@sentropic/h2a-cli 0.1.1 → 0.1.6

package/dist/bin.js

@@ -1,4 +1,32 @@
 #!/usr/bin/env node
-import { runCli } from "./cli.js";
-process.exitCode = runCli();
+import { runCli, runMcpServe } from "./cli.js";
+const argv = process.argv.slice(2);
+// `mcp-serve` is an async long-running JSON-RPC loop on real stdin; the
+// synchronous `runCli` cannot represent it. We dispatch directly here.
+if (argv[0] === "mcp-serve") {
+    const flags = {};
+    for (let i = 1; i < argv.length; i++) {
+        const token = argv[i];
+        if (token.startsWith("--")) {
+            const key = token.slice(2);
+            const next = argv[i + 1];
+            if (next !== undefined && !next.startsWith("--")) {
+                flags[key] = next;
+                i++;
+            }
+            else {
+                flags[key] = "true";
+            }
+        }
+    }
+    runMcpServe(flags).then((rc) => {
+        process.exitCode = rc;
+    }, (err) => {
+        process.stderr.write(`h2a mcp-serve: fatal: ${err.message}\n`);
+        process.exitCode = 1;
+    });
+}
+else {
+    process.exitCode = runCli(argv);
+}
 //# sourceMappingURL=bin.js.map

package/dist/bin.js.map

@@ -1 +1 @@
-{"version":3,"file":"bin.js","sourceRoot":"","sources":["../src/bin.ts"],"names":[],"mappings":";AAEA,OAAO,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAElC,OAAO,CAAC,QAAQ,GAAG,MAAM,EAAE,CAAC"}
+{"version":3,"file":"bin.js","sourceRoot":"","sources":["../src/bin.ts"],"names":[],"mappings":";AAEA,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAE/C,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;AAEnC,wEAAwE;AACxE,uEAAuE;AACvE,IAAI,IAAI,CAAC,CAAC,CAAC,KAAK,WAAW,EAAE,CAAC;IAC5B,MAAM,KAAK,GAA2B,EAAE,CAAC;IACzC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACrC,MAAM,KAAK,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC;QACtB,IAAI,KAAK,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC;YAC3B,MAAM,GAAG,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;YAC3B,MAAM,IAAI,GAAG,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;YACzB,IAAI,IAAI,KAAK,SAAS,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC;gBACjD,KAAK,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC;gBAClB,CAAC,EAAE,CAAC;YACN,CAAC;iBAAM,CAAC;gBACN,KAAK,CAAC,GAAG,CAAC,GAAG,MAAM,CAAC;YACtB,CAAC;QACH,CAAC;IACH,CAAC;IACD,WAAW,CAAC,KAAK,CAAC,CAAC,IAAI,CACrB,CAAC,EAAE,EAAE,EAAE;QACL,OAAO,CAAC,QAAQ,GAAG,EAAE,CAAC;IACxB,CAAC,EACD,CAAC,GAAG,EAAE,EAAE;QACN,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,yBAA0B,GAAa,CAAC,OAAO,IAAI,CAAC,CAAC;QAC1E,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC;IACvB,CAAC,CACF,CAAC;AACJ,CAAC;KAAM,CAAC;IACN,OAAO,CAAC,QAAQ,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC;AAClC,CAAC"}

