@oxagen/cli 0.5.0 → 0.6.1

package/dist/settings/resolve.d.ts

@@ -0,0 +1,37 @@
+import { type OxagenSettings } from "./schema.js";
+export type SettingsScope = "user" | "project" | "local";
+export interface ResolveSettingsOptions {
+    /** Working directory / project root (where `.oxagen/` lives). Defaults to process.cwd(). */
+    cwd?: string;
+    /** Override the user settings file path (testing). */
+    userSettingsPath?: string;
+    /** Override the project directory name (testing). Default ".oxagen". */
+    projectDirName?: string;
+    /** Skip the per-process cache (testing / after a write). */
+    noCache?: boolean;
+}
+export interface ResolvedScopeFile {
+    scope: SettingsScope;
+    path: string;
+    /** Present only when the file exists and parsed successfully. */
+    settings?: OxagenSettings;
+    /** Present when the file exists but failed schema validation. */
+    error?: string;
+}
+export interface ResolvedSettings {
+    /** Merged, env-expanded settings across every scope that exists. */
+    settings: OxagenSettings;
+    /** Per-scope diagnostics (path, parsed body, or error) for `oxagen settings`. */
+    scopes: ResolvedScopeFile[];
+}
+/** The three scope file paths for a given project root, in precedence order. */
+export declare function getScopePaths(opts?: ResolveSettingsOptions): Record<SettingsScope, string>;
+/** Clear the per-process resolution cache (after a write, or in tests). */
+export declare function clearSettingsCache(): void;
+/**
+ * Resolve the effective settings by loading and merging every scope that exists.
+ * Results are cached per project root for the life of the process (settings do
+ * not change mid-run); pass `noCache` to bypass.
+ */
+export declare function loadSettings(opts?: ResolveSettingsOptions): ResolvedSettings;
+//# sourceMappingURL=resolve.d.ts.map

package/dist/settings/resolve.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve.d.ts","sourceRoot":"","sources":["../../src/settings/resolve.ts"],"names":[],"mappings":"AAyBA,OAAO,EAEL,KAAK,cAAc,EAIpB,MAAM,aAAa,CAAC;AAErB,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG,SAAS,GAAG,OAAO,CAAC;AAEzD,MAAM,WAAW,sBAAsB;IACrC,4FAA4F;IAC5F,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,sDAAsD;IACtD,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,wEAAwE;IACxE,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,4DAA4D;IAC5D,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,aAAa,CAAC;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,iEAAiE;IACjE,QAAQ,CAAC,EAAE,cAAc,CAAC;IAC1B,iEAAiE;IACjE,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,gBAAgB;IAC/B,oEAAoE;IACpE,QAAQ,EAAE,cAAc,CAAC;IACzB,iFAAiF;IACjF,MAAM,EAAE,iBAAiB,EAAE,CAAC;CAC7B;AAQD,gFAAgF;AAChF,wBAAgB,aAAa,CAAC,IAAI,GAAE,sBAA2B,GAAG,MAAM,CACtE,aAAa,EACb,MAAM,CACP,CAQA;AAgHD,2EAA2E;AAC3E,wBAAgB,kBAAkB,IAAI,IAAI,CAEzC;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,IAAI,GAAE,sBAA2B,GAAG,gBAAgB,CAoBhF"}

package/dist/settings/resolve.js

