skill-flow 1.0.4 → 1.0.6

package/dist/services/skill-flow.js

@@ -2,14 +2,15 @@ import fs from "node:fs/promises";
 import path from "node:path";
 import { createChannelAdapters } from "../adapters/channel-adapters.js";
 import { StateStore } from "../state/store.js";
-import { ensureDir, hashDirectory, pathExists, readJsonFile, removePath, writeJsonFile } from "../utils/fs.js";
+import { ensureDir, hashDirectory, pathExists, readJsonFile, removePath, writeJsonFile, } from "../utils/fs.js";
 import { getBuiltinGitSources } from "../utils/builtin-git-sources.js";
 import { fetchGitHubSkillPaths } from "../utils/github-catalog.js";
-import { parseGitHubRepo } from "../utils/naming.js";
+import { buildProjectedSkillNameCandidates, parseGitHubRepo, resolveProjectedSkillNames, } from "../utils/naming.js";
 import { fail, ok } from "../utils/result.js";
 import { searchClawHubSkills } from "../utils/clawhub.js";
 import { deriveDisplayName, deriveSourceId } from "../utils/source-id.js";
 import { DeploymentApplier } from "./deployment-applier.js";
+import { ConfigCoordinator } from "./config-coordinator.js";
 import { DeploymentPlanner } from "./deployment-planner.js";
 import { DoctorService } from "./doctor-service.js";
 import { InventoryService } from "./inventory-service.js";
