openclaw-castroom 0.1.0

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "openclaw-castroom",
+  "version": "0.1.0",
+  "description": "Give your OpenClaw agents personality from TV show characters.",
+  "type": "module",
+  "bin": {
+    "castroom": "dist/index.js"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "lint": "node -e \"process.env.ESLINT_USE_FLAT_CONFIG='false'; import('node:child_process').then(({ spawnSync }) => { const result = spawnSync(process.execPath, ['node_modules/eslint/bin/eslint.js', '.'], { stdio: 'inherit', env: process.env }); process.exit(result.status ?? 1); });\"",
+    "format": "prettier --check .",
+    "format:write": "prettier --write .",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "commander": "14.0.3",
+    "execa": "9.6.1",
+    "fs-extra": "11.3.3",
+    "pathe": "2.0.3"
+  },
+  "devDependencies": {
+    "@types/fs-extra": "11.0.4",
+    "@types/node": "25.2.0",
+    "@typescript-eslint/eslint-plugin": "8.54.0",
+    "@typescript-eslint/parser": "8.54.0",
+    "eslint": "9.39.2",
+    "prettier": "3.8.1",
+    "typescript": "5.9.3",
+    "vitest": "4.0.18"
+  },
+  "eslintConfig": {
+    "root": true,
+    "env": {
+      "node": true,
+      "es2022": true
+    },
+    "parser": "@typescript-eslint/parser",
+    "parserOptions": {
+      "sourceType": "module"
+    },
+    "plugins": ["@typescript-eslint"],
+    "extends": ["eslint:recommended", "plugin:@typescript-eslint/recommended"],
+    "ignorePatterns": ["dist", "node_modules"]
+  },
+  "prettier": {
+    "singleQuote": true,
+    "semi": true,
+    "printWidth": 100,
+    "trailingComma": "all"
+  }
+}

package/src/commands/add.ts

@@ -0,0 +1,145 @@
+import { populateWorkspace } from './populate.js';
+import {
+  findPersonaInAnyPack,
+  getPersona,
+  listPacks,
+  listPersonas,
+  type Persona,
+} from '../personas/index.js';
+import {
+  detectNonInteractiveFlags,
+  ensureOpenclawAvailable,
+  getOpenclawAddHelp,
+  runOpenclawCommand,
+} from '../openclaw/runner.js';
+import { resolveWorkspace } from '../openclaw/workspace.js';
+import { withSpinner } from '../ui/spinner.js';
+
+export type AddOptions = {
+  pack?: string;
+  persona?: string;
+  listPacks?: boolean;
+  listPersonas?: boolean;
+  packListPersonas?: boolean;
+  workspace?: string;
+  force?: boolean;
+  dryRun?: boolean;
+  interactive?: boolean;
+  nonInteractive?: boolean;
+  verbose?: boolean;
+};
+
+export const addCommand = async (
+  agentName: string | undefined,
+  options: AddOptions,
+): Promise<void> => {
+  if (options.listPacks) {
+    console.log(listPacks().join('\n'));
+    return;
+  }
+
+  const pack = options.pack ?? 'office';
+
+  if (options.listPersonas || options.packListPersonas) {
+    console.log(listPersonas(pack).join('\n'));
+    return;
+  }
+
+  if (!agentName) {
+    throw new Error('Agent name is required unless --list-packs or --list-personas is used.');
+  }
+
+  if (options.interactive && options.nonInteractive) {
+    throw new Error('Use either --interactive or --non-interactive, not both.');
+  }
+
+  const personaInput = options.persona ?? agentName;
+  let persona: Persona;
+  try {
+    persona = getPersona(pack, personaInput);
+  } catch {
+    const found = findPersonaInAnyPack(personaInput);
+    if (found) {
+      persona = found.persona;
+    } else {
+      throw new Error(
+        `Unknown persona "${personaInput}". Use --pack <series> to specify, or run --list-personas to see options.`,
+      );
+    }
+  }
+
+  await ensureOpenclawAvailable();
+
+  let nonInteractiveFlags: string[] = [];
+  if (options.nonInteractive) {
+    const helpText = await getOpenclawAddHelp();
+    nonInteractiveFlags = detectNonInteractiveFlags(helpText);
+    if (nonInteractiveFlags.length === 0) {
+      throw new Error(
+        'OpenClaw does not expose a non-interactive flag. Re-run with --interactive or create the agent manually and use populate with --workspace.',
+      );
+    }
+  }
+
+  const args = ['agents', 'add', agentName, ...nonInteractiveFlags];
+  if (options.verbose) {
+    console.log(`running: openclaw ${args.join(' ')}`);
+  }
+
+  const result = await runOpenclawCommand(args, {
+    streamOutput: Boolean(options.verbose || !options.nonInteractive),
+    stdin: 'inherit',
+  });
+
+  if (result.exitCode !== 0) {
+    throw new Error(
+      `OpenClaw failed with exit code ${result.exitCode}. Check the OpenClaw output and try again.`,
+    );
+  }
+
+  const resolution = await resolveWorkspace({
+    explicitPath: options.workspace,
+    output: result,
+    cwd: process.cwd(),
+  });
+
+  for (const warning of resolution.warnings) {
+    console.warn(`warning: ${warning}`);
+  }
+
+  if (options.verbose) {
+    console.log(`workspace: ${resolution.workspace} (source: ${resolution.source})`);
+  }
+
+  const pickRandom = (arr: string[]): string => arr[Math.floor(Math.random() * arr.length)] ?? '';
+
+  const injection = await withSpinner(
+    options.dryRun ? 'Previewing persona injection…' : 'Injecting persona…',
+    async () =>
+      populateWorkspace({
+        workspacePath: resolution.workspace,
+        persona,
+        force: options.force ?? true,
+        dryRun: options.dryRun,
+      }),
+    {
+      enabled: Boolean(process.stdout.isTTY) && !options.verbose,
+      successText: options.dryRun ? 'Preview ready' : 'Persona ready',
+      failureText: 'Persona injection failed',
+    },
+  );
+
+  const wrote = injection.written.length;
+  const skipped = injection.skipped.length;
+  if (options.dryRun) {
+    console.log(`Would write ${wrote} file(s) (${skipped} skipped).`);
+  } else {
+    console.log(`Injected persona files (${wrote} written, ${skipped} skipped).`);
+  }
+
+  const greetings = persona.startAgentGreetings?.length ? persona.startAgentGreetings : persona.bootstrapGreetings;
+  const line = pickRandom(greetings);
+  if (line) {
+    console.log(`\n${persona.name}: ${line}`);
+  }
+};

