@dsh-workbench/shared 0.1.0

package/dist/host/tool-kit.js

@@ -0,0 +1,37 @@
+import { WorkbenchDataError } from './opencli';
+export function sessionWorkspace(exec) {
+    const cwd = exec?.agent?.session?.header?.cwd;
+    return typeof cwd === 'string' && cwd.trim() !== '' ? cwd.trim() : null;
+}
+export function textOutput(text) {
+    return [{ type: 'text', text }];
+}
+export function textRender(_args, value) {
+    const text = value?.text;
+    return textOutput(typeof text === 'string' ? text : JSON.stringify(value));
+}
+export const TEXT_OUTPUT = { schema: { type: 'object', properties: {}, additionalProperties: true }, render: textRender };
+export function jsonText(value) {
+    return JSON.stringify(value);
+}
+const UNCLASSIFIED = 'cli-unclassified';
+export function commandHintFor(names) {
+    return async (command, run) => {
+        try {
+            return await run();
+        }
+        catch (error) {
+            if (!(error instanceof WorkbenchDataError) || error.code !== UNCLASSIFIED)
+                throw error;
+            const advice = `这条命令（${command}）在这份 ${names.plugin} 插件里可能不存在（插件版本旧就会缺）：` +
+                `用 workbench_modules（action=update, id=${names.suiteId}）升级插件，或在面板的模块状态里点更新，再重试。`;
+            throw new WorkbenchDataError(error.code, `${error.message}。${advice}`, {
+                ...(error.detail === undefined ? {} : { detail: error.detail }),
+                hint: `升级：workbench_modules（action=update, id=${names.suiteId}）。` +
+                    `终端确认：opencli ${names.plugin} ${command} --help${error.hint === undefined ? '' : `\n${error.hint}`}`,
+                ...(error.helpUrl === undefined ? {} : { helpUrl: error.helpUrl }),
+                ...(error.project === undefined ? {} : { project: error.project }),
+            });
+        }
+    };
+}

package/dist/host/tool-scope.d.ts

@@ -0,0 +1,32 @@
+import type { DshPromptAssembly } from '@dsh-workbench/shared';
+export interface ScopedToolRegistry {
+    restrict(filter: {
+        readonly allow?: readonly string[];
+        readonly deny?: readonly string[];
+    }): () => void;
+}
+export interface ToolScopeAgent {
+    readonly ctx?: {
+        readonly tools?: ScopedToolRegistry | undefined;
+        get?<T = unknown>(name: string): T | undefined;
+    } | undefined;
+    readonly session?: {
+        readonly header?: {
+            readonly cwd?: string;
+        } | undefined;
+    } | undefined;
+}
+export interface ToolScopeOptions {
+    deniedTools(workspace: string | null): readonly string[];
+    logger?: {
+        info?(message: string): void;
+        warn?(message: string): void;
+    } | undefined;
+}
+export interface ToolScope {
+    apply(agent: unknown): void;
+    narrow(assembly: DshPromptAssembly, agent: unknown): DshPromptAssembly;
+    reapply(): void;
+    disposeAll(): void;
+}
+export declare function createToolScope(options: ToolScopeOptions): ToolScope;

package/dist/host/tool-scope.js

