@junoflow/cli 0.14.0 → 0.17.0

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

package/src/index.js

@@ -1,15 +1,12 @@
 import { parseArgs } from 'node:util';
 
-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 { APPROVAL_WAIT_USAGE, approvalWait } from './commands/approval-wait.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';
@@ -30,19 +27,39 @@ import { FLOW_PULL_USAGE, flowPull } from './commands/flow-pull.js';
 import { GEN_TYPES_USAGE, genTypes } from './commands/gen-types.js';
 import { INIT_USAGE, init } from './commands/init.js';
 import {
-  JOB_PING_USAGE,
-  JOB_RUN_USAGE,
-  jobPing,
-  jobRun,
-} from './commands/job-run.js';
+  TASK_PING_USAGE,
+  TASK_RUN_USAGE,
+  taskPing,
+  taskRun,
+} from './commands/task-run.js';
 import { PULL_USAGE, pull } from './commands/pull.js';
+import { PERMISSIONS_USAGE, permissions } from './commands/permissions.js';
 import { SKILL_USAGE, skill } from './commands/skill.js';
 import {
   SESSION_APPROVE_USAGE,
   sessionApprove,
 } from './commands/session-approve.js';
+import { runFollow } from './commands/run-follow.js';
+import {
+  SESSION_CANCEL_USAGE,
+  SESSION_EXPORT_USAGE,
+  SESSION_GET_USAGE,
+  SESSION_LIST_USAGE,
+  SESSION_RATE_USAGE,
+  sessionCancel,
+  sessionExport,
+  sessionGet,
+  sessionList,
+  sessionRate,
+} from './commands/session.js';
 import { runTool } from './commands/tool.js';
 import { VERIFY_TYPES_USAGE, verifyTypes } from './commands/verify-types.js';
