@uicast/core 0.0.1-beta.1 → 0.0.1

package/src/expr/evaluate.ts

@@ -1,74 +0,0 @@
-import type { StandardToolV0 } from "standard-tool";
-import type { ValueSource } from "../types";
-import { EntryError } from "../entry-error";
-import { ALLOWED_GLOBALS } from "./globals";
-import { SaferEval, SaferEvalError } from "./safer-eval";
-
-const saferEval = new SaferEval({
-  allowGlobals: ALLOWED_GLOBALS,
-  enforceAllowlist: true,
-});
-
-// Every scopes.X.Y path an expression reads, via the shared SaferEval singleton
-// (so extractDeps doesn't reach into the evaluator). Same parse cache as eval().
-export const getScopeReads = (expr: string): string[] =>
-  saferEval.scopeReads(expr);
-
-// Classify an evaluation failure by provenance: SaferEval's own rejections
-// carry their reason (syntax / policy / unknown identifier); an EntryError
-// passes through (a host function already tagged it); anything else threw
-// while the compiled expression ran.
-const wrapEvalError = (err: unknown): EntryError => {
-  if (EntryError.is(err)) return err;
-  if (err instanceof SaferEvalError) return EntryError.wrap(err, err.reason);
-  return EntryError.wrap(err, "expression-runtime");
-};
-
-// Evaluate a ValueSource: a `literal` is returned as-is, an `expr` runs through
-// SaferEval against context + host functions. Returns unknown — an async expr
-// resolves to a Promise (callers check `value instanceof Promise`). `functions`
-// (a StandardToolV0[]) are spread after context, so a host fn wins a name clash.
-// Every failure surfaces as a classified EntryError.
-export const evaluate = (
-  expr: ValueSource,
-  context: Record<string, unknown>,
-  options?: { functions?: StandardToolV0[]; allowedGlobals?: string[] },
-): unknown => {
-  if ("literal" in expr) return expr.literal;
-  if (!expr.expr) return null;
-  const functions = Object.fromEntries(
-    (options?.functions ?? []).map((tool) => [
-      tool.name,
-      // This closure is the engine/host boundary: anything escaping
-      // `tool.execute` is host code failing — unless the host already threw a
-      // classified EntryError itself (e.g. "invalid-arguments"), which wrap()
-      // passes through.
-      (input: unknown) => {
-        try {
-          const result = tool.execute(input);
-          return result instanceof Promise
-            ? result.catch((err) => {
-                throw EntryError.wrap(err, "host-function");
-              })
-            : result;
-        } catch (err) {
-          throw EntryError.wrap(err, "host-function");
-        }
-      },
-    ]),
-  );
-  try {
-    const result = saferEval.eval(
-      expr.expr,
-      { ...context, ...functions },
-      options?.allowedGlobals,
-    );
-    return result instanceof Promise
-      ? result.catch((err) => {
-          throw wrapEvalError(err);
-        })
-      : result;
-  } catch (err) {
-    throw wrapEvalError(err);
-  }
-};

package/src/expr/extract-deps.ts

@@ -1,32 +0,0 @@
-import { type ComponentEntry, isComponentListEntry } from "../types";
-import { getScopeReads } from "./evaluate";
-
-// Entries are immutable, so cached reads never go stale; WeakMap so a dropped
-// entry can be collected.
-const cache = new WeakMap<ComponentEntry, string[]>();
-
-// The reactive scopes.X.Y paths an entry reads, across its props, hidden, and each
-// expressions — the renderer subscribes to these. (seed run once and
-// callbacks read at fire time, so neither is scanned.)
-export function extractDeps(entry: ComponentEntry): string[] {
-  const cached = cache.get(entry);
-  if (cached) return cached;
-
-  const out = new Set<string>();
-
-  if (entry.props && "expr" in entry.props && entry.props.expr) {
-    for (const r of getScopeReads(entry.props.expr)) out.add(r);
-  }
-  if (entry.hidden) {
-    for (const r of getScopeReads(entry.hidden)) out.add(r);
-  }
-
-  // `each` reads both the list and anything its filter touches (e.g. a search term).
-  if (isComponentListEntry(entry)) {
-    for (const r of getScopeReads(entry.each)) out.add(r);
-  }
-
-  const result = [...out];
-  cache.set(entry, result);
-  return result;
-}