@@ -0,0 +1,84 @@
+function agentOf(value) {
+    return typeof value === 'object' && value !== null ? value : undefined;
+}
+function workspaceOf(handle) {
+    const cwd = handle.session?.header?.cwd;
+    return typeof cwd === 'string' && cwd !== '' ? cwd : null;
+}
+export function createToolScope(options) {
+    const applied = new WeakMap();
+    const seen = new Set();
+    function toolsOf(handle) {
+        const byProperty = handle.ctx?.tools;
+        if (byProperty?.restrict !== undefined)
+            return byProperty;
+        const byGet = handle.ctx?.get?.('tools');
+        return byGet?.restrict === undefined ? undefined : byGet;
+    }
+    function sync(handle) {
+        const tools = toolsOf(handle);
+        if (tools === undefined) {
+            options.logger?.warn?.('[dsh-workbench] 拿不到 agent 作用域的工具面：这次不收窄（下次再试）');
+            return;
+        }
+        const workspace = workspaceOf(handle);
+        const deny = [...options.deniedTools(workspace)];
+        const signature = `${workspace ?? ''}\u0000${deny.join(',')}`;
+        const previous = applied.get(handle);
+        if (previous !== undefined && previous.signature === signature)
+            return;
+        if (previous === undefined)
+            seen.add(new WeakRef(handle));
+        previous?.dispose();
+        if (deny.length === 0) {
+            options.logger?.info?.('[dsh-workbench] 这个工作区启用了全部套件：不收窄工具面');
+            applied.delete(handle);
+            return;
+        }
+        try {
+            applied.set(handle, { signature, dispose: tools.restrict({ deny }) });
+            options.logger?.info?.(`[dsh-workbench] 按工作区收窄工具面：${workspace ?? '(未知工作区)'} 里收起 ${deny.length} 个工具（${deny.join(', ')}）`);
+        }
+        catch (error) {
+            options.logger?.warn?.(`[dsh-workbench] 收窄工具面失败：${String(error)}`);
+        }
+    }
+    return {
+        apply(agent) {
+            const handle = agentOf(agent);
+            if (handle === undefined)
+                return;
+            sync(handle);
+        },
+        narrow(assembly, agent) {
+            const handle = agentOf(agent);
+            const tools = assembly?.tools;
+            if (handle === undefined || tools === undefined)
+                return assembly;
+            const deny = new Set(options.deniedTools(workspaceOf(handle)));
+            if (deny.size === 0)
+                return assembly;
+            const kept = tools.filter((tool) => !deny.has(tool.name));
+            return kept.length === tools.length ? assembly : { ...assembly, tools: kept };
+        },
+        reapply() {
+            for (const ref of [...seen]) {
+                const handle = ref.deref();
+                if (handle === undefined)
+                    seen.delete(ref);
+                else
+                    sync(handle);
+            }
+        },
+        disposeAll() {
+            for (const ref of [...seen]) {
+                const handle = ref.deref();
+                if (handle === undefined)
+                    continue;
+                applied.get(handle)?.dispose();
+                applied.delete(handle);
+            }
+            seen.clear();
+        },
+    };
+}

package/dist/host/unit-face.d.ts

@@ -0,0 +1,66 @@
+import type { DshHostContext } from '../api/dsh.js';
+import type { UnitManifest } from '../api/unit.js';
+import type { RouteTable } from '../host/http.js';
+import type { LongTaskBase, LongTaskHost, LongTaskRegistry } from '../host/long-task.js';
+import type { ProvisionHandler } from '../host/provision.js';
+import type { UnitCapability } from './unit-libs';
+import type { ApprovalCall, ApprovalFacts } from '../host/tool-approval.js';
+import type { ValueHandoff } from '../host/value-handoff.js';
+import type { WorkspaceStore } from '../host/workspace-store.js';
+export interface UnitMountDeps {
+    readonly ctx: DshHostContext;
+    readonly logger?: {
+        info?(message: string): void;
+        warn?(message: string): void;
+    } | undefined;
+    readonly manifests: () => readonly UnitManifest[];
+    readonly opencliCommand?: string;
+    readonly store: WorkspaceStore;
+    readonly values?: ValueHandoff | undefined;
+    readonly probe?: (unit: string, options?: {
+        readonly force?: boolean;
+    }) => Promise<UnitCapability | undefined>;
+    readonly longTasks?: LongTaskHost | undefined;
+}
+export type ContextRenderer = (ref: {
+    readonly kind: string;
+    readonly parts: readonly string[];
+}) => Promise<string> | string;
+export type UnitWarmRead = readonly string[];
+export interface UnitCall {
+    readonly source: string;
+    readonly args: Readonly<Record<string, unknown>>;
+    readonly result: unknown;
+}
+export interface UnitMountResult {
+    readonly routes: RouteTable;
+    registerTools(): Array<() => void>;
+    readonly factsOf?: ((call: UnitCall) => readonly string[] | undefined) | undefined;
+    readonly gate?: {
+        deniedTools(workspace: string | null): readonly string[];
+        subscribe(listener: () => void): () => void;
+    };
+    readonly context?: {
+        readonly kinds: readonly string[];
+        render(ref: {
+            readonly kind: string;
+            readonly parts: readonly string[];
+        }): Promise<string> | string;
+    };
+    readonly warmReads?: (() => readonly UnitWarmRead[]) | undefined;
+    readonly prefs?: {
+        readonly resource: string;
+        handle(payload: unknown): unknown;
+    };
+    readonly actions?: readonly {
+        readonly resource: string;
+        handle(payload: unknown): unknown;
+    }[];
+    readonly provision?: ProvisionHandler;
+    readonly longTasks?: LongTaskRegistry<LongTaskBase> | undefined;
+    readonly approvalDetail?: ((call: ApprovalCall) => ApprovalFacts | undefined | Promise<ApprovalFacts | undefined>) | undefined;
+}
+export interface UnitHostFace {
+    readonly manifest: UnitManifest;
+    mount(deps: UnitMountDeps): UnitMountResult;
+}

