@petercjl/infinite-canvas-cli 0.1.1 → 0.1.3

package/README.md

@@ -8,6 +8,12 @@ Each board file uses exactly one browser tab. Concurrent videos run in separate
 
 `doctor` distinguishes Chrome installation from runtime state. An installed executable passes the browser dependency check while Chrome is stopped. `browser open` launches or reuses the dedicated instance; video execution prepares it automatically. A port/profile conflict is reported explicitly. Chrome outside the standard paths can be selected with `INFINITE_CANVAS_CHROME_BIN`.
 
+## Installation lifecycle
+
+Installing or updating this plugin means preparing both the CLI and its companion Skill for the current Agent. A successful npm command alone is a partial installation. The executing Agent resolves its own Skill directory, reads `infinite-canvas skill source --json`, and completes `infinite-canvas install --agent AGENT_NAME --path SKILL_DIRECTORY --json`. Verify the CLI version and a receipt with `complete=true`, `skill.installed=true` and `skill.current=true`, then load the installed Skill (refresh the Agent session when required). npm installation prints this handoff; if lifecycle scripts are disabled, follow this same flow explicitly. Unknown destinations require resolution before completion; no other Agent directory is changed.
+
+For updates use `infinite-canvas update install --yes --agent AGENT_NAME --path SKILL_DIRECTORY --json`; this synchronizes the selected Skill even if the npm version is unchanged, and refuses missing or edited/unmanaged targets before package replacement. Direct npm upgrades must be followed by the same `install` verification step.
+
 ## Agent usage
 
 Provide the board ID, prompt and reference image attachments in their intended order. Send the Agent:

package/bin/infinite-canvas.mjs

@@ -4,7 +4,7 @@ import path from 'node:path';
 import crypto from 'node:crypto';
 import {META,ROOT,need,parse,readJSON,execute,stateRoot,newJSON,redact,safeId} from '../src/core.mjs';
 import {manifest,HELP} from '../src/contracts.mjs';
