@cod3vil/trunk 0.1.1

package/dist/core/tmuxRename.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Renaming live tmux sessions after a prefix change. Sessions are named
+ * `<prefix>_<branch>`, so changing the prefix without renaming them leaves
+ * sessions that `wt remove` can no longer find.
+ *
+ * Every target is matched exactly. A session belonging to another project that
+ * merely starts with the same letters is never touched, and neither is one
+ * whose name matches the prefix but has no branch after it.
+ */
+import { type CommandRunner } from './process.js';
+export type SessionRename = Readonly<{
+    from: string;
+    to: string;
+}>;
+export type RenameOptions = Readonly<{
+    tmuxPath?: string;
+    run?: CommandRunner;
+    env?: NodeJS.ProcessEnv;
+    /** For tests: an isolated tmux server, as in `tmux -L trunk-test`. */
+    socketName?: string;
+}>;
+export type RenameResult = Readonly<{
+    renamed: readonly SessionRename[];
+    failed: readonly SessionRename[];
+}>;
+/**
+ * Which sessions a prefix change affects. Pure, so the list can be shown to the
+ * user before anything is renamed.
+ */
+export declare function planRenames(sessionNames: readonly string[], oldPrefix: string, newPrefix: string): readonly SessionRename[];
+/** The sessions tmux currently knows about, or none when tmux is not running. */
+export declare function listSessions(options?: RenameOptions): Promise<readonly string[]>;
+/** Renames each session, reporting which ones tmux refused. */
+export declare function renameSessions(renames: readonly SessionRename[], options?: RenameOptions): Promise<RenameResult>;
+/** What to run by hand when a rename failed and the session is stranded. */
+export declare function manualKillCommands(failed: readonly SessionRename[]): readonly string[];

package/dist/core/tmuxRename.js

@@ -0,0 +1,79 @@
+/* eslint-disable unicorn/filename-case -- Phase 5 specifies tmuxRename.ts. */
+/**
+ * Renaming live tmux sessions after a prefix change. Sessions are named
+ * `<prefix>_<branch>`, so changing the prefix without renaming them leaves
+ * sessions that `wt remove` can no longer find.
+ *
+ * Every target is matched exactly. A session belonging to another project that
+ * merely starts with the same letters is never touched, and neither is one
+ * whose name matches the prefix but has no branch after it.
+ */
+import { runCommand } from './process.js';
+/**
+ * Which sessions a prefix change affects. Pure, so the list can be shown to the
+ * user before anything is renamed.
+ */
+export function planRenames(sessionNames, oldPrefix, newPrefix) {
+    if (!oldPrefix || oldPrefix === newPrefix) {
+        return Object.freeze([]);
+    }
+    const start = `${oldPrefix}_`;
+    return Object.freeze(sessionNames
+        .filter(name => name.startsWith(start) && name.length > start.length)
+        .map(name => Object.freeze({
+        from: name,
+        to: `${newPrefix}_${name.slice(start.length)}`,
+    })));
+}
+/** The sessions tmux currently knows about, or none when tmux is not running. */
+export async function listSessions(options = {}) {
+    const result = await run(options)(tmuxPath(options), [...socket(options), 'list-sessions', '-F', '#{session_name}'], { env: options.env });
+    if (result.code !== 0) {
+        return Object.freeze([]);
+    }
+    return Object.freeze(result.stdout
+        .split(/\r?\n/)
+        .map(line => line.trim())
+        .filter(Boolean));
+}
+/** Renames each session, reporting which ones tmux refused. */
+export async function renameSessions(renames, options = {}) {
+    const renamed = [];
+    const failed = [];
+    for (const rename of renames) {
+        // Renames must not race each other on the same tmux server.
+        // eslint-disable-next-line no-await-in-loop
+        const result = await run(options)(tmuxPath(options), [
+            ...socket(options),
+            'rename-session',
+            '-t',
+            // The `=` prefix is an exact match; without it tmux would accept a
+            // unique prefix and could rename the wrong session.
+            `=${rename.from}`,
+            rename.to,
+        ], { env: options.env });
+        if (result.code === 0) {
+            renamed.push(rename);
+        }
+        else {
+            failed.push(rename);
+        }
+    }
+    return Object.freeze({
+        renamed: Object.freeze(renamed),
+        failed: Object.freeze(failed),
+    });
+}
+/** What to run by hand when a rename failed and the session is stranded. */
+export function manualKillCommands(failed) {
+    return Object.freeze(failed.map(rename => `tmux kill-session -t '=${rename.from}'`));
+}
+function socket(options) {
+    return options.socketName ? ['-L', options.socketName] : [];
+}
+function tmuxPath(options) {
+    return options.tmuxPath ?? 'tmux';
+}
+function run(options) {
+    return options.run ?? runCommand;
+}

