@zjaaal/artemis 0.0.0-stage → 0.1.2

package/dist/errors/errors.d.ts

@@ -0,0 +1,25 @@
+import type { CommandErrorOptions, ExitCode, IsCommandErrorFn, IsUsageErrorFn, UsageErrorOptions } from '../models.js';
+/**
+ * An expected failure: the message (and hint) is shown to the user, without a stack trace.
+ * Throw it from a command when something went wrong that the caller can fix.
+ */
+export declare class CommandError extends Error {
+    /** How to fix the call, shown after the message. */
+    readonly hint: string | undefined;
+    /** The process exit code this failure maps to. */
+    readonly exitCode: ExitCode;
+    constructor(message: string, { hint, exitCode, cause }?: CommandErrorOptions);
+}
+/** The command line itself is wrong (unknown command, bad argument). Exits with 2. */
+export declare class UsageError extends CommandError {
+    /** The usage line of the command, shown after the message. */
+    readonly usage: string | undefined;
+    constructor(message: string, { hint, usage }?: UsageErrorOptions);
+}
+/**
+ * Whether something is an expected failure (a `CommandError`), even one thrown by another copy of
+ * Artemis, where `instanceof` would say no and the hint and exit code would be lost.
+ */
+export declare const isCommandError: IsCommandErrorFn;
+/** Whether something is a wrong-command-line failure (a `UsageError`), from any copy of Artemis. */
+export declare const isUsageError: IsUsageErrorFn;

package/dist/errors/errors.js

@@ -0,0 +1,37 @@
+import { COMMAND_ERROR_TAG, EXIT_CODE, USAGE_ERROR_TAG } from '../constants.js';
+import { hasTag } from '../utils/tag.js';
+/**
+ * An expected failure: the message (and hint) is shown to the user, without a stack trace.
+ * Throw it from a command when something went wrong that the caller can fix.
+ */
+export class CommandError extends Error {
+    /** How to fix the call, shown after the message. */
+    hint;
+    /** The process exit code this failure maps to. */
+    exitCode;
+    constructor(message, { hint, exitCode = EXIT_CODE.FAILED, cause } = {}) {
+        super(message, { cause });
+        this.name = 'CommandError';
+        this.hint = hint;
+        this.exitCode = exitCode;
+        Object.defineProperty(this, COMMAND_ERROR_TAG, { value: true });
+    }
+}
+/** The command line itself is wrong (unknown command, bad argument). Exits with 2. */
+export class UsageError extends CommandError {
+    /** The usage line of the command, shown after the message. */
+    usage;
+    constructor(message, { hint, usage } = {}) {
+        super(message, { hint, exitCode: EXIT_CODE.USAGE });
+        this.name = 'UsageError';
+        this.usage = usage;
+        Object.defineProperty(this, USAGE_ERROR_TAG, { value: true });
+    }
+}
+/**
+ * Whether something is an expected failure (a `CommandError`), even one thrown by another copy of
+ * Artemis, where `instanceof` would say no and the hint and exit code would be lost.
+ */
+export const isCommandError = (value) => value instanceof Error && hasTag(value, COMMAND_ERROR_TAG);
+/** Whether something is a wrong-command-line failure (a `UsageError`), from any copy of Artemis. */
+export const isUsageError = (value) => isCommandError(value) && hasTag(value, USAGE_ERROR_TAG);

package/dist/help/help.d.ts

@@ -0,0 +1,15 @@
+import type { CommandHelpFn, CreateStyleFn, ManifestFn, TopicManifestFn, RootHelpFn, TopicHelpFn, UsageFn } from '../models.js';
+/** Color helpers; with `enabled` false they return the text untouched. */
+export declare const createStyle: CreateStyleFn;
+/** `art uve config set [url] [flags]` */
+export declare const usage: UsageFn;
+export declare const rootHelp: RootHelpFn;
+export declare const topicHelp: TopicHelpFn;
+export declare const commandHelp: CommandHelpFn;
+/** Everything help shows, as data: what an agent reads to know which commands exist and how to call them. */
+export declare const manifest: ManifestFn;
+/**
+ * The manifest of one topic: the topic and its sub-topics, and every command under it. It keeps the
+ * shape of the whole manifest, so a caller reads both the same way.
+ */
+export declare const topicManifest: TopicManifestFn;

