sfora-cli 0.14.0 → 0.16.0

package/dist/local-core/skills.d.ts

@@ -0,0 +1,55 @@
+export interface SkillFile {
+    path: string;
+    contentBase64: string;
+    sha256: string;
+    size: number;
+    executable: boolean;
+}
+export interface SkillBundle {
+    schemaVersion: 1;
+    name: string;
+    files: SkillFile[];
+    hash: string;
+}
+export interface SkillInstallation {
+    schemaVersion: 1;
+    path: string;
+    name: string;
+    hash: string;
+    installedAt: number;
+    source?: string;
+    sourceVersion?: number;
+}
+export interface SkillDifference {
+    path: string;
+    kind: "added" | "removed" | "modified";
+}
+export declare const SKILL_LIMITS: {
+    files: number;
+    fileBytes: number;
+    totalBytes: number;
+};
+export declare function validateSkillName(name: string): void;
+export declare function validateSkillPath(path: string): void;
+export declare function skillBundleHash(files: SkillFile[]): string;
+export declare function validateSkillBundle(bundle: SkillBundle): void;
+export declare function readSkillBundle(directory: string, name?: string): Promise<SkillBundle>;
+/** Legacy array API; the shared discovery engine owns all traversal. */
+export declare function scanLocalSkills(roots?: string[]): Promise<Array<{
+    path: string;
+    name: string;
+    hash?: string;
+    error?: string;
+}>>;
+export declare function diffSkillBundles(local: SkillBundle, incoming: SkillBundle): SkillDifference[];
+export declare function readInstallation(destination: string): Promise<SkillInstallation | undefined>;
+/** A receipt is historical intent. Classify today's filesystem object before trusting it. */
+export declare function inspectSkillTarget(directory: string): Promise<{
+    state: 'missing' | 'link' | 'file' | 'managed' | 'modified' | 'unmanaged' | 'unavailable';
+    ownership: 'managed' | 'unmanaged' | 'unknown';
+    hash?: string;
+    receipt?: SkillInstallation;
+    reason?: string;
+}>;
+export declare function installSkillBundle(bundle: SkillBundle, targetRoot: string, source?: string, sourceVersion?: number): Promise<SkillInstallation>;
+export declare function uninstallSkill(directory: string): Promise<void>;

package/dist/local-core/skills.js

