@cvr/stacked 0.3.0 → 0.4.1

package/src/commands/submit.ts

@@ -1,68 +1,324 @@
 import { Command, Flag } from "effect/unstable/cli";
-import { Console, Effect } from "effect";
+import { Console, Effect, Option } from "effect";
 import { GitService } from "../services/Git.js";
 import { StackService } from "../services/Stack.js";
 import { GitHubService } from "../services/GitHub.js";
+import { ErrorCode, StackError } from "../errors/index.js";
+import { withSpinner, success } from "../ui.js";
 
-const draftFlag = Flag.boolean("draft").pipe(Flag.withAlias("d"));
-const forceFlag = Flag.boolean("force").pipe(Flag.withAlias("f"));
-const dryRunFlag = Flag.boolean("dry-run");
+const draftFlag = Flag.boolean("draft").pipe(
+  Flag.withAlias("d"),
+  Flag.withDescription("Create PRs as drafts"),
+);
+const noForceFlag = Flag.boolean("no-force").pipe(
+  Flag.withDescription("Disable force-push (force-with-lease is on by default)"),
+);
+const dryRunFlag = Flag.boolean("dry-run").pipe(
+  Flag.withDescription("Show what would happen without making changes"),
+);
+const titleFlag = Flag.string("title").pipe(
+  Flag.optional,
+  Flag.withAlias("t"),
+  Flag.withDescription(
+    "PR title (defaults to branch name). Comma-delimited for per-branch titles.",
+  ),
+);
+const bodyFlag = Flag.string("body").pipe(
+  Flag.optional,
+  Flag.withAlias("b"),
+  Flag.withDescription("PR body/description. Comma-delimited for per-branch bodies."),
+);
+const onlyFlag = Flag.boolean("only").pipe(Flag.withDescription("Only submit the current branch"));
+
+interface SubmitResult {
+  branch: string;
+  base: string;
+  number?: number;
+  url?: string;
+  action: "created" | "updated" | "unchanged" | "would-create" | "would-update" | "would-unchanged";
+}
+
+const STACKED_MARKER_START = "<!-- stacked -->";
+const STACKED_MARKER_END = "<!-- /stacked -->";
+
+const generateStackMetadata = (
+  branches: readonly string[],
+  prMap: Map<string, { number: number; url: string; state: string } | null>,
+  currentIdx: number,
+  stackName: string,
+): string => {
+  const rows = branches.map((branch, i) => {
+    const pr = prMap.get(branch) ?? null;
+    const isCurrent = i === currentIdx;
+    const branchCol = isCurrent ? `**\`${branch}\`**` : `\`${branch}\``;
+    const numCol = i + 1;
+    const numStr = isCurrent ? `**${numCol}**` : `${numCol}`;
+
+    let prCol: string;
+    if (pr === null) {
+      prCol = "—";
+    } else if (pr.state === "MERGED") {
+      prCol = `[#${pr.number}](${pr.url}) ✅`;
+    } else if (isCurrent) {
+      prCol = `**#${pr.number} ← you are here**`;
+    } else {
+      prCol = `[#${pr.number}](${pr.url})`;
+    }
+
+    return `| ${numStr} | ${branchCol} | ${prCol} |`;
+  });
+
+  return [
+    STACKED_MARKER_START,
+    `**Stack: \`${stackName}\`** (${currentIdx + 1} of ${branches.length})`,
+    "",
+    "| # | Branch | PR |",
+    "|---|--------|----|",
+    ...rows,
+    STACKED_MARKER_END,
+  ].join("\n");
+};
+
+const composePRBody = (userBody: string | undefined, metadata: string): string => {
+  if (userBody !== undefined) {
+    return `${userBody}\n\n---\n\n${metadata}`;
+  }
+  return metadata;
+};
+
+const updatePRBody = (
+  existingBody: string | undefined,
+  userBody: string | undefined,
+  metadata: string,
+): string => {
+  if (userBody !== undefined) {
+    return composePRBody(userBody, metadata);
+  }
+
+  if (existingBody !== undefined) {
+    const startIdx = existingBody.indexOf(STACKED_MARKER_START);
+    if (startIdx !== -1) {
+      const prefix = existingBody.substring(0, startIdx).replace(/\n*---\n*$/, "");
+      if (prefix.trim().length > 0) {
+        return `${prefix.trim()}\n\n---\n\n${metadata}`;
+      }
+      return metadata;
+    }
+    return `${existingBody.trim()}\n\n---\n\n${metadata}`;
+  }
+
+  return metadata;
+};
+
+const jsonFlag = Flag.boolean("json").pipe(Flag.withDescription("Output as JSON"));
 
 export const submit = Command.make("submit", {
   draft: draftFlag,
-  force: forceFlag,
+  noForce: noForceFlag,
   dryRun: dryRunFlag,
+  title: titleFlag,
+  body: bodyFlag,
+  only: onlyFlag,
+  json: jsonFlag,
 }).pipe(
   Command.withDescription("Push all stack branches and create/update PRs via gh"),
-  Command.withHandler(({ draft, force, dryRun }) =>
+  Command.withExamples([
+    { command: "stacked submit", description: "Push and create/update PRs for all branches" },
+    { command: "stacked submit --draft", description: "Create PRs as drafts" },
+    { command: "stacked submit --only", description: "Submit only the current branch" },
+    {
+      command: 'stacked submit --title "Add auth" --body "Implements OAuth2"',
+      description: "With PR title and body",
+    },
+  ]),
+  Command.withHandler(({ draft, noForce, dryRun, title: titleOpt, body: bodyOpt, only, json }) =>
     Effect.gen(function* () {
       const git = yield* GitService;
       const stacks = yield* StackService;
       const gh = yield* GitHubService;
 
+      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",
+        });
+      }
+
       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 trunk = yield* stacks.getTrunk();
+      const currentBranch = yield* git.currentBranch();
       const { branches } = result.stack;
 
+      const rawTitle = Option.isSome(titleOpt) ? titleOpt.value : undefined;
+      const rawBody = Option.isSome(bodyOpt) ? bodyOpt.value : undefined;
+
+      // Parse comma-delimited titles/bodies for per-branch support
+      const titles =
+        rawTitle !== undefined && rawTitle.includes(",")
+          ? rawTitle.split(",").map((s) => s.trim())
+          : undefined;
+      const bodies =
+        rawBody !== undefined && rawBody.includes(",")
+          ? rawBody.split(",").map((s) => s.trim())
+          : undefined;
+
+      if (titles !== undefined && titles.length !== branches.length) {
+        return yield* new StackError({
+          message: `--title has ${titles.length} values but stack has ${branches.length} branches`,
+        });
+      }
+      if (bodies !== undefined && bodies.length !== branches.length) {
+        return yield* new StackError({
+          message: `--body has ${bodies.length} values but stack has ${branches.length} branches`,
+        });
+      }
+
+      const getTitleForBranch = (branch: string, idx: number): string | undefined => {
+        if (titles !== undefined) return titles[idx];
+        // Single --title: apply only to current branch
+        if (rawTitle !== undefined && branch === currentBranch) return rawTitle;
+        return undefined;
+      };
+
+      const getBodyForBranch = (branch: string, idx: number): string | undefined => {
+        if (bodies !== undefined) return bodies[idx];
+        // Single --body: apply only to current branch
+        if (rawBody !== undefined && branch === currentBranch) return rawBody;
+        return undefined;
+      };
+
+      const results: SubmitResult[] = [];
+      const prMap = new Map<
+        string,
+        { number: number; url: string; state: string; body?: string | null } | null
+      >();
+
       for (let i = 0; i < branches.length; i++) {
         const branch = branches[i];
         if (branch === undefined) continue;
         const base = i === 0 ? trunk : (branches[i - 1] ?? trunk);
 
+        // --only: skip branches that aren't current
+        if (only && branch !== currentBranch) continue;
+
         if (dryRun) {
-          yield* Console.log(`Would push ${branch} and create/update PR (base: ${base})`);
+          const existingPR = yield* gh.getPR(branch);
+          const action =
+            existingPR === null
+              ? "would-create"
+              : existingPR.base !== base
+                ? "would-update"
+                : "would-unchanged";
+          results.push({
+            branch,
+            base,
+            number: existingPR?.number,
+            url: existingPR?.url,
+            action,
+          });
+          if (!json) {
+            yield* Console.error(`Would push ${branch} and create/update PR (base: ${base})`);
+          }
           continue;
         }
 
-        yield* Console.log(`Pushing ${branch}...`);
-        yield* git.push(branch, { force });
+        yield* withSpinner(`Pushing ${branch}`, git.push(branch, { force: !noForce }));
 
         const existingPR = yield* gh.getPR(branch);
+        prMap.set(branch, existingPR);
 
         if (existingPR !== null) {
           if (existingPR.base !== base) {
-            yield* Console.log(`Updating PR #${existingPR.number} base to ${base}`);
+            yield* Console.error(`Updating PR #${existingPR.number} base to ${base}`);
             yield* gh.updatePR({ branch, base });
+            results.push({
+              branch,
+              base,
+              number: existingPR.number,
+              url: existingPR.url,
+              action: "updated",
+            });
           } else {
-            yield* Console.log(`PR #${existingPR.number} already exists: ${existingPR.url}`);
+            yield* Console.error(`PR #${existingPR.number} already exists: ${existingPR.url}`);
+            results.push({
+              branch,
+              base,
+              number: existingPR.number,
+              url: existingPR.url,
+              action: "unchanged",
+            });
           }
         } else {
+          const userTitle = getTitleForBranch(branch, i);
+          const title =
+            userTitle ?? branch.replace(/[-_]/g, " ").replace(/^\w/, (c) => c.toUpperCase());
+          const metadata = generateStackMetadata(branches, prMap, i, result.name);
+          const userBody = getBodyForBranch(branch, i);
+          const body = composePRBody(userBody, metadata);
+
           const pr = yield* gh.createPR({
             head: branch,
             base,
-            title: branch,
+            title,
+            body,
             draft,
           });
-          yield* Console.log(`Created PR #${pr.number}: ${pr.url}`);
+          prMap.set(branch, { number: pr.number, url: pr.url, state: "OPEN" });
+          yield* success(`Created PR #${pr.number}: ${pr.url}`);
+          results.push({
+            branch,
+            base,
+            number: pr.number,
+            url: pr.url,
+            action: "created",
+          });
+        }
+      }
+
+      if (dryRun) {
+        if (json) {
+          // @effect-diagnostics-next-line effect/preferSchemaOverJson:off
+          yield* Console.log(JSON.stringify({ results }, null, 2));
         }
+        return;
+      }
+
+      // Update all processed PRs with complete stack metadata.
+      // This includes newly created PRs so placeholders get replaced in one submit run.
+      for (let i = 0; i < branches.length; i++) {
+        const branch = branches[i];
+        if (branch === undefined) continue;
+        if (only && branch !== currentBranch) continue;
+
+        const entry = results.find((x) => x.branch === branch);
+        if (entry === undefined) continue;
+
+        const metadata = generateStackMetadata(branches, prMap, i, result.name);
+        const existingPrData = prMap.get(branch) ?? null;
+        const existingBody = existingPrData?.body ?? undefined;
+        const userBody = getBodyForBranch(branch, i);
+        const body = updatePRBody(existingBody, userBody, metadata);
+        yield* gh.updatePR({ branch, body });
       }
 
-      yield* Console.log("Done");
+      // Print structured output to stdout
+      if (json) {
+        // @effect-diagnostics-next-line effect/preferSchemaOverJson:off
+        yield* Console.log(JSON.stringify({ results }, null, 2));
+      } else {
+        for (const r of results) {
+          yield* Console.log(`${r.branch} #${r.number} ${r.url} ${r.action}`);
+        }
+      }
     }),
   ),
 );

