@ciphrix/cli 0.1.0

package/dist/theme.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Colour handling for terminal output.
+ *
+ * Rules:
+ * - `NO_COLOR` (non-empty) disables colour, per https://no-color.org.
+ * - `FORCE_COLOR` (non-empty, not `0`) enables colour even when piped.
+ * - Otherwise colour is enabled only for an interactive TTY.
+ *
+ * Decoration must never leak into machine-readable output; callers gate that
+ * with the resolved `color` flag.
+ */
+export interface Theme {
+    readonly color: boolean;
+    bold(text: string): string;
+    dim(text: string): string;
+    cyan(text: string): string;
+    green(text: string): string;
+    red(text: string): string;
+    yellow(text: string): string;
+    grey(text: string): string;
+}
+export declare const colorEnabled: (stream?: Pick<NodeJS.WriteStream, "isTTY">, env?: NodeJS.ProcessEnv) => boolean;
+export declare const createTheme: (color?: boolean) => Theme;
+/** Restore only unguessable markers created by this module; forged marker-like text is discarded. */
+export declare const renderThemeStyles: (text: string) => string;

package/dist/theme.js

@@ -0,0 +1,39 @@
+import { randomUUID } from 'node:crypto';
+const OPEN = '\uE000CXI';
+const CLOSE = '\uE001';
+const issuedMarkerIds = new Set();
+const STYLE_CODES = {
+    '0': '\u001B[0m',
+    '1': '\u001B[1m',
+    '2': '\u001B[2m',
+    '31': '\u001B[31m',
+    '32': '\u001B[32m',
+    '33': '\u001B[33m',
+    '36': '\u001B[36m',
+    '90': '\u001B[90m',
+};
+const isSet = (value) => typeof value === 'string' && value !== '';
+export const colorEnabled = (stream = process.stdout, env = process.env) => {
+    if (isSet(env.FORCE_COLOR) && env.FORCE_COLOR !== '0')
+        return true;
+    if (isSet(env.NO_COLOR))
+        return false;
+    return stream.isTTY === true;
+};
+const paint = (open, text, color, markerId) => color ? `${OPEN}${markerId}:${open}${CLOSE}${text}${OPEN}${markerId}:0${CLOSE}` : text;
+export const createTheme = (color = colorEnabled()) => {
+    const markerId = randomUUID();
+    issuedMarkerIds.add(markerId);
+    return {
+        color,
+        bold: (text) => paint(1, text, color, markerId),
+        dim: (text) => paint(2, text, color, markerId),
+        cyan: (text) => paint(36, text, color, markerId),
+        green: (text) => paint(32, text, color, markerId),
+        red: (text) => paint(31, text, color, markerId),
+        yellow: (text) => paint(33, text, color, markerId),
+        grey: (text) => paint(90, text, color, markerId),
+    };
+};
+/** Restore only unguessable markers created by this module; forged marker-like text is discarded. */
+export const renderThemeStyles = (text) => text.replace(/\uE000CXI([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}):(0|1|2|31|32|33|36|90)\uE001/gi, (marker, markerId, code) => issuedMarkerIds.has(markerId.toLowerCase()) ? (STYLE_CODES[code] ?? '') : '');

package/dist/toolSurface.d.ts

@@ -0,0 +1,20 @@
+import { type ApiClient } from './api.js';
+import { type CredentialStore } from './credentials.js';
+export declare const asRecord: (value: unknown) => Record<string, unknown>;
+export declare const asText: (value: unknown, fallback?: string) => string;
+/**
+ * The message a caller should see. Ambiguous-name errors carry the candidates, so they are rendered here —
+ * otherwise the user is told "use a code" without being shown which codes exist.
+ */
+export declare const errorMessage: (envelope: Record<string, unknown>, fallback: string) => string;
+export interface ToolContext {
+    baseUrl: string;
+    client: ApiClient;
+    token: string;
+}
+export declare const resolveToolContext: (apiUrl?: string, store?: CredentialStore) => Promise<ToolContext>;
+export interface CallToolOptions {
+    confirmationToken?: string | undefined;
+    idempotencyKey?: string | undefined;
+}
+export declare const callTool: (ctx: ToolContext, toolName: string, input: unknown, options?: CallToolOptions) => Promise<Record<string, unknown>>;

