deepline 0.3.89 → 0.3.91

package/dist/bundling-sources/shared_libs/plays/run-input-summary.ts

@@ -0,0 +1,260 @@
+/**
+ * Display-only, size-bounded projection of a play run's input payload.
+ *
+ * The full input is intentionally NOT persisted in Convex: it can be up to
+ * `PLAY_SUBMIT_INPUT_MAX_BYTES` (1MB) and would bloat the hot-path run-start
+ * write (and risk the ~1MB Convex document limit). This builds a tiny summary —
+ * top-level keys with scalar values truncated and non-scalar values elided to a
+ * compact placeholder — purely so the runs UI can show "what was this called
+ * with". It is bounded hard so it only adds negligible bytes to the existing
+ * start-row write and never touches latency.
+ *
+ * Scalar values are passed through the shared secret redaction (key-aware, plus
+ * value-pattern/high-entropy heuristics) before truncation, mirroring the run
+ * *output* preview path — so an input field like `api_key`/`token`/`password`,
+ * or a secret-looking value, is never persisted or rendered back in the UI.
+ */
+
+import { redactSecretsInCustomerValue } from '../security/secret-redaction';
+
+const MAX_KEYS = 24;
+const MAX_STRING_CHARS = 120;
+const MAX_NESTED_VALUE_CHARS = 52;
+const MAX_OBJECT_PARTS = 4;
+const MAX_ARRAY_PARTS = 3;
+const MAX_TOTAL_BYTES = 2_000;
+
+const OBJECT_PREVIEW_KEYS = [
+  'full_name',
+  'fullName',
+  'name',
+  'first_name',
+  'firstName',
+  'last_name',
+  'lastName',
+  'title',
+  'role',
+  'company_name',
+  'companyName',
+  'company',
+  'domain',
+  'company_domain',
+  'companyDomain',
+  'email',
+  'work_email',
+  'workEmail',
+  'personal_email',
+  'personalEmail',
+  'linkedin_url',
+  'linkedinUrl',
+  'url',
+  'website',
+  'operation',
+  'changedAt',
+  'changed_at',
+  'createdAt',
+  'created_at',
+] as const;
+
+const LOW_SIGNAL_PREVIEW_KEYS = new Set([
+  'id',
+  '_id',
+  'key',
+  'metadata',
+  'raw',
+  'debug',
+  'payload',
+  'headers',
+]);
+
+function truncateString(value: string, maxChars: number): string {
+  return value.length > maxChars ? `${value.slice(0, maxChars)}…` : value;
+}
+
+function formatPreviewKey(key: string): string {
+  return key
+    .replace(/([a-z0-9])([A-Z])/g, '$1 $2')
+    .replace(/[_-]+/g, ' ')
+    .trim()
+    .toLowerCase();
+}
+
+function scalarSummaryValue(
+  value: unknown,
+  key: string,
+  maxChars: number,
+): string | number | boolean | null | undefined {
+  if (value === null) return null;
+  switch (typeof value) {
+    case 'string': {
+      // Key-aware + value-pattern redaction before truncation, so secrets never
+      // land in the persisted summary even when the value is short.
+      // Customer-aware redaction: key-aware + explicit credential patterns,
+      // WITHOUT the high-entropy heuristic — a long opaque customer id
+      // (campaign ids, CRM record ids) must survive the summary.
+      const safe = redactSecretsInCustomerValue(value, key);
+      return truncateString(safe, maxChars);
+    }
+    case 'number':
+    case 'boolean':
+      return value;
+    case 'bigint':
+      return truncateString(value.toString(), maxChars);
+    default:
+      return undefined;
+  }
+}
+
+function formatScalarPreview(value: unknown, key: string): string | null {
+  const summarized = scalarSummaryValue(value, key, MAX_NESTED_VALUE_CHARS);
+  if (summarized === undefined || summarized === null || summarized === '') {
+    return null;
+  }
+  return String(summarized);
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return Boolean(value && typeof value === 'object' && !Array.isArray(value));
+}
+
+function summarizeArrayValue(value: unknown[], key: string): string {
+  if (value.length === 0) return '[0 items]';
+
+  const parts: string[] = [];
+  for (const item of value.slice(0, MAX_ARRAY_PARTS)) {
+    const preview = isRecord(item)
+      ? summarizeObjectValue(item)
+      : Array.isArray(item)
+        ? `[${item.length} item${item.length === 1 ? '' : 's'}]`
+        : formatScalarPreview(item, key);
+    if (preview) parts.push(preview);
+  }
+
+  const suffixCount = value.length - parts.length;
+  const suffix =
+    suffixCount > 0
+      ? ` +${suffixCount} item${suffixCount === 1 ? '' : 's'}`
+      : '';
+  return parts.length > 0
+    ? truncateString(`${parts.join(', ')}${suffix}`, MAX_STRING_CHARS)
+    : `[${value.length} item${value.length === 1 ? '' : 's'}]`;
+}
+
+function summarizeObjectValue(record: Record<string, unknown>): string {
+  const entries = Object.entries(record);
+  const fieldCount = entries.length;
+  if (fieldCount === 0) return '{}';
+
+  const parts: string[] = [];
+  const usedRootKeys = new Set<string>();
+
+  const addPart = (path: string, rootKey: string, value: unknown): boolean => {
+    if (parts.length >= MAX_OBJECT_PARTS) return false;
+    const preview = formatScalarPreview(value, path);
+    if (!preview) return false;
+    parts.push(`${formatPreviewKey(path)}: ${preview}`);
+    usedRootKeys.add(rootKey);
+    return true;
+  };
+
+  const addPreferredFromRecord = (
+    source: Record<string, unknown>,
+    rootKey: string,
+    prefix = '',
+  ) => {
+    for (const preferredKey of OBJECT_PREVIEW_KEYS) {
+      if (preferredKey in source) {
+        addPart(
+          prefix ? `${prefix}.${preferredKey}` : preferredKey,
+          rootKey || preferredKey,
+          source[preferredKey],
+        );
+      }
+      if (parts.length >= MAX_OBJECT_PARTS) return;
+    }
+  };
+
+  addPreferredFromRecord(record, '');
+
+  for (const [rootKey, value] of entries) {
+    if (parts.length >= MAX_OBJECT_PARTS) break;
+    if (usedRootKeys.has(rootKey) || rootKey.startsWith('_')) continue;
+    if (isRecord(value)) {
+      addPreferredFromRecord(value, rootKey, rootKey);
+    }
+  }
+
+  for (const [rootKey, value] of entries) {
+    if (parts.length >= MAX_OBJECT_PARTS) break;
+    if (
+      usedRootKeys.has(rootKey) ||
+      rootKey.startsWith('_') ||
+      LOW_SIGNAL_PREVIEW_KEYS.has(rootKey)
+    ) {
+      continue;
+    }
+    if (Array.isArray(value)) {
+      const preview = summarizeArrayValue(value, rootKey);
+      if (preview) {
+        parts.push(`${formatPreviewKey(rootKey)}: ${preview}`);
+        usedRootKeys.add(rootKey);
+      }
+      continue;
+    }
+    addPart(rootKey, rootKey, value);
+  }
+
+  if (parts.length === 0) {
+    return `{${fieldCount} field${fieldCount === 1 ? '' : 's'}}`;
+  }
+
+  const remaining = Math.max(0, fieldCount - usedRootKeys.size);
+  const suffix =
+    remaining > 0 ? ` +${remaining} field${remaining === 1 ? '' : 's'}` : '';
+  return truncateString(`${parts.join(' · ')}${suffix}`, MAX_STRING_CHARS);
+}
+
+function summarizeValue(value: unknown, key: string): unknown {
+  const scalar = scalarSummaryValue(value, key, MAX_STRING_CHARS);
+  if (scalar !== undefined) {
+    return scalar;
+  }
+  if (Array.isArray(value)) {
+    return summarizeArrayValue(value, key);
+  }
+  if (isRecord(value)) {
+    return summarizeObjectValue(value);
+  }
+  // functions, symbols, undefined: not displayable
+  return undefined;
+}
+
+export function buildPlayRunInputSummary(
+  input: unknown,
+): Record<string, unknown> | undefined {
+  if (!input || typeof input !== 'object' || Array.isArray(input)) {
+    return undefined;
+  }
+  const entries = Object.entries(input as Record<string, unknown>);
+  if (entries.length === 0) return undefined;
+
+  const summary: Record<string, unknown> = {};
+  let count = 0;
+  for (const [key, value] of entries) {
+    if (count >= MAX_KEYS) {
+      const remaining = entries.length - count;
+      summary['…'] = `+${remaining} more field${remaining === 1 ? '' : 's'}`;
+      break;
+    }
+    const summarized = summarizeValue(value, key);
+    if (summarized === undefined) continue;
+    summary[key] = summarized;
+    count += 1;
+    if (JSON.stringify(summary).length > MAX_TOTAL_BYTES) {
+      delete summary[key];
+      summary['…'] = 'truncated';
+      break;
+    }
+  }
+  return Object.keys(summary).length > 0 ? summary : undefined;
+}

