@koda-sl/baker-cli 0.161.0 → 0.162.0

package/dist/cli.js

@@ -4265,14 +4265,40 @@ import { defineCommand as defineCommand31 } from "citty";
 
 // src/commands/ads/google/accounts.ts
 import { defineCommand as defineCommand19 } from "citty";
+
+// src/connected-resources.ts
+function listed(resources) {
+  return resources.map((resource) => resource.label ? `${resource.id} (${resource.label})` : resource.id).join("; ");
+}
+function connectedResourceHints({ plural, singular, flag, resources }) {
+  if (resources.length === 0) {
+    return [];
+  }
+  if (resources.length === 1) {
+    return [`This company connected one ${singular}: ${listed(resources)}. Commands use it unless you pass ${flag}.`];
+  }
+  return [
+    `This company connected ${resources.length} ${plural}: ${listed(resources)}. Each command works on one, so pass ${flag} \u2014 nothing is picked for you. A question about the whole business covers all ${resources.length}: answering from one and reporting it as the total is wrong.`
+  ];
+}
+
+// src/commands/ads/google/accounts.ts
 registerSchema({
   command: "ads.google.accounts",
-  description: "List all accessible Google Ads customer accounts. Returns accounts with id, name, access_type (direct or managed), level in the hierarchy, and optional manager_id for managed accounts. Run this first to find account IDs for other commands.",
+  description: "List the Google Ads accounts this company connected \u2014 there can be several, and every one of them is yours to work in. Returns accounts with id, name, access_type (direct or managed), level in the hierarchy, and optional manager_id for managed accounts. Run this first to find account IDs for other commands.",
   args: {
     "no-cache": { type: "boolean", description: "Skip cache, hit API directly", required: false },
     output: { type: "string", description: "Format: json|csv|md", required: false, default: "json" }
   }
 });
