@paleo/worktree-env 0.1.0

package/dist/errors.js

@@ -0,0 +1,22 @@
+export class StartupError extends Error {
+    label;
+    reason;
+    logFile;
+    constructor(label, reason, logFile) {
+        super(`${label}: ${reason}`);
+        this.label = label;
+        this.reason = reason;
+        this.logFile = logFile;
+    }
+}
+export class ConfigError extends Error {
+    exitCode;
+    constructor(message, exitCode = 1) {
+        super(message);
+        this.exitCode = exitCode;
+    }
+}
+export function exitWith(code, message) {
+    console.error(message);
+    process.exit(code);
+}

package/dist/helpers.d.ts

@@ -0,0 +1,8 @@
+export declare function patchEnvFile(content: string, patches: Record<string, string>): string;
+export declare function extractHost(content: string, key: string, fallback?: string): string;
+export interface CopyAndPatchCtx {
+    currentWorktree: string;
+    mainWorktree: string;
+    log: (msg: string) => void;
+}
+export declare function copyAndPatchFile(ctx: CopyAndPatchCtx, relPath: string, patchFn: (content: string) => string, label: string, force: boolean, required?: boolean): void;

package/dist/helpers.js

@@ -0,0 +1,42 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+export function patchEnvFile(content, patches) {
+    const lines = content.trimEnd().split("\n");
+    for (const [key, value] of Object.entries(patches)) {
+        const idx = lines.findIndex((l) => l.startsWith(`${key}=`));
+        if (idx !== -1) {
+            lines[idx] = `${key}=${value}`;
+        }
+        else {
+            lines.push(`${key}=${value}`);
+        }
+    }
+    return `${lines.join("\n")}\n`;
+}
+export function extractHost(content, key, fallback = "localhost") {
+    const re = new RegExp(`^${key}=(?:https?://)?([^:\\s]+)`, "m");
+    const m = content.match(re);
+    return m ? m[1] : fallback;
+}
+export function copyAndPatchFile(ctx, relPath, patchFn, label, force, required = false) {
+    const targetPath = join(ctx.currentWorktree, relPath);
+    const sourcePath = join(ctx.mainWorktree, relPath);
+    const alreadyExists = existsSync(targetPath);
+    if (alreadyExists && !force) {
+        ctx.log(`Skipped ${label} (already exists; use --force to overwrite).`);
+        return;
+    }
+    if (!existsSync(sourcePath)) {
+        if (required) {
+            console.error(`Error: ${relPath} not found in main worktree (required).`);
+            process.exit(1);
+        }
+        ctx.log(`Warning: ${relPath} not found in main worktree, skipping.`);
+        return;
+    }
+    const content = readFileSync(sourcePath, "utf-8");
+    const patched = patchFn(content);
+    mkdirSync(dirname(targetPath), { recursive: true });
+    writeFileSync(targetPath, patched);
+    ctx.log(`${alreadyExists ? "Overwritten" : "Created"} ${label}.`);
+}

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export { runSetupWorktree } from "./setup-worktree.js";
+export type { SetupWorktreeConfig, SetupContext, SummaryContext, PatchContext, ConfigFileEntry, TeardownContext, } from "./setup-worktree.js";
+export { runDevServer } from "./dev-server.js";
+export type { DevServerConfig, DevServerSummaryContext, ServerDescriptor, PortConfig, } from "./dev-server.js";
+export type { ResolvedSlot } from "./slots.js";
+import * as helpers from "./helpers.js";
+export { helpers };
+export { StartupError, ConfigError } from "./errors.js";

package/dist/index.js

@@ -0,0 +1,5 @@
+export { runSetupWorktree } from "./setup-worktree.js";
+export { runDevServer } from "./dev-server.js";
+import * as helpers from "./helpers.js";
+export { helpers };
+export { StartupError, ConfigError } from "./errors.js";

package/dist/log-polling.d.ts

@@ -0,0 +1,18 @@
+import { StartupError } from "./errors.js";
+export declare const LOG_TAIL_LINES = 30;
+export declare const POLL_INTERVAL_MS = 500;
+export declare const TIMEOUT_MS = 120000;
+export interface PollableServer {
+    name: string;
+    logFile: string;
+    detectSuccess: (logContent: string) => boolean;
+    detectError?: (logContent: string) => string | false;
+}
+export interface AwaitOptions {
+    timeoutMs?: number;
+    pollIntervalMs?: number;
+    isAlive?: (pid: number) => boolean;
+}
+export declare function waitForReady(server: PollableServer, pid: number, options?: AwaitOptions): Promise<void>;
+export declare function awaitAllReady(servers: PollableServer[], pids: number[], options?: AwaitOptions): Promise<void>;
+export declare function handleStartupFailure(err: StartupError): void;

