alignfirst 0.1.0-beta.0

package/dist/commands/plans.js

@@ -0,0 +1,154 @@
+import { existsSync, mkdirSync, realpathSync, statSync } from "node:fs";
+import { basename, dirname, join, resolve } from "node:path";
+import { parseArgs } from "node:util";
+import { CliError } from "../cli-error.js";
+import { assertMainWorktreeRoot } from "../git.js";
+import { parseCommandArgs } from "../parse-args.js";
+import { archiveEntry, archiveThresholdDays, autoArchive } from "../plans/archive.js";
+import { linkPlans } from "../plans/link.js";
+import { resolvePlansMode } from "../plans/mode.js";
+export function runPlans(ctx, args) {
+    const [command, ...rest] = args;
+    switch (command) {
+        case "setup":
+            return runSetup(ctx, rest);
+        case "check":
+            return runCheck(ctx, rest);
+        case "archive":
+            return runArchive(ctx, rest);
+        case "auto-archive":
+            return runAutoArchive(ctx, rest);
+        case "--help":
+        case "-h":
+            ctx.stdout.write(plansUsage(ctx));
+            return 0;
+        default:
+            throw new CliError(`Unknown or missing plans command.\n\n${plansUsage(ctx)}`);
+    }
+}
+function plansUsage(ctx) {
+    return `Usage:
+  ${ctx.form} plans setup <clone-dir> [--folder <name>]
+  ${ctx.form} plans check
+  ${ctx.form} plans archive <ticket-id | path>
+  ${ctx.form} plans auto-archive
+`;
+}
+function runSetup(ctx, args) {
+    const usage = `Usage: ${ctx.form} plans setup <clone-dir> [--folder <name>]\n`;
+    const parsed = parseSetupArgs(ctx, args, usage);
+    if (parsed === undefined)
+        return 0;
+    assertMainWorktreeRoot(ctx.cwd);
+    const cloneDir = resolve(ctx.cwd, parsed.dir);
+    checkClone(ctx, cloneDir);
+    const projectDir = join(cloneDir, parsed.folder);
+    mkdirSync(projectDir, { recursive: true });
+    linkPlans(ctx, projectDir);
+    return 0;
+}
+function parseSetupArgs(ctx, args, usage) {
+    const { values, positionals } = parseCommandArgs(usage, () => parseArgs({
+        args,
+        options: {
+            folder: { type: "string" },
+            help: { type: "boolean", short: "h", default: false },
+        },
+        strict: true,
+        allowPositionals: true,
+    }));
+    if (values.help) {
+        ctx.stdout.write(usage);
+        return;
+    }
+    if (positionals.length !== 1)
+        throw new CliError(usage.trimEnd());
+    const configFolder = ctx.projectConfig?.config.plans?.folder;
+    if (values.folder !== undefined && configFolder !== undefined)
+        throw new CliError(".alignfirst.json already sets plans.folder; drop --folder.");
+    const folder = values.folder ?? configFolder;
+    if (folder === undefined)
+        throw new CliError("Pass --folder <name> or set plans.folder in .alignfirst.json.");
+    return { dir: positionals[0], folder };
+}
+function checkClone(ctx, cloneDir) {
+    if (!existsSync(cloneDir))
+        throw new CliError(`${cloneDir} does not exist. Clone the team plans repository there first (see the instruction file).`);
+    if (!existsSync(join(cloneDir, ".git")))
+        throw new CliError(`${cloneDir} is not a git repository. Point ${ctx.form} plans setup at a clone of the team plans repository.`);
+    if (realpathSync(cloneDir) === realpathSync(ctx.cwd))
+        throw new CliError(`${cloneDir} is the product repository itself. Point ${ctx.form} plans setup at a clone of the team plans repository.`);
+}
+function runCheck(ctx, args) {
+    const usage = `Usage: ${ctx.form} plans check\n`;
+    if (handleBareHelp(ctx, args, usage))
+        return 0;
+    const mode = resolvePlansMode(ctx.cwd, ctx.form);
+    if (mode.kind === "shared")
+        ctx.stdout.write(".plans is linked to the team plans repository.\n");
+    else
+        ctx.stdout.write(".plans is a local directory (local plans mode): synchronization is disabled.\n");
+    return 0;
+}
+function handleBareHelp(ctx, args, usage) {
+    const { values, positionals } = parseCommandArgs(usage, () => parseArgs({
+        args,
+        options: { help: { type: "boolean", short: "h", default: false } },
+        strict: true,
+        allowPositionals: true,
+    }));
+    if (positionals.length > 0)
+        throw new CliError(`Unexpected argument: ${positionals[0]}\n\n${usage}`);
+    if (!values.help)
+        return false;
+    ctx.stdout.write(usage);
+    return true;
+}
+function runAutoArchive(ctx, args) {
+    const usage = `Usage: ${ctx.form} plans auto-archive\n`;
+    if (handleBareHelp(ctx, args, usage))
+        return 0;
+    const mode = resolvePlansMode(ctx.cwd, ctx.form);
+    const archived = autoArchive(join(ctx.cwd, ".plans"), archiveThresholdDays(ctx.env), ctx.stdout);
+    if (mode.kind === "shared" && archived)
+        ctx.stdout.write(`Publish with: ${ctx.form} sync\n`);
+    return 0;
+}
+function runArchive(ctx, args) {
+    const usage = `Usage: ${ctx.form} plans archive <ticket-id | path>\n`;
+    const target = resolveArchiveTarget(ctx, args, usage);
+    if (target === undefined)
+        return 0;
+    const mode = resolvePlansMode(ctx.cwd, ctx.form);
+    const root = join(ctx.cwd, ".plans");
+    archiveEntry(root, target, ctx.stdout);
+    if (mode.kind === "shared")
+        ctx.stdout.write(`Publish with: ${ctx.form} sync\n`);
+    return 0;
+}
+function resolveArchiveTarget(ctx, args, usage) {
+    const { values, positionals } = parseCommandArgs(usage, () => parseArgs({
+        args,
+        options: { help: { type: "boolean", short: "h", default: false } },
+        strict: true,
+        allowPositionals: true,
+    }));
+    if (values.help) {
+        ctx.stdout.write(usage);
+        return;
+    }
+    if (positionals.length !== 1)
+        throw new CliError(usage.trimEnd());
+    const argument = positionals[0];
+    const plansDir = join(ctx.cwd, ".plans");
+    const target = isPathArgument(argument) ? resolve(ctx.cwd, argument) : join(plansDir, argument);
+    const stats = statSync(target, { throwIfNoEntry: false });
+    if (!stats?.isDirectory() || realpathSync(dirname(target)) !== realpathSync(plansDir))
+        throw new CliError(`${argument} must be an existing directory directly under .plans.`);
+    if (basename(target).startsWith("_"))
+        throw new CliError(`${argument}: names starting with _ are not tickets.`);
+    return target;
+}
+function isPathArgument(argument) {
+    return argument.includes("/") || argument.includes("\\");
+}

