@cvr/stacked 0.2.0 → 0.4.0

package/src/commands/delete.ts

@@ -2,37 +2,50 @@ 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 { StackError } from "../errors/index.js";
+import { ErrorCode, StackError } from "../errors/index.js";
+import { confirm } from "../ui.js";
 
-const nameArg = Argument.string("name");
-const forceFlag = Flag.boolean("force").pipe(Flag.withAlias("f"));
+const nameArg = Argument.string("name").pipe(Argument.withDescription("Branch name to delete"));
+const forceFlag = Flag.boolean("force").pipe(
+  Flag.withAlias("f"),
+  Flag.withDescription("Delete even if branch has children in the stack"),
+);
+const keepRemoteFlag = Flag.boolean("keep-remote").pipe(
+  Flag.withDescription("Don't delete the remote branch"),
+);
+const jsonFlag = Flag.boolean("json").pipe(Flag.withDescription("Output as JSON"));
+const dryRunFlag = Flag.boolean("dry-run").pipe(
+  Flag.withDescription("Show what would happen without making changes"),
+);
 
-export const deleteCmd = Command.make("delete", { name: nameArg, force: forceFlag }).pipe(
+export const deleteCmd = Command.make("delete", {
+  name: nameArg,
+  force: forceFlag,
+  keepRemote: keepRemoteFlag,
+  json: jsonFlag,
+  dryRun: dryRunFlag,
+}).pipe(
   Command.withDescription("Remove branch from stack and delete git branch"),
-  Command.withHandler(({ name, force }) =>
+  Command.withExamples([
+    { command: "stacked delete feat-old", description: "Delete a leaf branch" },
+    { command: "stacked delete feat-mid --force", description: "Force delete a mid-stack branch" },
+  ]),
+  Command.withHandler(({ name, force, keepRemote, json, dryRun }) =>
     Effect.gen(function* () {
       const git = yield* GitService;
       const stacks = yield* StackService;
 
       const currentBranch = yield* git.currentBranch();
-      const data = yield* stacks.load();
-
-      let stackName: string | null = null;
-      for (const [sName, stack] of Object.entries(data.stacks)) {
-        if (stack.branches.includes(name)) {
-          stackName = sName;
-          break;
-        }
-      }
+      const trunk = yield* stacks.getTrunk();
 
-      if (stackName === null) {
-        return yield* new StackError({ message: `Branch "${name}" not found in any stack` });
-      }
-
-      const stack = data.stacks[stackName];
-      if (stack === undefined) {
-        return yield* new StackError({ message: `Stack "${stackName}" not found` });
+      const result = yield* stacks.findBranchStack(name);
+      if (result === null) {
+        return yield* new StackError({
+          code: ErrorCode.BRANCH_NOT_FOUND,
+          message: `Branch "${name}" not found in any stack`,
+        });
       }
+      const { name: stackName, stack } = result;
       const idx = stack.branches.indexOf(name);
 
       if (idx < stack.branches.length - 1 && !force) {
@@ -41,15 +54,70 @@ export const deleteCmd = Command.make("delete", { name: nameArg, force: forceFla
         });
       }
 
+      const hadChildren = idx < stack.branches.length - 1;
+      const willDeleteRemote = !keepRemote;
+
+      if (dryRun) {
+        if (json) {
+          // @effect-diagnostics-next-line effect/preferSchemaOverJson:off
+          yield* Console.log(
+            JSON.stringify(
+              { branch: name, stack: stackName, hadChildren, deleteRemote: willDeleteRemote },
+              null,
+              2,
+            ),
+          );
+        } else {
+          yield* Console.error(`Would delete branch "${name}" from stack "${stackName}"`);
+          if (hadChildren) {
+            yield* Console.error("Warning: branch has children that would be orphaned");
+          }
+          if (willDeleteRemote) {
+            yield* Console.error("Would also delete remote branch");
+          }
+        }
+        return;
+      }
+
+      const confirmed = yield* confirm(
+        `Delete branch "${name}"${keepRemote ? "" : " (local + remote)"}?`,
+      );
+      if (!confirmed) {
+        yield* Console.error("Aborted");
+        return;
+      }
+
       if (currentBranch === name) {
-        const parent = idx === 0 ? data.trunk : (stack.branches[idx - 1] ?? data.trunk);
+        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 deleting the current branch.",
+          });
+        }
+        const parent = idx === 0 ? trunk : (stack.branches[idx - 1] ?? trunk);
         yield* git.checkout(parent);
       }
 
-      yield* stacks.removeBranch(stackName, name);
       yield* git.deleteBranch(name, force);
+      yield* stacks.removeBranch(stackName, name);
+
+      if (willDeleteRemote) {
+        yield* git.deleteRemoteBranch(name).pipe(Effect.catchTag("GitError", () => Effect.void));
+      }
 
-      yield* Console.log(`Deleted ${name}`);
+      if (json) {
+        // @effect-diagnostics-next-line effect/preferSchemaOverJson:off
+        yield* Console.log(JSON.stringify({ deleted: name, hadChildren }, null, 2));
+      } else {
+        yield* Console.error(`Deleted ${name}`);
+        if (hadChildren) {
+          yield* Console.error(
+            "Warning: branch had children — commits unique to this branch may be lost if children don't include them. Run 'stacked sync' to rebase them onto the new parent.",
+          );
+        }
+      }
     }),
   ),
 );

