@vite-hub/workflow 0.0.3 → 0.1.0

package/dist/vite.d.ts

@@ -1,13 +1,372 @@
-import { y as WorkflowModuleOptions } from "./types-BUlYBZwH.js";
-import { Plugin } from "vite";
-
+import { i as DiscoveredWorkflowDefinition, y as WorkflowModuleOptions } from "./types-D82WmfZa.js";
+import { n as OperationContributionEntry } from "./operations-tNUdj3G4.js";
+import { Plugin } from "esbuild";
+import { Plugin as Plugin$1, ResolvedConfig } from "vite";
+//#region ../internal/src/inspect.d.ts
+interface ViteHubDefinitionField {
+  label: string;
+  value: string;
+}
+/** Serializable summary of one discovered Definition. Files are relative to the project root. */
+interface ViteHubDefinitionSummary {
+  fields: readonly ViteHubDefinitionField[];
+  file: string;
+  name: string;
+  source: string;
+}
+/** Lists the Definitions that one owner package discovered for the resolved Vite config. */
+interface ViteHubDefinitionInspector {
+  /** Stable singular kind, for example `queue` or `rate-limit`. */
+  kind: string;
+  label: string;
+  list: () => Promise<readonly ViteHubDefinitionSummary[]> | readonly ViteHubDefinitionSummary[];
+}
+/** One generated Provider Output file or directory that an owner package can write. */
+interface ViteHubProviderOutputEntry {
+  description: string;
+  owner: string;
+  /** Absolute path. */
+  path: string;
+}
+interface ViteHubInspectionContributor {
+  definitions?: readonly ViteHubDefinitionInspector[];
+  providerOutput?: readonly ViteHubProviderOutputEntry[];
+}
+type ViteHubInspectionContributorFactory = () => ViteHubInspectionContributor | undefined | Promise<ViteHubInspectionContributor | undefined>;
+interface ViteHubInspectionPluginMetadata {
+  inspect?: ViteHubInspectionContributor | ViteHubInspectionContributorFactory;
+}
+//#endregion
+//#region src/discovery.d.ts
+export declare function discoverWorkflowDefinitions(options: {
+  mode?: "vite-suffix";
+  rootDir: string;
+  scanDirs?: string[];
+  serverDirs?: string[];
+} | {
+  mode: "server-workflows";
+  scanDirs: string[];
+}): DiscoveredWorkflowDefinition[];
+//#endregion
+//#region ../internal/src/console.d.ts
+type MaybePromise<T> = T | Promise<T>;
+/** Lists discovered Definitions in a sidebar and shows the selected Definition's fields. */
+interface ViteHubConsoleDefinitionCatalogView {
+  kind: "definition-catalog";
+  /** States which runtime data this catalog does not include. */
+  notice: string;
+}
+interface ViteHubConsoleRecordColumn {
+  /** Key in `ViteHubConsoleRecord.cells`. */
+  key: string;
+  label: string;
+}
+/** Shows records in a table and the selected record's fields in a detail panel. */
+interface ViteHubConsoleRecordTableView {
+  columns: readonly ViteHubConsoleRecordColumn[];
+  kind: "record-table";
+  /** States the source and limits of the records. */
+  notice: string;
+}
+/**
+ * Lists the collections and documents of an owner runtime and edits them with owner actions: a form generated from each
+ * collection's JSON Schema, a Markdown body, save, publish, and revision history.
+ */
+interface ViteHubConsoleDocumentEditorView {
+  kind: "document-editor";
+  /** States where documents are stored and what the editor does not do. */
+  notice: string;
+}
+interface ViteHubConsoleOperationColumn {
+  /** Dot path into each item of the result, such as `author.name` or `messages.0.body`. */
+  key: string;
+  label: string;
+  /** `datetime` shows a time in milliseconds since the epoch as a date. `excerpt` cuts a long text. */
+  format?: "datetime" | "excerpt";
+}
+/** A chip above the list. Choosing it merges `input` into the operation input. The first chip is the default. */
+interface ViteHubConsoleOperationFilter {
+  id: string;
+  label: string;
+  input: Readonly<Record<string, unknown>>;
+}
+/**
+ * Lists the items that an operation returns, called over the Console RPC with the signed-in Console user. The operation
+ * checks the access of that user for each item, so the view shows only what the user may read. `operation` must return an
+ * array of objects with an `id`. A failure of the operation, with its `fix`, shows where the list would be.
+ */
+interface ViteHubConsoleOperationView {
+  columns: readonly ViteHubConsoleOperationColumn[];
+  filters?: readonly ViteHubConsoleOperationFilter[];
+  kind: "operation-view";
+  /**
+   * Makes each row a link: `{path}` placeholders take values from the item and are URL-encoded, and `{path:path}` takes an
+   * app path and encodes each segment (a value that is not an app path, such as `//evil.com/x`, gives no link). Rows where
+   * `when.path` is not `when.equals` get none.
+   */
+  link?: {
+    label?: string;
+    template: string;
+    when?: {
+      equals: string;
+      path: string;
+    };
+  };
+  notice: string;
+  /** Operation name, such as `comments.list`. */
+  operation: string;
+  /** Fetch every page with `limit` and a `before` object whose keys read these dot paths from the last item. */
+  pagination?: {
+    limit: number;
+    cursor: Readonly<Record<string, string>>;
+  };
+}
+interface ViteHubConsoleAuthView {
+  kind: "auth-management";
+  notice: string;
+}
+interface ViteHubConsoleAuthSection extends ViteHubConsoleSectionDescriptor<ViteHubConsoleAuthView> {}
+type ViteHubConsoleSectionView = ViteHubConsoleOperationView | ViteHubConsoleAuthView | ViteHubConsoleDefinitionCatalogView | ViteHubConsoleRecordTableView | ViteHubConsoleDocumentEditorView;
+/**
+ * The overview of a document editor section: document counts by state, the changes that wait for a publish, recent
+ * activity, and a New button per collection. It reads the owner `overview` action.
+ */
+interface ViteHubConsoleDocumentDashboardView {
+  kind: "document-dashboard";
+}
+/**
+ * The media library of a document editor section: folders, uploads, alt text, focal points, and crops of the Blob Store
+ * that `blob.serve` serves. The owner decides who may use it with `mediaAccess`, and finds the documents that use a file
+ * with `references`. The page needs the Blob section, so declare it with `requires: ["blob"]`.
+ */
+interface ViteHubConsoleMediaLibraryView {
+  kind: "media-library";
+}
+/**
+ * The singletons of a document editor section, such as site settings: one row per singleton that opens it in the
+ * editor. Singletons appear here instead of among the collections, and the Console hides the page when the section has
+ * none.
+ */
+interface ViteHubConsoleDocumentSettingsView {
+  kind: "document-settings";
+}
+/** A view that the Console UI in `vite-hub` renders for a section page. */
+type ViteHubConsoleSectionPageView = ViteHubConsoleDocumentDashboardView | ViteHubConsoleDocumentSettingsView | ViteHubConsoleMediaLibraryView;
+/**
+ * A page of a section next to its main view, such as the Content dashboard or media library. The section sidebar lists
+ * the pages, and each page has its own URL:
+ *
+ * - `/_vitehub/<section>` serves the `index` page, or the main view when the section has none.
+ * - `/_vitehub/<section>/-/<page>` serves every other page. The `-` segment keeps page URLs apart from the main view's
+ *   own segments, such as a collection name.
+ *
+ * Pages share the access of their section: `console.authorize` that allows the section allows every page of it.
+ */
+interface ViteHubConsoleSectionPage {
+  /** Lowercase route segment, for example `media`. */
+  id: string;
+  /** Display name, for example `Media`. */
+  label: string;
+  /** Iconify class name, for example `i-lucide-image`. */
+  icon: string;
+  view: ViteHubConsoleSectionPageView;
+  /**
+   * Serve this page at the section root. At most one page sets it, and `/_vitehub/<section>/-/<id>` then redirects to
+   * the root.
+   */
+  index?: boolean;
+  /**
+   * Sidebar heading, for example `Assets`. Pages without a group lead the sidebar, above the main view's navigation.
+   * Grouped pages follow it, in the order their group first appears.
+   */
+  group?: string;
+  /** Section ids that the project must enable, such as `["blob"]`. The Console leaves the page out otherwise. */
+  requires?: readonly string[];
+}
+/** One entry of a record's activity, such as a comment in a thread. `at` is an ISO 8601 timestamp. */
+interface ViteHubConsoleRecordActivity {
+  author: string;
+  at: string;
+  text: string;
+}
+/** One serializable record row. Values are display strings. Do not put credentials in records. */
+interface ViteHubConsoleRecord {
+  cells: Readonly<Record<string, string>>;
+  fields: readonly ViteHubDefinitionField[];
+  id: string;
+  /** The Console can run this record when it represents a runnable Schedule Definition. */
+  runnable?: boolean;
+  /**
+   * Where the record lives in the app, such as the page of a comment thread. `href` is an app path that starts with one
+   * `/`, or an `https:` URL. The Console opens it in a new tab.
+   */
+  link?: {
+    href: string;
+    label: string;
+  };
+  /** Entries in time order, such as the comments of a thread. The Console shows them as a conversation. */
+  activity?: readonly ViteHubConsoleRecordActivity[];
+}
+/** Serializable description of a Console section. The Console UI in `vite-hub` renders the view. */
+interface ViteHubConsoleSectionDescriptor<TView extends ViteHubConsoleSectionView = ViteHubConsoleSectionView> {
+  description: string;
+  /**
+   * Iconify class name, for example `i-lucide-inbox`. The Console draws with Lucide; `ph` also resolves. The
+   * Console build bundles the icon of every section in the `vite-hub` Console registry and fails if it cannot resolve one.
+   */
+  icon: string;
+  /** Lowercase route segment, for example `queues`. The Console serves the section at `/_vitehub/<id>`. */
+  id: string;
+  /** Plural display name, for example `Queues`. */
+  label: string;
+  view: TView;
+  /** Pages next to the main view, in sidebar order. Only document editor sections render pages today. */
+  pages?: readonly ViteHubConsoleSectionPage[];
+}
+interface ViteHubConsoleDefinitionCatalogSection<TOptions = void> extends ViteHubConsoleSectionDescriptor<ViteHubConsoleDefinitionCatalogView> {
+  /** Reads the section data on the server. The Console never runs it in the browser. */
+  read: (options: TOptions) => MaybePromise<readonly ViteHubDefinitionSummary[]>;
+}
+interface ViteHubConsoleRecordTableSection<TOptions = void> extends ViteHubConsoleSectionDescriptor<ViteHubConsoleRecordTableView> {
+  /** Reads the section data on the server. The Console never runs it in the browser. */
+  read: (options: TOptions) => MaybePromise<readonly ViteHubConsoleRecord[]>;
+}
+/** A named export of an owner package server module that the host imports in its generated server code. */
+interface ViteHubConsoleServerExport {
+  /** Named export of `module`. */
+  export: string;
+  /**
+   * Owner package module specifier, for example `@vite-hub/email/runtime/console`. The host maps it to the module
+   * path that the application can import.
+   */
+  module: string;
+}
+/**
+ * Server module export that returns records on each Console request. The export must be a
+ * {@link ViteHubConsoleRuntimeRecordReader}.
+ */
+interface ViteHubConsoleRuntimeReader extends ViteHubConsoleServerExport {}
+/**
+ * A record table that also reads records at request time. The Console shows the build-time records of `read` first,
+ * then the records of the `runtime` reader. A runtime record replaces a build-time record with the same id.
+ */
+interface ViteHubConsoleRuntimeRecordTableSection<TOptions = void> extends ViteHubConsoleSectionDescriptor<ViteHubConsoleRecordTableView> {
+  /** Reads build-time records on the server. When omitted, the section has only runtime records. */
+  read?: (options: TOptions) => MaybePromise<readonly ViteHubConsoleRecord[]>;
+  runtime: ViteHubConsoleRuntimeReader;
+  /**
+   * Returns the absolute path of the application module that turns the section on, such as `server/comments.ts`, or
+   * `undefined` when the project has none. With it, the host shows the section only when the module exists; without
+   * it, a Vite option enables the section.
+   */
+  entry?: (options: TOptions) => MaybePromise<string | undefined>;
+}
+/** A section whose list comes from an operation, called with the Console user on each visit. It has no build-time data. */
+interface ViteHubConsoleOperationSection extends ViteHubConsoleSectionDescriptor<ViteHubConsoleOperationView> {}
+/**
+ * A document editor section. The owner finds the application module that holds its runtime, such as `server/content.ts`,
+ * and names the server export that turns that module into {@link ViteHubConsoleDocumentActions}. The host shows the
+ * section only when `entry` finds a module, imports the module on the first Console request, and checks the Console
+ * section before it calls an action. The owner actions check their own access policy for the signed-in user.
+ */
+interface ViteHubConsoleDocumentEditorSection<TOptions = void> extends ViteHubConsoleSectionDescriptor<ViteHubConsoleDocumentEditorView> {
+  /** Returns the absolute path of the application module, or `undefined` when the project has none. */
+  entry: (options: TOptions) => MaybePromise<string | undefined>;
+  /**
+   * Reads, at build time and without running the application, what the project lacks for some editor features, such as
+   * a runner for scheduled publishes. The Console merges it with the owner `setup` action on each request.
+   */
+  inspect?: (options: TOptions, entry: string) => MaybePromise<ViteHubConsoleDocumentSetup>;
+  /** Owner export that must be a {@link ViteHubConsoleDocumentActionsFactory}. */
+  actions: ViteHubConsoleServerExport;
+}
+/**
+ * A Console section that an owner package contributes. The owner defines the label, icon, view, and data reader.
+ * `TOptions` is the discovery context that the host passes to `read`.
+ */
+type ViteHubConsoleSectionContribution<TOptions = void> = ViteHubConsoleAuthSection | ViteHubConsoleDefinitionCatalogSection<TOptions> | ViteHubConsoleRecordTableSection<TOptions> | ViteHubConsoleRuntimeRecordTableSection<TOptions> | ViteHubConsoleDocumentEditorSection<TOptions> | ViteHubConsoleOperationSection;
+/** A fix that the owner names for a feature the project lacks, such as `Add authorize to defineContent().` */
+interface ViteHubConsoleDocumentHint {
+  /** One sentence that names the fix. Text in backticks shows as code. */
+  message: string;
+  /** Absolute URL of the documentation for the fix. */
+  docs?: string;
+}
+/**
+ * What the project lacks for some editor features. The editor names each fix where the feature would be, instead of
+ * failing without a reason.
+ */
+interface ViteHubConsoleDocumentSetup {
+  /** Present when no user can read anything because the owner has no access policy. */
+  access?: ViteHubConsoleDocumentHint;
+  /**
+   * Live co-editing. `definition` names the Realtime Definition whose rooms are `<collection>/<id>`; the editor joins
+   * the room of a Markdown document instead of taking the edit lease. `unavailable` names why the owner wanted live
+   * editing and the host cannot run it, such as a host without a Realtime authority. Absent when live editing is off.
+   */
+  live?: {
+    definition: string;
+  } | {
+    unavailable: string;
+  };
+  /**
+   * Present when nothing runs scheduled publishes. The editor disables Schedule, and overdue schedules name the fix.
+   */
+  schedule?: ViteHubConsoleDocumentHint;
+}
+//#endregion
+//#region src/inspect.d.ts
+interface WorkflowInspectionOptions {
+  projectRoot: string;
+  rootDir: string;
+  serverDirs?: string[];
+}
+/** Lists user-facing Workflow Definitions. Generated Agent recovery Workflows are internal and stay hidden. */
+export declare function inspectWorkflowDefinitions(options: WorkflowInspectionOptions): ViteHubDefinitionSummary[];
+/** Console section that lists discovered Workflow Definitions. `vitehub inspect definitions` reads the same data. */
+export declare const workflowConsoleSection: ViteHubConsoleSectionContribution<WorkflowInspectionOptions>;
+//#endregion
 //#region src/vite.d.ts
