@moxxy/config 0.27.0

package/src/config-writer.test.ts

@@ -0,0 +1,52 @@
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { promises as fs } from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { setConfigValue } from './config-writer.js';
+
+let tmp: string;
+let prevHome: string | undefined;
+
+beforeEach(async () => {
+  tmp = await fs.mkdtemp(path.join(os.tmpdir(), 'moxxy-cfgw-'));
+  prevHome = process.env.MOXXY_HOME;
+  process.env.MOXXY_HOME = path.join(tmp, 'home');
+});
+
+afterEach(async () => {
+  if (prevHome === undefined) delete process.env.MOXXY_HOME;
+  else process.env.MOXXY_HOME = prevHome;
+  await fs.rm(tmp, { recursive: true, force: true });
+});
+
+describe('setConfigValue', () => {
+  it('creates the user config and sets a nested path', async () => {
+    const res = await setConfigValue({
+      scope: 'user',
+      cwd: tmp,
+      path: 'context.reasoning',
+      value: true,
+    });
+    expect(res.config.context?.reasoning).toBe(true);
+    const text = await fs.readFile(res.path, 'utf8');
+    expect(text).toContain('reasoning: true');
+  });
+
+  it('preserves comments on existing YAML', async () => {
+    const home = path.join(tmp, 'home');
+    await fs.mkdir(home, { recursive: true });
+    const file = path.join(home, 'config.yaml');
+    await fs.writeFile(file, '# keep me\ncontext:\n  caching: true # inline note\n');
+    await setConfigValue({ scope: 'user', cwd: tmp, path: 'tui.hints', value: false });
+    const text = await fs.readFile(file, 'utf8');
+    expect(text).toContain('# keep me');
+    expect(text).toContain('# inline note');
+    expect(text).toContain('hints: false');
+  });
+
+  it('rejects writes that would produce a schema-invalid config', async () => {
+    await expect(
+      setConfigValue({ scope: 'user', cwd: tmp, path: 'tui.theme', value: 'neon' }),
+    ).rejects.toThrow(/invalid config/);
+  });
+});

package/src/config-writer.ts

@@ -0,0 +1,88 @@
+import { promises as fs } from 'node:fs';
+import * as path from 'node:path';
+import { createMutex } from '@moxxy/sdk';
+import { moxxyPath, writeFileAtomic } from '@moxxy/sdk/server';
+import { findUpward } from './loader.js';
+import { moxxyConfigSchema, type MoxxyConfig } from './schema.js';
+
+/**
+ * The ONE schema-validated, comment-preserving dot-path config writer. Both
+ * the model-facing `config_set` tool (plugin.ts) and UI surfaces (the TUI's
+ * /settings panel) write through here, sharing a single mutex, so concurrent
+ * writers can't interleave and no surface can persist a structurally-invalid
+ * config.
+ */
+export type ConfigScope = 'user' | 'project';
+
+const USER_YAML = (): string => moxxyPath('config.yaml');
+
+// YAML names only — the writer round-trips documents with `setIn`, which it
+// can't do for the .ts/.js configs loadConfig also honors.
+const PROJECT_YAML_NAMES = ['moxxy.config.yaml', 'moxxy.config.yml'] as const;
+
+/** Serializes every config write in this process (tool + UI surfaces). */
+export const configWriteMutex = createMutex();
+
+export async function findScopePath(scope: ConfigScope, cwd: string): Promise<string | null> {
+  if (scope === 'user') {
+    const yaml = USER_YAML();
+    try {
+      await fs.access(yaml);
+      return yaml;
+    } catch {
+      return null;
+    }
+  }
+  return findUpward(cwd, PROJECT_YAML_NAMES);
+}
+
+export function scopeDefaultPath(scope: ConfigScope, cwd: string): string {
+  return scope === 'user' ? USER_YAML() : path.join(cwd, 'moxxy.config.yaml');
+}
+
+export function parseDotPath(p: string): Array<string | number> {
+  return p.split('.').map((seg) => (/^\d+$/.test(seg) ? Number(seg) : seg));
+}
+
+export interface SetConfigValueOptions {
+  readonly scope: ConfigScope;
+  readonly cwd: string;
+  /** Dot path into the config (e.g. `context.reasoning`, `tui.hints`). */
+  readonly path: string;
+  /** The ALREADY-PARSED value to set (callers own string→value parsing). */
+  readonly value: unknown;
+}
+
+export interface SetConfigValueResult {
+  /** The file that was written. */
+  readonly path: string;
+  /** The full validated config snapshot after the write. */
+  readonly config: MoxxyConfig;
+}
+
+export async function setConfigValue(opts: SetConfigValueOptions): Promise<SetConfigValueResult> {
+  return configWriteMutex.run(async () => {
+    const target = (await findScopePath(opts.scope, opts.cwd)) ?? scopeDefaultPath(opts.scope, opts.cwd);
+    await fs.mkdir(path.dirname(target), { recursive: true });
+    const yamlMod = (await import('yaml')) as typeof import('yaml');
+    let text = '';
+    try {
+      text = await fs.readFile(target, 'utf8');
+    } catch {
+      /* new file */
+    }
+    const doc = yamlMod.parseDocument(text);
+    doc.setIn(parseDotPath(opts.path), opts.value);
+    const candidate = String(doc);
+    const parsed = yamlMod.parse(candidate);
+    const validated = moxxyConfigSchema.safeParse(parsed ?? {});
+    if (!validated.success) {
+      throw new Error(
+        `config write to '${opts.path}' would produce an invalid config:\n` +
+          JSON.stringify(validated.error.issues, null, 2),
+      );
+    }
+    await writeFileAtomic(target, candidate);
+    return { path: target, config: validated.data };
+  });
+}

