@petercjl/boardmixcli 0.0.0-bootstrap.0 → 0.1.0

package/CONTRACT.md

@@ -0,0 +1,37 @@
+# Capability contract
+
+The CLI executes explicit operations. The calling Agent or application Skill owns content, file choice, sorting, coordinates, layout and acceptance decisions. The desktop/web adapter owns provider integration and translates native coordinate and ratio-lock behavior.
+
+## Commands
+
+Every connected command requires `--session PATH --file-key KEY`. `KEY` is the connected source context; a new target must be opened and attached before operating on it. Results are JSON. Failed commands exit nonzero. Successful native mutations include readback when available.
+
+| Command | Additional input | Result / side effect |
+| --- | --- | --- |
+| `board.info` | none | File name, team/project/folder, upload and connection status |
+| `board.create` | `--team-id N --project-id N [--folder-id N]` | Creates one unnamed file; returns its key; opens separately |
+| `board.rename` | `--name TEXT` | Changes name and reads it back from the service |
+| `board.open` | `--target-file-key KEY` | Requests a desktop tab; attachment and UI verification follow |
+| `board.close` | none | Rejects pending uploads, pending local save or disconnected cloud sync; returns close request receipt |
+| `image.list` | `--directory PATH` only | PNG metadata inventory in natural filename order; no connection needed |
+| `image.inspect` | `--file PATH` only | PNG dimensions, size and SHA-256; no connection needed |
+| `image.import` | `--file PATH` | Imports one PNG through the application uploader; returns asset digest, resource hash, new GUID and actual geometry |
+| `object.selection` | none | Returns currently selected objects; no selection change |
+| `object.get` | `--session-id N --local-id N` | Reads one object |
+| `object.move` | GUID plus `--x N --y N` | Absolute **top-left board coordinates**; translates native center-point API and verifies |
+| `object.resize` | GUID plus `--width N --height N` | Exact target size; temporarily releases ratio lock, restores it and verifies |
+| `view.fit` | `--ids JSON_GUID_ARRAY` | Fits only explicit GUIDs into the viewport |
+
+Image import preserves source bytes. Boardmix may choose a smaller initial display size; explicit resizing is a separate caller decision. Resizing does not resample or replace the uploaded source image.
+
+## Transport and recovery
+
+`serve --session NEW_PATH` creates a loopback service, private session token and console bootstrap script. Bootstrap attachment is currently performed once per opened view by an Agent. Close the developer-tools window after attachment before executing operations. On desktop 1.7.2 an open developer-tools window prevented the native close request from removing the tab in one test; repeating with developer tools closed removed the tab and passed UI verification. The source file path never goes to Boardmix: only the selected file bytes and base name enter the application's normal uploader. The local service exposes only explicitly registered image digests under authenticated routes.
+
+Each request targets one file key, carries a correlation ID and is dispatched once. The bridge routes to the matching attached view. Do not automatically retry file creation or image import after timeout. Inspect the canvas and request outcome first. In-memory outcomes are available at authenticated `/outcome/ID`; durable operation receipts are the caller's responsibility in this prototype.
+
+The browser adapter currently validates the observed `index-DjSD2oPg.js` build. An unverified build fails explicitly. Readback error is a mutation outcome requiring inspection, not proof that no change happened. `board.close` acknowledges a close request; the calling Agent verifies that the tab actually disappeared. Cloud-save persistence is verified by reopening and reading objects, independently of the close receipt. Native `view.fit` animates asynchronously; its immediate viewport snapshot can precede the final settled view. The calling Agent confirms the displayed fit independently.
+
+## Distribution status
+
+Local development prototype. No publication or managed CLI/Skill installation is claimed. Any Agent with Node.js, filesystem access and an authorized Boardmix connection can call the CLI. This machine's macOS desktop runtime has been exercised; other systems remain unverified. Application-layer Skills will be authored separately.

package/INSTALL.md

@@ -0,0 +1,11 @@
+# Install for the current Agent
+
+Send to your current Agent:
+
+> 安装 @petercjl/boardmixcli，并验证当前 Agent 的配套 Skill 可用。
+
+Agent execution contract: install the npm CLI, inspect `boardmixcli capabilities --json` and `boardmixcli skill source --json`, resolve your own advertised/configured Skill discovery directory, and pass the exact new Skill directory to `boardmixcli skill install --agent YOUR-VALID-AGENT-NAME --destination ABSOLUTE-SKILL-DIRECTORY --json`. Any valid Agent name uses the generic adapter. A missing destination stops before mutation. Unmanaged targets and local edits are protected. This step copies all resources and an isolated `.runtime` into the selected target. Installation does not access Boardmix or modify another Agent.
+
+Verify `skill status` using the same target and Agent: installed, managed, current and verification.verified must be true. Execute the target-owned `.runtime/bin/boardmixcli.mjs` with Node.js and verify its version. Load SKILL.md through your host's native registration/discovery mechanism; refresh the host session when necessary. The CLI reports host discovery pending because it cannot verify the host catalog. Report completion only when the host actually discovers/loads the Skill. Otherwise report the pending phase and recovery action.
+
+With npm scripts disabled, follow this identical handoff explicitly; the postinstall notice is guidance, not configuration. If npm succeeds but Skill sync fails, keep the installed CLI, resolve ownership/destination and retry `skill install/update`. Credentials remain in the already logged-in Boardmix application. Node.js >=22 and authorized per-editor developer-console access are external prerequisites. Desktop automation is tested on macOS Boardmix 1.7.2; other desktop platforms are unverified.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 petercjl
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,28 @@
-# BoardmixCLI bootstrap
+# BoardmixCLI
 
