@jxsuite/compiler 0.35.0 → 1.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jxsuite/compiler",
-  "version": "0.35.0",
+  "version": "1.1.0",
   "description": "Jx static HTML compiler, island detector, and site builder",
   "license": "MIT",
   "repository": {
@@ -19,15 +19,17 @@
   "type": "module",
   "exports": {
     ".": "./src/compiler.ts",
-    "./content-loader": "./src/site/content-loader.ts",
     "./format-host": "./src/site/format-host.ts",
+    "./project-sections": "./src/site/project-sections.ts",
+    "./schema-command": "./src/site/schema-command.ts",
     "./context-injection": "./src/site/context-injection.ts",
     "./head-merger": "./src/site/head-merger.ts",
     "./layout-resolver": "./src/site/layout-resolver.ts",
     "./pages-discovery": "./src/site/pages-discovery.ts",
     "./site": "./src/site/site-build.ts",
     "./site-loader": "./src/site/site-loader.ts",
-    "./types": "./src/types.ts"
+    "./types": "./src/types.ts",
+    "./db-push": "./src/site/db-push.ts"
   },
   "publishConfig": {
     "provenance": true
@@ -42,14 +44,16 @@
     "upgrade": "bunx npm-check-updates -u && bun install"
   },
   "dependencies": {
-    "@apidevtools/json-schema-ref-parser": "^15.4.0",
-    "@jxsuite/parser": "^0.35.1",
-    "@jxsuite/runtime": "^0.34.2",
-    "@jxsuite/schema": "^0.35.0",
+    "@apidevtools/json-schema-ref-parser": "^15.5.0",
+    "@jxsuite/create": "^1.1.0",
+    "@jxsuite/runtime": "^1.1.0",
+    "@jxsuite/schema": "^1.1.0",
     "sharp": "^0.35.3"
   },
   "devDependencies": {
     "@happy-dom/global-registrator": "^20.10.6",
+    "@jxsuite/connector": "^0.3.0",
+    "@jxsuite/parser": "^1.1.0",
     "@types/mdast": "^4.0.4"
   }
 }

package/src/cli.ts

@@ -2,12 +2,13 @@
 /**
  * Jx — Unified CLI for the Jx platform
  *
- * Commands: jx build [project-root] [--verbose] [--no-clean]
+ * Commands: jx build [project-root] [--verbose] [--no-clean] jx schema [project-root] jx validate
+ * [project-root]
  *
  * @module jx-cli
  */
 
-import { resolve } from "node:path";
+import { relative, resolve } from "node:path";
 
 // The CLI body runs inside an async function rather than via top-level await: when a test pulls this
 // Entry in with a dynamic import(), Bun's test runtime drops the continuation after a top-level await
