@duyquangnvx/agent-cli 0.16.0 → 0.18.0

package/docs/example/commit.test.ts

@@ -0,0 +1,78 @@
+import { runCli, runtimeCodes, type Spawn } from "@duyquangnvx/agent-cli";
+import { describe, expect, test } from "vitest";
+import { cli } from "./cli.js";
+import { folderWith, LINKS, pathWith } from "./folder.js";
+
+/** Child processes that answer from `answers`, keyed by the command line, and record each one. */
+function fakeSpawn(
+  answers: Readonly<Record<string, { exitCode: number; stdout?: string; stderr?: string }>>,
+) {
+  const ran: string[] = [];
+  const spawn: Spawn = async (command, args) => {
+    const line = [command, ...args].join(" ");
+    ran.push(line);
+    const answer = answers[line] ?? { exitCode: 0 };
+    return { stdout: answer.stdout ?? "", stderr: answer.stderr ?? "", exitCode: answer.exitCode };
+  };
+  return { spawn, ran };
+}
+
+describe("links commit", () => {
+  test("adds links.json and commits it with git", async () => {
+    const cwd = await folderWith(LINKS);
+    const { spawn, ran } = fakeSpawn({
+      "git rev-parse --short HEAD": { exitCode: 0, stdout: "4f2a9c1\n" },
+    });
+
+    const result = await runCli(cli, ["commit", "--message", "Add zod"], {
+      env: { PATH: await pathWith("git") },
+      cwd,
+      spawn,
+    });
+
+    expect(result).toEqual({
+      stdout: "Committed links.json as 4f2a9c1\n",
+      stderr: "",
+      exitCode: 0,
+    });
+    expect(ran).toEqual([
+      "git add links.json",
+      "git commit --message Add zod",
+      "git rev-parse --short HEAD",
+    ]);
+  });
+
+  test("a failing git fails with TOOL_FAILED, exit 2, and the end of its stderr", async () => {
+    const cwd = await folderWith(LINKS);
+    const { spawn } = fakeSpawn({
+      "git commit --message Update links": { exitCode: 1, stderr: "nothing to commit\n" },
+    });
+
+    const result = await runCli(cli, ["commit", "--json"], {
+      env: { PATH: await pathWith("git") },
+      cwd,
+      spawn,
+    });
+
+    expect(result.exitCode).toBe(2);
+    expect(JSON.parse(result.stderr).errors[0]).toMatchObject({
+      code: runtimeCodes.TOOL_FAILED,
+      message: "git exited with 1; its stderr ends:\nnothing to commit",
+    });
+  });
+
+  test("without git on PATH fails with TOOL_MISSING, exit 2, before running anything", async () => {
+    const cwd = await folderWith(LINKS);
+    const { spawn, ran } = fakeSpawn({});
+
+    const result = await runCli(cli, ["commit", "--json"], {
+      env: { PATH: await pathWith() },
+      cwd,
+      spawn,
+    });
+
+    expect(result.exitCode).toBe(2);
+    expect(JSON.parse(result.stderr).errors[0].code).toBe(runtimeCodes.TOOL_MISSING);
+    expect(ran).toEqual([]);
+  });
+});

package/docs/example/commit.ts

@@ -0,0 +1,26 @@
+import * as z from "zod";
+import { defineCommand } from "./define.js";
+import { LINKS_FILE } from "./store.js";
+
+export const commit = defineCommand({
+  description: "Commit links.json to the git repository it is in",
+  examples: [
+    { command: "links commit", note: "commit links.json with the message Update links" },
+    { command: 'links commit --message "Add the zod docs"', note: "commit with your message" },
+  ],
+  effect: "write",
+  tools: [{ name: "git", install: "brew install git" }],
+  options: z.object({
+    message: z.string().default("Update links").describe("the commit message"),
+  }),
+  output: z.object({ commit: z.string() }),
+  plan: ({ message }) => ({ message }),
+  apply: async ({ message }, ctx) => {
+    await ctx.spawn("git", ["add", LINKS_FILE], { check: true });
+    await ctx.spawn("git", ["commit", "--message", message], { check: true });
+    const head = await ctx.spawn("git", ["rev-parse", "--short", "HEAD"], { check: true });
+    return { commit: head.stdout.trim() };
+  },
+  render: ({ commit }) => `Committed ${LINKS_FILE} as ${commit}`,
+  renderPlan: ({ message }) => `Would commit ${LINKS_FILE} with the message "${message}"`,
+});

