@moxxy/config 0.27.0

package/src/schema.ts

@@ -0,0 +1,218 @@
+import { z } from 'zod';
+import { pluginSettingsSchema } from './plugin-settings-schema.js';
+import { pluginsTreeSchema } from './plugins-tree-schema.js';
+
+export const watcherModeSchema = z.enum(['auto', 'manual', 'off']);
+
+export const permissionsConfigSchema = z.object({
+  policyPath: z.string().optional(),
+  allow: z
+    .array(
+      z.object({
+        name: z.string(),
+        inputMatches: z.record(z.string(), z.string()).optional(),
+        reason: z.string().optional(),
+      }),
+    )
+    .optional(),
+  deny: z
+    .array(
+      z.object({
+        name: z.string(),
+        inputMatches: z.record(z.string(), z.string()).optional(),
+        reason: z.string().optional(),
+      }),
+    )
+    .optional(),
+});
+
+export const securityConfigSchema = z.object({
+  /**
+   * Master toggle. When omitted or false (the default), `@moxxy/plugin-security`
+   * is a no-op even if registered — every tool runs exactly as it does
+   * without the plugin. Per-tool `isolation: { ... }` declarations
+   * remain as documentation but are not enforced. Optional so a partial
+   * `security:` block (e.g. only `isolator`) validates and config_set can
+   * write one field at a time; consumers default it to false.
+   */
+  enabled: z.boolean().optional(),
+  // The default isolator now lives in the unified tree at
+  // `plugins.isolator.default` (a registry kind like any other); it is no
+  // longer a bespoke `security.isolator` key.
+  /**
+   * Per-tool isolator overrides keyed by tool name. e.g.
+   * `{ bash: 'subprocess', memory_save: 'none' }`. Falls back to the
+   * default isolator above when a tool isn't listed.
+   */
+  perTool: z.record(z.string(), z.string()).optional(),
+  /**
+   * Per-plugin isolator overrides keyed by plugin name. Applies to
+   * every tool the plugin contributes unless overridden in `perTool`.
+   */
+  perPlugin: z.record(z.string(), z.string()).optional(),
+  /**
+   * When true, tools without a declared `isolation` field are denied
+   * outright (instead of falling through to the default isolator).
+   * Useful for hardening once every in-use tool has been audited.
+   */
+  requireDeclaration: z.boolean().optional(),
+  /**
+   * The requireDeclaration ratchet for THIRD-PARTY plugins only — packages
+   * outside the trusted `@moxxy/` scope. Applies when a tool has no
+   * `isolation` declaration and the global `requireDeclaration` above did
+   * not already deny it:
+   * - 'off'     — third-party tools are treated like first-party ones.
+   * - 'warn'    — grace mode (the default while `security.enabled`): the
+   *               call runs, but a structured warning is logged once per
+   *               tool per process.
+   * - 'enforce' — the call is denied with a reason naming this flag.
+   * Tools with no resolvable owning plugin (e.g. runtime-attached MCP
+   * tools) are exempt — the npm-scope test is meaningless for them.
+   * Consumed by `@moxxy/plugin-security`
+   * (`SecurityPluginConfig.thirdPartyRequireDeclaration`).
+   */
+  thirdPartyRequireDeclaration: z.enum(['off', 'warn', 'enforce']).optional(),
+  /**
+   * Tighten the in-process input cap-check from best-effort to fail-closed.
+   * By default the fs/net checks only inspect string values under a recognized
+   * key name (`file`, `path`, `url`, …), so a path/URL carried by an
+   * unrecognized field (`config`, `manifest`, `webhook`) is not checked. With
+   * `strict: true`, any string value that is unambiguously an absolute path or a
+   * bare http(s) URL is treated as in-scope-required regardless of key name, so
+   * an unrecognized carrier fails closed. Consumed by `@moxxy/plugin-security`
+   * (`SecurityPluginConfig.strict`); without this field the loader's schema would
+   * silently strip a user's `security.strict: true` and the hardening would be
+   * lost. Defaults to false at the consumer.
+   */
+  strict: z.boolean().optional(),
+});
+
+export const embeddingsConfigSchema = z.object({
+  /**
+   * 'tfidf' (default, zero deps) | 'openai' (text-embedding-3-*)
+   * | 'transformers' (local, @huggingface/transformers) | 'none' (disable).
+   * Optional so a partial `embeddings:` block (e.g. only `model`) validates and
+   * config_set can write one field at a time; consumers default it to 'tfidf'.
+   */
+  provider: z.enum(['tfidf', 'openai', 'transformers', 'none']).optional(),
+  model: z.string().optional(),
+  dimensions: z.number().int().positive().optional(),
+  apiKey: z.string().optional(),
+  batchSize: z.number().int().positive().optional(),
+  cacheDir: z.string().optional(),
+  /** Persist computed embeddings to ~/.moxxy/memory/.embeddings.json. */
+  persistIndex: z.boolean().optional(),
+});
+
+/**
+ * Turn-boundary elision settings (context-on-demand). Off-by-floor safety:
+ * `keepRecentTurns` never drops below 2 and elision is skipped while the
+ * context is under `minContextRatioToElide` full.
+ */
+export const elisionConfigSchema = z.object({
+  enabled: z.boolean().optional(),
+  keepRecentTurns: z.number().int().min(2).optional(),
+  minContextRatioToElide: z.number().min(0).max(1).optional(),
+  /** Also collapse old user/assistant text turns (not just bulky tool results). */
+  elideConversational: z.boolean().optional(),
+  /** Auto-disable conversational elision after this many `recall({seq})` calls. */
+  conversationalRecallThreshold: z.number().int().positive().optional(),
+  maxRecallBytes: z.number().int().positive().optional(),
+  neverElideTools: z.array(z.string()).optional(),
+});
+
+/** Context-window / token-efficiency settings. */
+export const contextConfigSchema = z.object({
+  /** Master switch for prompt caching. Default true (lossless). */
+  caching: z.boolean().optional(),
+  // The active CacheStrategy now lives at `plugins.cacheStrategy.default`.
+  elision: elisionConfigSchema.optional(),
+  /** Lazy tool loading: send only core + loaded tool schemas, index the rest. Default false. */
+  lazyTools: z.boolean().optional(),
+  /**
+   * Reasoning/thinking preview. `true` enables it at the model's default depth;
+   * `{ effort }` sets the depth. Honored only by providers/models that support
+   * reasoning (Anthropic adaptive thinking, OpenAI/Codex reasoning). Default off.
+   */
+  reasoning: z
+    .union([z.boolean(), z.object({ effort: z.enum(['low', 'medium', 'high']).optional() })])
+    .optional(),
+  /**
+   * Stuck-loop guard tuning. The guard bails a turn early when the model keeps
+   * making the same tool call; `maxIterations` is the hard backstop. Raise the
+   * thresholds if legitimately-repeated work is being cut short, or set
+   * `enabled: false` to disable the guard and rely on `maxIterations` alone.
+   */
+  loopGuard: z
+    .object({
+      enabled: z.boolean().optional(),
+      windowSize: z.number().int().positive().optional(),
+      repeatThreshold: z.number().int().positive().optional(),
+      nearWindowSize: z.number().int().positive().optional(),
+      nearThreshold: z.number().int().positive().optional(),
+    })
+    .strict()
+    .optional(),
+});
+
+export const moxxyConfigSchema = z.object({
+  /**
+   * The unified plugins manifest — the single source of truth for what's
+   * installed/enabled (`plugins.packages`) and the active default per category
+   * (`plugins.<category>.default`). Replaces the legacy flat
+   * provider/mode/compactor/workflowExecutor keys, the old `plugins:` map, and
+   * `preferences.json`.
+   */
+  plugins: pluginsTreeSchema.optional(),
+  context: contextConfigSchema.optional(),
+  systemPrompt: z.string().optional(),
+  maxIterations: z.number().int().positive().optional(),
+  hookTimeoutMs: z.number().int().positive().optional(),
+  watcher: watcherModeSchema.optional(),
+  skills: z
+    .object({
+      projectDir: z.string().optional(),
+      userDir: z.string().optional(),
+      extraDirs: z.array(z.string()).optional(),
+    })
+    .optional(),
+  security: securityConfigSchema.optional(),
+  channels: z.record(z.string(), z.record(z.string(), z.unknown())).optional(),
+  permissions: permissionsConfigSchema.optional(),
+  env: z.record(z.string(), z.string()).optional(),
+  /** TUI presentation preferences (read at TUI boot; edited via /settings). */
+  tui: z
+    .object({
+      /** `mono` drops color like NO_COLOR; `default` is the standard palette. */
+      theme: z.enum(['default', 'mono']).optional(),
+      /** Hide the footer key-hint row when false. */
+      hints: z.boolean().optional(),
+      /**
+       * Ctrl+<letter> overrides for the input-editor command hotkeys. Values
+       * are single letters; unknown/conflicting letters are ignored at boot.
+       */
+      keys: z
+        .object({
+          forceSend: z.string().length(1).optional(),
+          dropQueued: z.string().length(1).optional(),
+          toggleTools: z.string().length(1).optional(),
+        })
+        .strict()
+        .optional(),
+    })
+    .strict()
+    .optional(),
+});
+
+export type MoxxyConfig = z.infer<typeof moxxyConfigSchema>;
+export type ContextConfig = z.infer<typeof contextConfigSchema>;
+export type ElisionConfig = z.infer<typeof elisionConfigSchema>;
+export type WatcherMode = z.infer<typeof watcherModeSchema>;
+export type PermissionsConfig = z.infer<typeof permissionsConfigSchema>;
+export type EmbeddingsConfig = z.infer<typeof embeddingsConfigSchema>;
+export type SecurityConfig = z.infer<typeof securityConfigSchema>;
+
+// `pluginSettingsSchema` is defined in ./plugin-settings-schema and re-exported
+// here for back-references; `PluginSettings` lives there too.
+export { pluginSettingsSchema };
+export type { PluginSettings } from './plugin-settings-schema.js';

