@junoflow/cli 0.6.0 → 0.10.0

package/src/api.js

@@ -6,21 +6,22 @@ import {
   UserError,
 } from './errors.js';
 import { resolveTarget } from './target.js';
+import { resolveToken } from './token.js';
 
 /**
  * clientName is the X-Juno-Client value: `cli/claude-code` inside a shell
- * Claude Code started (it sets CLAUDECODE=1), `cli` everywhere else. The
- * gateway records a write as `operator:<client>`; it is the actor, not a
- * security control.
+ * Claude Code started (it sets CLAUDECODE=1), `cli` everywhere else. It labels
+ * the calling client; the actor a write is recorded under is the request's
+ * principal, and the header is not a security control.
  */
 export function clientName(env = process.env) {
   return env.CLAUDECODE === '1' ? 'cli/claude-code' : 'cli';
 }
 
 /**
- * connect resolves the instance (target.js) and builds the client every
- * command uses, unless one was injected: `args.client` is how the tests hand
- * a command a client instead of a URL.
+ * connect resolves the instance (target.js) and the API key (token.js) and
+ * builds the client every command uses, unless one was injected:
+ * `args.client` is how the tests hand a command a client instead of a URL.
  */
 export async function connect(args, io) {
   const target = await resolveTarget({
@@ -28,9 +29,12 @@ export async function connect(args, io) {
     cwd: io.cwd,
     env: io.env,
   });
-  const client =
-    args.client ?? new JunoClient(target, { client: clientName(io.env) });
-  return { target, client };
+  if (args.client) return { target, client: args.client };
+  const token = await resolveToken({ token: args.token, env: io.env });
+  return {
+    target,
+    client: new JunoClient(target, { client: clientName(io.env), token }),
+  };
 }
 
 /**
@@ -43,17 +47,22 @@ export async function connect(args, io) {
 export class JunoClient {
   constructor(
     target,
-    { fetch: fetchImpl = globalThis.fetch, client = clientName() } = {}
+    { fetch: fetchImpl = globalThis.fetch, client = clientName(), token } = {}
   ) {
     this.target = target;
     this.fetch = fetchImpl;
     this.client = client;
+    // The API key, sent as a bearer on every request. A private field, so
+    // nothing that logs or serialises a client can print it.
+    this.#token = token;
   }
 
+  #token;
+
   /**
    * POST /api/integrations/scaffold — a whole starting project, path →
-   * content. `target` is what this client reached the instance at; the server
-   * prefers its own configured public URL and falls back to it.
+   * content. `target` is what this client reached the instance at, recorded
+   * as juno.target; the server falls back to its public URL without it.
    */
   async scaffold(id, { name, description, target } = {}) {
     const body = await this.#json('POST', '/api/integrations/scaffold', {
@@ -70,16 +79,28 @@ export class JunoClient {
     return this.#json('POST', '/api/typegen/integration', { manifest });
   }
 
-  /** POST /api/integrations/ingest — deploy, or validate only with dryRun. */
-  async ingest(project, { dryRun = false, id } = {}) {
-    const query = dryRun ? '?dry_run=true' : '';
-    return this.#json('POST', `/api/integrations/ingest${query}`, {
+  /**
+   * POST /api/integrations/ingest — deploy, or validate only with dryRun.
+   * `baseVersion` undefined sends none (a copy that records no base, --force,
+   * or --id naming another install). A 409 is a ConflictError: the install's
+   * active version is not the copy's base.
+   *
+   * It does not go through #workingCopyJSON, whose 422-without-diagnostics
+   * wording differs from what this route has always printed; only the 409 is
+   * shared.
+   */
+  async ingest(project, { dryRun = false, id, baseVersion } = {}) {
+    const path = `/api/integrations/ingest${dryRun ? '?dry_run=true' : ''}`;
+    const res = await this.#request('POST', path, {
       manifest: project.manifest,
       files: project.files,
       package_json: project.packageJSON ?? undefined,
       lockfile: project.lockfile ?? undefined,
       id: id ?? undefined,
+      base_version: baseVersion ?? undefined,
     });
+    if (res.status === 409) throw new ConflictError(problemDetail(res));
+    return this.#answer('POST', path, res);
   }
 
   /** GET /api/integrations/{id} — the manifest and sources Juno holds. */
@@ -87,6 +108,59 @@ export class JunoClient {
     return this.#json('GET', `/api/integrations/${encodeURIComponent(id)}`);
   }
 
+  /**
+   * GET /api/integrations/{id}/versions/{v} — one stored version, keyed as
+   * the Go struct spells it (`Manifest`, `SourceFiles`), or null when the
+   * instance has no such version.
+   */
+  async getIntegrationVersion(id, version) {
+    return this.#versionOrNull(
+      `/api/integrations/${encodeURIComponent(id)}/versions/${version}`
+    );
+  }
+
+  /**
+   * GET /api/flows/{id}/versions/{v} — one stored version (`manifest_json`,
+   * `source_files`), or null when the instance has no such version.
+   */
+  async getFlowVersion(id, version) {
+    return this.#versionOrNull(
+      `/api/flows/${encodeURIComponent(id)}/versions/${version}`
+    );
+  }
+
+  /**
+   * GET /api/flows/{id}/runs/{seq}/fixture — `{fixture, notes}`, run `seq`
+   * as a flowHarness scenario. A refusal (a run still going, one that
+   * suspended or was cancelled) is a 422 and an unknown flow or run a 404;
+   * both are a UserError in the server's own words.
+   */
+  async runFixture(flowId, seq) {
+    const path = `/api/flows/${encodeURIComponent(flowId)}/runs/${seq}/fixture`;
+    const res = await this.#request('GET', path);
+    if (res.status === 422 || res.status === 404) {
+      throw new UserError(problemDetail(res));
+    }
+    return this.#answer('GET', path, res);
+  }
+
+  /**
+   * GET /api/apps/{id}/versions/{v} — one stored version (`manifest`,
+   * `files`), or null when the instance has no such version.
+   */
+  async getAppVersion(id, version) {
+    return this.#versionOrNull(
+      `/api/apps/${encodeURIComponent(id)}/versions/${version}`
+    );
+  }
+
+  /** #versionOrNull is a GET whose 404 is an answer: there is no such version. */
+  async #versionOrNull(path) {
+    const res = await this.#request('GET', path);
+    if (res.status === 404) return null;
+    return this.#answer('GET', path, res);
+  }
+
   /**
    * POST /api/flows/scaffold — a flow working copy, `{files: {path: content},
    * warnings?: [string]}`: the active version's, or a stub for an id with
@@ -94,7 +168,7 @@ export class JunoClient {
    * the working copy is still rendered, because it is how that gets fixed.
    */
   async scaffoldFlow(id, { target } = {}) {
-    const body = await this.#flowJSON('/api/flows/scaffold', {
+    const body = await this.#workingCopyJSON('/api/flows/scaffold', {
       id,
       target: target ?? undefined,
     });
