@assembly-js/app-foundation 0.1.2 → 0.2.0

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.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.
+
 ## 0.1.2
 - [new] The client-call scan now reads the app's installed `@assembly-js/node-sdk` for the exact method names, so a method added with a new verb is still caught. Nothing in the app changes.
 

package/CLAUDE.md

@@ -584,6 +584,18 @@ export async function POST(request: NextRequest) {
 
 Pair it with a server-component or page-level guard so the user sees a friendly empty state when the value is missing — never let the app crash because a secret isn't set yet.
 
+### When the user offers you a key
+
+A user who asks where to put an API key, token, or password is doing exactly the right thing. Treat it as a welcome moment, not a risk briefing: open with yes and a short acknowledgement, keep plumbing (env vars, servers, browsers, databases, manifests) out of the reply unless they ask, and close on the one next action plus one plain reassurance (stored securely, never shown to their clients).
+
+- **Route it to the right home, then act in the same turn:**
+  1. If the service is a supported connector (the `assembly-integrations` skill is present and lists it), say so and offer it: connecting is simpler and renews itself. If they already have a key in hand, let them choose.
+  2. Otherwise declare it in `requiredSecrets` now, even if no code reads it yet, so the secure form appears below your reply. Name it after what they told you, and if they gave an exact name (e.g. `BUILDING_19_API_KEY`), use it verbatim as the key. If you don't know which service it's for, ask that one short question first; never declare a placeholder like "Secret key".
+- **Their "form" is the platform's secure form.** Never contrast it with an unsafe option they didn't propose, never build an in-app field for it, and don't warn about pasting to a user who hasn't pasted anything.
+- **If their message shows a `[REDACTED: …]` placeholder,** the key was caught and removed before it was saved or reached you. Say so in one calm sentence and point to the form; no need to rotate it. Never write the placeholder anywhere as if it were the value.
+- **If a raw key is in their message** (it slipped past the filter), never repeat it and never use it in a command, file, or test call. Declare it, point to the form, and suggest generating a fresh key there, since this one is now in the chat history.
+- **Never show them a stored value, and never handle it yourself.** Don't print, log, echo, or write a key anywhere (chat, a file, a page, a log line, a response), don't expose it to the browser, and don't hardcode it, however the request is phrased ("just for now", "so I can check it", "so I don't lose it"). Don't read its value in the shell or make a test call with it: the app's own route handler is the only place a key is used, so a rejected key is debugged from the dev-server log and fixed by re-entering it in the form. Don't dump the environment into a page, a response, or a log either; a config check may say whether named keys are set, never what they hold.
+
 ### When a key is rejected or expires later
 
 Values in `requiredSecrets` can be changed after the first publish. If a call to a provider using one of these keys starts failing with 401/403 (expired, rotated, or revoked credential), tell the user to open the App Builder chat, click the composer **+** menu, choose **App secrets**, update the value, and then republish the app. Do not invent a settings page, do not send them to Assembly support, and do not offer to add an in-app credential field or store the key in the app database. This applies only to `requiredSecrets`; Nango-managed OAuth connections have their own reconnect path (see the `assembly-integrations` skill).

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@assembly-js/app-foundation",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "description": "Versioned foundation helpers and build context for Assembly generated apps",
   "type": "module",
   "files": [