@softspark/ai-toolkit 4.29.2 → 4.30.2

package/scripts/config_resolver.py

@@ -91,6 +91,7 @@ def resolve_extends(
     project_root: str | Path,
     *,
     refresh: bool = False,
+    persistent: bool = True,
 ) -> ResolutionResult:
     """Resolve an extends chain into an ordered list of base configs.
 
@@ -98,6 +99,9 @@ def resolve_extends(
         extends_value: The extends string from .softspark-toolkit.json.
         project_root: The project directory (for resolving relative paths).
         refresh: Force re-fetch ignoring cache.
+        persistent: Allow remote sources to populate the config cache. When
+            false, cached sources remain readable and cache misses resolve in
+            an isolated staging directory that is removed before return.
 
     Returns:
         ResolutionResult with ordered configs (deepest ancestor first).
@@ -106,7 +110,26 @@ def resolve_extends(
         ConfigResolverError: On resolution failure.
     """
     result = ResolutionResult()
-    _resolve_chain(extends_value, Path(project_root), set(), result, refresh=refresh)
+    if persistent:
+        _resolve_chain(
+            extends_value,
+            Path(project_root),
+            set(),
+            result,
+            refresh=refresh,
+            staging_root=None,
+        )
+        return result
+
+    with tempfile.TemporaryDirectory(prefix="ai-toolkit-config-preview-") as tmp:
+        _resolve_chain(
+            extends_value,
+            Path(project_root),
+            set(),
+            result,
+            refresh=refresh,
+            staging_root=Path(tmp),
+        )
     return result
 
 
@@ -148,6 +171,7 @@ def _resolve_chain(
     result: ResolutionResult,
     *,
     refresh: bool = False,
+    staging_root: Path | None,
 ) -> None:
     """Recursively resolve extends chain with cycle + depth detection."""
     # Cycle detection
