@0xtiby/toby 1.1.0 → 1.2.0

package/dist/cli.js

@@ -2,7 +2,7 @@
 
 // src/cli.tsx
 import meow from "meow";
-import { render, Text as Text14 } from "ink";
+import { render } from "ink";
 
 // src/commands/plan.tsx
 import { useState as useState3, useEffect as useEffect2, useMemo as useMemo2 } from "react";
@@ -112,6 +112,220 @@ function ensureLocalDir(cwd) {
   return dir;
 }
 
+// src/lib/help.ts
+var SPEC_FLAGS = [
+  { name: "--spec=<query>", description: "Target spec(s) by name, slug, number, or list" },
+  { name: "--specs=<names>", description: "Alias for --spec" },
+  { name: "--all", description: "Process all matching specs" },
+  { name: "--iterations=<n>", description: "Override iteration count" },
+  { name: "--verbose", description: "Show full CLI output" },
+  { name: "--transcript", description: "Save session transcript to file" },
+  { name: "--cli=<name>", description: "Override AI CLI (claude, codex, opencode)" },
+  { name: "--session=<name>", description: "Name the session for branch/PR naming" }
+];
+var commandHelp = {
+  plan: {
+    summary: "Plan specs with AI loop engine",
+    usage: ["$ toby plan [options]"],
+    flags: SPEC_FLAGS,
+    examples: [
+      {
+        command: "toby plan --spec=auth --cli=claude --session=auth-feature",
+        description: 'Plan the auth spec using Claude, naming the session "auth-feature"'
+      },
+      {
+        command: "toby plan --spec=auth,payments --iterations=3 --verbose",
+        description: "Plan auth and payments specs with 3 iterations, showing full output"
+      },
+      {
+        command: "toby plan --all --transcript",
+        description: "Plan all pending specs and save a transcript of the session"
+      }
+    ]
+  },
+  build: {
+    summary: "Build tasks one-per-spawn with AI",
+    usage: ["$ toby build [options]"],
+    flags: SPEC_FLAGS,
+    examples: [
+      {
+        command: "toby build --spec=auth --cli=claude --session=auth-feature",
+        description: 'Build the auth spec using Claude, resuming "auth-feature"'
+      },
+      {
+        command: "toby build --all --iterations=5 --transcript",
+        description: "Build all planned specs with up to 5 iterations, saving transcripts"
+      },
+      {
+        command: "toby build --spec=2 --verbose",
+        description: "Build spec #2 with full CLI output visible"
+      }
+    ]
+  },
+  init: {
+    summary: "Initialize toby in current project",
+    usage: ["$ toby init [options]"],
+    flags: [
+      {
+        name: "--plan-cli=<name>",
+        description: "Set plan CLI (claude, codex, opencode)"
+      },
+      { name: "--plan-model=<id>", description: "Set plan model" },
+      {
+        name: "--build-cli=<name>",
+        description: "Set build CLI (claude, codex, opencode)"
+      },
+      { name: "--build-model=<id>", description: "Set build model" },
+      { name: "--specs-dir=<path>", description: "Set specs directory" },
+      {
+        name: "--verbose",
+        description: "Enable verbose output in config"
+      }
+    ],
+    examples: [
+      {
+        command: "toby init",
+        description: "Launch the interactive setup wizard"
+      },
+      {
+        command: "toby init --plan-cli=claude --build-cli=claude --specs-dir=specs",
+        description: "Non-interactive init with required flags (for CI/agents)"
+      },
+      {
+        command: "toby init --plan-cli=codex --build-cli=codex --specs-dir=specs --verbose",
+        description: "Initialize with Codex for both phases, verbose enabled"
+      }
+    ]
+  },
+  status: {
+    summary: "Show project status",
+    usage: ["$ toby status [options]"],
+    flags: [
+      {
+        name: "--spec=<query>",
+        description: "Show status for a specific spec by name, slug, or number"
+      }
+    ],
+    examples: [
+      {
+        command: "toby status",
+        description: "Show status overview for all specs in the project"
+      },
+      {
+        command: "toby status --spec=auth",
+        description: "Show detailed status for the auth spec"
+      }
+    ]
+  },
+  config: {
+    summary: "Manage configuration",
+    usage: [
+      "$ toby config                           Interactive config editor",
+      "$ toby config get <key>                 Show a config value (dot-notation)",
+      "$ toby config set <key> <value>         Set a config value",
+      "$ toby config set <k>=<v> [<k>=<v>...]  Batch set values"
+    ],
+    flags: [],
+    examples: [
+      {
+        command: "toby config",
+        description: "Open the interactive config editor"
+      },
+      {
+        command: "toby config get plan.cli",
+        description: "Show the configured plan CLI"
+      },
+      {
+        command: "toby config set plan.cli=claude build.iterations=5",
+        description: "Batch set plan CLI to claude and build iterations to 5"
+      }
+    ]
+  },
+  clean: {
+    summary: "Delete session transcripts",
+    usage: ["$ toby clean [options]"],
+    flags: [
+      {
+        name: "--force",
+        description: "Skip confirmation prompt (required in non-TTY)"
+      }
+    ],
+    examples: [
+      {
+        command: "toby clean",
+        description: "Delete all transcripts with confirmation prompt"
+      },
+      {
+        command: "toby clean --force",
+        description: "Delete all transcripts without confirmation (for CI/agents)"
+      }
+    ]
+  }
+};
+function formatCommandHelp(command2, help) {
+  const lines = [];
+  lines.push(`toby ${command2} \u2014 ${help.summary}`);
+  lines.push("");
+  lines.push("Usage");
+  for (const usage of help.usage) {
+    lines.push(`  ${usage}`);
+  }
+  if (help.flags.length > 0) {
+    lines.push("");
+    lines.push("Options");
+    const maxName = Math.max(...help.flags.map((f) => f.name.length));
+    for (const flag of help.flags) {
+      lines.push(`  ${flag.name.padEnd(maxName)}   ${flag.description}`);
+    }
+  }
+  lines.push("");
+  lines.push("Examples");
+  const exampleBlocks = help.examples.map(
+    (ex) => `  $ ${ex.command}
+    ${ex.description}`
+  );
+  lines.push(exampleBlocks.join("\n\n"));
+  lines.push("");
+  return lines.join("\n");
+}
+function formatErrorWithHint(message, validValues, example) {
+  const lines = [];
+  if (validValues) {
+    lines.push(`\u2717 ${message}. Valid options: ${validValues.join(", ")}`);
+  } else {
+    lines.push(`\u2717 ${message}`);
+  }
+  if (example) {
+    lines.push("");
+    lines.push("Example:");
+    lines.push(`  $ ${example}`);
+  }
+  lines.push("");
+  return lines.join("\n");
+}
+function formatGlobalHelp(version2) {
+  const maxCmd = Math.max(
+    ...Object.keys(commandHelp).map((c) => c.length)
+  );
+  const cmdLines = Object.entries(commandHelp).map(([name, h]) => `  ${name.padEnd(maxCmd)}   ${h.summary}`).join("\n");
+  return [
+    `toby v${version2} \u2014 AI-assisted development loop engine`,
+    "",
+    "Usage",
+    "  $ toby <command> [options]",
+    "",
+    "Commands",
+    cmdLines,
+    "",
+    "Options",
+    "  --help       Show help (use with a command for details)",
+    "  --version    Show version",
+    "",
+    "Run toby <command> --help for command-specific options and examples.",
+    ""
+  ].join("\n");
+}
+
 // src/lib/config.ts
 function readConfigFile(filePath) {
   try {
@@ -154,7 +368,13 @@ function writeConfig(config, filePath) {
 }
 function validateCliName(cli2) {
   if (cli2 && !CLI_NAMES.includes(cli2)) {
-    throw new Error(`Unknown CLI: ${cli2}. Must be one of: ${CLI_NAMES.join(", ")}`);
+    throw new Error(
+      formatErrorWithHint(
+        `Unknown CLI: ${cli2}`,
+        [...CLI_NAMES],
+        "toby plan --cli=claude --spec=auth"
+      )
+    );
   }
 }
 function resolveCommandConfig(config, command2, flags2 = {}) {
@@ -3152,107 +3372,43 @@ function Welcome({ version: version2 }) {
   ] });
 }
 
