@zjaaal/artemis 0.0.0-stage → 0.1.2

package/dist/kits/worktrees/lock.d.ts

@@ -0,0 +1,7 @@
+import type { WithLockFn } from './models.js';
+/**
+ * Runs `work` while holding `<stateFile>.lock`, so that two processes registering at once cannot
+ * both read the registry, pick the same slot and overwrite each other. Synchronous like the rest
+ * of the kit: it retries every few milliseconds, and takes over a lock whose process has died.
+ */
+export declare const withLock: WithLockFn;

package/dist/kits/worktrees/lock.js

@@ -0,0 +1,104 @@
+import path from 'node:path';
+import { createExclusive, makeDirectory, modifiedAt, readTextIfExists, removeFile } from '../../edges/files.js';
+import { CommandError } from '../../errors/errors.js';
+import { LOCK_GRACE_MS, LOCK_POLL_MS, LOCK_SUFFIX, TAKEOVER_STALE_MS, TAKEOVER_SUFFIX } from './constants.js';
+/** The process id a lock names (`<pid> <token>`), or undefined when it holds none yet. */
+const holderPid = (content) => Number.parseInt(content, 10) || undefined;
+/** How long ago a file was written, by the injected clock; undefined when it is not there. */
+function ageOf(file, edges) {
+    const written = modifiedAt(file);
+    return written === undefined ? undefined : edges.now() - written;
+}
+/** A lock with no process id in it is probably being written right now: give it a moment. */
+const isBeingWritten = (lock, edges) => (ageOf(lock, edges) ?? LOCK_GRACE_MS) < LOCK_GRACE_MS;
+function isHeld(lock, observed, edges) {
+    const pid = holderPid(observed);
+    return pid === undefined ? isBeingWritten(lock, edges) : edges.isProcessAlive(pid);
+}
+function lockedMessage(observed) {
+    const pid = holderPid(observed);
+    return `The instance registry is locked by ${pid === undefined ? 'another process' : `process ${pid}`}.`;
+}
+/** The lock is held by someone alive: wait a little, or give up once the deadline has passed. */
+function waitOrFail({ lock, deadline, edges }, observed) {
+    if (edges.now() > deadline) {
+        throw new CommandError(lockedMessage(observed), {
+            hint: `If no other command is running, delete ${lock}.`
+        });
+    }
+    edges.pause(LOCK_POLL_MS);
+}
+/** Whoever was taking over died half way: its guard is old enough to clear. */
+function clearAbandonedGuard(guard, edges) {
+    if ((ageOf(guard, edges) ?? 0) > TAKEOVER_STALE_MS) {
+        removeFile(guard);
+    }
+}
+/**
+ * Removes a lock whose holder is gone. Only one process at a time may do it (the guard), and it
+ * removes the lock only if it still holds exactly what was judged stale: if someone else got there
+ * first and made a new lock, that one is left alone. While the stale file exists nobody else can
+ * create a lock, so nothing can replace it between that check and the removal.
+ */
+function takeOver({ lock, ownership, edges }, observed) {
+    const guard = `${lock}${TAKEOVER_SUFFIX}`;
+    if (!createExclusive(guard, ownership)) {
+        clearAbandonedGuard(guard, edges);
+        edges.pause(LOCK_POLL_MS);
+        return;
+    }
+    try {
+        if (readTextIfExists(lock) === observed) {
+            removeFile(lock);
+        }
+    }
+    finally {
+        removeFile(guard);
+    }
+}
+/** The lock exists: wait for its holder, or take it over if the holder is gone. */
+function contend(attempt) {
+    const observed = readTextIfExists(attempt.lock);
+    // Released while we looked: just try to create it again.
+    if (observed === undefined) {
+        return;
+    }
+    if (isHeld(attempt.lock, observed, attempt.edges)) {
+        waitOrFail(attempt, observed);
+    }
+    else {
+        takeOver(attempt, observed);
+    }
+}
+function acquire(attempt) {
+    makeDirectory(path.dirname(attempt.lock));
+    while (!createExclusive(attempt.lock, attempt.ownership)) {
+        contend(attempt);
+    }
+}
+/** Gives the lock back, but only if it is still ours: never delete one another process holds. */
+function release({ lock, ownership }) {
+    if (readTextIfExists(lock) === ownership) {
+        removeFile(lock);
+    }
+}
+/**
+ * Runs `work` while holding `<stateFile>.lock`, so that two processes registering at once cannot
+ * both read the registry, pick the same slot and overwrite each other. Synchronous like the rest
+ * of the kit: it retries every few milliseconds, and takes over a lock whose process has died.
+ */
+export const withLock = (stateFile, work, edges) => {
+    const attempt = {
+        lock: `${stateFile}${LOCK_SUFFIX}`,
+        ownership: `${edges.pid} ${edges.token()}`,
+        deadline: edges.now() + edges.timeoutMs,
+        edges
+    };
+    acquire(attempt);
+    try {
+        return work();
+    }
+    finally {
+        release(attempt);
+    }
+};

