sfora-cli 0.14.0 → 0.16.0

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

@@ -0,0 +1,268 @@
+import { DatabaseSync } from 'node:sqlite';
+import { randomUUID } from 'node:crypto';
+import { mkdir, lstat, open } from 'node:fs/promises';
+import { dirname } from 'node:path';
+import { readSkillBundle } from './skills.js';
+import { assertSkillBindingSnapshot, planSkillTransfer } from './skill-sync.js';
+export const operationDirection = (plan) => plan.kind === 'skill-install-preview' ? 'install' : plan.direction;
+export const operationRemote = (plan) => plan.kind === 'skill-install-preview' ? plan.source : plan.binding.remote;
+export const operationDestination = (plan) => plan.kind === 'skill-install-preview' ? plan.destination : plan.location.path;
+/** Separate versioned journal: intent commits before network I/O. A dead worker never retains a SQLite lock. */
+export class SkillOperationJournal {
+    path;
+    constructor(path) {
+        this.path = path;
+    }
+    async access(change) {
+        await mkdir(dirname(this.path), { recursive: true, mode: 0o700 });
+        const handle = await open(this.path, 'ax', 0o600).catch(e => { if (e.code === 'EEXIST')
+            return null; throw e; });
+        await handle?.close();
+        const info = await lstat(this.path);
+        if (!info.isFile() || info.isSymbolicLink() || info.size > 64 * 1024 * 1024)
+            throw new Error('Invalid skill operation journal file.');
+        const db = new DatabaseSync(this.path);
+        try {
+            db.exec('PRAGMA busy_timeout=5000; PRAGMA synchronous=FULL; BEGIN IMMEDIATE;');
+            const version = Number(db.prepare('PRAGMA user_version').get().user_version);
+            if (version === 0) {
+                if (db.prepare("SELECT name FROM sqlite_master WHERE type='table'").all().length)
+                    throw new Error('Unrecognized operation journal.');
+                db.exec('CREATE TABLE operations(id TEXT PRIMARY KEY,data TEXT NOT NULL); PRAGMA user_version=1;');
+            }
+            else if (version !== 1)
+                throw new Error('Unsupported operation journal version.');
+            const result = change(db);
+            db.exec('COMMIT');
+            return result;
+        }
+        catch (error) {
+            try {
+                db.exec('ROLLBACK');
+            }
+            catch { }
+            throw error;
+        }
+        finally {
+            db.close();
+        }
+    }
+    decode(data) {
+        const op = JSON.parse(String(data));
+        if (!op || !/^[a-f0-9-]{36}$/.test(op.id) || !['planned', 'running', 'needs-attention', 'succeeded', 'cancelled'].includes(op.status)
+            || !['skill-transfer-preview', 'skill-install-preview'].includes(op.plan?.kind) || op.plan.schemaVersion !== 1 || !Number.isSafeInteger(op.createdAt)
+            || !Number.isSafeInteger(op.updatedAt) || (op.ownerPid !== undefined && (!Number.isSafeInteger(op.ownerPid) || op.ownerPid < 1))
+            || (op.status === 'running' && !op.ownerPid)
+            || (op.confirmedRevision && (op.confirmedRevision.contentPolicy !== 'bundle-v1' || op.confirmedRevision.hash !== (operationDirection(op.plan) === 'push' ? op.plan.expected.localHash : op.plan.expected.remote.hash) || op.confirmedRevision.cloudVersion !== op.plan.expected.remote.cloudVersion + (operationDirection(op.plan) === 'push' ? 1 : 0))))
+            throw new Error('Invalid operation record.');
+        return op;
+    }
+    async list() { return this.access(db => db.prepare('SELECT data FROM operations ORDER BY rowid DESC').all().map(row => this.decode(row.data))); }
+    async create(plan) {
+        if (!plan || plan.schemaVersion !== 1 || plan.outcome !== 'reviewable' || plan.blockers.length || JSON.stringify(plan).length > 2 * 1024 * 1024)
+            throw new Error('Only a reviewable plan can be queued.');
+        if (plan.kind === 'skill-install-preview') {
+            if (plan.expected.targetState !== 'missing' || plan.expected.localHash !== null || !plan.locator?.project || !plan.locator?.name)
+                throw new Error('Refresh the empty-destination installation plan.');
+        }
+        else if (plan.kind === 'skill-transfer-preview') {
+            const push = plan.direction === 'push';
+            if (!['push', 'pull'].includes(plan.direction) || plan.status !== (push ? 'local-changed' : 'remote-changed')
+                || plan.binding.baseline?.hash !== (push ? plan.expected.remote.hash : plan.expected.localHash)
+                || !/^[a-f0-9]{64}$/.test(plan.expected.localHash ?? '') || plan.expected.localHash === plan.expected.remote.hash
+                || (!push && plan.ownership !== 'managed'))
+                throw new Error('Only a reviewed, owned transfer can be queued.');
+        }
+        else
+            throw new Error('Unsupported operation plan.');
+        const now = Date.now();
+        const op = { id: randomUUID(), createdAt: now, updatedAt: now, status: 'planned', plan: structuredClone(plan) };
+        return this.access(db => {
+            if (Number(db.prepare('SELECT COUNT(*) AS count FROM operations').get().count) >= 10000)
+                throw new Error('Operation journal is full. Archive completed operations before queuing more.');
+            db.prepare('INSERT INTO operations VALUES (?,?)').run(op.id, JSON.stringify(op));
+            return op;
+        });
+    }
+    async confirm(id, revision) {
+        return this.access(db => {
+            const row = db.prepare('SELECT data FROM operations WHERE id=?').get(id);
+            if (!row)
+                throw new Error('Operation not found.');
+            const op = this.decode(row.data);
+            if (op.status !== 'running' || op.ownerPid !== process.pid)
+                throw new Error('Operation lease changed.');
+            if (revision.hash !== (operationDirection(op.plan) === 'push' ? op.plan.expected.localHash : op.plan.expected.remote.hash) || revision.cloudVersion !== op.plan.expected.remote.cloudVersion + (operationDirection(op.plan) === 'push' ? 1 : 0))
+                throw new Error('Unexpected confirmed revision.');
+            op.confirmedRevision = { ...revision };
+            op.updatedAt = Date.now();
+            db.prepare('UPDATE operations SET data=? WHERE id=?').run(JSON.stringify(op), id);
+        });
+    }
+    async checkpoint(id, local) {
+        return this.access(db => {
+            const row = db.prepare('SELECT data FROM operations WHERE id=?').get(id);
+            if (!row)
+                throw new Error('Operation not found.');
+            const op = this.decode(row.data);
+            if (op.status !== 'running' || op.ownerPid !== process.pid)
+                throw new Error('Operation lease changed.');
+            op.local = structuredClone(local);
+            op.updatedAt = Date.now();
+            db.prepare('UPDATE operations SET data=? WHERE id=?').run(JSON.stringify(op), id);
+        });
+    }
+    async claim(id, recover = false) {
+        return this.access(db => {
+            const row = db.prepare('SELECT data FROM operations WHERE id=?').get(id);
+            if (!row)
+                throw new Error('Operation not found.');
+            const op = this.decode(row.data);
+            if (op.status === 'succeeded' || op.status === 'cancelled')
+                return op;
+            const target = (o) => { const r = operationRemote(o.plan); return JSON.stringify([r.deployment, r.organizationId, r.projectId, r.skillId]); };
+            for (const other of db.prepare('SELECT data FROM operations WHERE id!=?').all(id).map(row => this.decode(row.data))) {
+                if (other.status === 'running' && (target(other) === target(op) || operationDestination(other.plan) === operationDestination(op.plan)))
+                    throw new Error(`Cloud target is reserved by operation ${other.id}. Complete or recover that operation first.`);
+            }
+            if (op.status === 'running') {
+                if (!recover)
+                    throw new Error('Operation is already running. Use recover after its worker has exited.');
+                if (op.ownerPid) {
+                    let alive = true;
+                    try {
+                        process.kill(op.ownerPid, 0);
+                    }
+                    catch (e) {
+                        if (e.code === 'ESRCH')
+                            alive = false;
+                    }
+                    if (alive)
+                        throw new Error('The operation worker is still running; recovery refused.');
+                }
+            }
+            op.status = 'running';
+            op.ownerPid = process.pid;
+            op.updatedAt = Date.now();
+            delete op.error;
+            db.prepare('UPDATE operations SET data=? WHERE id=?').run(JSON.stringify(op), id);
+            return op;
+        });
+    }
+    async cancel(id) {
+        return this.access(db => {
+            const row = db.prepare('SELECT data FROM operations WHERE id=?').get(id);
+            if (!row)
+                throw new Error('Operation not found.');
+            const op = this.decode(row.data);
+            if (op.status === 'cancelled')
+                return op;
+            if (op.status !== 'planned')
+                throw new Error('Only an unstarted operation can be cancelled. Recover uncertain work before abandoning it.');
+            op.status = 'cancelled';
+            op.updatedAt = Date.now();
+            db.prepare('UPDATE operations SET data=? WHERE id=?').run(JSON.stringify(op), id);
+            return op;
+        });
+    }
+    async finish(id, status, error) {
+        return this.access(db => {
+            const row = db.prepare('SELECT data FROM operations WHERE id=?').get(id);
+            if (!row)
+                throw new Error('Operation not found.');
+            const op = this.decode(row.data);
+            if (op.status !== 'running' || op.ownerPid !== process.pid)
+                throw new Error('Operation lease changed.');
+            op.status = status;
+            op.updatedAt = Date.now();
+            delete op.ownerPid;
+            if (error)
+                op.error = error.slice(0, 2000);
+            else
+                delete op.error;
+            db.prepare('UPDATE operations SET data=? WHERE id=?').run(JSON.stringify(op), id);
+            return op;
+        });
+    }
+}
+/** Idempotent by exact observed content/revision, never by names or a blind retry. */
+export class SkillPushExecutor {
+    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 (op.status === 'succeeded' || op.status === 'cancelled')
+            return op;
+        try {
+            const plan = op.plan;
+            if (plan.kind !== 'skill-transfer-preview' || plan.direction !== 'push')
+                throw new Error('Use the local executor for this operation.');
+            const catalog = await this.store.read();
+            const binding = catalog.bindings.find(b => b.id === plan.binding.id);
+            const location = catalog.locations.find(l => l.id === plan.location.id);
+            if (!binding || !location || location.skillId !== binding.localSkillId || location.path !== plan.location.path
+                || 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. Create a new plan.');
+            const { project, name } = binding.locator;
+            let remote = await this.cloud.snapshot(project, name);
+            assertSkillBindingSnapshot(binding, remote);
+            if (op.confirmedRevision) {
+                await this.store.transaction(c => {
+                    const current = c.bindings.find(b => b.id === binding.id);
+                    if (!current || JSON.stringify(current) !== JSON.stringify(binding))
+                        throw new Error('Binding changed during recovery.');
+                    if (JSON.stringify(current.baseline) === JSON.stringify(plan.binding.baseline))
+                        current.baseline = { ...op.confirmedRevision };
+                });
+                return await this.journal.finish(id, 'succeeded');
+            }
+            if (!remote.supportsIdentityGuards)
+                throw new Error('This Sfora deployment does not support identity-checked transfers yet. Update the server before applying.');
+            const version = plan.expected.remote.cloudVersion;
+            const draft = plan.expected.draftRevision;
+            const hash = plan.expected.localHash;
+            const confirmed = () => remote.revision.cloudVersion === version + 1 && remote.revision.hash === hash;
+            if (!confirmed()) {
+                // A crash may have occurred after the draft committed but before its
+                // response arrived. Only the exact intended next draft can be resumed.
+                const saved = remote.revision.cloudVersion === version && remote.revision.hash === plan.expected.remote.hash
+                    && remote.draftRevision === draft + 1 && remote.hasDraft && remote.draftHash === hash;
+                if (!saved) {
+                    const local = await (this.cloud.read ?? readSkillBundle)(location.path);
+                    const current = planSkillTransfer({ direction: 'push', binding, location, local: { state: 'available', bundle: local }, remote, ownership: plan.ownership });
+                    if (JSON.stringify(current) !== JSON.stringify(plan))
+                        throw new Error('Skill changed since review. Create a new plan.');
+                    const result = await this.cloud.saveDraft(project, { ...local, name }, version, draft, binding.remote.skillId);
+                    if (result.draftRevision !== draft + 1)
+                        throw new Error('Unexpected draft response. Inspect the operation before recovery.');
+                }
+                await this.cloud.publish(project, name, version, draft + 1, binding.remote.skillId);
+                remote = await this.cloud.snapshot(project, name);
+                assertSkillBindingSnapshot(binding, remote);
+                if (!confirmed())
+                    throw new Error('Publication could not be confirmed at the expected revision. Inspect before recovery.');
+            }
+            // Baseline commit is deliberately after remote confirmation. If the
+            // journal completion is interrupted, recovery recognizes this baseline.
+            await this.journal.confirm(id, remote.revision);
+            await this.store.transaction(c => {
+                const current = c.bindings.find(b => b.id === binding.id);
+                if (!current || JSON.stringify(current) !== JSON.stringify(binding))
+                    throw new Error('Binding changed during publication. Confirmation requires review.');
+                current.baseline = { ...remote.revision };
+            });
+            return await this.journal.finish(id, 'succeeded');
+        }
+        catch (error) {
+            await this.journal.finish(id, 'needs-attention', error.message);
+            throw error;
+        }
+    }
+}

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

