mirror-mind 0.0.1 → 0.33.0

package/ts/src/util/pythonText.ts

@@ -0,0 +1,317 @@
+// Python string semantics the port must reproduce byte-for-byte.
+//
+// Python indexes, slices, and orders `str` by Unicode code point. JavaScript
+// does all three by UTF-16 code unit, which agrees with Python on the Basic
+// Multilingual Plane and silently disagrees the moment an emoji or any other
+// astral character appears: `"🎯x".slice(0, 1)` is half a surrogate pair, and
+// `"🎯" < "\uFFFF"` in JS while Python says the opposite. Title truncation,
+// sorted term lists, and path ordering are all parity surfaces graded against
+// Python's output, so every one of them must go through these helpers.
+
+/**
+ * Python's whitespace set: what `str.isspace()` reports, what `str.strip()`
+ * removes, and what `\s` matches in a `str` pattern. It is NOT JavaScript's
+ * `\s`, and the difference is load-bearing in both directions:
+ *
+ * - Python includes U+001C-U+001F (the file/group/record/unit separators);
+ *   JavaScript does not.
+ * - JavaScript includes U+FEFF (the byte-order mark); Python does not.
+ *
+ * A UTF-8 file that opens with a BOM is the realistic case: both cores read
+ * the BOM into the string, and a JavaScript `\s` would silently collapse it
+ * away while Python keeps it -- enough to change a checksum and make one core
+ * report drift the other cannot see. Written as a class body so callers can
+ * build the anchors and quantifiers they need.
+ */
+export const PYTHON_WHITESPACE_CLASS =
+  "\\t\\n\\v\\f\\r\\u001c-\\u001f \\u0085\\u00a0\\u1680\\u2000-\\u200a\\u2028\\u2029\\u202f\\u205f\\u3000";
+
+/** A fresh regex over {@link PYTHON_WHITESPACE_CLASS}; `flags` always gets `u`. */
+export function pythonWhitespaceRegex(quantifier = "+", flags = "g"): RegExp {
+  return new RegExp(`[${PYTHON_WHITESPACE_CLASS}]${quantifier}`, `${flags}u`);
+}
+
+const PY_STRIP_RE = new RegExp(
+  `^[${PYTHON_WHITESPACE_CLASS}]+|[${PYTHON_WHITESPACE_CLASS}]+$`,
+  "gu",
+);
+
+/** Python `str.strip()` with no argument. Not `String.prototype.trim()`. */
+export function pyStrip(text: string): string {
+  return text.replace(PY_STRIP_RE, "");
+}
+
+const PY_RSTRIP_RE = new RegExp(`[${PYTHON_WHITESPACE_CLASS}]+$`, "u");
+
+/** Python `str.rstrip()` with no argument. */
+export function pyRStrip(text: string): string {
+  return text.replace(PY_RSTRIP_RE, "");
+}
+
+const PY_SPLIT_RE = new RegExp(`[${PYTHON_WHITESPACE_CLASS}]+`, "u");
+
+/**
+ * Python `str.split()` with no argument: split on RUNS of whitespace and drop
+ * the empty leading/trailing fields. `"a  b ".split()` is `["a", "b"]`, while
+ * JavaScript's `"a  b ".split(/\s+/)` yields a trailing `""` -- and disagrees
+ * about the separator set on U+001C-U+001F and U+FEFF besides.
+ */
+export function pySplitWhitespace(text: string): string[] {
+  const stripped = pyStrip(text);
+  if (stripped === "") return [];
+  return stripped.split(PY_SPLIT_RE);
+}
+
+/**
+ * Python `str.splitlines()`: the line boundaries are \n, \r, \r\n, \v, \f,
+ * U+001C, U+001D, U+001E, U+0085, U+2028, and U+2029 -- eleven of them, where
+ * `split("\n")` knows one. A ritual card fed a form feed renders as two blocks
+ * in Python and one long line in a naive port.
+ *
+ * Like Python, a trailing boundary does not produce a final empty field.
+ */
+export function pySplitLines(text: string): string[] {
+  if (text === "") return [];
+  const lines: string[] = [];
+  let current = "";
+  for (let index = 0; index < text.length; index += 1) {
+    const char = text[index] as string;
+    if (char === "\r") {
+      lines.push(current);
+      current = "";
+      if (text[index + 1] === "\n") index += 1;
+      continue;
+    }
+    if (PY_LINE_BOUNDARIES.has(char)) {
+      lines.push(current);
+      current = "";
+      continue;
+    }
+    current += char;
+  }
+  if (current !== "") lines.push(current);
+  return lines;
+}
+
+const PY_LINE_BOUNDARIES = new Set([
+  "\n",
+  "\v",
+  "\f",
+  "\u001c",
+  "\u001d",
+  "\u001e",
+  "\u0085",
+  "\u2028",
+  "\u2029",
+]);
+
+/**
+ * Python truthiness. JavaScript and Python agree on `null`/`undefined`,
+ * `false`, `0`, `NaN`, and `""` -- and disagree on containers: `[]` and `{}`
+ * are falsy in Python and truthy in JavaScript. Manifest validation leans on
+ * this exactly (`if not data.get(field)`), so an extension declaring
+ * `runtimes: {}` must fail the required-field check, not sail past it.
+ */
+export function pyTruthy(value: unknown): boolean {
+  if (value === null || value === undefined || value === false) return false;
+  if (typeof value === "number") return value !== 0 && !Number.isNaN(value);
+  if (typeof value === "string") return value.length > 0;
+  if (Array.isArray(value)) return value.length > 0;
+  if (typeof value === "object") return Object.keys(value).length > 0;
+  return Boolean(value);
+}
+
+/**
+ * Python `str(value)` for the scalar shapes a YAML manifest can hold. Error
+ * messages interpolate parsed YAML directly, so `None`/`True`/`False` must
+ * render with Python's capitalization, not JavaScript's.
+ */
+export function pyStr(value: unknown): string {
+  if (value === null || value === undefined) return "None";
+  if (value === true) return "True";
+  if (value === false) return "False";
+  if (Array.isArray(value)) return `[${value.map(pyRepr).join(", ")}]`;
+  if (typeof value === "object") {
+    const entries = Object.entries(value as Record<string, unknown>);
+    return `{${entries.map(([key, item]) => `${pyRepr(key)}: ${pyRepr(item)}`).join(", ")}}`;
+  }
+  return String(value);
+}
+
+/**
+ * Python `str.title()`: uppercase the first cased character of every run of
+ * letters, lowercase the rest.
+ *
+ * Not `capitalize()` and not a naive `[0].toUpperCase() + slice(1)`. Python breaks
+ * runs on any non-alphabetic character, so `"plan_approved".title()` is
+ * `"Plan_Approved"` and `"don't".title()` is `"Don'T"` -- the second is a famous
+ * Python wart, and a port that "fixes" it diverges on any surface that titles a
+ * value containing an apostrophe.
+ *
+ * Only lifecycle `next_event` values reach this today (`prepare`, `implement`),
+ * which are single lowercase words, so the wart is reproduced rather than
+ * exercised.
+ */
+export function pyTitle(text: string): string {
+  let previousIsAlpha = false;
+  let result = "";
+  for (const character of text) {
+    const isAlpha = /\p{L}/u.test(character);
+    result += previousIsAlpha ? character.toLowerCase() : character.toUpperCase();
+    previousIsAlpha = isAlpha;
+  }
+  return result;
+}
+
+/**
+ * Python `repr(value)` / an f-string's `!r`.
+ *
+ * Widened at CV22.DS7.TS4 plateau 2, where `inspect llm-calls` prints stored
+ * prompts and responses with `!r` -- arbitrary user text, not the single
+ * lowercase words the first caller passed. Python's rules, in order:
+ *
+ *   * the QUOTE is single, unless the string contains a single quote and no
+ *     double quote, in which case Python switches to double quotes rather
+ *     than escaping (`"it's fine"`, not `'it\'s fine'`);
+ *   * a backslash is doubled, and the chosen quote is escaped;
+ *   * `\n`, `\r`, `\t` get their short escapes; every other C0 control and
+ *     DEL get `\xNN`;
+ *   * printable non-ASCII is left ALONE (Python 3 repr is not ASCII-safe),
+ *     so `descrição` stays itself;
+ *   * non-printable non-ASCII is escaped by width: `\xNN`, `\uNNNN`, or
+ *     `\UNNNNNNNN`. Python's printable excludes Unicode's Other and Separator
+ *     categories, so a C1 control (U+009B, the 8-bit CSI), a bidi override, a
+ *     zero-width space, and a line separator are all escaped. Until CR104 the
+ *     port left them raw, so they reached a terminal through every caller.
+ *
+ * The categories come from the Unicode tables V8 carries, which can differ from
+ * the running Python's for code points assigned between their versions.
+ */
+export function pyRepr(value: unknown): string {
+  return typeof value === "string" ? pyReprString(value) : pyStr(value);
+}
+
+/** Unicode's Other and Separator categories: what Python's `str.isprintable` refuses. */
+const OTHER_OR_SEPARATOR = /^[\p{C}\p{Z}]$/u;
+
+/** Whether Python's repr prints `character` as itself. The ASCII space is the one printable separator. */
+function pyPrintable(character: string, code: number): boolean {
+  if (code < 0x80) return code >= 0x20 && code !== 0x7f;
+  return !OTHER_OR_SEPARATOR.test(character);
+}
+
+/** Python's escape for a character it will not print, by width. */
+function pyEscape(code: number): string {
+  if (code <= 0xff) return `\\x${code.toString(16).padStart(2, "0")}`;
+  if (code <= 0xffff) return `\\u${code.toString(16).padStart(4, "0")}`;
+  return `\\U${code.toString(16).padStart(8, "0")}`;
+}
+
+function pyReprString(value: string): string {
+  const quote = value.includes("'") && !value.includes('"') ? '"' : "'";
+  let out = "";
+  for (const character of value) {
+    if (character === "\\") {
+      out += "\\\\";
+    } else if (character === quote) {
+      out += `\\${quote}`;
+    } else if (character === "\n") {
+      out += "\\n";
+    } else if (character === "\r") {
+      out += "\\r";
+    } else if (character === "\t") {
+      out += "\\t";
+    } else {
+      const code = character.codePointAt(0) ?? 0;
+      out += pyPrintable(character, code) ? character : pyEscape(code);
+    }
+  }
+  return `${quote}${out}${quote}`;
+}
+
+/** Python `sorted()` / `<` on `str`: lexicographic by code point. */
+export function compareByCodePoint(a: string, b: string): number {
+  const left = Array.from(a);
+  const right = Array.from(b);
+  const shared = Math.min(left.length, right.length);
+  for (let index = 0; index < shared; index += 1) {
+    const delta = (left[index]?.codePointAt(0) ?? 0) - (right[index]?.codePointAt(0) ?? 0);
+    if (delta !== 0) return delta;
+  }
+  return left.length - right.length;
+}
+
+/** Python `sorted(values)` on strings. Returns a new array. */
+export function sortByCodePoint(values: readonly string[]): string[] {
+  return [...values].sort(compareByCodePoint);
+}
+
+/** Python `len(text)`: the number of code points, not UTF-16 units. */
+export function codePointLength(text: string): number {
+  return Array.from(text).length;
+}
+
+/** Python `text[:end]`: the first `end` code points. */
+export function sliceCodePoints(text: string, end: number): string {
+  return Array.from(text).slice(0, end).join("");
+}
+
+/**
+ * Python `sorted()` over `pathlib.Path` values: paths compare by their
+ * COMPONENT lists, not by their joined string. The two orders diverge whenever
+ * a directory name contains a character that sorts before `/` (0x2F) -- `-`
+ * (0x2D) is the common one, so `a/b` precedes `a-x/c` for Python while a plain
+ * string sort puts `a-x/c` first. Callers pass already-split components.
+ */
+export function comparePathComponents(a: readonly string[], b: readonly string[]): number {
+  const shared = Math.min(a.length, b.length);
+  for (let index = 0; index < shared; index += 1) {
+    const delta = compareByCodePoint(a[index] as string, b[index] as string);
+    if (delta !== 0) return delta;
+  }
+  return a.length - b.length;
+}
+
+/**
+ * Python `str.format(**values)` for named fields, including brace escaping.
+ *
+ * `"{{"` and `"}}"` are LITERAL braces in a format string and collapse to a
+ * single brace, which a naive `replaceAll("{name}", value)` leaves doubled.
+ * `WEEK_PLAN_PROMPT` embeds a JSON example written with doubled braces exactly
+ * so `.format()` can be applied to it, so the difference is not cosmetic: the
+ * assembled prompt bytes -- and therefore the replay digest -- disagree
+ * (CV22.DS7.US11, caught by the prompt-assembly golden).
+ *
+ * Only the subset the vendored templates use is implemented: named fields with
+ * no conversion, no format spec, no attribute or index access. An unknown
+ * field raises, as Python's `KeyError` does, rather than silently emitting the
+ * placeholder into a prompt.
+ */
+export function pyFormat(template: string, values: Readonly<Record<string, string>>): string {
+  let out = "";
+  for (let index = 0; index < template.length; index += 1) {
+    const char = template[index];
+    const next = template[index + 1];
+    if (char === "{" && next === "{") {
+      out += "{";
+      index += 1;
+    } else if (char === "}" && next === "}") {
+      out += "}";
+      index += 1;
+    } else if (char === "{") {
+      const close = template.indexOf("}", index + 1);
+      if (close === -1) throw new Error("pyFormat: unmatched '{' in template");
+      const field = template.slice(index + 1, close);
+      if (!Object.hasOwn(values, field)) {
+        throw new Error(`pyFormat: no value for field ${JSON.stringify(field)}`);
+      }
+      out += values[field];
+      index = close;
+    } else if (char === "}") {
+      throw new Error("pyFormat: single '}' in template");
+    } else {
+      out += char;
+    }
+  }
+  return out;
+}

