@assembly-js/app-foundation 0.3.0 → 0.3.2

package/CHANGELOG.md

@@ -19,6 +19,13 @@ 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.2
+- [new] The `assembly-api-contract` skill teaches the build agent to write and maintain `.assembly/openapi.json` alongside `app/api` routes.
+
+## 0.3.1
+- [guidance] The build agent now upgrades an app's bridge to 2.1.0 and its foundation package instead of skipping a deep link, mounts the location reporter, and deep-links notifications to the specific record.
+- [new] App destinations in `NavigateDestination` now accept an optional `path` for links to an app's inner page.
+
 ## 0.3.0
 - [new] `LocationReporter` is exported from `@assembly-js/app-foundation/client`, so apps born before the deeplink image can mount it in their layout and report their inner location to the host with the same surface-prefix handling as new apps.
 

package/CLAUDE.md

@@ -48,6 +48,9 @@ Assembly-specific gotchas live in `.claude/skills/<name>/SKILL.md`. Invoke them
 <!-- feature:deep-link-bridge-nav -->
 - `assembly-platform-links` — link platform records (client, company, invoice, contract, form, file) to their portal detail page via `linkTo()`; never hand-build a host URL. Also links between workspace apps by install id. Check the app's installed app-bridge first (see the skill) — `navigateTo` doesn't exist on older peers — and only link staff-only destinations (client, company, form, etc.) from the dashboard surface, never the client portal.
 <!-- /feature:deep-link-bridge-nav -->
+<!-- feature:deep-link-app-inner-location -->
+- `assembly-app-inner-location` — mount `<LocationReporter />` so the host mirrors the app's inner page in its address bar; deep-link a notification or link to a specific record with `linkTo({ to: 'app', installId, path })`, never to the app root. Never hand-write location reporting.
+<!-- /feature:deep-link-app-inner-location -->
 <!-- feature:cross-app-apis -->
 - `assembly-app-clients` — calling another workspace app through its generated client in `generated/apps/<appId>/` (`installerClient`, by verb and path), and rendering an empty state that names the app when the call is refused instead of a 500.
 <!-- /feature:cross-app-apis -->
@@ -65,6 +68,7 @@ Assembly-specific gotchas live in `.claude/skills/<name>/SKILL.md`. Invoke them
 - `assembly-route-auth` — REQUIRED on every `app/api/.../[id]/route.ts` handler: `requireAuth` + `requireCompanyScope` before returning or mutating data.
 - `assembly-scheduled-work` — REQUIRED when the prompt implies anything on a schedule or while nobody has the app open (remind, daily digest, every week, follow up in N days, at a specific time): one `*/30 * * * *` Vercel cron in `vercel.json` hitting one dispatcher route, every scheduled action a row in a schedule table, `CRON_SECRET` declared in `requiredSecrets` and verified on every tick, `getOfflineAssembly()` for platform calls. Checking for due work on page load ships a schedule that never fires.
 - `assembly-route-errors` — REQUIRED in every route handler: use `handleRouteError` from `@assembly-js/app-foundation/server` in catch blocks — never return `err.message`. Validate values before they hit typed DB columns (e.g. `parseUuid` before a uuid-column lookup).
+- `assembly-api-contract` — REQUIRED whenever an `app/api` route is added, removed, or changes its request or response shape: keep `.assembly/openapi.json` (OpenAPI 3.1, `servers: [{"url": "/api"}]`, paths without the `/api` prefix) in step; cron, webhook, `assembly-*` and `privateRoutes` routes stay out.
 - `assembly-action-results` — REQUIRED when a server action refuses work the UI should explain (validation, permission, not ready to send): return `{ ok: false, message }` instead of throwing. A thrown message is redacted in production.
 - `assembly-dev-server-logs` — the dev server's stdout/stderr (server-side errors, stack traces, console output) is readable at `/tmp/dev-server.log`; check it before guessing at a 500 or broken preview.
 - Your own preview is `localhost:3000`; never fetch the public `sb-*.vercel.run` host from inside the sandbox (egress to it is blocked).

package/dist/bridge-vnext.d.ts

