@cod3vil/trunk 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 theCodeD3vil
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,69 @@
+#!/usr/bin/env node
+/**
+ * Entry point. It parses the command line, checks the machine can run trunk,
+ * hands the work to one command module, and turns the returned Outcome into an
+ * exit code. All the real logic lives in `core/` and `commands/`; nothing here
+ * knows how a project is set up.
+ */
+import process from 'node:process';
+import { parseArguments } from './core/arguments.js';
+import { checkRequiredTools, probe, wtVersionWarning, } from './core/env.js';
+import { reportOutcome, step } from './core/log.js';
+import { guardPlatform } from './core/platform.js';
+import { badUsage, succeed } from './core/result.js';
+import { runClone } from './commands/clone.js';
+import { runInit } from './commands/init.js';
+import { runNew } from './commands/new.js';
+const cli = parseArguments();
+async function dispatch() {
+    const unsupportedPlatform = guardPlatform();
+    if (unsupportedPlatform) {
+        return unsupportedPlatform;
+    }
+    const [command, ...rest] = cli.input;
+    // Only the real commands need tools, so printing usage stays instant and
+    // works on a machine that has neither git nor wt installed.
+    let tools;
+    if (command === 'clone' || command === 'init' || command === 'new') {
+        tools = await probe();
+        const missingTools = checkRequiredTools(tools);
+        if (missingTools) {
+            return missingTools;
+        }
+        // An older wt still works; its templates may just render differently, so
+        // this warns and carries on rather than refusing to run.
+        const versionWarning = wtVersionWarning(tools.wt.version);
+        if (versionWarning) {
+            step('warning', versionWarning);
+        }
+    }
+    switch (command) {
+        case 'clone': {
+            return runClone(rest, cli.flags, tools, {
+                invocation: { executable: 'trunk', arguments: process.argv.slice(2) },
+            });
+        }
+        case 'init': {
+            return runInit(rest, cli.flags, tools, {
+                invocation: { executable: 'trunk', arguments: process.argv.slice(2) },
+            });
+        }
+        case 'new': {
+            return runNew(rest, cli.flags, tools, {
+                invocation: { executable: 'trunk', arguments: process.argv.slice(2) },
+            });
+        }
+        case undefined: {
+            // Printed here rather than through `cli.showHelp`, which exits inside
+            // meow; `process.exit` stays a single call site at the bottom of this file.
+            process.stdout.write(`${cli.help}\n`);
+            return succeed();
+        }
+        default: {
+            return badUsage(`unknown command: ${command}`);
+        }
+    }
+}
+const outcome = await dispatch();
+reportOutcome(outcome);
+process.exit(outcome.code);

package/dist/commands/clone.d.ts

@@ -0,0 +1,6 @@
+import type { CliFlags } from '../core/arguments.js';
+import type { ToolProbe } from '../core/env.js';
+import { type SetupDependencies } from '../core/pipeline.js';
+import { type Outcome } from '../core/result.js';
+export type { SetupDependencies as CloneDependencies } from '../core/pipeline.js';
+export declare function runClone(arguments_: readonly string[], flags: CliFlags, tools: ToolProbe, dependencies?: SetupDependencies): Promise<Outcome>;

package/dist/commands/clone.js

