deepline 0.0.1 → 0.1.1

package/dist/repo/sdk/src/worker-play-entry.ts

@@ -0,0 +1,286 @@
+/**
+ * Workers-only Deepline SDK entry.
+ *
+ * The normal `deepline` package entry exports the REST client, config loading,
+ * file writers, and CLI-oriented helpers. Per-graphHash Workers only need the
+ * tiny play-definition DSL at runtime. The esm_workers bundler aliases
+ * `import { definePlay } from "deepline"` to this file so user plays do not
+ * compile the full SDK client into every dynamic Worker isolate.
+ */
+
+import type {
+  ConditionalStepResolver,
+  DefinePlayConfig,
+  DeeplineNamedPlay,
+  DeeplinePlayRuntimeContext,
+  DefinedPlay,
+  PlayBindings,
+  PlayInputContract,
+  PlayReturnObject,
+  PlayStepProgramStep,
+  StepProgram,
+  StepProgramResolver,
+  StepResolver,
+} from './play.js';
+
+export type {
+  ConditionalStepResolver,
+  DefinePlayConfig,
+  DeeplineNamedPlay,
+  DeeplinePlayRuntimeContext,
+  DefinedPlay,
+  MapStepBuilder,
+  MapStepResolver,
+  PlayBindings,
+  PlayDataset,
+  PlayDatasetInput,
+  PlayInputContract,
+  PlayJob,
+  PlayReturnObject,
+  PlayStepProgramStep,
+  PrebuiltPlayRef,
+  StepProgram,
+  StepProgramResolver,
+  StepResolver,
+  ToolExecuteResult,
+} from './play.js';
+
+const PLAY_METADATA_SYMBOL = Symbol.for('deepline.play.metadata');
+
+type PlayMetadata = {
+  name: string;
+  bindings?: PlayBindings;
+  inputSchema?: Record<string, unknown>;
+  billing?: PlayBindings['billing'];
+};
+
+class WorkerConditionalStepResolver<Row, Value, ElseValue>
+  implements ConditionalStepResolver<Row, Value, ElseValue>
+{
+  readonly kind = 'conditional' as const;
+
+  constructor(
+    readonly when: (row: Row, index: number) => boolean | Promise<boolean>,
+    readonly run: StepResolver<Row, Value>,
+    readonly elseValue: ElseValue,
+  ) {}
+
+  else<ValueElse>(
+    value: ValueElse,
+  ): ConditionalStepResolver<Row, Value, ValueElse> {
+    return new WorkerConditionalStepResolver(this.when, this.run, value);
+  }
+}
+
+class WorkerStepProgram<Input, Output, ReturnValue>
+  implements StepProgram<Input, Output, ReturnValue>
+{
+  readonly kind = 'steps' as const;
+  declare readonly __inputType?: (input: Input) => void;
+
+  constructor(
+    readonly steps: readonly PlayStepProgramStep[],
+    readonly returnResolver?: StepResolver<Output, ReturnValue>,
+  ) {}
+
+  step<Name extends string, Value>(
+    name: Name,
+    resolver:
+      | StepResolver<Output, Value>
+      | ConditionalStepResolver<Output, Value>
+      | StepProgramResolver<Output, Value>,
+  ): StepProgram<Input, Output & Record<Name, Value>, ReturnValue> {
+    if (!name.trim()) {
+      throw new Error('steps().step(name, ...) requires a non-empty step name.');
+    }
+    return new WorkerStepProgram(
+      [
+        ...this.steps,
+        {
+          name,
+          resolver: resolver as PlayStepProgramStep['resolver'],
+        },
+      ],
+      this.returnResolver as StepResolver<
+        Output & Record<Name, Value>,
+        ReturnValue
+      >,
+    );
+  }
+
+  return<Value>(
+    resolver: StepResolver<Output, Value>,
+  ): StepProgram<Input, Output, Value> {
+    return new WorkerStepProgram(this.steps, resolver);
+  }
+}
+
+function createUnavailableNamedPlayHandle<TInput, TOutput extends PlayReturnObject>(
+  name: string,
+): DeeplineNamedPlay<TInput, TOutput> {
+  const unavailable = () => {
+    throw new Error(
+      `definePlay("${name}") remote lifecycle methods are unavailable inside workers_edge play execution. Use ctx.runPlay(...) for runtime composition.`,
+    );
+  };
+  return {
+    name,
+    get: unavailable,
+    runs: unavailable,
+    versions: unavailable,
+    publish: unavailable,
+    clearHistory: unavailable,
+    run: unavailable,
+    runSync: unavailable,
+  };
+}
+
+export function steps<TInput>(): StepProgram<TInput, TInput, TInput> {
+  return new WorkerStepProgram<TInput, TInput, TInput>([]);
+}
+
+export function when<Row, Value>(
+  predicate: (row: Row, index: number) => boolean | Promise<boolean>,
+  resolver: StepResolver<Row, Value>,
+): ConditionalStepResolver<Row, Value, null> {
+  return new WorkerConditionalStepResolver(predicate, resolver, null);
+}
+
+export function defineInput<TInput>(
+  schema: Record<string, unknown>,
+): PlayInputContract<TInput> {
+  if (!schema || typeof schema !== 'object' || Array.isArray(schema)) {
+    throw new Error(
+      'defineInput<T>(schema) requires a JSON-schema-like object.',
+    );
+  }
+  return { schema };
+}
+
+export function definePlay<TInput, TOutput extends PlayReturnObject>(
+  config: DefinePlayConfig<TInput, TOutput>,
+): DefinedPlay<TInput, TOutput>;
+export function definePlay<TInput, TOutput extends PlayReturnObject>(
+  name: string,
+  fn: (ctx: DeeplinePlayRuntimeContext, input: TInput) => Promise<TOutput>,
+  bindings?: PlayBindings,
+): DefinedPlay<TInput, TOutput>;
+export function definePlay<TInput, TOutput extends PlayReturnObject>(
+  nameOrConfig: string | DefinePlayConfig<TInput, TOutput>,
+  maybeFn?: (
+    ctx: DeeplinePlayRuntimeContext,
+    input: TInput,
+  ) => Promise<TOutput>,
+  maybeBindings?: PlayBindings,
+): DefinedPlay<TInput, TOutput> {
+  const config =
+    typeof nameOrConfig === 'string'
+      ? {
+          name: nameOrConfig,
+          fn: maybeFn,
+          bindings: maybeBindings,
+          inputSchema: undefined,
+          billing: maybeBindings?.billing,
+        }
+      : {
+          name: nameOrConfig.id,
+          fn: nameOrConfig.run,
+          bindings: nameOrConfig.bindings,
+          inputSchema: nameOrConfig.input.schema,
+          billing: nameOrConfig.billing,
+        };
+
+  const name = config.name;
+  const fn = config.fn;
+  if (typeof fn !== 'function') {
+    throw new Error('definePlay(...) requires an async run function.');
+  }
+  if (name.includes('/')) {
+    throw new Error(
+      'definePlay(name, ...) play names cannot contain "/". Slash is reserved for qualified references like "prebuilt/example" or "self/example".',
+    );
+  }
+  const normalizedName = name
+    .trim()
+    .replace(/[^a-z0-9]+/gi, '_')
+    .replace(/_+/g, '_')
+    .replace(/^_+|_+$/g, '')
+    .toLowerCase();
+  if (!normalizedName) {
+    throw new Error(
+      'definePlay(name, ...) requires a play name with at least one letter or number. Use only letters, numbers, underscores, or hyphens.',
+    );
+  }
+  if (normalizedName.length > 63) {
+    throw new Error(
+      `definePlay("${name}", ...) is too long after normalization (${normalizedName.length}/63). Shorten the play name to 63 characters or fewer. Normalized value: "${normalizedName}".`,
+    );
+  }
+
+  const metadata: PlayMetadata = {
+    name,
+    ...(config.bindings ? { bindings: config.bindings } : {}),
+    ...(config.inputSchema ? { inputSchema: config.inputSchema } : {}),
+    ...(config.billing ? { billing: config.billing } : {}),
+  };
+  const play = fn as DefinedPlay<TInput, TOutput>;
+
+  Object.defineProperty(play, PLAY_METADATA_SYMBOL, {
+    value: metadata,
+    enumerable: false,
+    configurable: false,
+    writable: false,
+  });
+  Object.defineProperty(play, 'playName', {
+    value: name,
+    enumerable: true,
+    configurable: false,
+    writable: false,
+  });
+  Object.defineProperty(play, 'bindings', {
+    value: config.bindings,
+    enumerable: true,
+    configurable: false,
+    writable: false,
+  });
+
+  const handle = createUnavailableNamedPlayHandle<TInput, TOutput>(name);
+  for (const key of [
+    'name',
+    'get',
+    'runs',
+    'versions',
+    'publish',
+    'clearHistory',
+    'run',
+    'runSync',
+  ] as const) {
+    Object.defineProperty(play, key, {
+      value: handle[key],
+      enumerable: false,
+      configurable: false,
+      writable: false,
+    });
+  }
+
+  return play;
+}
+
+export const defineWorkflow = definePlay;
+
+export function getDefinedPlayMetadata(value: unknown): PlayMetadata | null {
+  if (typeof value !== 'function') {
+    return null;
+  }
+  const metadata = (value as unknown as Record<PropertyKey, unknown>)[
+    PLAY_METADATA_SYMBOL
+  ];
+  if (!metadata || typeof metadata !== 'object') {
+    return null;
+  }
+  const candidate = metadata as PlayMetadata;
+  if (!candidate.name || typeof candidate.name !== 'string') {
+    return null;
+  }
+  return candidate;
+}

