@petercjl/ecom-cli 0.3.1 → 0.3.2

package/lib/browser.mjs

@@ -12,14 +12,22 @@ export function processProfile(executable,command) {
   if(executable.endsWith('/Ecom.app/Contents/MacOS/Ecom'))return path.join(os.homedir(),'Library','Application Support','Ecom','Ecom');
   return null;
 }
-export function discover({profile,instance}={}) {
+export function discover({profile,instance}={}, {allowFixedDevCdp=false}={}) {
   if(process.platform!=='darwin') throw fail('PLATFORM_UNSUPPORTED','Browser transport currently supports macOS; no debugging fallback is available');
   const candidates=[];
   for(const line of ps(['-axo','pid=,uid=,comm=']).split('\n')) {
     const m=line.trim().match(/^(\d+)\s+(\d+)\s+(.+)$/);
     if(!m || Number(m[2])!==process.getuid() || !/\/(Ecom Dev|Ecom)\.app\/Contents\/MacOS\/\1$/.test(m[3])) continue;
+    const channel=m[3].includes('/Ecom Dev.app/')?'dev':'stable';
+    if (!profile && !instance && channel !== 'stable') continue;
     let command; try {command=ps(['-ww','-p',m[1],'-o','command=']).trim();}catch{continue;}
-    if(/--(?:remote-debugging|headless|enable-automation)/.test(command)) continue;
+    const debugFlags = command.match(/(?:^| )--remote-debugging[^ ]*/g) ?? [];
+    if (/--(?:headless|enable-automation)/.test(command)) continue;
+    if (debugFlags.length) {
+      const fixedPort = debugFlags[0].match(/^ --remote-debugging-port=([1-9][0-9]{0,4})$/);
+      if (!allowFixedDevCdp || channel !== 'dev' || debugFlags.length !== 1 ||
+          !fixedPort || Number(fixedPort[1]) > 65535) continue;
+    }
     const selected=processProfile(m[3],command);
     if(!selected || !path.isAbsolute(selected) || (profile && path.resolve(profile)!==path.resolve(selected))) continue;
     const folder=path.join(selected,'Default','.ecom-native-cli'), file=path.join(folder,'endpoint.json');
@@ -28,9 +36,9 @@ export function discover({profile,instance}={}) {
     const endpoint=JSON.parse(fs.readFileSync(file,'utf8'));
     if(endpoint.product!=='Ecom' || endpoint.schemaVersion!==1 || endpoint.pid!==Number(m[1]) || endpoint.executable!==m[3] || endpoint.userDataDir!==selected || !/^[\da-f-]{36}$/.test(endpoint.instanceId) || typeof endpoint.authToken!=='string') continue;
     if(instance && endpoint.instanceId!==instance) continue;
-    candidates.push({folder,endpoint,channel:m[3].includes('/Ecom Dev.app/')?'dev':'stable'});
+    candidates.push({folder,endpoint,channel});
   }
-  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');
+  if(candidates.length!==1) throw fail(candidates.length?'INSTANCE_AMBIGUOUS':'INSTANCE_NOT_RUNNING',candidates.length?'Multiple Ecom instances; specify --profile or --instance':(profile||instance?'Open the selected Ecom instance in normal desktop mode':'Open the stable Ecom app, or explicitly select Ecom Dev with --profile or --instance'));
   return candidates[0];
 }
 const instanceOf=({endpoint,channel})=>({id:endpoint.instanceId,pid:endpoint.pid,channel});
@@ -76,6 +84,41 @@ export async function inspectInConnection(connection,selector) {
     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 openContainerHome(options) {
+  const connection = discover(options, {allowFixedDevCdp: true});
+  const listed = await readMailbox(connection);
+  const container = resolveContainer(listed.containers, options.container);
+  const body = await callMailbox(connection, {method:'shops.open', containerId:container.id, service:'home'});
+  const requestedUrl = homeUrl(body.requestedUrl);
+  if (body.containerId !== container.id || body.service !== 'home' ||
+      body.navigation !== 'started' || !requestedUrl) {
+    throw fail('PROTOCOL_MISMATCH', 'Unexpected container homepage response',
+      {operationId:body.operationId, executed:'unknown'});
+  }
+  return {ok:true, schemaVersion:1, operationId:body.operationId, instance:instanceOf(connection),
+    container, service:'home', status:'started', requestedUrl};
+}
+
+export async function qianniuLoginStep(action, options) {
+  const connection=discover(options);
+  const listed=await readMailbox(connection);
+  const container=resolveContainer(listed.containers,options.container);
+  const body=await callMailbox(connection,{method:'shops.'+action,containerId:container.id,
+    ...(action==='open'?{service:'qianniu'}:{})});
+  const statuses={
+    open:['started'],
+    'login-status':['page-unavailable','loading','login-page','backend-page','ambiguous'],
+    'submit-login':['wrong-page','manual-verification-required','password-form-unavailable',
+      'credentials-not-filled','already-submitted','clicked'],
+  };
+  const status=action==='open'?body.navigation:body.status;
+  if(body.containerId!==container.id||!statuses[action].includes(status)||
+      (action==='open'&&(body.service!=='qianniu'||body.requestedUrl!=='https://myseller.taobao.com/'))) {
+    throw fail('PROTOCOL_MISMATCH','Unexpected Qianniu response',{operationId:body.operationId,executed:'unknown'});
+  }
+  return {ok:true,schemaVersion:1,operationId:body.operationId,instance:instanceOf(connection),
+    container,service:'qianniu',status};
+}
 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');
@@ -90,25 +133,39 @@ export async function requestInConnection(connection,options) {
   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 registeredReadInConnection(connection,options,operation,params,registryHash) {
+export async function registeredReadInConnection(connection,options,operation,params,registryHash,route,signedRoute) {
   if(connection.endpoint.businessReadProtocol!==1)throw fail('BROWSER_UPGRADE_REQUIRED','This operation needs an Ecom build with native business read protocol 1');
-  if(connection.endpoint.businessReadRegistryHash!==registryHash)throw fail('BROWSER_UPGRADE_REQUIRED','Browser and CLI business catalogs differ; update them together');
+  const useRoute=connection.endpoint.businessRouteProtocol===1&&route!==undefined;
+  if(signedRoute&&connection.endpoint.signedBusinessRouteProtocol!==1)throw fail('BROWSER_UPGRADE_REQUIRED','This read requires signed route protocol 1');
+  if(!signedRoute&&!useRoute&&connection.endpoint.businessReadRegistryHash!==registryHash)throw fail('BROWSER_UPGRADE_REQUIRED','Browser and CLI business catalogs differ; update them together');
   const listed=await readMailbox(connection),container=resolveContainer(listed.containers,options.container);
-  const body=await callMailbox(connection,{method:'business.read',containerId:container.id,operation,params},75000);
+  const body=await callMailbox(connection,{method:'business.read',containerId:container.id,operation,params,...(useRoute?{route}:{}),...(signedRoute?{signedRoute}:{})},75000);
   if(body.containerId!==container.id||body.businessOperation!==operation||body.httpStatus!==200||!Object.hasOwn(body,'data'))throw fail('PROTOCOL_MISMATCH','Registered response differs from the pinned container or operation',{operationId:body.operationId,executed:'unknown'});
-  return {ok:true,schemaVersion:1,operationId:body.operationId,instance:instanceOf(connection),container,operation,httpStatus:body.httpStatus,data:body.data,...(Array.isArray(body.dataFlows)&&body.dataFlows.length?{dataFlows:body.dataFlows}:{}),transport:'native-business-read',identityBinding:'container-bound-account',registryHash};
+  return {ok:true,schemaVersion:1,operationId:body.operationId,instance:instanceOf(connection),container,operation,httpStatus:body.httpStatus,data:body.data,...(Array.isArray(body.dataFlows)&&body.dataFlows.length?{dataFlows:body.dataFlows}:{}),transport:'native-business-read',identityBinding:'container-bound-account',...(signedRoute?{signedBusinessRouteProtocol:1}:useRoute?{businessRouteProtocol:1}:{registryHash})};
 }
-export async function openBusinessPageInConnection(connection,options,operation,entryUrl,registryHash) {
-  if(connection.endpoint.businessPageOpenProtocol!==1||connection.endpoint.businessReadRegistryHash!==registryHash)throw fail('BROWSER_UPGRADE_REQUIRED','Update Ecom to the matching registered-page navigation capability');
+export async function openBusinessPageInConnection(connection,options,operation,entryUrl,registryHash,route) {
+  const useRoute=connection.endpoint.businessRouteProtocol===1&&route!==undefined;
+  if(connection.endpoint.businessPageOpenProtocol!==1||(!useRoute&&connection.endpoint.businessReadRegistryHash!==registryHash))throw fail('BROWSER_UPGRADE_REQUIRED','Update Ecom to the matching registered-page navigation capability');
   const listed=await readMailbox(connection),container=resolveContainer(listed.containers,options.container);
   const background=!options.foreground;
-  const body=await callMailbox(connection,{method:'shops.open',containerId:container.id,businessOperation:operation,background,reuse:background});
+  const body=await callMailbox(connection,{method:'shops.open',containerId:container.id,businessOperation:operation,background,reuse:background,...(useRoute?{route}:{})});
   if(body.containerId!==container.id||!['started','reused'].includes(body.navigation)||body.requestedUrl!==entryUrl)throw fail('PROTOCOL_MISMATCH','Navigation target differs from the registered container or entry page',{operationId:body.operationId,executed:'unknown'});
-  return {ok:true,schemaVersion:1,operationId:body.operationId,instance:instanceOf(connection),container,operation,requestedUrl:body.requestedUrl,navigation:body.navigation,background,authentication:'not-verified'};
+  let restoration;
+  if(body.restoration?.status!==undefined) {
+    const r=body.restoration.restore;
+    if(!['navigation-started','navigation-queued'].includes(body.restoration.status)||!r||r.containerId!==container.id||!Number.isInteger(r.tabId)||r.tabId<=0||typeof r.requestId!=='string'||!r.requestId||!['queued','loading','foreground-loading','ready','failed'].includes(r.phase))
+      throw fail('PROTOCOL_MISMATCH','Page restoration differs from the selected container',{operationId:body.operationId,executed:'unknown'});
+    restoration={status:body.restoration.status,restore:{requestId:r.requestId,tabId:r.tabId,containerId:r.containerId,phase:r.phase}};
+  }
+  return {ok:true,schemaVersion:1,operationId:body.operationId,instance:instanceOf(connection),container,operation,requestedUrl:body.requestedUrl,navigation:body.navigation,background,authentication:'not-verified',...(restoration?{restoration}:{})};
 }
 function safeDiagnostics(value) {
   if(!value||typeof value!=='object')return undefined;
   const result={};
+  if(Array.isArray(value.tabProtection))result.tabProtection=value.tabProtection.slice(0,60).filter(r=>
+    r&&['mvp','discard','freeze','connected-freeze'].includes(r.source)&&
+    ((Number.isInteger(r.code)&&r.code>=0&&r.code<=30)||(typeof r.code==='string'&&/^[A-Z_]{1,40}$/.test(r.code)))
+  ).map(r=>({source:r.source,code:r.code}));
   if(typeof value.phase==='string'&&/^[a-z-]{1,32}$/.test(value.phase))result.phase=value.phase;
   if(Number.isInteger(value.netError)&&value.netError<=0&&value.netError>=-9999)result.netError=value.netError;
   if(['json','html','text','none'].includes(value.bodyKind))result.bodyKind=value.bodyKind;

package/lib/cdp.mjs

@@ -0,0 +1,79 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import {fail} from './common.mjs';
+
+export async function cdpCommand(command, options) {
+  if (!options.profile || !path.isAbsolute(options.profile)) {
+    throw fail('INVALID_ARGUMENT', 'Specify the absolute Ecom Dev --profile path');
+  }
+  let endpoint;
+  try {
+    const file = path.join(options.profile, 'DevToolsActivePort');
+    const info = await fs.lstat(file);
+    if (!info.isFile() || info.size > 256) throw new Error();
+    endpoint = (await fs.readFile(file, 'utf8')).trim().split(/\r?\n/);
+  } catch {
+    throw fail('CDP_NOT_ENABLED', 'No CDP endpoint in this profile. Start Ecom Dev in CDP mode.');
+  }
+  const [rawPort, browserPath] = endpoint;
+  const port = Number(rawPort);
+  if (!/^\d{1,5}$/.test(rawPort) || port < 1 || port > 65535 ||
+      !/^\/devtools\/browser\/[\da-f-]+$/i.test(browserPath ?? '')) {
+    throw fail('CDP_ENDPOINT_INVALID', 'Invalid Ecom CDP endpoint record');
+  }
+  const host = '127.0.0.1:' + port;
+  const httpUrl = 'http://' + host;
+  const webSocketDebuggerUrl = 'ws://' + host + browserPath;
+  async function read(route) {
+    try {
+      const response = await fetch(httpUrl + route, {redirect: 'error', signal: AbortSignal.timeout(3000)});
+      if (!response.ok) throw new Error();
+      return await response.json();
+    } catch {
+      throw fail('CDP_UNREACHABLE', 'Ecom CDP did not respond on loopback');
+    }
+  }
+  const version = await read('/json/version');
+  if (version.webSocketDebuggerUrl !== webSocketDebuggerUrl) {
+    throw fail('CDP_ENDPOINT_INVALID', 'The live CDP endpoint does not match the selected profile');
+  }
+  if (command === 'endpoint') return {ok: true, httpUrl, webSocketDebuggerUrl};
+  if (command === 'tabs') return {ok: true, targets: await read('/json/list')};
+  const method = options['cdp-method'];
+  const target = options['cdp-target'];
+  if (!/^[A-Za-z]+\.[A-Za-z][A-Za-z0-9]*$/.test(method ?? '') ||
+      (target && !/^[\da-f]+$/i.test(target))) {
+    throw fail('INVALID_ARGUMENT', 'Specify a CDP Domain.method and optionally a target ID from cdp tabs');
+  }
+  let params;
+  try {
+    params = JSON.parse(options['params-json'] ?? '{}');
+    if (!params || typeof params !== 'object' || Array.isArray(params)) throw new Error();
+  } catch {
+    throw fail('INVALID_ARGUMENT', 'CDP parameters must be a JSON object');
+  }
+  const url = target ? 'ws://' + host + '/devtools/page/' + target : webSocketDebuggerUrl;
+  const socket = new WebSocket(url);
+  try {
+    const result = await new Promise((resolve, reject) => {
+      const deadline = setTimeout(() => reject(fail('CDP_TIMEOUT', 'No CDP reply; execution outcome is unknown')), 15000);
+      const finish = (error, value) => {
+        clearTimeout(deadline);
+        if (error) reject(error);
+        else resolve(value);
+      };
+      socket.addEventListener('open', () => socket.send(JSON.stringify({id: 1, method, params})), {once: true});
+      socket.addEventListener('message', event => {
+        const reply = JSON.parse(event.data);
+        if (reply.id !== 1) return;
+        if (reply.error) finish(fail('CDP_COMMAND_FAILED', reply.error.message));
+        else finish(null, reply.result);
+      });
+      socket.addEventListener('error', () => finish(fail('CDP_DISCONNECTED', 'CDP socket failed; check the target before retrying')), {once: true});
+      socket.addEventListener('close', () => finish(fail('CDP_DISCONNECTED', 'CDP socket closed before reply')), {once: true});
+    });
+    return {ok: true, result};
+  } finally {
+    socket.close();
+  }
+}

package/lib/cli.mjs

@@ -1,10 +1,16 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import {root,pkg,fail} from './common.mjs';
-import {discover,listContainers,inspectContainer,requestSession,validateReadUrl} from './browser.mjs';
+import {discover,listContainers,inspectContainer,requestSession,validateReadUrl,openContainerHome,qianniuLoginStep} from './browser.mjs';
+import {cdpCommand} from './cdp.mjs';
+import {pageCommand,validatePageOptions} from './page.mjs';
+import {searchXhs} from './xhs.mjs';
+import {noteCommand,validateNoteOptions} from './xhs-note.mjs';
+import {readMemory,tabMemoryAction,memoryOperation,validateTabTarget,autoMemory,protectTab,validateAutoOptions,restoreSettings,validateRestoreOptions} from './memory.mjs';
 import {source,status,installSkill,checkUpdate,updateInstall} from './maintenance.mjs';
 import {inventory,operationSchema,runRead,openOperation,planMutation,showPlan,authorizePlan,nativeRegistryHash} from './sycm.mjs';
 export const capabilities=()=>JSON.parse(fs.readFileSync(path.join(root,'capabilities.json'),'utf8'));
+const qianniuCommands=['shops open','shops login-status','shops submit-login'];
 export function parse(argv) {
   const positions=[],options={}, caps=capabilities();
   for(let i=0;i<argv.length;i++) {
@@ -13,8 +19,8 @@ export function parse(argv) {
     if(word==='--version'&&argv.length===1){positions.push('version');continue;}
     const key=word.slice(2);
     if(Object.hasOwn(options,key)) throw fail('INVALID_ARGUMENT','Duplicate option '+word);
-    if(['json','help','yes','foreground'].includes(key))options[key]=true;
-    else if(['agent','target','profile','instance','name','version','container','url','method','operation','params-json','plan','confirm'].includes(key)&&argv[i+1]&&!argv[i+1].startsWith('--')) options[key]=argv[++i];
+    if(['json','help','yes','foreground','fixture'].includes(key))options[key]=true;
+    else if(['agent','target','profile','instance','name','version','container','url','method','operation','params-json','plan','confirm','service','keyword','via','manifest','account-id','preparation','digest','fixture-port','tab','expected-page-version','operation-id','enabled','idle-seconds','keep-awake','lazy-startup','max-background','output','cdp-method','cdp-target'].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';
@@ -23,7 +29,21 @@ 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.startsWith('xhs note '))validateNoteOptions(command.slice(9),options);
+  if(command==='xhs search'&&(!options.container||typeof options.keyword!=='string'||!options.keyword.trim()||Buffer.byteLength(options.keyword.trim())>180||options.via!=='page'))throw fail('INVALID_ARGUMENT','Specify --container, --keyword (up to 180 UTF-8 bytes), and --via page; Cookie-only search is not yet supported');
+  if(['page read','media download'].includes(command))validatePageOptions(command,options);
   if(command==='containers inspect'&&!options.container)throw fail('INVALID_ARGUMENT','containers inspect requires --container');
+  if(['tabs discard','tabs wake','tabs protect'].includes(command))validateTabTarget(options);
+  if(command==='tabs protect'&&!['on','off'].includes(options['keep-awake']))throw fail('INVALID_ARGUMENT','Specify --keep-awake on|off');
+  if(command==='memory auto set')validateAutoOptions(options);
+  if(command==='memory restore set')validateRestoreOptions(options);
+  if(command==='memory operation'&&!/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/.test(options['operation-id']??''))throw fail('INVALID_ARGUMENT','Specify --operation-id UUID');
+  if(command==='shops open'&&(!options.container||!['home','qianniu'].includes(options.service??'home'))) {
+    throw fail('INVALID_ARGUMENT','Specify --container and optionally --service home|qianniu');
+  }
+  if(command!=='shops open'&&qianniuCommands.includes(command)&&(!options.container||options.service!=='qianniu')) {
+    throw fail('INVALID_ARGUMENT','Specify --container and --service qianniu');
+  }
   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');
@@ -36,14 +56,30 @@ export function parse(argv) {
 }
 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|inspect | session request | sycm operations|schema|run|open|capabilities|mutation plan|show|apply | skill source|status|install|update | update check|install | doctor; use help --json for required options',...capabilities(),...(capabilities().commandContracts[requested]??{})};
+  if(command==='help')return {ok:true,package:pkg.name,version:pkg.version,usage:'ecom-cli containers list|inspect | shops open|login-status|submit-login | xhs search --via page | xhs note preflight|open|upload|fill|verify|status|prepare|submit | cdp endpoint|tabs|call | page read | media download | session request | sycm operations|schema|run|open|capabilities|mutation plan|show|apply | skill source|status|install|update | update check|install | doctor; use help --json for required options',...capabilities(),...(capabilities().commandContracts[requested]??{})};
+  if(command.startsWith('cdp '))return cdpCommand(command.slice(4),options);
+  if(['page read','media download'].includes(command))return pageCommand(command,options);
   if(command==='version')return {ok:true,package:pkg.name,version:pkg.version,protocolVersion:1};
+  if(['memory status','memory tabs','memory processes','memory containers'].includes(command))return readMemory(options);
+  if(['tabs discard','tabs wake'].includes(command))return tabMemoryAction(command.slice(5),options);
+  if(command==='memory operation')return memoryOperation(options);
+  if(command==='memory restore status'||command==='memory restore set')return restoreSettings(command.slice(15),options);
+  if(command==='memory auto status'||command==='memory auto set')return autoMemory(command.slice(12),options);
+  if(command==='tabs protect')return protectTab(options);
   if(command==='capabilities'||command==='schema')return {ok:true,...capabilities()};
   if(command==='skill source') {const item=source();return {...capabilities(),...item,complete:true,items:[item]};}
   if(command==='skill status')return status(options);
   if(command==='skill install'||command==='skill update')return installSkill(options);
   if(command==='update check')return checkUpdate();
   if(command==='update install')return updateInstall(options);
+  if(command.startsWith('xhs note '))return noteCommand(command.slice(9),options);
+  if(command==='xhs search') {
+    const update=await checkUpdate({automatic:true});
+    if(update.available)process.stderr.write('Ecom CLI update available: '+update.latest+'\n');
+    return searchXhs(options);
+  }
+  if(command==='shops open'&&options.service!=='qianniu')return openContainerHome(options);
+  if(qianniuCommands.includes(command))return qianniuLoginStep(command.slice(6),options);
   if(command==='sycm capabilities')return inventory();
   if(command==='sycm operations'){const result=inventory();return {ok:true,schemaVersion:1,source:result.source,count:result.operations.length,operations:result.operations};}
   if(command==='sycm schema')return {ok:true,schemaVersion:1,operation:operationSchema(options.operation)};
@@ -57,7 +93,7 @@ export async function main(argv) {
     return authorizePlan(options);
   }
   if(command==='doctor') {
-    let instance,error;try{const found=discover(options);instance={id:found.endpoint.instanceId,pid:found.endpoint.pid,channel:found.channel,businessReadProtocol:found.endpoint.businessReadProtocol??0,businessPageOpenProtocol:found.endpoint.businessPageOpenProtocol??0,businessRegistryMatches:found.endpoint.businessReadRegistryHash===nativeRegistryHash()};}catch(e){error={code:e.code,message:e.message};}
+    let instance,error;try{const found=discover(options);instance={id:found.endpoint.instanceId,pid:found.endpoint.pid,channel:found.channel,businessReadProtocol:found.endpoint.businessReadProtocol??0,businessRouteProtocol:found.endpoint.businessRouteProtocol??0,signedBusinessRouteProtocol:found.endpoint.signedBusinessRouteProtocol??0,businessPageOpenProtocol:found.endpoint.businessPageOpenProtocol??0,xhsNoteProtocol:found.endpoint.xhsNoteProtocol??0,xhsNoteReviewProtocol:found.endpoint.xhsNoteReviewProtocol??0,businessRegistryMatches:found.endpoint.businessReadRegistryHash===nativeRegistryHash()};}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(['containers list','containers inspect','session request'].includes(command)) {

package/lib/dmp-audience-dev.json

@@ -0,0 +1,4 @@
+{
+  "payload": "{\"version\":1,\"purpose\":\"ecom-dev-dmp-read\",\"id\":\"dmp.competitor-audience\",\"method\":\"POST\",\"path\":\"/api/dmp/insight/tag/chart\",\"expiresAt\":1794376920,\"fields\":{\"appCode\":\"string\",\"needUnknown\":\"boolean\",\"tagId\":\"integer\",\"selectTagOptionSetDTO\":\"dictionary\"}}",
+  "signature": "rysjcVdsMFB+ME+NMLGC10i8VW3SsWZgQ8KpOh3bkgeycfW/+klxmAlDmqFW1JB/ju1xs/SSvGHD8PUd61TRDA=="
+}

package/lib/memory.mjs

@@ -0,0 +1,146 @@
+import {discover,callMailbox} from './browser.mjs';
+import {fail} from './common.mjs';
+
+// Validate the native boundary before using estimates or stable target IDs.
+export function validateSnapshot(body) {
+  if(body.snapshotVersion!==1||typeof body.snapshotId!=='string'||
+      !['macos-physical-footprint','windows-private-bytes'].includes(body.metric)||
+      !Array.isArray(body.tabs)||!Array.isArray(body.containers)||!Array.isArray(body.processes)||
+      !body.totals||!body.policy||!Number.isFinite(body.sampledAtUnixMs))
+    throw fail('PROTOCOL_MISMATCH','Invalid memory snapshot');
+  if(body.restoration!==undefined)validateRestoreSettings({restoration:body.restoration});
+  const pids=new Set(),tabs=new Set();
+  const measurement=x=>x===null||(Number.isFinite(x)&&x>=0);
+  for(const t of body.tabs){
+    if(!Number.isInteger(t.tabId)||tabs.has(t.tabId)||typeof t.containerId!=='string'||typeof t.pageVersion!=='string'||
+        !measurement(t.estimatedMemoryBytes)||!Array.isArray(t.discardReasons)||!Array.isArray(t.freezeReasons)||!Array.isArray(t.connectedFreezeReasons))
+      throw fail('PROTOCOL_MISMATCH','Invalid or duplicate memory tab');
+    const edits=t.manualDiscard?.editSignals;
+    if(edits!==undefined&&(!edits||typeof edits.available!=='boolean'||typeof edits.beforeUnloadDialogPossible!=='boolean'||edits.beforeUnloadBlocks!==false||
+        (edits.available?!['hadFormInteraction','hadUserEdits'].every(k=>typeof edits[k]==='boolean'):!['hadFormInteraction','hadUserEdits'].every(k=>edits[k]===null))))
+      throw fail('PROTOCOL_MISMATCH','Invalid native edit-protection signals');
+    tabs.add(t.tabId);
+  }
+  for(const p of body.processes){
+    if(!Number.isInteger(p.pid)||p.pid<=0||pids.has(p.pid)||!measurement(p.memoryBytes)||!measurement(p.residentBytes)||
+        !Array.isArray(p.tabIds)||new Set(p.tabIds).size!==p.tabIds.length||p.tabIds.some(id=>!tabs.has(id)))
+      throw fail('PROTOCOL_MISMATCH','Invalid or duplicate memory process');
+    pids.add(p.pid);
+  }
+  const total=body.processes.reduce((n,p)=>n+(p.memoryBytes??0),0);
+  if(!['memoryBytes','residentBytes','attributedBytes','unattributedBytes'].every(k=>Number.isFinite(body.totals[k])&&body.totals[k]>=0)||Math.abs(total-body.totals.memoryBytes)>1||
+      Math.abs(body.totals.attributedBytes+body.totals.unattributedBytes-total)>1)
+    throw fail('PROTOCOL_MISMATCH','Memory totals do not reconcile');
+  return body;
+}
+export async function readMemory(options={}) {
+  const connection=discover(options);
+  return readMemoryInConnection(connection);
+}
+export async function readMemoryInConnection(connection) {
+  if(connection.endpoint.memorySnapshotProtocol!==1)
+    throw fail('BROWSER_UPGRADE_REQUIRED','This Ecom build does not advertise memory snapshots');
+  const body=validateSnapshot(await callMailbox(connection,{method:'memory.snapshot'},15000));
+  return {...body,instance:{id:connection.endpoint.instanceId,pid:connection.endpoint.pid,channel:connection.channel}};
+}
+
+export function validateTabTarget(options) {
+  const tabId=Number(options.tab);
+  if(!/^[1-9][0-9]*$/.test(options.tab??'')||!Number.isSafeInteger(tabId)||tabId>2147483647||
+      typeof options.container!=='string'||!options.container||options.container.length>128||
+      typeof options['expected-page-version']!=='string'||!options['expected-page-version'].trim()||options['expected-page-version'].length>200)
+    throw fail('INVALID_ARGUMENT','Specify --tab ID, --container stable-ID (or @default), and --expected-page-version from the same native snapshot');
+  return {tabId,containerId:options.container==='@default'?'':options.container,expectedPageVersion:options['expected-page-version']};
+}
+export async function tabMemoryAction(action,options) {
+  const target=validateTabTarget(options);
+  return tabMemoryActionInConnection(discover(options),action,target);
+}
+export async function tabMemoryActionInConnection(connection,action,target) {
+  if(!['discard','wake'].includes(action))throw fail('INVALID_ARGUMENT','Unknown tab memory action');
+  if(connection.endpoint.manualTabMemoryProtocol!==1)throw fail('BROWSER_UPGRADE_REQUIRED','This Ecom build does not advertise manual tab sleep');
+  const queue=action==='wake'&&connection.endpoint.restoreQueueProtocol===1?{restoreQueueProtocol:1}:{};
+  const body=await callMailbox(connection,{method:'tabs.'+action,...target,...queue},15000);
+  const statuses=action==='discard'?['discarded','already-discarded']:['navigation-started','already-running',...(connection.endpoint.restoreQueueProtocol===1?['navigation-queued']:[])];
+  if(body.tabId!==target.tabId||body.containerId!==target.containerId||body.expectedPageVersion!==target.expectedPageVersion||
+      body.action!=='tabs.'+action||!statuses.includes(body.status)||typeof body.executed!=='boolean'||
+      (body.executed&&(typeof body.pageVersion!=='string'||body.navigationPreserved!==true)))
+    throw fail('PROTOCOL_MISMATCH','Action response does not match the pinned tab',{operationId:body.operationId,executed:'unknown'});
+  if(body.status==='navigation-queued'&&(body.restore?.phase!=='queued'||typeof body.restore?.requestId!=='string'))throw fail('PROTOCOL_MISMATCH','Queued restore has no native request identity',{executed:'unknown'});
+  return {...body,instance:{id:connection.endpoint.instanceId,pid:connection.endpoint.pid,channel:connection.channel}};
+}
+export async function memoryOperation(options) {
+  const connection=discover(options);
+  if(connection.endpoint.manualTabMemoryProtocol!==1)throw fail('BROWSER_UPGRADE_REQUIRED','Operation lookup requires a compatible browser');
+  const id=options['operation-id'];
+  const body=await callMailbox(connection,{method:'memory.operation',targetOperationId:id});
+  if(!['found','not-found'].includes(body.status)||(body.status==='found'&&body.result?.operationId!==id))
+    throw fail('PROTOCOL_MISMATCH','Operation lookup does not match requested ID',{executed:'unknown'});
+  return {...body,instance:{id:connection.endpoint.instanceId,pid:connection.endpoint.pid,channel:connection.channel}};
+}
+
+// Automatic settings are profile-persistent. Per-tab exceptions are run-scoped.
+export function validateAutoOptions(options) {
+  const idle=Number(options['idle-seconds']);
+  if(!['on','off'].includes(options.enabled)||!/^\d+$/.test(options['idle-seconds']??'')||!Number.isSafeInteger(idle)||idle<60||idle>86400)
+    throw fail('INVALID_ARGUMENT','Specify --enabled on|off and --idle-seconds 60..86400');
+  return {enabled:options.enabled==='on',idleSeconds:idle};
+}
+export function validateAutomatic(body) {
+  const a=body.automatic;
+  if(!a||a.protocolVersion!==1||typeof a.enabled!=='boolean'||!Number.isInteger(a.idleSeconds)||a.idleSeconds<60||a.idleSeconds>86400||
+      a.scanIntervalSeconds!==30||a.maxDiscardsPerScan!==1||typeof a.managed!=='boolean'||typeof a.pausedReason!=='string'||typeof a.running!=='boolean'||
+      !Number.isInteger(a.scanCount)||!Number.isInteger(a.discardCount)||!Array.isArray(a.recentActions))
+    throw fail('PROTOCOL_MISMATCH','Invalid automatic memory settings',{executed:'unknown'});
+  return body;
+}
+export async function autoMemory(action,options) {
+  const payload=action==='set'?validateAutoOptions(options):{};
+  return autoMemoryInConnection(discover(options),action,payload);
+}
+export async function autoMemoryInConnection(connection,action,payload={}) {
+  if(!['status','set'].includes(action))throw fail('INVALID_ARGUMENT','Unknown automatic memory action');
+  if(connection.endpoint.autoTabMemoryProtocol!==1)throw fail('BROWSER_UPGRADE_REQUIRED','Automatic memory management requires a compatible browser');
+  const body=validateAutomatic(await callMailbox(connection,{method:'memory.auto.'+action,...payload}));
+  if(action==='set'&&(body.automatic.enabled!==payload.enabled||body.automatic.idleSeconds!==payload.idleSeconds))
+    throw fail('PROTOCOL_MISMATCH','Automatic settings readback differs from requested values',{operationId:body.operationId,executed:'unknown'});
+  return {...body,instance:{id:connection.endpoint.instanceId,pid:connection.endpoint.pid,channel:connection.channel}};
+}
+export async function protectTab(options) {
+  const target=validateTabTarget(options);
+  if(!['on','off'].includes(options['keep-awake']))throw fail('INVALID_ARGUMENT','Specify --keep-awake on|off');
+  const connection=discover(options);
+  if(connection.endpoint.autoTabMemoryProtocol!==1)throw fail('BROWSER_UPGRADE_REQUIRED','Tab keep-running protection requires a compatible browser');
+  const keepAwake=options['keep-awake']==='on';
+  const body=await callMailbox(connection,{method:'tabs.protect',...target,keepAwake});
+  if(body.tabId!==target.tabId||body.containerId!==target.containerId||body.expectedPageVersion!==target.expectedPageVersion||body.keepAwake!==keepAwake||
+      body.scope!=='tab-until-closed-or-browser-restart')
+    throw fail('PROTOCOL_MISMATCH','Protection response does not match requested target',{operationId:body.operationId,executed:'unknown'});
+  return {...body,instance:{id:connection.endpoint.instanceId,pid:connection.endpoint.pid,channel:connection.channel}};
+}
+
+export function validateRestoreOptions(options) {
+  const max=Number(options['max-background']);
+  if(!['on','off'].includes(options['lazy-startup'])||!/^([1-4])$/.test(options['max-background']??''))
+    throw fail('INVALID_ARGUMENT','Specify --lazy-startup on|off and --max-background 1..4');
+  return {lazyStartup:options['lazy-startup']==='on',maxBackgroundRestores:max};
+}
+export function validateRestoreSettings(body) {
+  const r=body.restoration;
+  if(!r||r.protocolVersion!==1||typeof r.lazyStartup!=='boolean'||!Number.isInteger(r.maxBackgroundRestores)||r.maxBackgroundRestores<1||r.maxBackgroundRestores>4||
+      !['activeCount','queuedCount','peakActiveCount','deferredCount'].every(k=>Number.isInteger(r[k])&&r[k]>=0)||typeof r.managed!=='boolean'||!Array.isArray(r.recentRequests))
+    throw fail('PROTOCOL_MISMATCH','Invalid native restoration queue',{executed:'unknown'});
+  return body;
+}
+export async function restoreSettings(action,options) {
+  const payload=action==='set'?validateRestoreOptions(options):{};
+  return restoreSettingsInConnection(discover(options),action,payload);
+}
+export async function restoreSettingsInConnection(connection,action,payload={}) {
+  if(!['status','set'].includes(action))throw fail('INVALID_ARGUMENT','Unknown restore settings action');
+  if(connection.endpoint.restoreQueueProtocol!==1)throw fail('BROWSER_UPGRADE_REQUIRED','Restoration queue requires a compatible Ecom browser');
+  const body=validateRestoreSettings(await callMailbox(connection,{method:'memory.restore.'+action,...payload}));
+  if(action==='set'&&(body.restoration.lazyStartup!==payload.lazyStartup||body.restoration.maxBackgroundRestores!==payload.maxBackgroundRestores))
+    throw fail('PROTOCOL_MISMATCH','Restoration settings readback differs from request',{operationId:body.operationId,executed:'unknown'});
+  return {...body,instance:{id:connection.endpoint.instanceId,pid:connection.endpoint.pid,channel:connection.channel}};
+}

package/lib/page.mjs

@@ -0,0 +1,63 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import {callMailbox, discover, readMailbox, resolveContainer} from './browser.mjs';
+import {exists, fail, privatePath} from './common.mjs';
+
+export function validatePageOptions(command, options) {
+  let url;
+  try { url = new URL(options.url); } catch {}
+  if (!options.container || !url || url.protocol !== 'https:' ||
+      url.username || url.password || url.port || options.url.length > 8192)
+    throw fail('INVALID_ARGUMENT', 'Specify a container and a credential-free HTTPS page URL');
+  if (command === 'media download' && !options.output)
+    throw fail('INVALID_ARGUMENT', 'Specify a new local file with --output');
+}
+
+// Douyin's own embed uses the same public work ID as the desktop work URL.
+export function mediaPageUrl(url) {
+  const target = new URL(url);
+  const work = target.pathname.match(/^\/video\/(\d{16,22})\/?$/);
+  if (target.origin !== 'https://www.douyin.com' || !work ||
+      target.search || target.hash) return target.href;
+  const player = new URL('https://open.douyin.com/player/video');
+  player.searchParams.set('vid', work[1]);
+  return player.href;
+}
+
+export async function pageCommand(command, options) {
+  validatePageOptions(command, options);
+  const output = command === 'media download' ? path.resolve(options.output) : null;
+  if (output && exists(output)) throw fail('OUTPUT_EXISTS', 'Choose a new output file');
+  if (output && !fs.statSync(path.dirname(output), {throwIfNoEntry:false})?.isDirectory())
+    throw fail('INVALID_ARGUMENT', 'Output parent directory must exist');
+  const connection = discover(options);
+  if (connection.endpoint.backgroundPageProtocol !== 1)
+    throw fail('BROWSER_UPGRADE_REQUIRED', 'Use an Ecom build with background page protocol 1');
+  const {containers} = await readMailbox(connection);
+  const {id} = resolveContainer(containers, options.container);
+  const pageUrl = output ? mediaPageUrl(options.url) : new URL(options.url).href;
+  const result = await callMailbox(connection, {
+    method: output ? 'media.download' : 'page.read',
+    containerId: id,
+    url: pageUrl,
+  }, output ? 92000 : 29000);
+  if (result.containerId !== id)
+    throw fail('PROTOCOL_MISMATCH', 'Response did not match the selected container');
+  if (!output) return result;
+  const {artifact, ...receipt} = result;
+  const temporaryRoot = fs.realpathSync(os.tmpdir());
+  if (typeof artifact !== 'string' || !path.isAbsolute(artifact) ||
+      !fs.realpathSync(artifact).startsWith(temporaryRoot + path.sep))
+    throw fail('PROTOCOL_MISMATCH', 'Invalid media artifact path');
+  privatePath(artifact);
+  try {
+    if (!Number.isSafeInteger(result.bytes) || result.bytes <= 0 ||
+        fs.statSync(artifact).size !== result.bytes)
+      throw fail('PROTOCOL_MISMATCH', 'Invalid media artifact size');
+    fs.copyFileSync(artifact, output, fs.constants.COPYFILE_EXCL);
+  } finally {
+    fs.unlinkSync(artifact);
+  }
+  return {...receipt, output, pageUrl};
+}