@@ -0,0 +1,114 @@
+/**
+ * `trunk clone <url> [dir]`: from a remote URL to a project on disk, then into
+ * the shared setup pipeline.
+ *
+ * Nothing here ever changes directory: every git call carries `--git-dir` or
+ * `-C`, so the pipeline is safe to run from inside another worktree. And every
+ * step records what it is about to create in the journal before acting, so an
+ * interrupted run can describe or undo precisely what exists.
+ */
+import { join, basename, resolve as resolvePath } from 'node:path';
+import { addWorktree, cloneBare, configureOriginFetch, remoteDefaultBranch, setHeadBranch, } from '../core/git.js';
+import { configureProject, createContext, errorMessage, folderState, interrupted, locateWorktree, outputOf, warnAboutWorktreePath, } from '../core/pipeline.js';
+import { loadSshAliases, parseRemote } from '../core/repo.js';
+import { badUsage } from '../core/result.js';
+import { switchAttached } from '../core/wt.js';
+export async function runClone(arguments_, flags, tools, dependencies = {}) {
+    const [url, directory, ...extra] = arguments_;
+    if (!url) {
+        return badUsage('trunk clone needs a remote URL');
+    }
+    if (extra.length > 0) {
+        return badUsage(`unexpected argument: ${extra[0]}`);
+    }
+    const context = createContext(flags, tools, dependencies);
+    let remote;
+    try {
+        remote = parseRemote(url, await loadSshAliases(), context.cwd);
+    }
+    catch (error) {
+        return badUsage(errorMessage(error));
+    }
+    const projectDirectory = resolvePath(context.cwd, directory ?? (remote.repo || basename(url)));
+    const emptiness = await folderState(projectDirectory);
+    if (emptiness === 'occupied') {
+        return badUsage(`${projectDirectory} already exists and is not empty; choose another folder`);
+    }
+    try {
+        return await pipeline(context, remote, projectDirectory, emptiness);
+    }
+    catch (error) {
+        return interrupted(context, projectDirectory, errorMessage(error));
+    }
+}
+async function pipeline(context, remote, projectDirectory, emptiness) {
+    const gitDirectory = join(projectDirectory, '.git');
+    // Step 2: the bare clone, which is also what creates the folder.
+    if (emptiness === 'missing') {
+        context.journal.record({ kind: 'folder', path: projectDirectory });
+    }
+    context.journal.record({ kind: 'bare-repo', path: gitDirectory });
+    context.report('info', `cloning ${remote.url}`);
+    const cloned = await cloneBare(remote.url, gitDirectory, {
+        ...context.git,
+        attach: context.attach,
+    });
+    if (cloned !== 0) {
+        return interrupted(context, projectDirectory, 'git clone failed');
+    }
+    // Step 3: a bare clone has no fetch refspec, so origin/* would stay empty.
+    const configured = await configureOriginFetch(gitDirectory, context.git);
+    if (configured.code !== 0) {
+        return interrupted(context, projectDirectory, `could not configure the origin refspec: ${outputOf(configured)}`);
+    }
+    // Step 4: the remote decides the default branch; never assume main.
+    const defaultBranch = await remoteDefaultBranch(remote.url, context.git);
+    await setHeadBranch(gitDirectory, defaultBranch, context.git);
+    context.report('success', `default branch ${defaultBranch}`);
+    // Step 5: let wt place the first worktree so it can ask its own question.
+    const defaultWorktree = await createFirstWorktree(context, {
+        remote,
+        projectDirectory,
+        gitDirectory,
+        branch: defaultBranch,
+    });
+    if (!defaultWorktree) {
+        return interrupted(context, projectDirectory, `could not create the ${defaultBranch} worktree`);
+    }
+    return configureProject(context, {
+        remote,
+        projectDirectory,
+        gitDirectory,
+        defaultWorktree,
+        defaultBranch,
+    });
+}
+/**
+ * Worktrunk owns worktree placement, so the attached call is the one that gets
+ * it right. Without a terminal it cannot ask, so trunk falls back to plain git and
+ * says what that will cost.
+ */
+async function createFirstWorktree(context, location) {
+    const { remote, projectDirectory, gitDirectory, branch } = location;
+    const expected = join(projectDirectory, branch.replaceAll('/', '-'));
+    context.journal.record({ kind: 'worktree', path: expected, branch });
+    if (context.interactive) {
+        await switchAttached(projectDirectory, branch, {
+            wtPath: context.wtPath,
+            attach: context.attach,
+            env: context.env,
+        });
+    }
+    else {
+        const added = await addWorktree(gitDirectory, expected, branch, context.git);
+        if (added.code !== 0) {
+            return undefined;
+        }
+        warnAboutWorktreePath(context, remote, expected);
+    }
+    const actual = await locateWorktree(gitDirectory, expected, context.git);
+    if (actual !== expected) {
+        warnAboutWorktreePath(context, remote, actual);
+    }
+    return actual;
+}

