@redue/cli 0.0.0-stage → 0.1.0-alpha.11

package/src/linux-observer.mjs

@@ -0,0 +1,79 @@
+import path from 'node:path';
+import {spawn} from 'node:child_process';
+import {fileURLToPath} from 'node:url';
+import {randomUUID} from 'node:crypto';
+
+const helper=path.join(path.dirname(fileURLToPath(import.meta.url)),'linux-inotify.py');
+const fault=(reason,code)=>Object.assign(Error(reason),{code:code||reason});
+
+export function subscribeLinux(root,callback) {
+  return new Promise((resolve,reject)=>{
+    const child=spawn('python3',['-u',helper,root],
+      {stdio:['pipe','pipe','ignore']});
+    let ready=false,closing=false,ended=false,buffer='',last=Date.now();
+    const barriers=new Map();
+    const startup=setTimeout(()=>fail(fault('Linux observer startup timed out')),10000);
+    const heartbeat=setInterval(()=>{
+      if(ready&&!closing&&!barriers.size&&Date.now()-last>4000)
+        fail(fault('Linux observer heartbeat unavailable'));
+    },1000);
+    const cleanup=()=>{clearTimeout(startup);clearInterval(heartbeat);
+      for(const [id,pending] of barriers){clearTimeout(pending.timer);
+        pending.reject(fault('Linux observer unavailable'));barriers.delete(id);}};
+    const fail=error=>{
+      if(ended)return;ended=true;cleanup();
+      if(!ready)reject(error);else if(!closing)callback(error,[]);
+      child.kill('SIGTERM');
+    };
+    const request=(kind,fields={},timeoutMs=5000)=>{
+      if(ended||closing)return Promise.reject(fault('Linux observer unavailable'));
+      return new Promise((done,no)=>{
+        const id=randomUUID();const timer=setTimeout(()=>{
+          barriers.delete(id);no(fault(`Linux observer ${kind} timed out`));
+          fail(fault(`Linux observer ${kind} timed out`));
+        },timeoutMs);
+        barriers.set(id,{resolve:done,reject:no,timer});
+        child.stdin.write(JSON.stringify({kind,id,...fields})+'\n');
+      });
+    };
+    child.on('error',fail);
+    child.stdin.on('error',fail);
+    child.stdout.on('error',fail);
+    child.on('exit',(code,signal)=>{
+      if(!closing&&!ended)fail(fault(`Linux observer exited: ${code??signal}`));
+      else cleanup();
+    });
+    child.stdout.on('data',data=>{
+      buffer+=data.toString();
+      if(buffer.length>1024*1024){fail(fault('Linux observer output backlog'));return;}
+      for(;;){const end=buffer.indexOf('\n');if(end<0)break;
+        const line=buffer.slice(0,end);buffer=buffer.slice(end+1);
+        let message;try{message=JSON.parse(line);}catch{fail(fault('Linux observer protocol error'));return;}
+        last=Date.now();
+        if(message.kind==='ready'){
+          ready=true;clearTimeout(startup);
+          resolve({
+            synchronize(timeoutMs=5000){return request('barrier',{},timeoutMs);},
+            watchFiles(paths,timeoutMs=30000){
+              return request('watch-files',{paths},timeoutMs);
+            },
+            async unsubscribe(){
+              if(closing)return;closing=true;cleanup();child.stdin.end();
+              if(ended||child.exitCode!==null||child.signalCode!==null)return;
+              const exit=new Promise(done=>child.once('exit',done));
+              child.kill('SIGTERM');
+              const killer=setTimeout(()=>child.kill('SIGKILL'),1000);
+              await exit;clearTimeout(killer);
+            },
+            get pid(){return child.pid;}
+          });
+        }else if(message.kind==='event')callback(null,[{type:message.type,path:message.path}]);
+        else if(message.kind==='gap'){fail(fault(message.reason,message.reason));return;}
+        else if(message.kind==='barrier'||message.kind==='watched'){
+          const pending=barriers.get(message.id);if(!pending)continue;
+          barriers.delete(message.id);clearTimeout(pending.timer);pending.resolve();
+        }else if(message.kind!=='heartbeat'){fail(fault('Linux observer protocol error'));return;}
+      }
+    });
+  });
+}

package/src/node-onboarding.mjs

