argsbarg 3.6.4 → 4.0.1

package/src/config/resolve.ts

@@ -0,0 +1,167 @@
+/*
+Resolve program.appConfig values: defaults, file, env override, export to process.env.
+*/
+
+import type { CliAppConfigEntry, CliProgram } from "../types.ts";
+import { configEntryRequired, jsonSchemaRequiredKeys } from "./entry.ts";
+import type { AppConfigFileData } from "./file.ts";
+import { displayAppConfigPath } from "./file.ts";
+import { effectiveJsonSchema, schemaDefaultForKey } from "./schema.ts";
+
+export type ResolvedConfig = Record<string, unknown>;
+
+function isPresent(value: unknown): boolean {
+  if (value === undefined || value === null) {
+    return false;
+  }
+  if (typeof value === "string" && value.length === 0) {
+    return false;
+  }
+  return true;
+}
+
+function envOverrideValue(envName: string): string | undefined {
+  const val = process.env[envName];
+  if (val === undefined || val.length === 0) {
+    return undefined;
+  }
+  return val;
+}
+
+/** Coerce env string to typed value using property schema when possible. */
+function coerceEnvValue(program: CliProgram, key: string, raw: string): unknown {
+  const jsonSchema = effectiveJsonSchema(program);
+  if (!jsonSchema) {
+    return raw;
+  }
+  const properties = jsonSchema.properties;
+  if (typeof properties !== "object" || properties === null || Array.isArray(properties)) {
+    return raw;
+  }
+  const prop = (properties as Record<string, unknown>)[key];
+  if (typeof prop !== "object" || prop === null || Array.isArray(prop)) {
+    return raw;
+  }
+  const type = (prop as Record<string, unknown>).type;
+  if (type === "number" || type === "integer") {
+    const n = Number(raw);
+    return Number.isNaN(n) ? raw : n;
+  }
+  if (type === "boolean") {
+    const lower = raw.toLowerCase();
+    if (lower === "true" || lower === "1") return true;
+    if (lower === "false" || lower === "0") return false;
+  }
+  return raw;
+}
+
+/** Resolve all schema keys from file data and process.env. */
+export function resolveAppConfig(program: CliProgram, fileData: AppConfigFileData): ResolvedConfig {
+  const appConfig = program.appConfig;
+  if (!appConfig) {
+    return {};
+  }
+  const out: ResolvedConfig = {};
+  for (const [key, entry] of Object.entries(appConfig.entries)) {
+    const value = resolveConfigKey(program, key, entry, fileData);
+    if (value !== undefined) {
+      out[key] = value;
+    }
+  }
+  return out;
+}
+
+function resolveConfigKey(
+  program: CliProgram,
+  key: string,
+  entry: CliAppConfigEntry,
+  fileData: AppConfigFileData,
+): unknown {
+  if (entry.env) {
+    const fromEnv = envOverrideValue(entry.env);
+    if (fromEnv !== undefined) {
+      return coerceEnvValue(program, key, fromEnv);
+    }
+  }
+  if (key in fileData && isPresent(fileData[key])) {
+    return fileData[key];
+  }
+  const def = schemaDefaultForKey(program, key);
+  if (def !== undefined) {
+    return def;
+  }
+  return undefined;
+}
+
+/** Write mapped config values to process.env for subprocess inheritance. */
+export function exportConfigToEnv(program: CliProgram, resolved: ResolvedConfig): void {
+  const appConfig = program.appConfig;
+  if (!appConfig) {
+    return;
+  }
+  for (const [key, entry] of Object.entries(appConfig.entries)) {
+    if (!entry.env) {
+      continue;
+    }
+    const value = resolved[key];
+    if (!isPresent(value)) {
+      continue;
+    }
+    process.env[entry.env] = stringifyConfigValue(value);
+  }
+}
+
+export function stringifyConfigValue(value: unknown): string {
+  if (typeof value === "string") {
+    return value;
+  }
+  if (typeof value === "number" || typeof value === "boolean") {
+    return String(value);
+  }
+  return JSON.stringify(value);
+}
+
+/** Required schema keys that are still missing after resolution. */
+export function missingRequiredConfig(program: CliProgram, resolved: ResolvedConfig): string[] {
+  const appConfig = program.appConfig;
+  if (!appConfig) {
+    return [];
+  }
+  const jsonSchema = effectiveJsonSchema(program);
+  const fromSchema = jsonSchema ? jsonSchemaRequiredKeys(jsonSchema) : undefined;
+  const missing: string[] = [];
+  for (const [key, entry] of Object.entries(appConfig.entries)) {
+    if (!configEntryRequired(key, entry, fromSchema)) {
+      continue;
+    }
+    if (!isPresent(resolved[key])) {
+      missing.push(key);
+    }
+  }
+  return missing;
+}
+
+/** Stderr message when required config keys are missing. */
+export function formatMissingConfigMessage(program: CliProgram, keys: string[]): string {
+  const list = keys.join(", ");
+  const path = displayAppConfigPath(program);
+  return [
+    `Missing required configuration: ${list}`,
+    `Configure interactively:  ${program.key} install --configure`,
+    `Or set via:               ${program.key} config set <key> <value>`,
+    `Config file:              ${path}`,
+    `See:                      ${program.key} docs mcp`,
+  ].join("\n");
+}
+
+/** MCP tools/call error when required config is missing. */
+export function formatMcpMissingConfigMessage(program: CliProgram, keys: string[]): string {
+  const list = keys.join(", ");
+  const path = displayAppConfigPath(program);
+  return [
+    `Missing required configuration: ${list}`,
+    `Configure: ${program.key} install --configure`,
+    `Or set via: ${program.key} config set`,
+    `Config file: ${path}`,
+  ].join("\n");
+}

