@keystrokehq/skills 0.0.1

package/keystroke-workflow-authoring/references/runtime-helpers.md

@@ -0,0 +1,264 @@
+# Workflow Runtime Helpers
+
+Read this file when the user asks what they can access from `Workflow.run(...)` or `Step.run(...)`.
+
+`Operation`, `Step`, and `Tool` are aliases for the same class. In this workflow reference, the operation runtime context is described with the workflow-oriented `Step` naming.
+
+## Workflow runtime boundary
+
+Treat authored workflows as TypeScript orchestration code, not as a shell runtime.
+
+Teach these rules explicitly:
+- a workflow cannot run bash commands as part of the workflow authoring model
+- a step is not the place to shell out to `python`, `pnpm`, or arbitrary binaries by default
+- a workflow is for control flow, typed inputs and outputs, waits, hooks, and calls to steps, child workflows, or agents
+- if the task needs shell access, persistent filesystem state, or tool installation, move that work into an agent
+- if the agent needs Python or another binary, install it in the sandbox through sandbox setup or runtime preparation
+
+## Workflow `ctx.wait(duration)`
+
+```ts
+run: async (_input, ctx) => {
+  await ctx.wait('10m');
+  return { resumed: true };
+};
+```
+
+Use this when the workflow should pause durably and resume later.
+
+In authored workflow code, treat `ctx.wait(...)` as taking duration strings.
+
+Common public examples are:
+
+- `await ctx.wait('30s')`
+- `await ctx.wait('10m')`
+- `await ctx.wait('2h')`
+- `await ctx.wait('3d')`
+- `await ctx.wait('1w')`
+- `await ctx.wait('1y')`
+
+The executor normalizes waits into milliseconds internally, but the public workflow authoring surface to teach by default is the unit-based string form.
+
+When a workflow may be used as an agent tool, prefer adding intent metadata so yield receipts are understandable:
+
+```ts
+run: async (_input, ctx) => {
+  await ctx.wait('30m', {
+    intent: 'data-settlement',
+    reason: 'The provider needs time to settle before final reconciliation.',
+  });
+
+  return { resumed: true };
+};
+```
+
+## Workflow `ctx.createHook(name)`
+
+```ts
+run: async (_input, ctx) => {
+  const approval = ctx.createHook('approval');
+  await approval;
+
+  return { approved: true };
+};
+```
+
+Use this when the workflow needs an external approval or resume point.
+
+The hook returned by `ctx.createHook(name)` is promise-like, so you can `await` it directly.
+
+Think of a hook as a set of workflow suspension endpoints:
+
+- `resumeUrl`: endpoint that resumes the workflow
+- `cancelUrl`: endpoint that cancels the hook
+- `approvalPageUrl`: URL for a built-in approval page or human-facing approval flow
+- `token`: stable identifier for the hook instance
+
+It also exposes these properties:
+
+- `token`
+- `resumeUrl`
+- `cancelUrl`
+- `approvalPageUrl`
+
+When the hook may be mediated through an agent tool, include intent metadata:
+
+```ts
+run: async (_input, ctx) => {
+  const approval = ctx.createHook('approval', {
+    intent: 'human-decision',
+    prompt: 'Approve the refund?',
+    reason: 'Refunds above the policy threshold require approval.',
+  });
+
+  const result = await approval;
+  return { result };
+};
+```
+
+Example:
+
+```ts
+run: async (_input, ctx) => {
+  const approval = ctx.createHook('approval');
+
+  const token = await approval.token;
+  const resumeUrl = await approval.resumeUrl;
+
+  return {
+    token,
+    resumeUrl,
+  };
+};
+```
+
+You can also use the resumed payload in the workflow.
+
+If the external caller resumes the hook with structured data, `await approval` resolves to that payload:
+
+```ts
+run: async (_input, ctx) => {
+  const approval = ctx.createHook('approval');
+  const approvalPageUrl = await approval.approvalPageUrl;
+
+  // Send approvalPageUrl to a human or external system here.
+
+  const result = (await approval) as {
+    approved?: boolean;
+    reviewer?: string;
+    note?: string;
+  };
+
+  return {
+    approved: result.approved === true,
+    reviewer: result.reviewer ?? 'unknown',
+    note: result.note ?? '',
+    approvalPageUrl,
+  };
+};
+```
+
+You can also create hooks in a loop when the workflow should wait for repeated review until a condition is met:
+
+```ts
+run: async (_input, ctx) => {
+  let round = 1;
+  let latestNote = '';
+
+  while (true) {
+    const review = ctx.createHook(`approval-round-${round}`);
+    const result = (await review) as {
+      approved?: boolean;
+      note?: string;
+    };
+
+    latestNote = result.note ?? '';
+
+    if (result.approved === true) {
+      return {
+        approved: true,
+        rounds: round,
+        latestNote,
+      };
+    }
+
+    round += 1;
+  }
+};
+```
+
+## Workflow `ctx.workflowGlobals`
+
+```ts
+workflowGlobals: z.object({
+  tenantId: z.string(),
+}),
+run: async (_input, ctx) => {
+  return { tenantId: ctx.workflowGlobals.tenantId };
+};
+```
+
+Use this for typed workflow-wide runtime values.
+
+## Workflow `ctx.workflowId`
+
+```ts
+run: async (_input, ctx) => {
+  return { workflowId: ctx.workflowId };
+};
+```
+
+Use this when the workflow output or logs need the current run id.
+
+## Workflow `ctx.hasCredentialSet(id)`
+
+```ts
+run: async (input, ctx) => {
+  if (ctx.hasCredentialSet('slack')) {
+    await sendSlackMessage.run({
+      channel: input.channel,
+      text: input.summary,
+    });
+  }
+
+  return { ok: true };
+};
+```
+
+Use this for graceful degradation when a credential-backed branch is genuinely optional. Build analysis recognizes literal guards such as `ctx.hasCredentialSet('slack')` and treats matching credentials as conditional instead of required. Dynamic ids are not recognized.
+
+## Operation / Step `ctx.credentials`
+
+```ts
+run: async (_input, ctx) => {
+  return { apiKeyUsed: ctx.credentials.crmApi.apiKey };
+};
+```
+
+## Operation / Step `ctx.workflowGlobals`
+
+```ts
+run: async (_input, ctx) => {
+  return { tenantId: ctx.workflowGlobals.tenantId };
+};
+```
+
+## Operation / Step `ctx.attempt`, `ctx.maxAttempts`, and `ctx.stepId`
+
+```ts
+run: async (_input, ctx) => {
+  return {
+    attempt: ctx.attempt ?? 1,
+    maxAttempts: ctx.maxAttempts ?? 1,
+    stepId: ctx.stepId ?? 'unknown',
+  };
+};
+```
+
+Use these when operation behavior depends on retry state or when you want the step id in output or logs.
+
+## Public testing helpers
+
+Import these from `@keystrokehq/core/vitest`:
+
+- `keystrokeTestPlugin`
+- `createTestRuntime`
+- `createTestStepContext`
+- `createMockHook`
+
+### What they are used for
+
+- `keystrokeTestPlugin`: Vitest plugin that wires core test setup into the test process
+- `createTestRuntime`: build a full workflow test runtime with workflow context plus step execution metadata
+- `createTestStepContext`: build only the operation / step context for isolated tests
+- `createMockHook`: create an immediately resolving hook for tests that would otherwise block on `ctx.createHook(...)`
+
+Example:
+
+```ts
+import { createMockHook } from '@keystrokehq/core/vitest';
+
+const hook = createMockHook();
+await hook;
+const resumeUrl = await hook.resumeUrl;
+```

