opencastle 0.6.0 → 0.8.0

package/src/cli/prompt.ts

@@ -14,6 +14,19 @@ function moveUp(n: number): string {
   return n > 0 ? `${CSI}${n}A` : '';
 }
 
+// ── Color helpers ─────────────────────────────────────────────────
+
+/** ANSI color helpers for CLI output. */
+export const c = {
+  cyan: (s: string) => `\x1B[36m${s}\x1B[0m`,
+  green: (s: string) => `\x1B[32m${s}\x1B[0m`,
+  yellow: (s: string) => `\x1B[33m${s}\x1B[0m`,
+  red: (s: string) => `\x1B[31m${s}\x1B[0m`,
+  bold: (s: string) => `\x1B[1m${s}\x1B[0m`,
+  dim: (s: string) => `\x1B[2m${s}\x1B[0m`,
+  magenta: (s: string) => `\x1B[35m${s}\x1B[0m`,
+};
+
 // ── Line-buffered readline ────────────────────────────────────────
 // readline.question() drops lines that arrived between calls because
 // it only listens for the NEXT 'line' event.  When piped input
@@ -236,3 +249,166 @@ export async function confirm(
   if (!answer.trim()) return defaultYes;
   return answer.trim().toLowerCase().startsWith('y');
 }
+
+// ── Multiselect ───────────────────────────────────────────────────
+
+/**
+ * Interactive multi-choice selection prompt.
+ *
+ * TTY mode:  arrow-key navigation (↑/↓), Space to toggle, Enter to confirm.
+ * Piped mode: falls back to comma-separated number input.
+ *
+ * Returns an array of selected values (possibly empty).
+ */
+export async function multiselect(
+  message: string,
+  options: SelectOption[]
+): Promise<string[]> {
+  if (stdin.isTTY) {
+    return multiselectInteractive(message, options);
+  }
+  return multiselectNumbered(message, options);
+}
+
+// ── Arrow-key multiselect (TTY) ───────────────────────────────────
+
+function renderMultiselectOptions(
+  options: SelectOption[],
+  cursor: number,
+  selected: Set<number>,
+  initial: boolean
+): void {
+  if (!initial) {
+    stdout.write(moveUp(options.length));
+  }
+
+  for (let i = 0; i < options.length; i++) {
+    const active = i === cursor;
+    const checked = selected.has(i);
+    const checkbox = checked ? `\x1B[32m✔\x1B[0m` : ' ';
+    const marker = active ? '❯' : ' ';
+    const hint = options[i].hint ? ` ${c.dim('—')} ${c.dim(options[i].hint!)}` : '';
+    const label = active
+      ? `\x1B[36m${options[i].label}\x1B[0m${hint}`
+      : `${options[i].label}${hint}`;
+    stdout.write(`${ERASE_LINE}\r    ${marker} [${checkbox}] ${label}\n`);
+  }
+}
+
+function multiselectInteractive(
+  message: string,
+  options: SelectOption[]
+): Promise<string[]> {
+  return new Promise<string[]>((resolve) => {
+    let cursor = 0;
+    const selected = new Set<number>();
+    // Pre-select options marked as selected
+    for (let i = 0; i < options.length; i++) {
+      if (options[i].selected) selected.add(i);
+    }
+
+    if (_rl) _rl.pause();
+
+    stdout.write(`\n  ${message} ${c.dim('(↑/↓ navigate, Space toggle, Enter confirm)')}\n\n`);
+    stdout.write(HIDE_CURSOR);
+    renderMultiselectOptions(options, cursor, selected, true);
+
+    stdin.setRawMode(true);
+    stdin.resume();
+
+    const onData = (data: Buffer): void => {
+      const key = data.toString();
+
+      // Arrow up or k
+      if (key === `${ESC}[A` || key === 'k') {
+        cursor = (cursor - 1 + options.length) % options.length;
+        renderMultiselectOptions(options, cursor, selected, false);
+        return;
+      }
+
+      // Arrow down or j
+      if (key === `${ESC}[B` || key === 'j') {
+        cursor = (cursor + 1) % options.length;
+        renderMultiselectOptions(options, cursor, selected, false);
+        return;
+      }
+
+      // Space — toggle selection
+      if (key === ' ') {
+        if (selected.has(cursor)) {
+          selected.delete(cursor);
+        } else {
+          selected.add(cursor);
+        }
+        renderMultiselectOptions(options, cursor, selected, false);
+        return;
+      }
+
+      // Enter — confirm
+      if (key === '\r' || key === '\n') {
+        cleanup();
+        // Final render
+        stdout.write(moveUp(options.length));
+        for (let i = 0; i < options.length; i++) {
+          const checked = selected.has(i);
+          const hint = options[i].hint ? ` ${c.dim('—')} ${c.dim(options[i].hint!)}` : '';
+          const checkbox = checked ? `\x1B[32m✔\x1B[0m` : ' ';
+          const label = checked
+            ? `\x1B[36m${options[i].label}\x1B[0m${hint}`
+            : `\x1B[2m${options[i].label}${hint}\x1B[0m`;
+          stdout.write(`${ERASE_LINE}\r      [${checkbox}] ${label}\n`);
+        }
+        stdout.write('\n');
+        resolve(Array.from(selected).sort().map(i => options[i].value));
+        return;
+      }
+
+      // Ctrl+C
+      if (key === '\x03') {
+        cleanup();
+        stdout.write('\n');
+        process.exit(130);
+      }
+    };
+
+    function cleanup(): void {
+      stdin.removeListener('data', onData);
+      stdin.setRawMode(false);
+      stdout.write(SHOW_CURSOR);
+      if (_rl) _rl.resume();
+    }
+
+    stdin.on('data', onData);
+  });
+}
+
+// ── Number-based multiselect (piped / non-TTY) ────────────────────
+
+async function multiselectNumbered(
+  message: string,
+  options: SelectOption[]
+): Promise<string[]> {
+  console.log(`\n  ${message}\n`);
+  options.forEach((opt, i) => {
+    const hint = opt.hint ? ` — ${opt.hint}` : '';
+    console.log(`    ${i + 1}) ${opt.label}${hint}`);
+  });
+
+  const preselected = options
+    .map((opt, i) => (opt.selected ? i + 1 : null))
+    .filter((n): n is number => n !== null);
+  const defaultHint = preselected.length > 0 ? preselected.join(',') : 'none';
+  const answer = await nextLine(`\n  Select [comma-separated, e.g. 1,3] or Enter for ${defaultHint}: `);
+  if (!answer.trim()) {
+    return preselected.map(n => options[n - 1].value);
+  }
+
+  const nums = answer.split(',').map(s => parseInt(s.trim(), 10));
+  const result: string[] = [];
+  for (const num of nums) {
+    if (num >= 1 && num <= options.length) {
+      result.push(options[num - 1].value);
+    }
+  }
+  return result;
+}

