argsbarg 3.6.4 → 4.0.0

package/src/config/context.ts

@@ -0,0 +1,98 @@
+/*
+Handler-facing resolved app config snapshot (ctx.appConfig).
+*/
+
+import type { CliProgram } from "../types.ts";
+import { writeAppConfigFile } from "./file.ts";
+import type { ResolvedConfig } from "./resolve.ts";
+import { exportConfigToEnv, resolveAppConfig } from "./resolve.ts";
+
+/** Empty snapshot when program.appConfig is not set. */
+export class EmptyAppConfigSnapshot {
+  get(_key: string): undefined {
+    return undefined;
+  }
+
+  require(key: string): never {
+    throw new Error(`Configuration key '${key}' is not available (program.appConfig is not set)`);
+  }
+
+  set(_key: string, _value: unknown): void {
+    throw new Error("program.appConfig is not set");
+  }
+
+  read(): ResolvedConfig {
+    return {};
+  }
+}
+
+/** Resolved config for handlers with program.appConfig set. */
+export class AppConfigSnapshot {
+  private snapshot: ResolvedConfig;
+  private fileData: Record<string, unknown>;
+
+  constructor(
+    private readonly program: CliProgram,
+    fileData: Record<string, unknown>,
+    resolved: ResolvedConfig,
+  ) {
+    this.fileData = { ...fileData };
+    this.snapshot = { ...resolved };
+  }
+
+  get(key: string): unknown {
+    this.assertEntryKey(key);
+    return this.snapshot[key];
+  }
+
+  require(key: string): unknown {
+    const value = this.get(key);
+    if (
+      value === undefined ||
+      value === null ||
+      (typeof value === "string" && value.length === 0)
+    ) {
+      throw new Error(`Missing required configuration: ${key}`);
+    }
+    return value;
+  }
+
+  set(key: string, value: unknown): void {
+    this.assertEntryKey(key);
+    const next = { ...this.fileData, [key]: value };
+    writeAppConfigFile(this.program, next);
+    this.fileData = next;
+    this.snapshot = resolveAppConfig(this.program, next);
+    exportConfigToEnv(this.program, this.snapshot);
+  }
+
+  read(): ResolvedConfig {
+    return { ...this.snapshot };
+  }
+
+  /** Replace snapshot after external bootstrap (internal). */
+  refresh(fileData: Record<string, unknown>, resolved: ResolvedConfig): void {
+    this.fileData = { ...fileData };
+    this.snapshot = { ...resolved };
+  }
+
+  private assertEntryKey(key: string): void {
+    const entries = this.program.appConfig?.entries;
+    if (!entries || !(key in entries)) {
+      throw new Error(`Unknown configuration key: ${key}`);
+    }
+  }
+}
+
+export type AnyAppConfigSnapshot = AppConfigSnapshot | EmptyAppConfigSnapshot;
+
+export function createAppConfigSnapshot(
+  program: CliProgram,
+  fileData: Record<string, unknown>,
+  resolved: ResolvedConfig,
+): AnyAppConfigSnapshot {
+  if (!program.appConfig) {
+    return new EmptyAppConfigSnapshot();
+  }
+  return new AppConfigSnapshot(program, fileData, resolved);
+}

package/src/config/entry.ts