-Minimal placeholder to establish npm Trusted Publishing. The substantive CLI release is published separately by GitHub Actions.
+Boardmix 桌面画板的元命令能力包。提供文件新建、命名、打开和关闭，PNG 导入、图元读取、精确尺寸与位置调整，返回 JSON 结果。当前 Agent 负责材料选择、顺序、布局与业务验收。
+
+> 安装 @petercjl/boardmixcli，并验证当前 Agent 的配套 Skill 可用。
+
+> 更新 @petercjl/boardmixcli，并验证当前 Agent 的配套 Skill 已同步。
+
+> 使用 boardmixcli 新建一个画板，命名为“图片整理”，将我提供的 PNG 图片按指定顺序纵向无间隙排列，保存后退出画板。
+
+安装与更新的完整 Agent 交接见 [INSTALL.md](INSTALL.md)、[UPDATE.md](UPDATE.md)。npm 安装后还需同步当前 Agent 的配套 Skill；包管理入口提供物理隔离的资源与运行时，并由当前 Agent 确认宿主发现状态。适用于具备 Node.js、文件访问、本地 HTTP 和授权桌面控制能力的 Agent。
+
+## 开发者参考
+
+需要 Node.js >=22、已登录的 Boardmix，以及每个打开画板的 Console 连接。连接使用随机 loopback 端口和临时令牌；安装不授予服务访问权限。此包为独立开发的实验性工具，使用官方插件图元能力和版本锁定的内部桌面适配器。macOS Boardmix 1.7.2 / 前端 `index-DjSD2oPg.js` 已验证；其他桌面平台尚未验证，前端更新可能需要适配。
+
+运行 `boardmixcli capabilities --json`、`boardmixcli doctor --json` 发现合同；`boardmixcli skill source --json` 定位配套手册。参数、坐标、错误与恢复详见 [CONTRACT.md](CONTRACT.md)。业务状态保留在 Boardmix，会话和本地材料留在调用者本机。
+
+```sh
+boardmixcli serve --session /absolute/new-session.json
+boardmixcli board.info --session /absolute/new-session.json --file-key EXPLICIT_BOARD_KEY
+```
+
+`serve` 创建新的私有会话文件与 `.bootstrap.js`。在目标编辑器 Console 中执行启动脚本，然后关闭开发者工具；每个新打开的画板需要单独连接。会话文件包含临时令牌，勿公开。CLI 使用 App 现有登录态，不读取或导出登录凭证。
+
+可用操作：`board.info/create/rename/open/close`、`image.list/inspect/import`、`object.selection/get/move/resize`、`view.fit`。图元移动使用绝对左上角画板坐标；尺寸调整保留宽高比锁定状态。创建和导入超时后先核查结果再决定后续动作。
+
+运行 `npm test` 与 `npm run check` 检查包、命令与安装生命周期。真实画板证据、私人会话和备份均不进入公开包。

package/UPDATE.md

@@ -0,0 +1,11 @@
+# Update for the current Agent
+
+Send to your current Agent:
+
+> 更新 @petercjl/boardmixcli，并验证当前 Agent 的配套 Skill 已同步。
+
+Resolve the selected Agent's exact Skill destination before replacement. Run `skill status` and preserve local edits; unmanaged targets refuse reconciliation. `update check --json` checks the stable registry version. `update install --agent YOUR-VALID-AGENT-NAME --destination ABSOLUTE-SKILL-DIRECTORY --yes --json` downloads a candidate with real npm into a private temporary prefix, synchronizes only the selected target, verifies hashes and returns its target-owned runtime entry. This managed update does not replace an unrelated global npm installation. Use the returned entry as the current installation, or explicitly upgrade the global npm CLI and repeat selected-target synchronization when a global entry is required.
+
+Every package upgrade requires Skill synchronization, including same-version missing/stale repair. A verified current target takes a read-only no-op branch. Existing managed targets receive a recoverable adjacent backup before replacement. Host UI metadata is preserved. Missing canonical files may be repaired; edited files require reconciliation by the user. Package download failure leaves the target unchanged. A synchronization failure reports its phase and recovery; retry against the same target after resolving it. Backups provide rollback by restoring the preserved directory after checking ownership. Refresh host discovery and verify CLI version, Skill manifest/receipt version and `skill status` hashes. Host registration remains a separate host-owned phase.
+
+Ordinary atomic task entry checks for updates with a 1200 ms network timeout, persistent 24-hour throttling including offline backoff, and notification only. Set `BOARDMIXCLI_UPDATE_CHECK=0` to disable detection or `BOARDMIXCLI_CACHE_DIR` to choose a cache directory. Automatic installation requires an explicit update request. No other Agent is synchronized.

package/bin/boardmixcli.mjs

@@ -0,0 +1,34 @@
+#!/usr/bin/env node
+import {readFile,writeFile,stat} from 'node:fs/promises';
+import path from 'node:path';
+import {startBridge} from '../lib/bridge.mjs';
+import {operations,validate} from '../lib/protocol.mjs';
+import {atomicCommand} from '../lib/commands.mjs';
+import {maintenance,meta,parse,checkUpdate} from '../lib/maintenance.mjs';
+const args=process.argv.slice(2), command=args.shift();
+const output=x=>process.stdout.write(JSON.stringify(x,null,2)+'\n');
+function flag(k){const i=args.indexOf(k);return i<0?undefined:args[i+1];}
+async function absent(p){try{await stat(p);throw Error('TARGET_EXISTS: '+p);}catch(e){if(e.code!=='ENOENT')throw e;}}
+try {
+  if(['skill','update','doctor'].includes(command))output({ok:true,...await maintenance(command,args)});
+  else if(['board.info','board.create','board.rename','board.open','board.close','image.list','image.inspect','image.import','object.selection','object.get','object.move','object.resize','view.fit'].includes(command)){await checkUpdate({automatic:true});output(await atomicCommand(command,args));}
+  else if(command==='version'||command==='--version') {parse(args,{'--json':'boolean'});output({package:meta.name,version:meta.version});}
+  else if(command==='capabilities') output(JSON.parse(await readFile(new URL('../capabilities.json',import.meta.url),'utf8')));
+  else if(command==='serve') {
+    const target=flag('--session');if(!target)throw Error('SESSION_PATH_REQUIRED');
+    const session=path.resolve(target), boot=session+'.bootstrap.js';await absent(session);await absent(boot);
+    const bridge=await startBridge();
+    try{await writeFile(session,JSON.stringify({endpoint:bridge.endpoint,token:bridge.token}),{flag:'wx',mode:0o600});await writeFile(boot,bridge.bootstrap(),{flag:'wx',mode:0o600});}
+    catch(e){bridge.server.close();throw e;}
+    output({listening:bridge.endpoint,session,bootstrap:boot});
+  } else if(['status','request'].includes(command)) {
+    const target=flag('--session');if(!target)throw Error('SESSION_PATH_REQUIRED');
+    const {endpoint,token}=JSON.parse(await readFile(target,'utf8'));
+    if(!/^http:\/\/127\.0\.0\.1:\d+$/.test(endpoint)||typeof token!=='string')throw Error('INVALID_SESSION');
+    const headers={Authorization:'Bearer '+token,'Content-Type':'application/json'};
+    let request;
+    if(command==='request'){const file=flag('--input');if(!file)throw Error('INPUT_PATH_REQUIRED');request=validate(JSON.parse(await readFile(file,'utf8')));}
+    const r=await fetch(endpoint+(command==='status'?'/status':'/request'),{method:request?'POST':'GET',headers,body:request?JSON.stringify(request):undefined,signal:AbortSignal.timeout(20000)});
+    const result=await r.json();output(result);if(!r.ok||result.ok===false)process.exitCode=1;
+  } else output({usage:['serve --session <new-private-session-file>','status --session <file>','request --session <file> --input <json-file>','board.info | board.create | board.rename | board.open | board.close','image.list | image.inspect | image.import','object.selection | object.get | object.move | object.resize','view.fit --ids <JSON-GUID-array>','version','capabilities'],stage:'atomic-command-prototype'});
+} catch(error) {output({ok:false,error:error.message,...error.details?{details:error.details}:{}});process.exitCode=1;}

