@ciphrix/cli 0.1.0 → 0.2.0

package/dist/commands/capabilities.js

@@ -0,0 +1,288 @@
+import { Command, Option } from 'commander';
+import { applyTool } from '../actions.js';
+import { ApiError } from '../api.js';
+import { promptConfirm, writeLine } from '../io.js';
+import { ManifestError, resolveBinding } from '../manifest.js';
+import { asRecord, callTool, resolveToolContext } from '../toolSurface.js';
+import { FileInputError, readUploadFile, stageLocalFile } from '../upload.js';
+import { capabilities, onboardingOperations, } from './capabilityDefinitions.js';
+export class RenderedCommandError extends Error {
+}
+class InputError extends Error {
+}
+const retryHelp = 'Writes use one idempotency key per operation. Reuse that key/input for retries; never bypass an unknown outcome with a new key. Confirmed calls also require valid confirmation: a fresh invocation re-preflights and may be blocked by changed state or expiry. Inspect current state/jobs when uncertain. Replayed status packs and signed URLs are snapshots, not refreshed reads.';
+const parseJson = (text) => {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        throw new InputError('Expected strict JSON. Quote string values as JSON strings.');
+    }
+};
+const inputFor = async (spec, args, options) => {
+    const input = {};
+    for (const [index, name] of (spec.argument?.split(' ') ?? []).entries())
+        input[name] = args[index];
+    for (const field of spec.fields) {
+        const value = options[field.flag.replace(/-([a-z])/g, (_match, letter) => letter.toUpperCase())];
+        if (value === undefined)
+            continue;
+        if (Object.hasOwn(input, field.field))
+            throw new InputError(`Conflicting options for ${field.field}.`);
+        let parsed = value;
+        if (field.kind === 'clear')
+            parsed = null;
+        if (field.kind === 'integer') {
+            if (typeof value !== 'string' || !/^\d+$/.test(value) || !Number.isSafeInteger(Number(value)))
+                throw new InputError(`--${field.flag} requires a nonnegative integer.`);
+            parsed = Number(value);
+        }
+        if (field.kind === 'json') {
+            if (typeof value !== 'string')
+                throw new InputError('Expected a JSON argument.');
+            parsed = parseJson(value);
+        }
+        if (field.kind === 'file') {
+            if (typeof value !== 'string')
+                throw new InputError('Expected a regular file path.');
+            parsed = parseJson((await readUploadFile(value, 1024 * 1024)).toString('utf8'));
+            if (!Array.isArray(parsed))
+                throw new InputError(`--${field.flag} requires a JSON array.`);
+        }
+        input[field.field] = parsed;
+    }
+    if (spec.path === 'access entry bulk-update')
+        input.operation = 'update';
+    return input;
+};
+const partialFailure = (value, depth = 0) => {
+    if (depth > 32 || !value || typeof value !== 'object')
+        return false;
+    if (Array.isArray(value))
+        return value.some((item) => partialFailure(item, depth + 1));
+    const record = asRecord(value);
+    if (['failures', 'failed', 'unmerged'].some((key) => Array.isArray(record[key]) && record[key].length > 0))
+        return true;
+    return Object.values(record).some((child) => partialFailure(child, depth + 1));
+};
+const execute = async (ctx, tool, input, io, options) => {
+    if (tool.effect === 'read') {
+        if (options.yes || options.idempotencyKey !== undefined)
+            throw new InputError('Write controls do not apply to a read operation.');
+        return callTool(ctx, tool.name, input);
+    }
+    if (tool.confirmation === 'none' && options.yes)
+        throw new InputError('This write applies immediately and does not accept --yes.');
+    if (tool.confirmation !== 'none' && !options.yes && (options.json || !io.stdout.isTTY))
+        throw new InputError('This confirmed write requires --yes in JSON or non-interactive mode. No change was applied.');
+    return applyTool({
+        ctx,
+        io,
+        quiet: options.json === true,
+        toolName: tool.name,
+        input,
+        fallback: 'The operation could not be completed.',
+        yes: options.yes === true,
+        ...(typeof options.idempotencyKey === 'string' && { idempotencyKey: options.idempotencyKey }),
+        confirm: (question) => promptConfirm(io, question),
+    });
+};
+const render = (io, json, envelope, next) => {
+    if (json)
+        writeLine(io.stdout, JSON.stringify(envelope));
+    else {
+        writeLine(io.stdout, JSON.stringify(envelope.data ?? envelope, null, 2));
+        if (Array.isArray(envelope.warnings))
+            for (const warning of envelope.warnings)
+                writeLine(io.stdout, `warning: ${String(warning)}`);
+        if (asRecord(envelope.meta).truncated)
+            writeLine(io.stdout, 'Results are truncated; inspect continuation details.');
+        if (next)
+            writeLine(io.stdout, `next: ciphrix ${next} --help`);
+    }
+};
+const run = async (io, options, next, action) => {
+    let failed;
+    let applying = false;
+    try {
+        const key = options.idempotencyKey;
+        if (key !== undefined && (typeof key !== 'string' || !key.trim() || key.length > 256)) {
+            throw new InputError('The idempotency key must contain 1 to 256 characters.');
+        }
+        const envelope = await action(() => {
+            applying = true;
+        });
+        if (!envelope) {
+            if (options.json)
+                writeLine(io.stdout, JSON.stringify({ status: 'cancelled' }));
+            return;
+        }
+        render(io, options.json === true, envelope, next);
+        failed = envelope.status !== 'ok' || (applying && partialFailure(envelope.data));
+        if (failed && !options.json)
+            writeLine(io.stderr, 'The operation failed or partially applied. Inspect the returned outcomes before taking further action.');
+    }
+    catch (error) {
+        const envelope = error instanceof ApiError && asRecord(error.envelope).status === 'error'
+            ? asRecord(error.envelope)
+            : {
+                status: 'error',
+                error: {
+                    code: error instanceof InputError || error instanceof FileInputError
+                        ? 'invalid_input'
+                        : error instanceof ManifestError
+                            ? 'unsupported_capability'
+                            : error instanceof ApiError
+                                ? (error.code ?? 'http_error')
+                                : 'transport_error',
+                    message: error instanceof InputError ||
+                        error instanceof FileInputError ||
+                        error instanceof ApiError ||
+                        error instanceof ManifestError
+                        ? error.message
+                        : 'The request could not be completed. Check capabilities and inspect state before retrying a write.',
+                    ...(error instanceof ApiError && {
+                        httpStatus: error.status,
+                        ...(error.details !== undefined && { details: error.details }),
+                    }),
+                },
+            };
+        render(options.json ? io : { ...io, stdout: io.stderr }, options.json === true, envelope, '');
+        failed = true;
+    }
+    if (failed)
+        throw new RenderedCommandError();
+};
+const groupDescriptions = {
+    access: 'Access inventory, reviewed imports and assigned reviewer workflows',
+    'access resource': 'Resources, owners and asset relationships',
+    'access entry': 'Revisioned access inventory; inventory edits are not review decisions',
+    'access import': 'Your import proposals, selected-row merges and explicit discard',
+    'access review': 'Review campaigns, assigned decisions, completion and frozen outcomes',
+    agent: 'Agent activity, complete proposals and explicit human decisions',
+    'agent run': 'Grouped agent activity; findings are not completed assessments',
+    'agent action': 'Findings, reviewed proposals and declared approve/reject/choose options',
+    task: 'Your assigned stored work; discovery never completes tasks',
+    file: 'Owned local-file staging and explicit processing; no automatic downloads',
+};
+const parent = (program, path) => {
+    let current = program;
+    const traversed = [];
+    for (const segment of path) {
+        traversed.push(segment);
+        current =
+            current.commands.find((command) => command.name() === segment) ??
+                current
+                    .command(segment)
+                    .description(groupDescriptions[traversed.join(' ')] ?? `${segment} capabilities`);
+    }
+    return current;
+};
+const common = (command) => {
+    command
+        .option('--api-url <url>', 'override the API base URL')
+        .option('--json', 'emit one complete result/error envelope')
+        .option('--yes', 'confirmed writes only: explicitly authorize without prompting; rejected on reads/immediate writes')
+        .option('--idempotency-key <key>', 'writes only: key for one logical operation; reuse identical input, at most 256 characters')
+        .addHelpText('after', `\n${retryHelp}\n`);
+};
+const addField = (command, field) => {
+    const flag = `--${field.flag}${['boolean', 'clear'].includes(field.kind) ? '' : ' <value>'}`;
+    const option = new Option(flag, field.help);
+    if (field.required)
+        option.makeOptionMandatory();
+    if (field.kind === 'repeat')
+        option.argParser((value, previous = []) => [...previous, value]);
+    command.addOption(option);
+};
+export const registerCapabilities = (program, io, context = resolveToolContext) => {
+    for (const spec of capabilities) {
+        const segments = spec.path.split(' ');
+        const operation = segments.pop();
+        const command = parent(program, segments)
+            .command(operation +
+            (spec.argument
+                ? ` ${spec.argument
+                    .split(' ')
+                    .map((name) => `<${name}>`)
+                    .join(' ')}`
+                : ''))
+            .description(spec.description);
+        for (const field of spec.fields)
+            addField(command, field);
+        if (spec.path === 'access entry bulk-update')
+            command.addHelpText('after', '\nRows: [{accessId, expectedRevision}]. Only update is exposed. field selects identity, personId, role or status; value is a JSON string, or null to clear personId. Each row can fail independently.\n');
+        if (spec.path === 'access import merge')
+            command.addHelpText('after', '\nRows require proposal_row_id. Optional reviewed corrections: resource_id, resource_name, website, identity, role, person_id, resource_owner_person_id, confirm_person_match, confirm_visual_evidence, expected_revision, access_id. Preserve snake_case. Never infer match/evidence confirmations or merge all rows implicitly. Read the proposal before selecting rows.\n');
+        if (spec.path === 'access review decide')
+            command.addHelpText('after', '\nItems: [{accessId, expectedRevision, decision, comment?}]. decision is keep or revoke; comment may be null. Revoke records a removal request, not provider revocation. Complete the assigned task separately after all decisions.\n');
+        common(command);
+        command.action(async (...values) => {
+            const options = asRecord(values[values.length - 2]);
+            await run(io, options, spec.next, async (write) => {
+                const input = await inputFor(spec, values.slice(0, -2), options);
+                const ctx = await context(typeof options.apiUrl === 'string' ? options.apiUrl : undefined);
+                const tool = await resolveBinding(ctx, segments, operation);
+                if (tool.effect === 'write')
+                    write();
+                if (spec.path === 'file stage') {
+                    if (tool.effect !== 'write' || tool.confirmation !== 'none' || options.yes)
+                        throw new InputError('Staging requires an immediate write capability and does not accept --yes.');
+                    const advertised = Number(tool.limits?.maxFileBytes);
+                    const staged = await stageLocalFile(ctx, String(input.path), String(input.purpose), {
+                        maxUploadBytes: Number.isSafeInteger(advertised) && advertised > 0
+                            ? Math.min(advertised, 25 * 1024 * 1024)
+                            : 25 * 1024 * 1024,
+                    }, tool, typeof options.idempotencyKey === 'string' ? options.idempotencyKey : undefined);
+                    return staged.envelope;
+                }
+                return execute(ctx, tool, input, io, options);
+            });
+        });
+    }
+    const onboarding = program
+        .command('onboarding')
+        .description('Learn organizational context, inspect optional setup and explicitly complete the journey. Operating Context does not block completion.');
+    for (const [operation, description] of onboardingOperations)
+        onboarding.option(`--${operation}${['get-context', 'set-context', 'init-framework'].includes(operation) ? ' <value>' : ''}`, description);
+    onboarding
+        .option('--question <id>', 'questionId from the selected schema')
+        .option('--value <json>', 'strict JSON answer, including quoted JSON strings')
+        .option('--additional-context <text>', 'answer explanation; explanation-only answers are supported');
+    common(onboarding);
+    onboarding.action(async (options) => {
+        await run(io, options, 'onboarding --status', async (write) => {
+            const selected = onboardingOperations.filter(([operation]) => options[operation.replace(/-([a-z])/g, (_match, letter) => letter.toUpperCase())] !== undefined);
+            if (selected.length !== 1)
+                throw new InputError('Select exactly one onboarding operation; use --help for syntax.');
+            const operation = selected[0][0];
+            const input = {};
+            if (operation === 'get-context' || operation === 'set-context')
+                input.store = options[operation === 'get-context' ? 'getContext' : 'setContext'];
+            if (operation === 'set-context') {
+                if (typeof options.question !== 'string' ||
+                    (options.value === undefined && options.additionalContext === undefined))
+                    throw new InputError('Set context requires --question and --value and/or --additional-context.');
+                input.questionId = options.question;
+                if (options.value !== undefined) {
+                    if (typeof options.value !== 'string')
+                        throw new InputError('Expected a JSON answer.');
+                    input.value = parseJson(options.value);
+                }
+                if (options.additionalContext !== undefined)
+                    input.additionalContext = options.additionalContext;
+            }
+            else if (options.question !== undefined ||
+                options.value !== undefined ||
+                options.additionalContext !== undefined)
+                throw new InputError('Answer options require --set-context.');
+            if (operation === 'init-framework')
+                input.frameworkCode = options.initFramework;
+            const ctx = await context(typeof options.apiUrl === 'string' ? options.apiUrl : undefined);
+            const tool = await resolveBinding(ctx, ['onboarding'], operation === 'help-onboarding' ? 'help' : operation);
+            if (tool.effect === 'write')
+                write();
+            return execute(ctx, tool, input, io, options);
+        });
+    });
+};