@@ -0,0 +1,81 @@
+/*
+Shared helpers for program.appConfig schema entries.
+*/
+
+import type { CliAppConfigEntry, CliProgram } from "../types.ts";
+
+/** Default title when `CliAppConfigEntry.title` is omitted. */
+export function defaultConfigEntryTitle(key: string): string {
+  return key;
+}
+
+/** Default sensitive flag from config key name. */
+export function defaultConfigEntrySensitive(key: string): boolean {
+  return /key|token|secret|password/i.test(key);
+}
+
+/** Whether a schema entry is required for bootstrap / MCP enforcement. */
+export function configEntryRequired(
+  key: string,
+  entry: CliAppConfigEntry,
+  jsonSchemaRequired: Set<string> | undefined,
+): boolean {
+  if (entry.required === false) {
+    return false;
+  }
+  if (jsonSchemaRequired !== undefined) {
+    return jsonSchemaRequired.has(key);
+  }
+  return true;
+}
+
+/** Whether prompts and `config get` should redact this entry. */
+export function configEntrySensitive(key: string, entry: CliAppConfigEntry): boolean {
+  return entry.sensitive ?? defaultConfigEntrySensitive(key);
+}
+
+/** Manifest / plugin user_config key from a schema key. */
+export function configUserConfigKey(key: string): string {
+  const snake = key
+    .replace(/([a-z0-9])([A-Z])/g, "$1_$2")
+    .replace(/([A-Z]+)([A-Z][a-z])/g, "$1_$2")
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "_")
+    .replace(/^_|_$/g, "");
+  return snake || "config_key";
+}
+
+/** Required keys from a JSON Schema object root. */
+export function jsonSchemaRequiredKeys(
+  jsonSchema: Record<string, unknown>,
+): Set<string> | undefined {
+  const required = jsonSchema.required;
+  if (!Array.isArray(required)) {
+    return undefined;
+  }
+  return new Set(required.filter((k): k is string => typeof k === "string"));
+}
+
+/** Whether built-in config get/set commands are enabled. */
+export function configCommandsEnabled(program: CliProgram): boolean {
+  if (!program.appConfig) {
+    return false;
+  }
+  const commands = program.appConfig.commands;
+  if (commands === false) {
+    return false;
+  }
+  if (typeof commands === "object" && commands.enabled === false) {
+    return false;
+  }
+  return true;
+}
+
+/** Whether MCP exposes config set (config_get always on when commands enabled). */
+export function configMcpSetEnabled(program: CliProgram): boolean {
+  const commands = program.appConfig?.commands;
+  if (typeof commands === "object" && commands.mcpSet === false) {
+    return false;
+  }
+  return true;
+}

package/src/config/file.test.ts

