@junoflow/cli 0.3.0 → 0.6.0

package/bin/juno.js

@@ -1,4 +1,11 @@
 #!/usr/bin/env node
 import { run } from '../src/index.js';
 
+// A reader that stops early (`juno discover | head`) closes the pipe under the
+// next write. That is the reader's choice, not a failure worth a stack trace.
+process.stdout.on('error', (err) => {
+  if (err.code !== 'EPIPE') throw err;
+  process.exit(process.exitCode ?? 0);
+});
+
 process.exitCode = await run(process.argv.slice(2));

package/eslint.flow.config.js

@@ -0,0 +1,33 @@
+import tsParser from '@typescript-eslint/parser';
+import juno from '@junoflow/eslint-plugin';
+
+/**
+ * The lint preset for a flow working copy (`juno flow init`).
+ *
+ * The rules come from the plugin's `rulesets.json`, `configs.flow` — the set
+ * Juno's verify step lints a flow's `flow.ts` with — so the author runs the
+ * rules the server runs, by construction rather than by two lists.
+ *
+ * One rule reports nothing here: `juno/prefer-claim-over-set` needs to know
+ * which of the flow's state bindings have claim slots, which is a fact about
+ * the instance's registry that a local config cannot know. Verify is told, so
+ * `npm run check` and `npm run deploy` report it.
+ *
+ * The generated `.d.ts` files are not linted: verify lints the author's source
+ * and nothing else, and the flow rules are about handlers they do not contain.
+ */
+export default [
+  {
+    ignores: ['node_modules/**', 'dist/**', '**/*.d.ts'],
+  },
+  {
+    files: ['**/*.ts'],
+    languageOptions: {
+      parser: tsParser,
+      ecmaVersion: 2022,
+      sourceType: 'module',
+    },
+    plugins: { juno },
+    rules: { ...juno.configs.flow },
+  },
+];

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@junoflow/cli",
-  "version": "0.3.0",
-  "description": "Command line tools for developing Juno integrations",
+  "version": "0.6.0",
+  "description": "Develop Juno integrations and operate a Juno instance from the command line",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -16,13 +16,16 @@
     ".": "./src/index.js",
     "./package.json": "./package.json",
     "./tsconfig.base.json": "./tsconfig.base.json",
