@junoflow/cli 0.6.0 → 0.9.0

package/src/watch.js

@@ -28,23 +28,60 @@ export async function deployOnChange({ io, target, paths, once }) {
   };
   await iteration();
 
+  const watcher = watchPaths(paths, () => void iteration());
+  await new Promise((resolve) => {
+    process.once('SIGINT', () => {
+      watcher.close();
+      resolve();
+    });
+  });
+  return 0;
+}
+
+/**
+ * watchPaths calls onChange once edits to `paths` (`{path, recursive?,
+ * filter?}`) have settled for `debounceMs`, so an editor's save-and-rename is
+ * one call. `filter(filename)`, when given, drops an event its path does not
+ * want — the way to watch one file in a directory, since a watch on the file
+ * itself loses it the first time an editor saves by renaming over it. A path
+ * that does not exist is not watched: an app's public/ may be absent, since
+ * nothing but the page is required. Returns `{close()}`, which also drops a
+ * pending call.
+ */
+export function watchPaths(
+  paths,
+  onChange,
+  { debounceMs = WATCH_DEBOUNCE_MS } = {}
+) {
   let timer = null;
   const schedule = () => {
     if (timer) clearTimeout(timer);
     timer = setTimeout(() => {
       timer = null;
-      void iteration();
-    }, WATCH_DEBOUNCE_MS);
+      onChange();
+    }, debounceMs);
   };
 
-  const watchers = paths.map(({ path, recursive = false }) =>
-    watch(path, { recursive }, schedule)
-  );
-  await new Promise((resolve) => {
-    process.once('SIGINT', () => {
+  const watchers = [];
+  for (const { path, recursive = false, filter } of paths) {
+    try {
+      const w = watch(path, { recursive }, (_event, filename) => {
+        if (!filter || filter(filename == null ? null : String(filename))) {
+          schedule();
+        }
+      });
+      // A watched directory removed mid-session is not worth a crash.
+      w.on('error', () => w.close());
+      watchers.push(w);
+    } catch (err) {
+      if (err.code !== 'ENOENT') throw err;
+    }
+  }
+  return {
+    close() {
+      if (timer) clearTimeout(timer);
+      timer = null;
       for (const w of watchers) w.close();
-      resolve();
-    });
-  });
-  return 0;
+    },
+  };
 }

package/src/working-copy.js

