@honua/react 0.1.4-beta.0 → 0.1.9-beta.0

package/control-plane/commands/types.d.ts

@@ -0,0 +1,226 @@
+/**
+ * Shared application-command contract for the Honua control plane.
+ *
+ * Every surface — the `honua` CLI, the MCP server, Studio, and direct JS —
+ * invokes the *same* {@link HonuaCommand} objects. A transport adapts input
+ * and output only: it parses its own argument shape into the command's
+ * declared JSON-schema input, hands the result to
+ * `HonuaCommandRuntime.execute`, and renders the returned
+ * {@link HonuaCommandReceipt}. Domain sequencing (read-modify-write,
+ * optimistic-concurrency checks, job hand-off) and the dry-run projection live
+ * on the command, never on the transport.
+ *
+ * Authorization is deliberately **not** modelled here beyond an echo. The
+ * command layer carries no administrator credential of its own, refuses
+ * caller-supplied authority headers and the request-identity headers it derives
+ * itself (see `assertNoAuthorityOverride` and `assertNoCommandKeyOverride` in
+ * `./runtime.js`), and stamps every receipt `authorization:
+ * "server-enforced"`. A client cannot approve its own publication by choosing
+ * a different transport because no transport can express approval at all —
+ * the shared command inputs have no approval field and every command input
+ * schema is closed (`additionalProperties: false`).
+ *
+ * @experimental Part of the `@honua/sdk-js/control-plane` experimental
+ *   entrypoint; not yet covered by the SDK's semver contract.
+ * @module
+ */
+import type { QueryMethod } from "../../core/types.js";
+import type { HonuaStudioLifecycleClient } from "../../studio/lifecycle-client.js";
+import type { HonuaControlPlaneClient } from "../client.js";
+import type { HonuaControlPlaneRequestOptions, HonuaEntityValidators, HonuaProblemDetails } from "../types.js";
+import type { HonuaCommandValidationIssue } from "./errors.js";
+/**
+ * JSON-Schema subset used to describe a command's input.
+ *
+ * Structurally the same dialect `HonuaAgentToolDefinition.inputSchema` uses
+ * (`src/agent-tools/index.ts`) so MCP tool schemas, CLI help, and Studio forms
+ * can all project from one description. It is redeclared here rather than
+ * imported so the control-plane split package does not pull in the agent-tool
+ * runtime. `src/` is deliberately zod-free.
+ */
+export interface HonuaCommandJsonSchema {
+    readonly type?: string | readonly string[];
+    readonly description?: string;
+    readonly enum?: readonly unknown[];
+    readonly format?: string;
+    readonly properties?: Readonly<Record<string, HonuaCommandJsonSchema>>;
+    readonly items?: HonuaCommandJsonSchema;
+    readonly required?: readonly string[];
+    readonly additionalProperties?: boolean | HonuaCommandJsonSchema;
+    readonly minLength?: number;
+    readonly maxLength?: number;
+    readonly minimum?: number;
+    readonly maximum?: number;
+    readonly default?: unknown;
+}
+/**
+ * `read` commands never mutate and never carry an idempotency key on the
+ * wire; `action` commands do both. Mirrors `HonuaAgentToolMode`.
+ */
+export type HonuaCommandMode = "read" | "action";
+/**
+ * Terminal state recorded on a {@link HonuaCommandReceipt}. Mirrors
+ * `HonuaAgentToolStatus` and adds `cancelled` for `AbortSignal` aborts.
+ */
+export type HonuaCommandStatus = "ok" | "dry-run" | "denied" | "cancelled" | "error";
+/** Surfaces that may invoke a command. Recorded, never trusted. */
+export declare const HONUA_COMMAND_TRANSPORTS: readonly ["cli", "mcp", "studio", "sdk"];
+/** One of {@link HONUA_COMMAND_TRANSPORTS}. */
+export type HonuaCommandTransport = (typeof HONUA_COMMAND_TRANSPORTS)[number];
+/**
+ * Acting identity and tenant, as the *caller claims them*.
+ *
+ * These values are echoed onto the receipt so a downstream audit join can line
+ * a receipt up with the server-side record. They are never sent as request
+ * headers and never used to make a local authorization decision — the server
+ * derives the real acting identity from the credential on the
+ * {@link HonuaControlPlaneClient}'s underlying `HonuaClient`.
+ */
+export interface HonuaCommandIdentity {
+    /** Acting principal id as claimed by the caller. */
+    readonly actor?: string;
+    /** Tenant / workspace-owner echo. */
+    readonly tenantId?: string;
+    /** OAuth scope ceiling the caller believes it holds, sorted for determinism. */
+    readonly scopes?: readonly string[];
+}
+/** Stable pointer to the resource a command read or affected. */
+export interface HonuaCommandResourceRef {
+    /** Resource kind, e.g. `map-package`, `import-job`, `connection`. */
+    readonly type: string;
+    /** Server-assigned identifier, when the server returned one. */
+    readonly id?: string;
+    /** Owning workspace, when scoped. */
+    readonly workspaceId?: string;
+    /** Absolute or root-relative link the server returned for the resource. */
+    readonly href?: string;
+}
+/**
+ * The request a command *would* issue. Produced by {@link HonuaCommand.plan},
+ * recorded on every receipt, and the only thing a dry run evaluates — a dry
+ * run never reaches {@link HonuaCommand.execute}, so no transport can
+ * accidentally execute while previewing.
+ *
+ * Deliberately carries no request body: command inputs can contain connection
+ * credentials, and a plan is rendered to terminals and logs.
+ *
+ * It also carries no **resource link**. `resourceRef.href` is dropped by the
+ * runtime before the plan reaches a receipt, so a dry run — which is nothing
+ * but this plan — cannot print a URL for a resource that was never created or
+ * published (honua-sdk-js#1426). A link appears on a receipt only when the
+ * *server* returned one to {@link HonuaCommand.execute}.
+ */
+export interface HonuaCommandPlan {
+    readonly method: QueryMethod;
+    /** Path relative to the client's base path, exactly as the command will call it. */
+    readonly path: string;
+    /**
+     * One-line human summary for CLI/Studio previews.
+     *
+     * A command builds this from its own input, so it can name a source URL. The
+     * runtime passes it through the SDK's credential recognizer before it reaches
+     * a receipt, so a presigned URL or an embedded secret is withheld rather than
+     * persisted into an audit record. Commands should still prefer identifiers to
+     * URLs here.
+     */
+    readonly summary: string;
+    /** Resource this request addresses. Any `href` is stripped by the runtime. */
+    readonly resourceRef?: HonuaCommandResourceRef;
+}
+/** What {@link HonuaCommand.execute} returns to the runtime. */
+export interface HonuaCommandOutcome<TOutput> {
+    readonly output: TOutput;
+    /** Overrides `ok`; use `denied` when the server durably recorded a refusal. */
+    readonly status?: Extract<HonuaCommandStatus, "ok" | "denied">;
+    readonly resourceRef?: HonuaCommandResourceRef;
+    readonly validators?: HonuaEntityValidators;
+    readonly problem?: HonuaProblemDetails;
+}
+/** Discriminating tag on {@link HonuaCommandReceipt}. */
+export declare const HONUA_COMMAND_RECEIPT_KIND: "honua.command.receipt.v1";
+/**
+ * Deterministic, serializable record of one command invocation.
+ *
+ * Two equivalent calls made from different transports produce identical
+ * receipts apart from {@link HonuaCommandReceipt.transport}; `auditKey` hashes
+ * the transport-independent projection so a server-side audit join can match
+ * them. Nothing here is time-, host-, or random-dependent: `idempotencyKey`
+ * and `correlationId` are derived from the command id, the canonicalized
+ * input, and the tenant unless the caller supplies them.
+ */
+export interface HonuaCommandReceipt<TOutput = unknown> {
+    readonly kind: typeof HONUA_COMMAND_RECEIPT_KIND;
+    readonly commandId: string;
+    readonly mode: HonuaCommandMode;
+    readonly status: HonuaCommandStatus;
+    readonly idempotencyKey: string;
+    readonly correlationId: string;
+    readonly identity: HonuaCommandIdentity;
+    /** Surface that issued the call. Recorded for audit; excluded from `auditKey`. */
+    readonly transport: HonuaCommandTransport;
+    /** Always `server-enforced`: the command layer makes no authorization decision. */
+    readonly authorization: "server-enforced";
+    readonly plan: HonuaCommandPlan;
+    readonly resourceRef?: HonuaCommandResourceRef;
+    readonly validators?: HonuaEntityValidators;
+    readonly problem?: HonuaProblemDetails;
+    readonly output?: TOutput;
+    /** Hash of the transport-independent projection. Equal across transports. */
+    readonly auditKey: string;
+}
+/** Per-invocation context handed to {@link HonuaCommand.plan} and `execute`. */
+export interface HonuaCommandContext<TInput> {
+    /** Input after schema validation. */
+    readonly input: TInput;
+    readonly controlPlane: HonuaControlPlaneClient;
+    /**
+     * Studio lifecycle client, present only when the host supplied one. Commands
+     * in the `studio.*` namespace throw a `transport` `HonuaCommandError` when it
+     * is absent rather than reaching for a second credential.
+     */
+    readonly studio?: HonuaStudioLifecycleClient;
+    readonly identity: HonuaCommandIdentity;
+    readonly transport: HonuaCommandTransport;
+    readonly idempotencyKey: string;
+    readonly correlationId: string;
+    readonly dryRun: boolean;
+    readonly signal?: AbortSignal;
+    /**
+     * Request options for the underlying resource client, with `Idempotency-Key`
+     * (action commands only), `If-Match`, the caller's `AbortSignal`, and the
+     * caller's remaining headers already threaded. The headers that reach here
+     * can carry neither an authority claim nor a command-owned key: both
+     * families are refused before `plan` runs.
+     */
+    requestOptions(overrides?: HonuaControlPlaneRequestOptions): HonuaControlPlaneRequestOptions;
+}
+/**
+ * One idempotent application command, shared verbatim by every transport.
+ *
+ * @typeParam TInput - Validated input shape, described by `inputSchema`.
+ * @typeParam TOutput - Value carried on the receipt's `output`.
+ */
+export interface HonuaCommand<TInput, TOutput> {
+    /** Stable dotted id, e.g. `map-package.publish`. */
+    readonly id: string;
+    readonly title: string;
+    readonly description: string;
+    readonly mode: HonuaCommandMode;
+    /** Resource kind this command addresses; used for the receipt's `resourceRef`. */
+    readonly resourceKind: string;
+    readonly inputSchema: HonuaCommandJsonSchema;
+    /**
+     * Cross-field checks the JSON schema cannot express ("one of these two is
+     * required"). Called by the runtime after schema validation and **before**
+     * `plan`, so a dry run can never approve an input the real invocation would
+     * reject. Must be pure. Return an empty array when the input is valid.
+     */
+    validate?(input: TInput): readonly HonuaCommandValidationIssue[];
+    /** Describe the request without issuing it. Must be pure and side-effect free. */
+    plan(context: HonuaCommandContext<TInput>): HonuaCommandPlan;
+    /** Issue the request. Never called during a dry run. */
+    execute(context: HonuaCommandContext<TInput>): Promise<HonuaCommandOutcome<TOutput>>;
+}
+/** Any command, for registries and transport dispatch tables. */
+export type HonuaAnyCommand = HonuaCommand<any, any>;
+//# sourceMappingURL=types.d.ts.map

