@junoflow/cli 0.3.0 → 0.9.0

package/src/commands/app-dev.js

@@ -0,0 +1,141 @@
+import { readAppPackage } from '../app-project.js';
+import { createBuilder } from '../app-dev/build.js';
+import { createDevHarness } from '../app-dev/harness.js';
+import { createPanel } from '../app-dev/panel.js';
+import { createDevServer } from '../app-dev/server.js';
+import { createLive } from '../app-dev/stream.js';
+import { watchApp } from '../app-dev/watch.js';
+import { UsageError, UserError } from '../errors.js';
+import { readManifestFile } from '../working-copy.js';
+
+export const APP_DEV_USAGE = 'juno app dev [--port <n>] [--scenario <file>]';
+
+/** The port `juno app dev` listens on without --port. */
+export const DEFAULT_DEV_PORT = 8090;
+
+/**
+ * `juno app dev` — serve this app on localhost, offline, on mocked data
+ * (old-docs/design-docs/plan-local-dev-6-app-dev-server.md). The page is
+ * page/ as written, its modules bundled per request; the handlers run in
+ * Node through the working copy's own appHarness; the world is the
+ * --scenario file, or empty. It never reads `juno.target`, never connects to
+ * an instance and never reads a credential, so its effect is `local`.
+ *
+ * Bound to 127.0.0.1 only. It runs until SIGINT (or io.signal aborts), then
+ * closes the server and removes its temp directory.
+ */
+export async function appDev(argv, io) {
+  const port = parsePort(argv.port);
+  const dev = await startAppDev({
+    cwd: io.cwd,
+    port,
+    scenario: argv.scenario,
+    log: io.error,
+  });
+  io.log(
+    `juno app dev: ${dev.id} on http://localhost:${dev.port}/  ` +
+      `(${dev.harness.scenario ? `scenario: ${dev.harness.scenario.path}` : 'no scenario'})`
+  );
+  await new Promise((resolve) => {
+    const stop = () => {
+      process.off('SIGINT', stop);
+      io.signal?.removeEventListener('abort', stop);
+      resolve();
+    };
+    process.once('SIGINT', stop);
+    io.signal?.addEventListener('abort', stop, { once: true });
+    if (io.signal?.aborted) stop();
+  });
+  await dev.close();
+  return 0;
+}
+
+/**
+ * startAppDev reads the working copy, resolves esbuild and the testkit from
+ * it, and starts the server on port (0 picks a free one), with the live
+ * stream, the panel and the watcher wired in. It resolves to
+ * `{id, port, server, harness, builder, live, panel, close}`; `server` is
+ * createDevServer's object, whose `routes` a caller may extend. `pingMs` and
+ * `debounceMs` exist for tests.
+ */
+export async function startAppDev({
+  cwd,
+  port,
+  scenario,
+  log = () => {},
+  pingMs,
+  debounceMs,
+}) {
+  await readAppPackage(cwd);
+  const { manifest } = await readManifestFile(cwd);
+  if (typeof manifest?.id !== 'string' || manifest.id === '') {
+    throw new UserError('manifest.json has no id');
+  }
+
+  const builder = await createBuilder(cwd);
+  try {
+    const harness = await createDevHarness({ cwd, manifest, builder });
+    if (scenario !== undefined) await harness.useScenario(scenario);
+    const live = createLive({ dev: harness, pingMs });
+    const panel = createPanel({
+      cwd,
+      dev: harness,
+      builder,
+      live,
+      pingMs,
+      log,
+    });
+    await panel.noteScenario();
+    const server = createDevServer({
+      cwd,
+      dev: harness,
+      builder,
+      log,
+      routes: { stream: live.serve, dev: panel.route, shell: panel.shell },
+    });
+    let bound;
+    try {
+      bound = await server.listen(port);
+    } catch (err) {
+      if (err.code === 'EADDRINUSE') {
+        throw new UserError(
+          `port ${port} is in use — pass --port <n> to pick another`
+        );
+      }
+      throw err;
+    }
+    const watcher = watchApp(cwd, panel.watch, { debounceMs });
+    return {
+      id: manifest.id,
+      port: bound,
+      server,
+      harness,
+      builder,
+      live,
+      panel,
+      async close() {
+        watcher.close();
+        await panel.settled();
+        live.close();
+        panel.close();
+        await server.close();
+        await builder.close();
+      },
+    };
+  } catch (err) {
+    await builder.close();
+    throw err;
+  }
+}
+
+function parsePort(value) {
+  if (value === undefined) return DEFAULT_DEV_PORT;
+  const port = Number(value);
+  // 0 is the operating system's pick; the printed URL names the port it made.
+  if (!/^\d+$/.test(String(value)) || port > 65535) {
+    throw new UsageError(
+      `--port must be a port number from 0 to 65535, got ${JSON.stringify(value)}`
+    );
+  }
+  return port;
+}

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

