@junoflow/cli 0.1.5 → 0.6.0

package/src/commands/tool.js

@@ -0,0 +1,249 @@
+import { spawn } from 'node:child_process';
+import { readFile } from 'node:fs/promises';
+import { basename, resolve } from 'node:path';
+import { isDeepStrictEqual } from 'node:util';
+
+import { connect } from '../api.js';
+import { UsageError, UserError } from '../errors.js';
+import { EXIT_FAILURE, EXIT_OK } from '../exit.js';
+
+/**
+ * runTool runs one tool row of verbs.json: build the tool's input from the
+ * command line, POST it to the gateway, print the answer. It holds no tool
+ * semantics — the gateway validates the input against the tool's schema and
+ * answers 422 naming the field — so nothing here knows what any field means
+ * beyond which one the positional fills.
+ */
+export async function runTool(row, args, io) {
+  const input = await buildInput(row, args, io);
+
+  const { client } = await connect(args, io);
+  const { result, text } = await client.callTool(row.tool, input);
+
+  if (args.jq !== undefined) {
+    io.log(await runJq(args.jq, text, io));
+  } else {
+    io.log(io.isTTY ? JSON.stringify(result, null, 2) : text.trimEnd());
+  }
+  // A tool reports a domain failure as a 200 with a top-level string error:
+  // it is printed like any result, and only the exit code says it failed.
+  return typeof result?.error === 'string' ? EXIT_FAILURE : EXIT_OK;
+}
+
+/**
+ * buildInput merges in Decision 8's order: the --input object, then the
+ * positional into its field, then the row's flags, then fixed_input. A later
+ * source may fill a field but never silently overwrite one: a disagreement is
+ * a usage error naming both, because either could be the one the person meant.
+ */
+async function buildInput(row, args, io) {
+  const input = await readInput(args.input, io);
+  const positionals = args._;
+
+  // `<kind> <id>` is what discover's {kind, id} reads as, so a kind:id row
+  // takes it as two words as well as one.
+  if (row.positional === 'kind:id' && positionals.length === 2) {
+    put(input, 'kind', positionals[0], 'the positional argument');
+    put(input, 'id', positionals[1], 'the positional argument');
+    return finishInput(row, args, input);
+  }
+  if (positionals.length > 1) {
+    throw new UsageError(
+      `juno ${row.command} takes at most one positional argument, got ${positionals.length}: ${positionals.join(' ')}`
+    );
+  }
+  const [positional] = positionals;
+  if (positional !== undefined) {
+    if (row.id_field) {
+      put(input, row.id_field, positional, 'the positional argument');
+    } else if (row.positional === 'kind:id') {
+      putKindID(input, positional);
+    } else if (row.positional === 'file') {
+      await putFile(input, positional, io);
+    } else {
+      throw new UsageError(
+        `juno ${row.command} takes no positional argument; pass its input with --input`
+      );
+    }
+  }
+  return finishInput(row, args, input);
+}
+
+/** finishInput adds the row's flags, then its fixed_input. */
+function finishInput(row, args, input) {
+  for (const [flag, spec] of Object.entries(row.flags ?? {})) {
+    if (args[flag] === undefined) continue;
+    const values = spec.multiple ? args[flag] : [args[flag]];
+    const typed = values.map((v) => flagValue(flag, spec, v));
+    put(input, spec.field, spec.multiple ? typed : typed[0], `--${flag}`);
+  }
+
+  for (const [field, value] of Object.entries(row.fixed_input ?? {})) {
+    if (
+      Object.hasOwn(input, field) &&
+      !isDeepStrictEqual(input[field], value)
+    ) {
+      throw new UsageError(
+        `juno ${row.command} always sends ${JSON.stringify(field)}: ${JSON.stringify(value)}, ` +
+          `but --input has ${JSON.stringify(input[field])}`
+      );
+    }
+    input[field] = value;
+  }
+  return input;
+}
+
+/** put sets input[field] unless --input already holds a different value. */
+function put(input, field, value, source) {
+  if (Object.hasOwn(input, field) && !isDeepStrictEqual(input[field], value)) {
+    throw new UsageError(
+      `--input has ${JSON.stringify(field)}: ${JSON.stringify(input[field])}, ` +
+        `but ${source} says ${JSON.stringify(value)}; give it once`
+    );
+  }
+  input[field] = value;
+}
+
+/**
+ * putKindID splits `<kind>:<id>` on the first colon only: an endpoint id such
+ * as `ha:light.hallway` or `mqtt:zigbee2mqtt/porch/set` carries its own. An
+ * endpoint id on its own is an endpoint — `ha:` and `mqtt:` are what the tool
+ * calls the address, so `juno related ha:light.hallway` means what it says.
+ */
+function putKindID(input, arg) {
+  const colon = arg.indexOf(':');
+  if (colon <= 0 || colon === arg.length - 1) {
+    throw new UsageError(
+      `expected <kind>:<id> or <kind> <id>, e.g. state:porch-dark or ha:light.hallway; got "${arg}"`
+    );
+  }
+  const kind = arg.slice(0, colon);
+  if (ENDPOINT_SCHEMES.has(kind)) {
+    put(input, 'kind', 'endpoint', `the positional argument`);
+    put(input, 'id', arg, `the positional argument`);
+    return;
+  }
+  put(input, 'kind', kind, `the positional argument`);
+  put(input, 'id', arg.slice(colon + 1), `the positional argument`);
+}
+
+/** ENDPOINT_SCHEMES are the prefixes of an endpoint id, as get_related spells it. */
+const ENDPOINT_SCHEMES = new Set(['ha', 'mqtt']);
+
+/**
+ * putFile reads a script into `files` under its basename and makes it the
+ * `entry`. Other files from --input ride along; one with the same name is a
+ * usage error rather than silently replaced.
+ */
+async function putFile(input, arg, io) {
+  const path = resolve(io.cwd, arg);
+  let content;
+  try {
+    content = await readFile(path, 'utf8');
+  } catch (err) {
+    throw new UsageError(`cannot read ${path}: ${err.message}`);
+  }
+  const name = basename(path);
+  const files = input.files ?? {};
+  if (files === null || typeof files !== 'object' || Array.isArray(files)) {
+    throw new UsageError('--input has "files" that is not an object');
+  }
+  if (Object.hasOwn(files, name)) {
+    throw new UsageError(
+      `--input already has a file named "${name}" under "files", and so does the positional ${arg}; give it once`
+    );
+  }
+  input.files = { ...files, [name]: content };
+  put(input, 'entry', name, `the positional argument ${arg}`);
+}
+
+/** flagValue types one flag value as verbs.json declares it. */
+function flagValue(flag, spec, value) {
+  if (spec.type !== 'integer') return value;
+  if (!/^-?\d+$/.test(value)) {
+    throw new UsageError(`--${flag} takes an integer, got "${value}"`);
+  }
+  return Number(value);
+}
+
+/**
+ * readInput parses --input: `-` is stdin, `@path` a file relative to the
+ * working directory, anything else the JSON itself. Stdin is read only when
+ * asked for — an open, empty stdin would hang an agent — and an absent
+ * --input is `{}`.
+ */
+async function readInput(spec, io) {
+  if (spec === undefined) return {};
+
+  let source;
+  let raw;
+  if (spec === '-') {
+    source = 'stdin (--input -)';
+    raw = await io.readStdin();
+  } else if (spec.startsWith('@')) {
+    const path = resolve(io.cwd, spec.slice(1));
+    source = `--input ${spec}`;
+    try {
+      raw = await readFile(path, 'utf8');
+    } catch (err) {
+      throw new UsageError(`cannot read ${path} (${source}): ${err.message}`);
+    }
+  } else {
+    source = '--input';
+    raw = spec;
+  }
+
+  let value;
+  try {
+    value = JSON.parse(raw);
+  } catch (err) {
+    throw new UsageError(`${source} is not JSON: ${err.message}`);
+  }
+  if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+    throw new UsageError(`${source} must be a JSON object`);
+  }
+  return value;
+}
+
+/**
+ * runJq pipes the result through the jq on PATH. It is a subprocess, not a
+ * library: `--jq` exists so a filter stays inside the `juno <kind> <verb>`
+ * permission rule, and the CLI takes on no jq implementation of its own.
+ */
+function runJq(expr, text, io) {
+  const argv = io.isTTY ? [expr] : ['-c', expr];
+  return new Promise((resolvePromise, reject) => {
+    let child;
+    try {
+      child = spawn('jq', argv, {
+        env: io.env,
+        stdio: ['pipe', 'pipe', 'pipe'],
+      });
+    } catch (err) {
+      reject(jqSpawnError(err));
+      return;
+    }
+    const out = [];
+    const err = [];
+    child.stdout.on('data', (c) => out.push(c));
+    child.stderr.on('data', (c) => err.push(c));
+    child.on('error', (e) => reject(jqSpawnError(e)));
+    child.on('close', (code) => {
+      if (code === 0) {
+        resolvePromise(Buffer.concat(out).toString('utf8').replace(/\n$/, ''));
+        return;
+      }
+      const stderr = Buffer.concat(err).toString('utf8').trim();
+      reject(new UsageError(stderr || `jq exited ${code}`));
+    });
+    // jq may exit before reading everything (a bad expression); the EPIPE
+    // that follows is not the failure worth reporting.
+    child.stdin.on('error', () => {});
+    child.stdin.end(text);
+  });
+}
+
+function jqSpawnError(err) {
+  if (err.code === 'ENOENT') return new UsageError('jq is not installed');
+  return new UserError(`cannot run jq: ${err.message}`);
+}

