@assembly-js/app-foundation 0.3.9 → 0.4.0

package/CHANGELOG.md

@@ -19,6 +19,16 @@ A patch release never changes what an app's build requires; a minor release may
 not by hand; see `changes/README.md`. CI fails a PR that changes a check script without a
 `bump: minor` change file.
 
+## 0.4.0
+- [fix] The renewal response is never cached.
+- [fix] Analytics identify the viewer again in migrated apps.
+- [new] `extractPdfText` takes `maxPages` to cap how many pages are read.
+- [action] An app without `app.config.ts` moves its Next options there on a platform update.
+- [guidance] The checks' text changed: the PDF page cap, the renewal route wording, and route reachability on update turns.
+
+## 0.3.10
+- [guidance] Build agents are told to reuse an existing provider module and warned that adding a new requiredSecrets entry pauses a published app at the setup form.
+
 ## 0.3.9
 - [fix] `getOfflineAssembly` from `@assembly-js/app-foundation/scripts` now refuses to run inside Next, so a route under `app/` can no longer use it to act with the installer's access. The entry shipped in 0.2.1 for standalone scripts only and nothing the build agent is taught imports it from a route, so no existing app's code needs to change.
 

package/CLAUDE.md

@@ -535,6 +535,12 @@ Two paths, decided by whether an `assembly-integrations` skill is present and, i
 1. **Read the credential only from `process.env.<KEY>`, server-side only.** Route handlers, server components, and server actions can read it. Client components, `'use client'` modules, and anything that ends up in the browser bundle cannot. Never hardcode a value, never persist one to the database, never read from the URL, never write `.env*` files.
 2. **Declare every secret you read in `.assembly/app.json`.** Add an entry under a top-level `requiredSecrets` array in the same change that introduces the call. The Assembly platform reads this manifest after the build, prompts the user for each value, and injects them as Vercel env vars at deploy.
 