package/dist/cli-contract.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Stable JSON output contract + exit-code table for the `h2a` CLI surface.
+ *
+ * This module is the **machine-readable counterpart** of `docs/cli-contract.md`
+ * (DEC-034). Every verb exposed by `runCli` appears here with:
+ *
+ * - `outputShape`: one of three canonical envelopes (see below).
+ * - `exitCodes`: the subset of {0,1,2,3} the verb can return.
+ * - `requiredFlags` / `optionalFlags`: documented flag surface.
+ *
+ * Envelope shapes
+ * ---------------
+ *
+ * - `resource` — single entity persisted/loaded by the verb. Stdout is the
+ *   bare JSON of that entity (no `{ok}` wrapper). Examples: a negotiation
+ *   record, a journal entry, an envelope, the MCP config snippet for a host.
+ * - `list` — bare JSON array. Examples: `discover`, `inbox read`,
+ *   `negotiate journal`.
+ * - `action` — confirmation envelope `{ ok: true, ...details }` for verbs
+ *   that perform side effects but do not return a natural entity (`init`,
+ *   `register`, `inbox put`, `outbox put`, `negotiate stabilize`,
+ *   `host setup --write`).
+ * - `text` — non-JSON human output (currently only `--help`).
+ * - `stream` — long-running framed transport (`mcp-serve`, JSON-RPC 2.0
+ *   over stdio); no single stdout payload.
+ *
+ * Exit-code table
+ * ---------------
+ *
+ * - `0` success.
+ * - `1` user error — bad flag, missing required flag, invalid JSON,
+ *   validation failure on user input, unknown verb/subverb/host.
+ * - `2` runtime/state error — store conflict or business-rule failure
+ *   (negotiation not found, already open, already stabilized, signature
+ *   fails verification, quorum incomplete, broken journal, divergent
+ *   pre-existing config file).
+ * - `3` I/O / OS error — file unreadable, permission denied, write
+ *   refused by the filesystem.
+ *
+ * DEC-034 freezes this contract. Future breaking changes require a new DEC
+ * and a major version bump on `@sentropic/h2a-cli`.
+ */
+export type H2ACliOutputShape = "resource" | "list" | "action" | "text" | "stream";
+export type H2ACliExitCode = 0 | 1 | 2 | 3;
+export interface H2ACliVerbContract {
+    /** Full verb path, space-separated (`"negotiate open"`, `"host setup"`). */
+    readonly verb: string;
+    /** Canonical envelope of the stdout payload on success. */
+    readonly outputShape: H2ACliOutputShape;
+    /** Exit codes this verb can produce. Always includes `0` for success. */
+    readonly exitCodes: readonly H2ACliExitCode[];
+    /** Flags required for a happy-path invocation. */
+    readonly requiredFlags: readonly string[];
+    /** Flags accepted but optional. */
+    readonly optionalFlags: readonly string[];
+    /** One-line human description. */
+    readonly description: string;
+}
+export declare const H2A_CLI_VERB_CONTRACTS: readonly H2ACliVerbContract[];
+/** Map of verb-path → contract for O(1) lookups in tests and tooling. */
+export declare const H2A_CLI_VERB_CONTRACT_BY_VERB: ReadonlyMap<string, H2ACliVerbContract>;
+//# sourceMappingURL=cli-contract.d.ts.map

package/dist/cli-contract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli-contract.d.ts","sourceRoot":"","sources":["../src/cli-contract.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AAEH,MAAM,MAAM,iBAAiB,GAAG,UAAU,GAAG,MAAM,GAAG,QAAQ,GAAG,MAAM,GAAG,QAAQ,CAAC;AAEnF,MAAM,MAAM,cAAc,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;AAE3C,MAAM,WAAW,kBAAkB;IACjC,4EAA4E;IAC5E,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,2DAA2D;IAC3D,QAAQ,CAAC,WAAW,EAAE,iBAAiB,CAAC;IACxC,yEAAyE;IACzE,QAAQ,CAAC,SAAS,EAAE,SAAS,cAAc,EAAE,CAAC;IAC9C,kDAAkD;IAClD,QAAQ,CAAC,aAAa,EAAE,SAAS,MAAM,EAAE,CAAC;IAC1C,mCAAmC;IACnC,QAAQ,CAAC,aAAa,EAAE,SAAS,MAAM,EAAE,CAAC;IAC1C,kCAAkC;IAClC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC9B;AAED,eAAO,MAAM,sBAAsB,EAAE,SAAS,kBAAkB,EA2MtD,CAAC;AAEX,yEAAyE;AACzE,eAAO,MAAM,6BAA6B,EAAE,WAAW,CAAC,MAAM,EAAE,kBAAkB,CAEjF,CAAC"}

package/dist/cli-contract.js