@@ -0,0 +1,251 @@
+import { constants } from "node:fs";
+import { chmod, lstat, mkdir, open, readdir, realpath, rename, rm, writeFile } from "node:fs/promises";
+import { basename, dirname, join, resolve } from "node:path";
+import { randomUUID } from "node:crypto";
+import { atomicWrite, LocalConflictError, sha256, withLocalLock } from "./files.js";
+export const SKILL_LIMITS = { files: 1000, fileBytes: 5 * 1024 * 1024, totalBytes: 20 * 1024 * 1024 };
+export function validateSkillName(name) {
+    if (typeof name !== "string" || !/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(name) || name.length > 64)
+        throw new Error("Skill name must be 1–64 lowercase letters, digits and single hyphens.");
+}
+export function validateSkillPath(path) {
+    if (typeof path !== "string" || !path || path.length > 512 || path.includes("\\") || path.includes(":") || /[\x00-\x1f]/.test(path) || path.split("/").some(p => !p || p === "." || p === ".." || p.endsWith(".") || p.endsWith(" ")))
+        throw new Error(`Unsafe skill path: ${path}`);
+}
+export function skillBundleHash(files) {
+    return sha256(JSON.stringify([...files].sort((a, b) => a.path < b.path ? -1 : a.path > b.path ? 1 : 0).map(f => [f.path, f.sha256, f.size, f.executable])));
+}
+export function validateSkillBundle(bundle) {
+    if (!bundle || bundle.schemaVersion !== 1)
+        throw new Error("Unsupported skill bundle schema.");
+    validateSkillName(bundle.name);
+    if (!Array.isArray(bundle.files) || !bundle.files.length || bundle.files.length > SKILL_LIMITS.files)
+        throw new Error("Invalid skill file count.");
+    const paths = new Set();
+    let total = 0;
+    for (const file of bundle.files) {
+        if (!file || typeof file.contentBase64 !== "string" || file.contentBase64.length > Math.ceil(SKILL_LIMITS.fileBytes / 3) * 4)
+            throw new Error("Invalid skill file encoding or size.");
+        validateSkillPath(file.path);
+        const key = file.path.normalize("NFC").toLowerCase();
+        if (paths.has(key))
+            throw new Error(`Duplicate skill path: ${file.path}`);
+        paths.add(key);
+        const bytes = Buffer.from(file.contentBase64, "base64");
+        if (bytes.toString("base64") !== file.contentBase64 || bytes.length !== file.size || sha256(bytes) !== file.sha256 || typeof file.executable !== "boolean")
+            throw new Error(`Invalid skill file integrity: ${file.path}`);
+        total += bytes.length;
+        if (bytes.length > SKILL_LIMITS.fileBytes || total > SKILL_LIMITS.totalBytes)
+            throw new Error("Skill exceeds size limits.");
+    }
+    for (const path of paths) {
+        const parts = path.split("/");
+        while (parts.length > 1) {
+            parts.pop();
+            if (paths.has(parts.join("/")))
+                throw new Error("Skill file/directory collision.");
+        }
+    }
+    if (!bundle.files.some(f => f.path === "SKILL.md"))
+        throw new Error("A skill must contain SKILL.md.");
+    if (skillBundleHash(bundle.files) !== bundle.hash)
+        throw new Error("Invalid skill bundle hash.");
+}
+export async function readSkillBundle(directory, name = basename(resolve(directory))) {
+    validateSkillName(name);
+    if ((await lstat(directory)).isSymbolicLink())
+        throw new Error("Skill root cannot be a symbolic link.");
+    const root = await realpath(directory);
+    const files = [];
+    let total = 0;
+    let directories = 0;
+    async function walk(relative) {
+        if (++directories > 1000 || relative.split("/").length > 32)
+            throw new Error("Skill directory nesting exceeds limits.");
+        const folder = join(root, relative);
+        if ((await realpath(folder)) !== folder)
+            throw new Error("Symbolic links are not supported.");
+        for (const entry of await readdir(folder, { withFileTypes: true })) {
+            const path = relative ? `${relative}/${entry.name}` : entry.name;
+            validateSkillPath(path);
+            if (entry.isSymbolicLink())
+                throw new Error(`Symbolic links are not supported: ${path}`);
+            if (entry.isDirectory()) {
+                await walk(path);
+                continue;
+            }
+            if (!entry.isFile())
+                throw new Error(`Non-regular skill file: ${path}`);
+            const absolute = join(root, path);
+            const info = await lstat(absolute);
+            if (info.size > SKILL_LIMITS.fileBytes || total + info.size > SKILL_LIMITS.totalBytes || files.length >= SKILL_LIMITS.files)
+                throw new Error("Skill exceeds size limits.");
+            const handle = await open(absolute, constants.O_RDONLY | constants.O_NOFOLLOW);
+            let bytes;
+            try {
+                bytes = await handle.readFile();
+            }
+            finally {
+                await handle.close();
+            }
+            total += bytes.length;
+            files.push({ path, contentBase64: bytes.toString("base64"), size: bytes.length, sha256: sha256(bytes), executable: !!(info.mode & 0o111) });
+        }
+    }
+    await walk("");
+    files.sort((a, b) => a.path < b.path ? -1 : a.path > b.path ? 1 : 0);
+    const bundle = { schemaVersion: 1, name, files, hash: skillBundleHash(files) };
+    validateSkillBundle(bundle);
+    return bundle;
+}
+/** Legacy array API; the shared discovery engine owns all traversal. */
+export async function scanLocalSkills(roots) {
+    const { discoverSkills } = await import("./skill-discovery.js");
+    const result = await discoverSkills(roots?.map(path => ({ path, label: "Chosen folder", depth: 4 })));
+    if (result.warnings.length)
+        throw new Error(result.warnings.join("\n"));
+    return result.skills;
+}
+export function diffSkillBundles(local, incoming) {
+    validateSkillBundle(local);
+    validateSkillBundle(incoming);
+    const old = new Map(local.files.map(f => [f.path, f]));
+    const next = new Map(incoming.files.map(f => [f.path, f]));
+    return [...new Set([...old.keys(), ...next.keys()])].sort().flatMap(path => {
+        const a = old.get(path), b = next.get(path);
+        if (!a)
+            return [{ path, kind: "added" }];
+        if (!b)
+            return [{ path, kind: "removed" }];
+        return a.sha256 !== b.sha256 || a.executable !== b.executable ? [{ path, kind: "modified" }] : [];
+    });
+}
+function recordPath(destination) { return join(dirname(destination), `.${basename(destination)}.sfora-install.json`); }
+export async function readInstallation(destination) {
+    try {
+        const handle = await open(recordPath(destination), constants.O_RDONLY | constants.O_NOFOLLOW);
+        let raw;
+        try {
+            const info = await handle.stat();
+            if (!info.isFile() || info.size > 65536)
+                throw new Error('Invalid installation record file.');
+            raw = await handle.readFile('utf8');
+        }
+        finally {
+            await handle.close();
+        }
+        const record = JSON.parse(raw);
+        if (record.schemaVersion !== 1 || record.path !== destination || record.name !== basename(destination)
+            || !/^[a-f0-9]{64}$/.test(record.hash) || !Number.isSafeInteger(record.installedAt) || record.installedAt < 0
+            || (record.source !== undefined && (typeof record.source !== 'string' || record.source.length > 8192))
+            || (record.sourceVersion !== undefined && (!Number.isSafeInteger(record.sourceVersion) || record.sourceVersion < 1)))
+            throw new Error("Unsupported or mismatched installation record.");
+        return record;
+    }
+    catch (e) {
+        if (e.code === "ENOENT")
+            return undefined;
+        throw e;
+    }
+}
+/** A receipt is historical intent. Classify today's filesystem object before trusting it. */
+export async function inspectSkillTarget(directory) {
+    try {
+        const destination = join(await realpath(dirname(resolve(directory))), basename(directory));
+        const info = await lstat(destination).catch(e => { if (e.code === 'ENOENT')
+            return null; throw e; });
+        if (!info)
+            return { state: 'missing', ownership: 'unknown' };
+        if (info.isSymbolicLink())
+            return { state: 'link', ownership: 'unmanaged', reason: 'A link cannot be replaced using a copy installation receipt.' };
+        if (!info.isDirectory())
+            return { state: 'file', ownership: 'unmanaged', reason: 'The target is no longer a skill directory.' };
+        const bundle = await readSkillBundle(destination);
+        const receipt = await readInstallation(destination);
+        if (!receipt)
+            return { state: 'unmanaged', ownership: 'unmanaged', hash: bundle.hash };
+        if (receipt.hash !== bundle.hash)
+            return { state: 'modified', ownership: 'unmanaged', hash: bundle.hash, receipt, reason: 'The managed copy has local changes.' };
+        return { state: 'managed', ownership: 'managed', hash: bundle.hash, receipt };
+    }
+    catch (error) {
+        return { state: 'unavailable', ownership: 'unknown', reason: error.message };
+    }
+}
+export async function installSkillBundle(bundle, targetRoot, source, sourceVersion) {
+    validateSkillBundle(bundle);
+    if (sourceVersion !== undefined && (!Number.isSafeInteger(sourceVersion) || sourceVersion < 1))
+        throw new Error("Source version must be a positive integer.");
+    await mkdir(targetRoot, { recursive: true });
+    const root = await realpath(targetRoot);
+    const destination = join(root, bundle.name);
+    return withLocalLock(destination, async () => {
+        const previous = await readInstallation(destination);
+        let exists = false;
+        try {
+            await lstat(destination);
+            exists = true;
+        }
+        catch (e) {
+            if (e.code !== "ENOENT")
+                throw e;
+        }
+        if (exists) {
+            if (!previous)
+                throw new LocalConflictError("Destination is not owned by Sfora. Choose another target.");
+            if ((await readSkillBundle(destination)).hash !== previous.hash)
+                throw new LocalConflictError("Installed skill has local changes. Push or copy them before updating.");
+        }
+        const staging = join(root, `.${bundle.name}.${randomUUID()}.stage`);
+        const backup = `${staging}.previous`;
+        await mkdir(staging, { mode: 0o700 });
+        try {
+            for (const file of bundle.files) {
+                const path = join(staging, file.path);
+                await mkdir(dirname(path), { recursive: true });
+                await writeFile(path, Buffer.from(file.contentBase64, "base64"), { flag: "wx", mode: file.executable ? 0o755 : 0o644 });
+                await chmod(path, file.executable ? 0o755 : 0o644);
+            }
+            if (exists)
+                await rename(destination, backup);
+            try {
+                await rename(staging, destination);
+                const record = { schemaVersion: 1, path: destination, name: bundle.name, hash: bundle.hash, installedAt: Date.now(), source, sourceVersion };
+                await atomicWrite(recordPath(destination), `${JSON.stringify(record, null, 2)}\n`);
+                // Record publication completes the transaction. Failed obsolete-backup cleanup
+                // must never roll the destination back under a newly committed record.
+                await rm(backup, { recursive: true, force: true }).catch(() => { });
+                return record;
+            }
+            catch (error) {
+                await rm(destination, { recursive: true, force: true });
+                if (exists)
+                    await rename(backup, destination);
+                throw error;
+            }
+        }
+        finally {
+            await rm(staging, { recursive: true, force: true });
+        }
+    });
+}
+export async function uninstallSkill(directory) {
+    const destination = join(await realpath(dirname(resolve(directory))), basename(directory));
+    await withLocalLock(destination, async () => {
+        const record = await readInstallation(destination);
+        if (!record)
+            throw new Error("This skill installation is not owned by Sfora.");
+        if ((await readSkillBundle(destination)).hash !== record.hash)
+            throw new LocalConflictError("Installed skill has local changes; uninstall refused.");
+        const trash = `${destination}.${randomUUID()}.removed`;
+        await rename(destination, trash);
+        try {
+            await rm(recordPath(destination));
+        }
+        catch (error) {
+            await rename(trash, destination);
+            throw error;
+        }
+        await rm(trash, { recursive: true });
+    });
+}

