@junoflow/cli 0.6.0 → 0.10.0

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';
@@ -55,7 +62,11 @@ import {
 import { closest, closestByVerb, levenshtein } from './suggest.js';
 import { groupOf, normalizeVerb, rowFor, rows } from './verbs.js';
 
-const URL_OPTION = { url: { type: 'string' } };
+/**
+ * The two flags every command that reaches an instance takes, and the two a
+ * leading position accepts (`juno --url <u> --token <k> state get x`).
+ */
+const URL_OPTION = { url: { type: 'string' }, token: { type: 'string' } };
 
 /**
  * The verbs.json rows that call no tool, by command. A row is dispatchable
@@ -151,6 +162,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 +209,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 +223,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 +288,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>]
@@ -239,6 +304,8 @@ ${workingCopyListing(DISPATCHABLE, handlerFor)}
 
 --url <url> picks the instance; else $JUNO_URL, package.json juno.target,
 then the user config (juno config set url <url>).
+--token <key> is the API key to send; else $JUNO_TOKEN, then the user config
+(juno config set token <key>). Create one under Settings → API keys.
 `;
 
 /**
@@ -281,11 +348,11 @@ export async function run(argv, io = defaultIO()) {
 /**
  * dispatch is two-level: the first word is a top-level row (`discover`) or a
  * group, and a group's second word is the verb. A
- * leading `--url` is accepted before the first word, so
+ * leading `--url` or `--token` is accepted before the first word, so
  * `juno --url <u> state get x` reads the way an alias would write it.
  */
 async function dispatch(argv, io) {
-  const { url, rest } = leadingURL(argv);
+  const { leading, rest } = leadingFlags(argv);
   const [first, ...tail] = rest;
 
   if (!first || first === '--help' || first === '-h' || first === 'help') {
@@ -294,7 +361,7 @@ async function dispatch(argv, io) {
   }
 
   const top = dispatchable(first);
-  if (top) return runRow(top, tail, url, io);
+  if (top) return runRow(top, tail, leading, io);
 
   if (GROUPS.has(first)) {
     const [verb, ...args] = tail;
@@ -304,7 +371,7 @@ async function dispatch(argv, io) {
       return runCommand(
         { options: URL_OPTION },
         tail,
-        url,
+        leading,
         io,
         (parsed) => showGroupHelp(first, parsed, io, EXIT_OK),
         (parsed) => showGroupHelp(first, parsed, io, EXIT_USAGE)
@@ -316,7 +383,7 @@ async function dispatch(argv, io) {
         `${first} ${normalizeVerb(verb)}`,
       ]);
     }
-    return runRow(row, args, url, io);
+    return runRow(row, args, leading, io);
   }
 
   const second = tail[0] && !tail[0].startsWith('-') ? tail[0] : null;
@@ -335,7 +402,7 @@ async function showGroupHelp(group, args, io, code) {
 }
 
 /** runRow runs one verbs.json row, a tool's or a non-tool command's. */
-function runRow(row, argv, url, io) {
+function runRow(row, argv, leading, io) {
   if (!row.tool) {
     const handler = handlerFor(row);
     const run =
@@ -348,7 +415,7 @@ function runRow(row, argv, url, io) {
     return runCommand(
       handler,
       argv,
-      url,
+      leading,
       io,
       () => {
         io.log(nonToolHelp(row, handler));
@@ -369,7 +436,7 @@ function runRow(row, argv, url, io) {
   return runCommand(
     { run: (args) => runTool(row, args, io), options },
     argv,
-    url,
+    leading,
     io,
     async (args) => {
       io.log(await verbHelp(row, args, io));
@@ -381,10 +448,10 @@ function runRow(row, argv, url, io) {
 /**
  * runCommand parses a command's own flags (plus --help) and runs it, or its
  * help. A `--url` given before the command word fills in when the command's
- * own is absent. `run` defaults to the command's own; a group without a verb
+ * own is absent, and likewise `--token`. `run` defaults to the command's own; a group without a verb
  * passes its help instead.
  */
-async function runCommand(command, argv, url, io, help, run = command.run) {
+async function runCommand(command, argv, leading, io, help, run = command.run) {
   let parsed;
   try {
     parsed = parseArgs({
@@ -400,7 +467,9 @@ async function runCommand(command, argv, url, io, help, run = command.run) {
   }
 
   const args = { ...parsed.values, _: parsed.positionals, client: io.client };
-  if (url !== undefined && args.url === undefined) args.url = url;
+  for (const [flag, value] of Object.entries(leading)) {
+    if (value !== undefined && args[flag] === undefined) args[flag] = value;
+  }
   if (parsed.values.help) return help(args);
   return (await run(args, io)) ?? EXIT_OK;
 }
@@ -422,22 +491,29 @@ function refusePositional(row, args) {
   );
 }
 
-/** leadingURL takes `--url <u>` / `--url=<u>` off the front of argv. */
-function leadingURL(argv) {
-  let url;
+/**
+ * leadingFlags takes `--url <u>` / `--url=<u>` and `--token <k>` /
+ * `--token=<k>` off the front of argv, in either order.
+ */
+function leadingFlags(argv) {
+  const leading = {};
   let i = 0;
   while (i < argv.length) {
-    if (argv[i] === '--url' && i + 1 < argv.length) {
-      url = argv[i + 1];
+    const flag = ['url', 'token'].find(
+      (name) =>
+        (argv[i] === `--${name}` && i + 1 < argv.length) ||
+        argv[i].startsWith(`--${name}=`)
+    );
+    if (!flag) break;
+    if (argv[i] === `--${flag}`) {
+      leading[flag] = argv[i + 1];
       i += 2;
-    } else if (argv[i].startsWith('--url=')) {
-      url = argv[i].slice('--url='.length);
-      i += 1;
     } else {
-      break;
+      leading[flag] = argv[i].slice(`--${flag}=`.length);
+      i += 1;
     }
   }
-  return { url, rest: argv.slice(i) };
+  return { leading, rest: argv.slice(i) };
 }
 
 /**

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);

package/src/token.js

@@ -0,0 +1,30 @@
+import { readUserConfig } from './config.js';
+
+/**
+ * Resolve the API key to send as `Authorization: Bearer`, in precedence
+ * order: an explicit --token, then $JUNO_TOKEN, then `token` in the user
+ * config file `juno config set token` writes. It is the order resolveTarget
+ * follows for the URL, minus package.json: a working copy's package.json is
+ * committed, and a secret never goes in a file that is.
+ *
+ * Returns undefined when there is none: a request goes out unauthenticated,
+ * which is right for an instance behind a proxy that identifies the person,
+ * or one started with --no-auth. A blank value counts as unset, so an empty
+ * $JUNO_TOKEN does not shadow the config file.
+ *
+ * The token is a secret. Nothing in this CLI prints it, in an error message
+ * included.
+ */
+export async function resolveToken({ token, env = process.env } = {}) {
+  return (
+    clean(token) ??
+    clean(env.JUNO_TOKEN) ??
+    clean((await readUserConfig(env)).token)
+  );
+}
+
+function clean(value) {
+  if (typeof value !== 'string') return undefined;
+  const trimmed = value.trim();
+  return trimmed === '' ? undefined : trimmed;
+}

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;
+    },
+  };
 }