@@ -0,0 +1,239 @@
+/**
+ * Stable JSON output contract + exit-code table for the `h2a` CLI surface.
+ *
+ * This module is the **machine-readable counterpart** of `docs/cli-contract.md`
+ * (DEC-034). Every verb exposed by `runCli` appears here with:
+ *
+ * - `outputShape`: one of three canonical envelopes (see below).
+ * - `exitCodes`: the subset of {0,1,2,3} the verb can return.
+ * - `requiredFlags` / `optionalFlags`: documented flag surface.
+ *
+ * Envelope shapes
+ * ---------------
+ *
+ * - `resource` — single entity persisted/loaded by the verb. Stdout is the
+ *   bare JSON of that entity (no `{ok}` wrapper). Examples: a negotiation
+ *   record, a journal entry, an envelope, the MCP config snippet for a host.
+ * - `list` — bare JSON array. Examples: `discover`, `inbox read`,
+ *   `negotiate journal`.
+ * - `action` — confirmation envelope `{ ok: true, ...details }` for verbs
+ *   that perform side effects but do not return a natural entity (`init`,
+ *   `register`, `inbox put`, `outbox put`, `negotiate stabilize`,
+ *   `host setup --write`).
+ * - `text` — non-JSON human output (currently only `--help`).
+ * - `stream` — long-running framed transport (`mcp-serve`, JSON-RPC 2.0
+ *   over stdio); no single stdout payload.
+ *
+ * Exit-code table
+ * ---------------
+ *
+ * - `0` success.
+ * - `1` user error — bad flag, missing required flag, invalid JSON,
+ *   validation failure on user input, unknown verb/subverb/host.
+ * - `2` runtime/state error — store conflict or business-rule failure
+ *   (negotiation not found, already open, already stabilized, signature
+ *   fails verification, quorum incomplete, broken journal, divergent
+ *   pre-existing config file).
+ * - `3` I/O / OS error — file unreadable, permission denied, write
+ *   refused by the filesystem.
+ *
+ * DEC-034 freezes this contract. Future breaking changes require a new DEC
+ * and a major version bump on `@sentropic/h2a-cli`.
+ */
+export const H2A_CLI_VERB_CONTRACTS = [
+    // --- meta / help ---
+    {
+        verb: "--help",
+        outputShape: "text",
+        exitCodes: [0],
+        requiredFlags: [],
+        optionalFlags: [],
+        description: "Print human-readable usage. Same as `help` and no-argv invocation."
+    },
+    // --- registry / hosts / tooling discovery ---
+    {
+        verb: "hosts",
+        outputShape: "list",
+        exitCodes: [0],
+        requiredFlags: [],
+        optionalFlags: [],
+        description: "List host descriptors known to this CLI (codex, claude, gemini)."
+    },
+    {
+        verb: "mcp-tools",
+        outputShape: "list",
+        exitCodes: [0],
+        requiredFlags: [],
+        optionalFlags: [],
+        description: "List canonical MCP tool names exposed by the built-in server."
+    },
+    // --- setup / registry ---
+    {
+        verb: "init",
+        outputShape: "action",
+        exitCodes: [0, 1, 3],
+        requiredFlags: [],
+        optionalFlags: ["root"],
+        description: "Create the `<root>/.h2a/` local-files store layout (DEC-031)."
+    },
+    {
+        verb: "register",
+        outputShape: "action",
+        exitCodes: [0, 1, 2],
+        requiredFlags: ["json"],
+        optionalFlags: ["root"],
+        description: "Append an H2AActorRegistration to `registry/instances.jsonl`."
+    },
+    {
+        verb: "discover",
+        outputShape: "list",
+        exitCodes: [0, 1],
+        requiredFlags: [],
+        optionalFlags: ["root", "role", "scope"],
+        description: "List registered instances, optionally filtered by role/scope."
+    },
+    // --- negotiation ---
+    {
+        verb: "negotiate open",
+        outputShape: "resource",
+        exitCodes: [0, 1, 2],
+        requiredFlags: ["json"],
+        optionalFlags: ["root"],
+        description: "Open a new negotiation, persisting its `state.json`."
+    },
+    {
+        verb: "negotiate status",
+        outputShape: "resource",
+        exitCodes: [0, 1, 2],
+        requiredFlags: ["id", "status"],
+        optionalFlags: ["root"],
+        description: "Transition a negotiation to a new status (draft / proposed / countered / stabilized / closed)."
+    },
+    {
+        verb: "negotiate event",
+        outputShape: "resource",
+        exitCodes: [0, 1, 2],
+        requiredFlags: ["id", "json"],
+        optionalFlags: ["root", "causation-id", "correlation-id"],
+        description: "Append an arbitrary event payload to the negotiation journal."
+    },
+    {
+        verb: "negotiate offer",
+        outputShape: "resource",
+        exitCodes: [0, 1, 2],
+        requiredFlags: ["id", "instance", "artifact"],
+        optionalFlags: ["root", "event-id", "causation-id", "correlation-id"],
+        description: "Append a `propose` journal entry carrying the offered artifact body."
+    },
+    {
+        verb: "negotiate counter",
+        outputShape: "resource",
+        exitCodes: [0, 1, 2],
+        requiredFlags: ["id", "instance", "artifact"],
+        optionalFlags: ["root", "event-id", "causation-id", "correlation-id"],
+        description: "Append a `counter` journal entry carrying a counter-offer artifact body."
+    },
+    {
+        verb: "negotiate sign",
+        outputShape: "resource",
+        exitCodes: [0, 1, 2, 3],
+        requiredFlags: ["id", "instance", "artifact", "private-key"],
+        optionalFlags: ["root", "event-id", "causation-id", "correlation-id"],
+        description: "Sign the canonical artifact hash with the given ed25519 PEM private key and append a signature event."
+    },
+    {
+        verb: "negotiate stabilize",
+        outputShape: "action",
+        exitCodes: [0, 1, 2],
+        requiredFlags: ["id"],
+        optionalFlags: ["root", "event-id"],
+        description: "Verify quorum + signatures, persist the winning artifact in write-once form (DEC-033), and mark the negotiation stabilized."
+    },
+    {
+        verb: "negotiate journal",
+        outputShape: "list",
+        exitCodes: [0, 1, 2],
+        requiredFlags: ["id"],
+        optionalFlags: ["root"],
+        description: "Read and verify the full hash-chained journal for a negotiation."
+    },
+    // --- mailboxes ---
+    {
+        verb: "inbox put",
+        outputShape: "action",
+        exitCodes: [0, 1, 2],
+        requiredFlags: ["instance", "json"],
+        optionalFlags: ["root"],
+        description: "Drop an H2A envelope into the inbox of an instance."
+    },
+    {
+        verb: "inbox read",
+        outputShape: "list",
+        exitCodes: [0, 1],
+        requiredFlags: ["instance"],
+        optionalFlags: ["root"],
+        description: "List the inbox envelopes of an instance (oldest first)."
+    },
+    {
+        verb: "inbox pop",
+        outputShape: "resource",
+        exitCodes: [0, 1, 2],
+        requiredFlags: ["instance", "envelope"],
+        optionalFlags: ["root"],
+        description: "Remove and return a specific envelope from an instance's inbox."
+    },
+    {
+        verb: "outbox put",
+        outputShape: "action",
+        exitCodes: [0, 1, 2],
+        requiredFlags: ["instance", "json"],
+        optionalFlags: ["root"],
+        description: "Drop an H2A envelope into the outbox of an instance (append-only)."
+    },
+    {
+        verb: "outbox read",
+        outputShape: "list",
+        exitCodes: [0, 1],
+        requiredFlags: ["instance"],
+        optionalFlags: ["root"],
+        description: "List the outbox envelopes of an instance (oldest first)."
+    },
+    // --- store maintenance (DEC-036) ---
+    {
+        verb: "store migrate",
+        outputShape: "action",
+        exitCodes: [0, 1],
+        requiredFlags: [],
+        optionalFlags: ["root", "from", "to", "dry-run"],
+        description: "Migrate the local-files store schema between known versions (DEC-036). V1→V1 is a no-op (`changed:false`). Unknown --from or --to → exit 1."
+    },
+    // --- MCP transport ---
+    {
+        verb: "mcp-serve",
+        outputShape: "stream",
+        exitCodes: [0, 1],
+        requiredFlags: [],
+        optionalFlags: ["root"],
+        description: "Run the built-in MCP server speaking JSON-RPC 2.0 over stdio (long-running)."
+    },
+    // --- host wiring ---
+    {
+        verb: "host setup",
+        outputShape: "resource",
+        exitCodes: [0, 1, 2, 3],
+        requiredFlags: ["host"],
+        optionalFlags: ["root", "print", "write", "force"],
+        description: "Render or merge the `mcpServers.h2a` snippet for a host (codex|claude). `--print` (default) emits the snippet as a resource on stdout; `--write <file>` switches the verb to an action envelope and merges/creates the target config file."
+    },
+    {
+        verb: "host status",
+        outputShape: "action",
+        exitCodes: [0, 1],
+        requiredFlags: [],
+        optionalFlags: ["host"],
+        description: "Report each host's wave + adapter/setup/scenario-shipped flags (DEC-037/044). Output is `{ ok: true, hosts: [{host, wave, mcpAdapterShipped, hostSetupShipped, hostScenarioShipped, summary}] }`. Filter to a single host with `--host <name>`; unknown host → exit 1."
+    }
+];
+/** Map of verb-path → contract for O(1) lookups in tests and tooling. */
+export const H2A_CLI_VERB_CONTRACT_BY_VERB = new Map(H2A_CLI_VERB_CONTRACTS.map((c) => [c.verb, c]));
+//# sourceMappingURL=cli-contract.js.map

