@ciphrix/cli 0.1.1 → 0.3.0

package/dist/commands/capabilityDefinitions.js

@@ -0,0 +1,244 @@
+const help = {
+    page: 'page number starting at 1',
+    limit: 'page size; server limits apply',
+    search: 'search visible records',
+    'sort-by': 'server-supported sort field',
+    'sort-order': 'sort direction: asc or desc',
+    status: 'inventory status: active or inactive; review/agent operations use their own status vocabulary',
+    name: 'record name',
+    website: 'resource website',
+    'owner-person': 'existing People ID for the resource owner',
+    'include-empty': 'include resources with no access entries',
+    'expected-updated-at': 'exact updatedAt timestamp from the latest read',
+    'clear-website': 'clear the website; conflicts with --website',
+    'clear-owner': 'clear the owner; conflicts with --owner-person',
+    resource: 'existing resource ID; repeat for multiple selections where supported',
+    person: 'existing People ID for the access identity',
+    'review-state': 'inventory: needs_review, pending, keep, revoke or inactive; reviewer task: pending or all',
+    'reviewed-before': 'ISO review-history cutoff',
+    identity: 'reported account identity; does not change authentication',
+    role: 'inventory access role; does not change product authorization',
+    'clear-person': 'leave the identity unmatched; conflicts with --person',
+    'expected-revision': 'current revision from the latest entry or reviewer-task read',
+    'rows-file': 'JSON array of explicitly selected rows; regular file, at most 1 MiB',
+    field: 'single inventory field to update on every selected row',
+    value: 'strict JSON value; quote strings as JSON and use null only where supported',
+    action: 'explicit link or unlink action',
+    upload: 'ready upload ID owned by the caller; repeat to select multiple files',
+    cursor: 'continuation cursor returned by the preceding page',
+    filter: 'proposal-row filter: all, new, unchanged, update or conflict',
+    'ids-only': 'return proposal-row IDs instead of full details',
+    'due-at': 'ISO due date/time; review creation defaults to 14 days if omitted',
+    'items-file': 'JSON array of accessId, expectedRevision, decision and optional comment; at most 1 MiB',
+    outcome: 'frozen outcome filter: keep, revoke, pending, unresolved or inactive',
+    agent: 'agent filter; repeat for multiple values',
+    'action-type': 'action-type filter; repeat for multiple values',
+    'initiator-type': 'initiator-type filter; repeat for multiple values',
+    from: 'ISO lower date/time bound',
+    to: 'ISO upper date/time bound',
+    offset: 'number of grouped results to skip',
+    job: 'existing background job ID',
+    'review-only': 'read the current human-review queue',
+    decision: 'explicit human decision: approve, reject or choose',
+    option: 'exact declared option for choose only; no delete options',
+    reason: 'human explanation for the decision',
+    state: 'active or history',
+    'task-type': 'active-task filter: all, todo, assignment or action; omit with history',
+    purpose: 'staging purpose advertised by the server; does not process the file',
+    attachment: 'evidence attachment ID belonging to the selected test run',
+    run: 'existing run ID; omit to use the current run',
+};
+const field = (flag, target = flag.replace(/-([a-z])/g, (_match, letter) => letter.toUpperCase()), kind = 'text', required = false, description = help[flag] ?? `value for ${flag}`) => ({ flag, field: target, kind, required, help: description });
+const page = () => [field('page', 'page', 'integer'), field('limit', 'limit', 'integer')];
+const sort = () => [field('sort-by'), field('sort-order')];
+const spec = (path, description, argument, fields, next) => ({ path, description, ...(argument && { argument }), fields, next });
+const filters = () => [
+    field('agent', 'agent', 'repeat'),
+    field('action-type', 'actionType', 'repeat'),
+    field('status', 'status', 'repeat', false, 'status filter; repeat for multiple values'),
+    field('initiator-type', 'initiatorType', 'repeat'),
+    field('from'),
+    field('to'),
+    field('search', 'q'),
+    field('limit', 'limit', 'integer'),
+];
+export const capabilities = [
+    ...[
+        ['document workflow set', 'Set workflow type in draft.', 'workflowType'],
+        ['document reviewer set', 'Set reviewer; sent requests must be recalled first.', 'user'],
+        ['document reviewer remove', 'Remove the reviewer from a draft.'],
+        ['document approver set', 'Set approver; sent requests must be recalled first.', 'user'],
+        ['document approver remove', 'Remove approver; sent requests must be recalled first.'],
+        [
+            'document review complete',
+            'Record an explicitly authorized review decision; does not send approval.',
+        ],
+        ['document review send-back', 'Record an explicit negative review decision; clears reviewer.'],
+        [
+            'document review cancel',
+            'Recall review request; clears reviewer. Configure and resend separately.',
+        ],
+        [
+            'document approval send',
+            'Send for approval after review; never completes review implicitly.',
+        ],
+        [
+            'document approval send-back',
+            'Record an explicit negative approval decision; clears approver.',
+        ],
+        [
+            'document approval cancel',
+            'Recall approval request; clears approver. Configure and resend separately.',
+        ],
+        [
+            'document approval self-approve',
+            'Explicit self-approval, separate from ordinary approve; no review bypass.',
+        ],
+        [
+            'document workflow return-to-draft',
+            'Return eligible advanced approval-stage document to draft; clears assignments.',
+        ],
+    ].map(([path, description, input]) => ({
+        path: path,
+        description: description,
+        argument: 'document',
+        inputAdapter: 'documentWorkflow',
+        fields: input === 'workflowType'
+            ? [field('type', 'workflowType', 'text', true, 'workflow type: simple or advanced')]
+            : input === 'user'
+                ? [
+                    field('user', 'user', 'text', true, 'exact active user email or User ID; employees may be assigned'),
+                ]
+                : [],
+        next: 'document get',
+    })),
+    spec('user list', 'List active tenant users, including employees; discovery does not change accounts.', undefined, [
+        field('search', 'search', 'text', false, 'optional name/email search, at least three characters'),
+        ...page(),
+    ], 'document reviewer set'),
+    spec('access resource list', 'List review inventory resources and owners.', undefined, [
+        ...page(),
+        field('search'),
+        ...sort(),
+        field('status'),
+        field('owner-person', 'ownerPersonId'),
+        field('include-empty', 'includeEmpty', 'boolean'),
+    ], 'access resource get'),
+    spec('access resource get', 'Read a resource and its current inventory context.', 'resourceId', [], 'access entry list'),
+    spec('access resource create', 'Create manual inventory; reconcile active reviews.', undefined, [field('name', 'name', 'text', true), field('website'), field('owner-person', 'ownerPersonId')], 'access resource get'),
+    spec('access resource update', 'Update inventory. Inactivation also deactivates child access.', 'resourceId', [
+        field('expected-updated-at'),
+        field('name'),
+        field('website'),
+        field('clear-website', 'website', 'clear'),
+        field('owner-person', 'ownerPersonId'),
+        field('clear-owner', 'ownerPersonId', 'clear'),
+        field('status'),
+    ], 'access resource get'),
+    spec('access resource link-asset', 'Link or unlink an existing asset; reconcile reviews.', 'resourceId assetId', [field('action', 'action', 'text', true)], 'access resource get'),
+    spec('access resource bulk-update', 'Update selected resource owners/statuses; inspect per-row failures.', undefined, [
+        field('resource', 'resourceIds', 'repeat', true),
+        field('owner-person', 'ownerPersonId'),
+        field('clear-owner', 'ownerPersonId', 'clear'),
+        field('status'),
+    ], 'access resource list'),
+    spec('access entry list', 'List current access inventory; no review decisions are recorded.', undefined, [
+        ...page(),
+        field('search'),
+        ...sort(),
+        field('resource', 'resourceId'),
+        field('person', 'personId'),
+        field('owner-person', 'ownerPersonId'),
+        field('status'),
+        field('review-state'),
+        field('reviewed-before'),
+    ], 'access entry get'),
+    spec('access entry get', 'Read current inventory revision and prior review outcome.', 'accessId', [], 'access entry update'),
+    spec('access entry create', 'Create manual access inventory, not a review decision.', undefined, [
+        field('resource', 'resourceId', 'text', true),
+        field('identity', 'identity', 'text', true),
+        field('role', 'role', 'text', true),
+        field('person', 'personId'),
+        field('status'),
+    ], 'access entry get'),
+    spec('access entry update', 'Update revisioned inventory; integration-owned fields stay locked.', 'accessId', [
+        field('expected-revision', 'expectedRevision', 'integer', true),
+        field('identity'),
+        field('role'),
+        field('person', 'personId'),
+        field('clear-person', 'personId', 'clear'),
+        field('status'),
+    ], 'access entry get'),
+    spec('access entry bulk-update', 'Update one field on selected revisioned entries; inspect partial failures.', undefined, [
+        field('rows-file', 'rows', 'file', true),
+        field('field', 'field', 'text', true),
+        field('value', 'value', 'json', true),
+    ], 'access entry list'),
+    spec('access import start', 'Extract a proposal from owned register_import uploads; does not merge.', undefined, [field('upload', 'uploadIds', 'repeat', true)], 'access import get'),
+    spec('access import list', 'List your unresolved imports using cursor pagination.', undefined, [field('cursor'), field('limit', 'limit', 'integer')], 'access import get'),
+    spec('access import get', 'Inspect proposal rows, matches, evidence and revisions before merging.', 'importId', [
+        field('cursor'),
+        field('limit', 'limit', 'integer'),
+        field('filter'),
+        field('search'),
+        field('ids-only', 'idsOnly', 'boolean'),
+    ], 'access import merge'),
+    spec('access import merge', 'Merge only reviewed selected rows; preserve corrections and explicit confirmations.', 'importId', [field('rows-file', 'rows', 'file', true)], 'access import get'),
+    spec('access import discard', 'Stop extraction/merge; retain successful merges and independent enrichment.', 'importId', [], 'access import list'),
+    spec('access review preview', 'Preview selected eligible owners and unresolved entries without creating work.', undefined, [field('resource', 'resourceIds', 'repeat', true), field('due-at')], 'access review start'),
+    spec('access review start', 'Create a review, reviewer tasks and assignment notifications.', undefined, [
+        field('name', 'name', 'text', true),
+        field('resource', 'resourceIds', 'repeat', true),
+        field('due-at'),
+    ], 'access review list'),
+    spec('access review list', 'Read active progress or closed/cancelled history.', undefined, [
+        field('status', 'status', 'text', false, 'review filter: active, closed, cancelled or history'),
+        ...page(),
+    ], 'access review task'),
+    spec('access review task', 'Read your assigned reviewer task, current revisions and decisions.', 'taskId', [...page(), field('search'), field('review-state')], 'access review decide'),
+    spec('access review decide', 'Record explicit keep/revoke decisions. Revoke is a removal request, not provider revocation.', 'taskId', [field('items-file', 'items', 'file', true)], 'access review task'),
+    spec('access review complete', 'Complete your assigned task after all decisions; may close a fully reviewed campaign.', 'taskId', [], 'access review list'),
+    spec('access review result', 'Read frozen outcomes; pending/unresolved never imply approval.', 'reviewId', [...page(), field('search'), field('resource', 'resourceId'), field('outcome')], 'access review export'),
+    spec('access review end', 'Explicitly close with current outcomes or cancel without a result; close reviewer tasks.', 'reviewId', [
+        field('status', 'status', 'text', true, 'closed freezes outcomes; cancelled creates no result'),
+    ], 'access review result'),
+    spec('access review export', 'Create a temporary signed CSV reference; no automatic download.', 'reviewId', [], 'access review result'),
+    spec('agent run list', 'List grouped agent activity; counts are not completed assessments.', undefined, [...filters(), field('offset', 'offset', 'integer')], 'agent action list'),
+    spec('agent action list', 'Inspect agent findings or current review work; preserve truncation and cursors.', undefined, [
+        ...filters(),
+        field('job', 'aiTaskId'),
+        field('cursor'),
+        field('review-only', 'reviewOnly', 'boolean'),
+    ], 'agent action get'),
+    spec('agent action get', 'Read a proposal and its declared options before deciding.', 'agentActionId', [], 'agent action decide'),
+    spec('agent action decide', 'Apply an explicit reviewed decision; unsupported, delete and truncated approvals are refused.', 'agentActionId', [
+        field('decision', 'decision', 'text', true),
+        field('expected-updated-at', 'expectedUpdatedAt', 'text', true),
+        field('option'),
+        field('reason'),
+    ], 'agent action get'),
+    spec('task list', 'Read your assigned stored tasks; does not refresh assignments or complete work.', undefined, [field('state'), field('task-type'), ...page()], 'task get'),
+    spec('task get', 'Read your task and its supported next capability; unsupported actions remain in the app.', 'taskId', [], 'access review task'),
+    spec('file stage', 'Stage a local regular file as your current identity; at most 25 MiB, no automatic processing.', 'path', [field('purpose', 'purpose', 'text', true)], 'file process'),
+    spec('file process', 'Process owned documents-purpose uploads. May update context or create vendors; starts background work.', undefined, [field('upload', 'uploadIds', 'repeat', true)], 'job status'),
+    spec('test run file', 'Create a temporary reference for evidence linked to this test/run; no automatic download.', 'name', [field('attachment', 'attachmentId', 'text', true), field('run', 'runId')], 'test items'),
+    spec('test run assess', 'Request advisory AI assessment; does not change the human run result.', 'name', [field('run', 'runId')], 'test get'),
+    spec('control assess', 'Request/reuse advisory assessment. A cached result may have no job ID.', 'name', [], 'control assessment'),
+    spec('control assessment', 'Read advisory assessment/progress; absence means not assessed, not compliant.', 'name', [], 'control get'),
+];
+export const onboardingOperations = [
+    ['status', 'read current journey and separate context readiness'],
+    ['help-onboarding', 'read authenticated server help, all options and current status'],
+    ['get-context', 'read business/operating schema and answers'],
+    ['set-context', 'save one agreed business/operating answer without completing the journey'],
+    [
+        'run-vendor-agent',
+        'start vendor discovery; may create vendors; requires Business Context 100%',
+    ],
+    ['run-risk-agent', 'start initial risk generation; requires Business Context 100%'],
+    [
+        'init-framework',
+        'initialize a selected framework; may consume quota and notify administrators',
+    ],
+    ['complete', 'explicitly complete with Business Context 100%; operating/setup remain optional'],
+];