package/ts/src/util/semver.ts

@@ -0,0 +1,45 @@
+// Version comparison, once. (CV22.DS10.US3 plateau 4)
+//
+// Three readers compared versions before this module and each carried its own
+// copy: the release-notes reader (the oracle's `_parse_semver`), the welcome
+// card's remote tag (the oracle's `_semver_key`, the same function under a
+// second name), and now the package updater's plan, which has to know whether
+// a channel is ahead of or BEHIND the installed version. One rule for all
+// three, with the oracle's sort behavior kept: an unparseable version sorts
+// below every real one.
+
+export type SemverTriple = [number, number, number];
+
+const LOOSE = /^v?(\d+)\.(\d+)\.(\d+)$/;
+/** No leading `v`, no prerelease, no build, no surrounding space. */
+const PLAIN = /^\d+\.\d+\.\d+$/;
+
+/** Port of `_parse_semver`: an unparseable version is `[-1, -1, -1]`. */
+export function parseSemver(version: string): SemverTriple {
+  const match = LOOSE.exec(version.trim());
+  if (!match) return [-1, -1, -1];
+  return [Number(match[1]), Number(match[2]), Number(match[3])];
+}
+
+/** Negative when `a` is older than `b`, positive when newer, zero when equal. */
+export function compareSemver(a: string, b: string): number {
+  const left = parseSemver(a);
+  const right = parseSemver(b);
+  for (let index = 0; index < 3; index += 1) {
+    const diff = (left[index] as number) - (right[index] as number);
+    if (diff !== 0) return diff;
+  }
+  return 0;
+}
+
+/**
+ * The strict form: a bare numeric triple and nothing else.
+ *
+ * This is what a registry's dist-tag answer must look like before it becomes
+ * the spec of `npm install -g <name>@<value>`. npm's spec grammar also admits
+ * tags, ranges, URLs, and paths, and a value that is one of those installs
+ * something other than a version.
+ */
+export function isPlainSemver(version: string): boolean {
+  return PLAIN.test(version);
+}

