@duyquangnvx/agent-cli 0.16.0 → 0.18.0

package/docs/README.md

@@ -0,0 +1,51 @@
+# agent-cli
+
+> `@duyquangnvx/agent-cli` is the Runtime for Agent CLIs: command-line tools whose main caller is a Coding agent running them through a shell. It owns parsing, help, output, errors and exit codes, so every Agent CLI keeps the Output contract; a CLI declares Commands and the Runtime does the rest. These docs describe the version installed beside them.
+
+Read [Principles](principles.md) once, then the guide for the task at hand. Every TypeScript block in the guides is an excerpt of the [example](example/cli.ts).
+
+## Start
+
+- [Principles](principles.md): what a Coding agent needs from a CLI and how the Runtime gives it; read it before a judgement call a type leaves open, such as which Effect or Exit class.
+- [Getting started](getting-started.md): creating a CLI with the Scaffolder, its flags, and when the new repo counts as started.
+
+## Guides
+
+- [Commands](guides/commands.md): declaring a Command, its schemas, examples, output and `render`, and reaching files, programs, Secrets and progress through `ctx`.
+- [Effects and Plans](guides/effects-and-plans.md): choosing an Effect, splitting a write into `plan` and `apply`, `--dry-run`, `--force`, `--confirm`.
+- [Errors](guides/errors.md): the Error table, Exit classes, `ctx.fail`, Next steps, several failures at once.
+- [Lists](guides/lists.md): a List Command, `paginate` and `page`, `--limit`, `--cursor`, `--fields`.
+- [Long runs](guides/long-runs.md): a Command that calls a slow outside system, polls, could outlast the caller's tool timeout, starts a job to check on later, has a step that must not stop halfway, works through a queue, reports progress, keeps running as a server, or must keep finished work when it fails.
+- [Remote services](guides/remote-services.md): a port to a remote service: declaring ports, classifying failures, retrying, a request that starts a job or bills, a cost the operator approves, an SDK or LLM call, a Side task such as a usage count beside every run.
+- [Local state](guides/local-state.md): a Daemon or a store that outlives a run.
+- [`doctor`](guides/doctor.md): adding a `doctor` row, a tool the whole CLI relies on, or what the `install`, `registry` and `skill` rows check.
+- [Testing](guides/testing.md): writing a test, faking a port, the clock, files, a child process or a tool.
+- [Shipping](guides/shipping.md): choosing a Global or a Dependency install, releasing the CLI, its install lines, its own skill from a Skill Hub or packaged with it, or an Agents section.
+
+## Reference
+
+- [API reference](reference.md): which `.d.ts` file documents each export, for any field, option or method a guide does not spell out.
+- [Example](example/cli.ts): `links`, a complete Agent CLI using every feature the guides cover, with its tests beside each file.
+
+## A Command is done when
+
+- Every Error table code it throws, its helpers' and ports' included, is in its `errors`, and it throws its own through `ctx.fail`.
+- Every key it reads is in its `secrets`, whose `get` says where to obtain it.
+- Each line to run next is a Next step in `next`, never in the hint's prose; a rerun of the caller's own line comes from `ctx.rerun()`; the hint says whether running them is safe, and a step only the operator can take says so.
+- It declares `output` or `rows`.
+- It has `examples` with realistic full command lines starting with the CLI's name, which `checkExamples(cli)` passes.
+- Every field has `.describe()`.
+- `ctx.signal` reaches every outside call.
+- Every call to a slow outside system runs under a deadline.
+- Its tests, through `runCli`, cover:
+  - the success output, in text and under `--json`;
+  - each `CliError` code;
+  - for a Command with `secrets`, `SECRET_MISSING` before any work;
+  - for a write or destructive Command, that `--dry-run` and each refused guard change nothing;
+  - for a write Command, that it is idempotent: a second run after a success changes nothing;
+  - cancellation by passing `signal` to `runCli`, aborted once with the reason `"SIGTERM"` for 143;
+  - for a `serve` Command, aborting `signal` once the server answers;
+  - each `doctor` row it adds, with `HOME` pointed at an empty directory so no installed skill or secret leaks in.
+- The CLI's `pnpm test`, `pnpm typecheck` and `pnpm lint` pass.
+
+The example's tests have each of these.

