@ccoalm/ccl-skills 0.15.0 → 0.15.2

package/dist/codex-host.d.ts

@@ -11,12 +11,10 @@ export declare function checkHost(codexHome?: string): {
     ok: false;
     kind: string;
     message: string;
-    version?: undefined;
+    output?: undefined;
+    stdout?: undefined;
 } | {
     ok: true;
-    version: string;
-    kind?: undefined;
-    message?: undefined;
 };
 export declare function parsePluginList(text: string, marketplaceSource: string | null): {
     ok: boolean;

package/dist/codex-host.js

@@ -1,9 +1,10 @@
 import { spawnSync } from "node:child_process";
-import { existsSync } from "node:fs";
+import { existsSync, mkdtempSync, rmSync, statSync } from "node:fs";
+import { tmpdir } from "node:os";
 import { isAbsolute, join, resolve } from "node:path";
 import { LEGACY_REF, MARKET, REF } from "./paths.js";
-import { canonicalAlias } from "./fs-safe.js";
-import { compare, parseVersion } from "./version.js";
+import { assertSafeRoot, canonicalAlias } from "./fs-safe.js";
+import { probeHostCommand } from "./host-probe.js";
 function call(args, codexHome) {
     const env = {
         ...process.env,
@@ -16,28 +17,48 @@ function call(args, codexHome) {
     });
 }
 export function checkHost(codexHome) {
-    const p = call(["--version"], codexHome);
-    if (p.error || p.status !== 0)
-        return {
-            ok: false,
-            kind: "missing",
-            message: "Codex CLI is missing",
-        };
-    const version = parseVersion(`${p.stdout}\n${p.stderr}`);
-    if (!version || compare(version, "0.133.0") < 0)
-        return {
-            ok: false,
-            kind: "old",
-            message: "Codex >=0.133.0 is required",
-        };
-    return { ok: true, version };
+    const targetHome = codexHome || process.env.CODEX_HOME || join(process.env.HOME || "", ".codex");
+    try {
+        assertSafeRoot(targetHome, join(targetHome, "ccl-skills-npm"));
+        try {
+            if (!statSync(targetHome).isDirectory())
+                throw new Error(`Codex home is not a directory: ${targetHome}`);
+        }
+        catch (error) {
+            if (error.code !== "ENOENT")
+                throw error;
+        }
+    }
+    catch (error) {
+        return { ok: false, kind: "safety-refusal", message: String(error) };
+    }
+    // Codex refuses a nonexistent CODEX_HOME. Probe the binary against a private
+    // empty home without creating the user's target just to discover capability.
+    const temporaryHome = existsSync(targetHome) ? null : mkdtempSync(join(tmpdir(), "ccl-codex-probe-"));
+    try {
+        const env = { ...process.env, CODEX_HOME: temporaryHome || targetHome };
+        const marketplace = probeHostCommand("codex", ["plugin", "marketplace", "list"], env);
+        if (!marketplace.ok)
+            return marketplace;
+        const plugins = probeHostCommand("codex", ["plugin", "list"], env);
+        if (!plugins.ok)
+            return plugins;
+        const parsed = parseMarketplace(marketplace.stdout);
+        if (!parsed.ok || !parsePluginList(plugins.stdout, parsed.source).ok)
+            return { ok: false, kind: "state-unknown", message: "Codex public state could not be verified" };
+        return { ok: true };
+    }
+    finally {
+        if (temporaryHome)
+            rmSync(temporaryHome, { recursive: true, force: true });
+    }
 }
 export function parsePluginList(text, marketplaceSource) {
     const lines = text.split(/\r?\n/).filter((line) => line.trim());
     if (lines.length === 0 ||
         (lines.length === 1 && lines[0] === "No marketplace plugins found."))
         return { ok: true, plugin: false, legacy: false };
-    const header = /^PLUGIN\s+STATUS\s+VERSION\s+PATH\s*$/;
+    const header = /^PLUGIN\s+STATUS\s+VERSION\s+(?:PATH|SOURCE)\s*$/;
     const provenance = /^Marketplace `([^`]+)`$/;
     const sensitiveRefs = new Set();
     let plugin = false;

package/dist/host-probe.d.ts

@@ -0,0 +1,27 @@
+export declare function isHostCommandMissing(command: string, env?: NodeJS.ProcessEnv): boolean;
+export declare function probeHostVersion(command: string, env?: NodeJS.ProcessEnv): {
+    ok: false;
+    kind: string;
+    message: string;
+    output?: undefined;
+    stdout?: undefined;
+} | {
+    ok: true;
+    output: string;
+    stdout: string;
+    kind?: undefined;
+    message?: undefined;
+};
+export declare function probeHostCommand(command: string, args: string[], env?: NodeJS.ProcessEnv): {
+    ok: false;
+    kind: string;
+    message: string;
+    output?: undefined;
+    stdout?: undefined;
+} | {
+    ok: true;
+    output: string;
+    stdout: string;
+    kind?: undefined;
+    message?: undefined;
+};

package/dist/host-probe.js

@@ -0,0 +1,51 @@
+import { spawnSync } from "node:child_process";
+import { accessSync } from "node:fs";
+import { delimiter, resolve } from "node:path";
+// Host discovery must not hold up other hosts or wait for interactive input.
+const HOST_PROBE_TIMEOUT_MS = 10000;
+// Presence only: do not execute a candidate or inspect its configuration.
+export function isHostCommandMissing(command, env = process.env) {
+    const candidates = command.includes("/")
+        ? [command]
+        : (env.PATH ?? "/usr/bin:/bin").split(delimiter).map((dir) => resolve(dir, command));
+    let uncertain = false;
+    for (const candidate of candidates) {
+        try {
+            accessSync(candidate);
+            return false;
+        }
+        catch (error) {
+            const code = error.code;
+            if (code !== "ENOENT" && code !== "ENOTDIR")
+                uncertain = true;
+        }
+    }
+    return !uncertain;
+}
+export function probeHostVersion(command, env = process.env) {
+    return probeHostCommand(command, ["--version"], env);
+}
+export function probeHostCommand(command, args, env = process.env) {
+    const result = spawnSync(command, args, {
+        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} ${args.join(" ")} timed out after ${HOST_PROBE_TIMEOUT_MS}ms`
+                : kind === "missing"
+                    ? `${command} CLI is unavailable (ENOENT)`
+                    : `${command} ${args.join(" ")} failed (${errorCode || (result.signal ? `signal ${result.signal}` : result.error ? "spawn error" : `exit ${result.status}`)})`,
+        };
+    }
+    return { ok: true, output: `${result.stdout}\n${result.stderr}`, stdout: result.stdout };
+}

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/operations.js

