@postman-cse/onboarding-bootstrap 0.9.1

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@postman-cse/onboarding-bootstrap",
+  "version": "0.9.1",
+  "description": "Public open-alpha Postman bootstrap GitHub Action.",
+  "type": "module",
+  "main": "dist/index.cjs",
+  "bin": {
+    "postman-bootstrap": "dist/cli.cjs"
+  },
+  "scripts": {
+    "build": "npm run typecheck && rm -rf dist && esbuild src/index.ts --bundle --platform=node --target=node20 --format=cjs --outfile=dist/index.cjs && esbuild src/cli.ts --bundle --platform=node --target=node20 --format=cjs --outfile=dist/cli.cjs",
+    "check:dist": "npm run build && git diff --exit-code -- dist",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit -p tsconfig.json"
+  },
+  "keywords": [
+    "github-action",
+    "postman"
+  ],
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@actions/core": "^1.11.1",
+    "@actions/exec": "^1.1.1",
+    "@actions/io": "^1.1.3"
+  },
+  "overrides": {
+    "undici": "^6.24.0"
+  },
+  "devDependencies": {
+    "esbuild": "^0.27.3",
+    "@types/node": "^25.3.5",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.18",
+    "yaml": "^2.8.2"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/postman-cs/postman-bootstrap-action"
+  }
+}

package/src/cli.ts

@@ -0,0 +1,286 @@
+import { mkdir, writeFile } from 'node:fs/promises';
+import { execFile } from 'node:child_process';
+import path from 'node:path';
+import { promisify } from 'node:util';
+
+import * as io from '@actions/io';
+
+import {
+  createBootstrapDependencies,
+  resolveInputs,
+  type ResolvedInputs,
+  runBootstrap,
+  type BootstrapExecutionDependencies,
+  type ExecLike,
+  type PlannedOutputs
+} from './index.js';
+import { createSecretMasker } from './lib/secrets.js';
+
+interface CliConfig {
+  inputEnv: NodeJS.ProcessEnv;
+  resultJsonPath: string;
+  dotenvPath?: string;
+}
+
+export interface CliRuntime {
+  env?: NodeJS.ProcessEnv;
+  executeBootstrap?: typeof runBootstrap;
+  writeStdout?: (chunk: string) => void;
+}
+
+type ReporterCore = BootstrapExecutionDependencies['core'];
+
+export class ConsoleReporter implements ReporterCore {
+  public error(message: string): void {
+    console.error(message);
+  }
+
+  public async group<T>(name: string, fn: () => Promise<T>): Promise<T> {
+    console.error(`[group] ${name}`);
+    return await fn();
+  }
+
+  public info(message: string): void {
+    console.error(message);
+  }
+
+  public setOutput(_name: string, _value: string): void {
+  }
+
+  public warning(message: string): void {
+    console.error(`warning: ${message}`);
+  }
+}
+
+function readFlag(argv: string[], name: string): string | undefined {
+  const prefix = `--${name}=`;
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (arg === `--${name}`) {
+      return argv[index + 1];
+    }
+    if (arg?.startsWith(prefix)) {
+      return arg.slice(prefix.length);
+    }
+  }
+  return undefined;
+}
+
+function normalizeCliFlag(name: string): string {
+  return `INPUT_${name.replace(/-/g, '_').toUpperCase()}`;
+}
+
+const execFileAsync = promisify(execFile);
+
+function toCommandLabel(commandLine: string, args: string[], secretMasker: (value: string) => string): string {
+  const rendered = [commandLine, ...args].join(' ');
+  return secretMasker(rendered);
+}
+
+export function createCliExec(secretMasker: (value: string) => string): ExecLike {
+  const execCommand = async (
+    commandLine: string,
+    args: string[] = [],
+    options?: Parameters<ExecLike['exec']>[2]
+  ): Promise<number> => {
+    const output = await getExecOutput(commandLine, args, {
+      ...options,
+      ignoreReturnCode: true
+    });
+    if (output.exitCode !== 0 && !options?.ignoreReturnCode) {
+      throw new Error(`Command failed with exit code ${output.exitCode}: ${toCommandLabel(commandLine, args, secretMasker)}`);
+    }
+    return output.exitCode;
+  };
+
+  const getExecOutput = async (
+    commandLine: string,
+    args: string[] = [],
+    options?: Parameters<ExecLike['getExecOutput']>[2]
+  ): Promise<{ exitCode: number; stdout: string; stderr: string }> => {
+    const cwd = options?.cwd;
+    const env = options?.env ? { ...process.env, ...options.env } : process.env;
+    const commandLabel = toCommandLabel(commandLine, args, secretMasker);
+    process.stderr.write(`[command] ${commandLabel}\n`);
+
+    try {
+      const result = await execFileAsync(commandLine, args, {
+        cwd,
+        env,
+        encoding: 'utf8',
+        maxBuffer: 20 * 1024 * 1024,
+        windowsHide: true
+      });
+      const stdout = String(result.stdout ?? '');
+      const stderr = String(result.stderr ?? '');
+      if (stdout) {
+        process.stderr.write(secretMasker(stdout));
+      }
+      if (stderr) {
+        process.stderr.write(secretMasker(stderr));
+      }
+      return {
+        exitCode: 0,
+        stdout,
+        stderr
+      };
+    } catch (error) {
+      const execError = error as {
+        code?: number | string;
+        stdout?: string | Buffer;
+        stderr?: string | Buffer;
+        message?: string;
+      };
+      const stdout = String(execError.stdout ?? '');
+      const stderr = String(execError.stderr ?? '');
+      const fallbackMessage = execError.message ? `${execError.message}\n` : '';
+      if (stdout) {
+        process.stderr.write(secretMasker(stdout));
+      }
+      if (stderr) {
+        process.stderr.write(secretMasker(stderr));
+      } else if (fallbackMessage) {
+        process.stderr.write(secretMasker(fallbackMessage));
+      }
+      const numericCode =
+        typeof execError.code === 'number'
+          ? execError.code
+          : Number.parseInt(String(execError.code ?? '1'), 10) || 1;
+      if (!options?.ignoreReturnCode) {
+        throw new Error(`Command failed with exit code ${numericCode}: ${commandLabel}`);
+      }
+      return {
+        exitCode: numericCode,
+        stdout,
+        stderr
+      };
+    }
+  };
+
+  return {
+    exec: execCommand,
+    getExecOutput
+  };
+}
+
+export function createCliDependencies(
+  inputs: ResolvedInputs
+): BootstrapExecutionDependencies {
+  const secretMasker = createSecretMasker([
+    inputs.postmanApiKey,
+    inputs.postmanAccessToken,
+    inputs.githubToken,
+    inputs.ghFallbackToken
+  ]);
+  const cliExec = createCliExec(secretMasker);
+
+  return createBootstrapDependencies(inputs, {
+    core: new ConsoleReporter(),
+    exec: cliExec,
+    io,
+    specFetcher: fetch
+  });
+}
+
+export function parseCliArgs(argv: string[], env: NodeJS.ProcessEnv = process.env): CliConfig {
+  const inputNames = [
+    'project-name',
+    'spec-url',
+    'postman-api-key',
+    'postman-access-token',
+    'workspace-id',
+    'spec-id',
+    'baseline-collection-id',
+    'smoke-collection-id',
+    'contract-collection-id',
+    'domain',
+    'domain-code',
+    'requester-email',
+    'workspace-admin-user-ids',
+    'environments-json',
+    'system-env-map-json',
+    'governance-mapping-json',
+    'integration-backend',
+    'github-auth-mode',
+    'github-token',
+    'gh-fallback-token',
+    'team-id',
+    'repo-url'
+  ];
+
+  const inputEnv: NodeJS.ProcessEnv = { ...env };
+  for (const name of inputNames) {
+    const value = readFlag(argv, name);
+    if (value !== undefined) {
+      inputEnv[normalizeCliFlag(name)] = value;
+    }
+  }
+
+  return {
+    inputEnv,
+    resultJsonPath: readFlag(argv, 'result-json') ?? 'postman-bootstrap-result.json',
+    dotenvPath: readFlag(argv, 'dotenv-path')
+  };
+}
+
+export function toDotenv(outputs: PlannedOutputs): string {
+  return Object.entries(outputs)
+    .map(([key, value]) => [
+      `POSTMAN_BOOTSTRAP_${key.replace(/-/g, '_').toUpperCase()}`,
+      value
+    ] as const)
+    .map(([key, value]) => `${key}=${JSON.stringify(value)}`)
+    .join('\n');
+}
+
+async function writeOptionalFile(filePath: string | undefined, content: string): Promise<void> {
+  if (!filePath) {
+    return;
+  }
+  const workspaceRoot = path.resolve(process.cwd());
+  const resolved = path.resolve(workspaceRoot, filePath);
+  const relative = path.relative(workspaceRoot, resolved);
+  if (relative.startsWith('..') || path.isAbsolute(relative)) {
+    throw new Error(`Output path must stay within workspace: ${filePath}`);
+  }
+  await mkdir(path.dirname(resolved), { recursive: true });
+  await writeFile(resolved, content, 'utf8');
+}
+
+export async function runCli(
+  argv: string[] = process.argv.slice(2),
+  runtime: CliRuntime = {}
+): Promise<void> {
+  const env = runtime.env ?? process.env;
+  const config = parseCliArgs(argv, env);
+  const inputs = resolveInputs(config.inputEnv);
+  const dependencies = createCliDependencies(inputs);
+
+  if (!dependencies.github) {
+    dependencies.core.info('GitHub repository variable persistence disabled for this run');
+  }
+  if (inputs.domain && !dependencies.internalIntegration) {
+    dependencies.core.warning(
+      'Skipping governance assignment because postman-access-token is not configured'
+    );
+  }
+
+  const result = await (runtime.executeBootstrap ?? runBootstrap)(inputs, dependencies);
+
+  await writeOptionalFile(config.resultJsonPath, JSON.stringify(result, null, 2));
+  await writeOptionalFile(config.dotenvPath, toDotenv(result));
+
+  const writeStdout = runtime.writeStdout ?? ((chunk: string) => process.stdout.write(chunk));
+  writeStdout(`${JSON.stringify(result, null, 2)}\n`);
+}
+
+const currentModulePath = typeof __filename === 'string' ? __filename : '';
+const entrypoint = process.argv[1];
+
+if (entrypoint && currentModulePath === entrypoint) {
+  runCli().catch((error) => {
+    const message = error instanceof Error ? error.message : String(error);
+    process.stderr.write(`${message}\n`);
+    process.exitCode = 1;
+  });
+}