package/src/commands/populate.ts

@@ -0,0 +1,109 @@
+import fsExtra from 'fs-extra';
+const { ensureDir, pathExists, remove, rename, stat, writeFile } = fsExtra;
+import { basename, dirname, join } from 'pathe';
+import { renderPersonaFiles } from '../templates/common.js';
+import type { Persona } from '../personas/types.js';
+import { withSpinner } from '../ui/spinner.js';
+
+export type PopulateResult = {
+  written: string[];
+  skipped: string[];
+};
+
+const atomicWriteFile = async (filePath: string, content: string): Promise<void> => {
+  await ensureDir(dirname(filePath));
+  const tempPath = join(dirname(filePath), `.${basename(filePath)}.${Date.now()}.tmp`);
+  await writeFile(tempPath, content, { encoding: 'utf8' });
+  try {
+    await rename(tempPath, filePath);
+  } catch (error) {
+    if (process.platform === 'win32') {
+      await remove(filePath);
+      await rename(tempPath, filePath);
+      return;
+    }
+    throw error;
+  }
+};
+
+const assertWorkspaceDir = async (workspacePath: string): Promise<void> => {
+  if (!(await pathExists(workspacePath))) {
+    throw new Error(`Workspace not found: ${workspacePath}`);
+  }
+  const stats = await stat(workspacePath);
+  if (!stats.isDirectory()) {
+    throw new Error(`Workspace is not a directory: ${workspacePath}`);
+  }
+};
+
+export const populateWorkspace = async (options: {
+  workspacePath: string;
+  persona: Persona;
+  force?: boolean;
+  dryRun?: boolean;
+}): Promise<PopulateResult> => {
+  await assertWorkspaceDir(options.workspacePath);
+  const files = renderPersonaFiles(options.persona);
+  const written: string[] = [];
+  const skipped: string[] = [];
+
+  for (const [fileName, content] of Object.entries(files)) {
+    const filePath = join(options.workspacePath, fileName);
+    const exists = await pathExists(filePath);
+    if (exists && !options.force) {
+      skipped.push(filePath);
+      continue;
+    }
+
+    if (options.dryRun) {
+      written.push(filePath);
+      continue;
+    }
+
+    await atomicWriteFile(filePath, content);
+    written.push(filePath);
+  }
+
+  return { written, skipped };
+};
+
+export const populateCommand = async (options: {
+  workspace: string;
+  persona: Persona;
+  force?: boolean;
+  dryRun?: boolean;
+}): Promise<void> => {
+  const pickRandom = (arr: string[]): string => arr[Math.floor(Math.random() * arr.length)] ?? '';
+
+  const result = await withSpinner(
+    options.dryRun ? 'Previewing persona injection…' : 'Injecting persona…',
+    async () =>
+      populateWorkspace({
+        workspacePath: options.workspace,
+        persona: options.persona,
+        force: options.force,
+        dryRun: options.dryRun,
+      }),
+    {
+      enabled: Boolean(process.stdout.isTTY),
+      successText: options.dryRun ? 'Preview ready' : 'Persona ready',
+      failureText: 'Persona injection failed',
+    },
+  );
+
+  const wrote = result.written.length;
+  const skipped = result.skipped.length;
+  if (options.dryRun) {
+    console.log(`Would write ${wrote} file(s) (${skipped} skipped).`);
+  } else {
+    console.log(`Injected persona files (${wrote} written, ${skipped} skipped).`);
+  }
+
+  const greetings = options.persona.startAgentGreetings?.length
+    ? options.persona.startAgentGreetings
+    : options.persona.bootstrapGreetings;
+  const line = pickRandom(greetings);
+  if (line) {
+    console.log(`\n${options.persona.name}: ${line}`);
+  }
+};

