@petercjl/ecom-cli 0.1.2 → 0.2.0

package/README.md

@@ -1,6 +1,6 @@
 # Ecom CLI
 
-Agent CLI and portable Skill for the Ecom desktop browser. The first release lists the names and stable IDs of existing containers without opening websites or switching tabs. Ecom must already be running in normal desktop mode. The browser transport currently supports macOS; Windows browser integration is not implemented.
+Agent CLI and portable Skill for the Ecom desktop browser. List existing containers, inspect a selected account’s platform/homepage/login status, and perform explicitly authorized HTTPS JSON GET operations through that container’s native session, preserving the active tab. Ecom must already be running in normal desktop mode. The browser transport currently supports macOS; Windows browser integration is not implemented.
 
 ## Install
 
@@ -14,6 +14,12 @@ The Agent needs local Node.js 22+ and terminal/file access. Installation include
 
 > 用 Ecom CLI 列出我当前的浏览器容器。
 
+> 用 Ecom CLI 查看指定账号的平台、首页和登录核验状态。
+
+> 用 Ecom CLI，通过指定账号请求我提供的只读接口地址。
+
+Provide the account name or stable container ID. For requests, supply an authorized read-only HTTPS endpoint or a trusted registered business operation. The browser permits only its explicitly enabled origin, rejects redirects/HTML and unsupported methods, and retains credentials in its native session. Native account readiness and identity checks remain authoritative. An HTTP 200 JSON response is transport success; the caller evaluates business success.
+
 Container names may identify accounts. Use a trusted Agent and share results intentionally. Installing the plugin does not authorize website operations, cookie export or account modification.
 
 ## Update

package/UPDATE.md

@@ -4,6 +4,8 @@ User prompt: “帮我更新 @petercjl/ecom-cli 和它的配套 Skill。”
 
 Resolve the currently selected Agent and exact Skill destination before mutation. Inspect the declared command contract and managed status. When current, reuse the verified installation; a same-version update repairs a missing or stale unedited Skill.
 
+Backups live outside host Skill discovery in the user's Ecom CLI state directory (`ECOM_CLI_STATE_DIR` may select an absolute alternative). Version 0.1.1/0.1.2 callers use their historical installer during handoff. After upgrading these versions, invoke `skill status` through the new entry; if `recovery.required=true`, run that entry's `skill update` for the same exact target. This relocates the selected target's legacy backup chain with byte preservation and records old/new paths in `migratedBackups`. Verify recovery is clear before refreshing host discovery. Later updaters delegate activation to the acquired version's installer.
+
 Run the selected Skill's isolated CLI with `update install --agent <name> --target <absolute-skill-directory> --yes --json`. It selects stable `latest` (or an explicit stable `--version`), acquires the candidate through npm with scripts disabled, stages the full runtime plus Skill, preserves the previous target as a uniquely named backup, activates and verifies hashes/version. Use the new receipt's entry. The optional global bootstrap package remains independently installed; it is not the selected Agent runtime. Refresh host discovery and load the resulting Skill before reporting completion.
 
 Acquisition records a target-scoped operation journal and retains candidate location, requested version and previous version. For failure, inspect the journal and `skill status` before any new attempt. A directory lock, local edits or unmanaged target stops replacement. Failed rename restores the previous directory when possible and reports recovery evidence. Retain backups and candidates until an authorized cleanup. To roll back, verify a recorded backup, preserve the current target and restore that backup as an explicit maintenance action; do not overwrite user content.

package/bin/ecom-cli.mjs

@@ -4,6 +4,6 @@ try {
   const result = await main(process.argv.slice(2));
   process.stdout.write(JSON.stringify(result) + '\n');
 } catch (error) {
-  process.stdout.write(JSON.stringify({ok:false,error:{code:error.code || 'CLI_ERROR',message:error.code ? error.message : 'Operation failed; inspect doctor and operation status',executed:error.executed ?? false,...(error.operationId ? {operationId:error.operationId} : {}),...(error.recovery ? {recovery:error.recovery} : {})}}) + '\n');
+  process.stdout.write(JSON.stringify({ok:false,error:{code:error.code || 'CLI_ERROR',message:error.code ? error.message : 'Operation failed; inspect doctor and operation status',executed:error.executed ?? false,...(error.operationId ? {operationId:error.operationId} : {}),...(error.httpStatus!==undefined?{httpStatus:error.httpStatus}:{}),...(error.recovery ? {recovery:error.recovery} : {})}}) + '\n');
   process.exitCode = error.code === 'INVALID_ARGUMENT' ? 2 : 1;
 }

package/capabilities.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 1,
   "package": "@petercjl/ecom-cli",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "skills": [
     "ecom-cli"
   ],
@@ -159,6 +159,98 @@
         }
       },
       "sideEffects": "package-and-skill-update"
