@rigkit/sdk 0.1.8

package/src/runtime/operations.ts

@@ -0,0 +1,267 @@
+import {
+  createDevMachineEngine,
+  type DevMachineEngine,
+  type EngineOperationSummary,
+  type JsonValue,
+} from "@rigkit/engine";
+import { normalizeRuntimeRunError } from "./errors.ts";
+import {
+  HostCommandResultSchema,
+  objectSchema,
+  type JsonSchema,
+  type RuntimeOperation,
+  type RuntimeOperationsManifest,
+} from "./protocol.ts";
+import {
+  completeRun,
+  emitRunEvent,
+  failRun,
+  requestHost,
+  requestHostCapability,
+  requestHostCapabilitySession,
+  type RunRecord,
+  type RunStore,
+} from "./runs.ts";
+import { createRuntimeStateService } from "./state.ts";
+import { RIGKIT_RUNTIME_VERSION } from "./version.ts";
+
+export type EngineLoadOptions = {
+  projectId?: string;
+  projectDir: string;
+  configPath: string;
+  statePath?: string;
+  source?: JsonValue;
+};
+
+export async function loadEngine(input: EngineLoadOptions): Promise<DevMachineEngine> {
+  const engine = await createDevMachineEngine({
+    projectDir: input.projectDir,
+    configPath: input.configPath,
+    state: createRuntimeStateService({
+      projectId: input.projectId,
+      projectDir: input.projectDir,
+      configPath: input.configPath,
+      statePath: input.statePath,
+      runtimeVersion: RIGKIT_RUNTIME_VERSION,
+      source: input.source,
+    }),
+  });
+  await engine.load();
+  return engine;
+}
+
+export function runOperation(run: RunRecord, store: RunStore, options: EngineLoadOptions): void {
+  executeOperation(run, store, options).catch((error) => failRun(run, normalizeRuntimeRunError(error), store));
+}
+
+async function executeOperation(run: RunRecord, store: RunStore, options: EngineLoadOptions): Promise<void> {
+  const engine = await createDevMachineEngine({
+    projectDir: options.projectDir,
+    configPath: options.configPath,
+    state: createRuntimeStateService({
+      projectId: options.projectId,
+      projectDir: options.projectDir,
+      configPath: options.configPath,
+      statePath: options.statePath,
+      runtimeVersion: RIGKIT_RUNTIME_VERSION,
+      source: options.source,
+    }),
+    interaction: {
+      present: async (request) => {
+        await requestHost(store, run, "open.external", {
+          target: request.url,
+          kind: "url",
+          label: request.title,
+        });
+      },
+    },
+    local: {
+      open: async (target) => {
+        await requestHost(store, run, "open.external", { target, kind: guessExternalKind(target) });
+      },
+      command: async (command) => {
+        const result = await requestHost(store, run, "host.command.run", command);
+        return HostCommandResultSchema.parse(result);
+      },
+      requestCapability: async <Result = unknown>(capability: string, params: unknown) =>
+        await requestHostCapability(store, run, capability, params) as Result,
+      requestCapabilitySession: async <Result = unknown>(capability: string, params: unknown) =>
+        await requestHostCapabilitySession<Result>(store, run, capability, params),
+    },
+  });
+  engine.onEvent((event) => emitRunEvent(run, event));
+  await engine.load();
+
+  const result = await engine.runRuntimeOperation({ operation: run.operation, input: run.input });
+  completeRun(run, result, store);
+}
+
+export function operationsFor(engine: DevMachineEngine): RuntimeOperation[] {
+  return engine.listRuntimeOperations().map((operation) => runtimeOperationForEngineOperation(engine, operation));
+}
+
+function runtimeOperationForEngineOperation(engine: DevMachineEngine, operation: EngineOperationSummary): RuntimeOperation {
+  const required = operation.inputFields
+    .filter((field) => field.required ?? true)
+    .map((field) => field.name);
+  const properties = Object.fromEntries(
+    operation.inputFields.map((field) => [field.name, jsonSchemaForField(engine, operation, field)]),
+  );
+  const hasWorkspaceInput = operation.inputFields.some((field) => field.kind === "workspace");
+  return {
+    id: operation.id,
+    ...(operation.aliases?.length ? { aliases: [...operation.aliases] } : {}),
+    kind: operation.kind ?? (hasWorkspaceInput ? "workspace-action" : "command"),
+    source: operation.source ?? "config",
+    title: operation.title ?? titleize(operation.id),
+    description: operation.description ?? "",
+    createsWorkspace: operation.createsWorkspace,
+    requiredHostMethods: operation.requiredHostMethods?.map((method) => ({
+      id: method.id,
+      ...(method.modes?.length ? { modes: [...method.modes] } : {}),
+    })),
+    requiredHostCapabilities: operation.requiredHostCapabilities?.map((capability) => ({
+      id: capability.id,
+      ...(capability.schemaHash ? { schemaHash: capability.schemaHash } : {}),
+    })),
+    cli: operation.cli ? cloneOperationCli(operation.cli) : cliForFields(operation.inputFields),
+    inputSchema: objectSchema(properties, required),
+  };
+}
+
+function jsonSchemaForField(
+  engine: DevMachineEngine,
+  operation: EngineOperationSummary,
+  field: EngineOperationSummary["inputFields"][number],
+): JsonSchema {
+  const schema: JsonSchema = {
+    type: field.kind === "boolean" || field.kind === "number" ? field.kind : "string",
+    ...(field.description ? { description: field.description } : {}),
+    ...(field.defaultValue !== undefined ? { default: field.defaultValue } : {}),
+  };
+  if (field.kind === "string" && (field.required ?? true)) {
+    schema.minLength = 1;
+  }
+  if (field.name === "workflow") {
+    const workflows = engine.listWorkflows().map((workflow) => workflow.name);
+    Object.assign(schema, workflowJsonSchema(workflows));
+  }
+  if (field.kind === "workspace") {
+    schema["x-rigkit-input"] = {
+      kind: "workspace",
+      workflow: operation.workflow,
+      resolve: "data",
+    };
+  }
+  return schema;
+}
+
+function cloneOperationCli(cli: NonNullable<EngineOperationSummary["cli"]>): NonNullable<RuntimeOperation["cli"]> {
+  return {
+    ...(cli.positionals ? { positionals: cli.positionals.map((item) => ({ ...item })) } : {}),
+    ...(cli.options
+      ? {
+        options: cli.options.map((item) => ({
+          ...item,
+          ...(item.aliases ? { aliases: [...item.aliases] } : {}),
+        })),
+      }
+      : {}),
+  };
+}
+
+function cliForFields(fields: EngineOperationSummary["inputFields"]): NonNullable<RuntimeOperation["cli"]> {
+  return {
+    positionals: fields
+      .filter((field) => typeof field.position === "number")
+      .map((field) => ({ name: field.name, index: field.position! })),
+    options: fields
+      .filter((field) => typeof field.position !== "number")
+      .map((field) => ({
+        name: field.name,
+        flag: `--${dashCase(field.name)}`,
+        required: field.required ?? true,
+        type: field.kind === "boolean" || field.kind === "number" ? field.kind : "string",
+      })),
+  };
+}
+
+export function operationManifestFor(engine: DevMachineEngine): RuntimeOperationsManifest {
+  const operations = operationsFor(engine);
+  return {
+    hostMethods: {
+      known: [
+        { id: "message.show" },
+        { id: "prompt.text" },
+        { id: "prompt.confirm" },
+        { id: "prompt.select" },
+        { id: "open.external" },
+        { id: "host.command.run", modes: ["capture", "interactive"] },
+      ],
+      requiredByOperations: Object.fromEntries(
+        operations
+          .filter((operation) => operation.requiredHostMethods?.length)
+          .map((operation) => [
+            operation.id,
+            operation.requiredHostMethods!.flatMap((method) =>
+              method.modes?.length
+                ? method.modes.map((mode) => `${method.id}:${mode}`)
+                : [method.id]
+            ),
+          ]),
+      ),
+    },
+    hostCapabilities: {
+      optional: dedupeHostCapabilities(
+        operations.flatMap((operation) => operation.requiredHostCapabilities ?? []),
+      ),
+      requiredByOperations: Object.fromEntries(
+        operations
+          .filter((operation) => operation.requiredHostCapabilities?.length)
+          .map((operation) => [operation.id, operation.requiredHostCapabilities!.map((capability) => capability.id)]),
+      ),
+    },
+    operations,
+  };
+}
+
+function dedupeHostCapabilities(
+  capabilities: Array<{ id: string; schemaHash?: string }>,
+): Array<{ id: string; schemaHash?: string }> {
+  const seen = new Set<string>();
+  const deduped: Array<{ id: string; schemaHash?: string }> = [];
+  for (const capability of capabilities) {
+    const key = capability.schemaHash ? `${capability.id}\0${capability.schemaHash}` : capability.id;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    deduped.push({
+      id: capability.id,
+      ...(capability.schemaHash ? { schemaHash: capability.schemaHash } : {}),
+    });
+  }
+  return deduped;
+}
+
+function workflowJsonSchema(workflows: string[]): JsonSchema {
+  return workflows.length > 0
+    ? { type: "string", enum: workflows }
+    : { type: "string" };
+}
+
+function dashCase(value: string): string {
+  return value.replace(/[A-Z]/g, (letter) => `-${letter.toLowerCase()}`);
+}
+
+function titleize(value: string): string {
+  return value
+    .split(/[-_.\s]+/g)
+    .filter(Boolean)
+    .map((part) => `${part.slice(0, 1).toUpperCase()}${part.slice(1)}`)
+    .join(" ");
+}
+
+function guessExternalKind(target: string): "url" | "file" | "unknown" {
+  if (/^[a-z][a-z0-9+.-]*:/i.test(target)) return "url";
+  if (target.startsWith("/")) return "file";
+  return "unknown";
+}

