@yanglaofish/fishtools 0.4.0 → 0.5.0

package/node_modules/@mytools/pack/index.js

@@ -1,15 +1,14 @@
 import { mkdir, writeFile, readFile, readdir, chmod,cp } from 'node:fs/promises';
 import path from 'node:path';
-import { fileURLToPath } from 'node:url';
 import { randomUUID } from 'node:crypto';
 import { collectPackages, copyPackages } from './dependencies.js';
 import { copyRuntime, digest } from './runtime.js';
 import { FlowError } from '@mytools/sdk';
 import YAML from 'yaml';
-import { verifyBundle } from '@mytools/core/bundle';
+import { verifyBundle } from '@mytools/fst-platform/bundle';
 import {planEnvironments} from './environments.js';
 import {archiveDirectory} from './archive.js';
-import {copyDocumentation} from '../core/src/documentation.js';
+import {copyDocumentation} from '@mytools/fst-devtools/documentation';
 export {verifyBundle};
 
 async function hashes(root,dir=root,result={}){
@@ -21,40 +20,49 @@ async function hashes(root,dir=root,result={}){
   }
   return result;
 }
-async function prepare(app,{entries,target,includeWeb=false,portable=false,environments={}}){
-  if(portable)entries=(await app.listWorkflows()).map(w=>w.id);
+function declaredPrivileges(closure,plugins){
+  const used=new Set();
+  const scan=steps=>{for(const step of steps??[]){
+    if(step.action)used.add(step.action);
+    if(step.branch){scan(step.branch.then);scan(step.branch.else);}
+    if(step.parallel)scan(step.parallel.steps);
+  }};
+  for(const workflow of closure.workflows)scan(workflow.steps);
+  const report=[];
+  for(const plugin of plugins){
+    if(plugin.requirements?.privilege)report.push({plugin:plugin.id,scope:'plugin',privilege:plugin.requirements.privilege});
+    for(const [name,action] of Object.entries(plugin.actions??{}))if(used.has(`${plugin.id}:${name}`)&&action.requirements?.privilege)report.push({plugin:plugin.id,action:name,scope:'action',privilege:action.requirements.privilege});
+  }
+  return report;
+}
+async function prepare(source,{entries,target,includeWeb=false,portable=false,environments={}}){
+  // 兼容既有 packApplication(app) 调用，但只使用明确的快照 Interface。
+  const snapshot=typeof source.exportSnapshot==='function'?await source.exportSnapshot({entries,includeWeb,portable}):source;
+  const {closure,plugins}=snapshot;entries=snapshot.entries;
   if(!portable&&!entries?.length)throw new FlowError('请至少选择一个工作流');
   if(!['win32-x64','linux-x64-glibc'].includes(target))throw new FlowError('请选择支持的目标平台');
-  const closure=await app.store.resolve(entries,app.host);
-  const webProvider=[...app.host.definitions.values()].find(plugin=>typeof plugin.services?.web==='function');
-  const ids=new Set(portable?[...app.host.definitions.keys()].filter(id=>id!==webProvider?.id||includeWeb):closure.plugins);
-  for(const id of closure.plugins)ids.add(id);
-  if(includeWeb){if(!webProvider)throw new FlowError('未安装提供 Web 服务的插件');ids.add(webProvider.id);}
-  // Web 与其他入口使用相同的依赖闭包，包含提供者自身的传递依赖。
-  for(const id of ids)for(const dependency of Object.keys(app.host.definitions.get(id)?.dependencies??{}))ids.add(dependency);
-  const plugins=[...ids].map(id=>app.host.definitions.get(id));
+  const ids=new Set(plugins.map(p=>p.id));
   if(plugins.some(p=>!p.root))throw new FlowError('内存中临时定义的插件不能打包，请先安装为标准包');
-  const overrides=structuredClone(app.project.environments??{});
+  const overrides=structuredClone(snapshot.project.environments??{});
   for(const [id,value] of Object.entries(environments))overrides[id]={...overrides[id],...value};
   // 未选中的插件配置不进入导出，但显式拼错的覆盖项应报错。
   for(const id of Object.keys(overrides))if(!ids.has(id)&&!Object.hasOwn(environments,id))delete overrides[id];
   const environmentPlan=await planEnvironments(plugins,target,overrides);
-  return {closure,plugins,environmentPlan,overrides,entries};
+  return {closure,plugins,environmentPlan,overrides,entries,snapshot};
 }
 export async function planApplication(app,options={}){
-  const {plugins,environmentPlan,entries}=await prepare(app,options);
-  return {target:options.target,entries,plugins:plugins.map(p=>({id:p.id,platforms:p.platforms,architectures:p.architectures})),environments:environmentPlan.entries,environmentBytes:environmentPlan.bytes,warnings:environmentPlan.warnings};
+  const {plugins,closure,environmentPlan,entries,snapshot}=await prepare(app,options);
+  return {target:options.target,entries,plugins:plugins.map(p=>({id:p.id,platforms:p.platforms,architectures:p.architectures})),network:snapshot.project.network,privileges:declaredPrivileges(closure,plugins),environments:environmentPlan.entries,environmentBytes:environmentPlan.bytes,warnings:environmentPlan.warnings};
 }
 export async function packApplication(app,{entries,target,outDir='dist',includeWeb=false,runtimePath,cacheDir=path.resolve('.cache','runtimes'),readOnly=false,portable=false,environments={}}={}){
   const prepared=await prepare(app,{entries,target,includeWeb,portable,environments});
-  const {closure,plugins,environmentPlan,overrides}=prepared;entries=prepared.entries;
-  const coreRoot=fileURLToPath(new URL('../core/',import.meta.url)),packRoot=fileURLToPath(new URL('./',import.meta.url));
-  const nodes=await collectPackages([readOnly?coreRoot:packRoot,...plugins.map(p=>p.root)]);
+  const {closure,plugins,environmentPlan,overrides,snapshot}=prepared;entries=prepared.entries;
+  const nodes=await collectPackages([snapshot.toolRoot,...plugins.map(p=>p.root)],{omitOptionalPeers:readOnly?['@mytools/pack']:[]});
   const name=`fishtools-${target}-${Date.now()}-${randomUUID().slice(0,6)}`;
   const directory=path.resolve(outDir,name);await mkdir(directory,{recursive:true});
   const packages=await copyPackages(nodes,path.join(directory,'app'),target,{filters:environmentPlan.filters});
   let runtime;
-  const base=app.project.baseBundle?.root;
+  const base=snapshot.project.baseBundle?.root;
   if(base){
     const previous=JSON.parse(await readFile(path.join(base,'manifest.json'),'utf8'));
     if(previous.target===target&&(readOnly||previous.runtime.npm)){
@@ -70,13 +78,13 @@ export async function packApplication(app,{entries,target,outDir='dist',includeW
   for(const w of closure.workflows)await writeFile(path.join(workflowDir,`${w.id}.yaml`),YAML.stringify(w));
   const config={};
   for(const p of plugins)if(p.defaultConfig)config[p.id]=p.defaultConfig;
-  await writeFile(path.join(directory,'flow.project.json'),JSON.stringify({readOnly,plugins:plugins.map(p=>`./app/node_modules/${p.id}`),config,entries,environments:overrides,logs:app.project.logs},null,2));
+  await writeFile(path.join(directory,'flow.project.json'),JSON.stringify({readOnly,plugins:plugins.map(p=>`./app/node_modules/${p.id}`),config,entries,environments:overrides,network:snapshot.project.network,logs:snapshot.project.logs},null,2));
   const bundleId=randomUUID();
   await writeFile(path.join(directory,'bundle.json'),JSON.stringify({format:2,id:bundleId,editable:!readOnly}));
   await writeFile(path.join(directory,'package.json'),JSON.stringify({private:true,type:'module'},null,2));
   const launch=target==='win32-x64'
-    ? '@echo off\r\n"%~dp0runtime\\node.exe" "%~dp0app\\node_modules\\@mytools\\core\\bin\\fst.js" --project "%~dp0." %*\r\n'
-    : '#!/bin/sh\nROOT=$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)\nexec "$ROOT/runtime/node" "$ROOT/app/node_modules/@mytools/core/bin/fst.js" --project "$ROOT" "$@"\n';
+    ? '@echo off\r\n"%~dp0runtime\\node.exe" "%~dp0app\\node_modules\\@mytools\\fst-cli\\bin\\fst.js" --project "%~dp0." %*\r\n'
+    : '#!/bin/sh\nROOT=$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)\nexec "$ROOT/runtime/node" "$ROOT/app/node_modules/@mytools/fst-cli/bin/fst.js" --project "$ROOT" "$@"\n';
   const launcher=path.join(directory,target==='win32-x64'?'run.cmd':'run.sh');await writeFile(launcher,launch);await chmod(launcher,0o755);
   const fst=path.join(directory,target==='win32-x64'?'fst.cmd':'fst');await writeFile(fst,launch);await chmod(fst,0o755);
   await mkdir(path.join(directory,'bin'),{recursive:true});
@@ -88,7 +96,7 @@ export async function packApplication(app,{entries,target,outDir='dist',includeW
     const file=['app',p.path,e.executable].join('/');executablePaths.add(file);await chmod(path.join(directory,file),0o755);
   }
   await copyDocumentation(path.join(directory,'manual'));
-  const manifest={format:2,bundleId,editable:!readOnly,createdAt:new Date().toISOString(),target,runtime,entries,workflows:closure.workflows.map(w=>w.id),plugins:plugins.map(p=>({id:p.id,version:p.version,platforms:p.platforms,architectures:p.architectures})),environments:environmentPlan.entries,warnings:environmentPlan.warnings,packages,files:await hashes(directory)};
+  const manifest={format:2,bundleId,editable:!readOnly,createdAt:new Date().toISOString(),target,runtime,entries,workflows:closure.workflows.map(w=>w.id),plugins:plugins.map(p=>({id:p.id,version:p.version,platforms:p.platforms,architectures:p.architectures})),network:snapshot.project.network,privileges:declaredPrivileges(closure,plugins),environments:environmentPlan.entries,warnings:environmentPlan.warnings,packages,files:await hashes(directory)};
   await writeFile(path.join(directory,'manifest.json'),JSON.stringify(manifest,null,2));
   const archive=await archiveDirectory(directory,target,executablePaths);
   return {directory,archive,manifest};

package/node_modules/@mytools/pack/package.json

@@ -1 +1,29 @@
-{"name":"@mytools/pack","version":"0.1.0","type":"module","main":"index.js","files":["*.js"],"license":"MIT","dependencies":{"@mytools/core":"0.1.0","@mytools/sdk":"0.1.0","@npmcli/arborist":"10.0.3","archiver":"8.0.0","make-fetch-happen":"16.0.1","npm-packlist":"11.3.0","tar":"7.5.22","yaml":"2.9.1"}}
+{
+  "name": "@mytools/pack",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "index.js",
+  "files": [
+    "*.js"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "@mytools/sdk": "0.1.0",
+    "@npmcli/arborist": "10.0.3",
+    "archiver": "8.0.0",
+    "make-fetch-happen": "16.0.1",
+    "npm-packlist": "11.3.0",
+    "tar": "7.5.22",
+    "yaml": "2.9.1",
+    "@mytools/fst-platform": "0.1.0",
+    "@mytools/fst-devtools": "0.1.0"
+  },
+  "exports": {
+    ".": "./index.js",
+    "./dependencies": "./dependencies.js",
+    "./runtime": "./runtime.js",
+    "./environments": "./environments.js",
+    "./archive": "./archive.js",
+    "./package.json": "./package.json"
+  }
+}

package/node_modules/@mytools/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/node_modules/@mytools/sdk/conditions.js

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

package/node_modules/@mytools/sdk/diagnostics.js

@@ -0,0 +1,27 @@
+import {FlowError} from '@mytools/sdk';
+
+export function pluginError(cause,identity){
+  const error=new FlowError(`插件 ${identity.plugin}（${identity.action??identity.command}）执行失败：${cause?.message??String(cause)}`,{code:cause?.code??'EXECUTION_FAILED',details:cause?.details,cause});
+  return Object.assign(error,identity);
+}
+
+// Error 的 message/stack/cause 默认不可枚举，必须显式转换才会进入 JSON 日志。
+export function errorRecord(error,seen=new Set()){
+  if(error==null||typeof error!=='object')return {message:String(error)};
+  if(seen.has(error)||seen.size>=8)return {message:'错误链已截断'};
+  seen.add(error);
+  const record={name:error.name??'Error',message:error.message??String(error)};
+  for(const key of ['code','plugin','action','command','stack'])if(typeof error[key]==='string')record[key]=error[key];
+  if(error.details!==undefined){
+    try{
+    const objects=new WeakSet();
+    record.details=JSON.parse(JSON.stringify({value:error.details},(_key,value)=>{
+      if(typeof value==='bigint')return String(value);
+      if(value&&typeof value==='object'){if(objects.has(value))return '[循环引用]';objects.add(value);}
+      return value;
+    })).value;
+    }catch(cause){record.details={serializationError:cause?.message??String(cause)};}
+  }
+  if(error.cause!==undefined)record.cause=errorRecord(error.cause,seen);
+  return record;
+}

package/node_modules/@mytools/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/node_modules/@mytools/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/sdk/validation.js

@@ -0,0 +1,78 @@
+import Ajv from 'ajv';
+import { FlowError } from '@mytools/sdk';
+
+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,{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)[Boolean(useDefaults)];
+  let check=cache.get(schema);
+  if(!check){
+    // 每份定义独立解析 $id/$ref，避免插件重载或不同插件共用 ID 时串用约束。
+    // 编译结果仍按对象缓存；注册表随校验器释放，不污染后续安装批次。
+    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;
+}
+
+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,{useDefaults});
+  const copy = structuredClone(value);
+  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;
+}
+
+export function assertId(id) {
+  if (typeof id !== 'string' || !/^[a-zA-Z0-9][a-zA-Z0-9_-]{0,79}$/.test(id)) {
+    throw new FlowError('标识 ID 只能使用字母、数字、下划线和短横线，最多 80 字符', { code: 'VALIDATION' });
+  }
+}
+
+export function referenceParts(ref) {
+  if (typeof ref !== 'string') throw new FlowError('引用必须为字符串', {code:'VALIDATION'});
+  const parts = ref.split('.');
+  if (parts.some(p => !p || ['__proto__', 'constructor', 'prototype'].includes(p))) throw new FlowError(`非法引用字段：${ref}`, {code:'VALIDATION'});
+  if (parts[0] !== 'inputs' && !(parts[0] === 'steps' && parts[2] === 'output')) throw new FlowError(`非法引用：${ref}`, {code:'VALIDATION'});
+  return parts;
+}
+
+export function references(value, visit) {
+  if (!value || typeof value !== 'object') return;
+  if (Object.hasOwn(value, '$ref')) {
+    if (Object.keys(value).length !== 1) throw new FlowError('引用对象不能同时包含其他字段', {code:'VALIDATION'});
+    visit(value.$ref); return;
+  }
+  Object.values(value).forEach(v => references(v, visit));
+}
+
+export function bind(value, context) {
+  if (!value || typeof value !== 'object') return value;
+  if (Object.hasOwn(value, '$ref')) {
+    let current = context;
+    for (const field of referenceParts(value.$ref)) {
+      if (current == null || !Object.hasOwn(current, field)) throw new FlowError(`引用的值不存在：${value.$ref}`,{code:'MISSING_REFERENCE'});
+      current = current[field];
+    }
+    return structuredClone(current);
+  }
+  if (Array.isArray(value)) return value.map(v => bind(v, context));
+  return Object.fromEntries(Object.entries(value).map(([key, v]) => [key, bind(v, context)]));
+}

package/node_modules/@mytools/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/node_modules/@mytools/web/package.json

@@ -6,6 +6,7 @@
   "files": [
     "index.js",
     "server.js",
+    "src/model.js",
     "public"
   ],
   "license": "MIT",
@@ -28,5 +29,11 @@
     "react": "19.3.0",
     "react-dom": "19.3.0",
     "vite": "8.3.4"
+  },
+  "exports": {
+    ".": "./index.js",
+    "./server": "./server.js",
+    "./model": "./src/model.js",
+    "./package.json": "./package.json"
   }
 }