@redue/cli 0.1.0-alpha.2 → 0.1.0-alpha.20

package/bin/redue.mjs

@@ -1,15 +1,21 @@
 #!/usr/bin/env node
 import fs from 'node:fs';
+import {mark,traceBase,traceContext,traceEnvironment,traceId} from '../src/decision-profile.mjs';
+traceBase({...traceContext(),request:traceId(),work:'client'});
+mark('client.loaded');
+import {directCompiler,directQualification,directEnvironment,directInterpretation} from '../src/direct-typescript.mjs';
+import {runArgv,tscRun} from '../src/typescript-invocation.mjs';
+import {testEnvironment,testRunnerAt,testsInterpretation,testsQualification} from '../src/test-direct.mjs';
+import {scriptEnvironment,scriptInterpretation,scriptKinds,scriptQualification} from '../src/node-script.mjs';
 import os from 'node:os';
 import path from 'node:path';
 import {createHash} from 'node:crypto';
 import {spawn,spawnSync} from 'node:child_process';
 import {createRequire} from 'node:module';
-import {fileURLToPath} from 'node:url';
-import {discoverNodeProject} from '../src/node-onboarding.mjs';
+import {fileURLToPath,pathToFileURL} from 'node:url';
 import {processAlive} from '../src/process-liveness.mjs';
 import {samePath,withinPath,realObservedPath} from '../src/path-identity.mjs';
-import {stateIdentity,userStateBase} from '../src/platform-state.mjs';
+import {discoverConfig,projectState,canonicalConfig} from '../src/project-location.mjs';
 import {findExecutable} from '../src/executable-lookup.mjs';
 import {readCachedStatus} from '../src/cached-state.mjs';
 import {assertOwnedStatePlacement} from '../src/owned-state.mjs';
@@ -22,8 +28,12 @@ const help=`REDUE ${version}
 Usage: redue [--config FILE] [--state-dir DIR] COMMAND [OPTIONS]
 
 Commands:
-  init [--dry-run] [--workspace NAME] [--check KIND]
+  init [--dry-run] [--workspace NAME] [--check KIND] [--recipe typescript-direct|tests-direct|node-script]
                        Discover existing scripts; optionally select one workspace/check
+  agent setup codex|claude [--dry-run|--apply] [--json]
+  agent doctor [codex|claude] [--json]
+  agent remove codex|claude [--dry-run|--apply] [--json]
+                       Connect project instructions; explicit setup only
   start                Start the local observer
   stop                 Stop this observer
   status [--json|--short] Read conservative cached status
@@ -36,13 +46,20 @@ Commands:
 No checks run in the background. Direct commands outside redue create no receipts.`;
 
 function error(message){console.error(`redue: ${message}`);process.exit(2);}
+// Exits once queued output is written. On macOS, output to a pipe is written
+// asynchronously; exiting with it queued cuts it (at 8 KB through the pipe a
+// Node program, such as an agent's shell tool, reads).
+async function exit(code){await new Promise(resolve=>process.stdout.write('',resolve));process.exit(code);}
 const args=process.argv.slice(2);
+if(args.length===3&&args[0]==='agent'&&args[1]==='hook'&&args[2]==='claude'){
+  // Runs before config discovery: the hook must exit 0 on every failure,
+  // because Claude Code treats exit 2 as a block.
+  const {runClaudeHook}=await import('../src/claude-hook.mjs');
+  await runClaudeHook(fileURLToPath(import.meta.url));process.exit(0);
+}
 if(args.length===1&&args[0]==='--version'){console.log(version);process.exit(0);}