package/dist/skills-client.d.ts

@@ -0,0 +1,32 @@
+import { type SkillBundle } from "./local-core/skills.js";
+import type { ResolvedSettings } from "./config.js";
+import { type PublishedSkillSnapshot } from "./local-core/skill-sync.js";
+export declare class SkillsApiError extends Error {
+    readonly status: number;
+    constructor(status: number, body: string);
+}
+export declare class SkillPublicationUnavailableError extends Error {
+    readonly code: 'SKILL_NOT_FOUND' | 'SKILL_NOT_PUBLISHED';
+    constructor(code: 'SKILL_NOT_FOUND' | 'SKILL_NOT_PUBLISHED', message: string);
+}
+export declare class SkillsClient {
+    private readonly settings;
+    constructor(settings: ResolvedSettings);
+    request<T>(route: string, init?: RequestInit): Promise<T>;
+    list(project: string): Promise<unknown>;
+    detail(project: string, name: string): Promise<{
+        skill: {
+            version: number;
+            draftRevision: number;
+        };
+        [key: string]: unknown;
+    }>;
+    download(project: string, name: string, version?: number): Promise<SkillBundle>;
+    /** Pin a published revision and verify IDs/hash; lookup labels confer no update authority. */
+    snapshot(project: string, name: string): Promise<PublishedSkillSnapshot>;
+    saveDraft(project: string, bundle: SkillBundle, expectedVersion: number, expectedRevision?: number, expectedSkillId?: string): Promise<{
+        draftRevision: number;
+        [key: string]: unknown;
+    }>;
+    publish(project: string, name: string, expectedVersion: number, expectedRevision?: number, expectedSkillId?: string): Promise<unknown>;
+}