package/dist/kits/worktrees/models.d.ts

@@ -0,0 +1,123 @@
+export type WorktreeMeta = Record<string, unknown>;
+/** What the registry file stores for a worktree. `root` is null for a detached instance. */
+export type WorktreeRecord = {
+    slot: number;
+    root: string | null;
+    meta?: WorktreeMeta;
+};
+export type WorktreeRecords = Record<string, WorktreeRecord>;
+/** One instance of the app: a stable slot, its ports and color. */
+export type WorktreeInstance = {
+    name: string;
+    slot: number;
+    root: string | null;
+    isMain: boolean;
+    meta: WorktreeMeta;
+    color: string;
+    ports: Record<string, number>;
+};
+export type IsCheckoutFn = (root: string) => boolean;
+export type NowFn = () => number;
+export type IsProcessAliveFn = (pid: number) => boolean;
+export type PauseFn = (ms: number) => void;
+export type TokenFn = () => string;
+/** The clock, process liveness and waiting, injected so lock tests never sleep. */
+export type LockEdges = {
+    /** The process id written into the lock file. */
+    pid: number;
+    /** Tells this holder apart from any other holder with the same pid. */
+    token: TokenFn;
+    now: NowFn;
+    isProcessAlive: IsProcessAliveFn;
+    pause: PauseFn;
+    timeoutMs: number;
+};
+export type WorktreesOptions = {
+    /** JSON file the registry is kept in (the app's data folder). */
+    stateFile: string;
+    /** Path of the main checkout (slot 0). */
+    mainCheckout: string;
+    /** Base ports, shifted by `slot * slotStep`. */
+    ports: Record<string, number>;
+    /** Whether a git root is a checkout of this app; other repos count as outside any checkout. */
+    isCheckout?: IsCheckoutFn;
+    /** Variable that pins the instance by name, overriding the folder. */
+    envVar?: string;
+    /** Port shift per slot. Default 100. */
+    slotStep?: number;
+    /** One per slot, cycling. */
+    colors?: readonly string[];
+    /** Name of the main checkout's instance. Default "main". */
+    mainName?: string;
+    /** Environment to read `envVar` from. Default: the process environment. */
+    env?: NodeJS.ProcessEnv;
+    /** Clock for the registry lock. Default: `Date.now`. */
+    now?: NowFn;
+    /** Process liveness for the registry lock. Default: `process.kill(pid, 0)`. */
+    isProcessAlive?: IsProcessAliveFn;
+    /** How the lock waits between retries. Default: a blocking wait. */
+    pause?: PauseFn;
+    /** How long to wait for the lock before giving up. Default 10 seconds. */
+    lockTimeoutMs?: number;
+};
+export type CurrentOptions = {
+    cwd?: string;
+};
+export type EnsureOptions = {
+    cwd?: string;
+    root?: string;
+    name?: string;
+};
+export type EnsureDetachedOptions = {
+    name: string;
+    meta?: WorktreeMeta;
+};
+export type Worktrees = {
+    /** Every instance: the main one first, then the registered worktrees by slot. */
+    list: () => WorktreeInstance[];
+    get: (name: string) => WorktreeInstance;
+    current: (options?: CurrentOptions) => WorktreeInstance;
+    ensure: (options?: EnsureOptions) => WorktreeInstance;
+    ensureDetached: (options: EnsureDetachedOptions) => WorktreeInstance;
+    remove: (name: string) => void;
+};
+export type DefineWorktreesFn = (options: WorktreesOptions) => Worktrees;
+export type ToWorktreeNameFn = (folder: string) => string;
+/** One acquisition of the registry lock: where it is, who is asking, and when to give up. */
+export type LockAttempt = {
+    lock: string;
+    ownership: string;
+    deadline: number;
+    edges: LockEdges;
+};
+export type WithLockFn = <TResult>(stateFile: string, work: () => TResult, edges: LockEdges) => TResult;
+/** Options with their defaults applied, and the registry store they work on. */
+export type KitConfig = {
+    stateFile: string;
+    mainRoot: string;
+    ports: Record<string, number>;
+    isCheckout: IsCheckoutFn;
+    envVar: string | undefined;
+    slotStep: number;
+    colors: readonly string[];
+    mainName: string;
+    env: NodeJS.ProcessEnv;
+    store: RegistryStore;
+    lock: LockEdges;
+};
+/** What turns a record into an instance. */
+export type InstanceConfig = Pick<KitConfig, 'ports' | 'slotStep' | 'colors'>;
+export type RegistryStore = {
+    read: () => WorktreeRecords;
+    write: (records: WorktreeRecords) => void;
+};
+export type CreateRegistryStoreFn = (stateFile: string) => RegistryStore;
+export type DescribeInstanceFn = (config: InstanceConfig, name: string, record: WorktreeRecord) => WorktreeInstance;
+export type NextFreeSlotFn = (records: WorktreeRecords) => number;
+export type RecordOfFn = (records: WorktreeRecords, name: string) => WorktreeRecord | undefined;
+/** A name that is not taken by a registered worktree or by the main checkout. */
+export type UniqueNameFn = (wanted: string, base: string, taken: NameCheck) => string;
+export type NameCheck = (name: string) => boolean;
+export type IsValidNameFn = (name: string) => boolean;
+/** Something that runs with its own arguments, such as a registry operation. */
+export type Operation<TArgs extends unknown[], TResult> = (...args: TArgs) => TResult;

