@yanglaofish/fishtools 0.3.0 → 0.5.0

package/manual/packages/sdk/README.md

@@ -0,0 +1,31 @@
+# SDK模块
+
+包名：`@mytools/sdk`。内部 workspace 包，随 `@yanglaofish/fishtools` 统一交付。
+
+## 职责与边界
+
+插件定义、错误和共享 schema/条件契约。不承接宿主生命周期、磁盘持久化或界面行为。
+
+内部依赖：无。
+## 公开入口
+
+| 导入路径 | 实现位置 |
+| --- | --- |
+| `@mytools/sdk` | `./index.js` |
+| `@mytools/sdk/schema` | `./validation.js` |
+| `@mytools/sdk/schema-path` | `./schema-path.js` |
+| `@mytools/sdk/diagnostics` | `./diagnostics.js` |
+| `@mytools/sdk/conditions` | `./conditions.js` |
+| `@mytools/sdk/package.json` | `./package.json` |
+
+仅依赖 exports 声明的入口，禁止消费者跨包读取 src/bin 私有文件。入口路径由本模块维护，修改协议时同步消费方回归。
+
+## 维护与验证
+
+本模块负责上述职责的实现、文档与回归；跨模块接口调整需要同时检查生产者与消费者。具体维护人员尚未指定。
+
+在仓库根目录执行：
+
+```sh
+node --test tests/modules.test.js tests/plugin-contract.test.js tests/schema-diagnostics.test.js
+```

package/manual/packages/sdk/conditions.js

@@ -0,0 +1 @@
+export const conditionOperators=['eq','ne','gt','gte','lt','lte','contains','exists'];

package/manual/packages/sdk/package.json

@@ -1 +1,23 @@
-{"name":"@mytools/sdk","version":"0.1.0","type":"module","main":"index.js","exports":"./index.js","files":["index.js","README.md"],"license":"MIT"}
+{
+  "name": "@mytools/sdk",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "index.js",
+  "exports": {
+    ".": "./index.js",
+    "./schema": "./validation.js",
+    "./schema-path": "./schema-path.js",
+    "./diagnostics": "./diagnostics.js",
+    "./conditions": "./conditions.js",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "*.js",
+    "README.md",
+    "LICENSE"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "ajv": "8.20.0"
+  }
+}

package/manual/packages/sdk/schema-path.js

@@ -0,0 +1,31 @@
+import {FlowError} from '@mytools/sdk';
+
+const forbidden=new Set(['__proto__','constructor','prototype']);
+const missing=ref=>{throw new FlowError(`引用字段不存在：${ref}`,{code:'VALIDATION'});};
+
+// 路径只用于已声明的字段；开放对象可继续引用，带类型的动态键则继续逐层检查。
+export function resolveSchemaPath(schema,fields,ref=Array.isArray(fields)?fields.join('.'):fields){
+  const parts=Array.isArray(fields)?fields:typeof fields==='string'?fields.split('.'):[];
+  if(!parts.length)return schema;
+  if(parts.some(part=>typeof part!=='string'||!part||forbidden.has(part)))missing(ref);
+  let current=schema;
+  for(const field of parts){
+    if(current===true){continue;}
+    if(current===false||!current||typeof current!=='object'||Array.isArray(current))missing(ref);
+    const types=Array.isArray(current.type)?current.type:[current.type];
+    const isArray=types.includes('array')||current.items!==undefined;
+    if(isArray){
+      if(!/^(0|[1-9]\d*)$/.test(field))missing(ref);
+      if(Array.isArray(current.items))current=current.items[Number(field)]??current.additionalItems??true;
+      else current=current.items??true;
+      continue;
+    }
+    if(current.properties&&Object.hasOwn(current.properties,field)){
+      current=current.properties[field];continue;
+    }
+    if(!types.includes('object')&&types.some(type=>type!==undefined))missing(ref);
+    current=current.additionalProperties??true;
+  }
+  if(current===false)missing(ref);
+  return current;
+}

package/{node_modules/@mytools/core/src → manual/packages/sdk}/validation.js

