@treeseed/sdk 0.11.0 → 0.12.5

package/dist/scenes/training-transcript.js

@@ -0,0 +1,204 @@
+import { stepOffset } from "./training-captions.js";
+const BUILT_IN_GLOSSARY = {
+  reconciliation: "Exact-state comparison and repair from declared Treeseed desired state to observed live state.",
+  operation: "A tracked Treeseed platform task with lifecycle status, events, and durable evidence.",
+  checkpoint: "A durable scene marker that records completed workflow progress and possible resume position.",
+  segment: "A bounded section of a long scene used for evidence organization and future partial rendering.",
+  "managed dev": "The worktree-scoped local Treeseed development runtime supervised by SDK managed-dev services.",
+  seed: "A deterministic Treeseed data/configuration input planned or applied through canonical SDK seed services.",
+  auth: "A resolved non-interactive Treeseed market profile and session context.",
+  provider: "A host, service, or external platform managed only through canonical Treeseed reconciliation paths.",
+  Remotion: "The Phase 6 adapter-hosted renderer used to turn scene evidence into video outputs.",
+  Playwright: "The browser automation engine used by scene runs to collect executable acceptance evidence."
+};
+function text(value) {
+  return (value ?? "").replace(/\s+/gu, " ").trim();
+}
+function chapterForStep(run, stepId) {
+  return (run.chapters ?? []).find((chapter) => chapter.stepIds.includes(stepId)) ?? null;
+}
+function actionSummary(actionKind) {
+  if (actionKind === "goto") return "navigates the browser to the expected screen";
+  if (actionKind === "click") return "performs the requested user click";
+  if (actionKind === "fill") return "fills a browser field";
+  if (actionKind === "keyboard") return "sends a keyboard command";
+  if (actionKind === "waitForOperation") return "waits for a Treeseed platform operation to reach an accepted state";
+  if (actionKind === "pause") return "pauses the demo workflow at an intentional control point";
+  if (actionKind === "mailpitConfirmLatest") return "opens the latest local Mailpit confirmation link in the browser";
+  return `runs ${actionKind}`;
+}
+function buildTreeseedSceneTranscriptEntries(input) {
+  const entries = [{
+    id: "scene",
+    timestampMs: 0,
+    type: "scene",
+    title: input.scene.title,
+    text: text(input.scene.description) || `Scene ${input.scene.id} completed with status ${input.run.workflowStatus}.`
+  }];
+  if (input.scene.audience.length > 0) {
+    entries.push({
+      id: "scene-audience",
+      timestampMs: 0,
+      type: "scene",
+      title: "Audience",
+      text: input.scene.audience.join(", ")
+    });
+  }
+  for (const chapter of input.run.chapters ?? []) {
+    const firstStep = chapter.stepIds[0];
+    entries.push({
+      id: `chapter-${chapter.id}`,
+      timestampMs: firstStep ? stepOffset({ stepId: firstStep, timeline: input.timeline }) : 0,
+      type: "chapter",
+      title: chapter.title,
+      text: `Chapter ${chapter.title} covers ${chapter.stepIds.length} scene step${chapter.stepIds.length === 1 ? "" : "s"}.`,
+      chapterId: chapter.id
+    });
+  }
+  input.run.steps.forEach((step, index) => {
+    const chapter = chapterForStep(input.run, step.id);
+    entries.push({
+      id: `step-${step.id}`,
+      timestampMs: stepOffset({ stepId: step.id, timeline: input.timeline, fallbackMs: index * 4e3 }),
+      type: "step",
+      title: step.title,
+      text: `This step ${actionSummary(step.actionKind)} and records ${step.assertionResults.length} assertion result${step.assertionResults.length === 1 ? "" : "s"}.`,
+      stepId: step.id,
+      chapterId: chapter?.id ?? null
+    });
+  });
+  for (const overlay of input.scene.overlays ?? []) {
+    if (!overlay.text) continue;
+    const chapter = chapterForStep(input.run, overlay.at);
+    entries.push({
+      id: `overlay-${overlay.id}`,
+      timestampMs: stepOffset({ stepId: overlay.at, timeline: input.timeline }),
+      type: "overlay",
+      title: overlay.id,
+      text: overlay.text,
+      stepId: overlay.at,
+      chapterId: chapter?.id ?? null
+    });
+  }
+  for (const diagram of input.scene.diagrams ?? []) {
+    const chapter = chapterForStep(input.run, diagram.at);
+    const title = typeof diagram.props?.title === "string" ? diagram.props.title : diagram.id;
+    entries.push({
+      id: `diagram-${diagram.id}`,
+      timestampMs: stepOffset({ stepId: diagram.at, timeline: input.timeline }),
+      type: "diagram",
+      title,
+      text: `${diagram.component} renders as ${diagram.placement} evidence for step ${diagram.at}.`,
+      stepId: diagram.at,
+      chapterId: chapter?.id ?? null
+    });
+  }
+  const failedStep = input.run.failedStep ? input.run.steps.find((step) => step.id === input.run.failedStep) : null;
+  if (failedStep?.error && input.scene.training.narration.includeDiagnostics) {
+    const chapter = chapterForStep(input.run, failedStep.id);
+    entries.push({
+      id: `diagnostic-${failedStep.id}`,
+      timestampMs: stepOffset({ stepId: failedStep.id, timeline: input.timeline }),
+      type: "diagnostic",
+      title: failedStep.error.code,
+      text: failedStep.error.message,
+      stepId: failedStep.id,
+      chapterId: chapter?.id ?? null
+    });
+  }
+  return entries.sort((a, b) => a.timestampMs - b.timestampMs || a.id.localeCompare(b.id));
+}
+function scriptFor(entry, style) {
+  if (style === "concise") return `${entry.title}: ${entry.text}`;
+  if (style === "operator") return `Operator note. ${entry.title}. ${entry.text}`;
+  if (entry.type === "step") return `${entry.title}. This proves the workflow can ${entry.text.replace(/^This step /u, "")}`;
+  if (entry.type === "diagnostic") return `Review ${entry.title}. The recorded diagnostic is: ${entry.text}`;
+  return `${entry.title}. ${entry.text}`;
+}
+function buildTreeseedSceneNarrationEntries(input) {
+  return input.transcript.map((entry, index) => ({
+    id: `narration-${entry.id}`,
+    order: index + 1,
+    ...entry.chapterId ? { chapterId: entry.chapterId } : {},
+    ...entry.stepId ? { stepId: entry.stepId } : {},
+    title: entry.title,
+    script: scriptFor(entry, input.style),
+    source: entry.type
+  }));
+}
+function buildTreeseedSceneGlossary(input) {
+  const explicit = /* @__PURE__ */ new Map();
+  for (const term of input.scene.training.glossary.terms) explicit.set(term.term.toLowerCase(), term);
+  const haystack = input.transcript.map((entry) => `${entry.title} ${entry.text}`).join(" ").toLowerCase();
+  const terms = /* @__PURE__ */ new Map();
+  for (const [term, definition] of Object.entries(BUILT_IN_GLOSSARY)) {
+    if (haystack.includes(term.toLowerCase())) terms.set(term.toLowerCase(), { term, definition, tags: ["built-in"] });
+  }
+  for (const term of input.scene.diagrams.map((diagram) => diagram.component)) {
+    terms.set(term.toLowerCase(), { term, definition: "A typed Treeseed scene diagram component rendered from validated manifest props.", tags: ["diagram"] });
+  }
+  for (const [key, term] of explicit) terms.set(key, term);
+  return [...terms.values()].sort((a, b) => a.term.localeCompare(b.term));
+}
+function buildTreeseedSceneChapterClips(input) {
+  const chapters = input.run.chapters.length > 0 ? input.run.chapters : [{ id: "default", title: input.scene.title, stepIds: input.run.steps.map((step) => step.id), segmentIds: input.run.segments.map((segment) => segment.id) }];
+  return chapters.map((chapter) => {
+    const starts = chapter.stepIds.map((stepId) => stepOffset({ stepId, timeline: input.timeline }));
+    const ends = chapter.stepIds.map((stepId) => stepOffset({ stepId, timeline: input.timeline, prefer: "end", fallbackMs: stepOffset({ stepId, timeline: input.timeline }) + 4e3 }));
+    const startOffsetMs = Math.min(...starts, 0);
+    const endOffsetMs = Math.max(...ends, startOffsetMs + 4e3);
+    const safeName = `${input.scene.id}-${chapter.id}`.toLowerCase().replace(/[^a-z0-9._-]+/gu, "-");
+    return {
+      id: `${chapter.id}-clip`,
+      chapterId: chapter.id,
+      title: chapter.title,
+      startOffsetMs,
+      endOffsetMs,
+      durationMs: Math.max(0, endOffsetMs - startOffsetMs),
+      stepIds: chapter.stepIds,
+      segmentIds: chapter.segmentIds,
+      suggestedOutputName: `${safeName}.mp4`
+    };
+  });
+}
+function formatTreeseedSceneTranscriptMarkdown(entries) {
+  const scene = entries.find((entry) => entry.type === "scene");
+  const lines = [`# ${scene?.title ?? "Treeseed Scene Transcript"}`, ""];
+  for (const entry of entries) {
+    if (entry.id === "scene") {
+      lines.push(entry.text, "");
+    } else if (entry.type === "chapter") {
+      lines.push(`## Chapter: ${entry.title}`, "", entry.text, "");
+    } else {
+      const label = entry.type.charAt(0).toUpperCase() + entry.type.slice(1);
+      lines.push(`### ${label}: ${entry.title}`, "", entry.text, "");
+    }
+  }
+  return `${lines.join("\n").trimEnd()}
+`;
+}
+function formatTreeseedSceneNarrationMarkdown(entries) {
+  const lines = ["# Treeseed Scene Narration Script", ""];
+  for (const entry of entries) {
+    lines.push(`## ${entry.order}. ${entry.title}`, "", entry.script, "");
+  }
+  return `${lines.join("\n").trimEnd()}
+`;
+}
+function formatTreeseedSceneGlossaryMarkdown(terms) {
+  const lines = ["# Treeseed Scene Glossary", ""];
+  for (const term of terms) {
+    lines.push(`## ${term.term}`, "", term.definition ?? "No definition provided.", "");
+  }
+  return `${lines.join("\n").trimEnd()}
+`;
+}
+export {
+  buildTreeseedSceneChapterClips,
+  buildTreeseedSceneGlossary,
+  buildTreeseedSceneNarrationEntries,
+  buildTreeseedSceneTranscriptEntries,
+  formatTreeseedSceneGlossaryMarkdown,
+  formatTreeseedSceneNarrationMarkdown,
+  formatTreeseedSceneTranscriptMarkdown
+};

