@ccoalm/ccl-skills 0.14.0 → 0.15.1

package/dist/host-probe.js

@@ -0,0 +1,27 @@
+import { spawnSync } from "node:child_process";
+// Version discovery must not hold up other hosts or wait for interactive input.
+const HOST_PROBE_TIMEOUT_MS = 10000;
+export function probeHostVersion(command, env = process.env) {
+    const result = spawnSync(command, ["--version"], {
+        encoding: "utf8",
+        env,
+        stdio: ["ignore", "pipe", "pipe"],
+        timeout: HOST_PROBE_TIMEOUT_MS,
+        // spawnSync still waits if a child catches SIGTERM and does not exit.
+        killSignal: "SIGKILL",
+    });
+    if (result.error || result.status !== 0) {
+        const errorCode = result.error?.code;
+        const kind = errorCode === "ETIMEDOUT" ? "timeout" : errorCode === "ENOENT" ? "missing" : "probe-failed";
+        return {
+            ok: false,
+            kind,
+            message: kind === "timeout"
+                ? `${command} --version timed out after ${HOST_PROBE_TIMEOUT_MS}ms`
+                : kind === "missing"
+                    ? `${command} CLI is unavailable (ENOENT)`
+                    : `${command} --version failed (${errorCode || (result.signal ? `signal ${result.signal}` : result.error ? "spawn error" : `exit ${result.status}`)})`,
+        };
+    }
+    return { ok: true, output: `${result.stdout}\n${result.stderr}` };
+}

package/dist/opencode-adapter.js

@@ -6,6 +6,7 @@ import { fileURLToPath } from "node:url";
 import { atomicJson, sha256 } from "./fs-safe.js";
 import { readRelease } from "./manifest.js";
 import { compare } from "./version.js";