-import {automaticCheck,checkUpdate,installUpdate,updatePolicy,SKILL,skillStatus,installSkill} from '../src/lifecycle.mjs';
+import {automaticCheck,checkUpdate,installUpdate,updatePolicy,SKILL,skillStatus,installSkill,completeInstallation,installationContract} from '../src/lifecycle.mjs';
 
 const out=v=>console.log(JSON.stringify(v,null,2));
 async function main(argv){
@@ -12,11 +12,14 @@ async function main(argv){
   if(!command||['help','--help','-h'].includes(command))return console.log(HELP);
   need(Number(process.versions.node.split('.')[0])>=22,'CAPABILITY_UNAVAILABLE','Node.js 22 or newer is required.');
   if(['version','--version','-v'].includes(command)){const {args,options}=parse(argv.slice(1),{booleans:['json']});need(!args.length,'INVALID_ARGUMENT','Unexpected arguments.');return options.json?out({ok:true,name:META.name,version:META.version,entry:path.join(ROOT,'bin/infinite-canvas.mjs')}):console.log('infinite-canvas '+META.version);}
-  if(argv.includes('--help')||argv.includes('-h')){need(['video','task','frame','browser','board','skill','update','doctor','capabilities'].includes(command),'UNKNOWN_COMMAND','Unknown command.');return console.log(HELP);}
+  if(argv.includes('--help')||argv.includes('-h')){need(['install','video','task','frame','browser','board','skill','update','doctor','capabilities'].includes(command),'UNKNOWN_COMMAND','Unknown command.');return console.log(HELP);}
+  if(command==='install'){
+    const {options:o,args}=parse(argv.slice(1),{values:['agent','path'],booleans:['json']});need(!args.length,'INVALID_ARGUMENT','Unexpected arguments.');return out(await completeInstallation(o.agent,o.path));
+  }
   if(command==='_worker'){need(argv.length===2,'INVALID_ARGUMENT','Invalid worker invocation.');const {processJob}=await import('../src/workflow.mjs');return out(await processJob(action));}
   if(command==='skill'){
     const {options:o,args}=parse(rest,{values:['agent','path'],booleans:['json']});need(!args.length,'INVALID_ARGUMENT','Unexpected arguments.');
-    if(action==='source')return out({ok:true,source:SKILL,name:'infinite-canvas-video',version:META.version,installation:{named_agents:['codex'],fallback_agent:'generic',custom_path_required:true,scope:'selected Agent only'}});
+    if(action==='source')return out({ok:true,source:SKILL,name:'infinite-canvas-video',version:META.version,installation:{named_agents:['codex'],fallback_agent:'generic',custom_path_required:true,scope:'selected Agent only',...installationContract}});
     if(action==='status')return out(await skillStatus(o.agent||'codex',o.path));
     need(['install','update'].includes(action),'UNKNOWN_COMMAND','Use skill source/status/install/update.');return out(await installSkill(o.agent||'codex',o.path));
   }

package/capabilities.json

@@ -2,7 +2,21 @@
   "schema": "infinite-canvas-capabilities",
   "schema_version": "1.0.0",
   "package": "@petercjl/infinite-canvas-cli",
-  "version": "0.1.1",
+  "version": "0.1.3",
+  "installationLifecycle": {
+    "required_components": [
+      "cli",
+      "skill"
+    ],
+    "target_scope": "current Agent only",
+    "target_resolution": "Agent resolves its own Skill directory; pass --agent and --path",
+    "install": "infinite-canvas install --agent AGENT --path SKILL_DIRECTORY --json",
+    "update": "infinite-canvas update install --yes --agent AGENT --path SKILL_DIRECTORY --json",
+    "verification": "CLI entry/version and managed Skill current=true; partial installation is incomplete",
+    "skillRequired": true,
+    "updateRequiresSkillSync": true,
+    "unresolvedTarget": "SKILL_TARGET_REQUIRED; no implicit cross-Agent installation"
+  },
   "input": {
     "required": [
       "canvas_id",
@@ -43,6 +57,12 @@
     "concurrency": "separate conversations in the same tab; queued UI submissions and canvas writes; parallel remote runs",
     "submission": "click native Send",
     "directGenerationAPI": false,
+    "mediaHelperScope": [
+      "canvas.get",
+      "canvas.add",
+      "image.upload"
+    ],
+    "requestedVideoParameters": "Convey task requirements in the prepared native Agent prompt; explicit final prompts stay unchanged; verify actual artifact metadata.",
     "recovery": "saved sessionId/runId; read-only run and history APIs",
     "model": "inherit webpage settings"
   },
@@ -65,6 +85,22 @@
     "generic:windows": "built-in Chrome discovery/startup implemented; actual host video end-to-end verification pending"
   },
   "commandContracts": {
+    "install": {
+      "options": {
+        "--agent": {
+          "type": "string",
+          "required": true
+        },
+        "--path": {
+          "type": "string"
+        },
+        "--json": {
+          "type": "boolean"
+        }
+      },
+      "sideEffects": "local-write",
+      "output": "Verified CLI and current Agent companion Skill; complete=true only when both are ready"
+    },
     "video generate": {
       "options": {
         "--canvas": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@petercjl/infinite-canvas-cli",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Drive native Infinite Canvas Agent conversations and organize reference images and results in a Frame.",
   "type": "module",
   "bin": {
@@ -23,7 +23,9 @@
   },
   "scripts": {
     "test": "node --test",
-    "check": "node --check bin/infinite-canvas.mjs && node --test"
+    "check": "node --check bin/infinite-canvas.mjs && node --test",
+    "postinstall": "node src/postinstall.mjs",
+    "check:packed": "node scripts/check-packed-install.mjs"
   },
   "dependencies": {
     "playwright-core": "1.62.1",

package/skills/infinite-canvas-video/SKILL.md

@@ -9,7 +9,7 @@ Execute an explicitly selected canvas video request with the installed `infinite
 
 ## Input and output
 
-Require a board file ID, the exact prompt and 1–20 ordered PNG, JPEG or WebP references (local paths or HTTPS URLs). Ask only for missing required inputs. Preserve the prompt and image order; 图1 means the first attached image. Inherit model settings from the webpage. An authorized generation request allows one paid native Agent submission. A planning or dry-run request allows validation only.
+Require an existing board file ID or an explicit request to create a named board, the exact prompt and 1–20 ordered PNG, JPEG or WebP references (local paths or HTTPS URLs). Ask only for missing required inputs. Preserve the prompt and image order; 图1 means the first attached image. Use the webpage model and native Agent workflow. When composing the execution prompt from a task, include the requested duration, aspect ratio, resolution and reference order in natural language. Preserve a final prompt explicitly supplied verbatim; resolve conflicts with webpage settings before submission. The absence of separate CLI flags is not evidence that the webpage Agent cannot receive these requirements. An authorized generation request allows one paid native Agent submission. A planning or dry-run request allows validation only.
 
 Return the local MP4 from `artifacts[].path`, task ID, board ID and Frame ID. Success means `status=succeeded`, a nonempty downloaded video, original reference node IDs plus one video node in the saved Frame, and verified readback. A generated video with unfinished grouping is a partial result, reported with its task ID and recovery action.
 
@@ -19,6 +19,18 @@ Resolve `infinite-canvas` from PATH. Run `version --json`, `capabilities --json`
 
 External dependencies are Node.js 22+, `playwright-core` and `image-size` (package managed), installed Google Chrome on macOS or Windows, and `sealseek-media` with image upload, canvas get/add capabilities. This Skill invokes the helper through the CLI contract; it does not compose another generation Skill. Browser authentication stays in the user's dedicated Chrome profile. Never copy cookies or tokens into a prompt, output or package.
 
+## Generation route and helper boundary
+
+Video generation in this Skill always uses `infinite-canvas video generate`: one native Agent conversation and the webpage Send button. `sealseek-media` supplies canvas and media-management operations only. Never call its video/image generation commands or load its generation Skill as an alternative workflow. A missing flag, authentication error or UI issue does not authorize changing the generation route.
+
+Use the supplied board ID. If the user explicitly requests a new board, create it through the helper's documented `canvas create --title TITLE --submit --json`, retain the returned canvas ID and return to this Skill's native video flow. The helper may require its own CLI login for canvas reads/writes and image upload; browser login and CLI authentication are separate. On `AUTH_REJECTED`, complete the helper's normal `auth login` flow and verify it before resuming the same canvas operation. Login does not authorize generation.
+
+Inspect `capabilities` and dry-run output to distinguish explicit command options, inherited webpage settings and requirements conveyed in the prompt. Report a specific unverified or unsupported requirement accurately. Verify the actual returned video's dimensions and duration when inspection is available; a prompt or local dry run alone is not proof of delivery parameters.
+
+## Installation and update
+
+Treat plugin installation/update as one operation covering the CLI and this companion Skill. Resolve the current Agent’s own Skill directory from its configuration/catalog, read `skill source --json`, then run `install --agent AGENT_NAME --path SKILL_DIRECTORY --json`. For a package upgrade use `update install --yes --agent AGENT_NAME --path SKILL_DIRECTORY --json`; even an unchanged version must reconcile the Skill. If npm was installed/upgraded directly or scripts were disabled, run the same `install` completion step afterward. Completion requires the actual CLI version plus `complete=true`, `skill.installed=true` and `skill.current=true`. Load the synchronized Skill; refresh the host session if discovery requires it. Missing targets or synchronization failure are an incomplete installation. Only the current/requested Agent is synchronized.
+
 ## Main line
 
 1. Validate required inputs and authorization. Run `doctor --json`: its browser check means Chrome is available to launch; `browser_ready` separately reports runtime readiness. Use `browser open --json` to prepare Chrome. The CLI discovers and launches the system browser itself with fixed loopback 9223 and the persistent current-user `.dianshang-chrome-profile`; a separate launcher installation is unnecessary. For a UI compatibility check use `doctor --live --canvas ID --json`. On missing login, have the user sign in in that Chrome window, then return here. The CLI uses CDP port 9223 and the dedicated ecommerce profile. Enforce the single-tab constraint below before any submission or canvas write.

package/skills/infinite-canvas-video/references/runtime.md

@@ -5,6 +5,8 @@ These commands are for the executing Agent and developers.
 Browser invariant: one board file, one tab. Reuse the existing tab for that canvas ID. Concurrent tasks use distinct native conversations and captured session/run IDs within that tab. `BOARD_SELECTION_REQUIRED` means resolve duplicate tabs before continuing; preserve the existing tasks. UI submission and canvas writes are queued per board, while remote runs can progress concurrently.
 
 ```sh
+infinite-canvas install --agent AGENT_NAME --path RESOLVED_SKILL_DIR --json
+infinite-canvas update install --yes --agent AGENT_NAME --path RESOLVED_SKILL_DIR --json
 infinite-canvas version --json
 infinite-canvas capabilities --json
 infinite-canvas doctor --json
@@ -36,3 +38,12 @@ The CLI never prints browser credentials. Changing source, a live webpage deploy
 Only Google Chrome is an external browser prerequisite. macOS discovery checks system and current-user Applications; Windows checks per-user and Program Files locations, then App Paths registry entries. `INFINITE_CANVAS_CHROME_BIN` selects an actual executable for a custom installation. No extra launcher is required. `INFINITE_CANVAS_BROWSER_BIN` remains an explicit legacy override and is verified against the same port/profile contract.
 
 `browser status` is read-only. `chrome.installed` and `available` describe installation; `running` and `ready` describe the dedicated instance. A stopped but installed Chrome passes the browser dependency check in `doctor`. `browser open` and normal video execution launch/reuse it, verify process ownership, loopback CDP 9223 and the current-user profile. On Windows this profile is under the current home directory; on macOS it is under the current home directory with the same `.dianshang-chrome-profile` name. Windows uses built-in PowerShell process/TCP queries; macOS uses bounded nonblocking system process queries. Startup is queued so concurrent jobs share the browser. `doctor --live --canvas ID` requires the running, authenticated, editable board as well.
+
+
+## Native video route and Windows text I/O
+
+`infinite-canvas video generate` sends the exact prepared prompt to the webpage Agent. Duration, aspect ratio and resolution requested in a task belong in the prepared natural-language prompt unless an explicitly selected final prompt must remain verbatim. The CLI does not advertise separate flags for these settings; preserve the native route and distinguish webpage settings from prompt-level requirements. Verify actual output metadata before reporting exact dimensions or duration.
+
+`sealseek-media` is a canvas/media helper, including board creation, reads, uploads and adding existing media. It is not this Skill's generation route. Its CLI credentials can require a separate login even while the dedicated Chrome is logged in. Resolve that dependency and return to the native flow; do not submit a second generation through the helper.
+
+On Windows, use the host's declared shell and text-encoding contract. Keep JSON intact and parse it before selecting fields; a truncated text excerpt is not the complete result. Console replacement characters are inconclusive: inspect UTF-8 bytes or hashes before changing prompts or source files. If native CLI output or redirection is decoded incorrectly, report the host encoding issue. Preserve the existing task ID and submission receipt; recovery inspects that same task and never repeats a paid Send to obtain readable output.

package/src/contracts.mjs

@@ -1,6 +1,8 @@
 import {META} from './core.mjs';
+import {installationContract} from './lifecycle.mjs';
 const s={type:'string'},b={type:'boolean'};
 export const commandContracts={
+  'install':{options:{'--agent':{...s,required:true},'--path':s,'--json':b},sideEffects:'local-write',output:'Verified CLI and current Agent companion Skill; complete=true only when both are ready'},
   'video generate':{options:{'--canvas':s,'--prompt':s,'--prompt-file':s,'--reference':{...s,repeatable:true},'--output':s,'--request-id':s,'--new':b,'--submit':b,'--dry-run':b,'--json':b},sideEffects:'local-write',externalMutation:'With --submit: import references, send native Agent conversation, import a missing video, group selected elements in a Frame.',paid:'Only native webpage sending may charge credits.'},
   'task get|wait|resume|sync':{options:{'--timeout':s,'--json':b},sideEffects:'local-write',externalMutation:'resume continues original task; sync reapplies existing video archival and grouping; never a second generation.'},
   'frame group':{options:{'--canvas':s,'--elements':s,'--frame-id':s,'--name':s,'--submit':b,'--json':b},sideEffects:'local-write',externalMutation:'With --submit: reparent existing nodes and preserve their identities.'},
@@ -13,10 +15,11 @@ export const commandContracts={
   'update auto':{options:{'--json':b},sideEffects:'local-write'}
 };
 export const manifest={schema:'infinite-canvas-capabilities',schema_version:'1.0.0',package:META.name,version:META.version,
+  installationLifecycle:{...installationContract,skillRequired:true,updateRequiresSkillSync:true,unresolvedTarget:'SKILL_TARGET_REQUIRED; no implicit cross-Agent installation'},
   input:{required:['canvas_id','prompt','references'],references:'ordered PNG/JPEG/WebP local files or HTTPS URLs'},
   output:{terminal:'local MP4 + saved Frame containing original reference nodes and one video node',fields:['task_id','status','canvas_id','session_id','run_id','frame_id','reference_element_ids','video_element_id','artifacts']},
   operations:['browser.status','browser.open','board.inspect','video.generate.native-agent','task.inspect','task.wait','task.resume','task.sync','frame.group-existing'],
-  generationTransport:{kind:'native-browser-ui',newConversationPerLogicalVideo:true,singleTabPerCanvas:true,concurrency:'separate conversations in the same tab; queued UI submissions and canvas writes; parallel remote runs',submission:'click native Send',directGenerationAPI:false,recovery:'saved sessionId/runId; read-only run and history APIs',model:'inherit webpage settings'},
+  generationTransport:{kind:'native-browser-ui',newConversationPerLogicalVideo:true,singleTabPerCanvas:true,concurrency:'separate conversations in the same tab; queued UI submissions and canvas writes; parallel remote runs',submission:'click native Send',directGenerationAPI:false,mediaHelperScope:['canvas.get','canvas.add','image.upload'],requestedVideoParameters:'Convey task requirements in the prepared native Agent prompt; explicit final prompts stay unchanged; verify actual artifact metadata.',recovery:'saved sessionId/runId; read-only run and history APIs',model:'inherit webpage settings'},
   dependencies:{node:'>=22',browser:'Installed Google Chrome; built-in macOS/Windows discovery and startup on loopback 9223 with current-user dedicated profile',canvasAPI:'sealseek-media >=0.6.7, public CLI commands',libraries:['playwright-core','image-size'],optional:['ffprobe']},
   platforms:{'codex:macos':'tested: six native Agent video tasks across two boards; one tab per board; downloads, deduplication and Frame readback verified','generic:macos':'spec-compatible, runtime untested','sealseek:macos':'spec-compatible, runtime untested','generic:windows':'built-in Chrome discovery/startup implemented; actual host video end-to-end verification pending'},
   commandContracts,
@@ -44,10 +47,11 @@ board inspect --canvas ID --json
 doctor [--live --canvas ID] --json
 capabilities --json
 version [--json]
+install --agent AGENT_NAME --path SKILL_DIRECTORY --json
 skill source --json
 skill status|install|update [--agent codex|generic|AGENT_NAME] [--path DIR] --json
 update check --json
-update install --yes [--agent AGENT_NAME --path DIR] --json
+update install --yes --agent AGENT_NAME [--path DIR] --json
 update auto on|off|status --json
 
 Runtime: Node >=22; installed Google Chrome on macOS/Windows; sealseek-media.

package/src/core.mjs

@@ -4,12 +4,10 @@ import path from 'node:path';
 import os from 'node:os';
 import crypto from 'node:crypto';
 import {fileURLToPath} from 'node:url';
-import {execFile} from 'node:child_process';
-import {promisify} from 'node:util';
+export {execute} from './process-execution.mjs';
 
 export const ROOT=path.resolve(path.dirname(fileURLToPath(import.meta.url)),'..');
 export const META=JSON.parse(await fs.readFile(path.join(ROOT,'package.json'),'utf8'));
-export const execute=promisify(execFile);
 export class Fault extends Error {constructor(code,message,details={}){super(message);this.code=code;this.details=details;}}
 export function need(value,code,message,details){if(!value)throw new Fault(code,message,details);return value;}
 export const canonical=v=>JSON.stringify(sort(v));

package/src/lifecycle.mjs

@@ -5,6 +5,13 @@ import crypto from 'node:crypto';
 import {ROOT,META,need,exists,readJSON,newJSON,newFile,replaceOwned,stateRoot,hash,mkdir,lock,execute,Fault} from './core.mjs';
 
 export const SKILL=path.join(ROOT,'skills','infinite-canvas-video');
+export const installationContract={required_components:['cli','skill'],target_scope:'current Agent only',target_resolution:'Agent resolves its own Skill directory; pass --agent and --path',install:'infinite-canvas install --agent AGENT --path SKILL_DIRECTORY --json',update:'infinite-canvas update install --yes --agent AGENT --path SKILL_DIRECTORY --json',verification:'CLI entry/version and managed Skill current=true; partial installation is incomplete'};
+export async function completeInstallation(agent,destination){
+  need(agent,'SKILL_TARGET_REQUIRED','Resolve the current Agent and its Skill directory, then run install --agent AGENT --path DIRECTORY.');
+  const skill=await installSkill(agent,destination);
+  need(skill.installed&&skill.current,'SKILL_SYNC_FAILED','CLI and companion Skill must both be ready.');
+  return {ok:true,complete:true,version:META.version,cli:{entry:path.join(ROOT,'bin/infinite-canvas.mjs'),version:META.version},skill,changed:skill.changed};
+}
 export async function treeFiles(root,prefix=''){
   const out=[];for(const e of await fs.readdir(path.join(root,prefix),{withFileTypes:true})){need(!e.isSymbolicLink(),'UNMANAGED_STATE','Skill resources must not be symbolic links.');const rel=path.posix.join(prefix,e.name);if(e.isDirectory())out.push(...await treeFiles(root,rel));else out.push(rel);}return out.sort();
 }
@@ -65,16 +72,24 @@ export async function checkUpdate({force=false,fetcher=fetch,now=Date.now()}={})
   });
 }
 export async function automaticCheck(){try{const r=await checkUpdate();if(r.update_available&&!r.cached)process.stderr.write(JSON.stringify({update_available:true,current:META.version,latest:r.latest,installation:'explicit update install --yes required'})+'\n');}catch(e){process.stderr.write(JSON.stringify({update_check:'unavailable',code:e.code||'UPDATE_BUSY'})+'\n');}}
-export async function installUpdate({yes,agent,destination}={}){
+export async function installUpdate({yes,agent,destination}={}, {check=checkUpdate,packageRoot=ROOT}={}){
   need(yes,'PERMISSION_REQUIRED','Package update requires --yes.');
-  need(!await exists(path.join(ROOT,'.git')),'SOURCE_CHECKOUT','This is a Git-owned source checkout; update it through its repository.');
-  const version=await checkUpdate({force:true});need(version.published&&version.available,'REGISTRY_UNAVAILABLE','A published version is unavailable.');
-  if(version.latest===META.version){const skill=agent?await installSkill(agent,destination):null;return {ok:true,changed:!!skill?.changed,version:META.version,skill};}
+  need(!await exists(path.join(packageRoot,'.git')),'SOURCE_CHECKOUT','This is a Git-owned source checkout; update it through its repository.');
+  need(agent,'SKILL_TARGET_REQUIRED','Package updates require the current Agent and its Skill target.');
+  const target=await skillStatus(agent,destination);need(!target.edited?.length,'LOCAL_EDITS','Preserve edited Skill files before updating.');
+  const version=await check({force:true});need(version.published&&version.available,'REGISTRY_UNAVAILABLE','A published version is unavailable.');
+  if(version.latest===META.version)return completeInstallation(agent,destination);
   const backup=path.join(stateRoot(),'package-backups',crypto.randomUUID());await mkdir(path.dirname(backup));await fs.cp(ROOT,backup,{recursive:true,errorOnExist:true,force:false});
   try{
-    await execute(process.platform==='win32'?'npm.cmd':'npm',['install','--global',META.name+'@'+version.latest],{timeout:180000,maxBuffer:1024*1024});
-    const entry=process.platform==='win32'?'infinite-canvas.cmd':'infinite-canvas';const r=JSON.parse((await execute(entry,['version','--json'],{timeout:15000})).stdout);need(r.version===version.latest,'UPDATE_VERIFY_FAILED','Installed CLI version differs.');
-    let skill;if(agent){const args=['skill','update','--agent',agent,'--json',...(destination?['--path',destination]:[])];skill=JSON.parse((await execute(entry,args,{timeout:30000})).stdout);need(skill.ok,'SKILL_SYNC_FAILED','Package upgraded but selected Skill did not synchronize.');}
-    return {ok:true,version:r.version,changed:true,backup,skill};
+    const npmCLI=await resolveNpmCLI();await execute(process.execPath,[npmCLI,'install','--global',META.name+'@'+version.latest],{timeout:180000,maxBuffer:1024*1024});
+    const entry=path.join(ROOT,'bin/infinite-canvas.mjs');const r=JSON.parse((await execute(process.execPath,[entry,'version','--json'],{timeout:15000})).stdout);need(r.version===version.latest,'UPDATE_VERIFY_FAILED','Installed CLI version differs.');
+    const args=[entry,'install','--agent',agent,'--path',target.destination,'--json'];const receipt=JSON.parse((await execute(process.execPath,args,{timeout:30000})).stdout);need(receipt.ok&&receipt.complete&&receipt.skill?.current,'SKILL_SYNC_FAILED','Package upgraded but selected Skill did not synchronize.');
+    return {...receipt,changed:true,backup};
   }catch(e){throw new Fault('UPDATE_FAILED','Update did not verify. The complete previous package is backed up.',{backup,cause:e.code||e.message});}
 }
+async function resolveNpmCLI(){
+  const candidates=[process.env.npm_execpath,path.join(path.dirname(process.execPath),'node_modules/npm/bin/npm-cli.js')];
+  for(const dir of (process.env.PATH||'').split(path.delimiter)){const bin=path.join(dir,process.platform==='win32'?'npm.cmd':'npm');try{const real=await fs.realpath(bin);candidates.push(real,path.join(path.dirname(real),'node_modules/npm/bin/npm-cli.js'));}catch{}}
+  for(const file of candidates.filter(Boolean)){if(path.basename(file)==='npm-cli.js'&&await exists(file))return file;}
+  throw new Fault('NPM_UNAVAILABLE','Cannot locate the installed npm CLI JavaScript entry.');
+}

package/src/media-cli.mjs

@@ -4,6 +4,7 @@ import {execute,newJSON,readJSON,exists,canonical,need,Fault} from './core.mjs';
 export class MediaCLI {
   constructor(){this.bin=process.env.INFINITE_CANVAS_MEDIA_BIN||'sealseek-media';}
   async call(args){
+    need(['canvas get','canvas add','image upload'].includes(args.slice(0,2).join(' ')), 'MEDIA_HELPER_SCOPE', 'The media helper only reads/writes canvas media. Video generation uses the native Infinite Canvas Agent.');
     try{const {stdout}=await execute(this.bin,[...args,'--json'],{timeout:90000,maxBuffer:32*1024*1024,env:{...process.env,SEALSEEK_MEDIA_AUTO_UPDATE:'0'}});const r=JSON.parse(stdout);need(r.ok!==false,r.error?.code||'MEDIA_API_FAILED',r.error?.message||'Canvas operation failed.');return r;}
     catch(e){if(e instanceof Fault)throw e;let r;try{r=JSON.parse(e.stdout);}catch{}throw new Fault(r?.error?.code||'MEDIA_CLI_FAILED',r?.error?.message||'sealseek-media could not complete this operation.',{command:args.slice(0,2),cause:e.code});}
   }

package/src/postinstall.mjs

@@ -0,0 +1,2 @@
+import {installationContract} from './lifecycle.mjs';
+console.log(JSON.stringify({package:'@petercjl/infinite-canvas-cli',complete:false,code:'SKILL_SETUP_REQUIRED',message:'The CLI and bundled Skill are installed in the npm package. The current Agent must install/verify the companion Skill in its own Skill directory before reporting installation or update complete.',...installationContract}));

package/src/process-execution.mjs

@@ -0,0 +1,65 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import {execFile} from 'node:child_process';
+import {promisify} from 'node:util';
+
+const run = promisify(execFile);
+const failure = (code, message) => Object.assign(new Error(message), {code});
+async function fileExists(file) {
+  try { return (await fs.stat(file)).isFile(); }
+  catch (error) { if (['ENOENT', 'ENOTDIR'].includes(error.code)) return false; throw error; }
+}
+
+/** Resolve only a declared Node package bin. Never evaluate a batch script. */
+export async function npmShimEntry(shim) {
+  const text = await fs.readFile(shim, 'utf8');
+  const name = path.basename(shim, path.extname(shim));
+  const candidates = [...text.matchAll(/%(?:dp0%|~dp0)[\\/]([^"\r\n%]+\.(?:mjs|cjs|js))/gi)]
+    .map(match => path.resolve(path.dirname(shim), ...match[1].split(/[\\/]/)));
+  for (const entry of new Set(candidates)) {
+    if (!await fileExists(entry)) continue;
+    for (let directory = path.dirname(entry);;) {
+      const manifest = path.join(directory, 'package.json');
+      if (await fileExists(manifest)) {
+        let pkg;
+        try { pkg = JSON.parse(await fs.readFile(manifest, 'utf8')); }
+        catch { break; }
+        const bin = typeof pkg.bin === 'string'
+          ? (pkg.name?.split('/').at(-1) === name ? pkg.bin : undefined)
+          : pkg.bin?.[name];
+        if (typeof bin === 'string' && path.resolve(directory, bin) === entry) return entry;
+      }
+      const parent = path.dirname(directory);
+      if (parent === directory) break;
+      directory = parent;
+    }
+  }
+  throw failure('UNSUPPORTED_COMMAND_SHIM', 'This batch command has no verifiable npm Node entry. Use a native executable or explicit Node script path.');
+}
+
+export async function resolveWindowsCommand(command, options = {}) {
+  const env = options.env ?? process.env;
+  const cwd = options.cwd ?? process.cwd();
+  const pathKey = Object.keys(env).find(key => key.toLowerCase() === 'path');
+  const directories = /[\\/]/.test(command) || path.isAbsolute(command)
+    ? [''] : (env[pathKey] ?? '').split(path.delimiter).filter(Boolean).map(value => value.replace(/^"|"$/g, ''));
+  const extension = path.extname(command).toLowerCase();
+  const suffixes = extension ? [''] : ['.com', '.exe', '.cmd', '.bat'];
+  for (const directory of directories) for (const suffix of suffixes) {
+    const file = path.resolve(cwd, directory, command + suffix);
+    if (!await fileExists(file)) continue;
+    const ext = path.extname(file).toLowerCase();
+    if (['.cmd', '.bat'].includes(ext)) return {file: process.execPath, prefix: [await npmShimEntry(file)]};
+    if (['.js', '.mjs', '.cjs'].includes(ext)) return {file: process.execPath, prefix: [file]};
+    return {file, prefix: []};
+  }
+  throw failure('ENOENT', 'Command was not found in the supplied PATH.');
+}
+
+export async function execute(command, args = [], options = {}) {
+  // Do not expose a shell execution path: prompts, filenames and URLs are data.
+  if (options.shell) throw failure('SHELL_NOT_SUPPORTED', 'Use an executable and an argument array.');
+  if (process.platform !== 'win32') return run(command, args, {...options, shell: false});
+  const launch = await resolveWindowsCommand(command, options);
+  return run(launch.file, [...launch.prefix, ...args], {...options, shell: false, windowsHide: true});
+}