@open-cr-agent/cli 0.4.0 → 0.6.0

package/dist/config/cli-config.js

@@ -0,0 +1,199 @@
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { EFFORT_LEVELS, errorMessage, MODEL_TIERS, OcraError, } from "@open-cr-agent/core";
+import { isNotFound } from "@open-cr-agent/core/internal";
+import { z } from "zod";
+import { fetchRemoteConfig } from "./remote.js";
+import { DEFAULT_RUNTIME, effort } from "./schema.js";
+import { layerSchema, listSettings, resolveSettings, } from "./settings.js";
+const CONFIG_PATH = ".ocra/config.json";
+// OCRA_MODEL_TOP, OCRA_EFFORT_STANDARD and so on.
+const tierEnv = (prefix) => Object.fromEntries(MODEL_TIERS.map((tier) => [tier, `${prefix}_${tier.toUpperCase()}`]));
+const MODEL_ENV = tierEnv("OCRA_MODEL");
+const EFFORT_ENV = tierEnv("OCRA_EFFORT");
+export class ConfigError extends OcraError {
+    constructor(message, options) {
+        super("CONFIG_INVALID", message, options);
+        this.name = "ConfigError";
+    }
+}
+// Without the repository's file, only defaults and environment variables
+// apply: that file can name plugins, and plugins run code.
+export async function loadConfig(root, env, options = { repository: true }) {
+    return (await loadConfigLayers(root, env, options)).config;
+}
+/** The configuration's layers, and what they resolve to on their own. */
+export async function loadConfigLayers(root, env, options = { repository: true }) {
+    const layers = await configLayers(root, env, options);
+    const { config } = resolveConfig(layers);
+    for (const model of unpriced(config.providers, [
+        ...Object.values(config.models),
+        ...Object.values(agentChains(config)),
+    ])) {
+        options.warn?.(`${model} has a price of 0: reported cost and --max-cost-usd do not count its tokens`);
+    }
+    return { config, layers };
+}
+export function resolveConfig(layers) {
+    const { settings, sources } = resolveSettings(layers);
+    const { ultra, providers, ...rest } = settings;
+    return {
+        config: {
+            ...rest,
+            runtime: settings.runtime ?? DEFAULT_RUNTIME,
+            models: defined(settings.models),
+            effort: defined(settings.effort),
+            providers: toProviders(providers),
+        },
+        sources,
+        ultra,
+        listed: listSettings(settings, sources),
+    };
+}
+function defined(map) {
+    return Object.fromEntries(Object.entries(map).filter(([, value]) => value !== undefined));
+}
+// The configuration's layers, earliest first: a shared configuration it
+// extends, the file, and OCRA_MODEL_<TIER> and OCRA_EFFORT_<TIER> on top.
+async function configLayers(root, env, options) {
+    const read = options.read ?? ((path) => readConfigFromDisk(root, path));
+    const files = options.file
+        ? await fileLayers(ownFile(options.file), options, options.file)
+        : options.repository
+            ? await fileLayers(read, options, CONFIG_PATH)
+            : [];
+    return [...files, envLayer(env)];
+}
+function envLayer(env) {
+    const models = {};
+    const efforts = {};
+    for (const tier of MODEL_TIERS) {
+        const chain = (env[MODEL_ENV[tier]] ?? "")
+            .split(",")
+            .map((m) => m.trim())
+            .filter((m) => m !== "");
+        if (chain.length > 0)
+            models[tier] = chain;
+    }
+    for (const tier of MODEL_TIERS) {
+        const name = EFFORT_ENV[tier];
+        const value = env[name]?.trim();
+        if (!value)
+            continue;
+        const level = effort.safeParse(value);
+        if (!level.success) {
+            throw new ConfigError(`${name} must be one of ${EFFORT_LEVELS.join(", ")}`);
+        }
+        efforts[tier] = level.data;
+    }
+    return { source: "env", settings: { models, effort: efforts } };
+}
+function toProviders(declared) {
+    return Object.fromEntries(Object.entries(declared).map(([id, p]) => [
+        id,
+        {
+            baseUrl: p.baseUrl,
+            ...(p.apiKeyEnv ? { apiKeyEnv: p.apiKeyEnv } : {}),
+            ...(p.effort ? { effort: p.effort } : {}),
+            models: Object.fromEntries(Object.entries(p.models).map(([model, price]) => [
+                model,
+                {
+                    input: price.input,
+                    output: price.output,
+                    ...(price.cachedInput === undefined ? {} : { cachedInput: price.cachedInput }),
+                },
+            ])),
+        },
+    ]));
+}
+// The reviewers' and roles' own chains, by agent id (ADR-0025); a disabled
+// reviewer's is left out, since it makes no call.
+export function agentChains(config) {
+    const chains = {};
+    for (const [id, setting] of Object.entries(config.reviewers)) {
+        if (setting.models && setting.enabled !== false)
+            chains[id] = setting.models;
+    }
+    for (const [role, setting] of Object.entries(config.roles)) {
+        if (setting?.models)
+            chains[role] = setting.models;
+    }
+    return chains;
+}
+// Models of declared providers, named in a chain, priced at 0 per token.
+function unpriced(providers, chains) {
+    const named = new Set(chains.flatMap((chain) => chain ?? []));
+    return [...named].filter((model) => {
+        const slash = model.indexOf("/");
+        const price = providers[model.slice(0, slash)]?.models[model.slice(slash + 1)];
+        return price !== undefined && price.input === 0 && price.output === 0;
+    });
+}
+// The user's own checkout, read like any local file (links followed): unlike
+// the review's reads, which never follow links (vcs-local), this is trusted
+// configuration, and --no-repo-config skips it for code that is not.
+function ownFile(file) {
+    return async () => {
+        try {
+            return await readFile(file, "utf8");
+        }
+        catch (error) {
+            throw new ConfigError(`cannot read ${file}: ${errorMessage(error)}`, { cause: error });
+        }
+    };
+}
+async function readConfigFromDisk(root, path) {
+    try {
+        return await readFile(join(root, path), "utf8");
+    }
+    catch (error) {
+        if (isNotFound(error))
+            return undefined;
+        throw error;
+    }
+}
+// The file, and the shared configuration it extends under it.
+async function fileLayers(read, options, label) {
+    const text = await read(CONFIG_PATH);
+    if (text === undefined)
+        return [];
+    let data;
+    try {
+        data = JSON.parse(text);
+    }
+    catch (error) {
+        throw new ConfigError(`${label} is not valid JSON: ${errorMessage(error)}`, {
+            cause: error,
+        });
+    }
+    const local = layerSchema.safeParse(data);
+    if (!local.success)
+        throw new ConfigError(`${label} is invalid: ${z.prettifyError(local.error)}`);
+    const file = { source: "file", settings: local.data };
+    const shared = local.data.extends;
+    if (!shared)
+        return [file];
+    // A shared configuration that cannot be loaded costs its defaults, not the
+    // review: the repository's own settings still apply.
+    let remote;
+    try {
+        remote = await fetchRemoteConfig(shared, options.fetch);
+    }
+    catch (error) {
+        // Its limits are lost with it; say so rather than run silently unbounded.
+        const limits = local.data.maxCostUsd === undefined
+            ? "; none of its settings apply, including any spend or task limit"
+            : "; none of its settings apply";
+        options.warn?.(`could not load extends ${shared}: ${errorMessage(error)}${limits}`);
+        return [file];
+    }
+    const { rules = [], ...rest } = remote;
+    const settings = layerSchema.safeParse(rest);
+    if (!settings.success) {
+        options.warn?.(`ignoring extends ${shared}: its settings are invalid (${z.prettifyError(settings.error)})`);
+        return [file];
+    }
+    const sourced = rules.map((rule) => ({ ...rule, source: "shared" }));
+    return [{ source: "shared", settings: { ...settings.data, rules: sourced } }, file];
+}
+//# sourceMappingURL=cli-config.js.map