package/dist/repo/shared_libs/observability/node-tracing.ts

@@ -0,0 +1,129 @@
+import { mkdir, appendFile } from 'node:fs/promises';
+import { dirname } from 'node:path';
+import type { NodeSDK } from '@opentelemetry/sdk-node';
+import type {
+  ReadableSpan,
+  SpanExporter,
+} from '@opentelemetry/sdk-trace-base';
+import type { ExportResult } from '@opentelemetry/core';
+
+const EXPORT_RESULT_SUCCESS = 0;
+const EXPORT_RESULT_FAILED = 1;
+
+declare global {
+  var __deeplineTracingInitPromise: Promise<boolean> | undefined;
+  var __deeplineTracingSdk: NodeSDK | undefined;
+  var __deeplineTracingShutdownPromise: Promise<void> | undefined;
+}
+
+class JsonlFileSpanExporter implements SpanExporter {
+  constructor(private readonly filePath: string) {}
+
+  async export(
+    spans: ReadableSpan[],
+    resultCallback: (result: ExportResult) => void,
+  ): Promise<void> {
+    try {
+      await mkdir(dirname(this.filePath), { recursive: true });
+      const lines = spans
+        .map((span) =>
+          JSON.stringify({
+            traceId: span.spanContext().traceId,
+            spanId: span.spanContext().spanId,
+            parentSpanId: span.parentSpanContext?.spanId ?? null,
+            name: span.name,
+            kind: span.kind,
+            startTime: span.startTime,
+            endTime: span.endTime,
+            attributes: span.attributes,
+            status: span.status,
+            resource: span.resource.attributes,
+          }),
+        )
+        .join('\n');
+      if (lines.length > 0) {
+        await appendFile(this.filePath, `${lines}\n`, 'utf-8');
+      }
+      resultCallback({ code: EXPORT_RESULT_SUCCESS });
+    } catch (error) {
+      resultCallback({
+        code: EXPORT_RESULT_FAILED,
+        error: error instanceof Error ? error : new Error(String(error)),
+      });
+    }
+  }
+
+  async shutdown(): Promise<void> {}
+  async forceFlush(): Promise<void> {}
+}
+
+async function resolveTraceExporters(): Promise<SpanExporter[]> {
+  const exporters: SpanExporter[] = [];
+  const otlpEndpoint =
+    process.env.OTEL_EXPORTER_OTLP_TRACES_ENDPOINT?.trim() ||
+    process.env.OTEL_EXPORTER_OTLP_ENDPOINT?.trim() ||
+    '';
+  if (otlpEndpoint) {
+    const { OTLPTraceExporter } = await import(
+      '@opentelemetry/exporter-trace-otlp-http'
+    );
+    exporters.push(new OTLPTraceExporter());
+  }
+
+  const traceFilePath = process.env.DEEPLINE_TRACE_FILE?.trim() || '';
+  if (traceFilePath) {
+    exporters.push(new JsonlFileSpanExporter(traceFilePath));
+  }
+
+  return exporters;
+}
+
+async function startNodeTracing(serviceName: string): Promise<boolean> {
+  const exporters = await resolveTraceExporters();
+  if (exporters.length === 0) {
+    return false;
+  }
+
+  if (!process.env.OTEL_SERVICE_NAME) {
+    process.env.OTEL_SERVICE_NAME = serviceName;
+  }
+
+  const [{ NodeSDK }, { BatchSpanProcessor }] = await Promise.all([
+    import('@opentelemetry/sdk-node'),
+    import('@opentelemetry/sdk-trace-base'),
+  ]);
+
+  const sdk = new NodeSDK({
+    instrumentations: [],
+    spanProcessors: exporters.map(
+      (exporter) => new BatchSpanProcessor(exporter),
+    ),
+  });
+  await sdk.start();
+  globalThis.__deeplineTracingSdk = sdk;
+  return true;
+}
+
+export async function ensureNodeTracing(serviceName: string): Promise<boolean> {
+  globalThis.__deeplineTracingInitPromise ??= startNodeTracing(serviceName);
+  return await globalThis.__deeplineTracingInitPromise;
+}
+
+export async function shutdownNodeTracing(): Promise<void> {
+  const initialized = await (globalThis.__deeplineTracingInitPromise ??
+    Promise.resolve(false));
+  if (!initialized) {
+    return;
+  }
+
+  const sdk = globalThis.__deeplineTracingSdk;
+  if (!sdk) {
+    return;
+  }
+
+  globalThis.__deeplineTracingShutdownPromise ??= sdk.shutdown().finally(() => {
+    globalThis.__deeplineTracingSdk = undefined;
+    globalThis.__deeplineTracingInitPromise = undefined;
+  });
+  await globalThis.__deeplineTracingShutdownPromise;
+}

