session-orchestrator 3.16.0

package/scripts/lib/config/coercers.mjs

@@ -0,0 +1,248 @@
+/**
+ * coercers.mjs — Value coercion helpers for Session Config parsing.
+ *
+ * Ported from config-json-coercion.sh (v2). Shared by all per-section parsers.
+ * Two functions are exported for external callers (_coerceEnum, _coerceCollisionRisk);
+ * the rest are internal to the config subsystem.
+ */
+
+// ---------------------------------------------------------------------------
+// Internal: raw lookup
+// ---------------------------------------------------------------------------
+
+/**
+ * Look up a key in the parsed KV map; returns the raw string value or the
+ * given default. Last match wins (mirrors the shell `tail -1` behaviour).
+ * @param {Map<string, string>} kv
+ * @param {string} key
+ * @param {string|undefined} def
+ * @returns {string|undefined}
+ */
+export function _getVal(kv, key, def) {
+  const val = kv.get(key);
+  if (val !== undefined) return val;
+  return def;
+}
+
+// ---------------------------------------------------------------------------
+// Coercion helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Coerce a value to a JSON string or null.
+ * @param {Map<string, string>} kv
+ * @param {string} key
+ * @param {string} [def] — omit for null default
+ * @returns {string|null}
+ */
+export function _coerceString(kv, key, def) {
+  const val = _getVal(kv, key, def);
+  if (val === undefined || val === '' || val === 'none' || val === 'null') return null;
+  return val;
+}
+
+/**
+ * Coerce a value to an integer, supporting override syntax "N (k: M)".
+ * @param {Map<string, string>} kv
+ * @param {string} key
+ * @param {number} def
+ * @returns {number | {default: number, [k: string]: number}}
+ */
+export function _coerceInteger(kv, key, def) {
+  const raw = _getVal(kv, key, String(def));
+
+  // Override syntax: "6 (deep: 18)" or "6 (deep: 18, fast: 4)"
+  const overrideMatch = raw.match(/^(\d+)\s*\(([^)]+)\)\s*$/);
+  if (overrideMatch) {
+    const base = parseInt(overrideMatch[1], 10);
+    if (isNaN(base)) throw new Error(`config.mjs: invalid integer base for '${key}': '${raw}'`);
+    const overridesStr = overrideMatch[2];
+    const result = { default: base };
+    for (const pair of overridesStr.split(',')) {
+      const colonIdx = pair.indexOf(':');
+      if (colonIdx === -1) continue;
+      const okey = pair.slice(0, colonIdx).trim();
+      const oval = pair.slice(colonIdx + 1).trim();
+      const oint = parseInt(oval, 10);
+      if (isNaN(oint) || !/^\d+$/.test(oval)) {
+        throw new Error(`config.mjs: invalid integer override for '${key}.${okey}': '${oval}'`);
+      }
+      result[okey] = oint;
+    }
+    return result;
+  }
+
+  if (!/^\d+$/.test(raw)) {
+    throw new Error(`config.mjs: invalid integer for '${key}': '${raw}'`);
+  }
+  return parseInt(raw, 10);
+}
+
+/**
+ * Coerce a value to a float with optional bounds.
+ * @param {Map<string, string>} kv
+ * @param {string} key
+ * @param {number} def
+ * @param {number} [min]
+ * @param {number} [max] — exclusive upper bound
+ * @returns {number}
+ */
+export function _coerceFloat(kv, key, def, min, max) {
+  const raw = _getVal(kv, key, String(def));
+
+  if (!/^\d+(\.\d+)?$/.test(raw)) {
+    throw new Error(`config.mjs: invalid float for '${key}': '${raw}' (expected non-negative number)`);
+  }
+  const val = parseFloat(raw);
+
+  if (min !== undefined && val < min) {
+    throw new Error(`config.mjs: float '${key}' value '${raw}' is below minimum '${min}'`);
+  }
+  if (max !== undefined && val >= max) {
+    throw new Error(`config.mjs: float '${key}' value '${raw}' must be less than '${max}'`);
+  }
+  return val;
+}
+
+/**
+ * Coerce a value to a boolean.
+ * @param {Map<string, string>} kv
+ * @param {string} key
+ * @param {boolean} def
+ * @returns {boolean}
+ */
+export function _coerceBoolean(kv, key, def) {
+  const raw = _getVal(kv, key, def ? 'true' : 'false');
+  const lower = raw.toLowerCase();
+  if (lower === 'true') return true;
+  if (lower === 'false') return false;
+  throw new Error(`config.mjs: invalid boolean for '${key}': '${raw}' (expected true or false)`);
+}
+
+/**
+ * Coerce a value to a JSON array of strings, or null.
+ * Handles "[a, b, c]", "a, b, c", "[]", "none", or absent (null).
+ * @param {Map<string, string>} kv
+ * @param {string} key
+ * @param {string|null} [def] — raw default string like "[all]" or "[]"
+ * @returns {string[]|null}
+ */
+export function _coerceList(kv, key, def) {
+  const raw = _getVal(kv, key, def !== undefined ? def : undefined);
+
+  if (raw === undefined || raw === 'none' || raw === 'null') return null;
+
+  // Strip surrounding brackets
+  const stripped = raw.replace(/^\s*\[/, '').replace(/\]\s*$/, '').trim();
+
+  if (stripped === '') return [];
+
+  // If value contains '{', bail to null (complex object)
+  if (stripped.includes('{')) return null;
+
+  const items = stripped.split(',').map(s => s.trim()).filter(s => s.length > 0);
+  return items;
+}
+
+/**
+ * Coerce a value to an enum string (lower-cased), throw on invalid.
+ * @param {Map<string, string>} kv
+ * @param {string} key
+ * @param {string} def
+ * @param {string[]} allowed
+ * @returns {string}
+ */
+export function _coerceEnum(kv, key, def, allowed) {
+  const raw = _getVal(kv, key, def);
+  const lower = raw.toLowerCase();
+  if (!allowed.includes(lower)) {
+    throw new Error(`config.mjs: ${key} must be ${allowed.join('|')}, got '${raw}'`);
+  }
+  return lower;
+}
+
+/**
+ * Validate and normalise a collision-risk value from plan output JSON.
+ * Returns the default when value is null/undefined; throws TypeError on invalid.
+ * @param {*} value
+ * @param {string} [def='low']
+ * @returns {'low'|'medium'|'high'}
+ */
+export function _coerceCollisionRisk(value, def = 'low') {
+  const ALLOWED = ['low', 'medium', 'high'];
+  if (value === null || value === undefined) return def;
+  const lower = String(value).toLowerCase();
+  if (!ALLOWED.includes(lower)) {
+    throw new TypeError(`_coerceCollisionRisk: must be low|medium|high, got '${value}'`);
+  }
+  return lower;
+}
+
+/**
+ * Coerce a value to a plain object of string values, or null.
+ * Handles "{ key1: val1, key2: val2 }".
+ * @param {Map<string, string>} kv
+ * @param {string} key
+ * @returns {Record<string,string>|null}
+ */
+export function _coerceObject(kv, key) {
+  const raw = _getVal(kv, key, undefined);
+  if (raw === undefined || raw === 'none' || raw === 'null') return null;
+
+  const stripped = raw.replace(/^\s*\{/, '').replace(/\}\s*$/, '').trim();
+  if (stripped === '') return null;
+
+  const result = {};
+  for (const pair of stripped.split(',')) {
+    const colonIdx = pair.indexOf(':');
+    if (colonIdx === -1) continue;
+    const k = pair.slice(0, colonIdx).trim();
+    const v = pair.slice(colonIdx + 1).trim();
+    if (k) result[k] = v;
+  }
+  return Object.keys(result).length === 0 ? null : result;
+}
+
+/**
+ * Coerce a value to an object of boolean values (for enforcement-gates).
+ * @param {Map<string, string>} kv
+ * @param {string} key
+ * @returns {Record<string,boolean>|null}
+ */
+export function _coerceBoolObject(kv, key) {
+  const raw = _getVal(kv, key, undefined);
+  if (raw === undefined || raw === 'none' || raw === 'null') return null;
+
+  const stripped = raw.replace(/^\s*\{/, '').replace(/\}\s*$/, '').trim();
+  if (stripped === '') return null;
+
+  const result = {};
+  for (const pair of stripped.split(',')) {
+    const colonIdx = pair.indexOf(':');
+    if (colonIdx === -1) continue;
+    const k = pair.slice(0, colonIdx).trim();
+    const v = pair.slice(colonIdx + 1).trim().toLowerCase();
+    if (!k) continue;
+    if (v === 'true') result[k] = true;
+    else if (v === 'false') result[k] = false;
+    else throw new Error(`config.mjs: invalid enforcement-gates value for '${k}': '${v}' (must be true or false)`);
+  }
+  return Object.keys(result).length === 0 ? null : result;
+}
+
+/**
+ * Coerce max-turns: positive integer or "auto".
+ * @param {Map<string, string>} kv
+ * @returns {number|string}
+ */
+export function _coerceMaxTurns(kv) {
+  const raw = _getVal(kv, 'max-turns', 'auto');
+  const lower = raw.toLowerCase();
+  if (lower === 'auto') return 'auto';
+  if (/^\d+$/.test(raw)) {
+    const n = parseInt(raw, 10);
+    if (n <= 0) throw new Error(`config.mjs: invalid max-turns: '${raw}' (must be positive integer or 'auto')`);
+    return n;
+  }
+  throw new Error(`config.mjs: invalid max-turns: '${raw}' (must be positive integer or 'auto')`);
+}