package/src/cli/stack-config.ts

@@ -1,111 +1,39 @@
-import type { CmsChoice, DbChoice, PmChoice, NotifChoice, StackConfig, CopyDirOptions, RepoInfo } from './types.js';
-
-// ── Skill / Technology labels ─────────────────────────────────
-
-/** Display name for each CMS choice */
-const CMS_LABELS: Record<Exclude<CmsChoice, 'none'>, { tech: string; skill: string }> = {
-  sanity: { tech: 'Sanity', skill: 'sanity-cms' },
-  contentful: { tech: 'Contentful', skill: 'contentful-cms' },
-  strapi: { tech: 'Strapi', skill: 'strapi-cms' },
-};
-
-/** Display name for each DB choice */
-const DB_LABELS: Record<Exclude<DbChoice, 'none'>, { tech: string; skill: string }> = {
-  supabase: { tech: 'Supabase', skill: 'supabase-database' },
-  convex: { tech: 'Convex', skill: 'convex-database' },
-};
-
-/** Display name for each PM choice */
-const PM_LABELS: Record<Exclude<PmChoice, 'none'>, { tech: string; skill: string }> = {
-  linear: { tech: 'Linear', skill: 'task-management' },
-  jira: { tech: 'Jira', skill: 'jira-management' },
-};
-
-/** Display name for each notifications choice */
-const NOTIF_LABELS: Record<Exclude<NotifChoice, 'none'>, { tech: string; skill: string }> = {
-  slack: { tech: 'Slack', skill: 'slack-notifications' },
-  teams: { tech: 'Teams', skill: 'teams-notifications' },
-};
-
-// ── Exclusion / inclusion maps ────────────────────────────────
-
-/** Skills to EXCLUDE based on CMS choice */
-const CMS_SKILL_MAP: Record<CmsChoice, string[]> = {
-  sanity: ['contentful-cms', 'strapi-cms'],
-  contentful: ['sanity-cms', 'strapi-cms'],
-  strapi: ['sanity-cms', 'contentful-cms'],
-  none: ['sanity-cms', 'contentful-cms', 'strapi-cms'],
-};
-
-/** Skills to EXCLUDE based on DB choice */
-const DB_SKILL_MAP: Record<DbChoice, string[]> = {
-  supabase: ['convex-database'],
-  convex: ['supabase-database'],
-  none: ['supabase-database', 'convex-database'],
-};
-
-/** Skills to EXCLUDE based on PM choice */
-const PM_SKILL_MAP: Record<PmChoice, string[]> = {
-  linear: ['jira-management'],
-  jira: ['task-management'],
-  none: ['task-management', 'jira-management'],
-};
-
-/** Agents to EXCLUDE based on CMS choice */
-const CMS_AGENT_EXCLUSIONS: Record<CmsChoice, string[]> = {
-  sanity: [],
-  contentful: [],
-  strapi: [],
-  none: ['content-engineer.agent.md'],
-};
-
-/** Agents to EXCLUDE based on DB choice */
-const DB_AGENT_EXCLUSIONS: Record<DbChoice, string[]> = {
-  supabase: [],
-  convex: [],
-  none: ['database-engineer.agent.md'],
-};
-
-/** MCP server keys to INCLUDE based on CMS choice */
-const CMS_MCP_MAP: Record<CmsChoice, string[]> = {
-  sanity: ['Sanity'],
-  contentful: ['Contentful'],
-  strapi: ['Strapi'],
-  none: [],
-};
-
-/** MCP server keys to INCLUDE based on DB choice */
-const DB_MCP_MAP: Record<DbChoice, string[]> = {
-  supabase: ['Supabase'],
-  convex: ['Convex'],
-  none: [],
-};
-
-/** MCP server keys to INCLUDE based on PM choice */
-const PM_MCP_MAP: Record<PmChoice, string[]> = {
-  linear: ['Linear'],
-  jira: ['Jira'],
-  none: [],
-};
+import type { TechTool, TeamTool, StackConfig, CopyDirOptions, RepoInfo } from './types.js';
+import {
+  PLUGINS,
+  TECH_PLUGINS,
+  TEAM_PLUGINS,
+  CMS_PLUGINS,
+  DB_PLUGINS,
+  ALL_PLUGIN_SKILL_NAMES,
+  getSelectedSkillNames,
+} from '../orchestrator/plugins/index.js';
+import type { PluginConfig } from '../orchestrator/plugins/types.js';
+
+// ── Tool registries (derived from plugins) ────────────────────
+
+interface ToolInfo {
+  tech: string;
+  skill: string | null;
+  mcpServer: string | null;
+}
 