package/src/expr/globals.ts

@@ -1,118 +0,0 @@
-// Which JavaScript globals an expression can see. The engine enforces an
-// allowlist (safer-eval.ts): a free identifier that is neither an allowed global
-// nor an injected context name is rejected before the expression runs.
-// ALLOWED_GLOBALS is that list — also handed to SaferEval as allowGlobals and
-// shown to the LLM in the prompt. GLOBALS_TO_SHADOW are bound to undefined as a
-// second line of defence, so an allowed-by-mistake reference still stays inert.
-
-/** Globals an expression may reference. Every entry is also usable with `new`. */
-export const ALLOWED_GLOBALS: string[] = [
-  // Namespaces / utilities
-  "Math",
-  "JSON",
-  "Intl",
-  "Object",
-  "Array",
-  // Coercion (use as calls — `new Number(x)` etc. boxes the value)
-  "Number",
-  "String",
-  "Boolean",
-  "parseInt",
-  "parseFloat",
-  // Predicates / constants
-  "isNaN",
-  "isFinite",
-  "undefined",
-  "NaN",
-  "Infinity",
-  // URI helpers
-  "encodeURIComponent",
-  "decodeURIComponent",
-  "encodeURI",
-  "decodeURI",
-  // Constructors & async
-  "Date",
-  "Map",
-  "Set",
-  "RegExp",
-  "URL",
-  "URLSearchParams",
-  "Promise",
-  "BigInt",
-  // Error constructors
-  "Error",
-  "TypeError",
-  "RangeError",
-  "SyntaxError",
-  "ReferenceError",
-  "EvalError",
-  "URIError",
-  "AggregateError",
-];
-
-// Capability globals shadowed to undefined. (`eval` / `arguments` can't be param
-// names in strict mode — blocked in validate.ts instead.)
-export const GLOBALS_TO_SHADOW: string[] = [
-  // Global objects
-  "globalThis",
-  "self",
-  "window",
-  "global",
-  "document",
-  "navigator",
-  "location",
-  "history",
-  "localStorage",
-  "sessionStorage",
-  "indexedDB",
-
-  // Network / IO
-  "fetch",
-  "XMLHttpRequest",
-  "WebSocket",
-  "EventSource",
-  "Worker",
-  "SharedWorker",
-  "ServiceWorker",
-  "importScripts",
-  // Fire a network request via `.src` — an exfiltration channel even with fetch
-  // shadowed.
-  "Image",
-  "Audio",
-
-  // Code execution
-  "Function",
-  "WebAssembly", // runs arbitrary code
-  "setTimeout",
-  "setInterval",
-  "setImmediate",
-  "requestAnimationFrame",
-  "requestIdleCallback",
-  "queueMicrotask",
-
-  // Process / non-browser runtimes
-  "process",
-  "require",
-  "module",
-  "exports",
-  "__dirname",
-  "__filename",
-  "Buffer",
-  "Deno", // runtime god-object (fs/net/env) outside a browser
-  "Bun",
-
-  // DOM
-  "alert",
-  "confirm",
-  "prompt",
-  "close",
-  "open",
-  "print",
-  "postMessage",
-
-  // Constructors that can escape
-  "Proxy",
-  "Reflect",
-  "SharedArrayBuffer",
-  "Atomics",
-];

package/src/expr/safer-eval.ts

