argsbarg 3.3.5 → 3.3.7

package/CHANGELOG.md

@@ -7,6 +7,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [3.3.7] - 2026-06-21
+
+### Changed
+
+- **`docs mcp`** — intro copy is user-facing (`exposes an MCP server with features similar to the CLI`) instead of describing argsbarg internals.
+
+## [3.3.6] - 2026-06-21
+
+### Added
+
+- **`install --skill`** — installed `SKILL.md` and `reference.md` include a `Generated by … install --skill` HTML comment (after SKILL.md frontmatter).
+
 ## [3.3.5] - 2026-06-21
 
 ### Changed
@@ -276,7 +288,9 @@ 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.5...HEAD
+[Unreleased]: https://github.com/bdombro/bun-argsbarg/compare/v3.3.7...HEAD
+[3.3.7]: https://github.com/bdombro/bun-argsbarg/releases/tag/v3.3.7
+[3.3.6]: https://github.com/bdombro/bun-argsbarg/releases/tag/v3.3.6
 [3.3.5]: https://github.com/bdombro/bun-argsbarg/releases/tag/v3.3.5
 [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

package/docs/ai-skills.md

@@ -34,6 +34,8 @@ For library use, call `cliSkillInstall(root, "cursor" | "claude", { global: true
 - **`SKILL.md`** — YAML frontmatter, when-to-use guidance, shell command catalog, pitfalls
 - **`reference.md`** — full `docs schema` JSON export
 
+Installed files include an HTML comment hint (`Generated by myapp install --skill; do not edit.`) after SKILL.md frontmatter and at the top of `reference.md`.
+
 Skills describe **shell invocation only** — no MCP setup, `mcp.json`, or `tools/call` guidance. Use **`myapp docs mcp`** (when `docs` and `mcpServer` are enabled) or connect the MCP server for agent execution.
 
 ## MCP vs skills vs docs

package/package.json

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

package/src/docs/mcp-guide.ts

@@ -29,7 +29,7 @@ export function generateMcpGuide(root: CliProgram): string {
   const lines: string[] = [
     `# MCP server (${root.key})`,
     "",
-    `${root.key} exposes an MCP server via argsbarg. Each exposed leaf command becomes an MCP tool.`,
+    `${root.key} exposes an MCP server with features similar to the CLI.`,
     "",
     "## Quick start",
     "",

package/src/docs/save.ts

@@ -2,6 +2,7 @@ import { mkdirSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import type { CliProgram } from "../types.ts";
 import { docsTopicContent } from "./resolve.ts";
+import { generatedFileHtmlComment, insertGeneratedHint } from "../skill/hint.ts";
 
 /** Relative output directory for `docs --save`. */
 export const DOCS_SAVE_DIR = "docs";
@@ -16,24 +17,16 @@ export function docsTopicIsGeneratedByArgsbarg(topic: string): boolean {
 
 /** 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`;
+  return generatedFileHtmlComment(`${program.key} docs ${topic} --save`);
 }
 
-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;
   }
   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}`;
+  return insertGeneratedHint(content, hint, topic === "skill" ? { afterFrontmatter: true } : undefined);
 }
 
 /** File body for `--save` (hint on argsbarg-generated markdown only). */

package/src/index.test.ts

@@ -1773,7 +1773,9 @@ test("generateSkillBundle includes frontmatter and command catalog", () => {
   expect(bundle.skillMd).not.toContain("mcp.json");
   expect(bundle.skillMd).not.toContain("Prefer MCP");
   expect(bundle.skillMd).not.toContain("tools/call");
+  expect(bundle.skillMd).not.toContain("Generated by");
   expect(bundle.referenceMd).toContain("```json");
+  expect(bundle.referenceMd).not.toContain("Generated by");
   expect(() => JSON.parse(bundle.referenceMd.match(/```json\n([\s\S]*?)\n```/)![1]!)).not.toThrow();
 });
 
@@ -1788,6 +1790,12 @@ test("cliSkillInstall writes project Cursor skill files", () => {
     expect(existsSync(join(skillDir, "SKILL.md"))).toBe(true);
     expect(existsSync(join(skillDir, "reference.md"))).toBe(true);
     expect(readFileSync(join(skillDir, "SKILL.md"), "utf8")).toContain("stat owner lookup");
+    const skillText = readFileSync(join(skillDir, "SKILL.md"), "utf8");
+    expect(skillText.startsWith("---\n")).toBe(true);
+    const hint = "<!-- Generated by nested.ts install --skill; do not edit. -->";
+    expect(skillText.indexOf(hint)).toBeGreaterThan(skillText.indexOf("---\n", 4));
+    const refText = readFileSync(join(skillDir, "reference.md"), "utf8");
+    expect(refText.startsWith(hint)).toBe(true);
   } finally {
     process.chdir(prev);
     rmSync(cwd, { recursive: true, force: true });

package/src/skill/hint.ts

@@ -0,0 +1,42 @@
+import type { CliProgram } from "../types.ts";
+
+/** YAML frontmatter block at the start of SKILL.md. */
+export const MARKDOWN_FRONTMATTER_RE = /^---\r?\n[\s\S]*?\r?\n---\r?\n/;
+
+/** HTML comment marking argsbarg-generated markdown. */
+export function generatedFileHtmlComment(source: string): string {
+  return `<!-- Generated by ${source}; do not edit. -->\n\n`;
+}
+
+/** Prepends a hint, or inserts after frontmatter when requested. */
+export function insertGeneratedHint(
+  content: string,
+  hint: string,
+  options?: { afterFrontmatter?: boolean },
+): string {
+  if (options?.afterFrontmatter) {
+    const match = content.match(MARKDOWN_FRONTMATTER_RE);
+    if (match) {
+      return `${match[0]}${hint}${content.slice(match[0].length)}`;
+    }
+  }
+  return `${hint}${content}`;
+}
+
+/** Hint for `install --skill` output files. */
+export function skillInstallHint(program: CliProgram): string {
+  return generatedFileHtmlComment(`${program.key} install --skill`);
+}
+
+/** Applies install hints to SKILL.md (after frontmatter) and reference.md. */
+export function applySkillInstallHints(
+  program: CliProgram,
+  skillMd: string,
+  referenceMd: string,
+): { skillMd: string; referenceMd: string } {
+  const hint = skillInstallHint(program);
+  return {
+    skillMd: insertGeneratedHint(skillMd, hint, { afterFrontmatter: true }),
+    referenceMd: insertGeneratedHint(referenceMd, hint),
+  };
+}

package/src/skill/install.ts

@@ -3,6 +3,7 @@ import { homedir } from "node:os";
 import { join } from "node:path";
 import { CliProgram } from "../types.ts";
 import { generateSkillBundle, type SkillTarget } from "./generate.ts";
+import { applySkillInstallHints } from "./hint.ts";
 
 export interface SkillInstallOpts {
   global?: boolean;
@@ -26,6 +27,7 @@ function resolveSkillDir(target: SkillTarget, dirName: string, global: boolean):
 /** Writes SKILL.md and reference.md; returns changed file paths. */
 export function cliSkillInstall(root: CliProgram, target: SkillTarget, opts: SkillInstallOpts): string[] {
   const bundle = generateSkillBundle(root, target);
+  const { skillMd, referenceMd } = applySkillInstallHints(root, bundle.skillMd, bundle.referenceMd);
   const dir = resolveSkillDir(target, bundle.dirName, opts.global ?? false);
   const changed: string[] = [];
 
@@ -38,8 +40,8 @@ export function cliSkillInstall(root: CliProgram, target: SkillTarget, opts: Ski
 
   if (!opts.dry) {
     mkdirSync(dir, { recursive: true });
-    writeFileSync(skillPath, bundle.skillMd, "utf8");
-    writeFileSync(refPath, bundle.referenceMd, "utf8");
+    writeFileSync(skillPath, skillMd, "utf8");
+    writeFileSync(refPath, referenceMd, "utf8");
   }
 
   changed.push(skillPath, refPath);