package/dist/commands/setup.d.ts

@@ -0,0 +1,2 @@
+import type { CommandContext } from "../context.js";
+export declare function runSetup(ctx: CommandContext, args: string[]): number;

package/dist/commands/setup.js

@@ -0,0 +1,254 @@
+import { appendFileSync, existsSync, mkdirSync, readFileSync, readdirSync, realpathSync, renameSync, rmdirSync, unlinkSync, writeFileSync, } from "node:fs";
+import { basename, join } from "node:path";
+import { parseArgs } from "node:util";
+import { CliError } from "../cli-error.js";
+import { assertMainWorktreeRoot, gitOutputOrUndefined, gitSucceeds } from "../git.js";
+import { normalizeRemoteUrl } from "../overlay.js";
+import { parseCommandArgs } from "../parse-args.js";
+import { linkPlans } from "../plans/link.js";
+import { PROJECT_CONFIG_FILENAME, readProjectConfig, validateProjectConfig, } from "../project-config.js";
+import { installStubSkills } from "../skills.js";
+import { defaultCliRange } from "../version-guard.js";
+const ADOPT_FILES = ["AGENTS.md", "DEVELOPERS.md", "docs"];
+export function runSetup(ctx, args) {
+    const usage = setupUsage(ctx);
+    const options = parseSetupArgs(ctx, args, usage);
+    if (options === undefined)
+        return 0;
+    if (options.overlay)
+        return runOverlaySetup(ctx, options);
+    if (options.adopt)
+        return runAdopt(ctx);
+    return runDefaultSetup(ctx, options);
+}
+function setupUsage(ctx) {
+    return `Usage:
+  ${ctx.form} setup [--ticket-pattern <regex>] [--plans-folder <name>] [--port-range <first>-<last>] [--agent <name>]...
+  ${ctx.form} setup --overlay [--plans-folder <name>] [--ticket-pattern <regex>] [--port-range <first>-<last>]
+  ${ctx.form} setup --adopt
+`;
+}
+function parseSetupArgs(ctx, args, usage) {
+    const { values } = parseCommandArgs(usage, () => parseArgs({
+        args,
+        options: {
+            "ticket-pattern": { type: "string" },
+            "plans-folder": { type: "string" },
+            "port-range": { type: "string" },
+            agent: { type: "string", multiple: true, default: [] },
+            overlay: { type: "boolean", default: false },
+            adopt: { type: "boolean", default: false },
+            help: { type: "boolean", short: "h", default: false },
+        },
+        strict: true,
+    }));
+    if (values.help) {
+        ctx.stdout.write(usage);
+        return;
+    }
+    if (values.overlay && values.adopt)
+        throw new CliError(`--overlay and --adopt are mutually exclusive.\n\n${usage}`);
+    if ((values.overlay || values.adopt) && values.agent.length > 0)
+        throw new CliError(`--agent is available only in the default setup mode.\n\n${usage}`);
+    const portRange = values["port-range"] === undefined ? undefined : parsePortRange(values["port-range"], usage);
+    const options = {
+        ticketPattern: values["ticket-pattern"],
+        plansFolder: values["plans-folder"],
+        portRange,
+        agents: values.agent,
+        overlay: values.overlay,
+        adopt: values.adopt,
+    };
+    validateSetupOptions(options);
+    return options;
+}
+function parsePortRange(value, usage) {
+    const match = /^(\d+)-(\d+)$/.exec(value);
+    if (!match)
+        throw new CliError(`--port-range must be <first>-<last>.\n\n${usage}`);
+    return { first: Number(match[1]), last: Number(match[2]) };
+}
+function validateSetupOptions(options) {
+    validateProjectConfig({
+        schemaVersion: 1,
+        ...(options.ticketPattern === undefined ? {} : { ticketPattern: options.ticketPattern }),
+        ...(options.plansFolder === undefined ? {} : { plans: { folder: options.plansFolder } }),
+        ...(options.portRange === undefined ? {} : { portRange: options.portRange }),
+    }, PROJECT_CONFIG_FILENAME);
+}
+function runDefaultSetup(ctx, options) {
+    assertMainWorktreeRoot(ctx.cwd);
+    setupProjectConfig(ctx, options);
+    setupPlansDirectory(ctx);
+    installStubSkills(ctx, options.agents);
+    ctx.stdout.write("Installed the AlignFirst skills globally.\n");
+    setupReadme(ctx);
+    return 0;
+}
+function setupProjectConfig(ctx, options) {
+    const path = join(ctx.cwd, PROJECT_CONFIG_FILENAME);
+    if (existsSync(path)) {
+        readProjectConfig(ctx.cwd);
+        ctx.stdout.write(`${PROJECT_CONFIG_FILENAME} is valid.\n`);
+        if (hasProjectOptions(options))
+            throw new CliError(`${PROJECT_CONFIG_FILENAME} exists; edit it instead of passing options.`);
+        return;
+    }
+    const cli = defaultCliRange(ctx.version);
+    const config = validateProjectConfig({
+        schemaVersion: 1,
+        cli,
+        ...(options.ticketPattern === undefined ? {} : { ticketPattern: options.ticketPattern }),
+        ...(options.plansFolder === undefined ? {} : { plans: { folder: options.plansFolder } }),
+        ...(options.portRange === undefined ? {} : { portRange: options.portRange }),
+    }, PROJECT_CONFIG_FILENAME);
+    writeJson(path, config);
+    ctx.stdout.write(`Created ${PROJECT_CONFIG_FILENAME} (cli ${cli})\n`);
+}
+function hasProjectOptions(options) {
+    return (options.ticketPattern !== undefined ||
+        options.plansFolder !== undefined ||
+        options.portRange !== undefined);
+}
+function setupPlansDirectory(ctx) {
+    const plansPath = join(ctx.cwd, ".plans");
+    if (!existsSync(plansPath)) {
+        mkdirSync(plansPath);
+        ctx.stdout.write("Created .plans/\n");
+    }
+    if (gitSucceeds(ctx.cwd, "check-ignore", "-q", ".plans"))
+        return;
+    appendLine(join(ctx.cwd, ".gitignore"), ".plans");
+    ctx.stdout.write("Added .plans to .gitignore.\n");
+}
+function appendLine(path, line) {
+    const content = existsSync(path) ? readFileSync(path, "utf-8") : "";
+    const separator = content === "" || content.endsWith("\n") ? "" : "\n";
+    appendFileSync(path, `${separator}${line}\n`);
+}
+function setupReadme(ctx) {
+    const path = join(ctx.cwd, "README.md");
+    if (!existsSync(path))
+        return;
+    const content = readFileSync(path, "utf-8");
+    if (/alignfirst/i.test(content))
+        return;
+    appendFileSync(path, "\n## Prerequisites\n\nInstall the AlignFirst CLI: `npm install -g alignfirst`.\n");
+    ctx.stdout.write("Added the CLI prerequisite to README.md.\n");
+}
+function runOverlaySetup(ctx, options) {
+    const overlaysDir = resolveOverlaysDir(ctx);
+    assertMainWorktreeRoot(ctx.cwd);
+    const projectPath = realpathSync(ctx.cwd);
+    const name = options.plansFolder ?? basename(projectPath);
+    const overlayDir = join(overlaysDir, name, "_project");
+    if (existsSync(overlayDir))
+        throw new CliError(`${overlayDir} already exists.`);
+    const config = buildOverlayConfig(ctx, options, projectPath);
+    mkdirSync(overlayDir, { recursive: true });
+    writeJson(join(overlayDir, PROJECT_CONFIG_FILENAME), config);
+    ctx.stdout.write(`Created overlay: ${overlayDir}\n`);
+    setupOverlayPlans(ctx, overlaysDir, name);
+    setupGitExclude(ctx);
+    return 0;
+}
+function resolveOverlaysDir(ctx) {
+    const value = ctx.env.ALIGNFIRST_OVERLAYS;
+    if (value === undefined || value === "")
+        throw new CliError("ALIGNFIRST_OVERLAYS is not set.");
+    return value.startsWith("~/") ? join(ctx.home, value.slice(2)) : value;
+}
+function buildOverlayConfig(ctx, options, projectPath) {
+    const origin = gitOutputOrUndefined(ctx.cwd, "remote", "get-url", "origin");
+    return validateProjectConfig({
+        schemaVersion: 1,
+        project: {
+            ...(origin === undefined || origin === "" ? {} : { remote: normalizeRemoteUrl(origin) }),
+            paths: [projectPath],
+        },
+        ...(options.ticketPattern === undefined ? {} : { ticketPattern: options.ticketPattern }),
+        ...(options.plansFolder === undefined ? {} : { plans: { folder: options.plansFolder } }),
+        ...(options.portRange === undefined ? {} : { portRange: options.portRange }),
+    }, PROJECT_CONFIG_FILENAME);
+}
+function setupOverlayPlans(ctx, overlaysDir, name) {
+    if (gitSucceeds(overlaysDir, "rev-parse", "--git-dir")) {
+        linkPlans(ctx, join(overlaysDir, name));
+        return;
+    }
+    const plansPath = join(ctx.cwd, ".plans");
+    if (!existsSync(plansPath))
+        mkdirSync(plansPath);
+    ctx.stdout.write("Using a local .plans directory.\n");
+}
+function setupGitExclude(ctx) {
+    if (gitSucceeds(ctx.cwd, "check-ignore", "-q", ".plans"))
+        return;
+    appendLine(join(ctx.cwd, ".git", "info", "exclude"), ".plans");
+    ctx.stdout.write("Added .plans to .git/info/exclude.\n");
+}
+function runAdopt(ctx) {
+    const overlay = ctx.overlay;
+    if (overlay === undefined) {
+        const value = ctx.env.ALIGNFIRST_OVERLAYS;
+        throw new CliError(`No overlay matches this repository (ALIGNFIRST_OVERLAYS=${value === undefined || value === "" ? "unset" : value}).`);
+    }
+    adoptConfig(ctx, overlay.dir, overlay.config);
+    const agentsConflict = adoptFiles(ctx, overlay.dir);
+    removePlansExclude(ctx);
+    if (readdirSync(overlay.dir).length === 0)
+        rmdirSync(overlay.dir);
+    else
+        ctx.stdout.write(`Overlay remains: ${overlay.dir}\n`);
+    ctx.stdout.write("Next: add .plans to .gitignore.\n");
+    if (agentsConflict)
+        ctx.stdout.write("Next: merge the overlay AGENTS.md conventions by hand.\n");
+    return 0;
+}
+function adoptConfig(ctx, overlayDir, config) {
+    const name = PROJECT_CONFIG_FILENAME;
+    const source = join(overlayDir, name);
+    const target = join(ctx.cwd, name);
+    if (existsSync(target)) {
+        ctx.stdout.write(`kept in the overlay: ${name} (the root has its own)\n`);
+        return;
+    }
+    const rootConfig = structuredClone(config);
+    delete rootConfig.project;
+    writeJson(target, validateProjectConfig(rootConfig, name));
+    unlinkSync(source);
+    ctx.stdout.write(`Adopted ${name}.\n`);
+}
+function adoptFiles(ctx, overlayDir) {
+    let agentsConflict = false;
+    for (const name of ADOPT_FILES) {
+        const source = join(overlayDir, name);
+        if (!existsSync(source))
+            continue;
+        const target = join(ctx.cwd, name);
+        if (existsSync(target)) {
+            ctx.stdout.write(`kept in the overlay: ${name} (the root has its own)\n`);
+            if (name === "AGENTS.md")
+                agentsConflict = true;
+            continue;
+        }
+        renameSync(source, target);
+        ctx.stdout.write(`Adopted ${name}.\n`);
+    }
+    return agentsConflict;
+}
+function removePlansExclude(ctx) {
+    const path = join(ctx.cwd, ".git", "info", "exclude");
+    if (!existsSync(path))
+        return;
+    const content = readFileSync(path, "utf-8");
+    const lines = content.split(/\r?\n/);
+    const filtered = lines.filter((line) => line.trim() !== ".plans");
+    if (filtered.length === lines.length)
+        return;
+    writeFileSync(path, filtered.join("\n"));
+    ctx.stdout.write("Removed .plans from .git/info/exclude.\n");
+}
+function writeJson(path, value) {
+    writeFileSync(path, `${JSON.stringify(value, undefined, 2)}\n`);
+}

