@redue/cli 0.1.0-alpha.25 → 0.1.0-alpha.27

package/src/index.mjs

@@ -6,11 +6,17 @@ import micromatch from './glob.mjs';
 import {sha} from './plan.mjs';
 import {resolveLinks} from './installed-inputs.mjs';
 import {validInputRelative,identityFields,racyUntil} from './path-identity.mjs';
+import {isSandboxed} from './sandbox.mjs';
 
 const tracked = root => [...new Set(execFileSync('git',
   ['ls-files','--cached','--others','--exclude-standard','-z'],
   {cwd:root,env:{...process.env,GIT_OPTIONAL_LOCKS:'0'},maxBuffer:64*1024*1024})
   .toString().split('\0').filter(Boolean))];
+// Git-ignored paths at the top of each ignored tree: a directory ends in '/'.
+const ignored = root => [...new Set(execFileSync('git',
+  ['ls-files','--others','--ignored','--exclude-standard','--directory','-z'],
+  {cwd:root,env:{...process.env,GIT_OPTIONAL_LOCKS:'0'},maxBuffer:64*1024*1024})
+  .toString().split('\0').filter(Boolean))];
 const xor = (left,right) => { for(let i=0;i<32;i++) left[i]^=right[i]; };
 const token = (file,hash) => createHash('sha256').update(file+'\0'+hash).digest();
 const stablePrefix = glob => {
@@ -178,12 +184,13 @@ export class InputIndex {
   }
   summary(name) { const row=this.checks.get(name); return {fingerprint:this.fingerprint(name),
     revision:row.revision,planId:row.plan.id,files:row.files.size,probeAt:row.probeAt}; }
-  record(rel, changeReason=rel+' changed', observedStat=null) {
+  // `only`, when given, limits which checks may take the file.
+  record(rel, changeReason=rel+' changed', observedStat=null, only=null) {
     if(!validInputRelative(rel)) {
       this.unavailable='invalid event path'; return false;
     }
     const names=this.candidates(rel), old=this.files.get(rel), matched=[];
-    for(const name of names) if(this.matches(this.checks.get(name),rel)) matched.push(name);
+    for(const name of names) if((!only||only(name))&&this.matches(this.checks.get(name),rel)) matched.push(name);
     if(!matched.length && old===undefined) return false;
     let fresh,stat,inspection;
     try{stat=observedStat||fs.lstatSync(path.join(this.root,rel),{bigint:true});}
@@ -198,7 +205,7 @@ export class InputIndex {
         // (its package.json stands for them).
         // The second form is for recorded checks only: their recorder
         // classifies a read through the link where it leads.
-        const recorded=name=>['node-script-v1','npm-tests-direct-v1'].includes(this.checks.get(name).plan.qualification);
+        const recorded=name=>['node-script-v1','npm-tests-direct-v1'].includes(this.checks.get(name).plan.qualification)||isSandboxed(this.checks.get(name).plan.qualification);
         const observedDir=installed?physical=>!this.includeInstalled&&
           ([...this.installedRootSet].some(root=>physical.startsWith(root+'/'))||
             !physical.split('/').includes('node_modules')&&!this.installedPath(physical+'/package.json')&&matched.every(recorded))&&
@@ -267,6 +274,10 @@ export class InputIndex {
     this.unavailable=null;
     const trackedStarted=performance.now();
     const names=new Set(this.trackGit?tracked(this.root):[]);
+    // A sandboxed check's reads are not recorded, so git-ignored files are its
+    // inputs too: every ignored file its patterns take, outside the scan roots
+    // (installed trees) and the directories no pattern can take a file from.
+    const ignoredTrees=this.trackGit&&[...this.checks.values()].some(row=>row.plan.ignoredInputs)?ignored(this.root):[];
     this.profile.trackedMs+=performance.now()-trackedStarted;
     const enumerationStarted=performance.now();
     // Traverse declared input roots to include ignored/generated inputs. Avoid unrelated
@@ -310,6 +321,29 @@ export class InputIndex {
       }
       visit(base,prefix);
     }
+    // Only the checks that take ignored files get them here, as before for the others.
+    const ignoring=name=>this.checks.get(name).plan.ignoredInputs===true;
+    const takes=rel=>[...this.checks.values()].some(row=>row.plan.ignoredInputs&&this.matches(row,rel));
+    // A node_modules that is not installed input is skipped, as above. An
+    // ignored link is taken when it leads to a file in the checkout; a link
+    // to a directory or out of the checkout is not a file input.
+    const linkToFile=rel=>{try{const target=fs.realpathSync(path.join(this.root,rel));
+      return fs.statSync(target).isFile()&&target.startsWith(fs.realpathSync(this.root)+path.sep);}catch{return false;}};
+    const visitIgnored=rel=>{
+      const base=path.posix.basename(rel);
+      if(this.prefixes.has(rel)||this.installedPath(rel)&&!this.installedAncestors.has(rel)||base==='.git'||
+        base==='node_modules'&&!this.installedPath(rel))return;
+      let st;try{st=fs.lstatSync(path.join(this.root,rel),{bigint:true});}
+      catch(e){if(e.code==='ENOENT')return;throw e;}
+      this.profile.enumeratedEntries++;
+      if(st.isSymbolicLink()&&!linkToFile(rel))return;
+      if(st.isDirectory()){
+        if(!takes(rel+'/.redue-probe'))return;
+        for(const ent of fs.readdirSync(path.join(this.root,rel),{withFileTypes:true}))visitIgnored(rel+'/'+ent.name);
+      }else if(this.candidates(rel).size){
+        const started=performance.now();this.record(rel,'cold reconciliation',st,ignoring);processingMs+=performance.now()-started;scanned++;}
+    };
+    for(const entry of ignoredTrees)visitIgnored(entry.replace(/\/$/,''));
     this.profile.enumerationMs+=performance.now()-enumerationStarted-processingMs;
     const recordStarted=performance.now();
     for(const rel of names) {

package/src/landlock.py

@@ -0,0 +1,228 @@
+#!/usr/bin/env python3
+# The sandboxed recipe's Linux launcher (src/sandbox.mjs): runs a command
+# under a Landlock ruleset (Linux >= 5.13), with the standard library only.
+# Reads and executes are allowed beneath the --read paths; with --no-tcp
+# (ABI >= 4), every TCP bind and connect is refused, and (ABI >= 6) so is a
+# connection to an abstract Unix socket outside the run. Writes are not
+# handled, so they are not restricted.
+#
+# --hide PATH keeps the run from reading or executing beneath PATH, inside a
+# --read place. Landlock only grants, beneath a whole directory, so such a
+# place gets listing rights (beneath it all, hidden entries included) and
+# read and execute rights on each of its entries that is not hidden and
+# holds nothing hidden, descending into the ones that do. A hidden path can
+# still be listed and stat'ed. --stats FILE writes the rule count and the
+# time the rules took, as JSON.
+#
+# The launcher stays as the command's parent and a child subreaper: when the
+# command exits, it stops every process the command left running, daemons
+# that started their own session included (they are reparented to it), as a
+# CI job's end does. The command runs in its own process group; a signal the
+# launcher gets is passed to that group once. The launcher then ends as the
+# command did: with its exit status, or by its signal.
+#
+#   landlock.py --read /usr --read /tmp ... [--hide P ...] [--stats F] [--no-tcp] -- cmd args...
+#   landlock.py --probe     # prints {"abi": N} or {"abi": null, "errno": E}
+import ctypes
+import json
+import os
+import signal
+import sys
+import time
+
+SYS_CREATE, SYS_ADD, SYS_RESTRICT = 444, 445, 446  # the same on x86_64 and aarch64
+EXECUTE, READ_FILE, READ_DIR = 1 << 0, 1 << 2, 1 << 3
+BIND_TCP, CONNECT_TCP = 1 << 0, 1 << 1
+SCOPE_ABSTRACT_UNIX_SOCKET = 1 << 0
+PR_SET_NO_NEW_PRIVS, PR_SET_CHILD_SUBREAPER = 38, 36
+
+libc = ctypes.CDLL(None, use_errno=True)
+libc.syscall.restype = ctypes.c_long
+
+
+class RulesetAttr(ctypes.Structure):
+    _fields_ = [('fs', ctypes.c_uint64), ('net', ctypes.c_uint64), ('scoped', ctypes.c_uint64)]
+
+
+class PathBeneath(ctypes.Structure):
+    # Packed, as the kernel's struct is: 12 bytes. Python 3.14 asks for the layout.
+    _layout_ = 'ms'
+    _pack_ = 1
+    _fields_ = [('allowed', ctypes.c_uint64), ('fd', ctypes.c_int32)]
+
+
+def abi():
+    v = libc.syscall(SYS_CREATE, None, ctypes.c_size_t(0), ctypes.c_uint32(1))
+    return (v, 0) if v >= 0 else (None, ctypes.get_errno())
+
+
+def main(argv):
+    if argv == ['--probe']:
+        v, err = abi()
+        print(json.dumps({'abi': v, 'errno': err}))
+        return 0
+    reads, hidden, stats, no_tcp = [], set(), None, False
+    while argv and argv[0] != '--':
+        if argv[0] == '--read':
+            reads.append(argv[1]); argv = argv[2:]
+        elif argv[0] == '--hide':
+            hidden.add(os.path.normpath(argv[1])); argv = argv[2:]
+        elif argv[0] == '--stats':
+            stats = argv[1]; argv = argv[2:]
+        elif argv[0] == '--no-tcp':
+            no_tcp = True; argv = argv[1:]
+        else:
+            sys.exit(f'landlock.py: unknown option {argv[0]}')
+    cmd = argv[1:]
+    version, err = abi()
+    if version is None:
+        sys.exit(f'landlock.py: Landlock unavailable (errno {err})')
+    handled = EXECUTE | READ_FILE | READ_DIR
+    attr = RulesetAttr(handled, (BIND_TCP | CONNECT_TCP) if no_tcp and version >= 4 else 0,
+                       SCOPE_ABSTRACT_UNIX_SOCKET if no_tcp and version >= 6 else 0)
+    size = 24 if attr.scoped else 16 if attr.net else 8
+    ruleset = libc.syscall(SYS_CREATE, ctypes.byref(attr), ctypes.c_size_t(size), ctypes.c_uint32(0))
+    if ruleset < 0:
+        sys.exit(f'landlock.py: create_ruleset errno {ctypes.get_errno()}')
+    started, count = time.monotonic(), 0
+    def add(place, rights=None):
+        nonlocal count
+        try:
+            fd = os.open(place, os.O_PATH | os.O_CLOEXEC)
+        except OSError:
+            return
+        # A file takes file rights only.
+        if rights is None:
+            rights = handled if os.path.isdir(place) else EXECUTE | READ_FILE
+        rule = PathBeneath(rights, fd)
+        if libc.syscall(SYS_ADD, ctypes.c_int(ruleset), ctypes.c_int(1), ctypes.byref(rule), ctypes.c_uint32(0)) < 0:
+            sys.exit(f'landlock.py: add_rule {place} errno {ctypes.get_errno()}')
+        os.close(fd)
+        count += 1
+    # The directories that hold a hidden path, up to the root.
+    holders = set()
+    for path in hidden:
+        at = os.path.dirname(path)
+        while at not in holders and at != os.path.dirname(at):
+            holders.add(at); at = os.path.dirname(at)
+    def grant(directory):
+        # Links are not followed: what they lead to is granted on its own or not at all.
+        try:
+            entries = list(os.scandir(directory))
+        except OSError:
+            return
+        for entry in entries:
+            if entry.path in hidden or entry.is_symlink():
+                continue
+            if entry.path in holders:
+                grant(entry.path)
+            else:
+                add(entry.path)
+    for place in reads:
+        place = os.path.normpath(place)
+        if place in holders and os.path.isdir(place):
+            add(place, READ_DIR)
+            grant(place)
+        else:
+            add(place)
+    if stats:
+        with open(stats, 'w') as f:
+            json.dump({'rules': count, 'ms': round((time.monotonic() - started) * 1000, 1)}, f)
+    if libc.prctl(PR_SET_NO_NEW_PRIVS, 1, 0, 0, 0) != 0:
+        sys.exit(f'landlock.py: no_new_privs errno {ctypes.get_errno()}')
+    if libc.syscall(SYS_RESTRICT, ctypes.c_int(ruleset), ctypes.c_uint32(0)) < 0:
+        sys.exit(f'landlock.py: restrict_self errno {ctypes.get_errno()}')
+    os.close(ruleset)
+    libc.prctl(PR_SET_CHILD_SUBREAPER, 1, 0, 0, 0)
+    pid = os.fork()
+    if pid == 0:
+        os.setpgid(0, 0)
+        try:
+            os.execvp(cmd[0], cmd)
+        except OSError as e:
+            sys.stderr.write(f'landlock.py: exec {cmd[0]}: {e}\n')
+        os._exit(127)
+    # Also here, so a signal that comes before the child runs finds its group.
+    try:
+        os.setpgid(pid, pid)
+    except OSError:
+        pass
+    def forward(number, frame):
+        try:
+            os.killpg(pid, number)
+        except (ProcessLookupError, PermissionError):
+            pass
+    for number in (signal.SIGINT, signal.SIGTERM, signal.SIGHUP):
+        signal.signal(number, forward)
+    _, status = os.waitpid(pid, 0)
+    stop_left()
+    code = os.waitstatus_to_exitcode(status)
+    if code >= 0:
+        return code
+    # Killed by a signal: end the same way, so the caller sees the signal.
+    try:
+        signal.signal(-code, signal.SIG_DFL)
+    except (OSError, ValueError):
+        pass
+    os.kill(os.getpid(), -code)
+    return 128 - code
+
+
+def children(me):
+    # The kernel's list of this process's children, where it keeps one.
+    try:
+        found = set()
+        for task in os.listdir('/proc/self/task'):
+            with open(f'/proc/self/task/{task}/children') as f:
+                found.update(int(pid) for pid in f.read().split())
+        return list(found)
+    except OSError:
+        pass
+    # Else every process's parent. The fields after the command name, which
+    # may hold spaces or parentheses.
+    found = []
+    for entry in os.listdir('/proc'):
+        if not entry.isdigit():
+            continue
+        try:
+            with open(f'/proc/{entry}/stat') as f:
+                stat = f.read()
+        except OSError:
+            continue
+        if int(stat[stat.rindex(')') + 2:].split()[1]) == me:
+            found.append(int(entry))
+    return found
+
+
+# Every process left under the launcher: SIGTERM, then SIGKILL after a second.
+# A process's own children are reparented here when it ends, so this repeats
+# until none is left, for at most three seconds: a process in uninterruptible
+# sleep is named and left.
+def stop_left():
+    me, start, number = os.getpid(), time.monotonic(), signal.SIGTERM
+    while True:
+        while True:
+            try:
+                done, _ = os.waitpid(-1, os.WNOHANG)
+            except ChildProcessError:
+                done = 0
+            if done == 0:
+                break
+        left = children(me)
+        if not left:
+            return
+        if time.monotonic() > start + 3:
+            sys.stderr.write(f'landlock.py: processes {left} did not stop\n')
+            return
+        if time.monotonic() > start + 1:
+            number = signal.SIGKILL
+        for pid in left:
+            try:
+                os.kill(pid, number)
+            except ProcessLookupError:
+                pass
+        time.sleep(0.05)
+
+
+if __name__ == '__main__':
+    sys.exit(main(sys.argv[1:]))

package/src/node-onboarding.mjs

@@ -1,6 +1,7 @@
 import {directProject,directQualification} from './direct-typescript.mjs';
-import {testProject,testRecipeScript,testCheckInputs,testEnvironmentIssue,testsQualification} from './test-direct.mjs';
-import {commandLineIssue,scriptCheckInputs,scriptPath,scriptProject,scriptQualification} from './node-script.mjs';
+import {testProject,testRecipeScript,testCheckInputs,testsQualification} from './test-direct.mjs';
+import {generalIssue,scriptCheckInputs,scriptProject,scriptQualification} from './node-script.mjs';
+import {sandboxCheckInputs,sandboxKinds,sandboxQualification} from './sandbox.mjs';
 // Init proposes the general recipe for typecheck and lint scripts; test
 // scripts use the direct test recipe (Vitest, Jest).
 const generalKinds=['typecheck','lint'];
@@ -110,7 +111,7 @@ const proposable=(dir,scripts)=>exists(path.join(dir,'tsconfig.json'))&&!typeche
 // The inputs a TypeScript contract adds to its check's config: no exclusions,
 // which would outlive the tsconfig they came from; the plan adds the current ones.
 const contractInputs=contract=>[...contract.configs,...contract.sourcePatterns.filter(p=>!p.startsWith('!'))];
-function sourceLinkIssue(root) {
+export function sourceLinkIssue(root) {
   const stack=likelyDirs.filter(name=>exists(path.join(root,name)));
   let inspected=0;
   while(stack.length){
@@ -207,22 +208,16 @@ export function workspacePackages(root){
 // supported package manager and platform, and a script (with its pre and post
 // scripts) that, read as text, starts only Node programs.
 function generalCheck(root,kind,script){
-  if(!['darwin','linux'].includes(process.platform))throw Error('the general recipe records runs on macOS and Linux only');
-  const environmentIssue=testEnvironmentIssue();
-  if(environmentIssue)throw Error(environmentIssue);
-  let project;
-  try{project=scriptProject(root,script);}catch(e){throw Error(e.code?.replace(/^test-/,'')||e.message);}
-  for(const name of ['pre'+script,script,'post'+script]){
-    if(typeof project.scripts[name]!=='string')continue;
-    const issue=commandLineIssue(project.scripts[name],{cwd:root,searchPath:scriptPath(root,process.env.PATH)});
-    if(issue)throw Error(name===script?issue:`${name}: ${issue}`);
-  }
+  const issue=generalIssue(root,script);
+  if(issue)throw Error(issue);
+  const project=scriptProject(root,script);
   return {config:{name:kind,script,kind,qualification:scriptQualification,...scriptCheckInputs(project.dirs)},manager:project.manager};
 }
 export function discoverNodeProject(root,{recipe=null}={}) {
-  if(recipe&&!['typescript-direct','tests-direct','node-script'].includes(recipe))
-    throw Error('unknown recipe; use typescript-direct, tests-direct or node-script');
-  // Without --recipe, init tries the strict recipes first, then the general one.
+  if(recipe&&!['typescript-direct','tests-direct','node-script','sandbox'].includes(recipe))
+    throw Error('unknown recipe; use typescript-direct, tests-direct, node-script or sandbox');
+  // Without --recipe, init tries the strict recipes first, then the general
+  // one, then the sandboxed one.
   const auto=recipe===null;
   root=realObservedPath(root);
   const packageFile=path.join(root,'package.json');
@@ -281,7 +276,7 @@ export function discoverNodeProject(root,{recipe=null}={}) {
           reason:`explicit local ${project.runner} ${project.version} run of script ${JSON.stringify(chosen.script)}; the whole checkout is its input; npm and lifecycle scripts are not executed`};
       }catch(e){classification={level:'recording',reason:`Test recipe unavailable (${e.code||e.message}); original npm script retained`};}
     }
-    if(recipe!=='node-script'&&pm.name==='pnpm'&&kind==='typecheck'&&!workspaces&&!pm.issue&&(script===undefined||tscRuns(scripts[script]))){
+    if(recipe!=='node-script'&&recipe!=='sandbox'&&pm.name==='pnpm'&&kind==='typecheck'&&!workspaces&&!pm.issue&&(script===undefined||tscRuns(scripts[script]))){
       try{
         parts=tscChecks('typecheck',script??null,scripts,run=>{
           const contract=pnpmTypecheckInputs(root,'.',run);
@@ -294,14 +289,40 @@ export function discoverNodeProject(root,{recipe=null}={}) {
           qualification:'pnpm-tsc-v1'};}
       catch(e){classification={level:'recording',reason:`pnpm TypeScript contract needs review: ${e.message}`};}
     }
+    // The general recipe's row, when it takes the script.
+    let generalIssue=null,generalRow=null;
     if((auto||recipe==='node-script')&&script&&generalKinds.includes(kind)&&classification.level!=='ready'&&!observationIssue){
       try{
         const general=generalCheck(root,kind,script);
-        checks.push({config:general.config,level:'ready',qualification:scriptQualification,
-          reason:`general recipe: ${general.manager} runs script ${JSON.stringify(script)} with REDUE's recorder in every Node process; the whole checkout is its input`});
+        generalRow={config:general.config,level:'ready',qualification:scriptQualification,
+          reason:`general recipe: ${general.manager} runs script ${JSON.stringify(script)} with REDUE's recorder in every Node process; the whole checkout is its input`};
+      }catch(e){generalIssue=e.message;classification={...classification,reason:`General recipe unavailable (${e.message}); ${classification.reason}`};}
+    }
+    // After the strict recipes, a root typecheck or lint script gets the
+    // sandboxed recipe, which also covers programs the general recipe cannot
+    // record. It is ready only once init has run it both ways (bin/redue.mjs);
+    // `fallback` is the row init writes when that shows a difference or the
+    // sandbox cannot run here: the general recipe's, when it takes the script.
+    // Where the sandbox cannot start at run time, a script the general recipe
+    // takes is recorded as it would record it (cli.mjs).
+    // A script whose program is not installed gets none, and neither does one
+    // that changes files (`--fix`, `--write`): init would run it twice.
+    const writes=script&&['pre'+script,script,'post'+script].map(name=>scripts[name]).find(text=>typeof text==='string'&&
+      /(?:^|\s)--(?:fix|write|unsafe-fixes)(?=[\s=]|$)/.test(text));
+    if(writes)classification={...classification,reason:`Sandboxed recipe unavailable (the script changes files: ${writes.match(/--(?:fix|write|unsafe-fixes)/)[0]}); ${classification.reason}`};
+    if((auto||recipe==='sandbox')&&script&&sandboxKinds.includes(kind)&&classification.level!=='ready'&&!observationIssue&&
+      !/REDUE cannot find/.test(generalIssue||'')&&!writes){
+      try{
+        const project=scriptProject(root,script);
+        const fallback=generalRow??{config:{...check,...classification.qualification?{qualification:classification.qualification}:{}},...classification};
+        checks.push({config:{name:kind,script,kind,qualification:sandboxQualification,...sandboxCheckInputs(project.dirs)},level:'ready',
+          qualification:sandboxQualification,fallback,
+          reason:`sandboxed recipe: ${project.manager} runs script ${JSON.stringify(script)} inside the OS sandbox${generalIssue?` (the general recipe cannot record it: ${generalIssue})`:
+            generalRow?'; where the sandbox cannot run, the general recipe records it':''}; the whole checkout is its input`});
         continue;
-      }catch(e){classification={...classification,reason:`General recipe unavailable (${e.message}); ${classification.reason}`};}
+      }catch(e){classification={...classification,reason:`Sandboxed recipe unavailable (${e.code?.replace(/^test-/,'')||e.message}); ${classification.reason}`};}
     }
+    if(generalRow){checks.push(generalRow);continue;}
     if(!script&&classification.level!=='ready')continue;
     if(parts&&classification.level==='ready'){
       for(const part of parts)checks.push({config:{...check,...part,qualification:classification.qualification},...classification});

package/src/node-script.mjs

@@ -12,7 +12,7 @@ import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import {pnpmShimTarget} from './pnpm-shims.mjs';
-import {testPackageManager,testWorkspaceDirs,testEnvironment} from './test-direct.mjs';
+import {testPackageManager,testWorkspaceDirs,testEnvironment,testEnvironmentIssue} from './test-direct.mjs';
 
 export const scriptQualification='node-script-v1';
 export const scriptInterpretation='node-script@1';
@@ -358,6 +358,21 @@ export function childProgram({file,args,cwd,searchPath,env=null,script=null},{to
     return {needsHeader:false};
   return {issue:`ran ${name}, a program REDUE does not record`};
 }
+// Why the general recipe could not record a root script now, or null: what
+// init checks before it proposes it. A sandboxed check whose sandbox cannot
+// start is recorded this way instead (cli.mjs).
+export function generalIssue(root,script){
+  if(!['darwin','linux'].includes(process.platform))return 'the general recipe records runs on macOS and Linux only';
+  const environment=testEnvironmentIssue();
+  if(environment)return environment;
+  let project;try{project=scriptProject(root,script);}catch(e){return e.code?.replace(/^test-/,'')||e.message;}
+  for(const name of ['pre'+script,script,'post'+script]){
+    if(typeof project.scripts[name]!=='string')continue;
+    const issue=commandLineIssue(project.scripts[name],{cwd:root,searchPath:scriptPath(root,process.env.PATH)});
+    if(issue)return name===script?issue:`${name}: ${issue}`;
+  }
+  return null;
+}
 // What a recorded run needs from the check: the workspace package directories
 // whose node_modules its installed inputs list. The script must still exist.
 export function scriptRunFacts(root,check){

package/src/presentation.mjs

@@ -2,7 +2,8 @@
 // The recipe that made a receipt, by the qualification it names.
 const recipes={'npm-typescript-direct-v1':'direct TypeScript recipe','npm-tests-direct-v1':'direct test recipe',
   'node-script-v1':'general recipe','pnpm-tsc-v1':'pnpm TypeScript recipe','yarn-workspace-tsc-v1':'Yarn workspace TypeScript recipe',
-  'typescript-noemit-v1':'npm TypeScript recipe'};
+  'typescript-noemit-v1':'npm TypeScript recipe','sandbox-v1':'sandboxed recipe',
+  'sandbox-v2':'sandboxed recipe, git-ignored files hidden'};
 export const recipeLabel=recipe=>recipes[recipe]??null;
 export function checkLabel(row) {
   return row.result==='FAIL'?'FAILED':row.freshness;

package/src/python-onboarding.mjs

@@ -0,0 +1,87 @@
+// Python projects for `redue init`: typecheck and lint checks that run mypy,
+// pyright, ty or ruff from the project's .venv under the sandboxed recipe
+// (sandbox.mjs). A tool is proposed when it is installed in .venv/bin. Its
+// arguments are the ones the project runs it with, read from CI workflows,
+// the Makefile, tox, nox, a justfile and shell scripts; without one, the
+// tool's own default (`ruff check`, `ty check`, `pyright`, and `mypy` with
+// its configured files or `.`).
+import fs from 'node:fs';
+import path from 'node:path';
+import {realObservedPath} from './path-identity.mjs';
+import {sandboxCheckInputs,sandboxQualification} from './sandbox.mjs';
+
+const read=file=>{try{return fs.readFileSync(file,'utf8');}catch{return '';}};
+const exists=file=>{try{fs.lstatSync(file);return true;}catch{return false;}};
+const executable=file=>{try{fs.accessSync(file,fs.constants.X_OK);return fs.statSync(file).isFile();}catch{return false;}};
+// Each tool, its kind, and the subcommand it runs as a check.
+export const pythonTools=[{tool:'mypy',kind:'typecheck',sub:[]},{tool:'pyright',kind:'typecheck',sub:[]},
+  {tool:'ty',kind:'typecheck',sub:['check']},{tool:'ruff',kind:'lint',sub:['check']}];
+// The text of a TOML or INI section, up to the next section header.
+const section=(text,header)=>{const at=text.split(/\r?\n/).findIndex(line=>line.trim()===header);
+  if(at<0)return null;const rest=text.split(/\r?\n/).slice(at+1);const end=rest.findIndex(line=>/^\s*\[/.test(line));
+  return (end<0?rest:rest.slice(0,end)).join('\n');};
+// Ways a project starts a tool: through uv, poetry or pdm, `python -m`, or from .venv/bin.
+const wrappers=[/^uv run(?: --(?:frozen|locked|no-sync|offline|quiet|all-extras|all-groups))*(?: --(?:group|extra|with|python|package) [^ ]+)* /,
+  /^poetry run /,/^pdm run /,/^python3?(?:\.\d+)? -m /,/^(?:\.\/)?\.venv\/bin\//,
+  // A variable that names the environment's bin directory: `${PREFIX}mypy`.
+  /^\$\{?[A-Za-z_]+\}?(?=[A-Za-z])/];
+// A tool's arguments in one line of a script or workflow, or null. The line
+// must run the tool and its subcommand plainly; arguments with shell syntax,
+// or ones that change files or install packages, are not taken.
+export function toolArgs(line,{tool,sub}){
+  let text=line.trim().replace(/^-\s+/,'').replace(/^run:\s*/,'').replace(/^[@-]+/,'');
+  text=text.split(/\s(?:&&|\|\||;|\|)\s/)[0].replace(/\s+/g,' ').trim();
+  for(let changed=true;changed;){changed=false;for(const wrapper of wrappers)if(wrapper.test(text)){text=text.replace(wrapper,'');changed=true;}}
+  const words=text.split(' ');
+  if(words[0]!==tool||JSON.stringify(words.slice(1,1+sub.length))!==JSON.stringify(sub))return null;
+  const args=words.slice(1+sub.length);
+  if(args.some(arg=>!/^[A-Za-z0-9_./:=,@+%-]+$/.test(arg)||/^--(?:fix|unsafe-fixes|write|install-types|watch)(?:=|$)/.test(arg)||arg.startsWith('..')||arg.startsWith('/')))return null;
+  return args;
+}
+// The places a project writes how it runs its tools, in order of preference.
+function scriptTexts(root){
+  const texts=[];
+  const workflows=path.join(root,'.github','workflows');
+  let files=[];try{files=fs.readdirSync(workflows).filter(file=>/\.ya?ml$/.test(file)).sort();}catch{}
+  for(const file of files)texts.push(read(path.join(workflows,file)));
+  for(const file of ['Makefile','makefile','justfile','tox.ini','noxfile.py'])texts.push(read(path.join(root,file)));
+  // Shell scripts: *.sh, or a file whose #! line runs a shell (scripts/check).
+  for(const dir of ['scripts','script','bin','ci']){let names=[];try{names=fs.readdirSync(path.join(root,dir)).sort();}catch{}
+    for(const name of names){const text=read(path.join(root,dir,name)).slice(0,65536);
+      if(name.endsWith('.sh')||/^#!\S*(?:\/|env\s+)(?:ba|z|da)?sh\b/.test(text))texts.push(text);}}
+  return texts;
+}
+// The arguments the project runs `tool` with, or its default.
+export function projectArgs(root,spec,texts=scriptTexts(root)){
+  for(const text of texts)for(const line of text.split(/\r?\n/)){
+    if(/^\s*#/.test(line))continue;
+    const args=toolArgs(line,spec);
+    if(args)return {args,source:'project'};
+  }
+  if(spec.tool!=='mypy')return {args:[],source:'default'};
+  // mypy without targets needs `files` in its configuration.
+  const configured=[section(read(path.join(root,'pyproject.toml')),'[tool.mypy]'),section(read(path.join(root,'mypy.ini')),'[mypy]'),
+    section(read(path.join(root,'.mypy.ini')),'[mypy]'),section(read(path.join(root,'setup.cfg')),'[mypy]')].some(text=>text&&/^\s*files\s*=/m.test(text));
+  return {args:configured?[]:['.'],source:'default'};
+}
+// The Python checks `init` proposes, or null when the root is not a Python
+// project. Each row is ready only once init has run it both ways (bin/redue.mjs).
+export function discoverPythonProject(root){
+  root=realObservedPath(root);
+  if(!['pyproject.toml','setup.cfg','setup.py','requirements.txt'].some(file=>exists(path.join(root,file))))return null;
+  const checks=[],skipped=[];
+  if(!exists(path.join(root,'.venv','pyvenv.cfg'))){
+    skipped.push({kind:'python',reason:'no .venv in the project root; REDUE runs Python tools from the project\'s .venv (uv sync, or Poetry with virtualenvs.in-project)'});
+    return {root,checks,skipped};
+  }
+  const texts=scriptTexts(root);
+  const found=pythonTools.filter(spec=>executable(path.join(root,'.venv','bin',spec.tool)));
+  for(const spec of found){
+    const {args,source}=projectArgs(root,spec,texts);
+    const several=found.filter(other=>other.kind===spec.kind).length>1;
+    checks.push({config:{name:several?`${spec.kind}:${spec.tool}`:spec.kind,kind:spec.kind,qualification:sandboxQualification,
+      command:[`.venv/bin/${spec.tool}`,...spec.sub,...args],...sandboxCheckInputs()},level:'ready',qualification:sandboxQualification,
+      reason:`sandboxed recipe: ${[spec.tool,...spec.sub,...args].join(' ')} from .venv${source==='project'?' as the project runs it':''}; the whole checkout is its input`});
+  }
+  return {root,checks,skipped};
+}