@paleo/worktree-env 0.1.0

package/dist/slots.js

@@ -0,0 +1,132 @@
+import { execFileSync } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { allPorts, isValidPort } from "./ports.js";
+export const WORKTREES_DIR = ".local/worktrees";
+export const SLOTS_FILE = ".local/worktrees/slots.json";
+export function readSlots(mainWorktree) {
+    const filePath = join(mainWorktree, SLOTS_FILE);
+    if (!existsSync(filePath))
+        return { slots: {} };
+    return JSON.parse(readFileSync(filePath, "utf-8"));
+}
+export function writeSlots(mainWorktree, registry) {
+    const filePath = join(mainWorktree, SLOTS_FILE);
+    mkdirSync(join(mainWorktree, WORKTREES_DIR), { recursive: true });
+    writeFileSync(filePath, `${JSON.stringify(registry, undefined, 2)}\n`);
+}
+export function pickSlotPort(args, registry) {
+    const resolvedCurrent = resolve(args.currentWorktree);
+    if (args.slot !== undefined) {
+        const port = Number(args.slot);
+        if (!isValidPort(port, args.scheme)) {
+            console.error(`Error: Slot must be a valid port: ${allPorts(args.scheme).join(", ")}.`);
+            process.exit(1);
+        }
+        const existing = registry.slots[String(port)];
+        if (existing && resolve(existing.worktree) !== resolvedCurrent) {
+            console.error(`Error: Slot ${port} is already taken by ${existing.worktree} (branch: ${existing.branch}).`);
+            process.exit(1);
+        }
+        return port;
+    }
+    const existingEntry = Object.entries(registry.slots).find(([, v]) => resolve(v.worktree) === resolvedCurrent);
+    if (existingEntry)
+        return Number(existingEntry[0]);
+    for (const port of allPorts(args.scheme)) {
+        if (!registry.slots[String(port)])
+            return port;
+    }
+    console.error("Error: All slots are taken. Remove a worktree with --remove first.");
+    process.exit(1);
+}
+export function resolveAndRegisterSlot(input) {
+    const registry = readSlots(input.mainWorktree);
+    const port = pickSlotPort(input, registry);
+    const existing = registry.slots[String(port)];
+    let owner;
+    if (input.requestedOwner !== undefined) {
+        owner = input.requestedOwner;
+    }
+    else if (existing && existing.owner !== undefined) {
+        owner = existing.owner;
+    }
+    else {
+        owner = "default";
+    }
+    registry.slots[String(port)] = {
+        worktree: input.currentWorktree,
+        branch: input.branch,
+        owner,
+    };
+    writeSlots(input.mainWorktree, registry);
+    return { port, owner };
+}
+export function validateSlotAvailability(slotArg, ctx) {
+    if (slotArg === undefined)
+        return;
+    const port = Number(slotArg);
+    if (!isValidPort(port, ctx.scheme)) {
+        console.error(`Error: Slot must be a valid port: ${allPorts(ctx.scheme).join(", ")}.`);
+        process.exit(1);
+    }
+    const registry = readSlots(ctx.mainWorktree);
+    const existing = registry.slots[String(port)];
+    if (existing && resolve(existing.worktree) !== resolve(ctx.currentWorktree)) {
+        console.error(`Error: Slot ${port} is already taken by ${existing.worktree} (branch: ${existing.branch}).`);
+        process.exit(1);
+    }
+}
+export function lookupSlotForCwd() {
+    const cwd = resolve(process.cwd());
+    // Reads slots.json relative to cwd's `.local` symlink (so works in linked worktrees too).
+    const filePath = SLOTS_FILE;
+    if (!existsSync(filePath))
+        return undefined;
+    const registry = JSON.parse(readFileSync(filePath, "utf-8"));
+    for (const [port, entry] of Object.entries(registry.slots)) {
+        if (resolve(entry.worktree) === cwd) {
+            return {
+                slot: Number(port),
+                worktree: entry.worktree,
+                branch: entry.branch,
+                owner: entry.owner ?? "default",
+            };
+        }
+    }
+    return undefined;
+}
+export function synthesizeMainSlot(basePort) {
+    const gitCommonDir = execFileSync("git", ["rev-parse", "--path-format=absolute", "--git-common-dir"], { encoding: "utf-8" }).trim();
+    const mainWorktree = dirname(gitCommonDir);
+    const cwd = resolve(process.cwd());
+    if (resolve(mainWorktree) !== cwd)
+        return undefined;
+    const branch = execFileSync("git", ["branch", "--show-current"], { encoding: "utf-8" }).trim();
+    return { slot: basePort, worktree: cwd, branch, owner: "default" };
+}
+export function resolveCurrentSlot(basePort) {
+    const slot = lookupSlotForCwd() ?? synthesizeMainSlot(basePort);
+    if (!slot) {
+        console.error("Error: No slot found for this worktree. Run setup-worktree first.");
+        process.exit(1);
+    }
+    return slot;
+}
+export function handleSetOwner(input) {
+    if (input.isMainWorktree) {
+        console.error("Error: --set-owner must be run from a linked worktree.");
+        process.exit(1);
+    }
+    const registry = readSlots(input.mainWorktree);
+    const resolvedCurrent = resolve(input.currentWorktree);
+    const entry = Object.entries(registry.slots).find(([, v]) => resolve(v.worktree) === resolvedCurrent);
+    if (!entry) {
+        console.error("Error: No slot found for this worktree in the registry.");
+        process.exit(1);
+    }
+    const [slotPort, slotData] = entry;
+    registry.slots[slotPort] = { ...slotData, owner: input.newOwner };
+    writeSlots(input.mainWorktree, registry);
+    return { slotPort, owner: input.newOwner };
+}

package/dist/worktree.d.ts