package/src/commands/sync.ts

@@ -2,13 +2,45 @@ 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 { withSpinner, success, warn } from "../ui.js";
 
-const trunkFlag = Flag.string("trunk").pipe(Flag.optional, Flag.withAlias("t"));
-const fromFlag = Flag.string("from").pipe(Flag.optional, Flag.withAlias("f"));
+const trunkFlag = Flag.string("trunk").pipe(
+  Flag.optional,
+  Flag.withAlias("t"),
+  Flag.withDescription("Override trunk branch for this sync"),
+);
+const fromFlag = Flag.string("from").pipe(
+  Flag.optional,
+  Flag.withAlias("f"),
+  Flag.withDescription("Start rebasing after this branch (exclusive)"),
+);
+const jsonFlag = Flag.boolean("json").pipe(Flag.withDescription("Output as JSON"));
+const dryRunFlag = Flag.boolean("dry-run").pipe(
+  Flag.withDescription("Show rebase plan without executing"),
+);
 
-export const sync = Command.make("sync", { trunk: trunkFlag, from: fromFlag }).pipe(
-  Command.withDescription("Fetch and rebase stack on trunk. Use --from to start from a branch."),
-  Command.withHandler(({ trunk: trunkOpt, from: fromOpt }) =>
+interface SyncResult {
+  name: string;
+  action: "rebased" | "skipped" | "up-to-date";
+  base: string;
+}
+
+export const sync = Command.make("sync", {
+  trunk: trunkFlag,
+  from: fromFlag,
+  json: jsonFlag,
+  dryRun: dryRunFlag,
+}).pipe(
+  Command.withDescription(
+    "Fetch, rebase, and force-push stack branches. Use --from to start from a branch.",
+  ),
+  Command.withExamples([
+    { command: "stacked sync", description: "Rebase entire stack on trunk" },
+    { command: "stacked sync --from feat-auth", description: "Resume from a specific branch" },
+    { command: "stacked sync --dry-run", description: "Preview rebase plan" },
+  ]),
+  Command.withHandler(({ trunk: trunkOpt, from: fromOpt, json, dryRun }) =>
     Effect.gen(function* () {
       const git = yield* GitService;
       const stacks = yield* StackService;
@@ -16,13 +48,23 @@ export const sync = Command.make("sync", { trunk: trunkFlag, from: fromFlag }).p
       const trunk = Option.isSome(trunkOpt) ? trunkOpt.value : yield* stacks.getTrunk();
       const currentBranch = yield* git.currentBranch();
 
-      yield* Console.log(`Fetching ${trunk}...`);
-      yield* git.fetch();
+      if (!dryRun) {
+        const clean = yield* git.isClean();
+        if (!clean) {
+          return yield* new StackError({
+            code: ErrorCode.DIRTY_WORKTREE,
+            message: "Working tree has uncommitted changes. Commit or stash before syncing.",
+          });
+        }
+      }
 
       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 { branches } = result.stack;
@@ -32,23 +74,92 @@ export const sync = Command.make("sync", { trunk: trunkFlag, from: fromFlag }).p
       if (fromBranch !== undefined) {
         const idx = branches.indexOf(fromBranch);
         if (idx === -1) {
-          yield* Console.error(`Branch "${fromBranch}" not found in stack`);
-          return;
+          return yield* new StackError({
+            code: ErrorCode.BRANCH_NOT_FOUND,
+            message: `Branch "${fromBranch}" not found in stack`,
+          });
         }
         startIdx = idx + 1;
+        if (startIdx >= branches.length) {
+          yield* warn(`Nothing to sync — ${fromBranch} is the last branch in the stack`);
+          return;
+        }
       }
 
-      for (let i = startIdx; i < branches.length; i++) {
-        const branch = branches[i];
-        if (branch === undefined) continue;
-        const base = i === 0 ? `origin/${trunk}` : (branches[i - 1] ?? `origin/${trunk}`);
-        yield* Console.log(`Rebasing ${branch} onto ${base}...`);
-        yield* git.checkout(branch);
-        yield* git.rebase(base);
+      const results: SyncResult[] = [];
+
+      if (dryRun) {
+        for (let i = startIdx; i < branches.length; i++) {
+          const branch = branches[i];
+          if (branch === undefined) continue;
+          const base = i === 0 ? `origin/${trunk}` : (branches[i - 1] ?? `origin/${trunk}`);
+          results.push({ name: branch, action: "skipped", base });
+          if (!json) {
+            yield* Console.error(`Would rebase and force-push ${branch} onto ${base}`);
+          }
+        }
+
+        if (json) {
+          // @effect-diagnostics-next-line effect/preferSchemaOverJson:off
+          yield* Console.log(JSON.stringify({ branches: results }, null, 2));
+        } else {
+          yield* Console.error(
+            `\n${results.length} branch${results.length === 1 ? "" : "es"} would be rebased`,
+          );
+        }
+        return;
       }
 
-      yield* git.checkout(currentBranch);
-      yield* Console.log("Stack synced");
+      yield* withSpinner(`Fetching ${trunk}`, git.fetch());
+
+      yield* Effect.gen(function* () {
+        for (let i = startIdx; i < branches.length; i++) {
+          const branch = branches[i];
+          if (branch === undefined) continue;
+          const newBase = i === 0 ? `origin/${trunk}` : (branches[i - 1] ?? `origin/${trunk}`);
+
+          // Compute old base (merge-base of this branch and its parent) before rebasing
+          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) => {
+              const hint =
+                i === 0 ? "stacked sync" : `stacked sync --from ${branches[i - 1] ?? trunk}`;
+              return Effect.fail(
+                new StackError({
+                  code: ErrorCode.REBASE_CONFLICT,
+                  message: `Rebase conflict on ${branch}: ${e.message}\n\nResolve conflicts, then run:\n  git rebase --continue\n  ${hint}`,
+                }),
+              );
+            }),
+          );
+          yield* withSpinner(`Pushing ${branch}`, git.push(branch, { force: true }));
+          results.push({ name: branch, action: "rebased", base: newBase });
+        }
+      }).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({ branches: results }, null, 2));
+      } else {
+        yield* success("Stack synced");
+      }
     }),
   ),
 );

