@dsh-workbench/shared 0.3.6 → 0.3.7

package/dist/host/diy-record.js

@@ -0,0 +1,162 @@
+/**
+ * 录制约定的有效期（15 分钟，毫秒）：超过它没动静的约定算过期、当场让人。
+ */
+export const RECORD_STALE_MS = 15 * 60 * 1000;
+/**
+ * 一张图最多试几次（初拍 + 一次重试）：失败如实报过就停，不每拍重试到底。
+ */
+export const RECORD_SHOT_TRIES = 2;
+/**
+ * 把工具入参收成人话动作。
+ * @param raw - 任意入参值。
+ * @returns `'peek'` / `'halt'` / `'stop'` 原样；别的值（含 `undefined`、多余空白）给 `null`，由调用方拒。
+ */
+export function parseRecordIntent(raw) {
+    return raw === 'peek' || raw === 'halt' || raw === 'stop' ? raw : null;
+}
+/**
+ * 这一拍该不该落图：页面计数涨过 `shotsSeen` 才算；同一个计数已经试满就先放下，等他自己再按。
+ * @param state - 当前有效的那份约定。
+ * @param pageShots - 页面浮条上那个「已拍」计数。
+ * @returns 该落的那个计数；不该落给 `null`（没涨 / 试满了 / 不是个正经数）。
+ */
+export function shotDueOf(state, pageShots) {
+    if (!Number.isFinite(pageShots))
+        return null;
+    const n = Math.floor(pageShots);
+    if (n <= state.shotsSeen)
+        return null;
+    if (state.shotTries !== null && state.shotTries.n === n && state.shotTries.tries >= RECORD_SHOT_TRIES)
+        return null;
+    return n;
+}
+function alive(state, now) {
+    if (state === null)
+        return null;
+    return now - state.at <= RECORD_STALE_MS ? state : null;
+}
+function ownerOf(state, sessionId, now) {
+    const held = alive(state, now);
+    if (held === null)
+        return 'none';
+    return held.sessionId === sessionId ? held : 'not-owner';
+}
+/**
+ * 造一份新的录制约定存储（进程内存，同一时刻只可能有一份有效约定）。
+ * @returns 存取口；动作成不成都在返回的 `RecordMove` 里，不抛异常。
+ */
+export function createRecordStore() {
+    let held = null;
+    const live = (now) => alive(held, now);
+    const withShot = (found, shot, now, error) => {
+        const row = error === undefined ? shot : { n: shot.n, at: shot.at, path: shot.path, error };
+        const kept = found.shots.filter((one) => one.n !== shot.n);
+        const tries = found.shotTries !== null && found.shotTries.n === shot.n ? found.shotTries.tries : 0;
+        return {
+            ...found,
+            shots: [...kept, row].sort((one, two) => one.n - two.n),
+            shotsSeen: error === undefined ? Math.max(found.shotsSeen, shot.n) : found.shotsSeen,
+            shotTries: error === undefined ? null : { n: shot.n, tries: tries + 1 },
+            at: now,
+        };
+    };
+    return {
+        live,
+        begin(pact) {
+            const current = alive(held, pact.now);
+            if (current !== null) {
+                return { ok: false, code: current.sessionId === pact.sessionId ? 'already-held' : 'held-by-other' };
+            }
+            const state = {
+                phase: 'armed',
+                sessionId: pact.sessionId,
+                workspace: pact.workspace,
+                unit: pact.unit,
+                name: pact.name,
+                url: pact.url,
+                title: pact.title,
+                action: pact.action,
+                expect: pact.expect,
+                captureFile: pact.captureFile,
+                startedAt: pact.now,
+                t0: null,
+                t1: null,
+                shots: [],
+                shotsSeen: 0,
+                shotTries: null,
+                beats: 0,
+                beatMs: 0,
+                at: pact.now,
+            };
+            held = state;
+            return { ok: true, state };
+        },
+        started(sessionId, at, now) {
+            const found = ownerOf(held, sessionId, now);
+            if (typeof found === 'string')
+                return { ok: false, code: found };
+            if (found.phase === 'recording')
+                return { ok: false, code: 'already-recording' };
+            if (found.phase !== 'armed')
+                return { ok: false, code: 'not-armed' };
+            const state = { ...found, phase: 'recording', t0: at, at: now };
+            held = state;
+            return { ok: true, state };
+        },
+        finished(sessionId, at, now) {
+            const found = ownerOf(held, sessionId, now);
+            if (typeof found === 'string')
+                return { ok: false, code: found };
+            if (found.phase !== 'recording')
+                return { ok: false, code: 'not-recording' };
+            const state = { ...found, phase: 'finished', t1: at, at: now };
+            held = state;
+            return { ok: true, state };
+        },
+        shotTaken(sessionId, shot, now) {
+            const found = ownerOf(held, sessionId, now);
+            if (typeof found === 'string')
+                return { ok: false, code: found };
+            const state = withShot(found, shot, now, undefined);
+            held = state;
+            return { ok: true, state };
+        },
+        shotFailed(sessionId, shot, now) {
+            const found = ownerOf(held, sessionId, now);
+            if (typeof found === 'string')
+                return { ok: false, code: found };
+            const state = withShot(found, shot, now, shot.error === undefined ? '落图失败' : shot.error);
+            held = state;
+            return { ok: true, state };
+        },
+        beat(sessionId, ms, now) {
+            const found = ownerOf(held, sessionId, now);
+            if (typeof found === 'string')
+                return { ok: false, code: found };
+            const state = {
+                ...found,
+                beats: found.beats + 1,
+                beatMs: Math.max(0, Math.floor(ms)),
+                at: now,
+            };
+            held = state;
+            return { ok: true, state };
+        },
+        stop(sessionId, now) {
+            const found = ownerOf(held, sessionId, now);
+            if (typeof found === 'string')
+                return { ok: false, code: found };
+            held = null;
+            return { ok: true, state: found };
+        },
+    };
+}
+/**
+ * 「谁还占着、在录哪个动作」的一句话，用于别人来抢时说清现况。
+ * @param state - 当前有效的那份约定。
+ * @returns 形如「会话 x（自 HH:mm:ssZ 起在录 y 的「动作」）」的中文串。
+ */
+export function recordOwnerText(state) {
+    const at = new Date(state.startedAt).toISOString().slice(11, 19);
+    return `会话 ${state.sessionId}（自 ${at}Z 起在录 ${state.unit} 的「${state.action}」）`;
+}

