sfora-cli 0.14.0 → 0.16.0

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

@@ -0,0 +1,157 @@
+import { randomUUID } from 'node:crypto';
+import { realpath, stat } from 'node:fs/promises';
+import { basename, relative, isAbsolute } from 'node:path';
+import { discoverSkills, defaultSkillSources } from './skill-discovery.js';
+import { projectSkillSources } from './skill-adapters.js';
+import { SQLiteSkillStore } from './skill-store.js';
+import { readSkillBundle } from './skills.js';
+import { LocalConflictError } from './files.js';
+export const pathWithin = (root, path) => { const rel = relative(root, path); return rel === '' || (rel !== '..' && !rel.startsWith('../') && !rel.startsWith('..\\') && !isAbsolute(rel)); };
+const filesystemPorts = {
+    discover: discoverSkills,
+    resolveDirectory: async (path) => { const canonical = await realpath(path); if (!(await stat(canonical)).isDirectory())
+        throw new Error('Choose a directory for skill discovery.'); return canonical; },
+    inspect: readSkillBundle,
+};
+function rootSources(roots) {
+    return roots.flatMap(root => root.scope === 'project'
+        ? projectSkillSources(root.path).map(source => ({ ...source, id: `${root.id}:${source.id}`, label: `${root.label} · ${source.label}` }))
+        : [{ ...root, kind: 'custom' }]);
+}
+/** Node service shared by CLI and desktop. Its IDs are identity, not renderer grants. */
+export class SkillService {
+    store;
+    sources;
+    ports;
+    constructor(store = new SQLiteSkillStore(), sources = defaultSkillSources, ports = filesystemPorts) {
+        this.store = store;
+        this.sources = sources;
+        this.ports = ports;
+    }
+    async registerRoot(path, label, scope = "custom") {
+        const canonical = await this.ports.resolveDirectory(path);
+        const name = label?.trim() || basename(canonical) || canonical;
+        if (name.length > 200)
+            throw new Error('Folder label must be at most 200 characters.');
+        return this.store.transaction(c => {
+            const found = c.roots.find(r => r.path === canonical);
+            if (found) {
+                found.label = name;
+                found.scope = scope;
+                return { ...found };
+            }
+            const root = { id: randomUUID(), path: canonical, label: name, depth: 4, scope };
+            c.roots.push(root);
+            return root;
+        });
+    }
+    async roots() { return (await this.store.read()).roots; }
+    async removeRoot(id) {
+        return this.store.transaction(c => { if (!c.roots.some(r => r.id === id))
+            throw new Error('Registered folder not found.'); c.roots = c.roots.filter(r => r.id !== id); });
+    }
+    async inventory() {
+        const before = await this.store.read();
+        const sources = [...this.sources(), ...rootSources(before.roots)];
+        const result = await this.ports.discover(sources);
+        const now = Date.now();
+        return this.store.transaction(c => {
+            // Scanning happens outside the lock. Do not commit results for a changed root set,
+            // or let an older scan overwrite observations from a concurrent newer transaction.
+            if (c.revision !== before.revision)
+                throw new LocalConflictError('Skill catalog changed during discovery. Refresh to use the latest inventory.');
+            const active = new Set(sources.map(s => s.id ?? s.path));
+            for (const found of result.skills) {
+                let location = c.locations.find(l => l.path === found.path);
+                if (!location) {
+                    const identity = { id: randomUUID(), createdAt: now };
+                    c.identities.push(identity);
+                    location = { id: randomUUID(), skillId: identity.id, path: found.path, aliases: [], createdAt: now };
+                    c.locations.push(location);
+                }
+                // Retain provenance aliases, but only active roots contribute to the displayed view.
+                for (const alias of found.aliases) {
+                    const old = location.aliases.find(a => a.sourceId === alias.sourceId && a.path === alias.path);
+                    if (old)
+                        Object.assign(old, alias);
+                    else
+                        location.aliases.push(alias);
+                }
+                c.observations = c.observations.filter(o => o.locationId !== location.id);
+                c.observations.push({ locationId: location.id, name: found.name, observedAt: now, hash: found.hash, fileCount: found.fileCount, error: found.error, availability: 'available' });
+            }
+            const observed = new Set(result.skills.map(s => s.path));
+            const locations = c.locations.filter(l => l.aliases.some(a => active.has(a.sourceId)));
+            for (const location of locations) {
+                if (observed.has(location.path))
+                    continue;
+                const old = c.observations.find(o => o.locationId === location.id);
+                if (old) {
+                    old.availability = 'unavailable';
+                    old.error = 'Not observed in this scan. The folder may be missing or inaccessible; its last known metadata is retained.';
+                }
+            }
+            const skills = locations.map(l => {
+                const o = c.observations.find(o => o.locationId === l.id);
+                const aliases = l.aliases.filter(a => active.has(a.sourceId));
+                return { skillId: l.skillId, locationId: l.id, path: l.path, name: o?.name ?? basename(l.path), sources: [...new Set(aliases.map(a => a.label))], aliases, hash: o?.hash, fileCount: o?.fileCount, error: o?.error ?? (!o ? 'Observation needs refresh.' : undefined), availability: o?.availability ?? 'unavailable' };
+            }).sort((a, b) => a.name.localeCompare(b.name) || a.path.localeCompare(b.path));
+            return { skills, warnings: result.warnings };
+        });
+    }
+    /** Warm reads use persisted observations; explicit inventory remains a full reconciliation. */
+    async cachedInventory() {
+        const c = await this.store.read();
+        const active = new Set([...this.sources(), ...rootSources(c.roots)].map(s => s.id ?? s.path));
+        const skills = c.locations.filter(l => l.aliases.some(a => active.has(a.sourceId))).map(l => {
+            const o = c.observations.find(o => o.locationId === l.id);
+            const aliases = l.aliases.filter(a => active.has(a.sourceId));
+            return { skillId: l.skillId, locationId: l.id, path: l.path, name: o?.name ?? basename(l.path), sources: [...new Set(aliases.map(a => a.label))], aliases, hash: o?.hash, fileCount: o?.fileCount, error: o?.error ?? (!o ? 'Observation needs refresh.' : undefined), availability: o?.availability ?? 'unavailable' };
+        }).sort((a, b) => a.name.localeCompare(b.name) || a.path.localeCompare(b.path));
+        return { skills, warnings: [] };
+    }
+    async discoverySources() { return [...this.sources(), ...rootSources((await this.store.read()).roots)]; }
+    /** Re-read only affected known locations, preserving identity and last known bytes on failure. */
+    async refreshLocations(ids) {
+        const before = await this.store.read();
+        const updates = await Promise.all(before.locations.filter(l => ids.includes(l.id)).map(async (l) => {
+            try {
+                const bundle = await this.ports.inspect(l.path);
+                return { locationId: l.id, name: bundle.name, hash: bundle.hash, fileCount: bundle.files.length, observedAt: Date.now(), availability: 'available' };
+            }
+            catch (error) {
+                return { ...before.observations.find(o => o.locationId === l.id), locationId: l.id, name: basename(l.path), observedAt: Date.now(), availability: 'unavailable', error: error.message };
+            }
+        }));
+        await this.store.transaction(c => {
+            if (c.revision !== before.revision)
+                throw new LocalConflictError('Skill catalog changed during refresh.');
+            for (const update of updates) {
+                c.observations = c.observations.filter(o => o.locationId !== update.locationId);
+                c.observations.push(update);
+            }
+        });
+        return this.cachedInventory();
+    }
+    /** Metadata-only explicit relocation. Never guesses identity from a name/hash or moves files. */
+    async relocateLocation(id, path) {
+        const canonical = await this.ports.resolveDirectory(path);
+        await this.ports.inspect(canonical);
+        return this.store.transaction(c => {
+            const location = c.locations.find(l => l.id === id);
+            if (!location)
+                throw new Error('Skill location not found.');
+            if (c.locations.some(l => l.path === canonical && l.id !== id))
+                throw new Error('Destination is already associated with another skill location.');
+            const sources = [...this.sources(), ...rootSources(c.roots)];
+            const scopes = sources.filter(s => pathWithin(s.path, canonical));
+            if (!scopes.length)
+                throw new Error('Register the destination folder before relocating this skill.');
+            location.path = canonical;
+            location.aliases = scopes.map(s => ({ sourceId: ('id' in s && s.id) || s.path, path: canonical, label: s.label, kind: ('kind' in s && s.kind) || 'custom' }));
+            c.observations = c.observations.filter(o => o.locationId !== id);
+            return { ...location };
+        });
+    }
+    async rebuild() { await this.store.transaction(c => { c.observations = []; }); return this.inventory(); }
+}

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