package/docs/example/archive.test.ts

@@ -0,0 +1,280 @@
+import { setTimeout as wait } from "node:timers/promises";
+import { runCli } from "@duyquangnvx/agent-cli";
+import { fakeClock } from "@duyquangnvx/agent-cli/testing";
+import { describe, expect, test } from "vitest";
+import { cli } from "./cli.js";
+import { cliError } from "./define.js";
+import { fakePorts } from "./fake-ports.js";
+import { folderWith, LINKS } from "./folder.js";
+import type { Archive, Capture } from "./ports.js";
+
+/** An archive whose captures stay pending for one poll, then end as `captures` says. */
+function fakeArchive(captures: Readonly<Record<string, Capture>>): Archive {
+  const polled = new Set<string>();
+  return {
+    capture: async (url) => url,
+    status: async (job) => {
+      if (!polled.has(job)) {
+        polled.add(job);
+        return { state: "pending" };
+      }
+      return captures[job] ?? { state: "pending" };
+    },
+  };
+}
+
+// Real milliseconds a capture takes on threads the fake clock cannot see, as sharp's work does.
+const OFF_THREAD_MS = 20;
+
+const SNAPSHOTS: Record<string, Capture> = {
+  "https://zod.dev/": { state: "done", snapshot: "https://web.archive.org/web/1/https://zod.dev/" },
+  "https://vitest.dev/": {
+    state: "done",
+    snapshot: "https://web.archive.org/web/2/https://vitest.dev/",
+  },
+};
+
+describe("links archive", () => {
+  test("--dry-run prints the Plan and its cost", async () => {
+    const cwd = await folderWith(LINKS);
+
+    const result = await runCli(cli, ["archive", "--dry-run"], { cwd });
+
+    expect(result).toEqual({
+      stdout:
+        "Would archive 2 links:\n  https://zod.dev/\n  https://vitest.dev/\n" +
+        "cost: Archiving 2 links uses 2 of the Wayback Machine's daily captures.\n",
+      stderr: "",
+      exitCode: 0,
+    });
+  });
+
+  test("without --yes refuses with NOT_CONFIRMED, exit 2, naming the cost", async () => {
+    const cwd = await folderWith(LINKS);
+
+    const result = await runCli(cli, ["archive"], {
+      cwd,
+      ports: fakePorts({ archive: fakeArchive(SNAPSHOTS) }),
+    });
+
+    expect(result).toEqual({
+      stdout: "",
+      stderr:
+        "error: `links archive` needs --yes: Archiving 2 links uses 2 of the Wayback Machine's daily captures.\n" +
+        "hint: to approve the cost, run the Next step\n" +
+        "run: links archive --yes\n",
+      exitCode: 2,
+    });
+  });
+
+  test("a port's own CliError keeps its code and Exit class", async () => {
+    const cwd = await folderWith(LINKS);
+    const archive: Archive = {
+      capture: async () => {
+        throw cliError("UNREACHABLE", {
+          message: "web.archive.org did not answer",
+          hint: "run the Next step later",
+          next: [["archive", "--yes"]],
+        });
+      },
+      status: async () => ({ state: "pending" }),
+    };
+
+    const result = await runCli(cli, ["archive", "--yes", "--json"], {
+      cwd,
+      ports: fakePorts({ archive }),
+    });
+
+    expect(result.exitCode).toBe(3);
+    expect(JSON.parse(result.stderr).errors.map(({ code }: { code: string }) => code)).toEqual([
+      "UNREACHABLE",
+      "UNREACHABLE",
+    ]);
+  });
+
+  test("polls each capture until it is done and saves its snapshot", async () => {
+    const cwd = await folderWith(LINKS);
+
+    const result = await runCli(cli, ["archive", "--yes"], {
+      cwd,
+      ports: fakePorts({ archive: fakeArchive(SNAPSHOTS) }),
+      clock: fakeClock(),
+    });
+    const listed = await runCli(cli, ["list", "--fields", "id,snapshot", "--json"], {
+      cwd,
+    });
+
+    expect(result).toEqual({
+      stdout:
+        "1  https://web.archive.org/web/1/https://zod.dev/\n" +
+        "2  https://web.archive.org/web/2/https://vitest.dev/\n",
+      stderr: "",
+      exitCode: 0,
+    });
+    expect(JSON.parse(listed.stdout).items).toEqual([
+      { id: 1, snapshot: "https://web.archive.org/web/1/https://zod.dev/" },
+      { id: 2, snapshot: "https://web.archive.org/web/2/https://vitest.dev/" },
+    ]);
+  });
+
+  test("is idempotent: a second run captures nothing", async () => {
+    const cwd = await folderWith(LINKS);
+    await runCli(cli, ["archive", "--yes"], {
+      cwd,
+      ports: fakePorts({ archive: fakeArchive(SNAPSHOTS) }),
+      clock: fakeClock(),
+    });
+
+    const again = await runCli(cli, ["archive", "--yes", "--json"], {
+      cwd,
+      ports: fakePorts({}),
+    });
+
+    expect(again).toEqual({ stdout: "[]\n", stderr: "", exitCode: 0 });
+  });
+
+  test("a link the archive cannot capture fails with ARCHIVE_FAILED, exit 3, after the rest", async () => {
+    const cwd = await folderWith(LINKS);
+    const archive = fakeArchive({
+      "https://zod.dev/": { state: "failed", reason: "the site refused the crawler" },
+      "https://vitest.dev/": SNAPSHOTS["https://vitest.dev/"] as Capture,
+    });
+
+    const result = await runCli(cli, ["archive", "--yes", "--json"], {
+      cwd,
+      ports: fakePorts({ archive }),
+      clock: fakeClock(),
+    });
+
+    expect(result.exitCode).toBe(3);
+    expect(JSON.parse(result.stdout)).toEqual([
+      { id: 2, snapshot: "https://web.archive.org/web/2/https://vitest.dev/" },
+    ]);
+    expect(JSON.parse(result.stderr)).toEqual({
+      errors: [
+        {
+          code: "ARCHIVE_FAILED",
+          message:
+            "the Wayback Machine could not capture https://zod.dev/: the site refused the crawler",
+          hint: "retry later to archive the links not archived yet",
+          details: { id: 1, url: "https://zod.dev/" },
+          next: ["links archive --yes"],
+        },
+      ],
+    });
+  });
+
+  test("a capture request never answered fails with CAPTURE_UNANSWERED, exit 2, after the rest", async () => {
+    const cwd = await folderWith(LINKS);
+    const archive: Archive = {
+      ...fakeArchive(SNAPSHOTS),
+      capture: (url, signal) =>
+        url === "https://zod.dev/"
+          ? new Promise((_resolve, reject) =>
+              signal.addEventListener("abort", () => reject(signal.reason), { once: true }),
+            )
+          : Promise.resolve(url),
+    };
+
+    const result = await runCli(cli, ["archive", "--yes", "--json"], {
+      cwd,
+      ports: fakePorts({ archive }),
+      clock: fakeClock(),
+    });
+
+    expect(result.exitCode).toBe(2);
+    expect(JSON.parse(result.stdout)).toEqual([
+      { id: 2, snapshot: "https://web.archive.org/web/2/https://vitest.dev/" },
+    ]);
+    expect(JSON.parse(result.stderr)).toEqual({
+      errors: [
+        {
+          code: "CAPTURE_UNANSWERED",
+          message: "the Wayback Machine did not answer the capture of https://zod.dev/ in 60000 ms",
+          hint: "it may have used one of today's captures: ask your user before running again",
+          details: { id: 1, url: "https://zod.dev/" },
+          next: ["links archive --yes"],
+        },
+      ],
+    });
+  });
+
+  test("a capture still running off Node's thread holds the clock when the test says it is busy", async () => {
+    const cwd = await folderWith(LINKS);
+    let inFlight = 0;
+    const archive: Archive = {
+      ...fakeArchive(SNAPSHOTS),
+      capture: async (url) => {
+        inFlight++;
+        try {
+          await wait(OFF_THREAD_MS);
+          return url;
+        } finally {
+          inFlight--;
+        }
+      },
+    };
+
+    const result = await runCli(cli, ["archive", "--yes"], {
+      cwd,
+      ports: fakePorts({ archive }),
+      clock: fakeClock({ busy: () => inFlight > 0 }),
+    });
+
+    expect(result).toEqual({
+      stdout:
+        "1  https://web.archive.org/web/1/https://zod.dev/\n" +
+        "2  https://web.archive.org/web/2/https://vitest.dev/\n",
+      stderr: "",
+      exitCode: 0,
+    });
+  });
+
+  test("past its run deadline stops with exit 75, prints what it archived and hints how to resume", async () => {
+    const cwd = await folderWith(LINKS);
+    const archive = fakeArchive({ "https://zod.dev/": SNAPSHOTS["https://zod.dev/"] as Capture });
+
+    const result = await runCli(cli, ["archive", "--yes"], {
+      cwd,
+      ports: fakePorts({ archive }),
+      clock: fakeClock(),
+    });
+
+    expect(result).toEqual({
+      stdout: "1  https://web.archive.org/web/1/https://zod.dev/\n",
+      stderr:
+        "error: links archive ran past its 240000 ms deadline\n" +
+        "hint: run the Next step to continue the work\n" +
+        "run: links archive --yes\n",
+      exitCode: 75,
+    });
+  });
+
+  test("interrupted, prints what it archived and says how many links are left", async () => {
+    const cwd = await folderWith(LINKS);
+    const stop = new AbortController();
+    const archive: Archive = {
+      ...fakeArchive(SNAPSHOTS),
+      capture: async (url) => {
+        if (url === "https://vitest.dev/") stop.abort();
+        return url;
+      },
+    };
+
+    const result = await runCli(cli, ["archive", "--yes"], {
+      cwd,
+      ports: fakePorts({ archive }),
+      clock: fakeClock(),
+      signal: stop.signal,
+    });
+
+    expect(result).toEqual({
+      stdout: "1  https://web.archive.org/web/1/https://zod.dev/\n",
+      stderr:
+        "error: interrupted after archiving 1 of 2 links\n" +
+        "hint: unless it was stopped on purpose, run again to archive the rest\n" +
+        "run: links archive --yes\n",
+      exitCode: 130,
+    });
+  });
+});