package/dist/commands/sync.d.ts

@@ -0,0 +1,2 @@
+import type { CommandContext } from "../context.js";
+export declare function runSync(ctx: CommandContext, args: string[]): number;

package/dist/commands/sync.js

@@ -0,0 +1,63 @@
+import { join } from "node:path";
+import { parseArgs } from "node:util";
+import { git, gitOutput, gitSucceeds } from "../git.js";
+import { parseCommandArgs } from "../parse-args.js";
+import { archiveThresholdDays, autoArchive } from "../plans/archive.js";
+import { resolvePlansMode } from "../plans/mode.js";
+export function runSync(ctx, args) {
+    const usage = `Usage: ${ctx.form} sync [--auto-archive]\n`;
+    const options = parseSyncArgs(ctx, args, usage);
+    if (options === undefined)
+        return 0;
+    const thresholdDays = options.autoArchive ? archiveThresholdDays(ctx.env) : undefined;
+    const mode = resolvePlansMode(ctx.cwd, ctx.form);
+    const plansDir = join(ctx.cwd, ".plans");
+    if (mode.kind === "local") {
+        if (thresholdDays !== undefined)
+            autoArchive(plansDir, thresholdDays, ctx.stdout);
+        ctx.stdout.write("(local plans mode, nothing to sync)\n");
+        return 0;
+    }
+    const repoDir = mode.repoToplevel;
+    if (hasHead(repoDir))
+        git(repoDir, "pull", "--rebase", "--autostash");
+    if (thresholdDays !== undefined)
+        autoArchive(plansDir, thresholdDays, ctx.stdout);
+    git(repoDir, "add", "-A");
+    if (hasStagedChanges(repoDir))
+        git(repoDir, "commit", "--quiet", "-m", "sync");
+    if (hasHead(repoDir) && hasCommitsToSend(repoDir)) {
+        git(repoDir, "push", "--quiet", "-u", "origin", "HEAD");
+        ctx.stdout.write("Plans synchronized: local changes sent.\n");
+    }
+    else {
+        ctx.stdout.write("Plans synchronized: nothing to send.\n");
+    }
+    return 0;
+}
+function parseSyncArgs(ctx, args, usage) {
+    const { values } = parseCommandArgs(usage, () => parseArgs({
+        args,
+        options: {
+            "auto-archive": { type: "boolean", default: false },
+            help: { type: "boolean", short: "h", default: false },
+        },
+        strict: true,
+    }));
+    if (values.help) {
+        ctx.stdout.write(usage);
+        return;
+    }
+    return { autoArchive: values["auto-archive"] };
+}
+function hasHead(dir) {
+    return gitSucceeds(dir, "rev-parse", "--verify", "-q", "HEAD");
+}
+function hasStagedChanges(dir) {
+    return !gitSucceeds(dir, "diff", "--cached", "--quiet");
+}
+function hasCommitsToSend(dir) {
+    if (!gitSucceeds(dir, "rev-parse", "--verify", "-q", "@{u}"))
+        return true;
+    return gitOutput(dir, "rev-list", "--count", "@{u}..HEAD") !== "0";
+}

