@xiaoso/dsh-workflow-lite 0.0.0-stage → 0.1.0

package/lib/types/host/store/repository.d.ts

@@ -0,0 +1,217 @@
+/**
+ * dsh-workflow-lite — 文件仓储：唯一的副作用边界。
+ *
+ * 这一层兑现四条硬规矩：
+ * 1. **单文件原子写**——一切写入都经 `atomic.writeFileAtomic`；
+ * 2. **进程内锁的粒度 = 一次工具调用全程**（含预检与全部文件写）——`withLock` 把写路径串行化，
+ *    所以 `delete_node` 的"删节点 + 连带删边"不可能被另一个写插进来；
+ * 3. **写前哈希比对 + 字段级合并**——不一致不算冲突：按 `node.id` / `edge.id` 合并，
+ *    只有「同一个 node 的 `data` 双方都改过」或「同一个 `id` 一方删、一方改」才回 `conflict`；
+ *    合并期间基线又变则重试（有上限，见 {@link MAX_MERGE_ATTEMPTS}）；
+ * 4. **绝不隐式创建**——除 `write_node` 的 upsert 以外，写 action 指向不存在的图一律 `not_found`。
+ *
+ * 失败**不抛**（除真 IO 故障的 errno 翻译外）：返回 `{ ok: false, error: ToolError['error'] }`，
+ * `code ∈ { not_found, invalid_args, blocked, conflict, io_error }`。
+ *
+ * 校验分工：本模块只把「读出的文本 → 文档」交给**注入的** `validate`（`shared/validate.ts`
+ * 落地后由 host 装配），外加两条只有存储层才知道的判据——`workflow_dir_collision`
+ * （`.json` 与同名目录并存）与"合并后的终稿先自检再落盘"（用 `readDocument` 复核 canonical 文本）。
+ * @module @xiaoso/dsh-workflow-lite/host/store/repository
+ */
+import { type ChangedEntry, type ExecutionMode, type Handoff, type InputData, type ListResult, type NodeData, type OutputSpec, type Point, type ResourceItem, type ReusePolicy, type ToolError, type ToolWarning, type ValidationProblem, type VersionEntry, type WorkflowDocument, type WriteResult } from '../../shared/types.ts';
+import { type ValidationReport } from '../../shared/validate.ts';
+/** 合并-重试的上限：合并期间磁盘还在变就再读一次，超过这个次数即认输报 `conflict`。 */
+export declare const MAX_MERGE_ATTEMPTS = 5;
+/** 撞名自动加序号的上限（`-2` … `-99`）。 */
+export declare const MAX_SEQUENTIAL = 99;
+export interface LoadResult {
+    /** 名字归一后的图名（`not_found` 时也给出，便于上层报错）。 */
+    name: string;
+    /** 可加载时的规范化文档；**保存级问题 ⇒ `null`**。 */
+    document: WorkflowDocument | null;
+    /** 磁盘上的原文（供只读错误态展示）；不存在时 `null`。 */
+    text: string | null;
+    /** 原文的整图哈希（写前比对的基线）；不存在时 `null`。 */
+    hash: string | null;
+    /** 读入阶段的问题，含 `warning` / `hint`（上层按 `level` 分流）。 */
+    problems: ValidationProblem[];
+    /** `false` ⇒ 拒绝加载：要么保存级非空，要么文档不可用。 */
+    loadable: boolean;
+    /** 那个文件在不在。`loadable=false` 时用它区分 `not_found` 与 `blocked`。 */
+    exists: boolean;
+}
+export interface SaveOptions {
+    /** 加载时记录的整图哈希；`null` = 没有基线（退化为"以磁盘为基线"的合并，不报冲突）。 */
+    baseHash: string | null;
+    /** 画布「保留我的」：冲突也写（冲突 id 以本地为准）。**工具写路径不要传**。 */
+    force?: boolean;
+}
+export interface SaveResult {
+    /** 写回后磁盘内容的整图哈希 ⇒ 新的基线。 */
+    hash: string;
+    changed: ChangedEntry[];
+    warnings: ToolWarning[];
+}
+/** 仓储的统一返回：成功 `{ ok: true, result }`，失败 `{ ok: false, error }`（就是 `ToolError` 的字段）。 */
+export type Outcome<T> = {
+    ok: true;
+    result: T;
+} | {
+    ok: false;
+    error: ToolError['error'];
+};
+/**
+ * 文档级校验器——`shared/validate.ts` 的入口在 host 装配时注入（缺省不做文档级校验）。
+ *
+ * 图名要一起给：校验层有两条规则依赖它（图名的文件名约束、同名目录占位）。
+ * `maxNodes` 这类活配置由装配方闭包进来，仓储不认识 Config。
+ */
+export type DocumentValidator = (document: WorkflowDocument, workflow: string) => ValidationProblem[];
+export interface RepositoryOptions {
+    /** 数据根目录（Config 的 `dataDir`，默认 `~/.dsh/workflow-lite`）。 */
+    dataDir: string;
+    /** 见 {@link DocumentValidator}。 */
+    validate?: DocumentValidator;
+}
+/** `write_node` 的语义入参——`undefined` 一律表示"不改这一项"。 */
+export interface NodeUpsert {
+    /** 节点 id（图内大小写不敏感唯一）；不存在即新建。 */
+    id: string;
+    /** `data.prompt`；允许空串（空 `prompt` 是编译级，不拦落盘）。 */
+    content?: string;
+    /** 显示名；空串 = 清除（回落渲染 `id`）。 */
+    label?: string;
+    /**
+     * 它写的文件（一个路径）；`false` / `null` = 不写任何文件。产出放在资源节点里：
+     * 路径已有资源就连上，没有就新建（见 `shared/resources.ts` 的 `setStepOutputs`）。
+     */
+    output?: string | false | null;
+    /** 一个或多个写入的文件（可带生成规则）；给了它就整份替换（`noOutput` 仍然优先）。 */
+    outputs?: OutputSpec[];
+    /** 一句话描述；空串 = 清除。 */
+    description?: string;
+    /** `true` ⇒ 不写任何文件（与 `output` 同时给出时以本字段为准）。 */
+    noOutput?: boolean;
+    /** 从 `templates/nodes/<from>.json` 取 `data` 本体（**不复制模板的 `id` 与 `position`**）。 */
+    fromTemplate?: string;
+    /** 显式坐标；缺省时新建节点留 `{0,0}` 并报 `position_filled` 提示（布局由上层跑）。 */
+    position?: Point;
+}
+/**
+ * `write_node` 带 `input`：新建或改一个输入节点。给了的字段才改（`kind` 换了会按新题型重新规范化选项与默认值）；
+ * 文字字段空串 = 清除。
+ */
+export interface InputUpsert {
+    id: string;
+    question?: string;
+    kind?: InputData['kind'] | 'text';
+    options?: string[];
+    default?: string | string[];
+    placeholder?: string;
+    hint?: string;
+    required?: boolean;
+    position?: Point;
+}
+/** `write_resource`：新建或修改一个资源节点。给了的字段才改；`items` 给了就整份替换。 */
+export interface ResourceUpsert {
+    /** 资源节点 id；缺省 = 新建，按名字或第一项起一个。 */
+    id?: string;
+    /** 名字；空串 = 清除。 */
+    label?: string;
+    /** 描述；空串 = 清除。 */
+    description?: string;
+    items?: ResourceItem[];
+    position?: Point;
+}
+/** 改工作流设置时给的字段（没给的不动）。 */
+export interface SettingsPatch {
+    outputRoot?: string;
+    mode?: ExecutionMode;
+    reuse?: ReusePolicy;
+    setGoal?: boolean;
+    runState?: boolean;
+}
+export interface Repository {
+    readonly dataDir: string;
+    /** 首次启动按需创建 `workflows/` 与 `templates/nodes/`（**不建 `.dispatch/`**）。 */
+    ensureLayout(): Promise<Outcome<{
+        created: string[];
+    }>>;
+    load(workflow: string): Promise<LoadResult>;
+    save(workflow: string, next: WorkflowDocument, options: SaveOptions): Promise<Outcome<SaveResult>>;
+    list(): Promise<ListResult>;
+    create(workflow: string): Promise<Outcome<WriteResult>>;
+    rename(workflow: string, to: string): Promise<Outcome<WriteResult>>;
+    remove(workflow: string): Promise<Outcome<WriteResult>>;
+    /** 列一个工作流存下的版本（新的在前），标出哪个和磁盘上现在的内容一样。 */
+    listVersions(workflow: string): Promise<Outcome<VersionEntry[]>>;
+    /** 把磁盘上现在的样子存成新版本。和已有的某个版本内容一样就不存（`invalid_args`，`detail.same`）。 */
+    saveVersion(workflow: string, note: string): Promise<Outcome<VersionEntry>>;
+    /** 读一个版本的整张图（切换前看看会变什么）。 */
+    readVersion(workflow: string, n: number): Promise<Outcome<{
+        entry: VersionEntry;
+        document: WorkflowDocument;
+    }>>;
+    /**
+     * 切到某个版本：现在的内容还没存成版本时先自动存一份（`saved`），再把那个版本写回工作流。
+     * 回新的整图哈希。
+     */
+    restoreVersion(workflow: string, n: number): Promise<Outcome<{
+        hash: string;
+        saved: VersionEntry | null;
+    }>>;
+    /** 改版本说明。 */
+    noteVersion(workflow: string, n: number, note: string): Promise<Outcome<VersionEntry>>;
+    deleteVersion(workflow: string, n: number): Promise<Outcome<{
+        removed: true;
+    }>>;
+    /** 读一个节点模板的 `data` 本体（拿去用：半成品一律挡掉）。 */
+    readTemplate(name: string): Promise<Outcome<NodeData>>;
+    /**
+     * 新建一个节点模板文件（`templates/nodes/<名>.json`）。
+     *
+     * 名字撞了报 `conflict`：**不覆盖、也不自动加序号**——名字是人在对话框里指着输的，
+     * 悄悄改名会让他找不到刚建的那个。
+     */
+    createNodeTemplate(name: string, data: NodeData): Promise<Outcome<WriteResult>>;
+    /**
+     * 读一个节点模板给人**编辑**：只挡保存级（文件坏了），提示词还空着之类的编译级问题照样给出来——
+     * 半成品正是要打开来改的。（`readTemplate` 是"拿去用"的那条路，半成品一律挡掉。）
+     */
+    readNodeTemplateDraft(name: string): Promise<Outcome<NodeData>>;
+    /**
+     * 覆盖保存一个**已存在**的节点模板；给了 `from` 且与 `name` 不同就是"改名并保存"：
+     * 新名字被占用报 `conflict`（不覆盖别人的），写好新文件再删旧文件。
+     */
+    saveNodeTemplate(name: string, data: NodeData, from?: string): Promise<Outcome<WriteResult>>;
+    /** 删除一个节点模板文件。不存在报 `not_found`。 */
+    deleteNodeTemplate(name: string): Promise<Outcome<WriteResult>>;
+    writeNode(workflow: string, upsert: NodeUpsert): Promise<Outcome<WriteResult>>;
+    writeResource(workflow: string, upsert: ResourceUpsert): Promise<Outcome<WriteResult>>;
+    writeInput(workflow: string, upsert: InputUpsert): Promise<Outcome<WriteResult>>;
+    setLabel(workflow: string, node: string, label: string): Promise<Outcome<WriteResult>>;
+    /** 改工作流设置（产出根目录、执行方式、复用执行者、设定目标、记录运行状态）；给了的字段才改。 */
+    configure(workflow: string, patch: SettingsPatch): Promise<Outcome<WriteResult>>;
+    deleteNode(workflow: string, node: string): Promise<Outcome<WriteResult>>;
+    connect(workflow: string, source: string, target: string, when?: string, handoff?: Handoff | false | null, update?: boolean): Promise<Outcome<WriteResult>>;
+    disconnect(workflow: string, source: string, target: string, when?: string): Promise<Outcome<WriteResult>>;
+}
+/**
+ * `shared/validate.ts` 的 `ValidationReport` → 仓储的 `ValidationProblem[]`。
+ * 装配时的接线就是这两行（`maxNodes` 是活配置，用闭包每次重读）：
+ *
+ * ```ts
+ * createRepository({
+ *   dataDir,
+ *   validate: (document, workflow) =>
+ *     reportProblems(validateDocument(document, { workflowName: workflow, maxNodes: cfg.maxNodes })),
+ * })
+ * ```
+ */
+export declare function reportProblems(report: ValidationReport): ValidationProblem[];
+/** 把非阻塞问题（警告 / 提示）转成工具线格式的 `warnings`。 */
+export declare function problemsToWarnings(problems: readonly ValidationProblem[]): ToolWarning[];
+/** `before → after` 的变更摘要（`save` 回告用）。 */
+export declare function diffDocuments(before: WorkflowDocument | null, after: WorkflowDocument): ChangedEntry[];
+/** 建一个仓储。`validate` 由 host 在装配时接上 `shared/validate.ts`。 */
+export declare function createRepository(options: RepositoryOptions): Repository;