+// src/lib/cli-meta.ts
+var COMMAND_NAMES = Object.keys(commandHelp);
+var MEOW_FLAGS = {
+  help: { type: "boolean", default: false },
+  spec: { type: "string" },
+  specs: { type: "string" },
+  all: { type: "boolean", default: false },
+  iterations: { type: "number" },
+  verbose: { type: "boolean", default: false },
+  transcript: { type: "boolean" },
+  cli: { type: "string" },
+  planCli: { type: "string" },
+  planModel: { type: "string" },
+  buildCli: { type: "string" },
+  buildModel: { type: "string" },
+  specsDir: { type: "string" },
+  session: { type: "string" },
+  force: { type: "boolean", default: false }
+};
+var MEOW_FLAG_NAMES = Object.keys(MEOW_FLAGS);
+
 // src/cli.tsx
 import { jsx as jsx14 } from "react/jsx-runtime";
-function Help({ version: version2 }) {
-  return /* @__PURE__ */ jsx14(Text14, { children: `toby v${version2} \u2014 AI-assisted development loop engine
-
-Usage
-  $ toby <command> [options]
-
-Commands
-  plan     Plan specs with AI loop engine
-  build    Build tasks one-per-spawn with AI
-  init     Initialize toby in current project
-  status   Show project status
-  config   Manage configuration
-  clean    Delete all transcript files
-
-Options
-  --help       Show this help
-  --version    Show version
-
-Spec Selection
-  --spec=<name>       Single spec or comma-separated (e.g. --spec=auth,payments)
-  --specs=<names>     Alias for --spec` });
-}
-function UnknownCommand({ command: command2 }) {
-  return /* @__PURE__ */ jsx14(Text14, { color: "red", children: `Unknown command: ${command2}
-Run "toby --help" for available commands.` });
-}
-var cli = meow(
-  `
-Usage
-  $ toby <command> [options]
-
-Commands
-  plan     Plan specs with AI loop engine
-  build    Build tasks one-per-spawn with AI
-  init     Initialize toby in current project
-  status   Show project status
-  config   Manage configuration
-  clean    Delete all transcript files
-
-Plan Options
-  --spec=<query>     Target spec(s) by name, slug, number, or comma-separated list
-  --specs=<names>    Alias for --spec with comma-separated specs
-  --all              Plan all pending specs
-  --iterations=<n>   Override iteration count
-  --verbose          Show full CLI output
-  --transcript       Save session transcript to file
-  --cli=<name>       Override AI CLI (claude, codex, opencode)
-  --session=<name>   Name the session for branch/PR naming
-
-Build Options
-  --spec=<query>     Target spec(s) by name, slug, number, or comma-separated list
-  --specs=<names>    Alias for --spec with comma-separated specs
-  --all              Build all planned specs in order
-  --iterations=<n>   Override max iteration count
-  --verbose          Show full CLI output
-  --transcript       Save session transcript to file
-  --cli=<name>       Override AI CLI (claude, codex, opencode)
-  --session=<name>   Name the session for branch/PR naming
-
-Status Options
-  --spec=<query>     Show status for a spec by name, slug, or number
-
-Init Options
-  --plan-cli=<name>    Set plan CLI (claude, codex, opencode)
-  --plan-model=<id>    Set plan model
-  --build-cli=<name>   Set build CLI (claude, codex, opencode)
-  --build-model=<id>   Set build model
-  --specs-dir=<path>   Set specs directory
-  --verbose            Enable verbose output in config
-
-Config Subcommands
-  config             Interactive config editor
-  config get <key>   Show a config value (dot-notation)
-  config set <key> <value>  Set a config value
-  config set <k>=<v> [<k>=<v>...]  Batch set config values
-
-Clean Options
-  --force    Skip confirmation prompt
-`,
-  {
-    importMeta: import.meta,
-    flags: {
-      spec: { type: "string" },
-      specs: { type: "string" },
-      all: { type: "boolean", default: false },
-      iterations: { type: "number" },
-      verbose: { type: "boolean", default: false },
-      transcript: { type: "boolean" },
-      cli: { type: "string" },
-      planCli: { type: "string" },
-      planModel: { type: "string" },
-      buildCli: { type: "string" },
-      buildModel: { type: "string" },
-      specsDir: { type: "string" },
-      session: { type: "string" },
-      force: { type: "boolean", default: false }
-    }
-  }
-);
+function writeUnknownCommandError(command2) {
+  process.stderr.write(
+    formatErrorWithHint(
+      `Unknown command: ${command2}`,
+      COMMAND_NAMES,
+      "toby --help"
+    )
+  );
+}
+var cli = meow("", {
+  importMeta: import.meta,
+  autoHelp: false,
+  flags: MEOW_FLAGS
+});
 ensureGlobalDir();
 var resolvedSpec = cli.flags.specs ?? cli.flags.spec;
 var flags = { ...cli.flags, spec: resolvedSpec };
