@carljia/omd-dsh 0.1.7 → 0.1.9

package/lib/omd-matrix-controller.d.ts

@@ -0,0 +1,108 @@
+import type { Matrix } from "./sync.js";
+/**
+ * Client-side edit state machine for the omd model matrix — deliberately free
+ * of React and DOM so it can be unit-tested against fake wire faces
+ * (test/client-store.test.ts).
+ *
+ * The controller mirrors one settings namespace scope (`ctx.settingsScope`
+ * bind) and writes through `api.settings.replace` with the scope's revision
+ * as `expectedRevision` — a stale editor is refused rather than silently
+ * overwriting a concurrent change (`settings-rejected` on the wire).
+ */
+/** Settings namespace the host row registers (src/host.ts) — must stay in step. */
+export declare const OMD_SETTINGS_NS = "omd-model-allocation";
+/** Client-side sync state of one settings namespace (wire-contract subset). */
+export interface OmdScopeSnapshot {
+    status: "loading" | "ready" | "unavailable";
+    value: Matrix | undefined;
+    revision: number | undefined;
+    writable: boolean;
+    mode: "host" | "memory";
+}
+/** The `settings.replace` wire face this controller needs. */
+export interface OmdSettingsApi {
+    settings: {
+        replace(request: {
+            ns: string;
+            section: object;
+            expectedRevision?: number;
+        }): Promise<{
+            result: {
+                ok: true;
+                value: unknown;
+            };
+        } | {
+            result: {
+                ok: false;
+                error: {
+                    message: string;
+                };
+            };
+        }>;
+    };
+}
+/** The shared describe mirror face (used to reload Host state after a rejected write). */
+export interface OmdDescribeFace {
+    load(): Promise<unknown>;
+}
+/** The bound scope as the controller consumes it. */
+export interface OmdScope {
+    getSnapshot(): OmdScopeSnapshot;
+    subscribe(listener: () => void): () => void;
+}
+export interface OmdControllerSnapshot {
+    draft: Matrix | null;
+    status: "idle" | "saving";
+    error: string | null;
+    saved: boolean;
+}
+type ModeField = "provider" | "model" | "reasoningEffort";
+export declare class OmdMatrixController {
+    private readonly api;
+    private readonly scope;
+    private readonly describe;
+    draft: Matrix | null;
+    status: "idle" | "saving";
+    error: string | null;
+    saved: boolean;
+    private readonly listeners;
+    private readonly unsubscribeScope;
+    /**
+     * Cached snapshot handed to `useSyncExternalStore`. React requires
+     * `getSnapshot()` to return the SAME reference between changes — a fresh
+     * object per call throws "The result of getSnapshot should be cached" and
+     * crashes the whole settings entry (blank page). Rebuilt only in `emit()`.
+     */
+    private snapshot;
+    constructor(api: OmdSettingsApi, scope: OmdScope, describe: OmdDescribeFace);
+    /** Release the scope subscription (plugin fiber teardown). */
+    dispose(): void;
+    /** Stable snapshot reference (uSES-safe): the SAME object until state changes. */
+    getSnapshot(): OmdControllerSnapshot;
+    subscribe(listener: () => void): () => void;
+    private emit;
+    /** External change (mirror reload after a rejected write, another window):
+     *  rebuild the draft from the fresh value, unless a save is in flight. */
+    private onScopeChange;
+    private refreshDraft;
+    /** Whether the Save / Reset controls may run. */
+    get canSave(): boolean;
+    /** Whether the namespace accepts writes at all (read-only provider / memory mode). */
+    get writable(): boolean;
+    /** Edit one mode's top-level field; an empty string removes the override
+     *  (the field re-inherits the composition base / schema default). */
+    patchMode(modeId: string, field: ModeField, value: string): void;
+    /** Edit one tier's provider/model; an empty string removes the override. */
+    patchTier(modeId: string, tier: string, field: "provider" | "model", value: string): void;
+    /**
+     * Persist the whole draft matrix through `settings.replace` (wholesale
+     * section replacement — the removal/reset path merge cannot express). The
+     * revision fence makes a stale editor fail loudly instead of overwriting.
+     * @returns once the write settled and the snapshot reflects the outcome.
+     */
+    save(): Promise<void>;
+    /** Restore the shipped default matrix: replace with an empty section. */
+    reset(): Promise<void>;
+    private replace;
+}
+export {};

