@cvr/stacked 0.2.0 → 0.4.0

package/src/commands/adopt.ts

@@ -2,26 +2,80 @@ import { Argument, Command, Flag } from "effect/unstable/cli";
 import { Console, Effect, Option } from "effect";
 import { GitService } from "../services/Git.js";
 import { StackService } from "../services/Stack.js";
-import { StackError } from "../errors/index.js";
+import { ErrorCode, StackError } from "../errors/index.js";
+import { validateBranchName } from "./helpers/validate.js";
+import { dim } from "../ui.js";
 
-const branchArg = Argument.string("branch");
-const afterFlag = Flag.string("after").pipe(Flag.optional, Flag.withAlias("a"));
+const branchArg = Argument.string("branch").pipe(Argument.withDescription("Branch name to adopt"));
+const afterFlag = Flag.string("after").pipe(
+  Flag.optional,
+  Flag.withAlias("a"),
+  Flag.withDescription("Insert after this branch in the stack"),
+);
+const jsonFlag = Flag.boolean("json").pipe(Flag.withDescription("Output as JSON"));
 
-export const adopt = Command.make("adopt", { branch: branchArg, after: afterFlag }).pipe(
+export const adopt = Command.make("adopt", {
+  branch: branchArg,
+  after: afterFlag,
+  json: jsonFlag,
+}).pipe(
   Command.withDescription("Adopt existing git branch into current stack"),
-  Command.withHandler(({ branch, after }) =>
+  Command.withExamples([
+    { command: "stacked adopt feat-existing", description: "Add branch to current stack" },
+    {
+      command: "stacked adopt feat-x --after feat-a",
+      description: "Insert after a specific branch",
+    },
+  ]),
+  Command.withHandler(({ branch, after, json }) =>
     Effect.gen(function* () {
       const git = yield* GitService;
       const stacks = yield* StackService;
 
+      yield* validateBranchName(branch);
+
+      const trunk = yield* stacks.getTrunk();
+      if (branch === trunk) {
+        return yield* new StackError({
+          code: ErrorCode.TRUNK_ERROR,
+          message: `Cannot adopt trunk branch "${trunk}" into a stack`,
+        });
+      }
+
       const exists = yield* git.branchExists(branch);
       if (!exists) {
-        return yield* new StackError({ message: `Branch "${branch}" does not exist` });
+        return yield* new StackError({
+          code: ErrorCode.BRANCH_NOT_FOUND,
+          message: `Branch "${branch}" does not exist`,
+        });
+      }
+
+      const alreadyTracked = yield* stacks.findBranchStack(branch);
+      if (alreadyTracked !== null) {
+        const result = yield* stacks.currentStack();
+        if (result !== null && alreadyTracked.name === result.name) {
+          if (json) {
+            // @effect-diagnostics-next-line effect/preferSchemaOverJson:off
+            yield* Console.log(
+              JSON.stringify(
+                { adopted: branch, stack: result.name, alreadyTracked: true },
+                null,
+                2,
+              ),
+            );
+          } else {
+            yield* Console.error(`Branch "${branch}" is already in stack "${result.name}"`);
+          }
+          return;
+        }
+        return yield* new StackError({
+          code: ErrorCode.BRANCH_EXISTS,
+          message: `Branch "${branch}" is already tracked in stack "${alreadyTracked.name}"`,
+        });
       }
 
       const result = yield* stacks.currentStack();
       if (result === null) {
-        const trunk = yield* stacks.getTrunk();
         const currentBranch = yield* git.currentBranch();
         if (currentBranch === trunk) {
           yield* stacks.createStack(branch, [branch]);
@@ -33,7 +87,15 @@ export const adopt = Command.make("adopt", { branch: branchArg, after: afterFlag
         yield* stacks.addBranch(result.name, branch, afterBranch);
       }
 
-      yield* Console.log(`Adopted ${branch} into stack`);
+      if (json) {
+        const stackResult = yield* stacks.currentStack();
+        const stackName = stackResult?.name ?? branch;
+        // @effect-diagnostics-next-line effect/preferSchemaOverJson:off
+        yield* Console.log(JSON.stringify({ adopted: branch, stack: stackName }, null, 2));
+      } else {
+        yield* Console.error(`Adopted ${branch} into stack`);
+        yield* Console.error(dim("Run 'stacked sync' to rebase onto the new parent."));
+      }
     }),
   ),
 );

package/src/commands/amend.ts

@@ -0,0 +1,107 @@
+import { Command, Flag } from "effect/unstable/cli";
+import { Console, Effect, Option } from "effect";
+import { GitService } from "../services/Git.js";
+import { StackService } from "../services/Stack.js";
+import { ErrorCode, StackError } from "../errors/index.js";
+import { success, withSpinner } from "../ui.js";
+
+const editFlag = Flag.boolean("edit").pipe(Flag.withDescription("Open editor for commit message"));
+const jsonFlag = Flag.boolean("json").pipe(Flag.withDescription("Output as JSON"));
+const fromFlag = Flag.string("from").pipe(
+  Flag.optional,
+  Flag.withDescription("Start syncing from this branch (defaults to current)"),
+);
+
+export const amend = Command.make("amend", {
+  edit: editFlag,
+  json: jsonFlag,
+  from: fromFlag,
+}).pipe(
+  Command.withDescription("Amend current commit and rebase children"),
+  Command.withExamples([
+    { command: "stacked amend", description: "Amend and auto-rebase children" },
+    { command: "stacked amend --edit", description: "Amend with editor" },
+  ]),
+  Command.withHandler(({ edit, json, from }) =>
+    Effect.gen(function* () {
+      const git = yield* GitService;
+      const stacks = yield* StackService;
+
+      const currentBranch = yield* git.currentBranch();
+      const result = yield* stacks.currentStack();
+      if (result === null) {
+        return yield* new StackError({
+          code: ErrorCode.NOT_IN_STACK,
+          message:
+            "Not on a stacked branch. Run 'stacked list' to see your stacks, or 'stacked create <name>' to start one.",
+        });
+      }
+
+      yield* git.commitAmend({ edit });
+
+      const fromBranch = Option.isSome(from) ? from.value : currentBranch;
+
+      // Find children to rebase
+      const { branches } = result.stack;
+      const idx = branches.indexOf(fromBranch);
+      if (idx === -1 || idx >= branches.length - 1) {
+        if (json) {
+          // @effect-diagnostics-next-line effect/preferSchemaOverJson:off
+          yield* Console.log(JSON.stringify({ amended: currentBranch, synced: [] }, null, 2));
+        } else {
+          yield* success(`Amended ${currentBranch} (no children to rebase)`);
+        }
+        return;
+      }
+
+      // Rebase children
+      const children = branches.slice(idx + 1);
+      const synced: string[] = [];
+
+      yield* Effect.gen(function* () {
+        for (let i = 0; i < children.length; i++) {
+          const branch = children[i];
+          if (branch === undefined) continue;
+          const newBase = i === 0 ? fromBranch : (children[i - 1] ?? fromBranch);
+
+          const oldBase = yield* git
+            .mergeBase(branch, newBase)
+            .pipe(Effect.catchTag("GitError", () => Effect.succeed(newBase)));
+
+          yield* git.checkout(branch);
+          yield* withSpinner(
+            `Rebasing ${branch} onto ${newBase}`,
+            git.rebaseOnto(branch, newBase, oldBase),
+          ).pipe(
+            Effect.catchTag("GitError", (e) =>
+              Effect.fail(
+                new StackError({
+                  code: ErrorCode.REBASE_CONFLICT,
+                  message: `Rebase conflict on ${branch}: ${e.message}\n\nResolve conflicts, then run:\n  git rebase --continue`,
+                }),
+              ),
+            ),
+          );
+          synced.push(branch);
+        }
+      }).pipe(
+        Effect.ensuring(
+          git
+            .isRebaseInProgress()
+            .pipe(
+              Effect.andThen((inProgress) =>
+                inProgress ? Effect.void : git.checkout(currentBranch).pipe(Effect.ignore),
+              ),
+            ),
+        ),
+      );
+
+      if (json) {
+        // @effect-diagnostics-next-line effect/preferSchemaOverJson:off
+        yield* Console.log(JSON.stringify({ amended: currentBranch, synced }, null, 2));
+      } else {
+        yield* success(`Amended ${currentBranch} and rebased ${synced.length} child branch(es)`);
+      }
+    }),
+  ),
+);

package/src/commands/bottom.ts

@@ -1,29 +1,47 @@
-import { Command } from "effect/unstable/cli";
+import { Command, Flag } from "effect/unstable/cli";
 import { Console, Effect } from "effect";
 import { GitService } from "../services/Git.js";
 import { StackService } from "../services/Stack.js";
+import { ErrorCode, StackError } from "../errors/index.js";
+import { success } from "../ui.js";
 
-export const bottom = Command.make("bottom").pipe(
+const jsonFlag = Flag.boolean("json").pipe(Flag.withDescription("Output as JSON"));
+
+export const bottom = Command.make("bottom", { json: jsonFlag }).pipe(
   Command.withDescription("Checkout bottom branch of stack"),
-  Command.withHandler(() =>
+  Command.withExamples([
+    { command: "stacked bottom", description: "Jump to the bottom of the stack" },
+  ]),
+  Command.withHandler(({ json }) =>
     Effect.gen(function* () {
       const git = yield* GitService;
       const stacks = yield* StackService;
 
       const result = yield* stacks.currentStack();
       if (result === null) {
-        yield* Console.error("Not on a stacked branch");
-        return;
+        return yield* new StackError({
+          code: ErrorCode.NOT_IN_STACK,
+          message:
+            "Not on a stacked branch. Run 'stacked list' to see your stacks, or 'stacked create <name>' to start one.",
+        });
       }
 
       const bottomBranch = result.stack.branches[0];
       if (bottomBranch === undefined) {
-        yield* Console.error("Stack is empty");
-        return;
+        return yield* new StackError({
+          code: ErrorCode.STACK_EMPTY,
+          message: "Stack is empty. Run 'stacked create <name>' to add a branch.",
+        });
       }
 
       yield* git.checkout(bottomBranch);
-      yield* Console.log(`Switched to ${bottomBranch}`);
+
+      if (json) {
+        // @effect-diagnostics-next-line effect/preferSchemaOverJson:off
+        yield* Console.log(JSON.stringify({ branch: bottomBranch }, null, 2));
+      } else {
+        yield* success(`Switched to ${bottomBranch}`);
+      }
     }),
   ),
 );

package/src/commands/checkout.ts

@@ -1,15 +1,34 @@
-import { Argument, Command } from "effect/unstable/cli";
-import { Effect } from "effect";
+import { Argument, Command, Flag } from "effect/unstable/cli";
+import { Console, Effect } from "effect";
 import { GitService } from "../services/Git.js";
+import { StackService } from "../services/Stack.js";
+import { success } from "../ui.js";
 
-const nameArg = Argument.string("name");
+const nameArg = Argument.string("name").pipe(Argument.withDescription("Branch name to check out"));
+const jsonFlag = Flag.boolean("json").pipe(Flag.withDescription("Output as JSON"));
 
-export const checkout = Command.make("checkout", { name: nameArg }).pipe(
-  Command.withDescription("Switch to branch in current stack"),
-  Command.withHandler(({ name }) =>
+export const checkout = Command.make("checkout", { name: nameArg, json: jsonFlag }).pipe(
+  Command.withDescription("Switch to a branch (falls through to git if not in a stack)"),
+  Command.withExamples([
+    { command: "stacked checkout feat-b", description: "Switch to a stacked branch" },
+  ]),
+  Command.withHandler(({ name, json }) =>
     Effect.gen(function* () {
       const git = yield* GitService;
+      const stacks = yield* StackService;
+
+      const result = yield* stacks.findBranchStack(name);
+
       yield* git.checkout(name);
+
+      if (json) {
+        // @effect-diagnostics-next-line effect/preferSchemaOverJson:off
+        yield* Console.log(JSON.stringify({ branch: name, inStack: result !== null }, null, 2));
+      } else if (result !== null) {
+        yield* success(`Switched to ${name}`);
+      } else {
+        yield* success(`Switched to ${name} (not in a stack)`);
+      }
     }),
   ),
 );

package/src/commands/clean.ts

@@ -3,27 +3,60 @@ import { Console, Effect } from "effect";
 import { GitService } from "../services/Git.js";
 import { GitHubService } from "../services/GitHub.js";
 import { StackService } from "../services/Stack.js";
+import { ErrorCode, StackError } from "../errors/index.js";
+import { success, warn, dim, confirm } from "../ui.js";
 
-const dryRunFlag = Flag.boolean("dry-run");
+const dryRunFlag = Flag.boolean("dry-run").pipe(
+  Flag.withDescription("Show what would be removed without making changes"),
+);
+const jsonFlag = Flag.boolean("json").pipe(Flag.withDescription("Output as JSON"));
 
-export const clean = Command.make("clean", { dryRun: dryRunFlag }).pipe(
+export const clean = Command.make("clean", { dryRun: dryRunFlag, json: jsonFlag }).pipe(
   Command.withDescription("Remove merged branches from stacks (bottom-up)"),
-  Command.withHandler(({ dryRun }) =>
+  Command.withExamples([
+    { command: "stacked clean", description: "Remove merged branches" },
+    { command: "stacked clean --dry-run", description: "Preview what would be removed" },
+  ]),
+  Command.withHandler(({ dryRun, json }) =>
     Effect.gen(function* () {
       const git = yield* GitService;
       const gh = yield* GitHubService;
       const stacks = yield* StackService;
 
-      const currentBranch = yield* git.currentBranch();
+      const ghInstalled = yield* gh.isGhInstalled();
+      if (!ghInstalled) {
+        return yield* new StackError({
+          code: ErrorCode.GH_NOT_INSTALLED,
+          message: "gh CLI is not installed. Install it from https://cli.github.com",
+        });
+      }
+
+      let currentBranch = yield* git.currentBranch();
       const data = yield* stacks.load();
 
+      // Fetch all PR statuses in parallel across all stacks
+      const allBranches = Object.entries(data.stacks).flatMap(([stackName, stack]) =>
+        stack.branches.map((branch) => ({ stackName, branch })),
+      );
+
+      const prResults = yield* Effect.forEach(
+        allBranches,
+        ({ branch }) =>
+          gh.getPR(branch).pipe(
+            Effect.catchTag("GitHubError", () => Effect.succeed(null)),
+            Effect.map((pr) => [branch, pr] as const),
+          ),
+        { concurrency: 5 },
+      );
+      const prMap = new Map(prResults);
+
       const toRemove: Array<{ stackName: string; branch: string }> = [];
       const skippedMerged: Array<{ stackName: string; branch: string }> = [];
 
       for (const [stackName, stack] of Object.entries(data.stacks)) {
         let hitNonMerged = false;
         for (const branch of stack.branches) {
-          const pr = yield* gh.getPR(branch).pipe(Effect.catch(() => Effect.succeed(null)));
+          const pr = prMap.get(branch) ?? null;
           const isMerged = pr !== null && pr.state === "MERGED";
 
           if (!hitNonMerged && isMerged) {
@@ -36,48 +69,94 @@ export const clean = Command.make("clean", { dryRun: dryRunFlag }).pipe(
       }
 
       if (toRemove.length === 0) {
-        yield* Console.log("Nothing to clean");
-        if (skippedMerged.length > 0) {
-          yield* Console.log(
-            `\nNote: ${skippedMerged.length} merged branch${skippedMerged.length === 1 ? "" : "es"} skipped (non-merged branches below):`,
-          );
-          for (const { branch, stackName } of skippedMerged) {
-            yield* Console.log(`  ${branch} (${stackName})`);
+        if (json) {
+          // @effect-diagnostics-next-line effect/preferSchemaOverJson:off
+          yield* Console.log(JSON.stringify({ removed: [], skipped: [] }, null, 2));
+        } else {
+          yield* Console.error("Nothing to clean");
+          if (skippedMerged.length > 0) {
+            yield* warn(
+              `${skippedMerged.length} merged branch${skippedMerged.length === 1 ? "" : "es"} skipped (non-merged branches below):`,
+            );
+            for (const { branch, stackName } of skippedMerged) {
+              yield* Console.error(dim(`  ${branch} (${stackName})`));
+            }
           }
         }
         return;
       }
 
+      if (!dryRun) {
+        for (const { branch } of toRemove) {
+          yield* Console.error(dim(`  ${branch}`));
+        }
+        const confirmed = yield* confirm(
+          `Remove ${toRemove.length} merged branch${toRemove.length === 1 ? "" : "es"}?`,
+        );
+        if (!confirmed) {
+          yield* Console.error("Aborted");
+          return;
+        }
+      }
+
+      const removed: string[] = [];
+
       for (const { stackName, branch } of toRemove) {
         if (dryRun) {
-          yield* Console.log(`Would remove ${branch} from ${stackName}`);
+          yield* Console.error(`Would remove ${branch} from ${stackName}`);
+          removed.push(branch);
         } else {
           if (currentBranch === branch) {
             const trunk = yield* stacks.getTrunk();
             yield* git.checkout(trunk);
+            currentBranch = trunk;
+          }
+          const deleted = yield* git.deleteBranch(branch, true).pipe(
+            Effect.as(true),
+            Effect.catchTag("GitError", (e) =>
+              Console.error(`Warning: failed to delete local branch ${branch}: ${e.message}`).pipe(
+                Effect.as(false),
+              ),
+            ),
+          );
+          yield* git
+            .deleteRemoteBranch(branch)
+            .pipe(
+              Effect.catchTag("GitError", (e) =>
+                Console.error(`Warning: failed to delete remote branch ${branch}: ${e.message}`),
+              ),
+            );
+          if (deleted) {
+            yield* stacks.removeBranch(stackName, branch);
+            removed.push(branch);
+            yield* success(`Removed ${branch} from ${stackName}`);
           }
-          yield* stacks.removeBranch(stackName, branch);
-          yield* git.deleteBranch(branch, true).pipe(Effect.catch(() => Effect.void));
-          yield* Console.log(`Removed ${branch} from ${stackName}`);
         }
       }
 
-      if (dryRun) {
-        yield* Console.log(
+      if (json) {
+        const skipped = skippedMerged.map((x) => x.branch);
+        // @effect-diagnostics-next-line effect/preferSchemaOverJson:off
+        yield* Console.log(JSON.stringify({ removed, skipped }, null, 2));
+      } else if (dryRun) {
+        yield* Console.error(
           `\n${toRemove.length} branch${toRemove.length === 1 ? "" : "es"} would be removed`,
         );
       } else {
-        yield* Console.log(
-          `\nCleaned ${toRemove.length} merged branch${toRemove.length === 1 ? "" : "es"}`,
+        yield* success(
+          `Cleaned ${removed.length} merged branch${removed.length === 1 ? "" : "es"}`,
         );
-      }
-
-      if (skippedMerged.length > 0) {
-        yield* Console.log(
-          `\nNote: ${skippedMerged.length} merged branch${skippedMerged.length === 1 ? "" : "es"} skipped (non-merged branches below):`,
+        yield* Console.error(
+          dim("Run 'stacked sync' then 'stacked submit' to rebase and retarget PRs."),
         );
-        for (const { branch, stackName } of skippedMerged) {
-          yield* Console.log(`  ${branch} (${stackName})`);
+
+        if (skippedMerged.length > 0) {
+          yield* warn(
+            `${skippedMerged.length} merged branch${skippedMerged.length === 1 ? "" : "es"} skipped (non-merged branches below):`,
+          );
+          for (const { branch, stackName } of skippedMerged) {
+            yield* Console.error(dim(`  ${branch} (${stackName})`));
+          }
         }
       }
     }),

package/src/commands/create.ts

@@ -2,31 +2,87 @@ import { Argument, Command, Flag } from "effect/unstable/cli";
 import { Console, Effect, Option } from "effect";
 import { GitService } from "../services/Git.js";
 import { StackService } from "../services/Stack.js";
+import { ErrorCode, StackError } from "../errors/index.js";
+import { validateBranchName } from "./helpers/validate.js";
 
-const nameArg = Argument.string("name");
-const fromFlag = Flag.string("from").pipe(Flag.optional, Flag.withAlias("f"));
+const nameArg = Argument.string("name").pipe(Argument.withDescription("Branch name to create"));
+const fromFlag = Flag.string("from").pipe(
+  Flag.optional,
+  Flag.withAlias("f"),
+  Flag.withDescription("Branch from a specific branch instead of current"),
+);
+const jsonFlag = Flag.boolean("json").pipe(Flag.withDescription("Output as JSON"));
 
-export const create = Command.make("create", { name: nameArg, from: fromFlag }).pipe(
+export const create = Command.make("create", {
+  name: nameArg,
+  from: fromFlag,
+  json: jsonFlag,
+}).pipe(
   Command.withDescription("Create a new branch on top of current branch in stack"),
-  Command.withHandler(({ name, from }) =>
+  Command.withExamples([
+    { command: "stacked create feat-auth", description: "Create branch on top of current" },
+    {
+      command: "stacked create feat-ui --from feat-auth",
+      description: "Branch from a specific branch",
+    },
+  ]),
+  Command.withHandler(({ name, from, json }) =>
     Effect.gen(function* () {
       const git = yield* GitService;
       const stacks = yield* StackService;
 
+      yield* validateBranchName(name);
+
       const currentBranch = yield* git.currentBranch();
       const baseBranch = Option.isSome(from) ? from.value : currentBranch;
       const trunk = yield* stacks.getTrunk();
 
-      const data = yield* stacks.load();
-      let stackName: string | null = null;
+      if (name === trunk) {
+        return yield* new StackError({
+          code: ErrorCode.TRUNK_ERROR,
+          message: `Cannot create a branch with the same name as trunk ("${trunk}")`,
+        });
+      }
+
+      if (Option.isSome(from)) {
+        const fromExists = yield* git.branchExists(from.value);
+        if (!fromExists) {
+          return yield* new StackError({
+            code: ErrorCode.BRANCH_NOT_FOUND,
+            message: `Branch "${from.value}" does not exist`,
+          });
+        }
+      }
 
-      for (const [sName, stack] of Object.entries(data.stacks)) {
-        if (stack.branches.includes(baseBranch)) {
-          stackName = sName;
-          break;
+      const branchAlreadyExists = yield* git.branchExists(name);
+      if (branchAlreadyExists) {
+        const tracked = yield* stacks.findBranchStack(name);
+        if (tracked !== null) {
+          if (json) {
+            // @effect-diagnostics-next-line effect/preferSchemaOverJson:off
+            yield* Console.log(
+              JSON.stringify(
+                { branch: name, stack: tracked.name, base: baseBranch, alreadyExists: true },
+                null,
+                2,
+              ),
+            );
+          } else {
+            yield* Console.error(`Branch "${name}" already exists in stack "${tracked.name}"`);
+          }
+          return;
         }
+        return yield* new StackError({
+          code: ErrorCode.BRANCH_EXISTS,
+          message: `Branch "${name}" already exists but is not tracked in any stack`,
+        });
       }
 
+      const existing = yield* stacks.findBranchStack(baseBranch);
+      let stackName = existing?.name ?? null;
+
+      yield* git.createBranch(name, baseBranch);
+
       if (stackName === null) {
         if (baseBranch === trunk) {
           stackName = name;
@@ -37,10 +93,16 @@ export const create = Command.make("create", { name: nameArg, from: fromFlag }).
         }
       }
 
-      yield* git.createBranch(name, baseBranch);
       yield* stacks.addBranch(stackName, name, baseBranch === trunk ? undefined : baseBranch);
 
-      yield* Console.log(`Created branch ${name} on top of ${baseBranch}`);
+      if (json) {
+        // @effect-diagnostics-next-line effect/preferSchemaOverJson:off
+        yield* Console.log(
+          JSON.stringify({ branch: name, stack: stackName, base: baseBranch }, null, 2),
+        );
+      } else {
+        yield* Console.error(`Created branch ${name} on top of ${baseBranch}`);
+      }
     }),
   ),
 );