@dsh-workbench/shared 0.1.0

package/dist/host/long-task.d.ts

@@ -0,0 +1,58 @@
+import { type LongTaskStatus, type LongTaskStep } from '../api/long-task.js';
+export interface LongTaskBase {
+    readonly id: string;
+    readonly workspace: string;
+    readonly target: string;
+    readonly status: LongTaskStatus;
+    readonly step: string;
+    readonly steps: readonly string[];
+    readonly loginUrl?: string | undefined;
+    readonly why?: string | undefined;
+    readonly startedAt: string;
+    readonly at: string;
+}
+export interface LongTaskStart {
+    readonly workspace: string;
+    readonly target: string;
+    readonly payload?: unknown;
+}
+export interface LongTaskChange<S extends LongTaskBase> {
+    readonly kind: 'start' | 'step' | 'settle';
+    readonly snapshot: S;
+    readonly step?: LongTaskStep | undefined;
+}
+export interface LongTaskDeps<S extends LongTaskBase> {
+    readonly run: (options: {
+        readonly payload: unknown;
+        readonly onStep: (step: LongTaskStep) => void;
+    }) => Promise<unknown>;
+    readonly step?: ((step: LongTaskStep, current: S) => Partial<S>) | undefined;
+    readonly outcome?: ((result: unknown, current: S) => Partial<S>) | undefined;
+    readonly view: (snapshot: S) => Readonly<Record<string, unknown>>;
+    readonly now?: (() => string) | undefined;
+    readonly nextId?: (() => string) | undefined;
+    readonly facts?: ((change: LongTaskChange<S>) => readonly string[] | undefined) | undefined;
+    readonly recentMs?: number | undefined;
+}
+export interface LongTaskRegistry<S extends LongTaskBase> {
+    start(options: LongTaskStart): S;
+    snapshot(id: string): S | null;
+    active(workspace: string, target: string): S | null;
+    current(workspace: string): readonly Readonly<Record<string, unknown>>[];
+    onChange(listener: (change: LongTaskChange<S>) => void): () => void;
+}
+export declare function createLongTaskRegistry<S extends LongTaskBase>(deps: LongTaskDeps<S>): LongTaskRegistry<S>;
+export declare function sharedLongTaskRegistry<S extends LongTaskBase>(scope: string, key: string, deps: LongTaskDeps<S>): LongTaskRegistry<S>;
+export interface LongTaskHost {
+    create<S extends LongTaskBase>(options: {
+        readonly key: string;
+    } & LongTaskDeps<S>): LongTaskRegistry<S>;
+}
+export declare function createLongTaskHost(options: {
+    readonly scope: string;
+    readonly unit: string;
+    readonly bump: (facts: readonly string[]) => void;
+}): {
+    readonly host: LongTaskHost;
+    dispose(): void;
+};

package/dist/host/long-task.js

