@rigkit/provider-gcloud-cli 0.0.0-canary-20260518T014918-c5bc0c2

package/README.md

@@ -0,0 +1,33 @@
+# @rigkit/provider-gcloud-cli
+
+Copy local `gcloud` config/auth files into rigkit workspaces.
+
+This provider does not own Google OAuth. It requires the developer's local machine to have `gcloud` installed and authenticated, then copies selected files from the local gcloud config directory into a workspace. This makes normal VM-side commands such as `gcloud auth list` behave like they do locally.
+
+```ts
+import { workflow } from "@rigkit/sdk";
+import {
+  copyGcloudConfig,
+  gcloudConfigCopyInjectionSteps,
+  gcloudCopiedConfigReadyCommand,
+} from "@rigkit/provider-gcloud-cli";
+
+const app = workflow("example", {
+  providers: {
+    gcloudConfig: copyGcloudConfig.provider({
+      requireAuth: true,
+    }),
+  },
+});
+
+// Inside a workspace operation:
+const gcloudConfigFiles = await providers.gcloudConfig.configFiles();
+for (const step of gcloudConfigCopyInjectionSteps(gcloudConfigFiles)) {
+  await vm.exec(step.command, { name: step.name, env: step.env });
+}
+
+const verified = await vm.probe(gcloudCopiedConfigReadyCommand());
+if (!verified.ok) throw new Error("gcloud did not accept the copied config files");
+```
+
+By default, provider startup requires local `gcloud` to be installed and authenticated before Rigkit runs project commands. If local `gcloud` is missing, startup fails with the Google Cloud SDK install URL. If it is not authenticated, startup asks the user to run `gcloud auth login`.

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@rigkit/provider-gcloud-cli",
+  "version": "0.0.0-canary-20260518T014918-c5bc0c2",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/freestyle-sh/rigkit.git",
+    "directory": "packages/provider-gcloud-cli"
+  },
+  "exports": {
+    ".": "./src/index.ts",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "dependencies": {
+    "zod": "^4",
+    "@rigkit/sdk": "0.0.0-canary-20260518T014918-c5bc0c2",
+    "@rigkit/engine": "0.0.0-canary-20260518T014918-c5bc0c2"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "typescript": "latest"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc --noEmit",
+    "typecheck": "tsc --noEmit",
+    "test": "bun test"
+  }
+}

package/src/duration.ts

@@ -0,0 +1,46 @@
+export type DurationInput = number | string;
+
+const units: Record<string, number> = {
+  ms: 1,
+  millisecond: 1,
+  milliseconds: 1,
+  s: 1000,
+  sec: 1000,
+  secs: 1000,
+  second: 1000,
+  seconds: 1000,
+  m: 60 * 1000,
+  min: 60 * 1000,
+  mins: 60 * 1000,
+  minute: 60 * 1000,
+  minutes: 60 * 1000,
+  h: 60 * 60 * 1000,
+  hr: 60 * 60 * 1000,
+  hrs: 60 * 60 * 1000,
+  hour: 60 * 60 * 1000,
+  hours: 60 * 60 * 1000,
+  d: 24 * 60 * 60 * 1000,
+  day: 24 * 60 * 60 * 1000,
+  days: 24 * 60 * 60 * 1000,
+};
+
+export function parseDurationMs(value: DurationInput): number {
+  if (typeof value === "number") {
+    if (!Number.isFinite(value) || value < 0) throw new Error(`Duration must be a non-negative number`);
+    return Math.floor(value);
+  }
+
+  const trimmed = value.trim().toLowerCase();
+  const match = /^(\d+(?:\.\d+)?)\s*([a-z]+)$/.exec(trimmed);
+  if (!match) {
+    throw new Error(`Invalid duration ${JSON.stringify(value)}. Use values like "30m", "6h", or "1day".`);
+  }
+
+  const amount = Number(match[1]);
+  const unit = units[match[2]!];
+  if (!unit) {
+    throw new Error(`Invalid duration unit ${JSON.stringify(match[2])}`);
+  }
+
+  return Math.floor(amount * unit);
+}

package/src/index.ts