package/dist/kits/worktrees/models.js

@@ -0,0 +1,2 @@
+// Types of the worktrees kit: no type lives in a logic file.
+export {};

package/dist/kits/worktrees/names.d.ts

@@ -0,0 +1,5 @@
+import type { IsValidNameFn, ToWorktreeNameFn } from './models.js';
+/** "Core_Feat X" -> "core-feat-x": a folder name turned into a valid instance name. */
+export declare const toWorktreeName: ToWorktreeNameFn;
+/** Lowercase letters, digits and dashes, starting with a letter or digit, within the length limit. */
+export declare const isValidName: IsValidNameFn;

package/dist/kits/worktrees/names.js

@@ -0,0 +1,9 @@
+import { EDGE_DASHES, INVALID_NAME_RUN, MAX_INSTANCE_NAME_LENGTH, VALID_NAME } from './constants.js';
+/** "Core_Feat X" -> "core-feat-x": a folder name turned into a valid instance name. */
+export const toWorktreeName = (folder) => folder
+    .toLowerCase()
+    .replace(INVALID_NAME_RUN, '-')
+    .replace(EDGE_DASHES, '')
+    .slice(0, MAX_INSTANCE_NAME_LENGTH);
+/** Lowercase letters, digits and dashes, starting with a letter or digit, within the length limit. */
+export const isValidName = (name) => VALID_NAME.test(name);

