@junoflow/cli 0.6.0 → 0.9.0

package/src/commands/pull.js

@@ -1,30 +1,47 @@
-import { execFile } from 'node:child_process';
-import { mkdir, readFile, writeFile } from 'node:fs/promises';
-import { dirname, join } from 'node:path';
-import { promisify } from 'node:util';
-
 import { clientName, JunoClient } from '../api.js';
 import { UserError } from '../errors.js';
-import { readManifest } from '../project.js';
+import {
+  readIntegrationBaseVersion,
+  readManifest,
+  updateIntegrationPackage,
+} from '../project.js';
+import { stampTypeFiles } from '../stamp.js';
 import { resolveTarget } from '../target.js';
-
-const execFileAsync = promisify(execFile);
+import {
+  baseArtifactPaths,
+  MANIFEST,
+  manifestText,
+  pullArtifacts,
+  requireCleanTree,
+  setDependencies,
+  writeChangedFiles,
+} from '../working-copy.js';
+import { pickTypeFiles } from './gen-types.js';
 
 export const PULL_USAGE = 'juno integration pull [--force] [--id <id>]';
 
 /**
- * `juno integration pull` — write back the manifest and sources Juno holds,
- * and package.json's `scripts`.
+ * `juno integration pull` — make the working copy's artifact files the
+ * install's active version: manifest.json and every file under src/ and
+ * test/, exactly as the version stores them, plus types/ regenerated and
+ * stamped against the pulled manifest, and package.json's
+ * `juno.base_version` (the version pulled, which the next check and deploy
+ * send).
  *
  * This exists because the zip is a good first touch and a bad second one: once
  * the authoring agent has edited an integration you deployed, downloading the
  * project again would clobber your working tree, while pull touches only the
- * things Juno owns. The script lines are among them — the server generates
- * them (POST /api/integrations/scaffold renders this install's project), so a
- * project made by an older CLI picks up the current commands; every other key
- * in package.json is the author's and stays. It still refuses a dirty tree
- * without --force, because an uncommitted edit is the one thing git cannot get
- * back for you.
+ * files Juno stores. The scaffold's script lines are not among them: they are
+ * project content, and an author's own edits to them are theirs — a fresh
+ * `juno integration init` is how to get the current ones. `dependencies` is
+ * replaced only when the pulled manifest declares some (an agent-authored
+ * integration); otherwise they live in package.json alone, which Juno does not
+ * store, and stay. Every other key in package.json, and of `juno`, stays.
+ *
+ * A local file is deleted only when the base version had it and the pulled
+ * one does not; a file neither has is one not deployed yet, and stays. It
+ * still refuses a dirty tree without --force, because an uncommitted edit is
+ * the one thing git cannot get back for you.
  */
 export async function pull(argv, io) {
   const target = await resolveTarget({
@@ -32,26 +49,26 @@ export async function pull(argv, io) {
     cwd: io.cwd,
     env: io.env,
   });
-  const id = argv.id ?? (await readManifest(io.cwd)).id;
+  let manifestId;
+  try {
+    manifestId = (await readManifest(io.cwd)).id;
+  } catch (err) {
+    // With --id the manifest is about to be replaced, so a broken one is
+    // no reason to refuse.
+    if (argv.id === undefined) throw err;
+  }
+  const id = argv.id ?? manifestId;
   if (!id) {
     throw new UserError(
       'manifest.json declares no id — pass --id <integration>'
     );
   }
 
-  if (!argv.force) {
-    const dirty = await dirtyPaths(io.cwd);
-    if (dirty === null) {
-      io.warn(
-        'not a git repository — pull will overwrite manifest.json, src/ and package.json scripts with no undo'
-      );
-    } else if (dirty.length > 0) {
-      throw new UserError(
-        `working tree has uncommitted changes:\n${dirty.map((p) => `  ${p}`).join('\n')}\n` +
-          'Commit or stash them, or pass --force to overwrite.'
-      );
-    }
-  }
+  await requireCleanTree(io.cwd, {
+    force: argv.force,
+    overwrites: `${MANIFEST}, src/, test/ and types/`,
+    io,
+  });
 
   const client =
     argv.client ?? new JunoClient(target, { client: clientName(io.env) });
@@ -61,83 +78,60 @@ export async function pull(argv, io) {
       `${id} has no active version on ${target} — nothing to pull`
     );
   }
-  // Fetched before anything is written, so a failure here leaves the working
-  // copy as it was.
-  const scripts = scaffoldScripts(
-    await client.scaffold(id, { target }),
-    target
+  // Everything is fetched before anything is written, so a failure leaves
+  // the working copy as it was.
+  const manifestRaw = manifestText(detail.manifest);
+  const stored = { [MANIFEST]: manifestRaw, ...detail.source_files };
+  const types = stampTypeFiles(
+    pickTypeFiles(await client.typegen(detail.manifest)),
+    manifestRaw
   );
+  // The base belongs to the install the manifest names; pulling another
+  // (--id) has no base to diff against, so it deletes nothing.
+  const base = await baseArtifactPaths({
+    base:
+      id === manifestId ? await readIntegrationBaseVersion(io.cwd) : undefined,
+    version: detail.version,
+    stored,
+    read: async (v) => {
+      const b = await client.getIntegrationVersion(id, v);
+      return b ? [MANIFEST, ...Object.keys(b.SourceFiles ?? {})] : null;
+    },
+    id,
+    target,
+    io,
+  });
 
-  const written = ['manifest.json'];
-  await writeFile(
-    join(io.cwd, 'manifest.json'),
-    `${JSON.stringify(detail.manifest, null, 2)}\n`,
-    'utf8'
+  const { written, removed } = await pullArtifacts(io.cwd, {
+    stored,
+    base,
+    kind: 'integration',
+  });
+  written.push(
+    ...(await writeChangedFiles(
+      io.cwd,
+      Object.fromEntries(
+        Object.entries(types).map(([name, content]) => [
+          `types/${name}`,
+          content,
+        ])
+      )
+    ))
   );
-  for (const [rel, content] of Object.entries(detail.source_files ?? {})) {
-    const path = join(io.cwd, rel);
-    await mkdir(dirname(path), { recursive: true });
-    await writeFile(path, content, 'utf8');
-    written.push(rel);
-  }
-  if (await replaceScripts(io.cwd, scripts, io)) written.push('package.json');
-  io.log(
-    `pulled ${id} v${detail.version} from ${target} (${written.sort().join(', ')})`
+  const wrote = await updateIntegrationPackage(
+    io.cwd,
+    (pkg) => {
+      if (Object.keys(detail.manifest.dependencies ?? {}).length) {
+        setDependencies(pkg, detail.manifest);
+      }
+      pkg.juno.base_version = detail.version;
+    },
+    io
   );
+  if (wrote) written.push('package.json');
   io.log(
-    'run `npm run types` to regenerate types/ against the pulled manifest'
+    `pulled ${id} v${detail.version} from ${target} (${written.sort().join(', ')})`
   );
+  if (removed.length) io.log(`removed ${removed.join(', ')}`);
   return 0;
 }
-
-/** The `scripts` of the package.json a scaffold answered. */
-function scaffoldScripts(files, target) {
-  try {
-    const scripts = JSON.parse(files['package.json']).scripts;
-    if (scripts && typeof scripts === 'object') return scripts;
-  } catch {
-    // Reported below.
-  }
-  throw new UserError(
-    `${target} answered a project with no readable package.json scripts`
-  );
-}
-
-/**
- * replaceScripts sets package.json's `scripts`, keeping every other key and
- * its order, written the way npm writes it. A missing or unreadable
- * package.json is left alone with a warning: pull is not the place to invent
- * one. Returns whether it wrote.
- */
-async function replaceScripts(cwd, scripts, io) {
-  const path = join(cwd, 'package.json');
-  let pkg;
-  try {
-    pkg = JSON.parse(await readFile(path, 'utf8'));
-  } catch {
-    io.warn('no readable package.json — its scripts were not updated');
-    return false;
-  }
-  pkg.scripts = scripts;
-  await writeFile(path, `${JSON.stringify(pkg, null, 2)}\n`, 'utf8');
-  return true;
-}
-
-/**
- * Returns the paths git reports as changed, [] for a clean tree, or null when
- * this is not a git repository at all — three states the caller treats
- * differently, so they must not collapse into a boolean.
- */
-export async function dirtyPaths(cwd) {
-  try {
-    const { stdout } = await execFileAsync('git', ['status', '--porcelain'], {
-      cwd,
-    });
-    return stdout
-      .split('\n')
-      .map((line) => line.trim())
-      .filter(Boolean);
-  } catch {
-    return null;
-  }
-}

package/src/errors.js

@@ -52,9 +52,9 @@ export class UnreachableError extends Error {
 }
 
 /**
- * ConflictError is a deploy the server refused because the working copy is
- * stale: the flow's active version is not the one `juno.base_version` says it
- * was pulled from (a 409). The top-level handler prints the server's message,
+ * ConflictError is a deploy or check the server refused because the working
+ * copy is stale: the flow's, integration's or app's active version is not the
+ * one `juno.base_version` says it was pulled from (a 409). The top-level handler prints the server's message,
  * which names both versions, and exits 4. The fix is `npm run pull`, or
  * deploying with --force to replace whatever is active.
  */

package/src/exit.js

@@ -8,8 +8,8 @@
  *   2  usage: unknown command or flag, bad --input, a gateway 422 or 404,
  *      a bad --jq
  *   3  the instance is unreachable (the fetch itself failed)
- *   4  a deploy conflict: `juno flow deploy` / `check` against a flow whose
- *      active version is not the working copy's base_version (a 409)
+ *   4  a deploy conflict: a working-copy deploy or check (any kind) got a
+ *      409 because the active version is not the copy's base_version
  *   5  `juno ask` / `session approve`: the turn is still running (pending)
  *   6  `juno ask` / `session approve`: the assistant is awaiting input
  */

package/src/flow-project.js

@@ -1,128 +1,78 @@
-import { readFile, writeFile } from 'node:fs/promises';
-import { join } from 'node:path';
-
 import { UserError } from './errors.js';
+import { readSourceFiles, readTestFiles } from './project.js';
+import {
+  baseVersionOf,
+  MANIFEST,
+  manifestText,
+  PACKAGE_JSON,
+  readBoundPackage,
+  readManifestFile,
+  typeFiles,
+  writeChangedFiles,
+  writePackageJSON,
+} from './working-copy.js';
 
 /**
- * A flow working copy is flat (plan-external-agents-flows-as-files.md,
- * Decision 9): manifest.json and flow.ts are the author's, the two .d.ts
- * files are generated, and package.json's `juno` block binds the directory to
- * one flow. The layout is the server's (POST /api/flows/scaffold); this
- * module only knows the handful of names a command reads or writes back.
+ * A flow working copy is laid out as an integration's is: manifest.json, the
+ * sources under src/ (entry src/flow.ts) and the tests under test/ are the
+ * author's, types/ is
+ * generated, and package.json's `juno` block binds the directory to one flow.
+ * The layout is the server's (POST /api/flows/scaffold); this module only
+ * knows the handful of names a command reads or writes back, and what it
+ * shares with an app working copy lives in working-copy.js.
  */
-export const MANIFEST = 'manifest.json';
-export const FLOW_TS = 'flow.ts';
-export const PACKAGE_JSON = 'package.json';
+export { MANIFEST, PACKAGE_JSON, manifestText, typeFiles };
+export const SRC_DIR = 'src';
+export const FLOW_ENTRY = 'src/flow.ts';
 
 /**
  * readFlowProject reads what ingest takes: the manifest (parsed, so a broken
- * one fails here with its parse error rather than as a server 422), flow.ts,
- * and the binding in package.json. `flowId` is `juno.flow_id` — the id is
- * identity, so the CLI sends it and the server refuses a manifest naming
- * another — and `baseVersion` is `juno.base_version`, absent for a flow that
- * has never been deployed from this copy.
+ * one fails here with its parse error rather than as a server 422), every
+ * .ts and .json file under src/ and test/, and the binding in package.json.
+ * Juno stores test/ with the version and never compiles it. A copy
+ * with no src/flow.ts is refused before anything is sent. `flowId` is
+ * `juno.flow_id` — the id is identity, so the CLI sends it and the server
+ * refuses a manifest naming another — and `baseVersion` is
+ * `juno.base_version`, absent for a flow that has never been deployed from
+ * this copy.
  */
 export async function readFlowProject(cwd) {
   const pkg = await readFlowPackage(cwd);
+  const files = await readSourceFiles(cwd);
+  if (!Object.hasOwn(files, FLOW_ENTRY)) {
+    throw new UserError(
+      `no ${FLOW_ENTRY} — a flow working copy's entry is ${FLOW_ENTRY}`
+    );
+  }
   return {
     ...(await readFlowManifest(cwd)),
-    flowTS: await readText(cwd, FLOW_TS),
+    files: { ...files, ...(await readTestFiles(cwd)) },
     packageJSON: pkg,
     flowId: pkg.juno.flow_id,
-    baseVersion: Number.isInteger(pkg.juno.base_version)
-      ? pkg.juno.base_version
-      : undefined,
+    baseVersion: baseVersionOf(pkg),
   };
 }
 
 /** readFlowManifest is manifest.json, as bytes and parsed. */
-export async function readFlowManifest(cwd) {
-  const manifestRaw = await readText(cwd, MANIFEST);
-  try {
-    return { manifest: JSON.parse(manifestRaw), manifestRaw };
-  } catch (err) {
-    throw new UserError(`${MANIFEST} is not valid JSON: ${err.message}`);
-  }
-}
+export const readFlowManifest = readManifestFile;
 
-/**
- * readFlowPackage is package.json, refusing a directory that is not a flow
- * working copy — every command but `init` acts on the current directory, and
- * running one from the wrong place should say so rather than fail on a
- * missing flow.ts.
- */
-export async function readFlowPackage(cwd) {
-  let pkg = null;
-  try {
-    pkg = JSON.parse(await readFile(join(cwd, PACKAGE_JSON), 'utf8'));
-  } catch {
-    // Missing or unreadable: reported below as not a working copy.
-  }
-  if (typeof pkg?.juno?.flow_id !== 'string' || pkg.juno.flow_id === '') {
-    throw new UserError(
-      `${cwd} is not a flow working copy (no juno.flow_id in package.json) — ` +
-        'run `juno flow init <id>` to make one'
-    );
-  }
-  return pkg;
+/** readFlowPackage is package.json, refusing a directory that is not a flow working copy. */
+export function readFlowPackage(cwd) {
+  return readBoundPackage(cwd, { kind: 'flow', idKey: 'flow_id' });
 }
 
 /**
- * updatePackageJSON rewrites package.json through `mutate`, keeping every key
- * it does not touch (and their order), with a two-space indent and a trailing
- * newline — the way npm writes it, so the diff is only what changed.
+ * updatePackageJSON rewrites a flow working copy's package.json through
+ * `mutate`, keeping every key it does not touch (and their order).
  */
 export async function updatePackageJSON(cwd, mutate) {
   const pkg = await readFlowPackage(cwd);
   mutate(pkg);
-  await writeFile(
-    join(cwd, PACKAGE_JSON),
-    `${JSON.stringify(pkg, null, 2)}\n`,
-    'utf8'
-  );
+  await writePackageJSON(cwd, pkg);
 }
 
 /**
  * writeFlowFiles writes files by working-copy name, skipping one whose
- * content is already what is on disk so a watcher does not see a write that
- * changed nothing. Returns the names it wrote.
+ * content is already what is on disk. Returns the names it wrote.
  */
-export async function writeFlowFiles(cwd, files) {
-  const written = [];
-  for (const [name, content] of Object.entries(files)) {
-    const path = join(cwd, name);
-    let current = null;
-    try {
-      current = await readFile(path, 'utf8');
-    } catch {
-      // Not there yet.
-    }
-    if (current === content) continue;
-    await writeFile(path, content, 'utf8');
-    written.push(name);
-  }
-  return written.sort();
-}
-
-/** The canonical manifest a route answered, as manifest.json holds it. */
-export function manifestText(manifest) {
-  return `${JSON.stringify(manifest, null, 2)}\n`;
-}
-
-/**
- * The .d.ts files of a route's `types`. Filtering by extension rather than
- * naming the two keeps a future third file working without a CLI release.
- */
-export function typeFiles(types) {
-  return Object.fromEntries(
-    Object.entries(types ?? {}).filter(([name]) => name.endsWith('.d.ts'))
-  );
-}
-
-async function readText(cwd, name) {
-  try {
-    return await readFile(join(cwd, name), 'utf8');
-  } catch {
-    throw new UserError(`no ${name} in ${cwd}`);
-  }
-}
+export const writeFlowFiles = writeChangedFiles;

package/src/index.js

@@ -4,6 +4,12 @@ import {
   AGENT_SKILL_INSTALL_USAGE,
   agentSkillInstall,
 } from './commands/agent-skill-install.js';
+import { APP_CHECK_USAGE, appCheck } from './commands/app-check.js';
+import { APP_DEPLOY_USAGE, appDeploy } from './commands/app-deploy.js';
+import { APP_DEV_USAGE, appDev } from './commands/app-dev.js';
+import { APP_GEN_TYPES_USAGE, appGenTypes } from './commands/app-gen-types.js';
+import { APP_INIT_USAGE, appInit } from './commands/app-init.js';
+import { APP_PULL_USAGE, appPull } from './commands/app-pull.js';
 import { ASK_USAGE, ask } from './commands/ask.js';
 import { CHECK_USAGE, check } from './commands/check.js';
 import { CONFIG_SET_USAGE, configSet } from './commands/config.js';
@@ -18,6 +24,7 @@ import {
   FLOW_GEN_TYPES_USAGE,
   flowGenTypes,
 } from './commands/flow-gen-types.js';
+import { FLOW_FIXTURE_USAGE, flowFixture } from './commands/flow-fixture.js';
 import { FLOW_INIT_USAGE, flowInit } from './commands/flow-init.js';
 import { FLOW_PULL_USAGE, flowPull } from './commands/flow-pull.js';
 import { GEN_TYPES_USAGE, genTypes } from './commands/gen-types.js';
@@ -151,6 +158,15 @@ const WORKING_COPY = {
     options: { ...URL_OPTION, force: { type: 'boolean', default: false } },
     usage: FLOW_PULL_USAGE,
   },
+  'flow fixture': {
+    run: flowFixture,
+    options: {
+      ...URL_OPTION,
+      run: { type: 'string' },
+      force: { type: 'boolean', default: false },
+    },
+    usage: FLOW_FIXTURE_USAGE,
+  },
   'integration init': {
     run: init,
     options: {
@@ -189,6 +205,7 @@ const WORKING_COPY = {
       ...URL_OPTION,
       id: { type: 'string' },
       watch: { type: 'boolean', default: false },
+      force: { type: 'boolean', default: false },
       json: { type: 'boolean', default: false },
     },
     usage: DEPLOY_USAGE,
@@ -202,6 +219,50 @@ const WORKING_COPY = {
     },
     usage: PULL_USAGE,
   },
+  'app init': {
+    run: appInit,
+    options: { ...URL_OPTION, here: { type: 'boolean', default: false } },
+    usage: APP_INIT_USAGE,
+    positional: true,
+  },
+  'app gen-types': {
+    run: appGenTypes,
+    options: URL_OPTION,
+    usage: APP_GEN_TYPES_USAGE,
+  },
+  'app check': {
+    run: appCheck,
+    options: {
+      ...URL_OPTION,
+      'skip-local': { type: 'boolean', default: false },
+      json: { type: 'boolean', default: false },
+    },
+    usage: APP_CHECK_USAGE,
+  },
+  'app deploy': {
+    run: appDeploy,
+    options: {
+      ...URL_OPTION,
+      watch: { type: 'boolean', default: false },
+      force: { type: 'boolean', default: false },
+      json: { type: 'boolean', default: false },
+    },
+    usage: APP_DEPLOY_USAGE,
+  },
+  'app pull': {
+    run: appPull,
+    options: { ...URL_OPTION, force: { type: 'boolean', default: false } },
+    usage: APP_PULL_USAGE,
+  },
+  // No --url: the dev server is offline and never reads juno.target.
+  'app dev': {
+    run: appDev,
+    options: {
+      port: { type: 'string' },
+      scenario: { type: 'string' },
+    },
+    usage: APP_DEV_USAGE,
+  },
 };
 
 /** The handler of a non-tool row, working-copy or not, or undefined. */
@@ -223,7 +284,7 @@ function dispatchable(command) {
   return row && DISPATCHABLE.includes(row) ? row : undefined;
 }
 
-const USAGE = `juno — operate a Juno instance, and develop flows and integrations for it
+const USAGE = `juno — operate a Juno instance, and develop flows, integrations and apps for it
 
 Usage: juno <command> [options]
        juno <group> <verb> [id] [--input <json>|-|@file] [--jq <expr>]

package/src/project.js

@@ -2,15 +2,22 @@ import { readFile, readdir, mkdir, writeFile } from 'node:fs/promises';
 import { dirname, join, posix, relative, sep } from 'node:path';
 
 import { UserError } from './errors.js';
+import { PACKAGE_JSON, writePackageJSON } from './working-copy.js';
 
 /** Only these reach the server. Everything else is project furniture. */
 const SOURCE_EXTENSIONS = ['.ts', '.json'];
 const SOURCE_DIR = 'src';
+const TEST_DIR = 'test';
 
 /**
- * Read the four things Juno looks at: manifest.json, the sources under src/,
- * package.json's dependencies, and the lockfile. types/ and test/ are the
- * author's — they are never uploaded, and never compiled server-side.
+ * Read the four things Juno looks at: manifest.json, the sources under src/
+ * and test/, package.json's dependencies, and the lockfile. test/ is stored
+ * with the version but never compiled, linted or run server-side; types/ is
+ * generated and never uploaded.
+ *
+ * `baseVersion` is package.json's `juno.base_version`, the version this copy
+ * was pulled from or last deployed as, or undefined when it records none (a
+ * copy made before the check existed, or one with no `juno` block at all).
  */
 export async function readProject(cwd = process.cwd()) {
   const manifest = await readManifest(cwd);
@@ -18,14 +25,61 @@ export async function readProject(cwd = process.cwd()) {
   if (Object.keys(files).length === 0) {
     throw new UserError(`no TypeScript sources found under ${SOURCE_DIR}/`);
   }
+  const packageJSON = await readOptional(join(cwd, PACKAGE_JSON));
   return {
     manifest,
-    files,
-    packageJSON: await readOptional(join(cwd, 'package.json')),
+    files: { ...files, ...(await readTestFiles(cwd)) },
+    packageJSON,
     lockfile: await readOptional(join(cwd, 'package-lock.json')),
+    baseVersion: baseVersionOfText(packageJSON),
   };
 }
 
+/**
+ * readIntegrationBaseVersion is package.json's `juno.base_version`, or
+ * undefined: what `pull` diffs against without reading the sources.
+ */
+export async function readIntegrationBaseVersion(cwd) {
+  return baseVersionOfText(await readOptional(join(cwd, PACKAGE_JSON)));
+}
+
+/** `juno.base_version` of package.json's text, or undefined. */
+function baseVersionOfText(text) {
+  let pkg;
+  try {
+    pkg = JSON.parse(text);
+  } catch {
+    return undefined;
+  }
+  const base = pkg?.juno?.base_version;
+  return Number.isInteger(base) ? base : undefined;
+}
+
+/**
+ * updateIntegrationPackage rewrites package.json through `mutate`, keeping
+ * every key it does not touch (and their order). `juno` is handed over as an
+ * object even when the copy has none yet: an integration copy carries one only
+ * once it records a target or a base. A missing or unreadable package.json is
+ * left alone with a warning — no command here is the place to invent one.
+ * Returns whether it wrote.
+ */
+export async function updateIntegrationPackage(cwd, mutate, io) {
+  let pkg;
+  try {
+    pkg = JSON.parse(await readFile(join(cwd, PACKAGE_JSON), 'utf8'));
+  } catch {
+    pkg = null;
+  }
+  if (pkg === null || typeof pkg !== 'object' || Array.isArray(pkg)) {
+    io.warn(`no readable ${PACKAGE_JSON} — it was not updated`);
+    return false;
+  }
+  if (pkg.juno === null || typeof pkg.juno !== 'object') pkg.juno = {};
+  mutate(pkg);
+  await writePackageJSON(cwd, pkg);
+  return true;
+}
+
 /**
  * The manifest as it sits on disk. The stamp in types/integration-env.d.ts
  * fingerprints these exact bytes, so both writing and verifying it go through
@@ -51,15 +105,29 @@ export async function readManifest(cwd = process.cwd()) {
 }
 
 /** Walks src/ and returns repo-relative POSIX paths → content. */
-export async function readSourceFiles(cwd = process.cwd()) {
-  const root = join(cwd, SOURCE_DIR);
+export function readSourceFiles(cwd = process.cwd()) {
+  return readSourceTree(cwd, SOURCE_DIR);
+}
+
+/**
+ * readTestFiles is readSourceFiles for test/: the same .ts and .json rule,
+ * because Juno stores tests beside the sources under the same path rules.
+ * Every kind's working copy sends them; none requires them.
+ */
+export function readTestFiles(cwd = process.cwd()) {
+  return readSourceTree(cwd, TEST_DIR);
+}
+
+/** readSourceTree walks dir for .ts and .json files, by repo-relative POSIX path. */
+async function readSourceTree(cwd, dir) {
+  const root = join(cwd, dir);
   const files = {};
   async function walk(dir) {
     let entries;
     try {
       entries = await readdir(dir, { withFileTypes: true });
     } catch {
-      return; // no src/ at all; the caller reports it
+      return; // no such directory at all; the caller reports a missing src/
     }
     for (const entry of entries) {
       const full = join(dir, entry.name);