@softspark/ai-toolkit 1.8.0 → 2.0.0

package/scripts/install_steps/project_registry.py

@@ -0,0 +1,142 @@
+"""Project registry — tracks which directories have ai-toolkit installed locally.
+
+Stores registry in ~/.softspark/ai-toolkit/projects.json.
+Used by `ai-toolkit update` to propagate updates to all registered projects,
+and by `ai-toolkit projects` to list/manage them.
+
+Stdlib-only — no external dependencies.
+"""
+from __future__ import annotations
+
+import json
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
+from paths import PROJECTS_FILE
+
+
+def _registry_path() -> Path:
+    """Return the canonical path to projects.json."""
+    return PROJECTS_FILE
+
+
+def _now_iso() -> str:
+    return datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+
+# ---------------------------------------------------------------------------
+# Load / Save
+# ---------------------------------------------------------------------------
+
+def load_registry() -> list[dict[str, Any]]:
+    """Load project registry. Returns empty list if missing/corrupt."""
+    path = _registry_path()
+    if not path.is_file():
+        return []
+    try:
+        with open(path, encoding="utf-8") as f:
+            data = json.load(f)
+        if isinstance(data, dict):
+            projects = data.get("projects", [])
+            return projects if isinstance(projects, list) else []
+        return []
+    except (json.JSONDecodeError, OSError):
+        return []
+
+
+def save_registry(projects: list[dict[str, Any]]) -> None:
+    """Save project registry."""
+    path = _registry_path()
+    path.parent.mkdir(parents=True, exist_ok=True)
+    with open(path, "w", encoding="utf-8") as f:
+        json.dump({"projects": projects}, f, indent=2)
+        f.write("\n")
+
+
+# ---------------------------------------------------------------------------
+# CRUD
+# ---------------------------------------------------------------------------
+
+def register_project(
+    project_path: str | Path,
+    profile: str = "",
+    extends: str = "",
+) -> bool:
+    """Register a project directory. Returns True if newly added, False if updated.
+
+    Idempotent — updates existing entry if path already registered.
+    """
+    project_path = str(Path(project_path).resolve())
+    projects = load_registry()
+    now = _now_iso()
+
+    for p in projects:
+        if p.get("path") == project_path:
+            # Update existing
+            p["last_updated"] = now
+            if profile:
+                p["profile"] = profile
+            if extends:
+                p["extends"] = extends
+            elif "extends" in p and not extends:
+                # Clear extends if project no longer uses it
+                pass
+            save_registry(projects)
+            return False
+
+    # New registration
+    projects.append({
+        "path": project_path,
+        "registered_at": now,
+        "last_updated": now,
+        "profile": profile or "standard",
+        "extends": extends or "",
+    })
+    save_registry(projects)
+    return True
+
+
+def unregister_project(project_path: str | Path) -> bool:
+    """Unregister a project. Returns True if found and removed."""
+    project_path = str(Path(project_path).resolve())
+    projects = load_registry()
+    original_len = len(projects)
+    projects = [p for p in projects if p.get("path") != project_path]
+    if len(projects) < original_len:
+        save_registry(projects)
+        return True
+    return False
+
+
+def list_projects() -> list[dict[str, Any]]:
+    """List all registered projects with existence status."""
+    projects = load_registry()
+    for p in projects:
+        p["exists"] = Path(p["path"]).is_dir()
+    return projects
+
+
+def prune_stale() -> list[str]:
+    """Remove projects whose directories no longer exist. Returns pruned paths."""
+    projects = load_registry()
+    pruned: list[str] = []
+    kept: list[dict[str, Any]] = []
+
+    for p in projects:
+        if Path(p["path"]).is_dir():
+            kept.append(p)
+        else:
+            pruned.append(p["path"])
+
+    if pruned:
+        save_registry(kept)
+
+    return pruned
+
+
+def get_active_projects() -> list[dict[str, Any]]:
+    """Get registered projects that still exist on disk."""
+    return [p for p in load_registry() if Path(p["path"]).is_dir()]

package/scripts/migrate.py

