@junoflow/cli 0.6.0 → 0.9.0

package/src/commands/check.js

@@ -6,6 +6,7 @@ import { printDiagnosticsJSON, printJSON } from '../diagnostics.js';
 import { DiagnosticsError, UserError } from '../errors.js';
 import { readProject } from '../project.js';
 import { resolveTarget } from '../target.js';
+import { baseFor } from './deploy.js';
 import { verifyTypes } from './verify-types.js';
 
 export const CHECK_USAGE =
@@ -17,7 +18,8 @@ export const CHECK_USAGE =
  * tsc and eslint run locally against the committed types; reserved names,
  * cross-surface collisions and JSON Schema compilation need the server, so
  * they go through ingest?dry_run=1, which stores nothing and is safe to point
- * at a production instance.
+ * at a production instance. It sends `juno.base_version` like deploy does, so
+ * a stale copy is a 409 (exit 4) here, before deploy hits it.
  *
  * --json prints the route's body (or the 422's diagnostics) on stdout and
  * nothing else; the local tools' own output goes to stderr.
@@ -36,19 +38,7 @@ export async function check(argv, io) {
       io.error(err.message);
       failed = true;
     }
-    for (const [label, bin, args] of [
-      ['typecheck', 'tsc', ['--noEmit']],
-      ['lint', 'eslint', ['.']],
-    ]) {
-      const code = await runLocal(bin, args, io, {
-        quietStdout: argv.json,
-      });
-      if (code === SKIPPED) {
-        io.warn(`${label}: ${bin} is not installed — run npm install`);
-        continue;
-      }
-      if (code !== 0) failed = true;
-    }
+    if (await runLocalChecks(argv, io)) failed = true;
   }
 
   const target = await resolveTarget({
@@ -61,7 +51,11 @@ export async function check(argv, io) {
   const project = await readProject(io.cwd);
   let result;
   try {
-    result = await client.ingest(project, { dryRun: true, id: argv.id });
+    result = await client.ingest(project, {
+      dryRun: true,
+      id: argv.id,
+      baseVersion: baseFor(project, argv, io),
+    });
   } catch (err) {
     if (argv.json && err instanceof DiagnosticsError) {
       return printDiagnosticsJSON(err, io);
@@ -81,6 +75,28 @@ export async function check(argv, io) {
 
 export const SKIPPED = -1;
 
+/**
+ * runLocalChecks runs tsc and eslint from the working copy's node_modules,
+ * the offline half of every kind's `check`, and answers whether either
+ * failed. A tool that is not installed is a warning, not a failure: the
+ * server-side half still runs.
+ */
+export async function runLocalChecks(argv, io) {
+  let failed = false;
+  for (const [label, bin, args] of [
+    ['typecheck', 'tsc', ['--noEmit']],
+    ['lint', 'eslint', ['.']],
+  ]) {
+    const code = await runLocal(bin, args, io, { quietStdout: argv.json });
+    if (code === SKIPPED) {
+      io.warn(`${label}: ${bin} is not installed — run npm install`);
+      continue;
+    }
+    if (code !== 0) failed = true;
+  }
+  return failed;
+}
+
 /**
  * Runs a local devtool from node_modules/.bin. Its output goes straight to the
  * terminal: tsc and eslint already print file:line:col, and reformatting them

package/src/commands/deploy.js

@@ -3,18 +3,30 @@ import { join } from 'node:path';
 import { clientName, JunoClient } from '../api.js';
 import { printDiagnosticsJSON, printJSON } from '../diagnostics.js';
 import { DiagnosticsError } from '../errors.js';
-import { readManifestRaw, readProject, writeTypes } from '../project.js';
+import {
+  readManifestRaw,
+  readProject,
+  updateIntegrationPackage,
+  writeTypes,
+} from '../project.js';
 import { resolveTarget } from '../target.js';
 import { stampTypeFiles } from '../stamp.js';
 import { pickTypeFiles } from './gen-types.js';
 import { deployOnChange } from '../watch.js';
 
 export const DEPLOY_USAGE =
-  'juno integration deploy [--watch] [--id <id>] [--json]';
+  'juno integration deploy [--watch] [--force] [--id <id>] [--json]';
 
 /**
  * `juno integration deploy [--watch]` — upload the working copy, verify, activate.
  *
+ * It sends `juno.base_version`, so an install changed elsewhere since this
+ * copy was pulled is a 409 (exit 4) rather than a silent overwrite; --force
+ * sends none and replaces whatever is active. A successful deploy writes the
+ * new version back as the base. --id naming another install sends no base and
+ * writes none back: the base belongs to the install the manifest names (see
+ * baseFor).
+ *
  * The response carries the regenerated types, so a deploy keeps the committed
  * types/ honest without a second round trip that could answer for a different
  * manifest.
@@ -46,25 +58,66 @@ export async function deploy(argv, io) {
 }
 
 async function deployOnce(client, argv, io, target) {
+  // Re-read on every deploy, base included, so the watch loop is checked
+  // against its own previous deploy rather than refused by it.
   const project = await readProject(io.cwd);
-  const result = await client.ingest(project, { id: argv.id });
+  const result = await client.ingest(project, {
+    id: argv.id,
+    baseVersion: argv.force ? undefined : baseFor(project, argv, io),
+  });
   // Stamped against the manifest this deploy was built from, so the watch loop
   // leaves a tree that `juno integration verify-types` accepts.
   const written = await writeTypes(
     stampTypeFiles(pickTypeFiles(result.types), await readManifestRaw(io.cwd)),
     io.cwd
   );
+  if (
+    !deploysElsewhere(project, argv) &&
+    project.baseVersion !== result.version
+  ) {
+    const wrote = await updateIntegrationPackage(
+      io.cwd,
+      (pkg) => {
+        pkg.juno.base_version = result.version;
+      },
+      io
+    );
+    if (wrote) written.push('package.json');
+  }
   if (argv.json) {
     printJSON(result, io);
     return result;
   }
   for (const warning of result.warnings ?? []) io.warn(`warning: ${warning}`);
   io.log(
-    `deployed ${result.id} v${result.version} to ${target} (${written.join(', ')})`
+    `deployed ${result.id} v${result.version} to ${target} (${written.sort().join(', ')})`
   );
   return result;
 }
 
+/**
+ * baseFor is the base a check or deploy sends: the copy's
+ * `juno.base_version`, unless --id names an install other than the
+ * manifest's. That install's versions are ones this copy has never seen, so
+ * there is nothing to compare against, and the warning says the check is off
+ * rather than letting it pass silently. A first deploy to a new id has nothing
+ * to be stale against either, so this needs no --force.
+ */
+export function baseFor(project, argv, io) {
+  if (deploysElsewhere(project, argv)) {
+    io.warn(
+      `no stale-base check: deploying to ${argv.id}, not ${project.manifest?.id}`
+    );
+    return undefined;
+  }
+  return project.baseVersion;
+}
+
+/** Whether --id names an install other than the one the manifest does. */
+function deploysElsewhere(project, argv) {
+  return argv.id !== undefined && argv.id !== project.manifest?.id;
+}
+
 /**
  * Watch mode is the loop the whole design is for: edit the manifest, the types
  * regenerate, and the editor red-squiggles the method you have not written yet.

package/src/commands/flow-check.js

@@ -1,7 +1,7 @@
 import { connect } from '../api.js';
 import { DiagnosticsError } from '../errors.js';
 import { readFlowProject } from '../flow-project.js';
-import { runLocal, SKIPPED } from './check.js';
+import { runLocalChecks } from './check.js';
 import { printDiagnosticsJSON, printJSON } from '../diagnostics.js';
 import { printWarnings } from './flow-deploy.js';
 
@@ -15,23 +15,7 @@ export const FLOW_CHECK_USAGE = 'juno flow check [--skip-local] [--json]';
  */
 export async function flowCheck(argv, io) {
   const project = await readFlowProject(io.cwd);
-  let failed = false;
-
-  if (!argv['skip-local']) {
-    for (const [label, bin, args] of [
-      ['typecheck', 'tsc', ['--noEmit']],
-      ['lint', 'eslint', ['.']],
-    ]) {
-      const code = await runLocal(bin, args, io, {
-        quietStdout: argv.json,
-      });
-      if (code === SKIPPED) {
-        io.warn(`${label}: ${bin} is not installed — run npm install`);
-        continue;
-      }
-      if (code !== 0) failed = true;
-    }
-  }
+  const failed = !argv['skip-local'] && (await runLocalChecks(argv, io));
   warnOnDependencyDrift(project, io);
 
   const { target, client } = await connect(argv, io);
@@ -41,7 +25,7 @@ export async function flowCheck(argv, io) {
       {
         flowId: project.flowId,
         manifest: project.manifest,
-        flowTS: project.flowTS,
+        files: project.files,
         baseVersion: project.baseVersion,
       },
       { dryRun: true }
@@ -57,9 +41,7 @@ export async function flowCheck(argv, io) {
     printJSON(result, io);
   } else {
     printWarnings(result.warnings, io);
-    io.log(
-      `${result.flow_id}: manifest and flow.ts verified against ${target}`
-    );
+    io.log(`${result.flow_id}: manifest and src/ verified against ${target}`);
   }
   return failed ? 1 : 0;
 }

package/src/commands/flow-deploy.js

@@ -8,10 +8,10 @@ import {
   printJSON,
 } from '../diagnostics.js';
 import {
-  FLOW_TS,
   MANIFEST,
   manifestText,
   readFlowProject,
+  SRC_DIR,
   typeFiles,
   updatePackageJSON,
   writeFlowFiles,
@@ -22,15 +22,15 @@ export const FLOW_DEPLOY_USAGE =
   'juno flow deploy [--watch] [--force] [--json]';
 
 /**
- * `juno flow deploy` — upload manifest.json and flow.ts to
+ * `juno flow deploy` — upload manifest.json and src/ to
  * POST /api/flows/ingest, which verifies and commits them through the same
  * core the in-app assistant's submit_code uses, and activates the version.
  *
  * It sends `juno.base_version`, so a flow edited elsewhere since this copy was
  * pulled is a 409 (exit 4) rather than a silent overwrite; --force sends none
  * and replaces whatever is active. On success it writes back what the server
- * now holds: the canonical manifest, both .d.ts files, and the new
- * base_version.
+ * now holds: the canonical manifest, both files under types/, and the new
+ * base_version. --watch redeploys on every save to src/ or manifest.json.
  */
 export async function flowDeploy(argv, io) {
   const { target, client } = await connect(argv, io);
@@ -45,13 +45,16 @@ export async function flowDeploy(argv, io) {
   return deployOnChange({
     io,
     target,
-    paths: [{ path: join(io.cwd, FLOW_TS) }, { path: join(io.cwd, MANIFEST) }],
+    paths: [
+      { path: join(io.cwd, SRC_DIR), recursive: true },
+      { path: join(io.cwd, MANIFEST) },
+    ],
     once: async () => {
       const project = await readFlowProject(io.cwd);
-      const key = JSON.stringify([project.manifestRaw, project.flowTS]);
+      const key = JSON.stringify([project.manifestRaw, project.files]);
       if (key === last) return;
       const after = await deployProject(client, project, argv, io, target);
-      last = JSON.stringify([after.manifestRaw, project.flowTS]);
+      last = JSON.stringify([after.manifestRaw, project.files]);
     },
   });
 }
@@ -73,7 +76,7 @@ async function deployProject(client, project, argv, io, target) {
   const result = await client.ingestFlow({
     flowId: project.flowId,
     manifest: project.manifest,
-    flowTS: project.flowTS,
+    files: project.files,
     baseVersion: argv.force ? undefined : project.baseVersion,
   });
 

package/src/commands/flow-fixture.js

@@ -0,0 +1,67 @@
+import { mkdir, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+
+import { connect } from '../api.js';
+import { UsageError, UserError } from '../errors.js';
+import { readFlowPackage } from '../flow-project.js';
+import { baseVersionOf } from '../working-copy.js';
+import { exists } from './init.js';
+
+export const FLOW_FIXTURE_USAGE = 'juno flow fixture --run <seq> [--force]';
+
+export const FIXTURES_DIR = 'test/fixtures';
+
+/**
+ * `juno flow fixture --run <seq>` — write run `seq` of this working copy's
+ * flow as a flowHarness scenario, `test/fixtures/<flow-id>-<seq>.json`, for a
+ * test to replay with `h.scenario(fixture)`.
+ *
+ * The server builds the fixture (GET /api/flows/{id}/runs/{seq}/fixture) and
+ * the CLI writes what it is handed, as `init` does a scaffold. What the run
+ * did not record comes back as notes, one per line on stderr: each is
+ * something the author checks or fills in before the fixture replays.
+ *
+ * The run is a flag, not a positional, because a working-copy command takes
+ * none except `init`. It writes only a local file, so its effect is `read`.
+ */
+export async function flowFixture(argv, io) {
+  const seq = parseSeq(argv.run);
+  const pkg = await readFlowPackage(io.cwd);
+  const flowId = pkg.juno.flow_id;
+
+  const rel = `${FIXTURES_DIR}/${flowId}-${seq}.json`;
+  const path = join(io.cwd, rel);
+  // Refused before anything is fetched: an existing fixture may be one the
+  // author has edited (a credential filled in, a state corrected).
+  if (!argv.force && (await exists(path))) {
+    throw new UserError(`${rel} already exists; pass --force to overwrite it`);
+  }
+
+  const { client } = await connect(argv, io);
+  const { fixture, notes } = await client.runFixture(flowId, seq);
+
+  await mkdir(join(io.cwd, FIXTURES_DIR), { recursive: true });
+  await writeFile(path, `${JSON.stringify(fixture, null, 2)}\n`, 'utf8');
+
+  io.log(`wrote ${rel}`);
+  const base = baseVersionOf(pkg);
+  if (
+    base !== undefined &&
+    Number.isInteger(fixture?.flow_version) &&
+    fixture.flow_version !== base
+  ) {
+    io.warn(
+      `run ${seq} ran v${fixture.flow_version}; this working copy is at v${base} — the fixture may not replay`
+    );
+  }
+  for (const note of notes ?? []) io.warn(`note: ${note}`);
+  return 0;
+}
+
+/** parseSeq is `--run`'s value as a run number, or a usage error. */
+function parseSeq(value) {
+  if (value === undefined || !/^[1-9][0-9]*$/.test(value)) {
+    throw new UsageError(`usage: ${FLOW_FIXTURE_USAGE}`);
+  }
+  return Number(value);
+}

package/src/commands/flow-gen-types.js

@@ -1,4 +1,5 @@
 import { connect } from '../api.js';
+import { UserError } from '../errors.js';
 import {
   readFlowManifest,
   readFlowPackage,
@@ -9,17 +10,23 @@ import {
 export const FLOW_GEN_TYPES_USAGE = 'juno flow gen-types';
 
 /**
- * `juno flow gen-types` — regenerate flow-env.d.ts and flow-api.d.ts from
- * manifest.json against the instance's live catalog. manifest.json itself is
- * left alone: this refreshes what the editor type-checks against, nothing
- * more. Stale types cannot ship regardless, because ingest regenerates them.
+ * `juno flow gen-types` — regenerate types/flow-env.d.ts and
+ * types/flow-api.d.ts from manifest.json against the instance's live catalog.
+ * manifest.json itself is left alone: this refreshes what the editor
+ * type-checks against, nothing more. Stale types cannot ship regardless,
+ * because ingest regenerates them.
  */
 export async function flowGenTypes(argv, io) {
   await readFlowPackage(io.cwd);
   const { manifest } = await readFlowManifest(io.cwd);
   const { client } = await connect(argv, io);
   const generated = await client.typegenFlow(manifest);
-  const files = typeFiles(generated?.types);
+  const files = typeFiles(generated.types);
+  if (!Object.keys(files).length) {
+    throw new UserError(
+      `${client.target} answered no .d.ts files for this manifest`
+    );
+  }
   const written = await writeFlowFiles(io.cwd, files);
   io.log(
     written.length

package/src/commands/flow-pull.js

@@ -1,46 +1,50 @@
 import { connect } from '../api.js';
 import { UserError } from '../errors.js';
 import {
-  FLOW_TS,
   MANIFEST,
+  manifestText,
   PACKAGE_JSON,
   readFlowPackage,
   updatePackageJSON,
   writeFlowFiles,
 } from '../flow-project.js';
 import { printScaffoldWarnings } from './flow-init.js';
-import { dirtyPaths } from './pull.js';
+import {
+  baseArtifactPaths,
+  baseVersionOf,
+  pullArtifacts,
+  requireCleanTree,
+  setDependencies,
+} from '../working-copy.js';
 
 export const FLOW_PULL_USAGE = 'juno flow pull [--force]';
 
 /**
- * `juno flow pull` — overwrite the working copy with the flow's active
- * version: manifest.json, flow.ts and both .d.ts files, plus package.json's
- * `scripts`, `dependencies` and `juno.base_version` — every other key in
- * package.json is the author's and stays. Everything comes from
- * POST /api/flows/scaffold, the same render `init` writes, so a pulled copy
- * and a fresh one cannot differ.
+ * `juno flow pull` — make the working copy's artifact files the flow's active
+ * version: manifest.json and every file under src/ and test/, exactly as the
+ * version stores them (GET /api/flows/{id}/versions/{v}), never as the
+ * scaffold renders them. types/ is generated, so it comes from
+ * POST /api/flows/scaffold, which also names the active version. In
+ * package.json only `dependencies` (the manifest's) and `juno.base_version`
+ * are Juno's; `scripts` and every other key are the author's and stay.
+ *
+ * A local file is deleted only when the base version (`juno.base_version`)
+ * had it and the pulled one does not; a file neither has is one not deployed
+ * yet, and stays. Project files (tsconfig.json, README.md …) are never
+ * written or deleted.
  *
  * It refuses a dirty git tree without --force, as integration pull does: an
  * uncommitted edit is the one thing nothing can get back.
  */
 export async function flowPull(argv, io) {
-  const { juno } = await readFlowPackage(io.cwd);
-  const flowId = juno.flow_id;
+  const pkg = await readFlowPackage(io.cwd);
+  const flowId = pkg.juno.flow_id;
 
-  if (!argv.force) {
-    const dirty = await dirtyPaths(io.cwd);
-    if (dirty === null) {
-      io.warn(
-        `not a git repository — pull will overwrite ${MANIFEST} and ${FLOW_TS} 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 { target, client } = await connect(argv, io);
   const { files, warnings } = await client.scaffoldFlow(flowId, { target });
@@ -53,28 +57,52 @@ export async function flowPull(argv, io) {
     );
   }
   const version = scaffoldPkg.juno?.base_version;
-  // No base_version is the scaffold's stub for a flow with no active
-  // version; writing it over the author's work would lose it for nothing.
-  if (!Number.isInteger(version)) {
-    throw new UserError(
+  const noActive = () =>
+    new UserError(
       `${flowId} has no active version on ${target} — nothing to pull`
     );
-  }
+  // No base_version is the scaffold's stub for a flow with no active
+  // version; writing it over the author's work would lose it for nothing.
+  if (!Number.isInteger(version)) throw noActive();
 
-  const written = await writeFlowFiles(
-    io.cwd,
-    Object.fromEntries(
-      Object.entries(files).filter(
-        ([name]) =>
-          name === MANIFEST || name === FLOW_TS || name.endsWith('.d.ts')
+  // Everything is fetched before anything is written, so a failure leaves
+  // the working copy as it was.
+  const detail = await client.getFlowVersion(flowId, version);
+  if (!detail) throw noActive();
+  const manifest = JSON.parse(detail.manifest_json);
+  const stored = {
+    [MANIFEST]: manifestText(manifest),
+    ...detail.source_files,
+  };
+  const base = await baseArtifactPaths({
+    base: baseVersionOf(pkg),
+    version,
+    stored,
+    read: async (v) => {
+      const b = await client.getFlowVersion(flowId, v);
+      return b ? [MANIFEST, ...Object.keys(b.source_files ?? {})] : null;
+    },
+    id: flowId,
+    target,
+    io,
+  });
+
+  const { written, removed } = await pullArtifacts(io.cwd, {
+    stored,
+    base,
+    kind: 'flow',
+  });
+  written.push(
+    ...(await writeFlowFiles(
+      io.cwd,
+      Object.fromEntries(
+        Object.entries(files).filter(([name]) => name.startsWith('types/'))
       )
-    )
+    ))
   );
-  await updatePackageJSON(io.cwd, (pkg) => {
-    pkg.scripts = scaffoldPkg.scripts;
-    if (scaffoldPkg.dependencies) pkg.dependencies = scaffoldPkg.dependencies;
-    else delete pkg.dependencies;
-    pkg.juno.base_version = version;
+  await updatePackageJSON(io.cwd, (p) => {
+    setDependencies(p, manifest);
+    p.juno.base_version = version;
   });
   written.push(PACKAGE_JSON);
   printScaffoldWarnings(warnings, io);
@@ -82,5 +110,6 @@ export async function flowPull(argv, io) {
   io.log(
     `pulled ${flowId} v${version} from ${target} (${written.sort().join(', ')})`
   );
+  if (removed.length) io.log(`removed ${removed.join(', ')}`);
   return 0;
 }