package/docs/example/define.ts

@@ -0,0 +1,16 @@
+import { agentCli } from "@duyquangnvx/agent-cli";
+import * as z from "zod";
+import { errors } from "./errors.js";
+import { ports } from "./ports.js";
+
+const settingsSchema = z.object({
+  tag: z.string().optional().describe("the tag `links add` gives a link saved without --tag"),
+});
+
+export type Settings = z.infer<typeof settingsSchema>;
+
+export const { defineCli, defineCommand, cliError } = agentCli({
+  errors,
+  ports,
+  project: { file: "links.config.json", schema: settingsSchema },
+});

package/docs/example/errors.ts

@@ -0,0 +1,17 @@
+import { defineErrors } from "@duyquangnvx/agent-cli";
+import * as z from "zod";
+
+export const errors = defineErrors({
+  LINK_NOT_FOUND: { class: "caller" },
+  CORRUPT_DATA: { class: "caller" },
+  BUNDLE_EXISTS: { class: "caller" },
+  UNREACHABLE: { class: "source" },
+  ARCHIVE_FAILED: {
+    class: "source",
+    details: z.object({ id: z.number(), url: z.string() }),
+  },
+  CAPTURE_UNANSWERED: {
+    class: "operator",
+    details: z.object({ id: z.number(), url: z.string() }),
+  },
+});

package/docs/example/export.test.ts