+function accountHints(accounts) {
+  return connectedResourceHints({
+    plural: "Google Ads accounts",
+    singular: "Google Ads account",
+    flag: "--customer-id",
+    resources: accounts.map((account) => ({ id: account.id, label: account.name }))
+  });
+}
 function handleAccountsError(err) {
   if (err instanceof ApiError) {
     if (err.code === "UNAUTHORIZED" || err.code === "NOT_FOUND") {
@@ -4313,7 +4339,7 @@ Examples:
     if (useCache) {
       const cached = cacheGet("accounts", "list");
       if (cached) {
-        writeAdsJson({ ok: true, data: cached.data, cached: true });
+        writeJsonEnvelope({ ok: true, data: cached.data, cached: true, hints: accountHints(cached.data) });
         return;
       }
     }
@@ -4328,7 +4354,7 @@ Examples:
         writeAdsOutput(data, format);
         return;
       }
-      writeAdsJson({ ok: true, data });
+      writeJsonEnvelope({ ok: true, data, hints: accountHints(data) });
     } catch (err) {
       handleAccountsError(err);
     }
@@ -4491,6 +4517,16 @@ var GOOGLE_ADS_LIMITS = {
     descriptionTextMax: 90,
     businessNameMax: 25
   },
+  appAd: {
+    headlinesMin: 1,
+    headlinesMax: 5,
+    headlineTextMax: 30,
+    descriptionsMin: 1,
+    descriptionsMax: 5,
+    descriptionTextMax: 90,
+    imagesMax: 20,
+    youtubeVideosMax: 20
+  },
   sharedSet: {
     nameMax: 255
   },
@@ -4843,15 +4879,15 @@ var callAdSchema = z13.strictObject({
 });
 var appAdSchema = z13.strictObject({
   format: z13.literal("app"),
-  headlines: z13.array(z13.object({ text: z13.string().min(1).max(30) })).min(1),
-  descriptions: z13.array(z13.object({ text: z13.string().min(1).max(90) })).min(1),
+  headlines: z13.array(z13.object({ text: z13.string().min(1).max(GOOGLE_ADS_LIMITS.appAd.headlineTextMax) })).min(GOOGLE_ADS_LIMITS.appAd.headlinesMin).max(GOOGLE_ADS_LIMITS.appAd.headlinesMax),
+  descriptions: z13.array(z13.object({ text: z13.string().min(1).max(GOOGLE_ADS_LIMITS.appAd.descriptionTextMax) })).min(GOOGLE_ADS_LIMITS.appAd.descriptionsMin).max(GOOGLE_ADS_LIMITS.appAd.descriptionsMax),
   // An App campaign ad carries its images on its own content (`AppAdInfo.images`), not as
   // campaign-level asset links — same shape as a responsive display ad's marketing images.
-  images: z13.array(refSchema).optional(),
+  images: z13.array(refSchema).max(GOOGLE_ADS_LIMITS.appAd.imagesMax).optional(),
   // `AppAdInfo.youtube_videos` — an App ad's videos live on its content too. Without this field
   // there is no way to express "keep these videos on the ad", so a content update that only
   // restated headlines silently left the ad's videos to whatever the mask happened to omit.
-  youtubeVideos: z13.array(refSchema).optional()
+  youtubeVideos: z13.array(refSchema).max(GOOGLE_ADS_LIMITS.appAd.youtubeVideosMax).optional()
 });
 var videoAdSchema = z13.strictObject({
   format: z13.literal("video"),
@@ -10106,6 +10142,17 @@ Examples:
 // src/commands/ads/linkedin/accounts.ts
 import { defineCommand as defineCommand33 } from "citty";
 var ACCOUNTS_TTL_MS = 60 * 60 * 1e3;
+function accountHints2(accounts, includeAll) {
+  if (includeAll) {
+    return [];
+  }
+  return connectedResourceHints({
+    plural: "LinkedIn ad accounts",
+    singular: "LinkedIn ad account",
+    flag: "--account-id",
+    resources: accounts.map((account) => ({ id: account.externalId, label: account.name }))
+  });
+}
 var accountsCommand2 = defineCommand33({
   meta: {
     name: "accounts",
@@ -10129,7 +10176,12 @@ Examples:
     if (useCache) {
       const cached = cacheGet("linkedin-accounts", cacheKey);
       if (cached) {
-        writeAdsJson({ ok: true, data: cached.data, cached: true });
+        writeJsonEnvelope({
+          ok: true,
+          data: cached.data,
+          cached: true,
+          hints: accountHints2(cached.data, includeAll)
+        });
         return;
       }
     }
@@ -10146,7 +10198,7 @@ Examples:
         writeAdsOutput(data, fmt);
         return;
       }
-      writeAdsJson({ ok: true, data });
+      writeJsonEnvelope({ ok: true, data, hints: accountHints2(data, includeAll) });
     } catch (err) {
       handleLinkedinError(err);
     }
@@ -13118,6 +13170,20 @@ Examples:
 
 // src/commands/ads/meta/accounts.ts
 import { defineCommand as defineCommand53 } from "citty";
+function accountHints3(accounts, includeAll) {
+  if (includeAll) {
+    return [];
+  }
+  return connectedResourceHints({
+    plural: "Meta ad accounts",
+    singular: "Meta ad account",
+    flag: "--account-id",
+    resources: accounts.flatMap((account) => {
+      const id = account.externalId ?? account.id;
+      return id ? [{ id, ...account.name ? { label: account.name } : {} }] : [];
+    })
+  });
+}
 var accountsCommand3 = defineCommand53({
   meta: {
     name: "accounts",
@@ -13141,7 +13207,12 @@ Examples:
     if (useCache) {
       const cached = cacheGet("meta-accounts", cacheKey);
       if (cached) {
-        writeAdsJson({ ok: true, data: cached.data, cached: true });
+        writeJsonEnvelope({
+          ok: true,
+          data: cached.data,
+          cached: true,
+          hints: accountHints3(cached.data, includeAll)
+        });
         return;
       }
     }
@@ -13158,7 +13229,7 @@ Examples:
         writeAdsOutput(data, fmt);
         return;
       }
-      writeAdsJson({ ok: true, data });
+      writeJsonEnvelope({ ok: true, data, hints: accountHints3(data, includeAll) });
     } catch (err) {
       handleMetaError(err);
     }
@@ -15620,12 +15691,20 @@ import { defineCommand as defineCommand85 } from "citty";
 import { defineCommand as defineCommand69 } from "citty";
 registerSchema({
   command: "ads.x.accounts",
-  description: "List all accessible X Ads accounts. Returns accounts with id (base36), name, approval_status, timezone, currency. Run this first to find account IDs for other commands.",
+  description: "List the X Ads accounts this company connected \u2014 there can be several, and every one of them is yours to work in. Returns accounts with id (base36), name, approval_status, timezone, currency. Run this first to find account IDs for other commands.",
   args: {
     "no-cache": { type: "boolean", description: "Skip cache, hit API directly", required: false },
     output: { type: "string", description: "Format: json|csv|md", required: false, default: "json" }
   }
 });
+function accountHints4(accounts) {
+  return connectedResourceHints({
+    plural: "X Ads accounts",
+    singular: "X Ads account",
+    flag: "--account-id",
+    resources: accounts.map((account) => ({ id: account.id, label: account.name }))
+  });
+}
 function handleAccountsError2(err) {
   if (err instanceof ApiError) {
     if (err.code === "UNAUTHORIZED" || err.code === "NOT_FOUND") {
@@ -15663,7 +15742,7 @@ Examples:
     if (useCache) {
       const cached = cacheGet("x-accounts", "list");
       if (cached) {
-        writeAdsJson({ ok: true, data: cached.data, cached: true });
+        writeJsonEnvelope({ ok: true, data: cached.data, cached: true, hints: accountHints4(cached.data) });
         return;
       }
     }
@@ -15678,7 +15757,7 @@ Examples:
         writeAdsOutput(data, format);
         return;
       }
-      writeAdsJson({ ok: true, data });
+      writeJsonEnvelope({ ok: true, data, hints: accountHints4(data) });
     } catch (err) {
       handleAccountsError2(err);
     }
@@ -24961,11 +25040,19 @@ Examples:
 import { defineCommand as defineCommand105 } from "citty";
 registerSchema({
   command: "ga4.properties",
-  description: "List all accessible GA4 properties. Returns property IDs needed for query and audit commands. Run this first to find property IDs.",
+  description: "List the GA4 properties this company connected \u2014 there can be several, and every one of them is yours to query. Returns the property IDs the query and audit commands take. Run this first to find property IDs.",
   args: {
     "no-cache": { type: "boolean", description: "Skip cache, hit API directly", required: false }
   }
 });
+function propertyHints(properties) {
+  return connectedResourceHints({
+    plural: "GA4 properties",
+    singular: "GA4 property",
+    flag: "--property-id",
+    resources: properties.map((property) => ({ id: property.externalId, label: property.name }))
+  });
+}
 var propertiesCommand = defineCommand105({
   meta: {
     name: "properties",
@@ -24983,7 +25070,7 @@ Examples:
     if (useCache) {
       const cached = cacheGet("ga4-properties", "list");
       if (cached) {
-        writeJsonEnvelope({ ok: true, data: cached.data, cached: true });
+        writeJsonEnvelope({ ok: true, data: cached.data, cached: true, hints: propertyHints(cached.data) });
         return;
       }
     }
@@ -24998,7 +25085,7 @@ Examples:
         writeAdsOutput(data, format);
         return;
       }
-      writeJsonEnvelope({ ok: true, data });
+      writeJsonEnvelope({ ok: true, data, hints: propertyHints(data) });
     } catch (err) {
       if (err instanceof ApiError) {
         if (err.code === "UNAUTHORIZED" || err.code === "NOT_FOUND") {
@@ -25588,11 +25675,19 @@ Examples:
 import { defineCommand as defineCommand110 } from "citty";
 registerSchema({
   command: "gsc.sites",
-  description: "List all verified Google Search Console sites. Returns site URLs needed for query and sitemaps commands.",
+  description: "List the Search Console sites this company connected \u2014 there can be several, and every one of them is yours to query. Returns the site URLs the query and sitemaps commands take.",
   args: {
     "no-cache": { type: "boolean", description: "Skip cache, hit API directly", required: false }
   }
 });
+function siteHints(sites) {
+  return connectedResourceHints({
+    plural: "Search Console sites",
+    singular: "Search Console site",
+    flag: "--site-url",
+    resources: sites.map((site) => ({ id: site.siteUrl, label: site.permissionLevel }))
+  });
+}
 var sitesCommand = defineCommand110({
   meta: {
     name: "sites",
@@ -25610,7 +25705,7 @@ Examples:
     if (useCache) {
       const cached = cacheGet("gsc-sites", "list");
       if (cached) {
-        writeJsonEnvelope({ ok: true, data: cached.data, cached: true });
+        writeJsonEnvelope({ ok: true, data: cached.data, cached: true, hints: siteHints(cached.data) });
         return;
       }
     }
@@ -25625,7 +25720,7 @@ Examples:
         writeAdsOutput(data, format);
         return;
       }
-      writeJsonEnvelope({ ok: true, data });
+      writeJsonEnvelope({ ok: true, data, hints: siteHints(data) });
     } catch (err) {
       if (err instanceof ApiError) {
         if (err.code === "UNAUTHORIZED" || err.code === "NOT_FOUND") {
@@ -31803,7 +31898,7 @@ function handleError3(err) {
         ...err.code === "UNAUTHORIZED" ? {
           fix: {
             action: "request_connection",
-            explanation: 'Tag Manager is not connected for this company yet, or no container has been picked. Do NOT send the user to Settings \u2014 call the `request_connection` tool with { platform: "google-tag-manager", reason } and they connect and pick the container from inside the chat. `request_tag_input` is NOT the route: that form manages the container snippet on the site, not what runs inside the container, and it cannot pick a container. If `request_connection` is not available to you, say so plainly and point them at dashboard \u2192 Brain \u2192 Integrations \u2192 Tools \u2192 Google Tag Manager, where they also pick the container. Carry on with the rest of the task meanwhile.'
+            explanation: 'Tag Manager is not connected for this company yet, or no container has been picked. Do NOT send the user to Settings \u2014 call the `request_connection` tool with { platform: "google-tag-manager", reason } and they connect and pick their containers (they can pick more than one) from inside the chat. `request_tag_input` is NOT the route: that form manages the container snippet on the site, not what runs inside the container, and it cannot pick a container. If `request_connection` is not available to you, say so plainly and point them at dashboard \u2192 Brain \u2192 Integrations \u2192 Tools \u2192 Google Tag Manager, where they also pick the container. Carry on with the rest of the task meanwhile.'
           }
         } : {},
         retryable: RETRYABLE_CODES.has(err.code)
@@ -31948,14 +32043,18 @@ var draftCommand3 = defineCommand160({
 import { defineCommand as defineCommand161 } from "citty";
 registerSchema({
   command: "tagManager.containers",
-  description: "List the Google Tag Manager containers this company's connection can reach. The connected container is flagged. Start here to confirm which container you are managing.",
+  description: "List the Google Tag Manager containers this company's connection can reach. Every container the company connected is flagged `connected: true` \u2014 there can be several, and Baker may read and change all of them. Start here to confirm which containers you are managing.",
   args: {}
 });
 registerSchema({
   command: "tagManager.read",
-  description: "Read what is currently inside a Tag Manager container: tags, triggers, variables, folders and enabled built-in variables. Start here before proposing any change, so you edit what exists instead of duplicating it. Compact by default; pass --full for raw Tag Manager objects.",
+  description: "Read what is currently inside a Tag Manager container: tags, triggers, variables, folders and enabled built-in variables. Start here before proposing any change, so you edit what exists instead of duplicating it. Pass --container when the company connected more than one. Compact by default; pass --full for raw Tag Manager objects.",
   args: {
-    container: { type: "string", description: "Numeric container id (defaults to the connected one)", required: false },
+    container: {
+      type: "string",
+      description: "Numeric container id (optional only when one container is connected)",
+      required: false
+    },
     workspace: { type: "string", description: "Workspace id (defaults to the default workspace)", required: false },
     entities: {
       type: "string",
@@ -31965,6 +32064,23 @@ registerSchema({
     full: { type: "boolean", description: "Include the raw Tag Manager object for each entity", required: false }
   }
 });
+function containersHints(containers) {
+  const connected = containers.filter((container) => container.connected);
+  if (connected.length === 0) {
+    return [
+      "None of the containers this company connected came back from Tag Manager. The connected Google account may have lost access to them \u2014 ask the user to reconnect or pick a container again."
+    ];
+  }
+  return connectedResourceHints({
+    plural: "Tag Manager containers",
+    singular: "Tag Manager container",
+    flag: "--container",
+    resources: connected.map((container) => ({
+      id: container.containerId,
+      label: `${container.publicId} \xB7 ${container.name}`
+    }))
+  });
+}
 var containersCommand = defineCommand161({
   meta: {
     name: "containers",
@@ -31976,7 +32092,7 @@ Start here:
   run: async () => {
     try {
       const data = await apiGet("/api/tag-manager/containers");
-      writeJsonEnvelope({ ok: true, data });
+      writeJsonEnvelope({ ok: true, data, hints: containersHints(data.containers) });
     } catch (err) {
       handleError3(err);
     }
@@ -32007,7 +32123,9 @@ Examples:
         entities,
         full: args.full === true
       });
-      const hints = [];
+      const hints = [
+        `This is container ${data.container.containerId} ${data.container.publicId} (${data.container.name}). Stage changes for it with --container ${data.container.containerId}.`
+      ];
       if (data.installedContainerMismatch) {
         hints.push(data.installedContainerMismatch);
       }
@@ -32023,6 +32141,7 @@ Examples:
 
 // src/commands/tag-manager/write-commands.ts
 import { defineCommand as defineCommand162 } from "citty";
+var CONTAINER_ARG_DESCRIPTION = "Numeric container id (optional only when one container is connected \u2014 run `baker tag-manager containers`)";
 var ENTITIES = [
   {
     entity: "tag",
@@ -32056,7 +32175,7 @@ for (const { entity, noun, createHint } of ENTITIES) {
     args: {
       json: { type: "string", description: `Inline JSON ${noun} definition`, required: false },
       file: { type: "string", description: `Path to a JSON file with the ${noun} definition`, required: false },
-      container: { type: "string", description: "Numeric container id", required: false }
+      container: { type: "string", description: CONTAINER_ARG_DESCRIPTION, required: false }
     }
   });
   registerSchema({
@@ -32064,13 +32183,16 @@ for (const { entity, noun, createHint } of ENTITIES) {
     description: `Stage an update to an existing Tag Manager ${noun}. Pass the ${noun} id or path as the positional argument and the changed fields as JSON. Read the container first so you send the fields you mean to change.`,
     args: {
       json: { type: "string", description: "Inline JSON with the changed fields", required: false },
-      file: { type: "string", description: "Path to a JSON file with the changed fields", required: false }
+      file: { type: "string", description: "Path to a JSON file with the changed fields", required: false },
+      container: { type: "string", description: CONTAINER_ARG_DESCRIPTION, required: false }
     }
   });
   registerSchema({
     command: `tagManager.${entity}.delete`,
     description: `Stage the deletion of a Tag Manager ${noun}. Pass its id or path as the positional argument. Deleting is irreversible once the resulting version is published \u2014 confirm with the user first.`,
-    args: {}
+    args: {
+      container: { type: "string", description: CONTAINER_ARG_DESCRIPTION, required: false }
+    }
   });
 }
 function entityCommand(entity, noun, example) {
@@ -32089,7 +32211,7 @@ Examples:
         args: {
           json: { type: "string", description: "Inline JSON definition", required: false },
           file: { type: "string", description: "Path to a JSON file", required: false },
-          container: { type: "string", description: "Numeric container id", required: false }
+          container: { type: "string", description: CONTAINER_ARG_DESCRIPTION, required: false }
         },
         run: async ({ args }) => {
           await stageOp3({
@@ -32108,7 +32230,7 @@ Examples:
           id: { type: "positional", description: `${noun} id or path`, required: false },
           json: { type: "string", description: "Inline JSON with changed fields", required: false },
           file: { type: "string", description: "Path to a JSON file", required: false },
-          container: { type: "string", description: "Numeric container id", required: false }
+          container: { type: "string", description: CONTAINER_ARG_DESCRIPTION, required: false }
         },
         run: async ({ args }) => {
           await stageOp3({
@@ -32123,7 +32245,7 @@ Examples:
         meta: { name: "delete", description: `Stage the deletion of a ${noun} (pass its id or path)` },
         args: {
           id: { type: "positional", description: `${noun} id or path`, required: false },
-          container: { type: "string", description: "Numeric container id", required: false }
+          container: { type: "string", description: CONTAINER_ARG_DESCRIPTION, required: false }
         },
         run: async ({ args }) => {
           await stageOp3({
@@ -32145,7 +32267,8 @@ registerSchema({
   command: "tagManager.builtin",
   description: "Enable or disable Tag Manager built-in variables by type (e.g. clickUrl, pageUrl, formId). Built-in variables must be enabled before a trigger or tag can reference them as {{Click URL}}.",
   args: {
-    types: { type: "string", description: "Comma-separated built-in variable types", required: true }
+    types: { type: "string", description: "Comma-separated built-in variable types", required: true },
+    container: { type: "string", description: CONTAINER_ARG_DESCRIPTION, required: false }
   }
 });
 function builtinTypes(args) {
@@ -32173,7 +32296,7 @@ Examples:
       meta: { name: "enable", description: "Stage enabling built-in variables" },
       args: {
         types: { type: "string", description: "Comma-separated types", required: false },
-        container: { type: "string", description: "Numeric container id", required: false }
+        container: { type: "string", description: CONTAINER_ARG_DESCRIPTION, required: false }
       },
       run: async ({ args }) => {
         await stageOp3({
@@ -32187,7 +32310,7 @@ Examples:
       meta: { name: "disable", description: "Stage disabling built-in variables" },
       args: {
         types: { type: "string", description: "Comma-separated types", required: false },
-        container: { type: "string", description: "Numeric container id", required: false }
+        container: { type: "string", description: CONTAINER_ARG_DESCRIPTION, required: false }
       },
       run: async ({ args }) => {
         await stageOp3({