@deepseek-ai/dsh-client-ui-plugin-manager 0.1.6-alpha.2

package/lib/types/client/manager-store.d.ts

@@ -0,0 +1,330 @@
+/**
+ * The plugin manager's state: the Host's bundles joined with its plugin
+ * entries, the action in flight, the install run, and the confirmation an
+ * uninstall waits on. Every fact comes from the Host — the store re-reads
+ * after each action and after every `plugin-manager/changed` event, so a
+ * change made on another surface shows here without a manual refresh.
+ */
+import type { Context as ClientContext } from '@deepseek-ai/cordis';
+import type { BundleInfo, ManagementError, PluginEntryId, PluginInfo, PluginInspectProblem, PluginInstallFailureKind, PluginInstallLogChunk, PluginInstallProgress, PluginInstallRequestId, PluginSpecInspection, ReadOnlyReason } from '@deepseek-ai/dsh-api-remotes/client';
+import { type SnapshotStore } from '@deepseek-ai/dsh-client-store';
+import type { HostObservable } from '@deepseek-ai/dsh-client-ui-slots';
+import type { ConfigLedger } from './config-ledger.ts';
+/** The action a failed notice names. */
+export type FailedAction = 'enable' | 'disable' | 'uninstall' | 'rowEnable' | 'rowDisable';
+/** What the last action left to say, shown as a toast; `seq` tells one showing from the next. */
+export type ManagerNotice = {
+    readonly kind: 'restart';
+    readonly packageName: string;
+    readonly seq: number;
+} | {
+    readonly kind: 'overridden';
+    readonly packageName: string;
+    readonly seq: number;
+} | {
+    readonly kind: 'cancelled';
+    readonly seq: number;
+} | {
+    readonly kind: 'failed';
+    /** What was being done when it failed. */
+    readonly action: FailedAction;
+    /** The Host's refusal, when the Host refused; absent when the transport failed. */
+    readonly code?: ManagementError['code'];
+    /** The Host's diagnostic or the transport's words, shown verbatim; empty when the code says it all. */
+    readonly reason: string;
+    readonly packageName?: string;
+    readonly seq: number;
+};
+/** One row a bundle contributes, as the page lists it: the patch's declaration joined with its live entry. */
+export interface PackageRow {
+    /** The Loader entry carrying the row while the bundle is on; absent for a row of a bundle that is off. */
+    readonly entryId?: PluginEntryId;
+    /** The row id as the bundle declares it. */
+    readonly rowId: string;
+    /** The module the row names. */
+    readonly moduleName: string;
+    /** Whether the entry runs; false for a row without a live entry. */
+    readonly enabled: boolean;
+    /** The entry's fiber phase, null without a live fiber. */
+    readonly phase: PluginInfo['fiberPhase'];
+    /** Why the Host refuses to switch the row, when it does. */
+    readonly readOnlyReason?: ReadOnlyReason;
+}
+/** One bundle as the page shows it: the Host's bundle joined with the entries its rows run as. */
+export interface PackageView {
+    readonly name: string;
+    readonly version?: string;
+    readonly description?: string;
+    /** Whether the profile's own dependencies hold the package; false for a bundle the installation supplies. */
+    readonly installed: boolean;
+    /** Whether the installation ships the bundle for the person to switch on: official, off until selected, never removable. */
+    readonly optional: boolean;
+    /** Whether the bundle is in the profile's layer list. */
+    readonly enabled: boolean;
+    /** Why the Host refuses to switch the bundle off or remove it, when it does. */
+    readonly readOnlyReason?: ReadOnlyReason;
+    /** Why the Host cannot read the bundle, when it cannot. */
+    readonly error?: ManagementError;
+    readonly rows: readonly PackageRow[];
+}
+/** The typed spec as the Host read it, on the installing, installed, and failed screens. */
+export type InstallSubject = Extract<PluginSpecInspection, {
+    status: 'accepted';
+}> & {
+    readonly spec: string;
+};
+/** Why the typed spec was refused before anything installed. */
+export interface InstallInputError {
+    readonly problem: PluginInspectProblem;
+    readonly reason: string;
+}
+/** One pnpm run of an install, as the dialog's terminal draws it. */
+export interface InstallRun {
+    readonly jobId: string;
+    /** The command line the Host ran, space-joined. */
+    readonly command: string;
+    /** The directory the Host ran pnpm in: the profile directory. */
+    readonly cwd: string;
+    /** stdout and stderr interleaved as they arrived, pnpm's colour escapes included. */
+    readonly output: string;
+    /** pnpm's exit code once the run settled, null when it ended by a signal or never started; absent while it runs. */
+    readonly exitCode?: number | null;
+}
+/**
+ * The install dialog: the spec is typed while `idle`, read by the Host while
+ * `checking`, then installed through the Host-owned phases — `starting` until
+ * the Host acknowledges the run, `running`, `cancelling` while the Host stops
+ * it, `applying` once the bundle is being loaded, which closed the cancellation
+ * window — and the outcome shown as `done` or `failed`. A refused check, a
+ * confirmed cancellation, and the back control return to `idle` with the spec kept.
+ */
+export interface InstallState {
+    readonly open: boolean;
+    /** The package spec as typed. */
+    readonly spec: string;
+    readonly phase: 'idle' | 'checking' | 'starting' | 'running' | 'cancelling' | 'applying' | 'done' | 'failed';
+    /** Identifies this dialog's installation, including log and cancellation messages. */
+    readonly requestId?: PluginInstallRequestId;
+    /** Why the spec was refused before installing; shown under the field. */
+    readonly inputError: InstallInputError | null;
+    /** What the spec names, once the Host has read it. */
+    readonly subject: InstallSubject | null;
+    /** The pnpm runs of the open install, in the order they started. */
+    readonly runs: readonly InstallRun[];
+    /** Whether the run's command and output are unfolded. */
+    readonly detailsOpen: boolean;
+    /** The bundle the finished run added, left off until enabled from the installed screen. */
+    readonly installed: string | null;
+    /** Whether the finished run's bundle waits for the next start to load. */
+    readonly restartRequired: boolean;
+    /**
+     * The run's failure, once one settled the dialog: the Host's refusal
+     * `code` with its diagnostic as `reason`, or the transport's words alone;
+     * `kind` classifies a pnpm failure, and `pendingBuilds` names the packages
+     * whose install scripts pnpm left undecided, offered for approval.
+     * `cancelUnconfirmed` is a stop the Host did not confirm, shown over the
+     * running screen while the run goes on.
+     */
+    readonly failure: {
+        readonly reason: string;
+        readonly code?: ManagementError['code'];
+        readonly kind?: PluginInstallFailureKind;
+        readonly pendingBuilds?: readonly string[];
+        readonly cancelUnconfirmed?: true;
+    } | null;
+    /** The packages whose install scripts the finished run was allowed to execute, saved for this profile. */
+    readonly approvedBuilds: readonly string[];
+    /** Enabling the newly installed bundle from the installed screen is crossing the wire. */
+    readonly enabling: boolean;
+}
+/**
+ * Whether an installation is still owned by the Host.
+ * @param phase - the dialog's current installation phase.
+ * @returns true until an authoritative result settles the installation.
+ */
+export declare function isInstallPending(phase: InstallState['phase']): boolean;
+/** A destructive action waiting for the user's confirmation: a package's uninstall. */
+export interface ConfirmState {
+    readonly action: 'uninstall';
+    readonly packageName: string;
+}
+/** What the tab renders. */
+export interface PluginManagerState {
+    /** `unavailable` when the Host runs without a managed profile; `error` keeps the last packages. */
+    readonly status: 'idle' | 'loading' | 'ready' | 'error' | 'unavailable';
+    readonly packages: readonly PackageView[];
+    /** Package names and row keys with an action crossing the wire. */
+    readonly busy: readonly string[];
+    readonly notice: ManagerNotice | null;
+    readonly install: InstallState;
+    readonly confirm: ConfirmState | null;
+    /** The package the list scrolls to and marks, once an install enabled it. */
+    readonly highlight: string | null;
+}
+/** The registration-side face the tab's slot entry injects. */
+export interface PluginManagerFace {
+    hooks: {
+        /** Tab snapshot bound by the renderer as usePluginManager. */
+        pluginManager: SnapshotStore<PluginManagerState>;
+        /** The plugins carrying configuration, bound by the renderer as useConfigLedger. */
+        configLedger: HostObservable<ConfigLedger>;
+    };
+    /** Read the Host once the tab first renders. */
+    ensure: () => void;
+    /** Read the Host again. */
+    refresh: () => void;
+    openInstall: () => void;
+    /** Close the dialog; a check in flight is dropped, a Host-owned run has to be cancelled first. */
+    closeInstall: () => void;
+    editInstallSpec: (text: string) => void;
+    /** Check the spec with the Host, then install it; from the failed screen, run it again. */
+    runInstall: () => void;
+    /** Allow the install scripts the failed run left pending, saved for this profile, and run the same spec again. */
+    approveBuildsAndRetry: () => void;
+    /** Leave the check or the failed screen for the spec, or ask the Host to stop the run and wait for its cleanup. */
+    cancelInstall: () => void;
+    /**
+     * While the Host runs the install, ask it to stop and close the dialog once
+     * it confirms; the dialog stays when it cannot. Otherwise nothing.
+     */
+    cancelInstallAndClose: () => void;
+    toggleInstallDetails: () => void;
+    /** Enable the bundle the finished install added, then close the dialog and mark it in the list. */
+    enableInstalled: () => void;
+    /** Drop the list mark once it has been shown. */
+    clearHighlight: () => void;
+    /** Put a bundle into, or take it out of, the profile's layer list. */
+    setEnabled: (packageName: string, enabled: boolean) => void;
+    /** Ask before removing a package from the profile. */
+    uninstall: (packageName: string) => void;
+    confirm: () => void;
+    cancelConfirm: () => void;
+    /** Switch one of a bundle's rows on or off in the profile's user layer. */
+    setRowEnabled: (entryId: PluginEntryId, enabled: boolean) => void;
+    dismissNotice: () => void;
+}
+/**
+ * The key one row occupies in the busy list.
+ * @param entryId - the row's Loader entry id.
+ * @returns the busy key.
+ */
+export declare function rowKey(entryId: string): string;
+/**
+ * One bundle as the page shows it: its rows joined with the Host's entries.
+ * @param bundle - the Host's bundle.
+ * @param plugins - the Host's plugin entries.
+ * @returns the package view.
+ */
+export declare function packageView(bundle: BundleInfo, plugins: readonly PluginInfo[]): PackageView;
+/**
+ * The order the list shows packages in: by the short name a person reads, so a
+ * card stays put when its bundle is switched, whatever order the Host answers in.
+ * @param packages - the Host's bundles as views.
+ * @returns the views sorted by short name.
+ */
+export declare function sortPackages(packages: readonly PackageView[]): PackageView[];
+/** Reads and mutates the profile's plugins through the `pluginManager` Remote. */
+export declare class PluginManagerController {
+    private readonly ctx;
+    private readonly store;
+    private inFlight;
+    private rerun;
+    private generation;
+    private disposed;
+    private pendingConfirm;
+    /** Cancels the check the dialog has in flight. */
+    private inspectAbort;
+    private noticeSeq;
+    /**
+     * @param ctx - the tab plugin's context, whose `remote.pluginManager` and `remote.pluginInventory` namespaces answer.
+     */
+    constructor(ctx: ClientContext);
+    /**
+     * Read the tab's state.
+     * @returns the current sync snapshot (stable reference until the next change).
+     */
+    getSnapshot(): PluginManagerState;
+    /** Stop publishing and drop every late settlement. */
+    dispose(): void;
+    /**
+     * Build the face the tab's slot registration injects.
+     * @param configLedger - the projection of the plugins carrying configuration, bound beside the tab's own state.
+     * @returns the tab's snapshot sources and its actions.
+     */
+    inject(configLedger: HostObservable<ConfigLedger>): PluginManagerFace;
+    /**
+     * Follow the Host's cancellation window for this dialog's installation.
+     * @param progress - a request id and phase received from the Host.
+     */
+    installProgress(progress: PluginInstallProgress): void;
+    /**
+     * Fold a chunk belonging to this installation into its pnpm command.
+     * A final chunk may arrive after the install answer and still updates an existing run.
+     * @param chunk - the chunk the Host forwarded.
+     */
+    appendLog(chunk: PluginInstallLogChunk): void;
+    /**
+     * Read the bundles and the entries their rows run as. A call during an
+     * in-flight read marks one rerun after it settles.
+     * @returns settlement after this call's freshness is reflected.
+     */
+    load(): Promise<void>;
+    private read;
+    private shouldRerun;
+    private confirm;
+    /** Drop the check in flight; its answer is ignored. */
+    private abortInspect;
+    /** Whether a settlement arrives too late to matter: the store is disposed, or the dialog moved on. */
+    private gone;
+    /**
+     * Check the typed spec, then install it. The Host reads what the spec
+     * names first; a refused spec returns to the field with the reason, an
+     * accepted one becomes the subject the next screens show while pnpm runs.
+     */
+    private runInstall;
+    /**
+     * Hand the checked spec to the Host and settle the dialog from its answer.
+     * `approvedBuilds` names the pending install scripts the person allowed;
+     * the Host saves that permission for this profile before pnpm runs.
+     */
+    private startInstall;
+    /**
+     * Allow the install scripts the failed run left pending and run the same
+     * spec again. Only the failed screen with pending names offers this.
+     */
+    private approveBuildsAndRetry;
+    /**
+     * Leave the check or the failed screen for the spec at once; a Host-owned
+     * run is asked to stop and the dialog waits for the Host's word, since
+     * neither a dropped RPC nor a closed connection means pnpm has stopped.
+     * @param closeAfter - stop only a running install, and close the dialog once the Host confirms the stop.
+     */
+    private cancelInstall;
+    /**
+     * Back to the spec: the check, the run, and its request are forgotten and
+     * the spec is kept, with a toast when there is something to say — the Host
+     * stopped the run.
+     */
+    private offerSpecAgain;
+    /**
+     * Enable the bundle the finished install added, then close the dialog and
+     * mark it in the list. A refusal toasts and still closes: the list shows
+     * what did not switch on.
+     */
+    private enableInstalled;
+    /**
+     * Run one action under a busy key, turn its failure into the notice, and
+     * re-read the Host afterwards whatever happened.
+     */
+    private run;
+    /**
+     * Publish a change's outcome: a refused answer or a change the Host could
+     * not apply throws for {@link run} to report; a change that waits for the
+     * next start, that a higher layer overrides, or that the Host stopped is
+     * said in passing.
+     */
+    private applied;
+    private patch;
+    private patchInstall;
+}
+//# sourceMappingURL=manager-store.d.ts.map