@@ -0,0 +1,64 @@
+import { readFile, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { runCli, runtimeCodes } from "@duyquangnvx/agent-cli";
+import { describe, expect, test } from "vitest";
+import { cli } from "./cli.js";
+import { denied, fakeFiles, folderWith, LINKS } from "./folder.js";
+
+describe("links export", () => {
+  test("writes the links as a Markdown list", async () => {
+    const cwd = await folderWith(LINKS);
+
+    const result = await runCli(cli, ["export", "LINKS.md"], { cwd });
+
+    expect(result).toEqual({
+      stdout: `Exported 2 links to ${join(cwd, "LINKS.md")}\n`,
+      stderr: "",
+      exitCode: 0,
+    });
+    expect(await readFile(join(cwd, "LINKS.md"), "utf8")).toBe(
+      "- <https://zod.dev/> (docs)\n- <https://vitest.dev/>\n",
+    );
+  });
+
+  test("--dry-run lists the file it would write", async () => {
+    const cwd = await folderWith(LINKS);
+
+    const result = await runCli(cli, ["export", "LINKS.md", "--dry-run"], { cwd });
+
+    expect(result.stdout).toBe("Would export 2 links to LINKS.md\noutputs:\n  LINKS.md\n");
+  });
+
+  test("an existing file refuses with OUTPUT_EXISTS, exit 1, until --force", async () => {
+    const cwd = await folderWith(LINKS);
+    await writeFile(join(cwd, "LINKS.md"), "mine\n");
+
+    const refused = await runCli(cli, ["export", "LINKS.md"], { cwd });
+    const forced = await runCli(cli, ["export", "LINKS.md", "--force"], { cwd });
+
+    expect(refused).toEqual({
+      stdout: "",
+      stderr:
+        "error: `links export` would overwrite LINKS.md\n" +
+        "hint: to replace it, run the Next step\n" +
+        "run: links export LINKS.md --force\n",
+      exitCode: 1,
+    });
+    expect(forced.exitCode).toBe(0);
+    expect(await readFile(join(cwd, "LINKS.md"), "utf8")).toContain("https://zod.dev/");
+  });
+
+  test("a file it may not write fails with PERMISSION_DENIED, exit 2", async () => {
+    const cwd = await folderWith(LINKS);
+
+    const result = await runCli(cli, ["export", "LINKS.md", "--json"], {
+      cwd,
+      files: fakeFiles({ write: denied }),
+    });
+
+    expect(result.exitCode).toBe(2);
+    expect(JSON.parse(result.stderr)).toMatchObject({
+      errors: [{ code: runtimeCodes.PERMISSION_DENIED }],
+    });
+  });
+});

package/docs/example/export.ts

@@ -0,0 +1,32 @@
+import { resolve } from "node:path";
+import * as z from "zod";
+import { defineCommand } from "./define.js";
+import { type Link, readLinks } from "./store.js";
+
+function markdownOf(links: readonly Link[]): string {
+  return links
+    .map((link) => `- <${link.url}>${link.tags.length === 0 ? "" : ` (${link.tags.join(", ")})`}\n`)
+    .join("");
+}
+
+export const exportLinks = defineCommand({
+  description: "Write the links to a Markdown file",
+  examples: [
+    { command: "links export LINKS.md", note: "write every link to LINKS.md" },
+    { command: "links export LINKS.md --force", note: "replace an existing LINKS.md" },
+  ],
+  effect: "write",
+  errors: ["CORRUPT_DATA"],
+  args: z.object({
+    file: z.string().describe("the Markdown file to write, relative to the working directory"),
+  }),
+  output: z.object({ file: z.string(), count: z.number() }),
+  plan: async ({ file }, ctx) => ({ file, links: await readLinks(ctx) }),
+  outputs: (plan) => [plan.file],
+  apply: async (plan, ctx) => {
+    await ctx.files.write(plan.file, markdownOf(plan.links));
+    return { file: resolve(ctx.cwd, plan.file), count: plan.links.length };
+  },
+  render: ({ file, count }) => `Exported ${count} links to ${file}`,
+  renderPlan: (plan) => `Would export ${plan.links.length} links to ${plan.file}`,
+});

package/docs/example/fake-ports.ts

@@ -0,0 +1,14 @@
+import type { Archive, Ports, Usage, Web } from "./ports.js";
+
+async function unused(): Promise<never> {
+  throw new Error("this test does not expect a call to this port");
+}
+
+const unusedArchive: Archive = { capture: unused, status: unused };
+const unusedWeb: Web = { status: unused };
+const unusedUsage: Usage = { count: unused };
+
+/** Ports that fail when called, with `overrides` in place of the ones a test uses. */
+export function fakePorts(overrides: Partial<Ports>): Ports {
+  return { archive: unusedArchive, web: unusedWeb, usage: unusedUsage, ...overrides };
+}

package/docs/example/folder.ts

@@ -0,0 +1,48 @@
+import { chmod, mkdtemp, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import type { Files } from "@duyquangnvx/agent-cli";
+
+export const LINKS = [
+  { id: 1, url: "https://zod.dev/", tags: ["docs"] },
+  { id: 2, url: "https://vitest.dev/", tags: [] },
+];
+
+/** A new temporary folder whose links.json holds `links`. */
+export async function folderWith(links: unknown): Promise<string> {
+  const cwd = await mkdtemp(join(tmpdir(), "links-"));
+  await writeFile(join(cwd, "links.json"), JSON.stringify(links));
+  return cwd;
+}
+
+/** A folder to use as PATH, holding an empty executable for each name. */
+export async function pathWith(...names: readonly string[]): Promise<string> {
+  const folder = await mkdtemp(join(tmpdir(), "links-path-"));
+  for (const name of names) {
+    if (process.platform === "win32") {
+      await writeFile(join(folder, `${name}.cmd`), "@echo off\r\n");
+      continue;
+    }
+    await writeFile(join(folder, name), "#!/bin/sh\n");
+    await chmod(join(folder, name), 0o755);
+  }
+  return folder;
+}
+
+/** Files that hold nothing and accept every write, with `overrides` in place of some methods. */
+export function fakeFiles(overrides: Partial<Files>): Files {
+  return {
+    exists: async () => false,
+    write: async () => {},
+    read: async () => new Uint8Array(),
+    list: async () => [],
+    remove: async () => {},
+    mkdir: async () => {},
+    stat: async () => undefined,
+    ...overrides,
+  };
+}
+
+export async function denied(): Promise<never> {
+  throw Object.assign(new Error("EACCES: permission denied"), { code: "EACCES" });
+}

package/docs/example/import.test.ts

@@ -0,0 +1,53 @@
+import { readFile } from "node:fs/promises";
+import { join } 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 import", () => {
+  test("- reads the text from stdin and saves each link in it not saved yet", async () => {
+    const cwd = await folderWith(LINKS);
+    const notes = "Read https://zod.dev/ and https://biomejs.dev/.\nThen (https://pnpm.io).\n";
+
+    const result = await runCli(cli, ["import", "-"], { cwd, stdin: notes });
+
+    expect(result).toEqual({
+      stdout: "Saved link 3: https://biomejs.dev/\nSaved link 4: https://pnpm.io\n",
+      stderr: "",
+      exitCode: 0,
+    });
+    expect(JSON.parse(await readFile(join(cwd, "links.json"), "utf8"))).toHaveLength(4);
+  });
+
+  test("a repeated --tag gives each link every tag, in order", async () => {
+    const cwd = await folderWith([]);
+
+    const result = await runCli(
+      cli,
+      ["import", "see https://zod.dev", "--tag", "docs", "--tag=zod", "--json"],
+      { cwd },
+    );
+
+    expect(JSON.parse(result.stdout)).toEqual([
+      { id: 1, url: "https://zod.dev", tags: ["docs", "zod"] },
+    ]);
+  });
+
+  test("an empty stdin is a usage error and saves nothing", async () => {
+    const cwd = await folderWith([]);
+
+    const result = await runCli(cli, ["import", "-"], { cwd, stdin: "" });
+
+    expect(result.exitCode).toBe(1);
+    expect(result.stdout).toBe("");
+    expect(await readFile(join(cwd, "links.json"), "utf8")).toBe("[]");
+  });
+
+  test("--help shows the stdin form, and the help paragraph after the options", async () => {
+    const result = await runCli(cli, ["import", "--help"], { cwd: "." });
+
+    expect(result.stdout).toContain("  <text|->  the text holding the links");
+    expect(result.stdout).toMatch(/Options:[\s\S]*\n\nGive - to read the text from stdin, /);
+  });
+});

