@jxsuite/compiler 0.35.0 → 1.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jxsuite/compiler",
-  "version": "0.35.0",
+  "version": "1.0.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.0.0",
+    "@jxsuite/runtime": "^1.0.0",
+    "@jxsuite/schema": "^1.0.0",
     "sharp": "^0.35.3"
   },
   "devDependencies": {
     "@happy-dom/global-registrator": "^20.10.6",
+    "@jxsuite/connector": "^0.2.0",
+    "@jxsuite/parser": "^1.0.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,79 @@ 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/
+  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
+  --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;
+  for (let index = 0; index < rest.length; index += 1) {
+    const arg = rest[index]!;
+    if (arg === "--connection") {
+      index += 1;
+      connectionArg = rest[index];
+    } else if (arg.startsWith("--")) {
+      flags.add(arg);
+    } else {
+      positionals.push(arg);
+    }
+  }
+  const [positional] = positionals;
+  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;
+  }
 
-    const projectRoot = resolve(positional ?? ".");
+  if (command === "build") {
     const verbose = flags.has("--verbose");
     const clean = !flags.has("--no-clean");
 
@@ -58,6 +118,39 @@ Options:
       console.error(`Build failed: ${err.message}`);
       process.exit(1);
     }
+  } 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/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/format-host.ts

@@ -1,19 +1,21 @@
 /**
  * Format-host — node-side FormatHostIO and project registry construction
  *
- * Provides the filesystem/module I/O the shared format registry needs to run inside the compiler
- * (and dev server). Format classes are auto-discovered from the project-level imports map; see
- * specs/extensions.md.
+ * Provides the filesystem/module I/O the shared extension registry needs to run inside the compiler
+ * (and dev server). Extensions are declared explicitly in project.json's `extensions` array and
+ * discovered through their jx-extension.json manifests; see specs/extensions.md.
  */
 
 import { readFileSync } from "node:fs";
 import { dirname, isAbsolute, resolve, sep } from "node:path";
 import { pathToFileURL } from "node:url";
 import { createRequire } from "node:module";
-import { buildFormatRegistry } from "@jxsuite/schema/format-registry";
-import type { FormatHostIO, FormatRegistry } from "@jxsuite/schema/format-registry";
+import { buildExtensionRegistry } from "@jxsuite/schema/extension-registry";
+import type { ExtensionRegistry } from "@jxsuite/schema/extension-registry";
+import type { FormatHostIO, FormatRegistry, ProjectBlock } from "@jxsuite/schema/format-registry";
 import type { ProjectConfig } from "@jxsuite/schema/types";
 
