@assembly-js/app-foundation 0.0.25-rc.0 → 0.0.25-rc.2

package/bin/check-crons.mjs

@@ -1,45 +1,90 @@
 #!/usr/bin/env node
 // Fails the build when scheduled work is half-wired. A cron route that no
 // `vercel.json` entry invokes never runs; an entry pointing at a missing route
-// 404s forever; a cron route without the platform-managed secret is a public
-// endpoint that mutates workspace data; and a cron faster than the platform's
-// floor keeps the app's database awake around the clock. Every one of those
-// passes typecheck and `next build` and only shows up after publish, when
-// nobody is looking — so the app's own build is the gate. Dependency free on
-// purpose: it runs inside the generated app's sandbox before any deps beyond
+// 404s forever; a cron route that skips the platform-managed secret check is a
+// public endpoint that mutates workspace data; and a cron faster than the
+// platform's floor keeps the app's database awake around the clock. Every one
+// of those passes typecheck and `next build` and only shows up after publish,
+// when nobody is looking — so the app's own build is the gate. Dependency free
+// on purpose: it runs inside the generated app's sandbox before any deps beyond
 // Node are guaranteed.
+//
+// The build fails only for cron wiring the current turn is changing (see
+// cronWiringChangedThisTurn). Everything else — a template clone, a Vercel
+// build, an update turn that never touched the cron — gets the same findings
+// as warnings: those paths have no agent who can act on a failure, so failing
+// them would only strand an app that already worked.
 import { readFileSync, readdirSync, existsSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
 import { join, relative, sep } from 'node:path';
 
 const ROOT = process.cwd();
 const APP_DIR = join(ROOT, 'app');
 const VERCEL_JSON = join(ROOT, 'vercel.json');
-const MANIFEST = join(ROOT, '.assembly', 'app.json');
 
 // The conventional home for cron routes; a route here with no schedule is the
 // "looked right in preview, never ran in production" bug this guard exists for.
 const CRON_ROUTE_PREFIX = '/api/cron/';
 // Vercel sends this env var as the bearer on every cron invocation; the platform
-// mints it at deploy when the manifest declares it.
+// declares and mints it at deploy once vercel.json carries a cron entry.
 const CRON_SECRET_KEY = 'CRON_SECRET';
 // Platform floor: a poller faster than this never lets the app's database scale
 // to zero, which costs more than the work it does.
 const MIN_INTERVAL_MINUTES = 30;
 const ROUTE_FILE = /^route\.(tsx|ts|jsx|js)$/;
 
-function fail(lines) {
+// The turn program exports the SHA the sandbox started this turn at; the files
+// below are the ones whose change since then makes the findings the agent's own.
+const TURN_BASELINE_ENV = 'ASSEMBLY_TURN_BASELINE_SHA';
+const CRON_WIRING_PATHS = ['vercel.json', 'app/api/cron/'];
+
+function report(lines, { fatal }) {
   console.error('');
-  console.error('Scheduled work is not wired correctly:');
+  console.error(
+    fatal
+      ? 'Scheduled work is not wired correctly:'
+      : 'Scheduled work is not wired correctly (pre-existing; this build is not failed for it):',
+  );
   console.error('');
   for (const l of lines) console.error('  - ' + l);
   console.error('');
-  console.error('Every scheduled app needs all of these together:');
+  console.error('Every scheduled app needs both of these together:');
   console.error('  1. One dispatcher route under app/api/cron/ that verifies the cron secret.');
   console.error('  2. A matching entry in vercel.json, no more often than every 30 minutes:');
   console.error('       { "crons": [{ "path": "/api/cron/dispatch", "schedule": "*/30 * * * *" }] }');
-  console.error(`  3. "${CRON_SECRET_KEY}" declared in .assembly/app.json requiredSecrets (the platform mints it).`);
+  console.error(`The platform declares and mints "${CRON_SECRET_KEY}" itself once vercel.json has a cron entry.`);
   console.error('See the assembly-scheduled-work skill.');
-  process.exit(1);
+  if (fatal) process.exit(1);
+}
+
+function fail(lines) {
+  report(lines, { fatal: true });
+}
+
+function isCronWiringPath(file) {
+  return CRON_WIRING_PATHS.some((p) => (p.endsWith('/') ? file.startsWith(p) : file === p));
+}
+
+// Whether this turn changed vercel.json or a cron route: 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 — the sandbox is the one place a
+// finding can still be acted on.
+function cronWiringChangedThisTurn() {
+  const baseline = (process.env[TURN_BASELINE_ENV] ?? '').trim();
+  if (!baseline) return false;
+  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 true;
+    const changed = result.stdout.split('\n').map((line) => parse(line).trim()).filter(Boolean);
+    if (changed.some(isCronWiringPath)) return true;
+  }
+  return false;
 }
 
 function readJson(file, label) {
@@ -151,13 +196,6 @@ function minIntervalMinutes(schedule) {
   return Math.min(...gaps);
 }
 
-function declaredSecrets() {
-  if (!existsSync(MANIFEST)) return new Set();
-  const manifest = readJson(MANIFEST, '.assembly/app.json');
-  const secrets = Array.isArray(manifest?.requiredSecrets) ? manifest.requiredSecrets : [];
-  return new Set(secrets.map((s) => (typeof s?.key === 'string' ? s.key.trim() : '')));
-}
-
 // Only the two forms the skill prescribes count as verifying the secret, and
 // comments are stripped first so a copied auth comment above an unguarded
 // handler cannot pass. Form 1: the exported handler IS the cronRoute wrapper.
@@ -231,13 +269,6 @@ for (const route of cronRoutes) {
 }
 
 if (entries.length > 0) {
-  if (!declaredSecrets().has(CRON_SECRET_KEY)) {
-    problems.push(
-      `.assembly/app.json requiredSecrets does not declare "${CRON_SECRET_KEY}" — without it Vercel sends no ` +
-        `bearer and the cron route cannot tell a real tick from a stranger. Add ` +
-        `{ "key": "${CRON_SECRET_KEY}", "label": "Cron secret" }; the platform mints the value at deploy.`,
-    );
-  }
   for (const file of coveredRoutes) {
     if (!verifiesCronSecret(readFileSync(file, 'utf8'))) {
       problems.push(
@@ -250,4 +281,4 @@ if (entries.length > 0) {
   }
 }
 
-if (problems.length > 0) fail(problems);
+if (problems.length > 0) report(problems, { fatal: cronWiringChangedThisTurn() });

package/package.json

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

package/skills/assembly-scheduled-work/SKILL.md

@@ -58,7 +58,7 @@ The repo already has a `vercel.json`. **Add the `crons` key; keep every existing
 
 ## 3. Cron secret — declare it, never ask for it
 
-Vercel authenticates its own invocations by sending the project's `CRON_SECRET` env var as `Authorization: Bearer <value>`. Declare it as a required secret and the platform generates the value at deploy and sets it on the Vercel project:
+Vercel authenticates its own invocations by sending the project's `CRON_SECRET` env var as `Authorization: Bearer <value>`. Declare it as a required secret and the platform generates the value at deploy and sets it on the Vercel project. The platform also declares it itself for any app whose `vercel.json` has a cron entry, so a missing declaration never blocks a publish — declaring it keeps the manifest honest about what the app reads:
 
 ```json
 {
@@ -161,7 +161,7 @@ Crons **never fire in the builder preview**; only a published app has Vercel's s
 curl -sS -H "Authorization: Bearer $CRON_SECRET" http://localhost:3000/api/cron/dispatch
 ```
 
-Insert a row with `nextRunAt` in the past, run that, and confirm the side effect and the advanced `nextRunAt`. Then tell the user, in plain words, that the schedule starts running once the app is published. `bun run build` runs `check-crons.mjs`, which fails on a cron route without an entry, an entry without a route, a missing `CRON_SECRET` declaration, or a schedule faster than every 30 minutes — fix the wiring it names rather than deleting the check.
+Insert a row with `nextRunAt` in the past, run that, and confirm the side effect and the advanced `nextRunAt`. Then tell the user, in plain words, that the schedule starts running once the app is published. `bun run build` runs `check-crons.mjs`, which fails on a cron route without an entry, an entry without a route, a handler that skips the secret check, or a schedule faster than every 30 minutes — fix the wiring it names rather than deleting the check. Cron wiring that predates your turn is reported as a warning instead; fix it when the task touches it.
 
 ## Don'ts