argsbarg 5.0.1 → 5.0.2

package/src/mcp/env.test.ts

@@ -1,3 +1,7 @@
+/*
+Tests for mcp/env module behavior.
+*/
+
 import { afterEach, beforeEach, describe, expect, test } from "bun:test";
 import { chmodSync, mkdtempSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
@@ -6,7 +10,9 @@ import { applyShellEnv, bootstrapMcpEnv } from "./env.ts";
 
 const TEST_VAR = "ARGS_BARG_SHELL_ENV_TEST";
 
+/** Tests for mcp/env. */
 describe("mcp/env", () => {
+  /** ApplyShellEnv merges PATH and fills missing vars. */
   test("applyShellEnv merges PATH and fills missing vars", () => {
     const prevPath = process.env.PATH;
     const prevTest = process.env[TEST_VAR];
@@ -27,6 +33,7 @@ describe("mcp/env", () => {
     }
   });
 
+  /** ApplyShellEnv does not overwrite host vars except PATH merge. */
   test("applyShellEnv does not overwrite host vars except PATH merge", () => {
     const prev = process.env.HOME;
     process.env.HOME = "/host/home";
@@ -40,6 +47,7 @@ describe("mcp/env", () => {
   });
 });
 
+/** Tests for bootstrapMcpEnv. */
 describe("bootstrapMcpEnv", () => {
   let fakeShell: string;
   let prevShell: string | undefined;
@@ -70,21 +78,25 @@ fi
     else process.env[TEST_VAR] = prevTest;
   });
 
+  /** Defaults on when shellEnv is undefined. */
   test("defaults on when shellEnv is undefined", () => {
     bootstrapMcpEnv({});
     expect(process.env[TEST_VAR]).toBe("from_fake_shell");
   });
 
+  /** Runs when shellEnv is true. */
   test("runs when shellEnv is true", () => {
     bootstrapMcpEnv({ shellEnv: true });
     expect(process.env[TEST_VAR]).toBe("from_fake_shell");
   });
 
+  /** Tests that uses explicit shell path when shellEnv is a string. */
   test("uses explicit shell path when shellEnv is a string", () => {
     bootstrapMcpEnv({ shellEnv: fakeShell });
     expect(process.env[TEST_VAR]).toBe("from_fake_shell");
   });
 
+  /** Tests that skips capture when shellEnv is false. */
   test("skips capture when shellEnv is false", () => {
     bootstrapMcpEnv({ shellEnv: false });
     expect(process.env[TEST_VAR]).toBeUndefined();

package/src/mcp/zip.test.ts

@@ -1,3 +1,7 @@
+/*
+Tests for mcp/zip module behavior.
+*/
+
 import { expect, test } from "bun:test";
 import { execSync } from "node:child_process";
 import { mkdtempSync, readFileSync, statSync, writeFileSync } from "node:fs";
@@ -5,6 +9,7 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { zipStore } from "./zip.ts";
 
+/** ZipStore preserves unix executable mode on extract. */
 test("zipStore preserves unix executable mode on extract", () => {
   const work = mkdtempSync(join(tmpdir(), "zip-exec-"));
   const data = Buffer.from("#!/bin/sh\necho hi\n");

package/src/mcp.integration.test.ts

@@ -17,10 +17,12 @@ import { cliSchemaExport } from "./schema.ts";
 import { mcpRequest, nestedMcpFixture, testProgram } from "./test-fixtures.ts";
 import { cliValidateProgram } from "./validate.ts";
 
+/** Tests that sanitizeToolSegment normalizes dotted app keys. */
 test("sanitizeToolSegment normalizes dotted app keys", () => {
   expect(sanitizeToolSegment("minimal.ts")).toBe("minimal_ts");
 });
 
+/** McpToolDescription formats CLI path and root-leaf prefix. */
 test("mcpToolDescription formats CLI path and root-leaf prefix", () => {
   expect(mcpToolDescription(["stat", "owner", "lookup"], "nested.ts", "Resolve owner info.")).toBe(
     "stat owner lookup — Resolve owner info.",
@@ -29,6 +31,7 @@ test("mcpToolDescription formats CLI path and root-leaf prefix", () => {
   expect(mcpToolDescription([], "helloapp", "Tiny demo.")).toBe("helloapp — Tiny demo.");
 });
 
+/** Tests that collectMcpTools lists user leaf commands only. */
 test("collectMcpTools lists user leaf commands only", () => {
   const tools = collectMcpTools(nestedMcpFixture);
   const names = tools.map((t) => t.name);
@@ -42,6 +45,7 @@ test("collectMcpTools lists user leaf commands only", () => {
   expect(lookup.description).toBe("stat owner lookup — Resolve owner info.");
 });
 
+/** Tests that collectMcpTools appends leaf notes to MCP tool description. */
 test("collectMcpTools appends leaf notes to MCP tool description", () => {
   const root = testProgram({
     key: "app",
@@ -61,6 +65,7 @@ test("collectMcpTools appends leaf notes to MCP tool description", () => {
   expect(tools[0]?.description).toBe("run — Run.\n\nUse `--json` for structured output.");
 });
 
+/** Tests that collectMcpTools appends notes after mcpTool.description override. */
 test("collectMcpTools appends notes after mcpTool.description override", () => {
   const root = testProgram({
     key: "app",
@@ -81,6 +86,7 @@ test("collectMcpTools appends notes after mcpTool.description override", () => {
   expect(tools[0]?.description).toBe("Custom MCP text.\n\nOperational hint.");
 });
 
+/** Tests that collectMcpTools resolves {argsbarg:program} in appended notes. */
 test("collectMcpTools resolves {argsbarg:program} in appended notes", () => {
   const root = testProgram({
     key: "myapp",
@@ -100,6 +106,7 @@ test("collectMcpTools resolves {argsbarg:program} in appended notes", () => {
   expect(tools[0]?.description).toContain("See `myapp docs api`.");
 });
 
+/** CliSchemaExport includes leaf outputSchema. */
 test("cliSchemaExport includes leaf outputSchema", () => {
   const root = testProgram({
     key: "app",
@@ -125,6 +132,7 @@ test("cliSchemaExport includes leaf outputSchema", () => {
   });
 });
 
+/** CliSchemaExport accepts legacy mcpTool.outputSchema. */
 test("cliSchemaExport accepts legacy mcpTool.outputSchema", () => {
   const root = testProgram({
     key: "app",
@@ -147,6 +155,7 @@ test("cliSchemaExport accepts legacy mcpTool.outputSchema", () => {
   });
 });
 
+/** Tests that outputSchema must be a JSON Schema object. */
 test("outputSchema must be a JSON Schema object", () => {
   const root = testProgram({
     key: "app",
@@ -164,6 +173,7 @@ test("outputSchema must be a JSON Schema object", () => {
   expect(() => cliValidateProgram(root)).toThrow(/outputSchema must be a JSON Schema object/);
 });
 
+/** Tests that outputSchema cannot be set on both leaf and mcpTool. */
 test("outputSchema cannot be set on both leaf and mcpTool", () => {
   const root = testProgram({
     key: "app",
@@ -182,6 +192,7 @@ test("outputSchema cannot be set on both leaf and mcpTool", () => {
   expect(() => cliValidateProgram(root)).toThrow(/Set outputSchema on the leaf only/);
 });
 
+/** Tests that collectMcpTools merges parent options into inputSchema. */
 test("collectMcpTools merges parent options into inputSchema", () => {
   const tools = collectMcpTools(nestedMcpFixture);
   const lookup = tools.find((t) => t.name === "stat_owner_lookup")!;
@@ -190,6 +201,7 @@ test("collectMcpTools merges parent options into inputSchema", () => {
   expect(schema.required).toContain("path");
 });
 
+/** Tests that collectMcpTools includes outputSchema when set on leaf. */
 test("collectMcpTools includes outputSchema when set on leaf", () => {
   const root = testProgram({
     key: "app",
@@ -218,12 +230,14 @@ test("collectMcpTools includes outputSchema when set on leaf", () => {
   });
 });
 
+/** Tests that collectMcpTools omits outputSchema when leaf has none. */
 test("collectMcpTools omits outputSchema when leaf has none", () => {
   const tools = collectMcpTools(nestedMcpFixture);
   const lookup = tools.find((t) => t.name === "stat_owner_lookup")!;
   expect(lookup.outputSchema).toBeUndefined();
 });
 
+/** McpToolCallToArgv builds nested lookup argv. */
 test("mcpToolCallToArgv builds nested lookup argv", () => {
   const tools = collectMcpTools(nestedMcpFixture);
   const lookup = tools.find((t) => t.name === "stat_owner_lookup")!;
@@ -235,6 +249,7 @@ test("mcpToolCallToArgv builds nested lookup argv", () => {
   expect(argv).toEqual(["stat", "owner", "lookup", "--json", "--user-name", "alice", "./x"]);
 });
 
+/** McpToolCallToArgv expands varargs positionals. */
 test("mcpToolCallToArgv expands varargs positionals", () => {
   const tools = collectMcpTools(nestedMcpFixture);
   const read = tools.find((t) => t.name === "read")!;
@@ -242,6 +257,7 @@ test("mcpToolCallToArgv expands varargs positionals", () => {
   expect(argv).toEqual(["read", "a", "b"]);
 });
 
+/** Tests that reserved command name configure is rejected. */
 test("reserved command name configure is rejected", () => {
   const root = testProgram({
     key: "app",
@@ -257,6 +273,7 @@ test("reserved command name configure is rejected", () => {
   expect(() => cliValidateProgram(root)).toThrow(/Reserved command name: configure/);
 });
 
+/** Tests that top-level command name mcp is allowed without mcpServer. */
 test("top-level command name mcp is allowed without mcpServer", () => {
   const root = testProgram({
     key: "app",
@@ -272,6 +289,7 @@ test("top-level command name mcp is allowed without mcpServer", () => {
   expect(() => cliValidateProgram(root)).not.toThrow();
 });
 
+/** Tests that top-level command name mcp is rejected when mcpServer is enabled. */
 test("top-level command name mcp is rejected when mcpServer is enabled", () => {
   const root = testProgram({
     key: "app",
@@ -288,6 +306,7 @@ test("top-level command name mcp is rejected when mcpServer is enabled", () => {
   expect(() => cliValidateProgram(root)).toThrow(/Reserved command name: mcp/);
 });
 
+/** McpServer on non-root node is rejected. */
 test("mcpServer on non-root node is rejected", () => {
   const root = {
     key: "app",
@@ -305,6 +324,7 @@ test("mcpServer on non-root node is rejected", () => {
   expect(() => cliValidateProgram(root)).toThrow(/mcpServer is only supported on the program root/);
 });
 
+/** McpTool on root is rejected. */
 test("mcpTool on root is rejected", () => {
   const root = testProgram({
     key: "app",
@@ -315,6 +335,7 @@ test("mcpTool on root is rejected", () => {
   expect(() => cliValidateProgram(root)).toThrow(/mcpTool is only supported on leaf commands/);
 });
 
+/** McpTool on routing node is rejected. */
 test("mcpTool on routing node is rejected", () => {
   const root = testProgram({
     key: "app",
@@ -337,6 +358,7 @@ test("mcpTool on routing node is rejected", () => {
   expect(() => cliValidateProgram(root)).toThrow(/mcpTool is only supported on leaf commands/);
 });
 
+/** BuildToolCallSuccess returns stdout only. */
 test("buildToolCallSuccess returns stdout only", () => {
   const result = buildToolCallSuccess("hello\n", "");
   expect(result.isError).toBe(false);
@@ -344,6 +366,7 @@ test("buildToolCallSuccess returns stdout only", () => {
   expect(result.structuredContent).toBeUndefined();
 });
 
+/** BuildToolCallSuccess adds stderr as second content block. */
 test("buildToolCallSuccess adds stderr as second content block", () => {
   const result = buildToolCallSuccess("out\n", "warn\n");
   expect(result.content).toEqual([
@@ -353,6 +376,7 @@ test("buildToolCallSuccess adds stderr as second content block", () => {
   expect(result.structuredContent).toBeUndefined();
 });
 
+/** BuildToolCallSuccess stderr-only still includes stdout slot. */
 test("buildToolCallSuccess stderr-only still includes stdout slot", () => {
   const result = buildToolCallSuccess("", "warn\n");
   expect(result.content).toEqual([
@@ -361,22 +385,26 @@ test("buildToolCallSuccess stderr-only still includes stdout slot", () => {
   ]);
 });
 
+/** BuildToolCallSuccess parses JSON structuredContent. */
 test("buildToolCallSuccess parses JSON structuredContent", () => {
   const result = buildToolCallSuccess('{"a":1}\n', "");
   expect(result.structuredContent).toEqual({ a: 1 });
   expect(result.content[0]?.text).toBe('{"a":1}\n');
 });
 
+/** BuildToolCallSuccess skips structuredContent for plain text. */
 test("buildToolCallSuccess skips structuredContent for plain text", () => {
   const result = buildToolCallSuccess("lookup user=x\n", "");
   expect(result.structuredContent).toBeUndefined();
 });
 
+/** BuildToolCallSuccess parses JSON primitives. */
 test("buildToolCallSuccess parses JSON primitives", () => {
   const result = buildToolCallSuccess("true\n", "");
   expect(result.structuredContent).toBe(true);
 });
 
+/** MCP initialize returns tools and resources capabilities. */
 test("MCP initialize returns tools and resources capabilities", async () => {
   const responses = await mcpRequest([{ jsonrpc: "2.0", id: 1, method: "initialize", params: {} }]);
   const res = responses.get(1) as { result: { capabilities: Record<string, unknown> } };
@@ -384,6 +412,7 @@ test("MCP initialize returns tools and resources capabilities", async () => {
   expect(res.result.capabilities.resources).toBeDefined();
 });
 
+/** MCP tools/list includes stat_owner_lookup. */
 test("MCP tools/list includes stat_owner_lookup", async () => {
   const responses = await mcpRequest([{ jsonrpc: "2.0", id: 2, method: "tools/list", params: {} }]);
   const res = responses.get(2) as {
@@ -394,6 +423,7 @@ test("MCP tools/list includes stat_owner_lookup", async () => {
   expect(lookup?.inputSchema.required).toContain("path");
 });
 
+/** MCP resources/read returns schema JSON. */
 test("MCP resources/read returns schema JSON", async () => {
   const responses = await mcpRequest([
     { jsonrpc: "2.0", id: 3, method: "resources/read", params: { uri: "nested_ts://schema" } },
@@ -403,6 +433,7 @@ test("MCP resources/read returns schema JSON", async () => {
   expect(schema.key).toBe("nested.ts");
 });
 
+/** MCP tools/call runs stat_owner_lookup. */
 test("MCP tools/call runs stat_owner_lookup", async () => {
   const readme = join(import.meta.dir, "..", "README.md");
   const responses = await mcpRequest([
@@ -421,6 +452,7 @@ test("MCP tools/call runs stat_owner_lookup", async () => {
   expect(res.result.content[0]?.text).toContain("lookup user=test");
 });
 
+/** MCP tools/call returns structuredContent for JSON stdout. */
 test("MCP tools/call returns structuredContent for JSON stdout", async () => {
   const readme = join(import.meta.dir, "..", "README.md");
   const responses = await mcpRequest([
@@ -446,6 +478,7 @@ test("MCP tools/call returns structuredContent for JSON stdout", async () => {
   expect(JSON.parse(res.result.content[0]?.text.trim())).toEqual({ user: "test", path: readme });
 });
 
+/** MCP tools/call errors on missing required positional. */
 test("MCP tools/call errors on missing required positional", async () => {
   const responses = await mcpRequest([
     {
@@ -460,18 +493,21 @@ test("MCP tools/call errors on missing required positional", async () => {
   expect(res.result.content[0]?.text).toContain("Missing argument: path");
 });
 
+/** MCP ping returns empty result. */
 test("MCP ping returns empty result", async () => {
   const responses = await mcpRequest([{ jsonrpc: "2.0", id: 99, method: "ping", params: {} }]);
   const res = responses.get(99) as { result: Record<string, never> };
   expect(res.result).toEqual({});
 });
 
+/** Tests that minimal.ts mcp without opt-in fails. */
 test("minimal.ts mcp without opt-in fails", async () => {
   const { stderr, exitCode } = await $`bun run examples/minimal.ts mcp`.nothrow().quiet();
   expect(exitCode).toBe(1);
   expect(stderr.toString()).toContain("MCP is not available");
 });
 
+/** MCP resources/list includes custom resource. */
 test("MCP resources/list includes custom resource", async () => {
   const responses = await mcpRequest(
     [{ jsonrpc: "2.0", id: 10, method: "resources/list", params: {} }],
@@ -484,6 +520,7 @@ test("MCP resources/list includes custom resource", async () => {
   expect(uris).toContain("test://hello");
 });
 
+/** MCP resources/read returns docs topic resource body. */
 test("MCP resources/read returns docs topic resource body", async () => {
   const responses = await mcpRequest(
     [
@@ -500,6 +537,7 @@ test("MCP resources/read returns docs topic resource body", async () => {
   expect(res.result.contents[0]?.text).toBe("# MCP test readme\n");
 });
 
+/** MCP resources/read returns custom resource body. */
 test("MCP resources/read returns custom resource body", async () => {
   const responses = await mcpRequest(
     [{ jsonrpc: "2.0", id: 11, method: "resources/read", params: { uri: "test://hello" } }],
@@ -509,6 +547,7 @@ test("MCP resources/read returns custom resource body", async () => {
   expect(res.result.contents[0]?.text).toBe("hello resource");
 });
 
+/** MCP resources/read unknown URI returns error. */
 test("MCP resources/read unknown URI returns error", async () => {
   const responses = await mcpRequest(
     [{ jsonrpc: "2.0", id: 12, method: "resources/read", params: { uri: "missing://nope" } }],