@petercjl/boardmixcli 0.0.0-stage → 0.1.6

package/lib/bridge.mjs

@@ -0,0 +1,61 @@
+import {inspectVideo} from './video.mjs';
+import http from 'node:http';
+import {randomBytes, randomUUID} from 'node:crypto';
+import {readFile} from 'node:fs/promises';
+import {validate} from './protocol.mjs';
+import {inspectImage} from './assets.mjs';
+
+const main = await readFile(new URL('../plugin/main.js', import.meta.url), 'utf8');
+const pageAdapter = await readFile(new URL('./page-adapter.js',import.meta.url),'utf8');
+export async function startBridge() {
+  const token = randomBytes(32).toString('hex');
+  const queue = [], pending = new Map(), assets=new Map(),clients=new Map(),outcomes=new Map();
+  let lastSeen = 0;
+  function reply(res,status,data) { res.writeHead(status,{'Content-Type':'application/json','Access-Control-Allow-Origin':'*','Cache-Control':'no-store'}); res.end(JSON.stringify(data)); }
+  async function body(req) { let s=''; for await (const c of req) {s+=c; if(s.length>1024*1024) throw new Error('BODY_TOO_LARGE');} return JSON.parse(s || '{}'); }
+  const server = http.createServer(async(req,res)=>{
+    const host = `127.0.0.1:${server.address().port}`;
+    if(req.headers.host !== host) return reply(res,403,{error:'INVALID_HOST'});
+    if(req.method==='OPTIONS') {res.writeHead(204,{'Access-Control-Allow-Origin':'*','Access-Control-Allow-Headers':'Authorization,Content-Type','Access-Control-Allow-Methods':'GET,POST,OPTIONS','Access-Control-Allow-Private-Network':'true'});return res.end();}
+    if(req.headers.authorization !== `Bearer ${token}`) return reply(res,401,{error:'UNAUTHORIZED'});
+    try {
+      if(req.method==='GET' && req.url==='/status') return reply(res,200,{connected:Date.now()-lastSeen<5000,pending:pending.size,clients:Array.from(clients,([fileKey,time])=>({fileKey,connected:Date.now()-time<5000}))});
+      if(req.method==='GET' && req.url==='/bootstrap') return reply(res,200,{script:bootstrap()});
+      if(req.method==='POST'&&req.url==='/register-asset'){
+        const input=await body(req);if(typeof input.file!=='string')throw Error('FILE_REQUIRED');
+        const a=await (input.kind==='video'?inspectVideo:inspectImage)(input.file);if(a.sha256!==input.sha256)throw Error('ASSET_CHANGED');assets.set(a.sha256,a);return reply(res,200,{assetId:a.sha256,...a});
+      }
+      if(req.method==='GET'&&req.url.startsWith('/asset-info/')){const a=assets.get(req.url.slice('/asset-info/'.length));if(!a)return reply(res,404,{error:'ASSET_NOT_REGISTERED'});const {file,...publicInfo}=a;return reply(res,200,publicInfo);}
+      if(req.method==='GET'&&req.url.startsWith('/asset/')){const a=assets.get(req.url.slice('/asset/'.length));if(!a)return reply(res,404,{error:'ASSET_NOT_REGISTERED'});const current=await (a.kind==='video'?inspectVideo:inspectImage)(a.file);if(current.sha256!==a.sha256)throw Error('ASSET_CHANGED');res.writeHead(200,{'Content-Type':a.mime,'Access-Control-Allow-Origin':'*','Cache-Control':'no-store'});return res.end(await readFile(a.file));}
+      if(req.method==='GET'&&req.url.startsWith('/outcome/'))return reply(res,200,outcomes.get(req.url.slice('/outcome/'.length))||{error:'OUTCOME_NOT_FOUND'});
+      if(req.method==='GET' && req.url.startsWith('/next')) {lastSeen=Date.now();const key=new URL(req.url,'http://localhost').searchParams.get('fileKey');if(key)clients.set(key,lastSeen);const i=queue.findIndex(x=>!key||x.fileKey===key);return reply(res,200,{request:i<0?null:queue.splice(i,1)[0]});}
+      if(req.method==='POST' && req.url==='/result') {
+        const r=await body(req); const task=pending.get(r.id);
+        if(task){lastSeen=Date.now();clients.set(task.fileKey,lastSeen);}
+        outcomes.set(r.id,r);if(task) {clearTimeout(task.timer);pending.delete(r.id);reply(task.res,200,r);}
+        return reply(res,200,{accepted:!!task});
+      }
+      if(req.method==='POST' && req.url==='/request') {
+        const input=validate(await body(req));
+        if(input.op==='image.import.batch'&&input.params.items.some(i=>!assets.has(i.assetId)))throw Error('ASSET_NOT_REGISTERED');
+        if(['image.import','video.import'].includes(input.op)&&!assets.has(input.params.assetId))throw Error('ASSET_NOT_REGISTERED');
+        const operationId=['image.import.batch','video.import'].includes(input.op)?input.params.operationId:null;
+        if(operationId&&outcomes.has(operationId))return reply(res,200,outcomes.get(operationId));
+        if(operationId&&pending.has(operationId))return reply(res,409,{error:'OPERATION_PENDING'});
+        if(clients.size&&Date.now()-(clients.get(input.fileKey)||0)>=5000)return reply(res,409,{error:'TARGET_BOARD_NOT_CONNECTED'});
+        if(Date.now()-lastSeen>=5000) return reply(res,409,{error:'PLUGIN_NOT_CONNECTED'});
+        if(pending.size) return reply(res,409,{error:'BUSY'});
+        const id=operationId||randomUUID(); const task={id,channel:'boardmixcli-v1',...input};
+        const timer=setTimeout(()=>{pending.delete(id);const i=queue.findIndex(x=>x.id===id);if(i>=0)queue.splice(i,1);reply(res,504,{error:'OUTCOME_UNKNOWN',id,retrySafe:['info','board.info','object.get','object.get.batch','object.list'].includes(input.op)});},['video.import','image.import','image.import.batch'].includes(input.op)?150000:30000);
+        pending.set(id,{res,timer,fileKey:input.fileKey});queue.push(task);return;
+      }
+      reply(res,404,{error:'NOT_FOUND'});
+    } catch(error) {reply(res,400,{error:error.message});}
+  });
+  await new Promise((resolve,reject)=>{server.once('error',reject);server.listen(0,'127.0.0.1',resolve);});
+  const endpoint=`http://127.0.0.1:${server.address().port}`;
+  function bootstrap() {
+    return `(${pageAdapter})(${JSON.stringify({endpoint,token})},${JSON.stringify(main)})`;
+  }
+  return {server,endpoint,token,bootstrap};
+}