package/src/commands/detect.ts

@@ -0,0 +1,152 @@
+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 { success, warn, info } from "../ui.js";
+
+const dryRunFlag = Flag.boolean("dry-run").pipe(
+  Flag.withDescription("Show what would be detected without making changes"),
+);
+const jsonFlag = Flag.boolean("json").pipe(Flag.withDescription("Output as JSON"));
+
+export const detect = Command.make("detect", { dryRun: dryRunFlag, json: jsonFlag }).pipe(
+  Command.withDescription("Detect and register branch stacks from git history"),
+  Command.withExamples([
+    { command: "stacked detect", description: "Auto-discover and register stacks" },
+    { command: "stacked detect --dry-run", description: "Preview what would be detected" },
+  ]),
+  Command.withHandler(({ dryRun, json }) =>
+    Effect.gen(function* () {
+      const git = yield* GitService;
+      const stacks = yield* StackService;
+
+      const trunk = yield* stacks.getTrunk();
+      const allBranches = yield* git.listBranches();
+      const candidates = allBranches.filter((b) => b !== trunk);
+
+      const data = yield* stacks.load();
+      const alreadyTracked = new Set(Object.values(data.stacks).flatMap((s) => [...s.branches]));
+      const untracked = candidates.filter((b) => !alreadyTracked.has(b));
+
+      if (untracked.length === 0) {
+        yield* Console.error("No untracked branches found");
+        return;
+      }
+
+      // Build parent map: for each branch, find its direct parent among other branches
+      // A parent is the closest ancestor — i.e., an ancestor that is not an ancestor of another ancestor
+      const childOf = new Map<string, string>();
+
+      yield* Effect.forEach(
+        untracked,
+        (branch) =>
+          Effect.gen(function* () {
+            // Check all potential ancestors (trunk + other untracked) in parallel
+            const potentialAncestors = [trunk, ...untracked.filter((b) => b !== branch)];
+            const ancestryResults = yield* Effect.forEach(
+              potentialAncestors,
+              (other) =>
+                git.isAncestor(other, branch).pipe(
+                  Effect.catchTag("GitError", () => Effect.succeed(false)),
+                  Effect.map((is) => [other, is] as const),
+                ),
+              { concurrency: 5 },
+            );
+
+            const ancestors = ancestryResults.filter(([_, is]) => is).map(([name]) => name);
+
+            if (ancestors.length === 0) return;
+
+            // Find the closest ancestor — the one that is a descendant of all others
+            let closest = ancestors[0] ?? trunk;
+            for (let i = 1; i < ancestors.length; i++) {
+              const candidate = ancestors[i];
+              if (candidate === undefined) continue;
+              const candidateIsCloser = yield* git
+                .isAncestor(closest, candidate)
+                .pipe(Effect.catchTag("GitError", () => Effect.succeed(false)));
+              if (candidateIsCloser) closest = candidate;
+            }
+
+            childOf.set(branch, closest);
+          }),
+        { concurrency: 5 },
+      );
+
+      // Build linear chains from trunk
+      // Find branches whose parent is trunk (chain roots)
+      const chains: string[][] = [];
+      const roots = untracked.filter((b) => childOf.get(b) === trunk);
+
+      for (const root of roots) {
+        const chain = [root];
+        let current = root;
+
+        while (true) {
+          const children = untracked.filter((b) => childOf.get(b) === current);
+          const child = children[0];
+          if (children.length === 1 && child !== undefined) {
+            chain.push(child);
+            current = child;
+          } else {
+            // 0 children = end of chain, 2+ children = fork (skip)
+            break;
+          }
+        }
+
+        chains.push(chain);
+      }
+
+      // Report forks
+      const forkPoints = untracked.filter((b) => {
+        const children = untracked.filter((c) => childOf.get(c) === b);
+        return children.length > 1;
+      });
+      const forks = forkPoints.map((b) => ({
+        branch: b,
+        children: untracked.filter((c) => childOf.get(c) === b),
+      }));
+
+      if (json) {
+        const stacksData = chains.map((chain) => ({ name: chain[0] ?? "", branches: chain }));
+        // @effect-diagnostics-next-line effect/preferSchemaOverJson:off
+        yield* Console.log(JSON.stringify({ stacks: stacksData, forks }, null, 2));
+        return;
+      }
+
+      if (chains.length === 0) {
+        yield* info("No linear branch chains detected");
+        return;
+      }
+
+      for (const chain of chains) {
+        const name = chain[0];
+        if (name === undefined) continue;
+        const currentData = yield* stacks.load();
+        if (currentData.stacks[name] !== undefined) {
+          yield* warn(`Stack "${name}" already exists, skipping: ${chain.join(" → ")}`);
+          continue;
+        }
+        if (dryRun) {
+          yield* Console.error(`Would create stack "${name}": ${chain.join(" → ")}`);
+        } else {
+          yield* stacks.createStack(name, chain);
+          yield* success(`Created stack "${name}": ${chain.join(" → ")}`);
+        }
+      }
+
+      if (dryRun) {
+        yield* Console.error(
+          `\n${chains.length} stack${chains.length === 1 ? "" : "s"} would be created`,
+        );
+      }
+
+      if (forks.length > 0) {
+        yield* warn("Forked branches detected (not supported yet):");
+        for (const fork of forks) {
+          yield* Console.error(`  ${fork.branch} → ${fork.children.join(", ")}`);
+        }
+      }
+    }),
+  ),
+);