-/** Skills to EXCLUDE based on notifications choice */
-const NOTIF_SKILL_MAP: Record<NotifChoice, string[]> = {
-  slack: ['teams-notifications'],
-  teams: ['slack-notifications'],
-  none: ['slack-notifications', 'teams-notifications'],
-};
+/** All tech-tool metadata — derived from plugin configs. */
+const TECH_TOOL_INFO: Record<TechTool, ToolInfo> = Object.fromEntries(
+  TECH_PLUGINS.map((p) => [p.id, { tech: p.name, skill: p.skillName, mcpServer: p.mcpServerKey }])
+) as Record<TechTool, ToolInfo>;
 
-/** MCP server keys to INCLUDE based on notifications choice */
-const NOTIF_MCP_MAP: Record<NotifChoice, string[]> = {
-  slack: ['Slack'],
-  teams: ['Teams'],
-  none: [],
-};
+/** All team-tool metadata — derived from plugin configs. */
+const TEAM_TOOL_INFO: Record<TeamTool, ToolInfo> = Object.fromEntries(
+  TEAM_PLUGINS.map((p) => [p.id, { tech: p.name, skill: p.skillName, mcpServer: p.mcpServerKey }])
+) as Record<TeamTool, ToolInfo>;
 
-/** Always-included MCP servers */
-const CORE_MCP_SERVERS = ['chrome-devtools'];
+/** CMS-related tech tools. */
+const CMS_TOOLS: readonly TechTool[] = CMS_PLUGINS.map((p) => p.id) as TechTool[];
+/** Database-related tech tools. */
+const DB_TOOLS: readonly TechTool[] = DB_PLUGINS.map((p) => p.id) as TechTool[];
 