package/dist/commands/ticket.d.ts

@@ -0,0 +1,2 @@
+import type { CommandContext } from "../context.js";
+export declare function runTicket(ctx: CommandContext, args: string[]): number;

package/dist/commands/ticket.js

@@ -0,0 +1,119 @@
+import { join, relative } from "node:path";
+import { parseArgs } from "node:util";
+import { CliError } from "../cli-error.js";
+import { parseCommandArgs } from "../parse-args.js";
+import { assertPlansGate } from "../plans/layout.js";
+import { deduceTicketFromBranch, nextFileName, peekSideTicket, reserveSideTicket, resolveTicketDir, validateTicketId, } from "../plans/ticket.js";
+const USAGE = `Usage:
+  {{FORM}} ticket [<id>] [--next <filename>] [--new-cycle] [--json] [--dry-run]
+  {{FORM}} ticket --side [--json] [--dry-run]
+`;
+export function runTicket(ctx, args) {
+    assertPlansGate(ctx.cwd, ctx.form);
+    const usage = renderUsage(ctx);
+    const parsed = parseTicketArgs(ctx, args, usage);
+    if (parsed === undefined)
+        return 0;
+    const result = resolveTicket(ctx, parsed);
+    const next = parsed.next === undefined ? undefined : nextFileName(result.dir, parsed.next, parsed.newCycle);
+    if (parsed.json)
+        ctx.stdout.write(`${JSON.stringify(jsonReport(ctx, parsed, result, next), undefined, 2)}\n`);
+    else
+        ctx.stdout.write(renderReport(ctx, parsed, result, next));
+    return 0;
+}
+function renderUsage(ctx) {
+    return USAGE.replaceAll("{{FORM}}", ctx.form);
+}
+function parseTicketArgs(ctx, args, usage) {
+    const { values, positionals } = parseCommandArgs(usage, () => parseArgs({
+        args,
+        options: {
+            next: { type: "string" },
+            "new-cycle": { type: "boolean", default: false },
+            json: { type: "boolean", default: false },
+            "dry-run": { type: "boolean", default: false },
+            side: { type: "boolean", default: false },
+            help: { type: "boolean", short: "h", default: false },
+        },
+        strict: true,
+        allowPositionals: true,
+    }));
+    if (values.help) {
+        ctx.stdout.write(usage);
+        return;
+    }
+    if (positionals.length > 1)
+        throw new CliError(`Expected at most one ticket id.\n\n${usage}`);
+    if (values.side && positionals.length > 0)
+        throw new CliError(`A ticket id cannot be combined with --side.\n\n${usage}`);
+    if (values["new-cycle"] && values.next === undefined)
+        throw new CliError(`--new-cycle requires --next.\n\n${usage}`);
+    const resolution = resolveTicketId(ctx, positionals[0], values.side, values["dry-run"]);
+    return {
+        ...resolution,
+        next: values.next,
+        newCycle: values["new-cycle"],
+        json: values.json,
+        dryRun: values["dry-run"],
+        side: values.side,
+    };
+}
+function resolveTicketId(ctx, positional, side, dryRun) {
+    const pattern = ctx.projectConfig?.config.ticketPattern;
+    if (positional !== undefined) {
+        validateTicketId(positional, pattern);
+        return { id: positional };
+    }
+    if (side)
+        return { id: dryRun ? peekSideTicket(ctx.cwd) : reserveSideTicket(ctx.cwd) };
+    if (pattern === undefined)
+        throw new CliError("No ticket id given and .alignfirst.json has no ticketPattern: pass the id.");
+    const deduced = deduceTicketFromBranch(ctx.cwd, pattern);
+    validateTicketId(deduced.id, pattern);
+    return deduced;
+}
+function resolveTicket(ctx, options) {
+    if (options.side && !options.dryRun)
+        return {
+            id: options.id,
+            dir: join(ctx.cwd, ".plans", options.id),
+            state: "created",
+            entries: [],
+        };
+    return resolveTicketDir(ctx.cwd, options.id, { dryRun: options.dryRun });
+}
+function jsonReport(ctx, options, result, next) {
+    return {
+        id: result.id,
+        dir: relative(ctx.cwd, result.dir),
+        state: result.state,
+        ...(options.branch === undefined ? {} : { branch: options.branch }),
+        entries: result.entries,
+        ...(next === undefined ? {} : { next: relative(ctx.cwd, join(result.dir, next)) }),
+    };
+}
+function renderReport(ctx, options, result, next) {
+    const reservation = options.side && options.dryRun ? " (would be reserved)" : "";
+    const deduction = options.branch === undefined ? "" : ` (deduced from branch ${options.branch})`;
+    const directoryState = renderDirectoryState(result.state, options.dryRun);
+    const directory = `${relative(ctx.cwd, result.dir)}/`;
+    const lines = [
+        `Ticket ${result.id}${reservation}${deduction}`,
+        `Directory: ${directory}${directoryState}`,
+    ];
+    if (result.entries.length === 0)
+        lines.push("Entries: (none)");
+    else
+        lines.push("Entries:", ...result.entries.map((entry) => `  ${entry}`));
+    if (next !== undefined)
+        lines.push(`Next file: ${relative(ctx.cwd, join(result.dir, next))}`);
+    return `${lines.join("\n")}\n`;
+}
+function renderDirectoryState(state, dryRun) {
+    if (state === "existing")
+        return "";
+    if (state === "created")
+        return dryRun ? " (would be created)" : " (created)";
+    return dryRun ? " (would be restored from _archives)" : " (restored from _archives)";
+}