package/src/commands/doctor.ts

@@ -0,0 +1,124 @@
+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 { success, warn } from "../ui.js";
+
+const fixFlag = Flag.boolean("fix").pipe(Flag.withDescription("Auto-fix issues where possible"));
+const jsonFlag = Flag.boolean("json").pipe(Flag.withDescription("Output as JSON"));
+
+interface Finding {
+  type: "stale_branch" | "missing_trunk" | "duplicate_branch" | "parse_error";
+  message: string;
+  fixed: boolean;
+}
+
+export const doctor = Command.make("doctor", { fix: fixFlag, json: jsonFlag }).pipe(
+  Command.withDescription("Check stack metadata for issues and optionally fix them"),
+  Command.withExamples([
+    { command: "stacked doctor", description: "Check for metadata drift" },
+    { command: "stacked doctor --fix", description: "Auto-fix detected issues" },
+  ]),
+  Command.withHandler(({ fix, json }) =>
+    Effect.gen(function* () {
+      const git = yield* GitService;
+      const stacks = yield* StackService;
+
+      const data = yield* stacks.load();
+      const findings: Finding[] = [];
+
+      // Check 1: trunk branch exists
+      const trunkExists = yield* git
+        .branchExists(data.trunk)
+        .pipe(Effect.catchTag("GitError", () => Effect.succeed(false)));
+      if (!trunkExists) {
+        if (fix) {
+          // Auto-detect a trunk
+          for (const candidate of ["main", "master", "develop"]) {
+            const exists = yield* git
+              .branchExists(candidate)
+              .pipe(Effect.catchTag("GitError", () => Effect.succeed(false)));
+            if (exists) {
+              yield* stacks.setTrunk(candidate);
+              findings.push({
+                type: "missing_trunk",
+                message: `Trunk "${data.trunk}" not found, set to "${candidate}"`,
+                fixed: true,
+              });
+              break;
+            }
+          }
+        } else {
+          findings.push({
+            type: "missing_trunk",
+            message: `Trunk branch "${data.trunk}" does not exist`,
+            fixed: false,
+          });
+        }
+      }
+
+      // Check 2: all tracked branches exist in git
+      for (const [stackName, stack] of Object.entries(data.stacks)) {
+        for (const branch of stack.branches) {
+          const exists = yield* git
+            .branchExists(branch)
+            .pipe(Effect.catchTag("GitError", () => Effect.succeed(false)));
+          if (!exists) {
+            if (fix) {
+              yield* stacks.removeBranch(stackName, branch);
+              findings.push({
+                type: "stale_branch",
+                message: `Removed stale branch "${branch}" from stack "${stackName}"`,
+                fixed: true,
+              });
+            } else {
+              findings.push({
+                type: "stale_branch",
+                message: `Branch "${branch}" in stack "${stackName}" does not exist in git`,
+                fixed: false,
+              });
+            }
+          }
+        }
+      }
+
+      // Check 3: no branches in multiple stacks
+      const branchToStacks = new Map<string, string[]>();
+      for (const [stackName, stack] of Object.entries(data.stacks)) {
+        for (const branch of stack.branches) {
+          const existing = branchToStacks.get(branch) ?? [];
+          existing.push(stackName);
+          branchToStacks.set(branch, existing);
+        }
+      }
+      for (const [branch, stackNames] of branchToStacks) {
+        if (stackNames.length > 1) {
+          findings.push({
+            type: "duplicate_branch",
+            message: `Branch "${branch}" appears in multiple stacks: ${stackNames.join(", ")}`,
+            fixed: false,
+          });
+        }
+      }
+
+      if (json) {
+        // @effect-diagnostics-next-line effect/preferSchemaOverJson:off
+        yield* Console.log(JSON.stringify({ findings }, null, 2));
+      } else if (findings.length === 0) {
+        yield* success("No issues found");
+      } else {
+        for (const f of findings) {
+          if (f.fixed) {
+            yield* success(f.message);
+          } else {
+            yield* warn(f.message);
+          }
+        }
+        const fixable = findings.filter((f) => !f.fixed).length;
+        if (fixable > 0 && !fix) {
+          yield* Console.error(`\nRun 'stacked doctor --fix' to auto-fix ${fixable} issue(s)`);
+        }
+      }
+    }),
+  ),
+);