package/lib/types/host/store/versions.d.ts

@@ -0,0 +1,38 @@
+/**
+ * dsh-workflow-lite — 工作流版本的文件形状：`versions/<图名>/<序号>.json`。
+ *
+ * 一个版本一个文件，文件里是元信息加整张图：
+ *
+ * ```json
+ * { "format": 1, "n": 3, "createdAt": 1759650000000, "note": "跑通了审查环", "document": { … } }
+ * ```
+ *
+ * 切换到别的版本之前自动存的那份多一个 `autoBefore`（切到的版本号）。
+ * 本模块只管读、写、比内容；锁、和磁盘上现在那份比对、切换时写回工作流，都在仓储里。
+ *
+ * @module @xiaoso/dsh-workflow-lite/host/store/versions
+ */
+import type { WorkflowDocument } from '../../shared/types.ts';
+/** 读出来的一个版本；文件坏了 `document` 是 `null`。 */
+export interface StoredVersion {
+    n: number;
+    createdAt: number;
+    note: string;
+    autoBefore?: number;
+    document: WorkflowDocument | null;
+}
+/** 版本文件的规范写法。 */
+export declare function versionText(version: StoredVersion & {
+    document: WorkflowDocument;
+}): string;
+/** 解析一个版本文件；读不出来的字段给缺省，图读不出来就是 `null`。 */
+export declare function parseVersion(text: string, n: number): StoredVersion;
+/** 这个工作流存下的全部版本，新的在前。目录不在 = 没有版本。 */
+export declare function readVersions(dataDir: string, name: string): Promise<StoredVersion[]>;
+/** 只数个数（列工作流时用，不读内容）。 */
+export declare function countVersions(dataDir: string, name: string): Promise<number>;
+/**
+ * 比内容用的键：规范写法，但不算视口——平移缩放画布不算改了工作流。
+ * 卡片位置算（挪了卡片就是另一个样子，切换时会看到「布局」那一行）。
+ */
+export declare function contentKey(document: WorkflowDocument): string;