package/src/config/schema.ts

@@ -0,0 +1,101 @@
+/*
+Effective JSON Schema for program.appConfig (block schema or all-string synthesis).
+*/
+
+import type { CliAppConfigEntry, CliProgram } from "../types.ts";
+import { configEntryRequired, jsonSchemaRequiredKeys } from "./entry.ts";
+
+/** Synthesize a draft-07 object schema with string properties from metadata entries. */
+export function synthesizeAllStringSchema(
+  schema: Record<string, CliAppConfigEntry>,
+): Record<string, unknown> {
+  const properties: Record<string, unknown> = {};
+  const required: string[] = [];
+  for (const [key, entry] of Object.entries(schema)) {
+    const prop: Record<string, unknown> = {
+      type: "string",
+      description: entry.description,
+    };
+    if (entry.default !== undefined) {
+      prop.default = entry.default;
+    }
+    properties[key] = prop;
+    if (entry.required !== false) {
+      required.push(key);
+    }
+  }
+  const out: Record<string, unknown> = {
+    type: "object",
+    additionalProperties: false,
+    properties,
+  };
+  if (required.length > 0) {
+    out.required = required;
+  }
+  return out;
+}
+
+/** Block JSON Schema used for validation, or synthesized all-string schema. */
+export function effectiveJsonSchema(program: CliProgram): Record<string, unknown> | undefined {
+  const appConfig = program.appConfig;
+  if (!appConfig) {
+    return undefined;
+  }
+  if (appConfig.jsonSchema !== undefined) {
+    return appConfig.jsonSchema;
+  }
+  return synthesizeAllStringSchema(appConfig.entries);
+}
+
+/** Property subschema for one config key from the effective root schema. */
+export function configPropertySchema(
+  jsonSchema: Record<string, unknown>,
+  key: string,
+): Record<string, unknown> | undefined {
+  const properties = jsonSchema.properties;
+  if (typeof properties !== "object" || properties === null || Array.isArray(properties)) {
+    return undefined;
+  }
+  const prop = (properties as Record<string, unknown>)[key];
+  if (typeof prop !== "object" || prop === null || Array.isArray(prop)) {
+    return undefined;
+  }
+  return prop as Record<string, unknown>;
+}
+
+/** Default value for a key from JSON Schema property or entry metadata. */
+export function schemaDefaultForKey(program: CliProgram, key: string): unknown | undefined {
+  const appConfig = program.appConfig;
+  if (!appConfig) {
+    return undefined;
+  }
+  const entry = appConfig.entries[key];
+  if (!entry) {
+    return undefined;
+  }
+  const jsonSchema = effectiveJsonSchema(program);
+  if (jsonSchema) {
+    const prop = configPropertySchema(jsonSchema, key);
+    if (prop && "default" in prop) {
+      return prop.default;
+    }
+  }
+  return entry.default;
+}
+
+/** Required key set for the program config schema. */
+export function programConfigRequiredKeys(program: CliProgram): Set<string> {
+  const appConfig = program.appConfig;
+  if (!appConfig) {
+    return new Set();
+  }
+  const jsonSchema = effectiveJsonSchema(program);
+  const fromSchema = jsonSchema ? jsonSchemaRequiredKeys(jsonSchema) : undefined;
+  const required = new Set<string>();
+  for (const [key, entry] of Object.entries(appConfig.entries)) {
+    if (configEntryRequired(key, entry, fromSchema)) {
+      required.add(key);
+    }
+  }
+  return required;
+}

