@cod3vil/trunk 0.1.1

package/dist/core/prefix.js

@@ -0,0 +1,59 @@
+/**
+ * The tmux session prefix. Sessions are named `<prefix>_<branch>`, so the prefix
+ * is what keeps one repository's sessions apart from another's, and it has to
+ * survive tmux's own naming rules.
+ */
+/**
+ * Suggests a prefix from a repository name: the first word in full, then the
+ * initial of each word after it (`acme-web-backend` becomes `acme-wb`). Short
+ * enough to read in a tmux status line, and stable for a given name.
+ *
+ * Two repositories can suggest the same prefix; the setup form shows the value
+ * so the user can change it.
+ */
+export function initials(name) {
+    // Any run of punctuation separates words, which also absorbs doubled and
+    // trailing hyphens.
+    const parts = name
+        .toLowerCase()
+        .split(/[^a-z\d]+/)
+        .filter(Boolean);
+    if (parts.length < 2) {
+        return parts[0] ?? '';
+    }
+    return `${parts[0]}-${parts
+        .slice(1)
+        .map(part => part[0])
+        .join('')}`;
+}
+/**
+ * Checks a prefix the user typed. Each rule explains itself, and nothing is
+ * silently rewritten: a surprising prefix is worse than an error message.
+ */
+export function validatePrefix(prefix) {
+    if (prefix.length === 0) {
+        return invalid('Prefix cannot be empty.');
+    }
+    if (prefix.length > 24) {
+        return invalid('Prefix must be at most 24 characters.');
+    }
+    if (prefix.startsWith('-')) {
+        return invalid('Prefix cannot start with a hyphen.');
+    }
+    if (prefix.includes('_')) {
+        return invalid('Prefix cannot contain underscores because "_" separates it from the branch.');
+    }
+    if (prefix.includes('.') || prefix.includes(':')) {
+        return invalid('Prefix cannot contain "." or ":" because tmux rewrites them.');
+    }
+    if (/[A-Z]/.test(prefix)) {
+        return invalid('Prefix must use lowercase letters.');
+    }
+    if (!/^[a-z\d][a-z\d-]*$/.test(prefix)) {
+        return invalid('Prefix may contain only lowercase letters, digits, and hyphens.');
+    }
+    return Object.freeze({ valid: true });
+}
+function invalid(reason) {
+    return Object.freeze({ valid: false, reason });
+}

package/dist/core/process.d.ts

@@ -0,0 +1,27 @@
+export type CommandResult = Readonly<{
+    code: number | undefined;
+    stdout: string;
+    stderr: string;
+}>;
+export type CommandOptions = Readonly<{
+    cwd?: string;
+    env?: NodeJS.ProcessEnv;
+}>;
+/**
+ * Runs a command with trunk's own terminal, so the child can ask the user its
+ * own questions and stream its own progress. Nothing is captured, so callers
+ * get the exit code only.
+ */
+export type AttachedRunner = (command: string, arguments_: readonly string[], options?: CommandOptions) => Promise<number>;
+export declare const runAttached: AttachedRunner;
+/**
+ * The shape callers accept, so a test can pass a stub in place of
+ * {@link runCommand} and never touch the real machine.
+ */
+export type CommandRunner = (command: string, arguments_: readonly string[], options?: CommandOptions) => Promise<CommandResult>;
+/**
+ * Runs a command to completion and collects its output. A non-zero exit is a
+ * normal result, not a rejection; only a process that could not be started at
+ * all rejects.
+ */
+export declare const runCommand: CommandRunner;

package/dist/core/process.js