@@ -1,29 +1,42 @@
 import Ajv from 'ajv';
 import { FlowError } from '@mytools/sdk';
 
-const ajv = new Ajv({ allErrors: true, strict: false, useDefaults: true });
-const validators = new WeakMap();
-const booleanValidators = new Map();
+const ajv = new Ajv({ allErrors: true, strict: false });
+const validators = {true:new WeakMap(),false:new WeakMap()};
+const booleanValidators = {true:new Map(),false:new Map()};
 export const emptyObject = { type: 'object', properties: {}, additionalProperties: false };
 
-export function assertSchema(schema,label) {
+export function assertSchema(schema,label,{useDefaults=true}={}) {
   if (!(typeof schema==='boolean'||schema&&typeof schema==='object'&&!Array.isArray(schema))) throw new FlowError(`${label} 必须声明有效的 JSON Schema`,{code:'VALIDATION'});
-  const cache=typeof schema==='boolean'?booleanValidators:validators;
+  const cache=(typeof schema==='boolean'?booleanValidators:validators)[Boolean(useDefaults)];
   let check=cache.get(schema);
   if(!check){
     // 每份定义独立解析 $id/$ref，避免插件重载或不同插件共用 ID 时串用约束。
     // 编译结果仍按对象缓存；注册表随校验器释放，不污染后续安装批次。
-    try{check=new Ajv({allErrors:true,strict:false,useDefaults:true}).compile(schema);cache.set(schema,check);}
+    try{check=new Ajv({allErrors:true,strict:false,useDefaults:Boolean(useDefaults)}).compile(schema);cache.set(schema,check);}
     catch(cause){throw new FlowError(`${label} JSON Schema 无效：${cause.message}`,{code:'VALIDATION',cause});}
   }
   return check;
 }
 
-export function validate(schema, value, label) {
+const pointerToken=value=>String(value).replaceAll('~','~0').replaceAll('/','~1');
+function diagnostic(error){
+  let instancePath=error.instancePath;
+  if(error.keyword==='required')instancePath+=`/${pointerToken(error.params.missingProperty)}`;
+  if(error.keyword==='additionalProperties')instancePath+=`/${pointerToken(error.params.additionalProperty)}`;
+  // 保留 Ajv 原有 instancePath 语义，新字段提供指向缺失/额外属性的完整位置。
+  return {...error,jsonPointer:instancePath};
+}
+
+export function validate(schema, value, label,{useDefaults=true}={}) {
   if (schema==null) return structuredClone(value);
-  const check = assertSchema(schema,label);
+  const check = assertSchema(schema,label,{useDefaults});
   const copy = structuredClone(value);
-  if (!check(copy)) throw new FlowError(`${label}: ${ajv.errorsText(check.errors, { separator: '；' })}`, { code: 'VALIDATION', details: check.errors });
+  if (!check(copy)) {
+    const details=check.errors.map(diagnostic);
+    const locations=details.map(error=>`${error.jsonPointer||'/'} (${error.schemaPath})`).join('；');
+    throw new FlowError(`${label}: ${ajv.errorsText(check.errors, { separator: '；' })}；位置 ${locations}`, { code: 'VALIDATION', details });
+  }
   return copy;
 }
 

package/manual/plugins/web/README.md

@@ -0,0 +1,29 @@
+# Web模块
+
+包名：`@mytools/web`。内部 workspace 包，随 `@yanglaofish/fishtools` 统一交付。
+
+## 职责与边界
+
+官方 Web 插件、HTTP 服务、前端交互及模型投影。通过服务工厂参数获得应用接口，前端构建产物仍在本包 public 中。
+
+内部依赖：`@mytools/sdk`。
+## 公开入口
+
+| 导入路径 | 实现位置 |
+| --- | --- |
+| `@mytools/web` | `./index.js` |
+| `@mytools/web/server` | `./server.js` |
+| `@mytools/web/model` | `./src/model.js` |
+| `@mytools/web/package.json` | `./package.json` |
+
+仅依赖 exports 声明的入口，禁止消费者跨包读取 src/bin 私有文件。入口路径由本模块维护，修改协议时同步消费方回归。
+
+## 维护与验证
+
+本模块负责上述职责的实现、文档与回归；跨模块接口调整需要同时检查生产者与消费者。具体维护人员尚未指定。
+
+在仓库根目录执行：
+
+```sh
+node --test tests/modules.test.js tests/web.test.js tests/web-control.test.js
+```

package/manual/tests/application.test.js

@@ -2,9 +2,9 @@ import test from 'node:test';
 import assert from 'node:assert/strict';
 import { mkdir, writeFile, readFile } from 'node:fs/promises';
 import path from 'node:path';
-import { createApplication } from '../packages/core/src/application.js';
+import { createApplication } from '@mytools/core';
 import { temporary, testPlugin, object } from './helpers.js';
-import {validate} from '../packages/core/src/validation.js';
+import {validate} from '@mytools/sdk/schema';
 
 test('同 ID schema 隔离编译，保留内嵌引用且不串用旧约束',()=>{
   const schema=type=>({$id:'https://fishtools.test/review/config',type:'object',definitions:{value:{type}},properties:{value:{$ref:'#/definitions/value'}},required:['value']});
@@ -47,7 +47,8 @@ test('运行快照独立于之后保存，状态与日志持久化',async t=>{
   assert.deepEqual(app.getRun(run.id).output,{text:'HELLO'});
   const events=(await readFile(path.join(app.outputDir,run.id,'events.jsonl'),'utf8')).trim().split('\n').map(JSON.parse);
   assert.ok(events.some(e=>e.type==='run.succeeded'));
-  assert.ok(!events.some(e=>Object.hasOwn(e,'output')));
+  assert.deepEqual(events.find(e=>e.type==='run.result').output,{text:'HELLO'});
+  assert.deepEqual(events.find(e=>e.type==='step.succeeded').output,{text:'HELLO'});
 });
 
 test('仓库外本地插件可以安装、加载并执行，移除后目录同步',async t=>{
@@ -61,7 +62,8 @@ test('仓库外本地插件可以安装、加载并执行，移除后目录同
   await app.saveWorkflow({id:'external',schemaVersion:1,inputs:object(),steps:[{id:'hello',action:'external-flow-test:hello',with:{}}],outputs:{answer:{$ref:'steps.hello.output.value'}}});
   const run=await app.startRun('external',{});await run.done;
   assert.deepEqual(app.getRun(run.id).output,{answer:42});
-  await app.removePlugin('external-flow-test');
+  await assert.rejects(app.removePlugin('external-flow-test'),error=>error.code==='PLUGIN_IN_USE'&&error.details.workflows[0].id==='external');
+  await app.removePlugin('external-flow-test',{force:true});
   assert.ok(!app.catalog().some(a=>a.id==='external-flow-test:hello'));
 });
 

package/node_modules/@mytools/core/README.md

@@ -0,0 +1,44 @@
+# 应用内核模块
+
+包名：`@mytools/core`。内部 workspace 包，随 `@yanglaofish/fishtools` 统一交付。
+
+## 职责与边界
+
+组合各能力模块、协调运行与关闭、提供 CLI/Web 共用应用接口及导出声明快照。日志写入和缓存由 logs 负责；导出实现通过可选 pack 依赖加载。
+
+内部依赖：`@mytools/sdk`、`@mytools/fst-platform`、`@mytools/fst-logs`、`@mytools/fst-workflow`、`@mytools/fst-plugin`、`@mytools/fst-workspace`、`@mytools/pack`。
+`@mytools/pack` 是可选 peer 依赖；普通发行包含它，只读发行省略它。既有 `/process`、`/bundle`、`/environments` 子入口保留兼容转发。
+
+## 公开入口
+
+| 导入路径 | 实现位置 |
+| --- | --- |
+| `@mytools/core` | `./src/application.js` |
+| `@mytools/core/version` | `./src/version.js` |
+| `@mytools/core/process` | `./src/process.js` |
+| `@mytools/core/environments` | `./src/environments.js` |
+| `@mytools/core/bundle` | `./src/bundle.js` |
+| `@mytools/core/development` | `./src/development.js` |
+| `@mytools/core/package.json` | `./package.json` |
+
+仅依赖 exports 声明的入口，禁止消费者跨包读取 src/bin 私有文件。入口路径由本模块维护，修改协议时同步消费方回归。
+
+## 维护与验证
+
+本模块负责上述职责的实现、文档与回归；跨模块接口调整需要同时检查生产者与消费者。具体维护人员尚未指定。
+
+在仓库根目录执行：
+
+```sh
+node --test tests/modules.test.js tests/application.test.js tests/lifecycle.test.js tests/module-interfaces.test.js
+```
+
+## 开发监督进程
+
+`createDevelopmentSupervisor({projectDir,entry,args,env,configFile,onEvent})` 启动文件监听 worker 和应用子进程，返回 `status()`、幂等 `close()`。父进程不加载插件运行模块；每次重启使用全新的 Node 进程，完整更新 ESM 导入依赖。`bindDevelopmentChild(app,{details,closePresentation})` 通过 IPC 报告就绪，收到重启请求后等待 `app.developmentStatus()` 的运行和管理操作均为空闲，再调用 `app.close()` 及界面清理。
+
+监听来源为项目 `.flow/plugins.json` 的 `links`，同时监听项目配置、插件状态和显式配置覆盖文件。独立 worker 跳过 `node_modules`、`.git`、`.flow`、`dist` 及符号链接；默认限制 512 个源码目录、20000 个扫描条目和 24 层深度。超出预算或扫描超时会明确报告未完整监听，独立进程扫描避免挂载目录的 I/O 阻塞监督器。只读项目拒绝启用开发模式。
+
+源码变化默认合并 180 ms。关闭超时从应用报告空闲并开始关闭后计时，默认 5 秒；启动超时默认 15 秒。强制终止后最多等待 2 秒确认回收，未确认退出的子进程继续占用预算，不能启动重叠宿主。`onEvent` 提供 `ready/changed/waiting/restarting/failed/forced/blocked/watchError/closed` 等状态，启动失败保留源码监听，修复后可再次启动。
+
+验证：`node --test tests/development-watch.test.js` 使用真实非交互子进程验证完整模块图、忙碌等待、连续保存、源码修复、关闭与配置刷新，并验证真实 Web 重启。

package/node_modules/@mytools/core/package.json

@@ -5,32 +5,34 @@
   "main": "src/application.js",
   "exports": {
     ".": "./src/application.js",
+    "./version": "./src/version.js",
     "./process": "./src/process.js",
+    "./environments": "./src/environments.js",
     "./bundle": "./src/bundle.js",
-    "./environments": "./src/environments.js"
-  },
-  "bin": {
-    "fst": "bin/fst.js"
+    "./development": "./src/development.js",
+    "./package.json": "./package.json"
   },
   "files": [
     "src",
-    "bin",
-    "templates"
+    "README.md",
+    "LICENSE"
   ],
   "license": "MIT",
   "engines": {
     "node": ">=24.15.0"
   },
   "dependencies": {
-    "@mariozechner/pi-tui": "0.50.0",
     "@mytools/sdk": "0.1.0",
-    "ajv": "8.20.0",
-    "commander": "14.0.3",
-    "cordis": "3.18.1",
-    "execa": "10.1.0",
-    "semver": "7.7.4",
-    "tree-kill": "1.2.2",
-    "which": "7.0.0",
-    "yaml": "2.9.1"
+    "@mytools/fst-platform": "0.1.0",
+    "@mytools/fst-logs": "0.1.0",
+    "@mytools/fst-workflow": "0.1.0",
+    "@mytools/fst-plugin": "0.1.0",
+    "@mytools/fst-workspace": "0.1.0"
+  },
+  "peerDependencies": {
+    "@mytools/pack": "0.1.0"
+  },
+  "peerDependenciesMeta": {
+    "@mytools/pack": {"optional": true}
   }
 }