devflow-kit 2.3.0 → 2.5.0

package/dist/cli/commands/prompt-io.js

@@ -0,0 +1,38 @@
+/**
+ * Shared wizard prompt-IO seam for devflow init wizard steps.
+ *
+ * One-definition seam: PromptOutcome and WizardPromptIO were byte-identical
+ * duplicates across attribution-prompts.ts and compliance-prompts.ts
+ * (architecture-03 / consistency-06). They are defined ONCE here and re-used
+ * via import.
+ *
+ * D-PROMPT-IO: WizardPromptIO is the base DI seam for all two-action wizard
+ * steps (note + boolean select). Modules that add a third prompt extend this
+ * interface with an intersection type (e.g. CompliancePromptIO).
+ */
+import * as p from '@clack/prompts';
+// ── Shared clack adapters ─────────────────────────────────────────────────────
+/** Real clack adapter for the note prompt. */
+export function clackNote(message, title) {
+    p.note(message, title);
+}
+/**
+ * Real clack adapter for a select prompt, generic over the option value type T.
+ *
+ * typescript-05: no `as T` cast on the result path. `p.select<T>` returns
+ * `Promise<symbol | T>`; `p.isCancel` is a `(value: unknown) => value is symbol`
+ * guard that narrows away the cancel branch, leaving `result: T` without a cast.
+ * An `as T` here would mask a future widening of the library's return type.
+ *
+ * The `as unknown as SelectOptions<T>` on the input is a safe bridge for the
+ * unresolved conditional type `Option<T>` — our shape satisfies both branches
+ * (Primitive: label optional; non-Primitive: label required) and is strictly
+ * narrower, so no value-type information is lost.
+ */
+export async function clackSelect(opts) {
+    const result = await p.select(opts);
+    if (p.isCancel(result))
+        return { kind: 'cancel' };
+    return { kind: 'value', value: result };
+}
+//# sourceMappingURL=prompt-io.js.map

package/dist/cli/commands/proxy.js

@@ -22,7 +22,7 @@ import * as https from 'https';
 import { spawn as cpSpawn } from 'child_process';
 import * as p from '@clack/prompts';
 import color from 'picocolors';
-import { readProxyState, writeProxyState, buildProxyState, buildRoutingConfigJson, proxyBaseUrl, resolveProxyBin, DEFAULT_PROXY_PORT, } from '../../core/proxy-state.js';
+import { readProxyState, writeProxyState, buildProxyState, buildRoutingConfigJson, proxyBaseUrl, proxyJsonExists, resolveProxyBin, DEFAULT_PROXY_PORT, } from '../../core/proxy-state.js';
 import { syncManifestFeature, readManifest } from '../../core/manifest.js';
 import { writeFileAtomicExclusive } from '../../core/fs-atomic.js';
 import { scrubChildEnv, openProxyLog, rotateProxyLogIfLarge } from '../../core/proxy-log.js';