@@ -102,41 +176,85 @@ export class JunoClient {
   }
 
   /**
-   * POST /api/typegen/flow — `{manifest, types: {"flow-env.d.ts",
-   * "flow-api.d.ts"}}` for a manifest, from the live catalog.
+   * POST /api/typegen/flow — `{manifest, types: {"types/flow-env.d.ts",
+   * "types/flow-api.d.ts"}}` for a manifest, from the live catalog.
    */
   async typegenFlow(manifest) {
-    return this.#flowJSON('/api/typegen/flow', { manifest });
+    return this.#workingCopyJSON('/api/typegen/flow', { manifest });
   }
 
   /**
    * POST /api/flows/ingest — verify a flow working copy and, unless dryRun,
-   * commit and activate it. `baseVersion` undefined sends none (a new flow,
+   * commit and activate it. `files` is the working copy's src/ tree, path →
+   * content. `baseVersion` undefined sends none (a new flow,
    * or --force). A 409 is a ConflictError; a 422 with diagnostics is a
    * DiagnosticsError.
    */
-  async ingestFlow({ flowId, manifest, flowTS, baseVersion }, { dryRun } = {}) {
+  async ingestFlow({ flowId, manifest, files, baseVersion }, { dryRun } = {}) {
     const query = dryRun ? '?dry_run=true' : '';
-    return this.#flowJSON(`/api/flows/ingest${query}`, {
+    return this.#workingCopyJSON(`/api/flows/ingest${query}`, {
       flow_id: flowId,
       manifest,
-      flow_ts: flowTS,
+      files,
+      base_version: baseVersion ?? undefined,
+    });
+  }
+
+  /**
+   * POST /api/apps/scaffold — an app working copy, `{files: {path:
+   * content}}`: the active version's, or a stub for an id with none.
+   */
+  async scaffoldApp(id, { target } = {}) {
+    const body = await this.#workingCopyJSON('/api/apps/scaffold', {
+      id,
+      target: target ?? undefined,
+    });
+    return body?.files ?? {};
+  }
+
+  /**
+   * POST /api/typegen/app — `{manifest, types: {"types/app-api.d.ts", …}}`
+   * for an edited manifest, from the live catalog.
+   */
+  async typegenApp(manifest) {
+    return this.#workingCopyJSON('/api/typegen/app', { manifest });
+  }
+
+  /**
+   * POST /api/apps/ingest — verify an app working copy and store it as a
+   * version: activated, or with `activate: false` left as the draft
+   * `~draft/` serves. A 422 with diagnostics is a DiagnosticsError.
+   * `baseVersion` undefined sends none (a copy that records no base, or
+   * --force). When activating, a 409 is a ConflictError: the app's active
+   * version is not the copy's base. A draft is never refused; the answer's
+   * `stale_base` carries the sentence instead.
+   */
+  async ingestApp(
+    { manifest, files, lockfile },
+    { activate = true, baseVersion } = {}
+  ) {
+    return this.#workingCopyJSON('/api/apps/ingest', {
+      manifest,
+      files,
+      lockfile: lockfile ?? undefined,
+      activate,
       base_version: baseVersion ?? undefined,
     });
   }
 
   /**
-   * #flowJSON is #json for the flow working-copy routes, which answer two
-   * more failures in their own words: a 409 (the working copy is stale) and a
-   * 422 with no diagnostics (a flow id that is not kebab-case).
+   * #workingCopyJSON is #json for the flow and app working-copy routes, which
+   * answer two more failures in their own words: a 409 (the working copy is
+   * stale) and a 422 with no diagnostics (an id that is not kebab-case, an
+   * archive path outside src/, page/ and public/).
    */