package/lib/types/client/presentation.d.ts

@@ -0,0 +1,42 @@
+/** Display labels and toast sentences for global plugin management. */
+import type { ManagementError } from '@deepseek-ai/dsh-api-remotes/client';
+import type { PropsLocale } from '@deepseek-ai/dsh-client-ui-slots';
+import type { ManagerNotice, PackageView } from './manager-store.ts';
+/** The translate seat of the manager's dictionary. */
+export type Translate = PropsLocale<'pluginManager'>['t'];
+/**
+ * What a management error reads as: the code's sentence, or, for an
+ * operation error, the Host's diagnostic as it is.
+ * @param error - the Host's code and its diagnostic, when it has one.
+ * @param t - the manager's translate seat.
+ * @returns the sentence.
+ */
+export declare function managementText(error: {
+    readonly code: ManagementError['code'];
+    readonly diagnostic?: string;
+}, t: Translate): string;
+/**
+ * Compact a package name to what a person calls it.
+ * @param name - the package name.
+ * @returns the unscoped name without the harness prefixes.
+ */
+export declare function shortName(name: string): string;
+/**
+ * Localize known official packages by exact npm name at render time.
+ * @param pkg - original package identity and optional metadata description.
+ * @param t - the manager's current translate function.
+ * @returns localized copy and whether the package is a beta feature, or the package's short name and original description.
+ */
+export declare function packageText(pkg: Pick<PackageView, 'name' | 'description'>, t: Translate): {
+    title: string;
+    description: string | undefined;
+    beta: boolean;
+};
+/**
+ * The sentence one notice shows.
+ * @param notice - the last action's outcome.
+ * @param t - the manager's translate seat.
+ * @returns the sentence.
+ */
+export declare function noticeText(notice: ManagerNotice, t: Translate): string;
+//# sourceMappingURL=presentation.d.ts.map

