git-stint 0.1.1

package/dist/cli.js

@@ -0,0 +1,268 @@
+import { readFileSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import * as session from "./session.js";
+import { checkConflicts } from "./conflicts.js";
+import { test, testCombine } from "./test-session.js";
+const args = process.argv.slice(2);
+const command = args[0];
+// Known flags that take a value (used by arg parser to skip correctly)
+const VALUE_FLAGS = new Set(["-m", "--session", "--title", "--combine"]);
+function getFlag(flag) {
+    // Check for --flag=value syntax
+    const eqPrefix = flag + "=";
+    for (const arg of args) {
+        if (arg.startsWith(eqPrefix)) {
+            return arg.slice(eqPrefix.length);
+        }
+    }
+    // Check for --flag value syntax
+    const idx = args.indexOf(flag);
+    if (idx === -1)
+        return undefined;
+    const value = args[idx + 1];
+    if (value === undefined) {
+        throw new Error(`Flag '${flag}' requires a value.`);
+    }
+    return value;
+}
+/** Check if an arg is a value flag, handling both --flag and --flag=value forms. */
+function isValueFlag(arg) {
+    if (VALUE_FLAGS.has(arg))
+        return true;
+    // --flag=value: the flag consumed its value inline, don't skip next arg
+    for (const f of VALUE_FLAGS) {
+        if (arg.startsWith(f + "="))
+            return false; // value is inline, no skip
+    }
+    return false;
+}
+function getPositional(index) {
+    let pos = 0;
+    for (let i = 1; i < args.length; i++) {
+        if (args[i].startsWith("-")) {
+            // Only skip next arg if this flag takes a separate value (not --flag=value)
+            if (isValueFlag(args[i]))
+                i++;
+            continue;
+        }
+        if (pos === index)
+            return args[i];
+        pos++;
+    }
+    return undefined;
+}
+function getAllPositional() {
+    const result = [];
+    for (let i = 1; i < args.length; i++) {
+        if (args[i].startsWith("-")) {
+            if (isValueFlag(args[i]))
+                i++;
+            continue;
+        }
+        result.push(args[i]);
+    }
+    return result;
+}
+try {
+    switch (command) {
+        case "start": {
+            const name = getPositional(0);
+            session.start(name);
+            break;
+        }
+        case "track": {
+            const files = getAllPositional();
+            if (files.length === 0) {
+                console.error("Usage: git stint track <file...>");
+                process.exit(1);
+            }
+            const sessionFlag = getFlag("--session");
+            session.track(files, sessionFlag);
+            break;
+        }
+        case "status": {
+            session.status(getFlag("--session"));
+            break;
+        }
+        case "diff": {
+            session.diff(getFlag("--session"));
+            break;
+        }
+        case "commit": {
+            const message = getFlag("-m");
+            if (!message) {
+                console.error("Usage: git stint commit -m \"message\"");
+                process.exit(1);
+            }
+            session.sessionCommit(message, getFlag("--session"));
+            break;
+        }
+        case "log": {
+            session.log(getFlag("--session"));
+            break;
+        }
+        case "squash": {
+            const message = getFlag("-m");
+            if (!message) {
+                console.error("Usage: git stint squash -m \"message\"");
+                process.exit(1);
+            }
+            session.squash(message, getFlag("--session"));
+            break;
+        }
+        case "merge": {
+            session.merge(getFlag("--session"));
+            break;
+        }
+        case "pr": {
+            const title = getFlag("--title");
+            session.pr(title, getFlag("--session"));
+            break;
+        }
+        case "end": {
+            session.end(getFlag("--session"));
+            break;
+        }
+        case "abort": {
+            session.abort(getFlag("--session"));
+            break;
+        }
+        case "undo": {
+            session.undo(getFlag("--session"));
+            break;
+        }
+        case "conflicts": {
+            checkConflicts(getFlag("--session"));
+            break;
+        }
+        case "test": {
+            const combineNames = getFlag("--combine");
+            if (combineNames) {
+                // Collect all names after --combine
+                const idx = args.indexOf("--combine");
+                const names = [];
+                for (let i = idx + 1; i < args.length; i++) {
+                    if (args[i].startsWith("-"))
+                        break;
+                    names.push(args[i]);
+                }
+                if (names.length < 2) {
+                    console.error("Usage: git stint test --combine <session1> <session2> [...]");
+                    process.exit(1);
+                }
+                const dashIdx = args.indexOf("--");
+                const testCmd = dashIdx >= 0 ? args.slice(dashIdx + 1).join(" ") : undefined;
+                testCombine(names, testCmd);
+            }
+            else {
+                const dashIdx = args.indexOf("--");
+                const testCmd = dashIdx >= 0 ? args.slice(dashIdx + 1).join(" ") : undefined;
+                test(getFlag("--session"), testCmd);
+            }
+            break;
+        }
+        case "list": {
+            if (args.includes("--json")) {
+                session.listJson();
+            }
+            else {
+                session.list();
+            }
+            break;
+        }
+        case "prune": {
+            session.prune();
+            break;
+        }
+        case "install-hooks": {
+            const { install } = await import("./install-hooks.js");
+            const scope = args.includes("--user") ? "user" : "project";
+            install(scope);
+            break;
+        }
+        case "uninstall-hooks": {
+            const { uninstall } = await import("./install-hooks.js");
+            const scope = args.includes("--user") ? "user" : "project";
+            uninstall(scope);
+            break;
+        }
+        case "version":
+        case "--version":
+        case "-v": {
+            printVersion();
+            break;
+        }
+        case "help":
+        case "--help":
+        case "-h":
+        case undefined: {
+            printHelp();
+            break;
+        }
+        default: {
+            console.error(`Unknown command: ${command}`);
+            console.error("Run `git stint help` for usage.");
+            process.exit(1);
+        }
+    }
+}
+catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    console.error(`Error: ${message}`);
+    process.exit(1);
+}
+function getVersion() {
+    try {
+        const thisDir = dirname(fileURLToPath(import.meta.url));
+        const pkgPath = join(thisDir, "..", "package.json");
+        const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
+        return pkg.version || "unknown";
+    }
+    catch {
+        return "unknown";
+    }
+}
+function printVersion() {
+    console.log(`git-stint ${getVersion()}`);
+}
+function printHelp() {
+    console.log(`git-stint ${getVersion()} — Session-scoped change tracking for AI coding agents
+
+Usage: git stint <command> [options]
+
+Commands:
+  start [name]              Create a new session (branch + worktree)
+  list                      List all active sessions
+  status                    Show current session state
+  track <file...>           Add files to the pending list
+  diff                      Show uncommitted changes
+  commit -m "msg"           Commit changes, advance baseline
+  log                       Show session commit history
+  squash -m "msg"           Collapse all commits into one
+  merge                     Merge session into main (no PR)
+  pr [--title "..."]        Push branch and create GitHub PR
+  end                       Finalize session, clean up everything
+  abort                     Discard session — delete all changes
+  undo                      Revert last commit, changes become pending
+  conflicts                 Check file overlap with other sessions
+  test [-- <cmd>]           Run tests in the session worktree
+  test --combine A B        Test multiple sessions merged together
+  prune                     Clean up orphaned worktrees/branches
+  install-hooks [--user]    Install Claude Code hooks
+  uninstall-hooks [--user]  Remove Claude Code hooks
+
+Options:
+  --session <name>          Specify session (auto-detected from CWD)
+  -m "message"              Commit/squash message
+  --title "title"           PR title
+  --version                 Show version number
+
+Examples:
+  git stint start auth-fix
+  cd .stint/auth-fix/
+  # make changes...
+  git stint commit -m "Fix auth token refresh"
+  git stint pr --title "Fix auth bug"
+  git stint end`);
+}

