@petercjl/ecom-cli 0.1.2 → 0.1.3

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/capabilities.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 1,
   "package": "@petercjl/ecom-cli",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "skills": [
     "ecom-cli"
   ],
@@ -311,7 +311,7 @@
     "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,

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.1.3",
   "description": "Agent CLI and portable Skill for Ecom browser containers",
   "type": "module",
   "license": "MPL-2.0",

package/skills/ecom-cli/SKILL.md

@@ -33,6 +33,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/package.json

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