package/dist/help/help.js

@@ -0,0 +1,169 @@
+import { ANSI_ESCAPE, ANSI_RESET, GLOBAL_FLAGS, ID_SEPARATOR, NOTE_SEPARATOR, SECTION_SEPARATOR, STYLE_CODES, TABLE_GAP, TABLE_INDENT } from '../constants.js';
+const wrap = (code, enabled) => (text) => enabled
+    ? `${ANSI_ESCAPE}${code}m${String(text)}${ANSI_ESCAPE}${ANSI_RESET}m`
+    : String(text);
+/** Color helpers; with `enabled` false they return the text untouched. */
+export const createStyle = (enabled) => ({
+    bold: wrap(STYLE_CODES.bold, enabled),
+    dim: wrap(STYLE_CODES.dim, enabled),
+    red: wrap(STYLE_CODES.red, enabled),
+    green: wrap(STYLE_CODES.green, enabled),
+    yellow: wrap(STYLE_CODES.yellow, enabled),
+    cyan: wrap(STYLE_CODES.cyan, enabled)
+});
+const argToken = (arg) => (arg.required ? `<${arg.name}>` : `[${arg.name}]`);
+/** `art uve config set [url] [flags]` */
+export const usage = (bin, entry) => {
+    const { args, flags } = entry.definition;
+    const parts = [bin, entry.id, ...args.map(argToken)];
+    if (Object.keys(flags).length > 0) {
+        parts.push('[flags]');
+    }
+    return parts.join(ID_SEPARATOR);
+};
+function table(rows, style) {
+    const width = Math.max(0, ...rows.map(([name]) => name.length));
+    return rows
+        .map(([name, text]) => `${TABLE_INDENT}${style.green(name.padEnd(width))}${TABLE_GAP}${text ?? ''}`)
+        .join('\n');
+}
+const section = (title, body, style) => `${style.bold(title)}\n${body}`;
+/** A description followed by its notes in parentheses, e.g. "Tags (repeatable; default: a)". */
+const withNotes = (description, notes) => [description, notes.length ? `(${notes.join(NOTE_SEPARATOR)})` : ''].filter(Boolean).join(' ');
+function flagNotes(flag) {
+    const notes = [];
+    if (flag.multiple) {
+        notes.push('repeatable');
+    }
+    if (flag.choices) {
+        notes.push(`one of: ${flag.choices.join(', ')}`);
+    }
+    if (flag.default !== undefined) {
+        notes.push(`default: ${String(flag.default)}`);
+    }
+    return notes;
+}
+function flagLabel(name, flag) {
+    const short = flag.short ? `-${flag.short}, ` : '';
+    const value = flag.type === 'string' ? ' <value>' : '';
+    return `${short}--${name}${value}`;
+}
+const flagRows = (flags) => Object.entries(flags).map(([name, flag]) => [
+    flagLabel(name, flag),
+    withNotes(flag.description, flagNotes(flag))
+]);
+function argNotes(arg) {
+    const notes = [];
+    if (arg.required) {
+        notes.push('required');
+    }
+    else if (arg.default !== undefined) {
+        notes.push(`default: ${arg.default}`);
+    }
+    if (arg.choices) {
+        notes.push(`one of: ${arg.choices.join(', ')}`);
+    }
+    return notes;
+}
+const argRows = (args) => args.map((arg) => [arg.name, withNotes(arg.description, argNotes(arg))]);
+const globalFlagsSection = (style) => section('Global flags', table(flagRows(GLOBAL_FLAGS), style), style);
+const isTopLevel = (id) => !id.includes(ID_SEPARATOR);
+// The root lists top-level topics and commands; a topic lists every command under it, however
+// deep, so "art uve" shows "uve config set" rather than an intermediate "uve config" topic.
+function childrenOf(registry, prefix) {
+    const commands = [...registry.commands.values()];
+    if (!prefix) {
+        return {
+            topics: [...registry.topics.values()].filter((topic) => isTopLevel(topic.id)),
+            commands: commands.filter((entry) => isTopLevel(entry.id))
+        };
+    }
+    return {
+        topics: [],
+        commands: commands.filter((entry) => entry.id.startsWith(`${prefix}${ID_SEPARATOR}`))
+    };
+}
+function listing(registry, prefix, style) {
+    const { topics, commands } = childrenOf(registry, prefix);
+    const sections = [];
+    if (topics.length) {
+        const rows = topics.map((topic) => [topic.id, topic.description]);
+        sections.push(section('Topics', table(rows, style), style));
+    }
+    if (commands.length) {
+        const rows = commands.map((entry) => [entry.id, entry.definition.description]);
+        sections.push(section('Commands', table(rows, style), style));
+    }
+    sections.push(globalFlagsSection(style));
+    return sections.join(SECTION_SEPARATOR);
+}
+export const rootHelp = (bin, registry, style) => [
+    `${style.bold('Usage')}  ${bin} <topic> <command> [args] [flags]`,
+    listing(registry, '', style),
+    style.dim(`Run "${bin} <topic>" to list a topic, or "${bin} <command> --help" for details.`)
+].join(SECTION_SEPARATOR);
+export const topicHelp = (_bin, registry, topic, style) => [
+    `${style.bold(topic.id)}${topic.description ? `  ${topic.description}` : ''}`,
+    listing(registry, topic.id, style)
+].join(SECTION_SEPARATOR);
+export const commandHelp = (bin, entry, style) => {
+    const { description, args, flags, aliases, examples } = entry.definition;
+    const sections = [description, `${style.bold('Usage')}  ${usage(bin, entry)}`];
+    if (args.length) {
+        sections.push(section('Arguments', table(argRows(args), style), style));
+    }
+    if (Object.keys(flags).length) {
+        sections.push(section('Flags', table(flagRows(flags), style), style));
+    }
+    sections.push(globalFlagsSection(style));
+    if (aliases.length) {
+        sections.push(`${style.bold('Aliases')}  ${aliases.join(', ')}`);
+    }
+    if (examples.length) {
+        const lines = examples.map((example) => `${TABLE_INDENT}${bin} ${example}`);
+        sections.push(section('Examples', lines.join('\n'), style));
+    }
+    return sections.join(SECTION_SEPARATOR);
+};
+const describeFlags = (flags) => Object.entries(flags).map(([name, flag]) => ({
+    name,
+    type: flag.type,
+    short: flag.short ?? null,
+    multiple: Boolean(flag.multiple),
+    description: flag.description ?? '',
+    default: flag.default ?? null,
+    choices: flag.choices ?? null
+}));
+const describeArgs = (args) => args.map((arg) => ({
+    name: arg.name,
+    description: arg.description ?? '',
+    required: Boolean(arg.required),
+    default: arg.default ?? null,
+    choices: arg.choices ?? null
+}));
+const describeCommand = (bin, entry) => ({
+    id: entry.id,
+    description: entry.definition.description,
+    usage: usage(bin, entry),
+    aliases: entry.definition.aliases,
+    args: describeArgs(entry.definition.args),
+    flags: describeFlags(entry.definition.flags),
+    examples: entry.definition.examples
+});
+/** Everything help shows, as data: what an agent reads to know which commands exist and how to call them. */
+export const manifest = (bin, registry) => ({
+    bin,
+    topics: [...registry.topics.values()],
+    commands: [...registry.commands.values()].map((entry) => describeCommand(bin, entry)),
+    globalFlags: describeFlags(GLOBAL_FLAGS)
+});
+const isWithin = (id, topicId) => id === topicId || id.startsWith(`${topicId} `);
+/**
+ * The manifest of one topic: the topic and its sub-topics, and every command under it. It keeps the
+ * shape of the whole manifest, so a caller reads both the same way.
+ */
+export const topicManifest = (everything, topicId) => ({
+    ...everything,
+    topics: everything.topics.filter((topic) => isWithin(topic.id, topicId)),
+    commands: everything.commands.filter((command) => isWithin(command.id, topicId))
+});

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Artemis: drop a file in a folder, get a command.
+ *
+ *   commands/uve/config/set.js  ->  art uve config set
+ *
+ * Folders are topics, `_topic.js` describes a topic, and anything starting with "_" is private.
+ * Every command gets --help, --json and --yes, and `art help --json` describes all of them.
+ */
+export { EXIT_CODE } from './constants.js';
+export { defineCommand, defineTopic } from './define/define.js';
+export { CommandError, UsageError } from './errors/errors.js';
+export type { ArgDefinition, Command, CommandContext, CommandDefinition, ExitCode, FlagDefinition, InferArgs, InferFlags, RunInput, RunOptions, TopicDefinition } from './models.js';
+export { run } from './run/run.js';

