sfora-cli 0.14.0 → 0.16.0

package/dist/local-core/skill-index.js

@@ -0,0 +1,115 @@
+import { watch } from 'node:fs';
+import { resolve } from 'node:path';
+import { pathWithin } from './skill-service.js';
+/** Events are hints; periodic reconciliation repairs missed events and root changes. */
+export class SkillIndex {
+    service;
+    changed;
+    reconciliationMs;
+    watchers = [];
+    timer;
+    interval;
+    pending = new Set();
+    full = false;
+    running = false;
+    active;
+    closed = false;
+    started;
+    warnings = [];
+    constructor(service, changed = () => { }, reconciliationMs = 60_000) {
+        this.service = service;
+        this.changed = changed;
+        this.reconciliationMs = reconciliationMs;
+    }
+    start() {
+        return this.started ??= (async () => {
+            this.full = true;
+            await this.flush();
+            if (!this.closed) {
+                this.interval = setInterval(() => this.invalidate(), this.reconciliationMs);
+                this.interval.unref();
+            }
+        })();
+    }
+    async inventory() { await this.start(); return { ...await this.service.cachedInventory(), warnings: this.warnings }; }
+    invalidate(path) {
+        if (this.closed)
+            return;
+        const storePath = 'path' in this.service.store ? String(this.service.store.path) : undefined;
+        if (path && storePath && (path === storePath || path.startsWith(`${storePath}-`)))
+            return;
+        if (path && this.pending.size < 1000)
+            this.pending.add(path);
+        else
+            this.full = true;
+        if (!this.timer)
+            this.timer = setTimeout(() => { this.timer = undefined; void this.flush(); }, 150);
+    }
+    async configure() {
+        for (const watcher of this.watchers)
+            watcher.close();
+        this.watchers = [];
+        const sources = await this.service.discoverySources();
+        for (const source of sources.slice(0, 128)) {
+            try {
+                const watcher = watch(source.path, { recursive: true, persistent: false }, (_event, name) => this.invalidate(name ? resolve(source.path, String(name)) : undefined));
+                watcher.on('error', () => this.invalidate());
+                this.watchers.push(watcher);
+            }
+            catch { /* Missing roots are retried by reconciliation, never deleted from the catalog. */ }
+        }
+    }
+    async refresh() {
+        await this.start();
+        if (this.active)
+            await this.active;
+        this.full = true;
+        await this.flush();
+        return { ...await this.service.cachedInventory(), warnings: this.warnings };
+    }
+    flush() {
+        if (this.active)
+            return this.active;
+        this.active = this.perform().finally(() => { this.active = undefined; });
+        return this.active;
+    }
+    async perform() {
+        if (this.running || this.closed)
+            return;
+        this.running = true;
+        const full = this.full;
+        this.full = false;
+        const paths = [...this.pending];
+        this.pending.clear();
+        let failed = false;
+        try {
+            const catalog = await this.service.store.read();
+            const ids = catalog.locations.filter(l => paths.some(p => pathWithin(l.path, p))).map(l => l.id);
+            const unknown = paths.some(p => !catalog.locations.some(l => pathWithin(l.path, p)));
+            if (full || unknown) {
+                const result = await this.service.inventory();
+                this.warnings = result.warnings;
+                await this.configure();
+            }
+            else if (ids.length)
+                await this.service.refreshLocations(ids);
+            if (!this.closed)
+                this.changed();
+        }
+        catch (error) {
+            failed = true;
+            this.warnings = [error.message];
+            this.full = true;
+            if (!this.closed)
+                this.changed();
+        }
+        finally {
+            this.running = false;
+        }
+        // Do not drop events received during inspection, including external edits during our own writes.
+        if ((this.pending.size || (this.full && !failed)) && !this.closed && !this.timer)
+            this.timer = setTimeout(() => { this.timer = undefined; void this.flush(); }, 150);
+    }
+    close() { this.closed = true; clearTimeout(this.timer); clearInterval(this.interval); for (const watcher of this.watchers)
+        watcher.close(); this.watchers = []; }
+}

package/dist/local-core/skill-local-executor.d.ts