@@ -0,0 +1,199 @@
+#!/usr/bin/env python3
+"""Migrate ai-toolkit data from ~/.ai-toolkit to ~/.softspark/ai-toolkit.
+
+Called automatically by install.py and ai-toolkit.js on first run.
+Can also be invoked directly: python3 scripts/migrate.py [--dry-run]
+
+Migration steps:
+  1. Detect legacy ~/.ai-toolkit directory
+  2. Create ~/.softspark/ai-toolkit/
+  3. Move all contents (state, hooks, rules, sessions, etc.)
+  4. Leave ~/.ai-toolkit/.migrated marker with pointer to new location
+  5. Migrate per-project .ai-toolkit.json → .softspark-toolkit.json (via registry)
+
+Exit codes:
+  0  Migration succeeded or nothing to migrate
+  1  Migration failed
+"""
+from __future__ import annotations
+
+import json
+import os
+import shutil
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+from paths import (
+    LEGACY_DATA_DIR,
+    LEGACY_PROJECT_CONFIG,
+    LEGACY_PROJECT_LOCK,
+    PROJECT_CONFIG_FILENAME,
+    PROJECT_LOCK_FILENAME,
+    SOFTSPARK_DIR,
+    TOOLKIT_DATA_DIR,
+)
+
+
+MIGRATED_MARKER = LEGACY_DATA_DIR / ".migrated"
+
+
+def needs_migration() -> bool:
+    """Check if legacy directory exists and hasn't been migrated yet."""
+    if not LEGACY_DATA_DIR.is_dir():
+        return False
+    if MIGRATED_MARKER.is_file():
+        return False
+    # Don't migrate if AI_TOOLKIT_HOME is set (custom setup)
+    if os.environ.get("AI_TOOLKIT_HOME"):
+        return False
+    return True
+
+
+def migrate_home_directory(dry_run: bool = False) -> bool:
+    """Migrate ~/.ai-toolkit → ~/.softspark/ai-toolkit.
+
+    Returns True if migration was performed, False if skipped.
+    """
+    if not needs_migration():
+        return False
+
+    print()
+    print("## Migrating to new directory structure")
+    print(f"   {LEGACY_DATA_DIR} → {TOOLKIT_DATA_DIR}")
+    print()
+
+    if dry_run:
+        print("   (dry-run: no changes made)")
+        return False
+
+    # Create parent ~/.softspark/
+    SOFTSPARK_DIR.mkdir(parents=True, exist_ok=True)
+
+    if TOOLKIT_DATA_DIR.exists():
+        # New dir already exists (partial migration?) — merge carefully
+        _merge_directories(LEGACY_DATA_DIR, TOOLKIT_DATA_DIR)
+    else:
+        # Clean move
+        shutil.move(str(LEGACY_DATA_DIR), str(TOOLKIT_DATA_DIR))
+        # Recreate legacy dir for marker
+        LEGACY_DATA_DIR.mkdir(parents=True, exist_ok=True)
+
+    # Write migration marker
+    _write_marker()
+
+    print(f"   Migrated: {TOOLKIT_DATA_DIR}")
+    return True
+
+
+def _merge_directories(src: Path, dst: Path) -> None:
+    """Merge src into dst, preferring src files (newer)."""
+    for item in src.iterdir():
+        if item.name == ".migrated":
+            continue
+        dest_item = dst / item.name
+        if item.is_dir():
+            if dest_item.is_dir():
+                _merge_directories(item, dest_item)
+            else:
+                shutil.move(str(item), str(dest_item))
+        else:
+            # Overwrite with source (legacy has the latest data)
+            shutil.move(str(item), str(dest_item))
+
+
+def _write_marker() -> None:
+    """Write .migrated marker pointing to new location."""
+    LEGACY_DATA_DIR.mkdir(parents=True, exist_ok=True)
+    now = datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+    marker_data = {
+        "migrated_to": str(TOOLKIT_DATA_DIR),
+        "migrated_at": now,
+        "message": "ai-toolkit data has moved to ~/.softspark/ai-toolkit/. "
+                   "This directory is kept as a marker. Safe to delete.",
+    }
+    with open(MIGRATED_MARKER, "w", encoding="utf-8") as f:
+        json.dump(marker_data, f, indent=2)
+        f.write("\n")
+
+
+def migrate_project_configs(dry_run: bool = False) -> int:
+    """Rename .ai-toolkit.json → .softspark-toolkit.json in registered projects.
+
+    Returns the number of projects migrated.
+    """
+    registry_file = TOOLKIT_DATA_DIR / "projects.json"
+    if not registry_file.is_file():
+        return 0
+
+    try:
+        with open(registry_file, encoding="utf-8") as f:
+            data = json.load(f)
+        projects = data.get("projects", [])
+    except (json.JSONDecodeError, OSError):
+        return 0
+
+    count = 0
+    for project in projects:
+        project_path = Path(project.get("path", ""))
+        if not project_path.is_dir():
+            continue
+
+        # Migrate .ai-toolkit.json → .softspark-toolkit.json
+        old_config = project_path / LEGACY_PROJECT_CONFIG
+        new_config = project_path / PROJECT_CONFIG_FILENAME
+        if old_config.is_file() and not new_config.is_file():
+            if dry_run:
+                print(f"   Would rename: {old_config} → {new_config}")
+            else:
+                old_config.rename(new_config)
+                print(f"   Renamed: {old_config.name} → {new_config.name} in {project_path}")
+            count += 1
+
+        # Migrate .ai-toolkit.lock.json → .softspark-toolkit.lock.json
+        old_lock = project_path / LEGACY_PROJECT_LOCK
+        new_lock = project_path / PROJECT_LOCK_FILENAME
+        if old_lock.is_file() and not new_lock.is_file():
+            if dry_run:
+                print(f"   Would rename: {old_lock} → {new_lock}")
+            else:
+                old_lock.rename(new_lock)
+
+    return count
+
+
+def run_full_migration(dry_run: bool = False) -> bool:
+    """Run complete migration: home directory + project configs.
+
+    Returns True if any migration was performed.
+    """
+    migrated = migrate_home_directory(dry_run=dry_run)
+
+    if migrated and not dry_run:
+        count = migrate_project_configs(dry_run=dry_run)
+        if count > 0:
+            print(f"   Migrated {count} project config(s)")
+
+    return migrated
+
+
+def main() -> None:
+    dry_run = "--dry-run" in sys.argv
+
+    if not needs_migration():
+        print("Nothing to migrate (no legacy ~/.ai-toolkit found or already migrated).")
+        sys.exit(0)
+
+    success = run_full_migration(dry_run=dry_run)
+
+    if success:
+        print()
+        print("Migration complete. The old ~/.ai-toolkit/ directory contains only a")
+        print("migration marker and can be safely deleted.")
+    elif not dry_run:
+        print("Migration skipped.")
+
+
+if __name__ == "__main__":
+    main()

