pll-python 0.8.1 → 0.9.1

package/cli.cjs

@@ -24,8 +24,8 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 ));
 
 // src/cli/main.ts
-var fs8 = __toESM(require("node:fs"));
-var path8 = __toESM(require("node:path"));
+var fs9 = __toESM(require("node:fs"));
+var path9 = __toESM(require("node:path"));
 
 // src/cli/args.ts
 var import_node_util = require("node:util");
@@ -93,7 +93,7 @@ function reworded(err, options, argv) {
   return message;
 }
 
-// src/cli/examplar.ts
+// src/cli/bundle.ts
 var fs4 = __toESM(require("node:fs/promises"));
 var path4 = __toESM(require("node:path"));
 
@@ -396,7 +396,8 @@ function validateBundleUrl(url) {
   }
   return `\`${url}\` must be an https address.`;
 }
-async function loadBundle(url, store, fetchImpl = globalThis.fetch) {
+var EXAMPLAR_BUNDLE = { noun: "an Examplar bundle", looksRight: looksLikeBundle };
+async function loadBundle(url, store, fetchImpl = globalThis.fetch, kind = EXAMPLAR_BUNDLE) {
   const cached = await store.read(url).catch(() => void 0);
   let response;
   try {
@@ -424,8 +425,8 @@ async function loadBundle(url, store, fetchImpl = globalThis.fetch) {
       error: `${url} is ${json.length} bytes, past the ${MAX_BUNDLE_BYTES}-byte limit`
     };
   }
-  if (!looksLikeBundle(json)) {
-    return cached ? { json: cached.json, fromCache: true, note: `${url} did not return a bundle; using the cached copy` } : { fromCache: false, error: `${url} did not return an Examplar bundle` };
+  if (!kind.looksRight(json)) {
+    return cached ? { json: cached.json, fromCache: true, note: `${url} did not return a bundle; using the cached copy` } : { fromCache: false, error: `${url} did not return ${kind.noun}` };
   }
   const etag = response.headers.get("etag") ?? void 0;
   try {
@@ -682,8 +683,8 @@ var WorkerConnection = class {
       return Promise.reject(new Error(NOT_RUNNING));
     }
     const id = this.nextId++;
-    return new Promise((resolve4, reject) => {
-      this.pending.set(id, { resolve: resolve4, reject, live });
+    return new Promise((resolve5, reject) => {
+      this.pending.set(id, { resolve: resolve5, reject, live });
       worker.post({ id, type, ...fields });
     });
   }
@@ -799,7 +800,7 @@ function concatBytes(a, b) {
 }
 
 // src/run/examplar.ts
-async function runExamplarStep(runtime, bundles, host, code, fileName) {
+async function runExamplarStep(runtime, bundles, host, code, fileName, sessionKey) {
   const bundle = await fetchBundle(bundles, host, code);
   if (bundle === null) {
     return null;
@@ -827,7 +828,7 @@ async function runExamplarStep(runtime, bundles, host, code, fileName) {
   }
   let result;
   try {
-    result = await runtime.examplarRun(code, bundle.json, fileName);
+    result = await runtime.examplarRun(code, bundle.json, fileName, sessionKey);
   } catch (err) {
     if (!(err instanceof StoppedError)) {
       host.examplarCard(failedCard(bundle, errorText(err)));
@@ -975,11 +976,14 @@ function cardBody(card) {
     body.push({
       kind: "line",
       tone: "warn",
-      text: `${BUGGY}caught ${card.caught} of ${card.total} - missed ${card.missed.join(", ")}.`
+      text: `${BUGGY}caught ${card.caught} of ${card.total} - missed ${card.missed.map(chaffLabel).join(", ")}.`
     });
   }
   return body;
 }
+function chaffLabel(id) {
+  return /^\d+$/.test(id) ? `#${id}` : id;
+}
 var UNMOUNTED_HINT = "Your tests are checked on their own, so files next to your program are not available while that happens.";
 function isFileAccessError(message) {
   return /^(FileNotFoundError|IsADirectoryError|NotADirectoryError|PermissionError|ModuleNotFoundError|ImportError):/.test(
@@ -1000,6 +1004,128 @@ function timedOutProblem(stuck) {
   return `\`${stuck.test}\` ran for more than ${stuck.seconds} seconds against ${against}, so the check stopped. ` + (stuck.kind === "wheat" ? "A test that runs that long is usually stuck in a loop." : "That implementation may never finish on what this test gives it; tell your course staff.");
 }
 
+// src/run/bundles.ts
+var DIRECTIVE_RE2 = /^#\s*bundle\s+(\S+)\s+(\S+:\/\/\S*)\s*$/;
+var NAME_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
+var KEYWORDS = /* @__PURE__ */ new Set([
+  "False",
+  "None",
+  "True",
+  "and",
+  "as",
+  "assert",
+  "async",
+  "await",
+  "break",
+  "class",
+  "continue",
+  "def",
+  "del",
+  "elif",
+  "else",
+  "except",
+  "finally",
+  "for",
+  "from",
+  "global",
+  "if",
+  "import",
+  "in",
+  "is",
+  "lambda",
+  "nonlocal",
+  "not",
+  "or",
+  "pass",
+  "raise",
+  "return",
+  "try",
+  "while",
+  "with",
+  "yield"
+]);
+var MODULE_BUNDLE = {
+  noun: "a bundle",
+  looksRight(json) {
+    try {
+      const bundle = JSON.parse(json);
+      return typeof bundle === "object" && bundle !== null && typeof bundle.bundle === "number" && typeof bundle.pyc === "string";
+    } catch {
+      return false;
+    }
+  }
+};
+function parseBundleDirectives(source) {
+  const bundles = [];
+  const problems = [];
+  const lines = source.split(/\r?\n/);
+  for (let i = 0; i < lines.length; i++) {
+    const match = DIRECTIVE_RE2.exec(lines[i].trim());
+    if (match === null) {
+      continue;
+    }
+    const [, name, url] = match;
+    const line = i + 1;
+    if (!NAME_RE.test(name) || KEYWORDS.has(name)) {
+      problems.push({
+        line,
+        message: `\`${name}\` can't name a bundle: a name is letters, digits and \`_\`, not starting with a digit, and not one of Python's keywords.`
+      });
+      continue;
+    }
+    const earlier = bundles.find((bundle) => bundle.name === name);
+    if (earlier !== void 0) {
+      problems.push({
+        line,
+        message: `line ${earlier.line} already names a bundle \`${name}\`. Give each bundle its own name.`
+      });
+      continue;
+    }
+    const problem = validateBundleUrl(url);
+    if (problem !== null) {
+      problems.push({ line, message: problem });
+      continue;
+    }
+    bundles.push({ name, url, line });
+  }
+  return { bundles, problems };
+}
+async function runBundleStep(runtime, store, host, code, sessionKey) {
+  const { bundles, problems } = parseBundleDirectives(code);
+  if (problems.length > 0) {
+    for (const problem of problems) {
+      host.say(`Line ${problem.line}: ${problem.message}`, "problem");
+    }
+    return "failed";
+  }
+  if (bundles.length === 0) {
+    return "none";
+  }
+  host.status("Loading bundles...");
+  const entries = [];
+  for (const bundle of bundles) {
+    const load = await loadBundle(bundle.url, store, void 0, MODULE_BUNDLE);
+    if (load.note) {
+      host.say(`The bundle \`${bundle.name}\`: ${load.note}`, "note");
+    }
+    if (load.json === void 0) {
+      host.say(`Line ${bundle.line}: could not load the bundle \`${bundle.name}\`: ${load.error}.`, "problem");
+      return "failed";
+    }
+    entries.push({ name: bundle.name, json: load.json });
+  }
+  const result = await runtime.bundleLoad(sessionKey, JSON.stringify(entries));
+  if (!result.ok) {
+    const at = bundles.find((bundle) => bundle.name === result.name);
+    host.say(
+      `Line ${at?.line ?? "?"}: the bundle \`${result.name ?? "?"}\` could not be loaded: ${result.error ?? "it is broken"}.`,
+      "problem"
+    );
+    return "failed";
+  }
+  return "loaded";
+}
+
 // src/run/packages.ts
 var MAY_NEED_PACKAGES_RE = /\bimport\b|__import__|\.\s*to_pandas\s*\(/;
 function needsPackages(code, siblings = []) {
@@ -1241,7 +1367,14 @@ async function runFilePlan(runtime, host, plan) {
     if (stopped(host, STOPPED.beforeStart)) {
       return "stopped";
     }
-    const complete = await runExamplarStep(runtime, plan.bundles, host, code, fileName);
+    if (await runBundleStep(runtime, plan.bundles, host, code, sessionKey) === "failed") {
+      host.say("The file was not run.", "problem");
+      return "blocked";
+    }
+    if (stopped(host, STOPPED.beforeStart)) {
+      return "stopped";
+    }
+    const complete = await runExamplarStep(runtime, plan.bundles, host, code, fileName, sessionKey);
     if (complete !== null && stopped(host, STOPPED.checking)) {
       return "stopped";
     }
@@ -1632,8 +1765,8 @@ function processStatus(code) {
 }
 async function startPython(runtime, stopRequested) {
   let watch;
-  const stop = new Promise((resolve4) => {
-    watch = setInterval(() => stopRequested() && resolve4("stopped"), 50);
+  const stop = new Promise((resolve5) => {
+    watch = setInterval(() => stopRequested() && resolve5("stopped"), 50);
   });
   try {
     return await Promise.race([
@@ -1708,7 +1841,105 @@ function cannotRead(file, err) {
   }
 }
 
+// src/cli/bundle.ts
+var BUNDLE_USAGE = `pll bundle - author bundles
+
+  pll bundle build <file.py> [-o bundle.json]
+
+A bundle is a module a program names with a line of its own,
+
+  #bundle <name> https://example.edu/<file>.json
+
+and then uses by that name, with no import: functions to call whose code
+the student doesn't see. Put the bundle where that address finds it.
+
+<file.py> is the module, with the \`#level\` line it was written at: its code
+starts with that level's names (\`dataclass\`, \`Callable\`) wherever it is
+used. Its top-level \`test_\` functions, and an \`import pytest\`, are left out
+of the bundle; everything else is in it, docstrings too.
+
+Only bytecode is written to the bundle, so the source stays in your
+repository. It is compiled by the Pyodide this package pins, so it always
+matches the interpreter that will run it.
+
+  -o, --out FILE    write here instead of stdout
+`;
+var BUNDLE_USAGE_HINT = "Usage: pll bundle build <file.py> [-o bundle.json]. `pll bundle --help` says more.";
+var BUILD_OPTIONS = {
+  out: { type: "string", short: "o", needs: "a file" },
+  help: { type: "boolean", short: "h" }
+};
+function parseBundleArgs(argv) {
+  if (argv[0] === "-h" || argv[0] === "--help") {
+    return { help: true };
+  }
+  if (argv[0] !== "build") {
+    return {
+      help: false,
+      error: argv.length === 0 ? "bundle needs a subcommand" : `unknown bundle subcommand ${argv[0]}`
+    };
+  }
+  const line = parseCommandLine(argv.slice(1), BUILD_OPTIONS);
+  if ("error" in line) {
+    return { help: false, error: line.error };
+  }
+  const { values, positionals } = line;
+  const args = {
+    file: positionals[0],
+    out: values.out,
+    help: values.help === true
+  };
+  if (positionals.length > 1) {
+    args.error = `unexpected extra argument ${positionals[1]}`;
+  } else if (!args.help && args.file === void 0) {
+    args.error = "no file given";
+  } else if (args.file !== void 0 && !args.file.endsWith(".py")) {
+    args.error = `${args.file} is not a .py file`;
+  }
+  return args;
+}
+async function runBundle(runtime, view, argv) {
+  const args = parseBundleArgs(argv);
+  if (args.help) {
+    process.stdout.write(BUNDLE_USAGE);
+    return EXIT.ok;
+  }
+  if (args.error !== void 0) {
+    process.stderr.write(`pll: ${args.error}
+${BUNDLE_USAGE_HINT}
+`);
+    return EXIT.usage;
+  }
+  const file = path4.resolve(args.file);
+  let source;
+  try {
+    source = await fs4.readFile(file, "utf8");
+  } catch (err) {
+    view.problem(`pll: cannot read ${args.file}: ${errorText(err)}`);
+    return EXIT.usage;
+  }
+  const built = await runtime.bundleBuild(source, path4.basename(file));
+  if (!built.ok || !built.bundle) {
+    view.problem(`pll: ${built.error ?? "could not build the bundle"}`);
+    return EXIT.usage;
+  }
+  const bundle = built.bundle;
+  view.note(
+    `built for Python ${bundle.built.python}, at #level ${bundle.level}: defines ${bundle.defines.join(", ") || "nothing"}`
+  );
+  const json = JSON.stringify(bundle);
+  if (args.out === void 0) {
+    process.stdout.write(json + "\n");
+  } else {
+    await fs4.writeFile(path4.resolve(args.out), json + "\n", "utf8");
+    view.note(`wrote ${args.out} (${json.length} bytes)`);
+  }
+  return EXIT.ok;
+}
+
 // src/cli/examplar.ts
+var fs5 = __toESM(require("node:fs/promises"));
+var path5 = __toESM(require("node:path"));
 var EXAMPLAR_USAGE = `pll examplar - author Examplar bundles
 
   pll examplar build <dir> [-o bundle.json] [--verify tests.py]
@@ -1740,7 +1971,7 @@ bundles with this tool rather than a local python.
                     wrong fails on everything.
 `;
 var EXAMPLAR_USAGE_HINT = "Usage: pll examplar build <dir> [-o bundle.json] [--verify tests.py]. `pll examplar --help` says more.";
-var BUILD_OPTIONS = {
+var BUILD_OPTIONS2 = {
   out: { type: "string", short: "o", needs: "a file" },
   verify: { type: "string", needs: "a test file" },
   help: { type: "boolean", short: "h" }
@@ -1755,7 +1986,7 @@ function parseExamplarArgs(argv) {
       error: argv.length === 0 ? "examplar needs a subcommand" : `unknown examplar subcommand ${argv[0]}`
     };
   }
-  const line = parseCommandLine(argv.slice(1), BUILD_OPTIONS);
+  const line = parseCommandLine(argv.slice(1), BUILD_OPTIONS2);
   if ("error" in line) {
     return { help: false, error: line.error };
   }
@@ -1775,17 +2006,17 @@ function parseExamplarArgs(argv) {
 }
 async function readDir(folder) {
   try {
-    return await fs4.readdir(folder, { withFileTypes: true });
+    return await fs5.readdir(folder, { withFileTypes: true });
   } catch {
     throw new Error(`${folder} does not exist. See \`pll examplar --help\`.`);
   }
 }
 async function readWheats(dir) {
-  const folder = path4.join(dir, "wheats");
+  const folder = path5.join(dir, "wheats");
   const out = {};
   for (const entry of await readDir(folder)) {
     if (!entry.isFile() || !entry.name.endsWith(".py")) continue;
-    out[entry.name.slice(0, -3)] = await fs4.readFile(path4.join(folder, entry.name), "utf8");
+    out[entry.name.slice(0, -3)] = await fs5.readFile(path5.join(folder, entry.name), "utf8");
   }
   if (Object.keys(out).length === 0) {
     throw new Error(`${folder} has no .py files in it.`);
@@ -1793,7 +2024,7 @@ async function readWheats(dir) {
   return out;
 }
 async function readChaffs(dir) {
-  const folder = path4.join(dir, "chaffs");
+  const folder = path5.join(dir, "chaffs");
   const out = {};
   const loose = [];
   for (const entry of await readDir(folder)) {
@@ -1802,11 +2033,11 @@ async function readChaffs(dir) {
       continue;
     }
     if (!entry.isDirectory()) continue;
-    const inner = path4.join(folder, entry.name);
+    const inner = path5.join(folder, entry.name);
     const group = {};
-    for (const file of await fs4.readdir(inner, { withFileTypes: true })) {
+    for (const file of await fs5.readdir(inner, { withFileTypes: true })) {
       if (!file.isFile() || !file.name.endsWith(".py")) continue;
-      group[file.name.slice(0, -3)] = await fs4.readFile(path4.join(inner, file.name), "utf8");
+      group[file.name.slice(0, -3)] = await fs5.readFile(path5.join(inner, file.name), "utf8");
     }
     if (Object.keys(group).length > 0) {
       out[entry.name] = group;
@@ -1814,7 +2045,7 @@ async function readChaffs(dir) {
   }
   if (loose.length > 0) {
     throw new Error(
-      `${path4.join(folder, loose[0])} is not inside a function's directory. Chaffs go in \`chaffs/<function>/\`, named after the function they break - move it to \`chaffs/<function>/${loose[0]}\`.`
+      `${path5.join(folder, loose[0])} is not inside a function's directory. Chaffs go in \`chaffs/<function>/\`, named after the function they break - move it to \`chaffs/<function>/${loose[0]}\`.`
     );
   }
   if (Object.keys(out).length === 0) {
@@ -1834,7 +2065,7 @@ ${EXAMPLAR_USAGE_HINT}
 `);
     return EXIT.usage;
   }
-  const dir = path4.resolve(args.dir);
+  const dir = path5.resolve(args.dir);
   let sources;
   try {
     sources = { wheats: await readWheats(dir), chaffs: await readChaffs(dir) };
@@ -1861,7 +2092,7 @@ ${EXAMPLAR_USAGE_HINT}
   if (args.out === void 0) {
     process.stdout.write(json + "\n");
   } else {
-    await fs4.writeFile(path4.resolve(args.out), json + "\n", "utf8");
+    await fs5.writeFile(path5.resolve(args.out), json + "\n", "utf8");
     view.note(`wrote ${args.out} (${json.length} bytes)`);
   }
   return EXIT.ok;
@@ -1872,7 +2103,7 @@ function caught(impl) {
 async function verify(runtime, view, bundle, testsPath) {
   let testSource;
   try {
-    testSource = await fs4.readFile(path4.resolve(testsPath), "utf8");
+    testSource = await fs5.readFile(path5.resolve(testsPath), "utf8");
   } catch (err) {
     view.problem(`pll: cannot read ${testsPath}: ${errorText(err)}`);
     return EXIT.usage;
@@ -1882,17 +2113,22 @@ async function verify(runtime, view, bundle, testsPath) {
   } catch {
     view.note("could not load pytest; assertion messages will be terse.");
   }
+  try {
+    await runtime.ensurePackages(testSource);
+  } catch (err) {
+    view.note(`could not load libraries (${errorText(err)}); imports may fail.`);
+  }
   const result = await runtime.examplarRun(
     testSource,
     JSON.stringify(bundle),
-    path4.basename(testsPath)
+    path5.basename(testsPath)
   );
   if (!result.ok) {
     view.problem(`pll: ${result.error ?? "the bundle could not be run"}`);
     return EXIT.usage;
   }
   let bad = 0;
-  view.problem(`verifying with ${path4.basename(testsPath)}:`);
+  view.problem(`verifying with ${path5.basename(testsPath)}:`);
   if (result.timedOut) {
     const { kind, id, targets, test, seconds } = result.timedOut;
     const where = kind === "wheat" ? `wheat ${id}` : `chaff ${targets}/${id}`;
@@ -1952,12 +2188,12 @@ async function verify(runtime, view, bundle, testsPath) {
 }
 
 // src/cli/runtime.ts
-var fs6 = __toESM(require("node:fs"));
-var path6 = __toESM(require("node:path"));
+var fs7 = __toESM(require("node:fs"));
+var path7 = __toESM(require("node:path"));
 
 // src/desktop/pyodideRuntime.ts
-var fs5 = __toESM(require("node:fs"));
-var path5 = __toESM(require("node:path"));
+var fs6 = __toESM(require("node:fs"));
+var path6 = __toESM(require("node:path"));
 var import_node_worker_threads = require("node:worker_threads");
 
 // src/run/python.ts
@@ -2038,10 +2274,27 @@ var Python = class extends WorkerConnection {
   /**
    * Run a student's tests against every implementation in a bundle.
    * `fileName` is the student's file, whose own errors are told from the
-   * implementation's.
+   * implementation's; its definitions are given the modules its `#bundle`
+   * lines name, loaded for `sessionKey`'s run (`bundleLoad`).
+   */
+  examplarRun(testSource, bundle, fileName, sessionKey = "") {
+    return this.call("_pll_examplar_run", [testSource, bundle, fileName, sessionKey]);
+  }
+  /**
+   * Compile a module into a bundle, for `pll bundle build`. Authoring only;
+   * the bytecode is this interpreter's, as `examplarBuild`'s is.
+   */
+  bundleBuild(source, fileName) {
+    return this.call("_pll_bundle_build", [source, fileName]);
+  }
+  /**
+   * Make the modules a file's `#bundle` lines name, which `sessionKey`'s
+   * next file run gives its program. `entries` is the JSON of
+   * `[{name, json}]`, each `json` a fetched bundle. Their top levels run
+   * here.
    */
-  examplarRun(testSource, bundle, fileName) {
-    return this.call("_pll_examplar_run", [testSource, bundle, fileName]);
+  bundleLoad(sessionKey, entries) {
+    return this.call("_pll_bundle_load", [sessionKey, entries]);
   }
   /**
    * Apply one event to a running reactor and get the frame it produced.
@@ -2089,7 +2342,7 @@ function deliverRunResult(result, onEvent, fileName) {
 function desktopPython(paths) {
   return new Python({
     indexUrl() {
-      const found = paths.indexUrlCandidates.find((dir) => fs5.existsSync(path5.join(dir, "pyodide.asm.wasm")));
+      const found = paths.indexUrlCandidates.find((dir) => fs6.existsSync(path6.join(dir, "pyodide.asm.wasm")));
       if (!found) {
         throw new Error(paths.missingAssetsHint);
       }
@@ -2114,7 +2367,7 @@ function desktopPython(paths) {
 function createCliRuntime() {
   return desktopPython({
     indexUrlCandidates: pyodideDirectory(),
-    workerPath: path6.join(__dirname, "worker.cjs"),
+    workerPath: path7.join(__dirname, "worker.cjs"),
     missingAssetsHint: "Could not find Pyodide's assets. Reinstall pll-python so its `pyodide` dependency is present.",
     // Ample for a first start on a slow machine; an autograder waits no
     // longer than that for a Pyodide that will never start.
@@ -2124,7 +2377,7 @@ function createCliRuntime() {
 }
 function writable(dir) {
   try {
-    fs6.accessSync(dir, fs6.constants.W_OK);
+    fs7.accessSync(dir, fs7.constants.W_OK);
     return true;
   } catch {
     return false;
@@ -2133,15 +2386,15 @@ function writable(dir) {
 function userPackageCache(indexUrl) {
   let version = "unknown";
   try {
-    const manifest = fs6.readFileSync(path6.join(indexUrl, "package.json"), "utf8");
+    const manifest = fs7.readFileSync(path7.join(indexUrl, "package.json"), "utf8");
     version = JSON.parse(manifest).version;
   } catch {
   }
-  return path6.join(cacheRoot(), `pyodide-${version}`);
+  return path7.join(cacheRoot(), `pyodide-${version}`);
 }
 function pyodideDirectory() {
   try {
-    return [path6.dirname(require.resolve("pyodide"))];
+    return [path7.dirname(require.resolve("pyodide"))];
   } catch {
     return [];
   }
@@ -2179,7 +2432,7 @@ function createStdinReader() {
         return Promise.resolve(null);
       }
       start();
-      return new Promise((resolve4) => waiting.push(resolve4));
+      return new Promise((resolve5) => waiting.push(resolve5));
     },
     close() {
       ended = true;
@@ -2194,8 +2447,8 @@ function createStdinReader() {
 }
 
 // src/cli/view.ts
-var fs7 = __toESM(require("node:fs"));
-var path7 = __toESM(require("node:path"));
+var fs8 = __toESM(require("node:fs"));
+var path8 = __toESM(require("node:path"));
 var ESC = String.fromCharCode(27);
 var CliView = class {
   constructor(opts) {
@@ -2333,10 +2586,10 @@ var CliView = class {
       );
       return;
     }
-    const target = path7.join(dir, `image-${this.imageCount}.svg`);
+    const target = path8.join(dir, `image-${this.imageCount}.svg`);
     try {
-      fs7.mkdirSync(dir, { recursive: true });
-      fs7.writeFileSync(target, svg, "utf8");
+      fs8.mkdirSync(dir, { recursive: true });
+      fs8.writeFileSync(target, svg, "utf8");
       this.note(this.dim(`[image ${width}x${height} -> ${target}]`));
     } catch (err) {
       this.problem(`Could not write ${target}: ${errorText(err)}`);
@@ -2454,6 +2707,8 @@ same everywhere.
 
 Subcommands
   examplar build       author an Examplar bundle; see \`pll examplar --help\`
+  bundle build         compile a module a \`#bundle\` line names; see
+                       \`pll bundle --help\`
 
 Options
   --no-tests           do not run the file's \`test_*\` functions, which
@@ -2472,7 +2727,8 @@ everything PLL says about the run goes to stderr.
 Exit codes
   0    ran, and any tests passed
   1    the program raised, or was stopped
-  2    level checks found problems, so it was not run
+  2    level checks found problems, or a bundle could not be loaded,
+       so it was not run
   3    a test failed
   64   bad usage, or Python could not start
   130  a second Ctrl+C gave up waiting for it to stop
@@ -2545,17 +2801,24 @@ function parseArgs2(argv) {
 }
 function isFile(at) {
   try {
-    return !fs8.statSync(at).isDirectory();
+    return !fs9.statSync(at).isDirectory();
   } catch {
     return false;
   }
 }
+var SUBCOMMANDS = {
+  examplar: runExamplar,
+  bundle: runBundle
+};
 async function main(argv) {
-  const at = subcommandIndex(argv, "examplar", OPTIONS);
-  if (at !== -1) {
+  for (const [name, run] of Object.entries(SUBCOMMANDS)) {
+    const at = subcommandIndex(argv, name, OPTIONS);
+    if (at === -1) {
+      continue;
+    }
     const leading = parseCommandLine(argv.slice(0, at), LEADING_OPTIONS);
     if ("error" in leading) {
-      process.stderr.write(`pll: ${leading.error} before examplar
+      process.stderr.write(`pll: ${leading.error} before ${name}
 ${USAGE_HINT}
 `);
       return EXIT.usage;
@@ -2567,7 +2830,7 @@ ${USAGE_HINT}
     const runtime2 = createCliRuntime();
     sayPackageNotes(runtime2, view2);
     try {
-      return await runExamplar(runtime2, view2, argv.slice(at + 1));
+      return await run(runtime2, view2, argv.slice(at + 1));
     } catch (err) {
       view2.problem(`pll: ${errorText(err)}`);
       return EXIT.usage;
@@ -2581,7 +2844,7 @@ ${USAGE_HINT}
     return EXIT.ok;
   }
   if (args.version) {
-    process.stdout.write("0.8.1\n");
+    process.stdout.write("0.9.1\n");
     return EXIT.ok;
   }
   if (args.error !== void 0) {
@@ -2621,7 +2884,7 @@ ${USAGE_HINT}
   process.stderr.on("error", onBrokenPipe);
   try {
     return await runFile(runtime, view, {
-      file: path8.resolve(args.file),
+      file: path9.resolve(args.file),
       runTests: args.runTests,
       stopRequested: () => interrupted
     });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pll-python",
-  "version": "0.8.1",
+  "version": "0.9.1",
   "description": "Run Python with PLL's language levels from the command line: level checks, in-file tests, friendly errors and the built-in image and table libraries, all on Pyodide. No Python install needed.",
   "license": "MIT",
   "repository": {