@assembly-js/app-foundation 0.0.51 → 0.0.53

package/CHANGELOG.md

@@ -14,6 +14,13 @@ A foundation update reads the sections between an app's version and the target:
 from every bullet except `[guidance]`, agent work from the check scripts those `[action]`
 bullets ship. Write `[fix]`, `[behavior]` and `[action]` bullets for the app's owner.
 
+## 0.0.53
+- [action] A page or server action that calls a helper exported from a client-component file errors for every visitor who opens it; the build now reports the call, and the helper moves to a plain module both sides import.
+- [guidance] Tell the build agent that a helper shared between a server-rendered page and a client component belongs in a plain module, not the client component's file.
+
+## 0.0.52
+- [guidance] The build agent is told that the CRM tab loads the app's client route as staff, with the client or company of that page in the token, so it renders a staff view scoped to that record instead of the client view or an error. It is also told to send notifications for submissions, status changes, approvals and required alerts even when the request does not mention notifications.
+
 ## 0.0.51
 - [guidance] The build agent is told that its preview is `localhost:3000` and that the public sandbox host is unreachable from inside the sandbox.
 

package/CLAUDE.md

@@ -31,10 +31,10 @@ Assembly-specific gotchas live in `.claude/skills/<name>/SKILL.md`. Invoke them
 - `assembly-native-resources` — native message channels, forms, portal files/file channels: never hardcode their IDs, discover them at runtime
 - `assembly-mutations` — minimal `requestBody` rule for `update*` calls
 <!-- !feature:notification-settings -->
-- `assembly-notifications` — in-product + email notifications via createNotification; `ctaParams` for notification CTA URLs (the `/n` surface renders from those, not the best-effort `notificationId` claim)
+- `assembly-notifications` — in-product + email notifications via createNotification; `ctaParams` for notification CTA URLs (the `/n` surface renders from those, not the best-effort `notificationId` claim) Send them unprompted when the app has submissions, status changes, approvals, or alerts someone must act on, even if the request never says "notify".
 <!-- /feature:notification-settings -->
 <!-- feature:notification-settings -->
-- `assembly-notifications` — in-product + email notifications via createNotification; `ctaParams` for notification CTA URLs (the `/n` surface renders from those, not the best-effort `notificationId` claim); per-user toggleable categories via manifest `notificationSettings` + `notificationSettingId`
+- `assembly-notifications` — in-product + email notifications via createNotification; `ctaParams` for notification CTA URLs (the `/n` surface renders from those, not the best-effort `notificationId` claim); per-user toggleable categories via manifest `notificationSettings` + `notificationSettingId` Send them unprompted when the app has submissions, status changes, approvals, or alerts someone must act on, even if the request never says "notify".
 <!-- /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 -->
@@ -138,6 +138,8 @@ The token tells you which type the current viewer is:
 
 The app should **detect the viewer type from the token** and render audience-appropriate UI. Don't show "Create new" buttons to clients if creation is staff-only.
 
+**The CRM tab runs your client route as staff.** It loads the same `clientUrl` as the Client Portal, but its token carries the staff member's `internalUserId` plus the record the tab sits on: `clientId` (with its `companyId`) on a client's page, `companyId` alone on a company's page. So every page under the client surface has three viewers: a client, staff on a client's tab, and staff on a company's tab. Check `internalUserId` first. When it is set, render the staff view of that client or company, with the actions staff take there (review, upload, manage), never the client-only view and never a "portal users only" error. On a company's tab, show that company's records only, not the whole workspace.
+
 **The CRM tab is never the only path to per-client data.** The CRM tab is a shortcut: it renders with a specific `clientId`/`companyId` already in the token. But any client/company-specific data or action it exposes must *also* be reachable from the Dashboard main view — even if it takes a few clicks. Build the main view so an internal user can browse to a specific client/company (a list, or a `UserCompanySelector` that drills into a per-entity detail screen) and reach the same data and actions there. The main-view detail screen doesn't have to match the CRM-tab layout — it can reuse the same components or present them differently — but the main view must never be empty or aggregate-only when the CRM tab has per-client functionality. Don't leave `internalUrl` as a dead end.
 
 <!-- !feature:app-owned-header -->
