argsbarg 3.3.3 → 3.3.4

package/CHANGELOG.md

@@ -7,11 +7,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [3.3.4] - 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.
+- **`docs --save`** — write one docs subcommand to `./docs/`; argsbarg-generated markdown (`mcp`, `api`, `skill`) is prefixed with a `Generated by … docs … --save` HTML comment.
+
+### Removed
+
+- **`docs all`** — use individual subcommands (`docs readme`, `docs schema`, `docs api`, …) or `--save` per topic.
 
 ## [3.3.2] - 2026-06-21
 
@@ -255,7 +262,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.3...HEAD
+[Unreleased]: https://github.com/bdombro/bun-argsbarg/compare/v3.3.4...HEAD
+[3.3.4]: https://github.com/bdombro/bun-argsbarg/releases/tag/v3.3.4
 [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

package/docs/bundled-docs.md

@@ -30,10 +30,9 @@ myapp docs architecture
 myapp docs schema       # full command tree as JSON
 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
+myapp docs schema --save   # write ./docs/schema.json
 ```
 
 ## Configuration
@@ -45,7 +44,7 @@ myapp docs all --save      # write ./docs/<topic>.md for each bundled topic
 | `defaultTopic` | first key in `topics` | `fallbackCommand` for bare `myapp docs` |
 | `topics` | *(required)* | Topic key → `{ text, description? }` |
 
-Reserved topic keys in `topics`: **`mcp`**, **`all`**, **`schema`**, **`api`**, **`skill`** (supplied by the built-in).
+Reserved topic keys in `topics`: **`mcp`**, **`all`**, **`schema`**, **`api`**, **`skill`** (reserved — use the matching `docs <name>` subcommand instead).
 
 When `description` is omitted on a topic, ArgsBarg generates leaf help (`readme` → "Print README (user guide).").
 
@@ -102,8 +101,5 @@ Pass **`--save`** on `docs` or any docs subcommand to write files under **`./doc
 | `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.
+Argsbarg-generated markdown (`mcp`, `api`, `skill`) includes a `Generated by … docs … --save` HTML comment (`skill` places it after YAML frontmatter so parsers still work). Consumer topic files and `schema.json` are written as-is.

package/package.json

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

package/src/docs/builtin.ts

@@ -8,19 +8,17 @@ import {
   docsUserTopicKeys,
   printDocsTopic,
 } from "./resolve.ts";
-import { saveDocsTopics } from "./save.ts";
+import { saveDocsTopic } from "./save.ts";
 
 const DOCS_SAVE_OPTION: CliOption = {
   name: "save",
-  description: "Write documentation to ./docs/ (`docs all` writes one file per topic).",
+  description: "Write documentation to ./docs/.",
   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`);
-    }
+    process.stdout.write(`${saveDocsTopic(program, topic)}\n`);
     return;
   }
   printDocsTopic(program, topic);
@@ -58,7 +56,6 @@ export function cliBuiltinDocsGroup(program: CliProgram): CliRouter {
     docsLeaf(program, "schema", "Print the full command tree as JSON."),
     docsLeaf(program, "api", "Print the command tree as markdown."),
     docsLeaf(program, "skill", "Print generated Cursor SKILL.md content."),
-    docsLeaf(program, "all", "Print all bundled documentation combined."),
   );
 
   return {

package/src/docs/docs.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, test, beforeEach, afterEach } from "bun:test";
-import { existsSync, mkdtempSync, readFileSync, rmSync } from "node:fs";
+import { mkdtempSync, readFileSync, rmSync } from "node:fs";
 import { join } from "node:path";
 import { tmpdir } from "node:os";
 import { cliPresentationRoot } from "../builtins/presentation.ts";
@@ -7,9 +7,9 @@ import { completionBashScript } from "../completion.ts";
 import { cliInvoke } from "../index.ts";
 import type { CliProgram } from "../types.ts";
 import { cliValidateProgram } from "../validate.ts";
-import { combineAllDocs, docsEffectiveDefaultTopic } from "./resolve.ts";
+import { docsEffectiveDefaultTopic } from "./resolve.ts";
 import { generateMcpGuide } from "./mcp-guide.ts";
-import { docsTopicsToSave, saveDocsTopics } from "./save.ts";
+import { saveDocsTopic } from "./save.ts";
 
 let workDir: string;
 let prevCwd: string;
@@ -104,6 +104,11 @@ test("docs mcp when MCP enabled", async () => {
   expect(result.stdout).toContain("myapp mcp");
 });
 