package/dist/log-polling.js

@@ -0,0 +1,41 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { StartupError } from "./errors.js";
+import { isProcessAlive as defaultIsAlive } from "./process-control.js";
+export const LOG_TAIL_LINES = 30;
+export const POLL_INTERVAL_MS = 500;
+export const TIMEOUT_MS = 120_000;
+export async function waitForReady(server, pid, options = {}) {
+    const timeoutMs = options.timeoutMs ?? TIMEOUT_MS;
+    const pollIntervalMs = options.pollIntervalMs ?? POLL_INTERVAL_MS;
+    const isAlive = options.isAlive ?? defaultIsAlive;
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+        if (!isAlive(pid)) {
+            throw new StartupError(server.name, "process exited unexpectedly", server.logFile);
+        }
+        if (existsSync(server.logFile)) {
+            const logContent = readFileSync(server.logFile, "utf-8");
+            if (server.detectSuccess(logContent))
+                return;
+            const matched = server.detectError?.(logContent);
+            if (matched) {
+                throw new StartupError(server.name, `error detected (${matched})`, server.logFile);
+            }
+        }
+        await new Promise((r) => setTimeout(r, pollIntervalMs));
+    }
+    throw new StartupError(server.name, `did not become ready within ${timeoutMs / 1000}s`, server.logFile);
+}
+export async function awaitAllReady(servers, pids, options) {
+    await Promise.all(servers.map((server, i) => waitForReady(server, pids[i], options)));
+}
+export function handleStartupFailure(err) {
+    console.error(`\nError: ${err.label} ${err.reason}.`);
+    if (err.logFile && existsSync(err.logFile)) {
+        const lines = readFileSync(err.logFile, "utf-8").split("\n").slice(-LOG_TAIL_LINES);
+        console.error(`\n--- ${err.label} log tail (last ${LOG_TAIL_LINES} lines) ---`);
+        console.error(lines.join("\n"));
+        console.error(`--- end ---\nFull log: ${join(process.cwd(), err.logFile)}`);
+    }
+}

package/dist/ports.d.ts

@@ -0,0 +1,16 @@
+export interface PortSchemeOptions {
+    basePort: number;
+    portStep?: number;
+    maxSlotCount?: number;
+}
+export interface PortScheme {
+    basePort: number;
+    portStep: number;
+    maxSlotCount: number;
+    minPort: number;
+    maxPort: number;
+}
+export declare function resolvePortScheme(opts: PortSchemeOptions): PortScheme;
+export declare function isValidPort(port: number, scheme: PortScheme): boolean;
+export declare function allPorts(scheme: PortScheme): number[];
+export declare function defaultComputePorts(portNames: string[]): (slot: number) => Record<string, number>;

package/dist/ports.js

@@ -0,0 +1,37 @@
+export function resolvePortScheme(opts) {
+    const portStep = opts.portStep ?? 10;
+    const maxSlotCount = opts.maxSlotCount ?? 19;
+    const basePort = opts.basePort;
+    return {
+        basePort,
+        portStep,
+        maxSlotCount,
+        minPort: basePort + portStep,
+        maxPort: basePort + maxSlotCount * portStep,
+    };
+}
+export function isValidPort(port, scheme) {
+    return (Number.isInteger(port) &&
+        port >= scheme.minPort &&
+        port <= scheme.maxPort &&
+        (port - scheme.basePort) % scheme.portStep === 0);
+}
+export function allPorts(scheme) {
+    const ports = [];
+    for (let p = scheme.minPort; p <= scheme.maxPort; p += scheme.portStep) {
+        ports.push(p);
+    }
+    return ports;
+}
+export function defaultComputePorts(portNames) {
+    if (portNames.length === 0) {
+        throw new Error("portNames must not be empty");
+    }
+    return (slot) => {
+        const out = {};
+        portNames.forEach((name, i) => {
+            out[name] = slot + i;
+        });
+        return out;
+    };
+}

package/dist/process-control.d.ts