package/dist/index.js

@@ -0,0 +1,12 @@
+/**
+ * Artemis: drop a file in a folder, get a command.
+ *
+ *   commands/uve/config/set.js  ->  art uve config set
+ *
+ * Folders are topics, `_topic.js` describes a topic, and anything starting with "_" is private.
+ * Every command gets --help, --json and --yes, and `art help --json` describes all of them.
+ */
+export { EXIT_CODE } from './constants.js';
+export { defineCommand, defineTopic } from './define/define.js';
+export { CommandError, UsageError } from './errors/errors.js';
+export { run } from './run/run.js';

package/dist/kits/terminal/constants.d.ts

@@ -0,0 +1,10 @@
+export declare const WARP_CONFIG_FOLDER = ".warp/tab_configs";
+export declare const WARP_LINK_PREFIX = "warp://tab_config/";
+export declare const TAB_CONFIG_EXTENSION = ".toml";
+export declare const OPEN_COMMAND = "open";
+export declare const ROOT_PANE_ID = "root";
+export declare const FIRST_PANE_ID = "pane_1";
+export declare const PANE_ID_PREFIX = "pane_";
+export declare const SPLIT_ID_PREFIX = "split_";
+/** A tab id becomes a file name and part of a link, so it is a plain word: no slashes, spaces or `#`. */
+export declare const TAB_ID_PATTERN: RegExp;

