@assembly-js/app-foundation 0.3.8 → 0.3.10

package/CHANGELOG.md

@@ -19,6 +19,12 @@ 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.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.
+
 ## 0.3.8
 - [behavior] An app that calls a provider's inferred route now lists that provider in `.assembly/app-deps.json`.
 

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/dist/scripts.d.ts

@@ -3,6 +3,6 @@ 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/`.
+ * does not exist, so it refuses to run inside Next instead; use this only from scripts.
  */
 export declare function getOfflineAssembly(): Promise<AssemblyAPI>;

package/dist/scripts.js

@@ -4676,6 +4676,11 @@ async function mintBearerFromAppKey() {
 
 // src/scripts.ts
 async function getOfflineAssembly() {
+  if (process.env.NEXT_RUNTIME) {
+    throw new Error(
+      "getOfflineAssembly from '/scripts' must not run inside Next: its app-scoped bearer acts as the installer. Use getAssembly() or getAssemblyForRequest() from '/server' in user-facing routes, or getOfflineAssembly() from '/server' for cron and webhook routes"
+    );
+  }
   if (!process.env.ASSEMBLY_API_KEY) {
     throw new Error(
       "getOfflineAssembly: ASSEMBLY_API_KEY is not set \u2014 cannot mint an app-scoped bearer"

package/package.json

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