@vite-hub/workflow 0.0.4 → 0.1.0

package/dist/operations-B_rYG71W.js

@@ -0,0 +1,230 @@
+import { a as resumeWorkflowSignal, i as getWorkflowRun, o as runWorkflow, t as cancelWorkflow } from "./client-DsGM3M4U.js";
+import { getInlineWorkflowDefinitions, getWorkflowRuntimeConfig, getWorkflowRuntimeRegistry } from "./runtime/state.js";
+import { n as redactInspectionValue, t as redactInspectionText } from "./inspect-B72iFyj-.js";
+//#region src/results.ts
+const inlineRunNote = "Runs the Workflow inline in the Nitro runtime, as the app does in development. Inline runs are not durable and have no retries.";
+function unsupported(note) {
+	return {
+		note,
+		supported: false
+	};
+}
+/**
+* Operations that each provider supports. A supported operation can still fail when the runtime decides, for example
+* cancel on an inline Vercel run.
+*/
+function resolveWorkflowOperationSupport(provider) {
+	if (provider === "cloudflare") return {
+		cancel: unsupported("Cloudflare Workflows do not support cancellation through ViteHub."),
+		get: {
+			note: "Reads the run from the Cloudflare Workflow binding when the runtime has one.",
+			supported: true
+		},
+		resume: unsupported("Cloudflare Workflows do not support ViteHub signals."),
+		start: {
+			note: `Uses the Cloudflare Workflow binding when the runtime has one. Otherwise: ${inlineRunNote}`,
+			supported: true
+		}
+	};
+	if (provider === "openworkflow") return {
+		cancel: unsupported("OpenWorkflow does not support cancellation through ViteHub."),
+		get: {
+			note: "Reads the run from OpenWorkflow storage.",
+			supported: true
+		},
+		resume: unsupported("OpenWorkflow does not support ViteHub signals."),
+		start: {
+			note: "Enqueues the run in OpenWorkflow storage. The run stays queued until an OpenWorkflow worker processes the same storage.",
+			supported: true
+		}
+	};
+	return {
+		cancel: {
+			note: "Only native Vercel Workflow runs can be cancelled. Inline runs return an unsupported error.",
+			supported: true
+		},
+		get: {
+			note: "Reads inline runs, which expire 5 minutes after they finish. Native Vercel Workflow runs need the Workflow DevKit runtime.",
+			supported: true
+		},
+		resume: {
+			note: "Signals need a native Vercel Workflow run and the Workflow DevKit runtime.",
+			supported: true
+		},
+		start: {
+			note: `${inlineRunNote} Native Vercel Workflow Definitions need the Workflow DevKit runtime.`,
+			supported: true
+		}
+	};
+}
+//#endregion
+//#region src/runtime/operations.ts
+const maxRememberedRuns = 1024;
+/** A failure of a Workflow operation, with the status and code that every surface reports. */
+var WorkflowOperationError = class extends Error {
+	code;
+	fix;
+	status;
+	constructor(message, status, code, fix) {
+		super(message);
+		this.name = "WorkflowOperationError";
+		this.code = code;
+		this.status = status;
+		if (fix) this.fix = fix;
+	}
+};
+function isRecord(value) {
+	return !!value && typeof value === "object" && !Array.isArray(value);
+}
+function isResponse(value) {
+	if (value instanceof Response) return true;
+	const statusGetter = Object.getOwnPropertyDescriptor(Response.prototype, "status")?.get;
+	if (!statusGetter) return false;
+	try {
+		statusGetter.call(value);
+		return true;
+	} catch {
+		return false;
+	}
+}
+function jsonReplacer(_key, value) {
+	if (typeof value === "bigint") return value.toString();
+	if (value instanceof Error) return serializeError(value);
+	if (isResponse(value)) return { response: {
+		status: value.status,
+		statusText: value.statusText
+	} };
+	return value;
+}
+function toJsonValue(value) {
+	if (value === void 0) return void 0;
+	try {
+		const text = JSON.stringify(value, jsonReplacer);
+		return text === void 0 ? void 0 : redactInspectionValue(JSON.parse(text));
+	} catch {
+		return "[unserializable]";
+	}
+}
+function errorCode(error) {
+	if (!error || typeof error !== "object") return;
+	const code = Reflect.get(error, "code");
+	return typeof code === "string" ? code : void 0;
+}
+function serializeError(error) {
+	const code = errorCode(error);
+	return {
+		...code ? { code } : {},
+		message: redactInspectionText(error.message),
+		...error.name && error.name !== "Error" ? { name: error.name } : {}
+	};
+}
+function toIsoDate(value) {
+	if (value instanceof Date) return Number.isNaN(value.getTime()) ? void 0 : value.toISOString();
+	return typeof value === "string" ? value : void 0;
+}
+function isErrorLike(value) {
+	return value instanceof Error || isRecord(value) && typeof value.message === "string";
+}
+async function readResult(result) {
+	if (!isResponse(result)) return result;
+	const text = await result.clone().text();
+	if (!text) return void 0;
+	try {
+		return JSON.parse(text);
+	} catch {
+		return text;
+	}
+}
+/**
+* Converts a runtime Workflow run to JSON data. The view omits the start
+* payload and redacts credentials in the metadata, result, and error message.
+*/
+async function toWorkflowRunView(run, workflow) {
+	const createdAt = toIsoDate(run.createdAt);
+	const startedAt = toIsoDate(run.startedAt);
+	const completedAt = toIsoDate(run.completedAt);
+	const error = run.status === "failed" && isErrorLike(run.metadata) ? serializeError(run.metadata) : void 0;
+	const metadata = error ? void 0 : toJsonValue(run.metadata);
+	const result = toJsonValue(await readResult(run.result));
+	return {
+		...completedAt ? { completedAt } : {},
+		...createdAt ? { createdAt } : {},
+		...error ? { error } : {},
+		id: run.id,
+		...metadata === void 0 ? {} : { metadata },
+		provider: run.provider,
+		...result === void 0 ? {} : { result },
+		...startedAt ? { startedAt } : {},
+		status: run.status,
+		workflow
+	};
+}
+function runtimeFailure(operation, provider, error) {
+	if (error instanceof WorkflowOperationError) return error;
+	const code = errorCode(error);
+	if (code === "WORKFLOW_OPERATION_UNSUPPORTED") return new WorkflowOperationError(`workflow ${operation} is not supported by the ${provider} provider for this run.`, 501, code);
+	if (code === "WORKFLOW_DISABLED") return new WorkflowOperationError("Workflow is disabled in this runtime.", 409, code, "Enable Workflow with `vitehub({ workflow: true })` or `hubWorkflow()`.");
+	if (code === "WORKFLOW_DEFINITION_NOT_FOUND") return new WorkflowOperationError("Workflow definition was not found.", 404, code);
+	if (code === "VERCEL_WORKFLOW_SDK_LOAD_FAILED" || code === "WORKFLOW_NATIVE_ENTRY_INVALID" || code === "WORKFLOW_NATIVE_ENTRY_REQUIRED") return new WorkflowOperationError(`workflow ${operation} needs the Vercel Workflow DevKit runtime, which the runtime could not load.`, 501, code);
+	if (code === "WORKFLOW_PROVIDER_OPERATION_FAILED") {
+		const cause = error instanceof Error ? error.cause : void 0;
+		return new WorkflowOperationError(`workflow ${operation} failed in the ${provider} provider.${cause instanceof Error && cause.message ? ` ${redactInspectionText(cause.message)}` : ""}`, 502, code);
+	}
+	const message = error instanceof Error ? error.message : String(error);
+	return new WorkflowOperationError(redactInspectionText(message || "The Workflow operation failed."), 500, code || "WORKFLOW_OPERATION_FAILED");
+}
+function startableWorkflows() {
+	return [.../* @__PURE__ */ new Set([...Object.keys(getWorkflowRuntimeRegistry() ?? {}), ...getInlineWorkflowDefinitions().keys()])].sort();
+}
+const startedRuns = /* @__PURE__ */ new Map();
+function rememberRun(id, workflow) {
+	startedRuns.delete(id);
+	startedRuns.set(id, workflow);
+	if (startedRuns.size > maxRememberedRuns) {
+		const oldest = startedRuns.keys().next().value;
+		if (oldest !== void 0) startedRuns.delete(oldest);
+	}
+}
+/**
+* Runs one Workflow operation in the runtime of the app, so it uses the same Workflow state and registry as the app.
+* It redacts credentials in run data and error messages. Failures are `WorkflowOperationError`s.
+*/
+async function runWorkflowOperation(operation, input) {
+	const runtimeConfig = getWorkflowRuntimeConfig();
+	if (runtimeConfig === false) throw new WorkflowOperationError("Workflow is disabled in this runtime.", 409, "WORKFLOW_DISABLED", "Enable Workflow with `vitehub({ workflow: true })` or `hubWorkflow()`.");
+	const provider = runtimeConfig?.provider ?? "vercel";
+	const support = resolveWorkflowOperationSupport(provider)[operation];
+	if (!support.supported) throw new WorkflowOperationError(`workflow ${operation} is not supported by the ${provider} provider. ${support.note}`, 501, "WORKFLOW_OPERATION_UNSUPPORTED");
+	try {
+		return await run(operation, input);
+	} catch (error) {
+		throw runtimeFailure(operation, provider, error);
+	}
+}
+async function run(operation, input) {
+	if (operation === "start") {
+		const { payload, workflow } = input;
+		const workflows = startableWorkflows();
+		if (!workflows.includes(workflow)) {
+			if (!getWorkflowRuntimeRegistry()) throw new WorkflowOperationError(`Unknown Workflow: ${workflow}. The runtime has no Workflow registry.`, 409, "WORKFLOW_REGISTRY_MISSING", "Restart the dev server. In development the Workflow Vite plugin installs the registry with the Nitro plugin .vitehub/nitro/workflow/dev-plugin.mjs.");
+			throw new WorkflowOperationError(`Unknown Workflow: ${workflow}.${workflows.length ? ` Available Workflows: ${workflows.join(", ")}.` : " The Workflow registry of the runtime is empty."}`, 404, "WORKFLOW_DEFINITION_NOT_FOUND");
+		}
+		const started = await runWorkflow(workflow, payload);
+		rememberRun(started.id, workflow);
+		return { run: await toWorkflowRunView(started, workflow) };
+	}
+	if (operation === "resume") {
+		const { payload, token } = input;
+		const signal = await resumeWorkflowSignal(token, payload);
+		return { signal: {
+			id: signal.id,
+			provider: signal.provider
+		} };
+	}
+	const { runId, workflow: named } = input;
+	const workflow = named ?? startedRuns.get(runId);
+	if (!workflow) throw new WorkflowOperationError(`Run ${runId} was not started by \`workflow.start\` in this runtime.`, 400, "WORKFLOW_RUN_UNKNOWN", "Pass the name of the Workflow with `--workflow <name>`.");
+	return { run: await toWorkflowRunView(operation === "get" ? await getWorkflowRun(workflow, runId) : await cancelWorkflow(workflow, runId), workflow) };
+}
+//#endregion
+export { WorkflowOperationError, runWorkflowOperation, toWorkflowRunView };