package/dist/host/events.d.ts

@@ -0,0 +1,9 @@
+import type { DshHostContext, DshRequest, DshResponse } from '@dsh-workbench/shared';
+import type { FactLog } from './facts';
+export interface FactStream {
+    handler(req: DshRequest, res: DshResponse): void;
+    closeAll(): void;
+    size(): number;
+}
+export declare function createFactStream(log: FactLog): FactStream;
+export declare function registerFactStream(ctx: DshHostContext, log: FactLog): () => void;

package/dist/host/events.js

@@ -0,0 +1,70 @@
+import { EVENTS_PATH } from '@dsh-workbench/shared';
+const HEARTBEAT_MS = 25_000;
+function frame(payload) {
+    return `data: ${JSON.stringify(payload)}\n\n`;
+}
+export function createFactStream(log) {
+    const connections = new Set();
+    const cleanups = new Map();
+    const drop = (res) => {
+        cleanups.get(res)?.();
+        cleanups.delete(res);
+        connections.delete(res);
+    };
+    return {
+        size: () => connections.size,
+        closeAll() {
+            for (const res of [...connections]) {
+                drop(res);
+                res.end?.();
+            }
+        },
+        handler(req, res) {
+            if (req.method !== undefined && req.method !== 'GET') {
+                res.statusCode = 405;
+                res.end();
+                return;
+            }
+            const url = req.url ?? '/';
+            const cut = url.indexOf('?');
+            const since = Number(new URLSearchParams(cut === -1 ? '' : url.slice(cut + 1)).get('since') ?? 0) || 0;
+            const opening = log.since(since);
+            if (typeof res.write !== 'function') {
+                res.statusCode = 200;
+                res.setHeader('content-type', 'application/json; charset=utf-8');
+                res.end(JSON.stringify({ ok: true, ...opening }));
+                return;
+            }
+            const headers = {
+                'content-type': 'text/event-stream; charset=utf-8',
+                'cache-control': 'no-store, no-transform',
+                connection: 'keep-alive',
+            };
+            if (typeof res.writeHead === 'function')
+                res.writeHead(200, headers);
+            else {
+                res.statusCode = 200;
+                for (const [name, value] of Object.entries(headers))
+                    res.setHeader(name, value);
+            }
+            res.write(': connected\n\n');
+            res.write(frame({ type: 'sync', ...opening }));
+            connections.add(res);
+            const timer = setInterval(() => res.write?.(': ping\n\n'), HEARTBEAT_MS);
+            const unsubscribe = log.subscribe((change) => res.write?.(frame({ type: 'bump', ...change })));
+            cleanups.set(res, () => {
+                clearInterval(timer);
+                unsubscribe();
+            });
+            res.on?.('close', () => drop(res));
+        },
+    };
+}
+export function registerFactStream(ctx, log) {
+    const stream = createFactStream(log);
+    const unregister = ctx.webServer.register({ kind: 'exact', path: EVENTS_PATH, handler: stream.handler });
+    return () => {
+        stream.closeAll();
+        unregister();
+    };
+}

