@treeseed/sdk 0.11.0 → 0.12.4

package/dist/scenes/inspect.js

@@ -0,0 +1,64 @@
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { basename, join, resolve } from "node:path";
+import { sceneErrorDiagnostic } from "./diagnostics.js";
+function readJson(path) {
+  return JSON.parse(readFileSync(path, "utf8"));
+}
+function resolveTreeseedSceneRunRoot(projectRoot, run) {
+  const candidate = resolve(projectRoot, run);
+  if (existsSync(join(candidate, "run.json"))) return { runRoot: candidate, diagnostics: [] };
+  const runsRoot = join(projectRoot, ".treeseed", "scenes", "runs");
+  const matches = [];
+  if (existsSync(runsRoot)) {
+    for (const sceneId of readdirSync(runsRoot)) {
+      const sceneRoot = join(runsRoot, sceneId);
+      for (const runDir of readdirSync(sceneRoot)) {
+        const runRoot = join(sceneRoot, runDir);
+        if (basename(runRoot).endsWith(`-${run}`)) matches.push(runRoot);
+        else if (existsSync(join(runRoot, "run.json"))) {
+          try {
+            const report = readJson(join(runRoot, "run.json"));
+            if (report.runId === run) matches.push(runRoot);
+          } catch {
+          }
+        }
+      }
+    }
+  }
+  if (matches.length === 1) return { runRoot: matches[0], diagnostics: [] };
+  if (matches.length > 1) return { runRoot: null, diagnostics: [sceneErrorDiagnostic("scene.run_ambiguous", `Multiple scene runs match "${run}".`, "run")] };
+  return { runRoot: null, diagnostics: [sceneErrorDiagnostic("scene.run_not_found", `Scene run not found: ${run}.`, "run")] };
+}
+function inspectTreeseedSceneRun(input) {
+  const resolved = resolveTreeseedSceneRunRoot(input.projectRoot, input.run);
+  if (!resolved.runRoot) {
+    return { ok: false, runRoot: null, run: null, timeline: [], chapters: [], segments: [], checkpoints: [], selectedStep: null, diagnostics: resolved.diagnostics };
+  }
+  const diagnostics = [...resolved.diagnostics];
+  const runPath = join(resolved.runRoot, "run.json");
+  if (!existsSync(runPath)) {
+    diagnostics.push(sceneErrorDiagnostic("scene.run_not_found", `Run report not found: ${runPath}.`, "run"));
+    return { ok: false, runRoot: resolved.runRoot, run: null, timeline: [], chapters: [], segments: [], checkpoints: [], selectedStep: null, diagnostics };
+  }
+  const run = readJson(runPath);
+  const timeline = existsSync(run.timelinePath ?? "") ? readJson(run.timelinePath) : [];
+  const checkpointsRoot = run.artifacts?.checkpointsRoot;
+  const checkpoints = checkpointsRoot && existsSync(checkpointsRoot) ? readdirSync(checkpointsRoot).filter((entry) => entry.endsWith(".json")).map((entry) => readJson(join(checkpointsRoot, entry))) : run.checkpoints ?? [];
+  const selectedStep = input.stepId ? run.steps.find((step) => step.id === input.stepId) ?? null : null;
+  if (input.stepId && !selectedStep) diagnostics.push(sceneErrorDiagnostic("scene.step_not_found", `Step not found: ${input.stepId}.`, "step"));
+  return {
+    ok: diagnostics.every((entry) => entry.severity !== "error"),
+    runRoot: resolved.runRoot,
+    run,
+    timeline,
+    chapters: run.chapters ?? [],
+    segments: run.segments ?? [],
+    checkpoints,
+    selectedStep,
+    diagnostics
+  };
+}
+export {
+  inspectTreeseedSceneRun,
+  resolveTreeseedSceneRunRoot
+};

package/dist/scenes/loader.d.ts

@@ -0,0 +1,3 @@
+import type { LoadedTreeseedSceneDocument } from './types.js';
+export declare function resolveTreeseedScenePath(projectRoot: string, sceneNameOrPath: string): string;
+export declare function loadTreeseedSceneDocument(projectRoot: string, sceneNameOrPath: string): LoadedTreeseedSceneDocument;

