Seed Create

A seed is NOT complete until bun test passes on BOTH test files. This skill writes code and validates it. It does NOT do research — that's /seed:research.

Prerequisites

A research document MUST exist at src/domains/{domain}/{name}.research.md. The only exception is when the user provides precise API details directly (endpoints, params, response shapes) in their prompt.

Read the research doc fully before writing any code.

Step 1 — Determine domain placement

• New domain? Create src/domains/{domain}/index.ts, types.ts, __tests__/
• Existing domain? Add to the existing index.ts exports

Register the domain in entry points:

• src/tui/index.tsx — add import '../domains/{domain}'
• bin/fresha-seed.ts — add import '../src/domains/{domain}'

Step 2 — Write the seed

Follow the patterns in ../seed-shared/patterns.md.

Mandatory fields:

• name — unique, dot-separated (e.g. services.add)
• domain — matches directory name
• label — human-readable for TUI
• context — 'partner', 'consumer', or 'none'
• params — use param.* builders with freshaFaker defaults
• artifacts — typed function returning displayable results
• execute — async function using generated API clients

Param types:

• Static — free text/number input with faker defaults: param.static(z.string(), { label, defaultValue })
• Select — fixed options list: param.select([{ label, value }], { label })
• param.from (PREFERRED for all ID/resource params) — type-safe picker linked to a .get seed:

  typescript
  1// Extract .get and .add as standalone consts (before the domain export object)
  2const getGroups = defineOperation({ name: 'services.getGroups', execute: ... })
  3const addGroup = defineOperation({ name: 'services.addGroup', execute: ... })
  4
  5// In the seed's params:
  6serviceGroupId: param.from(getGroups, {
  7  display: (g) => g.name,   // TItem inferred from getGroups return type
  8  value: (g) => g.id,       // type-safe
  9  create: addGroup,          // TUI shows [+ Create new]
  10})
  11
  12// Optional variant — user can skip (auto-resolve internally)
  13serviceGroupId: param.optional(param.from(getGroups, { ... }))

• Count — up/down numeric input: param.count({ label, min, max, default })
• Boolean — toggle: param.boolean({ label, defaultValue }) Domain rules:
• Every domain MUST have a .get seed that returns the resource array
• Extract .get and .add operations as standalone const (not inline in the domain export) so other seeds can reference them via param.from
• Cross-domain references work: import { get as getServices } from '../services' then param.from(getServices, { ... })

Chaining is derived automatically from param.from declarations. The framework:

1. Auto-infers acceptsPort from the source operation's first output port (e.g. param.from(getGroups) → acceptsPort: 'serviceGroupId')
2. Generates inputs at registration time — do NOT declare inputs manually when using param.from
3. When param key differs from port name, set acceptsPort explicitly (e.g. paidPlanId accepts port membershipId)
4. Port names are typed via PortName union — typos are compile errors
5. Operations without param.from (static params) can still declare explicit inputs with typed port names

producesContext — needed if the seed creates a partner/consumer session:

typescript
1producesContext: {
2  type: 'partner',
3  extract: (r) => ({ id: r.partnerId, cookie: r.cookie }),
4},

Checklist:

• API calls use generated clients (openapi-fetch or GQL), NOT raw fetch
• Params with number types use zod validation and note API constraints
• ID/resource params use param.from referencing a .get seed — NOT param.static or manual param.dynamic
• param.from includes create when a corresponding .add seed exists
• No manual inputs array when param.from is used (auto-derived from acceptsPort)
• acceptsPort set explicitly when param key differs from port name
• .get and .add operations extracted as standalone consts for cross-referencing
• artifacts returns links (marketplace, flippy), IDs, credentials as appropriate
• Faker defaults for all static params where sensible
• Types in types.ts, not inline
• Research doc exists at src/domains/{domain}/{name}.research.md
• producesContext declared if seed creates a partner/consumer session

Step 3 — Write unit tests

File: src/domains/{domain}/__tests__/{domain}.test.ts

Must cover:

• Seed metadata (name, domain, context)
• Param shapes (kind, defaultValue type, labels)
• Artifacts function with mock data
• Dynamic param display/value functions with mock items

Run: bun test src/domains/{domain}/__tests__/{domain}.test.ts

Step 4 — Write integration tests

File: src/domains/{domain}/__tests__/{domain}.integration.test.ts

Must cover:

• Seed executes successfully against real API
• Return value has expected shape and truthy IDs
• Verified via Domain.get() — the source of truth
• Artifacts match real data
• Uses setupTestPartner/teardownTestPartner in beforeAll/afterAll — zero mocks, automatic teardown

typescript
1import { afterAll, beforeAll, describe, expect, test } from 'bun:test'
2import type { PartnerContext } from '../../../framework/types'
3import { setupTestPartner, teardownTestPartner } from '../../../test-utils'
4
5describe('Domain (integration)', () => {
6  let ctx: PartnerContext
7
8  beforeAll(async () => {
9    const setup = await setupTestPartner()
10    ctx = setup.ctx
11  }, 60_000)
12
13  afterAll(async () => {
14    await teardownTestPartner(ctx)
15  })
16
17  test('Domain.op creates X verifiable via get', async () => {
18    // Setup: Location.update + publish, Services.add if needed
19    // Execute: call the seed
20    // Assert: check return value
21    // Verify: call Domain.get()
22    // Artifacts: verify artifacts(result, ctx)
23  }, 90_000)
24})

Run: bun test src/domains/{domain}/__tests__/{domain}.integration.test.ts

Step 5 — Run until green (MANDATORY)

bash
1# Unit tests (fast)
2bun test src/domains/{domain}/__tests__/{domain}.test.ts
3
4# Integration tests (real API, ~10-60s per test)
5bun test src/domains/{domain}/__tests__/{domain}.integration.test.ts

1. Run both. If failures: read error, fix, re-run.
2. Repeat up to 3 iterations.
3. All tests green = seed complete.

References

• Patterns: See ../seed-shared/patterns.md
• Test utils: src/test-utils/index.ts
• Faker: src/data/faker.ts
• API clients: src/api/clients/
• Example seed: src/domains/services/index.ts
• Example tests: src/domains/services/__tests__/