@@ -0,0 +1,18 @@
+import { type PublishedSkillSnapshot } from './skill-sync.js';
+import { SkillOperationJournal, type SkillTransferOperation } from './skill-operations.js';
+import type { SkillStore } from './skill-store.js';
+export interface SkillLocalPorts {
+    snapshot(project: string, name: string): Promise<PublishedSkillSnapshot>;
+    /** Fault/telemetry seam, after durable steps; production never infers success from it. */
+    checkpoint?: (phase: string) => Promise<void>;
+}
+/** Recoverable local installation. Old bytes remain in an operation-specific backup.
+ * Destination creation and every file publication are exclusive: no foreign file is overwritten. */
+export declare class SkillLocalExecutor {
+    readonly store: SkillStore;
+    readonly journal: SkillOperationJournal;
+    readonly cloud: SkillLocalPorts;
+    constructor(store: SkillStore, journal: SkillOperationJournal, cloud: SkillLocalPorts);
+    apply(id: string, recover?: boolean): Promise<SkillTransferOperation>;
+    private run;
+}

package/dist/local-core/skill-local-executor.js

@@ -0,0 +1,249 @@
+import { randomUUID } from 'node:crypto';
+import { constants } from 'node:fs';
+import { mkdir, lstat, open, readdir, realpath, rename, rm, rmdir } from 'node:fs/promises';
+import { basename, dirname, join, isAbsolute } from 'node:path';
+import { atomicCreate, atomicWrite, sha256, withLocalLock } from './files.js';
+import { inspectSkillTarget, readInstallation, readSkillBundle } from './skills.js';
+import { assertSkillBindingSnapshot, planSkillInstallation, planSkillTransfer, validatePublishedSkillSnapshot } from './skill-sync.js';
+import { operationDestination } from './skill-operations.js';
+const exists = async (path) => lstat(path).catch(e => { if (e.code === 'ENOENT')
+    return null; throw e; });
+const readRegular = async (path, limit) => {
+    const handle = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW);
+    try {
+        const info = await handle.stat();
+        if (!info.isFile() || info.size > limit)
+            throw new Error('Invalid operation artifact.');
+        return await handle.readFile();
+    }
+    finally {
+        await handle.close();
+    }
+};
+const receiptHash = (receipt) => receipt ? sha256(JSON.stringify(receipt)) : null;
+async function directoryProof(path) {
+    const info = await lstat(path, { bigint: true });
+    if (!info.isDirectory() || info.isSymbolicLink())
+        throw new Error('Destination is no longer a directory.');
+    return { dev: String(info.dev), ino: String(info.ino) };
+}
+/** Recoverable local installation. Old bytes remain in an operation-specific backup.
+ * Destination creation and every file publication are exclusive: no foreign file is overwritten. */
+export class SkillLocalExecutor {
+    store;
+    journal;
+    cloud;
+    constructor(store, journal, cloud) {
+        this.store = store;
+        this.journal = journal;
+        this.cloud = cloud;
+    }
+    async apply(id, recover = false) {
+        const op = await this.journal.claim(id, recover);
+        if (['succeeded', 'cancelled'].includes(op.status))
+            return op;
+        try {
+            const plan = op.plan;
+            if (plan.kind === 'skill-transfer-preview' && plan.direction !== 'pull')
+                throw new Error('Use the push executor for this plan.');
+            const destination = operationDestination(plan);
+            if (!isAbsolute(destination) || join(await realpath(dirname(destination)), basename(destination)) !== destination)
+                throw new Error('Destination parent changed since review.');
+            const lock = `${destination}.sfora-lock`;
+            if (recover && await exists(lock)) {
+                const info = await lstat(lock);
+                if (!info.isDirectory() || info.isSymbolicLink())
+                    throw new Error('Unrecognized local lock; preserved.');
+                const entries = await readdir(lock);
+                if (entries.length !== 1 || entries[0] !== 'operation.json')
+                    throw new Error('Local lock ownership is unknown; preserved for inspection.');
+                const owner = JSON.parse((await readRegular(join(lock, 'operation.json'), 1024)).toString());
+                if (owner.id !== op.id)
+                    throw new Error('Local lock belongs to another operation.');
+                await rm(join(lock, 'operation.json'));
+                await rmdir(lock);
+            }
+            return await withLocalLock(destination, async () => {
+                await atomicCreate(join(lock, 'operation.json'), JSON.stringify({ id: op.id }));
+                return await this.run(op, destination);
+            });
+        }
+        catch (error) {
+            await this.journal.finish(id, 'needs-attention', error.message);
+            throw error;
+        }
+    }
+    async run(op, destination) {
+        const plan = op.plan;
+        if (plan.kind === 'skill-transfer-preview' && plan.direction !== 'pull')
+            throw new Error('Not a local plan.');
+        const artifactDirectory = join(dirname(this.journal.path), 'operation-artifacts', op.id);
+        const artifact = join(artifactDirectory, 'snapshot.json');
+        const backup = plan.kind === 'skill-transfer-preview' ? join(dirname(destination), `.${basename(destination)}.sfora-${op.id}.previous`) : undefined;
+        let local = op.local;
+        if (local && (local.destination !== destination || local.backup !== backup))
+            throw new Error('Operation checkpoint does not match its destination.');
+        let remote;
+        if (local) {
+            remote = JSON.parse((await readRegular(artifact, 30 * 1024 * 1024)).toString());
+            validatePublishedSkillSnapshot(remote);
+        }
+        else {
+            const locator = plan.kind === 'skill-install-preview' ? plan.locator : plan.binding.locator;
+            remote = await this.cloud.snapshot(locator.project, locator.name);
+            validatePublishedSkillSnapshot(remote);
+        }
+        if (remote.revision.hash !== plan.expected.remote.hash || remote.revision.cloudVersion !== plan.expected.remote.cloudVersion)
+            throw new Error('Published revision differs from the reviewed plan.');
+        if (plan.kind === 'skill-transfer-preview')
+            assertSkillBindingSnapshot(plan.binding, remote);
+        else if (JSON.stringify({ ...remote.remote, accountId: remote.accountId }) !== JSON.stringify(plan.source))
+            throw new Error('Installation source identity changed.');
+        const before = await this.store.read();
+        if (plan.kind === 'skill-transfer-preview') {
+            const binding = before.bindings.find(b => b.id === plan.binding.id), location = before.locations.find(l => l.id === plan.location.id);
+            if (!binding || !location || location.path !== destination || location.skillId !== binding.localSkillId
+                || JSON.stringify({ ...binding, baseline: plan.binding.baseline }) !== JSON.stringify(plan.binding)
+                || (!op.confirmedRevision && JSON.stringify(binding.baseline) !== JSON.stringify(plan.binding.baseline)))
+                throw new Error('Binding or location changed since review.');
+        }
+        else {
+            const location = before.locations.find(l => l.path === destination);
+            if (location && before.bindings.some(b => b.localSkillId === location.skillId && b.accountId === remote.accountId && b.remote.deployment === remote.remote.deployment && b.remote.organizationId === remote.remote.organizationId && b.remote.projectId === remote.remote.projectId && b.remote.skillId !== remote.remote.skillId))
+                throw new Error('Destination history belongs to another cloud identity. Choose a new destination.');
+        }
+        const checkpoint = async (next) => { await this.journal.checkpoint(op.id, next); local = next; await this.cloud.checkpoint?.(next.phase); };
+        if (!local) {
+            const target = await inspectSkillTarget(destination);
+            const current = plan.kind === 'skill-install-preview' ? planSkillInstallation(remote, destination, target)
+                : planSkillTransfer({ direction: 'pull', binding: plan.binding, location: plan.location, remote, local: { state: 'available', bundle: await readSkillBundle(destination) }, ownership: target.ownership });
+            if (JSON.stringify(current) !== JSON.stringify(plan))
+                throw new Error('Local or cloud state changed since review.');
+            await mkdir(artifactDirectory, { recursive: true, mode: 0o700 });
+            if (await exists(artifact)) {
+                const previous = JSON.parse((await readRegular(artifact, 30 * 1024 * 1024)).toString());
+                if (JSON.stringify(previous) !== JSON.stringify(remote))
+                    throw new Error('Staged snapshot differs; preserve it and create a new plan.');
+            }
+            else
+                await atomicCreate(artifact, JSON.stringify(remote));
+            await checkpoint({ phase: 'prepared', destination, backup, receiptBefore: receiptHash(await readInstallation(destination)) });
+        }
+        if (local.phase === 'prepared') {
+            if (backup) {
+                if (await exists(backup)) {
+                    if (await exists(destination))
+                        throw new Error('Both backup and destination exist without an ownership checkpoint; preserved for inspection.');
+                }
+                else {
+                    const target = await inspectSkillTarget(destination);
+                    if (target.ownership !== 'managed' || target.hash !== plan.expected.localHash || receiptHash(target.receipt) !== local.receiptBefore)
+                        throw new Error('Managed target changed before replacement.');
+                    await rename(destination, backup);
+                    await this.cloud.checkpoint?.('after-backup-rename');
+                }
+                if ((await readSkillBundle(backup, basename(destination))).hash !== plan.expected.localHash)
+                    throw new Error('Backup contains external changes; preserved for inspection.');
+            }
+            else if (await exists(destination))
+                throw new Error('Installation destination became occupied.');
+            await checkpoint({ ...local, phase: 'backed-up' });
+        }
+        if (local.phase === 'backed-up') {
+            if (await exists(destination))
+                throw new Error('Destination exists without a recorded owner. Its contents were preserved; inspect before recovery.');
+            await mkdir(destination, { mode: 0o700 });
+            await checkpoint({ ...local, phase: 'owned', directory: await directoryProof(destination) });
+        }
+        const verifyOwner = async () => {
+            if (JSON.stringify(await directoryProof(destination)) !== JSON.stringify(local.directory))
+                throw new Error('Destination was replaced by another process.');
+            if (join(await realpath(dirname(destination)), basename(destination)) !== destination)
+                throw new Error('Destination parent changed.');
+        };
+        await verifyOwner();
+        if (local.phase === 'owned') {
+            for (const file of remote.bundle.files) {
+                await verifyOwner();
+                let parent = destination;
+                for (const part of file.path.split('/').slice(0, -1)) {
+                    parent = join(parent, part);
+                    await mkdir(parent).catch(e => { if (e.code !== 'EEXIST')
+                        throw e; });
+                    const info = await lstat(parent);
+                    if (!info.isDirectory() || info.isSymbolicLink() || await realpath(parent) !== parent)
+                        throw new Error('Skill subdirectory changed; refusing to follow a link.');
+                }
+                const path = join(destination, file.path);
+                try {
+                    await atomicCreate(path, Buffer.from(file.contentBase64, 'base64'), file.executable ? 0o755 : 0o644);
+                }
+                catch (error) {
+                    if (error.code !== 'EEXIST')
+                        throw error;
+                    const bytes = await readRegular(path, 5 * 1024 * 1024);
+                    const info = await lstat(path);
+                    if (sha256(bytes) !== file.sha256 || !!(info.mode & 0o111) !== file.executable)
+                        throw new Error(`External changes in ${file.path}; preserved instead of overwritten.`);
+                }
+                await this.cloud.checkpoint?.(`file:${file.path}`);
+            }
+            await verifyOwner();
+            if ((await readSkillBundle(destination)).hash !== remote.bundle.hash)
+                throw new Error('Installed files include external changes; no baseline was recorded.');
+            const record = { schemaVersion: 1, path: destination, name: basename(destination), hash: remote.bundle.hash, installedAt: op.createdAt, source: `${remote.remote.deployment}/${remote.locator.project}/${remote.locator.name}`, sourceVersion: remote.revision.cloudVersion, operationId: op.id };
+            const receipt = await readInstallation(destination);
+            const receiptPath = join(dirname(destination), `.${basename(destination)}.sfora-install.json`);
+            if (JSON.stringify(receipt) !== JSON.stringify(record)) {
+                if (receiptHash(receipt) !== local.receiptBefore)
+                    throw new Error('Installation ownership record changed.');
+                if (receipt)
+                    await atomicWrite(receiptPath, JSON.stringify(record));
+                else
+                    await atomicCreate(receiptPath, JSON.stringify(record));
+            }
+            await checkpoint({ ...local, phase: 'copied' });
+        }
+        await verifyOwner();
+        if ((await readSkillBundle(destination)).hash !== remote.bundle.hash)
+            throw new Error('Local files changed before confirmation; preserved.');
+        const finalReceipt = await readInstallation(destination);
+        if (finalReceipt?.operationId !== op.id || finalReceipt.hash !== remote.bundle.hash)
+            throw new Error('Installation ownership record changed before confirmation.');
+        await this.journal.confirm(op.id, remote.revision);
+        await this.store.transaction(c => {
+            if (plan.kind === 'skill-transfer-preview') {
+                const current = c.bindings.find(b => b.id === plan.binding.id);
+                if (!current || JSON.stringify({ ...current, baseline: plan.binding.baseline }) !== JSON.stringify(plan.binding))
+                    throw new Error('Binding changed during installation.');
+                if (JSON.stringify(current.baseline) === JSON.stringify(plan.binding.baseline))
+                    current.baseline = { ...remote.revision };
+            }
+            else {
+                let root = c.roots.find(r => r.path === destination);
+                if (!root) {
+                    root = { id: randomUUID(), path: destination, label: basename(destination), depth: 0, scope: 'custom' };
+                    c.roots.push(root);
+                }
+                let location = c.locations.find(l => l.path === destination);
+                if (!location) {
+                    const identity = { id: randomUUID(), createdAt: Date.now() };
+                    c.identities.push(identity);
+                    location = { id: randomUUID(), skillId: identity.id, path: destination, createdAt: Date.now(), aliases: [] };
+                    c.locations.push(location);
+                }
+                if (!location.aliases.some(a => a.sourceId === root.id))
+                    location.aliases.push({ sourceId: root.id, path: destination, label: root.label, kind: 'custom' });
+                const binding = c.bindings.find(b => b.localSkillId === location.skillId && b.accountId === remote.accountId && b.remote.deployment === remote.remote.deployment && b.remote.organizationId === remote.remote.organizationId && b.remote.projectId === remote.remote.projectId);
+                if (binding && binding.remote.skillId !== remote.remote.skillId)
+                    throw new Error('A different cloud identity claimed this destination.');
+                if (!binding)
+                    c.bindings.push({ id: randomUUID(), localSkillId: location.skillId, remote: { ...remote.remote }, accountId: remote.accountId, locator: { ...remote.locator }, baseline: { ...remote.revision } });
+                else if (!op.confirmedRevision)
+                    binding.baseline = { ...remote.revision };
+            }
+        });
+        // Retain the original directory and staged snapshot for explicit inspection.
+        return this.journal.finish(op.id, 'succeeded');
+    }
+}