package/dist/kits/terminal/constants.js

@@ -0,0 +1,10 @@
+export const WARP_CONFIG_FOLDER = '.warp/tab_configs';
+export const WARP_LINK_PREFIX = 'warp://tab_config/';
+export const TAB_CONFIG_EXTENSION = '.toml';
+export const OPEN_COMMAND = 'open';
+export const ROOT_PANE_ID = 'root';
+export const FIRST_PANE_ID = 'pane_1';
+export const PANE_ID_PREFIX = 'pane_';
+export const SPLIT_ID_PREFIX = 'split_';
+/** A tab id becomes a file name and part of a link, so it is a plain word: no slashes, spaces or `#`. */
+export const TAB_ID_PATTERN = /^[A-Za-z0-9_-]+$/;

package/dist/kits/terminal/index.d.ts

@@ -0,0 +1,3 @@
+export type { OpenLinkFn, SplitDirection, Terminal, TerminalLayout, TerminalPane, TerminalSplit, TerminalTab, WarpOptions } from './models.js';
+export { openTabs } from './open-tabs.js';
+export { warp } from './warp.js';

package/dist/kits/terminal/index.js

@@ -0,0 +1,2 @@
+export { openTabs } from './open-tabs.js';
+export { warp } from './warp.js';

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

@@ -0,0 +1,57 @@
+/** One terminal pane: a folder, the commands to type in it, and whether it takes focus. */
+export type TerminalPane = {
+    dir: string;
+    run?: readonly string[];
+    focus?: boolean;
+};
+/** `horizontal` puts children side by side, `vertical` stacks them. */
+export type SplitDirection = 'horizontal' | 'vertical';
+export type TerminalSplit = {
+    split: SplitDirection;
+    children: readonly TerminalLayout[];
+};
+export type TerminalLayout = TerminalPane | TerminalSplit;
+type TabBase = {
+    id: string;
+    name: string;
+    title?: string;
+    color?: string;
+};
+/** A tab is either a flat list of panes (left to right) or a layout tree of splits. */
+export type TerminalTab = (TabBase & {
+    panes: readonly TerminalPane[];
+    layout?: never;
+}) | (TabBase & {
+    layout: TerminalLayout;
+    panes?: never;
+});
+/** What an adapter does with a tab: write its config, open it, remove it. */
+export type Terminal = {
+    write: (tab: TerminalTab) => void;
+    open: (id: string) => void;
+    remove: (id: string) => void;
+};
+export type OpenLinkFn = (url: string) => void;
+export type WarpOptions = {
+    /** Where Warp reads Tab Configs from. Default: `~/.warp/tab_configs`. */
+    configDir?: string;
+    /** How a link is opened. Default: macOS `open`. */
+    open?: OpenLinkFn;
+};
+export type CheckTabIdFn = (id: string) => string;
+export type WarpFn = (options?: WarpOptions) => Terminal;
+export type OpenTabsFn = (terminal: Terminal, tabs: readonly TerminalTab[]) => void;
+/** A pane or split with the id Warp refers to it by. */
+export type IdentifiedNode = (TerminalPane & {
+    id: string;
+}) | {
+    split: SplitDirection;
+    id: string;
+    children: IdentifiedNode[];
+};
+export type IdCounters = {
+    pane: number;
+    split: number;
+};
+export type ToTomlFn = (tab: TerminalTab) => string;
+export {};

