@junoflow/cli 0.3.0 → 0.9.0

package/src/installed-skill.js

@@ -0,0 +1,55 @@
+import { readFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+
+/** Where `juno agent-skill install` writes the skill, relative to a root. */
+export const SKILL_DIR = join('.claude', 'skills', 'juno');
+
+const VERSION_LINE = /^\s*(?:<!--\s*)?juno-skill-version:\s*"?([^"\s]+)"?/m;
+
+/**
+ * installedSkill finds the Juno skill a harness would load: SKILL.md under
+ * `.claude/skills/juno` in the current directory or the nearest parent that
+ * has one, then in the home directory. It answers the first file found and the
+ * version it records (null when it records none), or null when there is no
+ * file. A file that cannot be read counts as absent: the check it serves is a
+ * courtesy, never a failure.
+ */
+export async function installedSkill(cwd, env = process.env) {
+  const candidates = [];
+  let dir = resolve(cwd);
+  for (;;) {
+    candidates.push(join(dir, SKILL_DIR, 'SKILL.md'));
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  candidates.push(join(env.HOME || homedir(), SKILL_DIR, 'SKILL.md'));
+
+  for (const path of candidates) {
+    let text;
+    try {
+      text = await readFile(path, 'utf8');
+    } catch {
+      continue;
+    }
+    return { path, version: VERSION_LINE.exec(text)?.[1] ?? null };
+  }
+  return null;
+}
+
+/**
+ * warnIfStale says on stderr when the installed skill records a version other
+ * than the one the instance serves (`agent_skill_version` on GET /api/skills).
+ * Silent when either side has none.
+ */
+export async function warnIfStale(index, target, io) {
+  const served = index?.agent_skill_version;
+  if (!served) return;
+  const installed = await installedSkill(io.cwd, io.env);
+  if (!installed?.version || installed.version === served) return;
+  io.warn(
+    `the installed Juno skill (${installed.path}) is version ${installed.version}; ` +
+      `${target} serves ${served} — run \`juno agent-skill install\` to update it`
+  );
+}

package/src/project.js

@@ -2,15 +2,22 @@ import { readFile, readdir, mkdir, writeFile } from 'node:fs/promises';
 import { dirname, join, posix, relative, sep } from 'node:path';
 
 import { UserError } from './errors.js';
+import { PACKAGE_JSON, writePackageJSON } from './working-copy.js';
 
 /** Only these reach the server. Everything else is project furniture. */
 const SOURCE_EXTENSIONS = ['.ts', '.json'];
 const SOURCE_DIR = 'src';
+const TEST_DIR = 'test';
 
 /**
- * Read the four things Juno looks at: manifest.json, the sources under src/,
- * package.json's dependencies, and the lockfile. types/ and test/ are the
- * author's — they are never uploaded, and never compiled server-side.
+ * Read the four things Juno looks at: manifest.json, the sources under src/
+ * and test/, package.json's dependencies, and the lockfile. test/ is stored
+ * with the version but never compiled, linted or run server-side; types/ is
+ * generated and never uploaded.
+ *
+ * `baseVersion` is package.json's `juno.base_version`, the version this copy
+ * was pulled from or last deployed as, or undefined when it records none (a
+ * copy made before the check existed, or one with no `juno` block at all).
  */
 export async function readProject(cwd = process.cwd()) {
   const manifest = await readManifest(cwd);
@@ -18,14 +25,61 @@ export async function readProject(cwd = process.cwd()) {
   if (Object.keys(files).length === 0) {
     throw new UserError(`no TypeScript sources found under ${SOURCE_DIR}/`);
   }
+  const packageJSON = await readOptional(join(cwd, PACKAGE_JSON));
   return {
     manifest,
-    files,
-    packageJSON: await readOptional(join(cwd, 'package.json')),
+    files: { ...files, ...(await readTestFiles(cwd)) },
+    packageJSON,
     lockfile: await readOptional(join(cwd, 'package-lock.json')),
+    baseVersion: baseVersionOfText(packageJSON),
   };
 }
 
+/**
+ * readIntegrationBaseVersion is package.json's `juno.base_version`, or
+ * undefined: what `pull` diffs against without reading the sources.
+ */
+export async function readIntegrationBaseVersion(cwd) {
+  return baseVersionOfText(await readOptional(join(cwd, PACKAGE_JSON)));
+}
+
+/** `juno.base_version` of package.json's text, or undefined. */
+function baseVersionOfText(text) {
+  let pkg;
+  try {
+    pkg = JSON.parse(text);
+  } catch {
+    return undefined;
+  }
+  const base = pkg?.juno?.base_version;
+  return Number.isInteger(base) ? base : undefined;
+}
+
+/**
+ * updateIntegrationPackage rewrites package.json through `mutate`, keeping
+ * every key it does not touch (and their order). `juno` is handed over as an
+ * object even when the copy has none yet: an integration copy carries one only
+ * once it records a target or a base. A missing or unreadable package.json is
+ * left alone with a warning — no command here is the place to invent one.
+ * Returns whether it wrote.
+ */
+export async function updateIntegrationPackage(cwd, mutate, io) {
+  let pkg;
+  try {
+    pkg = JSON.parse(await readFile(join(cwd, PACKAGE_JSON), 'utf8'));
+  } catch {
+    pkg = null;
+  }
+  if (pkg === null || typeof pkg !== 'object' || Array.isArray(pkg)) {
+    io.warn(`no readable ${PACKAGE_JSON} — it was not updated`);
+    return false;
+  }
+  if (pkg.juno === null || typeof pkg.juno !== 'object') pkg.juno = {};
+  mutate(pkg);
+  await writePackageJSON(cwd, pkg);
+  return true;
+}
+
 /**
  * The manifest as it sits on disk. The stamp in types/integration-env.d.ts
  * fingerprints these exact bytes, so both writing and verifying it go through
@@ -51,15 +105,29 @@ export async function readManifest(cwd = process.cwd()) {
 }
 
 /** Walks src/ and returns repo-relative POSIX paths → content. */
-export async function readSourceFiles(cwd = process.cwd()) {
-  const root = join(cwd, SOURCE_DIR);
+export function readSourceFiles(cwd = process.cwd()) {
+  return readSourceTree(cwd, SOURCE_DIR);
+}
+
+/**
+ * readTestFiles is readSourceFiles for test/: the same .ts and .json rule,
+ * because Juno stores tests beside the sources under the same path rules.
+ * Every kind's working copy sends them; none requires them.
+ */
+export function readTestFiles(cwd = process.cwd()) {
+  return readSourceTree(cwd, TEST_DIR);
+}
+
+/** readSourceTree walks dir for .ts and .json files, by repo-relative POSIX path. */
+async function readSourceTree(cwd, dir) {
+  const root = join(cwd, dir);
   const files = {};
   async function walk(dir) {
     let entries;
     try {
       entries = await readdir(dir, { withFileTypes: true });
     } catch {
-      return; // no src/ at all; the caller reports it
+      return; // no such directory at all; the caller reports a missing src/
     }
     for (const entry of entries) {
       const full = join(dir, entry.name);

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,87 @@
+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();
+
+  const watcher = watchPaths(paths, () => void iteration());
+  await new Promise((resolve) => {
+    process.once('SIGINT', () => {
+      watcher.close();
+      resolve();
+    });
+  });
+  return 0;
+}
+
+/**
+ * watchPaths calls onChange once edits to `paths` (`{path, recursive?,
+ * filter?}`) have settled for `debounceMs`, so an editor's save-and-rename is
+ * one call. `filter(filename)`, when given, drops an event its path does not
+ * want — the way to watch one file in a directory, since a watch on the file
+ * itself loses it the first time an editor saves by renaming over it. A path
+ * that does not exist is not watched: an app's public/ may be absent, since
+ * nothing but the page is required. Returns `{close()}`, which also drops a
+ * pending call.
+ */
+export function watchPaths(
+  paths,
+  onChange,
+  { debounceMs = WATCH_DEBOUNCE_MS } = {}
+) {
+  let timer = null;
+  const schedule = () => {
+    if (timer) clearTimeout(timer);
+    timer = setTimeout(() => {
+      timer = null;
+      onChange();
+    }, debounceMs);
+  };
+
+  const watchers = [];
+  for (const { path, recursive = false, filter } of paths) {
+    try {
+      const w = watch(path, { recursive }, (_event, filename) => {
+        if (!filter || filter(filename == null ? null : String(filename))) {
+          schedule();
+        }
+      });
+      // A watched directory removed mid-session is not worth a crash.
+      w.on('error', () => w.close());
+      watchers.push(w);
+    } catch (err) {
+      if (err.code !== 'ENOENT') throw err;
+    }
+  }
+  return {
+    close() {
+      if (timer) clearTimeout(timer);
+      timer = null;
+      for (const w of watchers) w.close();
+    },
+  };
+}