@sublang/playbook 2.0.0 → 3.1.0

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

@@ -17,7 +17,11 @@ import {
 import { homedir, tmpdir } from 'node:os';
 import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { parse as parseYaml, stringify as stringifyYaml } from 'yaml';
+import {
+  parse as parseYaml,
+  parseDocument as parseYamlDocument,
+  stringify as stringifyYaml,
+} from 'yaml';
 
 const here = dirname(fileURLToPath(import.meta.url));
 const templatePath = resolve(here, '..', 'playbook.config.template.yaml');
@@ -25,8 +29,8 @@ const templatePath = resolve(here, '..', 'playbook.config.template.yaml');
 // PBCLI-1/8: the launcher composes a tmux-play config whose Captain is the
 // Playbook Captain shell adapter module.
 export const PLAYBOOK_CAPTAIN_MODULE = '@sublang/playbook/playbook-captain';
-// PBCLI-8/12: known adapter shorthands. A `profiles` id may not collide
-// with one of these, and these are the adapters with readiness predicates.
+// PBCLI-12: known adapter shorthands — the adapters with readiness
+// predicates.
 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.
@@ -63,6 +67,7 @@ export async function runPlaybookCli(options = {}) {
       ...(options.createAgent ? { createAgent: options.createAgent } : {}),
       ...(options.readStdin ? { readStdin: options.readStdin } : {}),
       ...(options.sessionsDir ? { sessionsDir: options.sessionsDir } : {}),
+      ...(options.hostRoots ? { hostRoots: options.hostRoots } : {}),
     });
   }
 