package/dist/conflicts.d.ts

@@ -0,0 +1 @@
+export declare function checkConflicts(sessionName?: string): void;

package/dist/conflicts.js

@@ -0,0 +1,49 @@
+import * as git from "./git.js";
+import { listManifests, resolveSession, getWorktreePath } from "./manifest.js";
+export function checkConflicts(sessionName) {
+    const current = resolveSession(sessionName);
+    const others = listManifests().filter((m) => m.name !== current.name);
+    if (others.length === 0) {
+        console.log("No other active sessions.");
+        return;
+    }
+    // Get current session's changed files
+    const currentFiles = new Set();
+    for (const cs of current.changesets) {
+        cs.files.forEach((f) => currentFiles.add(f));
+    }
+    current.pending.forEach((f) => currentFiles.add(f));
+    // Also check uncommitted changes in worktree
+    const worktree = getWorktreePath(current);
+    try {
+        const uncommitted = git.gitInDir(worktree, "diff", "--name-only");
+        if (uncommitted) {
+            uncommitted.split("\n").forEach((f) => currentFiles.add(f));
+        }
+        const staged = git.gitInDir(worktree, "diff", "--cached", "--name-only");
+        if (staged) {
+            staged.split("\n").forEach((f) => currentFiles.add(f));
+        }
+    }
+    catch { /* worktree may not be accessible */ }
+    let hasConflicts = false;
+    for (const other of others) {
+        const otherFiles = new Set();
+        for (const cs of other.changesets) {
+            cs.files.forEach((f) => otherFiles.add(f));
+        }
+        other.pending.forEach((f) => otherFiles.add(f));
+        const overlap = [...currentFiles].filter((f) => otherFiles.has(f));
+        if (overlap.length > 0) {
+            hasConflicts = true;
+            console.log(`Overlap with session '${other.name}':`);
+            for (const f of overlap) {
+                console.log(`  ${f}`);
+            }
+            console.log();
+        }
+    }
+    if (!hasConflicts) {
+        console.log("No file overlaps with other sessions.");
+    }
+}

