@hediet/linkrpc-cli 0.0.1

package/dist/index.d.ts

@@ -0,0 +1,381 @@
+import { IRequestSender, LinkRpcJsonSchema, SigningCallCtx } from "@hediet/linkrpc";
+//#region src/mcpForward.interface.d.ts
+/**
+ * Transparent MCP tunnel.
+ *
+ * A single long-lived {@link mcpForwardInterface.connect} request opens one MCP
+ * session "leg". The MCP JSON-RPC byte stream rides the linkrpc `$stream` duplex
+ * correlated to that request — **no MCP method is modeled here**. Payloads are
+ * opaque JSON-RPC messages, exactly as MCP emits them, so the forwarder that
+ * serves this interface stays dumb: it shuttles frames between a child process'
+ * stdio and the stream without ever parsing them.
+ *
+ * Why one duplex stream instead of request/response per MCP message: MCP is
+ * bidirectional and asynchronous (server-initiated `notifications/.../
+ * list_changed`, sampling requests). `$stream` already provides an ordered,
+ * request-correlated, cancellable duplex that the runtime keeps alive with
+ * periodic pings, so one stream == one MCP session leg.
+ *
+ * Lifecycle:
+ *  - The consumer (the aggregator) calls `connect()`, obtaining
+ *    `{ result, send, cancel, onMessage }`.
+ *  - `send({ frame })` carries a frame **to** the child (stdin);
+ *    `onMessage(({ frame }) => …)` receives frames **from** the child (stdout).
+ *  - Child exit → the forwarder resolves the request (`connect` returns) → the
+ *    consumer drops the client.
+ *  - Consumer dispose / service removed → `cancel()` → the forwarder kills the
+ *    child.
+ *
+ * Lives in the CLI package because the producer (`hub mcp-forward`) is a CLI
+ * command; the in-extension aggregator imports this contract from here too.
+ */
+declare const mcpForwardInterface: any;
+//#endregion
+//#region src/methodRef.d.ts
+/**
+ * A method reference as accepted on the CLI: `[serviceId::][interfaceId::]name[@hash]`.
+ */
+declare class MethodRefWithOptHash {
+  readonly serviceId: string | undefined;
+  readonly interfaceId: string | undefined;
+  readonly methodName: string;
+  readonly hash: string | undefined;
+  static parseMethodRef(input: string): MethodRefWithOptHash;
+  constructor(serviceId: string | undefined, interfaceId: string | undefined, methodName: string, hash: string | undefined);
+  /** Method name as it goes on the wire (no hash, no whitespace). */
+  getMethodOnWire(): string;
+}
+//#endregion
+//#region src/paramParsing.d.ts
+/**
+ * Parse `--param k=v` style overrides into a JSON object. Values that parse
+ * as JSON are used as-is (numbers, booleans, null, arrays, objects); the rest
+ * are treated as strings. Nested keys use `.` segments: `--param user.name=x`.
+ *
+ * Combined with `--params <json>` (the whole params blob), `--param k=v`
+ * entries layer on top (object-merge for `--params`, then per-key overrides).
+ */
+interface ParseParamsOptions {
+  /** Optional base params object (from `--params <json>` or stdin). */
+  base?: unknown;
+  /** Raw `--param k=v` strings, in order. */
+  overrides?: readonly string[];
+}
+declare function parseParamOverride(raw: string): {
+  path: string[];
+  value: unknown;
+};
+declare function mergeParams(opts: ParseParamsOptions): unknown;
+//#endregion
+//#region src/validation.d.ts
+/**
+ * Validate a concrete value against an `SvcJsonSchema`. Reuses linkrpc's
+ * structural assignability — the value is lowered to a closed, const-shaped
+ * schema and then asked "is this assignable to the target?". This avoids
+ * pulling in a separate JSON-Schema validator and stays consistent with how
+ * the connection layer reasons about interface compatibility.
+ *
+ * Returns `undefined` if the value is valid, or a short reason string.
+ */
+declare function validateValueAgainstSchema(value: unknown, target: LinkRpcJsonSchema, components?: Record<string, LinkRpcJsonSchema>): string | undefined;
+/**
+ * Lower a JSON value to the tightest `SvcJsonSchema` that matches only it.
+ * Primitives become `{ const }`; arrays become tuples with `items: false`
+ * (forbidding extras); objects become closed records with every property
+ * required.
+ *
+ * `undefined` becomes the empty closed object — that's the
+ * "no params supplied" case, which is only assignable to a target that has
+ * no required properties.
+ */
+declare function valueToConstSchema(v: unknown): LinkRpcJsonSchema;
+/**
+ * One thing wrong with `value` at a given JSON path. Path uses dot/bracket
+ * notation rooted at the validated value, e.g. `.query`, `.items[0].id`.
+ * The empty string is the root.
+ */
+interface ValidationIssue {
+  readonly path: string;
+  readonly reason: string;
+}
+/**
+ * Walk `value` against `schema` and collect every mismatch we can pinpoint.
+ * Returns `[]` on success. Each issue has a JSON-style path plus a single
+ * line saying why that location is wrong — designed to be printed directly
+ * under a "Param validation failed:" header.
+ *
+ * Coverage is best-effort: scalar / object / array / tuple / const / enum /
+ * union / `$ref`. Unions report the branch with the fewest mismatches
+ * (heuristic) so the user gets one concrete trail to fix instead of a
+ * cascade of "no branch matched".
+ */
+declare function explainValidation(value: unknown, schema: LinkRpcJsonSchema, components?: Record<string, LinkRpcJsonSchema>): ValidationIssue[];
+/**
+ * Render an `SvcJsonSchema` as a short, copy-paste-friendly type expression.
+ * Used as a hint next to required-property errors (`"name required (string)"`)
+ * and as the "Expected" footer when full-on params reporting fires.
+ */
+declare function describeSchema(schema: LinkRpcJsonSchema, components?: Record<string, LinkRpcJsonSchema>, depth?: number): string;
+/**
+ * Multi-line table of an object schema's properties: name, required-marker,
+ * type, and description. Used as the "Expected params:" footer printed under
+ * a validation error. Returns `undefined` if `schema` is not an object —
+ * fall back to a single `describeSchema` line in that case.
+ */
+declare function describeObjectParams(schema: LinkRpcJsonSchema, components?: Record<string, LinkRpcJsonSchema>): string | undefined;
+//#endregion
+//#region src/completions/directorySource.d.ts
+interface DirectoryEntry {
+  readonly serviceId: string;
+  readonly interfaceId: string;
+  readonly hash: string;
+}
+interface DirectorySource {
+  entries(): Promise<readonly DirectoryEntry[]>;
+  methodsOnInterface(serviceId: string | undefined, interfaceId: string): Promise<readonly string[]>;
+  /**
+   * Property names of the method's params object schema, or `[]` if the
+   * method takes no params / has a non-object params descriptor / does
+   * not exist on the interface.
+   */
+  paramNamesForMethod(serviceId: string | undefined, interfaceId: string, methodName: string): Promise<readonly string[]>;
+}
+/**
+ * Live source: walks the hub once (memoized for the instance lifetime),
+ * then derives every entry / methods lookup from that single snapshot +
+ * lazy `fetchSchema` calls. Each (sid, iid) schema is fetched at most once
+ * per instance regardless of how many downstream queries reference it.
+ */
+declare class ChannelDirectorySource implements DirectorySource {
+  private readonly _channel;
+  private _walkPromise;
+  private readonly _schemaCache;
+  constructor(_channel: IRequestSender<SigningCallCtx>);
+  entries(): Promise<readonly DirectoryEntry[]>;
+  methodsOnInterface(serviceId: string | undefined, interfaceId: string): Promise<readonly string[]>;
+  paramNamesForMethod(serviceId: string | undefined, interfaceId: string, methodName: string): Promise<readonly string[]>;
+  private _fetchSchema;
+}
+//#endregion
+//#region src/completions/tree.d.ts
+/**
+ * Static description of the CLI's command surface, used to drive
+ * completion. The runtime CLI is defined with `commander` in {@link ../cli};
+ * this table mirrors it. A drift test
+ * ({@link ./tree.test.ts}) verifies subcommand & flag names match.
+ *
+ * Keeping the tree static (rather than introspecting commander at
+ * completion time) lets the completer run with zero startup cost in the
+ * common static-only case and keeps the slot-resolution logic completely
+ * pure — straightforward to unit-test.
+ */
+type SlotType =
+/** A bare or qualified `[svc::][iface::]method[@hash]` reference. */
+'methodRef' |
+/** A bare `interfaceId[@hash]` (e.g. `schema <interfaceRef>`). */
+'interfaceRef' |
+/** A service id known to the hub. */
+'serviceId' |
+/** A bare interface id, sans hash. */
+'interfaceId' |
+/** One of the supported shell names (powershell, bash, zsh, fish). */
+'shell' |
+/** Anything else — completer returns no dynamic suggestions. */
+'free';
+interface FlagDef {
+  readonly name: string;
+  readonly takesValue: boolean;
+  readonly valueType?: SlotType;
+  readonly description?: string;
+}
+interface PositionalDef {
+  readonly name: string;
+  readonly type: SlotType;
+}
+interface SubcommandDef {
+  readonly name: string;
+  readonly description: string;
+  readonly options: readonly FlagDef[];
+  readonly positionals: readonly PositionalDef[];
+  readonly subcommands?: readonly SubcommandDef[];
+  /** When set, extra positionals beyond {@link positionals} are completed as this type. */
+  readonly variadic?: SlotType;
+  /** Hide from subcommand-name completion (used for `_complete`). */
+  readonly hidden?: boolean;
+}
+interface CommandTree {
+  readonly globalOptions: readonly FlagDef[];
+  readonly subcommands: readonly SubcommandDef[];
+}
+/** Hub-profile tree retained as the default for direct resolver consumers. */
+declare const COMMAND_TREE: CommandTree;
+//#endregion
+//#region src/completions/complete.d.ts
+interface Completion {
+  /** Text to replace the current word with. */
+  readonly text: string;
+  /** Tooltip / second-line detail (e.g. method signature). */
+  readonly tooltip?: string;
+}
+interface CompleteOptions {
+  readonly line: string;
+  readonly point: number;
+  readonly tree?: CommandTree;
+  /**
+   * Source of dynamic candidates. Omit to skip dynamic lookups entirely
+   * (only static completions returned) — useful when no hub is configured.
+   */
+  readonly directory?: DirectorySource;
+}
+/**
+ * Resolve completion candidates for the cursor at `point` in `line`.
+ *
+ * The slot kinds returned by {@link resolveSlot} map to:
+ *   - `subcommand` / `flag-name` / static-typed `flag-value` / static-typed
+ *     `positional` → filter against the {@link CommandTree}
+ *   - `flag-value` / `positional` with a dynamic slot type → call into
+ *     `directory` (skipped when `directory` is `undefined`)
+ *   - `flag-name` under `call`/`notify` with a methodRef typed → adds
+ *     `--p:<name>` shortcuts for the live params
+ *   - `none` → empty
+ *
+ * Candidates are always prefix-filtered so the caller (PowerShell) can
+ * enumerate the result as-is. The output is sorted and de-duplicated.
+ */
+declare function complete(opts: CompleteOptions): Promise<Completion[]>;
+//#endregion
+//#region src/completions/parse.d.ts
+/**
+ * Tokenize a shell-style command line and locate the token at the cursor.
+ *
+ * Used by the `_complete` subcommand to figure out what the user is currently
+ * typing. Quoting rules are intentionally minimal (POSIX-ish, matching what
+ * users actually type at a PowerShell prompt): single/double quoted strings
+ * are single tokens; nothing else is special. Cross-shell quoting nuances
+ * don't matter for completion — we only need to know where token boundaries
+ * are well enough to pick the current word.
+ */
+interface Token {
+  readonly text: string;
+  /** Byte offset where the token starts (including any opening quote). */
+  readonly start: number;
+  /** Byte offset one past the token end (including any closing quote). */
+  readonly end: number;
+  readonly quoted: boolean;
+}
+interface ParsedLine {
+  readonly tokens: readonly Token[];
+  /**
+   * Tokens fully to the left of the cursor (i.e. context — never includes the
+   * token the user is currently typing). The first token is the binary name.
+   */
+  readonly tokensBefore: readonly Token[];
+  /**
+   * The token the cursor is positioned in / at the right edge of, or
+   * `undefined` when the cursor sits in whitespace (a "new" word).
+   */
+  readonly currentToken: Token | undefined;
+  /**
+   * Text the user has typed for the current word so far (token start →
+   * cursor). Empty when {@link currentToken} is undefined. Used both for
+   * prefix-filtering candidates and as the value PowerShell replaces.
+   */
+  readonly currentWordPrefix: string;
+}
+/**
+ * Split `line` at `point` (0-indexed cursor position) into a previous-tokens
+ * list + a possibly in-progress current word. Cursor inside or at the end of
+ * a token = that token is the current word; cursor in whitespace = no current
+ * token, new empty word at this position.
+ */
+declare function parseLine(line: string, point: number): ParsedLine;
+//#endregion
+//#region src/completions/resolve.d.ts
+type Slot = {
+  readonly kind: 'subcommand';
+  readonly parent: SubcommandDef | undefined;
+} | {
+  readonly kind: 'flag-name';
+  readonly subcommand: SubcommandDef | undefined;
+} | {
+  readonly kind: 'flag-value';
+  readonly flag: FlagDef;
+  readonly subcommand: SubcommandDef | undefined;
+} | {
+  readonly kind: 'positional';
+  readonly type: SlotType;
+  readonly subcommand: SubcommandDef;
+  readonly index: number;
+} | {
+  readonly kind: 'none';
+};
+interface ResolvedContext {
+  readonly slot: Slot;
+  /** Subcommand parsed from the tokens (undefined if none seen yet). */
+  readonly subcommand: SubcommandDef | undefined;
+  /** Selected commands from the root command through the active leaf. */
+  readonly commandPath: readonly SubcommandDef[];
+  /**
+   * Flags already present on the line that take a value, paired with their
+   * value (or `undefined` if the value followed in the next token).
+   * Useful for extracting `--endpoint` etc. without re-parsing.
+   */
+  readonly seenFlagValues: ReadonlyMap<string, string | undefined>;
+  /**
+   * Positional values already typed (after the subcommand). Indexed
+   * positionally — `seenPositionals[0]` is the first positional, etc.
+   * Used to plumb e.g. the `methodRef` of `call <methodRef>` through to
+   * dynamic completion for `--p:<name>` flags.
+   */
+  readonly seenPositionals: readonly string[];
+}
+/**
+ * Walk the tokens before the cursor, tracking subcommand selection, current
+ * positional index, and whether the next token is the value for a flag.
+ * Returns the slot the cursor itself is in plus the surrounding context.
+ */
+declare function resolveSlot(parsed: ParsedLine, tree: CommandTree): ResolvedContext;
+//#endregion
+//#region src/completions/runComplete.d.ts
+interface CompleteForLineOptions {
+  readonly line: string;
+  readonly point: number;
+  /**
+   * Endpoint URI to connect to, overriding any `--endpoint` on the line and
+   * the env fallback. When omitted, the line's `--endpoint` (then `env`) is
+   * used.
+   */
+  readonly endpointOverride?: string;
+  /**
+   * Environment consulted for the `LINKRPC_ENDPOINT` fallback. Defaults to
+   * `process.env`. Pass `{}` to disable the env fallback entirely (the
+   * extension does this so completion never targets the extension host's
+   * environment).
+   */
+  readonly env?: NodeJS.ProcessEnv;
+  /** Override the directory source (tests). */
+  readonly directoryOverride?: DirectorySource;
+  /** Suppress the connect attempt entirely (tests). */
+  readonly skipConnect?: boolean;
+}
+interface CompleteForLineResult {
+  /** Completion candidates, already prefix-filtered, sorted and de-duped. */
+  readonly candidates: readonly Completion[];
+  /** The resolved slot the cursor sits in (subcommand / flag / positional). */
+  readonly slot: Slot;
+  /**
+   * Offset of the first character the candidate replaces (i.e. the start of
+   * the current word). Equal to `point - replacementLength`.
+   */
+  readonly replacementIndex: number;
+  /** Length of the current word prefix the candidate replaces. */
+  readonly replacementLength: number;
+}
+/**
+ * Resolve completion candidates for the cursor at `point` in `line`, opening a
+ * hub connection only when the slot needs dynamic data.
+ */
+declare function completeForLine(opts: CompleteForLineOptions): Promise<CompleteForLineResult>;
+//#endregion
+export { COMMAND_TREE, ChannelDirectorySource, type CommandTree, type CompleteForLineOptions, type CompleteForLineResult, type CompleteOptions, type Completion, type DirectoryEntry, type DirectorySource, type FlagDef, MethodRefWithOptHash, ParseParamsOptions, type ParsedLine, type ResolvedContext, type Slot, type SlotType, type SubcommandDef, type Token, ValidationIssue, complete, completeForLine, describeObjectParams, describeSchema, explainValidation, mcpForwardInterface, mergeParams, parseLine, parseParamOverride, resolveSlot, validateValueAgainstSchema, valueToConstSchema };
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,2 @@
+import { B as parseParamOverride, F as describeSchema, H as mcpForwardInterface, I as explainValidation, L as validateValueAgainstSchema, P as describeObjectParams, R as valueToConstSchema, V as MethodRefWithOptHash, _ as ChannelDirectorySource, f as complete, g as parseLine, h as COMMAND_TREE, m as resolveSlot, t as completeForLine, z as mergeParams } from "./chunks/runComplete-BkQwzPbF.js";
+export { COMMAND_TREE, ChannelDirectorySource, MethodRefWithOptHash, complete, completeForLine, describeObjectParams, describeSchema, explainValidation, mcpForwardInterface, mergeParams, parseLine, parseParamOverride, resolveSlot, validateValueAgainstSchema, valueToConstSchema };