+    },
+    "containers inspect": {
+      "options": {
+        "--json": {
+          "type": "boolean"
+        },
+        "--profile": {
+          "type": "string"
+        },
+        "--instance": {
+          "type": "string"
+        },
+        "--container": {
+          "type": "string",
+          "required": true,
+          "description": "Stable container ID or unique exact name"
+        }
+      },
+      "sideEffects": "local-write",
+      "authorization": "Read selected account metadata; credentials excluded and homepage credential fields redacted. Automatic update detection only.",
+      "output": {
+        "container": "id, name, platform, platformName, homeUrl, icon, color, login",
+        "login": "state, service, authenticationState, verificationSupported, checking, checkedAt, identityBound, identityConfirmed, expiry"
+      },
+      "errors": [
+        "CONTAINER_NOT_FOUND",
+        "CONTAINER_AMBIGUOUS",
+        "PROTOCOL_MISMATCH"
+      ]
+    },
+    "session request": {
+      "options": {
+        "--json": {
+          "type": "boolean"
+        },
+        "--profile": {
+          "type": "string"
+        },
+        "--instance": {
+          "type": "string"
+        },
+        "--container": {
+          "type": "string",
+          "required": true,
+          "description": "Stable container ID or unique exact name"
+        },
+        "--url": {
+          "type": "string",
+          "required": true,
+          "description": "HTTPS URL in the origin explicitly enabled by Ecom; no credentials or fragment"
+        },
+        "--method": {
+          "type": "string",
+          "default": "GET",
+          "enum": [
+            "GET"
+          ]
+        }
+      },
+      "sideEffects": "local-write",
+      "authorization": "Explicit user-authorized read operation using selected persistent container; website credentials remain native. GET is a transport restriction, not proof of business read-only semantics.",
+      "output": {
+        "instance": "Pinned Ecom identity",
+        "container": "id and name",
+        "httpStatus": "200",
+        "data": "Native-redacted JSON response",
+        "businessStatus": "not-evaluated"
+      },
+      "limits": {
+        "clientTimeoutMs": 60000,
+        "nativeNetworkTimeoutMs": 20000,
+        "nativeResponseBytes": 2097152,
+        "redirects": "rejected",
+        "html": "rejected",
+        "concurrency": "native limit 2 requests"
+      },
+      "errors": [
+        "INVALID_URL",
+        "METHOD_UNSUPPORTED",
+        "CREDENTIAL_INPUT_REJECTED",
+        "ORIGIN_NOT_ALLOWED",
+        "CONTAINER_NOT_FOUND",
+        "CONTAINER_AMBIGUOUS",
+        "SHOP_NOT_READY",
+        "SHOP_VERIFICATION_FAILED",
+        "BUSY",
+        "REQUEST_FAILED",
+        "NON_JSON_RESPONSE",
+        "INSTANCE_CHANGED",
+        "PROTOCOL_MISMATCH",
+        "OPERATION_TIMEOUT"
+      ]
     }
   },
   "transport": {
@@ -311,13 +403,13 @@
     "updateGuide": "UPDATE.md",
     "install": "Resolve current Agent exact Skill target; run skill install --agent NAME --target PATH; load Skill through host discovery.",
     "update": "Run selected Skill runtime update install --agent NAME --target PATH --yes; verify returned activated entry and refresh host discovery.",
-    "verification": "Verify CLI and Skill versions, managed hashes and current=true; host loads installed SKILL.md independently."
+    "verification": "Verify CLI and Skill versions, managed hashes, current=true and recovery.required=false; host loads installed SKILL.md independently."
   },
   "automaticUpdates": {
     "enabledByDefault": true,
     "intervalHours": 24,
     "timeoutMs": 1500,
-    "trigger": "containers list task entry",
+    "trigger": "containers list, containers inspect and session request task entry",
     "configuration": "Stable latest channel; detection only. Explicit update activates only the selected target runtime and Skill together.",
     "disable": "ECOM_CLI_UPDATE_CHECK=0",
     "recovery": "Offline checks retain installed runtime; local edit/ownership conflicts stop replacement; prior target kept as backup. Use recorded candidate and inspect target status before retrying.",
@@ -340,6 +432,17 @@
     "TARGET_REQUIRED",
     "LOCAL_EDITS",
     "UNMANAGED_TARGET",
-    "TARGET_LOCKED"
+    "TARGET_LOCKED",
+    "INVALID_URL",
+    "METHOD_UNSUPPORTED",
+    "CREDENTIAL_INPUT_REJECTED",
+    "ORIGIN_NOT_ALLOWED",
+    "CONTAINER_NOT_FOUND",
+    "CONTAINER_AMBIGUOUS",
+    "SHOP_NOT_READY",
+    "SHOP_VERIFICATION_FAILED",
+    "BUSY",
+    "REQUEST_FAILED",
+    "NON_JSON_RESPONSE"
   ]
 }

package/lib/browser.mjs

@@ -26,27 +26,85 @@ export function discover({profile,instance}={}) {
   if(candidates.length!==1) throw fail(candidates.length?'INSTANCE_AMBIGUOUS':'INSTANCE_NOT_RUNNING',candidates.length?'Multiple Ecom instances; specify --profile or --instance':'Open an Ecom build supporting this CLI in normal desktop mode');
   return candidates[0];
 }
