devflow-kit 3.8.0 → 3.10.0

package/dist/targets/claude-code/language-stamp.js

@@ -44,6 +44,7 @@ import * as path from 'path';
 import { writeFileAtomicExclusive } from '../../core/fs-atomic.js';
 import { mdFileName } from '../../core/orphan-sweep.js';
 import { installedLanguageFocuses } from '../../core/plugins.js';
+import { isUnrealFolder } from './linked-folder.js';
 /** The fixed prefix of the stamp line; the prompt and the anchored match share it. */
 export const LANGUAGE_STAMP_PREFIX = 'Installed language focuses: ';
 /** What an empty list renders as, and what the build ships. */
@@ -138,6 +139,11 @@ export async function restampInstalledCommands(opts) {
         warn(`language stamp: claudeDir is not an absolute path ("${claudeDir}") — the installed commands were not stamped`);
         return { focuses, rewritten, unchanged, absent, failed: [...LANGUAGE_STAMPED_COMMANDS] };
     }
+    // Whatever the caller's guard says, nothing is read or written through a commands folder that is a
+    // link or not a folder; every stamped command is then left as it is, and `failed` says so.
+    if (await isUnrealFolder(path.join(claudeDir, 'commands', 'devflow'))) {
+        return { focuses, rewritten, unchanged, absent, failed: [...LANGUAGE_STAMPED_COMMANDS] };
+    }
     for (const command of LANGUAGE_STAMPED_COMMANDS) {
         const target = path.join(claudeDir, 'commands', 'devflow', mdFileName(command));
         let current;

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

@@ -0,0 +1,182 @@
+import { promises as fs } from 'fs';
+import { writeFileAtomicExclusive } from '../../core/fs-atomic.js';
+/** Classify `dir` with `lstat`, so a link is seen as a link and never as the directory it points to. */
+export async function directoryState(dir) {
+    try {
+        const stat = await fs.lstat(dir);
+        if (stat.isSymbolicLink())
+            return 'link';
+        return stat.isDirectory() ? 'real' : 'unusable';
+    }
+    catch (err) {
+        return err.code === 'ENOENT' ? 'absent' : 'unusable';
+    }
+}
+/** Whether `dir` is a link or not a folder, so that a run must not write into it. An absent folder is fine: the run creates it. */
+export async function isUnrealFolder(dir) {
+    const state = await directoryState(dir);
+    return state === 'link' || state === 'unusable';
+}
+/** Whether a link stands at `entry`. An absent or unreadable entry is not a link. */
+export async function entryIsLink(entry) {
+    return (await directoryState(entry)) === 'link';
+}
+/**
+ * Remove the link at `entry` with `unlink`: the link, never what it points to.
+ *
+ * The one place the pre-clean replaces a link. `readdir` and `mkdir` follow a link, so a pre-clean
+ * that emptied through one would empty another directory. Never throws; a link that cannot be
+ * removed is `stuck`, and the caller leaves the path alone.
+ */
+export async function unlinkLinkAt(entry) {
+    if (!(await entryIsLink(entry)))
+        return 'no-link';
+    try {
+        await fs.unlink(entry);
+        return 'unlinked';
+    }
+    catch {
+        return 'stuck';
+    }
+}
+/**
+ * Remove `target` whole. A link there is unlinked instead and returned, so the caller can report it;
+ * the folder it points to is left as it is. A failure of the final `rm` is thrown.
+ */
+export async function removeReportingLink(target) {
+    const outcome = await unlinkLinkAt(target);
+    if (outcome === 'no-link')
+        await fs.rm(target, { recursive: true, force: true });
+    return outcome === 'unlinked' ? [target] : [];
+}
+/**
+ * Prove, with {@link isUnrealFolder}, that a run may write into `dir`, and record the folder in
+ * `report.refusedFolders` when it may not. Returns true for a refused folder, so the caller skips
+ * every write into it.
+ *
+ * The answer for each folder a run writes into besides the `devflow:git` references, which the
+ * installer's `referencesHostState` answers: the commands, rules and agents folders and every other
+ * skill folder. An absent folder is fine, since the install creates it. A link is refused and never
+ * repaired, because the installer did not create it. A full install's pre-clean has already replaced
+ * the links it could, so this refuses only what is left. Never throws.
+ */
+export async function refuseUnrealFolder(report, dir) {
+    if (!(await isUnrealFolder(dir)))
+        return false;
+    report.refusedFolders.push(dir);
+    return true;
+}
+/**
+ * Make `entry` safe to write: a link there is unlinked, never followed, so the caller then creates a
+ * real file or folder in its place. The entry can be a file or a folder. Only the last component is
+ * checked, so a caller checks each folder on the way down before it checks an entry in it.
+ *
+ * Fail closed: an entry `lstat` cannot inspect is refused. Never throws.
+ */
+export async function clearLinkedEntry(entry) {
+    try {
+        const stat = await fs.lstat(entry);
+        if (!stat.isSymbolicLink())
+            return 'clear';
+    }
+    catch (err) {
+        return err.code === 'ENOENT' ? 'clear' : 'refused';
+    }
+    try {
+        await fs.unlink(entry);
+        return 'replaced';
+    }
+    catch {
+        return 'refused';
+    }
+}
+/**
+ * {@link clearLinkedEntry} plus the report: a replaced link goes to `report.replacedLinks`, a refused
+ * entry to `report.refusedFolders`. Returns true when the caller may write at `entry`.
+ *
+ * The one call a write step makes before it creates or overwrites a file or folder inside a Devflow
+ * folder. Omit `report` when the step has none; the link is still never written through.
+ */
+export async function clearLinkForWrite(entry, report) {
+    const clearance = await clearLinkedEntry(entry);
+    if (clearance === 'replaced')
+        report?.replacedLinks.push(entry);
+    if (clearance === 'refused')
+        report?.refusedFolders.push(entry);
+    return clearance !== 'refused';
+}
+/** A report that holds no link yet. */
+export function newLinkReport() {
+    return { replacedLinks: [], refusedFolders: [] };
+}
+/**
+ * One report from several: the paths of every report in order, each path once. A command that gets
+ * the links of more than one step prints this, so a folder that two steps met is named once.
+ * Returns a new report; the inputs are not changed.
+ */
+export function mergeLinkReports(...reports) {
+    return {
+        replacedLinks: [...new Set(reports.flatMap(report => report.replacedLinks))],
+        refusedFolders: [...new Set(reports.flatMap(report => report.refusedFolders))],
+    };
+}
+/**
+ * The line for a link a step replaced. One wording for the install summary and for every converge
+ * that reports through a `warn` callback.
+ */
+export function replacedLinkMessage(linkPath) {
+    return `${linkPath} was a link. It was replaced with a real file or folder, and what it pointed to was left as it was.`;
+}
+/**
+ * The first sentence of every refused-folder line: what the folder is. The install and the uninstall
+ * both open with it and then say what they did and what to do.
+ */
+export function refusedFolderStatement(folder) {
+    return `${folder} is a link or not a folder.`;
+}
+/**
+ * The line for a folder a step wrote nothing at, because it is a link it could not remove or not a
+ * folder. One wording for the install summary and for every converge that reports through a `warn`
+ * callback.
+ */
+export function refusedFolderMessage(folder) {
+    return `${refusedFolderStatement(folder)} Nothing was written there. Replace it with a real file or folder and run the install again.`;
+}
+/** Send one line per link in `report` to `warn`: the replaced links first, then the refused folders. */
+export function warnLinkReport(report, warn) {
+    for (const linkPath of report.replacedLinks)
+        warn(replacedLinkMessage(linkPath));
+    for (const folder of report.refusedFolders)
+        warn(refusedFolderMessage(folder));
+}
+/** The mode of a file that replaces a link. The atomic writer would copy the mode of the link's target instead. */
+const REPLACED_LINK_FILE_MODE = 0o644;
+/**
+ * Write `content` at `file` through a temp file beside it and one rename. A rename puts the new file
+ * in the place of whatever stands at `file`, so a link there is replaced and never followed; the link
+ * is recorded in `links.replacedLinks` once the write is done. A file that replaces a link has the
+ * fixed mode 0644, never the mode of what the link pointed to, which the atomic writer would copy
+ * because its `stat` follows the link. Any other file goes through the atomic writer and keeps its
+ * own mode. The caller has proved that the folder holding `file` is a real one. Throws what the
+ * writer throws, so the caller keeps its own catch.
+ */
+export async function writeFileReplacingLink(file, content, links) {
+    if (!(await entryIsLink(file))) {
+        await writeFileAtomicExclusive(file, content);
+        return;
+    }
+    const temp = `${file}.tmp.${process.pid}`;
+    try {
+        // A stale temp file is removed first; the exclusive open then refuses anything placed there since.
+        await fs.rm(temp, { force: true });
+        await fs.writeFile(temp, content, { encoding: 'utf-8', flag: 'wx', mode: REPLACED_LINK_FILE_MODE });
+        await fs.chmod(temp, REPLACED_LINK_FILE_MODE);
+        await fs.rename(temp, file);
+    }
+    catch (err) {
+        await fs.rm(temp, { force: true }).catch(() => undefined);
+        throw err;
+    }
+    links?.replacedLinks.push(file);
+}
+//# sourceMappingURL=linked-folder.js.map

package/dist/targets/claude-code/reference-converge.js

@@ -0,0 +1,118 @@
+/**
+ * The references kind of the variant converge: make the installed `devflow:git` references
+ * match the machine's compliance switch (AC-41, AC-50).
+ *
+ * `devflow init`, `devflow compliance` and `devflow curation` reach it through
+ * convergeVariantAxes, so a compliance toggle needs no reinstall. It does, in order:
+ *
+ *   1. the overlay, with the manifest and the ONE source root of the switch
+ *      (`installedReferenceManifest({ compliance })`, `skillRefsSourceDir`): it rewrites the
+ *      references whose text differs between the two states and prunes the omitted
+ *      operation files from `pr/` and `tracker/`. With compliance off the source root is the
+ *      compliance-off tree, and an absent root is a failure that writes nothing: the converge
+ *      never falls through to the compliance-on references;
+ *   2. with compliance off, the removal list ({@link removeComplianceOffFiles});
+ *      with compliance on, the restore of the files the skill copy puts in place
+ *      ({@link restoreComplianceOffFiles}), from the source the install would copy.
+ *
+ * It acts on a skill that is ALREADY installed. A machine whose plugin selection holds no
+ * `devflow:git` has nothing to converge, and that is a clean result. A skill directory, or a
+ * `references` directory inside it, that is a link or not a directory is a failure: the overlay
+ * would stage, prune and set modes through it. A full install empties the skill directory first and
+ * so replaces such a link; this converge and a partial install have no such step, so each refuses
+ * instead, on the same proof ({@link referencesHostState}).
+ *
+ * Never throws. Every failure is a warning and a `failures` entry, and the next step still
+ * runs. With compliance off a caller reads `failures` and `stillPosting` and fails closed.
+ */
+import * as path from 'path';
+import { skillRefsSourceDir } from '../../core/assets.js';
+import { installedReferenceManifest, SKILL_REFS_SKILL_NAME } from '../../core/mds-variants.js';
+import { getPackageRoot } from '../../core/paths.js';
+import { prefixSkillName } from '../../core/plugins.js';
+import { removeComplianceOffFiles, restoreComplianceOffFiles } from './compliance-off-files.js';
+import { overlayGeneratedReferences, overlayUnitLabel, referencesHostState, resolveSkillSource } from './installer.js';
+export async function convergeReferences(opts) {
+    const { claudeDir, devflowDir, compliance, warn } = opts;
+    const failures = [];
+    const fail = (message) => {
+        warn(`reference converge: ${message}`);
+        failures.push(message);
+    };
+    // Precondition, asserted in production code: a relative claudeDir would resolve every
+    // install target somewhere unexpected, the removals included.
+    if (!path.isAbsolute(claudeDir)) {
+        fail(`claudeDir is not an absolute path ("${claudeDir}") — skipping convergence`);
+        return { converged: false, rewritten: [], removed: [], restored: [], failures, stillPosting: [], unproven: !compliance };
+    }
+    const root = opts.packageRoot ?? getPackageRoot();
+    const skillsDir = path.join(claudeDir, 'skills');
+    const gitSkillDir = path.join(skillsDir, prefixSkillName(SKILL_REFS_SKILL_NAME));
+    const manifest = installedReferenceManifest({ compliance });
+    let rewritten = [];
+    let unproven = false;
+    const host = await referencesHostState(gitSkillDir);
+    if (host.kind === 'refused') {
+        fail(`${host.path} is not a real directory, so the references in it were not converged`);
+        unproven = true;
+    }
+    else if (host.kind === 'ready') {
+        try {
+            const overlay = await overlayGeneratedReferences({
+                referencesTarget: path.join(gitSkillDir, 'references'),
+                sourceRoot: skillRefsSourceDir(compliance, root),
+                manifest,
+                warn,
+            });
+            rewritten = overlay.overlaidRefs;
+            for (const failure of overlay.overlayFailures) {
+                fail(`${overlayUnitLabel(failure.unit)} was not refreshed (${failure.error})`);
+                unproven = true;
+            }
+            for (const failed of overlay.pruned.failed) {
+                fail(`could not prune ${failed.name} (${String(failed.error)})`);
+                unproven = true;
+            }
+        }
+        catch (err) {
+            // The overlay throws for a packaging failure only: an absent source root, or a manifest entry
+            // the root lacks. Nothing is written in either case, and nothing falls through to another root.
+            fail(err instanceof Error ? err.message : String(err));
+            unproven = true;
+        }
+    }
+    const removed = [];
+    const restored = [];
+    const stillPosting = [];
+    if (!compliance) {
+        const removal = await removeComplianceOffFiles(skillsDir);
+        removed.push(...removal.removed);
+        for (const refusal of removal.refused) {
+            fail(`${refusal.entry} was not removed — ${refusal.reason}`);
+            stillPosting.push(path.join(skillsDir, ...refusal.entry.split('/')));
+        }
+    }
+    else {
+        // The overlay owns every generated reference (publication-gate.md among them), so the restore
+        // writes back only the files that come from the skill source.
+        const ownedByOverlay = new Set(manifest.map(rel => `${prefixSkillName(SKILL_REFS_SKILL_NAME)}/references/${rel}`));
+        const restoration = await restoreComplianceOffFiles({
+            skillsDir,
+            sourceDirOf: async (skill) => (await resolveSkillSource(skill, devflowDir, opts.packageRoot)).dir,
+            ownedElsewhere: ownedByOverlay,
+        });
+        restored.push(...restoration.restored);
+        for (const refusal of restoration.refused)
+            fail(`${refusal.entry} was not restored — ${refusal.reason}`);
+    }
+    return {
+        converged: failures.length === 0,
+        rewritten,
+        removed,
+        restored,
+        failures,
+        stillPosting: compliance ? [] : stillPosting,
+        unproven: compliance ? false : unproven,
+    };
+}
+//# sourceMappingURL=reference-converge.js.map

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

@@ -15,6 +15,7 @@ import { stampAgentTools } from '../../core/agent-frontmatter.js';
 import { agentSourceDirs } from '../../core/assets.js';
 import { mdFileName } from '../../core/orphan-sweep.js';
 import { TRACKER_MCP_SERVERS_DEFAULT, trackerServerTools } from '../../core/tracker.js';
+import { newLinkReport, refuseUnrealFolder, warnLinkReport, writeFileReplacingLink } from './linked-folder.js';
 /**
  * The agent this module owns.
  *
@@ -97,55 +98,67 @@ async function writeWouldChangeNothing(wanted, target) {
  * nothing reports `unchanged` and the summary stays quiet
  * (see {@link writeWouldChangeNothing}).
  *
+ * An `agents/devflow` that is a link, or not a folder, is refused: nothing is written there, and the
+ * folder is named in `refusedFolders` and in a warning. A `tracker.md` that is a link is replaced by a
+ * real file, and named in `replacedLinks` and in a warning.
+ *
  * Never throws. A caller reads `converged`; it does not catch. The one refusal
  * that is not an I/O degradation — a claudeDir that is not absolute — is reported
  * the same way rather than thrown, because an install must not die on it.
  */
 export async function convergeTrackerArtifacts(opts) {
     const { claudeDir, warn } = opts;
+    const links = newLinkReport();
+    const finish = (converged, agent) => {
+        warnLinkReport(links, warn);
+        return { converged, agent, replacedLinks: links.replacedLinks, refusedFolders: links.refusedFolders };
+    };
     // Precondition, asserted in production code rather than only in tests: an
     // empty or relative claudeDir would make the target resolve somewhere
     // unexpected.
     if (!path.isAbsolute(claudeDir)) {
         warn(`tracker: claudeDir is not an absolute path ("${claudeDir}") — skipping convergence`);
-        return { converged: false, agent: 'unchanged' };
+        return finish(false, 'unchanged');
     }
     const target = agentTarget(claudeDir);
+    // A link at the folder sends the write into another place, so the folder is proven first.
+    if (await refuseUnrealFolder(links, path.dirname(target)))
+        return finish(false, 'unchanged');
     const dirs = opts.agentSourceDirs ?? agentSourceDirs();
     const candidates = dirs.map(dir => path.join(dir, mdFileName(TRACKER_AGENT_NAME)));
     const source = await firstExisting(candidates);
     if (source === undefined) {
         warn(`tracker: agent source not found for "${TRACKER_AGENT_NAME}" (searched: ${candidates.join(', ')}) — ` +
             `run \`npm run build:mds\` if it is compiled from an .mds generator host`);
-        return { converged: false, agent: 'unchanged' };
+        return finish(false, 'unchanged');
     }
     let wanted;
     try {
         const stamped = stampAgentTools(await fs.readFile(source, 'utf-8'), trackerServerTools(opts.servers ?? TRACKER_MCP_SERVERS_DEFAULT));
         if (!stamped.ok) {
             warn(`tracker: the Tracker agent source could not take the tracker servers (${stamped.error}) — not installed`);
-            return { converged: false, agent: 'unchanged' };
+            return finish(false, 'unchanged');
         }
         wanted = stamped.value.content;
     }
     catch (err) {
         warn(`tracker: cannot read the Tracker agent source (${source}) — ${String(err)}`);
-        return { converged: false, agent: 'unchanged' };
+        return finish(false, 'unchanged');
     }
     // Already converged — nothing to write, and nothing for the summary to announce.
     // The directory is not created either: an identical file at the target means it is
     // already there (see {@link writeWouldChangeNothing}).
     if (await writeWouldChangeNothing(wanted, target)) {
-        return { converged: true, agent: 'unchanged' };
+        return finish(true, 'unchanged');
     }
     try {
         await fs.mkdir(path.dirname(target), { recursive: true });
-        await fs.writeFile(target, wanted);
+        await writeFileReplacingLink(target, wanted, links);
     }
     catch (err) {
         warn(`tracker: failed to install the Tracker agent (${target}) — ${String(err)}`);
-        return { converged: false, agent: 'unchanged' };
+        return finish(false, 'unchanged');
     }
-    return { converged: true, agent: 'installed' };
+    return finish(true, 'installed');
 }
 //# sourceMappingURL=tracker-install.js.map

package/dist/targets/claude-code/tracker-servers.js

@@ -17,7 +17,7 @@
  *          a `--plugin` run that does not install Git leaves the installed, stamped copy alone.
  *       2. `convergeTrackerArtifacts` stamps Tracker as it writes it, and compares the STAMPED text
  *          with the installed file, so a steady-state run reports `unchanged`.
- *       3. `convergeCurationVariants` (init, `devflow curation --enable/--disable`) carries the
+ *       3. `convergeVariantAxes` (init, `devflow curation` and `devflow compliance`) carries the
  *          installed stamp onto the variant it writes (`carryStampedTools`), the way it carries
  *          `model:` and `effort:`, so a variant switch keeps the list and a repeat run is byte-equal.
  *       4. `devflow tracker --servers` re-stamps the installed copies at once ({@link restampTrackerAgents}).
@@ -34,9 +34,9 @@
 import { promises as fs } from 'fs';
 import * as path from 'path';
 import { stampAgentTools } from '../../core/agent-frontmatter.js';
-import { writeFileAtomicExclusive } from '../../core/fs-atomic.js';
 import { mdFileName } from '../../core/orphan-sweep.js';
 import { trackerServerTools } from '../../core/tracker.js';
+import { newLinkReport, refuseUnrealFolder, warnLinkReport, writeFileReplacingLink } from './linked-folder.js';
 import { TRACKER_AGENT_NAME } from './tracker-install.js';
 /** The registry name of the Git agent. */
 export const GIT_AGENT_NAME = 'git';
@@ -51,7 +51,10 @@ export function isTrackerStampedAgent(agentName) {
  *
  * Rewrites only an installed copy (an absent one stays absent), compares against the bytes on
  * disk at the moment of writing, and writes atomically only when they differ, so a run that
- * changes nothing writes nothing. Never throws.
+ * changes nothing writes nothing. An `agents/devflow` that is a link, or not a folder, is refused:
+ * nothing is written there, both agents are `failed`, and the folder is named in `refusedFolders` and
+ * in a warning. An agent file that is a link is replaced by a real file, and named in `replacedLinks`
+ * and in a warning. Never throws.
  */
 export async function restampTrackerAgents(opts) {
     const { claudeDir, servers, warn } = opts;
@@ -59,11 +62,22 @@ export async function restampTrackerAgents(opts) {
     const unchanged = [];
     const absent = [];
     const failed = [];
+    const links = newLinkReport();
+    const finish = () => {
+        warnLinkReport(links, warn);
+        return { rewritten, unchanged, absent, failed, replacedLinks: links.replacedLinks, refusedFolders: links.refusedFolders };
+    };
     // Precondition, asserted in production code: a relative claudeDir would resolve the targets
     // against the working directory.
     if (!path.isAbsolute(claudeDir)) {
         warn(`tracker servers: claudeDir is not an absolute path ("${claudeDir}") — the installed agents were not stamped`);
-        return { rewritten, unchanged, absent, failed: [...TRACKER_STAMPED_AGENTS] };
+        failed.push(...TRACKER_STAMPED_AGENTS);
+        return finish();
+    }
+    // A link at the folder sends every write below it into another place, so the folder is proven first.
+    if (await refuseUnrealFolder(links, path.join(claudeDir, 'agents', 'devflow'))) {
+        failed.push(...TRACKER_STAMPED_AGENTS);
+        return finish();
     }
     const tools = trackerServerTools(servers);
     for (const agent of TRACKER_STAMPED_AGENTS) {
@@ -94,7 +108,7 @@ export async function restampTrackerAgents(opts) {
             continue;
         }
         try {
-            await writeFileAtomicExclusive(target, stamped.value.content);
+            await writeFileReplacingLink(target, stamped.value.content, links);
             rewritten.push(agent);
         }
         catch (err) {
@@ -102,6 +116,6 @@ export async function restampTrackerAgents(opts) {
             failed.push(agent);
         }
     }
-    return { rewritten, unchanged, absent, failed };
+    return finish();
 }
 //# sourceMappingURL=tracker-servers.js.map