@ngockhoale/ukit 2.3.14 → 2.3.17

package/src/core/gatewayResilienceEnv.js

@@ -0,0 +1,292 @@
+import fs from 'node:fs/promises';
+import fsSync from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+// Managed defaults that keep Claude Code responsive when it is pointed at a custom
+// gateway (any non-empty ANTHROPIC_BASE_URL). `CLAUDE_CODE_DISABLE_NONSTREAMING_FALLBACK='1'`
+// forces streaming mode so the client never falls back to a non-streaming POST that can
+// stall for minutes waiting for the full response. `CLAUDE_STREAM_IDLE_TIMEOUT_MS='600000'`
+// raises Claude Code's internal idle timeout from its default (the gateway-side keep-alive
+// can sit idle longer than the default when the upstream is slow).
+//
+// These are written ONLY when no user-set value already lives in the project's
+// `.claude/settings.json` env block — never clobber, always preserve. Re-running
+// `ukit install` is a no-op once the keys are in place.
+//
+// Probe order mirrors `templates/.claude/ukit/index/unic-gateway.mjs` (env → project
+// `.claude/settings.json` env → home `~/.claude/settings.json` env) but generalizes to ANY
+// non-empty `ANTHROPIC_BASE_URL`, not only `unicjsc.com`. The runtime template stays
+// scoped to UNIC because that's the lane-routing signal; here we only care that the user
+// is pointed at ANY gateway, so we apply resilience regardless of vendor.
+
+export const GATEWAY_RESILIENCE_ENV_DEFAULTS = Object.freeze({
+  CLAUDE_CODE_DISABLE_NONSTREAMING_FALLBACK: '1',
+  CLAUDE_STREAM_IDLE_TIMEOUT_MS: '600000',
+});
+
+const BASE_URL_ENV_VAR = 'ANTHROPIC_BASE_URL';
+const SETTINGS_RELATIVE_PATH = path.join('.claude', 'settings.json');
+
+function readBaseUrlFromEnvValue(value) {
+  return typeof value === 'string' && value.trim().length > 0 ? value : null;
+}
+
+function readBaseUrlFromEnvBlock(envBlock) {
+  if (!envBlock || typeof envBlock !== 'object' || Array.isArray(envBlock)) {
+    return null;
+  }
+  return readBaseUrlFromEnvValue(envBlock[BASE_URL_ENV_VAR]);
+}
+
+// Sync probe over a settings file. The probe is bounded to two small files at install
+// time (project + home), so a synchronous fs read keeps the detector's call signature
+// simple and matches the task interface contract (`detectCustomGateway` is sync). Errors
+// (ENOENT, EACCES, malformed JSON) are swallowed and treated as "no base URL found here"
+// so a corrupt user file can never crash the detector.
+function readBaseUrlFromSettingsFileSync(settingsPath) {
+  let raw;
+  try {
+    raw = fsSync.readFileSync(settingsPath, 'utf8');
+  } catch {
+    return null;
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return null;
+  }
+  return readBaseUrlFromEnvBlock(parsed?.env);
+}
+
+/**
+ * Detect whether ANY non-empty ANTHROPIC_BASE_URL is in scope, mirroring the probe order of
+ * `templates/.claude/ukit/index/unic-gateway.mjs` but generalized. Probe order is strictly
+ * env → project `.claude/settings.json` → home `~/.claude/settings.json`; first non-empty
+ * hit wins, and the returned `source` tells the caller which one matched.
+ *
+ * Synchronous by contract — the probe reads at most two small settings files via
+ * `fs.readFileSync` (cheap on install; never touches the network). Errors reading or
+ * parsing any file are swallowed so a corrupt settings file cannot crash the detector.
+ *
+ * @param {{ rootDir: string, homeDir: string, env?: object }} options
+ * @returns {{ customGateway: boolean, baseUrl: string|null, source: 'env'|'claude-settings'|null }}
+ */
+export function detectCustomGateway({ rootDir, homeDir, env } = {}) {
+  const envValue = env ? readBaseUrlFromEnvValue(env[BASE_URL_ENV_VAR]) : null;
+  if (envValue) {
+    return { customGateway: true, baseUrl: envValue, source: 'env' };
+  }
+
+  if (rootDir) {
+    const projectSettingsPath = path.join(rootDir, SETTINGS_RELATIVE_PATH);
+    const projectValue = readBaseUrlFromSettingsFileSync(projectSettingsPath);
+    if (projectValue) {
+      return { customGateway: true, baseUrl: projectValue, source: 'claude-settings' };
+    }
+  }
+
+  if (homeDir) {
+    const homeSettingsPath = path.join(homeDir, SETTINGS_RELATIVE_PATH);
+    const homeValue = readBaseUrlFromSettingsFileSync(homeSettingsPath);
+    if (homeValue) {
+      return { customGateway: true, baseUrl: homeValue, source: 'claude-settings' };
+    }
+  }
+
+  return { customGateway: false, baseUrl: null, source: null };
+}
+
+/**
+ * Async variant used by `applyGatewayResilienceEnv` so the settings-file probes can run
+ * without blocking the event loop. Mirrors `detectCustomGateway` exactly; the only
+ * difference is the Promise wrapper for callers that already sit in an async pipeline.
+ */
+export function detectCustomGatewayAsync({ rootDir, homeDir, env } = {}) {
+  return Promise.resolve(detectCustomGateway({ rootDir, homeDir, env }));
+}
+
+function backupPathFor(settingsPath) {
+  return `${settingsPath}.ukit-backup`;
+}
+
+/**
+ * Apply the managed env defaults to the project's `.claude/settings.json` env block when
+ * a custom gateway is detected. Skips a key the user has set to a non-default value —
+ * the contract is "add or already-at-default", never "overwrite".
+ *
+ * @param {{ projectRoot: string, homeDir?: string, env?: object }} options
+ * @returns {Promise<{
+ *   customGateway: boolean,
+ *   source: 'env'|'claude-settings'|null,
+ *   baseUrl: string|null,
+ *   applied: string[],
+ *   unchanged: string[],
+ *   skipped: string[],
+ *   changed: boolean,
+ *   reason?: string,
+ * }>}
+ */
+export async function applyGatewayResilienceEnv({
+  projectRoot,
+  homeDir = os.homedir(),
+  env = process.env,
+} = {}) {
+  const detection = detectCustomGateway({ rootDir: projectRoot, homeDir, env });
+
+  if (!detection.customGateway) {
+    return {
+      customGateway: false,
+      source: null,
+      baseUrl: null,
+      applied: [],
+      unchanged: [],
+      skipped: [],
+      changed: false,
+    };
+  }
+
+  const settingsPath = path.join(projectRoot, SETTINGS_RELATIVE_PATH);
+  await fs.mkdir(path.dirname(settingsPath), { recursive: true });
+
+  let raw;
+  try {
+    raw = await fs.readFile(settingsPath, 'utf8');
+  } catch (error) {
+    if (error && error.code === 'ENOENT') {
+      raw = null;
+    } else {
+      return {
+        ...detection,
+        applied: [],
+        unchanged: [],
+        skipped: [],
+        changed: false,
+        reason: `failed to read settings: ${error?.message ?? String(error)}`,
+      };
+    }
+  }
+
+  let settings;
+  if (raw === null) {
+    settings = {};
+  } else {
+    try {
+      settings = JSON.parse(raw);
+    } catch (error) {
+      return {
+        ...detection,
+        applied: [],
+        unchanged: [],
+        skipped: [],
+        changed: false,
+        reason: `failed to parse settings JSON: ${error?.message ?? String(error)}`,
+      };
+    }
+  }
+
+  if (!settings || typeof settings !== 'object' || Array.isArray(settings)) {
+    return {
+      ...detection,
+      applied: [],
+      unchanged: [],
+      skipped: [],
+      changed: false,
+      reason: 'settings JSON is not an object',
+    };
+  }
+
+  if (!settings.env || typeof settings.env !== 'object' || Array.isArray(settings.env)) {
+    settings.env = {};
+  }
+
+  const applied = [];
+  const unchanged = [];
+  const skipped = [];
+  let mutated = false;
+
+  for (const [key, defaultValue] of Object.entries(GATEWAY_RESILIENCE_ENV_DEFAULTS)) {
+    if (!(key in settings.env)) {
+      settings.env[key] = defaultValue;
+      applied.push(key);
+      mutated = true;
+      continue;
+    }
+    const currentValue = settings.env[key];
+    if (typeof currentValue === 'string' && currentValue === defaultValue) {
+      unchanged.push(key);
+      continue;
+    }
+    // User owns a non-default value — never touch it.
+    skipped.push(key);
+  }
+
+  if (!mutated) {
+    return {
+      ...detection,
+      applied,
+      unchanged,
+      skipped,
+      changed: false,
+    };
+  }
+
+  // Backup-then-write, same convention as `src/core/repairBrokenHooks.js`.
+  if (raw !== null) {
+    await fs.writeFile(backupPathFor(settingsPath), raw, 'utf8');
+  }
+  await fs.writeFile(settingsPath, `${JSON.stringify(settings, null, 2)}\n`, 'utf8');
+
+  return {
+    ...detection,
+    applied,
+    unchanged,
+    skipped,
+    changed: true,
+  };
+}
+
+/**
+ * Human-readable lines for the install report. Empty when nothing was applied and there
+ * is no gateway to report on.
+ */
+export function formatGatewayResilienceReport(report) {
+  if (!report) {
+    return [];
+  }
+
+  const lines = [];
+
+  if (!report.customGateway) {
+    lines.push('No custom gateway detected (ANTHROPIC_BASE_URL unset in env, project, and home settings).');
+    return lines;
+  }
+
+  const sourceLabel = report.source === 'env'
+    ? 'environment'
+    : 'Claude Code settings';
+  lines.push(
+    `Custom gateway detected (${sourceLabel}: ${report.baseUrl}). Writing resilience env defaults to project .claude/settings.json.`,
+  );
+
+  for (const key of report.applied || []) {
+    lines.push(`  - ${key} = ${JSON.stringify(GATEWAY_RESILIENCE_ENV_DEFAULTS[key])} (applied)`);
+  }
+  for (const key of report.unchanged || []) {
+    lines.push(`  - ${key} = ${JSON.stringify(GATEWAY_RESILIENCE_ENV_DEFAULTS[key])} (already set)`);
+  }
+  for (const key of report.skipped || []) {
+    lines.push(`  - ${key} = <user value preserved>`);
+  }
+
+  if (report.changed) {
+    lines.push('Backup: .claude/settings.json.ukit-backup');
+  }
+
+  if (report.reason) {
+    lines.push(`Note: ${report.reason}`);
+  }
+
+  return lines;
+}

