@hediet/linkrpc-cli 0.0.2 → 0.0.3-next.20260921.2

package/README.md

@@ -133,16 +133,48 @@ LINKRPC_ENDPOINT=unix:/run/hub/hub.sock?token=abc linkrpc ls
 | ----------------------------- | ---------------------------------------------------------------------------------------------------- |
 | `ls`                          | Explore the directory referral graph and its services/interfaces. Supports exact and prefix filters, regexp `--search`, `--format pretty\|json\|jsonl`, `--watch`, `--dump <file>`, and `--dump-patches <file\|->`. |
 | `defaults`                    | Print the preset service/interface (wraps `hubrpc.defaults::get`).                                   |
+| `contract export --output <file\|-> [--service <id>] [--max-depth <n>]` | Export a complete reusable static contract from live reflection. |
 | `schema show <interfaceId>[@hash]` | Print an interface schema (wraps `hubrpc.schemas::get`). `--method <name>`, `--json`.           |
 | `schema hash <schema.json>` | Compute `computeInterfaceHash` for a local schema without connecting.                                  |
 | `schema check-compat <interfaceId> <local.json>` | Compare a live interface schema with a local schema.                                  |
 | `codegen --input <bundle> --interface <id> --name <name> --output <file> [--preserve-wire-schema] [--check]` | Generate a TypeScript interface definition from a validated offline static bundle. |
+| `codegen --input <contract> --output <file> [--names <json>] [--check]` | Generate all reusable interface definitions and typed root/service/default/bare bindings. |
 
-`codegen` uses the same `{ interfaceSchemas, services, defaultInterface }`
+`codegen` uses the same `{ interfaceSchemas, services?, defaultInterface?, bareInterfaces? }`
 bundle parser and interface-hash verification as static reflection. `--check`
 compares the generated source with the output file and exits unsuccessfully if
 the file is missing or stale; it never overwrites in check mode.
 
+```sh
+linkrpc --endpoint-cmd-stdio "node server.js" contract export --output contract.json
+linkrpc codegen --input contract.json --output generated.ts
+linkrpc codegen --input contract.json --output generated.ts --check
+# Existing per-interface generation remains available:
+linkrpc codegen --input contract.json --interface demo.echo --name echoInterface \
+  --output echo.ts --preserve-wire-schema
+```
+
+Omit both `--interface` and `--name` for whole-contract generation. Every interface
+is emitted once, with canonical wire schemas preserved, and each binding refers
+to that definition. For `demo.echo`, default names include `demoEchoInterface`,
+`demoEchoRoot`, `demoEchoDefault`, and (for bare prefix `Runtime.`) `runtimeBare`.
+A service `worker` produces `workerDemoEchoService`. If names collide, supply a
+local `--names` JSON file containing `interfaceNames` (`"id@hash": "exportName"`)
+and/or `bindingNames` (`"root:id@hash"`, `"service:serviceId:id@hash"`,
+`"default"`, or `"bare:prefix"` keys). Unknown keys and colliding overrides fail.
+
+Contract export queries directory interfaces, `defaults.get`, and
+`defaults.listBindings`; it fails explicitly if discovery is inaccessible,
+truncated or depth-limited, default metadata is incomplete, or schemas cannot be
+retrieved and hash-verified. It writes the output only after successful completion.
+`--service` selects a reflection scope; default/bare bindings describe that scope's
+preset routes, not additional service-qualified foreign methods. No default or
+bare bindings are guessed from directory listings.
+
+`ls --dump` remains the diagnostic graph format, including directory provenance.
+It is not a static contract and is not an input to `contract export`. Export a
+contract directly from the endpoint for offline generation instead.
+
 `hub ls --format json` waits for finite exploration and prints the final state.
 `--format jsonl` emits progressive state while requests fan out: the first line
 is `{ "type": "snapshot", "revision": n, "value": ... }` and each later line

package/dist/chunks/{cli-D_-vlAa2.js → cli-FDKN1ydZ.js}