@@ -0,0 +1,34 @@
+import type { SkillCloudBinding, SkillIdentity, SkillLocation, SkillObservation } from './skill-domain.js';
+export interface RegisteredSkillRoot {
+    id: string;
+    path: string;
+    label: string;
+    depth: number;
+    scope?: "custom" | "project";
+}
+export interface SkillCatalog {
+    schemaVersion: 2;
+    revision: number;
+    roots: RegisteredSkillRoot[];
+    identities: SkillIdentity[];
+    locations: SkillLocation[];
+    observations: SkillObservation[];
+    bindings: SkillCloudBinding[];
+}
+export interface SkillStore {
+    read(): Promise<SkillCatalog>;
+    transaction<T>(change: (catalog: SkillCatalog) => T): Promise<T>;
+}
+export declare const defaultSkillCatalogPath: () => string;
+/** Fail closed rather than silently dropping durable records from a malformed/future store. */
+export declare function validateSkillCatalog(value: unknown): asserts value is SkillCatalog;
+/** SQLite owns cross-process locking and crash rollback; no persistent lock directories. */
+export declare class SQLiteSkillStore implements SkillStore {
+    readonly path: string;
+    constructor(path?: string);
+    private exists;
+    private version;
+    private readDatabase;
+    read(): Promise<SkillCatalog>;
+    transaction<T>(change: (catalog: SkillCatalog) => T): Promise<T>;
+}

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