-/** MCP servers included only when detected in the repo */
+/** MCP servers auto-included when detected in the repo. */
 const DETECTED_MCP_MAP: Record<string, string> = {
   vercel: 'Vercel',
 };
@@ -123,41 +51,64 @@ export interface McpEnvRequirement {
 
 /**
  * Registry of MCP servers that require API keys via environment variables.
- * Only servers with `env` fields in mcp.json need to be listed here.
- * HTTP-based servers (Sanity, Slack, Vercel, etc.) handle auth via OAuth.
+ * Derived from plugin configs — only plugins with envVars are included.
  */
-const MCP_ENV_REQUIREMENTS: McpEnvRequirement[] = [
-  {
-    server: 'Linear',
-    envVar: 'LINEAR_API_KEY',
-    hint: 'Create at linear.app → Settings → API → Personal API keys',
-  },
-];
+const MCP_ENV_REQUIREMENTS: McpEnvRequirement[] = Object.values(PLUGINS)
+  .filter((p) => p.envVars.length > 0 && p.mcpServerKey)
+  .flatMap((p) =>
+    p.envVars.map((ev) => ({
+      server: p.mcpServerKey!,
+      envVar: ev.name,
+      hint: ev.hint,
+    }))
+  );
+
+// ── Exported helpers ──────────────────────────────────────────
 
+/**
+ * Skills to EXCLUDE — all tool-specific skills that are NOT selected.
+ */
 export function getExcludedSkills(stack: StackConfig): Set<string> {
-  return new Set([
-    ...CMS_SKILL_MAP[stack.cms],
-    ...DB_SKILL_MAP[stack.db],
-    ...PM_SKILL_MAP[stack.pm ?? 'none'],
-    ...NOTIF_SKILL_MAP[stack.notifications ?? 'none'],
-  ]);
+  const selectedIds = [...stack.techTools, ...stack.teamTools] as string[];
+  const includedSkills = new Set(getSelectedSkillNames(selectedIds));
+  return new Set(ALL_PLUGIN_SKILL_NAMES.filter((s) => !includedSkills.has(s)));
 }
 
+/**
+ * Plugin IDs to INCLUDE — the user's selected tools.
+ */
+export function getIncludedPluginIds(stack: StackConfig): Set<string> {
+  return new Set([...stack.techTools, ...stack.teamTools]);
+}
+
+/**
+ * Agents to EXCLUDE — content-engineer if no CMS, database-engineer if no DB.
+ */
 export function getExcludedAgents(stack: StackConfig): Set<string> {
-  return new Set([
-    ...CMS_AGENT_EXCLUSIONS[stack.cms],
-    ...DB_AGENT_EXCLUSIONS[stack.db],
-  ]);
+  const excluded = new Set<string>();
+  const hasCms = stack.techTools.some((t) => (CMS_TOOLS as readonly string[]).includes(t));
+  const hasDb = stack.techTools.some((t) => (DB_TOOLS as readonly string[]).includes(t));
+
+  if (!hasCms) excluded.add('content-engineer.agent.md');
+  if (!hasDb) excluded.add('database-engineer.agent.md');
+
+  return excluded;
 }
 
+/**
+ * MCP servers to INCLUDE — core + selected tools + auto-detected from repo.
+ */
 export function getIncludedMcpServers(stack: StackConfig, repoInfo?: RepoInfo): Set<string> {
-  const servers = new Set([
-    ...CORE_MCP_SERVERS,
-    ...CMS_MCP_MAP[stack.cms],
-    ...DB_MCP_MAP[stack.db],
-    ...PM_MCP_MAP[stack.pm ?? 'none'],
-    ...NOTIF_MCP_MAP[stack.notifications ?? 'none'],
-  ]);
+  const servers = new Set<string>();
+
+  for (const tool of stack.techTools) {
+    const server = TECH_TOOL_INFO[tool]?.mcpServer;
+    if (server) servers.add(server);
+  }
+  for (const tool of stack.teamTools) {
+    const server = TEAM_TOOL_INFO[tool]?.mcpServer;
+    if (server) servers.add(server);
+  }
 
   // Add servers for detected deployment targets
   for (const dep of repoInfo?.deployment ?? []) {
@@ -165,6 +116,11 @@ export function getIncludedMcpServers(stack: StackConfig, repoInfo?: RepoInfo):
     if (server) servers.add(server);
   }
 
+  // Auto-detect NX from monorepo info
+  if (repoInfo?.monorepo === 'nx' && !stack.techTools.includes('nx')) {
+    servers.add('Nx');
+  }
+
   return servers;
 }
 
@@ -189,7 +145,6 @@ export function getCustomizationsTransform(
   stack: StackConfig
 ): NonNullable<CopyDirOptions['transform']> {
   return (content: string, srcPath: string) => {
-    // Pre-fill skill matrix with CMS and DB bindings
     if (srcPath.endsWith('skill-matrix.md')) {
       return transformSkillMatrix(content, stack);
     }
@@ -204,23 +159,97 @@ export function getCustomizationsTransform(
 function transformSkillMatrix(content: string, stack: StackConfig): string {
   let result = content;
 
-  // Fill the database row
-  if (stack.db !== 'none') {
-    const { tech, skill } = DB_LABELS[stack.db];
-    result = result.replace(
-      /(\| `database`\s*\|)\s*\|(\s*\|)/,
-      `$1 ${tech} | \`${skill}\` $2`
-    );
+  // Find first selected DB tool
+  const db = stack.techTools.find((t) => (DB_TOOLS as readonly string[]).includes(t));
+  if (db) {
+    const info = TECH_TOOL_INFO[db as TechTool];
+    if (info?.skill) {
+      result = result.replace(
+        /(\| `database`\s*\|)\s*\|(\s*\|)/,
+        `$1 ${info.tech} | \`${info.skill}\` $2`
+      );
+    }
   }
 
-  // Fill the CMS row
-  if (stack.cms !== 'none') {
-    const { tech, skill } = CMS_LABELS[stack.cms];
-    result = result.replace(
-      /(\| `cms`\s*\|)\s*\|(\s*\|)/,
-      `$1 ${tech} | \`${skill}\` $2`
-    );
+  // Find first selected CMS tool
+  const cms = stack.techTools.find((t) => (CMS_TOOLS as readonly string[]).includes(t));
+  if (cms) {
+    const info = TECH_TOOL_INFO[cms as TechTool];
+    if (info?.skill) {
+      result = result.replace(
+        /(\| `cms`\s*\|)\s*\|(\s*\|)/,
+        `$1 ${info.tech} | \`${info.skill}\` $2`
+      );
+    }
   }
 
   return result;
 }
+
+// ── Agent tool injection ──────────────────────────────────────
+
+/**
+ * Compute tool injections per agent based on the user's selected stack.
+ * Returns a Map where key = agent name (e.g. 'content-engineer'), value = tools to inject.
+ */
+export function getAgentToolInjections(stack: StackConfig): Map<string, string[]> {
+  const injections = new Map<string, string[]>();
+  const selectedIds = [...stack.techTools, ...stack.teamTools] as string[];
+
+  for (const id of selectedIds) {
+    const plugin = PLUGINS[id];
+    if (!plugin?.agentToolMap) continue;
+
+    for (const [agentName, tools] of Object.entries(plugin.agentToolMap)) {
+      const existing = injections.get(agentName) ?? [];
+      existing.push(...tools);
+      injections.set(agentName, existing);
+    }
+  }
+
+  return injections;
+}
+
+/**
+ * Returns a transform callback that injects plugin-specific tools
+ * into agent file frontmatter based on the user's stack selection.
+ */
+export function getAgentTransform(
+  stack: StackConfig
+): NonNullable<CopyDirOptions['transform']> {
+  const injections = getAgentToolInjections(stack);
+
+  return (content: string, srcPath: string) => {
+    // Extract agent name from filename (e.g., 'content-engineer' from 'content-engineer.agent.md')
+    const match = srcPath.match(/([^/\\]+)\.agent\.md$/);
+    if (!match) return content;
+
+    const agentName = match[1];
+    const toolsToInject = injections.get(agentName);
+    if (!toolsToInject || toolsToInject.length === 0) return content;
+
+    // Parse the frontmatter to find the tools array
+    const fmMatch = content.match(/^(---\n)([\s\S]*?)\n(---\n)([\s\S]*)$/);
+    if (!fmMatch) return content;
+
+    const frontmatter = fmMatch[2];
+    const body = fmMatch[4];
+
+    // Find and modify the tools line
+    const toolsMatch = frontmatter.match(/^(tools:\s*\[)(.*?)(\]\s*)$/m);
+    if (!toolsMatch) return content;
+
+    const existingTools = toolsMatch[2];
+    const injectedToolsList = toolsToInject.map((t) => `'${t}'`).join(', ');
+    const newTools = existingTools
+      ? `${existingTools}, ${injectedToolsList}`
+      : injectedToolsList;
+
+    const newFrontmatter = frontmatter.replace(
+      toolsMatch[0],
+      `${toolsMatch[1]}${newTools}${toolsMatch[3]}`
+    );
+
+    return `---\n${newFrontmatter}\n---\n${body}`;
+  };
+}

package/src/cli/types.ts

@@ -2,16 +2,36 @@ import type { ChildProcess } from 'node:child_process';
 
 // ── Stack selection types ──────────────────────────────────────
 
-export type CmsChoice = 'sanity' | 'contentful' | 'strapi' | 'none';
-export type DbChoice = 'supabase' | 'convex' | 'none';
-export type PmChoice = 'linear' | 'jira' | 'none';
-export type NotifChoice = 'slack' | 'teams' | 'none';
+export type IdeChoice = 'vscode' | 'cursor' | 'claude-code' | 'opencode';
+export type TechTool = 'sanity' | 'contentful' | 'strapi' | 'supabase' | 'convex' | 'vercel' | 'nx' | 'chrome-devtools';
+export type TeamTool = 'linear' | 'jira' | 'slack' | 'teams';
 
 export interface StackConfig {
-  cms: CmsChoice;
-  db: DbChoice;
-  pm: PmChoice;
-  notifications: NotifChoice;
+  ides: IdeChoice[];
+  techTools: TechTool[];
+  teamTools: TeamTool[];
+}
+
+/** Check if a stack config uses the legacy v1 format (individual choices with 'none'). */
+export function isLegacyStack(stack: unknown): stack is { cms: string; db: string; pm?: string; notifications?: string } {
+  return typeof stack === 'object' && stack !== null && 'cms' in stack;
+}
+
+/** Migrate a legacy v1 stack config to the v2 array format. */
+export function migrateStackConfig(
+  legacy: { cms: string; db: string; pm?: string; notifications?: string },
+  ide?: string
+): StackConfig {
+  const techTools: TechTool[] = [];
+  const teamTools: TeamTool[] = [];
+
+  if (legacy.cms && legacy.cms !== 'none') techTools.push(legacy.cms as TechTool);
+  if (legacy.db && legacy.db !== 'none') techTools.push(legacy.db as TechTool);
+  if (legacy.pm && legacy.pm !== 'none') teamTools.push(legacy.pm as TeamTool);
+  if (legacy.notifications && legacy.notifications !== 'none') teamTools.push(legacy.notifications as TeamTool);
+
+  const ides: IdeChoice[] = ide ? [ide as IdeChoice] : [];
+  return { ides, techTools, teamTools };
 }
 
 /** Context passed from bin/cli.mjs to every command handler. */
@@ -60,6 +80,7 @@ export interface RepoInfo {
 export interface Manifest {
   version: string;
   ide: string;
+  ides?: string[];
   installedAt: string;
   updatedAt: string;
   managedPaths?: ManagedPaths;
@@ -85,6 +106,8 @@ export interface SelectOption {
   label: string;
   hint?: string;
   value: string;
+  /** Whether this option starts selected (preselected). */
+  selected?: boolean;
 }
 
 /** Scaffold result from MCP config. */
@@ -93,6 +116,14 @@ export interface ScaffoldResult {
   action: 'created' | 'skipped';
 }
 
+/** IDE display labels. */
+export const IDE_LABELS: Record<IdeChoice, string> = {
+  vscode: 'VS Code',
+  cursor: 'Cursor',
+  'claude-code': 'Claude Code',
+  opencode: 'OpenCode',
+};
+
 // ── Run command types ──────────────────────────────────────────
 
 /** Validated task spec from YAML. */