@@ -0,0 +1,37 @@
+import { connect } from '../api.js';
+import { readAppPackage } from '../app-project.js';
+import { UserError } from '../errors.js';
+import {
+  readManifestFile,
+  typeFiles,
+  writeChangedFiles,
+} from '../working-copy.js';
+
+export const APP_GEN_TYPES_USAGE = 'juno app gen-types';
+
+/**
+ * `juno app gen-types` — regenerate the three files under types/ from
+ * manifest.json against the instance's live catalog: app-env.d.ts (what
+ * src/app.ts is checked against), app-client.d.ts (`juno` as the page sees
+ * it) and app-api.d.ts. manifest.json itself is left alone. Stale types
+ * cannot ship regardless, because ingest regenerates them.
+ */
+export async function appGenTypes(argv, io) {
+  await readAppPackage(io.cwd);
+  const { manifest } = await readManifestFile(io.cwd);
+  const { client } = await connect(argv, io);
+  const generated = await client.typegenApp(manifest);
+  const files = typeFiles(generated.types);
+  if (!Object.keys(files).length) {
+    throw new UserError(
+      `${client.target} answered no .d.ts files for this manifest`
+    );
+  }
+  const written = await writeChangedFiles(io.cwd, files);
+  io.log(
+    written.length
+      ? `wrote ${written.join(', ')}`
+      : `${Object.keys(files).sort().join(', ')} already up to date`
+  );
+  return 0;
+}

package/src/commands/app-init.js

@@ -0,0 +1,46 @@
+import { resolve } from 'node:path';
+
+import { connect } from '../api.js';
+import { printAuthoringIndex } from '../authoring-skills.js';
+import { UsageError, UserError } from '../errors.js';
+import { writeChangedFiles } from '../working-copy.js';
+import { exists } from './init.js';
+
+export const APP_INIT_USAGE = 'juno app init <id> [--here]';
+
+/**
+ * `juno app init <id>` — a working copy of the app's active version, or a
+ * stub with one handler for an id with none, written into ./<id> (or the
+ * current directory with --here).
+ *
+ * Every file comes from POST /api/apps/scaffold, the single generator of an
+ * app working copy: the CLI writes what it is handed and holds no copy of the
+ * layout, the script lines or the types. After the next steps it prints the
+ * app author's skill index, which is where an external agent starts.
+ */
+export async function appInit(argv, io) {
+  const [id, ...extra] = argv._;
+  if (!id || extra.length > 0) {
+    throw new UsageError(`usage: ${APP_INIT_USAGE}`);
+  }
+
+  const dir = resolve(io.cwd, argv.here ? '.' : id);
+  if (!argv.here && (await exists(dir))) {
+    throw new UserError(`${dir} already exists`);
+  }
+
+  const { target, client } = await connect(argv, io);
+  // The id is validated server-side, by the validator ingest runs: one answer
+  // to "is this a valid app id".
+  const files = await client.scaffoldApp(id, { target });
+  await writeChangedFiles(dir, files);
+
+  io.log(`created ${dir}`);
+  io.log('');
+  io.log(argv.here ? 'npm install' : `cd ${id} && npm install`);
+  io.log('npm test');
+  io.log('npm run check    # stores a draft and prints its preview URL');
+  io.log('npm run deploy');
+  await printAuthoringIndex('app', client, target, io);
+  return 0;
+}

package/src/commands/app-pull.js

