@intutic/sync-daemon 1.9.0 → 1.10.1

package/dist/harness/dshHooks.d.ts

@@ -0,0 +1,198 @@
+/**
+ * dshHooks.ts — DeepSeek "dsh" (developer preview, `@deepseek-ai/dsh`) Cordis
+ * plugin registration + LLM egress routing.
+ *
+ * dsh has no `hooks.json`/shell-script gate surface at all — it is
+ * plugin-first ("Cordis", DeepSeek's own extensibility framework), and the
+ * blocking gate for this harness ships as a real TypeScript module,
+ * `@intutic/gate/dsh` (`packages/gate-js/src/dsh.ts`), not a generated
+ * string of shell/JS this writer assembles the way `grokHooks.ts`/
+ * `museHooks.ts` do. This writer's job is narrower than theirs: merge-write
+ * the ROW that tells dsh's own Cordis loader to load that module, into every
+ * dsh profile this machine has, plus the LLM egress override.
+ *
+ * # What this phase confirmed against a REAL install — not the plan's guess
+ *
+ * `@deepseek-ai/dsh` and its Cordis framework packages (`@deepseek-ai/cordis`,
+ * `@deepseek-ai/dsh-app-boot`, `@deepseek-ai/dsh-tools`, `@deepseek-ai/dsh-base`,
+ * `@deepseek-ai/dsh-llm-pi-ai`, `@deepseek-ai/dsh-home-paths`, ...) are public
+ * on the npm registry (first published 2026-08-13, ~161 KB unpacked for the
+ * `dsh` package itself) — reachable and installable from this sandbox, unlike
+ * Muse Code/Grok Build in Wave 1. This writer was authored against a real
+ * `npm pack` + read of those packages' shipped `.d.ts`/README files, not
+ * solely the phase brief's prior research (see the TD entry this phase filed
+ * for exactly what was checked and what is still genuinely unconfirmed —
+ * dsh-permission, dsh-settings-local, and dsh-fs-policy 404'd as
+ * `publishConfig.access: restricted`, so the exact settings.yaml schema
+ * dsh-settings-local enforces was not directly inspected, only inferred from
+ * `dsh-base`'s own `cordis.patch.yml` comments and `dsh-llm-pi-ai`'s README).
+ *
+ * Confirmed facts this writer relies on:
+ *
+ *   - `$DSH_HOME` resolution (`dsh-home-paths`): an explicit configured path,
+ *     then `$DSH_HOME`, then `~/.dsh` — {@link resolveDshHome} below mirrors
+ *     the env-var half (this writer has no "explicit configured path" input).
+ *   - A **profile** is `$DSH_HOME/profiles/<name>/` holding a `package.json`
+ *     (the profile manifest) and a `cordis.patch.yml` (`PROFILE_PATCH_FILENAME`
+ *     — "the user patch layer inside a profile directory, hot-reloaded") —
+ *     confirmed from `@deepseek-ai/dsh-app-boot`'s shipped `profile.d.ts`.
+ *   - The patch-list format (`@deepseek-ai/cordis-plugin-include`'s
+ *     `applyEntryPatches`, read from its shipped `lib/index.js`): a top-level
+ *     YAML array of patch operations. `{ insert: [...] }` with no `id`
+ *     appends the listed rows to the array; `{ id, insert: [...] }` inserts
+ *     into an existing GROUP row's own `config` array; `{ id, name?,
+ *     config?, ... }` (no `insert`) looks up the row by `id` and overwrites
+ *     the named fields in place. This writer only ever emits the first shape
+ *     (a fresh, self-contained `insert:` block naming this row by `id`), so
+ *     its own writes are always recognizable on a later sync regardless of
+ *     which shape a human or an older version of this writer left.
+ *   - Plugin resolution (`@deepseek-ai/cordis-plugin-loader`'s shipped
+ *     `lib/index.js`): a patch row's `name` is resolved via a plain dynamic
+ *     `import(name)` when it is not a relative path — a bare specifier like
+ *     `@intutic/gate/dsh` resolves exactly the way any other bundle package
+ *     name in `dsh-base`'s own `cordis.patch.yml` does, subpath exports
+ *     included. Node resolves it from the profile directory's own
+ *     `node_modules` (the "two-anchor" resolution `profile.d.ts` documents
+ *     for out-of-tree plugins) — which means `@intutic/gate` must actually be
+ *     installed there; see {@link mergeProfileDependency} and the TD entry
+ *     for why this writer cannot run `pnpm install` on the user's behalf.
+ *   - `settings.yaml`'s `llm-pi-ai.providers.<id>.baseURL` path — CONFIRMED,
+ *     not merely the plan's assumption: `dsh-llm-pi-ai`'s shipped README shows
+ *     exactly this shape overriding an EXISTING catalog route's endpoint
+ *     (`providers.openai.baseURL: https://proxy.example.com:8443`), the same
+ *     "override base_url on what already resolves, don't invent a model
+ *     picker entry" shape `grokHooks.ts`'s `[model.*]` merge uses. `llm-pi-ai`
+ *     is NOT dsh's default LLM route (`llm-deepseek`, the native DeepSeek
+ *     adapter, is — see `dsh-base`'s own `agent-default-model` row) and
+ *     mounts **dormant** until a `llm-pi-ai:` settings section exists at all,
+ *     so this override alone never redirected a fresh profile's DEFAULT
+ *     egress — it only added a selectable route.
+ *   - **TD-370 follow-up, closed this phase:** `@deepseek-ai/dsh-llm-deepseek`
+ *     (registry-public, `npm pack`ed and read directly — 0.1.0-rc.8, the
+ *     current prerelease at the time) IS the adapter `dsh-base`'s
+ *     `agent-default-model` routes through by default, and its own shipped
+ *     README CONFIRMS the same live-reload settings seam `llm-pi-ai` has:
+ *     "the plugin registers the `llm-deepseek` namespace with this same
+ *     `Config` schema ... so a `llm-deepseek:` section in the user settings
+ *     document overrides any field without a restart." {@link mergeSettingsYaml}
+ *     now also merges `llm-deepseek.baseURL`, touching only that one field
+ *     (same "override base_url on what already resolves" discipline as the
+ *     `llm-pi-ai` merge and `grokHooks.ts`'s `[model.*]` merge) — this is the
+ *     one that actually redirects DEFAULT egress. The `llm-pi-ai` merge is
+ *     kept alongside it (a selectable route remains useful), not replaced.
+ *   - The `@intutic/gate/dsh` veto contract itself (`tools/pre-execute`,
+ *     `PreToolDecision`'s real `'deny'`/`'allow'`/`'ask'` shape, Cordis's
+ *     `waterfall` `next()` semantics) is confirmed from `dsh-tools`'s shipped
+ *     `.d.ts` — see `packages/gate-js/src/dsh.ts`'s own module doc for the
+ *     full record, including where the phase brief's prior guess
+ *     (`agent/pre-step`, `{kind:'reject'}`) was wrong.
+ *
+ * HLD §3.14 — Harness Onboarding Matrix
+ * @module
+ */
+/** `$DSH_HOME` resolution: an explicit env override, else `~/.dsh` — mirrors
+ *  `dsh-home-paths`' `resolveDshHome()` (this writer has no "explicit
+ *  configured path" input the way a booted dsh process might). An
+ *  empty/whitespace-only `$DSH_HOME` is treated as unset, matching that
+ *  package's own documented behaviour. */
+export declare function resolveDshHome(): string;
+/**
+ * Every EXISTING dsh profile directory on this machine — one containing its
+ * own `package.json` (the profile manifest `dsh-app-boot` requires; a bare
+ * directory, such as the flat `profiles/node_modules` fallback dsh itself
+ * maintains, is not a profile).
+ *
+ * Deliberately does not invent a profile: dsh's own CLI requires `--profile
+ * <name>` on every invocation (confirmed from `dsh`'s shipped `bin.js` — there
+ * is no bare "default" profile dsh falls back to), so this writer has no name
+ * to seed one under that a user did not already choose. A machine with no
+ * profile initialized yet gets governed on the next sync after the user's
+ * first `dsh --profile <name>` run creates one — see the TD entry.
+ */
+export declare function listDshProfileDirs(dshHome: string): Promise<string[]>;
+export interface DshCoverageGap {
+    /** dsh appears to be installed/used on this machine (a `$DSH_HOME` marker
+     *  exists, or `dsh` is on `$PATH`) — independent of whether it is governed. */
+    dshDetected: boolean;
+    /** Number of EXISTING dsh profiles — see {@link listDshProfileDirs}. */
+    profileCount: number;
+    /** `dshDetected && profileCount === 0`: dsh is present but nothing is
+     *  governed yet — TD-370's "silent no-profile window". */
+    gap: boolean;
+}
+/**
+ * Detects TD-370's "silent no-profile window": the stretch between `intutic
+ * connect` and the user's first `dsh --profile <name>` run, during which dsh
+ * is entirely ungoverned — {@link writeDshHooks} is a documented no-op with
+ * nothing to register into yet — and, before this function existed, nothing
+ * made that visible.
+ *
+ * A pure detector, deliberately: no logging, no side effect, so it stays
+ * trivially unit-testable. `watcher/settingsGuard.ts`'s `warnIfDshCoverageGap`
+ * is the side-effecting caller that actually logs the gap.
+ */
+export declare function detectDshCoverageGap(dshHome?: string): Promise<DshCoverageGap>;
+/**
+ * Structurally merges the Intutic governance plugin row into one profile's
+ * `cordis.patch.yml`, via the `yaml` package's `parseDocument`/`setIn` — the
+ * same "parse structurally, write-if-changed, preserve unrelated content,
+ * fall back to append-only on unparseable input" discipline `injectGoose`
+ * (`mcpAutoWrite.ts`) established for YAML in this codebase, reusing the same
+ * dependency rather than inventing a second approach.
+ */
+export declare function mergeProfilePatch(profileDir: string, workspaceRoot: string, workspaceId: string): Promise<void>;
+/**
+ * Ensures `@intutic/gate` is declared in the profile's own `package.json`
+ * `dependencies` — the "out-of-tree plugin" mechanism `dsh-app-boot`'s
+ * `profile.d.ts` documents (a profile's `node_modules` is pnpm-managed).
+ *
+ * This writer declares the dependency but does NOT run `pnpm install` in the
+ * profile directory — the daemon has no general "run an arbitrary package
+ * manager in a directory it does not own" capability, and every other
+ * writer in this codebase only ever writes config, never invokes a package
+ * manager on the user's behalf. Until the user (or their own tooling) runs
+ * one, the `cordis.patch.yml` row this module also writes resolves to a
+ * MISSING module and dsh's own loader reports that row's activation failed
+ * (`assertEntriesActivated`, confirmed from `dsh-app-boot`'s exports) rather
+ * than silently no-op — a fail-LOUD gap, not a fail-open one, but a real
+ * manual step nonetheless. See the TD entry and `apps/docs/integrations/dsh.md`.
+ */
+export declare function mergeProfileDependency(profileDir: string): Promise<void>;
+/**
+ * Structurally merges the Intutic proxy into TWO `settings.yaml` sections:
+ *
+ *  - `llm-deepseek.baseURL` — dsh's ACTUAL DEFAULT LLM route (CONFIRMED
+ *    against `@deepseek-ai/dsh-llm-deepseek`'s own shipped README this
+ *    phase — see module doc). Only `baseURL` is touched; `apiKeyEnv`,
+ *    `thinking`, `models`, etc. round-trip untouched, the same
+ *    "override base_url on what already resolves, never invent the rest of
+ *    the section" discipline `grokHooks.ts`'s `[model.*]` merge uses. This
+ *    is the merge that actually redirects DEFAULT egress — see the TD entry
+ *    for why the `llm-pi-ai` merge alone (below) never did.
+ *  - `llm-pi-ai.providers.intutic` — a SELECTABLE route (mounts dormant
+ *    until this section exists at all — see module doc). Kept alongside the
+ *    new default-route merge: a user, or a future sync, can still point a
+ *    model at it explicitly.
+ *
+ * Both overrides preserve every other provider and every other top-level
+ * section untouched.
+ */
+export declare function mergeSettingsYaml(dshHome: string, proxyUrl: string): Promise<void>;
+/**
+ * Register the Intutic governance plugin against every existing dsh profile
+ * on this machine, and merge the Intutic proxy into `settings.yaml`'s
+ * `llm-deepseek` (default) and `llm-pi-ai` (selectable) routes.
+ *
+ * A no-op (logged, not an error) when `$DSH_HOME/profiles` does not exist
+ * yet — dsh has not been run with any `--profile <name>` on this machine, so
+ * there is nothing to register into; the next sync cycle picks it up once
+ * the user's first `dsh` run creates one. Safe to call every cycle: every
+ * merge below is write-if-changed.
+ *
+ * @param workspaceRoot - Absolute workspace root (stored in the plugin row's
+ *   `config.repoRoot`).
+ * @param proxyUrl       - Intutic proxy URL, merged into settings.yaml.
+ * @param workspaceId    - Workspace ID, stored in the plugin row's config.
+ */
+export declare function writeDshHooks(workspaceRoot: string, proxyUrl: string, workspaceId?: string): Promise<void>;
+//# sourceMappingURL=dshHooks.d.ts.map

package/dist/harness/dshHooks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dshHooks.d.ts","sourceRoot":"","sources":["../../src/harness/dshHooks.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2FG;AAiCH;;;;0CAI0C;AAC1C,wBAAgB,cAAc,IAAI,MAAM,CAIvC;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAgB3E;AAoBD,MAAM,WAAW,cAAc;IAC7B;mFAC+E;IAC/E,WAAW,EAAE,OAAO,CAAA;IACpB,wEAAwE;IACxE,YAAY,EAAE,MAAM,CAAA;IACpB;8DAC0D;IAC1D,GAAG,EAAE,OAAO,CAAA;CACb;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,oBAAoB,CAAC,OAAO,SAAmB,GAAG,OAAO,CAAC,cAAc,CAAC,CAQ9F;AAkED;;;;;;;GAOG;AACH,wBAAsB,iBAAiB,CAAC,UAAU,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CA4DrH;AAID;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,sBAAsB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAuB9E;AAkDD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAsB,iBAAiB,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CA4ExF;AAyED;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,aAAa,CAAC,aAAa,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,WAAW,SAAK,GAAG,OAAO,CAAC,IAAI,CAAC,CAiB5G"}