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

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

@@ -0,0 +1,149 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { z } from 'zod/v4'
+import { createStep } from './step.ts'
+
+describe('defineWorkflowStep', () => {
+  const mockCore = {
+    startGroup: vi.fn(),
+    endGroup: vi.fn(),
+    debug: vi.fn(),
+    info: vi.fn(),
+    warning: vi.fn(),
+    error: vi.fn(),
+    setOutput: vi.fn(),
+  } as any
+
+  const mockContext = {
+    core: mockCore,
+    github: {} as any,
+    context: {} as any,
+    $: {} as any,
+    fs: {} as any,
+  } as any
+
+  beforeEach(() => {
+    vi.clearAllMocks()
+  })
+
+  it('executes step with validated inputs', async () => {
+    const TestStep = createStep({
+      name: 'test-step',
+      description: 'Test step',
+      inputs: z.object({
+        required: z.string(),
+        optional: z.string().optional(),
+      }),
+      outputs: z.object({ result: z.string() }),
+      async run({ inputs }) {
+        return { result: `Got ${inputs.required}` }
+      },
+    })
+
+    // Create context with PR controller
+    const contextWithPR = {
+      ...mockContext,
+      pr: {
+        number: 0,
+        isActive: false,
+        comment: vi.fn(),
+        deleteComment: vi.fn(),
+        getComments: vi.fn(),
+      },
+    }
+
+    const result = await TestStep.run({
+      ...contextWithPR,
+      inputs: {
+        required: 'value',
+        optional: 'optional-value',
+      },
+    })
+
+    expect(result).toEqual({ result: 'Got value' })
+  })
+
+  it('validates output types', async () => {
+    const TestStep = createStep({
+      name: 'test-step',
+      description: 'Test step',
+      inputs: z.object({
+        required: z.string(),
+      }),
+      outputs: z.object({ result: z.string() }),
+      async run({ inputs }) {
+        return { result: inputs.required }
+      },
+    })
+
+    // Outputs are validated in the runner, not in execute
+    expect(TestStep.definition.outputsSchema).toBeDefined()
+    expect(TestStep.definition.inputsSchema).toBeDefined()
+  })
+
+  it('step definition contains all metadata', async () => {
+    const TestStep = createStep({
+      name: 'test-step',
+      description: 'Test step',
+      inputs: z.object({
+        number: z.number(),
+      }),
+      outputs: z.object({ result: z.string() }),
+      async run() {
+        return { result: 'ok' }
+      },
+    })
+
+    expect(TestStep.definition.name).toBe('test-step')
+    expect(TestStep.definition.description).toBe('Test step')
+    expect(TestStep.definition.inputsSchema).toBeDefined()
+    expect(TestStep.definition.outputsSchema).toBeDefined()
+  })
+
+  // todo: this test is now a static type error, update to refelct that
+  // it('does not warn for non-object schemas', async () => {
+  //   const TestStep = defineStep({
+  //     name: 'test-step',
+  //     description: 'Test step',
+  //     inputs: z.string(),
+  //     outputs: z.object({ result: z.string() }),
+  //     async run({ inputs }) {
+  //       return { result: inputs }
+  //     },
+  //   })
+
+  //   await TestStep(mockContext, 'just-a-string')
+
+  //   expect(mockCore.warning).not.toHaveBeenCalled()
+  // })
+
+  it('always provides PR controller', async () => {
+    const mockPR = {
+      number: 123,
+      isActive: true,
+      comment: vi.fn(),
+      deleteComment: vi.fn(),
+      getComments: vi.fn(),
+    }
+
+    const contextWithPR = {
+      ...mockContext,
+      pr: mockPR,
+    }
+
+    const TestStep = createStep({
+      name: 'test-step',
+      description: 'Test step with PR',
+      inputs: z.object({}),
+      outputs: z.object({ isActive: z.boolean() }),
+      async run({ pr }) {
+        return { isActive: pr.isActive }
+      },
+    })
+
+    const result = await TestStep.run({
+      ...contextWithPR,
+      inputs: {},
+    })
+    expect(result).toEqual({ isActive: true })
+  })
+})

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

