@relay-baton/cli 1.0.0

package/dist/index.js

@@ -0,0 +1,394 @@
+#!/usr/bin/env node
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const commander_1 = require("commander");
+const init_1 = require("./commands/init");
+const doctor_1 = require("./commands/doctor");
+const verify_1 = require("./commands/verify");
+const status_1 = require("./commands/status");
+const review_1 = require("./commands/review");
+const receipt_1 = require("./commands/receipt");
+const checkpoint_1 = require("./commands/checkpoint");
+const guard_1 = require("./commands/guard");
+const risk_1 = require("./commands/risk");
+const workspace_1 = require("./commands/workspace");
+const profile_1 = require("./commands/profile");
+const inventory_1 = require("./commands/inventory");
+const run_1 = require("./commands/run");
+const handoff_1 = require("./commands/handoff");
+const handoffHistory_1 = require("./commands/handoffHistory");
+const handoffShow_1 = require("./commands/handoffShow");
+const handoffBundle_1 = require("./commands/handoffBundle");
+const report_1 = require("./commands/report");
+const migrate_1 = require("./commands/migrate");
+const plan_1 = require("./commands/plan");
+const execute_1 = require("./commands/execute");
+const compressContext_1 = require("./commands/compressContext");
+const compact_1 = require("./commands/compact");
+const budget_1 = require("./commands/budget");
+const usage_1 = require("./commands/usage");
+const compress_1 = require("./commands/compress");
+const tui_1 = require("./commands/tui");
+const chat_1 = require("./commands/chat");
+const replay_1 = require("./commands/replay");
+const conversation_1 = require("./commands/conversation");
+const git_1 = require("./commands/git");
+const session_1 = require("./commands/session");
+const sessionWorkspace_1 = require("./commands/sessionWorkspace");
+const login_1 = require("./commands/login");
+const project_1 = require("./commands/project");
+const program = new commander_1.Command();
+program
+    .name("relay-baton")
+    .description("Token-aware handoff harness for Codex CLI and Claude Code")
+    .version("1.0.0");
+function addProjectOptions(cmd) {
+    return cmd
+        .option("--project <name-or-id>", "registered project name or id")
+        .option("--path <repoPath>", "repository path");
+}
+addProjectOptions(program.command("init").description("Initialize .ai-session in the current repository")).action(init_1.initCommand);
+addProjectOptions(program.command("doctor").description("Check local environment").option("--deep", "run extended diagnostics")).action(doctor_1.doctorCommand);
+addProjectOptions(program.command("status").description("Show current session status").option("--json", "print machine-readable JSON")).action(status_1.statusCommand);
+addProjectOptions(program
+    .command("review")
+    .description("Deterministically review the working-tree diff against the current plan (no model call)")
+    .option("--json", "print machine-readable JSON")).action(review_1.reviewCommand);
+addProjectOptions(program
+    .command("verify")
+    .description("Simulated end-to-end check of the relay-baton pipeline (no real model calls)")
+    .option("--diet <profile>", "diet profile: off|lite|balanced|caveman|ultra")
+    .option("--real-agents", "EXPERIMENTAL scaffold only; never executes real agents")
+    .option("--keep-temp", "keep the throwaway temp repo used for the handoff check")
+    .option("--verbose", "print per-step detail")).action(verify_1.verifyCommand);
+program
+    .command("run")
+    .description("Run a relay chain: first agent runs the task; on fallback, hand off to the next agent")
+    .argument("<task>", "task description")
+    .option("--diet <profile>", "diet profile: off|lite|balanced|caveman|ultra")
+    .option("--force", "ignore quality gate failures")
+    .option("--allow-api-key-env", "allow passing API key env vars to child processes")
+    .option("--primary <agent>", "first agent in the relay chain (default: config primaryAgent)")
+    .option("--fallback <agent>", "second agent in the relay chain (default: config fallbackAgent)")
+    .option("--chain <a,b,c>", "explicit N-way relay chain (overrides --primary/--fallback)")
+    .option("--until <n>", "bounded auto-orchestration: up to N extra continue-steps (guardrail-gated, confirm each)")
+    .option("--yes", "pre-approve bounded --until steps (still capped + guardrail-gated)")
+    .option("--project <name-or-id>", "registered project name or id")
+    .option("--path <repoPath>", "repository path")
+    .action((task, opts) => (0, run_1.runCommand)(task, opts));
+const handoff = program
+    .command("handoff")
+    .description("Generate a handoff and optionally launch the next agent")
+    .option("--to <agent>", "next agent (claude)")
+    .option("--diet <profile>", "diet profile: off|lite|balanced|caveman|ultra")
+    .option("--force", "ignore quality gate failures")
+    .option("--no-run", "do not launch the next agent")
+    .option("--allow-api-key-env", "allow passing API key env vars to child processes")
+    .option("--project <name-or-id>", "registered project name or id")
+    .option("--path <repoPath>", "repository path")
+    .action((opts) => {
+    if (!opts.to) {
+        console.error("[relay-baton] missing required option: --to <agent>");
+        process.exit(2);
+    }
+    return (0, handoff_1.handoffCommand)(opts);
+});
+handoff
+    .command("history")
+    .description("List past handoff documents (current + timestamped backups)")
+    .option("--project <name-or-id>", "registered project name or id")
+    .option("--path <repoPath>", "repository path")
+    .action(handoffHistory_1.handoffHistoryCommand);
+handoff
+    .command("show")
+    .description("Print a handoff document read-only (current handoff.md by default)")
+    .option("--file <name>", "a history file name from `handoff history` instead of the current one")
+    .option("--json", "print machine-readable JSON")
+    .option("--project <name-or-id>", "registered project name or id")
+    .option("--path <repoPath>", "repository path")
+    .action(handoffShow_1.handoffShowCommand);
+handoff
+    .command("bundle")
+    .description("Build a portable handoff bundle (curated artifacts + git summary + redaction pass). Read-only on the repo")
+    .option("--json", "print machine-readable JSON")
+    .option("--dry-run", "show what would be bundled without writing")
+    .option("--out <dir>", "bundle root directory (default: ~/.relay-baton/handoff-bundles)")
+    .option("--project <name-or-id>", "registered project name or id")
+    .option("--path <repoPath>", "repository path")
+    .action(handoffBundle_1.handoffBundleCommand);
+handoff
+    .command("inspect")
+    .description("Validate a handoff bundle and print what it contains (read-only, applies nothing)")
+    .argument("<bundle>", "bundle id or path under the bundle root")
+    .option("--json", "print machine-readable JSON")
+    .option("--out <dir>", "bundle root directory (default: ~/.relay-baton/handoff-bundles)")
+    .action(handoffBundle_1.handoffInspectCommand);
+addProjectOptions(program
+    .command("report")
+    .description("Generate a human-readable markdown status report from existing artifacts (read-only, no model call)")
+    .option("--out <file>", "write the report to a file instead of stdout")
+    .option("--json", "wrap the markdown in JSON")).action(report_1.reportCommand);
+addProjectOptions(program
+    .command("migrate")
+    .description("Check .ai-session artifact schema versions; with --apply, normalize legacy artifacts (backs up first)")
+    .option("--check", "report only (default behavior, read-only)")
+    .option("--apply", "apply safe migrations (writes a .bak backup before each change)")
+    .option("--dry-run", "with --apply, show the plan without writing")
+    .option("--json", "print machine-readable JSON")).action(migrate_1.migrateCommand);
+program
+    .command("plan")
+    .description("Plan-execute mode: a planner agent writes .ai-session/plan.md")
+    .argument("<task>", "task description")
+    .option("--diet <profile>", "diet profile: off|lite|balanced|caveman|ultra")
+    .option("--with <agent>", "planner agent (default: config planExecute.defaultPlanner)")
+    .option("--planner <agent>", "planner agent (alias of --with)")
+    .option("--executor <agent>", "executor agent for --then-execute")
+    .option("--no-run", "scaffold an empty plan template instead of launching the planner")
+    .option("--then-execute", "run the execute phase immediately after a passing plan")
+    .option("--force", "ignore plan quality gate failures")
+    .option("--allow-api-key-env", "allow passing API key env vars to child processes")
+    .option("--project <name-or-id>", "registered project name or id")
+    .option("--path <repoPath>", "repository path")
+    .action((task, opts) => (0, plan_1.planCommand)(task, opts));
+program
+    .command("execute")
+    .description("Plan-execute mode: an executor agent implements .ai-session/plan.md")
+    .option("--diet <profile>", "diet profile: off|lite|balanced|caveman|ultra")
+    .option("--with <agent>", "executor agent (default: config planExecute.defaultExecutor)")
+    .option("--from <path>", "read the plan from a custom path")
+    .option("--force", "ignore quality gate failures")
+    .option("--allow-api-key-env", "allow passing API key env vars to child processes")
+    .option("--project <name-or-id>", "registered project name or id")
+    .option("--path <repoPath>", "repository path")
+    .action(execute_1.executeCommand);
+program
+    .command("compact")
+    .description("Recompute compact-state, repo-map, diff snapshot")
+    .option("--diet <profile>", "diet profile: off|lite|balanced|caveman|ultra")
+    .option("--project <name-or-id>", "registered project name or id")
+    .option("--path <repoPath>", "repository path")
+    .action(compact_1.compactCommand);
+program
+    .command("squeeze")
+    .description("Alias of compact")
+    .option("--diet <profile>", "diet profile: off|lite|balanced|caveman|ultra")
+    .option("--project <name-or-id>", "registered project name or id")
+    .option("--path <repoPath>", "repository path")
+    .action(compact_1.compactCommand);
+addProjectOptions(program.command("budget").description("Show context budget usage").option("--json", "print machine-readable JSON")).action(budget_1.budgetCommand);
+addProjectOptions(program.command("usage").description("Show local per-session usage (token proxy; never transmitted)").option("--json", "print machine-readable JSON")).action(usage_1.usageCommand);
+const receipt = program.command("receipt").description("Append-only execution receipts for plan steps");
+addProjectOptions(receipt.command("done").description("Mark a plan step done").argument("<step>", "1-based step index").option("--note <text>", "short note")).action((step, opts) => (0, receipt_1.receiptDoneCommand)(step, opts));
+addProjectOptions(receipt.command("skip").description("Mark a plan step skipped").argument("<step>", "1-based step index").option("--note <text>", "short note")).action((step, opts) => (0, receipt_1.receiptSkipCommand)(step, opts));
+addProjectOptions(receipt.command("list").description("List recorded receipts").option("--json", "print machine-readable JSON")).action(receipt_1.receiptListCommand);
+const checkpoint = program
+    .command("checkpoint")
+    .description("Append-only execution checkpoints (command, changed files, git, budget, result) per step");
+addProjectOptions(checkpoint
+    .command("add")
+    .description("Record an execution checkpoint for a step")
+    .argument("<step>", "1-based step index")
+    .option("--command <text>", "command preview this step ran")
+    .option("--result <result>", "step result: ok|fail|pending (default: pending)")
+    .option("--note <text>", "short note")
+    .option("--json", "print machine-readable JSON")).action((step, opts) => (0, checkpoint_1.checkpointCommand)(step, opts));
+addProjectOptions(checkpoint.command("list").description("List recorded execution checkpoints").option("--json", "print machine-readable JSON")).action(checkpoint_1.checkpointListCommand);
+addProjectOptions(checkpoint.command("summary").description("Compact execution receipt derived from checkpoints").option("--json", "print machine-readable JSON")).action(checkpoint_1.checkpointSummaryCommand);
+addProjectOptions(program
+    .command("guard")
+    .description("Evaluate stop-condition guardrails against checkpoints + live git/budget (advisory, read-only)")
+    .option("--json", "print machine-readable JSON")
+    .option("--exit-code", "exit non-zero (10) when a stop condition is triggered")).action(guard_1.guardCommand);
+addProjectOptions(program
+    .command("risk")
+    .description("Flag risky surfaces in the working tree (deps, deletions, release/CI, env/config, binaries). Read-only")
+    .option("--json", "print machine-readable JSON")).action(risk_1.riskCommand);
+addProjectOptions(program
+    .command("workspace")
+    .description("Deterministic workspace map: package managers, languages, monorepo packages, scripts, entry points, docs. Read-only")
+    .option("--json", "print machine-readable JSON")).action(workspace_1.workspaceCommand);
+addProjectOptions(program
+    .command("profile")
+    .description("Deterministic project profile hints: framework tags, recommended build/test, diet/agents, entry points. Read-only")
+    .option("--json", "print machine-readable JSON")).action(profile_1.profileCommand);
+addProjectOptions(program
+    .command("inventory")
+    .description("Bounded inventory: package scripts, workspace packages, CI workflows, release files. Read-only")
+    .option("--json", "print machine-readable JSON")).action(inventory_1.inventoryCommand);
+program
+    .command("compress-context")
+    .description("Compress running session context (state.md / commands.log) when over budget")
+    .option("--diet <profile>", "diet profile: off|lite|balanced|caveman|ultra")
+    .option("--threshold <ratio>", "compress when weight/budget exceeds this ratio (0..1)")
+    .option("--dry-run", "report what would change without writing")
+    .option("--force", "compress regardless of threshold")
+    .option("--project <name-or-id>", "registered project name or id")
+    .option("--path <repoPath>", "repository path")
+    .action(compressContext_1.compressContextCommand);
+program
+    .command("compress")
+    .description("Deterministically compress a markdown/instruction file")
+    .argument("<file>")
+    .option("--write", "rewrite file in place")
+    .option("--out <path>", "write to a different path")
+    .action(compress_1.compressCommand);
+program
+    .command("login")
+    .description("Run an agent CLI login flow interactively (codex/claude/opencode/gemini/aider/cursor)")
+    .argument("[agent]", "codex | claude | opencode | gemini | aider | cursor | all (default: all = first-class pair)")
+    .option("--allow-api-key-env", "allow passing API key env vars to login process")
+    .action((agent, opts) => (0, login_1.loginCommand)(agent, opts));
+const project = program.command("project").description("Manage registered projects");
+project.command("add").argument("<path>", "repository path").option("--name <name>").option("--diet <profile>").option("--primary <agent>").option("--fallback <agent>").option("--json", "print machine-readable JSON").action(project_1.projectAddCommand);
+project.command("list").description("List registered projects").option("--json", "print machine-readable JSON").action(project_1.projectListCommand);
+project.command("switch").argument("<name-or-id>").description("Switch active project").action(project_1.projectSwitchCommand);
+project.command("current").description("Show active project").option("--json", "print machine-readable JSON").action(project_1.projectCurrentCommand);
+project.command("remove").argument("<name-or-id>").description("Remove a project").option("--json", "print machine-readable JSON").action(project_1.projectRemoveCommand);
+project.command("doctor").description("Check registered projects").action(project_1.projectDoctorCommand);
+const git = program.command("git").description("Read-only git tracking helpers");
+git
+    .command("status")
+    .description("Show branch, ahead/behind, and working-tree change counts")
+    .option("--json", "print machine-readable JSON")
+    .option("--limit <n>", "max changed files to include")
+    .option("--project <name-or-id>", "registered project name or id")
+    .option("--path <repoPath>", "repository path")
+    .action(git_1.gitStatusCommand);
+const session = program.command("session").description("Manage work items (named sessions) + archives/recovery");
+// v2.6 multi-session workspace — named work items within one repo.
+session
+    .command("new")
+    .description("Create a named work item (session); the legacy flat session is `default`")
+    .argument("<name>", "work-item name (letters/digits/._-)")
+    .option("--switch", "switch the active session to the new one")
+    .option("--agent <id>", "pin this work item to an agent (codex|claude|opencode|gemini|aider|cursor)")
+    .option("--no-init", "do not initialize .ai-session artifacts for the new item")
+    .option("--json", "print machine-readable JSON")
+    .option("--project <name-or-id>", "registered project name or id")
+    .option("--path <repoPath>", "repository path")
+    .action(sessionWorkspace_1.sessionNewCommand);
+session
+    .command("switch")
+    .aliases(["use"])
+    .description("Switch the active work item (use `default` for the legacy flat session)")
+    .argument("<name>", "work-item name")
+    .option("--json", "print machine-readable JSON")
+    .option("--project <name-or-id>", "registered project name or id")
+    .option("--path <repoPath>", "repository path")
+    .action(sessionWorkspace_1.sessionSwitchCommand);
+session
+    .command("items")
+    .description("List work items in this repo and which one is active (read-only)")
+    .option("--json", "print machine-readable JSON")
+    .option("--project <name-or-id>", "registered project name or id")
+    .option("--path <repoPath>", "repository path")
+    .action(sessionWorkspace_1.sessionItemsCommand);
+session
+    .command("assign")
+    .description("Pin a work item to an agent (or `none` to clear)")
+    .argument("<name>", "work-item name")
+    .argument("<agent>", "agent id or `none`")
+    .option("--project <name-or-id>", "registered project name or id")
+    .option("--path <repoPath>", "repository path")
+    .action(sessionWorkspace_1.sessionAssignCommand);
+session
+    .command("remove")
+    .description("Remove a named work item (never `default`)")
+    .argument("<name>", "work-item name")
+    .option("--delete-files", "also delete the work item's .ai-session/sessions/<name> dir")
+    .option("--project <name-or-id>", "registered project name or id")
+    .option("--path <repoPath>", "repository path")
+    .action(sessionWorkspace_1.sessionRemoveCommand);
+const sessionWorktree = session
+    .command("worktree")
+    .description("Back a work item with an isolated git worktree for safe parallel execution");
+sessionWorktree
+    .command("add")
+    .description("Create a git worktree for a work item; run/handoff then execute there")
+    .argument("<name>", "work-item name")
+    .option("--branch <b>", "branch to create (default: relay/<name>)")
+    .option("--worktree-path <dir>", "worktree location (default: <parent>/<repo>.worktrees/<name>)")
+    .option("--project <name-or-id>", "registered project name or id")
+    .option("--path <repoPath>", "repository path")
+    .action(sessionWorkspace_1.sessionWorktreeAddCommand);
+sessionWorktree
+    .command("remove")
+    .description("Remove a work item's git worktree (commit/stash first, or --force)")
+    .argument("<name>", "work-item name")
+    .option("--force", "remove even if the worktree has changes")
+    .option("--project <name-or-id>", "registered project name or id")
+    .option("--path <repoPath>", "repository path")
+    .action(sessionWorkspace_1.sessionWorktreeRemoveCommand);
+session
+    .command("archive")
+    .description("Archive the current .ai-session artifacts without modifying the source repo")
+    .option("--json", "print machine-readable JSON")
+    .option("--dry-run", "show what would be archived without writing")
+    .option("--out <dir>", "archive root directory (default: ~/.relay-baton/session-archives)")
+    .option("--project <name-or-id>", "registered project name or id")
+    .option("--path <repoPath>", "repository path")
+    .action(session_1.sessionArchiveCommand);
+session
+    .command("list")
+    .description("List archived sessions (read-only)")
+    .option("--json", "print machine-readable JSON")
+    .option("--out <dir>", "archive root directory (default: ~/.relay-baton/session-archives)")
+    .action(session_1.sessionListCommand);
+session
+    .command("inspect")
+    .description("Validate an archived session's manifest and file integrity (read-only)")
+    .argument("<archive>", "archive id or path under the archive root")
+    .option("--json", "print machine-readable JSON")
+    .option("--out <dir>", "archive root directory (default: ~/.relay-baton/session-archives)")
+    .action(session_1.sessionInspectCommand);
+session
+    .command("resume")
+    .description("Diagnose the current .ai-session and suggest the safest next command (read-only)")
+    .option("--json", "print machine-readable JSON")
+    .option("--stale-hours <n>", "treat the session as stale when older than N hours (default: 24)")
+    .option("--project <name-or-id>", "registered project name or id")
+    .option("--path <repoPath>", "repository path")
+    .action(session_1.sessionResumeCommand);
+session
+    .command("export")
+    .description("Copy an archived session out to a destination directory for sharing/backup (read-only on the archive)")
+    .argument("<archive>", "archive id or path under the archive root")
+    .requiredOption("--to <dir>", "destination directory")
+    .option("--overwrite", "overwrite an existing destination")
+    .option("--json", "print machine-readable JSON")
+    .option("--out <dir>", "archive root directory (default: ~/.relay-baton/session-archives)")
+    .action(session_1.sessionExportCommand);
+session
+    .command("prune")
+    .description("Apply an archive retention policy (disabled by default; dry-run unless --apply)")
+    .option("--max-age-days <n>", "prune archives older than N days")
+    .option("--max-count <n>", "keep only the newest N archives")
+    .option("--apply", "actually delete (default is a dry-run preview)")
+    .option("--json", "print machine-readable JSON")
+    .option("--out <dir>", "archive root directory (default: ~/.relay-baton/session-archives)")
+    .action(session_1.sessionPruneCommand);
+addProjectOptions(program.command("tui").description("Start the relay-baton TUI")).action(tui_1.tuiCommand);
+addProjectOptions(program
+    .command("chat")
+    .aliases(["room"])
+    .description("Agent Room (v0.8 first cut): turn-based, confirmation-first multi-agent REPL")
+    .option("--allow-api-key-env", "allow passing API key env vars to confirmed agent runs")).action(chat_1.chatCommand);
+addProjectOptions(program
+    .command("replay")
+    .description("Replay the recorded conversation timeline (read-only, no model call)")
+    .option("--json", "print machine-readable JSON")
+    .option("--session <id>", "filter to a single session id")
+    .option("--kind <kinds>", "comma-separated event kinds to include")
+    .option("--limit <n>", "keep only the most recent N events")).action(replay_1.replayCommand);
+const conversation = program.command("conversation").description("Append/read Agent Room conversation events");
+addProjectOptions(conversation
+    .command("append")
+    .description("Append a single conversation event to the current session")
+    .argument("<text>", "event text")
+    .option("--json", "print machine-readable JSON")
+    .option("--role <role>", "event role: user|relay-baton|codex|claude")
+    .option("--kind <kind>", "event kind, e.g. message|command|status|budget|prompt_preview")).action((text, opts) => (0, conversation_1.conversationAppendCommand)(text, opts));
+program.parseAsync(process.argv).catch(err => {
+    console.error(err?.stack ?? err);
+    process.exit(1);
+});

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@relay-baton/cli",
+  "version": "1.0.0",
+  "description": "Token-aware handoff harness that lets Codex CLI and Claude Code take turns on the same repo",
+  "license": "MIT",
+  "author": "DongGeon Lee",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dgl1231/relay-baton.git",
+    "directory": "packages/cli"
+  },
+  "homepage": "https://github.com/dgl1231/relay-baton#readme",
+  "bugs": {
+    "url": "https://github.com/dgl1231/relay-baton/issues"
+  },
+  "keywords": [
+    "codex",
+    "claude",
+    "handoff",
+    "cli",
+    "token-diet",
+    "ai-agents"
+  ],
+  "main": "dist/index.js",
+  "bin": {
+    "relay-baton": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "commander": "^12.1.0",
+    "@relay-baton/tui": "1.0.0",
+    "@relay-baton/core": "1.0.0",
+    "@relay-baton/shared": "1.0.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.5.4",
+    "vitest": "^2.0.5",
+    "@types/node": "^20.14.10"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run",
+    "start": "node dist/index.js",
+    "dev": "tsc -p tsconfig.json --watch"
+  }
+}