package/capabilities.json

@@ -0,0 +1,230 @@
+{
+  "schemaVersion": 1,
+  "package": "@petercjl/boardmixcli",
+  "version": "0.1.0",
+  "stage": "experimental",
+  "releaseReady": true,
+  "responsibility": "Explicit capability operations; business workflow and layout remain with the calling Agent or application Skill",
+  "commands": [
+    "board.info",
+    "board.create",
+    "board.rename",
+    "board.open",
+    "board.close",
+    "image.list",
+    "image.inspect",
+    "image.import",
+    "object.selection",
+    "object.get",
+    "object.move",
+    "object.resize",
+    "view.fit"
+  ],
+  "coordinateContract": "object.move uses absolute top-left board coordinates",
+  "imageFormats": [
+    "image/png"
+  ],
+  "authentication": "ephemeral loopback token and existing Boardmix app login",
+  "adapterBuild": "index-DjSD2oPg.js",
+  "requiredCapabilities": [
+    "Node.js >=22",
+    "filesystem access",
+    "loopback HTTP",
+    "authorized Boardmix editor and console bootstrap"
+  ],
+  "agentEligibility": "Any Agent satisfying required capabilities",
+  "platformEvidence": {
+    "macos": "Boardmix 1.7.2 real atomic operations tested",
+    "windows": "portable lifecycle CI required; Boardmix runtime unverified",
+    "linux": "portable lifecycle CI required; Boardmix runtime unverified"
+  },
+  "unresolved": [
+    "Automatic attachment per opened editor view",
+    "Boardmix runtime validation on Windows and Linux"
+  ],
+  "installationLifecycle": {
+    "agentNeutral": true,
+    "targetRequired": true,
+    "hostRegistrationRequired": true,
+    "installationMode": "copy",
+    "sharedLinksAllowed": false,
+    "isolatedRuntimeRequired": true,
+    "skillRequired": true,
+    "updateRequiresSkillSync": true,
+    "required_components": [
+      "cli",
+      "skill"
+    ],
+    "installGuide": "INSTALL.md",
+    "updateGuide": "UPDATE.md",
+    "install": "Resolve own target; skill install with explicit agent and destination; copy runtime",
+    "update": "Stage candidate with npm; reconcile only selected Skill including same version",
+    "verification": "sha256 plus package, Skill and receipt version agreement; host discovery verified by host",
+    "installerIntegration": "postinstall notice and scripts-disabled INSTALL.md handoff"
+  },
+  "automaticUpdates": {
+    "enabledByDefault": true,
+    "intervalHours": 24,
+    "timeoutMs": 1200,
+    "trigger": "ordinary atomic command entry",
+    "configuration": "BOARDMIXCLI_CACHE_DIR selects cache",
+    "disable": "BOARDMIXCLI_UPDATE_CHECK=0",
+    "recovery": "24 hour offline backoff or explicit update check",
+    "defaultMode": "notify"
+  },
+  "commandContracts": {
+    "skill source": {
+      "options": {
+        "--json": {
+          "type": "boolean"
+        }
+      },
+      "sideEffects": "none"
+    },
+    "skill status": {
+      "options": {
+        "--json": {
+          "type": "boolean"
+        },
+        "--agent": {
+          "type": "string"
+        },
+        "--destination": {
+          "type": "string"
+        }
+      },
+      "sideEffects": "none"
+    },
+    "skill install": {
+      "options": {
+        "--json": {
+          "type": "boolean"
+        },
+        "--agent": {
+          "type": "string"
+        },
+        "--destination": {
+          "type": "string"
+        }
+      },
+      "sideEffects": "local-write"
+    },
+    "skill update": {
+      "options": {
+        "--json": {
+          "type": "boolean"
+        },
+        "--agent": {
+          "type": "string"
+        },
+        "--destination": {
+          "type": "string"
+        }
+      },
+      "sideEffects": "local-write"
+    },
+    "doctor": {
+      "options": {
+        "--json": {
+          "type": "boolean"
+        }
+      },
+      "sideEffects": "none"
+    },
+    "update check": {
+      "options": {
+        "--json": {
+          "type": "boolean"
+        }
+      },
+      "sideEffects": "local-write"
+    },
+    "update install": {
+      "options": {
+        "--json": {
+          "type": "boolean"
+        },
+        "--agent": {
+          "type": "string"
+        },
+        "--destination": {
+          "type": "string"
+        },
+        "--yes": {
+          "type": "boolean"
+        }
+      },
+      "sideEffects": "package-and-skill-update"
+    }
+  },
+  "maintenanceContract": {
+    "schemaVersion": 1,
+    "agentEligibility": "valid-name-with-generic-fallback",
+    "hostDiscoveryAuthority": "host",
+    "targetOptions": {
+      "--destination": {
+        "kind": "skill-directory"
+      }
+    },
+    "source": {
+      "name": {
+        "field": "name",
+        "type": "string"
+      },
+      "package": {
+        "field": "package",
+        "type": "string"
+      },
+      "version": {
+        "field": "version",
+        "type": "string"
+      },
+      "path": {
+        "field": "source",
+        "type": "string"
+      }
+    },
+    "status": {
+      "name": {
+        "field": "name",
+        "type": "string"
+      },
+      "package": {
+        "field": "package",
+        "type": "string"
+      },
+      "version": {
+        "field": "version",
+        "type": "string"
+      },
+      "target": {
+        "field": "target",
+        "type": "string"
+      },
+      "installed": {
+        "field": "installed",
+        "type": "boolean"
+      },
+      "managed": {
+        "field": "managed",
+        "type": "boolean"
+      },
+      "current": {
+        "field": "current",
+        "type": "boolean"
+      },
+      "edited": {
+        "field": "edited",
+        "type": "string[]"
+      },
+      "verification": {
+        "field": "verification",
+        "type": "object"
+      },
+      "recovery": {
+        "field": "recovery",
+        "type": "object"
+      }
+    }
+  }
+}