@@ -0,0 +1,46 @@
+import { SkillOperationJournal, type SkillPushPorts } from './skill-operations.js';
+import type { SkillStore } from './skill-store.js';
+export interface SkillReview {
+    id: string;
+    action: 'push' | 'pull' | 'install' | 'link';
+    outcome: 'reviewable' | 'blocked' | 'no-op' | 'draft-needed';
+    name: string;
+    project: string;
+    scope: string;
+    path: string;
+    version?: number;
+    files: Array<{
+        path: string;
+        kind: 'added' | 'removed' | 'modified';
+    }>;
+    blockers: string[];
+}
+/** Read-only previews become durable operations only when the person confirms.
+ * Ephemeral review IDs are capability tokens owned by the desktop main process. */
+export declare class SkillReviewService {
+    readonly store: SkillStore;
+    readonly journal: SkillOperationJournal;
+    readonly connect: (connection: string) => Promise<SkillPushPorts>;
+    readonly now: () => number;
+    private reviews;
+    constructor(store: SkillStore, journal: SkillOperationJournal, connect: (connection: string) => Promise<SkillPushPorts>, now?: () => number);
+    private remember;
+    private view;
+    transfer(input: {
+        locationId: string;
+        projectId: string;
+        connection: string;
+        direction: 'push' | 'pull';
+    }): Promise<SkillReview>;
+    install(input: {
+        projectId: string;
+        name: string;
+        connection: string;
+        destination: string;
+    }): Promise<SkillReview>;
+    confirm(id: string): Promise<{
+        status: string;
+        operationId?: string;
+    }>;
+    private apply;
+}

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