@@ -103,6 +108,15 @@ export async function runPlaybookCli(options = {}) {
 
   seedUserConfigIfMissing(userConfigPath, stderr);
 
+  // DR-021 §3: an existing profiles-based config is rewritten in place once,
+  // with the original kept beside it, so the user launches without editing.
+  try {
+    migrateUserConfigIfRetired(userConfigPath, stderr);
+  } catch (error) {
+    stderr.write(`playbook: ${errorMessage(error)}\n`);
+    return { code: COMPOSITION_FAILURE_EXIT_CODE };
+  }
+
   let composed;
   try {
     let top = parseYaml(readFileSync(userConfigPath, 'utf8')) ?? {};
@@ -114,7 +128,7 @@ export async function runPlaybookCli(options = {}) {
     for (const overlayPath of withPaths) {
       top = mergeConfigs(top, loadOverlayFragment(overlayPath));
     }
-    composed = await composeGenericConfig(top, loadModule);
+    composed = await composeGenericConfig(top, loadModule, userConfigPath);
   } catch (error) {
     stderr.write(`playbook: ${errorMessage(error)}\n`);
     return { code: COMPOSITION_FAILURE_EXIT_CODE };
@@ -235,29 +249,213 @@ export function resolveUserConfigPath(env = process.env, home = homedir()) {
   return join(resolveConfigHome(env, home), 'playbook', 'playbook.config.yaml');
 }
 
-// PBCLI-8: resolve a scalar `captain` / `players.<role>` value as a profile
-// id or adapter shorthand, or a full agent block whose optional `profile`
-// key names a `profiles` entry whose settings are the base under the block's
-// own explicit fields. The composed block carries no `profile` key.
-export function resolveAgent(value, profiles, path) {
-  if (typeof value === 'string') {
-    if (hasOwn(profiles, value)) return { ...profiles[value] };
-    return { adapter: value };
+// PBCLI-8 (DR-021): a scalar `captain` / `players.<role>` value is an
+// adapter shorthand; a full block is a self-contained tmux-play agent block
+// carrying its own adapter/model/effort/permissions. There is no profile
+// indirection, so retuning one agent cannot change another.
+export function resolveAgent(value, path) {
+  if (typeof value === 'string') return { adapter: value };
+  if (isObject(value)) return { ...value };
+  throw new Error(`${path} must be an adapter shorthand or an agent block`);
+}
+
+// DR-021 §3: migrate the user's config on disk, once, keeping the original.
+// The backup is written before the rewrite and never overwrites an existing
+// file, so a prior backup — or a user's own .bak — cannot be lost.
+function migrateUserConfigIfRetired(userConfigPath, stderr) {
+  let text;
+  try {
+    text = readFileSync(userConfigPath, 'utf8');
+  } catch {
+    return;
   }
-  if (isObject(value)) {
-    const { profile, ...rest } = value;
-    let base = {};
-    if (profile !== undefined) {
-      if (typeof profile !== 'string' || !hasOwn(profiles, profile)) {
-        throw new Error(`${path}.profile must name a profiles entry`);
+  let migrated;
+  try {
+    migrated = migrateRetiredProfiles(text);
+  } catch (error) {
+    throw new Error(
+      `cannot migrate the retired profiles config at ${userConfigPath}: ` +
+        `${errorMessage(error)} — edit it by hand: each agent takes its own ` +
+        'adapter, model, effort, and permissions',
+    );
+  }
+  if (migrated === undefined) return;
+  const backupPath = freeBackupPath(userConfigPath);
+  writeFileSync(backupPath, text, { mode: 0o600 });
+  writeFileSync(userConfigPath, migrated);
+  stderr.write(
+    `playbook: migrated ${userConfigPath} to inline agent settings ` +
+      `(the top-level "profiles" map was removed in 3.0.0); ` +
+      `the original is at ${backupPath}\n`,
+  );
+}
+
+function freeBackupPath(userConfigPath) {
+  const first = `${userConfigPath}.bak`;
+  if (!existsSync(first)) return first;
+  for (let n = 2; ; n += 1) {
+    const candidate = `${userConfigPath}.bak.${n}`;
+    if (!existsSync(candidate)) return candidate;
+  }
+}
+
+// DR-021 §3: rewrite a config written for the retired profiles model in
+// place, inlining each agent's settings and keeping the original beside it.
+// Edits go through the YAML Document API so the user's comments survive;
+// only the profiles block and its own commentary are removed. Returns the
+// migrated text, or undefined when there is nothing to migrate.
+export function migrateRetiredProfiles(text) {
+  const doc = parseYamlDocument(text);
+  const contents = doc.contents;
+  if (!contents || !Array.isArray(contents.items)) return undefined;
+  const profiles = doc.get('profiles');
+  const agentPaths = [['captain']];
+  const playbooks = doc.get('playbooks');
+  if (playbooks && Array.isArray(playbooks.items)) {
+    for (const entry of playbooks.items) {
+      const id = String(entry.key);
+      const players = doc.getIn(['playbooks', id, 'players']);
+      if (!players || !Array.isArray(players.items)) continue;
+      for (const player of players.items) {
+        agentPaths.push(['playbooks', id, 'players', String(player.key)]);
+      }
+    }
+  }
+
+  const profileSettings = (name) =>
+    profiles && typeof profiles.get === 'function'
+      ? profiles.get(name)
+      : undefined;
+
+  let changed = false;
+  for (const path of agentPaths) {
+    const node = doc.getIn(path, true);
+    if (node && typeof node.value === 'string' && !Array.isArray(node.items)) {
+      // A scalar that named a profile; a bare adapter shorthand stays.
+      const settings = profileSettings(node.value);
+      if (settings === undefined) continue;
+      const inlined = settings.clone();
+      // The scalar carried any comment on that line, and replacing the node
+      // would drop it. Re-attach it above the block that replaces it.
+      carryScalarComment(node, inlined);
+      doc.setIn(path, inlined);
+      changed = true;
+    } else if (node && Array.isArray(node.items)) {
+      const named = node.get?.('profile');
+      if (named === undefined) continue;
+      const settings = profileSettings(named);
+      if (settings === undefined) {
+        throw new Error(
+          `${path.join('.')}.profile names "${String(named)}", which no ` +
+            'profiles entry defines',
+        );
       }
-      base = { ...profiles[profile] };
+      // Fill the block from its profile in place — never rebuild it — so
+      // the user's own keys, ordering, and comments survive untouched. The
+      // block's own fields stay authoritative, so only absent keys are added.
+      node.delete('profile');
+      for (const item of settings.items) {
+        if (node.has(String(item.key))) continue;
+        // Append the whole pair, not a rebuilt key/value: a comment above a
+        // setting rides on that setting's key node, so stringifying the key
+        // would drop it.
+        node.add(item.clone());
+      }
+      changed = true;
+    }
+  }
+
+  if (profiles !== undefined) {
+    // The comment block above `profiles` usually carries the file's own
+    // header, which must outlive the removed section: keep every paragraph
+    // except the last, which documents profiles themselves.
+    const index = contents.items.findIndex(
+      (item) => String(item.key) === 'profiles',
+    );
+    const lead = index === -1 ? undefined : contents.items[index]?.key
+      ?.commentBefore;
+    doc.delete('profiles');
+    const header = keptHeaderComment(lead);
+    const next = contents.items[0];
+    if (header !== undefined && next?.key) {
+      next.key.commentBefore =
+        next.key.commentBefore === undefined
+          ? header
+          : `${header}\n\n${next.key.commentBefore}`;
     }
-    return { ...base, ...rest };
+    changed = true;
   }
-  throw new Error(
-    `${path} must be a profile id, an adapter shorthand, or an agent block`,
+  if (!changed) return undefined;
+  // Say what happened at the top of the file the user will open next:
+  // some of their remaining comments describe the retired model.
+  doc.commentBefore = MIGRATION_NOTE;
+  return doc.toString();
+}
+
+const MIGRATION_NOTE =
+  ' Migrated by playbook 3.0.0: the top-level `profiles` map was removed and\n' +
+  ' each agent now carries its settings inline. The pre-migration file is\n' +
+  ' kept beside this one as a .bak. Comments below may still describe the\n' +
+  ' retired profiles model.';
+
+// Move a scalar agent's own comments onto the block that replaces it, so
+// `captain: base # the judge` keeps its note. The pair's key comments are
+// untouched by the replacement and need no carrying.
+function carryScalarComment(node, inlined) {
+  const parts = [node.commentBefore, node.comment].filter(
+    (part) => typeof part === 'string' && part.trim() !== '',
   );
+  if (parts.length === 0) return;
+  const first = inlined.items?.[0]?.key;
+  if (!first) return;
+  // A flow map carrying a comment renders as a multi-line brace block; the
+  // ordinary block form is what the rest of the config looks like.
+  inlined.flow = false;
+  const carried = parts.join('\n');
+  first.commentBefore =
+    first.commentBefore === undefined
+      ? carried
+      : `${carried}\n${first.commentBefore}`;
+}
+
+// Drop the trailing paragraph — the one describing the profiles block —
+// and keep the rest of the leading comment (SPDX header, file overview).
+function keptHeaderComment(comment) {
+  if (typeof comment !== 'string' || comment.trim() === '') return undefined;
+  const paragraphs = comment.split('\n\n');
+  const kept = paragraphs.slice(0, -1).join('\n\n');
+  return kept.trim() === '' ? undefined : kept;
+}
+
+// A `profile` key that survives migration — introduced by a `--with`
+// overlay rather than the user's own config — is still rejected.
+function assertNoRetiredProfiles(top, configPath) {
+  const where = configPath ? ` in ${configPath}` : '';
+  if (top.profiles !== undefined) {
+    throw new Error(
+      `top-level "profiles" was removed${where}: write each agent's settings ` +
+        'inline under captain and each playbooks.<id>.players.<role> ' +
+        '(adapter, model, effort, permissions)',
+    );
+  }
+  const blocks = [['captain', top.captain]];
+  const playbooksCfg = isObject(top.playbooks) ? top.playbooks : {};
+  for (const [id, block] of Object.entries(playbooksCfg)) {
+    const playersMap = isObject(block) && isObject(block.players)
+      ? block.players
+      : {};
+    for (const [role, agent] of Object.entries(playersMap)) {
+      blocks.push([`playbooks.${id}.players.${role}`, agent]);
+    }
+  }
+  for (const [path, block] of blocks) {
+    if (isObject(block) && block.profile !== undefined) {
+      throw new Error(
+        `${path}.profile was removed${where}: write the agent's settings ` +
+          'inline in that block (adapter, model, effort, permissions)',
+      );
+    }
+  }
 }
 
 function isValidRegistryEntry(value) {
@@ -272,19 +470,12 @@ function isValidRegistryEntry(value) {
   );
 }
 
-// PBCLI-8/9/10: normalize the top-level `profiles` / `playbooks` config into
+// PBCLI-8/9/10: normalize the top-level `playbooks` config into
 // a tmux-play config (Captain = the shell adapter; `captain.options.playbooks`
 // the normalized enablement; a launch-time namespaced `<id>-<role>` roster;
 // launcher-owned `layout.initialVisible`).
-export async function composeGenericConfig(top, loadModule) {
-  const profiles = isObject(top.profiles) ? top.profiles : {};
-  for (const id of Object.keys(profiles)) {
-    if (ADAPTER_SHORTHANDS.includes(id)) {
-      throw new Error(
-        `profiles.${id} collides with the "${id}" adapter shorthand`,
-      );
-    }
-  }
+export async function composeGenericConfig(top, loadModule, configPath) {
+  assertNoRetiredProfiles(top, configPath);
 
   const playbooksCfg = requireObject(top.playbooks, 'playbooks');
   const ids = Object.keys(playbooksCfg);
@@ -294,7 +485,7 @@ export async function composeGenericConfig(top, loadModule) {
 
   const captain = {
     from: PLAYBOOK_CAPTAIN_MODULE,
-    ...resolveAgent(top.captain, profiles, 'captain'),
+    ...resolveAgent(top.captain, 'captain'),
   };
   if (captain.adapter === undefined) {
     throw new Error('captain must resolve an adapter');
@@ -389,7 +580,6 @@ export async function composeGenericConfig(top, loadModule) {
     for (const role of roles) {
       const agent = resolveAgent(
         playersMap[role],
-        profiles,
         `playbooks.${id}.players.${role}`,
       );
       if (agent.adapter === undefined) {
@@ -419,7 +609,16 @@ export async function composeGenericConfig(top, loadModule) {
     listing.push({ id, command, intent: entry.intent });
   }
 
-  captain.options = { playbooks: optionsPlaybooks };
+  // DR-013 A1: the shell cannot see its own captain's adapter through the
+  // tmux-play CaptainContext, so the launcher — which resolved it — passes it
+  // through. The shell needs it to decide whether an explicit empty tool
+  // allowlist can be enforced or must degrade to prompt-level restriction.
+  captain.options = {
+    playbooks: optionsPlaybooks,
+    ...(typeof captain.adapter === 'string' && captain.adapter.length > 0
+      ? { captainAdapter: captain.adapter }
+      : {}),
+  };
   const config = { captain, players: roster };
   // PBCLI-10: carry the user's tmux-play layout window/weight fields through;
   // the launcher owns `layout.initialVisible` (first enabled playbook).
@@ -504,9 +703,9 @@ function helpText({ userConfigPath, failingAdapters = [] }) {
     '  codex: run Codex CLI once or set OPENAI_API_KEY.',
     '',
     'Agent swap recipe:',
-    '  - reuse agent settings under top-level profiles',
-    '  - point each playbooks.<id>.captain / players.<role> at a profile id',
-    '    or an adapter shorthand (claude, codex)',
+    '  - set each agent inline: the top-level captain and every',
+    '    playbooks.<id>.players.<role> takes an adapter shorthand',
+    '    (claude, codex) or a block with adapter/model/effort/permissions',
     '  - the launcher injects captain.from and the namespaced <id>-<role>',
     '    host players',
     '',

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

@@ -0,0 +1,228 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: 2026 SubLang International <https://sublang.ai>
+
+// PBCLI-36/37 (DR-024): probe-first engine provisioning for filesystem
+// registry modules. A compiled thin artifact imports `xstate` and
+// `@sublang/playbook/xstate-runtime`, which Node resolves by walking up
+// from the artifact's own directory; a globally installed host therefore
+// fails at artifact load in a bare directory. Before importing such a
+// module, `playbook run` probes both specifiers with the module's path as
+// resolution parent and, only when a probe fails, symlinks the running
+// host's own installed package roots beside the module. It never shells
+// out to `npm link` and never installs from the registry.
+
+import { existsSync, lstatSync, readFileSync, readlinkSync } from 'node:fs';
+import { mkdir, symlink, unlink } from 'node:fs/promises';
+import { createRequire } from 'node:module';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+// PBCLI-37: probe specifier → the package name provisioning may link.
+const ENGINE_LINKS = new Map([
+  ['xstate', 'xstate'],
+  ['@sublang/playbook/xstate-runtime', '@sublang/playbook'],
+]);
+
+const DEPENDENCY_FIELDS = [
+  'dependencies',
+  'devDependencies',
+  'peerDependencies',
+  'optionalDependencies',
+];
+
+// PBCLI-37: package names whose probes fail with the module as resolution
+// parent. `createRequire` follows the same walk-up Node uses for the
+// module's own imports, so an empty result means a project-local (or
+// already provisioned) engine wins and provisioning must touch nothing.
+function missingEngineLinks(modulePath) {
+  const req = createRequire(modulePath);
+  const missing = [];
+  for (const [specifier, name] of ENGINE_LINKS) {
+    try {
+      req.resolve(specifier);
+    } catch {
+      missing.push(name);
+    }
+  }
+  return missing;
+}
+
+// PBCLI-36: a manifest at or above the module declaring @sublang/playbook
+// means a project chose a dependency and its install is broken or absent;
+// shadow-provisioning would mask the real fix.
+function declaringManifest(startDir) {
+  for (let dir = startDir; ; ) {
+    const manifestPath = join(dir, 'package.json');
+    if (existsSync(manifestPath)) {
+      try {
+        const manifest = JSON.parse(readFileSync(manifestPath, 'utf8'));
+        for (const field of DEPENDENCY_FIELDS) {
+          const block = manifest?.[field];
+          if (
+            block !== null &&
+            typeof block === 'object' &&
+            Object.prototype.hasOwnProperty.call(block, '@sublang/playbook')
+          ) {
+            return manifestPath;
+          }
+        }
+      } catch {
+        // An unreadable manifest cannot declare the dependency.
+      }
+    }
+    const parent = dirname(dir);
+    if (parent === dir) return undefined;
+    dir = parent;
+  }
+}
+
+function packageRootUpward(startDir, name) {
+  for (let dir = startDir; ; ) {
+    const manifestPath = join(dir, 'package.json');
+    if (existsSync(manifestPath)) {
+      try {
+        if (JSON.parse(readFileSync(manifestPath, 'utf8')).name === name) {
+          return dir;
+        }
+      } catch {
+        // Keep walking past an unreadable manifest.
+      }
+    }
+    const parent = dirname(dir);
+    if (parent === dir) return undefined;
+    dir = parent;
+  }
+}
+
+// PBCLI-37: the running host's own installed package roots, resolved from
+// the host's module scope — this file lives inside @sublang/playbook, and
+// xstate resolves from that root's own dependency tree.
+function defaultHostRoots() {
+  const here = dirname(fileURLToPath(import.meta.url));
+  const playbookRoot = packageRootUpward(here, '@sublang/playbook');
+  if (playbookRoot === undefined) {
+    throw new Error(
+      'cannot locate the running @sublang/playbook package root for provisioning',
+    );
+  }
+  const req = createRequire(join(playbookRoot, 'package.json'));
+  let xstateRoot;
+  try {
+    xstateRoot = packageRootUpward(dirname(req.resolve('xstate')), 'xstate');
+  } catch {
+    xstateRoot = undefined;
+  }
+  if (xstateRoot === undefined) {
+    throw new Error(
+      "cannot locate the running host's own xstate package for provisioning",
+    );
+  }
+  return { xstate: xstateRoot, '@sublang/playbook': playbookRoot };
+}
+
+// 'absent' | 'dangling' | 'live' (a symlink with an existing target) |
+// 'occupied' (a real file or directory, never removed).
+function linkState(linkPath) {
+  let stat;
+  try {
+    stat = lstatSync(linkPath);
+  } catch {
+    return 'absent';
+  }
+  if (!stat.isSymbolicLink()) return 'occupied';
+  return existsSync(linkPath) ? 'live' : 'dangling';
+}
+
+// PBCLI-36/37: probe, then provision the missing engine links beside a
+// filesystem registry module. Returns {} when the run may proceed (either
+// nothing was needed or links were created and logged) or { code: 1 }
+// after writing one `playbook run: <message>` diagnostic to stderr.
+export async function provisionEngine({
+  modulePath,
+  stderr,
+  enabled = true,
+  hostRoots,
+}) {
+  const missing = missingEngineLinks(modulePath);
+  if (missing.length === 0) return {};
+
+  const moduleDir = dirname(modulePath);
+  if (!enabled) {
+    // PBCLI-36: --no-provision still owes the dangling-link diagnostic —
+    // a stale link we (or a prior host) created must not surface as a raw
+    // module-not-found error.
+    for (const name of missing) {
+      const linkPath = join(moduleDir, 'node_modules', name);
+      if (linkState(linkPath) === 'dangling') {
+        stderr.write(
+          `playbook run: ${linkPath} is a stale engine link to missing ` +
+            `${readlinkSync(linkPath)}; rerun without --no-provision to relink\n`,
+        );
+        return { code: 1 };
+      }
+    }
+    return {};
+  }
+
+  const manifestPath = declaringManifest(moduleDir);
+  if (manifestPath !== undefined) {
+    stderr.write(
+      `playbook run: ${manifestPath} declares @sublang/playbook; ` +
+        'provisioning would shadow the project install — run the ' +
+        "project's dependency install (e.g. npm install) instead\n",
+    );
+    return { code: 1 };
+  }
+
+  let roots;
+  try {
+    roots = hostRoots ?? defaultHostRoots();
+  } catch (error) {
+    stderr.write(
+      `playbook run: ${error instanceof Error ? error.message : String(error)}\n`,
+    );
+    return { code: 1 };
+  }
+
+  // PBCLI-37: validate every destination before mutating any, so an
+  // occupied-path refusal leaves the module directory unchanged rather
+  // than half-provisioned.
+  const plans = [];
+  for (const name of missing) {
+    const linkPath = join(moduleDir, 'node_modules', name);
+    const state = linkState(linkPath);
+    if (state === 'occupied' || state === 'live') {
+      // A live-but-unresolvable link is as foreign as a real directory:
+      // neither is a link this host may replace.
+      stderr.write(
+        `playbook run: cannot provision ${linkPath}: the path is already ` +
+          `occupied${state === 'live' ? ' by a foreign symbolic link' : ''}\n`,
+      );
+      return { code: 1 };
+    }
+    plans.push({
+      linkPath,
+      target: roots[name],
+      dangling: state === 'dangling',
+    });
+  }
+
+  const created = [];
+  try {
+    for (const { linkPath, target, dangling } of plans) {
+      if (dangling) await unlink(linkPath);
+      await mkdir(dirname(linkPath), { recursive: true });
+      await symlink(target, linkPath, 'dir');
+      created.push(`${linkPath} -> ${target}`);
+    }
+  } catch (error) {
+    // PBCLI-37: a filesystem failure is a load fault, not a raw crash.
+    stderr.write(
+      'playbook run: cannot provision engine links: ' +
+        `${error instanceof Error ? error.message : String(error)}\n`,
+    );
+    return { code: 1 };
+  }
+  stderr.write(`playbook run: provisioned ${created.join(', ')}\n`);
+  return {};
+}