package/lib/assets.mjs

@@ -0,0 +1,18 @@
+import {readFile,readdir,stat} from 'node:fs/promises';
+import {createHash} from 'node:crypto';
+import path from 'node:path';
+
+export async function inspectImage(file) {
+  const absolute=path.resolve(file), metadata=await stat(absolute);
+  if(!metadata.isFile())throw Error('IMAGE_FILE_REQUIRED');
+  const bytes=await readFile(absolute);
+  if(bytes.length<24||bytes.subarray(0,8).toString('hex')!=='89504e470d0a1a0a')throw Error('PNG_REQUIRED_IN_THIS_ADAPTER');
+  const width=bytes.readUInt32BE(16),height=bytes.readUInt32BE(20);
+  if(!width||!height||bytes.length>100*1024*1024)throw Error('INVALID_IMAGE');
+  return {file:absolute,name:path.basename(absolute),mime:'image/png',size:bytes.length,width,height,sha256:createHash('sha256').update(bytes).digest('hex')};
+}
+export async function listImages(directory) {
+  const entries=await readdir(directory,{withFileTypes:true});
+  const names=entries.filter(e=>e.isFile()&&/\.png$/i.test(e.name)).map(e=>e.name).sort((a,b)=>a.localeCompare(b,'en',{numeric:true}));
+  return Promise.all(names.map(name=>inspectImage(path.join(directory,name))));
+}

package/lib/bridge.mjs

@@ -0,0 +1,55 @@
+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>16384) 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 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 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);
+        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'&&!assets.has(input.params.assetId))throw Error('ASSET_NOT_REGISTERED');
+        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=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.list'].includes(input.op)});},input.op==='image.import'?150000:30000);
+        pending.set(id,{res,timer});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/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 {call,request:(op,fileKey,params={})=>call('/request',{op,fileKey,params})};
+}

package/lib/commands.mjs

@@ -0,0 +1,35 @@
+import {parse} from './maintenance.mjs';
+import {connect} from './client.mjs';
+import {inspectImage,listImages} from './assets.mjs';
+export async function atomicCommand(command,args){
+  const extras={
+   '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=[...(command==='image.list'||command==='image.inspect'?[]:['--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.list')return {images:await listImages(option('--directory'))};
+  if(command==='image.inspect')return inspectImage(option('--file'));
+  const client=await connect(option('--session')),fileKey=option('--file-key');
+  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/maintenance.mjs

@@ -0,0 +1,168 @@
+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 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(1200)});
+  if(!r.ok)throw Error('REGISTRY_'+r.status);
+  const published=await r.json();result={checkedAt:Date.now(),version:meta.version,latest:published.version,available: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);
+ 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:'Existing Boardmix login and explicit per-editor console bootstrap; 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');
+}

package/lib/page-adapter.js

