@softspark/ai-toolkit 1.9.0 → 2.0.0

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/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"
 
 

package/scripts/update_projects.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python3
 """Update all registered projects in parallel.
 
-Reads ~/.ai-toolkit/projects.json and runs install.py --local in each
+Reads ~/.softspark/ai-toolkit/projects.json and runs install.py --local in each
 project directory concurrently using a thread pool.
 
 Stdlib-only — no external dependencies.

package/scripts/version_check.py

@@ -21,7 +21,10 @@ import sys
 import time
 from pathlib import Path
 
-CACHE_FILE = Path.home() / ".ai-toolkit" / "version-check.json"
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+from paths import VERSION_CHECK_FILE, STATE_FILE
+
+CACHE_FILE = VERSION_CHECK_FILE
 CACHE_TTL = 86400  # 24 hours
 PACKAGE_NAME = "@softspark/ai-toolkit"
 
@@ -34,7 +37,7 @@ def _get_installed_version() -> str:
     installed/updated, while package.json may be newer if the npm package
     was upgraded but `ai-toolkit update` was not run yet.
     """
-    state_file = Path.home() / ".ai-toolkit" / "state.json"
+    state_file = STATE_FILE
     if state_file.is_file():
         try:
             with open(state_file, encoding="utf-8") as f: