@reyemtech/stack-upgrade 0.4.0

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "@reyemtech/stack-upgrade",
+  "version": "0.4.0",
+  "description": "CLI to launch Stack Upgrade Agents via Docker or Kubernetes",
+  "type": "module",
+  "bin": {
+    "stack-upgrade": "src/index.js"
+  },
+  "files": [
+    "src/"
+  ],
+  "dependencies": {
+    "@clack/prompts": "^0.10",
+    "picocolors": "^1.1"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ReyemTech/stack-upgrade.git",
+    "directory": "cli"
+  },
+  "license": "MIT"
+}

package/src/config.js

@@ -0,0 +1,38 @@
+import { readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+const CONFIG_DIR = join(homedir(), '.stack-upgrade');
+const CONFIG_FILE = join(CONFIG_DIR, 'config.json');
+
+/**
+ * Load persisted config from ~/.stack-upgrade/config.json.
+ * @returns {Record<string, any>}
+ */
+export function loadConfig() {
+  try {
+    return JSON.parse(readFileSync(CONFIG_FILE, 'utf-8'));
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * Save config to ~/.stack-upgrade/config.json (merges with existing).
+ * @param {Record<string, any>} updates
+ */
+export function saveConfig(updates) {
+  const existing = loadConfig();
+  const merged = { ...existing, ...updates };
+  mkdirSync(CONFIG_DIR, { recursive: true });
+  writeFileSync(CONFIG_FILE, JSON.stringify(merged, null, 2) + '\n', 'utf-8');
+}
+
+/**
+ * Get a single config value.
+ * @param {string} key
+ * @returns {any}
+ */
+export function getConfig(key) {
+  return loadConfig()[key];
+}

package/src/credentials.js

@@ -0,0 +1,115 @@
+import { readFile } from 'node:fs/promises';
+import { execFileSync } from 'node:child_process';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import * as p from '@clack/prompts';
+import { getConfig, saveConfig } from './config.js';
+
+/**
+ * Auto-detect Claude credentials.
+ * Priority: saved config > credentials.json > env vars > prompt
+ * @param {{ promptIfMissing?: boolean }} options
+ * @returns {{ type: 'oauth' | 'apikey', value: string, source: string } | null}
+ */
+export async function detectClaudeCredentials({ promptIfMissing = true } = {}) {
+  // 1. Saved config (~/.stack-upgrade/config.json)
+  const saved = getConfig('claudeCredentials');
+  if (saved?.value) {
+    return {
+      type: saved.type,
+      value: saved.value,
+      source: '~/.stack-upgrade/config.json',
+    };
+  }
+
+  // 2. ~/.claude/.credentials.json
+  try {
+    const credPath = join(homedir(), '.claude', '.credentials.json');
+    const raw = await readFile(credPath, 'utf-8');
+    const creds = JSON.parse(raw);
+    const oauth = creds?.claudeAiOauth;
+    if (oauth?.accessToken && oauth?.expiresAt > Date.now()) {
+      return {
+        type: 'oauth',
+        value: oauth.accessToken,
+        source: '~/.claude/.credentials.json',
+      };
+    }
+  } catch {
+    // File doesn't exist or is invalid — continue
+  }
+
+  // 3. CLAUDE_CODE_OAUTH_TOKEN env var
+  if (process.env.CLAUDE_CODE_OAUTH_TOKEN) {
+    return {
+      type: 'oauth',
+      value: process.env.CLAUDE_CODE_OAUTH_TOKEN,
+      source: 'CLAUDE_CODE_OAUTH_TOKEN env var',
+    };
+  }
+
+  // 4. ANTHROPIC_API_KEY env var
+  if (process.env.ANTHROPIC_API_KEY) {
+    return {
+      type: 'apikey',
+      value: process.env.ANTHROPIC_API_KEY,
+      source: 'ANTHROPIC_API_KEY env var',
+    };
+  }
+
+  // 5. Prompt user (or return null if not allowed)
+  if (!promptIfMissing) return null;
+
+  const hasClaude = (() => {
+    try { execFileSync('which', ['claude'], { stdio: 'ignore' }); return true; } catch { return false; }
+  })();
+
+  const method = await p.select({
+    message: 'Claude credentials not found. How do you want to authenticate?',
+    options: [
+      ...(hasClaude ? [{ value: 'setup-token', label: 'Run claude setup-token (recommended)', hint: 'opens browser login' }] : []),
+      { value: 'oauth', label: 'Paste OAuth token manually' },
+      { value: 'apikey', label: 'Paste API key (Anthropic)' },
+    ],
+  });
+  if (p.isCancel(method)) process.exit(0);
+
+  let result;
+
+  if (method === 'setup-token') {
+    p.log.info('Launching claude setup-token...');
+    try {
+      const output = execFileSync('claude', ['setup-token'], {
+        encoding: 'utf-8',
+        stdio: ['inherit', 'pipe', 'inherit'],
+      });
+
+      const match = output.match(/\b(sk-ant-oat\S+)/);
+      if (match) {
+        p.log.success('Token captured from setup-token');
+        result = { type: 'oauth', value: match[1], source: 'claude setup-token' };
+      }
+    } catch {
+      // fall through
+    }
+
+    if (!result) {
+      p.log.warn('Could not capture token automatically. Please paste it below.');
+      const token = await p.password({ message: 'Paste the OAuth token from above:' });
+      if (p.isCancel(token)) process.exit(0);
+      result = { type: 'oauth', value: token, source: 'claude setup-token (manual paste)' };
+    }
+  } else {
+    const value = await p.password({
+      message: method === 'oauth' ? 'Paste your OAuth token:' : 'Paste your API key:',
+    });
+    if (p.isCancel(value)) process.exit(0);
+    result = { type: method, value, source: 'manual input' };
+  }
+
+  // Save to config for next time
+  saveConfig({ claudeCredentials: { type: result.type, value: result.value } });
+  p.log.success('Credentials saved to ~/.stack-upgrade/config.json');
+
+  return result;
+}

package/src/docker.js

@@ -0,0 +1,108 @@
+import { execFileSync } from 'node:child_process';
+import { resolve } from 'node:path';
+import pc from 'picocolors';
+import * as p from '@clack/prompts';
+import { deriveName } from './pod-name.js';
+
+/**
+ * Check if Docker is available.
+ */
+export function hasDocker() {
+  try {
+    execFileSync('docker', ['info'], { stdio: 'ignore' });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Pull a Docker image.
+ * @param {string} image
+ */
+function pullImage(image) {
+  const pullSpinner = p.spinner();
+  pullSpinner.start(`Pulling ${image}...`);
+  try {
+    execFileSync('docker', ['pull', image], { stdio: 'ignore' });
+    pullSpinner.stop('Pulled latest image');
+  } catch {
+    pullSpinner.stop('Using cached image (pull failed)');
+  }
+}
+
+/**
+ * Launch a single Docker container for an upgrade.
+ * @returns {{ containerName: string, outputDir: string }}
+ */
+function startContainer({ repoUrl, targetVersion, push, suffix, ghToken, claudeCreds, image, stack, envKey }) {
+  const containerName = deriveName(repoUrl, stack, targetVersion, suffix);
+  const repoShort = repoUrl.replace(/.*[:/]/, '').replace(/\.git$/, '');
+  const outputDir = resolve(process.cwd(), 'output', repoShort);
+
+  const args = ['run', '--rm', '-d', '--name', containerName];
+
+  const env = {
+    REPO_URL: repoUrl,
+    [envKey]: targetVersion,
+    GIT_PUSH: push ? 'true' : 'false',
+    GH_TOKEN: ghToken,
+  };
+
+  if (suffix) env.BRANCH_SUFFIX = suffix;
+
+  if (claudeCreds.type === 'oauth') {
+    env.CLAUDE_CODE_OAUTH_TOKEN = claudeCreds.value;
+  } else {
+    env.ANTHROPIC_API_KEY = claudeCreds.value;
+  }
+
+  for (const [key, val] of Object.entries(env)) {
+    if (val) args.push('-e', `${key}=${val}`);
+  }
+
+  args.push('-v', `${outputDir}:/output`);
+  args.push(image);
+
+  execFileSync('docker', args, { stdio: 'ignore' });
+
+  return { containerName, outputDir };
+}
+
+/**
+ * Launch one or more upgrades as local Docker containers.
+ * @param {Array<object>} upgrades - array of upgrade configs
+ */
+export async function launchDocker(upgrades) {
+  // Pull unique images
+  const images = [...new Set(upgrades.map((u) => u.image))];
+  for (const image of images) {
+    pullImage(image);
+  }
+
+  // Start all containers
+  const launched = [];
+  const launchSpinner = p.spinner();
+  launchSpinner.start(`Starting ${upgrades.length} ${upgrades.length === 1 ? 'container' : 'containers'}...`);
+
+  try {
+    for (const upgrade of upgrades) {
+      const result = startContainer(upgrade);
+      launched.push({ ...upgrade, ...result });
+    }
+    launchSpinner.stop(`${launched.length} ${launched.length === 1 ? 'container' : 'containers'} started`);
+  } catch (err) {
+    launchSpinner.stop('Failed to start container');
+    p.log.error(err.message);
+    process.exit(1);
+  }
+
+  // Summary
+  const lines = launched.map((l) => [
+    `${pc.bold(l.containerName)}:`,
+    `  Logs:   docker logs -f ${l.containerName}`,
+    `  Output: ${l.outputDir}/`,
+  ].join('\n'));
+
+  p.note(lines.join('\n\n'), `${launched.length} ${launched.length === 1 ? 'upgrade' : 'upgrades'} running!`);
+}

package/src/github.js

@@ -0,0 +1,137 @@
+import { execFileSync } from 'node:child_process';
+import * as p from '@clack/prompts';
+import { detectStack } from './stacks.js';
+
+/**
+ * Get the GitHub auth token from `gh auth token`.
+ * @returns {string|null}
+ */
+export function getGhToken() {
+  try {
+    return execFileSync('gh', ['auth', 'token'], { encoding: 'utf-8' }).trim();
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Get the authenticated GitHub username.
+ * @returns {string|null}
+ */
+export function getGhUser() {
+  try {
+    const out = execFileSync(
+      'gh', ['api', '/user', '--jq', '.login'],
+      { encoding: 'utf-8' },
+    );
+    return out.trim();
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * List PHP repos the user has access to, detect stack + version.
+ * @returns {Promise<Array<{ name: string, url: string, stack: string, stackName: string, version: string }>>}
+ */
+export async function discoverRepos() {
+  // Fetch all PHP repos (owner + collaborator)
+  let repos;
+  try {
+    const out = execFileSync('gh', [
+      'api', '/user/repos',
+      '--paginate',
+      '--jq', '.[] | select(.language == "PHP") | .full_name',
+    ], { encoding: 'utf-8', maxBuffer: 10 * 1024 * 1024 });
+    repos = out.trim().split('\n').filter(Boolean);
+  } catch {
+    return [];
+  }
+
+  if (repos.length === 0) return [];
+
+  // Check each repo for known stacks (parallel, with concurrency limit)
+  const results = [];
+  const batchSize = 10;
+
+  for (let i = 0; i < repos.length; i += batchSize) {
+    const batch = repos.slice(i, i + batchSize);
+    const promises = batch.map(async (fullName) => {
+      try {
+        const out = execFileSync('gh', [
+          'api', `/repos/${fullName}/contents/composer.json`,
+          '--jq', '.content',
+        ], { encoding: 'utf-8' });
+
+        const content = Buffer.from(out.trim(), 'base64').toString('utf-8');
+        const composer = JSON.parse(content);
+        const detected = detectStack(composer);
+        if (!detected) return null;
+
+        return {
+          name: fullName,
+          url: `https://github.com/${fullName}.git`,
+          stack: detected.stack,
+          stackName: detected.stack.charAt(0).toUpperCase() + detected.stack.slice(1),
+          version: detected.version,
+        };
+      } catch {
+        return null;
+      }
+    });
+
+    const batchResults = await Promise.all(promises);
+    results.push(...batchResults.filter(Boolean));
+  }
+
+  return results;
+}
+
+/**
+ * Prompt user to select a repo or enter manually.
+ * @param {Array} repos
+ * @returns {Promise<{ name: string, url: string, stack: string, version: string }>}
+ */
+export async function selectRepo(repos) {
+  if (repos.length === 0) {
+    const url = await p.text({
+      message: 'Enter the repository URL:',
+      placeholder: 'https://github.com/org/repo.git',
+      validate: (v) => {
+        if (!v) return 'URL is required';
+        if (!v.includes('github.com')) return 'Must be a GitHub URL';
+      },
+    });
+    if (p.isCancel(url)) process.exit(0);
+
+    return { name: url.replace(/.*github\.com[:/]/, '').replace(/\.git$/, ''), url, stack: 'laravel', version: 'unknown' };
+  }
+
+  const options = repos.map((r) => ({
+    value: r,
+    label: r.name,
+    hint: `${r.stackName} ${r.version}`,
+  }));
+  options.push({ value: 'manual', label: 'Enter URL manually' });
+
+  const choice = await p.select({
+    message: 'Which repo do you want to upgrade?',
+    options,
+  });
+  if (p.isCancel(choice)) process.exit(0);
+
+  if (choice === 'manual') {
+    const url = await p.text({
+      message: 'Enter the repository URL:',
+      placeholder: 'https://github.com/org/repo.git',
+      validate: (v) => {
+        if (!v) return 'URL is required';
+      },
+    });
+    if (p.isCancel(url)) process.exit(0);
+
+    return { name: url.replace(/.*github\.com[:/]/, '').replace(/\.git$/, ''), url, stack: 'laravel', version: 'unknown' };
+  }
+
+  return choice;
+}

package/src/index.js

@@ -0,0 +1,144 @@
+#!/usr/bin/env node
+
+import * as p from '@clack/prompts';
+import pc from 'picocolors';
+import { getGhToken, getGhUser, discoverRepos, selectRepo } from './github.js';
+import { detectClaudeCredentials } from './credentials.js';
+import { askRunTarget, askTargetVersion, askPush, askSuffix, askAddAnother } from './prompts.js';
+import { hasDocker, launchDocker } from './docker.js';
+import { hasKubectl, launchKubernetes } from './kubectl.js';
+import { getConfig, saveConfig } from './config.js';
+import { getStack, STACKS } from './stacks.js';
+
+async function main() {
+  p.intro(pc.bold('Stack Upgrade Agent'));
+
+  // --- Prerequisites (auto-detectable) ---
+  const preSpinner = p.spinner();
+  preSpinner.start('Checking prerequisites...');
+
+  let ghToken = getGhToken();
+  if (!ghToken) ghToken = getConfig('ghToken') || null;
+  const ghUser = ghToken ? getGhUser() : null;
+  const claudeAutoDetect = await detectClaudeCredentials({ promptIfMissing: false });
+
+  if (ghUser) {
+    p.log.message(`${pc.green('\u2713')} GitHub CLI authenticated (${ghUser})`);
+  } else {
+    p.log.message(`${pc.yellow('!')} GitHub CLI not authenticated (will prompt for repo URL)`);
+  }
+
+  preSpinner.stop('Prerequisites checked');
+
+  // Claude credentials — prompt after spinner if not auto-detected
+  let claudeCreds;
+  if (claudeAutoDetect) {
+    p.log.message(`${pc.green('\u2713')} Claude credentials found (${claudeAutoDetect.source})`);
+    claudeCreds = claudeAutoDetect;
+  } else {
+    claudeCreds = await detectClaudeCredentials({ promptIfMissing: true });
+  }
+
+  // Save GH token if we got one from `gh auth`
+  if (ghToken && !getConfig('ghToken')) {
+    saveConfig({ ghToken });
+  }
+
+  // --- Run target ---
+  const dockerAvailable = hasDocker();
+  const kubectlAvailable = hasKubectl();
+  const savedTarget = getConfig('runTarget');
+
+  let target;
+  if (savedTarget && ((savedTarget === 'docker' && dockerAvailable) || (savedTarget === 'kubernetes' && kubectlAvailable))) {
+    target = savedTarget;
+    p.log.message(`${pc.green('\u2713')} Run target: ${savedTarget === 'docker' ? 'Local Docker' : 'Kubernetes'} (saved)`);
+  } else {
+    target = await askRunTarget({ hasDocker: dockerAvailable, hasKubectl: kubectlAvailable });
+    saveConfig({ runTarget: target });
+  }
+
+  // --- Repo discovery ---
+  let repos = [];
+  if (ghToken) {
+    const scanSpinner = p.spinner();
+    scanSpinner.start('Scanning your repos...');
+    repos = await discoverRepos();
+    scanSpinner.stop(`Found ${repos.length} ${repos.length === 1 ? 'repo' : 'repos'}`);
+  }
+
+  // --- Shared config ---
+  const push = await askPush();
+  const suffix = await askSuffix();
+
+  // --- Multi-upgrade loop ---
+  const upgrades = [];
+
+  // eslint-disable-next-line no-constant-condition
+  while (true) {
+    const repo = await selectRepo(repos);
+
+    // Resolve stack
+    const stackConfig = getStack(repo.stack);
+    if (!stackConfig) {
+      p.log.warn(`Unknown stack: ${repo.stack}. Defaulting to Laravel.`);
+    }
+    const stack = stackConfig || getStack('laravel');
+
+    const targetVersion = await askTargetVersion(stack.versionLabel);
+
+    const branchName = suffix
+      ? `${stack.branchPrefix}-${targetVersion}-${suffix}`
+      : `${stack.branchPrefix}-${targetVersion}`;
+
+    upgrades.push({
+      repoUrl: repo.url,
+      repoName: repo.name,
+      targetVersion,
+      push,
+      suffix: suffix || '',
+      ghToken,
+      claudeCreds,
+      image: stack.image,
+      stack: repo.stack,
+      stackName: stack.name,
+      envKey: stack.envKey,
+      branchName,
+    });
+
+    const another = await askAddAnother();
+    if (!another) break;
+  }
+
+  // --- Confirmation ---
+  const summaryLines = upgrades.map((u, i) =>
+    `  ${i + 1}. ${u.repoName}    ${u.stackName} → ${u.targetVersion}    ${target === 'docker' ? 'Local Docker' : 'Kubernetes'}`,
+  );
+
+  p.note([
+    ...summaryLines,
+    '',
+    `Push+PR: ${push ? 'yes' : 'no'}${suffix ? `    Suffix: ${suffix}` : ''}`,
+  ].join('\n'), `Ready to launch ${upgrades.length} ${upgrades.length === 1 ? 'upgrade' : 'upgrades'}`);
+
+  const confirm = await p.confirm({ message: 'Launch now?' });
+  if (p.isCancel(confirm) || !confirm) {
+    p.cancel('Aborted.');
+    process.exit(0);
+  }
+
+  // --- Launch ---
+  if (target === 'docker') {
+    await launchDocker(upgrades);
+  } else {
+    await launchKubernetes(upgrades);
+  }
+
+  p.outro('Done!');
+}
+
+main().catch((err) => {
+  if (err.message?.includes('User force closed')) process.exit(0);
+  p.cancel(err.message);
+  process.exit(1);
+});

package/src/kubectl.js

@@ -0,0 +1,260 @@
+import { execFileSync } from 'node:child_process';
+import pc from 'picocolors';
+import * as p from '@clack/prompts';
+import { deriveName } from './pod-name.js';
+
+const SECRET_NAME = 'upgrade-agent';
+
+/**
+ * Check if kubectl is available.
+ */
+export function hasKubectl() {
+  try {
+    execFileSync('kubectl', ['version', '--client'], { stdio: 'ignore' });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * List available k8s contexts.
+ * @returns {string[]}
+ */
+function listContexts() {
+  try {
+    const out = execFileSync('kubectl', ['config', 'get-contexts', '-o', 'name'], { encoding: 'utf-8' });
+    return out.trim().split('\n').filter(Boolean);
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Get current k8s context.
+ * @returns {string|null}
+ */
+function currentContext() {
+  try {
+    return execFileSync('kubectl', ['config', 'current-context'], { encoding: 'utf-8' }).trim();
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * List namespaces in the current context.
+ * @returns {string[]}
+ */
+function listNamespaces() {
+  try {
+    const out = execFileSync('kubectl', ['get', 'namespaces', '-o', 'jsonpath={.items[*].metadata.name}'], { encoding: 'utf-8' });
+    return out.trim().split(/\s+/).filter(Boolean);
+  } catch {
+    return ['default'];
+  }
+}
+
+/**
+ * Prompt for k8s context selection.
+ * @returns {Promise<string>}
+ */
+async function selectContext() {
+  const contexts = listContexts();
+  if (contexts.length === 0) {
+    p.cancel('No Kubernetes contexts found. Run kubectl config to set one up.');
+    process.exit(1);
+  }
+
+  if (contexts.length === 1) {
+    p.log.info(`Using context: ${contexts[0]}`);
+    return contexts[0];
+  }
+
+  const current = currentContext();
+  const options = contexts.map((c) => ({
+    value: c,
+    label: c,
+    hint: c === current ? 'current' : undefined,
+  }));
+
+  const choice = await p.select({
+    message: 'Kubernetes context',
+    options,
+  });
+  if (p.isCancel(choice)) process.exit(0);
+  return choice;
+}
+
+/**
+ * Prompt for namespace selection.
+ * @returns {Promise<string>}
+ */
+async function selectNamespace() {
+  const namespaces = listNamespaces();
+  const common = ['default', 'upgrades'];
+  const options = [];
+
+  for (const ns of common) {
+    if (namespaces.includes(ns)) {
+      options.push({ value: ns, label: ns });
+    }
+  }
+  options.push({ value: '__other', label: 'Other' });
+
+  const choice = await p.select({
+    message: 'Kubernetes namespace',
+    options,
+  });
+  if (p.isCancel(choice)) process.exit(0);
+
+  if (choice === '__other') {
+    const ns = await p.text({
+      message: 'Namespace name:',
+      validate: (v) => { if (!v) return 'Required'; },
+    });
+    if (p.isCancel(ns)) process.exit(0);
+    return ns;
+  }
+
+  return choice;
+}
+
+/**
+ * Ensure the upgrade-agent secret exists in the namespace.
+ */
+function ensureSecret(namespace, ghToken, claudeCreds) {
+  try {
+    execFileSync('kubectl', ['get', 'secret', SECRET_NAME, '-n', namespace], { stdio: 'ignore' });
+    p.log.info(`Secret "${SECRET_NAME}" exists in namespace "${namespace}"`);
+    return;
+  } catch {
+    // Secret doesn't exist — create it
+  }
+
+  p.log.info(`Creating secret "${SECRET_NAME}" in namespace "${namespace}"...`);
+
+  const args = [
+    'create', 'secret', 'generic', SECRET_NAME,
+    '-n', namespace,
+  ];
+
+  if (ghToken) {
+    args.push(`--from-literal=GH_TOKEN=${ghToken}`);
+  }
+
+  if (claudeCreds.type === 'oauth') {
+    args.push(`--from-literal=CLAUDE_CODE_OAUTH_TOKEN=${claudeCreds.value}`);
+  } else {
+    args.push(`--from-literal=ANTHROPIC_API_KEY=${claudeCreds.value}`);
+  }
+
+  execFileSync('kubectl', args, { stdio: 'ignore' });
+  p.log.success(`Secret created (Claude: ${claudeCreds.type}, GitHub: ${ghToken ? 'yes' : 'no'})`);
+}
+
+/**
+ * Launch a single pod for an upgrade.
+ */
+function startPod({ namespace, repoUrl, targetVersion, push, suffix, ghToken, claudeCreds, image, stack, envKey }) {
+  const podName = deriveName(repoUrl, stack, targetVersion, suffix);
+
+  const envVars = [
+    { name: 'REPO_URL', value: repoUrl },
+    { name: envKey, value: targetVersion },
+    { name: 'GIT_PUSH', value: push ? 'true' : 'false' },
+  ];
+
+  if (suffix) envVars.push({ name: 'BRANCH_SUFFIX', value: suffix });
+
+  // Secret-backed env vars
+  const secretEnvs = ['GH_TOKEN', 'CLAUDE_CODE_OAUTH_TOKEN', 'ANTHROPIC_API_KEY'];
+  for (const key of secretEnvs) {
+    envVars.push({
+      name: key,
+      valueFrom: { secretKeyRef: { name: SECRET_NAME, key, optional: true } },
+    });
+  }
+
+  const overrides = JSON.stringify({
+    spec: {
+      containers: [{
+        name: podName,
+        image,
+        env: envVars,
+        resources: {
+          requests: { cpu: '1', memory: '2Gi' },
+          limits: { cpu: '2', memory: '4Gi' },
+        },
+      }],
+      restartPolicy: 'Never',
+    },
+  });
+
+  execFileSync('kubectl', [
+    'run', podName,
+    `--namespace=${namespace}`,
+    `--image=${image}`,
+    '--restart=Never',
+    `--overrides=${overrides}`,
+  ], { stdio: 'ignore' });
+
+  return podName;
+}
+
+/**
+ * Launch one or more upgrades as Kubernetes pods.
+ * @param {Array<object>} upgrades - array of upgrade configs
+ */
+export async function launchKubernetes(upgrades) {
+  const context = await selectContext();
+  execFileSync('kubectl', ['config', 'use-context', context], { stdio: 'ignore' });
+
+  const namespace = await selectNamespace();
+
+  // Ensure secret (uses first upgrade's creds — they're shared)
+  const { ghToken, claudeCreds } = upgrades[0];
+  ensureSecret(namespace, ghToken, claudeCreds);
+
+  // Launch all pods
+  const launched = [];
+  const launchSpinner = p.spinner();
+  launchSpinner.start(`Launching ${upgrades.length} ${upgrades.length === 1 ? 'pod' : 'pods'}...`);
+
+  try {
+    for (const upgrade of upgrades) {
+      const podName = startPod({ ...upgrade, namespace });
+      launched.push({ ...upgrade, podName });
+    }
+    launchSpinner.stop(`${launched.length} ${launched.length === 1 ? 'pod' : 'pods'} created`);
+  } catch (err) {
+    launchSpinner.stop('Failed to launch pod');
+    p.log.error(err.message);
+    process.exit(1);
+  }
+
+  // Wait for pods to start
+  const waitSpinner = p.spinner();
+  waitSpinner.start('Waiting for pods to start...');
+  for (const { podName } of launched) {
+    try {
+      execFileSync('kubectl', [
+        'wait', '--for=jsonpath={.status.phase}=Running', `pod/${podName}`,
+        '-n', namespace, '--timeout=120s',
+      ], { stdio: 'ignore' });
+    } catch {
+      // May still be pulling image
+    }
+  }
+  waitSpinner.stop('Pods running');
+
+  // Summary
+  const lines = launched.map((l) => [
+    `${pc.bold(l.podName)}:`,
+    `  Logs:   kubectl logs -f ${l.podName} -n ${namespace}`,
+    `  Status: kubectl get pod ${l.podName} -n ${namespace}`,
+    `  Clean:  kubectl delete pod ${l.podName} -n ${namespace}`,
+  ].join('\n'));
+
+  p.note(lines.join('\n\n'), `${launched.length} ${launched.length === 1 ? 'pod' : 'pods'} launched!`);
+}

package/src/pod-name.js

@@ -0,0 +1,27 @@
+/**
+ * Derive a container/pod name from repo + stack + version + suffix.
+ * K8s constraints: lowercase, alphanumeric + dashes, max 63 chars.
+ * @param {string} repoUrl
+ * @param {string} stack - stack key (e.g., 'laravel')
+ * @param {string} targetVersion
+ * @param {string} [suffix]
+ */
+export function deriveName(repoUrl, stack, targetVersion, suffix) {
+  const repoShort = repoUrl
+    .replace(/.*[:/]/, '')
+    .replace(/\.git$/, '')
+    .toLowerCase();
+
+  const prefix = stack.charAt(0); // 'l' for laravel, 'r' for react, etc.
+  let name = `upgrade-${repoShort}-${prefix}${targetVersion}`;
+  if (suffix) {
+    name += `-${suffix}`;
+  }
+
+  return name
+    .toLowerCase()
+    .replace(/[^a-z0-9-]/g, '-')
+    .replace(/-+/g, '-')
+    .replace(/-$/, '')
+    .slice(0, 63);
+}

package/src/prompts.js

@@ -0,0 +1,85 @@
+import * as p from '@clack/prompts';
+
+/**
+ * Prompt for target version.
+ * @param {string} [label='Target version']
+ * @returns {Promise<string>}
+ */
+export async function askTargetVersion(label = 'Target version') {
+  const version = await p.text({
+    message: label,
+    placeholder: '12',
+    validate: (v) => {
+      if (!v) return 'Version is required';
+      if (!/^\d+$/.test(v)) return 'Enter just the major version number (e.g., 12)';
+    },
+  });
+  if (p.isCancel(version)) process.exit(0);
+  return version;
+}
+
+/**
+ * Prompt for push + PR preference.
+ * @returns {Promise<boolean>}
+ */
+export async function askPush() {
+  const push = await p.confirm({
+    message: 'Push branch and open PR on completion?',
+    initialValue: true,
+  });
+  if (p.isCancel(push)) process.exit(0);
+  return push;
+}
+
+/**
+ * Prompt for optional branch suffix.
+ * @returns {Promise<string>}
+ */
+export async function askSuffix() {
+  const today = new Date().toISOString().slice(0, 10);
+  const suffix = await p.text({
+    message: 'Branch suffix (optional)',
+    placeholder: today,
+    defaultValue: '',
+  });
+  if (p.isCancel(suffix)) process.exit(0);
+  return suffix;
+}
+
+/**
+ * Prompt for run target (Docker or Kubernetes).
+ * @param {{ hasDocker: boolean, hasKubectl: boolean }} available
+ * @returns {Promise<'docker' | 'kubernetes'>}
+ */
+export async function askRunTarget({ hasDocker, hasKubectl }) {
+  const options = [];
+  if (hasDocker) options.push({ value: 'docker', label: 'Local Docker' });
+  if (hasKubectl) options.push({ value: 'kubernetes', label: 'Kubernetes cluster' });
+
+  if (options.length === 0) {
+    p.cancel('Neither docker nor kubectl found in PATH. Install one to continue.');
+    process.exit(1);
+  }
+
+  if (options.length === 1) return options[0].value;
+
+  const target = await p.select({
+    message: 'Where should the upgrade run?',
+    options,
+  });
+  if (p.isCancel(target)) process.exit(0);
+  return target;
+}
+
+/**
+ * Prompt to add another upgrade to the queue.
+ * @returns {Promise<boolean>}
+ */
+export async function askAddAnother() {
+  const another = await p.confirm({
+    message: 'Add another upgrade?',
+    initialValue: false,
+  });
+  if (p.isCancel(another)) process.exit(0);
+  return another;
+}

package/src/stacks.js

@@ -0,0 +1,36 @@
+export const STACKS = {
+  laravel: {
+    name: 'Laravel',
+    image: 'ghcr.io/reyemtech/laravel-upgrade-agent:latest',
+    detect: (composer) => composer?.require?.['laravel/framework'],
+    versionLabel: 'Target Laravel version',
+    branchPrefix: 'upgrade/laravel',
+    envKey: 'TARGET_LARAVEL',
+  },
+};
+
+/**
+ * Look up a stack by key.
+ * @param {string} key
+ * @returns {object|null}
+ */
+export function getStack(key) {
+  return STACKS[key] || null;
+}
+
+/**
+ * Detect which stack a composer.json belongs to.
+ * @param {object} composer - parsed composer.json
+ * @returns {{ stack: string, version: string } | null}
+ */
+export function detectStack(composer) {
+  for (const [key, stack] of Object.entries(STACKS)) {
+    const dep = stack.detect(composer);
+    if (dep) {
+      const match = dep.match(/(\d+)/);
+      const version = match ? `${match[1]}.x` : dep;
+      return { stack: key, version };
+    }
+  }
+  return null;
+}