@@ -149,9 +149,11 @@ function _stripProxyEnvFromObject(settings, managedPort) {
     const env = s.env;
     if (!env)
         return false;
-    // Devflow is the only producer of this var — always remove it, regardless of whether
-    // the URL is still ours. Port-scoping protects a FOREIGN url value; there is no
-    // foreign value of this key to protect. (applies PF-015, ADR-003)
+    // D-STRIP-1: every REMOVAL caller (init, uninstall, runDisable) first proves Devflow
+    // managed the proxy — `proxyJsonExists()` — and the enable caller is taking ownership
+    // of the key anyway, so reaching this line means the value is Devflow's to remove.
+    // Removal is therefore unconditional: unlike ANTHROPIC_BASE_URL (port-scoped below),
+    // this key has no foreign value to protect. (applies PF-015, ADR-003)
     const hadWindowVar = env[UNKNOWN_MODEL_WINDOW_ENV] !== undefined;
     delete env[UNKNOWN_MODEL_WINDOW_ENV];
     let removedUrl = false;
@@ -284,6 +286,31 @@ export function applyDisableToSettings(settings, managedPort) {
     const strippedEnv = _stripProxyEnvFromObject(settings, managedPort);
     return removedHooks || strippedEnv;
 }
+/**
+ * Settings teardown for every path that turns the proxy off: `devflow proxy --disable`
+ * and `devflow uninstall`.
+ *
+ * D-STRIP-1: the two removals answer to different evidence, so they are gated
+ * separately.
+ * - Hooks are Devflow's own artifacts — removed unconditionally. Leaving them behind
+ *   points later sessions at a hook script that no longer exists, and makes a re-run
+ *   of an interrupted uninstall unable to clean up.
+ * - The env vars (ANTHROPIC_BASE_URL, CLAUDE_CODE_DISABLE_UNKNOWN_MODEL_WINDOW_ENFORCEMENT)
+ *   are stripped only against `managedPort`, which the caller supplies from an existing
+ *   `proxy.json` — the one piece of evidence that Devflow ever wrote them. Pass
+ *   `undefined` when that file is absent: the values then belong to a gateway Devflow
+ *   never managed (a user's own LiteLLM on 4141, say) and must survive untouched.
+ *
+ * When `managedPort` is defined this delegates to `applyDisableToSettings`, so the
+ * both-operations invariant documented there still holds.
+ *
+ * Mutates settings in place. Returns true when any change was made.
+ */
+export function applyProxyTeardownToSettings(settings, managedPort) {
+    if (managedPort === undefined)
+        return removeProxyHooks(settings);
+    return applyDisableToSettings(settings, managedPort);
+}
 /**
  * Check whether the ensure-proxy hook is registered on at least one event.
  * Returns true if present on either SessionStart or UserPromptSubmit.
@@ -316,6 +343,47 @@ export function isOurRelayBody(body) {
         return false;
     }
 }
+/**
+ * Preflight check ④ — settings.json readable and parseable, no foreign
+ * ANTHROPIC_BASE_URL, plus the non-fatal ANTHROPIC_API_KEY warning.
+ *
+ * Extracted so the adopted-relay path and the free-port path run the identical
+ * check (D-EFR-5): a healthy relay on the port must not buy an exemption from the
+ * foreign-gateway refusal. Keeping it in one function is what stops the two paths
+ * from drifting on which sub-checks they apply or which message they return.
+ *
+ * `swallowSettingsReadError` semantics are preserved by the caller-supplied dep:
+ * when that flag is set (init), readSettingsJson() resolves to '{}' on I/O failure
+ * instead of rejecting, so the read-failure branch is reachable only from runEnable.
+ */
+async function checkSettingsEnv(deps, port) {
+    let settingsJson;
+    try {
+        settingsJson = await deps.readSettingsJson();
+    }
+    catch {
+        return Err('Could not read settings.json — check file permissions');
+    }
+    let parsedSettings;
+    try {
+        parsedSettings = JSON.parse(settingsJson);
+    }
+    catch {
+        return Err('settings.json is malformed — fix it before enabling the proxy');
+    }
+    if (readProxyEnvState(settingsJson, port) === 'foreign') {
+        return Err('An existing ANTHROPIC_BASE_URL in settings.json points to a different gateway — Devflow will not overwrite it');
+    }
+    // API key warning (non-fatal)
+    const envBlock = parsedSettings.env;
+    if (typeof envBlock === 'object' &&
+        envBlock !== null &&
+        !Array.isArray(envBlock) &&
+        typeof envBlock.ANTHROPIC_API_KEY === 'string') {
+        deps.onWarn?.('ANTHROPIC_API_KEY is set in settings.json — requests will use that key through the local relay');
+    }
+    return Ok(undefined);
+}
 /**
  * Run preflight checks before enabling the Devflow proxy.
  *
@@ -324,6 +392,8 @@ export function isOurRelayBody(body) {
  * ② ~/.codex/auth.json exists.
  * ③ Port probe: free → OK; accepting → health check → adopt or fail.
  * ④ settings.json parseable; ANTHROPIC_BASE_URL not pointing elsewhere; API key warn.
+ *    Runs on BOTH outcomes of ③ that can proceed — adopted relay and free port
+ *    (D-EFR-5) — via the shared `checkSettingsEnv` helper.
  *
  * Doctor is deliberately excluded from preflight: the relay's doctor subcommand
  * probes the relay port — a not-yet-started relay makes that probe fail (exit 1). A
@@ -349,6 +419,12 @@ export async function runProxyPreflight(port, codexAuthPath, configPath, logPath
         // Port is up — check health identity
         const healthResult = await deps.httpGet(`${proxyBaseUrl(port)}/__subswitch/health`, PROBE_TIMEOUT_MS);
         if (healthResult.ok && isOurRelayBody(healthResult.value)) {
+            // D-EFR-5: run check ④ BEFORE the adopted early-return. The old order
+            // (adopted-return first, settings check only when the port was free) let a
+            // healthy relay on the port silently skip the foreign-gateway refusal entirely.
+            const settingsCheck = await checkSettingsEnv(deps, port);
+            if (!settingsCheck.ok)
+                return Err(settingsCheck.error);
             return Ok({ binPath, npxWarning, adopted: true });
         }
         // Port accepting but health timed out, failed, or not our relay
@@ -356,32 +432,9 @@ export async function runProxyPreflight(port, codexAuthPath, configPath, logPath
     }
     // Port refused — free to proceed
     // ④ Settings.json check
-    let settingsJson;
-    try {
-        settingsJson = await deps.readSettingsJson();
-    }
-    catch {
-        return Err('Could not read settings.json — check file permissions');
-    }
-    let parsedSettings;
-    try {
-        parsedSettings = JSON.parse(settingsJson);
-    }
-    catch {
-        return Err('settings.json is malformed — fix it before enabling the proxy');
-    }
-    const envState = readProxyEnvState(settingsJson, port);
-    if (envState === 'foreign') {
-        return Err('An existing ANTHROPIC_BASE_URL in settings.json points to a different gateway — Devflow will not overwrite it');
-    }
-    // API key warning (non-fatal)
-    const envBlock = parsedSettings.env;
-    if (typeof envBlock === 'object' &&
-        envBlock !== null &&
-        !Array.isArray(envBlock) &&
-        typeof envBlock.ANTHROPIC_API_KEY === 'string') {
-        deps.onWarn?.('ANTHROPIC_API_KEY is set in settings.json — requests will use that key through the local relay');
-    }
+    const settingsCheck = await checkSettingsEnv(deps, port);
+    if (!settingsCheck.ok)
+        return Err(settingsCheck.error);
     return Ok({ binPath, npxWarning, adopted: false });
 }
 // ─── Production dependency implementations ────────────────────────────────────
@@ -1381,6 +1434,13 @@ async function runDisable() {
     // applyDisableToSettings strips ANTHROPIC_BASE_URL only when the URL
     // port matches the port Devflow manages — callers must supply it. Reading
     // proxy.json here also consolidates state for Step 2 below.
+    //
+    // D-STRIP-1: readProxyState() cannot distinguish "file absent" from "file present
+    // with the default port", so the env strip is gated on the file's existence — the
+    // only evidence that Devflow ever wrote those vars. Must be read before Step 2
+    // creates the file. Hook removal is NOT gated: our hooks are ours to remove on
+    // every path.
+    const proxyManaged = await proxyJsonExists(devflowDir);
     const priorStateResult = await readProxyState(devflowDir);
     const priorState = priorStateResult.ok ? priorStateResult.value : null;
     const managedPort = priorState?.port ?? DEFAULT_PROXY_PORT;
@@ -1401,7 +1461,7 @@ async function runDisable() {
         process.exitCode = 1;
         return;
     }
-    const changed = applyDisableToSettings(parsedSettings, managedPort);
+    const changed = applyProxyTeardownToSettings(parsedSettings, proxyManaged ? managedPort : undefined);
     if (changed) {
         // Guard ENOSPC/EACCES — unhandled rejection leaves proxy in partial state
         try {

package/dist/cli/commands/security.js

@@ -23,7 +23,74 @@ export function countDenyEntries(settingsJson) {
         return 0;
     }
 }
-// ─── Command ──────────────────────────────────────────────────────────────────
+/**
+ * Remove the Devflow deny list from the managed settings file — the ONE
+ * implementation `devflow security --disable` and `devflow init --security none`
+ * share, so "none" means none in every location (#378).
+ *
+ * Gated on detectDenyState's parse-safe signal rather than on the file merely
+ * existing: removeManagedSettings parses the file without a guard, so a corrupt
+ * managed file must be classified here and never reach it (SF5). Never throws —
+ * a permission failure is the `failed` outcome, reported by the caller.
+ *
+ * `managedPath` is the injectable seam for tests (see removeManagedSettings);
+ * production callers omit it and get the platform path.
+ */
+export async function removeManagedDenyList(rootDir, verbose, managedPath) {
+    let target;
+    if (managedPath !== undefined) {
+        target = managedPath;
+    }
+    else {
+        try {
+            target = getManagedSettingsPath();
+        }
+        catch {
+            return { kind: 'absent' };
+        }
+    }
+    let content;
+    try {
+        content = await fs.readFile(target, 'utf-8');
+    }
+    catch {
+        return { kind: 'absent' };
+    }
+    if (!detectDenyState(null, true, content).managed) {
+        return { kind: 'no-devflow-entries', path: target };
+    }
+    const removed = await removeManagedSettings(rootDir, verbose, target);
+    return removed ? { kind: 'removed', path: target } : { kind: 'failed', path: target };
+}
+/**
+ * The user-facing line for a ManagedDenyRemoval. Pure.
+ *
+ * D-MANAGED-REMOVAL-REMEDY: both `devflow security --disable` and
+ * `devflow init --security none` print this line, so the `failed` remedy names
+ * no command — pointing at `devflow security --disable` sent a user of that very
+ * command back to it. A `failed` removal means the write needed admin rights and
+ * the sudo fallback could not run (no interactive terminal) or was declined, so
+ * the remedy is exactly that: re-run interactively and accept the prompt, or
+ * edit the named file as an administrator.
+ */
+export function describeManagedDenyRemoval(outcome) {
+    switch (outcome.kind) {
+        case 'removed':
+            return { level: 'info', text: `Security deny list removed from managed settings (${outcome.path})` };
+        case 'absent':
+            return { level: 'info', text: 'No managed settings to remove' };
+        case 'no-devflow-entries':
+            return { level: 'warn', text: 'Managed settings file exists but contains no Devflow deny entries — skipping' };
+        case 'failed':
+            return {
+                level: 'warn',
+                text: `Could not remove the Devflow deny list from managed settings (${outcome.path}) — ` +
+                    'it needs admin rights, and sudo was declined or unavailable. Re-run this command in an ' +
+                    'interactive terminal and accept the sudo prompt, or, as an administrator, remove the Devflow ' +
+                    `entries from permissions.deny in ${outcome.path}.`,
+            };
+    }
+}
 export const securityCommand = new Command('security')
     .description('Manage the security deny list (permissions.deny in Claude Code settings)')
     .option('--status', 'Show current deny list state and entry counts')
@@ -157,21 +224,14 @@ export const securityCommand = new Command('security')
                 p.log.info('No Devflow deny entries found in user settings');
             }
         }
