@cod3vil/trunk 0.1.1

package/dist/core/generate/aliases.js

@@ -0,0 +1,45 @@
+/** Project-level convenience commands assembled from the enabled hooks. */
+import { usesCaddy } from '../settings.js';
+import { inlineCommand, multilineCommand, shellQuote } from './toml.js';
+const branchTemplate = '{{ branch | sanitize }}';
+export function generateAliases(settings) {
+    const aliases = [];
+    const up = upCommand(settings);
+    if (up) {
+        aliases.push(`up = ${inlineCommand(up)}`);
+    }
+    if (usesCaddy(settings)) {
+        aliases.push(`url = ${multilineCommand(urlAliasBody(settings))}`);
+    }
+    if (settings.mcAlias) {
+        aliases.push(`mc = ${multilineCommand(mcAliasBody)}`);
+    }
+    return aliases.length > 0 ? `[aliases]\n${aliases.join('\n')}` : undefined;
+}
+export function upCommand(settings) {
+    const commands = [];
+    if (settings.tmux || usesCaddy(settings)) {
+        commands.push('wt hook pre-start');
+    }
+    if (settings.server) {
+        commands.push(usesCaddy(settings)
+            ? 'wt hook post-start server proxy'
+            : 'wt hook post-start server');
+    }
+    return commands.length > 0 ? commands.join(' && ') : undefined;
+}
+export function urlAliasBody(settings) {
+    const suffix = shellQuote(`.${settings.hostLabel}.localhost:8080`);
+    return `{% if args %}BRANCH={{ args[0] | sanitize }}{% else %}BRANCH=${branchTemplate}{% endif %}
+HOST_SUFFIX=${suffix}
+URL="http://\${BRANCH}\${HOST_SUFFIX}"
+if command -v open >/dev/null 2>&1; then
+  open "$URL"
+elif command -v xdg-open >/dev/null 2>&1; then
+  xdg-open "$URL"
+else
+  printf '%s\\n' "$URL"
+fi`;
+}
+/** Keep this quoting aligned with Worktrunk's documented editor alias. */
+export const mcAliasBody = `WORKTRUNK_COMMIT__GENERATION__COMMAND='f=$(mktemp); printf "\\n\\n" > "$f"; sed "s/^/# /" >> "$f"; \${EDITOR:-vi} "$f" < /dev/tty > /dev/tty; grep -v "^#" "$f"' wt merge`;

package/dist/core/generate/header.d.ts

@@ -0,0 +1,2 @@
+import { type Settings } from '../settings.js';
+export declare function generateHeader(settings: Settings): string;

package/dist/core/generate/header.js