package/dist/commands/control.d.ts

@@ -9,8 +9,9 @@ export interface ControlCommonOptions {
 export interface ControlReadOptions extends ControlCommonOptions {
     name: string;
 }
-export declare const controlListCommand: ({ io, apiUrl, json, credentialStore, search, domain, status, applicability, ownerId, page, limit, }: ControlCommonOptions & {
+export declare const controlListCommand: ({ io, apiUrl, json, credentialStore, search, framework, domain, status, applicability, ownerId, page, limit, }: ControlCommonOptions & {
     search?: string | undefined;
+    framework?: string[] | undefined;
     domain?: string | undefined;
     status?: string | undefined;
     applicability?: string | undefined;

package/dist/commands/control.js

@@ -2,11 +2,13 @@ import { applyTool } from '../actions.js';
 import { writeLine, writeNextHint, writePageFooter, writeTable } from '../io.js';
 import { asRecord, asText, callTool, errorMessage, resolveToolContext } from '../toolSurface.js';
 const text = (value, fallback = '-') => typeof value === 'string' ? value : typeof value === 'number' ? String(value) : fallback;
-export const controlListCommand = async ({ io, apiUrl, json = false, credentialStore, search, domain, status, applicability, ownerId, page, limit, }) => {
+export const controlListCommand = async ({ io, apiUrl, json = false, credentialStore, search, framework, domain, status, applicability, ownerId, page, limit, }) => {
     const ctx = await resolveToolContext(apiUrl, credentialStore);
     const input = {};
     if (search)
         input.search = search;
+    if (framework !== undefined)
+        input.framework = framework;
     if (domain)
         input.domain = [domain];
     if (status)
@@ -86,6 +88,14 @@ export const controlGetCommand = async ({ io, name, apiUrl, json = false, creden
             continue;
         writeLine(io.stdout, `  ${io.theme.dim(`${label}:`)} ${text(value)}`);
     }
+    if (Array.isArray(control.complianceMap) && control.complianceMap.length > 0) {
+        writeLine(io.stdout, 'Catalogue framework relationships (not a compliance assessment):');
+        writeLine(io.stdout, JSON.stringify(control.complianceMap, null, 2));
+    }
+    if (control.items !== undefined) {
+        writeLine(io.stdout, 'Linked items:');
+        writeLine(io.stdout, JSON.stringify(control.items, null, 2));
+    }
     if (typeof control.notes === 'string' && control.notes.trim() !== '') {
         writeLine(io.stdout);
         writeLine(io.stdout, control.notes);

package/dist/commands/framework.js

@@ -34,7 +34,8 @@ export const frameworkListCommand = async ({ io, apiUrl, json = false, credentia
         writeLine(io.stdout, `${io.theme.dim(`Available to add (${available.length}):`)}`);
         for (const framework of available) {
             const record = asRecord(framework);
-            writeLine(io.stdout, `  ${text(record.frameworkName ?? record.name)}`);
+            const code = asText(record.frameworkCode ?? record.code);
+            writeLine(io.stdout, `  ${code ? `${code} — ` : ''}${text(record.frameworkName ?? record.name)}`);
         }
     }
 };

package/dist/commands/policyActions.js

@@ -1,10 +1,20 @@
 import { readFile } from 'node:fs/promises';
 import { applyTool } from '../actions.js';
+import { getManifest, resolveBinding } from '../manifest.js';
 import { writeLine, writeTable } from '../io.js';
 import { asRecord, asText, callTool, errorMessage, resolveToolContext } from '../toolSurface.js';
 const UUID = /^[0-9a-f]{8}-[0-9a-f-]{27}$/i;
 const num = (value, fallback) => typeof value === 'number' ? String(value) : asText(value, fallback);
 const target = (policy) => UUID.test(policy) ? { policyId: policy } : { name: policy };
+// Retain the original named calls only for older manifests without these bindings.
+const documentWriteName = async (ctx, operation) => {
+    const manifest = await getManifest(ctx);
+    if (manifest.some((tool) => tool.cli?.operation === operation &&
+        JSON.stringify(tool.cli.group) === JSON.stringify(['document']))) {
+        return (await resolveBinding(ctx, ['document'], operation)).name;
+    }
+    return operation === 'submit' ? 'submit_document' : 'approve_document';
+};
 const renderResult = (io, json, result) => {
     if (json) {
         writeLine(io.stdout, JSON.stringify(result, null, 2));
@@ -77,7 +87,7 @@ export const policySubmitCommand = async (options) => {
     const result = await applyTool({
         ctx,
         io,
-        toolName: 'submit_document',
+        toolName: await documentWriteName(ctx, 'submit'),
         input: target(policy),
         fallback: 'Could not submit the document for review.',
         yes,
@@ -92,7 +102,7 @@ export const policyApproveCommand = async (options) => {
     const result = await applyTool({
         ctx,
         io,
-        toolName: 'approve_document',
+        toolName: await documentWriteName(ctx, 'approve'),
         input: target(policy),
         fallback: 'Could not approve the document.',
         yes,

package/dist/commands/test.d.ts

@@ -29,8 +29,8 @@ export declare const testRunCreateCommand: ({ io, name, apiUrl, json, credential
     runAt?: string | undefined;
 }) => Promise<void>;
 export declare const testRunResultCommand: ({ io, name, runId, apiUrl, json, credentialStore, status, note, }: TestReadOptions & {
-    status: string;
-    note?: string | undefined;
+    status?: string | undefined;
+    note?: string | null | undefined;
 }) => Promise<void>;
 export declare const testRunDeleteCommand: ({ io, name, runId, apiUrl, json, yes, confirm, credentialStore, }: TestActionOptions) => Promise<void>;
 export interface TestAttachOptions extends TestReadOptions {

package/dist/commands/test.js

@@ -113,6 +113,12 @@ const renderRuns = (io, runs, assurance) => {
             assuranceLabel(assurance[text(record.id)]),
         ];
     }));
+    for (const run of runs) {
+        const record = asRecord(run);
+        if (typeof record.note === 'string' && record.note.trim() !== '') {
+            writeLine(io.stdout, `Note (${text(record.id)}): ${record.note}`);
+        }
+    }
 };
 const assuranceLabel = (assessment) => assessmentLabel(assessment);
 export const testItemsCommand = async ({ io, name, runId, apiUrl, json = false, credentialStore, }) => {
@@ -162,11 +168,15 @@ export const testRunCreateCommand = async ({ io, name, apiUrl, json = false, cre
         writeLine(io.stdout, `${io.theme.green('✓')} run created: ${text(asRecord(result.data).runId)}`);
 };
 export const testRunResultCommand = async ({ io, name, runId, apiUrl, json = false, credentialStore, status, note, }) => {
+    if (status === undefined && note === undefined)
+        throw new Error('Provide --status, --note or --clear-note.');
     const ctx = await resolveToolContext(apiUrl, credentialStore);
-    const input = { name, status };
+    const input = { name };
+    if (status !== undefined)
+        input.status = status;
     if (runId)
         input.runId = runId;
-    if (note)
+    if (note !== undefined)
         input.note = note;
     const result = await applyTool({
         ctx,
@@ -180,7 +190,12 @@ export const testRunResultCommand = async ({ io, name, runId, apiUrl, json = fal
     if (json)
         writeLine(io.stdout, JSON.stringify(result.data, null, 2));
     else
-        writeLine(io.stdout, `${io.theme.green('✓')} run result: ${status}`);
+        writeLine(io.stdout, status === undefined
+            ? 'Run note updated; result unchanged.'
+            : `${io.theme.green('✓')} run result: ${status}`);
+    const jobId = asText(asRecord(result.meta).aiTaskId);
+    if (!json && jobId)
+        writeNextHint(io, `ciphrix job status ${jobId}`);
 };
 export const testRunDeleteCommand = async ({ io, name, runId, apiUrl, json = false, yes = false, confirm, credentialStore, }) => {
     if (!runId)

package/dist/constants.d.ts

@@ -4,4 +4,4 @@
  */
 export declare const CLI_NAME = "ciphrix";
 export declare const CLI_TAGLINE = "Ciphrix compliance platform CLI";
-export declare const CLI_VERSION = "0.1.1";
+export declare const CLI_VERSION = "0.3.0";

package/dist/constants.js

@@ -4,4 +4,4 @@
  */
 export const CLI_NAME = 'ciphrix';
 export const CLI_TAGLINE = 'Ciphrix compliance platform CLI';
-export const CLI_VERSION = '0.1.1';
+export const CLI_VERSION = '0.3.0';

package/dist/manifest.d.ts

@@ -0,0 +1,19 @@
+import type { ToolContext } from './toolSurface.js';
+export interface ToolDescriptor {
+    name: string;
+    version: number;
+    description: string;
+    effect: 'read' | 'write' | 'destructive';
+    confirmation: 'none' | 'preflight_confirm';
+    inputSchema: Record<string, unknown>;
+    cli?: {
+        group: string[];
+        operation: string;
+    };
+    limits?: Record<string, unknown>;
+}
+export declare class ManifestError extends Error {
+}
+export declare const getManifest: (ctx: ToolContext) => Promise<ToolDescriptor[]>;
+export declare const getTool: (ctx: ToolContext, name: string) => Promise<ToolDescriptor>;
+export declare const resolveBinding: (ctx: ToolContext, group: string[], operation: string) => Promise<ToolDescriptor>;

package/dist/manifest.js

@@ -0,0 +1,93 @@
+export class ManifestError extends Error {
+}
+const cache = new WeakMap();
+const record = (value) => value !== null && typeof value === 'object' && !Array.isArray(value)
+    ? value
+    : {};
+const checkSchema = (value, depth = 0, budget = { properties: 0 }) => {
+    if (depth > 32)
+        throw new ManifestError('Tool schema exceeds the supported nesting limit.');
+    if (Array.isArray(value)) {
+        for (const child of value)
+            checkSchema(child, depth + 1, budget);
+    }
+    else if (value && typeof value === 'object') {
+        const schema = record(value);
+        budget.properties += Object.keys(record(schema.properties)).length;
+        if (budget.properties > 1000)
+            throw new ManifestError('Tool schema exceeds the supported property limit.');
+        for (const child of Object.values(schema))
+            checkSchema(child, depth + 1, budget);
+    }
+};
+export const getManifest = (ctx) => {
+    const previous = cache.get(ctx);
+    if (previous?.baseUrl === ctx.baseUrl && previous.token === ctx.token)
+        return previous.manifest;
+    const loaded = (async () => {
+        const body = record(await ctx.client.request('/tools/v1', { token: ctx.token }));
+        if (body.manifestVersion !== 1 ||
+            body.apiVersion !== 'v1' ||
+            !Array.isArray(body.tools) ||
+            body.tools.length > 1024) {
+            throw new ManifestError('Unsupported tool manifest. Update the client or contact your administrator.');
+        }
+        const names = new Set();
+        const bindings = new Set();
+        return body.tools.map((value) => {
+            const tool = record(value);
+            if (typeof tool.name !== 'string' ||
+                !/^[a-z][a-z0-9]*(?:_[a-z0-9]+)*$/.test(tool.name) ||
+                !Number.isInteger(tool.version) ||
+                Number(tool.version) < 1 ||
+                !['read', 'write', 'destructive'].includes(String(tool.effect)) ||
+                !['none', 'preflight_confirm'].includes(String(tool.confirmation)) ||
+                typeof tool.description !== 'string' ||
+                !tool.inputSchema ||
+                typeof tool.inputSchema !== 'object' ||
+                Array.isArray(tool.inputSchema) ||
+                names.has(tool.name))
+                throw new ManifestError('Invalid or unsupported tool descriptor.');
+            names.add(tool.name);
+            checkSchema(tool.inputSchema);
+            if (tool.cli !== undefined) {
+                const binding = record(tool.cli);
+                const segment = (part) => typeof part === 'string' &&
+                    part.length <= 64 &&
+                    /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/.test(part);
+                if (!Array.isArray(binding.group) ||
+                    binding.group.length < 1 ||
+                    binding.group.length > 6 ||
+                    !binding.group.every(segment) ||
+                    !segment(binding.operation))
+                    throw new ManifestError('Invalid command binding.');
+                const key = JSON.stringify([binding.group, binding.operation]);
+                if (tool.version === 1 && bindings.has(key))
+                    throw new ManifestError('Ambiguous command binding in tool manifest.');
+                if (tool.version === 1)
+                    bindings.add(key);
+            }
+            return tool;
+        });
+    })();
+    cache.set(ctx, { baseUrl: ctx.baseUrl, token: ctx.token, manifest: loaded });
+    return loaded;
+};
+export const getTool = async (ctx, name) => {
+    const tool = (await getManifest(ctx)).find((candidate) => candidate.name === name);
+    if (!tool)
+        throw new ManifestError('This operation is not available in the current tool manifest.');
+    if (tool.version !== 1)
+        throw new ManifestError('This operation version is not supported. Update the CLI.');
+    if (tool.effect === 'destructive')
+        throw new ManifestError('This operation is not available through tools.');
+    return tool;
+};
+export const resolveBinding = async (ctx, group, operation) => {
+    const matches = (await getManifest(ctx)).filter((candidate) => candidate.cli?.operation === operation &&
+        JSON.stringify(candidate.cli.group) === JSON.stringify(group));
+    const tool = matches.find((candidate) => candidate.version === 1) ?? matches[0];
+    if (!tool)
+        throw new ManifestError('This command is not supported by the current tool manifest. Update the server or check available capabilities.');
+    return getTool(ctx, tool.name);
+};

package/dist/toolSurface.d.ts

@@ -17,12 +17,4 @@ export interface CallToolOptions {
     confirmationToken?: string | undefined;
     idempotencyKey?: string | undefined;
 }
-/**
- * The tool surface requires an idempotency key on every write and rejects a write without one. Writes
- * must go through `applyTool`, which supplies the key and handles the preflight/confirmation contract.
- * This set is the CLI-side mirror of the tool surface's write effects, so a write cannot be issued as a
- * bare read-style call again. Keep it in step with the write tools the CLI exposes (ideally derived from
- * the manifest once the CLI consumes it).
- */
-export declare const WRITE_TOOL_NAMES: ReadonlySet<string>;
 export declare const callTool: (ctx: ToolContext, toolName: string, input: unknown, options?: CallToolOptions) => Promise<Record<string, unknown>>;

package/dist/toolSurface.js

@@ -1,6 +1,7 @@
 import { createApiClient } from './api.js';
 import { resolveApiBaseUrl } from './config.js';
 import { createCredentialStore } from './credentials.js';
+import { getTool } from './manifest.js';
 export const asRecord = (value) => value && typeof value === 'object' ? value : {};
 export const asText = (value, fallback = '') => typeof value === 'string' ? value : fallback;
 /**
@@ -34,53 +35,16 @@ export const resolveToolContext = async (apiUrl, store) => {
         throw new Error('Not signed in. Run `ciphrix login` first.');
     return { baseUrl, client: createApiClient(baseUrl), token: credential.token };
 };
-/**
- * The tool surface requires an idempotency key on every write and rejects a write without one. Writes
- * must go through `applyTool`, which supplies the key and handles the preflight/confirmation contract.
- * This set is the CLI-side mirror of the tool surface's write effects, so a write cannot be issued as a
- * bare read-style call again. Keep it in step with the write tools the CLI exposes (ideally derived from
- * the manifest once the CLI consumes it).
- */
-export const WRITE_TOOL_NAMES = new Set([
-    'set_context_answer',
-    'reset_context',
-    'create_document',
-    'edit_document_content',
-    'create_document_version',
-    'update_document',
-    'submit_document',
-    'approve_document',
-    'delete_document',
-    'create_test_run',
-    'set_test_run_status',
-    'delete_test_run',
-    'attach_run_item',
-    'update_test',
-    'delete_test',
-    'update_clause',
-    'link_clause_item',
-    'update_control',
-    'link_control_item',
-    'create_vendor',
-    'update_vendor',
-    'delete_vendor',
-    'link_vendor_file',
-    'create_risk',
-    'update_risk',
-    'delete_risk',
-    'link_risk_control',
-    'link_risk_file',
-    'set_check_enabled',
-    'create_asset',
-    'update_asset',
-    'delete_asset',
-    'set_asset_tag',
-]);
 export const callTool = async (ctx, toolName, input, options = {}) => {
-    if (WRITE_TOOL_NAMES.has(toolName) && !options.idempotencyKey) {
+    const tool = await getTool(ctx, toolName);
+    if (tool.effect !== 'read' && !options.idempotencyKey) {
         throw new Error(`Refusing to call the write tool '${toolName}' without an idempotency key. Use applyTool.`);
     }
-    const body = { input };
+    if (options.idempotencyKey !== undefined &&
+        (!options.idempotencyKey.trim() || options.idempotencyKey.length > 256)) {
+        throw new Error('The idempotency key must contain 1 to 256 characters.');
+    }
+    const body = { input, version: tool.version };
     if (options.confirmationToken)
         body.confirmationToken = options.confirmationToken;
     if (options.idempotencyKey)

package/dist/upload.d.ts

@@ -1,3 +1,4 @@
+import { type ToolDescriptor } from './manifest.js';
 import { type ToolContext } from './toolSurface.js';
 /** Maximum evidence file size read and staged by the CLI (25 MiB, matching the tool surface). */
 export declare const DEFAULT_MAX_UPLOAD_BYTES: number;
@@ -6,11 +7,20 @@ export interface UploadLimits {
     timeoutMs?: number;
     maxResponseBytes?: number;
 }
+export declare class FileInputError extends Error {
+}
+export declare const readUploadFile: (filePath: string, maxBytes: number) => Promise<Buffer>;
 /**
  * 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 stageLocalFile: (ctx: ToolContext, filePath: string, purpose: string, limits?: UploadLimits, descriptor?: ToolDescriptor, idempotencyKey?: string) => Promise<{
+    id: string;
+    filename: string;
+    size: number;
+    envelope: Record<string, unknown>;
+}>;
 export declare const uploadLocalFile: (ctx: ToolContext, filePath: string, purpose: string, limits?: UploadLimits) => Promise<{
     id: string;
     filename: string;