package/dist/host/unit-face.js

@@ -0,0 +1 @@
+export {};

package/dist/host/unit-libs.d.ts

@@ -0,0 +1,37 @@
+import type { PluginSourceProblem } from './plugin-source';
+import type { PluginRelease, UnitLibNeed, UnitPluginNeed } from '../api/unit';
+export interface UnitLibState {
+    readonly name: string;
+    readonly purpose: string;
+    readonly status: 'ok' | 'outdated' | 'missing' | 'unsatisfied';
+    readonly installed?: string;
+    readonly latest?: string;
+    readonly command?: string;
+}
+export interface UnitCommands {
+    readonly unit: string;
+    readonly plugins?: readonly UnitPluginNeed[];
+    readonly libs?: readonly UnitLibNeed[];
+}
+export interface UnitPluginState {
+    readonly name: string;
+    readonly status: "ok" | "outdated" | "missing";
+    readonly missing: readonly string[];
+    readonly install?: "ready" | PluginSourceProblem;
+    readonly command?: string;
+    readonly release?: PluginRelease;
+}
+export interface UnitCapability {
+    readonly unit: string;
+    readonly status: "ok" | "missing-commands" | "missing-plugin" | "unchecked";
+    readonly plugin?: string;
+    readonly required: readonly string[];
+    readonly missing: readonly string[];
+    readonly detail: string;
+    readonly command?: string;
+    readonly fix?: "install" | "update";
+    readonly install?: "ready" | PluginSourceProblem;
+    readonly plugins?: readonly UnitPluginState[];
+    readonly libs?: readonly UnitLibState[];
+    readonly released?: boolean;
+}

package/dist/host/unit-libs.js

@@ -0,0 +1 @@
+export {};

package/dist/host/unit-readiness.d.ts

@@ -0,0 +1,7 @@
+import type { UnitManifest } from '@dsh-workbench/shared';
+export interface UnitReadiness {
+    readonly canMount: boolean;
+    readonly missingHard: readonly string[];
+    readonly missingSoft: readonly string[];
+}
+export declare function unitReadiness(manifest: UnitManifest, lookup: (name: string) => unknown): UnitReadiness;

package/dist/host/unit-readiness.js

@@ -0,0 +1,5 @@
+export function unitReadiness(manifest, lookup) {
+    const missingHard = manifest.host.inject.filter((name) => lookup(name) === undefined);
+    const missingSoft = (manifest.host.optional ?? []).filter((name) => lookup(name) === undefined);
+    return { canMount: missingHard.length === 0, missingHard, missingSoft };
+}

package/dist/host/unit-registry.d.ts

@@ -0,0 +1,9 @@
+import type { UnitManifest } from '@dsh-workbench/shared';
+import type { UnitHostFace } from './unit-face';
+export interface UnitRegistry {
+    register(face: UnitHostFace): () => void;
+    all(): readonly UnitHostFace[];
+    manifests(): readonly UnitManifest[];
+    subscribe(listener: () => void): () => void;
+}
+export declare function createUnitRegistry(): UnitRegistry;

package/dist/host/unit-registry.js

