@junoflow/cli 0.3.0 → 0.6.0

package/src/index.js

@@ -1,123 +1,554 @@
 import { parseArgs } from 'node:util';
 
-import { check } from './commands/check.js';
-import { deploy } from './commands/deploy.js';
-import { init } from './commands/init.js';
-import { pull } from './commands/pull.js';
-import { types } from './commands/types.js';
-import { verifyTypes } from './commands/verify-types.js';
-import { DiagnosticsError, UserError } from './errors.js';
+import {
+  AGENT_SKILL_INSTALL_USAGE,
+  agentSkillInstall,
+} from './commands/agent-skill-install.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';
+import {
+  CREDENTIAL_SET_USAGE,
+  credentialSet,
+} from './commands/credential-set.js';
+import { DEPLOY_USAGE, deploy } from './commands/deploy.js';
+import { FLOW_CHECK_USAGE, flowCheck } from './commands/flow-check.js';
+import { FLOW_DEPLOY_USAGE, flowDeploy } from './commands/flow-deploy.js';
+import {
+  FLOW_GEN_TYPES_USAGE,
+  flowGenTypes,
+} from './commands/flow-gen-types.js';
+import { FLOW_INIT_USAGE, flowInit } from './commands/flow-init.js';
+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 { PULL_USAGE, pull } from './commands/pull.js';
+import { SKILL_USAGE, skill } from './commands/skill.js';
+import {
+  SESSION_APPROVE_USAGE,
+  sessionApprove,
+} from './commands/session-approve.js';
+import { runTool } from './commands/tool.js';
+import { VERIFY_TYPES_USAGE, verifyTypes } from './commands/verify-types.js';
+import {
+  ConflictError,
+  DiagnosticsError,
+  UnreachableError,
+  UsageError,
+  UserError,
+} from './errors.js';
 import { formatDiagnostics } from './diagnostics.js';
+import {
+  EXIT_CONFLICT,
+  EXIT_FAILURE,
+  EXIT_OK,
+  EXIT_UNREACHABLE,
+  EXIT_USAGE,
+} from './exit.js';
+import {
+  groupHelp,
+  nonToolHelp,
+  verbHelp,
+  WORKING_COPY_HEADING,
+  workingCopyListing,
+} from './help.js';
+import { closest, closestByVerb, levenshtein } from './suggest.js';
+import { groupOf, normalizeVerb, rowFor, rows } from './verbs.js';
 
