devflow-kit 2.3.0 → 2.5.0

package/dist/core/proxy-state.js

@@ -88,47 +88,75 @@ export async function writeProxyState(devflowDir, state) {
 // Pure helpers
 // ---------------------------------------------------------------------------
 /**
- * Accepted top-level keys for the subswitch 0.2.0 FileConfigSchema (z.strictObject).
- * Unknown top-level keys cause a hard relay startup error — never emit them.
+ * Top-level keys devflow carries into the routing config. Unknown top-level keys
+ * cause a hard relay startup error — never emit them.
  *
- * @D-EFR-4 Subswitch 0.2.0 routing config contract:
- *   FileConfigSchema is a z.strictObject with exactly 5 accepted top-level keys:
- *   port, logLevel, anthropic, providers, limits. Unknown keys cause a hard startup
- *   error — the relay refuses to start. anthropic and limits are themselves
- *   strictObject + prefault({}), so they may be partially specified.
- *
- *   connectTimeoutMs default: subswitch 0.2.0 applies anthropic.connectTimeoutMs
- *   as upstream.setTimeout() at anthropic-passthrough.js:86 — a socket *inactivity*
- *   timeout, not a connect timeout. The 10s default kills any Anthropic request
- *   whose upstream takes >10s to emit the first response byte — routine for long
- *   opus requests (confirmed: 99 spurious 504s clustered at 10004-10098ms while
- *   successful requests ran 25s-99s). Default overridden to 120 000ms; a
- *   user-specified value always wins.
- *
- *   limits.connectTimeoutMs is a registered LEGACY KEY that causes a hard startup
- *   error. Strip it from the limits block when preserving existing config.
+ * @D-EFR-4 Subswitch 0.5.0 routing config contract:
+ *   FileConfigSchema is a z.strictObject with exactly 6 accepted top-level keys:
+ *   port, logLevel, anthropic, providers, limits, codexIngress. Unknown keys cause a
+ *   hard startup error — the relay refuses to start. anthropic and limits are
+ *   themselves strictObject + prefault({}), so they may be partially specified.
+ *   codexIngress is accepted by the relay but deliberately NOT carried: devflow's
+ *   relay serves Claude Code only, and the ingress block would make it accept native
+ *   Codex traffic and hold Claude credentials on devflow's behalf.
  */
 const ROUTING_CONFIG_ALLOWED_TOP_KEYS = new Set([
     'port', 'logLevel', 'anthropic', 'providers', 'limits',
 ]);
-/** Default anthropic.connectTimeoutMs injected when not specified by the user (ms). */
-export const DEFAULT_ANTHROPIC_CONNECT_TIMEOUT_MS = 120_000;
+/**
+ * Sub-keys of a preserved `anthropic` / `limits` block that the pinned relay rejects
+ * outright — each is a registered LEGACY KEY, and a legacy key is a hard startup
+ * error naming its replacement, not a warning. They are stripped when carrying a
+ * user's existing config forward so an upgrade cannot leave the relay unable to boot.
+ *
+ * Every entry was valid under a version devflow previously pinned, which is what makes
+ * it reachable in a real user's file:
+ *   anthropic.streamIdleTimeoutMs — valid in 0.2.0, removed in 0.3.0 (relay no longer
+ *     bounds the stream-idle phase on a connected client).
+ *   limits.connectTimeoutMs       — moved to anthropic.connectTimeoutMs in 0.3.0;
+ *     stripping it loses nothing (relay default governs).
+ *   limits.maxConcurrentRequests  — valid in 0.2.0, removed in 0.3.0 (admission gate
+ *     removed).
+ *   limits.maxBodyBytes           — valid through 0.3.0, renamed to
+ *     limits.maxBufferedBodyBytes in 0.4.0. The old spelling is a registered legacy
+ *     key, so leaving it in place would stop the relay from booting.
+ *   limits.maxUpstreamSockets     — valid in 0.3.0, moved to anthropic.maxUpstreamSockets
+ *     in 0.4.0's providers.* restructure.
+ *   limits.streamIdleTimeoutMs    — valid in 0.3.0, moved to
+ *     providers.codex.streamIdleTimeoutMs in 0.4.0.
+ *   limits.requestTimeoutMs       — valid in 0.3.0, moved to
+ *     providers.codex.requestTimeoutMs in 0.4.0.
+ *   limits.maxSseEventBytes       — valid in 0.3.0, moved to
+ *     providers.codex.maxSseEventBytes in 0.4.0.
+ *
+ * Keys retired before the 0.2.0 baseline are deliberately absent: only keys reachable
+ * in a config written by a previously pinned devflow version belong on this list.
+ */
+const ROUTING_CONFIG_REJECTED_SUBKEYS = {
+    anthropic: ['streamIdleTimeoutMs'],
+    limits: [
+        'connectTimeoutMs',
+        'maxConcurrentRequests',
+        'maxBodyBytes',
+        'maxUpstreamSockets',
+        'streamIdleTimeoutMs',
+        'requestTimeoutMs',
+        'maxSseEventBytes',
+    ],
+};
 /**
  * Build the routing config JSON for ~/.devflow/proxy-routing.json.
  *
  * Authoritatively sets `port`. Preserves any existing valid `anthropic`,
- * `limits`, `logLevel`, and `providers` blocks from `existingContent`,
- * filtering out unknown top-level keys and the legacy `limits.connectTimeoutMs`
- * field (which causes a hard relay startup error in 0.2.0).
- *
- * Injects a default `anthropic.connectTimeoutMs` of 120 000ms when the user
- * has not set one — see @D-EFR-4 for the rationale.
+ * `limits`, `logLevel`, and `providers` blocks from `existingContent`, filtering
+ * out unknown top-level keys and every sub-key in ROUTING_CONFIG_REJECTED_SUBKEYS
+ * (each one a hard relay startup error). No `anthropic` block is injected when
+ * the user has not set one — the relay's own default governs (D-EFR-4).
  *
- * If `existingContent` is missing or malformed, falls back to a clean config
- * with only `port` and `anthropic.connectTimeoutMs`.
+ * If `existingContent` is missing or malformed, falls back to a port-only config.
  *
  * applies ADR-013: pure core-layer function — no I/O.
- * @D-EFR-4: see note above for the strict top-key constraint and timeout rationale.
+ * @D-EFR-4: see note above for the strict top-key constraint.
  */
 export function buildRoutingConfigJson(port, existingContent) {
     // Parse existing config tolerantly; a malformed file falls back to clean defaults.
@@ -138,7 +166,7 @@ export function buildRoutingConfigJson(port, existingContent) {
             const parsed = JSON.parse(existingContent);
             if (typeof parsed === 'object' && parsed !== null && !Array.isArray(parsed)) {
                 for (const [k, v] of Object.entries(parsed)) {
-                    // Only preserve the 5 accepted top-level keys; port is always ours.
+                    // Only preserve the carried top-level keys; port is always ours.
                     if (ROUTING_CONFIG_ALLOWED_TOP_KEYS.has(k) && k !== 'port') {
                         preserved[k] = v;
                     }
@@ -154,30 +182,36 @@ export function buildRoutingConfigJson(port, existingContent) {
     if (preserved.logLevel !== undefined) {
         config.logLevel = preserved.logLevel;
     }
-    // Anthropic block: preserve user settings; inject connectTimeoutMs default when absent.
-    // @D-EFR-4: the 10s upstream inactivity timeout kills long opus requests.
-    const existingAnthropic = typeof preserved.anthropic === 'object' &&
+    // Anthropic block: preserve user settings; strip legacy rejected sub-keys.
+    // No default is injected — the relay's own default governs (D-EFR-4).
+    if (typeof preserved.anthropic === 'object' &&
         preserved.anthropic !== null &&
-        !Array.isArray(preserved.anthropic)
-        ? { ...preserved.anthropic }
-        : {};
-    if (!Object.prototype.hasOwnProperty.call(existingAnthropic, 'connectTimeoutMs')) {
-        existingAnthropic.connectTimeoutMs = DEFAULT_ANTHROPIC_CONNECT_TIMEOUT_MS;
+        !Array.isArray(preserved.anthropic)) {
+        const existingAnthropic = { ...preserved.anthropic };
+        for (const key of ROUTING_CONFIG_REJECTED_SUBKEYS.anthropic) {
+            delete existingAnthropic[key];
+        }
+        if (Object.keys(existingAnthropic).length > 0) {
+            config.anthropic = existingAnthropic;
+        }
     }
-    config.anthropic = existingAnthropic;
     // Preserve providers block if present.
     if (preserved.providers !== undefined) {
         config.providers = preserved.providers;
     }
-    // Preserve limits block if present; strip legacy limits.connectTimeoutMs that
-    // causes a hard startup error in 0.2.0 (use anthropic.connectTimeoutMs instead).
+    // Preserve limits block if present, minus the sub-keys the relay hard-errors on
+    // (see ROUTING_CONFIG_REJECTED_SUBKEYS).
     if (preserved.limits !== undefined) {
         if (typeof preserved.limits === 'object' &&
             preserved.limits !== null &&
             !Array.isArray(preserved.limits)) {
             const limitsObj = { ...preserved.limits };
-            delete limitsObj['connectTimeoutMs'];
-            config.limits = limitsObj;
+            for (const key of ROUTING_CONFIG_REJECTED_SUBKEYS.limits) {
+                delete limitsObj[key];
+            }
+            if (Object.keys(limitsObj).length > 0) {
+                config.limits = limitsObj;
+            }
         }
         else {
             config.limits = preserved.limits;
@@ -210,6 +244,29 @@ export function proxyBaseUrl(port) {
 // ---------------------------------------------------------------------------
 // isProxyEnabled — the primary contract other modules consume
 // ---------------------------------------------------------------------------
+/**
+ * Returns true when ~/.devflow/proxy.json exists on disk — i.e. Devflow has
+ * previously managed the proxy on this machine.
+ *
+ * This is the evidence gate used by init and uninstall before stripping
+ * ANTHROPIC_BASE_URL / CLAUDE_CODE_DISABLE_UNKNOWN_MODEL_WINDOW_ENFORCEMENT:
+ * we only strip those vars when we can prove Devflow wrote them.
+ *
+ * D-STRIP-1: gate proxy env stripping on devflow-managed evidence.
+ *   readProxyState() returns Ok(defaultState) on ENOENT — it cannot distinguish
+ *   "file absent" from "file present with DEFAULT_PROXY_PORT". Callers that need
+ *   to differentiate must use proxyJsonExists() rather than checking the result
+ *   of readProxyState().
+ */
+export async function proxyJsonExists(devflowDir) {
+    try {
+        await fs.access(join(devflowDir, 'proxy.json'));
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
 /**
  * Check whether the Devflow proxy is currently enabled.
  * Returns false when the proxy state file is missing, unreadable, or malformed.

package/dist/core/reference-sweep.js

@@ -0,0 +1,136 @@
+import { promises as fs } from 'fs';
+import * as path from 'path';
+/**
+ * @file reference-sweep.ts
+ *
+ * Path-keyed registry-diff sweep for the generated `devflow:git` reference tree.
+ *
+ * Sibling of {@link sweepOrphanedAssets} in orphan-sweep.ts and deliberately the same
+ * {@link SweepResult} shape — `scanned` is the non-vacuity counter, removals and
+ * per-item failures are reported rather than thrown (avoids PF-009).
+ *
+ * What is genuinely new is the KEY. `sweepOrphanedAssets` keys a flat directory by
+ * registry name through `mdEntryName`, which cannot express `tracker/{provider}/{op}.md`:
+ * two providers may legitimately both carry a `comment.md`, so the registry name has to
+ * be the relative PATH, and the walk has to descend.
+ *
+ * Never writes, only removes (avoids PF-011).
+ */
+/**
+ * Descent bound for every walk over the generated reference tree — this sweep and the
+ * build's own prune, which imports it (`pruneOrphans` in scripts/build-mds.ts). One
+ * tree, one bound: two walkers each carrying their own literal is how they come to
+ * disagree on both the number of levels and what happens at the last one.
+ *
+ * `depth` counts the walked root as 0 and the bound is the deepest directory a walk may
+ * descend INTO, so `depth > MAX_REFERENCE_SWEEP_DEPTH` is the breach — the comparison
+ * the build's walks already use. The installed tree is two levels deep
+ * (`tracker/{provider}/{op}.md`), so 8 is generous. The bound exists because an
+ * unbounded recursion over a directory neither walker owns would spin on a symlink loop
+ * rather than fail — every loop has an explicit upper bound.
+ *
+ * The two walkers answer a breach differently by design, and both answer out loud: the
+ * build throws (a generated tree that deep is a build bug, and dist/ is still the
+ * build's own to fail), while this sweep records the unvisited subtree in `failed`
+ * (avoids PF-009 — an install is not abandoned over one subtree). Neither returns
+ * quietly: a subtree the walk never entered must not be summarised as converged.
+ */
+export const MAX_REFERENCE_SWEEP_DEPTH = 8;
+/**
+ * Remove everything under `root` that the manifest does not name.
+ *
+ * @param root - Directory to converge (the installed `references/tracker/` tree).
+ * @param knownRelPaths - POSIX paths relative to `root` that must survive. Derived from
+ *   the build's own module registries by the caller — never hand-listed.
+ *
+ * @returns A {@link SweepResult} whose `removed` entries are POSIX relative paths. A
+ *   directory into which no manifest path descends is removed WHOLE and reported by its
+ *   own relative path — leaving it empty would be a convergence that stops one step
+ *   short, and an empty provider directory is indistinguishable from a provider whose
+ *   references failed to install. A subtree left unswept because it breached
+ *   {@link MAX_REFERENCE_SWEEP_DEPTH} is reported in `failed` under its own relative
+ *   path, for the same reason: everything this sweep did not converge is named.
+ *
+ * A missing or unreadable `root` is a no-op, not an error: the overlay creates the tree
+ * it converges, so an absent one simply means there is nothing to prune yet.
+ */
+export async function sweepOrphanedReferences(root, knownRelPaths) {
+    const acc = { scanned: 0, removed: [], failed: [] };
+    await sweepDirectory(root, '', 0, knownRelPaths, directoryPrefixes(knownRelPaths), acc);
+    return { scanned: acc.scanned, removed: acc.removed, failed: acc.failed };
+}
+async function sweepDirectory(dir, prefix, depth, known, knownDirPrefixes, acc) {
+    if (depth > MAX_REFERENCE_SWEEP_DEPTH) {
+        // A breached bound means this subtree is never visited, so any orphan inside it
+        // survives. Report it through the same channel as a failed removal: a silent return
+        // would let the install summary claim convergence over ground never covered.
+        acc.failed.push({
+            name: prefix || dir,
+            error: new Error(`${prefix || dir}: sweep descent exceeds the bound of ${MAX_REFERENCE_SWEEP_DEPTH} ` +
+                `levels — this subtree was not swept and any orphans under it survive.`),
+        });
+        return;
+    }
+    let entries;
+    try {
+        entries = await fs.readdir(dir, { withFileTypes: true });
+    }
+    catch {
+        return; /* absent or unreadable — not an error (avoids PF-009) */
+    }
+    for (const entry of entries) {
+        const relPath = prefix === '' ? entry.name : `${prefix}/${entry.name}`;
+        const fullPath = path.join(dir, entry.name);
+        // A real subdirectory is either an ancestor of something the manifest names — in
+        // which case descend — or dead weight, in which case take the whole subtree.
+        // isDirectory() is false for a symlink-to-dir, so a planted link is treated as a
+        // leaf and removed rather than followed.
+        if (entry.isDirectory()) {
+            if (knownDirPrefixes.has(`${relPath}/`)) {
+                await sweepDirectory(fullPath, relPath, depth + 1, known, knownDirPrefixes, acc);
+                continue;
+            }
+            acc.scanned++;
+            try {
+                await fs.rm(fullPath, { recursive: true, force: true });
+                acc.removed.push(relPath);
+            }
+            catch (err) {
+                acc.failed.push({ name: relPath, error: err }); /* per-item isolation (avoids PF-009) */
+            }
+            continue;
+        }
+        acc.scanned++;
+        if (known.has(relPath))
+            continue;
+        try {
+            await fs.rm(fullPath, { force: true });
+            acc.removed.push(relPath);
+        }
+        catch (err) {
+            acc.failed.push({ name: relPath, error: err }); /* per-item isolation (avoids PF-009) */
+        }
+    }
+}
+/**
+ * Every directory prefix some manifest path sits under, trailing slash included:
+ * `tracker/github/comment.md` contributes `tracker/` and `tracker/github/`.
+ *
+ * Built once per sweep so "does anything the manifest names live under this directory?"
+ * costs one `has` per entry instead of a scan of the whole manifest per entry. The
+ * answer is identical to that scan: `dir/` is a member exactly when some manifest path
+ * starts with `dir/`.
+ *
+ * Both loops are bounded by their own input — the inner one walks separators from a
+ * strictly increasing offset, so it terminates at the last one in the path.
+ */
+function directoryPrefixes(known) {
+    const prefixes = new Set();
+    for (const p of known) {
+        for (let cut = p.indexOf('/'); cut !== -1; cut = p.indexOf('/', cut + 1)) {
+            prefixes.add(p.slice(0, cut + 1));
+        }
+    }
+    return prefixes;
+}
+//# sourceMappingURL=reference-sweep.js.map