package/dist/bundling-sources/shared_libs/plays/run-summary-types.ts

@@ -0,0 +1,49 @@
+/**
+ * Compact, truncated output preview attached to terminal runs by the runs-list
+ * endpoints. Lets the runs drawer render an output table without a blocking
+ * per-run detail fetch. Not the full sheet — capped rows/columns.
+ */
+export type PlayRunSummaryResultPreview = {
+  rows: Record<string, unknown>[];
+  stats: Record<string, unknown>;
+  tableNamespace: string;
+};
+
+export type PlayRunSummaryRecord = {
+  _id: string;
+  playId: string;
+  workflowId: string;
+  /** Backend runtime attempt identifier, when the scheduler exposes one. */
+  runId?: string;
+  playName?: string | null;
+  parentRunId?: string | null;
+  rootRunId?: string | null;
+  status: string;
+  createdAt: number;
+  startedAt?: number;
+  finishedAt?: number;
+  updatedAt: number;
+  artifactTableNamespace?: string;
+  artifactTableNamespaces?: string[];
+  error?: string;
+  outputPreview?: string;
+  billingTotalCredits?: number;
+  billingMaxCreditsPerRun?: number | null;
+  result?: PlayRunSummaryResultPreview;
+  /**
+   * Size-bounded projection of the play function's normalized return value.
+   * It drives run-list columns without fetching the full terminal result for
+   * every polling response. Use the explicit full-run endpoint for the exact
+   * return value.
+   */
+  output?: Record<string, unknown>;
+  /** The compact `output` projection omitted values or fields. */
+  outputPreviewTruncated?: true;
+  /**
+   * Display-only, size-bounded projection of the run's launch input (see
+   * packages/plays/run-input-summary.ts). Top-level keys with scalar values;
+   * large/nested values elided to placeholders. Undefined when the run had no
+   * input. NOT the full input payload.
+   */
+  inputSummary?: Record<string, unknown>;
+};