package/dist/repo/shared_libs/observability/tracing.ts

@@ -0,0 +1,98 @@
+import {
+  SpanKind,
+  SpanStatusCode,
+  trace,
+  type Attributes,
+  type Span,
+} from '@opentelemetry/api';
+
+type PrimitiveAttribute =
+  | string
+  | number
+  | boolean
+  | null
+  | undefined;
+
+type TraceAttributes = Record<string, PrimitiveAttribute>;
+
+function normalizeAttributes(
+  attributes: TraceAttributes | undefined,
+): Attributes | undefined {
+  if (!attributes) {
+    return undefined;
+  }
+
+  const normalized: Attributes = {};
+  for (const [key, value] of Object.entries(attributes)) {
+    if (value === undefined || value === null) {
+      continue;
+    }
+    if (
+      typeof value === 'string' ||
+      typeof value === 'number' ||
+      typeof value === 'boolean'
+    ) {
+      normalized[key] = value;
+    }
+  }
+  return Object.keys(normalized).length > 0 ? normalized : undefined;
+}
+
+function recordError(span: Span, error: unknown): void {
+  if (error instanceof Error) {
+    span.recordException(error);
+    span.setStatus({
+      code: SpanStatusCode.ERROR,
+      message: error.message,
+    });
+    return;
+  }
+
+  const message = String(error);
+  span.recordException({ name: 'Error', message });
+  span.setStatus({
+    code: SpanStatusCode.ERROR,
+    message,
+  });
+}
+
+export async function withActiveSpan<T>(
+  name: string,
+  options: {
+    tracer?: string;
+    kind?: SpanKind;
+    attributes?: TraceAttributes;
+  },
+  fn: (span: Span) => Promise<T> | T,
+): Promise<T> {
+  const tracer = trace.getTracer(options.tracer ?? 'deepline');
+  return await tracer.startActiveSpan(
+    name,
+    {
+      kind: options.kind,
+      attributes: normalizeAttributes(options.attributes),
+    },
+    async (span) => {
+      try {
+        const result = await fn(span);
+        span.setStatus({ code: SpanStatusCode.OK });
+        return result;
+      } catch (error) {
+        recordError(span, error);
+        throw error;
+      } finally {
+        span.end();
+      }
+    },
+  );
+}
+
+export function setSpanAttributes(
+  span: Span,
+  attributes: TraceAttributes,
+): void {
+  const normalized = normalizeAttributes(attributes);
+  if (normalized) {
+    span.setAttributes(normalized);
+  }
+}