package/docs/example/import.ts

@@ -0,0 +1,50 @@
+import { orStdin } from "@duyquangnvx/agent-cli";
+import * as z from "zod";
+import { defineCommand } from "./define.js";
+import { linkSchema, readLinks, writeLinks } from "./store.js";
+
+// Ends on a character that cannot close a sentence, so "see https://zod.dev." keeps no dot.
+const URL_PATTERN = /https?:\/\/[^\s<>()[\]"'`]*[^\s<>()[\]"'`.,;:!?]/g;
+
+export const importLinks = defineCommand({
+  description: "Save every link found in a text, such as a Markdown file",
+  help:
+    "Give - to read the text from stdin, so a file of any length or quoting goes in whole: " +
+    "`links import - < notes.md`. Links already saved are skipped.",
+  examples: [
+    { command: "links import - < notes.md", note: "save every link in notes.md" },
+    {
+      command: "links import 'see https://zod.dev' --tag docs --tag zod",
+      note: "save one link with two tags",
+    },
+  ],
+  effect: "write",
+  errors: ["CORRUPT_DATA"],
+  args: z.object({
+    text: orStdin(z.string().min(1)).describe("the text holding the links; - reads it from stdin"),
+  }),
+  options: z.object({
+    tag: z
+      .array(z.string())
+      .default([])
+      .describe("tag each saved link with this; repeat for more tags"),
+  }),
+  output: z.array(linkSchema),
+  plan: async ({ text, tag }, ctx) => {
+    const links = await readLinks(ctx);
+    const saved = new Set(links.map((link) => link.url));
+    const urls = [...new Set(text.match(URL_PATTERN))].filter((url) => !saved.has(url));
+    const firstId = Math.max(0, ...links.map((link) => link.id)) + 1;
+    return { add: urls.map((url, index) => ({ id: firstId + index, url, tags: tag })) };
+  },
+  apply: async (plan, ctx) => {
+    const links = await readLinks(ctx);
+    await ctx.runToEnd("saving the links", () => writeLinks(ctx, [...links, ...plan.add]));
+    return plan.add;
+  },
+  render: (added) =>
+    added.length === 0
+      ? "No new links."
+      : added.map((link) => `Saved link ${link.id}: ${link.url}`).join("\n"),
+  renderPlan: (plan) => `Would save ${plan.add.length} links`,
+});

package/docs/example/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "links",
+  "version": "1.0.0",
+  "description": "Keep a list of links and check that they still resolve.",
+  "private": true,
+  "type": "module",
+  "engines": {
+    "node": ">=22.12.0"
+  },
+  "bin": {
+    "links": "./dist/bin.js"
+  },
+  "scripts": {
+    "build": "tsdown"
+  },
+  "devDependencies": {
+    "@duyquangnvx/agent-cli": "workspace:*",
+    "tsdown": "0.23.0",
+    "zod": "4.6.7"
+  }
+}

