@backmatter/core 0.0.16 → 0.0.17

package/package.json

@@ -1,15 +1,21 @@
 {
   "name": "@backmatter/core",
-  "version": "0.0.16",
+  "version": "0.0.17",
   "description": "Experimental Backmatter SDK. APIs will break. Not ready for production.",
   "type": "module",
   "publishConfig": {
     "access": "public"
   },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/MRued/backmatter.git",
+    "directory": "packages/core"
+  },
   "exports": {
     ".": "./src/index.ts",
     "./node": "./src/node/index.ts",
     "./node/create-backmatter": "./src/node/create-backmatter.ts",
+    "./node/registry-import": "./src/node/registry-import.ts",
     "./preview": "./src/preview.ts",
     "./generate": "./src/node/generate.ts"
   },
@@ -21,7 +27,7 @@
     "!**/test-fixtures"
   ],
   "bin": {
-    "backmatter": "./bin/backmatter.js"
+    "backmatter": "bin/backmatter.js"
   },
   "scripts": {
     "test": "bun test"

package/src/config.ts

@@ -98,14 +98,38 @@ export function resolveDevBarApiUrl(
   return "";
 }
 
+function isLoopbackApiUrl(url: string): boolean {
+  try {
+    const { hostname } = new URL(url);
+    return hostname === "localhost" || hostname === "127.0.0.1" || hostname === "::1";
+  } catch {
+    return false;
+  }
+}
+
+/** Vercel, Netlify, Cloudflare Pages, or Railway — not a laptop `next build`. */
+function onPlatformDeploy(env: Record<string, string | undefined>): boolean {
+  return Boolean(env.VERCEL || env.NETLIFY || env.CF_PAGES || env.RAILWAY_ENVIRONMENT);
+}
+
 function detectApiUrl(
   config: BackmatterConfig,
   env: Record<string, string | undefined>,
   workspaceId: string | undefined,
 ): string | undefined {
-  const explicit = config.apiUrl !== undefined ? config.apiUrl : env.BACKMATTER_API_URL;
+  const fromConfig = config.apiUrl !== undefined;
+  const explicit = fromConfig ? config.apiUrl : env.BACKMATTER_API_URL;
   const trimmed = explicit?.trim();
-  if (trimmed) return stripTrailingSlash(trimmed);
+  // Next loads `.env` for every environment, so a dev loopback URL is present
+  // during `next build` and fails page-data collection when that API is down.
+  // A local production build falls through to the cloud API. An explicit
+  // config.apiUrl, `next dev`, and a real platform deploy keep the loopback URL.
+  const ignoreDevLoopback =
+    !fromConfig &&
+    Boolean(trimmed && isLoopbackApiUrl(trimmed)) &&
+    env.NEXT_PHASE === "phase-production-build" &&
+    !onPlatformDeploy(env);
+  if (trimmed && !ignoreDevLoopback) return stripTrailingSlash(trimmed);
   if (workspaceId && isDeployedHost(env)) return CLOUD_API_URL;
   return undefined;
 }

package/src/node/cli.ts

@@ -17,6 +17,7 @@ import { resolveConfig, type BackmatterConfig, type ResolvedConfig } from "../co
 import { discoverModels, discoverBlocks } from "./discover";
 import { walkContentFiles } from "./fs-loader";
 import { detectSdk, findConfigFile, generate, type GenerateResult } from "./generate";
+import { ensureRegistryTsconfig, REGISTRY_SPECIFIER } from "./registry-import";
 
 export type CliArgs = {
   command?: string;
@@ -261,16 +262,16 @@ export default defineConfig({
 `;
 }
 
-function renderCatchAllPage(registryImport: string): string {
+function renderCatchAllPage(): string {
   return `// ${CATCH_ALL_DIR}/page.tsx — mounts every model at its route, including / via indexSlug.
 import { cacheLife } from "next/cache";
 import { createCatchAll } from "@backmatter/next/routes";
-import { cms } from "${registryImport}";
-import { components as mdxComponents } from "${registryImport}/mdx";
-import { richtextComponents } from "${registryImport}/richtext";
-import { blockLoaders } from "${registryImport}/blocks";
-import { blockFallbacks } from "${registryImport}/block-fallbacks";
-import { layouts } from "${registryImport}/layouts";
+import { cms } from "${REGISTRY_SPECIFIER}";
+import { components as mdxComponents } from "${REGISTRY_SPECIFIER}/mdx";
+import { richtextComponents } from "${REGISTRY_SPECIFIER}/richtext";
+import { blockLoaders } from "${REGISTRY_SPECIFIER}/blocks";
+import { blockFallbacks } from "${REGISTRY_SPECIFIER}/block-fallbacks";
+import { layouts } from "${REGISTRY_SPECIFIER}/layouts";
 
 const components = { ...richtextComponents, ...mdxComponents };
 const route = createCatchAll(cms, { components, blocks: blockLoaders, fallbacks: blockFallbacks, layouts });
@@ -303,12 +304,12 @@ export default async function Page(props: {
 `;
 }
 
-function renderInstrumentation(syncImport: string): string {
+function renderInstrumentation(): string {
   return `// instrumentation.ts — schema sync on Node. Next also runs register() on Edge;
-// do not import .backmatter/sync there (it pulls Node APIs).
+// do not import ${REGISTRY_SPECIFIER}/sync there (it pulls Node APIs).
 export async function register() {
   if (process.env.NEXT_RUNTIME === "nodejs") {
-    await import("${syncImport}");
+    await import("${REGISTRY_SPECIFIER}/sync");
   }
 }
 `;
@@ -320,15 +321,15 @@ export function warnMissingInstrumentation(root: string): void {
   const hasSrc = existsSync(path.join(root, "src", "instrumentation.ts"));
   if (!hasRoot && !hasSrc) {
     console.warn(
-      "backmatter: add instrumentation.ts that imports .backmatter/sync — block schema sync will not run without it",
+      `backmatter: add instrumentation.ts that imports ${REGISTRY_SPECIFIER}/sync — block schema sync will not run without it`,
     );
   }
 }
 
-function renderPreviewRoute(registryImport: string): string {
+function renderPreviewRoute(): string {
   return `// api/backmatter/preview/route.ts — preview session enable / disable / stream / session.
 import { createPreviewRoute } from "@backmatter/next/preview-route";
-import { cms } from "${registryImport}";
+import { cms } from "${REGISTRY_SPECIFIER}";
 
 export const { GET, POST } = createPreviewRoute(cms);
 `;
@@ -347,10 +348,10 @@ export const config = {
 `;
 }
 
-function renderRevalidateRoute(registryImport: string): string {
+function renderRevalidateRoute(): string {
   return `// api/backmatter/revalidate/route.ts — content.committed from the BACKMATTER server.
 import { createRevalidateRoute } from "@backmatter/next/revalidate";
-import { cms } from "${registryImport}";
+import { cms } from "${REGISTRY_SPECIFIER}";
 
 export const POST = createRevalidateRoute(cms);
 `;
@@ -386,21 +387,16 @@ export async function runInit(args: CliArgs): Promise<string[]> {
     } else if (existsSync(requiredCatchAll)) {
       notes.push(`kept existing ${path.join(appDir, "[...backmatter]", "page.tsx")}`);
     } else {
-      const registry = path.relative(pageDir, path.join(root, ".backmatter")).split(path.sep).join("/");
       await mkdir(pageDir, { recursive: true });
-      await writeFile(page, renderCatchAllPage(registry.startsWith(".") ? registry : `./${registry}`));
+      await writeFile(page, renderCatchAllPage());
       notes.push(`wrote ${path.join(appDir, CATCH_ALL_DIR, "page.tsx")}`);
     }
 
     const revalidateDir = path.join(root, appDir, "api", "backmatter", "revalidate");
     const revalidateFile = path.join(revalidateDir, "route.ts");
     if (!existsSync(revalidateFile)) {
-      const registry = path.relative(revalidateDir, path.join(root, ".backmatter")).split(path.sep).join("/");
       await mkdir(revalidateDir, { recursive: true });
-      await writeFile(
-        revalidateFile,
-        renderRevalidateRoute(registry.startsWith(".") ? registry : `./${registry}`),
-      );
+      await writeFile(revalidateFile, renderRevalidateRoute());
       notes.push(`wrote ${path.join(appDir, "api/backmatter/revalidate/route.ts")}`);
     } else {
       notes.push(`kept existing ${path.join(appDir, "api/backmatter/revalidate/route.ts")}`);
@@ -409,12 +405,8 @@ export async function runInit(args: CliArgs): Promise<string[]> {
     const previewDir = path.join(root, appDir, "api", "backmatter", "preview");
     const previewFile = path.join(previewDir, "route.ts");
     if (!existsSync(previewFile)) {
-      const registry = path.relative(previewDir, path.join(root, ".backmatter")).split(path.sep).join("/");
       await mkdir(previewDir, { recursive: true });
-      await writeFile(
-        previewFile,
-        renderPreviewRoute(registry.startsWith(".") ? registry : `./${registry}`),
-      );
+      await writeFile(previewFile, renderPreviewRoute());
       notes.push(`wrote ${path.join(appDir, "api/backmatter/preview/route.ts")}`);
     } else {
       notes.push(`kept existing ${path.join(appDir, "api/backmatter/preview/route.ts")}`);
@@ -448,10 +440,12 @@ export async function runInit(args: CliArgs): Promise<string[]> {
       notes.push("kept existing instrumentation.ts");
     } else {
       const dest = usesSrcApp ? srcInstrumentation : rootInstrumentation;
-      const syncImport = usesSrcApp ? "../.backmatter/sync" : "./.backmatter/sync";
-      await writeFile(dest, renderInstrumentation(syncImport));
+      await writeFile(dest, renderInstrumentation());
       notes.push(`wrote ${path.relative(root, dest)}`);
     }
+
+    const tsconfigNote = ensureRegistryTsconfig(root);
+    if (tsconfigNote) notes.push(tsconfigNote);
   } else {
     notes.push("no @backmatter/next dependency: skipped the catch-all route");
   }

package/src/node/index.ts

@@ -39,6 +39,15 @@ export {
   REGISTRY_FILES,
 } from "./generate";
 export type { GenerateOptions, GenerateResult, GeneratedFile } from "./generate";
+export {
+  REGISTRY_SPECIFIER,
+  addRegistryPaths,
+  ensureRegistryTsconfig,
+  registryImportPaths,
+  inferTurbopackRoot,
+  registryTurbopackAlias,
+  registryWebpackAlias,
+} from "./registry-import";
 export {
   contentRoots,
   formatResults,

package/src/node/registry-import.ts

@@ -0,0 +1,335 @@
+// packages/core/src/node/registry-import.ts
+// The generated client lives in `.backmatter/`. Apps import it as `backmatter`
+// from any file. These helpers are the alias (`withBackmatter`) and the
+// matching `tsconfig.json` `paths` (`init` and `withBackmatter`).
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { DEFAULT_OUT_DIR, REGISTRY_FILES } from "./generate";
+
+export const REGISTRY_SPECIFIER = "backmatter";
+
+export type RegistryAlias = {
+  /** Bare import, e.g. `backmatter` or `backmatter/mdx`. */
+  specifier: string;
+  /** File name inside the out dir, e.g. `index.ts`. */
+  file: string;
+};
+
+export function registryAliases(): RegistryAlias[] {
+  return REGISTRY_FILES.map((file) => {
+    const stem = file.slice(0, -".ts".length);
+    return {
+      specifier: stem === "index" ? REGISTRY_SPECIFIER : `${REGISTRY_SPECIFIER}/${stem}`,
+      file,
+    };
+  });
+}
+
+const LOCK_FILES = ["pnpm-lock.yaml", "package-lock.json", "yarn.lock", "bun.lock", "bun.lockb"];
+
+/**
+ * Highest workspace or lockfile at or above `appRoot`, inside the git repo.
+ * Next uses the same files to choose `turbopack.root`. In a single-package app
+ * that is the app root; in this monorepo it is the repository root.
+ */
+export function inferTurbopackRoot(appRoot: string): string {
+  const start = path.resolve(appRoot);
+  const gitRoot = findGitRoot(start);
+  let dir = start;
+  let root = start;
+  while (true) {
+    if (hasWorkspace(dir) || LOCK_FILES.some((name) => existsSync(path.join(dir, name)))) root = dir;
+    if (gitRoot && dir === gitRoot) break;
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return root;
+}
+
+/**
+ * Turbopack `resolveAlias` values, relative to the Next app, with a `./` prefix.
+ * Next resolves these from the app directory even when `turbopack.root` is a
+ * parent workspace. A monorepo prefix (`./packages/docs/.backmatter/...`) makes
+ * the lookup `packages/docs/packages/docs/.backmatter`.
+ */
+export function registryTurbopackAlias(
+  appRoot: string,
+  outDir = DEFAULT_OUT_DIR,
+): Record<string, string> {
+  const alias: Record<string, string> = {};
+  const base = path.resolve(appRoot);
+  for (const { specifier, file } of registryAliases()) {
+    const abs = path.resolve(appRoot, outDir, file);
+    alias[specifier] = asRelative(path.relative(base, abs).split(path.sep).join("/"));
+  }
+  return alias;
+}
+
+/**
+ * Webpack `resolve.alias`. Keys end in `$` so `backmatter` matches only that
+ * specifier, and `backmatter/mdx` stays its own entry. Values are absolute.
+ */
+export function registryWebpackAlias(root: string, outDir = DEFAULT_OUT_DIR): Record<string, string> {
+  const alias: Record<string, string> = {};
+  for (const { specifier, file } of registryAliases()) {
+    alias[`${specifier}$`] = path.resolve(root, outDir, file);
+  }
+  return alias;
+}
+
+/**
+ * `tsconfig` `paths` for the registry. Values are relative to `baseUrl` when
+ * set, otherwise to the tsconfig directory (the project root).
+ */
+export function registryImportPaths(outDir = DEFAULT_OUT_DIR, baseUrl?: string): Record<string, string[]> {
+  const base = !baseUrl || baseUrl === "." ? "." : baseUrl;
+  const from = path.resolve("/registry-root", base);
+  const to = path.resolve("/registry-root", outDir);
+  const folder = asRelative(path.relative(from, to).split(path.sep).join("/"));
+  const paths: Record<string, string[]> = {};
+  for (const { specifier, file } of registryAliases()) {
+    paths[specifier] = [`${folder}/${file}`];
+  }
+  return paths;
+}
+
+/** Insert missing `backmatter` paths. Returns the source unchanged when they are already present. */
+export function addRegistryPaths(source: string, outDir = DEFAULT_OUT_DIR): string {
+  let parsed: unknown;
+  try {
+    parsed = looseParse(source);
+  } catch {
+    return source;
+  }
+  if (!isRecord(parsed)) return source;
+  const options = parsed.compilerOptions;
+  if (!isRecord(options)) return source;
+  const baseUrl = typeof options.baseUrl === "string" ? options.baseUrl : undefined;
+  const mappings = registryImportPaths(outDir, baseUrl);
+  const existing = isRecord(options.paths) ? options.paths : undefined;
+  if (options.paths !== undefined && !existing) return source;
+  const missing = Object.fromEntries(
+    Object.entries(mappings).filter(([key]) => !existing || existing[key] === undefined),
+  );
+  if (Object.keys(missing).length === 0) return source;
+
+  const compiler = findKeyBrace(source, "compilerOptions", 0, source.length);
+  if (!compiler) return source;
+  const compilerEnd = matchBrace(source, compiler.brace);
+  if (compilerEnd < 0) return source;
+
+  const nl = source.includes("\r\n") ? "\r\n" : "\n";
+  if (existing) {
+    const pathsBrace = findKeyBrace(source, "paths", compiler.brace + 1, compilerEnd);
+    if (!pathsBrace || pathsBrace.brace > compilerEnd) return source;
+    const indent = innerIndent(source, pathsBrace.brace);
+    const entries = formatEntries(missing, indent, nl);
+    return insertEntries(source, pathsBrace.brace, entries, indent, nl);
+  }
+
+  const indent = innerIndent(source, compiler.brace);
+  const child = `${indent}  `;
+  const entries = formatEntries(missing, child, nl);
+  const block = `${indent}"paths": {${nl}${entries},${nl}${indent}}`;
+  return `${source.slice(0, compiler.brace + 1)}${nl}${block},${source.slice(compiler.brace + 1)}`;
+}
+
+/** Write `paths` into tsconfig.json or jsconfig.json when the registry keys are missing. */
+export function ensureRegistryTsconfig(root: string, outDir = DEFAULT_OUT_DIR): string | null {
+  const tsconfig = path.join(root, "tsconfig.json");
+  const jsconfig = path.join(root, "jsconfig.json");
+  const file = existsSync(tsconfig) ? tsconfig : existsSync(jsconfig) ? jsconfig : null;
+  if (!file) return null;
+  const before = readFileSync(file, "utf-8");
+  const after = addRegistryPaths(before, outDir);
+  if (after === before) return null;
+  writeFileSync(file, after);
+  return `updated ${path.basename(file)}`;
+}
+
+function hasWorkspace(dir: string): boolean {
+  const pkgPath = path.join(dir, "package.json");
+  if (!existsSync(pkgPath)) return false;
+  try {
+    return JSON.parse(readFileSync(pkgPath, "utf-8")).workspaces != null;
+  } catch {
+    return false;
+  }
+}
+
+function findGitRoot(start: string): string | null {
+  let dir = start;
+  while (true) {
+    if (existsSync(path.join(dir, ".git"))) return dir;
+    const parent = path.dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+
+/** `.backmatter/...` is relative, and still needs a `./` so bundlers do not treat it as a package. */
+function asRelative(rel: string): string {
+  if (rel.startsWith("./") || rel.startsWith("../")) return rel;
+  return `./${rel}`;
+}
+
+function insertEntries(source: string, open: number, entries: string, indent: string, nl: string): string {
+  let rest = source.slice(open + 1);
+  if (!/^\r?\n/.test(rest)) rest = `${nl}${indent}${rest.trimStart()}`;
+  return `${source.slice(0, open + 1)}${nl}${entries},${rest}`;
+}
+
+function formatEntries(mappings: Record<string, string[]>, indent: string, nl: string): string {
+  return Object.entries(mappings)
+    .map(([key, value]) => `${indent}"${key}": [${value.map((entry) => JSON.stringify(entry)).join(", ")}]`)
+    .join(`,${nl}`);
+}
+
+function innerIndent(source: string, open: number): string {
+  const rest = source.slice(open + 1);
+  const nl = rest.search(/\r?\n/);
+  if (nl !== -1) {
+    const after = rest.slice(nl).replace(/^\r?\n/, "");
+    const indent = after.match(/^[ \t]*/)?.[0] ?? "";
+    const next = after[indent.length];
+    if (indent.length > 0 && next && next !== "}") return indent;
+  }
+  const lineStart = source.lastIndexOf("\n", open) + 1;
+  const base = source.slice(lineStart, open).match(/^[ \t]*/)?.[0] ?? "";
+  return `${base}  `;
+}
+
+function looseParse(source: string): unknown {
+  const stripped = stripJsonComments(source).replace(/,\s*([}\]])/g, "$1");
+  return JSON.parse(stripped);
+}
+
+function stripJsonComments(input: string): string {
+  let out = "";
+  let i = 0;
+  let inString = false;
+  let escaped = false;
+  while (i < input.length) {
+    const c = input[i]!;
+    const next = input[i + 1];
+    if (inString) {
+      out += c;
+      if (escaped) escaped = false;
+      else if (c === "\\") escaped = true;
+      else if (c === '"') inString = false;
+      i++;
+      continue;
+    }
+    if (c === '"') {
+      inString = true;
+      out += c;
+      i++;
+      continue;
+    }
+    if (c === "/" && next === "/") {
+      i += 2;
+      while (i < input.length && input[i] !== "\n") i++;
+      continue;
+    }
+    if (c === "/" && next === "*") {
+      i += 2;
+      while (i < input.length && !(input[i] === "*" && input[i + 1] === "/")) i++;
+      i += 2;
+      continue;
+    }
+    out += c;
+    i++;
+  }
+  return out;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function findKeyBrace(source: string, key: string, start: number, end: number): { brace: number } | null {
+  const needle = `"${key}"`;
+  let i = start;
+  let inString = false;
+  let escaped = false;
+  while (i < end) {
+    const c = source[i]!;
+    const next = source[i + 1];
+    if (inString) {
+      if (escaped) escaped = false;
+      else if (c === "\\") escaped = true;
+      else if (c === '"') inString = false;
+      i++;
+      continue;
+    }
+    if (c === '"') {
+      if (source.startsWith(needle, i)) {
+        let j = i + needle.length;
+        while (j < end && /\s/.test(source[j]!)) j++;
+        if (source[j] === ":") {
+          j++;
+          while (j < end && /\s/.test(source[j]!)) j++;
+          if (source[j] === "{") return { brace: j };
+        }
+      }
+      inString = true;
+      i++;
+      continue;
+    }
+    if (c === "/" && next === "/") {
+      i += 2;
+      while (i < end && source[i] !== "\n") i++;
+      continue;
+    }
+    if (c === "/" && next === "*") {
+      i += 2;
+      while (i < end && !(source[i] === "*" && source[i + 1] === "/")) i++;
+      i += 2;
+      continue;
+    }
+    i++;
+  }
+  return null;
+}
+
+function matchBrace(source: string, open: number): number {
+  let depth = 0;
+  let i = open;
+  let inString = false;
+  let escaped = false;
+  while (i < source.length) {
+    const c = source[i]!;
+    const next = source[i + 1];
+    if (inString) {
+      if (escaped) escaped = false;
+      else if (c === "\\") escaped = true;
+      else if (c === '"') inString = false;
+      i++;
+      continue;
+    }
+    if (c === '"') {
+      inString = true;
+      i++;
+      continue;
+    }
+    if (c === "/" && next === "/") {
+      i += 2;
+      while (i < source.length && source[i] !== "\n") i++;
+      continue;
+    }
+    if (c === "/" && next === "*") {
+      i += 2;
+      while (i < source.length && !(source[i] === "*" && source[i + 1] === "/")) i++;
+      i += 2;
+      continue;
+    }
+    if (c === "{") depth++;
+    else if (c === "}") {
+      depth--;
+      if (depth === 0) return i;
+    }
+    i++;
+  }
+  return -1;
+}