@@ -0,0 +1,112 @@
+import { describe, expect, test } from "bun:test";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import type { CliProgram } from "../types.ts";
+import { bootstrapAppConfig } from "./bootstrap.ts";
+import { readAppConfigFile, resolveAppConfigPath, writeAppConfigFile } from "./file.ts";
+import { buildProgramUserConfig } from "./manifest.ts";
+import { formatMissingConfigMessage, missingRequiredConfig, resolveAppConfig } from "./resolve.ts";
+
+const program: CliProgram = {
+  key: "myapp",
+  version: "1.0.0",
+  description: "Demo.",
+  appConfig: {
+    path: "~/.config/myapp-test/config",
+    entries: {
+      apiToken: { description: "Token.", env: "API_TOKEN" },
+      port: { description: "HTTP listen port (default 8080).", required: false },
+    },
+  },
+  handler: () => {},
+};
+
+describe("config/file", () => {
+  test("buildProgramUserConfig from program.appConfig env entries", () => {
+    const cfg = buildProgramUserConfig(program);
+    expect(cfg?.api_token).toMatchObject({
+      title: "apiToken",
+      description: "Token.",
+      required: true,
+    });
+    expect(cfg?.port).toBeUndefined();
+  });
+
+  test("resolveAppConfig prefers host env over file", () => {
+    const dir = mkdtempSync(join(tmpdir(), "cfg-test-"));
+    const prevHome = process.env.HOME;
+    process.env.HOME = dir;
+    const prevToken = process.env.API_TOKEN;
+    process.env.API_TOKEN = "from-host";
+    try {
+      const p: CliProgram = {
+        ...program,
+        appConfig: {
+          ...program.appConfig!,
+          path: join(dir, ".config", "myapp-test", "config"),
+        },
+      };
+      mkdirSync(join(dir, ".config", "myapp-test"), { recursive: true });
+      writeFileSync(resolveAppConfigPath(p), `${JSON.stringify({ apiToken: "from-file" })}\n`);
+      const resolved = resolveAppConfig(p, { apiToken: "from-file" });
+      expect(resolved.apiToken).toBe("from-host");
+    } finally {
+      if (prevHome === undefined) delete process.env.HOME;
+      else process.env.HOME = prevHome;
+      if (prevToken === undefined) delete process.env.API_TOKEN;
+      else process.env.API_TOKEN = prevToken;
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  test("missingRequiredConfig and formatMissingConfigMessage", () => {
+    const prev = process.env.API_TOKEN;
+    delete process.env.API_TOKEN;
+    try {
+      const resolved = resolveAppConfig(program, {});
+      const missing = missingRequiredConfig(program, resolved);
+      expect(missing).toContain("apiToken");
+      expect(missing).not.toContain("port");
+      const msg = formatMissingConfigMessage(program, missing);
+      expect(msg).toContain("install --configure");
+    } finally {
+      if (prev !== undefined) process.env.API_TOKEN = prev;
+    }
+  });
+
+  test("rejects unknown keys on read", () => {
+    const dir = mkdtempSync(join(tmpdir(), "cfg-test-"));
+    try {
+      const p: CliProgram = {
+        ...program,
+        appConfig: {
+          ...program.appConfig!,
+          path: join(dir, "config"),
+        },
+      };
+      writeFileSync(join(dir, "config"), `${JSON.stringify({ extra: true })}\n`);
+      expect(() => readAppConfigFile(p)).toThrow(/Unknown config key/);
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  test("writeAppConfigFile round-trip", () => {
+    const dir = mkdtempSync(join(tmpdir(), "cfg-test-"));
+    try {
+      const p: CliProgram = {
+        ...program,
+        appConfig: {
+          ...program.appConfig!,
+          path: join(dir, "config"),
+        },
+      };
+      writeAppConfigFile(p, { apiToken: "saved" });
+      const { resolved } = bootstrapAppConfig(p, { validateFile: true });
+      expect(resolved.apiToken).toBe("saved");
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+});

package/src/config/file.ts

@@ -0,0 +1,120 @@
+/*
+JSON app config file path helpers and strict read/write.
+*/
+
+import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { sanitizeToolSegment } from "../mcp/tools.ts";
+import { appConfigHome, expandTilde } from "../paths/host.ts";
+import type { CliProgram } from "../types.ts";
+import { effectiveJsonSchema } from "./schema.ts";
+import { validateConfigDocument } from "./validate.ts";
+
+export type AppConfigFileData = Record<string, unknown>;
+
+/** Resolved absolute path to the app JSON config file. */
+export function resolveAppConfigPath(program: CliProgram): string {
+  const custom = program.appConfig?.path;
+  if (custom) {
+    return expandTilde(custom);
+  }
+  const dirName = sanitizeToolSegment(program.key);
+  return join(appConfigHome(), dirName, "config");
+}
+
+/** Human-readable config path for error messages (`~` when under home). */
+export function displayAppConfigPath(program: CliProgram): string {
+  const resolved = resolveAppConfigPath(program);
+  const home = process.env.HOME ?? "";
+  if (home.length > 0 && resolved.startsWith(home)) {
+    return `~${resolved.slice(home.length)}`;
+  }
+  return resolved;
+}
+
+function parseConfigJson(text: string, path: string): AppConfigFileData {
+  try {
+    const parsed = JSON.parse(text) as unknown;
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+      throw new Error("root must be a JSON object");
+    }
+    return parsed as AppConfigFileData;
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    throw new Error(`Invalid JSON in config file ${path}: ${msg}`);
+  }
+}
+
+/** Read config file; returns `{}` when missing. Does not validate. */
+export function readAppConfigFileRaw(path: string): AppConfigFileData {
+  if (!existsSync(path)) {
+    return {};
+  }
+  let text: string;
+  try {
+    text = readFileSync(path, "utf8");
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    throw new Error(`Could not read config file ${path}: ${msg}`);
+  }
+  return parseConfigJson(text, path);
+}
+
+/** Read and validate config file against program schema. */
+export function readAppConfigFile(program: CliProgram): AppConfigFileData {
+  const path = resolveAppConfigPath(program);
+  const data = readAppConfigFileRaw(path);
+  if (Object.keys(data).length === 0) {
+    return data;
+  }
+  validateAppConfigData(program, data, path);
+  return data;
+}
+
+/** Validate in-memory config data; throws on failure. */
+export function validateAppConfigData(
+  program: CliProgram,
+  data: AppConfigFileData,
+  pathLabel?: string,
+): void {
+  const appConfig = program.appConfig;
+  if (!appConfig) {
+    throw new Error("program.appConfig is not set");
+  }
+  const allowed = new Set(Object.keys(appConfig.entries));
+  for (const key of Object.keys(data)) {
+    if (!allowed.has(key)) {
+      const where = pathLabel ?? "config";
+      throw new Error(`Unknown config key '${key}' in ${where}`);
+    }
+  }
+  const jsonSchema = effectiveJsonSchema(program);
+  if (!jsonSchema) {
+    return;
+  }
+  const result = validateConfigDocument(data, jsonSchema);
+  if (!result.valid) {
+    const where = pathLabel ?? "config";
+    throw new Error(`Invalid config in ${where}: ${result.errors.join("; ")}`);
+  }
+}
+
+/** Merge-write schema keys to the config file (`0o600`). */
+export function writeAppConfigFile(program: CliProgram, data: AppConfigFileData): void {
+  validateAppConfigData(program, data, displayAppConfigPath(program));
+  const path = resolveAppConfigPath(program);
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, `${JSON.stringify(data, null, 2)}\n`, { mode: 0o600 });
+}
+
+/** Removes the app config file when present. Returns true if removed. */
+export function uninstallAppConfig(program: CliProgram, dry: boolean): boolean {
+  const path = resolveAppConfigPath(program);
+  if (!existsSync(path)) {
+    return false;
+  }
+  if (!dry) {
+    unlinkSync(path);
+  }
+  return true;
+}

package/src/config/manifest.ts

@@ -0,0 +1,62 @@
+/*
+MCP bundle / plugin manifest builders for program.appConfig env-mapped entries.
+*/
+
+import type { CliAppConfigEntry, CliProgram } from "../types.ts";
+import {
+  configEntryRequired,
+  configEntrySensitive,
+  configUserConfigKey,
+  defaultConfigEntryTitle,
+  jsonSchemaRequiredKeys,
+} from "./entry.ts";
+import { effectiveJsonSchema } from "./schema.ts";
+
+function buildConfigUserConfigEntry(
+  key: string,
+  entry: CliAppConfigEntry,
+  jsonSchemaRequired: Set<string> | undefined,
+): Record<string, unknown> {
+  return {
+    type: "string",
+    title: entry.title ?? defaultConfigEntryTitle(key),
+    description: entry.description,
+    sensitive: configEntrySensitive(key, entry),
+    required: configEntryRequired(key, entry, jsonSchemaRequired),
+  };
+}
+
+/** Builds MCPB/plugin user_config from schema entries with `env` set. */
+export function buildProgramUserConfig(program: CliProgram): Record<string, unknown> | undefined {
+  const appConfig = program.appConfig;
+  if (!appConfig) {
+    return undefined;
+  }
+  const jsonSchema = effectiveJsonSchema(program);
+  const fromSchema = jsonSchema ? jsonSchemaRequiredKeys(jsonSchema) : undefined;
+  const out: Record<string, unknown> = {};
+  for (const [key, entry] of Object.entries(appConfig.entries)) {
+    if (!entry.env) {
+      continue;
+    }
+    out[configUserConfigKey(key)] = buildConfigUserConfigEntry(key, entry, fromSchema);
+  }
+  return Object.keys(out).length > 0 ? out : undefined;
+}
+
+/** Plugin .mcp.json env mapping from program.appConfig env entries. */
+export function buildPluginMcpEnvMapping(program: CliProgram): Record<string, string> | undefined {
+  const appConfig = program.appConfig;
+  if (!appConfig) {
+    return undefined;
+  }
+  const out: Record<string, string> = {};
+  for (const [key, entry] of Object.entries(appConfig.entries)) {
+    if (!entry.env) {
+      continue;
+    }
+    const manifestKey = configUserConfigKey(key);
+    out[entry.env] = `\${user_config.${manifestKey}}`;
+  }
+  return Object.keys(out).length > 0 ? out : undefined;
+}

package/src/config/resolve.test.ts

@@ -0,0 +1,88 @@
+import { describe, expect, test } from "bun:test";
+import type { CliProgram } from "../types.ts";
+import { resolveAppConfig } from "./resolve.ts";
+
+const program: CliProgram = {
+  key: "app",
+  version: "1.0.0",
+  description: "Test.",
+  appConfig: {
+    jsonSchema: {
+      type: "object",
+      properties: {
+        apiToken: { type: "string" },
+        maxRetries: { type: "integer", default: 3 },
+        region: { type: "string", default: "us-east-1" },
+      },
+      required: ["apiToken"],
+    },
+    entries: {
+      apiToken: { description: "Token.", env: "API_TOKEN" },
+      maxRetries: { description: "Retries." },
+      region: { description: "Region.", required: false },
+    },
+  },
+  handler: () => {},
+};
+
+describe("config/resolve", () => {
+  test("prefers env over file for mapped keys", () => {
+    const prev = process.env.API_TOKEN;
+    process.env.API_TOKEN = "from-env";
+    try {
+      const resolved = resolveAppConfig(program, { apiToken: "from-file" });
+      expect(resolved.apiToken).toBe("from-env");
+    } finally {
+      if (prev === undefined) delete process.env.API_TOKEN;
+      else process.env.API_TOKEN = prev;
+    }
+  });
+
+  test("uses file when env empty", () => {
+    const prev = process.env.API_TOKEN;
+    delete process.env.API_TOKEN;
+    try {
+      const resolved = resolveAppConfig(program, { apiToken: "from-file" });
+      expect(resolved.apiToken).toBe("from-file");
+    } finally {
+      if (prev !== undefined) process.env.API_TOKEN = prev;
+    }
+  });
+
+  test("empty string in env or file counts as missing", () => {
+    const prev = process.env.API_TOKEN;
+    process.env.API_TOKEN = "";
+    try {
+      const resolved = resolveAppConfig(program, { apiToken: "" });
+      expect(resolved.apiToken).toBeUndefined();
+    } finally {
+      if (prev === undefined) delete process.env.API_TOKEN;
+      else process.env.API_TOKEN = prev;
+    }
+  });
+
+  test("applies jsonSchema default when file and env absent", () => {
+    const prev = process.env.API_TOKEN;
+    delete process.env.API_TOKEN;
+    try {
+      const resolved = resolveAppConfig(program, { apiToken: "ok" });
+      expect(resolved.maxRetries).toBe(3);
+      expect(resolved.region).toBe("us-east-1");
+    } finally {
+      if (prev !== undefined) process.env.API_TOKEN = prev;
+    }
+  });
+
+  test("all-string mode uses entry.default", () => {
+    const stringProgram: CliProgram = {
+      ...program,
+      appConfig: {
+        entries: {
+          greeting: { description: "Hello.", default: "world" },
+        },
+      },
+    };
+    const resolved = resolveAppConfig(stringProgram, {});
+    expect(resolved.greeting).toBe("world");
+  });
+});