@junoflow/cli 0.1.5 → 0.6.0

package/src/help.js

@@ -0,0 +1,199 @@
+import { connect } from './api.js';
+import { AUTHORING_HEADINGS, authoringHeading } from './authoring-skills.js';
+import { UsageError } from './errors.js';
+import { groupOf } from './verbs.js';
+
+const INPUT_USAGE = '[--input <json>|-|@file] [--jq <expr>]';
+
+/**
+ * rowUsage is one command's synopsis: the positional and flags come from its
+ * verbs.json row, a non-tool command's from its handler.
+ */
+export function rowUsage(row, handler) {
+  if (!row.tool) return handler.usage;
+  const parts = [`juno ${row.command}`];
+  const positional = positionalName(row);
+  if (positional) parts.push(`[${positional}]`);
+  for (const [flag, spec] of Object.entries(row.flags ?? {})) {
+    parts.push(`[--${flag} <${spec.type}>${spec.multiple ? '...' : ''}]`);
+  }
+  parts.push(INPUT_USAGE);
+  return parts.join(' ');
+}
+
+function positionalName(row) {
+  if (row.id_field) return `<${row.id_field}>`;
+  if (row.positional === 'kind:id') return '<kind>:<id> | <kind> <id>';
+  if (row.positional === 'file') return '<file>';
+  return null;
+}
+
+/**
+ * groupHelp lists a group's commands. The effect and first sentence of each
+ * tool's description come from GET /api/tools, because the server owns that
+ * text; when the instance cannot answer, the commands are listed alone and
+ * the reason goes to stderr. A help must not fail offline.
+ *
+ * A group with working-copy commands (`juno flow init`, `deploy`, …) lists
+ * them under a second heading, from their own `summary`, offline: they act on
+ * a directory, not on the instance, and an agent reading the help must be
+ * able to tell the two apart. `handlerFor(row)` is a non-tool row's handler.
+ */
+export async function groupHelp(group, rows, handlerFor, args, io) {
+  const members = rows.filter((row) => groupOf(row) === group);
+  const onInstance = members.filter((row) => !row.working_copy);
+  const inWorkingCopy = members.filter((row) => row.working_copy);
+
+  // A kind with working copies also lists its authoring skills, by their
+  // first sentence, under the working-copy heading — the same index `init`
+  // prints, fetched the same way and dropped the same way offline.
+  const authoring = Object.hasOwn(AUTHORING_HEADINGS, group) ? group : null;
+  let tools = null;
+  let skills = null;
+  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]));
+      }
+      if (authoring) {
+        skills = (await client.listSkills({ authoring }))?.skills ?? [];
+      }
+    } catch (err) {
+      io.warn(`(descriptions unavailable: ${err.message})`);
+    }
+  }
+
+  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 tool = tools?.get(row.tool);
+    // 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),
+    ];
+  });
+  // One column width across both headings, so the two lists line up.
+  const render = tabulate(lines);
+  const body = (subset) => subset.map((row) => render[members.indexOf(row)]);
+
+  const out = [
+    onInstance.some((row) => row.tool)
+      ? `usage: juno ${group} <verb> [id] ${INPUT_USAGE}`
+      : `usage: juno ${group} <verb>`,
+    '',
+  ];
+  if (inWorkingCopy.length === 0) {
+    out.push(...body(members));
+  } else {
+    out.push('On the instance:', ...body(onInstance), '');
+    out.push(`${WORKING_COPY_HEADING}:`, ...body(inWorkingCopy));
+  }
+  if (skills?.length) {
+    const width = Math.max(...skills.map((s) => s.name.length));
+    out.push('', authoringHeading(authoring));
+    for (const s of skills) {
+      out.push(`  ${s.name.padEnd(width)}  ${firstSentence(s.description)}`);
+    }
+  }
+  out.push(
+    '',
+    `Run \`juno ${group} <verb> --help\` for a command's full description and input schema.`
+  );
+  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.
+ */
+export function workingCopyListing(rows, handlerFor) {
+  return tabulate(
+    rows
+      .filter((row) => row.working_copy)
+      .map((row) => [handlerFor(row).usage, row.effect, row.summary])
+  ).join('\n');
+}
+
+/** Rows of [synopsis, effect, text] as aligned, indented lines. */
+function tabulate(lines) {
+  const width = Math.max(...lines.map(([s]) => s.length));
+  const effectWidth = Math.max(...lines.map(([, e]) => (e ?? '').length));
+  return lines.map(([synopsis, effect = '', text]) =>
+    `  ${synopsis.padEnd(width)}  ${(effect ?? '').padEnd(effectWidth)}  ${text}`.trimEnd()
+  );
+}
+
+/**
+ * verbHelp is one tool command's help: the tool's full description, effect
+ * and input schema from GET /api/tools, plus what the row adds — positional,
+ * flags, fixed input. Unlike a group's, it needs the instance: the schema is
+ * the help.
+ */
+export async function verbHelp(row, args, io) {
+  const { target, client } = await connect(args, io);
+  const tool = (await client.listTools()).find((t) => t.name === row.tool);
+  if (!tool) {
+    throw new UsageError(
+      `${target} does not serve the tool "${row.tool}"; ` +
+        'the instance is probably older than this CLI'
+    );
+  }
+
+  const out = [`usage: ${rowUsage(row)}`, '', tool.description.trim(), ''];
+  out.push(`effect: ${row.effect ?? tool.effect}`);
+  out.push(`tool: ${row.tool}`);
+  if (row.id_field) {
+    out.push(`positional: <${row.id_field}> → input field "${row.id_field}"`);
+  } else if (row.positional === 'kind:id') {
+    out.push(
+      'positional: <kind>:<id> or <kind> <id> → input fields "kind" and "id", split at the first ":"; ' +
+        'ha:<entity_id> and mqtt:<topic> are endpoints'
+    );
+  } else if (row.positional === 'file') {
+    out.push(
+      'positional: <file> → its content under "files" by basename, and "entry"'
+    );
+  }
+  for (const [flag, spec] of Object.entries(row.flags ?? {})) {
+    const repeat = spec.multiple ? ', repeatable' : '';
+    out.push(
+      `flag: --${flag} <${spec.type}${repeat}> → input field "${spec.field}"`
+    );
+  }
+  if (row.fixed_input) {
+    out.push(`always sends: ${JSON.stringify(row.fixed_input)}`);
+  }
+  out.push('', 'input schema:', JSON.stringify(tool.input_schema, null, 2));
+  return out.join('\n');
+}
+
+/** 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}`;
+}
+
+/**
+ * firstSentence is a description's first sentence, for a one-line listing:
+ * up to the first `.`, `!` or `?` followed by whitespace, skipping the ones
+ * that close an abbreviation such as "e.g.".
+ */
+export function firstSentence(text = '') {
+  const flat = text.trim().replace(/\s+/g, ' ');
+  const end = /[.!?](?= |$)/g;
+  let m;
+  while ((m = end.exec(flat))) {
+    const upTo = flat.slice(0, m.index + 1);
+    if (!/\b(e\.g|i\.e|etc|vs)\.$/i.test(upTo)) return upTo;
+  }
+  return flat;
+}