session-orchestrator 3.16.0

package/scripts/parse-config.mjs

@@ -0,0 +1,149 @@
+#!/usr/bin/env node
+/**
+ * parse-config.mjs — Parse ## Session Config from CLAUDE.md or AGENTS.md and output validated JSON.
+ * Part of Session Orchestrator v3.0.0 (originally parse-config.sh in v2).
+ *
+ * Usage: node scripts/parse-config.mjs [path/to/CLAUDE.md|AGENTS.md]
+ *   If no path given, walks up from cwd to find project root and uses its CLAUDE.md (or AGENTS.md).
+ *
+ * Output: Single JSON object to stdout with ALL config fields (defaults applied).
+ * Exit codes: 0 success, 1 error (message to stderr)
+ *
+ * Environment:
+ *   SO_CONFIG_FILE             — override filename (e.g. "AGENTS.md") resolved from project root
+ *   SO_SKIP_CONFIG_VALIDATION  — set to "1" to bypass validate-config.mjs
+ */
+
+import { readFileSync, existsSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import { join, dirname, resolve, parse as parsePath } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { parseSessionConfig } from './lib/config.mjs';
+
+const SCRIPT_DIR = dirname(fileURLToPath(import.meta.url));
+
+// ---------------------------------------------------------------------------
+// Project-root resolution (walk up from cwd until .git / CLAUDE.md / AGENTS.md)
+// ---------------------------------------------------------------------------
+
+function findProjectRoot(startDir) {
+  let dir = resolve(startDir);
+  const { root } = parsePath(dir);
+
+  while (true) {
+    if (
+      existsSync(join(dir, '.git')) ||
+      existsSync(join(dir, 'CLAUDE.md')) ||
+      existsSync(join(dir, 'AGENTS.md'))
+    ) {
+      return dir;
+    }
+    const parent = dirname(dir);
+    if (parent === dir || dir === root) {
+      // Reached filesystem root without finding a project root — return cwd
+      return resolve(startDir);
+    }
+    dir = parent;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Config file resolution (mirrors parse-config.sh lines 31-47)
+// ---------------------------------------------------------------------------
+
+function resolveConfigFile(argPath) {
+  if (argPath) {
+    const abs = resolve(argPath);
+    if (!existsSync(abs)) {
+      process.stderr.write(`parse-config.mjs: File not found: ${argPath}\n`);
+      process.exit(1);
+    }
+    return abs;
+  }
+
+  const projectRoot = findProjectRoot(process.cwd());
+  const soConfigFile = process.env.SO_CONFIG_FILE;
+
+  if (soConfigFile) {
+    const candidate = join(projectRoot, soConfigFile);
+    if (existsSync(candidate)) {
+      return candidate;
+    }
+  }
+
+  const claudeMd = join(projectRoot, 'CLAUDE.md');
+  if (existsSync(claudeMd)) {
+    return claudeMd;
+  }
+
+  const agentsMd = join(projectRoot, 'AGENTS.md');
+  if (existsSync(agentsMd)) {
+    return agentsMd;
+  }
+
+  process.stderr.write('parse-config.mjs: CLAUDE.md or AGENTS.md required\n');
+  process.exit(1);
+}
+
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+
+const argPath = process.argv[2] ?? null;
+const configFile = resolveConfigFile(argPath);
+
+let content;
+try {
+  content = readFileSync(configFile, 'utf8');
+} catch (err) {
+  process.stderr.write(`parse-config.mjs: Failed to read ${configFile}: ${err.message}\n`);
+  process.exit(1);
+}
+
+let config;
+try {
+  config = parseSessionConfig(content);
+} catch (err) {
+  process.stderr.write(`parse-config.mjs: Parse error: ${err.message}\n`);
+  process.exit(1);
+}
+
+// jq -n produces pretty-printed JSON without a trailing newline — match that format
+const assembledJson = JSON.stringify(config, null, 2);
+
+// ---------------------------------------------------------------------------
+// Validation gate (mirrors parse-config.sh lines 281-286)
+// ---------------------------------------------------------------------------
+
+const validatorPath = join(SCRIPT_DIR, 'validate-config.mjs');
+const skipValidation = process.env.SO_SKIP_CONFIG_VALIDATION === '1';
+
+if (!skipValidation && existsSync(validatorPath)) {
+  // Use spawnSync so we can capture both stdout and stderr regardless of exit code
+  const result = spawnSync('node', [validatorPath], {
+    input: assembledJson,
+    encoding: 'utf8',
+    stdio: ['pipe', 'pipe', 'pipe'],
+  });
+
+  if (result.error) {
+    process.stderr.write(`parse-config.mjs: Failed to run validator: ${result.error.message}\n`);
+    process.exit(1);
+  }
+
+  // Relay validator stderr (warnings or errors) to our stderr
+  if (result.stderr) {
+    process.stderr.write(result.stderr);
+  }
+
+  if (result.status !== 0) {
+    // strict enforcement: validator exited non-zero → suppress stdout, exit 1
+    process.exit(1);
+  }
+
+  // Emit whatever the validator wrote to stdout (validate-config.mjs passes through raw input)
+  process.stdout.write(result.stdout);
+} else {
+  // Match jq -n output: no trailing newline
+  process.stdout.write(assembledJson);
+}

package/scripts/pi-install.mjs

@@ -0,0 +1,117 @@
+#!/usr/bin/env node
+/**
+ * pi-install.mjs — Register Session Orchestrator as a Pi package.
+ *
+ * Usage:
+ *   node scripts/pi-install.mjs [TARGET] [--global] [--settings-only]
+ *
+ * Default mode writes project-local settings to TARGET/.pi/settings.json and,
+ * when the `pi` binary is available, delegates to `pi install <source> -l`.
+ * `--settings-only` skips the binary call so CI and fresh machines can validate
+ * the package registration path without a global Pi install.
+ */
+
+import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+
+import { die } from './lib/common.mjs';
+
+const __filename = fileURLToPath(import.meta.url);
+const SCRIPT_DIR = path.dirname(__filename);
+const SO_ROOT = path.dirname(SCRIPT_DIR);
+
+const args = process.argv.slice(2);
+const globalMode = args.includes('--global');
+const settingsOnly = args.includes('--settings-only');
+const positional = args.filter((arg) => !arg.startsWith('--'));
+const target = positional[0] ? path.resolve(positional[0]) : process.cwd();
+const piAgentHome = process.env.PI_AGENT_HOME
+  ? path.resolve(process.env.PI_AGENT_HOME)
+  : path.join(os.homedir(), '.pi', 'agent');
+
+function readSettings(filePath) {
+  if (!existsSync(filePath)) return {};
+  try {
+    return JSON.parse(readFileSync(filePath, 'utf8'));
+  } catch (e) {
+    die(`Failed to parse ${filePath}: ${e.message}`);
+  }
+}
+
+function upsertPackage(settings, source) {
+  const next = { ...settings };
+  const packages = Array.isArray(next.packages) ? [...next.packages] : [];
+  const hasSource = packages.some((entry) => {
+    if (typeof entry === 'string') return entry === source;
+    return entry && typeof entry === 'object' && entry.source === source;
+  });
+  if (!hasSource) packages.push(source);
+  next.packages = packages;
+  return next;
+}
+
+function writeSettings(filePath, settings) {
+  mkdirSync(path.dirname(filePath), { recursive: true });
+  writeFileSync(filePath, JSON.stringify(settings, null, 2) + '\n', 'utf8');
+}
+
+function isDirectory(filePath) {
+  try {
+    return statSync(filePath).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+function commandAvailable(command) {
+  const lookup = process.platform === 'win32'
+    ? spawnSync('where', [command], { stdio: 'ignore' })
+    : spawnSync('sh', ['-c', `command -v ${command}`], { stdio: 'ignore' });
+  return lookup.status === 0;
+}
+
+const settingsPath = globalMode
+  ? path.join(piAgentHome, 'settings.json')
+  : path.join(target, '.pi', 'settings.json');
+const source = SO_ROOT;
+
+if (!globalMode && !isDirectory(target)) {
+  die(`Target project directory does not exist: ${target}`);
+}
+
+process.stdout.write('Session Orchestrator — Pi Setup\n');
+process.stdout.write('===============================\n');
+process.stdout.write('\n');
+process.stdout.write(`Source:   ${source}\n`);
+process.stdout.write(`Settings: ${settingsPath}\n`);
+process.stdout.write(`Scope:    ${globalMode ? 'global' : 'project-local'}\n`);
+process.stdout.write('\n');
+
+if (!settingsOnly) {
+  if (!commandAvailable('pi')) {
+    die('pi is required for install mode. Install @earendil-works/pi-coding-agent or rerun with --settings-only.');
+  }
+  const piArgs = ['install', source];
+  if (!globalMode) piArgs.push('-l');
+  const result = spawnSync('pi', piArgs, {
+    cwd: target,
+    encoding: 'utf8',
+    stdio: 'inherit',
+  });
+  if (result.status !== 0) {
+    process.exit(result.status ?? 1);
+  }
+}
+
+const settings = upsertPackage(readSettings(settingsPath), source);
+writeSettings(settingsPath, settings);
+
+process.stdout.write('Done. Session Orchestrator registered as a Pi package.\n');
+process.stdout.write('\n');
+process.stdout.write('Next steps:\n');
+process.stdout.write('  1. Trust the project in Pi when prompted so project-local package resources can load.\n');
+process.stdout.write('  2. Restart or /reload Pi.\n');
+process.stdout.write('  3. Use /session deep, /plan feature, /discovery, or /go from the Pi prompt menu.\n');

package/scripts/print-applicable-rules.mjs

@@ -0,0 +1,247 @@
+#!/usr/bin/env node
+/**
+ * print-applicable-rules.mjs — thin CLI wrapper around the #336 rule-loader.
+ *
+ * Wires the dormant `loadApplicableRules()` (scripts/lib/rule-loader.mjs) into
+ * the wave-executor's per-wave agent-prompt assembly (Epic #693 FA1 / #694).
+ * The wave-executor is coordinator-LLM prose, not an executable — so this CLI
+ * is the concrete, testable bridge: the coordinator runs it once per wave
+ * (after `wave-scope.json` is written, before assembling the Agent() prompt),
+ * captures stdout as the injectable `<APPLICABLE-RULES>` block, and prepends
+ * it to each dispatched agent's prompt.
+ *
+ * Resolution:
+ *   - scopePaths ← `allowedPaths` from `.claude/wave-scope.json`
+ *                  (override: --wave-scope <path>)
+ *   - mode       ← `session-type:` frontmatter in `.claude/STATE.md`
+ *                  (override: --mode <m>; unreadable → null = no mode gating)
+ *   - hostClass  ← `host_class` from `.orchestrator/host.json` via readHostClass
+ *                  (override: --host-class <c>; unreadable → null = no gating)
+ *   - rulesDir   ← <repoRoot>/.claude/rules
+ *
+ * Output:
+ *   - default      → an injectable Markdown block (header + each rule's raw
+ *                    content, separated by `\n\n---\n\n`). Empty match set →
+ *                    no output (exit 0) so the caller injects nothing.
+ *   - --json       → `{ count, rules: [{path, alwaysOn, matchedGlobs}] }`
+ *
+ * Exit codes (per .claude/rules/cli-design.md):
+ *   0 — success
+ *   1 — user/input error (bad --wave-scope path, malformed wave-scope JSON)
+ *   2 — system error (unexpected internal failure)
+ * Data → stdout, diagnostics → stderr.
+ *
+ * Best-effort by design: a missing rules dir, missing STATE.md, or missing
+ * host.json each degrade to "no gating / no rules" rather than failing — the
+ * wave-executor caller treats any non-zero exit as "inject nothing, continue".
+ *
+ * Related: issue #336 (glob-scoped rules), #694 (rule-activation / FA1),
+ *   scripts/lib/rule-loader.mjs (loadApplicableRules),
+ *   scripts/lib/autopilot/telemetry.mjs (readHostClass),
+ *   docs/rule-authoring.md (frontmatter authoring guide).
+ */
+
+import { parseArgs } from 'node:util';
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { findProjectRoot } from './lib/common.mjs';
+import { loadApplicableRules } from './lib/rule-loader.mjs';
+import { readHostClass } from './lib/autopilot/telemetry.mjs';
+
+const HELP = `Usage: node scripts/print-applicable-rules.mjs [options]
+
+Prints the glob-scoped + always-on rule set applicable to the current wave,
+as an injectable Markdown block, for the wave-executor to prepend to each
+dispatched agent's prompt (#336 / #694).
+
+Options:
+  --wave-scope <path>   Path to wave-scope.json (default: .claude/wave-scope.json).
+                        Its "allowedPaths" array is used as scopePaths.
+  --mode <m>            Override session mode (default: session-type: from
+                        .claude/STATE.md; unreadable -> no mode gating).
+  --host-class <c>      Override host class (default: host_class from
+                        .orchestrator/host.json; unreadable -> no gating).
+  --context <c>         Caller context for tier gating: 'wave' | 'coordinator'.
+                        When absent (default), tier gating is disabled and all
+                        rules are included regardless of their tier: frontmatter.
+                        Pass --context wave to exclude coordinator-only rules;
+                        pass --context coordinator to exclude wave-only rules.
+  --json                Emit { count, rules:[{path,alwaysOn,matchedGlobs}] }
+                        instead of the Markdown block.
+  --help, -h            Show this help and exit 0.
+
+Exit codes:
+  0  success
+  1  user/input error (bad --wave-scope path or malformed JSON)
+  2  system error
+`;
+
+/**
+ * Print an error to stderr and exit with the given code.
+ * @param {string} message
+ * @param {number} code
+ * @returns {never}
+ */
+function fail(message, code) {
+  process.stderr.write(`ERROR: ${message}\n`);
+  process.exit(code);
+}
+
+// ---------------------------------------------------------------------------
+// Parse argv
+// ---------------------------------------------------------------------------
+
+const rawArgv = process.argv.slice(2);
+if (rawArgv.includes('--help') || rawArgv.includes('-h')) {
+  process.stdout.write(HELP);
+  process.exit(0);
+}
+
+let parsed;
+try {
+  parsed = parseArgs({
+    args: rawArgv,
+    options: {
+      'wave-scope':  { type: 'string' },
+      mode:          { type: 'string' },
+      'host-class':  { type: 'string' },
+      context:       { type: 'string' },
+      json:          { type: 'boolean', default: false },
+    },
+    strict: true,
+  });
+} catch (err) {
+  fail(`Failed to parse arguments: ${err.message}`, 1);
+}
+
+const opts = parsed.values;
+
+// ---------------------------------------------------------------------------
+// Resolve repo root + canonical paths
+// ---------------------------------------------------------------------------
+
+const repoRoot = findProjectRoot(process.cwd());
+const rulesDir = join(repoRoot, '.claude', 'rules');
+const waveScopePath = opts['wave-scope']
+  ? opts['wave-scope']
+  : join(repoRoot, '.claude', 'wave-scope.json');
+const stateMdPath = join(repoRoot, '.claude', 'STATE.md');
+const hostJsonPath = join(repoRoot, '.orchestrator', 'host.json');
+
+// ---------------------------------------------------------------------------
+// scopePaths ← wave-scope.json allowedPaths
+// ---------------------------------------------------------------------------
+//
+// A user-supplied --wave-scope that does not exist or is malformed is a
+// user/input error (exit 1). The DEFAULT path is allowed to be absent — some
+// waves run before wave-scope.json is written — in which case we degrade to an
+// empty scope (only always-on rules match) rather than failing.
+
+let scopePaths = [];
+const waveScopeExplicit = Boolean(opts['wave-scope']);
+let waveScopeRaw;
+try {
+  waveScopeRaw = readFileSync(waveScopePath, 'utf8');
+} catch (err) {
+  if (waveScopeExplicit) {
+    fail(`Cannot read --wave-scope ${waveScopePath}: ${err.message}`, 1);
+  }
+  // Default path absent → no scope (always-on only). Diagnostic to stderr.
+  process.stderr.write(
+    `[print-applicable-rules] wave-scope not found at ${waveScopePath} — using empty scope (always-on rules only)\n`,
+  );
+  waveScopeRaw = null;
+}
+
+if (waveScopeRaw !== null) {
+  let waveScope;
+  try {
+    waveScope = JSON.parse(waveScopeRaw);
+  } catch (err) {
+    fail(`Malformed JSON in wave-scope ${waveScopePath}: ${err.message}`, 1);
+  }
+  const allowed = waveScope?.allowedPaths;
+  if (Array.isArray(allowed)) {
+    scopePaths = allowed.filter((p) => typeof p === 'string' && p.length > 0);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// mode ← --mode override | session-type: from STATE.md | null
+// ---------------------------------------------------------------------------
+
+/** @type {string|null} */
+let mode = null;
+if (opts.mode !== undefined && opts.mode !== '') {
+  mode = opts.mode;
+} else {
+  try {
+    const stateRaw = readFileSync(stateMdPath, 'utf8');
+    // STATE.md frontmatter is a simple `key: value` block delimited by `---`.
+    // Read only the `session-type:` scalar — no full YAML parse needed.
+    const fmMatch = /^---\r?\n([\s\S]*?)\r?\n---/.exec(stateRaw);
+    const fmText = fmMatch ? fmMatch[1] : stateRaw;
+    const typeMatch = /^session-type:\s*(.+?)\s*$/m.exec(fmText);
+    if (typeMatch) {
+      const v = typeMatch[1].replace(/^["']|["']$/g, '').trim();
+      if (v) mode = v;
+    }
+  } catch {
+    // STATE.md unreadable → leave mode null (no mode gating).
+  }
+}
+
+// ---------------------------------------------------------------------------
+// hostClass ← --host-class override | host.json | null
+// ---------------------------------------------------------------------------
+
+/** @type {string|null} */
+const hostClass =
+  opts['host-class'] !== undefined && opts['host-class'] !== ''
+    ? opts['host-class']
+    : readHostClass(hostJsonPath); // null on any I/O or parse error
+
+// ---------------------------------------------------------------------------
+// context ← --context override | null (default = no tier gating)
+// ---------------------------------------------------------------------------
+//
+// CRITICAL: when --context is NOT passed, context remains null and tier gating
+// is fully disabled — existing behaviour is preserved, existing tests stay green.
+
+/** @type {string|null} */
+const context = opts.context !== undefined && opts.context !== '' ? opts.context : null;
+
+// ---------------------------------------------------------------------------
+// Load + emit
+// ---------------------------------------------------------------------------
+
+let rules;
+try {
+  rules = loadApplicableRules({ rulesDir, scopePaths, mode, hostClass, context });
+} catch (err) {
+  fail(`Rule loading failed: ${err.message}`, 2);
+}
+
+if (opts.json) {
+  const out = {
+    count: rules.length,
+    rules: rules.map((r) => ({
+      path: r.path,
+      alwaysOn: r.alwaysOn,
+      matchedGlobs: r.matchedGlobs,
+    })),
+  };
+  process.stdout.write(JSON.stringify(out, null, 2) + '\n');
+  process.exit(0);
+}
+
+// Markdown block. Empty match set → print nothing (caller injects nothing).
+if (rules.length === 0) {
+  process.exit(0);
+}
+
+const header = '## Applicable Rules (scoped to this wave)';
+const body = rules.map((r) => r.content.trimEnd()).join('\n\n---\n\n');
+process.stdout.write(`${header}\n\n${body}\n`);
+process.exit(0);