package/src/define.ts

@@ -0,0 +1,19 @@
+import type { MoxxyConfig } from './schema.js';
+
+/**
+ * Typed configuration factory. Use in `moxxy.config.ts`:
+ *
+ *   import { defineConfig } from '@moxxy/config';
+ *
+ *   export default defineConfig({
+ *     provider: { name: 'anthropic', model: 'claude-sonnet-4-6' },
+ *     plugins: {
+ *       '@moxxy/plugin-mcp': { enabled: true, options: { servers: [...] } },
+ *       '@acme/moxxy-plugin-shell': { enabled: false },
+ *     },
+ *     watcher: 'auto',
+ *   });
+ */
+export function defineConfig(config: MoxxyConfig): MoxxyConfig {
+  return config;
+}

package/src/index.ts

@@ -0,0 +1,64 @@
+export { defineConfig } from './define.js';
+export { loadConfig, type LoadConfigOptions, type LoadedConfig } from './loader.js';
+export { mergeConfigs } from './merge.js';
+export {
+  buildConfigPlugin,
+  type ConfigApplier,
+  type ConfigApplyResult,
+} from './plugin.js';
+export {
+  moxxyConfigSchema,
+  pluginSettingsSchema,
+  permissionsConfigSchema,
+  embeddingsConfigSchema,
+  securityConfigSchema,
+  watcherModeSchema,
+  type MoxxyConfig,
+  type PluginSettings,
+  type PermissionsConfig,
+  type EmbeddingsConfig,
+  type SecurityConfig,
+  type WatcherMode,
+} from './schema.js';
+export {
+  pluginsTreeSchema,
+  providerSlotSchema,
+  providerItemSchema,
+  categorySlotSchema,
+  PLUGIN_CATEGORY_KEYS,
+  type PluginsTree,
+  type ProviderSlot,
+  type ProviderItem,
+  type CategorySlot,
+  type PluginCategoryKey,
+} from './plugins-tree-schema.js';
+// Comment-preserving writers for ~/.moxxy/config.yaml — the single store that
+// replaced ~/.moxxy/preferences.json (runtime provider/mode/model/disabled).
+export {
+  applyInitConfig,
+  clearPluginState,
+  defaultUserConfigPath,
+  isPluginDisabled,
+  loadActiveModel,
+  loadActiveProvider,
+  loadDisabledPackageNames,
+  loadDisabledProviders,
+  loadProviderItems,
+  removeProviderItem,
+  setCategoryDefault,
+  setPluginEnabled,
+  setProviderEnabled,
+  setProviderItemConfig,
+  setProviderModel,
+  type ProviderItemState,
+  type InitConfigSelections,
+  type UserConfigOptions,
+} from './user-config.js';
+
+export {
+  configWriteMutex,
+  setConfigValue,
+  type ConfigScope,
+  type SetConfigValueOptions,
+  type SetConfigValueResult,
+} from './config-writer.js';

