@duyquangnvx/agent-cli 0.17.0 → 0.18.0

package/docs/example/bundle.ts

@@ -0,0 +1,57 @@
+import { resolve } from "node:path";
+import { CliError, runtimeCodes } from "@duyquangnvx/agent-cli";
+import * as z from "zod";
+import { defineCommand } from "./define.js";
+import { type Link, linkWithId } from "./store.js";
+
+function shortcutOf(link: Link): string {
+  return `[InternetShortcut]\r\nURL=${link.url}\r\n`;
+}
+
+export const bundle = defineCommand({
+  description: "Write links as shortcut files into a new folder",
+  examples: [
+    { command: "links bundle docs 1 2", note: "write links 1 and 2 to docs/1.url and docs/2.url" },
+    { command: "links bundle docs 1 --force", note: "replace an existing docs folder" },
+  ],
+  effect: "write",
+  errors: ["LINK_NOT_FOUND", "CORRUPT_DATA", "BUNDLE_EXISTS"],
+  force: "an existing folder, removing everything in it",
+  args: z.object({
+    folder: z.string().describe("the folder to create, relative to the working directory"),
+    ids: z.array(z.number().int()).min(1).describe("the links' ids, as `links list` shows them"),
+  }),
+  output: z.object({ folder: z.string(), files: z.array(z.string()) }),
+  plan: async ({ folder, ids }, ctx) => ({
+    folder,
+    links: await Promise.all(ids.map((id) => linkWithId(ctx, id))),
+    remove: ctx.force && (await ctx.files.exists(folder)) ? await ctx.files.list(folder) : [],
+  }),
+  apply: async (plan, ctx) => {
+    if (ctx.force) {
+      await ctx.files.remove(plan.folder);
+    }
+    try {
+      await ctx.files.mkdir(plan.folder, { exclusive: true });
+    } catch (error) {
+      if (error instanceof CliError && error.code === runtimeCodes.ALREADY_EXISTS) {
+        const ids = plan.links.map((link) => String(link.id));
+        throw ctx.fail("BUNDLE_EXISTS", {
+          message: `${plan.folder} already exists`,
+          hint: "to replace it and everything in it, rerun with --force",
+          next: [["bundle", plan.folder, ...ids, "--force"]],
+        });
+      }
+      throw error;
+    }
+    const files = plan.links.map((link) => `${link.id}.url`);
+    for (const link of plan.links) {
+      await ctx.files.write(`${plan.folder}/${link.id}.url`, shortcutOf(link));
+    }
+    return { folder: resolve(ctx.cwd, plan.folder), files };
+  },
+  render: ({ folder, files }) => `Bundled ${files.length} links into ${folder}`,
+  renderPlan: (plan) =>
+    `Would bundle ${plan.links.length} links into ${plan.folder}` +
+    (plan.remove.length === 0 ? "" : `, removing ${plan.remove.join(", ")}`),
+});

package/docs/example/cli.test.ts