package/control-plane/commands/types.d.ts.map

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

package/control-plane/commands/types.js

@@ -0,0 +1,30 @@
+/**
+ * Shared application-command contract for the Honua control plane.
+ *
+ * Every surface — the `honua` CLI, the MCP server, Studio, and direct JS —
+ * invokes the *same* {@link HonuaCommand} objects. A transport adapts input
+ * and output only: it parses its own argument shape into the command's
+ * declared JSON-schema input, hands the result to
+ * `HonuaCommandRuntime.execute`, and renders the returned
+ * {@link HonuaCommandReceipt}. Domain sequencing (read-modify-write,
+ * optimistic-concurrency checks, job hand-off) and the dry-run projection live
+ * on the command, never on the transport.
+ *
+ * Authorization is deliberately **not** modelled here beyond an echo. The
+ * command layer carries no administrator credential of its own, refuses
+ * caller-supplied authority headers and the request-identity headers it derives
+ * itself (see `assertNoAuthorityOverride` and `assertNoCommandKeyOverride` in
+ * `./runtime.js`), and stamps every receipt `authorization:
+ * "server-enforced"`. A client cannot approve its own publication by choosing
+ * a different transport because no transport can express approval at all —
+ * the shared command inputs have no approval field and every command input
+ * schema is closed (`additionalProperties: false`).
+ *
+ * @experimental Part of the `@honua/sdk-js/control-plane` experimental
+ *   entrypoint; not yet covered by the SDK's semver contract.
+ * @module
+ */
+/** Surfaces that may invoke a command. Recorded, never trusted. */
+export const HONUA_COMMAND_TRANSPORTS = ["cli", "mcp", "studio", "sdk"];
+/** Discriminating tag on {@link HonuaCommandReceipt}. */
+export const HONUA_COMMAND_RECEIPT_KIND = "honua.command.receipt.v1";