@@ -0,0 +1,81 @@
+/** Produces the human-maintained contract at the top of every generated file. */
+import { agentCommands, maximumAgents } from '../agents.js';
+import { usesCaddy } from '../settings.js';
+import { commentText } from './toml.js';
+/** Where the description column starts, measured from after the `#   ` indent. */
+const descriptionColumn = 23;
+export function generateHeader(settings) {
+    const lines = [
+        '# Worktree automation shared by everyone on this repo.',
+        '#',
+        `# Generated by trunk ${commentText(settings.trunkVersion)} on ${settings.generatedOn} — edit it freely; trunk won't touch it again.`,
+        '#',
+        '# Setup on a new machine: install worktrunk (`wt`) with its shell integration, then run',
+        '# `wt config approvals add` here (again whenever this file changes).',
+        `# Package manager: ${settings.pm}.`,
+    ];
+    const optionalTools = optionalToolNames(settings);
+    if (optionalTools.length > 0) {
+        lines.push(`# ${joinList(optionalTools)} ${optionalTools.length === 1 ? 'is' : 'are'} optional; each step skips itself when its tool is missing.`);
+    }
+    const environment = environmentLines(settings);
+    if (environment.length > 0) {
+        lines.push('# Each machine can tune the optional steps with env vars in its shell profile:', '#', ...environment, '#');
+    }
+    if (settings.tmux) {
+        lines.push("# P is this repo's tmux session prefix; keep it unique across your repos.");
+    }
+    if (settings.noRemote) {
+        lines.push(`# No git remote yet, so the repo name is written out below. After you add one`, '# (git remote add origin <url>), you can switch these back to', '# {{ remote_repo | lower }}.');
+    }
+    lines.push('# Hook bodies are POSIX sh. Worktrunk template expressions are intentional; avoid', '# introducing shell forms that collide with them (notably shell length expansion).');
+    return lines.join('\n');
+}
+function optionalToolNames(settings) {
+    const names = [];
+    if (settings.tmux) {
+        names.push('tmux');
+    }
+    if (usesCaddy(settings)) {
+        names.push('caddy');
+    }
+    for (const agent of settings.agents) {
+        names.push(agentCommands[agent]);
+    }
+    return names;
+}
+function environmentLines(settings) {
+    const lines = [];
+    if (settings.tmux) {
+        lines.push(settingLine('WT_TMUX=off', 'no tmux session'));
+        if (settings.agents.length > 0) {
+            const agents = JSON.stringify(settings.agents.join(' '));
+            lines.push(settingLine(`WT_AGENTS=${agents}`, 'agents started in the Agents window'), settingLine('', `(default ${agents}; "" starts none; max ${maximumAgents})`));
+        }
+        lines.push(settingLine('WT_EDITOR=hx', 'editor in the Editor window (default $EDITOR, then nvim)'));
+    }
+    if (usesCaddy(settings)) {
+        lines.push(settingLine('WT_PROXY=off', 'no Caddy route'));
+    }
+    return lines;
+}
+/**
+ * One `VAR=value   description` line. A long value pushes its own description
+ * right rather than running into it, so the block stays readable for any agent
+ * list.
+ */
+function settingLine(setting, description) {
+    const padded = setting.length >= descriptionColumn
+        ? `${setting} `
+        : setting.padEnd(descriptionColumn);
+    return `#   ${padded}${description}`;
+}
+function joinList(values) {
+    if (values.length < 2) {
+        return values[0] ?? '';
+    }
+    if (values.length === 2) {
+        return values.join(' and ');
+    }
+    return `${values.slice(0, -1).join(', ')}, and ${values.at(-1)}`;
+}

package/dist/core/generate/index.d.ts

@@ -0,0 +1,8 @@
+/** Deterministically composes a complete project `.config/wt.toml`. */
+import { type Settings } from '../settings.js';
+export type GeneratedHook = Readonly<{
+    type: 'pre-start' | 'post-start' | 'pre-remove';
+    name: string;
+}>;
+export declare function compose(settings: Settings): string;
+export declare function expectedHooks(settings: Settings): readonly GeneratedHook[];

package/dist/core/generate/index.js

@@ -0,0 +1,74 @@
+/** Deterministically composes a complete project `.config/wt.toml`. */
+import { assertSettings, usesCaddy } from '../settings.js';
+import { generateAliases } from './aliases.js';
+import { generateHeader } from './header.js';
+import { generateList, generateUrlPreStart, proxyRemoveBody, proxyStartBody, } from './proxy.js';
+import { generatePostStart } from './steps.js';
+import { generateTmuxPreStart, tmuxRemoveBody } from './tmux.js';
+import { multilineCommand, tomlString } from './toml.js';
+export function compose(settings) {
+    assertSettings(settings);
+    const sections = [
+        generateHeader(settings),
+        generateAliases(settings),
+        generateTmuxPreStart(settings),
+        generateUrlPreStart(settings),
+        generatePostStart(settings, proxyStartBody(settings)),
+        generatePreRemove(settings),
+        generateCopyIgnoredStep(settings),
+        generateList(settings),
+    ].filter(Boolean);
+    return `${sections.join('\n\n')}\n`;
+}
+export function expectedHooks(settings) {
+    const hooks = [];
+    if (settings.tmux) {
+        hooks.push({ type: 'pre-start', name: 'tmux' });
+    }
+    if (usesCaddy(settings)) {
+        hooks.push({ type: 'pre-start', name: 'url' });
+    }
+    if (settings.copyIgnored) {
+        hooks.push({ type: 'post-start', name: 'copy' });
+    }
+    hooks.push({ type: 'post-start', name: 'install' });
+    if (settings.server) {
+        hooks.push({ type: 'post-start', name: 'server' });
+    }
+    if (usesCaddy(settings)) {
+        hooks.push({ type: 'post-start', name: 'proxy' });
+    }
+    if (settings.tmux) {
+        hooks.push({ type: 'pre-remove', name: 'tmux' });
+    }
+    if (usesCaddy(settings)) {
+        hooks.push({ type: 'pre-remove', name: 'proxy' });
+    }
+    return Object.freeze(hooks.map(hook => Object.freeze(hook)));
+}
+/**
+ * Paths a repository already excluded from `wt step copy-ignored`. Only ever
+ * present when adopting a config that had them, so an empty list emits nothing.
+ */
+function generateCopyIgnoredStep(settings) {
+    const excludes = settings.copyIgnoredExclude ?? [];
+    if (!settings.copyIgnored || excludes.length === 0) {
+        return undefined;
+    }
+    const values = excludes.map(value => tomlString(value)).join(', ');
+    return `[step.copy-ignored]\nexclude = [${values}]`;
+}
+function generatePreRemove(settings) {
+    const commands = [];
+    const tmux = tmuxRemoveBody(settings);
+    if (tmux) {
+        commands.push(`tmux = ${multilineCommand(tmux)}`);
+    }
+    const proxy = proxyRemoveBody(settings);
+    if (proxy) {
+        commands.push(`proxy = ${multilineCommand(proxy)}`);
+    }
+    return commands.length > 0
+        ? `[pre-remove]\n${commands.join('\n')}`
+        : undefined;
+}

