@junoflow/cli 0.3.0 → 0.6.0

package/src/commands/ask.js

@@ -0,0 +1,60 @@
+import { randomUUID } from 'node:crypto';
+
+import { connect } from '../api.js';
+import { UsageError } from '../errors.js';
+import { converse, DEFAULT_WAIT_SECONDS, finish } from '../prompt.js';
+
+export const ASK_USAGE =
+  'juno ask ["<prompt>"] [--session <id>] [--wait <seconds>]';
+
+/**
+ * `juno ask` is the CLI for the Agent Prompt API: it prompts the in-app
+ * assistant and prints the turn's final event. Off a TTY each call is one
+ * `stream: false` request that waits up to --wait seconds; on one it streams
+ * and writes progress to stderr. The exit code is the outcome (prompt.js).
+ *
+ * `--session <id>` resumes a conversation; with no prompt it observes, which
+ * is how to keep waiting on a turn that answered `pending`. A new
+ * conversation's id is minted here, so a transport retry resumes it rather
+ * than starting a second.
+ */
+export async function ask(args, io) {
+  const prompt = args._.length ? args._.join(' ') : undefined;
+  if (prompt === undefined && args.session === undefined) {
+    throw new UsageError(
+      `juno ask needs a prompt, or --session <id> to observe a session\nusage: ${ASK_USAGE}`
+    );
+  }
+  if (prompt !== undefined && !prompt.trim()) {
+    throw new UsageError('the prompt is empty');
+  }
+  // To a session awaiting approval, "approve" lets a tool call through. That
+  // is `juno session approve`, so a rule allowing `juno ask` cannot do it.
+  if (prompt?.trim().toLowerCase() === 'approve') {
+    throw new UsageError(
+      'juno ask does not approve tool calls; use: juno session approve ' +
+        (args.session ?? '<session-id>')
+    );
+  }
+
+  const stream = io.isTTY;
+  const body = { session_id: args.session ?? randomUUID() };
+  if (prompt !== undefined) {
+    body.message = prompt;
+    body.message_id = randomUUID();
+  }
+  if (!stream) body.wait_timeout_seconds = waitSeconds(args.wait);
+
+  const { client } = await connect(args, io);
+  const outcome = await converse(client, body, { stream, io });
+  return finish(outcome, body.session_id, io);
+}
+
+/** waitSeconds parses --wait; the server bounds it (1–600) and says so. */
+export function waitSeconds(flag) {
+  if (flag === undefined) return DEFAULT_WAIT_SECONDS;
+  if (!/^\d+$/.test(flag) || Number(flag) < 1) {
+    throw new UsageError(`--wait takes a number of seconds, got "${flag}"`);
+  }
+  return Number(flag);
+}

package/src/commands/check.js

@@ -1,19 +1,26 @@
 import { spawn } from 'node:child_process';
 import { join } from 'node:path';
 
-import { JunoClient } from '../api.js';
-import { UserError } from '../errors.js';
+import { clientName, JunoClient } from '../api.js';
+import { printDiagnosticsJSON, printJSON } from '../diagnostics.js';
+import { DiagnosticsError, UserError } from '../errors.js';
 import { readProject } from '../project.js';
 import { resolveTarget } from '../target.js';
 import { verifyTypes } from './verify-types.js';
 