package/src/index.ts

@@ -0,0 +1,112 @@
+#!/usr/bin/env node
+import { Command } from 'commander';
+import { addCommand } from './commands/add.js';
+import { populateCommand } from './commands/populate.js';
+import { getPersona, listPacks, listPersonas } from './personas/index.js';
+
+const program = new Command();
+
+program
+  .name('castroom')
+  .description('Give your OpenClaw agents personality from TV show characters.')
+  .version('0.1.0');
+
+program
+  .option('--pack <name>', 'Persona pack (default: "office")', 'office')
+  .option('--list-packs', 'List available persona packs and exit')
+  .option('--list-personas', 'List personas for the selected pack and exit')
+  .option('--pack-list-personas', 'Alias for --list-personas');
+
+program
+  .command('add')
+  .argument('[agentName]', 'Agent name to create with OpenClaw')
+  .usage('<agentName> [options]')
+  .option('--pack <name>', 'Persona pack (default: "office")', 'office')
+  .option('--persona <name>', 'Persona name (default: agentName)')
+  .option('--list-packs', 'List available persona packs and exit')
+  .option('--list-personas', 'List personas for the selected pack and exit')
+  .option('--pack-list-personas', 'Alias for --list-personas')
+  .option('--workspace <path>', 'Workspace path override')
+  .option('--force', 'Overwrite existing markdown files')
+  .option('--dry-run', 'Print actions without writing files')
+  .option('--interactive', 'Allow interactive OpenClaw prompts')
+  .option('--non-interactive', 'Attempt non-interactive OpenClaw flow')
+  .option('--verbose', 'Print extra diagnostics')
+  .action(async (agentName, options) => {
+    const parentOpts = program.opts();
+    await addCommand(agentName, {
+      ...parentOpts,
+      ...options,
+      pack: options.pack ?? parentOpts.pack ?? 'office',
+    });
+  });
+
+program
+  .command('populate')
+  .option('--workspace <path>', 'Workspace path to populate')
+  .option('--pack <name>', 'Persona pack (default: "office")', 'office')
+  .option('--persona <name>', 'Persona name to use')
+  .option('--list-packs', 'List available persona packs and exit')
+  .option('--list-personas', 'List personas for the selected pack and exit')
+  .option('--pack-list-personas', 'Alias for --list-personas')
+  .option('--force', 'Overwrite existing markdown files')
+  .option('--dry-run', 'Print actions without writing files')
+  .action(async (options) => {
+    const parentOpts = program.opts();
+    const merged = {
+      ...parentOpts,
+      ...options,
+      pack: options.pack ?? parentOpts.pack ?? 'office',
+    };
+
+    if (merged.listPacks) {
+      console.log(listPacks().join('\n'));
+      return;
+    }
+
+    if (merged.listPersonas || merged.packListPersonas) {
+      console.log(listPersonas(merged.pack ?? 'office').join('\n'));
+      return;
+    }
+
+    if (!merged.workspace) {
+      throw new Error('Workspace is required. Provide --workspace <path>.');
+    }
+
+    if (!merged.persona) {
+      throw new Error('Persona is required. Provide --persona <name>.');
+    }
+
+    const persona = getPersona(merged.pack ?? 'office', merged.persona);
+
+    await populateCommand({
+      workspace: merged.workspace,
+      persona,
+      force: merged.force,
+      dryRun: merged.dryRun,
+    });
+  });
+
+program.action(async (options) => {
+  if (options.listPacks) {
+    console.log(listPacks().join('\n'));
+    return;
+  }
+
+  if (options.listPersonas || options.packListPersonas) {
+    console.log(listPersonas(options.pack ?? 'office').join('\n'));
+    return;
+  }
+
+  program.help();
+});
+
+const main = async () => {
+  await program.parseAsync(process.argv);
+};
+
+main().catch((error) => {
+  const message = error instanceof Error ? error.message : String(error);
+  console.error(`error: ${message}`);
+  process.exitCode = 1;
+});

