@rigkit/engine 0.2.2 → 0.2.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rigkit/engine",
-  "version": "0.2.2",
+  "version": "0.2.4",
   "type": "module",
   "repository": {
     "type": "git",

package/src/authoring.ts

@@ -1,3 +1,4 @@
+import { RESERVED_WORKFLOW_OPERATION_IDS } from "./types.ts";
 import type {
   EnvResolver,
   RigkitConfigDefinition,
@@ -5,14 +6,14 @@ import type {
   OutputSchema,
   OutputSchemaValue,
   WorkflowDefinition,
-  WorkflowCreateDefinition,
-  WorkflowCreateHandler,
   WorkflowInputFieldDefinition,
   WorkflowInputShape,
   WorkflowOperationDefinition,
   WorkflowOperationInputBuilder,
   WorkflowOperationInputHelpers,
   WorkflowOperationOptions,
+  WorkflowWorkspaceOperationDefinition,
+  WorkflowWorkspaceOperationOptions,
   WorkflowNodeDefinition,
   WorkflowProviderDefinition,
   WorkflowProviderMap,
@@ -24,8 +25,8 @@ import type {
   WorkflowWorkspaceDefinition,
 } from "./types.ts";
 
-const reservedTaskContextKeys = new Set(["ctx", "runtime", "providers"]);
-const reservedHostOperationIds = new Set(["init", "doctor", "projects", "run", "ls", "help", "version", "completion"]);
+const reservedTaskContextKeys = new Set(["ctx", "runtime", "providers", "step"]);
+const reservedHostOperationIds = new Set<string>(RESERVED_WORKFLOW_OPERATION_IDS);
 
 const readEnv = (name: string, fallback?: string): string => {
   const value = process.env[name];
@@ -50,9 +51,17 @@ export function workflow<const Name extends string, const Providers extends Work
     providers: options.providers,
     sequence: <InputContext extends JsonObject = {}>(sequenceName: string) =>
       createSequence(app as unknown as WorkflowDefinition<string, Providers>, sequenceName, []),
-    task: (taskName: string, optionsOrHandler: WorkflowTaskOptions | WorkflowTaskHandler<Providers, {}, any>, maybeHandler?: WorkflowTaskHandler<Providers, {}, any>) =>
+    task: (
+      taskName: string,
+      optionsOrHandler: WorkflowTaskOptions | WorkflowTaskHandler<Providers, {}, never, any>,
+      maybeHandler?: WorkflowTaskHandler<Providers, {}, never, any>,
+    ) =>
       createTask(app as unknown as WorkflowDefinition<string, Providers>, taskName, optionsOrHandler as any, maybeHandler as any),
-    step: (taskName: string, optionsOrHandler: WorkflowTaskOptions | WorkflowTaskHandler<Providers, {}, any>, maybeHandler?: WorkflowTaskHandler<Providers, {}, any>) =>
+    step: (
+      taskName: string,
+      optionsOrHandler: WorkflowTaskOptions | WorkflowTaskHandler<Providers, {}, never, any>,
+      maybeHandler?: WorkflowTaskHandler<Providers, {}, never, any>,
+    ) =>
       createTask(app as unknown as WorkflowDefinition<string, Providers>, taskName, optionsOrHandler as any, maybeHandler as any),
   };
 
@@ -90,12 +99,11 @@ export function defineProvider<
   const ProviderId extends string,
   const Config extends object,
   Runtime = unknown,
-  WorkspaceContext extends object = object,
 >(
   providerId: ProviderId,
-  config: WorkflowProviderDefinition<ProviderId, Config, Runtime, WorkspaceContext>["config"],
+  config: WorkflowProviderDefinition<ProviderId, Config, Runtime>["config"],
   plugin?: unknown,
-): WorkflowProviderDefinition<ProviderId, Config, Runtime, WorkspaceContext> {
+): WorkflowProviderDefinition<ProviderId, Config, Runtime> {
   return {
     kind: "rigkit.provider",
     providerId,
@@ -120,14 +128,30 @@ export function isProviderDefinition(value: unknown): value is WorkflowProviderD
   return Boolean(value && typeof value === "object" && getKind(value) === "rigkit.provider");
 }
 
-function createSequence<Providers extends WorkflowProviderMap, InputContext extends JsonObject, OutputContext extends JsonObject>(
+function createSequence<
+  Providers extends WorkflowProviderMap,
+  InputContext extends JsonObject,
+  OutputContext extends JsonObject,
+  WorkspaceData extends object = JsonObject,
+  OperationIds extends string = never,
+  WorkspaceOperationIds extends string = never,
+  PreviousTaskIds extends string = never,
+>(
   app: WorkflowDefinition<string, Providers>,
   name: string,
   children: readonly WorkflowNodeDefinition<Providers, any, any>[],
-  workspace?: WorkflowWorkspaceDefinition<Providers, OutputContext>,
-  create?: WorkflowCreateDefinition<Providers, OutputContext>,
+  workspace?: WorkflowWorkspaceDefinition<Providers, OutputContext, any>,
   operations: readonly WorkflowOperationDefinition<Providers, any>[] = [],
-): WorkflowSequenceBuilder<Providers, InputContext, OutputContext> {
+  workspaceOperations: readonly WorkflowWorkspaceOperationDefinition<Providers, OutputContext, WorkspaceData, any>[] = [],
+): WorkflowSequenceBuilder<
+  Providers,
+  InputContext,
+  OutputContext,
+  WorkspaceData,
+  OperationIds,
+  WorkspaceOperationIds,
+  PreviousTaskIds
+> {
   const node = {
     kind: "rigkit.workflow-node" as const,
     nodeKind: "sequence" as const,
@@ -135,27 +159,27 @@ function createSequence<Providers extends WorkflowProviderMap, InputContext exte
     workflow: app,
     children,
     workspaceDefinition: workspace,
-    createDefinition: create,
     operations,
+    workspaceOperations,
     task: (
       taskName: string,
-      optionsOrHandler: WorkflowTaskOptions | WorkflowTaskHandler<Providers, OutputContext, any>,
-      maybeHandler?: WorkflowTaskHandler<Providers, OutputContext, any>,
+      optionsOrHandler: WorkflowTaskOptions | WorkflowTaskHandler<Providers, OutputContext, PreviousTaskIds, any>,
+      maybeHandler?: WorkflowTaskHandler<Providers, OutputContext, PreviousTaskIds, any>,
     ) => {
       const task = createTask(app, taskName, optionsOrHandler as any, maybeHandler as any);
-      return createSequence(app, name, [...children, task], workspace, create, operations);
+      return createSequence(app, name, [...children, task], workspace, operations, workspaceOperations);
     },
     step: (
       taskName: string,
-      optionsOrHandler: WorkflowTaskOptions | WorkflowTaskHandler<Providers, OutputContext, any>,
-      maybeHandler?: WorkflowTaskHandler<Providers, OutputContext, any>,
+      optionsOrHandler: WorkflowTaskOptions | WorkflowTaskHandler<Providers, OutputContext, PreviousTaskIds, any>,
+      maybeHandler?: WorkflowTaskHandler<Providers, OutputContext, PreviousTaskIds, any>,
     ) => {
       const task = createTask(app, taskName, optionsOrHandler as any, maybeHandler as any);
-      return createSequence(app, name, [...children, task], workspace, create, operations);
+      return createSequence(app, name, [...children, task], workspace, operations, workspaceOperations);
     },
     add: (child: WorkflowNodeDefinition<Providers, any, any>) => {
       assertSameWorkflow(app, child);
-      return createSequence(app, name, [...children, child], workspace, create, operations);
+      return createSequence(app, name, [...children, child], workspace, operations, workspaceOperations);
     },
     parallel: (branches: Record<string, WorkflowNodeDefinition<Providers, any, any>>) => {
       for (const [branchName, branch] of Object.entries(branches)) {
@@ -173,17 +197,40 @@ function createSequence<Providers extends WorkflowProviderMap, InputContext exte
         workflow: app,
         branches,
       };
-      return createSequence(app, name, [...children, parallelNode], workspace, create, operations);
+      return createSequence(app, name, [...children, parallelNode], workspace, operations, workspaceOperations);
+    },
+    workspace: (definition: WorkflowWorkspaceDefinition<Providers, OutputContext, any>) =>
+      createSequence(app, name, children, definition, operations, workspaceOperations),
+    operation: (id: string, options: WorkflowOperationOptions<Providers, any>) => {
+      const operation = createOperation(id, options);
+      assertUniqueOperationId(operations, operation.id, "Operation");
+      return createSequence(app, name, children, workspace, [...operations, operation], workspaceOperations);
+    },
+    workspaceOperation: (id: string, options: WorkflowWorkspaceOperationOptions<Providers, OutputContext, any, any>) => {
+      const operation = createWorkspaceOperation(id, options);
+      assertUniqueOperationId(workspaceOperations, operation.id, "Workspace operation");
+      return createSequence(app, name, children, workspace, operations, [...workspaceOperations, operation]);
     },
-    workspace: (definition: WorkflowWorkspaceDefinition<Providers, OutputContext>) =>
-      createSequence(app, name, children, definition, create, operations),
-    create: (handler: WorkflowCreateHandler<Providers, OutputContext, any>) =>
-      createSequence(app, name, children, workspace, { handler }, operations),
-    operation: (id: string, options: WorkflowOperationOptions<Providers, any>) =>
-      createSequence(app, name, children, workspace, create, [...operations, createOperation(id, options)]),
   };
 
-  return node as unknown as WorkflowSequenceBuilder<Providers, InputContext, OutputContext>;
+  return node as unknown as WorkflowSequenceBuilder<
+    Providers,
+    InputContext,
+    OutputContext,
+    WorkspaceData,
+    OperationIds,
+    WorkspaceOperationIds,
+    PreviousTaskIds
+  >;
+}
+
+function assertUniqueOperationId(
+  operations: readonly { id: string }[],
+  id: string,
+  label: string,
+): void {
+  if (!operations.some((operation) => operation.id === id)) return;
+  throw new Error(`${label} id ${id} is already defined`);
 }
 
 function createOperation<Providers extends WorkflowProviderMap, Input extends object>(
@@ -199,9 +246,6 @@ function createOperation<Providers extends WorkflowProviderMap, Input extends ob
     id: normalized,
     title: options.title,
     description: options.description,
-    createsWorkspace: options.createsWorkspace,
-    requiredHostMethods: normalizeHostMethodRequirements(options.requiredHostMethods),
-    requiredHostCapabilities: normalizeHostCapabilityRequirements(options.requiredHostCapabilities),
     input: typeof options.input === "function"
       ? options.input(createOperationInputHelpers())
       : options.input,
@@ -209,31 +253,30 @@ function createOperation<Providers extends WorkflowProviderMap, Input extends ob
   };
 }
 
-function normalizeHostMethodRequirements(
-  methods: WorkflowOperationOptions<any, any>["requiredHostMethods"],
-) {
-  return methods?.map((method) => {
-    const id = method.id.trim();
-    if (!id) throw new Error(`Host method requirements must have non-empty ids`);
-    return {
-      id,
-      ...(method.modes?.length ? { modes: [...method.modes] } : {}),
-    };
-  });
-}
-
-function normalizeHostCapabilityRequirements(
-  capabilities: WorkflowOperationOptions<any, any>["requiredHostCapabilities"],
-) {
-  return capabilities?.map((capability) => {
-    const id = capability.id.trim();
-    if (!id) throw new Error(`Host capability requirements must have non-empty ids`);
-    const schemaHash = capability.schemaHash?.trim();
-    return {
-      id,
-      ...(schemaHash ? { schemaHash } : {}),
-    };
-  });
+function createWorkspaceOperation<
+  Providers extends WorkflowProviderMap,
+  Context extends JsonObject,
+  Data extends JsonObject,
+  Input extends object,
+>(
+  id: string,
+  options: WorkflowWorkspaceOperationOptions<Providers, Context, Data, Input>,
+): WorkflowWorkspaceOperationDefinition<Providers, Context, Data, Input> {
+  const normalized = id.trim();
+  if (!normalized) throw new Error(`Workspace operation ids must be non-empty`);
+  if (normalized.includes("/")) throw new Error(`Workspace operation ids cannot contain "/"`);
+  if (reservedHostOperationIds.has(normalized)) {
+    throw new Error(`Workspace operation id ${normalized} is reserved by the Rigkit host`);
+  }
+  return {
+    id: normalized,
+    title: options.title,
+    description: options.description,
+    input: typeof options.input === "function"
+      ? options.input(createOperationInputHelpers())
+      : options.input,
+    run: options.run,
+  };
 }
 
 function createOperationInputHelpers(): WorkflowOperationInputHelpers {
@@ -287,15 +330,19 @@ function createOperationInputBuilder<Input extends object>(
   } as WorkflowOperationInputBuilder<Input>;
 }
 
-function createTask<Providers extends WorkflowProviderMap, InputContext extends JsonObject>(
+function createTask<
+  Providers extends WorkflowProviderMap,
+  InputContext extends JsonObject,
+  PreviousTaskIds extends string = string,
+>(
   app: WorkflowDefinition<string, Providers>,
   name: string,
-  optionsOrHandler: WorkflowTaskOptions | WorkflowTaskHandler<Providers, InputContext, any>,
-  maybeHandler?: WorkflowTaskHandler<Providers, InputContext, any>,
+  optionsOrHandler: WorkflowTaskOptions | WorkflowTaskHandler<Providers, InputContext, PreviousTaskIds, any>,
+  maybeHandler?: WorkflowTaskHandler<Providers, InputContext, PreviousTaskIds, any>,
 ): WorkflowTaskNode<Providers, InputContext, any> {
   const options = typeof optionsOrHandler === "function" ? undefined : optionsOrHandler;
   const handler = (typeof optionsOrHandler === "function" ? optionsOrHandler : maybeHandler) as
-    | WorkflowTaskHandler<Providers, InputContext, any>
+    | WorkflowTaskHandler<Providers, InputContext, PreviousTaskIds, any>
     | undefined;
   if (!handler) throw new Error(`Task ${name} is missing a handler`);
 

package/src/authoring.typecheck.ts

@@ -0,0 +1,87 @@
+import { sequence } from "./authoring.ts";
+
+sequence("normal-operation-ids")
+  .operation("open" as const, {
+    run: async () => null,
+  })
+  // @ts-expect-error duplicate operation ids are rejected for literal ids
+  .operation("open" as const, {
+    run: async () => null,
+  });
+
+sequence("workspace-operation-ids")
+  .step("prepare", async () => ({ ctx: { snapshotId: "snap-1" } }))
+  .workspace({
+    create: async ({ workflow, workspace }) => {
+      const snapshotId: string = workflow.ctx.snapshotId;
+      const name: string = workspace.name;
+      void snapshotId;
+      void name;
+      return { vmId: "vm-1", test: "ok" };
+    },
+    remove: async ({ workspace }) => {
+      const vmId: string = workspace.ctx.vmId;
+      const test: string = workspace.ctx.test;
+      void vmId;
+      void test;
+      // @ts-expect-error workspace context is read-only
+      workspace.ctx.vmId = "next";
+      // @ts-expect-error provider resources are not part of the workspace authoring API
+      workspace.resources;
+    },
+  })
+  .workspaceOperation("open-cmux" as const, {
+    run: async ({ workspace }) => {
+      const vmId: string = workspace.ctx.vmId;
+      void vmId;
+      // @ts-expect-error missing data properties are rejected
+      workspace.ctx.missing;
+      return null;
+    },
+  })
+  // @ts-expect-error duplicate workspace operation ids are rejected for literal ids
+  .workspaceOperation("open-cmux" as const, {
+    run: async () => null,
+  });
+
+sequence("typed-step-invalidation")
+  .step("github-auth", async () => ({ ctx: { token: "ok" } }))
+  .step("check-auth", async ({ step }) => {
+    const token: string = step.ctx.token;
+    void token;
+    return step.invalidate("github-auth");
+  });
+
+sequence("typed-step-invalidation-targets")
+  .step("github-auth", async () => ({ ctx: { token: "ok" } }))
+  .step("check-auth", async ({ step }) => {
+    // @ts-expect-error invalidation target must be a previous task id
+    return step.invalidate("missing-auth");
+  });
+
+sequence("duplicate-step-id")
+  .step("prepare" as const, async () => ({ ctx: { snapshotId: "snap-1" } }))
+  // @ts-expect-error duplicate task ids are rejected for literal ids
+  .step("prepare" as const, async ({ step }) => ({ ctx: step.ctx }));
+
+sequence("reserved-operation-id")
+  // @ts-expect-error reserved operation ids are rejected for literal ids
+  .operation("create" as const, {
+    run: async () => null,
+  });
+
+sequence("reserved-workspace-operation-id")
+  .workspace({
+    create: async () => ({}),
+    remove: async () => {},
+  })
+  // @ts-expect-error reserved workspace operation ids are rejected for literal ids
+  .workspaceOperation("remove" as const, {
+    run: async () => null,
+  });
+
+sequence("slash-operation-id")
+  // @ts-expect-error operation ids cannot contain slashes
+  .operation("workspace/open" as const, {
+    run: async () => null,
+  });

package/src/db/schema/core.ts

@@ -6,19 +6,15 @@ export const workspaces = sqliteTable(
   {
     id: text("id").primaryKey(),
     name: text("name").notNull(),
-    providerId: text("provider_id").notNull(),
     workflow: text("workflow").notNull(),
-    resourceId: text("resource_id").notNull(),
-    snapshotId: text("snapshot_id"),
-    sourceRef: text("source_ref_json", { mode: "json" }).$type<JsonValue>().notNull(),
-    context: text("context_json", { mode: "json" }).$type<Record<string, JsonValue>>().notNull(),
+    workflowCtx: text("workflow_ctx_json", { mode: "json" }).$type<Record<string, JsonValue>>().notNull(),
     createdAt: text("created_at").notNull(),
     updatedAt: text("updated_at").notNull(),
-    metadata: text("metadata_json", { mode: "json" }).$type<Record<string, JsonValue>>().notNull(),
+    ctx: text("ctx_json", { mode: "json" }).$type<Record<string, JsonValue>>().notNull(),
   },
   (table) => [
     uniqueIndex("workspaces_name_idx").on(table.name),
-    index("workspaces_provider_resource_idx").on(table.providerId, table.resourceId),
+    index("workspaces_workflow_idx").on(table.workflow),
   ],
 );