@@ -0,0 +1,21 @@
+export interface WorktreeContext {
+    currentWorktree: string;
+    mainWorktree: string;
+    isMainWorktree: boolean;
+}
+export interface RunCtx {
+    verbose: boolean;
+}
+export declare function detectWorktree(): WorktreeContext;
+export declare function computeWorktreePath(mainWorktree: string, branch: string): string;
+export declare function branchExists(branch: string): boolean;
+export declare function useExistingBranch(branch: string, ctx: WorktreeContext, run: RunCtx): WorktreeContext;
+export declare function createBranch(requestedBranch: string, ctx: WorktreeContext, run: RunCtx): WorktreeContext;
+export declare function verifyBranchAbsentFromRemote(branch: string, run: RunCtx): void;
+export declare function getCurrentBranch(worktreePath: string): string;
+export declare function enforceWorktreeMode(args: {
+    use?: string;
+    create?: string;
+    self?: boolean;
+}, ctx: WorktreeContext): void;
+export declare function removeWorktree(worktreePath: string, run: RunCtx): void;

package/dist/worktree.js

@@ -0,0 +1,92 @@
+import { execFileSync } from "node:child_process";
+import { basename, dirname, join, resolve } from "node:path";
+function stdioFor(ctx) {
+    return ctx.verbose ? "inherit" : "pipe";
+}
+export function detectWorktree() {
+    const currentWorktree = execFileSync("git", ["rev-parse", "--show-toplevel"], {
+        encoding: "utf-8",
+    }).trim();
+    const gitCommonDir = execFileSync("git", ["rev-parse", "--path-format=absolute", "--git-common-dir"], { encoding: "utf-8" }).trim();
+    const mainWorktree = dirname(gitCommonDir);
+    const isMainWorktree = resolve(currentWorktree) === resolve(mainWorktree);
+    return { currentWorktree, mainWorktree, isMainWorktree };
+}
+export function computeWorktreePath(mainWorktree, branch) {
+    const repoName = basename(mainWorktree);
+    const sanitized = branch.replaceAll("/", "-");
+    return join(dirname(mainWorktree), `${repoName}-${sanitized}`);
+}
+export function branchExists(branch) {
+    try {
+        execFileSync("git", ["rev-parse", "--verify", branch], { stdio: "pipe" });
+        return true;
+    }
+    catch {
+        try {
+            execFileSync("git", ["rev-parse", "--verify", `origin/${branch}`], { stdio: "pipe" });
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+}
+export function useExistingBranch(branch, ctx, run) {
+    if (!branchExists(branch)) {
+        console.error(`Error: Branch "${branch}" does not exist locally or on the remote.`);
+        process.exit(1);
+    }
+    const worktreePath = computeWorktreePath(ctx.mainWorktree, branch);
+    execFileSync("git", ["worktree", "add", worktreePath, branch], { stdio: stdioFor(run) });
+    return { ...ctx, currentWorktree: worktreePath, isMainWorktree: false };
+}
+export function createBranch(requestedBranch, ctx, run) {
+    let finalBranch = requestedBranch;
+    if (branchExists(finalBranch)) {
+        let suffix = 2;
+        while (branchExists(`${requestedBranch}-${suffix}`)) {
+            ++suffix;
+        }
+        finalBranch = `${requestedBranch}-${suffix}`;
+    }
+    const worktreePath = computeWorktreePath(ctx.mainWorktree, finalBranch);
+    execFileSync("git", ["worktree", "add", "-b", finalBranch, worktreePath], {
+        stdio: stdioFor(run),
+    });
+    console.log(`Branch: ${finalBranch}`);
+    return { ...ctx, currentWorktree: worktreePath, isMainWorktree: false };
+}
+export function verifyBranchAbsentFromRemote(branch, run) {
+    execFileSync("git", ["fetch"], { stdio: stdioFor(run) });
+    const remoteBranches = execFileSync("git", ["branch", "-r", "--list", `origin/${branch}`], {
+        encoding: "utf-8",
+    }).trim();
+    if (remoteBranches.length > 0) {
+        console.error(`Error: Branch "${branch}" still exists on the remote. Use --no-remote-check to skip this verification.`);
+        process.exit(1);
+    }
+}
+export function getCurrentBranch(worktreePath) {
+    return execFileSync("git", ["branch", "--show-current"], {
+        encoding: "utf-8",
+        cwd: worktreePath,
+    }).trim();
+}
+export function enforceWorktreeMode(args, ctx) {
+    if (args.use || args.create) {
+        if (!ctx.isMainWorktree) {
+            console.error("Error: --use and --create must be run from the main worktree.");
+            process.exit(1);
+        }
+    }
+    else if (args.self) {
+        if (ctx.isMainWorktree) {
+            console.error("Error: --self must be run from a linked worktree, not from the main worktree.");
+            process.exit(1);
+        }
+    }
+}
+export function removeWorktree(worktreePath, run) {
+    execFileSync("git", ["worktree", "remove", "--force", worktreePath], { stdio: stdioFor(run) });
+}

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@paleo/worktree-env",
+  "version": "0.1.0",
+  "description": "Worktree-based concurrent local environment kernel.",
+  "keywords": [
+    "worktree",
+    "environment",
+    "concurrent",
+    "local"
+  ],
+  "license": "CC0-1.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/paleo/alignfirst.git",
+    "directory": "packages/worktree-env"
+  },
+  "engines": {
+    "node": ">=22.12.0"
+  },
+  "packageManager": "npm@11.11.0",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "clear": "rimraf dist/*",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "devDependencies": {
+    "@types/node": "~24.12.3",
+    "rimraf": "~6.1.3",
+    "typescript": "~6.0.3",
+    "vitest": "~4.1.5"
+  }
+}