package/docs/example/ports.ts

@@ -0,0 +1,105 @@
+import * as z from "zod";
+
+export type Capture =
+  | { readonly state: "pending" }
+  | { readonly state: "done"; readonly snapshot: string }
+  | { readonly state: "failed"; readonly reason: string };
+
+/** The Wayback Machine's capture service; a test replaces it through `runCli`'s `ports`. */
+export interface Archive {
+  /** Starts capturing `url` and returns the capture's job id. */
+  capture(url: string, signal: AbortSignal): Promise<string>;
+  status(job: string, signal: AbortSignal): Promise<Capture>;
+}
+
+/** The web the saved links live on. */
+export interface Web {
+  /** The HTTP status `url` answers a HEAD request with, sent with `token` as a bearer token. */
+  status(url: string, token: string, signal: AbortSignal): Promise<number>;
+}
+
+/** The operator's own collector of usage counts, which `LINKS_USAGE_URL` names. */
+export interface Usage {
+  /** Counts one run of the Command at `command`. */
+  count(url: string, command: readonly string[], signal: AbortSignal): Promise<void>;
+}
+
+export interface Ports {
+  readonly archive: Archive;
+  readonly web: Web;
+  readonly usage: Usage;
+}
+
+const WAYBACK = "https://web.archive.org";
+
+const jobSchema = z.object({ job_id: z.string() });
+
+const statusSchema = z.discriminatedUnion("status", [
+  z.object({ status: z.literal("pending") }),
+  z.object({ status: z.literal("success"), timestamp: z.string(), original_url: z.string() }),
+  z.object({ status: z.literal("error"), message: z.string() }),
+]);
+
+async function json(response: Response): Promise<unknown> {
+  if (!response.ok) {
+    throw new Error(`${response.url} answered ${response.status}`);
+  }
+  return response.json();
+}
+
+function waybackArchive(): Archive {
+  return {
+    capture: async (url, signal) => {
+      const response = await fetch(`${WAYBACK}/save`, {
+        method: "POST",
+        headers: { accept: "application/json" },
+        body: new URLSearchParams({ url }),
+        signal,
+      });
+      return jobSchema.parse(await json(response)).job_id;
+    },
+    status: async (job, signal) => {
+      const response = await fetch(`${WAYBACK}/save/status/${job}`, {
+        headers: { accept: "application/json" },
+        signal,
+      });
+      const status = statusSchema.parse(await json(response));
+      switch (status.status) {
+        case "pending":
+          return { state: "pending" };
+        case "success":
+          return {
+            state: "done",
+            snapshot: `${WAYBACK}/web/${status.timestamp}/${status.original_url}`,
+          };
+        case "error":
+          return { state: "failed", reason: status.message };
+      }
+    },
+  };
+}
+
+const web: Web = {
+  status: async (url, token, signal) => {
+    const headers = { authorization: `Bearer ${token}` };
+    return (await fetch(url, { method: "HEAD", headers, signal })).status;
+  },
+};
+
+const usage: Usage = {
+  count: async (url, command, signal) => {
+    const response = await fetch(url, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ command: command.join(" ") }),
+      signal,
+    });
+    if (!response.ok) {
+      throw new Error(`${url} answered ${response.status}`);
+    }
+  },
+};
+
+export function ports(): Ports {
+  return { archive: waybackArchive(), web, usage };
+}