package/dist/repo/shared_libs/play-runtime/backend.ts

@@ -0,0 +1,139 @@
+export const PLAY_RUNTIME_BACKENDS = {
+  localProcess: 'local_process',
+  daytona: 'daytona',
+  // Artifact/runtime contract for Cloudflare Dynamic Workers. This is no
+  // longer a standalone runner backend; use profile=workers_edge so the
+  // cf-workflows scheduler owns loading and execution.
+  cloudflareWorkers: 'cloudflare_workers',
+} as const;
+
+export type PlayRuntimeBackendId =
+  (typeof PLAY_RUNTIME_BACKENDS)[keyof typeof PLAY_RUNTIME_BACKENDS];
+
+/**
+ * The runtime shape of a built play artifact. Different runner backends need
+ * different bundle outputs:
+ *   - cjs_node20: Daytona + local-process (full Node.js sandbox).
+ *   - esm_workers: Cloudflare Workers (V8 isolate, no `fs`/`child_process`).
+ *
+ * The CLI selects which kind to build based on the target backend; the worker
+ * validates the kind matches the backend it's about to dispatch to.
+ */
+export const PLAY_ARTIFACT_KINDS = {
+  cjsNode20: 'cjs_node20',
+  esmWorkers: 'esm_workers',
+} as const;
+
+export type PlayArtifactKind =
+  (typeof PLAY_ARTIFACT_KINDS)[keyof typeof PLAY_ARTIFACT_KINDS];
+
+export type PlayBackendDescriptor = {
+  id: PlayRuntimeBackendId;
+  /** What artifact kind this backend's runner consumes. */
+  artifactKind: PlayArtifactKind;
+  /** Human label for logs. */
+  label: string;
+};
+
+export const PLAY_BACKEND_DESCRIPTORS: Record<
+  PlayRuntimeBackendId,
+  PlayBackendDescriptor
+> = {
+  [PLAY_RUNTIME_BACKENDS.localProcess]: {
+    id: PLAY_RUNTIME_BACKENDS.localProcess,
+    artifactKind: PLAY_ARTIFACT_KINDS.cjsNode20,
+    label: 'Local node subprocess',
+  },
+  [PLAY_RUNTIME_BACKENDS.daytona]: {
+    id: PLAY_RUNTIME_BACKENDS.daytona,
+    artifactKind: PLAY_ARTIFACT_KINDS.cjsNode20,
+    label: 'Daytona sandbox',
+  },
+  [PLAY_RUNTIME_BACKENDS.cloudflareWorkers]: {
+    id: PLAY_RUNTIME_BACKENDS.cloudflareWorkers,
+    artifactKind: PLAY_ARTIFACT_KINDS.esmWorkers,
+    label: 'Cloudflare Dynamic Workers',
+  },
+};
+
+export function describePlayBackend(
+  id: PlayRuntimeBackendId,
+): PlayBackendDescriptor {
+  return PLAY_BACKEND_DESCRIPTORS[id];
+}
+
+export function artifactKindForBackend(
+  id: PlayRuntimeBackendId,
+): PlayArtifactKind {
+  return PLAY_BACKEND_DESCRIPTORS[id].artifactKind;
+}
+
+export function normalizePlayRuntimeBackend(
+  value?: string | null,
+): PlayRuntimeBackendId {
+  const normalized = value?.trim().toLowerCase();
+  if (!normalized) {
+    return defaultPlayRuntimeBackend();
+  }
+
+  if (normalized === PLAY_RUNTIME_BACKENDS.daytona) {
+    return PLAY_RUNTIME_BACKENDS.daytona;
+  }
+
+  if (normalized === PLAY_RUNTIME_BACKENDS.localProcess) {
+    return PLAY_RUNTIME_BACKENDS.localProcess;
+  }
+
+  if (normalized === PLAY_RUNTIME_BACKENDS.cloudflareWorkers) {
+    return PLAY_RUNTIME_BACKENDS.cloudflareWorkers;
+  }
+
+  throw new Error(
+    `Unsupported play runtime backend "${normalized}". Expected one of: ${Object.values(
+      PLAY_RUNTIME_BACKENDS,
+    ).join(', ')}.`,
+  );
+}
+
+export function defaultPlayRuntimeBackend(input?: {
+  deeplineEnv?: string | null;
+  vercelEnv?: string | null;
+  nodeEnv?: string | null;
+  previewPlaysDeployment?: boolean;
+}): PlayRuntimeBackendId {
+  if (input?.previewPlaysDeployment) {
+    return PLAY_RUNTIME_BACKENDS.daytona;
+  }
+
+  const candidates = [
+    input?.deeplineEnv ?? process.env.DEEPLINE_ENV,
+    input?.vercelEnv ?? process.env.VERCEL_ENV,
+    input?.nodeEnv ?? process.env.NODE_ENV,
+  ]
+    .filter(Boolean)
+    .map((value) => String(value).trim().toLowerCase());
+
+  for (const value of candidates) {
+    if (
+      value === 'production' ||
+      value === 'prod' ||
+      value === 'live' ||
+      value === 'preview' ||
+      value === 'staging' ||
+      value === 'stage'
+    ) {
+      return PLAY_RUNTIME_BACKENDS.daytona;
+    }
+  }
+
+  return PLAY_RUNTIME_BACKENDS.localProcess;
+}
+
+export function isPlayRuntimeBackendId(
+  value: unknown,
+): value is PlayRuntimeBackendId {
+  return (
+    typeof value === 'string' &&
+    Object.values(PLAY_RUNTIME_BACKENDS).includes(value as PlayRuntimeBackendId)
+  );
+}