package/dist/core/generate/proxy.d.ts

@@ -0,0 +1,8 @@
+/** Caddy route lifecycle, terminal URL report, and `wt list` URL fragment. */
+import { type Settings } from '../settings.js';
+export declare function proxyStartBody(settings: Settings): string | undefined;
+export declare function proxyRemoveBody(settings: Settings): string | undefined;
+export declare function generateUrlPreStart(settings: Settings): string | undefined;
+export declare function generateList(settings: Settings): string | undefined;
+/** The generated route with a caller-selected branch placeholder. */
+export declare function routeUrl(settings: Settings, branch: string): string;

package/dist/core/generate/proxy.js

@@ -0,0 +1,56 @@
+/** Caddy route lifecycle, terminal URL report, and `wt list` URL fragment. */
+import { usesCaddy } from '../settings.js';
+import { inlineCommand, multilineCommand, portExpression, repoExpression, shellQuote, } from './toml.js';
+const branchTemplate = '{{ branch | sanitize }}';
+export function proxyStartBody(settings) {
+    if (!usesCaddy(settings)) {
+        return undefined;
+    }
+    const remoteRepository = repoExpression(settings);
+    return `[ "\${WT_PROXY-on}" = off ] && exit 0
+command -v caddy >/dev/null 2>&1 || { echo "caddy not found; skipping proxy"; exit 0; }
+command -v curl >/dev/null 2>&1 || { echo "curl not found; skipping proxy"; exit 0; }
+ID=wt:${remoteRepository}:${branchTemplate}
+HOST=${branchTemplate}.${remoteRepository}.localhost
+PORT=${portExpression(settings)}
+curl -sf --max-time 0.5 http://localhost:2019/config/ >/dev/null || caddy start
+curl -sf http://localhost:2019/config/apps/http/servers/wt >/dev/null || \\
+  curl -sfX PUT http://localhost:2019/config/apps/http/servers/wt \\
+    -H 'Content-Type: application/json' \\
+    -d '{"listen":[":8080"],"automatic_https":{"disable":true},"routes":[]}'
+curl -sf -X DELETE "http://localhost:2019/id/$ID" >/dev/null || true
+PAYLOAD=$(printf '{"@id":"%s","match":[{"host":["%s"]}],"handle":[{"handler":"reverse_proxy","upstreams":[{"dial":"127.0.0.1:%s"}]}]}' "$ID" "$HOST" "$PORT")
+curl -sfX PUT http://localhost:2019/config/apps/http/servers/wt/routes/0 \\
+  -H 'Content-Type: application/json' \\
+  -d "$PAYLOAD"`;
+}
+export function proxyRemoveBody(settings) {
+    if (!usesCaddy(settings)) {
+        return undefined;
+    }
+    return `command -v curl >/dev/null 2>&1 || exit 0
+ID=wt:${repoExpression(settings)}:${branchTemplate}
+curl -sf -X DELETE "http://localhost:2019/id/$ID" >/dev/null || true`;
+}
+export function generateUrlPreStart(settings) {
+    if (!usesCaddy(settings)) {
+        return undefined;
+    }
+    const suffix = shellQuote(`.${settings.hostLabel}.localhost:8080`);
+    const body = `BRANCH=${branchTemplate}
+HOST_SUFFIX=${suffix}
+URL="http://\${BRANCH}\${HOST_SUFFIX}"
+printf '↗ Local server: %s\\n' "$URL"`;
+    return `[[pre-start]]\nurl = ${multilineCommand(body)}`;
+}
+export function generateList(settings) {
+    if (!usesCaddy(settings)) {
+        return undefined;
+    }
+    const url = routeUrl(settings, branchTemplate);
+    return `[list]\nurl = ${inlineCommand(url)}`;
+}
+/** The generated route with a caller-selected branch placeholder. */
+export function routeUrl(settings, branch) {
+    return `http://${branch}.${settings.hostLabel}.localhost:8080`;
+}

