devflow-kit 2.0.1 → 2.1.0

package/dist/cli/commands/flags.js

@@ -1,119 +1,538 @@
+/**
+ * devflow flags — Manage Claude Code feature flags.
+ *
+ * D-P3-1: Typed flags CLI rewrite (Phase 3).
+ *   - createFlagsCommand() factory — fresh Commander instance per call;
+ *     used by tests; src/cli.ts consumes the flagsCommand singleton export.
+ *   - Persist pipeline: convergeFlagsIntoSettings (fold-before-strip) — the
+ *     single pipeline entry point shared with init.ts (ARCH-H1, PF-015/017).
+ *   - PF-014 (process.exit swallows async work): all error paths set
+ *     process.exitCode = 1 and return; never call process.exit().
+ *   - PF-015 (multi-artifact fan-out): compute record first; settings write
+ *     and manifest write handled independently with their own error paths.
+ *   - PF-022 (applies-on-restart): bare non-TTY invocation prints status table
+ *     with a note that changes apply on restart.
+ *   - PF-023 (validate at the sink): parseFlagValueInput → coerceFlagValue
+ *     runs inside the core helpers before any write.
+ */
 import { Command } from 'commander';
 import { promises as fs } from 'fs';
 import * as path from 'path';
 import * as p from '@clack/prompts';
 import color from 'picocolors';
-import { getClaudeDirectory, getDevFlowDirectory } from '../../targets/claude-code/claude-paths.js';
-import { FLAG_REGISTRY, applyFlags, stripFlags, getDefaultFlags } from '../../core/flags.js';
+import { getClaudeDirectory, getDevFlowDirectory, } from '../../targets/claude-code/claude-paths.js';
+import { FLAG_REGISTRY, findFlag, convergeFlagsIntoSettings, parseFlagValueInput, formatFlagValue, effectiveDisplay, neutralValueOf, describeFlagKind, expectedInputFor, } from '../../core/flags.js';
 import { readManifest, writeManifest } from '../../core/manifest.js';
+import { writeFileAtomicExclusive } from '../../core/fs-atomic.js';
+import { sanitizeCell } from '../tui/cells.js';
+// Static imports for pure view-state helpers — no TTY machinery (applies PF-017).
+// runFlagsTui stays lazily imported in handleBare to keep TTY module out of
+// --list/--status code paths; buildFlagRows and collectFlagRecord are pure.
+import { buildFlagRows, collectFlagRecord } from '../flags-view/state.js';
+// ─── Internal helpers ─────────────────────────────────────────────────────────
 /**
- * Resolve current enabled flags from manifest (falls back to defaults if no manifest).
+ * Read and parse settings.json.
+ * ENOENT → returns `{ content: '{}', ok: true }`.
+ * Malformed JSON → returns `{ ok: false, reason: string }`.
+ *
+ * NEVER silently falls back to '{}' on malformed JSON — that would clobber the
+ * user's settings. The caller must abort with exit code 1 on !ok (avoids PF-023).
  */