package/dist/linkrpc.d.ts

@@ -0,0 +1 @@
+export {}

package/dist/linkrpc.js

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+import { t as runCli } from "./chunks/cli-D_-vlAa2.js";
+//#region src/linkrpc.ts
+runCli("linkrpc");
+//#endregion
+export {};
+
+//# sourceMappingURL=linkrpc.js.map

package/dist/linkrpc.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"linkrpc.js","names":[],"sources":["../src/linkrpc.ts"],"sourcesContent":["import { runCli } from './cli';\n\nrunCli('linkrpc');\n"],"mappings":";;;AAEA,OAAO,SAAS"}

package/dist/rpc.d.ts

@@ -0,0 +1 @@
+export {}

package/dist/rpc.js

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+import { t as runCli } from "./chunks/cli-D_-vlAa2.js";
+//#region src/rpc.ts
+runCli("rpc");
+//#endregion
+export {};
+
+//# sourceMappingURL=rpc.js.map

package/dist/rpc.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rpc.js","names":[],"sources":["../src/rpc.ts"],"sourcesContent":["import { runCli } from './cli';\n\nrunCli('rpc');\n"],"mappings":";;;AAEA,OAAO,KAAK"}

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@hediet/linkrpc-cli",
+  "version": "0.0.1",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "linkrpc": "./dist/linkrpc.js",
+    "rpc": "./dist/rpc.js",
+    "hub": "./dist/hub.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "commander": "^12.1.0",
+    "ink": "^5.1.0",
+    "ink-select-input": "^6.0.0",
+    "ink-text-input": "^6.0.0",
+    "react": "^18.3.1",
+    "zod": "^4.4.3",
+    "@hediet/linkrpc": "0.0.1",
+    "@hediet/linkrpc-hub": "0.0.1",
+    "@hediet/linkrpc-infra": "0.0.1"
+  },
+  "devDependencies": {
+    "@vscode/observables": "0.1.1-0",
+    "@types/node": "^20.0.0",
+    "@types/react": "^18.3.0",
+    "tsdown": "^0.22.3",
+    "tslib": "^2.8.1",
+    "tsx": "4.22.4",
+    "typescript": "^6.0.3",
+    "vitest": "^3.0.0",
+    "@hediet/linkrpc-client": "0.0.1"
+  },
+  "scripts": {
+    "cli": "tsx src/linkrpc.ts",
+    "build": "tsdown",
+    "dev": "tsdown --watch",
+    "generate:ahp-schema": "tsx generate-ahp-schema.ts",
+    "test": "vitest --run",
+    "test:watch": "vitest"
+  }
+}