deepline 0.3.258 → 0.3.260

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

@@ -119,16 +119,18 @@ export const PLAY_SETTING_FIELDS = {
     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 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(
@@ -174,3 +176,83 @@ export type PlaySettingsPathsPage = {
   cursor: string | null;
   hasMore: boolean;
 };
+
+/** A folder inside one location root. `ownerUserId` scopes personal roots. */
+export type PlayFolderLocation = {
+  root: 'person' | 'team';
+  ownerUserId?: string | null;
+  folders: readonly string[];
+};
+export type PlayFolderMove = {
+  playName: string;
+  from: PlayPath;
+  path: PlayPath;
+};
+
+function sameFolderRoot(
+  left: PlayFolderLocation,
+  right: PlayFolderLocation,
+): boolean {
+  return (
+    left.root === right.root &&
+    (left.root === 'team' ||
+      (left.ownerUserId ?? null) === (right.ownerUserId ?? null))
+  );
+}
+
+function startsWithFolders(
+  folders: readonly string[],
+  prefix: readonly string[],
+): boolean {
+  return (
+    folders.length >= prefix.length &&
+    prefix.every((segment, index) => folders[index] === segment)
+  );
+}
+
+/**
+ * Folders exist only as Play locations, so moving or renaming a folder moves
+ * every Play below it: `from.folders` is replaced by `to.folders` and the rest
+ * of each path is kept. The dashboard and `deepline plays settings
+ * move-folder` both apply this plan through the per-Play settings API, so a
+ * retried or interrupted move converges on the same paths.
+ */
+export function planPlayFolderMove(
+  paths: PlaySettingsPathsPage['paths'],
+  from: PlayFolderLocation,
+  to: PlayFolderLocation,
+): PlayFolderMove[] {
+  if (from.folders.length === 0)
+    throw new Error('Choose a folder to move; a root cannot be moved.');
+  if (sameFolderRoot(from, to) && startsWithFolders(to.folders, from.folders))
+    throw new Error('A folder cannot be moved into itself.');
+  const moves: PlayFolderMove[] = [];
+  for (const entry of paths) {
+    const location: PlayFolderLocation = {
+      root: entry.path?.root ?? 'person',
+      ownerUserId: entry.ownerUserId,
+      folders: entry.path?.folders ?? [],
+    };
+    if (!sameFolderRoot(location, from)) continue;
+    if (!startsWithFolders(location.folders, from.folders)) continue;
+    if (
+      to.root === 'person' &&
+      (entry.ownerUserId ?? null) !== (to.ownerUserId ?? null)
+    )
+      throw new Error(
+        `${entry.playName} belongs to another person, so it cannot move into this personal root. Move the folder to team instead.`,
+      );
+    moves.push({
+      playName: entry.playName,
+      from: entry.path,
+      path: playPathSchema.parse({
+        root: to.root,
+        folders: [
+          ...to.folders,
+          ...location.folders.slice(from.folders.length),
+        ],
+      }),
+    });
+  }
+  return moves;
+}

package/dist/bundling-sources/shared_libs/plays/static-pipeline.ts

@@ -390,11 +390,13 @@ function truncateStaticSubstepsForStorage(
   return (substeps ?? []).map((substep) => {
     const {
       paramsSource: _paramsSource,
+      inputPrelude: _inputPrelude,
       returnSource: _returnSource,
       sourceText: _sourceText,
       ...substepWithoutSourceText
     } = substep as PlayStaticSubstep & {
       paramsSource?: string;
+      inputPrelude?: string;
       pipeline?: PlayStaticPipeline | null;
       returnSource?: string;
       sourceText?: string;
@@ -1308,6 +1310,9 @@ export type PlayStaticSubstep = PlayStaticSubstepMetadata &
         toolId: string;
         field: string;
         paramsSource?: string;
+        /** The code computing the call's local inputs (`const candidate =
+         *  …`), when its inputs are locals of the calling function. */
+        inputPrelude?: string;
         sourceText?: string;
         description?: string;
         inLoop?: boolean;

package/dist/bundling-sources/shared_libs/plays/trigger-config-contract.ts

@@ -0,0 +1,222 @@
+import { z } from 'zod';
+
+/**
+ * Trigger configuration contract shared by the API route, the SDK/CLI, and the
+ * Play canvas. A Play's cron and webhook triggers are SOURCE declarations
+ * (`definePlay(..., { cron, webhook })`). A configuration change rewrites that
+ * declaration in the live revision's source and publishes the result as a new
+ * revision, so the source, the revision's stored bindings, and the scheduler
+ * bindings never disagree.
+ *
+ * The update is declarative: `cron`/`webhook` name the desired declaration,
+ * `null` removes it, and an omitted key leaves it unchanged. Repeating the same
+ * request after a lost response is a no-op, because the live revision already
+ * declares the requested state.
+ */
+
+const SECRET_NAME_PATTERN = /^[A-Z][A-Z0-9_]{1,63}$/;
+const secretName = z
+  .string()
+  .regex(
+    SECRET_NAME_PATTERN,
+    'Secret names are uppercase letters, digits, and underscores, starting with a letter.',
+  );
+
+export const PLAY_TRIGGER_TOLERANCE_SECONDS_MAX = 3600;
+
+export const playCronTriggerConfigSchema = z
+  .object({
+    schedule: z
+      .string()
+      .trim()
+      .min(1, 'Schedule is required.')
+      .max(256)
+      .describe('Standard 5-field cron expression, e.g. "0 9 * * 1-5".'),
+    timezone: z
+      .string()
+      .trim()
+      .min(1)
+      .max(64)
+      .optional()
+      .describe('IANA timezone. Omitted means UTC.'),
+    input: z
+      .record(z.string(), z.unknown())
+      .optional()
+      .describe('Static JSON object passed as the input of every cron run.'),
+  })
+  .strict();
+export type PlayCronTriggerConfig = z.output<
+  typeof playCronTriggerConfigSchema
+>;
+
+export const playWebhookAuthConfigSchema = z.discriminatedUnion('type', [
+  z
+    .object({
+      type: z.literal('standard-webhooks'),
+      headerFamily: z.enum(['standard', 'svix']),
+      signingSecrets: z.array(secretName).min(1).max(4),
+      toleranceSeconds: z
+        .number()
+        .int()
+        .min(1)
+        .max(PLAY_TRIGGER_TOLERANCE_SECONDS_MAX)
+        .optional(),
+    })
+    .strict(),
+  z
+    .object({
+      type: z.literal('hmac'),
+      secretEnv: secretName,
+      header: z.string().trim().min(1).max(128).optional(),
+      signaturePrefix: z.string().max(64).optional(),
+    })
+    .strict(),
+]);
+export type PlayWebhookAuthConfig = z.output<
+  typeof playWebhookAuthConfigSchema
+>;
+
+export const playWebhookTriggerConfigSchema = z
+  .object({
+    /** Omitted or null: an unsigned webhook. */
+    auth: playWebhookAuthConfigSchema.nullable().optional(),
+  })
+  .strict();
+export type PlayWebhookTriggerConfig = z.output<
+  typeof playWebhookTriggerConfigSchema
+>;
+
+export const playTriggerConfigUpdateSchema = z
+  .object({
+    /**
+     * Optimistic concurrency guard. When present, the update is refused with
+     * 409 if the live revision is no longer this one.
+     */
+    expectedRevisionId: z.string().trim().min(1).optional(),
+    cron: playCronTriggerConfigSchema.nullable().optional(),
+    webhook: playWebhookTriggerConfigSchema.nullable().optional(),
+  })
+  .strict()
+  .refine(
+    (update) => update.cron !== undefined || update.webhook !== undefined,
+    {
+      message: 'Provide cron and/or webhook. Use null to remove a trigger.',
+    },
+  );
+export type PlayTriggerConfigUpdate = z.output<
+  typeof playTriggerConfigUpdateSchema
+>;
+
+export type PlayTriggerConfigCronState = {
+  bindingId: string | null;
+  schedule: string;
+  timezone: string | null;
+  input: Record<string, unknown> | null;
+  /** Scheduler binding status: active, inactive (credit hold), or blocked. */
+  status: string | null;
+  nextScheduledAt: number | null;
+  lastScheduledAt: number | null;
+  blockedReasonCode: string | null;
+  blockedReason: string | null;
+};
+
+export type PlayTriggerConfigWebhookState = {
+  bindingId: string | null;
+  url: string | null;
+  status: string | null;
+  auth: PlayWebhookAuthConfig | null;
+};
+
+export type PlayTriggerConfigReadOnlyReason =
+  | 'not_published'
+  | 'git_managed'
+  | 'archived';
+
+export type PlayTriggerConfigView = {
+  name: string;
+  playDefinitionId: string;
+  liveRevisionId: string | null;
+  liveVersion: number | null;
+  /** Null when the triggers can be changed here; otherwise why not. */
+  readOnly: { reason: PlayTriggerConfigReadOnlyReason; message: string } | null;
+  cron: PlayTriggerConfigCronState | null;
+  webhook: PlayTriggerConfigWebhookState | null;
+};
+
+export type PlayTriggerConfigUpdateResult = {
+  /** False when the live revision already declared the requested triggers. */
+  changed: boolean;
+  /** Newly published revision, when `changed`. */
+  revisionId: string | null;
+  version: number | null;
+  triggers: PlayTriggerConfigView;
+};
+
+export function formatPlayTriggerConfigError(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);
+}
+
+/*
+ * One request for every surface. The dashboard, the SDK client, and the CLI
+ * all turn a user's intent into the request below with these functions and
+ * send it to the same route; none of them assembles the body itself.
+ */
+
+export {
+  PLAY_TRIGGER_CONFIG_UPDATE_METHOD,
+  playTriggerConfigPath,
+} from './trigger-config-route';
+
+/** Schedule (cron) intent: off, or on with its expression, zone and input. */
+export type PlayScheduleIntent =
+  | { enabled: false }
+  | {
+      enabled: true;
+      schedule: string;
+      /** Omitted or null: UTC, left unnamed in source. */
+      timezone?: string | null;
+      /** Omitted, null, or empty: no static input. */
+      input?: Record<string, unknown> | null;
+    };
+
+/** Webhook intent: off, or on with its authentication (null = unsigned). */
+export type PlayWebhookIntent =
+  | { enabled: false }
+  | { enabled: true; auth: PlayWebhookAuthConfig | null };
+
+/**
+ * The one request builder. Validates against the same schema the route
+ * parses with, so a surface cannot build a request the server would read
+ * differently. Throws a ZodError on an invalid intent.
+ */
+export function buildPlayTriggerConfigUpdate(intent: {
+  schedule?: PlayScheduleIntent;
+  webhook?: PlayWebhookIntent;
+  expectedRevisionId?: string | null;
+}): PlayTriggerConfigUpdate {
+  const schedule = intent.schedule;
+  const webhook = intent.webhook;
+  return playTriggerConfigUpdateSchema.parse({
+    ...(intent.expectedRevisionId
+      ? { expectedRevisionId: intent.expectedRevisionId }
+      : {}),
+    ...(schedule === undefined
+      ? {}
+      : {
+          cron: schedule.enabled
+            ? {
+                schedule: schedule.schedule,
+                ...(schedule.timezone ? { timezone: schedule.timezone } : {}),
+                ...(schedule.input && Object.keys(schedule.input).length > 0
+                  ? { input: schedule.input }
+                  : {}),
+              }
+            : null,
+        }),
+    ...(webhook === undefined
+      ? {}
+      : { webhook: webhook.enabled ? { auth: webhook.auth } : null }),
+  });
+}

package/dist/bundling-sources/shared_libs/plays/trigger-config-route.ts

@@ -0,0 +1,15 @@
+/**
+ * The trigger-config route, kept free of `zod` and every other dependency.
+ *
+ * The SDK client calls it at runtime, and the SDK client is bundled into
+ * authored Plays by the deployed play bundler, which resolves only the traced
+ * workspace sources — not their npm dependencies. Importing the schema module
+ * (`trigger-config-contract.ts`) from the client for this one path would pull
+ * `zod` into every Play bundle and fail it ("Could not resolve \"zod\"").
+ */
+
+export const PLAY_TRIGGER_CONFIG_UPDATE_METHOD = 'PUT' as const;
+
+export function playTriggerConfigPath(playName: string): string {
+  return `/api/v2/plays/${encodeURIComponent(playName)}/triggers`;
+}