@@ -1,233 +0,0 @@
-import * as acorn from "acorn";
-import {
-  containsAwait,
-  extractFreeIdentifiers,
-  extractScopeReads,
-} from "./analyze";
-import { GLOBALS_TO_SHADOW } from "./globals";
-import { SaferEvalError, validateNode } from "./validate";
-
-// Compiles and runs the expressions validate.ts approves: parse + analyse once
-// (cached), compile to a Function (AsyncFunction when the expr uses `await`),
-// shadow ambient globals as undefined params, run in-realm so Proxy state works.
-// Guardrail, not a sandbox — see the Expressions docs page, § Safety.
-
-// Re-exported from validate.ts for callers of this module.
-export { SaferEvalError };
-
-// The AsyncFunction constructor, for expressions that use `await`.
-const AsyncFunction = Object.getPrototypeOf(async () => {})
-  .constructor as typeof Function;
-
-type CacheEntry = {
-  isAsync: boolean;
-  scopeReads: string[];
-  freeIds: string[];
-  // Built lazily on first compile(); validate()/scopeReads() leave it unset.
-  fn?: (context: Record<string, unknown>) => unknown;
-};
-
-export class SaferEval {
-  #cache = new Map<string, CacheEntry>();
-  #maxCacheSize: number;
-  #shadowParams: string[];
-  #allowGlobals: Set<string>;
-  #enforceAllowlist: boolean;
-
-  constructor(
-    options: {
-      maxCacheSize?: number;
-      extraGlobalsToShadow?: string[];
-      allowGlobals?: string[];
-      enforceAllowlist?: boolean;
-    } = {},
-  ) {
-    const {
-      maxCacheSize = 500,
-      extraGlobalsToShadow = [],
-      allowGlobals = [],
-      enforceAllowlist = false,
-    } = options;
-
-    this.#maxCacheSize = maxCacheSize;
-    this.#enforceAllowlist = enforceAllowlist;
-
-    const allowSet = new Set(allowGlobals);
-    this.#allowGlobals = allowSet;
-    this.#shadowParams = [...GLOBALS_TO_SHADOW, ...extraGlobalsToShadow].filter(
-      (g) => !allowSet.has(g),
-    );
-  }
-
-  // Parse + validate without running. Throws SaferEvalError if invalid; returns
-  // isAsync + scopeReads and caches the analysis (compile() builds the fn later).
-  validate(expression: string): {
-    isAsync: boolean;
-    scopeReads: string[];
-    freeIds: string[];
-  } {
-    if (typeof expression !== "string") {
-      throw new SaferEvalError("Expression must be a string", "expression-syntax");
-    }
-
-    const trimmed = expression.trim();
-    if (!trimmed) {
-      throw new SaferEvalError("Expression cannot be empty", "expression-syntax");
-    }
-
-    const cached = this.#cache.get(expression);
-    if (cached) {
-      return {
-        isAsync: cached.isAsync,
-        scopeReads: cached.scopeReads,
-        freeIds: cached.freeIds,
-      };
-    }
-
-    // Parse as `"use strict"; void (expr)`: void(...) forces expression context
-    // (so `{...}` is an object literal, not a block), and strict mode rejects
-    // sloppy-only constructs (octal, `with`, dup params) here, not at compile.
-    const wrapper = `"use strict"; void (${trimmed})`;
-    let ast: acorn.Program;
-    try {
-      ast = acorn.parse(wrapper, {
-        ecmaVersion: 2022,
-        sourceType: "script",
-        allowAwaitOutsideFunction: true,
-      });
-    } catch (e: unknown) {
-      throw new SaferEvalError(
-        `Syntax error: ${e instanceof Error ? e.message : String(e)}. Expression: ${expression}`,
-        "expression-syntax",
-      );
-    }
-
-    validateNode(ast);
-
-    const analysis = {
-      isAsync: containsAwait(ast),
-      scopeReads: extractScopeReads(ast),
-      freeIds: extractFreeIdentifiers(ast),
-    };
-
-    // Cache the analysis (no fn yet); evict oldest when full.
-    if (this.#cache.size >= this.#maxCacheSize) {
-      const firstKey = this.#cache.keys().next().value;
-      if (firstKey !== undefined) this.#cache.delete(firstKey);
-    }
-    this.#cache.set(expression, { ...analysis });
-
-    return analysis;
-  }
-
-  // Compile to a reusable fn (returns a Promise if the expr uses `await`).
-  compile(expression: string): (context: Record<string, unknown>) => unknown {
-    const { isAsync } = this.validate(expression);
-    const entry = this.#cache.get(expression);
-    if (!entry) {
-      // Unreachable — validate() just inserted this entry.
-      throw new SaferEvalError(
-        `Cache entry missing for expression: ${expression}`,
-      );
-    }
-    if (entry.fn) return entry.fn;
-
-    const expr = expression.trim();
-    const Ctor = isAsync ? AsyncFunction : Function;
-
-    // Single-slot cache: new Ctor bakes in the param names (context keys ∪ shadow
-    // params), so it recompiles only if the context shape changes — which it
-    // doesn't in practice (a given expr always sees the same keys).
-    let cachedSig: string | undefined;
-    let cachedFn: ((...args: unknown[]) => unknown) | undefined;
-
-    const evaluator = (context: Record<string, unknown>) => {
-      const contextKeys = Object.keys(context);
-      const sig = contextKeys.join("\u0000");
-      if (sig !== cachedSig) {
-        // Context keys become params; shadow params follow, bound to undefined.
-        const allParams = [...contextKeys, ...this.#shadowParams];
-        try {
-          cachedFn = new Ctor(
-            ...allParams,
-            `"use strict"; return (${expr})`,
-          ) as (...args: unknown[]) => unknown;
-        } catch (e: unknown) {
-          // Parsed but won't compile — surface as SaferEvalError, not a raw one.
-          throw new SaferEvalError(
-            `Failed to compile expression: ${
-              e instanceof Error ? e.message : String(e)
-            }. Expression: ${expression}`,
-            "expression-syntax",
-          );
-        }
-        cachedSig = sig;
-      }
-
-      // Args match allParams: context values (Object.keys order) then shadow fills.
-      const allArgs = [
-        ...Object.values(context),
-        ...new Array(this.#shadowParams.length).fill(undefined),
-      ];
-      return (cachedFn as (...args: unknown[]) => unknown)(...allArgs);
-    };
-
-    entry.fn = evaluator;
-    return evaluator;
-  }
-
-  isAsync(expression: string): boolean {
-    const cached = this.#cache.get(expression);
-    if (cached) return cached.isAsync;
-    return this.validate(expression).isAsync;
-  }
-
-  // Every `scopes.X.Y` path the expression reads — the renderer auto-subscribes
-  // to these instead of the LLM writing a deps array.
-  scopeReads(expression: string): string[] {
-    const cached = this.#cache.get(expression);
-    if (cached) return cached.scopeReads;
-    return this.validate(expression).scopeReads;
-  }
-
-  // Allowlist gate: every free identifier must be an injected context name, a
-  // base allowed global, or one the host opted into via allowedGlobals.
-  #checkAllowlist(
-    freeIds: string[],
-    contextKeys: string[],
-    allowedGlobals: string[],
-  ): void {
-    const allowed = new Set([
-      ...contextKeys,
-      ...this.#allowGlobals,
-      ...allowedGlobals,
-    ]);
-    for (const id of freeIds) {
-      if (!allowed.has(id)) {
-        // The expression named something that doesn't exist here — an
-        // unregistered function or a global outside the allowlist.
-        throw new SaferEvalError(
-          `"${id}" is not available in expressions`,
-          "unknown-reference",
-        );
-      }
-    }
-  }
-
-  eval(
-    expression: string,
-    context: Record<string, unknown> = {},
-    allowedGlobals: string[] = [],
-  ): unknown {
-    if (this.#enforceAllowlist) {
-      const { freeIds } = this.validate(expression);
-      this.#checkAllowlist(freeIds, Object.keys(context), allowedGlobals);
-    }
-    const evaluator = this.compile(expression);
-    return evaluator(context);
-  }
-
-  clearCache(): void {
-    this.#cache.clear();
-  }
-}