@@ -1,5 +1,5 @@
-import { A as connectViaRootOverlay, C as findMethodInSchema, D as formatPrincipalSource, E as logoutCliIdentity, F as describeSchema, H as mcpForwardInterface, I as explainValidation, L as validateValueAgainstSchema, M as resolveTargetEndpoint, N as resolvedEndpointToConfig, O as parsePrincipalSpec, P as describeObjectParams, S as fetchSchema$1, V as MethodRefWithOptHash, a as resolveStaticHubSchemaSource, b as setupSigning, c as resolveInvocationEndpoint, d as formatContextReference, i as loadStaticHubSchema, j as connectViaTransport, k as connect, l as validationDefault, n as StaticHubReflection, o as mutationReference, p as resolveCliInvocation, r as withStaticHubReflection, s as resolveInvocationContext, t as completeForLine, u as ContextStore, v as requestReflectionAccess, w as walkHub, x as fetchDefaults, y as requestTopologyAccess, z as mergeParams } from "./runComplete-BkQwzPbF.js";
-import { ErrorCode, LinkRpcConnection, RpcError, TransportPair, computeInterfaceHash, connectTransports, generateTsInterface, isAssignable, jcsCanonicalize } from "@hediet/linkrpc";
+import { A as connectViaRootOverlay, C as findMethodInSchema, D as formatPrincipalSource, E as logoutCliIdentity, F as describeSchema, H as mcpForwardInterface, I as explainValidation, L as validateValueAgainstSchema, M as resolveTargetEndpoint, N as resolvedEndpointToConfig, O as parsePrincipalSpec, P as describeObjectParams, S as fetchSchema$1, V as MethodRefWithOptHash, a as resolveStaticHubSchemaSource, b as setupSigning, c as resolveInvocationEndpoint, d as formatContextReference, i as loadStaticHubSchema, j as connectViaTransport, k as connect, l as validationDefault, n as StaticHubReflection, o as mutationReference, p as resolveCliInvocation, r as withStaticHubReflection, s as resolveInvocationContext, t as completeForLine, u as ContextStore, v as requestReflectionAccess, w as walkHub, x as fetchDefaults, y as requestTopologyAccess, z as mergeParams } from "./runComplete-Du5wmOdB.js";
+import { ErrorCode, LinkRpcConnection, RpcError, TransportPair, computeInterfaceHash, connectTransports, exportStaticHubSchema, generateTsContract, generateTsInterface, isAssignable, jcsCanonicalize } from "@hediet/linkrpc";
 import { WebSocketTransport, connectNdjson, formatEndpointUri, isHubEndpoint, openWebSocket, parseEndpointUri, runInitializeHandshake, traceMessageTransport as traceMessageTransport$1 } from "@hediet/linkrpc/node";
 import { SocketServer } from "@hediet/linkrpc-hub/hub/server/node";
 import { randomBytes, randomUUID } from "node:crypto";
