@rigkit/engine 0.2.10 → 0.2.11

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Rigkit contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "@rigkit/engine",
-  "version": "0.2.10",
+  "version": "0.2.11",
+  "license": "MIT",
   "type": "module",
   "repository": {
     "type": "git",

package/src/engine.test.ts

@@ -11,7 +11,7 @@ import type {
   ProviderRuntimeContext,
   WorkflowProviderController,
 } from "./provider/types.ts";
-import type { DevMachineEvent, ExecResult, JsonValue } from "./types.ts";
+import type { DevMachineEvent, ExecResult, JsonValue, WorkflowProviderCheckResult } from "./types.ts";
 
 describe("DevMachineEngine workflow runtime", () => {
   test("plans, applies graph nodes, reuses graph cache, and forks workspaces", async () => {
@@ -791,6 +791,91 @@ describe("DevMachineEngine workflow runtime", () => {
     expect(leakedHostRow).toBeNull();
   });
 
+  test("includes provider checks in workflow plans", async () => {
+    const projectDir = mkdtempSync(join(tmpdir(), "rigkit-provider-status-"));
+    writeFileSync(
+      join(projectDir, "rig.config.ts"),
+      `
+        import { defineProvider, workflow } from "${import.meta.dir}/index.ts";
+
+        const app = workflow("provider-status", {
+          providers: {
+            test: defineProvider("test", {}),
+          },
+        });
+
+        export default app.task("noop", async () => {});
+      `,
+    );
+
+    const engine = await createDevMachineEngine({
+      projectDir,
+      providerFactory: () => new FakeWorkflowProvider({
+        check: {
+          id: "account",
+          label: "Test account",
+          status: "ok",
+          value: "acct-1",
+          fingerprint: "acct-1",
+          metadata: { accountId: "acct-1" },
+        },
+      }),
+    });
+    await engine.load();
+
+    expect((await engine.plan()).providerChecks).toEqual([{
+      providerId: "test",
+      providerName: "test",
+      id: "account",
+      label: "Test account",
+      status: "ok",
+      value: "acct-1",
+      fingerprint: "acct-1",
+      metadata: { accountId: "acct-1" },
+    }]);
+  });
+
+  test("requires provider checks before applying workflow tasks", async () => {
+    const projectDir = mkdtempSync(join(tmpdir(), "rigkit-provider-check-required-"));
+    writeFileSync(
+      join(projectDir, "rig.config.ts"),
+      `
+        import { defineProvider, workflow } from "${import.meta.dir}/index.ts";
+
+        const app = workflow("provider-check-required", {
+          providers: {
+            test: defineProvider("test", {}),
+          },
+        });
+
+        export default app.task("noop", async () => {});
+      `,
+    );
+
+    const engine = await createDevMachineEngine({
+      projectDir,
+      providerFactory: () => new FakeWorkflowProvider({
+        check: {
+          id: "auth",
+          label: "Test auth",
+          status: "required",
+          value: "login required",
+          message: "Run the provider auth flow.",
+          fingerprint: "missing",
+        },
+      }),
+    });
+    await engine.load();
+
+    expect((await engine.plan()).providerChecks?.[0]).toMatchObject({
+      label: "Test auth",
+      status: "required",
+    });
+    await expect(engine.apply()).rejects.toThrow(
+      "Provider check required: Test auth. Run the provider auth flow.",
+    );
+  });
+
   test("rejects task outputs that are not JSON serializable", async () => {
     const projectDir = mkdtempSync(join(tmpdir(), "rigkit-"));
     writeFileSync(
@@ -1146,9 +1231,14 @@ class FakeWorkflowProvider implements WorkflowProviderController<FakeRuntime> {
   constructor(
     private readonly options: {
       terminalCompleted?: Promise<{ finished: true }>;
+      check?: WorkflowProviderCheckResult | WorkflowProviderCheckResult[];
     } = {},
   ) {}
 
+  checks(): WorkflowProviderCheckResult | WorkflowProviderCheckResult[] | undefined {
+    return this.options.check;
+  }
+
   runtime(context: ProviderRuntimeContext): FakeRuntime {
     return {
       createVm: async () => this.createVm(context),

package/src/engine.ts

@@ -46,6 +46,8 @@ import type {
   WorkflowPlan,
   WorkflowPlanNode,
   WorkflowProviderMap,
+  WorkflowProviderCheck,
+  WorkflowProviderCheckResult,
   WorkflowStepInvalidation,
   WorkflowTaskCacheTTL,
   WorkflowTaskNode,
@@ -68,7 +70,7 @@ export type CreateDevMachineEngineOptions = {
   interaction?: {
     present?: InteractionPresenter;
   };
-  local?: Partial<LocalWorkspaceRuntime>;
+  local?: LocalWorkspaceRuntimeOptions;
 };
 
 export type { InteractionPresenter, InteractionPresentationRequest };
@@ -101,6 +103,12 @@ export type EngineProjectInfo = {
   workflow?: WorkflowSummary;
 };
 
+export type LocalWorkspaceRuntimeOptions =
+  & Partial<Omit<LocalWorkspaceRuntime, "prompt">>
+  & {
+    prompt?: Partial<NonNullable<LocalWorkspaceRuntime["prompt"]>>;
+  };
+
 export type EngineCacheScope = WorkflowCacheScope;
 
 export type EngineCacheEntry = {
@@ -313,6 +321,12 @@ export class DevMachineEngine {
     this.interactionPresenter = options.interaction?.present ?? defaultInteractionPresenter;
     this.local = {
       open: options.local?.open ?? openLocalTarget,
+      prompt: {
+        message: options.local?.prompt?.message ?? showLocalMessage,
+        text: options.local?.prompt?.text ?? promptLocalText,
+        confirm: options.local?.prompt?.confirm ?? confirmLocalPrompt,
+        select: options.local?.prompt?.select ?? selectLocalOption,
+      },
       command: options.local?.command ?? runLocalCommand,
       requestCapability: options.local?.requestCapability ?? requestUnsupportedHostCapability,
       requestCapabilitySession: options.local?.requestCapabilitySession ?? requestUnsupportedHostCapabilitySession,
@@ -329,7 +343,7 @@ export class DevMachineEngine {
 
     if (!existsSync(this.configPath)) {
       throw new Error(
-        `No Rigkit config found at ${this.configPath}. Create one with "rig init" or pass -config=<file>.`,
+        `No Rigkit config found at ${this.configPath}. Create one with "rig init" or pass --config=<file>.`,
       );
     }
 
@@ -794,6 +808,7 @@ export class DevMachineEngine {
   async runOperation(input: { operation: string; workflow?: string; input?: unknown }): Promise<unknown> {
     const { workflow, operation } = this.getWorkflowOperation(input.operation, input.workflow);
     const providers = await this.createProviders(workflow);
+    await this.requireProviderChecks(workflow, providers);
     const metadata: JsonObject = {};
     const runtime = await this.createTaskRuntime({
       workflow,
@@ -928,6 +943,7 @@ export class DevMachineEngine {
     const applied = await this.apply({ workflow: input.workflow ?? input.machine });
     const workflow = this.getWorkflow(input.workflow ?? input.machine);
     const providers = await this.createProviders(workflow);
+    await this.requireProviderChecks(workflow, providers);
     if (!workflow.workspace) {
       throw new Error(`Workflow ${workflow.name} does not define a workspace`);
     }
@@ -986,6 +1002,7 @@ export class DevMachineEngine {
       throw new Error(`Workflow ${workflow.name} does not define a workspace`);
     }
     const providers = await this.createProviders(workflow);
+    await this.requireProviderChecks(workflow, providers);
     const metadata: JsonObject = {};
     const runtime = await this.createTaskRuntime({
       workflow,
@@ -1021,7 +1038,10 @@ export class DevMachineEngine {
     providers: ProviderControllers;
     mode: EvaluationMode;
   }): Promise<{ context: Record<string, JsonValue>; plan: WorkflowPlan; fragments: Set<string> }> {
-    const providerFingerprint = providerFingerprintFor(input.workflow);
+    const providerChecks = await this.collectProviderChecks(input.workflow, input.providers, {
+      mode: input.mode === "plan" ? "plan" : "require",
+    });
+    const providerFingerprint = providerFingerprintFor(input.workflow, providerChecks);
     const planNodes: WorkflowPlanNode[] = [];
     const previousEvaluationFragmentHashes = this.evaluationFragmentHashes;
     const fragments = new Set<string>();
@@ -1060,6 +1080,7 @@ export class DevMachineEngine {
     const plan: WorkflowPlan = {
       workflow: input.workflow.name,
       providerFingerprint,
+      ...(providerChecks.length > 0 ? { providerChecks } : {}),
       cachedNodeCount,
       nodeCount: planNodes.length,
       nodes: planNodes,
@@ -1547,6 +1568,7 @@ export class DevMachineEngine {
     operation: WorkflowWorkspaceOperationDefinition<any, any, any, any>;
     rawInput: unknown;
   }): Promise<unknown> {
+    await this.requireProviderChecks(input.workflow, input.providers);
     const metadata: JsonObject = {};
     const providers = await this.createTaskRuntime({
       workflow: input.workflow,
@@ -1829,6 +1851,48 @@ export class DevMachineEngine {
     return Object.fromEntries(entries);
   }
 
+  private async collectProviderChecks(
+    workflow: LoadedWorkflow,
+    providers: ProviderControllers,
+    input: { mode: "plan" | "require" },
+  ): Promise<WorkflowProviderCheck[]> {
+    const checks = await Promise.all(
+      Object.entries(providers).map(async ([providerName, controller]) => {
+        const result = await controller.checks?.({
+          mode: input.mode,
+          workflow: workflow.name,
+          local: this.local,
+        });
+        return normalizeProviderChecks(result).map((check) => ({
+          providerId: check.providerId ?? controller.providerId,
+          providerName: check.providerName ?? providerName,
+          id: check.id,
+          label: check.label,
+          status: check.status,
+          value: check.value,
+          ...(check.message ? { message: check.message } : {}),
+          ...(check.detail ? { detail: check.detail } : {}),
+          ...(check.fingerprint ? { fingerprint: check.fingerprint } : {}),
+          ...(check.metadata ? { metadata: check.metadata } : {}),
+        }));
+      }),
+    );
+    const flatChecks = checks.flat();
+    if (input.mode === "require") {
+      const required = flatChecks.find((check) => check.status !== "ok");
+      if (required) {
+        throw new Error(
+          `Provider check required: ${required.label}${required.message ? `. ${required.message}` : ""}`,
+        );
+      }
+    }
+    return flatChecks;
+  }
+
+  private async requireProviderChecks(workflow: LoadedWorkflow, providers: ProviderControllers): Promise<void> {
+    await this.collectProviderChecks(workflow, providers, { mode: "require" });
+  }
+
   private async createProviderFromPlugin(input: Parameters<ProviderFactory>[0]): Promise<WorkflowProviderController> {
     const plugin = this.providers.find((provider) => provider.providerId === input.provider.providerId);
     if (!plugin) {
@@ -2034,9 +2098,9 @@ function collectNodePaths(root: WorkflowNodeDefinition<any, any, any>): string[]
   }
 }
 
-function providerFingerprintFor(workflow: LoadedWorkflow): string {
+function providerFingerprintFor(workflow: LoadedWorkflow, providerChecks: WorkflowProviderCheck[]): string {
   return hash({
-    cache: "provider-v2",
+    cache: "provider-v3",
     providers: Object.fromEntries(
       Object.entries(workflow.providers).map(([name, provider]) => [
         name,
@@ -2047,6 +2111,13 @@ function providerFingerprintFor(workflow: LoadedWorkflow): string {
         },
       ]),
     ),
+    checks: providerChecks.map((check) => ({
+      providerName: check.providerName,
+      providerId: check.providerId,
+      id: check.id,
+      status: check.status,
+      fingerprint: check.fingerprint ?? check.value,
+    })),
   });
 }
 
@@ -2484,6 +2555,13 @@ function optionalBooleanInput(
   return value;
 }
 
+function normalizeProviderChecks(
+  result: WorkflowProviderCheckResult | WorkflowProviderCheckResult[] | undefined,
+): WorkflowProviderCheckResult[] {
+  if (result === undefined) return [];
+  return Array.isArray(result) ? result : [result];
+}
+
 function isPlainObject(value: unknown): value is Record<string, unknown> {
   return Boolean(value && typeof value === "object" && !Array.isArray(value) && Object.getPrototypeOf(value) === Object.prototype);
 }
@@ -2507,6 +2585,30 @@ async function openLocalTarget(target: string): Promise<void> {
   }
 }
 
+async function showLocalMessage(input: { message: string; level?: "info" | "warn" | "error" }): Promise<void> {
+  const writer = input.level === "error" || input.level === "warn" ? console.error : console.log;
+  writer(input.message);
+}
+
+async function promptLocalText(input: { message: string; defaultValue?: string }): Promise<string> {
+  if (input.defaultValue !== undefined) return input.defaultValue;
+  throw new Error(`Host text prompt requires an interactive runtime host: ${input.message}`);
+}
+
+async function confirmLocalPrompt(input: { message: string; defaultValue?: boolean }): Promise<boolean> {
+  if (input.defaultValue !== undefined) return input.defaultValue;
+  throw new Error(`Host confirm prompt requires an interactive runtime host: ${input.message}`);
+}
+
+async function selectLocalOption(input: {
+  message: string;
+  options: Array<{ value: string; label?: string; description?: string }>;
+  defaultValue?: string;
+}): Promise<string> {
+  if (input.defaultValue) return input.defaultValue;
+  throw new Error(`Host select prompt requires an interactive runtime host: ${input.message}`);
+}
+
 async function requestUnsupportedHostCapability<Result = unknown>(capability: string): Promise<Result> {
   throw new Error(
     `Host capability ${capability} is unavailable outside a runtime host. ` +

package/src/provider/types.ts

@@ -7,6 +7,7 @@ import type {
   LoadedProviderDefinition,
   LocalWorkspaceRuntime,
   MaybePromise,
+  WorkflowProviderCheckResult,
 } from "../types.ts";
 
 export type VmHandle = {
@@ -73,9 +74,16 @@ export type ProviderRuntimeContext = {
   metadata(metadata: JsonObject): void;
 };
 
+export type ProviderCheckContext = {
+  mode: "plan" | "require";
+  workflow: string;
+  local: LocalWorkspaceRuntime;
+};
+
 export interface WorkflowProviderController<Runtime = unknown> {
   readonly providerId: string;
   runtime(context: ProviderRuntimeContext): MaybePromise<Runtime>;
+  checks?(context: ProviderCheckContext): MaybePromise<WorkflowProviderCheckResult | WorkflowProviderCheckResult[] | undefined>;
   validateArtifact?(ref: JsonValue): MaybePromise<boolean>;
 }
 

package/src/types.ts

@@ -54,6 +54,7 @@ export type CommandOptions = ExecOptions & {
 
 export type LocalWorkspaceRuntime = {
   open(target: string): MaybePromise<void>;
+  prompt?: LocalPromptRuntime;
   command?(input: LocalCommandRequest): MaybePromise<LocalCommandResult>;
   requestCapability?<Result = unknown>(
     capability: string,
@@ -67,6 +68,38 @@ export type LocalWorkspaceRuntime = {
   ): MaybePromise<HostCapabilitySession<Result>>;
 };
 
+export type LocalPromptRuntime = {
+  message(input: LocalMessageRequest): MaybePromise<void>;
+  text(input: LocalTextRequest): MaybePromise<string>;
+  confirm(input: LocalConfirmRequest): MaybePromise<boolean>;
+  select(input: LocalSelectRequest): MaybePromise<string>;
+};
+
+export type LocalMessageRequest = {
+  message: string;
+  level?: "info" | "warn" | "error";
+};
+
+export type LocalTextRequest = {
+  message: string;
+  defaultValue?: string;
+};
+
+export type LocalConfirmRequest = {
+  message: string;
+  defaultValue?: boolean;
+};
+
+export type LocalSelectRequest = {
+  message: string;
+  options: Array<{
+    value: string;
+    label?: string;
+    description?: string;
+  }>;
+  defaultValue?: string;
+};
+
 export type LocalHostCapabilityRequestOptions = {
   nodePath?: string;
 };
@@ -810,9 +843,29 @@ export type WorkflowPlanNode = {
   upstreamRunIds: string[];
 };
 
+export type WorkflowProviderCheckStatus = "ok" | "required";
+
+export type WorkflowProviderCheck = {
+  providerId: string;
+  providerName: string;
+  id: string;
+  label: string;
+  status: WorkflowProviderCheckStatus;
+  value: string;
+  message?: string;
+  detail?: string;
+  fingerprint?: string;
+  metadata?: JsonObject;
+};
+
+export type WorkflowProviderCheckResult =
+  & Omit<WorkflowProviderCheck, "providerId" | "providerName">
+  & Partial<Pick<WorkflowProviderCheck, "providerId" | "providerName">>;
+
 export type WorkflowPlan = {
   workflow: string;
   providerFingerprint: string;
+  providerChecks?: WorkflowProviderCheck[];
   cachedNodeCount: number;
   nodeCount: number;
   nodes: WorkflowPlanNode[];

package/src/version.ts

@@ -1 +1 @@
-export const RIGKIT_ENGINE_VERSION = "0.2.10";
+export const RIGKIT_ENGINE_VERSION = "0.2.11";