session-orchestrator 3.16.0

package/scripts/validate-wave-scope.mjs

@@ -0,0 +1,289 @@
+#!/usr/bin/env node
+/**
+ * validate-wave-scope.mjs — Validate .claude/wave-scope.json before enforcement hooks consume it.
+ *
+ * Part of v3.0 Bash→Node migration (Epic #124). Replaces validate-wave-scope.sh
+ * which depended on scripts/lib/common.sh → scripts/lib/platform.sh (removed).
+ *
+ * Usage:
+ *   node scripts/validate-wave-scope.mjs <path-to-wave-scope.json>
+ *   cat wave-scope.json | node scripts/validate-wave-scope.mjs
+ *   node scripts/validate-wave-scope.mjs --assert-subset <agent-filescope.json> < wave-scope.json
+ *
+ * Flags:
+ *   --assert-subset <path>  After schema validation passes, read the agent
+ *                           fileScope file (a JSON array of strings) and assert
+ *                           it is a subset of wave-scope.allowedPaths (#796).
+ *                           Fails (exit 1) with "missing: [...]" on violation.
+ *
+ * Exit codes:
+ *   0 — valid (validated JSON echoed to stdout)
+ *   1 — invalid input / validation failure (error messages written to stderr)
+ *   2 — I/O error (file not found, unreadable stdin, unreadable --assert-subset file)
+ */
+
+import { readFileSync, existsSync, statSync } from 'node:fs';
+import { warn } from './lib/common.mjs';
+import { assertFileScopeSubset } from './lib/scope-gate.mjs';
+
+/**
+ * Write an error to stderr and exit with the given code.
+ * @param {string} msg
+ * @param {number} [code=1]
+ * @returns {never}
+ */
+function die(msg, code = 1) {
+  process.stderr.write(`ERROR: ${msg}\n`);
+  process.exit(code);
+}
+
+/**
+ * Parse CLI flags out of argv, leaving positional args behind.
+ *
+ * Recognised: `--assert-subset <path>` (#796). Everything else is treated as a
+ * positional argument (the wave-scope.json file path), preserving legacy
+ * behaviour where argv[2] is the input file.
+ *
+ * @param {string[]} argv - full process.argv
+ * @returns {{ assertSubset: string|null, positionals: string[] }}
+ */
+function parseArgs(argv) {
+  const positionals = [];
+  let assertSubset = null;
+  for (let i = 2; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--assert-subset') {
+      assertSubset = argv[i + 1];
+      if (assertSubset === undefined) {
+        die('--assert-subset requires a file-path argument', 1);
+      }
+      i++; // consume the value
+    } else {
+      positionals.push(a);
+    }
+  }
+  return { assertSubset, positionals };
+}
+
+/**
+ * Read raw input: from a file path arg or from stdin (fd 0).
+ *
+ * Exit codes used here:
+ *   1 — bad argument (file path argument given but file not found)
+ *   2 — unexpected I/O error (file exists but cannot be read, stdin failure)
+ *
+ * @param {string|undefined} arg - the positional wave-scope.json file path (or undefined for stdin)
+ * @returns {string}
+ */
+function readInput(arg) {
+  if (arg) {
+    // Exit 1: file not found is a user/argument error
+    if (!existsSync(arg) || !statSync(arg).isFile()) {
+      die(`File not found: ${arg}`, 1);
+    }
+    // Exit 2: file exists but cannot be read is an I/O error
+    try {
+      return readFileSync(arg, 'utf8');
+    } catch (err) {
+      die(`Cannot read file ${arg}: ${err.message}`, 2);
+    }
+  }
+  // Exit 2: stdin read failure is an I/O error
+  try {
+    return readFileSync(0, 'utf8');
+  } catch (err) {
+    die(`Cannot read stdin: ${err.message}`, 2);
+  }
+}
+
+/**
+ * Parse raw JSON input; exits 1 on parse failure.
+ * @param {string} input
+ * @returns {unknown}
+ */
+function parseJson(input) {
+  try {
+    return JSON.parse(input);
+  } catch {
+    die('Input is not valid JSON');
+  }
+}
+
+/**
+ * Validate required scalar fields: wave, role, enforcement.
+ * @param {Record<string, unknown>} obj
+ * @param {string[]} errors
+ */
+function validateRequired(obj, errors) {
+  // wave — positive integer
+  if (!('wave' in obj) || obj.wave === null || obj.wave === undefined) {
+    errors.push('Missing required field: wave');
+  } else if (typeof obj.wave !== 'number' || !Number.isInteger(obj.wave) || obj.wave <= 0) {
+    errors.push(`wave must be a positive integer, got: ${JSON.stringify(obj.wave)}`);
+  }
+
+  // role — non-empty string
+  const roleType = obj.role === null ? 'null' : typeof obj.role;
+  if (!('role' in obj) || roleType !== 'string') {
+    errors.push(`role must be a string, got type: ${roleType}`);
+  } else if (obj.role.length === 0) {
+    errors.push('role must be a non-empty string');
+  }
+
+  // enforcement — one of strict|warn|off
+  const enfType = obj.enforcement === null ? 'null' : typeof obj.enforcement;
+  if (!('enforcement' in obj) || enfType !== 'string') {
+    errors.push(`enforcement must be a string, got type: ${enfType}`);
+  } else if (!['strict', 'warn', 'off'].includes(obj.enforcement)) {
+    errors.push(`enforcement must be one of: strict, warn, off — got: ${obj.enforcement}`);
+  }
+}
+
+/**
+ * Validate allowedPaths array: must exist, be an array of non-empty strings,
+ * with no absolute paths and no path-traversal segments.
+ * @param {Record<string, unknown>} obj
+ * @param {string[]} errors
+ * @param {string[]} warnings
+ */
+function validateAllowedPaths(obj, errors, warnings) {
+  if (!('allowedPaths' in obj)) {
+    errors.push('Missing required field: allowedPaths');
+    return;
+  }
+  const ap = obj.allowedPaths;
+  if (!Array.isArray(ap)) {
+    errors.push(`allowedPaths must be an array, got type: ${ap === null ? 'null' : typeof ap}`);
+    return;
+  }
+  for (const entry of ap) {
+    if (typeof entry !== 'string' || entry.length === 0) {
+      errors.push('allowedPaths contains empty string');
+      continue;
+    }
+    // Reject absolute paths (must be repo-relative)
+    if (entry.startsWith('/')) {
+      errors.push(`allowedPaths contains absolute path: ${entry}`);
+    }
+    // Reject path traversal: any `../` segment
+    if (entry.includes('../')) {
+      errors.push(`allowedPaths contains path traversal: ${entry}`);
+    }
+    // Warn on overly permissive glob patterns
+    if (entry === '**/*' || entry === '*') {
+      warnings.push(`allowedPaths contains overly permissive pattern: ${entry}`);
+    }
+  }
+}
+
+/**
+ * Validate blockedCommands: must exist and be an array.
+ * @param {Record<string, unknown>} obj
+ * @param {string[]} errors
+ */
+function validateBlockedCommands(obj, errors) {
+  if (!('blockedCommands' in obj)) {
+    errors.push('Missing required field: blockedCommands');
+    return;
+  }
+  if (!Array.isArray(obj.blockedCommands)) {
+    const t = obj.blockedCommands === null ? 'null' : typeof obj.blockedCommands;
+    errors.push(`blockedCommands must be an array, got type: ${t}`);
+  }
+}
+
+/**
+ * Validate optional gates field: if present must be an object of string→boolean entries.
+ * @param {Record<string, unknown>} obj
+ * @param {string[]} errors
+ */
+function validateGates(obj, errors) {
+  if (!('gates' in obj)) return;
+  const gates = obj.gates;
+  if (gates === null || typeof gates !== 'object' || Array.isArray(gates)) {
+    const t = gates === null ? 'null' : Array.isArray(gates) ? 'array' : typeof gates;
+    errors.push(`gates must be an object, got type: ${t}`);
+    return;
+  }
+  const bad = Object.entries(gates)
+    .filter(([, v]) => typeof v !== 'boolean')
+    .map(([k]) => k);
+  if (bad.length > 0) {
+    errors.push(`gates values must be booleans, invalid entries: ${bad.join(', ')}`);
+  }
+}
+
+/**
+ * Read the agent fileScope sidecar file and assert it is a subset of the
+ * wave's allowedPaths union (#796). Exits on failure; returns on success.
+ *
+ * Exit codes:
+ *   1 — fileScope file is not valid JSON, is not an array of strings, or the
+ *       subset assertion fails (validation error)
+ *   2 — fileScope file is missing / not a regular file / unreadable (I/O error)
+ *
+ * @param {Record<string, unknown>} obj - the already schema-validated wave-scope object
+ * @param {string} fileScopePath - path to the agent fileScope JSON file
+ */
+function assertSubsetOrDie(obj, fileScopePath) {
+  if (!existsSync(fileScopePath) || !statSync(fileScopePath).isFile()) {
+    die(`Cannot read --assert-subset file: ${fileScopePath}`, 2);
+  }
+  let raw;
+  try {
+    raw = readFileSync(fileScopePath, 'utf8');
+  } catch (err) {
+    die(`Cannot read --assert-subset file ${fileScopePath}: ${err.message}`, 2);
+  }
+  let fileScope;
+  try {
+    fileScope = JSON.parse(raw);
+  } catch {
+    die(`--assert-subset file is not valid JSON: ${fileScopePath}`, 1);
+  }
+  if (!Array.isArray(fileScope) || !fileScope.every((e) => typeof e === 'string')) {
+    die('--assert-subset file must be a JSON array of strings', 1);
+  }
+  const { ok, missing } = assertFileScopeSubset(fileScope, obj.allowedPaths);
+  if (!ok) {
+    die(`agent fileScope not ⊆ allowedPaths — missing: [${missing.join(', ')}]`, 1);
+  }
+}
+
+/**
+ * Main validation entry point. Reads input, validates, exits with appropriate code.
+ * @param {string} input - raw JSON string
+ * @param {string|null} [assertSubsetPath] - optional agent fileScope file for the #796 subset assertion
+ */
+function validate(input, assertSubsetPath = null) {
+  const obj = parseJson(input);
+  const errors = [];
+  const warnings = [];
+
+  validateRequired(obj, errors);
+  validateAllowedPaths(obj, errors, warnings);
+  validateBlockedCommands(obj, errors);
+  validateGates(obj, errors);
+
+  for (const w of warnings) {
+    warn(w);
+  }
+
+  if (errors.length > 0) {
+    for (const e of errors) {
+      process.stderr.write(`ERROR: ${e}\n`);
+    }
+    process.exit(1);
+  }
+
+  // #796 — optional dispatch-time subset assertion (runs only after schema validation passes)
+  if (assertSubsetPath) {
+    assertSubsetOrDie(obj, assertSubsetPath);
+  }
+
+  // Echo validated JSON to stdout (trailing newline normalised)
+  process.stdout.write(input.endsWith('\n') ? input : input + '\n');
+}
+
+const { assertSubset, positionals } = parseArgs(process.argv);
+validate(readInput(positionals[0]), assertSubset);

