hub-launch 1.25.0 → 1.27.0

package/dist/commands/init.js

@@ -129,200 +129,62 @@ export function initCommand(program, _config) {
         }
     });
 }
-/**
- * Get the deployment startup script template based on auth provider
- */
-function getDeploymentStartupTemplate(authProvider) {
-    const header = `#!/usr/bin/env tsx
-/**
- * Deployment Startup Script
- * Automatically logs in to preview deployment before opening
- *
- * Context passed as first argument (JSON string):
- * {
- *   deploymentUrl: string;
- *   issueNumber?: number;
- *   prNumber?: number;
- *   prTitle?: string;
- *   prUrl?: string;
- * }
- */
-
-import { chromium } from "@playwright/test";
-
-interface HookContext {
-  deploymentUrl: string;
-  issueNumber?: number;
-  prNumber?: number;
-}
-
-async function main() {
-  const contextJson = process.argv[2];
-  if (!contextJson) {
-    console.error("Error: No context provided");
-    process.exit(1);
-  }
-
-  const context: HookContext = JSON.parse(contextJson);
-  console.log(\`🚀 Starting preview for: \${context.deploymentUrl}\`);
-
-  // Browser headless mode: Use env var or default to visible
-  const headless = process.env.CI === "true" || process.env.HEADLESS === "true";
-
-  const browser = await chromium.launch({
-    headless,
-    slowMo: headless ? 0 : 100,
-  });
-
-  const page = await browser.newPage();
-
-  try {
-    await page.goto(context.deploymentUrl);
-`;
-    if (authProvider === 'clerk') {
-        return (header +
-            `
-    // Wait for Clerk authentication widget
-    await page.waitForSelector('[data-clerk-id]', { timeout: 5000 });
-
-    // Click sign-in button
-    await page.click('button:has-text("Sign in")');
-
-    // Fill in credentials from environment
-    const email = process.env.TEST_USER_EMAIL;
-    const password = process.env.TEST_USER_PASSWORD;
-
-    if (!email || !password) {
-      throw new Error(
-        "Required: TEST_USER_EMAIL and TEST_USER_PASSWORD environment variables"
-      );
-    }
-
-    // Enter email
-    await page.fill('input[name="identifier"]', email);
-    await page.click('button:has-text("Continue")');
-
-    // Enter password
-    await page.fill('input[name="password"]', password);
-    await page.click('button:has-text("Continue")');
-
-    // Wait for successful login
-    await page.waitForURL(\`\${context.deploymentUrl}/**\`, {
-      timeout: 10000
-    });
-
-    console.log("✅ Successfully logged in with Clerk!");
-    console.log("Browser will remain open for testing.");
-
-    // Keep browser open - user closes when done
-    // Don't call browser.close()
-
-  } catch (error) {
-    console.error("❌ Login failed:", error);
-    await browser.close();
-    process.exit(1);
-  }
-}
-
-main().catch(console.error);
-`);
-    }
-    if (authProvider === 'auth0') {
-        return (header +
-            `
-    // Wait for Auth0 login form
-    await page.waitForSelector('[name="username"]', { timeout: 5000 });
-
-    // Fill in credentials from environment
-    const email = process.env.TEST_USER_EMAIL;
-    const password = process.env.TEST_USER_PASSWORD;
-
-    if (!email || !password) {
-      throw new Error(
-        "Required: TEST_USER_EMAIL and TEST_USER_PASSWORD environment variables"
-      );
-    }
-
-    // Auth0 login flow
-    await page.fill('input[name="username"]', email);
-    await page.fill('input[name="password"]', password);
-    await page.click('button[type="submit"]');
+const HOOKS_README_TEMPLATE = `# HubLaunch Hooks
 
-    // Wait for redirect back to app
-    await page.waitForURL(\`\${context.deploymentUrl}/**\`, {
-      timeout: 10000
-    });
+This directory contains project-specific hooks that extend HubLaunch functionality.
 
-    console.log("✅ Successfully logged in with Auth0!");
-    console.log("Browser will remain open for testing.");
+\`beforeLaunch.ts\` and \`afterMerge.ts\` are generated with a working local-only example already active, plus commented-out Slack and database-branch (Neon+Vercel) examples you can uncomment and adapt.
 
-  } catch (error) {
-    console.error("❌ Login failed:", error);
-    await browser.close();
-    process.exit(1);
-  }
-}
+## Available Hooks
 
-main().catch(console.error);
-`);
-    }
-    // Generic template (no auth or custom)
-    return (header +
-        `
-    // Add your custom preview initialization logic here
-    //
-    // Examples:
-    // - Authenticate to deployment
-    // - Seed test data via API
-    // - Configure browser state
-    // - Navigate to specific page
-
-    console.log("✅ Preview setup complete!");
-    console.log("Browser opened at:", context.deploymentUrl);
-
-    // Optionally close browser after delay
-    // await new Promise(resolve => setTimeout(resolve, 30000));
-    // await browser.close();
-
-  } catch (error) {
-    console.error("❌ Preview setup failed:", error);
-    await browser.close();
-    process.exit(1);
-  }
-}
+### \`beforeLaunch.ts\`
+Runs **before** \`hula launch\` sends its launch request, so a project can
+provision a freshly-created, per-launch resource (e.g. a database branch) and
+inject its connection string into the container.
+
+- On success it must print \`{"envVars": {"KEY": "value", ...}}\` to **stdout**.
+  Those values are merged into the launch request's \`envVars\`, taking
+  precedence over any \`.env\`-sourced values with the same key.
+- **A nonzero exit, or stdout that is not valid \`{"envVars": {...}}\` JSON,
+  aborts the launch** — no request is sent. (Launching against the wrong
+  resource, e.g. a shared database, is worse than not launching.)
+- **stderr streams live** to your terminal, so you can watch the hook's
+  progress (it may make several seconds of API calls).
+- Printing nothing, \`{}\`, or \`{"envVars": {}}\` is a valid no-op — the launch
+  proceeds with no injected variables.
+- The hook is responsible for its own **find-or-create idempotency**: a
+  kill-and-relaunch runs \`beforeLaunch\` again with the same context, so key
+  your resource off \`issueName\`/\`planPath\` and reuse an existing resource
+  rather than creating a duplicate.
 
-main().catch(console.error);
-`);
+**Context Provided**:
+\`\`\`typescript
+{
+  issueName: string;   // The launch's issue/plan name
+  planPath: string;    // Path to the plan being launched
 }
-const HOOKS_README_TEMPLATE = `# HubLaunch Hooks
+\`\`\`
 
-This directory contains project-specific hooks that extend HubLaunch functionality.
+---
 
-## Available Hooks
+### \`afterMerge.ts\`
+Runs **after** \`hula approve\` successfully merges a PR. Use it to clean up
+whatever a \`beforeLaunch\` hook provisioned (e.g. delete the per-launch
+database branch).
 
-### \`deploymentStartupScript.ts\`
-Runs before opening a preview deployment. Use for:
-- **Authentication** (Clerk, Auth0, custom login flows)
-- **Browser automation** (Playwright-based interactions)
-- **Test data seeding** (API calls to populate data)
-- **Environment setup** (configure local state)
+- **Best-effort**: a failure only logs a warning — it never fails the merge,
+  which has already completed by the time this hook runs.
 
 **Context Provided**:
 \`\`\`typescript
 {
-  deploymentUrl: string;    // Preview deployment URL
-  issueNumber?: number;     // Associated issue number
-  prNumber?: number;        // Associated PR number
-  prTitle?: string;         // PR title
-  prUrl?: string;          // PR URL
+  issueNumber: number;   // Associated issue number
+  prNumber: number;      // Merged PR number
+  prTitle: string;       // Merged PR title
+  branch: string;        // The merged PR's source branch
 }
 \`\`\`
 
-**Usage**:
-- Configured in \`.hublaunch/hublaunch.config.ts\`
-- Runs automatically when you run \`hula preview\`
-- Runs in **background** (non-blocking)
-
 ---
 
 ## Creating Custom Hooks
@@ -372,11 +234,8 @@ export const config = {
   // ... other config ...
 
   hooks: {
-    deploymentStartup: ".hublaunch/hooks/deploymentStartupScript.ts",
-    beforePreview: ".hublaunch/hooks/beforePreview.ts",  // optional
-    afterPreview: ".hublaunch/hooks/afterPreview.ts",    // optional
-    beforeMerge: ".hublaunch/hooks/beforeMerge.ts",      // optional
-    afterMerge: ".hublaunch/hooks/afterMerge.ts",        // optional
+    beforeLaunch: ".hublaunch/hooks/beforeLaunch.ts",    // optional — inject per-launch env vars
+    afterMerge: ".hublaunch/hooks/afterMerge.ts",        // optional — cleanup after merge
   },
 };
 \`\`\`
@@ -409,10 +268,10 @@ Run hook manually for testing:
 
 \`\`\`bash
 # Test with sample context
-tsx .hublaunch/hooks/deploymentStartupScript.ts '{"deploymentUrl":"https://example.com","prNumber":123}'
+tsx .hublaunch/hooks/beforeLaunch.ts '{"issueName":"my-feature","planPath":".hublaunch/plans/my-feature.md"}'
 
 # Enable debug mode
-DEBUG=true tsx .hublaunch/hooks/deploymentStartupScript.ts '{"deploymentUrl":"https://example.com"}'
+DEBUG=true tsx .hublaunch/hooks/beforeLaunch.ts '{"issueName":"my-feature","planPath":".hublaunch/plans/my-feature.md"}'
 \`\`\`
 
 ---
@@ -423,6 +282,182 @@ DEBUG=true tsx .hublaunch/hooks/deploymentStartupScript.ts '{"deploymentUrl":"ht
 - **Examples**: https://github.com/YizYah/hub-launch/tree/main/examples
 - **Support**: https://github.com/YizYah/hub-launch/issues
 `;
+const BEFORE_LAUNCH_HOOK_TEMPLATE = `#!/usr/bin/env tsx
+/**
+ * beforeLaunch hook — runs before \`hula launch\` sends its launch request.
+ * See ./README.md for the full stdout/stderr contract.
+ *
+ * Context: { issueName: string; planPath: string }
+ */
+
+interface BeforeLaunchContext {
+  issueName: string;
+  planPath: string;
+}
+
+async function main() {
+  const context: BeforeLaunchContext = JSON.parse(process.argv[2] ?? '{}');
+
+  // -----------------------------------------------------------------------
+  // ACTIVE EXAMPLE — runs by default. Local-only, no external services or
+  // credentials required. Demonstrates the {"envVars": {...}} stdout
+  // contract by injecting a LAUNCH_TIMESTAMP env var into the container.
+  // Remove this block once you add your own logic below.
+  // -----------------------------------------------------------------------
+  console.error(\`[beforeLaunch] Launching "\${context.issueName}"...\`);
+  const envVars: Record<string, string> = { LAUNCH_TIMESTAMP: new Date().toISOString() };
+  console.error(\`[beforeLaunch] Injecting LAUNCH_TIMESTAMP=\${envVars.LAUNCH_TIMESTAMP}\`);
+
+  // -----------------------------------------------------------------------
+  // EXAMPLE IDEA — Slack notification. Uncomment and set SLACK_WEBHOOK_URL
+  // to post a message when a launch starts.
+  // -----------------------------------------------------------------------
+  // const webhookUrl = process.env.SLACK_WEBHOOK_URL;
+  // if (webhookUrl) {
+  //   await fetch(webhookUrl, {
+  //     method: 'POST',
+  //     headers: { 'Content-Type': 'application/json' },
+  //     body: JSON.stringify({ text: \`🚀 Launching *\${context.issueName}*\` }),
+  //   });
+  //   console.error('[beforeLaunch] Slack notification sent.');
+  // }
+
+  // -----------------------------------------------------------------------
+  // EXAMPLE IDEA — per-launch database branch (Neon + Vercel). Provisions
+  // an isolated Postgres branch and injects its connection string, so each
+  // launch gets its own database instead of sharing one. Requires
+  // NEON_API_KEY, NEON_PROJECT_ID, VERCEL_TOKEN, VERCEL_PROJECT_ID.
+  // Find-or-create by name is required (this hook re-runs on a
+  // kill-and-relaunch with the same issueName) — never log the actual
+  // connection string or tokens.
+  // -----------------------------------------------------------------------
+  // const branchName = \`preview/\${context.issueName}\`;
+  // const branches = await fetch(
+  //   \`https://console.neon.tech/api/v2/projects/\${process.env.NEON_PROJECT_ID}/branches\`,
+  //   { headers: { Authorization: \`Bearer \${process.env.NEON_API_KEY}\` } },
+  // ).then((r) => r.json());
+  // // ...find branchName in branches.branches; if absent, POST to create one
+  // // off the default branch, then read the connection string back.
+  // // let connectionString = /* from the found or created branch */ '';
+  // await fetch(
+  //   \`https://api.vercel.com/v10/projects/\${process.env.VERCEL_PROJECT_ID}/env\`,
+  //   {
+  //     method: 'POST',
+  //     headers: {
+  //       Authorization: \`Bearer \${process.env.VERCEL_TOKEN}\`,
+  //       'Content-Type': 'application/json',
+  //     },
+  //     body: JSON.stringify({
+  //       key: 'DATABASE_URL',
+  //       value: /* connectionString from above */ '',
+  //       target: ['preview'],
+  //       gitBranch: context.issueName,
+  //       type: 'encrypted',
+  //     }),
+  //   },
+  // );
+  // envVars.DATABASE_URL = /* connectionString from above */ '';
+  // console.error('[beforeLaunch] Neon branch + Vercel env var provisioned.');
+
+  console.log(JSON.stringify({ envVars }));
+}
+
+main().catch((error) => {
+  console.error('[beforeLaunch] Hook failed:', error instanceof Error ? error.message : String(error));
+  process.exit(1);
+});
+`;
+const AFTER_MERGE_HOOK_TEMPLATE = `#!/usr/bin/env tsx
+/**
+ * afterMerge hook — runs after \`hula approve\` successfully merges a PR.
+ * Best-effort: a failure only logs a warning, it never fails the merge.
+ * See ./README.md for the full contract.
+ *
+ * Context: { issueNumber: number; prNumber: number; prTitle: string; branch: string }
+ */
+
+interface AfterMergeContext {
+  issueNumber: number;
+  prNumber: number;
+  prTitle: string;
+  branch: string;
+}
+
+async function main() {
+  const context: AfterMergeContext = JSON.parse(process.argv[2] ?? '{}');
+
+  // -----------------------------------------------------------------------
+  // ACTIVE EXAMPLE — runs by default. Local-only: just logs what merged.
+  // Remove this block once you add your own cleanup logic below.
+  // -----------------------------------------------------------------------
+  console.error(
+    \`[afterMerge] PR #\${context.prNumber} "\${context.prTitle}" merged (issue #\${context.issueNumber}, branch \${context.branch}).\`,
+  );
+
+  // -----------------------------------------------------------------------
+  // EXAMPLE IDEA — Slack notification. Uncomment and set SLACK_WEBHOOK_URL.
+  // -----------------------------------------------------------------------
+  // const webhookUrl = process.env.SLACK_WEBHOOK_URL;
+  // if (webhookUrl) {
+  //   await fetch(webhookUrl, {
+  //     method: 'POST',
+  //     headers: { 'Content-Type': 'application/json' },
+  //     body: JSON.stringify({ text: \`✅ Merged PR #\${context.prNumber}: \${context.prTitle}\` }),
+  //   });
+  //   console.error('[afterMerge] Slack notification sent.');
+  // }
+
+  // -----------------------------------------------------------------------
+  // EXAMPLE IDEA — tear down the per-launch database branch (Neon + Vercel)
+  // that a matching beforeLaunch.ts provisioned. Requires NEON_API_KEY,
+  // NEON_PROJECT_ID, VERCEL_TOKEN, VERCEL_PROJECT_ID. Treat "not found" as
+  // already-clean: log a warning and continue, don't throw — this hook may
+  // re-run, or the launch may have been killed before beforeLaunch ran.
+  // -----------------------------------------------------------------------
+  // const branchName = \`preview/\${context.branch}\`;
+  // // ...GET the Neon branch by name; if found, DELETE it; if not found,
+  // // console.error a warning and continue.
+  // // ...GET the Vercel branch-scoped DATABASE_URL env var by gitBranch; if
+  // // found, DELETE it; if not found, console.error a warning and continue.
+}
+
+main().catch((error) => {
+  console.error('[afterMerge] Hook failed (non-fatal):', error instanceof Error ? error.message : String(error));
+});
+`;
+// Hook keys always written as a real (uncommented) config line by init. Each
+// key gets its existing/configured value if the merged config already has one,
+// otherwise the default path — which points at the working example file that
+// generateHookTemplates() scaffolds. Order here is the order their lines are
+// written to the generated config. Deliberately not every HooksSchema key —
+// beforePreview, afterPreview, beforeMerge, and deploymentShutdown are valid
+// config keys but are not suggested by init (see the fallback loop below,
+// which still preserves any of them if a config already has one set).
+const HOOK_KEY_DEFAULTS = [
+    { key: 'beforeLaunch', defaultPath: '.hublaunch/hooks/beforeLaunch.ts' },
+    { key: 'afterMerge', defaultPath: '.hublaunch/hooks/afterMerge.ts' },
+];
+/**
+ * Build the `hooks: { ... }` config section. Each key in HOOK_KEY_DEFAULTS is
+ * always written as a real, uncommented line: the existing/merged config's
+ * value if it already has one (never overridden), otherwise the default path
+ * to the working example file that generateHookTemplates() scaffolds. Any
+ * other configured hook key (valid per HooksSchema, just not advertised) is
+ * still preserved as a real line — it is never dropped.
+ */
+export function buildHooksConfigSection(hooks) {
+    const advertisedKeys = new Set(HOOK_KEY_DEFAULTS.map((d) => d.key));
+    const lines = HOOK_KEY_DEFAULTS.map(({ key, defaultPath }) => {
+        const value = hooks?.[key] ?? defaultPath;
+        return `    ${key}: ${JSON.stringify(value)},`;
+    });
+    for (const [key, value] of Object.entries(hooks ?? {})) {
+        if (value && !advertisedKeys.has(key)) {
+            lines.push(`    ${key}: ${JSON.stringify(value)},`);
+        }
+    }
+    return `\n\n  // Lifecycle hooks\n  hooks: {\n${lines.join('\n')}\n  },`;
+}
 const ADAPTERS_README_TEMPLATE = `# HubLaunch Adapters
 
 This directory contains custom service adapters for extending HubLaunch functionality.
@@ -558,33 +593,29 @@ Templates are automatically detected and used by HubLaunch when creating issues
 \`\`\`
 `;
 /**
- * Generate hook templates based on authentication provider
+ * Generate hook directory structure with documentation
  */
-export async function generateHookTemplates(projectRoot, authProvider) {
+export async function generateHookTemplates(projectRoot) {
     const hooksDir = join(projectRoot, '.hublaunch/hooks');
     // Create hooks directory
     await mkdir(hooksDir, { recursive: true });
     logger.success(`Created directory: .hublaunch/hooks/`);
-    // Generate deploymentStartupScript.ts template based on auth provider
-    // Only create if auth provider is configured (not "none"). An existing script
-    // is never overwritten — the user may have customized it.
-    if (authProvider !== 'none') {
-        const startupScriptPath = join(hooksDir, 'deploymentStartupScript.ts');
-        if (!existsSync(startupScriptPath)) {
-            const template = getDeploymentStartupTemplate(authProvider);
-            await writeFile(startupScriptPath, template, 'utf-8');
-            logger.success(`Created: .hublaunch/hooks/deploymentStartupScript.ts`);
-        }
-        else {
-            logger.info('Keeping existing deploymentStartupScript.ts');
-        }
-    }
     // Generate README for hooks
     const readmePath = join(hooksDir, 'README.md');
     if (!existsSync(readmePath)) {
         await writeFile(readmePath, HOOKS_README_TEMPLATE, 'utf-8');
         logger.success(`Created: .hublaunch/hooks/README.md`);
     }
+    const beforeLaunchPath = join(hooksDir, 'beforeLaunch.ts');
+    if (!existsSync(beforeLaunchPath)) {
+        await writeFile(beforeLaunchPath, BEFORE_LAUNCH_HOOK_TEMPLATE, 'utf-8');
+        logger.success(`Created: .hublaunch/hooks/beforeLaunch.ts`);
+    }
+    const afterMergePath = join(hooksDir, 'afterMerge.ts');
+    if (!existsSync(afterMergePath)) {
+        await writeFile(afterMergePath, AFTER_MERGE_HOOK_TEMPLATE, 'utf-8');
+        logger.success(`Created: .hublaunch/hooks/afterMerge.ts`);
+    }
     logger.blank();
     logger.info('📖 See .hublaunch/hooks/README.md for hook documentation');
 }
@@ -1076,12 +1107,6 @@ export async function executeInit(options) {
             },
         };
     }
-    // Add hooks if configured
-    if (authProvider !== 'none') {
-        baseConfig.hooks = {
-            deploymentStartup: '.hublaunch/hooks/deploymentStartupScript.ts',
-        };
-    }
     // Merge with existing config (existing values take precedence)
     const finalConfig = existingConfig
         ? mergeConfigs(existingConfig, baseConfig)
@@ -1104,10 +1129,11 @@ export async function executeInit(options) {
     const cliVersion = getCliVersion();
     if (cliVersion)
         finalConfig.version = cliVersion;
-    // Generate hooks config section (omitted entirely when not configured)
-    const hooksConfigSection = finalConfig.hooks
-        ? `\n\n  // Lifecycle hooks\n  hooks: ${JSON.stringify(finalConfig.hooks, null, 2).replace(/\n/g, '\n  ')},`
-        : '';
+    // Generate hooks config section. Always emitted: every known hook key gets
+    // a line — a real, uncommented value when already configured (never
+    // overridden), otherwise a commented-out placeholder so the available hook
+    // points are discoverable without reading docs.
+    const hooksConfigSection = buildHooksConfigSection(finalConfig.hooks);
     // Generate services config section without credentials (omitted when not configured)
     const servicesConfigSection = finalConfig.services
         ? `\n\n  // Service configuration\n  services: ${JSON.stringify(finalConfig.services, null, 2).replace(/\n/g, '\n  ')},`
@@ -1289,10 +1315,10 @@ ${envVarsLine}${stepsLine}${buildPreservedSection(finalConfig)}
         logger.info(`ℹ️  .env file already exists at ${envPath} - skipping to preserve your existing configuration`);
         logger.info('   Add any required environment variables manually if needed');
     }
-    // Always generate hooks directory structure (with README and optionally script)
+    // Always generate hooks directory structure (with README)
     logger.blank();
     logger.info('Generating hooks directory structure...');
-    await generateHookTemplates(repoRoot, authProvider);
+    await generateHookTemplates(repoRoot);
     // Always generate adapters directory structure
     logger.blank();
     logger.info('Generating adapter directory structure...');
@@ -1362,9 +1388,6 @@ ${envVarsLine}${stepsLine}${buildPreservedSection(finalConfig)}
             logger.listItem('- TEST_USER_PASSWORD: Test user password', 2);
             logger.blank();
         }
-        if (authProvider !== 'none') {
-            logger.listItem('Customize .hublaunch/hooks/deploymentStartupScript.ts as needed', 1);
-        }
         if (showLoginHint) {
             logger.listItem("Run 'hula login' to authenticate.", 1);
         }