@google-cloud/cloud-run-mcp 1.5.0 → 1.7.0

package/lib/cloud-api/build.js

@@ -0,0 +1,200 @@
+/*
+Copyright 2025 Google LLC
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    https://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+import { callWithRetry } from './helpers.js';
+import { logAndProgress } from '../util/helpers.js';
+
+const DELAY_WAIT_FOR_BUILD_LOGS = 10000; // 10 seconds delay to allow logs to propagate
+const BUILD_LOGS_LINES_TO_FETCH = 100; // Number of log lines to fetch for build logs snippet
+
+/**
+ * Triggers a Google Cloud Build job to build a container image from source code in a GCS bucket.
+ * It uses either a Dockerfile found in the source or Google Cloud Buildpacks if no Dockerfile is present.
+ * Waits for the build to complete and returns the build result.
+ *
+ * @async
+ * @param {object} context - The context object containing clients and other parameters.
+ * @param {string} projectId - The Google Cloud project ID.
+ * @param {string} location - The Google Cloud region for the build.
+ * @param {string} sourceBucketName - The GCS bucket name where the source code (zip) is stored.
+ * @param {string} sourceBlobName - The GCS blob name (the zip file) for the source code.
+ * @param {string} targetRepoName - The name of the target Artifact Registry repository (used for context, not directly in build steps).
+ * @param {string} targetImageUrl - The full Artifact Registry URL for the image to be built (e.g., `location-docker.pkg.dev/project/repo/image:tag`).
+ * @param {boolean} hasDockerfile - Indicates whether a Dockerfile is present in the source to guide the build process.
+ * @param {function(object): void} [progressCallback] - Optional callback for progress updates.
+ * @returns {Promise<object>} A promise that resolves with the completed Cloud Build object.
+ * @throws {Error} If the Cloud Build job fails, times out, or encounters an error during initiation or execution.
+ */
+export async function triggerCloudBuild(
+  context,
+  projectId,
+  location,
+  sourceBucketName,
+  sourceBlobName,
+  targetRepoName,
+  targetImageUrl,
+  hasDockerfile,
+  progressCallback
+) {
+  let buildSteps;
+
+  if (hasDockerfile) {
+    buildSteps = [
+      {
+        name: 'gcr.io/cloud-builders/docker',
+        args: ['build', '-t', targetImageUrl, '.'],
+        dir: '/workspace',
+      },
+    ];
+  } else {
+    buildSteps = [
+      {
+        name: 'gcr.io/k8s-skaffold/pack',
+        entrypoint: 'pack',
+        args: [
+          'build',
+          targetImageUrl,
+          '--builder',
+          'gcr.io/buildpacks/builder:latest',
+        ],
+        dir: '/workspace',
+      },
+    ];
+  }
+
+  const build = {
+    source: {
+      storageSource: {
+        bucket: sourceBucketName,
+        object: sourceBlobName,
+      },
+    },
+    steps: buildSteps,
+    images: [targetImageUrl],
+  };
+
+  await logAndProgress(
+    `Initiating Cloud Build for gs://${sourceBucketName}/${sourceBlobName} in ${location}...`,
+    progressCallback
+  );
+  const [operation] = await callWithRetry(
+    () =>
+      context.cloudBuildClient.createBuild({
+        projectId: projectId,
+        build: build,
+      }),
+    'cloudBuild.createBuild'
+  );
+
+  await logAndProgress(`Cloud Build job started...`, progressCallback);
+  const buildId = operation.metadata.build.id;
+  let completedBuild;
+  while (true) {
+    const [getBuildOperation] = await callWithRetry(
+      () =>
+        context.cloudBuildClient.getBuild({
+          projectId: projectId,
+          id: buildId,
+        }),
+      `cloudBuild.getBuild ${buildId}`
+    );
+    if (
+      ['SUCCESS', 'FAILURE', 'INTERNAL_ERROR', 'TIMEOUT', 'CANCELLED'].includes(
+        getBuildOperation.status
+      )
+    ) {
+      completedBuild = getBuildOperation;
+      break;
+    }
+    await logAndProgress(
+      `Build status: ${getBuildOperation.status}. Waiting...`,
+      progressCallback,
+      'debug'
+    );
+    await new Promise((resolve) => setTimeout(resolve, 5000));
+  }
+
+  if (completedBuild.status === 'SUCCESS') {
+    await logAndProgress(
+      `Cloud Build job ${buildId} completed successfully.`,
+      progressCallback
+    );
+    await logAndProgress(
+      `Image built: ${completedBuild.results.images[0].name}`,
+      progressCallback
+    );
+    return completedBuild;
+  } else {
+    const failureMessage = `Cloud Build job ${buildId} failed with status: ${completedBuild.status}`;
+    await logAndProgress(failureMessage, progressCallback, 'error');
+    const logsMessage = `Build logs: ${completedBuild.logUrl}`;
+    await logAndProgress(logsMessage, progressCallback); // Log URL is info, failure is error
+
+    let buildLogsSnippet = `\n\nRefer to Log URL for full details: ${completedBuild.logUrl}`; // Default snippet
+    try {
+      const logFilter = `resource.type="build" AND resource.labels.build_id="${buildId}"`;
+      await logAndProgress(
+        `Attempting to fetch last ${BUILD_LOGS_LINES_TO_FETCH} log lines for build ${buildId}...`,
+        progressCallback,
+        'debug'
+      );
+
+      // Wait for a short period to allow logs to propagate
+      await new Promise((resolve) =>
+        setTimeout(resolve, DELAY_WAIT_FOR_BUILD_LOGS)
+      );
+
+      // Fetch the most recent N log entries
+      const [entries] = await callWithRetry(
+        () =>
+          context.loggingClient.getEntries({
+            filter: logFilter,
+            orderBy: 'timestamp desc', // Get latest logs first
+            pageSize: BUILD_LOGS_LINES_TO_FETCH,
+          }),
+        `logging.getEntries for build ${buildId}`
+      );
+
+      if (entries && entries.length > 0) {
+        // Entries are newest first, reverse for chronological order of the snippet
+        const logLines = entries.reverse().map((entry) => entry.data || '');
+        if (logLines.length > 0) {
+          buildLogsSnippet = `\n\nLast ${logLines.length} log lines from build ${buildId}:\n${logLines.join('\n')}`;
+          await logAndProgress(
+            `Successfully fetched snippet of build logs for ${buildId}.`,
+            progressCallback,
+            'info'
+          );
+        }
+      } else {
+        await logAndProgress(
+          `No specific log entries retrieved for build ${buildId}. ${buildLogsSnippet}`,
+          progressCallback,
+          'warn'
+        );
+      }
+    } catch (logError) {
+      console.error(`Error fetching build logs for ${buildId}:`, logError);
+      await logAndProgress(
+        `Failed to fetch build logs snippet: ${logError.message}. ${buildLogsSnippet}`,
+        progressCallback,
+        'warn'
+      );
+      // buildLogsSnippet already contains the Log URL as a fallback
+    }
+    throw new Error(`Build ${buildId} failed.${buildLogsSnippet}`);
+  }
+}