package/docs/example/serve.test.ts

@@ -0,0 +1,49 @@
+import { createServer } from "node:net";
+import { runCli } from "@duyquangnvx/agent-cli";
+import { describe, expect, test } from "vitest";
+import { cli } from "./cli.js";
+import { folderWith, LINKS } from "./folder.js";
+
+const RETRY_MS = 10;
+
+async function freePort(): Promise<number> {
+  const server = createServer();
+  await new Promise<void>((resolve) => server.listen(0, "127.0.0.1", resolve));
+  const address = server.address();
+  await new Promise((resolve) => server.close(resolve));
+  if (address === null || typeof address === "string") throw new Error("no port");
+  return address.port;
+}
+
+/** The page at `url`, asked again until the server is up. */
+async function pageAt(url: string): Promise<string> {
+  for (;;) {
+    try {
+      return await (await fetch(url)).text();
+    } catch {
+      await new Promise((resolve) => setTimeout(resolve, RETRY_MS));
+    }
+  }
+}
+
+describe("links serve", () => {
+  test("serves the links until stopped, then exits 0", async () => {
+    const cwd = await folderWith(LINKS);
+    const port = await freePort();
+    const stop = new AbortController();
+
+    const run = runCli(cli, ["serve", "--port", String(port)], {
+      cwd,
+      signal: stop.signal,
+    });
+    const page = await pageAt(`http://127.0.0.1:${port}/`);
+    stop.abort();
+
+    expect(page).toContain('<a href="https://zod.dev/">https://zod.dev/</a>');
+    expect(await run).toEqual({
+      stdout: `Serving the links at http://127.0.0.1:${port}/ until Ctrl-C\n`,
+      stderr: "",
+      exitCode: 0,
+    });
+  });
+});

package/docs/example/serve.ts

@@ -0,0 +1,40 @@
+import { createServer } from "node:http";
+import * as z from "zod";
+import { defineCommand } from "./define.js";
+import { type Link, readLinks } from "./store.js";
+
+const DEFAULT_PORT = 4173;
+const HOST = "127.0.0.1";
+
+function pageOf(links: readonly Link[]): string {
+  const items = links.map((link) => `<li><a href="${link.url}">${link.url}</a></li>`).join("");
+  return `<!doctype html><title>Links</title><ul>${items}</ul>\n`;
+}
+
+export const serve = defineCommand({
+  description: "Serve the links as a web page until stopped",
+  examples: [
+    { command: "links serve", note: `serve the links at http://${HOST}:${DEFAULT_PORT}/` },
+    { command: "links serve --port 8080", note: "serve them on port 8080" },
+  ],
+  effect: "serve",
+  options: z.object({
+    port: z.number().int().positive().default(DEFAULT_PORT).describe("the port to listen on"),
+  }),
+  output: z.object({ url: z.string() }),
+  start: async ({ port }, ctx) => {
+    const server = createServer(async (_request, response) => {
+      try {
+        const links = await readLinks(ctx);
+        response.writeHead(200, { "content-type": "text/html" }).end(pageOf(links));
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        response.writeHead(500, { "content-type": "text/plain" }).end(`${message}\n`);
+      }
+    });
+    await new Promise<void>((resolve) => server.listen(port, HOST, resolve));
+    ctx.signal.addEventListener("abort", () => server.close(), { once: true });
+    return { url: `http://${HOST}:${port}/` };
+  },
+  render: ({ url }) => `Serving the links at ${url} until Ctrl-C`,
+});