package/src/expr/validate.ts

@@ -1,149 +0,0 @@
-import type * as acorn from "acorn";
-import { isNode } from "./ast-utils";
-
-// Expression validation — the guardrail. Walks a parsed expression and throws on
-// anything that shouldn't run; safer-eval.ts compiles only what this approves.
-// Guardrail, NOT a sandbox: a computed key (`obj["con"+"structor"]`) escapes it.
-// Full threat model: the Expressions docs page, § Safety.
-
-// Which EntryError reason an evaluation failure maps to. Defaults to
-// "sandbox-violation" (every policy rejection in this file); the parse and
-// allowlist sites in safer-eval.ts override it.
-export type SaferEvalErrorReason =
-  | "expression-syntax"
-  | "sandbox-violation"
-  | "unknown-reference";
-
-export class SaferEvalError extends Error {
-  readonly reason: SaferEvalErrorReason;
-
-  constructor(
-    message: string,
-    reason: SaferEvalErrorReason = "sandbox-violation",
-  ) {
-    super(message);
-    this.name = "SaferEvalError";
-    this.reason = reason;
-  }
-}
-
-// `eval` / `arguments` can't be shadowed as strict-mode params, so reject them as
-// references here instead (the rest are shadowed — see GLOBALS_TO_SHADOW).
-const FORBIDDEN_IDENTIFIERS = new Set(["eval", "arguments"]);
-
-// Most dangerous syntax never reaches this walk: every expression is parsed as
-// `"use strict"; void (EXPR)`, so a top-level statement / declaration / `with` /
-// octal / import is a syntax error. What survives, to reject by hand, is below.
-
-// Forbidden everywhere, even in a function body: dynamic `import()` loads code,
-// and `import.meta` / `new.target` (MetaProperty) reach host / constructor
-// internals. Keywords, so shadowing can't touch them — block structurally.
-const FORBIDDEN_EXPRESSIONS = new Set(["ImportExpression", "MetaProperty"]);
-
-// Forbidden as the whole expression (which must be one pure value); fine inside a
-// callback body where imperative code is allowed.
-const BODY_ONLY_EXPRESSIONS = new Set([
-  "AssignmentExpression", // x = 1, x += 1
-  "UpdateExpression", // x++, --x
-  "SequenceExpression", // a, b — comma operator
-]);
-
-// Escape-hatch property names: `.constructor` reaches the Function constructor,
-// `.__proto__` the prototype chain. Only static keys are caught; a computed key
-// escapes (the guardrail gap — banning it would ban all `arr[i]` access).
-const FORBIDDEN_PROPERTIES = new Set([
-  "constructor",
-  "__proto__",
-  "prototype",
-  "__defineGetter__",
-  "__defineSetter__",
-  "__lookupGetter__",
-  "__lookupSetter__",
-]);
-
-// Recursively walk the parsed expression, throwing on anything disallowed.
-// insideFunctionBody flips once inside an arrow / function body, where the
-// BODY_ONLY_EXPRESSIONS become legal. Entry point is acorn's Program node.
-export function validateNode(
-  node: acorn.AnyNode | null | undefined,
-  insideFunctionBody = false,
-): void {
-  if (!node || typeof node !== "object") return;
-
-  // The wrapped program must hold exactly one expression (the filter drops the
-  // "use strict" directive). More than one means the expr smuggled a `)` to break
-  // out of `void (...)` — e.g. `1); evil(); (2`.
-  if (node.type === "Program") {
-    const statements = node.body.filter(
-      (s) => !(s.type === "ExpressionStatement" && s.directive),
-    );
-    if (statements.length !== 1) {
-      throw new SaferEvalError(
-        `Expression must be a single expression, got ${statements.length} statements`,
-      );
-    }
-    validateNode(statements[0]);
-    return;
-  }
-
-  // Dynamic import / meta-properties: never allowed, not even in a body.
-  if (FORBIDDEN_EXPRESSIONS.has(node.type)) {
-    throw new SaferEvalError(`"${node.type}" is not allowed in expressions`);
-  }
-
-  // Assignment / update / comma: allowed in a callback body, not as the whole expr.
-  if (BODY_ONLY_EXPRESSIONS.has(node.type) && !insideFunctionBody) {
-    throw new SaferEvalError(
-      `"${node.type}" is only allowed inside a function body, not as the whole expression`,
-    );
-  }
-
-  // Tagged templates invoke an arbitrary tag function.
-  if (node.type === "TaggedTemplateExpression") {
-    throw new SaferEvalError("Tagged template literals are not allowed");
-  }
-
-  // Static access to escape-hatch properties; dynamic keys slip past.
-  if (node.type === "MemberExpression") {
-    const { property, computed } = node;
-    const staticKey =
-      !computed && property.type === "Identifier"
-        ? property.name
-        : computed &&
-            property.type === "Literal" &&
-            typeof property.value === "string"
-          ? property.value
-          : null;
-    if (staticKey !== null && FORBIDDEN_PROPERTIES.has(staticKey)) {
-      throw new SaferEvalError(`Access to "${staticKey}" is not allowed`);
-    }
-  }
-
-  // `eval` / `arguments` in reference position (the recursion below skips a
-  // non-computed member's `.property`, so a harmless `row.arguments` isn't hit).
-  if (node.type === "Identifier" && FORBIDDEN_IDENTIFIERS.has(node.name)) {
-    throw new SaferEvalError(`Access to "${node.name}" is not allowed`);
-  }
-
-  // Recurse. Two carries: descending into a function `body` sets
-  // insideFunctionBody for the subtree; a non-computed member's `.property` is a
-  // name already checked, so skip it (a computed `obj[eval]` is not skipped).
-  const fields = node as unknown as Record<string, unknown>;
-  const isFunction =
-    node.type === "ArrowFunctionExpression" ||
-    node.type === "FunctionExpression";
-  for (const key of Object.keys(node)) {
-    if (key === "type" || key === "start" || key === "end") continue;
-    if (node.type === "MemberExpression" && !node.computed && key === "property")
-      continue;
-    const child = fields[key];
-    const childInside = insideFunctionBody || (isFunction && key === "body");
-    if (Array.isArray(child)) {
-      for (const c of child) {
-        if (isNode(c)) validateNode(c, childInside);
-      }
-    } else if (isNode(child)) {
-      validateNode(child, childInside);
-    }
-  }
-}