package/dist/operations-tNUdj3G4.d.ts

@@ -0,0 +1,212 @@
+//#region ../../node_modules/.pnpm/@standard-schema+spec@1.1.0/node_modules/@standard-schema/spec/dist/index.d.ts
+/** The Standard Typed interface. This is a base type extended by other specs. */
+interface StandardTypedV1<Input = unknown, Output = Input> {
+  /** The Standard properties. */
+  readonly "~standard": StandardTypedV1.Props<Input, Output>;
+}
+declare namespace StandardTypedV1 {
+  /** The Standard Typed properties interface. */
+  interface Props<Input = unknown, Output = Input> {
+    /** The version number of the standard. */
+    readonly version: 1;
+    /** The vendor name of the schema library. */
+    readonly vendor: string;
+    /** Inferred types associated with the schema. */
+    readonly types?: Types<Input, Output> | undefined;
+  }
+  /** The Standard Typed types interface. */
+  interface Types<Input = unknown, Output = Input> {
+    /** The input type of the schema. */
+    readonly input: Input;
+    /** The output type of the schema. */
+    readonly output: Output;
+  }
+  /** Infers the input type of a Standard Typed. */
+  type InferInput<Schema extends StandardTypedV1> = NonNullable<Schema["~standard"]["types"]>["input"];
+  /** Infers the output type of a Standard Typed. */
+  type InferOutput<Schema extends StandardTypedV1> = NonNullable<Schema["~standard"]["types"]>["output"];
+}
+/** The Standard Schema interface. */
+interface StandardSchemaV1<Input = unknown, Output = Input> {
+  /** The Standard Schema properties. */
+  readonly "~standard": StandardSchemaV1.Props<Input, Output>;
+}
+declare namespace StandardSchemaV1 {
+  /** The Standard Schema properties interface. */
+  interface Props<Input = unknown, Output = Input> extends StandardTypedV1.Props<Input, Output> {
+    /** Validates unknown input values. */
+    readonly validate: (value: unknown, options?: StandardSchemaV1.Options | undefined) => Result<Output> | Promise<Result<Output>>;
+  }
+  /** The result interface of the validate function. */
+  type Result<Output> = SuccessResult<Output> | FailureResult;
+  /** The result interface if validation succeeds. */
+  interface SuccessResult<Output> {
+    /** The typed output value. */
+    readonly value: Output;
+    /** A falsy value for `issues` indicates success. */
+    readonly issues?: undefined;
+  }
+  interface Options {
+    /** Explicit support for additional vendor-specific parameters, if needed. */
+    readonly libraryOptions?: Record<string, unknown> | undefined;
+  }
+  /** The result interface if validation fails. */
+  interface FailureResult {
+    /** The issues of failed validation. */
+    readonly issues: ReadonlyArray<Issue>;
+  }
+  /** The issue interface of the failure output. */
+  interface Issue {
+    /** The error message of the issue. */
+    readonly message: string;
+    /** The path of the issue, if any. */
+    readonly path?: ReadonlyArray<PropertyKey | PathSegment> | undefined;
+  }
+  /** The path segment interface of the issue. */
+  interface PathSegment {
+    /** The key representing a path segment. */
+    readonly key: PropertyKey;
+  }
+  /** The Standard types interface. */
+  interface Types<Input = unknown, Output = Input> extends StandardTypedV1.Types<Input, Output> {}
+  /** Infers the input type of a Standard. */
+  type InferInput<Schema extends StandardTypedV1> = StandardTypedV1.InferInput<Schema>;
+  /** Infers the output type of a Standard. */
+  type InferOutput<Schema extends StandardTypedV1> = StandardTypedV1.InferOutput<Schema>;
+}
+//#endregion
+//#region ../internal/src/operations.d.ts
+/** `read` never changes state. `write` changes state. `destructive` deletes or publishes. */
+type OperationKind = "read" | "write" | "destructive";
+/** The signed-in user of a call. */
+interface OperationUser {
+  id: string;
+  name?: string;
+  email?: string;
+  image?: string;
+  [key: string]: unknown;
+}
+/** The Agent Actor when an agent calls through a capability or MCP on behalf of a user. */
+interface OperationActor {
+  id: string;
+  kind?: string;
+  label?: string;
+  meta?: object;
+}
+/** The checked Console access of a call. `vite-hub` issues it. `ConsoleAccess` has this shape. */
+interface OperationAccess {
+  readonly mode: string;
+  /**
+   * The sections that the call may use. `"all"` when no section filter applies. An entry is a section id (`"kv"`, every
+   * operation of the section) or `"<section>:read"` (only the operations that read).
+   */
+  readonly sections: "all" | readonly string[];
+  readonly user?: OperationUser;
+}
+interface OperationContext {
+  /** The checked Console access of the call. */
+  access: OperationAccess;
+  /** The signed-in user, or null. */
+  user: OperationUser | null;
+  /** The Agent Actor when an agent calls on behalf of `user`. */
+  actor?: OperationActor;
+  surface: "console" | "cli" | "mcp" | "agent";
+  /** Set by the host from generated build identity, never from request input or runtime NODE_ENV. */
+  development?: boolean;
+  env?: Record<string, unknown>;
+  waitUntil?: (task: Promise<unknown>) => void;
+  request?: Request;
+  /** Operations set a success status here, such as 202 for an accepted call. */
+  response?: {
+    status?: number;
+  };
+  /**
+   * An agent or an MCP client may pass `lease: "override"` to `content.save`, `content.remove`, and `content.restore`
+   * only when the developer allowed it. Defaults to false, so a model cannot take over a document that a person is editing.
+   */
+  overrideLeases?: boolean;
+  /**
+   * What an Agent may read of the Channel conversations, set by `operations({ conversations })`. `participant`: only the
+   * threads that the Actor takes part in. `all`: every thread. Unset: none.
+   */
+  conversations?: "all" | "participant";
+}
+interface OperationDefinition<Input, Output> {
+  /** `<section>.<verb>`, such as `content.publish`. Unique per app. */
+  name: string;
+  /** One sentence. Becomes the CLI help line and the MCP tool description. */
+  description: string;
+  /**
+   * Console section that grants access, such as `content`. `false`: any Console user. A function reads the section
+   * from the input, for operations that serve several sections.
+   */
+  section: string | false | ((input: Input) => string | undefined);
+  /** `read` never changes state. `write` changes state. `destructive` deletes or publishes; the CLI asks for `--yes`, MCP marks `destructiveHint`, agents require approval by default. */
+  kind: OperationKind;
+  /** Standard Schema (valibot in this repo). Its Standard JSON Schema builds CLI flags and the MCP input schema. */
+  input: StandardSchemaV1<unknown, Input>;
+  output?: StandardSchemaV1<unknown, Output>;
+  cli?: {
+    /** Defaults: namespace = section, command = verb. */
+    namespace?: string;
+    command?: string;
+    /** Input keys read from positional arguments, in order. */
+    positional?: string[];
+    /** Human output, written verbatim. Without it the CLI prints JSON. `--json` always prints JSON. */
+    format?: (output: Output) => string;
+    /** `vitehub <namespace>` runs this command when no command is named, such as `vitehub usage`. */
+    default?: boolean;
+    /**
+     * Route of the app that takes a signed dispatch of this operation, such as `/_vitehub/schedules/run`. With `--url`
+     * and a dispatch key in the environment (`VITEHUB_DISPATCH_KEY`), the command signs the input and posts it there, so
+     * a CI job needs no Console credentials. Without a key it calls the RPC.
+     */
+    dispatch?: string;
+  };
+  /** Largest request body in bytes. It can raise the 64 KiB default but not lower it. */
+  maxRequestBytes?: number;
+  /**
+   * Returns true when this call only reads, such as a dry run of a `destructive` operation. The CLI then skips the
+   * confirmation, and agents run it without approval. Without it, every call of a `destructive` operation asks.
+   */
+  readOnlyWhen?: (input: Input) => boolean;
+  /** `false`: MCP does not offer the operation as a tool, such as an editor transport that only the Console uses. */
+  mcp?: false;
+  /** `false`: the operation never reads `context.user`, so the Console skips the session lookup for it. */
+  user?: false;
+  /**
+   * The operation runs code of the app, such as a workflow, a job, a task, or a schedule. The Console registers it only
+   * when `console.invoke` is on, which is the default in development and off in a production build.
+   */
+  invoke?: true;
+  run: (input: Input, context: OperationContext) => Output | Promise<Output>;
+}
+/** An operation of any input and output, as a registry holds it. */
+interface AnyOperation extends Omit<OperationDefinition<unknown, unknown>, "cli" | "input" | "output" | "readOnlyWhen" | "run" | "section"> {
+  readOnlyWhen?: (input: never) => boolean;
+  cli?: {
+    namespace?: string;
+    command?: string;
+    default?: boolean;
+    dispatch?: string;
+    positional?: string[];
+    format?: (output: never) => string;
+  };
+  input: StandardSchemaV1;
+  output?: StandardSchemaV1;
+  run: (input: never, context: OperationContext) => unknown;
+  section: string | false | ((input: never) => string | undefined);
+}
+/** The contribution of one plugin: operations, or a module that exports them. */
+interface OperationContributionEntry {
+  /** Module the app imports, such as `@vite-hub/content/operations`. */
+  module: string;
+  /** Named export that holds an operation or an array of operations. Defaults to `default`. */
+  export?: string;
+  /** Loads the export in the tool process, for a module that the tool cannot resolve by name. */
+  load?: () => Promise<unknown>;
+  /** `false`: the app already has these operations at runtime. Only tools such as the CLI and `vitehub inspect` read the entry. */
+  runtime?: false;
+}
+//#endregion
+export { OperationContributionEntry as n, AnyOperation as t };

