@elytracms/cli 0.0.85 → 0.0.86

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@elytracms/cli",
   "author": "finaldream <hi@finaldream.de>",
-  "version": "0.0.85",
+  "version": "0.0.86",
   "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": ">=22.18.0"
   },
   "dependencies": {
-    "@elytracms/core": "^0.0.85"
+    "@elytracms/core": "^0.0.86"
   },
   "devDependencies": {
     "vitest": "^4.1.10"

package/src/cli.js

@@ -1,7 +1,7 @@
 import { spawnSync } from 'node:child_process'
 import { join } from 'node:path'
 import { stdout } from 'node:process'
-import { runDoctor } from './doctor.js'
+import { resolveInstalledEngineVersion, runDoctor } from './doctor.js'
 import { runPreviews } from './previews.js'
 import { inspectProject, resolveStudioEnv } from './project.js'
 import { ensureAuthKeys } from './provision.js'
@@ -426,7 +426,17 @@ export async function runInit(project, { log: emit = log, fetchImpl, exec, provi
   emit('')
   emit('3. Verify —')
   const env = resolveStudioEnv(project.root)
-  const code = await runDoctor({ env, fetchImpl, log: (l) => emit(`   ${l}`) })
+  // EC-552: with the studio dir known, the verify step includes the version
+  // handshake — right after a provision is exactly when a stale-functions state
+  // should be loud. Resolution happens HERE (the entry), keeping runDoctor injected.
+  const verifyStudioDir = project.apps.studio ? join(project.root, 'studio') : undefined
+  const code = await runDoctor({
+    env,
+    fetchImpl,
+    log: (l) => emit(`   ${l}`),
+    studioDir: verifyStudioDir,
+    installedEngineVersion: resolveInstalledEngineVersion(verifyStudioDir),
+  })
 
   // 4. Ready checklist.
   emit('')
@@ -470,6 +480,7 @@ export async function run(argv, { cwd = process.cwd(), env = process.env, emit =
       return 1
     }
     const studioEnv = resolveStudioEnv(project.root, env)
+    const doctorStudioDir = project.apps.studio ? join(project.root, 'studio') : undefined
     return runDoctor({
       env: studioEnv,
       fetchImpl,
@@ -477,7 +488,10 @@ export async function run(argv, { cwd = process.cwd(), env = process.env, emit =
       url: flagValue(argv, '--url'),
       // EC-399: where `convex env list` runs (name enumeration — presence only),
       // and whether the AI provider-key expectation applies.
-      studioDir: project.apps.studio ? join(project.root, 'studio') : undefined,
+      studioDir: doctorStudioDir,
+      // EC-552: the installed engine version — resolved at the entry so runDoctor
+      // stays pure/injected; unresolvable (deps not installed) → honest `unknown`.
+      installedEngineVersion: resolveInstalledEngineVersion(doctorStudioDir),
       // EC-469: where the project's `cms/` route set is read from (code, not backend).
       root: project.root,
       aiRouteConfigured: project.hasAiRoute,

package/src/doctor.js

@@ -1,3 +1,6 @@
+import { readFileSync } from 'node:fs'
+import { createRequire } from 'node:module'
+import { dirname, join } from 'node:path'
 import {
   REVALIDATE_ENV_ENDPOINT,
   REVALIDATE_ENV_SECRET,
@@ -5,6 +8,7 @@ import {
   checkDeploymentReady,
   expectedDeploymentEnv,
   probeAuthSigningKeys,
+  probeDeployedFunctionsVersion,
   probeRevalidateEndpoint,
 } from '@elytracms/core/export-sync/deployment-ready'
 import { executeWorkspaceConfig } from './config-harness.js'
@@ -68,16 +72,27 @@ export function resolveDoctorTarget(env = {}, { url } = {}) {
 // --- Probes (node) -----------------------------------------------------------
 
 /**
- * Reachability probe: any HTTP response means the deployment answered; a thrown fetch
- * (DNS/connection) means it did not. (The studio uses `adapter.status()`; the CLI has
- * no convex client, so a plain GET to the deployment's client URL is the node analogue.)
+ * Deployment probe (EC-542 + EC-552): ONE call to the public query API yields BOTH the
+ * reachability fact and the version-handshake probe. The studio's probe was always a
+ * real query (`adapter.status()` → `members:mine`); the CLI previously used a bare GET
+ * and called ANY HTTP response "answered" — measured false-positive: Convex's wildcard
+ * `*.convex.cloud` 404s (empty body) for deployments that DO NOT EXIST, so every
+ * nonexistent deployment passed. Reachability now means "answered AS a Convex
+ * deployment": a Convex envelope — success, missing-function, or any other Convex
+ * error — proves a deployment; a non-Convex answer (the empty 404) or a thrown fetch
+ * (DNS/connection) fails it, each with its own honest detail so "nothing there" and
+ * "there but not deployed" stay distinguishable (the latter is reachable=true + the
+ * `functions-version`/JWKS-404 checks telling the deploy story).
  */
-export async function probeReachable(url, fetchImpl = fetch) {
-  try {
-    const res = await fetchImpl(url, { method: 'GET' })
-    return { available: true, detail: `HTTP ${res.status}` }
-  } catch (error) {
-    return { available: false, detail: error instanceof Error ? error.message : String(error) }
+export async function probeDeployment(url, fetchImpl = fetch) {
+  const versionProbe = await probeDeployedFunctionsVersion(url, fetchImpl)
+  const answered =
+    versionProbe.status === 'answered' ||
+    versionProbe.status === 'missing' ||
+    versionProbe.answeredAsConvex === true
+  return {
+    reachable: answered ? { available: true } : { available: false, detail: versionProbe.detail },
+    versionProbe,
   }
 }
 
@@ -86,24 +101,54 @@ export async function probeReachable(url, fetchImpl = fetch) {
  * user facts are intentionally omitted (no auth session) → `unknown`; the app facts
  * (config/collections) are gathered separately via the consumer-Vite harness when it
  * is available (EC-495, {@link configFactsFromOutcome}).
+ *
+ * EC-542/EC-552: reachability and the version probe are ONE network call
+ * ({@link probeDeployment}); the `functions-version` fact is emitted only when the
+ * caller supplies `installedEngineVersion` (otherwise the probe outcome still decides
+ * reachability but the handshake stays an honest `unknown`).
  */
-export async function gatherFacts(target, { fetchImpl = fetch } = {}) {
+export async function gatherFacts(target, { fetchImpl = fetch, installedEngineVersion } = {}) {
   if (target.kind === 'playground') return { backend: { kind: 'playground' } }
   if (target.kind === 'unconfigured') return { backend: { kind: 'unconfigured', detail: target.detail } }
 
-  const reachable = await probeReachable(target.url, fetchImpl)
+  const { reachable, versionProbe } = await probeDeployment(target.url, fetchImpl)
   const siteUrl = backendSiteUrl(target.url, target.siteUrl)
   const authKeys = await probeAuthSigningKeys(siteUrl, fetchImpl)
   return {
     backend: { kind: 'convex', url: target.url },
     reachable,
     authKeys,
+    ...(installedEngineVersion
+      ? { functionsVersion: { probe: versionProbe, expected: installedEngineVersion } }
+      : {}),
     // A configured URL means a deployment is wired; leave `provisioned` unset (→ ok).
     // session omitted → the user checks surface as `unknown`; config/collections are
     // merged in by the caller from the EC-495 harness outcome (or stay omitted).
   }
 }
 
+/**
+ * Resolve the engine version of the `@elytracms/studio` package INSTALLED in the
+ * consumer's studio app (EC-552) — the `expected` half of the version handshake.
+ * Deliberately resolved through the `convex/delivery` export and its adjacent
+ * `package.json`: that is the very source file the consumer's `convex deploy`
+ * bundles, so the version read here is by construction the version a redeploy
+ * would stamp. (The consumer's own `package.json` only carries a RANGE.)
+ * `undefined` when the deps aren't installed → the fact is omitted → the check
+ * reports an honest `unknown`, matching the config checks' opportunistic contract.
+ */
+export function resolveInstalledEngineVersion(studioDir) {
+  if (!studioDir) return undefined
+  try {
+    const req = createRequire(join(studioDir, 'package.json'))
+    const deliverySource = req.resolve('@elytracms/studio/convex/delivery')
+    const pkg = JSON.parse(readFileSync(join(dirname(deliverySource), '..', 'package.json'), 'utf8'))
+    return typeof pkg.version === 'string' ? pkg.version : undefined
+  } catch {
+    return undefined
+  }
+}
+
 // --- Config facts via the consumer-Vite harness (EC-495) -------------------------------
 
 /**
@@ -389,6 +434,13 @@ export function formatReport(report) {
  * works-without-node_modules contract is untouched. A resolved config also hands the
  * route checks the same collections the studio actually mounts (superseding the
  * `cms/index.ts` re-export). `configOutcome` is injectable for tests.
+ *
+ * EC-552: when the caller supplies `installedEngineVersion` (the CLI entry resolves it
+ * from the consumer's installed `@elytracms/studio` via {@link
+ * resolveInstalledEngineVersion}), the deployed functions are probed for their stamped
+ * version and the `functions-version` check gets a real answer; otherwise the fact is
+ * omitted → an honest `unknown`. Resolution stays at the entry point so this function
+ * remains pure/injected like every other gatherer here.
  */
 export async function runDoctor({
   env = {},
@@ -402,6 +454,7 @@ export async function runDoctor({
   previewsArtifacts,
   routeFacts,
   configOutcome,
+  installedEngineVersion,
 } = {}) {
   const target = resolveDoctorTarget(env, { url })
 
@@ -417,7 +470,11 @@ export async function runDoctor({
     log('No backend configured.')
   }
 
-  const facts = await gatherFacts(target, { fetchImpl })
+  // EC-552: the version handshake rides the same probe as reachability; it becomes a
+  // real check only when the caller supplied the installed engine version (the CLI
+  // entry resolves it via `resolveInstalledEngineVersion`; runDoctor itself never
+  // touches the filesystem for it, staying pure/injected like every gatherer here).
+  const facts = await gatherFacts(target, { fetchImpl, installedEngineVersion })
   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.

package/src/previews.js

@@ -51,7 +51,9 @@ export const PREVIEWS_MANIFEST_FILE = 'elytra-previews.json'
 /** Root-relative URL prefix the manifest entries carry. */
 export const PREVIEWS_URL_PREFIX = '/elytra-previews/'
 /**
- * Manifest format version (mirrors `@elytracms/studio`'s PREVIEWS_MANIFEST_VERSION).
+ * Manifest format version — THE declaration (EC-514: the studio's mirror was
+ * removed; its reader is version-agnostic, and this CLI is the only writer and the
+ * only reader of the number). Bump on incompatible schema/hash changes.
  * `2` (EC-502): the entry hash no longer includes the engine version, so v1 hashes
  * are not comparable with v2 ones — a version mismatch is reported as itself
  * ("regenerate"), never as N bogus `stale` entries.