@@ -1256,14 +1256,30 @@ function formatVerdict(v) {
 //#region src/commands/codegen.ts
 async function codegenCommand(options) {
 	if (/^https?:\/\//i.test(options.input)) throw new Error("codegen --input must be a local offline bundle");
-	if (!/^[$A-Z_a-z][$\w]*$/.test(options.name)) throw new Error(`codegen --name must be a valid TypeScript identifier, got '${options.name}'`);
-	const matches = (await loadStaticHubSchema(options.input)).interfaceSchemas.filter((schema) => schema.id === options.interfaceId);
-	if (matches.length === 0) throw new Error(`Interface '${options.interfaceId}' was not found in bundle '${options.input}'`);
-	if (matches.length > 1) throw new Error(`Interface '${options.interfaceId}' is ambiguous in bundle '${options.input}' (${matches.length} schema versions)`);
-	const generated = generateTsInterface(matches[0], {
-		exportName: options.name,
-		preserveWireSchema: options.preserveWireSchema === true
-	});
+	if (options.name !== void 0 && !/^[$A-Z_a-z][$\w]*$/.test(options.name)) throw new Error(`codegen --name must be a valid TypeScript identifier, got '${options.name}'`);
+	const bundle = await loadStaticHubSchema(options.input);
+	let generated;
+	if (options.interfaceId === void 0) {
+		if (options.name !== void 0) throw new Error("codegen --name requires --interface");
+		let naming = {};
+		if (options.names !== void 0) {
+			const raw = JSON.parse(await readFile(options.names, "utf8"));
+			if (raw === null || typeof raw !== "object" || Array.isArray(raw) || Object.keys(raw).some((key) => key !== "interfaceNames" && key !== "bindingNames")) throw new Error("codegen --names must contain only interfaceNames and bindingNames maps");
+			for (const map of Object.values(raw)) if (map === null || typeof map !== "object" || Array.isArray(map) || Object.values(map).some((name) => typeof name !== "string")) throw new Error("codegen --names values must be string maps");
+			naming = raw;
+		}
+		generated = generateTsContract(bundle, naming);
+	} else {
+		if (options.name === void 0) throw new Error("codegen --interface requires --name");
+		if (options.names !== void 0) throw new Error("codegen --names is only supported for whole contracts");
+		const matches = bundle.interfaceSchemas.filter((schema) => schema.id === options.interfaceId);
+		if (matches.length === 0) throw new Error(`Interface '${options.interfaceId}' was not found in bundle '${options.input}'`);
+		if (matches.length > 1) throw new Error(`Interface '${options.interfaceId}' is ambiguous in bundle '${options.input}' (${matches.length} schema versions)`);
+		generated = generateTsInterface(matches[0], {
+			exportName: options.name,
+			preserveWireSchema: options.preserveWireSchema === true
+		});
+	}
 	if (options.check === true) {
 		let current;
 		try {
@@ -1279,6 +1295,17 @@ async function codegenCommand(options) {
 	await writeFile(options.output, generated, "utf8");
 }
 //#endregion
+//#region src/commands/contract.ts
+async function exportContractCommand(channel, options) {
+	const document = await exportStaticHubSchema(channel, options);
+	const text = `${JSON.stringify(document, null, 2)}\n`;
+	if (options.output === "-") process.stdout.write(text);
+	else {
+		await mkdir(dirname(options.output), { recursive: true });
+		await writeFile(options.output, text, "utf8");
+	}
+}
+//#endregion
 //#region src/completions/shellScripts.ts
 const SUPPORTED = /* @__PURE__ */ new Set(["powershell"]);
 function isSupportedShell(name) {
@@ -5140,16 +5167,29 @@ async function main(rawArgv, executableName = "linkrpc") {
 			process.stdout.write(out + "\n");
 		});
 	});
-	program.command("codegen").description("Generate a TypeScript interface definition from an offline schema bundle.").requiredOption("--input <bundle>", "local static hub schema bundle").requiredOption("--interface <id>", "interface id to generate").requiredOption("--name <name>", "exported TypeScript const name").requiredOption("--output <file>", "generated TypeScript output file").option("--preserve-wire-schema", "freeze the canonical input schema verbatim in the generated definition").option("--check", "fail if the output is missing or stale without overwriting it").action(async (opts) => {
+	program.command("codegen").description("Generate reusable TypeScript interfaces and bindings from an offline contract.").requiredOption("--input <bundle>", "local static hub schema bundle").option("--interface <id>", "generate only this interface (requires --name)").option("--name <name>", "single-interface exported TypeScript const name").option("--names <file>", "whole-contract JSON interfaceNames/bindingNames overrides").requiredOption("--output <file>", "generated TypeScript output file").option("--preserve-wire-schema", "freeze the canonical input schema verbatim in the generated definition").option("--check", "fail if the output is missing or stale without overwriting it").action(async (opts) => {
 		await codegenCommand({
 			input: opts.input,
 			interfaceId: opts.interface,
 			name: opts.name,
 			output: opts.output,
 			preserveWireSchema: opts.preserveWireSchema === true,
-			check: opts.check === true
+			check: opts.check === true,
+			names: opts.names
 		});
 	});
+	program.command("contract").description("Export reusable static interface and binding contracts.").command("export").requiredOption("--output <file>", "contract JSON destination, or - for stdout").option("--service <id>", "reflection scope (defaults to the endpoint root)").option("--max-depth <depth>", "maximum directory referral depth", (value) => {
+		if (!/^\d+$/.test(value)) throw new InvalidArgumentError("depth must be a non-negative integer");
+		return Number(value);
+	}).action(async (opts) => {
+		await withChannel(endpoint, getPrincipalSpec(), async (channel) => {
+			await exportContractCommand(channel, {
+				output: opts.output,
+				serviceId: opts.service,
+				maxDepth: opts.maxDepth
+			});
+		}, { requestReflectionAccess: true });
+	});
 	const schema = program.command("schema").description("Inspect, hash, and compare LinkRPC interface schemas.");
 	schema.command("show <interfaceRef>").description("Print an interface schema. `<interfaceRef>` is `id[@hash]`.").option("--method <name>", "show only this method").option("--service <id>", "route the lookup to this service (form-3); needed behind a hub").option("--json", "raw JSON output").action(async (interfaceRef, opts) => {
 		const { id, hash } = parseInterfaceRef(interfaceRef);
@@ -5625,7 +5665,7 @@ Batch options:
 				process.once("SIGINT", onSignal);
 				process.once("SIGTERM", onSignal);
 				try {
-					const { runApprovalUi } = await import("./runApprovalUi-BvJZdjKm.js");
+					const { runApprovalUi } = await import("./runApprovalUi-CTyhiDpa.js");
 					await runApprovalUi({
 						client,
 						signal: stop.signal
@@ -5639,7 +5679,7 @@ Batch options:
 	}
 	program.command("ui").description("Launch the terminal UI (form-based browser of services + methods).").action(async () => {
 		const acquired = await acquireConnection(endpoint);
-		const { runUi } = await import("./runUi-D-8LMU4F.js");
+		const { runUi } = await import("./runUi-CuJr8_tY.js");
 		try {
 			await runUi({
 				endpoint: acquired.ep,
@@ -6070,4 +6110,4 @@ function safeJson(value) {
 //#endregion
 export { observableValue as a, Disposable as c, ObservablePromise as i, approvalDetailLines as n, autorun as o, ObservableLazyPromise as r, derived as s, runCli as t };
 
-//# sourceMappingURL=cli-D_-vlAa2.js.map
+//# sourceMappingURL=cli-FDKN1ydZ.js.map