@google-cloud/kcmd 0.1.0 → 0.2.1

package/build/ts/kcmd/snapshot.d.ts

@@ -27,6 +27,10 @@ export declare class CatalogSnapshot {
     private _buildTypes;
     _loadEntryType(entryType: string): Promise<void>;
     _storeEntry(entry: dataplex.Entry): Promise<void>;
+    _previewStoreEntry(entry: dataplex.Entry): {
+        localName: string;
+        exists: boolean;
+    };
     _fetchEntry(name: string): Promise<dataplex.Entry | undefined>;
 }
 export declare function toLocalEntry(entry: dataplex.Entry, localName: string): md.Entry;

package/build/ts/kcmd/snapshot.js

@@ -233,6 +233,13 @@ class CatalogSnapshot {
         }
         await this._layout.saveEntry(localName, local);
     }
+    // Reports what _storeEntry would do with a Dataplex entry, without writing:
+    // the local name it maps to and whether a local copy already exists. Used by
+    // `pull --dry-run`.
+    _previewStoreEntry(entry) {
+        const localName = this.manifest.source.localName(entry);
+        return { localName, exists: this._layout.entryExists(localName) };
+    }
     // Fetches a Dataplex entry from its local metadata representation.
     // This is only meant to be used within the syncing process (as part of push operations).
     async _fetchEntry(name) {

package/build/ts/kcmd/sync.js

@@ -290,6 +290,20 @@ async function fetchEntryLinks(catalog, target, entries) {
     }
     return [...byKey.values()];
 }
