@sublang/playbook 0.9.0 → 1.0.0

package/reference/sdlc/code.playbook/bin/playbook.js

@@ -31,6 +31,10 @@ const ADAPTER_SHORTHANDS = ['claude', 'codex'];
 // PBCLI-8: launcher-owned keys inside a `playbooks.<id>` block; every other
 // key belongs to that playbook's option slice.
 const PLAYBOOK_LAUNCHER_KEYS = ['from', 'command', 'players'];
+const RESERVED_CAPTAIN_PLAYBOOK_ID = 'captain';
+// PBCLI-9: the bare `captain` id names the tmux-play host Captain, so no
+// playbook-local role may take it.
+const RESERVED_CAPTAIN_ROLE_ID = 'captain';
 const READINESS_FAILURE_EXIT_CODE = 2;
 const COMPOSITION_FAILURE_EXIT_CODE = 1;
 
@@ -39,9 +43,25 @@ export async function runPlaybookCli(options = {}) {
   const env = options.env ?? process.env;
   const stdout = options.stdout ?? process.stdout;
   const stderr = options.stderr ?? process.stderr;
+  const loadModule = options.loadModule ?? ((specifier) => import(specifier));
+
+  // PBCLI-18: `playbook run ...` is the non-interactive one-shot path; it
+  // never seeds, composes, resolves tmux-play, or launches it.
+  if (argv[0] === 'run') {
+    const { runPlaybookRun } = await import('./run.js');
+    return await runPlaybookRun({
+      argv: argv.slice(1),
+      stdout,
+      stderr,
+      ...(options.loadModule ? { loadModule: options.loadModule } : {}),
+      ...(options.createAgent ? { createAgent: options.createAgent } : {}),
+      ...(options.readStdin ? { readStdin: options.readStdin } : {}),
+      ...(options.sessionsDir ? { sessionsDir: options.sessionsDir } : {}),
+    });
+  }
+
   const spawnFn = options.spawn ?? spawn;
   const tmuxPlayBin = options.tmuxPlayBin ?? resolveTmuxPlayBin();
-  const loadModule = options.loadModule ?? ((specifier) => import(specifier));
   const home = options.homeDir ?? env.HOME ?? homedir();
   const userConfigPath = resolveUserConfigPath(env, home);
 
@@ -52,6 +72,25 @@ export async function runPlaybookCli(options = {}) {
     return { code: 0 };
   }
 
+  // PBCLI-25/26: `--with <path>` overlays are launcher-owned — consumed
+  // here, never forwarded to tmux-play, and incompatible with a raw
+  // `--config` launch, which bypasses the composition they target.
+  let withPaths;
+  let forwardArgv;
+  try {
+    ({ withPaths, rest: forwardArgv } = extractWithFlags(argv));
+  } catch (error) {
+    stderr.write(`playbook: ${errorMessage(error)}\n`);
+    return { code: COMPOSITION_FAILURE_EXIT_CODE };
+  }
+  if (withPaths.length > 0 && hasExplicitConfig(argv)) {
+    stderr.write(
+      'playbook: --with overlays the top-level config and cannot combine ' +
+        'with a raw --config launch\n',
+    );
+    return { code: COMPOSITION_FAILURE_EXIT_CODE };
+  }
+
   // PBCLI-1: explicit `--config <path>` launches that raw tmux-play config
   // directly, bypassing seeding, composition, and the readiness gate.
   if (hasExplicitConfig(argv)) {
@@ -62,10 +101,16 @@ export async function runPlaybookCli(options = {}) {
 
   let composed;
   try {
-    composed = await composeGenericConfig(
-      parseYaml(readFileSync(userConfigPath, 'utf8')) ?? {},
-      loadModule,
-    );
+    let top = parseYaml(readFileSync(userConfigPath, 'utf8')) ?? {};
+    if (withPaths.length > 0 && !isObject(top)) {
+      throw new Error(
+        `the top-level config at ${userConfigPath} must be a YAML map before --with can overlay it`,
+      );
+    }
+    for (const overlayPath of withPaths) {
+      top = mergeConfigs(top, loadOverlayFragment(overlayPath));
+    }
+    composed = await composeGenericConfig(top, loadModule);
   } catch (error) {
     stderr.write(`playbook: ${errorMessage(error)}\n`);
     return { code: COMPOSITION_FAILURE_EXIT_CODE };
@@ -104,7 +149,7 @@ export async function runPlaybookCli(options = {}) {
   try {
     return await launchTmuxPlay(
       spawnFn,
-      [tmuxPlayBin, '--config', composedPath, ...argv],
+      [tmuxPlayBin, '--config', composedPath, ...forwardArgv],
       stderr,
     );
   } finally {
@@ -112,6 +157,72 @@ export async function runPlaybookCli(options = {}) {
   }
 }
 
+// PBCLI-26: split `--with <path>` pairs out of the argument vector so
+// they are consumed by the launcher rather than forwarded to tmux-play.
+function extractWithFlags(argv) {
+  const withPaths = [];
+  const rest = [];
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === '--with') {
+      const value = argv[i + 1];
+      if (value === undefined || value === '') {
+        throw new Error('--with needs a value');
+      }
+      withPaths.push(value);
+      i += 1;
+    } else if (arg.startsWith('--with=')) {
+      const value = arg.slice('--with='.length);
+      if (!value) throw new Error('--with needs a value');
+      withPaths.push(value);
+    } else {
+      rest.push(arg);
+    }
+  }
+  return { withPaths, rest };
+}
+
+// PBCLI-25: an overlay fragment is a top-level-format YAML map.
+function loadOverlayFragment(overlayPath) {
+  const resolved = resolve(overlayPath);
+  let text;
+  try {
+    text = readFileSync(resolved, 'utf8');
+  } catch (error) {
+    throw new Error(
+      `cannot read --with overlay ${overlayPath}: ${errorMessage(error)}`,
+    );
+  }
+  let fragment;
+  try {
+    fragment = parseYaml(text);
+  } catch (error) {
+    throw new Error(
+      `cannot parse --with overlay ${overlayPath}: ${errorMessage(error)}`,
+    );
+  }
+  if (!isObject(fragment)) {
+    throw new Error(`--with overlay ${overlayPath} must be a YAML map`);
+  }
+  return fragment;
+}
+
+// PBCLI-25/26: recursive merge for plain maps, replacement for every
+// other value; neither input is mutated. Object.fromEntries defines own
+// data properties, so a hostile fragment key such as __proto__ cannot
+// reach the prototype.
+function mergeConfigs(base, overlay) {
+  return Object.fromEntries([
+    ...Object.entries(base),
+    ...Object.entries(overlay).map(([key, value]) => [
+      key,
+      isObject(base[key]) && isObject(value)
+        ? mergeConfigs(base[key], value)
+        : value,
+    ]),
+  ]);
+}
+
 export function resolveConfigHome(env = process.env, home = homedir()) {
   return env.XDG_CONFIG_HOME || join(home, '.config');
 }
@@ -152,9 +263,6 @@ function isValidRegistryEntry(value) {
     typeof value.command === 'string' &&
     typeof value.intent === 'string' &&
     Array.isArray(value.requiredRoleIds) &&
-    typeof value.idleStateId === 'string' &&
-    typeof value.finalStateId === 'string' &&
-    Array.isArray(value.parkStateIds) &&
     typeof value.validateOptions === 'function' &&
     typeof value.createRuntime === 'function'
   );
@@ -196,6 +304,11 @@ export async function composeGenericConfig(top, loadModule) {
   let firstVisible;
 
   for (const id of ids) {
+    if (id === RESERVED_CAPTAIN_PLAYBOOK_ID) {
+      throw new Error(
+        `playbooks.${id} collides with the reserved internal Captain id`,
+      );
+    }
     const block = requireObject(playbooksCfg[id], `playbooks.${id}`);
     const from = block.from;
     if (typeof from !== 'string' || from.length === 0) {
@@ -229,13 +342,35 @@ export async function composeGenericConfig(top, loadModule) {
       typeof block.command === 'string' && block.command.length > 0
         ? block.command
         : entry.command;
+    if (command === RESERVED_CAPTAIN_PLAYBOOK_ID) {
+      throw new Error(
+        `playbooks.${id}.command collides with the reserved internal Captain command`,
+      );
+    }
     if (seenCommands.has(command)) {
       throw new Error(`duplicate effective command "${command}"`);
     }
     seenCommands.set(command, id);
 
+    // PBCLI-9: reject the reserved role before the coverage checks below, so
+    // an entry requiring `captain` names the real fault rather than a missing
+    // players entry.
+    if (entry.requiredRoleIds.includes(RESERVED_CAPTAIN_ROLE_ID)) {
+      throw new Error(
+        `playbooks.${id} requires local role "${RESERVED_CAPTAIN_ROLE_ID}", ` +
+          'which is reserved for the tmux-play Captain',
+      );
+    }
+
     const playersMap = requireObject(block.players, `playbooks.${id}.players`);
     const roles = Object.keys(playersMap);
+    if (roles.includes(RESERVED_CAPTAIN_ROLE_ID)) {
+      throw new Error(
+        `playbooks.${id}.players.${RESERVED_CAPTAIN_ROLE_ID} binds local ` +
+          `role "${RESERVED_CAPTAIN_ROLE_ID}", which is reserved for the ` +
+          'tmux-play Captain',
+      );
+    }
     if (roles.length === 0) {
       throw new Error(`playbooks.${id} resolves no visible local role`);
     }
@@ -348,11 +483,18 @@ function helpText({ userConfigPath, failingAdapters = [] }) {
   return [
     ...failures,
     'Usage:',
-    '  playbook [--list] [--config <path>] [tmux-play options]',
+    '  playbook [--list] [--with <path>]... [--config <path>] [tmux-play options]',
+    '  playbook run <from> [task] [options]   # non-interactive one-shot',
+    '  playbook run resume <session-id> [reply]   # answer a parked run',
     '  playbook --help',
     '',
     `Default config: ${userConfigPath}`,
     '',
+    '  --with <path> overlays a top-level config fragment (same format as',
+    '  the default config) over the default config for this launch only —',
+    '  maps merge recursively, other values replace, later files win. The',
+    '  default config file is never modified.',
+    '',
     'Adapter setup:',
     '  claude: run Claude Code once or set ANTHROPIC_API_KEY.',
     '  codex: run Codex CLI once or set OPENAI_API_KEY.',