@terminus-ai/cli 0.0.1

package/bin/write-rules.mjs

@@ -0,0 +1,398 @@
+/**
+ * Validate-on-write rules — the `terminus dev` port of the backend evaluator
+ * (terminus-backend src/routes/app_write_rules.rs, capability doors C2), so
+ * an app meets its 422s locally instead of first in production. Semantics
+ * are pinned by the shared conformance vector
+ * test/contracts/app-runtime-v1/write-rules.json: same operators, same
+ * publish-time caps, same anchored full-match `matches`, same shared step
+ * budget, and the same `validate[{index}]: {message}` 422 envelope with
+ * error code "unprocessable". Resets and platform migrations bypass rules
+ * by design — they restore invariants, not break them.
+ */
+
+import { CliError } from "./client.mjs";
+
+export const MAX_WRITE_RULES_PER_COLLECTION = 32;
+export const MAX_WRITE_RULE_NODES = 64;
+export const MAX_WRITE_RULE_DEPTH = 4;
+export const MAX_WRITE_RULE_PATTERN_BYTES = 128;
+export const MAX_WRITE_RULE_MESSAGE_BYTES = 200;
+export const MAX_WRITE_RULE_PATH_DEPTH = 4;
+/** Shared per-write evaluation budget across all of a collection's rules. */
+export const MAX_WRITE_RULE_EVAL_STEPS = 4096;
+
+export const WRITE_RULE_OPERATORS = [
+  "eq", "neq", "lt", "lte", "gt", "gte", "in",
+  "required", "forbidChange", "typeOf", "matches",
+  "anyOf", "allOf", "not",
+];
+const OPERATOR_SET = new Set(WRITE_RULE_OPERATORS);
+
+function unprocessable(message) {
+  const error = new CliError(message);
+  error.status = 422;
+  // `code` is CliError's process-exit concept; the production error
+  // envelope's code rides separately so only coded API errors carry one.
+  error.apiCode = "unprocessable";
+  return error;
+}
+
+function isPlainObject(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+function soleEntry(value) {
+  if (!isPlainObject(value)) return null;
+  const entries = Object.entries(value);
+  return entries.length === 1 ? entries[0] : null;
+}
+
+function validFieldPath(path) {
+  const segments = String(path).split(".");
+  return segments.length >= 1
+    && segments.length <= MAX_WRITE_RULE_PATH_DEPTH
+    && segments.every((segment) => /^[A-Za-z0-9_-]{1,64}$/.test(segment));
+}
+
+/** Anchored full-match, mirroring the backend's `\A(?:pattern)\z` wrapper. */
+function compilePattern(pattern) {
+  try {
+    return new RegExp(`^(?:${pattern})$`);
+  } catch (error) {
+    throw new CliError(`invalid validate pattern: ${error.message}`);
+  }
+}
+
+/** Count AST nodes while validating shape; the count is the publish-time
+ * cost bound. Increment-then-check order matches the backend exactly so
+ * both sides accept and reject the same rule at the 64-node boundary. */
+function validateOperandNode(operand, counter) {
+  counter.nodes += 1;
+  if (counter.nodes > MAX_WRITE_RULE_NODES) {
+    throw new CliError(`validate rules hold at most ${MAX_WRITE_RULE_NODES} nodes`);
+  }
+  if (isPlainObject(operand)) {
+    const entries = Object.entries(operand);
+    if (!entries.length) throw new CliError("validate operands must not be empty objects");
+    if (entries.length > 1) throw new CliError("validate operands carry exactly one key");
+    const [key, value] = entries[0];
+    if (["field", "prior", "len"].includes(key)) {
+      if (typeof value !== "string" || !validFieldPath(value)) {
+        throw new CliError(
+          `validate ${key} paths are dot-paths of at most ${MAX_WRITE_RULE_PATH_DEPTH} short segments`,
+        );
+      }
+      return;
+    }
+    if (key === "actor") {
+      if (value !== "user_id") {
+        throw new CliError("validate actor operands support only 'user_id'");
+      }
+      return;
+    }
+    throw new CliError(`unknown validate operand '${key}'`);
+  }
+  if (Array.isArray(operand)) {
+    if (operand.length > 16) {
+      throw new CliError("validate literal arrays hold at most 16 values");
+    }
+    for (const value of operand) {
+      counter.nodes += 1;
+      if (value !== null && !["string", "number", "boolean"].includes(typeof value)) {
+        throw new CliError("validate literal arrays hold scalars only");
+      }
+    }
+  }
+}
+
+function validateRuleNode(rule, counter, depth) {
+  counter.nodes += 1;
+  if (counter.nodes > MAX_WRITE_RULE_NODES) {
+    throw new CliError(`validate rules hold at most ${MAX_WRITE_RULE_NODES} nodes`);
+  }
+  const entry = soleEntry(rule);
+  if (!entry) throw new CliError("validate rules are single-operator objects");
+  const [operator, operand] = entry;
+  if (!OPERATOR_SET.has(operator)) {
+    throw new CliError(`unknown validate operator '${operator}'`);
+  }
+  if (["anyOf", "allOf", "not"].includes(operator)) {
+    if (depth >= MAX_WRITE_RULE_DEPTH) {
+      throw new CliError(`validate combinators nest at most ${MAX_WRITE_RULE_DEPTH} deep`);
+    }
+    if (operator === "not") {
+      validateRuleNode(operand, counter, depth + 1);
+      return;
+    }
+    if (!Array.isArray(operand) || !operand.length) {
+      throw new CliError(`validate ${operator} takes a non-empty array`);
+    }
+    for (const nested of operand) validateRuleNode(nested, counter, depth + 1);
+    return;
+  }
+  if (["required", "forbidChange"].includes(operator)) {
+    if (!Array.isArray(operand) || !operand.length) {
+      throw new CliError(`validate ${operator} takes a non-empty array of field paths`);
+    }
+    if (operand.length > 16) {
+      throw new CliError(`validate ${operator} lists at most 16 fields`);
+    }
+    for (const field of operand) {
+      counter.nodes += 1;
+      if (typeof field !== "string" || !validFieldPath(field)) {
+        throw new CliError(`validate ${operator} entries are dot-paths`);
+      }
+    }
+    return;
+  }
+  if (operator === "typeOf") {
+    if (!Array.isArray(operand) || operand.length !== 2) {
+      throw new CliError("validate typeOf takes [operand, type]");
+    }
+    validateOperandNode(operand[0], counter);
+    if (!["string", "number", "boolean", "array", "object", "null"].includes(operand[1])) {
+      throw new CliError(
+        "validate typeOf types are string, number, boolean, array, object, or null",
+      );
+    }
+    return;
+  }
+  if (operator === "matches") {
+    if (!Array.isArray(operand) || operand.length !== 2) {
+      throw new CliError("validate matches takes [operand, pattern]");
+    }
+    validateOperandNode(operand[0], counter);
+    if (typeof operand[1] !== "string") {
+      throw new CliError("validate matches patterns are strings");
+    }
+    if (Buffer.byteLength(operand[1]) > MAX_WRITE_RULE_PATTERN_BYTES) {
+      throw new CliError(`validate patterns are at most ${MAX_WRITE_RULE_PATTERN_BYTES} bytes`);
+    }
+    compilePattern(operand[1]);
+    return;
+  }
+  if (operator === "in") {
+    if (!Array.isArray(operand) || operand.length !== 2) {
+      throw new CliError("validate in takes [operand, [values]]");
+    }
+    validateOperandNode(operand[0], counter);
+    if (!Array.isArray(operand[1])) {
+      throw new CliError("validate in takes a literal array of allowed values");
+    }
+    validateOperandNode(operand[1], counter);
+    return;
+  }
+  // Binary comparisons.
+  if (!Array.isArray(operand) || operand.length !== 2) {
+    throw new CliError(`validate ${operator} takes [left, right]`);
+  }
+  validateOperandNode(operand[0], counter);
+  validateOperandNode(operand[1], counter);
+}
+
+/** Normalize + bound a collection's `validate` section at definition time
+ * (the backend's `normalized_write_rules`). Returns undefined when there is
+ * nothing to enforce. */
+export function normalizedWriteRules(raw) {
+  if (raw === undefined || raw === null) return undefined;
+  if (!Array.isArray(raw)) {
+    throw new CliError("collection validate must be an array of { rule, message }");
+  }
+  if (!raw.length) return undefined;
+  if (raw.length > MAX_WRITE_RULES_PER_COLLECTION) {
+    throw new CliError(
+      `a collection declares at most ${MAX_WRITE_RULES_PER_COLLECTION} validate rules`,
+    );
+  }
+  for (const entry of raw) {
+    if (!isPlainObject(entry)) {
+      throw new CliError("validate entries are { rule, message } objects");
+    }
+    for (const key of Object.keys(entry)) {
+      if (!["rule", "message"].includes(key)) {
+        throw new CliError(`unknown validate entry field '${key}'`);
+      }
+    }
+    const message = typeof entry.message === "string" ? entry.message : "";
+    if (!message || Buffer.byteLength(message) > MAX_WRITE_RULE_MESSAGE_BYTES) {
+      throw new CliError(`validate messages are 1..=${MAX_WRITE_RULE_MESSAGE_BYTES} characters`);
+    }
+    if (!("rule" in entry)) throw new CliError("validate entries need a rule");
+    validateRuleNode(entry.rule, { nodes: 0 }, 0);
+  }
+  return structuredClone(raw);
+}
+
+/** Dot-path lookup distinguishing missing (undefined) from explicit null,
+ * the way the backend's Option<&Value> does. */
+function lookup(root, path) {
+  let current = root;
+  for (const segment of String(path).split(".")) {
+    if (!isPlainObject(current) || !Object.hasOwn(current, segment)) return undefined;
+    current = current[segment];
+  }
+  return current;
+}
+
+/** serde_json Value equality: deep, object-key-order-insensitive. */
+function deepEqual(left, right) {
+  if (left === right) return true;
+  if (Array.isArray(left) && Array.isArray(right)) {
+    return left.length === right.length
+      && left.every((value, index) => deepEqual(value, right[index]));
+  }
+  if (isPlainObject(left) && isPlainObject(right)) {
+    const keys = Object.keys(left);
+    return keys.length === Object.keys(right).length
+      && keys.every((key) => Object.hasOwn(right, key) && deepEqual(left[key], right[key]));
+  }
+  return false;
+}
+
+/** Rust String ordering: by Unicode code point (equals UTF-8 byte order),
+ * not UTF-16 code units and not collation. */
+function compareCodePoints(left, right) {
+  const a = [...left];
+  const b = [...right];
+  const shared = Math.min(a.length, b.length);
+  for (let index = 0; index < shared; index += 1) {
+    const delta = a[index].codePointAt(0) - b[index].codePointAt(0);
+    if (delta) return delta < 0 ? -1 : 1;
+  }
+  return a.length === b.length ? 0 : a.length < b.length ? -1 : 1;
+}
+
+function step(context) {
+  context.steps += 1;
+  if (context.steps > MAX_WRITE_RULE_EVAL_STEPS) {
+    throw unprocessable("validate rules exceeded their evaluation budget");
+  }
+}
+
+function resolveOperand(context, operand) {
+  step(context);
+  const entry = soleEntry(operand);
+  if (entry) {
+    const [key, value] = entry;
+    const path = typeof value === "string" ? value : "";
+    if (key === "field") return lookup(context.incoming, path) ?? null;
+    if (key === "prior") return lookup(context.prior, path) ?? null;
+    if (key === "len") {
+      const target = lookup(context.incoming, path);
+      if (typeof target === "string") return [...target].length;
+      if (Array.isArray(target)) return target.length;
+      return null;
+    }
+    if (key === "actor") return context.actorUserId;
+    return null;
+  }
+  return operand;
+}
+
+function holds(context, rule) {
+  step(context);
+  const entry = soleEntry(rule);
+  if (!entry) return false;
+  const [operator, operand] = entry;
+  if (operator === "anyOf") {
+    for (const nested of Array.isArray(operand) ? operand : []) {
+      if (holds(context, nested)) return true;
+    }
+    return false;
+  }
+  if (operator === "allOf") {
+    for (const nested of Array.isArray(operand) ? operand : []) {
+      if (!holds(context, nested)) return false;
+    }
+    return true;
+  }
+  if (operator === "not") return !holds(context, operand);
+  if (operator === "required") {
+    return (Array.isArray(operand) ? operand : []).every((field) => {
+      const value = lookup(context.incoming, typeof field === "string" ? field : "");
+      return value !== undefined && value !== null;
+    });
+  }
+  if (operator === "forbidChange") {
+    // Nothing stored yet: creation sets immutable fields.
+    if (context.prior === null) return true;
+    return (Array.isArray(operand) ? operand : []).every((field) => {
+      const path = typeof field === "string" ? field : "";
+      const incoming = lookup(context.incoming, path);
+      const prior = lookup(context.prior, path);
+      if (incoming === undefined || prior === undefined) return incoming === prior;
+      return deepEqual(incoming, prior);
+    });
+  }
+  if (operator === "typeOf") {
+    if (!Array.isArray(operand) || operand.length !== 2) return false;
+    const value = resolveOperand(context, operand[0]);
+    if (operand[1] === "string") return typeof value === "string";
+    if (operand[1] === "number") return typeof value === "number";
+    if (operand[1] === "boolean") return typeof value === "boolean";
+    if (operand[1] === "array") return Array.isArray(value);
+    if (operand[1] === "object") return isPlainObject(value);
+    if (operand[1] === "null") return value === null;
+    return false;
+  }
+  if (operator === "matches") {
+    if (!Array.isArray(operand) || operand.length !== 2) return false;
+    const value = resolveOperand(context, operand[0]);
+    if (typeof value !== "string" || typeof operand[1] !== "string") return false;
+    // Charged against the step budget by input size so a rule set cannot
+    // multiply large-string scans for free.
+    context.steps += Math.floor(Buffer.byteLength(value) / 64);
+    return compilePattern(operand[1]).test(value);
+  }
+  if (operator === "in") {
+    if (!Array.isArray(operand) || operand.length !== 2) return false;
+    const value = resolveOperand(context, operand[0]);
+    return Array.isArray(operand[1])
+      && operand[1].some((allowed) => deepEqual(allowed, value));
+  }
+  if (["eq", "neq", "lt", "lte", "gt", "gte"].includes(operator)) {
+    if (!Array.isArray(operand) || operand.length !== 2) return false;
+    const left = resolveOperand(context, operand[0]);
+    const right = resolveOperand(context, operand[1]);
+    if (operator === "eq") return deepEqual(left, right);
+    if (operator === "neq") return !deepEqual(left, right);
+    let order = null;
+    if (typeof left === "number" && typeof right === "number") {
+      order = left < right ? -1 : left > right ? 1 : 0;
+    } else if (typeof left === "string" && typeof right === "string") {
+      order = compareCodePoints(left, right);
+    }
+    if (order === null) return false;
+    if (operator === "lt") return order < 0;
+    if (operator === "lte") return order <= 0;
+    if (operator === "gt") return order > 0;
+    return order >= 0;
+  }
+  return false;
+}
+
+/** Enforce a collection's validate rules for one write (the backend's
+ * `enforce_write_rules`, called at every record-write door). `incoming` is
+ * the record as it will be stored; `prior` the stored record value, when
+ * any. Violations throw the production 422: code "unprocessable", message
+ * `validate[{index}]: {message}`. */
+export function enforceWriteRules(declaration, actorUserId, prior, incoming) {
+  const rules = declaration?.validate;
+  if (!Array.isArray(rules)) return;
+  const context = {
+    incoming,
+    prior: prior ?? null,
+    actorUserId: String(actorUserId),
+    steps: 0,
+  };
+  for (const [index, entry] of rules.entries()) {
+    const rule = isPlainObject(entry) ? entry.rule : undefined;
+    if (rule === undefined) continue;
+    if (!holds(context, rule)) {
+      const message = typeof entry.message === "string"
+        ? entry.message
+        : "record violates a collection rule";
+      throw unprocessable(`validate[${index}]: ${message}`);
+    }
+  }
+}

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@terminus-ai/cli",
+  "version": "0.0.1",
+  "description": "Terminus CLI (`terminus`): search and use skills, and develop, run, and publish apps, services, and agents on the Terminus platform.",
+  "license": "MIT",
+  "type": "module",
+  "homepage": "https://www.terminus.build",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Terminus-Intelligence/terminus-cli.git"
+  },
+  "bin": {
+    "terminus": "bin/terminus.js",
+    "terminus-cli": "bin/terminus.js"
+  },
+  "files": [
+    "bin",
+    "README.md"
+  ],
+  "exports": {
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=22.16.0"
+  },
+  "scripts": {
+    "build": "npm pack --dry-run",
+    "prepublishOnly": "npm test",
+    "test": "node --import ./test/helpers/offline.mjs --test \"test/*.test.mjs\""
+  },
+  "optionalDependencies": {
+    "@terminus-ai/agentd-darwin-arm64": "0.0.1",
+    "@terminus-ai/agentd-darwin-x64": "0.0.1",
+    "@terminus-ai/agentd-linux-arm64": "0.0.1",
+    "@terminus-ai/agentd-linux-x64": "0.0.1"
+  }
+}