@@ -3332,12 +3488,24 @@ var commands = {
 };
 var version = cli.pkg.version ?? "0.0.0";
 var [command] = cli.input;
-if (!command) {
+if (cli.flags.help) {
+  if (!command || command in commands) {
+    if (command && command in commandHelp) {
+      process.stdout.write(formatCommandHelp(command, commandHelp[command]));
+    } else {
+      process.stdout.write(formatGlobalHelp(version));
+    }
+    process.exitCode = 0;
+  } else {
+    writeUnknownCommandError(command);
+    process.exitCode = 1;
+  }
+} else if (!command) {
   if (process.stdin.isTTY) {
     const app = render(/* @__PURE__ */ jsx14(Welcome, { version }));
     await app.waitUntilExit();
   } else {
-    render(/* @__PURE__ */ jsx14(Help, { version })).unmount();
+    process.stdout.write(formatGlobalHelp(version));
   }
 } else if (command in commands) {
   const entry = commands[command];
@@ -3348,6 +3516,6 @@ if (!command) {
     app.unmount();
   }
 } else {
-  render(/* @__PURE__ */ jsx14(UnknownCommand, { command })).unmount();
+  writeUnknownCommandError(command);
   process.exitCode = 1;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@0xtiby/toby",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "AI-assisted development loop engine CLI",
   "repository": {
     "type": "git",