package/dist/local-core/skill-operations.d.ts

@@ -0,0 +1,61 @@
+import { readSkillBundle } from './skills.js';
+import { type PublishedSkillSnapshot, type SkillTransferPlan, type SkillInstallPlan } from './skill-sync.js';
+import type { SkillStore } from './skill-store.js';
+import type { SkillRevision } from './skill-domain.js';
+export type SkillOperationPlan = SkillTransferPlan | SkillInstallPlan;
+export interface LocalOperationCheckpoint {
+    phase: "prepared" | "backed-up" | "owned" | "copied";
+    destination: string;
+    backup?: string;
+    directory?: {
+        dev: string;
+        ino: string;
+    };
+    receiptBefore: string | null;
+}
+export declare const operationDirection: (plan: SkillOperationPlan) => "push" | "pull" | "install";
+export declare const operationRemote: (plan: SkillOperationPlan) => import("./skill-domain.js").CloudSkillIdentity & {
+    projectId: string;
+};
+export declare const operationDestination: (plan: SkillOperationPlan) => string;
+export interface SkillTransferOperation {
+    id: string;
+    createdAt: number;
+    updatedAt: number;
+    plan: SkillOperationPlan;
+    status: 'planned' | 'running' | 'needs-attention' | 'succeeded' | 'cancelled';
+    ownerPid?: number;
+    error?: string;
+    confirmedRevision?: SkillRevision;
+    local?: LocalOperationCheckpoint;
+}
+/** Separate versioned journal: intent commits before network I/O. A dead worker never retains a SQLite lock. */
+export declare class SkillOperationJournal {
+    readonly path: string;
+    constructor(path: string);
+    private access;
+    private decode;
+    list(): Promise<SkillTransferOperation[]>;
+    create(plan: SkillOperationPlan): Promise<SkillTransferOperation>;
+    confirm(id: string, revision: SkillRevision): Promise<void>;
+    checkpoint(id: string, local: LocalOperationCheckpoint): Promise<void>;
+    claim(id: string, recover?: boolean): Promise<SkillTransferOperation>;
+    cancel(id: string): Promise<SkillTransferOperation>;
+    finish(id: string, status: 'succeeded' | 'needs-attention', error?: string): Promise<SkillTransferOperation>;
+}
+export interface SkillPushPorts {
+    snapshot(project: string, name: string): Promise<PublishedSkillSnapshot>;
+    saveDraft(project: string, bundle: Awaited<ReturnType<typeof readSkillBundle>>, version: number, draftRevision: number, skillId: string): Promise<{
+        draftRevision: number;
+    }>;
+    publish(project: string, name: string, version: number, draftRevision: number, skillId: string): Promise<unknown>;
+    read?: typeof readSkillBundle;
+}
+/** Idempotent by exact observed content/revision, never by names or a blind retry. */
+export declare class SkillPushExecutor {
+    readonly store: SkillStore;
+    readonly journal: SkillOperationJournal;
+    readonly cloud: SkillPushPorts;
+    constructor(store: SkillStore, journal: SkillOperationJournal, cloud: SkillPushPorts);
+    apply(id: string, recover?: boolean): Promise<SkillTransferOperation>;
+}