package/dist/core/generate/steps.d.ts

@@ -0,0 +1,7 @@
+/** Dependency-copy, install, and development-server pipeline fragments. */
+import type { Settings } from '../settings.js';
+export declare function generatePostStart(settings: Settings, proxyBody: string | undefined): string;
+export declare function installCommand(settings: Settings): string;
+export declare function serverCommand(settings: Settings): string;
+/** The command inside the tether, also used by the setup summary. */
+export declare function developmentCommand(settings: Settings, port?: string): string;

package/dist/core/generate/steps.js

@@ -0,0 +1,88 @@
+import { commentText, inlineCommand, multilineCommand, portExpression, shellQuote, } from './toml.js';
+export function generatePostStart(settings, proxyBody) {
+    const blocks = [];
+    if (settings.copyIgnored) {
+        blocks.push(`[[post-start]]\ncopy = ${inlineCommand('wt step copy-ignored')}`);
+    }
+    blocks.push(`[[post-start]]\ninstall = ${inlineCommand(installCommand(settings))}`);
+    if (settings.server) {
+        const commands = [`server = ${inlineCommand(serverCommand(settings))}`];
+        if (proxyBody) {
+            commands.push(`proxy = ${multilineCommand(proxyBody)}`);
+        }
+        blocks.push(`${serverNotes(settings)}\n[[post-start]]\n${commands.join('\n')}`);
+    }
+    return blocks.join('\n\n');
+}
+export function installCommand(settings) {
+    const directory = settings.appDir ? shellQuote(settings.appDir) : undefined;
+    switch (settings.pm) {
+        case 'npm': {
+            return directory
+                ? `npm --prefix ${directory} install --prefer-offline --no-audit --no-fund`
+                : 'npm install --prefer-offline --no-audit --no-fund';
+        }
+        case 'pnpm': {
+            return directory
+                ? `pnpm --dir ${directory} install --prefer-offline`
+                : 'pnpm install --prefer-offline';
+        }
+        case 'bun': {
+            return directory ? `bun install --cwd=${directory}` : 'bun install';
+        }
+    }
+}
+export function serverCommand(settings) {
+    return `wt step tether -- ${developmentCommand(settings)}`;
+}
+/** The command inside the tether, also used by the setup summary. */
+export function developmentCommand(settings, port = portExpression(settings)) {
+    const script = shellQuote(settings.devScript);
+    const directory = settings.appDir ? shellQuote(settings.appDir) : undefined;
+    let command;
+    switch (settings.pm) {
+        case 'npm': {
+            command = `npm${directory ? ` --prefix ${directory}` : ''} run ${script} -- --port ${port}`;
+            break;
+        }
+        case 'pnpm': {
+            command = `pnpm${directory ? ` --dir ${directory}` : ''} run ${script} --port ${port}`;
+            break;
+        }
+        case 'bun': {
+            // `--cwd` rather than `cd <dir> &&`: the whole command is one argument
+            // list after `tether --`, and a `&&` there would end the tethered
+            // command, leaving the server running loose in the wrong directory.
+            command = `bun${directory ? ` --cwd=${directory}` : ''} run ${script} --port ${port}`;
+            break;
+        }
+    }
+    return command;
+}
+function serverNotes(settings) {
+    const lines = [
+        '# Dev server; `wt step tether` stops it when the worktree is removed, however it is',
+        '# removed. The port hashes repo + branch, so the same branch in two repos gets two ports.',
+        '# Adjust the command if this project needs something else:',
+        `#   port from the environment (Nest, Express):  PORT=<port> ${settings.pm} run start:dev`,
+        `#   another script:                             ${settings.pm} run <script> --port <port>`,
+    ];
+    if (settings.appDir) {
+        // Each package manager spells "run in this directory" differently.
+        const directoryFlag = {
+            npm: `--prefix ${commentText(settings.appDir)}`,
+            pnpm: `--dir ${commentText(settings.appDir)}`,
+            bun: `--cwd=${commentText(settings.appDir)}`,
+        }[settings.pm];
+        lines.push(`#   app in a subfolder:                         ${settings.pm} ${directoryFlag} run ${commentText(settings.devScript)} --port <port>`);
+    }
+    if (settings.pm === 'pnpm') {
+        lines.push('# (pnpm passes a literal "--" through, so do not write `pnpm run dev -- --port`.)');
+    }
+    if (settings.scripts.length > 0) {
+        lines.push(`# Detected package scripts: ${settings.scripts
+            .map(script => commentText(script))
+            .join(', ')}`);
+    }
+    return lines.join('\n');
+}