package/dist/git.d.ts

@@ -0,0 +1,40 @@
+export declare function git(...args: string[]): string;
+export declare function gitInDir(dir: string, ...args: string[]): string;
+export declare function getHead(dir?: string): string;
+export declare function getGitDir(): string;
+/** Returns the main .git dir (shared across worktrees). */
+export declare function getGitCommonDir(): string;
+export declare function getTopLevel(): string;
+export declare function currentBranch(dir?: string): string;
+/**
+ * Detect the default branch (main/master/etc) by checking the remote HEAD ref.
+ * Falls back to "main" if detection fails.
+ */
+export declare function getDefaultBranch(): string;
+export declare function branchExists(name: string): boolean;
+export declare function createBranch(name: string, from: string): void;
+export declare function deleteBranch(name: string): void;
+/**
+ * Check if a remote-tracking ref exists locally (no network call).
+ * Uses `git branch -r --list` which reads the local ref cache.
+ */
+export declare function remoteBranchExists(name: string): boolean;
+export declare function deleteRemoteBranch(name: string): void;
+export declare function addWorktree(path: string, branch: string): void;
+/** Create a worktree in detached HEAD mode at a given ref. */
+export declare function addWorktreeDetached(path: string, ref: string): void;
+export declare function removeWorktree(path: string, force?: boolean): void;
+export declare function diffNameOnly(base: string, head: string, dir?: string): string[];
+export declare function diffStat(base: string, head: string): string;
+export declare function logOneline(base: string, head: string): string;
+export declare function statusShort(dir: string): string;
+export declare function hasUncommittedChanges(dir: string): boolean;
+export declare function addAll(dir: string): void;
+export declare function commit(dir: string, message: string): string;
+export declare function resetSoft(dir: string, to: string): void;
+/** Reset HEAD to a specific target, keeping changes as unstaged. */
+export declare function resetMixed(dir: string, to: string): void;
+export declare function mergeInto(targetDir: string, ...branches: string[]): void;
+export declare function push(branch: string): void;
+export declare function isInsideGitRepo(): boolean;
+export declare function hasCommits(): boolean;