@@ -0,0 +1,33 @@
+export function createUnitRegistry() {
+    const faces = [];
+    const ids = new Set();
+    const listeners = new Set();
+    function notify() {
+        for (const listener of listeners)
+            listener();
+    }
+    return {
+        register(face) {
+            const id = face.manifest.id;
+            if (ids.has(id))
+                throw new Error(`套件 id 重复：${id}（id 会进持久化配置，不能撞）`);
+            ids.add(id);
+            faces.push(face);
+            notify();
+            return () => {
+                const index = faces.indexOf(face);
+                if (index < 0)
+                    return;
+                faces.splice(index, 1);
+                ids.delete(id);
+                notify();
+            };
+        },
+        all: () => faces,
+        manifests: () => faces.map((face) => face.manifest),
+        subscribe(listener) {
+            listeners.add(listener);
+            return () => listeners.delete(listener);
+        },
+    };
+}

package/dist/host/value-handoff.d.ts

@@ -0,0 +1,16 @@
+export interface HandoffEntry {
+    readonly fact: string;
+    readonly key: string;
+}
+export interface HandoffValue {
+    readonly value: unknown;
+    readonly at: number;
+}
+export interface ValueHandoff {
+    hand(entry: HandoffEntry, value: unknown, now?: number): void;
+    take(entry: HandoffEntry, now?: number): HandoffValue | undefined;
+}
+export declare function handoffId(entry: HandoffEntry): string;
+export declare function createValueHandoff(options?: {
+    ttlMs?: number;
+}): ValueHandoff;

package/dist/host/value-handoff.js

@@ -0,0 +1,21 @@
+import { HANDOFF_TTL_MS } from '../config/constants.js';
+export function handoffId(entry) {
+    return `${String(entry.fact.length)}:${entry.fact}${entry.key}`;
+}
+export function createValueHandoff(options = {}) {
+    const ttlMs = options.ttlMs ?? HANDOFF_TTL_MS;
+    const held = new Map();
+    return {
+        hand(entry, value, now = Date.now()) {
+            held.set(handoffId(entry), { value, at: now });
+        },
+        take(entry, now = Date.now()) {
+            const id = handoffId(entry);
+            const hit = held.get(id);
+            if (hit === undefined)
+                return undefined;
+            held.delete(id);
+            return now - hit.at >= ttlMs ? undefined : hit;
+        },
+    };
+}

package/dist/host/version-range.d.ts

@@ -0,0 +1,2 @@
+export type VersionVerdict = 'satisfied' | 'unsatisfied' | 'malformed';
+export declare function checkVersionRange(contract: string | undefined, version: string): VersionVerdict;

package/dist/host/version-range.js

@@ -0,0 +1,73 @@
+import { compareVersions } from './release';
+function readable(version) {
+    return compareVersions(version, '0.0.0') !== undefined;
+}
+function segmentsOf(version) {
+    if (!readable(version))
+        return undefined;
+    return version.split('.').map((part) => Number.parseInt(part, 10));
+}
+function caretUpper(base) {
+    const [major = 0, minor = 0, patch = 0] = base;
+    if (major > 0)
+        return `${major + 1}.0.0`;
+    return minor > 0 ? `0.${minor + 1}.0` : `0.0.${patch + 1}`;
+}
+function tildeUpper(base) {
+    const [major = 0, minor = 0] = base;
+    return `${major}.${minor + 1}.0`;
+}
+function comparator(token, version) {
+    const match = /^(>=|<=|>|<|=|\^|~)?\s*(.+)$/.exec(token.trim());
+    if (match === null)
+        return undefined;
+    const [, operator = '', raw = ''] = match;
+    const base = segmentsOf(raw.trim());
+    if (base === undefined)
+        return undefined;
+    const at = (other) => compareVersions(version, other);
+    switch (operator) {
+        case '^':
+            return (at(raw) ?? -1) >= 0 && (at(caretUpper(base)) ?? 1) < 0;
+        case '~':
+            return (at(raw) ?? -1) >= 0 && (at(tildeUpper(base)) ?? 1) < 0;
+        default:
+            break;
+    }
+    const compared = at(raw.trim());
+    if (compared === undefined)
+        return undefined;
+    switch (operator) {
+        case '>=':
+            return compared >= 0;
+        case '<=':
+            return compared <= 0;
+        case '>':
+            return compared > 0;
+        case '<':
+            return compared < 0;
+        case '=':
+        case '':
+            return compared === 0;
+        default:
+            return undefined;
+    }
+}
+export function checkVersionRange(contract, version) {
+    const spec = contract?.trim() ?? '';
+    if (spec === '')
+        return 'satisfied';
+    if (!readable(version))
+        return 'malformed';
+    const tokens = spec.split(/\s+/).filter((token) => token !== '');
+    if (tokens.length === 0)
+        return 'satisfied';
+    for (const token of tokens) {
+        const verdict = comparator(token, version);
+        if (verdict === undefined)
+            return 'malformed';
+        if (!verdict)
+            return 'unsatisfied';
+    }
+    return 'satisfied';
+}