package/scripts/paths.py

@@ -0,0 +1,50 @@
+"""Centralized path constants for ai-toolkit.
+
+All scripts MUST import paths from here — never hardcode ~/.ai-toolkit or
+~/.softspark/ai-toolkit directly.
+
+Supports override via AI_TOOLKIT_HOME env var for testing and custom setups.
+"""
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+# ---------------------------------------------------------------------------
+# Canonical paths
+# ---------------------------------------------------------------------------
+
+SOFTSPARK_DIR = Path(os.environ.get("SOFTSPARK_HOME", Path.home() / ".softspark"))
+
+TOOLKIT_DATA_DIR = Path(
+    os.environ.get("AI_TOOLKIT_HOME", SOFTSPARK_DIR / "ai-toolkit")
+)
+
+# Legacy path (pre-v2.0) — used only by migration detection
+LEGACY_DATA_DIR = Path.home() / ".ai-toolkit"
+
+# Sub-directories under TOOLKIT_DATA_DIR
+HOOKS_DIR = TOOLKIT_DATA_DIR / "hooks"
+RULES_DIR = TOOLKIT_DATA_DIR / "rules"
+SESSIONS_DIR = TOOLKIT_DATA_DIR / "sessions"
+COMPACTIONS_DIR = TOOLKIT_DATA_DIR / "compactions"
+CONFIG_CACHE_DIR = TOOLKIT_DATA_DIR / "config-cache"
+COMPILED_DIR = TOOLKIT_DATA_DIR / "compiled"
+
+# Files under TOOLKIT_DATA_DIR
+STATE_FILE = TOOLKIT_DATA_DIR / "state.json"
+PROJECTS_FILE = TOOLKIT_DATA_DIR / "projects.json"
+STATS_FILE = TOOLKIT_DATA_DIR / "stats.json"
+GOVERNANCE_LOG = TOOLKIT_DATA_DIR / "governance.log"
+VERSION_CHECK_FILE = TOOLKIT_DATA_DIR / "version-check.json"
+
+# Per-project config filenames
+PROJECT_CONFIG_FILENAME = ".softspark-toolkit.json"
+PROJECT_LOCK_FILENAME = ".softspark-toolkit.lock.json"
+
+# Legacy per-project config filenames (for migration)
+LEGACY_PROJECT_CONFIG = ".ai-toolkit.json"
+LEGACY_PROJECT_LOCK = ".ai-toolkit.lock.json"
+
+# Base config filename (published in npm packages — unchanged)
+BASE_CONFIG_FILENAME = "ai-toolkit.config.json"