+import {
+  VERSION_USAGE,
+  WHOAMI_USAGE,
+  version,
+  whoami,
+} from './commands/whoami.js';
 import {
   ConflictError,
   DiagnosticsError,
@@ -58,15 +75,15 @@ import {
   EXIT_UNREACHABLE,
   EXIT_USAGE,
 } from './exit.js';
-import {
-  groupHelp,
-  nonToolHelp,
-  verbHelp,
-  WORKING_COPY_HEADING,
-  workingCopyListing,
-} from './help.js';
+import { groupHelp, nonToolHelp, rootHelp, verbHelp } from './help.js';
 import { closest, closestByVerb, levenshtein } from './suggest.js';
-import { groupOf, normalizeVerb, rowFor, rows } from './verbs.js';
+import {
+  groupOf,
+  groupSummaries,
+  normalizeVerb,
+  rowFor,
+  rows,
+} from './verbs.js';
 
 /**
  * The two flags every command that reaches an instance takes, and the two a
@@ -94,11 +111,58 @@ const NON_TOOL = {
     },
     usage: ASK_USAGE,
   },
+  whoami: { run: whoami, options: URL_OPTION, usage: WHOAMI_USAGE },
+  version: { run: version, options: URL_OPTION, usage: VERSION_USAGE },
+  permissions: {
+    run: permissions,
+    options: {
+      ...URL_OPTION,
+      'allow-change': { type: 'boolean', default: false },
+      'working-copy': { type: 'boolean', default: false },
+      json: { type: 'boolean', default: false },
+    },
+    usage: PERMISSIONS_USAGE,
+  },
+  'session list': {
+    run: sessionList,
+    options: {
+      ...URL_OPTION,
+      rating: { type: 'string' },
+      profile: { type: 'string' },
+      limit: { type: 'string' },
+    },
+    usage: SESSION_LIST_USAGE,
+  },
+  'session get': {
+    run: sessionGet,
+    options: { ...URL_OPTION, transcript: { type: 'boolean', default: false } },
+    usage: SESSION_GET_USAGE,
+  },
+  'session export': {
+    run: sessionExport,
+    options: URL_OPTION,
+    usage: SESSION_EXPORT_USAGE,
+  },
+  'session rate': {
+    run: sessionRate,
+    options: { ...URL_OPTION, rating: { type: 'string' } },
+    usage: SESSION_RATE_USAGE,
+  },
+  'session cancel': {
+    run: sessionCancel,
+    options: URL_OPTION,
+    usage: SESSION_CANCEL_USAGE,
+  },
   'session approve': {
     run: sessionApprove,
     options: { ...URL_OPTION, wait: { type: 'string' } },
     usage: SESSION_APPROVE_USAGE,
   },
+  'approval wait': {
+    run: approvalWait,
+    options: { ...URL_OPTION, wait: { type: 'string' } },
+    usage: APPROVAL_WAIT_USAGE,
+  },
   'credential set': {
     run: credentialSet,
     options: {
@@ -111,19 +175,19 @@ const NON_TOOL = {
   // raw: everything after `--` is the wrapped command's, verbatim, so the
   // argv goes to the handler unparsed (see runRow). No --url or --token: the
   // wrapper reads no Juno config, only the ping URL.
-  'job run': {
-    run: (argv, io) => jobRun(argv, io, { env: io.env }),
+  'task run': {
+    run: (argv, io) => taskRun(argv, io, { env: io.env }),
     options: {
       'url-file': { type: 'string' },
       verbose: { type: 'boolean', default: false },
     },
-    usage: JOB_RUN_USAGE,
+    usage: TASK_RUN_USAGE,
     raw: true,
   },
-  // No --url or --token either: one report to the ping URL, found as job run
+  // No --url or --token either: one report to the ping URL, found as task run
   // finds it.
-  'job ping': {
-    run: (args, io) => jobPing(args, io, { env: io.env }),
+  'task ping': {
+    run: (args, io) => taskPing(args, io, { env: io.env }),
     options: {
       'url-file': { type: 'string' },
       start: { type: 'boolean' },
@@ -132,21 +196,9 @@ const NON_TOOL = {
       log: { type: 'boolean' },
       rid: { type: 'string' },
     },
-    usage: JOB_PING_USAGE,
+    usage: TASK_PING_USAGE,
   },
   'config set': { run: configSet, options: {}, usage: CONFIG_SET_USAGE },
-  'agent-skill install': {
-    run: agentSkillInstall,
-    options: {
-      ...URL_OPTION,
-      dir: { type: 'string' },
-      'allow-change': { type: 'boolean', default: false },
-      'working-copy': { type: 'boolean', default: false },
-      'agents-md': { type: 'boolean', default: false },
-      json: { type: 'boolean', default: false },
-    },
-    usage: AGENT_SKILL_INSTALL_USAGE,
-  },
 };
 
 /**
@@ -301,6 +353,21 @@ const WORKING_COPY = {
   },
 };
 
+/**
+ * Flags a tool row takes beyond its verbs.json ones, which name no field of
+ * the tool's input and so cannot be in the table: what the CLI does around
+ * the call. `run get --follow` streams the run's steps to stderr until it is
+ * done, then prints get_run as without it.
+ */
+const TOOL_EXTRAS = {
+  'run get': {
+    options: { follow: { type: 'boolean', default: false } },
+    help: "flag: --follow → no input field: stream the run's steps to stderr until it ends, then print the run",
+    run: (row, args, io) =>
+      args.follow ? runFollow(row, args, io) : runTool(row, args, io),
+  },
+};
+
 /** The handler of a non-tool row, working-copy or not, or undefined. */
 function handlerFor(row) {
   if (row.tool) return undefined;
@@ -320,26 +387,6 @@ function dispatchable(command) {
   return row && DISPATCHABLE.includes(row) ? row : undefined;
 }
 
-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>]
-
-Groups: ${[...GROUPS].join(', ')}
-Commands: ${DISPATCHABLE.filter((r) => !groupOf(r))
-  .map((r) => r.command)
-  .join(', ')}
-Run \`juno <group> --help\` for a group's commands.
-
-${WORKING_COPY_HEADING}:
-${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.
-`;
-
 /**
  * run is the whole CLI, injectable so the tests drive it without spawning a
  * process: io carries cwd, env, the TTY bit, stdin and the three output
@@ -387,9 +434,11 @@ async function dispatch(argv, io) {
   const { leading, rest } = leadingFlags(argv);
   const [first, ...tail] = rest;
 
+  // Bare `juno` is `juno --help`, exit 0: it is where an agent with nothing
+  // installed starts, and the primer is the answer it came for.
   if (!first || first === '--help' || first === '-h' || first === 'help') {
-    io.log(USAGE);
-    return first ? EXIT_OK : EXIT_USAGE;
+    const show = (args) => showRootHelp(args, io);
+    return runCommand({ options: URL_OPTION }, tail, leading, io, show, show);
   }
 
   const top = dispatchable(first);
@@ -428,6 +477,11 @@ async function dispatch(argv, io) {
   throw unknownTopLevel(first, first, [first]);
 }
 
+async function showRootHelp(args, io) {
+  io.log(await rootHelp(DISPATCHABLE, handlerFor, groupSummaries, args, io));
+  return EXIT_OK;
+}
+
 async function showGroupHelp(group, args, io, code) {
   io.log(await groupHelp(group, DISPATCHABLE, handlerFor, args, io));
   return code;
@@ -468,21 +522,28 @@ function runRow(row, argv, leading, io) {
     );
   }
 
+  // --wait is how long a destructive tool's approval is waited for; every
+  // tool row takes it, since which tools are destructive is the server's.
   const options = {
     ...URL_OPTION,
     input: { type: 'string' },
     jq: { type: 'string' },
+    wait: { type: 'string' },
   };
   for (const [flag, spec] of Object.entries(row.flags ?? {})) {
     options[flag] = { type: 'string', multiple: spec.multiple === true };
   }
+  const extras = TOOL_EXTRAS[row.command];
+  Object.assign(options, extras?.options);
+  const run = extras?.run ?? runTool;
   return runCommand(
-    { run: (args) => runTool(row, args, io), options },
+    { run: (args) => run(row, args, io), options },
     argv,
     leading,
     io,
     async (args) => {
-      io.log(await verbHelp(row, args, io));
+      const help = await verbHelp(row, args, io);
+      io.log(extras?.help ? `${help}\n${extras.help}` : help);
       return EXIT_OK;
     }
   );
@@ -611,6 +672,12 @@ export function defaultIO() {
     write: (text) => process.stdout.write(text),
     warn: (msg) => process.stderr.write(`${msg}\n`),
     error: (msg) => process.stderr.write(`${msg}\n`),
+    // Ctrl-C while waiting for an approval: the handler says how to resume,
+    // and the wait returns rather than the process dying mid-line.
+    onInterrupt: (fn) => {
+      process.once('SIGINT', fn);
+      return () => process.off('SIGINT', fn);
+    },
   };
 }
 

package/src/prompt.js

@@ -182,6 +182,15 @@ function nextStep(event, id) {
     return `still running; keep waiting with: juno ask --session ${id}`;
   }
   if (event.type !== 'awaiting_input') return null;
+  const approvalID = event.pending_input?.approval_id;
+  if (approvalID) {
+    // A destructive call's approval record: only a person in Juno answers it.
+    const url = event.pending_input.approval_url ?? `/approvals/${approvalID}`;
+    return (
+      `waiting for a person to approve it in Juno: ${url}\n` +
+      `wait for the outcome with: juno ask --session ${id}`
+    );
+  }
   if (event.pending_input?.kind === 'approval') {
     return (
       `awaiting approval; approve with: juno session approve ${id}\n` +

package/src/verbs.js

@@ -2,7 +2,9 @@ import { createRequire } from 'node:module';
 
 // createRequire rather than an import attribute: `with { type: 'json' }` needs
 // Node 20.10+, and engines says >=20.
-const { commands: ROWS } = createRequire(import.meta.url)('../verbs.json');
+const { commands: ROWS, groups: GROUPS } = createRequire(import.meta.url)(
+  '../verbs.json'
+);
 
 /**
  * verbs.json is the command table: every `juno <group> <verb>` the CLI
@@ -12,6 +14,9 @@ const { commands: ROWS } = createRequire(import.meta.url)('../verbs.json');
  */
 export const rows = ROWS;
 
+/** The one line `juno --help` lists each group by, keyed by group. */
+export const groupSummaries = GROUPS;
+
 const byCommand = new Map(ROWS.map((row) => [row.command, row]));
 
 /** The row for a command string ("state get"), or undefined. */