@junoflow/cli 0.1.5 → 0.6.0

package/src/prompt.js

@@ -0,0 +1,196 @@
+import { UnreachableError, UserError } from './errors.js';
+import {
+  EXIT_AWAITING_INPUT,
+  EXIT_FAILURE,
+  EXIT_OK,
+  EXIT_PENDING,
+} from './exit.js';
+
+/**
+ * The Agent Prompt API client both `juno ask` and `juno session approve` use:
+ * the request with its retries, the 409 contract, and the outcome → exit code
+ * mapping. Everything here follows docs/…/reference/agent-api.md; the CLI adds
+ * no semantics of its own beyond which of the server's answers ends a command.
+ */
+
+/** Transport retries after a failed fetch, each reusing both ids. */
+const TRANSPORT_RETRIES = 2;
+const TRANSPORT_BACKOFF_MS = [500, 1000];
+
+/** Rounds of observe-then-resend a busy session gets before giving up. */
+const BUSY_ROUNDS = 3;
+
+/** The default `wait_timeout_seconds`, which stays under a harness's Bash timeout. */
+export const DEFAULT_WAIT_SECONDS = 60;
+
+/**
+ * converse sends `body` (which always names its `session_id`: the CLI mints
+ * one for a new conversation) and returns the turn's final event as
+ * `{event, text}`, `text` being the bytes it arrived as.
+ *
+ * The 409 contract, told apart by the body as the API reference documents
+ * it:
+ * - "session is busy" / "is not idle" / "is not awaiting input": observe
+ *   until the turn ends, then send again with the same message_id, at most
+ *   BUSY_ROUNDS times. With `resendWhenBusy: false` (session approve, which
+ *   must not approve something other than what it checked) it is exit 1.
+ *   An observe that ends awaiting input is returned instead of resent: the
+ *   message was not meant as an answer to a question asked after it was
+ *   typed, and to an approval any answer but `approve` is a denial.
+ * - "session was just created": retry at once, once.
+ * - "session has ended", and anything else: exit 1 with the server's words.
+ */
+export async function converse(
+  client,
+  body,
+  { stream, io, resendWhenBusy = true }
+) {
+  let retriedJustCreated = false;
+  let rounds = 0;
+  for (;;) {
+    const answer = await exchange(client, body, { stream, io });
+    if (!answer.conflict) return answer;
+
+    const kind = conflictKind(answer.conflict);
+    if (kind === 'just-created' && !retriedJustCreated) {
+      retriedJustCreated = true;
+      continue;
+    }
+    if (kind !== 'busy' || !resendWhenBusy || rounds >= BUSY_ROUNDS) {
+      throw new UserError(answer.conflict);
+    }
+
+    rounds += 1;
+    io.warn(`${answer.conflict}`);
+    io.warn(`waiting for session ${body.session_id}'s current turn to end…`);
+    const observed = await exchange(client, observeBody(body), { stream, io });
+    if (observed.conflict) throw new UserError(observed.conflict);
+    if (observed.event.type === 'awaiting_input') {
+      io.warn(
+        'your message was not sent: the session is now awaiting input, ' +
+          'and it would have been taken as the answer'
+      );
+      return observed;
+    }
+  }
+}
+
+/**
+ * exchange is one request, retried at most TRANSPORT_RETRIES times when
+ * there was no answer at all. A retry is safe because it carries the same
+ * session_id and message_id: the server either creates the session under
+ * that id or, finding the message already delivered, observes its turn.
+ */
+async function exchange(client, body, { stream, io }) {
+  for (let attempt = 0; ; attempt += 1) {
+    try {
+      return await once(client, body, { stream, io });
+    } catch (err) {
+      if (!(err instanceof UnreachableError) || attempt >= TRANSPORT_RETRIES) {
+        throw err;
+      }
+      io.warn(`${err.message}; retrying`);
+      await sleep(TRANSPORT_BACKOFF_MS[attempt]);
+    }
+  }
+}
+
+async function once(client, body, { stream, io }) {
+  const answer = await client.prompt(body, { stream });
+  if (!answer.events) return answer;
+
+  // Streaming: progress to stderr, one line an event, until the final one.
+  for await (const line of answer.events) {
+    const { event } = line;
+    if (FINAL.has(event.type)) return line;
+    const note = progress(event);
+    if (note) io.warn(note);
+  }
+  throw new UnreachableError('the prompt stream ended before the turn did');
+}
+
+/** The event types that end a turn, and with it the stream. */
+const FINAL = new Set([
+  'message',
+  'awaiting_input',
+  'done',
+  'error',
+  'pending',
+]);
+
+function progress(event) {
+  switch (event.type) {
+    case 'session':
+      return `session ${event.session_id}`;
+    case 'turn':
+      return '· turn finished';
+    case 'child':
+      return `· delegated to authoring session ${event.child_session_id}`;
+    default:
+      return null;
+  }
+}
+
+/** Observe: the same session and wait, with no message and so no message_id. */
+function observeBody(body) {
+  const { message: _m, message_id: _id, ...rest } = body;
+  return rest;
+}
+
+function conflictKind(text) {
+  if (/^session is busy\b/.test(text)) return 'busy';
+  if (/\bis not (idle|awaiting input)\b/.test(text)) return 'busy';
+  if (/^session was just created\b/.test(text)) return 'just-created';
+  if (/^session has ended\b/.test(text)) return 'ended';
+  return 'other';
+}
+
+/**
+ * outcomeExit maps a turn's final event to the exit code: 0 a reply or a
+ * completed session, 5 still running, 6 awaiting input, 1 anything that
+ * failed.
+ */
+export function outcomeExit(event) {
+  switch (event.type) {
+    case 'message':
+      return EXIT_OK;
+    case 'done':
+      return event.status === 'completed' ? EXIT_OK : EXIT_FAILURE;
+    case 'pending':
+      return EXIT_PENDING;
+    case 'awaiting_input':
+      return EXIT_AWAITING_INPUT;
+    default:
+      return EXIT_FAILURE;
+  }
+}
+
+/**
+ * finish prints the final event on stdout — unchanged off a TTY, indented on
+ * one — says on stderr how to go on when the turn has not ended the
+ * conversation's business, and returns the exit code.
+ */
+export function finish({ event, text }, sessionID, io) {
+  io.log(io.isTTY ? JSON.stringify(event, null, 2) : text.trimEnd());
+  const next = nextStep(event, sessionID);
+  if (next) io.warn(next);
+  return outcomeExit(event);
+}
+
+function nextStep(event, id) {
+  if (event.type === 'pending') {
+    return `still running; keep waiting with: juno ask --session ${id}`;
+  }
+  if (event.type !== 'awaiting_input') return null;
+  if (event.pending_input?.kind === 'approval') {
+    return (
+      `awaiting approval; approve with: juno session approve ${id}\n` +
+      `or deny, with a reason the assistant sees: juno ask --session ${id} "<reason>"`
+    );
+  }
+  return `awaiting an answer; reply with: juno ask --session ${id} "<answer>"`;
+}
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/src/stamp.js