package/lib/types/client/slot-contract.d.ts

@@ -0,0 +1,56 @@
+/**
+ * The slots the Plugins page declares for plugins that carry their own
+ * configuration: the official plugins listed beside the official bundles, one
+ * bundle's configuration on its page, and one row's configuration opened from
+ * that row. A registrant merges this contract with `import type` and registers
+ * through `ctx.slots`; it never imports this package at runtime.
+ *
+ * Every entry is rendered in two views the owner asks for: `summary` for the
+ * one-liner the page places under the title, `page` for the form with its own
+ * save control. The page draws the title, the icon, and the crumb itself.
+ */
+/** The view the page asks a configuration entry for. */
+export interface PluginConfigViewProps {
+    /** `summary` renders the one-liner alone, as text or inline nodes; `page` renders the form with its save control. */
+    readonly view: 'summary' | 'page';
+}
+declare module '@deepseek-ai/dsh-client-ui-slots' {
+    interface SlotMap {
+        /**
+         * One official plugin the Plugins page lists in its Official group after
+         * the official bundles: `label` is the card's title and `order` its place.
+         * The page renders the entry as the card's one-liner (`view: 'summary'`)
+         * and, once the card is opened, as the body of the plugin's own page
+         * (`view: 'page'`). OCCUPIED by the host-plane configuration pages
+         * `ui-settings-plugins` ships; a bundle's configuration belongs in
+         * `plugins.bundle.config` or `plugins.row.config` instead.
+         */
+        'plugins.item': {
+            kind: 'list';
+            scope: 'root';
+            owner: PluginConfigViewProps;
+        };
+        /**
+         * A bundle's own configuration, keyed by the bundle's package name and
+         * rendered on the bundle's page between its description and its rows
+         * (`view: 'page'` only).
+         */
+        'plugins.bundle.config': {
+            kind: 'keyed';
+            scope: 'root';
+            owner: PluginConfigViewProps;
+        };
+        /**
+         * The configuration of one row a bundle declares, keyed by
+         * `<package name>#<row id>` with the row id as the bundle's patch declares
+         * it: the row on the bundle's page gains a configure control that opens
+         * the entry's page, headed by the row id and the entry's summary.
+         */
+        'plugins.row.config': {
+            kind: 'keyed';
+            scope: 'root';
+            owner: PluginConfigViewProps;
+        };
+    }
+}
+//# sourceMappingURL=slot-contract.d.ts.map

