devflow-kit 1.8.3 → 2.0.1

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

@@ -0,0 +1,305 @@
+/**
+ * Compliance artifact installer for the Claude Code target.
+ *
+ * Convergence function: installs or removes the compliance skill directory
+ * and rule file based on the current feature state.
+ *
+ * Applies ADR-013: I/O orchestration in src/targets/; pure helpers in src/core/.
+ * Applies PF-009: warn-not-throw for per-item failures.
+ * Applies PF-011: temp-sibling+rename for skill dir rewrites.
+ * Applies PF-015: both artifacts converge unconditionally (no || short-circuits).
+ */
+import { promises as fs } from 'fs';
+import * as path from 'path';
+import { skillsDir, rulesDir } from '../../core/assets.js';
+import { ALWAYS_PRESENT_REFS, normalizeFrameworks } from '../../core/compliance.js';
+import { parseComplianceFragment, composeComplianceSkill, composeComplianceRule } from '../../core/compliance-compose.js';
+import { validateSkillShadow, validateRuleShadow } from './installer.js';
+// ── Path helpers ───────────────────────────────────────────────────────────
+/** Installed compliance skill dir: {claudeDir}/skills/devflow:compliance/ */
+function skillTarget(claudeDir) {
+    return path.join(claudeDir, 'skills', 'devflow:compliance');
+}
+/** Installed compliance rule file: {claudeDir}/rules/devflow/compliance.md */
+function ruleTarget(claudeDir) {
+    return path.join(claudeDir, 'rules', 'devflow', 'compliance.md');
+}
+/** Returns true if the path exists (file or directory), false if ENOENT. */
+async function pathExists(p) {
+    try {
+        await fs.access(p);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+// ── Fragment loader ────────────────────────────────────────────────────────
+/**
+ * Load and parse per-framework fragment files from the canonical source.
+ *
+ * Fragments always come from the canonical source (not user-overridable) — they carry
+ * registry-owned content (mapping cells, reference blurbs, checklist items, rule bullets).
+ *
+ * PF-009: parse errors and unreadable files are reported via warn; the framework is
+ * silently omitted from the result map (C5 in composeComplianceSkill handles the gap).
+ */
+async function loadComplianceFragments(canonicalSrc, frameworks, warn) {
+    const map = new Map();
+    // C7: loop bounded by frameworks array (already registry-validated by caller)
+    for (const fw of frameworks) {
+        const fragPath = path.join(canonicalSrc, 'frameworks', fw, 'fragment.md');
+        try {
+            const raw = await fs.readFile(fragPath, 'utf-8');
+            const result = parseComplianceFragment(fw, raw);
+            if (result.ok) {
+                map.set(fw, result.value);
+            }
+            else {
+                warn(`compliance: fragment "${fw}" parse error — ${result.error}`);
+            }
+        }
+        catch (err) {
+            warn(`compliance: fragment "${fw}" unreadable — ${String(err)}`);
+        }
+    }
+    return map;
+}
+// ── Skill installer ────────────────────────────────────────────────────────
+/**
+ * Install the compliance skill directory (selective references).
+ *
+ * SKILL.md source: shadow at {devflowDir}/skills/compliance/SKILL.md (when valid),
+ * otherwise canonical src/assets/skills/compliance/SKILL.md.
+ *
+ * Reference files installed: ALWAYS_PRESENT_REFS + one {id}.md per selected framework.
+ * References always come from the canonical source — framework refs are not user-overridable.
+ *
+ * `fragments` is loaded once by convergeComplianceArtifacts and shared with the rule
+ * installer — the SKILL.md and the rule compose from the same parsed set.
+ *
+ * Applies PF-011: build under a .tmp sibling, remove old target, rename.
+ * Applies PF-009: unexpected I/O failures are reported via warn; never thrown.
+ */
+async function installSkillDir(claudeDir, devflowDir, frameworks, fragments, warn) {
+    const canonicalSrc = path.join(skillsDir(), 'compliance');
+    const target = skillTarget(claudeDir);
+    const tmpTarget = `${target}.tmp`;
+    // Determine SKILL.md source: prefer a valid shadow, else use canonical.
+    const skillShadowDir = path.join(devflowDir, 'skills', 'compliance');
+    const shadowState = await validateSkillShadow(skillShadowDir);
+    const skillMdSrc = shadowState === 'valid'
+        ? path.join(skillShadowDir, 'SKILL.md')
+        : path.join(canonicalSrc, 'SKILL.md');
+    try {
+        // Clean up any orphaned tmp from a prior crashed run (best-effort).
+        await fs.rm(tmpTarget, { recursive: true, force: true });
+        // Build the new directory tree under the tmp sibling (PF-011).
+        const refDst = path.join(tmpTarget, 'references');
+        await fs.mkdir(refDst, { recursive: true });
+        // SKILL.md: compose from template (shadow or canonical) + fragments.
+        // C1: a shadow without tokens passes through byte-identical.
+        const templateContent = await fs.readFile(skillMdSrc, 'utf-8');
+        const { content: composedSkill, warnings: skillWarnings } = composeComplianceSkill(templateContent, frameworks, fragments);
+        for (const w of skillWarnings)
+            warn(`compliance: ${w}`);
+        await fs.writeFile(path.join(tmpTarget, 'SKILL.md'), composedSkill, 'utf-8');
+        // Always-present reference files (detection.md, sources.md) from the canonical
+        // references/ directory — these are not framework-specific.
+        //
+        // PF-009: each copy is isolated. A skill dir missing one reference still works;
+        // aborting the whole install because one file is unreadable would take out
+        // SKILL.md too. Failures warn and the remaining refs still install.
+        const alwaysPresentSrc = path.join(canonicalSrc, 'references');
+        for (const ref of ALWAYS_PRESENT_REFS) {
+            try {
+                await fs.copyFile(path.join(alwaysPresentSrc, ref), path.join(refDst, ref));
+            }
+            catch (err) {
+                warn(`compliance: reference "${ref}" not installed — ${String(err)}`);
+            }
+        }
+        // Per-framework reference files: source is frameworks/{id}/reference.md,
+        // destination is references/{id}.md (installed artifact layout unchanged — C1
+        // for consumers). Every id here is a registry-validated bare name — no separator,
+        // no traversal — from normalizeFrameworks in convergeComplianceArtifacts.
+        for (const fw of frameworks) {
+            const srcRef = path.join(canonicalSrc, 'frameworks', fw, 'reference.md');
+            const dstRef = path.join(refDst, `${fw}.md`);
+            try {
+                await fs.copyFile(srcRef, dstRef);
+            }
+            catch (err) {
+                warn(`compliance: reference "${fw}.md" not installed — ${String(err)}`);
+            }
+        }
+        // Atomically swap: remove old target, rename tmp into place.
+        await fs.rm(target, { recursive: true, force: true });
+        await fs.rename(tmpTarget, target);
+    }
+    catch (err) {
+        // Clean up tmp on failure (best-effort) so no orphan is left behind.
+        await fs.rm(tmpTarget, { recursive: true, force: true }).catch(() => undefined);
+        warn(`compliance: skill install failed — ${String(err)}`);
+    }
+}
+// ── Rule installer ─────────────────────────────────────────────────────────
+/**
+ * Install the compliance rule file, composed with per-framework bullets and stamped
+ * with the active frameworks.
+ *
+ * Rule source: shadow at {devflowDir}/rules/compliance.md (when valid),
+ * otherwise canonical src/assets/rules/compliance.md.
+ *
+ * composeComplianceRule() replaces ${DEVFLOW_COMPLIANCE_RULE_BULLETS} with per-framework
+ * rule bullets and delegates ${DEVFLOW_COMPLIANCE_FRAMEWORKS} to stampComplianceRule
+ * (AC-35, AC-36). C1: a shadow without tokens passes through byte-identical.
+ *
+ * `fragments` is loaded once by convergeComplianceArtifacts from the canonical skill
+ * source (never the shadow — fragments are registry-owned) and shared with the skill
+ * installer.
+ *
+ * Applies PF-009: I/O failures are reported via warn; never thrown.
+ */
+async function installRuleFile(claudeDir, devflowDir, frameworks, fragments, warn) {
+    const ruleShadowFile = path.join(devflowDir, 'rules', 'compliance.md');
+    const canonicalRuleSrc = path.join(rulesDir(), 'compliance.md');
+    const target = ruleTarget(claudeDir);
+    try {
+        const shadowState = await validateRuleShadow(ruleShadowFile);
+        const sourcePath = shadowState === 'valid' ? ruleShadowFile : canonicalRuleSrc;
+        const templateContent = await fs.readFile(sourcePath, 'utf-8');
+        const { content: composed, warnings } = composeComplianceRule(templateContent, frameworks, fragments);
+        for (const w of warnings)
+            warn(`compliance: ${w}`);
+        await fs.mkdir(path.dirname(target), { recursive: true });
+        await fs.writeFile(target, composed, 'utf-8');
+    }
+    catch (err) {
+        warn(`compliance: rule install failed — ${String(err)}`);
+    }
+}
+// ── Public API ─────────────────────────────────────────────────────────────
+/**
+ * Converge compliance artifacts in the Claude Code install target.
+ *
+ * Convergence matrix:
+ *   enabled + rulesEnabled  → install skill dir (selective refs) + stamped rule
+ *   enabled + !rulesEnabled → install skill dir only; remove stale rule
+ *   !enabled                → remove both artifacts (warn-not-throw per PF-009)
+ *
+ * PF-015: both artifact operations execute unconditionally — no || short-circuits.
+ * PF-011: skill dir write uses temp-sibling+rename to avoid ENOENT windows.
+ *
+ * D: the `warn` callback is injected (not console.warn) so callers control
+ * surfacing (init log lines, test spies, etc.) — per the dependency-injection
+ * principle in engineering.md.
+ */
+export async function convergeComplianceArtifacts(opts) {
+    const { claudeDir, devflowDir, enabled, frameworks, rulesEnabled, warn } = opts;
+    // S78: claudeDir precondition — reliability rule: assert invariants in production code.
+    // An empty or relative claudeDir would make skillTarget/ruleTarget resolve to unexpected
+    // locations. Warn and bail rather than running fs.rm with a potentially wrong path.
+    if (!path.isAbsolute(claudeDir)) {
+        warn(`compliance: claudeDir is not an absolute path ("${claudeDir}") — skipping convergence`);
+        return { removedPreexisting: false, converged: false };
+    }
+    // Trust boundary. `frameworks` reaches here straight from the manifest on every
+    // caller's bare --enable path, and normalizeComplianceFeature only type-checks it.
+    // Filtering to registry IDs here — before any path.join or stamp — is what makes
+    // AC-35/AC-36 true for ALL callers rather than only the ones that happened to run
+    // parseFrameworkList. Unknown IDs are dropped, never turned into a path segment.
+    const safeFrameworks = normalizeFrameworks(frameworks);
+    // I13: Track whether every artifact operation in this run completed without error.
+    // `converged` starts true and is set false by the tracking wrapper whenever any warn
+    // path is taken — including inside installSkillDir / installRuleFile (PF-009 paths).
+    let converged = true;
+    const trackingWarn = (msg) => {
+        converged = false;
+        warn(msg);
+    };
+    // ── Disable path ─────────────────────────────────────────────────────────
+    if (!enabled) {
+        // Detect pre-existing artifacts BEFORE removal (to set removedPreexisting).
+        const skillExisted = await pathExists(skillTarget(claudeDir));
+        const ruleExisted = await pathExists(ruleTarget(claudeDir));
+        // PF-015: collect results independently — one failure must not skip the other.
+        let skillErr = null;
+        let ruleErr = null;
+        // Step 1: attempt skill dir removal
+        try {
+            if (skillExisted) {
+                await fs.rm(skillTarget(claudeDir), { recursive: true, force: true });
+            }
+        }
+        catch (err) {
+            skillErr = String(err);
+        }
+        // Step 2: attempt rule removal (runs regardless of Step 1 outcome — PF-015)
+        try {
+            if (ruleExisted) {
+                await fs.rm(ruleTarget(claudeDir), { force: true });
+            }
+        }
+        catch (err) {
+            ruleErr = String(err);
+        }
+        // PF-009: warn after BOTH attempts so neither failure blocks the other.
+        if (skillErr !== null) {
+            trackingWarn(`compliance: failed to remove skill dir — ${skillErr}`);
+        }
+        if (ruleErr !== null) {
+            trackingWarn(`compliance: failed to remove rule — ${ruleErr}`);
+        }
+        return { removedPreexisting: skillExisted || ruleExisted, converged };
+    }
+    // ── Enable path ──────────────────────────────────────────────────────────
+    //
+    // PF-015: installSkillDir and the rule step are independent operations.
+    // An error in installSkillDir is caught internally and reported via trackingWarn,
+    // so execution always continues to the rule step.
+    // Fragments are read and parsed once per convergence and shared by both artifacts:
+    // they are the same registry-owned files either way, so parsing twice would only
+    // duplicate the I/O and report each malformed fragment twice.
+    const fragments = await loadComplianceFragments(path.join(skillsDir(), 'compliance'), safeFrameworks, trackingWarn);
+    await installSkillDir(claudeDir, devflowDir, safeFrameworks, fragments, trackingWarn);
+    if (rulesEnabled) {
+        await installRuleFile(claudeDir, devflowDir, safeFrameworks, fragments, trackingWarn);
+    }
+    else {
+        // Rules disabled: remove any stale rule left from a prior enabled run.
+        // Ignore ENOENT (force: true) — absence is the desired end state.
+        try {
+            await fs.rm(ruleTarget(claudeDir), { force: true });
+        }
+        catch { /* absent = already in desired end state */ }
+    }
+    return { removedPreexisting: false, converged };
+}
+// ── Manifest-slice wrapper ─────────────────────────────────────────────────
+/**
+ * Thin wrapper around convergeComplianceArtifacts that extracts options from a
+ * manifest slice in one place, eliminating the repeated hand-assembly at each
+ * call site (init.ts, rules.ts, compliance.ts).
+ *
+ * @param opts.manifest - Structural type carrying only the compliance and rules
+ *   feature fields. Callers that have computed their own compliance state
+ *   (e.g. init.ts resolving prompt results) construct a synthetic slice;
+ *   callers with a live ManifestData can pass it directly.
+ * @param opts.rulesEnabledOverride - When provided, replaces
+ *   manifest.features.rules as the rulesEnabled source. Used by rules.ts where
+ *   rulesEnabled reflects the actual install outcome (!installFailed) rather
+ *   than the value stored in the manifest.
+ */
+export async function convergeFromManifest(opts) {
+    const { claudeDir, devflowDir, manifest, warn, rulesEnabledOverride } = opts;
+    return convergeComplianceArtifacts({
+        claudeDir,
+        devflowDir,
+        enabled: manifest.features.compliance.enabled,
+        frameworks: manifest.features.compliance.frameworks,
+        rulesEnabled: rulesEnabledOverride ?? manifest.features.rules,
+        warn,
+    });
+}
+//# sourceMappingURL=compliance-install.js.map

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

@@ -0,0 +1,9 @@
+/**
+ * Shared hook types for Claude Code settings.json.
+ * Used by learn.ts, ambient.ts, and memory.ts.
+ *
+ * NOTE: hud.ts uses a structurally different Settings type (statusLine, not hooks)
+ * and is intentionally excluded from this shared module.
+ */
+export {};
+//# sourceMappingURL=hooks.js.map