What Is the Role of CatalogClient in kcmd?

The CatalogClient is the core TypeScript class that bridges the kcmd CLI with Google Knowledge Catalog, exposing type-safe methods for entry manipulation while normalizing resource identifiers to canonical formats.

The CatalogClient in kcmd serves as the primary abstraction layer between the command-line synchronization tool and Google Cloud's Knowledge Catalog service (formerly Dataplex). Implemented in the GoogleCloudPlatform/knowledge-catalog repository, this specialized client wraps the generic ApiClient to provide Knowledge Catalog-specific operations with consistent resource handling.

Core Responsibilities of the CatalogClient

Exposing Dataplex REST Operations

The CatalogClient class defined in toolbox/mdcode/src/libts/gcp/dataplex.ts (lines 58-131) exposes methods that map directly to Dataplex REST endpoints. These include getEntryGroup, getEntryType, getAspectType, getEntry, lookupEntry, createEntry, modifyEntry, updateEntry, and listEntries. Each method handles the HTTP transport to https://dataplex.googleapis.com/v1 while providing TypeScript type safety for request and response payloads.

Normalizing Resource Identifiers

After every API call, the private _fixEntry helper method (lines 11-40 in dataplex.ts) rewrites project numbers to the canonical projects/<project>/... form. This normalization ensures that downstream components in the SDK work with consistent resource identifiers regardless of variations in the API response format.

Configuring API Context

The client initializes with a base URL of https://dataplex.googleapis.com and API version v1, encapsulating the service configuration. It accepts an ApiContext containing credentials and project settings, making it immediately usable by higher-level components without requiring manual endpoint configuration.

Integration with kcmd Architecture

CLI Command Initialization

In toolbox/mdcode/src/tool/commands.ts (lines 65-87), the CLI entry point constructs a CatalogClient from the user-supplied ApiContext. Commands such as kcmd init, kcmd pull, and kcmd push instantiate this client and inject it into the synchronization engine, establishing the connection to the Knowledge Catalog service.

Driving Synchronization Logic

The CatalogSync class in toolbox/mdcode/src/libts/sync.ts (lines 21-32) receives the CatalogClient through its constructor. During pulls, it invokes lookupEntry to fetch remote metadata, while push operations utilize createEntry and modifyEntry to propagate local changes. The client serves as the exclusive transport mechanism for these metadata operations.

Populating Local Snapshots

When building local representations, the CatalogSnapshot class in toolbox/mdcode/src/libts/snapshot.ts (lines 35-62) calls getEntryType and getAspectType to populate type metadata. This cached information fuels the manifest and layout layers that store entries on disk, enabling offline manifest operations.

Working with CatalogClient: Code Examples

Creating a Client Instance

import * as kcmd from 'kcmd';

// Obtain a default API context (credentials, project, etc.)
const ctx = kcmd.gcp.ApiContext.default();

// Build a client that talks to the Knowledge Catalog service
const catalog = new kcmd.gcp.CatalogClient(ctx);

Pulling Entries (as used by kcmd pull)

// Inside CatalogSync.pull()
const entries = this._snapshot.manifest.source.entries(this._catalog.context);
for await (const entry of entries) {
  const nameParts = entry.name.split('/');
  const res = await this._catalog.lookupEntry(
    nameParts[1],               // project
    nameParts[3],               // location
    entry.name,
    [...this._snapshot.aspectTypes.keys()] // requested aspects
  );
  if (res.status === 200 && res.result) {
    await this._snapshot._storeEntry(res.result);
  }
}

Pushing New Entries (as used by kcmd push)

// Inside CatalogSync.push()
const exist = await this._catalog.lookupEntry(project, location, entry.name);
if (exist.status !== 200) {
  // Entry does not exist → create it
  const createRes = await this._catalog.createEntry(
    project,
    location,
    entryGroup,
    entryId,
    entry
  );
}

Listing Entries (as used by kcmd status)

// Inside CatalogSync.status()
for await (const entry of this._catalog.listEntries(project, location, entryGroup)) {
  console.log(entry.name);
}

Summary

• The CatalogClient in toolbox/mdcode/src/libts/gcp/dataplex.ts serves as the dedicated bridge between kcmd and Google Knowledge Catalog, wrapping the generic ApiClient with domain-specific methods.
• It provides type-safe access to Dataplex REST endpoints including lookupEntry, createEntry, and modifyEntry while targeting https://dataplex.googleapis.com/v1.
• The _fixEntry helper ensures resource name consistency by normalizing project identifiers to canonical formats after every API call.
• CLI commands instantiate the client in toolbox/mdcode/src/tool/commands.ts and pass it to the sync engine, which uses it exclusively for metadata operations.
• The snapshot builder relies on getEntryType and getAspectType to cache type metadata locally, supporting offline manifest operations.

Frequently Asked Questions

What is the relationship between CatalogClient and ApiClient in kcmd?

The CatalogClient is a specialized wrapper around the generic ApiClient. While ApiClient handles raw HTTP transport and authentication, CatalogClient adds Knowledge Catalog-specific logic including endpoint paths, resource normalization via _fixEntry, and typed methods for entry operations.

How does CatalogClient handle resource name normalization?

After each API call, the private _fixEntry method (defined in toolbox/mdcode/src/libts/gcp/dataplex.ts lines 11-40) processes the response to rewrite project numbers into canonical projects/<project>/... identifiers. This ensures consistent resource naming throughout the SDK regardless of API response variations.

Which kcmd commands rely on CatalogClient?

The kcmd init, kcmd pull, kcmd push, and kcmd status commands all rely on CatalogClient. The CLI constructs the client in toolbox/mdcode/src/tool/commands.ts (lines 65-87) and passes it to CatalogSync, which uses it for all remote operations including listing, looking up, creating, and modifying entries.

Where is the CatalogClient class defined in the source code?

The CatalogClient class is defined in toolbox/mdcode/src/libts/gcp/dataplex.ts in the GoogleCloudPlatform/knowledge-catalog repository. This file contains the class implementation along with the _fixEntry helper and all CRUD methods for Knowledge Catalog entities.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}