@europeum-ebsi/cli 0.0.0 → 1.0.0-rc.0

package/src/commands/registry.ts

@@ -0,0 +1,152 @@
+import type { CliConfig } from "../config/config.ts";
+
+/**
+ * A positional argument for a command
+ */
+export interface CommandArg {
+  description: string;
+  example?: string;
+  /**
+   * CLI name / placeholder, e.g. "did"
+   */
+  name: string;
+  required: boolean;
+}
+
+/**
+ * A single command entry in the registry
+ */
+export interface CommandDescriptor {
+  args: CommandArg[];
+  /**
+   * Group label for display (first segment, title-cased)
+   */
+  group: string;
+  /**
+   * Executes the command.
+   * @param args  Positional arg values keyed by CommandArg.name
+   * @param opts  Option values keyed by long flag name (camelCase)
+   * @param config Resolved CLI configuration
+   * @returns The data to display (passed to formatOutput)
+   */
+  handler: (
+    args: Record<string, string>,
+    opts: Record<string, string>,
+    config: CliConfig,
+  ) => Promise<unknown>;
+  /**
+   * Unique dotted id, e.g. "did-registry.identifiers.list"
+   */
+  id: string;
+  options: CommandOption[];
+  /**
+   * Space-separated command path, e.g. ["did-registry", "identifiers", "list"]
+   */
+  segments: string[];
+  /**
+   * Short human-readable summary shown as a tip in help / palette
+   */
+  summary: string;
+}
+
+/**
+ * An optional flag / option for a command
+ */
+interface CommandOption {
+  defaultValue?: string;
+  description: string;
+  /**
+   * Commander flags string, e.g. "--page-after <cursor>"
+   */
+  flags: string;
+}
+
+/**
+ * Full path string for a descriptor, e.g. "did-registry identifiers list"
+ */
+export function commandPath(cmd: CommandDescriptor): string {
+  return cmd.segments.join(" ");
+}
+
+/**
+ * Fuzzy-match: returns true when all words in `query` appear (as
+ * substrings, case-insensitive) in the command's segment path or summary.
+ */
+export function matchesQuery(cmd: CommandDescriptor, query: string): boolean {
+  if (query.trim() === "") return true;
+  const haystack = `${commandPath(cmd)} ${cmd.summary}`.toLowerCase();
+  const words = query.trim().toLowerCase().split(/\s+/);
+  return words.every((word) => haystack.includes(word));
+}
+
+/**
+ * Ranks a matching command by how many query words appear in the command
+ * path (title) vs only in the summary description.
+ *
+ * - 2: every word found in the command path → title match
+ * - 1: some words found in the command path → partial title match
+ * - 0: no words found in the path → summary-only match
+ *
+ * Use as a sort key (descending) after filtering with matchesQuery so that
+ * path matches always appear before description-only matches.
+ */
+export function queryScore(cmd: CommandDescriptor, query: string): number {
+  if (query.trim() === "") return 0;
+  const words = query.trim().toLowerCase().split(/\s+/);
+  const path = commandPath(cmd).toLowerCase();
+  const pathHits = words.filter((word) => path.includes(word)).length;
+  if (pathHits === words.length) return 2;
+  return pathHits > 0 ? 1 : 0;
+}
+
+// ---------------------------------------------------------------------------
+// Command handlers are registered from individual command files.
+// The registry is assembled at the bottom of this file.
+// ---------------------------------------------------------------------------
+
+import { authCommands } from "./auth.ts";
+import { configCommands } from "./config-cmd.ts";
+import { contractsRegistryCommands } from "./contracts-registry.ts";
+import { didRegistryCommands } from "./did-registry.ts";
+import { faucetCommands } from "./faucet.ts";
+import { healthCommands } from "./health.ts";
+import { issuersRegistryCommands } from "./issuers-registry.ts";
+import { ledgerCommands } from "./ledger.ts";
+import { onboardingCommands } from "./onboarding.ts";
+import { openapiCommands } from "./openapi.ts";
+import { policiesRegistryCommands } from "./policies-registry.ts";
+import { schemasRegistryCommands } from "./schemas-registry.ts";
+import { timestampCommands } from "./timestamp.ts";
+import { trackAndTraceCommands } from "./track-and-trace.ts";
+import { walletCommands } from "./wallet.ts";
+
+/**
+ * The full ordered list of CLI commands
+ */
+export const COMMANDS: CommandDescriptor[] = [
+  ...healthCommands,
+  ...openapiCommands,
+  ...configCommands,
+  ...walletCommands,
+  ...faucetCommands,
+  ...onboardingCommands,
+  ...authCommands,
+  ...ledgerCommands,
+  ...contractsRegistryCommands,
+  ...didRegistryCommands,
+  ...issuersRegistryCommands,
+  ...policiesRegistryCommands,
+  ...schemasRegistryCommands,
+  ...timestampCommands,
+  ...trackAndTraceCommands,
+  {
+    args: [],
+    group: "exit",
+    /* v8 ignore next */
+    handler: () => process.exit(0),
+    id: "exit",
+    options: [],
+    segments: ["exit"],
+    summary: "Quit the EBSI CLI",
+  },
+];