package/scripts/vault-backfill.mjs

@@ -0,0 +1,404 @@
+#!/usr/bin/env node
+/**
+ * vault-backfill.mjs — GitLab group scanner + .vault.yaml backfill CLI (Issue #241).
+ *
+ * Scans GitLab groups for repos missing .vault.yaml and either previews (dry-run,
+ * default) or renders the canonical template content (--apply).
+ *
+ * CLI usage:
+ *   node scripts/vault-backfill.mjs [--groups <CSV>] [--dry-run] [--apply]
+ *     [--out-dir <path>] [--yes <manifest.json>] [--vault-dir <path>] [--verbose]
+ *
+ * Exit codes:
+ *   0 — success (clean run, dry or apply, even if some repos skipped)
+ *   1 — validation error (bad CLI flags, missing --groups AND no Session Config
+ *         gitlab-groups, malformed manifest, missing glab CLI)
+ *   2 — filesystem error (template missing, cannot write to out-dir)
+ *   3 — GitLab API error (auth failure, rate limit, group not found — when ALL
+ *         groups fail to resolve OR all repo-probes fail and nothing was processed)
+ *   4 — dry-run found nothing to backfill (informational; not an error)
+ *
+ * All logging → stderr. Structured JSON actions → stdout (one object per line).
+ * No external dependencies — Node stdlib only.
+ *
+ * Part of Vault-Docs Sub-Epic C (Issue #241).
+ */
+
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'node:fs';
+import { join, resolve, dirname } from 'node:path';
+import { createInterface } from 'node:readline';
+
+import {
+  assertGlabExists, setVerbose as setGlabVerbose,
+  listGroupRepos, checkVaultYaml, fetchRepoOwner,
+} from './lib/vault-backfill/glab.mjs';
+
+import {
+  loadTemplate, slugToHumanName, pathToSlug, renderTemplate,
+} from './lib/vault-backfill/template.mjs';
+
+import { validateManifest, SLUG_RE } from './lib/vault-backfill/manifest.mjs';
+
+// ── CLI argument parsing ──────────────────────────────────────────────────────
+
+const args = process.argv.slice(2);
+
+function getArg(name) {
+  const idx = args.indexOf(name);
+  return idx !== -1 ? args[idx + 1] : undefined;
+}
+
+const flagGroups  = getArg('--groups');
+const flagDryRun  = args.includes('--dry-run');
+const flagApply   = args.includes('--apply');
+const flagYes     = getArg('--yes');
+const flagVaultDir = getArg('--vault-dir');
+const flagOutDir  = getArg('--out-dir');
+const flagVerbose = args.includes('--verbose');
+
+// ── Logging + output ──────────────────────────────────────────────────────────
+
+function log(msg) {
+  process.stderr.write(`[vault-backfill] ${msg}\n`);
+}
+
+function emitAction(action, repoPath, extra = {}) {
+  process.stdout.write(JSON.stringify({ action, path: repoPath, ...extra }) + '\n');
+}
+
+function die(code, msg) {
+  process.stderr.write(`[vault-backfill] ERROR: ${msg}\n`);
+  process.exit(code);
+}
+
+// ── Validation ────────────────────────────────────────────────────────────────
+
+if (flagDryRun && flagApply) die(1, '--dry-run and --apply are mutually exclusive');
+
+const applyWrites = flagApply === true;
+
+/** Resolved staging output directory (used when --apply is set). */
+const outDir = resolve(flagOutDir ?? './.vault-backfill-staging');
+
+/** Whether any file writes failed (contributes to exit 2). */
+let hadWriteError = false;
+
+if (flagVerbose) setGlabVerbose(true);
+
+// ── Session Config reader (inline) ───────────────────────────────────────────
+
+/** Read vault-integration.{gitlab-groups,vault-dir} from CLAUDE.md / AGENTS.md in CWD. */
+function readVaultIntegrationConfig() {
+  const candidates = [join(process.cwd(), 'CLAUDE.md'), join(process.cwd(), 'AGENTS.md')];
+
+  let content = null;
+  for (const p of candidates) {
+    if (existsSync(p)) {
+      try { content = readFileSync(p, 'utf8'); break; } catch { /* try next */ }
+    }
+  }
+
+  if (!content) return { 'gitlab-groups': null, 'vault-dir': null };
+
+  let inBlock = false;
+  let gitlabGroups = null;
+  let vaultDir = null;
+
+  for (const rawLine of content.split(/\r?\n/)) {
+    const line = rawLine.replace(/\r$/, '');
+
+    if (!inBlock && /^vault-integration:\s*$/.test(line)) { inBlock = true; continue; }
+    if (inBlock) {
+      if (line.length > 0 && !/^\s/.test(line)) break;
+
+      const m = line.match(/^\s+([a-zA-Z_-]+):\s*(.*)/);
+      if (!m) continue;
+
+      const k = m[1].trim();
+      let v = m[2].trim().replace(/\s*#.*$/, '').trim();
+      if ((v.startsWith('"') && v.endsWith('"')) || (v.startsWith("'") && v.endsWith("'"))) {
+        v = v.slice(1, -1);
+      }
+
+      if (k === 'gitlab-groups' && v) {
+        gitlabGroups = v.replace(/^\[/, '').replace(/\]$/, '').trim() || null;
+      }
+      if (k === 'vault-dir' && v && v !== 'none' && v !== 'null') {
+        vaultDir = v;
+      }
+    }
+  }
+
+  return { 'gitlab-groups': gitlabGroups, 'vault-dir': vaultDir };
+}
+
+// ── Vault-dir folder stub ─────────────────────────────────────────────────────
+
+function createVaultFolderStub(vaultDir, slug) {
+  if (!vaultDir) return;
+  const stubDir = join(resolve(vaultDir), '01-projects', slug);
+  try {
+    if (!existsSync(stubDir)) {
+      if (applyWrites) {
+        mkdirSync(stubDir, { recursive: true });
+        log(`created vault folder stub: ${stubDir}`);
+      } else {
+        log(`[dry-run] would create vault folder stub: ${stubDir}`);
+      }
+    }
+  } catch (err) {
+    process.stderr.write(
+      `[vault-backfill] WARN: could not create vault stub for ${slug}: ${err.message}\n`,
+    );
+  }
+}
+
+// ── Process one repo ──────────────────────────────────────────────────────────
+
+function processRepo(entry, vaultDir, templateContent) {
+  const { path: repoPath, slug, tier, visibility, group, id } = entry;
+  const humanName = slugToHumanName(slug);
+
+  const owner = applyWrites ? fetchRepoOwner(id) : 'unknown';
+
+  let renderedContent;
+  try {
+    renderedContent = renderTemplate(
+      { humanName, slug, tier, gitlabPath: repoPath, owner },
+      templateContent,
+    );
+  } catch (err) {
+    process.stderr.write(
+      `[vault-backfill] WARN: template render failed for ${repoPath}: ${err.message}\n`,
+    );
+    emitAction('skipped-render-error', repoPath, { slug, tier, visibility, error: err.message });
+    return;
+  }
+
+  if (!applyWrites) {
+    // Dry-run: emit preview action only (no disk write)
+    emitAction('vault-yaml-rendered', repoPath, { slug, tier, visibility, group, content: renderedContent });
+    log(`[dry-run] ${repoPath}: would write .vault.yaml (slug=${slug}, tier=${tier})`);
+    createVaultFolderStub(vaultDir, slug);
+    return;
+  }
+
+  // Apply: write to staging directory at <out-dir>/<group>/<repo>/.vault.yaml
+  const writePath = join(outDir, repoPath, '.vault.yaml');
+  try {
+    mkdirSync(dirname(writePath), { recursive: true });
+    writeFileSync(writePath, renderedContent, 'utf8');
+    emitAction('wrote', writePath, { slug, id, tier, visibility, group });
+    log(`${repoPath}: wrote .vault.yaml → ${writePath}`);
+  } catch (err) {
+    emitAction('write-failed', writePath, { error: err.message, slug, group });
+    process.stderr.write(
+      `[vault-backfill] ERROR: cannot write ${writePath}: ${err.message}\n`,
+    );
+    hadWriteError = true;
+  }
+
+  createVaultFolderStub(vaultDir, slug);
+}
+
+// ── Scan groups ───────────────────────────────────────────────────────────────
+
+function scanGroups(groups) {
+  let failedGroups = 0;
+  const missing = [];
+
+  for (const group of groups) {
+    log(`scanning group: ${group}`);
+    const repos = listGroupRepos(group);
+    if (repos === null) { failedGroups++; continue; }
+
+    log(`  found ${repos.length} repo(s) in ${group}`);
+    for (const repo of repos) {
+      if (!repo.path) continue;
+      const status = checkVaultYaml(repo.path);
+      if (status === 'present') {
+        log(`  ${repo.path}: already has .vault.yaml — skipping`);
+        emitAction('skipped-has-vault-yaml', repo.path, { visibility: repo.visibility, createdAt: repo.createdAt });
+        continue;
+      }
+      missing.push({ ...repo, group });
+    }
+  }
+
+  const allGroupsFailed = failedGroups > 0 && failedGroups === groups.length;
+  return { repos: missing, apiError: failedGroups > 0, allGroupsFailed };
+}
+
+// ── Table printer ─────────────────────────────────────────────────────────────
+
+function printTable(repos) {
+  if (repos.length === 0) { process.stderr.write('\n  (no repos to backfill)\n'); return; }
+
+  const COL_REPO = Math.max(4, ...repos.map((r) => r.path.length));
+  const pad = (s, n) => String(s).padEnd(n);
+  const sep = `  ${'-'.repeat(COL_REPO + 26)}\n`;
+
+  process.stderr.write('\n');
+  process.stderr.write(`  ${pad('Repo', COL_REPO)}  ${pad('Date', 10)}  Visibility\n`);
+  process.stderr.write(sep);
+  for (const r of repos) {
+    process.stderr.write(`  ${pad(r.path, COL_REPO)}  ${pad(r.createdAt, 10)}  ${r.visibility}\n`);
+  }
+  process.stderr.write('\n');
+}
+
+// ── Interactive prompt ────────────────────────────────────────────────────────
+
+async function promptForRepo(rl, repoPath, suggestedSlug) {
+  const ask = (q) => new Promise((res) => rl.question(q, (a) => res(a.trim())));
+
+  process.stderr.write(`\n  Repo: ${repoPath}\n`);
+
+  let slug;
+  while (true) {
+    const input = await ask(`  Slug [${suggestedSlug}]: `);
+    slug = input || suggestedSlug;
+    if (SLUG_RE.test(slug)) break;
+    process.stderr.write(`  Invalid slug — must match [a-z0-9]+(-[a-z0-9]+)*\n`);
+  }
+
+  let tier;
+  while (true) {
+    const input = await ask(`  Tier (top/active/archived) [active]: `);
+    tier = input || 'active';
+    if (['top', 'active', 'archived'].includes(tier)) break;
+    process.stderr.write(`  Invalid tier — must be top|active|archived\n`);
+  }
+
+  const skip = await ask(`  Skip this repo? [y/N]: `);
+  if (skip.toLowerCase() === 'y') return null;
+  return { slug, tier };
+}
+
+// ── Headless (--yes) path ─────────────────────────────────────────────────────
+
+async function runHeadless(manifestPath, vaultDir) {
+  let raw;
+  try {
+    raw = JSON.parse(readFileSync(manifestPath, 'utf8'));
+  } catch (err) {
+    die(1, `cannot parse manifest '${manifestPath}': ${err.message}`);
+  }
+
+  const repos = validateManifest(raw, die);
+  const templateContent = loadTemplate(die);
+  const pending = repos.filter((r) => !r.skip);
+
+  log(`manifest: ${repos.length} entries, ${pending.length} to process`);
+  if (pending.length === 0) { log('nothing to backfill (all skip:true)'); process.exit(4); }
+
+  // When --yes manifest is provided, it is the authoritative scope — skip the
+  // GitLab API .vault.yaml presence check so the CLI works without live repo access.
+  for (const entry of pending) {
+    processRepo(
+      { ...entry, group: entry.path.split('/')[0] ?? '' },
+      vaultDir,
+      templateContent,
+    );
+  }
+}
+
+// ── Interactive path ──────────────────────────────────────────────────────────
+
+async function runInteractive(groups, vaultDir) {
+  const templateContent = loadTemplate(die);
+
+  log('scanning groups for repos missing .vault.yaml …');
+  const { repos: missing, apiError, allGroupsFailed } = scanGroups(groups);
+
+  if (apiError) log('WARN: one or more groups had API errors; results may be incomplete');
+
+  // Exit 3 only when ALL groups failed and nothing was processed at all
+  if (allGroupsFailed) {
+    die(3, 'all GitLab group scans failed — check auth (GITLAB_TOKEN) and group paths');
+  }
+
+  if (missing.length === 0) { log('all scanned repos already have .vault.yaml — nothing to backfill'); process.exit(4); }
+
+  printTable(missing);
+  log(`found ${missing.length} repo(s) without .vault.yaml`);
+
+  if (!applyWrites) {
+    log('(dry-run mode — use --apply to write .vault.yaml files)');
+    for (const repo of missing) {
+      processRepo({ ...repo, slug: pathToSlug(repo.path), tier: 'active' }, vaultDir, templateContent);
+    }
+    return;
+  }
+
+  // Interactive prompts
+  const rl = createInterface({ input: process.stdin, output: process.stderr, terminal: true });
+  const decisions = [];
+
+  for (const repo of missing) {
+    const decision = await promptForRepo(rl, repo.path, pathToSlug(repo.path));
+    if (decision === null) {
+      log(`${repo.path}: skipped by user`);
+      emitAction('skipped-by-user', repo.path, { visibility: repo.visibility });
+      continue;
+    }
+    decisions.push({ repo, ...decision });
+  }
+
+  if (decisions.length === 0) {
+    rl.close();
+    log('no repos selected — nothing to apply');
+    process.exit(0);
+  }
+
+  process.stderr.write(`\n  ${decisions.length} repo(s) will receive .vault.yaml. Apply? [y/N]: `);
+  const confirmed = await new Promise((resolve) => {
+    rl.question('', (a) => { rl.close(); resolve(a.trim().toLowerCase()); });
+  });
+
+  if (confirmed !== 'y') { log('aborted by user — no writes performed'); process.exit(0); }
+
+  for (const { repo, slug, tier } of decisions) {
+    processRepo({ ...repo, slug, tier }, vaultDir, templateContent);
+  }
+}
+
+// ── Main ──────────────────────────────────────────────────────────────────────
+
+async function main() {
+  const cfgConfig = readVaultIntegrationConfig();
+
+  let groups;
+  if (flagGroups) {
+    groups = flagGroups.split(',').map((g) => g.trim()).filter(Boolean);
+  } else if (cfgConfig['gitlab-groups']) {
+    groups = cfgConfig['gitlab-groups'].split(',').map((g) => g.trim()).filter(Boolean);
+  }
+
+  const vaultDir = flagVaultDir ?? cfgConfig['vault-dir'] ?? null;
+
+  if (!flagYes && (!groups || groups.length === 0)) {
+    die(1, 'no GitLab groups specified — pass --groups <CSV> or set vault-integration.gitlab-groups in CLAUDE.md');
+  }
+
+  if (flagYes) {
+    // Headless path: manifest is authoritative. No glab required (CI / air-gapped).
+    await runHeadless(flagYes, vaultDir);
+  } else {
+    // Interactive path: glab is required for group scanning + per-repo presence checks.
+    assertGlabExists(die);
+    await runInteractive(groups, vaultDir);
+  }
+
+  // Propagate write failures (EACCES, ENOSPC, etc.) as exit code 2
+  if (hadWriteError) {
+    process.stderr.write('[vault-backfill] ERROR: one or more .vault.yaml writes failed (see above)\n');
+    process.exit(2);
+  }
+}
+
+main().catch((err) => {
+  process.stderr.write(`[vault-backfill] unexpected error: ${err.message}\n`);
+  if (flagVerbose && err.stack) process.stderr.write(err.stack + '\n');
+  process.exit(2);
+});