@@ -0,0 +1,148 @@
+import { runsRouteOf } from '../api/long-task.js';
+const LIVE = new Set(['running', 'needs-login']);
+const RECENT_MS = 10 * 60 * 1000;
+export function createLongTaskRegistry(deps) {
+    const runs = new Map();
+    const now = deps.now ?? (() => new Date().toISOString());
+    let counter = 0;
+    const nextId = deps.nextId ?? (() => `run-${Date.now()}-${(counter += 1)}`);
+    const recentMs = deps.recentMs ?? RECENT_MS;
+    const listeners = new Set();
+    const notify = (change) => {
+        for (const listener of [...listeners]) {
+            try {
+                listener(change);
+            }
+            catch {
+            }
+        }
+    };
+    const patch = (id, next, change) => {
+        const current = runs.get(id);
+        if (current === undefined)
+            return;
+        const patched = { ...current, ...next, at: now() };
+        runs.set(id, patched);
+        notify({ ...change, snapshot: patched });
+    };
+    return {
+        active(workspace, target) {
+            for (const snapshot of runs.values()) {
+                if (snapshot.workspace !== workspace || snapshot.target !== target)
+                    continue;
+                if (snapshot.status === 'running' || snapshot.status === 'needs-login')
+                    return snapshot;
+            }
+            return null;
+        },
+        current(workspace) {
+            const floor = Date.parse(now()) - recentMs;
+            const newest = new Map();
+            for (const snapshot of runs.values()) {
+                if (snapshot.workspace !== workspace)
+                    continue;
+                newest.set(snapshot.target, snapshot);
+            }
+            return [...newest.values()]
+                .filter((snapshot) => LIVE.has(snapshot.status) || Date.parse(snapshot.at) >= floor)
+                .reverse()
+                .map((snapshot) => deps.view(snapshot));
+        },
+        start(options) {
+            const running = this.active(options.workspace, options.target);
+            if (running !== null)
+                return running;
+            const id = nextId();
+            const startedAt = now();
+            runs.set(id, {
+                id,
+                workspace: options.workspace,
+                target: options.target,
+                status: 'running',
+                step: '',
+                steps: [],
+                startedAt,
+                at: startedAt,
+            });
+            notify({ kind: 'start', snapshot: runs.get(id) });
+            const onStep = (step) => {
+                const current = runs.get(id);
+                if (current === undefined)
+                    return;
+                const steps = [...current.steps, `${step.kind === 'fail' ? '✗ ' : ''}${step.text}`].slice(-20);
+                const extra = deps.step?.(step, current) ?? {};
+                if (step.loginUrl !== undefined) {
+                    patch(id, { ...extra, status: 'needs-login', step: step.text, steps, loginUrl: step.loginUrl }, { kind: 'step', step });
+                    return;
+                }
+                patch(id, {
+                    ...extra,
+                    status: current.status === 'needs-login' ? 'running' : current.status,
+                    step: step.text,
+                    steps,
+                    ...(current.status === 'needs-login' ? { loginUrl: undefined } : {}),
+                }, { kind: 'step', step });
+            };
+            void deps
+                .run({ payload: options.payload, onStep })
+                .then((result) => {
+                const current = runs.get(id);
+                patch(id, { status: 'ok', ...(deps.outcome?.(result, current) ?? {}), loginUrl: undefined }, { kind: 'settle' });
+            })
+                .catch((error) => {
+                patch(id, {
+                    status: 'failed',
+                    why: error instanceof Error ? error.message : String(error),
+                    loginUrl: undefined,
+                }, { kind: 'settle' });
+            });
+            return runs.get(id);
+        },
+        snapshot(id) {
+            return runs.get(id) ?? null;
+        },
+        onChange(listener) {
+            listeners.add(listener);
+            return () => listeners.delete(listener);
+        },
+    };
+}
+function isRegistry(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const candidate = value;
+    return (typeof candidate.start === 'function' &&
+        typeof candidate.current === 'function' &&
+        typeof candidate.snapshot === 'function' &&
+        typeof candidate.onChange === 'function');
+}
+export function sharedLongTaskRegistry(scope, key, deps) {
+    const store = globalThis;
+    const slot = Symbol.for(`dsh-workbench:long-task:${scope}:${key}`);
+    const existing = store[slot];
+    if (existing !== undefined && isRegistry(existing))
+        return existing;
+    const created = createLongTaskRegistry(deps);
+    store[slot] = created;
+    return created;
+}
+export function createLongTaskHost(options) {
+    const offs = [];
+    return {
+        host: {
+            create(createOptions) {
+                const { key, facts, ...deps } = createOptions;
+                const registry = sharedLongTaskRegistry(options.scope, `${options.unit}:${key}`, deps);
+                offs.push(registry.onChange((change) => {
+                    const named = [runsRouteOf(options.unit), ...(facts?.(change) ?? [])];
+                    options.bump([...new Set(named)]);
+                }));
+                return registry;
+            },
+        },
+        dispose() {
+            for (const off of offs.splice(0))
+                off();
+        },
+    };
+}

package/dist/host/mount-units.d.ts

