@osolmaz/pi-workflows 0.16.1 → 0.16.3

package/src/{controllers → resource-managers}/conditions.ts

@@ -1,16 +1,16 @@
 import type {
-  ControllerCondition,
-  ControllerConditionInput,
-  ControllerConditionStatus,
-  ControllerResourceStatus,
-  ControllerStatusPatch,
+  ManagedResourceCondition,
+  ManagedResourceConditionInput,
+  ManagedResourceConditionStatus,
+  ManagedResourceStatus,
+  ResourceManagerStatusPatch,
 } from "./types.js";
 
 export function conditionTrue(
   type: string,
   reason: string,
   message?: string,
-): ControllerConditionInput {
+): ManagedResourceConditionInput {
   return condition(type, true, reason, message);
 }
 
@@ -18,7 +18,7 @@ export function conditionFalse(
   type: string,
   reason: string,
   message?: string,
-): ControllerConditionInput {
+): ManagedResourceConditionInput {
   return condition(type, false, reason, message);
 }
 
@@ -26,23 +26,23 @@ export function conditionUnknown(
   type: string,
   reason: string,
   message?: string,
-): ControllerConditionInput {
+): ManagedResourceConditionInput {
   return condition(type, "unknown", reason, message);
 }
 
 export function applyStatusPatch<TStatus>(
-  current: ControllerResourceStatus<TStatus>,
-  patch: ControllerStatusPatch<TStatus> | undefined,
+  current: ManagedResourceStatus<TStatus>,
+  patch: ResourceManagerStatusPatch<TStatus> | undefined,
   generation: number,
   now: string,
-): ControllerResourceStatus<TStatus> {
+): ManagedResourceStatus<TStatus> {
   return {
     observedGeneration: generation,
     conditions: mergeConditions(current.conditions, patch?.conditions ?? [], generation, now),
-    controllerStatus:
-      patch !== undefined && Object.hasOwn(patch, "controllerStatus")
-        ? (patch.controllerStatus as TStatus)
-        : current.controllerStatus,
+    resourceManagerStatus:
+      patch !== undefined && Object.hasOwn(patch, "resourceManagerStatus")
+        ? (patch.resourceManagerStatus as TStatus)
+        : current.resourceManagerStatus,
     ...(patch?.workflowRun === null
       ? {}
       : patch?.workflowRun !== undefined
@@ -54,11 +54,11 @@ export function applyStatusPatch<TStatus>(
 }
 
 export function mergeConditions(
-  current: ControllerCondition[],
-  updates: ControllerConditionInput[],
+  current: ManagedResourceCondition[],
+  updates: ManagedResourceConditionInput[],
   generation: number,
   now: string,
-): ControllerCondition[] {
+): ManagedResourceCondition[] {
   const byType = new Map(current.map((item) => [item.type, item]));
   const seen = new Set<string>();
   for (const update of updates) {
@@ -68,7 +68,7 @@ export function mergeConditions(
     }
     seen.add(update.type);
     const previous = byType.get(update.type);
-    const next: ControllerCondition = {
+    const next: ManagedResourceCondition = {
       ...update,
       observedGeneration: generation,
       lastTransitionTime:
@@ -83,11 +83,11 @@ export function mergeConditions(
 
 function condition(
   type: string,
-  status: ControllerConditionStatus,
+  status: ManagedResourceConditionStatus,
   reason: string,
   message: string | undefined,
-): ControllerConditionInput {
-  const value: ControllerConditionInput = {
+): ManagedResourceConditionInput {
+  const value: ManagedResourceConditionInput = {
     type,
     status,
     reason,
@@ -97,7 +97,7 @@ function condition(
   return value;
 }
 
-function validateCondition(value: ControllerConditionInput): void {
+function validateCondition(value: ManagedResourceConditionInput): void {
   if (value.type.trim().length === 0) {
     throw new Error("Condition type must not be empty");
   }

package/src/resource-managers/definition.ts

@@ -0,0 +1,71 @@
+import type {
+  AnyResourceManagerDefinition,
+  ResourceManagerDefinition,
+  ManagedResource,
+} from "./types.js";
+
+const RESOURCE_MANAGER_DEFINITION_BRAND = Symbol.for("pi-workflows.resource-manager-definition");
+const RESOURCE_MANAGER_NAME_PATTERN = /^[a-z][a-z0-9-]*$/;
+
+export function defineResourceManager<TSpec, TStatus>(
+  definition: ResourceManagerDefinition<TSpec, TStatus>,
+): ResourceManagerDefinition<TSpec, TStatus> {
+  assertValidResourceManagerDefinition(definition);
+  if (isResourceManagerDefinition(definition)) {
+    return definition;
+  }
+  Object.defineProperty(definition, RESOURCE_MANAGER_DEFINITION_BRAND, {
+    value: true,
+    enumerable: false,
+    configurable: false,
+    writable: false,
+  });
+  return definition;
+}
+
+export function isResourceManagerDefinition(value: unknown): value is AnyResourceManagerDefinition {
+  return (
+    value !== null &&
+    typeof value === "object" &&
+    (value as Record<PropertyKey, unknown>)[RESOURCE_MANAGER_DEFINITION_BRAND] === true
+  );
+}
+
+export function assertValidResourceManagerDefinition<TSpec, TStatus>(
+  definition: ResourceManagerDefinition<TSpec, TStatus>,
+): void {
+  if (definition === null || typeof definition !== "object") {
+    throw new Error("Invalid resource manager definition: expected an object");
+  }
+  if (!RESOURCE_MANAGER_NAME_PATTERN.test(definition.name)) {
+    throw new Error(
+      `Invalid resource manager definition: name ${JSON.stringify(definition.name)} must match ${RESOURCE_MANAGER_NAME_PATTERN.source}`,
+    );
+  }
+  if (typeof definition.initialStatus !== "function") {
+    throw new Error("Invalid resource manager definition: initialStatus must be a function");
+  }
+  if (typeof definition.reconcile !== "function") {
+    throw new Error("Invalid resource manager definition: reconcile must be a function");
+  }
+  if (
+    definition.timeoutMs !== undefined &&
+    (!Number.isSafeInteger(definition.timeoutMs) || definition.timeoutMs <= 0)
+  ) {
+    throw new Error(
+      "Invalid resource manager definition: timeoutMs must be a positive safe integer",
+    );
+  }
+}
+
+export function asAnyResourceManagerDefinition<TSpec, TStatus>(
+  definition: ResourceManagerDefinition<TSpec, TStatus>,
+): AnyResourceManagerDefinition {
+  return definition as unknown as ResourceManagerDefinition<unknown, unknown>;
+}
+
+export function asTypedResource<TSpec, TStatus>(
+  resource: ManagedResource,
+): ManagedResource<TSpec, TStatus> {
+  return resource as ManagedResource<TSpec, TStatus>;
+}

package/src/{controllers → resource-managers}/effects.ts

@@ -1,9 +1,9 @@
 import { jsonFingerprint } from "./json.js";
-import type { ControllerStore } from "./store.js";
+import type { ResourceManagerStore } from "./store.js";
 import type {
-  ControllerEffects,
-  ControllerQueueClaim,
-  ControllerResource,
+  ResourceManagerEffects,
+  ResourceManagerQueueClaim,
+  ManagedResource,
   EffectApplication,
   EffectDefinition,
   EffectObservation,
@@ -11,13 +11,13 @@ import type {
   JsonObject,
 } from "./types.js";
 
-export class ControllerEffectService implements ControllerEffects {
+export class ResourceManagerEffectService implements ResourceManagerEffects {
   private used = false;
 
   constructor(
-    private readonly store: ControllerStore,
-    private readonly resource: ControllerResource,
-    private readonly claim: ControllerQueueClaim,
+    private readonly store: ResourceManagerStore,
+    private readonly resource: ManagedResource,
+    private readonly claim: ResourceManagerQueueClaim,
     private readonly signal: AbortSignal,
   ) {}
 
@@ -115,7 +115,7 @@ export class ControllerEffectService implements ControllerEffects {
 
   private recordEvent(type: string, effectKey: string, extra: JsonObject = {}): void {
     this.store.recordEvent({
-      controller: this.resource.metadata.controller,
+      resourceManager: this.resource.metadata.resourceManager,
       key: this.resource.metadata.key,
       claim: this.claim,
       type,

package/src/resource-managers/errors.ts

@@ -0,0 +1,27 @@
+export class ManagedResourceConflictError extends Error {
+  constructor(resourceManager: string, key: string) {
+    super(`Managed resource ${resourceManager}/${key} changed during reconciliation`);
+    this.name = "ManagedResourceConflictError";
+  }
+}
+
+export class ManagedResourceNotFoundError extends Error {
+  constructor(resourceManager: string, key: string) {
+    super(`Managed resource not found: ${resourceManager}/${key}`);
+    this.name = "ManagedResourceNotFoundError";
+  }
+}
+
+export class EffectRequestConflictError extends Error {
+  constructor(key: string) {
+    super(`Effect key ${JSON.stringify(key)} was reused with a different request`);
+    this.name = "EffectRequestConflictError";
+  }
+}
+
+export class WorkflowRequestConflictError extends Error {
+  constructor(key: string) {
+    super(`Workflow request key ${JSON.stringify(key)} was reused with different input`);
+    this.name = "WorkflowRequestConflictError";
+  }
+}

package/src/resource-managers/index.ts

@@ -0,0 +1,88 @@
+export {
+  assertValidResourceManagerDefinition,
+  defineResourceManager,
+  isResourceManagerDefinition,
+} from "./definition.js";
+export {
+  applyStatusPatch,
+  conditionFalse,
+  conditionTrue,
+  conditionUnknown,
+  mergeConditions,
+} from "./conditions.js";
+export {
+  EffectRequestConflictError,
+  ManagedResourceConflictError,
+  ManagedResourceNotFoundError,
+  WorkflowRequestConflictError,
+} from "./errors.js";
+export { ResourceManagerEffectService } from "./effects.js";
+export { canonicalJson, jsonFingerprint } from "./json.js";
+export { ResourceManagerRuntime, type ResourceManagerRuntimeOptions } from "./runtime.js";
+export { createResultHelpers, requeue, requeueAfter, settled } from "./results.js";
+export {
+  SqliteResourceManagerStore,
+  type RunEventRecord,
+  type WorkflowRunClaimOptions,
+  type WorkflowRunPreparationResult,
+  type WorkflowRunQueueRecord,
+  type WorkflowRunReservationOptions,
+} from "./sqlite.js";
+export {
+  type ResourceManagerStore,
+  type EffectReservation,
+  type QueueItem,
+  type QueueRequeueOptions,
+  type WorkflowRecordUpdate,
+  type WorkflowReservation,
+} from "./store.js";
+export {
+  resourceManagerFileStem,
+  resourceManagerSearchDirs,
+  discoverResourceManagers,
+  loadResourceManagerFile,
+  loadDiscoveredResourceManagers,
+  type DiscoveredResourceManager,
+} from "./loader.js";
+export {
+  ResourceManagerWorkflowCoordinator,
+  type ResourceManagerWorkflowControlRequest,
+  type ResourceManagerWorkflowScheduler,
+  type WorkflowSchedulerRequest,
+  type WorkflowSchedulerResult,
+} from "./workflows.js";
+export type {
+  AnyResourceManagerDefinition,
+  ChildWorkflowRecord,
+  ChildWorkflowReference,
+  ChildWorkflowRequest,
+  ChildWorkflowState,
+  ManagedResourceCondition,
+  ManagedResourceConditionInput,
+  ManagedResourceConditionStatus,
+  ResourceManagerDefinition,
+  ResourceManagerEffects,
+  ResourceManagerFollowUpResult,
+  ResourceManagerQueueFollowUpRequest,
+  ResourceManagerRemoveFollowUpRequest,
+  ResourceManagerSettingsChangeRequest,
+  ResourceManagerSettingsChangeResult,
+  ResourceManagerEvent,
+  ResourceManagerQueueClaim,
+  ManagedResource,
+  ManagedResourceRef,
+  ManagedResourceStatus,
+  ResourceManagerStatusPatch,
+  ResourceManagerWorkflows,
+  EffectApplication,
+  EffectDefinition,
+  EffectObservation,
+  EffectRecord,
+  EffectState,
+  JsonObject,
+  JsonPrimitive,
+  JsonValue,
+  MaybePromise,
+  ReconcileContext,
+  ReconcileResult,
+} from "./types.js";

package/src/resource-managers/loader.ts

@@ -0,0 +1,111 @@
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { createJiti } from "jiti";
+import { isResourceManagerDefinition } from "./definition.js";
+import type { AnyResourceManagerDefinition } from "./types.js";
+
+const RESOURCE_MANAGER_FILE_SUFFIXES = [
+  ".resource-manager.ts",
+  ".resource-manager.js",
+  ".resource-manager.mts",
+  ".resource-manager.mjs",
+];
+
+export type DiscoveredResourceManager = {
+  name: string;
+  path: string;
+  source: "project" | "global";
+};
+
+export function resourceManagerSearchDirs(options: {
+  cwd: string;
+  homeDir?: string;
+}): { dir: string; source: DiscoveredResourceManager["source"] }[] {
+  const homeDir = options.homeDir ?? os.homedir();
+  return [
+    { dir: path.join(options.cwd, ".pi", "resource-managers"), source: "project" },
+    { dir: path.join(homeDir, ".pi", "agent", "resource-managers"), source: "global" },
+  ];
+}
+
+export function resourceManagerFileStem(filePath: string): string {
+  const base = path.basename(filePath);
+  const suffix = RESOURCE_MANAGER_FILE_SUFFIXES.find((candidate) => base.endsWith(candidate));
+  return suffix === undefined ? base : base.slice(0, -suffix.length);
+}
+
+const RESOURCE_MANAGER_ENTRY = path.join(path.dirname(fileURLToPath(import.meta.url)), "index");
+const WORKFLOW_ENTRY = path.join(
+  path.dirname(fileURLToPath(import.meta.url)),
+  "../workflows/index",
+);
+
+export async function loadResourceManagerFile(
+  filePath: string,
+): Promise<AnyResourceManagerDefinition> {
+  const absolutePath = path.resolve(filePath);
+  const jiti = createJiti(pathToFileURL(absolutePath).href, {
+    interopDefault: true,
+    moduleCache: false,
+    alias: {
+      "@osolmaz/pi-workflows/resource-managers": RESOURCE_MANAGER_ENTRY,
+      "@osolmaz/pi-workflows": WORKFLOW_ENTRY,
+    },
+  });
+  const loaded = (await jiti.import(absolutePath, { default: true })) as unknown;
+  if (!isResourceManagerDefinition(loaded)) {
+    throw new Error(
+      `ResourceManager module must default-export defineResourceManager(...): ${absolutePath}`,
+    );
+  }
+  return loaded;
+}
+
+export async function discoverResourceManagers(options: {
+  cwd: string;
+  homeDir?: string;
+}): Promise<DiscoveredResourceManager[]> {
+  const discovered: DiscoveredResourceManager[] = [];
+  const seen = new Set<string>();
+  for (const { dir, source } of resourceManagerSearchDirs(options)) {
+    for (const filePath of await listResourceManagerFiles(dir)) {
+      const name = resourceManagerFileStem(filePath);
+      if (seen.has(name)) {
+        continue;
+      }
+      seen.add(name);
+      discovered.push({ name, path: filePath, source });
+    }
+  }
+  return discovered;
+}
+
+export async function loadDiscoveredResourceManagers(options: {
+  cwd: string;
+  homeDir?: string;
+}): Promise<AnyResourceManagerDefinition[]> {
+  return await Promise.all(
+    (await discoverResourceManagers(options)).map(
+      async (entry) => await loadResourceManagerFile(entry.path),
+    ),
+  );
+}
+
+async function listResourceManagerFiles(dir: string): Promise<string[]> {
+  let entries: import("node:fs").Dirent[];
+  try {
+    entries = await fs.readdir(dir, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  return entries
+    .filter(
+      (entry) =>
+        entry.isFile() &&
+        RESOURCE_MANAGER_FILE_SUFFIXES.some((suffix) => entry.name.endsWith(suffix)),
+    )
+    .map((entry) => path.join(dir, entry.name))
+    .sort();
+}

package/src/{controllers → resource-managers}/results.ts

@@ -1,4 +1,4 @@
-import type { ControllerStatusPatch, ReconcileContext, ReconcileResult } from "./types.js";
+import type { ResourceManagerStatusPatch, ReconcileContext, ReconcileResult } from "./types.js";
 
 export function createResultHelpers<TStatus>(): Pick<
   ReconcileContext<TStatus>,
@@ -27,20 +27,20 @@ export function createResultHelpers<TStatus>(): Pick<
 }
 
 export function settled<TStatus>(
-  status?: ControllerStatusPatch<TStatus>,
+  status?: ResourceManagerStatusPatch<TStatus>,
 ): ReconcileResult<TStatus> {
   return createResultHelpers<TStatus>().settled(status);
 }
 
 export function requeue<TStatus>(
-  status?: ControllerStatusPatch<TStatus>,
+  status?: ResourceManagerStatusPatch<TStatus>,
 ): ReconcileResult<TStatus> {
   return createResultHelpers<TStatus>().requeue(status);
 }
 
 export function requeueAfter<TStatus>(
   afterMs: number,
-  status?: ControllerStatusPatch<TStatus>,
+  status?: ResourceManagerStatusPatch<TStatus>,
 ): ReconcileResult<TStatus> {
   return createResultHelpers<TStatus>().requeueAfter(afterMs, status);
 }