devflow-kit 3.3.0 → 3.4.0

package/dist/targets/claude-code/installer.js

@@ -1,13 +1,14 @@
 import { promises as fs } from 'fs';
 import { existsSync } from 'fs';
 import * as path from 'path';
-import { SKILL_NAMESPACE, prefixSkillName, unprefixSkillName, getAllSkillNames, getAllAgentNames, getAllCommandNames, FEATURE_OWNED_SKILLS, resolveSkillInstallPlan } from '../../core/plugins.js';
-import { skillsDir, agentSourceDirs, rulesDir, commandsDir, scriptsDir, compiledSkillRefsDir } from '../../core/assets.js';
+import { SKILL_NAMESPACE, prefixSkillName, unprefixSkillName, getAllSkillNames, getAllAgentNames, getAllCommandNames, FEATURE_OWNED_SKILLS, resolveSkillInstallPlan, omitLearningGatedSkills } from '../../core/plugins.js';
+import { skillsDir, agentSourceDirs, rulesDir, commandSourceDirs, scriptsDir, compiledSkillRefsDir } from '../../core/assets.js';
 import { getPackageRoot, isContainedIn } from '../../core/paths.js';
 import { sweepOrphanedAssets, mdFileName, mdEntryName } from '../../core/orphan-sweep.js';
 import { generatedReferenceManifest, installedReferenceManifest, PR_HOST_DESTINATION_ROOT, SKILL_REFS_SKILL_NAME, TRACKER_DESTINATION_ROOT } from '../../core/mds-variants.js';
 import { sweepOrphanedReferences, MAX_REFERENCE_SWEEP_DEPTH } from '../../core/reference-sweep.js';
 import { TRACKER_AGENT_NAME } from './tracker-install.js';
+import { restampInstalledCommands } from './language-stamp.js';
 // ---------------------------------------------------------------------------
 // Shadow validation helpers (exported — reused by Step 4 list commands)
 // ---------------------------------------------------------------------------
@@ -1278,6 +1279,39 @@ async function firstExisting(candidates) {
     }
     return undefined;
 }