@@ -0,0 +1,52 @@
+import type { DshHostContext } from '@dsh-workbench/shared';
+import type { UnitManifest } from '@dsh-workbench/shared';
+import { type RouteTable } from './http';
+import type { ContextRenderer, UnitHostFace, UnitMountDeps, UnitMountResult, UnitCall } from './unit-face';
+import { type UnitReadiness } from './unit-readiness';
+export interface MountedUnit {
+    readonly face: UnitHostFace;
+    readonly result: UnitMountResult;
+    readonly readiness: UnitReadiness;
+}
+export interface UnitsPlan {
+    readonly mounted: readonly MountedUnit[];
+    readonly routes: RouteTable;
+    readonly gate: UnitMountResult['gate'];
+    readonly prefs: ReadonlyArray<{
+        readonly resource: string;
+        readonly unit: string;
+        handle(payload: unknown): unknown;
+    }>;
+    readonly actions: ReadonlyArray<{
+        readonly resource: string;
+        readonly unit: string;
+        handle(payload: unknown): unknown;
+    }>;
+    readonly provision: UnitMountResult['provision'];
+    readonly contextRenderers: ReadonlyMap<string, ContextRenderer>;
+    readonly owners: ReadonlyMap<string, string>;
+    readonly routesOfUnit: ReadonlyMap<string, readonly string[]>;
+    readonly factsOf: ReadonlyMap<string, (call: UnitCall) => readonly string[] | undefined>;
+    readonly skipped: ReadonlyArray<{
+        readonly id: string;
+        readonly missing: readonly string[];
+    }>;
+    readonly warmReads: () => readonly (readonly string[])[];
+    readonly disposeLongTasks: () => void;
+}
+export declare function mountUnits(faces: readonly UnitHostFace[], deps: {
+    ctx: DshHostContext;
+    logger?: {
+        info?(m: string): void;
+        warn?(m: string): void;
+    } | undefined;
+    manifests: () => readonly UnitManifest[];
+    opencliCommand?: string;
+    probe?: UnitMountDeps['probe'];
+    store?: UnitMountDeps['store'];
+    values?: UnitMountDeps['values'];
+    longTasks?: {
+        readonly scope: string;
+        readonly bump: (facts: readonly string[]) => void;
+    } | undefined;
+}): UnitsPlan;

package/dist/host/mount-units.js

