@yunhozz/arc 0.1.4 → 0.1.6

package/lib/cli/completion.mjs

@@ -2,17 +2,18 @@ export function renderCompletion(shell){
  if(shell==='bash')return `_arc() {
  local cur="\${COMP_WORDS[COMP_CWORD]}" prev="\${COMP_WORDS[COMP_CWORD-1]}" command="\${COMP_WORDS[1]}" choices=""
  case "$prev" in
-  --target) choices="claude codex all" ;;
-  --preset) choices="economy balanced smart" ;;
-  --language) choices="en ko" ;;
+  --target) [[ $command == -* || $command == preset || $command == uninstall ]] && choices="claude codex all" ;;
+  --preset) [[ $command == -* ]] && choices="economy balanced smart" ;;
+  --language) [[ $command == -* ]] && choices="en ko" ;;
   *)
-   if (( COMP_CWORD == 1 )) && [[ $cur != -* ]]; then choices="preset uninstall"
+   if (( COMP_CWORD == 1 )) && [[ $cur != -* ]]; then choices="preset uninstall completion upgrade"
    else
     case "$command" in
      preset)
       if (( COMP_CWORD == 2 )) && [[ $cur != -* ]]; then choices="economy balanced smart"
       else choices="--target --check --dry-run --help"; fi ;;
      uninstall) choices="--target --dry-run --skip-global --help --version" ;;
+     upgrade) choices="--help" ;;
      completion) (( COMP_CWORD == 2 )) && choices="zsh bash" ;;
      -*) choices="--target --preset --language --max-total-subagents --max-concurrent-subagents --check --dry-run --skip-global --help --version" ;;
     esac
@@ -25,17 +26,18 @@ complete -F _arc arc
  if(shell==='zsh')return `_arc() {
  local -a candidates
  if (( CURRENT == 2 )) && [[ \${words[CURRENT]} != -* ]]; then
-  candidates=(preset uninstall)
+  candidates=(preset uninstall completion upgrade)
  else
   case "\${words[CURRENT-1]}" in
-   --target) candidates=(claude codex all) ;;
-   --preset) candidates=(economy balanced smart) ;;
-   --language) candidates=(en ko) ;;
+   --target) [[ \${words[2]} == -* || \${words[2]} == preset || \${words[2]} == uninstall ]] && candidates=(claude codex all) ;;
+   --preset) [[ \${words[2]} == -* ]] && candidates=(economy balanced smart) ;;
+   --language) [[ \${words[2]} == -* ]] && candidates=(en ko) ;;
    *) case "\${words[2]}" in
     preset)
      if (( CURRENT == 3 )) && [[ \${words[CURRENT]} != -* ]]; then candidates=(economy balanced smart)
      else candidates=(--target --check --dry-run --help); fi ;;
     uninstall) candidates=(--target --dry-run --skip-global --help --version) ;;
+    upgrade) candidates=(--help) ;;
     completion) (( CURRENT == 3 )) && candidates=(zsh bash) ;;
     -*) candidates=(--target --preset --language --max-total-subagents --max-concurrent-subagents --check --dry-run --skip-global --help --version) ;;
    esac ;;

package/lib/cli/index.mjs

@@ -13,7 +13,7 @@ export function parseArgs(args){
  if(options.check&&options.dryRun)throw inputError('--check and --dry-run cannot be combined');return options;
 }
 export async function selectChoices(options,io){return(await import('./choices.mjs')).selectChoices(options,io);}
