@redue/cli 0.1.0-alpha.22 → 0.1.0-alpha.24

package/src/setup.mjs

@@ -0,0 +1,178 @@
+// `redue setup claude` and `redue remove`: one command from a project with
+// installed dependencies to a working Claude Code integration, and one to
+// undo it. Setup runs init when the project has no config, agent setup
+// claude, start, and one recorded run of each check init can qualify that is
+// not CURRENT. It prints every file it writes. What it created is kept in a
+// record in the clone's Git directory (never committed); a later setup adds
+// to that account and never forgets it. Remove undoes exactly what the record
+// says setup created: the agent files or just this machine's hooks, the
+// observer state, the local ignore line, and the config if it is unchanged
+// since setup wrote it.
+import fs from 'node:fs';
+import path from 'node:path';
+import {createHash} from 'node:crypto';
+import {spawnSync} from 'node:child_process';
+import {createInterface} from 'node:readline/promises';
+import {projectState} from './project-location.mjs';
+import {claudeHooksInstalled,removeClaudeHooks,removeIntegration} from './agent-integration.mjs';
+
+const configName='redue.config.json',localSettings='.claude/settings.local.json',agentRecord='.redue/agents/claude.json';
+const hash=text=>createHash('sha256').update(text).digest('hex');
+const readText=file=>{try{return fs.readFileSync(file,'utf8');}catch{return null;}};
+const git=(root,...args)=>spawnSync('git',args,{cwd:root,encoding:'utf8',stdio:['ignore','pipe','ignore']});
+const ignoreLine=`/${localSettings}`;
+
+async function confirm(question,yes,{defaultYes}){
+  if(yes)return true;
+  if(!process.stdin.isTTY||!process.stdout.isTTY)throw Error('not a terminal; run again with --yes to proceed without prompts');
+  const prompt=createInterface({input:process.stdin,output:process.stdout});
+  try{const answer=(await prompt.question(`${question} ${defaultYes?'[Y/n]':'[y/N]'} `)).trim();
+    return defaultYes?!/^n/i.test(answer):/^y/i.test(answer);}finally{prompt.close();}
+}
+
+export async function setupCommand(args,{entry,cwd=process.cwd()}){
+  const action=args.shift();
+  const yes=args.includes('--yes'),rest=args.filter(arg=>arg!=='--yes');
+  if(action==='setup'&&(rest.length!==1||rest[0]!=='claude'))throw Error('use redue setup claude [--yes]');
+  if(action==='remove'&&rest.length)throw Error('use redue remove [--yes]');
+  const top=git(cwd,'rev-parse','--show-toplevel');
+  if(top.status!==0)throw Error('run this inside a Git checkout');
+  const root=fs.realpathSync(top.stdout.trim());
+  if(!fs.existsSync(path.join(root,'package.json')))throw Error(`no package.json at the repository root (${root})`);
+  // The entry as invoked, so a hook written by a child names the install's
+  // stable bin link rather than the versioned file behind it.
+  const invoked=typeof process.argv[1]==='string'&&path.isAbsolute(process.argv[1])&&
+    (()=>{try{return fs.realpathSync(process.argv[1])===fs.realpathSync(entry);}catch{return false;}})()?process.argv[1]:entry;
+  // Every step is the ordinary command, so its own output says what it did.
+  const redue=(argv,options={})=>spawnSync(process.execPath,[invoked,...argv],{cwd:root,encoding:'utf8',
+    stdio:options.capture?['ignore','pipe','pipe']:'inherit',timeout:options.timeout});
+  // One record per checkout, beside the others in the shared Git directory:
+  // linked worktrees share .git/info/exclude.
+  const common=path.resolve(root,git(root,'rev-parse','--git-common-dir').stdout.trim());
+  const recordFile=path.join(common,`redue-setup-${hash(root).slice(0,16)}.json`);
+  // Other checkouts' records, for checkouts that still exist.
+  const others=()=>{try{return fs.readdirSync(common).filter(name=>/^redue-setup-[0-9a-f]{16}\.json$/.test(name)&&path.join(common,name)!==recordFile)
+    .map(name=>JSON.parse(readText(path.join(common,name))??'null')).filter(other=>other&&fs.existsSync(other.root));}catch{return [];}};
+  const context={root,redue,yes,record:JSON.parse(readText(recordFile)??'null'),recordFile,
+    exclude:path.join(common,'info','exclude'),others,save:next=>fs.writeFileSync(recordFile,JSON.stringify(next,null,2)+'\n')};
+  return action==='setup'?setup(context):remove(context);
+}
+
+async function setup({root,redue,yes,record:previous,recordFile,exclude,save}){
+  if(!fs.existsSync(path.join(root,'node_modules')))
+    throw Error('dependencies are not installed: run your package manager\'s install (npm install, pnpm install, yarn) first');
+  if(fs.existsSync(path.join(root,'vstate.config.json'))&&!fs.existsSync(path.join(root,configName)))
+    throw Error('a legacy vstate.config.json exists; rename it to redue.config.json or remove it first');
+  if(git(root,'ls-files','--error-unmatch',localSettings).status===0)
+    throw Error(`${localSettings} is committed; the hooks REDUE adds there name this machine's paths. Untrack it (git rm --cached) first`);
+  const configPath=path.join(root,configName),configExisted=fs.existsSync(configPath);
+  // init's account of the checks: which can qualify, also with a config.
+  const preview=redue(['init','--dry-run','--json'],{capture:true});
+  if(preview.status!==0)throw Error(preview.stderr.trim().replace(/^redue: /,'')||'init failed');
+  const found=JSON.parse(preview.stdout);
+  if(!configExisted&&!found.writable)throw Error(`nothing to set up: ${found.issue||(found.checks.length?found.checks.map(check=>`${check.name}: ${check.reason}`).join('; '):'no typecheck, lint or test script REDUE can use')}`);
+  const levels=new Map(found.checks.map(check=>[check.name,check.level]));
+  const names=configExisted?JSON.parse(readText(configPath)).checks.map(check=>check.name):found.checks.map(check=>check.name);
+  const ready=names.filter(name=>levels.get(name)==='ready');
+  console.log(`Setting up REDUE for Claude Code in ${root}`);
+  console.log(configExisted?`  keep ${configName} (exists)`:`  create ${configName}: ${names.map(name=>`${name} (${levels.get(name)==='ready'?'can qualify':'recording-only'})`).join(', ')}`);
+  console.log(`  write the Claude Code integration: CLAUDE.md section, .claude/skills/redue-verification/SKILL.md, ${localSettings} hooks, ${agentRecord}`);
+  console.log(`  start the observer and record ${ready.length?ready.join(', '):'no check'} once, unless already CURRENT`);
+  if(!await confirm('Proceed?',yes,{defaultYes:true})){console.log('Nothing written.');return {applied:false};}
+  // What this run creates is added to what earlier runs created.
+  const state=projectState(root,configPath);
+  const own={schema:1,host:'claude',root,config:configName,state,
+    configCreated:Boolean(previous?.configCreated),configHash:previous?.configHash??null,
+    agentCreated:Boolean(previous?.agentCreated)||!fs.existsSync(path.join(root,agentRecord)),
+    hooksAdded:Boolean(previous?.hooksAdded)||!claudeHooksInstalled(root),
+    stateCreated:Boolean(previous?.stateCreated)||!fs.existsSync(state),
+    excludeAdded:Boolean(previous?.excludeAdded)};
+  if(!configExisted){
+    const init=redue(['init']);
+    if(init.status!==0||!fs.existsSync(configPath))throw Error(`init did not write ${configName}; nothing else was written`);
+    Object.assign(own,{configCreated:true,configHash:hash(readText(configPath))});
+  }
+  save(own);
+  console.log(`${previous?'update':'create'} ${recordFile}: what setup created, for redue remove`);
+  const agent=redue(['agent','setup','claude','--apply']);
+  if(agent.status!==0)throw Error('agent setup failed; see above. redue remove undoes what setup wrote');
+  // The hooks' settings hold machine paths: keep them out of commits in this
+  // clone when Git does not ignore them.
+  if(git(root,'check-ignore','-q',localSettings).status===1){
+    fs.mkdirSync(path.dirname(exclude),{recursive:true});
+    const text=readText(exclude)??'';
+    fs.writeFileSync(exclude,`${text}${text&&!text.endsWith('\n')?'\n':''}${ignoreLine}\n`);
+    console.log(`update ${exclude}: ignore ${ignoreLine} in this clone`);
+    own.excludeAdded=true;save(own);
+  }
+  // An observer that is already running is what start would give.
+  const started=redue(['start'],{capture:true});
+  process.stdout.write(started.stdout);
+  if(started.status!==0){
+    if(!/already running/.test(started.stderr))throw Error(`the observer did not start: ${started.stderr.trim().replace(/^redue: /,'')}`);
+    console.log('Observer already running.');
+  }
+  // The observer indexes the project first; a run before that cannot be
+  // recorded as reusable. Wait while it plans and indexes; once its plan is
+  // ready, an observer that is still unhealthy says why in the status below.
+  // Nothing to wait for when no check can qualify.
+  const observation=()=>{const out=redue(['status','--json'],{capture:true});try{return JSON.parse(out.stdout).observation??null;}catch{return null;}};
+  // An answer without a phase (a stopped observer) for 10 s in a row ends the
+  // wait too.
+  const begun=Date.now();let told=-1,unread=0,phaseless=0;
+  for(let state=observation();ready.length&&!(state?.phase==='ready'||state?.phase==='unavailable')&&phaseless<10;state=observation()){
+    const seconds=Math.round((Date.now()-begun)/1000);
+    unread=state===null?unread+1:0;phaseless=state&&!state.phase?phaseless+1:0;
+    if(unread>=30)throw Error('the observer\'s status cannot be read; run redue status to see why');
+    if(seconds>15*60)throw Error(`the observer is not ready after 15 minutes (${state?.reason||state?.phase||'unknown'}); run redue status, then redue setup claude again`);
+    if(Math.floor(seconds/15)>told){told=Math.floor(seconds/15);console.log(seconds?`Still indexing (${seconds} s)...`:'Waiting for the observer to index the project...');}
+    await new Promise(resolve=>setTimeout(resolve,1000));
+  }
+  // One recorded run of each check that can qualify and is not CURRENT.
+  const statusOf=()=>{const out=redue(['status','--sync','--json'],{capture:true,timeout:600_000});try{return JSON.parse(out.stdout).checks;}catch{return [];}};
+  const rows=statusOf(),due=ready.filter(name=>rows.find(row=>row.name===name)?.freshness!=='CURRENT');
+  for(const name of due){console.log(`Recording ${name} once:`);redue(['run',name]);}
+  if(ready.length&&!due.length)console.log(`Already CURRENT: ${ready.join(', ')}.`);
+  for(const row of statusOf())console.log(`  ${row.name}: ${row.freshness}${row.result?' / '+row.result:''}${row.freshness==='CURRENT'?'':' — '+row.reason}`);
+  console.log('Done. Start a new Claude Code session in this project. Undo with redue remove.');
+  return {applied:true};
+}
+
+async function remove({root,redue,yes,record:own,recordFile,exclude,others}){
+  if(!own){console.log('No setup record for this checkout: nothing redue setup created to remove.');
+    console.log('To undo a setup made step by step: redue agent remove claude --apply, then redue remove-state.');return {removed:false};}
+  const configPath=path.join(root,configName),configText=readText(configPath);
+  const removeAgent=own.agentCreated&&fs.existsSync(path.join(root,agentRecord));
+  const removeHooks=!removeAgent&&own.hooksAdded&&claudeHooksInstalled(root);
+  const removeState=own.stateCreated&&fs.existsSync(own.state);
+  const deleteConfig=own.configCreated&&configText!==null&&hash(configText)===own.configHash;
+  // The ignore line goes only when no other checkout of this repository is
+  // set up: those rely on it too, whichever added it.
+  const removeIgnore=own.excludeAdded&&!others().length;
+  console.log(`Removing what redue setup created in ${root}`);
+  if(removeAgent)console.log('  remove the Claude Code integration');
+  if(removeHooks)console.log(`  remove REDUE's hooks from ${localSettings} (the integration predates setup)`);
+  if(removeState)console.log('  stop the observer and remove its local state (receipts included)');
+  else if(!own.stateCreated)console.log('  keep the observer state (it predates setup)');
+  if(own.configCreated&&configText!==null)console.log(deleteConfig?`  delete ${configName}`:`  keep ${configName} (edited since setup)`);
+  if(removeIgnore)console.log(`  remove ${ignoreLine} from ${exclude}`);
+  console.log(`  delete ${recordFile}`);
+  if(!await confirm('Proceed?',yes,{defaultYes:false})){console.log('Nothing removed.');return {removed:false};}
+  if(removeAgent)for(const line of removeIntegration(root))console.log(line);
+  if(removeHooks){const changed=removeClaudeHooks(root);if(changed)console.log(`update ${changed}`);}
+  if(removeState&&redue(['--state-dir',own.state,'remove-state']).status!==0)
+    throw Error('the observer state was not removed; see above. The config and setup record are kept so you can retry');
+  if(deleteConfig){fs.unlinkSync(configPath);console.log(`remove ${configName}`);}
+  if(removeIgnore){
+    const text=readText(exclude);
+    if(text!==null&&text.split('\n').includes(ignoreLine)){
+      fs.writeFileSync(exclude,text.split('\n').filter(line=>line!==ignoreLine).join('\n'));
+      console.log(`update ${exclude}`);}
+  }
+  fs.unlinkSync(recordFile);console.log(`remove ${recordFile}`);
+  // Folders the integration lived in, when nothing else is left in them.
+  for(const dir of ['.redue/agents','.redue','.claude/skills/redue-verification','.claude/skills','.claude'])
+    try{fs.rmdirSync(path.join(root,dir));console.log(`remove ${dir}/`);}catch{}
+  console.log('Done.');
+  return {removed:true};
+}

