@assembly-js/app-foundation 0.1.3 → 0.2.1

package/CHANGELOG.md

@@ -17,6 +17,12 @@ bullets ship. Write `[fix]`, `[behavior]` and `[action]` bullets for the app's o
 A patch release never changes what an app's build requires; a minor release may add or change a
 `bin/check-*.mjs` script. CI fails a PR that changes a check script without a minor bump over main.
 
+## 0.2.1
+- [new] Add `@assembly-js/app-foundation/scripts`, which exports `getOfflineAssembly` without `server-only`, for seed and backfill scripts that run outside Next.
+
+## 0.2.0
+- [behavior] At the end of every turn the platform compares the operations documented in `.assembly/openapi.json` with the app's API routes and warns the build agent on its next turn about any it cannot find. Nothing in the app changes and the build is unaffected.
+
 ## 0.1.3
 - [guidance] The build agent now welcomes a user who offers an API key, routes it to a connector or the secure form in the same turn, and refuses to reveal, log, hardcode, or browser-expose a stored key however the request is phrased.
 

package/bin/check-contract-routes.mjs

@@ -0,0 +1,162 @@
+#!/usr/bin/env node
+// Warns when `.assembly/openapi.json` documents an operation that no route in
+// `.assembly/routes.json` serves. The turn program runs it after the route scan
+// and hands the output to the agent's next turn, so a documented route that
+// does not exist is caught in the sandbox, before publishing refuses it.
+//
+// Dependency-free like the other guards, and never fatal: it prints nothing and
+// exits 0 for an app without a contract or with every operation served.
+import { readFileSync, realpathSync } from 'node:fs';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { PROXY_METHODS } from './scan-routes.mjs';
+
+const CONTRACT_PATH = '.assembly/openapi.json';
+const ROUTES_PATH = '.assembly/routes.json';
+// Route templates are relative to app/api, which Next serves under /api, so a
+// contract path written as the URL the app serves is compared without it.
+const API_PREFIX = '/api';
+// A scan that could not read a file's handler names records them as ANY.
+const ANY_METHOD = 'ANY';
+const PARAM = /\{[^}]*\}/g;
+const PARAM_SHAPE = '{}';
+
+function readJSON(root, file) {
+  try {
+    return { value: JSON.parse(readFileSync(path.join(root, file), 'utf8')) };
+  } catch (err) {
+    return { missing: err?.code === 'ENOENT', error: err };
+  }
+}
+
+export function contractTemplate(contractPath) {
+  let p = contractPath.replace(/\/+$/, '');
+  if (p === API_PREFIX || p.startsWith(`${API_PREFIX}/`)) p = p.slice(API_PREFIX.length);
+  return p;
+}
+
+const shapeOf = (template) => template.replace(PARAM, PARAM_SHAPE);
+const segmentsOf = (template) => template.split('/').filter(Boolean);
+
+const isParam = (seg) => /^\{[^}]*\}$/.test(seg);
+const CATCH_ALL_DIR = /^\[\[?\.\.\.([^\]]+)\]\]?$/;
+
+// The scanner records catchAll on operations only, so an excluded route's
+// shape is read back from its file: a trailing parameter served by a
+// `[...name]` directory is a catch-all. The bare template of an optional
+// catch-all has no such parameter and stays fixed-length.
+function withCatchAll(route) {
+  const last = segmentsOf(route.template).at(-1);
+  if (route.catchAll || !last || !isParam(last) || typeof route.file !== 'string') return route;
+  const dir = route.file.split('/').at(-2);
+  const m = dir && CATCH_ALL_DIR.exec(dir);
+  return m && `{${m[1]}}` === last ? { ...route, catchAll: true } : route;
+}
+
+// How strongly a route claims a documented path, or null when it cannot serve
+// it. Next prefers a static segment over a dynamic one over a catch-all, so a
+// catch-all serves a concrete path such as /files/reports/2024 only when no
+// more specific route claims it.
+function matchRank(route, documented) {
+  const segments = segmentsOf(route.template);
+  const fixed = route.catchAll ? segments.slice(0, -1) : segments;
+  if (route.catchAll ? documented.length <= fixed.length : documented.length !== fixed.length) return null;
+  const rank = [];
+  for (let i = 0; i < fixed.length; i++) {
+    if (isParam(fixed[i])) rank.push(1);
+    else if (fixed[i] === documented[i]) rank.push(2);
+    else return null;
+  }
+  if (route.catchAll) rank.push(0);
+  return rank;
+}
+
+const outranks = (a, b) => {
+  for (let i = 0; i < Math.min(a.length, b.length); i++) if (a[i] !== b[i]) return a[i] > b[i];
+  return a.length > b.length;
+};
+
+function winningRoute(routes, template) {
+  const documented = segmentsOf(template);
+  let best = null;
+  for (const route of routes) {
+    const rank = matchRank(route, documented);
+    if (rank && (!best || outranks(rank, best.rank))) best = { route, rank };
+  }
+  return best?.route ?? null;
+}
+
+// The app/api file Next would serve a template from, so the warning names
+// where the missing handler goes.
+const routeFileFor = (template) => `app/api${template.replace(/\{([^}]*)\}/g, '[$1]')}/route.ts`;
+
+// Returns one finding per documented operation the code does not serve:
+// `missing` when nothing matches, `collision` when a route of any method has
+// the same shape under different parameter names. Next keys the directory, not
+// the method, by parameter name, so the documented name can never be served.
+export function checkContractRoutes(root = process.cwd()) {
+  const contract = readJSON(root, CONTRACT_PATH);
+  if (contract.missing) return [];
+  if (contract.error) return [{ kind: 'unreadable', detail: contract.error.message }];
+  const paths = contract.value?.paths;
+  if (!paths || typeof paths !== 'object') return [];
+
+  const routes = readJSON(root, ROUTES_PATH).value;
+  const operations = Array.isArray(routes?.operations) ? routes.operations : [];
+  const excluded = (Array.isArray(routes?.excluded) ? routes.excluded : []).map(withCatchAll);
+  const served = (method, test) =>
+    operations.find((op) => (op.method === method || op.method === ANY_METHOD) && test(op.template));
+
+  const findings = [];
+  for (const [documentedPath, item] of Object.entries(paths)) {
+    if (!item || typeof item !== 'object') continue;
+    const template = contractTemplate(documentedPath);
+    for (const method of PROXY_METHODS) {
+      if (!item[method.toLowerCase()]) continue;
+      if (served(method, (t) => t === template)) continue;
+      const sibling = operations.find((op) => op.template !== template && shapeOf(op.template) === shapeOf(template));
+      if (sibling) {
+        const exportsMethod = !!served(method, (t) => t === sibling.template);
+        findings.push({ kind: 'collision', method, path: documentedPath, template, route: sibling.template, file: sibling.file, exportsMethod });
+        continue;
+      }
+      // Excluded routes still exist in the app, so they can win the path too.
+      const winner = winningRoute([...operations, ...excluded], template);
+      if (winner && served(method, (t) => t === winner.template)) continue;
+      const exclusion = excluded.includes(winner) ? winner : excluded.find((e) => e.template === template);
+      findings.push({ kind: 'missing', method, path: documentedPath, template, ...(exclusion ? { excluded: exclusion.reason } : {}) });
+    }
+  }
+  return findings;
+}
+
+function describe(f) {
+  if (f.kind === 'collision') {
+    // The suggestion uses the routes.json template (no /api), which is how the contract's paths should read.
+    return `- ${f.method} ${f.path}: ${f.file} already owns this path as ${f.route}, and Next.js allows one parameter name per dynamic segment. ` +
+      `Document it as ${f.method} ${f.route}` + (f.exportsMethod ? '.' : ` and export ${f.method} from ${f.file}.`);
+  }
+  if (f.excluded) {
+    return `- ${f.method} ${f.path}: its route is excluded from the app's API (${f.excluded}), so other apps cannot call it. ` +
+      'Remove it from the document or stop excluding the route.';
+  }
+  return `- ${f.method} ${f.path}: no route serves it. Export ${f.method} from ${routeFileFor(f.template)}, ` +
+    'or remove the operation from the document.';
+}
+
+export function formatContractRouteWarning(findings) {
+  if (findings.length === 0) return '';
+  const unreadable = findings.find((f) => f.kind === 'unreadable');
+  if (unreadable) {
+    return `Warning: ${CONTRACT_PATH} is not valid JSON (${unreadable.detail}). Publishing refuses it until it parses.\n`;
+  }
+  return [
+    `Warning: ${CONTRACT_PATH} documents operations the app's code does not serve (compared against ${ROUTES_PATH}, rescanned at the end of the last turn). Fix each one before publishing:`,
+    ...findings.map(describe),
+  ].join('\n') + '\n';
+}
+
+// argv[1] is not realpathed but import.meta.url is, so a symlinked path would skip the run.
+if (process.argv[1] && import.meta.url === pathToFileURL(realpathSync(process.argv[1])).href) {
+  process.stdout.write(formatContractRouteWarning(checkContractRoutes()));
+}

