@alphafox/cli 0.3.4 → 0.3.6

package/dist/skills/manager.js

@@ -0,0 +1,445 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildSkillsManifest = buildSkillsManifest;
+exports.writeSkillsManifest = writeSkillsManifest;
+exports.loadAndVerifySkillsManifest = loadAndVerifySkillsManifest;
+exports.inspectSkills = inspectSkills;
+exports.syncSkills = syncSkills;
+exports.loadSkillsState = loadSkillsState;
+exports.hashSkillDirectory = hashSkillDirectory;
+exports.readSkillVersion = readSkillVersion;
+exports.readSkillName = readSkillName;
+const node_crypto_1 = require("node:crypto");
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+function buildSkillsManifest(packageRoot, versions) {
+    const skillsRoot = (0, node_path_1.join)(packageRoot, "skills");
+    if (!(0, node_fs_1.existsSync)(skillsRoot)) {
+        throw new Error(`Skills directory is missing: ${skillsRoot}`);
+    }
+    const skills = (0, node_fs_1.readdirSync)(skillsRoot, { withFileTypes: true })
+        .filter((entry) => entry.isDirectory() &&
+        (0, node_fs_1.existsSync)((0, node_path_1.join)(skillsRoot, entry.name, "SKILL.md")))
+        .map((entry) => {
+        const root = (0, node_path_1.join)(skillsRoot, entry.name);
+        const skillPath = (0, node_path_1.join)(root, "SKILL.md");
+        const files = manifestFiles(root);
+        const name = readSkillName(skillPath);
+        if (!name) {
+            throw Object.assign(new Error(`Skill name is missing from ${skillPath}`), {
+                type: "install",
+                subtype: "skills_bundle_name_missing",
+            });
+        }
+        const version = readSkillVersion(skillPath) ?? versions.packageVersion;
+        if (version !== versions.packageVersion) {
+            throw Object.assign(new Error(`Skill ${entry.name} version ${version} does not match package ${versions.packageVersion}`), {
+                type: "install",
+                subtype: "skills_bundle_version_mismatch",
+            });
+        }
+        return {
+            name,
+            version,
+            files,
+            hash: hashManifestFiles(files),
+        };
+    })
+        .sort((a, b) => a.name.localeCompare(b.name));
+    if (skills.length === 0) {
+        throw new Error(`No Skills found under ${skillsRoot}`);
+    }
+    if (new Set(skills.map((skill) => skill.name)).size !== skills.length) {
+        throw Object.assign(new Error("Skills bundle contains duplicate names"), {
+            type: "install",
+            subtype: "skills_bundle_duplicate_name",
+        });
+    }
+    return {
+        schemaVersion: 1,
+        packageName: "@alphafox/cli",
+        packageVersion: versions.packageVersion,
+        contractVersion: versions.contractVersion,
+        bundleHash: sha256(skills.map((skill) => `${skill.name}\0${skill.hash}`).join("\n")),
+        skills,
+    };
+}
+function writeSkillsManifest(packageRoot, outputPath, versions) {
+    const manifest = buildSkillsManifest(packageRoot, versions);
+    (0, node_fs_1.mkdirSync)((0, node_path_1.dirname)(outputPath), { recursive: true });
+    (0, node_fs_1.writeFileSync)(outputPath, `${JSON.stringify(manifest, null, 2)}\n`);
+    return manifest;
+}
+function loadAndVerifySkillsManifest(packageRoot, manifestPath = (0, node_path_1.join)(packageRoot, "dist", "skills-manifest.json")) {
+    try {
+        const recorded = JSON.parse((0, node_fs_1.readFileSync)(manifestPath, "utf8"));
+        if (recorded.schemaVersion !== 1 ||
+            recorded.packageName !== "@alphafox/cli" ||
+            typeof recorded.packageVersion !== "string" ||
+            typeof recorded.contractVersion !== "string" ||
+            typeof recorded.bundleHash !== "string" ||
+            !Array.isArray(recorded.skills)) {
+            throw new Error("manifest shape is invalid");
+        }
+        const packageJson = JSON.parse((0, node_fs_1.readFileSync)((0, node_path_1.join)(packageRoot, "package.json"), "utf8"));
+        if (packageJson.name !== recorded.packageName ||
+            packageJson.version !== recorded.packageVersion) {
+            throw new Error(`manifest ${recorded.packageName}@${recorded.packageVersion} does not match package ${String(packageJson.name)}@${String(packageJson.version)}`);
+        }
+        const actual = buildSkillsManifest(packageRoot, {
+            packageVersion: recorded.packageVersion,
+            contractVersion: recorded.contractVersion,
+        });
+        if (actual.bundleHash !== recorded.bundleHash) {
+            throw new Error(`bundle hash ${actual.bundleHash} does not match ${recorded.bundleHash}`);
+        }
+        if (JSON.stringify(actual.skills) !== JSON.stringify(recorded.skills)) {
+            throw new Error("manifest Skill entries do not match bundled files");
+        }
+        return actual;
+    }
+    catch (err) {
+        throw Object.assign(new Error(`AlphaFox Skills bundle integrity check failed: ${manifestPath}`), {
+            type: "install",
+            subtype: "skills_bundle_integrity",
+            details: err instanceof Error ? err.message : String(err),
+        });
+    }
+}
+function inspectSkills(input) {
+    const skills = input.manifest.skills.map((expected) => {
+        const installedDir = (0, node_path_1.join)(input.installedRoot, expected.name);
+        if (!(0, node_fs_1.existsSync)((0, node_path_1.join)(installedDir, "SKILL.md"))) {
+            return {
+                name: expected.name,
+                expectedVersion: expected.version,
+                installedVersion: null,
+                expectedHash: expected.hash,
+                installedHash: null,
+                status: "missing",
+                managed: false,
+            };
+        }
+        const installedHash = hashSkillDirectory(installedDir);
+        const installedVersion = readSkillVersion((0, node_path_1.join)(installedDir, "SKILL.md"));
+        if (installedHash === expected.hash) {
+            return {
+                name: expected.name,
+                expectedVersion: expected.version,
+                installedVersion,
+                expectedHash: expected.hash,
+                installedHash,
+                status: "current",
+                managed: true,
+            };
+        }
+        const previous = input.state?.skills[expected.name];
+        const stateConfirmsUnmodified = previous?.hash === installedHash;
+        const legacyVersionIsOlder = installedVersion != null &&
+            compareSemver(installedVersion, expected.version) < 0;
+        return {
+            name: expected.name,
+            expectedVersion: expected.version,
+            installedVersion,
+            expectedHash: expected.hash,
+            installedHash,
+            status: stateConfirmsUnmodified || (!input.state && legacyVersionIsOlder)
+                ? "stale"
+                : "modified",
+            managed: Boolean(previous) || legacyVersionIsOlder,
+        };
+    });
+    const summary = {
+        current: 0,
+        missing: 0,
+        stale: 0,
+        modified: 0,
+    };
+    for (const skill of skills)
+        summary[skill.status] += 1;
+    const expectedNames = new Set(input.manifest.skills.map((skill) => skill.name));
+    const orphans = Object.entries(input.state?.skills ?? {})
+        .filter(([name]) => !expectedNames.has(name))
+        .flatMap(([name, recorded]) => {
+        const installedDir = (0, node_path_1.join)(input.installedRoot, name);
+        if (!(0, node_fs_1.existsSync)((0, node_path_1.join)(installedDir, "SKILL.md")))
+            return [];
+        const installedHash = hashSkillDirectory(installedDir);
+        return [
+            {
+                name,
+                installedHash,
+                recordedHash: recorded.hash,
+                modified: installedHash !== recorded.hash,
+            },
+        ];
+    })
+        .sort((a, b) => a.name.localeCompare(b.name));
+    return {
+        bundleVersion: input.manifest.packageVersion,
+        contractVersion: input.manifest.contractVersion,
+        bundleHash: input.manifest.bundleHash,
+        installedRoot: input.installedRoot,
+        skills,
+        orphans,
+        summary,
+        restartRequired: summary.missing + summary.stale + summary.modified + orphans.length > 0,
+    };
+}
+async function syncSkills(input, deps) {
+    const state = loadSkillsState(input.statePath);
+    const before = inspectSkills({
+        manifest: input.manifest,
+        installedRoot: input.installedRoot,
+        state,
+    });
+    const selected = before.skills
+        .filter((skill) => skill.status === "missing" ||
+        skill.status === "stale" ||
+        (input.force && skill.status === "modified"))
+        .map((skill) => skill.name);
+    const blocked = before.skills
+        .filter((skill) => skill.status === "modified" && !input.force)
+        .map((skill) => skill.name);
+    const removed = before.orphans
+        .filter((skill) => !skill.modified || input.force)
+        .map((skill) => skill.name);
+    blocked.push(...before.orphans
+        .filter((skill) => skill.modified && !input.force)
+        .map((skill) => skill.name));
+    if (input.dryRun) {
+        return {
+            action: selected.length + removed.length > 0 ? "planned" : "skipped",
+            updated: selected,
+            removed,
+            blocked,
+            status: before,
+            restartRequired: selected.length + removed.length > 0,
+        };
+    }
+    const release = acquireSkillsLock(input.statePath);
+    let backupDir;
+    try {
+        if (selected.length + removed.length > 0) {
+            backupDir = backupSkills([...new Set([...selected, ...removed])], input.installedRoot, input.statePath, deps.now?.() ?? new Date());
+        }
+        if (selected.length > 0) {
+            await deps.install(selected);
+        }
+        if (removed.length > 0) {
+            if (!deps.remove) {
+                throw Object.assign(new Error("Skills remover is required for retired managed Skills"), {
+                    type: "install",
+                    subtype: "skills_remove_unavailable",
+                });
+            }
+            await deps.remove(removed);
+        }
+        const after = inspectSkills({
+            manifest: input.manifest,
+            installedRoot: input.installedRoot,
+            state,
+        });
+        const failed = selected.filter((name) => after.skills.find((skill) => skill.name === name)?.status !== "current");
+        if (failed.length > 0) {
+            throw Object.assign(new Error(`Skills sync verification failed for: ${failed.join(", ")}`), {
+                type: "install",
+                subtype: "skills_verify_failed",
+                details: { failed, backupDir },
+            });
+        }
+        const removalFailed = removed.filter((name) => (0, node_fs_1.existsSync)((0, node_path_1.join)(input.installedRoot, name, "SKILL.md")));
+        if (removalFailed.length > 0) {
+            throw Object.assign(new Error(`Retired Skills removal verification failed for: ${removalFailed.join(", ")}`), {
+                type: "install",
+                subtype: "skills_remove_verify_failed",
+                details: { failed: removalFailed, backupDir },
+            });
+        }
+        saveSkillsState(input.statePath, stateFromStatus(input.manifest, after, deps.now?.() ?? new Date(), state));
+        return {
+            action: selected.length + removed.length > 0 ? "synced" : "skipped",
+            updated: selected,
+            removed,
+            blocked,
+            ...(backupDir ? { backupDir } : {}),
+            status: after,
+            restartRequired: selected.length + removed.length > 0,
+        };
+    }
+    finally {
+        release();
+    }
+}
+function loadSkillsState(path) {
+    if (!(0, node_fs_1.existsSync)(path))
+        return null;
+    let parsed;
+    try {
+        parsed = JSON.parse((0, node_fs_1.readFileSync)(path, "utf8"));
+    }
+    catch (err) {
+        throw Object.assign(new Error(`Invalid Skills state file: ${path}`), {
+            type: "install",
+            subtype: "skills_state_invalid",
+            details: err instanceof Error ? err.message : String(err),
+        });
+    }
+    if (!parsed ||
+        typeof parsed !== "object" ||
+        parsed.schemaVersion !== 1 ||
+        typeof parsed.skills !== "object") {
+        throw Object.assign(new Error(`Invalid Skills state file: ${path}`), {
+            type: "install",
+            subtype: "skills_state_invalid",
+        });
+    }
+    return parsed;
+}
+function hashSkillDirectory(skillRoot) {
+    return hashManifestFiles(manifestFiles(skillRoot));
+}
+function readSkillVersion(skillPath) {
+    try {
+        const match = (0, node_fs_1.readFileSync)(skillPath, "utf8").match(/^version:\s*["']?([^"'\s]+)["']?\s*$/m);
+        return match?.[1] ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+function readSkillName(skillPath) {
+    try {
+        const match = (0, node_fs_1.readFileSync)(skillPath, "utf8").match(/^name:\s*["']?([^"'\s]+)["']?\s*$/m);
+        return match?.[1] ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+function manifestFiles(root) {
+    return listFiles(root)
+        .map((path) => {
+        const body = (0, node_fs_1.readFileSync)(path);
+        return {
+            path: (0, node_path_1.relative)(root, path).split(node_path_1.sep).join("/"),
+            sha256: sha256(body),
+            size: body.length,
+        };
+    })
+        .sort((a, b) => a.path.localeCompare(b.path));
+}
+function listFiles(root) {
+    const out = [];
+    for (const entry of (0, node_fs_1.readdirSync)(root, { withFileTypes: true })) {
+        const path = (0, node_path_1.join)(root, entry.name);
+        if (entry.isDirectory()) {
+            out.push(...listFiles(path));
+        }
+        else if (entry.isFile() || (0, node_fs_1.statSync)(path).isFile()) {
+            out.push(path);
+        }
+    }
+    return out;
+}
+function hashManifestFiles(files) {
+    return sha256(files
+        .map((file) => `${file.path}\0${file.size}\0${file.sha256}`)
+        .join("\n"));
+}
+function sha256(value) {
+    return (0, node_crypto_1.createHash)("sha256").update(value).digest("hex");
+}
+function compareSemver(a, b) {
+    const pa = a.replace(/-.*$/, "").split(".").map(Number);
+    const pb = b.replace(/-.*$/, "").split(".").map(Number);
+    for (let i = 0; i < 3; i += 1) {
+        const delta = (pa[i] || 0) - (pb[i] || 0);
+        if (delta !== 0)
+            return delta < 0 ? -1 : 1;
+    }
+    return 0;
+}
+function saveSkillsState(path, state) {
+    (0, node_fs_1.mkdirSync)((0, node_path_1.dirname)(path), { recursive: true });
+    const tmp = `${path}.tmp-${process.pid}`;
+    (0, node_fs_1.writeFileSync)(tmp, `${JSON.stringify(state, null, 2)}\n`, { mode: 0o600 });
+    (0, node_fs_1.renameSync)(tmp, path);
+}
+function stateFromStatus(manifest, status, now, previous) {
+    const skills = {};
+    for (const item of status.skills) {
+        if (item.status === "current" && item.installedHash) {
+            skills[item.name] = {
+                version: item.expectedVersion,
+                hash: item.installedHash,
+            };
+        }
+    }
+    for (const orphan of status.orphans) {
+        const recorded = previous?.skills[orphan.name];
+        if (orphan.modified && recorded) {
+            skills[orphan.name] = recorded;
+        }
+    }
+    return {
+        schemaVersion: 1,
+        packageVersion: manifest.packageVersion,
+        contractVersion: manifest.contractVersion,
+        bundleHash: manifest.bundleHash,
+        syncedAt: now.toISOString(),
+        skills,
+    };
+}
+function backupSkills(names, installedRoot, statePath, now) {
+    const existing = names.filter((name) => (0, node_fs_1.existsSync)((0, node_path_1.join)(installedRoot, name, "SKILL.md")));
+    if (existing.length === 0)
+        return undefined;
+    const stamp = now.toISOString().replace(/[:.]/g, "-");
+    const root = (0, node_path_1.join)((0, node_path_1.dirname)(statePath), "skill-backups", stamp);
+    (0, node_fs_1.mkdirSync)(root, { recursive: true });
+    for (const name of existing) {
+        (0, node_fs_1.cpSync)((0, node_path_1.join)(installedRoot, name), (0, node_path_1.join)(root, name), {
+            recursive: true,
+            dereference: true,
+        });
+    }
+    return root;
+}
+function acquireSkillsLock(statePath) {
+    (0, node_fs_1.mkdirSync)((0, node_path_1.dirname)(statePath), { recursive: true });
+    const path = `${statePath}.lock`;
+    let fd;
+    try {
+        fd = (0, node_fs_1.openSync)(path, "wx", 0o600);
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === "EEXIST") {
+            const ageMs = Date.now() - (0, node_fs_1.statSync)(path).mtimeMs;
+            if (ageMs > 5 * 60_000) {
+                (0, node_fs_1.unlinkSync)(path);
+                fd = (0, node_fs_1.openSync)(path, "wx", 0o600);
+            }
+            else {
+                throw Object.assign(new Error("Another AlphaFox Skills sync is already running"), {
+                    type: "install",
+                    subtype: "skills_sync_in_progress",
+                });
+            }
+        }
+        else {
+            throw err;
+        }
+    }
+    (0, node_fs_1.writeFileSync)(fd, `${process.pid}\n`);
+    (0, node_fs_1.closeSync)(fd);
+    return () => {
+        try {
+            (0, node_fs_1.unlinkSync)(path);
+        }
+        catch {
+            // Best effort: a stale lock is recovered after five minutes.
+        }
+    };
+}

package/dist/skills/run-command.d.ts

@@ -0,0 +1,22 @@
+import type { InstallRunner } from "../install/types";
+import { type SkillsStatus, type SkillsSyncResult } from "./manager";
+export interface SkillsCliFlags {
+    readonly format: "json" | "jsonl" | "text";
+    readonly yes: boolean;
+    readonly dryRun: boolean;
+    readonly noInput: boolean;
+    readonly jq?: string;
+}
+export interface SkillsCommandDeps {
+    readonly runner?: InstallRunner;
+    readonly packageRoot?: string;
+}
+export declare function installedSkillsRoot(env?: NodeJS.ProcessEnv): string;
+export declare function skillsStatePath(env?: NodeJS.ProcessEnv): string;
+export declare function resolveCurrentSkillsPackageRoot(searchDirs?: readonly string[]): string;
+export declare function inspectCurrentSkills(env?: NodeJS.ProcessEnv, packageRoot?: string): SkillsStatus;
+export declare function syncCurrentSkills(input: {
+    readonly force: boolean;
+    readonly dryRun: boolean;
+}, env?: NodeJS.ProcessEnv, deps?: SkillsCommandDeps): Promise<SkillsSyncResult>;
+export declare function cmdSkills(args: string[], flags: SkillsCliFlags, env?: NodeJS.ProcessEnv, deps?: SkillsCommandDeps): Promise<number>;

package/dist/skills/run-command.js

@@ -0,0 +1,143 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.installedSkillsRoot = installedSkillsRoot;
+exports.skillsStatePath = skillsStatePath;
+exports.resolveCurrentSkillsPackageRoot = resolveCurrentSkillsPackageRoot;
+exports.inspectCurrentSkills = inspectCurrentSkills;
+exports.syncCurrentSkills = syncCurrentSkills;
+exports.cmdSkills = cmdSkills;
+const node_os_1 = require("node:os");
+const node_path_1 = require("node:path");
+const profiles_1 = require("../config/profiles");
+const envelope_1 = require("../envelope");
+const exec_1 = require("../install/exec");
+const package_root_1 = require("../install/package-root");
+const manager_1 = require("./manager");
+const SKILLS_TIMEOUT_MS = 120_000;
+function installedSkillsRoot(env = process.env) {
+    return (env.ALPHAFOX_SKILLS_DIR?.trim() ||
+        (0, node_path_1.join)((0, node_os_1.homedir)(), ".agents", "skills"));
+}
+function skillsStatePath(env = process.env) {
+    return (0, node_path_1.join)((0, profiles_1.defaultConfigDir)(env), "skills-state.json");
+}
+function resolveCurrentSkillsPackageRoot(searchDirs = [__dirname, process.cwd()]) {
+    const root = (0, package_root_1.findAlphafoxPackageRoot)(searchDirs);
+    if (!root) {
+        throw Object.assign(new Error("Could not locate the installed @alphafox/cli Skills bundle"), {
+            type: "install",
+            subtype: "skills_package_missing",
+        });
+    }
+    return root;
+}
+function inspectCurrentSkills(env = process.env, packageRoot = resolveCurrentSkillsPackageRoot()) {
+    const manifest = (0, manager_1.loadAndVerifySkillsManifest)(packageRoot);
+    return (0, manager_1.inspectSkills)({
+        manifest,
+        installedRoot: installedSkillsRoot(env),
+        state: (0, manager_1.loadSkillsState)(skillsStatePath(env)),
+    });
+}
+async function syncCurrentSkills(input, env = process.env, deps = {}) {
+    const packageRoot = deps.packageRoot ?? resolveCurrentSkillsPackageRoot();
+    const runner = deps.runner ??
+        (0, exec_1.createDefaultInstallRunner)(env, [__dirname, process.cwd()]);
+    const manifest = (0, manager_1.loadAndVerifySkillsManifest)(packageRoot);
+    return await (0, manager_1.syncSkills)({
+        manifest,
+        packageRoot,
+        installedRoot: installedSkillsRoot(env),
+        statePath: skillsStatePath(env),
+        dryRun: input.dryRun,
+        force: input.force,
+    }, {
+        install: async (names) => {
+            await runner.exec("npx", [
+                "-y",
+                "skills",
+                "add",
+                packageRoot,
+                "-y",
+                "-g",
+                "--skill",
+                ...names,
+            ], { timeoutMs: SKILLS_TIMEOUT_MS });
+        },
+        remove: async (names) => {
+            await runner.exec("npx", ["-y", "skills", "remove", ...names, "-y", "-g"], { timeoutMs: SKILLS_TIMEOUT_MS });
+        },
+    });
+}
+async function cmdSkills(args, flags, env = process.env, deps = {}) {
+    const parsed = parseSkillsArgs(args);
+    if (parsed.action === "help") {
+        (0, envelope_1.writeSuccess)({
+            name: "skills",
+            usage: [
+                "alphafox skills status",
+                "alphafox skills sync [--dry-run]",
+                "alphafox skills sync --force --yes",
+            ],
+            notes: [
+                "Skills are synced only from the verified bundle inside the installed @alphafox/cli package",
+                "Modified Skills are preserved unless --force --yes is explicit",
+                "Restart the AI tool after a successful sync",
+            ],
+        }, { format: flags.format, jq: flags.jq });
+        return 0;
+    }
+    if (parsed.action === "status") {
+        (0, envelope_1.writeSuccess)(inspectCurrentSkills(env, deps.packageRoot ?? resolveCurrentSkillsPackageRoot()), { format: flags.format, jq: flags.jq });
+        return 0;
+    }
+    const runner = deps.runner ??
+        (0, exec_1.createDefaultInstallRunner)(env, [__dirname, process.cwd()]);
+    if (parsed.force && !flags.yes) {
+        const confirmed = !flags.noInput &&
+            runner.isTty() &&
+            (await runner.confirm("Modified AlphaFox Skills will be backed up and replaced. Continue?"));
+        if (!confirmed) {
+            throw Object.assign(new Error("Replacing modified Skills requires --force --yes"), {
+                type: "confirmation",
+                subtype: "skills_force_confirmation_required",
+            });
+        }
+    }
+    const result = await syncCurrentSkills({ force: parsed.force, dryRun: flags.dryRun }, env, { ...deps, runner });
+    (0, envelope_1.writeSuccess)(result, { format: flags.format, jq: flags.jq });
+    return result.blocked.length > 0 ? 1 : 0;
+}
+function parseSkillsArgs(args) {
+    const actionToken = args[0] ?? "status";
+    if (actionToken === "help" ||
+        actionToken === "--help" ||
+        actionToken === "-h") {
+        return { action: "help", force: false };
+    }
+    if (actionToken !== "status" && actionToken !== "sync") {
+        throw usageError(`Unknown skills action: ${actionToken}`);
+    }
+    let force = false;
+    for (const arg of args.slice(1)) {
+        if (arg === "--force")
+            force = true;
+        else if (arg === "--help" || arg === "-h") {
+            return { action: "help", force: false };
+        }
+        else {
+            throw usageError(`Unknown skills argument: ${arg}`);
+        }
+    }
+    if (actionToken === "status" && force) {
+        throw usageError("--force is only valid with skills sync");
+    }
+    return { action: actionToken, force };
+}
+function usageError(message) {
+    return Object.assign(new Error(message), {
+        type: "usage",
+        subtype: "invalid_skills_args",
+        status: 64,
+    });
+}