package/src/test-direct.mjs

@@ -430,13 +430,18 @@ function storePath(files,file,st){
 // files, which is a change REDUE sees. `cache` (in owned state) keeps each
 // file found in the store with its identity and store path, so an unchanged
 // file is not hashed again; its store link is still checked.
-export function sharedInstalledFile(root,project={},cache=null){
+// Without a pnpm store, a hard-linked installed file is accepted only when
+// every one of its links is an installed file the check observes (`observed`,
+// installed-observation.mjs): esbuild links its binary into its platform
+// package. Each accepted file's link count becomes a run fact in `facts`, so
+// a link added later is noticed before the next answer.
+export function sharedInstalledFile(root,project={},cache=null,{observed=()=>false,facts=[]}={}){
   const stack=modulesDirs(project).map(dir=>path.join(root,dir));
   const files=pnpmStoreFiles(root),now=Date.now();
   let known={},changed=false;
   if(files&&cache)try{const value=JSON.parse(fs.readFileSync(cache,'utf8'));
     if(value?.files===files&&value.entries&&typeof value.entries==='object')known=value.entries;}catch{}
-  const found={};
+  const found={},links=new Map();
   const shared=(file,reason)=>({file:path.relative(root,file).split(path.sep).join('/'),reason});
   while(stack.length){
     const dir=stack.pop();let entries;
@@ -447,7 +452,14 @@ export function sharedInstalledFile(root,project={},cache=null){
       if(!entry.isFile())continue;
       let st;try{st=fs.lstatSync(file,{bigint:true});}catch{continue;}
       if(st.nlink<=1n)continue;
-      if(!files)return shared(file,'has another hard link, and the install records no pnpm store');
+      if(!files){
+        // Distinct observed links by real path: a directory walked twice
+        // through a link counts once.
+        const key=`${st.dev}:${st.ino}`,group=links.get(key)??{file,nlink:st.nlink,seen:new Set()};
+        if(group.nlink!==st.nlink)return shared(file,'had its hard links change while REDUE checked them');
+        if(observed(file))try{group.seen.add(fs.realpathSync(file));}catch{}
+        links.set(key,group);continue;
+      }
       const key=`${st.dev}:${st.ino}`,cached=known[key];
       let at=Array.isArray(cached)&&cached[0]===identity(st)&&typeof cached[1]==='string'&&
         sameFile(path.join(files,cached[1]),st)?cached[1]:null;
@@ -463,6 +475,10 @@ export function sharedInstalledFile(root,project={},cache=null){
       else changed=true;
     }
   }
+  for(const group of links.values()){
+    if(BigInt(group.seen.size)<group.nlink)return shared(group.file,'has another hard link that is not an installed file this check observes, and the install records no pnpm store');
+    facts.push(['linkCount',group.file,Number(group.nlink)]);
+  }
   if(files&&cache&&(changed||Object.keys(found).length!==Object.keys(known).length))
     try{atomicJson(cache,{files,entries:found});}catch{}
   return null;

package/src/typescript-list.mjs

@@ -15,6 +15,8 @@ export function queryAnswer(kind,file,options) {
     if(kind==='readFile')return hash(fs.readFileSync(file,'utf8'));
     if(kind==='fileExists')return fs.statSync(file).isFile();
     if(kind==='directoryExists')return fs.statSync(file).isDirectory();
+    // How many hard links a file has: a link added elsewhere changes it.
+    if(kind==='linkCount')return fs.lstatSync(file).nlink;
     // The compiler resolves through realpathSync.native outside Windows.
     if(kind==='realpath')return process.platform==='win32'?fs.realpathSync(file):fs.realpathSync.native(file);
     if(kind==='directories')return fs.readdirSync(file,{withFileTypes:true})
@@ -44,7 +46,7 @@ export function queryAnswer(kind,file,options) {
 export function runFactChange(facts) {
   if(!Array.isArray(facts))return 'an unreadable run fact';
   for(const fact of facts){
-    if(!Array.isArray(fact)||!['fileExists','directoryExists','realpath','readFile','entries'].includes(fact[0])||
+    if(!Array.isArray(fact)||!['fileExists','directoryExists','realpath','readFile','entries','linkCount'].includes(fact[0])||
       typeof fact[1]!=='string')return 'an unreadable run fact';
     const [kind,file,answer]=fact;
     let now;try{now=queryAnswer(kind,file);}catch{return file;}
@@ -63,6 +65,14 @@ export function queriesMatch(queries) {
   return queries.every(([kind,file,answer,options])=>
     JSON.stringify(queryAnswer(kind,file,options))===JSON.stringify(answer));
 }
+// Why a recipe built on TypeScript's compiler API cannot use the TypeScript
+// installed at `tsRoot`, or null: TypeScript 7 is a native compiler and
+// ships no such API.
+export function compilerApiIssue(tsRoot) {
+  let version=null;try{version=JSON.parse(fs.readFileSync(path.join(tsRoot,'package.json'),'utf8')).version;}catch{}
+  return Number(String(version).split('.')[0])>=7?
+    `TypeScript ${version} is a native compiler without the compiler API this recipe reads; REDUE does not support TypeScript 7 yet`:null;
+}
 export function compilerFiles(tsRoot,cwd,config='tsconfig.json') {
   const require=createRequire(import.meta.url),ts=require(tsRoot);
   if(typeof ts.createProgram!=='function'||typeof ts.createCompilerHost!=='function')return null;

package/src/yarn-workspace-inputs.mjs

@@ -2,6 +2,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import {execFileSync} from 'node:child_process';
 import {createRequire} from 'node:module';
+import {compilerApiIssue} from './typescript-list.mjs';
 import micromatch from './glob.mjs';
 import {withinPath as within,realObservedPath} from './path-identity.mjs';
 
@@ -58,6 +59,8 @@ export function yarnWorkspacePackages(root){
 }
 
 function parsedTypeScript(root,dir){
+  const apiIssue=compilerApiIssue(path.join(root,'node_modules','typescript'));
+  if(apiIssue)throw Error(apiIssue);
   const require=createRequire(path.join(root,'package.json'));
   const ts=require(path.join(root,'node_modules','typescript'));
   const config=path.join(root,dir,'tsconfig.json'),reads=new Set();