+test("docs rejects unknown subcommand", async () => {
+  const result = await cliInvoke(docsFixture(), ["docs", "all"]);
+  expect(result.exitCode).not.toBe(0);
+});
+
 test("docs mcp absent from router when MCP disabled", async () => {
   const root = docsFixture(false);
   const presentation = cliPresentationRoot(root);
@@ -116,14 +121,6 @@ test("docs mcp absent from router when MCP disabled", async () => {
   expect(result.exitCode).not.toBe(0);
 });
 
-test("docs all concatenates user topics and mcp", () => {
-  const program = docsFixture(true);
-  const combined = combineAllDocs(program);
-  expect(combined).toContain("Hello README");
-  expect(combined).toContain("Architecture");
-  expect(combined).toContain("MCP server (myapp)");
-});
-
 test("presentation includes docs subtree", () => {
   const presentation = cliPresentationRoot(docsFixture());
   const docsNode = presentation.commands.find((c) => c.key === "docs");
@@ -203,6 +200,16 @@ test("docs api --save prepends generated hint", async () => {
   expect(text).toContain("CLI API reference");
 });
 
+test("docs skill --save keeps frontmatter first", async () => {
+  const result = await cliInvoke(docsFixture(), ["docs", "skill", "--save"]);
+  expect(result.exitCode).toBe(0);
+  const text = readFileSync(join(workDir, "docs/skill.md"), "utf8");
+  expect(text.startsWith("---\n")).toBe(true);
+  expect(text).toContain("name: myapp");
+  const hint = "<!-- Generated by myapp docs skill --save; do not edit. -->";
+  expect(text.indexOf(hint)).toBeGreaterThan(text.indexOf("---\n", 4));
+});
+
 test("docs schema --save writes JSON file", async () => {
   const result = await cliInvoke(docsFixture(), ["docs", "schema", "--save"]);
   expect(result.exitCode).toBe(0);
@@ -213,21 +220,9 @@ test("docs schema --save writes JSON file", async () => {
   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"]);
+test("saveDocsTopic returns relative path", () => {
+  const path = saveDocsTopic(docsFixture(), "api");
+  expect(path).toBe("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

@@ -51,16 +51,6 @@ export function docsTopicDescription(key: string, custom?: string): string {
   return `Print ${label} documentation.`;
 }
 
-/** Ordered keys for `docs all` (user topics, then auto `mcp` when enabled). */
-export function docsPrintOrder(program: CliProgram): string[] {
-  const docs = program.docs!;
-  const order = docsUserTopicKeys(docs);
-  if (docsIncludesMcpTopic(program)) {
-    order.push("mcp");
-  }
-  return order;
-}
-
 /** Markdown body for one docs topic key. */
 export function docsTopicText(program: CliProgram, topic: string): string {
   const docs = program.docs!;
@@ -88,21 +78,11 @@ export function docsTopicContent(program: CliProgram, topic: string): string {
   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)
-    .map((key) => docsTopicText(program, key).trim())
-    .join("\n\n---\n\n");
-}
-
-/** Writes one docs topic (or `all`) to stdout. */
+/** Writes one docs topic to stdout. */
 export function printDocsTopic(program: CliProgram, topic: string): void {
   process.stdout.write(docsTopicContent(program, topic));
 }

package/src/docs/save.ts

@@ -1,7 +1,7 @@
 import { mkdirSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import type { CliProgram } from "../types.ts";
-import { docsPrintOrder, docsTopicContent } from "./resolve.ts";
+import { docsTopicContent } from "./resolve.ts";
 
 /** Relative output directory for `docs --save`. */
 export const DOCS_SAVE_DIR = "docs";
@@ -14,18 +14,31 @@ 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`. */
+/** HTML comment for 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);
+const SKILL_FRONTMATTER_RE = /^---\r?\n[\s\S]*?\r?\n---\r?\n/;
+
+/** Inserts save hint without breaking YAML frontmatter (`docs skill`). */
+export function applySaveGeneratedHint(program: CliProgram, topic: string, content: string): string {
   if (!docsTopicIsGeneratedByArgsbarg(topic)) {
     return content;
   }
-  return `${docsSaveGeneratedHint(program, topic)}${content}`;
+  const hint = docsSaveGeneratedHint(program, topic);
+  if (topic === "skill") {
+    const match = content.match(SKILL_FRONTMATTER_RE);
+    if (match) {
+      return `${match[0]}${hint}${content.slice(match[0].length)}`;
+    }
+  }
+  return `${hint}${content}`;
+}
+
+/** File body for `--save` (hint on argsbarg-generated markdown only). */
+export function docsTopicContentForSave(program: CliProgram, topic: string): string {
+  return applySaveGeneratedHint(program, topic, docsTopicContent(program, topic));
 }
 
 /** Filename for a saved docs topic. */
@@ -36,25 +49,18 @@ export function docsSaveFilename(topic: string): string {
   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];
+/** Relative path under cwd for a saved docs topic. */
+export function docsSaveRelativePath(topic: string): string {
+  return join(DOCS_SAVE_DIR, docsSaveFilename(topic));
 }
 
-/** Writes docs topic(s) under `./docs/`; returns relative paths written. */
-export function saveDocsTopics(program: CliProgram, topic: string): string[] {
+/** Writes one docs topic under `./docs/`; returns relative path written. */
+export function saveDocsTopic(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;
+  const rel = docsSaveRelativePath(topic);
+  const abs = join(process.cwd(), rel);
+  writeFileSync(abs, docsTopicContentForSave(program, topic), "utf8");
+  return rel;
 }