package/dist/scenes/training.d.ts

@@ -0,0 +1,10 @@
+import { formatTreeseedSceneCaptionsSrt, formatTreeseedSceneCaptionsVtt } from './training-captions.js';
+import { formatTreeseedSceneNarrationMarkdown, formatTreeseedSceneTranscriptMarkdown } from './training-transcript.js';
+import type { TreeseedSceneManifest, TreeseedSceneRunReport, TreeseedSceneTimelineEvent, TreeseedSceneTrainingOutputOptions, TreeseedSceneTrainingOutputReport, TreeseedSceneTrainingOutputs } from './types.js';
+export declare function buildTreeseedSceneTrainingOutputs(input: {
+    scene: TreeseedSceneManifest;
+    run: TreeseedSceneRunReport;
+    timeline: TreeseedSceneTimelineEvent[];
+}): TreeseedSceneTrainingOutputs;
+export declare function generateTreeseedSceneTrainingOutputs(input: TreeseedSceneTrainingOutputOptions): TreeseedSceneTrainingOutputReport;
+export { formatTreeseedSceneCaptionsSrt, formatTreeseedSceneCaptionsVtt, formatTreeseedSceneNarrationMarkdown, formatTreeseedSceneTranscriptMarkdown, };

package/dist/scenes/training.js

