@hexclave/js 1.0.70 → 1.0.72

package/src/lib/hexclave-app/apps/implementations/admin-app-impl.ts

@@ -25,6 +25,7 @@ import { AdminProjectPermission, AdminProjectPermissionDefinition, AdminProjectP
 import type { PlanUsage } from "../../plan-usage";
 import { AdminOwnedProject, AdminProject, AdminProjectUpdateOptions, PushConfigOptions, adminProjectUpdateOptionsToCrud } from "../../projects";
 import type { AdminSessionReplay, AdminSessionReplayChunk, ListSessionReplayChunksOptions, ListSessionReplayChunksResult, ListSessionReplaysOptions, ListSessionReplaysResult, SessionReplayAllEventsResult } from "../../session-replays";
+import { AdminWorkflow, AdminWorkflowRun, AdminWorkflowRunDetails, AdminWorkflowRunsFilter, AdminWorkflowSyncResult, AdminWorkflowUpgradeResult, AdminWorkflowVersion, adminWorkflowFromCrud, adminWorkflowRunDetailsFromCrud, adminWorkflowRunFromCrud, adminWorkflowSyncResultFromCrud, adminWorkflowVersionFromCrud, isWorkflowRunDetailsJson } from "../../workflows";
 import { ManagedEmailProviderListItem, ManagedEmailProviderSetupResult, ManagedEmailProviderStatus, EmailOutboxUpdateOptions, StackAdminApp, StackAdminAppConstructorOptions } from "../interfaces/admin-app";
 import { clientVersion, createCache, getDefaultExtraRequestHeaders, getDefaultProjectId, getDefaultPublishableClientKey, getDefaultSecretServerKey, getDefaultSuperSecretAdminKey, resolveApiUrls, resolveConstructorOptions } from "./common";
 import { _HexclaveServerAppImplIncomplete } from "./server-app-impl";
@@ -97,6 +98,9 @@ export class _HexclaveAdminAppImplIncomplete<HasTokenStore extends boolean, Proj
   private readonly _adminEmailDraftsCache = createCache(async () => {
     return await this._interface.listInternalEmailDrafts();
   });
+  private readonly _adminWorkflowsCache = createCache(async () => {
+    return await this._interface.listWorkflows();
+  });
   private readonly _adminTeamPermissionDefinitionsCache = createCache(async () => {
     return await this._interface.listTeamPermissionDefinitions();
   });
@@ -477,6 +481,121 @@ export class _HexclaveAdminAppImplIncomplete<HasTokenStore extends boolean, Proj
     }));
   }
 