-const COMMANDS = {
-  init,
-  types,
-  'verify-types': verifyTypes,
-  check,
-  deploy,
-  pull,
+const URL_OPTION = { url: { type: 'string' } };
+
+/**
+ * The verbs.json rows that call no tool, by command. A row is dispatchable
+ * only once it has a handler here; until then the CLI treats it as unknown
+ * rather than advertising a command it cannot run.
+ */
+const NON_TOOL = {
+  skill: {
+    run: skill,
+    options: { ...URL_OPTION, json: { type: 'boolean', default: false } },
+    usage: SKILL_USAGE,
+  },
+  ask: {
+    run: ask,
+    options: {
+      ...URL_OPTION,
+      session: { type: 'string' },
+      wait: { type: 'string' },
+    },
+    usage: ASK_USAGE,
+  },
+  'session approve': {
+    run: sessionApprove,
+    options: { ...URL_OPTION, wait: { type: 'string' } },
+    usage: SESSION_APPROVE_USAGE,
+  },
+  'credential set': {
+    run: credentialSet,
+    options: {
+      ...URL_OPTION,
+      name: { type: 'string' },
+      description: { type: 'string' },
+    },
+    usage: CREDENTIAL_SET_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,
+  },
+};
+
+/**
+ * The working-copy commands: verbs.json rows with `working_copy: true`, which
+ * act on the project in the current directory rather than on the instance
+ * (plan-external-agents-flows-as-files.md, Decision 11). Like NON_TOOL, a row
+ * is dispatchable only once it has a handler here. `positional` is true only
+ * for `init`, which names what to make; every other one refuses a positional
+ * (see runRow), because the working copy, not an argument, says what it acts
+ * on.
+ */
+const WORKING_COPY = {
+  'flow init': {
+    run: flowInit,
+    options: { ...URL_OPTION, here: { type: 'boolean', default: false } },
+    usage: FLOW_INIT_USAGE,
+    positional: true,
+  },
+  'flow gen-types': {
+    run: flowGenTypes,
+    options: URL_OPTION,
+    usage: FLOW_GEN_TYPES_USAGE,
+  },
+  'flow check': {
+    run: flowCheck,
+    options: {
+      ...URL_OPTION,
+      'skip-local': { type: 'boolean', default: false },
+      json: { type: 'boolean', default: false },
+    },
+    usage: FLOW_CHECK_USAGE,
+  },
+  'flow deploy': {
+    run: flowDeploy,
+    options: {
+      ...URL_OPTION,
+      watch: { type: 'boolean', default: false },
+      force: { type: 'boolean', default: false },
+      json: { type: 'boolean', default: false },
+    },
+    usage: FLOW_DEPLOY_USAGE,
+  },
+  'flow pull': {
+    run: flowPull,
+    options: { ...URL_OPTION, force: { type: 'boolean', default: false } },
+    usage: FLOW_PULL_USAGE,
+  },
+  'integration init': {
+    run: init,
+    options: {
+      ...URL_OPTION,
+      name: { type: 'string' },
+      here: { type: 'boolean', default: false },
+    },
+    usage: INIT_USAGE,
+    positional: true,
+  },
+  'integration gen-types': {
+    run: genTypes,
+    options: URL_OPTION,
+    usage: GEN_TYPES_USAGE,
+  },
+  'integration verify-types': {
+    run: verifyTypes,
+    options: {},
+    usage: VERIFY_TYPES_USAGE,
+  },
+  // check and deploy keep --id: deploy under a different install id than the
+  // manifest's. pull keeps it too, to pull such an install back.
+  'integration check': {
+    run: check,
+    options: {
+      ...URL_OPTION,
+      id: { type: 'string' },
+      'skip-local': { type: 'boolean', default: false },
+      json: { type: 'boolean', default: false },
+    },
+    usage: CHECK_USAGE,
+  },
+  'integration deploy': {
+    run: deploy,
+    options: {
+      ...URL_OPTION,
+      id: { type: 'string' },
+      watch: { type: 'boolean', default: false },
+      json: { type: 'boolean', default: false },
+    },
+    usage: DEPLOY_USAGE,
+  },
+  'integration pull': {
+    run: pull,
+    options: {
+      ...URL_OPTION,
+      id: { type: 'string' },
+      force: { type: 'boolean', default: false },
+    },
+    usage: PULL_USAGE,
+  },
 };
 
-const USAGE = `juno — develop Juno integrations
+/** The handler of a non-tool row, working-copy or not, or undefined. */
+function handlerFor(row) {
+  if (row.tool) return undefined;
+  const table = row.working_copy ? WORKING_COPY : NON_TOOL;
+  return Object.hasOwn(table, row.command) ? table[row.command] : undefined;
+}
+
+/**
+ * The rows the CLI can run: every tool row, and the non-tool and
+ * working-copy rows above.
+ */
+const DISPATCHABLE = rows.filter((row) => row.tool || handlerFor(row));
+const GROUPS = new Set(DISPATCHABLE.map(groupOf).filter(Boolean));
+
+function dispatchable(command) {
+  const row = rowFor(command);
+  return row && DISPATCHABLE.includes(row) ? row : undefined;
+}
+
+const USAGE = `juno — operate a Juno instance, and develop flows and integrations 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.
 
-Commands:
-  init <name>      scaffold a new integration project from a Juno
-  types            generate types/ from manifest.json
-  verify-types     check types/ still matches manifest.json (offline)
-  check            typecheck and lint locally, then validate against a Juno
-  deploy [--watch] upload, verify, and activate a new version
-  pull             write back the manifest and sources Juno holds
-
-Options:
-  --url <url>      the Juno instance; else $JUNO_URL, else package.json juno.target
-  --name <name>    address an install under a different name than the manifest
-  --watch          deploy on every save (deploy only)
-  --force          overwrite a dirty working tree (pull only)
-  --here           scaffold into the current directory (init only)
-  --skip-local     skip the local tsc/eslint pass (check only)
-  -h, --help       this
+${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>).
 `;
 
 /**
  * run is the whole CLI, injectable so the tests drive it without spawning a
- * process: io carries cwd and the three output streams, and a command may be
- * handed a client instead of building one from a URL.
+ * process: io carries cwd, env, the TTY bit, stdin and the three output
+ * streams, and a command may be handed a client instead of building one from
+ * a URL. It returns the exit code (exit.js).
  */
 export async function run(argv, io = defaultIO()) {
-  const [command, ...rest] = argv;
-
-  if (
-    !command ||
-    command === '--help' ||
-    command === '-h' ||
-    command === 'help'
-  ) {
+  try {
+    return await dispatch(argv, io);
+  } catch (err) {
+    // Diagnostics print as file:line:col so an editor can click through; a
+    // UserError is a sentence about their input, and neither deserves a stack.
+    if (err instanceof DiagnosticsError) {
+      io.error(formatDiagnostics(err.diagnostics));
+      io.error(`\n${err.diagnostics.length} problem(s): ${err.message}`);
+      return EXIT_FAILURE;
+    }
+    if (err instanceof ConflictError) {
+      io.error(err.message);
+      return EXIT_CONFLICT;
+    }
+    if (err instanceof UsageError) {
+      io.error(err.message);
+      return EXIT_USAGE;
+    }
+    if (err instanceof UnreachableError) {
+      io.error(err.message);
+      return EXIT_UNREACHABLE;
+    }
+    if (err instanceof UserError) {
+      io.error(err.message);
+      return EXIT_FAILURE;
+    }
+    throw err;
+  }
+}
+
+/**
+ * dispatch is two-level: the first word is a top-level row (`discover`) or a
+ * group, and a group's second word is the verb. A
+ * leading `--url` is accepted before the first word, so
+ * `juno --url <u> state get x` reads the way an alias would write it.
+ */
+async function dispatch(argv, io) {
+  const { url, rest } = leadingURL(argv);
+  const [first, ...tail] = rest;
+
+  if (!first || first === '--help' || first === '-h' || first === 'help') {
     io.log(USAGE);
-    return command ? 0 : 1;
+    return first ? EXIT_OK : EXIT_USAGE;
   }
-  const handler = COMMANDS[command];
-  if (!handler) {
-    io.error(`unknown command: ${command}\n`);
-    io.error(USAGE);
-    return 1;
+
+  const top = dispatchable(first);
+  if (top) return runRow(top, tail, url, io);
+
+  if (GROUPS.has(first)) {
+    const [verb, ...args] = tail;
+    // `juno state` alone is its help, as a usage error: the person has not
+    // said what to do yet.
+    if (!verb || verb.startsWith('-')) {
+      return runCommand(
+        { options: URL_OPTION },
+        tail,
+        url,
+        io,
+        (parsed) => showGroupHelp(first, parsed, io, EXIT_OK),
+        (parsed) => showGroupHelp(first, parsed, io, EXIT_USAGE)
+      );
+    }
+    const row = dispatchable(`${first} ${normalizeVerb(verb)}`);
+    if (!row) {
+      throw unknownCommand(`${first} ${verb}`, [
+        `${first} ${normalizeVerb(verb)}`,
+      ]);
+    }
+    return runRow(row, args, url, io);
   }
 
+  const second = tail[0] && !tail[0].startsWith('-') ? tail[0] : null;
+  if (second) {
+    throw unknownTopLevel(`${first} ${second}`, first, [
+      `${first} ${normalizeVerb(second)}`,
+      first,
+    ]);
+  }
+  throw unknownTopLevel(first, first, [first]);
+}
+
+async function showGroupHelp(group, args, io, code) {
+  io.log(await groupHelp(group, DISPATCHABLE, handlerFor, args, io));
+  return code;
+}
+
+/** runRow runs one verbs.json row, a tool's or a non-tool command's. */
+function runRow(row, argv, url, io) {
+  if (!row.tool) {
+    const handler = handlerFor(row);
+    const run =
+      row.working_copy && !handler.positional
+        ? (args, io) => {
+            refusePositional(row, args);
+            return handler.run(args, io);
+          }
+        : handler.run;
+    return runCommand(
+      handler,
+      argv,
+      url,
+      io,
+      () => {
+        io.log(nonToolHelp(row, handler));
+        return EXIT_OK;
+      },
+      run
+    );
+  }
+
+  const options = {
+    ...URL_OPTION,
+    input: { type: 'string' },
+    jq: { type: 'string' },
+  };
+  for (const [flag, spec] of Object.entries(row.flags ?? {})) {
+    options[flag] = { type: 'string', multiple: spec.multiple === true };
+  }
+  return runCommand(
+    { run: (args) => runTool(row, args, io), options },
+    argv,
+    url,
+    io,
+    async (args) => {
+      io.log(await verbHelp(row, args, io));
+      return EXIT_OK;
+    }
+  );
+}
+
+/**
+ * runCommand parses a command's own flags (plus --help) and runs it, or its
+ * help. A `--url` given before the command word fills in when the command's
+ * own is absent. `run` defaults to the command's own; a group without a verb
+ * passes its help instead.
+ */
+async function runCommand(command, argv, url, io, help, run = command.run) {
   let parsed;
   try {
     parsed = parseArgs({
-      args: rest,
+      args: argv,
       allowPositionals: true,
       options: {
-        url: { type: 'string' },
-        name: { type: 'string' },
-        watch: { type: 'boolean', default: false },
-        force: { type: 'boolean', default: false },
-        here: { type: 'boolean', default: false },
-        'skip-local': { type: 'boolean', default: false },
+        ...command.options,
         help: { type: 'boolean', short: 'h', default: false },
       },
     });
   } catch (err) {
-    io.error(err.message);
-    return 1;
-  }
-  if (parsed.values.help) {
-    io.log(USAGE);
-    return 0;
+    throw new UsageError(err.message);
   }
 
   const args = { ...parsed.values, _: parsed.positionals, client: io.client };
-  try {
-    return (await handler(args, io)) ?? 0;
-  } catch (err) {
-    // Diagnostics print as file:line:col so an editor can click through; a
-    // UserError is a sentence about their input, and neither deserves a stack.
-    if (err instanceof DiagnosticsError) {
-      io.error(formatDiagnostics(err.diagnostics));
-      io.error(`\n${err.diagnostics.length} problem(s): ${err.message}`);
-      return 1;
-    }
-    if (err instanceof UserError) {
-      io.error(err.message);
-      return 1;
+  if (url !== undefined && args.url === undefined) args.url = url;
+  if (parsed.values.help) return help(args);
+  return (await run(args, io)) ?? EXIT_OK;
+}
+
+/**
+ * refusePositional: a working-copy command acts on the project in the current
+ * directory, so `juno flow deploy porch-light` is a usage error that says so
+ * and points at the command that makes a working copy of porch-light —
+ * rather than deploying whatever directory it happens to run in.
+ */
+function refusePositional(row, args) {
+  if (args._.length === 0) return;
+  const group = groupOf(row);
+  throw new UsageError(
+    `juno ${row.command} takes no argument: it acts on the working copy in ` +
+      'the current directory. ' +
+      `To get a working copy of "${args._[0]}", run \`juno ${group} init ${args._[0]}\` ` +
+      'and run this from inside it.'
+  );
+}
+
+/** leadingURL takes `--url <u>` / `--url=<u>` off the front of argv. */
+function leadingURL(argv) {
+  let url;
+  let i = 0;
+  while (i < argv.length) {
+    if (argv[i] === '--url' && i + 1 < argv.length) {
+      url = argv[i + 1];
+      i += 2;
+    } else if (argv[i].startsWith('--url=')) {
+      url = argv[i].slice('--url='.length);
+      i += 1;
+    } else {
+      break;
     }
-    throw err;
   }
+  return { url, rest: argv.slice(i) };
+}
+
+/**
+ * unknownCommand names what was typed and, when one is close, the command
+ * that was probably meant — rather than the whole help, which buries the fix.
+ */
+function unknownCommand(words, attempts) {
+  const candidates = [...DISPATCHABLE.map((row) => row.command), ...GROUPS];
+  const guess = closest(attempts, candidates);
+  const hint = guess ? `did you mean "juno ${guess}"?` : 'see juno --help';
+  return new UsageError(`unknown command "juno ${words}"; ${hint}`);
+}
+
+/**
+ * unknownTopLevel is unknownCommand for a first word that is neither a
+ * command nor a group. It may be a verb typed without its group: a bare
+ * `deploy` is nearer `juno integration deploy` (and `juno flow deploy`) than
+ * any top-level command, and the integration commands lived at the top level until
+ * 0.5.0. A verb match wins only when it is strictly nearer than every whole
+ * command, so a mistyped group (`juno stat get`) still finds its command.
+ */
+function unknownTopLevel(words, first, attempts) {
+  const commands = DISPATCHABLE.map((row) => row.command);
+  const whole = closest(attempts, [...commands, ...GROUPS]);
+  const wholeDistance = whole
+    ? Math.min(...attempts.map((a) => levenshtein(a, whole)))
+    : Infinity;
+  const byVerb = closestByVerb(normalizeVerb(first), commands);
+  if (byVerb.commands.length === 0 || byVerb.distance >= wholeDistance) {
+    return unknownCommand(words, attempts);
+  }
+  const quoted = byVerb.commands.map((c) => `"juno ${c}"`);
+  const list =
+    quoted.length === 1
+      ? quoted[0]
+      : `${quoted.slice(0, -1).join(', ')} or ${quoted.at(-1)}`;
+  return new UsageError(
+    `unknown command "juno ${words}"; did you mean ${list}?`
+  );
 }
 
 export function defaultIO() {
   return {
     cwd: process.cwd(),
+    env: process.env,
     client: null,
+    isTTY: process.stdout.isTTY === true,
+    stdinIsTTY: process.stdin.isTTY === true,
+    readStdin,
+    readSecret,
     log: (msg) => process.stdout.write(`${msg}\n`),
+    write: (text) => process.stdout.write(text),
     warn: (msg) => process.stderr.write(`${msg}\n`),
     error: (msg) => process.stderr.write(`${msg}\n`),
   };
 }
 
 export { JunoClient } from './api.js';