package/lib/{gcp-api-helpers.js → cloud-api/helpers.js}

@@ -14,6 +14,13 @@ See the License for the specific language governing permissions and
 limitations under the License.
 */
 
+import { ensureBillingEnabled } from './billing.js';
+
+const PREREQUISITE_APIS = [
+  'serviceusage.googleapis.com',
+  'cloudbilling.googleapis.com',
+];
+
 /**
  * Calls a function with retry logic for GCP API calls.
  * Retries on gRPC error code 7 (PERMISSION_DENIED).
@@ -84,12 +91,61 @@ async function checkAndEnableApi(
   }
 }
 
+/**
+ * Enables a single Google Cloud API with retry logic.
+ * @param {object} serviceUsageClient - The Service Usage client.
+ * @param {string} projectId - The Google Cloud project ID.
+ * @param {string} api - The API identifier (e.g., 'run.googleapis.com').
+ * @param {function(string, string=): void} progressCallback - A function to call with progress updates.
+ * @returns {Promise<void>} A promise that resolves when the API is enabled.
+ * @throws {Error} If the API fails to enable or if there's an issue checking its status.
+ */
+export async function enableApiWithRetry(
+  serviceUsageClient,
+  projectId,
+  api,
+  progressCallback
+) {
+  const serviceName = `projects/${projectId}/services/${api}`;
+  try {
+    await checkAndEnableApi(
+      serviceUsageClient,
+      serviceName,
+      api,
+      progressCallback
+    );
+  } catch (error) {
+    // First attempt failed, log a warning and retry once after a delay.
+    const warnMsg = `Failed to check/enable ${api}, retrying in 1s...`;
+    console.warn(warnMsg);
+    if (progressCallback) progressCallback({ level: 'warn', data: warnMsg });
+
+    await new Promise((resolve) => setTimeout(resolve, 1000));
+    try {
+      await checkAndEnableApi(
+        serviceUsageClient,
+        serviceName,
+        api,
+        progressCallback
+      );
+    } catch (retryError) {
+      // If the retry also fails, throw an error.
+      const errorMessage = `Failed to ensure API [${api}] is enabled after retry. Please check manually.`;
+      console.error(errorMessage, retryError);
+      if (progressCallback)
+        progressCallback({ level: 'error', data: errorMessage });
+      throw new Error(errorMessage);
+    }
+  }
+}
+
 /**
  * Ensures that the specified Google Cloud APIs are enabled for the given project.
  * If an API is not enabled, it attempts to enable it.  Retries any failure once after 1s.
  * Throws an error if an API cannot be enabled.
  *
  * @async
+ * @param {object} context - The context object containing clients and other parameters.
  * @param {string} projectId - The Google Cloud project ID.
  * @param {string[]} apis - An array of API identifiers to check and enable (e.g., 'run.googleapis.com').
  * @param {function(string, string=): void} progressCallback - A function to call with progress updates.
@@ -97,47 +153,37 @@ async function checkAndEnableApi(
  * @throws {Error} If an API fails to enable or if there's an issue checking its status.
  * @returns {Promise<void>} A promise that resolves when all specified APIs are enabled.
  */