package/src/commands/verify-types.js

@@ -5,8 +5,10 @@ import { UserError } from '../errors.js';
 import { readManifestRaw } from '../project.js';
 import { ENV_DTS, manifestStamp, readStamp } from '../stamp.js';
 
+export const VERIFY_TYPES_USAGE = 'juno integration verify-types';
+
 /**
- * `juno verify-types` — does types/ still describe manifest.json?
+ * `juno integration verify-types` — does types/ still describe manifest.json?
  *
  * The one check in this CLI that talks to nothing. It is the counterweight to
  * committing types/: that decision is what lets a drive-by contributor work
@@ -16,7 +18,7 @@ import { ENV_DTS, manifestStamp, readStamp } from '../stamp.js';
  * rather than noticing they are stale, and h.conformance() compares the
  * manifest with the module, never with types/.
  *
- * So this runs first in `npm test` and inside `juno check`. A failure here is
+ * So this runs first in `npm test` and inside `juno integration check`. A failure here is
  * always the same one sentence of advice, which is why the message says it
  * rather than describing the mismatch.
  */

package/src/config.js

@@ -0,0 +1,34 @@
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+
+/**
+ * The user config file: `$XDG_CONFIG_HOME/juno/config.json`, or
+ * `~/.config/juno/config.json` when XDG_CONFIG_HOME is unset. It holds
+ * `{"url": "…"}`, the last place resolveTarget looks, and is what makes `juno`
+ * usable outside a project after a global install.
+ */
+export function configPath(env = process.env) {
+  const base = env.XDG_CONFIG_HOME || join(env.HOME || homedir(), '.config');
+  return join(base, 'juno', 'config.json');
+}
+
+/** The parsed config; a missing or unreadable file is `{}`. */
+export async function readUserConfig(env = process.env) {
+  try {
+    const parsed = JSON.parse(await readFile(configPath(env), 'utf8'));
+    return parsed && typeof parsed === 'object' && !Array.isArray(parsed)
+      ? parsed
+      : {};
+  } catch {
+    return {};
+  }
+}
+
+/** Writes the whole config, creating its directory. */
+export async function writeUserConfig(env = process.env, cfg) {
+  const path = configPath(env);
+  await mkdir(dirname(path), { recursive: true });
+  await writeFile(path, `${JSON.stringify(cfg, null, 2)}\n`, 'utf8');
+  return path;
+}