package/src/contracts.ts

@@ -0,0 +1,166 @@
+export interface ActionInputContract {
+  description: string;
+  required: boolean;
+  default?: string;
+  allowedValues?: string[];
+}
+
+export interface ActionOutputContract {
+  description: string;
+}
+
+export interface BetaActionContract {
+  name: string;
+  description: string;
+  inputs: Record<string, ActionInputContract>;
+  outputs: Record<string, ActionOutputContract>;
+  retainedBehavior: string[];
+  removedBehavior: string[];
+}
+
+export const openAlphaActionContract: BetaActionContract = {
+  name: 'postman-bootstrap-action',
+  description: 'Public open-alpha contract for bootstrapping Postman assets from a registry-backed spec.',
+  inputs: {
+
+    'workspace-id': {
+      description: 'Existing Postman workspace ID.',
+      required: false
+    },
+    'spec-id': {
+      description: 'Existing Postman spec ID.',
+      required: false
+    },
+    'baseline-collection-id': {
+      description: 'Existing baseline collection ID.',
+      required: false
+    },
+    'smoke-collection-id': {
+      description: 'Existing smoke collection ID.',
+      required: false
+    },
+    'contract-collection-id': {
+      description: 'Existing contract collection ID.',
+      required: false
+    },
+    'project-name': {
+      description: 'Service project name.',
+      required: true
+    },
+    domain: {
+      description: 'Business domain for the service.',
+      required: false
+    },
+    'domain-code': {
+      description: 'Short domain code used in workspace naming.',
+      required: false
+    },
+    'requester-email': {
+      description: 'Requester email for audit context.',
+      required: false
+    },
+    'workspace-admin-user-ids': {
+      description: 'Comma-separated workspace admin user ids.',
+      required: false
+    },
+    'spec-url': {
+      description: 'HTTPS URL to the OpenAPI document.',
+      required: true
+    },
+    'environments-json': {
+      description: 'JSON array of environment slugs to preserve in bootstrap outputs.',
+      required: false,
+      default: '["prod"]'
+    },
+    'system-env-map-json': {
+      description: 'JSON map of environment slug to system environment id.',
+      required: false,
+      default: '{}'
+    },
+    'governance-mapping-json': {
+      description: 'JSON map of business domain to governance group name.',
+      required: false,
+      default: '{}'
+    },
+    'postman-api-key': {
+      description: 'Postman API key used for bootstrap operations.',
+      required: true
+    },
+    'postman-access-token': {
+      description: 'Postman access token used for governance and workspace mutations.',
+      required: false
+    },
+    'github-token': {
+      description: 'GitHub token for repository variable persistence.',
+      required: false
+    },
+    'gh-fallback-token': {
+      description: 'Fallback token for repository variable APIs.',
+      required: false
+    },
+    'github-auth-mode': {
+      description: 'GitHub auth mode for repository variable APIs.',
+      required: false,
+      default: 'github_token_first'
+    },
+    'integration-backend': {
+      description: 'Integration backend for downstream workspace connectivity.',
+      required: false,
+      default: 'bifrost',
+      allowedValues: ['bifrost']
+    }
+  },
+  outputs: {
+    'workspace-id': {
+      description: 'Postman workspace ID.'
+    },
+    'workspace-url': {
+      description: 'Postman workspace URL.'
+    },
+    'workspace-name': {
+      description: 'Postman workspace name.'
+    },
+    'spec-id': {
+      description: 'Uploaded Postman spec ID.'
+    },
+    'baseline-collection-id': {
+      description: 'Baseline collection ID.'
+    },
+    'smoke-collection-id': {
+      description: 'Smoke collection ID.'
+    },
+    'contract-collection-id': {
+      description: 'Contract collection ID.'
+    },
+    'collections-json': {
+      description: 'JSON summary of generated collections.'
+    },
+    'lint-summary-json': {
+      description: 'JSON summary of lint errors and warnings.'
+    }
+  },
+  retainedBehavior: [
+    'workspace creation',
+    'governance group assignment',
+    'requester workspace invitation',
+    'workspace admin assignment',
+    'spec upload to Spec Hub',
+    'OpenAPI operation summary normalization before upload (missing or oversized summaries)',
+    'spec linting by UID',
+    'baseline, smoke, and contract collection generation',
+    'collection tagging',
+    'GitHub repository variable persistence for downstream sync steps',
+    'workspace, spec, and collection outputs'
+  ],
+  removedBehavior: [
+    'snake_case input and output names',
+    'step mode',
+    'hardcoded runtime deployment assumptions',
+    'aws, docker, and infra workflow concerns',
+    'runtime-coupled workflow tuning knobs',
+    'legacy placeholder inputs such as team-id'
+  ]
+};
+
+export const contractInputNames = Object.keys(openAlphaActionContract.inputs);
+export const contractOutputNames = Object.keys(openAlphaActionContract.outputs);