litmus-cli 1.4.7 → 1.4.9

package/dist/lib/detect-project.js

@@ -101,7 +101,7 @@ export function resolvePythonInterpreter() {
  * which is the case a warning most needs to catch. `shell: true` on Windows so
  * `.cmd`/`.ps1` shims resolve, matching the Python probe above.
  */
-function isOnPath(bin) {
+export function isOnPath(bin) {
     try {
         return (spawnSync(bin, ["--version"], {
             encoding: "utf8",
@@ -116,7 +116,8 @@ function isOnPath(bin) {
 /**
  * Detect project type and suggest an install command.
  */
-export function detectProject(dir) {
+export function detectProject(dir, deps = {}) {
+    const onPath = deps.isOnPath ?? isOnPath;
     if (existsSync(path.join(dir, "package.json"))) {
         const hasYarnLock = existsSync(path.join(dir, "yarn.lock"));
         const hasPnpmLock = existsSync(path.join(dir, "pnpm-lock.yaml"));
@@ -133,24 +134,13 @@ export function detectProject(dir) {
                 : hasBunLock
                     ? "bun install"
                     : "npm install";
-        // Same disclosure contract as the Python skew below: a missing toolchain is
-        // ours to state here, not theirs to infer. Without this, `init`'s install
-        // failure prints "run `bun install` manually", which is the command that just
-        // failed — and the candidate is left guessing that a runtime they may never
-        // have heard of is the missing piece.
-        //
         // Gated on the SELECTED command, not on `hasBunLock`. A repo carrying both a
-        // bun lockfile and a pnpm/yarn one resolves to pnpm/yarn above, and telling
-        // that candidate to install Bun and run `bun install` would send them to
-        // install a second, competing dependency tree over the one we just built.
-        // Also means npm/yarn/pnpm repos never pay for the PATH probe.
-        const toolchainWarning = installCommand === "bun install" && !isOnPath("bun")
-            ? "This assessment's scaffold is a Bun project (bun.lock), and Bun isn't on " +
-                "your PATH. Install it from https://bun.sh, then re-run `bun install` in " +
-                "this folder. npm can install the dependencies but cannot run the " +
-                "scaffold's server — it uses Bun-only APIs."
-            : undefined;
-        return { type: "node", installCommand, toolchainWarning };
+        // bun lockfile and a pnpm/yarn one resolves to pnpm/yarn above, and reporting
+        // bun as missing there would send the candidate to install a second,
+        // competing dependency tree over the one we just built. Also means
+        // npm/yarn/pnpm repos never pay for the PATH probe.
+        const missingRuntime = installCommand === "bun install" && !onPath("bun") ? "bun" : undefined;
+        return { type: "node", installCommand, missingRuntime };
     }
     if (existsSync(path.join(dir, "requirements.txt")) ||
         existsSync(path.join(dir, "pyproject.toml")) ||
@@ -203,4 +193,35 @@ export function detectProject(dir) {
     }
     return { type: "unknown", installCommand: null };
 }
+/** How each supported runtime is obtained. npm ships per-platform bun binaries,
+ *  and npm is guaranteed present because this CLI is an npm package. */
+export const RUNTIME_INSTALL = {
+    bun: "npm install -g bun",
+};
+/**
+ * Install a runtime the project needs and the machine lacks.
+ *
+ * Separated from `init`'s reporting so all three outcomes are assertable: the
+ * install failing, and the install "succeeding" while leaving nothing on PATH.
+ * That second case is the one worth a unit test — a global install can land
+ * somewhere this process cannot reach, and treating it as success means the
+ * dependency install below dies on a command-not-found we already knew about.
+ */
+export function installRuntime(runtime, deps = {}) {
+    const exec = deps.exec ?? ((command) => {
+        // spawnSync reports a failure in `status` rather than throwing, so surface
+        // it as one — the catch below is what turns it into "unavailable".
+        const r = spawnSync(command, { shell: true, stdio: "pipe" });
+        if (r.status !== 0)
+            throw new Error(`\`${command}\` exited ${r.status}`);
+    });
+    const onPath = deps.isOnPath ?? isOnPath;
+    try {
+        exec(RUNTIME_INSTALL[runtime]);
+    }
+    catch {
+        return "unavailable";
+    }
+    return onPath(runtime) ? "installed" : "unavailable";
+}
 //# sourceMappingURL=detect-project.js.map

package/dist/lib/detect-project.js.map

@@ -1 +1 @@
-{"version":3,"file":"detect-project.js","sourceRoot":"","sources":["../../src/lib/detect-project.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,eAAe,CAAA;AACzC,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,IAAI,CAAA;AAC5C,OAAO,IAAI,MAAM,MAAM,CAAA;AAyBvB;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG,MAAM,CAAA;AAS5C;;;;;;;;;;;;;;;;GAgBG;AACH,SAAS,gBAAgB;IACvB,MAAM,OAAO,GAAG,sBAAsB,CAAA;IACtC,IAAI,OAAO,CAAC,QAAQ,KAAK,OAAO,EAAE,CAAC;QACjC,OAAO;YACL,EAAE,GAAG,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,IAAI,OAAO,EAAE,CAAC,EAAE,OAAO,EAAE,OAAO,OAAO,EAAE,EAAE;YAC/D,EAAE,GAAG,EAAE,IAAI,EAAE,IAAI,EAAE,EAAE,EAAE,OAAO,EAAE,IAAI,EAAE;YACtC,EAAE,GAAG,EAAE,QAAQ,EAAE,IAAI,EAAE,EAAE,EAAE,OAAO,EAAE,QAAQ,EAAE;YAC9C,EAAE,GAAG,EAAE,SAAS,EAAE,IAAI,EAAE,EAAE,EAAE,OAAO,EAAE,SAAS,EAAE;SACjD,CAAA;IACH,CAAC;IACD,OAAO;QACL,EAAE,GAAG,EAAE,SAAS,OAAO,EAAE,EAAE,IAAI,EAAE,EAAE,EAAE,OAAO,EAAE,SAAS,OAAO,EAAE,EAAE;QAClE,EAAE,GAAG,EAAE,SAAS,EAAE,IAAI,EAAE,EAAE,EAAE,OAAO,EAAE,SAAS,EAAE;KACjD,CAAA;AACH,CAAC;AAED,2EAA2E;AAC3E,SAAS,YAAY,CAAC,SAA0B;IAC9C,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,SAAS,CAAC,SAAS,CAAC,GAAG,EAAE,CAAC,GAAG,SAAS,CAAC,IAAI,EAAE,WAAW,CAAC,EAAE;YACxE,QAAQ,EAAE,MAAM;YAChB,KAAK,EAAE,OAAO,CAAC,QAAQ,KAAK,OAAO;SACpC,CAAC,CAAA;QACF,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,IAAI,CAAA;QACpC,MAAM,KAAK,GAAG,6BAA6B,CAAC,IAAI,CAAC,GAAG,MAAM,CAAC,MAAM,IAAI,EAAE,GAAG,MAAM,CAAC,MAAM,IAAI,EAAE,EAAE,CAAC,CAAA;QAChG,OAAO,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAA;IAChC,CAAC;IAAC,MAAM,CAAC;QACP,iEAAiE;QACjE,OAAO,IAAI,CAAA;IACb,CAAC;AACH,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,wBAAwB;IAKtC,MAAM,UAAU,GAAG,gBAAgB,EAAE,CAAA;IACrC,KAAK,MAAM,SAAS,IAAI,UAAU,EAAE,CAAC;QACnC,MAAM,eAAe,GAAG,YAAY,CAAC,SAAS,CAAC,CAAA;QAC/C,IAAI,CAAC,eAAe;YAAE,SAAQ;QAC9B,OAAO;YACL,OAAO,EAAE,SAAS,CAAC,OAAO;YAC1B,wEAAwE;YACxE,mEAAmE;YACnE,sCAAsC;YACtC,aAAa,EAAE,eAAe,CAAC,UAAU,CAAC,GAAG,sBAAsB,GAAG,CAAC;gBACrE,eAAe,KAAK,sBAAsB;YAC5C,eAAe;SAChB,CAAA;IACH,CAAC;IAED,MAAM,IAAI,GAAG,UAAU,CAAC,UAAU,CAAC,MAAM,GAAG,CAAC,CAAC,CAAA;IAC9C,OAAO,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,aAAa,EAAE,KAAK,EAAE,eAAe,EAAE,IAAI,EAAE,CAAA;AAC/E,CAAC;AAED;;;;;;;;GAQG;AACH,SAAS,QAAQ,CAAC,GAAW;IAC3B,IAAI,CAAC;QACH,OAAO,CACL,SAAS,CAAC,GAAG,EAAE,CAAC,WAAW,CAAC,EAAE;YAC5B,QAAQ,EAAE,MAAM;YAChB,KAAK,EAAE,OAAO,CAAC,QAAQ,KAAK,OAAO;SACpC,CAAC,CAAC,MAAM,KAAK,CAAC,CAChB,CAAA;IACH,CAAC;IAAC,MAAM,CAAC;QACP,0EAA0E;QAC1E,OAAO,KAAK,CAAA;IACd,CAAC;AACH,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,aAAa,CAAC,GAAW;IACvC,IAAI,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,cAAc,CAAC,CAAC,EAAE,CAAC;QAC/C,MAAM,WAAW,GAAG,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,WAAW,CAAC,CAAC,CAAA;QAC3D,MAAM,WAAW,GAAG,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,gBAAgB,CAAC,CAAC,CAAA;QAChE,8EAA8E;QAC9E,+EAA+E;QAC/E,gFAAgF;QAChF,+EAA+E;QAC/E,yDAAyD;QACzD,MAAM,UAAU,GACd,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,UAAU,CAAC,CAAC,IAAI,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,WAAW,CAAC,CAAC,CAAA;QACnF,MAAM,cAAc,GAAG,WAAW;YAChC,CAAC,CAAC,cAAc;YAChB,CAAC,CAAC,WAAW;gBACX,CAAC,CAAC,MAAM;gBACR,CAAC,CAAC,UAAU;oBACV,CAAC,CAAC,aAAa;oBACf,CAAC,CAAC,aAAa,CAAA;QACrB,4EAA4E;QAC5E,0EAA0E;QAC1E,8EAA8E;QAC9E,4EAA4E;QAC5E,sCAAsC;QACtC,EAAE;QACF,6EAA6E;QAC7E,4EAA4E;QAC5E,yEAAyE;QACzE,0EAA0E;QAC1E,+DAA+D;QAC/D,MAAM,gBAAgB,GACpB,cAAc,KAAK,aAAa,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC;YAClD,CAAC,CAAC,2EAA2E;gBAC3E,0EAA0E;gBAC1E,mEAAmE;gBACnE,4CAA4C;YAC9C,CAAC,CAAC,SAAS,CAAA;QACf,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,cAAc,EAAE,gBAAgB,EAAE,CAAA;IAC3D,CAAC;IAED,IACE,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,kBAAkB,CAAC,CAAC;QAC9C,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,gBAAgB,CAAC,CAAC;QAC5C,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,UAAU,CAAC,CAAC,EACtC,CAAC;QACD,0EAA0E;QAC1E,0EAA0E;QAC1E,MAAM,MAAM,GAAG,OAAO,CAAC,QAAQ,KAAK,OAAO,CAAC,CAAC,CAAC,oBAAoB,CAAC,CAAC,CAAC,cAAc,CAAA;QACnF,MAAM,MAAM,GAAG,wBAAwB,EAAE,CAAA;QACzC,MAAM,cAAc,GAAG,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,kBAAkB,CAAC,CAAC;YACnE,CAAC,CAAC,GAAG,MAAM,CAAC,OAAO,oBAAoB,MAAM,8BAA8B;YAC3E,CAAC,CAAC,GAAG,MAAM,CAAC,OAAO,oBAAoB,MAAM,eAAe,CAAA;QAC9D,2EAA2E;QAC3E,yEAAyE;QACzE,yEAAyE;QACzE,4EAA4E;QAC5E,mDAAmD;QACnD,MAAM,gBAAgB,GAAG,MAAM,CAAC,aAAa;YAC3C,CAAC,CAAC,SAAS;YACX,CAAC,CAAC,MAAM,CAAC,eAAe;gBACtB,CAAC,CAAC,uCAAuC,sBAAsB,yBAAyB;oBACtF,UAAU,MAAM,CAAC,eAAe,OAAO,MAAM,CAAC,OAAO,wCAAwC;oBAC7F,oEAAoE;oBACpE,GAAG,sBAAsB,oDAAoD;gBAC/E,CAAC,CAAC,sDAAsD,MAAM,CAAC,OAAO,kBAAkB;oBACtF,sDAAsD,sBAAsB,aAAa;oBACzF,0CAA0C,CAAA;QAChD,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,cAAc,EAAE,gBAAgB,EAAE,CAAA;IAC7D,CAAC;IAED,IAAI,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAC,EAAE,CAAC;QACzC,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,cAAc,EAAE,iBAAiB,EAAE,CAAA;IAC1D,CAAC;IAED,IAAI,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,SAAS,CAAC,CAAC,EAAE,CAAC;QAC1C,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,cAAc,EAAE,aAAa,EAAE,CAAA;IACxD,CAAC;IAED,IAAI,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,cAAc,CAAC,CAAC,IAAI,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,kBAAkB,CAAC,CAAC,EAAE,CAAC;QACjG,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,cAAc,EAAE,cAAc,EAAE,CAAA;IACzD,CAAC;IAED,MAAM,KAAK,GAAG,WAAW,CAAC,GAAG,CAAC,CAAA;IAC9B,IAAI,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC;QACjE,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,cAAc,EAAE,gBAAgB,EAAE,CAAA;IAC7D,CAAC;IAED,IAAI,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,YAAY,CAAC,CAAC,EAAE,CAAC;QAC7C,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,cAAc,EAAE,IAAI,EAAE,CAAA;IAC/C,CAAC;IAED,IAAI,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,SAAS,CAAC,CAAC,EAAE,CAAC;QAC1C,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,cAAc,EAAE,gBAAgB,EAAE,CAAA;IAC3D,CAAC;IAED,IAAI,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,eAAe,CAAC,CAAC,EAAE,CAAC;QAChD,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,cAAc,EAAE,kBAAkB,EAAE,CAAA;IAC5D,CAAC;IAED,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,cAAc,EAAE,IAAI,EAAE,CAAA;AAClD,CAAC"}
+{"version":3,"file":"detect-project.js","sourceRoot":"","sources":["../../src/lib/detect-project.ts"],"names":[],"mappings":"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"}

package/dist/lib/extract.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"extract.d.ts","sourceRoot":"","sources":["../../src/lib/extract.ts"],"names":[],"mappings":"AAYA;;;GAGG;AACH,wBAAsB,UAAU,CAC9B,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,IAAI,CAAC,CAuCf"}
+{"version":3,"file":"extract.d.ts","sourceRoot":"","sources":["../../src/lib/extract.ts"],"names":[],"mappings":"AAYA;;;GAGG;AACH,wBAAsB,UAAU,CAC9B,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,IAAI,CAAC,CAmEf"}

package/dist/lib/extract.js

@@ -1,5 +1,5 @@
 import { createWriteStream } from "fs";
-import { mkdir } from "fs/promises";
+import { chmod, mkdir } from "fs/promises";
 import path from "path";
 import { pipeline } from "stream/promises";
 import unzipper from "unzipper";
@@ -42,6 +42,33 @@ export async function extractZip(zipPath, targetDir) {
         }
         await mkdir(path.dirname(resolvedPath), { recursive: true });
         await pipeline(entry.stream(), createWriteStream(resolvedPath));
+        // RESTORE THE EXECUTABLE BIT, which `createWriteStream` drops.
+        //
+        // It writes with the default mode and ignores whatever the archive says, so
+        // a package whose brief instructs
+        //
+        //     ./bin/train --config config/run.json --out runs/mine
+        //
+        // extracted to a non-executable file and the candidate hit "Permission
+        // denied" on the first thing they were told to do. Manual `unzip` honours
+        // the mode, so this only ever broke for people using the CLI, which is
+        // everyone.
+        //
+        // GRANTED, NOT COPIED. We add +x when the archive marks the entry
+        // executable and clamp to 0755; we never apply the archive's mode verbatim.
+        // An archive can carry setuid, setgid and sticky bits, and nothing arriving
+        // over the wire should be able to set those on a candidate's machine.
+        // Anything not marked executable keeps the default write mode.
+        //
+        // The unix mode lives in the high half of the ZIP's external attributes.
+        // Absent on archives written by tools that store no mode, which reads as 0
+        // and correctly grants nothing.
+        const mode = (entry.externalFileAttributes ?? 0) >>> 16;
+        if (mode & 0o111) {
+            // Best-effort: on Windows chmod only toggles the read-only flag, and a
+            // filesystem that refuses it should not fail the whole extraction.
+            await chmod(resolvedPath, 0o755).catch(() => { });
+        }
     }
 }
 //# sourceMappingURL=extract.js.map

package/dist/lib/extract.js.map

@@ -1 +1 @@
-{"version":3,"file":"extract.js","sourceRoot":"","sources":["../../src/lib/extract.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,IAAI,CAAA;AACtC,OAAO,EAAE,KAAK,EAAE,MAAM,aAAa,CAAA;AACnC,OAAO,IAAI,MAAM,MAAM,CAAA;AACvB,OAAO,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAA;AAC1C,OAAO,QAAQ,MAAM,UAAU,CAAA;AAE/B,6EAA6E;AAC7E,8EAA8E;AAC9E,gEAAgE;AAChE,MAAM,eAAe,GAAG,GAAG,GAAG,IAAI,GAAG,IAAI,CAAA,CAAC,yBAAyB;AACnE,MAAM,cAAc,GAAG,MAAO,CAAA;AAE9B;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,UAAU,CAC9B,OAAe,EACf,SAAiB;IAEjB,MAAM,cAAc,GAAG,IAAI,CAAC,OAAO,CAAC,SAAS,CAAC,GAAG,IAAI,CAAC,GAAG,CAAA;IACzD,MAAM,KAAK,CAAC,cAAc,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAA;IAEhD,MAAM,SAAS,GAAG,MAAM,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,CAAA;IAEnD,IAAI,SAAS,CAAC,KAAK,CAAC,MAAM,GAAG,cAAc,EAAE,CAAC;QAC5C,MAAM,IAAI,KAAK,CAAC,+BAA+B,SAAS,CAAC,KAAK,CAAC,MAAM,iBAAiB,cAAc,yBAAyB,CAAC,CAAA;IAChI,CAAC;IAED,IAAI,UAAU,GAAG,CAAC,CAAA;IAClB,KAAK,MAAM,KAAK,IAAI,SAAS,CAAC,KAAK,EAAE,CAAC;QACpC,MAAM,YAAY,GAAG,IAAI,CAAC,OAAO,CAAC,cAAc,EAAE,KAAK,CAAC,IAAI,CAAC,CAAA;QAC7D,IAAI,CAAC,YAAY,CAAC,UAAU,CAAC,cAAc,CAAC,EAAE,CAAC;YAC7C,MAAM,IAAI,KAAK,CACb,iCAAiC,KAAK,CAAC,IAAI,4BAA4B,CACxE,CAAA;QACH,CAAC;QAED,IAAI,KAAK,CAAC,IAAI,KAAK,WAAW,EAAE,CAAC;YAC/B,MAAM,KAAK,CAAC,YAAY,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAA;YAC9C,SAAQ;QACV,CAAC;QACD,yEAAyE;QACzE,uEAAuE;QACvE,4EAA4E;QAC5E,mDAAmD;QACnD,IAAK,KAAK,CAAC,IAAe,KAAK,cAAc;YAAE,SAAQ;QAEvD,MAAM,UAAU,GAAG,OAAO,KAAK,CAAC,gBAAgB,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,gBAAgB,CAAC,CAAC,CAAC,CAAC,CAAA;QAC1F,UAAU,IAAI,UAAU,CAAA;QACxB,IAAI,UAAU,GAAG,eAAe,EAAE,CAAC;YACjC,MAAM,IAAI,KAAK,CACb,wCAAwC,CAAC,eAAe,GAAG,IAAI,GAAG,IAAI,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,qCAAqC,CACxH,CAAA;QACH,CAAC;QACD,MAAM,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,YAAY,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAA;QAC5D,MAAM,QAAQ,CAAC,KAAK,CAAC,MAAM,EAAE,EAAE,iBAAiB,CAAC,YAAY,CAAC,CAAC,CAAA;IACjE,CAAC;AACH,CAAC"}
+{"version":3,"file":"extract.js","sourceRoot":"","sources":["../../src/lib/extract.ts"],"names":[],"mappings":"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"}

package/dist/lib/python-env.d.ts

@@ -0,0 +1,157 @@
+/**
+ * Bind a Python assessment's notebook to the environment `init` just built.
+ *
+ * WHY THIS EXISTS AT ALL (ENG-1824). `litmus init` has always created `venv/`
+ * and installed into it, and ENG-1417 made it prefer the grading interpreter
+ * and warn when it could not get one. None of that reaches a notebook. For an
+ * `.ipynb` deliverable the graded artifact is the SAVED CELL OUTPUT — the
+ * extractor parses the notebook as JSON and never re-executes it — so the
+ * interpreter that decides the result is the one Jupyter picked, not the one
+ * in `venv/`. A perfect venv the kernel never uses buys exactly zero, and the
+ * shipped notebooks carry the generic kernelspec `{"name": "python3"}`, which
+ * resolves to whatever `python3` kernel the machine happens to have. A
+ * candidate with their own JupyterLab and their own pandas therefore runs
+ * every cell on a foreign interpreter, and nothing anywhere notices.
+ *
+ * EVERYTHING HERE IS BEST-EFFORT AND NEVER FATAL. It runs on the path that
+ * decides whether a candidate can start working, against tooling we do not
+ * control, on three platforms. A kernel we failed to register is a candidate
+ * who picks one manually — today's behaviour. An exception thrown here would
+ * be a candidate who cannot start at all, which is far worse than the skew it
+ * was trying to prevent. Every entry point returns a result and swallows.
+ */
+/** Where the venv's interpreter lives, per platform. */
+export declare function venvPython(dir: string): string;
+/** The `jupyter` the candidate should be told to run: the venv's own. */
+export declare function venvJupyterCommand(): string;
+/**
+ * Is `jupyter lab` actually runnable in this venv?
+ *
+ * `ipykernel` alone is not enough to answer that, and `ipykernel` is what the
+ * kernel registration proves. It brings in `jupyter-core`, so `venv/bin/jupyter`
+ * EXISTS while the `lab` subcommand — a separate `jupyterlab` distribution —
+ * does not. Telling a candidate to run the first and most prominent command we
+ * give them, and having it answer `'lab' is not a Jupyter command`, is a worse
+ * first thirty seconds than saying nothing.
+ */
+export declare function hasJupyterLab(dir: string): boolean;
+export declare function uvVersion(): string | null;
+/**
+ * Build `venv/` with uv, pinned to the grading interpreter.
+ *
+ * The directory name is passed EXPLICITLY. uv's default is `.venv`, and every
+ * line of instruction we ship — the package README's `source venv/bin/activate`
+ * included — names `venv`. Taking uv's default here would leave the candidate
+ * reading true-looking instructions about a directory that does not exist.
+ */
+export declare function buildVenvWithUv(dir: string): boolean;
+/**
+ * The distributions `requirements.txt` declares, as installable names.
+ *
+ * Deliberately conservative: anything that is not a plain pinned-or-floored
+ * requirement (a flag, an `-r` include, a URL, a path) is dropped rather than
+ * guessed at, because the only consumer is a probe whose false alarms would be
+ * worse than its silence.
+ */
+export declare function declaredRequirements(dir: string): string[];
+export interface EnvProbe {
+    version: string | null;
+    /** Declared distributions that are not installed in the venv. */
+    missing: string[];
+    /** Top-level modules that are installed but fail to import (broken wheel/ABI). */
+    broken: string[];
+}
+/**
+ * Ask the venv's own interpreter what it has.
+ *
+ * PRESENCE IS CHECKED THROUGH `importlib.metadata`, NOT BY IMPORTING THE
+ * REQUIREMENT NAME. Distribution names and module names disagree often enough
+ * (`beautifulsoup4`/`bs4`, `scikit-learn`/`sklearn`, `pillow`/`PIL`) that a
+ * hand-maintained alias table would eventually tell a candidate their working
+ * environment is broken. The metadata lookup is exact. The import check is
+ * then driven off the metadata's own top-level modules, so it stays exact too
+ * while still catching the case presence cannot — a wheel that installs and
+ * then fails to load.
+ */
+export declare function probeEnvironment(dir: string): EnvProbe;
+/**
+ * A kernelspec name identifying ONE CHECKOUT, not one assessment.
+ *
+ * Jupyter lowercases kernelspec names on install and matches them literally
+ * afterwards, so the name is normalised HERE rather than being compared
+ * case-insensitively later — otherwise the notebook we rewrite points at
+ * `litmus-Foo` while the registered kernel is `litmus-foo`, and the candidate
+ * gets a picker prompt about a missing kernel, which is worse than the generic
+ * name we started with.
+ *
+ * THE PATH FINGERPRINT IS WHAT KEEPS TWO CHECKOUTS APART, and the name alone
+ * cannot: kernelspecs are user-scope and `ipykernel install` OVERWRITES a spec
+ * of the same name. Two folders that normalise alike — a practice run beside a
+ * real attempt, the same assessment re-initialised under a different parent,
+ * or two companies who both called theirs "Take Home" — would otherwise share
+ * one spec. The second init would silently redirect the first notebook at the
+ * second checkout's interpreter, and submitting either would delete the spec
+ * the other one is bound to. The fingerprint is not shown to anyone: the
+ * picker displays `display_name`, and the notebook is bound by name so the
+ * candidate never has to read either.
+ */
+export declare function kernelNameFor(folderName: string, projectRoot: string): string;
+/**
+ * Register the venv's interpreter as a Jupyter kernel.
+ *
+ * `--user`, NOT `--sys-prefix`. A sys-prefix kernel is visible only to a
+ * JupyterLab launched from inside that venv, which excludes exactly the
+ * candidate this whole change is for: the one who already has a global
+ * JupyterLab, opens the notebook with it, and cannot even SEE the correct
+ * kernel. A user-scope kernelspec is discoverable by any Jupyter on the
+ * machine, which is the property that makes the notebook rewrite below mean
+ * something.
+ *
+ * Requires `ipykernel` in the venv. Assessments that ship jupyterlab get it
+ * transitively; ones that do not simply return false and the flow degrades to
+ * today's behaviour.
+ */
+export declare function registerKernel(dir: string, name: string, displayName: string): boolean;
+/**
+ * Remove the kernel we registered, before the assessment folder goes away.
+ *
+ * A user-scope kernelspec OUTLIVES THE FOLDER, and `litmus submit` deletes the
+ * folder. Left behind, it is a permanent entry in the candidate's own Jupyter
+ * pointing at an interpreter that no longer exists — our litter on their
+ * machine, and a broken kernel in every notebook they open afterwards. We made
+ * the global change, so we undo it.
+ *
+ * Called while the venv still exists, because that is what provides
+ * `jupyter_client` — asking it to remove the spec is how this stays correct on
+ * all three platforms without hardcoding three kernel directories.
+ */
+export declare function unregisterKernel(dir: string, name: string): boolean;
+/**
+ * Rewrite a notebook's kernelspec name/display_name, changing nothing else.
+ *
+ * A SURGICAL STRING EDIT, NOT A PARSE-AND-SERIALISE. The obvious
+ * implementation — `JSON.parse`, mutate, `JSON.stringify` — reformats the
+ * whole file: a 900-line notebook collapses to one line with the default
+ * serialiser and still differs byte-for-byte under any indent setting. That
+ * matters here more than it usually would, because `init` git-commits the
+ * extracted package as the candidate's baseline and the notebook diff against
+ * that baseline is grading evidence. Reflowing the deliverable before the
+ * candidate has opened it turns every later diff into one line of churn on the
+ * one file that carries their work.
+ *
+ * So: find the `kernelspec` object, replace the two string values inside it,
+ * leave every other byte — including `language`, the trailing whitespace and
+ * the file's own indentation — exactly as shipped. Returns null when there is
+ * nothing to edit, which is a report, not a failure: a notebook without a
+ * kernelspec is one we should leave alone rather than restructure.
+ */
+export declare function rewriteKernelspec(source: string, name: string, displayName: string): string | null;
+/**
+ * Point every notebook the package shipped at the registered kernel.
+ *
+ * Scoped to notebooks that exist at init time, i.e. ones we shipped. The
+ * candidate's own later notebooks are theirs; the deliverable is the one that
+ * has to execute on the environment we built.
+ */
+export declare function bindNotebooks(dir: string, name: string, displayName: string): string[];
+//# sourceMappingURL=python-env.d.ts.map

package/dist/lib/python-env.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"python-env.d.ts","sourceRoot":"","sources":["../../src/lib/python-env.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAUH,wDAAwD;AACxD,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAI9C;AAED,yEAAyE;AACzE,wBAAgB,kBAAkB,IAAI,MAAM,CAE3C;AAED;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAKlD;AAwDD,wBAAgB,SAAS,IAAI,MAAM,GAAG,IAAI,CAOzC;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CA0CpD;AAID;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,EAAE,CAmB1D;AAED,MAAM,WAAW,QAAQ;IACvB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;IACtB,iEAAiE;IACjE,OAAO,EAAE,MAAM,EAAE,CAAA;IACjB,kFAAkF;IAClF,MAAM,EAAE,MAAM,EAAE,CAAA;CACjB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,QAAQ,CAgDtD;AAID;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,aAAa,CAAC,UAAU,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,MAAM,CAW7E;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAOtF;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAUnE;AAID;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,WAAW,EAAE,MAAM,GAClB,MAAM,GAAG,IAAI,CA6Df;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,MAAM,EAAE,CAoCtF"}