@@ -668,6 +670,8 @@ If `tsc --noEmit` is clean and the task says "verify the build", run `bun run bu
 
 `bun run build` also **fails** if any page reads `searchParams.token`. Auth is in the bearer cookie, not the URL — no page (not even a surface entry page) needs it; `getAssembly()` / `getSessionIdentity()` read the bearer. Fix as the error instructs — fetch that page's data via `useServerAction`/`authFetch` instead. Run `bun run check:token-usage` to check it on its own.
 
+`bun run build` also **fails** if server code calls a function it imported from a `'use client'` file — a page, layout, or server action, or any module they import that has no directive, calling a helper that lives next to a client component. The server receives a client reference, not the function, so the page 500s at request time while `tsc` passes. Fix as the error instructs — move the helper to a plain module with no directive that both sides import. Run `bun run check:client-boundary` to check it on its own.
+
 <!-- !feature:app-owned-header -->
 `bun run build` also **fails** if a page route is unreachable — no link, `router.push`, redirect, or header CTA anywhere else points at it. Fix as the error instructs by adding an entry point on a reachable page. Run `bun run check:route-reachability` to check it on its own.
 <!-- /feature:app-owned-header -->
@@ -1472,6 +1476,7 @@ Use `AssemblyBridge.header.*` for breadcrumbs, CTAs, and actions menu. See `.cla
 - ❌ Don't preview a PDF (or any file) in an `<iframe>`, `<embed>` or `<object>` — the portal frame is sandboxed and Chrome won't run its PDF viewer inside it, so the preview renders blank while the build passes. Open the pre-signed URL in a new tab (`assembly-storage` Pattern A) or render pages to a canvas client-side with `next/dynamic` + `ssr: false`.
 - ❌ Don't call a change verified, working, or safe to publish because `tsc --noEmit` and `bun run build` passed — name the checks that ran and the signed-in screens left unopened. See "What a passing build proves" above.
 - ❌ Don't pass a function — or an object that holds one, like a question/field config with `visibleWhen`, `validate`, `render`, or `format` callbacks — as a prop from a server component or page into a `'use client'` component. Props cross that boundary as serialized data, so the render throws `Functions cannot be passed directly to Client Components` and the page 500s for every visitor no matter what the record holds. `tsc --noEmit` and `bun run build` both pass. Keep such a config in a shared module the client component imports itself, or express the logic as data (`{ showWhen: { field: 'entityType', equals: 'llc' } }`) and interpret it client-side.
+- ❌ Don't call a function imported from a `'use client'` file from a server component, layout, or server action — e.g. an answer formatter defined in the client component file that the `/n` notification page also renders. The server gets a client reference, not the function, so the render throws and the route 500s for every visitor; `tsc --noEmit` passes. A `'use client'` file should export only components and hooks; put a shared helper in a plain module (`lib/…`) both sides import. `bun run build` fails on this (`check:client-boundary`).
 - ❌ 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.

package/bin/check-client-boundary.mjs

