@t4h.framework/core 0.3.0 → 0.5.0

package/.ai/skills/framework-core/SKILL.md

@@ -0,0 +1,403 @@
+---
+name: framework-core
+description: >-
+  Author and test T4H Framework workflows, SyncActivity/AsyncActivity classes,
+  Claim dependencies, App manifests, env access, and in-memory workflow runs.
+  Use when importing @t4h.framework/core, building automation apps, orchestrating
+  with History.reconciler, wiring Claim providers, testing with
+  @t4h.framework/core/testing (WorkflowTesting, mockAsyncActivity), nested
+  startWorkflow, EnvDesign, Authorization manifests, or Internals.runWorkflow /
+  Internals.runActivity.
+---
+
+# @t4h.framework/core
+
+Core primitives for **Workflows** (orchestration), **Activities** (work units), and **Claims** (runtime dependencies). The runtime supplies `env`, `claims`, and `history`; this package defines the author API and in-memory test harness.
+
+| Import | Purpose |
+|--------|---------|
+| `@t4h.framework/core` | Workflows, activities, claims, app, env, internals |
+| `@t4h.framework/core/testing` | `WorkflowTesting` — tests/local only |
+
+Node `>=22`. Schemas use TypeBox (`typebox`). See [README.md](../../../README.md) for diagrams.
+
+---
+
+## Concepts
+
+- **Workflow** — orchestration; composes activities via `History.reconciler` (or helpers like `startWorkflow`).
+- **Activity** — `SyncActivity` (`toInput` → `run` → `toOutput`) or `AsyncActivity` (`toInput` → `bootstrap` → `advance` → `toOutput`, optional `onTimeout`).
+- **Claim** — abstract class; activity maps keys → constructors; runtime provides `{ provide, value }`.
+- **History** — replay: existing history entries skip execution; missing entries run activity and record result (`PushActivity`).
+
+Async helpers on `AsyncActivity`: `this.pending()`, `this.done()`, `this.rejected()`.
+
+---
+
+## Workflows
+
+```typescript
+import Type from 'typebox'
+import { Workflow, env } from '@t4h.framework/core'
+
+const bare = new Workflow(async () => ({ ok: true }))
+
+const withMeta = new Workflow(
+  { id: 'cashback/v1', description: 'Process cashback' },
+  async input => ({ value: input.amount * 0.05 }),
+)
+
+const schema = Type.Object({ userId: Type.String(), amount: Type.Number() })
+const validated = new Workflow({ id: 'cashback/v1', schema }, async input => ({
+  value: input.amount * 0.05,
+}))
+```
+
+- `new Workflow(fn)` or `new Workflow(options, fn)` — bad overload throws `Invalid constructor arguments`.
+- `WorkflowInput<T>` — from schema; `undefined` without schema.
+- `workflow.validate` — Ajv when `schema` set; else `null`.
+- Optional `authorization` on workflow/app → `toManifest()`.
+
+---
+
+## Invoking activities
+
+```typescript
+import { History } from '@t4h.framework/core'
+
+const syncResult = await History.reconciler(MySyncActivity, arg1)
+
+const handle = await History.reconciler(WaitAsyncActivity, 'order-1')
+const out = await handle.wait()
+```
+
+- No history: `toInput` then `PushActivity` → runtime runs `run`/`bootstrap`.
+- Replay: uses stored output; async returns `AsyncActivityAwaitable`; `wait()` throws `PushWaitAsyncActivity` if still `pending`.
+- Must run inside `History.run` (workflow runtime / `WorkflowTesting` provide this).
+
+---
+
+## SyncActivity
+
+```typescript
+import { SyncActivity } from '@t4h.framework/core'
+
+class CalculateCashbackActivity extends SyncActivity<
+  [transaction: { amount: number }], // TArgs
+  { amount: number },                  // TInput (Serializable)
+  number,                              // TSerializableOutput
+  number                               // TOutput
+> {
+  public async toInput(transaction: { amount: number }) {
+    return { amount: transaction.amount }
+  }
+  public run(input: { amount: number }) {
+    return Math.floor(input.amount * 0.05)
+  }
+  public toOutput(output: number) {
+    return output
+  }
+}
+```
+
+`toOutput(output, ...args)` receives original designer args.
+
+---
+
+## AsyncActivity
+
+```typescript
+import Type from 'typebox'
+import { AsyncActivity, AsyncActivityResultPending } from '@t4h.framework/core'
+
+const ApprovalSchema = Type.Object({ approved: Type.Boolean() })
+
+class WaitForApprovalActivity extends AsyncActivity<
+  [orderId: string],
+  { orderId: string },
+  { approved: boolean },
+  { approved: boolean },
+  { requestId: string; orderId: string },
+  typeof ApprovalSchema
+> {
+  public async toInput(orderId: string) {
+    return { orderId }
+  }
+  public async bootstrap(input: { orderId: string }) {
+    return this.pending({
+      payload: { requestId: 'req-123', orderId: input.orderId },
+      schema: ApprovalSchema,
+      timeoutAt: new Date(Date.now() + 3_600_000),
+    })
+  }
+  public async advance(
+    payload: Type.Static<typeof ApprovalSchema>,
+    bootstrap: AsyncActivityResultPending<{ requestId: string; orderId: string }>,
+  ) {
+    return payload.approved
+      ? this.done({ approved: true })
+      : this.rejected({ approved: false, requestId: bootstrap.payload?.requestId })
+  }
+  public toOutput(output: { approved: boolean }) {
+    return output
+  }
+}
+```
+
+Results: `AsyncActivityResultPending` | `AsyncActivityResultFulfilled` | `AsyncActivityResultRejected`. Default `onTimeout` → `rejected({ reason: 'timeout' })`.
+
+---
+
+## Claims
+
+```typescript
+import { SyncActivity, Claim } from '@t4h.framework/core'
+
+abstract class UserRepositoryClaim {
+  abstract findById(id: string): Promise<unknown>
+}
+
+class FetchUserActivity extends SyncActivity<[id: string], { id: string }, unknown, unknown> {
+  private readonly claims = new Claim({ repo: UserRepositoryClaim })
+
+  public async toInput(id: string) {
+    return { id }
+  }
+  public async run(input: { id: string }) {
+    return await this.claims.repo.findById(input.id)
+  }
+  public toOutput(output: unknown) {
+    return output
+  }
+}
+```
+
+Provider: `{ provide: UserRepositoryClaim, value: impl }`. Built-ins: `GetWorkflowUniqueIdentifierClaim`, `GetActivityUniqueIdentifierClaim`, `WorkflowClaim` (for `startWorkflow`).
+
+Exceptions: `ClaimKeyNotFoundException`, `ClaimConstructorNotFoundException`, `ClaimStorageNotActiveException`, `ClaimProviderNotFoundException`. Access `claims.*` only inside `Claim.run`.
+
+---
+
+## Nested workflows
+
+```typescript
+import { startWorkflow, WorkflowClaim } from '@t4h.framework/core'
+
+const ref = await startWorkflow(childWorkflow, { ...input, parallel?: boolean })
+// WorkflowRef: status 'fulfilled' | 'rejected', output Serializable
+```
+
+`StartWorkflowActivity`: `parallel: true` → immediate `done`; else `pending` until `advance`. Requires `WorkflowClaim` provider.
+
+---
+
+## App
+
+```typescript
+import { App, Workflow } from '@t4h.framework/core'
+
+const app = new App({
+  id: 'my-automation',
+  description: 'Cashback automation',
+  workflows: [myWorkflow],
+})
+app.addWorkflow(anotherWorkflow) // throws on duplicate workflow.id
+```
+
+`toManifest()` includes workflows + registered `EnvDesign` entries.
+
+---
+
+## Environment
+
+```typescript
+import { env, EnvDesign } from '@t4h.framework/core'
+
+// Under Env.run — string values
+console.log(env.API_URL)
+
+// Typed parsing (registers for app manifest)
+const config = EnvDesign({
+  API_URL: { type: String },
+  RETRIES: { type: Number, defaultValue: '3' },
+  DEBUG: { type: Boolean, isOptional: true },
+})
+```
+
+---
+
+## Serializable & Authorization
+
+**Serializable:** primitives, `null`, `undefined`, `Binary`, `SerializableClass`, arrays/objects thereof. `Binary`: `contentType`, `contentLength`, `stream()`.
+
+**Authorization:** subclass with `toManifest(): AuthorizationManifest` (`pathToModule`, optional `context`); attach to `Workflow` or `App`.
+
+---
+
+## Internals (runtime / unit tests)
+
+```typescript
+import { Internals } from '@t4h.framework/core'
+
+Internals.runWorkflow(workflow, {
+  input,
+  env: { API_URL: 'https://api.example.com' },
+  claims: [{ provide: UserRepositoryClaim, value: impl }],
+  history: [],
+  logs: [],
+})
+
+Internals.runActivity(FetchUserActivity, { env, claims }, a => a.run({ id: '123' }))
+```
+
+Stack: `Env.run` → `Claim.run` → `History.run` → `Logger.run` (workflows). **Test `advance` here** — not via `WorkflowTesting`.
+
+---
+
+## Testing (`@t4h.framework/core/testing`)
+
+Test-only entrypoint — **not** part of the production runtime contract. Import from the subpath export:
+
+```typescript
+import { WorkflowTesting } from '@t4h.framework/core/testing'
+```
+
+`package.json` maps `"./testing"` → `dist/testing/index.js`. The public API is **`WorkflowTesting.run`** only.
+
+### `WorkflowTesting.run`
+
+```typescript
+const output = await WorkflowTesting.run(workflow, input?, options?)
+```
+
+| Option | Type | Default | Purpose |
+|--------|------|---------|---------|
+| `claims` | `readonly ClaimProvider[]` | `[]` | Concrete claim implementations for the run |
+| `env` | `Env.Entries` | `{}` | String env vars (`Env.run`) |
+| `mockAsyncActivity` | function \| outcome array | — | Required when any async activity returns `pending` |
+| `logs` | `Log[]` | internal | Capture `console.log` / `console.error` once per run |
+| `maxTicks` | `number` | `10_000` | Max activity-resolution loops before error |
+
+Typed input follows `WorkflowInput<T>` when the workflow has a `schema`; omit `input` for workflows without one.
+
+### How the driver works
+
+1. Calls `Internals.runWorkflow` with an empty `history`.
+2. On **`PushActivity`**, runs the pushed activity in-process:
+   - **Sync:** `Internals.runActivity` → `run(input)` → append `{ type: 'sync', output }` to history.
+   - **Async:** real `bootstrap`; if already `done`/`rejected`, record and continue; if **`pending`**, apply `mockAsyncActivity` (throws if missing).
+3. Re-runs the workflow with accumulated history until it returns normally or `maxTicks` is exceeded.
+
+This drives sync activities end-to-end and async activities through bootstrap + mocked resolution — **not** through real `advance`.
+
+### Wiring claims in tests
+
+Pass explicit `{ provide, value }` providers — same shape as `Internals.runWorkflow`:
+
+```typescript
+import { WorkflowTesting } from '@t4h.framework/core/testing'
+import { History, type Log } from '@t4h.framework/core'
+
+const logs: Log[] = []
+const output = await WorkflowTesting.run(workflow, input, {
+  env: { API_URL: 'https://example.com' },
+  claims: [{ provide: UserRepositoryClaim, value: mockRepo }],
+  mockAsyncActivity: () => ({ status: 'fulfilled', output: true }),
+  logs,
+})
+```
+
+For a single activity, prefer `Claim.run([...], fn)` or `Internals.runActivity`. Use `WorkflowTesting.run` for full workflow integration tests.
+
+### `mockAsyncActivity`
+
+Required when `bootstrap` returns `pending`:
+
+| `status` | Effect |
+|----------|--------|
+| `fulfilled` | `{ output }` recorded as async fulfilled |
+| `rejected` | `{ reason }` recorded as async rejected |
+| `timeout` | runs the activity's real `onTimeout(pending)` (throws if undefined) |
+
+**Array** — FIFO, one entry per pending async:
+
+```typescript
+mockAsyncActivity: [
+  { status: 'fulfilled', output: true },
+  { status: 'rejected', reason: false },
+]
+```
+
+**Function** — `(activity, { input, pending, index }) => outcome`:
+
+```typescript
+mockAsyncActivity: (activity, { index }) => {
+  if (activity instanceof WaitForApprovalActivity)
+    return { status: 'fulfilled', output: true }
+  if (index === 1) return { status: 'timeout' }
+  return { status: 'rejected', reason: 'denied' }
+}
+```
+
+Bootstrap that already returns `done`/`rejected` needs no mock. Missing mock on pending throws: `pending and no resolveAsyncActivity`. Exhausted array throws: `No more async outcomes`.
+
+### Examples (from `WorkflowTesting.spec.ts`)
+
+**Sync workflow:**
+
+```typescript
+const workflow = new Workflow({ schema }, async input => {
+  const n = await History.reconciler(AddOneActivity, input.value)
+  return n * 10
+})
+await expect(WorkflowTesting.run(workflow, { value: 4 })).resolves.toBe(50)
+```
+
+**Capture logs:**
+
+```typescript
+const logs: Log[] = []
+await WorkflowTesting.run(workflow, undefined, { logs })
+expect(logs.map(entry => entry.args[0])).toEqual(['before activity', 'after activity'])
+```
+
+**Async fulfilled / rejected / timeout:**
+
+```typescript
+await WorkflowTesting.run(workflow, undefined, {
+  mockAsyncActivity: () => ({ status: 'fulfilled', output: true }),
+})
+await WorkflowTesting.run(workflow, undefined, {
+  mockAsyncActivity: () => ({ status: 'rejected', reason: false }),
+})
+await WorkflowTesting.run(workflow, undefined, {
+  mockAsyncActivity: () => ({ status: 'timeout' }),
+})
+```
+
+**Vitest setup** — add `@t4h.framework/core` and `@t4h.framework/core/testing` as devDependencies; run with Vitest (`vitest run`). See `packages/core/src/testing/__tests__/WorkflowTesting.spec.ts`.
+
+### Limits (use `Internals` instead)
+
+- No real **`advance`** — test `advance` via `Internals.runActivity` on the async class.
+- No **`PushWaitAsyncActivity`** / resuming pending `handle.wait()` across ticks.
+- Do not import `@t4h.framework/core/testing` in production app code.
+
+---
+
+## Anti-patterns
+
+- Claims or `env` outside `Claim.run` / `Env.run`.
+- `History.reconciler` outside `History.run`.
+- Pending async tests without `mockAsyncActivity`.
+- `advance` coverage only via `WorkflowTesting` (use `Internals.runActivity`).
+- Non-`Serializable` activity I/O.
+- Duplicate `workflow.id` in `App`.
+- `@t4h.framework/core/testing` in production.
+- APIs not exported from `core.ts` / `testing/index.ts`.
+
+---
+
+## Exports (main)
+
+`Workflow`, `App`, `SyncActivity`, `AsyncActivity`, `Claim`, `History`, `env`, `EnvDesign`, `Authorization`, `WorkflowRef`, `Binary`, `Serializable`, async result types, `startWorkflow`, `WorkflowClaim`, `Internals`, `isActivity`, `Logger`, `Activity` types, exceptions. **Testing:** `WorkflowTesting` only.