package/dist/toolSurface.js

@@ -0,0 +1,49 @@
+import { createApiClient } from './api.js';
+import { resolveApiBaseUrl } from './config.js';
+import { createCredentialStore } from './credentials.js';
+export const asRecord = (value) => value && typeof value === 'object' ? value : {};
+export const asText = (value, fallback = '') => typeof value === 'string' ? value : fallback;
+/**
+ * The message a caller should see. Ambiguous-name errors carry the candidates, so they are rendered here —
+ * otherwise the user is told "use a code" without being shown which codes exist.
+ */
+export const errorMessage = (envelope, fallback) => {
+    const error = asRecord(envelope.error);
+    const base = asText(error.message, fallback);
+    if (error.code === 'ambiguous' && Array.isArray(error.details)) {
+        const candidates = error.details
+            .map((item) => {
+            const record = asRecord(item);
+            const code = asText(record.code);
+            const name = asText(record.name);
+            if (code && name)
+                return `${code}  ${name}`;
+            return code || name || asText(record.id);
+        })
+            .filter((value) => value !== '');
+        if (candidates.length > 0)
+            return `${base}\n  ${candidates.join('\n  ')}`;
+    }
+    return base;
+};
+export const resolveToolContext = async (apiUrl, store) => {
+    const baseUrl = resolveApiBaseUrl({ flag: apiUrl });
+    const credentialStore = store ?? (await createCredentialStore());
+    const credential = await credentialStore.get(baseUrl);
+    if (!credential)
+        throw new Error('Not signed in. Run `ciphrix login` first.');
+    return { baseUrl, client: createApiClient(baseUrl), token: credential.token };
+};
+export const callTool = async (ctx, toolName, input, options = {}) => {
+    const body = { input };
+    if (options.confirmationToken)
+        body.confirmationToken = options.confirmationToken;
+    if (options.idempotencyKey)
+        body.idempotencyKey = options.idempotencyKey;
+    const data = await ctx.client.request(`/tools/v1/${encodeURIComponent(toolName)}`, {
+        method: 'POST',
+        token: ctx.token,
+        body,
+    });
+    return asRecord(data);
+};

package/dist/upload.d.ts

@@ -0,0 +1,18 @@
+import { type ToolContext } from './toolSurface.js';
+/** Maximum evidence file size read and staged by the CLI (50 MiB). */
+export declare const DEFAULT_MAX_UPLOAD_BYTES: number;
+export interface UploadLimits {
+    maxUploadBytes?: number;
+    timeoutMs?: number;
+    maxResponseBytes?: number;
+}
+/**
+ * Stages a local file through the `upload_file` tool and returns its upload id, ready to be attached
+ * to a target (a test run, a risk, a vendor). The file is sent as multipart to the tool surface with
+ * the bearer credential, so no cookie or CSRF token is involved.
+ */
+export declare const uploadLocalFile: (ctx: ToolContext, filePath: string, purpose: string, limits?: UploadLimits) => Promise<{
+    id: string;
+    filename: string;
+    size: number;
+}>;

package/dist/upload.js

