dsh-advisor 0.1.4 → 0.2.1

package/lib/tui-settings.d.ts

@@ -0,0 +1,144 @@
+/**
+ * dsh-tui settings-section seam (plan dsh-advisor-tui-settings-n9, T1) — the
+ * `tuiSettingsSections` Advisor section.
+ *
+ * dsh-tui ≥ v0.8.0 ships a `/settings` screen; optional plugins declare what
+ * is editable there by registering a SECTION over their settings namespace on
+ * the optional `tuiSettingsSections` host service
+ * (`src/dsh-adapter/settings-sections.ts` in dsh-TUI — a small host-only
+ * registry; storage + validation stay with the dsh settings service). The
+ * screen then renders the section's fields, stages edits, and writes them on
+ * save through the revision-fenced `settings.mutate` into the section's
+ * namespace user layer — for the advisor that is the already-registered
+ * `advisor` namespace (`src/settings.ts` `installAdvisorSettings`), so the
+ * section is fully writable.
+ *
+ * This module is the advisor's settings-seam surface:
+ * `installTuiSettingsSection` conditionally injects `tuiSettingsSections` and
+ * registers {@link ADVISOR_TUI_SETTINGS_SECTION} when the service exists; a
+ * profile without the `dsh-tui-settings-sections` row (dsh-tui < v0.8.0, or
+ * any non-TUI host) gets a clean no-op. The provider shapes are minimal LOCAL
+ * structural copies of the dsh-TUI types — the advisor MUST NOT import
+ * `@deepseek-harness-tui/dsh-tui` (zero new peers, plan Global Constraint),
+ * so drift against the upstream shape is bounded to the structural cast at
+ * the inject boundary and pinned by `tests/tui-settings.test.ts`.
+ *
+ * Upstream revision pin: the structural shapes mirror
+ * `@deepseek-harness-tui/dsh-tui` v0.8.0 (`src/dsh-adapter/settings-sections.ts`,
+ * dsh-TUI commit `02ff08e`). Residual drift window: an upstream
+ * addition/rename of a REQUIRED field would NOT fail the structural cast (the
+ * cast goes through `unknown`) and could cause host-side misrender rather than
+ * a compile error — re-verify against the dsh-TUI repo when bumping.
+ *
+ * Field subset (grill-me locked): the section covers the five SAFE §5.1 keys
+ * (`enabled` / `provider` / `model` / `immuneTurns` / `maxDeltaMessages`).
+ * `systemPrompt` is intentionally NOT a field — the TUI `text` control is
+ * single-line, and editing a multi-line prompt there would truncate/replace
+ * it (data loss). It stays editable via the web card or
+ * `$DSH_HOME/settings.yaml`. The TUI seam has no cross-field validation
+ * (upstream behavior, recorded): a save may set `enabled: true` with empty
+ * `provider`/`model`, which the S4 explicit model gate (spec §5.2) resolves
+ * to disabled-with-reason at runtime; the settings-service schema
+ * re-validation on mutate is the value-level backstop (a non-schema value
+ * fails the whole save before persist).
+ *
+ * @module dsh-advisor/tui-settings
+ */
+import type { Context } from '@deepseek-ai/cordis';
+/** Localized (zh/en) descriptions — structural mirror of dsh-TUI's
+ * `LocalizedDescriptions` (the `/settings` section + field labels/hints). */
+export type TuiLocalizedDescriptions = Readonly<Partial<Record<'zh' | 'en', string>>>;
+/** One `kind: 'select'` choice — structural mirror of dsh-TUI's
+ * `TuiSettingsFieldOption`. */
+export interface TuiSettingsFieldOption {
+    /** Stored value. */
+    value: string;
+    /** Display label (English; also the fallback). */
+    label: string;
+    /** Provider-owned translations for the label. */
+    descriptions?: TuiLocalizedDescriptions;
+}
+/** The write one field's draft stages when the section is saved — structural
+ * mirror of dsh-TUI's `TuiSettingsFieldWrite`. */
+export type TuiSettingsFieldWrite = {
+    kind: 'set';
+    value: unknown;
+} | {
+    kind: 'clear';
+};
+/** One editable field inside a section — structural mirror of dsh-TUI's
+ * `TuiSettingsField`. `path` uses the settings-service `mutate` path
+ * vocabulary (object keys); the advisor's §5.1 flat keys map directly as
+ * single-element paths. */
+export interface TuiSettingsField {
+    /** Key path from the section root, in the settings service's `mutate` path
+     * vocabulary (object keys; dict keys name their entry directly). */
+    path: readonly string[];
+    /** Short field label (English; also the fallback). */
+    label: string;
+    /** Provider-owned translations for the label. */
+    descriptions?: TuiLocalizedDescriptions;
+    /** Optional one-line help rendered under the field. */
+    hint?: string;
+    /** Provider-owned translations for the hint. */
+    hintDescriptions?: TuiLocalizedDescriptions;
+    kind: 'text' | 'number' | 'boolean' | 'select';
+    /** Choices for `kind: 'select'` (ignored otherwise). */
+    options?: readonly TuiSettingsFieldOption[];
+    /** Input placeholder for `kind: 'text' | 'number'`. */
+    placeholder?: string;
+    /** Credential control (mirrors the web cards' CardSecretSpec). */
+    secret?: {
+        ref: string;
+    };
+    /** Render a stored value as draft text (defaults to the kind's conversion). */
+    format?(value: unknown): string;
+    /** The write this draft text stages, or `undefined` when the text is not a
+     * value this field accepts (defaults to the kind's conversion — an empty
+     * text/number draft stages a clear, re-inheriting the composition layer). */
+    parse?(text: string): TuiSettingsFieldWrite | undefined;
+}
+/** One plugin's section inside the TUI `/settings` screen — structural mirror
+ * of dsh-TUI's `TuiSettingsSection`. */
+export interface TuiSettingsSection {
+    /** Settings namespace this section edits; the screen marks the section
+     * unavailable when the composition serves no such namespace. */
+    ns: string;
+    /** Section title (English; also the fallback). */
+    title: string;
+    /** Provider-owned translations for the title. */
+    descriptions?: TuiLocalizedDescriptions;
+    /** Editable fields, in display order. */
+    fields: readonly TuiSettingsField[];
+}
+/** The `tuiSettingsSections` host service key — the ONE name the T1
+ * registration condition (`installTuiSettingsSection`'s inject) and the T2
+ * hint truthfulness probe (`getConfig`'s `ctx.get`) are both keyed on. Shared
+ * so the registration condition and the render-time hint can never drift
+ * apart (S-001, plan QC fix wave). */
+export declare const TUI_SETTINGS_SECTIONS = "tuiSettingsSections";
+/** Test-friendly alias for the section namespace (`'advisor'`). The section
+ * itself reuses the shared {@link ADVISOR_SETTINGS_NAMESPACE} brand — a
+ * mismatched ns would silently render the section "unavailable" in the host
+ * screen (the alias exists so tests can pin the value without importing the
+ * settings module's brand). */
+export declare const ADVISOR_TUI_SETTINGS_NS = "advisor";
+/** The declared "Advisor" section for the dsh-tui `/settings` screen: the
+ * five safe §5.1 keys (enabled/provider/model/immuneTurns/maxDeltaMessages)
+ * with zh/en labels + hints. Field paths are single-element §5.1 flat keys,
+ * so staged edits map 1:1 onto the namespace `mutate` paths. */
+export declare const ADVISOR_TUI_SETTINGS_SECTION: TuiSettingsSection;
+/**
+ * Install the advisor's TUI settings-section surface: register the "Advisor"
+ * section on `tuiSettingsSections` when the host service exists (conditional
+ * inject; absent service → clean no-op). Called from `apply()` AFTER the
+ * single-reviewer claim (next to `installTuiClient`), so the section registers
+ * at most once per process. The structural accessor keeps the inject key in
+ * the standard position: the cordis Context has no `tuiSettingsSections`
+ * augmentation in this repo, so the service is read through a local
+ * structural cast. The inject child's return value (the registry disposer)
+ * is the child's own effect disposer, so the section withdraws when this
+ * fiber (or the service) goes away; a duplicate-ns registration is contained
+ * (debug log + no-op disposer, never throws — multi-fiber dedupe).
+ */
+export declare function installTuiSettingsSection(ctx: Context): void;

