Skip to content

The open-source app everyone uses to manage agents at work

Add paperclipai worktree:make command

Dotta80d87d3b4e08
diff --git a/cli/src/__tests__/worktree.test.ts b/cli/src/__tests__/worktree.test.ts
index 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.ts
index 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<void
export 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.md
index 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
```sh
paperclipai worktree init
+# or create the git worktree and initialize it in one step:
+pnpm paperclipai worktree:make paperclip-pr-432
```
This command: