@petercjl/infinite-canvas-cli 0.1.1 → 0.1.2

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.2",
+  "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",
@@ -65,6 +79,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.2",
   "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

@@ -19,6 +19,10 @@ 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.
 
+## 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

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,6 +15,7 @@ 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'],
@@ -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/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});
+}