argsbarg 7.0.6 → 7.0.8

package/src/docs/save.ts

@@ -1,20 +1,19 @@
 /*
 This module persists bundled documentation topics to disk when `--save` is passed.
-It writes documentation under `./docs/` and agent skills under `./skills/<app-name>/SKILL.md`.
+It writes documentation under `./docs/`.
 */
 
-import { existsSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { mkdirSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import type { CliProgram } from "../core/types.ts";
 import { generatedFileHtmlComment, insertGeneratedHint } from "../skill/hint.ts";
-import { skillDirName } from "../skill/naming.ts";
 import { 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", "cli", "skill", "http"] as const;
+export const DOCS_GENERATED_SAVE_TOPICS = ["mcp", "cli", "http"] as const;
 
 /** Whether `--save` should prepend a generated-file hint (argsbarg writers only). */
 export function docsTopicIsGeneratedByArgsbarg(
@@ -34,7 +33,7 @@ export function docsSaveGeneratedHint(
   return generatedFileHtmlComment(`${program.key} docs ${topic} --save`);
 }
 
-/** Inserts save hint without breaking YAML frontmatter (`docs skill`). */
+/** Inserts save hint into markdown content. */
 export function applySaveGeneratedHint(
   /** Program definition. */
   program: CliProgram,
@@ -47,7 +46,7 @@ export function applySaveGeneratedHint(
     return content;
   }
   const hint = docsSaveGeneratedHint(program, topic);
-  return insertGeneratedHint(content, hint, topic === "skill" ? { afterFrontmatter: true } : undefined);
+  return insertGeneratedHint(content, hint);
 }
 
 /** File body for `--save` (hint on argsbarg-generated markdown only). */
@@ -74,20 +73,17 @@ export function docsSaveFilename(
   return `${topic}.md`;
 }
 
-/** Relative path under cwd for a saved docs topic (or skills/<key>/SKILL.md for skill). */
+/** Relative path under cwd for a saved docs topic. */
 export function docsSaveRelativePath(
   /** Topic identifier. */
   topic: string,
-  /** Program root for resolving app-specific paths like skill directories. */
-  program?: CliProgram,
+  /** Program root for resolving app-specific paths. */
+  _program?: CliProgram,
 ): string {
-  if (topic === "skill" && program) {
-    return join("skills", skillDirName(program.key), "SKILL.md");
-  }
   return join(DOCS_SAVE_DIR, docsSaveFilename(topic));
 }
 
-/** Writes one docs topic under `./docs/` or `./skills/<key>/`; returns relative path written. */
+/** Writes one docs topic under `./docs/`; returns relative path written. */
 export function saveDocsTopic(
   /** Program definition root. */
   program: CliProgram,
@@ -98,13 +94,6 @@ export function saveDocsTopic(
   const abs = join(process.cwd(), rel);
   mkdirSync(dirname(abs), { recursive: true });
 
-  if (topic === "skill") {
-    const legacyDoc = join(process.cwd(), DOCS_SAVE_DIR, "skill.md");
-    if (existsSync(legacyDoc)) {
-      rmSync(legacyDoc, { force: true });
-    }
-  }
-
   writeFileSync(abs, docsTopicContentForSave(program, topic), "utf8");
   return rel;
 }

package/src/help.test.ts

@@ -5,7 +5,14 @@ Help rendering and label formatting tests.
 import { describe, expect, test } from "bun:test";
 import { cliPresentationRoot } from "./builtins/presentation.ts";
 import { type CliOption, CliOptionKind, type CliPositional } from "./core/types.ts";
-import { CLI_NOTES_PROGRAM, cliHelpRender, cliOptionLabel, cliPositionalLabel, cliResolveNotes } from "./help.ts";
+import {
+  CLI_NOTES_PROGRAM,
+  cliHelpRender,
+  cliOptionLabel,
+  cliPositionalLabel,
+  cliResolveNotes,
+  schemaToYamlLines,
+} from "./help.ts";
 import { testProgram } from "./test/fixtures.ts";
 
 describe("cliOptionLabel", () => {
@@ -64,7 +71,7 @@ describe("cliResolveNotes", () => {
 });
 
 describe("cliHelpRender", () => {
-  test("docs help lists schema, cli, and skill subcommands", () => {
+  test("docs help lists schema and cli subcommands", () => {
     const root = testProgram({
       key: "app",
       version: "1.0.0",
@@ -85,8 +92,7 @@ describe("cliHelpRender", () => {
     expect(help).toContain("Print the full CLI command tree as JSON.");
     expect(help).toContain("cli");
     expect(help).toContain("markdown");
-    expect(help).toContain("skill");
-    expect(help).toContain("reference agent SKILL");
+    expect(help).not.toContain("skill");
   });
 
   test("root help omits legacy --schema flag", () => {
@@ -106,7 +112,7 @@ describe("cliHelpRender", () => {
     expect(help).not.toContain("--schema");
   });
 
-  test("root help shows agent docs hint when docs enabled", () => {
+  test("root help omits agent docs hint when docs enabled", () => {
     const root = testProgram({
       key: "myapp",
       version: "1.0.0",
@@ -117,7 +123,7 @@ describe("cliHelpRender", () => {
       commands: [{ key: "run", description: "Run.", handler: () => {} }],
     });
     const help = cliHelpRender(cliPresentationRoot(root), [], false);
-    expect(help).toContain("For AI agents: `myapp docs skill`.");
+    expect(help).not.toContain("docs skill");
     expect(help).not.toContain("install --skill");
   });
 
@@ -134,7 +140,7 @@ describe("cliHelpRender", () => {
     expect(help).not.toContain("docs skill");
   });
 
-  test("root help includes program notes and agent hint", () => {
+  test("root help includes program notes", () => {
     const root = testProgram({
       key: "myapp",
       version: "1.0.0",
@@ -147,6 +153,242 @@ describe("cliHelpRender", () => {
     });
     const help = cliHelpRender(cliPresentationRoot(root), [], false);
     expect(help).toContain("See `myapp docs readme` for the user guide.");
-    expect(help).toContain("myapp docs skill");
+    expect(help).not.toContain("docs skill");
+  });
+
+  /** Tests that non-TTY help strips box characters and renders plain text. */
+  test("non-TTY help strips boxes and renders clean plain text", () => {
+    const root = testProgram({
+      key: "myapp",
+      version: "1.0.0",
+      description: "Test application.",
+      commands: [
+        {
+          key: "status",
+          description: "Show status.",
+          options: [
+            {
+              name: "verbose",
+              shortName: "v",
+              description: "Verbose output.",
+              kind: CliOptionKind.Presence,
+            },
+          ],
+          handler: () => {},
+        },
+      ],
+    });
+    const help = cliHelpRender(cliPresentationRoot(root), ["status"], false, { isTTY: false });
+    expect(help).not.toContain("╭─");
+    expect(help).not.toContain("╰─");
+    expect(help).not.toContain("│");
+    expect(help).toContain("Usage:\n  myapp status [OPTIONS]");
+    expect(help).toContain("Options:\n  --help, -h     Show help for this command.\n  --verbose, -v  Verbose output.");
+  });
+
+  /** Tests that TTY help renders rounded UTF-8 boxes. */
+  test("TTY help renders rounded UTF-8 boxes and omits output schema by default", () => {
+    const root = testProgram({
+      key: "myapp",
+      version: "1.0.0",
+      description: "Test application.",
+      commands: [
+        {
+          key: "status",
+          description: "Show status.",
+          outputSchema: {
+            type: "object",
+            properties: {
+              version: { type: "string", description: "App version." },
+            },
+            required: ["version"],
+          },
+          handler: () => {},
+        },
+      ],
+    });
+    const help = cliHelpRender(cliPresentationRoot(root), ["status"], false, { isTTY: true });
+    expect(help).toContain("╭");
+    expect(help).toContain("╰");
+    expect(help).toContain("│");
+    expect(help).not.toContain("Output Schema");
+  });
+
+  /** Tests that non-TTY help automatically includes output schema in YAML by default. */
+  test("non-TTY help automatically includes output schema in YAML by default", () => {
+    const root = testProgram({
+      key: "myapp",
+      version: "1.0.0",
+      description: "Test application.",
+      commands: [
+        {
+          key: "status",
+          description: "Show status.",
+          outputSchema: {
+            type: "object",
+            properties: {
+              version: { type: "string", description: "App version." },
+            },
+            required: ["version"],
+          },
+          handler: () => {},
+        },
+      ],
+    });
+    const help = cliHelpRender(cliPresentationRoot(root), ["status"], false, { isTTY: false });
+    expect(help).toContain("Output Schema (with --json):");
+    expect(help).toContain("# App version.");
+    expect(help).toContain("version: string");
+  });
+
+  /** Tests that json leaf commands render Output Schema (JSON) and Input Schema. */
+  test("json leaf renders Output Schema (JSON) and Input Schema in non-TTY mode", () => {
+    const root = testProgram({
+      key: "myapp",
+      version: "1.0.0",
+      description: "Test application.",
+      commands: [
+        {
+          key: "create",
+          kind: "json",
+          description: "Create resource.",
+          inputSchema: {
+            type: "object",
+            properties: {
+              name: { type: "string", description: "Resource name." },
+            },
+            required: ["name"],
+          },
+          outputSchema: {
+            type: "object",
+            properties: {
+              id: { type: "string", description: "Generated ID." },
+            },
+            required: ["id"],
+          },
+          handler: () => {},
+        },
+      ],
+    });
+    const help = cliHelpRender(cliPresentationRoot(root), ["create"], false, { isTTY: false });
+    expect(help).toContain("Input Schema:");
+    expect(help).toContain("# Resource name.");
+    expect(help).toContain("name: string");
+    expect(help).toContain("Output Schema (JSON):");
+    expect(help).toContain("# Generated ID.");
+    expect(help).toContain("id: string");
+  });
+});
+
+/** Tests for converting JSON Schema to human- and agent-friendly YAML lines. */
+describe("schemaToYamlLines", () => {
+  /** Tests primitive properties with required and optional keys and comments. */
+  test("formats primitive properties with descriptions and optionality", () => {
+    const schema = {
+      type: "object",
+      properties: {
+        documentId: {
+          type: "string",
+          description: "Unique document identifier.",
+        },
+        index: {
+          type: "integer",
+        },
+      },
+      required: ["documentId"],
+    };
+    const lines = schemaToYamlLines(schema, 0);
+    expect(lines).toEqual(["# Unique document identifier.", "documentId: string", "index?: integer"]);
+  });
+
+  /** Tests enums, string formats, and union types. */
+  test("formats enums, string formats, and union types", () => {
+    const schema = {
+      type: "object",
+      properties: {
+        format: {
+          type: "string",
+          enum: ["pdf", "html"],
+        },
+        createdAt: {
+          type: "string",
+          format: "date-time",
+        },
+        status: {
+          anyOf: [{ type: "string" }, { type: "number" }],
+        },
+      },
+    };
+    const lines = schemaToYamlLines(schema, 0);
+    expect(lines).toEqual(['format?: "pdf" | "html"', "createdAt?: string (date-time)", "status?: string | number"]);
+  });
+
+  /** Tests nested objects and arrays of objects with definitions. */
+  test("formats nested objects and arrays of objects with definition resolution", () => {
+    const schema = {
+      type: "object",
+      properties: {
+        tab: {
+          type: "object",
+          description: "Active tab metadata.",
+          properties: {
+            tabId: { type: "string" },
+            title: { type: "string" },
+          },
+          required: ["tabId", "title"],
+        },
+        tabs: {
+          type: "array",
+          items: {
+            $ref: "#/definitions/TabItem",
+          },
+        },
+      },
+      definitions: {
+        TabItem: {
+          type: "object",
+          properties: {
+            tabId: { type: "string" },
+            title: { type: "string" },
+            index: { type: "integer" },
+          },
+          required: ["tabId", "title", "index"],
+        },
+      },
+      required: ["tab"],
+    };
+    const lines = schemaToYamlLines(schema, 0);
+    expect(lines).toEqual([
+      "# Active tab metadata.",
+      "tab:",
+      "  tabId: string",
+      "  title: string",
+      "tabs?:",
+      "  - tabId: string",
+      "    title: string",
+      "    index: integer",
+    ]);
+  });
+
+  /** Tests recursive references handle cycles gracefully without infinite loop. */
+  test("handles recursive definition references without infinite loop", () => {
+    const schema = {
+      type: "object",
+      properties: {
+        name: { type: "string" },
+        parent: { $ref: "#/definitions/TreeNode" },
+      },
+      definitions: {
+        TreeNode: {
+          type: "object",
+          properties: {
+            name: { type: "string" },
+            parent: { $ref: "#/definitions/TreeNode" },
+          },
+        },
+      },
+    };
+    const lines = schemaToYamlLines(schema, 0);
+    expect(lines).toEqual(["name?: string", "parent?:", "  name?: string", "  parent?: TreeNode"]);
   });
 });