package/src/runtime/protocol.ts

@@ -0,0 +1,193 @@
+import { Schema } from "effect";
+import type { WorkflowEvent } from "@rigkit/engine";
+
+export const RUNTIME_API_VERSION = 1;
+export const RUNTIME_PROTOCOL_HASH = "sha256:6dc28b06c95c98d310db445f1b19aef478cd828f11287467fe261483dfde4f81";
+export const DEFAULT_IDLE_MS = 30 * 60 * 1000;
+
+export class RuntimeProtocolSchemaError extends Error {
+  constructor(readonly cause: unknown) {
+    super(String(cause));
+    this.name = "RuntimeProtocolSchemaError";
+  }
+}
+
+type ParseResult<T> =
+  | { success: true; data: T }
+  | { success: false; error: RuntimeProtocolSchemaError };
+
+type RuntimeSchema<T> = {
+  parse(value: unknown): T;
+  safeParse(value: unknown): ParseResult<T>;
+};
+
+function runtimeSchema<T, I>(schema: Schema.Schema<T, I, never>): RuntimeSchema<T> {
+  const decode = Schema.decodeUnknownSync(schema);
+  return {
+    parse(value) {
+      try {
+        return decode(value);
+      } catch (error) {
+        throw new RuntimeProtocolSchemaError(error);
+      }
+    },
+    safeParse(value) {
+      try {
+        return { success: true, data: decode(value) };
+      } catch (error) {
+        return { success: false, error: new RuntimeProtocolSchemaError(error) };
+      }
+    },
+  };
+}
+
+export const RunOperationRequestEffectSchema = Schema.Struct({
+  operation: Schema.NonEmptyString,
+  input: Schema.optional(Schema.Unknown),
+}).annotations({ identifier: "RunOperationRequest" });
+
+export const HostResponseEffectSchema = Schema.Union(
+  Schema.Struct({
+    error: Schema.Struct({
+      code: Schema.optional(Schema.String),
+      message: Schema.optional(Schema.String),
+    }),
+  }),
+  Schema.Struct({
+    result: Schema.optional(Schema.Unknown),
+  }),
+).annotations({ identifier: "HostResponse" });
+
+export const HostCommandRequestEffectSchema = Schema.Struct({
+  argv: Schema.Array(Schema.String).pipe(Schema.minItems(1)),
+  cwd: Schema.optional(Schema.String),
+  env: Schema.optional(Schema.Record({ key: Schema.String, value: Schema.UndefinedOr(Schema.String) })),
+  stdin: Schema.optional(Schema.NullOr(Schema.String)),
+  mode: Schema.optional(Schema.Literal("capture", "interactive")),
+  reason: Schema.optional(Schema.String),
+  presentation: Schema.optional(Schema.Struct({
+    visible: Schema.optional(Schema.Boolean),
+    label: Schema.optional(Schema.String),
+  })),
+}).annotations({ identifier: "HostCommandRequest" });
+
+export const HostCommandResultEffectSchema = Schema.Struct({
+  exitCode: Schema.Int,
+  stdout: Schema.NullOr(Schema.String),
+  stderr: Schema.NullOr(Schema.String),
+}).annotations({ identifier: "HostCommandResult" });
+
+export type RunOperationRequest = Schema.Schema.Type<typeof RunOperationRequestEffectSchema>;
+export type HostResponse = Schema.Schema.Type<typeof HostResponseEffectSchema>;
+export type HostCommandRequest = Schema.Schema.Type<typeof HostCommandRequestEffectSchema>;
+export type HostCommandResult = Schema.Schema.Type<typeof HostCommandResultEffectSchema>;
+
+export const RunOperationRequestSchema: RuntimeSchema<RunOperationRequest> = runtimeSchema(RunOperationRequestEffectSchema);
+export const HostResponseSchema: RuntimeSchema<HostResponse> = runtimeSchema(HostResponseEffectSchema);
+export const HostCommandRequestSchema: RuntimeSchema<HostCommandRequest> = runtimeSchema(HostCommandRequestEffectSchema);
+export const HostCommandResultSchema: RuntimeSchema<HostCommandResult> = runtimeSchema(HostCommandResultEffectSchema);
+
+export type HostRequestEvent = {
+  type: "host.request";
+  requestId: string;
+  id: string;
+  method: string;
+  params: unknown;
+};
+
+export type HostCapabilityRequestEvent = {
+  type: "host.capability.request";
+  requestId: string;
+  id: string;
+  capability: string;
+  params: unknown;
+};
+
+export type RunCompletedEvent = {
+  type: "run.completed";
+  runId: string;
+  result: unknown;
+};
+
+export type RunFailedEvent = {
+  type: "run.failed";
+  runId: string;
+  error: { code?: string; message: string };
+};
+
+export type RuntimeEvent =
+  | WorkflowEvent
+  | HostRequestEvent
+  | HostCapabilityRequestEvent
+  | RunCompletedEvent
+  | RunFailedEvent;
+
+export type JsonSchema = Record<string, unknown>;
+
+export type RuntimeOperationSource = "core" | "config";
+
+export type RuntimeOperationKind = "command" | "workspace-action";
+
+export type RuntimeOperationCliPosition = {
+  name: string;
+  index: number;
+};
+
+export type RuntimeOperationCliOption = {
+  name: string;
+  flag: string;
+  aliases?: string[];
+  required?: boolean;
+  runtime?: boolean;
+  type?: "string" | "boolean" | "number";
+};
+
+export type RuntimeOperationCli = {
+  positionals?: RuntimeOperationCliPosition[];
+  options?: RuntimeOperationCliOption[];
+};
+
+export type RuntimeHostMethodRequirement = {
+  id: string;
+  modes?: string[];
+};
+
+export type RuntimeHostCapabilityRequirement = {
+  id: string;
+  schemaHash?: string;
+};
+
+export type RuntimeOperation = {
+  id: string;
+  aliases?: string[];
+  kind: RuntimeOperationKind;
+  source: RuntimeOperationSource;
+  title: string;
+  description: string;
+  createsWorkspace?: boolean;
+  requiredHostMethods?: RuntimeHostMethodRequirement[];
+  requiredHostCapabilities?: RuntimeHostCapabilityRequirement[];
+  cli?: RuntimeOperationCli;
+  inputSchema: JsonSchema;
+};
+
+export type RuntimeOperationsManifest = {
+  hostMethods: {
+    known: RuntimeHostMethodRequirement[];
+    requiredByOperations: Record<string, string[]>;
+  };
+  hostCapabilities: {
+    optional: RuntimeHostCapabilityRequirement[];
+    requiredByOperations: Record<string, string[]>;
+  };
+  operations: RuntimeOperation[];
+};
+
+export function objectSchema(properties: Record<string, unknown>, required: string[] = []): JsonSchema {
+  return {
+    type: "object",
+    additionalProperties: false,
+    ...(required.length > 0 ? { required } : {}),
+    properties,
+  };
+}