package/dist/cli-contract.js.map

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

package/dist/cli.d.ts

@@ -1,7 +1,58 @@
+/**
+ * `h2a` CLI dispatcher — stable JSON output contract + exit-code table (DEC-034).
+ *
+ * Output shapes
+ * -------------
+ * Every JSON-emitting verb writes ONE of three canonical envelopes on stdout:
+ *
+ * - **resource** — bare JSON of a single entity. Used by verbs that return the
+ *   persisted/loaded record itself (`negotiate open`, `negotiate status`,
+ *   `negotiate event`, `negotiate offer`, `negotiate counter`, `negotiate sign`,
+ *   `inbox pop`, `host setup --print`).
+ * - **list** — bare JSON array. Used by `hosts`, `mcp-tools`, `discover`,
+ *   `inbox read`, `outbox read`, `negotiate journal`.
+ * - **action** — `{ ok: true, ...details }` confirmation envelope. Used by
+ *   verbs that perform side effects without a natural entity to return
+ *   (`init`, `register`, `inbox put`, `outbox put`, `negotiate stabilize`,
+ *   `host setup --write`).
+ *
+ * Stderr lines always follow `h2a <verb> [sub]: <message>` so callers can
+ * grep them deterministically. The `mcp-serve` verb is a long-running
+ * JSON-RPC 2.0 stdio transport and does not fit the envelope contract.
+ *
+ * Exit codes
+ * ----------
+ *
+ * - `0` — success.
+ * - `1` — user error: missing/bad flag, invalid JSON, validation failure on
+ *   caller-supplied data, unknown verb/subverb/host.
+ * - `2` — runtime/state error: store conflict or business-rule violation
+ *   (negotiation not found, already open, already stabilized, signature
+ *   fails verification, quorum incomplete, broken journal, divergent
+ *   pre-existing config file refusing merge without `--force`).
+ * - `3` — I/O / OS error: file unreadable, permission denied, write
+ *   refused by the filesystem.
+ *
+ * The full machine-readable manifest lives in `./cli-contract.ts`
+ * (`H2A_CLI_VERB_CONTRACTS`). Human-readable reference: `docs/cli-contract.md`.
+ */
 export interface H2ACliStreams {
     stderr: Pick<typeof process.stderr, "write">;
     stdout: Pick<typeof process.stdout, "write">;
+    cwd?: () => string;
 }
 export declare function renderCliHelp(): string;
