polen 0.9.1-next.1 → 0.10.0-next.10

package/src/lib/github-actions/pr-controller.ts

@@ -0,0 +1,183 @@
+import type { Context } from '@actions/github/lib/context.ts'
+import type { GitHub } from '@actions/github/lib/utils.ts'
+import { type Deployment, fetchPullRequestDeployments } from './lib/get-pr-deployments.ts'
+
+const createCommentMarker = (id: string) => `<!-- comment-id: ${id} -->`
+
+export interface CommentOptions {
+  /**
+   * Unique identifier for the comment. Used to find and update existing comments.
+   * If not provided, uses the current step name as the ID.
+   */
+  id?: string
+  /**
+   * Markdown content of the comment
+   */
+  content: string
+  /**
+   * Whether this comment is optional. If true, errors are logged but not thrown
+   * when not in a PR context. Defaults to false.
+   */
+  optional?: boolean
+}
+
+/**
+ * Create a PR controller. Returns a no-op controller when not in PR context.
+ */
+export function createPullRequestController(
+  github: InstanceType<typeof GitHub>,
+  context: Context,
+  defaultCommentId?: string,
+): PullRequestController {
+  // Check if this is a PR-related event
+  let prNumber: number | null = null
+
+  if (context.payload.pull_request?.number) {
+    // Direct PR events
+    prNumber = context.payload.pull_request.number
+  } else if (context.eventName === 'issue_comment' && context.payload.issue?.['pull_request']) {
+    // Issue comment on a PR (not on a regular issue)
+    prNumber = context.payload.issue.number
+  }
+
+  return new PullRequestController(github, context, prNumber, defaultCommentId)
+}
+
+// /**
+//  * Check if the current event is PR-related
+//  */
+// function isPREvent(context: Context): boolean {
+//   const prEvents = [
+//     'pull_request',
+//     'pull_request_review',
+//     'pull_request_review_comment',
+//     'pull_request_target',
+//     'issue_comment', // Can be on PRs too
+//   ]
+
+//   return prEvents.includes(context.eventName)
+//     || (context.eventName === 'issue_comment' && context.payload.issue?.['pull_request'])
+// }
+
+/**
+ * PR Controller for GitHub Actions
+ * Provides easy-to-use methods for interacting with pull requests
+ */
+export class PullRequestController {
+  public readonly isActive: boolean
+  public readonly number: number
+
+  constructor(
+    private github: InstanceType<typeof GitHub>,
+    private context: Context,
+    prNumber: number | null,
+    private defaultCommentId?: string,
+  ) {
+    this.isActive = prNumber !== null
+    this.number = prNumber || 0
+  }
+
+  async comment(options: CommentOptions): Promise<void> {
+    if (!this.isActive) {
+      if (options.optional) {
+        console.log('[skip] Not in a PR context, cannot create comment')
+        return
+      }
+      throw new Error('Not in a PR context, cannot create comment')
+    }
+
+    const { owner, repo } = this.context.repo
+
+    // Use provided ID or fall back to default
+    const commentId = options.id || this.defaultCommentId || 'default'
+
+    // Search for existing comment with the ID in the body
+    const commentMarker = createCommentMarker(commentId)
+    const body = `${options.content}\n\n${commentMarker}`
+
+    // Find existing comment
+    const { data: comments } = await this.github.rest.issues.listComments({
+      owner,
+      repo,
+      issue_number: this.number,
+      per_page: 100,
+    })
+
+    const existingComment = comments.find(comment => comment.body?.includes(commentMarker))
+
+    if (existingComment) {
+      // Update existing comment
+      await this.github.rest.issues.updateComment({
+        owner,
+        repo,
+        comment_id: existingComment.id,
+        body,
+      })
+    } else {
+      // Create new comment
+      await this.github.rest.issues.createComment({
+        owner,
+        repo,
+        issue_number: this.number,
+        body,
+      })
+    }
+  }
+
+  async fetchDeployments(): Promise<Deployment[]> {
+    if (!this.isActive) {
+      console.log('[skip] Not in a PR context, cannot fetch deployments')
+      return []
+    }
+    return await fetchPullRequestDeployments(
+      this.github,
+      this.context.repo.owner,
+      this.context.repo.repo,
+      this.number,
+    )
+  }
+
+  async deleteComment(id: string): Promise<void> {
+    if (!this.isActive) {
+      console.log('[skip] Not in a PR context, cannot delete comment')
+      return
+    }
+    const { owner, repo } = this.context.repo
+    const commentMarker = createCommentMarker(id)
+
+    // Find existing comment
+    const { data: comments } = await this.github.rest.issues.listComments({
+      owner,
+      repo,
+      issue_number: this.number,
+      per_page: 100,
+    })
+
+    const existingComment = comments.find(comment => comment.body?.includes(commentMarker))
+
+    if (existingComment) {
+      await this.github.rest.issues.deleteComment({
+        owner,
+        repo,
+        comment_id: existingComment.id,
+      })
+    }
+  }
+
+  // async getComments(): Promise<Array<{ id: number; body: string; created_at: string }>> {
+  //   const { owner, repo } = this.context.repo
+
+  //   const { data: comments } = await this.github.rest.issues.listComments({
+  //     owner,
+  //     repo,
+  //     issue_number: this.number,
+  //     per_page: 100,
+  //   })
+
+  //   return comments.map(comment => ({
+  //     id: comment.id,
+  //     body: comment.body || '',
+  //     created_at: comment.created_at,
+  //   }))
+  // }
+}

