@elytracms/cli 0.0.12 → 0.0.66

package/README.md

@@ -27,7 +27,9 @@ elytra init     First-run setup: provision Convex, generate the auth signing
 elytra doctor   Diagnose the active deployment's readiness and print each fix.
                 Includes the expected deployment env vars, reported set/missing
                 by NAME only — values are never read into the report or printed.
-                Read-only; exits non-zero if any check fails.
+                When the publish revalidate pair is set, also sends a signed
+                no-op ping to the endpoint to prove the publish → live chain
+                end to end. Read-only; exits non-zero if any check fails.
 
 elytra help     Show help
 elytra version  Show version
@@ -87,19 +89,55 @@ set on the wrong plane:
 3. **Convex deployment env** — set with `npx convex env set` (from `studio/`);
    lives on the deployment itself, visible in the Convex dashboard but in no
    file: the auth signing keys (`JWT_PRIVATE_KEY`, `JWKS` — set via
-   `npx @convex-dev/auth`), `SITE_URL`, and the publish/draft pair
+   `npx @convex-dev/auth`), `SITE_URL`, the instant-publish trio
    `CANVAS_PROJECT_SCOPE` / `CANVAS_REVALIDATE_ENDPOINT` /
-   `CANVAS_REVALIDATE_SECRET` and `DRAFT_PREVIEW_TOKEN` (each must match its
-   frontend-plane counterpart). `elytra doctor` diagnoses this plane's
-   readiness.
+   `CANVAS_REVALIDATE_SECRET`, and `DRAFT_PREVIEW_TOKEN` (each of the latter
+   four must match its frontend-plane counterpart). `elytra doctor` diagnoses
+   this plane's readiness.
 
 Because plane 3 lives in no file, it is the easiest to overlook — `elytra
 doctor` therefore enumerates the expected vars there (auth keys, `SITE_URL`,
-plus the AI provider key on the studio-host plane when the AI route is
-present) and reports each one **set or missing, by name only**: the doctor
-parses names out of `npx convex env list` and discards every value on the
-spot — values are never stored, printed, or logged. A missing required var
-(the auth keys) fails the run with its exact fix line; a missing recommended
-var (`SITE_URL`, the AI key) is a named warning that doesn't change the exit
+the instant-publish trio, the draft-preview token, plus the AI provider key
+on the studio-host plane when the AI route is present) and reports each one
+**set or missing, by name only**: the doctor parses names out of `npx convex
+env list` and discards every value on the spot — values are never stored,
+printed, or logged. A missing required var (the auth keys) fails the run
+with its exact fix line; a missing recommended var (`SITE_URL`, the AI key,
+the draft-preview token) is a named warning that doesn't change the exit
 code. The studio's boot-time "Deployment setup" screen lists the same
 expected vars, so the CLI and the studio tell one story.
+
+The **instant-publish trio** — `CANVAS_PROJECT_SCOPE`,
+`CANVAS_REVALIDATE_ENDPOINT`, and `CANVAS_REVALIDATE_SECRET` — gets special
+treatment, because the publish path **silently no-ops** while any of the
+three is unset: `CANVAS_PROJECT_SCOPE` gates the write-chokepoint trigger
+that *schedules* the revalidate webhook (checked FIRST, before the pair is
+even consulted), and the pair then gates whether the scheduled webhook
+actually *delivers*. Either way, publishes never update the live site until
+a redeploy, with no error anywhere. All three missing is a warning carrying
+exactly that consequence (a project without a delivery frontend may
+legitimately leave them unset); **any partial subset — one or two of the
+three set — fails** the run, because a half-configured trio has no
+legitimate reading (documented together in the scaffold's CONNECT.md, set in
+one shell block, so a partial state is far more likely an interrupted setup
+than a deliberate choice). When the pair (`CANVAS_REVALIDATE_ENDPOINT` +
+`CANVAS_REVALIDATE_SECRET`) IS set, the doctor goes one step further and
+proves the chain end to end: it POSTs a **signed no-op ping** (an empty tag
+list — the route revalidates nothing) to the endpoint. A 200
+`{"revalidated":[]}` passes (endpoint reachable, and the frontend's
+`REVALIDATE_SECRET` matches); a 401 fails as a secret mismatch between
+Convex and the frontend host; a network error only warns (unreachable from
+your machine is not the same as broken — Convex may still reach it). The
+pair's values are read in-process for the ping only and never printed. The
+ping proves only the pair's reachability/secret-match, not scheduling — a
+missing `CANVAS_PROJECT_SCOPE` still fails its own row (and the run)
+independently, even when the ping passes.
+
+The **draft-preview token** — `DRAFT_PREVIEW_TOKEN` — gates the deployment's
+`draftSnapshot` query and must equal the frontend host's own
+`DRAFT_PREVIEW_TOKEN` (the same secret that gates the frontend's
+preview-enable route); the doctor can only see the Convex-deployment side; it
+has no `pairWith` escalation because its real partner lives on a plane this
+doctor cannot read. Missing it is a warning: draft preview is closed
+everywhere (401 on both sides) until it's set — a project that never uses
+draft preview may legitimately leave it unset.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@elytracms/cli",
   "author": "finaldream <hi@finaldream.de>",
-  "version": "0.0.12",
+  "version": "0.0.66",
   "description": "The Elytra CLI — run a consuming repo's studio, frontend, and Convex backend under one command.",
   "license": "MIT",
   "type": "module",