package/dist/core/validate.d.ts

@@ -0,0 +1,22 @@
+import { type CommandRunner } from './process.js';
+import type { Settings } from './settings.js';
+export type ValidationPreview = Readonly<{
+    session?: string;
+    port?: number;
+    url?: string;
+}>;
+export type ValidationResult = Readonly<{
+    preview: ValidationPreview;
+    configOutput: string;
+    hookOutput: string;
+}>;
+export type ValidationOptions = Readonly<{
+    wtPath?: string;
+    run?: CommandRunner;
+    env?: NodeJS.ProcessEnv;
+}>;
+export declare class GeneratedConfigError extends Error {
+    readonly output: string;
+    constructor(message: string, output: string);
+}
+export declare function validateGeneratedConfig(worktreePath: string, settings: Settings, options?: ValidationOptions): Promise<ValidationResult>;

package/dist/core/validate.js

@@ -0,0 +1,111 @@
+/**
+ * Read-only validation of a generated project config through Worktrunk itself.
+ * The raw diagnostics stay attached to failures because they are usually the
+ * fastest way for a user to fix a local version or template mismatch.
+ */
+import { expectedHooks } from './generate/index.js';
+import { runCommand } from './process.js';
+export class GeneratedConfigError extends Error {
+    output;
+    constructor(message, output) {
+        super(`${message}${output.trim() ? `\n${output.trim()}` : ''}`);
+        this.name = 'GeneratedConfigError';
+        this.output = output;
+    }
+}
+export async function validateGeneratedConfig(worktreePath, settings, options = {}) {
+    const run = options.run ?? runCommand;
+    const wtPath = options.wtPath ?? 'wt';
+    const commandOptions = { env: options.env };
+    const config = await run(wtPath, ['-C', worktreePath, 'config', 'show'], commandOptions);
+    const configOutput = joinOutput(config.stdout, config.stderr);
+    if (config.code !== 0 || hasDiagnostic(configOutput)) {
+        throw new GeneratedConfigError('Worktrunk rejected the generated config.', configOutput);
+    }
+    const hooks = await run(wtPath, ['-C', worktreePath, 'hook', 'show', '--expanded', '--format', 'json'], commandOptions);
+    const hookOutput = joinOutput(hooks.stdout, hooks.stderr);
+    if (hooks.code !== 0 || hasDiagnostic(hookOutput)) {
+        throw new GeneratedConfigError('Worktrunk could not expand the generated hooks.', hookOutput);
+    }
+    const records = parseExpandedHooks(hooks.stdout, hookOutput);
+    assertExpectedHooks(records, settings, hookOutput);
+    return Object.freeze({
+        preview: Object.freeze(extractPreview(records)),
+        configOutput,
+        hookOutput,
+    });
+}
+function parseExpandedHooks(stdout, rawOutput) {
+    let value;
+    try {
+        value = JSON.parse(stdout);
+    }
+    catch {
+        throw new GeneratedConfigError('Worktrunk returned invalid hook JSON.', rawOutput);
+    }
+    if (!Array.isArray(value) || !value.every(entry => isExpandedHook(entry))) {
+        throw new GeneratedConfigError('Worktrunk returned unexpected hook data.', rawOutput);
+    }
+    return value;
+}
+function isExpandedHook(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        'expanded' in value &&
+        typeof value.expanded === 'string' &&
+        'name' in value &&
+        typeof value.name === 'string' &&
+        'source' in value &&
+        typeof value.source === 'string' &&
+        'type' in value &&
+        typeof value.type === 'string');
+}
+function assertExpectedHooks(records, settings, rawOutput) {
+    const configured = new Set(records
+        .filter(record => record.source === 'project')
+        .map(record => `${record.type}:${record.name}`));
+    const missing = expectedHooks(settings)
+        .map(hook => `${hook.type}:${hook.name}`)
+        .filter(hook => !configured.has(hook));
+    if (missing.length > 0) {
+        throw new GeneratedConfigError(`Worktrunk omitted generated hooks: ${missing.join(', ')}.`, rawOutput);
+    }
+}
+function extractPreview(records) {
+    const tmux = findHook(records, 'pre-start', 'tmux');
+    const server = findHook(records, 'post-start', 'server');
+    const proxy = findHook(records, 'post-start', 'proxy');
+    const prefix = tmux ? assignment(tmux, 'P') : undefined;
+    const branch = tmux ? assignment(tmux, 'B') : undefined;
+    const port = server ? /--port\s+(\d+)/.exec(server)?.[1] : undefined;
+    const host = proxy ? assignment(proxy, 'HOST') : undefined;
+    return {
+        session: prefix && branch ? `${prefix}_${branch}` : undefined,
+        port: port ? Number(port) : undefined,
+        url: host ? `http://${host}:8080` : undefined,
+    };
+}
+function findHook(records, type, name) {
+    return records.find(record => record.source === 'project' &&
+        record.type === type &&
+        record.name === name)?.expanded;
+}
+function assignment(body, name) {
+    const match = new RegExp(`^${name}=(.+)$`, 'm').exec(body);
+    return match ? unquote(match[1].trim()) : undefined;
+}
+function unquote(value) {
+    if ((value.startsWith("'") && value.endsWith("'")) ||
+        (value.startsWith('"') && value.endsWith('"'))) {
+        return value.slice(1, -1);
+    }
+    return value;
+}
+function hasDiagnostic(output) {
+    return output
+        .split(/\r?\n/)
+        .some(line => /^\s*[▲⚠✗]\s+.*(?:unknown field|invalid|error|warning|failed|rejected)/i.test(line) || /^\s*(?:warning|error)(?:\b|:)/i.test(line));
+}
+function joinOutput(stdout, stderr) {
+    return [stdout.trimEnd(), stderr.trimEnd()].filter(Boolean).join('\n');
+}

