dsh-plugin-local-infer 0.1.2 → 0.1.4

package/packages/ui/lib/route.d.ts

@@ -12,27 +12,38 @@
  * ~/.dsh/local-infer/config.json, shared with the CLI, so the browser never
  * sees a secret it did not store. The routes are held by an effect, so they
  * go when the plugin does.
+ *
+ * This module holds the HTTP plumbing every route builds on: the RouteError
+ * the domain operations throw with their own status, the RouteResponder the
+ * handlers answer through, and defineRoute, the template method that guards
+ * the method (405), reads the bounded body (413), and maps the handler's
+ * answer to a status. The request parsing lives in ./request.ts, the stored-
+ * config persistence in ./config.ts, the view models in ./viewmodels/, the
+ * operations in ./ops/, and each route definition in its own file under
+ * ./routes/. registerLocalInferRoute wires them onto the web server.
  * @module dsh-plugin-local-infer/ui/route
  */
 import type { Context } from '@deepseek-ai/cordis';
-import type { Config, DefaultProvenance, HardwareProfile, InstallResult, LaunchStep, LifecycleHost, ProviderLaunchRecord, ProviderStatus, RegisterResult, VramModel, VramVerdict } from 'dsh-plugin-local-infer/core';
-import type { DownloadResult, EngineDeathEvent, LaunchResult, LocalInferService } from 'dsh-plugin-local-infer/service';
-import type { EngineInfo } from '../../providers/lib/index.js';
-import type { DepsModel } from './deps.ts';
-import type { FormModel } from './form.ts';
-import type { MeterModel } from './meter.ts';
-import type { WarningsModel } from './warnings.ts';
+import type { LifecycleHost } from 'dsh-plugin-local-infer/core';
+import type { LocalInferService } from 'dsh-plugin-local-infer/service';
+/**
+ * LocalInferRoute is one webServer route definition the register step holds
+ * by an effect: the stable name, the exact-match path, and the handler the
+ * web server invokes per request. The route files under ./routes/ each build
+ * one of these through defineRoute.
+ */
+export interface LocalInferRoute {
+    name: string;
+    kind: 'exact';
+    path: string;
+    handler: (req: IncomingLike, res: OutgoingLike) => void | Promise<void>;
+}
 /**
  * The webServer service is dsh-specific and absent from the cordis Context
  * type, so the route narrows the scoped context to the two members it needs.
  */
 export interface WebServerService {
-    register(route: {
-        name: string;
-        kind: 'exact';
-        path: string;
-        handler: (req: IncomingLike, res: OutgoingLike) => void | Promise<void>;
-    }): () => void;
+    register(route: LocalInferRoute): () => void;
 }
 interface IncomingLike extends AsyncIterable<Buffer> {
     method: string;
@@ -49,198 +60,15 @@ interface OutgoingLike {
      */
     write?(chunk: string): unknown;
     end(body?: string): void;
+    /**
+     * Optional: watch the response for the client disconnecting (the node
+     * ServerResponse's 'close' before the route ends), so a stream route can
+     * abort the in-flight run when the card cancels it. The web server hands
+     * the handler a node ServerResponse; the tests' fake may omit it, and the
+     * route degrades to no abort.
+     */
+    on?(event: string, listener: (...args: unknown[]) => void): unknown;
 }
-/**
- * LocalInferSummary is the JSON the card renders: the engine list, the model
- * list, the detected hardware, the form model for the selected engine, the
- * meter model for the current config, the verdict the banner renders, the
- * guideline warning model the red banner and inline warnings render from,
- * and the config the form edits. Every field is plain data, so it crosses
- * the socket without a function left behind.
- */
-export interface LocalInferSummary {
-    engines: {
-        id: string;
-        label: string;
-        supports: {
-            docker: boolean;
-            local: boolean;
-        };
-        defaultBuildCommand?: string;
-        defaultDockerTag?: string;
-    }[];
-    models: {
-        id: string;
-        source: string;
-    }[];
-    hardware: HardwareProfile;
-    engineId: string;
-    formModel: FormModel;
-    meterModel: MeterModel;
-    verdict: VramVerdict;
-    warningsModel: WarningsModel;
-    config: Config;
-    platformConfigs: Record<string, StoredPlatformConfig>;
-    defaults: DefaultsModel;
-    modelDirectory: string;
-    modelDefaults: ModelDefaultModel[];
-    modelStatus: ModelStatusModel | null;
-    chatTemplateStatus: ChatTemplateStatusModel | null;
-    modelFiles: string[];
-    showHelp: boolean;
-    providers: ProviderSummaryEntry[];
-    logPath: string;
-    lastLogs: string;
-    unsureBanner: {
-        message: string;
-        killCommands: string[];
-    } | null;
-    registered: boolean;
-}
-/**
- * ProviderSummaryEntry is the card-facing view of one saved provider config:
- * the stable id the card edits and deletes against, the engine and model the
- * title renders ("NInfer: <model>"), the running-state the status dot paints,
- * and the full config and platform the expanded form draws from.
- */
-export interface ProviderSummaryEntry {
-    id: string;
-    engine: string;
-    model: string;
-    status: ProviderStatus;
-    config: Config;
-    platform: StoredPlatformConfig;
-}
-/**
- * ModelDefaultModel is the card-facing view of one default model entry: the
- * registry key the config `model` field carries, the label the dropdown
- * shows, and the Hugging Face URL the no-CLI row links to.
- */
-export interface ModelDefaultModel {
-    id: string;
-    label: string;
-    url: string;
-}
-/**
- * ModelStatusModel is the model-status read model the card draws: whether the
- * model is present in the model directory, whether the hf CLI is available,
- * and the download command the Download button runs. The card shows the row
- * only while the model is absent.
- */
-export interface ModelStatusModel {
-    modelId: string;
-    label: string;
-    url: string;
-    present: boolean;
-    hfCli: boolean;
-    downloadCommand: string;
-}
-/**
- * ChatTemplateStatusModel is the answer to "is the selected chat template in
- * the model directory": the repo reference, its display label, whether the
- * template file is present, whether the hf CLI is available, and the download
- * command the card runs (and the System dependencies box shows when the auto-
- * download is unavailable).
- */
-export interface ChatTemplateStatusModel {
-    repo: string;
-    label: string;
-    present: boolean;
-    hfCli: boolean;
-    downloadCommand: string;
-}
-/**
- * DefaultsModel is the resolved-defaults read model the card draws: the
- * starting config the defaults resolver produced and the per-key provenance
- * that names the source that supplied each value (a preset, the user, or a
- * spec default).
- */
-export interface DefaultsModel {
-    config: Config;
-    provenance: DefaultProvenance[];
-}
-/**
- * The config file the route owns. It sits under the dsh home so a web user and
- * a CLI user share one file, the way modsearch shares ~/.modsearch.
- */
-export declare function localInferConfigPath(): string;
-/**
- * StoredPlatformConfig is the per-engine platform config the deploy step
- * consumes (§3.10): where the engine platform lives locally and the git repo
- * that overrides the engine's default upstream. The map is keyed by engine id,
- * so the stored entry carries no id of its own; the route adds it when it
- * builds the EnginePlatformConfig the service registry stores.
- */
-export interface StoredPlatformConfig {
-    engineDirectory?: string;
-    engineFork?: string;
-    buildCommands?: string;
-    dockerTag?: string;
-}
-/**
- * StoredProviderConfig is one saved provider model+engine config the card
- * lists: a stable id the card edits and deletes against, the engine and the
- * full parameter config it serves, the per-engine platform config the deploy
- * step consumes, and the launch record the launch step persists when it
- * starts the entry's engine (the engine pid, start time, launch arguments,
- * and the DSH process pid that launched it). The record is what a DSH
- * restart re-links a surviving engine to its config; a stop clears it.
- */
-export interface StoredProviderConfig {
-    id: string;
-    engine: string;
-    config: Config;
-    platform: StoredPlatformConfig;
-    launch?: ProviderLaunchRecord;
-}
-export interface StoredConfig {
-    engine: string;
-    config: Config;
-    allowRunDeps: boolean;
-    platform: Record<string, StoredPlatformConfig>;
-    showHelp: boolean;
-    providers: StoredProviderConfig[];
-    logPath: string;
-    lastLogs: string;
-}
-/**
- * readConfig reads the stored engine, config, trust gate, and per-engine
- * platform configs. A missing or broken file reads as the scaffold default
- * (NInfer, empty config, gate off, no platform configs) so the card always has
- * a form to draw. A platform entry that is not an object (or whose fields are
- * not strings) is dropped, so a by-hand edit never poisons the deploy step.
- */
-export declare function readConfig(): StoredConfig;
-/**
- * writeConfig persists the engine, config, trust gate, per-engine platform
- * configs, and the help toggle, creating the directory tree on first write.
- */
-export declare function writeConfig(engine: string, config: Config, allowRunDeps: boolean, platform?: Record<string, StoredPlatformConfig>, showHelp?: boolean, providers?: StoredProviderConfig[], logPath?: string, lastLogs?: string): void;
-/**
- * relinkStoredProviders prices every stored provider launch record against the
- * live process table through the service's re-link rule and returns the
- * provider list the card should read: an adopted engine is re-marked plugin-
- * launched and tied to its model by the service, and a liveness watcher starts
- * on its port so a later pkill settles the stored state through the death
- * observer without another summary read; a dead engine's record is cleared on
- * disk here (the previous-pid list with it), so a recycled pid cannot re-link
- * to a config whose engine is down. The route calls it on mount and the
- * summary calls it per read, making re-attach independent of the card opening.
- */
-export declare function relinkStoredProviders(localInfer: LocalInferService, stored: StoredConfig): Promise<StoredProviderConfig[]>;
-/**
- * buildSummary assembles the card's read model for one engine and config: the
- * static engine and model lists, the detected hardware, the form model the
- * selected engine's parameter surface renders to, the meter model the
- * service's estimate prices, and the warning model the service's guideline
- * engine fires. The estimate is the single source the meter and the verdict
- * banner agree on, and the guideline results are the single source the red
- * banner and the inline warnings agree on.
- */
-export declare function buildSummary(localInfer: LocalInferService, request?: {
-    engine?: string;
-    config?: Config;
-}): Promise<LocalInferSummary>;
 /**
  * RouteError is a route failure that carries its own HTTP status, so the
  * handlers map the domain answer (a gate that is off, an unsupported build
@@ -251,227 +79,83 @@ export declare class RouteError extends Error {
     constructor(status: number, message: string);
 }
 /**
- * DepsRequest is the query the card sends for the deps panel: the engine and
- * the config the build mode reads from. Absent values fall back to the stored
- * config, the same rule the summary route applies.
- */
-export interface DepsRequest {
-    engine?: string;
-    config?: Config;
-}
-/**
- * resolveBuildMode picks the deploy mode the dep plan prices: the config's
- * buildMode when the selected engine supports it, else the engine's default
- * (local when the engine can build locally, docker when it cannot). The
- * docker-not-installed guideline reads this same value, so the panel and the
- * warning never disagree about the mode.
- */
-export declare function resolveBuildMode(engine: EngineInfo, config: Config): 'docker' | 'local';
-/**
- * buildDeps assembles the deps panel read model for one engine and config:
- * the detected hardware (with its package manager), the dep plan the service
- * resolves, the per-dep statuses, the copy/paste install string, and the
- * Play/Run trust gate the stored config carries.
- */
-export declare function buildDeps(localInfer: LocalInferService, request?: DepsRequest): Promise<DepsModel>;
-/**
- * InstallResponse is the answer to a Play/Run: the install result and the
- * refreshed deps model, so the card re-renders the gate from the same
- * re-check the install ran.
- */
-export interface InstallResponse {
-    result: InstallResult;
-    deps: DepsModel;
-}
-/**
- * runInstallFor is the Play/Run path: it refuses with a 409 while the
- * trust gate is off (the copy/paste path is always the fallback), runs the
- * install through the service, and refreshes the deps model from the
- * re-check, so the "Get" gate opens only after a re-check passes.
- */
-export declare function runInstallFor(localInfer: LocalInferService, request: DepsRequest): Promise<InstallResponse>;
-/**
- * DownloadRequest is the query the card sends for the download route: the
- * engine, model, and directory the hf CLI download targets. Absent values
- * fall back to the stored config, the same rule the summary route applies.
- */
-export interface DownloadRequest {
-    engine?: string;
-    model?: string;
-    directory?: string;
-}
-/**
- * downloadFor runs the hf CLI download for the request's default model: it
- * resolves the entry through the providers' default list (a 404 when no
- * entry names the pair), resolves the directory against the request, the
- * stored config, and the plugin's default model directory in that order, and
- * runs the download through the service.
- */
-export declare function downloadFor(localInfer: LocalInferService, request: DownloadRequest): Promise<DownloadResult>;
-/**
- * ChatTemplateDownloadRequest is the query the card sends for the chat-template
- * download route: the engine, the template repo reference, and the directory
- * the hf CLI targets. Absent values fall back to the stored config, the same
- * rule the summary route applies.
- */
-export interface ChatTemplateDownloadRequest {
-    engine?: string;
-    template?: string;
-    directory?: string;
-}
-/**
- * chatTemplateDownloadFor runs the hf CLI download for the request's chat
- * template: it resolves the template repo reference from the request or the
- * stored config's chatTemplate (a 400 when neither names an HF repo
- * reference), resolves the directory against the request, the stored config,
- * and the plugin's default model directory in that order, and runs the
- * download through the service.
- */
-export declare function chatTemplateDownloadFor(localInfer: LocalInferService, request: ChatTemplateDownloadRequest): Promise<DownloadResult>;
-/**
- * LaunchRequest is the query the card sends for the launch and stop routes: the
- * engine and the config the plan renders from. `platform` carries the card's
- * unsaved Engine Directory / Engine Fork edits for the engine, so a launch uses
- * them without a prior save. `providerId` names the saved provider entry the
- * launch drives, so the route persists the launch record (or clears it on a
- * stop) on that entry. `autoRebuild` is the card's "Auto Rebuild" checkbox:
- * when false, the deploy step skips the git sync (fetch, rebase, rebuild) and
- * launches the checkout as-is. Absent values fall back to the stored config,
- * the same rule the summary route applies.
- */
-export interface LaunchRequest {
-    engine?: string;
-    config?: Config;
-    platform?: StoredPlatformConfig;
-    providerId?: string;
-    autoRebuild?: boolean;
-}
-/**
- * launchEngine renders the plan the registered adapter produces for the config
- * and the detected hardware, then runs the service's launch entry point
- * (deploy, then the health poll). The detail the launch returns names the
- * broken step when the engine does not come up. The launch line (the engine
- * binary and its arguments) leads the run logs the card's Logs section and
- * the log file carry, so a broken setup diagnoses against the exact child
- * process the launch started. The launch step persists the
- * launch record (the engine pid, start time, launch arguments, and the DSH
- * process pid that launched it) on the request's provider entry, so a DSH
- * restart can re-link a surviving engine to its config.
- */
-export declare function launchEngine(localInfer: LocalInferService, request: LaunchRequest, onProgress?: (step: LaunchStep) => void): Promise<LaunchResult>;
-/**
- * handleEngineDeath persists a provider entry's state when its engine process
- * dies outside the plugin's stop path: a crash, a pkill of a plugin-launched
- * child seen through the service's exit watch, or the poll-detected exit of a
- * process adopted after a DSH restart. The entry whose launch record names the
- * dead pid (or the dead engine-and-port, when the report carries no pid match)
- * has its record cleared, so a restart never re-links a dead pid, and the exit
- * line lands in the card's last-run logs beside the engine's own output. An
- * event that matches no entry carrying a record (a stop the route already
- * cleared, an engine the plugin never tracked) is a no-op, which keeps an
- * expected stop quiet.
- */
-export declare function handleEngineDeath(event: EngineDeathEvent): void;
-/**
- * persistLaunchLogs stores a launch's captured output as the last run and
- * writes it to the configured log file. The log file is only written when the
- * run produced output and the log location is set; the last-run logs are always
- * persisted (an empty string clears a stale run) so the card's Logs section
- * shows the previous run after a reload.
- */
-export declare function persistLaunchLogs(result: LaunchResult, engineId: string, config: Config): void;
-/**
- * stopEngine renders the same plan and runs the service's stop entry point, so
- * the stop step targets the exact container or process the launch started. The
- * stop then clears the target entry's launch record (the engine pid and the
- * previous-pid list with it), so a recycled pid cannot re-link an engine the
- * user just stopped.
- */
-export declare function stopEngine(localInfer: LocalInferService, request: LaunchRequest): Promise<void>;
-/**
- * GetRequest is the query the card sends for the Get route: the engine and
- * the config the dep plan and the build mode read from, and the platform
- * override (the card's unsaved Engine Directory / Engine Fork edits), the
- * same rule the launch request applies. Absent values fall back to the
- * stored config.
- */
-export interface GetRequest {
-    engine?: string;
-    config?: Config;
-    platform?: StoredPlatformConfig;
-}
-/**
- * getEngine is the Get step: it syncs the engine checkout (clone the git
- * repo, or the fork when the platform entry provides one; fetch and rebase
- * a clean checkout; abort with a Logs alert when the checkout has local
- * changes), runs the system dependency plan, and runs the engine's build
- * steps. Every command and its output streams through log as it lands, so
- * the card appends it to the Logs section live. The dependency install only
- * runs while the Play/Run trust gate is on; with the gate off the deps are
- * re-checked and a missing one aborts the step with the copy/paste note.
- */
-export declare function getEngine(localInfer: LocalInferService, request: GetRequest, log: (chunk: string) => void, host?: LifecycleHost): Promise<{
-    ok: boolean;
-    detail?: string;
-}>;
-/**
- * RegisterRequest is the query the card sends for the register and
- * unregister routes: the engine and the config the plan renders from, and
- * agentDefault, which points the agent default model at the registered
- * engine. Absent values fall back to the stored config, the same rule the
- * summary route applies.
- */
-export interface RegisterRequest {
-    engine?: string;
-    config?: Config;
-    agentDefault?: boolean;
+ * RouteResponder is the answer side of a route: the JSON writer every route
+ * answers through, the stream openers the Get and launch routes use for live
+ * output, and the chunk writer a fake response may omit (the route then
+ * degrades to collecting only).
+ */
+export declare class RouteResponder {
+    private readonly res;
+    constructor(res: OutgoingLike);
+    /** Write a JSON answer: the status and content-type head, then the body. */
+    json(status: number, body: unknown): void;
+    /** Open a plain-text stream (the Get route's live log output). */
+    textStream(): void;
+    /** Open an NDJSON stream (the launch route's progress events). */
+    ndjsonStream(): void;
+    /** Stream one chunk; a fake response without write() collects nothing. */
+    write(chunk: string): void;
+    /**
+     * Watch the response's client disconnect (the node 'close' before the
+     * route ends): the listener fires once when the card's Cancel closes the
+     * stream, so the route aborts the in-flight run. A fake response without
+     * on() never fires it, and the run degrades to running to completion.
+     */
+    onClose(listener: () => void): void;
+    /** End the response, optionally with a final body chunk. */
+    end(body?: string): void;
 }
 /**
- * resolveContextWindow picks the context window the registrar publishes: the
- * config's maxContext when it names one, else the native ceiling of the
- * VramModel the config resolves to (the named model, or the single
- * registered model), else the 32768 spec default. The DSH contextWindow must
- * not promise a context the engine cannot serve, so the ceiling is the
- * model's own, not an optimistic number.
- */
-export declare function resolveContextWindow(config: Config, models: readonly VramModel[]): number;
-/**
- * registerFor renders the plan through the registered adapter, resolves the
- * model row and the context window, and runs the service's register entry
- * point, which upserts the provider and model through the settings seam.
- * The result carries the entry the registrar wrote, so the card names the
- * model it published.
- */
-export declare function registerFor(localInfer: LocalInferService, request?: RegisterRequest): Promise<RegisterResult>;
-/**
- * syncRegisteredModel re-runs the registration for a saved config when the
- * model is already registered in the DSH settings, so the registered model's
- * input types (the vision flag) stay in step with the saved config. A model
- * that is not registered (a fresh save) is a no-op, and a profile without the
- * settings seam throws, which the save route catches and swallows so the save
- * itself never fails on a sync that cannot run.
- */
-export declare function syncRegisteredModel(localInfer: LocalInferService, engine: string, config: Config): Promise<void>;
-/**
- * unregisterFor runs the service's removeModel entry point for the engine's
- * provider and the model row the register step resolved, so the removal
- * targets the exact entry the registration wrote.
- */
-export declare function unregisterFor(localInfer: LocalInferService, request?: RegisterRequest): Promise<{
-    removed: boolean;
-}>;
-/**
- * registerLocalInferRoute registers the summary, save, deps, install, get,
- * launch, stop, register, and unregister routes on the web server and holds
- * them by an effect, so a bundle switch off removes them before the next
- * switch on re-registers. The scoped context carries the webServer; the
- * localInfer service is passed in because the scope only injects what it
- * names. The optional getHost is the lifecycle host the Get route's git and
- * build steps run through; it defaults to the node host, and a test injects
- * a stub so the route never clones a real repo in CI.
+ * RouteInput is what a route handler receives: the parsed URL (the query
+ * params the GET routes read) and, for POST routes, the bounded JSON body.
+ */
+export interface RouteInput {
+    url: URL;
+    body: Record<string, unknown>;
+}
+/**
+ * RouteSpec is a route definition the register step holds by an effect: the
+ * stable name, the exact-match path, the method guard, the status an
+ * unexpected handler failure answers with, and the handler. The object
+ * literal union keeps the invariant the guard enforces: only a POST spec
+ * carries a 413 message, because only a POST spec reads a body.
+ */
+export type RouteSpec = {
+    name: string;
+    path: string;
+    method: 'GET';
+    failStatus: number;
+    run(input: RouteInput, res: RouteResponder): Promise<void>;
+} | {
+    name: string;
+    path: string;
+    method: 'POST';
+    failStatus: number;
+    tooLargeMessage: string;
+    run(input: RouteInput, res: RouteResponder): Promise<void>;
+};
+/**
+ * defineRoute is the template every route file builds on: it guards the
+ * method (405), reads the bounded body (413, POST only), and maps the
+ * handler's answer to a status: a RouteError carries its own status, any
+ * other failure answers with the spec's failStatus. The route files carry
+ * only the handler body.
+ */
+export declare function defineRoute(spec: RouteSpec): LocalInferRoute;
+/**
+ * registerLocalInferRoute registers the summary, save, provider-delete, deps,
+ * install, download, chat-template, get, launch, stop, logs, register, and
+ * unregister routes on the web server and holds them by an effect, so a
+ * bundle switch off removes them before the next switch on re-registers. The
+ * scoped context carries the webServer; the localInfer service is passed in
+ * because the scope only injects what it names. The optional getHost is the
+ * lifecycle host the Get route's git and build steps run through, and the
+ * optional launchHost the launch route's Get steps run through; both default
+ * to the node host, and a test injects a stub so the routes never clone a
+ * real repo in CI.
  */
 export declare function registerLocalInferRoute(scope: Context & {
     webServer: WebServerService;
-}, localInfer: LocalInferService, getHost?: LifecycleHost): void;
+}, localInfer: LocalInferService, getHost?: LifecycleHost, launchHost?: LifecycleHost): void;
 export {};
-//# sourceMappingURL=route.d.ts.map
+//# sourceMappingURL=route.d.ts.map