package/dist/scenes/loader.js

@@ -0,0 +1,38 @@
+import { existsSync, readFileSync } from "node:fs";
+import { isAbsolute, resolve } from "node:path";
+import { parseDocument } from "yaml";
+import { sceneErrorDiagnostic } from "./diagnostics.js";
+const FILESYSTEM_SAFE_SCENE_ID = /^[a-z0-9][a-z0-9._-]*$/u;
+function resolveTreeseedScenePath(projectRoot, sceneNameOrPath) {
+  const value = sceneNameOrPath.trim();
+  if (/\.(?:ya?ml)$/iu.test(value)) {
+    return isAbsolute(value) ? value : resolve(projectRoot, value);
+  }
+  return resolve(projectRoot, "scenes", `${value}.yaml`);
+}
+function loadTreeseedSceneDocument(projectRoot, sceneNameOrPath) {
+  const diagnostics = [];
+  const trimmed = sceneNameOrPath.trim();
+  const path = resolveTreeseedScenePath(projectRoot, trimmed);
+  if (!/\.(?:ya?ml)$/iu.test(trimmed) && !FILESYSTEM_SAFE_SCENE_ID.test(trimmed)) {
+    diagnostics.push(sceneErrorDiagnostic("scene.invalid_name", `Scene name must be a simple file-safe identifier: ${sceneNameOrPath}.`, "scene"));
+    return { path, value: null, diagnostics };
+  }
+  if (!existsSync(path)) {
+    diagnostics.push(sceneErrorDiagnostic("scene.not_found", `Scene manifest not found at ${path}.`, "manifest"));
+    return { path, value: null, diagnostics };
+  }
+  const source = readFileSync(path, "utf8");
+  const document = parseDocument(source, { prettyErrors: false });
+  for (const parseError of document.errors) {
+    diagnostics.push(sceneErrorDiagnostic("scene.yaml_parse_error", parseError.message, "manifest"));
+  }
+  if (diagnostics.length > 0) {
+    return { path, value: null, diagnostics };
+  }
+  return { path, value: document.toJSON(), diagnostics };
+}
+export {
+  loadTreeseedSceneDocument,
+  resolveTreeseedScenePath
+};

package/dist/scenes/logs.d.ts

@@ -0,0 +1,2 @@
+import type { TreeseedSceneLogCollectOptions, TreeseedSceneLogReport } from './types.js';
+export declare function collectTreeseedSceneLogs(input: TreeseedSceneLogCollectOptions): TreeseedSceneLogReport;

package/dist/scenes/logs.js

@@ -0,0 +1,47 @@
+import { existsSync, writeFileSync } from "node:fs";
+import { readTreeseedDevLogs } from "../local-dev/managed-dev.js";
+import { sceneWarningDiagnostic } from "./diagnostics.js";
+const MAX_BYTES = 1024 * 1024;
+const MAX_LINES = 1e3;
+function tail(content) {
+  const bytes = Buffer.from(content, "utf8");
+  const clipped = bytes.length > MAX_BYTES ? bytes.subarray(bytes.length - MAX_BYTES).toString("utf8") : content;
+  const lines = clipped.split(/\r?\n/u);
+  return lines.length > MAX_LINES ? lines.slice(lines.length - MAX_LINES).join("\n") : clipped;
+}
+function writeIfContent(path, content) {
+  writeFileSync(path, content.endsWith("\n") ? content : `${content}
+`, "utf8");
+  return path;
+}
+function collectTreeseedSceneLogs(input) {
+  const diagnostics = [];
+  const logs = {
+    dev: input.artifacts.devLogPath ?? null,
+    api: input.artifacts.apiLogPath ?? null,
+    operationsRunner: input.artifacts.operationsRunnerLogPath ?? null
+  };
+  try {
+    const devLogs = readTreeseedDevLogs({ cwd: input.projectRoot, surfaces: "web,api,operations-runner" }).logs;
+    const byId = new Map(devLogs.map((entry) => [entry.id, entry]));
+    const web = byId.get("web");
+    const api = byId.get("api");
+    const runner = byId.get("operations-runner");
+    if (web && input.artifacts.devLogPath) writeIfContent(input.artifacts.devLogPath, tail(web.content));
+    if (api && input.artifacts.apiLogPath) writeIfContent(input.artifacts.apiLogPath, tail(api.content));
+    if (runner && input.artifacts.operationsRunnerLogPath) writeIfContent(input.artifacts.operationsRunnerLogPath, tail(runner.content));
+    for (const [id, entry] of [["web", web], ["api", api], ["operations-runner", runner]]) {
+      if (!entry?.content) diagnostics.push(sceneWarningDiagnostic("scene.logs_unavailable", `No managed dev log content was available for ${id}.`, "logs"));
+    }
+  } catch (error) {
+    diagnostics.push(sceneWarningDiagnostic("scene.log_collect_failed", error instanceof Error ? error.message : String(error ?? "Log collection failed."), "logs"));
+  }
+  for (const [key, path] of Object.entries(logs)) {
+    if (path && !existsSync(path)) writeIfContent(path, "");
+    logs[key] = path;
+  }
+  return { ok: true, logs, diagnostics };
+}
+export {
+  collectTreeseedSceneLogs
+};