-        // Managed settings: gate on detected.managed (parse-safe signal from detectDenyState),
-        // not raw managedExists — avoids raw JSON.parse crash inside removeManagedSettings
-        // when the managed file exists but is corrupt JSON. (SF5 — applies engineering.md
-        // "never throw in business logic"; avoids PF partial-failure: user settings already
-        // stripped but manifest sync would be skipped on uncaught throw.)
-        if (detected.managed) {
-            await removeManagedSettings(rootDir, true);
-        }
-        else if (managedExists && !detected.managed) {
-            // File exists but is unparseable or contains no Devflow entries — warn and skip.
-            p.log.warn('Managed settings file exists but contains no Devflow deny entries — skipping');
-        }
-        else {
-            p.log.info('No managed settings to remove');
-        }
+        // Managed settings: the shared removal (parse-safe gate, never throws — SF5;
+        // a throw here would skip the manifest sync below after user settings were
+        // already stripped).
+        const managedMsg = describeManagedDenyRemoval(await removeManagedDenyList(rootDir, false));
+        if (managedMsg.level === 'warn')
+            p.log.warn(managedMsg.text);
+        else
+            p.log.info(managedMsg.text);
         await syncManifestFeature(devflowDir, 'security', 'none');
         return;
     }

package/dist/cli/commands/skills.js

