The open-source app everyone uses to manage agents at work
TypeScript acpxagent-orchestrationagent-skillsagentic-aiai-agentsai-engineeringai-governanceai-toolsautonomous-agentsclaudeclaude-codeclaude-skillscodexhermesllmmcpmulti-agentopenclawproject-managementworkflow-automation
Add paperclipai worktree:make command
Dotta80d87d3b4e08
diff --git a/cli/src/__tests__/worktree.test.ts b/cli/src/__tests__/worktree.test.tsindex dd832df414..580eb2dc43 100644--- a/cli/src/__tests__/worktree.test.ts+++ b/cli/src/__tests__/worktree.test.ts@@ -3,7 +3,14 @@ import os from "node:os";import path from "node:path";import { execFileSync } from "node:child_process";import { describe, expect, it } from "vitest";-import { copyGitHooksToWorktreeGitDir, copySeededSecretsKey, rebindWorkspaceCwd } from "../commands/worktree.js";+import {+ copyGitHooksToWorktreeGitDir,+ copySeededSecretsKey,+ rebindWorkspaceCwd,+ resolveGitWorktreeAddArgs,+ resolveWorktreeMakeTargetPath,+ worktreeMakeCommand,+} from "../commands/worktree.js";import {buildWorktreeConfig,buildWorktreeEnvEntries,@@ -78,6 +85,36 @@ describe("worktree helpers", () => {expect(sanitizeWorktreeInstanceId(" ")).toBe("worktree");});+ it("resolves worktree:make target paths under the user home directory", () => {+ expect(resolveWorktreeMakeTargetPath("paperclip-pr-432")).toBe(+ path.resolve(os.homedir(), "paperclip-pr-432"),+ );+ });++ it("rejects worktree:make names that are not safe directory/branch names", () => {+ expect(() => resolveWorktreeMakeTargetPath("paperclip/pr-432")).toThrow(+ "Worktree name must contain only letters, numbers, dots, underscores, or dashes.",+ );+ });++ it("builds git worktree add args for new and existing branches", () => {+ expect(+ resolveGitWorktreeAddArgs({+ branchName: "feature-branch",+ targetPath: "/tmp/feature-branch",+ branchExists: false,+ }),+ ).toEqual(["worktree", "add", "-b", "feature-branch", "/tmp/feature-branch", "HEAD"]);++ expect(+ resolveGitWorktreeAddArgs({+ branchName: "feature-branch",+ targetPath: "/tmp/feature-branch",+ branchExists: true,+ }),+ ).toEqual(["worktree", "add", "/tmp/feature-branch", "feature-branch"]);+ });+it("rewrites loopback auth URLs to the new port only", () => {expect(rewriteLocalUrlPort("http://127.0.0.1:3100", 3110)).toBe("http://127.0.0.1:3110/");expect(rewriteLocalUrlPort("https://paperclip.example", 3110)).toBe("https://paperclip.example");@@ -248,4 +285,44 @@ describe("worktree helpers", () => {fs.rmSync(tempRoot, { recursive: true, force: true });}});++ it("creates and initializes a worktree from the top-level worktree:make command", async () => {+ const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), "paperclip-worktree-make-"));+ const repoRoot = path.join(tempRoot, "repo");+ const fakeHome = path.join(tempRoot, "home");+ const worktreePath = path.join(fakeHome, "paperclip-make-test");+ const originalCwd = process.cwd();+ const originalHome = process.env.HOME;++ try {+ fs.mkdirSync(repoRoot, { recursive: true });+ fs.mkdirSync(fakeHome, { recursive: true });+ execFileSync("git", ["init"], { cwd: repoRoot, stdio: "ignore" });+ execFileSync("git", ["config", "user.email", "[email protected]"], { cwd: repoRoot, stdio: "ignore" });+ execFileSync("git", ["config", "user.name", "Test User"], { cwd: repoRoot, stdio: "ignore" });+ fs.writeFileSync(path.join(repoRoot, "README.md"), "# temp\n", "utf8");+ execFileSync("git", ["add", "README.md"], { cwd: repoRoot, stdio: "ignore" });+ execFileSync("git", ["commit", "-m", "Initial commit"], { cwd: repoRoot, stdio: "ignore" });++ process.env.HOME = fakeHome;+ process.chdir(repoRoot);++ await worktreeMakeCommand("paperclip-make-test", {+ seed: false,+ home: path.join(tempRoot, ".paperclip-worktrees"),+ });++ expect(fs.existsSync(path.join(worktreePath, ".git"))).toBe(true);+ expect(fs.existsSync(path.join(worktreePath, ".paperclip", "config.json"))).toBe(true);+ expect(fs.existsSync(path.join(worktreePath, ".paperclip", ".env"))).toBe(true);+ } finally {+ process.chdir(originalCwd);+ if (originalHome === undefined) {+ delete process.env.HOME;+ } else {+ process.env.HOME = originalHome;+ }+ fs.rmSync(tempRoot, { recursive: true, force: true });+ }+ });});diff --git a/cli/src/commands/worktree.ts b/cli/src/commands/worktree.tsindex e2fa8da81a..2ef42abf54 100644--- a/cli/src/commands/worktree.ts+++ b/cli/src/commands/worktree.ts@@ -62,6 +62,8 @@ type WorktreeInitOptions = {force?: boolean;};+type WorktreeMakeOptions = WorktreeInitOptions;+type WorktreeEnvOptions = {config?: string;json?: boolean;@@ -115,6 +117,62 @@ function nonEmpty(value: string | null | undefined): string | null {return typeof value === "string" && value.trim().length > 0 ? value.trim() : null;}+function resolveWorktreeMakeName(name: string): string {+ const value = nonEmpty(name);+ if (!value) {+ throw new Error("Worktree name is required.");+ }+ if (!/^[A-Za-z0-9._-]+$/.test(value)) {+ throw new Error(+ "Worktree name must contain only letters, numbers, dots, underscores, or dashes.",+ );+ }+ return value;+}++export function resolveWorktreeMakeTargetPath(name: string): string {+ return path.resolve(os.homedir(), resolveWorktreeMakeName(name));+}++function extractExecSyncErrorMessage(error: unknown): string | null {+ if (!error || typeof error !== "object") {+ return error instanceof Error ? error.message : null;+ }++ const stderr = "stderr" in error ? error.stderr : null;+ if (typeof stderr === "string") {+ return nonEmpty(stderr);+ }+ if (stderr instanceof Buffer) {+ return nonEmpty(stderr.toString("utf8"));+ }++ return error instanceof Error ? nonEmpty(error.message) : null;+}++function localBranchExists(cwd: string, branchName: string): boolean {+ try {+ execFileSync("git", ["show-ref", "--verify", "--quiet", `refs/heads/${branchName}`], {+ cwd,+ stdio: "ignore",+ });+ return true;+ } catch {+ return false;+ }+}++export function resolveGitWorktreeAddArgs(input: {+ branchName: string;+ targetPath: string;+ branchExists: boolean;+}): string[] {+ if (input.branchExists) {+ return ["worktree", "add", input.targetPath, input.branchName];+ }+ return ["worktree", "add", "-b", input.branchName, input.targetPath, "HEAD"];+}+function readPidFilePort(postmasterPidFile: string): number | null {if (!existsSync(postmasterPidFile)) return null;try {@@ -538,10 +596,7 @@ async function seedWorktreeDatabase(input: {}}-export async function worktreeInitCommand(opts: WorktreeInitOptions): Promise<void> {- printPaperclipCliBanner();- p.intro(pc.bgCyan(pc.black(" paperclipai worktree init ")));-+async function runWorktreeInit(opts: WorktreeInitOptions): Promise<void> {const cwd = process.cwd();const name = resolveSuggestedWorktreeName(cwd,@@ -642,6 +697,57 @@ export async function worktreeInitCommand(opts: WorktreeInitOptions): Promise<vo);}+export async function worktreeInitCommand(opts: WorktreeInitOptions): Promise<void> {+ printPaperclipCliBanner();+ p.intro(pc.bgCyan(pc.black(" paperclipai worktree init ")));+ await runWorktreeInit(opts);+}++export async function worktreeMakeCommand(nameArg: string, opts: WorktreeMakeOptions): Promise<void> {+ printPaperclipCliBanner();+ p.intro(pc.bgCyan(pc.black(" paperclipai worktree:make ")));++ const name = resolveWorktreeMakeName(nameArg);+ const sourceCwd = process.cwd();+ const targetPath = resolveWorktreeMakeTargetPath(name);+ if (existsSync(targetPath)) {+ throw new Error(`Target path already exists: ${targetPath}`);+ }++ mkdirSync(path.dirname(targetPath), { recursive: true });+ const worktreeArgs = resolveGitWorktreeAddArgs({+ branchName: name,+ targetPath,+ branchExists: localBranchExists(sourceCwd, name),+ });++ const spinner = p.spinner();+ spinner.start(`Creating git worktree at ${targetPath}...`);+ try {+ execFileSync("git", worktreeArgs, {+ cwd: sourceCwd,+ stdio: ["ignore", "pipe", "pipe"],+ });+ spinner.stop(`Created git worktree at ${targetPath}.`);+ } catch (error) {+ spinner.stop(pc.red("Failed to create git worktree."));+ throw new Error(extractExecSyncErrorMessage(error) ?? String(error));+ }++ const originalCwd = process.cwd();+ try {+ process.chdir(targetPath);+ await runWorktreeInit({+ ...opts,+ name,+ });+ } catch (error) {+ throw error;+ } finally {+ process.chdir(originalCwd);+ }+}+export async function worktreeEnvCommand(opts: WorktreeEnvOptions): Promise<void> {const configPath = resolveConfigPath(opts.config);const envPath = resolvePaperclipEnvFile(configPath);@@ -665,6 +771,22 @@ export async function worktreeEnvCommand(opts: WorktreeEnvOptions): Promise<voidexport function registerWorktreeCommands(program: Command): void {const worktree = program.command("worktree").description("Worktree-local Paperclip instance helpers");+ program+ .command("worktree:make")+ .description("Create ~/NAME as a git worktree, then initialize an isolated Paperclip instance inside it")+ .argument("<name>", "Worktree directory and branch name (created at ~/NAME)")+ .option("--instance <id>", "Explicit isolated instance id")+ .option("--home <path>", `Home root for worktree instances (default: ${DEFAULT_WORKTREE_HOME})`)+ .option("--from-config <path>", "Source config.json to seed from")+ .option("--from-data-dir <path>", "Source PAPERCLIP_HOME used when deriving the source config")+ .option("--from-instance <id>", "Source instance id when deriving the source config", "default")+ .option("--server-port <port>", "Preferred server port", (value) => Number(value))+ .option("--db-port <port>", "Preferred embedded Postgres port", (value) => Number(value))+ .option("--seed-mode <mode>", "Seed profile: minimal or full (default: minimal)", "minimal")+ .option("--no-seed", "Skip database seeding from the source instance")+ .option("--force", "Replace existing repo-local config and isolated instance data", false)+ .action(worktreeMakeCommand);+worktree.command("init").description("Create repo-local config/env and an isolated instance for this worktree")diff --git a/doc/DEVELOPING.md b/doc/DEVELOPING.mdindex 6b72d3d355..8b3e16213d 100644--- a/doc/DEVELOPING.md+++ b/doc/DEVELOPING.md@@ -132,6 +132,8 @@ Instead, create a repo-local Paperclip config plus an isolated instance for the```shpaperclipai worktree init+# or create the git worktree and initialize it in one step:+pnpm paperclipai worktree:make paperclip-pr-432```This command: