@junoflow/cli 0.3.0 → 0.9.0

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,19 +41,24 @@ 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;
   }
 
   /**
    * POST /api/integrations/scaffold — a whole starting project, path →
-   * content. `target` is what this client reached the instance at; the server
-   * prefers its own configured public URL and falls back to it.
+   * content. `target` is what this client reached the instance at, recorded
+   * as juno.target; the server falls back to its public URL without 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,
     });
@@ -32,58 +70,531 @@ export class JunoClient {
     return this.#json('POST', '/api/typegen/integration', { manifest });
   }
 
-  /** POST /api/integrations/ingest — deploy, or validate only with dryRun. */
-  async ingest(project, { dryRun = false, name } = {}) {
-    const query = dryRun ? '?dry_run=true' : '';
-    return this.#json('POST', `/api/integrations/ingest${query}`, {
+  /**
+   * POST /api/integrations/ingest — deploy, or validate only with dryRun.
+   * `baseVersion` undefined sends none (a copy that records no base, --force,
+   * or --id naming another install). A 409 is a ConflictError: the install's
+   * active version is not the copy's base.
+   *
+   * It does not go through #workingCopyJSON, whose 422-without-diagnostics
+   * wording differs from what this route has always printed; only the 409 is
+   * shared.
+   */
+  async ingest(project, { dryRun = false, id, baseVersion } = {}) {
+    const path = `/api/integrations/ingest${dryRun ? '?dry_run=true' : ''}`;
+    const res = await this.#request('POST', path, {
       manifest: project.manifest,
       files: project.files,
       package_json: project.packageJSON ?? undefined,
       lockfile: project.lockfile ?? undefined,
-      name: name ?? undefined,
+      id: id ?? undefined,
+      base_version: baseVersion ?? undefined,
+    });
+    if (res.status === 409) throw new ConflictError(problemDetail(res));
+    return this.#answer('POST', path, res);
+  }
+
+  /** GET /api/integrations/{id} — the manifest and sources Juno holds. */
+  async getIntegration(id) {
+    return this.#json('GET', `/api/integrations/${encodeURIComponent(id)}`);
+  }
+
+  /**
+   * GET /api/integrations/{id}/versions/{v} — one stored version, keyed as
+   * the Go struct spells it (`Manifest`, `SourceFiles`), or null when the
+   * instance has no such version.
+   */
+  async getIntegrationVersion(id, version) {
+    return this.#versionOrNull(
+      `/api/integrations/${encodeURIComponent(id)}/versions/${version}`
+    );
+  }
+
+  /**
+   * GET /api/flows/{id}/versions/{v} — one stored version (`manifest_json`,
+   * `source_files`), or null when the instance has no such version.
+   */
+  async getFlowVersion(id, version) {
+    return this.#versionOrNull(
+      `/api/flows/${encodeURIComponent(id)}/versions/${version}`
+    );
+  }
+
+  /**
+   * GET /api/flows/{id}/runs/{seq}/fixture — `{fixture, notes}`, run `seq`
+   * as a flowHarness scenario. A refusal (a run still going, one that
+   * suspended or was cancelled) is a 422 and an unknown flow or run a 404;
+   * both are a UserError in the server's own words.
+   */
+  async runFixture(flowId, seq) {
+    const path = `/api/flows/${encodeURIComponent(flowId)}/runs/${seq}/fixture`;
+    const res = await this.#request('GET', path);
+    if (res.status === 422 || res.status === 404) {
+      throw new UserError(problemDetail(res));
+    }
+    return this.#answer('GET', path, res);
+  }
+
+  /**
+   * GET /api/apps/{id}/versions/{v} — one stored version (`manifest`,
+   * `files`), or null when the instance has no such version.
+   */
+  async getAppVersion(id, version) {
+    return this.#versionOrNull(
+      `/api/apps/${encodeURIComponent(id)}/versions/${version}`
+    );
+  }
+
+  /** #versionOrNull is a GET whose 404 is an answer: there is no such version. */
+  async #versionOrNull(path) {
+    const res = await this.#request('GET', path);
+    if (res.status === 404) return null;
+    return this.#answer('GET', path, res);
+  }
+
+  /**
+   * 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.#workingCopyJSON('/api/flows/scaffold', {
+      id,
+      target: target ?? undefined,
     });
+    return { files: body?.files ?? {}, warnings: body?.warnings ?? [] };
   }
 
-  /** GET /api/integrations/{name} — the manifest and sources Juno holds. */
-  async getIntegration(name) {
-    return this.#json('GET', `/api/integrations/${encodeURIComponent(name)}`);
+  /**
+   * POST /api/typegen/flow — `{manifest, types: {"types/flow-env.d.ts",
+   * "types/flow-api.d.ts"}}` for a manifest, from the live catalog.
+   */
+  async typegenFlow(manifest) {
+    return this.#workingCopyJSON('/api/typegen/flow', { manifest });
+  }
+
+  /**
+   * POST /api/flows/ingest — verify a flow working copy and, unless dryRun,
+   * commit and activate it. `files` is the working copy's src/ tree, path →
+   * content. `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, files, baseVersion }, { dryRun } = {}) {
+    const query = dryRun ? '?dry_run=true' : '';
+    return this.#workingCopyJSON(`/api/flows/ingest${query}`, {
+      flow_id: flowId,
+      manifest,
+      files,
+      base_version: baseVersion ?? undefined,
+    });
+  }
+
+  /**
+   * POST /api/apps/scaffold — an app working copy, `{files: {path:
+   * content}}`: the active version's, or a stub for an id with none.
+   */
+  async scaffoldApp(id, { target } = {}) {
+    const body = await this.#workingCopyJSON('/api/apps/scaffold', {
+      id,
+      target: target ?? undefined,
+    });
+    return body?.files ?? {};
+  }
+
+  /**
+   * POST /api/typegen/app — `{manifest, types: {"types/app-api.d.ts", …}}`
+   * for an edited manifest, from the live catalog.
+   */
+  async typegenApp(manifest) {
+    return this.#workingCopyJSON('/api/typegen/app', { manifest });
+  }
+
+  /**
+   * POST /api/apps/ingest — verify an app working copy and store it as a
+   * version: activated, or with `activate: false` left as the draft
+   * `~draft/` serves. A 422 with diagnostics is a DiagnosticsError.
+   * `baseVersion` undefined sends none (a copy that records no base, or
+   * --force). When activating, a 409 is a ConflictError: the app's active
+   * version is not the copy's base. A draft is never refused; the answer's
+   * `stale_base` carries the sentence instead.
+   */
+  async ingestApp(
+    { manifest, files, lockfile },
+    { activate = true, baseVersion } = {}
+  ) {
+    return this.#workingCopyJSON('/api/apps/ingest', {
+      manifest,
+      files,
+      lockfile: lockfile ?? undefined,
+      activate,
+      base_version: baseVersion ?? undefined,
+    });
+  }
+
+  /**
+   * #workingCopyJSON is #json for the flow and app 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 (an id that is not kebab-case, an
+   * archive path outside src/, page/ and public/).
+   */
+  async #workingCopyJSON(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 jsonBody('POST', path, res);
+    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);
+    return { result: jsonBody('POST', path, res), 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) throw failure('GET', path, res);
+    return jsonBody('GET', path, res);
+  }
+
+  /**
+   * 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) throw failure('GET', path, res);
+    jsonBody('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) {
+    return this.#answer(method, path, await this.#request(method, path, body));
+  }
+
+  /** #answer is #json's reading of an answer already received. */
+  #answer(method, path, res) {
+    if (res.ok) return jsonBody(method, path, res);
+
+    // 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);
+    return {
+      status: answer.status,
+      event: jsonBody('POST', path, answer),
+      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) throw failure('GET', path, res);
+    return jsonBody('GET', path, res);
+  }
+
+  /**
+   * #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.
+   *
+   * A redirect is not followed. Juno's API never redirects, so a 3xx comes
+   * from something in front of it, typically an auth proxy sending the
+   * request to its sign-in page. Following it would hand the caller that
+   * page's HTML as a 200.
+   */
+  async #send(method, path, body) {
     const url = `${this.target}${path}`;