package/scripts/plugin.py

@@ -35,10 +35,12 @@ from _common import toolkit_dir, app_dir
 from plugin_schema import resolve_hook_event, validate_manifest, validate_references
 
 
+from paths import TOOLKIT_DATA_DIR, HOOKS_DIR as _HOOKS_DIR
+
 PLUGINS_DIR = app_dir / "plugins"
 CLAUDE_DIR = Path.home() / ".claude"
-HOOKS_DIR = Path.home() / ".ai-toolkit" / "hooks"
-PLUGINS_STATE_FILE = Path.home() / ".ai-toolkit" / "plugins.json"
+HOOKS_DIR = _HOOKS_DIR
+PLUGINS_STATE_FILE = TOOLKIT_DATA_DIR / "plugins.json"
 
 
 # ---------------------------------------------------------------------------
@@ -156,7 +158,7 @@ def _copy_scripts(name: str, pack_dir: Path, installed_items: list[str]) -> None
     plugin_scripts_dir = pack_dir / "scripts"
     if not plugin_scripts_dir.is_dir():
         return
-    scripts_dest = Path.home() / ".ai-toolkit" / "plugin-scripts" / name
+    scripts_dest = TOOLKIT_DATA_DIR / "plugin-scripts" / name
     scripts_dest.mkdir(parents=True, exist_ok=True)
     for script_file in sorted(plugin_scripts_dir.iterdir()):
         if script_file.name.startswith("__"):
@@ -282,7 +284,7 @@ def remove_pack(name: str) -> bool:
 
     print(f"  Removing: {name}")
 
-    # 1. Remove plugin hooks from ~/.ai-toolkit/hooks/
+    # 1. Remove plugin hooks from ~/.softspark/ai-toolkit/hooks/
     removed = 0
     for hook in HOOKS_DIR.glob(f"plugin-{name}-*.sh"):
         hook.unlink()
@@ -290,7 +292,7 @@ def remove_pack(name: str) -> bool:
         removed += 1
 
     # 2. Remove plugin scripts
-    scripts_dir = Path.home() / ".ai-toolkit" / "plugin-scripts" / name
+    scripts_dir = TOOLKIT_DATA_DIR / "plugin-scripts" / name
     if scripts_dir.is_dir():
         shutil.rmtree(scripts_dir)
         print(f"    Removed scripts: {scripts_dir}")
@@ -358,7 +360,7 @@ def update_pack(name: str) -> bool:
 # Clean
 # ---------------------------------------------------------------------------
 
-MEMORY_DB = Path.home() / ".ai-toolkit" / "memory.db"
+MEMORY_DB = TOOLKIT_DATA_DIR / "memory.db"
 
 # Map plugin names to their clean logic
 CLEANABLE_PLUGINS = {"memory-pack"}

package/scripts/projects_cli.py