@@ -0,0 +1,134 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { sceneErrorDiagnostic } from "./diagnostics.js";
+import { resolveTreeseedSceneRunRoot } from "./inspect.js";
+import { validateTreeseedScene } from "./planner.js";
+import { defaultTreeseedSceneTrainingConfig } from "./schema.js";
+import { buildTreeseedSceneCaptionCues, formatTreeseedSceneCaptionsSrt, formatTreeseedSceneCaptionsVtt } from "./training-captions.js";
+import { appendTreeseedSceneTrainingOutputPaths, writeTreeseedSceneTrainingOutputs } from "./training-report.js";
+import {
+  buildTreeseedSceneChapterClips,
+  buildTreeseedSceneGlossary,
+  buildTreeseedSceneNarrationEntries,
+  buildTreeseedSceneTranscriptEntries,
+  formatTreeseedSceneNarrationMarkdown,
+  formatTreeseedSceneTranscriptMarkdown
+} from "./training-transcript.js";
+function readJson(path) {
+  return JSON.parse(readFileSync(path, "utf8"));
+}
+function nowIso() {
+  return (/* @__PURE__ */ new Date()).toISOString();
+}
+function normalizeScene(scene) {
+  return {
+    ...scene,
+    training: scene.training ?? defaultTreeseedSceneTrainingConfig()
+  };
+}
+function applyFormatFilter(scene, formats) {
+  if (!formats || formats.length === 0) return scene;
+  const requested = new Set(formats);
+  return {
+    ...scene,
+    training: {
+      ...scene.training,
+      captions: {
+        ...scene.training.captions,
+        formats: scene.training.captions.formats.filter((format) => requested.has(format))
+      },
+      transcript: {
+        ...scene.training.transcript,
+        formats: scene.training.transcript.formats.filter((format) => requested.has(format))
+      }
+    }
+  };
+}
+function buildTreeseedSceneTrainingOutputs(input) {
+  const scene = normalizeScene(input.scene);
+  const transcript = scene.training.transcript.enabled || scene.training.narration.enabled || scene.training.glossary.enabled ? buildTreeseedSceneTranscriptEntries({ scene, run: input.run, timeline: input.timeline }) : [];
+  const captions = scene.training.captions.enabled ? buildTreeseedSceneCaptionCues({ scene, run: input.run, timeline: input.timeline }) : [];
+  const narration = scene.training.narration.enabled ? buildTreeseedSceneNarrationEntries({ scene, run: input.run, transcript, style: scene.training.narration.style }) : [];
+  const glossary = scene.training.glossary.enabled ? buildTreeseedSceneGlossary({ scene, transcript }) : [];
+  const chapterClips = scene.training.chapterClips.enabled ? buildTreeseedSceneChapterClips({ scene, run: input.run, timeline: input.timeline }) : [];
+  return {
+    schemaVersion: "treeseed.scene.training-output/v1",
+    sceneId: scene.id,
+    runId: input.run.runId,
+    generatedAt: nowIso(),
+    captions,
+    transcript,
+    narration,
+    glossary,
+    chapterClips
+  };
+}
+function failedReport(input) {
+  const blockers = input.blockers ?? input.diagnostics.filter((diagnostic) => diagnostic.severity === "error");
+  return {
+    ok: false,
+    phase: 8,
+    sceneId: null,
+    sourceRunId: null,
+    scenePath: input.scenePath,
+    runRoot: input.runRoot,
+    trainingRoot: input.runRoot ? join(input.runRoot, "training") : null,
+    outputs: null,
+    paths: null,
+    diagnostics: input.diagnostics,
+    warnings: input.warnings ?? input.diagnostics.filter((diagnostic) => diagnostic.severity === "warning"),
+    blockers
+  };
+}
+function generateTreeseedSceneTrainingOutputs(input) {
+  const resolved = resolveTreeseedSceneRunRoot(input.projectRoot, input.from);
+  if (!resolved.runRoot) return failedReport({ scenePath: input.scene, runRoot: null, diagnostics: resolved.diagnostics });
+  const scenePath = join(resolved.runRoot, "scene.normalized.json");
+  const runPath = join(resolved.runRoot, "run.json");
+  const timelinePath = join(resolved.runRoot, "timeline.json");
+  const blockers = [];
+  if (!existsSync(scenePath)) blockers.push(sceneErrorDiagnostic("scene.training_missing_scene", `Normalized scene artifact not found: ${scenePath}.`, "scene"));
+  if (!existsSync(runPath)) blockers.push(sceneErrorDiagnostic("scene.training_missing_run", `Run report artifact not found: ${runPath}.`, "from"));
+  if (!existsSync(timelinePath)) blockers.push(sceneErrorDiagnostic("scene.training_missing_timeline", `Timeline artifact not found: ${timelinePath}.`, "from"));
+  if (blockers.length > 0) return failedReport({ scenePath: input.scene, runRoot: resolved.runRoot, diagnostics: [...resolved.diagnostics, ...blockers], blockers });
+  const sourceScene = normalizeScene(readJson(scenePath));
+  const run = readJson(runPath);
+  const timeline = readJson(timelinePath);
+  const validation = validateTreeseedScene({ projectRoot: input.projectRoot, scene: input.scene });
+  if (!validation.ok) return failedReport({ scenePath: validation.scenePath, runRoot: resolved.runRoot, diagnostics: validation.diagnostics });
+  if (validation.scene?.id !== sourceScene.id) {
+    const diagnostic = sceneErrorDiagnostic("scene.training_scene_mismatch", `Scene manifest "${validation.scene?.id ?? "(unknown)"}" does not match source run scene "${sourceScene.id}".`, "scene");
+    return failedReport({ scenePath: validation.scenePath, runRoot: resolved.runRoot, diagnostics: [diagnostic], blockers: [diagnostic] });
+  }
+  const scene = applyFormatFilter(sourceScene, input.formats);
+  try {
+    const outputs = buildTreeseedSceneTrainingOutputs({ scene, run, timeline });
+    const paths = writeTreeseedSceneTrainingOutputs({ runRoot: resolved.runRoot, scene, outputs });
+    const updateWarnings = appendTreeseedSceneTrainingOutputPaths({ runPath, paths });
+    return {
+      ok: true,
+      phase: 8,
+      sceneId: sourceScene.id,
+      sourceRunId: run.runId,
+      scenePath: validation.scenePath,
+      runRoot: resolved.runRoot,
+      trainingRoot: paths.trainingRoot,
+      outputs,
+      paths,
+      diagnostics: updateWarnings,
+      warnings: updateWarnings,
+      blockers: []
+    };
+  } catch (error) {
+    const diagnostic = sceneErrorDiagnostic("scene.training_write_failed", `Training outputs could not be written. ${error instanceof Error ? error.message : String(error ?? "")}`.trim(), "training");
+    return failedReport({ scenePath: validation.scenePath, runRoot: resolved.runRoot, diagnostics: [diagnostic], blockers: [diagnostic] });
+  }
+}
+export {
+  buildTreeseedSceneTrainingOutputs,
+  formatTreeseedSceneCaptionsSrt,
+  formatTreeseedSceneCaptionsVtt,
+  formatTreeseedSceneNarrationMarkdown,
+  formatTreeseedSceneTranscriptMarkdown,
+  generateTreeseedSceneTrainingOutputs
+};