@@ -0,0 +1,262 @@
+import { execFile } from 'node:child_process';
+import { mkdir, readFile, rm, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { promisify } from 'node:util';
+
+import { safeRelative } from './commands/init.js';
+import { UserError } from './errors.js';
+
+const execFileAsync = promisify(execFile);
+
+/**
+ * What every working copy bound by package.json's `juno` block shares — a
+ * flow's (flow-project.js) and an app's (app-project.js): reading the
+ * manifest and the binding, writing back what a route answered, and the
+ * clean-tree check before a pull. Pulling itself (pullArtifacts) is shared
+ * with an integration's working copy too. The layout is the server's
+ * (POST /api/{flows,apps}/scaffold); this module knows only the names a
+ * command reads or writes back, and which of them are artifact files.
+ */
+export const MANIFEST = 'manifest.json';
+export const PACKAGE_JSON = 'package.json';
+
+/**
+ * page/tsconfig.json is a project file, not part of the page: the scaffold
+ * writes it, deploy never sends it (ingest would refuse it), and pull never
+ * writes or removes it.
+ */
+export const PAGE_TSCONFIG = 'page/tsconfig.json';
+
+/**
+ * The directories whose files a version stores, per kind, beside
+ * manifest.json. Everything else in a working copy is generated (types/) or
+ * a project file (tsconfig.json, README.md, package.json …) that no pull
+ * writes or deletes.
+ */
+const ARTIFACT_DIRS = {
+  flow: ['src/', 'test/'],
+  integration: ['src/', 'test/'],
+  app: ['src/', 'test/', 'page/', 'public/'],
+};
+
+/** isArtifactPath reports whether a `kind` version stores the file at path. */
+export function isArtifactPath(kind, path) {
+  if (path === MANIFEST) return true;
+  if (path === PAGE_TSCONFIG) return false;
+  return ARTIFACT_DIRS[kind].some((dir) => path.startsWith(dir));
+}
+
+/**
+ * pullArtifacts makes a working copy's artifact files the pulled version's.
+ * `stored` is that version's artifact files, path → content, as the version
+ * stores them and never as a scaffold renders them (a scaffold adds init-only
+ * files). Each one whose content differs is written.
+ *
+ * `base` is the artifact paths of the version the copy was pulled from or last
+ * deployed (`juno.base_version`), or null. A file is deleted only when the base
+ * had it and the pulled version does not: that is a file deleted in Juno. A
+ * file neither version has is one the author has not deployed yet, and stays.
+ * With no base, nothing is deleted. Returns `{written, removed}`, each sorted.
+ */
+export async function pullArtifacts(cwd, { stored, base, kind }) {
+  const written = await writeChangedFiles(cwd, stored);
+  const removed = [];
+  for (const path of base ?? []) {
+    if (Object.hasOwn(stored, path) || !isArtifactPath(kind, path)) continue;
+    try {
+      await rm(join(cwd, safeRelative(path)));
+    } catch (err) {
+      if (err.code === 'ENOENT') continue; // already gone locally
+      throw err;
+    }
+    removed.push(path);
+  }
+  return { written, removed: removed.sort() };
+}
+
+/**
+ * baseArtifactPaths is pullArtifacts' `base`: null when the copy records no
+ * base, the pulled version's own paths when the base is that version, and
+ * otherwise what `read(base)` answers — the base version's artifact paths, or
+ * null when the instance no longer has it. Pull then deletes nothing, and says
+ * so on stderr.
+ */
+export async function baseArtifactPaths({
+  base,
+  version,
+  stored,
+  read,
+  id,
+  target,
+  io,
+}) {
+  if (base === undefined) return null;
+  if (base === version) return Object.keys(stored);
+  const paths = await read(base);
+  if (paths === null) {
+    io.warn(
+      `${id} v${base}, this copy's base_version, no longer exists on ${target} — no local file was removed`
+    );
+  }
+  return paths;
+}
+
+/**
+ * setDependencies makes package.json's `dependencies` the manifest's, in name
+ * order as the scaffold writes them, or removes the key when the manifest
+ * declares none. It is the one place pull keeps the two in step.
+ */
+export function setDependencies(pkg, manifest) {
+  const deps = manifest?.dependencies;
+  if (deps && typeof deps === 'object' && Object.keys(deps).length) {
+    pkg.dependencies = Object.fromEntries(
+      Object.keys(deps)
+        .sort()
+        .map((name) => [name, deps[name]])
+    );
+  } else {
+    delete pkg.dependencies;
+  }
+}
+
+/** readManifestFile is manifest.json, as bytes and parsed. */
+export async function readManifestFile(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}`);
+  }
+}
+
+/**
+ * readBoundPackage is package.json, refusing a directory that is not a
+ * `kind` working copy (no string `juno.<idKey>`) — 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 file.
+ */
+export async function readBoundPackage(cwd, { kind, idKey }) {
+  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?.[idKey] !== 'string' || pkg.juno[idKey] === '') {
+    throw new UserError(
+      `${cwd} is not ${article(kind)} ${kind} working copy (no juno.${idKey} in package.json) — ` +
+        `run \`juno ${kind} init <id>\` to make one`
+    );
+  }
+  return pkg;
+}
+
+/** baseVersionOf is `juno.base_version`, or undefined when there is none. */
+export function baseVersionOf(pkg) {
+  return Number.isInteger(pkg.juno.base_version)
+    ? pkg.juno.base_version
+    : undefined;
+}
+
+/**
+ * writePackageJSON writes package.json with a two-space indent and a trailing
+ * newline — the way npm writes it — so, with every key the caller did not
+ * touch left in place, the diff is only what changed.
+ */
+export async function writePackageJSON(cwd, pkg) {
+  await writeFile(
+    join(cwd, PACKAGE_JSON),
+    `${JSON.stringify(pkg, null, 2)}\n`,
+    'utf8'
+  );
+}
+
+/**
+ * writeChangedFiles writes files by working-copy path, creating directories
+ * as needed and skipping a file whose content is already what is on disk, so
+ * a watcher does not see a write that changed nothing. Returns the paths it
+ * wrote, sorted.
+ */
+export async function writeChangedFiles(cwd, files) {
+  const written = [];
+  for (const [rel, content] of Object.entries(files)) {
+    const path = join(cwd, safeRelative(rel));
+    let current = null;
+    try {
+      current = await readFile(path, 'utf8');
+    } catch {
+      // Not there yet.
+    }
+    if (current === content) continue;
+    await mkdir(dirname(path), { recursive: true });
+    await writeFile(path, content, 'utf8');
+    written.push(rel);
+  }
+  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 them keeps a future file working without a CLI release.
+ */
+export function typeFiles(types) {
+  return Object.fromEntries(
+    Object.entries(types ?? {}).filter(([name]) => name.endsWith('.d.ts'))
+  );
+}
+
+/**
+ * requireCleanTree is pull's guard: without --force it refuses a dirty git
+ * tree, because an uncommitted edit is the one thing nothing can get back,
+ * and outside git it warns that `overwrites` has no undo.
+ */
+export async function requireCleanTree(cwd, { force, overwrites, io }) {
+  if (force) return;
+  const dirty = await dirtyPaths(cwd);
+  if (dirty === null) {
+    io.warn(
+      `not a git repository — pull will overwrite ${overwrites} 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.'
+    );
+  }
+}
+
+/**
+ * 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;
+  }
+}
+
+export async function readText(cwd, name) {
+  try {
+    return await readFile(join(cwd, name), 'utf8');
+  } catch {
+    throw new UserError(`no ${name} in ${cwd}`);
+  }
+}
+
+function article(word) {
+  return /^[aeiou]/.test(word) ? 'an' : 'a';
+}

package/tsconfig.page.json

@@ -0,0 +1,15 @@
+{
+  "//": "The compiler options Juno type-checks an app's page/ with server-side: tsconfig.base.json for the browser, with the DOM's types and no @types package. internal/verify's tsconfig_preset_test.go asserts this file and verify.PageCompilerOptions() are identical. Extend it from page/tsconfig.json; do not fork it.",
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "noEmit": true,
+    "esModuleInterop": true,
+    "resolveJsonModule": true,
+    "skipLibCheck": true,
+    "lib": ["ES2022", "DOM", "DOM.Iterable"],
+    "types": []
+  }
+}

package/verbs.json

@@ -76,7 +76,7 @@
       "command": "flow gen-types",
       "effect": "read",
       "working_copy": true,
-      "summary": "Regenerate flow-env.d.ts and flow-api.d.ts from manifest.json"
+      "summary": "Regenerate types/ from manifest.json"
     },
     {
       "command": "flow check",
@@ -96,6 +96,12 @@
       "working_copy": true,
       "summary": "Overwrite the working copy with the flow's active version"
     },
+    {
+      "command": "flow fixture",
+      "effect": "read",
+      "working_copy": true,
+      "summary": "Write a test fixture from a recorded run"
+    },
     { "command": "run list", "tool": "list_runs" },
     { "command": "run get", "tool": "get_run", "id_field": "run_id" },
     {
@@ -148,7 +154,7 @@
       "command": "integration pull",
       "effect": "read",
       "working_copy": true,
-      "summary": "Overwrite manifest.json, src/ and package.json scripts with the active version"
+      "summary": "Overwrite manifest.json, src/, test/ and types/ with the active version"
     },
     { "command": "device list", "tool": "list_devices" },
     { "command": "device get", "tool": "get_device", "id_field": "id" },
@@ -163,6 +169,49 @@
       "tool": "release_control",
       "id_field": "id"
     },
+    { "command": "app get", "tool": "get_app", "id_field": "id" },
+    {
+      "command": "app list-invocations",
+      "tool": "list_app_invocations",
+      "id_field": "id",
+      "flags": { "limit": { "field": "limit", "type": "integer" } }
+    },
+    {
+      "command": "app init",
+      "effect": "read",
+      "working_copy": true,
+      "summary": "Write a working copy of an app (or a stub for a new id) into ./<id>"
+    },
+    {
+      "command": "app gen-types",
+      "effect": "read",
+      "working_copy": true,
+      "summary": "Regenerate types/ from manifest.json"
+    },
+    {
+      "command": "app check",
+      "effect": "change",
+      "working_copy": true,
+      "summary": "Typecheck and lint locally, then store the working copy as a draft and print its preview URL"
+    },
+    {
+      "command": "app deploy",
+      "effect": "change",
+      "working_copy": true,
+      "summary": "Verify, commit and activate the working copy as the app's next version"
+    },
+    {
+      "command": "app pull",
+      "effect": "read",
+      "working_copy": true,
+      "summary": "Overwrite the working copy with the app's active version"
+    },
+    {
+      "command": "app dev",
+      "effect": "local",
+      "working_copy": true,
+      "summary": "Serve this app locally on mocked data"
+    },
     { "command": "finding get", "tool": "get_finding", "id_field": "slug" },
     { "command": "webhook list", "tool": "list_webhooks" },
     {