package/docs/example/archive.ts

@@ -0,0 +1,160 @@
+import { CliError, type Context, runtimeCodes } from "@duyquangnvx/agent-cli";
+import * as z from "zod";
+import { cliError, defineCommand } from "./define.js";
+import type { Ports } from "./ports.js";
+import { type Link, readLinks, writeLinks } from "./store.js";
+
+const CAPTURE_POLL_MS = 5000;
+const CAPTURE_TIMEOUT_MS = 60_000;
+// Below the two to ten minutes a Coding agent gives a shell call.
+const ARCHIVE_DEADLINE_MS = 4 * 60_000;
+
+const archivedSchema = z.object({ id: z.number(), snapshot: z.string() });
+
+type Archived = z.infer<typeof archivedSchema>;
+
+function archiveFailed(link: Link, reason: string, cause?: unknown): CliError {
+  return cliError(
+    "ARCHIVE_FAILED",
+    {
+      message: `the Wayback Machine could not capture ${link.url}: ${reason}`,
+      hint: "retry later to archive the links not archived yet",
+      next: [["archive", "--yes"]],
+      details: { id: link.id, url: link.url },
+    },
+    { cause },
+  );
+}
+
+// A missed run deadline keeps its own error, whose Next step is already the resume line.
+function stoppedAfter(ctx: Context<Ports>, done: number, total: number): unknown {
+  const reason: unknown = ctx.signal.reason;
+  if (!(reason instanceof CliError && reason.code === runtimeCodes.INTERRUPTED)) {
+    return reason;
+  }
+  return new CliError({
+    code: runtimeCodes.INTERRUPTED,
+    message: `interrupted after archiving ${done} of ${total} links`,
+    hint: "unless it was stopped on purpose, run again to archive the rest",
+    next: [ctx.rerun()],
+  });
+}
+
+// A sent capture may use one of the day's captures, so neither Ctrl-C nor the run deadline cuts it off.
+async function sendCapture(link: Link, ctx: Context<Ports>): Promise<string> {
+  try {
+    return await ctx.runToEnd("sending the capture", () =>
+      ctx.ports.archive.capture(link.url, ctx.deadline(CAPTURE_TIMEOUT_MS, { ignoreStop: true })),
+    );
+  } catch (error) {
+    if (!(error instanceof CliError && error.code === runtimeCodes.DEADLINE_EXCEEDED)) throw error;
+    throw cliError(
+      "CAPTURE_UNANSWERED",
+      {
+        message: `the Wayback Machine did not answer the capture of ${link.url} in ${CAPTURE_TIMEOUT_MS} ms`,
+        hint: "it may have used one of today's captures: ask your user before running again",
+        next: [["archive", "--yes"]],
+        details: { id: link.id, url: link.url },
+      },
+      { cause: error },
+    );
+  }
+}
+
+async function snapshotOf(link: Link, ctx: Context<Ports>): Promise<string> {
+  const { archive } = ctx.ports;
+  let capture: Awaited<ReturnType<typeof archive.status>>;
+  try {
+    const job = await sendCapture(link, ctx);
+    capture = await ctx.poll(
+      async () => {
+        const status = await archive.status(job, ctx.signal);
+        return status.state === "pending" ? undefined : status;
+      },
+      { intervalMs: CAPTURE_POLL_MS },
+    );
+  } catch (error) {
+    // An interrupt or a missed deadline already carries the right error.
+    if (ctx.signal.aborted) {
+      throw ctx.signal.reason;
+    }
+    if (error instanceof CliError) {
+      throw error;
+    }
+    throw archiveFailed(link, error instanceof Error ? error.message : String(error), error);
+  }
+  if (capture.state === "failed") {
+    throw archiveFailed(link, capture.reason);
+  }
+  return capture.snapshot;
+}
+
+async function saveSnapshot(ctx: Context<Ports>, archived: Archived): Promise<void> {
+  const links = await readLinks(ctx);
+  await writeLinks(
+    ctx,
+    links.map((link) =>
+      link.id === archived.id ? { ...link, snapshot: archived.snapshot } : link,
+    ),
+  );
+}
+
+export const archive = defineCommand({
+  description: "Save a snapshot of each link not archived yet in the Wayback Machine",
+  examples: [
+    { command: "links archive --dry-run", note: "show the links it would archive and the cost" },
+    { command: "links archive --tag docs --yes", note: "archive the links tagged docs" },
+  ],
+  effect: "write",
+  errors: ["CORRUPT_DATA", "ARCHIVE_FAILED", "CAPTURE_UNANSWERED", "UNREACHABLE"],
+  options: z.object({
+    tag: z.string().optional().describe("only archive links with this tag"),
+  }),
+  output: z.array(archivedSchema),
+  deadline: {
+    ms: ARCHIVE_DEADLINE_MS,
+    // Archived links are skipped, so running the same command again continues the work.
+    resume: (_input, rerun) => rerun(),
+  },
+  plan: async ({ tag }, ctx) => {
+    const links = await readLinks(ctx);
+    return {
+      archive: links.filter(
+        (link) => link.snapshot === undefined && (tag === undefined || link.tags.includes(tag)),
+      ),
+    };
+  },
+  cost: (plan) =>
+    plan.archive.length === 0
+      ? undefined
+      : `Archiving ${plan.archive.length} links uses ${plan.archive.length} of the Wayback Machine's daily captures.`,
+  apply: async (plan, ctx) => {
+    let archived: Archived[] = [];
+    let failures: unknown[] = [];
+    for (const link of plan.archive) {
+      try {
+        const done = { id: link.id, snapshot: await snapshotOf(link, ctx) };
+        await ctx.runToEnd("saving the links", () => saveSnapshot(ctx, done));
+        archived = [...archived, done];
+        ctx.deliver(archived);
+      } catch (error) {
+        if (ctx.signal.aborted) {
+          throw stoppedAfter(ctx, archived.length, plan.archive.length);
+        }
+        failures = [...failures, error];
+      }
+    }
+    if (failures.length > 0) {
+      throw new AggregateError(failures, `${failures.length} links were not archived`);
+    }
+    return archived;
+  },
+  render: (archived) =>
+    archived.length === 0
+      ? "Nothing to archive."
+      : archived.map((link) => `${link.id}  ${link.snapshot}`).join("\n"),
+  renderPlan: (plan) =>
+    plan.archive.length === 0
+      ? "Nothing to archive."
+      : `Would archive ${plan.archive.length} links:\n${plan.archive.map((link) => `  ${link.url}`).join("\n")}`,
+});