package/dist/core/generate/tmux.d.ts

@@ -0,0 +1,4 @@
+import { type Settings } from '../settings.js';
+export declare function generateTmuxPreStart(settings: Settings): string | undefined;
+export declare function tmuxStartBody(settings: Settings): string;
+export declare function tmuxRemoveBody(settings: Settings): string | undefined;

package/dist/core/generate/tmux.js

@@ -0,0 +1,98 @@
+/** Creates and tears down the deterministic tmux workspace for one worktree. */
+import { agentCommands, maximumAgents } from '../agents.js';
+import { multilineCommand, shellQuote } from './toml.js';
+const branchTemplate = '{{ branch | sanitize }}';
+const worktreeTemplate = '{{ worktree_path }}';
+export function generateTmuxPreStart(settings) {
+    if (!settings.tmux) {
+        return undefined;
+    }
+    return `[[pre-start]]\ntmux = ${multilineCommand(tmuxStartBody(settings))}`;
+}
+export function tmuxStartBody(settings) {
+    const defaultAgents = settings.agents.join(' ');
+    const commandMappings = Object.entries(agentCommands)
+        .filter(([id, command]) => id !== command)
+        .map(([id, command]) => `  [ "$a" = ${shellQuote(id)} ] && cmd=${shellQuote(command)}`)
+        .join('\n');
+    const agentWindow = settings.agents.length === 0
+        ? ''
+        : `
+AG_W=$(tmux new-window -P -F '#{window_id}' -t "=$S" -c "$W" -n Agents)
+n=0
+for a in \${WT_AGENTS-${defaultAgents}}; do
+  [ "$n" -ge ${maximumAgents} ] && echo "only the first ${maximumAgents} agents are started" && break
+  cmd=$a
+${commandMappings}
+  command -v "$cmd" >/dev/null 2>&1 || continue
+  [ "$n" -gt 0 ] && tmux split-window -h -t "$AG_W" -c "$W"
+  tmux send-keys -t "$AG_W" "$cmd" Enter
+  n=$((n + 1))
+done
+[ "$n" -eq 2 ] && tmux select-layout -t "$AG_W" even-horizontal >/dev/null
+[ "$n" -gt 2 ] && tmux select-layout -t "$AG_W" tiled >/dev/null`;
+    return `command -v tmux >/dev/null 2>&1 || { echo "tmux not found; skipping session"; exit 0; }
+[ "\${WT_TMUX-on}" = off ] && exit 0
+P=${shellQuote(settings.prefix)}
+B=${branchTemplate}
+W=${worktreeTemplate}
+S="\${P}_$B"
+
+# Remove agent credentials before a new tmux server can inherit them.
+for name in $(env | cut -d= -f1); do
+  case $name in
+    CLAUDE*|ANTHROPIC*|OPENCODE*|CODEX*|COPILOT*) unset "$name" ;;
+  esac
+done
+
+if tmux has-session -t "=$S" 2>/dev/null; then
+  session_path=$(tmux display-message -p -t "=$S" '#{session_path}')
+  if [ "$session_path" = "$W" ]; then
+    echo "tmux session $S already exists"
+    exit 0
+  fi
+  tmux kill-session -t "=$S" 2>/dev/null || true
+fi
+
+if ! tmux new-session -d -s "$S" -c "$W" -n Editor; then
+  echo "could not create tmux session $S"
+  exit 0
+fi
+ED_W=$(tmux display-message -p -t "=$S:1" '#{window_id}')
+editor=\${WT_EDITOR-\${EDITOR-nvim}}
+if [ -n "$editor" ] && command -v "$editor" >/dev/null 2>&1; then
+  tmux send-keys -t "$ED_W" "$editor" Enter
+fi${agentWindow}
+TERM_W=$(tmux new-window -P -F '#{window_id}' -t "=$S" -c "$W" -n Terminal)
+tmux split-window -h -t "$TERM_W" -c "$W"
+tmux select-window -t "$TERM_W"
+printf 'tmux session %s ready; attach with: tmux attach -t =%s\\n' "$S" "$S"`;
+}
+export function tmuxRemoveBody(settings) {
+    if (!settings.tmux) {
+        return undefined;
+    }
+    return `command -v tmux >/dev/null 2>&1 || exit 0
+P=${shellQuote(settings.prefix)}
+B=${branchTemplate}
+S="\${P}_$B"
+tmux has-session -t "=$S" 2>/dev/null || exit 0
+PIDS=
+collect_tree() {
+  parent=$1
+  for child in $(pgrep -P "$parent" 2>/dev/null); do
+    collect_tree "$child"
+  done
+  PIDS="$PIDS $parent"
+}
+for pane in $(tmux list-panes -s -t "=$S" -F '#{pane_id}'); do
+  [ "$pane" = "\${TMUX_PANE-}" ] && continue
+  pane_pid=$(tmux display-message -p -t "$pane" '#{pane_pid}')
+  [ -n "$pane_pid" ] && collect_tree "$pane_pid"
+done
+if [ -n "$PIDS" ]; then
+  kill -TERM $PIDS 2>/dev/null || true
+fi
+# Keep this delayed command on one line: tmux drops run-shell commands containing newlines.
+tmux run-shell -b -d 3 "if [ -n '$PIDS' ]; then kill -KILL $PIDS 2>/dev/null || true; fi; tmux kill-session -t '=$S' 2>/dev/null || true"`;
+}