package/dist/core/version.d.ts

@@ -0,0 +1,2 @@
+/** The package version, or `0.0.0` when package.json cannot be read. */
+export declare function trunkVersion(): string;

package/dist/core/version.js

@@ -0,0 +1,35 @@
+/**
+ * Trunk's own version, for the header of every generated config.
+ *
+ * Read from package.json rather than generated into the source: npm always
+ * includes package.json in the published tarball, so it is there at run time,
+ * and a generated file would have to be either committed and kept in sync or
+ * gitignored — and a gitignored file is invisible to type-aware linting, which
+ * is exactly how this broke before.
+ */
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+let cached;
+/** The package version, or `0.0.0` when package.json cannot be read. */
+export function trunkVersion() {
+    cached ??= readVersion();
+    return cached;
+}
+function readVersion() {
+    // `source/core/` and the built `dist/core/` both sit two levels below the
+    // package root, so one path serves the tests and the published CLI.
+    const packagePath = fileURLToPath(new URL('../../package.json', import.meta.url));
+    try {
+        const parsed = JSON.parse(readFileSync(packagePath, 'utf8'));
+        if (typeof parsed === 'object' &&
+            parsed !== null &&
+            'version' in parsed &&
+            typeof parsed.version === 'string') {
+            return parsed.version;
+        }
+    }
+    catch {
+        // Falls through to the placeholder below.
+    }
+    return '0.0.0';
+}

package/dist/core/words.d.ts