package/control-plane/commands/validate.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Structural validation for command inputs.
+ *
+ * Commands describe their input with the JSON-Schema subset in `./types.js`,
+ * the same dialect `src/agent-tools/index.ts` uses for agent tool definitions.
+ * That one description drives CLI argument checking, MCP tool schemas, Studio
+ * forms, and this validator — so an input rejected by one transport is
+ * rejected identically by all of them.
+ *
+ * The validator covers exactly the keywords the dialect declares. It is not a
+ * general JSON-Schema implementation and deliberately adds no dependency;
+ * `src/` is zod-free.
+ *
+ * @experimental
+ * @module
+ */
+import type { HonuaCommandValidationIssue } from "./errors.js";
+import type { HonuaCommandJsonSchema } from "./types.js";
+/**
+ * Validate `value` against `schema`, returning every finding.
+ *
+ * `additionalProperties: false` is the load-bearing rule for the security
+ * contract: a closed input schema is why no transport can smuggle an approval
+ * or authority field into a shared command.
+ */
+export declare function validateCommandInput(schema: HonuaCommandJsonSchema, value: unknown): HonuaCommandValidationIssue[];
+//# sourceMappingURL=validate.d.ts.map

package/control-plane/commands/validate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../../../../src/control-plane/commands/validate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,aAAa,CAAC;AAC/D,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,YAAY,CAAC;AAEzD;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,sBAAsB,EAAE,KAAK,EAAE,OAAO,GAAG,2BAA2B,EAAE,CAIlH"}

