deepline 0.3.213 → 0.3.215

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);

package/dist/bundling-sources/shared_libs/plays/settings-contract.ts

@@ -0,0 +1,176 @@
+import { z } from 'zod';
+
+/** Keep schema diagnostics readable in both interactive settings and the CLI. */
+export function formatPlaySettingsError(error: unknown): string {
+  if (error instanceof z.ZodError)
+    return [...new Set(error.issues.map((issue) => issue.message))].join(' ');
+  return error instanceof Error ? error.message : String(error);
+}
+
+/** Location organizes Plays. Existing workspace permissions still apply. */
+export const PLAY_LOCATION_ROOTS = [
+  {
+    value: 'person',
+    label: 'Personal',
+    description:
+      'The creator’s personal root, displayed as their name followed by “’s team”.',
+  },
+  {
+    value: 'team',
+    label: 'Team library',
+    description:
+      'The shared team library. Publishing moves personal locations here, keeping their folders.',
+  },
+] as const;
+
+const folder = z
+  .string()
+  .min(1)
+  .max(128)
+  .refine(
+    (value) =>
+      value === value.trim() &&
+      value !== '.' &&
+      value !== '..' &&
+      !/[\\/\u0000-\u001f\u007f]/u.test(value),
+    'Folder names must be trimmed, cannot be . or .., and cannot contain slashes or control characters.',
+  );
+export const playPathSchema = z
+  .union([
+    z.null(),
+    z
+      .object({
+        root: z.enum(['person', 'team']),
+        folders: z.array(folder).max(16).default([]),
+      })
+      .strict(),
+  ])
+  .transform((path) =>
+    path?.root === 'person' && path.folders.length === 0 ? null : path,
+  );
+export type PlayPath = z.output<typeof playPathSchema>;
+
+export function parsePlayPath(value: string): PlayPath {
+  const [root, ...parts] = value.split('/');
+  if (!PLAY_LOCATION_ROOTS.some((option) => option.value === root)) {
+    throw new Error(
+      'Path must start with person or team. Example: person/Research/ICP.',
+    );
+  }
+  let folders: string[];
+  try {
+    folders = parts.map(decodeURIComponent);
+  } catch {
+    throw new Error(
+      'Path contains an invalid percent escape. Encode a literal % as %25.',
+    );
+  }
+  return playPathSchema.parse({ root, folders });
+}
+export function formatPlayPath(path: PlayPath): string {
+  return path === null
+    ? 'person'
+    : [path.root, ...path.folders.map(encodeURIComponent)].join('/');
+}
+export function personalPlayRootLabel(ownerName?: string | null): string {
+  const name = ownerName?.trim();
+  return name ? `${name.split(/\s+/)[0]}’s team` : 'Personal';
+}
+export function displayPlayPath(
+  path: PlayPath,
+  ownerName?: string | null,
+): string {
+  return [
+    path?.root === 'team' ? 'Team library' : personalPlayRootLabel(ownerName),
+    ...(path?.folders ?? []),
+  ].join(' / ');
+}
+export function publishedPlayPath(path: PlayPath): PlayPath {
+  return { root: 'team', folders: path?.folders ?? [] };
+}
+
+/** One registry drives validation, defaults, CLI keys/help and settings controls. */
+export const PLAY_SETTING_FIELDS = {
+  path: {
+    schema: playPathSchema
+      .default(null)
+      .describe(
+        'Play location. Null means the creator’s personal root. Publishing moves it into Team library, preserving folders.',
+      ),
+    label: 'Location',
+    description:
+      'Organize this Play in the creator’s personal root or Team library. Publishing moves it to Team library and keeps its folders. Workspace sharing permissions apply in both roots.',
+    get defaultValue(): PlayPath {
+      return this.schema.parse(undefined);
+    },
+    cli: {
+      valueSyntax: 'person[/folder/…] | team[/folder/…] | null',
+      examples: [
+        'person',
+        'person/Research/ICP',
+        'team',
+        'team/Research',
+        'null',
+      ],
+      parse: (value: string) =>
+        value === 'null' ? null : parsePlayPath(value),
+      format: formatPlayPath,
+    },
+    ui: { control: 'play-location-picker' as const },
+  },
+} as const;
+export const playSettingsSchema = z.object(
+  Object.fromEntries(
+    Object.entries(PLAY_SETTING_FIELDS).map(([key, field]) => [
+      key,
+      field.schema,
+    ]),
+  ) as {
+    [K in keyof typeof PLAY_SETTING_FIELDS]: (typeof PLAY_SETTING_FIELDS)[K]['schema'];
+  },
+).passthrough();
+export const playSettingsPatchSchema = z
+  .object(
+    Object.fromEntries(
+      Object.entries(PLAY_SETTING_FIELDS).map(([key, field]) => [
+        key,
+        field.schema.unwrap().optional(),
+      ]),
+    ) as {
+      [K in keyof typeof PLAY_SETTING_FIELDS]: z.ZodOptional<
+        ReturnType<(typeof PLAY_SETTING_FIELDS)[K]['schema']['unwrap']>
+      >;
+    },
+  )
+  .strict()
+  .refine(
+    (patch) => Object.keys(patch).length > 0,
+    'Supply at least one setting.',
+  );
+export type PlaySettings = {
+  [K in keyof typeof PLAY_SETTING_FIELDS]: z.output<
+    (typeof PLAY_SETTING_FIELDS)[K]['schema']
+  >;
+};
+export type PlaySettingsPatch = z.output<typeof playSettingsPatchSchema>;
+/** Validate registered keys while preserving future keys in stored objects. */
+export function parsePlaySettings(value: unknown): PlaySettings {
+  return playSettingsSchema.parse(value) as PlaySettings;
+}
+export const DEFAULT_PLAY_SETTINGS: PlaySettings = parsePlaySettings({});
+export type PlaySettingsResult = {
+  playDefinitionId: string;
+  ownerUserId: string | null;
+  ownerName: string | null;
+  settings: PlaySettings;
+};
+export type PlaySettingsPathsPage = {
+  paths: Array<{
+    path: PlayPath;
+    ownerUserId: string | null;
+    ownerName: string | null;
+    playName: string;
+  }>;
+  cursor: string | null;
+  hasMore: boolean;
+};