@ccoalm/ccl-skills 0.2.0 → 0.4.0

package/dist/assets/release.json

@@ -1,8 +1,8 @@
 {
   "schema": 1,
   "npmPackage": "@ccoalm/ccl-skills",
-  "version": "0.2.0",
-  "sourceCommit": "fc04fbd666653826eed184be0723b6f3c6889e67",
+  "version": "0.4.0",
+  "sourceCommit": "b6a56485f7e4764e36a2c2ac14693db25964f018",
   "sourceState": "clean",
   "files": [
     {
@@ -287,7 +287,7 @@
     },
     {
       "path": "marketplace/plugins/ccl-skills/skills/code-review/scripts/classify_envelope.py",
-      "sha256": "30401c9fb101a3d5b37de1af939c14ad5590e1bf3f23e71f58bb20d92b23601a",
+      "sha256": "72956ebdfc3c22281b86fb6ada6c2e88a6e21c3a2aa6a80b09767adb62fb18b0",
       "mode": 493
     },
     {
@@ -375,9 +375,14 @@
       "sha256": "b92a8b2ae91608081665eabcee482b7550415d66df8ad654f1d041add6b3de8f",
       "mode": 420
     },
+    {
+      "path": "marketplace/plugins/ccl-skills/skills/code-review/scripts/test_abort_leak_state_helpers.sh",
+      "sha256": "6696d671f0aa071537e35fe93f9f39453659bafeb17a5ab5441407b557a2bdb1",
+      "mode": 493
+    },
     {
       "path": "marketplace/plugins/ccl-skills/skills/code-review/scripts/test_classify_envelope.sh",
-      "sha256": "dd3167c61b1443cb8661a53efc29fde86ef383a646bc866dde83a3a927dc5f16",
+      "sha256": "6ced09a9338753975d12fe81d45b513c276cd38470ef1b2a16849561d88bf19f",
       "mode": 493
     },
     {
@@ -437,7 +442,7 @@
     },
     {
       "path": "marketplace/plugins/ccl-skills/skills/code-review/scripts/test_parse_review_json.sh",
-      "sha256": "2362221e654e0d5f9378cd1be1eca9bc0633b3c6b1ed4a7dc4e77f0df986254b",
+      "sha256": "62be1010b6f01dfef76c3e6e6b96a8ff5d400c4d9c68060b33b0982ff2b8c754",
       "mode": 493
     },
     {
@@ -452,12 +457,12 @@
     },
     {
       "path": "marketplace/plugins/ccl-skills/skills/code-review/scripts/test_review_gate_abort_leak.sh",
-      "sha256": "9434aa303e93754ef5a8dfdaf6453bab86f0c253eb787b80fecc00b5f7b3e984",
+      "sha256": "b4bd03c04e822eb8ed212e9624ce9ca8c93bdcd363885cfdcf2fd77e74dd21a8",
       "mode": 493
     },
     {
       "path": "marketplace/plugins/ccl-skills/skills/code-review/scripts/test_review_gate.sh",
-      "sha256": "6659beaca736d91c9498157766b3d90ce1cbdff828d12fb91b4fff17b9857166",
+      "sha256": "244a56a2dbc3b02d11024ec7c4a5d45d31f98938a438b0bfd4ba5be3ea3bf60b",
       "mode": 493
     },
     {
@@ -1912,7 +1917,7 @@
     },
     {
       "path": "marketplace/plugins/ccl-skills/skills/skill-extraction-workflow/references/eval-routing.md",
-      "sha256": "f42096bd6667a932b92c6cf0cd1c3e363e483145b08c09572089b1da88055a32",
+      "sha256": "73ce45ed4bb5ca29f9e9b5e286c5da8bbad9d39d48fb8405b43050990814554d",
       "mode": 420
     },
     {
@@ -1937,7 +1942,7 @@
     },
     {
       "path": "marketplace/plugins/ccl-skills/skills/skill-extraction-workflow/references/extraction-quickstart.md",
-      "sha256": "50c5edb90fbf923aa2851341bb39c69500e829e6e1cd0e403b2d1ffa0fbd7483",
+      "sha256": "4c3660c0bf33bf742e7d690c11661f7edef1eab0d63a100866e8001ad3adfddb",
       "mode": 420
     },
     {
@@ -1947,7 +1952,7 @@
     },
     {
       "path": "marketplace/plugins/ccl-skills/skills/skill-extraction-workflow/references/harness-patterns-and-eval.md",
-      "sha256": "280be0406cbbe42a4f8b0470c27eab666a99c4643be6b3165053d334fe088f29",
+      "sha256": "2c106cb1df85e13b4034866fafbd32c0f9dacf89be7f15ffe8cd7089a8c8d7ef",
       "mode": 420
     },
     {
@@ -1977,7 +1982,7 @@
     },
     {
       "path": "marketplace/plugins/ccl-skills/skills/skill-extraction-workflow/references/recurring-anti-patterns-checklist.md",
-      "sha256": "a463977152868bae7ca534e95a166ad23d027d9c9ec3f4efdc6886fbc6e60074",
+      "sha256": "38a2abe3391b245fef430d334f6aac91a62f75a6f32d2f2a76ad9f946fabb6ec",
       "mode": 420
     },
     {
@@ -2012,12 +2017,12 @@
     },
     {
       "path": "marketplace/plugins/ccl-skills/skills/skill-extraction-workflow/references/source-register.md",
-      "sha256": "b028098c3d5fdcdb49b6e26fde4a162f958fa236085532e8975e4e7ce2e7de14",
+      "sha256": "bfc26af574b990ce5a8e7dcfcd42b17eaf302e1ba0ec61b10f1db774e85c2a30",
       "mode": 420
     },
     {
       "path": "marketplace/plugins/ccl-skills/skills/skill-extraction-workflow/references/source-to-skill-extraction.md",
-      "sha256": "1c4c99821e26a36a3b82a6194dc82997ce509f50f03f963b7db5a5126e2c5e21",
+      "sha256": "63f3e920df63add61965cefbb5673f6ef2b30249473b548af81fb3a89520b8cb",
       "mode": 420
     },
     {
@@ -2047,7 +2052,7 @@
     },
     {
       "path": "marketplace/plugins/ccl-skills/skills/skill-extraction-workflow/scripts/check-ccl-skills.sh",
-      "sha256": "c377934dc7b4f005970bd81a7747e91f0c374aed0f76ee44253a8fbce1a3eb8d",
+      "sha256": "4addb9d800b78b8cc2eb1c8f4429959631bcf092ef00d28306b95b9cd5f209da",
       "mode": 493
     },
     {
@@ -2077,7 +2082,7 @@
     },
     {
       "path": "marketplace/plugins/ccl-skills/skills/skill-extraction-workflow/scripts/eval-health.rb",
-      "sha256": "35a9b8488e9c8fbe56859fb01634fa9faaa4a993cc6fef816af0ec310b8abc0a",
+      "sha256": "c44e09befe49a5dd9491772bd1bdffb2c881df478fe2705e94d6006543aabadc",
       "mode": 493
     },
     {
@@ -2102,7 +2107,7 @@
     },
     {
       "path": "marketplace/plugins/ccl-skills/skills/skill-extraction-workflow/scripts/impact-chain-gate.rb",
-      "sha256": "f15d8b1d1932589e981ad1c104e73bfb9e057f61e5ceae60c3a75004422b7ae9",
+      "sha256": "af64b8f307c75943c81553af22ddb3702cdc1e3ecd77d7a9a3052b680874eaed",
       "mode": 493
     },
     {
@@ -2132,7 +2137,7 @@
     },
     {
       "path": "marketplace/plugins/ccl-skills/skills/skill-extraction-workflow/scripts/test_check_ccl_impact_chain_refscripts.sh",
-      "sha256": "81be5e3078121140402f88e1e56995dea3d2c70320490eb329e3460eadc1a2b3",
+      "sha256": "04e4b75799c9e6e97402a6515f063dd1c59dc0b4d5f02cc9448142dc99459fea",
       "mode": 493
     },
     {
@@ -2147,7 +2152,7 @@
     },
     {
       "path": "marketplace/plugins/ccl-skills/skills/skill-extraction-workflow/scripts/test_check_ccl_regressions.sh",
-      "sha256": "c6ff1fe420383ec343281678a96ba9b7b2905c8946ea6cd145a7c38da0ff28f2",
+      "sha256": "afaa9197cd4e0bf0e0b8d6e3189f0e939561b8142ec1e76c9baf9dd968a3af90",
       "mode": 493
     },
     {
@@ -2217,22 +2222,32 @@
     },
     {
       "path": "marketplace/plugins/ccl-skills/skills/skill-extraction-workflow/scripts/test_impact_chain_gate_dateless_host.sh",
-      "sha256": "493443e08b635ac1acd47339fcd0fe966646374e4224baa68a99f46dba932ae1",
+      "sha256": "08e707048810264e6d74d5df4d9415601b14749204eed55f9f160ae5dc782a60",
       "mode": 493
     },
     {
       "path": "marketplace/plugins/ccl-skills/skills/skill-extraction-workflow/scripts/test_impact_chain_gate_verdict_differential.sh",
-      "sha256": "3c6d27086a7c0d97b636f09faef811ed7d1a53806dbcce21de69707cc6f3dc0a",
+      "sha256": "30d94cbf6d2255d1a9eb38eb558ef2d8c638b4d1a65d739b1c713f339b9b22ad",
       "mode": 493
     },
     {
       "path": "marketplace/plugins/ccl-skills/skills/skill-extraction-workflow/scripts/test_impact_chain_round_attribution.sh",
-      "sha256": "a8e9bc8a8d60dae6c037c8fa760d15b5a0633e575a9831b9ab11235f3ca12da3",
+      "sha256": "034179e057ff3dbba0ecf3077fad6836caf45536a68479742ace8bbd016ab283",
+      "mode": 493
+    },
+    {
+      "path": "marketplace/plugins/ccl-skills/skills/skill-extraction-workflow/scripts/test_impact_chain_self_adjudication.sh",
+      "sha256": "85dbe8967dabe779b99d0e9543b7a6cc24d525f26e6f55eadd6995e16679fb76",
       "mode": 493
     },
     {
       "path": "marketplace/plugins/ccl-skills/skills/skill-extraction-workflow/scripts/test_impact_chain_source_refuted.sh",
-      "sha256": "e52069f1ab54e431d62db309c752ded5d7d148e221900a201235ef879e8d3af5",
+      "sha256": "f2f24a5e16d90b11ab0878004612c59a56091bca26f3f4a030490c3dd64a8449",
+      "mode": 493
+    },
+    {
+      "path": "marketplace/plugins/ccl-skills/skills/skill-extraction-workflow/scripts/test_liveness_predicate_gate.sh",
+      "sha256": "59a64a65c1998a18506164f93100cb270319ee9c6eddd485d32d78520b064e6a",
       "mode": 493
     },
     {
@@ -2287,7 +2302,7 @@
     },
     {
       "path": "marketplace/plugins/ccl-skills/skills/skill-extraction-workflow/SKILL.md",
-      "sha256": "081a7d21813d00a462f2c77c53923edf60cd6f740138d6c028b84ea4675c1aeb",
+      "sha256": "bff6bbfcc86cf5a2c523331621e113c2032a84130237ce1a89b79b5faf0b97dc",
       "mode": 420
     },
     {
@@ -2719,7 +2734,7 @@
     },
     {
       "path": "cli.js",
-      "sha256": "de1aebd30b83f4e53e17cd79a14dfaa5642aebdcaa1f89b0b358c13d05e89bf0",
+      "sha256": "5b5ab7f39b7faa81ea209b3e479295da64f2a834969ee5ac8d76354a182c2822",
       "mode": 493
     },
     {
@@ -2812,6 +2827,26 @@
       "sha256": "2aeabe2364755dc91d7058bf3e3b8e2bb4086a0392da6b8f87a3892879334915",
       "mode": 420
     },
+    {
+      "path": "update-notice.d.ts",
+      "sha256": "2caf9b8512c1969c4ecdb31e90de0265ef435b70a9bcca07f649d5055d63c6ab",
+      "mode": 420
+    },
+    {
+      "path": "update-notice.js",
+      "sha256": "da5ceca856f4492afd38010918d4c33c5f8dfc04d490bbf84ff955a8e12f7245",
+      "mode": 420
+    },
+    {
+      "path": "version-check.d.ts",
+      "sha256": "43e818adf60173644896298637f47b01d5819b17eda46eaa32d0c7d64724d012",
+      "mode": 420
+    },
+    {
+      "path": "version-check.js",
+      "sha256": "bd6babcff7eb222ce39f8ed4d8945f55f4004f45d17600fee497ee64357099da",
+      "mode": 420
+    },
     {
       "path": "version.d.ts",
       "sha256": "edc6c24c912373b1ffc68f7b261f2e04d616b0486e9ab2401d1201f094c5a885",
@@ -2823,5 +2858,5 @@
       "mode": 420
     }
   ],
-  "snapshotHash": "bbf4fb8c41de63a4392f4947f8b662e0b83918d3cd63f0b96306ccadc32ad1d0"
+  "snapshotHash": "6bf3d196d1ce59b751b9082bbb62b0c93cda0ceeb7e3c16431576522a5d9158e"
 }

