sfora-cli 0.15.0 → 0.16.0

package/dist/skills-command.js

@@ -1,9 +1,33 @@
-import { readFile } from "node:fs/promises";
-import { diffSkillBundles, installSkillBundle, readSkillBundle, scanLocalSkills, uninstallSkill, validateSkillBundle } from "./local-core/index.js";
+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>]
@@ -21,8 +45,35 @@ export async function runSkillsCommand(args, settings) {
     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));
+    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") {
@@ -30,6 +81,97 @@ export async function runSkillsCommand(args, settings) {
         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);
@@ -38,6 +180,12 @@ export async function runSkillsCommand(args, settings) {
     }
     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;

package/dist/version.d.ts

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

package/dist/version.js

@@ -1,2 +1,2 @@
 // Generated by scripts/sync-format.mjs from package.json.
-export const CLI_VERSION = "0.15.0";
+export const CLI_VERSION = "0.16.0";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sfora-cli",
-  "version": "0.15.0",
+  "version": "0.16.0",
   "type": "module",
   "description": "Your sfora workspace as a markdown filesystem \u2014 a CLI + MCP server. Post/task/doc, ls/cat/grep, and a shell so agents operate sfora natively.",
   "keywords": [
@@ -51,7 +51,7 @@
     "typescript": "^5.9.3"
   },
   "engines": {
-    "node": ">=20"
+    "node": ">=22.13.0"
   },
   "exports": {
     ".": {