@elevasis/sdk 1.9.0 → 1.10.0

package/dist/types/worker/index.d.ts

@@ -26,8 +26,27 @@
  *   Worker -> Parent:  { type: 'credential-request', id, name }
  *   Parent -> Worker:  { type: 'credential-result', id, provider?, credentials?, error?, code? }
  */
-import type { DeploymentSpec } from '../index.js';
+import type { DeploymentSpec, WorkflowDefinition } from '../index.js';
 export { platform, PlatformToolError } from './platform.js';
 export type { PlatformCredential } from './platform.js';
 export * from './adapters/index.js';
+export interface LogEntry {
+    level: 'debug' | 'info' | 'warn' | 'error';
+    message: string;
+    timestamp: string;
+    context?: Record<string, unknown>;
+}
+export declare function executeWorkflow(workflow: WorkflowDefinition, input: unknown, context: {
+    executionId: string;
+    organizationId: string;
+    organizationName: string;
+    sessionId?: string;
+    sessionTurnNumber?: number;
+    parentExecutionId?: string;
+    executionDepth: number;
+    adapters?: Record<string, unknown>;
+}): Promise<{
+    output: unknown;
+    logs: LogEntry[];
+}>;
 export declare function startWorker(org: DeploymentSpec): void;

package/dist/worker/index.js