package/lib/omd-matrix-controller.js

@@ -0,0 +1,180 @@
+/**
+ * Client-side edit state machine for the omd model matrix — deliberately free
+ * of React and DOM so it can be unit-tested against fake wire faces
+ * (test/client-store.test.ts).
+ *
+ * The controller mirrors one settings namespace scope (`ctx.settingsScope`
+ * bind) and writes through `api.settings.replace` with the scope's revision
+ * as `expectedRevision` — a stale editor is refused rather than silently
+ * overwriting a concurrent change (`settings-rejected` on the wire).
+ */
+/** Settings namespace the host row registers (src/host.ts) — must stay in step. */
+export const OMD_SETTINGS_NS = "omd-model-allocation";
+function cloneMatrix(value) {
+    if (value === undefined)
+        return null;
+    return JSON.parse(JSON.stringify(value));
+}
+function messageOf(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+export class OmdMatrixController {
+    api;
+    scope;
+    describe;
+    draft;
+    status = "idle";
+    error = null;
+    saved = false;
+    listeners = new Set();
+    unsubscribeScope;
+    /**
+     * Cached snapshot handed to `useSyncExternalStore`. React requires
+     * `getSnapshot()` to return the SAME reference between changes — a fresh
+     * object per call throws "The result of getSnapshot should be cached" and
+     * crashes the whole settings entry (blank page). Rebuilt only in `emit()`.
+     */
+    snapshot;
+    constructor(api, scope, describe) {
+        this.api = api;
+        this.scope = scope;
+        this.describe = describe;
+        this.draft = cloneMatrix(scope.getSnapshot().value);
+        this.snapshot = { draft: this.draft, status: this.status, error: this.error, saved: this.saved };
+        this.unsubscribeScope = scope.subscribe(() => this.onScopeChange());
+    }
+    /** Release the scope subscription (plugin fiber teardown). */
+    dispose() {
+        this.unsubscribeScope();
+        this.listeners.clear();
+    }
+    /** Stable snapshot reference (uSES-safe): the SAME object until state changes. */
+    getSnapshot() {
+        return this.snapshot;
+    }
+    subscribe(listener) {
+        this.listeners.add(listener);
+        return () => { this.listeners.delete(listener); };
+    }
+    emit() {
+        this.snapshot = { draft: this.draft, status: this.status, error: this.error, saved: this.saved };
+        for (const listener of [...this.listeners])
+            listener();
+    }
+    /** External change (mirror reload after a rejected write, another window):
+     *  rebuild the draft from the fresh value, unless a save is in flight. */
+    onScopeChange() {
+        if (this.status === "saving")
+            return;
+        this.refreshDraft();
+        this.emit();
+    }
+    refreshDraft() {
+        const value = this.scope.getSnapshot().value;
+        if (value !== undefined)
+            this.draft = cloneMatrix(value);
+    }
+    /** Whether the Save / Reset controls may run. */
+    get canSave() {
+        const snap = this.scope.getSnapshot();
+        return snap.status === "ready" && snap.writable && this.status !== "saving" && this.draft !== null;
+    }
+    /** Whether the namespace accepts writes at all (read-only provider / memory mode). */
+    get writable() {
+        return this.scope.getSnapshot().writable;
+    }
+    /** Edit one mode's top-level field; an empty string removes the override
+     *  (the field re-inherits the composition base / schema default). */
+    patchMode(modeId, field, value) {
+        const draft = this.draft;
+        if (draft === null)
+            return;
+        const modes = { ...draft.modes };
+        const cfg = { ...(modes[modeId] ?? {}) };
+        if (value === "")
+            delete cfg[field];
+        else
+            cfg[field] = value;
+        modes[modeId] = cfg;
+        this.draft = { ...draft, modes };
+        this.saved = false;
+        this.emit();
+    }
+    /** Edit one tier's provider/model; an empty string removes the override. */
+    patchTier(modeId, tier, field, value) {
+        const draft = this.draft;
+        if (draft === null)
+            return;
+        const modes = { ...draft.modes };
+        const cfg = { ...(modes[modeId] ?? {}) };
+        const tiers = { ...(cfg.tiers ?? {}) };
+        const tierCfg = { ...(tiers[tier] ?? {}) };
+        if (value === "")
+            delete tierCfg[field];
+        else
+            tierCfg[field] = value;
+        tiers[tier] = tierCfg;
+        cfg.tiers = tiers;
+        modes[modeId] = cfg;
+        this.draft = { ...draft, modes };
+        this.saved = false;
+        this.emit();
+    }
+    /**
+     * Persist the whole draft matrix through `settings.replace` (wholesale
+     * section replacement — the removal/reset path merge cannot express). The
+     * revision fence makes a stale editor fail loudly instead of overwriting.
+     * @returns once the write settled and the snapshot reflects the outcome.
+     */
+    async save() {
+        if (!this.canSave || this.draft === null)
+            return;
+        const snap = this.scope.getSnapshot();
+        this.status = "saving";
+        this.error = null;
+        this.emit();
+        const response = await this.replace({ section: this.draft, revision: snap.revision });
+        if (response.ok)
+            this.saved = true;
+        else {
+            this.error = response.message;
+            await this.describe.load();
+        }
+        this.refreshDraft();
+        this.status = "idle";
+        this.emit();
+    }
+    /** Restore the shipped default matrix: replace with an empty section. */
+    async reset() {
+        if (!this.canSave)
+            return;
+        const snap = this.scope.getSnapshot();
+        this.status = "saving";
+        this.error = null;
+        this.emit();
+        const response = await this.replace({ section: {}, revision: snap.revision });
+        if (response.ok)
+            this.saved = true;
+        else
+            this.error = response.message;
+        await this.describe.load();
+        this.refreshDraft();
+        this.status = "idle";
+        this.emit();
+    }
+    async replace(request) {
+        try {
+            const response = await this.api.settings.replace({
+                ns: OMD_SETTINGS_NS,
+                section: request.section,
+                ...(request.revision === undefined ? {} : { expectedRevision: request.revision }),
+            });
+            if (response.result.ok)
+                return { ok: true };
+            return { ok: false, message: response.result.error.message };
+        }
+        catch (error) {
+            return { ok: false, message: messageOf(error) };
+        }
+    }
+}

package/lib/plan.js

@@ -1,6 +1,5 @@
 import { mkdir, writeFile } from "node:fs/promises";
 import { basename, join } from "node:path";
-import { scopeOf } from "@deepseek-ai/dsh-scope";
 /**
  * @module @carljia/omd-dsh/plan
  *
@@ -96,9 +95,7 @@ function planModeActive(events) {
     return active;
 }
 function apply(ctx) {
-    if (scopeOf(ctx) === undefined) {
-        throw new Error("omd-plan: refusing to mount outside a scoped context; mount this row inside an agent preset");
-    }
+    // 无 scope 守卫：见 src/index.ts 的说明（自包含 bundle 无法读取 harness 的 kScope）。
     // Scoped .md-only write guard: the planner may write/edit only markdown
     // files, keeping it read-only for every other path. The plan file itself is
     // written by this row via node:fs (not through the model's write/edit tools),

package/lib/startwork.js

@@ -1,6 +1,5 @@
 import { access, readFile } from "node:fs/promises";
 import { isAbsolute, join } from "node:path";
-import { scopeOf } from "@deepseek-ai/dsh-scope";
 /**
  * @module @carljia/omd-dsh/startwork
  *
@@ -129,9 +128,7 @@ async function executeStartWork(ctx, invocation) {
     }
 }
 function apply(ctx) {
-    if (scopeOf(ctx) === undefined) {
-        throw new Error("omd-start-work: refusing to mount outside a scoped context; mount this row inside an agent preset");
-    }
+    // 无 scope 守卫：见 src/index.ts 的说明（自包含 bundle 无法读取 harness 的 kScope）。
     ctx.inject(["commands"], (commandCtx) => {
         commandCtx.commands.register({
             name: "start-work",

package/lib/sync.d.ts

@@ -1,15 +1,27 @@
 /**
  * omd-dsh sync core — materialize the OMD presets into <DSH_HOME>/.agent-presets.
  *
- * Shared by the CLI (\`omd-dsh sync\`) and the bundle boot row (\`dsh plugin add\`
- * + restart): locate the DSH harness node_modules, render each preset's
- * omd-mode / omd-task rows from the user's model matrix, copy the presets and
- * vendored row modules into .agent-presets, and rewrite the vendored modules'
- * bare @deepseek-ai/* imports to absolute file:// URLs into the harness tree so
- * the rows share ONE module instance with the harness (scope symbols etc.).
+ * Shared by the CLI (`omd-dsh sync`), the bundle boot row (`dsh plugin add`
+ * + restart), and the host settings row (lib/host.js): render each preset's
+ * omd-mode / omd-task rows from the model matrix, and copy the presets plus
+ * the vendored row modules into .agent-presets.
+ *
+ * The matrix has two faces: `runSync` reads/writes the CLI face
+ * (<DSH_HOME>/omd-matrix.json, the `omd-dsh setup` target), while the host
+ * settings row resolves the matrix from the settings namespace
+ * (`omd-model-allocation` in settings.yaml) and feeds it to
+ * `runSyncWithMatrix` — the file becomes an exported mirror of the namespace
+ * plus the CLI compatibility face (see src/host.ts).
+ *
+ * The vendored rows are SELF-CONTAINED bundles (see scripts/postbuild.mjs):
+ * every dependency is bundled in and they carry no @deepseek-ai imports, so
+ * the sync needs NO harness tree knowledge — the rows work regardless of
+ * whether the harness's agent machinery loads from an npx cache, a profile,
+ * or a global npm install, and no `--harness` configuration is ever needed.
+ * Bare package rows in the preset compositions (e.g. @deepseek-ai/dsh-persona)
+ * are resolved by the harness's own loader at runtime against the host base.
  */
 export type SyncFlags = {
-    harness?: string;
     dryRun: boolean;
     verbose: boolean;
 };
@@ -43,20 +55,26 @@ export declare const VENDOR_SOURCES: string[];
 /** User-owned model matrix: lives under DSH_HOME, never inside the package or the repo. */
 export declare const MATRIX_PATH: string;
 export declare function dshHome(): string;
+export declare const MatrixSchema: any;
+export declare function readDefaultMatrix(): Matrix;
 /**
- * Resolve the DSH harness node_modules:
- *   1. --harness flag (and cache it for later);
- *   2. auto-detect via the dsh executable on PATH;
- *   3. fall back to the locally cached value.
- */
-export declare function resolveHarness(flags: SyncFlags): string | undefined;
-/**
- * Resolve the harness node_modules from THIS module's own location, walking up
- * the Node resolution path for @deepseek-ai/dsh-scope. This is the reliable
- * anchor when the package runs as a bundle inside a DSH profile: the profile's
- * flat module fallback (or its hoisted node_modules) exposes the harness tree.
+ * Read the user's matrix file (<DSH_HOME>/omd-matrix.json) without touching
+ * the filesystem beyond the read: missing or malformed returns undefined and
+ * NEVER auto-generates — the caller decides what to fall back to (settings
+ * namespace resolved value / default matrix). This is the host row's
+ * "import CLI / legacy edits into the settings namespace" read.
  */
-export declare function resolveHarnessFromSelf(): string | undefined;
+export declare function readMatrixFileIfExists(): Matrix | undefined;
+/** Structural equality over the small JSON matrix (stringify equality suffices). */
+export declare function matrixEquals(a: Matrix, b: Matrix): boolean;
 export declare function loadMatrix(flags: SyncFlags, log?: (msg: string) => void): Matrix;
 export declare function saveMatrix(m: Matrix): void;
-export declare function runSync(flags: SyncFlags, harnessNodeModules: string, log?: (msg: string) => void): Promise<void>;
+/**
+ * Render and materialize the presets from an ALREADY-RESOLVED matrix. This is
+ * the shared core between the CLI file path (`runSync`) and the settings
+ * namespace path (host row): the matrix comes from the caller, everything
+ * after `loadMatrix(...)` is here.
+ */
+export declare function runSyncWithMatrix(matrix: Matrix, flags: SyncFlags, log?: (msg: string) => void): Promise<void>;
+/** CLI / manual-fallback path: load the matrix from <DSH_HOME>/omd-matrix.json (generating/migrating it on first run), then render. */
+export declare function runSync(flags: SyncFlags, log?: (msg: string) => void): Promise<void>;