@@ -0,0 +1,83 @@
+// Versioned adapter for the Boardmix web bundle observed in desktop 1.7.2.
+// Called with explicit local endpoint/token; no business layout decisions here.
+async function installPageAdapter(config,mainScript){
+  if(window.__boardmixcliPageBridge)window.__boardmixcliPageBridge.stop();
+  const src=Array.from(document.scripts).map(s=>s.src).find(s=>/\/assets\/index-[^/]+\.js/.test(s));
+  if(!src||!src.endsWith('/index-DjSD2oPg.js'))throw Error('UNVERIFIED_BOARDMIX_BUILD');
+  const module=await import(src), manager=module.z(),files=module.bm(),importer=module.eb;
+  if(typeof manager.renameFile!=='function'||typeof files.httpCreateFile!=='function'||typeof importer.importPureRefFiles!=='function')throw Error('ADAPTER_CONTRACT_MISMATCH');
+  const headers={Authorization:'Bearer '+config.token,'Content-Type':'application/json'};
+  let stopped=false,timer,pendingReply;
+  async function send(route,data){const r=await fetch(config.endpoint+route,{method:data?'POST':'GET',headers,body:data?JSON.stringify(data):undefined});if(!r.ok)throw Error('LOCAL_BRIDGE_'+r.status);return r.json();}
+  const runner=module.lr;
+  await runner.run({id:'boardmixcli-atomic',name:'boardmixcli',main:'main.js'},mainScript,'<!doctype html><meta charset="utf-8"><p>boardmixcli 已连接</p>');
+  function onReply(e){const r=e.data?.pluginMessage;if(r?.channel==='boardmixcli-v1'&&typeof r.ok==='boolean'&&pendingReply?.id===r.id){const done=pendingReply.resolve;pendingReply=null;done(r);}}
+  window.addEventListener('message',onReply);
+  async function plugin(op,params={}){
+    if(pendingReply)throw Error('PLUGIN_BUSY');
+    const id=crypto.randomUUID();
+    return new Promise((resolve,reject)=>{
+      const t=setTimeout(()=>{if(pendingReply?.id===id)pendingReply=null;reject(Error('PLUGIN_TIMEOUT'));},10000);
+      pendingReply={id,resolve:r=>{clearTimeout(t);r.ok?resolve(r.result):reject(Error(r.error));}};
+      window.postMessage({pluginMessage:{channel:'boardmixcli-v1',id,op,fileKey:manager.fileKey,params}},location.origin);
+    });
+  }
+  function boardInfo(){const f=manager.fileInfo;return {fileKey:manager.fileKey,name:f.name,teamId:f.team_id,projectId:f.project_id,folderId:f.folder_id,localSavePending:manager.isLocalSpaceActive&&manager.isEditorNeedSave,coopStatus:module.rl().coopStatus,uploading:importer.progressMap?.size||0};}
+  async function execute(job){
+    if(job.fileKey!==manager.fileKey)throw Error('FILE_MISMATCH');
+    const p=job.params;
+    if(job.op==='board.info')return boardInfo();
+    if(job.op==='board.create'){
+      const r=await files.httpCreateFile(p.teamId,p.projectId,p.folderId,undefined);
+      return {fileKey:r.file_key,name:r.name,teamId:r.team_id,projectId:r.project_id};
+    }
+    if(job.op==='board.rename'){await manager.renameFile(p.name);const read=await files.httpGetFile(job.fileKey);if(read.name!==p.name)throw Error('RENAME_READBACK_MISMATCH');return {fileKey:job.fileKey,name:read.name};}
+    if(job.op==='board.open'){if(!window.desktopManagerApi?.openFile)throw Error('DESKTOP_OPEN_UNAVAILABLE');window.desktopManagerApi.openFile(p.targetFileKey);return {requested:true,targetFileKey:p.targetFileKey};}
+    if(job.op==='board.close'){
+      if(importer.progressMap?.size||(manager.isLocalSpaceActive&&manager.isEditorNeedSave)||(!manager.isLocalSpaceActive&&module.rl().coopStatus!==1))throw Error('SAVE_OR_UPLOAD_PENDING');
+      if(!window.desktopManagerApi?.closeView)throw Error('DESKTOP_CLOSE_UNAVAILABLE');return {closeRequested:true,fileKey:job.fileKey};
+    }
+    if(job.op==='object.resize'){
+      const guid={sessionID:p.sessionID,localID:p.localID},original=await plugin('object.get',guid);
+      const locked=original.aspectRatioLocked;
+      let matched=false;
+      try{
+        if(locked){module.mK({nodes:[{guid,privateInfo:{lockAspectRatio:false}}]});await new Promise(r=>setTimeout(r,150));}
+        module.mK({nodes:[{guid,width:p.width,height:p.height}]});
+        const deadline=Date.now()+3000;
+        while(Date.now()<deadline){await new Promise(r=>setTimeout(r,100));const shape=await plugin('object.get',guid);if(Math.abs(shape.width-p.width)<0.01&&Math.abs(shape.height-p.height)<0.01){matched=true;break;}}
+        if(!matched)throw Error('RESIZE_READBACK_MISMATCH');
+      }finally{if(locked){module.mK({nodes:[{guid,privateInfo:{lockAspectRatio:true}}]});await new Promise(r=>setTimeout(r,150));}}
+      return plugin('object.get',guid);
+    }
+    if(job.op==='image.import'){
+      const a=await send('/asset-info/'+p.assetId),before=await plugin('object.selection');
+      const r=await fetch(config.endpoint+'/asset/'+p.assetId,{headers});if(!r.ok)throw Error('ASSET_FETCH_FAILED');
+      const blob=await r.blob(),file=new File([blob],a.name,{type:a.mime});
+      const submitted=await importer.importPureRefFiles([{file}]);if(submitted!==1)throw Error('IMPORT_REJECTED');
+      const known=new Set(before.objects.map(x=>x.guid.sessionID+':'+x.guid.localID));
+      const deadline=Date.now()+120000;
+      while(Date.now()<deadline){
+        await new Promise(r=>setTimeout(r,500));
+        const current=await plugin('object.selection'),added=current.objects.filter(x=>!known.has(x.guid.sessionID+':'+x.guid.localID));
+        if(added.length>1)throw Error('CONCURRENT_CANVAS_MUTATION');
+        if(added.length===1&&!(importer.progressMap?.size)&&added[0].width>0&&added[0].height>0)return {asset:{name:a.name,sha256:a.sha256,width:a.width,height:a.height},object:added[0],uploadFinished:true};
+      }
+      throw Error('IMPORT_OUTCOME_UNKNOWN');
+    }
+    return plugin(job.op,p);
+  }
+  async function poll(){
+    if(stopped)return;
+    try{
+      const next=await send('/next?fileKey='+encodeURIComponent(manager.fileKey));
+      if(next.request){const job=next.request;let response;try{response={id:job.id,ok:true,result:await execute(job)};}catch(e){response={id:job.id,ok:false,error:String(e.message||e)};}
+        await send('/result',response);
+        if(job.op==='board.close'&&response.ok){window.__boardmixcliPageBridge.stop();setTimeout(()=>window.desktopManagerApi.closeView(),100);return;}
+      }
+    }catch(e){console.warn('boardmixcli connection',e.message);}
+    timer=setTimeout(poll,350);
+  }
+  window.__boardmixcliPageBridge={stop(){stopped=true;clearTimeout(timer);window.removeEventListener('message',onReply);}};
+  poll();return {connected:true,...boardInfo()};
+}

package/lib/protocol.mjs

@@ -0,0 +1,23 @@
+export const operations = ['info','frame.create','object.get','object.selection','object.move','object.resize','view.fit','board.info','board.create','board.rename','board.open','board.close','image.import'];
+export function validate(input) {
+  if (!input || !operations.includes(input.op)) throw new Error('UNSUPPORTED_OPERATION');
+  if (typeof input.fileKey !== 'string' || !/^[A-Za-z0-9_-]{8,100}$/.test(input.fileKey)) throw new Error('INVALID_FILE_KEY');
+  const p = input.params ?? {};
+  if (!p || typeof p !== 'object' || Array.isArray(p)) throw new Error('INVALID_PARAMS');
+  const fields = ({'frame.create':['x','y','width','height','content'],'object.get':['sessionID','localID'],'object.move':['sessionID','localID','x','y'],'object.resize':['sessionID','localID','width','height'],'view.fit':['guids'],'board.create':['teamId','projectId','folderId'],'board.rename':['name'],'board.open':['targetFileKey'],'image.import':['assetId']})[input.op]||[];
+  if (Object.keys(p).some(k => !fields.includes(k))) throw new Error('UNKNOWN_PARAMETER');
+  if (input.op === 'frame.create') {
+    for (const k of ['x','y','width','height']) if (!Number.isFinite(p[k]) || Math.abs(p[k]) > 1e6) throw new Error('INVALID_GEOMETRY');
+    if (p.width <= 0 || p.height <= 0) throw new Error('INVALID_GEOMETRY');
+    if (p.content !== undefined && (typeof p.content !== 'string' || p.content.length > 1000)) throw new Error('INVALID_CONTENT');
+  }
+  if (['object.get','object.move','object.resize'].includes(input.op)) for (const k of ['sessionID','localID']) if (!Number.isSafeInteger(p[k]) || p[k] < 0) throw new Error('INVALID_GUID');
+  if(input.op==='object.move')for(const k of ['x','y'])if(!Number.isFinite(p[k])||Math.abs(p[k])>1e7)throw Error('INVALID_GEOMETRY');
+  if(input.op==='object.resize')for(const k of ['width','height'])if(!Number.isFinite(p[k])||p[k]<=0||p[k]>1e6)throw Error('INVALID_GEOMETRY');
+  if(input.op==='board.create')for(const k of ['teamId','projectId','folderId'])if(!Number.isSafeInteger(p[k])||p[k]<0)throw Error('INVALID_DESTINATION');
+  if(input.op==='board.rename'&&(typeof p.name!=='string'||!p.name.trim()||p.name.length>100))throw Error('INVALID_NAME');
+  if(input.op==='board.open'&&(typeof p.targetFileKey!=='string'||!/^[A-Za-z0-9_-]{8,100}$/.test(p.targetFileKey)))throw Error('INVALID_FILE_KEY');
+  if(input.op==='image.import'&&(typeof p.assetId!=='string'||!/^[a-f0-9]{64}$/.test(p.assetId)))throw Error('INVALID_ASSET_ID');
+  if(input.op==='view.fit'&&(!Array.isArray(p.guids)||!p.guids.length||p.guids.length>1000||p.guids.some(g=>!Number.isSafeInteger(g.sessionID)||g.sessionID<0||!Number.isSafeInteger(g.localID)||g.localID<0)))throw Error('INVALID_GUID_LIST');
+  return {op:input.op,fileKey:input.fileKey,params:p};
+}

