deepline 0.3.90 → 0.3.91

package/dist/bundling-sources/shared_libs/play-runtime/scheduler-backends/receipt-gateway.ts

@@ -5,7 +5,7 @@
  * read/write from a runner crosses HTTP to a co-located gateway process that
  * holds the runtime Postgres (PlanetScale) pool. There is exactly one receipt
  * backend — runners have no direct-Postgres receipt path and no app runtime
- * API fallback (see apps/play-runner/src/entry.ts).
+ * API fallback (see packages/play-runtime/runner-app/index.ts).
  *
  * The module is transport-agnostic on the database side so the production
  * gateway (apps/runtime-receipt-gateway/index.ts, pooled `pg` against

package/dist/bundling-sources/shared_libs/play-runtime/webhook-receipt-retry.ts

@@ -0,0 +1,50 @@
+import { createHash } from 'node:crypto';
+import {
+  PLAY_SECRET_UNAVAILABLE,
+  playSecretUnavailableErrorFrom,
+} from '../plays/secrets/errors';
+
+const RETRY_BASE_MS = 1_000;
+const RETRY_CAP_MS = 15 * 60 * 1_000;
+
+/**
+ * Admission has not called a customer provider or started user code. Unknown
+ * failures therefore stay retryable: an internal 5xx must not discard a
+ * source delivery. Only a proven local configuration error is blocked.
+ */
+export function classifyWebhookReceiptAdmissionFailure(error: unknown): {
+  retryable: boolean;
+  code: 'INTERNAL_ADMISSION_FAILURE' | typeof PLAY_SECRET_UNAVAILABLE;
+} {
+  const unavailableSecret = playSecretUnavailableErrorFrom(error);
+  if (unavailableSecret) {
+    return { retryable: false, code: PLAY_SECRET_UNAVAILABLE };
+  }
+  return { retryable: true, code: 'INTERNAL_ADMISSION_FAILURE' };
+}
+
+/**
+ * Stable jitter spreads a burst without making a receipt's retry timing
+ * unknowable to operators. The cap makes a prolonged platform incident cheap
+ * while the receipt remains durable and visible for recovery.
+ */
+export function webhookReceiptRetryDelayMs(input: {
+  eventId: string;
+  attempt: number;
+}): number {
+  const exponent = Math.min(Math.max(input.attempt - 1, 0), 10);
+  const ceiling = Math.min(RETRY_CAP_MS, RETRY_BASE_MS * 2 ** exponent);
+  const hash = createHash('sha256')
+    .update(input.eventId)
+    .update(':')
+    .update(String(input.attempt))
+    .digest();
+  // Keep a nonzero delay and give concurrent deliveries independent stable
+  // placement across the exponential window. The first retry spans 1–2s;
+  // otherwise a burst of first-attempt failures would synchronise again.
+  const fraction = hash.readUInt32BE(0) / 0xffff_ffff;
+  return Math.min(
+    RETRY_CAP_MS,
+    Math.max(RETRY_BASE_MS, Math.round(ceiling * (1 + fraction))),
+  );
+}

package/dist/bundling-sources/shared_libs/plays/bundling/repository-adapter.ts

@@ -0,0 +1,24 @@
+import { tmpdir } from 'node:os';
+import { join, resolve } from 'node:path';
+import type { PlayBundlingAdapter } from './index';
+import { discoverPackagedLocalFiles } from '../local-file-discovery';
+
+/** Repository source bundling shared by the API and the deploy worker.
+ * Callers supply their repository root; cloud validation is an API adapter.
+ */
+export function createRepositoryPlayBundlingAdapter(options: {
+  projectRoot: string;
+  sourceIdentityRoot?: string;
+}): PlayBundlingAdapter {
+  const sdkSourceRoot = resolve(options.projectRoot, 'packages', 'sdk', 'src');
+  return {
+    projectRoot: options.projectRoot,
+    sourceIdentityRoot: options.sourceIdentityRoot,
+    nodeModulesDir: resolve(options.projectRoot, 'node_modules'),
+    cacheDir: join(tmpdir(), 'deepline-play-artifacts-v37'),
+    sdkSourceRoot,
+    sdkPackageJson: resolve(sdkSourceRoot, '..', 'package.json'),
+    sdkEntryFile: resolve(sdkSourceRoot, 'index.ts'),
+    discoverPackagedLocalFiles,
+  };
+}

package/dist/bundling-sources/shared_libs/plays/child-run-projection.ts

@@ -0,0 +1,174 @@
+/**
+ * The bounded, durable read model for direct `ctx.runPlayAsync` descendants.
+ *
+ * A child belongs to an authored launch site through `launchKey`, not through
+ * its play name: one Play may be launched from several sites, and an async
+ * launch inside a fan-out has many independently progressing invocations.
+ * `invocationKey` is deliberately opaque; callers use its `runId` to drill
+ * into one actual Run instead of reconstructing an identity from input data.
+ */
+export type AsyncChildRunSummary = {
+  runId: string;
+  playName: string | null;
+  launchKey: string | null;
+  invocationKey: string | null;
+  rootBillingOwned: boolean;
+  status: string;
+  parentRunId: string | null;
+  rootRunId: string | null;
+  createdAt: number | null;
+  startedAt: number | null;
+  finishedAt: number | null;
+};
+
+export type AsyncChildRunStatusCounts = {
+  total: number;
+  queued: number;
+  active: number;
+  waiting: number;
+  succeeded: number;
+  failed: number;
+  cancelled: number;
+  unknown: number;
+};
+
+export type AsyncChildRunLaunchProjection = {
+  /** `null` is an older child run that predates durable authored attribution. */
+  launchKey: string | null;
+  playName: string | null;
+  counts: AsyncChildRunStatusCounts;
+  children: AsyncChildRunSummary[];
+};
+
+export type AsyncChildRunProjection = {
+  kind: 'async_child_runs';
+  /** Direct children returned by the bounded durable index read. */
+  returnedCount: number;
+  /** False means the displayed counts are a lower bound, never a fake total. */
+  complete: boolean;
+  counts: AsyncChildRunStatusCounts;
+  launches: AsyncChildRunLaunchProjection[];
+};
+
+/**
+ * Wire guard for the bounded projection. Callers must never turn a partial
+ * response into an invented zero-child fanout.
+ */
+export function isAsyncChildRunProjection(
+  value: unknown,
+): value is AsyncChildRunProjection {
+  if (!value || typeof value !== 'object') return false;
+  const candidate = value as Record<string, unknown>;
+  return (
+    candidate.kind === 'async_child_runs' &&
+    typeof candidate.returnedCount === 'number' &&
+    typeof candidate.complete === 'boolean' &&
+    Array.isArray(candidate.launches) &&
+    candidate.counts !== null &&
+    typeof candidate.counts === 'object'
+  );
+}
+
+/**
+ * New async children persist root-owned billing attribution at admission. Their
+ * execution facts are therefore already present in the root Run's billing
+ * query. Historic children have no such proof and retain the compatibility
+ * lookup rather than being silently undercounted.
+ */
+export function requiresLegacyChildBillingRead(input: {
+  billingRunId: string;
+  child: Pick<AsyncChildRunSummary, 'runId' | 'rootBillingOwned'>;
+}): boolean {
+  return (
+    !input.child.rootBillingOwned && input.billingRunId !== input.child.runId
+  );
+}
+
+const EMPTY_COUNTS = (): AsyncChildRunStatusCounts => ({
+  total: 0,
+  queued: 0,
+  active: 0,
+  waiting: 0,
+  succeeded: 0,
+  failed: 0,
+  cancelled: 0,
+  unknown: 0,
+});
+
+function addStatus(counts: AsyncChildRunStatusCounts, status: string): void {
+  counts.total += 1;
+  switch (status.trim().toLowerCase()) {
+    case 'queued':
+    case 'pending':
+    case 'scheduled':
+      counts.queued += 1;
+      return;
+    case 'running':
+    case 'in_progress':
+      counts.active += 1;
+      return;
+    case 'waiting':
+    case 'suspended':
+    case 'awaiting_signal':
+      counts.waiting += 1;
+      return;
+    case 'completed':
+    case 'complete':
+    case 'succeeded':
+    case 'success':
+      counts.succeeded += 1;
+      return;
+    case 'failed':
+    case 'error':
+      counts.failed += 1;
+      return;
+    case 'cancelled':
+    case 'canceled':
+    case 'stopped':
+      counts.cancelled += 1;
+      return;
+    default:
+      counts.unknown += 1;
+  }
+}
+
+/**
+ * Builds the one child-run representation shared by agent/API callers and UI.
+ * The input must already be sorted by newest child first; grouping preserves
+ * that order so a consumer can display recent child Runs without re-sorting.
+ */
+export function projectAsyncChildRuns(input: {
+  children: readonly AsyncChildRunSummary[];
+  complete: boolean;
+}): AsyncChildRunProjection {
+  const counts = EMPTY_COUNTS();
+  const byLaunchKey = new Map<string, AsyncChildRunLaunchProjection>();
+
+  for (const child of input.children) {
+    addStatus(counts, child.status);
+    const mapKey = child.launchKey ?? '__unattributed_async_child__';
+    let launch = byLaunchKey.get(mapKey);
+    if (!launch) {
+      launch = {
+        launchKey: child.launchKey,
+        playName: child.playName,
+        counts: EMPTY_COUNTS(),
+        children: [],
+      };
+      byLaunchKey.set(mapKey, launch);
+    }
+    // A key is the authored site, so preserve the first (most-recent) name
+    // while still retaining exact identity on every child row.
+    if (!launch.playName && child.playName) launch.playName = child.playName;
+    addStatus(launch.counts, child.status);
+    launch.children.push(child);
+  }
+
+  return {
+    kind: 'async_child_runs',
+    returnedCount: input.children.length,
+    complete: input.complete,
+    counts,
+    launches: [...byLaunchKey.values()],
+  };
+}

package/dist/bundling-sources/shared_libs/plays/deploy/api-client.ts

@@ -0,0 +1,267 @@
+import type { PlayBundleArtifact } from '../artifact-types';
+import type { PlayCompilerManifest } from '../compiler-manifest';
+import type { PlayDeploymentStatus } from '../deployment-status';
+import type {
+  SerializedPlayDeployment,
+  SerializedPlayProject,
+} from './project-serializer';
+
+/**
+ * The deploy worker's only channel to the control plane: the app HTTP API,
+ * authenticated with the per-deployment token minted at webhook intake. The
+ * worker holds no Convex, R2, or GitHub App credentials.
+ */
+
+// Mirrors the SDK's byte-aware chunker: the Vercel request-body ceiling is
+// the real constraint, not the server's 25-item batch cap.
+const REGISTER_MAX_BATCH_COUNT = 3;
+const REGISTER_MAX_BATCH_BYTES = 2_500_000;
+
+export type DeployApiErrorCode =
+  | 'PLAY_DEPLOYMENT_SUPERSEDED'
+  | 'PLAY_DEPLOYMENT_TERMINAL'
+  | 'PLAY_PROJECT_DISABLED'
+  | string;
+
+export class DeployApiError extends Error {
+  readonly status: number;
+  readonly code: DeployApiErrorCode | null;
+  readonly body: unknown;
+  constructor(input: {
+    message: string;
+    status: number;
+    code?: string | null;
+    body?: unknown;
+  }) {
+    super(input.message);
+    this.name = 'DeployApiError';
+    this.status = input.status;
+    this.code = input.code ?? null;
+    this.body = input.body;
+  }
+}
+
+export type RegisterArtifactEntry = {
+  name: string;
+  sourceCode: string;
+  sourceFiles?: Record<string, string>;
+  description?: string;
+  artifact: PlayBundleArtifact;
+  compilerManifest: PlayCompilerManifest;
+  /**
+   * Repo-relative path this play was built from. Per-entry, not per-request:
+   * one deployment registers up to 25 plays from 25 different files.
+   */
+  sourceFilePath?: string;
+};
+
+export type RegisteredArtifact = {
+  name?: string;
+  definitionId?: string;
+  revisionId?: string;
+  version?: number;
+  [key: string]: unknown;
+};
+
+export type DeploymentPlayState = {
+  name: string;
+  exists: boolean;
+  playProjectId: string | null;
+  /** repoFullName of the project that currently owns this play, if any. */
+  playProjectRepo: string | null;
+  /** Whether that owner is disabled; null when nothing owns the play. */
+  playProjectDisabled: boolean | null;
+  driftFromGit?: boolean;
+  workingRevision: {
+    revisionId: string;
+    sourceHash: string | null;
+    artifactHash: string | null;
+    graphHash: string | null;
+    artifactKind: string | null;
+    version: number | null;
+  } | null;
+  liveRevision: DeploymentPlayState['workingRevision'];
+};
+
+export class DeployApiClient {
+  constructor(
+    private readonly config: {
+      appBaseUrl: string;
+      deployToken: string;
+      deploymentId: string;
+      fetchImpl?: typeof fetch;
+    },
+  ) {}
+
+  private async request<T>(input: {
+    method: 'GET' | 'POST';
+    path: string;
+    body?: unknown;
+  }): Promise<T> {
+    const doFetch = this.config.fetchImpl ?? fetch;
+    const response = await doFetch(
+      `${this.config.appBaseUrl.replace(/\/$/, '')}${input.path}`,
+      {
+        method: input.method,
+        headers: {
+          Authorization: `Bearer ${this.config.deployToken}`,
+          ...(input.body !== undefined
+            ? { 'Content-Type': 'application/json' }
+            : {}),
+        },
+        body: input.body !== undefined ? JSON.stringify(input.body) : undefined,
+      },
+    );
+    const text = await response.text();
+    let parsed: unknown = null;
+    try {
+      parsed = text ? JSON.parse(text) : null;
+    } catch {
+      parsed = text;
+    }
+    if (!response.ok) {
+      const record = (parsed ?? {}) as { error?: unknown; code?: unknown };
+      throw new DeployApiError({
+        message:
+          typeof record.error === 'string'
+            ? record.error
+            : `Deploy API ${input.path} failed (${response.status}).`,
+        status: response.status,
+        code: typeof record.code === 'string' ? record.code : null,
+        body: parsed,
+      });
+    }
+    return parsed as T;
+  }
+
+  /** Every deployment-scoped route hangs off this one path. */
+  private deploymentPath(suffix = ''): string {
+    return `/api/v2/deployments/${this.config.deploymentId}${suffix}`;
+  }
+
+  getDeployment(): Promise<{
+    deployment: SerializedPlayDeployment;
+    project: SerializedPlayProject;
+    /** Server-computed; qualified when several targets build one repo. */
+    checkRunName: string;
+    /** The deploy target's workspace slug, for the manifest `org` guard. */
+    workspaceSlug: string | null;
+  }> {
+    return this.request({
+      method: 'GET',
+      path: this.deploymentPath(),
+    });
+  }
+
+  setStatus(input: {
+    status: Exclude<PlayDeploymentStatus, 'queued'>;
+    error?: string;
+    results?: unknown;
+    buildSeconds?: number;
+    checkRunId?: number;
+    /** Production push only: the PR whose merge produced the commit. */
+    mergedPullRequestNumber?: number;
+    /** Head-guard supersedes only: lets the server re-enqueue an uncovered head. */
+    observedHeadSha?: string;
+  }): Promise<{ ok: boolean }> {
+    return this.request({
+      method: 'POST',
+      path: this.deploymentPath('/status'),
+      body: input,
+    });
+  }
+
+  mintGitHubToken(): Promise<{
+    token: string;
+    expiresAt: string;
+    repoId: number;
+    repoFullName: string;
+  }> {
+    return this.request({
+      method: 'POST',
+      path: this.deploymentPath('/github-token'),
+      body: {},
+    });
+  }
+
+  playsState(names: string[]): Promise<{ plays: DeploymentPlayState[] }> {
+    return this.request({
+      method: 'POST',
+      path: this.deploymentPath('/plays-state'),
+      body: { names },
+    });
+  }
+
+  compileManifest(input: {
+    name: string;
+    sourceCode: string;
+    sourceFiles?: Record<string, string>;
+    artifact: PlayBundleArtifact;
+    importedPlayDependencies?: PlayCompilerManifest[];
+  }): Promise<{ compilerManifest: PlayCompilerManifest; warnings?: string[] }> {
+    return this.request({
+      method: 'POST',
+      path: '/api/v2/plays/compile-manifest',
+      body: input,
+    });
+  }
+
+  async registerArtifacts(
+    entries: RegisterArtifactEntry[],
+  ): Promise<RegisteredArtifact[]> {
+    const results: RegisteredArtifact[] = [];
+    let batch: RegisterArtifactEntry[] = [];
+    let batchBytes = 0;
+    const flush = async () => {
+      if (batch.length === 0) return;
+      const payload = await this.request<{ artifacts: RegisteredArtifact[] }>({
+        method: 'POST',
+        path: '/api/v2/plays/artifacts',
+        body: {
+          artifacts: batch.map((entry) => ({ ...entry, publish: false })),
+        },
+      });
+      results.push(...payload.artifacts);
+      batch = [];
+      batchBytes = 0;
+    };
+    for (const entry of entries) {
+      // Serialized UTF-8 bytes of the wire entry: sourceFiles, manifests,
+      // JSON escaping, and multibyte characters all count against the Vercel
+      // body limit, not just the two code strings.
+      const entryBytes = Buffer.byteLength(
+        JSON.stringify({ ...entry, publish: false }),
+        'utf8',
+      );
+      if (
+        batch.length >= REGISTER_MAX_BATCH_COUNT ||
+        (batch.length > 0 && batchBytes + entryBytes > REGISTER_MAX_BATCH_BYTES)
+      ) {
+        await flush();
+      }
+      batch.push(entry);
+      batchBytes += entryBytes;
+    }
+    await flush();
+    return results;
+  }
+
+  promote(plays: Array<{ name: string; revisionId: string }>): Promise<{
+    success: boolean;
+    outcomes: Array<{
+      name: string;
+      revisionId: string;
+      status: 'promoted' | 'failed';
+      version?: number;
+      error?: string;
+    }>;
+    phase?: string;
+    error?: string;
+  }> {
+    return this.request({
+      method: 'POST',
+      path: this.deploymentPath('/promote'),
+      body: { plays },
+    });
+  }
+}

package/dist/bundling-sources/shared_libs/plays/deploy/control-plane-types.ts

@@ -0,0 +1,73 @@
+import type { GenericId } from 'convex/values';
+import type { PlayDeploymentStatus } from '../deployment-status';
+
+export type { PlayDeploymentStatus } from '../deployment-status';
+
+/**
+ * Explicit row types for the GitHub deploy control plane, mirroring
+ * convex/schema.ts. App code deliberately does NOT use `Doc<'...'>` here:
+ * the schema-derived document types degrade to `unknown` fields under the
+ * full-project tsc pass (the schema type is past TypeScript's inference
+ * budget), which is why the rest of `src/` avoids `Doc<>` too. Keep these in
+ * sync with the schema tables by hand; the convex typecheck still validates
+ * the source of truth.
+ */
+
+export type GithubInstallationDoc = {
+  _id: GenericId<'githubInstallations'>;
+  _creationTime: number;
+  gitHost: string;
+  installationId: string;
+  orgId: string;
+  accountLogin: string;
+  accountType: 'User' | 'Organization';
+  targetId: number;
+  repositorySelection: 'all' | 'selected';
+  installedByUserId: string;
+  verifiedAt: number;
+  suspendedAt?: number;
+  deletedAt?: number;
+  createdAt: number;
+  updatedAt: number;
+};
+
+export type PlayProjectDoc = {
+  _id: GenericId<'playProjects'>;
+  _creationTime: number;
+  orgId: string;
+  gitHost: string;
+  installationId: string;
+  repoId: number;
+  repoFullName: string;
+  rootDirectory: string;
+  manifestPath?: string;
+  productionBranch: string;
+  checkOnPullRequest: boolean;
+  disabledAt?: number;
+  createdByUserId: string;
+  createdAt: number;
+  updatedAt: number;
+};
+
+export type PlayDeploymentDoc = {
+  _id: GenericId<'playDeployments'>;
+  _creationTime: number;
+  orgId: string;
+  playProjectId: GenericId<'playProjects'>;
+  commitSha: string;
+  ref: string;
+  isProduction: boolean;
+  trigger: 'push' | 'pull_request' | 'manual' | 'redeliver';
+  deliveryId?: string;
+  status: PlayDeploymentStatus;
+  checkRunId?: number;
+  pullRequestNumber?: number;
+  mergedPullRequestNumber?: number;
+  committerLogin?: string;
+  results?: unknown;
+  buildSeconds?: number;
+  startedAt?: number;
+  finishedAt?: number;
+  error?: string;
+  createdAt: number;
+};