argsbarg 3.4.1 → 3.5.0

package/src/parse.ts

@@ -7,12 +7,11 @@ It keeps handler dispatch and help on one parser so the CLI behavior stays consi
 across every entry path.
 */
 
-import { CliContext } from "./context.ts";
 import {
-  type CliLeaf,
-  CliNode,
   CliFallbackMode,
-  CliOption,
+  type CliLeaf,
+  type CliNode,
+  type CliOption,
   CliOptionKind,
   isCliLeaf,
   isCliRouter,
@@ -191,17 +190,30 @@ function consumeOptions(
 
     if (tok === "--") {
       idx += 1;
-      return { report: { err: null, stoppedOnUnknown: false, sawDoubleDash: true }, nextIndex: idx };
+      return {
+        report: { err: null, stoppedOnUnknown: false, sawDoubleDash: true },
+        nextIndex: idx,
+      };
     }
 
     if (tok.startsWith("--")) {
       const err = consumeLong(tok);
-      if (err === "") return { report: { err: null, stoppedOnUnknown: true, sawDoubleDash: false }, nextIndex: idx };
-      if (err) return { report: { err, stoppedOnUnknown: false, sawDoubleDash: false }, nextIndex: idx };
+      if (err === "")
+        return {
+          report: { err: null, stoppedOnUnknown: true, sawDoubleDash: false },
+          nextIndex: idx,
+        };
+      if (err)
+        return { report: { err, stoppedOnUnknown: false, sawDoubleDash: false }, nextIndex: idx };
     } else {
       const err = consumeShort(tok);
-      if (err === "") return { report: { err: null, stoppedOnUnknown: true, sawDoubleDash: false }, nextIndex: idx };
-      if (err) return { report: { err, stoppedOnUnknown: false, sawDoubleDash: false }, nextIndex: idx };
+      if (err === "")
+        return {
+          report: { err: null, stoppedOnUnknown: true, sawDoubleDash: false },
+          nextIndex: idx,
+        };
+      if (err)
+        return { report: { err, stoppedOnUnknown: false, sawDoubleDash: false }, nextIndex: idx };
     }
   }
 
@@ -212,7 +224,7 @@ function consumeOptions(
 
 /** Merges option defs from the program root along the routed command path. */
 export function collectOptionDefs(root: CliNode, path: string[]): CliOption[] {
-  let defs = [...(root.options ?? [])];
+  const defs = [...(root.options ?? [])];
   let node: CliNode = root;
 
   for (const seg of path) {
@@ -343,7 +355,16 @@ function finishLeaf(
     }
   }
 
-  return { kind: ParseKind.Ok, path, opts, args, helpExplicit: false, helpPath: [], errorMsg: "", errorHelpPath: [] };
+  return {
+    kind: ParseKind.Ok,
+    path,
+    opts,
+    args,
+    helpExplicit: false,
+    helpPath: [],
+    errorMsg: "",
+    errorHelpPath: [],
+  };
 }
 
 // ── Main Parser ───────────────────────────────────────────────────────────────
@@ -414,7 +435,16 @@ export function parse(root: CliNode, argv: string[]): ParseResult {
       cmdName = root.fallbackCommand;
       node = findChild(root.commands, cmdName);
       if (!node) {
-        return { kind: ParseKind.Error, path: [], opts: {}, args: [], helpExplicit: false, helpPath: [], errorMsg: `Unknown command: ${cmdName}`, errorHelpPath: path };
+        return {
+          kind: ParseKind.Error,
+          path: [],
+          opts: {},
+          args: [],
+          helpExplicit: false,
+          helpPath: [],
+          errorMsg: `Unknown command: ${cmdName}`,
+          errorHelpPath: path,
+        };
       }
     } else {
       return helpResult([], false);
@@ -428,16 +458,26 @@ export function parse(root: CliNode, argv: string[]): ParseResult {
       i += 1;
       node = childPick;
     } else {
+      const fallbackCommand = root.fallbackCommand;
       const canRouteUnknown =
-        root.fallbackCommand !== undefined &&
+        fallbackCommand !== undefined &&
         ((root.fallbackMode ?? CliFallbackMode.MissingOnly) === CliFallbackMode.MissingOrUnknown ||
           (root.fallbackMode ?? CliFallbackMode.MissingOnly) === CliFallbackMode.UnknownOnly);
 
       if (canRouteUnknown) {
-        cmdName = root.fallbackCommand!;
+        cmdName = fallbackCommand;
         node = findChild(root.commands, cmdName);
         if (!node) {
-          return { kind: ParseKind.Error, path: [], opts: {}, args: [], helpExplicit: false, helpPath: [], errorMsg: `Unknown command: ${cmdName}`, errorHelpPath: path };
+          return {
+            kind: ParseKind.Error,
+            path: [],
+            opts: {},
+            args: [],
+            helpExplicit: false,
+            helpPath: [],
+            errorMsg: `Unknown command: ${cmdName}`,
+            errorHelpPath: path,
+          };
         }
       } else {
         cmdName = peek;
@@ -451,7 +491,9 @@ export function parse(root: CliNode, argv: string[]): ParseResult {
             args: [],
             helpExplicit: false,
             helpPath: [],
-            errorMsg: forcePositionals ? `Expected subcommand but got positional: ${cmdName}` : `Unknown command: ${cmdName}`,
+            errorMsg: forcePositionals
+              ? `Expected subcommand but got positional: ${cmdName}`
+              : `Unknown command: ${cmdName}`,
             errorHelpPath: path,
           };
         }
@@ -460,7 +502,19 @@ export function parse(root: CliNode, argv: string[]): ParseResult {
   }
 
   path.push(cmdName);
-  let current = node!;
+  if (!node) {
+    return {
+      kind: ParseKind.Error,
+      path,
+      opts: {},
+      args: [],
+      helpExplicit: false,
+      helpPath: [],
+      errorMsg: `Unknown command: ${cmdName}`,
+      errorHelpPath: path,
+    };
+  }
+  let current = node;
 
   // Walk the command tree
   while (true) {
@@ -508,7 +562,15 @@ export function parse(root: CliNode, argv: string[]): ParseResult {
       if (!isCliLeaf(current)) {
         return helpResult(path, false);
       }
-      return finishLeaf(current, i, argv, path, opts, collectOptionDefs(root, path), forcePositionals);
+      return finishLeaf(
+        current,
+        i,
+        argv,
+        path,
+        opts,
+        collectOptionDefs(root, path),
+        forcePositionals,
+      );
     }
 
     const tok = argv[i];
@@ -542,10 +604,10 @@ export function parse(root: CliNode, argv: string[]): ParseResult {
         fb !== undefined &&
         (fm === CliFallbackMode.MissingOrUnknown || fm === CliFallbackMode.UnknownOnly);
 
-      if (canRouteUnknown) {
-        const fbNode = findChild(current.commands, fb!);
+      if (canRouteUnknown && fb !== undefined) {
+        const fbNode = findChild(current.commands, fb);
         if (fbNode) {
-          path.push(fb!);
+          path.push(fb);
           current = fbNode;
           continue;
         }
@@ -558,7 +620,9 @@ export function parse(root: CliNode, argv: string[]): ParseResult {
         args: [],
         helpExplicit: false,
         helpPath: [],
-        errorMsg: forcePositionals ? `Expected subcommand but got positional: ${tok}` : `Unknown subcommand: ${tok}`,
+        errorMsg: forcePositionals
+          ? `Expected subcommand but got positional: ${tok}`
+          : `Unknown subcommand: ${tok}`,
         errorHelpPath: path,
       };
     }
@@ -566,7 +630,15 @@ export function parse(root: CliNode, argv: string[]): ParseResult {
     if (!isCliLeaf(current)) {
       return helpResult(path, false);
     }
-    return finishLeaf(current, i, argv, path, opts, collectOptionDefs(root, path), forcePositionals);
+    return finishLeaf(
+      current,
+      i,
+      argv,
+      path,
+      opts,
+      collectOptionDefs(root, path),
+      forcePositionals,
+    );
   }
 }
 
@@ -578,7 +650,7 @@ export function parse(root: CliNode, argv: string[]): ParseResult {
 export function postParseValidate(root: CliNode, pr: ParseResult): ParseResult {
   if (pr.kind !== ParseKind.Ok) return pr;
 
-  let defs = [...(root.options ?? [])];
+  const defs = [...(root.options ?? [])];
   let node: CliNode = root;
 
   for (const seg of pr.path) {

package/src/runtime.ts

@@ -2,26 +2,29 @@
 This module runs parsed commands, help, errors, completion, and leaf handlers.
 */
 
-import { resolveCapabilities } from "./capabilities.ts";
 import { builtinInterceptRoot, dispatchBuiltin } from "./builtins/dispatch.ts";
 import { cliParseRoot, cliPresentationRoot } from "./builtins/presentation.ts";
-import type { CliRouter } from "./types.ts";
-import { type CliNode, type CliProgram, isCliLeaf, isCliRouter } from "./types.ts";
+import { resolveCapabilities } from "./capabilities.ts";
 import { CliContext } from "./context.ts";
 import { cliHelpRender } from "./help.ts";
-import { parse, postParseValidate, ParseKind } from "./parse.ts";
+import { ParseKind, parse, postParseValidate } from "./parse.ts";
+import type { CliRouter } from "./types.ts";
+import { type CliNode, type CliProgram, isCliLeaf, isCliRouter } from "./types.ts";
 import { cliValidateProgram } from "./validate.ts";
 
 function cliRootMergedWithBuiltins(program: CliProgram): CliRouter {
   return cliParseRoot(program);
 }
 
-export async function cliRun(program: CliProgram, argv: string[] = process.argv.slice(2)): Promise<never> {
+export async function cliRun(
+  program: CliProgram,
+  argv: string[] = process.argv.slice(2),
+): Promise<never> {
   try {
     cliValidateProgram(program);
   } catch (err) {
     if (err instanceof Error) {
-      process.stderr.write(err.message + "\n");
+      process.stderr.write(`${err.message}\n`);
     } else {
       process.stderr.write("Invalid CLI definition.\n");
     }
@@ -31,12 +34,16 @@ export async function cliRun(program: CliProgram, argv: string[] = process.argv.
   const caps = resolveCapabilities(program);
 
   if (argv.length >= 1 && argv[0] === "mcp" && !caps.mcp) {
-    process.stderr.write("MCP is not enabled. Set mcpServer: { enabled: true } on the program root.\n");
+    process.stderr.write(
+      "MCP is not enabled. Set mcpServer: { enabled: true } on the program root.\n",
+    );
     process.exit(1);
   }
 
   if (argv.length >= 1 && argv[0] === "install" && !caps.install) {
-    process.stderr.write("install is disabled. Remove install.enabled: false from the program root.\n");
+    process.stderr.write(
+      "install is disabled. Remove install.enabled: false from the program root.\n",
+    );
     process.exit(1);
   }
 
@@ -75,13 +82,16 @@ export async function cliRun(program: CliProgram, argv: string[] = process.argv.
   if (pr.kind === "error") {
     const color = process.stderr.isTTY;
     const msg = color ? `\u001B[31m${pr.errorMsg}\u001B[0m` : pr.errorMsg;
-    process.stderr.write(msg + "\n");
+    process.stderr.write(`${msg}\n`);
     process.stderr.write(cliHelpRender(cliPresentationRoot(program), pr.errorHelpPath, true));
     process.exit(1);
   }
 
   if (pr.kind === ParseKind.Ok) {
-    await dispatchBuiltin(program, pr, { isLeafCompletionIntercept, parseRoot: completionParseRoot });
+    await dispatchBuiltin(program, pr, {
+      isLeafCompletionIntercept,
+      parseRoot: completionParseRoot,
+    });
   }
 
   let current: CliNode = parseRoot;
@@ -109,7 +119,7 @@ export async function cliRun(program: CliProgram, argv: string[] = process.argv.
     process.exit(0);
   } catch (err) {
     if (err instanceof Error) {
-      process.stderr.write(err.message + "\n");
+      process.stderr.write(`${err.message}\n`);
     }
     process.exit(1);
   }
@@ -118,7 +128,7 @@ export async function cliRun(program: CliProgram, argv: string[] = process.argv.
 export function cliErrWithHelp(ctx: CliContext, msg: string): never {
   const color = process.stderr.isTTY;
   const line = color ? `\u001B[31m${msg}\u001B[0m` : msg;
-  process.stderr.write(line + "\n");
+  process.stderr.write(`${line}\n`);
   process.stderr.write(cliHelpRender(cliPresentationRoot(ctx.program), ctx.commandPath, true));
   process.exit(1);
 }

package/src/schema.ts

@@ -2,10 +2,16 @@
 This module serializes the CLI schema tree to JSON for machine-readable introspection.
 */
 
-import { type CliNode, type CliProgram, isCliLeaf, isCliRouter, leafOutputSchema } from "./types.ts";
-import { exportPresentationBuiltins, type CliSchemaExport } from "./builtins/export.ts";
+import { type CliSchemaExport, exportPresentationBuiltins } from "./builtins/export.ts";
 import { cliResolveNotes } from "./help.ts";
 import { visibleOptions } from "./hidden.ts";
+import {
+  type CliNode,
+  type CliProgram,
+  isCliLeaf,
+  isCliRouter,
+  leafOutputSchema,
+} from "./types.ts";
 
 const RESERVED = new Set(["completion", "install", "docs", "mcp", "version"]);
 
@@ -60,8 +66,8 @@ function exportCommand(cmd: CliNode, root: CliProgram): CliSchemaExport | null {
 /** Resolves `{argsbarg:program}` in exported notes using the root program key. */
 function resolveSchemaNotes(node: CliSchemaExport, appKey: string): CliSchemaExport {
   const out: CliSchemaExport = { ...node };
-  if ((out.notes ?? "").length > 0) {
-    out.notes = cliResolveNotes(out.notes!, appKey);
+  if ((out.notes ?? "").length > 0 && out.notes !== undefined) {
+    out.notes = cliResolveNotes(out.notes, appKey);
   }
   if (out.commands) {
     out.commands = out.commands.map((ch) => resolveSchemaNotes(ch, appKey));
@@ -83,7 +89,7 @@ export function cliSchemaExport(root: CliProgram): CliSchemaExport {
 }
 
 export function cliSchemaJson(root: CliProgram): string {
-  return JSON.stringify(cliSchemaExport(root), null, 2) + "\n";
+  return `${JSON.stringify(cliSchemaExport(root), null, 2)}\n`;
 }
 
 export type { CliSchemaExport };

package/src/skill/generate.ts

@@ -3,9 +3,9 @@ This module generates Agent Skills content (SKILL.md + reference.md) from a CLI
 */
 
 import { generateApiGuide } from "../docs/api-guide.ts";
+import { collectMcpTools, type McpToolDef, sanitizeToolSegment } from "../mcp/tools.ts";
 import { collectOptionDefs } from "../parse.ts";
-import { collectMcpTools, sanitizeToolSegment, type McpToolDef } from "../mcp/tools.ts";
-import { CliProgram, CliOptionKind } from "../types.ts";
+import { CliOptionKind, type CliProgram } from "../types.ts";
 
 export type SkillTarget = "cursor" | "claude";
 
@@ -18,7 +18,7 @@ export interface SkillBundle {
 /** Truncates text to maxLen with ellipsis. */
 function truncate(text: string, maxLen: number): string {
   if (text.length <= maxLen) return text;
-  return text.slice(0, maxLen - 1) + "…";
+  return `${text.slice(0, maxLen - 1)}…`;
 }
 
 /** Builds third-person skill description for YAML frontmatter. */
@@ -54,7 +54,7 @@ function formatCommandEntry(root: CliProgram, tool: McpToolDef): string {
   }
   const enums = opts.filter((o) => o.kind === CliOptionKind.Enum && o.choices?.length);
   for (const e of enums) {
-    line += ` (\`--${e.name}\`: ${e.choices!.join(" | ")})`;
+    line += ` (\`--${e.name}\`: ${e.choices?.join(" | ")})`;
   }
   const varargs = (tool.leaf.positionals ?? []).filter((p) => (p.argMax ?? 1) === 0);
   if (varargs.length > 0) {

package/src/skill/install.ts

@@ -1,7 +1,7 @@
 import { existsSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
-import { CliProgram } from "../types.ts";
+import type { CliProgram } from "../types.ts";
 import { generateSkillBundle, type SkillTarget } from "./generate.ts";
 import { applySkillInstallHints } from "./hint.ts";
 
@@ -25,7 +25,11 @@ 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[] {
+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);

package/src/validate.ts

@@ -3,17 +3,17 @@ This module validates CLI schemas before execution.
 */
 
 import { reservedCommandNames, resolveCapabilities } from "./capabilities.ts";
+import { DOCS_BUILTIN_TOPIC_KEYS } from "./docs/resolve.ts";
+import { resolveMcpSchemaUri } from "./mcp/tools.ts";
 import {
   type CliLeaf,
   type CliNode,
-  type CliProgram,
   CliOptionKind,
+  type CliProgram,
   CliSchemaValidationError,
   isCliLeaf,
   isCliRouter,
 } from "./types.ts";
-import { resolveMcpSchemaUri } from "./mcp/tools.ts";
-import { DOCS_BUILTIN_TOPIC_KEYS } from "./docs/resolve.ts";
 
 /** Validates `docs` configuration on the program root. */
 function validateDocsConfig(docs: import("./types.ts").CliDocsConfig): void {
@@ -93,17 +93,17 @@ function walkNode(node: CliNode, program: CliProgram, isRoot: boolean): void {
     const rogue = node as CliProgram;
     if (rogue.mcpServer !== undefined) {
       throw new CliSchemaValidationError(
-        "mcpServer is only supported on the program root (not on " + node.key + ")",
+        `mcpServer is only supported on the program root (not on ${node.key})`,
       );
     }
     if (rogue.install !== undefined) {
       throw new CliSchemaValidationError(
-        "install is only supported on the program root (not on " + node.key + ")",
+        `install is only supported on the program root (not on ${node.key})`,
       );
     }
     if (rogue.docs !== undefined) {
       throw new CliSchemaValidationError(
-        "docs is only supported on the program root (not on " + node.key + ")",
+        `docs is only supported on the program root (not on ${node.key})`,
       );
     }
   }
@@ -115,9 +115,7 @@ function walkNode(node: CliNode, program: CliProgram, isRoot: boolean): void {
     const outputSchema = node.outputSchema;
     const legacyOutputSchema = node.mcpTool?.outputSchema;
     if (outputSchema !== undefined && legacyOutputSchema !== undefined) {
-      throw new CliSchemaValidationError(
-        "Set outputSchema on the leaf only, not under mcpTool",
-      );
+      throw new CliSchemaValidationError("Set outputSchema on the leaf only, not under mcpTool");
     }
     const resolved = outputSchema ?? legacyOutputSchema;
     if (
@@ -132,7 +130,7 @@ function walkNode(node: CliNode, program: CliProgram, isRoot: boolean): void {
     const rogue = node as unknown as CliLeaf;
     if (rogue.mcpTool !== undefined) {
       throw new CliSchemaValidationError(
-        "mcpTool is only supported on leaf commands (not on " + node.key + ")",
+        `mcpTool is only supported on leaf commands (not on ${node.key})`,
       );
     }
   }
@@ -160,9 +158,7 @@ function walkNode(node: CliNode, program: CliProgram, isRoot: boolean): void {
     }
 
     if (node.fallbackMode !== undefined && node.fallbackCommand === undefined) {
-      throw new CliSchemaValidationError(
-        `fallbackMode requires fallbackCommand on '${node.key}'`,
-      );
+      throw new CliSchemaValidationError(`fallbackMode requires fallbackCommand on '${node.key}'`);
     }
 
     if (node.fallbackCommand !== undefined) {
@@ -233,10 +229,15 @@ function validateOptions(scopeKey: string, options: import("./types.ts").CliOpti
   }
 }
 
-function validatePositionals(scopeKey: string, positionals: import("./types.ts").CliPositional[]): void {
+function validatePositionals(
+  scopeKey: string,
+  positionals: import("./types.ts").CliPositional[],
+): void {
   for (const p of positionals) {
     if (p.argMin !== undefined && p.argMin < 0) {
-      throw new CliSchemaValidationError(`argMin must be >= 0 for positional ${scopeKey}/${p.name}`);
+      throw new CliSchemaValidationError(
+        `argMin must be >= 0 for positional ${scopeKey}/${p.name}`,
+      );
     }
     if (p.argMax !== undefined && p.argMax < 0) {
       throw new CliSchemaValidationError(
@@ -262,7 +263,11 @@ function validatePositionals(scopeKey: string, positionals: import("./types.ts")
   }
 
   for (let idx = 0; idx < positionals.length; idx++) {
-    const { argMax = 1 } = positionals[idx]!;
+    const positional = positionals[idx];
+    if (!positional) {
+      continue;
+    }
+    const { argMax = 1 } = positional;
     if (argMax === 0 && idx + 1 < positionals.length) {
       throw new CliSchemaValidationError(
         `Unlimited positional (argMax == 0) must be last in scope ${scopeKey}`,