session-orchestrator 3.16.0

package/scripts/lib/vault-backfill/template.mjs

@@ -0,0 +1,130 @@
+/**
+ * template.mjs — Canonical .vault.yaml template renderer for vault-backfill.
+ *
+ * Reads the template once from projects-baseline; subsequent calls use cache.
+ * Part of scripts/vault-backfill.mjs (Issue #241).
+ */
+
+import { readFileSync, existsSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { resolve } from 'node:path';
+
+export const TEMPLATE_PATH = process.env.PROJECTS_BASELINE_DIR
+  ? resolve(process.env.PROJECTS_BASELINE_DIR, 'templates/shared/.vault.yaml.template')
+  : resolve(homedir(), 'Projects/projects-baseline/templates/shared/.vault.yaml.template');
+
+const TODAY = new Date().toISOString().slice(0, 10);
+
+let _templateContent = null;
+
+/**
+ * Load and cache the canonical template. Calls dieFn(2, ...) if missing.
+ */
+export function loadTemplate(dieFn) {
+  if (_templateContent !== null) return _templateContent;
+
+  if (!existsSync(TEMPLATE_PATH)) {
+    dieFn(
+      2,
+      `canonical template not found at ${TEMPLATE_PATH} — ` +
+        `set PROJECTS_BASELINE_DIR env var or check projects-baseline checkout at $HOME/Projects/projects-baseline`,
+    );
+  }
+
+  try {
+    _templateContent = readFileSync(TEMPLATE_PATH, 'utf8');
+  } catch (err) {
+    dieFn(2, `cannot read template at ${TEMPLATE_PATH}: ${err.message}`);
+  }
+
+  return _templateContent;
+}
+
+/**
+ * Convert a kebab-case slug to a human-readable Title Case name.
+ * e.g. "auth-service" → "Auth Service"
+ */
+export function slugToHumanName(slug) {
+  return slug
+    .split('-')
+    .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
+    .join(' ');
+}
+
+/**
+ * Derive a kebab-case slug from a repo path (last segment).
+ */
+export function pathToSlug(repoPath) {
+  const last = repoPath.split('/').filter(Boolean).pop() ?? repoPath;
+  return last
+    .toLowerCase()
+    .replace(/[._]/g, '-')
+    .replace(/[^a-z0-9-]/g, '')
+    .replace(/-+/g, '-')
+    .replace(/^-+|-+$/g, '');
+}
+
+/**
+ * Produce a safe YAML 1.2 scalar for a user-supplied string value.
+ *
+ * Uses JSON.stringify (YAML 1.2 is a superset of JSON) which:
+ *   - wraps the value in double quotes
+ *   - escapes newlines (\n), carriage returns (\r), tabs (\t), backslashes, and double quotes
+ *
+ * This prevents YAML injection via embedded newlines or special characters
+ * in externally-sourced fields such as `owner` (GitLab API) and `gitlabPath`
+ * (manifest file). CWE-1336 / Issue #247.
+ *
+ * @param {string} value
+ * @returns {string} — a JSON-encoded double-quoted YAML scalar, e.g. "alice"
+ */
+export function yamlScalar(value) {
+  return JSON.stringify(String(value));
+}
+
+/**
+ * Render .vault.yaml content from the canonical template.
+ *
+ * Substitutions:
+ *   {{PROJECT_NAME}} → humanName   (metadata.name, summary placeholder)
+ *   metadata.slug    → slug         (overwrite the {{PROJECT_NAME}} echo on slug field)
+ *   tier             → manifest tier
+ *   owner            → fetched owner  [sanitised via yamlScalar]
+ *   {{GITLAB_GROUP}}/{{PROJECT_NAME}} → full gitlab path_with_namespace  [sanitised via yamlScalar]
+ *
+ * @param {{ humanName: string, slug: string, tier: string, gitlabPath: string, owner: string }} opts
+ * @param {string} templateContent - loaded template string
+ * @returns {string}
+ */
+export function renderTemplate({ humanName, slug, tier, gitlabPath, owner }, templateContent) {
+  let out =
+    `# Generated by scripts/vault-backfill.mjs on ${TODAY} — review and update before committing.\n` +
+    templateContent;
+
+  // {{PROJECT_NAME}} → humanName (appears in metadata.name, summary)
+  // humanName is derived from a manifest-validated slug ([a-z0-9-]) so it only
+  // contains word characters and spaces — no YAML-special characters.
+  out = out.replace(/\{\{PROJECT_NAME\}\}/g, humanName);
+
+  // metadata.slug line: after PROJECT_NAME substitution it reads slug: "humanName" — fix to actual slug
+  // slug is validated to /^[a-z0-9]+(?:-[a-z0-9]+)*$/ by validateManifest — safe to embed bare.
+  out = out.replace(/^(\s*slug:\s*)"[^"]*"(.*)$/m, `$1"${slug}"$2`);
+
+  // tier: active → tier: <manifest tier>
+  // tier is a closed enum (top|active|archived) — safe to embed bare.
+  out = out.replace(/^(\s*tier:\s*)active(.*)$/m, `$1${tier}$2`);
+
+  // owner field — value comes from GitLab API (externally controlled).
+  // Use yamlScalar() to produce a quoted scalar, preventing newline injection (CWE-1336, #247).
+  // The template has a bare unquoted owner value (e.g. `owner: bernhard`);
+  // the regex replaces only the bare value token, preserving any trailing comment.
+  out = out.replace(/^(\s*owner:\s*)\S+(.*)$/m, `$1${yamlScalar(owner)}$2`);
+
+  // spec.links.gitlab — template uses {{GITLAB_GROUP}}/{{PROJECT_NAME}};
+  // after PROJECT_NAME substitution the token reads {{GITLAB_GROUP}}/humanName, still inside "...".
+  // gitlabPath comes from the manifest `path` field which is not validated for YAML-special chars.
+  // Replace the whole "..." quoted token with yamlScalar(gitlabPath) to prevent injection (#247).
+  out = out.replace(/"?\{\{GITLAB_GROUP\}\}\/[^\n"]*"?/g, yamlScalar(gitlabPath));
+
+  return out;
+}

package/scripts/lib/vault-consolidate-fs.mjs

@@ -0,0 +1,331 @@
+/**
+ * vault-consolidate-fs.mjs — filesystem + classification helpers for
+ * scripts/vault-consolidate.mjs (Issue #514 / #607).
+ *
+ * Extracted from the previously-monolithic vault-consolidate.mjs so the
+ * walk / hash / classify / backup logic is unit-importable in isolation. The
+ * script itself (vault-consolidate.mjs) wires these helpers behind an
+ * `import.meta.url === pathToFileURL(process.argv[1])` entry-guard so importing
+ * the script no longer executes the migration as a top-level side effect.
+ *
+ * Every function here is behaviour-identical to its former in-script form;
+ * the only change is that previously-closed-over module constants/state
+ * (SCRIPT_NAME, BACKUP_PREFIX, DECISIONS_SIDECAR_REL, canonicalRoot) are now
+ * exported constants / explicit parameters so the helpers are pure with
+ * respect to their inputs.
+ */
+
+import { promises as fs } from 'node:fs';
+import { isUtf8 } from 'node:buffer';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { spawnSync } from 'node:child_process';
+
+export const SCRIPT_NAME = 'vault-consolidate';
+export const BACKUP_PREFIX = '.vault-backup-';
+export const DECISIONS_SIDECAR_REL = '.vault-consolidate-decisions.json';
+
+/**
+ * Recursively walk `root`, returning absolute paths of regular files.
+ * Skips: hidden directories (start with `.`), and any descendant of an
+ * existing `.vault-backup-*` directory.
+ */
+export async function walkFiles(root) {
+  /** @type {string[]} */
+  const out = [];
+  /** @type {string[]} */
+  const stack = [root];
+
+  while (stack.length > 0) {
+    const dir = stack.pop();
+    let entries;
+    try {
+      entries = await fs.readdir(dir, { withFileTypes: true });
+    } catch (err) {
+      process.stderr.write(`${SCRIPT_NAME}: WARN readdir failed for ${dir}: ${err.message}\n`);
+      continue;
+    }
+
+    for (const entry of entries) {
+      const fullPath = path.join(dir, entry.name);
+
+      // F5 (issue #514 fold-in) — symlink guard, evaluated FIRST.
+      //
+      // `fs.readdir(dir, { withFileTypes: true })` populates each Dirent from
+      // an `lstat` of the entry, so a symlink-to-directory already reports
+      // `isDirectory() === false` (and `isSymbolicLink() === true`) and would
+      // fall through both branches below untouched. This explicit guard makes
+      // the skip OBSERVABLE (a WARN line) and hardens against any future
+      // refactor that switches to `fs.stat`-based classification — which DOES
+      // follow symlinks and could recurse into an out-of-tree directory or
+      // copy a dereferenced target into the backup. We never follow a symlink:
+      // neither symlinked directories (recursion risk) nor symlinked files
+      // (the dereference-into-backup risk #514 also guards at stageBackup).
+      if (entry.isSymbolicLink()) {
+        process.stderr.write(
+          `${SCRIPT_NAME}: WARN skipping symlink (not dereferenced): ${fullPath}\n`
+        );
+        continue;
+      }
+
+      if (entry.isDirectory()) {
+        // Skip hidden dirs and prior backup staging dirs
+        if (entry.name === '.git') continue;
+        if (entry.name.startsWith(BACKUP_PREFIX)) continue;
+        if (entry.name === '.obsidian' || entry.name === '.trash') continue;
+        if (entry.name === 'node_modules') continue;
+        // Allow other dotfiles (vault-mirror writes none, but be conservative)
+        stack.push(fullPath);
+        continue;
+      }
+
+      if (entry.isFile()) {
+        // Skip macOS metadata, the decisions sidecar, and .DS_Store
+        if (entry.name === '.DS_Store') continue;
+        if (entry.name === DECISIONS_SIDECAR_REL) continue;
+        if (entry.name.startsWith('._')) continue;
+        // Skip backup archives left by prior --apply runs (idempotency).
+        // Matches both `.vault-backup-<ts>.tar.gz` and `.vault-backup-<ts>` dirs
+        // (the dir form is also filtered by the directory branch above).
+        if (entry.name.startsWith(BACKUP_PREFIX)) continue;
+        out.push(fullPath);
+      }
+      // (Symlinks already handled by the isSymbolicLink() guard above.)
+    }
+  }
+
+  out.sort();
+  return out;
+}
+
+export async function sha256OfFile(absPath) {
+  const buf = await fs.readFile(absPath);
+  return crypto.createHash('sha256').update(buf).digest('hex');
+}
+
+/**
+ * Check whether `B` starts with `A` modulo trailing whitespace.
+ * Both are utf-8 strings.
+ */
+export function isPrefix(a, b) {
+  const aTrim = a.trimEnd();
+  if (aTrim.length === 0) return false;
+  if (aTrim.length > b.length) return false;
+  return b.startsWith(aTrim);
+}
+
+/**
+ * Classify one source file.
+ *
+ * @param {string} srcAbs         absolute path inside source vault
+ * @param {string} rel            relative path under source root
+ * @param {string} canonicalRoot  absolute path of the canonical vault root
+ * @returns {Promise<object>}     action record
+ */
+export async function classifyFile(srcAbs, rel, canonicalRoot) {
+  const dstAbs = path.join(canonicalRoot, rel);
+
+  let srcStat;
+  try {
+    srcStat = await fs.stat(srcAbs);
+  } catch (err) {
+    return {
+      kind: 'action',
+      action: 'error',
+      rel,
+      source: srcAbs,
+      canonical: dstAbs,
+      error: `stat source failed: ${err.message}`,
+    };
+  }
+
+  let dstStat;
+  try {
+    dstStat = await fs.stat(dstAbs);
+  } catch {
+    dstStat = null;
+  }
+
+  if (dstStat === null) {
+    return {
+      kind: 'action',
+      action: 'copy',
+      rel,
+      source: srcAbs,
+      canonical: dstAbs,
+      src_size: srcStat.size,
+      src_mtime: srcStat.mtime.toISOString(),
+    };
+  }
+
+  // Both sides exist — hash both
+  let srcSha;
+  let dstSha;
+  try {
+    [srcSha, dstSha] = await Promise.all([sha256OfFile(srcAbs), sha256OfFile(dstAbs)]);
+  } catch (err) {
+    return {
+      kind: 'action',
+      action: 'error',
+      rel,
+      source: srcAbs,
+      canonical: dstAbs,
+      error: `hash failed: ${err.message}`,
+    };
+  }
+
+  if (srcSha === dstSha) {
+    return {
+      kind: 'action',
+      action: 'skip-already-present',
+      rel,
+      source: srcAbs,
+      canonical: dstAbs,
+      src_size: srcStat.size,
+      dst_size: dstStat.size,
+      src_sha: srcSha,
+      dst_sha: dstSha,
+    };
+  }
+
+  // Content differs — check subset relationship to pre-suggest a winner.
+  // We use explicit `isUtf8()` binary detection (not throw-based) to classify
+  // as `merge` vs `conflict-needs-review`. Node 20+ silently substitutes the
+  // U+FFFD replacement char for invalid UTF-8 sequences instead of throwing
+  // from `readFile('utf8')`, which previously left the conflict-needs-review
+  // branch unreachable for binary files (issue #508).
+  let subsetHint = null;
+  let textReadable = false;
+  try {
+    const [srcBuf, dstBuf] = await Promise.all([fs.readFile(srcAbs), fs.readFile(dstAbs)]);
+    // Both sides must be valid UTF-8 to be classified as `merge`. If either
+    // is binary (or non-UTF-8 encoded), fall through to conflict-needs-review
+    // so the operator inspects the pair manually with the right tool.
+    if (isUtf8(srcBuf) && isUtf8(dstBuf)) {
+      textReadable = true;
+      const srcContent = srcBuf.toString('utf8');
+      const dstContent = dstBuf.toString('utf8');
+      if (isPrefix(srcContent, dstContent)) {
+        // canonical is a superset of source → prefer canonical (dst)
+        subsetHint = 'dst-is-superset';
+      } else if (isPrefix(dstContent, srcContent)) {
+        // source is a superset of canonical → prefer source (src)
+        subsetHint = 'src-is-superset';
+      }
+    }
+  } catch {
+    // Read error (permissions, disappeared mid-walk, etc.) — leave
+    // textReadable=false; treat as conflict-needs-review so the operator
+    // inspects manually.
+  }
+
+  // Classification:
+  //   - both sides valid UTF-8                → merge  (AUQ-resolvable;
+  //                                              subset_hint may suggest winner)
+  //   - unreadable / binary / non-UTF-8       → conflict-needs-review
+  //
+  // Both classes still require an operator decision via the two-phase
+  // coordinator flow, but the label tells the caller whether the diff can be
+  // shown inline (merge) or requires opening the file in a binary tool
+  // (conflict-needs-review).
+  const action = textReadable ? 'merge' : 'conflict-needs-review';
+
+  return {
+    kind: 'action',
+    action,
+    rel,
+    source: srcAbs,
+    canonical: dstAbs,
+    src_size: srcStat.size,
+    dst_size: dstStat.size,
+    src_mtime: srcStat.mtime.toISOString(),
+    dst_mtime: dstStat.mtime.toISOString(),
+    src_sha: srcSha,
+    dst_sha: dstSha,
+    subset_hint: subsetHint,
+  };
+}
+
+/**
+ * Stage one file into the backup directory, preserving its relative path.
+ *
+ * #514 — symlink defense (defense-in-depth alongside the walk-level guard).
+ * `fs.copyFile()` and `fs.stat()` both FOLLOW symlinks, so a symlinked source
+ * entry (e.g. `evil.md → /etc/passwd`) would silently copy the TARGET's
+ * contents into the backup. We `fs.lstat()` first (which does NOT follow the
+ * link) and skip the copy entirely if the source is a symlink, so a symlink is
+ * never dereferenced into the backup.
+ *
+ * @returns {Promise<{staged: boolean}>}  staged=false when skipped (symlink)
+ */
+export async function stageBackup(backupRoot, srcAbs, rel) {
+  const linkStat = await fs.lstat(srcAbs);
+  if (linkStat.isSymbolicLink()) {
+    process.stderr.write(
+      `${SCRIPT_NAME}: WARN refusing to back up symlink (not dereferenced): ${srcAbs}\n`
+    );
+    return { staged: false };
+  }
+
+  const stagedAbs = path.join(backupRoot, rel);
+  await fs.mkdir(path.dirname(stagedAbs), { recursive: true });
+  await fs.copyFile(srcAbs, stagedAbs);
+  try {
+    const st = await fs.stat(srcAbs);
+    await fs.utimes(stagedAbs, st.atime, st.mtime);
+  } catch {
+    // non-fatal
+  }
+  return { staged: true };
+}
+
+/**
+ * Run `tar -czf <archive> -C <parent> <basename>` then remove the staging dir.
+ * Falls back to leaving the staging directory in place if tar is unavailable.
+ *
+ * @param {string} backupRoot absolute path of the staging directory
+ * @returns {Promise<{archive: string|null, removed: boolean}>}
+ */
+export async function compressAndCleanupBackup(backupRoot) {
+  const parent = path.dirname(backupRoot);
+  const basename = path.basename(backupRoot);
+  const archive = `${backupRoot}.tar.gz`;
+
+  const res = spawnSync('tar', ['-czf', archive, '-C', parent, basename], {
+    stdio: ['ignore', 'pipe', 'pipe'],
+    encoding: 'utf8',
+  });
+
+  // F1 (issue #514 fold-in) — distinguish "tar not on PATH" (ENOENT) from a
+  // non-zero tar exit. On ENOENT `spawnSync` sets `res.error` and leaves
+  // `res.status === null`; the generic branch below would otherwise print a
+  // confusing "tar failed (status null)". Surface the real cause and keep the
+  // uncompressed staging dir as the documented fallback.
+  if (res.error) {
+    const reason = res.error.code === 'ENOENT' ? 'tar not found on PATH' : res.error.message;
+    process.stderr.write(
+      `${SCRIPT_NAME}: WARN ${reason} — cannot compress backup. ` +
+        `Leaving staging directory at ${backupRoot} for manual archival.\n`
+    );
+    return { archive: null, removed: false };
+  }
+
+  if (res.status === 0) {
+    // Remove the now-redundant staging directory
+    try {
+      await fs.rm(backupRoot, { recursive: true, force: true });
+      return { archive, removed: true };
+    } catch (err) {
+      process.stderr.write(
+        `${SCRIPT_NAME}: WARN backup compressed but staging dir cleanup failed: ${err.message}\n`
+      );
+      return { archive, removed: false };
+    }
+  }
+
+  process.stderr.write(
+    `${SCRIPT_NAME}: WARN tar failed (status ${res.status}): ${res.stderr || res.stdout || 'no detail'}. ` +
+      `Leaving staging directory at ${backupRoot} for manual archival.\n`
+  );
+  return { archive: null, removed: false };
+}

package/scripts/lib/vault-migration-rules.mjs

@@ -0,0 +1,155 @@
+#!/usr/bin/env node
+/**
+ * vault-migration-rules.mjs — Per-user config loader for the vault migration scripts.
+ *
+ * Reads ~/.config/session-orchestrator/vault-migration-rules.yaml and returns
+ * structured defaults for the operator-private slug / username-rewrite data
+ * that the migration scripts (migrate-vault-paths.mjs, migrate-cold-start-seed.mjs)
+ * used to carry as hardcoded literals.
+ *
+ * Out of scope for this loader: argument-parsing, YAML schema versioning beyond
+ * v1, runtime mutation. The migration scripts retain `--repos` / `--from` / `--to`
+ * CLI args as the override path; this loader only supplies sensible defaults.
+ *
+ * Schema (schema-version: 1):
+ *
+ *   schema-version: 1
+ *   username-rewrites:
+ *     - from: '/Users/oldname/'
+ *       to:   '/Users/newname/'
+ *   audited-repos:   # default --repos for migrate-vault-paths.mjs
+ *     - repo-name-or-absolute-path
+ *   dormant-repos:   # default --repos for migrate-cold-start-seed.mjs
+ *     - '~/Projects/path/to/dormant-repo'
+ *
+ * All three sections are optional. Missing file → defaults are empty arrays;
+ * the migration scripts then fall back to their CLI-args path or print a
+ * helpful error if no override is given.
+ *
+ * Path: ~/.config/session-orchestrator/vault-migration-rules.yaml
+ *       (same per-user location convention as owner.yaml — outside every repo,
+ *        appended to ~/.gitignore by the migration-script bootstrap on first
+ *        write).
+ */
+
+import { readFileSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+import yaml from 'js-yaml';
+
+export const VAULT_MIGRATION_RULES_PATH = join(
+  homedir(),
+  '.config',
+  'session-orchestrator',
+  'vault-migration-rules.yaml',
+);
+
+/**
+ * Return the empty-defaults shape — used when the file does not exist or
+ * fails to parse. Callers decide whether to error or fall back to CLI args.
+ *
+ * @returns {{ usernameRewrites: Array<{from:string,to:string}>, auditedRepos: string[], dormantRepos: string[] }}
+ */
+export function getDefaults() {
+  return {
+    usernameRewrites: [],
+    auditedRepos: [],
+    dormantRepos: [],
+  };
+}
+
+/**
+ * Load and validate the vault-migration-rules config. Pure, never throws.
+ *
+ * @param {string} [filePath] - override for the default path (testing only)
+ * @returns {{ config: ReturnType<typeof getDefaults>, source: 'file'|'defaults', errors: string[] }}
+ */
+export function loadVaultMigrationRules(filePath = VAULT_MIGRATION_RULES_PATH) {
+  if (!existsSync(filePath)) {
+    return { config: getDefaults(), source: 'defaults', errors: [] };
+  }
+
+  let raw;
+  try {
+    raw = readFileSync(filePath, 'utf8');
+  } catch (err) {
+    return {
+      config: getDefaults(),
+      source: 'defaults',
+      errors: [`failed to read vault-migration-rules.yaml: ${err.message}`],
+    };
+  }
+
+  let parsed;
+  try {
+    parsed = yaml.load(raw);
+  } catch (err) {
+    return {
+      config: getDefaults(),
+      source: 'defaults',
+      errors: [`failed to parse vault-migration-rules.yaml: ${err.message}`],
+    };
+  }
+
+  const { config, errors } = normalize(parsed);
+  return { config, source: errors.length === 0 ? 'file' : 'defaults', errors };
+}
+
+/**
+ * Normalize a parsed YAML object into the canonical shape, returning errors
+ * for malformed entries. Unknown sections are ignored (forward-compatible).
+ *
+ * @param {unknown} obj
+ * @returns {{ config: ReturnType<typeof getDefaults>, errors: string[] }}
+ */
+function normalize(obj) {
+  const errors = [];
+  const config = getDefaults();
+
+  if (!isPlainObject(obj)) {
+    return { config, errors: ['config must be a YAML mapping'] };
+  }
+
+  // username-rewrites: [{ from: string, to: string }]
+  const rewrites = obj['username-rewrites'];
+  if (rewrites !== undefined) {
+    if (!Array.isArray(rewrites)) {
+      errors.push('username-rewrites must be an array');
+    } else {
+      for (let i = 0; i < rewrites.length; i++) {
+        const r = rewrites[i];
+        if (!isPlainObject(r) || typeof r.from !== 'string' || typeof r.to !== 'string') {
+          errors.push(`username-rewrites[${i}]: must have string 'from' and 'to' fields`);
+          continue;
+        }
+        config.usernameRewrites.push({ from: r.from, to: r.to });
+      }
+    }
+  }
+
+  // audited-repos: string[]
+  const audited = obj['audited-repos'];
+  if (audited !== undefined) {
+    if (!Array.isArray(audited) || !audited.every((s) => typeof s === 'string')) {
+      errors.push('audited-repos must be an array of strings');
+    } else {
+      config.auditedRepos = audited.slice();
+    }
+  }
+
+  // dormant-repos: string[]
+  const dormant = obj['dormant-repos'];
+  if (dormant !== undefined) {
+    if (!Array.isArray(dormant) || !dormant.every((s) => typeof s === 'string')) {
+      errors.push('dormant-repos must be an array of strings');
+    } else {
+      config.dormantRepos = dormant.slice();
+    }
+  }
+
+  return { config, errors };
+}
+
+function isPlainObject(v) {
+  return typeof v === 'object' && v !== null && !Array.isArray(v);
+}