@@ -21,20 +22,89 @@ async function main() {
     console.log(`Usage: jx <command> [options]
 
 Commands:
-  build [root]   Build a Jx site to dist/
+  build [root]     Build a Jx site to dist/
+  dev [root]       Start the dev server (requires @jxsuite/server and Bun)
+  preview [root]   Serve an already-built dist/ directory
+  schema [root]    Generate project.schema.json + document.schema.json from project.json#/extensions
+  validate [root]  Validate project.json against its generated project.schema.json
+  db push [root]   Sync the data section's tables to their connections (additive-only)
 
 Options:
   --verbose      Print detailed build progress
-  --no-clean     Don't clean outDir before building`);
+  --no-clean     Don't clean outDir before building
+  --port <n>     dev/preview: port to listen on (default 3000 / 4173)
+  --dry-run      db push: print the statements without executing them
+  --connection   db push: restrict to one connection name`);
     process.exit(0);
   }
 
-  if (command === "build") {
-    const rest = args.slice(1);
-    const flags = new Set(rest.filter((a) => a.startsWith("--")));
-    const positional = rest.find((a) => !a.startsWith("--"));
+  // `db push` is a two-word command; normalize it before the flag/positional split.
+  const isDb = command === "db";
+  const dbSubcommand = isDb ? args[1] : null;
+  const rest = args.slice(isDb ? 2 : 1);
+  const flags = new Set<string>();
+  const positionals: string[] = [];
+  let connectionArg: string | undefined;
+  let portArg: number | undefined;
+  for (let index = 0; index < rest.length; index += 1) {
+    const arg = rest[index]!;
+    if (arg === "--connection") {
+      index += 1;
+      connectionArg = rest[index];
+    } else if (arg === "--port") {
+      index += 1;
+      const parsed = Math.trunc(Number(rest[index] ?? ""));
+      if (Number.isFinite(parsed) && parsed >= 0) {
+        portArg = parsed;
+      }
+    } else if (arg.startsWith("--")) {
+      flags.add(arg);
+    } else {
+      positionals.push(arg);
+    }
+  }
+  const [positional] = positionals;
+  const projectRoot = resolve(positional ?? ".");
 
-    const projectRoot = resolve(positional ?? ".");
+  if (isDb) {
+    if (dbSubcommand !== "push") {
+      console.error(
+        `Unknown db subcommand: ${dbSubcommand ?? "(none)"}\nUsage: jx db push [root] [--dry-run] [--connection <name>]`,
+      );
+      process.exit(1);
+    }
+    const dryRun = flags.has("--dry-run");
+    try {
+      const { dbPush } = await import("./site/db-push.ts");
+      const { results, bindingsPatched, wranglerPath } = await dbPush(projectRoot, {
+        dryRun,
+        ...(connectionArg === undefined ? {} : { connection: connectionArg }),
+      });
+      for (const result of results) {
+        const mode = result.applied ? "applied" : "dry-run";
+        console.log(
+          `${result.connection} (${result.provider}) — ${result.tables.length} table(s), ` +
+            `${result.statements.length} statement(s) [${mode}]`,
+        );
+        for (const statement of result.statements) {
+          console.log(`  ${statement}`);
+        }
+        for (const warning of result.warnings) {
+          console.warn(`  warning: ${warning}`);
+        }
+      }
+      if (bindingsPatched && wranglerPath) {
+        console.log(`Updated bindings in ${relative(projectRoot, wranglerPath)}`);
+      }
+    } catch (error) {
+      const err = error as Error;
+      console.error(`db push failed: ${err.message}`);
+      process.exit(1);
+    }
+    return;
+  }
+
+  if (command === "build") {
     const verbose = flags.has("--verbose");
     const clean = !flags.has("--no-clean");
 
@@ -58,6 +128,59 @@ Options:
       console.error(`Build failed: ${err.message}`);
       process.exit(1);
     }
+  } else if (command === "dev") {
+    try {
+      const { runDev } = await import("./site/dev-command.ts");
+      runDev(projectRoot, portArg);
+    } catch (error) {
+      const err = error as Error;
+      console.error(err.message);
+      process.exit(1);
+    }
+  } else if (command === "preview") {
+    const { existsSync } = await import("node:fs");
+    const distDir = resolve(projectRoot, "dist");
+    if (!existsSync(distDir)) {
+      console.error(`No build output at ${distDir} — run \`jx build\` first.`);
+      process.exit(1);
+    }
+    const { startPreviewServer } = await import("./site/preview-server.ts");
+    const port = portArg ?? 4173;
+    startPreviewServer(distDir, port);
+    console.log(`Previewing ${distDir} at http://localhost:${port}`);
+  } else if (command === "schema") {
+    try {
+      const { writeProjectSchemas } = await import("./site/schema-command.ts");
+      const { projectSchemaPath, documentSchemaPath } = await writeProjectSchemas(projectRoot);
+      console.log(`Wrote ${relative(projectRoot, projectSchemaPath)}`);
+      console.log(`Wrote ${relative(projectRoot, documentSchemaPath)}`);
+    } catch (error) {
+      const err = error as Error;
+      console.error(`Schema generation failed: ${err.message}`);
+      process.exit(1);
+    }
+  } else if (command === "validate") {
+    try {
+      const { validateProjectFile } = await import("@jxsuite/schema/validate-project");
+      const { valid, errors } = await validateProjectFile(projectRoot);
+      if (valid) {
+        console.log(`project.json is valid (${projectRoot})`);
+      } else {
+        console.error(`project.json is INVALID (${projectRoot}):`);
+        for (const error of errors ?? []) {
+          const { instancePath, message } = (error ?? {}) as {
+            instancePath?: string;
+            message?: string;
+          };
+          console.error(`  - ${instancePath || "/"}: ${message ?? JSON.stringify(error)}`);
+        }
+        process.exit(1);
+      }
+    } catch (error) {
+      const err = error as Error;
+      console.error(`Validation failed: ${err.message}`);
+      process.exit(1);
+    }
   } else {
     console.error(`Unknown command: ${command}\nRun "jx --help" for usage.`);
     process.exit(1);

package/src/shared.ts

@@ -8,11 +8,14 @@
 
 import { RESERVED_KEYS, camelToKebab, toCSSText } from "@jxsuite/runtime";
 import { evaluateExpression, isMutating } from "@jxsuite/runtime/expression";
+import { runStatements } from "@jxsuite/runtime/statements";
 import {
   childrenContainArray,
+  hasStructuredBody,
   isExpressionDef,
   isFunctionDef,
   isMappedArray,
+  isNamedFormulaDef,
   isPrototypeDef,
   isRef,
   isSchemaOnlyDef as isSchemaOnly,
@@ -35,6 +38,28 @@ import type {
 // Re-export runtime utilities used by submodules
 export { RESERVED_KEYS, camelToKebab, toCSSText } from "@jxsuite/runtime";
 export { compileExpression, evaluateExpression, isMutating } from "@jxsuite/runtime/expression";
+export { compileStatements, runStatements } from "@jxsuite/runtime/statements";
+
+/**
+ * Emit the JS source of a named formula's scope callable: positional arguments are mapped onto the
+ * declared parameter names (honoring CemParameter defaults) as the `_args` object the compiled
+ * body's `$args/` refs read from. Call sites stay positional, matching the interpreter.
+ */
+export function emitFormulaFn(def: { parameters?: unknown[] }, compiledBody: string): string {
+  const entries: string[] = [];
+  for (const [i, p] of (def.parameters ?? []).entries()) {
+    const name = typeof p === "string" ? p : ((p as { name?: string } | null)?.name ?? "");
+    if (!name) {
+      continue;
+    }
+    const hasDefault = typeof p === "object" && p !== null && "default" in p;
+    const arg = hasDefault
+      ? `_a[${i}] === undefined ? ${JSON.stringify((p as { default?: unknown }).default)} : _a[${i}]`
+      : `_a[${i}]`;
+    entries.push(`${JSON.stringify(name)}: ${arg}`);
+  }
+  return `(..._a) => { const _args = { ${entries.join(", ")} }; return ${compiledBody}; }`;
+}
 export type { ExpressionNode } from "@jxsuite/runtime/expression";
 
 // CDN defaults
@@ -283,7 +308,24 @@ export function buildInitialScope(
     }
     if (isExpressionDef(def)) {
       const node = def.$expression as ExpressionNode;
-      if (isMutating(node.operator)) {
+      if (isNamedFormulaDef(def)) {
+        // Named formula: callable, positional args mapped onto its declared parameters.
+        const params = def.parameters as (string | { name?: string; default?: unknown })[];
+        setOwnScopeValue(scope, key, (...argValues: unknown[]) => {
+          const args: Record<string, unknown> = {};
+          for (const [i, p] of params.entries()) {
+            const name = typeof p === "string" ? p : (p?.name ?? "");
+            if (!name) {
+              continue;
+            }
+            args[name] =
+              argValues[i] === undefined && typeof p === "object" && p !== null && "default" in p
+                ? p.default
+                : argValues[i];
+          }
+          return evaluateExpression(node, scope, null, { args });
+        });
+      } else if (isMutating(node.operator)) {
         setOwnScopeValue(scope, key, (s: Record<string, unknown>, event: Event) =>
           evaluateExpression(node, s, event),
         );
@@ -293,12 +335,19 @@ export function buildInitialScope(
       continue;
     }
     if (isFunctionDef(def)) {
-      if (def.body) {
+      if (hasStructuredBody(def)) {
+        // Structured body (spec §20): a side-effecting handler in the build-time scope.
+        const { body } = def;
+        setOwnScopeValue(scope, key, (s: Record<string, unknown>, event?: Event) => {
+          void runStatements(body, s ?? scope, event ?? null);
+        });
+      } else if (typeof def.body === "string") {
         const names = def.parameters ? paramNames(def.parameters) : (def.arguments ?? []);
-        const fn = new Function("state", ...names, def.body) as (
+        const { body } = def;
+        const fn = new Function("state", ...names, body) as (
           state: Record<string, unknown>,
         ) => unknown;
-        if (def.body.includes("return")) {
+        if (body.includes("return")) {
           defineLazyScopeValue(scope, key, () => fn(scope));
         } else {
           setOwnScopeValue(scope, key, fn);

package/src/site/context-injection.ts

@@ -4,9 +4,6 @@
  * Injects project-level and page-level context variables into a page's state before compilation.
  * These are available as $site.* and $page.* in template expressions.
  *
- * Also resolves ContentCollection and ContentEntry $prototype entries against loaded content types
- * (Phase 2, spec §6.4).
- *
  * Per site-architecture spec §10: $site.name — from project.json name $site.url — from project.json
  * url $site.state.* — site-wide reactive state $page.url — current page URL path $page.title — page
  * title $page.params — dynamic route parameters (if any)
@@ -19,7 +16,6 @@ import type {
   JxStateDefinition,
   ProjectConfig,
 } from "@jxsuite/schema/types";
-import type { ContentLoaderEntry } from "@jxsuite/parser/types";
 import type { SiteRoute } from "../types.ts";
 
 /**
@@ -28,7 +24,6 @@ import type { SiteRoute } from "../types.ts";
  * @param {JxDocument} doc - The page document (mutated)
  * @param {ProjectConfig} projectConfig - Loaded project configuration
  * @param {SiteRoute} route - The resolved route for this page
- * @param {Map<string, ContentLoaderEntry[]>} [contentTypes] - Loaded content types
  * @param {string | null} [projectRoot] - Absolute path to the project root (for import rebasing)
  * @returns {JxDocument} The mutated document
  */
@@ -36,7 +31,6 @@ export function injectContext(
   doc: JxDocument,
   projectConfig: ProjectConfig,
   route: SiteRoute,
-  _contentTypes = new Map<string, ContentLoaderEntry[]>(),
   projectRoot: string | null = null,
 ) {
   if (!doc.state) {

package/src/site/db-push.ts

@@ -0,0 +1,178 @@
+/**
+ * Db-push — `jx db push [root] [--dry-run] [--connection <name>]` (plan Part 4a).
+ *
+ * Registry-driven: every `connections` entry resolves to its connector class (by
+ * `connector.provider`) and the additive schema sync runs through the class's `deploySchema`
+ * capability with the connection's tables from the `data` section. The environment is process.env
+ * merged under `<root>/.dev.vars` (wrangler convention, specs/extensions.md §13). After a non-dry
+ * apply, each connector's `bindings` fragment is deep-merged into wrangler.jsonc via
+ * `applyBindingFragments` (user keys preserved).
+ */
+
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { applyBindingFragments } from "@jxsuite/create/scaffold";
+import { buildProjectExtensionRegistry } from "./format-host.ts";
+import { loadProjectConfig } from "./site-loader.ts";
+import type { FormatEntry } from "@jxsuite/schema/format-registry";
+
+export interface DbPushOptions {
+  dryRun?: boolean;
+  /** Restrict the push to one connection name. */
+  connection?: string;
+}
+
+export interface ConnectionPushResult {
+  connection: string;
+  provider: string;
+  tables: string[];
+  statements: string[];
+  warnings: string[];
+  applied: boolean;
+}
+
+export interface DbPushResult {
+  results: ConnectionPushResult[];
+  /** True when wrangler.jsonc was rewritten with binding fragments. */
+  bindingsPatched: boolean;
+  wranglerPath: string | null;
+}
+
+interface DeployResultLike {
+  statements?: string[];
+  warnings?: string[];
+  applied?: boolean;
+}
+
+/**
+ * Push the project's table schemas to their connections' databases.
+ *
+ * @param {string} projectRoot - Absolute path to the project directory
+ * @param {DbPushOptions} [options]
+ * @returns {Promise<DbPushResult>}
+ */
+export async function dbPush(
+  projectRoot: string,
+  options: DbPushOptions = {},
+): Promise<DbPushResult> {
+  const { dryRun = false, connection: only } = options;
+  const { config } = loadProjectConfig(projectRoot);
+  const registry = await buildProjectExtensionRegistry(projectRoot, config);
+
+  const connections = (config.connections ?? {}) as Record<string, Record<string, unknown>>;
+  const tables = (config.data ?? {}) as Record<string, { connection?: string }>;
+
+  const names = Object.keys(connections).filter((name) => !only || name === only);
+  if (only && names.length === 0) {
+    throw new Error(`Unknown connection "${only}" (no such connections entry in project.json)`);
+  }
+  if (names.length === 0) {
+    throw new Error(
+      `project.json has no "connections" section — nothing to push. Declare a connection and ` +
+        `its tables in the "data" section first.`,
+    );
+  }
+
+  const env: Record<string, unknown> = {
+    ...process.env,
+    ...readDevVars(projectRoot),
+    JX_PROJECT_ROOT: projectRoot,
+  };
+
+  const results: ConnectionPushResult[] = [];
+  const fragments: Record<string, unknown>[] = [];
+  for (const name of names) {
+    const connection: Record<string, unknown> = { ...connections[name], $name: name };
+    const provider = String(connection.provider ?? "");
+    const entry = connectorByProvider(registry.connectors(), provider);
+    if (!entry) {
+      throw new Error(
+        `Connection "${name}" names provider "${provider}", but no enabled extension provides ` +
+          `it (enable the extension in project.json "extensions")`,
+      );
+    }
+    const connectionTables: Record<string, unknown> = {};
+    for (const [tableName, def] of Object.entries(tables)) {
+      if (def.connection === name) {
+        connectionTables[tableName] = def;
+      }
+    }
+
+    const deployed = (await entry.call("deploySchema", connectionTables, connection, {
+      dryRun,
+      env,
+    })) as DeployResultLike;
+    results.push({
+      applied: deployed.applied ?? !dryRun,
+      connection: name,
+      provider,
+      statements: deployed.statements ?? [],
+      tables: Object.keys(connectionTables),
+      warnings: deployed.warnings ?? [],
+    });
+
+    if (entry.capabilities.bindings) {
+      const fragment = (await entry.call("bindings", connection)) as Record<string, unknown>;
+      if (fragment && Object.keys(fragment).length > 0) {
+        fragments.push(fragment);
+      }
+    }
+  }
+
+  // Apply binding fragments to wrangler.jsonc (skipped on dry runs and non-wrangler projects).
+  const wranglerPath = resolve(projectRoot, "wrangler.jsonc");
+  let bindingsPatched = false;
+  if (!dryRun && fragments.length > 0 && existsSync(wranglerPath)) {
+    const existing = readFileSync(wranglerPath, "utf8");
+    const { content, patched } = applyBindingFragments(existing, fragments);
+    if (patched && content !== existing) {
+      writeFileSync(wranglerPath, content, "utf8");
+      bindingsPatched = true;
+    }
+  }
+
+  return { bindingsPatched, results, wranglerPath: existsSync(wranglerPath) ? wranglerPath : null };
+}
+
+/** Find the connector class serving a provider id. */
+function connectorByProvider(entries: FormatEntry[], provider: string): FormatEntry | undefined {
+  return entries.find((entry) => entry.connector?.provider === provider);
+}
+
+/**
+ * Parse `<root>/.dev.vars` (wrangler convention): KEY=VALUE lines, `#` comments, optional
+ * single/double quotes. Kept deliberately tiny; the dev server has its own copy in
+ * `@jxsuite/server` (dev-vars.ts) — the compiler cannot depend on the server package.
+ *
+ * @param {string} projectRoot
+ * @returns {Record<string, string>}
+ */
+export function readDevVars(projectRoot: string): Record<string, string> {
+  const path = resolve(projectRoot, ".dev.vars");
+  if (!existsSync(path)) {
+    return {};
+  }
+  const out: Record<string, string> = {};
+  for (const rawLine of readFileSync(path, "utf8").split("\n")) {
+    const line = rawLine.trim();
+    if (line === "" || line.startsWith("#")) {
+      continue;
+    }
+    const eq = line.indexOf("=");
+    if (eq === -1) {
+      continue;
+    }
+    const key = line.slice(0, eq).trim();
+    let value = line.slice(eq + 1).trim();
+    if (
+      (value.startsWith('"') && value.endsWith('"')) ||
+      (value.startsWith("'") && value.endsWith("'"))
+    ) {
+      value = value.slice(1, -1);
+    }
+    if (key !== "") {
+      out[key] = value;
+    }
+  }
+  return out;
+}

package/src/site/dev-command.ts

@@ -0,0 +1,84 @@
+/**
+ * Dev command — `jx dev` resolves the project's @jxsuite/server dev entry and spawns it under Bun.
+ *
+ * The compiler cannot depend on @jxsuite/server (the server already depends on the compiler), and
+ * the dev server is Bun-native while the jx bin runs under Node — so the command is pure resolution
+ * + spawn: the entry module is resolved from the PROJECT's node_modules and executed with Bun.
+ *
+ * @module dev-command
+ */
+
+import { createRequire } from "node:module";
+import { join } from "node:path";
+import { spawn } from "node:child_process";
+import type { ChildProcess } from "node:child_process";
+
+/**
+ * Resolve the project's `@jxsuite/server/dev` entry module.
+ *
+ * @param {string} projectRoot - Absolute project root
+ * @returns {string} Absolute path to the dev entry module
+ * @throws {Error} With an install hint when the package is not present
+ */
+export function resolveDevEntry(projectRoot: string): string {
+  try {
+    const projectRequire = createRequire(join(projectRoot, "package.json"));
+    return projectRequire.resolve("@jxsuite/server/dev");
+  } catch {
+    throw new Error(
+      `@jxsuite/server is not installed in ${projectRoot}. ` +
+        `Add it to devDependencies (e.g. \`bun add -d @jxsuite/server\`) and retry.`,
+    );
+  }
+}
+
+/** The slice of `process` runDev touches — injectable for tests. */
+export interface ProcessLike {
+  on: (event: string, handler: () => void) => unknown;
+  exitCode?: number | string | undefined;
+}
+
+/**
+ * Spawn the dev server under Bun with inherited stdio.
+ *
+ * @param {string} projectRoot - Absolute project root
+ * @param {number | undefined} port - Optional port override
+ * @param {typeof spawn} [spawnImpl] - Injectable for tests
+ * @param {ProcessLike} [proc] - Injectable for tests
+ * @returns {ChildProcess} The spawned Bun process
+ */
+export function runDev(
+  projectRoot: string,
+  port: number | undefined,
+  spawnImpl: typeof spawn = spawn,
+  proc: ProcessLike = process as unknown as ProcessLike,
+): ChildProcess {
+  const entry = resolveDevEntry(projectRoot);
+  const args = [entry, "--root", projectRoot];
+  if (port !== undefined) {
+    args.push("--port", String(port));
+  }
+  const child = spawnImpl("bun", args, { stdio: "inherit" });
+  child.on("error", (error: NodeJS.ErrnoException) => {
+    if (error.code === "ENOENT") {
+      console.error(
+        "The Jx dev server runs on Bun, which was not found on your PATH. " +
+          "Install it from https://bun.sh and retry.",
+      );
+    } else {
+      console.error(`Failed to start the dev server: ${error.message}`);
+    }
+    proc.exitCode = 1;
+  });
+  // Ctrl+C reaches the child through the shared process group; also mirror explicit kills.
+  proc.on("SIGINT", () => {
+    child.kill("SIGINT");
+  });
+  proc.on("SIGTERM", () => {
+    child.kill("SIGTERM");
+  });
+  child.on("exit", (code) => {
+    proc.exitCode = code ?? 0;
+  });
+  return child;
+}