-    "./eslint.config.js": "./eslint.config.js"
+    "./eslint.config.js": "./eslint.config.js",
+    "./eslint.flow.config.js": "./eslint.flow.config.js"
   },
   "files": [
     "bin",
     "src",
     "tsconfig.base.json",
     "eslint.config.js",
+    "eslint.flow.config.js",
+    "verbs.json",
     "README.md"
   ],
   "scripts": {
@@ -32,7 +35,7 @@
     "node": ">=20"
   },
   "dependencies": {
-    "@junoflow/eslint-plugin": "0.3.0",
+    "@junoflow/eslint-plugin": "0.6.0",
     "@typescript-eslint/parser": "^8.0.0"
   },
   "devDependencies": {

package/src/api.js

@@ -1,4 +1,37 @@
-import { DiagnosticsError, UserError } from './errors.js';
+import {
+  ConflictError,
+  DiagnosticsError,
+  UnreachableError,
+  UsageError,
+  UserError,
+} from './errors.js';
+import { resolveTarget } from './target.js';
+
+/**
+ * clientName is the X-Juno-Client value: `cli/claude-code` inside a shell
+ * Claude Code started (it sets CLAUDECODE=1), `cli` everywhere else. The
+ * gateway records a write as `operator:<client>`; it is the actor, not a
+ * security control.
+ */
+export function clientName(env = process.env) {
+  return env.CLAUDECODE === '1' ? 'cli/claude-code' : 'cli';
+}
+
+/**
+ * connect resolves the instance (target.js) and builds the client every
+ * command uses, unless one was injected: `args.client` is how the tests hand
+ * a command a client instead of a URL.
+ */
+export async function connect(args, io) {
+  const target = await resolveTarget({
+    url: args.url,
+    cwd: io.cwd,
+    env: io.env,
+  });
+  const client =
+    args.client ?? new JunoClient(target, { client: clientName(io.env) });
+  return { target, client };
+}
 
 /**
  * Client for the handful of endpoints this CLI knows about. It knows nothing
@@ -8,9 +41,13 @@ import { DiagnosticsError, UserError } from './errors.js';
  * disagree.
  */
 export class JunoClient {
-  constructor(target, { fetch: fetchImpl = globalThis.fetch } = {}) {
+  constructor(
+    target,
+    { fetch: fetchImpl = globalThis.fetch, client = clientName() } = {}
+  ) {
     this.target = target;
     this.fetch = fetchImpl;
+    this.client = client;
   }
 
   /**
@@ -18,9 +55,10 @@ export class JunoClient {
    * content. `target` is what this client reached the instance at; the server
    * prefers its own configured public URL and falls back to it.
    */
-  async scaffold(name, { description, target } = {}) {
+  async scaffold(id, { name, description, target } = {}) {
     const body = await this.#json('POST', '/api/integrations/scaffold', {
-      name,
+      id,
+      name: name ?? undefined,
       description: description ?? undefined,
       target: target ?? undefined,
     });
@@ -33,57 +71,387 @@ export class JunoClient {
   }
 
   /** POST /api/integrations/ingest — deploy, or validate only with dryRun. */
-  async ingest(project, { dryRun = false, name } = {}) {
+  async ingest(project, { dryRun = false, id } = {}) {
     const query = dryRun ? '?dry_run=true' : '';
     return this.#json('POST', `/api/integrations/ingest${query}`, {
       manifest: project.manifest,
       files: project.files,
       package_json: project.packageJSON ?? undefined,
       lockfile: project.lockfile ?? undefined,
-      name: name ?? undefined,
+      id: id ?? undefined,
     });
   }
 
-  /** GET /api/integrations/{name} — the manifest and sources Juno holds. */
-  async getIntegration(name) {
-    return this.#json('GET', `/api/integrations/${encodeURIComponent(name)}`);
+  /** GET /api/integrations/{id} — the manifest and sources Juno holds. */
+  async getIntegration(id) {
+    return this.#json('GET', `/api/integrations/${encodeURIComponent(id)}`);
+  }
+
+  /**
+   * POST /api/flows/scaffold — a flow working copy, `{files: {path: content},
+   * warnings?: [string]}`: the active version's, or a stub for an id with
+   * none. The warnings are a stored manifest the live catalog now refuses;
+   * the working copy is still rendered, because it is how that gets fixed.
+   */
+  async scaffoldFlow(id, { target } = {}) {
+    const body = await this.#flowJSON('/api/flows/scaffold', {
+      id,
+      target: target ?? undefined,
+    });
+    return { files: body?.files ?? {}, warnings: body?.warnings ?? [] };
+  }
+
+  /**
+   * POST /api/typegen/flow — `{manifest, types: {"flow-env.d.ts",
+   * "flow-api.d.ts"}}` for a manifest, from the live catalog.
+   */
+  async typegenFlow(manifest) {
+    return this.#flowJSON('/api/typegen/flow', { manifest });
+  }
+
+  /**
+   * POST /api/flows/ingest — verify a flow working copy and, unless dryRun,
+   * commit and activate it. `baseVersion` undefined sends none (a new flow,
+   * or --force). A 409 is a ConflictError; a 422 with diagnostics is a
+   * DiagnosticsError.
+   */
+  async ingestFlow({ flowId, manifest, flowTS, baseVersion }, { dryRun } = {}) {
+    const query = dryRun ? '?dry_run=true' : '';
+    return this.#flowJSON(`/api/flows/ingest${query}`, {
+      flow_id: flowId,
+      manifest,
+      flow_ts: flowTS,
+      base_version: baseVersion ?? undefined,
+    });
+  }
+
+  /**
+   * #flowJSON is #json for the flow working-copy routes, which answer two
+   * more failures in their own words: a 409 (the working copy is stale) and a
+   * 422 with no diagnostics (a flow id that is not kebab-case).
+   */
+  async #flowJSON(path, body) {
+    const res = await this.#request('POST', path, body);
+    if (res.status === 409) throw new ConflictError(problemDetail(res));
+    if (res.status === 422 && !res.parsed?.diagnostics?.length) {
+      throw new UserError(validationDetail(res));
+    }
+    if (res.ok) return res.parsed;
+    if (res.parsed?.diagnostics?.length) {
+      throw new DiagnosticsError(
+        res.parsed.detail || 'verification failed',
+        res.parsed.diagnostics
+      );
+    }
+    throw failure('POST', path, res);
+  }
+
+  /**
+   * POST /api/tools/{name} — one tool call. A 200 is the tool's answer and is
+   * returned whatever it says, `{"error": …}` included: a domain failure is a
+   * result, and the caller decides the exit code. `text` is the body exactly as
+   * it arrived, so it can be printed unchanged.
+   */
+  async callTool(name, input) {
+    const path = `/api/tools/${encodeURIComponent(name)}`;
+    const res = await this.#request('POST', path, input);
+    if (res.status === 422) {
+      throw new UsageError(
+        `invalid input for ${name}: ${validationDetail(res)}`
+      );
+    }
+    if (res.status === 404) {
+      throw new UsageError(
+        `${this.target} does not serve the tool "${name}"; ` +
+          'the instance is probably older than this CLI'
+      );
+    }
+    if (!res.ok) throw failure('POST', path, res);
+    if (res.parsed === null) {
+      throw new UserError(
+        `POST ${path} answered something that is not JSON: ${res.text.trim()}`
+      );
+    }
+    return { result: res.parsed, text: res.text };
+  }
+
+  /**
+   * GET /api/tools — every served tool with its description, input schema
+   * and effect. Help reads it, so the text a person sees is the server's.
+   */
+  async listTools() {
+    const body = await this.#json('GET', '/api/tools');
+    return body?.tools ?? [];
+  }
+
+  /**
+   * GET /api/skills — `{skills: [{name, description}], agent_skill_version}`,
+   * sorted by name. `authoring` (`flow` or `integration`) narrows it to the
+   * skills for writing that kind of working copy.
+   */
+  async listSkills({ authoring } = {}) {
+    const query = authoring
+      ? `?authoring=${encodeURIComponent(authoring)}`
+      : '';
+    return this.#json('GET', `/api/skills${query}`);
+  }
+
+  /**
+   * GET /api/agent-skill — `{version, skill_md, agents_md, permissions,
+   * working_copy_permissions}`: the skill a coding agent installs and the
+   * permission rules that go with it, both rendered by the server.
+   */
+  async getAgentSkill() {
+    return this.#json('GET', '/api/agent-skill');
+  }
+
+  /**
+   * GET /api/skills/{name} — `{name, description, body}`, the body exactly as
+   * the in-app load_skill returns it, or null when the instance serves no
+   * skill of that name.
+   */
+  async getSkill(name) {
+    const path = `/api/skills/${encodeURIComponent(name)}`;
+    const res = await this.#request('GET', path);
+    if (res.status === 404) return null;
+    if (!res.ok || res.parsed === null) throw failure('GET', path, res);
+    return res.parsed;
+  }
+
+  /**
+   * GET /api/secrets/{id} — the credential's `{name, description}`, or null
+   * when there is none (a built-in id answers 404 too). The route also
+   * answers the plaintext value; it is dropped here, so it never leaves this
+   * method.
+   */
+  async getCredentialMeta(id) {
+    const path = `/api/secrets/${encodeURIComponent(id)}`;
+    const res = await this.#request('GET', path);
+    if (res.status === 404) return null;
+    if (!res.ok || res.parsed === null) throw failure('GET', path, res);
+    return {
+      name: res.parsed.name ?? '',
+      description: res.parsed.description ?? '',
+    };
+  }
+
+  /** POST /api/secrets — a new credential. */
+  async createCredential({ id, name, description, value }) {
+    await this.#credentialWrite('POST', '/api/secrets', id, {
+      id,
+      name,
+      description,
+      value,
+    });
+  }
+
+  /** PUT /api/secrets/{id} — replace an existing credential's value. */
+  async updateCredential(id, { name, description, value }) {
+    const path = `/api/secrets/${encodeURIComponent(id)}`;
+    await this.#credentialWrite('PUT', path, id, { name, description, value });
+  }
+
+  /**
+   * #credentialWrite sends a credential write and returns nothing: PUT
+   * answers the stored plaintext, which no caller has any use for. A 422 is
+   * the server refusing the request (a reserved built-in id, a missing
+   * description), printed in its own words as a usage error.
+   */
+  async #credentialWrite(method, path, id, body) {
+    const res = await this.#request(method, path, body);
+    if (res.status === 422) {
+      throw new UsageError(
+        `cannot set credential "${id}": ${validationDetail(res)}`
+      );
+    }
+    if (!res.ok) throw failure(method, path, res);
   }
 
   async #json(method, path, body) {