@@ -5083,7 +5083,7 @@ function captureConsole(executionId, logs) {
     const timestamp = (/* @__PURE__ */ new Date()).toISOString();
     const entry = { level, message, timestamp, context: logContext };
     logs.push(entry);
-    parentPort.postMessage({
+    parentPort?.postMessage({
       type: "log",
       entry: { level, message, timestamp, executionId, context: logContext }
     });
@@ -5177,6 +5177,7 @@ async function executeWorkflow(workflow, input, context) {
           sessionTurnNumber: context.sessionTurnNumber,
           parentExecutionId: context.parentExecutionId,
           executionDepth: context.executionDepth,
+          adapters: context.adapters,
           store: /* @__PURE__ */ new Map(),
           logger: {
             debug: (msg) => console.log(`[debug] ${msg}`),
@@ -5434,4 +5435,4 @@ function startWorker(org) {
   });
 }
 
-export { PlatformToolError, acqDb, approval, createAdapter, createAnymailfinderAdapter, createApifyAdapter, createAttioAdapter, createDropboxAdapter, createGmailAdapter, createGoogleSheetsAdapter, createInstantlyAdapter, createMillionVerifierAdapter, createResendAdapter, createSignatureApiAdapter, createStripeAdapter, createTombaAdapter, crm, email, execution, list, llm, notifications, pdf, platform, projects, scheduler, startWorker, storage };
+export { PlatformToolError, acqDb, approval, createAdapter, createAnymailfinderAdapter, createApifyAdapter, createAttioAdapter, createDropboxAdapter, createGmailAdapter, createGoogleSheetsAdapter, createInstantlyAdapter, createMillionVerifierAdapter, createResendAdapter, createSignatureApiAdapter, createStripeAdapter, createTombaAdapter, crm, email, executeWorkflow, execution, list, llm, notifications, pdf, platform, projects, scheduler, startWorker, storage };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@elevasis/sdk",
-  "version": "1.9.0",
+  "version": "1.10.0",
   "description": "SDK for building Elevasis organization resources",
   "type": "module",
   "bin": {
@@ -14,6 +14,10 @@
     "./worker": {
       "types": "./dist/types/worker/index.d.ts",
       "import": "./dist/worker/index.js"
+    },
+    "./test-utils": {
+      "types": "./dist/test-utils/index.d.ts",
+      "import": "./dist/test-utils/index.js"
     }
   },
   "files": [
@@ -23,6 +27,8 @@
     "dist/types/worker/index.d.ts",
     "dist/types/worker/platform.d.ts",
     "dist/types/worker/adapters/",
+    "dist/test-utils/index.js",
+    "dist/test-utils/index.d.ts",
     "dist/cli.cjs",
     "reference/"
   ],
@@ -44,7 +50,7 @@
     "tsup": "^8.0.0",
     "typescript": "5.9.2",
     "zod": "^4.1.0",
-    "@repo/core": "0.9.0",
+    "@repo/core": "0.10.0",
     "@repo/typescript-config": "0.0.0"
   },
   "scripts": {

package/reference/_navigation.md

@@ -2,7 +2,7 @@
 
 Auto-generated from the package reference manifests.
 
-Package entries indexed: 43.
+Package entries indexed: 47.
 
 ## @elevasis/core / Core
 
@@ -40,6 +40,12 @@ Package entries indexed: 43.
 | --- | --- | --- | --- |
 | Worker Runtime | `runtime.mdx` | Worker runtime entrypoint, adapters, and platform execution surface. | (not specified) |
 
+## @elevasis/sdk / Testing
+
+| Resource | Location | Description | When to Load |
+| --- | --- | --- | --- |
+| Test Utils | `runtime.mdx` | Workflow runner, registry assertion, and typed adapter mocks for SDK consumers. | (not specified) |
+
 ## @elevasis/ui / Components
 
 | Resource | Location | Description | When to Load |
@@ -100,6 +106,14 @@ Package entries indexed: 43.
 | Provider UI | `packages/ui/src/provider/README.md` | Published provider UI entry for downstream applications. | (not specified) |
 | Elevasis Service Context | `packages/ui/src/provider/README.md` | Standalone service context and provider that supplies apiRequest, organizationId, and isReady to child components. | (not specified) |
 
+## @elevasis/ui / Testing
+
+| Resource | Location | Description | When to Load |
+| --- | --- | --- | --- |
+| Test Utils | `packages/ui/src/test-utils/README.md` | Published rendering helpers, auth mocks, MSW handlers, and test provider utilities. | (not specified) |
+| Test Utils Setup | `packages/ui/src/test-utils/README.md` | Vitest setup file for UI consumers using browser mocks and MSW. | (not specified) |
+| Test Utils Integration Setup | `packages/ui/src/test-utils/README.md` | Vitest setup file for integration tests that avoid MSW and use real network boundaries. | (not specified) |
+
 ## @elevasis/ui / Visual
 
 | Resource | Location | Description | When to Load |

package/reference/_reference-manifest.json

@@ -85,6 +85,20 @@
       "referencePath": "runtime.mdx",
       "publishedExportPath": "./dist/worker/index.js"
     },
+    {
+      "packageName": "@elevasis/sdk",
+      "packageDir": "packages/sdk",
+      "subpath": "./test-utils",
+      "kind": "subpath",
+      "title": "Test Utils",
+      "description": "Workflow runner, registry assertion, and typed adapter mocks for SDK consumers.",
+      "group": "Testing",
+      "order": 1,
+      "sourcePath": "packages/sdk/src/test-utils/index.ts",
+      "docPath": "apps/docs/content/docs/sdk/runtime.mdx",
+      "referencePath": "runtime.mdx",
+      "publishedExportPath": "./dist/test-utils/index.js"
+    },
     {
       "packageName": "@elevasis/ui",
       "packageDir": "packages/ui",
@@ -575,6 +589,48 @@
       "referencePath": "packages/ui/src/provider/README.md",
       "publishedExportPath": "./dist/provider/ElevasisServiceContext.js"
     },
+    {
+      "packageName": "@elevasis/ui",
+      "packageDir": "packages/ui",
+      "subpath": "./test-utils",
+      "kind": "subpath",
+      "title": "Test Utils",
+      "description": "Published rendering helpers, auth mocks, MSW handlers, and test provider utilities.",
+      "group": "Testing",
+      "order": 1,
+      "sourcePath": "packages/ui/src/test-utils/index.ts",
+      "docPath": "packages/ui/src/test-utils/README.md",
+      "referencePath": "packages/ui/src/test-utils/README.md",
+      "publishedExportPath": "./dist/test-utils/index.js"
+    },
+    {
+      "packageName": "@elevasis/ui",
+      "packageDir": "packages/ui",
+      "subpath": "./test-utils/setup",
+      "kind": "subpath",
+      "title": "Test Utils Setup",
+      "description": "Vitest setup file for UI consumers using browser mocks and MSW.",
+      "group": "Testing",
+      "order": 2,
+      "sourcePath": "packages/ui/src/test-utils/setup.ts",
+      "docPath": "packages/ui/src/test-utils/README.md",
+      "referencePath": "packages/ui/src/test-utils/README.md",
+      "publishedExportPath": "./dist/test-utils/setup.js"
+    },
+    {
+      "packageName": "@elevasis/ui",
+      "packageDir": "packages/ui",
+      "subpath": "./test-utils/setup-integration",
+      "kind": "subpath",
+      "title": "Test Utils Integration Setup",
+      "description": "Vitest setup file for integration tests that avoid MSW and use real network boundaries.",
+      "group": "Testing",
+      "order": 3,
+      "sourcePath": "packages/ui/src/test-utils/setup-integration.ts",
+      "docPath": "packages/ui/src/test-utils/README.md",
+      "referencePath": "packages/ui/src/test-utils/README.md",
+      "publishedExportPath": "./dist/test-utils/setup-integration.js"
+    },
     {
       "packageName": "@elevasis/ui",
       "packageDir": "packages/ui",

package/reference/claude-config/sync-notes/2026-04-24-test-utils-and-template-tests.md

@@ -0,0 +1,73 @@
+# Test Utils And Template Tests
+
+## Why this note exists
+
+This update adds meaningful package, template, and downstream test coverage while keeping ownership boundaries clear. Package-owned contracts live in package tests/test-utils; `_template` keeps scaffold smoke tests and examples; downstream projects keep custom tests for project-specific workflows and routes.
+
+The new package-level test-utils subpaths are being prepared in the monorepo packages:
+
+- `@elevasis/core/test-utils`
+- `@elevasis/ui/test-utils`
+- `@elevasis/sdk/test-utils`
+
+Until the bundled release train publishes those expanded package surfaces, `_template` keeps small local compatibility wrappers for tests that need the new helpers. Do not replace those wrappers with local `file:` dependencies.
+
+## Applies to
+
+All template-derived projects that sync from `external/_template`.
+
+Known affected projects: `nirvana-marketing`, `ZentaraHQ`.
+
+## Required actions
+
+### Step 1 -- Pull template changes via `/git-sync`
+
+Accept the new tests under sync-managed scaffold surfaces:
+
+- `ui/src/routes/__tests__/`
+- `core/types/**`
+- `core/config/**`
+- local core compatibility helpers under `core/test-utils/`
+
+Operations tests are intentionally narrower. Treat `operations/src/**` as project-owned runtime code. Only keep or add Operations tests in a downstream project when the project owns the workflow/module being tested. The template's email-notification tests are examples, not a requirement for every derived project.
+
+### Step 2 -- Run the expanded test chain
+
+From project root:
+
+```bash
+pnpm test
+```
+
+The root test script now runs `operations check` between UI and operations tests so resource-registry drift fails during ordinary test runs.
+
+### Step 3 -- Keep compatibility wrappers until the bundled release lands
+
+Do not delete any local compatibility wrapper that is still used by a project-owned custom test until the project has upgraded to package versions that publish the expanded test-utils subpaths.
+
+After the release train lands, projects can migrate local compatibility imports to:
+
+```ts
+import { renderWithProviders } from '@elevasis/ui/test-utils'
+import { makeProject } from '@elevasis/core/test-utils'
+import { runWorkflow } from '@elevasis/sdk/test-utils'
+```
+
+### Step 4 -- Adjust only for intentionally removed features
+
+If a derived project intentionally removed a feature route or workflow, skip or adjust the specific synced test case. For Operations, prefer project-owned tests that import package helpers over copied template workflow tests.
+
+## Verification
+
+- `pnpm -C ui test` passes.
+- `pnpm -C operations check` passes.
+- `pnpm -C operations test` passes.
+- `pnpm -C core test` passes.
+- `pnpm test` passes from project root.
+
+## Not handled by /git-sync
+
+- `/git-sync` does not publish or upgrade `@elevasis/*` package versions.
+- `/git-sync` does not remove compatibility wrappers after the release train.
+- `/git-sync` does not decide how a project-specific removed feature should be represented in tests.
+- `/git-sync` does not force template-only Operations example tests into downstream projects that do not own the matching workflow files.

package/reference/claude-config/sync-notes/2026-04-24-ui-consolidation-and-sdk-cli-train.md

@@ -32,7 +32,7 @@ Run from project root:
 pnpm up @elevasis/ui @elevasis/core @elevasis/sdk --latest
 ```
 
-Dep bumps are already written into `_template/ui/package.json` and `_template/operations/package.json` by the release train.
+Dep bumps are already written into `_template/ui/package.json`, `_template/operations/package.json`, and `_template/core/package.json` by the release train (`@elevasis/core` ^0.9.0, `@elevasis/ui` ^2.19.0, `@elevasis/sdk` ^1.9.0).
 
 ### Step 3 -- Replace inlined type defs with package imports
 

package/reference/packages/core/src/test-utils/README.md

@@ -2,12 +2,14 @@
 
 Published test helpers for downstream consumers of `@elevasis/core`.
 
-The public `@elevasis/core/test-utils` subpath is intentionally narrow. It exposes:
+The public `@elevasis/core/test-utils` subpath exposes:
 
 - `RLSTestContext` for dev-database RLS integration tests
 - `setupMatchMedia`, `setupResizeObserver`, and `setupBrowserMocks` for jsdom/browser test setup
-
-Internal monorepo fixtures and Vitest-specific mocks still exist under `packages/core/src/test-utils/`, but they are not part of the published package contract.
+- `TEST_USERS`, `TEST_ORGS`, `TEST_MEMBERSHIPS`, and related fixture factories
+- `createMockSupabaseClient`, `createMockWorkOSClient`, and related mocks
+- base entity factories such as `makeProject`, `makeDeal`, and `makeTask`
+- organization model/profile builders such as `makeOrganizationModel`, `makeInitializationState`, and `makeUserProfile`
 
 ## Published Usage
 
@@ -33,10 +35,3 @@ const ctx = new RLSTestContext()
 - `SUPABASE_ANON_KEY`
 - `SUPABASE_SERVICE_KEY`
 - `SUPABASE_JWT_SECRET`
-
-## Internal Scope
-
-The following folders remain implementation detail for the monorepo and are not published:
-
-- `fixtures/`
-- `mocks/`

package/reference/packages/ui/src/test-utils/README.md

@@ -0,0 +1,5 @@
+# UI Test Utilities
+
+Published test helpers for consumers that test Elevasis UI composition.
+
+Use `@elevasis/ui/test-utils` for provider-aware React rendering, WorkOS auth mocks, MSW handlers, and test query clients. Use `@elevasis/ui/test-utils/setup` or `@elevasis/ui/test-utils/setup-integration` from Vitest `setupFiles` when a consumer wants the shared browser and auth mocks.

package/reference/scaffold/operations/workflow-recipes.md

@@ -433,4 +433,97 @@ export const agents: never[] = []
 3. Import the group barrel in `operations/src/index.ts` and spread into `workflows`/`agents`.
 4. Run `pnpm -C operations check` to validate, then `pnpm -C operations deploy` to publish.
 
-**Note:** Use `.js` extensions in imports even though the source is TypeScript. The TypeScript compiler and esbuild bundler both require this for ESM interoperability.
+**Note:** Use `.js` extensions in imports even though the source is TypeScript. The TypeScript compiler and esbuild bundler both require this for ESM interoperability.
+
+---
+
+## 5. Testing Custom Workflows And UI
+
+Package-owned test helpers are the stable way to test custom downstream code. Do not copy template-only tests into a project unless the project owns the matching workflow, route, or component.
+
+After the bundled package release lands, use these public subpaths:
+
+```typescript
+import { makeProject } from '@elevasis/core/test-utils'
+import { renderWithProviders, mockAuthenticatedUser } from '@elevasis/ui/test-utils'
+import { assertResourceRegistry, mockNotifications, runWorkflow } from '@elevasis/sdk/test-utils'
+```
+
+### Workflow Smoke Test
+
+Use `runWorkflow` for project-owned workflows. This tests the workflow contract, step execution, and parsed output without deploying.
+
+```typescript
+import { describe, expect, it } from 'vitest'
+import { runWorkflow, mockNotifications } from '@elevasis/sdk/test-utils'
+import { emailNotification } from './index'
+import type { EmailNotificationOutput } from '@foundation/types'
+
+describe('emailNotification workflow', () => {
+  it('runs the notify step with a mocked notification adapter', async () => {
+    const notifications = mockNotifications({
+      create: { id: 'notification-1' }
+    })
+
+    const result = await runWorkflow<EmailNotificationOutput>(
+      emailNotification,
+      {
+        recipientEmail: 'jane@example.com',
+        recipientName: 'Jane',
+        subject: 'Action ready',
+        body: 'Your request has been processed.'
+      },
+      { adapters: { notification: notifications } }
+    )
+
+    expect(result.output.delivered).toBe(true)
+    expect(result.stepEvents.map((event) => event.stepId)).toContain('notify')
+  })
+})
+```
+
+### Registry Smoke Test
+
+Use `assertResourceRegistry` for a project-owned `operations/src/index.ts` manifest. Keep assertions generic unless the project intentionally owns a fixed workflow list.
+
+```typescript
+import { describe, expect, it } from 'vitest'
+import { assertResourceRegistry } from '@elevasis/sdk/test-utils'
+import org from './index'
+
+describe('operations registry', () => {
+  it('registers a valid operations manifest', () => {
+    const spec = assertResourceRegistry(org, { organizationName: 'Example Project' })
+    const workflows = spec.workflows ?? []
+
+    expect(workflows.length + (spec.agents?.length ?? 0)).toBeGreaterThan(0)
+    expect(new Set(workflows.map((workflow) => workflow.config.resourceId)).size).toBe(workflows.length)
+  })
+})
+```
+
+### UI And Core Fixtures
+
+Use `@elevasis/ui/test-utils` for route/component tests and `@elevasis/core/test-utils` for schema-compatible fixtures.
+
+```tsx
+import { describe, expect, it } from 'vitest'
+import { screen } from '@testing-library/react'
+import { makeProject } from '@elevasis/core/test-utils'
+import { mockAuthenticatedUser, renderWithProviders } from '@elevasis/ui/test-utils'
+import { ProjectCard } from './ProjectCard'
+
+describe('ProjectCard', () => {
+  it('renders a project fixture for an authenticated user', () => {
+    const project = makeProject({ name: 'Website Refresh' })
+
+    renderWithProviders(<ProjectCard project={project} />, {
+      auth: mockAuthenticatedUser()
+    })
+
+    expect(screen.getByText('Website Refresh')).toBeInTheDocument()
+  })
+})
+```
+
+Template tests are examples and smoke coverage. Downstream projects should keep custom tests close to the feature they validate, then consume these package helpers instead of copying scaffold internals.

package/reference/scaffold/recipes/add-a-feature.md

@@ -16,7 +16,7 @@ See [glossary.md](../reference/glossary.md) for term disambiguation throughout t
 A shell feature requires a `feature.id` in the org model's `features[]` array to gate it. You have two options:
 
 - **Reuse an existing feature** (e.g., `operations`, `monitoring`). The new shell module shares the on/off toggle with the existing feature entry. Fine for sub-modules within the same product area.
-- **Add a new feature object** -- add an entry to the `features[]` array in `foundations/config/organization-model.ts`. This is always a template-local change; no core package change is required.
+- **Add a new feature object** -- add an entry to the `features[]` array in `core/config/organization-model.ts`. This is always a template-local change; no core package change is required.
 
 For a genuinely new capability (e.g., `analytics`), you add a feature object to the defaults array and author a matching manifest.
 
@@ -26,7 +26,7 @@ See [glossary.md](../reference/glossary.md) under **Feature** (three contexts).
 
 ## 2. Update the organization model
 
-File: `foundations/config/organization-model.ts`
+File: `core/config/organization-model.ts`
 
 Add a new feature object to the `features[]` array passed to `defineOrganizationModel`.
 
@@ -63,7 +63,7 @@ Each field of the feature object:
 
 No domain entry or separate key resolver is needed. The `features[]` array is the sole source of truth.
 
-**Two-step pattern:** in a template-derived project, the `defineOrganizationModel` output is passed to `createFoundationOrganizationModel(override)` in `foundations/config/organization-model.ts`. The result exposes `.model`, `.canonical`, and `.homeLabel`. See `external/_template/foundations/config/organization-model.ts` for the canonical two-step example.
+**Two-step pattern:** in a template-derived project, the `defineOrganizationModel` output is passed to `createFoundationOrganizationModel(override)` in `core/config/organization-model.ts`. The result exposes `.model`, `.canonical`, and `.homeLabel`. See `external/_template/core/config/organization-model.ts` for the canonical two-step example.
 
 ---
 
@@ -154,5 +154,5 @@ pnpm -C ui dev
 
 - Feature appears in the nav sidebar.
 - Route is accessible and the subshell sidebar renders.
-- Toggle `features.enabled.analytics` to `false` in `foundations/config/organization-model.ts` and confirm the nav item disappears and the route redirects.
+- Toggle `features.enabled.analytics` to `false` in `core/config/organization-model.ts` and confirm the nav item disappears and the route redirects.
 - Check `FeatureGuard` by navigating directly to `/analytics` with the feature disabled.

package/reference/scaffold/recipes/add-a-resource.md

@@ -115,7 +115,7 @@ Full relationship and checkpoint types are defined in `@elevasis/sdk` (`Deployme
 
 ## 4. (Optional) Map to a domain
 
-To make the resource referenceable from the org model (so the Operations graph and Command View can link to it), add an entry to `resourceMappings` in `foundations/config/organization-model.ts`:
+To make the resource referenceable from the org model (so the Operations graph and Command View can link to it), add an entry to `resourceMappings` in `core/config/organization-model.ts`:
 
 ```ts
 resourceMappings: [

package/reference/scaffold/recipes/customize-organization-model.md

@@ -5,7 +5,7 @@ description: Annotated walkthrough for customizing the organization model in tem
 
 # Customize organization-model.ts
 
-`foundations/config/organization-model.ts` is the semantic contract between your UI runtime
+`core/config/organization-model.ts` is the semantic contract between your UI runtime
 and your platform operations. Every feature your users can access, every nav surface they can
 navigate to, and every resource backed by a workflow is declared here. The provider reads this
 contract at startup; everything downstream -- routing, gating, nav rendering -- derives from it.
@@ -366,7 +366,7 @@ Both sides must be consistent (schema validates bidirectionality):
 
 The organization model flows through the runtime in one direction:
 
-1. `foundations/config/organization-model.ts` calls `resolveOrganizationModel` at module load.
+1. `core/config/organization-model.ts` calls `resolveOrganizationModel` at module load.
    The resolved `canonicalOrganizationModel` is exported.
 2. `ui/src/routes/__root.tsx` imports `canonicalOrganizationModel` and passes it to
    `ElevasisFeaturesProvider` along with the `FEATURE_MANIFESTS` array.

package/reference/scaffold/recipes/gate-by-feature-or-admin.md

@@ -27,7 +27,7 @@ Do not substitute one for the other. `FeatureGuard` reads feature flags; `AdminG
 
 ## 2. Feature gate -- org level
 
-Ensure a feature object with the matching `id` exists in the org model. File: `foundations/config/organization-model.ts`.
+Ensure a feature object with the matching `id` exists in the org model. File: `core/config/organization-model.ts`.
 
 ```ts
 import { defineOrganizationModel, OPERATIONS_FEATURE_ID, SALES_FEATURE_ID } from '@elevasis/core/organization-model'
@@ -155,4 +155,4 @@ State matrix -- confirm each combination:
 | true                | (absent)        | non-admin | Admin-gated route redirects, admin nav hidden |
 | true                | (absent)        | admin     | Admin-gated route accessible, nav visible     |
 
-Check each gate independently: feature toggle in `foundations/config/organization-model.ts`, membership config in `org_memberships.config`, and admin status in the user profile.
+Check each gate independently: feature toggle in `core/config/organization-model.ts`, membership config in `org_memberships.config`, and admin status in the user profile.