@lucern/sdk 0.2.0-alpha.7 → 0.2.0-alpha.9

package/src/workflowClient.ts

@@ -1,826 +0,0 @@
-import {
-  createGatewayRequestClient,
-  type GatewayClientConfig,
-  LucernApiError,
-  randomIdempotencyKey,
-  toQueryString,
-} from "./coreClient";
-import {
-  asListItems,
-  createListResult,
-  mapAliasedList,
-  mapGatewayData,
-  normalizeTopicQuery,
-  resolveTopicId,
-  withTopicAlias,
-} from "./sdkSurface";
-import type {
-  LensPerspectiveType,
-  LensPromptTemplateReference,
-  LensStatus,
-  LensTaskTemplate,
-  LensWorkflowTemplate,
-} from "./contracts/lensWorkflow";
-import type {
-  WorkflowAutoFixPolicy,
-  WorkflowProofArtifact,
-  WorkflowStaffingHint,
-} from "./contracts/workflowRuntime";
-import type {
-  AddWorktreeResponse,
-  CompleteTaskResponse,
-  CreateBranchResponse,
-  CreateLensResponse,
-  CreateTaskResponse,
-  JsonObject,
-  JsonValue,
-  LensTopicBindingResponse,
-  ListBranchesResponse,
-  ListLensesResponse,
-  ListTopicsResponse,
-  ListWorktreesResponse,
-  MergeWorktreeResponse,
-  OpenPullRequestResponse,
-  PushWorktreeResponse,
-  SwitchTopicContextResponse,
-  TopicIdentifierInput,
-  UpdateTaskResponse,
-  WorkflowBranchRecord,
-  WorkflowLensRecord,
-  WorkflowTopicRecord,
-  WorkflowWorktreeRecord,
-} from "./types";
-
-export { LucernApiError };
-export type { PlatformGatewaySuccess } from "./coreClient";
-export type {
-  AddWorktreeResponse,
-  CompleteTaskResponse,
-  CreateBranchResponse,
-  CreateLensResponse,
-  CreateTaskResponse,
-  LensTopicBindingResponse,
-  ListBranchesResponse,
-  ListLensesResponse,
-  ListTopicsResponse,
-  ListWorktreesResponse,
-  MergeWorktreeResponse,
-  OpenPullRequestResponse,
-  PushWorktreeResponse,
-  SwitchTopicContextResponse,
-  UpdateTaskResponse,
-} from "./types";
-
-/** Configuration for the workflow client. */
-export type WorkflowClientConfig = GatewayClientConfig;
-
-/** Lifecycle status of a workflow branch. */
-export type WorkflowBranchStatus = "dormant" | "active" | "archived";
-
-/** Lifecycle status of a workflow lens. */
-export type WorkflowLensStatus = LensStatus;
-
-/** Analytical perspective type for a lens overlay. */
-export type WorkflowLensPerspectiveType = LensPerspectiveType;
-
-/** Lifecycle status of a workflow worktree. */
-export type WorkflowWorktreeStatus =
-  | "planning"
-  | "active"
-  | "paused"
-  | "completed"
-  | "merged"
-  | "failed"
-  | "archived";
-
-/** Possible outcomes when merging worktree findings into the main belief line. */
-export type WorkflowMergeOutcome =
-  | "validated"
-  | "invalidated"
-  | "forked"
-  | "inconclusive";
-
-/** Input for creating a new workflow worktree. */
-export type AddWorktreeInput = {
-  title: string;
-  topicId?: string;
-  branchId?: string;
-  objective?: string;
-  hypothesis?: string;
-  beliefIds?: string[];
-  autoShape?: boolean;
-  domainPackId?: string;
-  executionOrder?: number;
-  dependsOn?: string[];
-  blocks?: string[];
-  gate?: string;
-  proofArtifacts?: WorkflowProofArtifact[];
-  staffingHint?: WorkflowStaffingHint | string;
-  lastReconciledAt?: number;
-  autoFixPolicy?: WorkflowAutoFixPolicy;
-} & TopicIdentifierInput;
-
-/** Input for merging worktree findings with belief confidence outcomes. */
-export type MergeInput = {
-  outcomes: Array<{
-    beliefId: string;
-    confidence: number;
-    rationale: string;
-  }>;
-  summary?: string;
-};
-
-/** Input for updating the beliefs and questions tracked by a worktree. */
-export type UpdateWorktreeTargetsInput = {
-  worktreeId: string;
-  addBeliefIds?: string[];
-  addQuestionIds?: string[];
-  removeBeliefIds?: string[];
-  removeQuestionIds?: string[];
-};
-
-/** Input for marking a worktree complete with recorded outcomes. */
-export type CompleteWorktreeInput = {
-  worktreeId: string;
-  keyFindings?: string[];
-  decisionsReached?: string[];
-  nextSteps?: string[];
-};
-
-/** Input for moving a worktree forward to its next phase. */
-export type AdvanceWorktreePhaseInput = {
-  worktreeId: string;
-};
-
-/** Input for forcing a worktree into a specific phase. */
-export type SetWorktreePhaseInput = {
-  worktreeId: string;
-  phase: string;
-};
-
-/** Input for patching arbitrary structured worktree state. */
-export type PatchWorktreeStateInput = {
-  worktreeId: string;
-  patch: JsonObject;
-};
-
-/** Input for batch-creating worktrees through the workflow surface. */
-export type BulkCreateWorktreesInput = {
-  worktrees: unknown[];
-};
-
-/** Input for listing accessible topic contexts. */
-export type ListTopicsInput = {
-  includeShared?: boolean;
-  limit?: number;
-};
-
-/** Input for switching the active topic context by name. */
-export type SwitchTopicContextInput = {
-  targetTopicName: string;
-};
-
-/** Input for creating a workflow task linked to a question or worktree. */
-export type CreateTaskInput = {
-  title: string;
-  topicId?: string;
-  taskType?: "research" | "interview" | "analysis" | "data_collection";
-  linkedQuestionId?: string;
-  linkedWorktreeId?: string;
-  linkedBeliefId?: string;
-  description?: string;
-  priority?: "low" | "medium" | "high" | "urgent";
-} & TopicIdentifierInput;
-
-/** Input for marking a workflow task as completed with an output summary. */
-export type CompleteTaskInput = {
-  outputSummary: string;
-  evidenceCreated?: boolean;
-};
-
-/** Input for partially updating an existing workflow task. */
-export type UpdateTaskInput = {
-  title?: string;
-  description?: string;
-  linkedBeliefId?: string;
-  linkedQuestionId?: string;
-  linkedWorktreeId?: string;
-  priority?: "critical" | "high" | "medium" | "low";
-  status?: "todo" | "in_progress" | "blocked" | "done";
-};
-
-function normalizeLensQuery<T extends { topicId?: string }>(
-  value: T
-) {
-  const topicId = resolveTopicId(value);
-  return {
-    ...value,
-    ...(topicId ? { topicId } : {}),
-  };
-}
-
-/**
- * Create the workflow client for lenses, legacy branches, worktrees, context,
- * and tasks.
- * @param config - Gateway transport configuration.
- * @returns An object with methods to manage branches, lenses, worktrees, topics, and tasks.
- */
-export function createWorkflowClient(config: WorkflowClientConfig = {}) {
-  const gateway = createGatewayRequestClient(config);
-  const client = {
-    /**
-     * List workflow branches for a topic scope.
-     */
-    async listBranches(query: {
-      topicId?: string;
-      status?: WorkflowBranchStatus;
-      limit?: number;
-    } & TopicIdentifierInput) {
-      return gateway.request<ListBranchesResponse>({
-        path: `/api/platform/v1/workflow/branches${toQueryString(
-          normalizeTopicQuery(query)
-        )}`,
-      }).then((response) =>
-        mapGatewayData(response, (data) =>
-          mapAliasedList<WorkflowBranchRecord, "branches">(data, "branches")
-        )
-      );
-    },
-
-    /**
-     * Create a workflow branch.
-     */
-    async createBranch(
-      input: {
-        name: string;
-        topicId?: string;
-        description?: string;
-        metadata?: JsonObject;
-      } & TopicIdentifierInput,
-      idempotencyKey?: string
-    ) {
-      return gateway.request<CreateBranchResponse>({
-        path: "/api/platform/v1/workflow/branches",
-        method: "POST",
-        body: normalizeTopicQuery(input),
-        idempotencyKey: idempotencyKey ?? randomIdempotencyKey(),
-      }).then((response) =>
-        mapGatewayData(response, (data) =>
-          withTopicAlias(data as Record<string, unknown>) as CreateBranchResponse
-        )
-      );
-    },
-
-    /**
-     * List reusable lenses for a workspace or topic scope.
-     */
-    async listLenses(query: {
-      workspaceId?: string;
-      topicId?: string;
-      status?: WorkflowLensStatus;
-      perspectiveType?: WorkflowLensPerspectiveType;
-    } & TopicIdentifierInput) {
-      return gateway.request<ListLensesResponse>({
-        path: `/api/platform/v1/workflow/lenses${toQueryString(
-          normalizeLensQuery(query)
-        )}`,
-      }).then((response) =>
-        mapGatewayData(response, (data) =>
-          mapAliasedList<WorkflowLensRecord, "lenses">(data, "lenses")
-        )
-      );
-    },
-
-    /**
-     * Create a reusable workflow lens.
-     */
-    async createLens(
-      input: {
-        name: string;
-        workspaceId?: string;
-        topicId?: string;
-        description?: string;
-        perspectiveType: WorkflowLensPerspectiveType;
-        promptTemplates?: LensPromptTemplateReference[];
-        workflowTemplates?: LensWorkflowTemplate[];
-        taskTemplates?: LensTaskTemplate[];
-        filterCriteria?: JsonObject;
-      } & TopicIdentifierInput,
-      idempotencyKey?: string
-    ) {
-      const payload = normalizeLensQuery(input);
-      return gateway.request<CreateLensResponse>({
-        path: "/api/platform/v1/workflow/lenses",
-        method: "POST",
-        body: payload as JsonObject,
-        idempotencyKey: idempotencyKey ?? randomIdempotencyKey(),
-      }).then((response) =>
-        mapGatewayData(response, (data) =>
-          withTopicAlias(data as Record<string, unknown>) as CreateLensResponse
-        )
-      );
-    },
-
-    /**
-     * Apply an existing lens to a topic.
-     */
-    async applyLensToTopic(
-      input: {
-        lensId: string;
-        topicId?: string;
-        metadata?: JsonObject;
-      } & TopicIdentifierInput,
-      idempotencyKey?: string
-    ) {
-      const payload = normalizeLensQuery(input);
-      return gateway.request<LensTopicBindingResponse>({
-        path: "/api/platform/v1/workflow/lens-bindings",
-        method: "POST",
-        body: payload,
-        idempotencyKey: idempotencyKey ?? randomIdempotencyKey(),
-      }).then((response) =>
-        mapGatewayData(response, (data) =>
-          withTopicAlias(data as Record<string, unknown>) as LensTopicBindingResponse
-        )
-      );
-    },
-
-    /**
-     * Remove an applied lens from a topic.
-     */
-    async removeLensFromTopic(
-      input: {
-        lensId: string;
-        topicId?: string;
-      } & TopicIdentifierInput,
-      idempotencyKey?: string
-    ) {
-      const topicId = resolveTopicId(input);
-      if (!topicId) {
-        throw new LucernApiError({
-          code: "INVALID_REQUEST",
-          message: "topicId is required",
-          status: 400,
-        });
-      }
-
-      return gateway.request<LensTopicBindingResponse>({
-        path: `/api/platform/v1/workflow/lens-bindings${toQueryString({
-          lensId: input.lensId,
-          topicId,
-        })}`,
-        method: "DELETE",
-        idempotencyKey: idempotencyKey ?? randomIdempotencyKey(),
-      }).then((response) =>
-        mapGatewayData(response, (data) =>
-          withTopicAlias(data as Record<string, unknown>) as LensTopicBindingResponse
-        )
-      );
-    },
-
-    /**
-     * List worktrees for a topic scope.
-     */
-    async listWorktrees(query: {
-      topicId?: string;
-      branchId?: string;
-      status?: WorkflowWorktreeStatus;
-      track?: string;
-      executionBand?: number;
-      limit?: number;
-    } & TopicIdentifierInput) {
-      const normalized = normalizeTopicQuery(query);
-      return gateway.request<ListWorktreesResponse>({
-        path: `/api/platform/v1/worktrees${toQueryString({
-          ...normalized,
-          track: query.track,
-          executionBand: query.executionBand,
-        })}`,
-      }).then((response) =>
-        mapGatewayData(response, (data) =>
-          mapAliasedList<WorkflowWorktreeRecord, "worktrees">(
-            data,
-            "worktrees"
-          )
-        )
-      );
-    },
-
-    /**
-     * List all worktrees across accessible topics.
-     */
-    async listAllWorktrees(query: {
-      status?: WorkflowWorktreeStatus;
-      track?: string;
-      executionBand?: number;
-      limit?: number;
-    } = {}) {
-      return gateway.request<ListWorktreesResponse>({
-        path: `/api/platform/v1/worktrees${toQueryString({
-          status: query.status,
-          track: query.track,
-          executionBand: query.executionBand,
-          limit: query.limit,
-        })}`,
-      }).then((response) =>
-        mapGatewayData(response, (data) => {
-          const record =
-            data && typeof data === "object" && !Array.isArray(data)
-              ? (data as Record<string, unknown>)
-              : {};
-          const list = mapAliasedList<WorkflowWorktreeRecord, "worktrees">(
-            data,
-            "worktrees"
-          );
-          return {
-            ...list,
-            ...(record.tracks &&
-            typeof record.tracks === "object" &&
-            !Array.isArray(record.tracks)
-              ? { tracks: record.tracks as Record<string, number> }
-              : {}),
-            ...(record.bands &&
-            typeof record.bands === "object" &&
-            !Array.isArray(record.bands)
-              ? { bands: record.bands as Record<string, number> }
-              : {}),
-          } as ListWorktreesResponse;
-        })
-      );
-    },
-
-    /**
-     * Create a workflow worktree.
-     */
-    async createWorktree(input: AddWorktreeInput, idempotencyKey?: string) {
-      return gateway.request<AddWorktreeResponse>({
-        path: "/api/platform/v1/worktrees",
-        method: "POST",
-        body: normalizeTopicQuery(input),
-        idempotencyKey: idempotencyKey ?? randomIdempotencyKey(),
-      }).then((response) =>
-        mapGatewayData(response, (data) =>
-          withTopicAlias(data as Record<string, unknown>) as AddWorktreeResponse
-        )
-      );
-    },
-
-    /**
-     * @deprecated Use createWorktree.
-     */
-    async addWorktree(input: AddWorktreeInput, idempotencyKey?: string) {
-      return client.createWorktree(input, idempotencyKey);
-    },
-
-    /**
-     * Merge a worktree into the main belief line.
-     */
-    async merge(
-      worktreeId: string,
-      input: MergeInput,
-      idempotencyKey?: string
-    ) {
-      return gateway.request<MergeWorktreeResponse>({
-        path: `/api/platform/v1/worktrees/${encodeURIComponent(worktreeId)}/merge`,
-        method: "POST",
-        body: input,
-        idempotencyKey: idempotencyKey ?? randomIdempotencyKey(),
-      });
-    },
-
-    /**
-     * Activate a planning worktree.
-     */
-    async activateWorktree(worktreeId: string, idempotencyKey?: string) {
-      return gateway.request<AddWorktreeResponse>({
-        path: `/api/platform/v1/worktrees/${encodeURIComponent(worktreeId)}/activate`,
-        method: "POST",
-        idempotencyKey: idempotencyKey ?? randomIdempotencyKey(),
-      }).then((response) =>
-        mapGatewayData(response, (data) =>
-          withTopicAlias(data as Record<string, unknown>) as AddWorktreeResponse
-        )
-      );
-    },
-
-    /**
-     * Update targeted beliefs/questions for a worktree.
-     */
-    async updateWorktreeTargets(
-      input: UpdateWorktreeTargetsInput,
-      idempotencyKey?: string
-    ) {
-      const { worktreeId, ...body } = input;
-      return gateway.request<AddWorktreeResponse>({
-        path: `/api/platform/v1/worktrees/${encodeURIComponent(worktreeId)}/targets`,
-        method: "POST",
-        body,
-        idempotencyKey: idempotencyKey ?? randomIdempotencyKey(),
-      }).then((response) =>
-        mapGatewayData(response, (data) =>
-          withTopicAlias(data as Record<string, unknown>) as AddWorktreeResponse
-        )
-      );
-    },
-
-    /**
-     * Mark a worktree record complete.
-     */
-    async completeWorktree(
-      input: CompleteWorktreeInput,
-      idempotencyKey?: string
-    ) {
-      return gateway.request<Record<string, unknown>>({
-        path: "/api/platform/v1/worktrees/complete",
-        method: "POST",
-        body: input,
-        idempotencyKey: idempotencyKey ?? randomIdempotencyKey(),
-      });
-    },
-
-    /**
-     * Advance a worktree to its next lifecycle phase.
-     */
-    async advanceWorktreePhase(
-      input: AdvanceWorktreePhaseInput,
-      idempotencyKey?: string
-    ) {
-      return gateway.request<Record<string, unknown>>({
-        path: "/api/platform/v1/worktrees/advance-phase",
-        method: "POST",
-        body: input,
-        idempotencyKey: idempotencyKey ?? randomIdempotencyKey(),
-      });
-    },
-
-    /**
-     * Force a worktree into a specific lifecycle phase.
-     */
-    async setWorktreePhase(
-      input: SetWorktreePhaseInput,
-      idempotencyKey?: string
-    ) {
-      return gateway.request<Record<string, unknown>>({
-        path: "/api/platform/v1/worktrees/set-phase",
-        method: "POST",
-        body: input,
-        idempotencyKey: idempotencyKey ?? randomIdempotencyKey(),
-      });
-    },
-
-    /**
-     * Patch opaque worktree state for orchestration flows.
-     */
-    async patchWorktreeState(
-      input: PatchWorktreeStateInput,
-      idempotencyKey?: string
-    ) {
-      return gateway.request<Record<string, unknown>>({
-        path: "/api/platform/v1/worktrees/patch-state",
-        method: "POST",
-        body: input,
-        idempotencyKey: idempotencyKey ?? randomIdempotencyKey(),
-      });
-    },
-
-    /**
-     * Batch create worktree records.
-     */
-    async bulkCreateWorktrees(
-      input: BulkCreateWorktreesInput,
-      idempotencyKey?: string
-    ) {
-      return gateway.request<Record<string, unknown>>({
-        path: "/api/platform/v1/worktrees/bulk",
-        method: "POST",
-        body: input as unknown as JsonObject,
-        idempotencyKey: idempotencyKey ?? randomIdempotencyKey(),
-      });
-    },
-
-    /**
-     * Open a pull request for a worktree.
-     */
-    async openPullRequest(
-      worktreeId: string,
-      input: {
-        summary: string;
-        reviewers?: string[];
-        status?:
-          | "pending_review"
-          | "changes_requested"
-          | "approved"
-          | "blocked";
-      },
-      idempotencyKey?: string
-    ) {
-      return gateway.request<OpenPullRequestResponse>({
-        path: `/api/platform/v1/workflow/worktrees/${encodeURIComponent(worktreeId)}/pull-request`,
-        method: "POST",
-        body: input,
-        idempotencyKey: idempotencyKey ?? randomIdempotencyKey(),
-      });
-    },
-
-    /**
-     * Push scored worktree findings into another context.
-     */
-    async push(
-      worktreeId: string,
-      input: {
-        targetContext: string;
-        beliefIds?: string[];
-        metadata?: JsonObject;
-      },
-      idempotencyKey?: string
-    ) {
-      return gateway.request<PushWorktreeResponse>({
-        path: `/api/platform/v1/workflow/worktrees/${encodeURIComponent(worktreeId)}/push`,
-        method: "POST",
-        body: input,
-        idempotencyKey: idempotencyKey ?? randomIdempotencyKey(),
-      });
-    },
-
-    /**
-     * List accessible topic contexts.
-     */
-    async listTopics(query: ListTopicsInput = {}) {
-      return gateway.request<ListTopicsResponse>({
-        path: `/api/platform/v1/workflow/topics${toQueryString({
-          includeShared:
-            typeof query.includeShared === "boolean"
-              ? query.includeShared
-                ? "true"
-                : "false"
-              : undefined,
-          limit: query.limit,
-        })}`,
-      }).then((response) =>
-        mapGatewayData(response, (data) => {
-          const items = asListItems<WorkflowTopicRecord>(data, "topics").map(
-            (item) =>
-              withTopicAlias(
-                item as Record<string, unknown>
-              ) as WorkflowTopicRecord
-          );
-          const record =
-            data && typeof data === "object"
-              ? (data as Record<string, unknown>)
-              : {};
-          return {
-            ...record,
-            ...createListResult(items, "topics"),
-            total:
-              typeof record.total === "number" ? record.total : items.length,
-          } as ListTopicsResponse;
-        })
-      );
-    },
-
-    /**
-     * Switch the active context by topic or project name.
-     */
-    async switchTopicContext(
-      input: SwitchTopicContextInput,
-      idempotencyKey?: string
-    ) {
-      return gateway.request<SwitchTopicContextResponse>({
-        path: "/api/platform/v1/workflow/topics/switch",
-        method: "POST",
-        body: {
-          targetTopicName: input.targetTopicName,
-        },
-        idempotencyKey: idempotencyKey ?? randomIdempotencyKey(),
-      }).then((response) =>
-        mapGatewayData(response, (data) =>
-          withTopicAlias(
-            data as Record<string, unknown>
-          ) as SwitchTopicContextResponse
-        )
-      );
-    },
-
-    /**
-     * Create a workflow task.
-     */
-    async createTask(input: CreateTaskInput, idempotencyKey?: string) {
-      return gateway.request<CreateTaskResponse>({
-        path: "/api/platform/v1/workflow/tasks",
-        method: "POST",
-        body: normalizeTopicQuery(input),
-        idempotencyKey: idempotencyKey ?? randomIdempotencyKey(),
-      });
-    },
-
-    /**
-     * Complete a workflow task.
-     */
-    async completeTask(
-      taskId: string,
-      input: CompleteTaskInput,
-      idempotencyKey?: string
-    ) {
-      return gateway.request<CompleteTaskResponse>({
-        path: `/api/platform/v1/workflow/tasks/${encodeURIComponent(taskId)}/complete`,
-        method: "POST",
-        body: input,
-        idempotencyKey: idempotencyKey ?? randomIdempotencyKey(),
-      });
-    },
-
-    /**
-     * Update a workflow task.
-     */
-    async updateTask(
-      taskId: string,
-      input: UpdateTaskInput,
-      idempotencyKey?: string
-    ) {
-      return gateway.request<UpdateTaskResponse>({
-        path: `/api/platform/v1/workflow/tasks/${encodeURIComponent(taskId)}`,
-        method: "PATCH",
-        body: input,
-        idempotencyKey: idempotencyKey ?? randomIdempotencyKey(),
-      });
-    },
-
-    /**
-     * @deprecated Use createBranch.
-     */
-    async createPillar(
-      input: {
-        name: string;
-        topicId?: string;
-        description?: string;
-        metadata?: JsonObject;
-      } & TopicIdentifierInput,
-      idempotencyKey?: string
-    ) {
-      return client.createBranch(input, idempotencyKey);
-    },
-
-    /**
-     * @deprecated Use addWorktree.
-     */
-    async createSprint(
-      input: {
-        title: string;
-        topicId?: string;
-        branchId?: string;
-        hypothesis?: string;
-        beliefIds?: string[];
-      } & TopicIdentifierInput,
-      idempotencyKey?: string
-    ) {
-      return client.createWorktree(input, idempotencyKey);
-    },
-
-    /**
-     * @deprecated Use merge.
-     */
-    async completeSprint(
-      worktreeId: string,
-      input: MergeInput,
-      idempotencyKey?: string
-    ) {
-      return client.merge(worktreeId, input, idempotencyKey);
-    },
-
-    /**
-     * @deprecated Use openPullRequest.
-     */
-    async requestReview(
-      worktreeId: string,
-      input: {
-        summary: string;
-        reviewers?: string[];
-        status?:
-          | "pending_review"
-          | "changes_requested"
-          | "approved"
-          | "blocked";
-      },
-      idempotencyKey?: string
-    ) {
-      return client.openPullRequest(worktreeId, input, idempotencyKey);
-    },
-
-    /**
-     * @deprecated Use push.
-     */
-    async publishFindings(
-      worktreeId: string,
-      input: {
-        targetContext: string;
-        beliefIds?: string[];
-        metadata?: JsonObject;
-      },
-      idempotencyKey?: string
-    ) {
-      return client.push(worktreeId, input, idempotencyKey);
-    },
-  };
-
-  return client;
-}