-if(args.includes('--help')||args.includes('-h')||!args.length){console.log(help);process.exit(0);}
-const preferredConfig=path.resolve('redue.config.json');
-const legacyConfig=path.resolve('vstate.config.json');
-let configFile=fs.existsSync(preferredConfig)||!fs.existsSync(legacyConfig)?
-  preferredConfig:legacyConfig,stateOverride=null;
+if(args.includes('--help')||args.includes('-h')||!args.length){console.log(help);await exit(0);}
+let configFile=null,stateOverride=null;
 for(let i=0;i<args.length;){
   if(args[i]==='--config'||args[i]==='--state-dir'){
     const flag=args[i],value=args[i+1];if(!value)error(`${flag} requires a path`);
@@ -51,17 +68,28 @@ for(let i=0;i<args.length;){
   }else i++;
 }
 const command=args.shift();
+try{configFile??=command==='init'||stateOverride&&['stop','remove-state'].includes(command)?
+  path.resolve(fs.existsSync('redue.config.json')||!fs.existsSync('vstate.config.json')?'redue.config.json':'vstate.config.json'):discoverConfig();}
+catch(e){error(e.message);}
+if(fs.existsSync(path.dirname(configFile)))configFile=canonicalConfig(configFile);
+if(command==='agent'){
+  // Loaded on demand: onboarding and agent setup are not on the run/status path.
+  const {agentCommand}=await import('../src/agent-integration.mjs');
+  try{await agentCommand(args,{configFile,stateOverride,entry:fileURLToPath(import.meta.url)});}
+  catch(e){error(e.message);}
+  await exit(0);
+}
 if(!['init','start','stop','status','detail','explain','run','remove-state'].includes(command))
   error(`unknown command ${command||'<none>'}; use --help`);
 const json=args.includes('--json');
 const sync=args.includes('--sync');
 const dryRun=args.includes('--dry-run');
 const short=args.includes('--short');
-let workspaceSelection=null,checkSelection=null;
+let workspaceSelection=null,checkSelection=null,recipeSelection=null;
 if(command==='init')for(let i=0;i<args.length;){
-  if(args[i]==='--workspace'||args[i]==='--check'){
+  if(args[i]==='--workspace'||args[i]==='--check'||args[i]==='--recipe'){
     const flag=args[i],value=args[i+1];if(!value||value.startsWith('--'))error(`${flag} requires a name`);
-    if(flag==='--workspace')workspaceSelection=value;else checkSelection=value;
+    if(flag==='--workspace')workspaceSelection=value;else if(flag==='--recipe')recipeSelection=value;else checkSelection=value;
     args.splice(i,2);
   }else i++;
 }
@@ -73,7 +101,8 @@ if(short&&(command!=='status'||json||sync))error('--short is a cached status opt
 if(dryRun&&command!=='init')error('--dry-run is for init');
 
 if(command==='init'){
-  let discovery;try{discovery=discoverNodeProject(process.cwd());}
+  const {discoverNodeProject}=await import('../src/node-onboarding.mjs');
+  let discovery;try{discovery=discoverNodeProject(process.cwd(),{recipe:recipeSelection});}
   catch(e){error(e.message);}
   if(workspaceSelection||checkSelection){
     const chosen=discovery.checks.filter(row=>
@@ -104,7 +133,8 @@ if(command==='init'){
       console.log(`  ${row.name} (${row.script||row.command?.join(' ')}) — `+
         `${{ready:'ready to qualify',recording:'recording-only',unsupported:'unsupported'}[row.level]||row.level}: ${row.reason}`);
       if(row.script&&row.command)console.log(`    Recorded invocation: ${row.command.map(value=>
-        value==='@node'?'node':value.startsWith('@typescript-bin:')?
+        value==='@node'?'node':value==='@typescript-compiler:.'?'[reviewed local TypeScript compiler implementation]':
+          value.startsWith('@test-runner:')?`[local ${value.slice('@test-runner:'.length)}]`:value.startsWith('@typescript-bin:')?
           `[installed TypeScript in ${value.slice('@typescript-bin:'.length)}]`:value).join(' ')}`);
     }
     for(const row of summary.ambiguous)
@@ -121,10 +151,11 @@ if(command==='init'){
     if(!json){console.log(`Created ${configFile}. No checks were executed.`);
       console.log('Ready to qualify means the supported contract will be validated; it is not verification evidence.');
       console.log(`Next: review the config, then redue start and redue run ${JSON.stringify(discovery.checks[0].config.name)}.`);
+      console.log('Connect your agent: redue agent setup codex (or claude). Preview with --dry-run.');
       console.log('Use redue status first. --sync can establish applicability, but may cost more than rerunning a cheap check.');}
   } else if(unsupported&&!json)console.log(`No config written: ${summary.issue||'unsupported discovery boundary'}.`);
   if(json)console.log(JSON.stringify({...summary,proposed_config:discovery.config}));
-  process.exit(0);
+  await exit(0);
 }
 function printLifecycle(output,action,machine){
   if(machine){process.stdout.write(output);return;}
@@ -141,11 +172,12 @@ function printLifecycle(output,action,machine){
 if(stateOverride&&['stop','remove-state'].includes(command)){
   const runtime=path.join(stateOverride,'project-runtime-v1.json');
   if(!fs.existsSync(runtime)){console.log('No REDUE state exists at this path.');process.exit(0);}
+  mark('client.engine_submit');
   const result=spawnSync(process.execPath,[engine,runtime,command==='stop'?'stop':'uninstall'],
     {cwd:os.tmpdir(),stdio:['inherit','pipe','inherit'],encoding:'utf8',env:process.env});
   if(result.error)error(result.error.message);
   if(result.stdout)printLifecycle(result.stdout,command,json);
-  process.exit(result.status??2);
+  await exit(result.status??2);
 }
 let publicConfig;
 try{publicConfig=JSON.parse(fs.readFileSync(configFile,'utf8'));}
@@ -157,10 +189,7 @@ for(const key of Object.keys(publicConfig))
   if(!['schema','root','checks','packageManager'].includes(key))error(`unsupported config field ${key}`);
 if(check&&!publicConfig.checks.some(row=>row.name===check))error(`unknown check ${check}; use redue status to list configured checks`);
 const root=realObservedPath(path.resolve(path.dirname(configFile),publicConfig.root||'.'));
-const stateBase=userStateBase(process.platform,process.env,os.homedir());
-const state=stateOverride||path.join(stateBase,'vstate',
-  `vstate-${createHash('sha256').update(stateIdentity(root)+'\0'+
-    stateIdentity(configFile)).digest('hex').slice(0,16)}`);
+const state=stateOverride||projectState(root,configFile);
 if(!/^(?:vstate|redue)-/.test(path.basename(state)))
   error('--state-dir must name a dedicated redue-* directory outside the checkout (legacy vstate-* is also supported)');
 const runtimeFile=path.join(state,'project-runtime-v1.json');
@@ -169,9 +198,18 @@ function which(name){
   if(found)return found;
   error(`cannot resolve executable ${name} on PATH`);
 }
-function token(value){
+function token(value,cwd='.'){
   if(value==='@node')return process.execPath;
   if(value==='@project')return root;
+  if(value==='@typescript-compiler:.'){
+    try{return directCompiler(root,{verify:false}).entry;}catch(e){error(`direct compiler unavailable: ${e.code||e.message}`);}
+  }
+  if(value.startsWith('@test-runner:')){
+    // Qualification reports a missing runner; status and stop still work.
+    try{return testRunnerAt(root,cwd,value.slice('@test-runner:'.length)).entry;}
+    catch{return path.join(root,cwd,'node_modules',value.slice('@test-runner:'.length),'<unavailable>');}
+  }
+  if(value==='@vstate/direct-typescript-probe')return path.join(productRoot,'src','direct-typescript-probe.mjs');
   if(value.startsWith('@typescript-bin:')){
     const dir=value.slice('@typescript-bin:'.length);
     if(!dir||path.isAbsolute(dir)||dir.split('/').includes('..'))
@@ -192,10 +230,10 @@ function token(value){
   if(value.startsWith('@which:'))return which(value.slice(7));
   return value;
 }
-function argv(values,label){
+function argv(values,label,cwd){
   if(!Array.isArray(values)||!values.length||values.some(v=>typeof v!=='string'||!v))
     error(`${label} must be nonempty exact argv`);
-  return values.map(token);
+  return values.map(value=>token(value,cwd));
 }
 const categories=['source','generated','installedDependencies','environment','toolchain','runtime',
   'probeContinuity'];
@@ -208,8 +246,11 @@ const checks=publicConfig.checks.map(check=>{
   for(const category of categories)if(check.coverage?.[category]&&
     typeof check.coverageReview?.[category]!=='string')
     error(`${check.name}: reviewed coverage ${category} needs a rationale`);
+  const npmDirect=check.qualification===directQualification;
   const pnpmTypecheck=check.qualification==='pnpm-tsc-v1';
-  if(check.script&&check.command&&!pnpmTypecheck)
+  const testsDirect=check.qualification===testsQualification;
+  const generalScript=check.qualification===scriptQualification;
+  if(check.script&&check.command&&!pnpmTypecheck&&!npmDirect&&!testsDirect)
     error(`${check.name}: choose script or command, not both`);
   const manager=publicConfig.packageManager;
   if(check.script&&!['npm','yarn','pnpm'].includes(manager))
@@ -218,8 +259,20 @@ const checks=publicConfig.checks.map(check=>{
     [`@which:${manager}`,'run',check.script]:null;
   const npmAutomatic=check.qualification==='typescript-noemit-v1';
   const yarnWorkspace=check.qualification==='yarn-workspace-tsc-v1';
-  if(check.qualification&&!npmAutomatic&&!yarnWorkspace&&!pnpmTypecheck)
+  if(check.qualification&&!npmAutomatic&&!npmDirect&&!yarnWorkspace&&!pnpmTypecheck&&!testsDirect&&!generalScript)
     error(`${check.name}: unknown qualification contract`);
+  // The general recipe runs the root package script through the package manager.
+  if(generalScript&&(!['npm','pnpm','yarn'].includes(manager)||!check.script||check.command||check.cwd&&check.cwd!=='.'||
+    check.workspace||!scriptKinds.includes(check.kind)))
+    error(`${check.name}: the general recipe needs a root typecheck, test or lint script, without command or cwd`);
+  if(npmDirect&&(manager!=='npm'||check.cwd&&check.cwd!=='.'||!Array.isArray(check.command)||
+    check.command[0]!=='@node'||check.command[1]!=='@typescript-compiler:.'||
+    !tscRun({},{script:null,args:check.command.slice(2)}).run?.noEmit))
+    error(`${check.name}: direct recipe requires its explicit local compiler command`);
+  // The script's own arguments follow the runner; qualification compares them with the script.
+  if(testsDirect&&(!['npm','pnpm','yarn'].includes(manager)||!check.script||check.cwd&&check.cwd!=='.'&&!check.workspace||!Array.isArray(check.command)||
+    check.command[0]!=='@node'||!/^@test-runner:(?:vitest|jest)$/.test(check.command[1]||'')))
+    error(`${check.name}: test recipe requires its explicit local test runner command`);
   if(npmAutomatic&&(manager!=='npm'||check.cwd&&check.cwd!=='.'))
     error(`${check.name}: automatic TypeScript qualification currently needs root npm script`);
   if(yarnWorkspace&&(manager!=='yarn'||!check.workspace||check.cwd&&check.cwd!=='.'||
@@ -227,25 +280,32 @@ const checks=publicConfig.checks.map(check=>{
     check.command[1]!=='workspace'||check.command[2]!==check.workspace||
     check.command[3]!=='run'))
     error(`${check.name}: Yarn workspace qualification needs its discovered workspace command`);
-  if(pnpmTypecheck&&(manager!=='pnpm'||!check.script||!check.command||
+  if(pnpmTypecheck&&(manager!=='pnpm'||!Array.isArray(check.command)||
     check.command[0]!=='@node'||
     check.command[1]!==`@typescript-bin:${check.cwd||'.'}`||
     check.workspace&&check.cwd==='.'||
-    !check.command.slice(2).every(value=>typeof value==='string'&&value)))
+    !tscRun({},{script:null,args:check.command.slice(2)}).run))
     error(`${check.name}: pnpm qualification needs its discovered standalone TypeScript command`);
   const reason=check.kind==='test'?'test runtime, transforms and cache inputs need review':
     check.kind==='lint'?'lint plugins, config and resolver inputs need review':
     check.kind==='build'?'build environment and generated inputs need review':
     'check inputs need review';
-  const autoProbes=npmAutomatic?[['@node','@vstate/typescript-contract-probe',
+  // A chained script has one check per tsc run: each check's run counts them,
+  // so a run added to or removed from the script invalidates them all.
+  const runCount=(npmDirect||pnpmTypecheck)&&check.script?publicConfig.checks.filter(other=>
+    other.qualification===check.qualification&&other.script===check.script&&
+    (other.cwd||'.')===(check.cwd||'.')&&(other.workspace||null)===(check.workspace||null)).length:1;
+  if(runCount>16)error(`${check.name}: more than 16 checks for script ${check.script}`);
+  const run=npmDirect||pnpmTypecheck?runArgv({script:check.script??null,args:check.command.slice(2),count:runCount}):null;
+  const autoProbes=npmDirect?[['@node','@vstate/direct-typescript-probe','@project',...run]]:npmAutomatic?[['@node','@vstate/typescript-contract-probe',
     '@project',check.script,'@which:npm']]:yarnWorkspace?
     [['@node','@vstate/yarn-workspace-typecheck-probe','@project',
       check.workspace,check.command[4],'@which:yarn']]:pnpmTypecheck?
     [['@node','@vstate/pnpm-typecheck-probe','@project',
-      check.workspace||'.',check.script]]:[];
+      check.workspace||'.',...run]]:[];
   const windowsContext=process.platform==='win32'?
     ['ComSpec','COMSPEC','PATHEXT','USERPROFILE']:[];
-  const autoEnvironment=npmAutomatic?{variables:['NODE_OPTIONS','NODE_PATH','CI','HOME',
+  const autoEnvironment=npmDirect?directEnvironment:testsDirect?testEnvironment:generalScript?scriptEnvironment(manager):npmAutomatic?{variables:['NODE_OPTIONS','NODE_PATH','CI','HOME',
     'NODE_ENV','BASH_ENV','ENV',...windowsContext],prefixes:['npm_config_','DYLD_','TSGO_'],
     pathExecutables:['node','npm'],executableIdentity:true}:yarnWorkspace?
     {variables:['NODE_OPTIONS','NODE_PATH','CI','HOME','NODE_ENV','BASH_ENV','ENV',...windowsContext],
@@ -254,10 +314,11 @@ const checks=publicConfig.checks.map(check=>{
     {variables:['NODE_OPTIONS','NODE_PATH','CI','HOME','NODE_ENV','BASH_ENV','ENV',...windowsContext],
       prefixes:['PNPM_','COREPACK_','npm_config_','DYLD_','TSGO_'],
       pathExecutables:['node'],executableIdentity:true}:{};
-  return {name:check.name,command:argv(scriptCommand||check.command,`${check.name}.command`),
+  return {name:check.name,command:argv(scriptCommand||check.command,`${check.name}.command`,
+    typeof check.cwd==='string'&&check.cwd&&!path.isAbsolute(check.cwd)&&!check.cwd.split('/').includes('..')?check.cwd:'.'),
     cwd:check.cwd,inputs:check.inputs||[],generatedInputs:check.generatedInputs||[],
     installedInputs:check.installedInputs||(
-      npmAutomatic?['node_modules/**']:[]),
+      npmAutomatic||npmDirect||testsDirect?['node_modules/**']:[]),
     allowedExternalRoots:check.allowedExternalRoots||[],
     probes:[...(check.probes||[]),...autoProbes]
       .map((p,i)=>argv(p,`${check.name}.probes[${i}]`)),
@@ -266,6 +327,11 @@ const checks=publicConfig.checks.map(check=>{
     coverageReasons:check.coverageReasons||Object.fromEntries(
       categories.map(category=>[category,reason])),
     qualification:check.qualification||null,script:check.script||null,
+    ...(runCount>1?{runCount}:{}),
+    ...(npmAutomatic?{qualificationInterpretation:'npm-launcher-withheld@1'}:{}),
+    ...(npmDirect?{qualificationInterpretation:directInterpretation}:{}),
+    ...(testsDirect?{qualificationInterpretation:testsInterpretation}:{}),
+    ...(generalScript?{qualificationInterpretation:scriptInterpretation}:{}),
     workspace:check.workspace||null,kind:check.kind||null};
 });
 const runtime={schema:1,provider:'declared-project@1',root,state,checks};
@@ -277,7 +343,13 @@ if(maintenance&&!fs.existsSync(runtimeFile)){
   process.exit(0);
 }
 if(!maintenance)fs.mkdirSync(state,{recursive:true,mode:0o700});
-if(!maintenance&&fs.existsSync(runtimeFile)){
+// Two commands can meet on fresh state (SessionStart's start and the first
+// status): whichever creates the runtime file first wins, and the other
+// treats it as existing.
+let created=false;
+if(!maintenance&&!fs.existsSync(runtimeFile))
+  try{fs.writeFileSync(runtimeFile,serialized,{flag:'wx',mode:0o600});created=true;}catch(e){if(e.code!=='EEXIST')throw e;}
+if(!maintenance&&!created){
   const previous=fs.readFileSync(runtimeFile,'utf8');
   if(previous!==serialized){
     const pidFile=path.join(state,'observer.lock','pid');
@@ -287,18 +359,24 @@ if(!maintenance&&fs.existsSync(runtimeFile)){
     }
     fs.writeFileSync(runtimeFile,serialized,{mode:0o600});
   }
-}else if(!maintenance)fs.writeFileSync(runtimeFile,serialized,{flag:'wx',mode:0o600});
+}
 
 if(command==='status'&&!sync){
   const value=readCachedStatus(state,publicConfig.checks);
   console.log(json?JSON.stringify(value):renderStatus(value,{short}));
-  process.exit(0);
+  await exit(0);
 }
 
 const details=command==='detail'||command==='explain';
 const internal=command==='remove-state'?'uninstall':
   details?'sync':command==='status'&&sync?'sync':command;
-if(command==='run'){
+// On macOS and Linux the engine runs in this process, which saves a Node startup
+// on every run; its own handlers receive SIGINT and SIGTERM. Windows keeps a
+// child engine because cancellation reaches it over IPC.
+if(command==='run'&&process.platform!=='win32'){
+  process.argv=[process.argv[0],engine,runtimeFile,internal,check,...(!json?['--human']:[])];
+  await import(pathToFileURL(engine).href);
+}else if(command==='run'){
   const child=spawn(process.execPath,[engine,runtimeFile,internal,check,...(!json?['--human']:[])],
     {stdio:['inherit','inherit','inherit','ipc'],env:process.env});
   const forward=signal=>{if(child.exitCode!==null)return;
@@ -313,17 +391,20 @@ if(command==='run'){
   process.off('SIGINT',interrupt);process.off('SIGTERM',terminate);
   if(outcome.error)error(outcome.error.message);
   process.exit(outcome.status??(outcome.signal?128+os.constants.signals[outcome.signal]:1));
+}else{
+  mark('client.engine_submit');
+  const result=spawnSync(process.execPath,[engine,runtimeFile,internal,...(check?[check]:[])],
+    {stdio:['inherit','pipe','inherit'],
+      encoding:'utf8',env:traceEnvironment()});
+  mark('client.engine_complete',{exit:result.status,signal:result.signal});
+  if(result.error)error(result.error.message);
+  if(result.stdout){
+    if(['status','detail','explain'].includes(command)){
+      let value;try{value=JSON.parse(result.stdout);}catch{error('status response could not be read; applicability is unknown');}
+      if(details&&check)value={...value,checks:value.checks.filter(row=>row.name===check)};
+      if(json)console.log(JSON.stringify(value));
+      else console.log(details?renderExplain(value,check):renderStatus(value,{short}));
+    }else printLifecycle(result.stdout,command,json);
+  }
+  await exit(result.status??1);
 }
-const result=spawnSync(process.execPath,[engine,runtimeFile,internal,...(check?[check]:[])],
-  {stdio:['inherit','pipe','inherit'],
-    encoding:'utf8',env:process.env});
-if(result.error)error(result.error.message);
-if(result.stdout){
-  if(['status','detail','explain'].includes(command)){
-    let value;try{value=JSON.parse(result.stdout);}catch{error('status response could not be read; applicability is unknown');}
-    if(details&&check)value={...value,checks:value.checks.filter(row=>row.name===check)};
-    if(json)console.log(JSON.stringify(value));
-    else console.log(details?renderExplain(value,check):renderStatus(value,{short}));
-  }else printLifecycle(result.stdout,command,json);
-}
-process.exit(result.status??1);

package/docs/README.md

@@ -3,9 +3,10 @@
 For users:
 
 - [Install, initialize, run, and remove](user/getting-started.md)
+- [Fixed-build opt-in development pilot](user/pilot.md)
 - [Supported projects and conservative boundaries](user/supported-projects.md)
 - [Configuration](user/configuration.md)
-- [Coding-agent decision policy](user/agents.md)
+- [Connect coding agents and apply the decision policy](user/agents.md)
 - [JSON contract](user/json.md)
 - [Shell usage](user/shell.md)