+    const res = await this.#request(method, path, body);
+    if (res.ok) return res.parsed;
+
+    // A 422 is the interesting failure: it carries the compiler's own
+    // findings, and reprinting them beats summarising them.
+    if (res.parsed?.diagnostics?.length) {
+      throw new DiagnosticsError(
+        res.parsed.detail || 'verification failed',
+        res.parsed.diagnostics
+      );
+    }
+    throw failure(method, path, res);
+  }
+
+  /**
+   * POST /api/agent/prompt — one exchange with the in-app assistant. `stream`
+   * is written into the body here, so the request and how its answer is read
+   * cannot disagree.
+   *
+   * - `stream: false`: `{status, event, text}` — 200 is a turn that ended,
+   *   202 a `pending` one; `text` is the body as it arrived.
+   * - `stream: true`: `{status: 200, events}`, an async iterator over the
+   *   NDJSON lines as `{event, text}`, read as they arrive.
+   * - 409: `{status: 409, conflict}`, the server's words. The caller decides
+   *   what each one means (prompt.js); this method only reports it.
+   *
+   * A 400 is a malformed `--session` or `--wait` (UsageError); a 404 is
+   * observing a session that does not exist (UserError).
+   */
+  async prompt(body, { stream }) {
+    const path = '/api/agent/prompt';
+    const res = await this.#send('POST', path, { ...body, stream });
+    if (stream && res.status === 200) {
+      return { status: 200, events: ndjson(res.body, this.target) };
+    }
+
+    const answer = await this.#read(res);
+    if (answer.status === 409) {
+      return { status: 409, conflict: problemDetail(answer) };
+    }
+    if (answer.status === 400) throw new UsageError(problemDetail(answer));
+    if (answer.status === 404) throw new UserError(problemDetail(answer));
+    if (!answer.ok) throw failure('POST', path, answer);
+    if (answer.parsed === null || typeof answer.parsed !== 'object') {
+      throw new UserError(
+        `POST ${path} answered something that is not JSON: ${answer.text.trim()}`
+      );
+    }
+    return { status: answer.status, event: answer.parsed, text: answer.text };
+  }
+
+  /**
+   * GET /api/agent/{id} — one session's `{status, pending_input, …}`, or null
+   * when there is none.
+   */
+  async getAgentSession(id) {
+    const path = `/api/agent/${encodeURIComponent(id)}`;
+    const res = await this.#request('GET', path);
+    if (res.status === 404) return null;
+    if (!res.ok || res.parsed === null) throw failure('GET', path, res);
+    return res.parsed;
+  }
+
+  /**
+   * #request sends a request and reads its whole answer. It throws only when
+   * there is no answer at all; every status comes back to the caller, which
+   * knows what a 404 or a 422 means for its route.
+   */
+  async #request(method, path, body) {
+    return this.#read(await this.#send(method, path, body));
+  }
+
+  /**
+   * #send is the one place a request leaves this CLI, returning the fetch
+   * Response unread so a stream can be read as it arrives.
+   */
+  async #send(method, path, body) {
     const url = `${this.target}${path}`;