-export async function ensureApisEnabled(projectId, apis, progressCallback) {
-  const { ServiceUsageClient } = await import('@google-cloud/service-usage');
-  const serviceUsageClient = new ServiceUsageClient({ projectId });
+export async function ensureApisEnabled(
+  context,
+  projectId,
+  apis,
+  progressCallback
+) {
+  for (const api of PREREQUISITE_APIS) {
+    await enableApiWithRetry(
+      context.serviceUsageClient,
+      projectId,
+      api,
+      progressCallback
+    );
+  }
+
+  // Before enabling other APIs, ensure billing is enabled.
+  await ensureBillingEnabled(context, projectId, progressCallback);
+
   const message = 'Checking and enabling required APIs...';
   console.log(message);
   if (progressCallback) progressCallback({ level: 'info', data: message });
 
-
   for (const api of apis) {
-    const serviceName = `projects/${projectId}/services/${api}`;
-    try {
-      await checkAndEnableApi(
-        serviceUsageClient,
-        serviceName,
-        api,
-        progressCallback
-      );
-    } catch (error) {
-      // First attempt failed, log a warning and retry once after a delay.
-      const warnMsg = `Failed to check/enable ${api}, retrying in 1s...`;
-      console.warn(warnMsg);
-      if (progressCallback) progressCallback({ level: 'warn', data: warnMsg });
-
-      await new Promise((resolve) => setTimeout(resolve, 1000));
-      try {
-        await checkAndEnableApi(
-          serviceUsageClient,
-          serviceName,
-          api,
-          progressCallback
-        );
-      } catch (retryError) {
-        // If the retry also fails, throw an error.
-        const errorMessage = `Failed to ensure API [${api}] is enabled after retry. Please check manually.`;
-        console.error(errorMessage, retryError);
-        if (progressCallback) progressCallback({ level: 'error', data: errorMessage });
-        throw new Error(errorMessage);
-      }
-    }
+    await enableApiWithRetry(
+      context.serviceUsageClient,
+      projectId,
+      api,
+      progressCallback
+    );
   }
   const successMsg = 'All required APIs are enabled.';
   console.log(successMsg);
   if (progressCallback) progressCallback({ level: 'info', data: successMsg });
-}
+}

package/lib/{gcp-projects.js → cloud-api/projects.js}

@@ -17,7 +17,7 @@ limitations under the License.
 import {
   listBillingAccounts,
   attachProjectToBillingAccount,
-} from './gcp-billing-accounts.js';
+} from './billing.js';
 
 /**
  * Lists all accessible Google Cloud Platform projects.
@@ -39,40 +39,50 @@ export async function listProjects() {
   }
 }
 
+/**
+ * Creates a compliant GCP project ID in the format 'mcp-cvc-cvc', where 'c' is a consonant and 'v' is a vowel.
+ * @function generateProjectId
+ * @returns {string} A randomly generated, compliant GCP project ID in the format 'mcp-cvc-cvc'.
+ */
+export function generateProjectId() {
+  const consonants = 'bcdfghjklmnpqrstvwxyz';
+  const vowels = 'aeiou';
+
+  const getRandomChar = (source) =>
+    source.charAt(Math.floor(Math.random() * source.length));
+
+  const generateCVC = () => {
+    const c1 = getRandomChar(consonants);
+    const v = getRandomChar(vowels);
+    const c2 = getRandomChar(consonants);
+    return `${c1}${v}${c2}`;
+  };
+
+  const cvc1 = generateCVC();
+  const cvc2 = generateCVC();
+  return `mcp-${cvc1}-${cvc2}`;
+}
+
 /**
  * Creates a new Google Cloud Platform project.
  * @async
  * @function createProject
  * @param {string} [projectId] - Optional. The desired ID for the new project. If not provided, a compliant ID will be generated automatically (e.g., app-cvc-cvc).
+ * @param {string} [parent] - Optional. The resource name of the parent under which the project is to be created. e.g., "organizations/123" or "folders/456".
  * @returns {Promise<{projectId: string}|null>} A promise that resolves to an object containing the new project's ID.
  */