@@ -0,0 +1,115 @@
+import { randomUUID } from 'node:crypto';
+import { constants } from 'node:fs';
+import { lstat, open } from 'node:fs/promises';
+import { basename } from 'node:path';
+import { ApiError, DEFAULT_MAX_RESPONSE_BYTES, DEFAULT_REQUEST_TIMEOUT_MS, fetchWithoutRedirects, readLimitedText, withRequestTimeout, } from './api.js';
+import { asRecord } from './toolSurface.js';
+const MIME_TYPES = {
+    '.pdf': 'application/pdf',
+    '.png': 'image/png',
+    '.jpg': 'image/jpeg',
+    '.jpeg': 'image/jpeg',
+    '.gif': 'image/gif',
+    '.txt': 'text/plain',
+    '.md': 'text/markdown',
+    '.csv': 'text/csv',
+    '.json': 'application/json',
+    '.doc': 'application/msword',
+    '.docx': 'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
+    '.xls': 'application/vnd.ms-excel',
+    '.xlsx': 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
+};
+/** Maximum evidence file size read and staged by the CLI (50 MiB). */
+export const DEFAULT_MAX_UPLOAD_BYTES = 50 * 1024 * 1024;
+const readUploadFile = async (filePath, maxBytes) => {
+    const initialStat = await lstat(filePath);
+    if (initialStat.isSymbolicLink() || !initialStat.isFile()) {
+        throw new Error('Upload path must be a regular file, not a symlink or special file.');
+    }
+    if (initialStat.size > maxBytes) {
+        throw new Error(`Upload exceeds the ${maxBytes}-byte file size limit.`);
+    }
+    const noFollow = constants.O_NOFOLLOW ?? 0;
+    const file = await open(filePath, constants.O_RDONLY | noFollow);
+    try {
+        const openedStat = await file.stat();
+        if (!openedStat.isFile() ||
+            openedStat.dev !== initialStat.dev ||
+            openedStat.ino !== initialStat.ino) {
+            throw new Error('Upload path changed while it was being opened. Please retry.');
+        }
+        if (openedStat.size > maxBytes) {
+            throw new Error(`Upload exceeds the ${maxBytes}-byte file size limit.`);
+        }
+        const chunks = [];
+        let total = 0;
+        while (true) {
+            const remaining = maxBytes + 1 - total;
+            if (remaining <= 0)
+                throw new Error(`Upload exceeds the ${maxBytes}-byte file size limit.`);
+            const chunk = Buffer.allocUnsafe(Math.min(64 * 1024, remaining));
+            const { bytesRead } = await file.read(chunk, 0, chunk.length, null);
+            if (bytesRead === 0)
+                break;
+            total += bytesRead;
+            if (total > maxBytes)
+                throw new Error(`Upload exceeds the ${maxBytes}-byte file size limit.`);
+            chunks.push(chunk.subarray(0, bytesRead));
+        }
+        return Buffer.concat(chunks, total);
+    }
+    finally {
+        await file.close();
+    }
+};
+const contentTypeFor = (filename) => {
+    const dot = filename.lastIndexOf('.');
+    const extension = dot === -1 ? '' : filename.slice(dot).toLowerCase();
+    return MIME_TYPES[extension] ?? 'application/octet-stream';
+};
+/**
+ * Stages a local file through the `upload_file` tool and returns its upload id, ready to be attached
+ * to a target (a test run, a risk, a vendor). The file is sent as multipart to the tool surface with
+ * the bearer credential, so no cookie or CSRF token is involved.
+ */
+export const uploadLocalFile = async (ctx, filePath, purpose, limits = {}) => {
+    const filename = basename(filePath);
+    const contents = await readUploadFile(filePath, limits.maxUploadBytes ?? DEFAULT_MAX_UPLOAD_BYTES);
+    const form = new FormData();
+    form.append('purpose', purpose);
+    form.append('file', new Blob([new Uint8Array(contents)], { type: contentTypeFor(filename) }), filename);
+    return withRequestTimeout(limits.timeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS, async (signal) => {
+        const response = await fetchWithoutRedirects(`${ctx.baseUrl}/tools/v1/upload_file`, {
+            method: 'POST',
+            headers: { authorization: `Bearer ${ctx.token}`, 'idempotency-key': randomUUID() },
+            body: form,
+            signal,
+        });
+        const text = await readLimitedText(response, limits.maxResponseBytes ?? DEFAULT_MAX_RESPONSE_BYTES);
+        let data = null;
+        if (text) {
+            try {
+                data = JSON.parse(text);
+            }
+            catch {
+                data = text;
+            }
+        }
+        const envelope = asRecord(data);
+        if (!response.ok || envelope.status !== 'ok') {
+            const message = typeof asRecord(envelope.error).message === 'string'
+                ? asRecord(envelope.error).message
+                : `Upload failed with status ${response.status}`;
+            throw new ApiError(message, response.status);
+        }
+        const payload = asRecord(envelope.data);
+        const id = typeof payload.uploadId === 'string' ? payload.uploadId : null;
+        if (!id)
+            throw new ApiError('Upload did not return an id', 502);
+        return {
+            id,
+            filename: typeof payload.filename === 'string' ? payload.filename : filename,
+            size: typeof payload.size === 'number' ? payload.size : contents.length,
+        };
+    });
+};

