sfora-cli 0.15.0 → 0.17.0

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

@@ -0,0 +1,21 @@
+import type { SkillSource } from './skill-discovery.js';
+export interface SkillAgentAdapter {
+    id: string;
+    label: string;
+    globalPath: string;
+    projectPath: string;
+    depth: number;
+    /** A folder observation alone never establishes that an agent enables a skill. */
+    activation: 'unknown';
+    deploymentModes: readonly ['copy'];
+    caches: readonly {
+        id: string;
+        path: string;
+        label: string;
+        depth: number;
+    }[];
+}
+export declare const SKILL_AGENT_ADAPTERS: readonly SkillAgentAdapter[];
+export declare function defaultSkillSources(home?: string): SkillSource[];
+/** Caller explicitly selects/registers the project; never infer access from cwd in desktop. */
+export declare function projectSkillSources(project: string): SkillSource[];

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

@@ -0,0 +1,19 @@
+import { homedir } from 'node:os';
+import { join, resolve } from 'node:path';
+export const SKILL_AGENT_ADAPTERS = [
+    { id: 'agents', label: 'Agents', globalPath: '.agents/skills', projectPath: '.agents/skills', depth: 1, activation: 'unknown', deploymentModes: ['copy'], caches: [] },
+    { id: 'codex', label: 'Codex', globalPath: '.codex/skills', projectPath: '.codex/skills', depth: 2, activation: 'unknown', deploymentModes: ['copy'], caches: [{ id: 'codex-plugin-cache', path: '.codex/plugins/cache', label: 'Codex plugin cache', depth: 6 }] },
+    { id: 'claude', label: 'Claude', globalPath: '.claude/skills', projectPath: '.claude/skills', depth: 1, activation: 'unknown', deploymentModes: ['copy'], caches: [{ id: 'claude-plugin-cache', path: '.claude/plugins/cache', label: 'Claude plugin cache', depth: 6 }] },
+    { id: 'cursor', label: 'Cursor', globalPath: '.cursor/skills', projectPath: '.cursor/skills', depth: 1, activation: 'unknown', deploymentModes: ['copy'], caches: [] },
+];
+export function defaultSkillSources(home = homedir()) {
+    return SKILL_AGENT_ADAPTERS.flatMap(adapter => [
+        { id: adapter.id, path: join(home, adapter.globalPath), label: adapter.label, depth: adapter.depth, kind: 'agent' },
+        ...adapter.caches.map(cache => ({ id: cache.id, path: join(home, cache.path), label: cache.label, depth: cache.depth, kind: 'cache' })),
+    ]);
+}
+/** Caller explicitly selects/registers the project; never infer access from cwd in desktop. */
+export function projectSkillSources(project) {
+    const root = resolve(project);
+    return SKILL_AGENT_ADAPTERS.map(adapter => ({ id: `project:${root}:${adapter.id}`, path: join(root, adapter.projectPath), label: `${adapter.label} · project`, depth: adapter.depth, kind: 'agent' }));
+}

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

@@ -0,0 +1,22 @@
+export { defaultSkillSources } from './skill-adapters.js';
+export interface SkillSource {
+    path: string;
+    label: string;
+    depth: number;
+    id?: string;
+    kind?: "agent" | "cache" | "custom";
+}
+export interface LocalSkill {
+    path: string;
+    name: string;
+    sources: string[];
+    aliases: import("./skill-domain.js").SkillAlias[];
+    hash?: string;
+    fileCount?: number;
+    error?: string;
+}
+/** Bounded discovery; canonical aliases share a row. Bundles retain strict link/size checks. */
+export declare function discoverSkills(sources?: SkillSource[]): Promise<{
+    skills: LocalSkill[];
+    warnings: string[];
+}>;

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

