This repository is a minimal runnable, Windows-first CLI project for the first phase of a local AI workbench:

• detect runtime environment through a single cached module
• scan installed software
• classify software with maintainable config rules
• open software by name
• close software gracefully by name

The implementation is intentionally conservative:

• Windows is the only supported runtime for the first phase
• no GUI automation
• no privilege elevation
• no install or uninstall actions
• no system settings changes
• no full-disk file scan
• no winget integration

.
|-- README.md
|-- docs/
|   |-- mysql_schema.sql
|   |-- postgresql_schema.sql
|   |-- software_cache.json
|   `-- software_cache_grouped.md
|-- pyproject.toml
|-- requirements-dev.txt
|-- sample_output/
|   |-- software_scan.example.json
|   `-- software_scan.json
|-- src/
|   `-- local_ai_workbench/
|       |-- __init__.py
|       |-- __main__.py
|       |-- catalog.py
|       |-- classifier.py
|       |-- cli.py
|       |-- config_loader.py
|       |-- env_detector.py
|       |-- logging_config.py
|       |-- models.py
|       |-- paths.py
|       |-- render.py
|       |-- resolver.py
|       |-- storage.py
|       |-- config/
|       |   |-- categories.json
|       |   `-- close_denylist.json
|       `-- platform/
|           |-- __init__.py
|           |-- base.py
|           |-- factory.py
|           `-- windows.py
`-- tests/
    |-- conftest.py
    |-- test_catalog.py
    |-- test_classifier.py
    |-- test_cli.py
    |-- test_env_detector.py
    |-- test_paths.py
    |-- test_render.py
    `-- test_storage.py

• env_detector.py Provides get_os(), get_python_version(), is_venv(), and get_shell() with cached detection.
• platform/windows.py Encapsulates Windows-specific logic for registry-based software discovery, optional Start Menu shortcut enrichment, opening software, and graceful close attempts.
• classifier.py Applies category rules from config/categories.json.
• storage.py Saves and loads scan results as structured JSON.
• resolver.py Resolves user input against cached software records and returns exact or ambiguous matches.
• catalog.py Orchestrates scan, list, open, and close.
• cli.py Exposes the project as a CLI.

1. Detect runtime environment once and reuse cached results everywhere.
2. Isolate all platform-specific behavior behind a platform adapter.
3. Scan installed software from Windows registry entries and enrich launch metadata when Start Menu shortcuts are available.
4. Classify software using JSON-configured rules.
5. Persist the scan result to a JSON cache so list, open, and close can reuse it.
6. Resolve software names conservatively:
   • exact matches first
   • fuzzy matches second
   • return candidates instead of executing when multiple matches exist
7. Only attempt graceful close, with denylist protection for risky targets.

Each software record contains at least:

• id
• name
• category
• install_source
• executable_path
• launch_command
• closable
• system_app

Extra metadata such as publisher, install_location, registry_key, and process_names is also stored when available.

python -m venv .venv
.venv\Scripts\Activate.ps1
pip install -e .[dev]

If you do not want editable install:

pip install -r requirements-dev.txt
pip install .

The CLI stores the default scan cache under:

• Repository: .\docs\software_cache.json

Generated cache and rendered output files under docs/ and sample_output/ are local working artifacts. They are ignored by Git by default. Keep the checked-in schema files in docs/ and the example file in sample_output/ under version control.

Show all supported commands:

local-ai-workbench --help
local-ai-workbench scan --help
local-ai-workbench list --help
local-ai-workbench open --help
local-ai-workbench close --help

• scan Scan installed software and write the cache JSON. Default output is .\docs\software_cache.json.
• list List cached software records. Supports --category, --query, --group-by category, and --format markdown.
• open <name> [<name> ...] Open one or more matched software entries. Supports --dry-run.
• close <name> [<name> ...] Attempt graceful close for one or more matched software entries. Supports --dry-run and --yes.

Examples:

local-ai-workbench scan
local-ai-workbench scan --output .\docs\software_cache.json
local-ai-workbench scan --output .\sample_output\software_scan.json
local-ai-workbench list
local-ai-workbench list --category database
local-ai-workbench list --query mongo
local-ai-workbench list --group-by category --query cursor
local-ai-workbench list --format markdown > .\docs\software_cache.md
local-ai-workbench list --input .\docs\software_cache.json --format markdown --group-by category > .\docs\software_cache_grouped.md
local-ai-workbench open "Visual Studio Code"
local-ai-workbench open Cursor Chrome
local-ai-workbench open "Code" --dry-run
local-ai-workbench close "Notepad" --yes
local-ai-workbench close Cursor Chrome --yes
local-ai-workbench close "Notepad" --dry-run

Direct module execution also works:

python -m local_ai_workbench --help
python -m local_ai_workbench scan

scripts/import_snapshot.py converts a snapshot JSON file into SQL that replaces the current contents of scan_snapshots and software_records in a single transaction.

PostgreSQL schema:

psql "$env:DATABASE_URL" -f .\docs\postgresql_schema.sql
python .\scripts\import_snapshot.py --dialect postgresql --input .\docs\software_cache.json | psql "$env:DATABASE_URL"

MySQL schema:

Get-Content -Raw .\docs\mysql_schema.sql | mysql -u root -p software_db
python .\scripts\import_snapshot.py --dialect mysql --input .\docs\software_cache.json | mysql -u root -p software_db

If mysql is not on your PATH, use the full executable path instead:

$mysql = 'C:\Program Files\MySQL\MySQL Server 8.0\bin\mysql.exe'
Get-Content -Raw .\docs\mysql_schema.sql | & $mysql -u root -p software_db
python .\scripts\import_snapshot.py --dialect mysql --input .\docs\software_cache.json | & $mysql -u root -p software_db

• The project does not request administrator privileges.
• close only attempts a graceful close for matched GUI processes.
• close refuses risky targets through config/close_denylist.json.
• Ambiguous matches are listed and not executed.
• All commands log their actions.

The test suite only validates pure logic and mocked orchestration. It does not perform real software scans or real process control.

pytest