package/src/commands/top.ts

@@ -1,29 +1,45 @@
-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 top = Command.make("top").pipe(
+const jsonFlag = Flag.boolean("json").pipe(Flag.withDescription("Output as JSON"));
+
+export const top = Command.make("top", { json: jsonFlag }).pipe(
   Command.withDescription("Checkout top branch of stack"),
-  Command.withHandler(() =>
+  Command.withExamples([{ command: "stacked top", description: "Jump to the top 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 topBranch = result.stack.branches[result.stack.branches.length - 1];
       if (topBranch === 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(topBranch);
-      yield* Console.log(`Switched to ${topBranch}`);
+
+      if (json) {
+        // @effect-diagnostics-next-line effect/preferSchemaOverJson:off
+        yield* Console.log(JSON.stringify({ branch: topBranch }, null, 2));
+      } else {
+        yield* success(`Switched to ${topBranch}`);
+      }
     }),
   ),
 );

package/src/commands/trunk.ts

@@ -1,20 +1,51 @@
-import { Argument, Command } from "effect/unstable/cli";
+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").pipe(Argument.optional);
+const nameArg = Argument.string("name").pipe(
+  Argument.withDescription("Trunk branch name to set"),
+  Argument.optional,
+);
+const jsonFlag = Flag.boolean("json").pipe(Flag.withDescription("Output as JSON"));
 
-export const trunk = Command.make("trunk", { name: nameArg }).pipe(
+export const trunk = Command.make("trunk", { name: nameArg, json: jsonFlag }).pipe(
   Command.withDescription("Get or set the trunk branch"),
-  Command.withHandler(({ name }) =>
+  Command.withExamples([
+    { command: "stacked trunk", description: "Print current trunk branch" },
+    { command: "stacked trunk develop", description: "Set trunk to develop" },
+    { command: "stacked trunk --json", description: "JSON output" },
+  ]),
+  Command.withHandler(({ name, json }) =>
     Effect.gen(function* () {
+      const git = yield* GitService;
       const stacks = yield* StackService;
       if (Option.isSome(name)) {
+        yield* validateBranchName(name.value);
+        const exists = yield* git.branchExists(name.value);
+        if (!exists) {
+          return yield* new StackError({
+            code: ErrorCode.BRANCH_NOT_FOUND,
+            message: `Branch "${name.value}" does not exist`,
+          });
+        }
         yield* stacks.setTrunk(name.value);
-        yield* Console.log(`Trunk set to ${name.value}`);
+        if (json) {
+          // @effect-diagnostics-next-line effect/preferSchemaOverJson:off
+          yield* Console.log(JSON.stringify({ trunk: name.value }, null, 2));
+        } else {
+          yield* Console.error(`Trunk set to ${name.value}`);
+        }
       } else {
         const current = yield* stacks.getTrunk();
-        yield* Console.log(current);
+        if (json) {
+          // @effect-diagnostics-next-line effect/preferSchemaOverJson:off
+          yield* Console.log(JSON.stringify({ trunk: current }, null, 2));
+        } else {
+          yield* Console.log(current);
+        }
       }
     }),
   ),