package/dist/kits/worktrees/queries.d.ts

@@ -0,0 +1,20 @@
+import { CommandError } from '../../errors/errors.js';
+import type { CurrentOptions, KitConfig, WorktreeInstance } from './models.js';
+/** The instance pinned by the app's env variable, if the app has one and it is set. */
+export declare const pinnedName: ({ envVar, env }: KitConfig) => string | undefined;
+export declare const noInstanceError: (name: string) => CommandError;
+/** The main checkout is slot 0 and needs no registration. */
+export declare const mainInstance: (config: KitConfig) => WorktreeInstance;
+/** Every instance: the main one first, then the registered worktrees by slot. */
+export declare function listInstances(config: KitConfig): WorktreeInstance[];
+export declare function getInstance(config: KitConfig, name: string): WorktreeInstance;
+/** The checkout root containing `cwd`, or null when it is not a checkout of this app. */
+export declare function rootOf(config: KitConfig, cwd: string): string | null;
+/** The instance of a checkout root: the main one, or the registered worktree there. */
+export declare function instanceAt(config: KitConfig, root: string): WorktreeInstance | undefined;
+/**
+ * The instance for where the app runs: the env variable's if set; else the checkout containing
+ * `cwd` (main -> main, registered -> its instance); outside any checkout, main. A worktree that
+ * is not registered throws, so nothing lands on another worktree's instance by mistake.
+ */
+export declare function currentInstance(config: KitConfig, { cwd }?: CurrentOptions): WorktreeInstance;

package/dist/kits/worktrees/queries.js

@@ -0,0 +1,61 @@
+import { gitRoot } from './git.js';
+import { workingDirectory } from '../../edges/system.js';
+import { CommandError } from '../../errors/errors.js';
+import { MAIN_SLOT } from './constants.js';
+import { describeInstance } from './instances.js';
+/** The instance pinned by the app's env variable, if the app has one and it is set. */
+export const pinnedName = ({ envVar, env }) => envVar ? env[envVar] || undefined : undefined;
+export const noInstanceError = (name) => new CommandError(`There is no instance named "${name}".`, {
+    hint: 'Registered instances are listed by the app; a worktree registers on its first start.'
+});
+/** The main checkout is slot 0 and needs no registration. */
+export const mainInstance = (config) => describeInstance(config, config.mainName, { slot: MAIN_SLOT, root: config.mainRoot });
+/** Every instance: the main one first, then the registered worktrees by slot. */
+export function listInstances(config) {
+    const registered = Object.entries(config.store.read())
+        .map(([name, record]) => describeInstance(config, name, record))
+        .sort((a, b) => a.slot - b.slot);
+    return [mainInstance(config), ...registered];
+}
+export function getInstance(config, name) {
+    const found = listInstances(config).find((instance) => instance.name === name);
+    if (!found) {
+        throw noInstanceError(name);
+    }
+    return found;
+}
+/** The checkout root containing `cwd`, or null when it is not a checkout of this app. */
+export function rootOf(config, cwd) {
+    const root = gitRoot(cwd);
+    return root && config.isCheckout(root) ? root : null;
+}
+/** The instance of a checkout root: the main one, or the registered worktree there. */
+export function instanceAt(config, root) {
+    if (root === config.mainRoot) {
+        return mainInstance(config);
+    }
+    return listInstances(config).find((instance) => !instance.isMain && instance.root === root);
+}
+const unregisteredHint = (envVar) => `Register it first (the app's start command does that)${envVar ? `, or set ${envVar} to use another instance` : ''}.`;
+/**
+ * The instance for where the app runs: the env variable's if set; else the checkout containing
+ * `cwd` (main -> main, registered -> its instance); outside any checkout, main. A worktree that
+ * is not registered throws, so nothing lands on another worktree's instance by mistake.
+ */
+export function currentInstance(config, { cwd = workingDirectory() } = {}) {
+    const pinned = pinnedName(config);
+    if (pinned) {
+        return getInstance(config, pinned);
+    }
+    const root = rootOf(config, cwd);
+    if (!root) {
+        return mainInstance(config);
+    }
+    const found = instanceAt(config, root);
+    if (!found) {
+        throw new CommandError(`${root} is a worktree with no instance yet.`, {
+            hint: unregisteredHint(config.envVar)
+        });
+    }
+    return found;
+}

