@nocobase/app-cli-client 0.1.0-beta.2 → 0.1.0-beta.20

package/dist/skills.js

@@ -0,0 +1,728 @@
+// Local installation of the Skills shipped by a branded CLI (every `skills/<slug>/SKILL.md` in its package). No session, credential, or network is read.
+import { createHash } from 'node:crypto';
+import { constants, lstatSync, readdirSync } from 'node:fs';
+import { access, lstat, stat as followStat, mkdir, mkdtemp, open, readFile, readdir, rename, rm, writeFile, } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { Flags } from '@oclif/core';
+import { EXIT_CODES } from '@nocobase/agent-protocol';
+import { appCliHome } from "./config.js";
+import { AppCommand } from "./lib/command.js";
+import { findRunCredentials } from "./lib/credentials.js";
+import { CliCommandError } from "./lib/envelope.js";
+import { withSkillLock } from "./skills-lock.js";
+// The Skill every Studio CLI has shipped since the commands existed. It alone has a legacy Codex location and feeds ACP sessions.
+const SKILL = 'nb-studio-cli';
+// A slug names a directory below a tool's skills root, so it may not hold a separator and may not start with a dot.
+const SLUG = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+const TOOLS = ['claude', 'codex'];
+/** `skills`, and the earlier result's `skill` and `hash` for the primary Skill. */
+function shippedSummary(sources) {
+    const skills = [...sources].map(([skill, source]) => ({
+        skill,
+        hash: source.hash,
+    }));
+    const primary = skills.find(({ skill }) => skill === 'nb-studio-cli') ?? skills[0];
+    return { skills, skill: primary?.skill ?? '', hash: primary?.hash ?? '' };
+}
+function sourceOf(environment, skill) {
+    return path.resolve(environment.packageRoot, 'skills', skill);
+}
+/** The Skills a package ships: directories of `<packageRoot>/skills` holding SKILL.md, sorted by slug. */
+export function shippedSkills(packageRoot) {
+    const root = path.join(packageRoot, 'skills');
+    try {
+        return readdirSync(root, { withFileTypes: true })
+            .filter((entry) => {
+            if (!entry.isDirectory() || !SLUG.test(entry.name))
+                return false;
+            try {
+                return lstatSync(path.join(root, entry.name, 'SKILL.md')).isFile();
+            }
+            catch {
+                return false;
+            }
+        })
+            .map((entry) => entry.name)
+            .sort();
+    }
+    catch {
+        return [];
+    }
+}
+/** Only packages shipping at least one Skill expose the two commands. */
+export function hasStudioSkill(config) {
+    return (config.selfUpdate !== undefined &&
+        shippedSkills(config.selfUpdate.packageRoot).length > 0);
+}
+export function skillsEnvironment(config) {
+    if (config.selfUpdate === undefined)
+        throw new Error('This CLI has no packaged Skill.');
+    return {
+        packageRoot: config.selfUpdate.packageRoot,
+        cliVersion: config.version ?? 'unknown',
+        bin: config.bin,
+        stateHome: appCliHome(config),
+    };
+}
+function locations(environment, skills = shippedSkills(environment.packageRoot)) {
+    const home = environment.home ?? os.homedir();
+    const env = environment.env ?? process.env;
+    const configs = {
+        claude: path.resolve(env.CLAUDE_CONFIG_DIR || path.join(home, '.claude')),
+        codex: path.resolve(env.CODEX_HOME || path.join(home, '.codex')),
+    };
+    const roots = {
+        claude: path.join(configs.claude, 'skills'),
+        codex: path.resolve(home, '.agents', 'skills'),
+    };
+    return {
+        configs,
+        roots,
+        defaults: skills.flatMap((skill) => TOOLS.map((tool) => ({
+            skill,
+            tool,
+            path: path.join(roots[tool], skill),
+        }))),
+        // Only nb-studio-cli was ever installed below CODEX_HOME; newer Skills have no legacy location.
+        legacy: skills.includes(SKILL)
+            ? [
+                {
+                    skill: SKILL,
+                    tool: 'codex',
+                    path: path.join(configs.codex, 'skills', SKILL),
+                },
+            ]
+            : [],
+    };
+}
+async function detected(tool, environment) {
+    const env = environment.env ?? process.env;
+    if (env[tool === 'claude' ? 'CLAUDE_CONFIG_DIR' : 'CODEX_HOME'])
+        return true;
+    if ((await stat(locations(environment).configs[tool]))?.isDirectory())
+        return true;
+    const names = process.platform === 'win32' ? ['', '.exe', '.cmd', '.bat'] : [''];
+    for (const dir of (env.PATH ?? '').split(path.delimiter).filter(Boolean)) {
+        for (const suffix of names) {
+            const executable = path.join(dir, `${tool}${suffix}`);
+            try {
+                if (!(await followStat(executable)).isFile())
+                    continue;
+                await access(executable, constants.X_OK);
+                return true;
+            }
+            catch {
+                /* An inaccessible executable is not evidence of a usable tool. */
+            }
+        }
+    }
+    return false;
+}
+function selection(tools) {
+    if (tools.some((tool) => ![...TOOLS, 'all'].includes(tool)))
+        throw new CliCommandError('SKILLS_INVALID_TOOL', 'Choose --tool claude, codex, or all.', { exit: EXIT_CODES.validation });
+    return tools.includes('all')
+        ? [...TOOLS]
+        : TOOLS.filter((tool) => tools.includes(tool));
+}
+async function stat(file) {
+    try {
+        return await lstat(file);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return undefined;
+        throw error;
+    }
+}
+// Reject links at every writable component, including a dangling link. We never follow a link to replace its target.
+async function safePath(file, directory = true) {
+    const absolute = path.resolve(file);
+    let current = path.parse(absolute).root;
+    for (const part of absolute
+        .slice(current.length)
+        .split(path.sep)
+        .filter(Boolean)) {
+        current = path.join(current, part);
+        const info = await stat(current);
+        if (info === undefined)
+            continue;
+        if (info.isSymbolicLink() ||
+            (directory || current !== absolute ? !info.isDirectory() : !info.isFile()))
+            throw new CliCommandError('SKILLS_UNSAFE_PATH', `Refusing a symbolic link or unexpected file type: ${current}`, { exit: EXIT_CODES.validation });
+    }
+}
+async function snapshot(root) {
+    await safePath(root);
+    const entries = [];
+    async function visit(dir, relative) {
+        for (const name of (await readdir(dir)).sort()) {
+            const child = path.join(dir, name);
+            const rel = relative ? `${relative}/${name}` : name;
+            const info = await lstat(child);
+            if (info.isDirectory()) {
+                entries.push({ name: rel });
+                await visit(child, rel);
+            }
+            else if (info.isFile()) {
+                // O_NOFOLLOW also closes the file-link race between lstat and open on supported platforms.
+                const handle = await open(child, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
+                try {
+                    entries.push({ name: rel, bytes: await handle.readFile() });
+                }
+                finally {
+                    await handle.close();
+                }
+            }
+            else
+                throw new CliCommandError('SKILLS_UNSAFE_PATH', `Refusing a symbolic link or special file inside the Skill: ${child}`, { exit: EXIT_CODES.validation });
+        }
+    }
+    await visit(root, '');
+    const hash = createHash('sha256')
+        .update(JSON.stringify(entries.map((entry) => [
+        entry.name,
+        entry.bytes === undefined
+            ? 'directory'
+            : createHash('sha256').update(entry.bytes).digest('hex'),
+    ])))
+        .digest('hex');
+    return { entries, hash };
+}
+async function bundled(environment, skill) {
+    const result = await snapshot(sourceOf(environment, skill));
+    if (!result.entries.some((entry) => entry.name === 'SKILL.md' && entry.bytes !== undefined))
+        throw new Error(`The packaged ${skill} Skill has no SKILL.md.`);
+    return result;
+}
+async function bundledAll(environment) {
+    const slugs = shippedSkills(environment.packageRoot);
+    if (slugs.length === 0)
+        throw new Error('This CLI package ships no Skills.');
+    return new Map(await Promise.all(slugs.map(async (slug) => [slug, await bundled(environment, slug)])));
+}
+function registryFile(environment) {
+    return path.resolve(environment.stateHome, 'skills.json');
+}
+async function readRegistry(environment) {
+    const file = registryFile(environment);
+    await safePath(file, false);
+    if ((await stat(file)) === undefined)
+        return { version: 2, targets: [] };
+    const invalid = () => new CliCommandError('SKILLS_INVALID_REGISTRY', `Invalid Skill installation record: ${file}`, { exit: EXIT_CODES.validation });
+    const data = JSON.parse(await readFile(file, 'utf8'));
+    if (data === null || typeof data !== 'object')
+        throw invalid();
+    // A newer format may not even have targets. Never reinterpret or rewrite it.
+    if (typeof data.version === 'number' && data.version > 2)
+        return { version: 2, targets: [], newer: true };
+    if (!Array.isArray(data.targets))
+        throw invalid();
+    // The original file has no version and one top-level `skill`; its targets inherit it.
+    const legacy = data.version === undefined;
+    if (legacy ? data.skill !== SKILL : data.version !== 2)
+        throw invalid();
+    const targets = data.targets.map((target) => ({
+        ...target,
+        skill: legacy ? SKILL : target?.skill,
+    }));
+    if (targets.some((target) => !target ||
+        typeof target.skill !== 'string' ||
+        !SLUG.test(target.skill) ||
+        !TOOLS.includes(target.tool) ||
+        typeof target.path !== 'string' ||
+        !path.isAbsolute(target.path) ||
+        path.basename(target.path) !== target.skill ||
+        path.basename(path.dirname(target.path)) !== 'skills' ||
+        typeof target.cliVersion !== 'string' ||
+        typeof target.hash !== 'string'))
+        throw invalid();
+    return { version: 2, targets };
+}
+function requireWritableRegistry(registry, environment) {
+    if (registry.newer)
+        throw new CliCommandError('SKILLS_NEWER_REGISTRY', `The Skill installation record uses a newer format. Update ${environment.bin} before installing Skills.`, { exit: EXIT_CODES.validation });
+}
+async function writeRegistry(environment, registry) {
+    requireWritableRegistry(registry, environment);
+    const file = registryFile(environment);
+    await safePath(file, false);
+    const temporary = await mkdtemp(path.join(environment.stateHome, '.skills-record-'));
+    try {
+        const staged = path.join(temporary, 'skills.json');
+        await writeFile(staged, `${JSON.stringify(registry, null, 2)}\n`, {
+            mode: 0o600,
+        });
+        await rename(staged, file);
+    }
+    finally {
+        await rm(temporary, { recursive: true, force: true });
+    }
+}
+async function lock(file, work) {
+    await safePath(path.dirname(file));
+    return withSkillLock(file, work);
+}
+async function statusOf(target, environment, source, registry) {
+    const record = registry.targets.find((record) => path.resolve(record.path) === path.resolve(target.path));
+    const base = {
+        ...target,
+        legacy: target.tool === 'codex' &&
+            target.path !==
+                path.join(locations(environment).roots.codex, target.skill),
+        ...(source === undefined ? { dropped: true } : {}),
+        registered: record !== undefined,
+        ...(record ? { installedCliVersion: record.cliVersion } : {}),
+    };
+    try {
+        await safePath(target.path);
+        const present = (await stat(target.path)) !== undefined;
+        return {
+            ...base,
+            present,
+            upToDate: source !== undefined &&
+                present &&
+                (await snapshot(target.path)).hash === source.hash,
+        };
+    }
+    catch (error) {
+        return {
+            ...base,
+            present: (await stat(target.path).catch(() => undefined)) !== undefined,
+            upToDate: false,
+            error: error instanceof Error ? error.message : String(error),
+        };
+    }
+}
+function unique(targets) {
+    return [
+        ...new Map(targets.map((target) => {
+            const normalized = path.resolve(target.path);
+            return [normalized, { ...target, path: normalized }];
+        })).values(),
+    ];
+}
+/** Includes manual and legacy copies, and previously registered paths after environment variables change. */
+export async function skillsStatus(environment, tools = []) {
+    const selected = selection(tools);
+    const sources = await bundledAll(environment);
+    const registry = await readRegistry(environment);
+    const { defaults, legacy } = locations(environment);
+    const targets = unique([...defaults, ...legacy, ...registry.targets]).filter((target) => selected.length === 0 || selected.includes(target.tool));
+    return {
+        ...shippedSummary(sources),
+        cliVersion: environment.cliVersion,
+        targets: await Promise.all(targets.map((target) => statusOf(target, environment, sources.get(target.skill), registry))),
+    };
+}
+function overlaps(first, second) {
+    const contains = (a, b) => b === a || b.startsWith(`${a}${path.sep}`);
+    return (contains(path.resolve(first), path.resolve(second)) ||
+        contains(path.resolve(second), path.resolve(first)));
+}
+// Check the complete plan before replacing any directory: replacing a parent would delete a child Skill.
+function targetConflicts(targets) {
+    const destinations = unique(targets);
+    const conflicts = new Map();
+    for (let index = 0; index < destinations.length; index++) {
+        const first = destinations[index];
+        for (const second of destinations.slice(index + 1)) {
+            if (!overlaps(first.path, second.path))
+                continue;
+            const error = new CliCommandError('SKILLS_TARGET_OVERLAP', `Skill destinations contain one another: ${first.path} and ${second.path}. Choose separate tool configuration directories before installing.`, {
+                exit: EXIT_CODES.validation,
+                details: { paths: [first.path, second.path] },
+            });
+            conflicts.set(first.path, error);
+            conflicts.set(second.path, error);
+        }
+    }
+    return conflicts;
+}
+async function replace(target, environment, source, registry) {
+    requireWritableRegistry(registry, environment);
+    if (overlaps(target.path, environment.packageRoot) ||
+        overlaps(target.path, environment.stateHome))
+        throw new CliCommandError('SKILLS_UNSAFE_PATH', `The Skill destination overlaps its package or CLI state: ${target.path}`, { exit: EXIT_CODES.validation });
+    await safePath(target.path);
+    const ready = await reusable(target, environment, source, registry);
+    if (ready !== undefined)
+        return ready;
+    return lock(path.join(path.dirname(target.path), '.nb-studio-cli.lock'), async () => {
+        await safePath(target.path);
+        const ready = await reusable(target, environment, source, registry);
+        if (ready !== undefined)
+            return ready;
+        const before = await statusOf(target, environment, source, registry);
+        if (before.error)
+            throw new CliCommandError('SKILLS_UNSAFE_PATH', before.error, {
+                exit: EXIT_CODES.validation,
+            });
+        const action = before.upToDate
+            ? 'unchanged'
+            : before.present
+                ? 'update'
+                : 'install';
+        const record = {
+            ...target,
+            cliVersion: environment.cliVersion,
+            hash: source.hash,
+        };
+        const next = {
+            version: 2,
+            targets: [
+                ...registry.targets.filter((item) => path.resolve(item.path) !== path.resolve(target.path)),
+                record,
+            ],
+        };
+        if (action === 'unchanged')
+            await writeRegistry(environment, next);
+        else {
+            const temporary = await mkdtemp(path.join(path.dirname(target.path), '.nb-studio-cli-stage-'));
+            const staged = path.join(temporary, target.skill);
+            const backup = path.join(temporary, 'previous');
+            let moved = false;
+            let activated = false;
+            let committed = false;
+            try {
+                await mkdir(staged);
+                for (const entry of source.entries) {
+                    const file = path.join(staged, ...entry.name.split('/'));
+                    if (entry.bytes === undefined)
+                        await mkdir(file);
+                    else
+                        await writeFile(file, entry.bytes);
+                }
+                await safePath(target.path);
+                if (before.present) {
+                    await rename(target.path, backup);
+                    moved = true;
+                }
+                await rename(staged, target.path);
+                activated = true;
+                await writeRegistry(environment, next);
+                committed = true;
+            }
+            catch (error) {
+                try {
+                    if (activated)
+                        await rm(target.path, { recursive: true, force: true });
+                    if (moved) {
+                        await rename(backup, target.path);
+                        moved = false;
+                    }
+                }
+                catch (recovery) {
+                    throw new CliCommandError('SKILLS_RECOVERY_FAILED', `Skill replacement failed and recovery needs help. The previous copy is at ${backup}: ${recovery instanceof Error ? recovery.message : String(recovery)}`, {
+                        details: {
+                            cause: error instanceof Error ? error.message : String(error),
+                            backup,
+                        },
+                    });
+                }
+                throw error;
+            }
+            finally {
+                // If rollback itself fails, keep the backup for recovery rather than deleting the old copy.
+                if (committed || !moved)
+                    await rm(temporary, { recursive: true, force: true }).catch(() => undefined);
+            }
+        }
+        registry.targets = next.targets;
+        return {
+            ...before,
+            action,
+            present: true,
+            upToDate: true,
+            registered: true,
+            installedCliVersion: environment.cliVersion,
+        };
+    });
+}
+async function reusable(target, environment, source, registry) {
+    const record = registry.targets.find((record) => path.resolve(record.path) === path.resolve(target.path));
+    if (record?.tool !== target.tool ||
+        record.hash !== source.hash ||
+        record.cliVersion !== environment.cliVersion)
+        return undefined;
+    const status = await statusOf(target, environment, source, registry);
+    if (!status.upToDate || status.error)
+        return undefined;
+    return { ...status, action: 'unchanged' };
+}
+/** Replaces only the Skills the package ships and registers successful installations for self-update. */
+export async function installSkills(environment, tools = [], dryRun = false) {
+    const sources = await bundledAll(environment);
+    let selected = selection(tools);
+    if (selected.length === 0)
+        selected = (await Promise.all(TOOLS.map(async (tool) => (await detected(tool, environment)) ? tool : undefined))).filter((tool) => tool !== undefined);
+    if (selected.length === 0)
+        throw new CliCommandError('SKILLS_NO_TOOL', 'No Claude Code or Codex installation was detected. Choose a tool explicitly.', {
+            exit: EXIT_CODES.validation,
+            suggestions: TOOLS.map((tool) => ({
+                message: `Install for ${tool}.`,
+                run: {
+                    command: environment.bin,
+                    args: ['skills', 'install', '--tool', tool],
+                },
+            })),
+        });
+    const targets = unique(locations(environment).defaults.filter((target) => selected.includes(target.tool)));
+    const result = (targets) => ({
+        ...shippedSummary(sources),
+        cliVersion: environment.cliVersion,
+        dryRun,
+        targets,
+    });
+    const perform = async () => {
+        const registry = await readRegistry(environment);
+        requireWritableRegistry(registry, environment);
+        const conflict = targetConflicts([...targets, ...registry.targets])
+            .values()
+            .next().value;
+        if (conflict !== undefined)
+            throw conflict;
+        const results = [];
+        for (const target of targets) {
+            if (overlaps(target.path, environment.packageRoot) ||
+                overlaps(target.path, environment.stateHome))
+                throw new CliCommandError('SKILLS_UNSAFE_PATH', `The Skill destination overlaps its package or CLI state: ${target.path}`, { exit: EXIT_CODES.validation });
+            if (dryRun) {
+                const status = await statusOf(target, environment, sources.get(target.skill), registry);
+                if (status.error)
+                    throw new CliCommandError('SKILLS_UNSAFE_PATH', status.error, {
+                        exit: EXIT_CODES.validation,
+                    });
+                results.push({
+                    ...status,
+                    action: status.upToDate
+                        ? 'unchanged'
+                        : status.present
+                            ? 'update'
+                            : 'install',
+                });
+            }
+            else
+                results.push(await replace(target, environment, sources.get(target.skill), registry));
+        }
+        return result(results);
+    };
+    if (!dryRun) {
+        const registry = await readRegistry(environment);
+        requireWritableRegistry(registry, environment);
+        const conflict = targetConflicts([...targets, ...registry.targets])
+            .values()
+            .next().value;
+        if (conflict !== undefined)
+            throw conflict;
+        const ready = await Promise.all(targets.map(async (target) => {
+            if (overlaps(target.path, environment.packageRoot) ||
+                overlaps(target.path, environment.stateHome))
+                return undefined;
+            return reusable(target, environment, sources.get(target.skill), registry);
+        }));
+        if (ready.every((target) => target !== undefined))
+            return result(ready);
+    }
+    return dryRun
+        ? perform()
+        : lock(path.join(environment.stateHome, '.skills.lock'), perform);
+}
+/** Preserve native Skill installation for the tools with a managed destination. */
+export async function prepareSessionSkill(environment, agentId) {
+    if (TOOLS.some((tool) => tool === agentId)) {
+        try {
+            await installSkills(environment, [agentId]);
+        }
+        catch (error) {
+            if (!(error instanceof CliCommandError) ||
+                error.code !== 'SKILLS_NEWER_REGISTRY')
+                throw error;
+        }
+    }
+}
+/** ACP text is the common fallback; it needs no agent-specific install directory. */
+export async function sessionSkillInstructions(environment, agentId) {
+    if (TOOLS.some((tool) => tool === agentId))
+        return undefined;
+    try {
+        const source = await bundled(environment, SKILL);
+        const skill = source.entries.find((entry) => entry.name === 'SKILL.md');
+        const text = skill.bytes.toString('utf8');
+        if (!text.trim())
+            throw new Error('The packaged Skill is empty.');
+        return [
+            '# Studio session instructions',
+            'The shared nb-studio-cli Skill is supplied below for this session. Follow it directly; no Skill installation is needed.',
+            `Resolve any relative Skill references from ${sourceOf(environment, SKILL)}.`,
+            'Keep the bridge-selected profile and agent session environment. Do not switch identity or remove session context to bypass a refusal.',
+            text,
+            '# Current message',
+        ].join('\n\n');
+    }
+    catch (cause) {
+        throw new Error(`Could not load the packaged nb-studio-cli instructions. Update or reinstall ${environment.bin}, then restart the bridge and resend the message.`, { cause });
+    }
+}
+// A Skill the new package no longer ships. Only a copy we registered whose content still matches what we wrote is
+// removed; an edited copy is kept with a warning, and either way the record is dropped so the warning is not repeated.
+async function retire(record, environment) {
+    await safePath(record.path);
+    if ((await stat(record.path)) === undefined)
+        return { action: 'removed' };
+    if (overlaps(record.path, environment.packageRoot) ||
+        overlaps(record.path, environment.stateHome) ||
+        (await snapshot(record.path)).hash !== record.hash)
+        return {
+            action: 'kept',
+            message: `The ${record.skill} Skill is no longer shipped; its copy at ${record.path} was changed or cannot be removed safely, so it was left in place.`,
+        };
+    await rm(record.path, { recursive: true });
+    return { action: 'removed' };
+}
+/** Called after CLI activation, reading the new package. Failures are warnings, never CLI update failures. */
+export async function syncInstalledSkills(environment) {
+    const warnings = [];
+    const targets = [];
+    const advise = (message) => {
+        warnings.push(`${message} Run \`${environment.bin} skills install\` (use --tool claude or --tool codex to select explicitly).`);
+    };
+    try {
+        // Do not create state or tool directories on machines that never installed this Skill.
+        const registry = await readRegistry(environment);
+        requireWritableRegistry(registry, environment);
+        const shipped = shippedSkills(environment.packageRoot);
+        const { defaults, legacy } = locations(environment, shipped);
+        for (const target of unique([...defaults, ...legacy])) {
+            try {
+                if ((await stat(target.path)) !== undefined &&
+                    !registry.targets.some((record) => path.resolve(record.path) === path.resolve(target.path)))
+                    advise(`An unregistered ${target.skill} copy at ${target.path} was left unchanged.`);
+            }
+            catch (error) {
+                advise(`Could not inspect the Skill location ${target.path}: ${error instanceof Error ? error.message : String(error)}.`);
+            }
+        }
+        if (registry.targets.length > 0)
+            await lock(path.join(environment.stateHome, '.skills.lock'), async () => {
+                const current = await readRegistry(environment);
+                requireWritableRegistry(current, environment);
+                const kept = current.targets.filter((target) => shipped.includes(target.skill));
+                const dropped = current.targets.filter((target) => !shipped.includes(target.skill));
+                const destinations = unique(kept);
+                const conflicts = targetConflicts(destinations);
+                // Read each source inside its attempt so every registered target has a failure result if it is missing.
+                for (const target of destinations) {
+                    try {
+                        const conflict = conflicts.get(target.path);
+                        if (conflict !== undefined)
+                            throw conflict;
+                        const result = await replace(target, environment, await bundled(environment, target.skill), current);
+                        targets.push({
+                            skill: target.skill,
+                            tool: target.tool,
+                            path: target.path,
+                            action: result.action === 'unchanged' ? 'unchanged' : 'updated',
+                        });
+                    }
+                    catch (error) {
+                        const message = error instanceof Error ? error.message : String(error);
+                        targets.push({
+                            skill: target.skill,
+                            tool: target.tool,
+                            path: target.path,
+                            action: 'failed',
+                            error: message,
+                        });
+                        advise(`Could not update ${target.skill} at ${target.path}: ${message}.`);
+                    }
+                }
+                if (dropped.length === 0)
+                    return;
+                const retired = new Set();
+                for (const record of dropped) {
+                    try {
+                        const outcome = await retire(record, environment);
+                        retired.add(record);
+                        targets.push({
+                            skill: record.skill,
+                            tool: record.tool,
+                            path: record.path,
+                            action: outcome.action,
+                        });
+                        if (outcome.message !== undefined)
+                            warnings.push(outcome.message);
+                    }
+                    catch (error) {
+                        const message = error instanceof Error ? error.message : String(error);
+                        targets.push({
+                            skill: record.skill,
+                            tool: record.tool,
+                            path: record.path,
+                            action: 'failed',
+                            error: message,
+                        });
+                        warnings.push(`Could not remove the retired ${record.skill} Skill at ${record.path}: ${message}.`);
+                    }
+                }
+                // Re-read: replace() rewrote the record for each updated target.
+                const latest = await readRegistry(environment);
+                requireWritableRegistry(latest, environment);
+                await writeRegistry(environment, {
+                    version: 2,
+                    targets: latest.targets.filter((target) => ![...retired].some((gone) => gone.path === target.path)),
+                });
+            });
+    }
+    catch (error) {
+        if (error instanceof CliCommandError &&
+            error.code === 'SKILLS_NEWER_REGISTRY')
+            warnings.push(error.message);
+        else
+            advise(`Could not synchronize installed Skills: ${error instanceof Error ? error.message : String(error)}.`);
+    }
+    return { targets, warnings };
+}
+export function skillsCommands(app) {
+    const flags = {
+        tool: Flags.string({
+            description: 'Choose claude, codex, or all; repeat to choose multiple tools.',
+            options: ['claude', 'codex', 'all'],
+            multiple: true,
+        }),
+    };
+    class Install extends AppCommand {
+        toSuccessJson(result) {
+            return super.toSuccessJson({ data: result });
+        }
+        static summary = 'Install the Skills packaged with this CLI in local agent tools.';
+        static supportsDryRun = true;
+        static flags = flags;
+        async run() {
+            const { flags } = await this.parse(Install);
+            if (findRunCredentials(process.cwd(), app) !== undefined)
+                throw new CliCommandError('SKILLS_RUN_FORBIDDEN', 'The runner already supplies these Skills. Install it outside an agent run.', { exit: EXIT_CODES.auth });
+            const result = await installSkills(skillsEnvironment(app), flags.tool, this.dryRun);
+            for (const target of result.targets)
+                this.log(`${this.dryRun ? 'Would ' : ''}${target.action}: ${target.skill} ${target.tool} ${target.path}`);
+            return result;
+        }
+    }
+    class Status extends AppCommand {
+        toSuccessJson(result) {
+            return super.toSuccessJson({ data: result });
+        }
+        static summary = 'Compare local copies with the Skills packaged with this CLI.';
+        static flags = flags;
+        async run() {
+            const { flags } = await this.parse(Status);
+            const result = await skillsStatus(skillsEnvironment(app), flags.tool);
+            for (const target of result.targets)
+                this.log(`${target.skill} ${target.tool} ${target.path}: ${target.error ?? (target.present ? (target.dropped ? 'no longer shipped' : target.upToDate ? 'up to date' : 'outdated') : 'not installed')}${target.legacy ? ' (legacy)' : ''}${target.registered ? ' (registered)' : ''}`);
+            return result;
+        }
+    }
+    return { 'skills:install': Install, 'skills:status': Status };
+}
+//# sourceMappingURL=skills.js.map