package/package.json

@@ -0,0 +1,71 @@
+{
+  "name": "@ciphrix/cli",
+  "version": "0.1.0",
+  "description": "Official command-line interface for the Ciphrix compliance platform.",
+  "type": "module",
+  "license": "Apache-2.0",
+  "bin": {
+    "ciphrix": "dist/index.js"
+  },
+  "main": "dist/index.js",
+  "exports": {
+    ".": "./dist/index.js"
+  },
+  "files": [
+    "dist",
+    "skills",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20.19.0"
+  },
+  "packageManager": "npm@11.19.1",
+  "scripts": {
+    "clean": "node scripts/clean.mjs",
+    "build": "npm run clean && tsc -p tsconfig.build.json",
+    "postbuild": "node scripts/set-bin-mode.mjs",
+    "ci": "npm run format:check && npm run lint && npm run typecheck && npm test && npm run build && npm run commands:check && npm run package:check",
+    "dev": "tsx src/index.ts",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "commands:generate": "npm run build && node scripts/generate-command-reference.mjs",
+    "commands:check": "node scripts/generate-command-reference.mjs --check",
+    "package:check": "node scripts/check-package-contents.mjs",
+    "prepack": "npm run build",
+    "audit:render": "node scripts/render-audit.mjs"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/CiphrixHQ/ciphrix-cli.git"
+  },
+  "bugs": {
+    "url": "https://github.com/CiphrixHQ/ciphrix-cli/issues"
+  },
+  "homepage": "https://github.com/CiphrixHQ/ciphrix-cli#readme",
+  "keywords": [
+    "ciphrix",
+    "compliance",
+    "cli",
+    "security"
+  ],
+  "dependencies": {
+    "@napi-rs/keyring": "^2.1.0",
+    "commander": "^15.0.0"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@types/node": "^26.6.2",
+    "eslint": "^10.11.0",
+    "prettier": "^3.9.8",
+    "tsx": "^4.23.15",
+    "typescript": "^5.9.3",
+    "typescript-eslint": "^8.70.1",
+    "vitest": "^5.0.1"
+  }
+}

package/skills/ciphrix/SKILL.md