package/src/commands/down.ts

@@ -0,0 +1,62 @@
+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";
+
+const jsonFlag = Flag.boolean("json").pipe(Flag.withDescription("Output as JSON"));
+
+export const down = Command.make("down", { json: jsonFlag }).pipe(
+  Command.withDescription("Move down one branch in the stack"),
+  Command.withExamples([{ command: "stacked down", description: "Move to the next branch below" }]),
+  Command.withHandler(({ json }) =>
+    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.",
+        });
+      }
+
+      const { branches } = result.stack;
+      const idx = branches.indexOf(currentBranch);
+      if (idx === -1) {
+        return yield* new StackError({
+          code: ErrorCode.NOT_IN_STACK,
+          message: "Current branch not found in stack",
+        });
+      }
+
+      if (idx === 0) {
+        return yield* new StackError({
+          code: ErrorCode.ALREADY_AT_BOTTOM,
+          message: "Already at the bottom of the stack",
+        });
+      }
+
+      const prev = branches[idx - 1];
+      if (prev === undefined) {
+        return yield* new StackError({
+          code: ErrorCode.ALREADY_AT_BOTTOM,
+          message: "Already at the bottom of the stack",
+        });
+      }
+
+      yield* git.checkout(prev);
+
+      if (json) {
+        // @effect-diagnostics-next-line effect/preferSchemaOverJson:off
+        yield* Console.log(JSON.stringify({ branch: prev, from: currentBranch }, null, 2));
+      } else {
+        yield* success(`Switched to ${prev}`);
+      }
+    }),
+  ),
+);

package/src/commands/helpers/validate.ts

@@ -0,0 +1,61 @@
+import { Effect } from "effect";
+import { ErrorCode, StackError } from "../../errors/index.js";
+
+const BRANCH_NAME_PATTERN = /^[a-zA-Z0-9][a-zA-Z0-9._\-/]*$/;
+
+export const validateBranchName = Effect.fn("validateBranchName")(function* (name: string) {
+  if (name === "") {
+    return yield* new StackError({
+      code: ErrorCode.INVALID_BRANCH_NAME,
+      message: "Branch name cannot be empty",
+    });
+  }
+  if (name.startsWith("-")) {
+    return yield* new StackError({
+      code: ErrorCode.INVALID_BRANCH_NAME,
+      message: `Invalid branch name "${name}": cannot start with "-"`,
+    });
+  }
+  if (name.includes("..")) {
+    return yield* new StackError({
+      code: ErrorCode.INVALID_BRANCH_NAME,
+      message: `Invalid branch name "${name}": cannot contain ".."`,
+    });
+  }
+  if (name.includes(" ")) {
+    return yield* new StackError({
+      code: ErrorCode.INVALID_BRANCH_NAME,
+      message: `Invalid branch name "${name}": cannot contain spaces`,
+    });
+  }
+  if (name.endsWith(".lock")) {
+    return yield* new StackError({
+      code: ErrorCode.INVALID_BRANCH_NAME,
+      message: `Invalid branch name "${name}": cannot end with ".lock"`,
+    });
+  }
+  if (name.endsWith(".")) {
+    return yield* new StackError({
+      code: ErrorCode.INVALID_BRANCH_NAME,
+      message: `Invalid branch name "${name}": cannot end with "."`,
+    });
+  }
+  if (name.endsWith("/")) {
+    return yield* new StackError({
+      code: ErrorCode.INVALID_BRANCH_NAME,
+      message: `Invalid branch name "${name}": cannot end with "/"`,
+    });
+  }
+  if (name === "@") {
+    return yield* new StackError({
+      code: ErrorCode.INVALID_BRANCH_NAME,
+      message: `Invalid branch name "${name}": "@" alone is not a valid branch name`,
+    });
+  }
+  if (!BRANCH_NAME_PATTERN.test(name)) {
+    return yield* new StackError({
+      code: ErrorCode.INVALID_BRANCH_NAME,
+      message: `Invalid branch name "${name}": must start with alphanumeric and contain only alphanumerics, dots, hyphens, underscores, or slashes`,
+    });
+  }
+});