+### Adding a secret to an app that already calls the provider
+
+- If the app already calls this provider, extend that module rather than declaring a second credential for the same provider.
+- If that module reads its credential from the app database, keep using it for this change, tell the user once, and offer moving it to `requiredSecrets` as a separate step (they re-enter the value). Do not read or move the values. This does not relax rule 1: never store a new credential in the database.
+- Adding a new `requiredSecrets` entry to a published app pauses it at the setup form until the value is supplied.
+
 ### Manifest shape
 
 ```json

package/bin/check-next-config.mjs

@@ -12,17 +12,36 @@
 // wrapper spreads. Prose rules get skipped; a failing build doesn't.
 //
 // An app without app.config.ts predates the wrapper split (cloned from an older
-// foundation). There the wrapper form was never the contract, so this check
-// exits 0 — those apps are protected by the boot/restart patch scripts instead.
+// foundation). Off an update turn the wrapper form was never the contract, so
+// this check exits 0 — those apps are protected by the boot/restart patch
+// scripts instead. On a platform update turn (or --strict) it asks for the
+// split, because those apps otherwise pass the build and fail acceptance.
 import { readFileSync, existsSync } from 'node:fs';
 import { join } from 'node:path';
 
 const ROOT = process.cwd();
+const STRICT = process.argv.includes('--strict') || process.env.ASSEMBLY_UPDATE_TURN === '1';
 const CONFIG_FILES = ['next.config.ts', 'next.config.mjs', 'next.config.js'];
 const APP_CONFIG_FILES = ['app.config.ts', 'app.config.mjs', 'app.config.js'];
 
 if (!APP_CONFIG_FILES.some((f) => existsSync(join(ROOT, f)))) {
-  process.exit(0); // pre-wrapper app: not this check's contract
+  if (!STRICT) process.exit(0); // pre-wrapper app: not this check's contract
+  console.error(
+    'check-next-config: this app has no app.config.ts, so its Next options still live in next.config.*.\n\n' +
+      'Split them:\n' +
+      '  1. Create app.config.ts exporting the app\'s current Next options:\n\n' +
+      '       import type { NextConfig } from "next";\n' +
+      '       const appConfig: NextConfig = { /* the options from next.config */ };\n' +
+      '       export default appConfig;\n\n' +
+      '     Leave out allowedDevOrigins, devIndicators and experimental.reactDebugChannel: the platform\n' +
+      '     injects those and withAssemblyDev applies them.\n' +
+      '  2. Replace next.config.ts with the platform wrapper:\n\n' +
+      '       import { withAssemblyDev } from "@assembly-js/app-foundation/next";\n' +
+      '       import appConfig from "./app.config";\n' +
+      '       export default withAssemblyDev(appConfig);\n\n' +
+      '  3. Delete any other next.config.* file.\n',
+  );
+  process.exit(1);
 }
 
 const present = CONFIG_FILES.filter((f) => existsSync(join(ROOT, f)));

package/bin/check-reexchange-route.mjs

@@ -1,10 +1,10 @@
 #!/usr/bin/env node
 // Fails the build when the app's silent-renewal route is a hand-written copy
-// instead of the package's handler. The copies predate the Safari fallback
-// (a bearer returned in the body for browsers that refuse the partitioned
-// cookie), so an app carrying one signs its Safari users out after the first
-// hour. Dependency-free on purpose: it runs inside the generated app's sandbox
-// before any deps beyond Node exist.
+// instead of the package's handler. The handler is the one copy the platform
+// maintains (CSRF check, cookie clear-and-set, cookie probe, Safari body
+// fallback); a hand-written copy may be missing any of them. Dependency-free
+// on purpose: it runs inside the generated app's sandbox before any deps
+// beyond Node exist.
 //
 // An app with no such route passes; check-proxy-csrf owns the missing-route
 // finding.
@@ -40,8 +40,9 @@ out(
     : `check-reexchange-route: ${ROUTE_FILE} is not the package handler (pre-existing; this build is not failed for it):`,
 );
 out('');
-out('A hand-written renewal route does not return the bearer in the response body, so Safari');
-out('sessions end after the first hour. Replace the whole file with exactly this:');
+out('The package handler is the one copy the platform maintains (CSRF check, cookie clear-and-set,');
+out('cookie probe, Safari body fallback). A hand-written copy may be missing any of those, so');
+out('replace the whole file with exactly this:');
 out('');
 out("  import { createAssemblyReexchangeHandler } from '@assembly-js/app-foundation/server';");
 out('');

package/bin/check-route-reachability.mjs

@@ -9,10 +9,19 @@
 // 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).
+//
+// On a platform update turn (ASSEMBLY_UPDATE_TURN=1) a page that was already
+// unreferenced at ASSEMBLY_TURN_BASELINE_SHA only warns: an update never adds
+// links or removes pages, so failing it would push the agent to delete code.
+// A page added this turn, or orphaned this turn, still fails.
+import { spawnSync } from 'node:child_process';
 import { readFileSync, readdirSync, existsSync } from 'node:fs';
 import { join, relative, sep } from 'node:path';
 
 const ROOT = process.cwd();
+const UPDATE_TURN = process.env.ASSEMBLY_UPDATE_TURN === '1';
+const BASELINE = (process.env.ASSEMBLY_TURN_BASELINE_SHA ?? '').trim();
+const SOURCE_FILE = /\.(tsx|ts|jsx|js|mjs)$/;
 const APP_DIR = join(ROOT, 'app');
 const MANIFEST = join(ROOT, '.assembly', 'app.json');
 
@@ -93,7 +102,37 @@ function referencePattern(route) {
   return new RegExp(`['"\`]${escapeRe(prefix)}`);
 }
 
