@ciphrix/cli 0.1.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,201 @@
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="assets/brand/logo_dark_mode.svg">
+    <source media="(prefers-color-scheme: light)" srcset="assets/brand/logo_light_mode.svg">
+    <img alt="Ciphrix" src="assets/brand/logo_light_mode.svg" width="360">
+  </picture>
+</p>
+
+<h1 align="center">Ciphrix CLI</h1>
+
+<p align="center">
+  Compliance work, wherever you and your agents work.
+</p>
+
+The official command-line interface for the [Ciphrix](https://ciphrix.com) compliance platform.
+Use Ciphrix from your terminal, scripts, and agent workspaces to understand compliance context, work with
+policies and evidence, run tests, and manage frameworks, controls, assets, vendors, risks, and monitoring.
+
+## Install
+
+Requires Node.js 20.19 or newer.
+
+```bash
+npm install --global @ciphrix/cli
+ciphrix login
+```
+
+Or run a command without installing:
+
+```bash
+npx @ciphrix/cli --help
+```
+
+Update an existing global installation with `npm install --global @ciphrix/cli@latest`.
+
+`ciphrix login` opens the Ciphrix authorization page in your browser and prints the same link and device
+code in the terminal. Your password is never entered into the CLI.
+
+<p align="center">
+  <img alt="Ciphrix CLI help and document library" src="assets/readme/ciphrix-cli.jpg" width="824">
+</p>
+
+## From question to evidence
+
+```bash
+# Understand the organisation before changing anything
+ciphrix context get business
+
+# Find a policy and read it as Markdown
+ciphrix document list
+ciphrix document get "Access Control Policy"
+
+# See what a test covers and inspect its history
+ciphrix test links "MFA enforced"
+ciphrix test runs "MFA enforced"
+
+# Record a formal result
+ciphrix test run result "MFA enforced" \
+  --status passing \
+  --note "Rolled out organisation-wide"
+```
+
+Add `--json` to any command for stable machine-readable output. Commands that perform consequential
+changes show the proposed action and ask for confirmation; automation can opt in with `--yes`.
+
+## One interface for compliance work
+
+- **Understand the business** — read Business and Operating Context before proposing or changing controls.
+- **Work with policies** — find documents, read Markdown, manage versions, and move work through review.
+- **Connect evidence to assurance** — inspect tests and runs, attach evidence, and record formal results.
+- **Navigate the compliance model** — trace frameworks, clauses, controls, tests, documents, and assets.
+- **Manage operational registers** — work with assets, vendors, risks, treatments, ownership, and files.
+- **Operate monitoring** — inspect checks, resources, runs, findings, integrations, and background jobs.
+
+Names and stable Ciphrix codes are accepted throughout, so neither people nor agents need to work with
+opaque database identifiers.
+
+## Built for agent workspaces
+
+Ciphrix ships an agent skill as well as a CLI. The CLI provides the tools; the skill teaches an agent the
+Ciphrix domain model, operating principles, authority boundaries, and reliable workflows.
+
+Install the skill with the open [Skills CLI](https://skills.sh/docs/cli):
+
+```bash
+# Choose detected agents and installation scope interactively
+npx skills add CiphrixHQ/ciphrix-cli --skill ciphrix
+
+# Or install globally for selected agents
+npx skills add CiphrixHQ/ciphrix-cli --skill ciphrix \
+  -g \
+  -a codex \
+  -a claude-code \
+  -a cursor \
+  -a opencode
+```
+
+The skill works with compatible agent harnesses including Codex, Claude Code, Cursor, and OpenCode. It
+is also included in the npm package at [`skills/ciphrix/SKILL.md`](skills/ciphrix/SKILL.md). Installing
+the npm package never modifies an agent's configuration directories.
+
+Run `npx skills update` to update installed skills when a newer version is available.
+
+### Ask in natural language, operate through the CLI
+
+An agent can translate a request into a Ciphrix command, inspect the structured result, and present the
+answer in the workspace where the user is already working.
+
+<p align="center">
+  <img alt="An agent uses Ciphrix CLI to inspect the vendor register" src="assets/readme/pi-harness-1.jpg" width="960">
+</p>
+
+### Work with evidence from ChatGPT
+
+The same command surface supports multi-step compliance work: inspect a run, reopen it, attach evidence,
+return it to its intended state, and explain the resulting evidence assessment.
+
+<table>
+  <tr>
+    <td width="50%" align="center">
+      <img alt="Reopen a compliance test run and attach evidence from ChatGPT" src="assets/readme/chatgpt-2.jpg">
+    </td>
+    <td width="50%" align="center">
+      <img alt="Review the updated run and evidence relevance in ChatGPT" src="assets/readme/chatgpt-1.jpg">
+    </td>
+  </tr>
+  <tr>
+    <td align="center"><sub>Reopen the run and attach new evidence</sub></td>
+    <td align="center"><sub>Confirm the result and understand evidence relevance</sub></td>
+  </tr>
+</table>
+
+## Command surface
+
+Run `ciphrix <resource> --help` for its actions and `ciphrix <resource> <action> --help` for the flags of
+one command. Installed help is authoritative. The complete generated reference is available at
+[`skills/ciphrix/references/commands.md`](skills/ciphrix/references/commands.md) and checked for drift in CI.
+
+<details>
+<summary>Browse the command groups</summary>
+
+| Command                                            | What it does                                                                   |
+| -------------------------------------------------- | ------------------------------------------------------------------------------ |
+| `ciphrix login` · `logout`                         | Authorize this device or revoke its session.                                   |
+| `ciphrix context get` · `status` · `set` · `reset` | Read and maintain Business and Operating Context.                              |
+| `ciphrix document …`                               | Browse, read, create, edit, version, submit, approve, and delete documents.    |
+| `ciphrix test …`                                   | Inspect tests, links, runs and evidence; attach items and record results.      |
+| `ciphrix framework …`                              | Browse applied frameworks and work with clauses and mappings.                  |
+| `ciphrix control …`                                | Inspect controls, ownership, applicability, design requirements, and mappings. |
+| `ciphrix asset …`                                  | Maintain the asset register, mappings, and tags.                               |
+| `ciphrix vendor …`                                 | Maintain vendors and their attached files.                                     |
+| `ciphrix risk …`                                   | Maintain risks, treatment, scores, controls, and files.                        |
+| `ciphrix check …`                                  | Operate monitoring checks, resources, runs, findings, and integrations.        |
+| `ciphrix job status <jobId>`                       | Follow background work started by another command.                             |
+
+</details>
+
+## Safe by default
+
+- Credentials use the operating system keychain by default and are isolated by API environment.
+- Device authorization keeps passwords out of the terminal and CLI process.
+- API traffic requires HTTPS unless insecure HTTP is explicitly enabled for local testing.
+- Redirects are not followed for API calls or uploads.
+- Destructive and consequential actions require confirmation unless `--yes` is explicitly supplied.
+- JSON output is undecorated and suitable for programs and agents.
+- Requests time out, responses are size-limited, and local evidence uploads reject symbolic links and
+  files over 50 MiB.
+
+Please report vulnerabilities privately as described in [SECURITY.md](SECURITY.md).
+
+## Non-production and advanced configuration
+
+The CLI does not use a general configuration file. An API base is selected in this order:
+
+1. The command's `--api-url` option.
+2. `CIPHRIX_API_URL`.
+3. The built-in production API.
+
+Credentials are stored separately for each API base, so local or test authentication does not replace
+the production credential.
+
+| Setting                                                      | Purpose                                                                                                                                       |
+| ------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------- |
+| `--api-url <url>` / `CIPHRIX_API_URL`                        | Use a different API base, including its public API prefix.                                                                                    |
+| `--allow-insecure-http` / `CIPHRIX_ALLOW_INSECURE_HTTP=true` | Explicitly permit HTTP for trusted local testing. Never use it across an untrusted network.                                                   |
+| `CIPHRIX_CREDENTIAL_STORE=file`                              | Use a permission-restricted plaintext credential file for intentional headless or test environments. The keychain remains the normal default. |
+| `ciphrix login --no-open`                                    | Print the authorization link without opening a browser.                                                                                       |
+| `ciphrix logout --local-only`                                | Remove only this device's stored credential without contacting the API.                                                                       |
+| `NO_COLOR` / `FORCE_COLOR`                                   | Apply standard terminal colour controls. Piped output is never coloured.                                                                      |
+
+API URLs containing user information, query strings, or fragments are rejected. If remote logout fails,
+the local credential is retained so revocation can be retried; `--local-only` is always an explicit choice.
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) and [AGENTS.md](AGENTS.md). `main` is always releasable, and every
+change lands through a short-lived pull request with required review and automated checks.
+
+## License
+
+[Apache-2.0](LICENSE)

package/dist/actions.d.ts

@@ -0,0 +1,19 @@
+import { type CliIO } from './io.js';
+import { type ToolContext } from './toolSurface.js';
+export interface ApplyOptions {
+    ctx: ToolContext;
+    io: CliIO;
+    toolName: string;
+    input: unknown;
+    fallback: string;
+    yes?: boolean | undefined;
+    confirm?: ((question: string) => Promise<boolean>) | undefined;
+}
+/**
+ * Runs a tool, handling the two-step confirm contract when the tool requires it.
+ *
+ * - Tools that need no confirmation apply on the first call.
+ * - Tools that require confirmation: the first call is a preflight (summary + token), the user is asked
+ *   once, then the change is applied with the token and an idempotency key.
+ */
+export declare const applyTool: ({ ctx, io, toolName, input, fallback, yes, confirm, }: ApplyOptions) => Promise<Record<string, unknown> | null>;

package/dist/actions.js

@@ -0,0 +1,30 @@
+import { randomUUID } from 'node:crypto';
+import { promptConfirm, writeLine } from './io.js';
+import { asRecord, asText, callTool, errorMessage } from './toolSurface.js';
+/**
+ * Runs a tool, handling the two-step confirm contract when the tool requires it.
+ *
+ * - Tools that need no confirmation apply on the first call.
+ * - Tools that require confirmation: the first call is a preflight (summary + token), the user is asked
+ *   once, then the change is applied with the token and an idempotency key.
+ */
+export const applyTool = async ({ ctx, io, toolName, input, fallback, yes = false, confirm, }) => {
+    const ask = confirm ?? ((question) => promptConfirm(io, question));
+    const idempotencyKey = randomUUID();
+    const first = await callTool(ctx, toolName, input, { idempotencyKey });
+    if (first.status !== 'ok')
+        throw new Error(errorMessage(first, fallback));
+    const confirmation = asRecord(asRecord(first.meta).confirmation);
+    const token = asText(confirmation.token);
+    if (!token)
+        return first;
+    writeLine(io.stdout, asText(confirmation.summary, 'Apply this change?'));
+    if (!yes && !(await ask('Apply this change?'))) {
+        writeLine(io.stdout, 'Cancelled.');
+        return null;
+    }
+    const result = await callTool(ctx, toolName, input, { confirmationToken: token, idempotencyKey });
+    if (result.status !== 'ok')
+        throw new Error(errorMessage(result, fallback));
+    return result;
+};

package/dist/api.d.ts

@@ -0,0 +1,27 @@
+export declare class ApiError extends Error {
+    readonly status: number;
+    readonly code: string | undefined;
+    constructor(message: string, status: number, code?: string | undefined);
+}
+export interface RequestOptions {
+    method?: string;
+    body?: unknown;
+    token?: string;
+}
+export interface ApiClient {
+    readonly baseUrl: string;
+    request(path: string, options?: RequestOptions): Promise<unknown>;
+}
+/** Default time allowed for an API request, including reading its response body. */
+export declare const DEFAULT_REQUEST_TIMEOUT_MS = 30000;
+/** Maximum decoded response size buffered by the CLI. */
+export declare const DEFAULT_MAX_RESPONSE_BYTES: number;
+export interface RequestLimits {
+    timeoutMs?: number;
+    maxResponseBytes?: number;
+}
+export declare const withRequestTimeout: <T>(timeoutMs: number, operation: (signal: AbortSignal) => Promise<T>) => Promise<T>;
+export declare const readLimitedText: (response: Response, maxBytes: number) => Promise<string>;
+/** Never follow redirects for requests that may carry credentials or user data. */
+export declare const fetchWithoutRedirects: (url: string, init: RequestInit) => Promise<Response>;
+export declare const createApiClient: (baseUrl: string, limits?: RequestLimits) => ApiClient;

package/dist/api.js

@@ -0,0 +1,180 @@
+export class ApiError extends Error {
+    status;
+    code;
+    constructor(message, status, code = undefined) {
+        super(message);
+        this.name = 'ApiError';
+        this.status = status;
+        this.code = code;
+    }
+}
+/** Default time allowed for an API request, including reading its response body. */
+export const DEFAULT_REQUEST_TIMEOUT_MS = 30_000;
+/** Maximum decoded response size buffered by the CLI. */
+export const DEFAULT_MAX_RESPONSE_BYTES = 10 * 1024 * 1024;
+export const withRequestTimeout = async (timeoutMs, operation) => {
+    const controller = new AbortController();
+    let timedOut = false;
+    const timer = setTimeout(() => {
+        timedOut = true;
+        controller.abort();
+    }, timeoutMs);
+    try {
+        return await operation(controller.signal);
+    }
+    catch (error) {
+        if (timedOut) {
+            throw new Error(`Request timed out after ${Math.ceil(timeoutMs / 1000)} seconds.`, {
+                cause: error,
+            });
+        }
+        throw error;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+};
+export const readLimitedText = async (response, maxBytes) => {
+    const declaredLength = Number(response.headers.get('content-length'));
+    if (Number.isFinite(declaredLength) && declaredLength > maxBytes) {
+        await response.body?.cancel().catch(() => undefined);
+        throw new Error(`The API response exceeds the ${maxBytes}-byte size limit.`);
+    }
+    if (!response.body)
+        return '';
+    const reader = response.body.getReader();
+    const chunks = [];
+    let total = 0;
+    try {
+        while (true) {
+            const readPromise = Promise.resolve(reader.read());
+            const result = await readPromise.then((value) => value);
+            const { done, value } = result;
+            if (done)
+                break;
+            if (!value)
+                continue;
+            total += value.byteLength;
+            if (total > maxBytes) {
+                await reader.cancel().catch(() => undefined);
+                throw new Error(`The API response exceeds the ${maxBytes}-byte size limit.`);
+            }
+            chunks.push(value);
+        }
+    }
+    finally {
+        reader.releaseLock();
+    }
+    const buffer = new Uint8Array(total);
+    let offset = 0;
+    for (const chunk of chunks) {
+        buffer.set(chunk, offset);
+        offset += chunk.byteLength;
+    }
+    return new TextDecoder().decode(buffer);
+};
+/** Never follow redirects for requests that may carry credentials or user data. */
+export const fetchWithoutRedirects = async (url, init) => {
+    const response = await fetch(url, { ...init, redirect: 'manual' });
+    if (response.status >= 300 && response.status < 400) {
+        throw new Error('The API redirected this request. Redirects are blocked to protect credentials and data; update the API URL to the final HTTPS endpoint.');
+    }
+    return response;
+};
+const errorPayload = (data) => {
+    if (!data || typeof data !== 'object')
+        return { message: undefined, code: undefined, details: [] };
+    const record = data;
+    const nested = record.error && typeof record.error === 'object'
+        ? record.error
+        : undefined;
+    const message = typeof record.message === 'string'
+        ? record.message
+        : typeof record.error_description === 'string'
+            ? record.error_description
+            : typeof record.error === 'string'
+                ? record.error
+                : typeof nested?.message === 'string'
+                    ? nested.message
+                    : undefined;
+    const code = typeof record.error === 'string'
+        ? record.error
+        : typeof record.code === 'string'
+            ? record.code
+            : typeof nested?.code === 'string'
+                ? nested.code
+                : undefined;
+    const details = Array.isArray(nested?.details) ? nested?.details : [];
+    return { message, code, details };
+};
+/**
+ * Turn structured error details into something a user can act on: the ambiguous candidates, or the fields
+ * that failed validation. A bare "use a code" or "invalid input" is not actionable.
+ */
+const withDetails = (message, code, details) => {
+    if (details.length === 0)
+        return message;
+    const asRecord = (item) => item && typeof item === 'object' ? item : {};
+    const text = (value) => (typeof value === 'string' ? value : '');
+    if (code === 'ambiguous') {
+        const candidates = details
+            .map((item) => {
+            const record = asRecord(item);
+            const candidateCode = text(record.code);
+            const candidateName = text(record.name);
+            if (candidateCode && candidateName)
+                return `${candidateCode}  ${candidateName}`;
+            return candidateCode || candidateName || text(record.id);
+        })
+            .filter((value) => value !== '');
+        return candidates.length > 0 ? `${message}\n  ${candidates.join('\n  ')}` : message;
+    }
+    if (code === 'invalid_input') {
+        const problems = details
+            .map((item) => {
+            const record = asRecord(item);
+            const path = text(record.path) || text(record.field) || text(record.instancePath);
+            const problem = text(record.message) || text(record.error);
+            if (path && problem)
+                return `${path}: ${problem}`;
+            return problem || path;
+        })
+            .filter((value) => value !== '');
+        return problems.length > 0 ? `${message}\n  ${problems.join('\n  ')}` : message;
+    }
+    return message;
+};
+export const createApiClient = (baseUrl, limits = {}) => ({
+    baseUrl,
+    request: async (path, options = {}) => {
+        const timeoutMs = limits.timeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS;
+        const maxResponseBytes = limits.maxResponseBytes ?? DEFAULT_MAX_RESPONSE_BYTES;
+        const { method = 'GET', body, token } = options;
+        const headers = {};
+        if (body !== undefined)
+            headers['content-type'] = 'application/json';
+        if (token)
+            headers.authorization = `Bearer ${token}`;
+        const init = { method, headers };
+        if (body !== undefined)
+            init.body = JSON.stringify(body);
+        return withRequestTimeout(timeoutMs, async (signal) => {
+            const response = await fetchWithoutRedirects(`${baseUrl}${path}`, { ...init, signal });
+            const text = await readLimitedText(response, maxResponseBytes);
+            let data = null;
+            if (text) {
+                try {
+                    data = JSON.parse(text);
+                }
+                catch {
+                    data = text;
+                }
+            }
+            if (!response.ok) {
+                const { message, code, details } = errorPayload(data);
+                throw new ApiError(withDetails(message || `Request failed with status ${response.status}`, code, details), response.status, code);
+            }
+            return data;
+        });
+    },
+});

package/dist/banner.d.ts

@@ -0,0 +1,2 @@
+import type { Theme } from './theme.js';
+export declare const formatBanner: (theme: Theme) => string;