package/dist/kits/worktrees/registration.d.ts

@@ -0,0 +1,15 @@
+import type { EnsureDetachedOptions, EnsureOptions, KitConfig, WorktreeInstance } from './models.js';
+/**
+ * Returns the instance for a checkout, registering it on first use: `root` if given, else the
+ * checkout containing `cwd`. Named after its folder (with a suffix if taken) unless `name` is
+ * given. Outside any checkout it is the current instance.
+ */
+export declare function ensureInstance(config: KitConfig, { cwd, root, name }?: EnsureOptions): WorktreeInstance;
+/**
+ * Returns a named instance that belongs to no checkout (e.g. one per container image),
+ * registering it on first use with the next free slot. The folder never resolves to it; it is
+ * reached by name (get, or the env variable). `meta` is stored with it and updated each time.
+ */
+export declare function ensureDetachedInstance(config: KitConfig, { name, meta }: EnsureDetachedOptions): WorktreeInstance;
+/** Forgets a registered worktree, freeing its slot. Never touches the worktree itself. */
+export declare function removeInstance(config: KitConfig, name: string): void;

package/dist/kits/worktrees/registration.js

@@ -0,0 +1,107 @@
+import path from 'node:path';
+import { pathExists, realPathOrResolve } from '../../edges/files.js';
+import { workingDirectory } from '../../edges/system.js';
+import { CommandError, UsageError } from '../../errors/errors.js';
+import { FALLBACK_WORKTREE_NAME } from './constants.js';
+import { describeInstance, nextFreeSlot, recordOf, uniqueName } from './instances.js';
+import { isValidName, toWorktreeName } from './names.js';
+import { currentInstance, getInstance, instanceAt, noInstanceError, pinnedName, rootOf } from './queries.js';
+const isTakenBy = (config, records) => (name) => Object.hasOwn(records, name) || name === config.mainName;
+const isCheckoutRoot = (config, root) => pathExists(root) && config.isCheckout(root);
+function assertChoosable(config, records, name) {
+    if (!isValidName(name)) {
+        throw new UsageError(`"${name}" is not a valid instance name.`, {
+            hint: 'Use lowercase letters, digits and dashes, e.g. "feat-x".'
+        });
+    }
+    if (isTakenBy(config, records)(name)) {
+        throw new UsageError(`Instance "${name}" already belongs to another worktree.`, {
+            hint: 'Pick another name.'
+        });
+    }
+}
+/** Outside any checkout there is nothing to register: a known name, or the current instance. */
+function ensureOutsideCheckout(config, records, cwd, name) {
+    const existing = name ? recordOf(records, name) : undefined;
+    if (name && existing) {
+        return describeInstance(config, name, existing);
+    }
+    if (name) {
+        throw new UsageError(`Instance "${name}" does not exist yet, so it needs a worktree.`, {
+            hint: 'Run it inside the worktree, or pass the worktree path.'
+        });
+    }
+    return currentInstance(config, { cwd });
+}
+function registerCheckout(config, records, target, name) {
+    const known = instanceAt(config, target);
+    if (known) {
+        if (name && name !== known.name) {
+            throw new UsageError(`${target} is already registered as "${known.name}".`);
+        }
+        return known;
+    }
+    if (name) {
+        assertChoosable(config, records, name);
+    }
+    const base = toWorktreeName(path.basename(target)) || FALLBACK_WORKTREE_NAME;
+    const finalName = uniqueName(name ?? base, base, isTakenBy(config, records));
+    const record = { slot: nextFreeSlot(records), root: target };
+    config.store.write({ ...records, [finalName]: record });
+    return describeInstance(config, finalName, record);
+}
+/**
+ * Returns the instance for a checkout, registering it on first use: `root` if given, else the
+ * checkout containing `cwd`. Named after its folder (with a suffix if taken) unless `name` is
+ * given. Outside any checkout it is the current instance.
+ */
+export function ensureInstance(config, { cwd = workingDirectory(), root, name } = {}) {
+    const pinned = pinnedName(config);
+    if (!root && !name && pinned) {
+        return getInstance(config, pinned);
+    }
+    const records = config.store.read();
+    const explicitRoot = root ? realPathOrResolve(root) : undefined;
+    if (explicitRoot !== undefined && !isCheckoutRoot(config, explicitRoot)) {
+        throw new CommandError(`${explicitRoot} is not a checkout of this app.`, {
+            hint: 'Point it at the root of a worktree.'
+        });
+    }
+    const target = explicitRoot ?? rootOf(config, cwd);
+    return target
+        ? registerCheckout(config, records, target, name)
+        : ensureOutsideCheckout(config, records, cwd, name);
+}
+/**
+ * Returns a named instance that belongs to no checkout (e.g. one per container image),
+ * registering it on first use with the next free slot. The folder never resolves to it; it is
+ * reached by name (get, or the env variable). `meta` is stored with it and updated each time.
+ */
+export function ensureDetachedInstance(config, { name, meta = {} }) {
+    if (!isValidName(name ?? '') || name === config.mainName) {
+        throw new UsageError(`"${name}" is not a valid instance name.`, {
+            hint: 'Use lowercase letters, digits and dashes, e.g. "trunk-c467312".'
+        });
+    }
+    const records = config.store.read();
+    const existing = recordOf(records, name);
+    if (existing?.root) {
+        throw new UsageError(`Instance "${name}" already belongs to ${existing.root}.`, {
+            hint: 'Pick another name.'
+        });
+    }
+    const record = { slot: existing?.slot ?? nextFreeSlot(records), root: null, meta };
+    config.store.write({ ...records, [name]: record });
+    return describeInstance(config, name, record);
+}
+/** Forgets a registered worktree, freeing its slot. Never touches the worktree itself. */
+export function removeInstance(config, name) {
+    if (name === config.mainName) {
+        throw new CommandError('The main checkout is not registered, so it cannot be removed.');
+    }
+    const records = config.store.read();
+    if (!recordOf(records, name)) {
+        throw noInstanceError(name);
+    }
+    config.store.write(Object.fromEntries(Object.entries(records).filter(([key]) => key !== name)));
+}