package/lib/tui-settings.js

@@ -0,0 +1,145 @@
+/**
+ * dsh-tui settings-section seam (plan dsh-advisor-tui-settings-n9, T1) — the
+ * `tuiSettingsSections` Advisor section.
+ *
+ * dsh-tui ≥ v0.8.0 ships a `/settings` screen; optional plugins declare what
+ * is editable there by registering a SECTION over their settings namespace on
+ * the optional `tuiSettingsSections` host service
+ * (`src/dsh-adapter/settings-sections.ts` in dsh-TUI — a small host-only
+ * registry; storage + validation stay with the dsh settings service). The
+ * screen then renders the section's fields, stages edits, and writes them on
+ * save through the revision-fenced `settings.mutate` into the section's
+ * namespace user layer — for the advisor that is the already-registered
+ * `advisor` namespace (`src/settings.ts` `installAdvisorSettings`), so the
+ * section is fully writable.
+ *
+ * This module is the advisor's settings-seam surface:
+ * `installTuiSettingsSection` conditionally injects `tuiSettingsSections` and
+ * registers {@link ADVISOR_TUI_SETTINGS_SECTION} when the service exists; a
+ * profile without the `dsh-tui-settings-sections` row (dsh-tui < v0.8.0, or
+ * any non-TUI host) gets a clean no-op. The provider shapes are minimal LOCAL
+ * structural copies of the dsh-TUI types — the advisor MUST NOT import
+ * `@deepseek-harness-tui/dsh-tui` (zero new peers, plan Global Constraint),
+ * so drift against the upstream shape is bounded to the structural cast at
+ * the inject boundary and pinned by `tests/tui-settings.test.ts`.
+ *
+ * Upstream revision pin: the structural shapes mirror
+ * `@deepseek-harness-tui/dsh-tui` v0.8.0 (`src/dsh-adapter/settings-sections.ts`,
+ * dsh-TUI commit `02ff08e`). Residual drift window: an upstream
+ * addition/rename of a REQUIRED field would NOT fail the structural cast (the
+ * cast goes through `unknown`) and could cause host-side misrender rather than
+ * a compile error — re-verify against the dsh-TUI repo when bumping.
+ *
+ * Field subset (grill-me locked): the section covers the five SAFE §5.1 keys
+ * (`enabled` / `provider` / `model` / `immuneTurns` / `maxDeltaMessages`).
+ * `systemPrompt` is intentionally NOT a field — the TUI `text` control is
+ * single-line, and editing a multi-line prompt there would truncate/replace
+ * it (data loss). It stays editable via the web card or
+ * `$DSH_HOME/settings.yaml`. The TUI seam has no cross-field validation
+ * (upstream behavior, recorded): a save may set `enabled: true` with empty
+ * `provider`/`model`, which the S4 explicit model gate (spec §5.2) resolves
+ * to disabled-with-reason at runtime; the settings-service schema
+ * re-validation on mutate is the value-level backstop (a non-schema value
+ * fails the whole save before persist).
+ *
+ * @module dsh-advisor/tui-settings
+ */
+import { ADVISOR_SETTINGS_NAMESPACE } from './settings.js';
+/** The `tuiSettingsSections` host service key — the ONE name the T1
+ * registration condition (`installTuiSettingsSection`'s inject) and the T2
+ * hint truthfulness probe (`getConfig`'s `ctx.get`) are both keyed on. Shared
+ * so the registration condition and the render-time hint can never drift
+ * apart (S-001, plan QC fix wave). */
+export const TUI_SETTINGS_SECTIONS = 'tuiSettingsSections';
+/** Test-friendly alias for the section namespace (`'advisor'`). The section
+ * itself reuses the shared {@link ADVISOR_SETTINGS_NAMESPACE} brand — a
+ * mismatched ns would silently render the section "unavailable" in the host
+ * screen (the alias exists so tests can pin the value without importing the
+ * settings module's brand). */
+export const ADVISOR_TUI_SETTINGS_NS = 'advisor';
+/** The declared "Advisor" section for the dsh-tui `/settings` screen: the
+ * five safe §5.1 keys (enabled/provider/model/immuneTurns/maxDeltaMessages)
+ * with zh/en labels + hints. Field paths are single-element §5.1 flat keys,
+ * so staged edits map 1:1 onto the namespace `mutate` paths. */
+export const ADVISOR_TUI_SETTINGS_SECTION = {
+    ns: ADVISOR_SETTINGS_NAMESPACE,
+    title: 'Advisor',
+    descriptions: {
+        zh: '顾问评审设置',
+        en: 'Advisor settings',
+    },
+    fields: [
+        {
+            path: ['enabled'],
+            kind: 'boolean',
+            label: 'Enabled',
+            descriptions: { zh: '启用', en: 'Enabled' },
+            hint: 'Master switch for the advisor.',
+            hintDescriptions: { zh: '顾问总开关。', en: 'Master switch for the advisor.' },
+        },
+        {
+            path: ['provider'],
+            kind: 'text',
+            label: 'Provider',
+            descriptions: { zh: 'Provider', en: 'Provider' },
+            hint: 'Provider route; required (non-empty) when enabled.',
+            hintDescriptions: { zh: 'Provider 路由；启用时必须非空。', en: 'Provider route; required (non-empty) when enabled.' },
+            placeholder: 'e.g. deepseek-official',
+        },
+        {
+            path: ['model'],
+            kind: 'text',
+            label: 'Model',
+            descriptions: { zh: 'Model', en: 'Model' },
+            hint: 'Model id; required (non-empty) when enabled.',
+            hintDescriptions: { zh: '模型 ID；启用时必须非空。', en: 'Model id; required (non-empty) when enabled.' },
+            placeholder: 'e.g. deepseek-v4-flash',
+        },
+        {
+            path: ['immuneTurns'],
+            kind: 'number',
+            label: 'Immune turns',
+            descriptions: { zh: '免疫轮数', en: 'Immune turns' },
+            hint: 'Cooldown after a delivered interrupt (integer ≥ 0).',
+            hintDescriptions: { zh: '投递一次建议后的冷却轮数（整数 ≥ 0）。', en: 'Cooldown after a delivered interrupt (integer ≥ 0).' },
+        },
+        {
+            path: ['maxDeltaMessages'],
+            kind: 'number',
+            label: 'Max delta messages',
+            descriptions: { zh: '最大增量消息数', en: 'Max delta messages' },
+            hint: 'Delta window (integer ≥ 0; 0 = unbounded).',
+            hintDescriptions: { zh: '增量窗口（整数 ≥ 0；0 = 不限）。', en: 'Delta window (integer ≥ 0; 0 = unbounded).' },
+        },
+    ],
+};
+/**
+ * Install the advisor's TUI settings-section surface: register the "Advisor"
+ * section on `tuiSettingsSections` when the host service exists (conditional
+ * inject; absent service → clean no-op). Called from `apply()` AFTER the
+ * single-reviewer claim (next to `installTuiClient`), so the section registers
+ * at most once per process. The structural accessor keeps the inject key in
+ * the standard position: the cordis Context has no `tuiSettingsSections`
+ * augmentation in this repo, so the service is read through a local
+ * structural cast. The inject child's return value (the registry disposer)
+ * is the child's own effect disposer, so the section withdraws when this
+ * fiber (or the service) goes away; a duplicate-ns registration is contained
+ * (debug log + no-op disposer, never throws — multi-fiber dedupe).
+ */
+export function installTuiSettingsSection(ctx) {
+    ctx.inject([TUI_SETTINGS_SECTIONS], (tctx) => {
+        const sections = tctx.tuiSettingsSections;
+        if (sections === undefined)
+            return;
+        try {
+            return sections.register(ADVISOR_TUI_SETTINGS_SECTION);
+        }
+        catch (error) {
+            if (!(error instanceof Error) || !error.message.includes('already registered'))
+                throw error;
+            tctx.logger('advisor').debug('advisor tui settings section already registered — no section on this fiber (multi-fiber dedupe)');
+            return () => { };
+        }
+    });
+}
+//# sourceMappingURL=tui-settings.js.map