+/**
+ * `h2a mcp-serve` binds directly to the real process std streams because it
+ * is a long-running JSON-RPC loop. The test-friendly `streams` interface
+ * (write-only) cannot express a readable stdin; tests cover `runMcpStdio`
+ * with `PassThrough` streams instead of going through this verb.
+ */
+export declare function runMcpServe(flags: Record<string, string>, io?: {
+    stdin: NodeJS.ReadableStream;
+    stdout: NodeJS.WritableStream;
+    stderr: NodeJS.WritableStream;
+    cwd?: () => string;
+}): Promise<number>;
 export declare function runCli(argv?: readonly string[], streams?: H2ACliStreams): number;
 //# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAKA,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,IAAI,CAAC,OAAO,OAAO,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC7C,MAAM,EAAE,IAAI,CAAC,OAAO,OAAO,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC9C;AAQD,wBAAgB,aAAa,IAAI,MAAM,CActC;AAED,wBAAgB,MAAM,CACpB,IAAI,GAAE,SAAS,MAAM,EAA0B,EAC/C,OAAO,GAAE,aAGR,GACA,MAAM,CAqBR"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AA0CH,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,IAAI,CAAC,OAAO,OAAO,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC7C,MAAM,EAAE,IAAI,CAAC,OAAO,OAAO,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC7C,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CACpB;AAQD,wBAAgB,aAAa,IAAI,MAAM,CAwCtC;AAsaD;;;;;GAKG;AACH,wBAAsB,WAAW,CAC/B,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAC7B,EAAE,GAAE;IACF,KAAK,EAAE,MAAM,CAAC,cAAc,CAAC;IAC7B,MAAM,EAAE,MAAM,CAAC,cAAc,CAAC;IAC9B,MAAM,EAAE,MAAM,CAAC,cAAc,CAAC;IAC9B,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CAKpB,GACA,OAAO,CAAC,MAAM,CAAC,CAejB;AA0RD,wBAAgB,MAAM,CACpB,IAAI,GAAE,SAAS,MAAM,EAA0B,EAC/C,OAAO,GAAE,aAGR,GACA,MAAM,CA8BR"}