@@ -0,0 +1,428 @@
+import { mkdir, mkdtemp, readFile, writeFile } from "node:fs/promises";
+import { createServer, type Server } from "node:http";
+import type { AddressInfo } from "node:net";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { runCli, runtimeCodes } from "@duyquangnvx/agent-cli";
+import { checkExamples } from "@duyquangnvx/agent-cli/testing";
+import { afterEach, describe, expect, test } from "vitest";
+import { cli } from "./cli.js";
+import { fakePorts } from "./fake-ports.js";
+import { denied, fakeFiles, folderWith, LINKS, pathWith } from "./folder.js";
+
+test("every example parses, names a Command and passes its schemas", async () => {
+  await checkExamples(cli);
+});
+
+describe("links list", () => {
+  test("prints one link per line, then how many were shown", async () => {
+    const cwd = await folderWith(LINKS);
+
+    const result = await runCli(cli, ["list"], { cwd });
+
+    expect(result).toEqual({
+      stdout: "1  https://zod.dev/\n2  https://vitest.dev/\n2 shown; no more pages\n",
+      stderr: "",
+      exitCode: 0,
+    });
+  });
+
+  test("--fields keeps only the named fields under --json", async () => {
+    const cwd = await folderWith(LINKS);
+
+    const result = await runCli(cli, ["list", "--fields", "id,url", "--json"], { cwd });
+
+    expect(JSON.parse(result.stdout)).toEqual({
+      items: [
+        { id: 1, url: "https://zod.dev/" },
+        { id: 2, url: "https://vitest.dev/" },
+      ],
+    });
+  });
+
+  test("--limit returns a page and the command for the next one", async () => {
+    const cwd = await folderWith(LINKS);
+
+    const result = await runCli(cli, ["list", "--limit", "1", "--json"], { cwd });
+
+    expect(JSON.parse(result.stdout)).toEqual({
+      items: [LINKS[0]],
+      next: "links list --limit 1 --json --cursor 1",
+    });
+  });
+
+  test("a corrupt links.json fails with exit 1 and a hint", async () => {
+    const cwd = await folderWith("not links");
+
+    const result = await runCli(cli, ["list", "--json"], { cwd });
+
+    expect(result.exitCode).toBe(1);
+    expect(JSON.parse(result.stderr)).toMatchObject({ errors: [{ code: "CORRUPT_DATA" }] });
+  });
+
+  test("a links.json it may not read fails with PERMISSION_DENIED, exit 2", async () => {
+    const cwd = await folderWith(LINKS);
+
+    const result = await runCli(cli, ["list", "--json"], {
+      cwd,
+      files: fakeFiles({ exists: async () => true, read: denied }),
+    });
+
+    expect(result.exitCode).toBe(2);
+    expect(JSON.parse(result.stderr)).toMatchObject({
+      errors: [{ code: runtimeCodes.PERMISSION_DENIED }],
+    });
+  });
+});
+
+describe("links add", () => {
+  test("--dry-run prints the Plan and saves nothing", async () => {
+    const cwd = await folderWith([]);
+
+    const result = await runCli(cli, ["add", "https://zod.dev", "--dry-run"], { cwd });
+
+    expect(result).toEqual({
+      stdout: "Would save link 1: https://zod.dev\n",
+      stderr: "",
+      exitCode: 0,
+    });
+    expect(await readFile(join(cwd, "links.json"), "utf8")).toBe("[]");
+  });
+
+  test("saves the link", async () => {
+    const cwd = await folderWith([]);
+
+    await runCli(cli, ["add", "https://zod.dev", "--tag", "docs"], { cwd });
+    const listed = await runCli(cli, ["list", "--json"], { cwd });
+
+    expect(JSON.parse(listed.stdout)).toEqual({
+      items: [{ id: 1, url: "https://zod.dev", tags: ["docs"] }],
+    });
+  });
+
+  test("tags the link with the Project file's tag when --tag is absent", async () => {
+    const root = await folderWith([]);
+    await writeFile(join(root, "links.config.json"), JSON.stringify({ tag: "work" }));
+    const cwd = join(root, "notes");
+    await mkdir(cwd);
+
+    const result = await runCli(cli, ["add", "https://zod.dev", "--json"], { cwd });
+
+    expect(JSON.parse(result.stdout)).toEqual({ id: 1, url: "https://zod.dev", tags: ["work"] });
+  });
+
+  test("a Project file that fails its schema is PROJECT_INVALID, exit 2", async () => {
+    const cwd = await folderWith([]);
+    await writeFile(join(cwd, "links.config.json"), JSON.stringify({ tag: 3 }));
+
+    const result = await runCli(cli, ["add", "https://zod.dev", "--json"], { cwd });
+
+    expect(result.exitCode).toBe(2);
+    expect(JSON.parse(result.stderr)).toMatchObject({
+      errors: [{ code: runtimeCodes.PROJECT_INVALID }],
+    });
+  });
+
+  test("an address that is not a URL is a usage error", async () => {
+    const cwd = await folderWith([]);
+
+    const result = await runCli(cli, ["add", "zod"], { cwd });
+
+    expect(result.exitCode).toBe(1);
+    expect(result.stdout).toBe("");
+  });
+});
+
+describe("links remove", () => {
+  test("without --confirm deletes nothing and hints the exact command", async () => {
+    const cwd = await folderWith(LINKS);
+
+    const result = await runCli(cli, ["remove", "1"], { cwd });
+
+    expect(result).toEqual({
+      stdout: "",
+      stderr:
+        "error: `links remove` is destructive and needs --confirm\n" +
+        "hint: to confirm, run the Next step\n" +
+        "run: links remove 1 --confirm https://zod.dev/\n",
+      exitCode: 1,
+    });
+  });
+
+  test("with --confirm naming the link's url deletes it", async () => {
+    const cwd = await folderWith(LINKS);
+
+    const result = await runCli(cli, ["remove", "1", "--confirm", "https://zod.dev/"], {
+      cwd,
+    });
+
+    expect(result.stdout).toBe("Deleted link 1: https://zod.dev/\n");
+    expect(JSON.parse(await readFile(join(cwd, "links.json"), "utf8"))).toEqual([LINKS[1]]);
+  });
+});
+
+describe("links check", () => {
+  const TOKEN_ENV = { LINKS_TOKEN: "t0ken" };
+  let server: Server | undefined;
+  let authorization: string | undefined;
+
+  afterEach(() => {
+    authorization = undefined;
+    server?.closeAllConnections();
+    server?.close();
+  });
+
+  async function serve(answer: boolean): Promise<string> {
+    server = createServer((request, response) => {
+      authorization = request.headers.authorization;
+      if (answer) {
+        response.writeHead(204).end();
+      }
+    });
+    await new Promise<void>((resolve) => server?.listen(0, "127.0.0.1", resolve));
+    return `http://127.0.0.1:${(server.address() as AddressInfo).port}/`;
+  }
+
+  test("prints the status the link answers with, sending LINKS_TOKEN as a bearer token", async () => {
+    const url = await serve(true);
+    const cwd = await folderWith([{ id: 1, url, tags: [] }]);
+
+    const result = await runCli(cli, ["check", "1", "--json"], { env: TOKEN_ENV, cwd });
+
+    expect(JSON.parse(result.stdout)).toEqual({ id: 1, url, status: 204 });
+    expect(authorization).toBe("Bearer t0ken");
+  });
+
+  test("without LINKS_TOKEN fails with SECRET_MISSING, exit 2, before any request", async () => {
+    const url = await serve(true);
+    const cwd = await folderWith([{ id: 1, url, tags: [] }]);
+    const home = await mkdtemp(join(tmpdir(), "links-home-"));
+
+    const result = await runCli(cli, ["check", "1", "--json"], {
+      env: { HOME: home, USERPROFILE: home },
+      cwd,
+    });
+
+    expect(result.exitCode).toBe(2);
+    expect(JSON.parse(result.stderr).errors[0].code).toBe(runtimeCodes.SECRET_MISSING);
+    expect(authorization).toBeUndefined();
+  });
+
+  test("a link that never answers fails with DEADLINE_EXCEEDED, exit 75", async () => {
+    const url = await serve(false);
+    const cwd = await folderWith([{ id: 1, url, tags: [] }]);
+
+    const result = await runCli(cli, ["check", "1", "--timeout", "100", "--json"], {
+      env: TOKEN_ENV,
+      cwd,
+    });
+
+    expect(result.exitCode).toBe(75);
+    expect(JSON.parse(result.stderr)).toMatchObject({
+      errors: [{ code: runtimeCodes.DEADLINE_EXCEEDED }],
+    });
+  });
+
+  test("an interrupted check fails with INTERRUPTED, exit 130", async () => {
+    const url = await serve(false);
+    const cwd = await folderWith([{ id: 1, url, tags: [] }]);
+
+    const result = await runCli(cli, ["check", "1", "--json"], {
+      env: TOKEN_ENV,
+      cwd,
+      signal: AbortSignal.timeout(100),
+    });
+
+    expect(result.exitCode).toBe(130);
+    expect(JSON.parse(result.stderr)).toMatchObject({
+      errors: [{ code: runtimeCodes.INTERRUPTED }],
+    });
+  });
+});
+
+describe("links doctor", () => {
+  async function doctor(env: Record<string, string>, config?: unknown) {
+    const cwd = await folderWith(LINKS);
+    if (config !== undefined) {
+      await writeFile(join(cwd, "links.config.json"), JSON.stringify(config));
+    }
+    const home = await mkdtemp(join(tmpdir(), "links-home-"));
+    const result = await runCli(cli, ["doctor", "--json"], {
+      env: { HOME: home, USERPROFILE: home, LINKS_TOKEN: "t0ken", ...env },
+      cwd,
+    });
+    const report = JSON.parse(result.stdout);
+    const row = (name: string): unknown =>
+      report.rows.find(({ check }: { check: string }) => check === name);
+    return { cwd, home, result, report, row };
+  }
+
+  test("reports the store row", async () => {
+    const { cwd, result, row } = await doctor({ PATH: await pathWith("git") });
+
+    expect(result.exitCode).toBe(0);
+    expect(row("store")).toEqual({
+      check: "store",
+      state: "ok",
+      message: `${join(cwd, "links.json")} holds 2 links`,
+    });
+  });
+
+  test("the tag row reads the Project file's tag", async () => {
+    const { row } = await doctor({ PATH: await pathWith("git") }, { tag: "work" });
+
+    expect(row("tag")).toEqual({
+      check: "tag",
+      state: "ok",
+      message: "`links add` tags a link work unless given --tag",
+    });
+  });
+
+  test("the tag row says links stay untagged without a Project file", async () => {
+    const { row } = await doctor({ PATH: await pathWith("git") });
+
+    expect(row("tag")).toEqual({
+      check: "tag",
+      state: "ok",
+      message: "`links add` leaves a link untagged unless given --tag",
+    });
+  });
+
+  test("an invalid Project file skips the tag row and fails doctor once, as PROJECT_INVALID", async () => {
+    const { result, row } = await doctor({ PATH: await pathWith("git") }, { tag: 3 });
+
+    expect(row("tag")).toMatchObject({ check: "tag", state: "skipped" });
+    expect(JSON.parse(result.stderr).errors.map(({ code }: { code: string }) => code)).toEqual([
+      runtimeCodes.PROJECT_INVALID,
+    ]);
+    expect(result.exitCode).toBe(2);
+  });
+
+  test("a missing LINKS_TOKEN fails doctor with exit 2, naming where to get it and put it", async () => {
+    const { home, result, row } = await doctor({ PATH: await pathWith("git"), LINKS_TOKEN: "" });
+    const dotenv = join(home, ".config", "links", ".env");
+
+    expect(row("secrets")).toEqual({
+      check: "secrets",
+      state: "problem",
+      message: `LINKS_TOKEN is not set (get it from https://links.example.com/settings/tokens); add it to ${dotenv} or the environment`,
+    });
+    expect(result.exitCode).toBe(2);
+  });
+
+  test("a missing git fails doctor with exit 2, its install command as the fix", async () => {
+    const { result, row } = await doctor({ PATH: await pathWith() });
+
+    expect(row("git")).toMatchObject({ check: "git", state: "problem", fix: "brew install git" });
+    expect(result.exitCode).toBe(2);
+  });
+
+  test("reports where the token came from and never its value", async () => {
+    const cwd = await folderWith(LINKS);
+    const home = await mkdtemp(join(tmpdir(), "links-home-"));
+    await mkdir(join(home, ".config", "links"), { recursive: true });
+    const dotenv = join(home, ".config", "links", ".env");
+    await writeFile(dotenv, "LINKS_TOKEN=secret-from-file\n");
+    const env = { HOME: home, USERPROFILE: home };
+    const secretsRow = (stdout: string): unknown =>
+      JSON.parse(stdout).rows.find(({ check }: { check: string }) => check === "secrets");
+
+    const fromFile = await runCli(cli, ["doctor", "--json"], { env, cwd });
+    const fromEnv = await runCli(cli, ["doctor", "--json"], {
+      env: { ...env, LINKS_TOKEN: "secret-from-env" },
+      cwd,
+    });
+
+    expect(secretsRow(fromFile.stdout)).toEqual({
+      check: "secrets",
+      state: "ok",
+      message: `LINKS_TOKEN from ${dotenv}`,
+    });
+    expect(secretsRow(fromEnv.stdout)).toEqual({
+      check: "secrets",
+      state: "ok",
+      message: "LINKS_TOKEN from the environment",
+    });
+    expect(fromFile.stdout + fromEnv.stdout).not.toContain("secret-from");
+  });
+});
+
+describe("the usage count", () => {
+  const COLLECTOR = "https://usage.example.com/links";
+
+  function countingPorts() {
+    const counted: (readonly [string, readonly string[]])[] = [];
+    const ports = fakePorts({
+      usage: {
+        count: async (url, command) => {
+          counted.push([url, command]);
+        },
+      },
+    });
+    return { ports, counted };
+  }
+
+  test("counts a run of a Command at the collector LINKS_USAGE_URL names", async () => {
+    const cwd = await folderWith([]);
+    const { ports, counted } = countingPorts();
+
+    const result = await runCli(cli, ["add", "https://zod.dev"], {
+      env: { LINKS_USAGE_URL: COLLECTOR },
+      cwd,
+      ports,
+    });
+
+    expect(result.exitCode).toBe(0);
+    expect(counted).toEqual([[COLLECTOR, ["add"]]]);
+  });
+
+  test.each([
+    ["without LINKS_USAGE_URL", {}, ["add", "https://zod.dev"]],
+    ["for a dry run", { LINKS_USAGE_URL: COLLECTOR }, ["add", "https://zod.dev", "--dry-run"]],
+  ])("counts nothing %s", async (_name, env, argv) => {
+    const cwd = await folderWith([]);
+    const { ports, counted } = countingPorts();
+
+    await runCli(cli, argv, { env, cwd, ports });
+
+    expect(counted).toEqual([]);
+  });
+
+  test("a collector that fails changes nothing the caller sees", async () => {
+    const cwd = await folderWith([]);
+    const ports = fakePorts({
+      usage: {
+        count: async () => {
+          throw new Error("the collector is down");
+        },
+      },
+    });
+
+    const result = await runCli(cli, ["add", "https://zod.dev"], {
+      env: { LINKS_USAGE_URL: COLLECTOR },
+      cwd,
+      ports,
+    });
+
+    expect(result).toEqual({ stdout: "Saved link 1: https://zod.dev\n", stderr: "", exitCode: 0 });
+  });
+});
+
+describe("links --help --json", () => {
+  test("describes a Command's Effect and the JSON Schema of its output", async () => {
+    const result = await runCli(cli, ["check", "--help", "--json"], { cwd: "." });
+
+    const help = JSON.parse(result.stdout);
+    expect(help).toMatchObject({ name: "links check", effect: "read" });
+    expect(help.output.required).toEqual(["id", "url", "status"]);
+  });
+
+  test("lists the Error table with each code's Exit class", async () => {
+    const result = await runCli(cli, ["--help", "--json"], { cwd: "." });
+
+    expect(JSON.parse(result.stdout).errors).toMatchObject({
+      LINK_NOT_FOUND: { class: "caller" },
+      ARCHIVE_FAILED: { class: "source" },
+    });
+  });
+});