package/lib/tui-settings.js.map

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

package/lib/tui.d.ts

@@ -0,0 +1,60 @@
+/**
+ * dsh-tui client surface (plan dsh-advisor-tui-client-n8, T1) — the
+ * `tuiCommandTrees` /advisor provider.
+ *
+ * In a `dsh --profile dsh-tui` terminal session the plugin's `/advisor`
+ * command (registered through the conditional `ctx.inject(['commands'], ...)`
+ * child) already lands in the TUI `/` menu via the command-registry merge.
+ * What the TUI cannot infer is the LOCALIZED row description and the typed
+ * subcommand COMPLETION — those come from the optional `tuiCommandTrees`
+ * host service (`src/dsh-adapter/command-trees.ts` in dsh-TUI): a provider
+ * declares `root`, zh/en `descriptions`, and a `children(canonicalPath)`
+ * completion tree (root at index 0; the TUI asks at depth 2 when completing
+ * `/advisor <sub> ⋯`).
+ *
+ * This module is the advisor's TUI seam: `installTuiClient` conditionally
+ * injects `tuiCommandTrees` and registers the `/advisor` tree when the
+ * service exists; a profile without the `dsh-tui-command-trees` row (or any
+ * non-TUI host) gets a clean no-op. The provider shapes are minimal LOCAL
+ * structural copies of the dsh-TUI types — the advisor MUST NOT import
+ * `@deepseek-harness-tui/dsh-tui` (zero new peers, plan Global Constraint),
+ * so drift against the upstream shape is bounded to the structural cast at
+ * the inject boundary and pinned by `tests/tui-client.test.ts`.
+ *
+ * @module dsh-advisor/tui
+ */
+import type { Context } from '@deepseek-ai/cordis';
+/** Localized (zh/en) descriptions — structural mirror of dsh-TUI's
+ * `LocalizedDescriptions` (the TUI `/` row + completion descriptions). */
+export type TuiLocalizedDescriptions = Readonly<Partial<Record<'zh' | 'en', string>>>;
+/** One completion node — structural mirror of dsh-TUI's
+ * `CommandCompletionNode` (`src/commands.ts` in dsh-TUI). */
+export interface TuiCommandCompletionNode {
+    name: string;
+    aliases?: readonly string[];
+    description: string;
+    descriptions?: TuiLocalizedDescriptions;
+    tag?: string;
+    descriptionKey?: string;
+}
+/** A `/`-menu command tree provider — structural mirror of dsh-TUI's
+ * `TuiCommandTreeProvider`. `children` receives the canonical path with the
+ * root at index 0. */
+export interface TuiCommandTreeProvider {
+    root: string;
+    descriptions?: TuiLocalizedDescriptions;
+    children(canonicalPath: readonly string[]): readonly TuiCommandCompletionNode[];
+}
+/** The `/advisor` tree root (matches the command registry name). */
+export declare const ADVISOR_TUI_ROOT = "advisor";
+/**
+ * Install the advisor's TUI client surface: register the `/advisor`
+ * `tuiCommandTrees` provider when the host service exists (conditional
+ * inject; absent service → clean no-op). Called from `apply()` AFTER the
+ * single-reviewer claim, so the tree registers at most once per process
+ * (a duplicate-root registration would throw in the host registry). The
+ * structural accessor keeps the inject key in the standard position: the
+ * cordis Context has no `tuiCommandTrees` augmentation in this repo, so the
+ * service is read through a local structural cast.
+ */
+export declare function installTuiClient(ctx: Context): void;