-export async function createProject(projectId) {
+export async function createProject(projectId, parent) {
   const { ProjectsClient } = await import('@google-cloud/resource-manager');
   const client = new ProjectsClient();
   let projectIdToUse = projectId;
 
   if (!projectIdToUse) {
-    const consonants = 'bcdfghjklmnpqrstvwxyz';
-    const vowels = 'aeiou';
-
-    const getRandomChar = (source) =>
-      source.charAt(Math.floor(Math.random() * source.length));
-
-    const generateCVC = () => {
-      const c1 = getRandomChar(consonants);
-      const v = getRandomChar(vowels);
-      const c2 = getRandomChar(consonants);
-      return `${c1}${v}${c2}`;
-    };
-
-    const cvc1 = generateCVC();
-    const cvc2 = generateCVC();
-    projectIdToUse = `mcp-${cvc1}-${cvc2}`;
+    projectIdToUse = generateProjectId();
     console.log(`Project ID not provided, generated ID: ${projectIdToUse}`);
   }
 
   try {
-    const projectPayload = { projectId: projectIdToUse };
+    const projectPayload = { projectId: projectIdToUse, parent };
 
     console.log(`Attempting to create project with ID: ${projectIdToUse}`);
 
@@ -100,12 +110,13 @@ export async function createProject(projectId) {
  * @async
  * @function createProjectAndAttachBilling
  * @param {string} [projectIdParam] - Optional. The desired ID for the new project.
+ * @param {string} [parent] - Optional. The resource name of the parent under which the project is to be created. e.g., "organizations/123" or "folders/456".
  * @returns {Promise<{projectId: string, billingMessage: string}>} A promise that resolves to an object containing the project ID and a billing status message.
  */
-export async function createProjectAndAttachBilling(projectIdParam) {
+export async function createProjectAndAttachBilling(projectIdParam, parent) {
   let newProject;
   try {
-    newProject = await createProject(projectIdParam);
+    newProject = await createProject(projectIdParam, parent);
   } catch (error) {
     throw new Error(`Failed to create project: ${error.message}`);
   }
@@ -115,7 +126,7 @@ export async function createProjectAndAttachBilling(projectIdParam) {
   }
 
   const { projectId } = newProject;
-  let billingMessage = `Project ${projectId} created.`;
+  let billingMessage = `Project ${projectId} created successfully.`;
 
   try {
     const billingAccounts = await listBillingAccounts();
@@ -130,27 +141,46 @@ export async function createProjectAndAttachBilling(projectIdParam) {
           firstBillingAccount.name
         );
         if (billingInfo && billingInfo.billingEnabled) {
-          billingMessage += ` Successfully attached to billing account ${firstBillingAccount.displayName}.`;
+          billingMessage += ` It has been attached to billing account ${firstBillingAccount.displayName}.`;
         } else {
-          billingMessage += ` Could not attach to billing account ${firstBillingAccount.displayName} or billing not enabled. Please check manually. Console: https://console.cloud.google.com/billing/linkedaccount?project=${projectId}`;
+          billingMessage += ` However, it could not be attached to billing account ${firstBillingAccount.displayName} or billing not enabled. Please check manually: https://console.cloud.google.com/billing/linkedaccount?project=${projectId}`;
         }
       } else {
         const allBillingAccounts = billingAccounts
           .map((b) => `${b.displayName} (Open: ${b.open})`)
           .join(', ');
-        billingMessage += ` No open billing accounts found. Available (may not be usable): ${allBillingAccounts || 'None'}. Please link billing manually: https://console.cloud.google.com/billing/linkedaccount?project=${projectId}`;
+        billingMessage += ` However, no open billing accounts were found. Available (may not be usable): ${allBillingAccounts || 'None'}. Please link billing manually: https://console.cloud.google.com/billing/linkedaccount?project=${projectId}`;
       }
     } else {
-      billingMessage +=
-        ' No billing accounts found. Please link billing manually: https://console.cloud.google.com/billing/linkedaccount?project=${projectId}';
+      billingMessage += ` However, no billing accounts were found. Please link billing manually: https://console.cloud.google.com/billing/linkedaccount?project=${projectId}`;
     }
   } catch (billingError) {
     console.error(
       `Error during billing operations for project ${projectId}:`,
       billingError
     );
-    billingMessage += ` Error during billing operations: ${billingError.message}. Please check manually: https://console.cloud.google.com/billing/linkedaccount?project=${projectId}`;
+    billingMessage += ` However, an error occurred during billing operations: ${billingError.message}. Please check manually: https://console.cloud.google.com/billing/linkedaccount?project=${projectId}`;
   }
 
   return { projectId, billingMessage };
 }
+
+/**
+ * Deletes a Google Cloud Platform project.
+ * @async
+ * @function deleteProject
+ * @param {string} projectId - The ID of the project to delete.
+ * @returns {Promise<void>} A promise that resolves when the delete operation is initiated.
+ */
+export async function deleteProject(projectId) {
+  const { ProjectsClient } = await import('@google-cloud/resource-manager');
+  const client = new ProjectsClient();
+  try {
+    console.log(`Attempting to delete project with ID: ${projectId}`);
+    await client.deleteProject({ name: `projects/${projectId}` });
+    console.log(`Project ${projectId} deletion initiated successfully.`);
+  } catch (error) {
+    console.error(`Error deleting GCP project ${projectId}:`, error.message);
+    throw error; // Re-throw to be caught by the caller
+  }
+}

package/lib/cloud-api/registry.js

@@ -0,0 +1,98 @@
+/*
+Copyright 2025 Google LLC
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    https://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+import { callWithRetry } from './helpers.js';
+import { logAndProgress } from '../util/helpers.js';
+
+/**
+ * Ensures that an Artifact Registry repository exists.
+ * If the repository does not exist, it attempts to create it with the specified format.
+ *
+ * @async
+ * @param {object} context - The context object containing clients and other parameters.
+ * @param {string} projectId - The Google Cloud project ID.
+ * @param {string} location - The Google Cloud region for the repository.
+ * @param {string} repositoryId - The ID for the Artifact Registry repository.
+ * @param {string} [format='DOCKER'] - The format of the repository (e.g., 'DOCKER', 'NPM'). Defaults to 'DOCKER'.
+ * @param {function(object): void} [progressCallback] - Optional callback for progress updates.
+ * @returns {Promise<object>} A promise that resolves with the Artifact Registry repository object.
+ * @throws {Error} If there's an error checking or creating the repository.
+ */
+export async function ensureArtifactRegistryRepoExists(
+  context,
+  projectId,
+  location,
+  repositoryId,
+  format = 'DOCKER',
+  progressCallback
+) {
+  const parent = `projects/${projectId}/locations/${location}`;
+  const repoPath = context.artifactRegistryClient.repositoryPath(
+    projectId,
+    location,
+    repositoryId
+  );
+
+  try {
+    const [repository] = await callWithRetry(
+      () => context.artifactRegistryClient.getRepository({ name: repoPath }),
+      `artifactRegistry.getRepository ${repositoryId}`
+    );
+    await logAndProgress(
+      `Repository ${repositoryId} already exists in ${location}.`,
+      progressCallback
+    );
+    return repository;
+  } catch (error) {
+    if (error.code === 5) {
+      await logAndProgress(
+        `Repository ${repositoryId} does not exist in ${location}. Creating...`,
+        progressCallback
+      );
+      const repositoryToCreate = {
+        format: format,
+      };
+
+      const [operation] = await callWithRetry(
+        () =>
+          context.artifactRegistryClient.createRepository({
+            parent: parent,
+            repository: repositoryToCreate,
+            repositoryId: repositoryId,
+          }),
+        `artifactRegistry.createRepository ${repositoryId}`
+      );
+      await logAndProgress(
+        `Creating Artifact Registry repository ${repositoryId}...`,
+        progressCallback
+      );
+      const [result] = await operation.promise();
+      await logAndProgress(
+        `Artifact Registry repository ${result.name} created successfully.`,
+        progressCallback
+      );
+      return result;
+    } else {
+      const errorMessage = `Error checking/creating repository ${repositoryId}: ${error.message}`;
+      console.error(
+        `Error checking/creating repository ${repositoryId}:`,
+        error
+      );
+      await logAndProgress(errorMessage, progressCallback, 'error');
+      throw error;
+    }
+  }
+}