@catalyst-cloud/cli 0.16.30 → 0.16.31

package/dist/update-sdk.js

@@ -0,0 +1,262 @@
+// update-sdk.ts — a project's Catalyst SDK against the approved release (CTC-6708). The SDK is a
+// dependency in the customer's own project, pinned by their lockfile, so a release check only
+// reads it: the declared range, the lockfile's resolution and the installed package are read
+// separately (a manifest range is never reported as the installed version), and the owner is given
+// the one command that moves the project to the approved versions. Reading writes nothing.
+//
+// The project's files change only through `applySdkUpdate`: when its owner runs
+// `catalyst update sdk --project <path>`, or has turned automatic SDK updates on for that project.
+// It runs the project's own package manager by argv (never a shell, never a full upgrade) with
+// exact versions in the dependency group each package already sits in, holds a per-project lock,
+// keeps the package files' bytes, puts them back if the install fails, and reads the result back
+// before calling it updated.
+//
+// Only train members the project already declares are named. Each uses its own approved version:
+// the SDK and its replica modules may sit on different patches of one train.
+import { spawnSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { closeSync, existsSync, mkdirSync, openSync, readFileSync, rmSync, statSync, unlinkSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { configDirFor } from "./config.js";
+import { compareVersions, exactVersion } from "./approved-release.js";
+import { isRecord } from "./runner-update.js";
+export const SDK_PACKAGES = {
+    "@catalyst-cloud/sdk": "sdk",
+    "@catalyst-cloud/sdk-replica-node": "sdk-replica-node",
+    "@catalyst-cloud/sdk-replica-browser": "sdk-replica-browser",
+};
+const LOCKFILES = {
+    npm: ["package-lock.json", "npm-shrinkwrap.json"],
+    pnpm: ["pnpm-lock.yaml"],
+    bun: ["bun.lock", "bun.lockb"],
+    yarn: ["yarn.lock"],
+};
+const GROUPS = ["dependencies", "devDependencies", "optionalDependencies"];
+function readJson(path) {
+    try {
+        return JSON.parse(readFileSync(path, "utf8"));
+    }
+    catch {
+        return undefined;
+    }
+}
+/** The manager the project declares, else the single one whose lockfile is present. Two lockfiles
+ *  and no declaration is ambiguous: the report says so instead of picking the first one found. */
+export function detectPackageManager(dir, manifest) {
+    const present = Object.keys(LOCKFILES).filter((m) => LOCKFILES[m].some((f) => existsSync(join(dir, f))));
+    if (typeof manifest.packageManager === "string") {
+        const name = manifest.packageManager.split("@")[0];
+        if (name === "npm" || name === "pnpm" || name === "bun" || name === "yarn") {
+            if (present.length > 0 && !present.includes(name))
+                return { manager: null, reason: "lockfile_mismatch" };
+            return { manager: name, reason: null };
+        }
+        return { manager: null, reason: "package_manager_unsupported" };
+    }
+    if (present.length === 1)
+        return { manager: present[0] ?? null, reason: null };
+    if (present.length > 1)
+        return { manager: null, reason: "package_manager_ambiguous" };
+    return { manager: "npm", reason: null };
+}
+function npmLocked(dir, name) {
+    for (const file of LOCKFILES.npm) {
+        const lock = readJson(join(dir, file));
+        if (!isRecord(lock) || !isRecord(lock.packages))
+            continue;
+        const entry = lock.packages[`node_modules/${name}`];
+        if (isRecord(entry))
+            return exactVersion(entry.version);
+    }
+    return null;
+}
+function installedVersion(dir, name) {
+    const manifest = readJson(join(dir, "node_modules", ...name.split("/"), "package.json"));
+    return isRecord(manifest) ? exactVersion(manifest.version) : null;
+}
+const quote = (value) => (/^[A-Za-z0-9_./@:=-]+$/.test(value) ? value : `'${value.replace(/'/g, "'\\''")}'`);
+/** What runs is what node_modules holds; else what the lockfile resolves; else an exact declaration. */
+const currentVersion = (p) => p.installed ?? p.locked ?? exactVersion(p.declared);
+/** A package already past its approved version: an update keeps it where it is, never moves it down. */
+const aheadOfApproved = (p) => {
+    const current = currentVersion(p);
+    return current !== null && p.approved !== null && compareVersions(current, p.approved) > 0;
+};
+/** The exact-version add invocations for the declared packages, one per dependency group, so each
+ *  package stays in the group it is already in. Every spec is a known package at an exact version.
+ *  A package already newer than its approved version is left out. */
+export function sdkUpdateArgv(manager, packages) {
+    const byGroup = new Map();
+    for (const p of packages)
+        if (p.approved !== null && !aheadOfApproved(p))
+            byGroup.set(p.group, [...(byGroup.get(p.group) ?? []), `${p.name}@${p.approved}`]);
+    return [...byGroup].map(([group, specs]) => {
+        const flags = {
+            npm: ["install", "--save-exact", ...(group === "devDependencies" ? ["--save-dev"] : group === "optionalDependencies" ? ["--save-optional"] : [])],
+            pnpm: ["add", "--save-exact", ...(group === "devDependencies" ? ["--save-dev"] : group === "optionalDependencies" ? ["--save-optional"] : [])],
+            bun: ["add", "--exact", ...(group === "devDependencies" ? ["--dev"] : group === "optionalDependencies" ? ["--optional"] : [])],
+            yarn: ["add", "--exact", ...(group === "devDependencies" ? ["--dev"] : group === "optionalDependencies" ? ["--optional"] : [])],
+        };
+        return [manager, ...flags[manager], ...specs];
+    });
+}
+/** The same move as one command a person can paste. */
+export function sdkUpdateCommand(dir, manager, packages) {
+    const argv = sdkUpdateArgv(manager, packages);
+    if (argv.length === 0)
+        return null;
+    return `cd ${quote(dir)} && ${argv.map((a) => a.map(quote).join(" ")).join(" && ")}`;
+}
+/** What `catalyst update sdk` tells the owner to run: this CLI's own explicit, one-project update. */
+export function catalystSdkCommand(dir) {
+    return `catalyst update sdk --project ${quote(dir)}`;
+}
+/** Read one project's SDK packages against `release` (null when no approved record is usable). */
+export function inspectSdkProject(dir, release) {
+    const base = { path: dir, packageManager: null, packages: [], command: null, packageManagerCommand: null };
+    const manifest = readJson(join(dir, "package.json"));
+    if (!isRecord(manifest))
+        return { ...base, status: "unknown", reason: "package_json_unreadable" };
+    const packages = [];
+    for (const [name, member] of Object.entries(SDK_PACKAGES)) {
+        for (const group of GROUPS) {
+            const deps = manifest[group];
+            if (!isRecord(deps) || typeof deps[name] !== "string")
+                continue;
+            packages.push({
+                name,
+                group,
+                declared: deps[name],
+                locked: null,
+                installed: installedVersion(dir, name),
+                approved: release?.members[member] ?? null,
+            });
+            break;
+        }
+    }
+    if (packages.length === 0)
+        return { ...base, status: "no_sdk", reason: "no_sdk" };
+    const detected = detectPackageManager(dir, manifest);
+    if (detected.manager === "npm")
+        for (const p of packages)
+            p.locked = npmLocked(dir, p.name);
+    const project = { ...base, packageManager: detected.manager, packages };
+    if (release === null)
+        return { ...project, status: "approval_unavailable", reason: "approval_unavailable" };
+    if (detected.manager === null)
+        return { ...project, status: "unknown", reason: detected.reason ?? "package_manager_ambiguous" };
+    const pairs = [];
+    for (const p of packages) {
+        if (p.approved === null)
+            return { ...project, status: "approval_unavailable", reason: "approval_unavailable" };
+        const current = currentVersion(p);
+        if (current === null)
+            return { ...project, status: "unknown", reason: "installed_version_unknown" };
+        pairs.push({ current, approved: p.approved });
+    }
+    if (pairs.some((v) => compareVersions(v.current, v.approved) < 0))
+        return {
+            ...project,
+            status: "update_available",
+            reason: "behind_approved",
+            command: catalystSdkCommand(dir),
+            packageManagerCommand: sdkUpdateCommand(dir, detected.manager, packages),
+        };
+    if (pairs.some((v) => compareVersions(v.current, v.approved) > 0))
+        return { ...project, status: "installed_newer", reason: "installed_newer" };
+    return { ...project, status: "current", reason: "current" };
+}
+export const spawnPackageManager = (argv, cwd) => {
+    const [cmd, ...args] = argv;
+    if (cmd === undefined)
+        return { status: 1, stderr: "no command" };
+    const run = spawnSync(cmd, args, { cwd, stdio: ["ignore", "ignore", "pipe"], encoding: "utf8", timeout: 10 * 60_000 });
+    return { status: run.error ? 1 : run.status, stderr: run.error ? run.error.message : (run.stderr ?? "") };
+};
+/** The package files a manager writes: the manifest and every lockfile name it may create. */
+const PACKAGE_FILES = ["package.json", ...Object.values(LOCKFILES).flat()];
+/** Longer than the package manager's own timeout, so a live run's lock is never taken over. */
+const SDK_LOCK_STALE_MS = 15 * 60_000;
+function takeProjectLock(home, dir) {
+    const locks = join(configDirFor(home), "sdk-update-locks");
+    mkdirSync(locks, { recursive: true, mode: 0o700 });
+    const path = join(locks, `${createHash("sha256").update(dir).digest("hex").slice(0, 32)}.lock`);
+    for (let attempt = 0; attempt < 2; attempt++) {
+        try {
+            closeSync(openSync(path, "wx", 0o600));
+            return path;
+        }
+        catch {
+            // A run killed mid-install leaves its lock behind; past the stale age it is taken over.
+            try {
+                if (Date.now() - statSync(path).mtimeMs <= SDK_LOCK_STALE_MS)
+                    return null;
+                unlinkSync(path);
+            }
+            catch {
+                // gone already: try again
+            }
+        }
+    }
+    return null;
+}
+/** Move one project's declared SDK packages to their approved versions with its own manager. */
+export function applySdkUpdate(home, dir, release, exec = spawnPackageManager) {
+    const project = inspectSdkProject(dir, release);
+    if (project.status === "current")
+        return { outcome: "current", detail: "current", moved: [], project };
+    if (project.status !== "update_available" || project.packageManager === null)
+        return { outcome: "refused", detail: project.reason, moved: [], project };
+    const manager = project.packageManager;
+    const lock = takeProjectLock(home, dir);
+    if (lock === null)
+        return { outcome: "refused", detail: "update_running", moved: [], project };
+    try {
+        // Each package file's bytes before the run, or null for one that did not exist yet.
+        const kept = new Map(PACKAGE_FILES.map((f) => [f, existsSync(join(dir, f)) ? readFileSync(join(dir, f)) : null]));
+        const failed = (detail) => {
+            // Put back what this run changed: earlier bytes for a file it rewrote, removal for one it created.
+            for (const [file, bytes] of kept) {
+                const path = join(dir, file);
+                const now = existsSync(path) ? readFileSync(path) : null;
+                if (bytes === null) {
+                    if (now !== null)
+                        rmSync(path, { force: true });
+                }
+                else if (now === null || !now.equals(bytes))
+                    writeFileSync(path, bytes);
+            }
+            return { outcome: "failed", detail, moved: [], project: inspectSdkProject(dir, release) };
+        };
+        for (const argv of sdkUpdateArgv(manager, project.packages)) {
+            const run = exec(argv, dir);
+            if (run.status !== 0)
+                return failed("package_manager_failed");
+        }
+        const after = inspectSdkProject(dir, release);
+        const moved = [];
+        for (const p of after.packages) {
+            const before = project.packages.find((q) => q.name === p.name);
+            const now = p.installed ?? p.locked;
+            if (before !== undefined && aheadOfApproved(before)) {
+                // Left out of the install: it must still be where it was.
+                const stays = currentVersion(p);
+                if (stays === null || compareVersions(stays, currentVersion(before) ?? stays) !== 0)
+                    return failed("verify_failed");
+                continue;
+            }
+            if (now === null || p.approved === null || compareVersions(now, p.approved) !== 0)
+                return failed("verify_failed");
+            moved.push({ name: p.name, from: before?.installed ?? before?.locked ?? before?.declared ?? "unknown", to: now });
+        }
+        return { outcome: "updated", detail: manager, moved, project: after };
+    }
+    finally {
+        try {
+            unlinkSync(lock);
+        }
+        catch {
+            // released already
+        }
+    }
+}

package/dist/update-skills.js

@@ -0,0 +1,64 @@
+// update-skills.ts — the Cloud skills pack moves to its approved version (CTC-6708). The pack
+// ships inside the CLI package of the same version, so a release check installs that exact CLI
+// package into its own directory (update-cli.ts's stageCliRuntime, which checks it and selects
+// nothing), checks that its bundled skills carry the approved version's stamp, and refreshes the
+// copies of those skills this install already made. That works while the CLI itself is held: the
+// pack comes from the staged package, never from the older CLI's own bundle.
+//
+// It changes only what installSkills already treats as its own: a skill folder stamped by this
+// package. A person's own skill of the same name, a symlinked entry (a plugin or the installer's
+// link) and any skill not installed yet are left as they are. Success is read back from the stamps
+// on disk.
+import { existsSync, lstatSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import { installedBundleVersion, installSkills } from "./skills.js";
+import { stageCliRuntime, stagedSkillsDir } from "./update-cli.js";
+const skillNames = (dir) => readdirSync(dir, { withFileTypes: true })
+    .filter((e) => e.isDirectory() && existsSync(join(dir, e.name, "SKILL.md")))
+    .map((e) => e.name);
+/** Stamped Cloud skills that are links: installSkills never writes through one, so copying cannot move them. */
+function linkedPackEntries(skillsDir) {
+    let entries;
+    try {
+        entries = readdirSync(skillsDir);
+    }
+    catch {
+        return [];
+    }
+    return entries.filter((name) => {
+        try {
+            return lstatSync(join(skillsDir, name)).isSymbolicLink() && installedBundleVersion(skillsDir, [name]).version !== null;
+        }
+        catch {
+            return false;
+        }
+    });
+}
+/** Refresh the Cloud pack's installed skills in `skillsDir` to exact version `target`. */
+export function applyCloudPackUpdate(home, skillsDir, target, deps = {}) {
+    // Checked before any download, so a linked pack is not fetched again on every run.
+    if (linkedPackEntries(skillsDir).length > 0)
+        return { outcome: "linked", detail: "installation_owner_unknown", version: null };
+    const staged = stageCliRuntime(home, target, deps);
+    if (!staged.ok)
+        return { outcome: "failed", detail: staged.detail, version: null };
+    const source = stagedSkillsDir(staged.root);
+    let names;
+    try {
+        names = skillNames(source);
+    }
+    catch {
+        return { outcome: "failed", detail: "pack_mismatch", version: null };
+    }
+    // The staged package must carry exactly the approved pack, or nothing is copied.
+    if (names.length === 0 || installedBundleVersion(source, names).version !== target)
+        return { outcome: "failed", detail: "pack_mismatch", version: null };
+    try {
+        installSkills(skillsDir, { onlyExisting: true }, source, target);
+    }
+    catch {
+        return { outcome: "failed", detail: "install_failed", version: installedBundleVersion(skillsDir, names).version };
+    }
+    const now = installedBundleVersion(skillsDir, names).version;
+    return now === target ? { outcome: "updated", detail: "refreshed", version: now } : { outcome: "failed", detail: "verify_failed", version: now };
+}