package/dist/git.js

@@ -0,0 +1,149 @@
+import { execFileSync } from "node:child_process";
+export function git(...args) {
+    try {
+        return execFileSync("git", args, { encoding: "utf-8", stdio: ["pipe", "pipe", "pipe"] }).trim();
+    }
+    catch (err) {
+        const e = err;
+        const stderr = e.stderr?.trim() || e.message || "unknown error";
+        throw new Error(`git ${args[0]} failed: ${stderr}`);
+    }
+}
+export function gitInDir(dir, ...args) {
+    return git("-C", dir, ...args);
+}
+export function getHead(dir) {
+    return dir ? gitInDir(dir, "rev-parse", "HEAD") : git("rev-parse", "HEAD");
+}
+export function getGitDir() {
+    return git("rev-parse", "--git-dir");
+}
+/** Returns the main .git dir (shared across worktrees). */
+export function getGitCommonDir() {
+    return git("rev-parse", "--git-common-dir");
+}
+export function getTopLevel() {
+    return git("rev-parse", "--show-toplevel");
+}
+export function currentBranch(dir) {
+    const args = ["rev-parse", "--abbrev-ref", "HEAD"];
+    return dir ? gitInDir(dir, ...args) : git(...args);
+}
+/**
+ * Detect the default branch (main/master/etc) by checking the remote HEAD ref.
+ * Falls back to "main" if detection fails.
+ */
+export function getDefaultBranch() {
+    try {
+        const ref = git("symbolic-ref", "refs/remotes/origin/HEAD");
+        return ref.replace("refs/remotes/origin/", "");
+    }
+    catch {
+        // No remote HEAD — check if 'main' or 'master' exists locally
+        if (branchExists("main"))
+            return "main";
+        if (branchExists("master"))
+            return "master";
+        return "main";
+    }
+}
+export function branchExists(name) {
+    try {
+        git("show-ref", "--verify", "--quiet", `refs/heads/${name}`);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export function createBranch(name, from) {
+    git("branch", name, from);
+}
+export function deleteBranch(name) {
+    git("branch", "-D", name);
+}
+/**
+ * Check if a remote-tracking ref exists locally (no network call).
+ * Uses `git branch -r --list` which reads the local ref cache.
+ */
+export function remoteBranchExists(name) {
+    try {
+        const output = git("branch", "-r", "--list", `origin/${name}`);
+        return output.trim().length > 0;
+    }
+    catch {
+        return false;
+    }
+}
+export function deleteRemoteBranch(name) {
+    git("push", "origin", "--delete", name);
+}
+export function addWorktree(path, branch) {
+    git("worktree", "add", path, branch);
+}
+/** Create a worktree in detached HEAD mode at a given ref. */
+export function addWorktreeDetached(path, ref) {
+    git("worktree", "add", "--detach", path, ref);
+}
+export function removeWorktree(path, force = false) {
+    const args = force
+        ? ["worktree", "remove", "--force", path]
+        : ["worktree", "remove", path];
+    git(...args);
+}
+export function diffNameOnly(base, head, dir) {
+    const args = ["diff", "--name-only", `${base}..${head}`];
+    const output = dir ? gitInDir(dir, ...args) : git(...args);
+    return output ? output.split("\n") : [];
+}
+export function diffStat(base, head) {
+    return git("diff", "--stat", `${base}..${head}`);
+}
+export function logOneline(base, head) {
+    return git("log", "--oneline", `${base}..${head}`);
+}
+export function statusShort(dir) {
+    return gitInDir(dir, "status", "--short");
+}
+export function hasUncommittedChanges(dir) {
+    const status = statusShort(dir);
+    return status.length > 0;
+}
+export function addAll(dir) {
+    gitInDir(dir, "add", "-A");
+}
+export function commit(dir, message) {
+    gitInDir(dir, "commit", "-m", message);
+    return gitInDir(dir, "rev-parse", "HEAD");
+}
+export function resetSoft(dir, to) {
+    gitInDir(dir, "reset", "--soft", to);
+}
+/** Reset HEAD to a specific target, keeping changes as unstaged. */
+export function resetMixed(dir, to) {
+    gitInDir(dir, "reset", to);
+}
+export function mergeInto(targetDir, ...branches) {
+    gitInDir(targetDir, "merge", ...branches);
+}
+export function push(branch) {
+    git("push", "-u", "origin", branch);
+}
+export function isInsideGitRepo() {
+    try {
+        git("rev-parse", "--is-inside-work-tree");
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export function hasCommits() {
+    try {
+        git("rev-parse", "HEAD");
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/install-hooks.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Installs git-stint hooks into Claude Code's settings.
+ *
+ * Hooks installed:
+ *   PreToolUse (Write/Edit): Track files written in session worktrees.
+ *   Stop: Commit pending changes as WIP checkpoint.
+ */
+export declare function install(scope: "project" | "user"): void;
+export declare function uninstall(scope: "project" | "user"): void;

package/dist/install-hooks.js

@@ -0,0 +1,111 @@
+/**
+ * Installs git-stint hooks into Claude Code's settings.
+ *
+ * Hooks installed:
+ *   PreToolUse (Write/Edit): Track files written in session worktrees.
+ *   Stop: Commit pending changes as WIP checkpoint.
+ */
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+const HOOKS = {
+    hooks: {
+        PreToolUse: [
+            {
+                matcher: "Write|Edit|NotebookEdit",
+                command: "git-stint-hook-pre-tool",
+            },
+        ],
+        Stop: [
+            {
+                command: "git-stint-hook-stop",
+            },
+        ],
+    },
+};
+function getSettingsPath(scope) {
+    if (scope === "user") {
+        const home = process.env.HOME || process.env.USERPROFILE || "~";
+        return join(home, ".claude", "settings.json");
+    }
+    // Project scope
+    return join(process.cwd(), ".claude", "settings.json");
+}
+export function install(scope) {
+    const settingsPath = getSettingsPath(scope);
+    const dir = resolve(settingsPath, "..");
+    // Read existing settings or start fresh
+    let settings = {};
+    if (existsSync(settingsPath)) {
+        settings = JSON.parse(readFileSync(settingsPath, "utf-8"));
+    }
+    // Merge hooks (don't overwrite existing hooks)
+    const hooks = (settings.hooks || {});
+    for (const [event, hookList] of Object.entries(HOOKS.hooks)) {
+        if (!hooks[event]) {
+            hooks[event] = [];
+        }
+        for (const hook of hookList) {
+            const exists = hooks[event].some((h) => h.command === hook.command);
+            if (!exists) {
+                hooks[event].push(hook);
+            }
+        }
+    }
+    settings.hooks = hooks;
+    if (!existsSync(dir)) {
+        mkdirSync(dir, { recursive: true });
+    }
+    // Atomic write: temp file + rename to prevent corruption if interrupted
+    const tmp = settingsPath + ".tmp";
+    writeFileSync(tmp, JSON.stringify(settings, null, 2) + "\n");
+    renameSync(tmp, settingsPath);
+    console.log(`Hooks installed to ${settingsPath}`);
+    console.log("\nHooks added:");
+    console.log("  PreToolUse (Write/Edit): track files in session worktrees");
+    console.log("  Stop: commit pending changes as WIP checkpoint");
+}
+/** Known hook commands installed by git-stint. */
+const STINT_COMMANDS = new Set(Object.values(HOOKS.hooks).flat().map((h) => h.command));
+export function uninstall(scope) {
+    const settingsPath = getSettingsPath(scope);
+    if (!existsSync(settingsPath)) {
+        console.log("No settings file found. Nothing to uninstall.");
+        return;
+    }
+    let settings;
+    try {
+        settings = JSON.parse(readFileSync(settingsPath, "utf-8"));
+    }
+    catch {
+        console.error(`Failed to parse ${settingsPath}. Fix it manually.`);
+        return;
+    }
+    const hooks = settings.hooks;
+    if (!hooks) {
+        console.log("No hooks configured. Nothing to uninstall.");
+        return;
+    }
+    let removed = 0;
+    for (const event of Object.keys(hooks)) {
+        const before = hooks[event].length;
+        hooks[event] = hooks[event].filter((h) => !STINT_COMMANDS.has(h.command));
+        removed += before - hooks[event].length;
+        // Remove empty arrays to keep settings clean
+        if (hooks[event].length === 0) {
+            delete hooks[event];
+        }
+    }
+    // Remove empty hooks object
+    if (Object.keys(hooks).length === 0) {
+        delete settings.hooks;
+    }
+    if (removed === 0) {
+        console.log("No git-stint hooks found. Nothing to uninstall.");
+        return;
+    }
+    // Atomic write
+    const tmp = settingsPath + ".tmp";
+    writeFileSync(tmp, JSON.stringify(settings, null, 2) + "\n");
+    renameSync(tmp, settingsPath);
+    console.log(`Removed ${removed} git-stint hook(s) from ${settingsPath}`);
+}

package/dist/manifest.d.ts

@@ -0,0 +1,59 @@
+export interface Changeset {
+    id: number;
+    sha: string;
+    message: string;
+    files: string[];
+    /** ISO 8601 timestamp */
+    timestamp: string;
+}
+export interface SessionManifest {
+    /** Schema version for forward compatibility. Current: 1. */
+    version: number;
+    name: string;
+    /** HEAD sha when session was created (never changes). */
+    startedAt: string;
+    /** Advances on each commit. Used to compute diffs for the next changeset. */
+    baseline: string;
+    /** Git branch name, e.g. "stint/my-feature" */
+    branch: string;
+    /** Worktree path relative to repo root, e.g. ".stint/my-feature" */
+    worktree: string;
+    changesets: Changeset[];
+    /** Files tracked since last commit. */
+    pending: string[];
+}
+declare const MANIFEST_VERSION = 1;
+declare const BRANCH_PREFIX = "stint/";
+declare const WORKTREE_DIR = ".stint";
+export { BRANCH_PREFIX, WORKTREE_DIR, MANIFEST_VERSION };
+export declare function getSessionsDir(): string;
+export declare function loadManifest(name: string): SessionManifest | null;
+/**
+ * Atomic write: write to temp file, then rename.
+ * Prevents corruption if the process is killed mid-write.
+ */
+export declare function saveManifest(manifest: SessionManifest): void;
+export declare function listManifests(): SessionManifest[];
+export declare function deleteManifest(name: string): void;
+/**
+ * Resolve which session is active.
+ * Priority:
+ * 1. Explicit name passed via --session flag
+ * 2. CWD is inside a .stint/<name>/ worktree
+ * 3. Only one session exists → use it
+ * 4. Error
+ */
+export declare function resolveSession(explicit?: string): SessionManifest;
+/**
+ * Get the repo root (main worktree root, not a stint worktree).
+ * Uses git's --show-toplevel from the main worktree context.
+ */
+export declare function getRepoRoot(): string;
+/**
+ * Get the absolute worktree path for a session.
+ */
+export declare function getWorktreePath(manifest: SessionManifest): string;
+/**
+ * Check if any sessions exist. Cheaper than loading all manifests.
+ */
+export declare function hasAnySessions(): boolean;