package/dist/commands/capabilityDefinitions.d.ts

@@ -0,0 +1,17 @@
+export type FieldKind = 'text' | 'integer' | 'boolean' | 'repeat' | 'json' | 'file' | 'clear';
+export interface Field {
+    flag: string;
+    field: string;
+    help: string;
+    kind: FieldKind;
+    required: boolean;
+}
+export interface Capability {
+    path: string;
+    description: string;
+    argument?: string;
+    fields: Field[];
+    next: string;
+}
+export declare const capabilities: Capability[];
+export declare const onboardingOperations: readonly [readonly ["status", "read current journey and separate context readiness"], readonly ["help-onboarding", "read authenticated server help, all options and current status"], readonly ["get-context", "read business/operating schema and answers"], readonly ["set-context", "save one agreed business/operating answer without completing the journey"], readonly ["run-vendor-agent", "start vendor discovery; may create vendors; requires Business Context 100%"], readonly ["run-risk-agent", "start initial risk generation; requires Business Context 100%"], readonly ["init-framework", "initialize a selected framework; may consume quota and notify administrators"], readonly ["complete", "explicitly complete with Business Context 100%; operating/setup remain optional"]];

package/dist/commands/capabilityDefinitions.js

@@ -0,0 +1,191 @@
+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 = [
+    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/context.js

@@ -68,15 +68,17 @@ export const contextSetCommand = async ({ io, apiUrl, json = false, target, valu
     if (!questionId)
         throw new Error('A question id is required, for example business.company_size');
     const ctx = await resolveToolContext(apiUrl, credentialStore);
-    const envelope = await callTool(ctx, 'set_context_answer', {
-        store,
-        questionId,
-        value: parseValue(value),
+    const result = await applyTool({
+        ctx,
+        io,
+        toolName: 'set_context_answer',
+        input: { store, questionId, value: parseValue(value) },
+        fallback: 'Could not save the answer.',
     });
-    if (envelope.status !== 'ok')
-        throw new Error(errorMessage(envelope, 'Could not save the answer.'));
+    if (!result)
+        return;
     if (json) {
-        writeLine(io.stdout, JSON.stringify(envelope.data, null, 2));
+        writeLine(io.stdout, JSON.stringify(result.data, null, 2));
         return;
     }
     writeLine(io.stdout, `${io.theme.green('✓')} ${store}.${questionId} saved`);

package/dist/commands/control.d.ts

@@ -9,11 +9,13 @@ export interface ControlCommonOptions {
 export interface ControlReadOptions extends ControlCommonOptions {
     name: string;
 }
-export declare const controlListCommand: ({ io, apiUrl, json, credentialStore, search, domain, status, applicability, 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;
+    ownerId?: string | undefined;
     page?: number | undefined;
     limit?: number | undefined;
 }) => Promise<void>;

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, 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)
@@ -16,6 +18,11 @@ export const controlListCommand = async ({ io, apiUrl, json = false, credentialS
             .filter(Boolean);
     if (applicability)
         input.applicability = [applicability];
+    if (ownerId)
+        input.ownerId = ownerId
+            .split(',')
+            .map((value) => value.trim())
+            .filter(Boolean);
     if (page)
         input.page = page;
     if (limit)
@@ -81,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);
@@ -145,6 +160,16 @@ export const controlAvailableItemsCommand = async ({ io, name, itemType, apiUrl,
         const record = asRecord(item);
         return [text(record.name, text(record.id)), text(record.status)];
     }));
+    const total = typeof data.total === 'number' ? data.total : items.length;
+    const currentPage = typeof data.page === 'number' ? data.page : 1;
+    const pageSize = typeof data.limit === 'number' ? data.limit : 25;
+    writePageFooter(io, {
+        shown: items.length,
+        total,
+        page: currentPage,
+        limit: pageSize,
+        hasMore: data.hasMore === true || currentPage * pageSize < total,
+    });
 };
 export const controlUpdateCommand = async ({ io, name, apiUrl, json = false, yes = false, confirm, credentialStore, changes, }) => {
     if (Object.keys(changes).length === 0) {

package/dist/commands/framework.d.ts

@@ -24,9 +24,11 @@ export declare const frameworkClausesCommand: ({ io, framework, apiUrl, json, cr
 }) => Promise<void>;
 export declare const clauseGetCommand: ({ io, framework, clause, apiUrl, json, credentialStore, }: ClauseTargetOptions) => Promise<void>;
 export declare const clauseItemsCommand: ({ io, framework, clause, apiUrl, json, credentialStore, }: ClauseTargetOptions) => Promise<void>;
-export declare const clauseAvailableItemsCommand: ({ io, framework, clause, itemType, apiUrl, json, credentialStore, search, }: ClauseTargetOptions & {
+export declare const clauseAvailableItemsCommand: ({ io, framework, clause, itemType, apiUrl, json, credentialStore, search, page, limit, }: ClauseTargetOptions & {
     itemType: string;
     search?: string | undefined;
+    page?: number | undefined;
+    limit?: number | undefined;
 }) => Promise<void>;
 export declare const clauseUpdateCommand: ({ io, framework, clause, changes, apiUrl, json, yes, credentialStore, }: ClauseTargetOptions & {
     changes: Record<string, unknown>;