package/dist/core/generate/toml.d.ts

@@ -0,0 +1,16 @@
+/** TOML and shell escaping shared by every generated fragment. */
+import type { Settings } from '../settings.js';
+/**
+ * What stands in for the repository name in a generated template. With an
+ * origin this is Worktrunk's own variable; without one it is the name written
+ * out, because `remote_repo` would render empty.
+ */
+export declare function repoExpression(settings: Settings): string;
+/** The port hashes repo and branch together; the repo half follows the same rule. */
+export declare function portExpression(settings: Settings): string;
+export declare function tomlString(value: string): string;
+export declare function inlineCommand(body: string): string;
+export declare function multilineCommand(body: string): string;
+export declare function shellQuote(value: string): string;
+export declare function commentText(value: string): string;
+export declare function assertShellTemplate(body: string): void;

package/dist/core/generate/toml.js

@@ -0,0 +1,68 @@
+/**
+ * What stands in for the repository name in a generated template. With an
+ * origin this is Worktrunk's own variable; without one it is the name written
+ * out, because `remote_repo` would render empty.
+ */
+export function repoExpression(settings) {
+    return settings.noRemote ? settings.hostLabel : '{{ remote_repo | lower }}';
+}
+/** The port hashes repo and branch together; the repo half follows the same rule. */
+export function portExpression(settings) {
+    return settings.noRemote
+        ? `{{ ('${settings.hostLabel}/' ~ branch) | hash_port }}`
+        : "{{ (remote_repo ~ '/' ~ branch) | hash_port }}";
+}
+const allowedTemplates = Object.freeze([
+    '{{ branch | sanitize }}',
+    '{{ worktree_path }}',
+    '{{ remote_repo | lower }}',
+    "{{ (remote_repo ~ '/' ~ branch) | hash_port }}",
+    '{{ args }}',
+    '{{ args[0] | sanitize }}',
+    '{% if args %}',
+    '{% else %}',
+    '{% endif %}',
+]);
+export function tomlString(value) {
+    return JSON.stringify(value);
+}
+export function inlineCommand(body) {
+    assertShellTemplate(body);
+    return tomlString(body);
+}
+export function multilineCommand(body) {
+    assertShellTemplate(body);
+    if (body.includes("'''")) {
+        throw new TypeError("Generated command contains the TOML delimiter '''.");
+    }
+    return `'''\n${body.trim()}\n'''`;
+}
+export function shellQuote(value) {
+    if (/^[\w@%+=:,./-]+$/i.test(value)) {
+        return value;
+    }
+    return `'${value.split("'").join(`'"'"'`)}'`;
+}
+export function commentText(value) {
+    return value
+        .split(/\0|\r?\n/)
+        .join(' ')
+        .trim();
+}
+export function assertShellTemplate(body) {
+    if (body.includes('${#') || body.includes('{#')) {
+        throw new TypeError('Generated shell collides with Worktrunk template syntax.');
+    }
+    // The no-remote port form carries a literal project name, so it is matched
+    // by shape rather than listed.
+    let remainder = body.replaceAll(/{{ \('[^'{}]*\/' ~ branch\) \| hash_port }}/g, '');
+    for (const template of allowedTemplates) {
+        remainder = remainder.split(template).join('');
+    }
+    if (remainder.includes('{{') || remainder.includes('{%')) {
+        const line = remainder
+            .split(/\r?\n/)
+            .find(value => value.includes('{{') || value.includes('{%'));
+        throw new TypeError(`Unexpected Worktrunk template expression: ${line}`);
+    }
+}

package/dist/core/gh.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Publishing the setup branch. `gh` is optional throughout: without it, or
+ * against a host it cannot speak to, trunk pushes and prints the compare URL
+ * so the user can open the pull request themselves.
+ */
+import { type CommandResult, type CommandRunner } from './process.js';
+import type { ParsedRemote, SshAliases } from './repo.js';
+export type GhOptions = Readonly<{
+    ghPath?: string;
+    gitPath?: string;
+    run?: CommandRunner;
+    env?: NodeJS.ProcessEnv;
+}>;
+/**
+ * `gh` only authenticates against GitHub, so an SSH alias is resolved to its
+ * real host before deciding. A non-GitHub remote still gets a push and a URL.
+ */
+export declare function canOpenPullRequest(remote: ParsedRemote, ghInstalled: boolean): boolean;
+/** Where the user opens the pull request when trunk cannot do it for them. */
+export declare function compareUrl(remote: ParsedRemote, branch: string): string | undefined;
+export declare function pushBranch(worktreePath: string, branch: string, options?: GhOptions): Promise<CommandResult>;
+/**
+ * `--fill` reuses the commit message, which is why the commit body is written
+ * for teammates: it becomes the pull request description.
+ */
+export declare function createPullRequest(worktreePath: string, options?: GhOptions): Promise<CommandResult>;
+/** The two commands trunk prints when it stops after the commit. */
+export declare function publishCommands(branch: string, withPullRequest: boolean): readonly string[];
+export type RepositoryOwner = Readonly<{
+    login: string;
+    kind: 'user' | 'org';
+}>;
+/**
+ * The accounts a repository can be created under: the signed-in user first,
+ * then the organisations they belong to. An empty list means gh could not
+ * answer, which the caller treats as "ask for the owner instead of guessing".
+ */
+export declare function listOwners(options?: GhOptions): Promise<readonly RepositoryOwner[]>;
+/** Which account gh would act as, for the confirmation and for auth errors. */
+export declare function activeAccount(options?: GhOptions): Promise<string | undefined>;
+/**
+ * Creates the repository and nothing else: no push, no clone, no source. trunk
+ * builds the local side itself, so gh only has to make the remote exist.
+ */
+export declare function createRepository(owner: string, name: string, options?: GhOptions & {
+    visibility?: 'private' | 'public';
+}): Promise<CommandResult>;
+/** What to run by hand; trunk never deletes a remote repository itself. */
+export declare function deleteRepositoryCommand(owner: string, name: string): string;
+/**
+ * The SSH URL to use for a new remote. gh reports an https URL, but someone
+ * with several accounts reaches each through its own ssh alias, so the alias
+ * whose resolved host matches is preferred — and among those, one a sibling
+ * project already uses, since that is demonstrably the right account.
+ */
+export declare function sshRemoteUrl(owner: string, name: string, options: Readonly<{
+    realHost: string;
+    aliases: SshAliases;
+    siblingHosts?: readonly string[];
+}>): string;