+export const CHECK_USAGE =
+  'juno integration check [--skip-local] [--id <id>] [--json]';
+
 /**
- * `juno check` — the offline checks, then the ones only a Juno can answer.
+ * `juno integration check` — the offline checks, then the ones only a Juno can answer.
  *
  * tsc and eslint run locally against the committed types; reserved names,
  * cross-surface collisions and JSON Schema compilation need the server, so
  * they go through ingest?dry_run=1, which stores nothing and is safe to point
  * at a production instance.
+ *
+ * --json prints the route's body (or the 422's diagnostics) on stdout and
+ * nothing else; the local tools' own output goes to stderr.
  */
 export async function check(argv, io) {
   let failed = false;
@@ -22,7 +29,8 @@ export async function check(argv, io) {
     // Before tsc, deliberately: type-checking against types/ says nothing if
     // types/ describes a manifest that is no longer on disk.
     try {
-      await verifyTypes(argv, io);
+      // verify-types reports success on stdout, which --json reserves.
+      await verifyTypes(argv, argv.json ? { ...io, log: io.warn } : io);
     } catch (err) {
       if (!(err instanceof UserError)) throw err;
       io.error(err.message);
@@ -32,7 +40,9 @@ export async function check(argv, io) {
       ['typecheck', 'tsc', ['--noEmit']],
       ['lint', 'eslint', ['.']],
     ]) {
-      const code = await runLocal(bin, args, io);
+      const code = await runLocal(bin, args, io, {
+        quietStdout: argv.json,
+      });
       if (code === SKIPPED) {
         io.warn(`${label}: ${bin} is not installed — run npm install`);
         continue;
@@ -41,30 +51,48 @@ export async function check(argv, io) {
     }
   }
 
-  const target = await resolveTarget({ url: argv.url, cwd: io.cwd });
-  const client = argv.client ?? new JunoClient(target);
-  const project = await readProject(io.cwd);
-  const result = await client.ingest(project, {
-    dryRun: true,
-    name: argv.name,
+  const target = await resolveTarget({
+    url: argv.url,
+    cwd: io.cwd,
+    env: io.env,
   });
-  for (const warning of result.warnings ?? []) io.warn(`warning: ${warning}`);
-  io.log(`${result.name}: manifest and sources verified against ${target}`);
+  const client =
+    argv.client ?? new JunoClient(target, { client: clientName(io.env) });
+  const project = await readProject(io.cwd);
+  let result;
+  try {
+    result = await client.ingest(project, { dryRun: true, id: argv.id });
+  } catch (err) {
+    if (argv.json && err instanceof DiagnosticsError) {
+      return printDiagnosticsJSON(err, io);
+    }
+    throw err;
+  }
+
+  if (argv.json) {
+    printJSON(result, io);
+  } else {
+    for (const w of result.warnings ?? []) io.warn(`warning: ${w}`);
+    io.log(`${result.id}: manifest and sources verified against ${target}`);
+  }
 
   return failed ? 1 : 0;
 }
 
-const SKIPPED = -1;
+export const SKIPPED = -1;
 
 /**
  * Runs a local devtool from node_modules/.bin. Its output goes straight to the
  * terminal: tsc and eslint already print file:line:col, and reformatting them
  * would only lose the column.
  */
-function runLocal(bin, args, io) {
+export function runLocal(bin, args, io, { quietStdout = false } = {}) {
   const path = join(io.cwd, 'node_modules', '.bin', bin);
+  // quietStdout sends the tool's stdout to stderr, for a --json run whose
+  // stdout must carry the JSON and nothing else.
+  const stdio = quietStdout ? ['inherit', 2, 'inherit'] : 'inherit';
   return new Promise((resolve) => {
-    const child = spawn(path, args, { cwd: io.cwd, stdio: 'inherit' });
+    const child = spawn(path, args, { cwd: io.cwd, stdio });
     child.on('error', () => resolve(SKIPPED));
     child.on('close', (code) => resolve(code ?? 1));
   });

package/src/commands/config.js

@@ -0,0 +1,26 @@
+import { readUserConfig, writeUserConfig } from '../config.js';
+import { UsageError } from '../errors.js';
+import { normalizeTarget } from '../target.js';
+
+export const CONFIG_SET_USAGE = 'juno config set url <url>';
+
+/**
+ * `juno config set url <url>` writes the user config file, the last place
+ * resolveTarget looks. `url` is the only key; it is normalised the way every
+ * other source is, so what lands in the file is what a request would use.
+ */
+export async function configSet(argv, io) {
+  const [key, value, ...extra] = argv._;
+  const usage = `usage: ${CONFIG_SET_USAGE}`;
+  if (key === undefined) throw new UsageError(usage);
+  if (key !== 'url') {
+    throw new UsageError(`unknown config key "${key}"; ${usage}`);
+  }
+  if (value === undefined || extra.length) throw new UsageError(usage);
+
+  const url = normalizeTarget(value);
+  const current = await readUserConfig(io.env);
+  const path = await writeUserConfig(io.env, { ...current, url });
+  io.warn(`wrote ${path}`);
+  return 0;
+}

package/src/commands/credential-set.js

@@ -0,0 +1,68 @@
+import { connect } from '../api.js';
+import { UsageError } from '../errors.js';
+
+export const CREDENTIAL_SET_USAGE =
+  'juno credential set <id> [--name <name>] [--description <text>]';
+
+/**
+ * `juno credential set <id>` stores a secret a person types at a terminal.
+ * It goes through the REST credential routes rather than the tool gateway,
+ * which deliberately serves no write_credential: a secret an agent types
+ * lands in its transcript. For the same reason it refuses to run unless stdin
+ * is a TTY, so nothing can pipe a value in, and the value is read with echo
+ * off and never printed.
+ *
+ * An existing credential keeps its name and description unless --name or
+ * --description overrides them; a new one needs both.
+ */
+export async function credentialSet(args, io) {
+  const [id, ...extra] = args._;
+  if (id === undefined || extra.length) {
+    throw new UsageError(`usage: ${CREDENTIAL_SET_USAGE}`);
+  }
+  if (!io.stdinIsTTY) {
+    throw new UsageError(
+      'juno credential set reads the secret from a terminal, and stdin is not ' +
+        'one. A person must run it, e.g. as ' +
+        `\`! juno credential set ${id}\` inside Claude Code.`
+    );
+  }
+
+  const { client } = await connect(args, io);
+  const existing = await client.getCredentialMeta(id);
+
+  // Everything that can refuse the command does so before the prompt, so
+  // nobody types a secret into a command that was never going to store it.
+  if (!existing) {
+    const missing = ['name', 'description']
+      .filter((flag) => args[flag] === undefined)
+      .map((flag) => `--${flag}`);
+    if (missing.length) {
+      throw new UsageError(
+        `credential "${id}" does not exist; creating it needs --name and ` +
+          `--description (missing: ${missing.join(', ')})`
+      );
+    }
+  }
+
+  const value = await io.readSecret(`Secret for credential "${id}": `);
+  if (!value) throw new UsageError('an empty secret was not stored');
+
+  if (existing) {
+    await client.updateCredential(id, {
+      name: args.name ?? existing.name,
+      description: args.description ?? existing.description,
+      value,
+    });
+    io.warn(`updated credential "${id}"`);
+  } else {
+    await client.createCredential({
+      id,
+      name: args.name,
+      description: args.description,
+      value,
+    });
+    io.warn(`created credential "${id}"`);
+  }
+  return 0;
+}

package/src/commands/deploy.js

@@ -1,30 +1,45 @@
-import { watch } from 'node:fs';
 import { join } from 'node:path';
 
-import { JunoClient } from '../api.js';
+import { clientName, JunoClient } from '../api.js';
+import { printDiagnosticsJSON, printJSON } from '../diagnostics.js';
 import { DiagnosticsError } from '../errors.js';
 import { readManifestRaw, readProject, writeTypes } from '../project.js';
 import { resolveTarget } from '../target.js';
 import { stampTypeFiles } from '../stamp.js';
-import { formatDiagnostics } from '../diagnostics.js';
-import { pickTypeFiles } from './types.js';
+import { pickTypeFiles } from './gen-types.js';
+import { deployOnChange } from '../watch.js';
 
-/** How long to wait for edits to settle before redeploying. */
-const WATCH_DEBOUNCE_MS = 200;
+export const DEPLOY_USAGE =
+  'juno integration deploy [--watch] [--id <id>] [--json]';
 
 /**
- * `juno deploy [--watch]` — upload the working copy, verify, activate.
+ * `juno integration deploy [--watch]` — upload the working copy, verify, activate.
  *
  * The response carries the regenerated types, so a deploy keeps the committed
  * types/ honest without a second round trip that could answer for a different
  * manifest.
+ *
+ * --json prints the route's body (or the 422's diagnostics) on stdout instead
+ * of the summary line, for CI.
  */
 export async function deploy(argv, io) {
-  const target = await resolveTarget({ url: argv.url, cwd: io.cwd });
-  const client = argv.client ?? new JunoClient(target);
+  const target = await resolveTarget({
+    url: argv.url,
+    cwd: io.cwd,
+    env: io.env,
+  });
+  const client =
+    argv.client ?? new JunoClient(target, { client: clientName(io.env) });
 
   if (!argv.watch) {
-    await deployOnce(client, argv, io, target);
+    try {
+      await deployOnce(client, argv, io, target);
+    } catch (err) {
+      if (argv.json && err instanceof DiagnosticsError) {
+        return printDiagnosticsJSON(err, io);
+      }
+      throw err;
+    }
     return 0;
   }
   return watchAndDeploy(client, argv, io, target);
@@ -32,16 +47,20 @@ export async function deploy(argv, io) {
 
 async function deployOnce(client, argv, io, target) {
   const project = await readProject(io.cwd);
-  const result = await client.ingest(project, { name: argv.name });
+  const result = await client.ingest(project, { id: argv.id });
   // Stamped against the manifest this deploy was built from, so the watch loop
-  // leaves a tree that `juno verify-types` accepts.
+  // leaves a tree that `juno integration verify-types` accepts.
   const written = await writeTypes(
     stampTypeFiles(pickTypeFiles(result.types), await readManifestRaw(io.cwd)),
     io.cwd
   );
+  if (argv.json) {
+    printJSON(result, io);
+    return result;
+  }
   for (const warning of result.warnings ?? []) io.warn(`warning: ${warning}`);
   io.log(
-    `deployed ${result.name} v${result.version} to ${target} (${written.join(', ')})`
+    `deployed ${result.id} v${result.version} to ${target} (${written.join(', ')})`
   );
   return result;
 }
@@ -49,43 +68,15 @@ async function deployOnce(client, argv, io, target) {
 /**
  * Watch mode is the loop the whole design is for: edit the manifest, the types
  * regenerate, and the editor red-squiggles the method you have not written yet.
- * A failed deploy prints and keeps watching — the next save is the retry.
  */
-async function watchAndDeploy(client, argv, io, target) {
-  io.log(`watching ${io.cwd} — deploying to ${target}`);
-  await runWatchIteration(client, argv, io, target);
-
-  let timer = null;
-  const schedule = () => {
-    if (timer) clearTimeout(timer);
-    timer = setTimeout(() => {
-      timer = null;
-      void runWatchIteration(client, argv, io, target);
-    }, WATCH_DEBOUNCE_MS);
-  };
-
-  const watchers = [
-    watch(join(io.cwd, 'src'), { recursive: true }, schedule),
-    watch(join(io.cwd, 'manifest.json'), schedule),
-  ];
-  // Resolves only on SIGINT: watch mode ends when the author ends it.
-  await new Promise((resolve) => {
-    process.once('SIGINT', () => {
-      for (const w of watchers) w.close();
-      resolve();
-    });
+function watchAndDeploy(client, argv, io, target) {
+  return deployOnChange({
+    io,
+    target,
+    paths: [
+      { path: join(io.cwd, 'src'), recursive: true },
+      { path: join(io.cwd, 'manifest.json') },
+    ],
+    once: () => deployOnce(client, argv, io, target),
   });
-  return 0;
-}
-
-async function runWatchIteration(client, argv, io, target) {
-  try {
-    await deployOnce(client, argv, io, target);
-  } catch (err) {
-    if (err instanceof DiagnosticsError) {
-      io.error(formatDiagnostics(err.diagnostics));
-    } else {
-      io.error(err.message);
-    }
-  }
 }

package/src/commands/flow-check.js

@@ -0,0 +1,93 @@
+import { connect } from '../api.js';
+import { DiagnosticsError } from '../errors.js';
+import { readFlowProject } from '../flow-project.js';
+import { runLocal, SKIPPED } from './check.js';
+import { printDiagnosticsJSON, printJSON } from '../diagnostics.js';
+import { printWarnings } from './flow-deploy.js';
+
+export const FLOW_CHECK_USAGE = 'juno flow check [--skip-local] [--json]';
+
+/**
+ * `juno flow check` — local tsc and eslint, then a dry-run ingest: the same
+ * verification deploy runs (and the base_version check, so a stale copy is
+ * reported here before deploy hits it), with nothing committed. Safe to point
+ * at a production instance.
+ */
+export async function flowCheck(argv, io) {
+  const project = await readFlowProject(io.cwd);
+  let failed = false;
+
+  if (!argv['skip-local']) {
+    for (const [label, bin, args] of [
+      ['typecheck', 'tsc', ['--noEmit']],
+      ['lint', 'eslint', ['.']],
+    ]) {
+      const code = await runLocal(bin, args, io, {
+        quietStdout: argv.json,
+      });
+      if (code === SKIPPED) {
+        io.warn(`${label}: ${bin} is not installed — run npm install`);
+        continue;
+      }
+      if (code !== 0) failed = true;
+    }
+  }
+  warnOnDependencyDrift(project, io);
+
+  const { target, client } = await connect(argv, io);
+  let result;
+  try {
+    result = await client.ingestFlow(
+      {
+        flowId: project.flowId,
+        manifest: project.manifest,
+        flowTS: project.flowTS,
+        baseVersion: project.baseVersion,
+      },
+      { dryRun: true }
+    );
+  } catch (err) {
+    if (argv.json && err instanceof DiagnosticsError) {
+      return printDiagnosticsJSON(err, io);
+    }
+    throw err;
+  }
+
+  if (argv.json) {
+    printJSON(result, io);
+  } else {
+    printWarnings(result.warnings, io);
+    io.log(
+      `${result.flow_id}: manifest and flow.ts verified against ${target}`
+    );
+  }
+  return failed ? 1 : 0;
+}
+
+/**
+ * manifest.dependencies is what verify installs; package.json's dependencies
+ * are only there so a local `npm install` gives tsc the same modules. When the
+ * two disagree, local and server-side checks are checking different programs,
+ * so say which packages differ — and that the manifest is the one to edit.
+ */
+export function warnOnDependencyDrift(project, io) {
+  const declared = project.manifest?.dependencies ?? {};
+  const installed = project.packageJSON?.dependencies ?? {};
+  const names = [
+    ...new Set([...Object.keys(declared), ...Object.keys(installed)]),
+  ].sort();
+  const diffs = [];
+  for (const name of names) {
+    const a = declared[name];
+    const b = installed[name];
+    if (a === b) continue;
+    if (b === undefined) diffs.push(`${name} (only in manifest.json)`);
+    else if (a === undefined) diffs.push(`${name} (only in package.json)`);
+    else diffs.push(`${name} (manifest.json ${a}, package.json ${b})`);
+  }
+  if (diffs.length === 0) return;
+  io.warn(
+    `warning: manifest.json and package.json list different dependencies: ${diffs.join(', ')}. ` +
+      "Juno installs manifest.json's; add packages there, then copy them to package.json (or run `npm run pull` after deploying)."
+  );
+}

package/src/commands/flow-deploy.js

@@ -0,0 +1,107 @@
+import { join } from 'node:path';
+
+import { connect } from '../api.js';
+import { DiagnosticsError } from '../errors.js';
+import {
+  formatDiagnostic,
+  printDiagnosticsJSON,
+  printJSON,
+} from '../diagnostics.js';
+import {
+  FLOW_TS,
+  MANIFEST,
+  manifestText,
+  readFlowProject,
+  typeFiles,
+  updatePackageJSON,
+  writeFlowFiles,
+} from '../flow-project.js';
+import { deployOnChange } from '../watch.js';
+
+export const FLOW_DEPLOY_USAGE =
+  'juno flow deploy [--watch] [--force] [--json]';
+
+/**
+ * `juno flow deploy` — upload manifest.json and flow.ts to
+ * POST /api/flows/ingest, which verifies and commits them through the same
+ * core the in-app assistant's submit_code uses, and activates the version.
+ *
+ * It sends `juno.base_version`, so a flow edited elsewhere since this copy was
+ * pulled is a 409 (exit 4) rather than a silent overwrite; --force sends none
+ * and replaces whatever is active. On success it writes back what the server
+ * now holds: the canonical manifest, both .d.ts files, and the new
+ * base_version.
+ */
+export async function flowDeploy(argv, io) {
+  const { target, client } = await connect(argv, io);
+  if (!argv.watch) {
+    return deployOnce(client, argv, io, target);
+  }
+
+  // A deploy writes manifest.json back, which the watcher sees. Remembering
+  // what was last deployed makes that echo — and any save that changed
+  // nothing — a no-op instead of another version.
+  let last = null;
+  return deployOnChange({
+    io,
+    target,
+    paths: [{ path: join(io.cwd, FLOW_TS) }, { path: join(io.cwd, MANIFEST) }],
+    once: async () => {
+      const project = await readFlowProject(io.cwd);
+      const key = JSON.stringify([project.manifestRaw, project.flowTS]);
+      if (key === last) return;
+      const after = await deployProject(client, project, argv, io, target);
+      last = JSON.stringify([after.manifestRaw, project.flowTS]);
+    },
+  });
+}
+
+async function deployOnce(client, argv, io, target) {
+  const project = await readFlowProject(io.cwd);
+  try {
+    await deployProject(client, project, argv, io, target);
+  } catch (err) {
+    if (argv.json && err instanceof DiagnosticsError) {
+      return printDiagnosticsJSON(err, io);
+    }
+    throw err;
+  }
+  return 0;
+}
+
+async function deployProject(client, project, argv, io, target) {
+  const result = await client.ingestFlow({
+    flowId: project.flowId,
+    manifest: project.manifest,
+    flowTS: project.flowTS,
+    baseVersion: argv.force ? undefined : project.baseVersion,
+  });
+
+  const manifestRaw = manifestText(result.manifest);
+  const written = await writeFlowFiles(io.cwd, {
+    [MANIFEST]: manifestRaw,
+    ...typeFiles(result.types),
+  });
+  if (project.baseVersion !== result.version) {
+    await updatePackageJSON(io.cwd, (pkg) => {
+      pkg.juno.base_version = result.version;
+    });
+    written.push('package.json');
+  }
+
+  if (argv.json) {
+    printJSON(result, io);
+  } else {
+    printWarnings(result.warnings, io);
+    const files = written.length ? ` (${written.sort().join(', ')})` : '';
+    io.log(
+      `deployed ${result.flow_id} v${result.version} to ${target}${files}`
+    );
+  }
+  return { manifestRaw };
+}
+
+/** A route's warnings, each as a diagnostic line with a `warning: ` prefix. */
+export function printWarnings(warnings, io) {
+  for (const w of warnings ?? []) io.warn(`warning: ${formatDiagnostic(w)}`);
+}

package/src/commands/flow-gen-types.js

@@ -0,0 +1,30 @@
+import { connect } from '../api.js';
+import {
+  readFlowManifest,
+  readFlowPackage,
+  typeFiles,
+  writeFlowFiles,
+} from '../flow-project.js';
+
+export const FLOW_GEN_TYPES_USAGE = 'juno flow gen-types';
+
+/**
+ * `juno flow gen-types` — regenerate flow-env.d.ts and flow-api.d.ts from
+ * manifest.json against the instance's live catalog. manifest.json itself is
+ * left alone: this refreshes what the editor type-checks against, nothing
+ * more. Stale types cannot ship regardless, because ingest regenerates them.
+ */
+export async function flowGenTypes(argv, io) {
+  await readFlowPackage(io.cwd);
+  const { manifest } = await readFlowManifest(io.cwd);
+  const { client } = await connect(argv, io);
+  const generated = await client.typegenFlow(manifest);
+  const files = typeFiles(generated?.types);
+  const written = await writeFlowFiles(io.cwd, files);
+  io.log(
+    written.length
+      ? `wrote ${written.join(', ')}`
+      : `${Object.keys(files).sort().join(', ')} already up to date`
+  );
+  return 0;
+}