@@ -200,13 +200,24 @@ function cleanupCandidate(path, files, context) {
     removeEmptyTree(path, files);
     return [];
 }
-function resumeJournal(context) {
+function resumeJournal(context, host) {
     const p = paths(context), j = journal(p.journal, p.root);
+    const hostFailure = host.ok ? undefined : { kind: host.kind, message: host.message };
     if (!j)
         return {
             code: 5,
             status: "partial-journal",
             message: "operation journal is malformed",
+            ...(hostFailure ? { details: { hostFailure } } : {}),
+        };
+    if (!host.ok)
+        return {
+            code: 5,
+            status: "partial-journal",
+            message: host.kind === "missing"
+                ? "operation journal retained; restore or reinstall the Codex CLI, then rerun this command"
+                : "operation journal retained; restore readable Codex public plugin state, then rerun this command",
+            details: { hostFailure },
         };
     if (j.step === "committed" || j.step === "journal-unlink-failed") {
         if (j.operation !== "install" && j.operation !== "update")
@@ -274,6 +285,12 @@ function resumeJournal(context) {
         }
     }
     if (j.trashPath && j.snapshot) {
+        if (j.operation === "uninstall" && !exactState(p.codexHome, null, false))
+            return {
+                code: 5,
+                status: "partial",
+                message: "uninstall resume requires absent public state",
+            };
         const trash = contained(p.root, j.trashPath), deleted = j.deletedFiles || [], errors = remainingErrors(trash, j.snapshot, deleted);
         if (errors.length)
             return {
@@ -423,13 +440,16 @@ function doctor(context) {
         return { code: 3, status: "safety-refusal", message: String(error) };
     }
     const host = checkHost(p.codexHome);
-    if (!host.ok)
-        return { code: 4, status: `host-${host.kind}`, message: host.message };
+    if (!host.ok && host.kind === "safety-refusal")
+        return { code: 3, status: host.kind, message: host.message };
+    // Diagnose pending journals first; unreadable public state cannot authorize cleanup.
     if (existsSync(p.journal)) {
-        const repair = resumeJournal(context);
+        const repair = resumeJournal(context, host);
         if (repair)
             return repair;
     }
+    if (!host.ok)
+        return { code: host.kind === "state-unknown" ? 3 : 4, status: `host-${host.kind}`, message: host.message };
     const unknownTrash = existsSync(p.root)
         ? readdirSync(p.root).filter((name) => name.startsWith(".trash-"))
         : [];
@@ -478,13 +498,16 @@ function installOrUpdate(command, options, context) {
         return { code: 3, status: "safety-refusal", message: String(error) };
     }
     const host = checkHost(p.codexHome);
-    if (!host.ok)
-        return { code: 4, status: `host-${host.kind}`, message: host.message };
+    if (!host.ok && host.kind === "safety-refusal")
+        return { code: 3, status: host.kind, message: host.message };
+    // Diagnose pending journals first; unreadable public state cannot authorize cleanup.
     if (existsSync(p.journal)) {
-        const repair = resumeJournal(context);
+        const repair = resumeJournal(context, host);
         if (repair)
             return repair;
     }
+    if (!host.ok)
+        return { code: host.kind === "state-unknown" ? 3 : 4, status: `host-${host.kind}`, message: host.message };
     const problem = conflict(command, context);
     if (problem)
         return problem;
@@ -787,7 +810,10 @@ function uninstall(options, context) {
         return { code: 3, status: "safety-refusal", message: String(error) };
     }
     if (existsSync(p.journal)) {
-        const repair = resumeJournal(context);
+        const host = checkHost(p.codexHome);
+        if (!host.ok && host.kind === "safety-refusal")
+            return { code: 3, status: host.kind, message: host.message };
+        const repair = resumeJournal(context, host);
         if (repair)
             return repair;
     }

package/dist/unified.d.ts

@@ -1,4 +1,4 @@
-import type { PathContext } from "./paths.js";
+import { type PathContext } from "./paths.js";
 import type { Host, Options, Result } from "./types.js";
 export declare function runHostSequence(hosts: Host[], invoke: (host: Host) => Result): Result;
 export declare function runUnified(command: string, options?: Options, codexContext?: PathContext): Result;

package/dist/unified.js

@@ -1,14 +1,11 @@
-import { spawnSync } from "node:child_process";
+import { isHostCommandMissing, probeHostVersion } from "./host-probe.js";
+import { checkHost } from "./codex-host.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;
-}
+import { paths } from "./paths.js";
 function owned(host) {
     const home = process.env.HOME;
     if (!home)
@@ -57,8 +54,20 @@ 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) => {
+        const probe = host !== "codex" ? probeHostVersion(host)
+            : isHostCommandMissing(host) ? { ok: false, kind: "missing", message: "codex CLI was not found on PATH" }
+                : checkHost(paths(codexContext).codexHome);
+        return { host, probe };
+    });
+    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" && !(host === "codex" && probe.kind !== "safety-refusal" && existsSync(paths(codexContext).journal)))
+            return { code: probe.kind === "state-unknown" || probe.kind === "safety-refusal" ? 3 : 4, status: probe.kind === "safety-refusal" ? probe.kind : `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.15.0",
+	"version": "0.15.2",
   "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",