@@ -0,0 +1,232 @@
+/**
+ * Type-safe workflow step framework for GitHub Actions
+ */
+
+// import type { Context } from '@actions/github/lib/context.ts'
+import type { GitHub } from '@actions/github/lib/utils.ts'
+import { z } from 'zod/v4'
+import type { GitController } from './git-controller.ts'
+import type { PullRequestController } from './pr-controller.ts'
+import type { Context, ContextSchema as RealContextSchema } from './schemas/context.ts'
+
+/**
+ * Arguments passed to the step's run function.
+ *
+ * @template $Inputs - The validated input values based on your inputs schema
+ * @template $Context - The GitHub Actions context (validated if context schema provided)
+ */
+export interface Args<$Inputs extends Inputs = Inputs, $Context = Context> {
+  /** GitHub Actions core utilities for logging, setting outputs, etc. */
+  core: typeof import('@actions/core')
+
+  /** GitHub Actions context containing event payload, repo info, etc. */
+  context: $Context
+
+  /** Validated input values passed to the step */
+  inputs: $Inputs
+
+  /** Authenticated Octokit instance for GitHub API operations */
+  github: InstanceType<typeof GitHub>
+
+  /** zx's $ function for executing shell commands */
+  $: typeof import('zx').$
+
+  /** Node.js fs/promises module for file operations */
+  fs: typeof import('node:fs/promises')
+
+  /** PR controller for pull request operations (comment, review, etc.) */
+  pr: PullRequestController
+
+  /** Git controller for git operations (commit, push, etc.) without subprocess details */
+  git: GitController
+}
+
+export type Outputs = object
+
+export type Inputs = object
+
+type InputsSchema = z.ZodObject
+
+type OutputsSchema = z.ZodObject
+
+// This is a loose type because working with sub/sup schema types is complex, maybe not even workable, unclear, and not worth the effort
+type ContextSchema = z.Schema
+
+// Export the full step definition for runner
+export interface Step<
+  $InputsSchema extends InputsSchema = InputsSchema,
+  $OutputsSchema extends OutputsSchema = OutputsSchema,
+  $ContextSchema extends ContextSchema = ContextSchema,
+> {
+  definition: Definition<
+    $InputsSchema,
+    $OutputsSchema,
+    $ContextSchema
+  >
+  run: Runner<
+    z.output<$InputsSchema>,
+    z.output<$OutputsSchema>,
+    z.output<$ContextSchema>
+  >
+}
+
+export type Runner<
+  $Inputs extends Inputs = Inputs,
+  $Outputs extends Outputs = Outputs,
+  $Context = Context,
+> = (
+  context: Args<$Inputs, $Context>,
+) => Promise<$Outputs>
+
+// Generic workflow step definition
+export interface Definition<
+  $InputsSchema extends InputsSchema,
+  $OutputsSchema extends OutputsSchema,
+  $ContextSchema extends ContextSchema,
+> {
+  description?: string
+  name?: string
+  inputsSchema?: $InputsSchema
+  outputsSchema?: $OutputsSchema
+  contextSchema?: $ContextSchema
+}
+
+// Generic workflow step definition
+export interface CreateInput<
+  $InputsSchema extends InputsSchema,
+  $OutputsSchema extends OutputsSchema,
+  $ContextSchema extends z.Schema,
+> {
+  description?: string
+  name?: string
+  inputs?: $InputsSchema
+  outputs?: $OutputsSchema
+  context?: $ContextSchema
+  run: (
+    args: Args<z.output<$InputsSchema>, z.output<$ContextSchema>>,
+    // todo: Obj.isEmpty ...
+  ) => Promise<{} extends z.Infer<$OutputsSchema> ? void : z.Infer<$OutputsSchema>>
+}
+
+/**
+ * Create a type-safe GitHub Actions workflow step with runtime validation.
+ *
+ * This is the main entry point for defining custom workflow steps that can be executed
+ * by the GitHub Actions runner. It provides:
+ * - Type-safe inputs/outputs with Zod schema validation
+ * - Automatic GitHub Actions output handling (both individual outputs and bundled JSON)
+ * - Context validation to ensure steps run in the correct workflow events
+ * - Integration with GitHub API via Octokit
+ * - Built-in error handling and logging
+ *
+ * @example Basic step with inputs and outputs
+ * ```typescript
+ * import { z } from 'zod'
+ * import { GitHubActions } from '#lib/github-actions'
+ *
+ * export default GitHubActions.createStep({
+ *   name: 'my-step',
+ *   description: 'Processes some data and returns results',
+ *   inputs: z.object({
+ *     message: z.string(),
+ *     count: z.number().optional().default(1),
+ *   }),
+ *   outputs: z.object({
+ *     result: z.string(),
+ *     processed: z.boolean(),
+ *   }),
+ *   async run({ inputs, core }) {
+ *     core.info(`Processing: ${inputs.message}`)
+ *
+ *     return {
+ *       result: inputs.message.toUpperCase(),
+ *       processed: true,
+ *     }
+ *   }
+ * })
+ * ```
+ *
+ * @example Step with specific context requirements
+ * ```typescript
+ * export default GitHubActions.createStep({
+ *   name: 'pr-only-step',
+ *   description: 'This step only runs on pull requests',
+ *   context: GitHubActions.PullRequestContext,
+ *   outputs: z.object({
+ *     pr_number: z.number(),
+ *   }),
+ *   async run({ context, core }) {
+ *     const prNumber = context.payload.pull_request.number
+ *     core.info(`Running on PR #${prNumber}`)
+ *
+ *     return { pr_number: prNumber }
+ *   }
+ * })
+ * ```
+ *
+ * @example Using the GitHub API
+ * ```typescript
+ * export default GitHubActions.createStep({
+ *   name: 'create-issue',
+ *   description: 'Creates a GitHub issue',
+ *   inputs: z.object({
+ *     title: z.string(),
+ *     body: z.string(),
+ *   }),
+ *   outputs: z.object({
+ *     issue_number: z.number(),
+ *     issue_url: z.string(),
+ *   }),
+ *   async run({ inputs, github, context }) {
+ *     const issue = await github.rest.issues.create({
+ *       owner: context.repo.owner,
+ *       repo: context.repo.repo,
+ *       title: inputs.title,
+ *       body: inputs.body,
+ *     })
+ *
+ *     return {
+ *       issue_number: issue.data.number,
+ *       issue_url: issue.data.html_url,
+ *     }
+ *   }
+ * })
+ * ```
+ *
+ * @param input - Step configuration object
+ * @param input.name - Unique identifier for the step (used in logging and debugging)
+ * @param input.description - Human-readable description of what the step does
+ * @param input.inputs - Optional Zod schema for validating step inputs
+ * @param input.outputs - Optional Zod schema for validating step outputs
+ * @param input.context - Optional Zod schema for validating GitHub Actions context (event type)
+ * @param input.run - Async function that implements the step logic
+ *
+ * @returns A Step object that can be executed by the GitHub Actions runner
+ *
+ * @remarks
+ * - All outputs are automatically set as GitHub Actions outputs
+ * - Boolean outputs are properly handled (use fromJSON in workflows)
+ * - A special 'json' output contains all outputs bundled together
+ * - The runner provides extensive logging and error handling
+ * - Steps can access PR controller for pull request operations
+ * - The `$` from zx is available for shell commands
+ */
+export function createStep<
+  $InputsSchema extends InputsSchema,
+  $OutputsSchema extends OutputsSchema,
+  $ContextSchema extends ContextSchema = RealContextSchema,
+>(
+  input: CreateInput<$InputsSchema, $OutputsSchema, $ContextSchema>,
+): Step<$InputsSchema, $OutputsSchema, $ContextSchema> {
+  const { run, inputs, outputs, context, ...rest } = input
+  const definition: Definition<$InputsSchema, $OutputsSchema, $ContextSchema> = {
+    ...rest,
+    inputsSchema: inputs,
+    outputsSchema: outputs,
+    contextSchema: context,
+  }
+  return {
+    definition,
+    run,
+  } as any
+}