@@ -0,0 +1,106 @@
+import { connect } from '../api.js';
+import { readAppPackage, updateAppPackage } from '../app-project.js';
+import { UserError } from '../errors.js';
+import {
+  baseArtifactPaths,
+  baseVersionOf,
+  MANIFEST,
+  manifestText,
+  PACKAGE_JSON,
+  pullArtifacts,
+  requireCleanTree,
+  setDependencies,
+  writeChangedFiles,
+} from '../working-copy.js';
+
+export const APP_PULL_USAGE = 'juno app pull [--force]';
+
+/**
+ * `juno app pull` — make the working copy's artifact files the app's active
+ * version: manifest.json and every file under src/, test/, page/ and public/,
+ * exactly as the version stores them (GET /api/apps/{id}/versions/{v}), never
+ * as the scaffold renders them. types/ is generated, so it comes from
+ * POST /api/apps/scaffold, which also names the active version. In
+ * package.json only `dependencies` (the manifest's) and `juno.base_version`
+ * are Juno's; `scripts` and every other key are the author's and stay.
+ *
+ * A local file is deleted only when the base version (`juno.base_version`)
+ * had it and the pulled one does not; a file neither has is one not deployed
+ * yet, and stays. page/tsconfig.json and the other project files are never
+ * written or deleted.
+ *
+ * It refuses a dirty git tree without --force, as the other kinds' pull
+ * does: an uncommitted edit is the one thing nothing can get back.
+ */
+export async function appPull(argv, io) {
+  const pkg = await readAppPackage(io.cwd);
+  const appId = pkg.juno.app_id;
+
+  await requireCleanTree(io.cwd, {
+    force: argv.force,
+    overwrites: `${MANIFEST}, src/, test/, page/, public/ and types/`,
+    io,
+  });
+
+  const { target, client } = await connect(argv, io);
+  const files = await client.scaffoldApp(appId, { target });
+  let scaffoldPkg;
+  try {
+    scaffoldPkg = JSON.parse(files[PACKAGE_JSON]);
+  } catch {
+    throw new UserError(
+      `${target} answered a working copy with no readable ${PACKAGE_JSON}`
+    );
+  }
+  const version = scaffoldPkg.juno?.base_version;
+  const noActive = () =>
+    new UserError(
+      `${appId} has no active version on ${target} — nothing to pull`
+    );
+  // No base_version is the scaffold's stub for an app with no active
+  // version; writing it over the author's work would lose it for nothing.
+  if (!Number.isInteger(version)) throw noActive();
+
+  // Everything is fetched before anything is written, so a failure leaves
+  // the working copy as it was.
+  const detail = await client.getAppVersion(appId, version);
+  if (!detail) throw noActive();
+  const stored = { [MANIFEST]: manifestText(detail.manifest), ...detail.files };
+  const base = await baseArtifactPaths({
+    base: baseVersionOf(pkg),
+    version,
+    stored,
+    read: async (v) => {
+      const b = await client.getAppVersion(appId, v);
+      return b ? [MANIFEST, ...Object.keys(b.files ?? {})] : null;
+    },
+    id: appId,
+    target,
+    io,
+  });
+
+  const { written, removed } = await pullArtifacts(io.cwd, {
+    stored,
+    base,
+    kind: 'app',
+  });
+  written.push(
+    ...(await writeChangedFiles(
+      io.cwd,
+      Object.fromEntries(
+        Object.entries(files).filter(([name]) => name.startsWith('types/'))
+      )
+    ))
+  );
+  await updateAppPackage(io.cwd, (p) => {
+    setDependencies(p, detail.manifest);
+    p.juno.base_version = version;
+  });
+  written.push(PACKAGE_JSON);
+
+  io.log(
+    `pulled ${appId} v${version} from ${target} (${written.sort().join(', ')})`
+  );
+  if (removed.length) io.log(`removed ${removed.join(', ')}`);
+  return 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,28 @@
 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 { baseFor } from './deploy.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.
+ * at a production instance. It sends `juno.base_version` like deploy does, so
+ * a stale copy is a 409 (exit 4) here, before deploy hits it.
+ *
+ * --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,49 +31,84 @@ 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);
       failed = true;
     }
-    for (const [label, bin, args] of [
-      ['typecheck', 'tsc', ['--noEmit']],
-      ['lint', 'eslint', ['.']],
-    ]) {
-      const code = await runLocal(bin, args, io);
-      if (code === SKIPPED) {
-        io.warn(`${label}: ${bin} is not installed — run npm install`);
-        continue;
-      }
-      if (code !== 0) failed = true;
-    }
+    if (await runLocalChecks(argv, io)) failed = true;
   }
 
-  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,
+      baseVersion: baseFor(project, argv, io),
+    });
+  } 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;
+
+/**
+ * runLocalChecks runs tsc and eslint from the working copy's node_modules,
+ * the offline half of every kind's `check`, and answers whether either
+ * failed. A tool that is not installed is a warning, not a failure: the
+ * server-side half still runs.
+ */
+export async function runLocalChecks(argv, io) {
+  let failed = false;
+  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;
+  }
+  return failed;
+}
 
 /**
  * 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;
+}