package/src/commands/schemas-registry.ts

@@ -0,0 +1,255 @@
+import type { CommandDescriptor } from "./registry.ts";
+
+import { getClient, unwrap } from "../api/fetch.ts";
+import { q } from "../api/params.ts";
+import { contractAddressOptionFor } from "../ledger/registries.ts";
+import { requiredArg } from "./shared/args.ts";
+
+const PAGINATION_OPTIONS = [
+  {
+    description: "Cursor for pagination (page[after])",
+    flags: "--page-after <cursor>",
+  },
+  {
+    description: "Maximum number of items per page (page[size])",
+    flags: "--page-size <n>",
+  },
+];
+
+const { option: CONTRACT_ADDRESS_OPTION, resolve: contractAddress } =
+  contractAddressOptionFor("schemas-registry");
+
+export const schemasRegistryCommands: CommandDescriptor[] = [
+  {
+    args: [],
+    group: "Schemas Registry",
+    async handler(_args, opts, config) {
+      const client = getClient(config);
+      const result = await client.GET("/schemas-registry/schemas", {
+        params: {
+          query: q({
+            contractAddress: contractAddress(opts),
+            "page[after]": opts["pageAfter"]
+              ? Number(opts["pageAfter"])
+              : undefined,
+            "page[size]": opts["pageSize"]
+              ? Number(opts["pageSize"])
+              : undefined,
+          }),
+        },
+      });
+      return unwrap(result);
+    },
+    id: "schemas-registry.schemas.list",
+    options: [...PAGINATION_OPTIONS, CONTRACT_ADDRESS_OPTION],
+    segments: ["schemas-registry", "schemas", "list"],
+    summary: "List all trusted schemas registered on the EBSI ledger",
+  },
+
+  {
+    args: [
+      {
+        description: "Schema ID",
+        example: "0x1234...",
+        name: "schemaId",
+        required: true,
+      },
+    ],
+    group: "Schemas Registry",
+    async handler(args, opts, config) {
+      const client = getClient(config);
+      const result = await client.GET("/schemas-registry/schemas/{schemaId}", {
+        params: {
+          path: { schemaId: requiredArg(args, "schemaId") },
+          query: q({ contractAddress: contractAddress(opts) }),
+        },
+      });
+      return unwrap(result);
+    },
+    id: "schemas-registry.schemas.get",
+    options: [CONTRACT_ADDRESS_OPTION],
+    segments: ["schemas-registry", "schemas", "get"],
+    summary: "Get a schema by its ID",
+  },
+
+  {
+    args: [
+      {
+        description: "Schema ID",
+        example: "0x1234...",
+        name: "schemaId",
+        required: true,
+      },
+    ],
+    group: "Schemas Registry",
+    async handler(args, opts, config) {
+      const client = getClient(config);
+      const result = await client.GET(
+        "/schemas-registry/schemas/{schemaId}/revisions",
+        {
+          params: {
+            path: { schemaId: requiredArg(args, "schemaId") },
+            query: q({
+              contractAddress: contractAddress(opts),
+              "page[after]": opts["pageAfter"]
+                ? Number(opts["pageAfter"])
+                : undefined,
+              "page[size]": opts["pageSize"]
+                ? Number(opts["pageSize"])
+                : undefined,
+            }),
+          },
+        },
+      );
+      return unwrap(result);
+    },
+    id: "schemas-registry.schemas.revisions",
+    options: [...PAGINATION_OPTIONS, CONTRACT_ADDRESS_OPTION],
+    segments: ["schemas-registry", "schemas", "revisions"],
+    summary: "List all revisions of a schema",
+  },
+
+  {
+    args: [
+      {
+        description: "Schema ID",
+        example: "0x1234...",
+        name: "schemaId",
+        required: true,
+      },
+      {
+        description: "Schema revision ID",
+        example: "0x5678...",
+        name: "schemaRevisionId",
+        required: true,
+      },
+    ],
+    group: "Schemas Registry",
+    async handler(args, opts, config) {
+      const client = getClient(config);
+      const result = await client.GET(
+        "/schemas-registry/schemas/{schemaId}/revisions/{schemaRevisionId}",
+        {
+          params: {
+            path: {
+              schemaId: requiredArg(args, "schemaId"),
+              schemaRevisionId: requiredArg(args, "schemaRevisionId"),
+            },
+            query: q({ contractAddress: contractAddress(opts) }),
+          },
+        },
+      );
+      return unwrap(result);
+    },
+    id: "schemas-registry.schemas.revision",
+    options: [CONTRACT_ADDRESS_OPTION],
+    segments: ["schemas-registry", "schemas", "revision"],
+    summary: "Get a specific revision of a schema",
+  },
+
+  {
+    args: [
+      {
+        description: "Schema ID",
+        example: "0x1234...",
+        name: "schemaId",
+        required: true,
+      },
+      {
+        description: "Schema revision ID",
+        example: "0x5678...",
+        name: "schemaRevisionId",
+        required: true,
+      },
+    ],
+    group: "Schemas Registry",
+    async handler(args, opts, config) {
+      const client = getClient(config);
+      const result = await client.GET(
+        "/schemas-registry/schemas/{schemaId}/revisions/{schemaRevisionId}/metadata",
+        {
+          params: {
+            path: {
+              schemaId: requiredArg(args, "schemaId"),
+              schemaRevisionId: requiredArg(args, "schemaRevisionId"),
+            },
+            query: q({
+              contractAddress: contractAddress(opts),
+              "page[after]": opts["pageAfter"]
+                ? Number(opts["pageAfter"])
+                : undefined,
+              "page[size]": opts["pageSize"]
+                ? Number(opts["pageSize"])
+                : undefined,
+            }),
+          },
+        },
+      );
+      return unwrap(result);
+    },
+    id: "schemas-registry.schemas.metadata.list",
+    options: [...PAGINATION_OPTIONS, CONTRACT_ADDRESS_OPTION],
+    segments: ["schemas-registry", "schemas", "metadata", "list"],
+    summary: "List metadata for a schema revision",
+  },
+
+  {
+    args: [
+      {
+        description: "Schema ID",
+        example: "0x1234...",
+        name: "schemaId",
+        required: true,
+      },
+      {
+        description: "Schema revision ID",
+        example: "0x5678...",
+        name: "schemaRevisionId",
+        required: true,
+      },
+      {
+        description: "Schema revision metadata ID",
+        example:
+          "0x44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a",
+        name: "metadataId",
+        required: true,
+      },
+    ],
+    group: "Schemas Registry",
+    async handler(args, opts, config) {
+      const client = getClient(config);
+      const result = await client.GET(
+        "/schemas-registry/schemas/{schemaId}/revisions/{schemaRevisionId}/metadata/{metadataId}",
+        {
+          params: {
+            path: {
+              metadataId: requiredArg(args, "metadataId"),
+              schemaId: requiredArg(args, "schemaId"),
+              schemaRevisionId: requiredArg(args, "schemaRevisionId"),
+            },
+            query: q({ contractAddress: contractAddress(opts) }),
+          },
+        },
+      );
+      return unwrap(result);
+    },
+    id: "schemas-registry.schemas.metadata.get",
+    options: [CONTRACT_ADDRESS_OPTION],
+    segments: ["schemas-registry", "schemas", "metadata", "get"],
+    summary: "Get metadata for a schema revision",
+  },
+
+  {
+    args: [],
+    group: "Schemas Registry",
+    async handler(_args, _opts, config) {
+      const client = getClient(config);
+      const result = await client.GET("/schemas-registry/abi");
+      return unwrap(result);
+    },
+    id: "schemas-registry.abi",
+    options: [],
+    segments: ["schemas-registry", "abi"],
+    summary: "Get the ABI of the Schemas Registry smart contract",
+  },
+];