package/dist/commands/init.d.ts

@@ -0,0 +1,6 @@
+import type { CliFlags } from '../core/arguments.js';
+import type { ToolProbe } from '../core/env.js';
+import { type SetupDependencies } from '../core/pipeline.js';
+import { type Outcome } from '../core/result.js';
+export type { SetupDependencies as InitDependencies } from '../core/pipeline.js';
+export declare function runInit(arguments_: readonly string[], flags: CliFlags, tools: ToolProbe, dependencies?: SetupDependencies): Promise<Outcome>;

package/dist/commands/init.js

@@ -0,0 +1,235 @@
+/**
+ * `trunk init [dir]`: set up a project that is already on disk in the bare
+ * layout — cloned by hand, already using worktrunk, or left behind by an
+ * interrupted `trunk clone`.
+ *
+ * Everything from the existing-config question onward is the same code
+ * `trunk clone` runs. What is specific here is finding the project, refusing a
+ * plain clone, and repairing whatever a hand-made setup is missing.
+ */
+import { join, resolve as resolvePath } from 'node:path';
+import { adoptConfig } from '../core/adopt.js';
+import { addWorktree, configureOriginFetch, existingDefaultBranch, listWorktrees, originFetchRefspec, remoteDefaultBranch, runGit, setHeadBranch, } from '../core/git.js';
+import { configureProject, confirmStep, createContext, errorMessage, interrupted, locateWorktree, readExistingConfig, warnAboutWorktreePath, } from '../core/pipeline.js';
+import { detectLayout, loadSshAliases, parseRemote, } from '../core/repo.js';
+import { badUsage, unsupportedEnvironment, } from '../core/result.js';
+import { listSessions, manualKillCommands, planRenames, renameSessions, } from '../core/tmuxRename.js';
+import { switchAttached } from '../core/wt.js';
+export async function runInit(arguments_, flags, tools, dependencies = {}) {
+    const [directory, ...extra] = arguments_;
+    if (extra.length > 0) {
+        return badUsage(`unexpected argument: ${extra[0]}`);
+    }
+    const context = createContext(flags, tools, dependencies);
+    const target = resolvePath(context.cwd, directory ?? '.');
+    const layout = await detectLayout(target, context.git);
+    switch (layout.kind) {
+        case 'plain-clone': {
+            return refusePlainClone(context, layout);
+        }
+        case 'empty': {
+            return badUsage(`${target} holds no repository; use \`trunk clone <url> ${directory ?? '<dir>'}\` instead`);
+        }
+        case 'occupied': {
+            return badUsage(`${target} is not a git repository`);
+        }
+        default: {
+            break;
+        }
+    }
+    const projectDirectory = layout.projectRoot ?? target;
+    const gitDirectory = layout.gitDir ?? join(projectDirectory, '.git');
+    try {
+        return await setUpExisting(context, projectDirectory, gitDirectory);
+    }
+    catch (error) {
+        return interrupted(context, projectDirectory, errorMessage(error));
+    }
+}
+async function setUpExisting(context, projectDirectory, gitDirectory) {
+    const url = await originUrl(gitDirectory, context.git);
+    if (!url) {
+        return badUsage(`${projectDirectory} has no origin remote; trunk needs one to name the project`);
+    }
+    let remote;
+    try {
+        remote = parseRemote(url, await loadSshAliases(), context.cwd);
+    }
+    catch (error) {
+        return badUsage(errorMessage(error));
+    }
+    const defaultBranch = await repairDefaultBranch(context, gitDirectory, remote);
+    await repairFetchRefspec(context, gitDirectory);
+    const defaultWorktree = await ensureWorktree(context, {
+        remote,
+        projectDirectory,
+        gitDirectory,
+        branch: defaultBranch,
+    });
+    if (!defaultWorktree) {
+        return interrupted(context, projectDirectory, `could not create the ${defaultBranch} worktree`);
+    }
+    // Adoption runs before the form so the repository's own choices become the
+    // defaults, rather than trunk's.
+    const existing = await readExistingConfig(defaultWorktree);
+    const adoption = existing ? adoptConfig(existing) : undefined;
+    for (const note of adoption?.notes ?? []) {
+        context.report('warning', note.message);
+    }
+    const outcome = await configureProject(context, {
+        remote,
+        projectDirectory,
+        gitDirectory,
+        defaultWorktree,
+        defaultBranch,
+        adopted: adoption?.values,
+        copyIgnoredExclude: adoption?.copyIgnoredExclude,
+        async onSettings(settings) {
+            await offerSessionRenames(context, adoption?.values.prefix, settings.prefix);
+        },
+    });
+    return outcome;
+}
+/**
+ * Sessions are named `<prefix>_<branch>`, so changing the prefix without
+ * renaming them leaves sessions `wt remove` can no longer find. Offered rather
+ * than done: the sessions belong to whoever is working in them.
+ */
+async function offerSessionRenames(context, oldPrefix, newPrefix) {
+    if (!oldPrefix || oldPrefix === newPrefix || !context.tools.tmux.path) {
+        return;
+    }
+    const tmuxPath = context.tools.tmux.path;
+    const sessions = await listSessions({
+        tmuxPath,
+        run: context.run,
+        env: context.env,
+    });
+    const renames = planRenames(sessions, oldPrefix, newPrefix);
+    if (renames.length === 0) {
+        return;
+    }
+    context.report('info', `the prefix changed from ${oldPrefix} to ${newPrefix}; these tmux sessions would be renamed:`);
+    for (const rename of renames) {
+        context.report('info', `  ${rename.from} → ${rename.to}`);
+    }
+    const wanted = await confirmStep(context, 'rename them now?');
+    if (!wanted) {
+        return;
+    }
+    const result = await renameSessions(renames, {
+        tmuxPath,
+        run: context.run,
+        env: context.env,
+    });
+    for (const rename of result.renamed) {
+        context.report('success', `renamed ${rename.from} to ${rename.to}`);
+    }
+    if (result.failed.length > 0) {
+        context.report('warning', '`wt remove` will not find these sessions; kill them by hand:');
+        for (const command of manualKillCommands(result.failed)) {
+            context.report('info', `  ${command}`);
+        }
+    }
+}
+/**
+ * Trunk sets up bare-layout projects and never converts a checkout in place:
+ * the checkout may hold uncommitted work, ignored files and a shell someone is
+ * standing in. It prints the recipe and lets the user decide.
+ */
+async function refusePlainClone(context, layout) {
+    const clone = layout.worktreeRoot ?? layout.projectRoot ?? layout.path;
+    const gitDirectory = layout.gitDir ?? join(clone, '.git');
+    const url = (await originUrl(gitDirectory, context.git)) ?? '<remote url>';
+    const name = clone.split('/').at(-1) ?? 'project';
+    const dirty = await describeUnsavedWork(context, clone);
+    if (dirty.length > 0) {
+        context.report('warning', `${clone} still holds ${dirty.join(' and ')}; keep it until that is safe`);
+    }
+    for (const line of [
+        `${clone} is a normal clone; trunk sets up bare-layout projects.`,
+        '',
+        `  trunk clone ${url} ${name}-wt`,
+        `  cp ${name}/.env* ${name}-wt/<default branch>/`,
+        `  # check nothing uncommitted or unpushed is left in ${name}, then:`,
+        `  rm -rf ${name} && mv ${name}-wt ${name}`,
+    ]) {
+        context.report('info', line);
+    }
+    return unsupportedEnvironment(`${clone} is a normal clone`);
+}
+/** Uncommitted and unpushed work, named so the warning is specific. */
+async function describeUnsavedWork(context, clone) {
+    const found = [];
+    const status = await runGit(['-C', clone, 'status', '--porcelain'], context.git);
+    if (status.code === 0 && status.stdout.trim()) {
+        found.push('uncommitted changes');
+    }
+    const unpushed = await runGit(['-C', clone, 'log', '--branches', '--not', '--remotes', '--oneline'], context.git);
+    if (unpushed.code === 0 && unpushed.stdout.trim()) {
+        found.push('unpushed commits');
+    }
+    return Object.freeze(found);
+}
+/** A hand-made bare clone usually has no refspec, so `origin/*` is empty. */
+async function repairFetchRefspec(context, gitDirectory) {
+    const configured = await runGit(['--git-dir', gitDirectory, 'config', '--get', 'remote.origin.fetch'], context.git);
+    if (configured.code === 0 &&
+        configured.stdout.trim() === originFetchRefspec) {
+        return;
+    }
+    const repaired = await configureOriginFetch(gitDirectory, context.git);
+    context.report(repaired.code === 0 ? 'success' : 'warning', repaired.code === 0
+        ? 'set the origin fetch refspec and fetched'
+        : 'could not set the origin fetch refspec');
+}
+/** HEAD first, then the remote; record it the way wt expects to find it. */
+async function repairDefaultBranch(context, gitDirectory, remote) {
+    const existing = await existingDefaultBranch(gitDirectory, context.git);
+    if (existing) {
+        return existing;
+    }
+    const branch = await remoteDefaultBranch(remote.url, context.git);
+    await setHeadBranch(gitDirectory, branch, context.git);
+    await runGit(['--git-dir', gitDirectory, 'config', 'worktrunk.default-branch', branch], context.git);
+    context.report('success', `recorded the default branch ${branch}`);
+    return branch;
+}
+/**
+ * Reuses the worktree for the default branch when there is one, which is also
+ * what makes `trunk init` the resume command after an interrupted clone.
+ */
+async function ensureWorktree(context, location) {
+    const { remote, projectDirectory, gitDirectory, branch } = location;
+    const expected = join(projectDirectory, branch.replaceAll('/', '-'));
+    const worktrees = await listWorktrees(gitDirectory, context.git);
+    const existing = await locateWorktree(gitDirectory, expected, context.git);
+    if (worktrees.includes(existing) && existing !== projectDirectory) {
+        return existing;
+    }
+    context.journal.record({ kind: 'worktree', path: expected, branch });
+    if (context.interactive) {
+        await switchAttached(projectDirectory, branch, {
+            wtPath: context.wtPath,
+            attach: context.attach,
+            env: context.env,
+        });
+    }
+    else {
+        const added = await addWorktree(gitDirectory, expected, branch, context.git);
+        if (added.code !== 0) {
+            return undefined;
+        }
+        warnAboutWorktreePath(context, remote, expected);
+    }
+    const actual = await locateWorktree(gitDirectory, expected, context.git);
+    if (actual !== expected) {
+        context.journal.relocate(expected, actual);
+        warnAboutWorktreePath(context, remote, actual);
+    }
+    return actual;
+}
+async function originUrl(gitDirectory, options) {
+    const result = await runGit(['--git-dir', gitDirectory, 'config', '--get', 'remote.origin.url'], options);
+    return result.code === 0 ? result.stdout.trim() || undefined : undefined;
+}

package/dist/commands/new.d.ts

@@ -0,0 +1,6 @@
+import type { CliFlags } from '../core/arguments.js';
+import type { ToolProbe } from '../core/env.js';
+import { type SetupDependencies } from '../core/pipeline.js';
+import { type Outcome } from '../core/result.js';
+export type { SetupDependencies as NewDependencies } from '../core/pipeline.js';
+export declare function runNew(arguments_: readonly string[], flags: CliFlags, tools: ToolProbe, dependencies?: SetupDependencies): Promise<Outcome>;