+    // 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';
     let res;
     try {
       res = await this.fetch(url, {
         method,
-        headers: body ? { 'content-type': 'application/json' } : {},
+        headers,
         body: body ? JSON.stringify(body) : undefined,
+        redirect: 'manual',
       });
     } catch (err) {
-      throw new UserError(
+      throw new UnreachableError(
         `cannot reach Juno at ${this.target}: ${err.message}`
       );
     }
+    if (res.status >= 300 && res.status < 400) {
+      const location = res.headers?.get?.('location');
+      throw new UserError(
+        `${method} ${path} was redirected (${res.status})` +
+          (location ? ` to ${location}` : '') +
+          `: ${this.target} looks like it is behind an auth proxy or is ` +
+          'not the Juno API. Point the CLI at an address that reaches Juno ' +
+          'directly with --url or $JUNO_URL (inside a working copy, ' +
+          "package.json's juno.target is used otherwise)"
+      );
+    }
+    return res;
+  }
 
-    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);
+}
+
+/**
+ * jsonBody is a 2xx answer's parsed body, which every route this client calls
+ * answers as a JSON object. Anything else came from something other than
+ * Juno, such as a proxy's HTML page or a wrong URL. It is an error, never an
+ * empty success, because a caller reading fields off null either crashes or
+ * quietly does nothing.
+ */
+function jsonBody(method, path, res) {
+  if (res.parsed === null || typeof res.parsed !== 'object') {
+    throw new UserError(
+      `${method} ${path} answered something that is not JSON: ${res.text.trim()}`
+    );
+  }
+  return res.parsed;
+}
+
+/** 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('; ');
 }