package/dist/skills-client.js

@@ -0,0 +1,88 @@
+import { validateSkillBundle } from "./local-core/skills.js";
+import { SforaApiClient } from "./api-client.js";
+import { validatePublishedSkillSnapshot } from "./local-core/skill-sync.js";
+export class SkillsApiError extends Error {
+    status;
+    constructor(status, body) {
+        super(`Skills API ${status}: ${body}`);
+        this.status = status;
+    }
+}
+export class SkillPublicationUnavailableError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+    }
+}
+export class SkillsClient {
+    settings;
+    constructor(settings) {
+        this.settings = settings;
+    }
+    async request(route, init) {
+        if (!this.settings.apiKey)
+            throw new Error("Run sfora login to connect to cloud Skills.");
+        const response = await fetch(new URL(route, this.settings.url), {
+            ...init, headers: { Authorization: `Bearer ${this.settings.apiKey}`, "Content-Type": "application/json", "X-Sfora-Client": "cli", ...init?.headers },
+        });
+        if (!response.ok)
+            throw new SkillsApiError(response.status, await response.text());
+        return await response.json();
+    }
+    list(project) { return this.request(`/v1/skills?${new URLSearchParams({ project })}`); }
+    detail(project, name) {
+        return this.request(`/v1/skills?${new URLSearchParams({ project, name })}`);
+    }
+    async download(project, name, version) {
+        const query = new URLSearchParams({ project, name, download: "1" });
+        if (version !== undefined)
+            query.set("version", String(version));
+        const bundle = await this.request(`/v1/skills?${query}`);
+        validateSkillBundle(bundle);
+        return bundle;
+    }
+    /** Pin a published revision and verify IDs/hash; lookup labels confer no update authority. */
+    async snapshot(project, name) {
+        if (!this.settings.apiKey)
+            throw new Error("Run sfora login to connect to cloud Skills.");
+        const me = await new SforaApiClient({ baseUrl: this.settings.url, apiKey: this.settings.apiKey }).readMe();
+        const accountId = /^memberId: ([a-zA-Z0-9_-]+)$/m.exec(me)?.[1];
+        if (!accountId)
+            throw new Error('Cloud identity response is missing a member ID.');
+        let detail;
+        try {
+            detail = await this.detail(project, name);
+        }
+        catch (error) {
+            if (error instanceof SkillsApiError && error.status === 404)
+                throw new SkillPublicationUnavailableError('SKILL_NOT_FOUND', 'This project has no published skill with that name.');
+            throw error;
+        }
+        const skill = detail.skill;
+        if (![skill._id, skill.orgId, skill.projectId].every(v => typeof v === 'string' && v.length > 0))
+            throw new Error('Cloud skill response is missing qualified identity fields.');
+        if (!Number.isSafeInteger(skill.version) || skill.version < 1)
+            throw new SkillPublicationUnavailableError('SKILL_NOT_PUBLISHED', 'This skill has no published version to compare.');
+        const versions = detail.versions;
+        const revision = Array.isArray(versions) ? versions.find(v => v.version === skill.version && v.skillId === skill._id) : undefined;
+        if (!revision || typeof revision.hash !== 'string')
+            throw new Error('Cloud skill response is missing the published revision.');
+        const bundle = await this.download(project, name, skill.version);
+        const snapshot = {
+            remote: { deployment: new URL(this.settings.url).origin, organizationId: skill.orgId, projectId: skill.projectId, skillId: skill._id },
+            accountId, locator: { project, name }, revision: { hash: revision.hash, cloudVersion: skill.version, contentPolicy: 'bundle-v1' },
+            draftRevision: skill.draftRevision, hasDraft: !!skill.draftStorageId, draftHash: skill.draftHash,
+            supportsIdentityGuards: Array.isArray(detail.capabilities) && detail.capabilities.includes('qualified-skill-write-v1'), bundle,
+        };
+        validatePublishedSkillSnapshot(snapshot);
+        return snapshot;
+    }
+    saveDraft(project, bundle, expectedVersion, expectedRevision, expectedSkillId) {
+        validateSkillBundle(bundle);
+        return this.request("/v1/skills", { method: "POST", body: JSON.stringify({ project, name: bundle.name, bundle, expectedVersion, expectedRevision, expectedSkillId }) });
+    }
+    publish(project, name, expectedVersion, expectedRevision, expectedSkillId) {
+        return this.request("/v1/skills/publish", { method: "POST", body: JSON.stringify({ project, name, expectedVersion, expectedRevision, expectedSkillId }) });
+    }
+}

