deepline 0.3.89 → 0.3.91

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;
+};

package/dist/bundling-sources/shared_libs/plays/deploy/manifest.ts

@@ -0,0 +1,162 @@
+import { readdir, readFile, stat } from 'node:fs/promises';
+import { join, relative } from 'node:path';
+import picomatch from 'picomatch';
+
+/**
+ * deepline.json — the repo-owned half of deploy configuration. The repo
+ * describes what plays exist and where; Convex (playProjects) decides what
+ * happens when they change (production branch, PR checks, enable/disable).
+ * No field lives in both places.
+ */
+export type DeeplineRepoManifest = {
+  /** Globs relative to the project root directory. */
+  plays: string[];
+  /** Optional tenant guard: the workspace slug this repo expects. */
+  org?: string;
+};
+
+export const DEFAULT_PLAY_GLOBS = ['**/*.play.ts'];
+const MAX_DISCOVERED_PLAY_FILES = 200;
+const IGNORED_DIRECTORIES = new Set([
+  'node_modules',
+  '.git',
+  'dist',
+  'build',
+  '.next',
+]);
+
+export class DeeplineManifestError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'DeeplineManifestError';
+  }
+}
+
+export function parseDeeplineManifest(
+  raw: string | null,
+): DeeplineRepoManifest {
+  if (raw === null) {
+    return { plays: DEFAULT_PLAY_GLOBS };
+  }
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (error) {
+    throw new DeeplineManifestError(
+      `deepline.json is not valid JSON: ${error instanceof Error ? error.message : String(error)}`,
+    );
+  }
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    throw new DeeplineManifestError('deepline.json must be a JSON object.');
+  }
+  const record = parsed as { plays?: unknown; org?: unknown };
+  let plays = DEFAULT_PLAY_GLOBS;
+  if (record.plays !== undefined) {
+    if (
+      !Array.isArray(record.plays) ||
+      record.plays.length === 0 ||
+      !record.plays.every(
+        (glob) => typeof glob === 'string' && glob.trim().length > 0,
+      )
+    ) {
+      throw new DeeplineManifestError(
+        'deepline.json "plays" must be a non-empty array of glob strings, e.g. ["plays/**/*.play.ts"].',
+      );
+    }
+    plays = record.plays.map((glob) => glob.trim().replace(/^\.\//, ''));
+  }
+  if (plays.some((glob) => glob.startsWith('/') || glob.includes('..'))) {
+    throw new DeeplineManifestError(
+      'deepline.json "plays" globs must be relative and must not contain "..".',
+    );
+  }
+  const org =
+    typeof record.org === 'string' && record.org.trim()
+      ? record.org.trim()
+      : undefined;
+  return { plays, ...(org ? { org } : {}) };
+}
+
+export const DEFAULT_MANIFEST_FILE = 'deepline.json';
+
+export async function readDeeplineManifest(
+  projectRoot: string,
+  manifestFile: string = DEFAULT_MANIFEST_FILE,
+): Promise<DeeplineRepoManifest> {
+  let raw: string | null = null;
+  try {
+    raw = await readFile(join(projectRoot, manifestFile), 'utf8');
+  } catch (error) {
+    const code = (error as NodeJS.ErrnoException).code;
+    // Only "file does not exist" may fall through; a permissions or I/O
+    // failure must never silently select default globs.
+    if (code !== 'ENOENT' && code !== 'ENOTDIR') {
+      throw error;
+    }
+    // An absent DEFAULT manifest means "use defaults". An absent EXPLICITLY
+    // configured manifest means the project points at a file the repo does
+    // not have — deploying **/*.play.ts instead would publish plays the
+    // manifest was supposed to scope out.
+    if (manifestFile !== DEFAULT_MANIFEST_FILE) {
+      throw new DeeplineManifestError(
+        `DEEPLINE_MANIFEST_MISSING: this project is configured to read ${manifestFile}, but the file does not exist at the project root.`,
+      );
+    }
+    raw = null;
+  }
+  try {
+    return parseDeeplineManifest(raw);
+  } catch (error) {
+    if (error instanceof DeeplineManifestError) {
+      throw new DeeplineManifestError(
+        error.message.replace(/^deepline\.json/, manifestFile),
+      );
+    }
+    throw error;
+  }
+}
+
+/**
+ * Explicit globs beat inference; a glob that accidentally matches
+ * node_modules or fixtures publishes garbage, so vendored/build directories
+ * are always skipped and discovery is capped loudly.
+ */
+export async function discoverPlayFiles(input: {
+  projectRoot: string;
+  globs: string[];
+}): Promise<string[]> {
+  const matchers = input.globs.map((glob) => picomatch(glob));
+  const found: string[] = [];
+
+  async function walk(dir: string): Promise<void> {
+    const entries = await readdir(dir, { withFileTypes: true });
+    for (const entry of entries) {
+      if (entry.name.startsWith('.') && entry.name !== '.') continue;
+      const absolute = join(dir, entry.name);
+      if (entry.isDirectory()) {
+        if (IGNORED_DIRECTORIES.has(entry.name)) continue;
+        await walk(absolute);
+        continue;
+      }
+      if (!entry.isFile()) continue;
+      const relativePath = relative(input.projectRoot, absolute);
+      if (matchers.some((match) => match(relativePath))) {
+        found.push(relativePath);
+        if (found.length > MAX_DISCOVERED_PLAY_FILES) {
+          throw new DeeplineManifestError(
+            `deepline.json globs matched more than ${MAX_DISCOVERED_PLAY_FILES} play files. Tighten the globs.`,
+          );
+        }
+      }
+    }
+  }
+
+  const rootStat = await stat(input.projectRoot).catch(() => null);
+  if (!rootStat?.isDirectory()) {
+    throw new DeeplineManifestError(
+      `Project root directory does not exist in the repo: ${input.projectRoot}`,
+    );
+  }
+  await walk(input.projectRoot);
+  return found.sort();
+}

package/dist/bundling-sources/shared_libs/plays/deploy/project-serializer.ts

@@ -0,0 +1,87 @@
+import { DEFAULT_MANIFEST_FILE } from './manifest';
+import type { PlayDeploymentDoc, PlayProjectDoc } from './control-plane-types';
+
+export { DEFAULT_MANIFEST_FILE } from './manifest';
+
+export type SerializedPlayProject = {
+  id: string;
+  orgId: string;
+  gitHost: string;
+  installationId: string;
+  repoId: number;
+  repoFullName: string;
+  rootDirectory: string;
+  manifestPath: string;
+  productionBranch: string;
+  checkOnPullRequest: boolean;
+  disabled: boolean;
+  createdByUserId: string;
+  createdAt: number;
+  updatedAt: number;
+};
+
+export function serializePlayProject(
+  project: PlayProjectDoc,
+): SerializedPlayProject {
+  return {
+    id: String(project._id),
+    orgId: project.orgId,
+    gitHost: project.gitHost,
+    installationId: project.installationId,
+    repoId: project.repoId,
+    repoFullName: project.repoFullName,
+    rootDirectory: project.rootDirectory,
+    manifestPath: project.manifestPath?.trim() || DEFAULT_MANIFEST_FILE,
+    productionBranch: project.productionBranch,
+    checkOnPullRequest: project.checkOnPullRequest,
+    disabled: Boolean(project.disabledAt),
+    createdByUserId: project.createdByUserId,
+    createdAt: project.createdAt,
+    updatedAt: project.updatedAt,
+  };
+}
+
+export type SerializedPlayDeployment = {
+  id: string;
+  orgId: string;
+  playProjectId: string;
+  commitSha: string;
+  ref: string;
+  isProduction: boolean;
+  trigger: string;
+  status: string;
+  pullRequestNumber: number | null;
+  /** Production push only: the PR whose merge produced this commit. */
+  mergedPullRequestNumber: number | null;
+  committerLogin: string | null;
+  results: unknown;
+  buildSeconds: number | null;
+  error: string | null;
+  createdAt: number;
+  startedAt: number | null;
+  finishedAt: number | null;
+};
+
+export function serializePlayDeployment(
+  deployment: PlayDeploymentDoc,
+): SerializedPlayDeployment {
+  return {
+    id: String(deployment._id),
+    orgId: deployment.orgId,
+    playProjectId: String(deployment.playProjectId),
+    commitSha: deployment.commitSha,
+    ref: deployment.ref,
+    isProduction: deployment.isProduction,
+    trigger: deployment.trigger,
+    status: deployment.status,
+    pullRequestNumber: deployment.pullRequestNumber ?? null,
+    mergedPullRequestNumber: deployment.mergedPullRequestNumber ?? null,
+    committerLogin: deployment.committerLogin ?? null,
+    results: deployment.results ?? null,
+    buildSeconds: deployment.buildSeconds ?? null,
+    error: deployment.error ?? null,
+    createdAt: deployment.createdAt,
+    startedAt: deployment.startedAt ?? null,
+    finishedAt: deployment.finishedAt ?? null,
+  };
+}

package/dist/bundling-sources/shared_libs/plays/deploy/source-file-path.ts

@@ -0,0 +1,26 @@
+/**
+ * A revision's source path is repo-relative and is rendered as a location in
+ * the dashboard's play tree, so it is admitted once, here, rather than trusted
+ * from the request body.
+ */
+
+const MAX_LENGTH = 1024;
+
+/**
+ * Returns the path when it could have come from a repository walk, and null
+ * otherwise. Null is not an error: the field is optional everywhere downstream,
+ * and a play that did not come from a git deploy legitimately has no path.
+ */
+export function normalizeSourceFilePath(value: unknown): string | null {
+  if (typeof value !== 'string') return null;
+  const trimmed = value.trim();
+  if (!trimmed || trimmed.length > MAX_LENGTH) return null;
+  // Absolute paths and Windows separators never come from the repo walk, and
+  // `..` would let a path escape the project it claims to belong to.
+  if (trimmed.startsWith('/') || trimmed.includes('\\')) return null;
+  const segments = trimmed.split('/');
+  if (segments.some((segment) => segment === '..' || segment === '')) {
+    return null;
+  }
+  return trimmed;
+}

package/dist/bundling-sources/shared_libs/plays/deploy/target-paths.ts

@@ -0,0 +1,36 @@
+/**
+ * Deployment-target path validation shared by play-project create and
+ * update. The canonical forms feed the exact-duplicate target check in
+ * convex/playProjects.ts, so create and update MUST canonicalize
+ * identically — path aliases ('' vs '.', 'pkg//a' vs 'pkg/a') would
+ * otherwise slip past it.
+ */
+
+export function canonicalizeRootDirectory(
+  value: string,
+): { ok: true; rootDirectory: string } | { ok: false; error: string } {
+  if (value.split('/').some((part) => part === '..')) {
+    return { ok: false, error: 'rootDirectory must not contain "..".' };
+  }
+  return {
+    ok: true,
+    rootDirectory: value
+      .split('/')
+      .filter((part) => part && part !== '.')
+      .join('/'),
+  };
+}
+
+export function validateManifestPath(
+  value: string,
+): { ok: true; manifestPath: string } | { ok: false; error: string } {
+  const manifestPath = value.trim();
+  if (manifestPath.includes('/') || manifestPath.includes('..')) {
+    return {
+      ok: false,
+      error:
+        'manifestPath must be a bare file name under the base path (e.g. deepline.staging.json).',
+    };
+  }
+  return { ok: true, manifestPath };
+}

package/dist/bundling-sources/shared_libs/plays/deployment-status.ts

@@ -1,6 +1,6 @@
 /**
  * The play deployment status machine, shared by the Convex control plane
- * (convex/playDeployments.ts), worker auth (src/lib/auth/play-deploy-auth.ts),
+ * (convex/playDeployments.ts), worker auth (apps/deepline-api/src/lib/auth/play-deploy-auth.ts),
  * and the deploy-worker API surface. One spelling of the union, the terminal
  * set, and the allowed transitions.
  */

package/dist/bundling-sources/shared_libs/plays/docflow.ts

@@ -78,7 +78,7 @@ export type PlayDocflowEdge = {
    *
    * ABSENT — never `null` — when unrecorded, and that is load-bearing rather
    * than stylistic. `docflow` is whole-object serialized into
-   * `playStaticPipelineContractHash` (`src/lib/plays/artifact-storage.ts`),
+   * `playStaticPipelineContractHash` (`apps/deepline-api/src/lib/plays/artifact-storage.ts`),
    * which is part of the immutable artifact storage key, and the canonicalizer
    * there drops `undefined` but HASHES `null`. Emitting `arm: null` on an
    * unannotated edge would change the contract hash of every diagrammed play