@@ -0,0 +1,16 @@
+/**
+ * A word list for suggesting a prefix when a repository name gives a poor one.
+ * The words are short, concrete and unambiguous to type.
+ */
+/**
+ * Words that would be confusing as a session prefix because they already name a
+ * command or a branch. Kept out of the list below, and asserted in tests.
+ */
+export declare const reservedWords: readonly string[];
+/** Three to seven lowercase letters each: no digits, hyphens or ambiguity. */
+export declare const words: readonly string[];
+/**
+ * Picks a word, skipping any already in use. The random source is a parameter so
+ * tests can seed it and get the same word every run.
+ */
+export declare function randomWord(exclude?: ReadonlySet<string>, random?: () => number): string;

package/dist/core/words.js

@@ -0,0 +1,198 @@
+/**
+ * A word list for suggesting a prefix when a repository name gives a poor one.
+ * The words are short, concrete and unambiguous to type.
+ */
+/**
+ * Words that would be confusing as a session prefix because they already name a
+ * command or a branch. Kept out of the list below, and asserted in tests.
+ */
+export const reservedWords = Object.freeze([
+    'bash',
+    'brew',
+    'bun',
+    'caddy',
+    'cargo',
+    'code',
+    'deno',
+    'dev',
+    'docker',
+    'fish',
+    'gh',
+    'git',
+    'java',
+    'just',
+    'less',
+    'main',
+    'make',
+    'more',
+    'nano',
+    'next',
+    'node',
+    'npm',
+    'perl',
+    'pnpm',
+    'python',
+    'ruby',
+    'rustc',
+    'shell',
+    'task',
+    'tmux',
+    'vim',
+    'wt',
+    'yarn',
+    'zsh',
+]);
+/** Three to seven lowercase letters each: no digits, hyphens or ambiguity. */
+export const words = Object.freeze([
+    'acorn',
+    'anchor',
+    'anvil',
+    'apple',
+    'apron',
+    'badger',
+    'bamboo',
+    'barrel',
+    'beacon',
+    'beaver',
+    'birch',
+    'bison',
+    'blade',
+    'bloom',
+    'board',
+    'brook',
+    'brush',
+    'cabin',
+    'cactus',
+    'candle',
+    'canoe',
+    'cedar',
+    'cello',
+    'chalk',
+    'cherry',
+    'cliff',
+    'cloud',
+    'clover',
+    'coral',
+    'crane',
+    'creek',
+    'crown',
+    'crystal',
+    'daisy',
+    'delta',
+    'dune',
+    'eagle',
+    'earth',
+    'ember',
+    'falcon',
+    'fern',
+    'field',
+    'finch',
+    'flame',
+    'flint',
+    'forest',
+    'fox',
+    'frost',
+    'garden',
+    'gecko',
+    'globe',
+    'grove',
+    'harbor',
+    'hazel',
+    'heron',
+    'hill',
+    'honey',
+    'horse',
+    'iris',
+    'island',
+    'ivory',
+    'jade',
+    'kettle',
+    'koala',
+    'lake',
+    'lantern',
+    'laurel',
+    'lemon',
+    'lilac',
+    'linen',
+    'lotus',
+    'maple',
+    'marsh',
+    'meadow',
+    'melon',
+    'mint',
+    'moose',
+    'moss',
+    'moth',
+    'ocean',
+    'olive',
+    'onion',
+    'orchid',
+    'otter',
+    'owl',
+    'panda',
+    'pearl',
+    'pebble',
+    'pine',
+    'plum',
+    'pond',
+    'poppy',
+    'quartz',
+    'raven',
+    'reed',
+    'reef',
+    'ridge',
+    'robin',
+    'rose',
+    'sable',
+    'sage',
+    'sail',
+    'salmon',
+    'sand',
+    'seal',
+    'shark',
+    'slate',
+    'snail',
+    'snow',
+    'sparrow',
+    'spruce',
+    'star',
+    'stone',
+    'storm',
+    'summit',
+    'swan',
+    'thyme',
+    'tiger',
+    'topaz',
+    'torch',
+    'trout',
+    'tulip',
+    'turtle',
+    'vale',
+    'valley',
+    'velvet',
+    'vine',
+    'violet',
+    'walnut',
+    'wave',
+    'whale',
+    'willow',
+    'wolf',
+    'wren',
+    'yarrow',
+    'zebra',
+]);
+/**
+ * Picks a word, skipping any already in use. The random source is a parameter so
+ * tests can seed it and get the same word every run.
+ */
+export function randomWord(exclude = new Set(), random = Math.random) {
+    const candidates = words.filter(word => !exclude.has(word));
+    if (candidates.length === 0) {
+        throw new RangeError('No words remain after applying exclusions.');
+    }
+    const value = random();
+    if (value < 0 || value >= 1 || !Number.isFinite(value)) {
+        throw new RangeError('The random source must return a number from 0 up to 1.');
+    }
+    return candidates[Math.floor(value * candidates.length)];
+}