package/src/security-config.test.ts

@@ -0,0 +1,30 @@
+import { describe, expect, it } from 'vitest';
+import { moxxyConfigSchema, securityConfigSchema } from './schema.js';
+
+describe('security.thirdPartyRequireDeclaration schema round-trip', () => {
+  it.each(['off', 'warn', 'enforce'] as const)('accepts and preserves %s', (mode) => {
+    const parsed = moxxyConfigSchema.parse({
+      security: { enabled: true, thirdPartyRequireDeclaration: mode },
+    });
+    expect(parsed.security?.thirdPartyRequireDeclaration).toBe(mode);
+  });
+
+  it('stays absent when unset (consumer applies the warn default)', () => {
+    const parsed = moxxyConfigSchema.parse({ security: { enabled: true } });
+    expect(parsed.security?.thirdPartyRequireDeclaration).toBeUndefined();
+  });
+
+  it('rejects values outside the closed enum', () => {
+    expect(() =>
+      securityConfigSchema.parse({ thirdPartyRequireDeclaration: 'deny' }),
+    ).toThrow();
+    expect(() =>
+      securityConfigSchema.parse({ thirdPartyRequireDeclaration: true }),
+    ).toThrow();
+  });
+
+  it('validates as a partial block (the field alone parses)', () => {
+    const parsed = securityConfigSchema.parse({ thirdPartyRequireDeclaration: 'enforce' });
+    expect(parsed).toEqual({ thirdPartyRequireDeclaration: 'enforce' });
+  });
+});

