@assembly-js/app-foundation 0.0.1-rc.2 → 0.0.2-rc.1

package/CLAUDE.md

@@ -23,11 +23,22 @@ Assembly-specific gotchas live in `.claude/skills/<name>/SKILL.md`. Invoke them
 - `assembly-custom-fields` — workspace-defined fields, multiSelect rules
 - `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)
+<!-- /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`
+<!-- /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.
+<!-- /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
 - `assembly-app-bridge-toast` — show toast notifications in the parent dashboard
 - `assembly-ai` — AI features via Assembly's OpenAI proxy (no API keys needed)
 - `assembly-storage` — app-private file uploads/downloads (NOT the portal Files module). The storage helpers come from `@assembly-js/app-foundation/server` — import them, don't rewrite them. POST only `{ fileName }` (a bare name) and store the key the platform returns; never build the S3 key yourself.
+- `assembly-integrations` (present only when third-party integrations are enabled for this workspace) — third-party providers (Slack, etc.) via `requiredIntegrations` + `getIntegration()`. If this skill is present, read it before declaring an integration or writing any provider call — it lists what's connectable and each provider's gotchas. If it is absent, managed OAuth integrations are not available here; use `requiredSecrets` for any external service
 - `assembly-avatar-sub` — row-duplication + AvatarSub pattern for showing which company a client row represents (multi-company clients)
 - `assembly-user-company-selector` — UserCompanySelector for picking clients, internal users, companies
 - `assembly-forms` — react-hook-form + zod + Field component validation pattern