@@ -0,0 +1,274 @@
+import {directProject,directQualification} from './direct-typescript.mjs';
+import fs from 'node:fs';
+import path from 'node:path';
+import {spawnSync} from 'node:child_process';
+import micromatch from './glob.mjs';
+import {yarnWorkspaceTypecheckInputs} from './yarn-workspace-inputs.mjs';
+import {pnpmInstallInfo,pnpmProjectInfo,pnpmTypecheckInputs} from './pnpm-inputs.mjs';
+import {realObservedPath} from './path-identity.mjs';
+import {findExecutable} from './executable-lookup.mjs';
+
+const exists=file=>{try{fs.accessSync(file);return true;}catch{return false;}};
+const readJson=file=>JSON.parse(fs.readFileSync(file,'utf8'));
+const scriptNames={
+  typecheck:['typecheck','type-check','check:types','types:check'],
+  test:['test','test:unit','test:check'],
+  lint:['lint','lint:check'],
+  build:['build'],
+};
+const sourceExtensions='**/*.{ts,tsx,mts,cts,js,jsx,mjs,cjs,json,jsonc}';
+const likelyDirs=['src','app','apps','pages','lib','packages','test','tests','__tests__','scripts'];
+const toolConfigs=['tsconfig.json','tsconfig.base.json','vite.config.ts','vite.config.js',
+  'vitest.config.ts','vitest.config.js','jest.config.js','jest.config.ts',
+  'eslint.config.js','eslint.config.mjs','.eslintrc','.eslintrc.json',
+  '.eslintrc.js','.npmrc','.yarnrc.yml'];
+function installedNpmVersion() {
+  try{
+    const executable=findExecutable('npm');
+    if(!executable)return null;
+    const manifest=readJson(process.platform==='win32'?
+      path.join(path.dirname(executable),'node_modules','npm','package.json'):
+      path.join(path.dirname(path.dirname(executable)),'package.json'));
+    if(manifest.name==='npm')return manifest.version;
+  }catch{}
+  return null;
+}
+
+function manager(root,pkg) {
+  const declared=pkg.packageManager?.match(/^(npm|yarn|pnpm|bun)@([^+\s]+)/);
+  const locks=['package-lock.json','npm-shrinkwrap.json','yarn.lock','pnpm-lock.yaml',
+    'bun.lock','bun.lockb'].filter(name=>exists(path.join(root,name)));
+  const kinds=new Set(locks.map(name=>name.startsWith('package-lock')||name==='npm-shrinkwrap.json'?
+    'npm':name==='yarn.lock'?'yarn':name.startsWith('pnpm')?'pnpm':'bun'));
+  if(declared)kinds.add(declared[1]);
+  if(kinds.size!==1)return {name:null,version:declared?.[2]||null,layout:'unknown',
+    issue:kinds.size?'package-manager declaration conflicts with lockfiles':
+      'no supported lockfile or packageManager declaration'};
+  const name=[...kinds][0],version=declared?.[1]===name?declared[2]:null;
+  if(name==='bun')return {name,version,layout:'unsupported',
+    issue:'bun installation layout is not supported in this alpha'};
+  if(name==='pnpm'){
+    try{const installed=pnpmInstallInfo(root);
+      return {name,version:installed.version,
+        layout:`node-modules/${installed.linker}`,issue:null,lockfiles:locks,
+        workspacePatterns:installed.patterns};}
+    catch(e){let project;try{project=pnpmProjectInfo(root);}catch{}
+      return {name,version:project?.version||version,
+        layout:project?.linker||'recording-only',issue:e.message,
+        lockfiles:locks,workspacePatterns:project?.patterns||[]};}
+  }
+  if(name==='npm')return {name,version:version||installedNpmVersion(),
+    layout:'node-modules',issue:null,
+    lockfiles:locks};
+  const yarnrc=path.join(root,'.yarnrc.yml');
+  if(!exists(yarnrc)){
+    const classicLock=exists(path.join(root,'yarn.lock'))&&
+      /^# yarn lockfile v1\s*$/m.test(fs.readFileSync(path.join(root,'yarn.lock'),'utf8').slice(0,256));
+    const classic=version?.startsWith('1.')||(!version&&classicLock);
+    return {name,version:version||null,layout:classic?'node-modules':'unknown',
+      issue:!version?'Yarn version is not declared; Corepack may select a different version or edit package.json':
+        classic?null:'Yarn linker is not declared; node-modules layout cannot be assumed',
+      lockfiles:locks};
+  }
+  const text=fs.readFileSync(yarnrc,'utf8');
+  const linker=text.match(/^\s*nodeLinker\s*:\s*['"]?([\w-]+)/m)?.[1];
+  const mode=text.match(/^\s*nmMode\s*:\s*['"]?([\w-]+)/m)?.[1]||'classic';
+  if(linker!=='node-modules')return {name,version,layout:linker||'unknown',
+    issue:`Yarn ${linker||'unspecified'} linker is outside the node-modules alpha path`,
+    lockfiles:locks};
+  if(mode!=='classic')return {name,version,layout:`node-modules/${mode}`,
+    issue:`Yarn nmMode ${mode} is not yet observed safely`,lockfiles:locks};
+  return {name,version,layout:'node-modules/classic',issue:null,lockfiles:locks};
+}
+const exactTypeScript=script=>script.trim()==='tsc --noEmit';
+function sourceLinkIssue(root) {
+  const stack=likelyDirs.filter(name=>exists(path.join(root,name)));
+  let inspected=0;
+  while(stack.length){
+    const rel=stack.pop(),full=path.join(root,rel);
+    if(fs.lstatSync(full).isSymbolicLink())
+      return `${rel} is a source link; declare its permitted observation boundary explicitly`;
+    let entries;try{entries=fs.readdirSync(full,{withFileTypes:true});}
+    catch{return `${rel} cannot be inspected; source input coverage needs review`;}
+    for(const entry of entries){
+      if(++inspected>100000)return 'source tree is too large for init link inspection';
+      const child=`${rel}/${entry.name}`;
+      if(entry.isSymbolicLink())return `${child} is a source link; declare its permitted observation boundary explicitly`;
+      if(entry.isDirectory()&&!['.git','node_modules'].includes(entry.name))stack.push(child);
+    }
+  }
+  return null;
+}
+function sourceInputs(root,kind,lockfiles) {
+  const files=['package.json',...lockfiles,...toolConfigs.filter(name=>exists(path.join(root,name)))];
+  if(kind==='typecheck')return [...new Set(['package.json',...lockfiles,
+    'tsconfig.json',sourceExtensions,
+    '!node_modules/**','!.git/**'])];
+  const dirs=likelyDirs.filter(name=>exists(path.join(root,name)))
+    .map(name=>`${name}/**`);
+  return [...new Set([...files,...(dirs.length?dirs:['package.json'])])];
+}
+function classify(kind,scriptName,script,pkg,managerInfo,root) {
+  const value=script.trim();
+  if(managerInfo.issue)return {level:managerInfo.name==='pnpm'?'recording':'unsupported',
+    reason:managerInfo.issue};
+  if(kind==='typecheck'&&exactTypeScript(value)&&
+    !pkg.scripts?.['pre'+scriptName]&&!pkg.scripts?.['post'+scriptName]&&
+    managerInfo.name==='npm'&&
+    exists(path.join(root,'tsconfig.json'))&&
+    exists(path.join(root,'node_modules/typescript/package.json')))
+    return {level:'recording',reason:'npm launcher uses unobserved remote/cache/time inputs; execution can be recorded, but cannot be reused',
+      qualification:'typescript-noemit-v1'};
+  if(kind==='typecheck')return {level:'recording',reason:
+    'TypeScript invocation, installation, or configuration is outside the automatic noEmit contract'};
+  if(kind==='test')return {level:'recording',reason:/\b(vitest|jest)\b/.test(value)?
+    'test framework detected; caches, transforms and runtime inputs need review':
+    'test script detected; runtime and generated inputs need review'};
+  if(kind==='lint')return {level:'recording',reason:/\beslint\b/.test(value)?
+    'ESLint detected; plugin/config and resolver inputs need review':
+    'lint script detected; tool and config inputs need review'};
+  return {level:'recording',reason:/\bvite\b/.test(value)?
+    'Vite detected; build environment and generated inputs need review':
+    'build script detected; generated and runtime inputs need review'};
+}
+function selectScript(kind,names,scripts) {
+  const preferred=names.find(name=>typeof scripts[name]==='string'&&
+    scripts[name].trim()&&!/^echo\s+["']?Error: no test specified/.test(scripts[name]));
+  if(preferred)return {script:preferred};
+  const candidates=Object.keys(scripts).filter(name=>{
+    const value=scripts[name]?.trim();
+    if(typeof value!=='string')return false;
+    if(kind==='typecheck')return exactTypeScript(value);
+    if(kind==='test')return /^(?:vitest|jest)(?:\s|$)/.test(value);
+    if(kind==='lint')return /^eslint(?:\s|$)/.test(value);
+    return /^vite\s+build(?:\s|$)/.test(value);
+  });
+  return candidates.length===1?{script:candidates[0]}:
+    candidates.length>1?{ambiguous:candidates}:{};
+}
+function workspaceManifests(root,patterns) {
+  const listing=spawnSync('git',['ls-files','--cached','--others','--exclude-standard',
+    '-z','--',':(glob)**/package.json'],{cwd:root,encoding:'utf8',timeout:5000,
+    maxBuffer:32*1024*1024,stdio:['ignore','pipe','ignore'],
+    env:{...process.env,GIT_OPTIONAL_LOCKS:'0'}});
+  if(listing.status!==0||listing.error)throw Error('workspace package manifests cannot be inspected');
+  const matched=listing.stdout.split('\0').filter(Boolean).filter(file=>{
+    const dir=path.posix.dirname(file);
+    return dir!=='.'&&!dir.split('/').includes('node_modules')&&
+      micromatch.isMatch(dir,patterns,{dot:true});
+  }).sort();
+  if(matched.length>50)throw Error('more than 50 workspace packages found; select checks explicitly');
+  return matched.map(file=>({file,pkg:readJson(path.join(root,file))}));
+}
+export function discoverNodeProject(root,{recipe=null}={}) {
+  if(recipe&&recipe!=='typescript-direct')throw Error('unknown recipe; use typescript-direct');
+  root=realObservedPath(root);
+  const packageFile=path.join(root,'package.json');
+  if(!exists(packageFile))throw Error('run init from a repository containing package.json');
+  const pkg=readJson(packageFile),pm=manager(root,pkg),scripts=pkg.scripts||{};
+  const git=spawnSync('git',['rev-parse','--show-toplevel'],{cwd:root,
+    encoding:'utf8',timeout:3000,stdio:['ignore','pipe','ignore']});
+  const repositoryIssue=git.status===0?null:
+    'Git checkout is unavailable; filesystem observation needs a checkout';
+  const observationIssue=repositoryIssue||sourceLinkIssue(root);
+  const workspacePatterns=pm.name==='pnpm'?pm.workspacePatterns:
+    Array.isArray(pkg.workspaces)?pkg.workspaces:pkg.workspaces?.packages;
+  const workspaces=Boolean(pkg.workspaces)||Boolean(workspacePatterns?.length);
+  if(workspaces&&(!Array.isArray(workspacePatterns)||
+    workspacePatterns.some(value=>typeof value!=='string'||path.isAbsolute(value)||
+      value.split('/').includes('..'))))
+    throw Error('workspace patterns need a supported project-relative package list');
+  const checks=[],ambiguous=[];
+  for(const [kind,names] of Object.entries(scriptNames)) {
+    const selected=selectScript(kind,names,scripts),script=selected.script;
+    if(selected.ambiguous)ambiguous.push({kind,scripts:selected.ambiguous});
+    if(!script)continue;
+    let classification=observationIssue?{level:'unsupported',reason:observationIssue}:
+      classify(kind,script,scripts[script],pkg,pm,root);
+    if(workspaces&&classification.qualification==='typescript-noemit-v1')classification={level:'recording',
+      reason:'workspace task and installed-input closure need explicit qualification'};
+    const check={name:kind,script,kind,inputs:sourceInputs(root,kind,pm.lockfiles||[])};
+    if(recipe==='typescript-direct'&&kind==='typecheck'){
+      try{
+        if(pm.name!=='npm'||workspaces||observationIssue||pm.issue)throw Error('direct recipe requires a supported single-package npm checkout');
+        const compiler=directProject(root,script);
+        check.command=['@node','@typescript-compiler:.','--noEmit'];check.cwd='.';
+        classification={level:'ready',qualification:directQualification,
+          reason:`explicit local TypeScript ${compiler.version} compilation; npm launcher/lifecycle scripts are not executed; package.json stays unchanged`};
+      }catch(e){classification={level:'recording',reason:`Direct recipe unavailable (${e.code||e.message}); original npm script retained, without bypassing required behavior`};}
+    }
+    if(pm.name==='pnpm'&&kind==='typecheck'&&!workspaces&&!pm.issue&&
+      /^(?:tsc --noEmit|tsc -p (?:\.|tsconfig\.json)(?: --noEmit)?)$/.test(scripts[script].trim())){
+      try{const contract=pnpmTypecheckInputs(root,'.',script);
+        if(contract.limitations.length)throw Error(contract.limitations.join('; '));
+        check.command=['@node','@typescript-bin:.',
+          ...scripts[script].trim().split(/\s+/).slice(1)];
+        check.cwd='.';
+        check.inputs=['package.json','pnpm-lock.yaml',
+          ...(exists(path.join(root,'pnpm-workspace.yaml'))?['pnpm-workspace.yaml']:[]),
+          'tsconfig.json','src/**'];
+        classification={level:'ready',reason:'pinned pnpm TypeScript inputs and installation; checked again before reuse',
+          qualification:'pnpm-tsc-v1'};}
+      catch(e){classification={level:'recording',reason:`pnpm TypeScript contract needs review: ${e.message}`};}
+    }
+    if(classification.qualification)check.qualification=classification.qualification;
+    checks.push({config:check,...classification});
+  }
+  if(workspaces&&!observationIssue){
+    const seen=new Set();
+    for(const {file,pkg:member} of workspaceManifests(root,workspacePatterns)){
+      const dir=path.posix.dirname(file),name=member.name;
+      if(typeof name!=='string'||!name||seen.has(name)){
+        ambiguous.push({kind:'workspace',scripts:[dir],reason:'missing or duplicate package name'});
+        continue;
+      }
+      seen.add(name);
+      if(!['npm','yarn','pnpm'].includes(pm.name))continue;
+      for(const [kind,names] of Object.entries(scriptNames)){
+        const selected=selectScript(kind,names,member.scripts||{});
+        if(selected.ambiguous){ambiguous.push({kind:`${name}:${kind}`,
+          scripts:selected.ambiguous});continue;}
+        if(!selected.script)continue;
+        const command=pm.name==='npm'?['@which:npm','run',selected.script,
+          '--workspace',name]:pm.name==='yarn'?
+          ['@which:yarn','workspace',name,'run',selected.script]:
+          ['@which:pnpm','--filter',name,'run',selected.script];
+        const check={name:`${name}:${kind}`,kind,command,
+          inputs:['package.json',...(pm.lockfiles||[]),`${dir}/**`,
+            `!${dir}/node_modules/**`]};
+        let level=pm.issue&&pm.name!=='pnpm'?'unsupported':'recording';
+        let reason=pm.issue||'workspace script found; shared configuration and installed inputs need review';
+        if(!pm.issue&&pm.name==='yarn'&&pm.layout==='node-modules/classic'&&
+          kind==='typecheck'&&(member.scripts||{})[selected.script]?.trim()==='tsc -p .'&&
+          !member.scripts?.['pre'+selected.script]&&!member.scripts?.['post'+selected.script]){
+          try{
+            yarnWorkspaceTypecheckInputs(root,name,selected.script);
+            check.workspace=name;check.qualification='yarn-workspace-tsc-v1';
+            check.inputs=['package.json','yarn.lock','.yarnrc.yml',file,`${dir}/src/**`];
+            level='ready';reason='pinned Yarn workspace tsc and installed inputs; checked again before reuse';
+          }catch(e){reason=`workspace TypeScript contract needs review: ${e.message}`;}
+        }
+        if(!pm.issue&&pm.name==='pnpm'&&kind==='typecheck'&&
+          /^(?:tsc --noEmit|tsc -p (?:\.|tsconfig\.json)(?: --noEmit)?)$/.test(
+            (member.scripts||{})[selected.script]?.trim()||'')&&
+          !member.scripts?.['pre'+selected.script]&&!member.scripts?.['post'+selected.script]){
+          try{const contract=pnpmTypecheckInputs(root,name,selected.script);
+            if(contract.limitations.length)throw Error(contract.limitations.join('; '));
+            check.workspace=name;check.qualification='pnpm-tsc-v1';
+            check.script=selected.script;
+            check.cwd=dir;
+            check.command=['@node',`@typescript-bin:${dir}`,
+              ...member.scripts[selected.script].trim().split(/\s+/).slice(1)];
+            check.inputs=['package.json','pnpm-lock.yaml','pnpm-workspace.yaml',file,
+              `${dir}/src/**`];
+            level='ready';reason='pinned pnpm workspace TypeScript inputs; checked again before reuse';
+          }catch(e){reason=`pnpm TypeScript contract needs review: ${e.message}`;}
+        }
+        checks.push({config:check,level,reason});
+      }
+    }
+  }
+  return {schema:1,root,manager:pm,observationIssue,workspaces,node:process.version,
+    checks,ambiguous,
+    config:{schema:1,packageManager:pm.name||'unknown',checks:checks.map(row=>row.config)}};
+}

package/src/npm-typecheck-environment.mjs

@@ -0,0 +1,36 @@
+// Admission for the standalone npm 10.9.2 -> tsc --noEmit contract only.
+// Values are never returned: the caller separately fingerprints every original
+// npm_config_* key/value (including case and empty values).
+import path from 'node:path';
+export const npmEnvironmentInterpretation = 'npm-tsc-environment@2';
+const proxyKeys = new Set(['proxy', 'https_proxy', 'http_proxy', 'noproxy']);
+export function npmTypecheckEnvironmentIssue(env, {npmVersion, platform = process.platform} = {}) {
+  if (env.NODE_OPTIONS || env.NODE_PATH || env.BASH_ENV || env.ENV)
+    return 'execution-environment-unsupported';
+  const seen = new Map();
+  for (const [key, value] of Object.entries(env)) {
+    if (/^(DYLD_|TSGO_)/i.test(key)) return 'execution-environment-unsupported';
+    if (!/^npm_config_/i.test(key)) continue;
+    if (/^npm_config_prefix$/i.test(key) && platform === 'win32' && path.win32.isAbsolute(value)) continue;
+    const suffix = key.slice('npm_config_'.length).toLowerCase();
+    if (!proxyKeys.has(suffix)) return 'execution-environment-unsupported';
+    // http_proxy is an unknown, inert pass-through key in this inspected npm
+    // version, not an alias for proxy. Other npm versions require source review.
+    if (npmVersion !== '10.9.2') return 'npm-proxy-version-unsupported';
+    if (seen.has(suffix) && seen.get(suffix) !== value)
+      return 'npm-proxy-context-ambiguous';
+    seen.set(suffix, value);
+    if (typeof value !== 'string' || /[\x00-\x1f\x7f]/.test(value))
+      return 'npm-proxy-value-unsupported';
+    // npm ignores empty environment config, but passes the original environment
+    // to the child. Empty and absent remain distinct caller identities.
+    if (value === '' || (suffix === 'proxy' && value === 'false')) continue;
+    if (suffix === 'noproxy') continue;
+    try {
+      const url = new URL(value);
+      if (!['http:', 'https:'].includes(url.protocol) || !url.hostname)
+        return 'npm-proxy-value-unsupported';
+    } catch { return 'npm-proxy-value-unsupported'; }
+  }
+  return null;
+}

package/src/npm-typecheck-probe.mjs

@@ -0,0 +1,120 @@
+#!/usr/bin/env node
+// Read-only reviewed boundary for an npm script invoking local TypeScript.
+// A nonzero exit withdraws applicability. Output is a digest, never config values.
+import fs from 'node:fs';
+import path from 'node:path';
+import {createHash} from 'node:crypto';
+import {spawnSync} from 'node:child_process';
+import {fileURLToPath} from 'node:url';
+
+const [rootArg,nodeArg,npmArg,reviewedTsconfigHash,npmVersion,typescriptVersion]=process.argv.slice(2);
+const sha=value=>createHash('sha256').update(value).digest('hex');
+const inside=(file,dir)=>file===dir||file.startsWith(dir+path.sep);
+const fail=reason=>{throw Error(`typecheck boundary unavailable: ${reason}`);};
+const real=file=>fs.realpathSync(file);
+function fileHash(file){
+  const digest=createHash('sha256'),fd=fs.openSync(file,'r'),buffer=Buffer.alloc(1024*1024);
+  try{for(;;){const count=fs.readSync(fd,buffer,0,buffer.length,null);
+    if(!count)break;digest.update(buffer.subarray(0,count));}}
+  finally{fs.closeSync(fd);}
+  return digest.digest('hex');
+}
+function treeHash(dir){
+  const digest=createHash('sha256');
+  function visit(folder,relative=''){
+    for(const entry of fs.readdirSync(folder,{withFileTypes:true}).sort((a,b)=>
+      a.name.localeCompare(b.name))){
+      const rel=relative?relative+'/'+entry.name:entry.name,full=path.join(folder,entry.name);
+      if(entry.isDirectory()){digest.update(`d\0${rel}\0`);visit(full,rel);}
+      else if(entry.isFile())digest.update(`f\0${rel}\0${fileHash(full)}\0`);
+      else fail('npm installation contains an unsupported entry');
+    }
+  }
+  visit(dir);return digest.digest('hex');
+}
+function namesAt(dir){
+  if(!fs.existsSync(dir))return null;
+  if(!fs.statSync(dir).isDirectory())fail('ancestor resolution boundary is not a directory');
+  const names=[];
+  for(const entry of fs.readdirSync(dir,{withFileTypes:true}).sort((a,b)=>
+    a.name.localeCompare(b.name))){
+    names.push(entry.name);
+    if(entry.name.startsWith('@')&&entry.isDirectory())
+      names.push(...fs.readdirSync(path.join(dir,entry.name)).map(name=>entry.name+'/'+name).sort());
+  }
+  return names;
+}
+function rcKeys(file){
+  if(!fs.existsSync(file))return null;
+  const keys=[];
+  for(const line of fs.readFileSync(file,'utf8').split(/\r?\n/)){
+    const trimmed=line.trim();
+    if(!trimmed||trimmed.startsWith('#')||trimmed.startsWith(';'))continue;
+    const at=trimmed.indexOf('=');
+    if(at<0)fail('npm configuration has an unsupported entry');
+    const key=trimmed.slice(0,at).trim();
+    // These affect package acquisition, not this offline `npm run typecheck`.
+    if(key!=='registry'&&!/^\/\/[^\s]+\/:_authToken$/.test(key))
+      fail('npm configuration contains an unreviewed key');
+    keys.push(key);
+  }
+  return keys.sort();
+}
+function pathExecutable(name){
+  for(const folder of (process.env.PATH||'').split(path.delimiter)){
+    if(!folder)continue;
+    const candidate=path.join(folder,name);
+    try{fs.accessSync(candidate,fs.constants.X_OK);return real(candidate);}catch{}
+  }
+  return null;
+}
+try{
+  if(!rootArg||!nodeArg||!npmArg||!reviewedTsconfigHash||!npmVersion||!typescriptVersion)
+    fail('arguments missing');
+  const root=real(rootArg),node=real(nodeArg),npm=real(npmArg),home=process.env.HOME;
+  if(!home||!path.isAbsolute(home))fail('HOME is unavailable');
+  const homeTarget=real(home);
+  if(real(process.execPath)!==node||pathExecutable('node')!==node)
+    fail('npm shebang would use a different Node executable');
+  if(process.env.NODE_OPTIONS||process.env.NODE_PATH||process.env.BASH_ENV||process.env.ENV)
+    fail('unreviewed Node or shell preload environment');
+  if(Object.keys(process.env).some(key=>key.toLowerCase().startsWith('npm_config_')))
+    fail('npm configuration environment override');
+  if(Object.keys(process.env).some(key=>key.startsWith('DYLD_')||key.startsWith('TSGO_')))
+    fail('unreviewed native runtime environment');
+  const npmRoot=path.dirname(path.dirname(npm)),prefix=path.dirname(path.dirname(path.dirname(npmRoot)));
+  if(path.basename(npmRoot)!=='npm'||path.basename(path.dirname(npmRoot))!=='node_modules')
+    fail('npm installation layout changed');
+  if(JSON.parse(fs.readFileSync(path.join(npmRoot,'package.json'),'utf8')).version!==npmVersion||
+    JSON.parse(fs.readFileSync(path.join(root,'node_modules/typescript/package.json'),'utf8'))
+      .version!==typescriptVersion)fail('reviewed npm or TypeScript version changed');
+  const pkg=JSON.parse(fs.readFileSync(path.join(root,'package.json'),'utf8'));
+  if(pkg.scripts?.typecheck!=='tsc --noEmit'||pkg.scripts?.pretypecheck||pkg.scripts?.posttypecheck)
+    fail('typecheck script or lifecycle changed');
+  const tsconfig=path.join(root,'tsconfig.json');
+  if(fileHash(tsconfig)!==reviewedTsconfigHash)fail('TypeScript configuration needs review');
+  const tsc=real(path.join(root,'node_modules','.bin','tsc'));
+  if(tsc!==path.join(root,'node_modules','typescript','bin','tsc'))
+    fail('typecheck executable does not resolve to local TypeScript');
+  const listed=spawnSync(tsc,['--noEmit','--listFilesOnly'],{cwd:root,env:process.env,
+    encoding:'utf8',timeout:10000,maxBuffer:4*1024*1024,stdio:['ignore','pipe','pipe']});
+  if(listed.error||listed.signal||listed.status!==0)fail('TypeScript input listing unavailable');
+  const files=listed.stdout.trim().split(/\r?\n/).filter(Boolean).map(file=>path.resolve(file));
+  if(!files.length||files.some(file=>!inside(file,root)||
+    !(inside(file,path.join(root,'src'))||file===path.join(root,'vite.config.ts')||
+      inside(file,path.join(root,'node_modules')))))
+    fail('TypeScript consumes an input outside the observed file sets');
+  const ancestors=[];
+  for(let dir=path.dirname(root);;dir=path.dirname(dir)){
+    ancestors.push([dir,namesAt(path.join(dir,'node_modules'))]);
+    if(dir===path.dirname(dir))break;
+  }
+  const configFiles=[path.join(root,'.npmrc'),path.join(home,'.npmrc'),
+    path.join(prefix,'etc','npmrc')];
+  const npmConfig=configFiles.map(file=>[file,rcKeys(file)]);
+  // Metadata alone is insufficient for the installed npm CLI and native tools.
+  const fingerprint=sha(JSON.stringify({schema:1,probe:fileHash(fileURLToPath(import.meta.url)),
+    homeTarget,files:files.sort(),ancestors,
+    npmConfig,npmTree:treeHash(npmRoot),node:fileHash(node),shell:fileHash('/bin/sh')}));
+  process.stdout.write(fingerprint);
+}catch(e){console.error(e.message);process.exitCode=2;}

package/src/observation.mjs

@@ -0,0 +1,59 @@
+import fs from 'node:fs';
+import {mark,traceEnvironment} from './decision-profile.mjs';
+import path from 'node:path';
+import {randomUUID} from 'node:crypto';
+import {fork} from 'node:child_process';
+import {fileURLToPath} from 'node:url';
+
+// Observation contract: live notifications establish continuity only while the
+// subscription is healthy; history may accelerate catch-up; a fresh scan is
+// the deterministic fallback. A failed history operation never updates cursor.
+const workerFile=path.join(path.dirname(fileURLToPath(import.meta.url)),'history-worker.mjs');
+// Each query runs in a fresh helper: a reused native history session can take
+// ten times longer. The next helper is forked once a query settles, so its
+// startup is off the decision path. A failed or late helper is killed.
+let spare=null,queue=Promise.resolve(),closed=false;
+// After the observer's last query no helper is kept or started.
+export function closeHistory() {closed=true;spare?.kill('SIGKILL');spare=null;}
+function startHelper() {
+  const child=fork(workerFile,[],{stdio:['ignore','ignore','ignore','ipc'],env:traceEnvironment()});
+  child.abandoned=new Set();child.on('error',()=>{});
+  child.once('exit',()=>{if(spare===child)spare=null;
+    child.reply?.({ok:false,lost:Error(`history helper exited ${child.exitCode??child.signalCode}`)});
+    for(const next of child.abandoned)try{fs.unlinkSync(next);}catch{}});
+  return child;
+}
+export function history(root,cursor,backend,deadlineMs,faultFile) {
+  const run=()=>query(root,cursor,backend,deadlineMs,faultFile);
+  const result=queue.then(run,run);queue=result.catch(()=>{});return result;
+}
+function query(root,cursor,backend,deadlineMs,faultFile) {
+  const next=cursor+'.'+randomUUID()+'.next';
+  return new Promise((resolve,reject)=>{
+    mark('history.submit',{deadlineMs});
+    const worker=spare??startHelper();spare=null;
+    worker.ref();worker.channel?.ref();
+    let settled=false;
+    const finish=(error,value)=>{
+      if(settled)return;settled=true;worker.reply=null;clearTimeout(timer);
+      mark('history.complete',{childPid:worker.pid,outcome:error?.code||error?.name||'ok',events:value?.length});
+      if(error)worker.abandoned.add(next);
+      worker.kill('SIGKILL');
+      // A failed query disables history for this observer; keep no helper.
+      if(!closed&&!error){spare=startHelper();spare.unref();spare.channel?.unref();}
+      if(error){try{fs.unlinkSync(next);}catch{}
+        reject(error);return;}
+      try{fs.renameSync(next,cursor);resolve(value);}
+      catch(e){try{fs.unlinkSync(next);}catch{}reject(e);}
+    };
+    const timer=setTimeout(()=>{
+      const e=Error(`history query did not settle within ${deadlineMs} ms`);
+      e.code='ETIMEDOUT';finish(e);
+    },deadlineMs);
+    worker.reply=message=>message.lost?finish(message.lost):message.ok?finish(null,message.changes):
+      finish(Object.assign(Error(message.error),{code:message.code}));
+    worker.on('message',message=>worker.reply?.(message));
+    try{worker.send({root,previous:fs.existsSync(cursor)?cursor:'',next,backend,faultFile:faultFile||''});}
+    catch(e){finish(e);}
+  });
+}

package/src/owned-state.mjs

@@ -0,0 +1,32 @@
+// Resolve the destination, including linked parent directories, before any
+// state creation or removal. A watched root is readable, never state-owned.
+import fs from 'node:fs';
+import path from 'node:path';
+import {withinPath as within,realObservedPath} from './path-identity.mjs';
+
+export function resolvedDestination(file) {
+  let current=path.resolve(file),rest=[];
+  for(;;) {
+    try {
+      const canonical=realObservedPath(current);
+      return path.join(canonical,...rest);
+    } catch(e) {
+      if(e.code!=='ENOENT')throw e;
+      const parent=path.dirname(current);
+      if(parent===current)throw Error('state destination cannot be resolved');
+      rest.unshift(path.basename(current));current=parent;
+    }
+  }
+}
+
+export function assertOwnedStatePlacement(config) {
+  const state=path.resolve(config.state),resolved=resolvedDestination(state);
+  const observed=[config.root,...(config.checks||[]).flatMap(check=>
+    check.allowedExternalRoots||[])].map(resolvedDestination);
+  for(const boundary of observed)if(within(resolved,boundary)||within(boundary,resolved))
+    throw Error('REDUE state overlaps an observed checkout or external root');
+  try{if(fs.lstatSync(state).isSymbolicLink())
+    throw Error('REDUE state directory must not be a symlink');}
+  catch(e){if(e.code!=='ENOENT')throw e;}
+  return {state,resolved};
+}

package/src/path-identity.mjs

@@ -0,0 +1,43 @@
+import path from 'node:path';
+import fs from 'node:fs';
+
+// Windows callers may supply an 8.3 spelling while filesystem APIs and
+// TypeScript report the long name. Canonicalize existing paths at observation
+// boundaries; keep logical link paths separately for invalidation.
+export function realObservedPath(value) {
+  return process.platform==='win32'?fs.realpathSync.native(value):fs.realpathSync(value);
+}
+
+// Use the host path implementation in production. Passing path.win32 makes
+// the identity rules testable elsewhere; those tests are not NTFS acceptance.
+export function normalizedPath(value,paths=path) {
+  const resolved=paths.resolve(value);
+  if(paths!==path.win32)return resolved;
+  if(/^\\\\\?\\UNC\\/i.test(resolved))return '\\\\'+resolved.slice(8);
+  if(/^\\\\\?\\[A-Za-z]:\\/.test(resolved))return resolved.slice(4);
+  return resolved;
+}
+
+export function samePath(left,right,paths=path) {
+  return paths.relative(normalizedPath(left,paths),normalizedPath(right,paths))==='';
+}
+
+export function withinPath(file,root,paths=path) {
+  const relative=paths.relative(normalizedPath(root,paths),normalizedPath(file,paths));
+  return relative===''||(!paths.isAbsolute(relative)&&relative!=='..'&&
+    !relative.startsWith('..'+paths.sep));
+}
+
+export function observedRelative(root,file,paths=path) {
+  if(!withinPath(file,root,paths))return null;
+  return paths.relative(normalizedPath(root,paths),normalizedPath(file,paths))
+    .split(paths.sep).join('/');
+}
+
+export function validInputRelative(rel,platform=process.platform) {
+  if(typeof rel!=='string'||!rel||path.posix.isAbsolute(rel)||
+    rel.split('/').includes('..'))return false;
+  if(platform==='win32'&&(path.win32.isAbsolute(rel)||/^[A-Za-z]:/.test(rel)||
+    rel.includes('\\')))return false;
+  return true;
+}