+function git(args) {
+  const result = spawnSync('git', args, { cwd: ROOT, encoding: 'utf8', maxBuffer: 64 * 1024 * 1024 });
+  return result.status === 0 ? result.stdout : null;
+}
+
+// Sources at the baseline commit, or null when there is no baseline or git
+// cannot answer. Matched in JS rather than `git grep` so the JS reference
+// regex needs no translation to another dialect.
+function baselineSources() {
+  if (!BASELINE) return null;
+  const listing = git(['ls-tree', '-r', '--name-only', BASELINE, '--', 'app', 'components', 'lib']);
+  if (listing === null) return null;
+  const sources = new Map();
+  for (const path of listing.split('\n').filter((p) => SOURCE_FILE.test(p))) {
+    const content = git(['show', `${BASELINE}:${path}`]);
+    if (content === null) return null;
+    sources.set(path, content);
+  }
+  return sources;
+}
+
+// True only for a page that existed at the baseline and was already
+// unreferenced there, so the agent did not cause the orphan.
+function wasOrphanedAtBaseline(sources, path, pattern) {
+  if (!sources || !sources.has(path)) return false;
+  return ![...sources].some(([other, content]) => other !== path && pattern.test(content));
+}
+
+const sources = UPDATE_TURN ? baselineSources() : null;
 const violations = [];
+const preExisting = [];
 for (const file of pageFiles) {
   const route = routeForPageFile(file);
   if (allowed.has(route)) continue;
@@ -103,10 +142,25 @@ for (const file of pageFiles) {
     (other) => other !== file && pattern.test(contents.get(other)),
   );
   if (!referenced) {
-    violations.push(`${relative(ROOT, file).split(sep).join('/')}  (route ${route})`);
+    const rel = relative(ROOT, file).split(sep).join('/');
+    const entry = `${rel}  (route ${route})`;
+    if (UPDATE_TURN && (!BASELINE || sources === null || wasOrphanedAtBaseline(sources, rel, pattern))) {
+      preExisting.push(entry);
+    } else {
+      violations.push(entry);
+    }
   }
 }
 