+const instanceOf=({endpoint,channel})=>({id:endpoint.instanceId,pid:endpoint.pid,channel});
+const credentialKey=/token|cookie|csrf|password|authorization|secret|sessionid|api[-_]?key|access[-_]?key|credential/i;
+function homeUrl(value) {
+  try {
+    const url=new URL(value);if(url.protocol!=='https:')return null;
+    url.username='';url.password='';
+    for(const [key,value]of url.searchParams)if(credentialKey.test(key)||credentialKey.test(value)&&/[=%]/.test(value))url.searchParams.set(key,'[REDACTED]');
+    if(credentialKey.test(url.hash))url.hash='[REDACTED]';
+    return url.href;
+  }catch{return null;}
+}
+export function resolveContainer(items,value) {
+  if(typeof value!=='string'||!value.trim())throw fail('INVALID_ARGUMENT','Specify --container with a stable ID or unique exact name');
+  const matches=items.filter(c=>c.id===value||c.name===value);
+  if(matches.length!==1)throw fail(matches.length?'CONTAINER_AMBIGUOUS':'CONTAINER_NOT_FOUND','Select an existing stable container ID or unique exact name');
+  return matches[0];
+}
+export function validateReadUrl(value,method='GET') {
+  if(method!=='GET')throw fail('METHOD_UNSUPPORTED','This version supports explicit read-only GET operations only');
+  let url;try{url=new URL(value);}catch{throw fail('INVALID_URL','Specify an absolute HTTPS URL');}
+  if(url.protocol!=='https:'||url.username||url.password||url.hash)throw fail('INVALID_URL','HTTPS URL must have no credentials or fragment');
+  for(const [key,value]of url.searchParams)if(credentialKey.test(key)||credentialKey.test(value)&&/[=%]/.test(value))throw fail('CREDENTIAL_INPUT_REJECTED','Credentials remain in the browser; credential query parameters are not accepted');
+  return url.href;
+}
 export async function listContainers(options={}) {return readMailbox(discover(options));}
