@ccoalm/ccl-skills 0.2.0 → 0.3.0

package/README.md

@@ -36,6 +36,18 @@ ccl-skills uninstall --yes
 
 After `ccl-skills uninstall --yes`, remove the CLI package itself with `npm uninstall --global @ccoalm/ccl-skills` if it is no longer needed.
 
+## Update notice
+
+Nothing here updates itself. An interactive run prints a one-line notice on **stderr** when a newer version exists, at most once a day per version:
+
+```
+Update available: 0.2.0 -> 0.3.0
+Run: ccl-skills update --yes
+Silence: CCL_SKILLS_NO_UPDATE_NOTIFIER=1
+```
+
+The registry check runs at most once every 24 hours in a detached background process, so no invocation waits for the network, and its result is shown by the next run. The notice and its check are both silent under `--json`, in CI, when stdout or stderr is not a terminal, in terminals narrower than 60 columns, and when `CCL_SKILLS_NO_UPDATE_NOTIFIER` or `NO_UPDATE_NOTIFIER` is set. State lives in `version-check.json` under the managed root; a failed check keeps the last known version and never blocks or fails the command.
+
 Claude and Codex use package-owned local marketplace snapshots. OpenCode exposes skills, its native plugin, and `ccl-skills/runtime` through shared host directories. The native adapter maps the shipped session, tool, prompt, subagent, and stop behaviors to OpenCode events and covers `edit`, `write`, and `apply_patch`. Installation refuses unknown collisions, and uninstall preserves shared files for manual cleanup instead of guessing ownership.
 
 Set `CCL_SKILLS_REPO` to a valid checkout to override only the OpenCode asset source. An invalid override fails before writing host files. Without the variable, installation is offline after npm has downloaded the package.

package/dist/assets/release.json

@@ -1,8 +1,8 @@
 {
   "schema": 1,
   "npmPackage": "@ccoalm/ccl-skills",
-  "version": "0.2.0",
-  "sourceCommit": "fc04fbd666653826eed184be0723b6f3c6889e67",
+  "version": "0.3.0",
+  "sourceCommit": "0e8a42aee6ffd691679245331af0ad346baf4fdc",
   "sourceState": "clean",
   "files": [
     {
@@ -2719,7 +2719,7 @@
     },
     {
       "path": "cli.js",
-      "sha256": "de1aebd30b83f4e53e17cd79a14dfaa5642aebdcaa1f89b0b358c13d05e89bf0",
+      "sha256": "5b5ab7f39b7faa81ea209b3e479295da64f2a834969ee5ac8d76354a182c2822",
       "mode": 493
     },
     {
@@ -2812,6 +2812,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 +2843,5 @@
       "mode": 420
     }
   ],
-  "snapshotHash": "bbf4fb8c41de63a4392f4947f8b662e0b83918d3cd63f0b96306ccadc32ad1d0"
+  "snapshotHash": "f339a0ca319bb93956aebf42d2f63143ae37de54484398b0a3f87af313064436"
 }

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.3.0",
   "description": "Self-contained CCL Skills installer for Claude Code, Codex, and OpenCode",
 	"keywords": ["agent-skills", "claude-code", "codex", "opencode", "developer-tools"],
   "type": "module",