@@ -17,7 +17,7 @@
     "node": ">=20"
   },
   "dependencies": {
-    "@elytracms/core": "^0.0.64"
+    "@elytracms/core": "^0.0.66"
   },
   "devDependencies": {
     "vitest": "^4.1.10"

package/src/cli.js

@@ -25,7 +25,9 @@ Commands:
              verify readiness. Idempotent — safe to re-run at any point.
   doctor     Diagnose the active deployment's readiness (URL, reachability, auth
              signing keys, expected deployment env vars — set/missing by NAME,
-             values never shown — config, membership) and print each fix. Exit
+             values never shown — config, membership) and print each fix. When the
+             instant-publish revalidate pair is set, also sends a signed no-op ping
+             to the endpoint to prove the publish → live chain end to end. Exit
              non-zero if any check fails. Read-only. Optional: --url <convex url>.
   help       Show this help
   version    Show version

package/src/doctor.js

@@ -1,10 +1,13 @@
 import {
+  REVALIDATE_ENV_ENDPOINT,
+  REVALIDATE_ENV_SECRET,
   backendSiteUrl,
   checkDeploymentReady,
   expectedDeploymentEnv,
   probeAuthSigningKeys,
+  probeRevalidateEndpoint,
 } from '@elytracms/core/export-sync/deployment-ready'
-import { defaultConvexExec } from './provision.js'
+import { convexEnvGet, defaultConvexExec } from './provision.js'
 
 /**
  * `elytra doctor` (EC-259) — the pre-boot counterpart to the studio's boot
@@ -177,6 +180,50 @@ export function gatherDeploymentEnvFacts({ env = {}, target, studioDir, aiRouteC
   return facts
 }
 
+// --- Signed revalidate ping (EC-421) -------------------------------------------
+//
+// When the presence checks say the instant-publish pair IS set, the doctor proves the
+// chain end to end: a POST to the endpoint signed with the secret, carrying an EMPTY
+// tag list — by the receiving route's own semantics a harmless no-op answering 200
+// `{"revalidated":[]}`. Default-on (no flag): the ping is read-only in effect and the
+// silent-failure class it catches (secret mismatch — publishes rejected with 401
+// forever, no error anywhere) is exactly what the doctor exists for.
+//
+// The ping needs the pair's VALUES — the one sanctioned value read: captured
+// `npx convex env get` subprocess stdout (`convexEnvGet`), held in locals inside this
+// function, passed into the probe, and never attached to a fact, printed, or logged.
+
+/**
+ * Gather the revalidate-ping fact for the report, or `undefined` when the ping does
+ * not apply (pair not fully present / presence not enumerated — the presence checks
+ * already tell that story; a probe row would be noise). A pair that is PRESENT but
+ * whose values can't be read yields an honest `unknown`, never a fabricated outcome.
+ */
+export async function gatherRevalidateProbe({
+  envFacts,
+  studioDir,
+  exec,
+  fetchImpl = fetch,
+  probe = probeRevalidateEndpoint,
+} = {}) {
+  const names = envFacts?.deploymentSetNames
+  if (!names || !names.includes(REVALIDATE_ENV_ENDPOINT) || !names.includes(REVALIDATE_ENV_SECRET)) {
+    return undefined
+  }
+  // In-process value read (the ONLY sanctioned one): captured subprocess stdout.
+  const endpoint = convexEnvGet(REVALIDATE_ENV_ENDPOINT, { cwd: studioDir, exec })
+  const secret = convexEnvGet(REVALIDATE_ENV_SECRET, { cwd: studioDir, exec })
+  if (endpoint === '' || secret === '') {
+    return {
+      status: 'unknown',
+      detail:
+        'The revalidate pair is set, but its values could not be read here (`npx convex env get` failed) — ' +
+        'the signed ping was not run.',
+    }
+  }
+  return probe(endpoint, secret, fetchImpl)
+}
+
 // --- Formatting (pure) -------------------------------------------------------
 
 const GLYPH = { ok: '✓', warn: '!', fail: '✗', unknown: '?' }
@@ -226,7 +273,8 @@ export function formatReport(report) {
  * `url`, and `exec` are injectable for tests. `studioDir` (where `convex env list`
  * runs) and `aiRouteConfigured` enable the deployment-env bucket (EC-399); without a
  * studio dir the env checks stay honest `unknown`s. Playground stays untouched — no
- * deployment, no env bucket.
+ * deployment, no env bucket. When the instant-publish revalidate pair is present, a
+ * signed no-op ping proves the publish → live chain end to end (EC-421, default-on).
  */
 export async function runDoctor({
   env = {},
@@ -254,6 +302,14 @@ export async function runDoctor({
   const facts = await gatherFacts(target, { fetchImpl })
   if (target.kind === 'convex') {
     facts.deploymentEnv = gatherDeploymentEnvFacts({ env, target, studioDir, aiRouteConfigured, exec })
+    // EC-421: default-on signed no-op ping whenever the revalidate pair is present.
+    const revalidateProbe = await gatherRevalidateProbe({
+      envFacts: facts.deploymentEnv,
+      studioDir,
+      exec,
+      fetchImpl,
+    })
+    if (revalidateProbe) facts.revalidateProbe = revalidateProbe
   }
   const report = checkDeploymentReady(facts)
   log(formatReport(report))