@cod3vil/trunk 0.1.1

package/dist/core/resolve.js

@@ -0,0 +1,488 @@
+/**
+ * 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 { agentCommands, agentIds, isAgentId, maximumAgents, } from './agents.js';
+import { initials, validatePrefix } from './prefix.js';
+import { assertSettings, settingsDefaults } from './settings.js';
+export const setupFieldOrder = Object.freeze([
+    'prefix',
+    'pm',
+    'tmux',
+    'agents',
+    'copyIgnored',
+    'server',
+    'caddy',
+    'mcAlias',
+]);
+const packageManagers = Object.freeze(['npm', 'pnpm', 'bun']);
+const caddyInstallUrl = 'https://caddyserver.com/docs/install';
+/** Resolve a setup without reading the terminal or filesystem. */
+export function resolve(options) {
+    const warnings = (options.packageDetection?.warnings ?? []).map(message => Object.freeze({ message }));
+    const flags = parseFlags(options.flags ?? {});
+    const answers = validateValues(options.answers ?? {}, 'answer');
+    const existing = sanitizeExisting(options.existing ?? {}, warnings);
+    const detected = detectionValues(options);
+    const defaults = builtInValues(options);
+    const selected = selectValues({
+        flags,
+        answers,
+        existing,
+        detected,
+        defaults,
+    });
+    normalizeDependencies(selected, flags);
+    warnAboutPackageManagerMismatch(existing, options.packageDetection, warnings);
+    const questions = options.acceptDefaults
+        ? []
+        : setupFieldOrder
+            .filter(field => shouldAsk(field, selected))
+            .map(field => questionFor(field, selected, options));
+    const draft = createSettings(options, selected.values);
+    const sources = Object.freeze({ ...selected.sources });
+    const frozenWarnings = Object.freeze(warnings);
+    if (questions.length > 0) {
+        return Object.freeze({
+            kind: 'questions',
+            draft,
+            questions: Object.freeze(questions),
+            sources,
+            warnings: frozenWarnings,
+        });
+    }
+    assertSettings(draft);
+    return Object.freeze({
+        kind: 'complete',
+        settings: draft,
+        draft,
+        questions: Object.freeze([]),
+        sources,
+        warnings: frozenWarnings,
+    });
+}
+/** Maps Meow's names onto the names used by Settings. */
+export function setupFlagsFromCli(flags) {
+    return Object.freeze({
+        prefix: flags.prefix,
+        pm: flags.pm,
+        tmux: flags.tmux,
+        agents: flags.agents,
+        copyIgnored: flags.copyIgnored,
+        server: flags.server,
+        caddy: flags.caddy,
+        mcAlias: flags.mc,
+    });
+}
+/**
+ * Makes a non-interactive rerun explicit and reproducible instead of merely
+ * suggesting `--yes`, whose defaults could change with the machine.
+ */
+export function buildRerunCommand(executable, originalArguments, resolution) {
+    const separator = originalArguments.indexOf('--');
+    const beforeSeparator = separator === -1
+        ? [...originalArguments]
+        : originalArguments.slice(0, separator);
+    const afterSeparator = separator === -1 ? [] : originalArguments.slice(separator);
+    const added = resolution.questions.map(question => questionArgument(question));
+    const arguments_ = Object.freeze([
+        ...beforeSeparator,
+        ...added,
+        ...afterSeparator,
+    ]);
+    return Object.freeze({
+        arguments: arguments_,
+        display: [executable, ...arguments_]
+            .map(argument => shellQuote(argument))
+            .join(' '),
+    });
+}
+function builtInValues(options) {
+    const values = {
+        prefix: initials(options.fixed.repoName),
+        pm: 'npm',
+        tmux: settingsDefaults.tmux,
+        agents: settingsDefaults.agents,
+        copyIgnored: settingsDefaults.copyIgnored,
+        server: settingsDefaults.server,
+        caddy: settingsDefaults.caddy,
+        mcAlias: settingsDefaults.mcAlias,
+        ...options.defaults,
+    };
+    return {
+        ...values,
+        pm: parsePackageManager(values.pm, 'default package manager'),
+        agents: validateAgents(values.agents),
+    };
+}
+function detectionValues(options) {
+    const detected = {};
+    if (options.packageDetection) {
+        detected.pm = options.packageDetection.packageManager;
+    }
+    if (options.tools) {
+        detected.agents = Object.freeze(agentIds
+            .filter(id => options.tools?.agents[id].path !== undefined)
+            .slice(0, maximumAgents));
+        detected.caddy = options.tools.caddy.path !== undefined;
+    }
+    return detected;
+}
+function selectValues({ flags, answers, existing, detected, defaults, }) {
+    const values = { ...defaults };
+    const sources = {
+        prefix: 'built-in',
+        pm: 'built-in',
+        tmux: 'built-in',
+        agents: 'built-in',
+        copyIgnored: 'built-in',
+        server: 'built-in',
+        caddy: 'built-in',
+        mcAlias: 'built-in',
+    };
+    const answered = {
+        prefix: false,
+        pm: false,
+        tmux: false,
+        agents: false,
+        copyIgnored: false,
+        server: false,
+        caddy: false,
+        mcAlias: false,
+    };
+    for (const field of setupFieldOrder) {
+        if (hasValue(flags, field)) {
+            setSelected(field, flags[field], 'flag', true);
+        }
+        else if (hasValue(answers, field)) {
+            setSelected(field, answers[field], 'answer', true);
+        }
+        else if (hasValue(existing, field)) {
+            setSelected(field, existing[field], 'existing', false);
+        }
+        else if (hasValue(detected, field)) {
+            setSelected(field, detected[field], 'detection', false);
+        }
+        else {
+            setSelected(field, defaults[field], 'built-in', false);
+        }
+    }
+    return { values, sources, answered };
+    function setSelected(field, value, source, isAnswered) {
+        values[field] = value;
+        sources[field] = source;
+        answered[field] = isAnswered;
+    }
+}
+function normalizeDependencies(selected, flags) {
+    if (!selected.values.tmux) {
+        if (hasValue(flags, 'agents') && flags.agents.length > 0) {
+            throw new TypeError('Agents require --tmux; remove --no-tmux or use --agents=.');
+        }
+        selected.values.agents = Object.freeze([]);
+        selected.sources.agents = 'dependency';
+        selected.answered.agents = true;
+    }
+    if (!selected.values.server) {
+        if (hasValue(flags, 'caddy') && flags.caddy) {
+            throw new TypeError('Caddy requires --server; remove --no-server or use --no-caddy.');
+        }
+        selected.values.caddy = false;
+        selected.sources.caddy = 'dependency';
+        selected.answered.caddy = true;
+    }
+}
+function shouldAsk(field, selected) {
+    if (selected.answered[field]) {
+        return false;
+    }
+    if (field === 'agents') {
+        return selected.values.tmux;
+    }
+    if (field === 'caddy') {
+        return selected.values.server;
+    }
+    return true;
+}
+function questionFor(field, selected, options) {
+    const source = selected.sources[field];
+    switch (field) {
+        case 'prefix': {
+            return Object.freeze({
+                field,
+                kind: 'text',
+                label: 'prefix',
+                flag: '--prefix',
+                defaultValue: selected.values.prefix,
+                source,
+                help: 'keep it unique across your repos',
+            });
+        }
+        case 'pm': {
+            return Object.freeze({
+                field,
+                kind: 'select',
+                label: 'package manager',
+                flag: '--pm',
+                defaultValue: selected.values.pm,
+                source,
+                options: packageManagers,
+                needsConfirmation: options.packageDetection?.needsConfirmation ?? false,
+            });
+        }
+        case 'tmux': {
+            return Object.freeze({
+                field,
+                kind: 'boolean',
+                label: 'tmux session',
+                flag: '--tmux/--no-tmux',
+                defaultValue: selected.values.tmux,
+                source,
+                installed: options.tools?.tmux.path !== undefined,
+            });
+        }
+        case 'agents': {
+            return Object.freeze({
+                field,
+                kind: 'multi-select',
+                label: 'agents',
+                flag: '--agents',
+                defaultValue: Object.freeze([...selected.values.agents]),
+                source,
+                maximum: maximumAgents,
+                options: Object.freeze(agentIds.map(id => Object.freeze({
+                    id,
+                    command: agentCommands[id],
+                    installed: options.tools?.agents[id].path !== undefined,
+                }))),
+            });
+        }
+        case 'copyIgnored': {
+            return booleanQuestion({
+                field,
+                label: 'copy-ignored',
+                flag: '--copy/--no-copy',
+                defaultValue: selected.values.copyIgnored,
+                source,
+            });
+        }
+        case 'server': {
+            return booleanQuestion({
+                field,
+                label: 'dev server',
+                flag: '--server/--no-server',
+                defaultValue: selected.values.server,
+                source,
+            });
+        }
+        case 'caddy': {
+            return Object.freeze({
+                field,
+                kind: 'boolean',
+                label: options.tools?.caddy.path === undefined
+                    ? 'include Caddy anyway'
+                    : 'Caddy route',
+                flag: '--caddy/--no-caddy',
+                defaultValue: selected.values.caddy,
+                source,
+                availability: caddyAvailability(options.tools),
+            });
+        }
+        case 'mcAlias': {
+            return booleanQuestion({
+                field,
+                label: 'mc alias',
+                flag: '--mc/--no-mc',
+                defaultValue: selected.values.mcAlias,
+                source,
+            });
+        }
+    }
+}
+function booleanQuestion(properties) {
+    return Object.freeze({
+        ...properties,
+        kind: 'boolean',
+    });
+}
+function caddyAvailability(tools) {
+    if (tools?.caddy.path) {
+        return Object.freeze({ kind: 'installed' });
+    }
+    if (tools?.brew.path) {
+        return Object.freeze({
+            kind: 'brew-installable',
+            executable: tools.brew.path,
+            arguments: Object.freeze(['install', 'caddy']),
+        });
+    }
+    return Object.freeze({ kind: 'missing', installUrl: caddyInstallUrl });
+}
+function createSettings(options, values) {
+    const appDirectory = options.fixed.appDir ?? options.packageDetection?.appDir;
+    return Object.freeze({
+        trunkVersion: options.fixed.trunkVersion,
+        generatedOn: options.fixed.generatedOn,
+        repoName: options.fixed.repoName,
+        hostLabel: options.fixed.hostLabel,
+        prefix: values.prefix,
+        pm: values.pm,
+        ...(appDirectory ? { appDir: appDirectory } : {}),
+        tmux: values.tmux,
+        agents: Object.freeze([...values.agents]),
+        editorWindow: true,
+        copyIgnored: values.copyIgnored,
+        server: values.server,
+        caddy: values.caddy,
+        mcAlias: values.mcAlias,
+        devScript: options.fixed.devScript ?? settingsDefaults.devScript,
+        scripts: Object.freeze([
+            ...(options.fixed.scripts ?? options.packageDetection?.scripts ?? []),
+        ]),
+    });
+}
+function parseFlags(flags) {
+    const values = {};
+    if (flags.prefix !== undefined) {
+        values.prefix = flags.prefix;
+    }
+    if (flags.pm !== undefined) {
+        values.pm = parsePackageManager(flags.pm, '--pm');
+    }
+    if (flags.tmux !== undefined) {
+        values.tmux = flags.tmux;
+    }
+    if (flags.agents !== undefined) {
+        values.agents = parseAgents(flags.agents);
+    }
+    if (flags.copyIgnored !== undefined) {
+        values.copyIgnored = flags.copyIgnored;
+    }
+    if (flags.server !== undefined) {
+        values.server = flags.server;
+    }
+    if (flags.caddy !== undefined) {
+        values.caddy = flags.caddy;
+    }
+    if (flags.mcAlias !== undefined) {
+        values.mcAlias = flags.mcAlias;
+    }
+    return validateValues(values, 'flag');
+}
+function validateValues(values, source) {
+    const validated = { ...values };
+    if (values.prefix !== undefined) {
+        const result = validatePrefix(values.prefix);
+        if (!result.valid) {
+            throw new TypeError(result.reason);
+        }
+    }
+    if (values.pm !== undefined) {
+        validated.pm = parsePackageManager(values.pm, `${source} package manager`);
+    }
+    if (values.agents !== undefined) {
+        validated.agents = validateAgents(values.agents);
+    }
+    return validated;
+}
+function sanitizeExisting(values, warnings) {
+    const valid = {};
+    for (const field of setupFieldOrder) {
+        if (!hasValue(values, field)) {
+            continue;
+        }
+        try {
+            Object.assign(valid, validateValues({ [field]: values[field] }, 'default'));
+        }
+        catch (error) {
+            warnings.push(Object.freeze({
+                field,
+                message: `Ignoring invalid existing ${field}: ${errorMessage(error)}`,
+            }));
+        }
+    }
+    return valid;
+}
+function parsePackageManager(value, name) {
+    if (packageManagers.includes(value)) {
+        return value;
+    }
+    throw new TypeError(`${name} must be npm, pnpm, or bun.`);
+}
+function parseAgents(value) {
+    if (value === '') {
+        return Object.freeze([]);
+    }
+    const values = value.split(',').map(agent => agent.trim());
+    if (values.some(agent => agent.length === 0)) {
+        throw new TypeError('--agents must be a comma-separated list without empty entries.');
+    }
+    return validateAgents(values);
+}
+function validateAgents(values) {
+    for (const value of values) {
+        if (!isAgentId(value)) {
+            throw new TypeError(`Unknown agent "${value}"; choose from ${agentIds.join(',')}.`);
+        }
+    }
+    if (new Set(values).size !== values.length) {
+        throw new TypeError('Agents must not contain duplicates.');
+    }
+    if (values.length > maximumAgents) {
+        throw new TypeError(`max ${maximumAgents} (2×2 grid)`);
+    }
+    const selected = new Set(values);
+    return Object.freeze(agentIds.filter(id => selected.has(id)));
+}
+function warnAboutPackageManagerMismatch(existing, detection, warnings) {
+    if (existing.pm && detection && existing.pm !== detection.packageManager) {
+        warnings.push(Object.freeze({
+            field: 'pm',
+            message: `Existing config uses ${existing.pm}, but lockfile detection found ${detection.packageManager}.`,
+        }));
+    }
+}
+function questionArgument(question) {
+    switch (question.field) {
+        case 'prefix': {
+            return `--prefix=${question.defaultValue}`;
+        }
+        case 'pm': {
+            return `--pm=${question.defaultValue}`;
+        }
+        case 'agents': {
+            return `--agents=${question.defaultValue.join(',')}`;
+        }
+        case 'tmux': {
+            return question.defaultValue ? '--tmux' : '--no-tmux';
+        }
+        case 'copyIgnored': {
+            return question.defaultValue ? '--copy' : '--no-copy';
+        }
+        case 'server': {
+            return question.defaultValue ? '--server' : '--no-server';
+        }
+        case 'caddy': {
+            return question.defaultValue ? '--caddy' : '--no-caddy';
+        }
+        case 'mcAlias': {
+            return question.defaultValue ? '--mc' : '--no-mc';
+        }
+    }
+}
+function shellQuote(value) {
+    return /^[\w@%+=:,./-]+$/.test(value)
+        ? value
+        : `'${value.replaceAll("'", `'\\''`)}'`;
+}
+function hasValue(value, key) {
+    if (typeof value !== 'object' || value === null) {
+        return false;
+    }
+    return (Object.hasOwn(value, key) &&
+        value[key] !== undefined);
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/dist/core/result.d.ts

@@ -0,0 +1,27 @@
+/**
+ * How every command reports back. Commands return an Outcome instead of exiting
+ * themselves, so `cli.tsx` stays the one place that touches `process.exit` and
+ * the exit code of any run is easy to follow.
+ */
+/** Scripts depend on these numbers, so treat them as part of the public API. */
+export declare const exitCodes: {
+    readonly success: 0;
+    /** An external operation failed: git, wt or gh returned an error. */
+    readonly operationFailed: 1;
+    /** The command line itself was wrong: unknown command, missing argument. */
+    readonly badUsage: 2;
+    /** The machine cannot run trunk: Windows, or git/wt missing. */
+    readonly unsupportedEnvironment: 3;
+    /** The user declined a prompt or interrupted the run. */
+    readonly userAborted: 4;
+};
+export type ExitCode = (typeof exitCodes)[keyof typeof exitCodes];
+export type Outcome = {
+    code: ExitCode;
+    message?: string;
+};
+export declare function succeed(message?: string): Outcome;
+export declare function operationFailed(message: string): Outcome;
+export declare function badUsage(message: string): Outcome;
+export declare function unsupportedEnvironment(message: string): Outcome;
+export declare function userAborted(message?: string): Outcome;

package/dist/core/result.js

@@ -0,0 +1,32 @@
+/**
+ * How every command reports back. Commands return an Outcome instead of exiting
+ * themselves, so `cli.tsx` stays the one place that touches `process.exit` and
+ * the exit code of any run is easy to follow.
+ */
+/** Scripts depend on these numbers, so treat them as part of the public API. */
+export const exitCodes = {
+    success: 0,
+    /** An external operation failed: git, wt or gh returned an error. */
+    operationFailed: 1,
+    /** The command line itself was wrong: unknown command, missing argument. */
+    badUsage: 2,
+    /** The machine cannot run trunk: Windows, or git/wt missing. */
+    unsupportedEnvironment: 3,
+    /** The user declined a prompt or interrupted the run. */
+    userAborted: 4,
+};
+export function succeed(message) {
+    return { code: exitCodes.success, message };
+}
+export function operationFailed(message) {
+    return { code: exitCodes.operationFailed, message };
+}
+export function badUsage(message) {
+    return { code: exitCodes.badUsage, message };
+}
+export function unsupportedEnvironment(message) {
+    return { code: exitCodes.unsupportedEnvironment, message };
+}
+export function userAborted(message = 'setup aborted') {
+    return { code: exitCodes.userAborted, message };
+}

package/dist/core/settings.d.ts

@@ -0,0 +1,51 @@
+/**
+ * The complete input to the wt.toml generator. Keeping runtime detection and
+ * clocks outside this type makes composition deterministic and easy to test.
+ */
+import { type AgentId } from './agents.js';
+import type { PackageManager } from './detect.js';
+export type Settings = Readonly<{
+    trunkVersion: string;
+    generatedOn: string;
+    repoName: string;
+    hostLabel: string;
+    prefix: string;
+    pm: PackageManager;
+    appDir?: string;
+    tmux: boolean;
+    agents: readonly AgentId[];
+    editorWindow: true;
+    copyIgnored: boolean;
+    server: boolean;
+    caddy: boolean;
+    mcAlias: boolean;
+    devScript: string;
+    scripts: readonly string[];
+    /**
+     * Extra paths for `[step.copy-ignored]`. trunk never proposes these; they are
+     * carried over verbatim when adopting a hand-written config, so a repository
+     * that already excludes something does not lose it on overwrite.
+     */
+    copyIgnoredExclude?: readonly string[];
+    /**
+     * A project created before its remote exists. `remote_repo` renders empty
+     * without an origin, and every URL-bearing template is built from it, so the
+     * project name is written out literally instead.
+     */
+    noRemote?: boolean;
+}>;
+export declare const settingsDefaults: Readonly<{
+    tmux: true;
+    agents: readonly AgentId[];
+    editorWindow: true;
+    copyIgnored: true;
+    server: true;
+    caddy: true;
+    mcAlias: true;
+    devScript: "dev";
+    scripts: readonly string[];
+}>;
+/** Rejects values that cannot be represented safely by the generated config. */
+export declare function assertSettings(settings: Settings): void;
+/** Caddy has nothing to route when the development server is disabled. */
+export declare function usesCaddy(settings: Settings): boolean;

package/dist/core/settings.js

@@ -0,0 +1,83 @@
+/**
+ * The complete input to the wt.toml generator. Keeping runtime detection and
+ * clocks outside this type makes composition deterministic and easy to test.
+ */
+import { isAgentId, maximumAgents } from './agents.js';
+import { validatePrefix } from './prefix.js';
+export const settingsDefaults = Object.freeze({
+    tmux: true,
+    agents: Object.freeze([]),
+    editorWindow: true,
+    copyIgnored: true,
+    server: true,
+    caddy: true,
+    mcAlias: true,
+    devScript: 'dev',
+    scripts: Object.freeze([]),
+});
+/** Rejects values that cannot be represented safely by the generated config. */
+export function assertSettings(settings) {
+    assertSingleLine('trunkVersion', settings.trunkVersion);
+    assertDate(settings.generatedOn);
+    assertSingleLine('repoName', settings.repoName);
+    assertSingleLine('hostLabel', settings.hostLabel);
+    assertSingleLine('devScript', settings.devScript);
+    if (settings.hostLabel !== settings.repoName.toLowerCase()) {
+        throw new TypeError('hostLabel must be the lowercase repoName.');
+    }
+    const prefix = validatePrefix(settings.prefix);
+    if (!prefix.valid) {
+        throw new TypeError(prefix.reason);
+    }
+    if (settings.agents.length > maximumAgents) {
+        throw new TypeError(`At most ${maximumAgents} agents can be generated.`);
+    }
+    if (!settings.tmux && settings.agents.length > 0) {
+        throw new TypeError('Agents require the tmux session.');
+    }
+    if (new Set(settings.agents).size !== settings.agents.length) {
+        throw new TypeError('Agent ids must be unique.');
+    }
+    for (const agent of settings.agents) {
+        const value = agent;
+        if (!isAgentId(value)) {
+            throw new TypeError(`Unknown agent id: ${value}`);
+        }
+    }
+    if (settings.appDir) {
+        assertRelativePath(settings.appDir);
+    }
+    for (const script of settings.scripts) {
+        assertSingleLine('script name', script);
+    }
+    for (const exclude of settings.copyIgnoredExclude ?? []) {
+        assertSingleLine('copy-ignored exclude', exclude);
+    }
+}
+/** Caddy has nothing to route when the development server is disabled. */
+export function usesCaddy(settings) {
+    return settings.server && settings.caddy;
+}
+function assertDate(value) {
+    if (!/^\d{4}-\d{2}-\d{2}$/.test(value)) {
+        throw new TypeError('generatedOn must use YYYY-MM-DD.');
+    }
+    const parsed = new Date(`${value}T00:00:00.000Z`);
+    if (Number.isNaN(parsed.valueOf()) ||
+        !parsed.toISOString().startsWith(value)) {
+        throw new TypeError('generatedOn must be a real calendar date.');
+    }
+}
+function assertSingleLine(name, value) {
+    if (!value || /[\0\r\n]/.test(value)) {
+        throw new TypeError(`${name} must be a non-empty single line.`);
+    }
+}
+function assertRelativePath(value) {
+    assertSingleLine('appDir', value);
+    if (value.startsWith('/') ||
+        value.startsWith('~') ||
+        value.split(/[\\/]/).includes('..')) {
+        throw new TypeError('appDir must be a relative path inside the worktree.');
+    }
+}