@terminus-ai/cli 0.0.1

package/bin/vendor/where.mjs

@@ -0,0 +1,541 @@
+/**
+ * `@terminus-ai/app-sdk/where` — the ONE JavaScript evaluator for the §2.6
+ * managed-record query grammar: `where` validation + matching, `sort`
+ * ordering, and `search` text extraction + matching.
+ *
+ * The backend (`parse_record_filter` + the SQL it builds over `jsonb`) is
+ * the specification; this module mirrors it so that the SDK's client-side
+ * projections (`LiveCollection`), the `terminus dev` harness, and tests all
+ * agree with production. `conformance/where-grammar.json` carries the shared
+ * vectors.
+ *
+ * Known gaps versus PostgreSQL (documented, not hidden):
+ *   - String ordering follows `localeCompare("en")`, an approximation of the
+ *     database collation (en_US). Code-unit order is used only as a tiebreak.
+ *   - Full-text search mirrors `websearch_to_tsquery('simple', …)` over
+ *     `to_tsvector('simple', …)`: whole-token matching, AND/OR/NOT, quoted
+ *     phrases. The tokenizer approximates the default text-search parser
+ *     (words, numbers, hyphenated compounds, decimals, hosts/emails); URL
+ *     paths, file paths, and other exotic token classes are tokenized as
+ *     plain words here but as compound tokens by PostgreSQL.
+ *   - Top-level jsonb scalar-versus-array ordering quirks (a raw scalar
+ *     compares as a one-element array) are reproduced, but only matter when
+ *     one field mixes scalars and arrays across records.
+ */
+export const WHERE_OPERATORS = Object.freeze([
+    "eq",
+    "ne",
+    "gt",
+    "gte",
+    "lt",
+    "lte",
+    "in",
+    "exists",
+]);
+const OPERATOR_SET = new Set(WHERE_OPERATORS);
+/** Mirrors the backend's limits exactly. */
+export const WHERE_MAX_CONDITIONS = 8;
+export const WHERE_MAX_IN_OPTIONS = 32;
+export const WHERE_MAX_FIELD_LENGTH = 64;
+/** Thrown by `validateWhere`/`validateSort` for exactly the inputs the
+ * backend rejects with HTTP 400. */
+export class WhereGrammarError extends Error {
+    code = "invalid_where";
+    status = 400;
+    constructor(message) {
+        super(message);
+        this.name = "WhereGrammarError";
+    }
+}
+const FIELD_NAME = /^[A-Za-z0-9_.-]{1,64}$/;
+/** Mirrors the backend's `safe_field_name`. Field names are literal
+ * top-level keys: `"a.b"` addresses the key named `a.b`, not a path. */
+export function isSafeFieldName(field) {
+    return typeof field === "string" && FIELD_NAME.test(field);
+}
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/**
+ * Validate a `where` object and compile it into containment + conditions.
+ * Throws `WhereGrammarError` for every input the backend answers with 400:
+ * non-object filters, unsafe field names, `in` without 1-32 literals,
+ * non-boolean `exists`, or more than 8 operator conditions.
+ */
+export function validateWhere(where) {
+    if (where === undefined || where === null)
+        return { containment: {}, conditions: [] };
+    if (!isPlainObject(where))
+        throw new WhereGrammarError("where must be a JSON object");
+    const containment = {};
+    const conditions = [];
+    for (const [field, spec] of Object.entries(where)) {
+        if (!isSafeFieldName(field))
+            throw new WhereGrammarError(`invalid where field '${field}'`);
+        if (spec === undefined)
+            continue;
+        if (!isPlainObject(spec)) {
+            containment[field] = spec;
+            continue;
+        }
+        // An object whose keys are ALL operators is a condition set — e.g.
+        // { gte: a, lte: b } is a range. Anything else keeps containment.
+        const keys = Object.keys(spec);
+        const allOperators = keys.length > 0 && keys.every((key) => OPERATOR_SET.has(key));
+        if (!allOperators) {
+            containment[field] = spec;
+            continue;
+        }
+        for (const [key, operand] of Object.entries(spec)) {
+            const op = key;
+            switch (op) {
+                case "eq":
+                    containment[field] = operand;
+                    break;
+                case "ne":
+                    conditions.push([field, { op: "ne", operand }]);
+                    break;
+                case "gt":
+                case "gte":
+                case "lt":
+                case "lte":
+                    conditions.push([field, { op, operand }]);
+                    break;
+                case "in": {
+                    if (!Array.isArray(operand)) {
+                        throw new WhereGrammarError("'in' takes an array of literals");
+                    }
+                    if (operand.length === 0 || operand.length > WHERE_MAX_IN_OPTIONS) {
+                        throw new WhereGrammarError("'in' takes 1-32 literals");
+                    }
+                    conditions.push([field, { op: "in", options: operand }]);
+                    break;
+                }
+                case "exists":
+                    if (typeof operand !== "boolean") {
+                        throw new WhereGrammarError("'exists' takes true or false");
+                    }
+                    conditions.push([field, { op: "exists", expected: operand }]);
+                    break;
+            }
+        }
+    }
+    if (conditions.length > WHERE_MAX_CONDITIONS) {
+        throw new WhereGrammarError("where supports at most 8 operator conditions");
+    }
+    return { containment, conditions };
+}
+/** Validate a `sort` spec (`field` or `-field`). Returns the field and
+ * direction; throws `WhereGrammarError` on an unsafe field name. */
+export function validateSort(sort) {
+    if (typeof sort !== "string")
+        throw new WhereGrammarError("sort must be a string");
+    const descending = sort.startsWith("-");
+    const field = descending ? sort.slice(1) : sort;
+    if (!isSafeFieldName(field))
+        throw new WhereGrammarError(`invalid sort field '${field}'`);
+    return { field, descending };
+}
+// ---------------------------------------------------------------------------
+// jsonb semantics
+// ---------------------------------------------------------------------------
+/** Deep JSON equality (key-order independent), as `jsonb = jsonb`. */
+export function jsonEquals(left, right) {
+    if (Object.is(left, right))
+        return true;
+    if (typeof left === "number" && typeof right === "number")
+        return left === right;
+    if (Array.isArray(left) || Array.isArray(right)) {
+        if (!Array.isArray(left) || !Array.isArray(right) || left.length !== right.length)
+            return false;
+        return left.every((item, index) => jsonEquals(item, right[index]));
+    }
+    if (isPlainObject(left) && isPlainObject(right)) {
+        const leftKeys = Object.keys(left);
+        if (leftKeys.length !== Object.keys(right).length)
+            return false;
+        return leftKeys.every((key) => Object.hasOwn(right, key) && jsonEquals(left[key], right[key]));
+    }
+    return false;
+}
+/**
+ * jsonb containment (`haystack @> needle`) for nested values: objects contain
+ * objects whose every key is present with a contained value; arrays contain
+ * arrays whose every element is contained by some element; primitives must
+ * be equal. (The top-level "array contains primitive" exception never applies
+ * here because a `where` object is always an object.)
+ */
+export function jsonContains(haystack, needle) {
+    if (isPlainObject(needle)) {
+        if (!isPlainObject(haystack))
+            return false;
+        return Object.entries(needle).every(([key, value]) => Object.hasOwn(haystack, key) && jsonContains(haystack[key], value));
+    }
+    if (Array.isArray(needle)) {
+        if (!Array.isArray(haystack))
+            return false;
+        return needle.every((item) => {
+            if (isPlainObject(item))
+                return haystack.some((candidate) => jsonContains(candidate, item));
+            if (Array.isArray(item))
+                return haystack.some((candidate) => jsonContains(candidate, item));
+            return haystack.some((candidate) => jsonEquals(candidate, item));
+        });
+    }
+    return jsonEquals(haystack, needle);
+}
+/** `jsonb_typeof` */
+export function jsonTypeOf(value) {
+    if (value === undefined)
+        return undefined;
+    if (value === null)
+        return "null";
+    if (Array.isArray(value))
+        return "array";
+    switch (typeof value) {
+        case "string":
+            return "string";
+        case "number":
+            return "number";
+        case "boolean":
+            return "boolean";
+        case "object":
+            return "object";
+        default:
+            return undefined;
+    }
+}
+const TYPE_RANK = {
+    null: 0,
+    string: 1,
+    number: 2,
+    boolean: 3,
+    array: 4,
+    object: 5,
+};
+export function compareStrings(left, right) {
+    const collated = left.localeCompare(right, "en");
+    if (collated !== 0)
+        return collated < 0 ? -1 : 1;
+    return left < right ? -1 : left > right ? 1 : 0;
+}
+/** jsonb object keys sort by length first, then bytewise. */
+function compareKeys(left, right) {
+    if (left.length !== right.length)
+        return left.length < right.length ? -1 : 1;
+    return left < right ? -1 : left > right ? 1 : 0;
+}
+/**
+ * Total order over JSON values as PostgreSQL orders `jsonb`
+ * (Object > Array > Boolean > Number > String > Null; arrays by length then
+ * elements; objects by pair count then sorted pairs). Never receives
+ * `undefined` — callers handle missing fields (NULLS LAST) themselves.
+ */
+export function compareJson(left, right) {
+    const leftType = jsonTypeOf(left) ?? "null";
+    const rightType = jsonTypeOf(right) ?? "null";
+    if (leftType !== rightType) {
+        // Raw scalars are stored as one-element arrays: against an array they
+        // compare by length first, then sort before the array.
+        if (leftType === "array" && rightType !== "object") {
+            const rightLength = 1;
+            if (left.length !== rightLength) {
+                return left.length < rightLength ? -1 : 1;
+            }
+            return 1;
+        }
+        if (rightType === "array" && leftType !== "object") {
+            const leftLength = 1;
+            if (leftLength !== right.length) {
+                return leftLength < right.length ? -1 : 1;
+            }
+            return -1;
+        }
+        return TYPE_RANK[leftType] < TYPE_RANK[rightType] ? -1 : 1;
+    }
+    switch (leftType) {
+        case "null":
+            return 0;
+        case "boolean":
+            return left === right ? 0 : left ? 1 : -1;
+        case "number": {
+            const a = left;
+            const b = right;
+            return a < b ? -1 : a > b ? 1 : 0;
+        }
+        case "string":
+            return compareStrings(left, right);
+        case "array": {
+            const a = left;
+            const b = right;
+            if (a.length !== b.length)
+                return a.length < b.length ? -1 : 1;
+            for (let index = 0; index < a.length; index += 1) {
+                const order = compareJson(a[index], b[index]);
+                if (order)
+                    return order;
+            }
+            return 0;
+        }
+        case "object": {
+            const a = left;
+            const b = right;
+            const aKeys = Object.keys(a).sort(compareKeys);
+            const bKeys = Object.keys(b).sort(compareKeys);
+            if (aKeys.length !== bKeys.length)
+                return aKeys.length < bKeys.length ? -1 : 1;
+            for (let index = 0; index < aKeys.length; index += 1) {
+                const keyOrder = compareKeys(aKeys[index], bKeys[index]);
+                if (keyOrder)
+                    return keyOrder;
+                const valueOrder = compareJson(a[aKeys[index]], b[bKeys[index]]);
+                if (valueOrder)
+                    return valueOrder;
+            }
+            return 0;
+        }
+        default:
+            return 0;
+    }
+}
+// ---------------------------------------------------------------------------
+// where matching
+// ---------------------------------------------------------------------------
+function fieldValue(value, field) {
+    return isPlainObject(value) && Object.hasOwn(value, field) ? value[field] : undefined;
+}
+function conditionMatches(actual, condition) {
+    switch (condition.op) {
+        case "ne":
+            // IS DISTINCT FROM: a missing field is distinct from every operand.
+            return actual === undefined || !jsonEquals(actual, condition.operand);
+        case "in":
+            return actual !== undefined && condition.options.some((option) => jsonEquals(actual, option));
+        case "exists":
+            return (actual !== undefined) === condition.expected;
+        default: {
+            // Same-type jsonb comparison: type mismatches and missing fields never match.
+            if (actual === undefined || jsonTypeOf(actual) !== jsonTypeOf(condition.operand))
+                return false;
+            const order = compareJson(actual, condition.operand);
+            switch (condition.op) {
+                case "gt":
+                    return order > 0;
+                case "gte":
+                    return order >= 0;
+                case "lt":
+                    return order < 0;
+                case "lte":
+                    return order <= 0;
+            }
+        }
+    }
+}
+/** Evaluate a compiled filter against one record value. */
+export function compiledWhereMatches(value, compiled) {
+    if (Object.keys(compiled.containment).length && !jsonContains(value, compiled.containment)) {
+        return false;
+    }
+    return compiled.conditions.every(([field, condition]) => conditionMatches(fieldValue(value, field), condition));
+}
+/**
+ * Does `value` satisfy `where`? Validates first (throws `WhereGrammarError`
+ * exactly where the backend would answer 400). For repeated evaluation
+ * compile once with `validateWhere` and call `compiledWhereMatches`.
+ */
+export function whereMatches(value, where) {
+    return compiledWhereMatches(value, validateWhere(where));
+}
+/**
+ * Comparator for `ORDER BY data->field [DESC] NULLS LAST, record_id ASC`,
+ * or plain `ORDER BY record_id` when `sort` is omitted. Missing fields sort
+ * last in either direction; JSON `null` is a value (lowest) and follows
+ * the direction.
+ */
+export function recordComparator(sort) {
+    if (!sort)
+        return (left, right) => compareStrings(left.id, right.id);
+    const { field, descending } = validateSort(sort);
+    return (left, right) => {
+        const a = fieldValue(left.value, field);
+        const b = fieldValue(right.value, field);
+        if (a === undefined || b === undefined) {
+            if (a === undefined && b === undefined)
+                return compareStrings(left.id, right.id);
+            return a === undefined ? 1 : -1;
+        }
+        const order = compareJson(a, b);
+        if (order)
+            return descending ? -order : order;
+        return compareStrings(left.id, right.id);
+    };
+}
+/** Sort a copy of `records` by `sort` (see `recordComparator`). */
+export function sortRecords(records, sort) {
+    return [...records].sort(recordComparator(sort));
+}
+// ---------------------------------------------------------------------------
+// search
+// ---------------------------------------------------------------------------
+/**
+ * The searchable text for a record (mirrors `record_search_text`): the
+ * declared search fields joined by newlines — strings verbatim, arrays of
+ * strings one per line, other non-null values as JSON — or the whole record
+ * as compact JSON when no fields are declared.
+ */
+export function searchText(searchFields, value) {
+    const fields = Array.isArray(searchFields) ? searchFields.filter((f) => typeof f === "string") : [];
+    if (!fields.length)
+        return JSON.stringify(value ?? null);
+    let text = "";
+    for (const field of fields) {
+        const item = fieldValue(value, field);
+        if (typeof item === "string") {
+            text += `${item}\n`;
+        }
+        else if (Array.isArray(item)) {
+            for (const entry of item)
+                if (typeof entry === "string")
+                    text += `${entry}\n`;
+        }
+        else if (item !== undefined && item !== null) {
+            text += `${JSON.stringify(item)}\n`;
+        }
+    }
+    return text;
+}
+const WORD = "[\\p{L}\\p{N}]+";
+// Compound classes the default parser emits as one lexeme (plus parts for
+// hyphenated words): emails, hosts/versions (dotted), hyphenated words,
+// decimal numbers; then plain words.
+const TOKEN_PATTERN = new RegExp([
+    `(?<email>[\\p{L}\\p{N}_.+-]+@[\\p{L}\\p{N}-]+(?:\\.[\\p{L}\\p{N}-]+)+)`,
+    `(?<host>[\\p{L}\\p{N}-]+(?:\\.[\\p{L}\\p{N}-]+)+)`,
+    `(?<hyphenated>${WORD}(?:-${WORD})+)`,
+    `(?<word>${WORD})`,
+].join("|"), "gu");
+/**
+ * Approximates `to_tsvector('simple', text)`: lowercase lexemes with
+ * positions. Hyphenated compounds yield the whole word plus each part
+ * (numeric parts keep their sign, as PostgreSQL does).
+ */
+export function tokenize(text) {
+    const tokens = [];
+    let position = 0;
+    const push = (lexeme) => {
+        position += 1;
+        tokens.push({ lexeme: lexeme.toLowerCase(), position });
+    };
+    for (const match of String(text ?? "").matchAll(TOKEN_PATTERN)) {
+        const groups = match.groups ?? {};
+        if (groups.email !== undefined || groups.host !== undefined) {
+            push(match[0]);
+            continue;
+        }
+        if (groups.hyphenated !== undefined) {
+            push(match[0]);
+            match[0].split("-").forEach((part, index) => {
+                push(index > 0 && /^\p{N}+$/u.test(part) ? `-${part}` : part);
+            });
+            continue;
+        }
+        push(match[0]);
+    }
+    return tokens;
+}
+/**
+ * Parse `websearch_to_tsquery` syntax: unquoted words AND together,
+ * `"quoted words"` form a phrase, `or` separates alternatives, a leading
+ * `-` negates the following word or phrase. Every word is itself run
+ * through the tokenizer so hyphenated query words become phrases, as in
+ * PostgreSQL. Returns `[]` when the query carries no lexemes.
+ */
+export function parseSearchQuery(query) {
+    const groups = [[]];
+    const source = String(query ?? "");
+    const scanner = /"([^"]*)"?|(\S+)/g;
+    let negateNext = false;
+    for (const match of source.matchAll(scanner)) {
+        const quoted = match[1];
+        const word = match[2];
+        if (quoted !== undefined) {
+            const lexemes = tokenize(quoted).map((token) => token.lexeme);
+            if (lexemes.length)
+                groups[groups.length - 1].push({ phrase: lexemes, negated: negateNext });
+            negateNext = false;
+            continue;
+        }
+        if (word.toLowerCase() === "or") {
+            negateNext = false;
+            if (groups[groups.length - 1].length)
+                groups.push([]);
+            continue;
+        }
+        let body = word;
+        let negated = negateNext;
+        negateNext = false;
+        if (body.startsWith("-") && body.length > 1) {
+            negated = true;
+            body = body.slice(1);
+        }
+        else if (body === "-") {
+            negateNext = true;
+            continue;
+        }
+        const lexemes = tokenize(body).map((token) => token.lexeme);
+        if (!lexemes.length)
+            continue;
+        groups[groups.length - 1].push({ phrase: lexemes, negated });
+    }
+    return groups.filter((group) => group.length);
+}
+function phraseMatches(positions, phrase) {
+    const first = positions.get(phrase[0]);
+    if (!first)
+        return false;
+    if (phrase.length === 1)
+        return true;
+    return first.some((start) => phrase.every((lexeme, offset) => positions.get(lexeme)?.includes(start + offset) ?? false));
+}
+/** Evaluate a parsed query against tokenized text. */
+export function searchTokensMatch(tokens, query) {
+    if (!query.length)
+        return false;
+    const positions = new Map();
+    for (const token of tokens) {
+        const list = positions.get(token.lexeme);
+        if (list)
+            list.push(token.position);
+        else
+            positions.set(token.lexeme, [token.position]);
+    }
+    return query.some((group) => group.every((term) => phraseMatches(positions, term.phrase) !== term.negated));
+}
+/**
+ * `to_tsvector('simple', text) @@ websearch_to_tsquery('simple', query)`.
+ * Whole-token matching: `"dent"` does not match "Dentist". A query with no
+ * lexemes matches nothing, as in PostgreSQL.
+ */
+export function searchMatches(text, query) {
+    return searchTokensMatch(tokenize(text), parseSearchQuery(query));
+}
+/** What PostgreSQL's parser reads as tokens of their own and `tokenize` does
+ * not reproduce: URLs, protocols, hosts with paths and file paths (anything
+ * with a slash), markup tags and entities (which PostgreSQL drops), and
+ * numbers carrying their own sign or a signed exponent. */
+const INEXACT_TEXT = /\/|<[\p{L}!?]|&[#\p{L}\p{N}]+;|(?:^|[^\p{L}\p{N}])[-+]\p{N}|\p{N}[eE][-+]\p{N}/u;
+/**
+ * Whether `tokenize` reads `text` exactly as PostgreSQL's default parser
+ * does, so a search judged here agrees with the platform — false when the
+ * text holds a class this approximation does not reproduce (see the known
+ * gaps above). A live query judges nothing it cannot judge exactly: such a
+ * change makes it read its window afresh instead.
+ */
+export function searchTextIsExact(text) {
+    return !INEXACT_TEXT.test(String(text ?? ""));
+}
+/** Convenience: does a record value match a search over its declared fields? */
+export function recordSearchMatches(searchFields, value, query) {
+    return searchMatches(searchText(searchFields, value), query);
+}
+//# sourceMappingURL=where.js.map

package/bin/versioning.mjs

@@ -0,0 +1,72 @@
+// The one version grammar for creations. terminus-backend src/versioning.rs
+// is the truth: test/contracts/backend-release-version-vectors.json is its
+// cases, rendered by the backend and pinned here, and the tests run every one.
+// Strict MAJOR.MINOR.PATCH, three decimal integers (no leading zeros, no
+// prerelease/build tags in v1), each at most 2147483647. Stored bare
+// ("1.2.0"), displayed with a v ("v1.2.0"); parsing accepts one leading v so
+// typed input normalizes instead of erroring. New creations start at 0.0.1;
+// every publish must be strictly greater than the latest.
+
+export const FIRST_RELEASE_VERSION = "0.0.1";
+
+const SEGMENT = "(0|[1-9][0-9]{0,9})";
+const GRAMMAR = new RegExp(`^${SEGMENT}\\.${SEGMENT}\\.${SEGMENT}$`);
+const MAX_SEGMENT = 2147483647;
+
+// Rust's `str::trim`: Unicode White_Space at either end. Not JS `trim()`,
+// which also strips U+FEFF and keeps U+0085.
+const RUST_WHITESPACE = "[\\t\\n\\v\\f\\r \\u0085\\u00a0\\u1680\\u2000-\\u200a\\u2028\\u2029\\u202f\\u205f\\u3000]+";
+const EDGE_WHITESPACE = new RegExp(`^${RUST_WHITESPACE}|${RUST_WHITESPACE}$`, "g");
+
+/** Parse a strict release version; null when it does not fit the grammar. */
+export function parseReleaseVersion(value) {
+  const trimmed = String(value ?? "").replace(EDGE_WHITESPACE, "");
+  const bare = /^[vV]/.test(trimmed) ? trimmed.slice(1) : trimmed;
+  const match = GRAMMAR.exec(bare);
+  if (!match) return null;
+  const [major, minor, patch] = match.slice(1).map(Number);
+  if (major > MAX_SEGMENT || minor > MAX_SEGMENT || patch > MAX_SEGMENT) return null;
+  return { major, minor, patch, canonical: `${major}.${minor}.${patch}` };
+}
+
+/** Semver ordering over two parsed versions: negative, zero, positive. */
+export function compareReleaseVersions(a, b) {
+  return a.major - b.major || a.minor - b.minor || a.patch - b.patch;
+}
+
+/**
+ * The next patch above a released version: 0.0.1 → 0.0.2, 1.2.3 → 1.2.4.
+ *
+ * The same bump the platform takes when a publish names no version at all
+ * (terminus-backend `publish_release`), so a suggestion made here and a
+ * version chosen there agree. Null at the ceiling, where there is no next.
+ *
+ * Always computed from the RELEASE, never from what the folder happens to
+ * say: a working copy sitting on 0.1.0 under a 0.2.0 release would otherwise
+ * be told to go to 0.1.1, which is refused for the same reason 0.1.0 was.
+ */
+export function nextPatchVersion(value) {
+  const parsed = typeof value === "object" && value !== null ? value : parseReleaseVersion(value);
+  if (!parsed || parsed.patch >= MAX_SEGMENT) return null;
+  return `${parsed.major}.${parsed.minor}.${parsed.patch + 1}`;
+}
+
+/** The v-prefixed display form every surface prints. */
+export function formatReleaseVersion(value) {
+  const parsed = typeof value === "object" && value !== null ? value : parseReleaseVersion(value);
+  if (!parsed) return String(value ?? "");
+  return `v${parsed.canonical ?? `${parsed.major}.${parsed.minor}.${parsed.patch}`}`;
+}
+
+/**
+ * How far a pinned version sits behind a current one:
+ * "none" | "patch" | "minor" | "major". Junk on either side is "none".
+ */
+export function behindClass(pinned, current) {
+  const from = parseReleaseVersion(pinned);
+  const to = parseReleaseVersion(current);
+  if (!from || !to || compareReleaseVersions(to, from) <= 0) return "none";
+  if (to.major !== from.major) return "major";
+  if (to.minor !== from.minor) return "minor";
+  return "patch";
+}