argsbarg 6.1.1 → 6.1.3

package/src/{invoke.test.ts → runtime/invoke.test.ts}

@@ -5,16 +5,16 @@ Domain-specific regression tests (split from index.test.ts).
 import { expect, test } from "bun:test";
 import { join } from "node:path";
 import { $ } from "bun";
-import { Cli, type CliContext, CliOptionKind } from "./index.ts";
-import { ParseKind, parse, postParseValidate } from "./parse.ts";
-import { testProgram, varargsReadFixture } from "./test-fixtures.ts";
-import type { CliLeaf } from "./types.ts";
-import { isCliRouter } from "./types.ts";
-import { cliValidateProgram } from "./validate.ts";
+import { ParseKind, parse, postParseValidate } from "~/core/parse.ts";
+import type { CliLeaf } from "~/core/types.ts";
+import { isCliRouter } from "~/core/types.ts";
+import { cliValidateProgram } from "~/core/validate.ts";
+import { Cli, type CliContext, CliOptionKind } from "~/index";
+import { testProgram, varargsReadFixture } from "~/test/fixtures.ts";
 
 /** Tests that ctx.invocation is cli via Cli.run. */
 test("ctx.invocation is cli via Cli.run", async () => {
-  const indexPath = join(import.meta.dir, "index.ts");
+  const indexPath = join(import.meta.dir, "../index.ts");
   const { stdout } = await $`bun -e ${`
 import { Cli, CliProgram } from ${JSON.stringify(indexPath)};
 const program = {
@@ -45,6 +45,30 @@ test("ctx.invocation is mcp via Cli.invoke", async () => {
   expect(seen).toBe("mcp");
 });
 
+/** Tests that ctx.locals.requestId is seeded before handler on invoke. */
+test("Cli.invoke seeds ctx.locals.requestId", async () => {
+  let requestId = "";
+  const root = testProgram({
+    key: "app",
+    description: "",
+    hooks: {
+      beforeInvoke: (ctx: CliContext) => {
+        requestId = String(ctx.locals.requestId ?? "");
+      },
+    },
+    handler: () => {},
+  });
+  cliValidateProgram(root);
+  const wireId = "00000000-0000-4000-8000-000000000001";
+  const result = await new Cli(root).invoke([], {
+    invocation: "http",
+    requestId: wireId,
+    http: { request: new Request("http://localhost/"), clientIp: "127.0.0.1", requestId: wireId },
+  });
+  expect(result.kind).toBe("ok");
+  expect(requestId).toBe(wireId);
+});
+
 /** Cli.invoke rejects invalid Enum value. */
 test("Cli.invoke rejects invalid Enum value", async () => {
   const root = testProgram({

package/src/server/context.ts

@@ -0,0 +1,25 @@
+/*
+Per-server mutable handle context passed through HTTP/MCP dispatch.
+*/
+
+import type { CliHttpWireHooks, CliMcpWireHooks, ServerRuntime, ServerState } from "~/core/types.ts";
+import type { LogEmitter } from "~/log/emitter.ts";
+import type { ResolvedHttpServeConfig, ResolvedMcpServeConfig } from "./overrides.ts";
+
+/** Shared server state for one HTTP or MCP serve session. */
+export interface ServerHandleContext {
+  runtime: ServerRuntime;
+  emitter: LogEmitter;
+  http?: ResolvedHttpServeConfig;
+  mcp?: ResolvedMcpServeConfig;
+  httpHooks?: CliHttpWireHooks;
+  mcpHooks?: CliMcpWireHooks;
+}
+
+/** Creates a fresh {@link ServerRuntime} for HTTP or MCP. */
+export function createServerRuntime(
+  program: import("~/core/types.ts").CliProgram,
+  surface: "http" | "mcp",
+): ServerRuntime {
+  return { state: {} as ServerState, program, surface };
+}

package/src/server/overrides.ts

@@ -0,0 +1,112 @@
+/*
+CLI flag and programmatic overrides merged into HTTP/MCP server runtime config.
+*/
+
+import { join } from "node:path";
+import { resolveAppConfigDir } from "~/config/file.ts";
+import type { CliProgram } from "~/core/types.ts";
+import type { ResolvedLogConfig } from "~/log/emitter.ts";
+
+/** Overrides from `myapp http` / `serveHttp()` flags and embedders. */
+export interface ServeOverrides {
+  host?: string;
+  port?: number;
+  trustProxy?: boolean;
+  obscureErrors?: boolean;
+  logFormat?: "json" | "text";
+  logFile?: string;
+  noAccessLog?: boolean;
+  dev?: boolean;
+}
+
+/** Resolved HTTP listen and error options after merging schema + overrides. */
+export interface ResolvedHttpServeConfig {
+  hostname: string;
+  port: number;
+  trustProxy: boolean;
+  obscureUnexpected: boolean;
+  log: ResolvedLogConfig;
+}
+
+/** Resolved MCP serve options after merging schema + overrides. */
+export interface ResolvedMcpServeConfig {
+  obscureUnexpected: boolean;
+  log: ResolvedLogConfig;
+}
+
+function resolveLogFile(program: CliProgram, logFile: string | undefined): string | undefined {
+  if (!logFile) {
+    return undefined;
+  }
+  if (logFile.startsWith("/") || logFile.startsWith("~")) {
+    return logFile;
+  }
+  return join(resolveAppConfigDir(program), logFile);
+}
+
+/** Builds resolved HTTP server config (CLI flags > program schema). */
+export function resolveHttpServeConfig(program: CliProgram, overrides: ServeOverrides = {}): ResolvedHttpServeConfig {
+  const http = program.httpServer;
+  const obscureUnexpected = overrides.obscureErrors ?? http?.errors?.obscureUnexpected ?? false;
+  return {
+    hostname: overrides.host ?? http?.host ?? "127.0.0.1",
+    port: overrides.port ?? http?.port ?? 3000,
+    trustProxy: overrides.trustProxy ?? http?.trustProxy ?? false,
+    obscureUnexpected,
+    log: {
+      format: overrides.logFormat ?? program.log?.format ?? "json",
+      file: resolveLogFile(program, overrides.logFile ?? program.log?.file),
+      access: overrides.noAccessLog ? false : (program.log?.access ?? true),
+      errors: program.log?.errors ?? true,
+      dev: overrides.dev ?? false,
+    },
+  };
+}
+
+/** Builds resolved MCP server config (CLI flags > program schema). */
+export function resolveMcpServeConfig(program: CliProgram, overrides: ServeOverrides = {}): ResolvedMcpServeConfig {
+  const mcp = program.mcpServer;
+  return {
+    obscureUnexpected: overrides.obscureErrors ?? mcp?.errors?.obscureUnexpected ?? false,
+    log: {
+      format: overrides.logFormat ?? program.log?.format ?? "json",
+      file: resolveLogFile(program, overrides.logFile ?? program.log?.file),
+      access: program.log?.access ?? true,
+      errors: program.log?.errors ?? true,
+      dev: overrides.dev ?? false,
+    },
+  };
+}
+
+/** Parses `http` / `mcp serve` CLI opts into {@link ServeOverrides}. */
+export function serveOverridesFromOpts(opts: Record<string, string>, surface: "http" | "mcp"): ServeOverrides {
+  const out: ServeOverrides = {};
+  if (opts.host) {
+    out.host = opts.host;
+  }
+  if (opts.port) {
+    const port = Number(opts.port);
+    if (!Number.isNaN(port)) {
+      out.port = port;
+    }
+  }
+  if (opts["trust-proxy"]) {
+    out.trustProxy = true;
+  }
+  if (opts["obscure-errors"]) {
+    out.obscureErrors = true;
+  }
+  if (opts["log-format"] === "json" || opts["log-format"] === "text") {
+    out.logFormat = opts["log-format"];
+  }
+  if (opts["log-file"]) {
+    out.logFile = opts["log-file"];
+  }
+  if (opts["no-access-log"] && surface === "http") {
+    out.noAccessLog = true;
+  }
+  if (opts.dev) {
+    out.dev = true;
+  }
+  return out;
+}

package/src/skill/generate.ts

@@ -2,17 +2,17 @@
 This module generates Agent Skills content (SKILL.md + reference.md) from a CLI schema.
 */
 
-import { defaultConfigEntryTitle } from "../config/entry.ts";
-import { generateApiGuide } from "../docs/api-guide.ts";
+import { defaultConfigEntryTitle } from "~/config/entry.ts";
+import { collectOptionDefs } from "~/core/parse.ts";
+import { CliOptionKind, type CliProgram } from "~/core/types.ts";
+import { generateCliGuide } from "~/docs/cli-guide.ts";
 import {
   collectMcpTools,
   type McpToolDef,
   mcpServerId,
   resolveMcpSchemaUri,
   sanitizeToolSegment,
-} from "../mcp/tools.ts";
-import { collectOptionDefs } from "../parse.ts";
-import { CliOptionKind, type CliProgram } from "../types.ts";
+} from "~/mcp/tools.ts";
 import type { SkillTarget } from "./naming.ts";
 import { skillDirNameForTarget, skillFrontmatterName } from "./naming.ts";
 
@@ -149,7 +149,7 @@ function buildSkillMd(root: CliProgram, target: SkillTarget, dirName: string): s
     "",
     "## Reference",
     "",
-    `For full detail, open \`reference.md\` in this skill directory (same as \`${root.key} docs api\`).`,
+    `For full detail, open \`reference.md\` in this skill directory (same as \`${root.key} docs cli\`).`,
     "",
   );
 
@@ -190,9 +190,9 @@ function buildSkillMd(root: CliProgram, target: SkillTarget, dirName: string): s
   return lines.join("\n");
 }
 
-/** Builds reference.md with the full `docs api` markdown guide. */
+/** Builds reference.md with the compact `docs cli` markdown guide. */
 function buildReferenceMd(root: CliProgram): string {
-  return generateApiGuide(root);
+  return generateCliGuide(root, { compact: true });
 }
 
 /** Builds MCP routing SKILL.md for Claude Code plugin zips. */

package/src/skill/hint.ts

@@ -1,4 +1,4 @@
-import type { CliProgram } from "../types.ts";
+import type { CliProgram } from "~/core/types.ts";
 
 /** YAML frontmatter block at the start of SKILL.md. */
 export const MARKDOWN_FRONTMATTER_RE = /^---\r?\n[\s\S]*?\r?\n---\r?\n/;

package/src/skill/install.ts

@@ -1,7 +1,7 @@
 import { existsSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
-import { userHome } from "../paths/host.ts";
-import type { CliProgram } from "../types.ts";
+import type { CliProgram } from "~/core/types.ts";
+import { userHome } from "~/paths/host.ts";
 import { generateSkillBundle, type SkillTarget } from "./generate.ts";
 import { applySkillInstallHints } from "./hint.ts";
 

package/src/skill/naming.ts

@@ -1,7 +1,7 @@
 /** Agent skill install targets. */
 export type SkillTarget = "cursor" | "claude" | "codex" | "opencode" | "openclaw";
 
-import { sanitizeToolSegment } from "../mcp/tools.ts";
+import { sanitizeToolSegment } from "~/mcp/tools.ts";
 
 /** Kebab-case skill folder + frontmatter name for agents that require hyphen slugs. */
 export function skillSlug(programKey: string): string {

package/src/{test-fixtures.ts → test/fixtures.ts}

@@ -1,5 +1,5 @@
-import type { CliProgram } from "./types.ts";
-import { CliFallbackMode, CliOptionKind } from "./types.ts";
+import type { CliProgram } from "~/core/types.ts";
+import { CliFallbackMode, CliOptionKind } from "~/core/types.ts";
 
 export function testProgram(prog: Record<string, unknown> & { key: string; description: string }): CliProgram {
   return { version: "0.0.0", ...prog } as CliProgram;
@@ -166,6 +166,7 @@ export function nestedDocsFallbackFixture(): CliProgram {
   return testProgram({
     key: "app",
     description: "",
+    docs: { enabled: false },
     commands: [
       {
         key: "docs",

package/src/{config.integration.test.ts → test/integration/config.test.ts}

@@ -6,9 +6,9 @@ import { expect, test } from "bun:test";
 import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { dirname, join } from "node:path";
-import { bootstrapAppConfig } from "./config/bootstrap.ts";
-import { resolveAppConfigPath } from "./config/file.ts";
-import { mcpRequest, testProgram } from "./test-fixtures.ts";
+import { bootstrapAppConfig } from "~/config/bootstrap.ts";
+import { resolveAppConfigPath } from "~/config/file.ts";
+import { mcpRequest, testProgram } from "~/test/fixtures.ts";
 
 /** Tests that bootstrapAppConfig prefers host env over config file. */
 test("bootstrapAppConfig prefers host env over config file", () => {
@@ -124,13 +124,13 @@ test("MCP config file loads and exports vars for tool handlers", async () => {
   rmSync(dir, { recursive: true, force: true });
 });
 
-/** Cli.run docs api skips required appConfig exit. */
-test("Cli.run docs api skips required appConfig exit", async () => {
+/** Cli.run docs cli skips required appConfig exit. */
+test("Cli.run docs cli skips required appConfig exit", async () => {
   const dir = mkdtempSync(join(tmpdir(), "argsbarg-docs-skip-"));
   const configFile = join(dir, ".local", "lib", "docs_skip_test", "config");
   mkdirSync(dirname(configFile), { recursive: true });
   writeFileSync(configFile, "{}\n");
-  const entry = join(import.meta.dir, "index.ts");
+  const entry = join(import.meta.dir, "..", "..", "index.ts");
   const mainPath = join(dir, "run-docs.ts");
   writeFileSync(
     mainPath,
@@ -139,7 +139,7 @@ const program = {
   key: "docs-skip-test",
   version: "1.0.0",
   description: "test",
-  docs: { enabled: true, topics: { readme: { text: "# readme\\n" } } },
+  docs: { topics: { readme: { text: "# readme\\n" } } },
   appConfig: {
     entries: { token: { description: "Token.", env: "DOCS_SKIP_RUN_TOKEN" } },
   },
@@ -151,7 +151,7 @@ await new Cli(program).run(process.argv.slice(2));
   const env = { ...process.env, HOME: dir } as Record<string, string | undefined>;
   delete env.DOCS_SKIP_RUN_TOKEN;
   try {
-    const proc = Bun.spawn(["bun", "run", mainPath, "docs", "api"], {
+    const proc = Bun.spawn(["bun", "run", mainPath, "docs", "cli"], {
       stdout: "pipe",
       stderr: "pipe",
       env,