@@ -0,0 +1,186 @@
+import { runsRouteOf } from '@dsh-workbench/shared';
+import { param } from './http';
+import { createLongTaskHost } from './long-task';
+import { unitReadiness } from './unit-readiness';
+import { createWorkspaceStore } from './workspace-store';
+function withRunsRoute(result, unit) {
+    const runs = result.longTasks;
+    if (runs === undefined)
+        return result;
+    return {
+        ...result,
+        routes: {
+            ...result.routes,
+            [runsRouteOf(unit)]: (search) => {
+                const path = (param(search, 'path') ?? '').trim();
+                return { ok: true, runs: path === '' ? [] : runs.current(path) };
+            },
+        },
+    };
+}
+function collectRoutes(mounted) {
+    const routes = {};
+    const owner = new Map();
+    const routesOfUnit = new Map();
+    for (const item of mounted) {
+        const unit = item.face.manifest.id;
+        for (const [key, handler] of Object.entries(item.result.routes)) {
+            if (key !== unit && !key.startsWith(`${unit}/`)) {
+                throw new Error(`路由名要住在自己那一格的命名空间里（${unit} 或 ${unit}/…）：${key} 不属于 ${unit} —— ` +
+                    `装 / 升 / 卸时点名不到它，那个模块的数据会停在旧值`);
+            }
+            const previous = owner.get(key);
+            if (previous !== undefined) {
+                throw new Error(`路由名冲突：${key} 由套件 ${previous} 与 ${unit} 同时声明`);
+            }
+            owner.set(key, unit);
+            routes[key] = handler;
+            const own = routesOfUnit.get(unit);
+            if (own === undefined)
+                routesOfUnit.set(unit, [key]);
+            else
+                own.push(key);
+        }
+    }
+    return { routes, owners: owner, routesOfUnit };
+}
+function pickGate(mounted) {
+    const providers = mounted.filter((item) => item.result.gate !== undefined);
+    if (providers.length > 1) {
+        throw new Error(`启停闸门只能有一个提供者，现在是：${providers.map((item) => item.face.manifest.id).join('、')}`);
+    }
+    return providers[0]?.result.gate;
+}
+function pickProvision(mounted) {
+    const providers = mounted.filter((item) => item.result.provision !== undefined);
+    if (providers.length > 1) {
+        throw new Error(`机器供给只能有一个提供者，现在是：${providers.map((item) => item.face.manifest.id).join('、')}`);
+    }
+    return providers[0]?.result.provision;
+}
+function collectPrefs(mounted) {
+    const owner = new Map();
+    const prefs = [];
+    for (const item of mounted) {
+        const entry = item.result.prefs;
+        if (entry === undefined)
+            continue;
+        const previous = owner.get(entry.resource);
+        if (previous !== undefined) {
+            throw new Error(`偏好资源名冲突：${entry.resource} 由套件 ${previous} 与 ${item.face.manifest.id} 同时声明`);
+        }
+        owner.set(entry.resource, item.face.manifest.id);
+        prefs.push({ ...entry, unit: item.face.manifest.id });
+    }
+    return prefs;
+}
+function collectActions(mounted) {
+    const owner = new Map();
+    const actions = [];
+    for (const item of mounted) {
+        for (const entry of item.result.actions ?? []) {
+            const previous = owner.get(entry.resource);
+            if (previous !== undefined) {
+                throw new Error(`动作资源名冲突：${entry.resource} 由套件 ${previous} 与 ${item.face.manifest.id} 同时声明`);
+            }
+            owner.set(entry.resource, item.face.manifest.id);
+            actions.push({ ...entry, unit: item.face.manifest.id });
+        }
+    }
+    return actions;
+}
+function collectWarmReads(mounted) {
+    const declarations = mounted
+        .map((item) => item.result.warmReads)
+        .filter((declare) => declare !== undefined);
+    return () => {
+        const seen = new Set();
+        const reads = [];
+        for (const read of declarations.flatMap((declare) => declare())) {
+            const key = read.join(' ');
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            reads.push(read);
+        }
+        return reads;
+    };
+}
+function collectContextRenderers(mounted) {
+    const table = new Map();
+    const owner = new Map();
+    for (const item of mounted) {
+        const context = item.result.context;
+        if (context === undefined)
+            continue;
+        for (const kind of context.kinds) {
+            const previous = owner.get(kind);
+            if (previous !== undefined) {
+                throw new Error(`对话引用的 kind 冲突：${kind} 由套件 ${previous} 与 ${item.face.manifest.id} 同时认领`);
+            }
+            owner.set(kind, item.face.manifest.id);
+            table.set(kind, (ref) => context.render(ref));
+        }
+    }
+    return table;
+}
+export function mountUnits(faces, deps) {
+    const store = deps.store ?? createWorkspaceStore({ root: null });
+    const mounted = [];
+    const skipped = [];
+    const longTaskDisposers = [];
+    for (const face of faces) {
+        const readiness = unitReadiness(face.manifest, (dep) => deps.ctx.get(dep));
+        if (!readiness.canMount) {
+            skipped.push({ id: face.manifest.id, missing: readiness.missingHard });
+            continue;
+        }
+        const unit = face.manifest.id;
+        const longTasks = deps.longTasks === undefined
+            ? undefined
+            : createLongTaskHost({ scope: deps.longTasks.scope, unit, bump: deps.longTasks.bump });
+        if (longTasks !== undefined)
+            longTaskDisposers.push(longTasks.dispose);
+        const result = face.mount({
+            ctx: deps.ctx,
+            logger: deps.logger,
+            manifests: deps.manifests,
+            ...(deps.opencliCommand === undefined ? {} : { opencliCommand: deps.opencliCommand }),
+            ...(deps.probe === undefined ? {} : { probe: deps.probe }),
+            ...(deps.values === undefined ? {} : { values: deps.values }),
+            ...(longTasks === undefined ? {} : { longTasks: longTasks.host }),
+            store,
+        });
+        mounted.push({ face, readiness, result: withRunsRoute(result, unit) });
+    }
+    const collected = collectRoutes(mounted);
+    const prefs = collectPrefs(mounted);
+    const actions = collectActions(mounted);
+    const owners = new Map(collected.owners);
+    for (const entry of [...prefs, ...actions])
+        owners.set(entry.resource, entry.unit);
+    const factsOf = new Map();
+    for (const item of mounted) {
+        const declare = item.result.factsOf;
+        if (declare !== undefined)
+            factsOf.set(item.face.manifest.id, declare);
+    }
+    return {
+        mounted,
+        routes: collected.routes,
+        owners,
+        routesOfUnit: collected.routesOfUnit,
+        factsOf,
+        gate: pickGate(mounted),
+        prefs,
+        actions,
+        provision: pickProvision(mounted),
+        contextRenderers: collectContextRenderers(mounted),
+        skipped,
+        warmReads: collectWarmReads(mounted),
+        disposeLongTasks: () => {
+            for (const dispose of longTaskDisposers.splice(0))
+                dispose();
+        },
+    };
+}

package/dist/host/opencli-runtime.d.ts

