session-orchestrator 3.16.0

package/scripts/run-migrate-v2-cross-repo.mjs

@@ -0,0 +1,385 @@
+#!/usr/bin/env node
+/**
+ * run-migrate-v2-cross-repo.mjs — cross-repo Migrate-CLI v2 runner.
+ *
+ * Walks a list of repos, applies the v2 migration to each repo's learnings.jsonl,
+ * and reports pre/post invalid-rate per repo.
+ *
+ * Usage:
+ *   node scripts/run-migrate-v2-cross-repo.mjs [--repos <comma-list>] [--apply] [--json] [--out <path>]
+ *
+ * Flags:
+ *   --repos <comma-list>  Comma-separated repo paths (absolute or ~-prefixed).
+ *                         When omitted, uses the hardcoded ROLLOUT_REPOS list.
+ *   --apply               Write migrated records back to each file (atomic).
+ *                         DEFAULT is dry-run (no writes).
+ *   --json                Output machine-readable JSON instead of Markdown table.
+ *   --out <path>          Write output to file instead of stdout.
+ *
+ * Exit codes:
+ *   0  Success (including repos with no learnings.jsonl — gracefully skipped)
+ *   1  Input/argument error
+ *   2  I/O error
+ */
+
+import { existsSync, readFileSync, writeFileSync, copyFileSync, renameSync } from 'node:fs';
+import { mkdirSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { homedir } from 'node:os';
+import {
+  migrateLegacyLearning,
+  validateLearning,
+} from './lib/learnings.mjs';
+import { getCrossRepoProjects, getConfinementRoot } from './lib/config/cross-repo.mjs';
+import { validatePathInsideProject } from './lib/path-utils.mjs';
+
+const LEARNINGS_REL = '.orchestrator/metrics/learnings.jsonl';
+
+// ---------------------------------------------------------------------------
+// Arg parsing
+// ---------------------------------------------------------------------------
+
+const args = process.argv.slice(2);
+
+const helpFlag = args.includes('--help') || args.includes('-h');
+if (helpFlag) {
+  process.stdout.write(`Usage: run-migrate-v2-cross-repo.mjs [--repos <comma-list>] [--apply] [--json] [--out <path>]
+
+Options:
+  --repos <comma-list>  Comma-separated repo paths (absolute or ~-prefixed).
+                        Defaults to the 16-repo ROLLOUT_REPOS list from #305.
+  --apply               Write migrated files back (default: dry-run, no writes).
+  --json                Emit JSON instead of Markdown table.
+  --out <path>          Write output to file instead of stdout.
+
+Exit codes:  0 success  1 input error  2 I/O error
+`);
+  process.exit(0);
+}
+
+const applyFlag = args.includes('--apply');
+const jsonFlag = args.includes('--json');
+
+const reposIdx = args.indexOf('--repos');
+const reposArg =
+  reposIdx !== -1 && args[reposIdx + 1] ? args[reposIdx + 1] : null;
+
+const outIdx = args.indexOf('--out');
+const outPath =
+  outIdx !== -1 && args[outIdx + 1] ? args[outIdx + 1] : null;
+
+// ---------------------------------------------------------------------------
+// Resolve repos list
+// ---------------------------------------------------------------------------
+
+function resolveHome(p) {
+  if (p.startsWith('~/')) {
+    return join(homedir(), p.slice(2));
+  }
+  return p;
+}
+
+// Resolve the repo list: --repos flag wins; otherwise use Session Config.
+// If neither source provides repos, NO-OP cleanly (exit 0).
+let repos;
+
+if (reposArg) {
+  repos = reposArg
+    .split(',')
+    .map((r) => r.trim())
+    .filter((r) => r.length > 0)
+    .map(resolveHome);
+
+  if (repos.length === 0) {
+    process.stderr.write('run-migrate-v2: no repos to process\n');
+    process.exit(1);
+  }
+} else {
+  // Config-driven — resolved from the shared cross-repo accessor (#478).
+  const configProjects = await getCrossRepoProjects();
+
+  if (configProjects.length === 0) {
+    process.stderr.write(
+      'cross-repo: no projects configured (set cross-repo.projects in Session Config) — nothing to do.\n'
+    );
+    process.exit(0);
+  }
+
+  const migrateRoot = getConfinementRoot();
+  repos = configProjects
+    .map((r) => r.trim())
+    .filter((r) => r.length > 0)
+    .map(resolveHome)
+    .filter((absPath) => {
+      const guard = validatePathInsideProject(absPath, migrateRoot);
+      if (!guard.ok) {
+        process.stderr.write(
+          `run-migrate-v2: WARN rejecting confined-path violation for ${JSON.stringify(absPath)} (reason: ${guard.reason})\n`
+        );
+        return false;
+      }
+      return true;
+    });
+}
+
+// ---------------------------------------------------------------------------
+// Per-repo migration logic
+// ---------------------------------------------------------------------------
+
+/**
+ * @typedef {Object} RepoResult
+ * @property {string} repo       - absolute repo path
+ * @property {string} status     - 'skipped' | 'dry-run' | 'applied' | 'error'
+ * @property {number} total      - total records parsed
+ * @property {number} invalidPre - invalid records before migration
+ * @property {number} invalidPost - invalid records after migration
+ * @property {number} fixedByV2  - records that became valid after migration
+ * @property {number} malformed  - JSON-parse failures (preserved, not counted in invalid)
+ * @property {string|null} error  - error message if status=error
+ */
+
+/**
+ * Process a single repo. Returns a RepoResult.
+ *
+ * @param {string} repoPath - resolved absolute path to the repo
+ * @param {boolean} apply   - whether to write changes back
+ * @returns {RepoResult}
+ */
+function processRepo(repoPath, apply) {
+  const learningsPath = join(repoPath, LEARNINGS_REL);
+
+  if (!existsSync(learningsPath)) {
+    return {
+      repo: repoPath,
+      status: 'skipped',
+      total: 0,
+      invalidPre: 0,
+      invalidPost: 0,
+      fixedByV2: 0,
+      malformed: 0,
+      error: null,
+    };
+  }
+
+  // Read
+  let raw;
+  try {
+    raw = readFileSync(learningsPath, 'utf8');
+  } catch (err) {
+    return {
+      repo: repoPath,
+      status: 'error',
+      total: 0,
+      invalidPre: 0,
+      invalidPost: 0,
+      fixedByV2: 0,
+      malformed: 0,
+      error: `read failed: ${err.message}`,
+    };
+  }
+
+  const lines = raw.split('\n').filter((l) => l.trim().length > 0);
+
+  let malformed = 0;
+  let invalidPre = 0;
+  let invalidPost = 0;
+  let fixedByV2 = 0;
+  const outputLines = [];
+
+  for (const line of lines) {
+    // Parse
+    let parsed;
+    try {
+      parsed = JSON.parse(line);
+    } catch {
+      malformed++;
+      outputLines.push(line); // preserve malformed lines as-is
+      continue;
+    }
+
+    // Pre-migration validity check
+    let wasValidPre = true;
+    try {
+      validateLearning({ ...parsed, schema_version: parsed.schema_version ?? 1 });
+    } catch {
+      wasValidPre = false;
+      invalidPre++;
+    }
+
+    // Migrate
+    const migrated = migrateLegacyLearning(parsed);
+
+    // Post-migration validity check
+    let isValidPost = true;
+    let validatedRecord = migrated;
+    try {
+      validatedRecord = validateLearning({
+        ...migrated,
+        schema_version: migrated.schema_version ?? 1,
+      });
+    } catch {
+      isValidPost = false;
+      invalidPost++;
+    }
+
+    if (!wasValidPre && isValidPost) {
+      fixedByV2++;
+    }
+
+    // Use the migrated+validated record when valid; otherwise fall back to original
+    if (isValidPost) {
+      outputLines.push(JSON.stringify(validatedRecord));
+    } else {
+      // Preserve original line — do not discard records that still fail validation
+      outputLines.push(line);
+    }
+  }
+
+  const total = lines.length - malformed;
+
+  // Write (--apply only)
+  if (apply) {
+    const timestamp = Date.now();
+    const backupPath = `${learningsPath}.bak-cross-repo-migrate-${timestamp}`;
+    try {
+      // Backup original
+      copyFileSync(learningsPath, backupPath);
+      // Write migrated content atomically
+      const body = outputLines.join('\n') + '\n';
+      const tmpPath = `${learningsPath}.migrate-cross-repo-tmp-${process.pid}-${timestamp}`;
+      mkdirSync(dirname(learningsPath), { recursive: true });
+      writeFileSync(tmpPath, body, 'utf8');
+      renameSync(tmpPath, learningsPath);
+    } catch (err) {
+      return {
+        repo: repoPath,
+        status: 'error',
+        total,
+        invalidPre,
+        invalidPost,
+        fixedByV2,
+        malformed,
+        error: `write failed: ${err.message}`,
+      };
+    }
+  }
+
+  return {
+    repo: repoPath,
+    status: apply ? 'applied' : 'dry-run',
+    total,
+    invalidPre,
+    invalidPost,
+    fixedByV2,
+    malformed,
+    error: null,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Run across all repos
+// ---------------------------------------------------------------------------
+
+const results = repos.map((r) => processRepo(r, applyFlag));
+
+// ---------------------------------------------------------------------------
+// Aggregate
+// ---------------------------------------------------------------------------
+
+const aggregate = results.reduce(
+  (acc, r) => {
+    acc.totalRecords += r.total;
+    acc.totalFixedByV2 += r.fixedByV2;
+    acc.totalStillInvalidPost += r.invalidPost;
+    acc.totalMalformed += r.malformed;
+    acc.totalReposProcessed += r.status !== 'skipped' ? 1 : 0;
+    acc.totalReposSkipped += r.status === 'skipped' ? 1 : 0;
+    return acc;
+  },
+  {
+    totalRecords: 0,
+    totalFixedByV2: 0,
+    totalStillInvalidPost: 0,
+    totalMalformed: 0,
+    totalReposProcessed: 0,
+    totalReposSkipped: 0,
+  }
+);
+
+// ---------------------------------------------------------------------------
+// Format output
+// ---------------------------------------------------------------------------
+
+function repoName(absPath) {
+  return absPath.split('/').pop() ?? absPath;
+}
+
+function fmtPct(count, total) {
+  if (total === 0) return '—';
+  return `${count} (${((count / total) * 100).toFixed(1)}%)`;
+}
+
+function buildMarkdown(results, aggregate, mode) {
+  const lines = [];
+  lines.push(`# Cross-Repo Migrate-CLI v2 — ${mode} report`);
+  lines.push('');
+  lines.push(
+    '| Repo | Total | Invalid pre | Invalid post | Fixed by v2 | Malformed | Status |'
+  );
+  lines.push(
+    '|------|-------|-------------|--------------|-------------|-----------|--------|'
+  );
+  for (const r of results) {
+    const name = repoName(r.repo);
+    lines.push(
+      `| ${name} | ${r.total} | ${fmtPct(r.invalidPre, r.total)} | ${fmtPct(r.invalidPost, r.total)} | ${r.fixedByV2} | ${r.malformed} | ${r.status}${r.error ? `: ${r.error}` : ''} |`
+    );
+  }
+  lines.push('');
+  lines.push('## Aggregate');
+  lines.push('');
+  lines.push(`- Total records: **${aggregate.totalRecords}**`);
+  lines.push(`- Fixed by v2 migration: **${aggregate.totalFixedByV2}**`);
+  lines.push(`- Still invalid post-v2: **${aggregate.totalStillInvalidPost}**`);
+  lines.push(`- Malformed (unparseable): **${aggregate.totalMalformed}**`);
+  lines.push(`- Repos processed: **${aggregate.totalReposProcessed}**`);
+  lines.push(`- Repos skipped (no learnings.jsonl): **${aggregate.totalReposSkipped}**`);
+  lines.push('');
+  return lines.join('\n');
+}
+
+function buildJson(results, aggregate, mode) {
+  return JSON.stringify({ mode, repos: results, aggregate }, null, 2);
+}
+
+const mode = applyFlag ? 'apply' : 'dry-run';
+const output = jsonFlag
+  ? buildJson(results, aggregate, mode)
+  : buildMarkdown(results, aggregate, mode);
+
+// ---------------------------------------------------------------------------
+// Emit output
+// ---------------------------------------------------------------------------
+
+if (outPath) {
+  try {
+    mkdirSync(dirname(outPath), { recursive: true });
+    writeFileSync(outPath, output, 'utf8');
+    process.stderr.write(`run-migrate-v2: output written to ${outPath}\n`);
+  } catch (err) {
+    process.stderr.write(`run-migrate-v2: ERROR writing output to ${outPath}: ${err.message}\n`);
+    process.exit(2);
+  }
+} else {
+  process.stdout.write(output + '\n');
+}
+
+// Summary to stderr
+process.stderr.write(
+  `run-migrate-v2: [${mode}] ${aggregate.totalReposProcessed} processed, ` +
+    `${aggregate.totalReposSkipped} skipped, ` +
+    `${aggregate.totalFixedByV2} fixed-by-v2, ` +
+    `${aggregate.totalStillInvalidPost} still-invalid\n`
+);
+
+process.exit(0);

package/scripts/run-quality-gate.mjs

@@ -0,0 +1,216 @@
+#!/usr/bin/env node
+/**
+ * run-quality-gate.mjs — Run quality gate checks and output structured JSON results.
+ * Port of run-quality-gate.sh (issue #218). Preserves all 4 variants and the same
+ * CLI surface / JSON output shape / exit codes.
+ *
+ * Usage:
+ *   node scripts/run-quality-gate.mjs --variant <variant> [options]
+ *
+ * Flags:
+ *   --variant <v>            Required. baseline | incremental | full-gate | per-file
+ *   --config <json-or-file>  Config JSON string or path to JSON file
+ *                            (from parse-config output). When omitted, command
+ *                            defaults from the policy file or built-in defaults apply.
+ *   --files <f1,f2,...>      Comma-separated file list (incremental + per-file).
+ *   --session-start-ref <r>  Git ref for diff base (incremental, to find changed files).
+ *   -h, --help               Show this help and exit.
+ *
+ * Exit codes:
+ *   0 — pass (or informational; non-blocking variants always exit 0)
+ *   1 — script error (bad arguments, missing dependencies)
+ *   2 — gate failed (full-gate only: typecheck/test/lint errors)
+ *
+ * The gate sub-scripts in scripts/lib/gates/ are NOT reimplemented here; they are
+ * invoked via child_process.spawn('bash', [path, ...]) with the required env vars.
+ *
+ * References:
+ *   scripts/run-quality-gate.sh                  — original shell orchestrator
+ *   scripts/lib/quality-gates-policy.mjs         — loadQualityGatesPolicy, resolveCommand
+ *   scripts/lib/common.mjs                       — die, warn, findProjectRoot
+ *   scripts/lib/gates/gate-{baseline,incremental,full,per-file}.mjs
+ */
+
+import { existsSync, readFileSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { spawnSync } from 'node:child_process';
+
+import { die, warn } from './lib/common.mjs';
+import { loadQualityGatesPolicy, resolveCommand } from './lib/quality-gates-policy.mjs';
+import { emitEvent } from './lib/events.mjs';
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const GATES_DIR = join(__dirname, 'lib', 'gates');
+
+const VALID_VARIANTS = ['baseline', 'incremental', 'full-gate', 'per-file'];
+
+const DEFAULT_TEST_CMD = 'npm test';
+const DEFAULT_TYPECHECK_CMD = 'npm run typecheck';
+const DEFAULT_LINT_CMD = 'npm run lint';
+
+// Gate sub-script mapping
+const GATE_SCRIPT = {
+  baseline:    join(GATES_DIR, 'gate-baseline.mjs'),
+  incremental: join(GATES_DIR, 'gate-incremental.mjs'),
+  'full-gate': join(GATES_DIR, 'gate-full.mjs'),
+  'per-file':  join(GATES_DIR, 'gate-per-file.mjs'),
+};
+
+// ---------------------------------------------------------------------------
+// Argument parsing
+// ---------------------------------------------------------------------------
+
+const argv = process.argv.slice(2);
+
+if (argv.includes('-h') || argv.includes('--help')) {
+  process.stdout.write(
+    'Usage: run-quality-gate.mjs --variant <variant> [--config <json-or-file>] ' +
+    '[--files <file1,file2,...>] [--session-start-ref <ref>]\n\n' +
+    'Variants: baseline, incremental, full-gate, per-file\n\n' +
+    'Exit codes:\n' +
+    '  0 — pass (non-blocking variants always exit 0)\n' +
+    '  1 — script error (bad arguments, missing dependencies)\n' +
+    '  2 — gate failed (full-gate only)\n',
+  );
+  process.exit(0);
+}
+
+let variant = '';
+let config = '';
+let files = '';
+let sessionStartRef = '';
+
+for (let i = 0; i < argv.length; i++) {
+  const arg = argv[i];
+  switch (arg) {
+    case '--variant':
+      if (i + 1 >= argv.length) die('Missing value for --variant');
+      variant = argv[++i];
+      break;
+    case '--config':
+      if (i + 1 >= argv.length) die('Missing value for --config');
+      config = argv[++i];
+      break;
+    case '--files':
+      if (i + 1 >= argv.length) die('Missing value for --files');
+      files = argv[++i];
+      break;
+    case '--session-start-ref':
+      if (i + 1 >= argv.length) die('Missing value for --session-start-ref');
+      sessionStartRef = argv[++i];
+      break;
+    default:
+      die(`Unknown argument: ${arg}`);
+  }
+}
+
+if (!variant) die('Missing required argument: --variant');
+if (!VALID_VARIANTS.includes(variant)) {
+  die(`Invalid variant: '${variant}' (allowed: ${VALID_VARIANTS.join(', ')})`);
+}
+
+// ---------------------------------------------------------------------------
+// Command resolution — policy-file-first (#183), then config, then defaults
+// ---------------------------------------------------------------------------
+
+/**
+ * Resolve a command string from:
+ *   1. quality-gates policy file (.orchestrator/policy/quality-gates.json)
+ *   2. Session Config passed via --config (JSON string or file path)
+ *   3. Built-in default
+ *
+ * Mirrors extract_command() in run-quality-gate.sh.
+ *
+ * @param {object|null} policy
+ * @param {"test"|"typecheck"|"lint"} policyKey
+ * @param {string} configKey   e.g. "test-command"
+ * @param {object|null} configJson  parsed --config JSON (or null)
+ * @param {string} defaultCmd
+ * @returns {string}
+ */
+function extractCommand(policy, policyKey, configKey, configJson, defaultCmd) {
+  // 1. Policy file takes precedence
+  const fromPolicy = resolveCommand(policy, policyKey, '');
+  if (fromPolicy) return fromPolicy;
+
+  // 2. Session Config
+  if (configJson !== null && typeof configJson === 'object') {
+    const val = configJson[configKey];
+    if (val && typeof val === 'string' && val !== 'null') return val;
+  }
+
+  // 3. Built-in default
+  return defaultCmd;
+}
+
+// Load policy file (never throws)
+const repoRoot = process.cwd();
+const policy = loadQualityGatesPolicy(repoRoot);
+
+// Parse --config (JSON string or file path)
+let configJson = null;
+if (config) {
+  if (existsSync(config)) {
+    try {
+      configJson = JSON.parse(readFileSync(config, 'utf8'));
+    } catch (err) {
+      warn(`Could not parse config file '${config}': ${err.message}; using defaults`);
+    }
+  } else {
+    try {
+      configJson = JSON.parse(config);
+    } catch {
+      warn('Config is neither a valid file path nor valid JSON; using defaults');
+    }
+  }
+}
+
+const TYPECHECK_CMD = extractCommand(policy, 'typecheck', 'typecheck-command', configJson, DEFAULT_TYPECHECK_CMD);
+const TEST_CMD      = extractCommand(policy, 'test',      'test-command',      configJson, DEFAULT_TEST_CMD);
+const LINT_CMD      = extractCommand(policy, 'lint',      'lint-command',      configJson, DEFAULT_LINT_CMD);
+
+// ---------------------------------------------------------------------------
+// Gate dispatch — shell-out to existing gate-*.mjs sub-scripts
+// ---------------------------------------------------------------------------
+
+const gatePath = GATE_SCRIPT[variant];
+
+if (!existsSync(gatePath)) {
+  die(`Gate script not found: ${gatePath}`);
+}
+
+const env = {
+  ...process.env,
+  TYPECHECK_CMD,
+  TEST_CMD,
+  LINT_CMD,
+  FILES: files,
+  SESSION_START_REF: sessionStartRef,
+};
+
+const result = spawnSync('node', [gatePath], {
+  env,
+  stdio: 'inherit',
+});
+
+if (result.error) {
+  die(`Failed to run gate script: ${result.error.message}`);
+}
+
+// Quality-gate telemetry — one canonical event per gate run via emitEvent
+// (single emission path). Best-effort: a telemetry failure must NEVER alter the
+// gate's authoritative exit code.
+const exitCode = result.status ?? 1;
+try {
+  await emitEvent(`orchestrator.quality_gate.${exitCode === 0 ? 'passed' : 'failed'}`, {
+    variant,
+    exit_code: exitCode,
+  });
+} catch { /* best-effort telemetry — gate result is authoritative */ }
+
+process.exit(exitCode);

package/scripts/spikes/h3-agent-teams/preflight.sh

@@ -0,0 +1,53 @@
+#!/usr/bin/env bash
+# preflight.sh — NON-claude smoke test of the H3 hook seam's command contract.
+#
+# Builds the fixture if missing, then runs `npm run --silent typecheck` in both
+# toggle states and asserts the exit codes the TaskCompleted hook depends on:
+#   pass-state → exit 0   (hook would allow completion)
+#   fail-state → exit 2   (hook would BLOCK completion)
+#
+# This validates the seam's command contract WITHOUT spawning any claude
+# session — only node/npm in /tmp. Exit 0 iff both assertions pass.
+set -uo pipefail
+
+HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+FIXTURE="/tmp/h3-agent-teams-test"
+FAILED=0
+
+echo "=== H3 preflight — hook-seam command contract (no claude session) ==="
+
+# Build fixture if missing.
+if [ ! -f "${FIXTURE}/package.json" ]; then
+  echo "[preflight] fixture missing — running setup.sh"
+  bash "${HERE}/setup.sh"
+fi
+
+run_assert() {
+  local state="$1" expected="$2"
+  bash "${HERE}/toggle.sh" "${state}" >/dev/null
+  local out exit_code
+  out="$(cd "${FIXTURE}" && npm run --silent typecheck 2>&1)"
+  exit_code=$?
+  if [ "${exit_code}" -eq "${expected}" ]; then
+    echo "PASS: ${state}-state → exit ${exit_code} (expected ${expected})  | ${out}"
+  else
+    echo "FAIL: ${state}-state → exit ${exit_code} (expected ${expected})  | ${out}"
+    FAILED=1
+  fi
+}
+
+run_assert pass 0
+run_assert fail 2
+
+# Leave the fixture in PASS state for run 1 (operator toggles to fail before runs 2-3).
+bash "${HERE}/toggle.sh" pass >/dev/null
+
+echo "=== preflight result ==="
+if [ "${FAILED}" -eq 0 ]; then
+  echo "ALL ASSERTIONS PASSED — hook command contract verified (exit 0 pass / exit 2 fail)"
+  echo "Fixture left in PASS state at ${FIXTURE} (ready for run 1)."
+  exit 0
+else
+  echo "ONE OR MORE ASSERTIONS FAILED — do not proceed to the interactive runs."
+  exit 1
+fi