-  async #flowJSON(path, body) {
+  async #workingCopyJSON(path, body) {
     const res = await this.#request('POST', path, body);
     if (res.status === 409) throw new ConflictError(problemDetail(res));
     if (res.status === 422 && !res.parsed?.diagnostics?.length) {
       throw new UserError(validationDetail(res));
     }
-    if (res.ok) return res.parsed;
+    if (res.ok) return jsonBody('POST', path, res);
     if (res.parsed?.diagnostics?.length) {
       throw new DiagnosticsError(
         res.parsed.detail || 'verification failed',
@@ -167,12 +285,7 @@ export class JunoClient {
       );
     }
     if (!res.ok) throw failure('POST', path, res);
-    if (res.parsed === null) {
-      throw new UserError(
-        `POST ${path} answered something that is not JSON: ${res.text.trim()}`
-      );
-    }
-    return { result: res.parsed, text: res.text };
+    return { result: jsonBody('POST', path, res), text: res.text };
   }
 
   /**
@@ -214,8 +327,8 @@ export class JunoClient {
     const path = `/api/skills/${encodeURIComponent(name)}`;
     const res = await this.#request('GET', path);
     if (res.status === 404) return null;
-    if (!res.ok || res.parsed === null) throw failure('GET', path, res);
-    return res.parsed;
+    if (!res.ok) throw failure('GET', path, res);
+    return jsonBody('GET', path, res);
   }
 
   /**
@@ -228,7 +341,8 @@ export class JunoClient {
     const path = `/api/secrets/${encodeURIComponent(id)}`;
     const res = await this.#request('GET', path);
     if (res.status === 404) return null;
-    if (!res.ok || res.parsed === null) throw failure('GET', path, res);
+    if (!res.ok) throw failure('GET', path, res);
+    jsonBody('GET', path, res);
     return {
       name: res.parsed.name ?? '',
       description: res.parsed.description ?? '',
@@ -268,8 +382,12 @@ export class JunoClient {
   }
 
   async #json(method, path, body) {
-    const res = await this.#request(method, path, body);
-    if (res.ok) return res.parsed;
+    return this.#answer(method, path, await this.#request(method, path, body));
+  }
+
+  /** #answer is #json's reading of an answer already received. */
+  #answer(method, path, res) {
+    if (res.ok) return jsonBody(method, path, res);
 
     // A 422 is the interesting failure: it carries the compiler's own
     // findings, and reprinting them beats summarising them.