package/lib/types/index.d.ts

@@ -0,0 +1,4 @@
+/** Host loader entry for the plugin-manager tab's browser implementation exported from `./client`. */
+/** Host plugin body — no host-side behavior for the plugin manager tab. */
+export declare function apply(): void;
+//# sourceMappingURL=index.d.ts.map

package/package.json

@@ -0,0 +1,71 @@
+{
+  "name": "@deepseek-ai/dsh-client-ui-plugin-manager",
+  "description": "Plugin management for the dsh web client: the sidebar Plugins panel installs, enables, disables, retries, and composes installed plugin packages",
+  "version": "0.1.6-alpha.2",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/deepseek-ai/deepseek-harness.git",
+    "directory": "packages/client/ui-plugin-manager"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./client": {
+      "types": "./lib/types/client/index.d.ts",
+      "default": "./lib/client.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "dsh": {
+    "client": {
+      "inject": [
+        "@deepseek-ai/dsh-api-remotes",
+        "@deepseek-ai/dsh-client-locale",
+        "@deepseek-ai/dsh-client-ui-layout",
+        "@deepseek-ai/dsh-client-ui-sidebar"
+      ],
+      "platform": "web"
+    }
+  },
+  "license": "MIT",
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.2"
+  },
+  "devDependencies": {
+    "@testing-library/react": "^16.1.0",
+    "@types/react": "~18.3.1",
+    "clsx": "^2.1.1",
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0",
+    "@deepseek-ai/cordis": "^4.0.2",
+    "@deepseek-ai/dsh-api-remotes": "^0.1.6-alpha.2",
+    "@deepseek-ai/dsh-client-locale": "^0.1.6-alpha.2",
+    "@deepseek-ai/dsh-client-store": "^0.1.6-alpha.2",
+    "@deepseek-ai/dsh-client-test-runtime": "^0.1.6-alpha.2",
+    "@deepseek-ai/dsh-client-ui-layout": "^0.1.6-alpha.2",
+    "@deepseek-ai/dsh-client-ui-renderer": "^0.1.6-alpha.2",
+    "@deepseek-ai/dsh-client-ui-sidebar": "^0.1.6-alpha.2",
+    "@deepseek-ai/dsh-client-ui-slots": "^0.1.6-alpha.2",
+    "@deepseek-ai/dsh-plugin-manager": "^0.1.6-alpha.2",
+    "@deepseek-ai/dsh-util-crypto": "^0.1.6-alpha.2",
+    "@deepseek-ai/dsh-client-ui-primitives": "^0.1.6-alpha.2"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/client.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "scripts": {
+    "bundle": "tsdown",
+    "watch": "tsdown --watch"
+  }
+}