package/dist/scenes/operations.d.ts

@@ -0,0 +1,3 @@
+import type { TreeseedSceneOperationWaitOptions, TreeseedSceneOperationWaitReport } from './types.js';
+export declare function waitForTreeseedSceneOperation(input: TreeseedSceneOperationWaitOptions): Promise<TreeseedSceneOperationWaitReport>;
+export declare function extractTreeseedSceneOperationIds(value: unknown): string[];

package/dist/scenes/operations.js

@@ -0,0 +1,128 @@
+import { sceneErrorDiagnostic } from "./diagnostics.js";
+const FAILURE_STATUSES = /* @__PURE__ */ new Set(["failed", "cancelled", "timed_out", "error"]);
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function valueAt(record, path) {
+  let current = record;
+  for (const key of path) {
+    if (!current || typeof current !== "object" || Array.isArray(current)) return void 0;
+    current = current[key];
+  }
+  return current;
+}
+function operationStatus(operation) {
+  return String(operation.status ?? valueAt(operation, ["operation", "status"]) ?? valueAt(operation, ["payload", "operation", "status"]) ?? "").trim();
+}
+function operationKind(operation) {
+  return String(operation.kind ?? operation.operation ?? valueAt(operation, ["operation", "kind"]) ?? valueAt(operation, ["payload", "operation", "kind"]) ?? "").trim() || null;
+}
+function operationIdFrom(input) {
+  if (input.spec.id) return input.spec.id;
+  if (input.spec.source === "explicit") return null;
+  return input.linkedOperationIds?.at(-1) ?? null;
+}
+async function defaultFetchOperation(input, operationId) {
+  if (input.fetchOperation) return input.fetchOperation(operationId);
+  const serviceId = process.env.TREESEED_ACCEPTANCE_SERVICE_ID ?? process.env.TREESEED_WEB_SERVICE_ID ?? process.env.TREESEED_API_WEB_SERVICE_ID ?? "web";
+  const serviceSecret = process.env.TREESEED_ACCEPTANCE_SERVICE_SECRET ?? process.env.TREESEED_WEB_SERVICE_SECRET ?? process.env.TREESEED_API_WEB_SERVICE_SECRET;
+  if (!serviceSecret) throw sceneErrorDiagnostic("scene.operation_unavailable", "Missing service credentials for platform operation polling.", "workflow.operation");
+  const response = await fetch(`${input.baseUrl.replace(/\/+$/u, "")}/v1/platform/operations/${encodeURIComponent(operationId)}`, {
+    headers: {
+      accept: "application/json",
+      "x-treeseed-service-id": serviceId,
+      "x-treeseed-service-secret": serviceSecret
+    }
+  });
+  const payload = await response.json().catch(() => ({}));
+  if (!response.ok) throw new Error(`Operation polling failed with HTTP ${response.status}.`);
+  return payload;
+}
+async function defaultFetchEvents(input, operationId) {
+  if (input.fetchEvents) return input.fetchEvents(operationId);
+  return [];
+}
+async function waitForTreeseedSceneOperation(input) {
+  const started = Date.now();
+  const operationId = operationIdFrom(input);
+  const acceptedStatuses = input.spec.status ?? [];
+  if (!operationId) {
+    return {
+      ok: false,
+      operationId: null,
+      kind: input.spec.kind ?? null,
+      finalStatus: null,
+      acceptedStatuses,
+      events: [],
+      durationMs: 0,
+      diagnostics: [sceneErrorDiagnostic("scene.operation_id_unresolved", "No operation id was provided or observed for operation polling.", "workflow.operation")]
+    };
+  }
+  const timeoutMs = Math.max(1e3, Math.floor((input.spec.timeoutSeconds ?? 300) * 1e3));
+  const pollMs = Math.max(250, Math.floor((input.spec.pollIntervalSeconds ?? 2) * 1e3));
+  const wait = input.sleep ?? sleep;
+  let latestStatus = null;
+  let latestKind = input.spec.kind ?? null;
+  let events = [];
+  while (Date.now() - started <= timeoutMs) {
+    try {
+      const payload = await defaultFetchOperation(input, operationId);
+      const operation = payload.operation ?? payload.payload?.operation ?? payload;
+      latestStatus = operationStatus(operation);
+      latestKind = operationKind(operation) ?? latestKind;
+      events = await defaultFetchEvents(input, operationId);
+      const tick = {
+        ok: acceptedStatuses.includes(latestStatus),
+        operationId,
+        kind: latestKind,
+        finalStatus: latestStatus,
+        acceptedStatuses,
+        events,
+        durationMs: Date.now() - started,
+        diagnostics: []
+      };
+      await input.onUpdate?.(tick);
+      if (acceptedStatuses.includes(latestStatus)) return tick;
+      if (FAILURE_STATUSES.has(latestStatus)) {
+        return { ...tick, ok: false, diagnostics: [sceneErrorDiagnostic("scene.operation_failed", `Operation ${operationId} ended with status ${latestStatus}.`, "workflow.operation")] };
+      }
+    } catch (error) {
+      const diagnostic = error && typeof error === "object" && "code" in error ? error : sceneErrorDiagnostic("scene.operation_unavailable", error instanceof Error ? error.message : String(error ?? "Operation polling failed."), "workflow.operation");
+      return {
+        ok: false,
+        operationId,
+        kind: latestKind,
+        finalStatus: latestStatus,
+        acceptedStatuses,
+        events,
+        durationMs: Date.now() - started,
+        diagnostics: [diagnostic]
+      };
+    }
+    await wait(pollMs);
+  }
+  return {
+    ok: false,
+    operationId,
+    kind: latestKind,
+    finalStatus: latestStatus,
+    acceptedStatuses,
+    events,
+    durationMs: Date.now() - started,
+    diagnostics: [sceneErrorDiagnostic("scene.operation_poll_timeout", `Operation ${operationId} did not reach an accepted status within ${timeoutMs}ms.`, "workflow.operation")]
+  };
+}
+function extractTreeseedSceneOperationIds(value) {
+  if (!value || typeof value !== "object") return [];
+  const record = value;
+  const candidates = [
+    record.operationId,
+    valueAt(record, ["operation", "id"]),
+    valueAt(record, ["payload", "operation", "id"])
+  ];
+  return candidates.filter((entry) => typeof entry === "string" && entry.trim().length > 0);
+}
+export {
+  extractTreeseedSceneOperationIds,
+  waitForTreeseedSceneOperation
+};

package/dist/scenes/phase0.d.ts

@@ -0,0 +1,9 @@
+import type { TreeseedSceneArtifactPathPlan, TreeseedScenePhase0Report } from './types.js';
+export declare const TREESEED_SCENE_PLATFORM_NAME: "central TreeSeed acceptance test harness and demo / educational video generator";
+export declare function createTreeseedScenePhase0Report(): TreeseedScenePhase0Report;
+export declare function planTreeseedSceneArtifactPaths(input: {
+    workspaceRoot: string;
+    sceneId: string;
+    runId?: string;
+    timestamp?: string;
+}): TreeseedSceneArtifactPathPlan;