package/scripts/lib/config/cold-start.mjs

@@ -0,0 +1,92 @@
+import { matchBlockHeader } from './block-header.mjs';
+
+/**
+ * cold-start.mjs — Parser for the top-level `cold-start:` YAML block (PRD F1.3 /
+ * issue #500). Drives the cold-start detector that nudges operators about long
+ * idle periods or memory silence.
+ *
+ * Returns `{ enabled, "nudge-after-hours", "silence-after-sessions" }`.
+ * Tolerant parser: malformed values silently fall back to defaults.
+ *
+ * Consumer: `scripts/lib/cold-start-detector.mjs` (I2's code).
+ */
+
+/**
+ * Parse the top-level `cold-start:` YAML block from markdown content.
+ * Independent of the `## Session Config` section boundary.
+ *
+ * Defaults:
+ *   enabled:                  true
+ *   nudge-after-hours:        1 (integer ≥ 0)
+ *   silence-after-sessions:   1 (integer ≥ 0)
+ *
+ * @param {string} content — full file contents
+ * @returns {{ enabled: boolean, "nudge-after-hours": number, "silence-after-sessions": number }}
+ */
+export function _parseColdStart(content) {
+  const defaults = {
+    enabled: true,
+    'nudge-after-hours': 1,
+    'silence-after-sessions': 1,
+  };
+
+  const lines = content.split(/\r?\n/);
+  let inBlock = false;
+  const blockLines = [];
+
+  for (const rawLine of lines) {
+    const line = rawLine.replace(/\r$/, '');
+    if (!inBlock) {
+      if (matchBlockHeader(line, 'cold-start')) inBlock = true;
+      continue;
+    }
+    if (line.length > 0 && !/^\s/.test(line)) break;
+    blockLines.push(line);
+  }
+
+  if (blockLines.length === 0) return defaults;
+
+  let csEnabled = true;
+  let csNudgeAfterHours = 1;
+  let csSilenceAfterSessions = 1;
+
+  for (const rawLine of blockLines) {
+    const clean = rawLine.replace(/\s*#.*$/, '').replace(/\s+$/, '');
+    if (!clean.trim()) continue;
+
+    const kvMatch = clean.match(/^\s+([a-zA-Z_-]+):\s*(.*)/);
+    if (!kvMatch) continue;
+
+    const k = kvMatch[1];
+    let v = kvMatch[2].trim();
+    if (v.startsWith('"') && v.endsWith('"') && v.length >= 2) v = v.slice(1, -1);
+    else if (v.startsWith("'") && v.endsWith("'") && v.length >= 2) v = v.slice(1, -1);
+
+    switch (k) {
+      case 'enabled':
+        // Default is true → only flip to false on explicit "false"
+        csEnabled = v.toLowerCase() !== 'false';
+        break;
+      case 'nudge-after-hours': {
+        if (/^\d+$/.test(v)) {
+          const n = parseInt(v, 10);
+          if (n >= 0) csNudgeAfterHours = n;
+        }
+        break;
+      }
+      case 'silence-after-sessions': {
+        if (/^\d+$/.test(v)) {
+          const n = parseInt(v, 10);
+          if (n >= 0) csSilenceAfterSessions = n;
+        }
+        break;
+      }
+    }
+  }
+
+  return {
+    enabled: csEnabled,
+    'nudge-after-hours': csNudgeAfterHours,
+    'silence-after-sessions': csSilenceAfterSessions,
+  };
+}

package/scripts/lib/config/config-protection.mjs

@@ -0,0 +1,120 @@
+import { matchBlockHeader } from './block-header.mjs';
+
+/**
+ * config-protection.mjs — Parser for the top-level `config-protection:` YAML
+ * block (ecc-analysis / issue #622).
+ *
+ * Drives the PreToolUse Edit|Write guard that intercepts edits to a small
+ * allow-list of quality-gate config files (eslint / vitest / tsconfig /
+ * prettier / commitlint / gitleaks) and WARNs — or, in `strict` mode, blocks —
+ * when an edit LOOSENS a gate (threshold lowered, disable/ignore directive
+ * added, rule removed, gitleaks allowlist widened, tsconfig strictness
+ * relaxed). The edit-tool analogue of the test-the-mock gate-cheating
+ * anti-pattern. First-time creation, tightening, and neutral edits are always
+ * allowed. A `allow-config-weakening: true` Session Config line bypasses the
+ * guard for the session (mirrors `allow-destructive-ops`).
+ *
+ * Returns `{ enabled, mode }`.
+ * Tolerant parser: malformed values silently fall back to defaults.
+ *
+ * Consumer: `hooks/config-protection.mjs`.
+ */
+
+/** Valid `mode` values. Unknown values fall back to the default. */
+const VALID_MODES = new Set(['warn', 'strict']);
+const DEFAULT_MODE = 'warn';
+
+/**
+ * Parse the top-level `config-protection:` YAML block from markdown content.
+ * Independent of the `## Session Config` section boundary (mirrors the other
+ * config parsers in this directory — tolerant, defaults-on-malformed).
+ *
+ * Defaults:
+ *   enabled: true
+ *   mode:    'warn'   (warn → stderr + event + exit 0; strict → block, exit 2)
+ *
+ * @param {string} content — full file contents
+ * @returns {{ enabled: boolean, mode: 'warn'|'strict' }}
+ */
+export function _parseConfigProtection(content) {
+  const defaults = {
+    enabled: true,
+    mode: DEFAULT_MODE,
+  };
+
+  if (typeof content !== 'string' || content.length === 0) return defaults;
+
+  const lines = content.split(/\r?\n/);
+  let inBlock = false;
+  const blockLines = [];
+
+  for (const rawLine of lines) {
+    const line = rawLine.replace(/\r$/, '');
+    if (!inBlock) {
+      if (matchBlockHeader(line, 'config-protection')) inBlock = true;
+      continue;
+    }
+    if (line.length > 0 && !/^\s/.test(line)) break;
+    blockLines.push(line);
+  }
+
+  if (blockLines.length === 0) return defaults;
+
+  let cpEnabled = true;
+  let cpMode = DEFAULT_MODE;
+
+  for (const rawLine of blockLines) {
+    const clean = rawLine.replace(/\s*#.*$/, '').replace(/\s+$/, '');
+    if (!clean.trim()) continue;
+
+    const kvMatch = clean.match(/^\s+([a-zA-Z_-]+):\s*(.*)/);
+    if (!kvMatch) continue;
+
+    const k = kvMatch[1];
+    let v = kvMatch[2].trim();
+    if (v.startsWith('"') && v.endsWith('"') && v.length >= 2) v = v.slice(1, -1);
+    else if (v.startsWith("'") && v.endsWith("'") && v.length >= 2) v = v.slice(1, -1);
+
+    switch (k) {
+      case 'enabled':
+        // Default is true → only flip to false on explicit "false".
+        cpEnabled = v.toLowerCase() !== 'false';
+        break;
+      case 'mode': {
+        const lower = v.toLowerCase();
+        cpMode = VALID_MODES.has(lower) ? lower : DEFAULT_MODE;
+        break;
+      }
+    }
+  }
+
+  return {
+    enabled: cpEnabled,
+    mode: cpMode,
+  };
+}
+
+/**
+ * Detect the per-session bypass `allow-config-weakening: true`. This is a
+ * top-level Session Config line (NOT inside the `config-protection:` block),
+ * mirroring `allow-destructive-ops`. Line-scoped within the `## Session Config`
+ * section, exactly like `pre-bash-destructive-guard.mjs`'s bypass scan.
+ *
+ * @param {string} content — full file contents
+ * @returns {boolean} true when the bypass is explicitly set to `true`
+ */
+export function _isConfigWeakeningAllowed(content) {
+  if (typeof content !== 'string' || content.length === 0) return false;
+
+  const lines = content.split(/\r?\n/);
+  let inConfig = false;
+  for (const line of lines) {
+    if (line === '## Session Config') { inConfig = true; continue; }
+    if (inConfig && /^## /.test(line)) break;
+    if (inConfig) {
+      const m = line.match(/^\s*(?:-\s+\*\*)?allow-config-weakening(?::\*\*)?\s*:\s*(\S+)/);
+      if (m && m[1].toLowerCase() === 'true') return true;
+    }
+  }
+  return false;
+}

package/scripts/lib/config/cross-repo.mjs

@@ -0,0 +1,104 @@
+/**
+ * cross-repo.mjs — Parser for the `cross-repo:` sub-block in Session Config (#469, #478).
+ *
+ * Exports:
+ *   _parseCrossRepo(content)       — PURE, no side effects. Extracts cross-repo.projects from
+ *                                    the top-level `cross-repo:` block in markdown content.
+ *   getCrossRepoProjects(cwd?)     — async accessor: reads config file, parses, returns list.
+ *
+ * Uses block-scanner (not _parseKV) because the dot in "cross-repo.projects" is not
+ * supported by the KV regex. Scans for a `cross-repo:` block and then reads `projects:`.
+ */
+
+// `readConfigFile` is imported from the dependency-free leaf config/io.mjs (a
+// sibling), NOT from config.mjs. This avoids the former length-2 cycle
+// config.mjs ⇄ config/cross-repo.mjs (config.mjs imports `_parseCrossRepo` from
+// here). We deliberately do NOT import `parseSessionConfig` — calling it from
+// `getCrossRepoProjects` would re-run `_parseCrossRepo` (double-parse). By calling
+// `_parseCrossRepo` directly on the raw content we parse exactly once. (issue #664)
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { readConfigFile } from './io.mjs';
+import { matchBlockHeader } from './block-header.mjs';
+
+/**
+ * Resolve the cross-repo confinement root. Defaults to ~/Projects.
+ * Override via CROSS_REPO_CONFINEMENT_ROOT env (test-only — never set in production).
+ *
+ * @returns {string} absolute path
+ */
+export function getConfinementRoot() {
+  const v = process.env.CROSS_REPO_CONFINEMENT_ROOT;
+  return (v && v.trim()) ? v : join(homedir(), 'Projects');
+}
+
+// Allowlist: only characters that are safe in shell contexts and file paths.
+// Rejects entries containing shell metacharacters (;, $, `, |, &, >, <, (, ), space, etc.).
+const SAFE_PATH_RE = /^[A-Za-z0-9._~/-]+$/;
+
+/**
+ * Parse the `cross-repo:` block from markdown content and extract the `projects:` list.
+ *
+ * Behaviour-preserving lift of the IIFE that previously lived in config.mjs.
+ * Scans lines for `cross-repo:` block header, then reads the `projects:` key inside.
+ * Stops scanning at the next non-indented, non-empty line (next top-level YAML key).
+ *
+ * @param {string} content — full CLAUDE.md / AGENTS.md file content
+ * @returns {string[]} list of project paths, or [] when absent/empty/none/null
+ */
+export function _parseCrossRepo(content) {
+  const lines = content.split(/\r?\n/);
+  let inBlock = false;
+
+  for (const rawLine of lines) {
+    const line = rawLine.replace(/\r$/, '');
+
+    if (!inBlock) {
+      if (matchBlockHeader(line, 'cross-repo')) { inBlock = true; }
+      continue;
+    }
+
+    // Stop at next top-level (non-indented, non-empty) key
+    if (line.length > 0 && !/^\s/.test(line)) break;
+
+    const m = line.match(/^\s+projects:\s*(.*)/);
+    if (m) {
+      const raw = m[1].replace(/\s*#.*$/, '').trim();
+      if (!raw || raw === 'none' || raw === 'null') return [];
+      const stripped = raw.replace(/^\s*\[/, '').replace(/\]\s*$/, '').trim();
+      if (stripped === '') return [];
+      // SEAM(#477): per-entry shell-meta validation — reject entries with shell metacharacters.
+      return stripped.split(',').map(s => s.trim()).filter(s => {
+        if (s.length === 0) return false;
+        if (!SAFE_PATH_RE.test(s)) {
+          process.stderr.write(`cross-repo: rejected project entry with shell metacharacter: ${JSON.stringify(s)}\n`);
+          return false;
+        }
+        return true;
+      });
+    }
+  }
+
+  return [];
+}
+
+/**
+ * Load cross-repo.projects from Session Config (CLAUDE.md / AGENTS.md) in the
+ * given working directory (defaults to process.cwd()).
+ *
+ * Returns an empty array when the field is absent or the config file is not found.
+ * Never throws.
+ *
+ * @param {string} [cwd] — directory to search for CLAUDE.md / AGENTS.md
+ * @returns {Promise<string[]>}
+ */
+export async function getCrossRepoProjects(cwd = process.cwd()) {
+  try {
+    const mdContent = await readConfigFile(cwd);
+    // Direct call (not via parseSessionConfig) — avoids the double-parse and tightens
+    // the cycle surface to a single readConfigFile edge. See module-header note.
+    return _parseCrossRepo(mdContent);
+  } catch {
+    return [];
+  }
+}