feat(ql3): establish 3.0 incubation baseline

2026-09-21 18:08:20 +08:00 · 2026-08-12 00:25:26 +08:00
parent 4bf92dcfeb
commit c699c32461
2817 changed files with 779642 additions and 653 deletions
@@ -0,0 +1,232 @@
+import type {
+  createLocalPluginPackageWorkflowAdministrationService,
+  establishAuthenticatedLocalCommand,
+  openLocalSqlitePluginPackageWorkflowAdministrationDatabase,
+  PluginPackageWorkflowRunEventListResult,
+  PluginPackageWorkflowRunInspectionResult,
+  PluginPackageWorkflowRunListResult,
+  PluginPackageWorkflowStepRunListResult,
+} from './contractAuthority';
+
+export interface LocalPluginPackageWorkflowCommandOptions {
+  readonly deploymentRoot: string;
+  readonly databasePath: string;
+  readonly profile: 'edge' | 'standalone';
+  readonly ownerPepperKeyringDirectory: string;
+  readonly credentialFilePath: string;
+  readonly busyTimeoutMs?: number;
+}
+
+export interface LocalPluginPackageWorkflowCommandRequestBase {
+  readonly projectId: string;
+  readonly packageName: string;
+  readonly requestId: string;
+  readonly auditEventId: string;
+  readonly failureAuditEventId: string;
+}
+
+export interface InspectLocalPluginPackageWorkflowCommand {
+  readonly schemaVersion: 1;
+  readonly operation: 'workflow.inspect';
+  readonly options: LocalPluginPackageWorkflowCommandOptions;
+  readonly request: LocalPluginPackageWorkflowCommandRequestBase;
+}
+
+export interface StartLocalPluginPackageWorkflowCommand {
+  readonly schemaVersion: 1;
+  readonly operation: 'workflow.start';
+  readonly options: LocalPluginPackageWorkflowCommandOptions;
+  readonly request: LocalPluginPackageWorkflowCommandRequestBase & {
+    readonly workflowId: string;
+    readonly planId: string;
+    readonly runId: string;
+    readonly stepRunIds: Readonly<Record<string, string>>;
+  };
+}
+
+export interface CancelLocalPluginPackageWorkflowCommand {
+  readonly schemaVersion: 1;
+  readonly operation: 'workflow.cancel';
+  readonly options: LocalPluginPackageWorkflowCommandOptions;
+  readonly request: LocalPluginPackageWorkflowCommandRequestBase & {
+    readonly runId: string;
+    readonly mutationId: string;
+    readonly runEventId: string;
+  };
+}
+
+export interface InspectLocalPluginPackageWorkflowRunCommand {
+  readonly schemaVersion: 1;
+  readonly operation: 'workflow.run.inspect';
+  readonly options: LocalPluginPackageWorkflowCommandOptions;
+  readonly request: LocalPluginPackageWorkflowCommandRequestBase & {
+    readonly workflowId: string;
+    readonly runId: string;
+  };
+}
+
+export interface ListLocalPluginPackageWorkflowRunsCommand {
+  readonly schemaVersion: 1;
+  readonly operation: 'workflow.run.list';
+  readonly options: LocalPluginPackageWorkflowCommandOptions;
+  readonly request: LocalPluginPackageWorkflowCommandRequestBase & {
+    readonly workflowId: string;
+    readonly limit: number;
+    readonly after: Readonly<{ admittedAtMs: number; runId: string }> | null;
+  };
+}
+
+export interface ListLocalPluginPackageWorkflowStepRunsCommand {
+  readonly schemaVersion: 1;
+  readonly operation: 'workflow.step.list';
+  readonly options: LocalPluginPackageWorkflowCommandOptions;
+  readonly request: LocalPluginPackageWorkflowCommandRequestBase & {
+    readonly workflowId: string;
+    readonly runId: string;
+    readonly limit: number;
+    readonly after: Readonly<{ stepKey: string; id: string }> | null;
+  };
+}
+
+export interface ListLocalPluginPackageWorkflowRunEventsCommand {
+  readonly schemaVersion: 1;
+  readonly operation: 'workflow.event.list';
+  readonly options: LocalPluginPackageWorkflowCommandOptions;
+  readonly request: LocalPluginPackageWorkflowCommandRequestBase & {
+    readonly workflowId: string;
+    readonly runId: string;
+    readonly limit: number;
+    readonly afterSequence: number;
+  };
+}
+
+export type LocalPluginPackageWorkflowCommand =
+  | InspectLocalPluginPackageWorkflowCommand
+  | InspectLocalPluginPackageWorkflowRunCommand
+  | ListLocalPluginPackageWorkflowRunsCommand
+  | ListLocalPluginPackageWorkflowStepRunsCommand
+  | ListLocalPluginPackageWorkflowRunEventsCommand
+  | StartLocalPluginPackageWorkflowCommand
+  | CancelLocalPluginPackageWorkflowCommand;
+
+export type LocalPluginPackageWorkflowCommandResult =
+  | Readonly<{
+      schemaVersion: 1;
+      operation: 'workflow.inspect';
+      projectId: string;
+      packageName: string;
+      found: boolean;
+      publicationState: 'active' | 'withdrawn' | 'absent' | null;
+      workflows: readonly Readonly<{
+        id: string;
+        name: string;
+        enabled: boolean;
+        steps: readonly Readonly<{
+          id: string;
+          task: string;
+          needs: readonly string[];
+        }>[];
+      }>[];
+    }>
+  | Readonly<{
+      schemaVersion: 1;
+      operation: 'workflow.run.inspect';
+      projectId: string;
+      packageName: string;
+      workflowId: string;
+      runId: string;
+      found: boolean;
+      run: PluginPackageWorkflowRunInspectionResult['run'];
+      stepCount: number | null;
+      stepStatusCounts: PluginPackageWorkflowRunInspectionResult['stepStatusCounts'];
+    }>
+  | Readonly<{
+      schemaVersion: 1;
+      operation: 'workflow.run.list';
+      projectId: string;
+      packageName: string;
+      workflowId: string;
+      after: PluginPackageWorkflowRunListResult['after'];
+      runs: PluginPackageWorkflowRunListResult['runs'];
+      truncated: boolean;
+      next: PluginPackageWorkflowRunListResult['next'];
+    }>
+  | Readonly<{
+      schemaVersion: 1;
+      operation: 'workflow.step.list';
+      projectId: string;
+      packageName: string;
+      workflowId: string;
+      runId: string;
+      found: boolean;
+      stepRuns: PluginPackageWorkflowStepRunListResult['stepRuns'];
+      truncated: boolean;
+      next: PluginPackageWorkflowStepRunListResult['next'];
+    }>
+  | Readonly<{
+      schemaVersion: 1;
+      operation: 'workflow.event.list';
+      projectId: string;
+      packageName: string;
+      workflowId: string;
+      runId: string;
+      found: boolean;
+      afterSequence: number;
+      headSequence: number | null;
+      events: PluginPackageWorkflowRunEventListResult['events'];
+      truncated: boolean;
+      nextAfterSequence: number | null;
+    }>
+  | Readonly<{
+      schemaVersion: 1;
+      operation: 'workflow.start';
+      status: 'created' | 'existing';
+      projectId: string;
+      packageName: string;
+      workflowId: string;
+      runId: string;
+      stepCount: number;
+      admittedAtMs: number;
+    }>
+  | Readonly<{
+      schemaVersion: 1;
+      operation: 'workflow.cancel';
+      status:
+        | 'accepted'
+        | 'existing'
+        | 'already_requested'
+        | 'already_terminal';
+      projectId: string;
+      packageName: string;
+      workflowId: string;
+      runId: string;
+      runStatus: string;
+      runVersion: number;
+      eventSequence: number;
+      cancelRequestedAtMs?: number;
+      cancelReason?: string;
+    }>;
+
+export interface LocalPluginPackageWorkflowCommandRunner {
+  run(
+    commandFilePath: string,
+  ): Promise<LocalPluginPackageWorkflowCommandResult>;
+}
+
+export interface LocalPluginPackageWorkflowCommandRunnerDependencies {
+  readonly openDatabase: typeof openLocalSqlitePluginPackageWorkflowAdministrationDatabase;
+  readonly authenticate: typeof establishAuthenticatedLocalCommand;
+  readonly createService: typeof createLocalPluginPackageWorkflowAdministrationService;
+  readonly now: () => number;
+}
+
+export class LocalPluginPackageWorkflowCommandConfigurationError extends TypeError {
+  readonly code = 'LOCAL_PLUGIN_PACKAGE_WORKFLOW_COMMAND_CONFIGURATION_INVALID';
+
+  constructor(message: string, readonly cause?: unknown) {
+    super(
+      `Local Plugin Package Workflow command configuration is invalid: ${message}`,
+    );
+    this.name = 'LocalPluginPackageWorkflowCommandConfigurationError';
+  }
+}