argsbarg 3.3.2 → 3.3.3

package/CHANGELOG.md

@@ -7,8 +7,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
-## [3.3.2] - 2026-06-21
+## [3.3.3] - 2026-06-21
+
+### Added
 
+- **`docs --save`** — write bundled docs to `./docs/`; `docs all --save` writes one file per topic instead of combined stdout output. Argsbarg-generated markdown (`mcp`, `api`, `skill`) is prefixed with a `Generated by … docs … --save` HTML comment.
 
 ## [3.3.2] - 2026-06-21
 
@@ -252,8 +255,8 @@ const cli = { ... } satisfies CliProgram;  // or : CliProgram
 - Migrate schemas: rename every `children` property to **`commands`**; move positional definitions to **`CliPositional`** objects on `positionals` and strip `positional` / `argMin` / `argMax` from flag definitions under `options` (flags only carry `name`, `description`, `kind`, and optional `shortName`).
 - Imports: use `CliPositional` where needed; replace `CliOptionDef` with `CliOption` or `CliPositional` as appropriate.
 
-[Unreleased]: https://github.com/bdombro/bun-argsbarg/compare/v3.3.2...HEAD
-[3.3.2]: https://github.com/bdombro/bun-argsbarg/releases/tag/v3.3.2
+[Unreleased]: https://github.com/bdombro/bun-argsbarg/compare/v3.3.3...HEAD
+[3.3.3]: https://github.com/bdombro/bun-argsbarg/releases/tag/v3.3.3
 [3.3.2]: https://github.com/bdombro/bun-argsbarg/releases/tag/v3.3.2
 [3.3.1]: https://github.com/bdombro/bun-argsbarg/releases/tag/v3.3.1
 [3.3.0]: https://github.com/bdombro/bun-argsbarg/releases/tag/v3.3.0

package/docs/bundled-docs.md

@@ -32,6 +32,8 @@ myapp docs api          # command tree as markdown
 myapp docs skill        # generated Cursor SKILL.md
 myapp docs all          # all user topics; includes auto mcp when MCP enabled
 myapp docs mcp          # auto-generated when mcpServer.enabled