@@ -0,0 +1,169 @@
+/**
+ * resolve.ts — Loads and merges the unified `settings.json` across three scopes.
+ *
+ * Precedence (lowest → highest), identical to the MCP config layering and to
+ * Claude Code:
+ *   1. User (global):   ~/.config/oxagen/settings.json
+ *   2. Project (shared): <projectRoot>/.oxagen/settings.json
+ *   3. Local (personal): <projectRoot>/.oxagen/settings.local.json
+ *
+ * Merge rules:
+ *   - scalars (model, apiUrl, $schema):       higher scope wins
+ *   - env:                                    keyed merge; higher scope wins per key
+ *   - permissions.defaultMode/defaultMcpPolicy: higher scope wins
+ *   - permissions.allow/deny:                 concatenated (deduped), higher scope last
+ *   - permissions.mcpServers, mcpServers, toolVisibility: keyed replace
+ *   - hooks:                                  per-event matcher lists concatenated
+ *   - unknown (forward-compat) keys:          higher scope wins (shallow)
+ *
+ * `${VAR}` references in any string value are expanded from the environment at
+ * resolution time (reusing @oxagen/mcp-config's expander).
+ */
+import { readFileSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+import { expandEnvVars } from "@oxagen/mcp-config/resolve";
+import { oxagenSettingsSchema, } from "./schema.js";
+const DEFAULT_PROJECT_DIR = ".oxagen";
+function userSettingsFile() {
+    return join(homedir(), ".config", "oxagen", "settings.json");
+}
+/** The three scope file paths for a given project root, in precedence order. */
+export function getScopePaths(opts = {}) {
+    const root = opts.cwd ?? process.cwd();
+    const dir = opts.projectDirName ?? DEFAULT_PROJECT_DIR;
+    return {
+        user: opts.userSettingsPath ?? userSettingsFile(),
+        project: join(root, dir, "settings.json"),
+        local: join(root, dir, "settings.local.json"),
+    };
+}
+function loadScope(scope, path) {
+    if (!existsSync(path))
+        return { scope, path };
+    let raw;
+    try {
+        raw = readFileSync(path, "utf8");
+    }
+    catch (err) {
+        return { scope, path, error: err instanceof Error ? err.message : String(err) };
+    }
+    let json;
+    try {
+        json = JSON.parse(raw);
+    }
+    catch (err) {
+        return {
+            scope,
+            path,
+            error: `invalid JSON: ${err instanceof Error ? err.message : String(err)}`,
+        };
+    }
+    const parsed = oxagenSettingsSchema.safeParse(json);
+    if (!parsed.success) {
+        return { scope, path, error: parsed.error.issues.map((i) => `${i.path.join(".")}: ${i.message}`).join("; ") };
+    }
+    return { scope, path, settings: parsed.data };
+}
+// ── Merge helpers ───────────────────────────────────────────────────────────
+function dedupe(values) {
+    return [...new Set(values)];
+}
+function mergePermissions(base, overlay) {
+    if (!base)
+        return overlay;
+    if (!overlay)
+        return base;
+    return {
+        defaultMode: overlay.defaultMode ?? base.defaultMode,
+        allow: base.allow || overlay.allow
+            ? dedupe([...(base.allow ?? []), ...(overlay.allow ?? [])])
+            : undefined,
+        deny: base.deny || overlay.deny
+            ? dedupe([...(base.deny ?? []), ...(overlay.deny ?? [])])
+            : undefined,
+        defaultMcpPolicy: overlay.defaultMcpPolicy ?? base.defaultMcpPolicy,
+        mcpServers: base.mcpServers || overlay.mcpServers
+            ? { ...(base.mcpServers ?? {}), ...(overlay.mcpServers ?? {}) }
+            : undefined,
+    };
+}
+function mergeHooks(base, overlay) {
+    if (!base)
+        return overlay;
+    if (!overlay)
+        return base;
+    const concat = (a, b) => a || b ? [...(a ?? []), ...(b ?? [])] : undefined;
+    return {
+        SessionStart: concat(base.SessionStart, overlay.SessionStart),
+        PreToolUse: concat(base.PreToolUse, overlay.PreToolUse),
+        PostToolUse: concat(base.PostToolUse, overlay.PostToolUse),
+    };
+}
+/** Keys with bespoke merge logic; everything else is shallow "overlay wins". */
+const STRUCTURED_KEYS = new Set([
+    "env",
+    "permissions",
+    "hooks",
+    "mcpServers",
+    "toolVisibility",
+]);
+function mergeSettings(base, overlay) {
+    const merged = { ...base };
+    // Pass-through + scalar keys: overlay wins (skip the structured ones below).
+    for (const [key, value] of Object.entries(overlay)) {
+        if (value === undefined)
+            continue;
+        if (STRUCTURED_KEYS.has(key))
+            continue;
+        merged[key] = value;
+    }
+    if (base.env || overlay.env) {
+        merged.env = { ...(base.env ?? {}), ...(overlay.env ?? {}) };
+    }
+    merged.permissions = mergePermissions(base.permissions, overlay.permissions);
+    merged.hooks = mergeHooks(base.hooks, overlay.hooks);
+    if (base.mcpServers || overlay.mcpServers) {
+        merged.mcpServers = { ...(base.mcpServers ?? {}), ...(overlay.mcpServers ?? {}) };
+    }
+    if (base.toolVisibility || overlay.toolVisibility) {
+        merged.toolVisibility = {
+            ...(base.toolVisibility ?? {}),
+            ...(overlay.toolVisibility ?? {}),
+        };
+    }
+    return merged;
+}
+// ── Public API ──────────────────────────────────────────────────────────────
+const cache = new Map();
+/** Clear the per-process resolution cache (after a write, or in tests). */
+export function clearSettingsCache() {
+    cache.clear();
+}
+/**
+ * Resolve the effective settings by loading and merging every scope that exists.
+ * Results are cached per project root for the life of the process (settings do
+ * not change mid-run); pass `noCache` to bypass.
+ */
+export function loadSettings(opts = {}) {
+    const paths = getScopePaths(opts);
+    const cacheKey = `${paths.user}|${paths.project}|${paths.local}`;
+    if (!opts.noCache) {
+        const hit = cache.get(cacheKey);
+        if (hit)
+            return hit;
+    }
+    const order = ["user", "project", "local"];
+    const scopes = order.map((scope) => loadScope(scope, paths[scope]));
+    let merged = {};
+    for (const sc of scopes) {
+        if (sc.settings)
+            merged = mergeSettings(merged, sc.settings);
+    }
+    const expanded = expandEnvVars(merged);
+    const result = { settings: expanded, scopes };
+    if (!opts.noCache)
+        cache.set(cacheKey, result);
+    return result;
+}
+//# sourceMappingURL=resolve.js.map

package/dist/settings/resolve.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve.js","sourceRoot":"","sources":["../../src/settings/resolve.ts"],"names":[],"mappings":"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"}

package/dist/settings/runtime.d.ts

@@ -0,0 +1,28 @@
+/**
+ * runtime.ts — Glue that makes `settings.json` drive the running CLI.
+ *
+ * The model and apiUrl resolvers (model.ts, config.ts) and the gateway key
+ * resolver (agent/env.ts) already consult environment variables. Rather than
+ * thread settings through each of them, we project the relevant settings into
+ * `process.env` once at startup — and only for vars the shell has not already
+ * set, so an explicit `OXAGEN_MODEL=… oxagen` or a shell export always wins.
+ *
+ * This keeps the wiring additive and cycle-free: those resolvers are untouched,
+ * yet `settings.json` now feeds them.
+ */
+import { type ResolveSettingsOptions } from "./resolve.js";
+export interface AppliedSettingsEnv {
+    /** Names of env vars populated from settings.env. */
+    envKeys: string[];
+    /** Whether OXAGEN_API_URL was set from settings.apiUrl. */
+    apiUrl: boolean;
+    /** Whether OXAGEN_MODEL was set from settings.model. */
+    model: boolean;
+}
+/**
+ * Project `env`, `apiUrl`, and `model` from the resolved settings into
+ * `process.env` (filling only unset vars). Call once at CLI startup. Returns
+ * what was applied (useful for `--verbose` / diagnostics).
+ */
+export declare function applySettingsToEnv(opts?: ResolveSettingsOptions): AppliedSettingsEnv;
+//# sourceMappingURL=runtime.d.ts.map

package/dist/settings/runtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../../src/settings/runtime.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,EAAgB,KAAK,sBAAsB,EAAE,MAAM,cAAc,CAAC;AAQzE,MAAM,WAAW,kBAAkB;IACjC,qDAAqD;IACrD,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,2DAA2D;IAC3D,MAAM,EAAE,OAAO,CAAC;IAChB,wDAAwD;IACxD,KAAK,EAAE,OAAO,CAAC;CAChB;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,GAAE,sBAA2B,GAAG,kBAAkB,CAwBxF"}

package/dist/settings/runtime.js

@@ -0,0 +1,45 @@
+/**
+ * runtime.ts — Glue that makes `settings.json` drive the running CLI.
+ *
+ * The model and apiUrl resolvers (model.ts, config.ts) and the gateway key
+ * resolver (agent/env.ts) already consult environment variables. Rather than
+ * thread settings through each of them, we project the relevant settings into
+ * `process.env` once at startup — and only for vars the shell has not already
+ * set, so an explicit `OXAGEN_MODEL=… oxagen` or a shell export always wins.
+ *
+ * This keeps the wiring additive and cycle-free: those resolvers are untouched,
+ * yet `settings.json` now feeds them.
+ */
+import { loadSettings } from "./resolve.js";
+/** True when an env var is effectively unset (so settings may fill it). */
+function isUnset(name) {
+    const v = process.env[name];
+    return v === undefined || v === "";
+}
+/**
+ * Project `env`, `apiUrl`, and `model` from the resolved settings into
+ * `process.env` (filling only unset vars). Call once at CLI startup. Returns
+ * what was applied (useful for `--verbose` / diagnostics).
+ */
+export function applySettingsToEnv(opts = {}) {
+    const { settings } = loadSettings(opts);
+    const envKeys = [];
+    for (const [key, value] of Object.entries(settings.env ?? {})) {
+        if (isUnset(key)) {
+            process.env[key] = value;
+            envKeys.push(key);
+        }
+    }
+    let apiUrl = false;
+    if (settings.apiUrl && isUnset("OXAGEN_API_URL")) {
+        process.env["OXAGEN_API_URL"] = settings.apiUrl;
+        apiUrl = true;
+    }
+    let model = false;
+    if (settings.model && isUnset("OXAGEN_MODEL")) {
+        process.env["OXAGEN_MODEL"] = settings.model;
+        model = true;
+    }
+    return { envKeys, apiUrl, model };
+}
+//# sourceMappingURL=runtime.js.map

package/dist/settings/runtime.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.js","sourceRoot":"","sources":["../../src/settings/runtime.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,EAAE,YAAY,EAA+B,MAAM,cAAc,CAAC;AAEzE,2EAA2E;AAC3E,SAAS,OAAO,CAAC,IAAY;IAC3B,MAAM,CAAC,GAAG,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAC5B,OAAO,CAAC,KAAK,SAAS,IAAI,CAAC,KAAK,EAAE,CAAC;AACrC,CAAC;AAWD;;;;GAIG;AACH,MAAM,UAAU,kBAAkB,CAAC,OAA+B,EAAE;IAClE,MAAM,EAAE,QAAQ,EAAE,GAAG,YAAY,CAAC,IAAI,CAAC,CAAC;IACxC,MAAM,OAAO,GAAa,EAAE,CAAC;IAE7B,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,QAAQ,CAAC,GAAG,IAAI,EAAE,CAAC,EAAE,CAAC;QAC9D,IAAI,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC;YACjB,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;YACzB,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QACpB,CAAC;IACH,CAAC;IAED,IAAI,MAAM,GAAG,KAAK,CAAC;IACnB,IAAI,QAAQ,CAAC,MAAM,IAAI,OAAO,CAAC,gBAAgB,CAAC,EAAE,CAAC;QACjD,OAAO,CAAC,GAAG,CAAC,gBAAgB,CAAC,GAAG,QAAQ,CAAC,MAAM,CAAC;QAChD,MAAM,GAAG,IAAI,CAAC;IAChB,CAAC;IAED,IAAI,KAAK,GAAG,KAAK,CAAC;IAClB,IAAI,QAAQ,CAAC,KAAK,IAAI,OAAO,CAAC,cAAc,CAAC,EAAE,CAAC;QAC9C,OAAO,CAAC,GAAG,CAAC,cAAc,CAAC,GAAG,QAAQ,CAAC,KAAK,CAAC;QAC7C,KAAK,GAAG,IAAI,CAAC;IACf,CAAC;IAED,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC;AACpC,CAAC"}