package/keystroke-workflow-authoring/references/source-map.md

@@ -0,0 +1,108 @@
+# Workflow Feature Map
+
+Use only the public imports a user repo can rely on:
+
+```ts
+import { Operation, Step, Workflow } from '@keystrokehq/core';
+import {
+  createMockHook,
+  createTestRuntime,
+  createTestStepContext,
+  keystrokeTestPlugin,
+} from '@keystrokehq/core/vitest';
+```
+
+`Operation`, `Step`, and `Tool` are aliases for the same class. In this workflow skill, prefer `Step` for examples and explanations, but `Operation` is equally valid for shared or integration-oriented code.
+
+## `Workflow` config fields
+
+- `id`
+- `name`
+- `description`
+- `author`
+- `version`
+- `tags`
+- `input`
+- `output`
+- `triggers`
+- `timeout`
+- `retries`
+- `workflowGlobals`
+- `run`
+
+## `Workflow` instance methods
+
+- `run(input, runtimeOrContextOrOptions?)`
+- `withTimeout(duration)`
+- `retry(policy)`
+- `describe()`
+- `toManifest()`
+
+### What they are used for
+
+- `run(...)`: execute the workflow directly
+- `withTimeout(...)`: create a new workflow instance with a different timeout
+- `retry(...)`: create a new workflow instance with a different retry policy
+- `describe()`: return a human-readable summary string
+- `toManifest()`: return the core manifest description
+
+Teach this distinction when it matters:
+- `workflow.toManifest()` returns the primitive-level core manifest
+- the build pipeline enriches that into the full built workflow manifest
+
+## `Workflow.run` context
+
+- `ctx.wait(duration)`
+- `ctx.createHook(name)`
+- `ctx.workflowGlobals`
+- `ctx.workflowId`
+
+## `Operation` / `Step` config fields
+
+- `name`
+- `description`
+- `input`
+- `output`
+- `timeout`
+- `tags`
+- `retries`
+- `workflowGlobals`
+- `credentialSets`
+- `needsApproval`
+- `run`
+
+## `Operation` / `Step` instance methods
+
+- `run(input, ctx?)`
+- `withTimeout(duration)`
+- `retry(policy)`
+- `configure(overrides)`
+- `mapInput(schema, fn)`
+- `mapOutput(schema, fn)`
+- `describe()`
+- `toManifest()`
+
+### What they are used for
+
+- `run(...)`: execute the operation directly
+- `withTimeout(...)`: create a new operation instance with a different timeout
+- `retry(...)`: create a new operation instance with a different retry policy
+- `configure(...)`: create a new operation instance with updated metadata such as description, timeout, retries, tags, or approval metadata
+- `mapInput(...)`: create a wrapper operation with a new input schema and input transformation
+- `mapOutput(...)`: create a wrapper operation with a new output schema and output transformation
+- `describe()`: return a human-readable summary string
+- `toManifest()`: return the operation manifest description
+
+## `Operation.run` / `Step.run` context
+
+- `ctx.credentials`
+- `ctx.workflowGlobals`
+- `ctx.attempt`
+- `ctx.maxAttempts`
+- `ctx.stepId`
+
+## Where to read next
+
+- `patterns.md` shows workflow and operation examples
+- `runtime-helpers.md` shows public context examples
+- `testing.md` shows public testing examples