package/src/config/validate.test.ts

@@ -0,0 +1,63 @@
+import { describe, expect, test } from "bun:test";
+import { parseConfigSetValue, validateConfigDocument } from "./validate.ts";
+
+const rootSchema = {
+  type: "object",
+  additionalProperties: false,
+  required: ["apiToken", "maxRetries"],
+  properties: {
+    apiToken: { type: "string", minLength: 1 },
+    maxRetries: { type: "integer", minimum: 0, maximum: 10 },
+    enabled: { type: "boolean", default: true },
+    prefs: {
+      type: "object",
+      properties: { ttl: { type: "number" } },
+      required: ["ttl"],
+    },
+  },
+};
+
+describe("config/validate", () => {
+  test("accepts valid document", () => {
+    const result = validateConfigDocument(
+      { apiToken: "x", maxRetries: 3, prefs: { ttl: 3600 } },
+      rootSchema,
+    );
+    expect(result.valid).toBe(true);
+    expect(result.errors).toEqual([]);
+  });
+
+  test("rejects missing required property", () => {
+    const result = validateConfigDocument({ apiToken: "x" }, rootSchema);
+    expect(result.valid).toBe(false);
+    expect(result.errors.some((e) => e.includes("maxRetries"))).toBe(true);
+  });
+
+  test("rejects unknown property when additionalProperties is false", () => {
+    const result = validateConfigDocument(
+      { apiToken: "x", maxRetries: 1, extra: true },
+      rootSchema,
+    );
+    expect(result.valid).toBe(false);
+    expect(result.errors.some((e) => e.includes("extra"))).toBe(true);
+  });
+
+  test("rejects type mismatch", () => {
+    const result = validateConfigDocument({ apiToken: "x", maxRetries: "nope" }, rootSchema);
+    expect(result.valid).toBe(false);
+  });
+
+  test("parseConfigSetValue coerces number and boolean", () => {
+    expect(parseConfigSetValue("5", { type: "integer" }, rootSchema, false)).toBe(5);
+    expect(parseConfigSetValue("true", { type: "boolean" }, rootSchema, false)).toBe(true);
+  });
+
+  test("parseConfigSetValue requires --json for objects", () => {
+    expect(() => parseConfigSetValue('{"ttl":1}', { type: "object" }, rootSchema, false)).toThrow(
+      /--json/,
+    );
+    expect(parseConfigSetValue('{"ttl":1}', { type: "object" }, rootSchema, true)).toEqual({
+      ttl: 1,
+    });
+  });
+});

package/src/config/validate.ts