package/control-plane/commands/validate.js

@@ -0,0 +1,132 @@
+/**
+ * Structural validation for command inputs.
+ *
+ * Commands describe their input with the JSON-Schema subset in `./types.js`,
+ * the same dialect `src/agent-tools/index.ts` uses for agent tool definitions.
+ * That one description drives CLI argument checking, MCP tool schemas, Studio
+ * forms, and this validator — so an input rejected by one transport is
+ * rejected identically by all of them.
+ *
+ * The validator covers exactly the keywords the dialect declares. It is not a
+ * general JSON-Schema implementation and deliberately adds no dependency;
+ * `src/` is zod-free.
+ *
+ * @experimental
+ * @module
+ */
+/**
+ * Validate `value` against `schema`, returning every finding.
+ *
+ * `additionalProperties: false` is the load-bearing rule for the security
+ * contract: a closed input schema is why no transport can smuggle an approval
+ * or authority field into a shared command.
+ */
+export function validateCommandInput(schema, value) {
+    const issues = [];
+    validateNode(schema, value, "", issues);
+    return issues;
+}
+function validateNode(schema, value, path, issues) {
+    if (schema.type !== undefined && !matchesType(schema.type, value)) {
+        issues.push({ path, message: `expected type ${formatType(schema.type)}, received ${describe(value)}` });
+        return;
+    }
+    if (schema.enum !== undefined && !schema.enum.some((allowed) => Object.is(allowed, value))) {
+        issues.push({ path, message: `expected one of ${schema.enum.map((entry) => JSON.stringify(entry)).join(", ")}` });
+        return;
+    }
+    if (typeof value === "string")
+        validateString(schema, value, path, issues);
+    if (typeof value === "number")
+        validateNumber(schema, value, path, issues);
+    if (Array.isArray(value)) {
+        if (schema.items) {
+            value.forEach((entry, index) => validateNode(schema.items, entry, `${path}[${index}]`, issues));
+        }
+        return;
+    }
+    if (isPlainRecord(value))
+        validateObject(schema, value, path, issues);
+}
+function validateString(schema, value, path, issues) {
+    if (schema.minLength !== undefined && value.length < schema.minLength) {
+        issues.push({ path, message: `expected at least ${schema.minLength} character(s)` });
+    }
+    if (schema.maxLength !== undefined && value.length > schema.maxLength) {
+        issues.push({ path, message: `expected at most ${schema.maxLength} character(s)` });
+    }
+}
+function validateNumber(schema, value, path, issues) {
+    if (schema.minimum !== undefined && value < schema.minimum) {
+        issues.push({ path, message: `expected >= ${schema.minimum}` });
+    }
+    if (schema.maximum !== undefined && value > schema.maximum) {
+        issues.push({ path, message: `expected <= ${schema.maximum}` });
+    }
+}
+function validateObject(schema, value, path, issues) {
+    const properties = schema.properties ?? {};
+    for (const required of schema.required ?? []) {
+        if (value[required] === undefined) {
+            issues.push({ path: join(path, required), message: "is required" });
+        }
+    }
+    for (const [key, child] of Object.entries(value)) {
+        if (child === undefined)
+            continue;
+        const propertySchema = properties[key];
+        if (propertySchema) {
+            validateNode(propertySchema, child, join(path, key), issues);
+            continue;
+        }
+        if (schema.additionalProperties === false) {
+            issues.push({ path: join(path, key), message: "is not an accepted property of this command" });
+            continue;
+        }
+        if (typeof schema.additionalProperties === "object") {
+            validateNode(schema.additionalProperties, child, join(path, key), issues);
+        }
+    }
+}
+function matchesType(type, value) {
+    const types = typeof type === "string" ? [type] : type;
+    return types.some((entry) => matchesSingleType(entry, value));
+}
+function matchesSingleType(type, value) {
+    switch (type) {
+        case "string":
+            return typeof value === "string";
+        case "number":
+            return typeof value === "number" && Number.isFinite(value);
+        case "integer":
+            return typeof value === "number" && Number.isInteger(value);
+        case "boolean":
+            return typeof value === "boolean";
+        case "array":
+            return Array.isArray(value);
+        case "object":
+            return isPlainRecord(value);
+        case "null":
+            return value === null;
+        default:
+            return true;
+    }
+}
+function formatType(type) {
+    return typeof type === "string" ? type : type.join(" | ");
+}
+function describe(value) {
+    if (value === null)
+        return "null";
+    if (value === undefined)
+        return "undefined";
+    if (Array.isArray(value))
+        return "array";
+    return typeof value;
+}
+function isPlainRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function join(path, key) {
+    return path ? `${path}.${key}` : key;
+}