@@ -17,56 +18,98 @@ import { SourceService } from "./source-service.js";
 import { WorkflowService } from "./workflow-service.js";
 import { WorkspaceBootstrapService, } from "./workspace-bootstrap-service.js";
 export class SkillFlowApp {
-    store = new StateStore();
-    inventoryService = new InventoryService();
-    sourceService = new SourceService(this.store, this.inventoryService);
-    planner = new DeploymentPlanner(createChannelAdapters());
-    applier = new DeploymentApplier();
-    doctorService = new DoctorService();
-    workflowService = new WorkflowService();
-    workspaceBootstrapService = new WorkspaceBootstrapService(this.store);
+    store;
+    inventoryService;
+    sourceService;
+    planner;
+    applier;
+    doctorService;
+    workflowService;
+    workspaceBootstrapService;
+    configCoordinator;
+    mutationQueue = Promise.resolve();
+    constructor() {
+        this.store = new StateStore();
+        this.inventoryService = new InventoryService();
+        this.sourceService = new SourceService(this.store, this.inventoryService);
+        this.planner = new DeploymentPlanner(createChannelAdapters());
+        this.applier = new DeploymentApplier();
+        this.doctorService = new DoctorService();
+        this.workflowService = new WorkflowService();
+        this.workspaceBootstrapService = new WorkspaceBootstrapService(this.store);
+        this.configCoordinator = new ConfigCoordinator({
+            store: this.store,
+            doctorService: this.doctorService,
+            workflowService: this.workflowService,
+            getAvailableTargets: () => this.getAvailableTargets(),
+            pruneMissingCheckouts: () => this.pruneMissingCheckoutsImpl(),
+            getConfigData: () => this.getConfigDataImpl(),
+        });
+    }
     async addSource(locator, options) {
+        return this.runSerializedMutation(() => this.addSourceImpl(locator, options));
+    }
+    async addSourceImpl(locator, options) {
         const addOptions = options ?? {};
         const result = await this.sourceService.addSource(locator, addOptions);
         if (!result.ok) {
             return result;
         }
-        await this.store.init();
-        const manifest = await this.store.readManifest();
-        const lockFile = await this.store.readLock();
+        const { manifest, lockFile } = await this.store.readState();
         const source = manifest.sources.find((item) => item.id === result.data.manifest.id);
         if (!source) {
             return result;
         }
+        const requestedPath = this.normalizeRequestedPath(source.requestedPath);
+        if (requestedPath) {
+            source.requestedPath = requestedPath;
+            result.data.manifest.requestedPath = requestedPath;
+        }
+        else {
+            delete source.requestedPath;
+            delete result.data.manifest.requestedPath;
+        }
+        const sourceLeafs = lockFile.leafInventory.filter((leaf) => leaf.sourceId === source.id);
+        const selectedLeafIds = this.selectLeafIdsForRequestedPath(sourceLeafs, requestedPath);
         source.selectionMode =
             addOptions.selectionMode ??
-                (source.requestedPath ? "partial" : "all");
+                (selectedLeafIds.length >= sourceLeafs.length && sourceLeafs.length > 0
+                    ? "all"
+                    : "partial");
+        result.data.manifest.selectionMode = source.selectionMode;
         const enabledTargets = addOptions.enabledTargets ??
             await this.getAvailableTargets();
         manifest.bindings[source.id] = this.bindingFromDraft({
             enabledTargets,
-            selectedLeafIds: this.selectLeafIdsForRequestedPath(lockFile.leafInventory.filter((leaf) => leaf.sourceId === source.id), source.requestedPath),
+            selectedLeafIds,
         });
-        await this.store.writeManifest(manifest);
+        await this.store.writeState(manifest, lockFile);
+        const warnings = [...result.warnings];
+        if (requestedPath && selectedLeafIds.length < sourceLeafs.length) {
+            warnings.push({
+                code: "ADD_SELECTION_PRESELECTED",
+                message: `Preselected ${selectedLeafIds.length} of ${sourceLeafs.length} ` +
+                    `skill${sourceLeafs.length === 1 ? "" : "s"} under '${requestedPath}'; ` +
+                    "the full skills group was imported.",
+            });
+        }
         if (addOptions.project === false) {
-            return result;
+            return ok(result.data, warnings);
         }
         const plan = await this.planForAffectedSources(manifest, lockFile, source.id);
         if (!plan.ok) {
-            return fail(plan.errors, [...result.warnings, ...plan.warnings]);
+            return fail(plan.errors, [...warnings, ...plan.warnings]);
         }
         const applied = await this.applier.applyPlan(lockFile, plan.data.actions);
-        await this.store.writeLock(lockFile);
+        await this.store.writeState(manifest, lockFile);
         if (!applied.ok) {
-            return fail(applied.errors, [...result.warnings, ...plan.warnings, ...applied.warnings]);
+            return fail(applied.errors, [...warnings, ...plan.warnings, ...applied.warnings]);
         }
-        return ok(result.data, [...result.warnings, ...plan.warnings, ...applied.warnings]);
+        return ok(result.data, [...warnings, ...plan.warnings, ...applied.warnings]);
     }
     async findSkills(query) {
-        await this.store.init();
-        const manifest = await this.store.readManifest();
-        const lockFile = await this.store.readLock();
-        const normalizedQuery = query.trim().toLowerCase();
+        const { manifest, lockFile } = await this.store.readState();
+        const normalizedQuery = this.normalizeSearchQuery(query);
         const warnings = [];
         const localKeys = new Set();
         const candidates = [];
@@ -111,7 +154,7 @@ export class SkillFlowApp {
             }
         }
         try {
-            const results = await searchClawHubSkills(query, 8);
+            const results = await searchClawHubSkills(normalizedQuery, 8);
             remoteSearchSucceeded = true;
             for (const result of results) {
                 candidates.push({
@@ -147,124 +190,63 @@ export class SkillFlowApp {
         return ok({ candidates }, warnings);
     }
     async listWorkflows() {
+        return this.runSerializedMutation(() => this.listWorkflowsImpl());
+    }
+    async listWorkflowsImpl() {
+        const pruned = await this.pruneMissingCheckoutsImpl();
+        if (!pruned.ok) {
+            return fail(pruned.errors, pruned.warnings);
+        }
         const reconciled = await this.sourceService.reconcileInventory(undefined, {
             force: true,
         });
         if (!reconciled.ok) {
             return fail(reconciled.errors, reconciled.warnings);
         }
-        await this.store.init();
-        const manifest = await this.store.readManifest();
-        const lockFile = await this.store.readLock();
+        const { manifest, lockFile } = await this.store.readState();
         await this.persistNormalizedBindings(manifest, lockFile);
         return ok({
             summaries: this.workflowService.getSummaries(manifest, lockFile),
-        });
+        }, pruned.warnings);
     }
     async getConfigData() {
+        return this.runSerializedMutation(() => this.getConfigDataImpl());
+    }
+    async getConfigDataImpl() {
+        const pruned = await this.pruneMissingCheckoutsImpl();
+        if (!pruned.ok) {
+            return fail(pruned.errors, pruned.warnings);
+        }
         const reconciled = await this.sourceService.reconcileInventory(undefined, {
             force: true,
         });
         if (!reconciled.ok) {
             return fail(reconciled.errors, reconciled.warnings);
         }
-        await this.store.init();
-        const manifest = await this.store.readManifest();
-        const lockFile = await this.store.readLock();
+        const { manifest, lockFile } = await this.store.readState();
         await this.persistNormalizedBindings(manifest, lockFile);
         return ok({
             manifest,
             lockFile,
             summaries: this.workflowService.getSummaries(manifest, lockFile),
-        });
+        }, pruned.warnings);
     }
     async bootstrapWorkspaceState(onEvent) {
-        onEvent?.({
-            phase: "detect-targets",
-            level: "info",
-            message: "Detecting available agent targets...",
-        });
-        const availableTargets = await this.getAvailableTargets();
-        await this.store.init();
-        let manifest = await this.store.readManifest();
-        let lockFile = await this.store.readLock();
-        const detected = await this.workspaceBootstrapService.detectUnmanagedExternalSkills(manifest, lockFile, onEvent);
-        const importedSourceIds = [];
-        if (detected.length > 0) {
-            onEvent?.({
-                phase: "import-unmanaged-skills",
-                level: "info",
-                message: `Importing ${detected.length} unmanaged skill${detected.length === 1 ? "" : "s"} into skill-flow...`,
-            });
-        }
-        for (const item of detected) {
-            const imported = await this.addSource(item.path, {
-                enabledTargets: item.importedFromTargets,
-                selectionMode: "all",
-                project: false,
-                sourceIdOverride: item.sourceId,
-                displayNameOverride: item.displayName,
-                importedFromTargets: item.importedFromTargets,
-                importMode: "bootstrap-detected",
-                ...(item.originLocator ? { originLocator: item.originLocator } : {}),
-                ...(item.originRequestedPath ? { originRequestedPath: item.originRequestedPath } : {}),
-                ...(item.originBranch ? { originBranch: item.originBranch } : {}),
-            });
-            if (!imported.ok) {
-                return fail(imported.errors, imported.warnings);
-            }
-            importedSourceIds.push(imported.data.manifest.id);
-            onEvent?.({
-                phase: "import-unmanaged-skills",
-                level: "success",
-                message: `Imported ${imported.data.manifest.displayName}.`,
-            });
-        }
-        onEvent?.({
-            phase: "refresh-sources",
-            level: "info",
-            message: "Refreshing managed inventory...",
-        });
-        const reconciled = await this.sourceService.reconcileInventory(undefined, { force: true });
-        if (!reconciled.ok) {
-            return fail(reconciled.errors, reconciled.warnings);
+        return this.runSerializedMutation(() => this.bootstrapWorkspaceStateImpl(onEvent));
+    }
+    async bootstrapWorkspaceStateImpl(onEvent) {
+        const boot = await this.configCoordinator.bootstrapWorkspaceState(onEvent);
+        if (!boot.ok) {
+            return fail(boot.errors, boot.warnings);
         }
-        manifest = await this.store.readManifest();
-        lockFile = await this.store.readLock();
-        onEvent?.({
-            phase: "normalize-bindings",
-            level: "info",
-            message: "Normalizing config state...",
-        });
-        await this.persistNormalizedBindings(manifest, lockFile);
-        onEvent?.({
-            phase: "audit-projections",
-            level: "info",
-            message: "Auditing current projections...",
-        });
-        const audit = await this.doctorService.run(manifest, lockFile);
-        if (!audit.ok) {
-            return fail(audit.errors, audit.warnings);
-        }
-        onEvent?.({
-            phase: "build-summaries",
-            level: "info",
-            message: "Building config summaries...",
-        });
-        const summaries = this.workflowService.getSummaries(manifest, lockFile, audit.data);
-        onEvent?.({
-            phase: "done",
-            level: "success",
-            message: "Config bootstrap complete.",
-        });
         return ok({
-            availableTargets,
-            manifest,
-            lockFile,
-            summaries,
-            initialDrafts: this.buildInitialDrafts(summaries),
-            audit: audit.data,
-            importedSourceIds,
+            availableTargets: boot.data.availableTargets,
+            manifest: boot.data.manifest,
+            lockFile: boot.data.lockFile,
+            summaries: boot.data.summaries,
+            initialDrafts: boot.data.initialDrafts,
+            audit: boot.data.audit,
+            importedSourceIds: [],
         });
     }
     async getAvailableTargets() {
@@ -282,9 +264,7 @@ export class SkillFlowApp {
         // config TUI state flow:
         //   draft -> previewDraft() -> plan only
         //   draft -> applyDraft()   -> plan + filesystem + manifest/lock writes
-        await this.store.init();
-        const manifest = await this.store.readManifest();
-        const lockFile = await this.store.readLock();
+        const { manifest, lockFile } = await this.store.readState();
         this.normalizeBindings(manifest, lockFile);
         const prepared = this.prepareManifestForDraft(manifest, lockFile, sourceId, draft);
         const plan = await this.planForAffectedSources(prepared.manifest, lockFile, sourceId);
@@ -294,15 +274,10 @@ export class SkillFlowApp {
         return ok({ plan: plan.data, manifest: prepared.manifest, lockFile }, [...prepared.warnings, ...plan.warnings]);
     }
     async applyDraft(sourceId, draft) {
-        const reconciled = await this.sourceService.reconcileInventory([sourceId], {
-            force: true,
-        });
-        if (!reconciled.ok) {
-            return fail(reconciled.errors, reconciled.warnings);
-        }
-        await this.store.init();
-        const manifest = await this.store.readManifest();
-        const lockFile = await this.store.readLock();
+        return this.runSerializedMutation(() => this.applyDraftImpl(sourceId, draft));
+    }
+    async applyDraftImpl(sourceId, draft) {
+        const { manifest, lockFile } = await this.store.readState();
         this.normalizeBindings(manifest, lockFile);
         const prepared = this.prepareManifestForDraft(manifest, lockFile, sourceId, draft);
         const plan = await this.planForAffectedSources(prepared.manifest, lockFile, sourceId);
@@ -310,56 +285,143 @@ export class SkillFlowApp {
             return fail(plan.errors, [...prepared.warnings, ...plan.warnings]);
         }
         const applyResult = await this.applier.applyPlan(lockFile, plan.data.actions);
-        await this.store.writeManifest(prepared.manifest);
-        await this.store.writeLock(lockFile);
+        await this.store.writeState(prepared.manifest, lockFile);
         if (!applyResult.ok) {
             return fail(applyResult.errors, [...prepared.warnings, ...plan.warnings, ...applyResult.warnings]);
         }
         return ok({ actions: plan.data.actions, draft: prepared.draft }, [...prepared.warnings, ...plan.warnings, ...applyResult.warnings]);
     }
     async updateSources(sourceIds) {
-        const reconciled = await this.sourceService.reconcileInventory(sourceIds, {
-            force: true,
-        });
-        if (!reconciled.ok) {
-            return fail(reconciled.errors, reconciled.warnings);
+        return this.runSerializedMutation(() => this.updateSourcesImpl(sourceIds));
+    }
+    async updateSourcesImpl(sourceIds) {
+        const pruned = await this.pruneMissingCheckoutsImpl();
+        if (!pruned.ok) {
+            return fail(pruned.errors, pruned.warnings);
         }
-        const updated = await this.sourceService.updateSources(sourceIds);
+        const requestedIds = sourceIds?.filter((sourceId) => !pruned.data.removedSourceIds.includes(sourceId));
+        if (sourceIds?.length && requestedIds?.length === 0) {
+            return ok({ updated: [] }, pruned.warnings);
+        }
+        const updated = await this.sourceService.updateSources(requestedIds);
         if (!updated.ok) {
             return updated;
         }
-        const manifest = await this.store.readManifest();
-        const lockFile = await this.store.readLock();
-        this.applySelectionModeForUpdatedSources(manifest, lockFile, updated.data.updated);
+        const { manifest, lockFile } = await this.store.readState();
+        this.applySourceUpdateResults(manifest, lockFile, updated.data.updated);
         await this.persistNormalizedBindings(manifest, lockFile);
-        const activeSourceIds = manifest.sources
+        const planSourceIds = manifest.sources
             .map((source) => source.id)
-            .filter((id) => this.hasActiveTargets(manifest, id));
-        for (const sourceId of activeSourceIds) {
-            const plan = await this.planner.planForSource(sourceId, manifest, lockFile);
-            if (!plan.ok) {
-                return fail(plan.errors, plan.warnings);
-            }
-            await this.applier.applyPlan(lockFile, plan.data.actions);
+            .filter((id) => updated.data.updated.some((item) => item.sourceId === id) ||
+            this.hasActiveTargets(manifest, id) ||
+            lockFile.deployments.some((deployment) => deployment.sourceId === id));
+        const planned = await this.planAndApplySources(manifest, lockFile, planSourceIds);
+        if (!planned.ok) {
+            return fail(planned.errors, [...pruned.warnings, ...updated.warnings, ...planned.warnings]);
         }
-        await this.store.writeLock(lockFile);
-        return updated;
+        await this.store.writeState(manifest, lockFile);
+        return ok(updated.data, [...pruned.warnings, ...updated.warnings, ...planned.warnings]);
     }
     async doctor() {
+        return this.runSerializedMutation(() => this.doctorImpl());
+    }
+    async doctorImpl() {
+        const pruned = await this.pruneMissingCheckoutsImpl();
+        if (!pruned.ok) {
+            return fail(pruned.errors, pruned.warnings);
+        }
         const reconciled = await this.sourceService.reconcileInventory();
         if (!reconciled.ok) {
             return fail(reconciled.errors, reconciled.warnings);
         }
-        await this.store.init();
-        const manifest = await this.store.readManifest();
-        const lockFile = await this.store.readLock();
+        const { manifest, lockFile } = await this.store.readState();
         await this.persistNormalizedBindings(manifest, lockFile);
-        return this.doctorService.run(manifest, lockFile);
+        const doctor = await this.doctorService.run(manifest, lockFile);
+        if (!doctor.ok) {
+            return doctor;
+        }
+        return ok(doctor.data, [...pruned.warnings, ...doctor.warnings]);
+    }
+    async repairTargets(sourceIds) {
+        return this.runSerializedMutation(() => this.repairTargetsImpl(sourceIds));
+    }
+    async repairTargetsImpl(sourceIds) {
+        const { manifest, lockFile } = await this.store.readState();
+        this.normalizeBindings(manifest, lockFile);
+        const requestedIds = sourceIds?.length
+            ? sourceIds
+            : manifest.sources.map((source) => source.id);
+        for (const sourceId of requestedIds) {
+            if (!manifest.sources.some((source) => source.id === sourceId)) {
+                return fail({
+                    code: "SOURCE_NOT_FOUND",
+                    message: `Skills group id '${sourceId}' is not registered.`,
+                });
+            }
+        }
+        const planSourceIds = requestedIds.filter((sourceId) => this.hasActiveTargets(manifest, sourceId) ||
+            lockFile.deployments.some((deployment) => deployment.sourceId === sourceId));
+        const planned = await this.planAndApplySources(manifest, lockFile, planSourceIds);
+        if (!planned.ok) {
+            return fail(planned.errors, planned.warnings);
+        }
+        await this.store.writeState(manifest, lockFile);
+        return ok({ actions: planned.data.actions }, planned.warnings);
+    }
+    async repairSource(sourceIds) {
+        return this.runSerializedMutation(() => this.repairSourceImpl(sourceIds));
+    }
+    async repairSourceImpl(sourceIds) {
+        const pruned = await this.pruneMissingCheckoutsImpl();
+        if (!pruned.ok) {
+            return fail(pruned.errors, pruned.warnings);
+        }
+        const requestedIds = sourceIds?.filter((sourceId) => !pruned.data.removedSourceIds.includes(sourceId));
+        if (sourceIds?.length && requestedIds?.length === 0) {
+            return ok({ updated: [] }, pruned.warnings);
+        }
+        const repaired = await this.sourceService.updateSources(requestedIds);
+        if (!repaired.ok) {
+            return repaired;
+        }
+        const { manifest, lockFile } = await this.store.readState();
+        this.applySourceUpdateResults(manifest, lockFile, repaired.data.updated);
+        await this.persistNormalizedBindings(manifest, lockFile);
+        await this.store.writeState(manifest, lockFile);
+        return ok(repaired.data, [...pruned.warnings, ...repaired.warnings]);
+    }
+    async repairState(sourceIds) {
+        return this.runSerializedMutation(() => this.repairStateImpl(sourceIds));
+    }
+    async repairStateImpl(sourceIds) {
+        const pruned = await this.pruneMissingCheckoutsImpl();
+        if (!pruned.ok) {
+            return fail(pruned.errors, pruned.warnings);
+        }
+        const requestedIds = sourceIds?.filter((sourceId) => !pruned.data.removedSourceIds.includes(sourceId));
+        if (sourceIds?.length && requestedIds?.length === 0) {
+            return ok({ repairedSourceIds: [], removedDeploymentCount: 0 }, pruned.warnings);
+        }
+        const reconciled = await this.sourceService.reconcileInventory(requestedIds, {
+            force: true,
+        });
+        if (!reconciled.ok) {
+            return fail(reconciled.errors, [...pruned.warnings, ...reconciled.warnings]);
+        }
+        const { manifest, lockFile } = await this.store.readState();
+        await this.persistNormalizedBindings(manifest, lockFile);
+        const removedDeploymentCount = await this.rebuildDeploymentState(manifest, lockFile, requestedIds);
+        await this.store.writeState(manifest, lockFile);
+        return ok({
+            repairedSourceIds: reconciled.data.updatedSourceIds,
+            removedDeploymentCount,
+        }, [...pruned.warnings, ...reconciled.warnings]);
     }
     async uninstall(sourceIds) {
-        await this.store.init();
-        const manifest = await this.store.readManifest();
-        const lockFile = await this.store.readLock();
+        return this.runSerializedMutation(() => this.uninstallImpl(sourceIds));
+    }
+    async uninstallImpl(sourceIds) {
+        const { manifest, lockFile } = await this.store.readState();
         const warnings = [];
         const removedRefs = sourceIds
             .map((sourceId) => manifest.sources.find((source) => source.id === sourceId))
@@ -370,26 +432,33 @@ export class SkillFlowApp {
                 if (!(await pathExists(deployment.targetPath))) {
                     continue;
                 }
-                if (deployment.strategy === "symlink") {
-                    const stats = await fs.lstat(deployment.targetPath);
-                    if (stats.isSymbolicLink()) {
-                        await removePath(deployment.targetPath);
-                    }
-                    else {
-                        warnings.push(`Skipped ${deployment.targetPath} because it no longer looks like a managed symlink.`);
-                    }
-                    continue;
-                }
-                const currentHash = await hashDirectory(deployment.targetPath);
-                if (currentHash === deployment.contentHash) {
+                try {
                     await removePath(deployment.targetPath);
                 }
-                else {
-                    warnings.push(`Skipped ${deployment.targetPath} because the copied skill has drifted from saved state.`);
+                catch (error) {
+                    warnings.push(`Unable to remove ${deployment.targetPath}: ${String(error)}`);
                 }
             }
         }
-        const removed = await this.sourceService.removeSource(sourceIds);
+        if (warnings.length > 0) {
+            return fail({
+                code: "GROUP_DELETE_INCOMPLETE",
+                message: `Unable to fully delete ${warnings.length} managed path${warnings.length === 1 ? "" : "s"}.`,
+            }, warnings.map((message) => ({
+                code: "GROUP_DELETE_PATH_FAILED",
+                message,
+            })));
+        }
+        let removed;
+        try {
+            removed = await this.sourceService.removeSource(sourceIds);
+        }
+        catch (error) {
+            return fail({
+                code: "GROUP_DELETE_INCOMPLETE",
+                message: `Unable to fully delete selected skills groups: ${String(error)}`,
+            });
+        }
         if (!removed.ok) {
             return fail(removed.errors, removed.warnings);
         }
@@ -405,11 +474,58 @@ export class SkillFlowApp {
         }
         return { targets };
     }
+    async pruneMissingCheckoutsImpl() {
+        const { manifest, lockFile } = await this.store.readState();
+        const removedSourceIds = [];
+        const warnings = [];
+        for (const source of lockFile.sources) {
+            if (await pathExists(source.checkoutPath)) {
+                continue;
+            }
+            removedSourceIds.push(source.id);
+            warnings.push({
+                code: "SOURCE_CHECKOUT_MISSING",
+                message: `Removed ${source.displayName} because checkout is missing at ${source.checkoutPath}.`,
+            });
+            const deployments = lockFile.deployments.filter((deployment) => deployment.sourceId === source.id);
+            for (const deployment of deployments) {
+                if (!(await pathExists(deployment.targetPath))) {
+                    continue;
+                }
+                try {
+                    await removePath(deployment.targetPath);
+                }
+                catch (error) {
+                    return fail({
+                        code: "SOURCE_CHECKOUT_PRUNE_FAILED",
+                        message: `Unable to clean deployment ${deployment.targetPath}: ${String(error)}`,
+                    }, warnings);
+                }
+            }
+        }
+        if (removedSourceIds.length === 0) {
+            return ok({ removedSourceIds: [] });
+        }
+        manifest.sources = manifest.sources.filter((source) => !removedSourceIds.includes(source.id));
+        for (const sourceId of removedSourceIds) {
+            delete manifest.bindings[sourceId];
+        }
+        lockFile.sources = lockFile.sources.filter((source) => !removedSourceIds.includes(source.id));
+        lockFile.leafInventory = lockFile.leafInventory.filter((leaf) => !removedSourceIds.includes(leaf.sourceId));
+        lockFile.deployments = lockFile.deployments.filter((deployment) => !removedSourceIds.includes(deployment.sourceId));
+        await this.store.writeState(manifest, lockFile);
+        return ok({ removedSourceIds }, warnings);
+    }
     async persistNormalizedBindings(manifest, lockFile) {
         if (!this.normalizeBindings(manifest, lockFile)) {
             return;
         }
-        await this.store.writeManifest(manifest);
+        await this.store.writeState(manifest, lockFile);
+    }
+    async runSerializedMutation(task) {
+        const run = this.mutationQueue.then(() => this.store.withMutationLock(task), () => this.store.withMutationLock(task));
+        this.mutationQueue = run.then(() => undefined, () => undefined);
+        return run;
     }
     normalizeBindings(manifest, lockFile) {
         let changed = false;
@@ -439,15 +555,22 @@ export class SkillFlowApp {
         };
     }
     selectLeafIdsForRequestedPath(leafs, requestedPath) {
-        if (!requestedPath) {
+        const normalizedPath = this.normalizeRequestedPath(requestedPath);
+        if (!normalizedPath) {
             return leafs.map((leaf) => leaf.id);
         }
-        const normalizedPath = requestedPath.replace(/^\.\/+/, "").replace(/\/+$/, "");
         return leafs
             .filter((leaf) => leaf.relativePath === normalizedPath ||
             leaf.relativePath.startsWith(`${normalizedPath}/`))
             .map((leaf) => leaf.id);
     }
+    normalizeRequestedPath(requestedPath) {
+        if (!requestedPath) {
+            return undefined;
+        }
+        const normalized = requestedPath.trim().replace(/^\.\/+/, "").replace(/\/+$/, "");
+        return normalized.length > 0 && normalized !== "." ? normalized : undefined;
+    }
     prepareManifestForDraft(manifest, lockFile, sourceId, draft) {
         manifest.bindings[sourceId] = this.bindingFromDraft(draft);
         const source = manifest.sources.find((item) => item.id === sourceId);
@@ -510,9 +633,13 @@ export class SkillFlowApp {
         const sourceIds = manifest.sources
             .map((source) => source.id)
             .filter((sourceId) => sourceId === primarySourceId || this.hasActiveTargets(manifest, sourceId));
+        return this.planForSources(manifest, lockFile, sourceIds);
+    }
+    async planForSources(manifest, lockFile, sourceIds) {
+        const uniqueSourceIds = [...new Set(sourceIds)];
         const actions = [];
         const warnings = [];
-        for (const sourceId of sourceIds) {
+        for (const sourceId of uniqueSourceIds) {
             const plan = await this.planner.planForSource(sourceId, manifest, lockFile);
             if (!plan.ok) {
                 return fail(plan.errors, [...warnings, ...plan.warnings]);
@@ -526,6 +653,148 @@ export class SkillFlowApp {
             blocked: actions.filter((action) => action.kind === "blocked"),
         }, warnings);
     }
+    async planAndApplySources(manifest, lockFile, sourceIds) {
+        const planned = await this.planForSources(manifest, lockFile, sourceIds);
+        if (!planned.ok) {
+            return fail(planned.errors, planned.warnings);
+        }
+        const applyResult = await this.applier.applyPlan(lockFile, planned.data.actions);
+        if (!applyResult.ok) {
+            return fail(applyResult.errors, [...planned.warnings, ...applyResult.warnings]);
+        }
+        return ok({ actions: planned.data.actions }, [...planned.warnings, ...applyResult.warnings]);
+    }
+    async rebuildDeploymentState(manifest, lockFile, sourceIds) {
+        const requested = sourceIds?.length ? new Set(sourceIds) : undefined;
+        const previousDeployments = lockFile.deployments;
+        const previousCount = previousDeployments.length;
+        const previousByKey = new Map(previousDeployments.map((deployment) => [
+            this.getDeploymentKey(deployment.sourceId, deployment.leafId, deployment.target),
+            deployment,
+        ]));
+        const nextDeployments = previousDeployments.filter((deployment) => requested ? !requested.has(deployment.sourceId) : false);
+        const adapters = createChannelAdapters();
+        const detectionCache = new Map();
+        const projectedNameCache = new Map();
+        for (const source of manifest.sources) {
+            if (requested && !requested.has(source.id)) {
+                continue;
+            }
+            const binding = manifest.bindings[source.id] ?? { targets: {} };
+            for (const adapter of adapters) {
+                const targetBinding = binding.targets[adapter.target];
+                if (!targetBinding?.enabled) {
+                    continue;
+                }
+                let detection = detectionCache.get(adapter.target);
+                if (!detection) {
+                    detection = await adapter.detect();
+                    detectionCache.set(adapter.target, detection);
+                }
+                for (const leafId of targetBinding.leafIds) {
+                    const leaf = lockFile.leafInventory.find((candidate) => candidate.sourceId === source.id && candidate.id === leafId);
+                    if (!leaf) {
+                        continue;
+                    }
+                    const existing = previousByKey.get(this.getDeploymentKey(source.id, leaf.id, adapter.target));
+                    if (!detection.available) {
+                        if (existing) {
+                            nextDeployments.push({
+                                ...existing,
+                                contentHash: leaf.contentHash,
+                                status: "active",
+                            });
+                        }
+                        continue;
+                    }
+                    let projectedLinkNames = projectedNameCache.get(adapter.target);
+                    if (!projectedLinkNames) {
+                        projectedLinkNames = this.buildProjectedLinkNameMap(manifest, lockFile, adapter.target);
+                        projectedNameCache.set(adapter.target, projectedLinkNames);
+                    }
+                    const rebuilt = await this.findManagedDeploymentOnDisk(source, leaf, adapter.target, adapter.strategy, detection.rootPath, projectedLinkNames, existing);
+                    if (!rebuilt) {
+                        continue;
+                    }
+                    nextDeployments.push(rebuilt);
+                }
+            }
+        }
+        lockFile.deployments = nextDeployments;
+        return Math.max(0, previousCount - nextDeployments.length);
+    }
+    buildProjectedLinkNameMap(manifest, lockFile, target) {
+        return resolveProjectedSkillNames(manifest.sources.flatMap((source) => {
+            const targetBinding = manifest.bindings[source.id]?.targets[target];
+            if (!targetBinding?.enabled) {
+                return [];
+            }
+            return targetBinding.leafIds
+                .map((leafId) => lockFile.leafInventory.find((leaf) => leaf.id === leafId))
+                .filter((leaf) => Boolean(leaf))
+                .map((leaf) => ({
+                leafId: leaf.id,
+                groupId: source.id,
+                groupName: source.displayName,
+                groupAuthor: parseGitHubRepo(source.locator)?.owner,
+                skillName: leaf.linkName,
+            }));
+        }));
+    }
+    async findManagedDeploymentOnDisk(source, leaf, target, strategy, rootPath, projectedLinkNames, existing) {
+        const projectedLinkName = projectedLinkNames.get(leaf.id) ?? leaf.linkName;
+        const candidatePaths = buildProjectedSkillNameCandidates({
+            preferredName: projectedLinkName,
+            groupId: source.id,
+            groupName: source.displayName,
+            groupAuthor: parseGitHubRepo(source.locator)?.owner,
+            skillName: leaf.linkName,
+        }).map((name) => path.join(rootPath, name));
+        if (existing?.targetPath && !candidatePaths.includes(existing.targetPath)) {
+            candidatePaths.unshift(existing.targetPath);
+        }
+        for (const targetPath of candidatePaths) {
+            const matches = await this.matchesManagedProjection(strategy, targetPath, leaf);
+            if (!matches) {
+                continue;
+            }
+            return {
+                sourceId: source.id,
+                leafId: leaf.id,
+                target,
+                targetPath,
+                strategy,
+                status: "active",
+                contentHash: leaf.contentHash,
+                appliedAt: existing?.appliedAt ?? new Date().toISOString(),
+            };
+        }
+        return undefined;
+    }
+    async matchesManagedProjection(strategy, targetPath, leaf) {
+        try {
+            const stats = await fs.lstat(targetPath);
+            if (strategy === "symlink") {
+                if (!stats.isSymbolicLink()) {
+                    return false;
+                }
+                const linked = await fs.readlink(targetPath);
+                const resolved = path.resolve(path.dirname(targetPath), linked);
+                return resolved === leaf.absolutePath;
+            }
+            if (!stats.isDirectory()) {
+                return false;
+            }
+            const onDiskHash = await hashDirectory(targetPath);
+            return onDiskHash === leaf.contentHash;
+        }
+        catch {
+            return false;
+        }
+    }
+    getDeploymentKey(sourceId, leafId, target) {
+        return `${sourceId}\n${leafId}\n${target}`;
+    }
     hasActiveTargets(manifest, sourceId) {
         const binding = manifest.bindings[sourceId];
         if (!binding) {
@@ -547,7 +816,7 @@ export class SkillFlowApp {
             const source = manifest.sources.find((item) => item.id === leaf.sourceId);
             return {
                 id: `local:${leaf.id}`,
-                title: leaf.title,
+                title: this.getCandidateTitle(leaf),
                 description: leaf.description,
                 source: "local",
                 sourceLabel: source
@@ -666,7 +935,7 @@ export class SkillFlowApp {
         if (tokens.length === 0) {
             return true;
         }
-        const haystack = fields.join("\n").toLowerCase();
+        const haystack = this.normalizeSearchQuery(fields.join("\n"));
         return tokens.every((token) => haystack.includes(token));
     }
     compareCandidates(left, right, query) {
@@ -696,8 +965,8 @@ export class SkillFlowApp {
     }
     getQueryScore(candidate, query) {
         const tokens = query.split(/\s+/).filter(Boolean);
-        const titleField = candidate.title.toLowerCase();
-        const pathTail = (candidate.relativePath ?? "").split("/").pop()?.toLowerCase() ?? "";
+        const titleField = this.normalizeSearchQuery(candidate.title);
+        const pathTail = this.normalizeSearchQuery((candidate.relativePath ?? "").split("/").pop() ?? "");
         const fields = [
             titleField,
             pathTail,
@@ -723,6 +992,16 @@ export class SkillFlowApp {
         }
         return candidate.locator;
     }
+    getCandidateTitle(leaf) {
+        const title = leaf.title.trim();
+        if (title.length === 0 || /^\{[^}]+\}$/.test(title)) {
+            return leaf.linkName || leaf.name;
+        }
+        return title;
+    }
+    normalizeSearchQuery(value) {
+        return value.trim().toLowerCase().replace(/[_-]+/g, " ").replace(/\s+/g, " ");
+    }
     formatSourceLabel(locator, displayName) {
         if (locator.startsWith("clawhub:")) {
             return `${displayName}@clawhub`;
@@ -736,30 +1015,41 @@ export class SkillFlowApp {
         }
         return `${displayName}@${repo.owner}`;
     }
-    buildInitialDrafts(summaries) {
-        return Object.fromEntries(summaries.map((summary) => {
-            const enabledTargets = Object.entries(summary.bindings.targets)
-                .filter(([, value]) => value?.enabled)
-                .map(([target]) => target);
-            const selectedLeafIds = [...new Set(enabledTargets.flatMap((target) => summary.bindings.targets[target]?.leafIds ?? []))];
-            return [summary.source.id, { enabledTargets, selectedLeafIds }];
-        }));
-    }
-    applySelectionModeForUpdatedSources(manifest, lockFile, updates) {
+    applySourceUpdateResults(manifest, lockFile, updates) {
         for (const update of updates) {
-            if (!update.changed || update.addedLeafIds.length === 0) {
+            if (!update.changed) {
                 continue;
             }
             const source = manifest.sources.find((item) => item.id === update.sourceId);
             const binding = manifest.bindings[update.sourceId];
-            if (!source || !binding || source.selectionMode !== "all") {
+            if (!source || !binding) {
+                continue;
+            }
+            for (const diff of update.diffs) {
+                if (diff.kind !== "moved" || !diff.previousLeafId) {
+                    continue;
+                }
+                for (const targetBinding of Object.values(binding.targets)) {
+                    if (!targetBinding?.enabled || !targetBinding.leafIds.includes(diff.previousLeafId)) {
+                        continue;
+                    }
+                    targetBinding.leafIds = targetBinding.leafIds.map((leafId) => leafId === diff.previousLeafId ? diff.leafId : leafId);
+                }
+            }
+            if ((update.selectionMode ?? source.selectionMode) !== "all") {
+                continue;
+            }
+            const addedLeafIds = update.diffs
+                .filter((diff) => diff.kind === "added")
+                .map((diff) => diff.leafId);
+            if (addedLeafIds.length === 0) {
                 continue;
             }
             for (const targetBinding of Object.values(binding.targets)) {
                 if (!targetBinding?.enabled) {
                     continue;
                 }
-                const merged = new Set([...targetBinding.leafIds, ...update.addedLeafIds]);
+                const merged = new Set([...targetBinding.leafIds, ...addedLeafIds]);
                 targetBinding.leafIds = [...merged].filter((leafId) => lockFile.leafInventory.some((leaf) => leaf.id === leafId && leaf.sourceId === update.sourceId));
             }
         }