@@ -0,0 +1,187 @@
+import { randomUUID } from 'node:crypto';
+import { setTimeout as delay } from 'node:timers/promises';
+import { DatabaseSync } from 'node:sqlite';
+import { lstat, mkdir, open } from 'node:fs/promises';
+import { dirname, join, isAbsolute } from 'node:path';
+import { homedir } from 'node:os';
+export const defaultSkillCatalogPath = () => join(homedir(), '.sfora/skills/catalog.sqlite');
+const empty = () => ({ schemaVersion: 2, revision: 0, roots: [], identities: [], locations: [], observations: [], bindings: [] });
+const string = (value) => typeof value === 'string' && value.length > 0 && value.length <= 8192;
+const time = (value) => Number.isSafeInteger(value) && Number(value) >= 0;
+/** Fail closed rather than silently dropping durable records from a malformed/future store. */
+export function validateSkillCatalog(value) {
+    const c = value;
+    if (!c || c.schemaVersion !== 2)
+        throw new Error('Unsupported skill catalog schema. Keep this file and use a compatible Sfora version.');
+    if (!time(c.revision) || ![c.roots, c.identities, c.locations, c.observations, c.bindings].every(v => Array.isArray(v) && v.length <= 10000))
+        throw new Error('Invalid skill catalog structure. Original catalog was preserved.');
+    const unique = (values) => new Set(values).size === values.length;
+    if (!c.roots.every(r => r && string(r.id) && string(r.path) && isAbsolute(r.path) && string(r.label) && Number.isInteger(r.depth) && r.depth >= 0 && r.depth <= 6 && (r.scope === undefined || ["custom", "project"].includes(r.scope))) || !unique(c.roots.map(r => r.id)) || !unique(c.roots.map(r => r.path)))
+        throw new Error('Invalid registered skill roots.');
+    if (!c.identities.every(i => i && string(i.id) && time(i.createdAt)) || !unique(c.identities.map(i => i.id)))
+        throw new Error('Invalid skill identities.');
+    const identities = new Set(c.identities.map(i => i.id));
+    if (!c.locations.every(l => l && string(l.id) && identities.has(l.skillId) && string(l.path) && isAbsolute(l.path) && time(l.createdAt) && Array.isArray(l.aliases) && l.aliases.length <= 1000 && l.aliases.every(a => a && string(a.sourceId) && string(a.path) && isAbsolute(a.path) && string(a.label) && ['agent', 'cache', 'custom'].includes(a.kind))) || !unique(c.locations.map(l => l.id)) || !unique(c.locations.map(l => l.path)))
+        throw new Error('Invalid skill locations.');
+    const deployment = (value) => {
+        if (!string(value))
+            return false;
+        try {
+            const url = new URL(value);
+            return ['https:', 'http:'].includes(url.protocol) && !url.username && !url.password && url.origin === value;
+        }
+        catch {
+            return false;
+        }
+    };
+    if (!c.bindings.every(b => b && string(b.id) && identities.has(b.localSkillId) && string(b.accountId)
+        && b.remote && deployment(b.remote.deployment) && string(b.remote.organizationId) && string(b.remote.projectId) && string(b.remote.skillId)
+        && b.locator && string(b.locator.project) && string(b.locator.name)
+        && (b.baseline === undefined || (b.baseline && b.baseline.contentPolicy === 'bundle-v1' && /^[a-f0-9]{64}$/.test(b.baseline.hash)
+            && Number.isSafeInteger(b.baseline.cloudVersion) && Number(b.baseline.cloudVersion) > 0)))
+        || !unique(c.bindings.map(b => b.id))
+        || !unique(c.bindings.map(b => JSON.stringify([b.localSkillId, b.accountId, b.remote.deployment, b.remote.organizationId, b.remote.projectId]))))
+        throw new Error('Invalid skill cloud bindings.');
+    const locations = new Set(c.locations.map(l => l.id));
+    if (!c.observations.every(o => o && locations.has(o.locationId) && string(o.name) && time(o.observedAt) && ['available', 'unavailable'].includes(o.availability) && (o.hash === undefined || /^[a-f0-9]{64}$/.test(o.hash)) && (o.fileCount === undefined || time(o.fileCount)) && (o.error === undefined || typeof o.error === 'string')) || !unique(c.observations.map(o => o.locationId)))
+        throw new Error('Invalid skill observations.');
+}
+/** SQLite owns cross-process locking and crash rollback; no persistent lock directories. */
+export class SQLiteSkillStore {
+    path;
+    constructor(path = defaultSkillCatalogPath()) {
+        this.path = path;
+    }
+    async exists() {
+        const info = await lstat(this.path).catch(error => { if (error.code === 'ENOENT')
+            return null; throw error; });
+        if (!info)
+            return false;
+        if (!info.isFile() || info.isSymbolicLink())
+            throw new Error('Skill catalog must be a regular file, not a symbolic link.');
+        if (info.size > 64 * 1024 * 1024)
+            throw new Error('Skill catalog exceeds supported size.');
+        return true;
+    }
+    version(db) { return Number(db.prepare('PRAGMA user_version').get().user_version); }
+    readDatabase(db) {
+        if (this.version(db) === 0 && db.prepare("SELECT name FROM sqlite_master WHERE type='table'").all().length === 0)
+            return empty();
+        if (![1, 2].includes(this.version(db)))
+            throw new Error('Unsupported skill catalog schema. Keep this file and use a compatible Sfora version.');
+        const rows = (table) => db.prepare(`SELECT data FROM ${table} ORDER BY rowid`).all().map(row => JSON.parse(String(row.data)));
+        const catalog = { schemaVersion: 2, revision: Number(db.prepare("SELECT value FROM metadata WHERE key='revision'").get().value), roots: rows('roots'), identities: rows('identities'), locations: rows('locations'), observations: rows('observations'), bindings: this.version(db) === 1 ? [] : rows('bindings') };
+        validateSkillCatalog(catalog);
+        return catalog;
+    }
+    async read() {
+        if (!await this.exists())
+            return empty();
+        const db = new DatabaseSync(this.path, { readOnly: true });
+        try {
+            db.exec('PRAGMA busy_timeout=5000; BEGIN');
+            const catalog = this.readDatabase(db);
+            db.exec('COMMIT');
+            return catalog;
+        }
+        finally {
+            db.close();
+        }
+    }
+    async transaction(change) {
+        await mkdir(dirname(this.path), { recursive: true, mode: 0o700 });
+        const exists = await this.exists();
+        if (!exists) {
+            const handle = await open(this.path, 'ax', 0o600).catch(error => { if (error.code === 'EEXIST')
+                return null; throw error; });
+            await handle?.close();
+        }
+        await this.exists();
+        const db = new DatabaseSync(this.path);
+        try {
+            db.exec('PRAGMA busy_timeout=5000; PRAGMA foreign_keys=ON;');
+            // Changing journal mode on first open can return SQLITE_BUSY without using
+            // busy_timeout. Retry only before any user mutation or transaction has begun.
+            const deadline = Date.now() + 5000;
+            for (;;) {
+                try {
+                    const version = this.version(db);
+                    if (![0, 1, 2].includes(version))
+                        throw new Error('Unsupported skill catalog schema. Keep this file and use a compatible Sfora version.');
+                    // VACUUM INTO includes committed WAL pages. Reserve private permissions
+                    // before SQLite writes the backup; never copy a live database file.
+                    if (version === 1) {
+                        this.readDatabase(db);
+                        const backupPath = `${this.path}.v1-${randomUUID()}.sqlite`;
+                        const backup = await open(backupPath, 'ax', 0o600);
+                        await backup.close();
+                        db.prepare('VACUUM INTO ?').run(backupPath);
+                    }
+                    db.exec('PRAGMA journal_mode=WAL; PRAGMA synchronous=FULL; BEGIN IMMEDIATE;');
+                    break;
+                }
+                catch (error) {
+                    if (![5, 6].includes(Number(error.errcode)) || Date.now() >= deadline)
+                        throw error;
+                    await delay(25);
+                }
+            }
+            if (this.version(db) === 0) {
+                if (db.prepare("SELECT name FROM sqlite_master WHERE type='table'").all().length)
+                    throw new Error('Unrecognized skill catalog; existing tables were preserved.');
+                db.exec(`CREATE TABLE metadata (key TEXT PRIMARY KEY, value INTEGER NOT NULL);
+          INSERT INTO metadata VALUES ('revision',0);
+          CREATE TABLE roots (id TEXT PRIMARY KEY, data TEXT NOT NULL);
+          CREATE TABLE identities (id TEXT PRIMARY KEY, data TEXT NOT NULL);
+          CREATE TABLE locations (id TEXT PRIMARY KEY, skill_id TEXT NOT NULL REFERENCES identities(id), data TEXT NOT NULL);
+          CREATE TABLE observations (id TEXT PRIMARY KEY REFERENCES locations(id), data TEXT NOT NULL);
+          PRAGMA user_version=1;`);
+            }
+            if (this.version(db) === 1) {
+                db.exec(`CREATE TABLE bindings (id TEXT PRIMARY KEY, skill_id TEXT NOT NULL REFERENCES identities(id), data TEXT NOT NULL);
+          PRAGMA user_version=2;`);
+            }
+            const catalog = this.readDatabase(db);
+            const result = change(catalog);
+            if (result && typeof result.then === "function")
+                throw new Error("Skill catalog transactions must be synchronous.");
+            catalog.revision++;
+            validateSkillCatalog(catalog);
+            // Metadata tables are small; synchronize changed rows under one transaction.
+            // The service never removes durable identities during observation rebuilds.
+            const sync = (table, values) => {
+                const ids = new Set(values.map(v => v.id));
+                const remove = db.prepare(`DELETE FROM ${table} WHERE id=?`);
+                for (const row of db.prepare(`SELECT id FROM ${table}`).all())
+                    if (!ids.has(String(row.id)))
+                        remove.run(String(row.id));
+                const statement = db.prepare((table === 'locations' || table === 'bindings')
+                    ? `INSERT INTO ${table}(id,skill_id,data) VALUES (?,?,?) ON CONFLICT(id) DO UPDATE SET skill_id=excluded.skill_id,data=excluded.data WHERE data!=excluded.data`
+                    : `INSERT INTO ${table}(id,data) VALUES (?,?) ON CONFLICT(id) DO UPDATE SET data=excluded.data WHERE data!=excluded.data`);
+                for (const row of values)
+                    if ((table === 'locations' || table === 'bindings'))
+                        statement.run(row.id, row.skillId, row.data);
+                    else
+                        statement.run(row.id, row.data);
+            };
+            sync('roots', catalog.roots.map(r => ({ id: r.id, data: JSON.stringify(r) })));
+            sync('identities', catalog.identities.map(r => ({ id: r.id, data: JSON.stringify(r) })));
+            sync('locations', catalog.locations.map(r => ({ id: r.id, skillId: r.skillId, data: JSON.stringify(r) })));
+            sync('observations', catalog.observations.map(r => ({ id: r.locationId, data: JSON.stringify(r) })));
+            sync('bindings', catalog.bindings.map(r => ({ id: r.id, skillId: r.localSkillId, data: JSON.stringify(r) })));
+            db.prepare("UPDATE metadata SET value=? WHERE key='revision'").run(catalog.revision);
+            db.exec('COMMIT');
+            return result;
+        }
+        catch (error) {
+            try {
+                db.exec('ROLLBACK');
+            }
+            catch { }
+            throw error;
+        }
+        finally {
+            db.close();
+        }
+    }
+}

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