@@ -311,12 +429,11 @@ export class JunoClient {
     if (answer.status === 400) throw new UsageError(problemDetail(answer));
     if (answer.status === 404) throw new UserError(problemDetail(answer));
     if (!answer.ok) throw failure('POST', path, answer);
-    if (answer.parsed === null || typeof answer.parsed !== 'object') {
-      throw new UserError(
-        `POST ${path} answered something that is not JSON: ${answer.text.trim()}`
-      );
-    }
-    return { status: answer.status, event: answer.parsed, text: answer.text };
+    return {
+      status: answer.status,
+      event: jsonBody('POST', path, answer),
+      text: answer.text,
+    };
   }
 
   /**
@@ -327,8 +444,8 @@ export class JunoClient {
     const path = `/api/agent/${encodeURIComponent(id)}`;
     const res = await this.#request('GET', path);
     if (res.status === 404) return null;
-    if (!res.ok || res.parsed === null) throw failure('GET', path, res);
-    return res.parsed;
+    if (!res.ok) throw failure('GET', path, res);
+    return jsonBody('GET', path, res);
   }
 
   /**
@@ -343,24 +460,44 @@ export class JunoClient {
   /**
    * #send is the one place a request leaves this CLI, returning the fetch
    * Response unread so a stream can be read as it arrives.
+   *
+   * A redirect is not followed. Juno's API never redirects, so a 3xx comes
+   * from something in front of it, typically an auth proxy sending the
+   * request to its sign-in page. Following it would hand the caller that
+   * page's HTML as a 200.
    */
   async #send(method, path, body) {
     const url = `${this.target}${path}`;
     // Every request carries the header, the existing commands' included:
     // one client, one header.
     const headers = { 'X-Juno-Client': this.client };