@@ -0,0 +1,100 @@
+import { defineProvider, type WorkflowProviderDefinition } from "@rigkit/sdk";
+import type { BaseProviderPlugin } from "@rigkit/engine";
+import * as z from "zod/v4-mini";
+import {
+  assertLocalGcloudReady,
+  createGcloudConfigCopyController,
+  GCLOUD_CONFIG_COPY_PROVIDER_ID,
+  requiresLocalGcloudAuth,
+  type GcloudConfigCopyConfig,
+  type GcloudConfigCopyRuntime,
+} from "./provider.ts";
+import { createGcloudAuthStore } from "./store.ts";
+
+const gcloudConfigCopyProviderConfigSchema = z.object({
+  command: z.optional(z.string()),
+  requireAuth: z.optional(z.boolean()),
+  key: z.optional(z.string()),
+  account: z.optional(z.string()),
+  scopes: z.optional(z.array(z.string())),
+  installUrl: z.optional(z.string()),
+  accessTokenLifetimeSeconds: z.optional(z.number()),
+  configDir: z.optional(z.string()),
+});
+
+export type GcloudConfigCopyProviderConfig = z.output<typeof gcloudConfigCopyProviderConfigSchema>;
+
+export type GcloudConfigCopyProviderDefinition = WorkflowProviderDefinition<
+  typeof GCLOUD_CONFIG_COPY_PROVIDER_ID,
+  GcloudConfigCopyProviderConfig,
+  GcloudConfigCopyRuntime
+>;
+
+export function provider(config: GcloudConfigCopyProviderDefinition["config"] = {}): GcloudConfigCopyProviderDefinition {
+  return defineProvider(GCLOUD_CONFIG_COPY_PROVIDER_ID, config, gcloudConfigCopyProviderPlugin);
+}
+
+export const copyGcloudConfig = {
+  provider,
+};
+
+export const defineGcloudConfigCopyProvider = provider;
+
+export const gcloudConfigCopyProviderPlugin: BaseProviderPlugin = {
+  providerId: GCLOUD_CONFIG_COPY_PROVIDER_ID,
+  async createProvider({ provider, storage }) {
+    const config = parseGcloudConfigCopyProviderConfig(provider.config);
+    if (requiresLocalGcloudAuth(config)) {
+      await assertLocalGcloudReady(config);
+    }
+    return createGcloudConfigCopyController(config, createGcloudAuthStore(storage));
+  },
+};
+
+export {
+  assertLocalGcloudReady,
+  DEFAULT_GCLOUD_AUTH_SCOPES,
+  DEFAULT_GCLOUD_INSTALL_URL,
+  GCLOUD_CONFIG_COPY_PROVIDER_ID,
+  createGcloudConfigCopyController,
+  requiresLocalGcloudAuth,
+} from "./provider.ts";
+export {
+  DEFAULT_GCLOUD_ACCESS_TOKEN_EXPIRES_AT_PATH,
+  DEFAULT_GCLOUD_ACCESS_TOKEN_PATH,
+  DEFAULT_GCLOUD_CONFIG_DIR,
+  gcloudAccessTokenFreshCommand,
+  gcloudAccessTokenInjection,
+  gcloudConfigCopyInjection,
+  gcloudConfigCopyInjectionSteps,
+  gcloudCopiedConfigReadyCommand,
+} from "./inject.ts";
+export { createGcloudAuthStore, normalizeScopes } from "./store.ts";
+export { RIGKIT_PROVIDER_GCLOUD_CLI_VERSION } from "./version.ts";
+export type {
+  GcloudConfigCopyConfig,
+  GcloudConfigCopyRuntime,
+  GcloudConfigFilesOptions,
+  GcloudCommandResult,
+  GcloudCommandRunner,
+  GcloudFreshAccessTokenOptions,
+} from "./provider.ts";
+export type {
+  GcloudAccessCredentials,
+  GcloudAccessTokenInjection,
+  GcloudAccessTokenInjectionOptions,
+  GcloudConfigCopy,
+  GcloudConfigFile,
+  GcloudConfigCopyInjection,
+  GcloudConfigCopyInjectionOptions,
+  GcloudConfigCopyInjectionStep,
+} from "./inject.ts";
+export type { GcloudCredentialsInput, GcloudStoredCredentials } from "./store.ts";
+
+function parseGcloudConfigCopyProviderConfig(value: unknown): GcloudConfigCopyConfig {
+  const result = z.safeParse(gcloudConfigCopyProviderConfigSchema, value);
+  if (!result.success) {
+    throw new Error(`Invalid gcloud config copy provider config:\n${z.prettifyError(result.error)}`);
+  }
+  return result.data;
+}

package/src/inject.test.ts

@@ -0,0 +1,70 @@
+import { describe, expect, test } from "bun:test";
+import {
+  gcloudAccessTokenFreshCommand,
+  gcloudAccessTokenInjection,
+  gcloudConfigCopyInjection,
+  gcloudConfigCopyInjectionSteps,
+  gcloudCopiedConfigReadyCommand,
+} from "./inject.ts";
+
+describe("gcloud config copy helpers", () => {
+  test("keeps token material in env instead of the emitted command", () => {
+    const injection = gcloudAccessTokenInjection({
+      accessToken: "secret-token",
+      tokenType: "Bearer",
+      expiresAt: new Date(Date.now() + 60_000).toISOString(),
+      account: "dev@example.com",
+      scopes: ["openid"],
+    });
+
+    expect(injection.command).not.toContain("secret-token");
+    expect(injection.env.RIGKIT_GCLOUD_CLI_ACCESS_TOKEN).toBe("secret-token");
+    expect(injection.env.RIGKIT_GCLOUD_CLI_ACCOUNT).toBe("dev@example.com");
+    expect(injection.command).toContain("gcloud config set auth/access_token_file");
+    expect(injection.command).toContain("gcloud config set account");
+  });
+
+  test("supports hour-style freshness checks", () => {
+    const command = gcloudAccessTokenFreshCommand({ minExpiration: "6hrs" });
+    expect(command).toContain("21600000");
+  });
+
+  test("copies gcloud config files without embedding file contents in the command", () => {
+    const injection = gcloudConfigCopyInjection({
+      sourceConfigDir: "/Users/dev/.config/gcloud",
+      account: "dev@example.com",
+      files: [
+        { path: "active_config", contentsBase64: Buffer.from("default").toString("base64") },
+        { path: "credentials.db", contentsBase64: "secret-db-base64" },
+      ],
+    });
+
+    expect(injection.command).toContain("rm -rf \"$config_dir\"");
+    expect(injection.command).toContain("gcloud CLI is not installed");
+    expect(injection.command).toContain("credentials.db");
+    expect(injection.command).toContain("gcloud config set account");
+    expect(injection.command).not.toContain("secret-db-base64");
+    expect(injection.env.RIGKIT_GCLOUD_CLI_CONFIG_FILE_1).toBe("secret-db-base64");
+    expect(injection.env.RIGKIT_GCLOUD_CLI_ACCOUNT).toBe("dev@example.com");
+    expect(gcloudCopiedConfigReadyCommand()).toContain("gcloud auth list");
+  });
+
+  test("splits copied gcloud config files into small upload steps", () => {
+    const steps = gcloudConfigCopyInjectionSteps(
+      {
+        sourceConfigDir: "/Users/dev/.config/gcloud",
+        files: [
+          { path: "credentials.db", contentsBase64: "1234567890abcdef" },
+        ],
+      },
+      { chunkSize: 8 },
+    );
+
+    expect(steps).toHaveLength(3);
+    expect(steps[0]!.name).toBe("prepare gcloud config copy");
+    expect(steps[1]!.env.RIGKIT_GCLOUD_CLI_CONFIG_FILE_CHUNK).toBe("12345678");
+    expect(steps[2]!.env.RIGKIT_GCLOUD_CLI_CONFIG_FILE_CHUNK).toBe("90abcdef");
+    expect(steps[1]!.command).toContain(": > \"$config_dir/credentials.db\"");
+    expect(steps[2]!.command).not.toContain(": > \"$config_dir/credentials.db\"");
+  });
+});

