@taranek/orche 0.0.23 → 0.0.24

package/dist/cli.js

@@ -4,6 +4,7 @@ import { execFileSync, spawn } from "node:child_process";
 import path from "node:path";
 import { createWorktree } from "./worktree.js";
 import { pruneCommand } from "./prune.js";
+import { initCommand } from "./init.js";
 import { getMultiplexer } from "./multiplexer.js";
 import { buildLayout } from "./layout.js";
 import { getReviewBinaryPath } from "./review-manager.js";
@@ -146,14 +147,17 @@ function printUsage() {
 orche — orchestrate agents across git worktrees
 
 Usage:
+  orche init [-f]                    Bootstrap a repo: write .orche.json + .gitignore entry
   orche start <task> [-p <preset>]   Start a new session for <task>
   orche review [path]                Open the review UI for a worktree
   orche prune [--all] [-f]           Remove orche worktrees (interactive multiselect)
 
 Options:
   -p, --preset=<name>    Load .orche.<name>.json instead of .orche.json
+  -f, --force            (init/prune) overwrite/skip safety checks
 
 Examples:
+  orche init                        Create .orche.json + add .orche/ to .gitignore
   orche start fix-auth              Create worktree + session for "fix-auth"
   orche start fix-auth -p mobile    Use .orche.mobile.json preset
   orche start fix-auth -p debug     Use .orche.debug.json preset
@@ -163,10 +167,9 @@ Examples:
   orche prune --all                 Remove all orche worktrees
   orche prune --force               Allow removing worktrees with uncommitted changes
 
-Requires a ${CONFIG_NAME} file in the current directory.
+Requires a ${CONFIG_NAME} file in the current directory (run \`orche init\`).
 Use .orche.local.json for local overrides (not committed).
 Use .orche.<preset>.json for named presets (e.g. .orche.mobile.json).
-See .orche.example.json for the config format.
 `);
 }
 async function main() {
@@ -178,6 +181,9 @@ async function main() {
     if (subcommand === "start") {
         startSession();
     }
+    else if (subcommand === "init") {
+        initCommand(process.argv.slice(3));
+    }
     else if (subcommand === "prune") {
         const repoRoot = getRepoRoot(process.cwd());
         await pruneCommand(repoRoot, process.argv.slice(3));

package/dist/init.d.ts

@@ -0,0 +1 @@
+export declare function initCommand(argv: string[]): void;

package/dist/init.js

@@ -0,0 +1,108 @@
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { execSync } from "node:child_process";
+import path from "node:path";
+import pc from "picocolors";
+const CONFIG_NAME = ".orche.json";
+const GITIGNORE_NAME = ".gitignore";
+const GITIGNORE_ENTRY = ".orche/";
+const DEFAULT_CONFIG = {
+    multiplexer: "auto",
+    layout: {
+        direction: "horizontal",
+        panes: [
+            { name: "agent", command: "echo 'replace me with your agent command (e.g. claude, codex, aider)'" },
+            { name: "dev", command: "echo 'replace me with your dev server command (e.g. pnpm dev)'" },
+        ],
+    },
+};
+function parseOptions(argv) {
+    return {
+        force: argv.includes("--force") || argv.includes("-f"),
+    };
+}
+function isAvailable(bin) {
+    try {
+        execSync(`command -v ${bin}`, { stdio: "ignore" });
+        return true;
+    }
+    catch (err) {
+        // command -v exits nonzero when the binary is missing — expected, not an error.
+        console.log(`[init] ${bin} not found:`, err.message);
+        return false;
+    }
+}
+function ensureGitRepo(cwd) {
+    try {
+        execSync("git rev-parse --show-toplevel", { cwd, stdio: "ignore" });
+    }
+    catch (err) {
+        console.error(pc.red("error:"), "not inside a git repository");
+        console.error("run `git init` first, then `orche init`");
+        console.log(`[init] git rev-parse failed:`, err.message);
+        process.exit(1);
+    }
+}
+function ensureMultiplexer() {
+    const tmux = isAvailable("tmux");
+    const cmux = isAvailable("cmux");
+    if (tmux && cmux)
+        return "both";
+    if (cmux)
+        return "cmux";
+    if (tmux)
+        return "tmux";
+    console.error(pc.red("error:"), "neither tmux nor cmux is installed");
+    console.error("orche needs a terminal multiplexer to drive multiple panes. install one:");
+    console.error(`  ${pc.cyan("tmux")}: brew install tmux   (or your package manager)`);
+    console.error(`  ${pc.cyan("cmux")}: https://cmux.com`);
+    process.exit(1);
+}
+/** Write .orche.json. Refuses to overwrite unless force=true. */
+function writeConfig(cwd, force) {
+    const configPath = path.join(cwd, CONFIG_NAME);
+    if (existsSync(configPath) && !force) {
+        console.log(pc.dim(`skipped ${CONFIG_NAME} (already exists — pass --force to overwrite)`));
+        return false;
+    }
+    writeFileSync(configPath, JSON.stringify(DEFAULT_CONFIG, null, 2) + "\n");
+    console.log(`${pc.green("✓")} wrote ${pc.bold(CONFIG_NAME)}`);
+    return true;
+}
+/** Append .orche/ to .gitignore if not present. Creates the file if missing. */
+function ensureGitignore(cwd) {
+    const gitignorePath = path.join(cwd, GITIGNORE_NAME);
+    let contents = "";
+    if (existsSync(gitignorePath)) {
+        contents = readFileSync(gitignorePath, "utf-8");
+        const lines = contents.split(/\r?\n/).map((l) => l.trim());
+        // Match either ".orche/" or ".orche" (no trailing slash) — both ignore the dir.
+        if (lines.includes(GITIGNORE_ENTRY) || lines.includes(".orche")) {
+            console.log(pc.dim(`skipped ${GITIGNORE_NAME} (already ignores .orche)`));
+            return;
+        }
+    }
+    const prefix = contents.length === 0 || contents.endsWith("\n") ? "" : "\n";
+    writeFileSync(gitignorePath, contents + prefix + GITIGNORE_ENTRY + "\n");
+    console.log(`${pc.green("✓")} added ${pc.bold(GITIGNORE_ENTRY)} to ${pc.bold(GITIGNORE_NAME)}`);
+}
+function printNextSteps(mux) {
+    const muxNote = mux === "both" ? pc.dim("(tmux + cmux both detected — using cmux first via 'auto')") :
+        mux === "cmux" ? pc.dim("(cmux detected)") :
+            pc.dim("(tmux detected)");
+    console.log("");
+    console.log(pc.bold("Next:"));
+    console.log(`  1. Edit ${pc.cyan(CONFIG_NAME)} — set the panes you want (agent, dev server, etc.)`);
+    console.log(`  2. Run ${pc.cyan("orche start <task-name>")} to spin up a worktree + session`);
+    console.log(`  3. ${pc.cyan("orche review")} inside a worktree to open the diff UI`);
+    console.log("");
+    console.log(`  ${muxNote}`);
+}
+export function initCommand(argv) {
+    const opts = parseOptions(argv);
+    const cwd = process.cwd();
+    ensureGitRepo(cwd);
+    const mux = ensureMultiplexer();
+    writeConfig(cwd, opts.force);
+    ensureGitignore(cwd);
+    printNextSteps(mux);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@taranek/orche",
-  "version": "0.0.23",
+  "version": "0.0.24",
   "type": "module",
   "bin": {
     "orche": "./dist/cli.js"

package/src/cli.ts

@@ -5,6 +5,7 @@ import { execFileSync, spawn } from "node:child_process";
 import path from "node:path";
 import { createWorktree } from "./worktree.js";
 import { pruneCommand } from "./prune.js";
+import { initCommand } from "./init.js";
 import { getMultiplexer } from "./multiplexer.js";
 import { buildLayout } from "./layout.js";
 import { getReviewBinaryPath } from "./review-manager.js";
@@ -161,14 +162,17 @@ function printUsage(): void {
 orche — orchestrate agents across git worktrees
 
 Usage:
+  orche init [-f]                    Bootstrap a repo: write .orche.json + .gitignore entry
   orche start <task> [-p <preset>]   Start a new session for <task>
   orche review [path]                Open the review UI for a worktree
   orche prune [--all] [-f]           Remove orche worktrees (interactive multiselect)
 
 Options:
   -p, --preset=<name>    Load .orche.<name>.json instead of .orche.json
+  -f, --force            (init/prune) overwrite/skip safety checks
 
 Examples:
+  orche init                        Create .orche.json + add .orche/ to .gitignore
   orche start fix-auth              Create worktree + session for "fix-auth"
   orche start fix-auth -p mobile    Use .orche.mobile.json preset
   orche start fix-auth -p debug     Use .orche.debug.json preset
@@ -178,10 +182,9 @@ Examples:
   orche prune --all                 Remove all orche worktrees
   orche prune --force               Allow removing worktrees with uncommitted changes
 
-Requires a ${CONFIG_NAME} file in the current directory.
+Requires a ${CONFIG_NAME} file in the current directory (run \`orche init\`).
 Use .orche.local.json for local overrides (not committed).
 Use .orche.<preset>.json for named presets (e.g. .orche.mobile.json).
-See .orche.example.json for the config format.
 `);
 }
 
@@ -195,6 +198,8 @@ async function main(): Promise<void> {
 
   if (subcommand === "start") {
     startSession();
+  } else if (subcommand === "init") {
+    initCommand(process.argv.slice(3));
   } else if (subcommand === "prune") {
     const repoRoot = getRepoRoot(process.cwd());
     await pruneCommand(repoRoot, process.argv.slice(3));

package/src/init.ts

@@ -0,0 +1,121 @@
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { execSync } from "node:child_process";
+import path from "node:path";
+import pc from "picocolors";
+
+const CONFIG_NAME = ".orche.json";
+const GITIGNORE_NAME = ".gitignore";
+const GITIGNORE_ENTRY = ".orche/";
+
+const DEFAULT_CONFIG = {
+  multiplexer: "auto",
+  layout: {
+    direction: "horizontal",
+    panes: [
+      { name: "agent", command: "echo 'replace me with your agent command (e.g. claude, codex, aider)'" },
+      { name: "dev", command: "echo 'replace me with your dev server command (e.g. pnpm dev)'" },
+    ],
+  },
+};
+
+interface InitOptions {
+  force: boolean;
+}
+
+function parseOptions(argv: string[]): InitOptions {
+  return {
+    force: argv.includes("--force") || argv.includes("-f"),
+  };
+}
+
+function isAvailable(bin: string): boolean {
+  try {
+    execSync(`command -v ${bin}`, { stdio: "ignore" });
+    return true;
+  } catch (err) {
+    // command -v exits nonzero when the binary is missing — expected, not an error.
+    console.log(`[init] ${bin} not found:`, (err as Error).message);
+    return false;
+  }
+}
+
+function ensureGitRepo(cwd: string): void {
+  try {
+    execSync("git rev-parse --show-toplevel", { cwd, stdio: "ignore" });
+  } catch (err) {
+    console.error(pc.red("error:"), "not inside a git repository");
+    console.error("run `git init` first, then `orche init`");
+    console.log(`[init] git rev-parse failed:`, (err as Error).message);
+    process.exit(1);
+  }
+}
+
+function ensureMultiplexer(): "tmux" | "cmux" | "both" {
+  const tmux = isAvailable("tmux");
+  const cmux = isAvailable("cmux");
+  if (tmux && cmux) return "both";
+  if (cmux) return "cmux";
+  if (tmux) return "tmux";
+
+  console.error(pc.red("error:"), "neither tmux nor cmux is installed");
+  console.error("orche needs a terminal multiplexer to drive multiple panes. install one:");
+  console.error(`  ${pc.cyan("tmux")}: brew install tmux   (or your package manager)`);
+  console.error(`  ${pc.cyan("cmux")}: https://cmux.com`);
+  process.exit(1);
+}
+
+/** Write .orche.json. Refuses to overwrite unless force=true. */
+function writeConfig(cwd: string, force: boolean): boolean {
+  const configPath = path.join(cwd, CONFIG_NAME);
+  if (existsSync(configPath) && !force) {
+    console.log(pc.dim(`skipped ${CONFIG_NAME} (already exists — pass --force to overwrite)`));
+    return false;
+  }
+  writeFileSync(configPath, JSON.stringify(DEFAULT_CONFIG, null, 2) + "\n");
+  console.log(`${pc.green("✓")} wrote ${pc.bold(CONFIG_NAME)}`);
+  return true;
+}
+
+/** Append .orche/ to .gitignore if not present. Creates the file if missing. */
+function ensureGitignore(cwd: string): void {
+  const gitignorePath = path.join(cwd, GITIGNORE_NAME);
+  let contents = "";
+  if (existsSync(gitignorePath)) {
+    contents = readFileSync(gitignorePath, "utf-8");
+    const lines = contents.split(/\r?\n/).map((l) => l.trim());
+    // Match either ".orche/" or ".orche" (no trailing slash) — both ignore the dir.
+    if (lines.includes(GITIGNORE_ENTRY) || lines.includes(".orche")) {
+      console.log(pc.dim(`skipped ${GITIGNORE_NAME} (already ignores .orche)`));
+      return;
+    }
+  }
+  const prefix = contents.length === 0 || contents.endsWith("\n") ? "" : "\n";
+  writeFileSync(gitignorePath, contents + prefix + GITIGNORE_ENTRY + "\n");
+  console.log(`${pc.green("✓")} added ${pc.bold(GITIGNORE_ENTRY)} to ${pc.bold(GITIGNORE_NAME)}`);
+}
+
+function printNextSteps(mux: "tmux" | "cmux" | "both"): void {
+  const muxNote =
+    mux === "both" ? pc.dim("(tmux + cmux both detected — using cmux first via 'auto')") :
+    mux === "cmux" ? pc.dim("(cmux detected)") :
+    pc.dim("(tmux detected)");
+
+  console.log("");
+  console.log(pc.bold("Next:"));
+  console.log(`  1. Edit ${pc.cyan(CONFIG_NAME)} — set the panes you want (agent, dev server, etc.)`);
+  console.log(`  2. Run ${pc.cyan("orche start <task-name>")} to spin up a worktree + session`);
+  console.log(`  3. ${pc.cyan("orche review")} inside a worktree to open the diff UI`);
+  console.log("");
+  console.log(`  ${muxNote}`);
+}
+
+export function initCommand(argv: string[]): void {
+  const opts = parseOptions(argv);
+  const cwd = process.cwd();
+
+  ensureGitRepo(cwd);
+  const mux = ensureMultiplexer();
+  writeConfig(cwd, opts.force);
+  ensureGitignore(cwd);
+  printNextSteps(mux);
+}