+import { probeHostVersion } from "./host-probe.js";
 const PACKAGE = "@ccoalm/ccl-skills";
 function paths(context) {
     const rawHome = context.home ?? (context.env ? context.env.HOME : process.env.HOME);
@@ -21,7 +22,7 @@ function assertExclusiveRoot(base, root, createBase = false) {
         throw new Error("managed root is not canonical");
     if (createBase)
         mkdirSync(base, { recursive: true });
-    for (const component of [base, root]) {
+    for (const component of [base, root, join(root, "snapshots")]) {
         if (!existsSync(component))
             continue;
         const stat = lstatSync(component);
@@ -124,10 +125,6 @@ function readManifest(path, root) {
     }).sort((a, b) => a.destination.localeCompare(b.destination));
     return { schema: 1, npmPackage: PACKAGE, installedAt: raw.installedAt, version: raw.version, sourceCommit: raw.sourceCommit, sourceKind: raw.sourceKind, snapshot, snapshotHash: raw.snapshotHash, entries };
 }
-function hostAvailable(context) {
-    const result = spawnSync("opencode", ["--version"], { encoding: "utf8", env: context.env || process.env });
-    return !result.error && result.status === 0;
-}
 function sharedPath(base, rel) {
     const path = resolve(base, safeRel(rel, "OpenCode destination"));
     if (!path.startsWith(`${resolve(base)}${sep}`))
@@ -190,17 +187,19 @@ function actualFiles(directory) {
 function preflight(base, next, old) {
     assertSafeSharedParents(base, next);
     const previous = new Map((old?.entries || []).map((entry) => [entry.destination, entry]));
+    const drift = [];
     if (old) {
+        assertSafeSharedParents(base, old.entries);
         for (const entry of old.entries) {
             const path = sharedPath(base, entry.destination);
             if (!existsSync(path) || (regular(path).mode & 0o777) !== entry.mode || sha256(path) !== entry.sha256)
-                throw new Error(`owned OpenCode file drifted: ${entry.destination}`);
+                drift.push(entry.destination);
         }
         const skillNames = new Set(old.entries.filter((entry) => entry.destination.startsWith("skills/")).map((entry) => entry.destination.split("/")[1]));
         for (const skill of skillNames) {
             const expected = old.entries.filter((entry) => entry.destination.startsWith(`skills/${skill}/`)).map((entry) => entry.destination.slice(`skills/${skill}/`.length)).sort();
             if (JSON.stringify(actualFiles(join(base, "skills", skill))) !== JSON.stringify(expected))
-                throw new Error(`owned OpenCode skill directory drifted: ${skill}`);
+                drift.push(`skills/${skill}`);
         }
     }
     const nextSkills = new Set(next.filter((entry) => entry.destination.startsWith("skills/")).map((entry) => entry.destination.split("/")[1]));
@@ -211,6 +210,7 @@ function preflight(base, next, old) {
     for (const entry of next)
         if (!previous.has(entry.destination) && existsSync(sharedPath(base, entry.destination)))
             throw new Error(`OpenCode path collision: ${entry.destination}`);
+    return drift;
 }
 function prepareSnapshot(p, candidate) {
     const snapshotRel = join("snapshots", candidate.snapshotHash, "source"), snapshot = join(p.root, snapshotRel);
@@ -305,8 +305,9 @@ function writeShared(p, snapshot, entries, old, isInterrupted, copyShared = (fro
 function doctor(context) {
     const p = paths(context);
     assertExclusiveRoot(p.base, p.root);
-    if (!hostAvailable(context))
-        return { code: 4, status: "host-missing", message: "OpenCode CLI is not installed" };
+    const host = probeHostVersion("opencode", context.env || process.env);
+    if (!host.ok)
+        return { code: 4, status: `host-${host.kind}`, message: host.message };
     const legacy = existsSync(join(p.base, "ccl-skills/install-manifest.json")), manifest = readManifest(p.manifest, p.root);
     if (legacy && manifest)
         return { code: 3, status: "double-install", message: "legacy checkout and npm OpenCode installs are both present; keep exactly one" };
@@ -315,20 +316,22 @@ function doctor(context) {
             return { code: 3, status: legacy ? "legacy-install" : "unowned-registration", message: "OpenCode ccl-skills files exist without an npm ownership receipt" };
         return { code: 3, status: "absent", message: "ccl-skills is not installed for OpenCode" };
     }
-    const drift = [];
-    for (const entry of manifest.entries) {
-        const path = sharedPath(p.base, entry.destination);
-        if (!existsSync(path) || sha256(path) !== entry.sha256)
-            drift.push(entry.destination);
+    let drift = [], reason;
+    try {
+        drift = preflight(p.base, manifest.entries, manifest);
+    }
+    catch (error) {
+        reason = String(error);
     }
-    if (drift.length)
-        return { code: 3, status: "shared-drift", message: "OpenCode shared files changed after npm install; they will never be auto-deleted", details: { drift } };
+    if (drift.length || reason)
+        return { code: 3, status: "shared-drift", message: "OpenCode shared files changed after npm install; they will never be auto-deleted", details: { drift, ...(reason ? { reason } : {}) } };
     return { code: 0, status: "healthy", message: `OpenCode uses @ccoalm/ccl-skills ${manifest.version}` };
 }
 function installOrUpdate(commandName, options, context) {
     const p = paths(context);
-    if (!hostAvailable(context))
-        return { code: 4, status: "host-missing", message: "OpenCode CLI is not installed" };
+    const host = probeHostVersion("opencode", context.env || process.env);
+    if (!host.ok)
+        return { code: 4, status: `host-${host.kind}`, message: host.message };
     let candidate;
     try {
         candidate = source(context);
@@ -350,7 +353,9 @@ function installOrUpdate(commandName, options, context) {
             return { code: 3, status: "downgrade-refused", message: "newer OpenCode assets are installed" };
     }
     try {
-        preflight(p.base, candidate.entries, old);
+        const drift = preflight(p.base, candidate.entries, old);
+        if (drift.length)
+            throw new Error(`owned OpenCode paths drifted: ${drift.join(", ")}`);
     }
     catch (error) {
         return { code: 3, status: "collision", message: String(error) };

package/dist/unified.js

@@ -1,14 +1,9 @@
-import { spawnSync } from "node:child_process";
+import { probeHostVersion } from "./host-probe.js";
 import { existsSync } from "node:fs";
 import { join, resolve } from "node:path";
 import { runClaude } from "./claude-adapter.js";
 import { run as runCodex } from "./operations.js";
 import { runOpenCode } from "./opencode-adapter.js";
-function available(host) {
-    const command = host === "opencode" ? "opencode" : host;
-    const result = spawnSync(command, ["--version"], { encoding: "utf8" });
-    return !result.error && result.status === 0;
-}
 function owned(host) {
     const home = process.env.HOME;
     if (!home)
@@ -57,8 +52,15 @@ export function runUnified(command, options = {}, codexContext = {}) {
     if (options.host)
         return dispatch(options.host, command, options, codexContext);
     const includeOwned = command === "doctor" || command === "uninstall";
-    const hosts = ["claude", "codex", "opencode"].filter((host) => command === "update" ? available(host) && owned(host) : available(host) || (includeOwned && owned(host)));
+    const candidates = ["claude", "codex", "opencode"].filter((host) => command !== "update" || owned(host));
+    const probes = candidates.map((host) => ({ host, probe: probeHostVersion(host) }));
+    const hosts = probes.filter(({ host, probe }) => probe.ok || probe.kind !== "missing" || (includeOwned && owned(host))).map(({ host }) => host);
     if (!hosts.length)
-        return { code: 4, status: "host-missing", message: "none of Claude Code, Codex, or OpenCode is installed" };
-    return runHostSequence(hosts, (host) => dispatch(host, command, { ...options, host }, codexContext));
+        return { code: 4, status: "host-missing", message: "no Claude Code, Codex, or OpenCode CLI is available" };
+    return runHostSequence(hosts, (host) => {
+        const probe = probes.find((entry) => entry.host === host).probe;
+        if (!probe.ok && probe.kind !== "missing")
+            return { code: 4, status: `host-${probe.kind}`, message: probe.message };
+        return dispatch(host, command, { ...options, host }, codexContext);
+    });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ccoalm/ccl-skills",
-	"version": "0.14.0",
+	"version": "0.15.1",
   "description": "Reusable workflows that help coding agents plan, build, test, review, and release software — for Claude Code, Codex, and OpenCode",
 	"keywords": ["skills", "agent-skills", "claude", "claude-code", "codex", "opencode", "agent", "ai", "ai-agents", "cli", "anthropic", "developer-tools"],
   "type": "module",