package/dist/host/workspace-store.d.ts

@@ -0,0 +1,19 @@
+export interface ModuleStore {
+    readonly dir: string;
+    read(name: string): unknown | null;
+    write(name: string, value: unknown): void;
+    remove(name: string): void;
+    list(): string[];
+}
+export interface WorkspaceStore {
+    for(unitId: string, workspace: string | null): ModuleStore;
+    machine(unitId: string): ModuleStore;
+    scan(unitId: string): ModuleStore[];
+}
+export declare function workspaceKey(workspace: string): string;
+export declare function createWorkspaceStore(options: {
+    readonly root?: string | null | undefined;
+    readonly logger?: {
+        warn?(message: string): void;
+    } | undefined;
+}): WorkspaceStore;

package/dist/host/workspace-store.js

@@ -0,0 +1,133 @@
+import { createHash } from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { workspacesRoot } from '../host/data-root.js';
+function slug(raw, max = 40) {
+    const cleaned = raw
+        .replace(/[^A-Za-z0-9._-]+/g, '-')
+        .replace(/^[-.]+|[-.]+$/g, '')
+        .slice(0, max);
+    return cleaned === '' ? 'workspace' : cleaned;
+}
+export function workspaceKey(workspace) {
+    const abs = path.resolve(workspace);
+    return `${slug(path.basename(abs))}-${createHash('sha1').update(abs).digest('hex').slice(0, 8)}`;
+}
+function inside(dir, name) {
+    const trimmed = name.trim();
+    if (trimmed === '' || trimmed === '.' || trimmed === '..') {
+        throw new Error(`模块文件夹里只接受相对文件名，收到的是「${name}」`);
+    }
+    if (trimmed.includes('\0') || path.isAbsolute(trimmed)) {
+        throw new Error(`模块只能写自己的文件夹：不接受绝对路径「${name}」`);
+    }
+    const full = path.resolve(dir, trimmed);
+    if (full !== dir && !full.startsWith(dir + path.sep)) {
+        throw new Error(`模块只能写自己的文件夹：路径越界「${name}」`);
+    }
+    return full;
+}
+function memoryStore(dir) {
+    const files = new Map();
+    return {
+        dir,
+        read: (name) => {
+            inside(dir, name);
+            return files.get(name) ?? null;
+        },
+        write: (name, value) => {
+            inside(dir, name);
+            files.set(name, value);
+        },
+        remove: (name) => {
+            inside(dir, name);
+            files.delete(name);
+        },
+        list: () => [...files.keys()].sort(),
+    };
+}
+function fileStore(dir) {
+    const ensureFor = (file) => {
+        fs.mkdirSync(path.dirname(file), { recursive: true });
+    };
+    return {
+        dir,
+        read: (name) => {
+            const file = inside(dir, name);
+            try {
+                return JSON.parse(fs.readFileSync(file, 'utf8'));
+            }
+            catch {
+                return null;
+            }
+        },
+        write: (name, value) => {
+            const file = inside(dir, name);
+            ensureFor(file);
+            const tmp = `${file}.tmp`;
+            fs.writeFileSync(tmp, `${JSON.stringify(value, null, 2)}\n`, 'utf8');
+            fs.renameSync(tmp, file);
+        },
+        remove: (name) => {
+            const file = inside(dir, name);
+            try {
+                fs.unlinkSync(file);
+            }
+            catch {
+            }
+        },
+        list: () => {
+            try {
+                return fs
+                    .readdirSync(dir, { withFileTypes: true })
+                    .filter((entry) => entry.isFile())
+                    .map((entry) => entry.name)
+                    .sort();
+            }
+            catch {
+                return [];
+            }
+        },
+    };
+}
+export function createWorkspaceStore(options) {
+    const root = options.root === null ? null : options.root ?? workspacesRoot();
+    let warned = false;
+    const memory = new Map();
+    const fallback = (dir) => {
+        if (!warned) {
+            warned = true;
+            options.logger?.warn?.('[dsh-workbench] 没有可写的数据根：模块配置只在本进程内生效（见 shared/api/host/data-root.ts）');
+        }
+        const hit = memory.get(dir);
+        if (hit !== undefined)
+            return hit;
+        const created = memoryStore(dir);
+        memory.set(dir, created);
+        return created;
+    };
+    const open = (parts) => root === null
+        ? fallback(path.join('/_memory', ...parts))
+        : fileStore(path.join(root, ...parts.map((part) => slug(part))));
+    return {
+        for: (unitId, workspace) => workspace === null || workspace.trim() === ''
+            ? fallback(path.join('/_memory', slug(unitId)))
+            : open([workspaceKey(workspace), unitId]),
+        machine: (unitId) => open(['_machine', unitId]),
+        scan: (unitId) => {
+            if (root === null)
+                return [];
+            let entries;
+            try {
+                entries = fs.readdirSync(root, { withFileTypes: true })
+                    .filter((entry) => entry.isDirectory() && !entry.name.startsWith('_'))
+                    .map((entry) => entry.name)
+                    .sort();
+            }
+            catch {
+                return [];
+            }
+            return entries.map((key) => fileStore(path.join(root, key, slug(unitId))));
+        },
+    };
+}