package/dist/{review/remote-config.d.ts → config/remote.d.ts}

@@ -1,5 +1,5 @@
 import { z } from "zod";
-export declare const remoteConfigSchema: z.ZodObject<{
+declare const remoteConfigSchema: z.ZodObject<{
     $schema: z.ZodOptional<z.ZodString>;
     models: z.ZodOptional<z.ZodRecord<z.ZodEnum<{
         light: "light";
@@ -31,5 +31,5 @@ export declare const remoteConfigSchema: z.ZodObject<{
 }, z.core.$strict>;
 export type RemoteConfig = z.infer<typeof remoteConfigSchema>;
 export declare function fetchRemoteConfig(spec: string, fetchImpl?: typeof fetch): Promise<RemoteConfig>;
-export declare function mergeConfig(remote: RemoteConfig, local: Record<string, unknown>): Record<string, unknown>;
-//# sourceMappingURL=remote-config.d.ts.map
+export {};
+//# sourceMappingURL=remote.d.ts.map

package/dist/{review/remote-config.js → config/remote.js}

@@ -1,5 +1,5 @@
 import { createHash } from "node:crypto";
-import { OcraError } from "@open-cr-agent/core";
+import { MODEL_TIERS, OcraError } from "@open-cr-agent/core";
 import { repoRuleSchema } from "@open-cr-agent/core/internal";
 import { z } from "zod";
 const MAX_BYTES = 256 * 1024;
@@ -7,11 +7,11 @@ const TIMEOUT_MS = 10_000;
 // What a shared configuration may set: settings, rules and model providers
 // (a company gateway, for example), never plugins or a runtime, because it
 // is fetched from outside the repository.
-export const remoteConfigSchema = z
+const remoteConfigSchema = z
     .object({
     $schema: z.string().optional(),
-    models: z.record(z.enum(["top", "standard", "light"]), z.unknown()).optional(),
-    effort: z.partialRecord(z.enum(["top", "standard", "light"]), z.unknown()).optional(),
+    models: z.record(z.enum(MODEL_TIERS), z.unknown()).optional(),
+    effort: z.partialRecord(z.enum(MODEL_TIERS), z.unknown()).optional(),
     concurrency: z.unknown().optional(),
     taskTimeoutMinutes: z.unknown().optional(),
     runTimeoutMinutes: z.unknown().optional(),
@@ -81,22 +81,4 @@ async function readLimited(response, limit, name) {
     }
     return Buffer.concat(chunks).toString("utf8");
 }
-// The repository's own values win; lists and maps are combined.
-export function mergeConfig(remote, local) {
-    const { rules: _rules, ...settings } = remote;
-    const merged = { ...settings, ...local };
-    for (const key of ["models", "effort", "reviewers", "roles", "github", "providers"]) {
-        const a = settings[key];
-        const b = local[key];
-        if (a !== undefined || b !== undefined)
-            merged[key] = { ...(a ?? {}), ...(b ?? {}) };
-    }
-    for (const key of ["include", "exclude"]) {
-        const a = settings[key] ?? [];
-        const b = local[key] ?? [];
-        if (a.length + b.length > 0)
-            merged[key] = [...a, ...b];
-    }
-    return merged;
-}
-//# sourceMappingURL=remote-config.js.map
+//# sourceMappingURL=remote.js.map

package/dist/{review/config.d.ts → config/schema.d.ts}

@@ -1,7 +1,13 @@
-import { type CustomProvider, type ModelChains, OcraError, type RepoRule, type TierEfforts } from "@open-cr-agent/core";
 import { z } from "zod";
-export declare const CONFIG_PATH = ".ocra/config.json";
-declare const configSchema: z.ZodObject<{
+export declare const effort: z.ZodEnum<{
+    high: "high";
+    low: "low";
+    medium: "medium";
+    minimal: "minimal";
+    none: "none";
+}>;
+export declare const DEFAULT_RUNTIME = "opencode";
+export declare const configSchema: z.ZodObject<{
     $schema: z.ZodOptional<z.ZodString>;
     models: z.ZodDefault<z.ZodObject<{
         top: z.ZodOptional<z.ZodPipe<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>, z.ZodTransform<string[], string | string[]>>>;
@@ -48,7 +54,7 @@ declare const configSchema: z.ZodObject<{
     }, z.core.$strict>>;
     include: z.ZodDefault<z.ZodArray<z.ZodString>>;
     exclude: z.ZodDefault<z.ZodArray<z.ZodString>>;
-    runtime: z.ZodDefault<z.ZodUnion<[z.ZodEnum<{
+    runtime: z.ZodOptional<z.ZodUnion<[z.ZodEnum<{
         direct: "direct";
         opencode: "opencode";
     }>, z.ZodString]>>;
@@ -60,6 +66,7 @@ declare const configSchema: z.ZodObject<{
             lite: "lite";
             trivial: "trivial";
         }>>;
+        models: z.ZodOptional<z.ZodPipe<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>, z.ZodTransform<string[], string | string[]>>>;
         effort: z.ZodOptional<z.ZodEnum<{
             high: "high";
             low: "low";
@@ -73,6 +80,7 @@ declare const configSchema: z.ZodObject<{
         judge: "judge";
         verifier: "verifier";
     }> & z.core.$partial, z.ZodObject<{
+        models: z.ZodOptional<z.ZodPipe<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>, z.ZodTransform<string[], string | string[]>>>;
         effort: z.ZodOptional<z.ZodEnum<{
             high: "high";
             low: "low";
@@ -100,24 +108,4 @@ declare const configSchema: z.ZodObject<{
 }, z.core.$strict>;
 export declare const CONFIG_SCHEMA_ID = "https://ocra.majincheng.com/schema/config.v1.json";
 export declare function configJsonSchema(): Record<string, unknown>;
-export type CliConfig = Omit<z.infer<typeof configSchema>, "models" | "effort" | "providers"> & {
-    models: ModelChains;
-    effort: TierEfforts;
-    providers: Record<string, CustomProvider>;
-    rules: RepoRule[];
-};
-export interface LoadOptions {
-    repository: boolean;
-    read?: (path: string) => Promise<string | undefined>;
-    file?: string;
-    fetch?: typeof fetch;
-    warn?: (message: string) => void;
-}
-export declare class ConfigError extends OcraError {
-    constructor(message: string, options?: {
-        cause?: unknown;
-    });
-}
-export declare function loadConfig(root: string, env: Readonly<Record<string, string | undefined>>, options?: LoadOptions): Promise<CliConfig>;
-export {};
-//# sourceMappingURL=config.d.ts.map
+//# sourceMappingURL=schema.d.ts.map

package/dist/config/schema.js

@@ -0,0 +1,138 @@
+import { EFFORT_LEVELS } from "@open-cr-agent/core";
+import { AGENT_ROLES, MAX_TIMER_MS, RISK_TIERS } from "@open-cr-agent/core/internal";
+import { z } from "zod";
+// What .ocra/config.json may say. Every layer of settings (settings.ts) is
+// checked against it.
+// How much a model reasons before answering (ADR-0025); unset leaves the
+// provider's default.
+export const effort = z.enum(EFFORT_LEVELS);
+// The longest timeout a timer keeps, about 24.8 days; a longer one would fire at once.
+const timeoutMinutes = z
+    .number()
+    .positive()
+    .max(Math.floor(MAX_TIMER_MS / 60_000))
+    .optional();
+const modelChain = z
+    .union([z.string().min(1), z.array(z.string().min(1)).min(1)])
+    .transform((value) => (typeof value === "string" ? [value] : value));
+// Where review code is sent: over https, or plain http only to this machine.
+// OpenCode replaces {env:NAME} and {file:path} anywhere in its configuration,
+// so an address with braces could carry a variable or a file (the checkout's
+// .git/config holds its token) to the endpoint.
+const endpoint = z
+    .url()
+    .refine((value) => {
+    const url = new URL(value);
+    if (url.protocol === "https:")
+        return true;
+    const host = url.hostname.replace(/^\[|\]$/g, "");
+    return (url.protocol === "http:" &&
+        (host === "localhost" || host === "::1" || /^127\.\d+\.\d+\.\d+$/.test(host)));
+}, "must be an https URL, or http on this machine (localhost, 127.0.0.1, ::1)")
+    .refine((value) => !/[{}]/.test(value), "must not contain { or }");
+// The platforms' and clouds' credentials never go to a model endpoint; the
+// same prefixes are never passed to the runtime by prefix (server-env.ts).
+const PLATFORM_TOKENS = /^(GITHUB_|GH_|GITLAB_|CI_|ACTIONS_|RUNNER_|AWS_|AZURE_|NPM_|SSH_|OCRA_)/;
+const price = z.number().min(0).max(10_000);
+const providerSchema = z
+    .object({
+    type: z.literal("openai-compatible"),
+    baseUrl: endpoint,
+    apiKeyEnv: z
+        .string()
+        .regex(/^[A-Za-z_][A-Za-z0-9_]*$/, "must be an environment variable name")
+        .refine((name) => !PLATFORM_TOKENS.test(name), "must not name a platform or cloud credential")
+        .optional(),
+    // Prices in US dollars per million tokens; 0 means unpriced.
+    models: z
+        .record(z.string().regex(/^[\w./:@-]{1,200}$/), z.object({ input: price, output: price, cachedInput: price.optional() }).strict())
+        .refine((models) => Object.keys(models).length > 0, "must list at least one model"),
+    // How the endpoint takes a reasoning effort: "openai" sends
+    // reasoning_effort (the default), "openrouter" sends reasoning.effort.
+    effort: z.enum(["openai", "openrouter"]).optional(),
+})
+    .strict();
+// The runtimes ocra ships; a plugin may register another name, so the
+// schema lists these for editors and still accepts any other string.
+const BUILTIN_RUNTIMES = ["opencode", "direct"];
+export const DEFAULT_RUNTIME = "opencode";
+export const configSchema = z
+    .object({
+    $schema: z.string().optional(),
+    models: z
+        .object({ top: modelChain, standard: modelChain, light: modelChain })
+        .partial()
+        .strict()
+        .default({}),
+    effort: z
+        .object({ top: effort, standard: effort, light: effort })
+        .partial()
+        .strict()
+        .default({}),
+    concurrency: z.number().int().min(1).max(32).optional(),
+    taskTimeoutMinutes: timeoutMinutes,
+    runTimeoutMinutes: timeoutMinutes,
+    verify: z.boolean().optional(),
+    judge: z.boolean().optional(),
+    maxCostUsd: z.number().positive().optional(),
+    maxTasks: z.number().int().min(1).max(1_000).optional(),
+    // Unset: each provider's default. A seed makes sampling repeatable only
+    // where the provider supports it.
+    sampling: z
+        .object({
+        temperature: z.number().min(0).max(2),
+        seed: z
+            .number()
+            .int()
+            .min(0)
+            .max(2 ** 31 - 1),
+    })
+        .partial()
+        .strict()
+        .optional(),
+    github: z
+        .object({ requestChanges: z.boolean(), botLogin: z.string().min(1) })
+        .partial()
+        .strict()
+        .default({}),
+    include: z.array(z.string().min(1)).default([]),
+    exclude: z.array(z.string().min(1)).default([]),
+    // Unset means "opencode"; loadConfig fills it in and records whether the
+    // file chose, so account defaults (ADR-0025) apply only where it did not.
+    runtime: z.enum(BUILTIN_RUNTIMES).or(z.string().min(1)).optional(),
+    plugins: z.array(z.string().min(1)).default([]),
+    reviewers: z
+        .record(z.string(), z
+        .object({
+        enabled: z.boolean(),
+        minTier: z.enum(RISK_TIERS),
+        // The reviewer's own chain, for its review tasks and plan call.
+        models: modelChain,
+        effort,
+    })
+        .partial()
+        .strict())
+        .default({}),
+    roles: z
+        .partialRecord(z.enum(AGENT_ROLES), z.object({ models: modelChain, effort }).partial().strict())
+        .default({}),
+    pluginSettings: z.record(z.string(), z.unknown()).default({}),
+    providers: z.record(z.string().regex(/^[a-z][a-z0-9-]{0,39}$/), providerSchema).default({}),
+    extends: z.string().min(1).optional(),
+})
+    .strict();
+export const CONFIG_SCHEMA_ID = "https://ocra.majincheng.com/schema/config.v1.json";
+// JSON Schema (draft 2020-12) of .ocra/config.json, for editors: what a
+// file may say, so defaults are optional and model chains take either form.
+export function configJsonSchema() {
+    const generated = z.toJSONSchema(configSchema, { target: "draft-2020-12", io: "input" });
+    const { $schema, ...rest } = generated;
+    return {
+        $schema,
+        $id: CONFIG_SCHEMA_ID,
+        title: "ocra configuration",
+        description: "The .ocra/config.json file of a repository, or a file passed with --config. Unknown keys are rejected.",
+        ...rest,
+    };
+}
+//# sourceMappingURL=schema.js.map

package/dist/config/settings.d.ts

@@ -0,0 +1,37 @@
+import { type SourcedRule } from "@open-cr-agent/core";
+import { z } from "zod";
+import { configSchema } from "./schema.js";
+type FileSettings = z.output<typeof configSchema>;
+export type Settings = FileSettings & {
+    rules: SourcedRule[];
+    ultra: boolean;
+};
+type SettingSource = "shared" | "file" | "env" | "account" | "flag";
+export type LayerSettings = {
+    [K in keyof Settings]?: Settings[K];
+};
+export interface SettingsLayer {
+    source: SettingSource;
+    settings: LayerSettings;
+    under?: boolean;
+}
+export type SettingSources = Record<string, SettingSource[]>;
+export declare const layerSchema: z.ZodType<Omit<LayerSettings, "rules" | "ultra">>;
+/** The layers, earliest first, over ocra's defaults, and where each setting came from. */
+export declare function resolveSettings(layers: readonly SettingsLayer[]): {
+    settings: Settings;
+    sources: SettingSources;
+};
+export interface ListedSetting {
+    key: string;
+    value?: unknown;
+    sources: SettingSource[];
+}
+/**
+ * The settings --plan lists, in its order, with their sources. A setting
+ * only a command-line flag set is the flag's, not a setting, and is left
+ * out.
+ */
+export declare function listSettings(settings: Settings, sources: SettingSources): ListedSetting[];
+export {};
+//# sourceMappingURL=settings.d.ts.map

package/dist/config/settings.js

@@ -0,0 +1,133 @@
+import { isDeepStrictEqual } from "node:util";
+import { MODEL_TIERS, OcraError } from "@open-cr-agent/core";
+import { z } from "zod";
+import { configSchema } from "./schema.js";
+const ALL = ["shared", "file", "env", "account"];
+const NOT_ENV = ["shared", "file", "account"];
+const ALWAYS = { list: "always" };
+// How each setting merges, which layers may set it, and how --plan lists
+// it, in --plan's order. A shared configuration is fetched from outside the
+// repository, so it never names plugins or a runtime; the account never
+// moves code or keys (providers, extends) or decides whose comments are
+// trusted (github). The layers' parsers refuse these with a warning; here
+// they are a broken invariant.
+const MERGE = {
+    runtime: { merge: "replace", from: ["file", "account"], plan: ALWAYS },
+    models: { merge: "entries", from: ALL, plan: { list: "always", entries: MODEL_TIERS } },
+    effort: { merge: "entries", from: ALL, plan: { list: "always", entries: MODEL_TIERS } },
+    reviewers: { merge: "entries", from: NOT_ENV, plan: { list: "set" } },
+    roles: { merge: "entries", from: NOT_ENV, plan: { list: "set" } },
+    concurrency: { merge: "replace", from: NOT_ENV, plan: ALWAYS },
+    taskTimeoutMinutes: { merge: "replace", from: NOT_ENV, plan: ALWAYS },
+    runTimeoutMinutes: { merge: "replace", from: NOT_ENV, plan: ALWAYS },
+    maxCostUsd: { merge: "replace", from: NOT_ENV, plan: ALWAYS },
+    maxTasks: { merge: "replace", from: NOT_ENV, plan: ALWAYS },
+    verify: { merge: "replace", from: NOT_ENV, plan: ALWAYS },
+    judge: { merge: "replace", from: NOT_ENV, plan: ALWAYS },
+    sampling: { merge: "replace", from: ["file", "account"], plan: ALWAYS },
+    include: { merge: "concat", from: NOT_ENV, plan: ALWAYS },
+    exclude: { merge: "concat", from: NOT_ENV, plan: ALWAYS },
+    rules: {
+        merge: "concat",
+        from: ["shared", "account"],
+        // Where each rule applies and whose it is; the rule's text can be long.
+        plan: {
+            list: "always",
+            show: (rules) => rules.map(({ path, source }) => ({ path, source })),
+        },
+    },
+    ultra: { merge: "replace", from: ["account", "flag"], plan: { list: "set" } },
+    $schema: { merge: "replace", from: ["shared", "file"] },
+    github: { merge: "entries", from: ["shared", "file"] },
+    plugins: { merge: "replace", from: ["file"] },
+    pluginSettings: { merge: "replace", from: ["file"] },
+    providers: { merge: "entries", from: ["shared", "file"] },
+    extends: { merge: "replace", from: ["file"] },
+};
+// The configuration file's schema without its defaults, so a layer holds
+// only what it sets; unknown keys are refused as in the file.
+export const layerSchema = z
+    .object(Object.fromEntries(Object.entries(configSchema.shape).map(([key, schema]) => [
+    key,
+    (schema instanceof z.ZodDefault ? schema.unwrap() : schema).optional(),
+])))
+    .strict();
+/** The layers, earliest first, over ocra's defaults, and where each setting came from. */
+export function resolveSettings(layers) {
+    const merged = { ...configSchema.parse({}), rules: [], ultra: false };
+    const sources = {};
+    const record = (name, source) => {
+        const from = sources[name] ?? [];
+        if (!from.includes(source))
+            sources[name] = [...from, source];
+    };
+    for (const { source, settings, under = false } of layers) {
+        for (const [key, value] of Object.entries(settings)) {
+            if (value === undefined)
+                continue;
+            const rule = MERGE[key];
+            if (!rule.from.includes(source)) {
+                throw new OcraError("INTERNAL", `the ${source} settings may not set ${key}`);
+            }
+            if (rule.merge === "replace") {
+                if (under && sources[key])
+                    continue;
+                merged[key] = value;
+                sources[key] = [source];
+            }
+            else if (rule.merge === "entries") {
+                const entries = { ...merged[key] };
+                for (const [entry, setting] of Object.entries(value)) {
+                    const name = `${key}.${entry}`;
+                    if (setting === undefined || (under && sources[name]))
+                        continue;
+                    entries[entry] = setting;
+                    sources[name] = [source];
+                }
+                merged[key] = entries;
+            }
+            else {
+                const current = merged[key];
+                const added = under
+                    ? value.filter((v) => !current.some((c) => isDeepStrictEqual(c, v)))
+                    : value;
+                if (added.length === 0)
+                    continue;
+                merged[key] = [...current, ...added];
+                record(key, source);
+            }
+        }
+    }
+    return { settings: merged, sources };
+}
+/**
+ * The settings --plan lists, in its order, with their sources. A setting
+ * only a command-line flag set is the flag's, not a setting, and is left
+ * out.
+ */
+export function listSettings(settings, sources) {
+    const listed = [];
+    for (const [key, rule] of Object.entries(MERGE)) {
+        const plan = rule.plan;
+        if (!plan)
+            continue;
+        const value = settings[key];
+        const add = (name, shown, always) => {
+            const from = (sources[name] ?? []).filter((source) => source !== "flag");
+            if (from.length === 0 && !always)
+                return;
+            listed.push(from.length === 0 ? { key: name, sources: [] } : { key: name, value: shown, sources: from });
+        };
+        if (rule.merge === "entries") {
+            const map = value;
+            for (const entry of plan.entries ?? Object.keys(map)) {
+                add(`${key}.${entry}`, map[entry], plan.list === "always");
+            }
+        }
+        else {
+            add(key, plan.show ? plan.show(value) : value, plan.list === "always");
+        }
+    }
+    return listed;
+}
+//# sourceMappingURL=settings.js.map

package/dist/config/user-dir.d.ts

@@ -0,0 +1,3 @@
+/** ~/.config/ocra ($XDG_CONFIG_HOME/ocra), or %APPDATA%\ocra on Windows: this machine's own. */
+export declare function ocraConfigDir(env: Readonly<Record<string, string | undefined>>): string;
+//# sourceMappingURL=user-dir.d.ts.map

package/dist/config/user-dir.js

@@ -0,0 +1,10 @@
+import { homedir } from "node:os";
+import { join } from "node:path";
+/** ~/.config/ocra ($XDG_CONFIG_HOME/ocra), or %APPDATA%\ocra on Windows: this machine's own. */
+export function ocraConfigDir(env) {
+    const base = process.platform === "win32"
+        ? (env.APPDATA ?? join(homedir(), "AppData", "Roaming"))
+        : (env.XDG_CONFIG_HOME ?? join(homedir(), ".config"));
+    return join(base, "ocra");
+}
+//# sourceMappingURL=user-dir.js.map

package/dist/index.d.ts

@@ -1,2 +1,2 @@
-export { run } from "./run.js";
+export declare function run(argv: readonly string[]): Promise<number>;
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -1,2 +1,11 @@
-export { run } from "./run.js";
+// The public API of @open-cr-agent/cli, a contract under the 0.x rule
+// (manual: Embedding, Stability); etc/cli.api.md records it. What the
+// other workspace packages need beyond this comes from
+// "@open-cr-agent/cli/internal", which is not a contract.
+import { defaultDeps, run as runWith } from "./run.js";
+// The `ocra` command with its arguments (no node or script path), writing
+// to stdout and stderr; resolves to the exit code.
+export function run(argv) {
+    return runWith([...argv], process.stdout, process.stderr, defaultDeps());
+}
 //# sourceMappingURL=index.js.map