-async function resolveEnabledFlags(devflowDir) {
-    const manifest = await readManifest(devflowDir);
-    if (manifest) {
-        return manifest.features.flags;
+async function readSettingsSafe(settingsPath) {
+    let raw;
+    try {
+        raw = await fs.readFile(settingsPath, 'utf-8');
     }
-    return getDefaultFlags();
+    catch (err) {
+        if (err.code === 'ENOENT') {
+            return { ok: true, content: '{}' };
+        }
+        return { ok: false, reason: `Cannot read settings.json: ${err.message}` };
+    }
+    // REL-M2 + PERF-L4: single parse — validate root shape and return raw string.
+    // The plain-object guard catches null/array roots before they reach applyFlags/stripFlags
+    // (applies PF-023 — validate at the sink; early rejection gives actionable error messages).
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return { ok: false, reason: 'settings.json is malformed — fix it before changing flags' };
+    }
+    if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        return { ok: false, reason: 'settings.json must be a JSON object — fix it before changing flags' };
+    }
+    return { ok: true, content: raw };
 }
 /**
- * Update settings.json with the given flag set.
+ * Persist a FlagsRecord to settings.json and manifest.
+ *
+ * Uses `convergeFlagsIntoSettings` (ARCH-H1: fold-before-strip pipeline) so the
+ * invariant lives in the pipeline, not at call sites. This ensures that:
+ *   - An externally-set /focus survives unless viewModeExplicit is true (PF-015).
+ *   - Valued flags not yet claimed by devflow (absent from the manifest record)
+ *     have their existing settings values preserved rather than stripped (REG-H1,
+ *     SEC-M3, ADR-014).
+ *
+ * PF-015: settings write and manifest write are evaluated independently.
+ * Each failure is reported with its own message and exit code 1.
+ * The second write is never skipped due to the first succeeding or failing.
+ *
+ * Returns a discriminated PersistResult (never a boolean — avoids the two-state
+ * lie that cannot express the third "manifest absent" outcome). Success is tracked
+ * in LOCALS, never read back off `process.exitCode` (avoids PF-014, PF-015).
  */