package/lib/tui.js

@@ -0,0 +1,113 @@
+/**
+ * dsh-tui client surface (plan dsh-advisor-tui-client-n8, T1) — the
+ * `tuiCommandTrees` /advisor provider.
+ *
+ * In a `dsh --profile dsh-tui` terminal session the plugin's `/advisor`
+ * command (registered through the conditional `ctx.inject(['commands'], ...)`
+ * child) already lands in the TUI `/` menu via the command-registry merge.
+ * What the TUI cannot infer is the LOCALIZED row description and the typed
+ * subcommand COMPLETION — those come from the optional `tuiCommandTrees`
+ * host service (`src/dsh-adapter/command-trees.ts` in dsh-TUI): a provider
+ * declares `root`, zh/en `descriptions`, and a `children(canonicalPath)`
+ * completion tree (root at index 0; the TUI asks at depth 2 when completing
+ * `/advisor <sub> ⋯`).
+ *
+ * This module is the advisor's TUI seam: `installTuiClient` conditionally
+ * injects `tuiCommandTrees` and registers the `/advisor` tree when the
+ * service exists; a profile without the `dsh-tui-command-trees` row (or any
+ * non-TUI host) gets a clean no-op. The provider shapes are minimal LOCAL
+ * structural copies of the dsh-TUI types — the advisor MUST NOT import
+ * `@deepseek-harness-tui/dsh-tui` (zero new peers, plan Global Constraint),
+ * so drift against the upstream shape is bounded to the structural cast at
+ * the inject boundary and pinned by `tests/tui-client.test.ts`.
+ *
+ * @module dsh-advisor/tui
+ */
+/** The `/advisor` tree root (matches the command registry name). */
+export const ADVISOR_TUI_ROOT = 'advisor';
+/** The four typed `/advisor` subcommands surfaced as completion children.
+ * Bare `/advisor` (toggle) is the empty-argument default, not a completion
+ * child (compass S1); `USAGE` is the unknown-subcommand fallback, not a
+ * named command. */
+const ADVISOR_SUBCOMMANDS = ['on', 'off', 'status', 'config'];
+/** zh/en copy for the `/` menu row (shown via the host's `descriptions(root)`). */
+const ADVISOR_TUI_DESCRIPTIONS = {
+    zh: '按会话运行的评审顾问：开启 / 关闭 / 状态 / 配置',
+    en: 'Per-session advisor: enable, disable, status, or config',
+};
+/** zh/en copy per completion node. `description` is the plain fallback the
+ * node carries; `descriptions` is the localized map the TUI prefers. */
+const SUBCOMMAND_DESCRIPTIONS = {
+    on: {
+        description: 'Enable the advisor for this session',
+        descriptions: {
+            zh: '为本会话启用顾问',
+            en: 'Enable the advisor for this session',
+        },
+    },
+    off: {
+        description: 'Disable the advisor for this session',
+        descriptions: {
+            zh: '为本会话禁用顾问',
+            en: 'Disable the advisor for this session',
+        },
+    },
+    status: {
+        description: 'Show per-session advisor status (state, model, runtime, pending, last activity)',
+        descriptions: {
+            zh: '查看本会话顾问状态（开关、模型、运行态、待处理、最近活动）',
+            en: 'Show per-session advisor status (state, model, runtime, pending, last activity)',
+        },
+    },
+    config: {
+        description: 'Show the composed advisor config (settings readback)',
+        descriptions: {
+            zh: '查看组合后的顾问配置（设置回读）',
+            en: 'Show the composed advisor config (settings readback)',
+        },
+    },
+};
+/** The `/advisor` completion tree. `children` NEVER throws: unknown paths and
+ * a bare `[]` return an empty list (leaves have no deeper completion — the
+ * TUI asks at depth 2). */
+const advisorTree = {
+    root: ADVISOR_TUI_ROOT,
+    descriptions: ADVISOR_TUI_DESCRIPTIONS,
+    children(canonicalPath) {
+        // Root at index 0: only `['advisor']` asks for the subcommand list.
+        if (canonicalPath.length !== 1 || canonicalPath[0] !== ADVISOR_TUI_ROOT)
+            return [];
+        return ADVISOR_SUBCOMMANDS.map((name) => ({
+            name,
+            description: SUBCOMMAND_DESCRIPTIONS[name].description,
+            descriptions: SUBCOMMAND_DESCRIPTIONS[name].descriptions,
+        }));
+    },
+};
+/**
+ * Install the advisor's TUI client surface: register the `/advisor`
+ * `tuiCommandTrees` provider when the host service exists (conditional
+ * inject; absent service → clean no-op). Called from `apply()` AFTER the
+ * single-reviewer claim, so the tree registers at most once per process
+ * (a duplicate-root registration would throw in the host registry). The
+ * structural accessor keeps the inject key in the standard position: the
+ * cordis Context has no `tuiCommandTrees` augmentation in this repo, so the
+ * service is read through a local structural cast.
+ */
+export function installTuiClient(ctx) {
+    ctx.inject(['tuiCommandTrees'], (tctx) => {
+        const trees = tctx.tuiCommandTrees;
+        if (trees === undefined)
+            return;
+        try {
+            return trees.register(advisorTree);
+        }
+        catch (error) {
+            if (!(error instanceof Error) || !error.message.includes('already registered'))
+                throw error;
+            tctx.logger('advisor').debug('advisor tui tree already registered — no tree on this fiber (multi-fiber dedupe)');
+            return () => { };
+        }
+    });
+}
+//# sourceMappingURL=tui.js.map