package/lib/browser-process.mjs

@@ -0,0 +1,61 @@
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { execFile, spawn } from 'node:child_process';
+import { promisify } from 'node:util';
+
+const exec = promisify(execFile);
+export const profile = path.join(os.homedir(), '.dianshang-chrome-profile');
+const chrome = '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome';
+const cdp = 'http://127.0.0.1:9223';
+function fail(code, message) { return Object.assign(new Error(message), { code }); }
+
+export function matchesProcess(command, expectedProfile = profile) {
+  return command.startsWith(`${chrome} `)
+    && /(?:^|\s)--remote-debugging-port=9223(?:\s|$)/.test(command)
+    && (command.includes(`--user-data-dir=${expectedProfile} `) || command.endsWith(`--user-data-dir=${expectedProfile}`))
+    && !command.includes('--no-sandbox');
+}
+
+export async function status() {
+  if (process.platform !== 'darwin') throw fail('UNSUPPORTED_PLATFORM', '此安装版只支持 macOS');
+  let listeners;
+  try { listeners = (await exec('/usr/sbin/lsof', ['-b', '-nP', '-t', '-iTCP:9223', '-sTCP:LISTEN'], { timeout: 5000 })).stdout.trim(); }
+  catch (error) { if (error.code === 1 && !error.stderr) listeners = ''; else throw error; }
+  if (!listeners) return { ok: false, state: 'stopped', cdp, profile };
+  const pids = [...new Set(listeners.split(/\s+/))];
+  for (const pid of pids) {
+    const command = (await exec('/bin/ps', ['-p', pid, '-o', 'command='])).stdout.trim();
+    if (!matchesProcess(command)) throw fail('PORT_CONFLICT', '9223 端口不是指定的安全电商浏览器；未停止或修改任何进程');
+  }
+  try {
+    const response = await fetch(`${cdp}/json/version`, { signal: AbortSignal.timeout(1500), redirect: 'error' });
+    const value = await response.json();
+    if (!response.ok || !value.Browser?.includes('Chrome/') || !value.webSocketDebuggerUrl) throw new Error('CDP 无效');
+    return { ok: true, state: 'ready', cdp, profile, pids, browser: value.Browser };
+  } catch { return { ok: false, state: 'starting', cdp, profile, pids }; }
+}
+
+export async function open(url, deps = {status, access:fs.access, mkdir:fs.mkdir, spawn, fetch, pause:ms=>new Promise(r=>setTimeout(r,ms))}) {
+  let current = await deps.status();
+  const started = current.state === 'stopped';
+  if (started) {
+    await deps.access(chrome);
+    await deps.mkdir(profile, { recursive: true, mode: 0o700 });
+    const child = deps.spawn(chrome, ['--remote-debugging-address=127.0.0.1', '--remote-debugging-port=9223', `--user-data-dir=${profile}`, '--no-first-run', '--no-default-browser-check', 'about:blank'], { detached: true, stdio: 'ignore' });
+    await new Promise((resolve, reject) => { child.once('spawn', resolve); child.once('error', reject); });
+    child.unref();
+  }
+  const deadline = Date.now() + 15000;
+  while (!current.ok && Date.now() < deadline) {
+    await deps.pause(300);
+    current = await deps.status();
+  }
+  if (!current.ok) throw fail('NOT_READY', '浏览器尚未就绪；未清理资料、锁文件或终止其他浏览器');
+  if (url) {
+    const response = await deps.fetch(`${cdp}/json/new?${encodeURIComponent(url)}`, { method: 'PUT', signal: AbortSignal.timeout(3000), redirect: 'error' });
+    if (!response.ok) throw fail('TAB_OPEN_FAILED', `浏览器已就绪，打开页面失败 HTTP ${response.status}`);
+  }
+  return { ...current, started };
+}
+

package/lib/browser-session.mjs