+    if (this.#token) headers.authorization = `Bearer ${this.#token}`;
     if (body) headers['content-type'] = 'application/json';
+    let res;
     try {
-      return await this.fetch(url, {
+      res = await this.fetch(url, {
         method,
         headers,
         body: body ? JSON.stringify(body) : undefined,
+        redirect: 'manual',
       });
     } catch (err) {
       throw new UnreachableError(
         `cannot reach Juno at ${this.target}: ${err.message}`
       );
     }
+    if (res.status >= 300 && res.status < 400) {
+      const location = res.headers?.get?.('location');
+      throw new UserError(
+        `${method} ${path} was redirected (${res.status})` +
+          (location ? ` to ${location}` : '') +
+          `: ${this.target} looks like it is behind an auth proxy or is ` +
+          'not the Juno API. Point the CLI at an address that reaches Juno ' +
+          'directly with --url or $JUNO_URL (inside a working copy, ' +
+          "package.json's juno.target is used otherwise)"
+      );
+    }
+    return res;
   }
 
   async #read(res) {
@@ -429,6 +566,22 @@ async function* ndjson(body, target) {
   yield* lines(true);
 }
 
+/**
+ * jsonBody is a 2xx answer's parsed body, which every route this client calls
+ * answers as a JSON object. Anything else came from something other than
+ * Juno, such as a proxy's HTML page or a wrong URL. It is an error, never an
+ * empty success, because a caller reading fields off null either crashes or
+ * quietly does nothing.
+ */
+function jsonBody(method, path, res) {
+  if (res.parsed === null || typeof res.parsed !== 'object') {
+    throw new UserError(
+      `${method} ${path} answered something that is not JSON: ${res.text.trim()}`
+    );
+  }
+  return res.parsed;
+}
+
 /** The server's own words in an error answer: Huma's `detail`, else the body. */
 function problemDetail(res) {
   return (
@@ -436,13 +589,22 @@ function problemDetail(res) {
   );
 }
 
-/** A UserError for a non-ok answer, carrying the server's own words. */
+/**
+ * A UserError for a non-ok answer, carrying the server's own words. A 401
+ * adds how to get a credential; a 403 is the server's detail as is, because
+ * it already names what the key may not do.
+ */
 function failure(method, path, res) {
+  const message = `${method} ${path} failed (${res.status}): ${problemDetail(res)}`;
   return new UserError(
-    `${method} ${path} failed (${res.status}): ${problemDetail(res)}`
+    res.status === 401 ? `${message}\n${UNAUTHORIZED_HINT}` : message
   );
 }
 
+const UNAUTHORIZED_HINT =
+  'Create an API key under Settings → API keys and pass it with --token, ' +
+  '$JUNO_TOKEN or `juno config set token`.';
+
 /**
  * The words of a 422: the gateway's own detail names the failing field (`/id`,
  * `/ops/0/when`, `/` for the root); Huma's request validation puts it in

package/src/app-dev/build.js

@@ -0,0 +1,134 @@
+import { mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { createRequire } from 'node:module';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+import { UserError } from '../errors.js';
+
+/**
+ * loadFromWorkingCopy imports `name` as the working copy's own code would:
+ * resolved from its package.json, so out of its node_modules. The CLI has no
+ * runtime dependencies (`.claude/rules/cli.md`, "A thin client"), and the dev
+ * server must run the esbuild and testkit the project's own build and tests
+ * run, not a second copy of either.
+ */
+export async function loadFromWorkingCopy(cwd, name) {
+  let resolved;
+  try {
+    resolved = createRequire(join(cwd, 'package.json')).resolve(name);
+  } catch {
+    throw new UserError(
+      `${name} is not installed in this working copy — run npm install`
+    );
+  }
+  return import(pathToFileURL(resolved).href);
+}
+
+/**
+ * createBuilder wraps the working copy's esbuild with the two builds the dev
+ * server makes: a page/ module for the browser, as ingest bundles it
+ * (internal/verify/page.go's bundlePage), and src/app.ts for Node, imported
+ * in process for the harness.
+ *
+ * A page module is built on every request, so a save needs no watcher to show
+ * up. The handlers are built once and kept: `invalidate()` marks them for a
+ * rebuild on the next `handlers()`, and a rebuild that fails keeps the last
+ * good module serving, with the failure in `error` — a syntax error mid-edit
+ * must not take the page's working calls down with it. `generation` counts
+ * the handler builds that succeeded, so a caller holding something built from
+ * one module can tell when it is out of date.
+ */
+export async function createBuilder(cwd) {
+  const mod = await loadFromWorkingCopy(cwd, 'esbuild');
+  const esbuild = typeof mod.build === 'function' ? mod : mod.default;
+  const tmp = await mkdtemp(join(tmpdir(), 'juno-app-dev-'));
+
+  let generation = 0;
+  let good = null; // the last module that built and imported
+  let dirty = true;
+  let error = null; // the last rebuild's failure, null after a success
+
+  const builder = {
+    /** The page/ module at abs, bundled for the browser, as JavaScript text. */
+    async page(abs) {
+      const out = await esbuild.build({
+        entryPoints: [abs],
+        absWorkingDir: cwd,
+        bundle: true,
+        format: 'esm',
+        platform: 'browser',
+        target: 'es2020',
+        write: false,
+        logLevel: 'silent',
+      });
+      return out.outputFiles[0].text;
+    },
+
+    /**
+     * The handlers module's default export, rebuilt first when invalidated.
+     * Throws only when nothing has ever built.
+     */
+    async handlers() {
+      if (dirty) {
+        dirty = false;
+        try {
+          good = await buildHandlers();
+          error = null;
+        } catch (err) {
+          // Retried on the next call too, so a fix is picked up even before
+          // anything invalidates.
+          error = err;
+          dirty = true;
+        }
+      }
+      if (!good) throw error;
+      return good;
+    },
+
+    /** Marks src/ as changed: the next handlers() rebuilds. */
+    invalidate() {
+      dirty = true;
+    },
+
+    /** The last handlers rebuild's failure, or null. */
+    get error() {
+      return error;
+    },
+
+    /** How many handler builds have succeeded. */
+    get generation() {
+      return generation;
+    },
+
+    /** Removes the temp directory the handler builds are written to. */
+    close() {
+      return rm(tmp, { recursive: true, force: true });
+    },
+  };
+
+  /**
+   * One Node build of src/app.ts, written under tmp and imported with a
+   * cache-busting query: Node caches a module by URL, and the same URL would
+   * answer the first build forever.
+   */
+  async function buildHandlers() {
+    const out = await esbuild.build({
+      entryPoints: [join(cwd, 'src', 'app.ts')],
+      absWorkingDir: cwd,
+      bundle: true,
+      format: 'esm',
+      platform: 'node',
+      target: 'node20',
+      write: false,
+      logLevel: 'silent',
+    });
+    const file = join(tmp, 'app.mjs');
+    await writeFile(file, out.outputFiles[0].text, 'utf8');
+    generation += 1;
+    const mod = await import(`${pathToFileURL(file).href}?v=${generation}`);
+    return mod.default;
+  }
+
+  return builder;
+}

package/src/app-dev/harness.js

@@ -0,0 +1,108 @@
+import { readFile } from 'node:fs/promises';
+import { isAbsolute, relative, resolve } from 'node:path';
+
+import { UserError } from '../errors.js';
+import { loadFromWorkingCopy } from './build.js';
+
+/**
+ * createDevHarness runs the app's handlers the way `npm test` does: through
+ * the working copy's own @junoflow/testkit appHarness, so the dev server is
+ * exactly as strict as the project's tests — an unanswered target is a
+ * refusal naming `binding.method`, not a silent `undefined`.
+ *
+ * The world comes from a scenario file, the shape `h.scenario` takes
+ * (plan-local-dev-6 decision 7). With none, the world is empty, and every
+ * call that asks it something fails visibly.
+ *
+ * One harness lives until the scenario or the manifest changes; then a fresh
+ * one is built and the scenario re-applied to it. A handlers rebuild keeps
+ * the harness: its `app` reads the builder's latest module on every call.
+ */
+export async function createDevHarness({ cwd, manifest, builder }) {
+  const { appHarness } = await loadFromWorkingCopy(cwd, '@junoflow/testkit');
+  if (typeof appHarness !== 'function') {
+    throw new UserError(
+      '@junoflow/testkit in this working copy has no appHarness — run npm install @junoflow/testkit@latest'
+    );
+  }
+
+  let latest = { handlers: {} };
+  const app = {
+    get handlers() {
+      return latest.handlers;
+    },
+  };
+
+  const dev = {
+    manifest,
+    /** The scenario in use, `{path, value}` (path relative to cwd), or null. */
+    scenario: null,
+    /** The testkit harness calls go through; replaced by a reset. */
+    h: null,
+
+    /**
+     * Reads and applies the scenario at path (relative to cwd), or the empty
+     * world for null. A file that is not a scenario fails here, naming it,
+     * and the scenario in use stays.
+     */
+    async useScenario(path) {
+      if (path == null) {
+        dev.scenario = null;
+      } else {
+        const abs = isAbsolute(path) ? path : resolve(cwd, path);
+        const rel = relative(cwd, abs);
+        const value = await readScenario(abs, rel);
+        // Applied to a throwaway harness first, so a bad key is refused with
+        // the testkit's message before anything is replaced.
+        try {
+          appHarness({ manifest: dev.manifest, app }).scenario(value);
+        } catch (err) {
+          throw new UserError(`${rel}: ${err.message}`);
+        }
+        dev.scenario = { path: rel, value };
+      }
+      reset();
+      return dev;
+    },
+
+    /** Replaces the manifest (manifest.json was saved) and resets. */
+    setManifest(m) {
+      dev.manifest = m;
+      reset();
+      return dev;
+    },
+
+    /**
+     * Calls handler name with input, after picking up the latest handlers
+     * build. Resolves to the result after the JSON round trip; throws what
+     * the handler threw, the harness's refusal, or the build's failure.
+     */
+    async call(name, input) {
+      // A module with no default export reaches the harness's own refusal.
+      latest = (await builder.handlers()) ?? {};
+      return dev.h.call(name, input);
+    },
+  };
+
+  function reset() {
+    dev.h = appHarness({ manifest: dev.manifest, app });
+    if (dev.scenario) dev.h.scenario(dev.scenario.value);
+  }
+
+  reset();
+  return dev;
+}
+
+async function readScenario(abs, rel) {
+  let text;
+  try {
+    text = await readFile(abs, 'utf8');
+  } catch (err) {
+    throw new UserError(`cannot read scenario ${rel}: ${err.message}`);
+  }
+  try {
+    return JSON.parse(text);
+  } catch (err) {
+    throw new UserError(`scenario ${rel} is not valid JSON: ${err.message}`);
+  }
+}