@junoflow/cli 0.3.0 → 0.9.0

package/src/commands/init.js

@@ -1,33 +1,44 @@
 import { mkdir, writeFile, access } from 'node:fs/promises';
 import { dirname, join, resolve, sep } from 'node:path';
 
-import { JunoClient } from '../api.js';
-import { UserError } from '../errors.js';
+import { clientName, JunoClient } from '../api.js';
+import { printAuthoringIndex } from '../authoring-skills.js';
+import { UsageError, UserError } from '../errors.js';
 import { resolveTarget } from '../target.js';
 
+export const INIT_USAGE = 'juno integration init <id> [--name <name>] [--here]';
+
 /**
- * `juno init [name]` — ask a Juno for a starting project and write it down.
+ * `juno integration init <id>` — a working copy of the install's active
+ * version, or a starting project for an id with none, written into ./<id>
+ * (or the current directory with --here).
  *
  * Every file comes from `POST /api/integrations/scaffold`, which renders it
  * with the same generator behind **Develop locally → Download project**. The
  * CLI holds no copy of the layout: a scaffold and an ejected project cannot
- * drift, and the starter arrives with `types/` already generated, which only
- * the server can produce.
+ * drift, and the project arrives with `types/` already generated, which only
+ * the server can produce. `--name` shapes only a starter. After the next steps
+ * it prints the integration author's skill index.
  */
 export async function init(argv, io) {
-  const name = argv._[0] ?? argv.name;
-  if (!name) throw new UserError('usage: juno init <name>');
+  const [id, ...extra] = argv._;
+  if (!id || extra.length > 0) throw new UsageError(`usage: ${INIT_USAGE}`);
 
-  const dir = resolve(io.cwd, argv.here ? '.' : name);
+  const dir = resolve(io.cwd, argv.here ? '.' : id);
   if (!argv.here && (await exists(dir))) {
     throw new UserError(`${dir} already exists`);
   }
 
-  const target = await resolveTarget({ url: argv.url, cwd: io.cwd });
-  const client = argv.client ?? new JunoClient(target);
-  // The name is validated server-side, against the same rules an install is:
-  // one answer to "is this a valid integration name" rather than two.
-  const files = await client.scaffold(name, { target });
+  const target = await resolveTarget({
+    url: argv.url,
+    cwd: io.cwd,
+    env: io.env,
+  });
+  const client =
+    argv.client ?? new JunoClient(target, { client: clientName(io.env) });
+  // The id is validated server-side, against the same rules an install is:
+  // one answer to "is this a valid integration id" rather than two.
+  const files = await client.scaffold(id, { name: argv.name, target });
 
   for (const [rel, content] of Object.entries(files)) {
     const path = join(dir, safeRelative(rel));
@@ -37,9 +48,10 @@ export async function init(argv, io) {
 
   io.log(`created ${dir}`);
   io.log('');
-  io.log(argv.here ? 'npm install' : `cd ${name} && npm install`);
+  io.log(argv.here ? 'npm install' : `cd ${id} && npm install`);
   io.log('npm test');
   io.log('npm run deploy');
+  await printAuthoringIndex('integration', client, target, io);
   return 0;
 }
 
@@ -48,7 +60,7 @@ export async function init(argv, io) {
  * but "write these paths" is the one place a bad answer escapes the project
  * directory, and checking costs a line.
  */
-function safeRelative(rel) {
+export function safeRelative(rel) {
   const parts = rel.split('/');
   if (rel.startsWith('/') || parts.includes('..') || parts.includes('')) {
     throw new UserError(
@@ -58,7 +70,7 @@ function safeRelative(rel) {
   return parts.join(sep);
 }
 
-async function exists(path) {
+export async function exists(path) {
   try {
     await access(path);
     return true;

package/src/commands/pull.js

@@ -1,89 +1,137 @@
-import { execFile } from 'node:child_process';
-import { mkdir, writeFile } from 'node:fs/promises';
-import { dirname, join } from 'node:path';
-import { promisify } from 'node:util';
-
-import { JunoClient } from '../api.js';
+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';
+import {
+  baseArtifactPaths,
+  MANIFEST,
+  manifestText,
+  pullArtifacts,
+  requireCleanTree,
+  setDependencies,
+  writeChangedFiles,
+} from '../working-copy.js';
+import { pickTypeFiles } from './gen-types.js';
 
-const execFileAsync = promisify(execFile);
+export const PULL_USAGE = 'juno integration pull [--force] [--id <id>]';
 
 /**
- * `juno pull` — write back the manifest and sources Juno holds.
+ * `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
- * two things Juno owns. 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({ url: argv.url, cwd: io.cwd });
-  const name = argv.name ?? (await readManifest(io.cwd)).name;
-  if (!name) {
+  const target = await resolveTarget({
+    url: argv.url,
+    cwd: io.cwd,
+    env: io.env,
+  });
+  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 name — pass --name <integration>'
+      '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 and src/ 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);
-  const detail = await client.getIntegration(name);
+  const client =
+    argv.client ?? new JunoClient(target, { client: clientName(io.env) });
+  const detail = await client.getIntegration(id);
   if (!detail?.manifest) {
     throw new UserError(
-      `${name} has no active version on ${target} — nothing to pull`
+      `${id} has no active version on ${target} — nothing to pull`
     );
   }
+  // 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);
-  }
+  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(
-    `pulled ${name} v${detail.version} from ${target} (${written.sort().join(', ')})`
+    `pulled ${id} v${detail.version} from ${target} (${written.sort().join(', ')})`
   );
-  io.log('run `juno types` to regenerate types/ against the pulled manifest');
+  if (removed.length) io.log(`removed ${removed.join(', ')}`);
   return 0;
 }
-
-/**
- * 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.
- */
-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/commands/session-approve.js

@@ -0,0 +1,73 @@
+import { randomUUID } from 'node:crypto';
+
+import { connect } from '../api.js';
+import { UsageError, UserError } from '../errors.js';
+import { converse, finish } from '../prompt.js';
+import { waitSeconds } from './ask.js';
+
+export const SESSION_APPROVE_USAGE =
+  'juno session approve <session-id> [--wait <seconds>]';
+
+/**
+ * `juno session approve <id>` lets through the tool call an assistant session
+ * is waiting on. It is its own command, not `juno ask … approve`, so that a
+ * permission rule allowing `juno ask` does not also let a coding agent
+ * approve the assistant's call_service on the user's behalf.
+ *
+ * It checks first that the session is awaiting an approval — anything else
+ * sent to a question would be taken as the answer — then sends `approve` as
+ * `juno ask` would, and prints and exits the same way.
+ */
+export async function sessionApprove(args, io) {
+  const [id, ...extra] = args._;
+  if (id === undefined || extra.length) {
+    throw new UsageError(`usage: ${SESSION_APPROVE_USAGE}`);
+  }
+  const wait = waitSeconds(args.wait);
+
+  const { client } = await connect(args, io);
+  const session = await client.getAgentSession(id);
+  if (!session) throw new UserError(`no assistant session ${id}`);
+  const refusal = notAwaitingApproval(session, id);
+  if (refusal) throw new UserError(refusal);
+
+  const body = {
+    session_id: id,
+    message: 'approve',
+    message_id: randomUUID(),
+    wait_timeout_seconds: wait,
+  };
+  // Never resent after a busy 409: whatever is pending by then is not what
+  // was checked above.
+  const outcome = await converse(client, body, {
+    stream: false,
+    io,
+    resendWhenBusy: false,
+  });
+  return finish(outcome, id, io);
+}
+
+/** What the session is doing instead of waiting on an approval, if it is. */
+function notAwaitingApproval(session, id) {
+  const pending = session.pending_input;
+  if (session.status === 'awaiting_input' && pending?.kind === 'approval') {
+    return null;
+  }
+  if (session.status === 'awaiting_input') {
+    return (
+      `session ${id} is asking a question, not waiting for an approval: ` +
+      `${JSON.stringify(pending?.question ?? '')}\n` +
+      `answer it with: juno ask --session ${id} "<answer>"`
+    );
+  }
+  if (session.status === 'active') {
+    return (
+      `session ${id} is running a turn and has nothing to approve yet; ` +
+      `wait for it with: juno ask --session ${id}`
+    );
+  }
+  if (session.status === 'idle') {
+    return `session ${id} is idle and has nothing to approve`;
+  }
+  return `session ${id} has ended (status: ${session.status}); there is nothing to approve`;
+}

package/src/commands/skill.js

@@ -0,0 +1,73 @@
+import { connect } from '../api.js';
+import { UsageError } from '../errors.js';
+import { warnIfStale } from '../installed-skill.js';
+import { levenshtein } from '../suggest.js';
+
+export const SKILL_USAGE = 'juno skill [<name>] [--json]';
+
+/**
+ * `juno skill` prints the skills the instance serves: with no name, one line
+ * per skill; with a name, that skill's body exactly as served. `--json`
+ * prints the route's JSON instead. The server renders each tool reference as
+ * the `juno` command in front of it; the CLI does not rewrite them. The index
+ * also says when an installed agent skill is older than what the instance
+ * serves (installed-skill.js).
+ */
+export async function skill(args, io) {
+  const [name, ...extra] = args._;
+  if (extra.length) throw new UsageError(`usage: ${SKILL_USAGE}`);
+
+  const { target, client } = await connect(args, io);
+
+  if (name === undefined) {
+    const index = await client.listSkills();
+    await warnIfStale(index, target, io);
+    if (args.json) return printJSON(index, io);
+    for (const s of index?.skills ?? []) {
+      io.log(`${s.name} — ${s.description}`);
+    }
+    return 0;
+  }
+
+  const detail = await client.getSkill(name);
+  if (!detail) {
+    const { skills = [] } = (await client.listSkills()) ?? {};
+    throw unknownSkill(
+      name,
+      skills.map((s) => s.name)
+    );
+  }
+  if (args.json) return printJSON(detail, io);
+  // Verbatim: the body's own trailing newline is the last byte written.
+  io.write(detail.body);
+  return 0;
+}
+
+/** Compact off a TTY, indented on one, as every JSON the CLI prints. */
+function printJSON(value, io) {
+  io.log(io.isTTY ? JSON.stringify(value, null, 2) : JSON.stringify(value));
+  return 0;
+}
+
+/**
+ * unknownSkill names up to three served skills near what was typed. Skill
+ * names are short, so the distance allowed grows with the name, and a name
+ * that contains what was typed (`integration` → `integration-states`) counts
+ * as near.
+ */
+function unknownSkill(name, names) {
+  const max = Math.max(3, Math.floor(name.length / 2));
+  const near = names
+    .map((n) => ({
+      n,
+      d: n.includes(name) ? 0 : levenshtein(name, n),
+    }))
+    .filter(({ d }) => d <= max)
+    .sort((a, b) => a.d - b.d)
+    .slice(0, 3)
+    .map(({ n }) => `"${n}"`);
+  const hint = near.length
+    ? `did you mean ${near.join(', ')}?`
+    : 'run `juno skill` for the list';
+  return new UsageError(`unknown skill "${name}"; ${hint}`);
+}

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}`);
+}