@assembly-js/app-foundation 0.0.2 → 0.0.4

package/CLAUDE.md

@@ -31,7 +31,7 @@ Assembly-specific gotchas live in `.claude/skills/<name>/SKILL.md`. Invoke them
 <!-- /feature:notification-settings -->
 - `clearing-client-notifications` — REQUIRED when the app sends client notifications: clear the portal sidebar badge with markNotificationRead (clear-on-view vs clear-on-action)
 <!-- feature:api-resources -->
-- `assembly-automations` — declare the app's API contract in `.assembly/api-resources.json` (a separate file from `app.json`): domain events that become automation triggers + workspace webhooks, and staff-invokable operations that become automation actions. Declared events must also be emitted at runtime, reporting the acting user on the documented headers — declaring alone never fires anything. Read it before adding either.
+- `assembly-automations` — REQUIRED when the request asks for a platform-side effect in reaction to an in-app event (a message, a CRM field, a contract, a form, a file — not the app's own tables), even if the user never says "automation": declare the app's API contract in `.assembly/api-resources.json` (a separate file from `app.json`) — domain events that become automation triggers + workspace webhooks, and staff-invokable operations that become automation actions. Declared events must also be emitted at runtime, reporting the acting user on the documented headers — declaring alone never fires anything. Read it before adding either.
 <!-- /feature:api-resources -->
 - `assembly-app-surfaces` — REQUIRED before writing `.assembly/app.json`: declare which surfaces (dashboard, client portal, notification) the app exposes; omitting the client surface keeps the app off client portal nav entirely
 - `assembly-app-bridge-header` — breadcrumbs (don't include app name), CTAs
@@ -125,6 +125,10 @@ The `surfaces` field in `.assembly/app.json` declares **surface types** (dashboa
 ## What's already built in — DO NOT REINVENT
 
 Before adding a feature, check whether Assembly already covers it. If it does, **use the existing module via the SDK** instead of rebuilding.
+<!-- feature:api-resources -->
+
+**Then ask who should perform it — you or the platform.** Reaching a module through the SDK is right when the user is doing the thing *now*: they pressed a button and are watching it happen. When the effect should instead happen *in reaction to* something that happens in the app ("when a project is completed, message the client"), that is a workflow that integrates with the Assembly platform, and **the platform performs it, not your code.** The test is where the effect lands: on Assembly's own data rather than only in your app's tables. Decide this **before** you write or plan the call — read the `assembly-automations` skill to decide it, and don't reach for the module's SDK method until you have.
+<!-- /feature:api-resources -->
 
 **Built-in modules (core, available in every portal):**
 
@@ -207,7 +211,10 @@ Two things flow into the running app from Assembly:
 
 ## Third-party APIs and secrets
 
-Any external service (SendGrid, Twilio, Resend, a niche SaaS, an API-key-only service) reaches its credential the same way: it **must** flow through `process.env` and be declared in the app manifest, per the rules below. Managed OAuth integrations are not available here — there is no provider whose credential the platform brokers for you.
+Two paths, decided by whether an `assembly-integrations` skill is present and, if so, its supported-provider list:
+
+- **Supported OAuth provider (e.g. Slack), when the `assembly-integrations` skill is present:** use `requiredIntegrations` + `getIntegration()` from `@assembly-js/app-foundation/server` — no credential, no env var, no `requiredSecrets` entry. The skill covers this; read it before deciding.
+- **Anything else** (SendGrid, Twilio, Resend, a niche SaaS, an API-key-only service), or **any external service when the `assembly-integrations` skill is absent** (managed OAuth is not available for this workspace): the credential **must** flow through `process.env` and be declared in the app manifest, per the rules below.
 
 ### Two rules
 
@@ -697,11 +704,14 @@ Everything above resolves the **viewer's** bearer from the request cookie. Some
 
 ```ts
 // app/api/cron/digest/route.ts — Vercel cron or a webhook handler
-import { getOfflineAssembly } from '@assembly-js/app-foundation/server';
+import { getOfflineAssembly, listAll } from '@assembly-js/app-foundation/server';
 
 export async function GET() {
   const assembly = await getOfflineAssembly(); // app-scoped, no cookie needed
-  const { data: clients = [] } = await assembly.listClients();
+  // Background work must cover everyone — walk every page (see Pagination).
+  const clients = await listAll((nextToken) =>
+    assembly.listClients({ nextToken, limit: 100 }),
+  );
   // …do the background work (send a digest, reconcile state, etc.)…
   return Response.json({ ok: true });
 }
@@ -971,11 +981,11 @@ Keys in the `customFields` object are the field's `key` property (from `listCust
 
 The same rule applies to every native resource the app points at: a message channel, a form, a portal file or file channel. You MUST NOT hardcode one of their IDs in code. Those IDs are minted per workspace and are only valid in the workspace they came from — paste one into source and the feature works exactly once, in the workspace you built it in. Everywhere else the lookup returns nothing and the feature silently does nothing, or the call fails. No data fix can reach it, because the broken value is in the code.
 
-List, then match on a stable attribute the workspace owner controls — or resolve the resource from the current request's identity:
+List — paging through every page, or the match false-negatives once the workspace outgrows one page — then match on a stable attribute the workspace owner controls, or resolve the resource from the current request's identity:
 
 ```ts
 // A form, by the user's wording. The display name is on `fields`, not the form.
-const { data: forms = [] } = await assembly.listForms({});
+const forms = await listAll((nextToken) => assembly.listForms({ nextToken, limit: 100 }));
 const intakeForm = forms.find((f) => f.fields?.name?.toLowerCase().includes('intake'));
 if (!intakeForm?.id) {
   return <div>The intake form hasn&apos;t been set up in this workspace yet.</div>;
@@ -1045,21 +1055,20 @@ if (!res.ok) {
 
 ### Pagination
 
-List methods take `limit` (default ~20, max 100) and `nextToken` (cursor). The response is `{ data: [...], nextToken: string | null }`. Loop until `nextToken` is null:
+List methods take `limit` (default ~20, max 100) and `nextToken` (cursor). The response is `{ data, nextToken }`, and one call returns only the first page — a list rendered from it looks correct until the workspace has more than ~20 rows.
+
+`@assembly-js/app-foundation/client` exports `listAll` for the whole walk — import it, don't rewrite it. It works for any `list*` method, since they all share that envelope:
 
 ```ts
-async function listAllClients() {
-  const all = [];
-  let cursor: string | undefined;
-  do {
-    const page = await assembly.listClients({ limit: 100, nextToken: cursor });
-    all.push(...page.data);
-    cursor = page.nextToken ?? undefined;
-  } while (cursor);
-  return all;
-}
+import { listAll } from '@assembly-js/app-foundation/client';
+
+const clients = await listAll((nextToken) =>
+  assembly.listClients({ limit: 100, nextToken }),
+);
 ```
 
+Pass `limit: 100` (the max) so the walk makes 5x fewer round trips than the ~20 default.
+
 ---
 
 ## Client-side SDK: `@assembly-js/app-bridge`
@@ -1118,8 +1127,12 @@ Use `AssemblyBridge.header.*` for breadcrumbs, CTAs, and actions menu. See `.cla
 - ❌ Don't use `Select` or `Combobox` to pick any Assembly person or organization record (clients, internal users, team members, staff, companies). Always use `UserCompanySelector` — in forms, filters, dropdowns, "assign to" controls, everywhere.
 - ❌ Don't use `Combobox` when the user asks for a "dropdown" or "select" — use `Select`. Only use `Combobox` when the user explicitly needs type-to-search/filter functionality for non-user/non-company data.
 - ❌ Don't manually render the selected value in a `Select` trigger. Use `<SelectValue placeholder="..." />` inside `SelectTrigger` **and** pass `items={options}` to the `<Select>` root — without `items`, Base UI cannot resolve labels and will display raw values (UUIDs) in the trigger. See "Select and Combobox — base-ui differences" for the full pattern.
-- ❌ Don't ship a third-party API call without a `requiredSecrets` entry for its credential in `.assembly/app.json`. The deploy pipeline reads the manifest to know what to ask the user for — without it, the credential is never set and the app stays broken. See "Third-party APIs and secrets" above.
+- ❌ Don't ship a third-party API call without its manifest entry: `requiredIntegrations` for supported OAuth providers (when the `assembly-integrations` skill is present — see it), `requiredSecrets` for everything else. The deploy pipeline reads the manifest to know what to ask the user for — without it, the credential is never set and the app stays broken. See "Third-party APIs and secrets" above.
 - ❌ Don't read third-party credentials from anywhere other than `process.env` (no DB, no URL params, no client bundle, no hardcoded defaults, no `.env*` files committed to the repo).
+<!-- feature:api-resources -->
+- ❌ Don't create `.assembly/api-resources.json` unless **both** are true: the request is reactive (something happens *because* an in-app event happened, not because the user pressed a button), **and** the effect lands on the Assembly platform — a message, a client/company custom field, a contract, a form, a file. "When a time entry is logged, message the contact" qualifies even though the user never says "automation". A reaction that only writes the app's own tables does not, a platform write the user triggers directly does not, and a domain full of automatable mutations does not; an unrequested declaration surfaces actions to every workspace admin in the automation builder. When both *are* true, see the `assembly-automations` skill — declare and emit the trigger rather than hard-coding the platform-side action, and never put `apiResources` in `.assembly/app.json`; they are separate files with different owners.
+- ❌ Don't declare an `exposeToAutomations` operation without serving an authenticated route at that record's `baseUrl` — the platform calls it with a query-string app token that `requireAuth` cannot read, so hand-rolled auth here silently yields a public endpoint that mutates workspace data. Read the `assembly-automations` skill's "Serving actions" section and copy its wrapper.
+<!-- /feature:api-resources -->
 
 ---
 

package/bin/check-route-reachability.mjs

@@ -0,0 +1,129 @@
+#!/usr/bin/env node
+// Fails the build when a page route is orphaned — no link, router.push,
+// redirect, or header-CTA target anywhere else in the app points at it.
+// Next.js happily builds and typechecks a page nothing links to, so an
+// unreachable page ships silently; when that page manages a prerequisite
+// resource (e.g. stages that cases require), the whole primary flow dies
+// with it. Dependency free on purpose: it runs inside the generated app's
+// sandbox before any deps beyond Node are guaranteed. Known limit: matching
+// is statically evident string references — fully dynamic path construction
+// is out of scope (the gate guards against pages the agent forgot to link,
+// not obfuscation).
+import { readFileSync, readdirSync, existsSync } from 'node:fs';
+import { join, relative, sep } from 'node:path';
+
+const ROOT = process.cwd();
+const APP_DIR = join(ROOT, 'app');
+const MANIFEST = join(ROOT, '.assembly', 'app.json');
+
+// Surface entry routes are loaded directly by the host portal, so they need
+// no in-app inbound link. Mirrors .assembly/check-token-usage.mjs: only
+// declared surfaces qualify; '/' alone when no manifest declares any.
+function allowedEntryRoutes() {
+  const defaults = ['/'];
+  try {
+    const manifest = JSON.parse(readFileSync(MANIFEST, 'utf8'));
+    const declared = ['internal', 'client', 'notification']
+      .map((k) => manifest?.surfaces?.[k]?.path)
+      .filter((p) => typeof p === 'string' && p.startsWith('/'))
+      .map((p) => (p === '/' ? p : p.replace(/\/+$/, '')));
+    if (declared.length > 0) return new Set(declared);
+  } catch {
+    // fall through to defaults
+  }
+  return new Set(defaults);
+}
+
+function sourceFiles(dir) {
+  const out = [];
+  if (!existsSync(dir)) return out;
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    const full = join(dir, entry.name);
+    if (entry.isDirectory()) {
+      if (entry.name === 'node_modules' || entry.name === '.next') continue;
+      out.push(...sourceFiles(full));
+    } else if (/\.(tsx|ts|jsx|js|mjs)$/.test(entry.name)) {
+      out.push(full);
+    }
+  }
+  return out;
+}
+
+// The URL route a page file serves; route groups `(group)` and parallel-route
+// slots `@slot` never appear in the URL.
+function routeForPageFile(file) {
+  const segments = relative(APP_DIR, file).split(sep).slice(0, -1);
+  const urlSegments = segments.filter(
+    (seg) => !(seg.startsWith('(') && seg.endsWith(')')) && !seg.startsWith('@'),
+  );
+  return '/' + urlSegments.join('/');
+}
+
+if (!existsSync(APP_DIR)) process.exit(0);
+
+const allowed = allowedEntryRoutes();
+const files = [
+  ...sourceFiles(APP_DIR),
+  ...sourceFiles(join(ROOT, 'components')),
+  ...sourceFiles(join(ROOT, 'lib')),
+];
+const pageFiles = files.filter((f) =>
+  /^page\.(tsx|ts|jsx|js)$/.test(f.split(sep).pop()),
+);
+const contents = new Map(files.map((f) => [f, readFileSync(f, 'utf8')]));
+
+function escapeRe(s) {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+// A reference is the route appearing as a string/template path in any file
+// other than the page's own: href="/setup", router.push('/setup'),
+// redirect(`/setup?tab=1`), an actions-menu handler, etc. Dynamic routes
+// match on the static prefix before the first dynamic segment, so a list
+// page's `/cases/${id}` satisfies /cases/[id] (and its descendants — a
+// detail page is the click-path to its own sub-routes).
+function referencePattern(route) {
+  const dynIdx = route.indexOf('[');
+  if (dynIdx === -1) {
+    // Full path, terminated so /setup doesn't match /setup2 or /foo/setup.
+    return new RegExp(`['"\`]${escapeRe(route)}(?:['"\`?#]|\\$\\{)`);
+  }
+  const prefix = route.slice(0, dynIdx); // includes trailing '/'
+  if (prefix === '/') return null; // root-level dynamic route: not statically checkable
+  return new RegExp(`['"\`]${escapeRe(prefix)}`);
+}
+
+const violations = [];
+for (const file of pageFiles) {
+  const route = routeForPageFile(file);
+  if (allowed.has(route)) continue;
+  const pattern = referencePattern(route);
+  if (!pattern) continue;
+  const referenced = files.some(
+    (other) => other !== file && pattern.test(contents.get(other)),
+  );
+  if (!referenced) {
+    violations.push(`${relative(ROOT, file).split(sep).join('/')}  (route ${route})`);
+  }
+}
+
+if (violations.length > 0) {
+  console.error('');
+  console.error('Unreachable page routes — nothing in the app links to them:');
+  console.error('');
+  for (const v of violations) console.error('  - ' + v);
+  console.error('');
+  console.error(
+    'Every page needs a click path from a surface entry route (' +
+      [...allowed].join(', ') +
+      '):',
+  );
+  console.error('a <Link>, router.push, redirect, header primaryCta/secondaryCta, or');
+  console.error('actions-menu item on an already-reachable page must point at it.');
+  console.error('');
+  console.error('If the page manages a prerequisite resource (e.g. stages that cases');
+  console.error('require, templates that documents require), add its entry point next to');
+  console.error("the dependent flow — e.g. an actions-menu item on the main view and a");
+  console.error('link on the empty state that blocks on it.');
+  process.exit(1);
+}

package/bin/check-token-usage.mjs

@@ -0,0 +1,128 @@
+#!/usr/bin/env node
+// Fails the build if any page reads the session token from `searchParams`.
+// Dependency-free on purpose: it runs inside the generated app's sandbox before
+// any deps beyond Node exist.
+//
+// Auth is cookie-borne in the bearer model: the foundation middleware exchanges
+// the first-load `?token=` for an HttpOnly bearer cookie exactly once, and
+// getAssembly() / getSessionIdentity() read that cookie. No page needs
+// `searchParams.token` — not even a surface entry page. A page gated on it
+// renders its auth-rejection state to everyone after any client-side navigation
+// (`router.push`, `<Link>`), which drops query params. Fetch per-user data via
+// server actions (useServerAction) or authFetch route handlers instead.
+import { readFileSync, readdirSync, existsSync } from 'node:fs';
+import { join, relative, sep } from 'node:path';
+
+const ROOT = process.cwd();
+const APP_DIR = join(ROOT, 'app');
+
+function pageFiles(dir) {
+  const out = [];
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    const full = join(dir, entry.name);
+    if (entry.isDirectory()) {
+      if (entry.name === 'node_modules') continue;
+      out.push(...pageFiles(full));
+    } else if (/^page\.(tsx|ts|jsx|js)$/.test(entry.name)) {
+      out.push(full);
+    }
+  }
+  return out;
+}
+
+// A 'use client' page never has the dangerous dependency: it holds no token at
+// all (identity comes from useAssembly()), and useSearchParams-for-filters is a
+// different mechanism than the server `searchParams` prop this targets. The
+// failure class is server components reading the URL token, so client files are
+// skipped. The directive must be the file's first statement; allow leading
+// comments/whitespace.
+function isClientComponent(content) {
+  const head = content
+    .replace(/^\uFEFF/, '')
+    .replace(/^(?:\s*(?:\/\/[^\n]*\n|\/\*[\s\S]*?\*\/))*\s*/, '');
+  return /^['"]use client['"]/.test(head);
+}
+
+// True when the file reads a `token` property off the route's searchParams —
+// directly, via destructuring, bracket access, optional chaining, or through
+// any chain of local aliases (const sp = searchParams; const p = await sp;
+// p['token']). Alias tracking is a fixpoint over simple assignments, so
+// indirection depth doesn't matter. Pattern-based on purpose (no AST dependency
+// inside the sandbox); these are the shapes generated server components actually
+// produce. Known limit: statically evident reads only — dynamic key construction
+// or cross-file data flow is out of scope (this guards code an agent naturally
+// writes, not obfuscation).
+function readsTokenFromSearchParams(content) {
+  if (!content.includes('searchParams')) return false;
+  // Every local name that transitively aliases searchParams, awaited or not.
+  // Seed with destructuring renames of the prop itself: ({ searchParams: sp }).
+  const names = new Set(['searchParams']);
+  for (const m of content.matchAll(/\bsearchParams\s*:\s*(\w+)/g)) {
+    names.add(m[1]);
+  }
+  // Optional TS type annotation between the name and '=' (const p: SP = ...).
+  const aliasRe = /(?:const|let|var)\s+(\w+)(?:\s*:\s*[^=;]+)?\s*=\s*(?:await\s+)?(?:props\s*\.\s*)?(\w+)\b/g;
+  let grew = true;
+  while (grew) {
+    grew = false;
+    for (const m of content.matchAll(aliasRe)) {
+      if (names.has(m[2]) && !names.has(m[1])) {
+        names.add(m[1]);
+        grew = true;
+      }
+    }
+  }
+  // Bracket keys: the 'token' literal plus any const bound to it.
+  const tokenKeys = ["'token'", '"token"'];
+  for (const m of content.matchAll(/(?:const|let|var)\s+(\w+)\s*=\s*['"]token['"]/g)) {
+    tokenKeys.push(m[1]);
+  }
+  const bracketKey = `(?:${tokenKeys
+    .map((k) => k.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'))
+    .join('|')})`;
+  for (const rawName of names) {
+    const name = rawName.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    // name.token / name?.token / name['token'] / (await name).token variants
+    if (
+      new RegExp(
+        `\\b${name}\\s*\\)?\\s*(?:!\\s*)?(?:(?:\\?\\.|\\.)\\s*token\\b|(?:\\?\\.)?\\s*\\[\\s*${bracketKey}\\s*\\])`,
+      ).test(content)
+    ) {
+      return true;
+    }
+    // const { token } = name / = await name
+    if (
+      new RegExp(
+        `\\{[^}]*\\btoken\\b[^}]*\\}\\s*=\\s*(?:await\\s+)?(?:props\\s*\\.\\s*)?${name}\\b\\s*!?`,
+      ).test(content)
+    ) {
+      return true;
+    }
+  }
+  return false;
+}
+
+if (!existsSync(APP_DIR)) process.exit(0);
+
+const violations = [];
+for (const file of pageFiles(APP_DIR)) {
+  const content = readFileSync(file, 'utf8');
+  if (isClientComponent(content)) continue;
+  if (readsTokenFromSearchParams(content)) {
+    violations.push(relative(ROOT, file).split(sep).join('/'));
+  }
+}
+
+if (violations.length > 0) {
+  console.error('');
+  console.error('A page reads the session token from searchParams:');
+  console.error('');
+  for (const v of violations) console.error('  - ' + v);
+  console.error('');
+  console.error('Auth is in the bearer cookie, not the URL — no page, not even a surface');
+  console.error('entry page, should read searchParams.token. getAssembly() and');
+  console.error('getSessionIdentity() read the bearer cookie; fetch per-user data via');
+  console.error('server actions (useServerAction) or authFetch route handlers.');
+  console.error('See CLAUDE.md and the assembly-session-token skill.');
+  process.exit(1);
+}

package/bin/push-schema.mjs

@@ -0,0 +1,70 @@
+#!/usr/bin/env node
+// Pushes the Drizzle schema to the provisioned Neon database at build time,
+// then smoke-checks that the expected tables were created. Exits 0 silently
+// when DATABASE_URL is absent (snapshot builds run without a real database).
+import { execFileSync } from "node:child_process";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+const DATABASE_URL = process.env.DATABASE_URL?.trim();
+if (!DATABASE_URL) {
+  process.exit(0);
+}
+
+const schemaPath = join(process.cwd(), "lib", "schema.ts");
+let schemaSource = "";
+try {
+  schemaSource = readFileSync(schemaPath, "utf8");
+} catch {
+  // schema.ts missing: drizzle-kit will report its own error below.
+}
+
+// drizzle-kit is a dev dependency; its binary lives in node_modules/.bin.
+const drizzleKit = join(process.cwd(), "node_modules", ".bin", "drizzle-kit");
+try {
+  execFileSync(drizzleKit, ["push", "--force"], {
+    stdio: "inherit",
+    env: process.env,
+  });
+} catch (err) {
+  if (err.code === "ENOENT") {
+    console.error(
+      "\ndrizzle-kit binary not found — run `bun install` before building.",
+    );
+  } else {
+    console.error(
+      "\ndrizzle-kit push failed — database schema was not applied.",
+    );
+  }
+  process.exit(1);
+}
+
+// Smoke-check: verify each pgTable() declared in lib/schema.ts exists in the
+// database. Checking specific names avoids a false-pass when pre-existing tables
+// from a prior deployment make the total count non-zero.
+const tableNames = [
+  ...schemaSource.matchAll(/pgTable\s*\(\s*['"]([^'"]+)['"]/g),
+].map((m) => m[1]);
+if (tableNames.length === 0) {
+  process.exit(0);
+}
+
+const { neon } = await import("@neondatabase/serverless");
+const sql = neon(DATABASE_URL);
+const rows = await sql`
+  SELECT table_name
+  FROM information_schema.tables
+  WHERE table_schema = 'public' AND table_type = 'BASE TABLE'
+`;
+const found = new Set(rows.map((r) => r.table_name));
+const missing = tableNames.filter((t) => !found.has(t));
+if (missing.length > 0) {
+  console.error(
+    `\nSchema push reported success but the following table(s) are missing: ${missing.join(", ")}.`,
+    "\nVerify that DATABASE_URL points to the correct Neon project and that lib/schema.ts exports valid pgTable() definitions.",
+  );
+  process.exit(1);
+}
+console.log(
+  `Schema verified: ${tableNames.length} table(s) confirmed (${tableNames.join(", ")}).`,
+);