package/dist/kits/worktrees/registry-store.d.ts

@@ -0,0 +1,3 @@
+import type { CreateRegistryStoreFn } from './models.js';
+/** The registry file: JSON the app keeps wherever it says. The kit stores nothing of its own. */
+export declare const createRegistryStore: CreateRegistryStoreFn;

package/dist/kits/worktrees/registry-store.js

@@ -0,0 +1,27 @@
+import path from 'node:path';
+import { makeDirectory, readTextIfExists, writeText } from '../../edges/files.js';
+import { CommandError } from '../../errors/errors.js';
+import { messageOf } from '../../utils/error-message.js';
+import { STATE_INDENT_SPACES } from './constants.js';
+/** The registry file: JSON the app keeps wherever it says. The kit stores nothing of its own. */
+export const createRegistryStore = (stateFile) => ({
+    read: () => {
+        const text = readTextIfExists(stateFile);
+        if (text === undefined) {
+            return {};
+        }
+        try {
+            const records = JSON.parse(text);
+            return records;
+        }
+        catch (error) {
+            throw new CommandError(`${stateFile} is not valid JSON: ${messageOf(error)}`, {
+                hint: 'Fix the file, or delete it to forget every registered worktree.'
+            });
+        }
+    },
+    write: (records) => {
+        makeDirectory(path.dirname(stateFile));
+        writeText(stateFile, `${JSON.stringify(records, null, STATE_INDENT_SPACES)}\n`);
+    }
+});