package/ts/src/util/shellWord.ts

@@ -0,0 +1,25 @@
+// CR104 — one shell word for a value a printed command interpolates.
+//
+// Mirror prints commands for its reader to run: `Run: mirror build adopt --journey
+// <slug> --method ariad`, the Pull command, a skipped seed entry's edit command.
+// Agents run them as printed. A value that reaches such a command from the database
+// — a journey slug, a persona id — may predate the grammar that now keeps new keys
+// plain (`#identity/identityKey.ts`), so it can hold anything a shell reads as
+// syntax. Every such command therefore quotes what it interpolates, here, once.
+//
+// CR002 wrote this for the Pull command, private to `scopePhrases.ts`; CR104 made
+// it the one helper every printed command uses.
+
+/**
+ * A POSIX shell word for `value`: as is when it is a plain token, single-quoted
+ * otherwise, so `x;touch PWNED` arrives as one argument and runs nothing. A plain
+ * token prints unchanged, which keeps every ordinary slug byte-identical in the
+ * commands that print it. The empty string becomes `''`, one empty argument.
+ *
+ * Quoting does not stop a word that begins with `-` from reading as an option to
+ * the command it is passed to. That is the grammar's job, not the shell's.
+ */
+export function shellWord(value: string): string {
+  if (/^[A-Za-z0-9._-]+$/u.test(value)) return value;
+  return `'${value.replaceAll("'", `'\\''`)}'`;
+}

package/ts/src/util/slug.ts

@@ -0,0 +1,64 @@
+// Port of src/memory/utils.py (strip_accents, kebab_slug). Registered in
+// ts/parity/oracle-baseline.json.
+//
+// kebab_slug is the canonical filesystem-safe slug for roadmap folders,
+// journey slugs, and exploration folders across the Python codebase (builder
+// story paths, explorer handoff ids, JourneyService.draft_journey). Ported
+// here as ONE shared function for both writer and locator call sites, per the
+// DS7.US1 rider: the original Python bug this guards against was
+// writer/locator drift from two independently-hand-rolled slugifiers.
+
+/**
+ * Port of `strip_accents`: NFD-decompose, then drop every Unicode
+ * Nonspacing_Mark codepoint (Python's `unicodedata.category(c) == "Mn"`) --
+ * e.g. "episódio" -> "episodio". Both runtimes resolve category membership
+ * against the same kind of Unicode Character Database assignment (ICU-backed
+ * in Python's `unicodedata` and in V8's Unicode property escapes), verified
+ * against the live oracle for a broad accent/script sample rather than
+ * assumed equivalent.
+ */
+export function stripAccents(text: string): string {
+  return text.normalize("NFD").replace(/\p{Mn}/gu, "");
+}
+
+/**
+ * Port of `kebab_slug`: lowercase, strip accents, collapse every run of
+ * non-`[a-z0-9]` characters to a single hyphen, trim edge hyphens, then
+ * hard-cap at `maxLength` characters (re-trimming any edge hyphen the cap
+ * itself exposes) so a single directory component can never exceed the
+ * filesystem NAME_MAX limit (255 bytes). Truncation is safe as plain UTF-16
+ * slicing because by this point the string contains only ASCII
+ * `[a-z0-9-]` characters -- the accent-stripping and character-class
+ * collapse already happened, so there is no multi-code-unit codepoint for a
+ * slice boundary to split.
+ *
+ * Returns "" when no alphanumeric content remains; callers decide how to
+ * handle that (bare code prefix, fallback token, or a validation error) --
+ * this function never substitutes a default itself.
+ */
+export function kebabSlug(text: string, maxLength = 80): string {
+  const normalized = stripAccents(text).toLowerCase();
+  let slug = normalized.replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+  if (slug.length > maxLength) {
+    slug = slug.slice(0, maxLength).replace(/^-+|-+$/g, "");
+  }
+  return slug;
+}
+
+const KEBAB_SLUG = /^[a-z0-9]+(?:-[a-z0-9]+)*$/u;
+
+/**
+ * Whether `value` is a kebab-case slug: lowercase ASCII letters and digits, in runs
+ * joined by single hyphens, at most `maxLength` characters. Those are exactly the
+ * non-empty strings `kebabSlug` returns unchanged, so a slug is what this module
+ * would have made, and `kebabSlug` of anything else is the slug to suggest in its
+ * place (CR104).
+ *
+ * A shell carries such a slug as one plain word, and it can never begin with the
+ * hyphen that would make it read as an option. That is why journey slugs and
+ * persona ids, which agents put into commands, must be one
+ * (`#identity/identityKey.ts`).
+ */
+export function isKebabSlug(value: string, maxLength = 80): boolean {
+  return value.length <= maxLength && KEBAB_SLUG.test(value);
+}