package/lib/tui.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tui.js","sourceRoot":"","sources":["../src/tui.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AA4BH,oEAAoE;AACpE,MAAM,CAAC,MAAM,gBAAgB,GAAG,SAAS,CAAA;AAEzC;;;oBAGoB;AACpB,MAAM,mBAAmB,GAAG,CAAC,IAAI,EAAE,KAAK,EAAE,QAAQ,EAAE,QAAQ,CAAU,CAAA;AAItE,mFAAmF;AACnF,MAAM,wBAAwB,GAA6B;IACzD,EAAE,EAAE,8BAA8B;IAClC,EAAE,EAAE,yDAAyD;CAC9D,CAAA;AAED;wEACwE;AACxE,MAAM,uBAAuB,GAAyG;IACpI,EAAE,EAAE;QACF,WAAW,EAAE,qCAAqC;QAClD,YAAY,EAAE;YACZ,EAAE,EAAE,UAAU;YACd,EAAE,EAAE,qCAAqC;SAC1C;KACF;IACD,GAAG,EAAE;QACH,WAAW,EAAE,sCAAsC;QACnD,YAAY,EAAE;YACZ,EAAE,EAAE,UAAU;YACd,EAAE,EAAE,sCAAsC;SAC3C;KACF;IACD,MAAM,EAAE;QACN,WAAW,EAAE,iFAAiF;QAC9F,YAAY,EAAE;YACZ,EAAE,EAAE,+BAA+B;YACnC,EAAE,EAAE,iFAAiF;SACtF;KACF;IACD,MAAM,EAAE;QACN,WAAW,EAAE,sDAAsD;QACnE,YAAY,EAAE;YACZ,EAAE,EAAE,kBAAkB;YACtB,EAAE,EAAE,sDAAsD;SAC3D;KACF;CACF,CAAA;AAED;;2BAE2B;AAC3B,MAAM,WAAW,GAA2B;IAC1C,IAAI,EAAE,gBAAgB;IACtB,YAAY,EAAE,wBAAwB;IACtC,QAAQ,CAAC,aAAgC;QACvC,oEAAoE;QACpE,IAAI,aAAa,CAAC,MAAM,KAAK,CAAC,IAAI,aAAa,CAAC,CAAC,CAAC,KAAK,gBAAgB;YAAE,OAAO,EAAE,CAAA;QAClF,OAAO,mBAAmB,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;YACxC,IAAI;YACJ,WAAW,EAAE,uBAAuB,CAAC,IAAI,CAAC,CAAC,WAAW;YACtD,YAAY,EAAE,uBAAuB,CAAC,IAAI,CAAC,CAAC,YAAY;SACzD,CAAC,CAAC,CAAA;IACL,CAAC;CACF,CAAA;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,gBAAgB,CAAC,GAAY;IAC3C,GAAG,CAAC,MAAM,CAAC,CAAC,iBAAiB,CAAC,EAAE,CAAC,IAAI,EAAE,EAAE;QACvC,MAAM,KAAK,GAAI,IAA6F,CAAC,eAAe,CAAA;QAC5H,IAAI,KAAK,KAAK,SAAS;YAAE,OAAM;QAC/B,IAAI,CAAC;YACH,OAAO,KAAK,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAA;QACpC,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,IAAI,CAAC,CAAC,KAAK,YAAY,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,oBAAoB,CAAC;gBAAE,MAAM,KAAK,CAAA;YAC3F,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,KAAK,CAAC,kFAAkF,CAAC,CAAA;YAChH,OAAO,GAAG,EAAE,GAAE,CAAC,CAAA;QACjB,CAAC;IACH,CAAC,CAAC,CAAA;AACJ,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-advisor",
-  "version": "0.1.4",
+  "version": "0.2.1",
   "type": "module",
   "description": "dsh plugin bundle porting the omp advisor subsystem: a per-session reviewer model that observes the primary transcript and injects severity-ranked advice (nit/concern/blocker).",
   "repository": {