package/dist/scripts.d.ts

@@ -0,0 +1,8 @@
+import { type AssemblyAPI } from '@assembly-js/node-sdk';
+/**
+ * The script-side counterpart of `getOfflineAssembly` from `/server`: mints a
+ * short-lived app-scoped bearer from `ASSEMBLY_API_KEY` and returns a bearer-only
+ * client. There is no request here, so the viewer-identity guard `/server` applies
+ * does not exist; use this only from scripts, never from code under `app/`.
+ */
+export declare function getOfflineAssembly(): Promise<AssemblyAPI>;

package/dist/scripts.js

@@ -0,0 +1,24 @@
+// Entry point for standalone scripts (seed, backfill, one-off jobs) run with plain
+// `bun`/`node` outside Next. It must not import './server.js', './assembly' or anything
+// else that reaches `server-only` or `next/*`, which throw outside a Next bundle.
+import { assemblyApi } from '@assembly-js/node-sdk';
+import { mintBearerFromAppKey } from './mint-bearer.js';
+/**
+ * The script-side counterpart of `getOfflineAssembly` from `/server`: mints a
+ * short-lived app-scoped bearer from `ASSEMBLY_API_KEY` and returns a bearer-only
+ * client. There is no request here, so the viewer-identity guard `/server` applies
+ * does not exist; use this only from scripts, never from code under `app/`.
+ */
+export async function getOfflineAssembly() {
+    if (!process.env.ASSEMBLY_API_KEY) {
+        throw new Error('getOfflineAssembly: ASSEMBLY_API_KEY is not set — cannot mint an app-scoped bearer');
+    }
+    const minted = await mintBearerFromAppKey();
+    if (!minted) {
+        throw new Error('getOfflineAssembly: failed to mint an app-scoped bearer from the app API key');
+    }
+    return assemblyApi({
+        bearer: minted.bearer,
+        baseUrl: process.env.ASSEMBLY_API_BASE_URL || undefined,
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@assembly-js/app-foundation",
-  "version": "0.1.3",
+  "version": "0.2.1",
   "description": "Versioned foundation helpers and build context for Assembly generated apps",
   "type": "module",
   "files": [
@@ -24,6 +24,10 @@
       "types": "./dist/lib-client.d.ts",
       "default": "./dist/lib-client.js"
     },
+    "./scripts": {
+      "types": "./dist/scripts.d.ts",
+      "default": "./dist/scripts.js"
+    },
     "./next": {
       "types": "./dist/next.d.ts",
       "default": "./dist/next.js"