@@ -0,0 +1,132 @@
+import type { SkillCloudBinding, SkillRevision } from './skill-domain.js';
+import type { SkillStore } from './skill-store.js';
+import { type SkillBundle, type inspectSkillTarget } from './skills.js';
+export interface SkillCloudScope {
+    deployment: string;
+    accountId: string;
+    organizationId: string;
+}
+export interface PublishedSkillSnapshot {
+    remote: SkillCloudBinding['remote'];
+    accountId: string;
+    locator: SkillCloudBinding['locator'];
+    revision: SkillRevision;
+    draftRevision: number;
+    hasDraft: boolean;
+    draftHash?: string;
+    supportsIdentityGuards?: boolean;
+    bundle: SkillBundle;
+}
+export type SkillTransferPlan = ReturnType<typeof planSkillTransfer>;
+/** A new installation needs an explicitly selected empty destination, not a guessed name match. */
+export declare function planSkillInstallation(remote: PublishedSkillSnapshot, destination: string, target: Awaited<ReturnType<typeof inspectSkillTarget>>): {
+    schemaVersion: 1;
+    kind: "skill-install-preview";
+    source: {
+        accountId: string;
+        deployment: string;
+        organizationId: string;
+        skillId: string;
+        projectId: string;
+    };
+    locator: {
+        project: string;
+        name: string;
+    };
+    destination: string;
+    expected: {
+        remote: {
+            hash: string;
+            contentPolicy: "bundle-v1";
+            cloudVersion?: number;
+        };
+        targetState: "file" | "link" | "unavailable" | "managed" | "unmanaged" | "modified" | "missing";
+        localHash: string | null;
+    };
+    ownership: "unknown" | "managed" | "unmanaged";
+    outcome: string;
+    blockers: string[];
+    files: {
+        path: string;
+        kind: "added";
+        after: {
+            hash: string;
+            size: number;
+            executable: boolean;
+        };
+    }[];
+};
+export type SkillContentState = {
+    state: 'available';
+    bundle: SkillBundle;
+} | {
+    state: 'missing';
+    reason: string;
+} | {
+    state: 'unavailable';
+    reason: string;
+};
+export type SkillSyncStatus = 'local-only' | 'synced' | 'local-changed' | 'remote-changed' | 'conflict' | 'missing' | 'unknown' | 'unavailable';
+export declare function assertSkillBindingScope(binding: SkillCloudBinding, scope: SkillCloudScope): void;
+export declare function validatePublishedSkillSnapshot(snapshot: PublishedSkillSnapshot): void;
+export declare function assertSkillBindingSnapshot(binding: SkillCloudBinding, snapshot: PublishedSkillSnapshot): void;
+/** Adoption is explicit. Matching names, install receipts and stale observations cannot establish a baseline. */
+export declare class SkillBindingService {
+    readonly store: SkillStore;
+    constructor(store: SkillStore);
+    list(): Promise<SkillCloudBinding[]>;
+    adopt(localSkillId: string, snapshot: PublishedSkillSnapshot, verifiedLocal: SkillBundle): Promise<SkillCloudBinding>;
+}
+/** Pure three-way comparison. Unavailable input is never interpreted as deletion or synchronization. */
+export declare function compareSkillStates(local: SkillContentState, remote: SkillContentState | undefined, baseline?: SkillRevision): SkillSyncStatus;
+/** Review artifact only. A future executor must revalidate every token and record a durable operation. */
+export declare function planSkillTransfer(input: {
+    direction: 'push' | 'pull';
+    binding: SkillCloudBinding;
+    location: {
+        id: string;
+        path: string;
+        skillId: string;
+    };
+    local: SkillContentState;
+    remote: PublishedSkillSnapshot;
+    ownership: 'managed' | 'unmanaged' | 'unknown';
+}): {
+    schemaVersion: 1;
+    kind: "skill-transfer-preview";
+    direction: "push" | "pull";
+    status: SkillSyncStatus;
+    outcome: string;
+    blockers: string[];
+    binding: SkillCloudBinding;
+    location: {
+        id: string;
+        path: string;
+        skillId: string;
+    };
+    ownership: "unknown" | "managed" | "unmanaged";
+    expected: {
+        localHash: string | null;
+        remote: {
+            hash: string;
+            contentPolicy: "bundle-v1";
+            cloudVersion?: number;
+        };
+        draftRevision: number;
+    };
+    files: {
+        before: {
+            hash: string;
+            size: number;
+            executable: boolean;
+        } | null;
+        after: {
+            hash: string;
+            size: number;
+            executable: boolean;
+        } | null;
+        path: string;
+        kind: "added" | "removed" | "modified";
+    }[];
+};
+export type SkillInstallPlan = ReturnType<typeof planSkillInstallation>;

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

