argsbarg 1.4.3 → 2.0.0

package/src/builtins/presentation.ts

@@ -0,0 +1,50 @@
+import type { CliCapabilities } from "../capabilities.ts";
+import { resolveCapabilities } from "../capabilities.ts";
+import type { CliLeaf, CliNode, CliProgram, CliRouter } from "../types.ts";
+import { isCliLeaf, isCliRouter } from "../types.ts";
+import { cliBuiltinCompletionGroup } from "./completion-group.ts";
+import { cliBuiltinInstallCommand } from "./install.ts";
+import { cliBuiltinMcpCommand } from "./mcp.ts";
+
+/** Built-in command nodes injected for help, schema, and completions. */
+export function presentationBuiltins(program: CliProgram, caps: CliCapabilities): CliNode[] {
+  const builtins: CliNode[] = [cliBuiltinCompletionGroup(program.key)];
+  if (caps.install) {
+    builtins.push(cliBuiltinInstallCommand(program));
+  }
+  if (caps.mcp) {
+    builtins.push(cliBuiltinMcpCommand());
+  }
+  return builtins;
+}
+
+/**
+ * Returns a schema suitable for help display, including capability-built-in subtrees.
+ * Routing programs get builtins merged; leaf programs are wrapped as a tiny router.
+ */
+export function cliPresentationRoot(program: CliProgram): CliRouter {
+  const caps = resolveCapabilities(program);
+  const builtins = presentationBuiltins(program, caps);
+
+  if (isCliLeaf(program)) {
+    return {
+      key: program.key,
+      description: program.description,
+      options: program.options,
+      commands: builtins,
+    };
+  }
+
+  return {
+    key: program.key,
+    description: program.description,
+    notes: program.notes,
+    options: program.options,
+    fallbackCommand: program.fallbackCommand,
+    fallbackMode: program.fallbackMode,
+    commands: [...program.commands, ...builtins],
+  };
+}
+
+/** Presentation tree may include builtin leaf stubs. */
+export type CliPresentationNode = CliNode | CliLeaf;

package/src/builtins/scopes.ts

@@ -0,0 +1,46 @@
+/*
+Shared completion scope walk used by bash, zsh, and fish emitters.
+*/
+
+import { type CliNode, type CliRouter, isCliLeaf, isCliRouter } from "../types.ts";
+
+/** One tab-completion scope: child commands, options, and path key for the schema walk. */
+export interface ScopeRec {
+  kids: CliNode[];
+  opts: import("../types.ts").CliOption[];
+  path: string;
+  wantsFiles: boolean;
+}
+
+function hasPositionalArguments(cmd: CliNode): boolean {
+  return isCliLeaf(cmd) && (cmd.positionals ?? []).length > 0;
+}
+
+function walkScopes(cmdPath: string, cmd: CliNode, acc: ScopeRec[]): void {
+  const kids = isCliRouter(cmd) ? cmd.commands : [];
+  acc.push({
+    kids,
+    opts: cmd.options ?? [],
+    path: cmdPath,
+    wantsFiles: hasPositionalArguments(cmd),
+  });
+  for (const ch of kids) {
+    const nextPath = cmdPath === "" ? ch.key : cmdPath + "/" + ch.key;
+    walkScopes(nextPath, ch, acc);
+  }
+}
+
+/** Flattens the schema into a list of completion scopes (root + every command path). */
+export function collectScopes(schema: CliRouter): ScopeRec[] {
+  const acc: ScopeRec[] = [];
+  acc.push({
+    kids: schema.commands ?? [],
+    opts: schema.options ?? [],
+    path: "",
+    wantsFiles: false,
+  });
+  for (const c of schema.commands ?? []) {
+    walkScopes(c.key, c, acc);
+  }
+  return acc;
+}

package/src/builtins/shell-helpers.ts

@@ -0,0 +1,24 @@
+/** Produces a shell-safe identifier from the app or command name (alnum → `_`). */
+export function identToken(s: string): string {
+  return s.replace(/[^a-zA-Z0-9]/g, "_");
+}
+
+/** Escapes a string for use inside single quotes in generated shell scripts. */
+export function escShellSingleQuoted(s: string): string {
+  return s.replace(/'/g, "'\\''");
+}
+
+/** Escapes a string for use inside fish single-quoted strings. */
+export function escFishSingleQuoted(s: string): string {
+  return s.replace(/\\/g, "\\\\").replace(/'/g, "\\'");
+}
+
+/** Sanitizes the app key for generated shell function names (non-alnum removed). */
+export function mainName(schemaName: string): string {
+  return schemaName.replace(/[^a-zA-Z0-9]/g, "_");
+}
+
+export const kHelpLong = "--help";
+export const kHelpShort = "-h";
+export const kSchemaLong = "--schema";
+export const kSchemaDesc = "Print the full command tree as JSON.";

package/src/capabilities.ts

@@ -0,0 +1,32 @@
+/*
+Internal capability resolver — decides which platform builtins are active for a program.
+Not exported from the public package barrel.
+*/
+
+import type { CliProgram } from "./types.ts";
+import { isCompiledExecutable } from "./install/compiled.ts";
+
+/** Platform builtins derived from program config and runtime. */
+export interface CliCapabilities {
+  completion: true;
+  mcp: boolean;
+  install: boolean;
+}
+
+/** Resolves which capabilities are enabled for a program. */
+export function resolveCapabilities(program: CliProgram): CliCapabilities {
+  return {
+    completion: true,
+    mcp: program.mcpServer !== undefined,
+    install: isCompiledExecutable() && program.install?.enabled !== false,
+  };
+}
+
+/** Reserved top-level command names for the given capabilities. */
+export function reservedCommandNames(caps: CliCapabilities): string[] {
+  const names = ["completion", "install"];
+  if (caps.mcp) {
+    names.push("mcp");
+  }
+  return names;
+}