@petercjl/boardmixcli 0.0.0-stage → 0.1.6

package/CONTRACT.md

@@ -0,0 +1,83 @@
+# 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. For a CDP-connected Chrome, `browser.connect` attaches each exact editor without opening DevTools. Desktop console attachment remains a fallback. 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.
+
+## Added capability operations
+
+`frame.create --session FILE --file-key KEY --x X --y Y --width W --height H --name TEXT` creates one native Frame, normalizes its top-left position, sets and verifies its name.
+
+`text.create` uses the same geometry options with `--text TEXT [--font-size N]` (default 28). Native text uses auto-fit bounds; returned width and height are actual measured values, not a fixed requested rectangle. Verify position and inspect visible content; current text readback exposes font size, not the rich-text content.
+
+`image.download --url URL --output NEW_FILE` downloads only the explicit HTTP(S) source, validates PNG/JPEG/WebP metadata and creates a private new file with SHA256. Existing targets refuse overwrite. `image.inspect`, `image.list` and `image.import` accept the same formats and preserve source bytes. Download failure does not submit anything to Boardmix.
+
+Frame/text creation has the same uncertain-outcome rules as image import. Geometric containment inside Frames is distinct from native parent-child membership; the latter is not exposed by this contract.
+
+## Distribution status
+
+npm-distributed capability package with CLI-managed isolated Skill installation. Source changes beyond the registry version require an explicitly selected development entry until their release. 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.
+
+## Batch operations (contract version 1)
+
+- `image.inspect.batch --input FILE`: JSON array of 1–1000 absolute file paths; returns `images` with dimensions, SHA256 and MD5. Local inspection uses bounded concurrency.
+- `image.import.batch --session SESSION --file-key KEY --input FILE --receipt NEW_FILE`: JSON array of 1–20 `{key,file,sha256?}` entries. Imports through one native uploader call; returns `items` containing the caller key, source metadata and distinct object GUID, plus `uploadFinished`. Native resource hashes are matched to source MD5, independently of completion order. Duplicate bytes receive distinct GUIDs.
+- `object.get.batch --session SESSION --file-key KEY --input FILE`: JSON array of 1–1000 `{sessionID,localID}` values; returns `objects` in input order.
+- `object.place.batch --session SESSION --file-key KEY --input FILE`: JSON array of 1–200 `{sessionID,localID,x,y,width,height}` entries. Validates the whole request, then applies exact dimensions and absolute top-left positions, restores original aspect locks and waits for matching readback. Returns `objects` in input order. It is not a transactional rollback operation: failure can leave partial placement; inspect and repeat explicit placement for the same GUIDs.
+
+Import receipts are private, durable files reserved before submission. Reusing the same input, file key and receipt reads the recorded result or the running bridge outcome; it never submits the import again. Changed inputs return RECEIPT_CONFLICT. BATCH_OUTCOME_UNRESOLVED requires inspection of the existing operation and canvas; retain the receipt, source files and session, and do not create a fresh receipt to retry an uncertain import. Bridge outcomes are in memory; a completed receipt survives bridge restarts. Batch writes on one editor are serialized, while local file reads and native upload scheduling can run concurrently.
+
+Frame creation can return rounded native dimensions. Callers requiring exact fractional geometry apply `object.place.batch` or `object.resize` using the returned GUID. Preserve the GUID before validating final layout so recovery can finish placement without recreating the Frame.
+
+## Browser connection (contract version 1)
+
+The caller supplies an existing, authorized Chrome CDP endpoint as `--endpoint http://127.0.0.1:PORT`. No browser profile is created and no login is copied. Only Boardmix app targets are enumerated. This route does not launch or restart the desktop app. A normal desktop without a CDP endpoint retains the explicit console fallback; a failed browser connection must not silently switch hosts.
+
+- `browser.targets --endpoint URL`: read-only target inventory with title, URL, exact file key and target ID.
+- `browser.open --endpoint URL --file-key KEY`: opens an existing Boardmix file in a browser tab, or reuses its unique existing tab. Requires an existing Boardmix app/home tab. It does not create a Boardmix file. Call `board.create` separately through a connected editor.
+- `browser.connect --endpoint URL --session SESSION --file-key KEY`: matches one exact editor, waits for its app script, injects the versioned adapter and verifies the authenticated local bridge. Reuses only a live adapter matching that session; pending writes refuse replacement. Returns connected/reused/fileKey/visibleDevTools. No visible console is opened.
+- `browser.close --endpoint URL --session SESSION --file-key KEY`: reads upload/save/sync status first, closes only the exact tab and checks that its target disappears. It preserves the cloud file. BROWSER_CLOSE_PENDING requires target inspection rather than a blind repeated close.
+
+Missing endpoint/target, duplicate matching tabs, unverified adapter build and identity mismatch stop with structured errors. Login remains the user's existing browser session. Editor writes still require an explicit file key and the existing capability authorization. Source and CDN image bytes follow the same upload contract as desktop mode. Browser attachment has been tested on macOS Chrome; native Windows/Linux execution remains unverified.
+
+## Managed browser and login
+
+`browser.ensure --json` starts/reuses macOS Google Chrome at http://127.0.0.1:9223 using the persistent `~/.dianshang-chrome-profile`, opens Boardmix home if absent, and returns `state:ready` only after workspace login markers are visible. No pre-opened Boardmix tab is required. The packaged launcher has no ecommerce CLI dependency.
+
+`auth.status --json` is read-only. `auth.wait --wait-ms 60000 --json` resumes preparation and polls login for up to 60 seconds; `browser.ensure` defaults to 15 seconds and returns immediately on an identified login page. AUTH_REQUIRED includes a human login prompt and resume command. Unknown/load states remain AUTH_STATE_UNKNOWN. CLI exits nonzero until ready. Human login/verification stays in Chrome; the CLI does not read or print credentials. Repeat calls reuse the profile and home tab.
+
+Startup verifies the listening process, Chrome executable, debugging port and exact profile. PORT_CONFLICT refuses to change other processes. Missing Chrome and unsupported launch platforms are explicit errors. Windows/Linux launch is not implemented. Existing explicit-endpoint browser commands remain compatible. Browser readiness does not grant file write authorization; continue with the caller-selected file and bridge session.
+
+## Native video contract v1
+
+`video.inspect --file FILE` returns MP4 width, height, duration, SHA256 and MD5 using ffprobe on PATH. `video.download --url HTTPS_URL --output NEW_FILE` preserves source bytes and refuses existing files. Maximum source size is 100 MiB.
+
+`video.import --session SESSION --file-key KEY --file FILE --receipt NEW_RECEIPT` creates one native video object, awaits the provider upload, and verifies object resourceHash equals source MD5, mediaType is video/mp4, and mediaLoading is false. Returns asset, object GUID/geometry, and uploadFinished. Placement is a separate explicit operation. The receipt is reserved before submission. Repeating the same file hash and board with the same receipt retrieves the known result; changed intent returns RECEIPT_CONFLICT, unknown outcome returns VIDEO_OUTCOME_UNRESOLVED without resubmission. Use object.get after recovery to verify the object still exists. No automatic transcoding or poster substitution. Tested on macOS Chrome; other hosts require ffprobe and runtime verification.

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,40 @@
-# Temporary Holding Version
+# BoardmixCLI
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Boardmix 桌面画板的元命令能力包。提供文件新建、命名、打开和关闭，PNG/JPEG/WebP 导入、Frame 与文字创建、图元读取、精确尺寸与位置调整，返回 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/download/import`、`frame.create`、`text.create`、`object.selection/get/move/resize`、`view.fit`。图元移动使用绝对左上角画板坐标；尺寸调整保留宽高比锁定状态。创建和导入超时后先核查结果再决定后续动作。
+
+运行 `npm test` 与 `npm run check` 检查包、命令与安装生命周期。真实画板证据、私人会话和备份均不进入公开包。
+
+Batch contract v1 supports up to 20 images per native import, durable import receipts, bulk object reads and explicit bulk placement. See CONTRACT.md for JSON inputs and recovery behavior.
+
+Existing logged-in Chrome sessions can connect through `browser.targets/open/connect/close` using an explicit loopback CDP endpoint. This route keeps DevTools closed; no desktop restart or additional profile is required. See CONTRACT.md.
+
+## Managed browser and login
+
+`browser.ensure --json` starts/reuses macOS Google Chrome at http://127.0.0.1:9223 using the persistent `~/.dianshang-chrome-profile`, opens Boardmix home if absent, and returns `state:ready` only after workspace login markers are visible. No pre-opened Boardmix tab is required. The packaged launcher has no ecommerce CLI dependency.
+
+`auth.status --json` is read-only. `auth.wait --wait-ms 60000 --json` resumes preparation and polls login for up to 60 seconds; `browser.ensure` defaults to 15 seconds and returns immediately on an identified login page. AUTH_REQUIRED includes a human login prompt and resume command. Unknown/load states remain AUTH_STATE_UNKNOWN. CLI exits nonzero until ready. Human login/verification stays in Chrome; the CLI does not read or print credentials. Repeat calls reuse the profile and home tab.
+
+Startup verifies the listening process, Chrome executable, debugging port and exact profile. PORT_CONFLICT refuses to change other processes. Missing Chrome and unsupported launch platforms are explicit errors. Windows/Linux launch is not implemented. Existing explicit-endpoint browser commands remain compatible. Browser readiness does not grant file write authorization; continue with the caller-selected file and bridge session.

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,48 @@
+#!/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';
+import {targets,attachDesktop,openDesktop,closeBrowser} from '../lib/desktop.mjs';
+import {ensureBrowser,authStatus} from '../lib/browser-session.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(['browser.ensure','auth.status','auth.wait'].includes(command)){
+    const o=parse(args,{'--wait-ms':'string','--json':'boolean'});
+    const r=command==='auth.status'?await authStatus():await ensureBrowser({waitMs:Number(o['--wait-ms']??(command==='auth.wait'?60000:15000))});output(r);if(!r.ok)process.exitCode=1;
+  } else if(command?.startsWith('browser.')) {
+    const o=parse(args,{'--session':'string','--endpoint':'string','--file-key':'string','--json':'boolean'});
+    const options={session:o['--session'],base:o['--endpoint'],fileKey:o['--file-key'],browser:command.startsWith('browser.')};
+    if(options.browser&&!options.base)throw Error('BROWSER_ENDPOINT_REQUIRED');
+    if(command==='browser.targets')output({targets:await targets(options.base)});
+    else if(command==='browser.connect')output(await attachDesktop(options));
+    else if(command==='browser.close')output(await closeBrowser(options));
+    else if(command==='browser.open')output(await openDesktop(options));
+    else throw Error('UNKNOWN_DESKTOP_COMMAND');
+  } else if(['skill','update','doctor'].includes(command))output({ok:true,...await maintenance(command,args)});
+  else if(['video.inspect','video.download','video.import','image.inspect.batch','image.import.batch','object.get.batch','object.place.batch','frame.create','text.create','image.download','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:['browser.ensure [--wait-ms 0..60000]','auth.status | auth.wait [--wait-ms 0..60000]','browser.targets --endpoint URL','browser.open --file-key KEY --endpoint URL','browser.connect | browser.close --session FILE --file-key KEY --endpoint URL','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','image.inspect.batch --input FILES_JSON','image.import.batch --input ITEMS_JSON --receipt NEW_RECEIPT','object.get.batch | object.place.batch --input ITEMS_JSON','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,289 @@
+{
+  "schemaVersion": 1,
+  "package": "@petercjl/boardmixcli",
+  "version": "0.1.6",
+  "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",
+    "frame.create",
+    "text.create",
+    "image.download",
+    "image.inspect.batch",
+    "image.import.batch",
+    "object.get.batch",
+    "object.place.batch",
+    "browser.targets",
+    "browser.open",
+    "browser.connect",
+    "browser.close",
+    "browser.ensure",
+    "auth.status",
+    "auth.wait",
+    "video.inspect",
+    "video.download",
+    "video.import"
+  ],
+  "coordinateContract": "object.move uses absolute top-left board coordinates",
+  "imageFormats": [
+    "image/png",
+    "image/jpeg",
+    "image/webp"
+  ],
+  "authentication": "Managed Chrome launch, human Boardmix login, resumable auth check and ephemeral bridge token",
+  "adapterBuild": "index-DjSD2oPg.js",
+  "requiredCapabilities": [
+    "Node.js >=22",
+    "filesystem access",
+    "loopback HTTP",
+    "authorized Boardmix browser CDP endpoint, or explicit desktop console fallback"
+  ],
+  "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": [
+    "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"
+      }
+    }
+  },
+  "batchContract": {
+    "version": 1,
+    "imageImportLimit": 20,
+    "objectPlaceLimit": 200,
+    "objectReadLimit": 1000,
+    "mapping": "caller key + source MD5 to native resourceHash",
+    "recovery": "--receipt is reserved before submit; repeat only returns recorded or bridge outcome, never reimports"
+  },
+  "browserContract": {
+    "version": 2,
+    "endpoint": "explicit http://127.0.0.1:PORT",
+    "requires": "Chrome installed; browser.ensure owns macOS launch and login readiness",
+    "operations": [
+      "targets",
+      "open",
+      "connect",
+      "close",
+      "ensure",
+      "auth.status",
+      "auth.wait"
+    ],
+    "visibleDevTools": false,
+    "exactFileKey": true,
+    "creationOwnedBy": "board.create",
+    "desktopLaunch": "not provided; existing desktop uses console fallback",
+    "tested": "macOS Chrome with Boardmix index-DjSD2oPg.js",
+    "managedEndpoint": "http://127.0.0.1:9223",
+    "launchPlatforms": [
+      "macos"
+    ]
+  },
+  "videoContract": {
+    "version": 1,
+    "formats": [
+      "video/mp4"
+    ],
+    "maxBytes": 104857600,
+    "requires": "ffprobe on PATH",
+    "import": "Native video object; await upload and verify MD5, MIME and ready state",
+    "receipt": "Required; repeated receipt queries outcome and never resubmits"
+  }
+}

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';
+import {imageMetadata} from './image-codecs.mjs';
+
+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);
+  const {width,height,mime}=imageMetadata(bytes);
+  if(!width||!height||bytes.length>100*1024*1024)throw Error('INVALID_IMAGE');
+  return {file:absolute,name:path.basename(absolute),mime,size:bytes.length,width,height,sha256:createHash('sha256').update(bytes).digest('hex'),md5:createHash('md5').update(bytes).digest('hex')};
+}
+export async function listImages(directory) {
+  const entries=await readdir(directory,{withFileTypes:true});
+  const names=entries.filter(e=>e.isFile()&&/\.(png|jpe?g|webp)$/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/batch.mjs

@@ -0,0 +1,45 @@
+import fs from 'node:fs/promises';
+import crypto from 'node:crypto';
+import {inspectImage} from './assets.mjs';
+import {validate} from './protocol.mjs';
+
+export async function inspectBatch(files){
+  if(!Array.isArray(files)||!files.length||files.length>1000||files.some(f=>typeof f!=='string'))throw Error('INVALID_FILE_LIST');
+  const images=[];
+  for(let i=0;i<files.length;i+=4)images.push(...await Promise.all(files.slice(i,i+4).map(inspectImage)));
+  return {images};
+}
+// A receipt is reserved before submitting. Repeating it only reads a known outcome.
+export async function importBatch(client,fileKey,items,receiptPath){
+  if(!Array.isArray(items)||!items.length||items.length>20)throw Error('INVALID_BATCH');
+  const keys=new Set();
+  for(const i of items){if(!i||Object.keys(i).some(k=>!['key','file','sha256'].includes(k))||typeof i.key!=='string'||!i.key||i.key.length>200||keys.has(i.key)||typeof i.file!=='string'||i.sha256!==undefined&&!/^[a-f0-9]{64}$/.test(i.sha256))throw Error('INVALID_BATCH_ITEM');keys.add(i.key);}
+  const identity=crypto.createHash('sha256').update(JSON.stringify({fileKey,items})).digest('hex');
+  let old;
+  try{old=JSON.parse(await fs.readFile(receiptPath,'utf8'));}catch(e){if(e.code!=='ENOENT')throw e;}
+  if(old){
+    if(old.owner!=='@petercjl/boardmixcli'||old.identity!==identity)throw Error('RECEIPT_CONFLICT');
+    if(old.result)return {ok:true,result:old.result,recovered:true};
+    const outcome=await client.call('/outcome/'+old.operationId);
+    if(!outcome.ok||!outcome.result)throw Object.assign(Error('BATCH_OUTCOME_UNRESOLVED'),{details:{operationId:old.operationId,receipt:receiptPath,outcome}});
+    await saveReceipt(receiptPath,{...old,result:outcome.result,status:'completed'});
+    return {...outcome,recovered:true};
+  }
+  const inspected=(await inspectBatch(items.map(i=>i.file))).images;
+  for(let i=0;i<items.length;i++)if(items[i].sha256&&inspected[i].sha256!==items[i].sha256)throw Error('ASSET_CHANGED');
+  const params={operationId:crypto.randomUUID(),items:items.map((i,n)=>({key:i.key,assetId:inspected[n].sha256}))};
+  validate({op:'image.import.batch',fileKey,params});
+  for(let i=0;i<items.length;i+=4)await Promise.all(inspected.slice(i,i+4).map(a=>client.call('/register-asset',{file:a.file,sha256:a.sha256})));
+  const receipt={owner:'@petercjl/boardmixcli',schemaVersion:1,identity,fileKey,operationId:params.operationId,status:'submitted',createdAt:new Date().toISOString()};
+  await fs.writeFile(receiptPath,JSON.stringify(receipt,null,2),{flag:'wx',mode:0o600});
+  const response=await client.request('image.import.batch',fileKey,params);
+  await saveReceipt(receiptPath,{...receipt,status:'completed',result:response.result});
+  return response;
+}
+async function saveReceipt(file,value){
+  const old=JSON.parse(await fs.readFile(file,'utf8'));
+  if(old.owner!==value.owner||old.identity!==value.identity)throw Error('RECEIPT_CONFLICT');
+  await fs.copyFile(file,file+'.'+crypto.randomUUID()+'.backup',fs.constants.COPYFILE_EXCL);
+  const stage=file+'.'+crypto.randomUUID()+'.tmp';
+  await fs.writeFile(stage,JSON.stringify(value,null,2),{flag:'wx',mode:0o600});await fs.rename(stage,file);
+}