@@ -169,7 +193,13 @@ def _resolve_chain(
     visited.add(canonical)
 
     # Resolve this source
-    base_config = _resolve_source(extends_value, project_root, result, refresh=refresh)
+    base_config = _resolve_source(
+        extends_value,
+        project_root,
+        result,
+        refresh=refresh,
+        staging_root=staging_root,
+    )
     _validate_resolved_base(base_config)
 
     # Recurse if this base also extends something
@@ -180,6 +210,7 @@ def _resolve_chain(
             visited,
             result,
             refresh=refresh,
+            staging_root=staging_root,
         )
 
     # Append after recursion (deepest ancestor first)
@@ -205,14 +236,25 @@ def _resolve_source(
     result: ResolutionResult,
     *,
     refresh: bool = False,
+    staging_root: Path | None,
 ) -> BaseConfig:
     """Resolve a single extends source."""
     if source.startswith("git+"):
-        return _resolve_git(source, result, refresh=refresh)
+        return _resolve_git(
+            source,
+            result,
+            refresh=refresh,
+            staging_root=staging_root,
+        )
     if source.startswith(".") or source.startswith("/") or source.startswith("~"):
         return _resolve_local(source, project_root)
     # Default: npm package
-    return _resolve_npm(source, result, refresh=refresh)
+    return _resolve_npm(
+        source,
+        result,
+        refresh=refresh,
+        staging_root=staging_root,
+    )
 
 
 # ---------------------------------------------------------------------------
@@ -224,6 +266,7 @@ def _resolve_npm(
     result: ResolutionResult,
     *,
     refresh: bool = False,
+    staging_root: Path | None,
 ) -> BaseConfig:
     """Resolve from npm registry via npm pack."""
     package_name, version_spec = _parse_npm_source(source)
@@ -270,8 +313,13 @@ def _resolve_npm(
         tarball = tarballs[0]
         version = _extract_version_from_tarball(tarball.name, package_name)
 
-        # Extract to cache
-        dest = cache_dir / version
+        dest = _remote_destination(
+            cache_dir / version,
+            staging_root,
+            "npm",
+            pack_source,
+            version,
+        )
         dest.mkdir(parents=True, exist_ok=True)
         _extract_tarball(tarball, dest)
 
@@ -366,6 +414,7 @@ def _resolve_git(
     result: ResolutionResult,
     *,
     refresh: bool = False,
+    staging_root: Path | None,
 ) -> BaseConfig:
     """Resolve from git URL (git+https://...)."""
     url = source.removeprefix("git+")
@@ -379,16 +428,19 @@ def _resolve_git(
     if not refresh and cache_dir.is_dir() and (cache_dir / CONFIG_FILENAME).is_file():
         return _load_cached_config(cache_dir, source)
 
-    # Clone (shallow)
-    cache_dir.mkdir(parents=True, exist_ok=True)
+    destination = _remote_destination(
+        cache_dir,
+        staging_root,
+        "git",
+        url,
+    )
+    destination.parent.mkdir(parents=True, exist_ok=True)
     try:
-        # Clean previous clone if refreshing
-        if cache_dir.is_dir():
-            shutil.rmtree(cache_dir)
-            cache_dir.mkdir(parents=True)
+        if destination.is_dir():
+            shutil.rmtree(destination)
 
         proc = subprocess.run(
-            ["git", "clone", "--depth", "1", url, str(cache_dir)],
+            ["git", "clone", "--depth", "1", url, str(destination)],
             capture_output=True,
             text=True,
             timeout=120,
@@ -404,7 +456,7 @@ def _resolve_git(
             f"git clone failed: {proc.stderr.strip()}"
         )
 
-    return _load_cached_config(cache_dir, source)
+    return _load_cached_config(destination, source)
 
 
 # ---------------------------------------------------------------------------
@@ -431,6 +483,20 @@ def _resolve_local(source: str, project_root: Path) -> BaseConfig:
 # Shared helpers
 # ---------------------------------------------------------------------------
 
+def _remote_destination(
+    persistent_path: Path,
+    staging_root: Path | None,
+    source_kind: str,
+    source: str,
+    version: str = "",
+) -> Path:
+    """Choose a persistent cache path or an isolated preview path."""
+    if staging_root is None:
+        return persistent_path
+    source_key = hashlib.sha256(source.encode()).hexdigest()[:16]
+    destination = staging_root / source_kind / source_key
+    return destination / version if version else destination
+
 def _load_cached_config(
     config_dir: Path,
     source: str,

package/scripts/doctor.py

@@ -7,16 +7,17 @@
 
 Checks:
   1. Environment prerequisites (node, bash, python3, bats) + check_deps
-  2. Global install integrity (symlinks, settings.json hooks)
-  3. Hook scripts (existence, executable)
-  4. Hook configuration (valid event names)
-  5. Generated artifacts (AGENTS.md, llms.txt staleness)
-  6. Planned assets
-  7. Benchmark freshness
-  8. Stale rules
-  9. URL hook sources
-  10. Language rules drift (project-local)
-  11. Plugin double-load (Claude app plugin vs global install)
+  2. Local AI runtime availability and versions (credential-blind)
+  3. Global install integrity (symlinks, settings.json hooks)
+  4. Hook scripts (existence, executable)
+  5. Hook configuration (valid event names)
+  6. Generated artifacts (AGENTS.md, llms.txt staleness)
+  7. Planned assets
+  8. Benchmark freshness
+  9. Stale rules
+  10. URL hook sources
+  11. Language rules drift (project-local)
+  12. Plugin double-load (Claude app plugin vs global install)
 
 Exit codes:
   0  all checks pass
@@ -24,6 +25,7 @@ Exit codes:
 """
 from __future__ import annotations
 
+from dataclasses import dataclass
 import json
 import os
 import re
@@ -100,6 +102,32 @@ PLANNED_ASSETS = [
     toolkit_dir / "app" / "skills" / "agent-creator" / "SKILL.md",
 ]
 
+AI_RUNTIME_BINARIES = (
+    ("dsh", "DSH"),
+    ("codex", "Codex"),
+    ("claude", "Claude Code"),
+    ("copilot", "GitHub Copilot"),
+)
+AI_RUNTIME_VERSION_TIMEOUT_SECONDS = 5
+_SEMVER_NUMERIC_IDENTIFIER = r"(?:0|[1-9][0-9]*)"
+_SEMVER_PRERELEASE_IDENTIFIER = (
+    rf"(?:{_SEMVER_NUMERIC_IDENTIFIER}|"
+    r"[0-9A-Za-z-]*[A-Za-z-][0-9A-Za-z-]*)"
+)
+_SEMVER_BUILD_IDENTIFIER = r"[0-9A-Za-z-]+"
+SEMVER_OUTPUT = re.compile(
+    r"(?<![0-9A-Za-z.+-])v?"
+    rf"(?P<version>{_SEMVER_NUMERIC_IDENTIFIER}\."
+    rf"{_SEMVER_NUMERIC_IDENTIFIER}\."
+    rf"{_SEMVER_NUMERIC_IDENTIFIER}"
+    rf"(?:-{_SEMVER_PRERELEASE_IDENTIFIER}"
+    rf"(?:\.{_SEMVER_PRERELEASE_IDENTIFIER})*)?"
+    rf"(?:\+{_SEMVER_BUILD_IDENTIFIER}"
+    rf"(?:\.{_SEMVER_BUILD_IDENTIFIER})*)?)"
+    r"(?![0-9A-Za-z.+-])"
+)
+VERSION_LIKE_OUTPUT = re.compile(r"(?<![0-9])[0-9]+\.[0-9]+\.[^\s,;()]+")
+
 
 # ---------------------------------------------------------------------------
 # Status helpers
@@ -134,20 +162,53 @@ class DiagResult:
 # Version extraction
 # ---------------------------------------------------------------------------
 
-def _get_version(binary: str) -> str:
-    """Get a version string from a binary."""
+@dataclass(frozen=True, slots=True)
+class VersionProbe:
+    """Result of a bounded, non-authenticating ``--version`` probe."""
+
+    version: str | None
+    error: str | None
+
+
+def _probe_version(executable: str) -> VersionProbe:
+    """Run the exact discovered executable and parse its SemVer output."""
     try:
         result = subprocess.run(
-            [binary, "--version"],
+            [executable, "--version"],
             capture_output=True,
             text=True,
-            timeout=5,
+            timeout=AI_RUNTIME_VERSION_TIMEOUT_SECONDS,
         )
+    except FileNotFoundError:
+        return VersionProbe(None, "executable disappeared before version check")
+    except subprocess.TimeoutExpired:
+        return VersionProbe(None, "version check timed out")
+    except UnicodeError:
+        return VersionProbe(None, "version output is not valid text")
+    except OSError as error:
+        detail = error.strerror or type(error).__name__
+        return VersionProbe(None, f"version check failed: {detail}")
+
+    if result.returncode != 0:
+        return VersionProbe(
+            None,
+            f"version command exited with status {result.returncode}",
+        )
+    try:
         output = result.stdout.strip() or result.stderr.strip()
-        m = re.search(r"(\d+\.\d+\.\d+)", output)
-        return m.group(1) if m else "unknown"
-    except (FileNotFoundError, subprocess.TimeoutExpired):
-        return ""
+    except UnicodeError:
+        return VersionProbe(None, "version output is not valid text")
+    match = SEMVER_OUTPUT.search(output)
+    if not match:
+        if VERSION_LIKE_OUTPUT.search(output):
+            return VersionProbe(None, "version output contained invalid SemVer")
+        return VersionProbe(None, "version output did not contain SemVer")
+    return VersionProbe(match.group("version"), None)
+
+
+def _get_version(executable: str) -> str:
+    """Compatibility helper for required environment binary reporting."""
+    return _probe_version(executable).version or ""
 
 
 # ---------------------------------------------------------------------------
@@ -165,8 +226,8 @@ def check_environment(dr: DiagResult, fix_mode: bool) -> None:
         ("python3", "python3", False),
         ("bats", "bats", False),
     ]:
-        if shutil.which(binary):
-            version = _get_version(binary)
+        if executable := shutil.which(binary):
+            version = _get_version(executable)
             ver_str = f" {version}" if version else ""
             dr.ok(f"{label}{ver_str}")
         else:
@@ -191,6 +252,22 @@ def check_environment(dr: DiagResult, fix_mode: bool) -> None:
     print()
 
 
+def check_ai_runtimes(dr: DiagResult) -> None:
+    """Report local AI runtime availability without inspecting login state."""
+    print("## AI Runtimes")
+    for binary, label in AI_RUNTIME_BINARIES:
+        executable = shutil.which(binary)
+        if not executable:
+            dr.skip(f"{label} ({binary}) not found")
+            continue
+        probe = _probe_version(executable)
+        if probe.version:
+            dr.ok(f"{label} ({binary}) {probe.version}")
+        else:
+            dr.warn(f"{label} ({binary}) detected but {probe.error}")
+    print()
+
+
 # ---------------------------------------------------------------------------
 # Check 2: Global Install
 # ---------------------------------------------------------------------------
@@ -839,6 +916,7 @@ def main() -> None:
     dr = DiagResult()
 
     check_environment(dr, fix_mode)
+    check_ai_runtimes(dr)
     check_global_install(dr, fix_mode)
     check_hook_scripts(dr, fix_mode)
     check_hook_configuration(dr)

package/scripts/ecosystem_tools.json

@@ -1,7 +1,7 @@
 {
   "schema_version": 1,
   "description": "Authoritative registry of tools ai-toolkit integrates with. Consumed by scripts/ecosystem_doctor.py to detect upstream doc/version drift.",
-  "last_updated": "2026-08-19",
+  "last_updated": "2026-09-01",
   "tools": [
     {
       "id": "claude-code",
@@ -130,6 +130,56 @@
       ],
       "version_probe": null
     },
+    {
+      "id": "dsh",
+      "display_name": "DeepSeek Harness",
+      "kind": "harness",
+      "status": "developer-preview",
+      "selection_policy": "explicit-only",
+      "reviewed_version": "0.1.1-rc.2",
+      "excluded_from": [
+        "editors-all",
+        "auto-detect",
+        "defaults"
+      ],
+      "urls": {
+        "docs": "https://deepseek-harness.github.io/deepseek-harness/",
+        "release_notes": "https://github.com/deepseek-ai/deepseek-harness/releases",
+        "reviewed_release": "https://github.com/deepseek-ai/deepseek-harness/releases/tag/dsh-v0.1.1-rc.2",
+        "reviewed_cli_docs": "https://github.com/deepseek-ai/deepseek-harness/blob/dsh-v0.1.1-rc.2/apps/cli/reference/README.md",
+        "reviewed_skill_docs": "https://github.com/deepseek-ai/deepseek-harness/blob/dsh-v0.1.1-rc.2/docs/subsystems/skills.md"
+      },
+      "config_paths": [
+        ".agents/skills/*/SKILL.md",
+        "$DSH_HOME/profiles/<profile>/package.json",
+        "$DSH_HOME/profiles/<profile>/node_modules/@softspark/dsh-*",
+        "$DSH_HOME/.agent-presets/softspark-orchestrator"
+      ],
+      "our_generators": [
+        "scripts/generate_codex_skills.py"
+      ],
+      "our_lifecycle": [
+        "scripts/install_steps/dsh.py"
+      ],
+      "lifecycle_commands": [
+        "ai-toolkit dsh install --profile web",
+        "ai-toolkit dsh update --profile web",
+        "ai-toolkit dsh doctor --profile web",
+        "ai-toolkit dsh uninstall --profile web"
+      ],
+      "status_note": "Community compatibility target maintained by SoftSpark. DeepSeek AI has not endorsed this integration. ai-toolkit reuses its native skill generator for project .agents/skills output and manages exact @softspark/dsh-codex@1.0.0 and @softspark/dsh-orchestrator@1.0.1 packages only through explicit profile lifecycle commands. Upstream has newer prereleases, but this entry remains pinned to the reviewed DSH 0.1.1-rc.2 contract pending qualification.",
+      "capability_markers": [
+        "Developer preview",
+        "profiles",
+        "dsh plugin",
+        "skills",
+        "Agent Preset"
+      ],
+      "version_probe": {
+        "kind": "command",
+        "command": "dsh --version"
+      }
+    },
     {
       "id": "cursor",
       "display_name": "Cursor",

package/scripts/generate_codex_skills.py

@@ -3,7 +3,7 @@
 # Copyright 2024-2026 Lukasz Krzemien (biuro@softspark.eu)
 # Source: https://github.com/softspark/ai-toolkit
 
-"""Mirror the ai-toolkit skill catalogue into Codex ``.agents/skills/``.
+"""Mirror the ai-toolkit skill catalogue into ``.agents/skills/``.
 
 OpenAI Codex CLI discovers Agent Skills from ``.agents/skills/`` in the
 repository tree, plus user/admin/system skill locations. Unlike the Augment
@@ -13,7 +13,8 @@ on disk, so this generator syncs every skill in ``app/skills/`` into
 
 The standalone generator keeps ``enable_codex_skills=False`` as a compatibility
 default. Selecting Codex in the main installer installs this catalog
-automatically; ``--codex-skills`` remains an explicit refresh option.
+automatically; ``--codex-skills`` remains an explicit refresh option. DSH
+reuses the same one-level managed surface without receiving other Codex config.
 
 Implementation:
   * Native Codex-compatible skills are symlinked to canonical ``app/skills``.
@@ -40,7 +41,7 @@ from pathlib import Path
 sys.path.insert(0, str(Path(__file__).resolve().parent))
 from codex_skill_adapter import (
     cleanup_codex_skills,
-    prepare_codex_skills_dir,
+    managed_skill_surface_transaction,
     sync_codex_skill,
     unmanaged_codex_skill_names,
 )
@@ -104,27 +105,28 @@ def generate(target_dir: Path, enable_codex_skills: bool = False) -> None:
     if not enable_codex_skills:
         return
 
-    codex_skills_dir = prepare_codex_skills_dir(target_dir)
-
     sources = _iter_source_skills()
-    user_names = unmanaged_codex_skill_names(codex_skills_dir, skills_dir)
-
     linked = 0
     adapted = 0
     skipped = 0
-    for skill in sources:
-        if skill.name in user_names:
-            skipped += 1
-            continue
-        mode = sync_codex_skill(skill, codex_skills_dir)
-        if mode == "linked":
-            linked += 1
-        elif mode == "adapted":
-            adapted += 1
-        else:
-            skipped += 1
-
-    cleanup_codex_skills(codex_skills_dir, skills_dir, user_names)
+    with managed_skill_surface_transaction(target_dir, skills_dir) as transaction:
+        codex_skills_dir = transaction.skills_dst
+        user_names = unmanaged_codex_skill_names(codex_skills_dir, skills_dir)
+
+        for skill in sources:
+            if skill.name in user_names:
+                skipped += 1
+                continue
+            mode = sync_codex_skill(skill, codex_skills_dir)
+            if mode == "linked":
+                linked += 1
+            elif mode == "adapted":
+                adapted += 1
+            else:
+                skipped += 1
+
+        cleanup_codex_skills(codex_skills_dir, skills_dir, user_names)
+        transaction.commit({"codex"})
 
     print(
         f"  Codex skill mirror: {_count_entries(codex_skills_dir)} skills "

package/scripts/install.py

@@ -76,7 +76,7 @@ from config_resolver import (
 )
 from config_merger import ConfigMergeError, merge_config_chain
 from config_validator import validate_project_config
-from config_lock import save_lock_file
+from config_lock import LOCK_FILENAME, save_lock_file
 
 
 # ---------------------------------------------------------------------------
@@ -317,7 +317,7 @@ VALID_LANGS = {"python", "typescript", "golang", "go", "rust", "java", "kotlin",
 
 def validate_args(cfg: dict) -> None:
     """Validate parsed arguments — exit non-zero on invalid values."""
-    from install_steps.ai_tools import ALL_EDITORS
+    from install_steps.ai_tools import LOCAL_ONLY_EDITORS, SELECTABLE_EDITORS
 
     errors: list[str] = []
 
@@ -339,8 +339,13 @@ def validate_args(cfg: dict) -> None:
     if cfg["editors"] and cfg["editors"] != "all":
         for e in cfg["editors"].split(","):
             e = e.strip()
-            if e and e not in ALL_EDITORS:
-                errors.append(f"Unknown editor: '{e}' (valid: {', '.join(ALL_EDITORS)}, all)")
+            if e and e not in SELECTABLE_EDITORS:
+                errors.append(
+                    f"Unknown editor: '{e}' "
+                    f"(valid: {', '.join(SELECTABLE_EDITORS)}, all)"
+                )
+            if e in LOCAL_ONLY_EDITORS and not cfg["local"]:
+                errors.append(f"Editor '{e}' is project-local and requires --local")
 
     # Validate --lang
     if cfg["lang"]:
@@ -536,6 +541,8 @@ def resolve_extends_config(
     project_dir: Path,
     config_path: str = "",
     refresh: bool = False,
+    *,
+    persist_lock: bool = True,
 ) -> dict | None:
     """Resolve .softspark-toolkit.json extends and return merged config.
 
@@ -574,7 +581,12 @@ def resolve_extends_config(
     print(f"  Resolving extends: {extends}...")
 
     try:
-        result = resolve_extends(extends, config_root, refresh=refresh)
+        result = resolve_extends(
+            extends,
+            config_root,
+            refresh=refresh,
+            persistent=persist_lock,
+        )
     except ConfigResolverError as e:
         print(f"  ✗ Resolution failed: {e}")
         sys.exit(1)
@@ -611,13 +623,15 @@ def resolve_extends_config(
         "overrides_applied": merge_result.overrides_applied,
     }
 
-    # Generate lock file
-    lock_path = save_lock_file(
-        config_root,
-        config_metas,
-        ai_toolkit_version=_get_toolkit_version(),
-    )
-    print(f"  Saved: {lock_path.name}")
+    if persist_lock:
+        lock_path = save_lock_file(
+            config_root,
+            config_metas,
+            ai_toolkit_version=_get_toolkit_version(),
+        )
+        print(f"  Saved: {lock_path.name}")
+    else:
+        print(f"  Would save: {LOCK_FILENAME} (dry-run)")
 
     return merge_result.merged
 
@@ -736,7 +750,10 @@ def main() -> None:
         config_path_arg: str = cfg["config"]
         refresh_base: bool = cfg["refresh_base"]
         merged_config = resolve_extends_config(
-            project_dir, config_path=config_path_arg, refresh=refresh_base,
+            project_dir,
+            config_path=config_path_arg,
+            refresh=refresh_base,
+            persist_lock=not dry_run,
         )
         if merged_config:
             cfg = _apply_merged_config(merged_config, cfg)