devflow-kit 3.10.0 → 3.12.0

package/dist/targets/claude-code/curation-install.js

@@ -91,15 +91,16 @@ import { isProxyEnabled } from '../../core/proxy-state.js';
 import { WORKFLOW_FOLDERS } from '../../core/mds-variants.js';
 import { DEVFLOW_PLUGINS, CURATION_GATED_SKILLS, installedLanguageFocuses, prefixSkillName, selectedWorkflowFolders, skillsOf, workflowFolderNames, } from '../../core/plugins.js';
 import { convergeFromManifest } from './compliance-install.js';
+import { swapFolderIn } from './folder-swap.js';
 import { copyDirectory, resolveSkillSource } from './installer.js';
 import { LANGUAGE_STAMPED_COMMANDS, stampForConverge } from './language-stamp.js';
-import { entryIsLink, newLinkReport, refuseUnrealFolder, refusedFolderMessage, warnLinkReport, writeFileReplacingLink } from './linked-folder.js';
+import { directoryState, newLinkReport, refuseUnrealFolder, refusedFolderMessage, unlinkLinkAt, warnLinkReport, writeFileReplacingLink } from './linked-folder.js';
 import { convergeReferences } from './reference-converge.js';
 import { installWorkflowFolder, readWorkflowFolder } from './workflow-folder-install.js';
 // ── Bounds ─────────────────────────────────────────────────────────────────
 /**
- * The most variant files one kind may carry. The shipped roster is 14 commands and
- * 9 agents; the bound exists so a directory that grew without limit cannot turn the
+ * The most variant files one kind may carry. The shipped roster is 13 commands and
+ * 11 agents; the bound exists so a directory that grew without limit cannot turn the
  * converge into an unbounded loop (every loop has an explicit bound).
  */
 export const MAX_CURATION_ROSTER = 256;
@@ -380,6 +381,16 @@ async function pathExists(p) {
         return false;
     }
 }
+/**
+ * The two folders a skill swap uses, both directly under `claudeDir`: the staging copy, and the
+ * backup the old skill folder waits in while the copy is renamed into place.
+ *
+ * @param now - The clock reading that makes the name unique, in milliseconds.
+ */
+export function curationSwapPaths(claudeDir, now) {
+    const staging = path.join(claudeDir, `.devflow-curation-${process.pid}-${now.toString(36)}.tmp`);
+    return { staging, backup: `${staging}.old` };
+}
 /**
  * Install one skill directory atomically: stage a copy beside the claude dir's
  * skills, then swap it in, restoring the old directory if the swap fails.
@@ -387,33 +398,56 @@ async function pathExists(p) {
  * Staged under `claudeDir` itself, not under `skills/`: a staging directory a
  * crash leaves behind must not look like a second skill to Claude Code.
  *
+ * A file in the old directory that devflow did not ship moves to the backup folder first. If one
+ * cannot move, nothing is swapped: the shipped files are written into the old directory and the
+ * file stays (see {@link swapFolderIn}).
+ *
  * A target that is a link is moved aside as the link itself, never followed, so what it points to is
  * left as it was; the link is recorded in `links` once the real folder stands in its place.
  */