-    let res;
+    // Every request carries the header, the existing commands' included:
+    // one client, one header.
+    const headers = { 'X-Juno-Client': this.client };
+    if (body) headers['content-type'] = 'application/json';
     try {
-      res = await this.fetch(url, {
+      return await this.fetch(url, {
         method,
-        headers: body ? { 'content-type': 'application/json' } : {},
+        headers,
         body: body ? JSON.stringify(body) : undefined,
       });
     } catch (err) {
-      throw new UserError(
+      throw new UnreachableError(
         `cannot reach Juno at ${this.target}: ${err.message}`
       );
     }
+  }
 
-    const text = await res.text();
+  async #read(res) {
+    let text;
+    try {
+      text = await res.text();
+    } catch (err) {
+      throw new UnreachableError(
+        `lost the connection to Juno at ${this.target}: ${err.message}`
+      );
+    }
     let parsed = null;
     try {
       parsed = text ? JSON.parse(text) : null;
     } catch {
-      // A non-JSON body from a proxy or a wrong URL; reported below as-is.
+      // A non-JSON body from a proxy or a wrong URL; reported as-is.
     }
+    return {
+      ok: res.ok,
+      status: res.status,
+      statusText: res.statusText,
+      text,
+      parsed,
+    };
+  }
+}
 
