@yanglaofish/fishtools 0.5.1 → 0.5.2

package/node_modules/@mytools/fst-workspace/README.md

@@ -17,12 +17,15 @@
 | `@mytools/fst-workspace/plugins` | `./src/plugins.js` |
 | `@mytools/fst-workspace/installations` | `./src/plugin-installations.js` |
 | `@mytools/fst-workspace/bundles` | `./src/bundle-workspace.js` |
+| `@mytools/fst-workspace/shortcuts` | `./src/shortcuts.js` |
 | `@mytools/fst-workspace/package.json` | `./package.json` |
 
 仅依赖 exports 声明的入口，禁止消费者跨包读取 src/bin 私有文件。入口路径由本模块维护，修改协议时同步消费方回归。
 
 ## 维护与验证
 
+`/shortcuts` 提供 `validateShortcuts` 校验、`bindShortcutCommands` 在用户配置时补齐命令提供者身份，以及 `describeShortcuts` 生成可用或失效状态。绑定函数可传入 previous 保留旧项：未绑定命令修改参数或重命名仍保持失效，需重新选择目标。命令项使用 command 与 plugin 同时匹配，动作项使用稳定 action ID；不执行其他插件的同名能力。实际保存、备份与宿主装配由 core 协调。
+
 本模块负责上述职责的实现、文档与回归；跨模块接口调整需要同时检查生产者与消费者。具体维护人员尚未指定。
 
 在仓库根目录执行：

package/node_modules/@mytools/fst-workspace/package.json

@@ -8,6 +8,7 @@
     ".": "./src/index.js",
     "./workflows": "./src/workflows.js",
     "./project": "./src/project.js",
+    "./shortcuts": "./src/shortcuts.js",
     "./plugins": "./src/plugins.js",
     "./installations": "./src/plugin-installations.js",
     "./bundles": "./src/bundle-workspace.js",

package/node_modules/@mytools/fst-workspace/src/shortcuts.js