@@ -0,0 +1,304 @@
+#!/usr/bin/env node
+// Fails the build when server code calls a function it imported from a
+// 'use client' module. Next hands server code a client *reference* for every
+// export of such a module: rendering one as JSX is fine, calling one throws
+// ("Attempted to call X() from the server but X is on the client"), and the
+// route answers 500 for every visitor. tsc and `next build` both pass — the
+// module typechecks, and a dynamic page is never prerendered — so the agent's
+// own build is the only gate that sees it before a user does.
+//
+// Server code is found by walking imports from Next's server entry files under
+// app/ (page, layout, route, …) and from 'use server' modules, stopping at the
+// first 'use client' module; everything reached without crossing that line is
+// evaluated on the server. Parsed with the app's own TypeScript, parse-only
+// like scan-routes.mjs (ts.createSourceFile, no Program, no type check): an
+// import is an edge only when it survives to the emitted module, and a finding
+// is a real call, `new`, or tagged template whose callee is an imported
+// binding — never a name inside a string, a comment, or JSX text. A binding the
+// file also declares locally is left alone rather than guessed at. Known
+// limits: a binding re-exported through a barrel, and a helper in a shared
+// module that only client code ever calls, are reported or missed by shape
+// (the fix — a helper in a plain module — is right either way).
+//
+// A finding is a warning on an ordinary turn and fails the build under
+// --strict (the update acceptance) or when ASSEMBLY_TURN_BASELINE_SHA says this
+// turn changed a file involved: the caller, the client file, or any import on
+// the chain that put the caller on the server — a new page that renders an
+// existing shared component makes that component's call run on the server for
+// the first time. A Vercel build or a template clone has no agent who can act
+// on a failure, and the route was already broken, so neither is failed.
+import { readdirSync, readFileSync, existsSync, statSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import { createRequire } from 'node:module';
+import { dirname, join, relative, resolve, sep } from 'node:path';
+
+const ROOT = process.cwd();
+const STRICT = process.argv.includes('--strict');
+const APP_DIR = join(ROOT, 'app');
+const SOURCE_DIRS = ['app', 'components', 'lib'];
+const SOURCE_FILE = /\.(tsx|ts|jsx|js|mjs)$/;
+const RESOLVE_EXTENSIONS = ['.tsx', '.ts', '.jsx', '.js', '.mjs'];
+// Next renders or invokes these on the server unless the file opts into the client.
+const SERVER_ENTRY_FILE = /^(page|layout|template|default|loading|not-found|route)\.(tsx|ts|jsx|js)$/;
+// tsconfig's `@/*` → `./*`, the only alias the scaffold defines.
+const PATH_ALIAS = '@/';
+// The turn program exports the SHA the sandbox started this turn at; a finding
+// is the agent's own when a file it involves changed since then.
+const TURN_BASELINE_ENV = 'ASSEMBLY_TURN_BASELINE_SHA';
+
+// Resolved from this file: inside an app it sits in node_modules/ or
+// .assembly/, so this finds the app's own typescript (the one `next build`
+// uses); in this repo it finds the package's devDependency.
+function loadTypeScript() {
+  try {
+    return createRequire(import.meta.url)('typescript');
+  } catch {
+    return null;
+  }
+}
+
+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 (SOURCE_FILE.test(entry.name) && !/\.test\.\w+$/.test(entry.name)) {
+      out.push(full);
+    }
+  }
+  return out;
+}
+
+const toPosix = (file) => relative(ROOT, file).split(sep).join('/');
+
+function resolveImport(fromFile, specifier) {
+  let base;
+  if (specifier.startsWith(PATH_ALIAS)) base = join(ROOT, specifier.slice(PATH_ALIAS.length));
+  else if (specifier.startsWith('.')) base = resolve(dirname(fromFile), specifier);
+  else return null; // a package: not this app's code
+  const candidates = [
+    base,
+    ...RESOLVE_EXTENSIONS.map((ext) => base + ext),
+    ...RESOLVE_EXTENSIONS.map((ext) => join(base, 'index' + ext)),
+  ];
+  for (const candidate of candidates) {
+    try {
+      if (statSync(candidate).isFile()) return candidate;
+    } catch {
+      // not this candidate
+    }
+  }
+  return null;
+}
+
+// 'client' | 'server' | '' — a directive is the file's first statement, which
+// the parser keeps as an expression statement holding the string.
+function directiveOf(ts, sf) {
+  const first = sf.statements[0];
+  if (!first || !ts.isExpressionStatement(first) || !ts.isStringLiteral(first.expression)) return '';
+  const match = /^use (client|server)$/.exec(first.expression.text);
+  return match ? match[1] : '';
+}
+
+// Static imports as the emitted module keeps them. TypeScript drops
+// `import type`, a clause whose specifiers are all `type X`, and the matching
+// `export type … from` forms, so a module reached only that way never runs.
+function staticImports(ts, sf, file) {
+  const imports = [];
+  const edges = new Set();
+  const edge = (specifier) => {
+    const target = resolveImport(file, specifier);
+    if (target) edges.add(target);
+    return target;
+  };
+  for (const st of sf.statements) {
+    if (ts.isImportDeclaration(st) && ts.isStringLiteral(st.moduleSpecifier)) {
+      const clause = st.importClause;
+      if (!clause) {
+        edge(st.moduleSpecifier.text); // side-effect import
+        continue;
+      }
+      if (clause.isTypeOnly) continue;
+      const bindings = [];
+      if (clause.name) bindings.push({ local: clause.name.text, kind: 'default' });
+      const named = clause.namedBindings;
+      if (named && ts.isNamespaceImport(named)) bindings.push({ local: named.name.text, kind: 'namespace' });
+      if (named && ts.isNamedImports(named)) {
+        for (const el of named.elements) if (!el.isTypeOnly) bindings.push({ local: el.name.text, kind: 'named' });
+      }
+      if (bindings.length === 0) continue;
+      const target = edge(st.moduleSpecifier.text);
+      if (target) imports.push({ target, bindings });
+    } else if (ts.isExportDeclaration(st) && st.moduleSpecifier && ts.isStringLiteral(st.moduleSpecifier)) {
+      if (st.isTypeOnly) continue;
+      const clause = st.exportClause;
+      if (clause && ts.isNamedExports(clause) && clause.elements.every((el) => el.isTypeOnly)) continue;
+      edge(st.moduleSpecifier.text);
+    }
+  }
+  return { imports, edges };
+}
+
+// Every call-like use of an identifier (`name(…)`, `name.member(…)`, `new
+// name(…)`, name`…`), every name the file declares itself, and the targets of
+// dynamic `import('…')` — one walk over the tree.
+function walkUses(ts, sf, file, edges) {
+  const calls = [];
+  const declared = new Set();
+  const lineOf = (node) => sf.getLineAndCharacterOfPosition(node.getStart(sf)).line + 1;
+  const visit = (node) => {
+    if (ts.isCallExpression(node) || ts.isNewExpression(node) || ts.isTaggedTemplateExpression(node)) {
+      const callee = ts.isTaggedTemplateExpression(node) ? node.tag : node.expression;
+      if (callee.kind === ts.SyntaxKind.ImportKeyword) {
+        const arg = node.arguments?.[0];
+        if (arg && ts.isStringLiteral(arg)) {
+          const target = resolveImport(file, arg.text);
+          if (target) edges.add(target);
+        }
+      } else if (ts.isIdentifier(callee)) {
+        calls.push({ name: callee.text, member: '', line: lineOf(callee) });
+      } else if (ts.isPropertyAccessExpression(callee) && ts.isIdentifier(callee.expression)) {
+        calls.push({ name: callee.expression.text, member: callee.name.text, line: lineOf(callee) });
+      }
+    } else if (
+      (ts.isVariableDeclaration(node) || ts.isParameter(node) || ts.isBindingElement(node) ||
+        ts.isFunctionDeclaration(node) || ts.isClassDeclaration(node)) &&
+      node.name && ts.isIdentifier(node.name)
+    ) {
+      declared.add(node.name.text);
+    }
+    ts.forEachChild(node, visit);
+  };
+  visit(sf);
+  return { calls, declared };
+}
+
+function readModule(ts, file) {
+  const text = readFileSync(file, 'utf8');
+  const sf = ts.createSourceFile(file, text, ts.ScriptTarget.Latest, false, file.endsWith('x') ? ts.ScriptKind.TSX : ts.ScriptKind.TS);
+  const { imports, edges } = staticImports(ts, sf, file);
+  const { calls, declared } = walkUses(ts, sf, file, edges);
+  return { file, directive: directiveOf(ts, sf), imports, edges, calls, declared };
+}
+
+function isServerEntry(file) {
+  return file.startsWith(APP_DIR + sep) && SERVER_ENTRY_FILE.test(file.split(sep).pop());
+}
+
+// The repo-relative paths this turn changed: commits since the baseline plus
+// whatever is still uncommitted. No baseline means no turn (a Vercel build, a
+// clone bootstrap), so nothing is the agent's to fix. A git failure with a
+// baseline fails closed by treating every file as changed — the sandbox is the
+// one place a finding can still be acted on.
+const EVERY_FILE = { has: () => true };
+function changedThisTurn() {
+  const baseline = (process.env[TURN_BASELINE_ENV] ?? '').trim();
+  if (!baseline) return new Set();
+  const changed = new Set();
+  const listings = [
+    { args: ['diff', '--name-only', `${baseline}..HEAD`], parse: (line) => line },
+    // Porcelain rows are "XY path", or "XY old -> new" for a rename.
+    { args: ['status', '--porcelain', '--untracked-files=all'], parse: (line) => line.slice(3).split(' -> ').pop() },
+  ];
+  for (const { args, parse } of listings) {
+    const result = spawnSync('git', args, { cwd: ROOT, encoding: 'utf8' });
+    if (result.status !== 0) return EVERY_FILE;
+    for (const line of result.stdout.split('\n')) {
+      const file = parse(line).trim();
+      if (file) changed.add(file);
+    }
+  }
+  return changed;
+}
+
+function report(findings, { fatal }) {
+  console.error('');
+  console.error(
+    fatal
+      ? "Server code calls a function exported from a 'use client' file:"
+      : "Server code calls a function exported from a 'use client' file (pre-existing; this build is not failed for it):",
+  );
+  console.error('');
+  for (const f of findings) console.error(`  - ${f.file}:${f.line} calls ${f.name}() imported from ${f.target}`);
+  console.error('');
+  console.error("A module that starts with 'use client' reaches server code as client references,");
+  console.error('not as functions: rendering one as JSX works, calling one throws, and the page');
+  console.error('answers 500 for every visitor. tsc and next build both pass.');
+  console.error('');
+  console.error('Move the helper into a plain module with no directive (lib/<name>.ts) and import');
+  console.error("it from both sides. A 'use client' file should export only components and hooks.");
+  if (fatal) process.exit(1);
+}
+
+if (!existsSync(APP_DIR)) process.exit(0);
+
+const ts = loadTypeScript();
+if (!ts) {
+  // Every scaffolded app depends on typescript; without it there is no parser
+  // and no `next build` either, so there is nothing for this check to guard.
+  console.error('check-client-boundary: typescript is not installed; skipped.');
+  process.exit(0);
+}
+
+const modules = new Map();
+for (const dir of SOURCE_DIRS) {
+  for (const file of sourceFiles(join(ROOT, dir))) modules.set(file, readModule(ts, file));
+}
+
+// Everything reachable from a server entry without crossing into a client
+// module runs on the server. A client module is a boundary, not a node: what
+// it imports is its own business.
+const serverReachable = new Set();
+const queue = [...modules.values()]
+  .filter((m) => m.directive === 'server' || (m.directive !== 'client' && isServerEntry(m.file)))
+  .map((m) => m.file);
+while (queue.length > 0) {
+  const file = queue.pop();
+  if (serverReachable.has(file)) continue;
+  serverReachable.add(file);
+  for (const target of modules.get(file).edges) {
+    const next = modules.get(target);
+    if (next && next.directive !== 'client' && !serverReachable.has(target)) queue.push(target);
+  }
+}
+
+const findings = [];
+for (const file of serverReachable) {
+  const mod = modules.get(file);
+  for (const { target, bindings } of mod.imports) {
+    if (modules.get(target)?.directive !== 'client') continue;
+    for (const binding of bindings) {
+      if (mod.declared.has(binding.local)) continue; // shadowed somewhere in the file
+      const call = mod.calls.find((c) =>
+        c.name === binding.local && (binding.kind === 'namespace' ? c.member !== '' : c.member === ''),
+      );
+      if (!call) continue;
+      const name = call.member ? `${call.name}.${call.member}` : call.name;
+      findings.push({ file: toPosix(file), line: call.line, target: toPosix(target), name });
+    }
+  }
+}
+
+if (findings.length === 0) process.exit(0);
+
+// A finding is the turn's own when the turn wrote the call, the client file, or
+// any link in the import chain that puts the caller on the server. Walk forward
+// from every server-side file the turn changed; what that reaches is the turn's.
+const changed = STRICT ? EVERY_FILE : changedThisTurn();
+const ownedByTurn = new Set();
+const seeds = [...serverReachable].filter((file) => changed.has(toPosix(file)));
+while (seeds.length > 0) {
+  const file = seeds.pop();
+  if (ownedByTurn.has(toPosix(file))) continue;
+  ownedByTurn.add(toPosix(file));
+  for (const target of modules.get(file).edges) {
+    if (serverReachable.has(target) && !ownedByTurn.has(toPosix(target))) seeds.push(target);
+  }
+}
+const own = findings.filter((f) => ownedByTurn.has(f.file) || changed.has(f.target));
+const preexisting = findings.filter((f) => !own.includes(f));
+if (preexisting.length > 0) report(preexisting, { fatal: false });
+if (own.length > 0) report(own, { fatal: true });