package/src/lib/github-actions/run-step-cli.ts

@@ -0,0 +1,84 @@
+#!/usr/bin/env node
+/**
+ * CLI for running workflow steps
+ *
+ * This is designed to be called from GitHub Actions workflows
+ * with our convention of steps being in .github/steps/<name>.ts
+ */
+
+import * as core from '@actions/core'
+import { runStep, runStepByName } from './runner.ts'
+
+async function main() {
+  const stepName = process.argv[2]
+  const workflowName = process.argv[3]
+  const pathOverride = process.argv[4]
+  const inputsJson = process.argv[5] || '{}'
+  const previousJson = process.argv[7] || '{}'
+
+  if (!stepName) {
+    core.setFailed('Missing required step name parameter')
+    core.error(
+      'Usage: run-step-cli <step-name> <workflow-name> [path-override] [inputs-json] [previous-json]',
+    )
+    core.error('This runner expects steps to be in .github/steps/<name>.ts')
+    process.exit(1)
+  }
+
+  // Module discovery is now handled by the runner
+
+  try {
+    core.info(`Running workflow step: ${stepName}`)
+
+    // Parse all inputs
+    const inputs = JSON.parse(inputsJson)
+    const previous = JSON.parse(previousJson)
+
+    // Debug logging
+    core.debug(`Parsed inputs: ${JSON.stringify(inputs)}`)
+    core.debug(`Parsed previous: ${JSON.stringify(previous)}`)
+
+    const mergedInputs = {
+      ...inputs,
+      previous,
+    }
+
+    core.debug(`Merged inputs: ${JSON.stringify(mergedInputs)}`)
+
+    // If path override is provided and not empty, use it directly
+    if (pathOverride && pathOverride !== '') {
+      await runStep(pathOverride, JSON.stringify(mergedInputs))
+    } else {
+      await runStepByName(stepName, workflowName, JSON.stringify(mergedInputs))
+    }
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error)
+    const stack = error instanceof Error ? error.stack : undefined
+
+    core.error(`Failed to run step ${stepName}: ${message}`)
+    if (stack) {
+      core.error(`Stack trace:`)
+      core.error(stack)
+    }
+
+    core.error(`Step name: ${stepName}`)
+    core.error(`Workflow name: ${workflowName || 'none'}`)
+    core.error(`Path override: ${pathOverride || 'none'}`)
+    core.error(`Inputs: ${inputsJson}`)
+    core.error(`Previous: ${previousJson}`)
+
+    // Check for common issues
+    if (error instanceof Error) {
+      if (error.message.includes('Cannot find module')) {
+        core.error(`Module import error - check that all dependencies are installed`)
+      } else if (error.message.includes('SyntaxError')) {
+        core.error(`Syntax error in step file - check TypeScript compilation`)
+      }
+    }
+
+    core.setFailed(`Step execution failed: ${message}`)
+    process.exit(1)
+  }
+}
+
+main()

package/src/lib/github-actions/runner.test.ts

