gcp-job-runner 1.0.0-2 → 1.0.0

package/README.md

@@ -1,3 +1,61 @@
-# code-conventions
+# gcp-job-runner
 
-Formalize and sync code-conventions across repositories
+Define jobs with Zod schemas, run them locally or on Cloud Run.
+
+## Quick Look
+
+```typescript
+import { z } from "zod";
+import { defineJob } from "gcp-job-runner";
+
+export default defineJob({
+  description: "Count down and exit",
+  schema: z.object({
+    seconds: z.number().default(10).describe("Number of seconds to count down"),
+  }),
+  handler: async ({ seconds }) => {
+    for (let i = seconds; i > 0; i--) {
+      console.log(`${i}...`);
+      await new Promise((resolve) => setTimeout(resolve, 1000));
+    }
+    console.log("Done!");
+  },
+});
+```
+
+Run it locally:
+
+```bash
+job local run stag countdown --seconds 5
+```
+
+Run it on Cloud Run:
+
+```bash
+job cloud run stag countdown --seconds 5
+```
+
+Same code, same arguments, same secrets. The cloud command automatically builds a Docker image, pushes it to Artifact Registry, and streams logs back to your terminal. Images are cached by content hash — only source code changes trigger a rebuild.
+
+## Features
+
+- **Zod validation** — arguments are validated before your handler runs, with auto-generated `--help` for every job
+- **Interactive mode** — browse jobs and fill in arguments interactively with `--interactive`
+- **Cloud Run deployment** — no Terraform or manual GCP config needed, just `job cloud run`
+- **Smart caching** — a single Docker image contains all jobs; running different jobs or different arguments doesn't rebuild
+- **GCP Secret Manager** — secrets are loaded transparently for both local and cloud execution
+- **Multi-environment** — configure staging, production, etc. and switch with a single argument
+
+## Install
+
+```bash
+npm install gcp-job-runner
+```
+
+## Documentation
+
+Full documentation is available at [0x80.github.io/gcp-job-runner](https://0x80.github.io/gcp-job-runner/).
+
+## License
+
+MIT

package/dist/define-job.mjs

@@ -173,14 +173,11 @@ function getArrayElementType(schema) {
 */
 function getBaseType(schema) {
 	let def = schema._def;
-	/** Unwrap ZodEffects (refinements, transforms) */
-	while (getType(def) === "ZodEffects" && def.schema) def = def.schema._def;
-	/** Unwrap optional */
-	if (getType(def) === "optional" && def.innerType) def = def.innerType._def;
-	/** Unwrap default */
-	if (getType(def) === "default" && def.innerType) def = def.innerType._def;
-	/** Unwrap any remaining effects */
-	while (getType(def) === "ZodEffects" && def.schema) def = def.schema._def;
+	/** Unwrap optional/default/effects in any order until we reach a base type */
+	while ((getType(def) === "optional" || getType(def) === "default" || getType(def) === "ZodEffects") && (def.innerType || def.schema)) {
+		const inner = def.innerType ?? def.schema;
+		if (inner) def = inner._def;
+	}
 	switch (getType(def)) {
 		case "array":
 		case "ZodArray": return "array";

package/dist/define-job.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"define-job.mjs","names":[],"sources":["../src/define-job.ts"],"sourcesContent":["import { parseArgs } from \"node:util\";\nimport { consola } from \"consola\";\nimport type { ZodObject, ZodRawShape, ZodType } from \"zod\";\nimport { z } from \"zod\";\nimport {\n  formatZodError,\n  generateFullHelp,\n  schemaToParseArgsOptions,\n} from \"./help\";\nimport type { FlagAliases, JobFunction, JobOptions } from \"./types\";\n\n/** Internal Zod definition type for introspection */\ninterface ZodDef {\n  type?: string;\n  typeName?: string;\n  schema?: ZodType;\n  innerType?: ZodType;\n  element?: ZodType;\n}\n\n/**\n * Create a job with Zod schema validation.\n *\n * Returns a function with signature (argv, jobName) => Promise<void> that is\n * called by runJob(). The function:\n * - Parses flags from argv using Node's built-in `parseArgs`\n * - Handles --help (prints help and returns)\n * - Validates args against the Zod schema (strict mode, rejects unknown)\n * - Calls the handler with validated, typed args\n *\n * @example\n * ```typescript\n * const ArgsSchema = z.object({\n *   name: z.string().describe(\"Your name\"),\n *   verbose: z.boolean().optional().default(false),\n * });\n *\n * export default defineJob({\n *   schema: ArgsSchema,\n *   handler: async (args) => {\n *     console.log(`Hello, ${args.name}!`);\n *   },\n *   description: \"Greet someone\",\n * });\n * ```\n */\nexport function defineJob<T extends ZodRawShape = ZodRawShape>(\n  options: JobOptions<T>,\n): JobFunction {\n  const schema = options.schema ?? (z.object({}) as unknown as ZodObject<T>);\n  const { handler } = options;\n\n  const fn: JobFunction = async (\n    argv: string[],\n    jobName: string,\n    commandPrefix?: string,\n  ): Promise<void> => {\n    /** Parse args from argv */\n    const parsed = parseArgv(argv, schema, options.aliases);\n\n    const helpOptions = {\n      ...options,\n      name: jobName,\n      commandPrefix: commandPrefix ?? options.commandPrefix,\n    };\n\n    /** Handle --help */\n    if (parsed.help === true) {\n      const helpText = generateFullHelp(schema, helpOptions);\n      consola.box(helpText);\n      return;\n    }\n\n    /** Validate with strict mode (reject unknown fields) */\n    const strictSchema = schema.strict();\n    const result = strictSchema.safeParse(parsed);\n\n    if (!result.success) {\n      const errorText = formatZodError(result.error);\n      const helpText = generateFullHelp(schema, helpOptions);\n      consola.error(`${errorText}\\n\\n${helpText}`);\n      process.exit(1);\n    }\n\n    await handler(result.data);\n  };\n\n  /** Attach metadata for discovery and interactive mode */\n  fn.__metadata = {\n    description: options.description,\n    schema,\n  };\n\n  return fn;\n}\n\n/**\n * Convert kebab-case to camelCase.\n */\nfunction toCamelCase(str: string): string {\n  return str.replace(/-([a-z])/g, (_, letter: string) => letter.toUpperCase());\n}\n\n/**\n * Parse argv into a merged args object using Node's built-in `parseArgs`.\n * Supports both --args JSON format and individual flags.\n * Coerces values to match the schema types.\n */\nfunction parseArgv<T extends ZodRawShape>(\n  argv: string[],\n  schema: ZodObject<T>,\n  aliases?: FlagAliases,\n): Record<string, unknown> {\n  /** Extract --args JSON if present */\n  let jsonArgs: Record<string, unknown> = {};\n  let filteredArgv = argv;\n  const argsIndex = argv.findIndex((arg) => arg === \"--args\" || arg === \"-a\");\n\n  if (argsIndex !== -1) {\n    const argsValue = argv[argsIndex + 1];\n    if (argsValue?.trim().startsWith(\"{\")) {\n      try {\n        const parsed = JSON.parse(argsValue) as unknown;\n        if (\n          typeof parsed === \"object\" &&\n          parsed !== null &&\n          !Array.isArray(parsed)\n        ) {\n          jsonArgs = parsed as Record<string, unknown>;\n        }\n      } catch {\n        /** Ignore JSON parse errors */\n      }\n    }\n    /** Remove --args/-a and its value from argv before passing to parseArgs */\n    filteredArgv = [...argv.slice(0, argsIndex), ...argv.slice(argsIndex + 2)];\n  }\n\n  /** Build parseArgs options from schema and aliases */\n  const options = schemaToParseArgsOptions(schema, aliases);\n\n  /** Add built-in help option */\n  options.help = { type: \"boolean\", short: \"h\" };\n\n  /** Parse with strict: false to allow unknown flags (Zod handles rejection) */\n  const { values } = parseArgs({\n    args: filteredArgv,\n    options,\n    strict: false,\n    allowPositionals: true,\n  });\n\n  /** Build flag args, converting kebab-case to camelCase and resolving aliases */\n  const flagArgs: Record<string, unknown> = {};\n\n  for (const [key, value] of Object.entries(values)) {\n    if (value === undefined) continue;\n    const camelKey = toCamelCase(key);\n    const resolvedKey = aliases?.[camelKey] ?? camelKey;\n    flagArgs[resolvedKey] = value;\n  }\n\n  /** Merge: flags take precedence over JSON args */\n  const merged = { ...jsonArgs, ...flagArgs };\n\n  /** Coerce values to match schema types */\n  return coerceToSchema(merged, schema);\n}\n\n/**\n * Coerce parsed values to match schema types.\n * - Converts values to the expected type (string, number, boolean)\n * - Wraps single values in arrays if the schema expects an array\n */\nfunction coerceToSchema<T extends ZodRawShape>(\n  values: Record<string, unknown>,\n  schema: ZodObject<T>,\n): Record<string, unknown> {\n  const result: Record<string, unknown> = { ...values };\n  const shape = schema.shape;\n\n  for (const [key, value] of Object.entries(result)) {\n    const fieldSchema = shape[key] as ZodType | undefined;\n    if (!fieldSchema || value === undefined) continue;\n\n    const baseType = getBaseType(fieldSchema);\n\n    if (baseType === \"array\") {\n      const elementType = getArrayElementType(fieldSchema);\n      if (Array.isArray(value)) {\n        result[key] = value.map((v) => coerceValue(v, elementType));\n      } else {\n        result[key] = [coerceValue(value, elementType)];\n      }\n    } else if (baseType !== null) {\n      result[key] = coerceValue(value, baseType);\n    }\n  }\n\n  return result;\n}\n\n/**\n * Coerce a single value to the expected type.\n */\nfunction coerceValue(value: unknown, targetType: string | null): unknown {\n  if (value === undefined || value === null || targetType === null)\n    return value;\n\n  switch (targetType) {\n    case \"string\":\n      return `${value as string | number | boolean}`;\n    case \"number\":\n      return typeof value === \"number\" ? value : Number(value);\n    case \"boolean\":\n      if (typeof value === \"boolean\") return value;\n      if (value === \"true\") return true;\n      if (value === \"false\") return false;\n      return Boolean(value);\n    default:\n      return value;\n  }\n}\n\n/**\n * Get the element type of an array schema.\n */\nfunction getArrayElementType(schema: ZodType): string | null {\n  let def = schema._def as ZodDef;\n\n  /** Unwrap optional/default/effects to get to the array */\n  while (\n    (getType(def) === \"optional\" ||\n      getType(def) === \"default\" ||\n      getType(def) === \"ZodEffects\") &&\n    (def.innerType || def.schema)\n  ) {\n    const inner = def.innerType ?? def.schema;\n    if (inner) {\n      def = inner._def as ZodDef;\n    }\n  }\n\n  /** Get the element schema from the array */\n  const typeName = getType(def);\n  if ((typeName === \"array\" || typeName === \"ZodArray\") && def.element) {\n    return getBaseType(def.element);\n  }\n\n  return null;\n}\n\n/**\n * Get the base type of a Zod schema, unwrapping optional/default/effects\n * wrappers. Returns null if the type cannot be confidently determined.\n */\nfunction getBaseType(schema: ZodType): string | null {\n  let def = schema._def as ZodDef;\n\n  /** Unwrap ZodEffects (refinements, transforms) */\n  while (getType(def) === \"ZodEffects\" && def.schema) {\n    def = def.schema._def as ZodDef;\n  }\n\n  /** Unwrap optional */\n  if (getType(def) === \"optional\" && def.innerType) {\n    def = def.innerType._def as ZodDef;\n  }\n\n  /** Unwrap default */\n  if (getType(def) === \"default\" && def.innerType) {\n    def = def.innerType._def as ZodDef;\n  }\n\n  /** Unwrap any remaining effects */\n  while (getType(def) === \"ZodEffects\" && def.schema) {\n    def = def.schema._def as ZodDef;\n  }\n\n  const typeName = getType(def);\n  switch (typeName) {\n    case \"array\":\n    case \"ZodArray\":\n      return \"array\";\n    case \"number\":\n    case \"ZodNumber\":\n    case \"int\":\n    case \"ZodInt\":\n      return \"number\";\n    case \"boolean\":\n    case \"ZodBoolean\":\n      return \"boolean\";\n    case \"string\":\n    case \"ZodString\":\n      return \"string\";\n    default:\n      return null;\n  }\n}\n\n/**\n * Get type string from a Zod definition, handling both v3 and v4 formats.\n */\nfunction getType(def: ZodDef): string | undefined {\n  return def.type ?? def.typeName;\n}\n"],"mappings":"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"}
+{"version":3,"file":"define-job.mjs","names":[],"sources":["../src/define-job.ts"],"sourcesContent":["import { parseArgs } from \"node:util\";\nimport { consola } from \"consola\";\nimport type { ZodObject, ZodRawShape, ZodType } from \"zod\";\nimport { z } from \"zod\";\nimport {\n  formatZodError,\n  generateFullHelp,\n  schemaToParseArgsOptions,\n} from \"./help\";\nimport type { FlagAliases, JobFunction, JobOptions } from \"./types\";\n\n/** Internal Zod definition type for introspection */\ninterface ZodDef {\n  type?: string;\n  typeName?: string;\n  schema?: ZodType;\n  innerType?: ZodType;\n  element?: ZodType;\n}\n\n/**\n * Create a job with Zod schema validation.\n *\n * Returns a function with signature (argv, jobName) => Promise<void> that is\n * called by runJob(). The function:\n * - Parses flags from argv using Node's built-in `parseArgs`\n * - Handles --help (prints help and returns)\n * - Validates args against the Zod schema (strict mode, rejects unknown)\n * - Calls the handler with validated, typed args\n *\n * @example\n * ```typescript\n * const ArgsSchema = z.object({\n *   name: z.string().describe(\"Your name\"),\n *   verbose: z.boolean().optional().default(false),\n * });\n *\n * export default defineJob({\n *   schema: ArgsSchema,\n *   handler: async (args) => {\n *     console.log(`Hello, ${args.name}!`);\n *   },\n *   description: \"Greet someone\",\n * });\n * ```\n */\nexport function defineJob<T extends ZodRawShape = ZodRawShape>(\n  options: JobOptions<T>,\n): JobFunction {\n  const schema = options.schema ?? (z.object({}) as unknown as ZodObject<T>);\n  const { handler } = options;\n\n  const fn: JobFunction = async (\n    argv: string[],\n    jobName: string,\n    commandPrefix?: string,\n  ): Promise<void> => {\n    /** Parse args from argv */\n    const parsed = parseArgv(argv, schema, options.aliases);\n\n    const helpOptions = {\n      ...options,\n      name: jobName,\n      commandPrefix: commandPrefix ?? options.commandPrefix,\n    };\n\n    /** Handle --help */\n    if (parsed.help === true) {\n      const helpText = generateFullHelp(schema, helpOptions);\n      consola.box(helpText);\n      return;\n    }\n\n    /** Validate with strict mode (reject unknown fields) */\n    const strictSchema = schema.strict();\n    const result = strictSchema.safeParse(parsed);\n\n    if (!result.success) {\n      const errorText = formatZodError(result.error);\n      const helpText = generateFullHelp(schema, helpOptions);\n      consola.error(`${errorText}\\n\\n${helpText}`);\n      process.exit(1);\n    }\n\n    await handler(result.data);\n  };\n\n  /** Attach metadata for discovery and interactive mode */\n  fn.__metadata = {\n    description: options.description,\n    schema,\n  };\n\n  return fn;\n}\n\n/**\n * Convert kebab-case to camelCase.\n */\nfunction toCamelCase(str: string): string {\n  return str.replace(/-([a-z])/g, (_, letter: string) => letter.toUpperCase());\n}\n\n/**\n * Parse argv into a merged args object using Node's built-in `parseArgs`.\n * Supports both --args JSON format and individual flags.\n * Coerces values to match the schema types.\n */\nfunction parseArgv<T extends ZodRawShape>(\n  argv: string[],\n  schema: ZodObject<T>,\n  aliases?: FlagAliases,\n): Record<string, unknown> {\n  /** Extract --args JSON if present */\n  let jsonArgs: Record<string, unknown> = {};\n  let filteredArgv = argv;\n  const argsIndex = argv.findIndex((arg) => arg === \"--args\" || arg === \"-a\");\n\n  if (argsIndex !== -1) {\n    const argsValue = argv[argsIndex + 1];\n    if (argsValue?.trim().startsWith(\"{\")) {\n      try {\n        const parsed = JSON.parse(argsValue) as unknown;\n        if (\n          typeof parsed === \"object\" &&\n          parsed !== null &&\n          !Array.isArray(parsed)\n        ) {\n          jsonArgs = parsed as Record<string, unknown>;\n        }\n      } catch {\n        /** Ignore JSON parse errors */\n      }\n    }\n    /** Remove --args/-a and its value from argv before passing to parseArgs */\n    filteredArgv = [...argv.slice(0, argsIndex), ...argv.slice(argsIndex + 2)];\n  }\n\n  /** Build parseArgs options from schema and aliases */\n  const options = schemaToParseArgsOptions(schema, aliases);\n\n  /** Add built-in help option */\n  options.help = { type: \"boolean\", short: \"h\" };\n\n  /** Parse with strict: false to allow unknown flags (Zod handles rejection) */\n  const { values } = parseArgs({\n    args: filteredArgv,\n    options,\n    strict: false,\n    allowPositionals: true,\n  });\n\n  /** Build flag args, converting kebab-case to camelCase and resolving aliases */\n  const flagArgs: Record<string, unknown> = {};\n\n  for (const [key, value] of Object.entries(values)) {\n    if (value === undefined) continue;\n    const camelKey = toCamelCase(key);\n    const resolvedKey = aliases?.[camelKey] ?? camelKey;\n    flagArgs[resolvedKey] = value;\n  }\n\n  /** Merge: flags take precedence over JSON args */\n  const merged = { ...jsonArgs, ...flagArgs };\n\n  /** Coerce values to match schema types */\n  return coerceToSchema(merged, schema);\n}\n\n/**\n * Coerce parsed values to match schema types.\n * - Converts values to the expected type (string, number, boolean)\n * - Wraps single values in arrays if the schema expects an array\n */\nfunction coerceToSchema<T extends ZodRawShape>(\n  values: Record<string, unknown>,\n  schema: ZodObject<T>,\n): Record<string, unknown> {\n  const result: Record<string, unknown> = { ...values };\n  const shape = schema.shape;\n\n  for (const [key, value] of Object.entries(result)) {\n    const fieldSchema = shape[key] as ZodType | undefined;\n    if (!fieldSchema || value === undefined) continue;\n\n    const baseType = getBaseType(fieldSchema);\n\n    if (baseType === \"array\") {\n      const elementType = getArrayElementType(fieldSchema);\n      if (Array.isArray(value)) {\n        result[key] = value.map((v) => coerceValue(v, elementType));\n      } else {\n        result[key] = [coerceValue(value, elementType)];\n      }\n    } else if (baseType !== null) {\n      result[key] = coerceValue(value, baseType);\n    }\n  }\n\n  return result;\n}\n\n/**\n * Coerce a single value to the expected type.\n */\nfunction coerceValue(value: unknown, targetType: string | null): unknown {\n  if (value === undefined || value === null || targetType === null)\n    return value;\n\n  switch (targetType) {\n    case \"string\":\n      return `${value as string | number | boolean}`;\n    case \"number\":\n      return typeof value === \"number\" ? value : Number(value);\n    case \"boolean\":\n      if (typeof value === \"boolean\") return value;\n      if (value === \"true\") return true;\n      if (value === \"false\") return false;\n      return Boolean(value);\n    default:\n      return value;\n  }\n}\n\n/**\n * Get the element type of an array schema.\n */\nfunction getArrayElementType(schema: ZodType): string | null {\n  let def = schema._def as ZodDef;\n\n  /** Unwrap optional/default/effects to get to the array */\n  while (\n    (getType(def) === \"optional\" ||\n      getType(def) === \"default\" ||\n      getType(def) === \"ZodEffects\") &&\n    (def.innerType || def.schema)\n  ) {\n    const inner = def.innerType ?? def.schema;\n    if (inner) {\n      def = inner._def as ZodDef;\n    }\n  }\n\n  /** Get the element schema from the array */\n  const typeName = getType(def);\n  if ((typeName === \"array\" || typeName === \"ZodArray\") && def.element) {\n    return getBaseType(def.element);\n  }\n\n  return null;\n}\n\n/**\n * Get the base type of a Zod schema, unwrapping optional/default/effects\n * wrappers. Returns null if the type cannot be confidently determined.\n */\nfunction getBaseType(schema: ZodType): string | null {\n  let def = schema._def as ZodDef;\n\n  /** Unwrap optional/default/effects in any order until we reach a base type */\n  while (\n    (getType(def) === \"optional\" ||\n      getType(def) === \"default\" ||\n      getType(def) === \"ZodEffects\") &&\n    (def.innerType || def.schema)\n  ) {\n    const inner = def.innerType ?? def.schema;\n    if (inner) {\n      def = inner._def as ZodDef;\n    }\n  }\n\n  const typeName = getType(def);\n  switch (typeName) {\n    case \"array\":\n    case \"ZodArray\":\n      return \"array\";\n    case \"number\":\n    case \"ZodNumber\":\n    case \"int\":\n    case \"ZodInt\":\n      return \"number\";\n    case \"boolean\":\n    case \"ZodBoolean\":\n      return \"boolean\";\n    case \"string\":\n    case \"ZodString\":\n      return \"string\";\n    default:\n      return null;\n  }\n}\n\n/**\n * Get type string from a Zod definition, handling both v3 and v4 formats.\n */\nfunction getType(def: ZodDef): string | undefined {\n  return def.type ?? def.typeName;\n}\n"],"mappings":"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"}

package/package.json

@@ -1,8 +1,12 @@
 {
   "name": "gcp-job-runner",
-  "version": "1.0.0-2",
+  "version": "1.0.0",
   "description": "Trivially run the same jobs locally or in the cloud",
   "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/0x80/gcp-job-runner"
+  },
   "bin": {
     "job": "dist/cli.mjs"
   },
@@ -19,12 +23,28 @@
     "./run-cloud": "./dist/run-cloud.mjs",
     "./package.json": "./package.json"
   },
+  "scripts": {
+    "build": "tsdown",
+    "dev": "tsdown --watch",
+    "check-types": "tsc --noEmit",
+    "check-lint": "oxlint -c .oxlintrc.json --import-plugin",
+    "format": "oxfmt",
+    "check-format": "oxfmt --check",
+    "test": "vitest",
+    "test:integration": "vitest run --config vitest.integration.config.ts",
+    "coverage": "vitest run --coverage",
+    "clean": "del-cli dist *.tsbuildinfo",
+    "docs:dev": "vitepress dev docs",
+    "docs:build": "vitepress build docs",
+    "docs:preview": "vitepress preview docs",
+    "prepare": "husky && tsdown"
+  },
   "dependencies": {
     "@google-cloud/logging": "^11.2.0",
     "@google-cloud/secret-manager": "^6.1.1",
     "consola": "^3.4.0",
     "execa": "^9.6.1",
-    "isolate-package": "1.27.0-8",
+    "isolate-package": "1.27.0",
     "zod": "^4.3.6"
   },
   "devDependencies": {
@@ -37,6 +57,7 @@
     "oxlint": "^1.47.0",
     "tsdown": "^0.20.1",
     "typescript": "^5.9.3",
+    "vitepress": "^1.6.4",
     "vitest": "^4.0.18"
   },
   "lint-staged": {
@@ -51,15 +72,5 @@
   "engines": {
     "node": ">=22.0.0"
   },
-  "scripts": {
-    "build": "tsdown",
-    "dev": "tsdown --watch",
-    "check-types": "tsc --noEmit",
-    "check-lint": "oxlint -c .oxlintrc.json --import-plugin",
-    "format": "oxfmt",
-    "check-format": "oxfmt --check",
-    "test": "vitest",
-    "coverage": "vitest run --coverage",
-    "clean": "del-cli dist *.tsbuildinfo"
-  }
-}
+  "packageManager": "pnpm@10.22.0"
+}

package/src/cloud/isolation-pipeline.integration.test.ts

@@ -0,0 +1,199 @@
+import { existsSync, readFileSync } from "node:fs";
+import { cp, mkdir, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import process from "node:process";
+import { execa } from "execa";
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+
+const projectRoot = path.resolve(import.meta.dirname, "../..");
+
+/**
+ * Build a fixture package.json for gcp-job-runner by deriving it from the real
+ * one. Strips isolate-package (build-time only), devDependencies, and scripts.
+ */
+function buildFixturePackageJson(): Record<string, unknown> {
+  const real = JSON.parse(
+    readFileSync(path.join(projectRoot, "package.json"), "utf-8"),
+  ) as Record<string, unknown>;
+
+  const dependencies = { ...(real.dependencies as Record<string, string>) };
+  delete dependencies["isolate-package"];
+
+  return {
+    name: real.name,
+    version: real.version,
+    type: real.type,
+    files: real.files,
+    exports: real.exports,
+    dependencies,
+  };
+}
+
+describe("isolation pipeline", () => {
+  let workspaceRoot: string;
+  let serviceDirectory: string;
+  let isolateDirectory: string;
+
+  beforeAll(async () => {
+    /** Preconditions */
+    const { exitCode } = await execa("pnpm", ["--version"], {
+      reject: false,
+    });
+    expect(exitCode, "pnpm must be available").toBe(0);
+    expect(
+      existsSync(path.join(projectRoot, "dist")),
+      "dist/ must exist — run pnpm build first",
+    ).toBe(true);
+
+    /** Create temp pnpm workspace */
+    workspaceRoot = path.join(
+      tmpdir(),
+      `isolation-test-${Date.now()}-${Math.random().toString(36).slice(2)}`,
+    );
+
+    const runnerPackageDirectory = path.join(
+      workspaceRoot,
+      "packages/gcp-job-runner",
+    );
+    serviceDirectory = path.join(workspaceRoot, "packages/test-service");
+    isolateDirectory = path.join(serviceDirectory, "isolate");
+
+    await mkdir(runnerPackageDirectory, { recursive: true });
+    await mkdir(path.join(serviceDirectory, "dist/jobs"), { recursive: true });
+
+    /** Write workspace root config */
+    await writeFile(
+      path.join(workspaceRoot, "pnpm-workspace.yaml"),
+      'packages:\n  - "packages/*"\n',
+    );
+    await writeFile(
+      path.join(workspaceRoot, "package.json"),
+      JSON.stringify({ name: "test-workspace", private: true }, null, 2),
+    );
+
+    /** Write gcp-job-runner fixture package */
+    await writeFile(
+      path.join(runnerPackageDirectory, "package.json"),
+      JSON.stringify(buildFixturePackageJson(), null, 2),
+    );
+    await cp(
+      path.join(projectRoot, "dist"),
+      path.join(runnerPackageDirectory, "dist"),
+      { recursive: true },
+    );
+
+    /** Write test-service package */
+    await writeFile(
+      path.join(serviceDirectory, "package.json"),
+      JSON.stringify(
+        {
+          name: "test-service",
+          version: "0.0.0",
+          private: true,
+          type: "module",
+          files: ["dist"],
+          dependencies: {
+            "gcp-job-runner": "workspace:*",
+          },
+        },
+        null,
+        2,
+      ),
+    );
+
+    /** Write a minimal hello job */
+    await writeFile(
+      path.join(serviceDirectory, "dist/jobs/hello.mjs"),
+      [
+        'import { defineJob } from "gcp-job-runner";',
+        "export default defineJob({",
+        "  handler: async () => {",
+        '    console.log("hello from isolated job");',
+        "  },",
+        "});",
+      ].join("\n"),
+    );
+
+    /** Write isolate config for the test service */
+    await writeFile(
+      path.join(serviceDirectory, "isolate.config.json"),
+      JSON.stringify(
+        {
+          buildDirName: "dist",
+          includeDevDependencies: true,
+        },
+        null,
+        2,
+      ),
+    );
+
+    /** Install dependencies in the workspace */
+    await execa("pnpm", ["install"], { cwd: workspaceRoot });
+
+    /** Run isolation so all tests can assert on the output */
+    const { isolate } = await import("isolate-package");
+
+    const originalCwd = process.cwd();
+    try {
+      process.chdir(serviceDirectory);
+      await isolate({ buildDirName: "dist", includeDevDependencies: true });
+    } finally {
+      process.chdir(originalCwd);
+    }
+  }, 120_000);
+
+  afterAll(async () => {
+    if (workspaceRoot) {
+      await rm(workspaceRoot, { recursive: true, force: true });
+    }
+  });
+
+  it("isolation produces valid output", () => {
+    /** Verify isolate output structure */
+    expect(existsSync(path.join(isolateDirectory, "package.json"))).toBe(true);
+    expect(existsSync(path.join(isolateDirectory, "pnpm-lock.yaml"))).toBe(
+      true,
+    );
+    expect(existsSync(path.join(isolateDirectory, "pnpm-workspace.yaml"))).toBe(
+      true,
+    );
+
+    /** Build output should be copied */
+    expect(existsSync(path.join(isolateDirectory, "dist/jobs/hello.mjs"))).toBe(
+      true,
+    );
+
+    /** Workspace dependency should be packed */
+    expect(
+      existsSync(path.join(isolateDirectory, "packages/gcp-job-runner")),
+    ).toBe(true);
+  });
+
+  it("pnpm install --frozen-lockfile succeeds in isolate output", async () => {
+    const result = await execa("pnpm", ["install", "--frozen-lockfile"], {
+      cwd: isolateDirectory,
+      reject: false,
+    });
+
+    expect(result.exitCode, `pnpm install failed:\n${result.stderr}`).toBe(0);
+  }, 60_000);
+
+  it("job executes from isolated environment", async () => {
+    const result = await execa(
+      "node",
+      ["--input-type=module", "-e", "import 'gcp-job-runner/run-cloud'"],
+      {
+        cwd: isolateDirectory,
+        env: {
+          ...process.env,
+          JOB_ARGV: JSON.stringify(["hello"]),
+        },
+        reject: false,
+      },
+    );
+
+    expect(result.exitCode, `Job execution failed:\n${result.stderr}`).toBe(0);
+    expect(result.stdout).toContain("hello from isolated job");
+  }, 30_000);
+});

package/src/define-job.test.ts

@@ -210,6 +210,19 @@ describe("defineJob", () => {
     expect(handler).toHaveBeenCalledWith({ name: "test", verbose: true });
   });
 
+  it("coerces numbers through optional().default() wrappers", async () => {
+    const handler = vi.fn();
+    const job = defineJob({
+      schema: z.object({
+        limit: z.number().optional().default(10),
+      }),
+      handler,
+    });
+
+    await job(["--limit", "42"], "test-job");
+    expect(handler).toHaveBeenCalledWith({ limit: 42 });
+  });
+
   it("converts kebab-case flags to camelCase", async () => {
     const handler = vi.fn();
     const job = defineJob({

package/src/define-job.ts

@@ -257,24 +257,17 @@ function getArrayElementType(schema: ZodType): string | null {
 function getBaseType(schema: ZodType): string | null {
   let def = schema._def as ZodDef;
 
-  /** Unwrap ZodEffects (refinements, transforms) */
-  while (getType(def) === "ZodEffects" && def.schema) {
-    def = def.schema._def as ZodDef;
-  }
-
-  /** Unwrap optional */
-  if (getType(def) === "optional" && def.innerType) {
-    def = def.innerType._def as ZodDef;
-  }
-
-  /** Unwrap default */
-  if (getType(def) === "default" && def.innerType) {
-    def = def.innerType._def as ZodDef;
-  }
-
-  /** Unwrap any remaining effects */
-  while (getType(def) === "ZodEffects" && def.schema) {
-    def = def.schema._def as ZodDef;
+  /** Unwrap optional/default/effects in any order until we reach a base type */
+  while (
+    (getType(def) === "optional" ||
+      getType(def) === "default" ||
+      getType(def) === "ZodEffects") &&
+    (def.innerType || def.schema)
+  ) {
+    const inner = def.innerType ?? def.schema;
+    if (inner) {
+      def = inner._def as ZodDef;
+    }
   }
 
   const typeName = getType(def);