@@ -0,0 +1,22 @@
+import type { UnitLibNeed } from '../api/unit.js';
+import { dshHome } from './data-root';
+export { dshHome };
+export declare function isolatedRoot(): string;
+export declare function isolatedHome(): string;
+export declare const OPENCLI_NPM_PACKAGE = "@jackwener/opencli";
+export declare function toolchainDir(): string;
+export declare function toolchainOpencliDir(): string;
+export declare function vendorPrefix(): string;
+export declare function vendorPeerLink(): {
+    readonly dir: string;
+    readonly parent: string;
+};
+export declare function npmCacheDir(): string;
+export declare function isolatedCommand(): string;
+export declare function libsPrefix(): string;
+export declare function libDir(name: string): string;
+export declare function libInstallCommand(options: {
+    readonly need: UnitLibNeed;
+    readonly version?: string | undefined;
+}): string;
+export declare function isolatedInstallCommand(): string;

package/dist/host/opencli-runtime.js

@@ -0,0 +1,46 @@
+import { OPENCLI_PIN } from '../config/constants.js';
+import { quoteShellArg } from '../lib/text.js';
+import { dshHome } from './data-root';
+export { dshHome };
+export function isolatedRoot() {
+    return `${dshHome()}/workbench/opencli`;
+}
+export function isolatedHome() {
+    return `${isolatedRoot()}/home`;
+}
+export const OPENCLI_NPM_PACKAGE = '@jackwener/opencli';
+export function toolchainDir() {
+    return `${isolatedRoot()}/toolchain`;
+}
+export function toolchainOpencliDir() {
+    return `${toolchainDir()}/node_modules/${OPENCLI_NPM_PACKAGE}`;
+}
+export function vendorPrefix() {
+    return `${isolatedRoot()}/plugins-npm`;
+}
+export function vendorPeerLink() {
+    const base = `${vendorPrefix()}/node_modules`;
+    const [scope] = OPENCLI_NPM_PACKAGE.split('/');
+    return { dir: `${base}/${OPENCLI_NPM_PACKAGE}`, parent: `${base}/${scope}` };
+}
+export function npmCacheDir() {
+    return `${isolatedRoot()}/npm-cache`;
+}
+export function isolatedCommand() {
+    return `${isolatedRoot()}/bin/opencli`;
+}
+export function libsPrefix() {
+    return `${isolatedRoot()}/libs`;
+}
+export function libDir(name) {
+    return `${libsPrefix()}/node_modules/${name}`;
+}
+export function libInstallCommand(options) {
+    const { need, version } = options;
+    const registry = process.env[need.registryEnv]?.trim() || need.registryDefault;
+    const spec = version ?? need.version ?? 'latest';
+    return `npm i --prefix '${libsPrefix()}' ${quoteShellArg(`${need.name}@${spec}`)} --registry '${registry}' --cache '${npmCacheDir()}'`;
+}
+export function isolatedInstallCommand() {
+    return `npm i --prefix '${toolchainDir()}' ${OPENCLI_NPM_PACKAGE}@${OPENCLI_PIN} --cache '${npmCacheDir()}'`;
+}

package/dist/host/opencli.d.ts

@@ -0,0 +1,37 @@
+import type { DshShell } from '../api/dsh.js';
+export declare class WorkbenchDataError extends Error {
+    readonly code: string;
+    readonly detail?: string;
+    readonly hint?: string;
+    readonly project?: unknown;
+    readonly helpUrl?: string;
+    constructor(code: string, message: string, extra?: {
+        detail?: string;
+        hint?: string;
+        project?: unknown;
+        helpUrl?: string;
+    });
+}
+export interface OpencliResult {
+    readonly value: unknown;
+    readonly at: number;
+}
+export type OpencliSession = 'persistent' | 'ephemeral';
+export declare function opencliCommandLine(command: string, argv: readonly string[], session?: OpencliSession): string;
+export interface Opencli {
+    json(args: readonly string[], options?: {
+        key?: string;
+        workdir?: string;
+        session?: OpencliSession;
+    }): Promise<OpencliResult>;
+}
+export declare function createOpencli(options: {
+    shell: DshShell;
+    plugin: string;
+    logger?: {
+        warn?(message: string): void;
+    } | undefined;
+    command?: string;
+    timeoutMs?: number;
+    maxConcurrent?: number;
+}): Opencli;