@@ -0,0 +1,192 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { z } from 'zod/v4'
+import { runStep } from './runner.ts'
+import { createStep } from './step.ts'
+
+// Mock the discovery module
+vi.mock('./discovery.ts')
+
+// Mock @actions/core
+vi.mock('@actions/core', () => ({
+  startGroup: vi.fn(),
+  endGroup: vi.fn(),
+  debug: vi.fn(),
+  info: vi.fn(),
+  warning: vi.fn(),
+  error: vi.fn(),
+  setOutput: vi.fn(),
+  setFailed: vi.fn(),
+}))
+
+// Mock GitHub context
+vi.mock('@actions/github', () => ({
+  context: {
+    repo: { owner: 'test', repo: 'test' },
+    eventName: 'push',
+    payload: {},
+  },
+  getOctokit: vi.fn(() => ({
+    rest: {
+      issues: {
+        listComments: vi.fn().mockResolvedValue({ data: [] }),
+        createComment: vi.fn(),
+        updateComment: vi.fn(),
+        deleteComment: vi.fn(),
+      },
+    },
+  })),
+}))
+
+describe('runner', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+    process.env['GITHUB_TOKEN'] = 'test-token'
+  })
+
+  describe('runStep', () => {
+    it('validates inputs before running step', async () => {
+      const TestStep = createStep({
+        name: 'test-step',
+        description: 'Test step',
+        inputs: z.object({
+          required: z.string(),
+          number: z.number(),
+        }),
+        outputs: z.object({ result: z.string() }),
+        async run({ inputs }) {
+          return { result: `Got ${inputs.required} and ${inputs.number}` }
+        },
+      })
+
+      // Mock the module import
+      vi.doMock('./test-step.ts', () => ({
+        default: TestStep,
+      }))
+
+      await runStep(
+        './test-step.ts',
+        JSON.stringify({
+          required: 'value',
+          number: 42,
+        }),
+      )
+
+      const core = await import('@actions/core')
+      expect(core.startGroup).toHaveBeenCalledWith('test-step: Test step')
+      expect(core.setOutput).toHaveBeenCalledWith('result', 'Got value and 42')
+    })
+
+    it('handles validation errors', async () => {
+      const TestStep = createStep({
+        name: 'test-step',
+        description: 'Test step',
+        inputs: z.object({
+          required: z.string(),
+          number: z.number(),
+        }),
+        outputs: z.object({ result: z.string() }),
+        async run() {
+          return { result: 'ok' }
+        },
+      })
+
+      vi.doMock('./test-step.ts', () => ({
+        default: TestStep,
+      }))
+
+      const core = await import('@actions/core')
+
+      await expect(runStep(
+        './test-step.ts',
+        JSON.stringify({
+          required: 'value',
+          number: 'not-a-number', // Invalid type
+        }),
+      )).rejects.toThrow()
+
+      expect(core.error).toHaveBeenCalledWith(
+        expect.stringContaining('Validation error in step test-step'),
+      )
+    })
+
+    it('warns about unknown inputs', async () => {
+      const TestStep = createStep({
+        name: 'test-step',
+        description: 'Test step',
+        inputs: z.object({
+          known: z.string(),
+        }),
+        outputs: z.object({ result: z.string() }),
+        async run({ inputs }) {
+          return { result: inputs.known }
+        },
+      })
+
+      vi.doMock('./test-step.ts', () => ({
+        default: TestStep,
+      }))
+
+      await runStep(
+        './test-step.ts',
+        JSON.stringify({
+          known: 'value',
+          unknown1: 'should-warn',
+          unknown2: 'also-warn',
+        }),
+      )
+
+      const core = await import('@actions/core')
+      expect(core.warning).toHaveBeenCalledWith(
+        `Step 'test-step' received unknown inputs: unknown1, unknown2. These inputs will be ignored.`,
+      )
+    })
+
+    it('validates and exports outputs', async () => {
+      const TestStep = createStep({
+        name: 'test-step',
+        description: 'Test step',
+        inputs: z.object({}),
+        outputs: z.object({
+          status: z.string(),
+          count: z.number(),
+        }),
+        async run() {
+          return { status: 'complete', count: 5 }
+        },
+      })
+
+      vi.doMock('./test-step.ts', () => ({
+        default: TestStep,
+      }))
+
+      await runStep('./test-step.ts', '{}')
+
+      const core = await import('@actions/core')
+      expect(core.setOutput).toHaveBeenCalledWith('status', 'complete')
+      expect(core.setOutput).toHaveBeenCalledWith('count', '5')
+    })
+
+    it('warns when step returns outputs without schema', async () => {
+      const TestStep = createStep({
+        name: 'test-step',
+        description: 'Test step',
+        inputs: z.object({}),
+        // No outputs schema defined
+        async run() {
+          return { unexpected: 'output' } as any
+        },
+      })
+
+      vi.doMock('./test-step.ts', () => ({
+        default: TestStep,
+      }))
+
+      await runStep('./test-step.ts', '{}')
+
+      const core = await import('@actions/core')
+      expect(core.warning).toHaveBeenCalledWith(
+        expect.stringContaining('Step did not define outputs schema, but returned outputs'),
+      )
+    })
+  })
+})