@@ -48,6 +48,7 @@ export type NavigateDestination = {
 } | {
     to: 'app';
     installId: string;
+    path?: string;
 };
 export type NavigateToOptions = {
     replace?: boolean;

package/package.json

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

package/skills/assembly-api-contract/SKILL.md

@@ -0,0 +1,123 @@
+---
+name: assembly-api-contract
+description: REQUIRED whenever you add, remove, or change the request or response shape of a route under app/api. Write and maintain .assembly/openapi.json, the app's OpenAPI 3.1 API contract — one operation per callable (method, path) with JSON Schema bodies; servers /api and paths without the /api prefix. Skip cron, webhook, assembly-* and privateRoutes routes.
+---
+
+Keep `.assembly/openapi.json` in step with `app/api` in the same turn as the route change. It is the document other apps and tools read to learn what this app's API accepts and returns.
+
+## When to touch it
+
+- Route added: add an operation for each exported GET, POST, PUT, PATCH or DELETE handler; never document head or options, which are not proxied.
+- Route removed, or a method removed from it: delete that operation (and the path entry once it has no operations).
+- Request body, query parameter, or response field changed: update the schemas to match.
+
+## Format
+
+- OpenAPI `3.1.0`, JSON, at `.assembly/openapi.json`. Bodies are JSON Schema.
+- Identity of an operation is `(method, path template)`. `operationId` is a label only; renaming it changes nothing.
+- `servers` is `[{ "url": "/api" }]` and `paths` are written **without** the `/api` prefix, exactly as the route scanner templates them (`app/api/projects/[projectId]/tasks/route.ts` becomes `/projects/{projectId}/tasks`). Path parameters are `{name}` using the folder's bracket name.
+- The stored document is capped at 1 MB and publishing refuses a larger one. Keep it small: describe fields, do not paste sample data.
+
+## What stays out
+
+A route is not callable by other apps, so it must not appear, when it is:
+
+- under a `cron`, `webhook` or `webhooks` segment, or a segment starting `assembly-`
+- wrapped in `cronRoute` or `automationActionRoute`
+- matched by a glob in `privateRoutes` in `.assembly/app.json` (matched against the route template, not the file path). The scanner records these as excluded, so documenting one is reported as a drift.
+
+## Worked example
+
+`app/api/projects/[projectId]/tasks/route.ts` exports `GET` (list) and `POST` (create):
+
+```json
+{
+  "openapi": "3.1.0",
+  "info": { "title": "Project tasks", "version": "1.0.0" },
+  "servers": [{ "url": "/api" }],
+  "paths": {
+    "/projects/{projectId}/tasks": {
+      "get": {
+        "operationId": "listProjectTasks",
+        "summary": "List the tasks of a project",
+        "parameters": [
+          { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }
+        ],
+        "responses": {
+          "200": {
+            "description": "The project's tasks",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "required": ["tasks"],
+                  "properties": { "tasks": { "type": "array", "items": { "$ref": "#/components/schemas/Task" } } }
+                }
+              }
+            }
+          },
+          "404": { "$ref": "#/components/responses/Error" }
+        }
+      },
+      "post": {
+        "operationId": "createProjectTask",
+        "summary": "Create a task in a project",
+        "parameters": [
+          { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "required": ["title"],
+                "properties": { "title": { "type": "string", "minLength": 1 }, "dueDate": { "type": ["string", "null"], "format": "date" } }
+              }
+            }
+          }
+        },
+        "responses": {
+          "201": { "description": "The created task", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Task" } } } },
+          "400": { "$ref": "#/components/responses/Error" }
+        }
+      }
+    }
+  },
+  "components": {
+    "schemas": {
+      "Task": {
+        "type": "object",
+        "required": ["id", "title", "done"],
+        "properties": {
+          "id": { "type": "string", "format": "uuid" },
+          "title": { "type": "string" },
+          "done": { "type": "boolean" },
+          "dueDate": { "type": ["string", "null"], "format": "date" }
+        }
+      }
+    },
+    "responses": {
+      "Error": {
+        "description": "Error",
+        "content": {
+          "application/json": {
+            "schema": { "type": "object", "required": ["error"], "properties": { "error": { "type": "string" } } }
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+Document the error shape your handlers really return (see `assembly-route-errors`: `{ error }`).
+
+## Drift
+
+The platform may compare the contract with the scanned routes after a turn and report disagreements. Fix each kind at its source:
+
+- Documented operation with no route in code: remove the operation, or restore the route if it was deleted by mistake. A method the file does not export counts as missing.
+- Route in code with no operation: add the operation, unless the route is one of the excluded kinds above.
+- Same path under a different parameter name (`{id}` in the contract, `[taskId]` in the folder): Next allows one name per dynamic segment, so rename the contract's parameter to the folder's.
+- Shape mismatch (a response field renamed, a body field now required): update the schemas to what the handler returns and accepts.

package/skills/assembly-app-inner-location/SKILL.md

@@ -0,0 +1,19 @@
+<!-- feature:deep-link-app-inner-location -->
+---
+name: assembly-app-inner-location
+description: Use whenever the app has inner pages the host should mirror in its address bar, or when a notification, email or link should open this app on a specific record instead of its root. Covers mounting LocationReporter and pointing notifications at a specific record.
+---
+
+## What the reporter does
+
+The host mirrors the app's inner page in its own address bar and can open the app straight at an inner page. That only works if the app reports its location, and `<LocationReporter />` from the foundation package does exactly that. The reporter needs `AssemblyBridge.location`, which ships in app-bridge 2.1.0, and a `navigateTo`-only 2.0.0 bridge lacks it. Check with `grep -q onNavigate node_modules/@assembly-js/app-bridge/dist/index.d.ts && echo supported || echo unsupported`; if `unsupported`, run `bun add @assembly-js/app-bridge@2.1.0` (exact stable release, never a prerelease or range), then `bunx tsc --noEmit`, before mounting the reporter.
+
+- Mount `<LocationReporter />` once, in `app/layout.tsx`, imported from `@assembly-js/app-foundation/client`. If it is already there, leave it.
+- Never write custom `location.report` or `location.onNavigate` code, and never hand-write a `LocationSync` component. The reporter already handles surface prefixes and route changes.
+
+## Notifications deep-link to the record, not the app root
+
+When the app sends an email or in-product notification about a specific record (a document request, a submission), the destination is set by the notification's `ctaParams` and surface, not by `linkTo`. Pass `ctaParams` that identify the record (`ctaParams: { requestId: request.id }`) and render that record from an existing inner route of this app, one that works when opened cold. Follow `assembly-notifications` for the send-and-open pattern.
+
+To link from a button inside the app to an inner page, use `linkTo` as described in `assembly-platform-links` (the `app` destination takes an optional `path`).
+<!-- /feature:deep-link-app-inner-location -->

package/skills/assembly-platform-links/SKILL.md

@@ -14,7 +14,13 @@ Before writing any `linkTo()` or `AssemblyBridge.navigateTo()` call, check what
 grep -q navigateTo node_modules/@assembly-js/app-bridge/dist/index.d.ts && echo supported || echo unsupported
 ```
 
-If it reports `unsupported`, do not use this skill — there is no supported way for this app to trigger platform navigation yet. Skip the link rather than ship a button that silently does nothing.
+If it reports `unsupported`, upgrade the app in this same turn instead of skipping the link:
+
+1. Confirm the app is on the foundation package: `grep -q app-foundation package.json`. If it is not (vendored `lib/`), say the security update must land first and stop — do not attempt the migration in a feature turn.
+2. Pin the bridge to the exact stable release: `bun add @assembly-js/app-bridge@2.1.0`. Never pin a prerelease (`-beta`, `-rc`, `-next`) or a range.
+3. Bump the foundation dependency listed in `package.json` to `^0.3.0`, the floor that exports `linkTo` and `LocationReporter` (`bun add <that package name>@^0.3.0`).
+4. Run `bunx tsc --noEmit` and `bun run build`, and confirm the existing header and toast bridge calls still type-check. Fix any break before continuing.
+5. Re-run the check above, then proceed with this skill.
 
 ## When to reach for this skill
 
@@ -74,7 +80,7 @@ The host rejects staff-only destinations when the viewer is a client in the port
 | `article` | `articleId` | — | Yes |
 | `files` | — | `channelId` | Yes |
 | `channel` | — | `channelId` | Yes |
-| `app` | `installId` | — | Yes, if the target app is installed for that viewer |
+| `app` | `installId` | `path` | Yes, if the target app is installed for that viewer |
 | `home` | — | — | No — staff only |
 | `product` | — | — | No — staff only |
 | `helpdesk` | — | — | Yes |