@@ -0,0 +1,43 @@
+/**
+ * The one way trunk runs another program. Everything goes through `spawn`
+ * without a shell, so an argument containing a space or a quote can never be
+ * reinterpreted as shell syntax.
+ */
+import { spawn } from 'node:child_process';
+export const runAttached = async (command, arguments_, options = {}) => new Promise((resolve, reject) => {
+    const child = spawn(command, arguments_, {
+        cwd: options.cwd,
+        env: options.env,
+        stdio: 'inherit',
+    });
+    child.once('error', reject);
+    child.once('close', code => {
+        resolve(code ?? 1);
+    });
+});
+/**
+ * Runs a command to completion and collects its output. A non-zero exit is a
+ * normal result, not a rejection; only a process that could not be started at
+ * all rejects.
+ */
+export const runCommand = async (command, arguments_, options = {}) => new Promise((resolve, reject) => {
+    const child = spawn(command, arguments_, {
+        cwd: options.cwd,
+        env: options.env,
+        stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    let stdout = '';
+    let stderr = '';
+    child.stdout.setEncoding('utf8');
+    child.stderr.setEncoding('utf8');
+    child.stdout.on('data', (chunk) => {
+        stdout += chunk;
+    });
+    child.stderr.on('data', (chunk) => {
+        stderr += chunk;
+    });
+    child.once('error', reject);
+    child.once('close', code => {
+        resolve(Object.freeze({ code: code ?? undefined, stdout, stderr }));
+    });
+});

package/dist/core/repo.d.ts

@@ -0,0 +1,79 @@
+import { type GitOptions } from './git.js';
+/** A remote on a hosting service, parsed from any URL form git accepts. */
+export type Remote = Readonly<{
+    kind: 'hosted';
+    /** The URL exactly as the user typed it. */
+    url: string;
+    /** The host as written, which may be an SSH alias such as `github.com-work`. */
+    host: string;
+    /** What that alias resolves to in ~/.ssh/config, for deciding gh can reach it. */
+    realHost: string;
+    owner: string;
+    /** Repository name without the `.git` suffix. */
+    repo: string;
+    /**
+     * `host/owner/repo`, matching what `wt config show` prints as its Identifier.
+     * The alias is kept verbatim, because that is the string wt keys its
+     * per-project settings on.
+     */
+    identifier: string;
+}>;
+export type LocalRemote = Readonly<{
+    kind: 'local';
+    url: string;
+    path: string;
+    repo: string;
+    identifier: string;
+}>;
+export type ParsedRemote = Remote | LocalRemote;
+export type SshAliases = Readonly<Record<string, string>>;
+/**
+ * - `bare-project`: the directory is a trunk-layout project root, holding a bare
+ *   `.git` with worktrees beside it. This is the layout trunk sets up.
+ * - `bare-inside`: somewhere inside such a project, for example one of its
+ *   worktrees; `projectRoot` points at the top.
+ * - `plain-clone`: an ordinary clone, which trunk refuses to convert in place.
+ * - `empty`: nothing there yet, which is what clone and new want.
+ * - `occupied`: files that are not a repository.
+ */
+export type LayoutKind = 'bare-project' | 'bare-inside' | 'plain-clone' | 'empty' | 'occupied';
+export type RepositoryLayout = Readonly<{
+    kind: LayoutKind;
+    path: string;
+    /**
+     * The directory whose git marker produced this classification. It differs
+     * from `path` when the answer came from an ancestor, which is how a plain
+     * subdirectory of a repository is reported; callers that need the target
+     * itself to be the repository must compare the two.
+     */
+    matchedAt?: string;
+    projectRoot?: string;
+    gitDir?: string;
+    worktreeRoot?: string;
+}>;
+/**
+ * Parses any remote git understands: scp-style (`git@host:owner/repo.git`),
+ * https, ssh:// and a plain local path. The repository name comes from here and
+ * nowhere else — in trunk's layout the project folder holds a bare `.git`, so
+ * the folder name is not the project's identity.
+ */
+export declare function parseRemote(url: string, aliases?: SshAliases, workingDirectory?: string): ParsedRemote;
+/**
+ * Reads `Host`/`HostName` pairs out of an ssh config. Parsed here rather than
+ * shelled out to `ssh -G` so it stays fast and testable; this only needs to
+ * cover the common forms, since a miss just leaves the alias unresolved.
+ */
+export declare function parseSshAliases(contents: string): SshAliases;
+/** Best effort: no ssh config, or one that cannot be read, simply means no aliases. */
+export declare function loadSshAliases(configPath?: string): Promise<SshAliases>;
+/**
+ * Turns an alias into the host it really points at. An exact entry wins over a
+ * pattern such as `*.internal`, and an unknown host is returned unchanged.
+ */
+export declare function resolveSshAlias(host: string, aliases: SshAliases): string;
+/**
+ * Works out what a directory is, so a command knows whether to set it up,
+ * refuse it, or resolve upwards to the project it belongs to. A missing
+ * directory counts as empty: that is a target waiting to be created.
+ */
+export declare function detectLayout(path: string, gitOptions?: GitOptions): Promise<RepositoryLayout>;

package/dist/core/repo.js

@@ -0,0 +1,294 @@
+/**
+ * What a repository is and what shape a directory is in: parsing a remote URL
+ * into the identity wt uses, resolving SSH host aliases, and classifying a
+ * directory as a trunk-layout project, a plain clone, empty or occupied.
+ */
+import { readFile, readdir, realpath, stat } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { basename, dirname, isAbsolute, join, resolve } from 'node:path';
+import process from 'node:process';
+import { fileURLToPath } from 'node:url';
+import { gitCommonDirectory, isBareRepository } from './git.js';
+/** Entries an otherwise empty directory may hold and still count as empty. */
+const ignorableEntries = new Set(['.DS_Store', '.localized', 'Thumbs.db']);
+/**
+ * Parses any remote git understands: scp-style (`git@host:owner/repo.git`),
+ * https, ssh:// and a plain local path. The repository name comes from here and
+ * nowhere else — in trunk's layout the project folder holds a bare `.git`, so
+ * the folder name is not the project's identity.
+ */
+export function parseRemote(url, aliases = {}, workingDirectory = process.cwd()) {
+    const value = url.trim();
+    if (!value) {
+        throw new TypeError('Remote URL cannot be empty.');
+    }
+    if (/^[a-z][a-z\d+.-]*:\/\//i.test(value)) {
+        const parsed = new URL(value);
+        if (parsed.protocol === 'file:') {
+            return localRemote(value, fileURLToPath(parsed), workingDirectory);
+        }
+        if (['http:', 'https:', 'ssh:'].includes(parsed.protocol)) {
+            return hostedRemote(value, parsed.hostname, parsed.pathname, aliases);
+        }
+    }
+    // The scp-style form `[user@]host:path` has no scheme to match on. The
+    // Windows check keeps `C:\repo` from being read as a host named C.
+    const scp = /^(?:[^@/]+@)?([^:/]+):(.+)$/.exec(value);
+    if (scp && !looksLikeLocalWindowsPath(value)) {
+        return hostedRemote(value, scp[1], scp[2], aliases);
+    }
+    return localRemote(value, value, workingDirectory);
+}
+/**
+ * Reads `Host`/`HostName` pairs out of an ssh config. Parsed here rather than
+ * shelled out to `ssh -G` so it stays fast and testable; this only needs to
+ * cover the common forms, since a miss just leaves the alias unresolved.
+ */
+export function parseSshAliases(contents) {
+    const aliases = {};
+    // Directives apply to the Host block above them, so the current block is
+    // carried down the file. ssh honours the first value it sees for a host.
+    let hosts = [];
+    for (const originalLine of contents.split(/\r?\n/)) {
+        const line = originalLine.replace(/\s+#.*$/, '').trim();
+        if (!line) {
+            continue;
+        }
+        const parsed = parseSshDirective(line);
+        if (!parsed) {
+            continue;
+        }
+        const { directive, values } = parsed;
+        if (directive.toLowerCase() === 'host') {
+            hosts = values.filter(host => !host.startsWith('!'));
+            continue;
+        }
+        if (directive.toLowerCase() !== 'hostname' || values.length === 0) {
+            continue;
+        }
+        for (const host of hosts) {
+            if (!hasAlias(aliases, host)) {
+                aliases[host] = values[0];
+            }
+        }
+    }
+    return Object.freeze(aliases);
+}
+/** Best effort: no ssh config, or one that cannot be read, simply means no aliases. */
+export async function loadSshAliases(configPath = join(homedir(), '.ssh', 'config')) {
+    try {
+        return parseSshAliases(await readFile(configPath, 'utf8'));
+    }
+    catch {
+        return Object.freeze({});
+    }
+}
+/**
+ * Turns an alias into the host it really points at. An exact entry wins over a
+ * pattern such as `*.internal`, and an unknown host is returned unchanged.
+ */
+export function resolveSshAlias(host, aliases) {
+    const entries = Object.entries(aliases);
+    const exact = entries.find(([alias]) => alias.toLowerCase() === host.toLowerCase());
+    const matched = exact ?? entries.find(([alias]) => hostMatches(alias, host));
+    return matched?.[1].split('%h').join(host) ?? host;
+}
+/**
+ * Works out what a directory is, so a command knows whether to set it up,
+ * refuse it, or resolve upwards to the project it belongs to. A missing
+ * directory counts as empty: that is a target waiting to be created.
+ */
+export async function detectLayout(path, gitOptions = {}) {
+    const resolvedPath = resolve(path);
+    const targetStat = await safeStat(resolvedPath);
+    if (!targetStat) {
+        return layout('empty', resolvedPath);
+    }
+    const target = await realpath(resolvedPath);
+    if (!targetStat.isDirectory()) {
+        return layout('occupied', target);
+    }
+    const targetEntries = await readdir(target);
+    if (targetEntries.every(entry => ignorableEntries.has(entry))) {
+        return layout('empty', target);
+    }
+    return searchLayout(target, target, gitOptions);
+}
+function hostedRemote(url, host, remotePath, aliases) {
+    const parts = remotePath
+        .replace(/^\/+/, '')
+        .replace(/\/+$/, '')
+        .split('/')
+        .filter(Boolean);
+    if (parts.length !== 2) {
+        throw new TypeError(`Remote must contain an owner and repository: ${url}`);
+    }
+    const owner = parts[0];
+    const repo = stripGitSuffix(parts[1]);
+    if (!owner || !repo) {
+        throw new TypeError(`Remote must contain an owner and repository: ${url}`);
+    }
+    return Object.freeze({
+        kind: 'hosted',
+        url,
+        host,
+        realHost: resolveSshAlias(host, aliases),
+        owner,
+        repo,
+        identifier: `${host}/${owner}/${repo}`,
+    });
+}
+function localRemote(url, path, workingDirectory) {
+    const absolutePath = isAbsolute(path)
+        ? resolve(path)
+        : resolve(workingDirectory, path);
+    const identityPath = stripGitSuffix(absolutePath);
+    const repo = basename(identityPath);
+    if (!repo) {
+        throw new TypeError(`Local remote does not name a repository: ${url}`);
+    }
+    return Object.freeze({
+        kind: 'local',
+        url,
+        path: absolutePath,
+        repo,
+        identifier: url.startsWith('file:') ? stripGitSuffix(url) : identityPath,
+    });
+}
+async function layoutFromGitDirectory(candidate, gitOptions) {
+    const { gitDirectory, target, matchedAt, worktreeRoot } = candidate;
+    const commonDirectory = await gitCommonDirectory(gitDirectory, gitOptions);
+    if (!commonDirectory) {
+        return undefined;
+    }
+    const bare = await isBareRepository(commonDirectory, gitOptions);
+    if (bare === undefined) {
+        return undefined;
+    }
+    // In trunk's layout the bare git directory sits at `<project>/.git`, so the
+    // project root is its parent either way.
+    const projectRoot = dirname(commonDirectory);
+    if (!bare) {
+        return layout('plain-clone', target, {
+            matchedAt,
+            projectRoot,
+            gitDir: commonDirectory,
+            worktreeRoot,
+        });
+    }
+    return layout(target === projectRoot ? 'bare-project' : 'bare-inside', target, {
+        matchedAt,
+        projectRoot,
+        gitDir: commonDirectory,
+        worktreeRoot,
+    });
+}
+/**
+ * Walks from the target up towards the filesystem root looking for a git
+ * marker, the way git itself resolves a repository. That is what lets a command
+ * run from inside a worktree or a subdirectory; `matchedAt` records how far up
+ * the answer came from.
+ */
+async function searchLayout(current, target, gitOptions) {
+    // Being inside `<project>/.git` itself: there is no `.git` entry to find here.
+    if (basename(current) === '.git') {
+        const direct = await layoutFromGitDirectory({ gitDirectory: current, target, matchedAt: current }, gitOptions);
+        if (direct) {
+            return direct;
+        }
+    }
+    // A `.git` directory is a repository; a `.git` file is a linked worktree
+    // pointing at one.
+    const marker = join(current, '.git');
+    const markerStat = await safeStat(marker);
+    if (markerStat?.isDirectory()) {
+        const detected = await layoutFromGitDirectory({ gitDirectory: marker, target, matchedAt: current }, gitOptions);
+        if (detected) {
+            return detected;
+        }
+    }
+    else if (markerStat?.isFile()) {
+        const gitDirectory = await gitDirectoryFromFile(marker);
+        if (gitDirectory) {
+            const detected = await layoutFromGitDirectory({ gitDirectory, target, matchedAt: current, worktreeRoot: current }, gitOptions);
+            if (detected) {
+                return detected;
+            }
+        }
+    }
+    const parent = dirname(current);
+    return parent === current
+        ? layout('occupied', target)
+        : searchLayout(parent, target, gitOptions);
+}
+async function gitDirectoryFromFile(path) {
+    try {
+        const contents = await readFile(path, 'utf8');
+        const match = /^gitdir:\s*(.+)\s*$/i.exec(contents.trim());
+        if (!match) {
+            return undefined;
+        }
+        return isAbsolute(match[1])
+            ? resolve(match[1])
+            : resolve(dirname(path), match[1]);
+    }
+    catch {
+        return undefined;
+    }
+}
+async function safeStat(path) {
+    try {
+        return await stat(path);
+    }
+    catch (error) {
+        if (isMissingFileError(error)) {
+            return undefined;
+        }
+        throw error;
+    }
+}
+function layout(kind, path, details = {}) {
+    return Object.freeze({ kind, path, ...details });
+}
+function stripGitSuffix(value) {
+    return value.replace(/\.git$/i, '');
+}
+function looksLikeLocalWindowsPath(value) {
+    return /^[a-z]:[\\/]/i.test(value);
+}
+function hasAlias(aliases, host) {
+    return Object.keys(aliases).some(alias => alias.toLowerCase() === host.toLowerCase());
+}
+function parseSshDirective(line) {
+    const match = /^([^\s=]+)(?:\s*=\s*|\s+)(.+)$/.exec(line);
+    if (!match) {
+        return undefined;
+    }
+    return {
+        directive: match[1],
+        values: match[2].trim().split(/\s+/),
+    };
+}
+function hostMatches(pattern, host) {
+    const specialCharacters = '\\^$.*+?()[]{}|';
+    const expression = [...pattern]
+        .map(character => {
+        if (character === '*') {
+            return '.*';
+        }
+        if (character === '?') {
+            return '.';
+        }
+        return specialCharacters.includes(character)
+            ? `\\${character}`
+            : character;
+    })
+        .join('');
+    return new RegExp(`^${expression}$`, 'i').test(host);
+}
+function isMissingFileError(error) {
+    if (!(error instanceof Error) || !('code' in error)) {
+        return false;
+    }
+    return error.code === 'ENOENT' || error.code === 'ENOTDIR';
+}

package/dist/core/resolve.d.ts

@@ -0,0 +1,127 @@
+/**
+ * Turns flags, adopted values, environment detection and built-in defaults into
+ * the one Settings object consumed by the generator. This module is deliberately
+ * synchronous and headless so scripted and interactive setup share the same path.
+ */
+import { maximumAgents, type AgentId } from './agents.js';
+import type { CliFlags } from './arguments.js';
+import type { PackageDetection, PackageManager } from './detect.js';
+import type { ToolProbe } from './env.js';
+import { type Settings } from './settings.js';
+export declare const setupFieldOrder: readonly ["prefix", "pm", "tmux", "agents", "copyIgnored", "server", "caddy", "mcAlias"];
+export type SetupField = (typeof setupFieldOrder)[number];
+export type SetupValues = Readonly<{
+    prefix: string;
+    pm: PackageManager;
+    tmux: boolean;
+    agents: readonly AgentId[];
+    copyIgnored: boolean;
+    server: boolean;
+    caddy: boolean;
+    mcAlias: boolean;
+}>;
+export type SetupFlags = Readonly<{
+    prefix?: string;
+    pm?: string;
+    tmux?: boolean;
+    agents?: string;
+    copyIgnored?: boolean;
+    server?: boolean;
+    caddy?: boolean;
+    mcAlias?: boolean;
+}>;
+export type FixedSettings = Readonly<Pick<Settings, 'trunkVersion' | 'generatedOn' | 'repoName' | 'hostLabel'> & Partial<Pick<Settings, 'appDir' | 'devScript' | 'scripts'>>>;
+export type ResolveOptions = Readonly<{
+    fixed: FixedSettings;
+    flags?: SetupFlags;
+    /** Values entered by the form. Flags still take precedence over them. */
+    answers?: Partial<SetupValues>;
+    /** Best-effort values read from an existing wt.toml during overwrite. */
+    existing?: Partial<SetupValues>;
+    packageDetection?: PackageDetection;
+    tools?: Pick<ToolProbe, 'tmux' | 'caddy' | 'brew' | 'agents'>;
+    /** Overrides for callers with a command-specific built-in default. */
+    defaults?: Partial<SetupValues>;
+    /** `--yes`: accept every proposed value without opening the form. */
+    acceptDefaults?: boolean;
+}>;
+export type ValueSource = 'flag' | 'answer' | 'existing' | 'detection' | 'built-in' | 'dependency';
+export type ResolutionWarning = Readonly<{
+    field?: SetupField;
+    message: string;
+}>;
+export type AgentOption = Readonly<{
+    id: AgentId;
+    command: string;
+    installed: boolean;
+}>;
+export type CaddyAvailability = Readonly<{
+    kind: 'installed';
+}> | Readonly<{
+    kind: 'brew-installable';
+    executable: string;
+    arguments: readonly ['install', 'caddy'];
+}> | Readonly<{
+    kind: 'missing';
+    installUrl: 'https://caddyserver.com/docs/install';
+}>;
+type QuestionBase<Field extends SetupField, Value> = Readonly<{
+    field: Field;
+    label: string;
+    flag: string;
+    defaultValue: Value;
+    source: Exclude<ValueSource, 'flag' | 'answer' | 'dependency'>;
+}>;
+export type OpenQuestion = (QuestionBase<'prefix', string> & Readonly<{
+    kind: 'text';
+    help: 'keep it unique across your repos';
+}>) | (QuestionBase<'pm', PackageManager> & Readonly<{
+    kind: 'select';
+    options: readonly PackageManager[];
+    needsConfirmation: boolean;
+}>) | (QuestionBase<'tmux', boolean> & Readonly<{
+    kind: 'boolean';
+    installed: boolean;
+}>) | (QuestionBase<'agents', readonly AgentId[]> & Readonly<{
+    kind: 'multi-select';
+    maximum: typeof maximumAgents;
+    options: readonly AgentOption[];
+}>) | (QuestionBase<'copyIgnored', boolean> & Readonly<{
+    kind: 'boolean';
+}>) | (QuestionBase<'server', boolean> & Readonly<{
+    kind: 'boolean';
+}>) | (QuestionBase<'caddy', boolean> & Readonly<{
+    kind: 'boolean';
+    availability: CaddyAvailability;
+}>) | (QuestionBase<'mcAlias', boolean> & Readonly<{
+    kind: 'boolean';
+}>);
+type ResolutionDetails = Readonly<{
+    draft: Settings;
+    questions: readonly OpenQuestion[];
+    sources: Readonly<Record<SetupField, ValueSource>>;
+    warnings: readonly ResolutionWarning[];
+}>;
+export type CompleteResolution = ResolutionDetails & Readonly<{
+    kind: 'complete';
+    settings: Settings;
+}>;
+export type NeedsInputResolution = ResolutionDetails & Readonly<{
+    kind: 'questions';
+    questions: readonly OpenQuestion[];
+}>;
+export type Resolution = CompleteResolution | NeedsInputResolution;
+/** Resolve a setup without reading the terminal or filesystem. */
+export declare function resolve(options: ResolveOptions): Resolution;
+/** Maps Meow's names onto the names used by Settings. */
+export declare function setupFlagsFromCli(flags: CliFlags): SetupFlags;
+export type RerunCommand = Readonly<{
+    arguments: readonly string[];
+    display: string;
+}>;
+/**
+ * Makes a non-interactive rerun explicit and reproducible instead of merely
+ * suggesting `--yes`, whose defaults could change with the machine.
+ */
+export declare function buildRerunCommand(executable: string, originalArguments: readonly string[], resolution: NeedsInputResolution): RerunCommand;
+export {};