package/src/lib/helpers.ts

@@ -1,4 +1,4 @@
-import { Manifest } from '@wollybeard/kit'
+import { Err, Manifest } from '@wollybeard/kit'
 
 /**
  * Check if a project has a package installed by examining its package.json
@@ -9,8 +9,9 @@ export async function checkIsProjectHasPackageInstalled(
 ): Promise<boolean> {
   const packageJson = await Manifest.resource.read(projectRoot)
 
-  if (!packageJson) {
-    return false
+  if (Err.is(packageJson)) {
+    if (packageJson._tag === 'ResourceErrorNotFound') return false
+    throw packageJson
   }
 
   // Check if React is in dependencies or devDependencies

package/src/lib/kit-temp.test-d.ts

@@ -0,0 +1,115 @@
+import { Ts } from '@wollybeard/kit'
+import { objFilter, ObjOmit, ObjPick, objPolicyFilter } from './kit-temp.js'
+import type { ObjPolicyFilter } from './kit-temp.js'
+
+// Test object for all tests
+type TestObj = { a: string; b: number; c: boolean; d: string[] }
+declare const testObj: TestObj
+
+// Test 1: objPolicyFilter with allow mode
+{
+  const result = objPolicyFilter('allow', testObj, ['a', 'c'] as const)
+  Ts.assertEqual<{ a: string; c: boolean }>()(result)
+}
+
+// Test 2: objPolicyFilter with deny mode
+{
+  const result = objPolicyFilter('deny', testObj, ['a', 'c'] as const)
+  Ts.assertEqual<{ b: number; d: string[] }>()(result)
+}
+
+// Test 3: objFilter returns Partial<T>
+{
+  const result = objFilter(testObj, (key, value) => value !== 'hello')
+  Ts.assertEqual<Partial<TestObj>>()(result)
+
+  // All properties are optional
+  Ts.assertSub<typeof result.a>()(undefined)
+  Ts.assertSub<typeof result.b>()(undefined)
+  Ts.assertSub<typeof result.c>()(undefined)
+  Ts.assertSub<typeof result.d>()(undefined)
+}
+
+// Test 4: ObjPick type inference
+{
+  const result = ObjPick(testObj, ['a', 'c'] as const)
+  Ts.assertEqual<{ a: string; c: boolean }>()(result)
+}
+
+// Test 5: ObjOmit type inference
+{
+  const result = ObjOmit(testObj, ['a', 'c'] as const)
+  Ts.assertEqual<{ b: number; d: string[] }>()(result)
+}
+
+// Test 6: ObjPolicyFilter type-level function
+{
+  type Allow = ObjPolicyFilter<TestObj, 'a' | 'c', 'allow'>
+  type _TestAllow = Ts.AssertEqual<Allow, { a: string; c: boolean }>
+
+  type Deny = ObjPolicyFilter<TestObj, 'a' | 'c', 'deny'>
+  type _TestDeny = Ts.AssertEqual<Deny, { b: number; d: string[] }>
+
+  type AllowEmpty = ObjPolicyFilter<TestObj, never, 'allow'>
+  type _TestAllowEmpty = Ts.AssertEqual<AllowEmpty, {}>
+
+  type DenyEmpty = ObjPolicyFilter<TestObj, never, 'deny'>
+  type _TestDenyEmpty = Ts.AssertEqual<DenyEmpty, TestObj>
+}
+
+// Test 7: Edge cases
+{
+  // Empty object
+  const empty = {}
+  const allowEmpty = objPolicyFilter('allow', empty, [])
+  const denyEmpty = objPolicyFilter('deny', empty, [])
+  const filterEmpty = objFilter(empty, () => true)
+
+  Ts.assertEqual<{}>()(allowEmpty)
+  Ts.assertEqual<{}>()(denyEmpty)
+  Ts.assertEqual<{}>()(filterEmpty)
+
+  // Single property object
+  const single = { a: 1 }
+  const allowSingle = objPolicyFilter('allow', single, ['a'] as const)
+  const denySingle = objPolicyFilter('deny', single, ['a'] as const)
+  const filterSingle = objFilter(single, () => true)
+
+  Ts.assertEqual<{ a: number }>()(allowSingle)
+  Ts.assertEqual<{}>()(denySingle)
+  Ts.assertEqual<{ a?: number }>()(filterSingle)
+}
+
+// Test 8: Complex nested object
+{
+  type ComplexObj = {
+    nested: { a: string; b: number }
+    array: string[]
+    optional?: boolean
+    readonly ro: string
+  }
+  const complexObj = {} as ComplexObj
+
+  const picked = objPolicyFilter('allow', complexObj, ['nested', 'optional'] as const)
+  Ts.assertEqual<{ nested: { a: string; b: number }; optional?: boolean }>()(picked)
+
+  const omitted = objPolicyFilter('deny', complexObj, ['nested', 'optional'] as const)
+  Ts.assertEqual<{ array: string[]; readonly ro: string }>()(omitted)
+
+  const filtered = objFilter(complexObj, (key) => key !== 'array')
+  Ts.assertEqual<Partial<ComplexObj>>()(filtered)
+}
+
+// Test 9: Keys parameter type inference
+{
+  // With const assertion
+  const keys1 = ['a', 'c'] as const
+  const result1 = objPolicyFilter('allow', testObj, keys1)
+  Ts.assertEqual<{ a: string; c: boolean }>()(result1)
+
+  // Without const assertion (wider type)
+  const keys2: (keyof TestObj)[] = ['a', 'c']
+  const result2 = objPolicyFilter('allow', testObj, keys2)
+  // Result is a union of all possible picks
+  type Result2 = typeof result2 // Pick<TestObj, keyof TestObj>
+}

package/src/lib/kit-temp.test.ts

@@ -0,0 +1,127 @@
+import * as fc from 'fast-check'
+import { describe, expect, test } from 'vitest'
+import { objFilter, ObjOmit, ObjPick, objPolicyFilter } from './kit-temp.js'
+
+describe('objPolicyFilter', () => {
+  const testObj = { a: 1, b: 2, c: 3, d: 4 }
+
+  test('allow mode picks specified keys', () => {
+    expect(objPolicyFilter('allow', testObj, ['a', 'c'])).toEqual({ a: 1, c: 3 })
+    expect(objPolicyFilter('allow', testObj, [])).toEqual({})
+    expect(objPolicyFilter('allow', testObj, ['a', 'z'] as any)).toEqual({ a: 1 })
+  })
+
+  test('deny mode omits specified keys', () => {
+    expect(objPolicyFilter('deny', testObj, ['a', 'c'])).toEqual({ b: 2, d: 4 })
+    expect(objPolicyFilter('deny', testObj, [])).toEqual(testObj)
+    expect(objPolicyFilter('deny', testObj, ['z'] as any)).toEqual(testObj)
+  })
+
+  test('preserves undefined values', () => {
+    const obj = { a: 1, b: undefined, c: 3 }
+    expect(objPolicyFilter('allow', obj, ['a', 'b'])).toEqual({ a: 1, b: undefined })
+  })
+})
+
+describe('objFilter', () => {
+  const testObj = { a: 1, b: 2, c: 3, d: 4 }
+
+  test('filters by predicates', () => {
+    // By value
+    expect(objFilter(testObj, (k, v) => v > 2)).toEqual({ c: 3, d: 4 })
+
+    // By key
+    expect(objFilter(testObj, k => k === 'a' || k === 'c')).toEqual({ a: 1, c: 3 })
+
+    // By full object context
+    expect(objFilter(testObj, (k, v, obj) => {
+      const avg = Object.values(obj).reduce((a, b) => a + b, 0) / Object.keys(obj).length
+      return v < avg
+    })).toEqual({ a: 1, b: 2 })
+  })
+
+  test('edge cases', () => {
+    expect(objFilter(testObj, () => false)).toEqual({})
+    expect(objFilter(testObj, () => true)).toEqual(testObj)
+    expect(objFilter({}, () => true)).toEqual({})
+  })
+})
+
+describe('ObjPick and ObjOmit', () => {
+  test('are aliases for objPolicyFilter', () => {
+    const obj = { a: 1, b: 2, c: 3 }
+    const keys = ['a', 'c'] as const
+
+    expect(ObjPick(obj, keys)).toEqual(objPolicyFilter('allow', obj, keys))
+    expect(ObjOmit(obj, keys)).toEqual(objPolicyFilter('deny', obj, keys))
+  })
+})
+
+describe('property-based tests', () => {
+  test('objPolicyFilter allow/deny are complementary', () => {
+    fc.assert(
+      fc.property(
+        fc.object(),
+        fc.array(fc.string()),
+        (obj, keys) => {
+          const allowed = objPolicyFilter('allow', obj, keys)
+          const denied = objPolicyFilter('deny', obj, keys)
+
+          // Every key in obj is either in allowed or denied, never both
+          Object.keys(obj).forEach(key => {
+            const inAllowed = Object.prototype.hasOwnProperty.call(allowed, key)
+            const inDenied = Object.prototype.hasOwnProperty.call(denied, key)
+            expect(inAllowed).toBe(!inDenied)
+          })
+
+          // Combined they reconstruct the original object
+          expect({ ...allowed, ...denied }).toEqual(obj)
+        },
+      ),
+    )
+  })
+
+  test('objFilter preserves values unchanged', () => {
+    fc.assert(
+      fc.property(
+        fc.object(),
+        (obj) => {
+          const filtered = objFilter(obj, () => true)
+          expect(filtered).toEqual(obj)
+
+          // Values are the same reference
+          Object.keys(filtered).forEach(key => {
+            expect(filtered[key]).toBe(obj[key])
+          })
+        },
+      ),
+    )
+  })
+
+  test('objPolicyFilter is immutable', () => {
+    fc.assert(
+      fc.property(
+        fc.object(),
+        fc.array(fc.string()),
+        fc.oneof(fc.constant('allow' as const), fc.constant('deny' as const)),
+        (obj, keys, mode) => {
+          const original = { ...obj }
+          objPolicyFilter(mode, obj, keys)
+          expect(obj).toEqual(original)
+        },
+      ),
+    )
+  })
+
+  test('empty keys behavior', () => {
+    fc.assert(
+      fc.property(
+        fc.object(),
+        (obj) => {
+          expect(objPolicyFilter('allow', obj, [])).toEqual({})
+          expect(objPolicyFilter('deny', obj, [])).toEqual(obj)
+        },
+      ),
+    )
+  })
+})