package/dist/kits/worktrees/worktrees.d.ts

@@ -0,0 +1,10 @@
+import type { DefineWorktreesFn } from './models.js';
+/**
+ * Artemis worktrees kit: give every checkout of a repo its own instance (a stable slot, ports
+ * shifted by that slot, a color) so several copies of an app can run side by side.
+ *
+ * Every checkout is a worktree, the main one included. The main checkout is slot 0 and needs no
+ * registration; other worktrees register on first use (ensure) and keep their slot until removed.
+ * The kit stores nothing of its own: the app says where the registry lives (stateFile).
+ */
+export declare const defineWorktrees: DefineWorktreesFn;

package/dist/kits/worktrees/worktrees.js

@@ -0,0 +1,56 @@
+import { currentProcess } from '../../edges/process.js';
+import { processId } from '../../edges/system.js';
+import { isProcessAlive, newToken, now, pause } from './lock-edges.js';
+import { DEFAULT_COLORS, DEFAULT_MAIN_NAME, DEFAULT_SLOT_STEP, LOCK_TIMEOUT_MS } from './constants.js';
+import { realPathOrResolve } from '../../edges/files.js';
+import { createRegistryStore } from './registry-store.js';
+import { withLock } from './lock.js';
+import { ensureDetachedInstance, ensureInstance, removeInstance } from './registration.js';
+import { currentInstance, getInstance, listInstances } from './queries.js';
+const everyFolderIsACheckout = () => true;
+/** The options with their defaults applied, and the registry file they work on. */
+function configure(options) {
+    return {
+        stateFile: options.stateFile,
+        mainRoot: realPathOrResolve(options.mainCheckout),
+        ports: options.ports,
+        isCheckout: options.isCheckout ?? everyFolderIsACheckout,
+        envVar: options.envVar,
+        slotStep: options.slotStep ?? DEFAULT_SLOT_STEP,
+        colors: options.colors ?? DEFAULT_COLORS,
+        mainName: options.mainName ?? DEFAULT_MAIN_NAME,
+        env: options.env ?? currentProcess().env,
+        store: createRegistryStore(options.stateFile),
+        lock: {
+            pid: processId(),
+            token: newToken,
+            now: options.now ?? now,
+            isProcessAlive: options.isProcessAlive ?? isProcessAlive,
+            pause: options.pause ?? pause,
+            timeoutMs: options.lockTimeoutMs ?? LOCK_TIMEOUT_MS
+        }
+    };
+}
+/** Every write to the registry happens under its lock; reading needs none. */
+function locked(config, operation) {
+    return (...args) => withLock(config.stateFile, () => operation(...args), config.lock);
+}
+/**
+ * Artemis worktrees kit: give every checkout of a repo its own instance (a stable slot, ports
+ * shifted by that slot, a color) so several copies of an app can run side by side.
+ *
+ * Every checkout is a worktree, the main one included. The main checkout is slot 0 and needs no
+ * registration; other worktrees register on first use (ensure) and keep their slot until removed.
+ * The kit stores nothing of its own: the app says where the registry lives (stateFile).
+ */
+export const defineWorktrees = (options) => {
+    const config = configure(options);
+    return {
+        list: () => listInstances(config),
+        get: (name) => getInstance(config, name),
+        current: (currentOptions) => currentInstance(config, currentOptions),
+        ensure: locked(config, (ensureOptions) => ensureInstance(config, ensureOptions)),
+        ensureDetached: locked(config, (detachedOptions) => ensureDetachedInstance(config, detachedOptions)),
+        remove: locked(config, (name) => removeInstance(config, name))
+    };
+};