+/**
+ * Resolve the directory a registry skill installs from: its valid shadow, else
+ * the shipped source (an invalid shadow is reported and the source is
+ * installed in its place).
+ *
+ * The ONE spelling of that decision: the install loop and
+ * convergeLearningVariants both call it, so a skill the learning toggle installs
+ * later is shadowed exactly as one the install installed.
+ *
+ * The shipped source is stat-checked FIRST, even under a valid shadow, so an
+ * absent source is a packaging failure that throws (the hard-error policy for a
+ * declared source) rather than being masked by a shadow. Callers that must not
+ * throw catch it.
+ *
+ * @param packageRoot - Package root the shipped source is read from. Injectable so
+ *   a caller working on a temp tree resolves the skill from the same root as its
+ *   other sources; omitted, it is the running package.
+ */
+export async function resolveSkillSource(skillName, devflowDir, packageRoot) {
+    const skillSource = path.join(skillsDir(packageRoot), skillName);
+    let isDir = false;
+    try {
+        isDir = (await fs.stat(skillSource)).isDirectory();
+    }
+    catch { /* stat failed — source absent */ }
+    if (!isDir) {
+        throw new Error(`Skill source not found for declared skill "${skillName}": ${skillSource}. ` +
+            `Ensure the skill directory exists in src/assets/skills/.`);
+    }
+    const shadowDir = path.join(devflowDir, 'skills', skillName);
+    const shadow = await validateSkillShadow(shadowDir);
+    return { dir: shadow === 'valid' ? shadowDir : skillSource, shadow };
+}
 /**
  * Registry skills that have a shadow directory under `~/.devflow/skills/`.
  *
@@ -1347,7 +1381,7 @@ async function removeDeselectedSkills(skillsDir, names) {
  * Returns an InstallReport describing which shadows were applied and which were skipped.
  */
 export async function installViaFileCopy(options) {
-    const { plugins, claudeDir, devflowDir, skillsMap, agentsMap, rulesMap = new Map(), isPartialInstall, spinner, warn = () => { }, } = options;
+    const { plugins, claudeDir, devflowDir, skillsMap, agentsMap, rulesMap = new Map(), isPartialInstall, spinner, learning, warn = () => { }, } = options;
     const report = {
         shadowedSkills: [],
         shadowedRules: [],
@@ -1484,11 +1518,13 @@ export async function installViaFileCopy(options) {
         warn(`Could not remove deselected skill "${prefixSkillName(failure.name)}" — ${String(failure.error)}`);
     }
     // Install commands from selected plugins using registry-driven lookup.
-    // Source: dist/commands/{name}.md (single lookup directory for all commands).
+    // Source: dist/commands/{name}.md, or — with learning off — the learning-off
+    // variant dist/learning-off/commands/{name}.md when the host has one
+    // (D-LEARNING-VARIANT-INSTALL; commandSourceDirs owns the order).
     // A declared command with no compiled source file is a hard error, not a skip.
     spinner.message('Installing commands and agents...');
     const commandsTarget = path.join(claudeDir, 'commands', 'devflow');
-    const cDir = commandsDir();
+    const commandDirs = commandSourceDirs(learning);
     const commandsSourceNames = new Set();
     for (const plugin of plugins) {
         for (const cmd of plugin.commands) {
@@ -1499,12 +1535,11 @@ export async function installViaFileCopy(options) {
     if (commandsSourceNames.size > 0) {
         await fs.mkdir(commandsTarget, { recursive: true });
         for (const name of commandsSourceNames) {
-            const srcFile = path.join(cDir, mdFileName(name));
-            try {
-                await fs.access(srcFile);
-            }
-            catch {
-                throw new Error(`Command source not found for declared command "${name}": ${srcFile}. ` +
+            const srcFile = await firstExisting(commandDirs.map(dir => path.join(dir, mdFileName(name))));
+            if (srcFile === undefined) {
+                // The error names the learning-ON path: that file exists for every declared
+                // command, while a learning-off file exists only for a host with an arm.
+                throw new Error(`Command source not found for declared command "${name}": ${path.join(commandSourceDirs(true)[0], mdFileName(name))}. ` +
                     `Ensure build:mds ran successfully before install.`);
             }
             await fs.copyFile(srcFile, path.join(commandsTarget, mdFileName(name)));
@@ -1514,6 +1549,18 @@ export async function installViaFileCopy(options) {
     // knownNames spans ALL plugins (getAllCommandNames) so commands from uninstalled
     // plugins survive a partial run. Only names absent from the full registry are removed.
     recordSweep(report, 'command', await sweepOrphanedAssets(commandsTarget, new Set(getAllCommandNames()), mdEntryName));
+    // D-LANGUAGE-FOCUS-STAMP: record the language focuses the EFFECTIVE selection installs on the
+    // installed /code-review, on every install shape. This is the language gate the command reads
+    // (no run-time probe of Claude Code's directory), so it runs after the copy and the sweep and
+    // whether or not code-review's own plugin is in this run: `--plugin=devflow-typescript` copies no
+    // command, yet must update a code-review an earlier run installed. The copy above wrote the shipped
+    // `(none)` line; the rewrite compares against what is on disk now, so neither that copy nor the
+    // pre-clean can defeat it. A failure is a warning, never an abort.
+    await restampInstalledCommands({
+        claudeDir,
+        effectivePlugins: options.effectivePlugins ?? plugins,
+        warn,
+    });
     // Install agents (deduplicated), resolved dist-first with a src fallback:
     // dist/agents/{name}.md (compiled from an .mds generator host) wins over
     // src/assets/agents/{name}.md. A declared agent absent from BOTH is a
@@ -1532,7 +1579,8 @@ export async function installViaFileCopy(options) {
     // registry via getAllAgentNames() — still treats a converged tracker.md as known
     // and leaves it alone.
     const agentsTarget = path.join(claudeDir, 'agents', 'devflow');
-    const agentDirs = options.agentSourceDirs ?? agentSourceDirs();
+    // Learning-aware (D-LEARNING-VARIANT-INSTALL). An injected list wins as given.
+    const agentDirs = options.agentSourceDirs ?? agentSourceDirs(undefined, learning);
     const allAgentNames = new Set();
     for (const plugin of plugins) {
         for (const agent of plugin.agents) {
@@ -1549,7 +1597,7 @@ export async function installViaFileCopy(options) {
             const candidates = agentDirs.map(dir => path.join(dir, mdFileName(agentName)));
             const srcFile = await firstExisting(candidates);
             if (srcFile === undefined) {
-                throw new Error(`Agent source not found for declared agent "${agentName}": ${candidates[0]}. ` +
+                throw new Error(`Agent source not found for declared agent "${agentName}": ${path.join(options.agentSourceDirs?.[0] ?? agentSourceDirs()[0], mdFileName(agentName))}. ` +
                     `Run \`npm run build:mds\` if it is compiled from an .mds generator host, otherwise ` +
                     `ensure the agent file exists in src/assets/agents/ (searched: ${candidates.join(', ')}).`);
             }
@@ -1564,33 +1612,21 @@ export async function installViaFileCopy(options) {
     // Resolved from flat src/assets/skills/{name}/ (no per-plugin subdirectory).
     // A declared skill whose source directory is absent is a build/packaging failure
     // and throws rather than silently skipping (matches command pattern).
+    //
+    // D-LEARNING-VARIANT-INSTALL: a learning-off machine skips the learning-gated
+    // skills here. The pre-clean above walked the UNFILTERED map, so on a full
+    // install a leftover copy is already gone; a partial install leaves removal to
+    // convergeLearningVariants, which init runs straight after this call.
     spinner.message('Installing skills...');
-    for (const [skillName] of skillsMap) {
-        const skillSource = path.join(skillsDir(), skillName);
-        let isDir = false;
-        try {
-            const stat = await fs.stat(skillSource);
-            isDir = stat.isDirectory();
-        }
-        catch { /* stat failed — source absent */ }
-        if (!isDir) {
-            throw new Error(`Skill source not found for declared skill "${skillName}": ${skillSource}. ` +
-                `Ensure the skill directory exists in src/assets/skills/.`);
-        }
-        const shadowDir = path.join(devflowDir, 'skills', skillName);
-        const prefixedName = prefixSkillName(skillName);
-        const skillTarget = path.join(claudeDir, 'skills', prefixedName);
-        const shadowState = await validateSkillShadow(shadowDir);
-        if (shadowState === 'valid') {
-            await copyDirectory(shadowDir, skillTarget);
+    for (const [skillName] of omitLearningGatedSkills(skillsMap, learning)) {
+        const resolved = await resolveSkillSource(skillName, devflowDir);
+        const skillTarget = path.join(claudeDir, 'skills', prefixSkillName(skillName));
+        await copyDirectory(resolved.dir, skillTarget);
+        if (resolved.shadow === 'valid') {
             report.shadowedSkills.push(skillName);
         }
-        else if (shadowState === 'missing-skill-md') {
+        else if (resolved.shadow === 'missing-skill-md') {
             report.skippedShadows.push({ kind: 'skill', name: skillName, reason: 'missing-skill-md' });
-            await copyDirectory(skillSource, skillTarget);
-        }
-        else {
-            await copyDirectory(skillSource, skillTarget);
         }
         // Converge the generated references onto the skill that was just installed. One call
         // site downstream of all three branches above, so a shadowed devflow:git receives the

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

@@ -0,0 +1,185 @@
+/**
+ * Language-focus stamp for the installed /code-review command.
+ *
+ * D-LANGUAGE-FOCUS-STAMP: /code-review spawns a language focus only when its file-type trigger fires AND
+ * the focus appears on one fixed-prefix line of the installed command. That line replaces the run-time
+ * `test -f` probe of Claude Code's directory; the installer writes it from the registry and the effective
+ * selection ({@link installedLanguageFocuses}), so the prompt reads a fact instead of discovering one.
+ * Decided here:
+ *
+ *   - The carrier is one line, `Installed language focuses: <list>`, shipped as `(none)` in
+ *     src/assets/commands/code-review.mds and found again by an anchored match, so a later run can
+ *     re-stamp a copy an earlier run stamped. It carries no MDS interpolation braces, and it sits outside
+ *     every learning arm, so both variants carry it. A separate stamped file would add a file to the
+ *     install walk and the install goldens, which an in-place rewrite leaves unchanged.
+ *   - Only code-review.md carries it. /dynamic-build spawns every review focus and drops none (plan
+ *     decision 1), so it has no stamp, no reduced classes and no DIFF_FILE.
+ *   - The stamp describes what is on disk, so it is computed from the EFFECTIVE selection
+ *     (`FileCopyOptions.effectivePlugins`), never from the plugins one run copies, and it is applied after
+ *     the command copy and the orphan sweep, whether or not code-review's own plugin is in the run. The
+ *     rewrite compares the bytes it is about to write with the bytes now on disk, at the moment it writes,
+ *     so no earlier same-run copy or pre-clean can defeat it.
+ *   - `devflow uninstall --plugin` removes a language plugin's skill but no command, so its name would
+ *     stay in the stamped copy; the selective phase re-stamps from the plugins that remain, through
+ *     {@link restampInstalledCommands} like the install.
+ *   - Composition with the learning converge (D-LEARNING-VARIANT-INSTALL), pinned: the converge rewrites
+ *     installed command files from dist or dist/learning-off, and those files carry the shipped `(none)`
+ *     line. It therefore applies {@link carryLanguageStamp} inside its own write path, putting the stamp
+ *     it finds on the installed copy into the variant it writes ({@link stampForConverge}); a copy with no
+ *     list to carry, one installed before the stamp existed, is stamped from the converge's selection
+ *     instead of being given the shipped `(none)`. The alternative, re-stamping after every
+ *     converge write, would make a steady-state run see a stamped copy that differs from its source, rewrite
+ *     it and re-stamp it on every `devflow init`; carrying keeps the converge's byte comparison honest, so a
+ *     run that changes nothing writes nothing, and it leaves one authority for the list: install and
+ *     uninstall change it, a variant switch never does.
+ *   - No prompt rule for a damaged stamp exists: no legitimate configuration produces one. A copy with
+ *     no stamp line, or several, is reported here as a warning and left as it is.
+ *   - Nothing here decides a diff's class or which focuses a diff gets. Those are prompt rules the
+ *     orchestrator executes; this module only turns the registry and a selection into a list.
+ *
+ * Never throws: every failure is a warning, because the install must not die on a stamp.
+ */
+import { promises as fs } from 'fs';
+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';
+/** 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. */
+export const LANGUAGE_STAMP_NONE = '(none)';
+/** Installed commands that carry the stamp line. Only /code-review (plan decision 1). */
+export const LANGUAGE_STAMPED_COMMANDS = ['code-review'];
+/** The most focuses one stamp lists; the registry has eight, so the bound is generous. */
+const MAX_STAMPED_FOCUSES = 16;
+/** One focus name is a plain lowercase skill name. */
+const FOCUS_NAME_RE = /^[a-z][a-z0-9-]{0,31}$/;
+/** A well-formed list as rendered: `(none)`, or comma-space separated plain names. */
+const STAMP_VALUE_RE = /^(?:\(none\)|[a-z][a-z0-9-]{0,31}(?:, [a-z][a-z0-9-]{0,31}){0,15})$/;
+/** The stamp line, anchored to a whole line. Rebuilt per use: a global regex carries state. */
+const stampLineRe = () => /^Installed language focuses: [^\r\n]*$/gm;
+/** The full stamp line for a list. */
+export function renderLanguageStamp(focuses) {
+    return `${LANGUAGE_STAMP_PREFIX}${focuses.length === 0 ? LANGUAGE_STAMP_NONE : focuses.join(', ')}`;
+}
+/**
+ * `content` with its one stamp line replaced by the rendering of `focuses`.
+ *
+ * Pure. Refuses a list holding anything but plain skill names, so no prompt text can ride in on it, and
+ * refuses a file with no stamp line or several rather than guessing which one is the carrier.
+ */
+export function applyLanguageStamp(content, focuses) {
+    if (focuses.length > MAX_STAMPED_FOCUSES || !focuses.every(name => FOCUS_NAME_RE.test(name))) {
+        return { ok: false, reason: 'bad-focus-name' };
+    }
+    const lines = [...content.matchAll(stampLineRe())];
+    if (lines.length === 0)
+        return { ok: false, reason: 'no-stamp-line' };
+    if (lines.length > 1)
+        return { ok: false, reason: 'several-stamp-lines' };
+    const at = lines[0].index ?? 0;
+    return { ok: true, content: content.slice(0, at) + renderLanguageStamp(focuses) + content.slice(at + lines[0][0].length) };
+}
+/**
+ * `source` with its stamp line replaced by the one on `installed`.
+ *
+ * The learning converge's write path (see the header): the variant it installs keeps the list the
+ * install stamped. Returns `source` unchanged unless both sides hold exactly one stamp line and the
+ * installed one is a well-formed list, so a damaged or hostile line is never copied into a fresh file.
+ */
+export function carryLanguageStamp(source, installed) {
+    const carried = carriableStampLine(installed);
+    const into = [...source.matchAll(stampLineRe())];
+    if (carried === null || into.length !== 1)
+        return source;
+    const at = into[0].index ?? 0;
+    return source.slice(0, at) + carried + source.slice(at + into[0][0].length);
+}
+/** The installed copy's one stamp line when it holds exactly one and its list is well formed, else null. */
+function carriableStampLine(installed) {
+    const from = [...installed.matchAll(stampLineRe())];
+    if (from.length !== 1)
+        return null;
+    return STAMP_VALUE_RE.test(from[0][0].slice(LANGUAGE_STAMP_PREFIX.length)) ? from[0][0] : null;
+}
+/**
+ * The text the learning converge installs for a stamped command: `source` carrying the installed copy's
+ * list ({@link carryLanguageStamp}) when the copy holds one, else `source` stamped with `focuses`, the
+ * effective selection's list, exactly as the install stamps it.
+ *
+ * A copy with no list to carry was installed by a version before the stamp existed, or is damaged. A
+ * `--plugin` init right after an upgrade reaches such a copy through the converge alone (the run copies
+ * no command), so installing the shipped `(none)` over it would drop every language focus until the next
+ * full install. A list that IS carried is never changed here. Pure.
+ */
+export function stampForConverge(source, installed, focuses) {
+    if (carriableStampLine(installed) !== null)
+        return carryLanguageStamp(source, installed);
+    const stamped = applyLanguageStamp(source, focuses);
+    return stamped.ok ? stamped.content : source;
+}
+/**
+ * Stamp every installed copy that carries the stamp with the list for `effectivePlugins`.
+ *
+ * Called by installViaFileCopy after the command copy and the orphan sweep (every install shape) and by
+ * the selective uninstall phase after the removals. A command that is not installed is left absent, so a
+ * `--plugin` run never gains a command it did not install.
+ */
+export async function restampInstalledCommands(opts) {
+    const { claudeDir, effectivePlugins, warn, mayChange } = opts;
+    const focuses = installedLanguageFocuses(effectivePlugins);
+    const rewritten = [];
+    const unchanged = [];
+    const absent = [];
+    const failed = [];
+    // Precondition, asserted in production code: a relative claudeDir would resolve the targets
+    // against the working directory.
+    if (!path.isAbsolute(claudeDir)) {
+        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] };
+    }
+    for (const command of LANGUAGE_STAMPED_COMMANDS) {
+        const target = path.join(claudeDir, 'commands', 'devflow', mdFileName(command));
+        let current;
+        try {
+            current = await fs.readFile(target, 'utf-8');
+        }
+        catch (err) {
+            if (err.code === 'ENOENT') {
+                absent.push(command);
+            }
+            else {
+                warn(`language stamp: cannot read ${mdFileName(command)} (${target}) — ${String(err)}`);
+                failed.push(command);
+            }
+            continue;
+        }
+        const stamped = applyLanguageStamp(current, focuses);
+        if (!stamped.ok) {
+            warn(stamped.reason === 'no-stamp-line'
+                ? `language stamp: ${mdFileName(command)} has no stamp line, so the installed language focuses were not recorded. Run \`devflow init\` to reinstall it.`
+                : `language stamp: ${mdFileName(command)} has ${stamped.reason === 'several-stamp-lines' ? 'several stamp lines' : 'an unusable language list'}, so it was left as it is. Run \`devflow init\` to reinstall it.`);
+            failed.push(command);
+            continue;
+        }
+        // Compared at the moment of writing, against what is on disk now.
+        if (stamped.content === current) {
+            unchanged.push(command);
+            continue;
+        }
+        try {
+            if (mayChange !== undefined && !(await mayChange(target))) {
+                failed.push(command);
+                continue;
+            }
+            await writeFileAtomicExclusive(target, stamped.content);
+            rewritten.push(command);
+        }
+        catch (err) {
+            warn(`language stamp: could not rewrite ${mdFileName(command)} (${target}) — ${String(err)}`);
+            failed.push(command);
+        }
+    }
+    return { focuses, rewritten, unchanged, absent, failed };
+}
+//# sourceMappingURL=language-stamp.js.map