@paleo/worktree-env 0.2.0 → 0.4.0

package/README.md

@@ -41,7 +41,6 @@ import { runSetupWorktree, helpers } from "@paleo/worktree-env";
 await runSetupWorktree({
   basePort: 8100,
   portNames: ["server", "frontend", "db"],
-  devLimitEnvVar: "MYAPP_DEV_LIMIT",
   devServerPidFiles: [".local-data/dev-server.pid"],
   configFiles: [
     {
@@ -53,32 +52,33 @@ await runSetupWorktree({
         }),
     },
   ],
-  provisionDatabase: async () => {},
+  setupWorktreeData: async ({ currentWorktree }) => {
+    // Create per-worktree directories, copy seed data, start containers, etc.
+  },
   installAndBuild: async () => {},
   printSummary: ({ slot, branch, owner, ports }) =>
-    `Slot ${slot} (${branch}, ${owner}) — server :${ports.server}`,
+    `Slot ${slot} (${branch}${owner ? `, ${owner}` : ""}) — server :${ports.server}`,
 });
 ```
 
 ```ts
-import { runDevServer } from "@paleo/worktree-env";
+import { runDevServer, helpers } from "@paleo/worktree-env";
 
 await runDevServer({
   basePort: 8100,
-  devLimitEnvVar: "MYAPP_DEV_LIMIT",
+  devLimit: 5,
   servers: [
     {
       name: "dev",
-      command: "npm",
-      args: ["run", "dev"],
+      exec: { command: "npm", args: ["run", "dev"] },
+      port: helpers.readPortFromEnvFile(".env", "PORT"),
       pidFile: ".local-data/dev-server.pid",
       logFile: ".local-data/logs/dev-server.log",
       detectSuccess: (log) => log.includes("Server is ready on port"),
-      portConfig: { file: ".env", var: "PORT" },
     },
   ],
   printSummary: ({ slot, servers }) =>
-    `Dev servers started in slot ${slot.slot} (${slot.owner}): ${servers
+    `Dev servers started in slot ${slot.slot}${slot.owner ? ` (${slot.owner})` : ""}: ${servers
       .map((s) => `${s.server.name} :${s.port} (PID ${s.pid})`)
       .join(", ")}`,
 });

package/dist/cli.d.ts

@@ -2,11 +2,11 @@ export interface SetupArgs {
     help?: boolean;
     use?: string;
     create?: string;
-    self?: boolean;
+    here?: boolean;
     owner?: string;
     "set-owner"?: string;
     remove?: string;
-    "remove-self"?: boolean;
+    "remove-here"?: boolean;
     "no-remote-check"?: boolean;
     slot?: string;
     force?: boolean;

package/dist/cli.js

@@ -12,14 +12,14 @@ const SETUP_OPTIONS = {
         arg: "branch",
         description: "Create a new branch + worktree, then set up the local environment. If the branch already exists, appends a numeric suffix (-2, -3, ...)",
     },
-    self: {
+    here: {
         type: "boolean",
         description: "Set up the local environment in the current linked worktree",
     },
     owner: {
         type: "string",
         arg: "name",
-        description: 'Owner of the slot (free-form label, defaults to "default")',
+        description: "Owner of the slot (free-form label, optional)",
     },
     "set-owner": {
         type: "string",
@@ -31,13 +31,13 @@ const SETUP_OPTIONS = {
         arg: "branch",
         description: "Remove a worktree by branch name (stop dev server, free slot, delete directory)",
     },
-    "remove-self": {
+    "remove-here": {
         type: "boolean",
         description: "Remove the current linked worktree (same as --remove, but for the worktree you are in)",
     },
     "no-remote-check": {
         type: "boolean",
-        description: "Skip remote branch verification when removing (use with --remove or --remove-self)",
+        description: "Skip remote branch verification when removing (use with --remove or --remove-here)",
     },
     slot: {
         type: "string",
@@ -87,10 +87,10 @@ export function printDevServerHelp() {
     console.log(formatHelp("dev-server [options]", "Start, stop, or list background dev-server processes.", DEV_SERVER_OPTIONS));
 }
 export function isSetupMode(args) {
-    return args.use !== undefined || args.create !== undefined || Boolean(args.self);
+    return args.use !== undefined || args.create !== undefined || Boolean(args.here);
 }
 export function isRemoveMode(args) {
-    return args.remove !== undefined || Boolean(args["remove-self"]);
+    return args.remove !== undefined || Boolean(args["remove-here"]);
 }
 export function isSetOwnerMode(args) {
     return args["set-owner"] !== undefined;
@@ -99,24 +99,24 @@ export function validateSetupFlags(args) {
     const modeFlags = [
         args.use,
         args.create,
-        args.self,
+        args.here,
         isRemoveMode(args),
         isSetOwnerMode(args),
     ].filter(Boolean);
     if (modeFlags.length > 1) {
-        throw new ConfigError("Error: --use, --create, --self, --remove, --remove-self, and --set-owner are mutually exclusive.");
+        throw new ConfigError("Error: --use, --create, --here, --remove, --remove-here, and --set-owner are mutually exclusive.");
     }
-    if (args.remove !== undefined && args["remove-self"]) {
-        throw new ConfigError("Error: --remove and --remove-self are mutually exclusive.");
+    if (args.remove !== undefined && args["remove-here"]) {
+        throw new ConfigError("Error: --remove and --remove-here are mutually exclusive.");
     }
     if ((args.slot !== undefined || args.force) && !isSetupMode(args)) {
-        throw new ConfigError("Error: --slot and --force can only be used with --use, --create, or --self.");
+        throw new ConfigError("Error: --slot and --force can only be used with --use, --create, or --here.");
     }
     if (args.owner !== undefined && !isSetupMode(args)) {
-        throw new ConfigError("Error: --owner is only valid with --use, --create, or --self.");
+        throw new ConfigError("Error: --owner is only valid with --use, --create, or --here.");
     }
     if (args["no-remote-check"] && !isRemoveMode(args)) {
-        throw new ConfigError("Error: --no-remote-check is only valid with --remove or --remove-self.");
+        throw new ConfigError("Error: --no-remote-check is only valid with --remove or --remove-here.");
     }
 }
 export function validateDevServerFlags(args) {

package/dist/dev-server.d.ts

@@ -1,29 +1,38 @@
 import { type ResolvedSlot } from "./slots.js";
-export type PortConfig = {
-    file: string;
-    var: string;
-} | {
-    file: string;
-    jsonPath: string;
-};
+/** Configuration accepted by {@link runDevServer}. */
 export interface DevServerConfig {
+    /** Anchor port for the slot range. Used to synthesize the main worktree's slot. */
     basePort: number;
-    /** Maximum concurrent dev-servers across all worktrees. `0` means unlimited. */
-    devLimit: number;
+    /** Maximum concurrent dev-servers across all worktrees. Omit for no limit. */
+    devLimit?: number;
+    /** One entry per process to spawn. Started in array order. */
     servers: ServerDescriptor[];
+    /** Hook invoked once before any dev-server is spawned (e.g. `docker compose up -d`). */
     ensureInfrastructure?: () => Promise<void> | void;
+    /** Builds the post-start summary printed to stdout. Defaults to a generic layout. */
     printSummary?: (ctx: DevServerSummaryContext) => string;
 }
+/** Describes one process to spawn. */
 export interface ServerDescriptor {
+    /** Short label used in logs and the registry. */
     name: string;
-    command: string;
-    args: string[];
+    /** Command and arguments passed to `child_process.spawn`. */
+    exec: {
+        command: string;
+        args: string[];
+    };
+    /** Port the process will listen on. Use `helpers.readPortFromEnvFile` / `readPortFromJsonFile` to read it from a config file. */
+    port: number;
+    /** Path (relative to cwd) where the spawned PID is written. */
     pidFile: string;
+    /** Path (relative to cwd) where stdout+stderr are tee'd. */
     logFile: string;
+    /** Returns `true` once the log content indicates the server is ready. */
     detectSuccess: (logContent: string) => boolean;
+    /** Returns a non-empty marker string when the log content indicates a fatal error, or `false` otherwise. */
     detectError?: (logContent: string) => string | false;
-    portConfig: PortConfig;
 }
+/** Context passed to {@link DevServerConfig.printSummary}. */
 export interface DevServerSummaryContext {
     slot: ResolvedSlot;
     servers: {

package/dist/dev-server.js

@@ -1,5 +1,5 @@
 import { spawn } from "node:child_process";
-import { closeSync, existsSync, mkdirSync, openSync, readFileSync, writeFileSync } from "node:fs";
+import { closeSync, mkdirSync, openSync, writeFileSync } from "node:fs";
 import { createConnection } from "node:net";
 import { dirname, join } from "node:path";
 import { parseDevServerArgs, printDevServerHelp, validateDevServerFlags, } from "./cli.js";
@@ -9,48 +9,6 @@ import { awaitAllReady, handleStartupFailure } from "./log-polling.js";
 import { cleanupPidFile, isProcessAlive, readPid, stopByPidFile } from "./process-control.js";
 import { resolveCurrentSlot } from "./slots.js";
 import { detectWorktree } from "./worktree.js";
-function readEnvFileVar(filePath, varName) {
-    const content = readFileSync(filePath, "utf-8");
-    const match = content.match(new RegExp(`^${varName}=(.+)`, "m"));
-    if (!match) {
-        console.error(`Error: ${varName} not found in ${filePath}.`);
-        process.exit(1);
-    }
-    return match[1].trim();
-}
-function readJsonPath(filePath, jsonPath) {
-    const content = readFileSync(filePath, "utf-8");
-    const data = JSON.parse(content);
-    const segments = jsonPath.split(".");
-    let cur = data;
-    for (const seg of segments) {
-        if (cur === null || cur === undefined || typeof cur !== "object") {
-            console.error(`Error: ${jsonPath} not found in ${filePath}.`);
-            process.exit(1);
-        }
-        cur = cur[seg];
-    }
-    if (cur === undefined || cur === null) {
-        console.error(`Error: ${jsonPath} not found in ${filePath}.`);
-        process.exit(1);
-    }
-    return String(cur);
-}
-function readPortFromConfig(portConfig) {
-    if (!existsSync(portConfig.file)) {
-        console.error(`Error: ${portConfig.file} not found. Run setup-worktree first.`);
-        process.exit(1);
-    }
-    const raw = "var" in portConfig
-        ? readEnvFileVar(portConfig.file, portConfig.var)
-        : readJsonPath(portConfig.file, portConfig.jsonPath);
-    const port = Number(raw);
-    if (!Number.isFinite(port)) {
-        console.error(`Error: invalid port "${raw}" in ${portConfig.file}.`);
-        process.exit(1);
-    }
-    return port;
-}
 function isPortBusy(port) {
     return new Promise((resolve) => {
         const socket = createConnection({ port, host: "127.0.0.1" });
@@ -72,7 +30,7 @@ function spawnServer(server) {
     mkdirSync(dirname(server.logFile), { recursive: true });
     mkdirSync(dirname(server.pidFile), { recursive: true });
     const logFd = openSync(server.logFile, "w");
-    const child = spawn(server.command, server.args, {
+    const child = spawn(server.exec.command, server.exec.args, {
         detached: true,
         stdio: ["ignore", logFd, logFd],
     });
@@ -130,7 +88,7 @@ export async function runDevServer(config) {
 async function start(config, mainWorktree) {
     const limit = config.devLimit;
     const active = pruneAndPersist(mainWorktree).servers;
-    if (limit > 0 && active.length >= limit) {
+    if (limit !== undefined && active.length >= limit) {
         console.error(`Error: dev-server cap reached (${active.length}/${limit}). Active dev-servers:`);
         printActiveServers(active);
         console.error("Run `dev:down` in another worktree, or `dev:down --all`.");
@@ -138,7 +96,7 @@ async function start(config, mainWorktree) {
     }
     const serverPorts = config.servers.map((server) => [
         server,
-        readPortFromConfig(server.portConfig),
+        server.port,
     ]);
     const busyResults = await Promise.all(serverPorts.map(([, port]) => isPortBusy(port)));
     let anyBusy = false;
@@ -213,7 +171,8 @@ async function start(config, mainWorktree) {
 }
 function defaultPrintSummary(slot, servers, ports, pids) {
     console.log("\nDev servers started!");
-    console.log(`  Worktree: slot ${slot.slot}, owner ${slot.owner}`);
+    const ownerSuffix = slot.owner ? `, owner ${slot.owner}` : "";
+    console.log(`  Worktree: slot ${slot.slot}${ownerSuffix}`);
     servers.forEach((server, i) => {
         const url = `http://localhost:${ports[i]}/`;
         const logPath = join(process.cwd(), server.logFile);

package/dist/dev-servers-registry.d.ts

@@ -4,7 +4,7 @@ export interface DevServerEntry {
     slot: number;
     worktree: string;
     branch: string;
-    owner: string;
+    owner?: string;
     pids: Record<string, number>;
     startedAt: string;
 }

package/dist/dev-servers-registry.js

@@ -60,7 +60,8 @@ function formatEntry(entry) {
     const pids = Object.entries(entry.pids)
         .map(([name, pid]) => `${name}=${pid}`)
         .join(",");
-    return `  slot ${entry.slot}  branch=${entry.branch}  owner=${entry.owner}  pids=${pids}  startedAt=${entry.startedAt}  worktree=${entry.worktree}`;
+    const ownerPart = entry.owner ? `  owner=${entry.owner}` : "";
+    return `  slot ${entry.slot}  branch=${entry.branch}${ownerPart}  pids=${pids}  startedAt=${entry.startedAt}  worktree=${entry.worktree}`;
 }
 export function printActiveServers(active) {
     const sorted = [...active].sort((a, b) => a.slot - b.slot);
@@ -86,7 +87,8 @@ export async function stopAllRegistered(input) {
         return;
     }
     for (const entry of data.servers) {
-        console.log(`Stopping slot ${entry.slot} (${entry.branch}, owner=${entry.owner})...`);
+        const ownerSuffix = entry.owner ? `, owner=${entry.owner}` : "";
+        console.log(`Stopping slot ${entry.slot} (${entry.branch}${ownerSuffix})...`);
         for (const [name, pid] of Object.entries(entry.pids)) {
             if (!isProcessAlive(pid))
                 continue;

package/dist/helpers.d.ts

@@ -1,5 +1,15 @@
 export declare function patchEnvFile(content: string, patches: Record<string, string>): string;
 export declare function extractHost(content: string, key: string, fallback?: string): string;
+/**
+ * Reads `<varName>=<value>` from a dotenv-style file and parses it as a port.
+ * Exits with code 1 on missing file, missing variable, or non-numeric value.
+ */
+export declare function readPortFromEnvFile(file: string, varName: string): number;
+/**
+ * Reads a dotted path (e.g. `server.port`) from a JSON file and parses it as a port.
+ * Exits with code 1 on missing file, missing path, or non-numeric value.
+ */
+export declare function readPortFromJsonFile(file: string, jsonPath: string): number;
 export interface CopyAndPatchCtx {
     currentWorktree: string;
     mainWorktree: string;

package/dist/helpers.js

@@ -18,6 +18,55 @@ export function extractHost(content, key, fallback = "localhost") {
     const m = content.match(re);
     return m ? m[1] : fallback;
 }
+/**
+ * Reads `<varName>=<value>` from a dotenv-style file and parses it as a port.
+ * Exits with code 1 on missing file, missing variable, or non-numeric value.
+ */
+export function readPortFromEnvFile(file, varName) {
+    if (!existsSync(file)) {
+        console.error(`Error: ${file} not found. Run setup-worktree first.`);
+        process.exit(1);
+    }
+    const content = readFileSync(file, "utf-8");
+    const match = content.match(new RegExp(`^${varName}=(.+)`, "m"));
+    if (!match) {
+        console.error(`Error: ${varName} not found in ${file}.`);
+        process.exit(1);
+    }
+    return toPort(match[1].trim(), file);
+}
+/**
+ * Reads a dotted path (e.g. `server.port`) from a JSON file and parses it as a port.
+ * Exits with code 1 on missing file, missing path, or non-numeric value.
+ */
+export function readPortFromJsonFile(file, jsonPath) {
+    if (!existsSync(file)) {
+        console.error(`Error: ${file} not found. Run setup-worktree first.`);
+        process.exit(1);
+    }
+    const data = JSON.parse(readFileSync(file, "utf-8"));
+    let cur = data;
+    for (const seg of jsonPath.split(".")) {
+        if (cur === null || cur === undefined || typeof cur !== "object") {
+            console.error(`Error: ${jsonPath} not found in ${file}.`);
+            process.exit(1);
+        }
+        cur = cur[seg];
+    }
+    if (cur === undefined || cur === null) {
+        console.error(`Error: ${jsonPath} not found in ${file}.`);
+        process.exit(1);
+    }
+    return toPort(String(cur), file);
+}
+function toPort(raw, file) {
+    const port = Number(raw);
+    if (!Number.isFinite(port)) {
+        console.error(`Error: invalid port "${raw}" in ${file}.`);
+        process.exit(1);
+    }
+    return port;
+}
 export function copyAndPatchFile(ctx, relPath, patchFn, label, force, required = false) {
     const targetPath = join(ctx.currentWorktree, relPath);
     const sourcePath = join(ctx.mainWorktree, relPath);

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 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 { DevServerConfig, DevServerSummaryContext, ServerDescriptor, } from "./dev-server.js";
 export type { ResolvedSlot } from "./slots.js";
 import * as helpers from "./helpers.js";
 export { helpers };

package/dist/setup-worktree.d.ts

@@ -1,51 +1,76 @@
+/** Context passed to setup-time hooks (`setupWorktreeData`, `installAndBuild`, `afterDatabase`). */
 export interface SetupContext {
     currentWorktree: string;
     mainWorktree: string;
     slot: number;
     branch: string;
-    owner: string;
+    owner?: string;
     ports: Record<string, number>;
     force: boolean;
     verbose: boolean;
 }
+/** Context passed to {@link ConfigFileEntry.patch}. */
 export interface PatchContext {
     slot: number;
     ports: Record<string, number>;
     mainWorktree: string;
     currentWorktree: string;
 }
+/** One config file copied from the main worktree and patched per slot. */
 export interface ConfigFileEntry {
+    /** Path relative to the worktree root. Same path is read from main and written to current. */
     path: string;
+    /** Returns the patched content given the source content and the slot's ports. */
     patch: (content: string, ctx: PatchContext) => string;
+    /** When `true`, abort if the source file is missing in the main worktree. Defaults to `false`. */
     required?: boolean;
 }
+/** Context passed to {@link SetupWorktreeConfig.printSummary}. */
 export interface SummaryContext {
     slot: number;
     branch: string;
-    owner: string;
+    owner?: string;
     ports: Record<string, number>;
     currentWorktree: string;
     mainWorktree: string;
 }
+/** Context passed to {@link SetupWorktreeConfig.teardownInfrastructure}. */
 export interface TeardownContext {
     worktree: string;
     mainWorktree: string;
     verbose: boolean;
 }
+/** Configuration accepted by {@link runSetupWorktree}. */
 export interface SetupWorktreeConfig {
+    /** Anchor port for the slot range. Slots are derived from this value. */
     basePort: number;
+    /** Distance between consecutive slots. Defaults to `10`. */
     portStep?: number;
+    /** Maximum number of slots. Defaults to `9`. */
     maxSlotCount?: number;
+    /** Custom port computation; takes precedence over `portNames`. */
     ports?: (slot: number) => Record<string, number>;
+    /** Named offsets `[name0, name1, ...]` mapped to `slot+0`, `slot+1`, ... Required if `ports` is omitted. */
     portNames?: string[];
-    perWorktreeDirs?: string[];
+    /** Directories symlinked from the main worktree. Defaults to `[".local", ".plans"]`. */
     sharedDirs?: string[];
+    /** PID files written by `dev-server`, used by `--remove` to stop processes before teardown. */
     devServerPidFiles: string[];
+    /** Config files copied from the main worktree and patched per slot. */
     configFiles: ConfigFileEntry[];
-    provisionDatabase: (ctx: SetupContext) => Promise<void> | void;
+    /**
+     * Runs after symlinks and config files. Owns per-worktree data setup:
+     * create any required directories (e.g. `.local-data/...`), copy or
+     * provision databases / file storage, start infrastructure containers.
+     */
+    setupWorktreeData: (ctx: SetupContext) => Promise<void> | void;
+    /** Tears down infrastructure on `--remove` (e.g. `docker compose down -v`). Best-effort; errors should be swallowed. */
     teardownInfrastructure?: (ctx: TeardownContext) => Promise<void> | void;
+    /** Runs after `setupWorktreeData`. Typically `npm install && npm run build`. */
     installAndBuild: (ctx: SetupContext) => Promise<void> | void;
+    /** Runs after `installAndBuild`. Typically migrations and seeds. */
     afterDatabase?: (ctx: SetupContext) => Promise<void> | void;
+    /** Builds the post-setup summary printed to stdout. */
     printSummary: (ctx: SummaryContext) => string;
 }
 export declare function runSetupWorktree(config: SetupWorktreeConfig): Promise<void>;

package/dist/setup-worktree.js

@@ -87,8 +87,6 @@ async function runSetup(args, ctx, run, config) {
         .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;
@@ -102,7 +100,7 @@ async function runSetup(args, ctx, run, config) {
         force,
         verbose: run.verbose,
     };
-    await config.provisionDatabase(setupContext);
+    await config.setupWorktreeData(setupContext);
     await config.installAndBuild(setupContext);
     if (config.afterDatabase)
         await config.afterDatabase(setupContext);
@@ -122,11 +120,6 @@ function ensureWorktree(args, ctx, run) {
         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);
@@ -154,8 +147,8 @@ function generateConfigFiles(ctx, entries, slot, ports, force, log) {
         }), entry.path, force, entry.required ?? false);
     }
 }
-function resolveRemoveTarget(args, ctx, registry, removeSelf) {
-    if (removeSelf) {
+function resolveRemoveTarget(args, ctx, registry, removeHere) {
+    if (removeHere) {
         if (ctx.isMainWorktree) {
             console.error("Error: Cannot remove the main worktree.");
             process.exit(1);
@@ -170,7 +163,7 @@ function resolveRemoveTarget(args, ctx, registry, removeSelf) {
             slotPort: entry[0],
             branch: entry[1].branch,
             worktreePath: ctx.currentWorktree,
-            owner: entry[1].owner ?? "default",
+            owner: entry[1].owner,
         };
     }
     const branch = args.remove ?? "";
@@ -181,10 +174,10 @@ function resolveRemoveTarget(args, ctx, registry, removeSelf) {
     }
     const worktreePath = entry[1].worktree;
     if (resolve(ctx.currentWorktree) === resolve(worktreePath)) {
-        console.error("Error: You are currently in this worktree. Use --remove-self instead.");
+        console.error("Error: You are currently in this worktree. Use --remove-here instead.");
         process.exit(1);
     }
-    return { slotPort: entry[0], branch, worktreePath, owner: entry[1].owner ?? "default" };
+    return { slotPort: entry[0], branch, worktreePath, owner: entry[1].owner };
 }
 async function stopDevServerByPidFiles(worktreePath, pidFiles, log) {
     for (const pidFileRel of pidFiles) {
@@ -215,13 +208,13 @@ async function stopDevServerByPidFiles(worktreePath, pidFiles, log) {
 }
 async function handleRemove(args, ctx, run, config) {
     const log = makeLog(run.verbose);
-    const removeSelf = Boolean(args["remove-self"]);
+    const removeHere = Boolean(args["remove-here"]);
     const registry = readSlots(ctx.mainWorktree);
-    const target = resolveRemoveTarget(args, ctx, registry, removeSelf);
+    const target = resolveRemoveTarget(args, ctx, registry, removeHere);
     if (!args["no-remote-check"]) {
         verifyBranchAbsentFromRemote(target.branch, run);
     }
-    const ownerSuffix = target.owner !== "default" ? `, owner ${target.owner}` : "";
+    const ownerSuffix = target.owner ? `, owner ${target.owner}` : "";
     if (!existsSync(target.worktreePath)) {
         console.warn(`Warning: Worktree directory ${target.worktreePath} not found. Cleaning up registry only.`);
         delete registry.slots[target.slotPort];
@@ -240,17 +233,17 @@ async function handleRemove(args, ctx, run, config) {
     delete registry.slots[target.slotPort];
     writeSlots(ctx.mainWorktree, registry);
     removeDevServerEntryByWorktree(ctx.mainWorktree, target.worktreePath);
-    if (removeSelf) {
+    if (removeHere) {
         process.chdir(ctx.mainWorktree);
     }
     removeWorktree(target.worktreePath, run);
     console.log(`Removed worktree for branch "${target.branch}" (slot ${target.slotPort}${ownerSuffix}).`);
-    if (removeSelf) {
+    if (removeHere) {
         console.log(`Now run: cd ${ctx.mainWorktree}`);
     }
 }
 function handleSetOwnerMode(args, ctx) {
-    const newOwner = args["set-owner"] ?? "default";
+    const newOwner = args["set-owner"];
     const { slotPort } = handleSetOwner({
         newOwner,
         currentWorktree: ctx.currentWorktree,
@@ -265,7 +258,10 @@ function handleSetOwnerMode(args, ctx) {
         const resolvedCurrent = resolve(ctx.currentWorktree);
         for (const server of data.servers) {
             if (resolve(server.worktree) === resolvedCurrent) {
-                server.owner = newOwner;
+                if (newOwner !== undefined)
+                    server.owner = newOwner;
+                else
+                    delete server.owner;
                 changed = true;
             }
         }
@@ -274,5 +270,5 @@ function handleSetOwnerMode(args, ctx) {
             writeFileSync(devServersPath, `${JSON.stringify(data, undefined, 2)}\n`);
         }
     }
-    console.log(`Owner for slot ${slotPort}: ${newOwner}`);
+    console.log(`Owner for slot ${slotPort}: ${newOwner ?? "(none)"}`);
 }

package/dist/slots.d.ts

@@ -4,7 +4,7 @@ export declare const SLOTS_FILE = ".local/worktrees/slots.json";
 export interface SlotEntry {
     worktree: string;
     branch: string;
-    owner: string;
+    owner?: string;
 }
 export interface SlotsRegistry {
     slots: Record<string, SlotEntry>;
@@ -13,7 +13,7 @@ export interface ResolvedSlot {
     slot: number;
     worktree: string;
     branch: string;
-    owner: string;
+    owner?: string;
 }
 export declare function readSlots(mainWorktree: string): SlotsRegistry;
 export declare function writeSlots(mainWorktree: string, registry: SlotsRegistry): void;
@@ -34,7 +34,7 @@ export interface RegisterSlotInput {
 }
 export declare function resolveAndRegisterSlot(input: RegisterSlotInput): {
     port: number;
-    owner: string;
+    owner: string | undefined;
 };
 export declare function validateSlotAvailability(slotArg: string | undefined, ctx: {
     currentWorktree: string;
@@ -45,12 +45,12 @@ 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;
+    newOwner: string | undefined;
     currentWorktree: string;
     mainWorktree: string;
     isMainWorktree: boolean;
 }
 export declare function handleSetOwner(input: SetOwnerInput): {
     slotPort: string;
-    owner: string;
+    owner: string | undefined;
 };

package/dist/slots.js

@@ -44,21 +44,14 @@ 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)] = {
+    const owner = input.requestedOwner ?? existing?.owner;
+    const entry = {
         worktree: input.currentWorktree,
         branch: input.branch,
-        owner,
     };
+    if (owner !== undefined)
+        entry.owner = owner;
+    registry.slots[String(port)] = entry;
     writeSlots(input.mainWorktree, registry);
     return { port, owner };
 }
@@ -90,7 +83,7 @@ export function lookupSlotForCwd() {
                 slot: Number(port),
                 worktree: entry.worktree,
                 branch: entry.branch,
-                owner: entry.owner ?? "default",
+                owner: entry.owner,
             };
         }
     }
@@ -103,7 +96,7 @@ export function synthesizeMainSlot(basePort) {
     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" };
+    return { slot: basePort, worktree: cwd, branch };
 }
 export function resolveCurrentSlot(basePort) {
     const slot = lookupSlotForCwd() ?? synthesizeMainSlot(basePort);
@@ -126,7 +119,13 @@ export function handleSetOwner(input) {
         process.exit(1);
     }
     const [slotPort, slotData] = entry;
-    registry.slots[slotPort] = { ...slotData, owner: input.newOwner };
+    const updated = {
+        worktree: slotData.worktree,
+        branch: slotData.branch,
+    };
+    if (input.newOwner !== undefined)
+        updated.owner = input.newOwner;
+    registry.slots[slotPort] = updated;
     writeSlots(input.mainWorktree, registry);
     return { slotPort, owner: input.newOwner };
 }

package/dist/worktree.d.ts

@@ -16,6 +16,6 @@ export declare function getCurrentBranch(worktreePath: string): string;
 export declare function enforceWorktreeMode(args: {
     use?: string;
     create?: string;
-    self?: boolean;
+    here?: boolean;
 }, ctx: WorktreeContext): void;
 export declare function removeWorktree(worktreePath: string, run: RunCtx): void;

package/dist/worktree.js

@@ -80,9 +80,9 @@ export function enforceWorktreeMode(args, ctx) {
             process.exit(1);
         }
     }
-    else if (args.self) {
+    else if (args.here) {
         if (ctx.isMainWorktree) {
-            console.error("Error: --self must be run from a linked worktree, not from the main worktree.");
+            console.error("Error: --here must be run from a linked worktree, not from the main worktree.");
             process.exit(1);
         }
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@paleo/worktree-env",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "Worktree-based concurrent local environment kernel.",
   "keywords": [
     "worktree",
@@ -33,8 +33,10 @@
   "scripts": {
     "build": "tsc",
     "clear": "rimraf dist/*",
+    "lint": "biome check",
     "test": "vitest run",
-    "test:watch": "vitest"
+    "test:watch": "vitest",
+    "prepublishOnly": "npm run clear && npm run build && npm run lint && npm run test"
   },
   "devDependencies": {
     "@types/node": "~24.12.3",