@lmzhen/dsh-evolution-commands 0.16.0 → 0.17.0-rc.1

package/lib/types/doctor.d.ts

@@ -8,9 +8,11 @@ export declare const EVOLUTION_BUNDLE_TAILS: Set<string>;
  * "absent" is the user simply not using that base (never an action); "unknown"
  * is a comparison that could not run, kept distinct from a verified "fresh". */
 export interface PresetFreshnessRow {
-    /** Agent-preset base name (the id the platform registry read() takes). */
+    /** Profile whose patch layer carries (or lacks) the row. */
+    profile: string;
+    /** Agent-preset base name — the `--base` value the row was composed for. */
     base: string;
-    /** Install destination <home>/.agent-presets/<base.id> that was compared. */
+    /** The profile patch compared: `<home>/profiles/<profile>/cordis.patch.yml`. */
     destination: string;
     status: 'fresh' | 'differs' | 'absent' | 'unknown';
     /** Why the comparison could not run — set on unknown rows only. */
@@ -39,6 +41,23 @@ export interface ScopedProbeCheck {
     /** Scoped gate evaluations that resolved false. */
     misses: number;
 }
+/** G3 (stage 8): what the family's LEGACY settings document still holds.
+
+ * Read-only: the boot migration and `/evolution migrate` write; doctor only answers whether
+ * anything is left. `none` (a document with no family section) and `absent` (no document) are
+ * different findings — the first means the values were never the family's, the second that the
+ * platform's import already took the file away.
+ */
+export interface LegacyMigrationRow {
+    /** `migrated` = every family value sits on its row; `pending` = some do not; `none` = the
+     * document carries no family section; `absent` = no legacy document under this home;
+     * `unavailable` = no settings seat or no IO seam to read through. */
+    readonly state: 'migrated' | 'pending' | 'none' | 'absent' | 'unavailable';
+    /** The document the verdict came from, when one was read. */
+    readonly source: string | undefined;
+    /** Keys still waiting for their row, as `rowId.key`. */
+    readonly pending: readonly string[];
+}
 export interface DoctorReport {
     /** OPT-23 (2026-09): `preset-only` — the delivered Evolution preset
      * artifact exists but NO profile carries an evolution bundle (e.g. the
@@ -101,6 +120,21 @@ export interface DoctorReport {
      * whose cross-session consumers are inert for every session stops looking
      * healthy. See {@link ScopedProbeCheck}. */
     scopedProbe: ScopedProbeCheck;
+    /** G3 (stage 8): the legacy settings document's remaining work. */
+    legacy: LegacyMigrationRow;
+    /** G5: the family bundles the RUNNING profile selects, per the platform's `listBundles()`;
+     * null when that surface is not mounted — `bundles` then carries the cross-profile aggregate. */
+    runtimeBundles: string[] | null;
+    /** G5: where the install form came from. `aggregate` = the cross-profile scan (the surface
+     * was absent), so the form describes every profile on the machine, not this runtime. */
+    formSource: 'platform' | 'aggregate';
+    /** G5: the platform's own preset verdicts (see {@link presetIssues}). */
+    presetIssues: string[];
+    /** G5: family bundles this profile INSTALLS without selecting them (`enabled: false`) — the
+     * plugin page lists those too, so doctor names them instead of leaving a visible mismatch. */
+    dormantBundles: string[];
+    /** G5: where the review row's presence came from: the live entry, or the aggregate inference. */
+    serviceSource: 'platform' | 'bundles';
     actions: string[];
 }
 /** Profile bundle rows for evolution-family packages across all profiles.
@@ -111,11 +145,6 @@ export interface DoctorReport {
  * list alone, and treating it as "no bundles" is exactly the fail-open state
  * the double-mount exclusion exists to prevent. */
 export declare function collectEvolutionBundles(home: string, onReadError?: (error: unknown, scope: 'profiles-dir' | 'profile-manifest') => void): string[];
-/**
- * Diagnose the deployment. `ctx` supplies service presence (a bare stub with
- * only `get` is enough); `home` defaults to the evolution root so tests can
- * point doctor at a temp DSH_HOME.
- */
 export declare function diagnose(ctx: {
     get(name: string): unknown;
 }, options?: {

package/lib/types/index.d.ts

@@ -4,6 +4,14 @@
  */
 import type { Context } from '@deepseek-ai/cordis';
 import z from '@deepseek-ai/schemastery';
+import type { ContextFormed } from '@deepseek-ai/dsh-llm';
+declare module '@deepseek-ai/dsh-llm' {
+    interface MessageSourceMap {
+        'evolution-commands': {
+            kind: 'evolution-commands';
+        } & ContextFormed;
+    }
+}
 export declare const name = "evolution-commands";
 export interface Config {
     /** Skill-tree root for maintain/restructure; empty uses the default tree.
@@ -37,19 +45,19 @@ export interface Config {
      * widens them. */
     threatExemptLabels?: string[] | undefined;
 }
-export declare const Config: z<Schemastery.ObjectS<{
-    root: z<string, string>;
-    skillsRoot: z<string, string>;
-    maintainCooldownMs: z<number, number>;
-    maintainTimeoutMs: z<number, number>;
-    threatExemptLabels: z<string[], string[]>;
-}>, Schemastery.ObjectT<{
-    root: z<string, string>;
-    skillsRoot: z<string, string>;
-    maintainCooldownMs: z<number, number>;
-    maintainTimeoutMs: z<number, number>;
-    threatExemptLabels: z<string[], string[]>;
-}>>;
+export declare const Config: z<Schemastery.ObjectS<NoInfer<{
+    root: z<string, string, "defined">;
+    skillsRoot: z<string, string, "defined">;
+    maintainCooldownMs: z<number, number, "defined">;
+    maintainTimeoutMs: z<number, number, "defined">;
+    threatExemptLabels: z<string[], string[], "defined">;
+}>>, Schemastery.ObjectT<NoInfer<{
+    root: z<string, string, "defined">;
+    skillsRoot: z<string, string, "defined">;
+    maintainCooldownMs: z<number, number, "defined">;
+    maintainTimeoutMs: z<number, number, "defined">;
+    threatExemptLabels: z<string[], string[], "defined">;
+}>>, "plain">;
 export declare function apply(ctx: Context, rawConfig?: Config): void;
 /** F-211: the fs surface atomicWriteFiles uses — injectable so the commit-phase
  * rename-failure path is deterministically testable. Defaults to node:fs.

package/lib/types/migration.d.ts

@@ -0,0 +1,104 @@
+import type { EvolutionIoLike, NamespaceMigrationPlan, NamespaceMigrationReport, SettingsProviderLike } from '@lmzhen/dsh-evolution-core';
+/**
+ * The legacy document names the platform leaves behind, in read order.
+ * @param home - the profile home the document sits in.
+ * @returns both candidate paths, the renamed import first.
+ */
+export declare function legacySettingsPaths(home: string): readonly string[];
+/** What one migration attempt found and did. */
+export interface NamespaceMigrationOutcome {
+    /** The file the plan was read from; undefined when neither name exists. */
+    readonly source: string | undefined;
+    /** The document's plan; undefined when there was no document to read. */
+    readonly plan: NamespaceMigrationPlan | undefined;
+    /** What the run wrote; undefined when the document carried nothing to move. */
+    readonly report: NamespaceMigrationReport | undefined;
+}
+/** Everything {@link runNamespaceMigration} needs from its caller. */
+export interface NamespaceMigrationRun {
+    /** The profile home the legacy document sits in. */
+    readonly home: string;
+    /** The family IO seam, for the read. */
+    readonly io: EvolutionIoLike;
+    /** The platform settings seat; undefined when the deployment has none. */
+    readonly settings: SettingsProviderLike | undefined;
+    /** Where a kept value is reported (the run always reports, never silently drops). */
+    readonly warn: (message: string) => void;
+}
+/**
+ * Read the first legacy document that exists and merge what it holds.
+ *
+ * The write goes through the platform's own `settings.update`, so the merge semantics, the
+ * revision fence and the row's schema validation are the platform's — a row whose schema
+ * refuses a key refuses the whole patch, which is why the planner refuses unknown keys
+ * before this runs.
+ * @param run - the home, the reader, the settings seat and the warning sink.
+ * @returns the source file, its plan, and what the run did (all undefined when there was
+ *   nothing to read or nowhere to write).
+ */
+export declare function runNamespaceMigration(run: NamespaceMigrationRun): Promise<NamespaceMigrationOutcome>;
+/** What the legacy document still holds, and what a row already answers for. */
+export interface LegacyDocumentState {
+    /** The document the verdict came from. */
+    readonly source: string;
+    /** How many legacy sections carried values a row can take. */
+    readonly sections: number;
+    /** Keys no row carries yet, as `rowId.key` — a run would write these. */
+    readonly pending: readonly string[];
+    /** Keys a row already answers for (equal value, or a stored value that won). */
+    readonly settled: readonly string[];
+}
+/** Everything {@link readLegacyDocumentState} reads: the home, the reader, the settings seat. */
+export interface LegacyDocumentRead {
+    /** The profile home the legacy document sits in. */
+    readonly home: string;
+    /** The family IO seam, for the read. */
+    readonly io: EvolutionIoLike;
+    /** The platform settings seat; undefined when the deployment has none. */
+    readonly settings: SettingsProviderLike | undefined;
+}
+/**
+ * Read the legacy document and report what is still unmigrated.
+ *
+ * Read-only by construction: the answer comes from the pure classifier, never from the
+ * applier, so a doctor run cannot write. `runNamespaceMigration` and this read the SAME
+ * decision, which is what keeps the report and the next run's outcome from disagreeing.
+ * @param run - the home, the reader, the settings seat.
+ * @returns the state, or undefined when there is no legacy document or no settings seat.
+ */
+export declare function readLegacyDocumentState(run: LegacyDocumentRead): Promise<LegacyDocumentState | undefined>;
+/** The context members the migration reads, structurally, so a spec needs no host. */
+export interface MigrationHost {
+    /** The service store (`settings`, `profileContext`, `evolutionIo`). */
+    get(name: string): unknown;
+    readonly logger: {
+        warn(message: string): void;
+    };
+}
+/** Why an attempt could not run: a missing prerequisite, named for the caller's message. */
+export type NamespaceMigrationProblem = 'settings' | 'home' | 'io';
+/** One attempt: either an outcome, or the prerequisite that was absent. */
+export type NamespaceMigrationAttempt = {
+    readonly ok: true;
+    readonly outcome: NamespaceMigrationOutcome;
+} | {
+    readonly ok: false;
+    readonly problem: NamespaceMigrationProblem;
+};
+/**
+ * Run the migration from a plugin context: probe the settings seat, the profile home and the
+ * IO seam, then delegate to {@link runNamespaceMigration}.
+ *
+ * The command reports `problem` as its own error text; a boot-time caller skips instead — the
+ * point of naming the missing prerequisite rather than throwing is that both readers can act.
+ * @param host - the context (services + logger).
+ * @returns the outcome, or the prerequisite that is absent.
+ */
+export declare function migrateFromContext(host: MigrationHost): Promise<NamespaceMigrationAttempt>;
+/**
+ * Render one outcome for the command surface.
+ * @param outcome - the run's result.
+ * @returns the report text (Chinese copy, the family's user-facing language).
+ */
+export declare function renderNamespaceMigration(outcome: NamespaceMigrationOutcome): string;
+//# sourceMappingURL=migration.d.ts.map

package/lib/types/params.d.ts

@@ -3,10 +3,10 @@
  * surface, so one text answers "which parameters exist, who may write them, and
  * did I already override this one".
  *
- * The join key is the OWNER PACKAGE: core's `PARAM_NAMESPACES` maps a package to
- * the one namespace it registers, and `settings.describe()` reports that
- * namespace's raw user section (a key's PRESENCE is the override) plus the
- * resolved value. Everything here is pure; the command handler supplies the data.
+ * The join key is the OWNER PACKAGE: `settings.describe()` keys a section by the Loader
+ * entry id, which is the row id (core's `paramSettingsId` names that mapping), and reports
+ * that section's raw user section (a key's PRESENCE is the override) plus the resolved
+ * value. Everything here is pure; the command handler supplies the data.
  * @module @lmzhen/dsh-evolution-commands/params
  */
 import { type ParamExposure } from '@lmzhen/dsh-evolution-core';

package/lib/types/platform-view.d.ts

@@ -0,0 +1,97 @@
+/**
+ * G5: the platform's own view of the RUNNING profile, read through the services the platform
+ * mounts — `pluginManager` (bundles, plugin rows), `configEditor` (inherited vs override) and
+ * `pluginInventory` (live rows, agent presets).
+ *
+ * Read structurally on purpose: the family declares no dependency edge into the platform's
+ * management packages, because a plane that does not mount them must render a named line, not
+ * fail to load. Every reader answers `undefined` for an absent surface; the caller says what
+ * that means, and no caller may re-derive the same facts by scanning the profile off disk — one
+ * fact has one home.
+ * @module @lmzhen/dsh-evolution-commands/platform-view
+ */
+/** One installed bundle as the platform reports it (the fields the doctor reads). */
+export interface PlatformBundle {
+    /** Package name. */
+    readonly name: string;
+    /** Selected in the profile manifest; a load error means its layer was skipped. */
+    readonly enabled: boolean;
+    /** Held by the profile's own dependencies (false = supplied by the installation). */
+    readonly installed: boolean;
+    /** Shipped for the person to switch on. */
+    readonly optional: boolean;
+    readonly removable: boolean;
+    /** Why a profile control cannot modify it, when it cannot. */
+    readonly readOnlyReason?: string;
+    /** A management failure; `code` is the platform's own discriminant. */
+    readonly error?: {
+        readonly code?: string;
+        readonly diagnostic?: string;
+    };
+    /** The rows the bundle's patch inserts. */
+    readonly rows: readonly {
+        readonly rowId: string;
+        readonly moduleName: string;
+    }[];
+    /** Ids of rows the bundle's patch changes without declaring them. */
+    readonly overrides: readonly string[];
+}
+/** One live Loader entry as the platform reports it. */
+export interface PlatformPlugin {
+    /** The Loader entry id. */
+    readonly entryId: string;
+    /** The row id the entry carries, when the platform resolved one. */
+    readonly moduleName?: string;
+    readonly enabled: boolean;
+    /** The fiber's lifecycle phase, as the platform names it. */
+    readonly fiberPhase?: string;
+}
+/** One agent preset as the platform reports it. */
+export interface PlatformPreset {
+    readonly id: string;
+    readonly name?: string;
+    readonly isDefault?: boolean;
+    /** The platform's own verdict on a preset it could not compose; absent when it is healthy. */
+    readonly broken?: string;
+    /** Composition rows; `entryId` is null for a row that declares none. `enabled` includes
+     * disabled ancestor groups, so a row the platform ships switched off is visible as such. */
+    readonly rows: readonly {
+        readonly entryId: string | null;
+        readonly moduleName?: string;
+        readonly enabled?: boolean | 'conditional';
+    }[];
+}
+/** One managed entry's two layers, as `configEditor.configuration()` reports them. */
+export interface PlatformConfiguration {
+    /** The Loader entry the layers belong to (the platform hands over the entry itself). */
+    readonly entry: {
+        readonly options?: {
+            readonly id?: string;
+            readonly name?: string;
+        };
+    };
+    /** The value the inherited layers (bundle, preset) resolve to. */
+    readonly inherited: unknown;
+    /** The user's override, when the profile patch sets one. */
+    readonly override: unknown;
+}
+/** What the running profile looks like through the platform's surfaces. */
+export interface PlatformView {
+    /** `pluginManager.listBundles()`; undefined when that service is not mounted. */
+    readonly bundles: readonly PlatformBundle[] | undefined;
+    /** `pluginManager.listPlugins()`, or the inventory's own entry list; undefined when neither. */
+    readonly plugins: readonly PlatformPlugin[] | undefined;
+    /** `configEditor.configuration()`; undefined when that service is not mounted. */
+    readonly configuration: readonly PlatformConfiguration[] | undefined;
+    /** The inventory's agent presets; undefined outside a Web composition (that row is a Web-app one). */
+    readonly presets: readonly PlatformPreset[] | undefined;
+}
+/**
+ * Read every platform surface the doctor uses.
+ * @param ctx - the context (services), read structurally.
+ * @returns the view; each member is undefined when its surface is not mounted or did not answer.
+ */
+export declare function readPlatformView(ctx: {
+    get(name: string): unknown;
+}): Promise<PlatformView>;
+//# sourceMappingURL=platform-view.d.ts.map

package/lib/types/preset-source.d.ts

@@ -0,0 +1,44 @@
+/** The launcher-owned profile facts a preset write needs. */
+export interface PresetProfileTarget {
+    /** Profile name, e.g. `web`. */
+    readonly profile: string;
+    /** Absolute profile directory. */
+    readonly profileDir: string;
+    /** Absolute path of the profile's `cordis.patch.yml` — where a new row goes. */
+    readonly patchPath: string;
+    /** Bundle package names this process started with (`startedBundles`). */
+    readonly bundles: readonly string[];
+}
+/** The patch file name inside a profile directory (`packages/boot/app-boot/src/profile.ts`,
+ * `PROFILE_PATCH_FILENAME`). */
+export declare const PROFILE_PATCH_FILENAME = "cordis.patch.yml";
+/**
+ * The profile patch this process writes into, or undefined outside a profile.
+ *
+ * `profileContext` is registered by the profile launcher only
+ * (`packages/boot/app-boot/src/profile-context.ts`); a bare library mount — the family's own specs,
+ * or a host started without a profile — has none, and then there is no file for a row to live in.
+ * @param ctx - the plugin context (a `get(name)` view is enough).
+ * @returns the target, or undefined when no profile is mounted.
+ */
+export declare function presetProfileTarget(ctx: {
+    get(name: string): unknown;
+}): PresetProfileTarget | undefined;
+/** The family preset id stem: every shipped id starts with it (`evolution-agent/bases.json`),
+ * which is what a profile carrying a family row is recognized by when the table itself cannot be
+ * read. */
+export declare const FAMILY_PRESET_ID_STEM = "evolution";
+/**
+ * Resolve the platform base preset patch one `--base` composes.
+ *
+ * The module graph is probed FIRST: a desktop/Electron host resolves the bundle package inside
+ * `app.asar`, where no file walk reaches — the platform packages are not on disk at all. The file
+ * candidates (the target profile's own `node_modules`, then the unpacked Electron resource scope,
+ * then a source checkout, then a global install, then `DSH_AGENT_PRESET_ROOT`) and the loud failure
+ * live in core's `resolveBasePresetPatch`.
+ * @param base - the base name from `evolution-agent/bases.json`.
+ * @param target - the profile target, when one is mounted.
+ * @returns the patch file's absolute path.
+ */
+export declare function resolvePresetBasePatch(base: string, target: PresetProfileTarget | undefined): string;
+//# sourceMappingURL=preset-source.d.ts.map

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@lmzhen/dsh-evolution-commands",
   "description": "Human commands for the evolution family (/evolution pending|curator|maintain|doctor) (community build)",
-  "version": "0.16.0",
+  "version": "0.17.0-rc.1",
   "publishConfig": {
     "access": "public"
   },
@@ -27,19 +27,19 @@
   "license": "MIT",
   "dependencies": {
     "@deepseek-ai/schemastery": "^3.18.1",
-    "@lmzhen/dsh-evolution-approval": "^0.16.0",
-    "@lmzhen/dsh-evolution-core": "^0.16.0",
-    "@lmzhen/dsh-evolution-maintenance": "^0.16.0"
+    "@lmzhen/dsh-evolution-approval": "^0.17.0-rc.1",
+    "@lmzhen/dsh-evolution-core": "^0.17.0-rc.1",
+    "@lmzhen/dsh-evolution-maintenance": "^0.17.0-rc.1"
   },
   "optionalDependencies": {
-    "@lmzhen/dsh-evolution-agent-preset": "^0.16.0"
+    "@lmzhen/dsh-evolution-agent-preset": "^0.17.0-rc.1"
   },
   "peerDependencies": {
     "@deepseek-ai/cordis": "^4.0.1",
-    "@deepseek-ai/dsh-commands": "^0.1.5-rc.2",
-    "@deepseek-ai/dsh-llm": "^0.1.5-rc.2"
+    "@deepseek-ai/dsh-commands": "^0.2.0-rc.1",
+    "@deepseek-ai/dsh-llm": "^0.2.0-rc.1"
   },
   "devDependencies": {
-    "@deepseek-ai/dsh-commands": "^0.1.5-rc.2"
+    "@deepseek-ai/dsh-commands": "^0.2.0-rc.1"
   }
 }