package/dist/kits/terminal/models.js

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

package/dist/kits/terminal/open-link.d.ts

@@ -0,0 +1,2 @@
+import type { OpenLinkFn } from './models.js';
+export declare const openLink: OpenLinkFn;

package/dist/kits/terminal/open-link.js

@@ -0,0 +1,12 @@
+import { spawnSync } from 'node:child_process';
+import { OPEN_COMMAND } from './constants.js';
+import { CommandError } from '../../errors/errors.js';
+// Edge: opens a link with the macOS `open` command.
+export const openLink = (url) => {
+    const result = spawnSync(OPEN_COMMAND, [url], { encoding: 'utf8' });
+    if (result.status !== 0) {
+        throw new CommandError(`Warp did not open ${url}: ${String(result.stderr ?? '').trim()}`, {
+            hint: 'Check Warp is installed and handles warp:// links.'
+        });
+    }
+};

package/dist/kits/terminal/open-tabs.d.ts

@@ -0,0 +1,3 @@
+import type { OpenTabsFn } from './models.js';
+/** Writes every tab, then opens them in order. */
+export declare const openTabs: OpenTabsFn;

package/dist/kits/terminal/open-tabs.js

@@ -0,0 +1,5 @@
+/** Writes every tab, then opens them in order. */
+export const openTabs = (terminal, tabs) => {
+    tabs.forEach((tab) => terminal.write(tab));
+    tabs.forEach((tab) => terminal.open(tab.id));
+};

package/dist/kits/terminal/toml.d.ts

@@ -0,0 +1,3 @@
+import type { ToTomlFn } from './models.js';
+/** The Warp Tab Config (TOML) for a tab. Pure: the same tab always gives the same text. */
+export declare const toToml: ToTomlFn;

package/dist/kits/terminal/toml.js

