@controllerai/cli 0.2.0

package/dist/commands/skills.js

@@ -0,0 +1,1156 @@
+import { createHash } from 'node:crypto';
+import { existsSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, realpathSync, readdirSync, renameSync, rmdirSync, rmSync, writeFileSync, } from 'node:fs';
+import { homedir } from 'node:os';
+import { basename, dirname, join, relative, resolve, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { CaiError, networkError, userError } from '../errors.js';
+import { emit, printKeyValues, printTable, warn } from '../output.js';
+import { CLI_VERSION } from '../version.js';
+export const PUBLIC_SKILLS = [
+    'controllerai-start',
+    'controllerai-workflows',
+    'controllerai-node-config',
+    'controllerai-expressions',
+    'controllerai-flow-control',
+    'controllerai-runs',
+    'controllerai-triggers',
+    'controllerai-data',
+    'controllerai-ai-nodes',
+    'controllerai-integration-actions',
+    'controllerai-agents',
+];
+export const DEFAULT_SKILLS_MANIFEST_URL = 'https://getcontroller.ai/skills/manifest.json';
+export const SKILL_UPDATE_FALLBACK_CODES = [
+    'SKILLS_NETWORK_UNAVAILABLE',
+    'SKILLS_HTTP_UNAVAILABLE',
+];
+const skillUpdateFallbackCodeSet = new Set(SKILL_UPDATE_FALLBACK_CODES);
+const MARKER = '.controllerai-managed';
+const MAX_MANIFEST_SIZE = 256 * 1024;
+const MAX_SKILL_FILE_SIZE = 1024 * 1024;
+const MAX_SKILL_SET_SIZE = 5 * 1024 * 1024;
+const FETCH_TIMEOUT_MS = 5_000;
+const moduleDir = dirname(fileURLToPath(import.meta.url));
+const isRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+const sha256 = (bytes) => createHash('sha256').update(bytes).digest('hex');
+const safeRelativePath = (value, label) => {
+    if (typeof value !== 'string' || !value || value.includes('\\') || value.startsWith('/')) {
+        throw userError(`${label} must be a non-empty relative POSIX path.`, 'INVALID_SKILLS_MANIFEST');
+    }
+    const parts = value.split('/');
+    if (parts.some(part => !part ||
+        part === '.' ||
+        part === '..' ||
+        part.includes('\0') ||
+        !/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(part))) {
+        throw userError(`${label} contains an unsafe path segment.`, 'INVALID_SKILLS_MANIFEST');
+    }
+    return value;
+};
+export const validateSkillsUrl = (value, label = 'Skills URL') => {
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        throw userError(`${label} must be an absolute URL.`, 'UNSAFE_SKILLS_URL');
+    }
+    const hostname = url.hostname.toLowerCase();
+    const loopback = ['localhost', '127.0.0.1', '[::1]', '::1'].includes(hostname);
+    if (url.protocol !== 'https:' && !(url.protocol === 'http:' && loopback)) {
+        throw userError(`${label} must use HTTPS (loopback HTTP is allowed for tests).`, 'UNSAFE_SKILLS_URL');
+    }
+    if (url.username || url.password || url.search || url.hash) {
+        throw userError(`${label} must not contain credentials, a query, or a fragment.`, 'UNSAFE_SKILLS_URL');
+    }
+    return url.toString();
+};
+const parseSemver = (value, label) => {
+    const match = value.match(/^v?(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-([0-9A-Za-z.-]+))?(?:\+[0-9A-Za-z.-]+)?$/);
+    if (!match) {
+        throw userError(`${label} must be a semantic version.`, 'INVALID_SKILLS_MANIFEST');
+    }
+    return {
+        numbers: [Number(match[1]), Number(match[2]), Number(match[3])],
+        prerelease: match[4]?.split('.') ?? [],
+    };
+};
+const compareSemver = (left, right) => {
+    const a = parseSemver(left, 'CLI version');
+    const b = parseSemver(right, 'Minimum CLI version');
+    for (let index = 0; index < 3; index += 1) {
+        if (a.numbers[index] !== b.numbers[index])
+            return a.numbers[index] - b.numbers[index];
+    }
+    if (a.prerelease.length === 0 && b.prerelease.length > 0)
+        return 1;
+    if (b.prerelease.length === 0 && a.prerelease.length > 0)
+        return -1;
+    const count = Math.max(a.prerelease.length, b.prerelease.length);
+    for (let index = 0; index < count; index += 1) {
+        const av = a.prerelease[index];
+        const bv = b.prerelease[index];
+        if (av === undefined)
+            return -1;
+        if (bv === undefined)
+            return 1;
+        if (av === bv)
+            continue;
+        const an = /^\d+$/.test(av) ? Number(av) : undefined;
+        const bn = /^\d+$/.test(bv) ? Number(bv) : undefined;
+        if (an !== undefined && bn !== undefined)
+            return an - bn;
+        if (an !== undefined)
+            return -1;
+        if (bn !== undefined)
+            return 1;
+        return av.localeCompare(bv);
+    }
+    return 0;
+};
+const compareSkillSetVersions = (left, right) => {
+    const parse = (value) => {
+        if (!/^\d+(?:\.\d+)*$/.test(value))
+            return undefined;
+        return value.split('.').map(Number);
+    };
+    const a = parse(left);
+    const b = parse(right);
+    if (!a || !b)
+        return undefined;
+    const count = Math.max(a.length, b.length);
+    for (let index = 0; index < count; index += 1) {
+        const difference = (a[index] ?? 0) - (b[index] ?? 0);
+        if (difference !== 0)
+            return difference;
+    }
+    return 0;
+};
+const skillsManifestContentDigest = (manifest) => sha256(`${manifest.schemaVersion}\0${manifest.skillSetVersion}\0${manifest.minCliVersion}\n` +
+    manifest.skills
+        .flatMap(skill => skill.files.map(file => `${skill.name}\0${file.path}\0${file.sha256}\0${file.size}\n`))
+        .sort()
+        .join(''));
+/** A published version is a content address: changing bytes requires a new version. */
+export const assertImmutableSkillSetVersion = (candidate, trusted) => {
+    if (candidate.skillSetVersion === trusted.skillSetVersion &&
+        skillsManifestContentDigest(candidate) !== skillsManifestContentDigest(trusted)) {
+        throw userError(`Skill set ${candidate.skillSetVersion} was published with different contents. ` +
+            'Controller AI skill-set versions are immutable; publish a new version instead.', 'SKILL_SET_VERSION_CONFLICT');
+    }
+};
+export const validateSkillsManifest = (value, cliVersion = CLI_VERSION) => {
+    if (!isRecord(value) || value.schemaVersion !== 1) {
+        throw userError('Skills manifest schemaVersion must be 1.', 'INVALID_SKILLS_MANIFEST');
+    }
+    if (typeof value.skillSetVersion !== 'string' ||
+        value.skillSetVersion.length > 64 ||
+        !/^[A-Za-z0-9][A-Za-z0-9_-]*(?:\.[A-Za-z0-9][A-Za-z0-9_-]*)*$/.test(value.skillSetVersion)) {
+        throw userError('Skills manifest has an invalid skillSetVersion.', 'INVALID_SKILLS_MANIFEST');
+    }
+    if (typeof value.minCliVersion !== 'string') {
+        throw userError('Skills manifest has no minCliVersion.', 'INVALID_SKILLS_MANIFEST');
+    }
+    parseSemver(value.minCliVersion, 'minCliVersion');
+    if (compareSemver(cliVersion, value.minCliVersion) < 0) {
+        throw userError(`Skill set ${value.skillSetVersion} requires cai ${value.minCliVersion} or newer; ` +
+            `this is cai ${cliVersion}. Upgrade the CLI first.`, 'CLI_TOO_OLD_FOR_SKILLS');
+    }
+    if (!Array.isArray(value.skills)) {
+        throw userError('Skills manifest skills must be an array.', 'INVALID_SKILLS_MANIFEST');
+    }
+    const expected = new Set(PUBLIC_SKILLS);
+    const seenSkills = new Set();
+    const seenPaths = new Set();
+    const seenUrls = new Set();
+    let totalSize = 0;
+    const skills = value.skills.map((candidate, skillIndex) => {
+        if (!isRecord(candidate) || typeof candidate.name !== 'string' || !expected.has(candidate.name)) {
+            throw userError(`Skills manifest entry ${skillIndex} has an unknown skill name.`, 'INVALID_SKILLS_MANIFEST');
+        }
+        if (seenSkills.has(candidate.name)) {
+            throw userError(`Skills manifest repeats ${candidate.name}.`, 'INVALID_SKILLS_MANIFEST');
+        }
+        seenSkills.add(candidate.name);
+        if (!Array.isArray(candidate.files) || candidate.files.length === 0) {
+            throw userError(`${candidate.name} has no files.`, 'INVALID_SKILLS_MANIFEST');
+        }
+        const files = candidate.files.map((file, fileIndex) => {
+            if (!isRecord(file)) {
+                throw userError(`${candidate.name} file ${fileIndex} is invalid.`, 'INVALID_SKILLS_MANIFEST');
+            }
+            const path = safeRelativePath(file.path, `${candidate.name} file path`);
+            if (!path.startsWith(`${candidate.name}/`) || path === `${candidate.name}/`) {
+                throw userError(`${path} must be rooted beneath ${candidate.name}/.`, 'INVALID_SKILLS_MANIFEST');
+            }
+            if (seenPaths.has(path)) {
+                throw userError(`Skills manifest repeats ${path}.`, 'INVALID_SKILLS_MANIFEST');
+            }
+            seenPaths.add(path);
+            if (typeof file.url !== 'string') {
+                throw userError(`${path} has no URL.`, 'INVALID_SKILLS_MANIFEST');
+            }
+            const url = validateSkillsUrl(file.url, `${path} URL`);
+            if (seenUrls.has(url)) {
+                throw userError(`Skills manifest repeats the URL for ${path}.`, 'INVALID_SKILLS_MANIFEST');
+            }
+            seenUrls.add(url);
+            if (typeof file.sha256 !== 'string' || !/^[a-fA-F0-9]{64}$/.test(file.sha256)) {
+                throw userError(`${path} has an invalid SHA-256.`, 'INVALID_SKILLS_MANIFEST');
+            }
+            if (typeof file.size !== 'number' ||
+                !Number.isSafeInteger(file.size) ||
+                file.size < 0 ||
+                file.size > MAX_SKILL_FILE_SIZE) {
+                throw userError(`${path} has an invalid or excessive size.`, 'INVALID_SKILLS_MANIFEST');
+            }
+            totalSize += file.size;
+            return { path, url, sha256: file.sha256.toLowerCase(), size: file.size };
+        });
+        if (!files.some(file => file.path === `${candidate.name}/SKILL.md`)) {
+            throw userError(`${candidate.name} is missing SKILL.md.`, 'INVALID_SKILLS_MANIFEST');
+        }
+        return { name: candidate.name, files };
+    });
+    const missing = PUBLIC_SKILLS.filter(skill => !seenSkills.has(skill));
+    if (missing.length > 0 || seenSkills.size !== PUBLIC_SKILLS.length) {
+        throw userError(`Skills manifest must contain exactly the public skill set; missing: ${missing.join(', ') || 'none'}.`, 'INVALID_SKILLS_MANIFEST');
+    }
+    if (totalSize > MAX_SKILL_SET_SIZE) {
+        throw userError('Skills manifest exceeds the maximum total size.', 'INVALID_SKILLS_MANIFEST');
+    }
+    return {
+        schemaVersion: 1,
+        skillSetVersion: value.skillSetVersion,
+        minCliVersion: value.minCliVersion,
+        skills,
+    };
+};
+export const bundledSkillsRoot = () => {
+    const candidates = [
+        resolve(moduleDir, '..', '..', 'skills'),
+        resolve(moduleDir, '..', '..', '..', '.claude', 'skills'),
+    ];
+    const found = candidates.find(candidate => existsSync(join(candidate, 'manifest.json')) &&
+        existsSync(join(candidate, PUBLIC_SKILLS[0], 'SKILL.md')));
+    if (!found) {
+        throw userError(`Controller AI skills are missing from this installation. Checked: ${candidates.join(', ')}`, 'SKILLS_NOT_BUNDLED');
+    }
+    return found;
+};
+const readJsonBytes = (bytes, label) => {
+    try {
+        return JSON.parse(bytes.toString('utf8'));
+    }
+    catch {
+        throw userError(`${label} is not valid JSON.`, 'INVALID_SKILLS_MANIFEST');
+    }
+};
+export const readBundledSkillsManifest = () => {
+    const manifestPath = join(bundledSkillsRoot(), 'manifest.json');
+    const manifestStat = lstatSync(manifestPath);
+    if (!manifestStat.isFile() || manifestStat.size > MAX_MANIFEST_SIZE) {
+        throw userError('Bundled skills manifest is too large.', 'INVALID_SKILLS_MANIFEST');
+    }
+    const bytes = readFileSync(manifestPath);
+    return validateSkillsManifest(readJsonBytes(bytes, 'Bundled skills manifest'));
+};
+const readBundledSkillSet = () => {
+    const root = bundledSkillsRoot();
+    const manifest = readBundledSkillsManifest();
+    const contents = new Map();
+    for (const skill of manifest.skills) {
+        for (const file of skill.files) {
+            const filePath = join(root, ...file.path.split('/'));
+            const fileStat = lstatSync(filePath);
+            if (!fileStat.isFile() || fileStat.size !== file.size) {
+                throw userError(`Bundled skill file ${file.path} does not match its manifest. Reinstall the CLI.`, 'INVALID_BUNDLED_SKILLS');
+            }
+            const bytes = readFileSync(filePath);
+            if (bytes.length !== file.size || sha256(bytes) !== file.sha256) {
+                throw userError(`Bundled skill file ${file.path} does not match its manifest. Reinstall the CLI.`, 'INVALID_BUNDLED_SKILLS');
+            }
+            contents.set(file.path, bytes);
+        }
+    }
+    return { manifest, contents, source: 'bundled' };
+};
+const readBoundedResponseBody = async (response, maximumSize, label) => {
+    if (!response.body)
+        return Buffer.alloc(0);
+    const reader = response.body.getReader();
+    const chunks = [];
+    let total = 0;
+    try {
+        for (;;) {
+            const chunk = await reader.read();
+            if (chunk.done)
+                break;
+            const bytes = Buffer.from(chunk.value);
+            total += bytes.length;
+            if (total > maximumSize) {
+                try {
+                    await reader.cancel();
+                }
+                catch {
+                    // The integrity failure remains authoritative even if cancellation races a closed body.
+                }
+                throw userError(`${label} exceeds the maximum allowed size.`, 'SKILLS_INTEGRITY_FAILED');
+            }
+            chunks.push(bytes);
+        }
+    }
+    finally {
+        reader.releaseLock();
+    }
+    return Buffer.concat(chunks, total);
+};
+const fetchBytes = async (fetchImpl, url, maximumSize, label) => {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);
+    try {
+        const response = await fetchImpl(url, { signal: controller.signal, redirect: 'manual' });
+        if (response.status >= 300 && response.status < 400) {
+            throw userError(`${label} attempted an HTTP redirect.`, 'UNSAFE_SKILLS_REDIRECT');
+        }
+        if (!response.ok) {
+            throw networkError(`${label} returned HTTP ${response.status}.`, 'SKILLS_HTTP_UNAVAILABLE');
+        }
+        return await readBoundedResponseBody(response, maximumSize, label);
+    }
+    catch (error) {
+        if (error instanceof CaiError)
+            throw error;
+        throw networkError(`${label} could not be downloaded: ${error instanceof Error ? error.message : String(error)}`, 'SKILLS_NETWORK_UNAVAILABLE');
+    }
+    finally {
+        clearTimeout(timer);
+    }
+};
+export const fetchHostedSkillSet = async (manifestUrl = process.env.CAI_SKILLS_MANIFEST_URL ?? DEFAULT_SKILLS_MANIFEST_URL, fetchImpl = fetch) => {
+    const safeManifestUrl = validateSkillsUrl(manifestUrl, 'Skills manifest URL');
+    const manifestBytes = await fetchBytes(fetchImpl, safeManifestUrl, MAX_MANIFEST_SIZE, 'Skills manifest');
+    const manifest = validateSkillsManifest(readJsonBytes(manifestBytes, 'Skills manifest'));
+    const manifestOrigin = new URL(safeManifestUrl).origin;
+    for (const skill of manifest.skills) {
+        for (const file of skill.files) {
+            const fileUrl = new URL(file.url);
+            if (fileUrl.origin !== manifestOrigin) {
+                throw userError(`${file.path} must be hosted on the skills manifest origin (${manifestOrigin}).`, 'UNSAFE_SKILLS_URL');
+            }
+            const expectedPath = `/skills/${manifest.skillSetVersion}/${file.path}`;
+            if (fileUrl.pathname !== expectedPath) {
+                throw userError(`${file.path} URL must use the versioned path ${expectedPath}.`, 'UNSAFE_SKILLS_URL');
+            }
+        }
+    }
+    const contents = new Map();
+    await Promise.all(manifest.skills.flatMap(skill => skill.files.map(async (file) => {
+        const bytes = await fetchBytes(fetchImpl, file.url, file.size, file.path);
+        if (bytes.length !== file.size) {
+            throw userError(`${file.path} size does not match the manifest.`, 'SKILLS_INTEGRITY_FAILED');
+        }
+        if (sha256(bytes) !== file.sha256) {
+            throw userError(`${file.path} SHA-256 does not match the manifest.`, 'SKILLS_INTEGRITY_FAILED');
+        }
+        contents.set(file.path, bytes);
+    })));
+    return { manifest, contents, source: 'hosted', manifestUrl: safeManifestUrl };
+};
+const directoryIdentity = (directory) => {
+    let cursor = resolve(directory);
+    const missingSegments = [];
+    for (;;) {
+        try {
+            return join(realpathSync(cursor), ...missingSegments);
+        }
+        catch {
+            const parent = dirname(cursor);
+            if (parent === cursor)
+                return resolve(directory);
+            missingSegments.unshift(basename(cursor));
+            cursor = parent;
+        }
+    }
+};
+const dedupeDirectories = (rows) => {
+    const seen = new Set();
+    return rows.filter(row => {
+        const key = directoryIdentity(row.directory);
+        if (seen.has(key))
+            return false;
+        seen.add(key);
+        return true;
+    });
+};
+export const skillTargetDirectories = (target, projectDir = process.cwd(), home = homedir(), codexHome = process.env.CODEX_HOME ?? join(home, '.codex')) => {
+    const candidates = [
+        {
+            target: 'codex',
+            homeDirectory: codexHome,
+            skillsDirectory: join(codexHome, 'skills'),
+        },
+        {
+            target: 'claude',
+            homeDirectory: join(home, '.claude'),
+            skillsDirectory: join(home, '.claude', 'skills'),
+        },
+        {
+            target: 'cursor',
+            homeDirectory: join(home, '.cursor'),
+            skillsDirectory: join(home, '.cursor', 'skills'),
+        },
+        {
+            target: 'copilot',
+            homeDirectory: join(home, '.copilot'),
+            skillsDirectory: join(home, '.copilot', 'skills'),
+        },
+        {
+            target: 'agents',
+            homeDirectory: join(home, '.agents'),
+            skillsDirectory: join(home, '.agents', 'skills'),
+        },
+    ];
+    if (target === 'auto') {
+        const detected = candidates.filter(candidate => ['codex', 'claude', 'cursor', 'copilot'].includes(candidate.target)
+            ? existsSync(candidate.homeDirectory)
+            : false);
+        const selected = detected.length > 0 ? detected : candidates.filter(row => row.target === 'agents');
+        return dedupeDirectories(selected.map(row => ({ target: row.target, directory: row.skillsDirectory })));
+    }
+    if (target === 'all') {
+        return dedupeDirectories(candidates.map(row => ({ target: row.target, directory: row.skillsDirectory })));
+    }
+    const selected = candidates.find(candidate => candidate.target === target);
+    if (selected)
+        return [{ target: selected.target, directory: selected.skillsDirectory }];
+    if (target === 'project') {
+        return [{ target: 'project', directory: join(resolve(projectDir), '.agents', 'skills') }];
+    }
+    return [];
+};
+const markerFilesForSkill = (skill) => skill.files
+    .map(file => ({
+    path: file.path.slice(skill.name.length + 1),
+    sha256: file.sha256,
+    size: file.size,
+}))
+    .sort((left, right) => left.path.localeCompare(right.path));
+const digestMarkerFiles = (files) => sha256(files.map(file => `${file.path}\0${file.sha256}\0${file.size}\n`).join(''));
+/** Unlike existsSync, this treats dangling symbolic links as existing directory entries. */
+const pathExistsLexically = (path) => {
+    try {
+        lstatSync(path);
+        return true;
+    }
+    catch (error) {
+        if (isRecord(error) && error.code === 'ENOENT')
+            return false;
+        throw error;
+    }
+};
+const hasControllerManagedMarker = (skillDirectory) => {
+    try {
+        const markerPath = join(skillDirectory, MARKER);
+        const markerStat = lstatSync(markerPath);
+        if (!markerStat.isFile() || markerStat.size > MAX_MANIFEST_SIZE)
+            return false;
+        const marker = JSON.parse(readFileSync(markerPath, 'utf8'));
+        return isRecord(marker) && marker.package === '@controllerai/cli';
+    }
+    catch {
+        return false;
+    }
+};
+const isControllerManagedSkillDirectory = (path) => {
+    try {
+        // A symlink is never owned by this installer, even when its target happens
+        // to contain a Controller AI marker.
+        if (!lstatSync(path).isDirectory())
+            return false;
+        return hasControllerManagedMarker(path);
+    }
+    catch {
+        return false;
+    }
+};
+const assertReplaceableSkillOutput = (output, force = false) => {
+    if (pathExistsLexically(output) &&
+        !isControllerManagedSkillDirectory(output) &&
+        !force) {
+        throw userError(`${output} already exists and is not managed by Controller AI. ` +
+            'Move it, or rerun with --force to replace it.', 'UNMANAGED_SKILL_EXISTS');
+    }
+};
+const writeStagedSkill = (stagingRoot, skill, skillSet, installedAt) => {
+    const output = join(stagingRoot, skill.name);
+    const files = markerFilesForSkill(skill);
+    const digest = digestMarkerFiles(files);
+    for (const file of skill.files) {
+        const relativePath = file.path.slice(skill.name.length + 1);
+        const destination = join(output, ...relativePath.split('/'));
+        const bytes = skillSet.contents.get(file.path);
+        if (!bytes) {
+            throw userError(`Skill source is missing ${file.path}.`, 'INCOMPLETE_SKILL_SOURCE');
+        }
+        mkdirSync(dirname(destination), { recursive: true });
+        writeFileSync(destination, bytes, { mode: 0o644 });
+    }
+    const marker = {
+        schemaVersion: 1,
+        package: '@controllerai/cli',
+        skill: skill.name,
+        installedAt,
+        skillSetVersion: skillSet.manifest.skillSetVersion,
+        digest,
+        files,
+        source: skillSet.source,
+        ...(skillSet.manifestUrl ? { manifestUrl: skillSet.manifestUrl } : {}),
+    };
+    writeFileSync(join(output, MARKER), `${JSON.stringify(marker, null, 2)}\n`, { mode: 0o600 });
+    return { digest };
+};
+/**
+ * True only when the occupant's marker proves it is the copy THIS run staged.
+ * (dev, ino) alone is not a safe identity: Linux filesystems eagerly reuse
+ * inode numbers, so a directory created moments after ours was deleted can
+ * carry the same numbers. The marker's per-run installedAt + content digest
+ * cannot be inherited that way.
+ */
+const occupantIsInstalledStage = (output, identity) => {
+    const outputStat = lstatSync(output);
+    if (outputStat.dev !== identity.dev || outputStat.ino !== identity.ino)
+        return false;
+    try {
+        const marker = JSON.parse(readFileSync(join(output, MARKER), 'utf8'));
+        return marker.installedAt === identity.installedAt && marker.digest === identity.digest;
+    }
+    catch {
+        return false;
+    }
+};
+const removeNewEmptyDestination = (prepared) => {
+    if (prepared.directoryExisted)
+        return;
+    try {
+        rmdirSync(prepared.destination.directory);
+    }
+    catch {
+        // A parent may now contain user-created content; never remove it recursively.
+    }
+};
+const prepareDestination = (destination, skillSet, fileOperations = {}) => {
+    const directoryExisted = existsSync(destination.directory);
+    let stagingRoot;
+    let backupRoot;
+    const installedAt = new Date().toISOString();
+    const digests = new Map();
+    try {
+        mkdirSync(destination.directory, { recursive: true });
+        stagingRoot = mkdtempSync(join(destination.directory, '.controllerai-stage-'));
+        backupRoot = mkdtempSync(join(destination.directory, '.controllerai-backup-'));
+        for (const skill of skillSet.manifest.skills) {
+            digests.set(skill.name, writeStagedSkill(stagingRoot, skill, skillSet, installedAt).digest);
+        }
+        return {
+            destination,
+            directoryExisted,
+            stagingRoot,
+            backupRoot,
+            digests,
+            installedAt,
+            renamePath: fileOperations.rename ?? renameSync,
+            removeTree: fileOperations.removeTree ??
+                (path => {
+                    rmSync(path, { recursive: true, force: true });
+                }),
+            swaps: [],
+        };
+    }
+    catch (error) {
+        if (stagingRoot)
+            rmSync(stagingRoot, { recursive: true, force: true });
+        if (backupRoot)
+            rmSync(backupRoot, { recursive: true, force: true });
+        if (!directoryExisted) {
+            try {
+                rmdirSync(destination.directory);
+            }
+            catch {
+                // mkdirSync may have failed before creating the destination.
+            }
+        }
+        throw error;
+    }
+};
+const commitDestination = (prepared, skillSet, force = false) => {
+    for (const skill of skillSet.manifest.skills) {
+        const output = join(prepared.destination.directory, skill.name);
+        const stagedPath = join(prepared.stagingRoot, skill.name);
+        const stagedStat = lstatSync(stagedPath);
+        // Preflight happened before staging. Revalidate ownership at the last
+        // possible moment so a newly-created unmanaged occupant is never moved.
+        assertReplaceableSkillOutput(output, force);
+        const backup = pathExistsLexically(output)
+            ? join(prepared.backupRoot, skill.name)
+            : undefined;
+        const swap = {
+            output,
+            backup,
+            stagedInstalled: false,
+            stagedIdentity: {
+                dev: stagedStat.dev,
+                ino: stagedStat.ino,
+                installedAt: prepared.installedAt,
+                digest: prepared.digests.get(skill.name) ?? '',
+            },
+        };
+        // Journal the backup before the risky staged rename. If that rename fails,
+        // rollback still knows where the original copy lives.
+        prepared.swaps.push(swap);
+        if (backup)
+            prepared.renamePath(output, backup);
+        prepared.renamePath(stagedPath, output);
+        swap.stagedInstalled = true;
+    }
+};
+const rollbackDestination = (prepared) => {
+    const failures = [];
+    try {
+        for (const swap of [...prepared.swaps].reverse()) {
+            try {
+                if (swap.stagedInstalled && pathExistsLexically(swap.output)) {
+                    const isInstalledStage = occupantIsInstalledStage(swap.output, swap.stagedIdentity);
+                    if (!isInstalledStage) {
+                        if (swap.backup) {
+                            throw new Error(`refusing to remove an unexpected occupant at ${swap.output}`);
+                        }
+                    }
+                    else {
+                        prepared.removeTree(swap.output);
+                    }
+                }
+                if (swap.backup && pathExistsLexically(swap.backup)) {
+                    if (pathExistsLexically(swap.output)) {
+                        throw new Error(`refusing to overwrite an unexpected occupant at ${swap.output}`);
+                    }
+                    prepared.renamePath(swap.backup, swap.output);
+                }
+            }
+            catch (error) {
+                failures.push(error instanceof Error ? error.message : String(error));
+            }
+        }
+        if (failures.length === 0)
+            prepared.swaps.length = 0;
+    }
+    finally {
+        try {
+            prepared.removeTree(prepared.stagingRoot);
+        }
+        catch (error) {
+            failures.push(`could not remove staging directory ${prepared.stagingRoot}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        if (failures.length === 0) {
+            try {
+                prepared.removeTree(prepared.backupRoot);
+            }
+            catch (error) {
+                failures.push(`could not remove backup directory ${prepared.backupRoot}: ${error instanceof Error ? error.message : String(error)}`);
+            }
+        }
+        removeNewEmptyDestination(prepared);
+    }
+    if (failures.length > 0) {
+        throw userError(`Could not restore a previous skill installation; recoverable backups remain at ` +
+            `${prepared.backupRoot}: ${failures.join('; ')}`, 'SKILLS_ROLLBACK_RESTORE_FAILED');
+    }
+};
+const finalizeDestination = (prepared) => {
+    const warnings = [];
+    for (const [label, path] of [
+        ['staging', prepared.stagingRoot],
+        ['backup', prepared.backupRoot],
+    ]) {
+        try {
+            prepared.removeTree(path);
+        }
+        catch (error) {
+            warnings.push(`Skills were installed, but the temporary ${label} directory could not be removed; ` +
+                `it remains at ${path}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    return warnings;
+};
+const installedRows = (prepared, skillSet) => skillSet.manifest.skills.map(skill => {
+    const path = join(prepared.destination.directory, skill.name);
+    return {
+        target: prepared.destination.target,
+        skill: skill.name,
+        path,
+        skillFile: join(path, 'SKILL.md'),
+        skillSetVersion: skillSet.manifest.skillSetVersion,
+        digest: prepared.digests.get(skill.name),
+        source: skillSet.source,
+    };
+});
+const assertSkillTarget = (target) => {
+    if (!['auto', 'agents', 'codex', 'claude', 'cursor', 'copilot', 'all', 'project'].includes(target)) {
+        throw userError('--target must be auto, agents, codex, claude, cursor, copilot, all, or project.', 'BAD_SKILL_TARGET');
+    }
+};
+const createSkillInstallResult = (value) => {
+    const retained = value.retained ?? [];
+    const updated = value.installed;
+    const available = [...updated, ...retained];
+    return {
+        ...value,
+        updateSkillSetVersion: value.skillSetVersion,
+        updateSource: value.source,
+        installed: updated,
+        updated,
+        retained,
+        available,
+        availableSkillSetVersions: [...new Set(available.map(row => row.skillSetVersion))],
+        availableSkillSources: [...new Set(available.map(row => row.source))],
+        availableSkillCount: available.length,
+        updatedSkillCount: updated.length,
+        retainedSkillCount: retained.length,
+    };
+};
+const installSkillSet = (skillSet, opts, selectedDestinations) => {
+    const target = opts.target ?? 'auto';
+    assertSkillTarget(target);
+    const home = opts.homeDir ?? homedir();
+    const codexHome = opts.codexHome ?? process.env.CODEX_HOME ?? join(home, '.codex');
+    const allDestinations = skillTargetDirectories(target, opts.projectDir, home, codexHome);
+    const destinations = selectedDestinations ?? allDestinations;
+    // Preflight every collision across every target before changing anything.
+    for (const destination of destinations) {
+        for (const skill of PUBLIC_SKILLS) {
+            const output = join(destination.directory, skill);
+            assertReplaceableSkillOutput(output, opts.force);
+            assertInstalledSkillVersionImmutable(output, skill, skillSet.manifest.skills.find(candidate => candidate.name === skill), skillSet.manifest.skillSetVersion);
+        }
+    }
+    const prepared = [];
+    try {
+        for (const destination of destinations) {
+            prepared.push(prepareDestination(destination, skillSet, opts.fileOperations));
+        }
+        opts.afterPrepare?.(destinations);
+        for (const destination of prepared)
+            commitDestination(destination, skillSet, opts.force);
+    }
+    catch (error) {
+        const rollbackFailures = [];
+        for (const destination of [...prepared].reverse()) {
+            try {
+                rollbackDestination(destination);
+            }
+            catch (candidate) {
+                rollbackFailures.push({
+                    target: destination.destination.target,
+                    directory: destination.destination.directory,
+                    backupRoot: destination.backupRoot,
+                    ...(candidate instanceof CaiError ? { code: candidate.code } : {}),
+                    message: candidate instanceof Error ? candidate.message : String(candidate),
+                });
+            }
+        }
+        if (rollbackFailures.length > 0) {
+            throw new CaiError(`Skill installation failed and rollback was incomplete for ${rollbackFailures.length} ` +
+                `destination${rollbackFailures.length === 1 ? '' : 's'}:\n${rollbackFailures
+                    .map(failure => `- ${failure.target} (${failure.directory}): recoverable backup at ` +
+                    `${failure.backupRoot}; ${failure.message}`)
+                    .join('\n')}`, {
+                code: 'SKILLS_ROLLBACK_FAILED',
+                detail: {
+                    installationError: error instanceof Error ? error.message : String(error),
+                    rollbackFailures,
+                },
+            });
+        }
+        throw error;
+    }
+    const installed = prepared.flatMap(destination => installedRows(destination, skillSet));
+    const cleanupWarnings = prepared.flatMap(finalizeDestination);
+    return createSkillInstallResult({
+        skillSetVersion: skillSet.manifest.skillSetVersion,
+        source: skillSet.source,
+        ...(skillSet.manifestUrl ? { manifestUrl: skillSet.manifestUrl } : {}),
+        installed,
+        removedLegacyPaths: [],
+        migrationWarnings: [],
+        cleanupWarnings,
+    });
+};
+export const installSkills = (opts = {}) => installSkillSet(readBundledSkillSet(), opts);
+export const updateSkills = async (opts = {}) => {
+    assertSkillTarget(opts.target ?? 'auto');
+    const manifestUrl = opts.manifestUrl ?? process.env.CAI_SKILLS_MANIFEST_URL ?? DEFAULT_SKILLS_MANIFEST_URL;
+    let skillSet;
+    try {
+        skillSet = await fetchHostedSkillSet(manifestUrl, opts.fetchImpl ?? fetch);
+        assertImmutableSkillSetVersion(skillSet.manifest, readBundledSkillSet().manifest);
+    }
+    catch (error) {
+        if (opts.fallbackToBundled === false)
+            throw error;
+        if (!(error instanceof CaiError) || !skillUpdateFallbackCodeSet.has(error.code)) {
+            throw error;
+        }
+        const warning = `Hosted skill update was unavailable (${error instanceof Error ? error.message : String(error)}). ` +
+            'Intact current or newer managed skill sets will be retained; the verified bundled set ' +
+            'will be installed only where retention is impossible.';
+        (opts.onWarning ?? warn)(warning);
+        skillSet = readBundledSkillSet();
+        return installAvailabilityFallback(skillSet, opts);
+    }
+    return installSkillSet(skillSet, opts);
+};
+const filesUnder = (directory, root = directory) => readdirSync(directory, { withFileTypes: true }).flatMap(entry => {
+    const path = join(directory, entry.name);
+    if (entry.isDirectory())
+        return filesUnder(path, root);
+    return [relative(root, path).split(sep).join('/')];
+});
+const parseManagedMarker = (path, skill) => {
+    let value;
+    try {
+        const markerStat = lstatSync(path);
+        if (!markerStat.isFile() || markerStat.size > MAX_MANIFEST_SIZE)
+            return { kind: 'invalid' };
+        const bytes = readFileSync(path);
+        value = JSON.parse(bytes.toString('utf8'));
+    }
+    catch {
+        return { kind: 'invalid' };
+    }
+    if (!isRecord(value) || value.package !== '@controllerai/cli')
+        return { kind: 'invalid' };
+    if (value.schemaVersion !== 1 || value.skillSetVersion === undefined || value.digest === undefined) {
+        return { kind: 'legacy' };
+    }
+    if (value.skill !== skill ||
+        typeof value.installedAt !== 'string' ||
+        typeof value.skillSetVersion !== 'string' ||
+        typeof value.digest !== 'string' ||
+        !/^[a-f0-9]{64}$/.test(value.digest) ||
+        !Array.isArray(value.files) ||
+        !['bundled', 'hosted'].includes(String(value.source))) {
+        return { kind: 'invalid' };
+    }
+    const seen = new Set();
+    const files = [];
+    try {
+        for (const candidate of value.files) {
+            if (!isRecord(candidate))
+                return { kind: 'invalid' };
+            const filePath = safeRelativePath(candidate.path, 'Managed skill file path');
+            if (seen.has(filePath))
+                return { kind: 'invalid' };
+            seen.add(filePath);
+            if (typeof candidate.sha256 !== 'string' ||
+                !/^[a-f0-9]{64}$/.test(candidate.sha256) ||
+                typeof candidate.size !== 'number' ||
+                !Number.isSafeInteger(candidate.size) ||
+                candidate.size < 0 ||
+                candidate.size > MAX_SKILL_FILE_SIZE) {
+                return { kind: 'invalid' };
+            }
+            files.push({ path: filePath, sha256: candidate.sha256, size: candidate.size });
+        }
+    }
+    catch {
+        return { kind: 'invalid' };
+    }
+    files.sort((left, right) => left.path.localeCompare(right.path));
+    if (!seen.has('SKILL.md') || digestMarkerFiles(files) !== value.digest) {
+        return { kind: 'invalid' };
+    }
+    return {
+        kind: 'current',
+        marker: {
+            schemaVersion: 1,
+            package: '@controllerai/cli',
+            skill,
+            installedAt: value.installedAt,
+            skillSetVersion: value.skillSetVersion,
+            digest: value.digest,
+            files,
+            source: value.source,
+            ...(typeof value.manifestUrl === 'string' ? { manifestUrl: value.manifestUrl } : {}),
+        },
+    };
+};
+function assertInstalledSkillVersionImmutable(output, skill, incoming, incomingVersion) {
+    if (!isControllerManagedSkillDirectory(output))
+        return;
+    const parsed = parseManagedMarker(join(output, MARKER), skill);
+    if (parsed.kind !== 'current' || parsed.marker.skillSetVersion !== incomingVersion)
+        return;
+    const incomingDigest = digestMarkerFiles(markerFilesForSkill(incoming));
+    if (parsed.marker.digest === incomingDigest)
+        return;
+    throw userError(`Installed ${skill} and the update both claim skill set ${incomingVersion}, but their ` +
+        'contents differ. Skill-set versions are immutable; refusing to overwrite the installed copy.', 'SKILL_SET_VERSION_CONFLICT');
+}
+const inspectInstalledSkill = (destination, skill, expected, baselineVersion) => {
+    const path = join(destination.directory, skill);
+    const skillFile = join(path, 'SKILL.md');
+    const expectedFiles = markerFilesForSkill(expected);
+    const expectedDigest = digestMarkerFiles(expectedFiles);
+    const base = {
+        target: destination.target,
+        skill,
+        path,
+        skillFile,
+        installed: existsSync(skillFile),
+        managed: existsSync(join(path, MARKER)),
+        expectedDigest,
+    };
+    if (!existsSync(path))
+        return { ...base, status: 'missing' };
+    if (!base.managed) {
+        return { ...base, status: 'unmanaged', reason: 'Controller AI management marker is absent.' };
+    }
+    const parsed = parseManagedMarker(join(path, MARKER), skill);
+    if (parsed.kind === 'legacy') {
+        return { ...base, status: 'stale', reason: 'Legacy marker has no version or digest.' };
+    }
+    if (parsed.kind === 'invalid') {
+        return { ...base, status: 'invalid', reason: 'Management marker is invalid.' };
+    }
+    const marker = parsed.marker;
+    for (const file of marker.files) {
+        const filePath = join(path, ...file.path.split('/'));
+        if (!existsSync(filePath)) {
+            return {
+                ...base,
+                status: 'incomplete',
+                skillSetVersion: marker.skillSetVersion,
+                digest: marker.digest,
+                source: marker.source,
+                reason: `${file.path} is missing.`,
+            };
+        }
+        const fileStat = lstatSync(filePath);
+        if (!fileStat.isFile()) {
+            return {
+                ...base,
+                status: 'incomplete',
+                skillSetVersion: marker.skillSetVersion,
+                digest: marker.digest,
+                source: marker.source,
+                reason: `${file.path} is not a regular file.`,
+            };
+        }
+        if (fileStat.size !== file.size) {
+            return {
+                ...base,
+                status: 'modified',
+                skillSetVersion: marker.skillSetVersion,
+                digest: marker.digest,
+                source: marker.source,
+                reason: `${file.path} size differs from its installed marker.`,
+            };
+        }
+    }
+    const actualFiles = filesUnder(path).filter(file => file !== MARKER).sort();
+    const declaredFiles = marker.files.map(file => file.path).sort();
+    if (actualFiles.length !== declaredFiles.length ||
+        actualFiles.some((file, index) => file !== declaredFiles[index])) {
+        return {
+            ...base,
+            status: 'modified',
+            skillSetVersion: marker.skillSetVersion,
+            digest: marker.digest,
+            source: marker.source,
+            reason: 'Managed skill contains undeclared or missing files.',
+        };
+    }
+    for (const file of marker.files) {
+        const filePath = join(path, ...file.path.split('/'));
+        const fileStat = lstatSync(filePath);
+        if (!fileStat.isFile() || fileStat.size !== file.size) {
+            return {
+                ...base,
+                status: 'modified',
+                skillSetVersion: marker.skillSetVersion,
+                digest: marker.digest,
+                source: marker.source,
+                reason: `${file.path} changed while it was being checked.`,
+            };
+        }
+        const bytes = readFileSync(filePath);
+        if (bytes.length !== file.size || sha256(bytes) !== file.sha256) {
+            return {
+                ...base,
+                status: 'modified',
+                skillSetVersion: marker.skillSetVersion,
+                digest: marker.digest,
+                source: marker.source,
+                reason: `${file.path} differs from its installed digest.`,
+            };
+        }
+    }
+    const versionComparison = compareSkillSetVersions(marker.skillSetVersion, baselineVersion);
+    const stale = versionComparison === undefined
+        ? marker.skillSetVersion !== baselineVersion
+        : versionComparison < 0 || (versionComparison === 0 && marker.digest !== expectedDigest);
+    if (stale) {
+        return {
+            ...base,
+            status: 'stale',
+            skillSetVersion: marker.skillSetVersion,
+            digest: marker.digest,
+            source: marker.source,
+            reason: `Bundled skill set is ${baselineVersion}.`,
+        };
+    }
+    return {
+        ...base,
+        status: 'current',
+        skillSetVersion: marker.skillSetVersion,
+        digest: marker.digest,
+        source: marker.source,
+    };
+};
+export const installedSkillStatus = (opts = {}) => {
+    const manifest = readBundledSkillsManifest();
+    const expected = new Map(manifest.skills.map(skill => [skill.name, skill]));
+    const home = opts.homeDir ?? homedir();
+    const codexHome = opts.codexHome ?? process.env.CODEX_HOME ?? join(home, '.codex');
+    return skillTargetDirectories(opts.target ?? 'all', opts.projectDir, home, codexHome).flatMap(destination => PUBLIC_SKILLS.map(skill => inspectInstalledSkill(destination, skill, expected.get(skill), manifest.skillSetVersion)));
+};
+const installAvailabilityFallback = (bundledSkillSet, opts) => {
+    const target = opts.target ?? 'auto';
+    const home = opts.homeDir ?? homedir();
+    const codexHome = opts.codexHome ?? process.env.CODEX_HOME ?? join(home, '.codex');
+    const destinations = skillTargetDirectories(target, opts.projectDir, home, codexHome);
+    const statuses = installedSkillStatus(opts);
+    const retained = [];
+    const installDestinations = destinations.filter(destination => {
+        const rows = statuses.filter(row => directoryIdentity(dirname(row.path)) === directoryIdentity(destination.directory));
+        const retain = rows.length === PUBLIC_SKILLS.length && rows.every(row => row.status === 'current');
+        if (!retain)
+            return true;
+        for (const row of rows) {
+            retained.push({
+                target: destination.target,
+                skill: row.skill,
+                path: row.path,
+                skillFile: row.skillFile,
+                skillSetVersion: row.skillSetVersion,
+                digest: row.digest,
+                source: row.source,
+            });
+        }
+        return false;
+    });
+    const result = installSkillSet(bundledSkillSet, opts, installDestinations);
+    return createSkillInstallResult({
+        skillSetVersion: result.skillSetVersion,
+        source: result.source,
+        ...(result.manifestUrl ? { manifestUrl: result.manifestUrl } : {}),
+        installed: result.installed,
+        retained,
+        removedLegacyPaths: result.removedLegacyPaths,
+        migrationWarnings: result.migrationWarnings,
+        cleanupWarnings: result.cleanupWarnings,
+    });
+};
+export const entrySkillPaths = (result) => [
+    ...new Set(result.available
+        .filter(row => row.skill === 'controllerai-start')
+        .map(row => row.skillFile)),
+];
+const printInstallResult = (result) => {
+    const entries = entrySkillPaths(result);
+    const available = [
+        ...result.updated.map(row => ({ action: 'updated', row })),
+        ...result.retained.map(row => ({ action: 'retained', row })),
+    ];
+    printKeyValues([
+        ['update skill set', result.updateSkillSetVersion],
+        ['update source', result.updateSource],
+        ['available versions', result.availableSkillSetVersions.join(', ')],
+        ['available sources', result.availableSkillSources.join(', ')],
+        ['skills available', result.availableSkillCount],
+        ['skills updated', result.updatedSkillCount],
+        ['skills retained', result.retainedSkillCount],
+    ]);
+    process.stdout.write('\nAvailable skills:\n');
+    printTable(['action', 'target', 'skill', 'version', 'digest', 'path'], available.map(({ action, row }) => [
+        action,
+        row.target,
+        row.skill,
+        row.skillSetVersion,
+        row.digest,
+        row.skillFile,
+    ]));
+    if (result.removedLegacyPaths.length > 0) {
+        process.stdout.write('\nRemoved legacy managed Codex copies:\n');
+        for (const path of result.removedLegacyPaths)
+            process.stdout.write(`  ${path}\n`);
+    }
+    if (entries.length > 0) {
+        process.stdout.write('\nRead this entry skill now:\n');
+        for (const path of entries)
+            process.stdout.write(`  ${path}\n`);
+    }
+};
+const emitInstallWarnings = (result) => {
+    for (const message of [...result.migrationWarnings, ...result.cleanupWarnings])
+        warn(message);
+};
+export const registerSkills = (program) => {
+    const skills = program
+        .command('skills')
+        .description('Install and update Controller AI guidance for your agent');
+    const addInstallOptions = (command) => command
+        .option('--target <target>', 'auto, agents, codex, claude, cursor, copilot, all, or project', 'auto')
+        .option('--project-dir <path>', 'project root for the open-standard project target')
+        .option('--force', 'replace an existing unmanaged skill with the same name', false);
+    addInstallOptions(skills.command('install'))
+        .description('Install the verified skill set bundled with this CLI')
+        .action(async (opts) => {
+        const result = installSkills(opts);
+        emitInstallWarnings(result);
+        emit({
+            ...result,
+            entrySkillPath: entrySkillPaths(result)[0],
+            entrySkillPaths: entrySkillPaths(result),
+        }, () => printInstallResult(result));
+    });
+    addInstallOptions(skills.command('update'))
+        .description('Fetch, verify, and install the latest hosted Controller AI skill set')
+        .action(async (opts) => {
+        const result = await updateSkills(opts);
+        emitInstallWarnings(result);
+        emit({
+            ...result,
+            entrySkillPath: entrySkillPaths(result)[0],
+            entrySkillPaths: entrySkillPaths(result),
+        }, () => printInstallResult(result));
+    });
+    skills
+        .command('status')
+        .option('--target <target>', 'auto, agents, codex, claude, cursor, copilot, all, or project', 'all')
+        .option('--project-dir <path>', 'project root for the open-standard project target')
+        .description('Verify installed Controller AI skills, versions, and digests')
+        .action(async (opts) => {
+        assertSkillTarget(opts.target);
+        const rows = installedSkillStatus(opts);
+        emit({ skills: rows }, () => printTable(['target', 'skill', 'status', 'version', 'digest', 'path'], rows.map(row => [
+            row.target,
+            row.skill,
+            row.status,
+            row.skillSetVersion,
+            row.digest,
+            row.skillFile,
+        ])));
+    });
+};
+//# sourceMappingURL=skills.js.map