@@ -0,0 +1,119 @@
+import {FlowError} from '@mytools/sdk';
+import {builtinCommands,isCommandName} from '@mytools/fst-plugin/contracts';
+import {isBuiltin} from 'node:module';
+
+const dangerousFields=new Set(['__proto__','constructor','prototype']);
+const shortcutFields=new Set(['action','command','plugin','input']);
+
+function validPluginId(value){
+  if(typeof value!=='string'||!value.length||value.length>214||value!==value.toLowerCase()||isBuiltin(value)||['node_modules','favicon.ico'].includes(value))return false;
+  const parts=/^(?:@([^/]+)\/)?([^/]+)$/.exec(value);
+  if(!parts||/^[._-]/.test(value)||parts[2].startsWith('.'))return false;
+  return (!parts[1]||/^[a-z0-9_.~'!()*-]+$/.test(parts[1]))&&/^[a-z0-9_.-]+$/.test(parts[2]);
+}
+
+function invalid(location,message){
+  throw new FlowError(message,{code:'VALIDATION',details:{path:location}});
+}
+
+function plainObject(value){
+  return value!==null&&typeof value==='object'&&!Array.isArray(value)&&[Object.prototype,null].includes(Object.getPrototypeOf(value));
+}
+
+function entries(value,location){
+  if(!plainObject(value))invalid(location,`${location} 必须为普通 JSON 对象`);
+  return Reflect.ownKeys(value).map(key=>{
+    if(typeof key!=='string'||dangerousFields.has(key))invalid(location,`${location} 包含危险或非 JSON 字段`);
+    const field=Object.getOwnPropertyDescriptor(value,key);
+    if(!field.enumerable||!Object.hasOwn(field,'value'))invalid(`${location}.${key}`,`${location}.${key} 必须为普通 JSON 字段`);
+    return [key,field.value];
+  });
+}
+
+function cloneJson(value,location,ancestors=new Set()){
+  if(value===null||typeof value==='string'||typeof value==='boolean')return value;
+  if(typeof value==='number'&&Number.isFinite(value))return value;
+  if(typeof value!=='object')invalid(location,`${location} 必须为可序列化的 JSON 值`);
+  if(ancestors.has(value))invalid(location,`${location} 不能包含循环引用`);
+  ancestors.add(value);
+  try{
+    if(Array.isArray(value)){
+      if(Object.getPrototypeOf(value)!==Array.prototype||Reflect.ownKeys(value).length!==value.length+1)invalid(location,`${location} 必须为普通且完整的 JSON 数组`);
+      const copy=[];
+      for(let index=0;index<value.length;index++){
+        const field=Object.getOwnPropertyDescriptor(value,String(index));
+        if(!field?.enumerable||!Object.hasOwn(field,'value'))invalid(`${location}[${index}]`,`${location} 必须为普通且完整的 JSON 数组`);
+        copy.push(cloneJson(field.value,`${location}[${index}]`,ancestors));
+      }
+      return copy;
+    }
+    return Object.fromEntries(entries(value,location).map(([key,nested])=>[key,cloneJson(nested,`${location}.${key}`,ancestors)]));
+  }finally{ancestors.delete(value);}
+}
+
+export function validateShortcuts(shortcuts,{reservedNames=[]}={}){
+  if(!Array.isArray(reservedNames)||reservedNames.some(name=>typeof name!=='string'))invalid('reservedNames','保留名称必须为字符串数组');
+  const reserved=new Set([...builtinCommands.map(command=>command.name),...reservedNames].map(name=>name.normalize('NFC')));
+  const copy={};
+  for(const [name,shortcut] of entries(shortcuts,'shortcuts')){
+    const location=`shortcuts.${name}`;
+    // 明确拒绝未规范化名称，避免两个视觉相同的入口指向不同能力。
+    if(name!==name.normalize('NFC'))invalid(location,`快捷名称必须使用 NFC 规范形式：${name}`);
+    if(!isCommandName(name))invalid(location,`快捷名称无效：/${name}`);
+    if(reserved.has(name))invalid(location,`快捷名称与现有命令冲突：/${name}`);
+    reserved.add(name);
+    const fields=entries(shortcut,location);
+    if(fields.some(([key])=>!shortcutFields.has(key)))invalid(location,`快捷项 ${name} 包含未声明字段`);
+    const hasAction=Object.hasOwn(shortcut,'action'),hasCommand=Object.hasOwn(shortcut,'command');
+    if(hasAction===hasCommand)invalid(location,`快捷项 ${name} 必须声明 action 或 command 之一`);
+    const field=hasAction?'action':'command',target=shortcut[field];
+    if(hasAction){
+      const separator=typeof target==='string'?target.lastIndexOf(':'):-1;
+      if(separator<=0||separator===target.length-1||/[\s\p{C}]/u.test(target))invalid(`${location}.action`,`快捷项 ${name} 的 action 必须为稳定动作 ID`);
+    }else if(!isCommandName(target))invalid(`${location}.command`,`快捷项 ${name} 的 command 名称无效`);
+    copy[name]={[field]:target};
+    if(Object.hasOwn(shortcut,'plugin')){
+      if(hasAction)invalid(`${location}.plugin`,`动作快捷项 ${name} 不能声明 plugin`);
+      if(!validPluginId(shortcut.plugin))invalid(`${location}.plugin`,`快捷项 ${name} 的 plugin 必须为合法插件包 ID`);
+      copy[name].plugin=shortcut.plugin;
+    }
+    if(Object.hasOwn(shortcut,'input')){
+      if(!plainObject(shortcut.input))invalid(`${location}.input`,`快捷项 ${name} 的 input 必须为普通 JSON 对象`);
+      copy[name].input=cloneJson(shortcut.input,`${location}.input`);
+    }
+  }
+  return copy;
+}
+
+export function bindShortcutCommands(shortcuts,{commands=[],previous={}}={}){
+  const copy=validateShortcuts(shortcuts);
+  const old=validateShortcuts(previous),unbound=new Set(Object.values(old).filter(shortcut=>shortcut.command&&shortcut.plugin===undefined).map(shortcut=>shortcut.command));
+  for(const [name,shortcut] of Object.entries(copy)){
+    // 已有未绑定项即使改参数或重命名也需明确选择目标，不能被整组保存顺带启用。
+    if(!Object.hasOwn(shortcut,'command')||Object.hasOwn(shortcut,'plugin'))continue;
+    if(old[name]?.command===shortcut.command||unbound.has(shortcut.command))continue;
+    const command=commands.find(command=>command.name===shortcut.command);
+    if(command?.plugin!==undefined)shortcut.plugin=command.plugin;
+  }
+  return validateShortcuts(copy);
+}
+
+export function describeShortcuts(shortcuts,{actions=[],commands=[]}={}){
+  const actionIndex=new Map(actions.map(action=>[action.id,action]));
+  return Object.entries(validateShortcuts(shortcuts)).map(([name,shortcut])=>{
+    const field=Object.hasOwn(shortcut,'action')?'action':'command';
+    const id=shortcut[field];
+    let definition;
+    if(field==='action')definition=actionIndex.get(id);
+    else if(shortcut.plugin!==undefined)definition=commands.find(command=>command.name===id&&command.plugin===shortcut.plugin);
+    const descriptions=field==='action'?[definition?.title,definition?.description]:[definition?.description];
+    const target={[field]:id};
+    if(shortcut.plugin!==undefined)target.plugin=shortcut.plugin;
+    const entry={name,target,input:shortcut.input??{},available:Boolean(definition),description:descriptions.find(value=>typeof value==='string'&&value.trim())??id};
+    if(!definition){
+      if(field==='command'&&shortcut.plugin===undefined)entry.reason='尚未绑定目标插件，请重新选择目标';
+      else entry.reason=`${field==='action'?'动作':'命令'}不可用或尚未安装：${shortcut.plugin?`${shortcut.plugin} → `:''}${id}`;
+    }
+    return entry;
+  });
+}

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

@@ -78,7 +78,7 @@ 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,network:snapshot.project.network,logs:snapshot.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,commandPresets:snapshot.project.commandPresets,shortcuts:snapshot.project.shortcuts},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));