package/dist/skills-command.d.ts

@@ -0,0 +1,4 @@
+import type { CliArgs } from "./cli-args.js";
+import type { ResolvedSettings } from "./config.js";
+export declare const SKILLS_HELP = "Skills:\n  sfora skills inventory --json               Persistent local inventory with warnings and identities\n  sfora skills roots [add <folder> [label] | add-project <folder> [label] | remove <id>]\n                                              Manage registered discovery folders (never deletes files)\n  sfora skills scan [root ...] --json          Discover complete local skill bundles\n  sfora skills list --project <slug>           List cloud project skills\n  sfora skills index --json                  Read cached local inventory without scanning\n  sfora skills operations                    List durable transfer outcomes and recovery needs\n  sfora skills queue <plan.json>             Queue a reviewed push, pull or install\n  sfora skills cancel <operation-id>         Cancel an unstarted operation\n  sfora skills apply <plan.json|operation-id> Execute a reviewed plan\n  sfora skills recover <operation-id>        Reconcile an interrupted operation\n  sfora skills apply-batch <ids.json>        Run queued operation IDs with per-item outcomes\n  sfora skills recover-batch <ids.json>      Resume incomplete items without replaying successes\n  sfora skills bindings                      List explicit cloud mappings and baselines\n  sfora skills bind <location-id> <cloud-name> --project <slug>\n                                              Explicitly adopt a published cloud identity\n  sfora skills status <binding-id>            Compare current files with the bound published revision\n  sfora skills plan <binding-id> <push|pull>   Preview IDs, hashes, conflicts and per-file changes\n  sfora skills plan-install <name> --project <slug> --skills-target <existing-directory>\n                                              Preview a new installation without modifying files\n  sfora skills relocate <location-id> <folder> Preserve identity after an explicit folder move\n  sfora skills push <folder> --project <slug> --expected-version <N> [--expected-revision <N>]\n                                              Upload draft and publish (0 for a new skill)\n  sfora skills pull <name> <bundle.json> --project <slug> [--version <N>]\n  sfora skills install <name> --project <slug> --skills-target <directory> [--version <N>]\n  sfora skills install-file <bundle.json> --skills-target <directory>\n  sfora skills diff <folder> <name> --project <slug> [--version <N>]\n  sfora skills uninstall <installed-folder>   Remove only an unchanged Sfora-owned install\n";
+export declare function runSkillsCommand(args: CliArgs, settings: ResolvedSettings): Promise<void>;

