@atomic-chat/core 0.5.1

package/dist/settings/schema.js

@@ -0,0 +1,196 @@
+/**
+ * Provider setting schemas: the app's four extension `settings.json` descriptor arrays embedded verbatim
+ * as JSON (`schema/*.json`), the per-key defaults, and the canonical value types the runtime expects.
+ *
+ * Ported from: core/src/browser/extension.ts:150-240 (`registerSettings` / `getSettings` / `getSetting` /
+ * `updateSettings` — the array lives in `localStorage[<extension name>]`, values are whatever the UI
+ * stored), extensions/llamacpp-upstream-extension/src/index.ts:697-745 (`onLoad`: for every descriptor
+ * `config[key] = await getSetting(key, descriptor.controllerProps.value)` — so `this.config` is typed by
+ * the descriptor defaults), extensions/mlx-extension/src/buildMlxConfig.ts (`asNumber`: number inputs
+ * ship string defaults and the UI hands back strings).
+ *
+ * The wire types are an explicit table, not derived from `controllerProps.type`, because the descriptors
+ * disagree with Rust `LlamacppConfig`: `timeout` ships "1800" (a string) but is `i32`; `fit_ctx` ships
+ * 4096 (a number) but is `String`; `fit_target` is a string on both sides. Keys missing from the table
+ * pass through untouched, so unknown keys survive (PLAN.md §5.1).
+ */
+import foundationModelsSchema from './schema/foundation-models.json' with { type: 'json' };
+import llamacppUpstreamSchema from './schema/llamacpp-upstream.json' with { type: 'json' };
+import llamacppSchema from './schema/llamacpp.json' with { type: 'json' };
+import mlxSchema from './schema/mlx.json' with { type: 'json' };
+export const LOCAL_PROVIDER_IDS = [
+    'llamacpp-upstream',
+    'llamacpp',
+    'mlx',
+    'foundation-models',
+];
+const CONTROLLER_TYPES = new Set(['checkbox', 'input', 'dropdown', 'slider']);
+/** Validate the embedded JSON once at load time; a bad descriptor is a packaging bug, not user input. */
+function toDescriptors(provider, raw) {
+    if (!Array.isArray(raw))
+        throw new Error(`settings schema for ${provider} is not an array`);
+    return raw.map((entry, i) => {
+        const d = entry;
+        if (!d ||
+            typeof d.key !== 'string' ||
+            typeof d.controllerType !== 'string' ||
+            !CONTROLLER_TYPES.has(d.controllerType) ||
+            typeof d.controllerProps !== 'object' ||
+            d.controllerProps === null ||
+            !('value' in d.controllerProps)) {
+            throw new Error(`settings schema for ${provider}: invalid descriptor at index ${i}`);
+        }
+        return d;
+    });
+}
+const SCHEMAS = {
+    'llamacpp-upstream': toDescriptors('llamacpp-upstream', llamacppUpstreamSchema),
+    'llamacpp': toDescriptors('llamacpp', llamacppSchema),
+    'mlx': toDescriptors('mlx', mlxSchema),
+    'foundation-models': toDescriptors('foundation-models', foundationModelsSchema),
+};
+/** The descriptor array as the app registers it (deep copy — callers may mutate `options`/`value`). */
+export function settingsSchema(provider) {
+    return structuredClone(SCHEMAS[provider]);
+}
+/** `key → controllerProps.value`, exactly as the descriptors ship (`timeout` is the string "1800" here). */
+export function defaultSettingValues(provider) {
+    const out = {};
+    for (const d of SCHEMAS[provider])
+        out[d.key] = structuredClone(d.controllerProps.value);
+    return out;
+}
+/**
+ * Rust `LlamacppConfig` (args.rs:12-97) field types — engine settings from `settings.json` plus the
+ * per-model / computed fields the load plan merges in, so one table serves both.
+ */
+const LLAMACPP_VALUE_TYPES = {
+    version_backend: 'string',
+    auto_unload: 'boolean',
+    timeout: 'number',
+    llamacpp_env: 'string',
+    extra_args: 'string',
+    reasoning_preserve: 'boolean',
+    mtp: 'boolean',
+    mtp_draft_path: 'string',
+    dflash: 'boolean',
+    dflash_draft_path: 'string',
+    dflash_spec_supported: 'boolean',
+    dflash_n_max: 'number',
+    dflash_block_size: 'number',
+    concurrent_mode: 'boolean',
+    concurrent_slots: 'number',
+    expose_metrics: 'boolean',
+    parallel: 'number',
+    cont_batching: 'boolean',
+    fit: 'boolean',
+    fit_target: 'string',
+    fit_ctx: 'string',
+    threads: 'number',
+    threads_batch: 'number',
+    ctx_shift: 'boolean',
+    ctx_size: 'number',
+    n_gpu_layers: 'number',
+    n_predict: 'number',
+    batch_size: 'number',
+    ubatch_size: 'number',
+    device: 'string',
+    split_mode: 'string',
+    main_gpu: 'number',
+    flash_attn: 'string',
+    no_mmap: 'boolean',
+    mlock: 'boolean',
+    no_kv_offload: 'boolean',
+    cache_type_k: 'string',
+    cache_type_v: 'string',
+    defrag_thold: 'number',
+    rope_scaling: 'string',
+    rope_scale: 'number',
+    rope_freq_base: 'number',
+    rope_freq_scale: 'number',
+    chat_template: 'string',
+    offload_mmproj: 'boolean',
+    cpu_moe: 'boolean',
+    n_cpu_moe: 'number',
+    override_tensor_buffer_t: 'string',
+};
+/** MLX `settings.json` keys plus the `MlxConfig` fields `buildMlxConfig` derives from them. */
+const MLX_VALUE_TYPES = {
+    version_backend: 'string',
+    dflash_enabled: 'boolean',
+    block_size: 'number',
+    mtp_enabled: 'boolean',
+    mtp_block_size: 'number',
+    eagle3_enabled: 'boolean',
+    eagle3_block_size: 'number',
+    kv_quant_scheme: 'string',
+    kv_bits: 'number',
+    timeout: 'number',
+    auto_unload: 'boolean',
+    ctx_size: 'number',
+    draft_model_path: 'string',
+};
+const FOUNDATION_MODELS_VALUE_TYPES = {
+    timeout: 'number',
+};
+export const CANONICAL_VALUE_TYPES = {
+    'llamacpp-upstream': LLAMACPP_VALUE_TYPES,
+    'llamacpp': LLAMACPP_VALUE_TYPES,
+    'mlx': MLX_VALUE_TYPES,
+    'foundation-models': FOUNDATION_MODELS_VALUE_TYPES,
+};
+/**
+ * Coerce one value to its wire type. Uncoercible input ("abc" for a number, `{}` for a boolean) is
+ * returned unchanged rather than invented — validation, if any, belongs to the caller.
+ */
+export function canonicalizeSettingValue(type, value) {
+    switch (type) {
+        case 'boolean': {
+            if (typeof value === 'boolean')
+                return value;
+            if (typeof value === 'number')
+                return value === 1 ? true : value === 0 ? false : value;
+            if (typeof value === 'string') {
+                const s = value.trim().toLowerCase();
+                if (s === 'true' || s === '1')
+                    return true;
+                if (s === 'false' || s === '0')
+                    return false;
+            }
+            return value;
+        }
+        case 'number': {
+            if (typeof value === 'number')
+                return value;
+            if (typeof value === 'boolean')
+                return value ? 1 : 0;
+            if (typeof value === 'string' && value.trim() !== '') {
+                const n = Number(value);
+                return Number.isFinite(n) ? n : value;
+            }
+            return value;
+        }
+        case 'string': {
+            if (typeof value === 'string')
+                return value;
+            if (typeof value === 'number' || typeof value === 'boolean')
+                return String(value);
+            return value;
+        }
+    }
+}
+/**
+ * Apply the provider's type table to every key of `values`: booleans for checkboxes, numbers where Rust
+ * has `i32`/`u32`/`f32`, strings for `fit_ctx`/`fit_target`/dropdowns. Keys the table does not know are
+ * copied as they are. Never mutates the input.
+ */
+export function canonicalizeSettingValues(provider, values) {
+    const types = CANONICAL_VALUE_TYPES[provider];
+    const out = {};
+    for (const [key, value] of Object.entries(values)) {
+        const type = types[key];
+        out[key] = type === undefined ? value : canonicalizeSettingValue(type, value);
+    }
+    return out;
+}
+//# sourceMappingURL=schema.js.map