+export type { ExtensionRegistry } from "@jxsuite/schema/extension-registry";
 export type { FormatRegistry, FormatEntry } from "@jxsuite/schema/format-registry";
 
 /**
@@ -73,23 +75,136 @@ export function createNodeFormatIO(projectRoot: string): FormatHostIO {
   };
 }
 
-/** Build the format registry for a project from its project.json imports map. */
-export async function buildProjectFormatRegistry(
+/** Build the extension registry for a project from its project.json `extensions` array. */
+export async function buildProjectExtensionRegistry(
   projectRoot: string,
   projectConfig?: ProjectConfig,
-): Promise<FormatRegistry> {
-  return buildFormatRegistry(
-    projectConfig?.imports as Record<string, string> | undefined,
+): Promise<ExtensionRegistry> {
+  return buildExtensionRegistry(
+    projectConfig?.extensions,
     createNodeFormatIO(projectRoot),
     resolve(projectRoot, "project.json"),
   );
 }
 
+/**
+ * Format-dispatch view of the project's extension registry.
+ *
+ * @deprecated Part-3 cleanup: the desktop app still imports this; use
+ *   `buildProjectExtensionRegistry(...).then((r) => r.formats)` instead.
+ */
+export async function buildProjectFormatRegistry(
+  projectRoot: string,
+  projectConfig?: ProjectConfig,
+): Promise<FormatRegistry> {
+  const registry = await buildProjectExtensionRegistry(projectRoot, projectConfig);
+  return registry.formats;
+}
+
+// ─── Studio extensions payload ────────────────────────────────────────────────
+
+/** One project-section contribution on the studio wire (specs/extensions.md §9/§9.1). */
+export interface ExtensionsPayloadContribution {
+  /** The $prototype-visible class name declaring the `project` block. */
+  className: string;
+  /** The class descriptor's `project` admission block. */
+  project: ProjectBlock;
+  /** The class descriptor's `$studio` block (settings section vocabulary), when declared. */
+  studio: Record<string, unknown> | null;
+  /**
+   * The section's value schema — `properties[<key>]` of the extension's project fragment — or null
+   * when the extension ships no project fragment (or it lacks the key).
+   */
+  entrySchema: Record<string, unknown> | null;
+}
+
+/** One extension package on the studio wire (the formats route's `extensions` sibling array). */
+export interface ExtensionsPayloadEntry {
+  specifier: string;
+  name: string;
+  title?: string;
+  description?: string;
+  contributions: ExtensionsPayloadContribution[];
+  /**
+   * Every manifest class of the extension with its resolved descriptor path, in declaration order
+   * (additive; lets the studio address a class by `$src` without hardcoding its package layout).
+   * Plain state classes (no admission blocks — `$prototype` targets like TableQuery or Session)
+   * carry `state: true` plus their `$studio.stateDefaults` hint (specs/extensions.md §10), so the
+   * studio can offer them in its add-state picker and seed new defs (e.g. `timing: "client"`).
+   */
+  classes: {
+    name: string;
+    path: string;
+    state?: boolean;
+    stateDefaults?: Record<string, unknown>;
+  }[];
+}
+
+/**
+ * Build the studio-facing extensions payload from a project's extension registry: per extension,
+ * its manifest identity plus every project-section contribution paired with the entry schema read
+ * from the extension's shipped project fragment. Unreadable fragments degrade to a null entrySchema
+ * (the studio renders the section without field metadata).
+ *
+ * @param {ExtensionRegistry} registry
+ * @returns {ExtensionsPayloadEntry[]}
+ */
+export function buildExtensionsPayload(registry: ExtensionRegistry): ExtensionsPayloadEntry[] {
+  const payload: ExtensionsPayloadEntry[] = [];
+  for (const ext of registry.extensions) {
+    let fragmentProperties: Record<string, Record<string, unknown>> = {};
+    if (ext.schemas.project) {
+      try {
+        const fragment = JSON.parse(readFileSync(ext.schemas.project, "utf8")) as {
+          properties?: Record<string, Record<string, unknown>>;
+        };
+        fragmentProperties = fragment.properties ?? {};
+      } catch {
+        fragmentProperties = {};
+      }
+    }
+    const contributions: ExtensionsPayloadContribution[] = [];
+    for (const cls of ext.classes) {
+      if (!cls.project) {
+        continue;
+      }
+      contributions.push({
+        className: cls.name,
+        entrySchema: fragmentProperties[cls.project.key] ?? null,
+        project: cls.project,
+        studio: cls.studio,
+      });
+    }
+    payload.push({
+      classes: ext.classes.map((cls) => {
+        const stateDefaults = cls.studio?.stateDefaults as Record<string, unknown> | undefined;
+        const isState =
+          cls.project === null &&
+          cls.server === null &&
+          cls.connector === null &&
+          cls.extensions.length === 0;
+        return {
+          name: cls.name,
+          path: cls.classPath,
+          ...(isState ? { state: true } : {}),
+          ...(stateDefaults && typeof stateDefaults === "object" ? { stateDefaults } : {}),
+        };
+      }),
+      contributions,
+      name: ext.manifest.name,
+      specifier: ext.specifier,
+      ...(ext.manifest.title === undefined ? {} : { title: ext.manifest.title }),
+      ...(ext.manifest.description === undefined ? {} : { description: ext.manifest.description }),
+    });
+  }
+  return payload;
+}
+
 /** Error message for an unregistered non-JSON extension, naming the fix. */
 export function unknownFormatError(path: string, ext: string): Error {
   return new Error(
-    `No format class imported for "${ext}" (${path}). ` +
-      `Add a format class to project.json imports, e.g. ` +
-      `"Markdown": "@jxsuite/parser/Markdown.class.json".`,
+    `No format class registered for "${ext}" (${path}). ` +
+      `Enable an extension providing this format in project.json "extensions", ` +
+      `e.g. "@jxsuite/parser".`,
   );
 }