@@ -226,7 +237,12 @@ Any external service (SendGrid, Twilio, Resend, a niche SaaS, an API-key-only se
 - `type` — `url | api_key | secret | text`. The platform picks input style from this.
 - `docsUrl` — optional link the platform renders as "Where do I find this?".
 
+<!-- !feature:notification-settings -->
 Valid top-level manifest keys: `surfaces`, `requiredSecrets`, and `requiredIntegrations` (leave it in place if present — it is platform-managed).
+<!-- /feature:notification-settings -->
+<!-- feature:notification-settings -->
+Valid top-level manifest keys: `surfaces`, `requiredSecrets`, `notificationSettings` (per-user toggleable internal-user notification categories, plus an optional app-level `actionLabel` that gives the app a row in the *client's* Your Actions card — see the `assembly-notifications` skill), and `requiredIntegrations` (leave it in place if present — it is platform-managed).
+<!-- /feature:notification-settings -->
 
 ### Example: post to a Slack webhook from a route handler
 

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "@assembly-js/app-foundation",
-  "version": "0.0.1-rc.2",
+  "version": "0.0.2-rc.1",
   "description": "Versioned foundation helpers and build context for Assembly generated apps",
   "type": "module",
   "files": [
     "dist",
     "skills",
-    "CLAUDE.md"
+    "CLAUDE.md",
+    "render-context.mjs"
   ],
   "exports": {
     "./server": {
@@ -19,7 +20,7 @@
     }
   },
   "scripts": {
-    "build": "tsc",
+    "build": "tsc && tsc-alias",
     "test": "bun test",
     "prepublishOnly": "npm run build && npm run verify:dist",
     "verify:dist": "node scripts/verify-dist-resolves.mjs"
@@ -35,6 +36,7 @@
     "@types/node": "^22",
     "next": "^15.5.0",
     "server-only": "^0.0.1",
+    "tsc-alias": "^1.9.1",
     "typescript": "^5.3.3"
   },
   "publishConfig": {

package/render-context.mjs

@@ -0,0 +1,96 @@
+// Renders this package's prose for one app: strips the feature-gate blocks the
+// app's flags don't enable, and substitutes the catalog tokens.
+//
+// A port of prompts.RenderFeatureGates / parseFeatureMarker in the Go tree. The
+// duplication is deliberate — the gates interleave with prose line by line, so the
+// side that writes the files has to do the stripping, and that side is now the
+// sandbox. render-context.test.mjs pins the two implementations to a shared fixture
+// so a divergence fails a build rather than silently shipping wrong prose.
+//
+// Catalogs arrive pre-rendered from Go instead of as data: the action catalog
+// branches on advertised resolvers, cross-provider resolvers, and a no-resolver
+// fallback, and re-deriving that here would be a second implementation of logic
+// that exists in one place today.
+
+// A marker is a full line, optionally prefixed with "# " so it can sit inside YAML
+// frontmatter without breaking the parse.
+function parseFeatureMarker(line) {
+  let trimmed = line.trim();
+  if (trimmed.startsWith('# ')) trimmed = trimmed.slice(2);
+  if (!trimmed.startsWith('<!-- ') || !trimmed.endsWith(' -->')) return null;
+
+  let inner = trimmed.slice('<!-- '.length, -' -->'.length);
+  const marker = { name: '', close: false, negated: false };
+
+  if (inner.startsWith('/')) {
+    marker.close = true;
+    // Tolerate "/!feature:…" so a negated block can be closed symmetrically;
+    // polarity comes from the open marker either way.
+    inner = inner.slice(1);
+    if (inner.startsWith('!')) inner = inner.slice(1);
+  } else if (inner.startsWith('!')) {
+    marker.negated = true;
+    inner = inner.slice(1);
+  }
+
+  if (!inner.startsWith('feature:')) return null;
+  marker.name = inner.slice('feature:'.length);
+  return marker;
+}
+
+// Keeps the lines this app's features select. Throws on a malformed gate rather than
+// guessing: a mismatched marker means the prose is not what its author intended, and
+// shipping half a gated block is worse than failing the turn.
+export function renderFeatureGates(content, features) {
+  if (!content.includes('feature:')) return content;
+
+  const enabled = new Set(features ?? []);
+  const out = [];
+  let open = null;
+  let include = true;
+
+  // Split keeping line terminators so the output is byte-identical to the input
+  // outside the stripped blocks.
+  const lines = content.split(/(?<=\n)/);
+  for (let i = 0; i < lines.length; i += 1) {
+    const line = lines[i];
+    const marker = parseFeatureMarker(line);
+    if (!marker) {
+      if (include) out.push(line);
+      continue;
+    }
+    if (marker.close) {
+      if (!open || open.name !== marker.name) {
+        throw new Error(`line ${i + 1}: unmatched close marker for feature "${marker.name}"`);
+      }
+      open = null;
+      include = true;
+      continue;
+    }
+    if (open) {
+      throw new Error(`line ${i + 1}: nested open marker for feature "${marker.name}" (blocks cannot nest)`);
+    }
+    open = marker;
+    include = enabled.has(marker.name) !== marker.negated;
+  }
+  if (open) {
+    throw new Error(`unclosed gate marker for feature "${open.name}"`);
+  }
+  return out.join('');
+}
+
+// Replaces each catalog token with the markdown Go rendered for it. A token with no
+// entry is left alone: the config omits catalogs when the workspace cannot reach a
+// provider, and the surrounding prose is written to read correctly either way.
+export function substituteCatalogs(content, catalogs) {
+  let out = content;
+  for (const [token, markdown] of Object.entries(catalogs ?? {})) {
+    out = out.split(token).join(markdown);
+  }
+  return out;
+}
+
+// The whole render for one file.
+export function renderContextFile(content, config) {
+  return substituteCatalogs(renderFeatureGates(content, config?.features), config?.catalogs);
+}

package/skills/assembly-app-surfaces/SKILL.md

@@ -0,0 +1,104 @@
+---
+name: assembly-app-surfaces
+description: Use whenever generating a Vibe app to declare which surfaces (dashboard-internal, client portal, or both) the app exposes. Omitting the client surface keeps the app off client portal nav entirely. The choice is a product decision, not a default.
+---
+
+Every generated app must declare its **surfaces** in a `.assembly/app.json` file at the repo root. Note: `surfaces` declares surface *types* (dashboard, client portal, notification) — per-client or per-company visibility is a platform setting configured in the app's settings, not in this file. The build pipeline reads this file after deploy and uses it to populate the marketplace app's `InternalUrl` (dashboard preview) and `ClientUrl` (client portal). If you omit a surface, that URL stays empty — and an empty `ClientUrl` means the app does not appear in client portal nav at all.
+
+## First decide: does this app have a client view?
+
+A Vibe app has a **client view** only if end-clients (the customers of the workspace, not the workspace's internal users) are meant to interact with it directly inside the client portal. Examples:
+
+- **Internal-only** (omit `client`): admin dashboards, internal reporting, time trackers used only by employees, internal CRM views.
+- **Client-facing** (include `client`): self-serve client request forms, client-visible status pages, client-shared file browsers.
+
+If you are unsure, default to **internal-only**. Do not add a client surface unless the prompt clearly describes a client-facing experience.
+
+## File format
+
+```json
+{
+  "surfaces": {
+    "internal": { "path": "/" },
+    "client":   { "path": "/c" }
+  }
+}
+```
+
+- `internal` is **required** — every Vibe app must have a dashboard surface. `client` is optional; omit it for internal-only apps. `notification` is optional; declare it only when the app uses `ctaParams` in notifications (see below).
+- `path` is the route within your app for that surface. Must start with `/`. Use `/` for the surface's root; use distinct sub-paths if both surfaces share one Next.js app.
+- Generate the corresponding routes in your app code. E.g. if you declare `client.path = "/c"`, you must have a `/c` page in the app.
+
+<!-- !feature:notification-settings -->
+> **Every surface MUST be nested under `surfaces`.** A surface placed at the top level — e.g. `{ "surfaces": {...}, "notification": { "path": "/n" } }` — is silently dropped by the deploy parser, leaving that surface's URL empty and its notification links broken. The only valid top-level keys are `surfaces`, `requiredSecrets`, and `requiredIntegrations` (see below). The build validates this: `bun run build` runs `node .assembly/validate-manifest.mjs` first and **fails with a specific error** if the manifest is malformed or a key is misplaced. Run `bun run validate:manifest` to check it directly.
+
+`requiredSecrets` and `requiredIntegrations` are **top-level siblings of `surfaces`**, not surfaces — see the secrets guidance and the `assembly-integrations` skill. The full manifest shape is:
+<!-- /feature:notification-settings -->
+<!-- feature:notification-settings -->
+> **Every surface MUST be nested under `surfaces`.** A surface placed at the top level — e.g. `{ "surfaces": {...}, "notification": { "path": "/n" } }` — is silently dropped by the deploy parser, leaving that surface's URL empty and its notification links broken. The only valid top-level keys are `surfaces`, `requiredSecrets`, `notificationSettings`, and `requiredIntegrations` (see below). The build validates this: `bun run build` runs `node .assembly/validate-manifest.mjs` first and **fails with a specific error** if the manifest is malformed or a key is misplaced. Run `bun run validate:manifest` to check it directly.
+
+`requiredSecrets`, `notificationSettings`, and `requiredIntegrations` are **top-level siblings of `surfaces`**, not surfaces — see the `assembly-notifications` skill, the secrets guidance, and the `assembly-integrations` skill. The full manifest shape is:
+<!-- /feature:notification-settings -->
+
+```json
+{
+  "surfaces": { "internal": { "path": "/" }, "client": { "path": "/c" }, "notification": { "path": "/n" } },
+  "requiredSecrets": [{ "key": "SENDGRID_API_KEY", "label": "SendGrid API key" }],
+  "requiredIntegrations": [{ "provider": "slack", "scopes": ["chat:write", "channels:read"] }]
+}
+```
+<!-- feature:notification-settings -->
+
+`notificationSettings` declares per-user toggleable internal-user notification categories — schema and rules in the `assembly-notifications` skill.
+<!-- /feature:notification-settings -->
+<!-- feature:api-resources -->
+
+The app's API contract (automation triggers/actions, webhook events) is NOT an `app.json` key: it lives in a separate sibling file, `.assembly/api-resources.json` — see the `assembly-automations` skill.
+<!-- /feature:api-resources -->
+
+## The `notification` surface
+
+When an app sends notifications with `ctaParams`, the Notification Center needs to know where to send the user when they click the notification's CTA. Declare a `notification` surface to set that destination URL.
+
+```json
+{
+  "surfaces": {
+    "internal": { "path": "/" },
+    "notification": { "path": "/n" }
+  }
+}
+```
+
+When `notification` is declared:
+- The build pipeline sets `notificationUrl` on the marketplace app to `<deployURL>/n`.
+- When a user clicks a notification CTA, the portal opens the app at `notificationUrl?token=<jwt>&<ctaParams>`.
+- Your `/n` page shows its context-specific content from the `ctaParams` in the URL. Those always arrive; `notificationId` from the token payload is best-effort under the session-exchange flow, so never gate the record render on it.
+
+**Declare the `notification` surface whenever the app sends notifications with `ctaParams`.** If notifications have no `ctaParams`, the surface is optional. See the `assembly-notifications` skill for the full CTA params pattern.
+
+## Examples
+
+Dashboard-only time tracker:
+```json
+{ "surfaces": { "internal": { "path": "/" } } }
+```
+
+App with both surfaces in one Next.js project:
+```json
+{
+  "surfaces": {
+    "internal": { "path": "/" },
+    "client":   { "path": "/c" }
+  }
+}
+```
+
+App with notifications that have CTA params:
+```json
+{
+  "surfaces": {
+    "internal": { "path": "/" },
+    "notification": { "path": "/n" }
+  }
+}
+```