package/src/diagnostics.js

@@ -14,3 +14,17 @@ export function formatDiagnostic(d) {
 export function formatDiagnostics(diagnostics) {
   return diagnostics.map(formatDiagnostic).join('\n');
 }
+
+/**
+ * --json on check and deploy (both kinds): the route's body on stdout,
+ * indented only on a TTY, for CI.
+ */
+export function printJSON(body, io) {
+  io.log(io.isTTY ? JSON.stringify(body, null, 2) : JSON.stringify(body));
+}
+
+/** --json on a failed verify: the 422's detail and diagnostics, exit 1. */
+export function printDiagnosticsJSON(err, io) {
+  printJSON({ detail: err.message, diagnostics: err.diagnostics }, io);
+  return 1;
+}

package/src/errors.js

@@ -24,3 +24,43 @@ export class DiagnosticsError extends Error {
     this.diagnostics = diagnostics ?? [];
   }
 }
+
+/**
+ * UsageError is a command line the CLI cannot act on: an unknown command or
+ * flag, a missing argument, a malformed --input. The top-level handler prints
+ * its message and exits 2. The fix is to change the command line — the message
+ * should say how, rather than restating the whole help.
+ */
+export class UsageError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'UsageError';
+  }
+}
+
+/**
+ * UnreachableError means the request never got an answer: the fetch itself
+ * failed (connection refused, DNS, TLS). The top-level handler exits 3. The
+ * fix is on the network side — is the instance running, and is --url (or
+ * $JUNO_URL, package.json, the user config) pointing at it?
+ */
+export class UnreachableError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'UnreachableError';
+  }
+}
+
+/**
+ * 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,
+ * which names both versions, and exits 4. The fix is `npm run pull`, or
+ * deploying with --force to replace whatever is active.
+ */
+export class ConflictError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'ConflictError';
+  }
+}