@@ -0,0 +1,79 @@
+import { readdir, realpath, lstat } from 'node:fs/promises';
+import { defaultSkillSources } from './skill-adapters.js';
+export { defaultSkillSources } from './skill-adapters.js';
+import { join, basename } from 'node:path';
+import { readSkillBundle } from './skills.js';
+class ScanLimitError extends Error {
+}
+/** Bounded discovery; canonical aliases share a row. Bundles retain strict link/size checks. */
+export async function discoverSkills(sources = defaultSkillSources()) {
+    const found = new Map();
+    const warnings = [];
+    let visited = 0;
+    for (const source of sources) {
+        const seen = new Set();
+        async function walk(path, depth) {
+            if (++visited > 5000 || found.size >= 1000)
+                throw new ScanLimitError('Scan limit reached. Choose a narrower folder to find more skills.');
+            const canonical = await realpath(path);
+            if (seen.has(canonical)) {
+                const existing = found.get(canonical);
+                if (existing && !existing.aliases.some(a => a.sourceId === (source.id ?? source.path) && a.path === path))
+                    existing.aliases.push({ sourceId: source.id ?? source.path, path, label: source.label, kind: source.kind ?? "custom" });
+                return;
+            }
+            seen.add(canonical);
+            const entries = await readdir(canonical, { withFileTypes: true });
+            if (entries.some(entry => entry.name === 'SKILL.md')) {
+                const existing = found.get(canonical);
+                if (existing) {
+                    if (!existing.sources.includes(source.label))
+                        existing.sources.push(source.label);
+                    existing.aliases.push({ sourceId: source.id ?? source.path, path, label: source.label, kind: source.kind ?? "custom" });
+                    return;
+                }
+                const skill = { path: canonical, name: basename(canonical), sources: [source.label], aliases: [{ sourceId: source.id ?? source.path, path, label: source.label, kind: source.kind ?? "custom" }] };
+                found.set(canonical, skill);
+                try {
+                    const bundle = await readSkillBundle(canonical);
+                    skill.hash = bundle.hash;
+                    skill.fileCount = bundle.files.length;
+                }
+                catch (error) {
+                    skill.error = error instanceof Error ? error.message : String(error);
+                }
+                return;
+            }
+            if (depth === 0)
+                return;
+            for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
+                if (['node_modules', '.git'].includes(entry.name))
+                    continue;
+                if (!entry.isDirectory() && !entry.isSymbolicLink())
+                    continue;
+                const child = join(path, entry.name);
+                try {
+                    if ((await lstat(await realpath(child))).isDirectory())
+                        await walk(child, depth - 1);
+                }
+                catch (error) {
+                    if (error instanceof ScanLimitError)
+                        throw error;
+                    warnings.push(`${source.label}: ${child}: ${error instanceof Error ? error.message : String(error)}`);
+                }
+            }
+        }
+        try {
+            await walk(source.path, source.depth);
+        }
+        catch (error) {
+            if (error instanceof ScanLimitError) {
+                warnings.push(error.message);
+                break;
+            }
+            if (error.code !== 'ENOENT')
+                warnings.push(`${source.label}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    return { skills: [...found.values()].sort((a, b) => a.name.localeCompare(b.name) || a.path.localeCompare(b.path)), warnings };
+}

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

@@ -0,0 +1,74 @@
+/** Stable domain records. Names/hashes are labels/content, never identity or permission. */
+export interface SkillIdentity {
+    id: string;
+    createdAt: number;
+}
+export interface SkillAlias {
+    sourceId: string;
+    path: string;
+    label: string;
+    kind: 'agent' | 'cache' | 'custom';
+}
+export interface SkillLocation {
+    id: string;
+    skillId: string;
+    path: string;
+    aliases: SkillAlias[];
+    createdAt: number;
+}
+export interface SkillObservation {
+    locationId: string;
+    name: string;
+    observedAt: number;
+    hash?: string;
+    fileCount?: number;
+    error?: string;
+    availability: 'available' | 'unavailable';
+}
+export interface SkillRevision {
+    hash: string;
+    contentPolicy: 'bundle-v1';
+    cloudVersion?: number;
+}
+export interface CloudSkillIdentity {
+    deployment: string;
+    organizationId: string;
+    skillId: string;
+}
+export interface SkillCloudBinding {
+    id: string;
+    localSkillId: string;
+    remote: CloudSkillIdentity & {
+        projectId: string;
+    };
+    /** Authenticated member ID, never an API key or its fingerprint. */
+    accountId: string;
+    /** Lookup hints only; every lookup must revalidate the qualified IDs. */
+    locator: {
+        project: string;
+        name: string;
+    };
+    baseline?: SkillRevision;
+}
+export interface SkillProjectAssignment {
+    projectId: string;
+    remote: CloudSkillIdentity;
+    pinnedVersion: number;
+    overrideSkillId?: string;
+}
+export interface SkillAgentTarget {
+    skillId: string;
+    agentId: string;
+    path: string;
+    scope: 'global' | 'project';
+    mode: 'copy' | 'link';
+    ownership: 'managed' | 'unmanaged' | 'unknown';
+}
+export interface SkillOperation {
+    id: string;
+    kind: 'push' | 'pull' | 'install';
+    skillId: string;
+    expectedLocalHash?: string;
+    expectedRemote?: SkillRevision;
+    status: 'planned' | 'running' | 'succeeded' | 'failed' | 'cancelled';
+}

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

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,23 @@
+import { SkillOperationJournal, type SkillPushPorts } from './skill-operations.js';
+import type { SkillStore } from './skill-store.js';
+export declare class SkillOperationExecutor {
+    readonly store: SkillStore;
+    readonly journal: SkillOperationJournal;
+    readonly cloud: SkillPushPorts;
+    constructor(store: SkillStore, journal: SkillOperationJournal, cloud: SkillPushPorts);
+    apply(id: string, recover?: boolean): Promise<import("./skill-operations.js").SkillTransferOperation>;
+    /** Each item owns its durable outcome. Successful work is never replayed. */
+    batch(ids: string[], options?: {
+        recover?: boolean;
+        signal?: AbortSignal;
+        onResult?: (result: {
+            id: string;
+            status: string;
+            error?: string;
+        }) => void;
+    }): Promise<{
+        id: string;
+        status: string;
+        error?: string;
+    }[]>;
+}

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

@@ -0,0 +1,51 @@
+import { SkillPushExecutor, operationDirection } from './skill-operations.js';
+import { SkillLocalExecutor } from './skill-local-executor.js';
+export class SkillOperationExecutor {
+    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.list()).find(o => o.id === id);
+        if (!op)
+            throw new Error('Operation not found.');
+        return operationDirection(op.plan) === 'push'
+            ? new SkillPushExecutor(this.store, this.journal, this.cloud).apply(id, recover)
+            : new SkillLocalExecutor(this.store, this.journal, this.cloud).apply(id, recover);
+    }
+    /** Each item owns its durable outcome. Successful work is never replayed. */
+    async batch(ids, options = {}) {
+        if (!Array.isArray(ids) || !ids.length || ids.length > 1000 || new Set(ids).size !== ids.length || ids.some(id => typeof id !== 'string'))
+            throw new Error('Select 1–1000 distinct operation IDs.');
+        const operations = await this.journal.list();
+        if (ids.some(id => !operations.some(op => op.id === id)))
+            throw new Error('A selected operation no longer exists. Refresh before running.');
+        const results = [];
+        for (const id of ids) {
+            let result;
+            if (options.signal?.aborted) {
+                const op = (await this.journal.list()).find(o => o.id === id);
+                if (op.status === 'planned')
+                    result = { id, status: (await this.journal.cancel(id)).status };
+                else
+                    result = { id, status: op.status, error: ['succeeded', 'cancelled'].includes(op.status) ? undefined : 'Batch stopped before this item; its previous outcome is retained.' };
+            }
+            else {
+                try {
+                    result = { id, status: (await this.apply(id, options.recover)).status };
+                }
+                catch (error) {
+                    const current = (await this.journal.list()).find(o => o.id === id);
+                    result = { id, status: current.status, error: error.message };
+                }
+            }
+            results.push(result);
+            options.onResult?.(result);
+        }
+        return results;
+    }
+}

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

@@ -0,0 +1,54 @@
+import { SkillService } from './skill-service.js';
+/** Events are hints; periodic reconciliation repairs missed events and root changes. */
+export declare class SkillIndex {
+    readonly service: SkillService;
+    readonly changed: () => void;
+    readonly reconciliationMs: number;
+    private watchers;
+    private timer?;
+    private interval?;
+    private pending;
+    private full;
+    private running;
+    private active?;
+    private closed;
+    private started?;
+    private warnings;
+    constructor(service: SkillService, changed?: () => void, reconciliationMs?: number);
+    start(): Promise<void>;
+    inventory(): Promise<{
+        warnings: string[];
+        skills: {
+            skillId: string;
+            locationId: string;
+            path: string;
+            name: string;
+            sources: string[];
+            aliases: import("./skill-domain.js").SkillAlias[];
+            hash: string | undefined;
+            fileCount: number | undefined;
+            error: string | undefined;
+            availability: "available" | "unavailable";
+        }[];
+    }>;
+    invalidate(path?: string): void;
+    private configure;
+    refresh(): Promise<{
+        warnings: string[];
+        skills: {
+            skillId: string;
+            locationId: string;
+            path: string;
+            name: string;
+            sources: string[];
+            aliases: import("./skill-domain.js").SkillAlias[];
+            hash: string | undefined;
+            fileCount: number | undefined;
+            error: string | undefined;
+            availability: "available" | "unavailable";
+        }[];
+    }>;
+    private flush;
+    private perform;
+    close(): void;
+}

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;
+}