package/src/loader.test.ts

@@ -0,0 +1,122 @@
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { promises as fs } from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { loadConfig } from './loader.js';
+
+let tmp: string;
+
+beforeEach(async () => {
+  tmp = await fs.mkdtemp(path.join(os.tmpdir(), 'mox-config-'));
+});
+afterEach(async () => {
+  await fs.rm(tmp, { recursive: true, force: true });
+});
+
+describe('loadConfig', () => {
+  it('returns empty config when no file is found', async () => {
+    const result = await loadConfig({ cwd: tmp, skipUser: true });
+    expect(result.config).toEqual({});
+    expect(result.sources).toEqual([]);
+  });
+
+  it('loads a moxxy.config.js from cwd', async () => {
+    await fs.writeFile(
+      path.join(tmp, 'moxxy.config.js'),
+      `export default { plugins: { provider: { default: 'anthropic', items: { anthropic: { model: 'sonnet' } } } } };`,
+    );
+    const result = await loadConfig({ cwd: tmp, skipUser: true });
+    expect(result.config.plugins?.provider?.default).toBe('anthropic');
+    expect(result.config.plugins?.provider?.items?.anthropic?.model).toBe('sonnet');
+    expect(result.sources[0]?.scope).toBe('project');
+  });
+
+  it('walks upward to find moxxy.config.js', async () => {
+    const nested = path.join(tmp, 'a/b/c');
+    await fs.mkdir(nested, { recursive: true });
+    await fs.writeFile(
+      path.join(tmp, 'moxxy.config.js'),
+      `export default { plugins: { mode: { default: 'default' } } };`,
+    );
+    const result = await loadConfig({ cwd: nested, skipUser: true });
+    expect(result.config.plugins?.mode?.default).toBe('default');
+  });
+
+  it('honors explicitPath over upward search', async () => {
+    await fs.writeFile(
+      path.join(tmp, 'moxxy.config.js'),
+      `export default { plugins: { mode: { default: 'default' } } };`,
+    );
+    const custom = path.join(tmp, 'custom.config.js');
+    await fs.writeFile(custom, `export default { plugins: { mode: { default: 'research' } } };`);
+    const result = await loadConfig({ cwd: tmp, explicitPath: custom, skipUser: true });
+    expect(result.config.plugins?.mode?.default).toBe('research');
+    expect(result.sources[0]?.scope).toBe('explicit');
+  });
+
+  it('rejects a config whose schema is invalid', async () => {
+    await fs.writeFile(
+      path.join(tmp, 'moxxy.config.js'),
+      `export default { plugins: { provider: { default: 42 } } };`,
+    );
+    await expect(loadConfig({ cwd: tmp, skipUser: true })).rejects.toThrow(/Invalid moxxy config/);
+  });
+
+  it('rejects a config with no default export', async () => {
+    await fs.writeFile(
+      path.join(tmp, 'moxxy.config.js'),
+      `export const config = {};`,
+    );
+    await expect(loadConfig({ cwd: tmp, skipUser: true })).rejects.toThrow(/default-export/);
+  });
+
+  it('reloads a rewritten .mjs config freshly even on rapid successive loads', async () => {
+    // The first import is plain (single module-registry entry, no per-load
+    // cache-buster → no leak); subsequent reloads append a monotonic-counter
+    // buster so back-to-back reloads in the same millisecond can't return the
+    // stale cached module. Use .mjs so it goes through importJsConfig, not jiti.
+    const file = path.join(tmp, 'moxxy.config.mjs');
+    await fs.writeFile(file, `export default { plugins: { mode: { default: 'default' } } };`);
+    const first = await loadConfig({ cwd: tmp, skipUser: true });
+    expect(first.config.plugins?.mode?.default).toBe('default');
+
+    await fs.writeFile(file, `export default { plugins: { mode: { default: 'goal' } } };`);
+    // Two reloads with no delay between them (same-ms risk).
+    const [a, b] = await Promise.all([
+      loadConfig({ cwd: tmp, skipUser: true }),
+      loadConfig({ cwd: tmp, skipUser: true }),
+    ]);
+    expect(a.config.plugins?.mode?.default).toBe('goal');
+    expect(b.config.plugins?.mode?.default).toBe('goal');
+  });
+
+  it('resolves each .ts config\'s relative imports against ITS OWN dir (jiti cache keyed by cwd)', async () => {
+    // Two projects in two dirs, each with a .ts config that imports a sibling
+    // module. A jiti instance binds its resolution base to the dir it was
+    // created with; a single shared instance would resolve the SECOND config's
+    // `./marker` against the FIRST dir, picking up the wrong value.
+    const dirA = await fs.mkdtemp(path.join(os.tmpdir(), 'mox-jiti-a-'));
+    const dirB = await fs.mkdtemp(path.join(os.tmpdir(), 'mox-jiti-b-'));
+    try {
+      await fs.writeFile(path.join(dirA, 'marker.ts'), `export const marker = 'from-A';`);
+      await fs.writeFile(
+        path.join(dirA, 'moxxy.config.ts'),
+        `import { marker } from './marker';\nexport default { plugins: { provider: { default: 'x', items: { x: { model: marker } } } } };`,
+      );
+      await fs.writeFile(path.join(dirB, 'marker.ts'), `export const marker = 'from-B';`);
+      await fs.writeFile(
+        path.join(dirB, 'moxxy.config.ts'),
+        `import { marker } from './marker';\nexport default { plugins: { provider: { default: 'x', items: { x: { model: marker } } } } };`,
+      );
+
+      const a = await loadConfig({ cwd: dirA, skipUser: true });
+      const b = await loadConfig({ cwd: dirB, skipUser: true });
+
+      expect(a.config.plugins?.provider?.items?.x?.model).toBe('from-A');
+      expect(b.config.plugins?.provider?.items?.x?.model).toBe('from-B');
+    } finally {
+      await fs.rm(dirA, { recursive: true, force: true });
+      await fs.rm(dirB, { recursive: true, force: true });
+    }
+  });
+});

