sfora-cli 0.14.0 → 0.15.0

package/dist/local/workspace.js

@@ -1,3 +1,4 @@
+import { atomicWrite, withLocalLock } from "../local-core/files.js";
 /**
  * LocalWorkspace — the OSS local mode. A `.sfora/` directory in your repo is
  * the workspace: tasks, posts, and docs are plain markdown files on disk, in
@@ -224,32 +225,37 @@ export class LocalWorkspace {
      * scanning the board. The markdown is written verbatim — files are storage.
      */
     async writeTask(markdown, opts = {}) {
-        const parsed = parseMarkdownCard(markdown);
-        if (!parsed.title.trim()) {
-            throw new Error("Title is required — add an H1 (`# Title`) or a frontmatter `title:`");
-        }
-        const fmColumn = typeof parsed.frontmatter.column === "string"
-            ? parsed.frontmatter.column
-            : undefined;
-        const fmStatus = typeof parsed.frontmatter.status === "string"
-            ? parsed.frontmatter.status
-            : undefined;
-        const column = await this.#resolveColumn(opts.column ?? fmColumn, fmStatus);
-        // Existing card (by explicit frontmatter number) → replace in place,
-        // wherever it currently lives (the new write may also move it).
-        const fmNumber = typeof parsed.frontmatter.number === "string"
-            ? Number.parseInt(parsed.frontmatter.number, 10)
-            : undefined;
-        const existing = fmNumber !== undefined && Number.isFinite(fmNumber)
-            ? await this.#findByNumber(fmNumber)
-            : undefined;
-        if (existing) {
-            await rm(join(this.root, "board", existing.column, existing.filename));
-        }
-        const number = existing?.number ?? (await this.#nextNumber());
-        const filename = cardFilename({ number, title: parsed.title });
-        await writeFile(join(this.root, "board", column, filename), markdown, "utf8");
-        return { filename, column, number };
+        return withLocalLock(join(this.root, "board"), async () => {
+            const parsed = parseMarkdownCard(markdown);
+            if (!parsed.title.trim()) {
+                throw new Error("Title is required — add an H1 (`# Title`) or a frontmatter `title:`");
+            }
+            const fmColumn = typeof parsed.frontmatter.column === "string"
+                ? parsed.frontmatter.column
+                : undefined;
+            const fmStatus = typeof parsed.frontmatter.status === "string"
+                ? parsed.frontmatter.status
+                : undefined;
+            const column = await this.#resolveColumn(opts.column ?? fmColumn, fmStatus);
+            // Existing card (by explicit frontmatter number) → replace in place,
+            // wherever it currently lives (the new write may also move it).
+            const fmNumber = typeof parsed.frontmatter.number === "string"
+                ? Number.parseInt(parsed.frontmatter.number, 10)
+                : undefined;
+            const existing = fmNumber !== undefined && Number.isFinite(fmNumber)
+                ? await this.#findByNumber(fmNumber)
+                : undefined;
+            const number = existing?.number ?? (await this.#nextNumber());
+            const filename = cardFilename({ number, title: parsed.title });
+            const destination = join(this.root, "board", column, filename);
+            await atomicWrite(destination, markdown, 0o644);
+            if (existing) {
+                const previous = join(this.root, "board", existing.column, existing.filename);
+                if (previous !== destination)
+                    await rm(previous);
+            }
+            return { filename, column, number };
+        });
     }
     // ─── Posts & docs ────────────────────────────────────────────────
     async writePost(markdown, opts = {}) {
@@ -261,7 +267,7 @@ export class LocalWorkspace {
         const filename = `${date}-${slugify(parsed.title)}.md`;
         const dir = opts.draft ? "drafts" : "posts";
         await mkdir(join(this.root, dir), { recursive: true });
-        await writeFile(join(this.root, dir, filename), markdown, "utf8");
+        await withLocalLock(join(this.root, dir, filename), () => atomicWrite(join(this.root, dir, filename), markdown, 0o644));
         return { filename };
     }
     async writeDoc(markdown) {
@@ -271,7 +277,7 @@ export class LocalWorkspace {
         }
         const filename = noteFilename({ title: parsed.title });
         await mkdir(join(this.root, "docs"), { recursive: true });
-        await writeFile(join(this.root, "docs", filename), markdown, "utf8");
+        await withLocalLock(join(this.root, "docs", filename), () => atomicWrite(join(this.root, "docs", filename), markdown, 0o644));
         return { filename };
     }
     async listPosts(kind = "posts") {

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

@@ -0,0 +1,23 @@
+import { type FSWatcher } from "node:fs";
+export declare const sha256: (bytes: Uint8Array | string) => string;
+export declare class LocalConflictError extends Error {
+    readonly code = "LOCAL_CONFLICT";
+    constructor(message?: string);
+}
+/** Exclusive cross-process lock. A crashed process leaves an explicit recoverable lock;
+ * never steal a live/slow operation's lock based on a timeout. */
+export declare function withLocalLock<T>(path: string, operation: () => Promise<T>): Promise<T>;
+/** Write a complete staged file on the same filesystem before replacing the destination. */
+export declare function atomicWrite(path: string, content: string | Uint8Array, mode?: number): Promise<void>;
+export interface LocalMarkdownSnapshot {
+    path: string;
+    content: string;
+    revision: string;
+}
+export declare function readLocalMarkdown(path: string): Promise<LocalMarkdownSnapshot>;
+export declare function saveLocalMarkdown(path: string, content: string, expectedRevision: string): Promise<LocalMarkdownSnapshot>;
+/** Save As creates a new path only. Replacing an existing file requires its current revision. */
+export declare function atomicCreate(path: string, content: string | Uint8Array): Promise<string>;
+export declare function saveNewLocalMarkdown(path: string, content: string): Promise<LocalMarkdownSnapshot>;
+/** Watch the parent so atomic replacement by another editor remains observable. */
+export declare function watchLocalMarkdown(path: string, onChange: () => void): FSWatcher;

package/dist/local-core/files.js

@@ -0,0 +1,110 @@
+import { createHash, randomUUID } from "node:crypto";
+import { watch } from "node:fs";
+import { mkdir, open, readFile, realpath, rename, rm, stat, link } from "node:fs/promises";
+import { basename, dirname, join, resolve } from "node:path";
+import { setTimeout as delay } from "node:timers/promises";
+export const sha256 = (bytes) => createHash("sha256").update(bytes).digest("hex");
+export class LocalConflictError extends Error {
+    code = "LOCAL_CONFLICT";
+    constructor(message = "The file changed on disk. Reload or save a separate copy.") { super(message); this.name = "LocalConflictError"; }
+}
+/** Exclusive cross-process lock. A crashed process leaves an explicit recoverable lock;
+ * never steal a live/slow operation's lock based on a timeout. */
+export async function withLocalLock(path, operation) {
+    const lock = `${path}.sfora-lock`;
+    const deadline = Date.now() + 5000;
+    for (;;) {
+        try {
+            await mkdir(lock, { mode: 0o700 });
+            break;
+        }
+        catch (error) {
+            if (error.code !== "EEXIST")
+                throw error;
+            if (Date.now() >= deadline)
+                throw new Error(`Local operation locked: ${lock}. If no Sfora process is using it, remove this lock directory and retry.`);
+            await delay(25);
+        }
+    }
+    try {
+        return await operation();
+    }
+    finally {
+        await rm(lock, { recursive: true, force: true });
+    }
+}
+/** Write a complete staged file on the same filesystem before replacing the destination. */
+export async function atomicWrite(path, content, mode = 0o600) {
+    const temporary = join(dirname(path), `.${basename(path)}.${randomUUID()}.tmp`);
+    const handle = await open(temporary, "wx", mode);
+    try {
+        await handle.writeFile(content);
+        await handle.sync();
+    }
+    catch (error) {
+        await rm(temporary, { force: true });
+        throw error;
+    }
+    finally {
+        await handle.close();
+    }
+    try {
+        await rename(temporary, path);
+    }
+    finally {
+        await rm(temporary, { force: true });
+    }
+}
+const MAX_MARKDOWN_BYTES = 20 * 1024 * 1024;
+export async function readLocalMarkdown(path) {
+    const canonical = await realpath(path);
+    const info = await stat(canonical);
+    if (!info.isFile() || info.size > MAX_MARKDOWN_BYTES)
+        throw new Error("Select a regular Markdown file smaller than 20 MiB.");
+    const bytes = await readFile(canonical);
+    // Buffer decoding preserves BOM. Reject invalid UTF-8 instead of silently corrupting it.
+    const content = bytes.toString("utf8");
+    if (!Buffer.from(content, "utf8").equals(bytes))
+        throw new Error("This file is not valid UTF-8.");
+    return { path: canonical, content, revision: sha256(bytes) };
+}
+export async function saveLocalMarkdown(path, content, expectedRevision) {
+    const canonical = await realpath(path);
+    if (Buffer.byteLength(content) > MAX_MARKDOWN_BYTES)
+        throw new Error("Markdown exceeds 20 MiB.");
+    return withLocalLock(canonical, async () => {
+        const previous = await readLocalMarkdown(canonical);
+        if (previous.revision !== expectedRevision)
+            throw new LocalConflictError();
+        const mode = (await stat(canonical)).mode & 0o777;
+        await atomicWrite(canonical, content, mode);
+        return { path: canonical, content, revision: sha256(content) };
+    });
+}
+/** Save As creates a new path only. Replacing an existing file requires its current revision. */
+export async function atomicCreate(path, content) {
+    const destination = join(await realpath(dirname(resolve(path))), basename(path));
+    const temporary = `${destination}.${randomUUID()}.tmp`;
+    try {
+        await atomicWrite(temporary, content);
+        // Hard link publishes atomically and fails EEXIST instead of overwriting a raced save.
+        await link(temporary, destination);
+    }
+    finally {
+        await rm(temporary, { force: true });
+    }
+    return destination;
+}
+export async function saveNewLocalMarkdown(path, content) {
+    if (Buffer.byteLength(content) > MAX_MARKDOWN_BYTES)
+        throw new Error("Markdown exceeds 20 MiB.");
+    const destination = await atomicCreate(path, content);
+    return { path: destination, content, revision: sha256(content) };
+}
+/** Watch the parent so atomic replacement by another editor remains observable. */
+export function watchLocalMarkdown(path, onChange) {
+    return watch(dirname(path), (_event, filename) => {
+        if (filename === null || filename.toString() === basename(path))
+            onChange();
+    });
+}

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

@@ -0,0 +1,4 @@
+/** Trusted Node-only operations shared by the CLI and Electron main process.
+ * Renderers must obtain native dialog grants; never expose these as arbitrary IPC paths. */
+export * from "./files.js";
+export * from "./skills.js";

package/dist/local-core/index.js

@@ -0,0 +1,4 @@
+/** Trusted Node-only operations shared by the CLI and Electron main process.
+ * Renderers must obtain native dialog grants; never expose these as arbitrary IPC paths. */
+export * from "./files.js";
+export * from "./skills.js";

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

@@ -0,0 +1,45 @@
+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>;
+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 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,239 @@
+import { constants } from "node:fs";
+import { chmod, lstat, mkdir, open, readdir, readFile, realpath, rename, rm, writeFile } from "node:fs/promises";
+import { basename, dirname, join, resolve } from "node:path";
+import { homedir } from "node:os";
+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;
+}
+export async function scanLocalSkills(roots = [join(homedir(), ".agents/skills"), join(homedir(), ".codex/skills"), join(homedir(), ".claude/skills")]) {
+    const results = [];
+    for (const root of roots) {
+        let entries;
+        try {
+            entries = await readdir(root, { withFileTypes: true });
+        }
+        catch (e) {
+            if (e.code === "ENOENT")
+                continue;
+            throw e;
+        }
+        for (const entry of entries) {
+            if (!entry.isDirectory() || entry.name.startsWith("."))
+                continue;
+            const path = join(root, entry.name);
+            try {
+                await lstat(join(path, "SKILL.md"));
+            }
+            catch {
+                continue;
+            }
+            try {
+                const bundle = await readSkillBundle(path);
+                results.push({ path, name: bundle.name, hash: bundle.hash });
+            }
+            catch (e) {
+                results.push({ path, name: entry.name, error: e instanceof Error ? e.message : String(e) });
+            }
+        }
+    }
+    return results;
+}
+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`); }
+async function readInstallation(destination) {
+    try {
+        const record = JSON.parse(await readFile(recordPath(destination), "utf8"));
+        if (record.schemaVersion !== 1 || record.path !== destination)
+            throw new Error("Unsupported or mismatched installation record.");
+        return record;
+    }
+    catch (e) {
+        if (e.code === "ENOENT")
+            return undefined;
+        throw e;
+    }
+}
+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,21 @@
+import { type SkillBundle } from "./local-core/skills.js";
+import type { ResolvedSettings } from "./config.js";
+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>;
+    saveDraft(project: string, bundle: SkillBundle, expectedVersion: number, expectedRevision?: number): Promise<{
+        draftRevision: number;
+        [key: string]: unknown;
+    }>;
+    publish(project: string, name: string, expectedVersion: number, expectedRevision?: number): Promise<unknown>;
+}

package/dist/skills-client.js

@@ -0,0 +1,36 @@
+import { validateSkillBundle } from "./local-core/skills.js";
+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 Error(`Skills API ${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;
+    }
+    saveDraft(project, bundle, expectedVersion, expectedRevision) {
+        validateSkillBundle(bundle);
+        return this.request("/v1/skills", { method: "POST", body: JSON.stringify({ project, name: bundle.name, bundle, expectedVersion, expectedRevision }) });
+    }
+    publish(project, name, expectedVersion, expectedRevision) {
+        return this.request("/v1/skills/publish", { method: "POST", body: JSON.stringify({ project, name, expectedVersion, expectedRevision }) });
+    }
+}

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 scan [root ...] --json          Discover complete local skill bundles\n  sfora skills list --project <slug>           List cloud project skills\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,75 @@
+import { readFile } from "node:fs/promises";
+import { diffSkillBundles, installSkillBundle, readSkillBundle, scanLocalSkills, uninstallSkill, validateSkillBundle } from "./local-core/index.js";
+import { SkillsClient } from "./skills-client.js";
+export const SKILLS_HELP = `Skills:
+  sfora skills scan [root ...] --json          Discover complete local skill bundles
+  sfora skills list --project <slug>           List cloud project skills
+  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 === "scan") {
+        print(await scanLocalSkills(args.rest.length > 1 ? args.rest.slice(1) : undefined));
+        return;
+    }
+    if (verb === "uninstall") {
+        await uninstallSkill(need(first, "Installed folder"));
+        print({ uninstalled: first });
+        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 === "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);
+}