@@ -7,16 +7,17 @@ import { createHash } from 'node:crypto';
  * and TestManifestStampParity pin the same input to the same output from each
  * side, which is the only thing that keeps them together.
  *
- * Why it exists: "edit manifest.json, forget `juno types`" is the one mistake
- * this workflow reliably produces, and nothing else catches it. tsc compiles
- * happily against stale types, eslint is happy, and h.conformance() checks the
- * manifest against the *module*, never against types/. The drift surfaces at
- * deploy, or later still, as a flow author calling an action with a shape that
- * no longer exists.
+ * Why it exists: "edit manifest.json, forget `juno integration gen-types`" is
+ * the one mistake this workflow reliably produces, and nothing else catches
+ * it. tsc compiles happily against stale types, eslint is happy, and
+ * h.conformance() checks the manifest against the *module*, never against
+ * types/. The drift surfaces at deploy, or later still, as a flow author
+ * calling an action with a shape that no longer exists.
  *
  * Why a hash rather than asking a Juno: the check has to run where the mistake
  * is caught — a contributor's CI, which deliberately has no instance to ask.
- * `juno types` needs a server; verifying what it wrote must not.
+ * `juno integration gen-types` needs a server; verifying what it wrote must
+ * not.
  */
 const STAMP_PREFIX = '// juno:manifest-sha256 ';
 const STAMP_LENGTH = 16;