-export { DiagnosticsError, UserError } from './errors.js';
+export {
+  DiagnosticsError,
+  UnreachableError,
+  UsageError,
+  UserError,
+} from './errors.js';
 export { resolveTarget } from './target.js';
 export { readProject } from './project.js';
+
+/** readStdin reads the whole of stdin; only `--input -` ever calls it. */
+async function readStdin() {
+  const chunks = [];
+  for await (const chunk of process.stdin) chunks.push(chunk);
+  return Buffer.concat(chunks).toString('utf8');
+}
+
+/**
+ * readSecret prompts on stderr and reads one line from the terminal with echo
+ * off: raw mode, so no keystroke is echoed, restored before it returns.
+ * Backspace edits; Enter or Ctrl-D ends the line; Ctrl-C restores the mode
+ * and exits 130, as an interrupted command does. Only `credential set` calls
+ * it, and only once stdin is known to be a TTY.
+ */
+function readSecret(prompt) {
+  const stdin = process.stdin;
+  return new Promise((resolve) => {
+    let value = [];
+    const wasRaw = stdin.isRaw;
+    const done = () => {
+      stdin.off('data', onData);
+      stdin.setRawMode(wasRaw);
+      stdin.pause();
+      process.stderr.write('\n');
+    };
+    const onData = (chunk) => {
+      for (const ch of chunk) {
+        if (ch === '\u0003') {
+          done();
+          process.exit(130);
+        }
+        if (ch === '\r' || ch === '\n' || ch === '\u0004') {
+          done();
+          resolve(value.join(''));
+          return;
+        }
+        if (ch === '\u007f' || ch === '\b') value = value.slice(0, -1);
+        else value.push(ch);
+      }
+    };
+    process.stderr.write(prompt);
+    stdin.setEncoding('utf8');
+    stdin.setRawMode(true);
+    stdin.on('data', onData);
+    stdin.resume();
+  });
+}

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