@@ -0,0 +1,53 @@
+import { FIRST_PANE_ID, PANE_ID_PREFIX, ROOT_PANE_ID, SPLIT_ID_PREFIX } from './constants.js';
+// TOML basic strings use the same escapes as JSON for what we write (paths and commands)
+const str = (value) => JSON.stringify(value);
+const isSplit = (node) => 'split' in node;
+/** A flat list of panes is a left-to-right split; a single pane needs no split at all. */
+function layoutOf(tab) {
+    if (tab.layout) {
+        return tab.layout;
+    }
+    const panes = tab.panes ?? [];
+    const [only] = panes;
+    return panes.length === 1 && only ? only : { split: 'horizontal', children: panes };
+}
+/** Assigns Warp pane ids: "root" for the top node, split_N for nested splits, pane_N for panes. */
+function assignIds(node, counters, isRoot) {
+    if (!isSplit(node)) {
+        return { ...node, id: isRoot ? FIRST_PANE_ID : `${PANE_ID_PREFIX}${++counters.pane}` };
+    }
+    const id = isRoot ? ROOT_PANE_ID : `${SPLIT_ID_PREFIX}${++counters.split}`;
+    const children = node.children.map((child) => assignIds(child, counters, false));
+    return { split: node.split, id, children };
+}
+// Warp reads the first [[panes]] entry as the root, so nodes go out parent first
+function nodeLines(node) {
+    const header = ['', '[[panes]]', `id = ${str(node.id)}`];
+    if ('children' in node) {
+        const ids = node.children.map((child) => str(child.id)).join(', ');
+        return [
+            ...header,
+            `split = ${str(node.split)}`,
+            `children = [${ids}]`,
+            ...node.children.flatMap(nodeLines)
+        ];
+    }
+    return [
+        ...header,
+        'type = "terminal"',
+        `directory = ${str(node.dir)}`,
+        ...(node.run?.length ? [`commands = [${node.run.map(str).join(', ')}]`] : []),
+        ...(node.focus ? ['is_focused = true'] : [])
+    ];
+}
+/** The Warp Tab Config (TOML) for a tab. Pure: the same tab always gives the same text. */
+export const toToml = (tab) => {
+    const root = assignIds(layoutOf(tab), { pane: 0, split: 0 }, true);
+    const lines = [
+        `name = ${str(tab.name)}`,
+        ...(tab.title ? [`title = ${str(tab.title)}`] : []),
+        ...(tab.color ? [`color = ${str(tab.color)}`] : []),
+        ...nodeLines(root)
+    ];
+    return `${lines.join('\n')}\n`;
+};

package/dist/kits/terminal/warp.d.ts

@@ -0,0 +1,6 @@
+import type { WarpFn } from './models.js';
+/**
+ * Warp adapter: each tab becomes a Tab Config (`<id>.toml`) opened through its warp:// link, as a
+ * new tab in the focused window (or a new window if none is open).
+ */
+export declare const warp: WarpFn;

package/dist/kits/terminal/warp.js

@@ -0,0 +1,32 @@
+import path from 'node:path';
+import { makeDirectory, removeFile, writeText } from '../../edges/files.js';
+import { homeDirectory } from '../../edges/system.js';
+import { CommandError } from '../../errors/errors.js';
+import { TAB_CONFIG_EXTENSION, TAB_ID_PATTERN, WARP_CONFIG_FOLDER, WARP_LINK_PREFIX } from './constants.js';
+import { openLink } from './open-link.js';
+import { toToml } from './toml.js';
+/** A tab id is used as a file name and in a link, so anything but a plain word is refused. */
+const checkedId = (id) => {
+    if (!TAB_ID_PATTERN.test(id)) {
+        throw new CommandError(`"${id}" is not a valid tab id.`, {
+            hint: 'Use letters, digits, dashes and underscores only, e.g. "demo_dotcms".'
+        });
+    }
+    return id;
+};
+/**
+ * Warp adapter: each tab becomes a Tab Config (`<id>.toml`) opened through its warp:// link, as a
+ * new tab in the focused window (or a new window if none is open).
+ */
+export const warp = ({ configDir = path.join(homeDirectory(), WARP_CONFIG_FOLDER), open = openLink } = {}) => {
+    const fileOf = (id) => path.join(configDir, `${checkedId(id)}${TAB_CONFIG_EXTENSION}`);
+    return {
+        write: (tab) => {
+            const file = fileOf(tab.id);
+            makeDirectory(configDir);
+            writeText(file, toToml(tab));
+        },
+        open: (id) => open(`${WARP_LINK_PREFIX}${checkedId(id)}`),
+        remove: (id) => removeFile(fileOf(id))
+    };
+};

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

