@deepseek-harness-tui/dsh-tui 0.15.0 → 0.16.0

package/lib/types/dsh-adapter/plugin-install.d.ts

@@ -0,0 +1,160 @@
+/**
+ * `/plugin install <spec>`: the write half of the plugin command (Stage C-4).
+ *
+ * The flow owns the whole conversation with the host service — what a spec
+ * names, gate 1's pre-install notice, gate 3's trust routing, pnpm's progress,
+ * cancellation, the build-script approval, the version-exemption escape and
+ * the final report — and it produces the transcript lines for all of it.
+ *
+ * What it does not do is ask. Every point where a person decides comes back as
+ * a {@link PluginInstallStep}; the UI renders it and answers by calling the
+ * next method. That keeps key handling where every other overlay keeps it
+ * (`Chat.tsx`) and the domain here, and it lets a regression drive the whole
+ * flow through a fake service without a terminal.
+ *
+ * Three rules the service's own semantics force:
+ *
+ * - `installBundle` resolves only once the run is over and the profile was
+ *   restored or changed, so the promise IS the result. The service deletes a
+ *   request the moment it settles, which makes `waitForInstall` a recovery path
+ *   for a caller that lost the promise — not a mailbox to collect from, and not
+ *   something this flow needs (it never lets go).
+ * - A failure arrives in-band: the service folds every error into
+ *   `application: 'failed'` with `result.error`. Only a lock or disposal error
+ *   rejects, so the flow contains both shapes.
+ * - Everything asynchronous is fenced to the binding that asked. A `/new` or a
+ *   resume mid-install must not write pnpm output into the new session's
+ *   transcript; the run itself is a profile-level operation and keeps going.
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { ChangeResult, IncompatiblePlugin, InstallSpecKind, PluginInstallRequestId, Registry } from '@deepseek-ai/dsh-plugin-manager/types';
+import { type PluginInstallNotice } from './plugin-declaration.js';
+import { type FirstPartyFeedLoad, type FirstPartyVerdict } from './plugin-feed.js';
+import { type PluginInstallEvents, type PluginManagerView } from './plugin-manager.js';
+/** How many lines of pnpm's output the failure report keeps. */
+export declare const INSTALL_LOG_TAIL = 6;
+/** What a spec names, once the service has read it. */
+export interface PluginArtifact {
+    readonly name?: string | undefined;
+    readonly version?: string | undefined;
+    readonly kind: InstallSpecKind;
+    readonly bundle: boolean | null;
+    readonly registry: Registry;
+    readonly host?: string | undefined;
+}
+/** What the profile's compatibility file currently exempts. */
+export type VersionExemptions = ReturnType<PluginManagerView['listVersionExemptions']>;
+/** Stable display shape across the host's peers → requirements rename. */
+export type IncompatiblePackage = Pick<IncompatiblePlugin, 'name' | 'version' | 'runtimeVersion'> & {
+    readonly peers: Readonly<Record<string, string>>;
+};
+/**
+ * What `/plugin install` has to say next. `done` means the flow has reported
+ * everything it is going to report: refused, finished, failed or cancelled.
+ */
+export type PluginInstallStep = {
+    readonly kind: 'confirm';
+    readonly artifact: PluginArtifact;
+    /** Gate 3: whether the feed vouches for this exact artifact. */
+    readonly trust: FirstPartyVerdict;
+    /** Gate 1: what could be read about the package's declarations, before it lands. */
+    readonly notice: PluginInstallNotice;
+}
+/** pnpm was blocked by build scripts this profile has not approved. */
+ | {
+    readonly kind: 'build-blocked';
+    readonly builds: readonly string[];
+}
+/** The running host refuses this exact version; the exemption is the escape. */
+ | {
+    readonly kind: 'incompatible';
+    readonly packages: readonly IncompatiblePackage[];
+    readonly exemptions: VersionExemptions;
+} | {
+    readonly kind: 'done';
+};
+/** What the caller of a flow supplies that only the UI knows. */
+export interface PluginInstallSink {
+    /** The session the flow's output belongs to; see `binding` below. */
+    readonly binding: () => number;
+    /** Whether a turn is running; see `busy` on the flow's options. */
+    readonly busy: () => boolean;
+    /** Where the flow's transcript lines go (already sanitized and capped). */
+    readonly onLines: (lines: readonly string[]) => void;
+}
+export interface PluginInstallFlowOptions {
+    readonly manager: PluginManagerView;
+    readonly spec: string;
+    /** The feed the trust verdict reads (loaded once by the caller). */
+    readonly feed: FirstPartyFeedLoad;
+    /** Gate 1's evidence for one target; `declarationNoticeFor` in the wiring. */
+    readonly noticeOf: (target: {
+        readonly name?: string | undefined;
+        readonly directory?: string | undefined;
+    }) => PluginInstallNotice;
+    /** Resolve a path spec to a directory, when the caller knows the profile root. */
+    readonly specDirectory?: ((spec: string) => string | undefined) | undefined;
+    /** The binding generation that asked; every asynchronous write is fenced to it. */
+    readonly binding: () => number;
+    /**
+     * Whether a turn is running. Installing changes the profile, and the change
+     * applies or reloads plugins under whatever is running, so the flow refuses
+     * while this is true — before the inspection, and again before the write.
+     */
+    readonly busy: () => boolean;
+    /** Where the flow's transcript lines go (already sanitized and capped). */
+    readonly onLines: (lines: readonly string[]) => void;
+    /** The manager's install events, when the caller has a context to subscribe on. */
+    readonly events?: PluginInstallEvents | undefined;
+    /** This package's running version — the other side of the drift check. */
+    readonly ownVersion?: string | undefined;
+    /** The profile an installation belongs to, for the manual commands. */
+    readonly profileName?: string | undefined;
+    /** The registry asked first. */
+    readonly registry?: Registry | undefined;
+    /** Injectable for a regression; a fresh process-unique id otherwise. */
+    readonly requestId?: PluginInstallRequestId | undefined;
+}
+export interface PluginInstallFlow {
+    readonly requestId: PluginInstallRequestId;
+    /** Read the spec, judge it, and either ask (gate 1 / gate 3) or install straight away. */
+    begin(): Promise<PluginInstallStep>;
+    /** Answer a `confirm` step: proceed. */
+    confirm(): Promise<PluginInstallStep>;
+    /** Answer a `build-blocked` step: allow these scripts and retry. */
+    approve(builds: readonly string[]): Promise<PluginInstallStep>;
+    /** Answer an `incompatible` step: exempt these exact versions and retry. */
+    acceptRisk(): Promise<PluginInstallStep>;
+    /** Stop pending work and await profile writes already started; repeated calls share the wait. */
+    cancel(): Promise<PluginInstallStep>;
+    /** Release the event subscriptions. */
+    dispose(): void;
+}
+/**
+ * The reason line for a result that failed, from the most specific field it
+ * carries. Exported because the lifecycle flow (`./plugin-manage.ts`) writes
+ * through the same `change()` funnel and reports the same shapes — and because
+ * the credential reasoning below is exactly the kind of rule that must not exist
+ * in two copies: a removal runs pnpm too.
+ */
+export declare function failureReasonOf(result: ChangeResult): string;
+export declare function createPluginInstallFlow(options: PluginInstallFlowOptions): PluginInstallFlow;
+/**
+ * The `/plugin install` entry the screen calls: `/plugin`'s argument text in, a
+ * flow out — or `undefined` for anything that is not an install form, and for a
+ * launch with no profile plugin service to install through (the screen then
+ * runs the read-only report, which is where the CLI route is printed).
+ *
+ * This is the one place that knows how the flow is wired to the running
+ * composition: the host service and its events, the packaged feed, gate 1's
+ * declaration reader, and the profile-relative resolution of a `install <path>`
+ * spec. It lives beside the flow rather than in the entry so a regression can
+ * drive the real wiring with a fixture context — the parts that only exist here
+ * (the feed load, the declaration read, the `file:` base URL) are exactly the
+ * ones a fixture-only battery would otherwise never touch.
+ */
+export declare function createPluginInstallEntry(ctx: Context, options?: {
+    readonly profileName?: string | undefined;
+    readonly ownVersion?: string | undefined;
+}): (args: string, sink: PluginInstallSink) => PluginInstallFlow | undefined;
+//# sourceMappingURL=plugin-install.d.ts.map

package/lib/types/dsh-adapter/plugin-install.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin-install.d.ts","sourceRoot":"","sources":["../../../src/dsh-adapter/plugin-install.ts"],"names":[],"mappings":"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"}