@@ -0,0 +1,110 @@
+#!/usr/bin/env python3
+"""CLI for managing the ai-toolkit project registry.
+
+Usage:
+    ai-toolkit projects                — List all registered projects
+    ai-toolkit projects --prune        — Remove stale (deleted) projects
+    ai-toolkit projects remove <path>  — Unregister a specific project
+
+Stdlib-only — no external dependencies.
+"""
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+from install_steps.project_registry import (
+    list_projects,
+    prune_stale,
+    unregister_project,
+)
+
+
+def main() -> None:
+    args = sys.argv[1:]
+
+    if not args or args == []:
+        cmd_list()
+    elif args[0] == "--prune":
+        cmd_prune()
+    elif args[0] == "remove" and len(args) >= 2:
+        cmd_remove(args[1])
+    elif args[0] in ("--help", "-h", "help"):
+        cmd_help()
+    else:
+        print(f"Unknown: {' '.join(args)}", file=sys.stderr)
+        cmd_help()
+        sys.exit(1)
+
+
+def cmd_list() -> None:
+    """List all registered projects."""
+    projects = list_projects()
+
+    if not projects:
+        print("  No registered projects.")
+        print("  Run 'ai-toolkit install --local' in a project to register it.")
+        return
+
+    print(f"  Registered projects ({len(projects)}):")
+    print()
+
+    for p in projects:
+        path_short = p["path"].replace(str(Path.home()), "~")
+        status = "✓" if p["exists"] else "✗ MISSING"
+        profile = p.get("profile", "")
+        extends = p.get("extends", "")
+        updated = p.get("last_updated", "")
+
+        print(f"  {status}  {path_short}")
+        details = []
+        if profile:
+            details.append(f"profile: {profile}")
+        if extends:
+            details.append(f"extends: {extends}")
+        if updated:
+            details.append(f"updated: {updated}")
+        if details:
+            print(f"        {' | '.join(details)}")
+
+    stale = [p for p in projects if not p["exists"]]
+    if stale:
+        print()
+        print(f"  {len(stale)} stale project(s). Run 'ai-toolkit projects --prune' to clean up.")
+
+
+def cmd_prune() -> None:
+    """Remove stale projects."""
+    pruned = prune_stale()
+    if pruned:
+        for p in pruned:
+            path_short = p.replace(str(Path.home()), "~")
+            print(f"  Pruned: {path_short}")
+        print(f"  Removed {len(pruned)} stale project(s).")
+    else:
+        print("  No stale projects found.")
+
+
+def cmd_remove(project_path: str) -> None:
+    """Unregister a specific project."""
+    resolved = Path(project_path).resolve()
+    if unregister_project(resolved):
+        path_short = str(resolved).replace(str(Path.home()), "~")
+        print(f"  Removed: {path_short}")
+    else:
+        print(f"  Not found in registry: {project_path}")
+        sys.exit(1)
+
+
+def cmd_help() -> None:
+    print("Usage: ai-toolkit projects [command]")
+    print()
+    print("Commands:")
+    print("  (none)          List all registered projects")
+    print("  --prune         Remove projects whose directories no longer exist")
+    print("  remove <path>   Unregister a specific project")
+
+
+if __name__ == "__main__":
+    main()

package/scripts/remove_rule.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python3
 """remove-rule -- Unregister a rule (opposite of add-rule).
 
-Removes the rule file from ~/.ai-toolkit/rules/ (so it is no longer
+Removes the rule file from ~/.softspark/ai-toolkit/rules/ (so it is no longer
 re-applied on future 'ai-toolkit install' runs) AND strips its injected
 block from the target CLAUDE.md.
 
@@ -29,11 +29,12 @@ def main() -> None:
 
     rule_name = sys.argv[1]
     target_dir = Path(sys.argv[2]) if len(sys.argv) > 2 else Path.home()
-    rules_dir = Path.home() / ".ai-toolkit" / "rules"
+    from paths import RULES_DIR
+    rules_dir = RULES_DIR
 
     removed = 0
 
-    # 1. Unregister from ~/.ai-toolkit/rules/
+    # 1. Unregister from ~/.softspark/ai-toolkit/rules/
     rule_file = rules_dir / f"{rule_name}.md"
     if rule_file.is_file():
         rule_file.unlink()
@@ -51,7 +52,7 @@ def main() -> None:
     if removed == 0:
         print()
         print("Nothing to unregister. To list registered rules:")
-        print("  ls ~/.ai-toolkit/rules/")
+        print(f"  ls {rules_dir}/")
 
 
 if __name__ == "__main__":

package/scripts/stats.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python3
 """ai-toolkit stats -- Show skill usage statistics.
 
-Reads ~/.ai-toolkit/stats.json (populated by track-usage.sh hook)
+Reads ~/.softspark/ai-toolkit/stats.json (populated by track-usage.sh hook)
 and displays a sorted table of skill invocations.
 
 Options:
@@ -15,8 +15,9 @@ import sys
 from pathlib import Path
 
 sys.path.insert(0, str(Path(__file__).resolve().parent))
+from paths import STATS_FILE as _STATS_FILE
 
-STATS_FILE = Path.home() / ".ai-toolkit" / "stats.json"
+STATS_FILE = _STATS_FILE
 
 
 def main() -> None:

package/scripts/sync.py

@@ -21,9 +21,10 @@ from pathlib import Path
 
 sys.path.insert(0, str(Path(__file__).resolve().parent))
 from _common import toolkit_dir
+from paths import TOOLKIT_DATA_DIR, RULES_DIR as _RULES_DIR
 
-CONFIG_DIR = Path.home() / ".ai-toolkit"
-RULES_DIR = CONFIG_DIR / "rules"
+CONFIG_DIR = TOOLKIT_DATA_DIR
+RULES_DIR = _RULES_DIR
 GIST_ID_FILE = CONFIG_DIR / ".gist-id"