pll-python 0.1.0

package/cli.cjs

@@ -0,0 +1,1711 @@
+#!/usr/bin/env node
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+
+// src/cli/main.ts
+var path6 = __toESM(require("node:path"));
+
+// src/cli/runtime.ts
+var path2 = __toESM(require("node:path"));
+
+// src/desktop/pyodideRuntime.ts
+var fs = __toESM(require("node:fs"));
+var path = __toESM(require("node:path"));
+var import_node_worker_threads = require("node:worker_threads");
+
+// src/common/deliverResult.ts
+function deliverRunResult(result, onEvent, fileName) {
+  if (result.displays) {
+    for (const display of result.displays) {
+      deliverDisplay(display, onEvent, fileName);
+    }
+  }
+  if (result.result_repr !== null && result.result_repr !== void 0) {
+    onEvent({ kind: "result", repr: result.result_repr });
+  }
+  if (!result.ok && result.error_type) {
+    onEvent({
+      kind: "error",
+      errorType: result.error_type,
+      message: result.error_message ?? "",
+      traceback: result.traceback ?? "",
+      lineNumber: result.line_number,
+      column: result.column,
+      fileName
+    });
+  }
+  onEvent({ kind: "done" });
+}
+function deliverDisplay(display, onEvent, fileName) {
+  switch (display.type) {
+    case "stdout":
+      onEvent({ kind: "stdout", text: display.text });
+      break;
+    case "stderr":
+      onEvent({ kind: "stderr", text: display.text });
+      break;
+    case "image":
+      onEvent({
+        kind: "image",
+        svg: display.data,
+        width: display.width,
+        height: display.height,
+        source: fileName
+      });
+      break;
+    case "reactor":
+      onEvent({
+        kind: "reactor",
+        id: display.id,
+        title: display.title,
+        tickRate: display.tick_rate,
+        ticking: display.ticking,
+        wantsKeys: display.wants_keys,
+        wantsMouse: display.wants_mouse,
+        register: display.register,
+        frame: display.frame,
+        index: display.index,
+        length: display.length,
+        atEnd: display.at_end,
+        stopped: display.stopped,
+        valueRepr: display.value_repr
+      });
+      break;
+    case "table":
+      onEvent({
+        kind: "table",
+        columns: display.columns,
+        rows: display.rows,
+        rowCount: display.row_count,
+        shownCount: display.shown_count,
+        truncated: display.truncated,
+        source: fileName
+      });
+      break;
+  }
+}
+function asPlain(value) {
+  if (value instanceof Map) {
+    const obj = {};
+    for (const [k, v] of value.entries()) {
+      obj[String(k)] = asPlain(v);
+    }
+    return obj;
+  }
+  if (Array.isArray(value)) {
+    return value.map(asPlain);
+  }
+  return value;
+}
+function adaptTestCase(raw) {
+  const row = asPlain(raw) ?? {};
+  const line = row.line_number;
+  return {
+    name: String(row.name ?? ""),
+    outcome: String(row.outcome ?? "failed"),
+    lineNumber: typeof line === "number" ? line : null,
+    message: row.message == null ? null : String(row.message),
+    stdout: row.stdout == null ? null : String(row.stdout)
+  };
+}
+function deliverTestResult(result, onEvent, fileName) {
+  if (result.internal_error && result.error_type) {
+    onEvent({
+      kind: "error",
+      errorType: result.error_type,
+      message: result.error_message ?? "",
+      traceback: result.traceback ?? "",
+      lineNumber: result.line_number,
+      column: result.column,
+      fileName
+    });
+    onEvent({ kind: "done" });
+    return;
+  }
+  const tests = Array.isArray(result.tests) ? result.tests.map(adaptTestCase) : [];
+  onEvent({
+    kind: "testReport",
+    fileName,
+    passed: result.passed ?? 0,
+    failed: result.failed ?? 0,
+    skipped: result.skipped ?? 0,
+    errors: result.errors ?? 0,
+    tests
+  });
+  onEvent({ kind: "done" });
+}
+
+// src/common/interruptBuffer.ts
+var INTERRUPT_SAB_BYTES = 1;
+var INTERRUPT_SIGINT = 2;
+function tryCreateInterruptBuffer() {
+  try {
+    return new SharedArrayBuffer(INTERRUPT_SAB_BYTES);
+  } catch {
+    return null;
+  }
+}
+function signalInterrupt(sab) {
+  Atomics.store(new Uint8Array(sab), 0, INTERRUPT_SIGINT);
+}
+
+// src/common/stdinBuffer.ts
+var STDIN_SAB_BYTES = 64 * 1024;
+var STDIN_STATE_INDEX = 0;
+var STDIN_LENGTH_INDEX = 1;
+var STDIN_PAYLOAD_OFFSET = 8;
+var STDIN_STATE_LINE = 1;
+var STDIN_STATE_EOF = 2;
+function tryCreateStdinBuffer() {
+  try {
+    return new SharedArrayBuffer(STDIN_SAB_BYTES);
+  } catch {
+    return null;
+  }
+}
+function writeStdinLine(sab, line) {
+  const state = new Int32Array(sab);
+  if (line === null) {
+    Atomics.store(state, STDIN_STATE_INDEX, STDIN_STATE_EOF);
+    Atomics.notify(state, STDIN_STATE_INDEX);
+    return;
+  }
+  const encoded = new TextEncoder().encode(line);
+  const max = sab.byteLength - STDIN_PAYLOAD_OFFSET;
+  const n = Math.min(encoded.length, max);
+  const bytes = new Uint8Array(sab, STDIN_PAYLOAD_OFFSET);
+  bytes.set(encoded.subarray(0, n));
+  Atomics.store(state, STDIN_LENGTH_INDEX, n);
+  Atomics.store(state, STDIN_STATE_INDEX, STDIN_STATE_LINE);
+  Atomics.notify(state, STDIN_STATE_INDEX);
+}
+
+// src/common/workerRuntime.ts
+var WorkerPythonRuntime = class {
+  worker = null;
+  nextId = 1;
+  pending = /* @__PURE__ */ new Map();
+  initPromise = null;
+  stdinBuffer = null;
+  interruptBuffer = null;
+  stdinHandler = null;
+  /** Event sink for the in-flight runFile, so live displays can stream. */
+  live = null;
+  async initialize() {
+    if (!this.initPromise) {
+      this.initPromise = this.doInitialize();
+    }
+    await this.initPromise;
+  }
+  async doInitialize() {
+    const indexUrl = this.resolveIndexUrl();
+    this.worker = this.spawn({
+      onMessage: (msg) => this.handleMessage(msg),
+      onError: (err) => this.rejectAllPending(err)
+    });
+    this.stdinBuffer = tryCreateStdinBuffer();
+    this.interruptBuffer = tryCreateInterruptBuffer();
+    await this.request(
+      {
+        type: "init",
+        indexUrl,
+        ...this.stdinBuffer ? { stdinBuffer: this.stdinBuffer } : {},
+        ...this.interruptBuffer ? { interruptBuffer: this.interruptBuffer } : {}
+      },
+      "ready"
+    );
+  }
+  async runFile(request, onEvent) {
+    await this.initialize();
+    this.live = { onEvent, fileName: request.fileName };
+    try {
+      const { result } = await this.request({ type: "runFile", ...request }, "result");
+      deliverRunResult(result, onEvent, request.fileName);
+    } finally {
+      this.live = null;
+    }
+  }
+  async replEval(request, onEvent) {
+    await this.initialize();
+    const { result } = await this.request({ type: "replEval", ...request }, "result");
+    deliverRunResult(result, onEvent, "<repl>");
+  }
+  async checkReplComplete(code) {
+    await this.initialize();
+    const { result } = await this.request({ type: "checkSyntax", code }, "syntax");
+    return {
+      status: result.status,
+      errorType: result.error_type,
+      message: result.message,
+      lineNumber: result.lineno,
+      offset: result.offset
+    };
+  }
+  async hasTests(code) {
+    await this.initialize();
+    const { result } = await this.request({ type: "hasTests", code }, "hasTests");
+    return result;
+  }
+  async ensurePackages(code) {
+    await this.initialize();
+    await this.request({ type: "loadPackages", code }, "packagesReady");
+  }
+  async ensurePytest() {
+    await this.initialize();
+    await this.request({ type: "loadPytest" }, "pytestReady");
+  }
+  async runTests(request, onEvent) {
+    await this.initialize();
+    const { result } = await this.request(
+      {
+        type: "runTests",
+        code: request.code,
+        fileName: request.fileName,
+        level: request.level
+      },
+      "testResult"
+    );
+    deliverTestResult(result, onEvent, request.fileName);
+  }
+  async staticAnalyze(request) {
+    await this.initialize();
+    const { result } = await this.request({ type: "staticAnalyze", ...request }, "static");
+    return result ?? [];
+  }
+  async mountWorkspaceFiles(files) {
+    await this.initialize();
+    await this.request({ type: "mountWorkspace", files }, "workspaceReady");
+  }
+  async collectWorkspaceFiles() {
+    await this.initialize();
+    const { files } = await this.request({ type: "collectWorkspace" }, "workspaceFiles");
+    return files;
+  }
+  async reactorStep(reactorId, event) {
+    await this.initialize();
+    const { result } = await this.request(
+      { type: "reactorStep", reactorId, event },
+      "reactorFrame"
+    );
+    return result;
+  }
+  async reactorSeek(reactorId, index) {
+    await this.initialize();
+    const { result } = await this.request(
+      { type: "reactorSeek", reactorId, index },
+      "reactorFrame"
+    );
+    return result;
+  }
+  async reactorDispose(reactorId) {
+    await this.initialize();
+    await this.request({ type: "reactorDispose", reactorId }, "reactorDisposed");
+  }
+  interrupt() {
+    if (!this.interruptBuffer) {
+      return false;
+    }
+    signalInterrupt(this.interruptBuffer);
+    return true;
+  }
+  setStdinHandler(handler) {
+    this.stdinHandler = handler;
+  }
+  dispose() {
+    this.worker?.terminate();
+    this.worker = null;
+    this.initPromise = null;
+    this.stdinBuffer = null;
+    this.interruptBuffer = null;
+    this.live = null;
+    this.rejectAllPending(new Error("Runtime disposed"));
+  }
+  /** Send `msg` and resolve with the reply, asserting it is of type `expected`. */
+  async request(msg, expected) {
+    const worker = this.worker;
+    if (!worker) {
+      throw new Error("Worker not initialized");
+    }
+    const id = this.nextId++;
+    const reply = await new Promise((resolve3, reject) => {
+      this.pending.set(id, { resolve: resolve3, reject });
+      worker.post({ id, ...msg });
+    });
+    if (reply.type !== expected) {
+      throw new Error(`Pyodide worker replied "${reply.type}", expected "${expected}"`);
+    }
+    return reply;
+  }
+  handleMessage(msg) {
+    if (msg.type === "display") {
+      if (this.live) {
+        deliverDisplay(msg.payload, this.live.onEvent, this.live.fileName);
+      }
+      return;
+    }
+    if (msg.type === "stdinRequest") {
+      void this.handleStdinRequest();
+      return;
+    }
+    const pending = this.pending.get(msg.id);
+    if (!pending) {
+      return;
+    }
+    this.pending.delete(msg.id);
+    if (msg.type === "error") {
+      pending.reject(new Error(msg.message));
+    } else {
+      pending.resolve(msg);
+    }
+  }
+  rejectAllPending(err) {
+    for (const pending of this.pending.values()) {
+      pending.reject(err);
+    }
+    this.pending.clear();
+  }
+  async handleStdinRequest() {
+    let line = null;
+    try {
+      line = this.stdinHandler ? await this.stdinHandler() : null;
+    } catch {
+      line = null;
+    }
+    if (this.stdinBuffer) {
+      writeStdinLine(this.stdinBuffer, line);
+    }
+  }
+};
+
+// src/desktop/pyodideRuntime.ts
+var DesktopPyodideRuntime = class extends WorkerPythonRuntime {
+  constructor(paths) {
+    super();
+    this.paths = paths;
+  }
+  paths;
+  resolveIndexUrl() {
+    const found = this.paths.indexUrlCandidates.find(
+      (dir) => fs.existsSync(path.join(dir, "pyodide.asm.wasm"))
+    );
+    if (!found) {
+      throw new Error(this.paths.missingAssetsHint);
+    }
+    return found;
+  }
+  spawn(handlers) {
+    const worker = new import_node_worker_threads.Worker(this.paths.workerPath);
+    worker.on("message", (msg) => handlers.onMessage(msg));
+    worker.on(
+      "error",
+      (err) => handlers.onError(err instanceof Error ? err : new Error(String(err)))
+    );
+    return {
+      post: (msg) => worker.postMessage(msg),
+      terminate: () => void worker.terminate()
+    };
+  }
+};
+
+// src/cli/runtime.ts
+function createCliRuntime() {
+  return new DesktopPyodideRuntime({
+    // `pyodide` is external in the bundle, so this resolves at run time
+    // from the installed package rather than being inlined.
+    indexUrlCandidates: [path2.dirname(require.resolve("pyodide"))],
+    workerPath: path2.join(__dirname, "worker.cjs"),
+    missingAssetsHint: "Could not find Pyodide's assets. Reinstall pll-python so its `pyodide` dependency is present."
+  });
+}
+
+// src/cli/run.ts
+var fs3 = __toESM(require("node:fs/promises"));
+var path4 = __toESM(require("node:path"));
+
+// src/common/analyzers/static/shadowingExplainer.ts
+function outerScopeNoun(kind) {
+  switch (kind) {
+    case "module":
+      return "the file";
+    case "function":
+    case "lambda":
+      return "an enclosing function";
+    case "class":
+      return "an enclosing class";
+    case "comprehension":
+      return "an enclosing comprehension";
+    default:
+      return "an outer scope";
+  }
+}
+function explainShadowing(raw, level, fileName) {
+  const name = raw.name_token ?? "this name";
+  const outerLine = raw.outer_line_number ?? null;
+  const outerNoun = outerScopeNoun(raw.outer_scope_kind);
+  const knownOuterLine = outerLine !== null && outerLine > 0;
+  const outerHint = knownOuterLine ? ` (first defined on line ${outerLine}, in ${outerNoun})` : ` in ${outerNoun}`;
+  return {
+    id: "shadowing",
+    errorType: "Shadowing",
+    message: raw.message,
+    headline: `\`${name}\` is already defined${outerHint}.`,
+    howToFix: [
+      `Rename the inner \`${name}\` to something distinct (e.g. \`${name}_inner\`, \`local_${name}\`, or whatever describes its role).`,
+      `Or, if you want to use the outer \`${name}\`, just read it directly without making a new variable.`
+    ],
+    fileName,
+    lineNumber: raw.line_number,
+    column: raw.column,
+    nameToken: raw.name_token,
+    severity: "error",
+    raw: JSON.stringify(raw),
+    origin: "static",
+    level
+  };
+}
+function explainShadowingBuiltin(raw, level, fileName) {
+  const name = raw.name_token ?? "this name";
+  const headline = `\`${name}\` is the name of a Python built-in.`;
+  return {
+    id: "shadowing-builtin",
+    errorType: "Shadowing",
+    message: raw.message,
+    headline,
+    howToFix: [
+      `Pick a different name. Common patterns: \`my_${name}\`, \`${name}_value\`, \`${name}s\` (plural), or a more specific noun describing what this value represents.`
+    ],
+    fileName,
+    lineNumber: raw.line_number,
+    column: raw.column,
+    nameToken: raw.name_token,
+    severity: "error",
+    raw: JSON.stringify(raw),
+    origin: "static",
+    level
+  };
+}
+
+// src/common/analyzers/static/reassignmentExplainer.ts
+function explainReassignment(raw, level, fileName) {
+  const name = raw.name_token ?? "this name";
+  const firstLine = raw.first_line_number ?? null;
+  const firstLineHint = firstLine !== null && firstLine > 0 ? ` (first assigned on line ${firstLine})` : "";
+  return {
+    id: "reassignment",
+    errorType: "Reassignment",
+    message: raw.message,
+    headline: `\`${name}\` is already assigned${firstLineHint}.`,
+    howToFix: level === "intermediate" ? [
+      `If you want a different value, give it a different name (e.g. \`${name}_doubled\`, \`new_${name}\`, \`${name}2\`).`,
+      `If you're trying to update a value (\`x = x + 1\`, accumulators, running totals), wrap the work in a function and rebind \`${name}\` from the function's return value: \`${name} = compute_${name}(...)\`.`
+    ] : [
+      `If you want a different value, give it a different name (e.g. \`${name}_doubled\`, \`new_${name}\`, \`${name}2\`).`,
+      `If you're trying to update a value (\`x = x + 1\`, accumulators, running totals), use a built-in like \`sum(...)\`, \`max(...)\`, or a small helper function that returns the new value instead.`
+    ],
+    fileName,
+    lineNumber: raw.line_number,
+    column: raw.column,
+    nameToken: raw.name_token,
+    severity: "error",
+    raw: JSON.stringify(raw),
+    origin: "static",
+    level
+  };
+}
+
+// src/common/analyzers/static/disallowedKeywordExplainer.ts
+function explainDisallowedKeyword(raw, level, fileName) {
+  const keyword = raw.keyword === "nonlocal" ? "nonlocal" : "global";
+  const names = Array.isArray(raw.names) ? raw.names : [];
+  const formattedNames = names.map((n) => `\`${n}\``).join(", ");
+  const namesPhrase = formattedNames.length > 0 ? ` ${formattedNames}` : "";
+  const headline = `\`${keyword}\` is not allowed at the ${level} level.`;
+  const howToFix = [];
+  if (keyword === "global") {
+    howToFix.push(
+      `Pass${namesPhrase || " the value"} into this function as an argument instead of declaring it \`global\`.`,
+      `If the function needs to *change* a value, return the new value and let the caller decide what to do with it (e.g. \`x = update(x)\`).`
+    );
+  } else {
+    howToFix.push(
+      `Return${namesPhrase || " the new value"} from this inner function and have the outer function rebind it explicitly (e.g. \`x = inner(x)\`).`,
+      `If the inner function only needs to *read* the outer name, just use it directly - you don't need \`nonlocal\` for that.`
+    );
+  }
+  return {
+    id: "disallowed-keyword",
+    errorType: "DisallowedKeyword",
+    message: raw.message,
+    headline,
+    howToFix,
+    fileName,
+    lineNumber: raw.line_number,
+    column: raw.column,
+    nameToken: raw.name_token,
+    severity: "error",
+    raw: JSON.stringify(raw),
+    origin: "static",
+    level
+  };
+}
+
+// src/common/analyzers/static/registry.ts
+var explainers = {
+  shadowing: explainShadowing,
+  "shadowing-builtin": explainShadowingBuiltin,
+  reassignment: explainReassignment,
+  "disallowed-keyword": explainDisallowedKeyword
+};
+function fallbackExplainer(raw, level, fileName) {
+  return {
+    id: raw.id,
+    errorType: raw.error_type || "StaticError",
+    message: raw.message,
+    headline: raw.message,
+    howToFix: [],
+    fileName,
+    lineNumber: raw.line_number,
+    column: raw.column,
+    nameToken: raw.name_token,
+    severity: "error",
+    raw: JSON.stringify(raw),
+    origin: "static",
+    level
+  };
+}
+function enrichStaticFindings(rawFindings, level, fileName) {
+  return rawFindings.map((raw) => {
+    const explainer = explainers[raw.id] ?? fallbackExplainer;
+    return explainer(raw, level, fileName);
+  });
+}
+
+// src/common/errors/pythonErrorParser.ts
+var NON_USER_FRAME = [
+  "<exec>",
+  "/pll_vendor",
+  "site-packages",
+  "/lib/python",
+  "_pytest",
+  "pluggy"
+];
+function userTracebackFrames(traceback) {
+  const frames = [];
+  for (const raw of traceback.split(/\r?\n/)) {
+    const m = raw.match(/^\s*File "([^"]+)", line (\d+)(?:, in (\S+))?/);
+    if (!m) continue;
+    const fileName = m[1];
+    if (NON_USER_FRAME.some((token) => fileName.includes(token))) continue;
+    frames.push({
+      fileName,
+      line: parseInt(m[2], 10),
+      functionName: m[3] && m[3] !== "<module>" ? m[3] : null
+    });
+  }
+  return frames;
+}
+function parsePythonError(rawTraceback) {
+  const traceback = rawTraceback.trimEnd();
+  const lines = traceback.split(/\r?\n/);
+  let errorType = "Error";
+  let message = traceback;
+  for (let i = lines.length - 1; i >= 0; i--) {
+    const line = lines[i];
+    const m = line.match(/^([A-Za-z_][A-Za-z0-9_.]*):\s?(.*)$/);
+    if (m && !line.startsWith(" ")) {
+      errorType = m[1];
+      message = m[2];
+      break;
+    }
+    if (line.match(/^[A-Za-z_][A-Za-z0-9_.]*$/) && !line.startsWith(" ")) {
+      errorType = line;
+      message = "";
+      break;
+    }
+  }
+  let fileName = null;
+  let lineNumber = null;
+  for (let i = lines.length - 1; i >= 0; i--) {
+    const line = lines[i];
+    const m = line.match(/^\s*File\s+"([^"]+)",\s+line\s+(\d+)/);
+    if (m) {
+      fileName = m[1];
+      lineNumber = parseInt(m[2], 10);
+      break;
+    }
+  }
+  let column = null;
+  if (lineNumber !== null) {
+    for (let i = 0; i < lines.length - 1; i++) {
+      if (/^\s*\^+\s*$/.test(lines[i + 1] ?? "")) {
+        const caretLine = lines[i + 1];
+        const caretIdx = caretLine.indexOf("^");
+        if (caretIdx >= 0) {
+          column = caretIdx;
+        }
+      }
+    }
+  }
+  let nameToken = null;
+  if (errorType === "NameError") {
+    const nm = message.match(/name '([^']+)' is not defined/);
+    if (nm) {
+      nameToken = nm[1];
+    }
+  }
+  return {
+    errorType,
+    message,
+    traceback,
+    fileName,
+    lineNumber,
+    column,
+    nameToken
+  };
+}
+
+// src/common/errors/nameErrorExplainer.ts
+function explainNameError(parsed) {
+  const name = parsed.nameToken ?? "this name";
+  const didYouMean = extractDidYouMean(parsed.message);
+  const headline = `Python doesn't know what \`${name}\` means.`;
+  const howToFix = [
+    `Check the spelling of \`${name}\` (Python is case-sensitive).`,
+    `Make sure \`${name}\` is defined before this line runs.`,
+    `If \`${name}\` should be text, put it in quotes: \`"${name}"\`.`
+  ];
+  if (didYouMean.length > 0) {
+    howToFix.unshift(
+      `Python suggested: ${didYouMean.map((s) => "`" + s + "`").join(", ")} - try one of those.`
+    );
+  }
+  return { headline, howToFix };
+}
+function extractDidYouMean(message) {
+  const m = message.match(/Did you mean:\s*([^?]+)\??/i);
+  if (!m) {
+    return [];
+  }
+  return m[1].split(/,|\bor\b/).map((s) => s.trim().replace(/^['"`]|['"`]$/g, "")).filter((s) => s.length > 0);
+}
+
+// src/common/analyzers/nameErrorAnalyzer.ts
+var nameErrorAnalyzer = {
+  handles: ["NameError"],
+  analyze(input) {
+    const { parsedError, fileName, level } = input;
+    if (parsedError.errorType !== "NameError") {
+      return null;
+    }
+    const explanation = explainNameError(parsedError);
+    return {
+      id: "name-error",
+      errorType: "NameError",
+      message: parsedError.message,
+      headline: explanation.headline,
+      howToFix: explanation.howToFix,
+      fileName,
+      lineNumber: parsedError.lineNumber,
+      column: parsedError.column,
+      nameToken: parsedError.nameToken,
+      severity: "error",
+      raw: parsedError.traceback,
+      origin: "runtime",
+      level
+    };
+  }
+};
+
+// src/common/level.ts
+var DEFAULT_LEVEL = "raw";
+var HEADER_RE = /^#\s*level\s+([a-z]+)\s*$/;
+var LEVEL_NAMES = [
+  "raw",
+  "beginner",
+  "intermediate",
+  "advanced"
+];
+function parseLevel(source) {
+  const lines = source.split(/\r?\n/);
+  for (const raw of lines) {
+    const line = raw.trim();
+    if (line.length === 0) {
+      continue;
+    }
+    const match = HEADER_RE.exec(line);
+    if (!match) {
+      return DEFAULT_LEVEL;
+    }
+    const name = match[1];
+    for (const level of LEVEL_NAMES) {
+      if (name === level) return level;
+    }
+    return DEFAULT_LEVEL;
+  }
+  return DEFAULT_LEVEL;
+}
+function levelRejectsBoolAsNumber(level) {
+  return level === "beginner" || level === "intermediate";
+}
+function levelHasStaticChecks(level) {
+  return level === "beginner" || level === "intermediate";
+}
+
+// src/common/errors/typeCheckExplainer.ts
+var FRIENDLY_TYPES = {
+  int: "a whole number",
+  float: "a number",
+  complex: "a complex number",
+  str: "a string",
+  bool: "`True` or `False`",
+  bytes: "bytes",
+  list: "a list",
+  dict: "a dictionary",
+  set: "a set",
+  tuple: "a tuple",
+  None: "`None`",
+  NoneType: "`None`"
+};
+function cleanTypeName(type) {
+  return type.startsWith("__main__.") ? type.slice("__main__.".length) : type;
+}
+function describeType(type) {
+  const name = cleanTypeName(type);
+  if (name === "None" || name === "NoneType") return "`None`";
+  const friendly = FRIENDLY_TYPES[name];
+  return friendly ? `${friendly} (\`${name}\`)` : `\`${name}\``;
+}
+function describeTypes(types) {
+  const described = types.map(describeType);
+  if (described.length === 0) return "a different type";
+  if (described.length === 1) return described[0];
+  return `${described.slice(0, -1).join(", ")} or ${described[described.length - 1]}`;
+}
+function boolAsNumberNote(expected, actual, level) {
+  if (actual !== "bool" || expected.length === 0) return null;
+  if (!expected.some((type) => type === "int" || type === "float")) return null;
+  if (level !== void 0 && !levelRejectsBoolAsNumber(level)) return null;
+  return "At `#level beginner` and `#level intermediate`, `True` and `False` are not accepted as numbers, even though Python counts them as `1` and `0`.";
+}
+function conversionFor(expected, actual) {
+  if (expected.length !== 1 || actual === null) return null;
+  const to = expected[0];
+  const numeric = actual === "int" || actual === "float" || actual === "bool";
+  if (to === "int" && (actual === "str" || actual === "float")) return "int";
+  if (to === "float" && actual === "str") return "float";
+  if (to === "str" && numeric) return "str";
+  return null;
+}
+var ELEMENT_RE = /^(item \d+|key .+|value of key .+|\[.+\]) of (.+)$/;
+function membersPhrase(element) {
+  if (element.startsWith("the value for key")) return "every value in";
+  if (element.startsWith("key ")) return "every key in";
+  return "every item in";
+}
+function describeElement(element) {
+  if (element.startsWith("value of key ")) {
+    return `the value for key ${element.slice("value of key ".length)}`;
+  }
+  if (element.startsWith("[")) return "one of the values";
+  return element;
+}
+function parseTypeCheckMessage(message) {
+  const unknown = {
+    kind: "unknown",
+    name: null,
+    element: null,
+    actual: null,
+    expected: []
+  };
+  const lines = message.split(/\r?\n/);
+  const first = lines[0].trim();
+  let expected = [];
+  let subject = null;
+  const unionAt = first.indexOf(" did not match any element in the union:");
+  if (unionAt >= 0) {
+    subject = first.slice(0, unionAt);
+    for (const raw of lines.slice(1)) {
+      const m = raw.match(/^\s*([A-Za-z_][A-Za-z0-9_.\[\], ]*):/);
+      if (m) expected.push(m[1].trim());
+    }
+  } else {
+    const predicates = [
+      [/^(.*) is not an instance of (.+)$/, (m) => [m[2]]],
+      [/^(.*) is neither float or int$/, () => ["float"]],
+      [/^(.*) is not None$/, () => ["None"]],
+      [/^(.*) is not a ([A-Za-z_][A-Za-z0-9_]*)$/, (m) => [m[2]]]
+    ];
+    for (const [re, pick] of predicates) {
+      const m = first.match(re);
+      if (m) {
+        subject = m[1];
+        expected = pick(m);
+        break;
+      }
+    }
+  }
+  if (subject === null) return unknown;
+  let actual = null;
+  const withActual = subject.match(/^(.*) \(([^()]*)\)$/);
+  if (withActual) {
+    subject = withActual[1];
+    actual = withActual[2];
+  }
+  let element = null;
+  const elementMatch = subject.match(ELEMENT_RE);
+  if (elementMatch) {
+    element = describeElement(elementMatch[1]);
+    subject = elementMatch[2];
+  }
+  if (subject === "the return value") {
+    return { kind: "return", name: null, element, actual, expected };
+  }
+  const argument = subject.match(/^argument "(.+)"$/);
+  if (argument) {
+    return { kind: "argument", name: argument[1], element, actual, expected };
+  }
+  const assigned = subject.match(/^value assigned to (.+)$/);
+  if (assigned) {
+    return { kind: "variable", name: assigned[1], element, actual, expected };
+  }
+  return { ...unknown, element, actual, expected };
+}
+function explainTypeCheckError(message, functionName, level) {
+  const parsed = parseTypeCheckMessage(message);
+  const wanted = describeTypes(parsed.expected);
+  const owner = functionName ? `\`${functionName}\`` : "this function";
+  const named = parsed.name ? `\`${parsed.name}\`` : "a value";
+  const convert = conversionFor(parsed.expected, parsed.actual);
+  const boolNote = boolAsNumberNote(parsed.expected, parsed.actual, level);
+  const annotation = parsed.expected.length === 1 ? cleanTypeName(parsed.expected[0]) : null;
+  if (parsed.kind === "argument") {
+    if (parsed.element) {
+      return {
+        headline: `${owner} expects ${membersPhrase(parsed.element)} ${named} to be ${wanted}, but ${parsed.element} is not.`,
+        howToFix: [
+          `Look at ${parsed.element} of the ${parsed.actual ?? "value"} you passed for ${named}.`,
+          "Every one has to match the annotation, not just the first."
+        ]
+      };
+    }
+    const got = parsed.actual ? `, but got ${describeType(parsed.actual)}` : "";
+    const howToFix = [`Check the value you passed for ${named} on this line.`];
+    if (boolNote) howToFix.push(boolNote);
+    if (convert) {
+      howToFix.push(`If it should be ${wanted}, convert it with \`${convert}(...)\`.`);
+    }
+    if (annotation && parsed.actual) {
+      howToFix.push(
+        `Or, if ${named} really should be ${describeType(parsed.actual)}, change its annotation in ${owner} from \`${annotation}\` to \`${cleanTypeName(parsed.actual)}\`.`
+      );
+    }
+    return {
+      headline: `${owner} expects ${named} to be ${wanted}${got}.`,
+      howToFix
+    };
+  }
+  if (parsed.kind === "return") {
+    if (parsed.actual === "None" || parsed.actual === "NoneType") {
+      return {
+        headline: `${owner} should return ${wanted}, but it finished without returning a value.`,
+        howToFix: [
+          "Make sure every path through the function reaches a `return`.",
+          "An `if` with no `else` falls off the end, and Python then returns `None`.",
+          `Or annotate the return type as \`None\` if ${owner} is not meant to return anything.`
+        ]
+      };
+    }
+    const got = parsed.actual ? describeType(parsed.actual) : "something else";
+    const howToFix = [];
+    const wantsNone = parsed.expected.length === 1 && /^(None|NoneType)$/.test(parsed.expected[0]);
+    if (wantsNone) {
+      howToFix.push("Use a bare `return`, or drop the `return` entirely.");
+    } else if (convert) {
+      howToFix.push(`Convert the returned value with \`${convert}(...)\`.`);
+    } else {
+      howToFix.push(`Return ${wanted} from this line.`);
+    }
+    if (boolNote) howToFix.push(boolNote);
+    if (annotation && parsed.actual) {
+      howToFix.push(
+        `Or change ${owner}'s return annotation from \`${annotation}\` to \`${cleanTypeName(parsed.actual)}\`.`
+      );
+    }
+    return {
+      headline: `${owner} says it returns ${wanted}, but this line returns ${got}.`,
+      howToFix
+    };
+  }
+  if (parsed.kind === "variable") {
+    if (parsed.element) {
+      return {
+        headline: `${named} is annotated so ${membersPhrase(parsed.element)} it is ${wanted}, but ${parsed.element} is not.`,
+        howToFix: [`Look at ${parsed.element} of the value assigned to ${named}.`]
+      };
+    }
+    const got = parsed.actual ? describeType(parsed.actual) : "a different type";
+    const howToFix = [`Assign ${wanted} to ${named}.`];
+    if (boolNote) howToFix.push(boolNote);
+    if (convert) {
+      howToFix.push(`You can convert the value with \`${convert}(...)\`.`);
+    }
+    if (annotation && parsed.actual) {
+      howToFix.push(
+        `Or change ${named}'s annotation from \`${annotation}\` to \`${cleanTypeName(parsed.actual)}\`.`
+      );
+    }
+    return {
+      headline: `${named} is annotated as ${wanted}, but ${got} was assigned here.`,
+      howToFix
+    };
+  }
+  return {
+    headline: "A value does not match the type annotation written for it.",
+    howToFix: [
+      message.split(/\r?\n/)[0].trim(),
+      "Either pass a value of the annotated type, or change the annotation."
+    ]
+  };
+}
+
+// src/common/analyzers/typeCheckAnalyzer.ts
+var HANDLED = ["TypeCheckError", "typeguard.TypeCheckError"];
+function messageWithDetail(traceback, fallback) {
+  const lines = traceback.split(/\r?\n/);
+  for (let i = lines.length - 1; i >= 0; i--) {
+    const line = lines[i];
+    const marker = line.indexOf("TypeCheckError:");
+    if (line.startsWith(" ") || marker < 0) continue;
+    const detail = [line.slice(marker + "TypeCheckError:".length).trim()];
+    for (let j = i + 1; j < lines.length; j++) {
+      if (lines[j].trim() === "") continue;
+      if (!lines[j].startsWith(" ")) break;
+      detail.push(lines[j]);
+    }
+    return detail.join("\n");
+  }
+  return fallback;
+}
+var typeCheckAnalyzer = {
+  handles: HANDLED,
+  analyze(input) {
+    const { parsedError, fileName, level } = input;
+    if (!HANDLED.includes(parsedError.errorType)) {
+      return null;
+    }
+    const message = messageWithDetail(parsedError.traceback, parsedError.message);
+    const parsed = parseTypeCheckMessage(message);
+    const frames = userTracebackFrames(parsedError.traceback);
+    const innermost = frames.length > 0 ? frames[frames.length - 1] : null;
+    const blamed = parsed.kind === "argument" && frames.length >= 2 ? frames[frames.length - 2] : innermost;
+    const explanation = explainTypeCheckError(
+      message,
+      innermost ? innermost.functionName : null,
+      level
+    );
+    return {
+      id: "type-check",
+      // Not a real Python exception name; "TypeCheckError" means nothing to
+      // a student, and "TypeError" would name a different Python error.
+      errorType: "TypeMismatch",
+      message,
+      headline: explanation.headline,
+      howToFix: explanation.howToFix,
+      fileName: blamed ? blamed.fileName : fileName,
+      lineNumber: blamed ? blamed.line : parsedError.lineNumber,
+      column: null,
+      nameToken: parsed.name,
+      severity: "error",
+      raw: parsedError.traceback,
+      origin: "runtime",
+      level
+    };
+  }
+};
+
+// src/common/analyzers/registry.ts
+var analyzers = [nameErrorAnalyzer, typeCheckAnalyzer];
+function findRuntimeFinding(source, fileName, level, parsedError) {
+  for (const analyzer of analyzers) {
+    if (!analyzer.handles.includes(parsedError.errorType)) {
+      continue;
+    }
+    const finding = analyzer.analyze({ source, fileName, level, parsedError });
+    if (finding) {
+      return finding;
+    }
+  }
+  return null;
+}
+
+// src/common/analyzers/runtimeFinding.ts
+function findingForErrorEvent(event, source, fileName, level) {
+  const traceback = event.traceback || `${event.errorType}: ${event.message}`;
+  const parsed = parsePythonError(traceback);
+  if (parsed.lineNumber === null && event.lineNumber !== null) {
+    parsed.lineNumber = event.lineNumber;
+  }
+  if (parsed.column === null && event.column !== null) {
+    parsed.column = event.column;
+  }
+  if (parsed.fileName === null && event.fileName) {
+    parsed.fileName = event.fileName;
+  }
+  return findRuntimeFinding(source, fileName, level, parsed);
+}
+
+// src/common/pyodideRunner.ts
+var ANY_IMPORT_RE = /(^|\n)[ \t]*(import|from)[ \t]+\S/;
+
+// src/cli/files.ts
+var fs2 = __toESM(require("node:fs/promises"));
+var path3 = __toESM(require("node:path"));
+
+// src/common/workspaceFilePolicy.ts
+var MAX_FILE_BYTES = 2 * 1024 * 1024;
+var MAX_TOTAL_BYTES = 8 * 1024 * 1024;
+var MAX_FILES = 50;
+var MOUNT_EXTENSIONS = /* @__PURE__ */ new Set([
+  ".csv",
+  ".txt",
+  ".tsv",
+  ".json",
+  ".md",
+  ".dat",
+  ".xml",
+  ".py"
+]);
+var WRITEBACK_EXTENSIONS = /* @__PURE__ */ new Set([
+  ".csv",
+  ".txt",
+  ".tsv",
+  ".json",
+  ".md",
+  ".dat",
+  ".xml"
+]);
+function extensionOf(name) {
+  const dot = name.lastIndexOf(".");
+  if (dot <= 0) {
+    return "";
+  }
+  return name.slice(dot).toLowerCase();
+}
+function isSafeBasename(name) {
+  if (!name || name === "." || name === "..") {
+    return false;
+  }
+  if (name.startsWith(".")) {
+    return false;
+  }
+  if (name.includes("/") || name.includes("\\") || name.includes("\0")) {
+    return false;
+  }
+  return true;
+}
+function isMountableName(name) {
+  return isSafeBasename(name) && MOUNT_EXTENSIONS.has(extensionOf(name));
+}
+function isWritebackName(name) {
+  return isSafeBasename(name) && WRITEBACK_EXTENSIONS.has(extensionOf(name));
+}
+function utf8ByteLength(text) {
+  return new TextEncoder().encode(text).byteLength;
+}
+function decodeMountContents(data) {
+  if (data.byteLength > MAX_FILE_BYTES) {
+    return void 0;
+  }
+  for (let i = 0; i < data.byteLength; i++) {
+    if (data[i] === 0) {
+      return void 0;
+    }
+  }
+  return new TextDecoder("utf-8").decode(data);
+}
+function selectMountableFiles(candidates) {
+  const selected = [];
+  let total = 0;
+  for (const candidate of candidates) {
+    if (selected.length >= MAX_FILES) {
+      break;
+    }
+    if (!isMountableName(candidate.name)) {
+      continue;
+    }
+    let text;
+    if (typeof candidate.contents === "string") {
+      if (utf8ByteLength(candidate.contents) > MAX_FILE_BYTES) {
+        continue;
+      }
+      if (candidate.contents.includes("\0")) {
+        continue;
+      }
+      text = candidate.contents;
+    } else {
+      const decoded = decodeMountContents(candidate.contents);
+      if (decoded === void 0) {
+        continue;
+      }
+      text = decoded;
+    }
+    const size = utf8ByteLength(text);
+    if (total + size > MAX_TOTAL_BYTES) {
+      continue;
+    }
+    selected.push({ name: candidate.name, contents: text });
+    total += size;
+  }
+  return selected;
+}
+function selectWritebackFiles(files) {
+  const selected = [];
+  let total = 0;
+  for (const file of files) {
+    if (selected.length >= MAX_FILES) {
+      break;
+    }
+    if (!isWritebackName(file.name)) {
+      continue;
+    }
+    const size = utf8ByteLength(file.contents);
+    if (size > MAX_FILE_BYTES || total + size > MAX_TOTAL_BYTES) {
+      continue;
+    }
+    if (file.contents.includes("\0")) {
+      continue;
+    }
+    selected.push(file);
+    total += size;
+  }
+  return selected;
+}
+
+// src/cli/files.ts
+async function collectSiblingFiles(scriptPath) {
+  const folder = path3.dirname(path3.resolve(scriptPath));
+  let entries;
+  try {
+    entries = await fs2.readdir(folder, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  const candidates = [];
+  for (const entry of entries) {
+    if (!entry.isFile() || !isMountableName(entry.name)) {
+      continue;
+    }
+    try {
+      candidates.push({ name: entry.name, contents: await fs2.readFile(path3.join(folder, entry.name)) });
+    } catch {
+    }
+  }
+  return selectMountableFiles(candidates);
+}
+async function writeBackSiblingFiles(scriptPath, files) {
+  const folder = path3.dirname(path3.resolve(scriptPath));
+  const written = [];
+  for (const file of selectWritebackFiles(files)) {
+    try {
+      await fs2.writeFile(path3.join(folder, file.name), file.contents, "utf8");
+      written.push(file.name);
+    } catch {
+    }
+  }
+  return written;
+}
+
+// src/cli/run.ts
+var EXIT = {
+  ok: 0,
+  /** The program raised. */
+  programError: 1,
+  /** Level checks found problems, so the file was not run. */
+  blocked: 2,
+  /** The program ran, but its in-file tests did not all pass. */
+  testsFailed: 3,
+  /** Bad usage, or PLL itself could not run. */
+  usage: 64
+};
+async function runFile(runtime, view, opts) {
+  const fileName = path4.basename(opts.file);
+  let source;
+  try {
+    source = await fs3.readFile(opts.file, "utf8");
+  } catch (err) {
+    view.problem(`Cannot read ${opts.file}: ${errText(err)}`);
+    return EXIT.usage;
+  }
+  const level = parseLevel(source);
+  view.note(`${fileName} [${level}]`);
+  if (levelHasStaticChecks(level)) {
+    const blocked = await staticChecks(runtime, view, source, fileName, level);
+    if (blocked) {
+      return EXIT.blocked;
+    }
+  }
+  await ensurePackages(runtime, view, source);
+  try {
+    await runtime.mountWorkspaceFiles(await collectSiblingFiles(opts.file));
+  } catch (err) {
+    view.note(`Could not load files next to this script (${errText(err)}).`);
+  }
+  const onEvent = (event) => {
+    if (event.kind === "error") {
+      const finding = findingForErrorEvent(event, source, fileName, level);
+      if (finding) {
+        view.runtimeFinding(finding);
+        return;
+      }
+    }
+    view.handle(event);
+  };
+  if (opts.runTests) {
+    await maybeRunTests(runtime, view, source, fileName, level, onEvent);
+  }
+  await runtime.runFile({ code: source, fileName, sessionKey: opts.file, level }, onEvent);
+  await writeBack(runtime, view, opts.file);
+  if (view.sawError) return EXIT.programError;
+  if (view.testFailures > 0) return EXIT.testsFailed;
+  return EXIT.ok;
+}
+async function staticChecks(runtime, view, source, fileName, level) {
+  let raw;
+  try {
+    raw = await runtime.staticAnalyze({ code: source, fileName, level });
+  } catch (err) {
+    view.note(`Static analysis failed (${errText(err)}); running anyway.`);
+    return false;
+  }
+  const findings = enrichStaticFindings(raw, level, fileName);
+  if (findings.length === 0) {
+    return false;
+  }
+  view.findings(findings);
+  view.problem(`Static analysis found ${findings.length} problem(s). File not run.`);
+  return true;
+}
+async function ensurePackages(runtime, view, source) {
+  if (!ANY_IMPORT_RE.test(source)) {
+    return;
+  }
+  try {
+    await runtime.ensurePackages(source);
+  } catch (err) {
+    const message = errText(err);
+    if (!/syntaxerror|invalid syntax/i.test(message)) {
+      view.note(`Could not load libraries (${message}). Continuing.`);
+    }
+  }
+}
+async function maybeRunTests(runtime, view, source, fileName, level, onEvent) {
+  try {
+    if (!await runtime.hasTests(source)) {
+      return;
+    }
+    await runtime.ensurePytest();
+  } catch (err) {
+    view.note(`Could not check for tests (${errText(err)}); skipping them.`);
+    return;
+  }
+  await runtime.runTests({ code: source, fileName, sessionKey: fileName, level }, onEvent);
+}
+async function writeBack(runtime, view, file) {
+  try {
+    const changed = await runtime.collectWorkspaceFiles();
+    if (changed.length === 0) {
+      return;
+    }
+    const written = await writeBackSiblingFiles(file, changed);
+    if (written.length > 0) {
+      view.note(`Saved ${written.join(", ")} next to ${path4.basename(file)}.`);
+    }
+  } catch (err) {
+    view.note(`Could not save files next to this script (${errText(err)}).`);
+  }
+}
+function errText(err) {
+  return err instanceof Error ? err.message : String(err);
+}
+
+// src/cli/stdin.ts
+var readline = __toESM(require("node:readline"));
+function createLineReader() {
+  let rl = null;
+  let closed = false;
+  const pending = [];
+  const buffered = [];
+  function ensure() {
+    if (rl) return rl;
+    rl = readline.createInterface({ input: process.stdin, terminal: false });
+    rl.on("line", (line) => {
+      const next = pending.shift();
+      if (next) next(line);
+      else buffered.push(line);
+    });
+    const finish = () => {
+      closed = true;
+      while (pending.length > 0) pending.shift()?.(null);
+    };
+    rl.on("close", finish);
+    process.stdin.on("end", finish);
+    return rl;
+  }
+  return {
+    read() {
+      if (buffered.length > 0) {
+        return Promise.resolve(buffered.shift() ?? null);
+      }
+      if (closed) {
+        return Promise.resolve(null);
+      }
+      ensure();
+      return new Promise((resolve3) => pending.push(resolve3));
+    },
+    close() {
+      closed = true;
+      rl?.close();
+      rl = null;
+    }
+  };
+}
+
+// src/cli/view.ts
+var fs4 = __toESM(require("node:fs"));
+var path5 = __toESM(require("node:path"));
+
+// src/common/analyzers/findingLocation.ts
+function findingLocation(finding) {
+  if (finding.lineNumber === null) {
+    return null;
+  }
+  if (finding.fileName === "<repl>" || finding.fileName === "<input>") {
+    return null;
+  }
+  const label = finding.column !== null ? `${finding.fileName}:${finding.lineNumber}:${finding.column + 1}` : `${finding.fileName}:${finding.lineNumber}`;
+  return {
+    fileName: finding.fileName,
+    line: finding.lineNumber,
+    column: finding.column,
+    label
+  };
+}
+
+// src/common/errorFormatter.ts
+function formatFriendlyError(finding) {
+  const lines = [];
+  lines.push(`${finding.errorType}: ${finding.headline}`);
+  const location = findingLocation(finding);
+  if (location) {
+    lines.push(`  at ${location.label}`);
+  }
+  if (finding.howToFix.length > 0) {
+    lines.push("");
+    lines.push("How to fix:");
+    for (const item of finding.howToFix) {
+      lines.push(`  - ${item}`);
+    }
+  }
+  return lines;
+}
+
+// src/cli/view.ts
+var ESC = String.fromCharCode(27);
+var CliView = class {
+  constructor(opts) {
+    this.opts = opts;
+  }
+  opts;
+  /** True once the program raised, so the exit code can reflect it. */
+  sawError = false;
+  /** Failing + erroring tests across all reports. */
+  testFailures = 0;
+  imageCount = 0;
+  paint(code, text) {
+    return this.opts.color ? `${ESC}[${code}m${text}${ESC}[0m` : text;
+  }
+  dim(text) {
+    return this.paint("2", text);
+  }
+  red(text) {
+    return this.paint("31", text);
+  }
+  green(text) {
+    return this.paint("32", text);
+  }
+  /** PLL's own commentary. Always stderr, silenced by --quiet. */
+  note(text) {
+    if (!this.opts.quiet) {
+      process.stderr.write(text + "\n");
+    }
+  }
+  /** Something the user must see even under --quiet. */
+  problem(text) {
+    process.stderr.write(text + "\n");
+  }
+  /** Static-analysis findings, in the same words the editor uses. */
+  findings(findings) {
+    for (const finding of findings) {
+      const lines = formatFriendlyError(finding);
+      this.problem(this.red(lines[0]));
+      for (const line of lines.slice(1)) {
+        this.problem(line);
+      }
+      this.problem("");
+    }
+  }
+  /** A friendly finding for a runtime error, in place of the traceback. */
+  runtimeFinding(finding) {
+    this.sawError = true;
+    const lines = formatFriendlyError(finding);
+    this.problem(this.red(lines[0]));
+    for (const line of lines.slice(1)) {
+      this.problem(line);
+    }
+  }
+  handle(event) {
+    switch (event.kind) {
+      case "stdout":
+        process.stdout.write(event.text);
+        break;
+      case "stderr":
+        process.stderr.write(event.text);
+        break;
+      case "result":
+        if (event.repr !== null && event.repr !== void 0) {
+          process.stdout.write(event.repr + "\n");
+        }
+        break;
+      case "image":
+        this.image(event.svg, event.width, event.height);
+        break;
+      case "table":
+        process.stdout.write(renderTable(event) + "\n");
+        break;
+      case "reactor": {
+        const which = event.title === "reactor" ? "reactor" : `reactor "${event.title}"`;
+        this.note(
+          this.dim(`[${which} needs the editor's interactions panel; not run here]`)
+        );
+        break;
+      }
+      case "testReport":
+        this.testReport(event);
+        break;
+      case "error": {
+        this.sawError = true;
+        const body = event.traceback || `${event.errorType}: ${event.message}`;
+        process.stderr.write(this.red(body.trimEnd()) + "\n");
+        break;
+      }
+      case "done":
+        break;
+    }
+  }
+  image(svg, width, height) {
+    this.imageCount += 1;
+    const dir = this.opts.saveImagesDir;
+    if (!dir) {
+      this.note(
+        this.dim(`[image ${width}x${height}; pass --save-images to write it out]`)
+      );
+      return;
+    }
+    const target = path5.join(dir, `image-${this.imageCount}.svg`);
+    try {
+      fs4.mkdirSync(dir, { recursive: true });
+      fs4.writeFileSync(target, svg, "utf8");
+      this.note(this.dim(`[image ${width}x${height} -> ${target}]`));
+    } catch (err) {
+      this.problem(`Could not write ${target}: ${errText2(err)}`);
+    }
+  }
+  testReport(event) {
+    const bad = event.failed + event.errors;
+    this.testFailures += bad;
+    const summary = `${event.passed} passed` + (event.failed ? `, ${event.failed} failed` : "") + (event.errors ? `, ${event.errors} errored` : "") + (event.skipped ? `, ${event.skipped} skipped` : "");
+    this.problem((bad === 0 ? this.green("tests: ") : this.red("tests: ")) + summary);
+    for (const test of event.tests) {
+      if (test.outcome === "passed") {
+        this.note(this.dim(`  ok   ${test.name}`));
+        continue;
+      }
+      const where = test.lineNumber === null ? "" : ` (line ${test.lineNumber})`;
+      this.problem(this.red(`  ${test.outcome.toUpperCase()} ${test.name}${where}`));
+      for (const line of (test.message ?? "").split("\n")) {
+        if (line.trim()) {
+          this.problem("        " + line);
+        }
+      }
+    }
+  }
+};
+function errText2(err) {
+  return err instanceof Error ? err.message : String(err);
+}
+function renderTable(table) {
+  const widths = table.columns.map(
+    (name, i) => Math.max(name.length, ...table.rows.map((row) => (row[i] ?? "").length), 0)
+  );
+  const line = (cells) => cells.map((cell, i) => cell.padEnd(widths[i])).join("  ").trimEnd();
+  const out = [
+    line(table.columns),
+    widths.map((w) => "-".repeat(w)).join("  ").trimEnd()
+  ];
+  for (const row of table.rows) {
+    out.push(line(table.columns.map((_, i) => row[i] ?? "")));
+  }
+  out.push(
+    table.truncated ? `(${table.shownCount} of ${table.rowCount} rows)` : `(${table.rowCount} row${table.rowCount === 1 ? "" : "s"})`
+  );
+  return out.join("\n");
+}
+
+// src/cli/main.ts
+var USAGE = `pll - run Python with PLL's language levels, outside the editor
+
+  pll <file.py> [options]
+
+The level comes from the file's own \`#level\` line, exactly as in the
+editor; there is deliberately no flag to override it, so a file behaves the
+same everywhere.
+
+Options
+  --no-tests           do not run the file's \`test_*\` functions first
+  --save-images <dir>  write pictures there as .svg (they cannot be drawn
+                       in a terminal); without this, each one prints a note
+  -q, --quiet          only the program's own output
+  --no-color           never use ANSI colour
+  -h, --help           this message
+  -v, --version        print the version
+
+The program's own stdout is the only thing on stdout, so it can be piped;
+everything PLL says about the run goes to stderr.
+
+Exit codes
+  0  ran, tests passed        2  level checks blocked it
+  1  the program raised       3  a test failed
+`;
+function parseArgs(argv) {
+  const args = {
+    runTests: true,
+    quiet: false,
+    // Colour only when stderr is a terminal, and never when NO_COLOR is set.
+    color: process.stderr.isTTY === true && !process.env.NO_COLOR,
+    help: false,
+    version: false
+  };
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === "--no-tests") args.runTests = false;
+    else if (arg === "-q" || arg === "--quiet") args.quiet = true;
+    else if (arg === "--no-color") args.color = false;
+    else if (arg === "-h" || arg === "--help") args.help = true;
+    else if (arg === "-v" || arg === "--version") args.version = true;
+    else if (arg === "--save-images") {
+      const dir = argv[++i];
+      if (dir === void 0) {
+        args.error = "--save-images needs a directory";
+        return args;
+      }
+      args.saveImagesDir = dir;
+    } else if (arg.startsWith("-")) {
+      args.error = `unknown option ${arg}`;
+      return args;
+    } else if (args.file === void 0) {
+      args.file = arg;
+    } else {
+      args.error = `unexpected extra argument ${arg}`;
+      return args;
+    }
+  }
+  if (!args.help && !args.version && args.file === void 0) {
+    args.error = "no file given";
+  }
+  if (args.file !== void 0 && !args.file.endsWith(".py")) {
+    args.error = `${args.file} is not a .py file`;
+  }
+  return args;
+}
+async function main(argv) {
+  const args = parseArgs(argv);
+  if (args.help) {
+    process.stdout.write(USAGE);
+    return EXIT.ok;
+  }
+  if (args.version) {
+    process.stdout.write("0.1.0\n");
+    return EXIT.ok;
+  }
+  if (args.error !== void 0) {
+    process.stderr.write(`pll: ${args.error}
+
+${USAGE}`);
+    return EXIT.usage;
+  }
+  const view = new CliView({
+    saveImagesDir: args.saveImagesDir,
+    quiet: args.quiet,
+    color: args.color
+  });
+  const runtime = createCliRuntime();
+  const reader = createLineReader();
+  runtime.setStdinHandler(() => reader.read());
+  let interrupted = false;
+  const onSigint = () => {
+    if (interrupted) {
+      process.stderr.write("\npll: giving up.\n");
+      process.exit(130);
+    }
+    interrupted = true;
+    if (!runtime.interrupt()) {
+      process.stderr.write("\npll: cannot interrupt; press Ctrl+C again to quit.\n");
+    }
+  };
+  process.on("SIGINT", onSigint);
+  try {
+    return await runFile(runtime, view, {
+      file: path6.resolve(args.file),
+      runTests: args.runTests
+    });
+  } catch (err) {
+    view.problem(`pll: ${err instanceof Error ? err.message : String(err)}`);
+    return EXIT.usage;
+  } finally {
+    process.off("SIGINT", onSigint);
+    reader.close();
+    runtime.dispose();
+  }
+}
+
+// src/cli/bin.ts
+main(process.argv.slice(2)).then(
+  (code) => process.exit(code),
+  (err) => {
+    process.stderr.write(`pll: ${err instanceof Error ? err.stack : String(err)}
+`);
+    process.exit(EXIT.usage);
+  }
+);
+//# sourceMappingURL=cli.cjs.map