package/dist/cli.js

@@ -2,9 +2,11 @@
 import { readFileSync, realpathSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 import { Worker } from "node:worker_threads";
-import { spawnSync } from "node:child_process";
+import { spawn, spawnSync } from "node:child_process";
+import { paths } from "./paths.js";
+import { cachePath, emitNotice } from "./update-notice.js";
 const pkg = JSON.parse(readFileSync(fileURLToPath(new URL("../package.json", import.meta.url)), "utf8"));
-const HELP = `ccl-skills — npm snapshot installer for Claude Code, Codex, and OpenCode\n\nUsage:\n  ccl-skills install [--host claude|codex|opencode] [--json]\n  ccl-skills update [--host claude|codex|opencode] [--yes] [--allow-downgrade] [--json]\n  ccl-skills doctor [--host claude|codex|opencode] [--json]\n  ccl-skills uninstall [--host claude|codex|opencode] [--yes] [--json]\n\nWithout --host, every installed or package-owned host is selected.\nUpdate and uninstall are dry-run unless --yes is supplied.\nBy default update --yes upgrades the global npm package to @latest before refreshing assets.\nSet CCL_SKILLS_SKIP_SELF_UPDATE=1 for an assets-only refresh; --allow-downgrade always uses the invoked package without installing @latest first.`;
+const HELP = `ccl-skills — npm snapshot installer for Claude Code, Codex, and OpenCode\n\nUsage:\n  ccl-skills install [--host claude|codex|opencode] [--json]\n  ccl-skills update [--host claude|codex|opencode] [--yes] [--allow-downgrade] [--json]\n  ccl-skills doctor [--host claude|codex|opencode] [--json]\n  ccl-skills uninstall [--host claude|codex|opencode] [--yes] [--json]\n\nWithout --host, every installed or package-owned host is selected.\nUpdate and uninstall are dry-run unless --yes is supplied.\nBy default update --yes upgrades the global npm package to @latest before refreshing assets.\nSet CCL_SKILLS_SKIP_SELF_UPDATE=1 for an assets-only refresh; --allow-downgrade always uses the invoked package without installing @latest first.\n\nAn interactive run prints an update notice on stderr at most once a day.\nSet CCL_SKILLS_NO_UPDATE_NOTIFIER=1 (or NO_UPDATE_NOTIFIER) to silence it; it is\nalready silent under --json, in CI, and when output is not a terminal.`;
 export function parseArgs(args) {
     if (!args.length ||
         args.includes("--help") ||
@@ -164,10 +166,28 @@ function selfUpdate(options) {
         return { code: 5, status: "package-updated-assets-unknown", message: "npm package updated, but the fresh CLI returned an invalid result" };
     }
 }
+/** Secondary guidance chrome. It is handed a stderr writer only, runs after the
+ * command's own output, and schedules its registry check in a detached child,
+ * so it can neither reach stdout nor add latency to this invocation. */
+function notifyUpdate(json) {
+    emitNotice({
+        current: pkg.version,
+        now: Date.now(),
+        env: process.env,
+        stdoutTTY: !!process.stdout.isTTY,
+        stderrTTY: !!process.stderr.isTTY,
+        columns: process.stdout.columns,
+        json,
+    }, cachePath(paths().root), {
+        stderr: (text) => write(process.stderr, text),
+        spawnCheck: () => spawn(process.execPath, [fileURLToPath(new URL("./version-check.js", import.meta.url))], { detached: true, stdio: "ignore" }).unref(),
+    });
+}
 export async function main(args) {
     const parsed = parseArgs(args);
     if (parsed.direct) {
         write(parsed.direct.stream === "stdout" ? process.stdout : process.stderr, parsed.direct.text);
+        notifyUpdate(false);
         return parsed.direct.code;
     }
     const shouldSelfUpdate = parsed.command === "update" && parsed.options.yes && !parsed.options.allowDowngrade && process.env.CCL_SKILLS_SKIP_SELF_UPDATE !== "1";
@@ -184,6 +204,7 @@ export async function main(args) {
     write(process.stdout, parsed.json
         ? JSON.stringify(result)
         : `${result.status}: ${result.message}${result.plan ? `\n${result.plan.map((x) => `- ${x}`).join("\n")}` : ""}`);
+    notifyUpdate(!!parsed.json);
     return result.code;
 }
 export function isDirectEntrypoint(importMetaUrl, argv1) {

package/dist/update-notice.d.ts

@@ -0,0 +1,71 @@
+import { mkdirSync, renameSync, unlinkSync, writeFileSync, readFileSync } from "node:fs";
+export type Cache = {
+    latest?: string;
+    lastCheckedAt?: string;
+    notifiedVersion?: string;
+    notifiedAt?: string;
+};
+export type NoticeInput = {
+    current: string;
+    cache?: Cache;
+    now: number;
+    env: Record<string, string | undefined>;
+    stdoutTTY: boolean;
+    stderrTTY: boolean;
+    columns?: number;
+    json: boolean;
+};
+export type Verdict = {
+    show: false;
+    reason: string;
+} | {
+    show: true;
+    reason: "update-available";
+    latest: string;
+};
+export declare const TTL_MS: number;
+export declare const CACHE_FILE = "version-check.json";
+/** Numeric precedence. Returns 0 when either side is not a stable version, so
+ * an unparseable value can never be reported as newer. */
+export declare function compareVersions(a: string, b: string): number;
+export declare function pickLatest(packument: unknown): string | null;
+/** Fails open toward refreshing: an absent, malformed, or future timestamp all
+ * mean "check again", never "assume fresh". */
+export declare function needsRefresh(cache: Cache | undefined, now: number, ttl?: number): boolean;
+export declare function refreshAllowed(input: NoticeInput): boolean;
+export declare function shouldNotify(input: NoticeInput): Verdict;
+/** Plain text only: colour is an enhancement, never the state carrier, and
+ * every line fits the narrow-terminal floor this notice is gated on. */
+export declare function formatNotice(current: string, latest: string): string;
+export declare function cachePath(root: string): string;
+export type EmitDeps = {
+    stderr: (text: string) => void;
+    spawnCheck: () => void;
+};
+/** The only entry the CLI calls. It is handed a stderr writer and nothing that
+ * can reach stdout, so the notice structurally cannot pollute primary output.
+ * Returns the sanitized reason code; it never throws and never changes exit. */
+export declare function emitNotice(input: NoticeInput, file: string, deps: EmitDeps): string;
+export type RefreshOptions = {
+    file: string;
+    now?: number;
+    fetchImpl?: (url: string, init: unknown) => Promise<{
+        ok: boolean;
+        json: () => Promise<unknown>;
+    }>;
+    timeoutMs?: number;
+};
+/** Runs in a detached child, never on the caller's path. The check time is
+ * stamped even on failure so an offline machine retries once per TTL, not once
+ * per command; a failed check never erases a previously known version. */
+export declare function refresh(options: RefreshOptions): Promise<void>;
+export declare function readCache(path: string, read?: typeof readFileSync): Cache | undefined;
+export type WriteDeps = {
+    writeFileSync?: typeof writeFileSync;
+    renameSync?: typeof renameSync;
+    unlinkSync?: typeof unlinkSync;
+    mkdirSync?: typeof mkdirSync;
+};
+/** Temp file in the target directory, then rename: a reader sees the old cache
+ * or the whole new one, never a truncated one, and never an EXDEV failure. */
+export declare function writeCacheAtomic(path: string, cache: Cache, deps?: WriteDeps): void;

package/dist/update-notice.js

@@ -0,0 +1,173 @@
+// Update notice: a terminal side channel, never primary output.
+// Display is bound to eligibility, cache freshness, and cooldown; the network
+// check runs detached so no invocation pays for it. Every failure path is
+// swallowed — a version check must never change what the command itself does.
+import { dirname, join } from "node:path";
+import { mkdirSync, renameSync, unlinkSync, writeFileSync, readFileSync } from "node:fs";
+export const TTL_MS = 24 * 60 * 60 * 1000;
+export const CACHE_FILE = "version-check.json";
+const MIN_COLUMNS = 60;
+const OPT_OUT = ["CCL_SKILLS_NO_UPDATE_NOTIFIER", "NO_UPDATE_NOTIFIER"];
+const CI_VARS = [
+    "CI",
+    "CONTINUOUS_INTEGRATION",
+    "BUILD_NUMBER",
+    "GITHUB_ACTIONS",
+    "GITLAB_CI",
+    "BUILDKITE",
+    "CIRCLECI",
+    "TRAVIS",
+    "TEAMCITY_VERSION",
+    "JENKINS_URL",
+];
+// Releases accept only stable MAJOR.MINOR.PATCH, so anything else — prerelease,
+// build metadata, or a hostile string — is not a version we will ever suggest.
+const STABLE = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/;
+const set = (env, names) => names.some((name) => (env[name] ?? "") !== "");
+/** Numeric precedence. Returns 0 when either side is not a stable version, so
+ * an unparseable value can never be reported as newer. */
+export function compareVersions(a, b) {
+    if (!STABLE.test(a) || !STABLE.test(b))
+        return 0;
+    const left = a.split(".").map(Number), right = b.split(".").map(Number);
+    for (let i = 0; i < 3; i++)
+        if (left[i] !== right[i])
+            return left[i] - right[i];
+    return 0;
+}
+export function pickLatest(packument) {
+    const tags = packument?.["dist-tags"];
+    const latest = tags?.latest;
+    return typeof latest === "string" && STABLE.test(latest) ? latest : null;
+}
+/** Fails open toward refreshing: an absent, malformed, or future timestamp all
+ * mean "check again", never "assume fresh". */
+export function needsRefresh(cache, now, ttl = TTL_MS) {
+    const at = Date.parse(cache?.lastCheckedAt ?? "");
+    return Number.isNaN(at) || at > now || now - at >= ttl;
+}
+/** The display gates that do not depend on cache contents. Shared by the notice
+ * and the background check so `--json`, CI, and opt-out make no network call. */
+function displayAllowed(input) {
+    if (set(input.env, OPT_OUT))
+        return { ok: false, reason: "opt-out" };
+    if (set(input.env, CI_VARS) || !input.stdoutTTY || !input.stderrTTY)
+        return { ok: false, reason: "non-interactive" };
+    if (input.json)
+        return { ok: false, reason: "structured-output" };
+    // A pty with no window size reports 0: that is "width unknown", not "zero
+    // cells wide", so it must not be treated as a narrow terminal.
+    if (input.columns !== undefined && input.columns > 0 && input.columns < MIN_COLUMNS)
+        return { ok: false, reason: "narrow-terminal" };
+    return { ok: true, reason: "eligible" };
+}
+export function refreshAllowed(input) {
+    return displayAllowed(input).ok;
+}
+export function shouldNotify(input) {
+    const gate = displayAllowed(input);
+    if (!gate.ok)
+        return { show: false, reason: gate.reason };
+    const latest = input.cache?.latest;
+    if (!latest)
+        return { show: false, reason: "no-cache" };
+    if (compareVersions(latest, input.current) <= 0)
+        return { show: false, reason: "up-to-date" };
+    const notifiedAt = Date.parse(input.cache?.notifiedAt ?? "");
+    if (input.cache?.notifiedVersion === latest &&
+        !Number.isNaN(notifiedAt) &&
+        input.now - notifiedAt < TTL_MS)
+        return { show: false, reason: "cooldown" };
+    return { show: true, reason: "update-available", latest };
+}
+/** Plain text only: colour is an enhancement, never the state carrier, and
+ * every line fits the narrow-terminal floor this notice is gated on. */
+export function formatNotice(current, latest) {
+    return [
+        `Update available: ${current} -> ${latest}`,
+        "Run: ccl-skills update --yes",
+        "Silence: CCL_SKILLS_NO_UPDATE_NOTIFIER=1",
+    ].join("\n");
+}
+export function cachePath(root) {
+    return join(root, CACHE_FILE);
+}
+/** The only entry the CLI calls. It is handed a stderr writer and nothing that
+ * can reach stdout, so the notice structurally cannot pollute primary output.
+ * Returns the sanitized reason code; it never throws and never changes exit. */
+export function emitNotice(input, file, deps) {
+    try {
+        const cache = input.cache ?? readCache(file);
+        const resolved = { ...input, cache };
+        const verdict = shouldNotify(resolved);
+        if (verdict.show) {
+            deps.stderr(formatNotice(input.current, verdict.latest));
+            writeCacheAtomic(file, {
+                ...cache,
+                notifiedVersion: verdict.latest,
+                notifiedAt: new Date(input.now).toISOString(),
+            });
+        }
+        if (refreshAllowed(resolved) && needsRefresh(cache, input.now))
+            deps.spawnCheck();
+        return verdict.reason;
+    }
+    catch {
+        return "unavailable";
+    }
+}
+const REGISTRY = "https://registry.npmjs.org/@ccoalm%2fccl-skills";
+/** Runs in a detached child, never on the caller's path. The check time is
+ * stamped even on failure so an offline machine retries once per TTL, not once
+ * per command; a failed check never erases a previously known version. */
+export async function refresh(options) {
+    const now = options.now ?? Date.now(), previous = readCache(options.file) ?? {};
+    let latest = null;
+    try {
+        const response = await (options.fetchImpl ?? fetch)(REGISTRY, {
+            headers: { Accept: "application/vnd.npm.install-v1+json" },
+            signal: AbortSignal.timeout(options.timeoutMs ?? 5000),
+        });
+        if (response.ok)
+            latest = pickLatest(await response.json());
+    }
+    catch {
+        /* offline, throttled, or malformed: keep the previous value */
+    }
+    writeCacheAtomic(options.file, {
+        ...previous,
+        ...(latest ? { latest } : {}),
+        lastCheckedAt: new Date(now).toISOString(),
+    });
+}
+export function readCache(path, read = readFileSync) {
+    try {
+        const parsed = JSON.parse(read(path, "utf8"));
+        return parsed && typeof parsed === "object" && !Array.isArray(parsed)
+            ? parsed
+            : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Temp file in the target directory, then rename: a reader sees the old cache
+ * or the whole new one, never a truncated one, and never an EXDEV failure. */
+export function writeCacheAtomic(path, cache, deps = {}) {
+    const write = deps.writeFileSync ?? writeFileSync, rename = deps.renameSync ?? renameSync, unlink = deps.unlinkSync ?? unlinkSync, temp = join(dirname(path), `.${CACHE_FILE}.tmp-${process.pid}`);
+    try {
+        // Without this the state root is absent until a host install runs, the
+        // write fails every time, and the caller reschedules the check forever.
+        (deps.mkdirSync ?? mkdirSync)(dirname(path), { recursive: true });
+        write(temp, `${JSON.stringify(cache)}\n`, { encoding: "utf8", mode: 0o600 });
+        rename(temp, path);
+    }
+    catch {
+        try {
+            unlink(temp);
+        }
+        catch {
+            /* nothing to clean up */
+        }
+    }
+}

package/dist/version-check.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/version-check.js

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+// Detached entrypoint for the background version check. It is spawned with
+// stdio ignored and unref'd, so it cannot slow, block, or outlive-block the
+// command that scheduled it, and it exits 0 whatever the registry does.
+import { paths } from "./paths.js";
+import { cachePath, refresh } from "./update-notice.js";
+refresh({ file: cachePath(paths().root) }).then(() => process.exit(0), () => process.exit(0));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ccoalm/ccl-skills",
-	"version": "0.2.0",
+	"version": "0.4.0",
   "description": "Self-contained CCL Skills installer for Claude Code, Codex, and OpenCode",
 	"keywords": ["agent-skills", "claude-code", "codex", "opencode", "developer-tools"],
   "type": "module",