-    if (res.ok) return parsed;
-
-    // A 422 is the interesting failure: it carries the compiler's own
-    // findings, and reprinting them beats summarising them.
-    if (parsed?.diagnostics?.length) {
-      throw new DiagnosticsError(
-        parsed.detail || 'verification failed',
-        parsed.diagnostics
-      );
+/**
+ * ndjson reads a response body one line at a time, yielding each parsed line
+ * with its exact text. A connection that drops mid-stream is an
+ * UnreachableError, like one that never connected: either way there is no
+ * answer, and a retry that reuses the message id is safe.
+ */
+async function* ndjson(body, target) {
+  const decoder = new TextDecoder();
+  let buffered = '';
+  const lines = function* (final) {
+    let nl;
+    while ((nl = buffered.indexOf('\n')) >= 0 || (final && buffered)) {
+      const text = nl >= 0 ? buffered.slice(0, nl) : buffered;
+      buffered = nl >= 0 ? buffered.slice(nl + 1) : '';
+      if (!text.trim()) continue;
+      let event;
+      try {
+        event = JSON.parse(text);
+      } catch {
+        throw new UserError(
+          `the prompt stream sent a line that is not JSON: ${text}`
+        );
+      }
+      yield { event, text };
     }
-    const detail =
-      parsed?.detail || parsed?.title || text.trim() || res.statusText;
-    throw new UserError(`${method} ${path} failed (${res.status}): ${detail}`);
+  };
+  try {
+    for await (const chunk of body) {
+      buffered += decoder.decode(chunk, { stream: true });
+      yield* lines(false);
+    }
+  } catch (err) {
+    if (err instanceof UserError) throw err;
+    throw new UnreachableError(
+      `lost the connection to Juno at ${target}: ${err.message}`
+    );
+  }
+  buffered += decoder.decode();
+  yield* lines(true);
+}
+
+/** The server's own words in an error answer: Huma's `detail`, else the body. */
+function problemDetail(res) {
+  return (
+    res.parsed?.detail || res.parsed?.title || res.text.trim() || res.statusText
+  );
+}
+
+/** A UserError for a non-ok answer, carrying the server's own words. */
+function failure(method, path, res) {
+  return new UserError(
+    `${method} ${path} failed (${res.status}): ${problemDetail(res)}`
+  );
+}
+
+/**
+ * The words of a 422: the gateway's own detail names the failing field (`/id`,
+ * `/ops/0/when`, `/` for the root); Huma's request validation puts it in
+ * `errors[]` instead, so those are appended.
+ */
+function validationDetail(res) {
+  const parts = [res.parsed?.detail || res.text.trim() || res.statusText];
+  for (const e of res.parsed?.errors ?? []) {
+    parts.push(e.location ? `${e.location}: ${e.message}` : e.message);
   }
+  return parts.filter(Boolean).join('; ');
 }

package/src/authoring-skills.js

@@ -0,0 +1,42 @@
+import { warnIfStale } from './installed-skill.js';
+
+/**
+ * The kinds of working copy with an authoring skill index, and the heading
+ * each is printed under. The index itself is the server's
+ * (GET /api/skills?authoring=<kind>): the same name and description lines the
+ * in-app flow and integration authors are given, so it cannot drift from the
+ * skills.
+ */
+export const AUTHORING_HEADINGS = {
+  flow: 'Skills for writing a flow',
+  integration: 'Skills for writing an integration',
+};
+
+/** The heading line, saying how a listed skill is loaded. */
+export function authoringHeading(kind) {
+  return `${AUTHORING_HEADINGS[kind]} (load one with \`juno skill <name>\`):`;
+}
+
+/**
+ * printAuthoringIndex prints a kind's authoring skills after `init` has
+ * written the working copy, as `  <name> — <description>`. Fetching it is a
+ * courtesy: the working copy is already on disk, so a failure is a note on
+ * stderr, never a failed init. It also says when an installed agent skill is
+ * stale, since the index carries the version the instance serves.
+ */
+export async function printAuthoringIndex(kind, client, target, io) {
+  let index;
+  try {
+    index = await client.listSkills({ authoring: kind });
+  } catch (err) {
+    io.warn(`(skill index unavailable: ${err.message})`);
+    return;
+  }
+  const skills = index?.skills ?? [];
+  if (skills.length > 0) {
+    io.log('');
+    io.log(authoringHeading(kind));
+    for (const s of skills) io.log(`  ${s.name} — ${s.description}`);
+  }
+  await warnIfStale(index, target, io);
+}

package/src/commands/agent-skill-install.js

@@ -0,0 +1,64 @@
+import { mkdir, writeFile } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+
+import { connect } from '../api.js';
+import { UsageError } from '../errors.js';
+import { SKILL_DIR } from '../installed-skill.js';
+
+export const AGENT_SKILL_INSTALL_USAGE =
+  'juno agent-skill install [--dir <path>] [--allow-change] [--working-copy] [--agents-md] [--json]';
+
+/**
+ * `juno agent-skill install` writes the skill GET /api/agent-skill renders to
+ * `<dir>/SKILL.md` (default `.claude/skills/juno` under the current
+ * directory) and prints a Claude Code permission block on stdout: every read
+ * command, plus every change command with --allow-change, plus the working
+ * copy's npm scripts of the same tiers with --working-copy. No act command is
+ * ever in it — the server leaves them out, and the CLI adds nothing.
+ *
+ * `--agents-md` prints the same text as an AGENTS.md section instead and
+ * writes nothing; `--json` prints the route's body.
+ */
+export async function agentSkillInstall(args, io) {
+  if (args._.length > 0) {
+    throw new UsageError(
+      `juno agent-skill install takes no argument; usage: ${AGENT_SKILL_INSTALL_USAGE}`
+    );
+  }
+  const { client } = await connect(args, io);
+  const skill = await client.getAgentSkill();
+
+  if (args.json) return printJSON(skill, io);
+  if (args['agents-md']) {
+    io.write(skill.agents_md);
+    return 0;
+  }
+
+  const dir = resolve(io.cwd, args.dir ?? SKILL_DIR);
+  const path = join(dir, 'SKILL.md');
+  await mkdir(dir, { recursive: true });
+  await writeFile(path, skill.skill_md, 'utf8');
+
+  const tiers = (t) => [
+    ...(t?.read ?? []),
+    ...(args['allow-change'] ? (t?.change ?? []) : []),
+  ];
+  const allow = tiers(skill.permissions);
+  if (args['working-copy'])
+    allow.push(...tiers(skill.working_copy_permissions));
+
+  io.warn(`wrote ${path} (version ${skill.version})`);
+  io.warn(
+    args['working-copy']
+      ? "Add these rules to this working copy's .claude/settings.json — not to user-wide settings, " +
+          "where they would also allow any other project's npm scripts:"
+      : 'Add these rules to .claude/settings.json (or ~/.claude/settings.json) to run them without a prompt:'
+  );
+  return printJSON({ permissions: { allow } }, io);
+}
+
+/** Compact off a TTY, indented on one, as every JSON the CLI prints. */
+function printJSON(value, io) {
+  io.log(io.isTTY ? JSON.stringify(value, null, 2) : JSON.stringify(value));
+  return 0;
+}