@junoflow/cli 0.3.0 → 0.9.0

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 or check the server refused because the working
+ * copy is stale: the flow's, integration's or app'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: 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)
+ *   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,78 @@
+import { UserError } from './errors.js';
+import { readSourceFiles, readTestFiles } from './project.js';
+import {
+  baseVersionOf,
+  MANIFEST,
+  manifestText,
+  PACKAGE_JSON,
+  readBoundPackage,
+  readManifestFile,
+  typeFiles,
+  writeChangedFiles,
+  writePackageJSON,
+} from './working-copy.js';
+
+/**
+ * A flow working copy is laid out as an integration's is: manifest.json, the
+ * sources under src/ (entry src/flow.ts) and the tests under test/ are the
+ * author's, types/ is
+ * 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, and what it
+ * shares with an app working copy lives in working-copy.js.
+ */
+export { MANIFEST, PACKAGE_JSON, manifestText, typeFiles };
+export const SRC_DIR = 'src';
+export const FLOW_ENTRY = 'src/flow.ts';
+
+/**
+ * readFlowProject reads what ingest takes: the manifest (parsed, so a broken
+ * one fails here with its parse error rather than as a server 422), every
+ * .ts and .json file under src/ and test/, and the binding in package.json.
+ * Juno stores test/ with the version and never compiles it. A copy
+ * with no src/flow.ts is refused before anything is sent. `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);
+  const files = await readSourceFiles(cwd);
+  if (!Object.hasOwn(files, FLOW_ENTRY)) {
+    throw new UserError(
+      `no ${FLOW_ENTRY} — a flow working copy's entry is ${FLOW_ENTRY}`
+    );
+  }
+  return {
+    ...(await readFlowManifest(cwd)),
+    files: { ...files, ...(await readTestFiles(cwd)) },
+    packageJSON: pkg,
+    flowId: pkg.juno.flow_id,
+    baseVersion: baseVersionOf(pkg),
+  };
+}
+
+/** readFlowManifest is manifest.json, as bytes and parsed. */
+export const readFlowManifest = readManifestFile;
+
+/** readFlowPackage is package.json, refusing a directory that is not a flow working copy. */
+export function readFlowPackage(cwd) {
+  return readBoundPackage(cwd, { kind: 'flow', idKey: 'flow_id' });
+}
+
+/**
+ * updatePackageJSON rewrites a flow working copy's package.json through
+ * `mutate`, keeping every key it does not touch (and their order).
+ */
+export async function updatePackageJSON(cwd, mutate) {
+  const pkg = await readFlowPackage(cwd);
+  mutate(pkg);
+  await writePackageJSON(cwd, pkg);
+}
+
+/**
+ * writeFlowFiles writes files by working-copy name, skipping one whose
+ * content is already what is on disk. Returns the names it wrote.
+ */
+export const writeFlowFiles = writeChangedFiles;

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