package/dist/host/write-result.d.ts

@@ -0,0 +1 @@
+export declare function writeResultForClient(value: unknown, code: string): unknown;

package/dist/host/write-result.js

@@ -0,0 +1,18 @@
+export function writeResultForClient(value, code) {
+    if (typeof value !== 'object' || value === null)
+        return value;
+    const box = value;
+    const existing = box['error'];
+    if (box['ok'] !== false || (typeof existing === 'object' && existing !== null))
+        return value;
+    const text = box['text'];
+    const detail = box['detail'];
+    return {
+        ok: false,
+        error: {
+            code,
+            message: typeof text === 'string' && text.trim() !== '' ? text : '这一步没有成功，也没说为什么',
+            ...(typeof detail === 'string' ? { detail } : {}),
+        },
+    };
+}

package/dist/host.d.ts

@@ -0,0 +1,19 @@
+export * from './host/__tests__/fakes';
+export * from './host/cli-error';
+export * from './host/data-root';
+export * from './host/facts';
+export * from './host/git';
+export * from './host/http';
+export * from './host/long-task';
+export * from './host/opencli-runtime';
+export * from './host/opencli';
+export * from './host/plugin-source';
+export * from './host/provision';
+export * from './host/shell';
+export * from './host/tool-approval';
+export * from './host/tool-kit';
+export * from './host/unit-face';
+export * from './host/unit-libs';
+export * from './host/value-handoff';
+export * from './host/workspace-store';
+export * from './host/write-result';

package/dist/host.js

@@ -0,0 +1,19 @@
+export * from './host/__tests__/fakes';
+export * from './host/cli-error';
+export * from './host/data-root';
+export * from './host/facts';
+export * from './host/git';
+export * from './host/http';
+export * from './host/long-task';
+export * from './host/opencli-runtime';
+export * from './host/opencli';
+export * from './host/plugin-source';
+export * from './host/provision';
+export * from './host/shell';
+export * from './host/tool-approval';
+export * from './host/tool-kit';
+export * from './host/unit-face';
+export * from './host/unit-libs';
+export * from './host/value-handoff';
+export * from './host/workspace-store';
+export * from './host/write-result';

package/dist/i18n/en.d.ts

@@ -0,0 +1,2 @@
+import type { WorkbenchMessages } from './zh';
+export declare const en: Record<keyof WorkbenchMessages, string>;