@@ -0,0 +1,25 @@
+/** The main checkout is slot 0 and needs no registration; registered worktrees start at 1. */
+export declare const MAIN_SLOT = 0;
+export declare const FIRST_WORKTREE_SLOT = 1;
+export declare const DEFAULT_MAIN_NAME = "main";
+export declare const DEFAULT_SLOT_STEP = 100;
+export declare const DEFAULT_COLORS: readonly ["blue", "green", "magenta", "cyan", "yellow", "red"];
+/** An instance name is a lowercase letter or digit, then letters, digits and dashes. */
+export declare const MAX_INSTANCE_NAME_LENGTH = 31;
+export declare const VALID_NAME: RegExp;
+export declare const INVALID_NAME_RUN: RegExp;
+export declare const EDGE_DASHES: RegExp;
+export declare const FIRST_SUFFIX = 2;
+export declare const FALLBACK_WORKTREE_NAME = "worktree";
+export declare const STATE_INDENT_SPACES = 4;
+export declare const LOCK_SUFFIX = ".lock";
+export declare const LOCK_TIMEOUT_MS = 10000;
+export declare const LOCK_POLL_MS = 10;
+/** A lock file with no process id in it is probably being written; it is left alone this long. */
+export declare const LOCK_GRACE_MS = 200;
+/** Whoever is taking over a stale lock is given this long before the takeover itself counts as abandoned. */
+export declare const TAKEOVER_STALE_MS = 5000;
+export declare const TAKEOVER_SUFFIX = ".takeover";
+export declare const INT32_BYTES = 4;
+/** Signal 0 only asks whether the process exists. */
+export declare const PROBE_SIGNAL = 0;

package/dist/kits/worktrees/constants.js

@@ -0,0 +1,25 @@
+/** The main checkout is slot 0 and needs no registration; registered worktrees start at 1. */
+export const MAIN_SLOT = 0;
+export const FIRST_WORKTREE_SLOT = 1;
+export const DEFAULT_MAIN_NAME = 'main';
+export const DEFAULT_SLOT_STEP = 100;
+export const DEFAULT_COLORS = ['blue', 'green', 'magenta', 'cyan', 'yellow', 'red'];
+/** An instance name is a lowercase letter or digit, then letters, digits and dashes. */
+export const MAX_INSTANCE_NAME_LENGTH = 31;
+export const VALID_NAME = new RegExp(`^[a-z0-9][a-z0-9-]{0,${MAX_INSTANCE_NAME_LENGTH - 1}}$`);
+export const INVALID_NAME_RUN = /[^a-z0-9-]+/g;
+export const EDGE_DASHES = /^-+|-+$/g;
+export const FIRST_SUFFIX = 2;
+export const FALLBACK_WORKTREE_NAME = 'worktree';
+export const STATE_INDENT_SPACES = 4;
+export const LOCK_SUFFIX = '.lock';
+export const LOCK_TIMEOUT_MS = 10_000;
+export const LOCK_POLL_MS = 10;
+/** A lock file with no process id in it is probably being written; it is left alone this long. */
+export const LOCK_GRACE_MS = 200;
+/** Whoever is taking over a stale lock is given this long before the takeover itself counts as abandoned. */
+export const TAKEOVER_STALE_MS = 5000;
+export const TAKEOVER_SUFFIX = '.takeover';
+export const INT32_BYTES = 4;
+/** Signal 0 only asks whether the process exists. */
+export const PROBE_SIGNAL = 0;

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

@@ -0,0 +1,2 @@
+import type { GitRootFn } from '../../models.js';
+export declare const gitRoot: GitRootFn;

package/dist/kits/worktrees/git.js

@@ -0,0 +1,7 @@
+import { spawnSync } from 'node:child_process';
+import { realPathOrResolve } from '../../edges/files.js';
+// Edge: asks git which checkout a folder belongs to.
+export const gitRoot = (cwd) => {
+    const result = spawnSync('git', ['rev-parse', '--show-toplevel'], { cwd, encoding: 'utf8' });
+    return result.status === 0 ? realPathOrResolve(result.stdout.trim()) : null;
+};

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

@@ -0,0 +1,3 @@
+export type { CurrentOptions, EnsureDetachedOptions, EnsureOptions, IsCheckoutFn, WorktreeInstance, WorktreeMeta, Worktrees, WorktreesOptions } from './models.js';
+export { toWorktreeName } from './names.js';
+export { defineWorktrees } from './worktrees.js';