+async function withLinkRateLimitRetry(fn) {
+    const baseDelay = process.env.GCP_RETRY_DELAY_MS !== undefined
+        ? Math.max(0, Number(process.env.GCP_RETRY_DELAY_MS) || 0)
+        : 500;
+    let delay = baseDelay;
+    let res = await fn();
+    for (let attempt = 1; attempt < 4 && res.status === 429; attempt++) {
+        if (delay > 0)
+            await new Promise((r) => setTimeout(r, delay));
+        delay = Math.min(delay * 2, 5000);
+        res = await fn();
+    }
+    return res;
+}
 /** Reconciles `bundle/_links.yaml` against the entry group's EntryLinks. */
 async function reconcileLinks(catalog, target, desiredLinks, entries, existingEntries) {
     const existingLinks = new Map();
@@ -304,8 +318,14 @@ async function reconcileLinks(catalog, target, desiredLinks, entries, existingEn
             const res = await catalog.lookupEntryLinks(target.project, target.location, {
                 entry: entryName,
             });
-            if (res.status === 404 || res.status === 501)
+            // A brand-new entry created milliseconds earlier in batchChangeMetadata
+            // can return 403 ("or it may not exist") during regional read-after-create
+            // IAM propagation and has no pre-existing links to delete.
+            if (res.status === 404 ||
+                res.status === 501 ||
+                (res.status === 403 && !existingEntries.has(entryName))) {
                 return [];
+            }
             if (res.status !== 200) {
                 console.error(`  lookupEntryLinks(${entryName}): HTTP ${res.status} ${res.message ?? ''}`);
                 lookupFailed = true;
@@ -345,7 +365,7 @@ async function reconcileLinks(catalog, target, desiredLinks, entries, existingEn
     for (const [id, prev] of existingLinks) {
         const desired = desiredById.get(id);
         if (!desired || (0, links_1.isStaleEntryLink)(prev, desired)) {
-            const del = await catalog.deleteEntryLink(target.project, target.location, target.groupId, id);
+            const del = await withLinkRateLimitRetry(() => catalog.deleteEntryLink(target.project, target.location, target.groupId, id));
             if (del.status !== 200 && del.status !== 404) {
                 console.error(`  ${id}: HTTP ${del.status} ${del.message ?? ''}`);
                 failed++;
@@ -359,11 +379,11 @@ async function reconcileLinks(catalog, target, desiredLinks, entries, existingEn
         const id = (0, links_1.entryLinkId)(link);
         const prev = existingLinks.get(id);
         if (!prev) {
-            const res = await catalog.createEntryLink(target.project, target.location, target.groupId, id, link);
+            const res = await withLinkRateLimitRetry(() => catalog.createEntryLink(target.project, target.location, target.groupId, id, link));
             if (res.status === 409) {
-                const del = await catalog.deleteEntryLink(target.project, target.location, target.groupId, id);
+                const del = await withLinkRateLimitRetry(() => catalog.deleteEntryLink(target.project, target.location, target.groupId, id));
                 if (del.status === 200 || del.status === 404) {
-                    const retry = await catalog.createEntryLink(target.project, target.location, target.groupId, id, link);
+                    const retry = await withLinkRateLimitRetry(() => catalog.createEntryLink(target.project, target.location, target.groupId, id, link));
                     if (retry.status !== 200) {
                         console.error(`  ${id}: HTTP ${retry.status} ${retry.message ?? ''}`);
                         failed++;
@@ -380,7 +400,7 @@ async function reconcileLinks(catalog, target, desiredLinks, entries, existingEn
             }
         }
         else if (JSON.stringify(prev.aspects ?? {}) !== JSON.stringify(link.aspects ?? {})) {
-            const upd = await catalog.updateEntryLink(link, Object.keys(link.aspects ?? {}));
+            const upd = await withLinkRateLimitRetry(() => catalog.updateEntryLink(link, Object.keys(link.aspects ?? {})));
             if (upd.status !== 200) {
                 console.error(`  ${id}: HTTP ${upd.status} ${upd.message ?? ''}`);
                 failed++;
@@ -436,6 +456,8 @@ class CatalogSync {
             const requested = [...aspectTypes.keys()];
             const system = new Set(this._snapshot.manifest.source.systemAspects);
             const leftOut = new Map();
+            let wouldCreate = 0;
+            let wouldUpdate = 0;
             for (const entry of entries) {
                 // TODO: Handle local modification conflicts.
                 // TODO: Handle config changes or service deletions that require removing local entries.
@@ -450,7 +472,18 @@ class CatalogSync {
                 // lookupEntry sets every returned aspect's type.
                 const stored = new Set(Object.values(res.result.aspects ?? {})
                     .map(a => gcp._nameToTypeRef(a.aspectType)));
-                await this._snapshot._storeEntry(res.result);
+                if (options?.dryRun) {
+                    // Reconstruct and report only; never touch the local snapshot.
+                    const { localName, exists } = this._snapshot._previewStoreEntry(res.result);
+                    console.log(`would ${exists ? 'update' : 'create'} ${localName}`);
+                    if (exists)
+                        wouldUpdate++;
+                    else
+                        wouldCreate++;
+                }
+                else {
+                    await this._snapshot._storeEntry(res.result);
+                }
                 const onEntry = await this._catalog.lookupEntryAspectTypes(nameParts[1], nameParts[3], entry.name);
                 for (const type of onEntry.result ?? []) {
                     if (!stored.has(type) && !aspectTypes.has(type) && !system.has(type)) {
@@ -463,6 +496,10 @@ class CatalogSync {
                     `${count === 1 ? 'entry' : 'entries'}; list it under ` +
                     `snapshot.aspects in catalog.yaml to pull it.`);
             }
+            if (options?.dryRun) {
+                console.log(`Dry run: would write ${wouldCreate} new and ${wouldUpdate} updated ` +
+                    `entr${wouldCreate + wouldUpdate === 1 ? 'y' : 'ies'}; no files written (--dry-run).`);
+            }
             return { success: true };
         }
         catch (e) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@google-cloud/kcmd",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "Google Knowledge Catalog Metadata as Code Library, CLI and MCP Server",
   "repository": {
     "type": "git",