package/src/user-config.test.ts

@@ -0,0 +1,113 @@
+import { promises as fs } from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { parse as parseYaml } from 'yaml';
+import { applyInitConfig, setPluginEnabled } from './user-config.js';
+import { moxxyConfigSchema } from './schema.js';
+
+let tmp: string;
+let configPath: string;
+
+beforeEach(async () => {
+  tmp = await fs.mkdtemp(path.join(os.tmpdir(), 'mox-user-config-'));
+  configPath = path.join(tmp, 'config.yaml');
+});
+
+afterEach(async () => {
+  await fs.rm(tmp, { recursive: true, force: true });
+});
+
+async function readParsed(): Promise<Record<string, unknown>> {
+  const raw = await fs.readFile(configPath, 'utf8');
+  return parseYaml(raw) as Record<string, unknown>;
+}
+
+describe('applyInitConfig', () => {
+  it('writes the unified plugins tree the clean-slate schema reads', async () => {
+    const written = await applyInitConfig(
+      { provider: 'anthropic', model: 'claude-sonnet-4-6', mode: 'goal', embedder: 'openai' },
+      { configPath },
+    );
+    expect(written).toBe(configPath);
+
+    const parsed = await readParsed();
+    expect(parsed).toMatchObject({
+      plugins: {
+        provider: { default: 'anthropic', items: { anthropic: { model: 'claude-sonnet-4-6' } } },
+        mode: { default: 'goal' },
+        embedder: { default: 'openai' },
+      },
+    });
+    // The result must validate against the real config schema.
+    expect(moxxyConfigSchema.safeParse(parsed).success).toBe(true);
+  });
+
+  it('MERGES into the existing package ledger instead of clobbering it', async () => {
+    // Simulate ensureProvider/installPlugins enabling packages BEFORE the wizard
+    // persists the provider default + model (the exact init ordering).
+    await setPluginEnabled('@moxxy/plugin-provider-anthropic', true, { configPath });
+    await setPluginEnabled('@moxxy/plugin-telegram', true, { configPath });
+
+    await applyInitConfig(
+      { provider: 'anthropic', model: 'claude-sonnet-4-6', mode: 'default', embedder: 'tfidf' },
+      { configPath },
+    );
+
+    const parsed = (await readParsed()) as {
+      plugins: {
+        packages: Record<string, { enabled: boolean }>;
+        provider: { default: string };
+      };
+    };
+    // Ledger survived the merge.
+    expect(parsed.plugins.packages['@moxxy/plugin-provider-anthropic']).toEqual({ enabled: true });
+    expect(parsed.plugins.packages['@moxxy/plugin-telegram']).toEqual({ enabled: true });
+    // And the provider default landed alongside it.
+    expect(parsed.plugins.provider.default).toBe('anthropic');
+  });
+
+  it('omits the tfidf floor, a null model, and the security block by default', async () => {
+    await applyInitConfig(
+      { provider: 'anthropic', model: null, mode: 'default', embedder: 'tfidf' },
+      { configPath },
+    );
+    const parsed = (await readParsed()) as { plugins: Record<string, unknown>; security?: unknown };
+    expect(parsed.plugins.embedder).toBeUndefined();
+    expect(parsed.plugins.provider).toEqual({ default: 'anthropic' });
+    expect(parsed.security).toBeUndefined();
+  });
+
+  it('writes security.enabled only when opted in', async () => {
+    await applyInitConfig(
+      { provider: 'anthropic', mode: 'default', embedder: 'tfidf', security: { enabled: true } },
+      { configPath },
+    );
+    const parsed = (await readParsed()) as { security: { enabled: boolean } };
+    expect(parsed.security.enabled).toBe(true);
+  });
+
+  it('records fallbacks (excluding the primary) and never references the vault key', async () => {
+    await applyInitConfig(
+      { provider: 'anthropic', mode: 'default', embedder: 'tfidf', fallbacks: ['anthropic', 'openai'] },
+      { configPath },
+    );
+    const raw = await fs.readFile(configPath, 'utf8');
+    const parsed = parseYaml(raw) as { plugins: { provider: { fallbacks: string[] } } };
+    expect(parsed.plugins.provider.fallbacks).toEqual(['openai']);
+    // Like `moxxy provision`, the key lives in the vault under its canonical
+    // name — the config must not carry a ${vault:...} apiKey ref.
+    expect(raw).not.toContain('apiKey');
+    expect(raw).not.toContain('${vault:');
+  });
+
+  it('preserves user comments across the merge (comment-preserving round-trip)', async () => {
+    await fs.writeFile(configPath, '# my hand-written config\nplugins:\n  packages: {}\n');
+    await applyInitConfig(
+      { provider: 'anthropic', mode: 'default', embedder: 'tfidf' },
+      { configPath },
+    );
+    const raw = await fs.readFile(configPath, 'utf8');
+    expect(raw).toContain('# my hand-written config');
+  });
+});