package/dist/kits/worktrees/index.js

@@ -0,0 +1,2 @@
+export { toWorktreeName } from './names.js';
+export { defineWorktrees } from './worktrees.js';

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

@@ -0,0 +1,9 @@
+import type { DescribeInstanceFn, NextFreeSlotFn, RecordOfFn, UniqueNameFn } from './models.js';
+/** A record of the registry as an instance: its ports shifted by slot, and its color by slot. */
+export declare const describeInstance: DescribeInstanceFn;
+/** The record of a registered name. Only the registry's own entries count, never `constructor` and friends. */
+export declare const recordOf: RecordOfFn;
+/** The lowest slot no registered worktree uses. Slot 0 is the main checkout. */
+export declare const nextFreeSlot: NextFreeSlotFn;
+/** `wanted`, or `base-2`, `base-3`... when it is taken. */
+export declare const uniqueName: UniqueNameFn;

package/dist/kits/worktrees/instances.js

@@ -0,0 +1,33 @@
+import { FIRST_SUFFIX, FIRST_WORKTREE_SLOT, MAIN_SLOT } from './constants.js';
+/** A record of the registry as an instance: its ports shifted by slot, and its color by slot. */
+export const describeInstance = (config, name, record) => ({
+    name,
+    slot: record.slot,
+    root: record.root,
+    isMain: record.slot === MAIN_SLOT,
+    meta: record.meta ?? {},
+    color: config.colors[record.slot % config.colors.length] ?? '',
+    ports: Object.fromEntries(Object.entries(config.ports).map(([key, port]) => [
+        key,
+        port + record.slot * config.slotStep
+    ]))
+});
+/** The record of a registered name. Only the registry's own entries count, never `constructor` and friends. */
+export const recordOf = (records, name) => Object.hasOwn(records, name) ? records[name] : undefined;
+/** The lowest slot no registered worktree uses. Slot 0 is the main checkout. */
+export const nextFreeSlot = (records) => {
+    const used = new Set(Object.values(records).map((record) => record.slot));
+    let slot = FIRST_WORKTREE_SLOT;
+    while (used.has(slot)) {
+        slot++;
+    }
+    return slot;
+};
+/** `wanted`, or `base-2`, `base-3`... when it is taken. */
+export const uniqueName = (wanted, base, isTaken) => {
+    let name = wanted;
+    for (let suffix = FIRST_SUFFIX; isTaken(name); suffix++) {
+        name = `${base}-${suffix}`;
+    }
+    return name;
+};

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

@@ -0,0 +1,7 @@
+import type { IsProcessAliveFn, NowFn, PauseFn, TokenFn } from './models.js';
+export declare const now: NowFn;
+/** Signal 0 only asks whether the process exists. Someone else's process (EPERM) is alive too. */
+export declare const isProcessAlive: IsProcessAliveFn;
+/** A blocking wait: the kit is synchronous like the rest of its callers. */
+export declare const pause: PauseFn;
+export declare const newToken: TokenFn;

package/dist/kits/worktrees/lock-edges.js

@@ -0,0 +1,21 @@
+import { randomUUID } from 'node:crypto';
+import { ERROR_CODE } from '../../constants.js';
+import { INT32_BYTES, PROBE_SIGNAL } from './constants.js';
+import { codeOf } from '../../utils/error-code.js';
+// Edges of the registry lock: the clock, process liveness, and waiting.
+export const now = () => Date.now();
+/** Signal 0 only asks whether the process exists. Someone else's process (EPERM) is alive too. */
+export const isProcessAlive = (pid) => {
+    try {
+        process.kill(pid, PROBE_SIGNAL);
+        return true;
+    }
+    catch (error) {
+        return codeOf(error) === ERROR_CODE.PERMISSION_DENIED;
+    }
+};
+/** A blocking wait: the kit is synchronous like the rest of its callers. */
+export const pause = (ms) => {
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(INT32_BYTES)), 0, 0, ms);
+};
+export const newToken = () => randomUUID();