package/dist/core/wt.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Worktrunk wrappers. Two kinds live here: captured calls, whose output trunk
+ * reads, and attached calls, which borrow trunk's terminal so wt can ask its
+ * own questions.
+ *
+ * trunk never writes to the user's worktrunk config. When wt needs to know
+ * something, such as where worktrees belong for a project, wt asks for it
+ * itself through an attached call.
+ */
+import { type AttachedRunner, type CommandResult, type CommandRunner } from './process.js';
+export type WtOptions = Readonly<{
+    wtPath?: string;
+    run?: CommandRunner;
+    attach?: AttachedRunner;
+    env?: NodeJS.ProcessEnv;
+}>;
+export type HookType = 'pre-start' | 'post-start';
+/**
+ * The first `wt switch` in a project, with the terminal attached so wt's own
+ * worktree-path question reaches the user.
+ */
+export declare function switchAttached(projectDirectory: string, branch: string, options?: WtOptions): Promise<number>;
+/**
+ * Creates the setup worktree. `--no-hooks` is mandatory: the config being
+ * written has not been approved yet, and the hooks would otherwise run against
+ * a half-configured repository.
+ */
+export declare function switchCreateAttached(projectDirectory: string, branch: string, options?: WtOptions): Promise<number>;
+/** Undoes {@link switchCreateAttached}; also the rollback path's first step. */
+export declare function remove(projectDirectory: string, branch: string, options?: WtOptions): Promise<CommandResult>;
+/** Interactive by design: the user is approving commands that will run. */
+export declare function approvalsAdd(worktreePath: string, options?: WtOptions): Promise<number>;
+/**
+ * Runs one hook as the smoke test. Attached, because post-start starts a real
+ * dev server and prints where it is listening.
+ */
+export declare function runHook(worktreePath: string, hook: HookType, options?: WtOptions): Promise<number>;
+/** Where wt writes a failed hook's output, for the message after a failure. */
+export declare function hookLogPath(projectDirectory: string, branch: string, hook: HookType): string;
+/** Worktrunk's own branch-to-path rule, used for log paths and warnings. */
+export declare function sanitizeBranch(branch: string): string;

package/dist/core/wt.js