@@ -0,0 +1,111 @@
+import { randomUUID } from 'node:crypto';
+import { isAbsolute } from 'node:path';
+import { diffSkillBundles, validateSkillBundle } from './skills.js';
+/** A new installation needs an explicitly selected empty destination, not a guessed name match. */
+export function planSkillInstallation(remote, destination, target) {
+    validatePublishedSkillSnapshot(remote);
+    if (!isAbsolute(destination))
+        throw new Error('Installation destination must be absolute.');
+    const blockers = target.state === 'missing' ? [] : ['Destination is occupied or unavailable. Choose a new folder, or explicitly bind and review an update.'];
+    return { schemaVersion: 1, kind: 'skill-install-preview', source: { ...remote.remote, accountId: remote.accountId }, locator: { ...remote.locator }, destination,
+        expected: { remote: { ...remote.revision }, targetState: target.state, localHash: target.hash ?? null }, ownership: target.ownership,
+        outcome: blockers.length ? 'blocked' : 'reviewable', blockers,
+        files: remote.bundle.files.map(f => ({ path: f.path, kind: 'added', after: { hash: f.sha256, size: f.size, executable: f.executable } })) };
+}
+export function assertSkillBindingScope(binding, scope) {
+    if (binding.accountId !== scope.accountId || binding.remote.deployment !== scope.deployment || binding.remote.organizationId !== scope.organizationId) {
+        throw new Error('Skill binding belongs to a different account, organization or deployment. Explicitly link the intended destination.');
+    }
+}
+export function validatePublishedSkillSnapshot(snapshot) {
+    validateSkillBundle(snapshot.bundle);
+    if (snapshot.revision.contentPolicy !== 'bundle-v1' || snapshot.revision.hash !== snapshot.bundle.hash
+        || !Number.isSafeInteger(snapshot.revision.cloudVersion) || Number(snapshot.revision.cloudVersion) < 1
+        || !Number.isSafeInteger(snapshot.draftRevision) || snapshot.draftRevision < 0 || typeof snapshot.hasDraft !== 'boolean') {
+        throw new Error('Published skill revision does not match its verified bundle.');
+    }
+}
+export function assertSkillBindingSnapshot(binding, snapshot) {
+    validatePublishedSkillSnapshot(snapshot);
+    assertSkillBindingScope(binding, { ...snapshot.remote, accountId: snapshot.accountId });
+    if (binding.remote.skillId !== snapshot.remote.skillId || binding.remote.projectId !== snapshot.remote.projectId) {
+        throw new Error('Cloud lookup resolved to a different skill identity. No binding was changed.');
+    }
+}
+/** Adoption is explicit. Matching names, install receipts and stale observations cannot establish a baseline. */
+export class SkillBindingService {
+    store;
+    constructor(store) {
+        this.store = store;
+    }
+    async list() { return (await this.store.read()).bindings; }
+    async adopt(localSkillId, snapshot, verifiedLocal) {
+        validatePublishedSkillSnapshot(snapshot);
+        validateSkillBundle(verifiedLocal);
+        return this.store.transaction(c => {
+            if (!c.identities.some(i => i.id === localSkillId))
+                throw new Error('Local skill identity not found. Refresh the inventory first.');
+            const existing = c.bindings.find(b => b.localSkillId === localSkillId && b.accountId === snapshot.accountId
+                && b.remote.deployment === snapshot.remote.deployment && b.remote.organizationId === snapshot.remote.organizationId && b.remote.projectId === snapshot.remote.projectId);
+            if (existing)
+                assertSkillBindingSnapshot(existing, snapshot);
+            const binding = existing ?? { id: randomUUID(), localSkillId, remote: { ...snapshot.remote }, accountId: snapshot.accountId, locator: { ...snapshot.locator } };
+            binding.locator = { ...snapshot.locator };
+            // Differing bytes retain the last confirmed baseline, or remain unknown.
+            if (verifiedLocal.hash === snapshot.revision.hash)
+                binding.baseline = { ...snapshot.revision };
+            if (!existing)
+                c.bindings.push(binding);
+            return structuredClone(binding);
+        });
+    }
+}
+/** Pure three-way comparison. Unavailable input is never interpreted as deletion or synchronization. */
+export function compareSkillStates(local, remote, baseline) {
+    if (local.state === 'available')
+        validateSkillBundle(local.bundle);
+    if (remote?.state === 'available')
+        validateSkillBundle(remote.bundle);
+    if (local.state === 'unavailable' || remote?.state === 'unavailable')
+        return 'unavailable';
+    if (local.state === 'missing' || remote?.state === 'missing')
+        return 'missing';
+    if (!remote)
+        return 'local-only';
+    if (!baseline || baseline.contentPolicy !== 'bundle-v1' || !/^[a-f0-9]{64}$/.test(baseline.hash))
+        return 'unknown';
+    if (local.bundle.hash === remote.bundle.hash)
+        return 'synced';
+    if (local.bundle.hash === baseline.hash)
+        return 'remote-changed';
+    if (remote.bundle.hash === baseline.hash)
+        return 'local-changed';
+    return 'conflict';
+}
+/** Review artifact only. A future executor must revalidate every token and record a durable operation. */
+export function planSkillTransfer(input) {
+    const { binding, local, remote, direction, location, ownership } = input;
+    assertSkillBindingSnapshot(binding, remote);
+    if (location.skillId !== binding.localSkillId)
+        throw new Error('Location does not belong to the bound local skill.');
+    const status = compareSkillStates(local, { state: 'available', bundle: remote.bundle }, binding.baseline);
+    const blockers = [];
+    if (!['synced', direction === 'push' ? 'local-changed' : 'remote-changed'].includes(status))
+        blockers.push(`Cannot ${direction} automatically from ${status}; review the divergence first.`);
+    if (status !== 'synced' && direction === 'pull' && ownership !== 'managed')
+        blockers.push('Replacing local files requires verified Sfora ownership or an explicitly chosen new destination.');
+    if (status !== 'synced' && direction === 'push' && remote.hasDraft)
+        blockers.push('The cloud contains an unpublished draft; review it before replacing it.');
+    const before = direction === 'push' ? remote.bundle : local.state === 'available' ? local.bundle : undefined;
+    const after = direction === 'pull' ? remote.bundle : local.state === 'available' ? local.bundle : undefined;
+    const files = before && after ? diffSkillBundles(before, after).map(change => {
+        const metadata = (bundle) => { const f = bundle.files.find(f => f.path === change.path); return f ? { hash: f.sha256, size: f.size, executable: f.executable } : null; };
+        return { ...change, before: metadata(before), after: metadata(after) };
+    }) : [];
+    return {
+        schemaVersion: 1, kind: 'skill-transfer-preview', direction, status,
+        outcome: blockers.length ? 'blocked' : status === 'synced' ? 'no-op' : 'reviewable', blockers,
+        binding: structuredClone(binding), location: { ...location }, ownership,
+        expected: { localHash: local.state === 'available' ? local.bundle.hash : null, remote: { ...remote.revision }, draftRevision: remote.draftRevision }, files,
+    };
+}