package/dist/host/facts.d.ts

@@ -22,3 +22,9 @@ export interface ToolUnit {
 }
 export declare function toolUnits(manifests: readonly UnitManifest[]): Map<string, ToolUnit>;
 export declare function wroteNow(result: unknown): boolean | undefined;
+/**
+ * 由单元 id 拼出它那一族事实的范围名。
+ * @param unit 单元 id，不带后缀。
+ * @returns <unit>* —— 永远是范围名，不是某一条事实。
+ */
+export declare function unitFactScope(unit: string): string;

package/dist/host/facts.js

@@ -1,3 +1,4 @@
+import { FACT_SCOPE_SUFFIX } from '../api/facts.js';
 export function createFactLog(options = {}) {
     const epoch = options.epoch ?? `e${Date.now().toString(36)}${Math.random().toString(36).slice(2, 8)}`;
     let rev = 0;
@@ -42,3 +43,11 @@ export function wroteNow(result) {
     const wrote = value?.wrote;
     return typeof wrote === 'boolean' ? wrote : undefined;
 }
+/**
+ * 由单元 id 拼出它那一族事实的范围名。
+ * @param unit 单元 id，不带后缀。
+ * @returns <unit>* —— 永远是范围名，不是某一条事实。
+ */
+export function unitFactScope(unit) {
+    return `${unit}${FACT_SCOPE_SUFFIX}`;
+}

package/dist/host/git.js

@@ -1,4 +1,4 @@
-import { quoteShellArg, tailLines } from '../lib/text.js';
+import { quoteShellArg, tailLines } from './shell-text.js';
 import { runShell } from './shell.js';
 export function createHeadReader(options) {
     const { shell, logger } = options;

package/dist/host/http.d.ts

@@ -1,5 +1,5 @@
 import type { DshHostContext } from '../api/dsh.js';
-import { type PanelStateStore } from '../lib/panel-state.js';
+import { type PanelStateStore } from './panel-state.js';
 import { type ProvisionHandler } from './provision.js';
 export type RouteHandler = (search: URLSearchParams) => Promise<unknown> | unknown;
 export type RouteTable = Record<string, RouteHandler>;
@@ -27,7 +27,7 @@ export declare function changesHandler(log: {
 }): RouteHandler;
 export declare function preflightHandler(preflight: {
     run(options?: {
-        force?: boolean;
+        hard?: boolean;
     }): Promise<unknown>;
     snapshot(): unknown;
 }): RouteHandler;

package/dist/host/http.js

@@ -1,5 +1,5 @@
-import { unitFactScope } from '../api/facts.js';
-import { parseCardsReport, parseCrashReport } from '../lib/panel-state.js';
+import { unitFactScope } from './facts.js';
+import { parseCardsReport, parseCrashReport } from './panel-state.js';
 import { ACTIONS_PREFIX, API_PREFIX, DIY_DEBUG_PATH, DIY_RECORD_PATH, PANEL_STATE_PREFIX, PLUGIN_ID, PREFS_PREFIX, PROVISION_PREFIX } from '../config/constants.js';
 import { parseProvisionBody, } from './provision.js';
 import { WorkbenchDataError } from '../host/opencli.js';
@@ -179,7 +179,7 @@ export function changesHandler(log) {
 }
 export function preflightHandler(preflight) {
     return (search) => {
-        void preflight.run({ force: flag(search, 'force') });
+        void preflight.run({ hard: flag(search, 'hard') });
         return { ok: true, ...preflight.snapshot() };
     };
 }

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

@@ -39,11 +39,16 @@ export interface LongTaskDeps<S extends LongTaskBase> {
     readonly facts?: ((change: LongTaskChange<S>) => readonly string[] | undefined) | undefined;
     readonly recentMs?: number | undefined;
 }
+/**
+ * 一个单元的长任务注册表：`current(workspace)` 是面板那一行要的投影，`live()` 是外壳侧栏那颗
+ * loading 点要的（**不分工作区、不分目标**，把现在活着的每一趟交出来），`stop` 只把中断信号转给生产方。
+ */
 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>>[];
+    live(): readonly S[];
     stop(id: string, by?: string): boolean;
     onChange(listener: (change: LongTaskChange<S>) => void): () => void;
 }

package/dist/host/long-task.js

@@ -55,6 +55,9 @@ export function createLongTaskRegistry(deps) {
                 .reverse()
                 .map((snapshot) => ({ ...deps.view(snapshot), id: snapshot.id }));
         },
+        live() {
+            return [...runs.values()].filter((snapshot) => LIVE.has(snapshot.status));
+        },
         start(options) {
             const running = this.active(options.workspace, options.target);
             if (running !== null)

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.js

@@ -1,5 +1,5 @@
 import { OPENCLI_PIN } from '../config/constants.js';
-import { quoteShellArg } from '../lib/text.js';
+import { quoteShellArg } from './shell-text.js';
 import { dshHome } from './data-root.js';
 export { dshHome };
 export function isolatedRoot() {

package/dist/host/opencli-window.js

@@ -1,4 +1,4 @@
-import { quoteShellArg } from '../lib/text.js';
+import { quoteShellArg } from './shell-text.js';
 const OPENCLI_WINDOW_ENV = 'OPENCLI_WINDOW=background';
 export function backgroundPrefix() {
     return [quoteShellArg('env'), quoteShellArg(OPENCLI_WINDOW_ENV)];

package/dist/host/opencli.js

@@ -1,5 +1,6 @@
 import { OPENCLI_MAX_CONCURRENT, OPENCLI_TIMEOUT_MS } from '../config/constants.js';
-import { parseJsonLoose, quoteShellArg, tailLines } from '../lib/text.js';
+import { parseJsonLoose } from '../lib/text.js';
+import { quoteShellArg, tailLines } from './shell-text.js';
 import { helpUrlOf, parseCliErrorEnvelope } from './cli-error.js';
 import { backgroundPrefix } from './opencli-window.js';
 import { runShell } from './shell.js';