@@ -0,0 +1,7 @@
+export declare function readPid(pidFile: string): number | undefined;
+export declare function isProcessAlive(pid: number): boolean;
+export declare function isProcessGroupAlive(pid: number): boolean;
+export declare function killProcessGroup(pid: number, signal: NodeJS.Signals): void;
+export declare function cleanupPidFile(pidFile: string): void;
+export declare function stopProcessGroup(pid: number, timeoutMs?: number): Promise<void>;
+export declare function stopByPidFile(pidFile: string, label: string, log?: (msg: string) => void): Promise<void>;

package/dist/process-control.js

@@ -0,0 +1,67 @@
+import { existsSync, readFileSync, unlinkSync } from "node:fs";
+export function readPid(pidFile) {
+    if (!existsSync(pidFile))
+        return undefined;
+    const raw = readFileSync(pidFile, "utf-8").trim();
+    const pid = Number(raw);
+    if (!Number.isInteger(pid) || pid <= 0)
+        return undefined;
+    return pid;
+}
+export function isProcessAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export function isProcessGroupAlive(pid) {
+    try {
+        process.kill(-pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export function killProcessGroup(pid, signal) {
+    try {
+        process.kill(-pid, signal);
+    }
+    catch {
+        try {
+            process.kill(pid, signal);
+        }
+        catch {
+            // already dead
+        }
+    }
+}
+export function cleanupPidFile(pidFile) {
+    if (existsSync(pidFile))
+        unlinkSync(pidFile);
+}
+export async function stopProcessGroup(pid, timeoutMs = 10_000) {
+    killProcessGroup(pid, "SIGTERM");
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+        await new Promise((r) => setTimeout(r, 300));
+        if (!isProcessGroupAlive(pid))
+            return;
+    }
+    killProcessGroup(pid, "SIGKILL");
+}
+export async function stopByPidFile(pidFile, label, log = () => { }) {
+    const pid = readPid(pidFile);
+    if (pid === undefined || !isProcessAlive(pid)) {
+        cleanupPidFile(pidFile);
+        log(`No ${label} process is running.`);
+        return;
+    }
+    log(`Stopping ${label} (PID ${pid})...`);
+    await stopProcessGroup(pid);
+    cleanupPidFile(pidFile);
+    log(`${label} stopped.`);
+}

package/dist/setup-worktree.d.ts

@@ -0,0 +1,52 @@
+export interface SetupContext {
+    currentWorktree: string;
+    mainWorktree: string;
+    slot: number;
+    branch: string;
+    owner: string;
+    ports: Record<string, number>;
+    force: boolean;
+    verbose: boolean;
+}
+export interface PatchContext {
+    slot: number;
+    ports: Record<string, number>;
+    mainWorktree: string;
+    currentWorktree: string;
+}
+export interface ConfigFileEntry {
+    path: string;
+    patch: (content: string, ctx: PatchContext) => string;
+    required?: boolean;
+}
+export interface SummaryContext {
+    slot: number;
+    branch: string;
+    owner: string;
+    ports: Record<string, number>;
+    currentWorktree: string;
+    mainWorktree: string;
+}
+export interface TeardownContext {
+    worktree: string;
+    mainWorktree: string;
+    verbose: boolean;
+}
+export interface SetupWorktreeConfig {
+    basePort: number;
+    portStep?: number;
+    maxSlotCount?: number;
+    ports?: (slot: number) => Record<string, number>;
+    portNames?: string[];
+    perWorktreeDirs?: string[];
+    sharedDirs?: string[];
+    devServerPidFiles: string[];
+    devLimitEnvVar?: string;
+    configFiles: ConfigFileEntry[];
+    provisionDatabase: (ctx: SetupContext) => Promise<void> | void;
+    teardownInfrastructure?: (ctx: TeardownContext) => Promise<void> | void;
+    installAndBuild: (ctx: SetupContext) => Promise<void> | void;
+    afterDatabase?: (ctx: SetupContext) => Promise<void> | void;
+    printSummary: (ctx: SummaryContext) => string;
+}
+export declare function runSetupWorktree(config: SetupWorktreeConfig): Promise<void>;

package/dist/setup-worktree.js

@@ -0,0 +1,272 @@
+import { existsSync, mkdirSync, readFileSync, symlinkSync, writeFileSync } from "node:fs";
+import { dirname, join, relative, resolve } from "node:path";
+import { isRemoveMode, isSetOwnerMode, isSetupMode, parseSetupArgs, printSetupHelp, validateSetupFlags, } from "./cli.js";
+import { removeDevServerEntryByWorktree } from "./dev-servers-registry.js";
+import { ConfigError } from "./errors.js";
+import { copyAndPatchFile } from "./helpers.js";
+import { defaultComputePorts, resolvePortScheme } from "./ports.js";
+import { handleSetOwner, readSlots, resolveAndRegisterSlot, validateSlotAvailability, writeSlots, } from "./slots.js";
+import { createBranch, detectWorktree, enforceWorktreeMode, getCurrentBranch, removeWorktree, useExistingBranch, verifyBranchAbsentFromRemote, } from "./worktree.js";
+import { cleanupPidFile, isProcessAlive, isProcessGroupAlive, killProcessGroup, readPid, } from "./process-control.js";
+function makeLog(verbose) {
+    return (msg) => {
+        if (verbose)
+            console.log(msg);
+    };
+}
+function resolvePortsFn(config) {
+    if (config.ports)
+        return config.ports;
+    if (config.portNames && config.portNames.length > 0) {
+        return defaultComputePorts(config.portNames);
+    }
+    throw new ConfigError("Config error: provide either `ports` (function) or `portNames` (array).");
+}
+export async function runSetupWorktree(config) {
+    let args;
+    try {
+        args = parseSetupArgs();
+    }
+    catch (err) {
+        console.error(err.message);
+        process.exit(1);
+    }
+    const verbose = args.verbose ?? false;
+    if (args.help) {
+        printSetupHelp();
+        return;
+    }
+    try {
+        validateSetupFlags(args);
+    }
+    catch (err) {
+        if (err instanceof ConfigError) {
+            console.error(err.message);
+            process.exit(err.exitCode);
+        }
+        throw err;
+    }
+    if (!isSetupMode(args) && !isRemoveMode(args) && !isSetOwnerMode(args)) {
+        printSetupHelp();
+        return;
+    }
+    const ctx = detectWorktree();
+    enforceWorktreeMode(args, ctx);
+    const run = { verbose };
+    if (isRemoveMode(args)) {
+        await handleRemove(args, ctx, run, config);
+        return;
+    }
+    if (isSetOwnerMode(args)) {
+        handleSetOwnerMode(args, ctx);
+        return;
+    }
+    await runSetup(args, ctx, run, config);
+}
+async function runSetup(args, ctx, run, config) {
+    const log = makeLog(run.verbose);
+    const scheme = resolvePortScheme(config);
+    const portsFn = resolvePortsFn(config);
+    validateSlotAvailability(args.slot, {
+        currentWorktree: ctx.currentWorktree,
+        mainWorktree: ctx.mainWorktree,
+        scheme,
+    });
+    const setupCtx = ensureWorktree(args, ctx, run);
+    const branch = getCurrentBranch(setupCtx.currentWorktree);
+    const { port: slot, owner } = resolveAndRegisterSlot({
+        slot: args.slot,
+        currentWorktree: setupCtx.currentWorktree,
+        mainWorktree: setupCtx.mainWorktree,
+        scheme,
+        branch,
+        requestedOwner: args.owner,
+    });
+    const ports = portsFn(slot);
+    log(`Using slot ${slot} (${Object.entries(ports)
+        .map(([k, v]) => `${k}: ${v}`)
+        .join(", ")})`);
+    const sharedDirs = config.sharedDirs ?? [".local", ".plans"];
+    const perWorktreeDirs = config.perWorktreeDirs ?? [".local-data"];
+    setupLocalDirectories(setupCtx.currentWorktree, perWorktreeDirs);
+    linkSharedDirectories(setupCtx, sharedDirs, log);
+    generateConfigFiles(setupCtx, config.configFiles, slot, ports, args.force ?? false, log);
+    const force = args.force ?? false;
+    const setupContext = {
+        currentWorktree: setupCtx.currentWorktree,
+        mainWorktree: setupCtx.mainWorktree,
+        slot,
+        branch,
+        owner,
+        ports,
+        force,
+        verbose: run.verbose,
+    };
+    await config.provisionDatabase(setupContext);
+    await config.installAndBuild(setupContext);
+    if (config.afterDatabase)
+        await config.afterDatabase(setupContext);
+    console.log(config.printSummary({
+        slot,
+        branch,
+        owner,
+        ports,
+        currentWorktree: setupCtx.currentWorktree,
+        mainWorktree: setupCtx.mainWorktree,
+    }));
+}
+function ensureWorktree(args, ctx, run) {
+    if (args.use)
+        return useExistingBranch(args.use, ctx, run);
+    if (args.create)
+        return createBranch(args.create, ctx, run);
+    return ctx;
+}
+function setupLocalDirectories(worktreePath, dirs) {
+    for (const dir of dirs) {
+        mkdirSync(join(worktreePath, dir), { recursive: true });
+    }
+}
+function linkSharedDirectories(ctx, dirs, log) {
+    for (const dirName of dirs) {
+        const link = join(ctx.currentWorktree, dirName);
+        const mainDir = join(ctx.mainWorktree, dirName);
+        if (!existsSync(mainDir)) {
+            log(`Skipped ${dirName} symlink (not present in main worktree).`);
+        }
+        else if (existsSync(link)) {
+            log(`Skipped ${dirName} symlink (already exists).`);
+        }
+        else {
+            const relTarget = relative(ctx.currentWorktree, mainDir);
+            symlinkSync(relTarget, link);
+            log(`Created ${dirName} symlink → main worktree.`);
+        }
+    }
+}
+function generateConfigFiles(ctx, entries, slot, ports, force, log) {
+    for (const entry of entries) {
+        copyAndPatchFile({ currentWorktree: ctx.currentWorktree, mainWorktree: ctx.mainWorktree, log }, entry.path, (content) => entry.patch(content, {
+            slot,
+            ports,
+            mainWorktree: ctx.mainWorktree,
+            currentWorktree: ctx.currentWorktree,
+        }), entry.path, force, entry.required ?? false);
+    }
+}
+function resolveRemoveTarget(args, ctx, registry, removeSelf) {
+    if (removeSelf) {
+        if (ctx.isMainWorktree) {
+            console.error("Error: Cannot remove the main worktree.");
+            process.exit(1);
+        }
+        const resolvedCurrent = resolve(ctx.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);
+        }
+        return { slotPort: entry[0], branch: entry[1].branch, worktreePath: ctx.currentWorktree };
+    }
+    const branch = args.remove ?? "";
+    const entry = Object.entries(registry.slots).find(([, v]) => v.branch === branch);
+    if (!entry) {
+        console.error(`Error: No worktree found for branch "${branch}" in the slot registry.`);
+        process.exit(1);
+    }
+    const worktreePath = entry[1].worktree;
+    if (resolve(ctx.currentWorktree) === resolve(worktreePath)) {
+        console.error("Error: You are currently in this worktree. Use --remove-self instead.");
+        process.exit(1);
+    }
+    return { slotPort: entry[0], branch, worktreePath };
+}
+async function stopDevServerByPidFiles(worktreePath, pidFiles, log) {
+    for (const pidFileRel of pidFiles) {
+        const pidFile = join(worktreePath, pidFileRel);
+        const pid = readPid(pidFile);
+        if (pid === undefined)
+            continue;
+        if (!isProcessAlive(pid)) {
+            cleanupPidFile(pidFile);
+            continue;
+        }
+        log(`Stopping dev server (PID ${pid})...`);
+        killProcessGroup(pid, "SIGTERM");
+        const deadline = Date.now() + 5_000;
+        let stillAlive = true;
+        while (Date.now() < deadline) {
+            if (!isProcessGroupAlive(pid)) {
+                stillAlive = false;
+                break;
+            }
+            await new Promise((r) => setTimeout(r, 300));
+        }
+        if (stillAlive) {
+            killProcessGroup(pid, "SIGKILL");
+        }
+        cleanupPidFile(pidFile);
+    }
+}
+async function handleRemove(args, ctx, run, config) {
+    const log = makeLog(run.verbose);
+    const removeSelf = Boolean(args["remove-self"]);
+    const registry = readSlots(ctx.mainWorktree);
+    const target = resolveRemoveTarget(args, ctx, registry, removeSelf);
+    if (!args["no-remote-check"]) {
+        verifyBranchAbsentFromRemote(target.branch, run);
+    }
+    if (!existsSync(target.worktreePath)) {
+        console.warn(`Warning: Worktree directory ${target.worktreePath} not found. Cleaning up registry only.`);
+        delete registry.slots[target.slotPort];
+        writeSlots(ctx.mainWorktree, registry);
+        console.log(`Removed registry entry for branch "${target.branch}" (slot ${target.slotPort}).`);
+        return;
+    }
+    await stopDevServerByPidFiles(target.worktreePath, config.devServerPidFiles, log);
+    if (config.teardownInfrastructure) {
+        await config.teardownInfrastructure({
+            worktree: target.worktreePath,
+            mainWorktree: ctx.mainWorktree,
+            verbose: run.verbose,
+        });
+    }
+    delete registry.slots[target.slotPort];
+    writeSlots(ctx.mainWorktree, registry);
+    removeDevServerEntryByWorktree(ctx.mainWorktree, target.worktreePath);
+    if (removeSelf) {
+        process.chdir(ctx.mainWorktree);
+    }
+    removeWorktree(target.worktreePath, run);
+    console.log(`Removed worktree for branch "${target.branch}" (slot ${target.slotPort}).`);
+    if (removeSelf) {
+        console.log(`Now run: cd ${ctx.mainWorktree}`);
+    }
+}
+function handleSetOwnerMode(args, ctx) {
+    const newOwner = args["set-owner"] ?? "default";
+    const { slotPort } = handleSetOwner({
+        newOwner,
+        currentWorktree: ctx.currentWorktree,
+        mainWorktree: ctx.mainWorktree,
+        isMainWorktree: ctx.isMainWorktree,
+    });
+    // Propagate to dev-servers.json entries for this worktree.
+    const devServersPath = join(ctx.mainWorktree, ".local/worktrees/dev-servers.json");
+    if (existsSync(devServersPath)) {
+        const data = JSON.parse(readFileSync(devServersPath, "utf-8"));
+        let changed = false;
+        const resolvedCurrent = resolve(ctx.currentWorktree);
+        for (const server of data.servers) {
+            if (resolve(server.worktree) === resolvedCurrent) {
+                server.owner = newOwner;
+                changed = true;
+            }
+        }
+        if (changed) {
+            mkdirSync(dirname(devServersPath), { recursive: true });
+            writeFileSync(devServersPath, `${JSON.stringify(data, undefined, 2)}\n`);
+        }
+    }
+    console.log(`Owner for slot ${slotPort}: ${newOwner}`);
+}

package/dist/slots.d.ts

@@ -0,0 +1,56 @@
+import { type PortScheme } from "./ports.js";
+export declare const WORKTREES_DIR = ".local/worktrees";
+export declare const SLOTS_FILE = ".local/worktrees/slots.json";
+export interface SlotEntry {
+    worktree: string;
+    branch: string;
+    owner: string;
+}
+export interface SlotsRegistry {
+    slots: Record<string, SlotEntry>;
+}
+export interface ResolvedSlot {
+    slot: number;
+    worktree: string;
+    branch: string;
+    owner: string;
+}
+export declare function readSlots(mainWorktree: string): SlotsRegistry;
+export declare function writeSlots(mainWorktree: string, registry: SlotsRegistry): void;
+export interface PickSlotArgs {
+    slot?: string;
+    currentWorktree: string;
+    mainWorktree: string;
+    scheme: PortScheme;
+}
+export declare function pickSlotPort(args: PickSlotArgs, registry: SlotsRegistry): number;
+export interface RegisterSlotInput {
+    slot?: string;
+    currentWorktree: string;
+    mainWorktree: string;
+    scheme: PortScheme;
+    branch: string;
+    requestedOwner?: string;
+}
+export declare function resolveAndRegisterSlot(input: RegisterSlotInput): {
+    port: number;
+    owner: string;
+};
+export declare function validateSlotAvailability(slotArg: string | undefined, ctx: {
+    currentWorktree: string;
+    mainWorktree: string;
+    scheme: PortScheme;
+}): void;
+export declare function lookupSlotForCwd(): ResolvedSlot | undefined;
+export declare function synthesizeMainSlot(basePort: number): ResolvedSlot | undefined;
+export declare function resolveCurrentSlot(basePort: number): ResolvedSlot;
+export interface SetOwnerInput {
+    newOwner: string;
+    currentWorktree: string;
+    mainWorktree: string;
+    isMainWorktree: boolean;
+}
+export declare function handleSetOwner(input: SetOwnerInput): {
+    slotPort: string;
+    owner: string;
+};