@@ -0,0 +1,132 @@
+import { randomUUID } from 'node:crypto';
+import { readSkillBundle, inspectSkillTarget } from './skills.js';
+import { SkillBindingService, planSkillInstallation, planSkillTransfer } from './skill-sync.js';
+import { SkillOperationExecutor } from './skill-executor.js';
+/** Read-only previews become durable operations only when the person confirms.
+ * Ephemeral review IDs are capability tokens owned by the desktop main process. */
+export class SkillReviewService {
+    store;
+    journal;
+    connect;
+    now;
+    reviews = new Map();
+    constructor(store, journal, connect, now = Date.now) {
+        this.store = store;
+        this.journal = journal;
+        this.connect = connect;
+        this.now = now;
+    }
+    remember(entry) {
+        for (const [id, item] of this.reviews)
+            if (item.expiresAt < this.now() && (!item.operationId || item.result) && !item.running)
+                this.reviews.delete(id);
+        if (this.reviews.size >= 50)
+            throw new Error('Too many open reviews. Finish existing transfers or reopen the app.');
+        this.reviews.set(entry.view.id, { ...entry, expiresAt: this.now() + 10 * 60_000 });
+        return structuredClone(entry.view);
+    }
+    view(remote, path, action) {
+        return { id: randomUUID(), action, outcome: 'reviewable', name: remote.locator.name, project: remote.locator.project,
+            scope: `${remote.remote.deployment} · ${remote.remote.organizationId} · ${remote.accountId}`, path, version: remote.revision.cloudVersion, files: [], blockers: [] };
+    }
+    async transfer(input) {
+        if (!['push', 'pull'].includes(input.direction))
+            throw new Error('Choose Push to Sfora or Update local copy.');
+        const catalog = await this.store.read();
+        const location = catalog.locations.find(l => l.id === input.locationId);
+        if (!location)
+            throw new Error('This local skill is no longer tracked. Refresh and choose it again.');
+        const local = await readSkillBundle(location.path);
+        const cloud = await this.connect(input.connection);
+        const names = [...new Set(catalog.bindings.filter(b => b.localSkillId === location.skillId && b.remote.projectId === input.projectId).map(b => b.locator.name))];
+        let remote;
+        try {
+            remote = await cloud.snapshot(input.projectId, names.length === 1 ? names[0] : local.name);
+        }
+        catch (error) {
+            const code = error?.code;
+            if (names.length || !['SKILL_NOT_FOUND', 'SKILL_NOT_PUBLISHED'].includes(code ?? ''))
+                throw error;
+            if (input.direction === 'pull')
+                throw new Error('This skill has no published version to install. Open its project to review or publish a draft.');
+            return this.remember({ connection: input.connection, view: { id: randomUUID(), action: 'push', outcome: 'draft-needed', name: local.name, project: input.projectId, scope: input.connection, path: location.path,
+                    files: local.files.map(file => ({ path: file.path, kind: 'added' })), blockers: ['For the first publication, review these local files in the project editor, save a draft, then publish it for your team.'] } });
+        }
+        if (remote.remote.projectId !== input.projectId)
+            throw new Error('The selected project resolved to a different identity.');
+        const binding = catalog.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);
+        const view = this.view(remote, location.path, input.direction);
+        if (!binding) {
+            if (local.hash !== remote.revision.hash) {
+                view.outcome = 'blocked';
+                view.blockers = ['These copies have not been linked and their contents differ. Open the project to review its existing skill, or install it into a new folder.'];
+                return this.remember({ view, connection: input.connection });
+            }
+            view.action = 'link';
+            return this.remember({ view, connection: input.connection, link: { localSkillId: location.skillId, locationId: location.id, snapshot: remote } });
+        }
+        const target = await inspectSkillTarget(location.path);
+        const plan = planSkillTransfer({ direction: input.direction, binding, location, local: { state: 'available', bundle: local }, remote, ownership: target.ownership });
+        view.outcome = plan.outcome;
+        view.files = plan.files.map(f => ({ path: f.path, kind: f.kind }));
+        view.blockers = plan.blockers;
+        return this.remember({ view, connection: input.connection, plan });
+    }
+    async install(input) {
+        const remote = await (await this.connect(input.connection)).snapshot(input.projectId, input.name);
+        if (remote.remote.projectId !== input.projectId)
+            throw new Error('The selected project resolved to a different identity.');
+        const plan = planSkillInstallation(remote, input.destination, await inspectSkillTarget(input.destination));
+        const view = this.view(remote, input.destination, 'install');
+        view.outcome = plan.outcome;
+        view.files = plan.files.map(f => ({ path: f.path, kind: f.kind }));
+        view.blockers = plan.blockers;
+        return this.remember({ view, connection: input.connection, plan });
+    }
+    async confirm(id) {
+        const entry = this.reviews.get(id);
+        if (!entry || (!entry.operationId && entry.expiresAt < this.now()))
+            throw new Error('This review expired. Review the current changes again.');
+        if (entry.view.outcome !== 'reviewable')
+            throw new Error('There are no applicable changes in this review.');
+        if (entry.result)
+            return entry.result;
+        if (entry.running)
+            return entry.running;
+        entry.running = this.apply(entry).then(result => { if (result.status === 'succeeded') {
+            entry.result = result;
+            delete entry.plan;
+            delete entry.link;
+        } return result; }).finally(() => { entry.running = undefined; });
+        return entry.running;
+    }
+    async apply(entry) {
+        const cloud = await this.connect(entry.connection);
+        if (entry.link) {
+            const { snapshot, locationId, localSkillId } = entry.link;
+            const location = (await this.store.read()).locations.find(l => l.id === locationId && l.skillId === localSkillId);
+            if (!location || location.path !== entry.view.path)
+                throw new Error('Local location changed. Review the copies again.');
+            const remote = await cloud.snapshot(snapshot.locator.project, snapshot.locator.name);
+            if (JSON.stringify(remote.remote) !== JSON.stringify(snapshot.remote) || remote.accountId !== snapshot.accountId || JSON.stringify(remote.revision) !== JSON.stringify(snapshot.revision))
+                throw new Error('Cloud identity or revision changed. Review the copies again.');
+            const local = await readSkillBundle(location.path);
+            if (local.hash !== remote.revision.hash)
+                throw new Error('Local files changed. Review the copies again.');
+            await new SkillBindingService(this.store).adopt(localSkillId, remote, local);
+            return { status: 'succeeded' };
+        }
+        if (!entry.plan)
+            throw new Error('Review has no applicable changes.');
+        const recovering = !!entry.operationId;
+        if (!entry.operationId)
+            entry.operationId = (await this.journal.create(entry.plan)).id;
+        try {
+            const operation = await new SkillOperationExecutor(this.store, this.journal, cloud).apply(entry.operationId, recovering);
+            return { status: operation.status, operationId: operation.id };
+        }
+        catch (error) {
+            throw new Error(`${error.message} The result is saved in Transfers for recovery.`);
+        }
+    }
+}

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

