dubstack 0.1.3

package/dist/lib/git.js

@@ -0,0 +1,184 @@
+import { execa } from "execa";
+import { DubError } from "./errors.js";
+/**
+ * Checks whether the given directory is inside a git repository.
+ * @returns `true` if inside a git worktree, `false` otherwise. Never throws.
+ */
+export async function isGitRepo(cwd) {
+    try {
+        const { stdout } = await execa("git", ["rev-parse", "--is-inside-work-tree"], { cwd });
+        return stdout.trim() === "true";
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Returns the absolute path to the repository root.
+ * @throws {DubError} If not inside a git repository.
+ */
+export async function getRepoRoot(cwd) {
+    try {
+        const { stdout } = await execa("git", ["rev-parse", "--show-toplevel"], {
+            cwd,
+        });
+        return stdout.trim();
+    }
+    catch {
+        throw new DubError("Not a git repository. Run this command inside a git repo.");
+    }
+}
+/**
+ * Returns the name of the currently checked-out branch.
+ * @throws {DubError} If HEAD is detached or the repo has no commits.
+ */
+export async function getCurrentBranch(cwd) {
+    try {
+        const { stdout } = await execa("git", ["rev-parse", "--abbrev-ref", "HEAD"], { cwd });
+        const branch = stdout.trim();
+        if (branch === "HEAD") {
+            throw new DubError("HEAD is detached. Checkout a branch before running this command.");
+        }
+        return branch;
+    }
+    catch (error) {
+        if (error instanceof DubError)
+            throw error;
+        throw new DubError("Repository has no commits. Make at least one commit first.");
+    }
+}
+/**
+ * Checks whether a branch with the given name exists locally.
+ * @returns `true` if the branch exists, `false` otherwise. Never throws.
+ */
+export async function branchExists(name, cwd) {
+    try {
+        await execa("git", ["rev-parse", "--verify", `refs/heads/${name}`], {
+            cwd,
+        });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Creates a new branch and switches to it.
+ * @throws {DubError} If a branch with that name already exists.
+ */
+export async function createBranch(name, cwd) {
+    if (await branchExists(name, cwd)) {
+        throw new DubError(`Branch '${name}' already exists.`);
+    }
+    await execa("git", ["checkout", "-b", name], { cwd });
+}
+/**
+ * Switches to an existing branch.
+ * @throws {DubError} If the branch does not exist.
+ */
+export async function checkoutBranch(name, cwd) {
+    try {
+        await execa("git", ["checkout", name], { cwd });
+    }
+    catch {
+        throw new DubError(`Branch '${name}' not found.`);
+    }
+}
+/**
+ * Deletes a local branch forcefully. Used by undo to remove created branches.
+ * @throws {DubError} If the branch does not exist.
+ */
+export async function deleteBranch(name, cwd) {
+    try {
+        await execa("git", ["branch", "-D", name], { cwd });
+    }
+    catch {
+        throw new DubError(`Failed to delete branch '${name}'. It may not exist.`);
+    }
+}
+/**
+ * Force-moves a branch pointer to a specific commit SHA.
+ * Used by undo to reset branches to their pre-operation tips.
+ */
+export async function forceBranchTo(name, sha, cwd) {
+    try {
+        const current = await getCurrentBranch(cwd).catch(() => null);
+        if (current === name) {
+            await execa("git", ["reset", "--hard", sha], { cwd });
+        }
+        else {
+            await execa("git", ["branch", "-f", name, sha], { cwd });
+        }
+    }
+    catch (error) {
+        if (error instanceof DubError)
+            throw error;
+        throw new DubError(`Failed to reset branch '${name}' to ${sha}.`);
+    }
+}
+/**
+ * Checks whether the working tree is clean (no uncommitted changes).
+ * @returns `true` if clean (no output from `git status --porcelain`).
+ */
+export async function isWorkingTreeClean(cwd) {
+    const { stdout } = await execa("git", ["status", "--porcelain"], { cwd });
+    return stdout.trim() === "";
+}
+/**
+ * Performs `git rebase --onto` to move a branch from one base to another.
+ *
+ * @param newBase - The commit/branch to rebase onto
+ * @param oldBase - The old base commit to replay from
+ * @param branch - The branch being rebased
+ * @throws {DubError} If a merge conflict occurs during rebase
+ */
+export async function rebaseOnto(newBase, oldBase, branch, cwd) {
+    try {
+        await execa("git", ["rebase", "--onto", newBase, oldBase, branch], { cwd });
+    }
+    catch {
+        throw new DubError(`Conflict while restacking '${branch}'.\n` +
+            "  Resolve conflicts, stage changes, then run: dub restack --continue");
+    }
+}
+/**
+ * Continues an in-progress rebase after conflicts have been resolved.
+ * @throws {DubError} If the rebase continue fails.
+ */
+export async function rebaseContinue(cwd) {
+    try {
+        await execa("git", ["rebase", "--continue"], {
+            cwd,
+            env: { GIT_EDITOR: "true" },
+        });
+    }
+    catch {
+        throw new DubError("Failed to continue rebase. Ensure all conflicts are resolved and staged.");
+    }
+}
+/**
+ * Returns the merge-base (common ancestor) commit SHA of two branches.
+ */
+export async function getMergeBase(a, b, cwd) {
+    try {
+        const { stdout } = await execa("git", ["merge-base", a, b], { cwd });
+        return stdout.trim();
+    }
+    catch {
+        throw new DubError(`Could not find common ancestor between '${a}' and '${b}'.`);
+    }
+}
+/**
+ * Returns the commit SHA at the tip of a branch.
+ * @throws {DubError} If the branch does not exist.
+ */
+export async function getBranchTip(name, cwd) {
+    try {
+        const { stdout } = await execa("git", ["rev-parse", name], { cwd });
+        return stdout.trim();
+    }
+    catch {
+        throw new DubError(`Branch '${name}' not found.`);
+    }
+}
+//# sourceMappingURL=git.js.map

package/dist/lib/git.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"git.js","sourceRoot":"","sources":["../../src/lib/git.ts"],"names":[],"mappings":"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"}

package/dist/lib/state.d.ts

@@ -0,0 +1,70 @@
+/** A branch within a stack. */
+export interface Branch {
+    /** Branch name, e.g. "feat/api-endpoint" */
+    name: string;
+    /** Set to "root" for the base branch (e.g. main). Omitted for children. */
+    type?: "root";
+    /** Name of the parent branch. `null` only for root branches. */
+    parent: string | null;
+    /** GitHub PR URL. Populated in Phase 2. */
+    pr_link: string | null;
+}
+/** A stack of dependent branches. */
+export interface Stack {
+    /** Unique identifier for this stack. */
+    id: string;
+    /** Ordered list of branches in the stack. */
+    branches: Branch[];
+}
+/** Root state persisted to `.git/dubstack/state.json`. */
+export interface DubState {
+    /** All tracked stacks in this repository. */
+    stacks: Stack[];
+}
+/**
+ * Returns the absolute path to the dubstack state file.
+ * @throws {DubError} If not inside a git repository.
+ */
+export declare function getStatePath(cwd: string): Promise<string>;
+/**
+ * Returns the absolute path to the dubstack directory inside `.git`.
+ * @throws {DubError} If not inside a git repository.
+ */
+export declare function getDubDir(cwd: string): Promise<string>;
+/**
+ * Reads and parses the dubstack state file.
+ * @throws {DubError} If the state file is missing or contains invalid JSON.
+ */
+export declare function readState(cwd: string): Promise<DubState>;
+/**
+ * Writes the dubstack state to disk.
+ * Creates the parent directory if it doesn't exist.
+ */
+export declare function writeState(state: DubState, cwd: string): Promise<void>;
+/**
+ * Initializes the dubstack state directory and file.
+ * Idempotent — returns `"already_exists"` if already initialized.
+ *
+ * @returns `"created"` if freshly initialized, `"already_exists"` if state file already present.
+ */
+export declare function initState(cwd: string): Promise<"created" | "already_exists">;
+/**
+ * Finds the stack containing a given branch.
+ * @returns The matching stack, or `undefined` if the branch isn't tracked.
+ */
+export declare function findStackForBranch(state: DubState, name: string): Stack | undefined;
+/**
+ * Adds a child branch to the state, linking it to its parent.
+ *
+ * Decision tree:
+ * 1. If `child` already exists in any stack → throws `DubError` (no duplicates)
+ * 2. If `parent` is found in an existing stack → appends child to that stack
+ * 3. If `parent` is not in any stack → creates a new stack with parent as root
+ *
+ * @param state - The state to mutate (modified in place)
+ * @param child - Name of the new branch
+ * @param parent - Name of the parent branch
+ * @throws {DubError} If child branch already exists in state
+ */
+export declare function addBranchToStack(state: DubState, child: string, parent: string): void;
+//# sourceMappingURL=state.d.ts.map

package/dist/lib/state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"state.d.ts","sourceRoot":"","sources":["../../src/lib/state.ts"],"names":[],"mappings":"AAMA,+BAA+B;AAC/B,MAAM,WAAW,MAAM;IACtB,4CAA4C;IAC5C,IAAI,EAAE,MAAM,CAAC;IACb,2EAA2E;IAC3E,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,gEAAgE;IAChE,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,2CAA2C;IAC3C,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;CACvB;AAED,qCAAqC;AACrC,MAAM,WAAW,KAAK;IACrB,wCAAwC;IACxC,EAAE,EAAE,MAAM,CAAC;IACX,6CAA6C;IAC7C,QAAQ,EAAE,MAAM,EAAE,CAAC;CACnB;AAED,0DAA0D;AAC1D,MAAM,WAAW,QAAQ;IACxB,6CAA6C;IAC7C,MAAM,EAAE,KAAK,EAAE,CAAC;CAChB;AAED;;;GAGG;AACH,wBAAsB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAG/D;AAED;;;GAGG;AACH,wBAAsB,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAG5D;AAED;;;GAGG;AACH,wBAAsB,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,CAAC,CAa9D;AAED;;;GAGG;AACH,wBAAsB,UAAU,CAAC,KAAK,EAAE,QAAQ,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAO5E;AAED;;;;;GAKG;AACH,wBAAsB,SAAS,CAC9B,GAAG,EAAE,MAAM,GACT,OAAO,CAAC,SAAS,GAAG,gBAAgB,CAAC,CAYvC;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CACjC,KAAK,EAAE,QAAQ,EACf,IAAI,EAAE,MAAM,GACV,KAAK,GAAG,SAAS,CAInB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,gBAAgB,CAC/B,KAAK,EAAE,QAAQ,EACf,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,GACZ,IAAI,CAsBN"}

package/dist/lib/state.js

@@ -0,0 +1,110 @@
+import * as crypto from "node:crypto";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { DubError } from "./errors.js";
+import { getRepoRoot } from "./git.js";
+/**
+ * Returns the absolute path to the dubstack state file.
+ * @throws {DubError} If not inside a git repository.
+ */
+export async function getStatePath(cwd) {
+    const root = await getRepoRoot(cwd);
+    return path.join(root, ".git", "dubstack", "state.json");
+}
+/**
+ * Returns the absolute path to the dubstack directory inside `.git`.
+ * @throws {DubError} If not inside a git repository.
+ */
+export async function getDubDir(cwd) {
+    const root = await getRepoRoot(cwd);
+    return path.join(root, ".git", "dubstack");
+}
+/**
+ * Reads and parses the dubstack state file.
+ * @throws {DubError} If the state file is missing or contains invalid JSON.
+ */
+export async function readState(cwd) {
+    const statePath = await getStatePath(cwd);
+    if (!fs.existsSync(statePath)) {
+        throw new DubError("DubStack is not initialized. Run 'dub init' first.");
+    }
+    try {
+        const raw = fs.readFileSync(statePath, "utf-8");
+        return JSON.parse(raw);
+    }
+    catch {
+        throw new DubError("State file is corrupted. Delete .git/dubstack and run 'dub init' to re-initialize.");
+    }
+}
+/**
+ * Writes the dubstack state to disk.
+ * Creates the parent directory if it doesn't exist.
+ */
+export async function writeState(state, cwd) {
+    const statePath = await getStatePath(cwd);
+    const dir = path.dirname(statePath);
+    if (!fs.existsSync(dir)) {
+        fs.mkdirSync(dir, { recursive: true });
+    }
+    fs.writeFileSync(statePath, `${JSON.stringify(state, null, 2)}\n`);
+}
+/**
+ * Initializes the dubstack state directory and file.
+ * Idempotent — returns `"already_exists"` if already initialized.
+ *
+ * @returns `"created"` if freshly initialized, `"already_exists"` if state file already present.
+ */
+export async function initState(cwd) {
+    const statePath = await getStatePath(cwd);
+    const dir = path.dirname(statePath);
+    if (fs.existsSync(statePath)) {
+        return "already_exists";
+    }
+    fs.mkdirSync(dir, { recursive: true });
+    const emptyState = { stacks: [] };
+    fs.writeFileSync(statePath, `${JSON.stringify(emptyState, null, 2)}\n`);
+    return "created";
+}
+/**
+ * Finds the stack containing a given branch.
+ * @returns The matching stack, or `undefined` if the branch isn't tracked.
+ */
+export function findStackForBranch(state, name) {
+    return state.stacks.find((stack) => stack.branches.some((b) => b.name === name));
+}
+/**
+ * Adds a child branch to the state, linking it to its parent.
+ *
+ * Decision tree:
+ * 1. If `child` already exists in any stack → throws `DubError` (no duplicates)
+ * 2. If `parent` is found in an existing stack → appends child to that stack
+ * 3. If `parent` is not in any stack → creates a new stack with parent as root
+ *
+ * @param state - The state to mutate (modified in place)
+ * @param child - Name of the new branch
+ * @param parent - Name of the parent branch
+ * @throws {DubError} If child branch already exists in state
+ */
+export function addBranchToStack(state, child, parent) {
+    if (findStackForBranch(state, child)) {
+        throw new DubError(`Branch '${child}' is already tracked in a stack.`);
+    }
+    const childBranch = { name: child, parent, pr_link: null };
+    const existingStack = findStackForBranch(state, parent);
+    if (existingStack) {
+        existingStack.branches.push(childBranch);
+    }
+    else {
+        const rootBranch = {
+            name: parent,
+            type: "root",
+            parent: null,
+            pr_link: null,
+        };
+        state.stacks.push({
+            id: crypto.randomUUID(),
+            branches: [rootBranch, childBranch],
+        });
+    }
+}
+//# sourceMappingURL=state.js.map

package/dist/lib/state.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"state.js","sourceRoot":"","sources":["../../src/lib/state.ts"],"names":[],"mappings":"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"}

package/dist/lib/undo-log.d.ts

@@ -0,0 +1,33 @@
+import type { DubState } from "./state.js";
+/**
+ * Snapshot of system state before a mutation, used by `dub undo`.
+ * Only one undo level is supported — each new mutation overwrites the previous snapshot.
+ */
+export interface UndoEntry {
+    /** Which command created this snapshot. */
+    operation: "create" | "restack";
+    /** ISO timestamp of when the snapshot was taken. */
+    timestamp: string;
+    /** The branch user was on before the operation. */
+    previousBranch: string;
+    /** Full copy of state.json before mutation. */
+    previousState: DubState;
+    /** Map of branch name → commit SHA before mutation. */
+    branchTips: Record<string, string>;
+    /** Branches created by this operation (to be deleted on undo). */
+    createdBranches: string[];
+}
+/**
+ * Saves an undo entry to disk. Overwrites any previous entry (1 level only).
+ */
+export declare function saveUndoEntry(entry: UndoEntry, cwd: string): Promise<void>;
+/**
+ * Reads the most recent undo entry.
+ * @throws {DubError} If no undo entry exists.
+ */
+export declare function readUndoEntry(cwd: string): Promise<UndoEntry>;
+/**
+ * Deletes the undo entry file. Called after a successful undo.
+ */
+export declare function clearUndoEntry(cwd: string): Promise<void>;
+//# sourceMappingURL=undo-log.d.ts.map

package/dist/lib/undo-log.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"undo-log.d.ts","sourceRoot":"","sources":["../../src/lib/undo-log.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAG3C;;;GAGG;AACH,MAAM,WAAW,SAAS;IACzB,2CAA2C;IAC3C,SAAS,EAAE,QAAQ,GAAG,SAAS,CAAC;IAChC,oDAAoD;IACpD,SAAS,EAAE,MAAM,CAAC;IAClB,mDAAmD;IACnD,cAAc,EAAE,MAAM,CAAC;IACvB,+CAA+C;IAC/C,aAAa,EAAE,QAAQ,CAAC;IACxB,uDAAuD;IACvD,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACnC,kEAAkE;IAClE,eAAe,EAAE,MAAM,EAAE,CAAC;CAC1B;AAOD;;GAEG;AACH,wBAAsB,aAAa,CAClC,KAAK,EAAE,SAAS,EAChB,GAAG,EAAE,MAAM,GACT,OAAO,CAAC,IAAI,CAAC,CAGf;AAED;;;GAGG;AACH,wBAAsB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,CAAC,CAOnE;AAED;;GAEG;AACH,wBAAsB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAK/D"}

package/dist/lib/undo-log.js

@@ -0,0 +1,37 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { DubError } from "./errors.js";
+import { getDubDir } from "./state.js";
+async function getUndoPath(cwd) {
+    const dubDir = await getDubDir(cwd);
+    return path.join(dubDir, "undo.json");
+}
+/**
+ * Saves an undo entry to disk. Overwrites any previous entry (1 level only).
+ */
+export async function saveUndoEntry(entry, cwd) {
+    const undoPath = await getUndoPath(cwd);
+    fs.writeFileSync(undoPath, `${JSON.stringify(entry, null, 2)}\n`);
+}
+/**
+ * Reads the most recent undo entry.
+ * @throws {DubError} If no undo entry exists.
+ */
+export async function readUndoEntry(cwd) {
+    const undoPath = await getUndoPath(cwd);
+    if (!fs.existsSync(undoPath)) {
+        throw new DubError("Nothing to undo.");
+    }
+    const raw = fs.readFileSync(undoPath, "utf-8");
+    return JSON.parse(raw);
+}
+/**
+ * Deletes the undo entry file. Called after a successful undo.
+ */
+export async function clearUndoEntry(cwd) {
+    const undoPath = await getUndoPath(cwd);
+    if (fs.existsSync(undoPath)) {
+        fs.unlinkSync(undoPath);
+    }
+}
+//# sourceMappingURL=undo-log.js.map

package/dist/lib/undo-log.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"undo-log.js","sourceRoot":"","sources":["../../src/lib/undo-log.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,SAAS,CAAC;AAC9B,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAClC,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAEvC,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAqBvC,KAAK,UAAU,WAAW,CAAC,GAAW;IACrC,MAAM,MAAM,GAAG,MAAM,SAAS,CAAC,GAAG,CAAC,CAAC;IACpC,OAAO,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;AACvC,CAAC;AAED;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CAClC,KAAgB,EAChB,GAAW;IAEX,MAAM,QAAQ,GAAG,MAAM,WAAW,CAAC,GAAG,CAAC,CAAC;IACxC,EAAE,CAAC,aAAa,CAAC,QAAQ,EAAE,GAAG,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC;AACnE,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,GAAW;IAC9C,MAAM,QAAQ,GAAG,MAAM,WAAW,CAAC,GAAG,CAAC,CAAC;IACxC,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,QAAQ,CAAC,EAAE,CAAC;QAC9B,MAAM,IAAI,QAAQ,CAAC,kBAAkB,CAAC,CAAC;IACxC,CAAC;IACD,MAAM,GAAG,GAAG,EAAE,CAAC,YAAY,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;IAC/C,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAc,CAAC;AACrC,CAAC;AAED;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAAC,GAAW;IAC/C,MAAM,QAAQ,GAAG,MAAM,WAAW,CAAC,GAAG,CAAC,CAAC;IACxC,IAAI,EAAE,CAAC,UAAU,CAAC,QAAQ,CAAC,EAAE,CAAC;QAC7B,EAAE,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC;IACzB,CAAC;AACF,CAAC"}

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "dubstack",
+  "version": "0.1.3",
+  "description": "CLI tool for managing stacked diffs (dependent git branches)",
+  "type": "module",
+  "bin": {
+    "dub": "./dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/wiseiodev/dubstack.git"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "keywords": [
+    "git",
+    "stacked-diffs",
+    "cli",
+    "branches"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "chalk": "^5.6.2",
+    "commander": "^14.0.3",
+    "execa": "^9.6.1"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.4.2",
+    "@types/node": "^25.2.3",
+    "tsx": "^4.21.0",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.18"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsx src/index.ts",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit",
+    "checks": "biome check .",
+    "checks:fix": "biome check --write ."
+  }
+}