package/src/commands/shared/args.ts

@@ -0,0 +1,14 @@
+/**
+ * Reads a positional argument that Commander guarantees is present (required
+ * args are validated before the handler runs), without needing a per-call-site
+ * `v8 ignore` comment — `noUncheckedIndexedAccess` widens every indexed read
+ * to `string | undefined` regardless of that guarantee.
+ */
+export function requiredArg(
+  args: Record<string, string>,
+  name: string,
+  fallback = "",
+): string {
+  /* v8 ignore next -- required positional guaranteed by commander */
+  return args[name] ?? fallback;
+}

package/src/commands/shared/wallet-opts.ts

@@ -0,0 +1,85 @@
+import type { CliConfig } from "../../config/config.ts";
+import type { KeyAlgorithm, WalletDetails } from "../../crypto/wallet.ts";
+
+import { SIGN_ALGS } from "../../config/config.ts";
+import { deriveWallet } from "../../crypto/wallet.ts";
+
+/**
+ * Resolves `--sign-alg` (flag → config, which is already flag/env/persisted
+ * resolved and validated by `resolveConfig`). Re-validates here too, since a
+ * command-local `--sign-alg` flag value hasn't gone through that validation.
+ */
+export function resolveSignAlg(
+  opts: Record<string, string>,
+  config: Pick<CliConfig, "signAlg">,
+): KeyAlgorithm | undefined {
+  const raw = opts["signAlg"] ?? config.signAlg;
+  if (raw === undefined) return undefined;
+  const normalized = raw.toUpperCase();
+  if (!SIGN_ALGS.includes(normalized as KeyAlgorithm)) {
+    throw new Error(
+      `Invalid --sign-alg "${raw}". Valid values: ${SIGN_ALGS.join(", ")}`,
+    );
+  }
+  return normalized as KeyAlgorithm;
+}
+
+/**
+ * Resolves the currently-configured wallet from `--es256k-key`/`--es256-key`/
+ * `--sign-alg`/`--did` (or their env/persisted-config fallbacks, already
+ * folded into `config` by `resolveConfig`), throwing the same descriptive
+ * error every command that needs a wallet uses when the mandatory secp256k1
+ * key is missing.
+ */
+export async function resolveWallet(
+  opts: Record<string, string>,
+  config: Pick<
+    CliConfig,
+    "did" | "es256kPrivateKey" | "es256PrivateKey" | "signAlg"
+  >,
+): Promise<WalletDetails> {
+  const es256kPrivateKey = opts["es256kKey"] ?? config.es256kPrivateKey;
+  if (!es256kPrivateKey) {
+    throw new Error(
+      "No secp256k1 private key found. Provide --es256k-key <hex>, set " +
+        "EBSI_ES256K_PRIVATE_KEY, or run `ebsi config set es256kPrivateKey <hex>`.",
+    );
+  }
+  const es256PrivateKey = opts["es256Key"] ?? config.es256PrivateKey;
+  const signAlg = resolveSignAlg(opts, config);
+  const overrideDid = opts["did"] ?? config.did;
+
+  return deriveWallet(
+    {
+      es256kPrivateKey,
+      ...(es256PrivateKey !== undefined && { es256PrivateKey }),
+      ...(signAlg !== undefined && { signAlg }),
+    },
+    overrideDid,
+  );
+}
+
+/**
+ * The `--es256k-key`/`--es256-key`/`--sign-alg` options shared by every
+ * command that resolves a wallet, for `--help` text on that command (mirrors
+ * the global flags of the same name).
+ */
+export const WALLET_KEY_OPTIONS = [
+  {
+    description:
+      "secp256k1 private key (0x-prefixed hex) — overrides config/env.",
+    flags: "--es256k-key <hex>",
+  },
+  {
+    description:
+      "P-256 private key (hex), optional — overrides config/env. " +
+      "Enables --sign-alg ES256.",
+    flags: "--es256-key <hex>",
+  },
+  {
+    description:
+      'Which key signs VCs/VPs when both are configured: "ES256" or "ES256K" ' +
+      "— overrides config/env. Required when both keys are configured.",
+    flags: "--sign-alg <alg>",
+  },
+];