package/src/loader.ts

@@ -0,0 +1,232 @@
+import { promises as fs } from 'node:fs';
+import * as path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { moxxyHome } from '@moxxy/sdk/server';
+import { mergeConfigs } from './merge.js';
+import { moxxyConfigSchema, type MoxxyConfig } from './schema.js';
+
+export interface LoadConfigOptions {
+  readonly cwd: string;
+  readonly explicitPath?: string;
+  readonly skipUser?: boolean;
+}
+
+export interface LoadedConfig {
+  readonly config: MoxxyConfig;
+  readonly sources: ReadonlyArray<{ scope: 'project' | 'user' | 'explicit'; path: string }>;
+}
+
+const CONFIG_NAMES = [
+  'moxxy.config.yaml',
+  'moxxy.config.yml',
+  'moxxy.config.ts',
+  'moxxy.config.js',
+  'moxxy.config.mjs',
+  'moxxy.config.cjs',
+];
+const USER_CONFIG_NAMES = [
+  'config.yaml',
+  'config.yml',
+  'config.ts',
+  'config.js',
+  'config.mjs',
+  'config.cjs',
+];
+/** Cap upward filesystem traversal when searching for a project config.
+ *  Shared with the config plugin's scope-resolution walk so the bound can't
+ *  drift between load time (here) and edit time (plugin.ts). */
+export const MAX_CONFIG_SEARCH_DEPTH = 12;
+
+export async function loadConfig(opts: LoadConfigOptions): Promise<LoadedConfig> {
+  const sources: Array<{ scope: 'project' | 'user' | 'explicit'; path: string }> = [];
+  const configs: MoxxyConfig[] = [];
+
+  if (!opts.skipUser) {
+    const userPath = await findFile(moxxyHome(), USER_CONFIG_NAMES);
+    if (userPath) {
+      const cfg = await loadOne(userPath);
+      configs.push(cfg);
+      sources.push({ scope: 'user', path: userPath });
+    }
+  }
+
+  if (opts.explicitPath) {
+    const cfg = await loadOne(opts.explicitPath);
+    configs.push(cfg);
+    sources.push({ scope: 'explicit', path: opts.explicitPath });
+  } else {
+    const projectPath = await findUpward(opts.cwd, CONFIG_NAMES);
+    if (projectPath) {
+      warnIfAncestorExecutableConfig(projectPath, opts.cwd);
+      const cfg = await loadOne(projectPath);
+      configs.push(cfg);
+      sources.push({ scope: 'project', path: projectPath });
+    }
+  }
+
+  return { config: mergeConfigs(...configs), sources };
+}
+
+const EXECUTABLE_CONFIG_EXTS = new Set(['.ts', '.tsx', '.js', '.mjs', '.cjs']);
+
+function isUnderDir(filePath: string, dir: string): boolean {
+  const rel = path.relative(path.resolve(dir), path.resolve(filePath));
+  return rel === '' || (!rel.startsWith('..') && !path.isAbsolute(rel));
+}
+
+/**
+ * The project-config upward walk resolves and then EXECUTES the first matching
+ * config above cwd. An ancestor (e.g. a shared home/temp parent or an untrusted
+ * outer repo) can therefore plant a config whose code runs with full process
+ * privileges. We keep the documented upward-walk behavior but surface the exact
+ * absolute path on stderr before running an ancestor *executable* config, so the
+ * operator can see what is about to execute. Non-executable YAML and at/under-cwd
+ * configs are silent (no new trust boundary widened).
+ */
+function warnIfAncestorExecutableConfig(filePath: string, cwd: string): void {
+  if (!EXECUTABLE_CONFIG_EXTS.has(path.extname(filePath))) return;
+  if (isUnderDir(filePath, cwd)) return;
+  console.warn(
+    `[moxxy] executing project config from an ancestor directory: ${path.resolve(filePath)}`,
+  );
+}
+
+async function loadOne(filePath: string): Promise<MoxxyConfig> {
+  const ext = path.extname(filePath);
+  let raw: unknown;
+
+  if (ext === '.yaml' || ext === '.yml') {
+    const yamlText = await fs.readFile(filePath, 'utf8');
+    const yamlMod = (await import('yaml')) as { parse: (text: string) => unknown };
+    raw = yamlMod.parse(yamlText);
+    if (raw === null || raw === undefined) raw = {};
+  } else {
+    let mod: unknown;
+    if (ext === '.ts' || ext === '.tsx') {
+      const jiti = await getJiti(path.dirname(filePath));
+      if (!jiti) throw new Error(`Cannot load ${filePath}: jiti is required for .ts configs.`);
+      mod = jiti(filePath);
+    } else {
+      mod = await importJsConfig(filePath);
+    }
+    raw = extractDefault(mod);
+    if (!raw) {
+      throw new Error(`Config file ${filePath} must default-export the result of defineConfig().`);
+    }
+  }
+
+  const parsed = moxxyConfigSchema.safeParse(raw);
+  if (!parsed.success) {
+    throw new Error(
+      `Invalid moxxy config at ${filePath}:\n` + JSON.stringify(parsed.error.issues, null, 2),
+    );
+  }
+  return parsed.data;
+}
+
+// Key the cache by cwd: a jiti instance binds its module-resolution /
+// interopDefault base to the dir it was created with, so a single shared
+// instance would resolve a SECOND project's `.ts` config relative imports
+// against the FIRST project's dir. Long-lived hosts (desktop/runner) load
+// configs for multiple workspaces in one process, so each cwd needs its own.
+//
+// Each entry carries its own module-resolution + compiled-module store, so an
+// unbounded map would grow one jiti runtime per workspace dir forever. Cap it
+// with a small LRU (re-insert on hit, drop the oldest on overflow) so a
+// long-running host that opens many projects keeps only a bounded working set.
+const MAX_CACHED_JITI = 16;
+const cachedJiti = new Map<string, (id: string) => unknown>();
+
+type JitiFactory = (cwd: string, opts?: unknown) => (id: string) => unknown;
+
+async function getJiti(cwd: string): Promise<((id: string) => unknown) | null> {
+  const existing = cachedJiti.get(cwd);
+  if (existing) {
+    // Mark as most-recently-used.
+    cachedJiti.delete(cwd);
+    cachedJiti.set(cwd, existing);
+    return existing;
+  }
+  try {
+    const mod = await import('jiti');
+    const factory =
+      (mod as { createJiti?: JitiFactory; default?: JitiFactory }).createJiti ??
+      (mod as { default?: JitiFactory }).default;
+    if (!factory) return null;
+    const instance = factory(cwd, { interopDefault: true });
+    cachedJiti.set(cwd, instance);
+    while (cachedJiti.size > MAX_CACHED_JITI) {
+      const oldest = cachedJiti.keys().next().value;
+      if (oldest === undefined) break;
+      cachedJiti.delete(oldest);
+    }
+    return instance;
+  } catch {
+    return null;
+  }
+}
+
+// The ESM module registry never evicts an entry once imported and offers no
+// eviction API: every DISTINCT specifier is retained for the process lifetime
+// along with its whole module graph. A naive `?v=${Date.now()}` cache-buster on
+// every load therefore leaks one module per reload in the exact long-lived
+// hosts (desktop/runner) this loader targets. Instead: import each JS config by
+// its plain file URL the FIRST time (one registry entry, GC-stable), and only
+// append a cache-buster when re-loading a path we've already imported — using a
+// monotonic counter so same-millisecond reloads are still guaranteed unique
+// (Date.now()'s 1ms resolution would otherwise return the stale cached module).
+const importedJsConfigs = new Set<string>();
+let importReloadCounter = 0;
+
+async function importJsConfig(filePath: string): Promise<unknown> {
+  const base = pathToFileURL(filePath).href;
+  if (importedJsConfigs.has(base)) {
+    return import(`${base}?v=${Date.now()}-${++importReloadCounter}`);
+  }
+  importedJsConfigs.add(base);
+  return import(base);
+}
+
+function extractDefault(mod: unknown): unknown {
+  if (!mod) return undefined;
+  if (typeof mod !== 'object') return undefined;
+  const m = mod as Record<string, unknown>;
+  if (m.default && typeof m.default === 'object') return m.default;
+  return undefined;
+}
+
+/**
+ * Walk upward from `startDir` (bounded by {@link MAX_CONFIG_SEARCH_DEPTH})
+ * returning the first directory that holds one of `names`. The `names` list is
+ * a deliberate parameter: `loadConfig` searches every config extension while the
+ * config plugin's editor searches only the YAML names it can safely mutate — so
+ * the shared traversal invariant lives here, the divergent name set stays with
+ * the caller. Returns the full path, or null if none found within the bound.
+ */
+export async function findUpward(
+  startDir: string,
+  names: ReadonlyArray<string>,
+): Promise<string | null> {
+  let cursor = path.resolve(startDir);
+  for (let i = 0; i < MAX_CONFIG_SEARCH_DEPTH; i++) {
+    const found = await findFile(cursor, names);
+    if (found) return found;
+    const parent = path.dirname(cursor);
+    if (parent === cursor) break;
+    cursor = parent;
+  }
+  return null;
+}
+
+async function findFile(dir: string, names: ReadonlyArray<string>): Promise<string | null> {
+  for (const name of names) {
+    const candidate = path.join(dir, name);
+    try {
+      await fs.access(candidate);
+      return candidate;
+    } catch {
+      // continue
+    }
+  }
+  return null;
+}