package/src/core/runInstallPipeline.js

@@ -13,6 +13,7 @@ import { writeInstallMetadata } from './metadata.js';
 import { cleanupLegacyPaths, migrateLegacyRuntimeRoot } from './migrateLegacy.js';
 import { ensureGitignore } from './ensureGitignore.js';
 import { repairBrokenHooks } from './repairBrokenHooks.js';
+import { applyGatewayResilienceEnv } from './gatewayResilienceEnv.js';
 import { cleanupEmptyParents, readJsonIfExists, removeFileOrLinkOnly, resolveProjectRelativePath } from './fileOps.js';
 
 const AUTO_PRUNE_OBSOLETE_PREFIXES = [
@@ -324,6 +325,14 @@ export async function runInstallPipeline({
     // install) clears it for them. Backups are written next to each settings file.
     const hookRepair = await repairBrokenHooks({ projectRoot: pathConfig.projectRoot });
 
+    // If the project is pointed at any custom gateway (env, project settings, or home
+    // settings), write two managed env defaults that keep Claude Code from stalling on
+    // non-streaming fallback and idle timeouts. Re-running install is a no-op once the
+    // keys are in place.
+    const gatewayResilience = await applyGatewayResilienceEnv({
+      projectRoot: pathConfig.projectRoot,
+    });
+
     await pruneObsoleteManagedPaths({
       installMetaData,
       projectRoot: pathConfig.projectRoot,
@@ -359,6 +368,7 @@ export async function runInstallPipeline({
       rows: toDiffRows(diffResults),
       writes,
       hookRepair,
+      gatewayResilience,
     };
   }
 
@@ -371,5 +381,6 @@ export async function runInstallPipeline({
     rows: toDiffRows(diffResults),
     writes: [],
     hookRepair: { removals: [], files: [] },
+    gatewayResilience: { customGateway: false, reason: 'dry-run' },
   };
 }

package/src/core/taskBudgetValidator.js

@@ -0,0 +1,241 @@
+// taskBudgetValidator.js — TASK-014 / Cycle C12
+//
+// Pure validator + dumb table-driven verification-minutes estimator. Turns the
+// planner's "needs_breakdown" prose rule into a measurable gate that runs BEFORE
+// any task is marked `ready`.
+//
+// Exports:
+//   DEFAULT_CRITERIA              — frozen thresholds used by `validateTaskFile` by default.
+//   VERIFICATION_MINUTE_TABLE     — frozen literal table for `yarn test:release-core` and
+//                                   `node scripts/release/verify-release.mjs`. `yarn vitest run`
+//                                   is NOT in the table — its cost is computed dynamically
+//                                   (0.5 per file argument), see `estimateVerificationMinutes`.
+//   estimateVerificationMinutes   — sums per-command minutes over a verification list.
+//   validateTaskFile              — parses a TASK-xxx.md and returns
+//                                   `{ verdict, reasons: [{ criterion, detail }] }`.
+//
+// Criteria (strictly-greater violation rule):
+//   - target-file-count       : bullet lines under `## Target Files`
+//   - test-case-count         : table rows under `## Test Cases` (excluding header + separator)
+//   - verification-minutes    : `estimateVerificationMinutes` over commands in
+//                                the first ```bash fence under `## Verification Commands`
+//   - investigate-first       : `## Goal` body contains both /investigate/i and /first/i
+//   - missing-field           : required section(s) absent (Goal, Test Cases,
+//                               Verification Commands) — empty / random markdown must
+//                               never crash.
+//
+// Parsing is deliberately markdown-light and dependency-free so the validator can be
+// duplicated byte-for-byte into the shipped CLI twin (templates/.claude/ukit/index/
+// task-budget-validator.mjs) without dragging `src/` into user installs.
+
+export const DEFAULT_CRITERIA = Object.freeze({
+  maxTargetFiles: 3,
+  maxTestCases: 8,
+  maxVerificationMinutes: 10,
+});
+
+export const VERIFICATION_MINUTE_TABLE = Object.freeze({
+  'yarn test:release-core': 3,
+  'node scripts/release/verify-release.mjs': 2,
+});
+
+// Per-command minute estimate. `yarn vitest run` → 0.5 per FILE argument
+// (i.e. per non-flag token after `run`); anything else falls back to 1 flat.
+export function estimateVerificationMinutes(commands) {
+  if (!Array.isArray(commands)) return 0;
+  let total = 0;
+  for (const raw of commands) {
+    const cmd = String(raw || '').trim();
+    if (!cmd) continue;
+    if (Object.prototype.hasOwnProperty.call(VERIFICATION_MINUTE_TABLE, cmd)) {
+      total += VERIFICATION_MINUTE_TABLE[cmd];
+      continue;
+    }
+    if (/^yarn\s+vitest(\s+run)?\b/.test(cmd)) {
+      // 0.5 minutes per non-flag argument after `run` (or after `yarn vitest`).
+      const tokens = cmd.split(/\s+/);
+      const runIdx = tokens.indexOf('run');
+      const tail = runIdx >= 0 ? tokens.slice(runIdx + 1) : tokens.slice(2);
+      const fileArgs = tail.filter((t) => !t.startsWith('-') && t.length > 0);
+      total += fileArgs.length * 0.5;
+      continue;
+    }
+    total += 1;
+  }
+  // Round to 1 decimal place so the summary reason is human-friendly.
+  return Math.round(total * 10) / 10;
+}
+
+// Section helpers. We treat any line starting with `## ` as a new section header.
+// Section bodies run until the next `## ` (or EOF).
+function splitSections(markdown) {
+  const lines = String(markdown || '').split('\n');
+  const sections = new Map(); // heading text → body lines (without the heading line)
+  let currentHeading = null;
+  let buffer = [];
+  for (const line of lines) {
+    const m = /^##\s+(.+?)\s*$/.exec(line);
+    if (m) {
+      if (currentHeading !== null) sections.set(currentHeading, buffer);
+      currentHeading = m[1].trim();
+      buffer = [];
+    } else if (currentHeading !== null) {
+      buffer.push(line);
+    }
+  }
+  if (currentHeading !== null) sections.set(currentHeading, buffer);
+  return sections;
+}
+
+function getSectionBody(sections, name) {
+  if (!sections.has(name)) return null;
+  return sections.get(name).join('\n');
+}
+
+// Count bullets under `## Target Files` — lines whose first non-whitespace char is `- `
+function countTargetFiles(body) {
+  if (body == null) return 0;
+  const lines = body.split('\n');
+  let count = 0;
+  for (const line of lines) {
+    if (/^\s*-\s+\S/.test(line)) count += 1;
+  }
+  return count;
+}
+
+// Count test-case rows under `## Test Cases`. The header row `| # | Loại | ...` and the
+// separator row `|---|-----|...` are both skipped.
+function countTestCases(body) {
+  if (body == null) return 0;
+  const lines = body.split('\n');
+  let count = 0;
+  let sawHeader = false;
+  let sawSeparator = false;
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (!trimmed.startsWith('|')) continue;
+    if (!sawHeader) {
+      sawHeader = true;
+      continue;
+    }
+    if (!sawSeparator && /^\|[-\s|]+\|\s*$/.test(trimmed)) {
+      sawSeparator = true;
+      continue;
+    }
+    count += 1;
+  }
+  return count;
+}
+
+// Extract the first ```bash ... ``` fence under `## Verification Commands` and split
+// into non-empty lines.
+function extractVerificationCommands(body) {
+  if (body == null) return [];
+  const lines = body.split('\n');
+  const fenceStart = /^```\s*bash\s*$/;
+  const fenceEnd = /^```\s*$/;
+  let inFence = false;
+  const out = [];
+  for (const line of lines) {
+    if (!inFence) {
+      if (fenceStart.test(line.trim())) inFence = true;
+      continue;
+    }
+    if (fenceEnd.test(line.trim())) break;
+    out.push(line);
+  }
+  return out.map((l) => l.trim()).filter(Boolean);
+}
+
+// Trim the Goal body — strip code fences, blank lines, leading whitespace noise so
+// the investigate/first regex sees prose only.
+function goalText(body) {
+  if (body == null) return '';
+  return body
+    .split('\n')
+    .map((l) => l.replace(/^#+\s*/, '').trim())
+    .filter(Boolean)
+    .join(' ');
+}
+
+export function validateTaskFile(markdown, criteria = DEFAULT_CRITERIA) {
+  const reasons = [];
+
+  // Defensive: any non-string input is treated as empty markdown. Validator must never
+  // throw — it's an advisory gate that downstream agents and the shipped CLI both rely on.
+  const text = typeof markdown === 'string' ? markdown : '';
+  const sections = splitSections(text);
+
+  const goalBody = getSectionBody(sections, 'Goal');
+  const targetBody = getSectionBody(sections, 'Target Files');
+  const testBody = getSectionBody(sections, 'Test Cases');
+  const verifyBody = getSectionBody(sections, 'Verification Commands');
+
+  // missing-field — only the sections that carry real gate semantics are required.
+  // Acceptance / Test Files are not gate-bearing.
+  const requiredSections = [
+    ['Goal', goalBody],
+    ['Test Cases', testBody],
+    ['Verification Commands', verifyBody],
+  ];
+  for (const [name, body] of requiredSections) {
+    if (body == null || body.trim() === '') {
+      reasons.push({
+        criterion: 'missing-field',
+        detail: `required section \`## ${name}\` is missing or empty`,
+      });
+    }
+  }
+
+  // target-file-count
+  if (targetBody != null) {
+    const n = countTargetFiles(targetBody);
+    if (n > criteria.maxTargetFiles) {
+      reasons.push({
+        criterion: 'target-file-count',
+        detail: `${n} target files exceeds maxTargetFiles=${criteria.maxTargetFiles}`,
+      });
+    }
+  }
+
+  // test-case-count
+  if (testBody != null) {
+    const n = countTestCases(testBody);
+    if (n > criteria.maxTestCases) {
+      reasons.push({
+        criterion: 'test-case-count',
+        detail: `${n} test cases exceeds maxTestCases=${criteria.maxTestCases}`,
+      });
+    }
+  }
+
+  // verification-minutes — only count when we actually have commands to score.
+  if (verifyBody != null) {
+    const commands = extractVerificationCommands(verifyBody);
+    if (commands.length > 0) {
+      const minutes = estimateVerificationMinutes(commands);
+      if (minutes > criteria.maxVerificationMinutes) {
+        reasons.push({
+          criterion: 'verification-minutes',
+          detail: `estimated ${minutes} verification minutes exceeds maxVerificationMinutes=${criteria.maxVerificationMinutes}`,
+        });
+      }
+    }
+  }
+
+  // investigate-first — regex pair, per Discussion 2026-09-12 (intentionally dumb).
+  if (goalBody != null) {
+    const prose = goalText(goalBody);
+    if (/\binvestigate\b/i.test(prose) && /\bfirst\b/i.test(prose)) {
+      reasons.push({
+        criterion: 'investigate-first',
+        detail: 'Goal contains both "investigate" and "first" — split the task into a spike + a build step',
+      });
+    }
+  }
+
+  return {
+    verdict: reasons.length === 0 ? 'ok' : 'needs_breakdown',
+    reasons,
+  };
+}