deepline 0.3.214 → 0.3.215

package/dist/bundling-sources/sdk/src/release.ts

@@ -200,7 +200,7 @@ export const SDK_RELEASE = {
   // getters keep their established compatibility behavior.
   // 0.3.1 deprecated the legacy `deepline enrich` command in favor of Plays.
   // 0.3.90 is the first deliberately versioned SDK release for API v3.
-  version: '0.3.214',
+  version: '0.3.215',
   updateSummary:
     'Play grep now returns concise results with the matched fields and terms. Automatic CLI updates are enabled by default; use `deepline settings autoupdate off` to opt out, `deepline settings autoupdate on` to re-enable updates, or `deepline settings autoupdate pin <version>` to hold an exact release.',
   packageCapabilities: {

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

@@ -91,6 +91,23 @@ export type DeploymentPlayState = {
   liveRevision: DeploymentPlayState['workingRevision'];
 };
 
+export type DeploymentMonitorEntry = {
+  /** Repository-relative source path, including the linked target's root. */
+  file: string;
+  /** The monitor API owns definition validation. */
+  definition: unknown;
+};
+
+export type DeploymentMonitorOutcome = {
+  key: string;
+  file: string;
+  status: 'planned' | 'applying' | 'applied' | 'stopped' | 'failed';
+  jobId?: string;
+  warning?: string;
+  error?: string;
+  credits?: number | null;
+};
+
 export class DeployApiClient {
   constructor(
     private readonly config: {
@@ -223,6 +240,29 @@ export class DeployApiClient {
     });
   }
 
+  monitors(
+    action: 'plan' | 'apply',
+    entries: DeploymentMonitorEntry[],
+  ): Promise<{ monitors: DeploymentMonitorOutcome[] }> {
+    return this.request({
+      method: 'POST',
+      path: this.deploymentPath('/monitors'),
+      body: { action, entries },
+    });
+  }
+
+  monitorJob(
+    jobId: string,
+    monitorKey: string,
+  ): Promise<{ monitors: DeploymentMonitorOutcome[] }> {
+    return this.request({
+      method: 'GET',
+      path: this.deploymentPath(
+        `/monitors?jobId=${encodeURIComponent(jobId)}&monitorKey=${encodeURIComponent(monitorKey)}`,
+      ),
+    });
+  }
+
   compileManifest(input: {
     name: string;
     sourceCode: string;

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

@@ -4,19 +4,22 @@ 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
+ * describes what plays and monitors 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[];
+  /** Monitor JSON files to discover, relative to the project root directory. */
+  monitors: 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;
+export const DEFAULT_MONITOR_GLOBS = ['**/*.monitor.json'];
+const MAX_DISCOVERED_FILES = 200;
 const IGNORED_DIRECTORIES = new Set([
   'node_modules',
   '.git',
@@ -32,11 +35,33 @@ export class DeeplineManifestError extends Error {
   }
 }
 
+function readGlobs(value: unknown, field: 'plays' | 'monitors'): string[] {
+  if (
+    !Array.isArray(value) ||
+    (field === 'plays' && value.length === 0) ||
+    !value.every((glob) => typeof glob === 'string' && glob.trim().length > 0)
+  ) {
+    throw new DeeplineManifestError(
+      `deepline.json "${field}" must be ${field === 'plays' ? 'a non-empty' : 'an'} array of glob strings.`,
+    );
+  }
+  const globs = value.map((glob: string) => glob.trim().replace(/^\.\//, ''));
+  if (globs.some((glob) => glob.startsWith('/') || glob.includes('..'))) {
+    throw new DeeplineManifestError(
+      `deepline.json "${field}" globs must be relative and must not contain "..".`,
+    );
+  }
+  return globs;
+}
+
 export function parseDeeplineManifest(
   raw: string | null,
 ): DeeplineRepoManifest {
   if (raw === null) {
-    return { plays: DEFAULT_PLAY_GLOBS };
+    return {
+      plays: DEFAULT_PLAY_GLOBS,
+      monitors: DEFAULT_MONITOR_GLOBS,
+    };
   }
   let parsed: unknown;
   try {
@@ -49,32 +74,28 @@ export function parseDeeplineManifest(
   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 record = parsed as {
+    plays?: unknown;
+    monitors?: unknown;
+    org?: unknown;
+  };
+  const plays =
+    record.plays === undefined
+      ? DEFAULT_PLAY_GLOBS
+      : readGlobs(record.plays, 'plays');
+  const monitors =
+    record.monitors === undefined
+      ? DEFAULT_MONITOR_GLOBS
+      : readGlobs(record.monitors, 'monitors');
   const org =
     typeof record.org === 'string' && record.org.trim()
       ? record.org.trim()
       : undefined;
-  return { plays, ...(org ? { org } : {}) };
+  return {
+    plays,
+    monitors,
+    ...(org ? { org } : {}),
+  };
 }
 
 export const DEFAULT_MANIFEST_FILE = 'deepline.json';
@@ -121,7 +142,7 @@ export async function readDeeplineManifest(
  * node_modules or fixtures publishes garbage, so vendored/build directories
  * are always skipped and discovery is capped loudly.
  */
-export async function discoverPlayFiles(input: {
+export async function discoverDeploymentFiles(input: {
   projectRoot: string;
   globs: string[];
 }): Promise<string[]> {
@@ -142,9 +163,9 @@ export async function discoverPlayFiles(input: {
       const relativePath = relative(input.projectRoot, absolute);
       if (matchers.some((match) => match(relativePath))) {
         found.push(relativePath);
-        if (found.length > MAX_DISCOVERED_PLAY_FILES) {
+        if (found.length > MAX_DISCOVERED_FILES) {
           throw new DeeplineManifestError(
-            `deepline.json globs matched more than ${MAX_DISCOVERED_PLAY_FILES} play files. Tighten the globs.`,
+            `deepline.json globs matched more than ${MAX_DISCOVERED_FILES} files. Tighten the globs.`,
           );
         }
       }
@@ -160,3 +181,5 @@ export async function discoverPlayFiles(input: {
   await walk(input.projectRoot);
   return found.sort();
 }
+
+export const discoverPlayFiles = discoverDeploymentFiles;

package/dist/bundling-sources/shared_libs/plays/deploy/monitor-files.ts

@@ -0,0 +1,52 @@
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import type {
+  DeploymentMonitorEntry,
+  DeploymentMonitorOutcome,
+} from './api-client';
+import { DeeplineManifestError, discoverDeploymentFiles } from './manifest';
+
+export async function readMonitorFiles(input: {
+  projectRoot: string;
+  rootDirectory: string;
+  globs: string[];
+}): Promise<DeploymentMonitorEntry[]> {
+  const files = await discoverDeploymentFiles(input);
+  if (files.length > 100) {
+    throw new DeeplineManifestError(
+      'A deployment may contain at most 100 monitor definitions. Split the repository into multiple linked targets.',
+    );
+  }
+  return Promise.all(
+    files.map(async (file) => {
+      const sourcePath = input.rootDirectory
+        ? `${input.rootDirectory}/${file}`
+        : file;
+      const raw = await readFile(join(input.projectRoot, file), 'utf8');
+      try {
+        return { file: sourcePath, definition: JSON.parse(raw) as unknown };
+      } catch {
+        throw new DeeplineManifestError(
+          `${sourcePath} must contain a monitor definition as valid JSON.`,
+        );
+      }
+    }),
+  );
+}
+
+export function monitorDeploymentSummary(
+  outcomes: DeploymentMonitorOutcome[],
+): string {
+  return outcomes
+    .map(
+      (outcome) =>
+        `- Monitor \`${outcome.key}\` (\`${outcome.file}\`): ${outcome.status}${
+          outcome.credits != null
+            ? ` (${outcome.credits} Deepline credits)`
+            : ''
+        }${outcome.jobId ? ` — job \`${outcome.jobId}\`` : ''}${
+          outcome.error ? `\n  - ${outcome.error}` : ''
+        }${outcome.warning ? `\n  - :warning: ${outcome.warning}` : ''}`,
+    )
+    .join('\n');
+}

package/dist/bundling-sources/shared_libs/plays/deploy/run-deployment.ts

@@ -4,6 +4,8 @@ import type { PlayCompilerManifest } from '../compiler-manifest';
 import {
   DeployApiClient,
   DeployApiError,
+  type DeploymentMonitorEntry,
+  type DeploymentMonitorOutcome,
   type DeploymentPlayState,
   type RegisterArtifactEntry,
 } from './api-client';
@@ -13,6 +15,7 @@ import {
   DeeplineManifestError,
   DEFAULT_MANIFEST_FILE,
 } from './manifest';
+import { monitorDeploymentSummary, readMonitorFiles } from './monitor-files';
 import type { SerializedPlayDeployment } from './project-serializer';
 import { resolveOwnedPlayReferenceName } from '../play-reference';
 import type { BundledPlayFileResult } from '../bundling/index';
@@ -173,6 +176,7 @@ export type PlayDeploymentRunResult = {
     | 'superseded'
     | 'cancelled';
   outcomes: PlayDeployOutcome[];
+  monitorOutcomes?: DeploymentMonitorOutcome[];
   checkRunId?: number;
 };
 
@@ -419,6 +423,11 @@ export async function runDeployment(
   }
 
   const buildSeconds = () => Math.max(0, (Date.now() - startedAt) / 1000);
+  let monitorOutcomes: DeploymentMonitorOutcome[] = [];
+  const monitorResults = () =>
+    monitorOutcomes.length > 0 ? { monitors: monitorOutcomes } : {};
+  const monitorRunResult = () =>
+    monitorOutcomes.length > 0 ? { monitorOutcomes } : {};
   const finishFailed = async (input: {
     error: string;
     outcomes: PlayDeployOutcome[];
@@ -428,7 +437,7 @@ export async function runDeployment(
       await setStatus({
         status: 'failed',
         error: input.error.slice(0, 2000),
-        results: { plays: input.outcomes },
+        results: { plays: input.outcomes, ...monitorResults() },
         buildSeconds: buildSeconds(),
         ...(input.checkRunId ? { checkRunId: input.checkRunId } : {}),
       });
@@ -453,6 +462,7 @@ export async function runDeployment(
     return {
       finalStatus: 'failed',
       outcomes: input.outcomes,
+      ...monitorRunResult(),
       checkRunId: input.checkRunId,
     };
   };
@@ -462,13 +472,15 @@ export async function runDeployment(
   ): Promise<PlayDeploymentRunResult> => {
     // Carried by the terminal status rather than per-play results so every
     // reader — API, CLI, dashboard, alerting — sees it without parsing them.
-    const finalStatus = outcomes.some((outcome) => outcome.warning)
+    const finalStatus = [...outcomes, ...monitorOutcomes].some(
+      (outcome) => outcome.warning,
+    )
       ? ('succeeded_with_warnings' as const)
       : ('succeeded' as const);
     try {
       await setStatus({
         status: finalStatus,
-        results: { plays: outcomes },
+        results: { plays: outcomes, ...monitorResults() },
         buildSeconds: buildSeconds(),
         ...(checkRun ? { checkRunId: checkRun.checkRunId } : {}),
       });
@@ -494,6 +506,7 @@ export async function runDeployment(
     return {
       finalStatus,
       outcomes,
+      ...monitorRunResult(),
       checkRunId: checkRun?.checkRunId,
     };
   };
@@ -615,8 +628,9 @@ export async function runDeployment(
         await writeCheck({
           conclusion: 'neutral',
           title: `Deployment ${stopped}`,
-          summary:
-            'This deployment was stopped before it finished. Nothing from it went live.',
+          summary: monitorOutcomes.some((outcome) => outcome.jobId)
+            ? 'This deployment was stopped before it finished. Monitor jobs already submitted may have changed live resources; inspect the jobs in its receipt.'
+            : 'This deployment was stopped before it finished. Nothing from it went live.',
         }).catch(() => undefined);
         throw revocation;
       });
@@ -687,6 +701,7 @@ export async function runDeployment(
         status: 'superseded',
         error: `Branch ${deploymentBranch} is now at ${head?.slice(0, 12) ?? '<deleted>'}; this deployment's commit is no longer the head.`,
         buildSeconds: buildSeconds(),
+        ...(monitorOutcomes.length > 0 ? { results: monitorResults() } : {}),
         ...(head ? { observedHeadSha: head } : {}),
       });
       return { finalStatus: 'superseded' as const, outcomes: [] };
@@ -703,12 +718,25 @@ export async function runDeployment(
     const manifestFile = target.manifestPath || DEFAULT_MANIFEST_FILE;
     let manifest;
     let playFiles: string[];
+    let monitorEntries: DeploymentMonitorEntry[] | undefined;
     try {
       manifest = await readDeeplineManifest(projectRoot, manifestFile);
       playFiles = await discoverPlayFiles({
         projectRoot,
         globs: manifest.plays,
       });
+      const discoveredMonitors = await readMonitorFiles({
+        projectRoot,
+        rootDirectory: target.rootDirectory,
+        globs: manifest.monitors,
+      });
+      if (!project && discoveredMonitors.length > 0) {
+        throw new DeeplineManifestError(
+          'Monitor Git deployment requires a linked repository. Deploy individual monitor files with deepline monitors deploy --file.',
+        );
+      }
+      monitorEntries =
+        project && discoveredMonitors.length > 0 ? discoveredMonitors : undefined;
     } catch (error) {
       if (error instanceof DeeplineManifestError) {
         return await failWithCheck({
@@ -739,7 +767,29 @@ export async function runDeployment(
       }
     }
 
-    if (playFiles.length === 0) {
+    if (monitorEntries !== undefined) {
+      const plan = await client.monitors('plan', monitorEntries);
+      monitorOutcomes = plan.monitors;
+      const failed = monitorOutcomes.filter(
+        (outcome) => outcome.status === 'failed',
+      );
+      if (failed.length > 0) {
+        return await failWithCheck({
+          title: 'Monitor validation failed',
+          summary: monitorDeploymentSummary(monitorOutcomes),
+          error: `${failed.length} monitor definition(s) failed validation.`,
+          outcomes: [],
+          annotations: failed.map((outcome) =>
+            annotationForFailure({
+              file: outcome.file,
+              message: outcome.error ?? 'Monitor validation failed.',
+            }),
+          ),
+        });
+      }
+    }
+
+    if (playFiles.length === 0 && monitorOutcomes.length === 0) {
       const checkRun = await postCheckOrNull({
         conclusion: 'neutral',
         title: 'No plays matched',
@@ -956,7 +1006,10 @@ export async function runDeployment(
     }
 
     await setStatus({ status: 'publishing' }).catch(() => undefined);
-    const states = await client.playsState(ordered.map((play) => play.name));
+    const states =
+      ordered.length > 0
+        ? await client.playsState(ordered.map((play) => play.name))
+        : { plays: [] };
     const stateByName = new Map<string, DeploymentPlayState>(
       states.plays.map((play) => [play.name, play]),
     );
@@ -1170,13 +1223,21 @@ export async function runDeployment(
       // no validation signal (the deploy token dies with a terminal status).
       const checkRun = await postCheckOrNull({
         conclusion: 'success',
-        title: `${ordered.length} play${ordered.length === 1 ? '' : 's'} validated and registered (not deployed)`,
+        title:
+          monitorEntries !== undefined
+            ? `${ordered.length} play(s) validated and registered; ${monitorEntries.length} monitor(s) checked (not deployed)`
+            : `${ordered.length} play${ordered.length === 1 ? '' : 's'} validated and registered (not deployed)`,
         ...(annotations.length > 0 ? { annotations } : {}),
-        summary: outcomes
-          .map(
-            (outcome) =>
-              `- \`${outcome.name}\`: ${outcome.status}${outcome.version !== undefined ? ` (v${outcome.version})` : ''}${outcome.sdkUpdated ? ' — SDK updated' : ''}${outcome.warning ? `\n  - :warning: ${outcome.warning}` : ''}`,
-          )
+        summary: [
+          outcomes
+            .map(
+              (outcome) =>
+                `- \`${outcome.name}\`: ${outcome.status}${outcome.version !== undefined ? ` (v${outcome.version})` : ''}${outcome.sdkUpdated ? ' — SDK updated' : ''}${outcome.warning ? `\n  - :warning: ${outcome.warning}` : ''}`,
+            )
+            .join('\n'),
+          monitorDeploymentSummary(monitorOutcomes),
+        ]
+          .filter(Boolean)
           .join('\n'),
       });
       const result = await finishSucceeded(outcomes, checkRun);
@@ -1198,6 +1259,62 @@ export async function runDeployment(
       if (superseded) return superseded;
     }
 
+    if (monitorEntries !== undefined) {
+      monitorOutcomes = (await client.monitors('apply', monitorEntries))
+        .monitors;
+      // Provider changes are not atomic with Play promotion. Retain the exact
+      // jobs in the deployment receipt before waiting or reporting a failure.
+      await setStatus({
+        status: 'publishing',
+        results: { plays: outcomes, ...monitorResults() },
+      });
+      const deadline = Date.now() + 10 * 60_000;
+      while (monitorOutcomes.some((outcome) => outcome.status === 'applying')) {
+        if (Date.now() >= deadline) {
+          throw new RetryableDeploymentError(
+            'Monitor jobs are still reconciling. Retrying this deployment will resume the same jobs.',
+          );
+        }
+        await new Promise((resolve) => setTimeout(resolve, 1000));
+        for (let index = 0; index < monitorOutcomes.length; index += 1) {
+          const outcome = monitorOutcomes[index];
+          if (outcome.status !== 'applying') continue;
+          if (!outcome.jobId) {
+            throw new Error(
+              `Monitor ${outcome.key} has no reconciliation job.`,
+            );
+          }
+          const result = await client.monitorJob(outcome.jobId, outcome.key);
+          const settled = result.monitors.find(
+            (monitor) =>
+              monitor.key === outcome.key && monitor.jobId === outcome.jobId,
+          );
+          if (!settled) {
+            throw new Error(`Monitor job ${outcome.jobId} returned no result.`);
+          }
+          monitorOutcomes[index] = { ...outcome, ...settled };
+        }
+      }
+      if (
+        monitorOutcomes.some(
+          (outcome) =>
+            outcome.status === 'failed' || outcome.status === 'planned',
+        )
+      ) {
+        return await failWithCheck({
+          title: 'Monitor deployment failed',
+          summary: monitorDeploymentSummary(monitorOutcomes),
+          error:
+            'Some monitor changes failed. Applied changes remain live; inspect the reported jobs before retrying.',
+          outcomes,
+        });
+      }
+      // Monitor reconciliation may take minutes. Recheck the branch before
+      // publishing Plays; a newer push must not be reverted by this one.
+      const superseded = await supersedeIfHeadMoved();
+      if (superseded) return { ...superseded, ...monitorRunResult() };
+    }
+
     if (toPromote.length > 0) {
       try {
         const promotion = await client.promote(toPromote);
@@ -1280,13 +1397,22 @@ export async function runDeployment(
 
     const checkRun = await postCheckOrNull({
       conclusion: 'success',
-      title: `Deployed ${outcomes.filter((o) => o.status === 'promoted').length} play(s) (${outcomes.filter((o) => o.status === 'unchanged').length} unchanged)`,
+      title: `Deployed ${outcomes.filter((o) => o.status === 'promoted').length} play(s) (${outcomes.filter((o) => o.status === 'unchanged').length} unchanged)${
+        monitorEntries !== undefined
+          ? `; ${monitorOutcomes.filter((outcome) => outcome.status === 'applied').length} monitor(s) applied`
+          : ''
+      }`,
       ...(annotations.length > 0 ? { annotations } : {}),
-      summary: outcomes
-        .map(
-          (outcome) =>
-            `- \`${outcome.name}\`: ${outcome.status}${outcome.sdkUpdated ? ' — SDK updated' : ''}${outcome.warning ? `\n  - :warning: ${outcome.warning}` : ''}`,
-        )
+      summary: [
+        outcomes
+          .map(
+            (outcome) =>
+              `- \`${outcome.name}\`: ${outcome.status}${outcome.sdkUpdated ? ' — SDK updated' : ''}${outcome.warning ? `\n  - :warning: ${outcome.warning}` : ''}`,
+          )
+          .join('\n'),
+        monitorDeploymentSummary(monitorOutcomes),
+      ]
+        .filter(Boolean)
         .join('\n'),
     });
     return await finishSucceeded(outcomes, checkRun);
@@ -1342,6 +1468,7 @@ export async function runDeployment(
     await setStatus({
       status: 'failed',
       error: message.slice(0, 2000),
+      ...(monitorOutcomes.length > 0 ? { results: monitorResults() } : {}),
       buildSeconds: buildSeconds(),
       ...(checkRunId ? { checkRunId } : {}),
     }).catch(() => undefined);