package/dist/settings/schema.js.map

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

package/dist/settings/store.d.ts

@@ -0,0 +1,168 @@
+/**
+ * `<data>/atomic-core/settings.json` — the core's replacement for the app's `localStorage[<extension>]`
+ * descriptor arrays (core/src/browser/extension.ts:150-240) and its loose service keys
+ * (`llama_cpp_pending_backend`, `llama_cpp_better_backend_recommendation`, … — PLAN.md §8.1).
+ *
+ * Shape (PLAN.md §3.4):
+ *   { version, revision, updated_at,
+ *     providers: { <provider>: { <canonical key>: <typed value> } },
+ *     server: ServerSettings, cloud: { providers: [] },
+ *     state: { providers: { <provider>: { backend_type, pending_backend, better_backend_recommendation,
+ *                                          last_recheck_outcome } },
+ *              migrations: { <scope>: { baseline, legacy_hash, acknowledged_revision } } } }
+ *
+ * Rules:
+ *  - `revision` is monotonic and only moves when a value actually changed; callers pass
+ *    `expectedRevision` to get a conflict (`INVALID_ARGUMENT`) instead of a lost update.
+ *  - Every write is atomic: `<file>.tmp` then rename, mode 0600 (protected like credentials).
+ *  - Unknown keys — at the top level, inside a provider, inside `state` — survive read → write, so an
+ *    older core never destroys what a newer one stored (PLAN.md §5.1).
+ *  - Values are canonicalized on read and on write (`canonicalizeSettingValues`), so `get()` returns
+ *    the types Rust `LlamacppConfig` expects even when the file was hand-edited with strings.
+ *  - I/O is injected (`fs`, `now`) so tests run on an in-memory fake.
+ */
+import type { LocalProviderId, ServerSettings } from '../contracts/index.js';
+import type { ImportOutcome, Resolutions } from './import.js';
+export declare const SETTINGS_FILE_VERSION = 1;
+export type ProviderValues = Record<string, unknown>;
+/** Per-provider runtime facts the app kept as loose `localStorage` keys; all `string | null` there too. */
+export interface ProviderRuntimeState {
+    backend_type: string | null;
+    pending_backend: string | null;
+    better_backend_recommendation: string | null;
+    last_recheck_outcome: string | null;
+    [extra: string]: unknown;
+}
+/** One migration scope (a provider, `server` or `cloud`), see PLAN.md §3.4 "Settings migration". */
+export interface MigrationRecord {
+    baseline: Record<string, unknown> | null;
+    legacy_hash: string | null;
+    acknowledged_revision: number | null;
+    [extra: string]: unknown;
+}
+export interface CoreState {
+    providers: Record<LocalProviderId, ProviderRuntimeState> & Record<string, unknown>;
+    migrations: Record<string, MigrationRecord>;
+    [extra: string]: unknown;
+}
+export interface CloudSettings {
+    providers: Record<string, unknown>[];
+    [extra: string]: unknown;
+}
+export interface SettingsDocument {
+    version: number;
+    owner_scope?: 'app' | 'cli';
+    revision: number;
+    /** ISO-8601 of the last write, from the injected clock. */
+    updated_at: string;
+    providers: Record<LocalProviderId, ProviderValues> & Record<string, unknown>;
+    server: ServerSettings & Record<string, unknown>;
+    cloud: CloudSettings;
+    state: CoreState;
+    [extra: string]: unknown;
+}
+export type SettingsScope = LocalProviderId | 'server' | 'cloud' | 'state';
+/** What `onChange` listeners receive; the events module maps it onto `settings:changed`. */
+export interface SettingsChange {
+    scope: SettingsScope;
+    /** The setting key; for `state` changes it is `<provider>.<key>`. */
+    key: string;
+    value: unknown;
+    revision: number;
+}
+export interface UpdateOptions {
+    /** Refuse the write when the on-disk revision moved past this (`INVALID_ARGUMENT`). */
+    expectedRevision?: number;
+}
+export interface UpdateResult {
+    revision: number;
+    /** Keys whose value actually changed (empty ⇒ nothing was written). */
+    changed: string[];
+}
+export interface ImportOptions extends UpdateOptions {
+    /** How to settle keys both sides changed; without one, the import reports the conflict instead. */
+    resolutions?: Resolutions;
+}
+export interface ImportResult extends ImportOutcome {
+    revision: number;
+}
+/** The subset of `node:fs/promises` the store needs; tests pass an in-memory fake. */
+export interface SettingsFs {
+    readFile(path: string, encoding: 'utf8'): Promise<string>;
+    writeFile(path: string, data: string, options?: {
+        encoding?: 'utf8';
+        mode?: number;
+    }): Promise<void>;
+    rename(from: string, to: string): Promise<void>;
+    mkdir(path: string, options?: {
+        recursive?: boolean;
+    }): Promise<string | undefined>;
+    stat(path: string): Promise<unknown>;
+}
+export interface SettingsStoreOptions {
+    ownerScope?: 'app' | 'cli';
+    fs?: SettingsFs;
+    /** Milliseconds since epoch; defaults to `Date.now`. */
+    now?: () => number;
+}
+export declare const EMPTY_PROVIDER_STATE: ProviderRuntimeState;
+/** Schema defaults with the wire types applied — what a fresh provider section holds. */
+export declare function canonicalProviderDefaults(provider: LocalProviderId): ProviderValues;
+/**
+ * Fill every known section with defaults, keep everything else. `raw` may be `{}` (fresh file) or
+ * anything a previous core wrote. Throws `IO_ERROR` when the file claims a newer format version.
+ */
+export declare function normalizeSettingsDocument(raw: Record<string, unknown>, nowMs: number): SettingsDocument;
+export declare class SettingsStore {
+    readonly path: string;
+    private doc;
+    private readonly fs;
+    private readonly now;
+    private readonly listeners;
+    /** Serialises mutations so two concurrent `update`s never race on `.tmp`. */
+    private chain;
+    private constructor();
+    /** Read the file, or create it with schema defaults when absent. Corrupt JSON is an `IO_ERROR`. */
+    static open(path: string, options?: SettingsStoreOptions): Promise<SettingsStore>;
+    get revision(): number;
+    /** Full deep copy of the document (control API snapshot). */
+    snapshot(): SettingsDocument;
+    get(provider: LocalProviderId): ProviderValues;
+    get server(): ServerSettings & Record<string, unknown>;
+    get state(): CoreState;
+    /** Apply `patch` (canonicalized) to a provider; keys whose value is unchanged are ignored. */
+    update(provider: LocalProviderId, patch: ProviderValues, options?: UpdateOptions): Promise<UpdateResult>;
+    updateServer(patch: Partial<ServerSettings> & Record<string, unknown>, options?: UpdateOptions): Promise<UpdateResult>;
+    /**
+     * Replace the cloud provider list (non-secret parts only; keys live in credentials.json). One
+     * change is reported for the whole list when anything in it differs.
+     */
+    setCloudProviders(providers: Record<string, unknown>[], options?: UpdateOptions): Promise<UpdateResult>;
+    updateState(provider: LocalProviderId, patch: Partial<ProviderRuntimeState>, options?: UpdateOptions): Promise<UpdateResult>;
+    /**
+     * Take the desktop app's settings for a provider (PLAN.md §3.4).
+     *
+     * Three-way, not a copy: see `import.ts`. Nothing is written when any key conflicts, so a scope
+     * is either fully migrated or not migrated at all — a half-applied import would leave the app and
+     * the core disagreeing about settings neither side accepted.
+     *
+     * The migration record is written even when the merge applies no values, because the record is
+     * what stops the next start from merging the same change all over again.
+     */
+    importProvider(provider: LocalProviderId, legacyValues: ProviderValues, options?: ImportOptions): Promise<ImportResult>;
+    /**
+     * Record that the app has mirrored the core's settings up to `revision`.
+     *
+     * Only meaningful after an import: it is how a planned rollback knows whether the app's copy is
+     * current enough to hand ownership back (PLAN.md §3.4). The acknowledgement itself is a
+     * metadata-only write, but it advances the file's revision like every other write. Store that
+     * resulting revision as the equivalent mirrored state so status is in sync immediately after it.
+     */
+    acknowledge(scope: SettingsScope, revision: number): Promise<UpdateResult>;
+    /** What the core knows about a scope's migration, or `null` when it has never been imported. */
+    migration(scope: SettingsScope): MigrationRecord | null;
+    /** Called once per changed key after the write landed; returns the unsubscribe function. */
+    onChange(listener: (change: SettingsChange) => void): () => void;
+    private mutate;
+    private persist;
+}