package/package.json

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

package/skills/assembly-notifications/SKILL.md

@@ -1,10 +1,10 @@
 ---
 name: assembly-notifications
 # <!-- !feature:notification-settings -->
-description: Use when the app must notify internal users or clients about something that happened — in-product, email, or both. Covers createNotification, the Notification Center /n surface, and clearing the client badge (see clearing-client-notifications).
+description: Use when the app must notify internal users or clients about something that happened — in-product, email, or both — including unprompted, whenever it has submissions, status changes, approvals, or required alerts. Covers createNotification, the Notification Center /n surface, and clearing the client badge (see clearing-client-notifications).
 # <!-- /feature:notification-settings -->
 # <!-- feature:notification-settings -->
-description: Use when the app must notify internal users or clients, or needs per-user notification preferences (Product/Email toggles). Covers createNotification, the /n surface, notificationSettings + notificationSettingId, and clearing the client badge (see clearing-client-notifications).
+description: Use when the app must notify internal users or clients (including unprompted, whenever it has submissions, status changes, approvals, or required alerts), or needs per-user notification preferences (Product/Email toggles). Covers createNotification, the /n surface, notificationSettings + notificationSettingId, and clearing the client badge (see clearing-client-notifications).
 # <!-- /feature:notification-settings -->
 ---