@cvr/stacked 0.3.0 → 0.4.1

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

@@ -2,12 +2,21 @@ 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";
+import { detectLimitConfig, limitUntrackedBranches } from "./helpers/detect.js";
 
-const dryRunFlag = Flag.boolean("dry-run");
+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 }).pipe(
+export const detect = Command.make("detect", { dryRun: dryRunFlag, json: jsonFlag }).pipe(
   Command.withDescription("Detect and register branch stacks from git history"),
-  Command.withHandler(({ dryRun }) =>
+  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;
@@ -18,62 +27,81 @@ export const detect = Command.make("detect", { dryRun: dryRunFlag }).pipe(
 
       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));
+      const untrackedAll = candidates.filter((b) => !alreadyTracked.has(b));
+      const detectLimit = yield* detectLimitConfig;
+      const { untracked, skipped } = limitUntrackedBranches(untrackedAll, detectLimit);
 
       if (untracked.length === 0) {
-        yield* Console.log("No untracked branches found");
+        yield* Console.error("No untracked branches found");
         return;
       }
 
+      if (skipped > 0) {
+        yield* warn(
+          `Analyzing ${untracked.length}/${untrackedAll.length} untracked branches (set STACKED_DETECT_MAX_BRANCHES to adjust)`,
+        );
+      }
+
       // 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>();
 
-      for (const branch of untracked) {
-        const ancestors: string[] = [];
-
-        // Check trunk
-        const trunkIsAncestor = yield* git
-          .isAncestor(trunk, branch)
-          .pipe(Effect.catch(() => Effect.succeed(false)));
-        if (trunkIsAncestor) ancestors.push(trunk);
-
-        // Check other untracked branches
-        for (const other of untracked) {
-          if (other === branch) continue;
-          const is = yield* git
-            .isAncestor(other, branch)
-            .pipe(Effect.catch(() => Effect.succeed(false)));
-          if (is) ancestors.push(other);
-        }
-
-        if (ancestors.length === 0) continue;
-
-        // 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.catch(() => Effect.succeed(false)));
-          if (candidateIsCloser) closest = candidate;
-        }
-
-        childOf.set(branch, closest);
-      }
+      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 childrenByParent = new Map<string, string[]>();
+      for (const branch of untracked) {
+        const parent = childOf.get(branch);
+        if (parent === undefined) continue;
+        const children = childrenByParent.get(parent) ?? [];
+        children.push(branch);
+        childrenByParent.set(parent, children);
+      }
+
       const chains: string[][] = [];
-      const roots = untracked.filter((b) => childOf.get(b) === trunk);
+      const roots = childrenByParent.get(trunk) ?? [];
 
       for (const root of roots) {
         const chain = [root];
         let current = root;
 
         while (true) {
-          const children = untracked.filter((b) => childOf.get(b) === current);
+          const children = childrenByParent.get(current) ?? [];
           const child = children[0];
           if (children.length === 1 && child !== undefined) {
             chain.push(child);
@@ -87,38 +115,51 @@ export const detect = Command.make("detect", { dryRun: dryRunFlag }).pipe(
         chains.push(chain);
       }
 
+      // Report forks
+      const forkPoints = untracked.filter((b) => (childrenByParent.get(b)?.length ?? 0) > 1);
+      const forks = forkPoints.map((b) => ({
+        branch: b,
+        children: childrenByParent.get(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* Console.log("No linear branch chains detected");
+        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.log(`Would create stack "${name}": ${chain.join(" → ")}`);
+          yield* Console.error(`Would create stack "${name}": ${chain.join(" → ")}`);
         } else {
           yield* stacks.createStack(name, chain);
-          yield* Console.log(`Created stack "${name}": ${chain.join(" → ")}`);
+          yield* success(`Created stack "${name}": ${chain.join(" → ")}`);
         }
       }
 
       if (dryRun) {
-        yield* Console.log(
+        yield* Console.error(
           `\n${chains.length} stack${chains.length === 1 ? "" : "s"} would be created`,
         );
       }
 
-      // Report forks
-      const forkPoints = untracked.filter((b) => {
-        const children = untracked.filter((c) => childOf.get(c) === b);
-        return children.length > 1;
-      });
-      if (forkPoints.length > 0) {
-        yield* Console.log("\nNote: forked branches detected (not supported yet):");
-        for (const branch of forkPoints) {
-          const children = untracked.filter((c) => childOf.get(c) === branch);
-          yield* Console.log(`  ${branch} → ${children.join(", ")}`);
+      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/detect.ts

@@ -0,0 +1,22 @@
+import { Config } from "effect";
+
+export const DEFAULT_MAX_DETECT_BRANCHES = 200;
+
+export interface LimitedBranches {
+  readonly untracked: readonly string[];
+  readonly skipped: number;
+}
+
+export const detectLimitConfig = Config.int("STACKED_DETECT_MAX_BRANCHES").pipe(
+  Config.withDefault(DEFAULT_MAX_DETECT_BRANCHES),
+  Config.orElse(() => Config.succeed(DEFAULT_MAX_DETECT_BRANCHES)),
+  Config.map((value) => (value > 0 ? value : DEFAULT_MAX_DETECT_BRANCHES)),
+);
+
+export const limitUntrackedBranches = (
+  untrackedAll: readonly string[],
+  limit: number,
+): LimitedBranches => {
+  const untracked = untrackedAll.slice(0, limit);
+  return { untracked, skipped: untrackedAll.length - untracked.length };
+};

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`,
+    });
+  }
+});