package/src/inject.ts

@@ -0,0 +1,259 @@
+import type { ExecOptions } from "@rigkit/sdk";
+import { parseDurationMs, type DurationInput } from "./duration.ts";
+
+export const DEFAULT_GCLOUD_ACCESS_TOKEN_PATH = "${HOME:-/root}/.config/rigkit/gcloud/access-token";
+export const DEFAULT_GCLOUD_ACCESS_TOKEN_EXPIRES_AT_PATH = "${HOME:-/root}/.config/rigkit/gcloud/expires-at-ms";
+export const DEFAULT_GCLOUD_CONFIG_DIR = "${HOME:-/root}/.config/gcloud";
+
+export type GcloudAccessCredentials = {
+  accessToken: string;
+  tokenType: string;
+  expiresAt: string;
+  account?: string | null;
+  scopes: string[];
+};
+
+export type GcloudAccessTokenInjectionOptions = {
+  tokenPath?: string;
+  expiresAtPath?: string;
+};
+
+export type GcloudAccessTokenInjection = {
+  command: string;
+  env: NonNullable<ExecOptions["env"]>;
+};
+
+export type GcloudConfigFile = {
+  path: string;
+  contentsBase64: string;
+};
+
+export type GcloudConfigCopy = {
+  sourceConfigDir: string;
+  account?: string | null;
+  files: GcloudConfigFile[];
+};
+
+export type GcloudConfigCopyInjectionOptions = {
+  configDir?: string;
+  chunkSize?: number;
+};
+
+export type GcloudConfigCopyInjection = {
+  command: string;
+  env: NonNullable<ExecOptions["env"]>;
+};
+
+export type GcloudConfigCopyInjectionStep = GcloudConfigCopyInjection & {
+  name: string;
+};
+
+export function gcloudAccessTokenInjection(
+  credentials: GcloudAccessCredentials,
+  options: GcloudAccessTokenInjectionOptions = {},
+): GcloudAccessTokenInjection {
+  const expiresAtMs = Date.parse(credentials.expiresAt);
+  if (!Number.isFinite(expiresAtMs)) {
+    throw new Error(`Invalid gcloud credential expiration ${JSON.stringify(credentials.expiresAt)}`);
+  }
+
+  return {
+    command: [
+      "set -e",
+      'export HOME="${HOME:-/root}"',
+      `token_path=${shellPathExpression(options.tokenPath, DEFAULT_GCLOUD_ACCESS_TOKEN_PATH)}`,
+      `expires_at_path=${shellPathExpression(options.expiresAtPath, DEFAULT_GCLOUD_ACCESS_TOKEN_EXPIRES_AT_PATH)}`,
+      'command -v gcloud >/dev/null 2>&1 || { echo "gcloud CLI is not installed" >&2; exit 1; }',
+      'mkdir -p "$(dirname "$token_path")" "$(dirname "$expires_at_path")"',
+      "umask 077",
+      'printf "%s\\n" "$RIGKIT_GCLOUD_CLI_ACCESS_TOKEN" > "$token_path"',
+      'printf "%s\\n" "$RIGKIT_GCLOUD_CLI_EXPIRES_AT_MS" > "$expires_at_path"',
+      'gcloud config set auth/access_token_file "$token_path" >/dev/null',
+      'if [ -n "${RIGKIT_GCLOUD_CLI_ACCOUNT:-}" ]; then',
+      '  gcloud config set account "$RIGKIT_GCLOUD_CLI_ACCOUNT" >/dev/null',
+      "fi",
+    ].join("\n"),
+    env: {
+      RIGKIT_GCLOUD_CLI_ACCESS_TOKEN: credentials.accessToken,
+      RIGKIT_GCLOUD_CLI_EXPIRES_AT: credentials.expiresAt,
+      RIGKIT_GCLOUD_CLI_EXPIRES_AT_MS: String(expiresAtMs),
+      RIGKIT_GCLOUD_CLI_ACCOUNT: credentials.account ?? undefined,
+    },
+  };
+}
+
+export function gcloudConfigCopyInjection(
+  configCopy: GcloudConfigCopy,
+  options: GcloudConfigCopyInjectionOptions = {},
+): GcloudConfigCopyInjection {
+  if (configCopy.files.length === 0) {
+    throw new Error("Cannot copy empty gcloud config file set");
+  }
+
+  const env: NonNullable<ExecOptions["env"]> = {};
+  const command = [
+    "set -e",
+    'export HOME="${HOME:-/root}"',
+    `config_dir=${shellPathExpression(options.configDir, DEFAULT_GCLOUD_CONFIG_DIR)}`,
+    'command -v gcloud >/dev/null 2>&1 || { echo "gcloud CLI is not installed" >&2; exit 1; }',
+    'rm -rf "$config_dir"',
+    'mkdir -p "$config_dir"',
+    "umask 077",
+  ];
+
+  configCopy.files.forEach((file, index) => {
+    assertSafeRelativePath(file.path);
+    const variable = `RIGKIT_GCLOUD_CLI_CONFIG_FILE_${index}`;
+    env[variable] = file.contentsBase64;
+    command.push(
+      `mkdir -p "$(dirname "$config_dir/${shellDoubleQuote(file.path)}")"`,
+      `printf '%s' "$${variable}" | base64 -d > "$config_dir/${shellDoubleQuote(file.path)}"`,
+      `chmod 600 "$config_dir/${shellDoubleQuote(file.path)}"`,
+    );
+  });
+  if (configCopy.account) {
+    env.RIGKIT_GCLOUD_CLI_ACCOUNT = configCopy.account;
+    command.push(
+      'export CLOUDSDK_CONFIG="$config_dir"',
+      'gcloud config set account "$RIGKIT_GCLOUD_CLI_ACCOUNT" >/dev/null',
+    );
+  }
+
+  return {
+    command: command.join("\n"),
+    env,
+  };
+}
+
+export function gcloudConfigCopyInjectionSteps(
+  configCopy: GcloudConfigCopy,
+  options: GcloudConfigCopyInjectionOptions = {},
+): GcloudConfigCopyInjectionStep[] {
+  if (configCopy.files.length === 0) {
+    throw new Error("Cannot copy empty gcloud config file set");
+  }
+
+  const chunkSize = normalizeChunkSize(options.chunkSize);
+  const configDir = shellPathExpression(options.configDir, DEFAULT_GCLOUD_CONFIG_DIR);
+  const steps: GcloudConfigCopyInjectionStep[] = [
+    {
+      name: "prepare gcloud config copy",
+      command: [
+        "set -e",
+        'export HOME="${HOME:-/root}"',
+        `config_dir=${configDir}`,
+        'command -v gcloud >/dev/null 2>&1 || { echo "gcloud CLI is not installed" >&2; exit 1; }',
+        'rm -rf "$config_dir"',
+        'mkdir -p "$config_dir"',
+      ].join("\n"),
+      env: {},
+    },
+  ];
+
+  configCopy.files.forEach((file, index) => {
+    assertSafeRelativePath(file.path);
+    const chunks = splitBase64(file.contentsBase64, chunkSize);
+    chunks.forEach((chunk, chunkIndex) => {
+      steps.push({
+        name: `copy gcloud config file ${file.path} ${chunkIndex + 1}/${chunks.length}`,
+        command: [
+          "set -e",
+          'export HOME="${HOME:-/root}"',
+          `config_dir=${configDir}`,
+          "umask 077",
+          `mkdir -p "$(dirname "$config_dir/${shellDoubleQuote(file.path)}")"`,
+          chunkIndex === 0 ? `: > "$config_dir/${shellDoubleQuote(file.path)}"` : "",
+          `printf '%s' "$RIGKIT_GCLOUD_CLI_CONFIG_FILE_CHUNK" | base64 -d >> "$config_dir/${shellDoubleQuote(file.path)}"`,
+          `chmod 600 "$config_dir/${shellDoubleQuote(file.path)}"`,
+        ].filter(Boolean).join("\n"),
+        env: {
+          RIGKIT_GCLOUD_CLI_CONFIG_FILE_CHUNK: chunk,
+        },
+      });
+    });
+  });
+  if (configCopy.account) {
+    steps.push({
+      name: "set copied gcloud account",
+      command: [
+        "set -e",
+        'export HOME="${HOME:-/root}"',
+        `config_dir=${configDir}`,
+        'export CLOUDSDK_CONFIG="$config_dir"',
+        'gcloud config set account "$RIGKIT_GCLOUD_CLI_ACCOUNT" >/dev/null',
+      ].join("\n"),
+      env: {
+        RIGKIT_GCLOUD_CLI_ACCOUNT: configCopy.account,
+      },
+    });
+  }
+
+  return steps;
+}
+
+export function gcloudAccessTokenFreshCommand(
+  options: GcloudAccessTokenInjectionOptions & { minExpiration?: DurationInput } = {},
+): string {
+  const minExpirationMs = parseDurationMs(options.minExpiration ?? 0);
+  return [
+    "set -e",
+    'export HOME="${HOME:-/root}"',
+    `expires_at_path=${shellPathExpression(options.expiresAtPath, DEFAULT_GCLOUD_ACCESS_TOKEN_EXPIRES_AT_PATH)}`,
+    'test -s "$expires_at_path"',
+    'expires_at_ms="$(cat "$expires_at_path")"',
+    'case "$expires_at_ms" in ""|*[!0-9]*) exit 1;; esac',
+    'now_ms="$(($(date +%s) * 1000))"',
+    `test "$expires_at_ms" -gt "$((now_ms + ${minExpirationMs}))"`,
+    "gcloud auth print-access-token >/dev/null 2>&1",
+  ].join("\n");
+}
+
+export function gcloudCopiedConfigReadyCommand(): string {
+  return [
+    "set -e",
+    'export HOME="${HOME:-/root}"',
+    'gcloud auth list --filter=status:ACTIVE --format="value(account)" | grep -q .',
+    "gcloud auth print-access-token >/dev/null 2>&1",
+  ].join("\n");
+}
+
+function shellPathExpression(path: string | undefined, defaultExpression: string): string {
+  return path ? shellQuote(path) : `"${defaultExpression}"`;
+}
+
+function shellQuote(value: string): string {
+  return `'${value.replaceAll("'", "'\\''")}'`;
+}
+
+function shellDoubleQuote(value: string): string {
+  return value.replaceAll("\\", "\\\\").replaceAll('"', '\\"').replaceAll("$", "\\$").replaceAll("`", "\\`");
+}
+
+function normalizeChunkSize(value: number | undefined): number {
+  const chunkSize = Math.floor(value ?? 16 * 1024);
+  if (!Number.isFinite(chunkSize) || chunkSize < 4) {
+    throw new Error(`Invalid gcloud config file chunk size ${JSON.stringify(value)}`);
+  }
+  return chunkSize - (chunkSize % 4);
+}
+
+function splitBase64(value: string, chunkSize: number): string[] {
+  const chunks: string[] = [];
+  for (let index = 0; index < value.length; index += chunkSize) {
+    chunks.push(value.slice(index, index + chunkSize));
+  }
+  return chunks.length > 0 ? chunks : [""];
+}
+
+function assertSafeRelativePath(path: string): void {
+  if (
+    !path ||
+    path.startsWith("/") ||
+    path.includes("\0") ||
+    path.includes("\n") ||
+    path.includes("\r") ||
+    path.split("/").some((part) => part === "" || part === "." || part === "..")
+  ) {
+    throw new Error(`Unsafe gcloud config file path ${JSON.stringify(path)}`);
+  }
+}