+myapp docs readme --save   # write ./docs/readme.md
+myapp docs all --save      # write ./docs/<topic>.md for each bundled topic
 ```
 
 ## Configuration
@@ -89,3 +91,19 @@ All `docs` subcommands are hidden from MCP `tools/list` (`mcpTool: { enabled: fa
 | `mcp` | Callable tools + schema resource |
 
 Do not declare a top-level command named **`docs`** when `docs.enabled` is `true` — it is reserved.
+
+## Save to disk (`--save`)
+
+Pass **`--save`** on `docs` or any docs subcommand to write files under **`./docs/`** (relative to the current working directory). Each saved path is printed on stdout.
+
+| Command | Output |
+| --- | --- |
+| `docs readme --save` | `./docs/readme.md` |
+| `docs schema --save` | `./docs/schema.json` |
+| `docs api --save` | `./docs/api.md` |
+| `docs skill --save` | `./docs/skill.md` |
+| `docs all --save` | one file per bundled topic (`readme.md`, `mcp.md`, …) — not a combined file |
+
+`docs all --save` uses the same topic set as stdout `docs all` (user topics plus auto `mcp` when enabled). It does not include `schema`, `api`, or `skill` unless you invoke those subcommands separately.
+
+Argsbarg-generated markdown (`mcp`, `api`, `skill`) is prefixed with an HTML comment: `<!-- Generated by myapp docs api --save; do not edit. -->`. Consumer topic files and `schema.json` are written as-is.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "argsbarg",
-  "version": "3.3.2",
+  "version": "3.3.3",
   "type": "module",
   "engines": {
     "bun": ">=1.3"

package/src/docs/builtin.ts

@@ -1,4 +1,4 @@
-import { CliFallbackMode, type CliLeaf, type CliProgram, type CliRouter } from "../types.ts";
+import { CliFallbackMode, CliOptionKind, type CliLeaf, type CliOption, type CliProgram, type CliRouter } from "../types.ts";
 import {
   DOCS_ROUTER_DESCRIPTION,
   docsEffectiveDefaultTopic,
@@ -8,14 +8,32 @@ import {
   docsUserTopicKeys,
   printDocsTopic,
 } from "./resolve.ts";
+import { saveDocsTopics } from "./save.ts";
+
+const DOCS_SAVE_OPTION: CliOption = {
+  name: "save",
+  description: "Write documentation to ./docs/ (`docs all` writes one file per topic).",
+  kind: CliOptionKind.Presence,
+};
+
+function runDocsTopic(program: CliProgram, topic: string, ctx: { hasFlag(name: string): boolean }): void {
+  if (ctx.hasFlag("save")) {
+    for (const path of saveDocsTopics(program, topic)) {
+      process.stdout.write(`${path}\n`);
+    }
+    return;
+  }
+  printDocsTopic(program, topic);
+}
 
 function docsLeaf(program: CliProgram, key: string, description: string): CliLeaf {
   return {
     key,
     description,
+    options: [DOCS_SAVE_OPTION],
     mcpTool: { enabled: false },
-    handler: () => {
-      printDocsTopic(program, key);
+    handler: (ctx) => {
+      runDocsTopic(program, key, ctx);
     },
   };
 }
@@ -46,6 +64,7 @@ export function cliBuiltinDocsGroup(program: CliProgram): CliRouter {
   return {
     key: "docs",
     description: docs.description ?? DOCS_ROUTER_DESCRIPTION,
+    options: [DOCS_SAVE_OPTION],
     fallbackCommand: docsEffectiveDefaultTopic(docs),
     fallbackMode: CliFallbackMode.MissingOnly,
     commands: leaves,

package/src/docs/docs.test.ts

@@ -1,4 +1,7 @@
-import { expect, test } from "bun:test";
+import { describe, expect, test, beforeEach, afterEach } from "bun:test";
+import { existsSync, mkdtempSync, readFileSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
 import { cliPresentationRoot } from "../builtins/presentation.ts";
 import { completionBashScript } from "../completion.ts";
 import { cliInvoke } from "../index.ts";
@@ -6,6 +9,21 @@ import type { CliProgram } from "../types.ts";
 import { cliValidateProgram } from "../validate.ts";
 import { combineAllDocs, docsEffectiveDefaultTopic } from "./resolve.ts";
 import { generateMcpGuide } from "./mcp-guide.ts";
+import { docsTopicsToSave, saveDocsTopics } from "./save.ts";
+
+let workDir: string;
+let prevCwd: string;
+
+beforeEach(() => {
+  workDir = mkdtempSync(join(tmpdir(), "argsbarg-docs-save-"));
+  prevCwd = process.cwd();
+  process.chdir(workDir);
+});
+
+afterEach(() => {
+  process.chdir(prevCwd);
+  rmSync(workDir, { recursive: true, force: true });
+});
 
 function docsFixture(mcp = true): CliProgram {
   return {
@@ -165,3 +183,52 @@ test("generateMcpGuide includes schema URI", () => {
   const guide = generateMcpGuide(docsFixture(true));
   expect(guide).toContain("myapp://schema");
 });
+
+test("docs --save writes topic file", async () => {
+  const result = await cliInvoke(docsFixture(), ["docs", "readme", "--save"]);
+  expect(result.exitCode).toBe(0);
+  expect(result.stdout.trim()).toBe("docs/readme.md");
+  const text = readFileSync(join(workDir, "docs/readme.md"), "utf8");
+  expect(text).toContain("Hello README");
+  expect(text).not.toContain("Generated by");
+});
+
+test("docs api --save prepends generated hint", async () => {
+  const result = await cliInvoke(docsFixture(), ["docs", "api", "--save"]);
+  expect(result.exitCode).toBe(0);
+  const text = readFileSync(join(workDir, "docs/api.md"), "utf8");
+  expect(text.startsWith("<!-- Generated by myapp docs api --save; do not edit. -->\n\n")).toBe(
+    true,
+  );
+  expect(text).toContain("CLI API reference");
+});
+
+test("docs schema --save writes JSON file", async () => {
+  const result = await cliInvoke(docsFixture(), ["docs", "schema", "--save"]);
+  expect(result.exitCode).toBe(0);
+  expect(result.stdout.trim()).toBe("docs/schema.json");
+  const text = readFileSync(join(workDir, "docs/schema.json"), "utf8");
+  expect(text).not.toContain("Generated by");
+  const schema = JSON.parse(text);
+  expect(schema.key).toBe("myapp");
+});
+
+test("docs all --save writes separate topic files", async () => {
+  const program = docsFixture(true);
+  const result = await cliInvoke(program, ["docs", "all", "--save"]);
+  expect(result.exitCode).toBe(0);
+  const lines = result.stdout.trim().split("\n");
+  expect(lines).toEqual(docsTopicsToSave(program, "all").map((key) => `docs/${key}.md`));
+  expect(readFileSync(join(workDir, "docs/readme.md"), "utf8")).not.toContain("Generated by");
+  expect(readFileSync(join(workDir, "docs/mcp.md"), "utf8")).toContain(
+    "<!-- Generated by myapp docs mcp --save; do not edit. -->",
+  );
+});
+
+test("saveDocsTopics returns relative paths", () => {
+  const paths = saveDocsTopics(docsFixture(), "api");
+  expect(paths).toEqual(["docs/api.md"]);
+  const text = readFileSync(join(workDir, "docs/api.md"), "utf8");
+  expect(text).toContain("<!-- Generated by myapp docs api --save; do not edit. -->");
+  expect(text).toContain("CLI API reference");
+});

package/src/docs/resolve.ts

@@ -77,6 +77,24 @@ export function docsTopicText(program: CliProgram, topic: string): string {
   return entry.text;
 }
 
+/** Full file body for a docs topic (stdout or `--save`). */
+export function docsTopicContent(program: CliProgram, topic: string): string {
+  if (topic === "schema") {
+    return cliSchemaJson(program);
+  }
+  if (topic === "api") {
+    return generateApiGuide(program);
+  }
+  if (topic === "skill") {
+    return `${generateSkillBundle(program, "cursor").skillMd}\n`;
+  }
+  if (topic === "all") {
+    return `${combineAllDocs(program)}\n`;
+  }
+  const text = docsTopicText(program, topic);
+  return text.endsWith("\n") ? text : `${text}\n`;
+}
+
 /** All bundled docs concatenated with horizontal rules. */
 export function combineAllDocs(program: CliProgram): string {
   return docsPrintOrder(program)
@@ -84,36 +102,7 @@ export function combineAllDocs(program: CliProgram): string {
     .join("\n\n---\n\n");
 }
 
-/** Writes CLI schema JSON to stdout (`docs schema`). */
-export function printDocsSchema(program: CliProgram): void {
-  process.stdout.write(cliSchemaJson(program));
-}
-
-/** Writes markdown API reference to stdout (`docs api`). */
-export function printDocsApi(program: CliProgram): void {
-  process.stdout.write(generateApiGuide(program));
-}
-
-/** Writes generated Cursor SKILL.md to stdout (`docs skill`). */
-export function printDocsSkill(program: CliProgram): void {
-  const bundle = generateSkillBundle(program, "cursor");
-  process.stdout.write(`${bundle.skillMd}\n`);
-}
-
 /** Writes one docs topic (or `all`) to stdout. */
 export function printDocsTopic(program: CliProgram, topic: string): void {
-  if (topic === "schema") {
-    printDocsSchema(program);
-    return;
-  }
-  if (topic === "api") {
-    printDocsApi(program);
-    return;
-  }
-  if (topic === "skill") {
-    printDocsSkill(program);
-    return;
-  }
-  const content = topic === "all" ? combineAllDocs(program) : docsTopicText(program, topic);
-  process.stdout.write(`${content}\n`);
+  process.stdout.write(docsTopicContent(program, topic));
 }

package/src/docs/save.ts

@@ -0,0 +1,60 @@
+import { mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import type { CliProgram } from "../types.ts";
+import { docsPrintOrder, docsTopicContent } from "./resolve.ts";
+
+/** Relative output directory for `docs --save`. */
+export const DOCS_SAVE_DIR = "docs";
+
+/** Builtin docs topics generated by argsbarg (not consumer `docs.topics`). */
+export const DOCS_GENERATED_SAVE_TOPICS = ["mcp", "api", "skill"] as const;
+
+/** Whether `--save` should prepend a generated-file hint (argsbarg writers only). */
+export function docsTopicIsGeneratedByArgsbarg(topic: string): boolean {
+  return (DOCS_GENERATED_SAVE_TOPICS as readonly string[]).includes(topic);
+}
+
+/** HTML comment prepended to generated markdown saved with `--save`. */
+export function docsSaveGeneratedHint(program: CliProgram, topic: string): string {
+  return `<!-- Generated by ${program.key} docs ${topic} --save; do not edit. -->\n\n`;
+}
+
+/** File body for `--save` (hint on argsbarg-generated markdown only). */
+export function docsTopicContentForSave(program: CliProgram, topic: string): string {
+  const content = docsTopicContent(program, topic);
+  if (!docsTopicIsGeneratedByArgsbarg(topic)) {
+    return content;
+  }
+  return `${docsSaveGeneratedHint(program, topic)}${content}`;
+}
+
+/** Filename for a saved docs topic. */
+export function docsSaveFilename(topic: string): string {
+  if (topic === "schema") {
+    return "schema.json";
+  }
+  return `${topic}.md`;
+}
+
+/** Topic keys to write for one `docs` invocation (`all` expands to bundled topics). */
+export function docsTopicsToSave(program: CliProgram, topic: string): string[] {
+  if (topic === "all") {
+    return docsPrintOrder(program);
+  }
+  return [topic];
+}
+
+/** Writes docs topic(s) under `./docs/`; returns relative paths written. */
+export function saveDocsTopics(program: CliProgram, topic: string): string[] {
+  const dir = join(process.cwd(), DOCS_SAVE_DIR);
+  mkdirSync(dir, { recursive: true });
+
+  const saved: string[] = [];
+  for (const key of docsTopicsToSave(program, topic)) {
+    const rel = join(DOCS_SAVE_DIR, docsSaveFilename(key));
+    const abs = join(process.cwd(), rel);
+    writeFileSync(abs, docsTopicContentForSave(program, key), "utf8");
+    saved.push(rel);
+  }
+  return saved;
+}