package/package.json

@@ -1,16 +1,45 @@
 {
   "name": "@petercjl/boardmixcli",
-  "version": "0.0.0-bootstrap.0",
-  "description": "Reserved bootstrap package for configuring GitHub Actions Trusted Publishing",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Atomic Boardmix desktop operations and portable Agent capability manual",
   "license": "MIT",
-  "publishConfig": {
-    "access": "public"
-  },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/petercjl/boardmixcli.git"
   },
+  "homepage": "https://github.com/petercjl/boardmixcli#readme",
+  "bugs": {
+    "url": "https://github.com/petercjl/boardmixcli/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "bin": {
+    "boardmixcli": "bin/boardmixcli.mjs"
+  },
+  "scripts": {
+    "test": "node --test test/*.test.mjs",
+    "check": "node scripts/validate-package.mjs",
+    "prepack": "node scripts/validate-package.mjs",
+    "postinstall": "node scripts/install-notice.mjs",
+    "smoke": "node scripts/packed-smoke.mjs"
+  },
+  "engines": {
+    "node": ">=22"
+  },
   "files": [
-    "README.md"
+    "bin/*.mjs",
+    "lib/*.mjs",
+    "lib/page-adapter.js",
+    "plugin/main.js",
+    "scripts/*.mjs",
+    "skills/boardmixcli/**",
+    "README.md",
+    "INSTALL.md",
+    "UPDATE.md",
+    "LICENSE",
+    "CONTRACT.md",
+    "capabilities.json"
   ]
 }

package/plugin/main.js

@@ -0,0 +1,40 @@
+// Boardmix plugin sandbox. Only named operations are accepted.
+function compact(r) {
+  return {guid:r.guid,name:r.name,x:r.x,y:r.y,width:r.width,height:r.height,objectType:r.objectType,aspectRatioLocked:r.lockAspectRatio,resourceHash:r.imageInfo&&r.imageInfo.hash,cropped:r.imageInfo&&r.imageInfo.cropped,imageNum:r.imageNum};
+}
+boardmix.ui.on('message', function(message) {
+  if (!message || message.channel !== 'boardmixcli-v1' || typeof message.op !== 'string') return;
+  var response = {channel:'boardmixcli-v1', id:message.id};
+  try {
+    if (message.fileKey !== boardmix.fileKey) throw new Error('FILE_MISMATCH');
+    var p = message.params || {};
+    if (message.op === 'info') response.result = {fileKey:boardmix.fileKey, apiVersion:boardmix.apiVersion, view:boardmix.viewport.getView(), zoom:boardmix.viewport.getZoom(), operations:['info','frame.create','object.get']};
+    else if (message.op === 'frame.create') {
+      var created = boardmix.createFrame(p);
+      var g = created.guid;
+      response.result = {created:compact(created), readback:compact(boardmix.getById(g.sessionID,g.localID))};
+    } else if (message.op === 'object.get') response.result = compact(boardmix.getById(p.sessionID,p.localID));
+    else if(message.op==='object.selection'){
+      var selection=boardmix.getSelect();response.result={objects:selection.guids.map(function(g){return compact(boardmix.getById(g.sessionID,g.localID));})};
+    }
+    else if(message.op==='view.fit'){
+      boardmix.viewport.zoomTo({guids:p.guids});response.result={guids:p.guids,zoom:boardmix.viewport.getZoom(),view:boardmix.viewport.getView()};
+    }
+    else if(message.op==='object.move'){
+      var original=boardmix.getById(p.sessionID,p.localID);
+      boardmix.moveTo(p.sessionID,p.localID,p.x+original.width/2,p.y+original.height/2);
+      var moved=compact(boardmix.getById(p.sessionID,p.localID));
+      if(Math.abs(moved.x-p.x)>0.01||Math.abs(moved.y-p.y)>0.01)throw new Error('MOVE_READBACK_MISMATCH:'+JSON.stringify(moved));
+      response.result=moved;
+    }
+    else if(message.op==='object.resize'){
+      throw new Error('HOST_ADAPTER_REQUIRED_FOR_EXACT_RESIZE');
+    }
+    else throw new Error('UNSUPPORTED_OPERATION');
+    response.ok = true;
+  } catch (error) { response.ok = false; response.error = String(error.message || error); }
+  boardmix.ui.postMessage(response);
+});
+// Boardmix routes sandbox replies through its plugin window wrapper.
+boardmix.showUI({title:'boardmixcli',width:280,height:90});
+boardmix.ui.hide();

package/scripts/install-notice.mjs

@@ -0,0 +1 @@
+console.log('@petercjl/boardmixcli: CLI installation is one phase. Ask your current Agent to read INSTALL.md / UPDATE.md, resolve its own Skill destination, run skill install/update, verify hashes and refresh host discovery. No service access is granted by installation.');

package/scripts/packed-smoke.mjs