package/docs/example/cli.ts

@@ -0,0 +1,191 @@
+import { type DoctorCheck, paginate } from "@duyquangnvx/agent-cli";
+import * as z from "zod";
+import { archive } from "./archive.js";
+import { bundle } from "./bundle.js";
+import { commit } from "./commit.js";
+import { defineCli, defineCommand, type Settings } from "./define.js";
+import { exportLinks } from "./export.js";
+import { importLinks } from "./import.js";
+import manifest from "./package.json" with { type: "json" };
+import type { Ports } from "./ports.js";
+import { serve } from "./serve.js";
+import { linkSchema, linksPath, linkWithId, readLinks, writeLinks } from "./store.js";
+
+const list = defineCommand({
+  description: "List saved links",
+  examples: [
+    { command: "links list", note: "show every link with its id" },
+    { command: "links list --tag docs", note: "show only the links tagged docs" },
+    { command: "links list --fields id,url --json", note: "get only each link's id and url" },
+  ],
+  effect: "read",
+  errors: ["CORRUPT_DATA"],
+  options: z.object({
+    tag: z.string().optional().describe("only show links with this tag"),
+  }),
+  rows: linkSchema,
+  run: async ({ tag, limit, cursor }, ctx) => {
+    const links = await readLinks(ctx);
+    const matching = tag === undefined ? links : links.filter((link) => link.tags.includes(tag));
+    return paginate(matching, { limit, cursor });
+  },
+  render: (page, style) =>
+    page.items.length === 0
+      ? "No links."
+      : page.items.map((link) => `${style.dim(String(link.id))}  ${link.url}`).join("\n"),
+});
+
+const add = defineCommand({
+  description: "Save a link",
+  examples: [
+    { command: "links add https://zod.dev --tag docs", note: "save a link tagged docs" },
+    { command: "links add https://zod.dev --dry-run", note: "show the link it would save" },
+  ],
+  effect: "write",
+  errors: ["CORRUPT_DATA"],
+  args: z.object({
+    url: z.url().describe("the address to save"),
+  }),
+  options: z.object({
+    tag: z
+      .string()
+      .optional()
+      .describe("tag the link with this, in place of the Project file's tag"),
+  }),
+  output: linkSchema,
+  plan: async ({ url, tag }, ctx) => {
+    const links = await readLinks(ctx);
+    const id = Math.max(0, ...links.map((link) => link.id)) + 1;
+    const tags = [tag ?? ctx.project?.settings.tag].filter((name) => name !== undefined);
+    return { add: { id, url, tags } };
+  },
+  apply: async (plan, ctx) => {
+    const links = await readLinks(ctx);
+    await ctx.runToEnd("saving the links", () => writeLinks(ctx, [...links, plan.add]));
+    return plan.add;
+  },
+  render: (link) => `Saved link ${link.id}: ${link.url}`,
+  renderPlan: (plan) => `Would save link ${plan.add.id}: ${plan.add.url}`,
+});
+
+const remove = defineCommand({
+  description: "Delete a saved link",
+  examples: [
+    { command: "links remove 3 --dry-run", note: "show the link it would delete" },
+    {
+      command: "links remove 3 --confirm https://zod.dev",
+      note: "delete link 3, confirmed by its url",
+    },
+  ],
+  effect: "destructive",
+  errors: ["LINK_NOT_FOUND", "CORRUPT_DATA"],
+  args: z.object({
+    id: z.number().int().describe("the link's id, as `links list` shows it"),
+  }),
+  output: linkSchema,
+  plan: async ({ id }, ctx) => ({ remove: await linkWithId(ctx, id) }),
+  confirm: (plan) => plan.remove.url,
+  apply: async (plan, ctx) => {
+    const links = await readLinks(ctx);
+    await ctx.runToEnd("saving the links", () =>
+      writeLinks(
+        ctx,
+        links.filter((link) => link.id !== plan.remove.id),
+      ),
+    );
+    return plan.remove;
+  },
+  render: (link) => `Deleted link ${link.id}: ${link.url}`,
+  renderPlan: (plan) => `Would delete link ${plan.remove.id}: ${plan.remove.url}`,
+});
+
+const DEFAULT_TIMEOUT_MS = 5000;
+
+const check = defineCommand({
+  description: "Check that a saved link still answers",
+  examples: [
+    { command: "links check 3", note: "print the HTTP status link 3 answers with" },
+    { command: "links check 3 --timeout 1000", note: "give up after 1 second" },
+  ],
+  effect: "read",
+  errors: ["LINK_NOT_FOUND", "CORRUPT_DATA", "UNREACHABLE"],
+  secrets: [{ name: "LINKS_TOKEN", get: "https://links.example.com/settings/tokens" }],
+  args: z.object({
+    id: z.number().int().describe("the link's id, as `links list` shows it"),
+  }),
+  options: z.object({
+    timeout: z
+      .number()
+      .int()
+      .positive()
+      .default(DEFAULT_TIMEOUT_MS)
+      .describe("milliseconds to wait for an answer"),
+  }),
+  output: z.object({ id: z.number(), url: z.string(), status: z.number() }),
+  run: async ({ id, timeout }, ctx) => {
+    const link = await linkWithId(ctx, id);
+    const signal = ctx.deadline(timeout);
+    try {
+      const token = ctx.secret("LINKS_TOKEN").value;
+      return { id, url: link.url, status: await ctx.ports.web.status(link.url, token, signal) };
+    } catch (error) {
+      // An interrupt or a missed deadline already carries the right error.
+      if (signal.aborted) {
+        throw signal.reason;
+      }
+      throw ctx.fail(
+        "UNREACHABLE",
+        {
+          message: `${link.url} did not answer`,
+          hint: "check the address, then try again",
+          next: [["check", String(id)]],
+        },
+        { cause: error },
+      );
+    }
+  },
+});
+
+const store: DoctorCheck<Ports, Settings> = {
+  name: "store",
+  run: async (ctx) => {
+    const links = await readLinks(ctx);
+    return { state: "ok", message: `${linksPath(ctx.cwd)} holds ${links.length} links` };
+  },
+};
+
+const tag: DoctorCheck<Ports, Settings> = {
+  name: "tag",
+  run: (ctx) => {
+    const tag = ctx.project?.settings.tag;
+    return {
+      state: "ok",
+      message:
+        tag === undefined
+          ? "`links add` leaves a link untagged unless given --tag"
+          : `\`links add\` tags a link ${tag} unless given --tag`,
+    };
+  },
+};
+
+export const cli = defineCli({
+  manifest,
+  // Counts only real runs, and only for an operator who named a collector.
+  sideTask: ({ command, dryRun, env, ports, signal }) => {
+    const url = env.LINKS_USAGE_URL;
+    return dryRun || url === undefined ? undefined : ports.usage.count(url, command, signal);
+  },
+  commands: {
+    list,
+    add,
+    import: importLinks,
+    remove,
+    check,
+    archive,
+    export: exportLinks,
+    bundle,
+    commit,
+    serve,
+  },
+  doctor: [store, tag],
+});