package/src/provider.test.ts

@@ -0,0 +1,151 @@
+import { describe, expect, test } from "bun:test";
+import { mkdirSync, mkdtempSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { createStateStore } from "@rigkit/engine";
+import { gcloudConfigCopyProviderPlugin } from "./index.ts";
+import {
+  GCLOUD_CONFIG_COPY_PROVIDER_ID,
+  assertLocalGcloudReady,
+  createGcloudConfigCopyController,
+  requiresLocalGcloudAuth,
+  type GcloudCommandRunner,
+} from "./provider.ts";
+import { createGcloudAuthStore } from "./store.ts";
+
+describe("local gcloud config copy provider", () => {
+  test("requires startup auth by default", async () => {
+    expect(requiresLocalGcloudAuth({})).toBe(true);
+    expect(requiresLocalGcloudAuth({ requireAuth: true })).toBe(true);
+
+    const projectDir = mkdtempSync(join(tmpdir(), "rigkit-gcloud-"));
+    const state = createStateStore({ projectDir });
+    await state.syncSchema();
+
+    await expect(
+      gcloudConfigCopyProviderPlugin.createProvider({
+        provider: {
+          providerId: GCLOUD_CONFIG_COPY_PROVIDER_ID,
+          config: { command: join(projectDir, "missing-gcloud") },
+        },
+        storage: state.providerStorage("gcloud.config.copy"),
+        hostStorage: state.providerStorage("gcloud.config.copy.host"),
+        local: { open: async () => {} },
+      }),
+    ).rejects.toThrow("Local gcloud CLI is required");
+  });
+
+  test("can skip startup auth explicitly", async () => {
+    expect(requiresLocalGcloudAuth({ requireAuth: false })).toBe(false);
+
+    const projectDir = mkdtempSync(join(tmpdir(), "rigkit-gcloud-"));
+    const state = createStateStore({ projectDir });
+    await state.syncSchema();
+
+    const controller = await gcloudConfigCopyProviderPlugin.createProvider({
+      provider: {
+        providerId: GCLOUD_CONFIG_COPY_PROVIDER_ID,
+        config: {
+          command: join(projectDir, "missing-gcloud"),
+          requireAuth: false,
+        },
+      },
+      storage: state.providerStorage("gcloud.config.copy"),
+      hostStorage: state.providerStorage("gcloud.config.copy.host"),
+      local: { open: async () => {} },
+    });
+
+    expect(controller.providerId).toBe(GCLOUD_CONFIG_COPY_PROVIDER_ID);
+  });
+
+  test("fails startup when local gcloud is missing", async () => {
+    const runner: GcloudCommandRunner = async () => ({
+      stdout: "",
+      stderr: "command not found: gcloud",
+      exitCode: 127,
+    });
+
+    await expect(assertLocalGcloudReady({}, runner)).rejects.toThrow("Local gcloud CLI is required");
+  });
+
+  test("fails startup when local gcloud is not authenticated", async () => {
+    const runner: GcloudCommandRunner = async (_command, args) => {
+      if (args[0] === "--version") return { stdout: "Google Cloud SDK", stderr: "", exitCode: 0 };
+      return { stdout: "", stderr: "You do not currently have an active account selected.", exitCode: 1 };
+    };
+
+    await expect(assertLocalGcloudReady({}, runner)).rejects.toThrow("not authenticated");
+  });
+
+  test("mints and stores a fresh local gcloud access token", async () => {
+    const projectDir = mkdtempSync(join(tmpdir(), "rigkit-gcloud-"));
+    const state = createStateStore({ projectDir });
+    await state.syncSchema();
+    const store = createGcloudAuthStore(state.providerStorage("gcloud.config.copy"));
+    const calls: string[][] = [];
+    const runner: GcloudCommandRunner = async (_command, args) => {
+      calls.push([...args]);
+      if (args[0] === "auth") return { stdout: "access-token\n", stderr: "", exitCode: 0 };
+      if (args[0] === "config") return { stdout: "dev@example.com\n", stderr: "", exitCode: 0 };
+      throw new Error(`unexpected command ${args.join(" ")}`);
+    };
+
+    const controller = createGcloudConfigCopyController({}, store, runner);
+    const runtime = await controller.runtime({} as never);
+    const credentials = await runtime.freshAccessToken();
+
+    expect(credentials.accessToken).toBe("access-token");
+    expect(credentials.account).toBe("dev@example.com");
+    expect(credentials.tokenType).toBe("Bearer");
+    expect(Date.parse(credentials.expiresAt)).toBeGreaterThan(Date.now());
+    expect(store.getCredentials()?.accessToken).toBe("access-token");
+    expect(calls).toEqual([
+      ["auth", "print-access-token", "--quiet"],
+      ["config", "get-value", "account", "--quiet"],
+    ]);
+  });
+
+  test("copies local gcloud config files needed for auth", async () => {
+    const projectDir = mkdtempSync(join(tmpdir(), "rigkit-gcloud-"));
+    const configDir = join(projectDir, "gcloud");
+    mkdirSync(join(configDir, "configurations"), { recursive: true });
+    mkdirSync(join(configDir, "logs"), { recursive: true });
+    mkdirSync(join(configDir, "virtenv", "bin"), { recursive: true });
+    writeFileSync(join(configDir, "active_config"), "default\n");
+    writeFileSync(join(configDir, "access_tokens.db"), "access");
+    writeFileSync(join(configDir, "credentials.db"), "credentials");
+    writeFileSync(join(configDir, "default_configs.db"), "not copied config");
+    writeFileSync(join(configDir, "configurations", "config_default"), "[core]\naccount = dev@example.com\n");
+    writeFileSync(join(configDir, "logs", "ignored.log"), "noise");
+    writeFileSync(join(configDir, "virtenv", "bin", "python"), "not copied config");
+
+    const state = createStateStore({ projectDir });
+    await state.syncSchema();
+    const store = createGcloudAuthStore(state.providerStorage("gcloud.config.copy"));
+    const calls: string[][] = [];
+    const runner: GcloudCommandRunner = async (_command, args) => {
+      calls.push([...args]);
+      if (args[0] === "config") return { stdout: "dev@example.com\n", stderr: "", exitCode: 0 };
+      if (args[0] === "info") return { stdout: `${configDir}\n`, stderr: "", exitCode: 0 };
+      throw new Error(`unexpected command ${args.join(" ")}`);
+    };
+
+    const controller = createGcloudConfigCopyController({}, store, runner);
+    const runtime = await controller.runtime({} as never);
+    const configCopy = await runtime.configFiles();
+
+    expect(configCopy.account).toBe("dev@example.com");
+    expect(configCopy.sourceConfigDir).toBe(configDir);
+    expect(configCopy.files.map((file) => file.path)).toEqual([
+      "access_tokens.db",
+      "active_config",
+      "configurations/config_default",
+      "credentials.db",
+    ]);
+    expect(Buffer.from(configCopy.files[3]!.contentsBase64, "base64").toString()).toBe("credentials");
+    expect(calls).toEqual([
+      ["config", "get-value", "account", "--quiet"],
+      ["info", "--format=value(config.paths.global_config_dir)", "--quiet"],
+    ]);
+  });
+});

package/src/provider.ts

@@ -0,0 +1,312 @@
+import type { WorkflowProviderController } from "@rigkit/engine";
+import { homedir } from "node:os";
+import { join, relative, resolve, sep } from "node:path";
+import { lstat, readdir, readFile } from "node:fs/promises";
+import type { GcloudAccessCredentials, GcloudConfigCopy } from "./inject.ts";
+import {
+  DEFAULT_GCLOUD_CREDENTIAL_KEY,
+  normalizeScopes,
+  type GcloudStoredCredentials,
+} from "./store.ts";
+import type { createGcloudAuthStore } from "./store.ts";
+
+export const GCLOUD_CONFIG_COPY_PROVIDER_ID = "gcloud-config-copy";
+
+export const DEFAULT_GCLOUD_AUTH_SCOPES = [
+  "email",
+  "openid",
+  "https://www.googleapis.com/auth/cloud-platform",
+] as const;
+
+export const DEFAULT_GCLOUD_INSTALL_URL = "https://cloud.google.com/sdk/docs/install";
+
+const DEFAULT_ACCESS_TOKEN_LIFETIME_SECONDS = 55 * 60;
+
+export type GcloudConfigCopyConfig = {
+  command?: string;
+  requireAuth?: boolean;
+  key?: string;
+  account?: string;
+  scopes?: readonly string[];
+  installUrl?: string;
+  accessTokenLifetimeSeconds?: number;
+  configDir?: string;
+};
+
+export type GcloudFreshAccessTokenOptions = {
+  key?: string;
+  account?: string;
+  scopes?: readonly string[];
+};
+
+export type GcloudConfigFilesOptions = {
+  account?: string;
+  configDir?: string;
+};
+
+export type GcloudConfigCopyRuntime = {
+  freshAccessToken(options?: GcloudFreshAccessTokenOptions): Promise<GcloudAccessCredentials>;
+  configFiles(options?: GcloudConfigFilesOptions): Promise<GcloudConfigCopy>;
+};
+
+export type GcloudCommandResult = {
+  stdout: string;
+  stderr: string;
+  exitCode: number;
+};
+
+export type GcloudCommandRunner = (command: string, args: readonly string[]) => Promise<GcloudCommandResult>;
+
+type GcloudAuthStore = ReturnType<typeof createGcloudAuthStore>;
+
+export function createGcloudConfigCopyController(
+  config: GcloudConfigCopyConfig,
+  store: GcloudAuthStore,
+  runner: GcloudCommandRunner = runGcloudCommand,
+): WorkflowProviderController<GcloudConfigCopyRuntime> {
+  return {
+    providerId: GCLOUD_CONFIG_COPY_PROVIDER_ID,
+    runtime() {
+      return {
+        freshAccessToken: async (options = {}) =>
+          await freshAccessToken({
+            config,
+            store,
+            runner,
+            options,
+          }),
+        configFiles: async (options = {}) =>
+          await localGcloudConfigFiles({
+            config,
+            runner,
+            options,
+          }),
+      };
+    },
+  };
+}
+
+export async function assertLocalGcloudReady(
+  config: GcloudConfigCopyConfig,
+  runner: GcloudCommandRunner = runGcloudCommand,
+): Promise<void> {
+  const command = config.command ?? "gcloud";
+  const version = await runner(command, ["--version"]);
+  if (version.exitCode !== 0) {
+    throw new Error(
+      [
+        `Local gcloud CLI is required for this workflow, but ${JSON.stringify(command)} could not be run.`,
+        `Install it from ${config.installUrl ?? DEFAULT_GCLOUD_INSTALL_URL}, then rerun Rigkit.`,
+        version.stderr || version.stdout,
+      ].filter(Boolean).join("\n"),
+    );
+  }
+
+  const token = await runner(command, authPrintAccessTokenArgs({ account: config.account }));
+  if (token.exitCode !== 0 || !token.stdout.trim()) {
+    throw new Error(
+      [
+        "Local gcloud is installed, but it is not authenticated.",
+        "Run `gcloud auth login`, then rerun Rigkit.",
+        token.stderr || token.stdout,
+      ].filter(Boolean).join("\n"),
+    );
+  }
+}
+
+export function requiresLocalGcloudAuth(config: GcloudConfigCopyConfig): boolean {
+  return config.requireAuth ?? true;
+}
+
+async function freshAccessToken(input: {
+  config: GcloudConfigCopyConfig;
+  store: GcloudAuthStore;
+  runner: GcloudCommandRunner;
+  options: GcloudFreshAccessTokenOptions;
+}): Promise<GcloudAccessCredentials> {
+  const command = input.config.command ?? "gcloud";
+  const account = input.options.account ?? input.config.account;
+  const token = await input.runner(command, authPrintAccessTokenArgs({ account }));
+  if (token.exitCode !== 0 || !token.stdout.trim()) {
+    throw new Error(
+      [
+        "Failed to mint a fresh gcloud access token from local gcloud.",
+        "Run `gcloud auth login`, then rerun Rigkit.",
+        token.stderr || token.stdout,
+      ].filter(Boolean).join("\n"),
+    );
+  }
+
+  const configuredAccount = account ?? await readConfiguredAccount(command, input.runner);
+  const lifetimeSeconds = input.config.accessTokenLifetimeSeconds ?? DEFAULT_ACCESS_TOKEN_LIFETIME_SECONDS;
+  const credentials = input.store.saveCredentials({
+    key: input.options.key ?? input.config.key ?? DEFAULT_GCLOUD_CREDENTIAL_KEY,
+    account: configuredAccount,
+    scopes: normalizeScopes(input.options.scopes ?? input.config.scopes ?? DEFAULT_GCLOUD_AUTH_SCOPES),
+    accessToken: token.stdout.trim(),
+    tokenType: "Bearer",
+    expiresAt: new Date(Date.now() + lifetimeSeconds * 1000).toISOString(),
+  });
+
+  return toAccessCredentials(credentials);
+}
+
+async function localGcloudConfigFiles(input: {
+  config: GcloudConfigCopyConfig;
+  runner: GcloudCommandRunner;
+  options: GcloudConfigFilesOptions;
+}): Promise<GcloudConfigCopy> {
+  const command = input.config.command ?? "gcloud";
+  const account = input.options.account ?? input.config.account ?? await readConfiguredAccount(command, input.runner);
+  const configDir = resolveGcloudConfigDir(
+    input.options.configDir ??
+    input.config.configDir ??
+    await readConfiguredGcloudConfigDir(command, input.runner),
+  );
+  const files = await readGcloudConfigFiles(configDir);
+  if (files.length === 0) {
+    throw new Error(`No copyable gcloud config files found in ${configDir}`);
+  }
+
+  return {
+    sourceConfigDir: configDir,
+    account,
+    files,
+  };
+}
+
+async function readConfiguredAccount(
+  command: string,
+  runner: GcloudCommandRunner,
+): Promise<string | undefined> {
+  const account = await runner(command, ["config", "get-value", "account", "--quiet"]);
+  if (account.exitCode !== 0) return undefined;
+  const value = account.stdout.trim();
+  return value && value !== "(unset)" ? value : undefined;
+}
+
+async function readConfiguredGcloudConfigDir(
+  command: string,
+  runner: GcloudCommandRunner,
+): Promise<string | undefined> {
+  const result = await runner(command, ["info", "--format=value(config.paths.global_config_dir)", "--quiet"]);
+  const value = result.stdout.trim();
+  return result.exitCode === 0 && value ? value : undefined;
+}
+
+async function readGcloudConfigFiles(configDir: string): Promise<GcloudConfigCopy["files"]> {
+  const root = resolve(configDir);
+  const files: GcloudConfigCopy["files"] = [];
+
+  async function visit(path: string): Promise<void> {
+    const entry = await lstat(path);
+    if (entry.isSymbolicLink()) return;
+    if (entry.isDirectory()) {
+      const name = path.split(sep).at(-1);
+      if (name && shouldSkipConfigDir(name)) return;
+      const children = await readdir(path);
+      await Promise.all(children.map((child) => visit(join(path, child))));
+      return;
+    }
+    if (!entry.isFile()) return;
+
+    const relativePath = relative(root, path).split(sep).join("/");
+    if (!isSafeRelativePath(relativePath)) return;
+    if (!shouldCopyConfigFile(relativePath)) return;
+
+    files.push({
+      path: relativePath,
+      contentsBase64: Buffer.from(await readFile(path)).toString("base64"),
+    });
+  }
+
+  await visit(root);
+  return files.sort((left, right) => left.path.localeCompare(right.path));
+}
+
+function resolveGcloudConfigDir(configDir: string | undefined): string {
+  if (configDir?.trim()) return resolve(expandHome(configDir.trim()));
+  if (process.env.CLOUDSDK_CONFIG?.trim()) return resolve(expandHome(process.env.CLOUDSDK_CONFIG.trim()));
+  return join(homedir(), ".config", "gcloud");
+}
+
+function expandHome(path: string): string {
+  if (path === "~") return homedir();
+  if (path.startsWith("~/")) return join(homedir(), path.slice(2));
+  return path;
+}
+
+function shouldSkipConfigDir(name: string): boolean {
+  return (
+    name === "logs" ||
+    name === "cache" ||
+    name === "virtenv" ||
+    name === ".install" ||
+    name === ".backup" ||
+    name === "__pycache__"
+  );
+}
+
+function shouldCopyConfigFile(path: string): boolean {
+  return (
+    path === "active_config" ||
+    path === "application_default_credentials.json" ||
+    path === "access_tokens.db" ||
+    path.startsWith("access_tokens.db-") ||
+    path === "credentials.db" ||
+    path.startsWith("credentials.db-") ||
+    path.startsWith("configurations/") ||
+    path.startsWith("legacy_credentials/")
+  );
+}
+
+function isSafeRelativePath(path: string): boolean {
+  return Boolean(
+    path &&
+    !path.startsWith("/") &&
+    !path.includes("\0") &&
+    !path.includes("\n") &&
+    !path.includes("\r") &&
+    path.split("/").every((part) => part && part !== "." && part !== "..")
+  );
+}
+
+function authPrintAccessTokenArgs(input: { account?: string }): string[] {
+  return [
+    "auth",
+    "print-access-token",
+    "--quiet",
+    ...(input.account ? ["--account", input.account] : []),
+  ];
+}
+
+async function runGcloudCommand(command: string, args: readonly string[]): Promise<GcloudCommandResult> {
+  try {
+    const proc = Bun.spawn([command, ...args], {
+      stdout: "pipe",
+      stderr: "pipe",
+    });
+    const [stdout, stderr, exitCode] = await Promise.all([
+      new Response(proc.stdout).text(),
+      new Response(proc.stderr).text(),
+      proc.exited,
+    ]);
+    return { stdout, stderr, exitCode };
+  } catch (error) {
+    return {
+      stdout: "",
+      stderr: error instanceof Error ? error.message : String(error),
+      exitCode: 127,
+    };
+  }
+}
+
+function toAccessCredentials(credentials: GcloudStoredCredentials): GcloudAccessCredentials {
+  return {
+    accessToken: credentials.accessToken,
+    tokenType: credentials.tokenType,
+    expiresAt: credentials.expiresAt,
+    account: credentials.account,
+    scopes: credentials.scopes,
+  };
+}

package/src/store.test.ts

@@ -0,0 +1,34 @@
+import { describe, expect, test } from "bun:test";
+import { mkdtempSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { createStateStore } from "@rigkit/engine";
+import { createGcloudAuthStore } from "./store.ts";
+
+describe("gcloud auth store", () => {
+  test("upserts local access token credentials", async () => {
+    const projectDir = mkdtempSync(join(tmpdir(), "rigkit-gcloud-"));
+    const state = createStateStore({ projectDir });
+    await state.syncSchema();
+    const store = createGcloudAuthStore(state.providerStorage("gcloud.config.copy"));
+
+    const first = store.saveCredentials({
+      account: "dev@example.com",
+      scopes: ["openid", "https://www.googleapis.com/auth/cloud-platform"],
+      accessToken: "access-1",
+      expiresAt: new Date(Date.now() + 60_000).toISOString(),
+    });
+
+    const second = store.saveCredentials({
+      scopes: ["https://www.googleapis.com/auth/cloud-platform", "openid"],
+      accessToken: "access-2",
+      expiresAt: new Date(Date.now() + 120_000).toISOString(),
+    });
+
+    expect(second.id).toBe(first.id);
+    expect(second.account).toBe("dev@example.com");
+    expect(second.accessToken).toBe("access-2");
+    expect(second.scopes).toEqual(["https://www.googleapis.com/auth/cloud-platform", "openid"]);
+    expect(store.getCredentials()?.accessToken).toBe("access-2");
+  });
+});

package/src/store.ts

@@ -0,0 +1,99 @@
+import type { ProviderStorage } from "@rigkit/engine";
+import type { JsonValue } from "@rigkit/sdk";
+
+export const DEFAULT_GCLOUD_CREDENTIAL_KEY = "default";
+
+export type GcloudStoredCredentials = {
+  id: string;
+  key: string;
+  account?: string | null;
+  scopes: string[];
+  accessToken: string;
+  tokenType: string;
+  expiresAt: string;
+  createdAt: string;
+  updatedAt: string;
+};
+
+export type GcloudCredentialsInput = {
+  key?: string;
+  account?: string | null;
+  scopes: string[];
+  accessToken: string;
+  tokenType?: string;
+  expiresAt: string;
+};
+
+export function createGcloudAuthStore(storage: ProviderStorage) {
+  return {
+    getCredentials(key = DEFAULT_GCLOUD_CREDENTIAL_KEY): GcloudStoredCredentials | undefined {
+      return parseCredentials(storage.get(credentialsKey(key))?.value);
+    },
+
+    saveCredentials(input: GcloudCredentialsInput): GcloudStoredCredentials {
+      const now = new Date().toISOString();
+      const key = input.key ?? DEFAULT_GCLOUD_CREDENTIAL_KEY;
+      const existing = this.getCredentials(key);
+      const credentials: GcloudStoredCredentials = {
+        id: existing?.id ?? crypto.randomUUID(),
+        key,
+        account: input.account ?? existing?.account ?? null,
+        scopes: normalizeScopes(input.scopes),
+        accessToken: input.accessToken,
+        tokenType: input.tokenType ?? "Bearer",
+        expiresAt: input.expiresAt,
+        createdAt: existing?.createdAt ?? now,
+        updatedAt: now,
+      };
+
+      storage.set(credentialsKey(key), credentials as unknown as JsonValue);
+      return credentials;
+    },
+  };
+}
+
+export function normalizeScopes(scopes: readonly string[]): string[] {
+  return [...new Set(scopes.map((scope) => scope.trim()).filter(Boolean))].sort();
+}
+
+function credentialsKey(key: string): string {
+  return `credentials:${key}`;
+}
+
+function parseCredentials(value: JsonValue | undefined): GcloudStoredCredentials | undefined {
+  if (!isRecord(value)) return undefined;
+  return {
+    id: requiredString(value, "id"),
+    key: requiredString(value, "key"),
+    account: optionalStringOrNull(value, "account"),
+    scopes: stringArray(value.scopes, "scopes"),
+    accessToken: requiredString(value, "accessToken"),
+    tokenType: requiredString(value, "tokenType"),
+    expiresAt: requiredString(value, "expiresAt"),
+    createdAt: requiredString(value, "createdAt"),
+    updatedAt: requiredString(value, "updatedAt"),
+  };
+}
+
+function requiredString(record: Record<string, JsonValue>, key: string): string {
+  const value = record[key];
+  if (typeof value !== "string" || value.trim() === "") {
+    throw new Error(`Invalid gcloud provider state: ${key} must be a non-empty string`);
+  }
+  return value;
+}
+
+function optionalStringOrNull(record: Record<string, JsonValue>, key: string): string | null | undefined {
+  const value = record[key];
+  if (value === undefined || value === null || typeof value === "string") return value;
+  throw new Error(`Invalid gcloud provider state: ${key} must be a string or null`);
+}
+
+function stringArray(value: JsonValue | undefined, key: string): string[] {
+  if (Array.isArray(value) && value.every((item) => typeof item === "string")) return value;
+  throw new Error(`Invalid gcloud provider state: ${key} must be a string array`);
+}
+
+function isRecord(value: unknown): value is Record<string, JsonValue> {
+  return Boolean(value && typeof value === "object" && !Array.isArray(value));
+}

package/src/version.ts

@@ -0,0 +1 @@
+export const RIGKIT_PROVIDER_GCLOUD_CLI_VERSION = "0.0.0-canary-20260518T014918-c5bc0c2";