@@ -0,0 +1,32 @@
+import {mkdtemp,readFile,rm,writeFile,stat} from 'node:fs/promises';
+import {execFileSync} from 'node:child_process';
+import {fileURLToPath} from 'node:url';
+import {tmpdir} from 'node:os';
+import path from 'node:path';
+import assert from 'node:assert/strict';
+const root=fileURLToPath(new URL('../',import.meta.url)),scratch=await mkdtemp(path.join(tmpdir(),'boardmix-packed-'));
+const npmCli=process.env.npm_execpath||fileURLToPath(new URL('../../../npm/bin/npm-cli.js',import.meta.url));
+function npm(args){return execFileSync(process.execPath,[npmCli,...args],{cwd:root,encoding:'utf8',env:{...process.env,BOARDMIXCLI_UPDATE_CHECK:'0'}});}
+function cli(entry,args){return JSON.parse(execFileSync(process.execPath,[entry,...args],{encoding:'utf8',env:{...process.env,BOARDMIXCLI_UPDATE_CHECK:'0'}}));}
+try{
+ const packed=JSON.parse(npm(['pack','--silent','--json','--pack-destination',scratch]))[0];
+ assert.ok(packed.files.every(f=>!/(evidence|\.bak-|\.session\.|bootstrap\.js)/.test(f.path)));
+ const bootstrap=path.join(scratch,'bootstrap');npm(['install','--prefix',bootstrap,'--ignore-scripts','--no-audit','--no-fund',path.join(scratch,packed.filename)]);
+ const entry=path.join(bootstrap,'node_modules/@petercjl/boardmixcli/bin/boardmixcli.mjs');
+ const version=cli(entry,['version']).version;
+ for(const name of ['host-a','host-b']){
+  const target=path.join(scratch,name),args=['--agent',name,'--destination',target,'--json'];
+  assert.equal(cli(entry,['skill','status',...args]).installed,false);
+  assert.equal(cli(entry,['skill','install',...args]).current,true);
+  assert.equal(cli(entry,['skill','update',...args]).changed,false);
+ }
+ const a=path.join(scratch,'host-a/.runtime/bin/boardmixcli.mjs'),b=path.join(scratch,'host-b/.runtime/bin/boardmixcli.mjs');
+ if(process.platform!=='win32')assert.notEqual((await stat(a)).ino,(await stat(b)).ino);
+ await rm(bootstrap,{recursive:true});await rm(path.join(scratch,'host-a'),{recursive:true});
+ assert.equal(cli(b,['version']).version,version);
+ const png=Buffer.alloc(24);Buffer.from('89504e470d0a1a0a','hex').copy(png);png.write('IHDR',12);png.writeUInt32BE(750,16);png.writeUInt32BE(1475,20);
+ const image=path.join(scratch,'图片.png');await writeFile(image,png);
+ const result=cli(b,['image.inspect','--file',image]);assert.equal(result.width,750);assert.equal(result.height,1475);
+ assert.equal(cli(b,['skill','status','--agent','host-b','--destination',path.join(scratch,'host-b'),'--json']).current,true);
+ console.log(JSON.stringify({ok:true,version,packedFiles:packed.files.length,isolation:'bootstrap and host-a removed; host-b version, image.inspect and receipt verified',historicalUpdater:'first release; registry absence checked before bootstrap publication'}));
+}finally{await rm(scratch,{recursive:true,force:true});}

package/scripts/sync-version.mjs

@@ -0,0 +1,13 @@
+// Release-only identity synchronization; prepack remains read-only.
+import {readFile,writeFile,copyFile,stat} from 'node:fs/promises';
+import {fileURLToPath} from 'node:url';
+import path from 'node:path';
+import {randomUUID} from 'node:crypto';
+const root=fileURLToPath(new URL('../',import.meta.url));
+const pkg=JSON.parse(await readFile(path.join(root,'package.json'),'utf8'));
+for(const name of ['capabilities.json','skills/boardmixcli/manifest.json']){
+ const p=path.join(root,name);await stat(p);const x=JSON.parse(await readFile(p,'utf8'));
+ if(x.version===pkg.version&&x.package===pkg.name)continue;
+ await copyFile(p,p+'.bak-'+randomUUID());x.version=pkg.version;x.package=pkg.name;
+ await writeFile(p,JSON.stringify(x,null,2)+'\n');
+}

package/scripts/validate-package.mjs

@@ -0,0 +1,11 @@
+import {readFile} from 'node:fs/promises';
+import {fileURLToPath} from 'node:url';
+import path from 'node:path';
+const root=fileURLToPath(new URL('../',import.meta.url));
+const p=JSON.parse(await readFile(path.join(root,'package.json'),'utf8'));
+for(const f of ['capabilities.json','skills/boardmixcli/manifest.json']){
+ const x=JSON.parse(await readFile(path.join(root,f),'utf8'));
+ if(x.version!==p.version||x.package!==p.name)throw Error('VERSION_DRIFT: '+f);
+}
+for(const f of ['INSTALL.md','UPDATE.md','CONTRACT.md','skills/boardmixcli/SKILL.md'])if(!(await readFile(path.join(root,f),'utf8')).trim())throw Error('MISSING_RESOURCE: '+f);
+console.error('Package and Skill identity verified: '+p.name+'@'+p.version);

package/skills/boardmixcli/SKILL.md