package/.ai/skills/framework-workflow-creation/SKILL.md

@@ -0,0 +1,170 @@
+---
+name: framework-workflow-creation
+description: >-
+  Design and implement T4H Framework workflows with @t4h.framework/core using
+  the project's standard structure for workflow files, app registration, and
+  environment handling. Use this whenever the user asks to create a new
+  workflow, wire it into an App, define orchestration with History.reconciler,
+  or refactor workflow code to remove hardcoded URLs/secrets/client values and
+  move configuration to env constants.
+---
+
+# Create workflows with `@t4h.framework/core`
+
+Use this skill to build production-ready workflow modules that are easy to register, test, and maintain.
+
+## Primary goal
+
+Create workflows that:
+
+- expose a `Workflow` constant with explicit metadata (`id`, optional `description`, optional `schema`);
+- orchestrate work through framework primitives (`History.reconciler`, `startWorkflow`) instead of ad-hoc infrastructure code;
+- register cleanly in `App` with `export default new App({...})`;
+- never hardcode URLs, secrets, tokens, client IDs, or tenants in workflow files.
+
+## Expected project shape
+
+### Workflow module
+
+```ts
+import { Workflow } from '@t4h.framework/core'
+
+export const myWorkflow = new Workflow({ id: 'my-workflow' }, async input => {
+  // orchestration only
+})
+```
+
+### App declaration
+
+```ts
+import { App } from '@t4h.framework/core'
+import { myWorkflow } from './workflows/my-workflow.js'
+
+export default new App({
+  id: 'my-app',
+  description: 'My app',
+  workflows: [myWorkflow],
+})
+```
+
+### Environment constants module
+
+```ts
+import { env } from '@t4h.framework/core'
+
+export const SERVICE_URL = env.SERVICE_URL!
+if (!SERVICE_URL) throw new TypeError('SERVICE_URL is not defined')
+```
+
+Keep this in a dedicated constants file and import values into workflows/activities.
+
+## Core APIs to prefer while authoring workflows
+
+- `Workflow` for orchestration entrypoints.
+- `History.reconciler(ActivityClass, ...args)` to execute activities deterministically.
+- `startWorkflow(childWorkflow, { ...input, parallel? })` for nested workflow orchestration.
+- `App` to register workflow modules for runtime discovery.
+- `env` / `EnvDesign` for configuration contracts (not inline literal secrets).
+
+## Authoring rules
+
+1. Keep workflows orchestration-focused. Put low-level operations in activities and claims.
+2. Define workflow metadata with stable `id`.
+3. Use schema when input validation is needed.
+4. Import configuration from environment constants.
+5. Keep side effects explicit and easy to assert in tests.
+
+## Hard constraints
+
+- Do not hardcode URLs, client IDs, client secrets, API keys, tenants, or tokens.
+- Do not initialize third-party clients with inline credentials inside workflow files.
+- Do not read `process.env` directly in workflow modules when the project uses centralized constants via `env`.
+
+If a required env key is missing, fail fast with a clear `TypeError` in the constants module.
+
+## Workflow implementation recipe
+
+### Step 1: define/extend env constants
+
+- Add required keys in a constants module.
+- Export each key from `env.<KEY>!`.
+- Validate each key immediately with an explicit `TypeError`.
+
+### Step 2: create workflow file
+
+- Import `Workflow` and required orchestration helpers.
+- Import only typed/safe constants (never raw secrets inline).
+- Implement the function body as orchestration steps.
+
+### Step 3: wire in App
+
+- Import the workflow module in `main.tsx`.
+- Add it to `workflows: [...]` in `new App({...})`.
+- Keep `App` declaration as default export for runtime loading.
+
+### Step 4: make it test-friendly
+
+- Keep outputs deterministic where possible.
+- Avoid hidden global state.
+- Structure side effects so they can be mocked by claim/activity tests.
+
+## Recommended patterns
+
+### A) Workflow with validated input schema
+
+```ts
+import Type from 'typebox'
+import { Workflow } from '@t4h.framework/core'
+
+const schema = Type.Object({
+  customerId: Type.String(),
+})
+
+export const customerSync = new Workflow(
+  { id: 'customer-sync', schema },
+  async input => {
+    return { accepted: true, customerId: input.customerId }
+  },
+)
+```
+
+### B) Workflow orchestrating activities
+
+```ts
+import { History, Workflow } from '@t4h.framework/core'
+
+export const processOrder = new Workflow({ id: 'process-order' }, async input => {
+  const prepared = await History.reconciler(PrepareOrderActivity, input)
+  const charged = await History.reconciler(ChargeOrderActivity, prepared)
+  return { charged }
+})
+```
+
+### C) Nested workflow orchestration
+
+```ts
+import { Workflow, startWorkflow } from '@t4h.framework/core'
+import { childWorkflow } from './child-workflow.js'
+
+export const parentWorkflow = new Workflow({ id: 'parent-workflow' }, async input => {
+  const ref = await startWorkflow(childWorkflow, input)
+  return ref.output
+})
+```
+
+## Anti-patterns to remove on sight
+
+- Inline `"https://..."` service endpoints in workflow body.
+- Inline `"secret"` / `"clientId"` string literals in workflow code.
+- Creating SDK/API clients with literal credentials in the workflow function.
+- Large workflow functions doing infrastructure plumbing instead of orchestration.
+- Registering workflows in scattered places instead of centralized `App` declaration.
+
+## Output expectations when executing this skill
+
+When asked to create a workflow, produce:
+
+1. A new workflow file exporting a named `Workflow` constant.
+2. Any required env constants in the central constants module.
+3. `App` registration update with the workflow included.
+4. No hardcoded client, secret, token, tenant, or URL values in workflow code.