+if (preExisting.length > 0) {
+  console.warn('');
+  console.warn(
+    'check-route-reachability: unreferenced pages (pre-existing; this build is not failed for it — a platform update never adds links or removes pages):',
+  );
+  for (const v of preExisting) console.warn('  - ' + v);
+  console.warn('');
+}
+
 if (violations.length > 0) {
   console.error('');
   console.error('Unreachable page routes — nothing in the app links to them:');

package/bin/check-server-pdf-imports.mjs

@@ -57,6 +57,9 @@ out("Replace each server-side use with the foundation's helper:");
 out("  import { extractPdfText } from '@assembly-js/app-foundation/server';");
 out('  const { text, pages } = await extractPdfText(bytes);');
 out('');
+out('Keep whatever page limit the old code applied by passing `{ maxPages: N }`, and keep any');
+out('byte-size guard in front of the call.');
+out('');
 out('Then remove the pdf-parse / pdfjs-dist / @napi-rs/canvas dependencies, any');
 out('GlobalWorkerOptions.workerSrc setup, and their entries in serverExternalPackages');
 out('in app.config.ts. Do not touch client-side PDF rendering code.');

package/dist/pdf.d.ts

@@ -1,6 +1,11 @@
 export interface PdfText {
-    /** Every page's text, pages separated by a newline. Empty when the PDF has no text layer (a scan). */
+    /** Every extracted page's text, pages separated by a newline. Empty when the PDF has no text layer (a scan). */
     text: string;
+    /** The document's total page count, even when `maxPages` truncated the text. */
     pages: number;
+    /** True when `maxPages` cut the extraction short of the document's last page. */
+    truncated: boolean;
 }
-export declare function extractPdfText(data: ArrayBuffer | Uint8Array): Promise<PdfText>;
+export declare function extractPdfText(data: ArrayBuffer | Uint8Array, opts?: {
+    maxPages?: number;
+}): Promise<PdfText>;

package/dist/pdf.js

@@ -3,13 +3,41 @@
 // runtime by paths computed from their own location, which the deploy tracer
 // can't follow, so they pass in the sandbox and 500 once published. Loaded
 // lazily so routes that never parse a PDF don't carry the bundle.
-export async function extractPdfText(data) {
+export async function extractPdfText(data, opts) {
     const { getDocumentProxy, extractText } = await import('unpdf');
     // pdf.js rejects a Node Buffer outright, so hand it a plain Uint8Array view.
     const bytes = data instanceof ArrayBuffer
         ? new Uint8Array(data)
         : new Uint8Array(data.buffer, data.byteOffset, data.byteLength);
     const pdf = await getDocumentProxy(bytes);
-    const { text, totalPages } = await extractText(pdf, { mergePages: true });
-    return { text, pages: totalPages };
+    try {
+        const total = pdf.numPages;
+        const maxPages = opts?.maxPages;
+        if (maxPages === undefined || maxPages >= total) {
+            const { text, totalPages } = await extractText(pdf, { mergePages: true });
+            return { text, pages: totalPages, truncated: false };
+        }
+        const pageTexts = [];
+        for (let n = 1; n <= Math.max(0, maxPages); n++) {
+            const content = await (await pdf.getPage(n)).getTextContent();
+            pageTexts.push(content.items
+                .filter((item) => 'str' in item && item.str != null)
+                .map((item) => {
+                const { str, hasEOL } = item;
+                return str + (hasEOL ? '\n' : '');
+            })
+                .join(''));
+        }
+        // Mirrors unpdf's own normalisation so truncated and full output agree.
+        const text = pageTexts
+            .join('\n')
+            .replace(/[^\S\n]+/g, ' ')
+            .replace(/ ?\n ?/g, '\n')
+            .replace(/\n{3,}/g, '\n\n');
+        return { text, pages: total, truncated: true };
+    }
+    finally {
+        // Same teardown unpdf's own helpers use; the bundled proxy has no destroy().
+        await pdf.loadingTask.destroy();
+    }
 }

package/dist/proxy.js

@@ -538,12 +538,10 @@ async function handleRequest(request, options) {
         // isClient gates accent/font in layout SSR. Always forward it so layout can
         // fall back when getSessionIdentity() cannot read the bearer on first paint.
         requestHeaders.set('x-assembly-is-client', identity.clientId ? 'true' : 'false');
-        // Distinct/workspace headers are legacy-only — bearer path reads them from
-        // the self-describing bearer via getSessionIdentity().
-        if (!exchangeEnabled) {
-            requestHeaders.set('x-assembly-distinct-id', identity.clientId ?? '');
-            requestHeaders.set('x-assembly-workspace-id', identity.workspaceId ?? '');
-        }
+        // Set in both auth modes: migrated apps' layouts still read these for
+        // analytics identity, and inbound copies are stripped so they can't be forged.
+        requestHeaders.set('x-assembly-distinct-id', identity.clientId ?? '');
+        requestHeaders.set('x-assembly-workspace-id', identity.workspaceId ?? '');
     }
     // Hand the active bearer to the render as a request header. On first load the
     // bearer exists nowhere else the render can see it (the Set-Cookie below isn't

package/dist/reexchange.js

@@ -41,6 +41,8 @@ export function createAssemblyReexchangeHandler() {
         // script could read.
         const wantsBearerInBody = req.headers.has(BEARER_IN_BODY_HEADER);
         const response = NextResponse.json(wantsBearerInBody ? { ok: true, bearer: minted.bearer } : { ok: true });
+        // The body can carry a live bearer, so no cache may keep or replay it.
+        response.headers.set('Cache-Control', 'no-store');
         const maxAge = Math.max(0, Math.floor((minted.bearerExpiresAt - Date.now()) / 1_000));
         // headers.append, not response.cookies.set, which keys by name and would
         // collapse the clear and the set of the same-named cookie. The legacy

package/package.json

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