@@ -0,0 +1,26 @@
+---
+name: boardmixcli
+description: Operate Boardmix desktop boards through explicit atomic CLI commands for files, PNG images, object geometry and viewport. Use for authorized Boardmix automation; the caller owns content and layout decisions.
+---
+
+# BoardmixCLI capability manual
+
+Input: explicit operations, Boardmix file keys, local PNG paths and object GUIDs, authorized by the user. Strategy: discover the installed contract, connect the selected editor, execute atomic operations and verify readback. Output: JSON receipts and verified Boardmix state. The calling Agent or application Skill owns business methods, material selection, ordering and layout.
+
+## Main line
+
+1. Resolve this Skill directory from the host's actual loaded resource path. Use Node.js with its target-owned `.runtime/bin/boardmixcli.mjs`; never infer a different Agent's installation path. Read this Skill’s `capabilities.json` and `adapters/generic.json` to resolve the logical execution and desktop features from the current host. Run `version`, `capabilities --json`, and `doctor --json`. In a source npm checkout, resolve the canonical runtime through the package CLI instead. Node.js >=22, local filesystem, loopback HTTP and authorized editor-console access are required. Any Agent with these capabilities may use the generic adapter. Native desktop execution is tested on macOS Boardmix 1.7.2; other desktop platforms remain unverified.
+2. For local inspection, `image.list --directory ABSOLUTE_DIRECTORY` returns PNG filenames in natural numeric order; `image.inspect --file ABSOLUTE_PNG` returns source dimensions and SHA256. Caller decides whether this order suits the task. For editor actions, read the runtime's `CONTRACT.md` before the first write to obtain exact flags and response/error contracts.
+3. Start `serve --session NEW_ABSOLUTE_PRIVATE_FILE`. Use the host's authorized native desktop tools to open the intended Boardmix editor's developer Console and execute the generated bootstrap script. This is an explicit provider adapter prerequisite: each opened editor requires its own connection. Close developer tools before file-close operations. Verify `status --session FILE` and `board.info --session FILE --file-key EXACT_KEY` identify the intended view. A mismatched front-end build stops for adapter repair.
+4. Execute only caller-selected operations: file create/name/open/close; one PNG import; object get/move/resize; explicit viewport fit. Every editor command requires `--session` and `--file-key`. GUID sessionID/localID are separate numeric flags. Move uses absolute top-left board coordinates. Resize sets both dimensions and preserves aspect-ratio lock. Inspect each receipt, then read object/file state to verify the requested change before proceeding.
+5. Report actual file identity, operations, verified state and unresolved outcomes. For close, verify the file is absent from the desktop's open-file tabs after the close receipt. Fit animates asynchronously, so an immediate viewport value may precede the final visual state.
+
+## Recovery and boundaries
+
+- Missing Node, desktop controls, console access, login or supported front-end build: return CAPABILITY_UNAVAILABLE / AUTH_REQUIRED / FEATURE_UNSUPPORTED with the prerequisite. Resume at step 1 or 3 after resolution; do not invent a different adapter.
+- File create or image import timeout: outcome may be unknown. Inspect the operation receipt/outcome and actual file/object state before any new mutation. Avoid duplicate creates/imports. Resume at step 4 only when the outcome is known.
+- Protected local destination: preserve unmanaged targets and edits; use CLI-managed skill status/install/update with the current Agent's explicit destination. Installation does not authorize Boardmix writes or paid service actions.
+- Package update: read `.runtime/UPDATE.md`, reconcile only this selected installation, verify CLI/Skill/receipt versions and hashes, then refresh host discovery. A current verified receipt takes a read-only completion branch. Host discovery requires host evidence.
+- New recurring integration failures belong in a separately authorized capability-package repair with tests. Business quality and layout rules remain owned by the application layer.
+
+The runtime CONTRACT.md and capabilities.json are authoritative versioned operation references. This mechanical manual directly internalizes tested command behavior; it has no nested Skill or private knowledge-base dependency. Clean-context regression is separate from ordinary operation.

package/skills/boardmixcli/adapters/generic.json

@@ -0,0 +1,31 @@
+{
+  "schema": "portable-skill-adapter",
+  "schema_version": "1.0.0",
+  "platform": "generic",
+  "mappings": [
+    {
+      "capability_id": "command.execute",
+      "status": "implemented",
+      "implementation": {
+        "kind": "instruction",
+        "discovery": "Resolve command execution and native desktop controls from the current Agent advertised tools. CLI is target-owned .runtime/bin/boardmixcli.mjs; run with Node >=22. Console and tab inspection use host-authorized native desktop control. Return CAPABILITY_UNAVAILABLE when missing."
+      },
+      "features": [
+        "node22",
+        "json-results"
+      ]
+    },
+    {
+      "capability_id": "desktop.console",
+      "status": "implemented",
+      "implementation": {
+        "kind": "instruction",
+        "discovery": "Resolve command execution and native desktop controls from the current Agent advertised tools. CLI is target-owned .runtime/bin/boardmixcli.mjs; run with Node >=22. Console and tab inspection use host-authorized native desktop control. Return CAPABILITY_UNAVAILABLE when missing."
+      },
+      "features": [
+        "console-paste",
+        "inspect-open-tabs"
+      ]
+    }
+  ]
+}

package/skills/boardmixcli/agents/openai.yaml

@@ -0,0 +1,3 @@
+interface:
+  display_name: "BoardmixCLI"
+  short_description: "Operate Boardmix through explicit atomic CLI commands"

package/skills/boardmixcli/capabilities.json

@@ -0,0 +1,67 @@
+{
+  "schema": "portable-skill-capabilities",
+  "schema_version": "1.0.0",
+  "skill": "boardmixcli",
+  "target_platforms": [
+    "generic"
+  ],
+  "host_resolution": {
+    "fallback_adapter": "generic",
+    "destination": "host-supplied explicit Skill directory"
+  },
+  "capabilities": [
+    {
+      "id": "command.execute",
+      "purpose": "Execute target-owned Node CLI",
+      "required": true,
+      "required_features": [
+        "node22",
+        "json-results"
+      ],
+      "input_fields": [
+        "argv"
+      ],
+      "output_fields": [
+        "stdout",
+        "exitCode"
+      ],
+      "side_effects": {
+        "local_process": true,
+        "authorization": "Explicit caller operation",
+        "external_mutation": false,
+        "may_cost_money": false
+      },
+      "errors": [
+        "CAPABILITY_UNAVAILABLE",
+        "FEATURE_UNSUPPORTED"
+      ]
+    },
+    {
+      "id": "desktop.console",
+      "purpose": "Connect authorized Boardmix editor",
+      "required": true,
+      "required_features": [
+        "console-paste",
+        "inspect-open-tabs"
+      ],
+      "input_fields": [
+        "bootstrap-file",
+        "editor-file-key"
+      ],
+      "output_fields": [
+        "connected",
+        "visible-file-state"
+      ],
+      "side_effects": {
+        "application_access": true,
+        "authorization": "User authorized Boardmix access",
+        "external_mutation": true,
+        "may_cost_money": false
+      },
+      "errors": [
+        "CAPABILITY_UNAVAILABLE",
+        "FEATURE_UNSUPPORTED"
+      ]
+    }
+  ]
+}

package/skills/boardmixcli/manifest.json

@@ -0,0 +1,5 @@
+{
+  "name": "boardmixcli",
+  "package": "@petercjl/boardmixcli",
+  "version": "0.1.0"
+}