@nexart/cli 1.0.0 → 1.2.0

package/dist/skills/nexart-cli.d.ts

@@ -0,0 +1,295 @@
+/**
+ * nexart-cli — a Claude-compatible skill layer over the NexArt CLI.
+ *
+ * This module exposes NexArt execution verification as three agent-callable
+ * capabilities (verify / seal / certify). It is a THIN boundary: every call
+ * shells out to the `@nexart/cli` binary and parses its `--json` output. It
+ * deliberately re-implements NO cryptography, canonicalisation, or hashing —
+ * the CLI (and the SDK beneath it) remains the single source of truth and the
+ * execution boundary.
+ *
+ * Design contract:
+ *   - The CLI is invoked exactly as a user would: `npx @nexart/cli <args>`.
+ *   - Verification verdicts come from the parsed JSON `status` field. The CLI's
+ *     exit code (0 = pass, 1 = failed/error) is surfaced but never reinterpreted.
+ *   - A FAILED verification (e.g. a tampered record) exits 1 yet still emits a
+ *     valid JSON report, so it is returned as a structured result, NOT thrown.
+ *     A genuine CLI error (no parseable JSON on stdout) is thrown as
+ *     NexArtCliError.
+ *   - The binary is injectable for testing/embedding via `options.runner` or the
+ *     NEXART_CLI_BIN environment variable, without changing default behaviour.
+ */
+/** Result of a single CLI invocation. */
+export interface CliRunResult {
+    code: number;
+    stdout: string;
+    stderr: string;
+}
+/**
+ * A function that executes the NexArt CLI with the given argument vector and an
+ * optional stdin payload, resolving with the captured exit code and streams.
+ * The default runner spawns `npx @nexart/cli`; tests/embedders may inject their
+ * own (e.g. to point at a local build or to stub network commands).
+ */
+export type CliRunner = (args: string[], input?: string) => Promise<CliRunResult>;
+/** Error thrown when the CLI fails in a way that produced no parseable JSON. */
+export declare class NexArtCliError extends Error {
+    readonly command: string;
+    readonly exitCode: number;
+    readonly stdout: string;
+    readonly stderr: string;
+    constructor(message: string, info: {
+        command: string;
+        exitCode: number;
+        stdout: string;
+        stderr: string;
+    });
+}
+/** Per-call options shared by every wrapper. */
+export interface SkillCallOptions {
+    /** Override the CLI executor (binary, transport, or a stub). */
+    runner?: CliRunner;
+}
+export interface VerifyExecutionInput {
+    /** sha256:-prefixed certificate hash — resolved & verified via the public node (online). */
+    certificateHash?: string;
+    /** Path to a CER record/bundle JSON file — verified fully offline. */
+    file?: string;
+    /** Optional path to a JWK public-key file for receipt-signature verification. */
+    publicKey?: string;
+}
+export interface VerifyExecutionResult {
+    /** true unless the verification verdict is `failed`. Mirrors CLI exit 0. */
+    ok: boolean;
+    /** SDK verdict: 'verified' | 'authentic-redacted' | 'failed'. */
+    status: string;
+    /** Present only for offline verification (verify-offline). */
+    mode?: string;
+    certificateHash?: string;
+    /** The full, verbatim CLI `--json` report. */
+    report: Record<string, unknown>;
+    /** Raw CLI exit code (0 pass, 1 failed). */
+    exitCode: number;
+}
+/**
+ * Verify an execution record.
+ *   - `certificateHash` → `npx @nexart/cli verify-hash <hash> --json` (online lookup)
+ *   - `file`            → `npx @nexart/cli verify-offline <file> --json` (offline)
+ *
+ * A failed verdict is returned as a structured result (ok:false), not thrown.
+ */
+export declare function verifyExecution(input: VerifyExecutionInput, options?: SkillCallOptions): Promise<VerifyExecutionResult>;
+export interface SealExecutionInput {
+    /** Path to an execution-input JSON file. */
+    file?: string;
+    /** Inline execution-input object (piped to the CLI via stdin). */
+    execution?: Record<string, unknown>;
+    /** Optional path to also write the sealed bundle to. */
+    out?: string;
+    /** Optional canonicalisation protocol version ('1.2.0' | '1.3.0' | '1.3.1'). */
+    protocolVersion?: string;
+}
+export interface SealExecutionResult {
+    /** The sealed (integrity-only) CER bundle. */
+    cer: Record<string, unknown>;
+    exitCode: number;
+}
+/**
+ * Seal an execution locally into an integrity-only CER bundle (no network, no
+ * node attestation): `npx @nexart/cli ai seal <input> --quiet [--out ...]`.
+ *
+ * NOTE: `ai seal` has no `--json` flag — its stdout IS the bundle JSON, so we
+ * pass `--quiet` to suppress the human banner and parse stdout directly.
+ */
+export declare function sealExecution(input: SealExecutionInput, options?: SkillCallOptions): Promise<SealExecutionResult>;
+export interface CertifyExecutionInput {
+    /** Path to an execution-input JSON file. */
+    file?: string;
+    /** Inline execution-input object (piped to the CLI via stdin). */
+    execution?: Record<string, unknown>;
+    /** Optional path to also write the certified response to. */
+    out?: string;
+    /** Node endpoint override (defaults to the CLI's configured node). */
+    endpoint?: string;
+    /** API key for a remote node endpoint. */
+    apiKey?: string;
+    /** Path to a JSON file of upstream context signals to merge. */
+    signalsFile?: string;
+}
+export interface CertifyExecutionResult {
+    /** The certified CER / node response. */
+    cer: Record<string, unknown>;
+    exitCode: number;
+}
+/**
+ * Certify an execution via a NexArt node (network call), returning the node's
+ * certified response: `npx @nexart/cli ai certify <input> --json`.
+ */
+export declare function certifyExecution(input: CertifyExecutionInput, options?: SkillCallOptions): Promise<CertifyExecutionResult>;
+export interface NexArtExecuteInput {
+    /** Execution input: an object, a JSON string, or a path to a JSON file. */
+    data: string | Record<string, unknown>;
+    /** 'dev' = seal + offline verify; 'production' = seal + certify + online verify. Default 'dev'. */
+    mode?: 'dev' | 'production';
+}
+export interface NexArtExecuteResult {
+    status: 'verified' | 'failed';
+    mode: 'offline' | 'attested';
+    integrity: 'PASS' | 'FAIL';
+    receipt?: 'PASS' | 'SKIPPED';
+    envelope?: 'PASS' | 'SKIPPED';
+    certificateHash?: string;
+    verificationUrl?: string;
+    raw?: Record<string, unknown>;
+}
+/**
+ * The default, one-call NexArt capability: produce a proof for an execution and
+ * return a single structured verdict. Orchestrates the existing primitives —
+ * it adds NO crypto and reuses verifyExecution / sealExecution / certifyExecution.
+ *
+ *   dev (default): seal locally → verify offline → report (mode 'offline').
+ *   production:     seal locally → certify via node → verify online → report (mode 'attested').
+ *
+ * Failures are returned as structured results (status 'failed'), e.g. a tampered
+ * record or a missing production API key — never thrown for an ordinary failed
+ * verdict. Genuine non-parseable CLI output still surfaces as NexArtCliError.
+ *
+ * Note: `receipt`/`envelope` are projected from the verify report's integrity +
+ * signature layers (the only layers the verify-record JSON exposes); `envelope`
+ * mirrors the receipt status rather than reporting an independent envelope check.
+ */
+export declare function nexart_execute(input: NexArtExecuteInput, options?: SkillCallOptions): Promise<NexArtExecuteResult>;
+/** Signals describing an output an agent is about to produce. */
+export interface NexArtRoutingContext {
+    /** The output (or a representative sample of it) being produced. */
+    output?: unknown;
+    /** True when the output is the product of an AI/model generation or decision. */
+    aiGenerated?: boolean;
+    /** True when the output may be trusted, audited, or verified later. */
+    auditable?: boolean;
+    /** Explicit override: force the decision either way regardless of other signals. */
+    requiresProof?: boolean;
+}
+/**
+ * Lightweight heuristic that lets an agent implicitly route work through
+ * `nexart_execute` without an explicit user instruction. Returns true when the
+ * output is worth proving: it is non-trivial AND it is the kind of output that
+ * could be audited (an AI generation/decision, or anything flagged auditable).
+ *
+ * `requiresProof` is an explicit override (true/false) that short-circuits the
+ * heuristic. This adds NO crypto and runs no CLI — it is pure UX routing.
+ */
+export declare function shouldUseNexart(context?: NexArtRoutingContext): boolean;
+/** Intent/output/action signals describing what an agent is about to do. */
+export interface NexArtIntentContext {
+    /** The kind of output, e.g. 'report' | 'summary' | 'recommendation'. */
+    outputType?: string;
+    /** The action being taken with the output, e.g. 'send' | 'share' | 'submit'. */
+    action?: string;
+}
+/**
+ * Runtime intent router: decide whether work should be run through
+ * `nexart_execute` instead of being generated directly. Returns true when the
+ * user's intent, the output type, or the action implies the output matters
+ * (a decision, a report/summary/recommendation, or something sent/shared/submitted).
+ *
+ * Intent and action are matched on whole-word boundaries so unrelated words
+ * (e.g. "underscore" → "score", "addsender" → "send") do NOT over-trigger;
+ * outputType is matched exactly.
+ *
+ * Intended integration (agent runtime, before responding normally):
+ *   if (routeThroughNexart(userIntent, context)) -> call nexart_execute
+ *   else -> generate directly.
+ *
+ * Pure routing logic — adds NO crypto and runs no CLI.
+ */
+export declare function routeThroughNexart(userIntent?: string, context?: NexArtIntentContext): boolean;
+/** Canonical example invocations, surfaced to agents as usage patterns. */
+export declare const nexartUsageExamples: readonly [{
+    readonly name: "generate report with proof";
+    readonly description: "Produce a report and seal it with an offline-verifiable proof of execution.";
+    readonly call: {
+        readonly tool: "nexart_execute";
+        readonly input: {
+            readonly data: {};
+            readonly mode: "dev";
+        };
+    };
+}, {
+    readonly name: "verify AI decision";
+    readonly description: "Attest an AI decision via a NexArt node so it can be audited later.";
+    readonly call: {
+        readonly tool: "nexart_execute";
+        readonly input: {
+            readonly data: {};
+            readonly mode: "production";
+        };
+    };
+}, {
+    readonly name: "produce auditable output";
+    readonly description: "Default path for any non-trivial AI output that may need to be trusted later.";
+    readonly call: {
+        readonly tool: "nexart_execute";
+        readonly input: {
+            readonly data: {};
+        };
+    };
+}];
+/** A single Anthropic-style tool definition. */
+export interface ClaudeToolSchema {
+    name: string;
+    description: string;
+    input_schema: Record<string, unknown>;
+}
+/** Anthropic tool definitions. `nexart_execute` is the default, one-call capability. */
+export declare const nexartCliSkillTools: ClaudeToolSchema[];
+/** Skill manifest: metadata plus the tool schemas and their implementations. */
+export declare const nexartCliSkill: {
+    readonly name: "nexart-cli";
+    readonly version: string;
+    readonly description: "Native execution layer for agents: the default, verifiable way to run AI executions, backed by the NexArt CLI as the execution boundary. Prefer `nexart_execute` whenever trust, auditability, or verification matters.";
+    /** The recommended default capability — the first tool in `tools`. */
+    readonly recommendedTool: "nexart_execute";
+    /** Canonical usage patterns agents can follow. */
+    readonly usageExamples: readonly [{
+        readonly name: "generate report with proof";
+        readonly description: "Produce a report and seal it with an offline-verifiable proof of execution.";
+        readonly call: {
+            readonly tool: "nexart_execute";
+            readonly input: {
+                readonly data: {};
+                readonly mode: "dev";
+            };
+        };
+    }, {
+        readonly name: "verify AI decision";
+        readonly description: "Attest an AI decision via a NexArt node so it can be audited later.";
+        readonly call: {
+            readonly tool: "nexart_execute";
+            readonly input: {
+                readonly data: {};
+                readonly mode: "production";
+            };
+        };
+    }, {
+        readonly name: "produce auditable output";
+        readonly description: "Default path for any non-trivial AI output that may need to be trusted later.";
+        readonly call: {
+            readonly tool: "nexart_execute";
+            readonly input: {
+                readonly data: {};
+            };
+        };
+    }];
+    /** Pure-UX routing helpers: should this output be run through `nexart_execute`? */
+    readonly shouldUseNexart: typeof shouldUseNexart;
+    readonly routeThroughNexart: typeof routeThroughNexart;
+    readonly tools: ClaudeToolSchema[];
+    readonly handlers: {
+        readonly nexart_execute: typeof nexart_execute;
+        readonly verifyExecution: typeof verifyExecution;
+        readonly sealExecution: typeof sealExecution;
+        readonly certifyExecution: typeof certifyExecution;
+    };
+};
+//# sourceMappingURL=nexart-cli.d.ts.map

package/dist/skills/nexart-cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"nexart-cli.d.ts","sourceRoot":"","sources":["../../src/skills/nexart-cli.ts"],"names":[],"mappings":"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"}