@@ -0,0 +1,96 @@
+import { discoverSkills, type SkillSource } from './skill-discovery.js';
+import { type RegisteredSkillRoot, type SkillStore } from './skill-store.js';
+import { readSkillBundle } from './skills.js';
+export declare const pathWithin: (root: string, path: string) => boolean;
+export interface SkillServicePorts {
+    discover: typeof discoverSkills;
+    resolveDirectory(path: string): Promise<string>;
+    inspect: typeof readSkillBundle;
+}
+/** Node service shared by CLI and desktop. Its IDs are identity, not renderer grants. */
+export declare class SkillService {
+    readonly store: SkillStore;
+    readonly sources: () => SkillSource[];
+    readonly ports: SkillServicePorts;
+    constructor(store?: SkillStore, sources?: () => SkillSource[], ports?: SkillServicePorts);
+    registerRoot(path: string, label?: string, scope?: "custom" | "project"): Promise<{
+        id: string;
+        path: string;
+        label: string;
+        depth: number;
+        scope?: "custom" | "project";
+    }>;
+    roots(): Promise<RegisteredSkillRoot[]>;
+    removeRoot(id: string): Promise<void>;
+    inventory(): Promise<{
+        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";
+        }[];
+        warnings: string[];
+    }>;
+    /** Warm reads use persisted observations; explicit inventory remains a full reconciliation. */
+    cachedInventory(): Promise<{
+        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";
+        }[];
+        warnings: string[];
+    }>;
+    discoverySources(): Promise<SkillSource[]>;
+    /** Re-read only affected known locations, preserving identity and last known bytes on failure. */
+    refreshLocations(ids: string[]): Promise<{
+        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";
+        }[];
+        warnings: string[];
+    }>;
+    /** Metadata-only explicit relocation. Never guesses identity from a name/hash or moves files. */
+    relocateLocation(id: string, path: string): Promise<{
+        id: string;
+        skillId: string;
+        path: string;
+        aliases: import("./skill-domain.js").SkillAlias[];
+        createdAt: number;
+    }>;
+    rebuild(): Promise<{
+        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";
+        }[];
+        warnings: string[];
+    }>;
+}