@junoflow/cli 0.15.0 → 0.17.0

package/src/commands/session.js

@@ -0,0 +1,103 @@
+import { connect } from '../api.js';
+import { UsageError } from '../errors.js';
+import { EXIT_OK } from '../exit.js';
+import { json } from './approval-wait.js';
+
+// The assistant's sessions, over /api/agent… as the web UI's Assistant pages
+// read and drive them. They call no tool: a session is the in-app assistant's
+// conversation, not a resource the gateway serves. `session approve` (its own
+// file) is the fourth driving command; these never answer what a session
+// waits on.
+
+export const SESSION_LIST_USAGE =
+  'juno session list [--rating up|down|unaddressed|addressed|unrated] [--profile assistant|author|integration_author|app_author] [--limit <n>]';
+export const SESSION_GET_USAGE = 'juno session get <session-id> [--transcript]';
+export const SESSION_EXPORT_USAGE = 'juno session export <session-id>';
+export const SESSION_RATE_USAGE =
+  'juno session rate <session-id> --rating up|down|addressed|none';
+export const SESSION_CANCEL_USAGE = 'juno session cancel <session-id>';
+
+/** The words `--rating` takes on `session rate`, as the route's numbers. */
+const RATINGS = { up: 2, none: 0, addressed: -1, down: -2 };
+
+/** oneID is the single session id a command takes. */
+function oneID(args, usage) {
+  const [id, ...extra] = args._;
+  if (id === undefined || extra.length) throw new UsageError(`usage: ${usage}`);
+  return id;
+}
+
+/** sessionPath is /api/agent/{id} plus suffix, and the 404 it answers. */
+function sessionPath(id, suffix = '') {
+  return [
+    `/api/agent/${encodeURIComponent(id)}${suffix}`,
+    { notFound: `no assistant session ${id}` },
+  ];
+}
+
+async function print(io, value) {
+  await json(io)(value);
+  return EXIT_OK;
+}
+
+/** `juno session list`: GET /api/agent, newest first. */
+export async function sessionList(args, io) {
+  if (args._.length) throw new UsageError(`usage: ${SESSION_LIST_USAGE}`);
+  const query = new URLSearchParams();
+  if (args.rating !== undefined) query.set('rating', args.rating);
+  if (args.profile !== undefined) query.set('profile', args.profile);
+  if (args.limit !== undefined) {
+    if (!/^\d+$/.test(args.limit)) {
+      throw new UsageError(`--limit takes a number, got "${args.limit}"`);
+    }
+    query.set('limit', args.limit);
+  }
+  const { client } = await connect(args, io);
+  const qs = query.size ? `?${query}` : '';
+  return print(io, await client.rest('GET', `/api/agent${qs}`));
+}
+
+/** `juno session get <id>`: GET /api/agent/{id}, with its transcript on request. */
+export async function sessionGet(args, io) {
+  const id = oneID(args, SESSION_GET_USAGE);
+  const { client } = await connect(args, io);
+  const [path, opts] = sessionPath(
+    id,
+    args.transcript ? '?transcript=true' : ''
+  );
+  return print(io, await client.rest('GET', path, undefined, opts));
+}
+
+/** `juno session export <id>`: GET /api/agent/{id}/export. */
+export async function sessionExport(args, io) {
+  const id = oneID(args, SESSION_EXPORT_USAGE);
+  const { client } = await connect(args, io);
+  const [path, opts] = sessionPath(id, '/export');
+  return print(io, await client.rest('GET', path, undefined, opts));
+}
+
+/** `juno session rate <id> --rating …`: PUT /api/agent/{id}/rating. */
+export async function sessionRate(args, io) {
+  const id = oneID(args, SESSION_RATE_USAGE);
+  if (!Object.hasOwn(RATINGS, args.rating ?? '')) {
+    throw new UsageError(
+      `--rating takes up, down, addressed or none; usage: ${SESSION_RATE_USAGE}`
+    );
+  }
+  const { client } = await connect(args, io);
+  const [path, opts] = sessionPath(id, '/rating');
+  return print(
+    io,
+    await client.rest('PUT', path, { rating: RATINGS[args.rating] }, opts)
+  );
+}
+
+/** `juno session cancel <id>`: POST /api/agent/{id}/cancel. */
+export async function sessionCancel(args, io) {
+  const id = oneID(args, SESSION_CANCEL_USAGE);
+  const { client } = await connect(args, io);
+  // The orchestrator's own words on a 404: an unknown session and one that
+  // has already ended are both refused there.
+  const [path] = sessionPath(id, '/cancel');
+  return print(io, await client.rest('POST', path));
+}