-async function swapInSkillDirectory(claudeDir, sourceDir, target, links) {
-    const staging = path.join(claudeDir, `.devflow-curation-${process.pid}-${Date.now().toString(36)}.tmp`);
-    const backup = `${staging}.old`;
+async function swapInSkillDirectory(claudeDir, sourceDir, target, links, backups) {
+    const { staging, backup } = curationSwapPaths(claudeDir, Date.now());
     try {
         await copyDirectory(sourceDir, staging);
         await fs.mkdir(path.dirname(target), { recursive: true });
-        const wasLink = await entryIsLink(target);
-        const hadTarget = wasLink || await pathExists(target);
-        if (hadTarget)
-            await fs.rename(target, backup);
-        try {
-            await fs.rename(staging, target);
-        }
-        catch (err) {
-            if (hadTarget)
-                await fs.rename(backup, target);
-            throw err;
-        }
-        if (wasLink)
-            links.replacedLinks.push(target);
+        await swapFolderIn({
+            backups,
+            target,
+            staged: staging,
+            aside: backup,
+            links,
+            mergeInto: () => copyDirectory(staging, target, undefined, links),
+        });
     }
     finally {
         await fs.rm(staging, { recursive: true, force: true }).catch(() => undefined);
-        await fs.rm(backup, { recursive: true, force: true }).catch(() => undefined);
+    }
+}
+/**
+ * Remove a curation-gated skill folder. The files devflow shipped go by the session's list, anything
+ * else moves to the backup folder first, and the folder goes with a plain `rmdir`: 'kept' means it
+ * still stands because a file could not move. A link is unlinked and a file in its place moves aside.
+ */
+async function removeSkillFolder(target, backups) {
+    const state = await directoryState(target);
+    switch (state) {
+        case 'absent':
+            return 'absent';
+        case 'link':
+            return (await unlinkLinkAt(target)) === 'unlinked' ? 'removed' : 'kept';
+        case 'unusable': {
+            const moved = await backups.moveWhole(target);
+            return moved.status === 'moved' ? 'removed' : moved.status === 'absent' ? 'absent' : 'kept';
+        }
+        case 'real': {
+            await backups.prepass([target]);
+            return (await backups.removeListed(target)).folderRemoved ? 'removed' : 'kept';
+        }
+        default: {
+            const unreachable = state;
+            void unreachable;
+            return 'kept';
+        }
     }
 }
 /** Converge the curation-gated skill directories. A skill folder that was a link and was swapped is recorded in `links`. Never throws. */
@@ -421,15 +455,24 @@ async function convergeSkills(opts, links) {
     const { claudeDir, devflowDir, curation, plugins, warn } = opts;
     const selected = skillsOf(plugins);
     let state = 'unchanged';
+    // A skills folder that is a link or not a folder is refused once. The removal and the swap below
+    // would reach the folder the link points to: `directoryState` of a skill folder follows the link
+    // above it. The refusal is recorded in `links`, and the converge is not clean.
+    if (await refuseUnrealFolder(links, path.join(claudeDir, 'skills')))
+        return 'failed';
     // Every gated skill is converged: a failure on one must not skip the next.
     for (const skill of CURATION_GATED_SKILLS) {
         const target = path.join(claudeDir, 'skills', prefixSkillName(skill));
         try {
             if (!curation) {
-                if (!(await pathExists(target)))
-                    continue;
-                await fs.rm(target, { recursive: true });
-                state = 'removed';
+                const removal = await removeSkillFolder(target, opts.backups);
+                if (removal === 'removed') {
+                    state = 'removed';
+                }
+                else if (removal === 'kept') {
+                    warn(`curation variants: the ${prefixSkillName(skill)} skill folder (${target}) still holds a file that could not be moved aside, so it was not removed`);
+                    state = 'failed';
+                }
                 continue;
             }
             if (!selected.has(skill)) {
@@ -440,7 +483,7 @@ async function convergeSkills(opts, links) {
             const resolved = await resolveSkillSource(skill, devflowDir, opts.packageRoot);
             if ((await pathExists(target)) && (await treesIdentical(resolved.dir, target)))
                 continue;
-            await swapInSkillDirectory(claudeDir, resolved.dir, target, links);
+            await swapInSkillDirectory(claudeDir, resolved.dir, target, links, opts.backups);
             state = 'installed';
         }
         catch (err) {
@@ -590,7 +633,7 @@ async function attempt(label, warn, fallback, run) {
  * install owns the removal. Never throws.
  */
 async function convergeWorkflowFolders(opts) {
-    const { claudeDir, switches, plugins, folders, root, warn } = opts;
+    const { claudeDir, switches, plugins, folders, root, warn, backups } = opts;
     const installed = [];
     const unchanged = [];
     const failures = [];
@@ -611,7 +654,7 @@ async function convergeWorkflowFolders(opts) {
             continue;
         }
         const links = newLinkReport();
-        const result = await installWorkflowFolder({ claudeDir, name: folder.name, files: read.files, links });
+        const result = await installWorkflowFolder({ claudeDir, name: folder.name, files: read.files, links, backups });
         switch (result.outcome) {
             case 'installed':
                 installed.push(folder.name);
@@ -668,7 +711,7 @@ export function workflowFoldersPosting(folders, compliance) {
  * Never throws.
  */
 export async function convergeVariantAxes(opts) {
-    const { claudeDir, devflowDir, manifest, plugins, warn, packageRoot } = opts;
+    const { claudeDir, devflowDir, manifest, plugins, warn, packageRoot, backups } = opts;
     const switches = { curation: manifest.features.curation, compliance: manifest.features.compliance.enabled };
     // Precondition, asserted in production code: a relative claudeDir would resolve
     // every install target somewhere unexpected, the skill removal included.
@@ -692,9 +735,9 @@ export async function convergeVariantAxes(opts) {
     }
     const prompts = await attempt('prompt variants', warn, notRun(switches, 'the prompt converge failed'), () => convergePromptVariants({ claudeDir, switches, plugins, warn, packageRoot }));
     const skillLinks = newLinkReport();
-    const skill = await attempt('curation variants', warn, 'failed', () => convergeSkills({ claudeDir, devflowDir, curation: switches.curation, plugins, warn, packageRoot }, skillLinks));
+    const skill = await attempt('curation variants', warn, 'failed', () => convergeSkills({ claudeDir, devflowDir, curation: switches.curation, plugins, warn, packageRoot, backups }, skillLinks));
     warnLinkReport(skillLinks, warn);
-    const compliance = await attempt('compliance artifacts', warn, { removedPreexisting: false, converged: false, replacedLinks: [], refusedFolders: [] }, () => convergeFromManifest({ claudeDir, devflowDir, manifest, warn }));
+    const compliance = await attempt('compliance artifacts', warn, { removedPreexisting: false, converged: false, replacedLinks: [], refusedFolders: [] }, () => convergeFromManifest({ claudeDir, devflowDir, manifest, warn, backups }));
     const references = await attempt('reference converge', warn, {
         converged: false,
         rewritten: [],
@@ -703,7 +746,7 @@ export async function convergeVariantAxes(opts) {
         failures: ['the reference converge failed'],
         stillPosting: [],
         unproven: !switches.compliance,
-    }, () => convergeReferences({ claudeDir, devflowDir, compliance: switches.compliance, warn, packageRoot }));
+    }, () => convergeReferences({ claudeDir, devflowDir, compliance: switches.compliance, warn, packageRoot, backups }));
     const workflowFolders = await attempt('workflow folders', warn, { converged: false, installed: [], unchanged: [], failures: ['the workflow folder converge failed'], stalled: [] }, () => convergeWorkflowFolders({
         claudeDir,
         switches,
@@ -711,6 +754,7 @@ export async function convergeVariantAxes(opts) {
         folders: opts.workflowFolders ?? WORKFLOW_FOLDERS,
         root: opts.workflowFoldersRoot ?? packageRoot ?? getPackageRoot(),
         warn,
+        backups,
     }));
     return {
         converged: prompts.converged && skill !== 'failed' && compliance.converged && references.converged && workflowFolders.converged,
@@ -975,6 +1019,7 @@ export async function applyVariantToggle(opts) {
         plugins: DEVFLOW_PLUGINS.filter(plugin => selection.has(plugin.name)),
         warn,
         packageRoot: opts.packageRoot,
+        backups: opts.backups,
     });
     if (result.converged) {
         await recordInstalledVariants(devflowDir, { curation: state.features.curation, compliance: state.features.compliance.enabled }, warn);

package/dist/targets/claude-code/folder-swap.js

@@ -0,0 +1,142 @@
+/**
+ * The swap of a folder that devflow owns and that may hold files of the user's: a skill folder the
+ * converge replaces. The new folder is built beside the old one and renamed in; the old folder waits
+ * in an aside folder while that happens.
+ *
+ * Nothing here removes a folder with a recursive `rm`. Before the swap, the backup session moves
+ * every file devflow did not ship out of the old folder. If any file could not move, the folder is
+ * not swapped: the files devflow ships are written into it one by one, and it stays in place. The
+ * write comes before any removal, so a copy that fails leaves the old shipped files in the folder;
+ * then only the listed entries that the new folder lacks are removed. The same holds when the aside
+ * name is taken by a folder that keeps a file. A file at the aside name
+ * moves to the backup folder first; if it cannot move, a rename never replaces it, so a folder
+ * stays in place and a link makes the swap throw. After
+ * a swap, the aside folder is scanned again, because a file can arrive between the first scan and the
+ * rename. What the session moves out of it is named, what devflow shipped is removed by the list the
+ * scan made, and the folder goes with a plain `rmdir`; a folder that still holds a file stays.
+ *
+ * This module imports no installer module, so the install and the converge steps can all use it.
+ * A swap that cannot finish throws, and the caller reports it.
+ */
+import { promises as fs } from 'fs';
+import * as path from 'path';
+import { DEFAULT_ENTRY_CAP, MAX_WALK_DEPTH } from './install-backup.js';
+import { directoryState, unlinkLinkAt } from './linked-folder.js';
+const errorMessage = (err) => (err instanceof Error ? err.message : String(err));
+/**
+ * Remove a folder that was displaced from `stoodAt`: scan it as if it still stood there, move what
+ * devflow did not ship, remove what it shipped by the session's list, then `rmdir`. A displaced link
+ * is unlinked. A folder that still holds a file stays, and the session's record names the file.
+ */
+export async function discardDisplacedFolder(backups, aside, stoodAt) {
+    const state = await directoryState(aside);
+    if (state === 'link') {
+        await unlinkLinkAt(aside);
+        return;
+    }
+    if (state !== 'real')
+        return;
+    await backups.prepass([{ folder: aside, displacedFrom: stoodAt }]);
+    await backups.removeListed(aside);
+}
+/**
+ * The files and links below `staged` as paths relative to it, with `/` separators. Null when the
+ * walk reached its depth or entry bound, because a list that stops early would name too few.
+ */
+async function stagedPaths(staged) {
+    const found = new Set();
+    async function walk(folder, rel, depth) {
+        if (depth > MAX_WALK_DEPTH)
+            return false;
+        const entries = await fs.readdir(folder, { withFileTypes: true });
+        for (const entry of entries) {
+            const childRel = rel === '' ? entry.name : `${rel}/${entry.name}`;
+            if (entry.isDirectory()) {
+                if (!(await walk(path.join(folder, entry.name), childRel, depth + 1)))
+                    return false;
+            }
+            else {
+                found.add(childRel);
+                if (found.size > DEFAULT_ENTRY_CAP)
+                    return false;
+            }
+        }
+        return true;
+    }
+    return (await walk(staged, '', 0)) ? found : null;
+}
+/**
+ * Write the files of `staged` into `target`, then remove what the old folder held and the new one
+ * lacks. The write comes first: if the copy fails, the files devflow shipped are still in the old
+ * folder. The removal scans `target` again with a filter that leaves every staged path, every kept
+ * file and everything below a kept folder alone, so `removeListed` takes only the listed leftovers
+ * (retired and sidecar names, `.DS_Store`) and the shipped files that the new release dropped.
+ * When the staged list is not complete, nothing is removed.
+ */
+async function mergeThenClear(backups, target, staged, mergeInto) {
+    const written = await stagedPaths(staged);
+    await mergeInto();
+    if (written === null)
+        return;
+    await backups.prepass([{
+            folder: target,
+            include: (relative, kind) => !(kind !== 'directory' && written.has(relative)) && !backups.isKept(path.join(target, ...relative.split('/'))),
+        }]);
+    await backups.removeListed(target);
+}
+/**
+ * Put `staged` at `target`. See the module comment for the order of the steps.
+ *
+ * If the rename of `staged` fails, the old folder is renamed back. If that fails too, the old folder
+ * stays at `aside` and the error names the path. Throws on a failure that leaves the swap undone.
+ */
+export async function swapFolderIn(options) {
+    const { backups, target, staged, aside, links, mergeInto } = options;
+    // What an earlier, interrupted swap left at the aside name is cleared first, so the rename below has a free name.
+    // A file there is not a displaced folder: it moves to the backup folder, because a rename replaces it without a trace.
+    await discardDisplacedFolder(backups, aside, target);
+    if ((await directoryState(aside)) === 'unusable')
+        await backups.moveWhole(aside);
+    const asideTaken = (await directoryState(aside)) !== 'absent';
+    let state = await directoryState(target);
+    if (state === 'unusable') {
+        const moved = await backups.moveWhole(target);
+        if (moved.status === 'kept') {
+            throw new Error(`${target} is not a folder and could not be moved aside (${moved.reason})`);
+        }
+        state = 'absent';
+    }
+    if (state === 'real') {
+        await backups.prepass([target]);
+        if (asideTaken || backups.keptUnder(target).length > 0) {
+            await mergeThenClear(backups, target, staged, mergeInto);
+            return 'merged';
+        }
+    }
+    if (state === 'link' && asideTaken) {
+        throw new Error(`${target} is a link and was not replaced: ${aside} is in the way and could not be moved`);
+    }
+    const displaced = state !== 'absent';
+    if (displaced)
+        await fs.rename(target, aside);
+    try {
+        await fs.rename(staged, target);
+    }
+    catch (err) {
+        if (displaced) {
+            try {
+                await fs.rename(aside, target);
+            }
+            catch (restoreErr) {
+                throw new Error(`${errorMessage(err)}; the previous folder could not be put back (${errorMessage(restoreErr)}) and is kept at ${aside}`);
+            }
+        }
+        throw err;
+    }
+    if (state === 'link')
+        links.replacedLinks.push(target);
+    if (displaced)
+        await discardDisplacedFolder(backups, aside, target);
+    return 'swapped';
+}
+//# sourceMappingURL=folder-swap.js.map