-type WorkflowVitePlugin = Plugin;
-declare function hubWorkflow(options?: WorkflowModuleOptions): WorkflowVitePlugin;
+interface WorkflowNitroConfigOptions {
+  nitro: Record<string, unknown>;
+  projectRoot: string;
+  serverDirs?: string[];
+  transformRegistry?: (code: string, id: string) => string | Promise<string>;
+}
+export type WorkflowVitePlugin = Plugin$1 & {
+  vitehub?: ViteHubInspectionPluginMetadata & {
+    operations?: readonly OperationContributionEntry[];
+    workflow?: {
+      createNitroConfig?: (options: WorkflowNitroConfigOptions) => Promise<Record<string, unknown>>;
+      prepareScheduleRuntime?: (artifactDir?: string, config?: ResolvedConfig) => Promise<{
+        bundleAlias: Record<string, string>;
+        bundlePlugins?: Plugin[];
+        importBase: string;
+        native: boolean;
+        registryFile: string;
+      } | undefined>;
+    };
+  };
+};
+interface InternalWorkflowModuleOptions {
+  agentImportBase?: string;
+  hosting?: string;
+  implicitlyEnabled?: boolean;
+  importBase?: string;
+  providerImportAliases?: Record<string, string>;
+  includeUserAppEntry?: boolean;
+  workspaceDependencyRuntimeImports?: {
+    sandboxTask?: string;
+    sandboxTaskRuntimeState?: string;
+    shellWorkspace?: string;
+  };
+  workspaceImportBase?: string;
+}
+export declare function hubWorkflow(options?: WorkflowModuleOptions, internalOptions?: InternalWorkflowModuleOptions): WorkflowVitePlugin;
 declare module "vite" {
   interface UserConfig {
     workflow?: WorkflowModuleOptions;
   }
 }
 //#endregion
-export { WorkflowVitePlugin, hubWorkflow };
+export type { WorkflowInspectionOptions };