package/dist/skills-command.js

@@ -0,0 +1,223 @@
+import { dirname, join } from "node:path";
+import { readFile, realpath } from "node:fs/promises";
+import { diffSkillBundles, installSkillBundle, inspectSkillTarget, readSkillBundle, discoverSkills, SkillService, uninstallSkill, validateSkillBundle } from "./local-core/index.js";
+import { SkillOperationJournal } from "./local-core/skill-operations.js";
+import { SkillOperationExecutor } from "./local-core/skill-executor.js";
+import { defaultSkillCatalogPath } from "./local-core/skill-store.js";
+import { SkillsClient } from "./skills-client.js";
+import { SkillBindingService, assertSkillBindingSnapshot, compareSkillStates, planSkillTransfer, planSkillInstallation } from './local-core/skill-sync.js';
+export const SKILLS_HELP = `Skills:
+  sfora skills inventory --json               Persistent local inventory with warnings and identities
+  sfora skills roots [add <folder> [label] | add-project <folder> [label] | remove <id>]
+                                              Manage registered discovery folders (never deletes files)
+  sfora skills scan [root ...] --json          Discover complete local skill bundles
+  sfora skills list --project <slug>           List cloud project skills
+  sfora skills index --json                  Read cached local inventory without scanning
+  sfora skills operations                    List durable transfer outcomes and recovery needs
+  sfora skills queue <plan.json>             Queue a reviewed push, pull or install
+  sfora skills cancel <operation-id>         Cancel an unstarted operation
+  sfora skills apply <plan.json|operation-id> Execute a reviewed plan
+  sfora skills recover <operation-id>        Reconcile an interrupted operation
+  sfora skills apply-batch <ids.json>        Run queued operation IDs with per-item outcomes
+  sfora skills recover-batch <ids.json>      Resume incomplete items without replaying successes
+  sfora skills bindings                      List explicit cloud mappings and baselines
+  sfora skills bind <location-id> <cloud-name> --project <slug>
+                                              Explicitly adopt a published cloud identity
+  sfora skills status <binding-id>            Compare current files with the bound published revision
+  sfora skills plan <binding-id> <push|pull>   Preview IDs, hashes, conflicts and per-file changes
+  sfora skills plan-install <name> --project <slug> --skills-target <existing-directory>
+                                              Preview a new installation without modifying files
+  sfora skills relocate <location-id> <folder> Preserve identity after an explicit folder move
+  sfora skills push <folder> --project <slug> --expected-version <N> [--expected-revision <N>]
+                                              Upload draft and publish (0 for a new skill)
+  sfora skills pull <name> <bundle.json> --project <slug> [--version <N>]
+  sfora skills install <name> --project <slug> --skills-target <directory> [--version <N>]
+  sfora skills install-file <bundle.json> --skills-target <directory>
+  sfora skills diff <folder> <name> --project <slug> [--version <N>]
+  sfora skills uninstall <installed-folder>   Remove only an unchanged Sfora-owned install
+`;
+export async function runSkillsCommand(args, settings) {
+    const [verb, first, second] = args.rest;
+    for (const [label, value] of [["version", args.skillVersion], ["expected-version", args.expectedVersion], ["expected-revision", args.expectedRevision]]) {
+        if (value !== undefined && (!Number.isSafeInteger(value) || value < (label === "version" ? 1 : 0)))
+            throw new Error(`--${label} must be a ${label === "version" ? "positive" : "non-negative"} integer.`);
+    }
+    const print = (value) => console.log(JSON.stringify(value, null, args.json ? undefined : 2));
+    const need = (value, label) => { if (!value)
+        throw new Error(`${label} is required.\n${SKILLS_HELP}`); return value; };
+    if (verb === "roots") {
+        const service = new SkillService();
+        if (!first)
+            print(await service.roots());
+        else if (first === "add" || first === "add-project")
+            print(await service.registerRoot(need(second, "Folder"), args.rest[3], first === "add-project" ? "project" : "custom"));
+        else if (first === "remove") {
+            await service.removeRoot(need(second, "Root ID"));
+            print({ removed: second });
+        }
+        else
+            throw new Error("Use skills roots, skills roots add <folder> [label], or skills roots remove <id>.");
+        return;
+    }
+    if (verb === "index") {
+        print(await new SkillService().cachedInventory());
+        return;
+    }
+    if (verb === "inventory" || verb === "scan") {
+        const result = verb === "scan" && args.rest.length > 1
+            ? await discoverSkills(args.rest.slice(1).map(path => ({ path, label: "Chosen folder", depth: 4 })))
+            : await new SkillService().inventory();
+        if (verb === "scan") {
+            print(result.skills);
+            if (result.warnings.length)
+                console.error(JSON.stringify({ warnings: result.warnings }));
+        }
+        else
+            print(result);
+        return;
+    }
+    if (verb === "uninstall") {
+        await uninstallSkill(need(first, "Installed folder"));
+        print({ uninstalled: first });
+        return;
+    }
+    if (['operations', 'queue', 'cancel', 'apply', 'recover', 'apply-batch', 'recover-batch'].includes(verb)) {
+        const journal = new SkillOperationJournal(join(dirname(defaultSkillCatalogPath()), 'operations.sqlite'));
+        if (verb === 'operations') {
+            print(await journal.list());
+            return;
+        }
+        if (verb === 'cancel') {
+            print(await journal.cancel(need(first, 'Operation ID')));
+            return;
+        }
+        if (verb === 'queue') {
+            print(await journal.create(JSON.parse(await readFile(need(first, 'Plan JSON'), 'utf8'))));
+            return;
+        }
+        const service = new SkillService();
+        const client = new SkillsClient(settings);
+        const executor = new SkillOperationExecutor(service.store, journal, client);
+        if (verb === 'apply-batch' || verb === 'recover-batch') {
+            const ids = JSON.parse(await readFile(need(first, 'Operation IDs JSON'), 'utf8'));
+            const controller = new AbortController();
+            const stop = () => { controller.abort(); console.error('Stopping after the current item; unstarted work will be cancelled.'); };
+            process.once('SIGINT', stop);
+            try {
+                const results = await executor.batch(ids, { recover: verb === 'recover-batch', signal: controller.signal });
+                print(results);
+                if (results.some(r => r.error))
+                    process.exitCode = 1;
+            }
+            finally {
+                process.removeListener('SIGINT', stop);
+            }
+            return;
+        }
+        const operation = verb === 'apply' && !/^[a-f0-9-]{36}$/.test(first ?? '') ? await journal.create(JSON.parse(await readFile(need(first, 'Plan JSON'), 'utf8'))) : undefined;
+        const id = operation?.id ?? need(first, 'Operation ID');
+        try {
+            print(await executor.apply(id, verb === 'recover'));
+        }
+        catch (error) {
+            throw new Error(`${error.message} Operation ${id} was retained; inspect skills operations, then use skills recover ${id}.`);
+        }
+        return;
+    }
+    if (['bindings', 'bind', 'status', 'plan', 'relocate'].includes(verb)) {
+        const service = new SkillService();
+        const bindings = new SkillBindingService(service.store);
+        if (verb === 'bindings') {
+            print(await bindings.list());
+            return;
+        }
+        if (verb === 'relocate') {
+            print(await service.relocateLocation(need(first, 'Location ID'), need(second, 'Folder')));
+            return;
+        }
+        const catalog = await service.store.read();
+        const binding = verb === 'bind' ? undefined : catalog.bindings.find(b => b.id === need(first, 'Binding ID'));
+        if (verb !== 'bind' && !binding)
+            throw new Error('Skill binding not found.');
+        if (binding && args.project && args.project !== binding.locator.project)
+            throw new Error('--project differs from the explicit skill binding.');
+        const location = catalog.locations.find(l => verb === 'bind' ? l.id === first : l.skillId === binding.localSkillId);
+        if (!location)
+            throw new Error('Local skill location not found. Register its folder and refresh the inventory first.');
+        if (verb === 'plan' && second !== 'push' && second !== 'pull')
+            throw new Error('Choose skills plan <binding-id> <push|pull>.');
+        const client = new SkillsClient(settings);
+        const snapshot = await client.snapshot(binding?.locator.project ?? need(args.project, '--project'), binding?.locator.name ?? need(second, 'Cloud skill name'));
+        if (binding)
+            assertSkillBindingSnapshot(binding, snapshot);
+        let local;
+        try {
+            local = { state: 'available', bundle: await readSkillBundle(location.path) };
+        }
+        catch (error) {
+            local = { state: error.code === 'ENOENT' ? 'missing' : 'unavailable', reason: error.message };
+        }
+        if (verb === 'bind') {
+            if (local.state !== 'available')
+                throw new Error(local.reason);
+            print(await bindings.adopt(location.skillId, snapshot, local.bundle));
+            return;
+        }
+        if (verb === 'status') {
+            print({ bindingId: binding.id, status: compareSkillStates(local, { state: 'available', bundle: snapshot.bundle }, binding.baseline),
+                local: local.state === 'available' ? { state: local.state, hash: local.bundle.hash } : local, remote: snapshot.revision, baseline: binding.baseline ?? null });
+            return;
+        }
+        const target = await inspectSkillTarget(location.path);
+        print(planSkillTransfer({ direction: second, binding: binding, location, local, remote: snapshot, ownership: target.ownership }));
+        return;
+    }
+    if (verb === "install-file") {
+        const bundle = JSON.parse(await readFile(need(first, "Bundle JSON"), "utf8"));
+        validateSkillBundle(bundle);
+        print(await installSkillBundle(bundle, need(args.skillsTarget, "--skills-target"), first));
+        return;
+    }
+    const project = need(args.project, "--project");
+    const client = new SkillsClient(settings);
+    if (verb === 'plan-install') {
+        const remote = await client.snapshot(project, need(first, 'Skill name'));
+        const target = join(await realpath(need(args.skillsTarget, '--skills-target')), remote.bundle.name);
+        print(planSkillInstallation(remote, target, await inspectSkillTarget(target)));
+        return;
+    }
+    if (verb === "list") {
+        print(await client.list(project));
+        return;
+    }
+    if (verb === "push") {
+        if (args.expectedVersion === undefined)
+            throw new Error("--expected-version is required (0 for a new skill). Read the current version with skills list first.");
+        const bundle = await readSkillBundle(need(first, "Skill folder"));
+        const draft = await client.saveDraft(project, bundle, args.expectedVersion, args.expectedRevision);
+        print(await client.publish(project, bundle.name, args.expectedVersion, draft.draftRevision));
+        return;
+    }
+    if (verb === "pull") {
+        const bundle = await client.download(project, need(first, "Skill name"), args.skillVersion);
+        // Export refuses to overwrite unrelated files; explicit repeated exports can choose a new path.
+        const { atomicCreate } = await import("./local-core/files.js");
+        await atomicCreate(need(second, "Output bundle JSON"), `${JSON.stringify(bundle, null, 2)}\n`);
+        print({ path: second, hash: bundle.hash });
+        return;
+    }
+    if (verb === "install") {
+        const name = need(first, "Skill name");
+        const version = args.skillVersion ?? (await client.detail(project, name)).skill.version;
+        if (!Number.isSafeInteger(version) || version < 1)
+            throw new Error("This skill has no published version to install.");
+        const bundle = await client.download(project, name, version);
+        print(await installSkillBundle(bundle, need(args.skillsTarget, "--skills-target"), `${settings.url}/${project}/${name}`, version));
+        return;
+    }
+    if (verb === "diff") {
+        print(diffSkillBundles(await readSkillBundle(need(first, "Local folder")), await client.download(project, need(second, "Skill name"), args.skillVersion)));
+        return;
+    }
+    throw new Error(SKILLS_HELP);
+}

package/dist/version.d.ts

@@ -0,0 +1 @@
+export declare const CLI_VERSION = "0.16.0";