@@ -0,0 +1,59 @@
+/**
+ * Worktrunk wrappers. Two kinds live here: captured calls, whose output trunk
+ * reads, and attached calls, which borrow trunk's terminal so wt can ask its
+ * own questions.
+ *
+ * trunk never writes to the user's worktrunk config. When wt needs to know
+ * something, such as where worktrees belong for a project, wt asks for it
+ * itself through an attached call.
+ */
+import { runAttached, runCommand, } from './process.js';
+/**
+ * The first `wt switch` in a project, with the terminal attached so wt's own
+ * worktree-path question reaches the user.
+ */
+export async function switchAttached(projectDirectory, branch, options = {}) {
+    return attach(options)(wtPath(options), ['-C', projectDirectory, 'switch', branch], { env: options.env });
+}
+/**
+ * Creates the setup worktree. `--no-hooks` is mandatory: the config being
+ * written has not been approved yet, and the hooks would otherwise run against
+ * a half-configured repository.
+ */
+export async function switchCreateAttached(projectDirectory, branch, options = {}) {
+    return attach(options)(wtPath(options), ['-C', projectDirectory, 'switch', '--create', branch, '--no-hooks'], { env: options.env });
+}
+/** Undoes {@link switchCreateAttached}; also the rollback path's first step. */
+export async function remove(projectDirectory, branch, options = {}) {
+    return run(options)(wtPath(options), ['-C', projectDirectory, 'remove', branch, '--no-hooks', '--yes'], { env: options.env });
+}
+/** Interactive by design: the user is approving commands that will run. */
+export async function approvalsAdd(worktreePath, options = {}) {
+    return attach(options)(wtPath(options), ['-C', worktreePath, 'config', 'approvals', 'add'], { env: options.env });
+}
+/**
+ * Runs one hook as the smoke test. Attached, because post-start starts a real
+ * dev server and prints where it is listening.
+ */
+export async function runHook(worktreePath, hook, options = {}) {
+    return attach(options)(wtPath(options), ['-C', worktreePath, 'hook', hook], {
+        env: options.env,
+    });
+}
+/** Where wt writes a failed hook's output, for the message after a failure. */
+export function hookLogPath(projectDirectory, branch, hook) {
+    return `${projectDirectory}/.git/wt/logs/${sanitizeBranch(branch)}/project/${hook}/`;
+}
+/** Worktrunk's own branch-to-path rule, used for log paths and warnings. */
+export function sanitizeBranch(branch) {
+    return branch.replaceAll('/', '-');
+}
+function wtPath(options) {
+    return options.wtPath ?? 'wt';
+}
+function run(options) {
+    return options.run ?? runCommand;
+}
+function attach(options) {
+    return options.attach ?? runAttached;
+}

package/dist/ui/SetupForm.d.ts

@@ -0,0 +1,55 @@
+import React from 'react';
+import { resolve, type ResolveOptions } from '../core/resolve.js';
+import { type Outcome } from '../core/result.js';
+export type SetupFormProperties = Readonly<{
+    folder: string;
+    options: ResolveOptions;
+    randomPrefix?: () => string;
+    onSubmit: (settings: SetupValuesResult) => void;
+    onAbort: () => void;
+}>;
+type SetupValuesResult = Extract<ReturnType<typeof resolve>, {
+    kind: 'complete';
+}>['settings'];
+export type SetupFormOutcome = Readonly<{
+    kind: 'settings';
+    settings: SetupValuesResult;
+}> | Readonly<{
+    kind: 'aborted';
+}>
+/** The terminal could not run the form, so the caller falls back to flags. */
+ | Readonly<{
+    kind: 'unavailable';
+    reason: string;
+}>;
+export type CollectSettingsResult = Readonly<{
+    kind: 'settings';
+    settings: SetupValuesResult;
+}> | Readonly<{
+    kind: 'outcome';
+    outcome: Outcome;
+}>;
+export type CollectSettingsOptions = Readonly<{
+    folder: string;
+    resolveOptions: ResolveOptions;
+    invocation: Readonly<{
+        executable: string;
+        arguments: readonly string[];
+    }>;
+    yes?: boolean;
+    interactive?: boolean;
+    randomPrefix?: () => string;
+    installCaddy?: (executable: string, arguments_: readonly string[]) => Promise<boolean>;
+    report?: (line: string) => void;
+    /** Injectable so the abort and submit paths are testable without a TTY. */
+    runForm?: (properties: Omit<SetupFormProperties, 'onSubmit' | 'onAbort'>) => Promise<SetupFormOutcome>;
+    /** Injectable for the same reason as {@link CollectSettingsOptions.runForm}. */
+    askInstall?: () => Promise<InstallAnswer>;
+}>;
+export default function SetupForm({ folder, options, randomPrefix, onSubmit, onAbort, }: SetupFormProperties): React.ReactElement;
+/** Mounts Ink with Ctrl+C routed through the form's normal abort result. */
+export declare function runSetupForm(properties: Omit<SetupFormProperties, 'onSubmit' | 'onAbort'>): Promise<SetupFormOutcome>;
+/** Chooses the headless path or mounts the form, including the Caddy branch. */
+export declare function collectSettings({ folder, resolveOptions, invocation, yes, interactive, randomPrefix, installCaddy, report, runForm, askInstall, }: CollectSettingsOptions): Promise<CollectSettingsResult>;
+export type InstallAnswer = 'yes' | 'no' | 'abort';
+export {};