@@ -0,0 +1,32 @@
+import {open as start, status as processStatus} from './browser-process.mjs';
+import {rpc} from './desktop.mjs';
+export const browserEndpoint='http://127.0.0.1:9223';
+const home='https://boardmix.cn/app/';
+const pause=ms=>new Promise(r=>setTimeout(r,ms));
+export function classifyAuth({url,text,hasUserAvatar=false}) {
+ const u=new URL(url); if(u.origin!=='https://boardmix.cn')return 'unknown';
+ if(/(?:^|\/)(?:login|signin)(?:\/|$)/i.test(u.pathname)||/扫码登录|验证码登录|密码登录|微信登录|登录\s*[/／]\s*注册/.test(text))return 'login_required';
+ if((/^\/app\/team\//.test(u.pathname)||u.pathname==='/app/recent-file'&&hasUserAvatar)&&['最近打开','我的收藏','全部项目'].every(x=>text.includes(x)))return 'ready';
+ return 'unknown';
+}
+async function list(){const r=await fetch(browserEndpoint+'/json/list',{signal:AbortSignal.timeout(2000),redirect:'error'});if(!r.ok)throw Error('BROWSER_UNAVAILABLE');return r.json();}
+async function read(t){const c=await rpc(browserEndpoint,t);try{const r=await c.send('Runtime.evaluate',{expression:'({url:location.href,text:document.body?.innerText||"",hasUserAvatar:!!document.querySelector("nav .ed-avatar--container")})',returnByValue:true});if(r.exceptionDetails)throw Error('AUTH_PROBE_FAILED');return r.result.value;}finally{c.close();}}
+function candidate(t){try{const u=new URL(t.url);return t.type==='page'&&u.origin==='https://boardmix.cn'&&!u.pathname.startsWith('/app/editor/');}catch{return false;}}
+export async function authStatus(deps={list,read,processStatus}) {
+ const browser=await deps.processStatus();if(!browser.ok)return {ok:false,state:'browser_unavailable',browser};
+ const pages=(await deps.list()).filter(candidate); let login=null;
+ for(const t of pages){const state=classifyAuth(await deps.read(t));if(state==='ready')return {ok:true,state,endpoint:browserEndpoint,tabId:t.id,url:t.url};if(state==='login_required')login=t;}
+ return {ok:false,state:login?'login_required':'unknown',code:login?'AUTH_REQUIRED':'AUTH_STATE_UNKNOWN',endpoint:browserEndpoint,tabId:login?.id,url:login?.url||home,prompt:login?'请在已打开的 Chrome Boardmix 页面完成登录，然后继续检测。':'Boardmix 登录状态尚未确认，请等待页面加载或检查页面。',resume:'boardmixcli browser.ensure --wait-ms 60000'};
+}
+async function enterLogin(result){
+ const t=(await list()).find(t=>t.id===result.tabId);if(!t)return;
+ const c=await rpc(browserEndpoint,t);try{await c.send('Page.bringToFront');await c.send('Runtime.evaluate',{expression:`(()=>{const b=[...document.querySelectorAll('button.loginEntry--btn')].find(e=>/登录\\s*[/／]\\s*注册/.test(e.textContent));if(b)b.click();})()`});}finally{c.close();}
+}
+export async function ensureBrowser({waitMs=15000}={},deps={start,list,authStatus,pause,enterLogin}) {
+ if(!Number.isInteger(waitMs)||waitMs<0||waitMs>60000)throw Error('INVALID_WAIT_MS');
+ const browser=await deps.start();
+ if(!(await deps.list()).some(candidate))await deps.start(home);
+ const deadline=Date.now()+waitMs;let result,loginOpened=false;
+ do{result=await deps.authStatus();if(result.state==='login_required'&&!loginOpened){await deps.enterLogin?.(result);loginOpened=true;}if(result.ok||result.state==='login_required'&&waitMs<=15000)break;if(Date.now()>=deadline)break;await deps.pause(500);}while(true);
+ return {...result,browserStarted:browser.started,profile:browser.profile};
+}

package/lib/client.mjs

@@ -0,0 +1,11 @@
+import {readFile} from 'node:fs/promises';
+export async function connect(sessionPath){
+  if(!sessionPath)throw Error('SESSION_PATH_REQUIRED');
+  const {endpoint,token}=JSON.parse(await readFile(sessionPath,'utf8'));
+  if(!/^http:\/\/127\.0\.0\.1:\d+$/.test(endpoint)||typeof token!=='string')throw Error('INVALID_SESSION');
+  async function call(route,data){
+    const r=await fetch(endpoint+route,{method:data?'POST':'GET',headers:{Authorization:'Bearer '+token,'Content-Type':'application/json'},body:data?JSON.stringify(data):undefined,signal:AbortSignal.timeout(190000)});
+    const result=await r.json();if(!r.ok||result.ok===false){const e=Error(result.error||'REQUEST_FAILED');e.details=result;throw e;}return result;
+  }
+  return {endpoint,call,request:(op,fileKey,params={})=>call('/request',{op,fileKey,params})};
+}

package/lib/commands.mjs

@@ -0,0 +1,50 @@
+import {inspectVideo,downloadVideo,importVideo} from './video.mjs';
+import {readFile} from 'node:fs/promises';
+import {inspectBatch,importBatch} from './batch.mjs';
+import {parse} from './maintenance.mjs';
+import {connect} from './client.mjs';
+import {downloadImage} from './image-codecs.mjs';
+import {inspectImage,listImages} from './assets.mjs';
+export async function atomicCommand(command,args){
+  const extras={
+   'video.inspect':['--file'],'video.download':['--url','--output'],'video.import':['--file','--receipt'],
+   'image.inspect.batch':['--input'],'image.import.batch':['--input','--receipt'],'object.get.batch':['--input'],'object.place.batch':['--input'],
+   'image.download':['--url','--output'],'frame.create':['--x','--y','--width','--height','--name'],'text.create':['--x','--y','--width','--height','--text','--font-size'],'image.list':['--directory'],'image.inspect':['--file'],'image.import':['--file'],
+   'board.create':['--team-id','--project-id','--folder-id'],'board.rename':['--name'],
+   'board.open':['--target-file-key'],'object.get':['--session-id','--local-id'],
+   'object.move':['--session-id','--local-id','--x','--y'],
+   'object.resize':['--session-id','--local-id','--width','--height'],'view.fit':['--ids']
+  };
+  const flags=[...(['video.inspect','video.download','image.list','image.inspect','image.download','image.inspect.batch'].includes(command)?[]:['--session','--file-key']),...(extras[command]||[])];
+  parse(args,Object.fromEntries(flags.map(k=>[k,'string'])));
+  function option(name,required=true){const i=args.indexOf(name);const v=i<0?undefined:args[i+1];if(required&&(!v||v.startsWith('--')))throw Error(name+'_REQUIRED');return v;}
+  function number(name){const v=Number(option(name));if(!Number.isFinite(v))throw Error('INVALID_'+name);return v;}
+  if(command==='image.inspect.batch')return inspectBatch(JSON.parse(await readFile(option('--input'),'utf8')));
+  if(command==='video.inspect')return inspectVideo(option('--file'));
+  if(command==='video.download')return downloadVideo(option('--url'),option('--output'));
+  if(command==='image.list')return {images:await listImages(option('--directory'))};
+  if(command==='image.inspect')return inspectImage(option('--file'));
+  if(command==='image.download'){const r=await downloadImage(option('--url'),option('--output'));return {...await inspectImage(r.file),sourceUrl:r.sourceUrl};}
+  const client=await connect(option('--session')),fileKey=option('--file-key');
+  if(command==='video.import')return importVideo(client,fileKey,option('--file'),option('--receipt'));
+  if(command==='image.import.batch')return importBatch(client,fileKey,JSON.parse(await readFile(option('--input'),'utf8')),option('--receipt'));
+  if(command==='object.get.batch')return client.request(command,fileKey,{guids:JSON.parse(await readFile(option('--input'),'utf8'))});
+  if(command==='object.place.batch')return client.request(command,fileKey,{items:JSON.parse(await readFile(option('--input'),'utf8'))});
+  if(['frame.create','text.create'].includes(command))return client.request(command,fileKey,{x:number('--x'),y:number('--y'),width:number('--width'),height:number('--height'),content:option(command==='frame.create'?'--name':'--text'),...(command==='text.create'?{fontSize:Number(option('--font-size',false)||28)}:{})});
+  if(command==='board.info')return client.request(command,fileKey);
+  if(command==='board.create')return client.request(command,fileKey,{teamId:number('--team-id'),projectId:number('--project-id'),folderId:Number(option('--folder-id',false)||0)});
+  if(command==='board.rename')return client.request(command,fileKey,{name:option('--name')});
+  if(command==='board.open')return client.request(command,fileKey,{targetFileKey:option('--target-file-key')});
+  if(command==='board.close')return client.request(command,fileKey);
+  if(command==='object.selection')return client.request(command,fileKey);
+  if(command==='object.get')return client.request(command,fileKey,{sessionID:number('--session-id'),localID:number('--local-id')});
+  if(command==='object.move')return client.request(command,fileKey,{sessionID:number('--session-id'),localID:number('--local-id'),x:number('--x'),y:number('--y')});
+  if(command==='object.resize')return client.request(command,fileKey,{sessionID:number('--session-id'),localID:number('--local-id'),width:number('--width'),height:number('--height')});
+  if(command==='view.fit')return client.request(command,fileKey,{guids:JSON.parse(option('--ids'))});
+  if(command==='image.import'){
+    const asset=await inspectImage(option('--file'));
+    const registered=await client.call('/register-asset',{file:asset.file,sha256:asset.sha256});
+    return client.request(command,fileKey,{assetId:registered.assetId});
+  }
+  throw Error('UNKNOWN_COMMAND');
+}

package/lib/desktop.mjs

@@ -0,0 +1,59 @@
+import {connect} from './client.mjs';
+const pause=ms=>new Promise(r=>setTimeout(r,ms));
+export const defaultEndpoint='http://127.0.0.1:19427';
+export function endpoint(value=defaultEndpoint){
+ if(!/^http:\/\/127\.0\.0\.1:\d+$/.test(value))throw Error('LOOPBACK_ENDPOINT_REQUIRED');
+ const port=Number(new URL(value).port);if(port<1024||port>65535)throw Error('INVALID_DEBUG_PORT');return value;
+}
+export function editorKey(url){try{const u=new URL(url);return u.origin==='https://boardmix.cn'&&/^\/app\/editor\/[A-Za-z0-9_-]{8,128}$/.test(u.pathname)?u.pathname.split('/').pop():null;}catch{return null;}}
+function boardmixTarget(t){try{const u=new URL(t.url);return t.type==='page'&&(u.origin==='https://boardmix.cn'&&u.pathname.startsWith('/app/')||u.protocol==='file:'&&u.pathname.endsWith('/boardmix.app/Contents/Resources/app.asar/packages/renderer/dist/index.html'));}catch{return false;}}
+export async function targets(base=defaultEndpoint){
+ endpoint(base);let r;try{r=await fetch(base+'/json/list',{signal:AbortSignal.timeout(2000),redirect:'error'});}catch{throw Error('DESKTOP_CONNECTION_UNAVAILABLE');}
+ if(!r.ok)throw Error('DESKTOP_CONNECTION_UNAVAILABLE');const list=await r.json();if(!Array.isArray(list))throw Error('INVALID_DESKTOP_RESPONSE');
+ return list.filter(boardmixTarget).map(t=>({id:t.id,title:t.title,url:t.url,fileKey:editorKey(t.url),webSocketDebuggerUrl:t.webSocketDebuggerUrl}));
+}
+export async function rpc(base,target){
+ const u=new URL(target.webSocketDebuggerUrl),b=new URL(endpoint(base));
+ if(u.protocol!=='ws:'||u.hostname!=='127.0.0.1'||u.port!==b.port||!u.pathname.startsWith('/devtools/page/')||u.username||u.password)throw Error('UNTRUSTED_DEBUG_TARGET');
+ const ws=new WebSocket(u),pending=new Map();let serial=0;
+ await new Promise((resolve,reject)=>{const t=setTimeout(()=>{ws.close();reject(Error('DESKTOP_CONNECT_TIMEOUT'));},3000);ws.addEventListener('open',()=>{clearTimeout(t);resolve();},{once:true});ws.addEventListener('error',()=>{clearTimeout(t);reject(Error('DESKTOP_CONNECT_FAILED'));},{once:true});});
+ ws.addEventListener('message',e=>{let m;try{m=JSON.parse(e.data);}catch{return;}const p=pending.get(m.id);if(!p)return;pending.delete(m.id);clearTimeout(p.timer);m.error?p.reject(Error('CDP_REQUEST_FAILED')):p.resolve(m.result);});
+ ws.addEventListener('close',()=>{for(const p of pending.values()){clearTimeout(p.timer);p.reject(Error('DESKTOP_DISCONNECTED'));}pending.clear();});
+ return {close:()=>ws.close(),send(method,params={}){return new Promise((resolve,reject)=>{const id=++serial,timer=setTimeout(()=>{pending.delete(id);reject(Error('DESKTOP_REQUEST_TIMEOUT'));},20000);pending.set(id,{resolve,reject,timer});ws.send(JSON.stringify({id,method,params}));});}};
+}
+async function evaluate(c,expression){const r=await c.send('Runtime.evaluate',{expression,awaitPromise:true,returnByValue:true});if(r.exceptionDetails)throw Error('DESKTOP_ADAPTER_FAILED');return r.result?.value;}
+function validKey(k){if(typeof k!=='string'||!/^[A-Za-z0-9_-]{8,128}$/.test(k))throw Error('FILE_KEY_REQUIRED');}
+export async function attachDesktop({session,fileKey,base=defaultEndpoint,browser=false},deps={targets,rpc}){
+ validKey(fileKey);endpoint(base);const client=await connect(session),status=await client.call('/status');
+ const found=(await deps.targets(base)).filter(t=>t.fileKey===fileKey);
+ if(found.length!==1)throw Error(found.length?'AMBIGUOUS_EDITOR':'EDITOR_NOT_OPEN');
+ if(status.pending)throw Error('BRIDGE_BUSY');
+ const c=await deps.rpc(base,found[0]);try{
+  const identity=await evaluate(c,'({url:location.href,desktop:window.desktopManagerApi?.version,bridge:window.__boardmixcliPageBridge?.endpoint,active:window.__boardmixcliPageBridge?.active})');
+  if(editorKey(identity?.url)!==fileKey||!browser&&identity.desktop!=='1.0.0')throw Error('DESKTOP_IDENTITY_MISMATCH');
+  if(identity.active&&identity.bridge===client.endpoint&&status.clients?.some(c=>c.fileKey===fileKey&&c.connected))return {connected:true,fileKey,reused:true,visibleDevTools:false};
+  const readyUntil=Date.now()+10000;let ready=false;
+  while(Date.now()<readyUntil){if(await evaluate(c,"Array.from(document.scripts).some(s=>s.src.includes('/assets/index-')&&s.src.endsWith('.js'))")){ready=true;break;}await pause(200);}
+  if(!ready)throw Error('EDITOR_LOADING');
+  const {script}=await client.call('/bootstrap');const result=await evaluate(c,script);
+  if(!result?.connected||result.fileKey!==fileKey)throw Error('ATTACH_READBACK_MISMATCH');
+  const deadline=Date.now()+5000;
+  while(Date.now()<deadline){const s=await client.call('/status');if(s.clients?.some(x=>x.fileKey===fileKey&&x.connected))return {connected:true,fileKey,reused:false,visibleDevTools:false};await pause(100);}
+  throw Error('ATTACH_NOT_CONFIRMED');
+ }finally{c.close();}
+}
+export async function closeBrowser({session,fileKey,base}){
+ validKey(fileKey);endpoint(base);const found=(await targets(base)).filter(t=>t.fileKey===fileKey);if(found.length!==1)throw Error(found.length?'AMBIGUOUS_EDITOR':'EDITOR_NOT_OPEN');
+ const client=await connect(session),{result:info}=await client.request('board.info',fileKey);
+ if(info.fileKey!==fileKey||info.uploading||info.localSavePending||info.coopStatus!==1)throw Error('SAVE_OR_UPLOAD_PENDING');
+ const c=await rpc(base,found[0]);try{await evaluate(c,'window.__boardmixcliPageBridge?.stop()');const result=await c.send('Target.closeTarget',{targetId:found[0].id});if(!result.success)throw Error('BROWSER_CLOSE_FAILED');}finally{c.close();}
+ const deadline=Date.now()+5000;while(Date.now()<deadline){if(!(await targets(base)).some(t=>t.id===found[0].id))return {closed:true,fileKey};await pause(100);}throw Error('BROWSER_CLOSE_PENDING');
+}
+export async function openDesktop({fileKey,base=defaultEndpoint,browser=false}){
+ validKey(fileKey);const list=await targets(base),existing=list.filter(t=>t.fileKey===fileKey);
+ if(existing.length>1)throw Error('AMBIGUOUS_EDITOR');if(existing.length===1)return {opened:true,fileKey,reused:true};
+ const host=list.find(t=>t.url.startsWith('https://boardmix.cn/app/'));
+ if(!host)throw Error('BOARDMIX_HOME_REQUIRED');const c=await rpc(base,host);
+ try{if(browser)await c.send('Target.createTarget',{url:'https://boardmix.cn/app/editor/'+fileKey,background:false});else{const ok=await evaluate(c,`(()=>{if(window.desktopManagerApi?.version!=='1.0.0')return false;window.desktopManagerApi.openFile(${JSON.stringify(fileKey)});return true;})()`);if(!ok)throw Error('DESKTOP_IDENTITY_MISMATCH');}}finally{c.close();}
+ const deadline=Date.now()+15000;while(Date.now()<deadline){if((await targets(base)).some(t=>t.fileKey===fileKey))return {opened:true,fileKey,reused:false};await pause(250);}throw Error('EDITOR_OPEN_PENDING');
+}

package/lib/image-codecs.mjs

@@ -0,0 +1,23 @@
+import {lstat,writeFile} from 'node:fs/promises';
+import path from 'node:path';
+export function imageMetadata(b){
+ if(b.length>=24&&b.subarray(0,8).toString('hex')==='89504e470d0a1a0a')return {mime:'image/png',width:b.readUInt32BE(16),height:b.readUInt32BE(20)};
+ if(b.length>4&&b[0]===255&&b[1]===216){
+  let i=2;while(i+4<=b.length){if(b[i++]!==255)throw Error('INVALID_JPEG');while(b[i]===255)i++;const marker=b[i++];if(marker===217||marker===218)break;if(marker===1||marker>=208&&marker<=215)continue;const len=b.readUInt16BE(i);if(len<2||i+len>b.length)throw Error('INVALID_JPEG');if([192,193,194,195,197,198,199,201,202,203,205,206,207].includes(marker)){if(len<7)throw Error('INVALID_JPEG');return {mime:'image/jpeg',height:b.readUInt16BE(i+3),width:b.readUInt16BE(i+5)};}i+=len;}
+ }
+ if(b.length>=30&&b.toString('ascii',0,4)==='RIFF'&&b.toString('ascii',8,12)==='WEBP'){
+  const kind=b.toString('ascii',12,16);
+  if(kind==='VP8X')return {mime:'image/webp',width:1+b.readUIntLE(24,3),height:1+b.readUIntLE(27,3)};
+  if(kind==='VP8 '&&b.subarray(23,26).toString('hex')==='9d012a')return {mime:'image/webp',width:b.readUInt16LE(26)&16383,height:b.readUInt16LE(28)&16383};
+  if(kind==='VP8L'&&b[20]===47){const v=b.readUInt32LE(21);return {mime:'image/webp',width:(v&16383)+1,height:((v>>>14)&16383)+1};}
+ }
+ throw Error('UNSUPPORTED_IMAGE_FORMAT_PNG_REQUIRED_OR_JPEG_WEBP');
+}
+export async function downloadImage(url,output){
+ const u=new URL(url);if(!['https:','http:'].includes(u.protocol)||u.username||u.password)throw Error('INVALID_IMAGE_URL');
+ const target=path.resolve(output);try{await lstat(target);throw Error('TARGET_EXISTS');}catch(e){if(e.code!=='ENOENT')throw e;}
+ const r=await fetch(u,{signal:AbortSignal.timeout(30000)});if(!r.ok)throw Error('IMAGE_DOWNLOAD_HTTP_'+r.status);
+ const chunks=[];let size=0;for await(const c of r.body){size+=c.length;if(size>100*1024*1024)throw Error('IMAGE_TOO_LARGE');chunks.push(c);}
+ const data=Buffer.concat(chunks),m=imageMetadata(data);if(!m.width||!m.height)throw Error('INVALID_IMAGE');
+ await writeFile(target,data,{flag:'wx',mode:0o600});return {file:target,sourceUrl:u.href,...m,size};
+}

package/lib/maintenance.mjs

@@ -0,0 +1,170 @@
+import {readFile,writeFile,mkdir,readdir,lstat,cp,rename,rm,mkdtemp,chmod} from 'node:fs/promises';
+import {createHash,randomUUID} from 'node:crypto';
+import {fileURLToPath} from 'node:url';
+import {homedir,tmpdir} from 'node:os';
+import path from 'node:path';
+import {spawn} from 'node:child_process';
+
+export const root=fileURLToPath(new URL('../',import.meta.url));
+export const meta=JSON.parse(await readFile(path.join(root,'package.json'),'utf8'));
+const capabilityManifest=JSON.parse(await readFile(path.join(root,'capabilities.json'),'utf8'));
+const components=['bin','lib','plugin','scripts','package.json','capabilities.json','CONTRACT.md','README.md','INSTALL.md','UPDATE.md','LICENSE'];
+const receiptName='.boardmixcli-receipt.json';
+const fail=(code,details)=>{throw Object.assign(Error(code),{details});};
+const json=async p=>JSON.parse(await readFile(p,'utf8'));
+async function exists(p){try{return await lstat(p);}catch(e){if(e.code==='ENOENT')return null;throw e;}}
+export function parse(args,allowed){
+ const result={};
+ for(let i=0;i<args.length;i++){
+  const k=args[i]; if(!Object.hasOwn(allowed,k)||Object.hasOwn(result,k))fail('INVALID_ARGUMENT',{argument:k});
+  if(allowed[k]==='boolean')result[k]=true;
+  else {const v=args[++i];if(!v||v.startsWith('--'))fail('MISSING_ARGUMENT',{argument:k});result[k]=v;}
+ }return result;
+}
+function targetOf(o){
+ if(!o['--agent']||! /^[a-z][a-z0-9-]{0,63}$/.test(o['--agent']))fail('INVALID_AGENT');
+ if(!o['--destination']||!path.isAbsolute(o['--destination']))fail('DESTINATION_REQUIRED',{recovery:'Resolve the current Agent exact Skill directory and pass --destination absolute-path.'});
+ const t=path.resolve(o['--destination']);
+ const runtimeSelf=path.resolve(root)===path.join(t,'.runtime');
+ if(t===path.parse(t).root||t===homedir()||t===path.resolve(root)||(!runtimeSelf&&root.startsWith(t+path.sep))||t.startsWith(root+path.sep))fail('UNSAFE_DESTINATION');
+ return t;
+}
+async function tree(dir,prefix=''){
+ const out={};
+ for(const e of await readdir(dir,{withFileTypes:true})){
+  const rel=prefix+e.name,p=path.join(dir,e.name);
+  if(e.isSymbolicLink())fail('SYMLINK_UNSUPPORTED',{path:p});
+  if(e.isDirectory())Object.assign(out,await tree(p,rel+'/'));
+  else if(e.isFile())out[rel]=createHash('sha256').update(await readFile(p)).digest('hex');
+ }return out;
+}
+async function expected(){
+ const out=await tree(path.join(root,'skills/boardmixcli'));
+ for(const name of components){
+  const p=path.join(root,name),s=await lstat(p);
+  if(s.isDirectory()){for(const [k,v] of Object.entries(await tree(p)))if(!k.includes('.bak'))out['.runtime/'+name+'/'+k]=v;}
+  else out['.runtime/'+name]=createHash('sha256').update(await readFile(p)).digest('hex');
+ }
+ // The isolated runtime also carries its own canonical Skill for lifecycle commands.
+ for(const [k,v] of Object.entries(await tree(path.join(root,'skills/boardmixcli'))))out['.runtime/skills/boardmixcli/'+k]=v;
+ return out;
+}
+export async function status(o){
+ const target=targetOf(o),s=await exists(target);
+ const base={name:'boardmixcli',package:meta.name,version:meta.version,target,agent:o['--agent'],installed:!!s,managed:false,current:false,edited:[],verification:{verified:false,algorithm:'sha256'},recovery:{action:'skill install with the same explicit target'},hostDiscovery:'pending-host-verification'};
+ if(!s)return base;
+ if(!s.isDirectory()||s.isSymbolicLink())fail('UNMANAGED_TARGET',{target});
+ const r=await json(path.join(target,receiptName)).catch(()=>null);
+ if(!r||r.package!==meta.name||r.agent!==o['--agent']||!r.hashes||r.target!==target)return base;
+ base.managed=true;const actual=await tree(target);delete actual[receiptName];
+ const wanted=await expected();
+ // UI metadata is host-owned after first installation; preserve it across reconciliation.
+ const hostOwned=k=>k.startsWith('agents/');
+ base.edited=Object.keys(actual).filter(k=>!hostOwned(k)&&(!r.hashes[k]||actual[k]!==r.hashes[k]));
+ const exact=Object.entries(wanted).every(([k,h])=>hostOwned(k)||actual[k]===h);
+ base.current=r.version===meta.version&&exact&&base.edited.length===0;
+ base.verification={verified:base.current,algorithm:'sha256',installedVersion:r.version};
+ base.recovery={action:base.edited.length?'Preserve local edits and resolve ownership before updating.':base.current?'none':'skill update with this explicit target'};
+ return base;
+}
+export async function install(o,{renameTarget=rename}={}){
+ const target=targetOf(o),prior=await status(o);
+ if(prior.installed&&!prior.managed)fail('UNMANAGED_TARGET',{target});
+ if(prior.edited.length)fail('EDITED_TARGET',{target,edited:prior.edited});
+ if(prior.current)return {...prior,changed:false};
+ await mkdir(path.dirname(target),{recursive:true});
+ const stage=await mkdtemp(path.join(path.dirname(target),'.boardmixcli-stage-'));
+ let backup;
+ try{
+  for(const e of await readdir(path.join(root,'skills/boardmixcli')))await cp(path.join(root,'skills/boardmixcli',e),path.join(stage,e),{recursive:true,errorOnExist:true,force:false});
+  const runtime=path.join(stage,'.runtime');await mkdir(runtime);
+  for(const name of components)await cp(path.join(root,name),path.join(runtime,name),{recursive:true,filter:p=>!p.includes('.bak'),force:false,errorOnExist:true});
+  await cp(path.join(root,'skills/boardmixcli'),path.join(runtime,'skills/boardmixcli'),{recursive:true});
+  if(prior.installed&&await exists(path.join(target,'agents'))){await rm(path.join(stage,'agents'),{recursive:true,force:true});await cp(path.join(target,'agents'),path.join(stage,'agents'),{recursive:true});}
+  const hashes=await tree(stage);
+  await writeFile(path.join(stage,receiptName),JSON.stringify({package:meta.name,version:meta.version,agent:o['--agent'],target,hashes,sourceVersion:meta.version},null,2)+'\n',{flag:'wx',mode:0o600});
+  let inPlace=false;
+  if(prior.installed){
+   backup=target+'.backup-'+randomUUID();
+   try{await renameTarget(target,backup);}
+   catch(e){
+    if(!['EBUSY','EPERM','EACCES'].includes(e.code))throw e;
+    await cp(target,backup,{recursive:true,force:false,errorOnExist:true});
+    inPlace=true;
+   }
+  }
+  if(inPlace){
+   // Locked-directory update: snapshot first, copy complete resources, commit receipt last.
+   try{
+    for(const e of await readdir(stage))if(e!==receiptName)await cp(path.join(stage,e),path.join(target,e),{recursive:true,force:true});
+    await cp(path.join(stage,receiptName),path.join(target,receiptName),{force:true});
+   }catch(e){fail('SKILL_SYNC_FAILED',{target,backup,phase:'in-place-sync',recovery:'Restore the complete preserved backup after releasing host file locks.'});}
+  }else try{await rename(stage,target);}catch(e){if(backup)await rename(backup,target);throw e;}
+  const result=await status(o);if(!result.current)fail('INSTALL_VERIFICATION_FAILED',{target,backup});
+  return {...result,changed:true,...backup?{backup}:{}};
+ }finally{await rm(stage,{recursive:true,force:true});}
+}
+const newerVersion=(candidate,current)=>{const a=candidate.match(/^([0-9]+)\.([0-9]+)\.([0-9]+)$/),b=current.match(/^([0-9]+)\.([0-9]+)\.([0-9]+)/);if(!a||!b)return false;for(let i=1;i<4;i++){if(Number(a[i])!==Number(b[i]))return Number(a[i])>Number(b[i]);}return false;};
+const cacheDir=()=>process.env.BOARDMIXCLI_CACHE_DIR||path.join(homedir(),'.cache','boardmixcli');
+export async function checkUpdate({automatic=false}={}){
+ if(process.env.BOARDMIXCLI_UPDATE_CHECK==='0')return {enabled:false};
+ const p=path.join(cacheDir(),'update.json');
+ const cached=await json(p).catch(()=>null);
+ if(automatic&&cached&&Date.now()-cached.checkedAt<24*3600e3)return {...cached,cached:true};
+ let result;
+ try{
+  const r=await fetch('https://registry.npmjs.org/@petercjl%2fboardmixcli/latest',{signal:AbortSignal.timeout(automatic?1200:10000)});
+  if(!r.ok)throw Error('REGISTRY_'+r.status);
+  const published=await r.json();result={checkedAt:Date.now(),version:meta.version,latest:published.version,available:newerVersion(published.version,meta.version)};
+ }catch(e){result={checkedAt:Date.now(),version:meta.version,available:false,error:e.message,recovery:'Retry update check after network recovery.'};}
+ try{
+  await mkdir(cacheDir(),{recursive:true});
+  const prior=await exists(p);
+  if(!prior)await writeFile(p,JSON.stringify({...result,owner:meta.name}),{flag:'wx',mode:0o600});
+  else if(!prior.isSymbolicLink()&&cached?.owner===meta.name){
+   const next=p+'.'+randomUUID();await writeFile(next,JSON.stringify({...result,owner:meta.name}),{flag:'wx',mode:0o600});await rename(next,p);
+  }
+ }catch{}
+ if(automatic&&result.available)process.stderr.write(`boardmixcli: ${result.latest} available; ask your Agent to update CLI and its selected Skill.\n`);
+ return result;
+}
+async function run(cmd,args){return new Promise((resolve,reject)=>{const c=spawn(cmd,args,{stdio:['ignore','pipe','pipe'],shell:false});let out='',err='';c.stdout.on('data',x=>out+=x);c.stderr.on('data',x=>err+=x);c.on('error',reject);c.on('exit',code=>code===0?resolve(out):reject(Object.assign(Error('UPDATE_COMMAND_FAILED'),{details:{phase:'candidate-install',code,stderr:err.slice(-2000)}})));});}
+export async function updateInstall(o){
+ const before=await status(o);if(before.installed&&(!before.managed||before.edited.length))fail('TARGET_PROTECTED',before);
+ if(!o['--yes'])fail('CONFIRMATION_REQUIRED');
+ // Stage into a private managed prefix. Replace neither the npm package nor selected Skill on a download failure.
+ const latest=await checkUpdate();if(latest.error||!latest.latest)fail('UPDATE_CHECK_FAILED',latest);
+ if(latest.latest!==meta.version&&!newerVersion(latest.latest,meta.version))return {...await install(o),packageChanged:false,installedAhead:true,registryVersion:latest.latest};
+ const stage=await mkdtemp(path.join(tmpdir(),'boardmixcli-update-'));
+ const npmCli=process.env.npm_execpath||path.join(path.dirname(process.execPath),'node_modules/npm/bin/npm-cli.js');
+ try{
+  if(!/^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/.test(latest.latest))fail('INVALID_REGISTRY_VERSION');
+  const npmArgs=['install','--prefix',stage,'--ignore-scripts','--no-audit','--no-fund',meta.name+'@'+latest.latest];
+  if(process.platform==='win32'){
+   if(!await exists(npmCli))fail('NPM_RUNTIME_UNAVAILABLE',{recovery:'Use npm-managed execution or configure npm_execpath to npm-cli.js.'});
+   await run(process.execPath,[npmCli,...npmArgs]);
+  }else await run('npm',npmArgs);
+  const candidate=path.join(stage,'node_modules/@petercjl/boardmixcli/bin/boardmixcli.mjs');
+  const result=JSON.parse(await run(process.execPath,[candidate,'skill','update','--agent',o['--agent'],'--destination',o['--destination'],'--json']));
+  if(!result.current)fail('SKILL_SYNC_FAILED',result);
+  return {...result,entry:path.join(o['--destination'],'.runtime/bin/boardmixcli.mjs'),packageChanged:meta.version!==latest.latest,recovery:{action:'Use the selected Skill target-owned entry; refresh host discovery.'}};
+ }finally{await rm(stage,{recursive:true,force:true});}
+}
+export async function maintenance(command,args){
+ if(command==='doctor'){
+  parse(args,{'--json':'boolean'});
+  return {ok:Number(process.versions.node.split('.')[0])>=22,package:meta.name,version:meta.version,node:process.version,platform:process.platform,adapterBuild:'index-DjSD2oPg.js',service:{connected:false,required:'Run browser.ensure for managed Chrome startup and login, then browser.connect; inspect status --session FILE.'},skill:{source:path.join(root,'skills/boardmixcli'),registration:'host-owned'}};
+ }
+ const action=args.shift();
+ if(command==='skill'){
+  if(action==='source'){parse(args,{'--json':'boolean'});return {name:'boardmixcli',package:meta.name,version:meta.version,source:path.join(root,'skills/boardmixcli'),maintenanceContract:capabilityManifest.maintenanceContract,commandContracts:capabilityManifest.commandContracts};}
+  if(!['status','install','update'].includes(action))fail('UNKNOWN_COMMAND');
+  if(args.includes('--help')){parse(args,{'--help':'boolean','--json':'boolean'});return {command:'skill '+action,...capabilityManifest.commandContracts['skill '+action]};}
+  const o=parse(args,{'--agent':'string','--destination':'string','--json':'boolean'});
+  return action==='status'?status(o):install(o);
+ }
+ if(command==='update'){
+  if(action==='check'){parse(args,{'--json':'boolean'});return checkUpdate();}
+  if(action==='install')return updateInstall(parse(args,{'--agent':'string','--destination':'string','--yes':'boolean','--json':'boolean'}));
+ }fail('UNKNOWN_COMMAND');
+}