package/docs/example/bin.test.ts

@@ -0,0 +1,118 @@
+import { type ChildProcess, execFileSync, spawn } from "node:child_process";
+import { mkdtemp, realpath, writeFile } from "node:fs/promises";
+import { createServer, type Server } from "node:http";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { type RunResult, runCli, runtimeCodes } from "@duyquangnvx/agent-cli";
+import { afterEach, describe, expect, test, vi } from "vitest";
+import { cli } from "./cli.js";
+import { folderWith, LINKS } from "./folder.js";
+
+// Under a full parallel run a spawned bin can take seconds just to start.
+const SPAWN_TIMEOUT_MS = 20_000;
+
+vi.setConfig({ testTimeout: SPAWN_TIMEOUT_MS });
+
+const BIN = fileURLToPath(new URL("./dist/bin.js", import.meta.url));
+
+interface Spawned {
+  readonly child: ChildProcess;
+  readonly result: Promise<RunResult>;
+}
+
+function spawnBin(argv: readonly string[], cwd: string, env: NodeJS.ProcessEnv): Spawned {
+  const child = spawn(process.execPath, [BIN, ...argv], { cwd, env });
+  const result = new Promise<RunResult>((resolve, reject) => {
+    let stdout = "";
+    let stderr = "";
+    child.stdout.setEncoding("utf8").on("data", (chunk: string) => {
+      stdout += chunk;
+    });
+    child.stderr.setEncoding("utf8").on("data", (chunk: string) => {
+      stderr += chunk;
+    });
+    child.on("error", reject);
+    child.on("close", (exitCode) => resolve({ stdout, stderr, exitCode: exitCode ?? -1 }));
+  });
+  return { child, result };
+}
+
+function runBin(argv: readonly string[], cwd: string, env: NodeJS.ProcessEnv): Promise<RunResult> {
+  return spawnBin(argv, cwd, env).result;
+}
+
+describe("built links bin", () => {
+  test.each([
+    [["list"]],
+    [["list", "--json"]],
+    [["--json", "list"]],
+    [["list", "--tag", "docs"]],
+    [["lsit"]],
+    [["list", "--tags", "docs"]],
+  ])("%j matches runCli", async (argv) => {
+    const cwd = await folderWith(LINKS);
+    const env = { ...process.env };
+
+    const fromBin = await runBin(argv, cwd, env);
+    const inProcess = await runCli(cli, argv, { env, cwd });
+
+    expect(fromBin).toEqual(inProcess);
+  });
+
+  test("a corrupt data file fails the same way as runCli", async () => {
+    // The bin sees its cwd resolved (macOS: /private/var), so runCli must get the same path.
+    const cwd = await realpath(await mkdtemp(join(tmpdir(), "links-bin-")));
+    await writeFile(join(cwd, "links.json"), "{ not json");
+    const env = { ...process.env };
+
+    const fromBin = await runBin(["list"], cwd, env);
+    const inProcess = await runCli(cli, ["list"], { env, cwd });
+
+    expect(fromBin).toEqual(inProcess);
+    expect(fromBin.exitCode).toBe(1);
+  });
+});
+
+test("the built bin prints its version, the commit and time it was built, and its changelog", async () => {
+  const head = execFileSync("git", ["rev-parse", "HEAD"], { encoding: "utf8" }).trim();
+  const packageRoot = await realpath(fileURLToPath(new URL(".", import.meta.url)));
+
+  const { stdout, exitCode } = await runBin(["--version"], tmpdir(), { ...process.env });
+
+  const [, sha, changelog] =
+    /^1\.0\.0 \(([0-9a-f]{7,40})(?:\+dirty)?\) built \d{4}-\d\d-\d\dT\d\d:\d\d:\d\d\.\d{3}Z\nchangelog (.+)\n$/.exec(
+      stdout,
+    ) ?? [];
+  expect(sha, stdout).toBeDefined();
+  expect(head.startsWith(sha ?? "-")).toBe(true);
+  expect(changelog).toBe(join(packageRoot, "CHANGELOG.md"));
+  expect(exitCode).toBe(0);
+});
+
+// Windows has no SIGINT a parent process can send to a child.
+describe.skipIf(process.platform === "win32")("built links bin on Ctrl-C", () => {
+  let server: Server | undefined;
+
+  afterEach(() => {
+    server?.closeAllConnections();
+    server?.close();
+  });
+
+  test("one SIGINT while a link is checked ends the run with INTERRUPTED and exit 130", async () => {
+    let bin: Spawned | undefined;
+    // A link that never answers, so the check is still running when the request arrives.
+    server = createServer(() => bin?.child.kill("SIGINT"));
+    await new Promise<void>((resolve) => server?.listen(0, "127.0.0.1", resolve));
+    const address = server.address();
+    if (address === null || typeof address === "string") throw new Error("no port");
+    const cwd = await folderWith([{ id: 1, url: `http://127.0.0.1:${address.port}/`, tags: [] }]);
+
+    bin = spawnBin(["check", "1", "--json"], cwd, { ...process.env, LINKS_TOKEN: "token" });
+    const result = await bin.result;
+
+    expect(result.exitCode).toBe(130);
+    expect(result.stdout).toBe("");
+    expect(result.stderr).toContain(`"code":"${runtimeCodes.INTERRUPTED}"`);
+  });
+});