package/src/commands/skill.js

@@ -1,27 +1,25 @@
 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]';
+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).
+ * per skill; with names, those skills' bodies exactly as served — one name
+ * prints the body alone, several put a `===== <name> =====` line before
+ * each, so one call loads everything a task needs. `--json` prints the
+ * route's JSON instead: the index, one skill's detail, or an array of them.
+ * Every name is resolved before anything is printed, so an unknown one fails
+ * the call with nothing written. The server renders each tool reference as
+ * the `juno` command in front of it; the CLI does not rewrite them.
  */
 export async function skill(args, io) {
-  const [name, ...extra] = args._;
-  if (extra.length) throw new UsageError(`usage: ${SKILL_USAGE}`);
+  const names = args._;
+  const { client } = await connect(args, io);
 
-  const { target, client } = await connect(args, io);
-
-  if (name === undefined) {
+  if (names.length === 0) {
     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}`);
@@ -29,17 +27,28 @@ export async function skill(args, io) {
     return 0;
   }
 
-  const detail = await client.getSkill(name);
-  if (!detail) {
+  const details = await Promise.all(names.map((n) => client.getSkill(n)));
+  const missing = names.find((_, i) => !details[i]);
+  if (missing !== undefined) {
     const { skills = [] } = (await client.listSkills()) ?? {};
     throw unknownSkill(
-      name,
+      missing,
       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);
+  if (args.json) {
+    return printJSON(details.length === 1 ? details[0] : details, io);
+  }
+  if (details.length === 1) {
+    // Verbatim: the body's own trailing newline is the last byte written.
+    io.write(details[0].body);
+    return 0;
+  }
+  details.forEach((d, i) => {
+    if (i > 0) io.write('\n');
+    io.write(`===== ${d.name} =====\n\n`);
+    io.write(d.body);
+  });
   return 0;
 }
 

package/src/commands/tool.js

@@ -3,9 +3,10 @@ import { readFile } from 'node:fs/promises';
 import { basename, resolve } from 'node:path';
 import { isDeepStrictEqual } from 'node:util';
 
-import { connect } from '../api.js';
+import { connect, skillsPointer } from '../api.js';
 import { UsageError, UserError } from '../errors.js';
 import { EXIT_FAILURE, EXIT_OK } from '../exit.js';
+import { approvalWaitSeconds, followApproval } from './approval-wait.js';
 
 /**
  * runTool runs one tool row of verbs.json: build the tool's input from the
@@ -16,9 +17,23 @@ import { EXIT_FAILURE, EXIT_OK } from '../exit.js';
  */
 export async function runTool(row, args, io) {
   const input = await buildInput(row, args, io);
+  const wait = approvalWaitSeconds(args.wait);
 
-  const { client } = await connect(args, io);
-  const { result, text } = await client.callTool(row.tool, input);
+  const { client, target } = await connect(args, io);
+  const { result, text, skills } = await client.callTool(row.tool, input);
+
+  // A destructive tool runs nothing until a person approves it in Juno: it
+  // answers approval_required, and the command waits for the decision
+  // (plan-cli-parity.md decision 11, the one result the CLI interprets).
+  const required = result?.approval_required;
+  if (required && typeof required === 'object' && required.id) {
+    const print = async (value) => {
+      const out = JSON.stringify(value);
+      if (args.jq !== undefined) io.log(await runJq(args.jq, out, io));
+      else io.log(io.isTTY ? JSON.stringify(value, null, 2) : out);
+    };
+    return followApproval(required, { client, target, wait, io, print });
+  }
 
   if (args.jq !== undefined) {
     io.log(await runJq(args.jq, text, io));
@@ -26,8 +41,11 @@ export async function runTool(row, args, io) {
     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;
+  // it is printed like any result, and only the exit code says it failed —
+  // plus, on stderr, the skills the gateway says explain the tool.
+  if (typeof result?.error !== 'string') return EXIT_OK;
+  if (skills.length) io.warn(skillsPointer(skills));
+  return EXIT_FAILURE;
 }
 
 /**

package/src/commands/whoami.js

@@ -0,0 +1,38 @@
+import { readFileSync } from 'node:fs';
+
+import { connect } from '../api.js';
+import { UsageError } from '../errors.js';
+import { EXIT_OK } from '../exit.js';
+import { json } from './approval-wait.js';
+
+export const WHOAMI_USAGE = 'juno whoami';
+export const VERSION_USAGE = 'juno version';
+
+/** This CLI's own version, from the package it ships in. */
+const CLI_VERSION = JSON.parse(
+  readFileSync(new URL('../../package.json', import.meta.url), 'utf8')
+).version;
+
+/**
+ * `juno whoami`: GET /api/me — the principal the instance takes this CLI for
+ * (a key, a user behind the proxy, or local), its scope and the linked
+ * person. It is how an agent learns what its key may do before it tries.
+ */
+export async function whoami(args, io) {
+  if (args._.length) throw new UsageError(`usage: ${WHOAMI_USAGE}`);
+  const { client } = await connect(args, io);
+  await json(io)(await client.rest('GET', '/api/me'));
+  return EXIT_OK;
+}
+
+/**
+ * `juno version`: GET /api/version, the instance's build and schema version,
+ * with this CLI's version beside it as `cli_version`.
+ */
+export async function version(args, io) {
+  if (args._.length) throw new UsageError(`usage: ${VERSION_USAGE}`);
+  const { client } = await connect(args, io);
+  const body = await client.rest('GET', '/api/version');
+  await json(io)({ ...body, cli_version: CLI_VERSION });
+  return EXIT_OK;
+}

package/src/exit.js

@@ -10,8 +10,11 @@
  *   3  the instance is unreachable (the fetch itself failed)
  *   4  a deploy conflict: a working-copy deploy or check (any kind) got a
  *      409 because the active version is not the copy's base_version
- *   5  `juno ask` / `session approve`: the turn is still running (pending)
+ *   5  `juno ask` / `session approve`: the turn is still running (pending);
+ *      a destructive command or `approval wait`: nobody has decided the
+ *      approval when --wait ran out
  *   6  `juno ask` / `session approve`: the assistant is awaiting input
+ * 130  Ctrl-C while waiting for an approval; the request stays open
  *
  * `juno task run` is the exception once its own arguments are accepted: it
  * exits with the wrapped command's status, as a shell would report it.
@@ -23,3 +26,4 @@ export const EXIT_UNREACHABLE = 3;
 export const EXIT_CONFLICT = 4;
 export const EXIT_PENDING = 5;
 export const EXIT_AWAITING_INPUT = 6;
+export const EXIT_INTERRUPTED = 130;

package/src/help.js

@@ -50,12 +50,18 @@ export async function groupHelp(group, rows, handlerFor, args, io) {
   const authoring = Object.hasOwn(AUTHORING_HEADINGS, group) ? group : null;
   let tools = null;
   let skills = null;
+  let readFirst = [];
   if (onInstance.some((row) => row.tool) || authoring) {
     try {
       const { client } = await connect(args, io);
       if (onInstance.some((row) => row.tool)) {
         tools = new Map((await client.listTools()).map((t) => [t.name, t]));
       }
+      readFirst = await readFirstFor(
+        client,
+        [group, ...members.map((r) => r.tool)],
+        io
+      );
       if (authoring) {
         skills = (await client.listSkills({ authoring }))?.skills ?? [];
       }
@@ -65,19 +71,17 @@ export async function groupHelp(group, rows, handlerFor, args, io) {
   }
 
   const lines = members.map((row) => {
-    const synopsis = row.tool
-      ? `juno ${row.command}${positionalName(row) ? ` ${positionalName(row)}` : ''}`
-      : handlerFor(row).usage;
-    if (!row.tool) return [synopsis, row.effect, row.summary];
+    const line = synopsis(row, handlerFor);
+    if (!row.tool) return [line, row.effect, row.summary];
     const tool = tools?.get(row.tool);
+    // A row that fixes part of its tool's input (one verb of command_task)
+    // says what it does itself; the tool's first sentence covers every verb.
+    if (row.summary)
+      return [line, row.effect ?? tool?.effect ?? '', row.summary];
     // Offline, no tool row shows an effect: printing only the rows that carry
     // their own would read as if the others had none.
-    if (!tool) return [synopsis, '', ''];
-    return [
-      synopsis,
-      row.effect ?? tool.effect,
-      firstSentence(tool.description),
-    ];
+    if (!tool) return [line, '', ''];
+    return [line, row.effect ?? tool.effect, firstSentence(tool.description)];
   });
   // One column width across both headings, so the two lists line up.
   const render = tabulate(lines);
@@ -89,6 +93,7 @@ export async function groupHelp(group, rows, handlerFor, args, io) {
       : `usage: juno ${group} <verb>`,
     '',
   ];
+  if (readFirst.length) out.push(readFirstLine(readFirst), '');
   if (inWorkingCopy.length === 0) {
     out.push(...body(members));
   } else {
@@ -109,21 +114,99 @@ export async function groupHelp(group, rows, handlerFor, args, io) {
   return out.join('\n');
 }
 
-export const WORKING_COPY_HEADING =
-  'In a working copy (run from the project directory)';
-
 /**
- * workingCopyListing is every working-copy command with its effect and
- * summary, for `juno --help`; offline, since all of it is in verbs.json.
+ * rootHelp is `juno --help` and bare `juno`: the place an agent with nothing
+ * installed starts. Usage first, then the primer from GET /api/agent-primer
+ * (what Juno is made of, how to work with it, what only the user does), then
+ * every group and top-level command by one line from verbs.json, the
+ * working-copy commands, and the skill index from GET /api/skills. The
+ * instance owns the primer and the skills; the CLI owns the listing.
+ *
+ * Offline — no instance configured, unreachable, refused — the primer and the
+ * skills are dropped, the reason goes to stderr as for a group's help, and one
+ * line says how to connect. A help must not fail offline.
  */
-export function workingCopyListing(rows, handlerFor) {
-  return tabulate(
-    rows
-      .filter((row) => row.working_copy)
-      .map((row) => [handlerFor(row).usage, row.effect, row.summary])
-  ).join('\n');
+export async function rootHelp(rows, handlerFor, groupSummaries, args, io) {
+  let primer = null;
+  let skills = null;
+  try {
+    const { client } = await connect(args, io);
+    const [p, index] = await Promise.all([
+      client.getAgentPrimer(),
+      client.listSkills(),
+    ]);
+    primer = p?.body ?? null;
+    skills = index?.skills ?? [];
+  } catch (err) {
+    io.warn(`(guide unavailable: ${err.message})`);
+  }
+
+  const out = [
+    'juno — operate a Juno instance, and develop flows, integrations and apps for it',
+    '',
+    'Usage: juno <command> [options]',
+    `       juno <group> <verb> [id] ${INPUT_USAGE}`,
+    '',
+  ];
+  if (primer) {
+    out.push(primer.trim(), '');
+  } else {
+    out.push(
+      'The guide to working with Juno and the skill index come from the instance,',
+      'which did not answer (the reason is on stderr). `juno config set url <url>`',
+      'and `juno config set token <key>` connect this CLI to one.',
+      ''
+    );
+  }
+
+  const groups = [];
+  for (const row of rows) {
+    const group = groupOf(row);
+    if (group && !groups.includes(group)) groups.push(group);
+  }
+  out.push("Groups (run `juno <group> --help` for a group's commands):");
+  out.push(...tabulate(groups.map((g) => [g, '', groupSummaries[g] ?? ''])));
+  out.push('', 'Commands:');
+  out.push(
+    ...tabulate(
+      rows
+        .filter((row) => !groupOf(row))
+        .map((row) => [synopsis(row, handlerFor), '', row.summary ?? ''])
+    )
+  );
+
+  if (skills?.length) {
+    out.push(
+      '',
+      'Skills (`juno skill <name>...` prints them; `juno skill` gives each its full description):'
+    );
+    const width = Math.max(...skills.map((s) => s.name.length));
+    for (const s of skills) {
+      out.push(`  ${s.name.padEnd(width)}  ${firstSentence(s.description)}`);
+    }
+  }
+
+  out.push(
+    '',
+    '--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.',
+    ''
+  );
+  return out.join('\n');
+}
+
+/** One row's synopsis as a listing shows it: `juno state get <id>`. */
+function synopsis(row, handlerFor) {
+  if (!row.tool) return handlerFor(row).usage;
+  const positional = positionalName(row);
+  return `juno ${row.command}${positional ? ` ${positional}` : ''}`;
 }
 
+export const WORKING_COPY_HEADING =
+  'In a working copy (run from the project directory)';
+
 /** Rows of [synopsis, effect, text] as aligned, indented lines. */
 function tabulate(lines) {
   const width = Math.max(...lines.map(([s]) => s.length));
@@ -149,7 +232,15 @@ export async function verbHelp(row, args, io) {
     );
   }
 
-  const out = [`usage: ${rowUsage(row)}`, '', tool.description.trim(), ''];
+  const out = [`usage: ${rowUsage(row)}`, ''];
+  // Which skills to read first is the server's mapping (each skill's
+  // applies_to); a failure to fetch it drops the line, never the help.
+  const readFirst = await readFirstFor(client, [groupOf(row), row.tool], io);
+  if (readFirst.length) out.push(readFirstLine(readFirst), '');
+  // A top-level command's summary is its line in `juno --help`; the tool's
+  // description says the same at length.
+  if (row.summary && row.fixed_input) out.push(row.summary, '');
+  out.push(tool.description.trim(), '');
   out.push(`effect: ${row.effect ?? tool.effect}`);
   out.push(`tool: ${row.tool}`);
   if (row.id_field) {
@@ -177,6 +268,36 @@ export async function verbHelp(row, args, io) {
   return out.join('\n');
 }
 
+/**
+ * skillsFor is the names of the skills whose applies_to names any of `names`
+ * (a group, a tool), in the index's order. The mapping is the server's: the CLI
+ * only matches the strings.
+ */
+export function skillsFor(skills, names) {
+  const wanted = new Set(names.filter(Boolean));
+  return skills
+    .filter((s) => (s.applies_to ?? []).some((n) => wanted.has(n)))
+    .map((s) => s.name);
+}
+
+/**
+ * readFirstFor fetches the skill index and answers skillsFor over it. Its
+ * own failure costs only the line: the reason goes to stderr and the help
+ * goes on.
+ */
+async function readFirstFor(client, names, io) {
+  try {
+    return skillsFor((await client.listSkills())?.skills ?? [], names);
+  } catch (err) {
+    io.warn(`(skills unavailable: ${err.message})`);
+    return [];
+  }
+}
+
+function readFirstLine(names) {
+  return `Read first: juno skill ${names.join(' ')}`;
+}
+
 /** The help of a non-tool command, offline: its summary and its usage. */
 export function nonToolHelp(row, handler) {
   return `${row.summary}\n\nusage: ${handler.usage}`;