package/dist/context.d.ts

@@ -0,0 +1,15 @@
+import type { Overlay, ResolvedProjectConfig } from "./overlay.js";
+export interface Output {
+    write(text: string): void;
+}
+export interface CommandContext {
+    cwd: string;
+    env: NodeJS.ProcessEnv;
+    home: string;
+    stdout: Output;
+    stderr: Output;
+    form: string;
+    version: string;
+    projectConfig?: ResolvedProjectConfig;
+    overlay?: Overlay;
+}

package/dist/context.js

@@ -0,0 +1 @@
+export {};

package/dist/errors.d.ts

@@ -0,0 +1,2 @@
+export declare function errorMessage(error: unknown): string;
+export declare function isNodeError(error: unknown): error is NodeJS.ErrnoException;

package/dist/errors.js

@@ -0,0 +1,6 @@
+export function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+export function isNodeError(error) {
+    return error instanceof Error && "code" in error;
+}

package/dist/executables.d.ts

@@ -0,0 +1 @@
+export declare function findExecutable(env: NodeJS.ProcessEnv, name: string): string | undefined;

package/dist/executables.js

@@ -0,0 +1,24 @@
+import { accessSync, constants, statSync } from "node:fs";
+import { delimiter, join } from "node:path";
+export function findExecutable(env, name) {
+    const path = env.PATH;
+    if (path === undefined || path === "")
+        return;
+    for (const dir of path.split(delimiter)) {
+        const candidate = join(dir, name);
+        if (isExecutableFile(candidate))
+            return candidate;
+    }
+    return;
+}
+function isExecutableFile(path) {
+    try {
+        if (!statSync(path).isFile())
+            return false;
+        accessSync(path, constants.X_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/git.d.ts

@@ -0,0 +1,5 @@
+export declare function git(dir: string, ...args: string[]): void;
+export declare function assertMainWorktreeRoot(cwd: string): void;
+export declare function gitOutput(dir: string, ...args: string[]): string;
+export declare function gitOutputOrUndefined(dir: string, ...args: string[]): string | undefined;
+export declare function gitSucceeds(dir: string, ...args: string[]): boolean;