package/src/openclaw/runner.ts

@@ -0,0 +1,121 @@
+import { execa } from 'execa';
+
+export type OpenclawResult = {
+  stdout: string;
+  stderr: string;
+  exitCode: number;
+};
+
+type RunOptions = {
+  streamOutput?: boolean;
+  stdin?: 'inherit' | 'ignore';
+  cwd?: string;
+};
+
+const OPENCLAW_BIN = 'openclaw';
+
+const isMissingCommand = (error: unknown) =>
+  error instanceof Error && 'code' in error && (error as { code?: string }).code === 'ENOENT';
+
+export const ensureOpenclawAvailable = async (): Promise<void> => {
+  try {
+    const result = await execa(OPENCLAW_BIN, ['--version'], { reject: false });
+    if (result.exitCode !== 0) {
+      throw new Error('OpenClaw CLI returned a non-zero exit code.');
+    }
+  } catch (error) {
+    if (isMissingCommand(error)) {
+      throw new Error(
+        'OpenClaw CLI not found. Install OpenClaw and ensure the `openclaw` command is on your PATH.',
+      );
+    }
+    throw new Error(
+      'OpenClaw CLI is not available. Install OpenClaw and ensure the `openclaw` command works.',
+    );
+  }
+};
+
+export const runOpenclawCommand = async (
+  args: string[],
+  { streamOutput, stdin = 'inherit', cwd }: RunOptions = {},
+): Promise<OpenclawResult> => {
+  try {
+    const child = execa(OPENCLAW_BIN, args, {
+      stdin,
+      stdout: 'pipe',
+      stderr: 'pipe',
+      reject: false,
+      cwd,
+    });
+
+    let stdout = '';
+    let stderr = '';
+
+    child.stdout?.on('data', (chunk) => {
+      const text = chunk.toString();
+      stdout += text;
+      if (streamOutput) {
+        process.stdout.write(text);
+      }
+    });
+
+    child.stderr?.on('data', (chunk) => {
+      const text = chunk.toString();
+      stderr += text;
+      if (streamOutput) {
+        process.stderr.write(text);
+      }
+    });
+
+    const result = await child;
+    return {
+      stdout,
+      stderr,
+      exitCode: result.exitCode ?? 0,
+    };
+  } catch (error) {
+    if (isMissingCommand(error)) {
+      throw new Error(
+        'OpenClaw CLI not found. Install OpenClaw and ensure the `openclaw` command is on your PATH.',
+      );
+    }
+    throw error;
+  }
+};
+
+const escapeRegex = (value: string) => value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+
+export const detectNonInteractiveFlags = (helpText: string): string[] => {
+  const candidates = ['--yes', '-y', '--defaults', '--no-input', '--non-interactive'];
+  const normalized = helpText.replace(/\r/g, '');
+  const supported = candidates.filter((flag) => {
+    const pattern = new RegExp(
+      `(^|\\s|[\\[(,])${escapeRegex(flag)}(?=\\s|,|$|[\\])])`,
+      'm',
+    );
+    return pattern.test(normalized);
+  });
+
+  const result: string[] = [];
+  for (const flag of candidates) {
+    if (!supported.includes(flag)) {
+      continue;
+    }
+    if (flag === '-y' && supported.includes('--yes')) {
+      continue;
+    }
+    result.push(flag);
+  }
+
+  return result;
+};
+
+export const getOpenclawAddHelp = async (): Promise<string> => {
+  const result = await runOpenclawCommand(['agents', 'add', '--help'], { stdin: 'ignore' });
+  if (result.exitCode !== 0) {
+    throw new Error(
+      'Failed to run `openclaw agents add --help`. Try --interactive or create the agent manually.',
+    );
+  }
+  return [result.stdout, result.stderr].filter(Boolean).join('\n');
+};