@@ -0,0 +1,292 @@
+/*
+Draft-07 JSON Schema subset validator for program.appConfig files.
+Aligned with common ts-json-schema-generator output (local $ref, objects, scalars).
+*/
+
+type JsonSchema = Record<string, unknown>;
+
+export interface ValidateResult {
+  valid: boolean;
+  errors: string[];
+}
+
+/** Validate `data` against a JSON Schema root. Returns human-readable error messages. */
+export function validateConfigDocument(data: unknown, rootSchema: JsonSchema): ValidateResult {
+  const errors: string[] = [];
+  validateValue(data, rootSchema, rootSchema, "$", errors);
+  return { valid: errors.length === 0, errors };
+}
+
+function validateValue(
+  value: unknown,
+  schema: JsonSchema,
+  root: JsonSchema,
+  path: string,
+  errors: string[],
+): void {
+  const resolved = resolveSchema(schema, root);
+  if (!resolved) {
+    return;
+  }
+
+  if ("const" in resolved) {
+    if (value !== resolved.const) {
+      errors.push(`${path}: must be ${JSON.stringify(resolved.const)}`);
+    }
+    return;
+  }
+
+  if (Array.isArray(resolved.enum)) {
+    if (!resolved.enum.some((item) => item === value)) {
+      errors.push(`${path}: must be one of ${JSON.stringify(resolved.enum)}`);
+    }
+    return;
+  }
+
+  const anyOf = resolved.anyOf ?? resolved.oneOf;
+  if (Array.isArray(anyOf)) {
+    const branchErrors: string[][] = [];
+    for (const branch of anyOf) {
+      if (typeof branch !== "object" || branch === null || Array.isArray(branch)) {
+        continue;
+      }
+      const branchErrs: string[] = [];
+      validateValue(value, branch as JsonSchema, root, path, branchErrs);
+      if (branchErrs.length === 0) {
+        return;
+      }
+      branchErrors.push(branchErrs);
+    }
+    errors.push(`${path}: must match one of the allowed types`);
+    if (branchErrors.length === 1 && branchErrors[0]?.[0]) {
+      errors.push(branchErrors[0][0]);
+    }
+    return;
+  }
+
+  const types = normalizeTypes(resolved.type);
+  if (types.length > 0 && !matchesAnyType(value, types)) {
+    errors.push(`${path}: must be ${types.join(" or ")}`);
+    return;
+  }
+
+  if (types.includes("string") || (types.length === 0 && typeof value === "string")) {
+    validateString(value, resolved, path, errors);
+  }
+  if (types.includes("number") || types.includes("integer")) {
+    validateNumber(value, resolved, path, errors, types.includes("integer"));
+  }
+  if (types.includes("boolean")) {
+    if (typeof value !== "boolean") {
+      errors.push(`${path}: must be boolean`);
+    }
+  }
+  if (types.includes("null") && value !== null) {
+    errors.push(`${path}: must be null`);
+  }
+  if (types.includes("object") || (types.length === 0 && isPlainObject(value))) {
+    validateObject(value, resolved, root, path, errors);
+  }
+  if (types.includes("array") || (types.length === 0 && Array.isArray(value))) {
+    validateArray(value, resolved, root, path, errors);
+  }
+}
+
+function resolveSchema(schema: JsonSchema, root: JsonSchema): JsonSchema | undefined {
+  const ref = schema.$ref;
+  if (typeof ref === "string" && ref.startsWith("#/definitions/")) {
+    const name = decodeURIComponent(ref.slice("#/definitions/".length));
+    const definitions = root.definitions;
+    if (typeof definitions !== "object" || definitions === null || Array.isArray(definitions)) {
+      return schema;
+    }
+    const target = (definitions as Record<string, unknown>)[name];
+    if (typeof target === "object" && target !== null && !Array.isArray(target)) {
+      return target as JsonSchema;
+    }
+  }
+  return schema;
+}
+
+function normalizeTypes(type: unknown): string[] {
+  if (typeof type === "string") {
+    return [type];
+  }
+  if (Array.isArray(type)) {
+    return type.filter((t): t is string => typeof t === "string");
+  }
+  return [];
+}
+
+function matchesAnyType(value: unknown, types: string[]): boolean {
+  for (const t of types) {
+    if (t === "null" && value === null) return true;
+    if (t === "array" && Array.isArray(value)) return true;
+    if (t === "object" && isPlainObject(value)) return true;
+    if (t === "integer" && typeof value === "number" && Number.isInteger(value)) return true;
+    if (t === "number" && typeof value === "number") return true;
+    if (t === "boolean" && typeof value === "boolean") return true;
+    if (t === "string" && typeof value === "string") return true;
+  }
+  return types.length === 0;
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function validateString(value: unknown, schema: JsonSchema, path: string, errors: string[]): void {
+  if (typeof value !== "string") {
+    errors.push(`${path}: must be string`);
+    return;
+  }
+  if (typeof schema.minLength === "number" && value.length < schema.minLength) {
+    errors.push(`${path}: string shorter than minLength ${schema.minLength}`);
+  }
+  if (typeof schema.maxLength === "number" && value.length > schema.maxLength) {
+    errors.push(`${path}: string longer than maxLength ${schema.maxLength}`);
+  }
+  if (typeof schema.pattern === "string") {
+    try {
+      if (!new RegExp(schema.pattern).test(value)) {
+        errors.push(`${path}: does not match pattern`);
+      }
+    } catch {
+      /* invalid pattern in schema — skip */
+    }
+  }
+}
+
+function validateNumber(
+  value: unknown,
+  schema: JsonSchema,
+  path: string,
+  errors: string[],
+  integer: boolean,
+): void {
+  if (typeof value !== "number" || Number.isNaN(value)) {
+    errors.push(`${path}: must be number`);
+    return;
+  }
+  if (integer && !Number.isInteger(value)) {
+    errors.push(`${path}: must be integer`);
+  }
+  if (typeof schema.minimum === "number" && value < schema.minimum) {
+    errors.push(`${path}: below minimum ${schema.minimum}`);
+  }
+  if (typeof schema.maximum === "number" && value > schema.maximum) {
+    errors.push(`${path}: above maximum ${schema.maximum}`);
+  }
+}
+
+function validateObject(
+  value: unknown,
+  schema: JsonSchema,
+  root: JsonSchema,
+  path: string,
+  errors: string[],
+): void {
+  if (!isPlainObject(value)) {
+    errors.push(`${path}: must be object`);
+    return;
+  }
+  const properties = schema.properties;
+  const propMap =
+    typeof properties === "object" && properties !== null && !Array.isArray(properties)
+      ? (properties as Record<string, JsonSchema>)
+      : undefined;
+
+  if (propMap) {
+    for (const [key, propSchema] of Object.entries(propMap)) {
+      if (key in value) {
+        validateValue(value[key], propSchema, root, `${path}.${key}`, errors);
+      }
+    }
+  }
+
+  const required = schema.required;
+  if (Array.isArray(required)) {
+    for (const key of required) {
+      if (typeof key === "string" && !(key in value)) {
+        errors.push(`${path}: missing required property '${key}'`);
+      }
+    }
+  }
+
+  if (schema.additionalProperties === false && propMap) {
+    for (const key of Object.keys(value)) {
+      if (!(key in propMap)) {
+        errors.push(`${path}: unknown property '${key}'`);
+      }
+    }
+  }
+}
+
+function validateArray(
+  value: unknown,
+  schema: JsonSchema,
+  root: JsonSchema,
+  path: string,
+  errors: string[],
+): void {
+  if (!Array.isArray(value)) {
+    errors.push(`${path}: must be array`);
+    return;
+  }
+  if (typeof schema.minItems === "number" && value.length < schema.minItems) {
+    errors.push(`${path}: fewer than minItems ${schema.minItems}`);
+  }
+  if (typeof schema.maxItems === "number" && value.length > schema.maxItems) {
+    errors.push(`${path}: more than maxItems ${schema.maxItems}`);
+  }
+  const items = schema.items;
+  if (typeof items === "object" && items !== null && !Array.isArray(items)) {
+    for (let i = 0; i < value.length; i++) {
+      validateValue(value[i], items as JsonSchema, root, `${path}[${i}]`, errors);
+    }
+  }
+}
+
+/** Parse a CLI/MCP set value against a property schema. */
+export function parseConfigSetValue(
+  raw: string,
+  propertySchema: JsonSchema | undefined,
+  rootSchema: JsonSchema,
+  useJson: boolean,
+): unknown {
+  if (useJson) {
+    const parsed = JSON.parse(raw) as unknown;
+    const errors: string[] = [];
+    if (propertySchema) {
+      validateValue(parsed, propertySchema, rootSchema, "$", errors);
+      if (errors.length > 0) {
+        throw new Error(errors[0] ?? "Invalid config value");
+      }
+    }
+    return parsed;
+  }
+
+  const resolved = propertySchema ? resolveSchema(propertySchema, rootSchema) : undefined;
+  const types = resolved ? normalizeTypes(resolved.type) : ["string"];
+
+  if (types.includes("boolean")) {
+    const lower = raw.trim().toLowerCase();
+    if (lower === "true" || lower === "1") return true;
+    if (lower === "false" || lower === "0") return false;
+    throw new Error("Expected boolean: true, false, 1, or 0");
+  }
+  if (types.includes("number") || types.includes("integer")) {
+    const n = Number(raw);
+    if (Number.isNaN(n)) {
+      throw new Error("Expected number");
+    }
+    if (types.includes("integer") && !Number.isInteger(n)) {
+      throw new Error("Expected integer");
+    }
+    return n;
+  }
+  if (types.includes("object") || types.includes("array")) {
+    throw new Error("Use --json for object or array config values");
+  }
+  return raw;
+}