@ciphrix/cli 0.1.1 → 0.3.0

package/dist/upload.js

@@ -1,4 +1,5 @@
 import { randomUUID } from 'node:crypto';
+import { getTool, ManifestError } from './manifest.js';
 import { constants } from 'node:fs';
 import { lstat, open } from 'node:fs/promises';
 import { basename } from 'node:path';
@@ -21,13 +22,15 @@ const MIME_TYPES = {
 };
 /** Maximum evidence file size read and staged by the CLI (25 MiB, matching the tool surface). */
 export const DEFAULT_MAX_UPLOAD_BYTES = 25 * 1024 * 1024;
-const readUploadFile = async (filePath, maxBytes) => {
+export class FileInputError extends Error {
+}
+export 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.');
+        throw new FileInputError('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.`);
+        throw new FileInputError(`Upload exceeds the ${maxBytes}-byte file size limit.`);
     }
     const noFollow = constants.O_NOFOLLOW ?? 0;
     const file = await open(filePath, constants.O_RDONLY | noFollow);
@@ -36,24 +39,24 @@ const readUploadFile = async (filePath, maxBytes) => {
         if (!openedStat.isFile() ||
             openedStat.dev !== initialStat.dev ||
             openedStat.ino !== initialStat.ino) {
-            throw new Error('Upload path changed while it was being opened. Please retry.');
+            throw new FileInputError('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.`);
+            throw new FileInputError(`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.`);
+                throw new FileInputError(`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.`);
+                throw new FileInputError(`Upload exceeds the ${maxBytes}-byte file size limit.`);
             chunks.push(chunk.subarray(0, bytesRead));
         }
         return Buffer.concat(chunks, total);
@@ -72,16 +75,26 @@ const contentTypeFor = (filename) => {
  * 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 = {}) => {
+export const stageLocalFile = async (ctx, filePath, purpose, limits = {}, descriptor, idempotencyKey = randomUUID()) => {
+    const tool = descriptor ?? (await getTool(ctx, 'upload_file'));
+    if (tool.effect !== 'write' || tool.confirmation !== 'none') {
+        throw new ManifestError('The server does not support immediate file staging.');
+    }
+    const properties = asRecord(tool.inputSchema.properties);
+    const purposes = asRecord(properties.purpose).enum;
+    if (!Array.isArray(purposes) || !purposes.includes(purpose))
+        throw new Error('Unsupported upload purpose.');
+    if (!idempotencyKey.trim() || idempotencyKey.length > 256)
+        throw new Error('The idempotency key must contain 1 to 256 characters.');
     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`, {
+        const response = await fetchWithoutRedirects(`${ctx.baseUrl}/tools/v1/${encodeURIComponent(tool.name)}`, {
             method: 'POST',
-            headers: { authorization: `Bearer ${ctx.token}`, 'idempotency-key': randomUUID() },
+            headers: { authorization: `Bearer ${ctx.token}`, 'idempotency-key': idempotencyKey },
             body: form,
             signal,
         });
@@ -100,7 +113,9 @@ export const uploadLocalFile = async (ctx, filePath, purpose, limits = {}) => {
             const message = typeof asRecord(envelope.error).message === 'string'
                 ? asRecord(envelope.error).message
                 : `Upload failed with status ${response.status}`;
-            throw new ApiError(message, response.status);
+            throw new ApiError(message, response.status, typeof asRecord(envelope.error).code === 'string'
+                ? String(asRecord(envelope.error).code)
+                : undefined, asRecord(envelope.error).details, envelope);
         }
         const payload = asRecord(envelope.data);
         const id = typeof payload.uploadId === 'string' ? payload.uploadId : null;
@@ -108,8 +123,13 @@ export const uploadLocalFile = async (ctx, filePath, purpose, limits = {}) => {
             throw new ApiError('Upload did not return an id', 502);
         return {
             id,
+            envelope,
             filename: typeof payload.filename === 'string' ? payload.filename : filename,
             size: typeof payload.size === 'number' ? payload.size : contents.length,
         };
     });
 };
+export const uploadLocalFile = async (ctx, filePath, purpose, limits = {}) => {
+    const { id, filename, size } = await stageLocalFile(ctx, filePath, purpose, limits);
+    return { id, filename, size };
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ciphrix/cli",
-  "version": "0.1.1",
+  "version": "0.3.0",
   "description": "Official command-line interface for the Ciphrix compliance platform.",
   "type": "module",
   "license": "Apache-2.0",

package/skills/ciphrix/SKILL.md

@@ -1,6 +1,6 @@
 ---
 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.
+description: Operate a Ciphrix compliance programme with the `ciphrix` CLI. Use for onboarding and organizational context, documents, frameworks, controls, tests and evidence, access reviews and imports, agent findings, assigned tasks, risks, vendors, assets, monitoring checks, or background jobs.
 ---
 
 # Ciphrix
@@ -83,8 +83,9 @@ Two consequences worth internalising:
   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.
+- **Intents, not hidden decisions.** An agent may coordinate explicitly authorized platform operations
+  for one user request. Each operation remains separate: stop on errors or uncertain outcomes and never
+  infer a formal decision merely because it would let the next step proceed.
 - **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
@@ -140,6 +141,44 @@ are what a check raised. `check disable` silences a check for the tenant — rec
 
 ## Guardrails
 
+**Document workflow.** Configuration, request sending, review completion, ordinary approval and
+self-approval are separate intents. Sending for approval never authorizes completing review first.
+When a recipient setter reports an already-sent request, explain the current stage and offer recall,
+configure and resend, even if the requested recipient is unchanged. Proceed only with authorization;
+recall clears the recipient, so set them again before resending rather than removing an already-cleared
+assignment. Unsent same-recipient selection reports already set. Read again between recovery steps and
+use a separate write key per operation. Employees may be assigned and complete decisions in the app;
+user discovery does not grant tool access. Use exact active User IDs/emails, not People IDs or fuzzy
+name matches. Workflow readiness is business guidance, not permission or proof of notification delivery.
+Before coordinating a document request or recovery, read
+[the workflow guide](references/document-workflows.md) for stage-specific sequencing and result handling;
+use installed help or [the generated reference](references/commands.md) for exact syntax.
+
+**Context and onboarding.** Read the server status and question schema, then save only facts agreed
+with the user. Business and Operating Context are separate. Let the server decide readiness; initial
+setup is optional and journey completion is explicit. A context save never authorizes starting agents,
+initializing a framework or completing onboarding. Replayed packs are snapshots: read status again for
+current readiness.
+
+**Access reviews and proposals.** Inventory is not a review decision. Inspect proposal rows, matches,
+source evidence and current revisions before selecting a merge. Never manufacture person-match or
+visual-evidence confirmation. Keep/revoke decisions, reviewer-task completion and campaign ending are
+distinct human intents. A revoke decision is a removal request, not provider-side revocation. Agent
+findings/options and AI assessments are advisory; inspect the complete current proposal and exact
+declared option before any explicit decision. Assigned-task discovery grants no completion authority.
+
+**Writes and uncertainty.** Discover capabilities through the server, use the exact reviewed inputs,
+and treat confirmation as explicit delegated consent, not an obstacle to automate around. Retain one
+idempotency key per logical operation; never retry unknown outcomes with a new key. The CLI performs no
+automatic write retries and does not promise confirmed recovery across invocations or expired tokens.
+Inspect state/jobs when uncertain. Batch results can partially apply; preserve and report failures.
+Advisory assessments never authorize a formal passing result.
+
+**Files.** Stage and process only the files the user selected. General processing may update context
+or create vendor records; staging alone does not authorize that processing. Imports are proposed work,
+not merged inventory. Temporary evidence/export references expire; do not forward credentials to them,
+claim bytes were downloaded when only a reference was returned, or treat a replayed URL as renewed.
+
 - 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.