-export async function readMailbox({folder,endpoint,channel},timeoutMs=10000) {
+export async function readMailbox(connection,timeoutMs=10000) {
+  const body=await callMailbox(connection,{method:'containers.list'},timeoutMs);
+  if(!Array.isArray(body.containers)||body.containers.some(c=>typeof c.id!=='string'||typeof c.name!=='string'))throw fail('PROTOCOL_MISMATCH','Invalid container list',{operationId:body.operationId,executed:'unknown'});
+  return {...body,instance:instanceOf(connection),containers:body.containers.map(({id,name})=>({id,name}))};
+}
+export async function inspectContainer(options={}) {
+  if(!options.container)throw fail('INVALID_ARGUMENT','containers inspect requires --container');
+  return inspectInConnection(discover(options),options.container);
+}
+export async function inspectInConnection(connection,selector) {
+  const body=await callMailbox(connection,{method:'shops.list'});
+  if(!Array.isArray(body.shops)||body.shops.some(c=>typeof c.id!=='string'||typeof c.name!=='string'))throw fail('PROTOCOL_MISMATCH','Invalid account metadata',{operationId:body.operationId,executed:'unknown'});
+  const row=resolveContainer(body.shops,selector);
+  const string=x=>typeof x==='string'?x:null;
+  const container={id:row.id,name:row.name,platform:string(row.platform),platformName:string(row.customPlatformName),homeUrl:homeUrl(row.homeUrl),icon:Number.isInteger(row.icon)?row.icon:null,color:string(row.color),
+    login:{state:string(row.state)??'unconfigured',service:string(row.authentication?.service),authenticationState:string(row.authentication?.state),verificationSupported:row.verificationSupported===true,checking:row.checking===true,checkedAt:string(row.checkedAt),identityBound:!!row.identity,identityConfirmed:row.state==='ready'&&!!row.identity,expiry:row.expiry?{kind:string(row.expiry.kind),cookieExpiresAt:string(row.expiry.cookieExpiresAt)}:null}};
+  return {ok:true,schemaVersion:1,operationId:body.operationId,instance:instanceOf(connection),container};
+}
+export async function requestSession(options={}) {
+  if(!options.container||!options.url)throw fail('INVALID_ARGUMENT','session request requires --container and --url');
+  const url=validateReadUrl(options.url,options.method??'GET');
+  return requestInConnection(discover(options),{...options,url});
+}
+export async function requestInConnection(connection,options) {
+  const url=validateReadUrl(options.url,options.method??'GET');
+  if(!connection.endpoint.allowedOrigin||new URL(url).origin!==connection.endpoint.allowedOrigin)throw fail('ORIGIN_NOT_ALLOWED','URL must match the HTTPS origin explicitly enabled by this Ecom instance');
+  const listed=await readMailbox(connection);
+  const container=resolveContainer(listed.containers,options.container);
+  const body=await callMailbox(connection,{method:'session.get',containerId:container.id,url},60000);
+  if(body.containerId!==container.id||body.httpStatus!==200||!Object.hasOwn(body,'data'))throw fail('PROTOCOL_MISMATCH','Session response does not match selected container or JSON response contract',{operationId:body.operationId,executed:'unknown'});
+  return {ok:true,schemaVersion:1,operationId:body.operationId,instance:instanceOf(connection),container,request:{method:'GET',url},httpStatus:body.httpStatus,data:body.data,businessStatus:'not-evaluated'};
+}
+export async function callMailbox({folder,endpoint},payload,timeoutMs=10000) {
   privatePath(folder,true);privatePath(path.join(folder,'endpoint.json'));
   const current=JSON.parse(fs.readFileSync(path.join(folder,'endpoint.json'),'utf8'));
   if(current.pid!==endpoint.pid || current.instanceId!==endpoint.instanceId || current.authToken!==endpoint.authToken) throw fail('INSTANCE_CHANGED','Instance changed before submission; discover it again');
   const id=crypto.randomUUID(), request=path.join(folder,id+'.request.json'), temporary=path.join(folder,id+'.request.tmp'), response=path.join(folder,id+'.response.json');
   if(exists(request)||exists(response)) throw fail('OPERATION_COLLISION','Request already exists');
-  writeNew(temporary,{schemaVersion:1,instanceId:endpoint.instanceId,authToken:endpoint.authToken,method:'containers.list'});
+  writeNew(temporary,{...payload,schemaVersion:1,instanceId:endpoint.instanceId,authToken:endpoint.authToken});
   fs.renameSync(temporary,request);
   const end=Date.now()+timeoutMs;
   while(Date.now()<end) {
     if(exists(response)) {
       privatePath(response);
       const raw=fs.readFileSync(response,'utf8');
-      if(Buffer.byteLength(raw)>1024*1024) throw fail('PROTOCOL_MISMATCH','Oversized response',{operationId:id,executed:'unknown'});
+      if(Buffer.byteLength(raw)>(payload.method==='session.get'?2*1024*1024+65536:1024*1024)) throw fail('PROTOCOL_MISMATCH','Oversized response',{operationId:id,executed:'unknown'});
       let body;try{body=JSON.parse(raw);}catch{await pause(25);continue;}
       if(body.schemaVersion!==1 || body.instanceId!==endpoint.instanceId || body.operationId!==id) throw fail('PROTOCOL_MISMATCH','Response does not match this operation',{operationId:id,executed:'unknown'});
       fs.unlinkSync(response);
-      if(body.ok!==true) throw fail('BROWSER_ERROR','Browser refused read-only request',{operationId:id,executed:body.error?.executed??false});
-      if(!Array.isArray(body.containers)||body.containers.some(c=>typeof c.id!=='string'||typeof c.name!=='string')) throw fail('PROTOCOL_MISMATCH','Invalid container list',{operationId:id,executed:'unknown'});
-      return {ok:true,schemaVersion:1,operationId:id,instance:{id:endpoint.instanceId,pid:endpoint.pid,channel},containers:body.containers.map(({id,name})=>({id,name}))};
+      if(body.ok!==true) {
+        const code=/^[A-Z][A-Z0-9_]{0,63}$/.test(body.error?.code??'')?body.error.code:'BROWSER_ERROR';
+        throw fail(code,'Ecom refused the request: '+code,{operationId:id,executed:body.error?.executed??'unknown',...(Number.isInteger(body.error?.httpStatus)?{httpStatus:body.error.httpStatus}:{})});
+      }
+      return body;
     }
     await pause(25);
   }

package/lib/cli.mjs

@@ -1,7 +1,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import {root,pkg,fail} from './common.mjs';
-import {discover,listContainers} from './browser.mjs';
+import {discover,listContainers,inspectContainer,requestSession,validateReadUrl} from './browser.mjs';
 import {source,status,installSkill,checkUpdate,updateInstall} from './maintenance.mjs';
 export const capabilities=()=>JSON.parse(fs.readFileSync(path.join(root,'capabilities.json'),'utf8'));
 export function parse(argv) {
@@ -13,7 +13,7 @@ export function parse(argv) {
     const key=word.slice(2);
     if(Object.hasOwn(options,key)) throw fail('INVALID_ARGUMENT','Duplicate option '+word);
     if(['json','help','yes'].includes(key))options[key]=true;
-    else if(['agent','target','profile','instance','name','version'].includes(key)&&argv[i+1]&&!argv[i+1].startsWith('--')) options[key]=argv[++i];
+    else if(['agent','target','profile','instance','name','version','container','url','method'].includes(key)&&argv[i+1]&&!argv[i+1].startsWith('--')) options[key]=argv[++i];
     else throw fail('INVALID_ARGUMENT','Unknown option or missing value: '+word);
   }
   let command=positions.join(' ')||'help';
@@ -22,11 +22,16 @@ export function parse(argv) {
   if(!caps.commandContracts[command]) throw fail('INVALID_ARGUMENT','Unsupported command; use help --json');
   if(command!=='help')for(const key of Object.keys(options))if(!caps.commandContracts[command].options['--'+key])throw fail('INVALID_ARGUMENT','Option is not supported by this command: --'+key);
   if(options.name&&options.name!=='ecom-cli')throw fail('INVALID_ARGUMENT','Unknown Skill name');
+  if(command==='containers inspect'&&!options.container)throw fail('INVALID_ARGUMENT','containers inspect requires --container');
+  if(command==='session request') {
+    if(!options.container||!options.url)throw fail('INVALID_ARGUMENT','session request requires --container and --url');
+    options.url=validateReadUrl(options.url,options.method??'GET');
+  }
   return {command,options,requested};
 }
 export async function main(argv) {
   const {command,options,requested}=parse(argv);
-  if(command==='help')return {ok:true,package:pkg.name,version:pkg.version,usage:'ecom-cli containers list --json | skill source|status|install|update | update check|install | doctor',...capabilities(),...(capabilities().commandContracts[requested]??{})};
+  if(command==='help')return {ok:true,package:pkg.name,version:pkg.version,usage:'ecom-cli containers list|inspect | session request | skill source|status|install|update | update check|install | doctor; use help --json for required options',...capabilities(),...(capabilities().commandContracts[requested]??{})};
   if(command==='version')return {ok:true,package:pkg.name,version:pkg.version,protocolVersion:1};
   if(command==='capabilities'||command==='schema')return {ok:true,...capabilities()};
   if(command==='skill source') {const item=source();return {...capabilities(),...item,complete:true,items:[item]};}
@@ -38,9 +43,11 @@ export async function main(argv) {
     let instance,error;try{const found=discover(options);instance={id:found.endpoint.instanceId,pid:found.endpoint.pid,channel:found.channel};}catch(e){error={code:e.code,message:e.message};}
     return {ok:!error,package:pkg.name,version:pkg.version,node:process.version,platform:process.platform,transport:'private-local-mailbox',debuggingRequired:false,instance,...(error?{error}:{}),skillSource:source().path};
   }
-  if(command==='containers list') {
+  if(['containers list','containers inspect','session request'].includes(command)) {
     const update=await checkUpdate({automatic:true});
     if(update.available)process.stderr.write('Ecom CLI update available: '+update.latest+'; ask the current Agent to update the package and Skill.\n');
+    if(command==='containers inspect')return inspectContainer(options);
+    if(command==='session request')return requestSession(options);
     return listContainers(options);
   }
 }

package/lib/maintenance.mjs

@@ -5,6 +5,20 @@ import crypto from 'node:crypto';
 import {spawnSync} from 'node:child_process';
 import {root,pkg,fail,exists,tree,writeNew} from './common.mjs';
 const receiptName='.ecom-receipt.json';
+function legacyBackup(target,backup) {
+  return typeof backup==='string'&&path.dirname(backup)===path.dirname(target)&&path.basename(backup).startsWith(path.basename(target)+'.ecom-backup-')&&exists(backup);
+}
+function recoveryDirectory(target) {
+  const state=process.env.ECOM_CLI_STATE_DIR??path.join(os.homedir(),'.ecom-cli');
+  if(!path.isAbsolute(state))throw fail('INVALID_ARGUMENT','ECOM_CLI_STATE_DIR must be absolute');
+  const directory=path.join(state,'recovery');
+  if(directory===target||directory.startsWith(target+path.sep)||directory.startsWith(path.dirname(target)+path.sep))throw fail('TARGET_CONFLICT','Recovery directory must be outside the host Skill discovery directory');
+  for(let p=directory;p!==path.dirname(p);p=path.dirname(p)) {
+    if(exists(p)&&fs.lstatSync(p).isSymbolicLink()&&!(process.platform==='darwin'&&['/var','/tmp'].includes(p)&&fs.lstatSync(p).uid===0))throw fail('UNSAFE_PATH','Recovery path must use physical directories');
+  }
+  fs.mkdirSync(directory,{recursive:true,mode:0o700});
+  return directory;
+}
 export const source=(base=root)=>({ok:true,name:'ecom-cli',package:pkg.name,version:JSON.parse(fs.readFileSync(path.join(base,'package.json'),'utf8')).version,path:path.join(base,'skills/ecom-cli'),provenance:{ownership:'npm-package',registryContentVerified:false}});
 export function targetOf(options) {
   if(!options.agent || !/^[a-z][a-z0-9-]{0,63}$/.test(options.agent)) throw fail('INVALID_ARGUMENT','Supply a valid --agent name; unnamed hosts use the generic adapter');
@@ -27,18 +41,21 @@ export function status(options,base=root) {
   const canonicalCurrent=managed && Object.entries(canonical).every(([name,hash])=>files[name]===hash) && Object.keys(files).filter(n=>!n.startsWith('.runtime/')).length===Object.keys(canonical).length;
   let runtimeVersion;try{runtimeVersion=JSON.parse(fs.readFileSync(path.join(target,'.runtime/package.json'),'utf8')).version;}catch{}
   const current=!!(managed&&!edited&&canonicalCurrent&&runtimeVersion===identity.version&&receipt.version===identity.version);
-  return {...identity,target,installed,managed,current,edited:!!edited,adapter:'generic',agent:options.agent,entry:path.join(target,'.runtime/bin/ecom-cli.mjs'),verification:{verified:current,algorithm:'sha256'},recovery:{required:installed&&!current,action:edited?'Preserve local edits; reconcile them before update':'Run skill update for this exact target'},hostDiscovery:{authority:'host',verified:false},...(managed?{installedVersion:receipt.version,backup:receipt.backup??null}:{})};
+  const layoutRecovery=managed&&legacyBackup(target,receipt.backup);
+  return {...identity,target,installed,managed,current,edited:!!edited,adapter:'generic',agent:options.agent,entry:path.join(target,'.runtime/bin/ecom-cli.mjs'),verification:{verified:current,algorithm:'sha256'},recovery:{required:installed&&(!current||layoutRecovery),action:edited?'Preserve local edits; reconcile them before update':layoutRecovery?'Run skill update using this new entry to relocate legacy backups outside host discovery':'Run skill update for this exact target'},hostDiscovery:{authority:'host',verified:false},...(managed?{installedVersion:receipt.version,backup:receipt.backup??null,migratedBackups:receipt.migratedBackups??[]}:{})};
 }
 export function installSkill(options,base=root) {
   const before=status(options,base), target=before.target;
-  if(before.current) return {...before,changed:false};
+  if(before.current&&!before.recovery.required) return {...before,changed:false};
   if(before.installed&&!before.managed) throw fail('UNMANAGED_TARGET','Existing Skill is user-owned; choose a fresh destination');
   if(before.edited) throw fail('LOCAL_EDITS','Managed Skill has local edits; preserve and reconcile them before update');
   const parent=path.dirname(target);fs.mkdirSync(parent,{recursive:true});
+  const recovery=recoveryDirectory(target);
   const lock=target+'.ecom-lock';let fd;
   try {fd=fs.openSync(lock,'wx',0o600);}catch{throw fail('TARGET_LOCKED','Another maintenance operation holds the target lock');}
-  const operationId=crypto.randomUUID(), staging=target+'.ecom-stage-'+operationId;
-  const backup=before.installed?target+'.ecom-backup-'+operationId:null;
+  const operationId=crypto.randomUUID(), staging=path.join(parent,'.'+path.basename(target)+'.ecom-stage-'+operationId);
+  const backup=before.installed?path.join(recovery,operationId):null;
+  const migratedBackups=[];
   let activated=false;
   try {
     tree(base);
@@ -48,18 +65,30 @@ export function installSkill(options,base=root) {
       fs.cpSync(path.join(base,name),path.join(runtime,name),{recursive:true,errorOnExist:true,force:false});
     }
     const manifest=source(base);
-    writeNew(path.join(staging,receiptName),{schemaVersion:1,package:pkg.name,name:'ecom-cli',version:manifest.version,target,agent:options.agent,operationId,backup,files:tree(staging)});
     // Recheck edits after staging, before replacement.
     const again=status(options,base);
     if(again.edited || again.installed!==before.installed) throw fail('TARGET_CHANGED','Skill changed during preparation');
+    let legacy=before.backup;
+    while(legacyBackup(target,legacy)) {
+      const info=fs.lstatSync(legacy);
+      if(!info.isDirectory()||info.isSymbolicLink())throw fail('UNSAFE_PATH','Legacy backup must be a physical directory');
+      const record=JSON.parse(fs.readFileSync(path.join(legacy,receiptName),'utf8'));
+      if(record.package!==pkg.name||record.target!==target||record.agent!==options.agent)throw fail('UNMANAGED_TARGET','Legacy backup ownership does not match selected target');
+      const destination=path.join(recovery,'legacy-'+crypto.randomUUID());
+      fs.renameSync(legacy,destination);
+      migratedBackups.push({from:legacy,to:destination,version:record.version});
+      legacy=record.backup;
+    }
+    writeNew(path.join(staging,receiptName),{schemaVersion:1,package:pkg.name,name:'ecom-cli',version:manifest.version,target,agent:options.agent,operationId,backup,migratedBackups,files:tree(staging)});
     if(backup) fs.renameSync(target,backup);
     try {fs.renameSync(staging,target);activated=true;}catch(e){if(backup&&!exists(target))fs.renameSync(backup,target);throw e;}
     const result=status(options,base);
     if(!result.current) throw fail('VERIFY_FAILED','Installation integrity verification failed');
     return {...result,changed:true,operationId,backup,completion:{cli:true,skill:true,hostDiscovery:false},remainingActions:['Load installed SKILL.md through the current Agent discovery mechanism']};
   } catch(e) {
+    if(!activated)for(const moved of migratedBackups.toReversed())if(!exists(moved.from)&&exists(moved.to)){try{fs.renameSync(moved.to,moved.from);}catch{/* Preserve both recorded identities for manual recovery. */}}
     if(!activated&&exists(staging)) fs.rmSync(staging,{recursive:true});
-    throw fail(e.code||'INSTALL_FAILED',e.code?e.message:'Skill activation failed; the previous installation is preserved',{operationId,recovery:{backup,target,activated,action:'Inspect skill status before retrying'}});
+    throw fail(e.code||'INSTALL_FAILED',e.code?e.message:'Skill activation failed; the previous installation is preserved',{operationId,recovery:{backup,target,activated,migratedBackups,action:'Inspect skill status before retrying'}});
   } finally {fs.closeSync(fd);fs.unlinkSync(lock);}
 }
 const cacheRoot=()=>path.join(os.homedir(),'.cache','ecom-cli');
@@ -97,6 +126,10 @@ export async function updateInstall(options) {
   if(acquired.status!==0) throw fail('PACKAGE_ACQUISITION_FAILED','Candidate installation failed; existing runtime and Skill retained',{operationId,recovery:{journal,stage:'acquisition',action:'Inspect candidate and operation record before retrying'}});
   const candidate=path.join(directory,'node_modules/@petercjl/ecom-cli');
   if(source(candidate).version!==selected) throw fail('VERSION_MISMATCH','Acquired candidate version differs from requested version',{operationId,recovery:{journal}});
-  const result=installSkill(options,candidate);
+  // The acquired version owns its installer semantics; historical callers may
+  // require one new-entry skill update to reconcile their legacy backup layout.
+  const handoff=spawnSync(process.execPath,[path.join(candidate,'bin/ecom-cli.mjs'),'skill','update','--agent',options.agent,'--target',before.target,'--json'],{encoding:'utf8',timeout:30000});
+  let result;try{result=JSON.parse(handoff.stdout);}catch{}
+  if(handoff.status!==0||!result?.ok)throw fail('CANDIDATE_ACTIVATION_FAILED','New-version installer failed; inspect target status and recorded candidate',{operationId,recovery:{journal,stage:'activation',candidate,backup:result?.error?.recovery?.backup,action:'Use the recorded candidate entry to inspect status and reconcile the exact target'}});
   return {...result,operationId,journal,selectedVersion:selected,bootstrapRetained:true,activation:'Use the entry in this receipt; the selected Skill contains its own CLI runtime'};
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@petercjl/ecom-cli",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "description": "Agent CLI and portable Skill for Ecom browser containers",
   "type": "module",
   "license": "MPL-2.0",

package/skills/ecom-cli/SKILL.md

@@ -1,23 +1,29 @@
 ---
 name: ecom-cli
-description: List isolated account containers in the running Ecom desktop browser, inspect its CLI connection, or install/update the Ecom CLI and companion Skill for the current Agent. Use when the user asks for Ecom browser containers or Ecom CLI setup. Website business queries and browser mutations are outside the first release.
+description: List and inspect account containers in the running Ecom browser, send explicitly authorized read-only HTTPS JSON requests using a selected container session, diagnose connections, or install/update the Ecom CLI and companion Skill. Use for Ecom account metadata and native-session API access; application business logic stays with the calling workflow.
 ---
 
 # Ecom CLI
 
 ## Input → strategy → output
 
-Input is a request to list Ecom containers, diagnose the connection, or maintain this plugin for the current Agent. The current Agent needs local command execution, file access and Node.js 22+. Output is a verified container list (stable ID and name), connection diagnosis, or an installation receipt with a separate host discovery check. Container names may identify accounts; disclose only within the user's request.
+Input is an Ecom container listing/detail request, an authorized read-only endpoint plus target container, a connection diagnosis, or selected-Agent maintenance intent. The current Agent needs local command execution, file access and Node.js 22+. Output is a container list, projected account metadata, native-redacted JSON response with pinned target identity, connection diagnosis, or installation receipt with a separate host discovery check. Container names may identify accounts; disclose only within the user's request.
 
 ## Main line
 
 1. Resolve this installed Skill's directory from the host's actual discovery record. Its bundled CLI is `.runtime/bin/ecom-cli.mjs` relative to that directory. Invoke it through an available Node.js 22+ runtime, checking host-managed runtime configuration before PATH. Canonical npm source has no `.runtime`; complete its managed installation using the packaged INSTALL.md first.
 2. Read [capabilities.json](capabilities.json) and use [the generic adapter](adapters/generic.json) for any host with the required capabilities. Probe the actual entry with `version --json` and `capabilities --json`; use only declared commands and flags. A missing runtime or required capability ends with CAPABILITY_UNAVAILABLE; do not modify adapters during a task.
-3. For normal listing, invoke the resolved entry with `containers list --json`. Ecom must already be running in normal desktop mode. Discovery validates the live executable and protected endpoint. With multiple instances, ask which instance/profile the user intends and pass the declared selector. Never choose an account from a name guess.
-4. Require `ok=true`, protocol version 1, a concrete instance identity and container ID/name pairs. Return the names and stable IDs as requested. This operation reads containers without navigating pages or changing the active tab.
+3. Choose the supported operation from the live schema. Use `containers list --json` to locate targets, then use a stable ID or unique exact name. Ecom must already be running in normal desktop mode; discovery validates its executable and protected endpoint. Multiple instances require an explicit intended instance/profile rather than a guess.
+4. For account details, run `containers inspect --container VALUE --json`. Report platform, saved homepage and timestamped service-login status. `identityBound` records a saved binding; `identityConfirmed` requires the native ready state. Cookie expiry is a reference, not proof of current service access. Account names are labels and do not grant or remove capabilities. Credential-like homepage fields are redacted.
+5. For a session request, require an explicit authorized read-only endpoint from the user or a trusted business capability’s registered operation. Business selection, endpoint semantics, date/metrics and interpretation belong to that caller. Run `session request --container VALUE --url HTTPS_URL --method GET --json`. GET alone does not prove an endpoint has no side effects; resolve unclear endpoint intent before submission. The CLI pins one instance and container across discovery and execution. Credentials remain native; header/body/credential inputs, redirects and HTML are unsupported. The enabled origin is controlled by Ecom, not expanded by the CLI.
+6. Require `ok=true`, protocol version 1, operation ID and matching instance/container IDs. For requests, require the JSON response contract and distinguish HTTP success from business success: `businessStatus=not-evaluated` requires the caller’s platform-specific check. Preserve structured errors and executed status. These operations do not navigate or activate tabs.
 
 ## Diagnosis and recovery
 
+- SHOP_NOT_READY: inspect this exact account. Complete login and platform-identity verification through its Ecom account management page; a cookie expiry or account name does not satisfy readiness. If the native adapter cannot verify identity, report that gap and stop the data request. Return to step 5 only after readiness is established.
+- SHOP_VERIFICATION_FAILED: stop; the browser’s pre-request identity check failed. Preserve the selected target and report the failure.
+- ORIGIN_NOT_ALLOWED, CREDENTIAL_INPUT_REJECTED, METHOD_UNSUPPORTED or INVALID_URL: correct the intended input within the declared contract; do not broaden browser permissions.
+- REQUEST_FAILED or NON_JSON_RESPONSE: preserve HTTP/operation/execute fields; handle login, permission or challenge through the original container. Do not infer business success.
 - INSTANCE_NOT_RUNNING: run `doctor --json`. Ask the user to open a compatible Ecom version. Do not enable remote debugging or substitute another browser.
 - INSTANCE_AMBIGUOUS: obtain the intended instance or profile, then return to step 3.
 - INSTANCE_CHANGED: no request was submitted; rediscover before returning to step 3.
@@ -33,6 +39,8 @@ Resolve the current Agent's exact Skill destination from host configuration; use
 
 For an authorized package update, invoke the installed entry's `update install --agent NAME --target PATH --yes --json`. It acquires stable latest and activates CLI plus Skill together. Use the new entry from its receipt, verify CLI/Skill versions and SHA-256 `current=true`, then refresh and load this exact Skill through host discovery. Preserve receipts and backups. Local edits and unmanaged destinations require reconciliation before replacement; other Agent installations remain untouched. Automatic task-entry checks only notify; offline checks retain the installed runtime.
 
+Always inspect `skill status` using the newly activated entry. If `recovery.required=true` identifies legacy backups in host discovery, run the new entry's `skill update` for that same target and verify recovery clears. Backups are preserved outside the Skill discovery directory; migration records identify both old and new locations.
+
 ## QA and evolution
 
 Success requires actual structured CLI output, not inferred browser state. Maintenance additionally requires integrity plus native host discovery. Runtime checks do not claim clean-context regression or other Agents/OS tests. Add new commands to the browser capability layer, CLI schema, tests and this canonical Skill together in an authorized development cycle. This simple deterministic Skill uses direct internalization of user-confirmed scope and verified CLI contracts; private knowledge bases are not runtime dependencies.

package/skills/ecom-cli/capabilities.json

@@ -24,13 +24,17 @@
       "output_fields": [
         "ok",
         "containers",
+        "container",
         "instance",
+        "httpStatus",
+        "data",
+        "businessStatus",
         "error"
       ],
       "side_effects": {
         "external_mutation": false,
         "may_cost_money": false,
-        "authorization": "Read-only browser request authorized by user; selected-target writes require installation/update intent"
+        "authorization": "Container metadata reads and explicitly authorized read-only HTTPS operations; website Set-Cookie may refresh the native session. Selected-target maintenance requires installation/update intent."
       },
       "errors": [
         "CAPABILITY_UNAVAILABLE",

package/skills/ecom-cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@petercjl/ecom-cli",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "private": true,
   "type": "module"
 }