package/src/lib/github-actions/runner.ts

@@ -0,0 +1,226 @@
+/**
+ * Runner utilities for executing workflow steps in GitHub Actions
+ */
+
+import * as core from '@actions/core'
+import { context, getOctokit } from '@actions/github'
+import { Obj, Path, Str } from '@wollybeard/kit'
+import { promises as fs } from 'node:fs'
+import { z } from 'zod/v4'
+import { $ } from 'zx'
+import { createGitController } from './git-controller.ts'
+import { createPullRequestController } from './pr-controller.ts'
+import { searchModule } from './search-module.ts'
+import type { Args, Step } from './step.ts'
+
+/**
+ * Create a workflow context with all necessary tools
+ */
+export function createArgs(stepName: string): Args {
+  const githubToken = process.env['GITHUB_TOKEN']
+  if (!githubToken) {
+    throw new Error('GITHUB_TOKEN environment variable is required')
+  }
+
+  const github = getOctokit(githubToken)
+  const pr = createPullRequestController(github, context, stepName)
+  const git = createGitController($)
+
+  return {
+    core,
+    github,
+    context,
+    $,
+    fs,
+    pr,
+    git,
+    inputs: {},
+  }
+}
+
+/**
+ * Run a workflow step by name using discovery
+ */
+export async function runStepByName(
+  stepName: string,
+  workflowName?: string,
+  inputsJson?: string,
+): Promise<void> {
+  // Discover the step module
+  const moduleLocation = searchModule({ stepName, workflowName })
+
+  if (!moduleLocation.found || !moduleLocation.path) {
+    core.error(`Step '${stepName}' not found`)
+    core.error(`Searched paths:`)
+    moduleLocation.searchedPaths.forEach(path => core.error(`  - ${path}`))
+    throw new Error(`Step '${stepName}' not found`)
+  }
+
+  core.debug(`Found step at: ${moduleLocation.path}`)
+  await runStep(moduleLocation.path, inputsJson)
+}
+
+/**
+ * Run a workflow step by importing it from a path
+ */
+export async function runStep(
+  stepPath: string,
+  inputsJson?: string,
+): Promise<void> {
+  const rawInputs = inputsJson ? JSON.parse(inputsJson) : {}
+
+  try {
+    // Dynamically import the step module
+    let stepModule: any
+
+    // Check if this is a test scenario (mocked module)
+    if (process.env['NODE_ENV'] === 'test' && stepPath.startsWith('./test-')) {
+      // For tests, use direct import path
+      stepModule = await import(stepPath)
+    } else {
+      // For real usage, convert to absolute path
+      const { resolve } = await import('node:path')
+      const { pathToFileURL } = await import('node:url')
+
+      // Resolve to absolute path and convert to file URL for proper ESM import
+      const absolutePath = resolve(process.cwd(), stepPath)
+      const importUrl = pathToFileURL(absolutePath).href
+
+      stepModule = await import(importUrl)
+    }
+
+    const step: Step = stepModule.default
+
+    if (!step || !step.run || !step.definition) {
+      throw new Error(`Module at ${stepPath} does not export a valid workflow step as default export`)
+    }
+
+    //
+    //
+    //
+    //
+    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ • Process Step Definition
+    // Validate Inputs
+    // Warning about excess properties
+    // Validate expected GitHub event versus actual
+    //
+    //
+
+    const { definition } = step
+    const stepName = definition.name ?? Path.parse(stepPath).name
+
+    // todo: allow step definition to opt-out of runtime validation
+    // Validate context if schema is provided
+    let validatedContext: any = context
+    if (definition.contextSchema) {
+      const contextValidation = definition.contextSchema.safeParse(context)
+      if (!contextValidation.success) {
+        const errorMessage = `Step '${stepName}' expects a different GitHub event context`
+        core.error(errorMessage)
+        core.error(`Expected context: ${JSON.stringify(contextValidation.error.issues, null, 2)}`)
+        core.error(`Actual event: ${context.eventName}`)
+
+        // For now, default to hard error. We can make this configurable later
+        throw new Error(errorMessage)
+      }
+      validatedContext = contextValidation.data
+    }
+
+    // Validate inputs
+    let inputs: Record<string, unknown> = {}
+    if (definition.inputsSchema) {
+      const parseResult = definition.inputsSchema.safeParse(rawInputs)
+      if (parseResult.success) {
+        inputs = parseResult.data
+      } else {
+        core.error(`Validation error in step ${stepName}: ${parseResult.error.message}`)
+        core.debug(`Validation issues: ${JSON.stringify(parseResult.error.issues, null, 2)}`)
+        core.debug(`Received data: ${JSON.stringify(rawInputs, null, 2)}`)
+        throw parseResult.error
+      }
+
+      // todo: let step define if it wants to silence this warning
+      // Check for excess properties if using object schema
+      if (definition.inputsSchema instanceof z.ZodObject && typeof rawInputs === 'object' && rawInputs !== null) {
+        const knownKeys = Object.keys(definition.inputsSchema.shape)
+        const providedKeys = Object.keys(rawInputs)
+        const unknownKeys = providedKeys.filter(key => !knownKeys.includes(key))
+
+        if (unknownKeys.length > 0) {
+          core.warning(
+            `Step '${stepName}' received unknown inputs: ${unknownKeys.join(', ')}. These inputs will be ignored.`,
+          )
+          core.debug(`Known inputs: ${knownKeys.join(', ')}`)
+          core.debug(`Provided inputs: ${JSON.stringify(rawInputs, null, 2)}`)
+        }
+      }
+    }
+
+    //
+    //
+    //
+    //
+    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ • Run Step
+    //
+    //
+
+    // Create context with validated inputs
+    const args = createArgs(stepName)
+    const stepArgs = {
+      ...args,
+      context: validatedContext,
+      inputs: inputs as any,
+    }
+
+    core.startGroup(`${definition.name}: ${definition.description}`)
+    core.debug(`Inputs: ${JSON.stringify(inputs)}`)
+
+    // Execute step
+    const outputRaw = await step.run(stepArgs)
+
+    //
+    //
+    //
+    //
+    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ • Handle Step Output
+    //
+    //
+
+    // Validate & Export outputs
+    // todo: allow step definition to opt-out of output validation
+    if (definition.outputsSchema) {
+      const outputs = definition.outputsSchema.parse(outputRaw)
+      const json = JSON.stringify(outputs)
+      core.setOutput('json', json)
+      for (const [key, value] of Obj.entries(outputs)) {
+        // todo: if key === json raise an error, it is a reserved name
+        core.setOutput(key, Str.is(value) ? value : JSON.stringify(value))
+      }
+    } else if (outputRaw !== undefined && outputRaw !== null) {
+      core.warning(
+        `Step did not define outputs schema, but returned outputs. These will not be validated or exported. Outputs were: ${
+          JSON.stringify(outputRaw)
+        }`,
+      )
+    }
+
+    core.endGroup()
+  } catch (error) {
+    core.endGroup()
+
+    // Log error details once (if not already logged)
+    if (error instanceof Error && !(error instanceof z.ZodError)) {
+      core.error(`Step failed: ${error.message}`)
+      core.debug(`Stack: ${error.stack}`)
+    } else if (!(error instanceof z.ZodError)) {
+      core.error(`Step failed: ${String(error)}`)
+    }
+
+    if (inputsJson) {
+      core.debug(`Step inputs: ${inputsJson}`)
+    }
+
+    // Re-throw to let CLI handle the error
+    throw error
+  }
+}