@whyvix/remote 0.3.17 → 0.3.18

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@whyvix/remote",
-  "version": "0.3.17",
+  "version": "0.3.18",
   "private": false,
   "type": "module",
   "files": [
@@ -13,20 +13,22 @@
     "native/win32-x64/whyvix-gui-helper.exe",
     "native/gui-window-action-helper-manifest.json",
     "native/win32-x64/whyvix-gui-window-action-helper.exe",
-    "README.md"
+    "README.md",
+    "npm-shrinkwrap.json"
   ],
   "scripts": {
     "gateway": "node services/gateway/src/index.js",
     "agent": "node packages/agent/src/index.js",
     "test:r0": "node scripts/r0-test.js",
-    "test": "npm run test:r0 && npm run test:r4-desktop-connect && npm run test:r1-r2 && npm run test:r3-r5 && npm run test:r10-gui-window-focus && npm run test:r10-documents && npm run test:r10-observability",
-    "check": "node --check packages/protocol/src/index.js && node --check packages/agent/src/security.js && node --check packages/agent/src/process-manager.js && node --check packages/agent/src/precision-document-manager.js && node --check packages/agent/src/tools.js && node --check packages/agent/src/agent.js && node --check packages/agent/src/index.js && node --check packages/cli/index.js && node --check services/gateway/src/device-registry.js && node --check services/gateway/src/gateway.js && node --check services/gateway/src/index.js && node --check services/gateway/src/authorization/sqlite-desktop-connect-repository.js && node --check services/gateway/src/web/desktop-connect-api.js && node --check services/gateway/src/production-authority.js && node --check services/gateway/src/production-runtime.js && node --check services/gateway/src/web/identity-web-server.js && node --check scripts/r4-desktop-connect-authorization-test.js && node --check scripts/r4-desktop-connect-transaction-test.js && node --check scripts/r4-desktop-connect-api-test.js && node --check scripts/r0-test.js && node --check scripts/r1-r2-test.js && node --check scripts/r3-r5-test.js",
+    "test": "npm run test:r0 && npm run test:r4-desktop-connect && npm run test:r1-r2 && npm run test:r3-r5 && npm run test:r10-gui-window-focus && npm run test:r10-documents && npm run test:r10-observability && npm run test:r10-self-update",
+    "check": "node --check packages/protocol/src/index.js && node --check packages/agent/src/security.js && node --check packages/agent/src/process-manager.js && node --check packages/agent/src/self-update-manager.js && node --check packages/agent/src/update-supervisor.js && node --check packages/agent/src/update-lifecycle.js && node --check packages/agent/src/update-activation-plan.js && node --check packages/agent/src/update-bootstrap-executor.js && node --check packages/agent/src/update-supervisor-host.js && node --check packages/agent/src/update-archive-policy.js && node --check packages/agent/src/update-persistence.js && node --check packages/cli/update-supervisor.js && node --check packages/agent/src/precision-document-manager.js && node --check packages/agent/src/tools.js && node --check packages/agent/src/agent.js && node --check packages/agent/src/index.js && node --check packages/cli/index.js && node --check services/gateway/src/device-registry.js && node --check services/gateway/src/gateway.js && node --check services/gateway/src/index.js && node --check services/gateway/src/authorization/sqlite-desktop-connect-repository.js && node --check services/gateway/src/web/desktop-connect-api.js && node --check services/gateway/src/production-authority.js && node --check services/gateway/src/production-runtime.js && node --check services/gateway/src/web/identity-web-server.js && node --check scripts/r4-desktop-connect-authorization-test.js && node --check scripts/r4-desktop-connect-transaction-test.js && node --check scripts/r4-desktop-connect-api-test.js && node --check scripts/r0-test.js && node --check scripts/r1-r2-test.js && node --check scripts/r3-r5-test.js",
     "test:r4-desktop-connect": "node scripts/r4-desktop-connect-authorization-test.js && node scripts/r4-desktop-connect-transaction-test.js && node scripts/r4-desktop-connect-api-test.js && node scripts/r4-desktop-connect-browser-test.js",
     "test:r1-r2": "node scripts/r1-r2-test.js",
     "test:r3-r5": "node scripts/r3-r5-test.js",
     "test:r10-gui-window-focus": "node scripts/r10-gui-window-action-contract-test.js && node scripts/r10-gui-window-action-source-test.js && node scripts/r10-gui-window-action-agent-capability-test.js && node scripts/r10-gui-window-action-authorization-test.js && node scripts/r10-gui-window-action-loader-test.js && node scripts/r10-gui-window-action-mcp-schema-test.js && node scripts/r10-gui-window-action-cli-wiring-test.js && node scripts/r10-deployment-certify-authorization-test.js && node scripts/r10-deployment-certify-protocol-test.js && node scripts/r10-deployment-activation-response-test.js",
     "test:r10-documents": "node scripts/r10-precision-document-inspect-test.js && node scripts/r10-precision-document-compare-test.js && node scripts/r10-precision-docx-mutation-test.js && node scripts/r10-precision-xlsx-mutation-test.js && node scripts/r10-precision-pptx-mutation-test.js",
-    "test:r10-observability": "node scripts/r10-write-preview-test.js && node scripts/r10-cli-presentation-test.js && node scripts/r10-usage-metering-test.js"
+    "test:r10-observability": "node scripts/r10-write-preview-test.js && node scripts/r10-cli-presentation-test.js && node scripts/r10-usage-metering-test.js",
+    "test:r10-self-update": "node scripts/r10-self-update-manager-test.js && node scripts/r10-update-supervisor-test.js && node scripts/r10-update-lifecycle-test.js && node scripts/r10-update-activation-plan-test.js && node scripts/r10-update-bootstrap-executor-test.js && node scripts/r10-update-supervisor-host-test.js && node scripts/r10-update-archive-policy-test.js && node scripts/r10-update-persistence-test.js"
   },
   "dependencies": {
     "@modelcontextprotocol/ext-apps": "^2.0.0",

package/packages/agent/src/agent.js

@@ -4,6 +4,7 @@ import WebSocket from "ws";
 import { envelope, parseMessage, TYPES } from "../../protocol/src/index.js";
 import { createSecurity } from "./security.js";
 import { ProcessManager } from "./process-manager.js";
+import { SelfUpdateManager } from "./self-update-manager.js";
 import { RemoteExecutionManager } from "./remote-execution-manager.js";
 import { DeploymentManager } from "./deployment-manager.js";
 import { GuiManager } from "./gui-manager.js";
@@ -37,13 +38,14 @@ export function createAgent({gatewayUrl="ws://127.0.0.1:8787",deviceId=randomUUI
   let ws=null,reconnectTimer=null,stopped=false,generation=0;
   const security=createSecurity({token,workspaces,audit});
   const processManager=new ProcessManager({audit});
+  const selfUpdateManager=new SelfUpdateManager({audit});
   const remoteExecutionManager=new RemoteExecutionManager({targets:remoteTargets,audit});
   const deploymentManager=new DeploymentManager({profiles:deploymentProfiles,security,audit,transferArtifact:deploymentTransferArtifact});
   const guiManager=new GuiManager({backend:guiBackend,audit});
   const guiWindowActionManager=new GuiWindowActionManager({backend:guiWindowActionBackend,audit});
   const precisionDocumentManager=new PrecisionDocumentManager({security,audit});
   const advertisedCapabilities=[...new Set([...capabilities,...(guiManager.capabilities().available?["gui.observe"]:[]),...(guiWindowActionManager.capabilities().available?["gui.window.focus"]:[]),...(precisionDocumentManager.capabilities().available?["document.precision.inspect","document.precision.compare","document.precision.mutate.docx","document.precision.mutate.xlsx","document.precision.mutate.pptx"]:[])])].sort();
-  const executeTool=createToolExecutor({security,processManager,remoteExecutionManager,deploymentManager,guiManager,guiWindowActionManager,precisionDocumentManager});
+  const executeTool=createToolExecutor({security,processManager,selfUpdateManager,remoteExecutionManager,deploymentManager,guiManager,guiWindowActionManager,precisionDocumentManager});
   function scheduleReconnect(reason){
     if(stopped||!reconnect||reconnectTimer)return;
     log("[agent:reconnect-scheduled]",reason,reconnectMs);

package/packages/agent/src/self-update-manager.js

@@ -0,0 +1,83 @@
+import os from "node:os";
+import path from "node:path";
+import crypto from "node:crypto";
+import { gunzipSync } from "node:zlib";
+import { mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { spawn, execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { readUpdateTarEntries, validateUpdateArchiveEntries } from "./update-archive-policy.js";
+const execFileAsync=promisify(execFile);
+
+const PACKAGE_NAME="@whyvix/remote";
+const REGISTRY="https://registry.npmjs.org";
+const VERSION=/^(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)(?:-[0-9A-Za-z.-]+)?$/;
+
+function fail(code,message){throw Object.assign(new Error(message),{code});}
+function safeVersion(value){const version=String(value||"").trim();if(!VERSION.test(version))fail("UPDATE_VERSION_INVALID","Explicit semver version is required");return version;}
+function digest(buffer){return crypto.createHash("sha512").update(buffer).digest("base64");}
+
+export class SelfUpdateManager{
+  constructor({fetchFn=fetch,spawnFn=spawn,nodeExecPath=process.execPath,homeDir=os.homedir(),registry=REGISTRY,audit=()=>{}}={}){
+    if(registry!==REGISTRY)fail("UPDATE_REGISTRY_DENIED","Only the official npm registry is allowed");
+    this.fetchFn=fetchFn;this.spawnFn=spawnFn;this.nodeExecPath=nodeExecPath;this.homeDir=homeDir;this.registry=registry;this.audit=audit;
+  }
+  updateRoot(version){return path.join(this.homeDir,".whyvix-remote","updates",safeVersion(version));}
+  async prepare({version}={}){
+    version=safeVersion(version);
+    const encoded=encodeURIComponent(PACKAGE_NAME);
+    const metadataResponse=await this.fetchFn(`${this.registry}/${encoded}/${version}`,{headers:{accept:"application/json"}});
+    if(!metadataResponse.ok)fail("UPDATE_METADATA_FAILED",`Registry metadata request failed: ${metadataResponse.status}`);
+    const metadata=await metadataResponse.json();
+    if(metadata?.name!==PACKAGE_NAME||metadata?.version!==version)fail("UPDATE_METADATA_INVALID","Registry metadata identity mismatch");
+    const tarball=String(metadata?.dist?.tarball||"");
+    const integrity=String(metadata?.dist?.integrity||"");
+    if(!tarball.startsWith(`${this.registry}/`)||!integrity.startsWith("sha512-"))fail("UPDATE_METADATA_INVALID","Registry tarball authority or integrity is invalid");
+    const response=await this.fetchFn(tarball,{headers:{accept:"application/octet-stream"}});
+    if(!response.ok)fail("UPDATE_DOWNLOAD_FAILED",`Package download failed: ${response.status}`);
+    const bytes=Buffer.from(await response.arrayBuffer());
+    const actual=`sha512-${digest(bytes)}`;if(actual!==integrity)fail("UPDATE_INTEGRITY_FAILED","Downloaded package integrity mismatch");
+    const root=this.updateRoot(version);
+    await mkdir(root,{recursive:true,mode:0o700});
+    const artifact=path.join(root,`whyvix-remote-${version}.tgz`);
+    await writeFile(artifact,bytes,{flag:"w",mode:0o600});
+    await writeFile(path.join(root,"manifest.json"),JSON.stringify({package:PACKAGE_NAME,version,registry:this.registry,integrity,artifact},null,2),{encoding:"utf8",flag:"w",mode:0o600});
+    this.audit({event:"update.prepared",version,bytes:bytes.length});
+    return{package:PACKAGE_NAME,version,artifact,integrity,bytes:bytes.length};
+  }
+  async verifyPrepared({version}={}){
+    version=safeVersion(version);const root=this.updateRoot(version);
+    const manifest=JSON.parse(await readFile(path.join(root,"manifest.json"),"utf8"));
+    if(manifest.package!==PACKAGE_NAME||manifest.version!==version||manifest.registry!==this.registry||!String(manifest.integrity).startsWith("sha512-"))fail("UPDATE_PREPARED_INVALID","Prepared update manifest is invalid");
+    const expectedArtifact=path.join(root,`whyvix-remote-${version}.tgz`);
+    if(path.resolve(manifest.artifact)!==path.resolve(expectedArtifact))fail("UPDATE_PREPARED_INVALID","Prepared artifact path is invalid");
+    const bytes=await readFile(expectedArtifact);if(`sha512-${digest(bytes)}`!==manifest.integrity)fail("UPDATE_INTEGRITY_FAILED","Prepared package integrity mismatch");
+    return{package:PACKAGE_NAME,version,artifact:expectedArtifact,integrity:manifest.integrity,bytes:bytes.length};
+  }
+  async materialize({version}={}){
+    const prepared=await this.verifyPrepared({version});version=prepared.version;
+    const root=this.updateRoot(version),extractRoot=path.join(root,"extracted");
+    validateUpdateArchiveEntries(readUpdateTarEntries(gunzipSync(await readFile(prepared.artifact))));
+    await rm(extractRoot,{recursive:true,force:true});await mkdir(extractRoot,{recursive:true,mode:0o700});
+    try{await execFileAsync("tar",["-xzf",prepared.artifact,"-C",extractRoot],{windowsHide:true,maxBuffer:1024*1024});}
+    catch{await rm(extractRoot,{recursive:true,force:true});fail("UPDATE_EXTRACT_FAILED","Verified package could not be extracted");}
+    const packageRoot=path.join(extractRoot,"package"),meta=JSON.parse(await readFile(path.join(packageRoot,"package.json"),"utf8"));
+    if(meta?.name!==PACKAGE_NAME||meta?.version!==version||meta?.bin?.["whyvix-remote"]!=="packages/cli/index.js"){await rm(extractRoot,{recursive:true,force:true});fail("UPDATE_PACKAGE_INVALID","Extracted package identity or launcher is invalid");}
+    const launcher=path.join(packageRoot,"packages","cli","index.js");await readFile(launcher);
+    this.audit({event:"update.materialized",version});return{...prepared,packageRoot,launcher};
+  }
+  launchReplacement({version,cwd=process.cwd()}={}){
+    version=safeVersion(version);const root=this.updateRoot(version),launcher=path.join(root,"extracted","package","packages","cli","index.js"),readyFile=path.join(root,"registered.json");
+    const child=this.spawnFn(this.nodeExecPath,[launcher,"remote"],{cwd,windowsHide:true,shell:false,detached:false,stdio:["ignore","ignore","ignore"],env:{...process.env}});
+    child.unref?.();this.audit({event:"update.replacement_started",version,pid:child.pid});return{version,pid:child.pid,readyFile};
+  }
+  async waitForRegistration({version,candidate,planFingerprint,timeoutMs=15000,pollMs=200}={}){
+    version=safeVersion(version);const readyFile=path.join(this.updateRoot(version),"registered.json"),deadline=Date.now()+Math.max(1000,Math.min(Number(timeoutMs)||15000,60000));
+    const expectedPid=Number(candidate?.pid);if(!Number.isInteger(expectedPid)||expectedPid<=0)fail("UPDATE_PID_INVALID","Candidate pid is required for registration proof");
+    if(!String(planFingerprint||"").trim())fail("UPDATE_PLAN_INVALID","Activation plan fingerprint is required for registration proof");
+    while(Date.now()<deadline){try{const ready=JSON.parse(await readFile(readyFile,"utf8"));if(ready.version===version&&ready.deviceId&&ready.pid===expectedPid&&ready.planFingerprint===planFingerprint)return ready;}catch{}await new Promise(r=>setTimeout(r,Math.max(50,Math.min(Number(pollMs)||200,1000))));}
+    fail("UPDATE_REGISTRATION_TIMEOUT","Replacement did not confirm trusted gateway registration before timeout");
+  }
+  async discard({version}={}){version=safeVersion(version);await rm(this.updateRoot(version),{recursive:true,force:true});this.audit({event:"update.discarded",version});return{version,discarded:true};}
+}
+export const SELF_UPDATE_PACKAGE=PACKAGE_NAME;
+export const SELF_UPDATE_REGISTRY=REGISTRY;

package/packages/agent/src/tools.js

@@ -7,7 +7,7 @@ import { execFile } from "node:child_process";
 import { promisify } from "node:util";
 const execFileAsync=promisify(execFile);
 
-export function createToolExecutor({ security, processManager, remoteExecutionManager, deploymentManager, guiManager, guiWindowActionManager, precisionDocumentManager }) {
+export function createToolExecutor({ security, processManager, selfUpdateManager, remoteExecutionManager, deploymentManager, guiManager, guiWindowActionManager, precisionDocumentManager }) {
   const binaryTransferManager=new BinaryTransferManager({security,audit:(entry)=>security.audit(entry)});
   const pendingDeployments=new Map();
   const pendingDeploymentTtlMs=10*60*1000;
@@ -127,6 +127,9 @@ export function createToolExecutor({ security, processManager, remoteExecutionMa
     if(tool==="remote.output"){if(!remoteExecutionManager)throw Object.assign(new Error("Remote execution is not configured"),{code:"REMOTE_JOB_NOT_FOUND"});return remoteExecutionManager.output(args);}
     if(tool==="remote.input"){if(!remoteExecutionManager)throw Object.assign(new Error("Remote execution is not configured"),{code:"REMOTE_JOB_NOT_FOUND"});return remoteExecutionManager.input(args);}
     if(tool==="remote.stop"){if(!remoteExecutionManager)throw Object.assign(new Error("Remote execution is not configured"),{code:"REMOTE_JOB_NOT_FOUND"});return remoteExecutionManager.stop(args);}
+    if(tool==="agent.update_prepare"){if(!selfUpdateManager)throw Object.assign(new Error("Self-update is not configured"),{code:"UPDATE_NOT_AVAILABLE"});const prepared=await selfUpdateManager.prepare(args);const materialized=await selfUpdateManager.materialize(args);return{package:prepared.package,version:prepared.version,integrity:prepared.integrity,bytes:prepared.bytes,materialized:Boolean(materialized.launcher)};}
+    if(tool==="agent.update_verify"){if(!selfUpdateManager)throw Object.assign(new Error("Self-update is not configured"),{code:"UPDATE_NOT_AVAILABLE"});return selfUpdateManager.verifyPrepared(args);}
+    if(tool==="agent.update_discard"){if(!selfUpdateManager)throw Object.assign(new Error("Self-update is not configured"),{code:"UPDATE_NOT_AVAILABLE"});return selfUpdateManager.discard(args);}
     if(tool==="process.discover")return processManager.discover(args);
     if(tool==="process.start"){const cwd=security.resolveFilesystemPath(args.cwd);return processManager.start({...args,cwd});}
     if(tool==="process.output")return processManager.output(args);

package/packages/agent/src/update-activation-plan.js

@@ -0,0 +1,41 @@
+import path from "node:path";
+import crypto from "node:crypto";
+import { readJsonStrict, writeJsonAtomic } from "./update-persistence.js";
+
+function fail(code,message){throw Object.assign(new Error(message),{code});}
+function semver(value){const v=String(value||"").trim();if(!/^(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)(?:-[0-9A-Za-z.-]+)?$/.test(v))fail("UPDATE_VERSION_INVALID","Explicit semver version is required");return v;}
+function canonical(value){return JSON.stringify(value,Object.keys(value).sort());}
+
+export class UpdateActivationPlan{
+  constructor({manager,homeDir,now=()=>Date.now(),audit=()=>{}}={}){
+    if(!manager)fail("UPDATE_MANAGER_REQUIRED","Self-update manager is required");
+    this.manager=manager;this.homeDir=homeDir||manager.homeDir;this.now=now;this.audit=audit;
+  }
+  planPath(){return path.join(this.homeDir,".whyvix-remote","activation-plan.json");}
+  async create({currentVersion,targetVersion,deviceId}={}){
+    currentVersion=semver(currentVersion);targetVersion=semver(targetVersion);
+    if(currentVersion===targetVersion)fail("UPDATE_TARGET_SAME","Target version must differ from current version");
+    if(!String(deviceId||"").trim())fail("UPDATE_DEVICE_INVALID","Device id is required");
+    const current=await this.manager.verifyPrepared({version:currentVersion});
+    const target=await this.manager.verifyPrepared({version:targetVersion});
+    const plan={schema:1,deviceId:String(deviceId),currentVersion,targetVersion,currentIntegrity:current.integrity,targetIntegrity:target.integrity,createdAt:this.now()};
+    const fingerprint=crypto.createHash("sha256").update(canonical(plan)).digest("hex");
+    const envelope={...plan,fingerprint};
+    await writeJsonAtomic(this.planPath(),envelope);
+    this.audit({event:"update.activation_plan_created",currentVersion,targetVersion,deviceId:String(deviceId),fingerprint});
+    return envelope;
+  }
+  async verify(){
+    const envelope=await readJsonStrict(this.planPath(),{missing:null,invalidCode:"UPDATE_PLAN_INVALID"});
+    if(!envelope)fail("UPDATE_PLAN_INVALID","Activation plan is missing");
+    const {fingerprint,...plan}=envelope;
+    if(plan.schema!==1||!String(plan.deviceId||"").trim())fail("UPDATE_PLAN_INVALID","Activation plan identity is invalid");
+    plan.currentVersion=semver(plan.currentVersion);plan.targetVersion=semver(plan.targetVersion);
+    const expected=crypto.createHash("sha256").update(canonical(plan)).digest("hex");
+    if(fingerprint!==expected)fail("UPDATE_PLAN_INVALID","Activation plan fingerprint mismatch");
+    const current=await this.manager.verifyPrepared({version:plan.currentVersion});
+    const target=await this.manager.verifyPrepared({version:plan.targetVersion});
+    if(current.integrity!==plan.currentIntegrity||target.integrity!==plan.targetIntegrity)fail("UPDATE_PLAN_INVALID","Prepared package integrity no longer matches activation plan");
+    return envelope;
+  }
+}

package/packages/agent/src/update-archive-policy.js

@@ -0,0 +1,35 @@
+function fail(code,message){throw Object.assign(new Error(message),{code});}
+
+export function validateUpdateArchiveEntries(entries){
+  if(!Array.isArray(entries)||entries.length<1)fail("UPDATE_ARCHIVE_INVALID","Archive entry list is required");
+  for(const raw of entries){
+    const name=String(raw?.name||"").replaceAll("\\","/");
+    const type=String(raw?.type||"file").toLowerCase();
+    if(!name||name.startsWith("/")||/^[A-Za-z]:\//.test(name)||name.startsWith("//"))fail("UPDATE_ARCHIVE_PATH_DENIED","Archive contains an absolute path");
+    const parts=name.split("/").filter(Boolean);
+    if(parts.includes("..")||parts[0]!=="package")fail("UPDATE_ARCHIVE_PATH_DENIED","Archive entry escapes package root");
+    if(type==="symlink"||type==="hardlink"||type==="link")fail("UPDATE_ARCHIVE_LINK_DENIED","Archive links are not allowed");
+  }
+  return{valid:true,count:entries.length};
+}
+
+export function readUpdateTarEntries(buffer){
+  if(!Buffer.isBuffer(buffer)||buffer.length<512)fail("UPDATE_ARCHIVE_INVALID","Tar archive bytes are required");
+  const entries=[];
+  for(let offset=0;offset+512<=buffer.length;){
+    const header=buffer.subarray(offset,offset+512);
+    if(header.every(byte=>byte===0))break;
+    const text=(start,length)=>header.subarray(start,start+length).toString("utf8").replace(/\0.*$/s,"");
+    const name=text(0,100),prefix=text(345,155),full=prefix?`${prefix}/${name}`:name;
+    const sizeText=text(124,12).trim();const size=sizeText?Number.parseInt(sizeText,8):0;
+    if(!Number.isFinite(size)||size<0)fail("UPDATE_ARCHIVE_INVALID","Tar entry size is invalid");
+    const typeFlag=String.fromCharCode(header[156]||48);
+    if(!["0","1","2","5","\u0000"].includes(typeFlag))fail("UPDATE_ARCHIVE_TYPE_DENIED",`Unsupported tar entry type: ${typeFlag}`);
+    const type=typeFlag==="2"?"symlink":typeFlag==="1"?"hardlink":typeFlag==="5"?"directory":"file";
+    entries.push({name:full,type});
+    offset+=512+Math.ceil(size/512)*512;
+  }
+  if(entries.length<1)fail("UPDATE_ARCHIVE_INVALID","Tar archive has no entries");
+  return entries;
+}
+

package/packages/agent/src/update-bootstrap-executor.js

@@ -0,0 +1,32 @@
+import path from "node:path";
+import { rm } from "node:fs/promises";
+import { UpdateLifecycle } from "./update-lifecycle.js";
+import { acquireExclusiveLock } from "./update-persistence.js";
+
+function fail(code,message){throw Object.assign(new Error(message),{code});}
+
+export class UpdateBootstrapExecutor{
+  constructor({manager,activationPlan,supervisor,waitStable,audit=()=>{}}={}){
+    if(!manager||!activationPlan||!supervisor||!waitStable)fail("UPDATE_BOOTSTRAP_INVALID","Complete bootstrap dependencies are required");
+    Object.assign(this,{manager,activationPlan,supervisor,waitStable,audit});
+  }
+  async execute(){
+    const lockPath=path.join(this.manager.homeDir,".whyvix-remote","update-activation.lock");
+    const release=await acquireExclusiveLock(lockPath);
+    try{
+    const plan=await this.activationPlan.verify();
+    const readyFile=path.join(this.manager.updateRoot(plan.targetVersion),"registered.json");
+    await rm(readyFile,{force:true});
+    const lifecycle=new UpdateLifecycle({
+      supervisor:this.supervisor,
+      startCandidate:({version})=>this.manager.launchReplacement({version}),
+      waitRegistered:({version,candidate})=>this.manager.waitForRegistration({version,candidate,planFingerprint:plan.fingerprint}),
+      waitStable:args=>this.waitStable(args),
+      startRollback:({version})=>this.manager.launchReplacement({version}),
+      audit:this.audit
+    });
+    this.audit({event:"update.bootstrap_started",currentVersion:plan.currentVersion,targetVersion:plan.targetVersion,deviceId:plan.deviceId});
+    return await lifecycle.activate({currentVersion:plan.currentVersion,targetVersion:plan.targetVersion});
+    }finally{await release();}
+  }
+}

package/packages/agent/src/update-lifecycle.js

@@ -0,0 +1,31 @@
+function fail(code,message,cause){const error=Object.assign(new Error(message),{code});if(cause)error.cause=cause;throw error;}
+
+export class UpdateLifecycle{
+  constructor({supervisor,startCandidate,waitRegistered,waitStable,startRollback,audit=()=>{}}={}){
+    if(!supervisor||!startCandidate||!waitRegistered||!waitStable||!startRollback)fail("UPDATE_LIFECYCLE_INVALID","Complete lifecycle dependencies are required");
+    Object.assign(this,{supervisor,startCandidate,waitRegistered,waitStable,startRollback,audit});
+  }
+  async rollback(cause){
+    const plan=await this.supervisor.rollbackPlan();
+    const result=await this.startRollback(plan);
+    this.audit({event:"update.rollback_started",version:plan.version,reason:cause?.code||"UPDATE_FAILED"});
+    return result;
+  }
+  async activate({currentVersion,targetVersion}={}){
+    await this.supervisor.arm({currentVersion,targetVersion});
+    let candidate;
+    try{
+      candidate=await this.startCandidate({version:targetVersion});
+      if(!candidate||!Number.isInteger(candidate.pid)||candidate.pid<=0)fail("UPDATE_CANDIDATE_START_FAILED","Candidate did not return a valid pid");
+      await this.supervisor.markCandidateStarted({targetVersion,pid:candidate.pid});
+      const registered=await this.waitRegistered({version:targetVersion,candidate});
+      await this.supervisor.markRegistered({targetVersion,deviceId:registered?.deviceId});
+      const stable=await this.waitStable({version:targetVersion,candidate,registered});
+      if(stable!==true)fail("UPDATE_CANDIDATE_UNSTABLE","Candidate did not survive the stability window");
+      return await this.supervisor.commit({targetVersion});
+    }catch(error){
+      try{await this.rollback(error);}catch(rollbackError){fail("UPDATE_ROLLBACK_FAILED","Candidate activation failed and rollback could not be started",rollbackError);}
+      throw error;
+    }
+  }
+}

package/packages/agent/src/update-persistence.js

@@ -0,0 +1,34 @@
+import path from "node:path";
+import crypto from "node:crypto";
+import { mkdir, open, readFile, rename, rm, writeFile } from "node:fs/promises";
+
+function fail(code,message,cause){throw Object.assign(new Error(message),{code,cause});}
+
+export async function readJsonStrict(file,{missing=null,invalidCode="UPDATE_STATE_INVALID"}={}){
+  try{return JSON.parse(await readFile(file,"utf8"));}
+  catch(error){
+    if(error?.code==="ENOENT")return missing;
+    if(error instanceof SyntaxError)fail(invalidCode,"Persisted update JSON is malformed",error);
+    throw error;
+  }
+}
+
+export async function writeJsonAtomic(file,value){
+  const dir=path.dirname(file);await mkdir(dir,{recursive:true,mode:0o700});
+  const tmp=path.join(dir,`.${path.basename(file)}.${process.pid}.${crypto.randomBytes(8).toString("hex")}.tmp`);
+  try{
+    await writeFile(tmp,JSON.stringify(value,null,2),{encoding:"utf8",mode:0o600,flag:"wx"});
+    await rename(tmp,file);
+  }finally{await rm(tmp,{force:true}).catch(()=>{});}
+  return value;
+}
+
+export async function acquireExclusiveLock(file,{busyCode="UPDATE_BUSY"}={}){
+  await mkdir(path.dirname(file),{recursive:true,mode:0o700});
+  let handle;
+  try{handle=await open(file,"wx",0o600);}
+  catch(error){if(error?.code==="EEXIST")fail(busyCode,"Another update activation already holds the lock",error);throw error;}
+  await handle.writeFile(JSON.stringify({pid:process.pid,createdAt:Date.now()}),"utf8");
+  let released=false;
+  return async()=>{if(released)return;released=true;await handle.close();await rm(file,{force:true});};
+}

package/packages/agent/src/update-supervisor-host.js

@@ -0,0 +1,35 @@
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { spawn } from "node:child_process";
+import { SelfUpdateManager } from "./self-update-manager.js";
+import { UpdateSupervisor } from "./update-supervisor.js";
+import { UpdateActivationPlan } from "./update-activation-plan.js";
+import { UpdateBootstrapExecutor } from "./update-bootstrap-executor.js";
+
+const sleep=ms=>new Promise(resolve=>setTimeout(resolve,ms));
+function fail(code,message){throw Object.assign(new Error(message),{code});}
+
+export async function runUpdateSupervisorHost({homeDir,nodeExecPath=process.execPath,spawnFn=spawn,graceMs=15000,pollMs=250,audit=()=>{}}={}){
+  const manager=new SelfUpdateManager({homeDir,nodeExecPath,spawnFn,audit});
+  const activationPlan=new UpdateActivationPlan({manager,homeDir,audit});
+  const supervisor=new UpdateSupervisor({manager,homeDir,audit});
+  const waitStable=async({candidate})=>{
+    const pid=Number(candidate?.pid);
+    if(!Number.isInteger(pid)||pid<=0)fail("UPDATE_PID_INVALID","Candidate pid is required for stability monitoring");
+    const deadline=Date.now()+Math.max(1000,Math.min(Number(graceMs)||15000,60000));
+    while(Date.now()<deadline){
+      try{process.kill(pid,0);}catch{return false;}
+      await sleep(Math.max(50,Math.min(Number(pollMs)||250,1000)));
+    }
+    return true;
+  };
+  return new UpdateBootstrapExecutor({manager,activationPlan,supervisor,waitStable,audit}).execute();
+}
+
+export function launchDetachedUpdateSupervisorHost({nodeExecPath=process.execPath,spawnFn=spawn}={}){
+  const hostScript=path.resolve(path.dirname(fileURLToPath(import.meta.url)),"../../cli/update-supervisor.js");
+  const child=spawnFn(nodeExecPath,[hostScript],{cwd:path.dirname(hostScript),windowsHide:true,shell:false,detached:true,stdio:"ignore"});
+  if(!Number.isInteger(child?.pid)||child.pid<=0)fail("UPDATE_SUPERVISOR_START_FAILED","Detached update supervisor did not return a valid pid");
+  child.unref?.();
+  return{pid:child.pid};
+}

package/packages/agent/src/update-supervisor.js

@@ -0,0 +1,52 @@
+import path from "node:path";
+import { readJsonStrict, writeJsonAtomic } from "./update-persistence.js";
+
+function fail(code,message){throw Object.assign(new Error(message),{code});}
+function version(value){const v=String(value||"").trim();if(!/^(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)(?:-[0-9A-Za-z.-]+)?$/.test(v))fail("UPDATE_VERSION_INVALID","Explicit semver version is required");return v;}
+
+export class UpdateSupervisor{
+  constructor({manager,homeDir,audit=()=>{},now=()=>Date.now()}={}){
+    if(!manager)fail("UPDATE_MANAGER_REQUIRED","Self-update manager is required");
+    this.manager=manager;this.homeDir=homeDir||manager.homeDir;this.audit=audit;this.now=now;
+  }
+  statePath(){return path.join(this.homeDir,".whyvix-remote","update-state.json");}
+  async readState(){return readJsonStrict(this.statePath(),{missing:null,invalidCode:"UPDATE_STATE_INVALID"});}
+  async writeState(state){return writeJsonAtomic(this.statePath(),state);}
+  async arm({currentVersion,targetVersion}={}){
+    currentVersion=version(currentVersion);targetVersion=version(targetVersion);
+    if(currentVersion===targetVersion)fail("UPDATE_TARGET_SAME","Target version must differ from current version");
+    await this.manager.verifyPrepared({version:currentVersion});
+    await this.manager.verifyPrepared({version:targetVersion});
+    const state={status:"armed",currentVersion,targetVersion,armedAt:this.now()};
+    await this.writeState(state);this.audit({event:"update.armed",currentVersion,targetVersion});return state;
+  }
+  async markCandidateStarted({targetVersion,pid}={}){
+    targetVersion=version(targetVersion);const state=await this.readState();
+    if(state?.status!=="armed"||state.targetVersion!==targetVersion)fail("UPDATE_NOT_ARMED","Update activation is not armed for this target");
+    if(!Number.isInteger(pid)||pid<=0)fail("UPDATE_PID_INVALID","Candidate pid is invalid");
+    const next={...state,status:"candidate_started",candidatePid:pid,startedAt:this.now()};
+    await this.writeState(next);return next;
+  }
+  async markRegistered({targetVersion,deviceId}={}){
+    targetVersion=version(targetVersion);const state=await this.readState();
+    if(state?.status!=="candidate_started"||state.targetVersion!==targetVersion)fail("UPDATE_STATE_INVALID","Candidate was not started for this target");
+    if(!String(deviceId||"").trim())fail("UPDATE_DEVICE_INVALID","Registered device id is required");
+    const next={...state,status:"registered",deviceId:String(deviceId),registeredAt:this.now()};
+    await this.writeState(next);this.audit({event:"update.registered",targetVersion,deviceId:String(deviceId)});return next;
+  }
+  async commit({targetVersion}={}){
+    targetVersion=version(targetVersion);const state=await this.readState();
+    if(state?.status!=="registered"||state.targetVersion!==targetVersion)fail("UPDATE_NOT_REGISTERED","Candidate registration must be proven before commit");
+    const next={...state,status:"committed",activeVersion:targetVersion,lastKnownGood:state.currentVersion,committedAt:this.now()};
+    await this.writeState(next);this.audit({event:"update.committed",targetVersion,lastKnownGood:state.currentVersion});return next;
+  }
+  async rollbackPlan(){
+    const state=await this.readState();
+    if(!state?.currentVersion)fail("UPDATE_ROLLBACK_UNAVAILABLE","No rollback version is recorded");
+    await this.manager.verifyPrepared({version:state.currentVersion});
+    const reason=state.status||"unknown";
+    await this.writeState({...state,status:"rollback_started",rollbackVersion:state.currentVersion,rollbackStartedAt:this.now()});
+    this.audit({event:"update.rollback_planned",version:state.currentVersion,reason});
+    return{version:state.currentVersion,reason};
+  }
+}

package/packages/cli/index.js

@@ -2,7 +2,7 @@
 import os from "node:os";
 import crypto from "node:crypto";
 import { mkdir, readFile, writeFile } from "node:fs/promises";
-import { join, dirname } from "node:path";
+import { join, dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { createAgent } from "../agent/src/agent.js";
 import { loadDeploymentProfiles } from "../agent/src/deployment-profile-loader.js";
@@ -88,7 +88,17 @@ const agent=createAgent({
   },
   log:(event,tool,meta)=>presenter.log(event,tool,meta),
   errorLog:(event,tool,code,message)=>presenter.error(event,tool,code,message),
-  onRegistered:({authorizedAccount})=>presenter.registered(authorizedAccount)
+  onRegistered:async({authorizedAccount})=>{
+    presenter.registered(authorizedAccount);
+    const version=String(packageMeta.version||"unknown");
+    const managedPackageRoot=resolve(credentialDir,"updates",version,"extracted","package");
+    if(resolve(packageRoot)===managedPackageRoot){
+      const plan=JSON.parse(await readFile(join(credentialDir,"activation-plan.json"),"utf8"));
+      if(plan?.targetVersion!==version||plan?.deviceId!==deviceId||!String(plan?.fingerprint||"").trim())throw new Error("Managed update activation plan does not match this candidate");
+      const readyFile=join(credentialDir,"updates",version,"registered.json");
+      await writeFile(readyFile,JSON.stringify({deviceId,version,pid:process.pid,planFingerprint:plan.fingerprint,registeredAt:new Date().toISOString()}),{encoding:"utf8",flag:"wx",mode:0o600});
+    }
+  }
 });
 let shuttingDown=false;
 async function shutdown(){