package/dist/bundling-sources/shared_libs/plays/secrets/errors.ts

@@ -0,0 +1,19 @@
+export const PLAY_SECRET_UNAVAILABLE = 'PLAY_SECRET_UNAVAILABLE' as const;
+
+export class PlaySecretUnavailableError extends Error {
+  readonly code = PLAY_SECRET_UNAVAILABLE;
+
+  constructor(readonly secretName: string) {
+    super(`Secret ${secretName} is not active or does not exist.`);
+    this.name = 'PlaySecretUnavailableError';
+  }
+}
+
+export function playSecretUnavailableErrorFrom(
+  error: unknown,
+): PlaySecretUnavailableError | null {
+  const message = error instanceof Error ? error.message : String(error);
+  const match =
+    /Secret ([A-Z][A-Z0-9_]*) is not active or does not exist\./.exec(message);
+  return match ? new PlaySecretUnavailableError(match[1]) : null;
+}

package/dist/bundling-sources/shared_libs/plays/share/copy.ts

@@ -0,0 +1,271 @@
+/**
+ * Package-owned helpers for share-page copy: the generation input shape, a deterministic
+ * (no-LLM) fallback builder, override merging, and validation of model output.
+ *
+ * Nothing here performs network I/O — see generate-card.ts for the LLM call.
+ */
+import type {
+  PlayShareCopyOverrides,
+  PlayShareGeneratedCopy,
+  PlayShareSchemaShape,
+  PlayShareStaticPipelineSummary,
+} from './types';
+
+/** A single safe, bounded sample of a successful run. */
+export type ShareRunSummarySample = {
+  rowCount: number | null;
+  outputLeadCount: number | null;
+  columns: string[];
+};
+
+/**
+ * Everything the copy generators are allowed to see about a revision. This is
+ * assembled server-side and contains no provider spend, secrets, or source.
+ */
+export type ShareCardGenerationInput = {
+  playName: string;
+  displayName?: string | null;
+  ownerDisplayName: string | null;
+  version: number;
+  graphHash: string | null;
+  sourceHash: string;
+  summary: PlayShareStaticPipelineSummary;
+  inputSchema: PlayShareSchemaShape;
+  outputSchema: PlayShareSchemaShape;
+  providerNames: string[];
+  existingDescription: string | null;
+  sampleRunSummaries: ShareRunSummarySample[];
+};
+
+const COPY_FIELDS: Array<keyof PlayShareGeneratedCopy> = [
+  'title',
+  'shortDescription',
+  'jtbd',
+  'whenToUse',
+  'inputs',
+  'outputs',
+  'agentPrompt',
+  'llmSummary',
+  'seoTitle',
+  'seoDescription',
+];
+
+function humanizePlayName(name: string): string {
+  const cleaned = name
+    .split('/')
+    .pop()!
+    .replace(/[._-]+/g, ' ')
+    .trim();
+  if (!cleaned) {
+    return 'Play';
+  }
+  return cleaned
+    .split(/\s+/)
+    .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
+    .join(' ');
+}
+
+function firstSentence(text: string): string {
+  const trimmed = text.trim();
+  const match = trimmed.match(/^.*?[.!?](\s|$)/);
+  return (match ? match[0] : trimmed).trim();
+}
+
+function joinList(items: string[], fallback: string): string {
+  const cleaned = items.filter(Boolean);
+  if (cleaned.length === 0) {
+    return fallback;
+  }
+  if (cleaned.length === 1) {
+    return cleaned[0];
+  }
+  return `${cleaned.slice(0, -1).join(', ')} and ${cleaned[cleaned.length - 1]}`;
+}
+
+/**
+ * Build a conservative card from structured facts, no model required. Used as a
+ * deterministic fallback and as the seed for the LLM prompt. Uncertain parts are
+ * intentionally generic rather than invented.
+ */
+export function buildDeterministicShareCard(
+  input: ShareCardGenerationInput,
+): PlayShareGeneratedCopy {
+  const human = input.displayName?.trim() || humanizePlayName(input.playName);
+  const providers = input.providerNames.filter(Boolean);
+  const providerPhrase =
+    providers.length > 0
+      ? ` using ${joinList(providers, 'GTM providers')}`
+      : '';
+  const inputFields = input.inputSchema?.fields ?? [];
+  const outputFields = input.outputSchema?.fields ?? [];
+
+  const existing = input.existingDescription?.trim() || '';
+  const shortDescription = existing
+    ? firstSentence(existing)
+    : `${human} is a Deepline play that automates a ${input.summary.stepCount}-step GTM pipeline${providerPhrase}.`;
+
+  const jtbd = existing
+    ? existing
+    : `Run a repeatable, multi-step GTM workflow${providerPhrase} without wiring providers together by hand.`;
+
+  const whenToUse =
+    providers.length > 0
+      ? [
+          `You need data from ${joinList(providers, 'multiple providers')} in one pass.`,
+          'You want a repeatable pipeline instead of one-off lookups.',
+          'You want an agent or teammate to run the same workflow on demand.',
+        ]
+      : [
+          'You need a repeatable, multi-step GTM workflow.',
+          'You want an agent or teammate to run it on demand.',
+          'You want consistent output columns every run.',
+        ];
+
+  const inputs =
+    inputFields.length > 0
+      ? inputFields
+      : input.summary.hasMap
+        ? ['A list of rows to process (CSV or table).']
+        : ['Run parameters for the workflow.'];
+
+  const outputs =
+    outputFields.length > 0
+      ? outputFields
+      : ['An enriched output table with one row per processed record.'];
+
+  const agentPrompt = `Use the Deepline "${input.playName}" play to ${jtbd
+    .charAt(0)
+    .toLowerCase()}${jtbd.slice(1)}`;
+
+  const llmSummary = [
+    `${human} (Deepline play "${input.playName}", version ${input.version}).`,
+    shortDescription,
+    `Pipeline: ${input.summary.stepCount} steps, ${input.summary.providerCount} provider${input.summary.providerCount === 1 ? '' : 's'}${input.summary.hasMap ? ', processes input rows as a dataset' : ''}.`,
+    inputFields.length > 0 ? `Inputs: ${inputFields.join(', ')}.` : null,
+    outputFields.length > 0 ? `Outputs: ${outputFields.join(', ')}.` : null,
+  ]
+    .filter(Boolean)
+    .join(' ');
+
+  const primaryInput = inputs[0]?.replace(/\.$/, '') ?? 'GTM inputs';
+  const primaryOutput = outputs[0]?.replace(/\.$/, '') ?? 'workflow output';
+  const providerCount = input.summary.providerCount;
+  const seoTitle = `${human}: Inputs, Outputs & CLI Setup`;
+  const seoDescription = [
+    `Run or fork this Deepline play from ${primaryInput} to ${primaryOutput}.`,
+    `See steps, ${providerCount} provider${providerCount === 1 ? '' : 's'}, setup, and CLI commands.`,
+  ].join(' ');
+
+  return {
+    title: human,
+    shortDescription,
+    jtbd,
+    whenToUse,
+    inputs,
+    outputs,
+    agentPrompt,
+    llmSummary,
+    seoTitle,
+    seoDescription,
+  };
+}
+
+function nonEmptyString(value: unknown): value is string {
+  return typeof value === 'string' && value.trim().length > 0;
+}
+
+function nonEmptyStringArray(value: unknown): value is string[] {
+  return (
+    Array.isArray(value) &&
+    value.length > 0 &&
+    value.every((item) => nonEmptyString(item))
+  );
+}
+
+/**
+ * Validate an arbitrary object as `PlayShareGeneratedCopy`. Returns the typed
+ * copy or throws (loud failure) so model output can never silently degrade.
+ */
+export function parseGeneratedCopy(value: unknown): PlayShareGeneratedCopy {
+  if (!value || typeof value !== 'object') {
+    throw new Error('Generated copy must be an object.');
+  }
+  const record = value as Record<string, unknown>;
+  const stringFields: Array<keyof PlayShareGeneratedCopy> = [
+    'title',
+    'shortDescription',
+    'jtbd',
+    'agentPrompt',
+    'llmSummary',
+    'seoTitle',
+    'seoDescription',
+  ];
+  for (const field of stringFields) {
+    if (!nonEmptyString(record[field])) {
+      throw new Error(
+        `Generated copy field "${field}" must be a non-empty string.`,
+      );
+    }
+  }
+  const arrayFields: Array<keyof PlayShareGeneratedCopy> = [
+    'whenToUse',
+    'inputs',
+    'outputs',
+  ];
+  for (const field of arrayFields) {
+    if (!nonEmptyStringArray(record[field])) {
+      throw new Error(
+        `Generated copy field "${field}" must be a non-empty array of strings.`,
+      );
+    }
+  }
+
+  return {
+    title: (record.title as string).trim(),
+    shortDescription: (record.shortDescription as string).trim(),
+    jtbd: (record.jtbd as string).trim(),
+    whenToUse: (record.whenToUse as string[]).map((item) => item.trim()),
+    inputs: (record.inputs as string[]).map((item) => item.trim()),
+    outputs: (record.outputs as string[]).map((item) => item.trim()),
+    agentPrompt: (record.agentPrompt as string).trim(),
+    llmSummary: (record.llmSummary as string).trim(),
+    seoTitle: (record.seoTitle as string).trim(),
+    seoDescription: (record.seoDescription as string).trim(),
+  };
+}
+
+function isMeaningfulOverride(value: unknown): boolean {
+  if (nonEmptyString(value)) {
+    return true;
+  }
+  if (Array.isArray(value)) {
+    return value.some((item) => nonEmptyString(item));
+  }
+  return false;
+}
+
+/**
+ * Merge owner overrides over generated copy at read time. Only non-empty
+ * overrides win; everything else falls through to the generated value.
+ */
+export function mergeShareCopy(
+  generated: PlayShareGeneratedCopy,
+  overrides: PlayShareCopyOverrides | null | undefined,
+): PlayShareGeneratedCopy {
+  if (!overrides) {
+    return generated;
+  }
+  const merged: PlayShareGeneratedCopy = { ...generated };
+  for (const field of COPY_FIELDS) {
+    const override = overrides[field];
+    if (isMeaningfulOverride(override)) {
+      // Field types are homogeneous per key; cast is safe after the check.
+      (merged[field] as unknown) = Array.isArray(override)
+        ? override
+            .filter((item) => nonEmptyString(item))
+            .map((item) => item.trim())
+        : (override as string).trim();
+    }
+  }
+  return merged;
+}