package/dist/operations.d.ts

@@ -0,0 +1,37 @@
+import { E as WorkflowRunStatus, x as WorkflowProvider } from "./types-D82WmfZa.js";
+import { t as AnyOperation } from "./operations-tNUdj3G4.js";
+//#region src/results.d.ts
+/** One Workflow run as the operations return it. The start payload is not included. */
+interface WorkflowRunView {
+  completedAt?: string;
+  createdAt?: string;
+  error?: {
+    code?: string;
+    message: string;
+    name?: string;
+  };
+  id: string;
+  metadata?: unknown;
+  provider: WorkflowProvider;
+  result?: unknown;
+  startedAt?: string;
+  status: WorkflowRunStatus;
+  workflow: string;
+}
+/** The signal that `workflow.resume` delivered. */
+interface WorkflowSignalView {
+  id: string;
+  provider: WorkflowProvider;
+}
+interface WorkflowRunResult {
+  run: WorkflowRunView;
+}
+interface WorkflowSignalResult {
+  signal: WorkflowSignalView;
+}
+//#endregion
+//#region src/operations.d.ts
+/** The `workflow.*` operations: start, get, cancel, and resume. The Console, `vitehub workflow`, and agents run them. */
+export declare const workflowOperations: readonly AnyOperation[];
+//#endregion
+export type { WorkflowRunResult, WorkflowRunView, WorkflowSignalResult, WorkflowSignalView };