package/src/index.ts

@@ -1,28 +0,0 @@
-// uicast public API. Prompt-partial builders live in uicast/prompt.
-
-export { createComponentDefinition } from "./def/create-component-definition";
-
-export { evaluate } from "./expr/evaluate";
-export { extractDeps } from "./expr/extract-deps";
-
-export {
-  EntryError,
-  type EntryErrorReason,
-  type EntryFault,
-} from "./entry-error";
-
-export { createProxyScope, type ReactiveProxy } from "./scope/create-proxy-scope";
-export { parseScope } from "./scope/parse-scope";
-
-export { buildElementsById } from "./utils/utils";
-
-export { streamJsonLines } from "./stream/stream-json-lines";
-
-export {
-  type ComponentEntry,
-  type ComponentListEntry,
-  type ComponentDefinition,
-  type CombinedSpec,
-  isComponentEntry,
-  isComponentListEntry,
-} from "./types";

package/src/prompt/get-common-instructions-partial-prompt.ts

@@ -1,20 +0,0 @@
-import INSTRUCTIONS from "./md/INSTRUCTIONS.json" with { type: "json" };
-
-/** No options yet — the type is reserved so the signature can grow without breaking callers. */
-export type CommonInstructionsPromptOptions = Record<string, never>;
-
-/**
- * The LLM-facing instruction block — the contract authored in
- * `md/INSTRUCTIONS.md` and imported here as a JSON string via the md-to-json
- * pipeline (`npm run md-to-json` regenerates the `.json` sibling after edits).
- *
- * A partial-prompt primitive: the consuming app's prompt assembler composes
- * this — alongside the other `get*PartialPrompt` builders — into the full
- * system prompt it sends to the generation LLM. core ships the pieces; the app
- * owns the assembly.
- */
-export function getCommonInstructionsPartialPrompt(
-	_options: CommonInstructionsPromptOptions = {},
-): string {
-	return INSTRUCTIONS;
-}