-async function updateSettingsFlags(claudeDir, flagIds) {
+async function persistFlagConfig(claudeDir, devflowDir, settingsContent, newRecord, 
+// ARCH-M2 + PERF-L1: caller passes the already-read manifest so this function
+// does not re-read it (two snapshots, one write; readManifest also self-heals
+// = extra write). null → {ok:false,reason:'no-manifest'} (C2 discriminant intact).
+manifest, opts = { viewModeExplicit: false }) {
+    // D15: convergeFlagsIntoSettings is the fold-before-strip pipeline entry point
+    // (applies PF-015, PF-017, REG-H1, ARCH-H1). ownedRecord is omitted so the
+    // `newRecord` (the manifest record) serves as the owned set — a key present in
+    // the manifest means devflow previously claimed it; absent = never written by
+    // devflow, so the existing settings value is adopted.
+    const { settings: updatedSettings, record: foldedRecord } = convergeFlagsIntoSettings(settingsContent, newRecord, opts);
+    // PF-015: accumulate each artifact's failure independently; combine at the end.
+    const failed = [];
+    // Settings write — independent error path (avoids PF-015 fan-out).
     const settingsPath = path.join(claudeDir, 'settings.json');
-    let content;
     try {
-        content = await fs.readFile(settingsPath, 'utf-8');
-        // Validate that content is parseable JSON before passing to stripFlags/applyFlags
-        JSON.parse(content);
+        await writeFileAtomicExclusive(settingsPath, updatedSettings);
     }
-    catch {
-        content = '{}';
+    catch (err) {
+        p.log.error(`Failed to write settings.json: ${err instanceof Error ? err.message : String(err)}`);
+        failed.push('settings');
+        process.exitCode = 1;
+        // PF-015: still attempt the manifest write — evaluate each artifact independently.
+    }
+    // Manifest write — independent error path (avoids PF-015 fan-out).
+    // Uses foldedRecord (not newRecord) so adopted values are persisted to the
+    // manifest, keeping manifest ↔ settings.json in sync.
+    //
+    // An absent manifest is a FAILURE, not a no-op (TS-H2 / ARCH-H2 / REL-H2):
+    // returning success here would tell the user "Flags saved." while the manifest
+    // was never updated — reverted on the next `devflow init`.
+    if (!manifest) {
+        p.log.error('No devflow manifest found — flag selections were not recorded. Run devflow init first.');
+        process.exitCode = 1;
+        // Return the dedicated discriminant so callers cannot accidentally suppress it.
+        return { ok: false, reason: 'no-manifest' };
+    }
+    manifest.features.flags = foldedRecord;
+    manifest.updatedAt = new Date().toISOString();
+    try {
+        await writeManifest(devflowDir, manifest);
+    }
+    catch (err) {
+        p.log.error(`Failed to write manifest.json: ${err instanceof Error ? err.message : String(err)}`);
+        failed.push('manifest');
+        process.exitCode = 1;
     }
-    const stripped = stripFlags(content);
-    const updated = applyFlags(stripped, flagIds);
-    await fs.writeFile(settingsPath, updated, 'utf-8');
+    // PF-015: OR the locals afterwards — never compose required side effects with ||/&&.
+    return failed.length > 0 ? { ok: false, failed } : { ok: true };
 }
 /**
- * Update manifest with the given flag set.
+ * Load manifest and settings.json for the mutating CLI branches.
+ *
+ * Returns a discriminated result — never exits itself. The dispatcher or handler
+ * reports the reason and sets process.exitCode = 1 on failure (avoids PF-014).
+ * One shared load path means a fix lands once, not four times (applies PF-017 —
+ * the four copies of the same preamble are exactly the "fix on one site, miss the
+ * other three" shape).
  */
-async function updateManifestFlags(devflowDir, flagIds) {
+async function loadFlagContext(claudeDir, devflowDir) {
     const manifest = await readManifest(devflowDir);
-    if (!manifest)
-        return;
-    manifest.features.flags = flagIds;
-    manifest.updatedAt = new Date().toISOString();
-    await writeManifest(devflowDir, manifest);
+    if (!manifest) {
+        return { ok: false, reason: 'No devflow installation found — run devflow init first' };
+    }
+    const settingsResult = await readSettingsSafe(path.join(claudeDir, 'settings.json'));
+    if (!settingsResult.ok) {
+        return { ok: false, reason: settingsResult.reason };
+    }
+    return { ok: true, value: { manifest, settingsContent: settingsResult.content } };
 }
 /**
- * Parse and validate comma-separated flag IDs against the registry.
- * Exits with error if any IDs are unknown.
+ * Format the current FlagsRecord as a status table — one row per registry flag.
+ *
+ * Shared between --status (p.log.info sink) and bare non-TTY (process.stdout.write
+ * sink). Both call sites choose their own sink; this function produces the row
+ * strings only (CPLX-SF5, CONS-M3: the longer "not adopted — default X applies
+ * on next devflow init" wording is kept in both surfaces; the short form dropped
+ * the actionable second half).
+ *
+ * Returns plain strings — sanitizeCell strips control characters to prevent a
+ * persisted LF/TAB from reshaping the line-oriented table (applies SEC-M1).
  */
-function parseFlagIds(input) {
-    const ids = input.split(',').map(s => s.trim()).filter(Boolean);
-    const invalid = ids.filter(id => !FLAG_REGISTRY.some(f => f.id === id));
-    if (invalid.length > 0) {
-        p.log.error(`Unknown flag(s): ${invalid.join(', ')}`);
-        p.log.info(`Available: ${FLAG_REGISTRY.map(f => f.id).join(', ')}`);
-        process.exit(1);
-    }
-    return ids;
+function formatStatusRows(record) {
+    return FLAG_REGISTRY.map(flag => {
+        const value = Object.prototype.hasOwnProperty.call(record, flag.id)
+            ? record[flag.id]
+            : undefined;
+        // sanitizeCell: defence in depth — a persisted LF/TAB must not inject extra
+        // rows into the line-oriented table (applies SEC-M1).
+        // D-EFFDV: effectiveDisplay supplies the default label so 'unset' never appears.
+        const rawDisplay = value !== undefined
+            ? formatFlagValue(flag, value)
+            : `not adopted — default: ${effectiveDisplay(flag, neutralValueOf(flag)).text} applies on next devflow init`;
+        const displayValue = sanitizeCell(rawDisplay);
+        return `${flag.id.padEnd(28)} ${displayValue}`;
+    });
 }
-export const flagsCommand = new Command('flags')
-    .description('Manage Claude Code feature flags')
-    .option('--enable <ids>', 'Enable flag(s), comma-separated')
-    .option('--disable <ids>', 'Disable flag(s), comma-separated')
-    .option('--status', 'Show current flag states')
-    .option('--list', 'List all available flags')
-    .action(async (options) => {
-    const claudeDir = getClaudeDirectory();
-    const devflowDir = getDevFlowDirectory();
-    if (options.list) {
-        p.intro(color.bgCyan(color.black(' Claude Code Flags ')));
-        const defaults = new Set(getDefaultFlags());
-        for (const flag of FLAG_REGISTRY) {
-            const status = defaults.has(flag.id) ? color.green('default ON') : color.dim('default OFF');
-            const targetInfo = flag.target.type === 'env'
-                ? `env.${flag.target.key}`
-                : `setting.${flag.target.key}`;
-            p.log.info(`${color.bold(flag.id)} — ${flag.label} (${status})`);
-            p.log.info(`  ${color.dim(flag.description)} → ${color.dim(targetInfo)}`);
+// ─── Branch handlers ──────────────────────────────────────────────────────────
+//
+// One named async handler per CLI branch — each is independently readable and
+// carries one responsibility. The dispatcher (createFlagsCommand action) is ~15
+// lines and routes without logic of its own (ARCH-M1, CPLX-H1).
+/** Handle --list: read-only registry dump, no manifest required. */
+async function handleList() {
+    p.intro(color.bgCyan(color.black(' Claude Code Flags ')));
+    for (const flag of FLAG_REGISTRY) {
+        const kindLabel = describeFlagKind(flag);
+        const targetInfo = flag.target.type === 'env'
+            ? `env ${flag.target.key}`
+            : `setting ${flag.target.key}`;
+        // D-EFFDV: number flags show the upstream default when present so the
+        // registry dump is meaningful even for flags with no devflow defaultValue.
+        const defaultLabel = flag.kind === 'number' && flag.upstreamDefault !== undefined
+            ? `upstream default: ${flag.upstreamDefault}`
+            : flag.defaultValue !== undefined && flag.defaultValue !== null
+                ? String(flag.defaultValue)
+                : 'none';
+        const recLabel = flag.recommended ? color.green('recommended') : color.dim('optional');
+        p.log.info(`${color.bold(flag.id.padEnd(28))} ${recLabel.padEnd(20)} ${color.dim(kindLabel.padEnd(36))} ${color.dim(targetInfo)}`);
+        p.log.info(`  ${color.dim(flag.hint)} — default: ${color.cyan(defaultLabel)}`);
+    }
+    p.outro(color.dim('Use --enable / --disable / --set / --unset to manage flags'));
+}
+/** Handle --status: read-only status table, degrades gracefully without a manifest. */
+async function handleStatus(devflowDir) {
+    p.intro(color.bgCyan(color.black(' Claude Code Flags — Status ')));
+    const manifest = await readManifest(devflowDir);
+    if (!manifest) {
+        p.log.warn('Devflow is not installed — run devflow init first');
+        p.log.info('Showing registry defaults only:');
+    }
+    const record = manifest?.features.flags ?? {};
+    for (const row of formatStatusRows(record)) {
+        p.log.info(row);
+    }
+    p.outro(color.dim('Use --enable / --disable / --set / --unset to change flags'));
+}
+/**
+ * Handle --enable/--disable: set boolean flags to the given value.
+ *
+ * Collapsed from two identical 50-line branches into one handler parameterized by
+ * `value: boolean` — the only deltas were the record assignment (true vs false)
+ * and one error-message string (--set vs --unset as the suggested alternative)
+ * (CPLX-H2 — applies PF-017: one fix lands once, not twice).
+ */
+async function handleSetBooleans(claudeDir, devflowDir, ids, value) {
+    // Validate: must be known boolean flags only.
+    // Collect the validated flag definitions so the success loop can use them
+    // directly — avoids findFlag(id) re-lookups after the guard (TS-S1).
+    const flagDefs = [];
+    for (const id of ids) {
+        const flag = findFlag(id);
+        if (!flag) {
+            p.log.error(`Unknown flag: ${color.bold(id)}`);
+            p.log.info(`Available: ${FLAG_REGISTRY.map(f => f.id).join(', ')}`);
+            process.exitCode = 1;
+            return;
+        }
+        if (flag.kind !== 'boolean') {
+            const alt = value ? `--set ${id}=value` : `--unset ${id}`;
+            p.log.error(`${color.bold(id)} is a ${flag.kind} flag — use ${color.bold(alt)} to ${value ? 'set' : 'clear'} it`);
+            process.exitCode = 1;
+            return;
         }
+        flagDefs.push(flag);
+    }
+    // Manifest required for mutating ops (avoids settings/manifest desync)
+    const ctx = await loadFlagContext(claudeDir, devflowDir);
+    if (!ctx.ok) {
+        p.log.error(ctx.reason);
+        process.exitCode = 1;
         return;
     }
-    if (options.status) {
-        p.intro(color.bgCyan(color.black(' Claude Code Flags ')));
-        const enabled = new Set(await resolveEnabledFlags(devflowDir));
-        for (const flag of FLAG_REGISTRY) {
-            const state = enabled.has(flag.id) ? color.green('enabled') : color.dim('disabled');
-            p.log.info(`${flag.id.padEnd(25)} ${state}`);
+    // PF-015: compute new record before any write
+    const newRecord = { ...ctx.value.manifest.features.flags };
+    for (const flag of flagDefs) {
+        newRecord[flag.id] = value;
+    }
+    const result = await persistFlagConfig(claudeDir, devflowDir, ctx.value.settingsContent, newRecord, ctx.value.manifest);
+    if (result.ok) {
+        for (const flag of flagDefs) {
+            // D-EFFDV: formatFlagValue routes through effectiveDisplay — one vocabulary
+            // shared with --status and TUI so the three surfaces cannot drift.
+            p.log.success(`${flag.id} ${formatFlagValue(flag, value)}`);
+        }
+    }
+}
+/** Handle --set id=value (repeatable): validate all assignments then persist. */
+async function handleSet(claudeDir, devflowDir, setValues) {
+    // Phase: parse and validate ALL assignments before any mutation.
+    const assignments = [];
+    for (const assignment of setValues) {
+        // Split on first = only — rest is the value (e.g. spellcheck=a=b → id='spellcheck', value='a=b')
+        const eqIdx = assignment.indexOf('=');
+        if (eqIdx === -1) {
+            p.log.error(`Invalid --set format: ${color.bold(assignment)} — expected id=value`);
+            process.exitCode = 1;
+            return;
+        }
+        const id = assignment.slice(0, eqIdx);
+        const text = assignment.slice(eqIdx + 1);
+        // Prototype pollution guard (applies PF-023)
+        if (id === '__proto__' || id === 'constructor' || id === 'prototype') {
+            p.log.error(`Unknown flag: ${color.bold(id)}`);
+            process.exitCode = 1;
+            return;
+        }
+        const flag = findFlag(id);
+        if (!flag) {
+            p.log.error(`Unknown flag: ${color.bold(id)}`);
+            p.log.info(`Available: ${FLAG_REGISTRY.map(f => f.id).join(', ')}`);
+            process.exitCode = 1;
+            return;
         }
+        const value = parseFlagValueInput(flag, text);
+        if (value === null && text !== 'unset') {
+            // parseFlagValueInput returns null both for 'unset' and for invalid values.
+            // If the input isn't literally 'unset', the null means invalid.
+            p.log.error(`Invalid value for ${color.bold(id)}: ${color.bold(text)}`);
+            p.log.info(`Expected: ${expectedInputFor(flag)}`);
+            process.exitCode = 1;
+            return;
+        }
+        assignments.push({ id, flag, value });
+    }
+    // All assignments valid — load manifest + settings
+    const ctx = await loadFlagContext(claudeDir, devflowDir);
+    if (!ctx.ok) {
+        p.log.error(ctx.reason);
+        process.exitCode = 1;
         return;
     }
-    if (options.enable) {
-        const ids = parseFlagIds(options.enable);
-        const current = await resolveEnabledFlags(devflowDir);
-        const updated = [...new Set([...current, ...ids])];
-        await updateSettingsFlags(claudeDir, updated);
-        await updateManifestFlags(devflowDir, updated);
-        for (const id of ids) {
-            p.log.success(`${id} enabled`);
+    // PF-015: compute final record before any write
+    const newRecord = { ...ctx.value.manifest.features.flags };
+    for (const { id, flag, value } of assignments) {
+        // null from parseFlagValueInput for literal 'unset' → use neutral value
+        newRecord[id] = value ?? neutralValueOf(flag);
+    }
+    // viewModeExplicit: true when the user explicitly assigned view-mode in --set.
+    // This lets the chosen value override an externally-set /focus.
+    const viewModeExplicit = assignments.some(a => a.id === 'view-mode');
+    const result = await persistFlagConfig(claudeDir, devflowDir, ctx.value.settingsContent, newRecord, ctx.value.manifest, { viewModeExplicit });
+    if (result.ok) {
+        for (const { id, flag, value } of assignments) {
+            // null means the user typed 'unset' explicitly — echo their word back.
+            // For active values, route through formatFlagValue (D-EFFDV vocabulary).
+            const displayText = value === null ? 'unset' : formatFlagValue(flag, value);
+            p.log.success(`${id} = ${displayText}`);
         }
+    }
+}
+/** Handle --unset ids: reset flags to their neutral values. */
+async function handleUnset(claudeDir, devflowDir, ids) {
+    // Validate: must be known flags (any kind).
+    // Collect the validated flag definitions so the mutation loop can use them
+    // directly — avoids findFlag(id) re-lookups after the guard (TS-S1).
+    const flagDefs = [];
+    for (const id of ids) {
+        const flag = findFlag(id);
+        if (!flag) {
+            p.log.error(`Unknown flag: ${color.bold(id)}`);
+            p.log.info(`Available: ${FLAG_REGISTRY.map(f => f.id).join(', ')}`);
+            process.exitCode = 1;
+            return;
+        }
+        flagDefs.push(flag);
+    }
+    const ctx = await loadFlagContext(claudeDir, devflowDir);
+    if (!ctx.ok) {
+        p.log.error(ctx.reason);
+        process.exitCode = 1;
         return;
     }
-    if (options.disable) {
-        const ids = parseFlagIds(options.disable);
-        const current = await resolveEnabledFlags(devflowDir);
-        const toDisable = new Set(ids);
-        const updated = current.filter(id => !toDisable.has(id));
-        await updateSettingsFlags(claudeDir, updated);
-        await updateManifestFlags(devflowDir, updated);
+    // PF-015: compute new record before any write
+    const newRecord = { ...ctx.value.manifest.features.flags };
+    for (const flag of flagDefs) {
+        newRecord[flag.id] = neutralValueOf(flag);
+    }
+    // viewModeExplicit: true when the user explicitly unset view-mode.
+    const viewModeExplicit = ids.includes('view-mode');
+    const result = await persistFlagConfig(claudeDir, devflowDir, ctx.value.settingsContent, newRecord, ctx.value.manifest, { viewModeExplicit });
+    if (result.ok) {
         for (const id of ids) {
-            p.log.success(`${id} disabled`);
+            p.log.success(`${id} unset`);
         }
-        return;
     }
-    // No option — show help
-    p.log.info('Usage: devflow flags --status | --list | --enable <ids> | --disable <ids>');
-});
+}
+/**
+ * Apply a TUI result to disk — the save/persist seam extracted from handleBare.
+ *
+ * Enables seam testing of the TUI→persist wiring without a real TTY (closes
+ * the interactive-surface coverage gap per PF-017(c)). The test drives
+ * runFlagsTui with PassThrough streams, feeds its result here, and asserts
+ * the whole post-state of both artifacts (manifest + settings.json) per PF-015.
+ *
+ * @param result       TUI result from runFlagsTui — action 'save', 'cancel', or 'abort'.
+ * @param freshSettingsContent Settings.json content re-read AFTER the TUI closed
+ *                     (see REL-M3 in handleBare — caller owns the re-read).
+ * @param manifest     Loaded manifest threaded from loadFlagContext before TUI launch.
+ * @param claudeDir    Path to ~/.claude directory (for settings.json write).
+ * @param devflowDir   Path to ~/.devflow directory (for manifest write).
+ * @returns 'saved' on successful persist, 'unchanged' for cancel/abort,
+ *          or the PersistResult error discriminant when persist fails
+ *          (persistFlagConfig already logged + set exitCode in that case).
+ */
+export async function applyTuiResult(result, freshSettingsContent, manifest, claudeDir, devflowDir) {
+    if (result.action !== 'save') {
+        return 'unchanged';
+    }
+    const existingRecord = manifest.features.flags;
+    const newRecord = collectFlagRecord(result.rows);
+    // viewModeExplicit: true if the user changed the view-mode row in the TUI
+    const viewModeExplicit = newRecord['view-mode'] !== existingRecord['view-mode'];
+    const persistResult = await persistFlagConfig(claudeDir, devflowDir, freshSettingsContent, newRecord, manifest, { viewModeExplicit });
+    if (persistResult.ok) {
+        return 'saved';
+    }
+    return persistResult;
+}
+/**
+ * Handle bare invocation (no subcommand flags).
+ *
+ * D-P5-1: TTY path launches the interactive flags TUI via lazy import;
+ * non-TTY path prints a status table + note to stderr + exitCode 1.
+ * CONS-M3: formatStatusRows() is the shared row formatter — non-TTY now uses
+ * the longer "not adopted — default X applies on next devflow init" wording,
+ * matching --status (convergence of the two divergent status surfaces).
+ *
+ * TS-H2 / ARCH-H2 / REL-H2: TTY path reuses loadFlagContext (the same guard
+ * that mutating handlers use) before importing or launching the TUI. An absent or
+ * unreadable manifest is a hard-refuse: the TUI must not launch, and settings.json
+ * must not be touched. This prevents the silent-factory-reset path (TUI seeded
+ * from {} writes settings.json; next devflow init re-adopts registry defaults and
+ * silently reverts everything the user confirmed). The non-TTY path degrades
+ * gracefully (status table only, no writes, no manifest required).
+ */
+async function handleBare(claudeDir, devflowDir) {
+    // REL-H1: require both stdin AND stdout to be TTYs.
+    // Gating on process.stdout.isTTY alone lets `devflow flags < /dev/null` enter
+    // alt-screen while stdin ends immediately, leaving the terminal stranded with
+    // hidden cursor on exit. Precedent: agents.ts uses the same two-flag predicate.
+    if (process.stdin.isTTY && process.stdout.isTTY) {
+        // ── Manifest + settings required before the TUI may launch ──────────
+        // Reuses loadFlagContext — the same guard as --enable/--disable/--set/--unset.
+        // If the manifest is absent or unreadable, we refuse here and settings.json
+        // is never touched (avoids TS-H2 / ARCH-H2 / REL-H2 silent half-write).
+        const ctx = await loadFlagContext(claudeDir, devflowDir);
+        if (!ctx.ok) {
+            p.log.error(ctx.reason);
+            process.exitCode = 1;
+            return;
+        }
+        const record = ctx.value.manifest.features.flags;
+        // ── Build initial rows from registry + current record ──────────────
+        // buildFlagRows is a static import (pure — no TTY); only runFlagsTui is lazy.
+        const initialRows = buildFlagRows(record);
+        // ── Launch TUI ────────────────────────────────────────────────────
+        const { runFlagsTui } = await import('../flags-view/index.js');
+        // Wrap: runTui rejects on initial-render failure or handler throw.
+        // On rejection: log and bail — no settings write (avoids PF-014 process.exit).
+        let result;
+        try {
+            result = await runFlagsTui(initialRows);
+        }
+        catch (err) {
+            p.log.error(`Flags editor failed: ${err instanceof Error ? err.message : String(err)}`);
+            process.exitCode = 1;
+            return;
+        }
+        if (result.action === 'save') {
+            // REL-M3: re-read settings.json AFTER the human-paced TUI session closes.
+            // The read captured before runFlagsTui is a stale snapshot by the time the
+            // user saves — any concurrent writer (proxy enable, devflow agents, Claude
+            // Code /config) that ran during the session would be silently overwritten by
+            // the atomic rename in writeFileAtomicExclusive. Re-reading rebases the flag
+            // write onto current content and ensures convergeFlagsIntoSettings sees the
+            // fresh viewMode (applies PF-022 — file state, not config state, is reality).
+            const freshSettings = await readSettingsSafe(path.join(claudeDir, 'settings.json'));
+            if (!freshSettings.ok) {
+                p.log.error(freshSettings.reason);
+                process.exitCode = 1;
+                return;
+            }
+            const outcome = await applyTuiResult(result, freshSettings.content, ctx.value.manifest, claudeDir, devflowDir);
+            if (outcome === 'saved') {
+                p.outro(color.green('Flags saved.'));
+            }
+            // Error outcomes: persistFlagConfig already logged and set exitCode.
+        }
+        else {
+            p.outro(color.dim('No changes made.'));
+        }
+    }
+    else {
+        // non-TTY: status table — degrades gracefully without manifest (read-only).
+        const manifest = await readManifest(devflowDir);
+        const record = manifest?.features.flags ?? {};
+        for (const row of formatStatusRows(record)) {
+            process.stdout.write(`${row}\n`);
+        }
+        process.stderr.write('Note: interactive TUI requires a TTY. Use --enable/--disable/--set/--unset for mutations.\n');
+        process.exitCode = 1;
+    }
+}
+// ─── Command factory ──────────────────────────────────────────────────────────
+/** Accumulator for repeatable --set options. */
+function collectSet(val, prev) {
+    return prev.concat(val);
+}
+/**
+ * Create a fresh flags Command instance.
+ *
+ * Call this in tests to get a clean Commander instance per test case — avoids
+ * Commander's internal option-value state leaking across tests.
+ *
+ * Bare invocation (no subcommand):
+ *   - TTY: launches the interactive flags TUI (lazy import keeps TTY machinery
+ *     out of --list/--status code paths).
+ *   - non-TTY: prints status table to stdout + note to stderr + exitCode 1.
+ */
+export function createFlagsCommand() {
+    return new Command('flags')
+        .description('Manage Claude Code feature flags')
+        .option('--list', 'List all available flags with metadata')
+        .option('--status', 'Show current flag states')
+        .option('--enable <ids>', 'Enable boolean flag(s), comma-separated')
+        .option('--disable <ids>', 'Disable boolean flag(s), comma-separated')
+        .option('--set <assignment>', 'Set flag value (repeatable): id=value. Use "unset" as value to clear.', collectSet, [])
+        .option('--unset <ids>', 'Reset flag(s) to neutral (comma-separated)')
+        .action(async (options) => {
+        const claudeDir = getClaudeDirectory();
+        const devflowDir = getDevFlowDirectory();
+        const splitIds = (s) => s.split(',').map(t => t.trim()).filter(Boolean);
+        if (options.list)
+            return handleList();
+        if (options.status)
+            return handleStatus(devflowDir);
+        if (options.enable !== undefined)
+            return handleSetBooleans(claudeDir, devflowDir, splitIds(options.enable), true);
+        if (options.disable !== undefined)
+            return handleSetBooleans(claudeDir, devflowDir, splitIds(options.disable), false);
+        if (options.set && options.set.length > 0)
+            return handleSet(claudeDir, devflowDir, options.set);
+        if (options.unset !== undefined)
+            return handleUnset(claudeDir, devflowDir, splitIds(options.unset));
+        return handleBare(claudeDir, devflowDir);
+    });
+}
+// ─── Singleton export ─────────────────────────────────────────────────────────
+//
+// src/cli.ts imports this; end-to-end tests should use createFlagsCommand()
+// instead to get a fresh instance per test.
+export const flagsCommand = createFlagsCommand();
 //# sourceMappingURL=flags.js.map