-export async function runCli(args=process.argv.slice(2),{input=process.stdin,output=process.stdout,error=process.stderr}={}){
+export async function runCli(args=process.argv.slice(2),{input=process.stdin,output=process.stdout,error=process.stderr,cwd=process.cwd(),env=process.env}={}){
  let controller,onInterrupt,progress;
  try{
   const options=parseArgs(args);if(options.help){output.write(usage+'\n');return 0;}if(options.version){output.write(JSON.parse(fs.readFileSync(path.join(packageRoot,'package.json'))).version+'\n');return 0;}
@@ -22,12 +22,12 @@ export async function runCli(args=process.argv.slice(2),{input=process.stdin,out
   const {startProgress}=await import('./progress.mjs');
   const interactive=input.isTTY&&output.isTTY,label=options.check?'Checking ARC…':options.dryRun?'Preparing ARC dry run…':'Installing ARC…';
   if(!interactive)progress=startProgress({output,label});
-  controller=new AbortController();onInterrupt=()=>controller.abort();process.once('SIGINT',onInterrupt);
+  controller=new AbortController();onInterrupt=()=>controller.abort();process.once('SIGINT',onInterrupt);process.once('SIGTERM',onInterrupt);
   const {loadNative}=await import('../safe-fs/native.mjs');const native=loadNative();
   const [{openRoot},{verifyPayload},{resolveTarget},{buildInstallPlan,validatePlanSet}]=await Promise.all([import('../safe-fs/index.mjs'),import('../installer/manifest.mjs'),import('../installer/targets.mjs'),import('../installer/plan.mjs')]);
   const safeFs={openRoot:p=>openRoot(p,{native})},payload=verifyPayload({packageRoot,safeFs});
   const platforms=options.target==='all'?['codex','claude']:[options.target];
-  const {previewLimits,previewLanguage}=await import('../installer/plan.mjs');const{defaultLanguage}=await import('../installer/language.mjs');const selections=platforms.map(platform=>{const target=resolveTarget(platform,{userHome:os.homedir(),env:process.env});return{target,preview:previewLimits({target,safeFs}),languagePreview:previewLanguage({target,safeFs})};});
+  const {previewLimits,previewLanguage}=await import('../installer/plan.mjs');const{defaultLanguage}=await import('../installer/language.mjs');const selections=platforms.map(platform=>{const target=resolveTarget(platform,{userHome:os.homedir(),env,cwd});return{target,preview:previewLimits({target,safeFs}),languagePreview:previewLanguage({target,safeFs})};});
   if(interactive){const{selectLimits,selectLanguage}=await import('./choices.mjs');await selectLimits(options,selections,{input,output});await selectLanguage(options,defaultLanguage(selections.map(item=>item.languagePreview.existing)),{input,output});}
   progress??=startProgress({output,label});
   const plans=selections.map(({target,preview,languagePreview})=>buildInstallPlan({payload,target,language:options.language,languagePreview,preset:options.preset,skipGlobal:options.skipGlobal,safeFs,limitsPreview:preview,limits:{...(options.maxTotalSubagents===undefined?{}:{max_total_subagents:options.maxTotalSubagents}),...(options.maxConcurrentSubagents===undefined?{}:{max_concurrent_subagents:options.maxConcurrentSubagents})},concurrentExplicit:options.maxConcurrentSubagents!==undefined||Boolean(options.concurrentSelected)}));const {attachShellCompletion}=await import('../installer/shell-completion.mjs');attachShellCompletion(plans,{safeFs});validatePlanSet(plans);
@@ -48,8 +48,8 @@ export async function runCli(args=process.argv.slice(2),{input=process.stdin,out
   progress.stop();
   const reportResults=()=>{for(const item of result.results){output.write(`${item.platform}: ${item.status}; rollback: ${item.rollback}\n`);for(const recovery of item.residualPaths)output.write(`Residual path: ${recovery}\n`);if(item.error)error.write(`Error: ${item.error.message}\n`);}};
   if(result.interrupted){reportResults();return 130;}
-  if(result.results.every(item=>item.status==='installed'&&!item.error)){output.write(`ARC installed! [${result.results.map(item=>item.platform).join('/')}]\n`);return 0;}
+  if(result.results.every(item=>item.status==='installed'&&!item.error)){output.write(`ARC version ${JSON.parse(fs.readFileSync(path.join(packageRoot,'package.json'))).version} installed! [${result.results.map(item=>item.platform).join('/')}]\n`);return 0;}
   reportResults();return 1;
  }catch(cause){progress?.stop();error.write(`Error: ${cause.message}\n`);if(cause.code==='ARC_CLI_INPUT'){error.write(usage+'\n');return 2;}if(cause.code==='ARC_CANCELLED')return 130;return ['ARC_UNSUPPORTED_RUNTIME','ARC_NATIVE_UNAVAILABLE','ARC_TARGET_CONFIGURATION'].includes(cause.code)?2:1;
- }finally{progress?.stop();if(onInterrupt)process.removeListener('SIGINT',onInterrupt);}
+ }finally{progress?.stop();if(onInterrupt){process.removeListener('SIGINT',onInterrupt);process.removeListener('SIGTERM',onInterrupt);}}
 }

package/lib/cli/postinstall.mjs

@@ -0,0 +1,17 @@
+import path from 'node:path';
+import {inspectNpmContext,resolveInvocationCwd} from '../npm/context.mjs';
+import {openInstallerTerminal} from './terminal.mjs';
+import {runCli} from './index.mjs';
+export async function runPostinstall({packageRoot,env=process.env,cwd=process.cwd(),input=process.stdin,output=process.stdout,error=process.stderr,deps={}}){
+ let terminal;
+ try{
+  if(env.npm_lifecycle_event!=='postinstall'){output.write('Run arc to install the ARC harness.\n');return 0;}
+  const context=await(deps.inspectNpmContext??inspectNpmContext)({packageRoot,entryPath:path.join(packageRoot,'scripts/postinstall.mjs'),env,cwd});
+  if(context.kind!=='global'){output.write('Run arc to install the ARC harness.\n');return 0;}
+  terminal=(deps.openInstallerTerminal??openInstallerTerminal)({env,input,output,error});
+  if(terminal.kind==='skip'){output.write('Run arc to install the ARC harness.\n');return 0;}
+  const invocationCwd=resolveInvocationCwd({env,cwd,lifecycle:true});
+  return await(deps.runCli??runCli)([],{...terminal.io,cwd:invocationCwd,env});
+ }catch(cause){(terminal?.io.error??error).write(`Error: ${cause.message}\n`);return 1;}
+ finally{terminal?.dispose?.();}
+}

package/lib/cli/root.mjs

@@ -1,6 +1,6 @@
 import fs from 'node:fs';
 import {renderCompletion} from './completion.mjs';
-const usage='Usage: arc [installation options]\n  arc preset [economy|balanced|smart] --target <codex|claude|all>\n  arc uninstall --target <codex|claude|all>\n  arc completion <zsh|bash>  (shell setup)\n  arc --help | --version';
+const usage='Usage: arc [installation options]\n  arc preset [economy|balanced|smart] --target <codex|claude|all>\n  arc uninstall --target <codex|claude|all>\n  arc upgrade [--help]\n  arc completion <zsh|bash>  (shell setup)\n  arc --help | --version';
 const completionUsage='Usage: arc completion <zsh|bash>';
 export async function runRoot(args=process.argv.slice(2),io={}){
  const output=io.output??process.stdout,error=io.error??process.stderr;
@@ -8,6 +8,7 @@ export async function runRoot(args=process.argv.slice(2),io={}){
  if(command==='--help'&&!rest.length){output.write(usage+'\n\n');return(await import('./index.mjs')).runCli(args,io);}
  if(command==='--version'&&!rest.length){output.write(JSON.parse(fs.readFileSync(new URL('../../package.json',import.meta.url))).version+'\n');return 0;}
  if(command==='preset')return(await import('./preset.mjs')).runCli(rest,io);
+ if(command==='upgrade')return(await import('./upgrade.mjs')).runCli(rest,io);
  if(command==='install'){error.write('Error: The install subcommand was removed. Run npx --yes @yunhozz/arc [installation options].\n');return 2;}
  if(command===undefined||command.startsWith('--'))return(await import('./index.mjs')).runCli(args,io);
  if(command==='uninstall')return(await import('./uninstall.mjs')).runCli(rest,io);

package/lib/cli/terminal.mjs

@@ -0,0 +1,19 @@
+import fs from 'node:fs';
+import tty from 'node:tty';
+function openControllingTerminal(){
+ let inputFd,outputFd,input,output;
+ try{
+  inputFd=fs.openSync('/dev/tty','r+');outputFd=fs.openSync('/dev/tty','r+');
+  input=new tty.ReadStream(inputFd);inputFd=undefined;
+  output=new tty.WriteStream(outputFd);outputFd=undefined;
+  return{io:{input,output,error:output},dispose(){input.destroy();output.destroy();}};
+ }catch(cause){input?.destroy();output?.destroy();if(inputFd!==undefined)fs.closeSync(inputFd);if(outputFd!==undefined)fs.closeSync(outputFd);throw cause;}
+}
+export function openInstallerTerminal({platform=process.platform,env=process.env,input=process.stdin,output=process.stdout,error=process.stderr,openTty=openControllingTerminal}={}){
+ if(!['darwin','linux'].includes(platform))return{kind:'skip',reason:'unsupported platform'};
+ if(['CI','CONTINUOUS_INTEGRATION','BUILD_NUMBER','RUN_ID'].some(name=>env[name]&&env[name]!=='false'&&env[name]!=='0'))return{kind:'skip',reason:'non-interactive environment'};
+ let owned,io;
+ try{if(input.isTTY&&output.isTTY)io={input,output,error};else{owned=openTty();io=owned.io;}if(!io.input.isTTY||!io.output.isTTY)throw Error('Terminal is not interactive');}catch{owned?.dispose();return{kind:'skip',reason:'no interactive terminal'};}
+ const wasRaw=Boolean(io.input.isRaw),wasFlowing=io.input.readableFlowing;let disposed=false;
+ return{kind:'interactive',io,dispose(){if(disposed)return;disposed=true;try{if(io.input.setRawMode&&!io.input.destroyed)io.input.setRawMode(wasRaw);if(wasFlowing!==true)io.input.pause();}finally{owned?.dispose();}}};
+}

package/lib/cli/upgrade.mjs

@@ -0,0 +1,57 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import {fileURLToPath} from 'node:url';
+const packageRoot=path.resolve(fileURLToPath(new URL('../../',import.meta.url)));
+const usage='Usage: arc upgrade [--help]';
+const inputError=message=>Object.assign(Error(message),{code:'ARC_CLI_INPUT'});
+const configurationError=message=>Object.assign(Error(message),{code:'ARC_TARGET_CONFIGURATION'});
+function identity(root){const pkg=JSON.parse(fs.readFileSync(path.join(root,'package.json'),'utf8'));if(pkg.name!=='@yunhozz/arc'||!/^\d+\.\d+\.\d+$/.test(pkg.version))throw configurationError('Invalid ARC package identity');return pkg;}
+async function runtime(deps){
+ const [context,state,upgrade,npm]=await Promise.all([import('../npm/context.mjs'),import('../installer/upgrade-state.mjs'),import('../installer/upgrade.mjs'),import('../npm/upgrade.mjs')]);
+ let safeFs=deps.safeFs;if(!safeFs){const[{loadNative},{openRoot}]=await Promise.all([import('../safe-fs/native.mjs'),import('../safe-fs/index.mjs')]);const native=loadNative();safeFs={openRoot:root=>openRoot(root,{native})};}
+ return{...context,...state,...upgrade,...npm,...deps,safeFs};
+}
+function report(result,output,error){
+ for(const item of result.results){output.write(item.platform+': '+item.status+'; rollback: '+item.rollback+'\n');for(const filename of item.residualPaths??[])output.write('Residual path: '+filename+'\n');if(item.error)error.write('Error: '+item.error.message+'\n');}
+ if(result.interrupted)return 130;
+ if(result.results.every(item=>item.status==='installed'&&!item.error)){output.write('ARC version '+result.version+' harness upgraded! Previous harness version: not recorded.\nOpen a new shell session to use updated completion.\nzsh completion: eval "$(arc completion zsh)" for this session\n');return 0;}
+ error.write('Harness update did not complete. Retry arc upgrade or npx --yes @yunhozz/arc@latest upgrade.\n');return 1;
+}
+function failure(cause,error){error.write('Error: '+cause.message+'\n');return ['ARC_CANCELLED','ARC_NPM_CANCELLED'].includes(cause.code)?130:['ARC_CLI_INPUT','ARC_TARGET_CONFIGURATION','ARC_UNSUPPORTED_RUNTIME','ARC_NATIVE_UNAVAILABLE'].includes(cause.code)?2:1;}
+export async function runCli(args=process.argv.slice(2),io={},deps={}){
+ const output=io.output??process.stdout,error=io.error??process.stderr;let controller,onInterrupt,packageStarted=false;
+ try{
+  if(args.length===1&&args[0]==='--help'){output.write(usage+'\nUpdates the global CLI and installed harness; npm exec updates the harness only.\n');return 0;}
+  if(args.length)throw inputError('Expected no arguments or --help');
+  const root=deps.packageRoot??packageRoot,pkg=identity(root),env=io.env??process.env,cwd=fs.realpathSync(io.cwd??process.cwd()),api=await runtime(deps);
+  const context=await api.inspectNpmContext({packageRoot:root,entryPath:path.join(root,'bin/arc.mjs'),env,cwd});
+  if(!['global','npx'].includes(context.kind))throw configurationError('Run upgrade from a verified global ARC installation or npx --yes @yunhozz/arc@latest upgrade');
+  const state=api.collectInstalledState({safeFs:api.safeFs,userHome:deps.userHome??os.homedir(),env,cwd});
+  if(!state.targets.length)throw configurationError('No installed ARC harness found. Run npx --yes @yunhozz/arc to install it first');
+  controller=new AbortController();onInterrupt=()=>controller.abort();process.once('SIGINT',onInterrupt);process.once('SIGTERM',onInterrupt);
+  if(context.kind==='npx')return report(await api.upgradeInstalledTargets({packageRoot:root,state,safeFs:api.safeFs,signal:controller.signal}),output,error);
+  const latest=await api.resolveLatest({context,env,cwd,signal:controller.signal});packageStarted=true;
+  const replaced=await api.upgradeGlobal({context,expectedVersion:latest.version,env,cwd,signal:controller.signal});
+  if(replaced.packageStatus!=='updated')throw replaced.error??Error('CLI replacement failed');
+  output.write('CLI: updated to '+latest.version+' (previous '+pkg.version+').\n');
+  const result=await api.runUpgradeChild({entryPath:path.join(context.packageRoot,'bin/arc-upgrade.mjs'),request:{protocol:1,expectedVersion:latest.version,invocationCwd:cwd,expectedStateToken:state.stateToken},env,cwd,signal:controller.signal});
+  if(result.stdout)output.write(result.stdout);if(result.stderr)error.write(result.stderr);
+  if(result.code===0&&!result.signal)return 0;
+  error.write('CLI was updated but the harness update did not complete. Retry arc upgrade or npx --yes @yunhozz/arc@latest upgrade.\n');return result.code===130?130:1;
+ }catch(cause){const code=failure(cause,error);if(cause.code==='ARC_CLI_INPUT')error.write(usage+'\n');if(packageStarted)error.write('CLI state may have changed. Retry arc upgrade; if it is unavailable, run npx --yes @yunhozz/arc@latest upgrade.\n');return code;}
+ finally{if(onInterrupt){process.removeListener('SIGINT',onInterrupt);process.removeListener('SIGTERM',onInterrupt);}}
+}
+export async function runChild(request,io={},deps={}){
+ const output=io.output??process.stdout,error=io.error??process.stderr;let onInterrupt;
+ try{
+  if(!request||Object.keys(request).sort().join(',')!=='expectedStateToken,expectedVersion,invocationCwd,protocol'||request.protocol!==1||typeof request.expectedVersion!=='string'||!/^\d+\.\d+\.\d+$/.test(request.expectedVersion)||typeof request.expectedStateToken!=='string'||!/^[a-f0-9]{64}$/.test(request.expectedStateToken)||typeof request.invocationCwd!=='string'||!path.isAbsolute(request.invocationCwd)||fs.realpathSync(request.invocationCwd)!==request.invocationCwd)throw inputError('Invalid private upgrade request');
+  const root=deps.packageRoot??packageRoot,pkg=identity(root);if(pkg.version!==request.expectedVersion)throw configurationError('The new ARC package version does not match the requested upgrade');
+  const api=await runtime(deps),env=io.env??process.env,cwd=request.invocationCwd,context=await api.inspectNpmContext({packageRoot:root,entryPath:path.join(root,'bin/arc-upgrade.mjs'),env,cwd});
+  if(context.kind!=='global'||context.packageRoot!==root)throw configurationError('Cannot verify the replaced global ARC package');
+  const state=api.collectInstalledState({safeFs:api.safeFs,userHome:deps.userHome??os.homedir(),env,cwd});if(state.stateToken!==request.expectedStateToken)throw configurationError('Installed ARC settings changed during CLI replacement; retry upgrade');
+  if(!state.targets.length)throw configurationError('No installed ARC harness found');
+  const controller=new AbortController();onInterrupt=()=>controller.abort();process.once('SIGINT',onInterrupt);process.once('SIGTERM',onInterrupt);
+  return report(await api.upgradeInstalledTargets({packageRoot:root,state,safeFs:api.safeFs,signal:controller.signal}),output,error);
+ }catch(cause){return failure(cause,error);}finally{if(onInterrupt){process.removeListener('SIGINT',onInterrupt);process.removeListener('SIGTERM',onInterrupt);}}
+}

package/lib/installer/plan.mjs

@@ -2,6 +2,7 @@ import {installClaudeHook} from '../policy/claude-hook.mjs';
 import {validateGitPolicy} from '../../claude/skill/hooks/role-git-guard.mjs';
 import{parseLanguage,serializeLanguage,renderLanguagePolicy,validateLanguage}from'./language.mjs';
 import{resolveLimits}from'../limits.mjs';import{parseLimits,serializeLimits}from'./limits.mjs';import{readRuntimeConcurrency,renderCodexConcurrency,renderClaudeConcurrency}from'./runtime-config.mjs';import{assertPlanSnapshot}from'./transaction.mjs';
+import{validateModelConfig}from'../models/config.mjs';
 import path from'node:path';import{loadModelConfig,applyPreset,serializeModelConfig,renderProfiles,resolveModelSettings}from'../models/index.mjs';import{inspectPath,TargetConfigurationError}from'./targets.mjs';import{renderManagedBlock,renderWaitSettings,agentsBlockBody}from'./global-config.mjs';
 function fail(message){throw new TargetConfigurationError(message);}
 export function previewLimits({target,safeFs}){
@@ -16,7 +17,7 @@ export function previewLanguage({target,safeFs}){
  let existing=null;try{if(current.exists)existing=parseLanguage(current.bytes).language;}catch(cause){fail(`Invalid ARC language settings: ${cause.message}`);}
  return{existing,snapshot};
 }
-export function buildInstallPlan({payload,target,preset,skipGlobal=false,safeFs,limits,concurrentExplicit=false,limitsPreview,language='en',languagePreview}){
+export function buildInstallPlan({payload,target,preset,skipGlobal=false,safeFs,limits,concurrentExplicit=false,limitsPreview,language='en',languagePreview,modelConfig}){
  validateLanguage(language);
  if(languagePreview)assertPlanSnapshot({snapshot:languagePreview.snapshot},{safeFs});
  const languageState=languagePreview??previewLanguage({target,safeFs});
@@ -24,7 +25,7 @@ export function buildInstallPlan({payload,target,preset,skipGlobal=false,safeFs,
  const preview=limitsPreview??previewLimits({target,safeFs});
  limits=resolveLimits({existing:preview.existing,overrides:limits??{}});
  const input=payload.modelInputs[target.platform];if(!input)fail('Selected payload platform is unavailable');
- const config=applyPreset(loadModelConfig(input.models,target.platform),preset),profiles=renderProfiles(input.profiles,resolveModelSettings(config));for(const[name,bytes]of profiles)profiles.set(name,renderLanguagePolicy(bytes,language));const modelBytes=Buffer.from(serializeModelConfig(config));
+ const config=modelConfig===undefined?applyPreset(loadModelConfig(input.models,target.platform),preset):validateModelConfig(modelConfig);if(config.platform!==target.platform)fail('Model config platform does not match target');const profiles=renderProfiles(input.profiles,resolveModelSettings(config));for(const[name,bytes]of profiles)profiles.set(name,renderLanguagePolicy(bytes,language));const modelBytes=Buffer.from(serializeModelConfig(config));
  if(target.platform==='claude'){try{const script=payload.files.get('claude/skill/hooks/role-git-guard.mjs'),policy=payload.files.get('claude/skill/hooks/git-policy.json');if(!Buffer.isBuffer(script)||!script.length||!Buffer.isBuffer(policy))throw Error('Missing hook assets');validateGitPolicy(JSON.parse(policy.toString('utf8')));for(const[name,bytes]of profiles)profiles.set(name,installClaudeHook(bytes,path.join(target.home,'skills/arc')));}catch(cause){fail(`Invalid Claude Git guard: ${cause.message}`);}}
  const skill=new Map();for(const[name,bytes]of payload.files)if(name.startsWith(target.payloadPrefix+'/skill/'))skill.set(name.slice((target.payloadPrefix+'/skill/').length),Buffer.from(bytes));skill.set('SKILL.md',renderLanguagePolicy(skill.get('SKILL.md'),language));skill.set('settings.toml',serializeLanguage(language));skill.set('models.toml',modelBytes);skill.set('limits.toml',serializeLimits(limits));
  const snapshot=new Map(),home=target.home;const skills=path.join(home,'skills'),agents=path.join(home,'agents'),arc=path.join(skills,'arc');

package/lib/installer/upgrade-state.mjs

@@ -0,0 +1,29 @@
+import path from 'node:path';
+import {createHash} from 'node:crypto';
+import {resolveTarget,inspectPath,TargetConfigurationError} from './targets.mjs';
+import {loadModelConfig} from '../models/index.mjs';
+import {parseLanguage} from './language.mjs';
+import {parseLimits} from './limits.mjs';
+import {removeManagedBlock} from './global-config.mjs';
+import {renderShellCompletion} from './shell-completion.mjs';
+import {readRuntimeConcurrency} from './runtime-config.mjs';
+const fail=message=>{throw new TargetConfigurationError(message);};
+export function collectInstalledState({safeFs,userHome,env={},cwd}){
+ if(env.CODEX_HOME!==undefined&&!path.isAbsolute(env.CODEX_HOME)&&env.CODEX_HOME!=='~'&&!env.CODEX_HOME.startsWith('~/')&&(!cwd||!path.isAbsolute(cwd)))fail('A verified invocation cwd is required for relative CODEX_HOME');
+ const targets=[];
+ for(const platform of ['codex','claude']){
+  const target=resolveTarget(platform,{userHome,env,cwd}),snapshot=new Map(),arc=path.join(target.home,'skills/arc');
+  const skill=inspectPath(safeFs,arc,{kind:'directory',tree:true,allowLinks:true,snapshot});
+  const profiles=target.profileNames.map(name=>inspectPath(safeFs,path.join(target.home,'agents',name),{kind:'file',read:true,snapshot}));
+  const instruction=inspectPath(safeFs,target.instructionPath,{kind:'file',read:true,snapshot}),managed=instruction.exists?removeManagedBlock(instruction.bytes):{changed:false};
+  if(!skill.exists){if(profiles.some(item=>item.exists)||managed.changed)fail(`Incomplete ARC installation: ${target.home}`);continue;}
+  function mandatory(name){const found=inspectPath(safeFs,path.join(arc,name),{kind:'file',read:true,snapshot});if(!found.exists||!found.bytes.length)fail(`Incomplete ARC installation: missing ${name} at ${target.home}`);return found.bytes;}
+  mandatory('SKILL.md');if(profiles.some(item=>!item.exists||!item.bytes.length))fail(`Incomplete ARC installation: missing profile at ${target.home}`);
+  let language,modelConfig,limits;try{language=parseLanguage(mandatory('settings.toml')).language;modelConfig=loadModelConfig(mandatory('models.toml'),platform);limits=parseLimits(mandatory('limits.toml'));}catch(cause){throw new TargetConfigurationError(`Invalid installed ARC settings at ${target.home}: ${cause.message}`,{cause});}
+  const native=inspectPath(safeFs,target.runtimeConfigPath,{kind:'file',read:true,snapshot});if(native.exists)try{readRuntimeConcurrency(platform,native.bytes);}catch(cause){throw new TargetConfigurationError(`Invalid native configuration at ${target.runtimeConfigPath}: ${cause.message}`,{cause});}
+  const shell=inspectPath(safeFs,path.join(userHome,'.zshrc'),{kind:'file',read:true,snapshot});if(shell.exists)renderShellCompletion(shell.bytes);
+  targets.push({target,language,modelConfig,limits,snapshot});
+ }
+ const hash=createHash('sha256');for(const entry of targets){hash.update(entry.target.platform+'\0'+entry.target.home+'\0');for(const [name,value]of [...entry.snapshot].sort(([a],[b])=>a.localeCompare(b)))hash.update(JSON.stringify([name,value],(key,value)=>key==='atimeNs'?undefined:typeof value==='bigint'?value.toString():value));}
+ return{targets,stateToken:hash.digest('hex')};
+}

package/lib/installer/upgrade.mjs

@@ -0,0 +1,34 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import {buildInstallPlan,validatePlanSet} from './plan.mjs';
+import {assertPlanSnapshot} from './transaction.mjs';
+import {inspectPath} from './targets.mjs';
+import {renderManagedBlock,removeManagedBlock,agentsBlockBody} from './global-config.mjs';
+import {renderShellCompletion} from './shell-completion.mjs';
+import {verifyPayload} from './manifest.mjs';
+import {installTargets} from './install.mjs';
+import {acquireExternalSkills} from './acquisition.mjs';
+export function buildUpgradePlans({payload,state,safeFs}){
+ for(const entry of state.targets)assertPlanSnapshot(entry,{safeFs});
+ const plans=state.targets.map(entry=>{
+  const {target,language,modelConfig,limits}=entry;
+  const plan=buildInstallPlan({payload,target,language,modelConfig,preset:modelConfig.preset,limits,skipGlobal:true,safeFs});
+  for(const [name,value]of entry.snapshot)plan.snapshot.set(name,value);
+  const current=inspectPath(safeFs,target.instructionPath,{kind:'file',read:true,snapshot:plan.snapshot});
+  if(current.exists&&removeManagedBlock(current.bytes).changed){const rendered=renderManagedBlock(current.bytes,agentsBlockBody(target.home,target.userHome,language,target.platform));plan.managedPaths.push(target.instructionPath);if(!rendered.content.equals(current.bytes))plan.globalChanges.push({path:target.instructionPath,original:current.bytes,...rendered});}
+  return plan;
+ });
+ const first=plans[0];if(first){const filename=path.join(first.target.userHome,'.zshrc'),current=inspectPath(safeFs,filename,{kind:'file',read:true,snapshot:first.snapshot});
+  if(current.exists){const content=renderShellCompletion(current.bytes);if(current.bytes.includes(Buffer.from('# >>> arc completion >>>'))){first.managedPaths.push(filename);if(!content.equals(current.bytes))first.globalChanges.push({path:filename,original:current.bytes,content,action:'update completion'});}}
+  for(const plan of plans.slice(1))plan.snapshot.delete(filename);
+ }
+ validatePlanSet(plans);return plans;
+}
+export async function upgradeInstalledTargets({packageRoot,state,safeFs,signal,acquisition}){
+ const payload=verifyPayload({packageRoot,safeFs}),version=JSON.parse(payload.files.get('package.json').toString('utf8')).version,plans=buildUpgradePlans({payload,state,safeFs});
+ const acquire=acquisition??(async()=>{const work=fs.mkdtempSync(path.join(fs.realpathSync(os.tmpdir()),'arc-acquire-'));let acquired;
+  try{acquired=await acquireExternalSkills({work,safeFs,signal});}catch(error){if(!error.residualPaths?.length)try{fs.rmdirSync(work);}catch(cleanup){throw Object.assign(new AggregateError([error,cleanup],'Cannot clean private acquisition work'),{code:'ARC_ACQUISITION_CLEANUP',residualPaths:[work]});}throw error;}
+  return{...acquired,dispose:async()=>{await acquired.dispose();fs.rmdirSync(work);}};});
+ return{version,...await installTargets(plans,{safeFs,signal,acquisition:acquire})};
+}

package/lib/npm/context.mjs

@@ -0,0 +1,36 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import {runNpm as defaultRunNpm} from './process.mjs';
+const unsupported=reason=>({kind:'unsupported',reason});
+function realDirectory(value){if(typeof value!=='string'||!path.isAbsolute(value))throw Error('Expected an absolute directory');const real=fs.realpathSync(value);if(!fs.statSync(real).isDirectory())throw Error('Expected a directory');return real;}
+function npmExecutable(env){
+ const candidates=env.npm_execpath?[env.npm_execpath]:(env.PATH??'').split(path.delimiter).filter(p=>path.isAbsolute(p)).map(p=>path.join(p,'npm'));
+ for(const candidate of candidates)try{if(!path.isAbsolute(candidate))continue;const cli=fs.realpathSync(candidate),root=path.dirname(path.dirname(cli));if(path.basename(cli)==='npm-cli.js'&&path.basename(path.dirname(cli))==='bin'&&JSON.parse(fs.readFileSync(path.join(root,'package.json'),'utf8')).name==='npm'&&fs.statSync(cli).isFile())return cli;}catch{}
+ throw Error('Cannot verify npm CLI');
+}
+export function resolveInvocationCwd({env={},cwd,lifecycle=false}){
+ if(lifecycle){
+  if(env.INIT_CWD!==undefined)return realDirectory(env.INIT_CWD);
+  if(env.CODEX_HOME!==undefined&&!path.isAbsolute(env.CODEX_HOME)&&env.CODEX_HOME!=='~'&&!env.CODEX_HOME.startsWith('~/'))throw Error('Original invocation directory (INIT_CWD) is required for relative CODEX_HOME');
+ }
+ return realDirectory(cwd);
+}
+export async function inspectNpmContext({packageRoot,entryPath,env=process.env,cwd=process.cwd(),execPath=process.execPath,runNpm=defaultRunNpm}){
+ try{
+  if(fs.realpathSync(execPath)!==fs.realpathSync(process.execPath))return unsupported('Node executable does not match this runtime');
+  const root=realDirectory(packageRoot),entry=fs.realpathSync(entryPath);
+  if(!entry.startsWith(root+path.sep)||!fs.statSync(entry).isFile()||JSON.parse(fs.readFileSync(path.join(root,'package.json'),'utf8')).name!=='@yunhozz/arc')return unsupported('ARC entry is outside the package');
+  const npmCli=npmExecutable(env);
+  async function query(args){const result=await runNpm(npmCli,args,{cwd,env});if(result.code!==0||result.signal)throw Error('npm context query failed');const value=result.stdout.trim();if(!path.isAbsolute(value)||value.includes('\n'))throw Error('npm returned an invalid context path');try{return fs.realpathSync(value);}catch(error){if(error.code!=='ENOENT')throw error;return path.resolve(value);}}
+  const prefix=await query(['prefix','--global']),npmRoot=await query(['root','--global']);
+  if([path.join(prefix,'lib/node_modules'),path.join(prefix,'node_modules')].includes(npmRoot)&&root===path.join(npmRoot,'@yunhozz/arc'))return{kind:'global',packageRoot:root,entryPath:entry,prefix,npmCli};
+  if(env.npm_command==='exec'){
+   const cache=realDirectory(await query(['config','get','cache'])),relative=path.relative(path.join(cache,'_npx'),root),parts=relative.split(path.sep);
+   if(parts.length===4&&parts[0]&&parts[0]!=='.'&&parts[0]!=='..'&&parts.slice(1).join('/')==='node_modules/@yunhozz/arc'){
+    const bin=path.join(cache,'_npx',parts[0],'node_modules/.bin'),paths=(env.PATH??'').split(path.delimiter);
+    if(paths.some(value=>{try{return realDirectory(value)===realDirectory(bin);}catch{return false;}})&&realDirectory(env.INIT_CWD))return{kind:'npx',packageRoot:root,entryPath:entry,npmCli};
+   }
+  }
+  return unsupported('ARC is not in a verified global or npm exec installation');
+ }catch{return unsupported('Cannot verify npm installation context');}
+}

package/lib/npm/process.mjs

@@ -0,0 +1,17 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import {spawn} from 'node:child_process';
+function failure(message,code,cause){return Object.assign(new Error(message,{cause}),{code});}
+export async function runNpm(npmCli,args,{cwd,env,signal}={}){
+ if(signal?.aborted)throw failure('npm cancelled','ARC_NPM_CANCELLED');
+ if(!path.isAbsolute(npmCli)||!Array.isArray(args)||args.some(arg=>typeof arg!=='string'))throw failure('Invalid npm invocation','ARC_NPM_START');
+ let cli;try{cli=fs.realpathSync(npmCli);if(!fs.statSync(cli).isFile())throw Error('Not a regular file');}catch(cause){throw failure('Cannot resolve npm CLI','ARC_NPM_START',cause);}
+ return new Promise((resolve,reject)=>{
+  const child=spawn(process.execPath,[cli,...args],{cwd,env,stdio:['ignore','pipe','pipe'],shell:false});
+  const stdout=[],stderr=[];let startError,cancelled=false;
+  child.stdout.on('data',bytes=>stdout.push(bytes));child.stderr.on('data',bytes=>stderr.push(bytes));
+  const abort=()=>{cancelled=true;child.kill('SIGTERM');};signal?.addEventListener('abort',abort,{once:true});if(signal?.aborted)abort();
+  child.once('error',error=>{startError=error;});
+  child.once('close',(code,killedBy)=>{signal?.removeEventListener('abort',abort);if(cancelled)reject(failure('npm cancelled','ARC_NPM_CANCELLED'));else if(startError)reject(failure('Cannot start npm','ARC_NPM_START',startError));else resolve({code,signal:killedBy,stdout:Buffer.concat(stdout).toString('utf8'),stderr:Buffer.concat(stderr).toString('utf8')});});
+ });
+}

package/lib/npm/upgrade.mjs

@@ -0,0 +1,29 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import {spawn} from 'node:child_process';
+import {runNpm as defaultRunNpm} from './process.mjs';
+const validVersion=value=>typeof value==='string'&&/^\d+\.\d+\.\d+$/.test(value);
+function cancelled(){return Object.assign(Error('Upgrade cancelled'),{code:'ARC_CANCELLED'});}
+export async function resolveLatest({context,env,cwd,signal,runNpm=defaultRunNpm}){
+ const result=await runNpm(context.npmCli,['view','@yunhozz/arc@latest','--json'],{env,cwd,signal});
+ let value;try{value=JSON.parse(result.stdout);}catch{}
+ if(result.code!==0||result.signal||value?.name!=='@yunhozz/arc'||!validVersion(value.version))throw Error('Cannot resolve a valid latest ARC package');
+ return{name:'@yunhozz/arc',version:value.version};
+}
+export async function upgradeGlobal({context,expectedVersion,env,cwd,signal,runNpm=defaultRunNpm}){
+ if(context.kind!=='global'||!path.isAbsolute(context.prefix)||!validVersion(expectedVersion))throw Error('Invalid global upgrade version or prefix');
+ const result=await runNpm(context.npmCli,['install','--global','@yunhozz/arc@'+expectedVersion,'--prefix',context.prefix,'--ignore-scripts'],{env,cwd,signal});
+ return result.code===0&&!result.signal?{packageStatus:'updated',version:expectedVersion}:{packageStatus:'failed',error:Error('CLI replacement failed; the package may have changed')};
+}
+export async function runUpgradeChild({entryPath,request,env,cwd,signal}){
+ if(signal?.aborted)throw cancelled();
+ if(!path.isAbsolute(entryPath))throw Error('Invalid upgrade child path');
+ const entry=fs.realpathSync(entryPath);if(!fs.statSync(entry).isFile())throw Error('Invalid upgrade child');
+ return new Promise((resolve,reject)=>{
+  const child=spawn(process.execPath,[entry],{cwd,env,stdio:['pipe','pipe','pipe'],shell:false});let stdout='',stderr='',startError,aborted=false;
+  child.stdout.on('data',bytes=>{stdout+=bytes;});child.stderr.on('data',bytes=>{stderr+=bytes;});child.stdin.on('error',()=>{});
+  const abort=()=>{aborted=true;child.kill('SIGTERM');};signal?.addEventListener('abort',abort,{once:true});if(signal?.aborted)abort();
+  child.once('error',error=>{startError=error;});child.once('close',(code,killedBy)=>{signal?.removeEventListener('abort',abort);if(aborted)resolve({code:130,signal:killedBy,stdout,stderr});else if(startError)reject(Error('Cannot start the new ARC CLI',{cause:startError}));else resolve({code,signal:killedBy,stdout,stderr});});
+  child.stdin.end(JSON.stringify(request));
+ });
+}

package/lib/release/artifact.mjs

@@ -0,0 +1,163 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import {gunzipSync} from 'node:zlib';
+import {isDeepStrictEqual} from 'node:util';
+import {spawnSync} from 'node:child_process';
+import {fileURLToPath} from 'node:url';
+import {openRoot} from '../safe-fs/index.mjs';
+import {verifyPayload} from '../installer/manifest.mjs';
+import {readCheckedFile,typeOf,sameIdentity} from '../installer/targets.mjs';
+import {runNpm} from '../npm/process.mjs';
+
+const HOOKS=['preinstall','install','postinstall','prepublish','prepare','prepublishOnly','prepack','postpack','publish','postpublish','preuninstall','uninstall','postuninstall'];
+const NAME='@yunhozz/arc',HOOK='node scripts/postinstall.mjs';
+const same=(a,b)=>a.dev===b.dev&&a.ino===b.ino;
+const digest=(bytes,algorithm='sha256')=>crypto.createHash(algorithm).update(bytes).digest('hex');
+const json=file=>JSON.parse(fs.readFileSync(file,'utf8'));
+function abort(signal){if(signal?.aborted)throw new Error('Release artifact generation cancelled');}
+function inside(parent,child){const relative=path.relative(parent,child);return relative===''||(!relative.startsWith('..'+path.sep)&&relative!=='..'&&!path.isAbsolute(relative));}
+function regular(file){const stat=fs.lstatSync(file);if(!stat.isFile()||stat.isSymbolicLink())throw new Error('Expected regular release input: '+file);return stat;}
+function metadata(pkg,lock,{artifact=false}={}){
+ if(pkg.name!==NAME||!/^\d+\.\d+\.\d+$/.test(pkg.version)||pkg.private===true)throw new Error('Invalid release package identity');
+ for(const hook of HOOKS)if(pkg.scripts?.[hook]!==undefined&&!(artifact&&hook==='postinstall'&&pkg.scripts[hook]===HOOK))throw new Error('Unapproved package lifecycle: '+hook);
+ if(artifact&&pkg.scripts?.postinstall!==HOOK)throw new Error('Artifact postinstall is missing');
+ if(Object.hasOwn(pkg.scripts??{},'build')||Object.hasOwn(pkg,'workspaces'))throw new Error('Source Git preparation trigger is not allowed');
+ if(lock){
+  const root=lock.packages?.[''];if(lock.name!==pkg.name||lock.version!==pkg.version||root?.name!==pkg.name||root?.version!==pkg.version)throw new Error('Package lock identity mismatch');
+  for(const key of ['bin','dependencies','optionalDependencies','devDependencies','peerDependencies','engines'])if(!isDeepStrictEqual(root[key],pkg[key]))throw new Error('Package lock metadata mismatch: '+key);
+  if(artifact?root.hasInstallScript!==true:Object.hasOwn(root,'hasInstallScript'))throw new Error('Package lock install script metadata mismatch');
+ }
+}
+function inputNames(pkg){const names=new Set(['README.md','package.json','package-lock.json','MANIFEST.sha256']);for(const entry of pkg.files??[]){const name=entry.replace(/\/$/,'');if(!name||name.startsWith('/')||name.includes('\\')||name.split('/').some(part=>!part||part==='.'||part==='..')||/[*?\[\]]/.test(name))throw new Error('Unsupported package files entry');names.add(name);}return [...names].sort();}
+function sourceMetadata(root){
+ const directory=openRoot(root);
+ try{const result={};for(const name of ['package.json','package-lock.json']){const stat=directory.lstat(name);if(typeOf(stat)!==0o100000)throw new Error('Expected regular source metadata: '+name);result[name]=readCheckedFile(directory,name,stat).bytes;}return result;}
+ finally{directory.close();}
+}
+function inventory(root,pkg){
+ const files=new Map(),directory=openRoot(root);
+ function visit(parent,name,relative){
+  const stat=parent.lstat(name),type=typeOf(stat);
+  if(type===0o040000){
+   const child=parent.openDir(name);try{if(!sameIdentity(stat,child.stat()))throw new Error('Release source directory changed');
+    const before=child.stat();for(const leaf of child.readDir())visit(child,leaf,relative+'/'+leaf);if(!sameIdentity(before,child.stat()))throw new Error('Release source directory changed while reading');
+   }finally{child.close();}
+  }else if(type===0o100000){const item=readCheckedFile(parent,name,stat);files.set(relative,{bytes:item.bytes,mode:Number(stat.mode&0o777n)});}
+  else throw new Error('Unsafe release source file: '+relative);
+ }
+ try{
+  for(const name of inputNames(pkg)){
+   const parts=name.split('/'),opened=[];let parent=directory;
+   try{for(const part of parts.slice(0,-1)){const stat=parent.lstat(part);if(typeOf(stat)!==0o040000)throw new Error('Unsafe release source parent');const child=parent.openDir(part);opened.push(child);if(!sameIdentity(stat,child.stat()))throw new Error('Release source parent changed');parent=child;}visit(parent,parts.at(-1),name);}
+   finally{for(const child of opened.reverse())child.close();}
+  }
+ }finally{directory.close();}
+ const snapshot=digest([...files].sort(([a],[b])=>a<b?-1:a>b?1:0).map(([name,{bytes,mode}])=>name+'\0'+mode+'\0'+bytes.length+'\0'+digest(bytes)+'\n').join(''));
+ return{files,snapshot};
+}
+function refresh(root){
+ const result=spawnSync(process.execPath,[path.join(root,'scripts/update-manifest.mjs'),'--root',root],{encoding:'utf8',env:{PATH:process.env.PATH}});
+ if(result.status!==0)throw new Error('Staging manifest generation failed: '+result.stderr);
+}
+function safeOutput(sourceRoot,outDir){
+ if(!path.isAbsolute(outDir)||path.normalize(outDir)!==outDir||inside(sourceRoot,outDir))throw new Error('Release output must be an absolute directory outside source');
+ let current=path.parse(outDir).root;for(const component of outDir.slice(current.length).split(path.sep).filter(Boolean)){
+  current=path.join(current,component);try{const stat=fs.lstatSync(current);if(stat.isSymbolicLink()||!stat.isDirectory())throw new Error('Unsafe release output path');}catch(error){if(error.code!=='ENOENT')throw error;if(current!==outDir)throw new Error('Release output parent is missing');}
+ }
+ const parent=fs.realpathSync(path.dirname(outDir));if(inside(sourceRoot,parent))throw new Error('Release output resolves inside source');
+ try{fs.mkdirSync(outDir,{mode:0o700});}catch(error){if(error.code!=='EEXIST')throw error;}
+ if(fs.readdirSync(outDir).length)throw new Error('Release output is occupied or incomplete; use a new output directory');
+ return openRoot(outDir);
+}
+function readText(bytes,start,length){return bytes.subarray(start,start+length).toString('utf8').replace(/\0.*$/s,'');}
+function number(bytes,start,length){const text=readText(bytes,start,length).trim();if(!/^[0-7]*$/.test(text))throw new Error('Unsupported tar number');const value=parseInt(text||'0',8);if(!Number.isSafeInteger(value))throw new Error('Invalid tar size');return value;}
+function pax(bytes){
+ const result={};let offset=0;while(offset<bytes.length){const space=bytes.indexOf(32,offset);if(space<0)throw new Error('Malformed tar metadata');const size=Number(bytes.subarray(offset,space).toString());if(!Number.isSafeInteger(size)||size<=space-offset+1||offset+size>bytes.length)throw new Error('Malformed tar metadata');const record=bytes.subarray(space+1,offset+size).toString('utf8');if(!record.endsWith('\n'))throw new Error('Malformed tar metadata');const equal=record.indexOf('=');if(equal<1)throw new Error('Malformed tar metadata');result[record.slice(0,equal)]=record.slice(equal+1,-1);offset+=size;}return result;
+}
+function archive(bytes){
+ const raw=gunzipSync(bytes,{maxOutputLength:256*1024*1024}),files=new Map();let extended={},global={};
+ for(let offset=0;offset+512<=raw.length;){
+  const header=raw.subarray(offset,offset+512);if(header.every(byte=>byte===0))break;
+  let sum=0;for(let i=0;i<512;i++)sum+=i>=148&&i<156?32:header[i];if(sum!==number(header,148,8))throw new Error('Invalid tar header checksum');
+  const size=number(header,124,12),type=String.fromCharCode(header[156]||48),end=offset+512+size;if(end>raw.length)throw new Error('Truncated tar archive');
+  const data=raw.subarray(offset+512,end);offset+=512+Math.ceil(size/512)*512;
+  if(type==='x'||type==='g'){const values=pax(data);if(type==='g')global={...global,...values};else extended=values;continue;}
+  const attrs={...global,...extended};extended={};if(attrs.linkpath!==undefined)throw new Error('Archive links are forbidden');
+  let name=attrs.path??[readText(header,345,155),readText(header,0,100)].filter(Boolean).join('/');
+  if(name.endsWith('/'))name=name.slice(0,-1);
+  if(name!=='package'&&(!name.startsWith('package/')||name.split('/').some(part=>!part||part==='.'||part==='..')||name.includes('\\')||name.includes('\0')))throw new Error('Unsafe archive path');
+  if(type==='5')continue;if(type!=='0')throw new Error('Archive links and special files are forbidden');
+  if(name==='package'||files.has(name))throw new Error('Duplicate archive path');
+  if(attrs.size!==undefined&&Number(attrs.size)!==size)throw new Error('Unsupported tar size override');
+  files.set(name.slice(8),{bytes:Buffer.from(data),mode:number(header,100,8)&0o777});
+ }
+ if(!files.size)throw new Error('Empty release archive');return files;
+}
+function validateTarball(bytes,{expectedName,expectedVersion}){
+ const files=archive(bytes),pkgFile=files.get('package.json');if(!pkgFile)throw new Error('Artifact package metadata is missing');
+ const pkg=JSON.parse(pkgFile.bytes);metadata(pkg,undefined,{artifact:true});
+ if(pkg.name!==expectedName||pkg.version!==expectedVersion)throw new Error('Artifact package identity mismatch');
+ for(const name of ['scripts/postinstall.mjs','lib/cli/postinstall.mjs','lib/cli/terminal.mjs'])if(!files.has(name))throw new Error('Artifact runtime asset missing: '+name);
+ if(files.has('package-lock.json')||[...files.keys()].some(name=>name.split('/').some(part=>part==='.git'||part.startsWith('.arc-release'))))throw new Error('Private staging data in artifact');
+ const root=fs.mkdtempSync(path.join(fs.realpathSync(os.tmpdir()),'arc-release-verify-'));
+ try{
+  for(const[name,item]of files){const filename=path.join(root,name);fs.mkdirSync(path.dirname(filename),{recursive:true,mode:0o700});fs.writeFileSync(filename,item.bytes,{mode:item.mode});}
+  verifyPayload({packageRoot:root,safeFs:{openRoot}});
+ }finally{fs.rmSync(root,{recursive:true,force:true});}
+ return pkg;
+}
+async function pack({stagingRoot,workRoot,npmCli,signal}){
+ const packDir=path.join(workRoot,'packed'),home=path.join(workRoot,'home');fs.mkdirSync(packDir);fs.mkdirSync(home);
+ const env={PATH:process.env.PATH,HOME:home,npm_config_userconfig:path.join(home,'user.npmrc'),npm_config_globalconfig:path.join(home,'global.npmrc'),npm_config_cache:path.join(workRoot,'cache'),npm_config_offline:'true',npm_config_ignore_scripts:'true',npm_config_audit:'false',npm_config_fund:'false',npm_config_update_notifier:'false'};
+ const result=await runNpm(npmCli,['pack','--ignore-scripts','--offline','--json','--pack-destination',packDir],{cwd:stagingRoot,env,signal});
+ if(result.code!==0)throw new Error('Release npm pack failed: '+result.stderr);
+ const records=JSON.parse(result.stdout),record=Array.isArray(records)?records[0]:records[NAME];
+ if(!record||typeof record.filename!=='string'||path.basename(record.filename)!==record.filename)throw new Error('Invalid npm pack result');
+ const filename=path.join(packDir,record.filename);regular(filename);return fs.readFileSync(filename);
+}
+export async function buildReleaseArtifact({sourceRoot,outDir,npmCli,signal,deps={}}){
+ if(!path.isAbsolute(sourceRoot)||fs.realpathSync(sourceRoot)!==sourceRoot)throw new Error('Source root must be an absolute real path');
+ abort(signal);const inputs=sourceMetadata(sourceRoot),pkg=JSON.parse(inputs['package.json']),lock=JSON.parse(inputs['package-lock.json']);metadata(pkg,lock);
+ const source=inventory(sourceRoot,pkg);for(const name of ['package.json','package-lock.json'])if(!inputs[name].equals(source.files.get(name).bytes))throw new Error('Release source metadata changed during validation');
+ verifyPayload({packageRoot:sourceRoot,safeFs:{openRoot}});if(inventory(sourceRoot,pkg).snapshot!==source.snapshot)throw new Error('Release source snapshot changed during validation');
+ let output,lockIdentity,workRoot,workIdentity;const id=crypto.randomUUID(),partial='.arc-release-'+id+'.partial';let partialExists=false;
+ try{
+  output=safeOutput(sourceRoot,outDir);const lockFile=output.openFile('.arc-release.lock',{createExclusive:true,read:false});try{lockFile.writeAll(JSON.stringify({schema:1,owner:id,pid:process.pid,state:'incomplete'}));lockIdentity=lockFile.stat();lockFile.sync();}finally{lockFile.close();}
+  workRoot=fs.mkdtempSync(path.join(fs.realpathSync(path.dirname(outDir)),'.arc-release-stage-'));workIdentity=fs.lstatSync(workRoot);
+  const stagingRoot=path.join(workRoot,'package');fs.mkdirSync(stagingRoot,{mode:0o700});
+  for(const[name,item]of source.files){const filename=path.join(stagingRoot,name);fs.mkdirSync(path.dirname(filename),{recursive:true,mode:0o700});fs.writeFileSync(filename,item.bytes,{flag:'wx',mode:item.mode});}
+  const stagedPkg={...pkg,scripts:{...pkg.scripts,postinstall:HOOK}},stagedLock=structuredClone(lock);stagedLock.packages[''].hasInstallScript=true;
+  fs.writeFileSync(path.join(stagingRoot,'package.json'),JSON.stringify(stagedPkg,null,2)+'\n');fs.writeFileSync(path.join(stagingRoot,'package-lock.json'),JSON.stringify(stagedLock,null,2)+'\n');metadata(stagedPkg,stagedLock,{artifact:true});
+  fs.writeFileSync(path.join(stagingRoot,'.arc-release-staging.json'),JSON.stringify({schema:1,owner:id,state:'incomplete',sourceSnapshot:source.snapshot}));
+  refresh(stagingRoot);verifyPayload({packageRoot:stagingRoot,safeFs:{openRoot}});await deps.onStaged?.({stagingRoot,signal});abort(signal);
+  const bytes=await(deps.pack??pack)({stagingRoot,workRoot,npmCli,signal});abort(signal);validateTarball(bytes,{expectedName:pkg.name,expectedVersion:pkg.version});
+  if(inventory(sourceRoot,pkg).snapshot!==source.snapshot)throw new Error('Release source snapshot changed during generation');abort(signal);
+  const tarballPath=path.join(outDir,'arc-release.tgz'),receiptPath=path.join(outDir,'arc-release.json');
+  const receipt={schema:1,name:pkg.name,version:pkg.version,tarballPath,sha512:digest(bytes,'sha512'),sourceSnapshot:source.snapshot,verified:true};
+  const file=output.openFile(partial,{createExclusive:true,read:false});partialExists=true;try{file.writeAll(bytes);file.sync();}finally{file.close();}
+  output.renameNoReplaceTo(partial,output,'arc-release.tgz');partialExists=false;
+  const receiptFile=output.openFile(partial,{createExclusive:true,read:false});partialExists=true;try{receiptFile.writeAll(JSON.stringify(receipt,null,2)+'\n');receiptFile.sync();}finally{receiptFile.close();}
+  output.renameNoReplaceTo(partial,output,'arc-release.json');partialExists=false;output.sync();
+  if(!same(output.stat(),fs.lstatSync(outDir,{bigint:true}))||fs.lstatSync(outDir).isSymbolicLink())throw new Error('Release output directory changed');
+  return{...receipt,receiptPath};
+ }finally{
+  if(workRoot){try{if(same(workIdentity,fs.lstatSync(workRoot)))fs.rmSync(workRoot,{recursive:true,force:true});}catch(error){if(error.code!=='ENOENT')throw error;}}
+  if(output){try{if(partialExists)output.unlink(partial);if(lockIdentity&&same(lockIdentity,output.lstat('.arc-release.lock')))output.unlink('.arc-release.lock');}finally{output.close();}}
+ }
+}
+export async function verifyReleaseArtifact({outDir,expectedName,expectedVersion}){
+ if(!path.isAbsolute(outDir)||fs.realpathSync(outDir)!==outDir)throw new Error('Unsafe release output path');
+ if(fs.readdirSync(outDir).includes('.arc-release.lock'))throw new Error('Release output is locked or incomplete');
+ regular(path.join(outDir,'arc-release.json'));const receipt=json(path.join(outDir,'arc-release.json'));
+ if(receipt.schema!==1||receipt.verified!==true||receipt.name!==expectedName||receipt.version!==expectedVersion||receipt.tarballPath!==path.join(outDir,'arc-release.tgz')||!/^[a-f0-9]{128}$/.test(receipt.sha512)||!/^[a-f0-9]{64}$/.test(receipt.sourceSnapshot))throw new Error('Invalid release receipt');
+ regular(receipt.tarballPath);const bytes=fs.readFileSync(receipt.tarballPath);if(digest(bytes,'sha512')!==receipt.sha512)throw new Error('Release tarball digest mismatch');
+ validateTarball(bytes,{expectedName,expectedVersion});return receipt;
+}
+export function resolveNpmCli(){
+ const executable=process.env.npm_execpath;if(executable&&path.isAbsolute(executable)&&fs.existsSync(executable))return fs.realpathSync(executable);
+ const candidate=path.resolve(path.dirname(process.execPath),'../lib/node_modules/npm/bin/npm-cli.js');
+ if(fs.existsSync(candidate))return fs.realpathSync(candidate);throw new Error('Cannot resolve npm CLI; use npm run pack:release');
+}
+export const releaseSourceRoot=path.resolve(fileURLToPath(new URL('../../',import.meta.url)));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yunhozz/arc",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "publishConfig": {
     "access": "public",
     "registry": "https://registry.npmjs.org/"
@@ -14,7 +14,8 @@
     "build:native": "node scripts/build-native.mjs",
     "check:manifest": "node scripts/update-manifest.mjs --check",
     "update:role-policy": "node scripts/update-role-policy.mjs",
-    "check:role-policy": "node scripts/update-role-policy.mjs --check"
+    "check:role-policy": "node scripts/update-role-policy.mjs --check",
+    "pack:release": "node scripts/pack-release.mjs"
   },
   "devDependencies": {
     "node-gyp": "11.5.0",

package/scripts/pack-release.mjs

@@ -0,0 +1,9 @@
+import {buildReleaseArtifact,resolveNpmCli,releaseSourceRoot} from '../lib/release/artifact.mjs';
+const args=process.argv.slice(2),controller=new AbortController();
+const cancel=()=>controller.abort();process.once('SIGINT',cancel);process.once('SIGTERM',cancel);
+try{
+ if(args.length!==2||args[0]!=='--out-dir')throw Error('Usage: npm run pack:release -- --out-dir <absolute-output-directory>');
+ const result=await buildReleaseArtifact({sourceRoot:releaseSourceRoot,outDir:args[1],npmCli:resolveNpmCli(),signal:controller.signal});
+ console.log(JSON.stringify(result,null,2));
+}catch(error){console.error('Release artifact error: '+error.message);process.exitCode=controller.signal.aborted?130:1;}
+finally{process.removeListener('SIGINT',cancel);process.removeListener('SIGTERM',cancel);}

package/scripts/postinstall.mjs

@@ -0,0 +1,4 @@
+import {fileURLToPath} from 'node:url';
+import {runPostinstall} from '../lib/cli/postinstall.mjs';
+const packageRoot=fileURLToPath(new URL('../',import.meta.url));
+process.exitCode=await runPostinstall({packageRoot,cwd:packageRoot});