@@ -68,8 +69,8 @@ export function stampEnvDTS(envDTS, manifestJSON) {
  * Applied client-side rather than server-side because it fingerprints the bytes
  * on *this* disk: both endpoints are handed a parsed manifest and never see the
  * file, and the same typegen endpoint also answers the authoring agent, which
- * has no file at all. The project generator behind `juno init` does see one, so
- * it stamps there — internal/typegen/stamp.go.
+ * has no file at all. The project generator behind `juno integration init`
+ * does see one, so it stamps there — internal/typegen/stamp.go.
  */
 export function stampTypeFiles(types, rawManifest) {
   const name = ENV_DTS.replace('types/', '');

package/src/suggest.js

@@ -0,0 +1,67 @@
+/** Suggestions further than this are more likely noise than a typo. */
+const MAX_DISTANCE = 3;
+
+/**
+ * closest is the candidate nearest to any of `attempts` by edit distance, or
+ * null when none is within MAX_DISTANCE. Ties go to the earlier candidate, so
+ * the order of verbs.json decides.
+ */
+export function closest(attempts, candidates) {
+  let best = null;
+  let bestDistance = MAX_DISTANCE + 1;
+  for (const candidate of candidates) {
+    for (const attempt of attempts) {
+      const d = levenshtein(attempt, candidate);
+      if (d < bestDistance) {
+        best = candidate;
+        bestDistance = d;
+      }
+    }
+  }
+  return best;
+}
+
+/** levenshtein is the plain edit distance: insert, delete, substitute. */
+export function levenshtein(a, b) {
+  let prev = Array.from({ length: b.length + 1 }, (_, j) => j);
+  for (let i = 1; i <= a.length; i++) {
+    const cur = [i];
+    for (let j = 1; j <= b.length; j++) {
+      cur[j] = Math.min(
+        prev[j] + 1,
+        cur[j - 1] + 1,
+        prev[j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1)
+      );
+    }
+    prev = cur;
+  }
+  return prev[b.length];
+}
+
+/**
+ * closestByVerb is for a bare word that is not a command: the grouped
+ * commands whose verb is nearest to it, all of them when several groups share
+ * that verb, with the distance. A bare `deploy` is the verb of both
+ * `flow deploy` and `integration deploy`, and only the person knows which
+ * working copy they are in, so both are offered rather than whichever
+ * verbs.json lists first. A verb one of whose `-` words is the attempt counts
+ * as distance 1, so a bare `types` still finds `gen-types`.
+ */
+export function closestByVerb(attempt, commands) {
+  let best = [];
+  let bestDistance = MAX_DISTANCE + 1;
+  for (const command of commands) {
+    const space = command.indexOf(' ');
+    if (space < 0) continue;
+    const verb = command.slice(space + 1);
+    let d = levenshtein(attempt, verb);
+    if (d > 1 && verb.split('-').includes(attempt)) d = 1;
+    if (d < bestDistance) {
+      best = [command];
+      bestDistance = d;
+    } else if (d === bestDistance) {
+      best.push(command);
+    }
+  }
+  return { commands: best, distance: bestDistance };
+}

package/src/target.js

@@ -1,24 +1,34 @@
 import { readFile } from 'node:fs/promises';
 import { join } from 'node:path';
 
+import { readUserConfig } from './config.js';
 import { UserError } from './errors.js';
 
 /**
  * Resolve which Juno instance to talk to, in precedence order: an explicit
  * --url, then $JUNO_URL, then `juno.target` in package.json — which is what an
- * ejected project arrives with, so a fresh clone deploys with no setup.
+ * ejected project arrives with, so a fresh clone deploys with no setup — then
+ * the user config file `juno config set url` writes, for use outside a
+ * project.
  *
- * A missing target names all three: "no target configured" leaves the reader
- * guessing which of the three they were supposed to have used.
+ * A missing target names all four: "no target configured" leaves the reader
+ * guessing which of them they were supposed to have used.
  */
-export async function resolveTarget({ url, cwd = process.cwd() } = {}) {
+export async function resolveTarget({
+  url,
+  cwd = process.cwd(),
+  env = process.env,
+} = {}) {
   const candidate =
-    url ?? process.env.JUNO_URL ?? (await targetFromPackageJSON(cwd));
+    url ??
+    env.JUNO_URL ??
+    (await targetFromPackageJSON(cwd)) ??
+    (await targetFromUserConfig(env));
   if (!candidate) {
     throw new UserError(
-      'no Juno instance to deploy to. Pass --url <url>, set $JUNO_URL, or add\n' +
+      'no Juno instance configured. Pass --url <url>, set $JUNO_URL, add\n' +
         '  "juno": { "target": "http://juno.local:8080" }\n' +
-        'to package.json.'
+        'to package.json, or run `juno config set url <url>`.'
     );
   }
   return normalizeTarget(candidate);
@@ -33,6 +43,11 @@ async function targetFromPackageJSON(cwd) {
   }
 }
 
+async function targetFromUserConfig(env) {
+  const { url } = await readUserConfig(env);
+  return typeof url === 'string' && url.trim() ? url : null;
+}
+
 /** Accepts a bare host the way a browser address bar does. */
 export function normalizeTarget(target) {
   let t = target.trim().replace(/\/+$/, '');

package/src/verbs.js

@@ -0,0 +1,34 @@
+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');
+
+/**
+ * verbs.json is the command table: every `juno <group> <verb>` the CLI
+ * answers, and the one place a command name is decided. The Go tests in
+ * internal/agent/verbs_test.go hold it to the tool gateway; this module only
+ * indexes it.
+ */
+export const rows = ROWS;
+
+const byCommand = new Map(ROWS.map((row) => [row.command, row]));
+
+/** The row for a command string ("state get"), or undefined. */
+export function rowFor(command) {
+  return byCommand.get(command);
+}
+
+/**
+ * A verb spelled with `_` is an alias for the `-` spelling, so an agent that
+ * types the tool's own word order (`juno state get_history`) still lands.
+ */
+export function normalizeVerb(verb) {
+  return verb.replaceAll('_', '-');
+}
+
+/** The group of a two-word command, or null for a top-level one. */
+export function groupOf(row) {
+  const space = row.command.indexOf(' ');
+  return space < 0 ? null : row.command.slice(0, space);
+}

package/src/watch.js

@@ -0,0 +1,50 @@
+import { watch } from 'node:fs';
+
+import { DiagnosticsError } from './errors.js';
+import { formatDiagnostics } from './diagnostics.js';
+
+/** How long to wait for edits to settle before redeploying. */
+export const WATCH_DEBOUNCE_MS = 200;
+
+/**
+ * deployOnChange is `deploy --watch` for both kinds of working copy: run
+ * `once`, then again whenever one of `paths` changes (`{path, recursive?}`),
+ * debounced so an editor's save-and-rename is one deploy. A failed deploy is
+ * printed and the loop keeps watching — the next save is the retry. It
+ * resolves only on SIGINT: watch mode ends when the author ends it.
+ */
+export async function deployOnChange({ io, target, paths, once }) {
+  io.log(`watching ${io.cwd} — deploying to ${target}`);
+  const iteration = async () => {
+    try {
+      await once();
+    } catch (err) {
+      if (err instanceof DiagnosticsError) {
+        io.error(formatDiagnostics(err.diagnostics));
+      } else {
+        io.error(err.message);
+      }
+    }
+  };
+  await iteration();
+
+  let timer = null;
+  const schedule = () => {
+    if (timer) clearTimeout(timer);
+    timer = setTimeout(() => {
+      timer = null;
+      void iteration();
+    }, WATCH_DEBOUNCE_MS);
+  };
+
+  const watchers = paths.map(({ path, recursive = false }) =>
+    watch(path, { recursive }, schedule)
+  );
+  await new Promise((resolve) => {
+    process.once('SIGINT', () => {
+      for (const w of watchers) w.close();
+      resolve();
+    });
+  });
+  return 0;
+}

package/verbs.json

@@ -0,0 +1,227 @@
+{
+  "commands": [
+    {
+      "command": "discover",
+      "tool": "discover",
+      "id_field": "query",
+      "flags": {
+        "kind": { "field": "kinds", "type": "string", "multiple": true }
+      },
+      "naming_exception": "searches every kind, so it has no group"
+    },
+    {
+      "command": "related",
+      "tool": "get_related",
+      "positional": "kind:id",
+      "flags": { "degree": { "field": "degree", "type": "integer" } },
+      "naming_exception": "takes any kind, so it has no group"
+    },
+    { "command": "state get", "tool": "get_state", "id_field": "id" },
+    {
+      "command": "state get-history",
+      "tool": "get_state_history",
+      "id_field": "id"
+    },
+    {
+      "command": "state get-layers",
+      "tool": "get_state_layers",
+      "id_field": "id"
+    },
+    { "command": "state evaluate-level", "tool": "evaluate_level" },
+    {
+      "command": "state preview-layers",
+      "tool": "edit_state_layers",
+      "id_field": "id",
+      "fixed_input": { "dry_run": true },
+      "effect": "read",
+      "naming_exception": "fixes dry_run: true on edit_state_layers, so a permission rule can allow the preview and not the edit"
+    },
+    { "command": "state create", "tool": "create_state", "id_field": "id" },
+    {
+      "command": "state edit-layers",
+      "tool": "edit_state_layers",
+      "id_field": "id",
+      "fixed_input": { "dry_run": false }
+    },
+    {
+      "command": "state set-value",
+      "tool": "set_state_value",
+      "id_field": "id"
+    },
+    { "command": "state claim", "tool": "claim_state", "id_field": "id" },
+    { "command": "state release", "tool": "release_state", "id_field": "id" },
+    { "command": "flow get", "tool": "get_flow", "id_field": "id" },
+    {
+      "command": "flow set-enabled",
+      "tool": "set_flow_enabled",
+      "id_field": "flow_id"
+    },
+    {
+      "command": "flow trigger",
+      "tool": "trigger_flow",
+      "id_field": "flow_id"
+    },
+    {
+      "command": "flow fire-trigger",
+      "tool": "fire_trigger",
+      "id_field": "flow_id"
+    },
+    {
+      "command": "flow init",
+      "effect": "read",
+      "working_copy": true,
+      "summary": "Write a working copy of a flow (or a stub for a new id) into ./<id>"
+    },
+    {
+      "command": "flow gen-types",
+      "effect": "read",
+      "working_copy": true,
+      "summary": "Regenerate flow-env.d.ts and flow-api.d.ts from manifest.json"
+    },
+    {
+      "command": "flow check",
+      "effect": "read",
+      "working_copy": true,
+      "summary": "Typecheck and lint locally, then verify against Juno without deploying"
+    },
+    {
+      "command": "flow deploy",
+      "effect": "change",
+      "working_copy": true,
+      "summary": "Verify, commit and activate the working copy as the flow's next version"
+    },
+    {
+      "command": "flow pull",
+      "effect": "read",
+      "working_copy": true,
+      "summary": "Overwrite the working copy with the flow's active version"
+    },
+    { "command": "run list", "tool": "list_runs" },
+    { "command": "run get", "tool": "get_run", "id_field": "run_id" },
+    {
+      "command": "integration get",
+      "tool": "get_integration",
+      "id_field": "id"
+    },
+    {
+      "command": "integration configure",
+      "tool": "configure_integration",
+      "id_field": "id"
+    },
+    { "command": "integration install", "tool": "install_integration" },
+    {
+      "command": "integration run-schedule",
+      "tool": "run_integration_schedule",
+      "id_field": "integration"
+    },
+    {
+      "command": "integration init",
+      "effect": "read",
+      "working_copy": true,
+      "summary": "Write a working copy of an install (or a starter for a new id) into ./<id>"
+    },
+    {
+      "command": "integration gen-types",
+      "effect": "read",
+      "working_copy": true,
+      "summary": "Regenerate types/ from manifest.json"
+    },
+    {
+      "command": "integration verify-types",
+      "effect": "read",
+      "working_copy": true,
+      "summary": "Check offline that types/ matches manifest.json"
+    },
+    {
+      "command": "integration check",
+      "effect": "read",
+      "working_copy": true,
+      "summary": "Typecheck and lint locally, then verify against Juno without deploying"
+    },
+    {
+      "command": "integration deploy",
+      "effect": "change",
+      "working_copy": true,
+      "summary": "Verify, commit and activate the working copy as the install's next version"
+    },
+    {
+      "command": "integration pull",
+      "effect": "read",
+      "working_copy": true,
+      "summary": "Overwrite manifest.json, src/ and package.json scripts with the active version"
+    },
+    { "command": "device list", "tool": "list_devices" },
+    { "command": "device get", "tool": "get_device", "id_field": "id" },
+    { "command": "device preview", "tool": "preview_device" },
+    { "command": "device write", "tool": "write_device" },
+    { "command": "device suspend", "tool": "suspend_device", "id_field": "id" },
+    { "command": "device release", "tool": "release_device", "id_field": "id" },
+    { "command": "control write", "tool": "write_control" },
+    { "command": "control use", "tool": "use_control", "id_field": "id" },
+    {
+      "command": "control release",
+      "tool": "release_control",
+      "id_field": "id"
+    },
+    { "command": "finding get", "tool": "get_finding", "id_field": "slug" },
+    { "command": "webhook list", "tool": "list_webhooks" },
+    {
+      "command": "webhook get-deliveries",
+      "tool": "get_webhook_deliveries",
+      "id_field": "id"
+    },
+    { "command": "webhook write", "tool": "write_webhook", "id_field": "id" },
+    { "command": "webhook fire", "tool": "fire_webhook", "id_field": "id" },
+    { "command": "credential list", "tool": "list_credentials" },
+    {
+      "command": "ha get-entity",
+      "tool": "get_entity",
+      "id_field": "entity_id"
+    },
+    {
+      "command": "ha get-entity-history",
+      "tool": "get_entity_history",
+      "id_field": "entity_id"
+    },
+    { "command": "ha list-services", "tool": "list_services" },
+    { "command": "ha call-service", "tool": "call_service" },
+    {
+      "command": "script run",
+      "tool": "run_script",
+      "positional": "file",
+      "flags": {
+        "cred": { "field": "credentials", "type": "string", "multiple": true }
+      }
+    },
+    {
+      "command": "skill",
+      "effect": "read",
+      "summary": "Print the skills Juno's assistant can load, or one skill's body"
+    },
+    {
+      "command": "ask",
+      "effect": "act",
+      "summary": "Prompt Juno's in-app assistant"
+    },
+    {
+      "command": "session approve",
+      "effect": "act",
+      "summary": "Approve the tool call an assistant session is waiting on"
+    },
+    {
+      "command": "credential set",
+      "effect": "act",
+      "summary": "Set a credential's secret, typed at a terminal with echo off"
+    },
+    {
+      "command": "config set",
+      "effect": "local",
+      "summary": "Remember the instance URL in the user config file"
+    },
+    {
+      "command": "agent-skill install",
+      "effect": "local",
+      "summary": "Write Juno's skill for a coding agent and print its permission block"
+    }
+  ]
+}