package/src/commands/index.ts

@@ -6,15 +6,33 @@ import { stacks } from "./stacks.js";
 import { checkout } from "./checkout.js";
 import { top } from "./top.js";
 import { bottom } from "./bottom.js";
+import { up } from "./up.js";
+import { down } from "./down.js";
 import { sync } from "./sync.js";
 import { deleteCmd } from "./delete.js";
 import { submit } from "./submit.js";
 import { adopt } from "./adopt.js";
 import { log } from "./log.js";
 import { clean } from "./clean.js";
+import { detect } from "./detect.js";
+import { init } from "./init.js";
+import { status } from "./status.js";
+import { doctor } from "./doctor.js";
+import { rename } from "./rename.js";
+import { reorder } from "./reorder.js";
+import { split } from "./split.js";
+import { amend } from "./amend.js";
 
 const root = Command.make("stacked").pipe(
-  Command.withDescription("Branch-based stacked PR manager"),
+  Command.withDescription(
+    "Branch-based stacked PR manager\n\nGlobal flags:\n  --verbose       Show detailed output\n  --quiet, -q     Suppress non-essential output\n  --no-color      Disable color output\n  --yes, -y       Skip confirmation prompts",
+  ),
+  Command.withExamples([
+    { command: "stacked create feat-auth", description: "Create a new branch in the stack" },
+    { command: "stacked list", description: "Show branches in the current stack" },
+    { command: "stacked sync", description: "Rebase all branches in order" },
+    { command: "stacked submit", description: "Push and create/update PRs" },
+  ]),
 );
 
 export const command = root.pipe(
@@ -26,11 +44,21 @@ export const command = root.pipe(
     checkout,
     top,
     bottom,
+    up,
+    down,
     sync,
     deleteCmd,
     submit,
     adopt,
     log,
     clean,
+    detect,
+    init,
+    status,
+    doctor,
+    rename,
+    reorder,
+    split,
+    amend,
   ]),
 );

package/src/commands/init.ts

@@ -0,0 +1,40 @@
+import { Command } from "effect/unstable/cli";
+import { Console, Effect } from "effect";
+import { StackError } from "../errors/index.js";
+import { mkdirSync, writeFileSync } from "fs";
+import { join } from "path";
+import { homedir } from "os";
+
+const skillContent = typeof __SKILL_CONTENT__ !== "undefined" ? __SKILL_CONTENT__ : null;
+
+export const init = Command.make("init").pipe(
+  Command.withDescription("Install the stacked Claude skill to ~/.claude/skills"),
+  Command.withExamples([{ command: "stacked init", description: "Install the Claude skill" }]),
+  Command.withHandler(() =>
+    Effect.gen(function* () {
+      if (skillContent === null) {
+        return yield* new StackError({
+          message: "Skill content not available. This command only works with the compiled binary.",
+        });
+      }
+
+      const skillsDir = process.env["STACKED_SKILLS_DIR"] ?? join(homedir(), ".claude", "skills");
+      const targetDir = join(skillsDir, "stacked");
+      const targetPath = join(targetDir, "SKILL.md");
+
+      yield* Console.error(`Writing skill to ${targetPath}...`);
+      yield* Effect.try({
+        try: () => {
+          mkdirSync(targetDir, { recursive: true });
+          writeFileSync(targetPath, skillContent);
+        },
+        catch: (e) => new StackError({ message: `Failed to write skill: ${e}` }),
+      });
+
+      yield* Console.error(`Installed stacked skill to ${targetPath}`);
+      yield* Console.error("\nNext steps:");
+      yield* Console.error("  stacked trunk          # verify/set your trunk branch");
+      yield* Console.error("  stacked create <name>  # start your first stack");
+    }),
+  ),
+);