package/docs/example/bin.ts

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+import { runProcess } from "@duyquangnvx/agent-cli";
+import { cli } from "./cli.js";
+
+await runProcess(cli);

package/docs/example/bundle.test.ts

@@ -0,0 +1,57 @@
+import { mkdir, readdir, readFile, writeFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import { runCli } from "@duyquangnvx/agent-cli";
+import { describe, expect, test } from "vitest";
+import { cli } from "./cli.js";
+import { folderWith, LINKS } from "./folder.js";
+
+describe("links bundle", () => {
+  test("writes one shortcut file per link into a new folder", async () => {
+    const cwd = await folderWith(LINKS);
+
+    const result = await runCli(cli, ["bundle", "docs", "1", "2"], { cwd });
+
+    expect(result).toEqual({
+      stdout: `Bundled 2 links into ${resolve(cwd, "docs")}\n`,
+      stderr: "",
+      exitCode: 0,
+    });
+    expect(await readdir(resolve(cwd, "docs"))).toEqual(["1.url", "2.url"]);
+    expect(await readFile(resolve(cwd, "docs", "1.url"), "utf8")).toBe(
+      "[InternetShortcut]\r\nURL=https://zod.dev/\r\n",
+    );
+  });
+
+  test("an existing folder refuses with BUNDLE_EXISTS, exit 1, hinting --force", async () => {
+    const cwd = await folderWith(LINKS);
+    await mkdir(resolve(cwd, "docs"));
+    await writeFile(resolve(cwd, "docs", "notes.txt"), "mine\n");
+
+    const result = await runCli(cli, ["bundle", "docs", "1"], { cwd });
+
+    expect(result).toEqual({
+      stdout: "",
+      stderr:
+        "error: docs already exists\n" +
+        "hint: to replace it and everything in it, rerun with --force\n" +
+        "run: links bundle docs 1 --force\n",
+      exitCode: 1,
+    });
+    expect(await readdir(resolve(cwd, "docs"))).toEqual(["notes.txt"]);
+  });
+
+  test("--force replaces the folder, and its dry run names what it removes", async () => {
+    const cwd = await folderWith(LINKS);
+    await mkdir(resolve(cwd, "docs"));
+    await writeFile(resolve(cwd, "docs", "notes.txt"), "mine\n");
+
+    const dryRun = await runCli(cli, ["bundle", "docs", "1", "--force", "--dry-run"], {
+      cwd,
+    });
+    const forced = await runCli(cli, ["bundle", "docs", "1", "--force"], { cwd });
+
+    expect(dryRun.stdout).toBe("Would bundle 1 links into docs, removing notes.txt\n");
+    expect(forced.exitCode).toBe(0);
+    expect(await readdir(resolve(cwd, "docs"))).toEqual(["1.url"]);
+  });
+});