package/keystroke-workflow-authoring/references/testing.md

@@ -0,0 +1,108 @@
+# Workflow Testing
+
+Read this file when the user asks how to test a Keystroke workflow or workflow-facing operation.
+
+Assume `helloWorkflow`, `accountSyncWorkflow`, `loadCustomer`, `paymentWebhook`, and `paymentWorkflow` are the workflow, operation, and trigger instances shown elsewhere in this skill.
+
+## Vitest setup
+
+`keystrokeTestPlugin()` adds the core test setup file to Vitest. Use it when you want normal `workflow.run(...)` and `step.run(...)` calls to work in tests without building custom harness code first.
+
+```ts
+import { defineConfig } from 'vitest/config';
+import { keystrokeTestPlugin } from '@keystrokehq/core/vitest';
+
+export default defineConfig({
+  plugins: [keystrokeTestPlugin()],
+});
+```
+
+## Test a workflow directly
+
+```ts
+import { expect, test } from 'vitest';
+
+test('returns the greeting', async () => {
+  await expect(helloWorkflow.run({ name: 'Ada' })).resolves.toEqual({
+    message: 'Hello, Ada!',
+  });
+});
+```
+
+## Test a workflow with globals or hooks
+
+`createTestRuntime()` builds both sides of the workflow test runtime:
+
+- `runtime.context` for the workflow `ctx`
+- `runtime.stepContext` for operation execution metadata such as credentials, retry info, and workflow globals
+
+Use it when a workflow test needs more than plain input data.
+
+```ts
+import { createMockHook, createTestRuntime } from '@keystrokehq/core/vitest';
+
+const runtime = createTestRuntime({
+  workflowGlobals: {
+    tenantId: 'tenant_123',
+  },
+  createHook: () => createMockHook(),
+});
+
+await accountSyncWorkflow.run(
+  { accountId: 'acct_123', waitForApproval: true },
+  runtime.context
+);
+```
+
+## Test a step directly
+
+`createTestStepContext()` is the smaller helper for operation unit tests. Use it when you want to call `step.run(...)` or `operation.run(...)` directly and provide only the runtime context values that operation reads.
+
+```ts
+import { createTestStepContext } from '@keystrokehq/core/vitest';
+
+const stepContext = createTestStepContext({
+  credentials: {
+    crmApi: {
+      apiKey: 'test-key',
+    },
+  },
+  workflowGlobals: {
+    tenantId: 'tenant_123',
+  },
+  attempt: 2,
+  maxAttempts: 4,
+  stepId: 'load-customer',
+});
+
+await loadCustomer.run({ customerId: 'cus_123' }, stepContext);
+```
+
+## Test a trigger transform
+
+Create a bound trigger by calling the trigger with `{ transform }`, then call `bound.transform?.(payload)` to verify the mapping from trigger payload to workflow input.
+
+```ts
+const bound = paymentWebhook({
+  transform: (payload) => ({
+    eventId: payload.id,
+    amount: payload.amount,
+  }),
+});
+
+const input = await bound.transform?.(
+  { id: 'evt_123', type: 'payment.completed', amount: 5000 }
+);
+
+expect(input).toEqual({ eventId: 'evt_123', amount: 5000 });
+await paymentWorkflow.run(input);
+```
+
+## What to test
+
+- workflow happy path
+- operation / step happy path
+- waits and hooks when they affect behavior
+- workflow globals validation
+- credential-backed operation behavior
+- bound trigger transforms when triggers are involved

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@keystrokehq/skills",
+  "version": "0.0.1",
+  "private": false,
+  "type": "module",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "files": [
+    "README.md",
+    "AGENTS-blurb.md",
+    "keystroke-workflow-authoring",
+    "keystroke-agent-authoring",
+    "keystroke-data-toolkit",
+    "keystroke-workflow-as-tool-debugging",
+    "keystroke-credential-binding",
+    "keystroke-trigger-authoring",
+    "keystroke-task-authoring",
+    "keystroke-cli-workspace"
+  ],
+  "scripts": {
+    "build": "node -e \"process.exit(0)\"",
+    "lint": "biome check ."
+  }
+}