@@ -0,0 +1,169 @@
+---
+name: ciphrix
+description: Operate a Ciphrix compliance programme with the `ciphrix` CLI. Use when an agent needs to understand or change a tenant's business context, documents, frameworks, controls, tests and evidence, risks, vendors, assets, monitoring checks, or background jobs.
+---
+
+# Ciphrix
+
+Ciphrix is an AI-native compliance automation platform. A tenant's compliance programme lives in one
+place: how the organization operates, the documents it publishes, the frameworks it has adopted, the
+tests those frameworks impose, the evidence gathered against those tests, and the risks, vendors, assets
+and monitoring checks around them. AI does the heavy lifting — generating drafts, reading evidence,
+judging relevance — but every formal decision stays with a human.
+
+You are operating that programme through `ciphrix`. You resolve things by **name or code**, you act on
+**intents**, and you report what actually happened — including when nothing did.
+
+## Operating stance
+
+Ciphrix treats compliance as a living model of how an organization operates, not a checklist assembled
+for an audit. Context explains the organization; documents state how it intends to operate; frameworks,
+clauses and controls express obligations and design; tests ask whether those claims hold; evidence and
+monitoring show what actually happened; risks, vendors and assets connect that assurance to the real
+business. Preserve those relationships when you work.
+
+Apply these principles:
+
+- **Reality before paperwork.** Start from the organization's actual context and current records. Do not
+  manufacture a polished compliance story that is unsupported by the system.
+- **Evidence before assertion.** Treat evidence, monitoring results and recorded decisions as distinct
+  facts. A document saying that a control exists is not proof that it operated, and an AI assessment is
+  not a human decision.
+- **Assistance without invented authority.** Help people understand, draft, organise and execute their
+  intent. Do not approve, attest, accept risk, record a test result or make another formal decision unless
+  the user clearly asked for that decision.
+- **The API is the source of truth.** Never infer access, state or success from expectations. Report the
+  result returned by Ciphrix, preserve distinctions such as `not found`, `not permitted`, `pending` and
+  `not assessed`, and never work around authorization.
+- **Small, attributable changes.** Read the relevant record before changing it, update only the requested
+  fields, and report the resulting state. Do not turn a narrow request into broad programme cleanup.
+- **Human-readable by default, structured when needed.** Use normal output when working with a person.
+  Use `--json` when exact fields, pagination or reliable machine processing matter; do not scrape
+  decorated terminal output.
+
+## How the platform is organised
+
+Understanding these relationships is most of the job:
+
+- **Context** is the foundation. _Business Context_ describes how the organization actually operates;
+  _Operating Context_ scopes the document and compliance programme. Everything else — discovery, document
+  generation, risk and vendor suggestions, tests — is grounded in this. Answers merge over time; a new
+  answer that conflicts with an existing one goes to review instead of silently overwriting.
+- **Frameworks** (SOC 2, ISO 27001, …) are applied to the tenant and bring their **clauses** and
+  **tests** with them.
+- A **test** is a single requirement check. Each test has **runs**, one per month — the server enforces
+  that cadence. A run collects **evidence items**: uploaded files, native documents, or results from
+  monitoring **checks**. Attaching evidence starts an AI pipeline that digests the item, judges its
+  **relevance** to the test, and produces an **assurance** view. A human then records the **run
+  result** (`passing`, `failing`, `skipped`, or back to `pending`), which is a formal decision.
+- **Documents** (the Document Library) have a lifecycle: `draft` → review → approval → `approved`. Only a
+  draft is editable; changing an approved document means creating a new version.
+- **Files** are uploads and the file system. Keep the two words apart: the Document Library holds design
+  documents; Files holds uploaded files.
+- **Risks**, **vendors** and **assets** are registers with their own state (status, owner, criticality,
+  review status, classification). Each has a stable code, and state changes are auditable. A risk also
+  carries a **treatment** (strategy and notes) and **scores**; an asset carries **tags** and is mapped to
+  controls, risks, tests and checks.
+- **Clauses** and **controls** are what you are assessed against. A clause belongs to a framework and
+  carries an applicability and a design-requirement assessment; a control is the tenant's own layer with
+  a status, an owner, an applicability and design requirements.
+- **Monitoring checks** run continuously against connected integrations and produce results on their own.
+  A check can be turned on or off for the tenant, and its run history and linked findings are readable.
+
+Two consequences worth internalising:
+
+- **AI output is never a verdict.** An assessment that hasn't been evaluated reads as _not assessed_ —
+  never a guess. Honest absence beats a plausible answer.
+- **Not found ≠ no access ≠ not assessed.** These are different facts and are reported differently.
+  Do not collapse them.
+
+## How to operate
+
+- **Names or codes, not ids.** Documents, tests, controls, clauses, risks, vendors, checks and assets are
+  addressed by their human name **or** their stable code (for example `ACME-DOC-A1B2`, `TSQ-001`,
+  `ACME-RSK-CQJ4`, `ACME-AST-M5SD`). Ids work but are never required, and you never invent one. Prefer the
+  code when a name is ambiguous.
+- **Intents, not steps.** Ask for the outcome; don't orchestrate the underlying calls. One user-facing
+  request may be several platform operations — that composition is the CLI's job, not the user's.
+- **Ask only for decisions.** Only actions that change something a person should review stop for
+  confirmation — deleting, editing content, linking, or changing a control, clause, test or asset. A
+  formal decision is its own verb (`approve`, `submit`, `test run result`) and applies directly. Everything
+  else just happens. Use `--yes` only when the user has already authorised that exact change; it removes
+  an interactive prompt, not the need for authority.
+- **Async work returns a job id.** Attaching evidence or starting AI work returns a job id immediately and
+  does not block; report the id and let the user track it with `ciphrix job status`.
+- **Rich text is Markdown.** Document content and descriptions come back as Markdown, and you supply
+  Markdown.
+- **Lists paginate.** You'll see `showing 1–25 of N · next: --page 2`; page through rather than assuming
+  you have everything.
+- **`--json`** gives the raw payload when you need exact fields.
+
+## Patterns
+
+These are the shapes of the work; run `ciphrix <resource> --help` for the exact flags.
+
+**Answer "what does the platform know about us?"** Start with context: read Business and Operating
+Context, and check what's still unanswered. This is the usual first move when a request is broad, because
+everything downstream depends on it.
+
+**Change a document.** Read it, decide whether the change is **content** or **metadata**, and act
+accordingly. If the document is approved, you must open a new version first — editing an approved document
+is refused by design. Publishing and approving are formal, separate steps; don't fold them into the edit.
+When drafting content, preserve the user's intended policy position and clearly separate current practice
+from proposals or future commitments.
+
+**Attach evidence to a test.** Find the test, then attach in one step with a local file
+(`test attach "<test>" --file <path>`). The command stages the file and attaches it; you do not need to
+stage and attach separately. Only stage a file on its own when you intend to attach it later or reuse it
+across several items. After attaching, report the returned job id and point at `ciphrix job status` — the
+relevance judgement is not instant.
+
+**See what you're assessed against.** A framework holds **clauses**; each clause carries an applicability
+and a design-requirement assessment and is mapped to tests and documents. Read the clauses, then the one
+that matters. **Controls** are the tenant's own layer over that: `control list` and `control get` show the
+status, owner, applicability and design requirements, and `control items` shows what is mapped to it.
+Ownership, applicability, design requirements and notes are yours to change; a control's or test's name and
+description belong to the catalogue and are refused for system records (use `--rename` only on custom ones).
+
+**Record a result.** A run result is a decision, not a note. `pending` is not "failed" — it reopens the
+run for more evidence. Use it deliberately.
+
+**Triage a risk, vendor or asset.** Read the current record first, then update only the fields you're
+changing. Report which fields applied and which were refused; don't assume success. A risk's treatment and
+scores are their own reads; a vendor's or risk's files are listed and changed separately from the record
+itself.
+
+**Work the checks.** `check list` shows status and compliance; `check runs` is the history; `check findings`
+are what a check raised. `check disable` silences a check for the tenant — record why with `--notes`.
+
+**Check on background work.** Anything that returns a job id is polled, not awaited.
+
+## Guardrails
+
+- Work only in the tenant and API environment the authenticated user selected. Never discover or switch
+  tenants, endpoints or credential stores by guessing.
+- Do not expose access tokens, stored credentials or sensitive response data in prose, logs or commands.
+  Prefer the OS keychain. File-based credential storage and plaintext HTTP are explicit local/testing
+  opt-ins, never defaults.
+- Do not retry denied actions through another command, weaken authorization, or reinterpret an access
+  failure as a missing record.
+- Don't edit an approved document; create a new version.
+- Don't treat `pending` as a failure or as "done".
+- Don't invent AI assessments. If it isn't evaluated, say so.
+- Don't guess when a name is ambiguous — the CLI lists the candidates and stops; take that as your answer
+  and ask the user.
+- Don't stage a file and then attach it when a single attach-with-file command exists.
+- Before a consequential write, make sure the target resolved to the intended record. After the write,
+  report the server's outcome rather than claiming success from the command exit alone.
+
+## Finding exact syntax
+
+The command surface is discoverable and always current — don't memorise or infer it:
+
+- `ciphrix --help` — the resources and verbs.
+- `ciphrix <resource> --help` — flags for a resource.
+- `ciphrix <resource> <verb> --help` — exact arguments and write semantics.
+- [`references/commands.md`](references/commands.md) — generated command and option reference for offline discovery; live help from the installed CLI remains authoritative.
+
+If the CLI does not expose the requested capability, say so. Do not call private endpoints, reproduce
+backend logic, or invent a command from this guide.