beatrina 0.8.6

package/lib/engine-labels.js

@@ -0,0 +1,324 @@
+// engine-labels.js — the page's ONE answer to "what is this thing called?".
+//
+// For as long as there was one language the answer was a constant, so nothing
+// had to ask: the editor's accessible name was the literal "R code editor",
+// a figure's alt text was `R plot ${n}`, the AI chip said "⚡ R ready", and the
+// footer said "local R kernel". Beatrix runs engines (R today, Python next),
+// so every one of those became a question — and a question answered in a dozen
+// places is a dozen answers that drift. This module is the one answer.
+//
+// TWO HALVES, ON PURPOSE.
+//
+//   1. The NAME of an engine (`engineKey`, `engineLabel`, and the phrasings
+//      built on them). Pure, no kernel, no DOM — a chunk header's `engine`
+//      string in, a word out.
+//   2. What the ATTACHED KERNEL declared (`kernelLanguage`, `reportedEngines`,
+//      `kernelDisplay`). Also pure: it takes the ready frame's `info` object
+//      and returns a fact, so the page's language behaviour is testable
+//      without a socket.
+//
+// THE KERNEL DECLARES; THE PAGE NEVER GUESSES. `language` is a field on the
+// ready frame and on /health. A kernel built before the field existed sends
+// nothing, and an absent field means "r" — that is not a guess about an
+// unknown kernel, it is the only kernel that can be speaking this protocol
+// without saying so.
+//
+// R'S WORDING IS UNCHANGED FOR R, BYTE FOR BYTE. Every phrasing below produces
+// exactly the string the page produced before it existed when the engine is R.
+// That is the compatibility contract the existing suites assert, and it is
+// what makes this a rename of the SOURCE of a word rather than of the word.
+
+/** The engines the page knows how to name. Order is the options sheet's. */
+export const KNOWN_ENGINES = Object.freeze([
+  Object.freeze({ key: "r", label: "R" }),
+  Object.freeze({ key: "python", label: "Python" }),
+  Object.freeze({ key: "js", label: "JavaScript" }),
+  Object.freeze({ key: "bash", label: "Bash" }),
+  Object.freeze({ key: "sql", label: "SQL" }),
+]);
+
+/** What a chunk with no `engine` at all is, and what a silent kernel runs. */
+export const DEFAULT_ENGINE = "r";
+
+const BY_KEY = new Map(KNOWN_ENGINES.map((e) => [e.key, e.label]));
+
+/**
+ * An engine string, normalised to the key the page compares on.
+ *
+ * An ABSENT engine (null/undefined) is `r` — a hand-made cell with no header.
+ * An EMPTY engine is empty: ```{} names no engine and must never collapse into
+ * R, because "no engine" and "R" have opposite meanings at the run gate.
+ *
+ * @param {string|null|undefined} engine
+ * @returns {string}
+ */
+export function engineKey(engine) {
+  if (engine == null) return DEFAULT_ENGINE;
+  return String(engine).trim().toLowerCase();
+}
+
+/**
+ * `r` → "R", `python` → "Python"; an unknown engine keeps its own spelling,
+ * capitalised. The empty engine (```{}) has no name and returns "".
+ *
+ * @param {string|null|undefined} engine
+ * @returns {string}
+ */
+export function engineLabel(engine) {
+  const key = engineKey(engine);
+  if (!key) return "";
+  const known = BY_KEY.get(key);
+  if (known) return known;
+  return key.charAt(0).toUpperCase() + key.slice(1);
+}
+
+/** The word to put in a sentence for an engine that may be nameless. */
+function word(engine) {
+  return engineLabel(engine) || engineLabel(DEFAULT_ENGINE);
+}
+
+// ── phrasings ───────────────────────────────────────────────────────────────
+// One function per user-visible string that used to spell "R" inline. Each is
+// the WHOLE string, not a fragment, so a translator or a reviewer can read the
+// sentence here instead of reassembling it from a template at the call site.
+
+/** The code surface's accessible name: "R code editor" / "Python code editor". */
+export function codeEditorLabel(engine, profile = "cell") {
+  return `${word(engine)} ${profile === "script" ? "script" : "code"} editor`;
+}
+
+/** A figure's alt text: "R plot 1". `index` is 0-based, as the caller counts. */
+export function plotAltText(engine, index) {
+  return `${word(engine)} plot ${Number(index) + 1}`;
+}
+
+/** The AI panel's session chip: "⚡ R ready" (the glyph is the caller's). */
+export function readyLabel(engine) {
+  return `${word(engine)} ready`;
+}
+
+/** The footer's affiliation tail: "local R kernel". */
+export function kernelFooterLabel(engine) {
+  return `local ${word(engine)} kernel`;
+}
+
+/** Session ▾'s runtime row: "R Version" / "Python Version". */
+export function versionMenuLabel(engine) {
+  return `${word(engine)} Version`;
+}
+
+// ── what the attached kernel declared ───────────────────────────────────────
+
+/**
+ * The language a kernel declared, from its ready frame (`kernel.info`) or a
+ * parsed /health body — the two carry the same field name on purpose.
+ *
+ * @param {object|null|undefined} info
+ * @returns {string} an engine key: "r", "python", …
+ */
+export function kernelLanguage(info) {
+  const declared = info && typeof info.language === "string" ? info.language.trim() : "";
+  return declared ? engineKey(declared) : DEFAULT_ENGINE;
+}
+
+/**
+ * The language's version, as the kernel reported it.
+ *
+ * A kernel in any language other than R sends `language_version` ("3.14.4"),
+ * because a field called `r` holding a Python version would be a lie every
+ * existing reader would print.
+ *
+ * THE `r` FIELD HAS TWO SHAPES AND ONE NAME. The ready frame sends
+ * `R.version.string` — "R version 4.5.2 (2025-10-31)" — and /health sends
+ * "4.5.2". One reader has to handle both, so it strips what may be there and
+ * adds nothing. A patched build keeps its word ("4.5.2 Patched").
+ *
+ * @returns {string} e.g. "4.5.2", or "" when the kernel said nothing
+ */
+export function kernelVersion(info) {
+  if (!info) return "";
+  const declared = typeof info.language_version === "string" ? info.language_version.trim() : "";
+  if (declared) return declared;
+  if (typeof info.r === "string" && info.r.trim()) {
+    return info.r.replace(/^R version /, "").replace(/ \(.*\)$/, "").trim();
+  }
+  return "";
+}
+
+/**
+ * "R 4.5.2" / "Python 3.14.4" / "R session" — the short form for a badge, a
+ * chip or a chooser row. One function, so the badge, the status chip and the
+ * attach chooser cannot name one session three ways.
+ *
+ * With no version it is "<Language> session", which is what the attach chooser
+ * has always shown for a listener that named no version.
+ */
+export function kernelDisplay(info) {
+  const label = engineLabel(kernelLanguage(info));
+  const version = kernelVersion(info);
+  return version ? `${label} ${version}` : `${label} session`;
+}
+
+/**
+ * One engine row, normalised. Two wire shapes are accepted on purpose.
+ *
+ * `ready.engines` may be
+ *   - an array of STRINGS  — `["python", "bash"]`, a bare declaration of what
+ *     this kernel will also run. This is the shape the Python kernel
+ *     (`carmapy`) already sends and the page-patch series already reads, so it
+ *     must keep working.
+ *   - an array of OBJECTS  — `{name, label, version, path}`, which is what a
+ *     host that DISCOVERED runtimes can say. The engine chooser and Doctor
+ *     need the version and the path; a bare name cannot carry them.
+ *
+ * Accepting both is not indecision: they answer different questions ("may I
+ * send this chunk?" and "what did you find on this machine?"), and a kernel
+ * that can only answer the first must not be forced to invent the second.
+ *
+ * @returns {{name:string,label:string,version:string,path:string,current:boolean}|null}
+ */
+function engineRow(entry, language) {
+  if (typeof entry === "string") {
+    const name = engineKey(entry);
+    return name ? { name, label: engineLabel(name), version: "", path: "", current: name === language } : null;
+  }
+  if (!entry || typeof entry !== "object" || Array.isArray(entry)) return null;
+  const name = engineKey(entry.name ?? entry.engine ?? entry.key ?? entry.language);
+  if (!name) return null;
+  const text = (value) => (typeof value === "string" ? value.trim() : "");
+  return {
+    name,
+    label: text(entry.label) || engineLabel(name),
+    version: text(entry.version) || text(entry.language_version),
+    path: text(entry.path),
+    current: entry.current === true || name === language,
+  };
+}
+
+/**
+ * What the kernel SAID it found, normalised — or `[]` when it said nothing.
+ *
+ * An empty answer is the degradation signal, and it is deliberately NOT
+ * "assume R": a kernel that reports no engines is one built before the field
+ * existed, and the chooser that reads this must then show what it always
+ * showed rather than inventing a one-row table.
+ *
+ * @param {object|null|undefined} info
+ * @returns {Array<{name:string,label:string,version:string,path:string,current:boolean}>}
+ */
+export function reportedEngines(info) {
+  const declared = info && Array.isArray(info.engines) ? info.engines : null;
+  if (!declared || !declared.length) return [];
+  const language = kernelLanguage(info);
+  const rows = [];
+  declared.forEach((entry) => {
+    const row = engineRow(entry, language);
+    if (row && !rows.some((seen) => seen.name === row.name)) rows.push(row);
+  });
+  if (!rows.length) return [];
+  // The kernel's own language is always one of its engines — a session that
+  // would not run its own language is not a thing, and a list that omitted it
+  // would strand every chunk in the notebook.
+  if (!rows.some((row) => row.name === language)) {
+    rows.unshift({ name: language, label: engineLabel(language), version: kernelVersion(info), path: "", current: true });
+  } else {
+    const own = rows.find((row) => row.name === language);
+    if (!own.version) own.version = kernelVersion(info);
+    own.current = true;
+  }
+  return rows;
+}
+
+/**
+ * Every engine this kernel will execute, as keys — the language always first.
+ *
+ * This is the list a run gate compares against. It is never empty: with no
+ * declaration at all the answer is the kernel's language alone.
+ *
+ * @returns {string[]}
+ */
+export function declaredEngines(info) {
+  const language = kernelLanguage(info);
+  const out = [language];
+  reportedEngines(info).forEach((row) => { if (!out.includes(row.name)) out.push(row.name); });
+  return out;
+}
+
+// ── authoring: what an AI may say about a chunk's language ─────────────────
+// The tool schemas (lib/ai-tools.js, lib/mcp-bridge.js, tools/mcp/carmar-mcp.mjs)
+// all name engines from HERE, so the enum a model is shown, the refusal it gets
+// and the header a chunk is written with cannot disagree. Pure and import-free:
+// tools/mcp/carmar-mcp.mjs loads it in Node beside the authoring contract.
+
+/** The engines a tool schema offers. The SESSION decides which of them run. */
+export const AUTHORING_ENGINES = Object.freeze(KNOWN_ENGINES.map((e) => e.key));
+
+/**
+ * A tool's `engine` argument, validated. Absent (undefined, null, "") is R, so
+ * a call that never heard of the parameter means exactly what it always meant.
+ *
+ * @returns {string} an engine key
+ * @throws {Error} naming the engines that exist, for anything else
+ */
+export function engineArg(value, name = "engine") {
+  if (value == null || value === "") return DEFAULT_ENGINE;
+  if (typeof value !== "string") {
+    throw new Error(`${name} must be a string: one of ${AUTHORING_ENGINES.join(", ")}.`);
+  }
+  const key = engineKey(value);
+  if (!AUTHORING_ENGINES.includes(key)) {
+    throw new Error(`${name} "${value}" is not an engine CarmaR knows. Use one of ${AUTHORING_ENGINES.join(", ")}.`);
+  }
+  return key;
+}
+
+/**
+ * The chunk header a new code chunk carries for `engine` — the SAME shape the
+ * `carmar:insert-cell` door writes (src/notebook-entry.js). R gets none, so an
+ * R insert is byte-identical to one made before engines existed.
+ *
+ * @returns {object|null}
+ */
+export function engineChunkMeta(engine) {
+  const key = engineKey(engine);
+  if (!key || key === DEFAULT_ENGINE) return null;
+  return { engine: key, label: null, options: {}, rawOptions: null, hashPipeRaw: [] };
+}
+
+/**
+ * The engine of a notebook cell as a manifest or adapter describes it
+ * (`{kind, chunk}`): null for prose, the header's engine for code, R when the
+ * code cell has no header. An EMPTY engine (```{}) stays "" — it names none.
+ */
+export function cellEngine(cell) {
+  if (!cell) return null;
+  const kind = String(cell.kind || "");
+  if (kind === "md" || kind === "text") return null;
+  return engineKey(cell.chunk && cell.chunk.engine != null ? cell.chunk.engine : null);
+}
+
+/**
+ * Why a chunk in `engine` cannot be authored or run here, in the sentence a
+ * model repeats to the user — or "" when the attached session runs it.
+ *
+ * @param {string} engine
+ * @param {string[]} declared  what the host declared (lib/chunk-meta.js chunkEngines())
+ */
+export function engineRefusal(engine, declared = [DEFAULT_ENGINE]) {
+  const key = engineKey(engine);
+  const list = (Array.isArray(declared) && declared.length ? declared : [DEFAULT_ENGINE]).map(engineKey);
+  if (list.includes(key)) return "";
+  const runs = list.map(engineLabel);
+  const said = runs.length === 1 ? runs[0] : `${runs.slice(0, -1).join(", ")} and ${runs.at(-1)}`;
+  const name = key ? engineLabel(key) : "Engine-less";
+  return `This session does not run ${name} chunks — the attached session runs ${said} only. `
+    + `Write the step in ${runs[0]}, or tell the user that ${name} needs a session with a `
+    + `${name} engine (Session ▾ lists the engines this one found).`;
+}
+
+export default {
+  AUTHORING_ENGINES, engineArg, engineChunkMeta, cellEngine, engineRefusal,
+  KNOWN_ENGINES, DEFAULT_ENGINE, engineKey, engineLabel,
+  codeEditorLabel, plotAltText, readyLabel, kernelFooterLabel, versionMenuLabel,
+  kernelLanguage, kernelVersion, kernelDisplay, reportedEngines, declaredEngines,
+};

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "beatrina",
+  "version": "0.8.6",
+  "description": "Beatrina is a modern, powerful, feature-rich integrated development environment (IDE) for R, Python, and JavaScript.",
+  "type": "module",
+  "bin": {
+    "beatrina": "bin/beatrina.mjs"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "optionalDependencies": {
+    "node-pty": "^1.1.0"
+  },
+  "license": "SEE LICENSE IN LICENSE",
+  "author": "Mohammed Saqr <saqr@saqr.me> (https://saqr.me)",
+  "homepage": "https://saqr.me",
+  "files": [
+    "bin",
+    "host",
+    "engines",
+    "kernel",
+    "failsafe",
+    "lib",
+    "check",
+    "build-info.json",
+    "carmar_V0.8.6.html",
+    "README.md",
+    "LICENSE",
+    "NOTICES"
+  ]
+}