@@ -4,7 +4,8 @@ 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 { getAllSkillNames, prefixSkillName, unprefixSkillName, FEATURE_OWNED_SKILLS } from '../../core/plugins.js';
+import { getAllSkillNames, prefixSkillName, unprefixSkillName, skillOwners, FEATURE_OWNED_SKILLS } from '../../core/plugins.js';
+import { skillsDir } from '../../core/assets.js';
 import { copyDirectory, validateSkillShadow } from '../../targets/claude-code/installer.js';
 /**
  * Check if a directory exists.
@@ -31,6 +32,25 @@ export async function hasShadow(skillName, devflowDir) {
     const dir = devflowDir ?? getDevFlowDirectory();
     return dirExists(getShadowDir(dir, skillName));
 }
+/**
+ * Which plugin(s) a user must select to get a skill — rendered for a message.
+ *
+ * Every declarer, never the first: once install is scoped, the question this
+ * answers is "which plugin do I select to keep this?", and a first-wins answer
+ * names one plugin out of several that would each do (D-ALL-OWNERS).
+ * FEATURE_OWNED skills have no plugin owner at all and say so, because telling
+ * a user to select a plugin for `compliance` would send them looking for one
+ * that does not exist.
+ */
+function describeOwners(bareName, owners) {
+    const declarers = owners ?? skillOwners(bareName);
+    if (declarers.length === 0) {
+        return FEATURE_OWNED_SKILLS.includes(bareName)
+            ? 'its feature (devflow compliance --enable)'
+            : 'no plugin';
+    }
+    return declarers.join(' or ');
+}
 /** Render the shadow-state display tag for a skill. Exhaustive switch catches new states at compile time. */
 function buildSkillShadowTag(shadowState) {
     switch (shadowState) {
@@ -72,8 +92,16 @@ export const skillsCommand = new Command('skills')
         }
         const prefixedName = prefixSkillName(bareName);
         const installedSkillDir = path.join(claudeDir, 'skills', prefixedName);
-        if (!await dirExists(installedSkillDir)) {
-            p.log.error(`Skill not installed: ${prefixedName}. Run devflow init first.`);
+        const installed = await dirExists(installedSkillDir);
+        // A skill outside the current selection is not installed, and that is no
+        // longer a reason to refuse: skills are plugin-scoped now, so "not
+        // installed" is an ordinary state for a registry skill nobody selected.
+        // The shadow is seeded from the shipped source instead and reported as
+        // DORMANT — it exists, it is preserved by every future install, and it
+        // applies to nothing until the plugin that uses it is selected.
+        const seedDir = installed ? installedSkillDir : path.join(skillsDir(), bareName);
+        if (!await dirExists(seedDir)) {
+            p.log.error(`No source for ${bareName} — reinstall devflow, then try again.`);
             process.exit(1);
         }
         const shadowDir = getShadowDir(devflowDir, bareName);
@@ -83,8 +111,12 @@ export const skillsCommand = new Command('skills')
         }
         // Create shadow directory (unprefixed) and copy original as reference backup
         await fs.mkdir(path.join(devflowDir, 'skills'), { recursive: true });
-        await copyDirectory(installedSkillDir, shadowDir);
+        await copyDirectory(seedDir, shadowDir);
         p.log.success(`Shadowed ${color.cyan(bareName)}`);
+        if (!installed) {
+            p.log.warn(`Shadow for ${bareName} is inactive — the plugin that uses it is not selected. ` +
+                `Run devflow init and select ${describeOwners(bareName)} to apply it.`);
+        }
         p.log.info(`Edit ${color.dim(path.join(shadowDir, 'SKILL.md'))} then run devflow init to apply.`);
     }
     else if (action === 'unshadow') {
@@ -114,14 +146,27 @@ export const skillsCommand = new Command('skills')
         catch { /* skills dir absent — no shadows */ }
         const shadowDirSet = new Set(shadowDirNames);
         const knownSkillSet = new Set(allSkills);
+        // L3: every skill's declarers, resolved ONCE into a map before any row is
+        // rendered. Calling skillOwners() inside the row loop would walk the whole
+        // registry per skill for an answer that does not change between rows.
+        const ownersBySkill = new Map(allSkills.map(skill => [skill, skillOwners(skill)]));
         // Build rows in parallel; short-circuit validateSkillShadow for skills with no shadow dir
         const knownResults = await Promise.all(allSkills.map(async (skill) => {
             const shadowState = shadowDirSet.has(skill)
                 ? await validateSkillShadow(path.join(shadowsRoot, skill))
                 : 'none';
-            return { skill, shadowState };
+            const installed = await dirExists(path.join(claudeDir, 'skills', prefixSkillName(skill)));
+            return { skill, shadowState, installed };
         }));
-        const rows = knownResults.map(({ skill, shadowState }) => `  ${color.cyan(skill.padEnd(28))} ${buildSkillShadowTag(shadowState)}`);
+        const rows = knownResults.map(({ skill, shadowState, installed }) => {
+            // Skills are plugin-scoped, so "which plugin do I select to keep this?"
+            // is the question the list has to answer — and for a skill that is not
+            // installed it is the only useful thing the row can say.
+            const provenance = installed
+                ? color.dim(`installed because: ${describeOwners(skill, ownersBySkill.get(skill))}`)
+                : color.dim(`not installed — provided by: ${describeOwners(skill, ownersBySkill.get(skill))}`);
+            return `  ${color.cyan(skill.padEnd(28))} ${buildSkillShadowTag(shadowState).padEnd(20)} ${provenance}`;
+        });
         // Orphan shadows: in ~/.devflow/skills/ but not a known skill
         for (const dirName of shadowDirNames) {
             if (!knownSkillSet.has(dirName)) {
@@ -129,7 +174,8 @@ export const skillsCommand = new Command('skills')
             }
         }
         const shadowedCount = knownResults.filter(r => r.shadowState !== 'none').length;
-        p.note(rows.join('\n'), `Skills (${allSkills.length} known, ${shadowedCount} shadowed)`);
+        const installedCount = knownResults.filter(r => r.installed).length;
+        p.note(rows.join('\n'), `Skills (${allSkills.length} known, ${installedCount} installed, ${shadowedCount} shadowed)`);
     }
     else {
         p.log.error(`Unknown action: ${action}`);

package/dist/cli/commands/tracker-prompts.js

@@ -0,0 +1,145 @@
+/**
+ * Tracker prompt helpers for devflow init.
+ *
+ * CLI-layer module (ADR-013): prompt-rendering logic lives in src/cli/commands/,
+ * core business logic stays in src/core/tracker.ts.
+ *
+ * avoids PF-029: the wizard gate keys on `modePromptShown` (was the Setup-mode
+ * p.select prompt actually shown?), never on the mode name, so --recommended
+ * (flag, no prompt) and the non-TTY fallback preserve their promptless contracts.
+ * avoids PF-014: runTrackerStep never calls process.exit() or throws — callers
+ * own the cancel idiom (p.cancel + process.exit(0)), keeping try/finally safe.
+ * The shared DI seam (PromptOutcome, WizardPromptIO, clackNote, clackSelect) is
+ * defined once in prompt-io.ts and imported here, never re-declared.
+ *
+ * D-TRACKER-GATE: this step copies COMPLIANCE's gate, not ATTRIBUTION's.
+ * Attribution is Advanced-only because it silently rewrites git metadata; a
+ * wrong tracker provider is immediately visible and trivially reversible, while
+ * a user who never sees the question silently gets `github` — invisible to
+ * exactly the Jira/Linear user the question exists for. Compliance's signature
+ * is also the only one already carrying `hasCliOverride`, which `--tracker`
+ * needs.
+ */
+import { clackNote, clackSelect } from './prompt-io.js';
+import { DEFAULT_TRACKER_PROVIDER, TRACKER_PROVIDERS, } from '../../core/tracker.js';
+// ── Shared prompt content ──────────────────────────────────────────────────────
+/** Message shown on the tracker provider select prompt. */
+export const TRACKER_SELECT_MESSAGE = 'Issue tracker for this machine';
+/** Build clack select options for the tracker provider list. */
+export function providerChoices() {
+    return TRACKER_PROVIDERS.map(provider => ({
+        value: provider.id,
+        label: provider.label,
+        hint: provider.hint,
+    }));
+}
+/**
+ * Format a padded provider catalogue suitable for a clack note body.
+ * Produces: `  github     — GitHub Issues through the gh CLI`
+ */
+export function formatProviderCatalogue() {
+    return 'Valid provider IDs:\n' +
+        TRACKER_PROVIDERS.map(p => `  ${p.id.padEnd(10)} — ${p.hint}`).join('\n');
+}
+/**
+ * Format tracker state for the Recommended-mode summary line and note header.
+ *
+ * Pure function — no I/O, no side effects. `github` carries the `(default)`
+ * marker so a user reading the summary can tell "I chose this" from "this is
+ * what devflow does when nobody chooses".
+ */
+export function formatTrackerSummary(provider) {
+    return provider === DEFAULT_TRACKER_PROVIDER ? `${provider} (default)` : provider;
+}
+// ── Gate predicate ─────────────────────────────────────────────────────────────
+/**
+ * Determines whether the tracker wizard step should run for a given init invocation.
+ *
+ * Gate table (per PF-029: key on modePromptShown, never on the mode name):
+ *
+ *   --recommended flag / !isTTY fallback             → no (promptless contract preserved)
+ *   Interactive mode-prompt → Recommended            → yes (modePromptShown=true)
+ *   --advanced flag / re-init (banner path)          → yes (mode='advanced', isTTY=true)
+ *   Interactive mode-prompt → Advanced               → yes (modePromptShown=true)
+ *   Any path with --tracker <id>                     → no (hasCliOverride wins)
+ *
+ * BOTH wizard paths call this predicate, so the table above is the single
+ * authority for both and they cannot drift. A Recommended-only wiring would be
+ * dead on every re-init — re-init is Advanced-only by construction.
+ *
+ * Pure predicate — no side effects, fully testable without a TTY.
+ */
+export function shouldRunTrackerStep(input) {
+    if (input.hasCliOverride)
+        return false;
+    if (!input.isTTY)
+        return false;
+    // Advanced path: non-TTY has already exit-1'd, so isTTY=true here → always run.
+    // Covers: --advanced flag, re-init banner path, interactive-prompt → advanced.
+    if (input.mode === 'advanced')
+        return true;
+    // Recommended path: only run when the Setup-mode p.select actually ran
+    // (user made an active choice). --recommended flag and !isTTY fallback never set
+    // modePromptShown=true, preserving their promptless contracts.
+    return input.modePromptShown;
+}
+/**
+ * Build the real (clack) TrackerPromptIO adapter.
+ * Delegates the shared note + select to the shared adapters (prompt-io.ts).
+ * Translates clack's cancel symbol into the PromptOutcome discriminated union.
+ */
+export function buildClackTrackerPrompts() {
+    return {
+        note: clackNote,
+        select: (opts) => clackSelect(opts),
+        selectProvider: (opts) => clackSelect(opts),
+    };
+}
+/**
+ * Run the tracker wizard step.
+ *
+ * Flow:
+ *   1. Note — "Current setting: …" header then the provider catalogue.
+ *   2. Provider select — labelled GitHub / Jira / Linear with hints, seeded from
+ *      the prior state. `p.select`, never `p.confirm`: Enter-through must be an
+ *      INFORMED keep of a named provider, not a y/N reflex (PF-029).
+ *
+ * Returns:
+ *   {kind:'resolved', state, messages} — step completed; `state` is the chosen
+ *     TrackerFeatureState; `messages` are emitted by the caller.
+ *   {kind:'cancelled'} — user pressed Escape; caller runs p.cancel + process.exit(0).
+ *
+ * Invariants (PF-014):
+ *   - Never calls process.exit(), never throws.
+ *   - The returned state is always a fresh object, never the seed.
+ *   - All I/O is routed through the `prompts` parameter (injectable for tests).
+ */
+export async function runTrackerStep(opts) {
+    const { seed, prompts } = opts;
+    prompts.note(`Current setting: ${formatTrackerSummary(seed.provider)}\n\n` +
+        'Selects which issue tracker devflow reads and writes when a workflow\n' +
+        'needs an issue. GitHub is the default and needs no extra setup.\n' +
+        'Jira and Linear learn your project\'s issue conventions in the\n' +
+        'background at the next session start; pull requests stay on GitHub\n' +
+        'either way.\n\n' +
+        formatProviderCatalogue(), 'Issue tracker');
+    const outcome = await prompts.selectProvider({
+        message: TRACKER_SELECT_MESSAGE,
+        options: providerChoices(),
+        initialValue: seed.provider,
+    });
+    if (outcome.kind === 'cancel')
+        return { kind: 'cancelled' };
+    const provider = outcome.value;
+    return {
+        kind: 'resolved',
+        // Fresh object — never alias the seed the caller still holds.
+        state: { provider },
+        messages: [
+            provider === DEFAULT_TRACKER_PROVIDER
+                ? { level: 'info', text: `Tracker: ${provider} (default) — change later with devflow tracker --set <id>` }
+                : { level: 'success', text: `Tracker: ${provider}` },
+        ],
+    };
+}
+//# sourceMappingURL=tracker-prompts.js.map