package/src/exit.js

@@ -0,0 +1,22 @@
+/**
+ * Exit codes, one table for the whole CLI (plan-external-agents-cli.md,
+ * Decision 11):
+ *
+ *   0  success
+ *   1  a tool result with a top-level string `error`; any other failure
+ *      (a UserError, diagnostics, a 5xx)
+ *   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)
+ *   5  `juno ask` / `session approve`: the turn is still running (pending)
+ *   6  `juno ask` / `session approve`: the assistant is awaiting input
+ */
+export const EXIT_OK = 0;
+export const EXIT_FAILURE = 1;
+export const EXIT_USAGE = 2;
+export const EXIT_UNREACHABLE = 3;
+export const EXIT_CONFLICT = 4;
+export const EXIT_PENDING = 5;
+export const EXIT_AWAITING_INPUT = 6;

package/src/flow-project.js

@@ -0,0 +1,128 @@
+import { readFile, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+
+import { UserError } from './errors.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.
+ */
+export const MANIFEST = 'manifest.json';
+export const FLOW_TS = 'flow.ts';
+export const PACKAGE_JSON = 'package.json';
+
+/**
+ * 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.
+ */
+export async function readFlowProject(cwd) {
+  const pkg = await readFlowPackage(cwd);
+  return {
+    ...(await readFlowManifest(cwd)),
+    flowTS: await readText(cwd, FLOW_TS),
+    packageJSON: pkg,
+    flowId: pkg.juno.flow_id,
+    baseVersion: Number.isInteger(pkg.juno.base_version)
+      ? pkg.juno.base_version
+      : undefined,
+  };
+}
+
+/** 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}`);
+  }
+}
+
+/**
+ * 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;
+}
+
+/**
+ * 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.
+ */
+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'
+  );
+}
+
+/**
+ * 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.
+ */
+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}`);
+  }
+}