+  // ─── Workflows (internal-project gated; see the Workflows v1 spec) ───────
+
+  async listWorkflows(): Promise<AdminWorkflow[]> {
+    const crud = Result.orThrow(await this._adminWorkflowsCache.getOrWait([], "write-only"));
+    return crud.map(adminWorkflowFromCrud);
+  }
+
+  async createWorkflow(options: { id: string, displayName?: string, source: string }): Promise<AdminWorkflowSyncResult> {
+    const result = await this._interface.createWorkflow({
+      id: options.id,
+      display_name: options.displayName,
+      source: options.source,
+    });
+    await this._adminWorkflowsCache.refresh([]);
+    return adminWorkflowSyncResultFromCrud(result);
+  }
+
+  async updateWorkflowSource(workflowId: string, source: string): Promise<AdminWorkflowSyncResult> {
+    const result = await this._interface.updateWorkflowSource(workflowId, source);
+    await this._adminWorkflowsCache.refresh([]);
+    return adminWorkflowSyncResultFromCrud(result);
+  }
+
+  async deleteWorkflow(workflowId: string): Promise<void> {
+    await this._interface.deleteWorkflow(workflowId);
+    await this._adminWorkflowsCache.refresh([]);
+  }
+
+  async listWorkflowVersions(workflowId: string): Promise<AdminWorkflowVersion[]> {
+    return (await this._interface.listWorkflowVersions(workflowId)).map(adminWorkflowVersionFromCrud);
+  }
+
+  async listWorkflowRuns(workflowId: string, filter: AdminWorkflowRunsFilter & { includeState: true }): Promise<{ runs: AdminWorkflowRunDetails[], nextCursor: string | null }>;
+  async listWorkflowRuns(workflowId: string, filter?: AdminWorkflowRunsFilter): Promise<{ runs: AdminWorkflowRun[], nextCursor: string | null }>;
+  async listWorkflowRuns(workflowId: string, filter: AdminWorkflowRunsFilter = {}): Promise<{ runs: AdminWorkflowRun[], nextCursor: string | null }> {
+    if (filter.includeState === true) {
+      const result = await this._interface.listWorkflowRuns(workflowId, {
+        state: filter.state,
+        version: filter.version,
+        run_key: filter.runKey,
+        cursor: filter.cursor,
+        limit: filter.limit,
+        include_state: true,
+      });
+      return {
+        runs: result.runs.map((run) => adminWorkflowRunDetailsFromCrud(
+          isWorkflowRunDetailsJson(run)
+            ? run
+            : throwErr("Workflow runs response omitted state after include_state=true"),
+        )),
+        nextCursor: result.next_cursor,
+      };
+    }
+    const result = await this._interface.listWorkflowRuns(workflowId, {
+      state: filter.state,
+      version: filter.version,
+      run_key: filter.runKey,
+      cursor: filter.cursor,
+      limit: filter.limit,
+    });
+    return {
+      runs: result.runs.map(adminWorkflowRunFromCrud),
+      nextCursor: result.next_cursor,
+    };
+  }
+
+  async getWorkflowRun(runId: string): Promise<AdminWorkflowRunDetails> {
+    return adminWorkflowRunDetailsFromCrud(await this._interface.getWorkflowRun(runId));
+  }
+
+  async cancelWorkflowRuns(workflowId: string, filter: { runKey?: string, runId?: string, state?: "queued" | "running" | "sleeping", version?: number } = {}): Promise<{ canceledCount: number }> {
+    const result = await this._interface.cancelWorkflowRuns(workflowId, {
+      run_key: filter.runKey,
+      run_id: filter.runId,
+      state: filter.state,
+      version: filter.version,
+    });
+    await this._adminWorkflowsCache.refresh([]);
+    return { canceledCount: result.canceled_count };
+  }
+
+  async upgradeWorkflowRuns(workflowId: string, options: { toVersion: number, runKey?: string, fromVersion?: number }): Promise<AdminWorkflowUpgradeResult> {
+    const result = await this._interface.upgradeWorkflowRuns(workflowId, {
+      to_version: options.toVersion,
+      run_key: options.runKey,
+      from_version: options.fromVersion,
+    });
+    return {
+      upgradedCount: result.upgraded_count,
+      skipped: result.skipped.map((skip) => ({
+        runId: skip.run_id,
+        runKey: skip.run_key,
+        fromVersion: skip.from_version,
+        diagnostic: {
+          reason: skip.diagnostic.reason,
+          suspendedStepKey: skip.diagnostic.suspended_step_key,
+          foundStepKey: skip.diagnostic.found_step_key,
+          consumedStepKeys: skip.diagnostic.consumed_step_keys,
+          unconsumedStepKeys: skip.diagnostic.unconsumed_step_keys,
+          details: skip.diagnostic.details,
+        },
+      })),
+    };
+  }
+
+  async retryWorkflowRun(runId: string): Promise<void> {
+    await this._interface.retryWorkflowRun(runId);
+    await this._adminWorkflowsCache.refresh([]);
+  }
+
+  async sendWorkflowEvent(name: string, data?: unknown): Promise<{ eventId: string }> {
+    const result = await this._interface.sendWorkflowEvent(name, data ?? null);
+    return { eventId: result.event_id };
+  }
+
   async listEmailDrafts(): Promise<{ id: string, displayName: string, themeId: string | undefined | false, tsxSource: string, sentAt: Date | null }[]> {
     const crud = Result.orThrow(await this._adminEmailDraftsCache.getOrWait([], "write-only"));
     return crud.map((draft) => ({

package/src/lib/hexclave-app/apps/implementations/client-app-impl.cross-domain.test.ts

@@ -535,7 +535,7 @@ describe("StackClientApp cross-domain auth", () => {
     }
 
     const errorUrl = new URL(redirectedUrl);
-    expect(errorUrl.origin).toBe(`https://${projectId}.built-with-stack-auth.com`);
+    expect(errorUrl.origin).toBe(`https://${projectId}.built-with-hexclave.com`);
     expect(errorUrl.pathname).toBe("/handler/error");
     expect(errorUrl.searchParams.get("errorCode")).toBe("SIGN_UP_REJECTED");
     expect(errorUrl.searchParams.get("message")).toBe("Your sign up was rejected by an administrator's sign-up rule.");
@@ -715,7 +715,7 @@ describe("StackClientApp cross-domain auth", () => {
     redirectBackUrl.searchParams.set("hexclave_cross_domain_code_challenge", handoffCodeChallenge);
     redirectBackUrl.searchParams.set("hexclave_cross_domain_after_callback_redirect_url", handoffAfterCallbackRedirect);
 
-    const arrivalUrl = new URL(`https://${projectId}.built-with-stack-auth.com/handler/sign-in`);
+    const arrivalUrl = new URL(`https://${projectId}.built-with-hexclave.com/handler/sign-in`);
     arrivalUrl.searchParams.set("after_auth_return_to", redirectBackUrl.toString());
     arrivalUrl.searchParams.set("hexclave_cross_domain_state", handoffState);
     arrivalUrl.searchParams.set("hexclave_cross_domain_code_challenge", handoffCodeChallenge);
@@ -754,7 +754,7 @@ describe("StackClientApp cross-domain auth", () => {
         .mockResolvedValue(crossDomainAuthorizeRedirect);
 
       // All redirect-back query params were dropped before the after-sign-in redirect.
-      windowMock.location.href = `https://${projectId}.built-with-stack-auth.com/handler/sign-in`;
+      windowMock.location.href = `https://${projectId}.built-with-hexclave.com/handler/sign-in`;
 
       const redirectUrl = await clientApp[hexclaveAppInternalsSymbol].getRedirectToHandlerUrl("afterSignIn");
 

package/src/lib/hexclave-app/apps/implementations/client-app-impl.ts

@@ -59,6 +59,7 @@ import { EditableTeamMemberProfile, ReceivedTeamInvitation, SentTeamInvitation,
 import { buildCliAuthConfirmUrl, getHostedHandlerUrl, isHostedHandlerUrlForProject, resolveHandlerUrls } from "../../url-targets";
 import { augmentUrlWithPersistedRedirectBackState, saveRedirectBackStateFromUrl } from "./redirect-back-state";
 import { recordRedirectAndThrowIfLoopDetected } from "./redirect-loop-breaker";
+import { scopePasskeyAuthenticationToHostname, scopePasskeyRegistrationToHostname } from "../../passkey-rp-id";
 import { ActiveSession, Auth, BaseUser, CurrentUser, InternalUserExtra, OAuthProvider, ProjectCurrentUser, SyncedPartialUser, TokenPartialUser, UserExtra, UserUpdateOptions, userUpdateOptionsToCrud, withUserDestructureGuard } from "../../users";
 import { StackClientApp, StackClientAppConstructorOptions, StackClientAppJson } from "../interfaces/client-app";
 import { _HexclaveAdminAppImplIncomplete } from "./admin-app-impl";
@@ -2233,12 +2234,11 @@ export class _HexclaveClientAppImplIncomplete<HasTokenStore extends boolean, Pro
 
         const { options_json, code } = initiationResult.data;
 
-        // HACK: Override the rpID to be the actual domain
-        if (options_json.rp.id !== "THIS_VALUE_WILL_BE_REPLACED.example.com") {
-          throw new HexclaveAssertionError(`Expected returned RP ID from server to equal sentinel, but found ${options_json.rp.id}`);
-        }
-
-        options_json.rp.id = hostname;
+        // Passkeys intentionally stay scoped to the hostname where they were
+        // registered. In particular, passkeys created on the legacy hosted
+        // components domain continue to work there but are not carried over to
+        // a replacement hosted domain.
+        scopePasskeyRegistrationToHostname(options_json, hostname);
 
         let attResp;
         try {
@@ -3425,11 +3425,10 @@ export class _HexclaveClientAppImplIncomplete<HasTokenStore extends boolean, Pro
 
         const { options_json, code } = initiationResult.data;
 
-        // HACK: Override the rpID to be the actual domain
-        if (options_json.rpId !== "THIS_VALUE_WILL_BE_REPLACED.example.com") {
-          throw new HexclaveAssertionError(`Expected returned RP ID from server to equal sentinel, but found ${options_json.rpId}`);
-        }
-        options_json.rpId = window.location.hostname;
+        // Keep authentication scoped to the current hostname. This deliberately
+        // does not add cross-domain compatibility for passkeys created on a
+        // previous hosted components domain.
+        scopePasskeyAuthenticationToHostname(options_json, window.location.hostname);
 
         const authentication_response = await startAuthentication({ optionsJSON: options_json });
         return await this._interface.signInWithPasskey({ authentication_response, code }, session);

package/src/lib/hexclave-app/apps/implementations/server-app-impl.ts

@@ -35,6 +35,7 @@ import { Customer, CustomerProductsList, CustomerProductsRequestOptions, InlineP
 import { DataVaultStore } from "../../data-vault";
 import { EmailDeliveryInfo, SendEmailOptions } from "../../email";
 import { NotificationCategory } from "../../notification-categories";
+import { scopePasskeyRegistrationToHostname } from "../../passkey-rp-id";
 import { AdminProjectPermissionDefinition, AdminTeamPermission, AdminTeamPermissionDefinition } from "../../permissions";
 import { EditableTeamMemberProfile, ReceivedTeamInvitation, SentTeamInvitation, ServerListTeamsOptions, ServerListUsersOptions, ServerTeam, ServerTeamCreateOptions, ServerTeamUpdateOptions, ServerTeamUser, Team, serverTeamCreateOptionsToCrud, serverTeamUpdateOptionsToCrud } from "../../teams";
 import { ProjectCurrentServerUser, ServerOAuthProvider, ServerUser, ServerUserCreateOptions, ServerUserUpdateOptions, serverUserCreateOptionsToCrud, serverUserUpdateOptionsToCrud, withUserDestructureGuard } from "../../users";
@@ -780,7 +781,6 @@ export class _HexclaveServerAppImplIncomplete<HasTokenStore extends boolean, Pro
         return providers.find((p) => p.id === id) ?? null;
       },
       async registerPasskey(options?: { hostname?: string }): Promise<Result<undefined, KnownErrors["PasskeyRegistrationFailed"] | KnownErrors["PasskeyWebAuthnError"]>> {
-        // TODO remove duplicated code between this and the function in client-app-impl.ts
         const hostname = options?.hostname || (await app._getCurrentUrl())?.hostname;
         if (!hostname) {
           throw new HexclaveAssertionError("hostname must be provided if the Stack App does not have a redirect method");
@@ -795,12 +795,7 @@ export class _HexclaveServerAppImplIncomplete<HasTokenStore extends boolean, Pro
 
         const { options_json, code } = initiationResult.data;
 
-        // HACK: Override the rpID to be the actual domain
-        if (options_json.rp.id !== "THIS_VALUE_WILL_BE_REPLACED.example.com") {
-          throw new HexclaveAssertionError(`Expected returned RP ID from server to equal sentinel, but found ${options_json.rp.id}`);
-        }
-
-        options_json.rp.id = hostname;
+        scopePasskeyRegistrationToHostname(options_json, hostname);
 
         let attResp;
         try {

package/src/lib/hexclave-app/apps/interfaces/admin-app.ts

@@ -14,6 +14,7 @@ import { InternalApiKey, InternalApiKeyCreateOptions, InternalApiKeyFirstView }
 import { AdminProjectPermission, AdminProjectPermissionDefinition, AdminProjectPermissionDefinitionCreateOptions, AdminProjectPermissionDefinitionUpdateOptions, AdminTeamPermission, AdminTeamPermissionDefinition, AdminTeamPermissionDefinitionCreateOptions, AdminTeamPermissionDefinitionUpdateOptions } from "../../permissions";
 import type { PlanUsage } from "../../plan-usage";
 import { AdminProject } from "../../projects";
+import type { AdminWorkflow, AdminWorkflowRun, AdminWorkflowRunDetails, AdminWorkflowRunsFilter, AdminWorkflowSyncResult, AdminWorkflowUpgradeResult, AdminWorkflowVersion } from "../../workflows";
 import { _HexclaveAdminAppImpl } from "../implementations";
 import { StackServerApp, StackServerAppConstructorOptions } from "./server-app";
 
@@ -60,6 +61,7 @@ export type ManagedEmailProviderListItem = {
 
 import type { AdminSessionReplay, ListSessionReplayChunksOptions, ListSessionReplayChunksResult, ListSessionReplaysOptions, ListSessionReplaysResult, SessionReplayAllEventsResult } from "../../session-replays";
 export type { AdminSessionReplay, AdminSessionReplayChunk, ListSessionReplaysOptions, ListSessionReplaysResult, ListSessionReplayChunksOptions, ListSessionReplayChunksResult, SessionReplayAllEventsResult } from "../../session-replays";
+export type { AdminWorkflow, AdminWorkflowDivergenceDiagnostic, AdminWorkflowRun, AdminWorkflowRunDetails, AdminWorkflowRunsFilter, AdminWorkflowRunState, AdminWorkflowStep, AdminWorkflowStepAttempt, AdminWorkflowSyncResult, AdminWorkflowTrigger, AdminWorkflowUpgradeResult, AdminWorkflowVersion } from "../../workflows";
 
 
 /** @deprecated Use `HexclaveAdminAppConstructorOptions` from the `@hexclave/*` package instead — same symbol, new brand name. See https://docs.hexclave.com/migration. */
@@ -83,6 +85,7 @@ export type StackAdminApp<HasTokenStore extends boolean = boolean, ProjectId ext
   & AsyncStoreProperty<"emailPreview", [{ themeId?: string | null | false, themeTsxSource?: string, templateId?: string, templateTsxSource?: string }], string, false>
   & AsyncStoreProperty<"emailTemplates", [], { id: string, displayName: string, themeId?: string, tsxSource: string }[], true>
   & AsyncStoreProperty<"emailDrafts", [], { id: string, displayName: string, themeId: string | undefined | false, tsxSource: string, sentAt: Date | null }[], true>
+  & AsyncStoreProperty<"workflows", [], AdminWorkflow[], true>
   & AsyncStoreProperty<"stripeAccountInfo", [], { account_id: string, charges_enabled: boolean, details_submitted: boolean, payouts_enabled: boolean } | null, false>
   & AsyncStoreProperty<
     "transactions",
@@ -138,6 +141,22 @@ export type StackAdminApp<HasTokenStore extends boolean = boolean, ProjectId ext
     createEmailTemplate(displayName: string): Promise<{ id: string }>,
     deleteEmailTemplate(id: string): Promise<void>,
 
+    // Workflows (internal-project gated; see the Workflows v1 spec). The
+    // management verbs live on the admin app only in v1.
+    createWorkflow(options: { id: string, displayName?: string, source: string }): Promise<AdminWorkflowSyncResult>,
+    updateWorkflowSource(workflowId: string, source: string): Promise<AdminWorkflowSyncResult>,
+    deleteWorkflow(workflowId: string): Promise<void>,
+    listWorkflowVersions(workflowId: string): Promise<AdminWorkflowVersion[]>,
+    listWorkflowRuns: {
+      (workflowId: string, filter: AdminWorkflowRunsFilter & { includeState: true }): Promise<{ runs: AdminWorkflowRunDetails[], nextCursor: string | null }>,
+      (workflowId: string, filter?: AdminWorkflowRunsFilter): Promise<{ runs: AdminWorkflowRun[], nextCursor: string | null }>,
+    },
+    getWorkflowRun(runId: string): Promise<AdminWorkflowRunDetails>,
+    cancelWorkflowRuns(workflowId: string, filter?: { runKey?: string, runId?: string, state?: "queued" | "running" | "sleeping", version?: number }): Promise<{ canceledCount: number }>,
+    upgradeWorkflowRuns(workflowId: string, options: { toVersion: number, runKey?: string, fromVersion?: number }): Promise<AdminWorkflowUpgradeResult>,
+    retryWorkflowRun(runId: string): Promise<void>,
+    sendWorkflowEvent(name: string, data?: unknown): Promise<{ eventId: string }>,
+
     setupPayments(): Promise<{ url: string }>,
     createStripeWidgetAccountSession(): Promise<{ client_secret: string }>,
     getPaymentMethodConfigs(): Promise<{ configId: string, methods: Array<{ id: string, name: string, enabled: boolean, available: boolean, overridable: boolean }> } | null>,

package/src/lib/hexclave-app/index.ts

@@ -45,6 +45,21 @@ export type {
   EmailOutboxUpdateOptions
 } from "./apps/interfaces/admin-app";
 
+export type {
+  AdminWorkflow,
+  AdminWorkflowDivergenceDiagnostic,
+  AdminWorkflowRun,
+  AdminWorkflowRunDetails,
+  AdminWorkflowRunsFilter,
+  AdminWorkflowRunState,
+  AdminWorkflowStep,
+  AdminWorkflowStepAttempt,
+  AdminWorkflowSyncResult,
+  AdminWorkflowTrigger,
+  AdminWorkflowUpgradeResult,
+  AdminWorkflowVersion
+} from "./workflows";
+
 export type {
   ProjectConfig
 } from "./project-configs";

package/src/lib/hexclave-app/passkey-rp-id.test.ts

@@ -0,0 +1,43 @@
+
+//===========================================
+// THIS FILE IS AUTO-GENERATED FROM TEMPLATE. DO NOT EDIT IT DIRECTLY UNLESS YOU ALSO EDIT THE CORRESPONDING FILE IN packages/template
+//===========================================
+import { describe, expect, it } from "vitest";
+import { scopePasskeyAuthenticationToHostname, scopePasskeyRegistrationToHostname } from "./passkey-rp-id";
+
+const passkeyRpIdSentinel = "THIS_VALUE_WILL_BE_REPLACED.example.com";
+
+describe.each([
+  "project-id.built-with-hexclave.com",
+  "project-id.built-with-stack-auth.com",
+])("passkeys on %s", (hostname) => {
+  it("scopes registration to the current hostname", () => {
+    const options = { rp: { id: passkeyRpIdSentinel } };
+
+    scopePasskeyRegistrationToHostname(options, hostname);
+
+    expect(options.rp.id).toBe(hostname);
+  });
+
+  it("scopes authentication to the current hostname", () => {
+    const options = { rpId: passkeyRpIdSentinel };
+
+    scopePasskeyAuthenticationToHostname(options, hostname);
+
+    expect(options.rpId).toBe(hostname);
+  });
+});
+
+it("rejects registration options without the server sentinel", () => {
+  expect(() => scopePasskeyRegistrationToHostname(
+    { rp: { id: "unexpected.example.com" } },
+    "project-id.built-with-hexclave.com",
+  )).toThrow("Expected returned RP ID from server to equal sentinel");
+});
+
+it("rejects authentication options without the server sentinel", () => {
+  expect(() => scopePasskeyAuthenticationToHostname(
+    { rpId: "unexpected.example.com" },
+    "project-id.built-with-hexclave.com",
+  )).toThrow("Expected returned RP ID from server to equal sentinel");
+});

package/src/lib/hexclave-app/passkey-rp-id.ts

@@ -0,0 +1,27 @@
+
+//===========================================
+// THIS FILE IS AUTO-GENERATED FROM TEMPLATE. DO NOT EDIT IT DIRECTLY UNLESS YOU ALSO EDIT THE CORRESPONDING FILE IN packages/template
+//===========================================
+import { HexclaveAssertionError } from "@hexclave/shared/dist/utils/errors";
+
+const passkeyRpIdSentinel = "THIS_VALUE_WILL_BE_REPLACED.example.com";
+
+export function scopePasskeyRegistrationToHostname(
+  options: { rp: { id?: string } },
+  hostname: string,
+): void {
+  if (options.rp.id !== passkeyRpIdSentinel) {
+    throw new HexclaveAssertionError(`Expected returned RP ID from server to equal sentinel, but found ${options.rp.id}`);
+  }
+  options.rp.id = hostname;
+}
+
+export function scopePasskeyAuthenticationToHostname(
+  options: { rpId?: string },
+  hostname: string,
+): void {
+  if (options.rpId !== passkeyRpIdSentinel) {
+    throw new HexclaveAssertionError(`Expected returned RP ID from server to equal sentinel, but found ${options.rpId}`);
+  }
+  options.rpId = hostname;
+}

package/src/lib/hexclave-app/workflows.test.ts

@@ -0,0 +1,28 @@
+
+//===========================================
+// THIS FILE IS AUTO-GENERATED FROM TEMPLATE. DO NOT EDIT IT DIRECTLY UNLESS YOU ALSO EDIT THE CORRESPONDING FILE IN packages/template
+//===========================================
+import type { WorkflowVersionJson } from "@hexclave/shared/dist/interface/workflows";
+import { describe, expect, it } from "vitest";
+import { adminWorkflowVersionFromCrud } from "./workflows";
+
+describe("adminWorkflowVersionFromCrud", () => {
+  it("preserves the deployment source hash", () => {
+    const version: WorkflowVersionJson = {
+      workflow_id: "daily-report",
+      version: 3,
+      source: "export default 1",
+      source_hash: "0123456789abcdef",
+      runtime_env_version: "v1",
+      is_latest: true,
+      in_flight_runs: 2,
+      created_at_millis: 1234,
+    };
+
+    expect(adminWorkflowVersionFromCrud(version)).toMatchObject({
+      workflowId: "daily-report",
+      version: 3,
+      sourceHash: "0123456789abcdef",
+    });
+  });
+});

package/src/lib/hexclave-app/workflows.ts

@@ -0,0 +1,245 @@
+
+//===========================================
+// THIS FILE IS AUTO-GENERATED FROM TEMPLATE. DO NOT EDIT IT DIRECTLY UNLESS YOU ALSO EDIT THE CORRESPONDING FILE IN packages/template
+//===========================================
+import type {
+  WorkflowDivergenceDiagnosticJson,
+  WorkflowRunDetailsJson,
+  WorkflowRunJson,
+  WorkflowSummaryJson,
+  WorkflowSyncResultJson,
+  WorkflowVersionJson,
+} from "@hexclave/shared/dist/interface/workflows";
+
+// SDK-side (camelCase) types + converters for the workflows admin surface.
+// The wire types live in @hexclave/shared/dist/interface/workflows; these
+// mirror them 1:1 so the dashboard never touches snake_case.
+
+export type AdminWorkflowTrigger =
+  | { type: "event", eventType: string }
+  | { type: "schedule", cron: string, timezone: string };
+
+export type AdminWorkflow = {
+  id: string,
+  displayName: string,
+  latestVersion: number,
+  triggers: AdminWorkflowTrigger[],
+  stats: {
+    activeRuns: number,
+    sleepingRuns: number,
+    failed7d: number,
+    runVolume14d: number[],
+  },
+  createdAtMillis: number,
+  lastDeployedAtMillis: number,
+};
+
+export type AdminWorkflowRunState = "queued" | "running" | "sleeping" | "completed" | "failed" | "canceled";
+
+export type AdminWorkflowDivergenceDiagnostic = {
+  reason: WorkflowDivergenceDiagnosticJson["reason"],
+  suspendedStepKey: string | null,
+  foundStepKey: string | null,
+  consumedStepKeys: string[],
+  unconsumedStepKeys: string[],
+  details: string,
+};
+
+export type AdminWorkflowRun = {
+  id: string,
+  workflowId: string,
+  runKey: string | null,
+  state: AdminWorkflowRunState,
+  version: number,
+  triggerType: string,
+  triggerSummary: string,
+  currentStepId: string | null,
+  stepsRecorded: number,
+  errorSummary: string | null,
+  failureKind: "user" | "platform" | null,
+  lastUpgradeDivergence: AdminWorkflowDivergenceDiagnostic | null,
+  createdAtMillis: number,
+  completedAtMillis: number | null,
+  nextWakeAtMillis: number | null,
+};
+
+export type AdminWorkflowStep = {
+  stepKey: string,
+  stepId: string,
+  kind: "run" | "sleep",
+  result: unknown,
+  resultSizeBytes: number,
+  attempts: number,
+  executedAtVersion: number,
+  elapsedMs: number | null,
+  createdAtMillis: number,
+};
+
+export type AdminWorkflowStepAttempt = {
+  stepKey: string,
+  stepId: string,
+  /** 0 for the original execution; incremented by each manual retry of the run. */
+  retryEpoch: number,
+  attempt: number,
+  outcome: "succeeded" | "failed",
+  error: { name: string, message: string, stack?: string } | null,
+  failureKind: "user" | "platform" | null,
+  logs: string | null,
+  startedAtMillis: number,
+  finishedAtMillis: number,
+};
+
+export type AdminWorkflowRunDetails = AdminWorkflowRun & {
+  triggerPayload: unknown,
+  steps: AdminWorkflowStep[],
+  stepAttempts: AdminWorkflowStepAttempt[],
+};
+
+export type AdminWorkflowVersion = {
+  workflowId: string,
+  version: number,
+  sourceHash: string,
+  source: string,
+  runtimeEnvVersion: string,
+  isLatest: boolean,
+  inFlightRuns: number,
+  createdAtMillis: number,
+};
+
+export type AdminWorkflowSyncResult = {
+  workflowId: string,
+  version: number,
+  created: boolean,
+  inFlightRunsOnOlderVersions: number,
+};
+
+export type AdminWorkflowUpgradeResult = {
+  upgradedCount: number,
+  skipped: {
+    runId: string,
+    runKey: string | null,
+    fromVersion: number,
+    diagnostic: AdminWorkflowDivergenceDiagnostic,
+  }[],
+};
+
+export type AdminWorkflowRunsFilter = {
+  state?: AdminWorkflowRunState,
+  version?: number,
+  runKey?: string,
+  cursor?: string,
+  limit?: number,
+  /** Include each run's memoized steps and attempt history. */
+  includeState?: boolean,
+};
+
+export function adminWorkflowFromCrud(crud: WorkflowSummaryJson): AdminWorkflow {
+  return {
+    id: crud.id,
+    displayName: crud.display_name,
+    latestVersion: crud.latest_version,
+    triggers: crud.triggers.map((trigger) => trigger.type === "event"
+      ? { type: "event", eventType: trigger.event_type }
+      : { type: "schedule", cron: trigger.cron, timezone: trigger.timezone }),
+    stats: {
+      activeRuns: crud.stats.active_runs,
+      sleepingRuns: crud.stats.sleeping_runs,
+      failed7d: crud.stats.failed_7d,
+      runVolume14d: crud.stats.run_volume_14d,
+    },
+    createdAtMillis: crud.created_at_millis,
+    lastDeployedAtMillis: crud.last_deployed_at_millis,
+  };
+}
+
+function adminDivergenceFromCrud(crud: WorkflowDivergenceDiagnosticJson | null): AdminWorkflowDivergenceDiagnostic | null {
+  if (crud == null) return null;
+  return {
+    reason: crud.reason,
+    suspendedStepKey: crud.suspended_step_key,
+    foundStepKey: crud.found_step_key,
+    consumedStepKeys: crud.consumed_step_keys,
+    unconsumedStepKeys: crud.unconsumed_step_keys,
+    details: crud.details,
+  };
+}
+
+export function adminWorkflowRunFromCrud(crud: WorkflowRunJson): AdminWorkflowRun {
+  return {
+    id: crud.id,
+    workflowId: crud.workflow_id,
+    runKey: crud.run_key,
+    state: crud.state,
+    version: crud.version,
+    triggerType: crud.trigger_type,
+    triggerSummary: crud.trigger_summary,
+    currentStepId: crud.current_step_id,
+    stepsRecorded: crud.steps_recorded,
+    errorSummary: crud.error_summary,
+    failureKind: crud.failure_kind,
+    lastUpgradeDivergence: adminDivergenceFromCrud(crud.last_upgrade_divergence),
+    createdAtMillis: crud.created_at_millis,
+    completedAtMillis: crud.completed_at_millis,
+    nextWakeAtMillis: crud.next_wake_at_millis,
+  };
+}
+
+export function isWorkflowRunDetailsJson(crud: WorkflowRunJson): crud is WorkflowRunDetailsJson {
+  return "trigger_payload" in crud
+    && "steps" in crud
+    && Array.isArray(crud.steps)
+    && "step_attempts" in crud
+    && Array.isArray(crud.step_attempts);
+}
+
+export function adminWorkflowRunDetailsFromCrud(crud: WorkflowRunDetailsJson): AdminWorkflowRunDetails {
+  return {
+    ...adminWorkflowRunFromCrud(crud),
+    triggerPayload: crud.trigger_payload,
+    steps: crud.steps.map((step) => ({
+      stepKey: step.step_key,
+      stepId: step.step_id,
+      kind: step.kind,
+      result: step.result,
+      resultSizeBytes: step.result_size_bytes,
+      attempts: step.attempts,
+      executedAtVersion: step.executed_at_version,
+      elapsedMs: step.elapsed_ms,
+      createdAtMillis: step.created_at_millis,
+    })),
+    stepAttempts: crud.step_attempts.map((attempt) => ({
+      stepKey: attempt.step_key,
+      stepId: attempt.step_id,
+      retryEpoch: attempt.retry_epoch,
+      attempt: attempt.attempt,
+      outcome: attempt.outcome,
+      error: attempt.error,
+      failureKind: attempt.failure_kind,
+      logs: attempt.logs,
+      startedAtMillis: attempt.started_at_millis,
+      finishedAtMillis: attempt.finished_at_millis,
+    })),
+  };
+}
+
+export function adminWorkflowVersionFromCrud(crud: WorkflowVersionJson): AdminWorkflowVersion {
+  return {
+    workflowId: crud.workflow_id,
+    version: crud.version,
+    sourceHash: crud.source_hash,
+    source: crud.source,
+    runtimeEnvVersion: crud.runtime_env_version,
+    isLatest: crud.is_latest,
+    inFlightRuns: crud.in_flight_runs,
+    createdAtMillis: crud.created_at_millis,
+  };
+}
+
+export function adminWorkflowSyncResultFromCrud(crud: WorkflowSyncResultJson): AdminWorkflowSyncResult {
+  return {
+    workflowId: crud.workflow_id,
+    version: crud.version,
+    created: crud.created,
+    inFlightRunsOnOlderVersions: crud.in_flight_runs_on_older_versions,
+  };
+}