@treeseed/sdk 0.11.0 → 0.12.4

package/dist/scenes/planner.js

@@ -0,0 +1,166 @@
+import { hasTreeseedSceneErrors, sceneErrorDiagnostic } from "./diagnostics.js";
+import { loadTreeseedSceneDocument } from "./loader.js";
+import { planTreeseedSceneArtifactPaths } from "./phase0.js";
+import { treeseedSceneDiagramPluginId, validateTreeseedSceneDiagrams } from "./diagram-validation.js";
+import {
+  listBuiltInTreeseedSceneActions,
+  listBuiltInTreeseedSceneAssertions,
+  listBuiltInTreeseedSceneRenderers,
+  resolveTreeseedScenePlugins
+} from "./registry.js";
+import { parseTreeseedSceneManifest, sceneActionKind, sceneExpectationKinds } from "./schema.js";
+import {
+  TREESEED_SCENE_ENVIRONMENTS
+} from "./types.js";
+function splitDiagnostics(diagnostics, severity) {
+  return diagnostics.filter((diagnostic) => diagnostic.severity === severity);
+}
+function resolveEnvironment(value, fallback) {
+  return value ?? fallback;
+}
+function chapterForStep(stepId, chapters) {
+  let current = null;
+  for (const chapter of chapters) {
+    if (chapter.startsAt === stepId) current = chapter.id;
+  }
+  return current;
+}
+function rendererIds(scene) {
+  return [
+    ...scene.render.remotion ? ["remotion"] : [],
+    ...scene.overlays.map((overlay) => overlay.renderer),
+    ...scene.diagrams.map((diagram) => diagram.renderer)
+  ].filter(Boolean);
+}
+function trainingOutputIds(scene) {
+  if (!scene.training.enabled) return [];
+  return [
+    ...scene.training.captions.enabled ? ["captions"] : [],
+    ...scene.training.transcript.enabled ? ["transcript"] : [],
+    ...scene.training.narration.enabled ? ["narration"] : [],
+    ...scene.training.glossary.enabled ? ["glossary"] : [],
+    ...scene.training.chapterClips.enabled ? ["chapter-clips"] : []
+  ];
+}
+function enabledPluginIds(input) {
+  return [.../* @__PURE__ */ new Set([
+    ...input.actionIds.map((id) => input.registry.actionPlugins.get(id)).filter((id) => Boolean(id)),
+    ...input.assertionIds.map((id) => input.registry.assertionPlugins.get(id)).filter((id) => Boolean(id)),
+    ...input.rendererIds.map((id) => input.registry.rendererPlugins.get(id)).filter((id) => Boolean(id)),
+    ...(input.diagramIds ?? []).map((id) => treeseedSceneDiagramPluginId({ component: id, registry: input.registry })).filter((id) => Boolean(id)),
+    ...(input.trainingOutputIds ?? []).length > 0 ? ["treeseed.scene.training.deterministic"] : []
+  ])].sort();
+}
+function validateTreeseedScene(input) {
+  const loaded = loadTreeseedSceneDocument(input.projectRoot, input.scene);
+  const diagnostics = [...loaded.diagnostics];
+  const scene = diagnostics.length > 0 ? null : parseTreeseedSceneManifest(loaded.value, diagnostics);
+  return {
+    ok: scene !== null && !hasTreeseedSceneErrors(diagnostics),
+    scenePath: loaded.path,
+    scene: scene && !hasTreeseedSceneErrors(diagnostics) ? scene : null,
+    diagnostics
+  };
+}
+function planTreeseedScene(input) {
+  const validation = validateTreeseedScene(input);
+  const pluginResolution = resolveTreeseedScenePlugins();
+  const diagnostics = [...validation.diagnostics];
+  const scene = validation.scene;
+  const diagramDiagnostics = scene ? validateTreeseedSceneDiagrams({ scene, registry: pluginResolution.registry }) : [];
+  if (input.environment && !TREESEED_SCENE_ENVIRONMENTS.includes(input.environment)) {
+    diagnostics.push(sceneErrorDiagnostic("scene.invalid_environment", `Unknown environment: ${input.environment}.`, "environment"));
+  }
+  const environment = resolveEnvironment(input.environment, scene?.target.environment ?? "local");
+  const combinedDiagnostics = [...diagnostics, ...diagramDiagnostics, ...pluginResolution.diagnostics];
+  const blockers = splitDiagnostics(combinedDiagnostics, "error");
+  const warnings = splitDiagnostics(combinedDiagnostics, "warning");
+  if (!scene || blockers.length > 0) {
+    const allActionIds = listBuiltInTreeseedSceneActions().map((action) => action.id);
+    const allAssertionIds = listBuiltInTreeseedSceneAssertions().map((assertion) => assertion.id);
+    const allRendererIds = listBuiltInTreeseedSceneRenderers().map((renderer) => renderer.id);
+    return {
+      ok: false,
+      phase: 1,
+      scenePath: validation.scenePath,
+      sceneId: scene?.id ?? null,
+      title: scene?.title ?? null,
+      environment,
+      baseUrl: scene?.target.baseUrl ?? "auto",
+      browser: scene?.target.browser ?? null,
+      viewport: scene?.target.viewport ?? null,
+      workflowSteps: [],
+      enabledActions: allActionIds,
+      enabledAssertions: allAssertionIds,
+      enabledRenderers: allRendererIds,
+      enabledDiagrams: scene?.diagrams.map((diagram) => diagram.component).sort() ?? [],
+      enabledDiagramPlugins: scene ? [...new Set(scene.diagrams.map((diagram) => treeseedSceneDiagramPluginId({ component: diagram.component, registry: pluginResolution.registry })).filter((id) => Boolean(id)))].sort() : [],
+      enabledTrainingOutputs: scene ? trainingOutputIds(scene) : [],
+      enabledNarrationPlugins: scene?.training.enabled && scene.training.narration.enabled ? ["treeseed.scene.training.deterministic"] : [],
+      enabledDeviceProfiles: scene?.devices.profiles.map((profile) => profile.id).sort() ?? [],
+      enabledPlugins: enabledPluginIds({ actionIds: allActionIds, assertionIds: allAssertionIds, rendererIds: allRendererIds, diagramIds: scene?.diagrams.map((diagram) => diagram.component) ?? [], trainingOutputIds: scene ? trainingOutputIds(scene) : [], registry: pluginResolution.registry }),
+      plugins: pluginResolution.summaries,
+      pluginDiagnostics: pluginResolution.diagnostics,
+      artifactPaths: null,
+      diagnostics: combinedDiagnostics,
+      warnings,
+      blockers,
+      estimatedDurationSeconds: null
+    };
+  }
+  let currentChapter = null;
+  const workflowSteps = scene.workflow.map((step) => {
+    currentChapter = chapterForStep(step.id, scene.chapters) ?? currentChapter;
+    return {
+      id: step.id,
+      title: step.title,
+      actionKind: sceneActionKind(step.action),
+      assertionKinds: sceneExpectationKinds(step.expect),
+      chapterId: currentChapter,
+      demoOnly: step.demoOnly === true
+    };
+  });
+  const actionIds = [...new Set(workflowSteps.map((step) => step.actionKind))];
+  const assertionIds = [...new Set(workflowSteps.flatMap((step) => step.assertionKinds))];
+  const activeRendererIds = [...new Set(rendererIds(scene))];
+  const diagramIds = [...new Set(scene.diagrams.map((diagram) => diagram.component))].sort();
+  const diagramPluginIds = [...new Set(diagramIds.map((id) => treeseedSceneDiagramPluginId({ component: id, registry: pluginResolution.registry })).filter((id) => Boolean(id)))].sort();
+  const trainingOutputs = trainingOutputIds(scene);
+  return {
+    ok: true,
+    phase: 1,
+    scenePath: validation.scenePath,
+    sceneId: scene.id,
+    title: scene.title,
+    environment,
+    baseUrl: scene.target.baseUrl,
+    browser: scene.target.browser,
+    viewport: scene.target.viewport,
+    workflowSteps,
+    enabledActions: actionIds,
+    enabledAssertions: assertionIds,
+    enabledRenderers: activeRendererIds,
+    enabledDiagrams: diagramIds,
+    enabledDiagramPlugins: diagramPluginIds,
+    enabledTrainingOutputs: trainingOutputs,
+    enabledNarrationPlugins: scene.training.enabled && scene.training.narration.enabled ? ["treeseed.scene.training.deterministic"] : [],
+    enabledDeviceProfiles: scene.devices.profiles.map((profile) => profile.id).sort(),
+    enabledPlugins: enabledPluginIds({ actionIds, assertionIds, rendererIds: activeRendererIds, diagramIds, trainingOutputIds: trainingOutputs, registry: pluginResolution.registry }),
+    plugins: pluginResolution.summaries,
+    pluginDiagnostics: pluginResolution.diagnostics,
+    artifactPaths: planTreeseedSceneArtifactPaths({
+      workspaceRoot: input.projectRoot,
+      sceneId: scene.id,
+      runId: input.runId,
+      timestamp: input.timestamp
+    }),
+    diagnostics: combinedDiagnostics,
+    warnings,
+    blockers,
+    estimatedDurationSeconds: null
+  };
+}
+export {
+  planTreeseedScene,
+  validateTreeseedScene
+};

package/dist/scenes/playwright-adapter.d.ts

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

package/dist/scenes/playwright-adapter.js

@@ -0,0 +1,63 @@
+function normalizePlaywrightError(error) {
+  const message = error instanceof Error ? error.message : String(error ?? "Unknown Playwright error.");
+  const missingBrowser = /Executable doesn't exist|browserType\.launch|playwright install/iu.test(message);
+  const tagged = new Error(message);
+  tagged.treeseedSceneCode = missingBrowser ? "scene.playwright_browser_missing" : "scene.playwright_unavailable";
+  return tagged;
+}
+function createPlaywrightTreeseedSceneBrowserAdapter() {
+  return {
+    async launch(input) {
+      let playwright;
+      try {
+        playwright = await import("playwright");
+      } catch (error) {
+        throw normalizePlaywrightError(error);
+      }
+      const browserType = playwright[input.browser];
+      if (!browserType) {
+        throw new Error(`Unsupported Playwright browser: ${input.browser}`);
+      }
+      try {
+        const browser = await browserType.launch();
+        const context = await browser.newContext({
+          viewport: input.viewport,
+          screen: input.viewport,
+          deviceScaleFactor: input.deviceScaleFactor ?? 1,
+          isMobile: input.isMobile ?? false,
+          hasTouch: input.hasTouch ?? false,
+          ...input.userAgent ? { userAgent: input.userAgent } : {},
+          ...input.recordVideoDir ? { recordVideo: { dir: input.recordVideoDir, size: input.videoSize ?? input.viewport } } : {}
+        });
+        const page = await context.newPage();
+        const video = page.video?.() ?? null;
+        return {
+          page,
+          async startTracing() {
+            await context.tracing.start({ screenshots: true, snapshots: true, sources: true });
+          },
+          async stopTracing(tracePath) {
+            await context.tracing.stop({ path: tracePath });
+          },
+          async videoPaths() {
+            if (!video) return [];
+            try {
+              return [await video.path()];
+            } catch {
+              return [];
+            }
+          },
+          async close() {
+            await context.close().catch(() => void 0);
+            await browser.close().catch(() => void 0);
+          }
+        };
+      } catch (error) {
+        throw normalizePlaywrightError(error);
+      }
+    }
+  };
+}
+export {
+  createPlaywrightTreeseedSceneBrowserAdapter
+};

package/dist/scenes/plugins.d.ts

@@ -0,0 +1,5 @@
+import type { TreeseedScenePlugin, TreeseedScenePluginRegistry, TreeseedScenePluginResolution, TreeseedScenePluginSummary, TreeseedSceneRuntimePluginContext, TreeseedSceneRuntimePluginContextInput } from './types.js';
+export declare function createTreeseedScenePluginRegistry(plugins: TreeseedScenePlugin[]): TreeseedScenePluginRegistry;
+export declare function summarizeTreeseedScenePlugins(plugins: TreeseedScenePlugin[]): TreeseedScenePluginSummary[];
+export declare function createTreeseedSceneRuntimePluginContext(input: TreeseedSceneRuntimePluginContextInput): TreeseedSceneRuntimePluginContext;
+export declare function pluginResolutionFromRegistry(registry: TreeseedScenePluginRegistry): TreeseedScenePluginResolution;

package/dist/scenes/plugins.js

@@ -0,0 +1,115 @@
+import { sceneErrorDiagnostic } from "./diagnostics.js";
+import { resolveTreeseedSceneLocator } from "./selectors.js";
+function categories(plugin) {
+  const values = [];
+  if (plugin.actions && Object.keys(plugin.actions).length > 0) values.push("action");
+  if (plugin.assertions && Object.keys(plugin.assertions).length > 0) values.push("assertion");
+  if (plugin.environment) values.push("environment");
+  if (plugin.captures && Object.keys(plugin.captures).length > 0) values.push("capture");
+  if (plugin.artifacts && Object.keys(plugin.artifacts).length > 0) values.push("artifact");
+  if (plugin.renderers && Object.keys(plugin.renderers).length > 0) values.push("renderer");
+  if (plugin.diagrams && Object.keys(plugin.diagrams).length > 0) values.push("diagram");
+  if (plugin.narration && Object.keys(plugin.narration).length > 0) values.push("narration");
+  return values;
+}
+function summary(plugin) {
+  return {
+    id: plugin.id,
+    version: plugin.version,
+    status: plugin.status,
+    categories: categories(plugin),
+    phase: plugin.phase,
+    summary: plugin.summary
+  };
+}
+function addEntries(input) {
+  for (const [id, entry] of Object.entries(input.entries ?? {})) {
+    if (input.map.has(id)) {
+      input.diagnostics.push(sceneErrorDiagnostic("scene.plugin_duplicate", `Duplicate ${input.category} plugin entry: ${id}.`, `plugins.${input.plugin.id}.${input.category}.${id}`));
+      continue;
+    }
+    input.map.set(id, entry);
+    input.ownerMap.set(id, input.plugin.id);
+  }
+}
+function createTreeseedScenePluginRegistry(plugins) {
+  const registry = {
+    plugins: [...plugins],
+    actions: /* @__PURE__ */ new Map(),
+    actionPlugins: /* @__PURE__ */ new Map(),
+    assertions: /* @__PURE__ */ new Map(),
+    assertionPlugins: /* @__PURE__ */ new Map(),
+    environmentProviders: [],
+    captures: /* @__PURE__ */ new Map(),
+    capturePlugins: /* @__PURE__ */ new Map(),
+    artifacts: /* @__PURE__ */ new Map(),
+    artifactPlugins: /* @__PURE__ */ new Map(),
+    renderers: /* @__PURE__ */ new Map(),
+    rendererPlugins: /* @__PURE__ */ new Map(),
+    diagrams: /* @__PURE__ */ new Map(),
+    diagramPlugins: /* @__PURE__ */ new Map(),
+    narration: /* @__PURE__ */ new Map(),
+    narrationPlugins: /* @__PURE__ */ new Map(),
+    diagnostics: []
+  };
+  const pluginIds = /* @__PURE__ */ new Set();
+  for (const plugin of registry.plugins) {
+    if (!plugin.id || !plugin.version || !plugin.summary) {
+      registry.diagnostics.push(sceneErrorDiagnostic("scene.plugin_invalid", "Plugin id, version, and summary are required.", `plugins.${plugin.id || "(unknown)"}`));
+      continue;
+    }
+    if (pluginIds.has(plugin.id)) {
+      registry.diagnostics.push(sceneErrorDiagnostic("scene.plugin_duplicate", `Duplicate plugin id: ${plugin.id}.`, `plugins.${plugin.id}`));
+      continue;
+    }
+    pluginIds.add(plugin.id);
+    if (plugin.environment) registry.environmentProviders.push(plugin.environment);
+    addEntries({ plugin, category: "action", entries: plugin.actions, map: registry.actions, ownerMap: registry.actionPlugins, diagnostics: registry.diagnostics });
+    addEntries({ plugin, category: "assertion", entries: plugin.assertions, map: registry.assertions, ownerMap: registry.assertionPlugins, diagnostics: registry.diagnostics });
+    addEntries({ plugin, category: "capture", entries: plugin.captures, map: registry.captures, ownerMap: registry.capturePlugins, diagnostics: registry.diagnostics });
+    addEntries({ plugin, category: "artifact", entries: plugin.artifacts, map: registry.artifacts, ownerMap: registry.artifactPlugins, diagnostics: registry.diagnostics });
+    addEntries({ plugin, category: "renderer", entries: plugin.renderers, map: registry.renderers, ownerMap: registry.rendererPlugins, diagnostics: registry.diagnostics });
+    addEntries({ plugin, category: "diagram", entries: plugin.diagrams, map: registry.diagrams, ownerMap: registry.diagramPlugins, diagnostics: registry.diagnostics });
+    addEntries({ plugin, category: "narration", entries: plugin.narration, map: registry.narration, ownerMap: registry.narrationPlugins, diagnostics: registry.diagnostics });
+  }
+  const diagramComponents = /* @__PURE__ */ new Map();
+  for (const [providerId, provider] of registry.diagrams.entries()) {
+    for (const component of Object.keys(provider.diagrams ?? {})) {
+      const owner = diagramComponents.get(component);
+      if (owner) {
+        registry.diagnostics.push(sceneErrorDiagnostic("scene.plugin_duplicate", `Duplicate diagram component id: ${component}.`, `plugins.${registry.diagramPlugins.get(providerId) ?? providerId}.diagram.${providerId}.${component}`));
+        continue;
+      }
+      diagramComponents.set(component, providerId);
+    }
+  }
+  return registry;
+}
+function summarizeTreeseedScenePlugins(plugins) {
+  return plugins.map(summary).sort((a, b) => a.id.localeCompare(b.id));
+}
+function createTreeseedSceneRuntimePluginContext(input) {
+  return {
+    ...input,
+    resolveSelector(selector) {
+      return resolveTreeseedSceneLocator(input.session.page, selector);
+    },
+    resolveUrl(value) {
+      return new URL(value, input.baseUrl.endsWith("/") ? input.baseUrl : `${input.baseUrl}/`).toString();
+    }
+  };
+}
+function pluginResolutionFromRegistry(registry) {
+  return {
+    ok: !registry.diagnostics.some((entry) => entry.severity === "error"),
+    registry,
+    diagnostics: registry.diagnostics,
+    summaries: summarizeTreeseedScenePlugins(registry.plugins)
+  };
+}
+export {
+  createTreeseedScenePluginRegistry,
+  createTreeseedSceneRuntimePluginContext,
+  pluginResolutionFromRegistry,
+  summarizeTreeseedScenePlugins
+};

package/dist/scenes/progress.d.ts

@@ -0,0 +1,17 @@
+import type { TreeseedSceneProgressEvent, TreeseedSceneProgressEventType } from './types.js';
+export declare function createTreeseedSceneProgress(input: {
+    sceneId: string | null;
+    runId: string | null;
+    startedAtMs: number;
+    progressPath?: string | null;
+    onProgress?: (event: TreeseedSceneProgressEvent) => void;
+    now?: () => Date;
+}): {
+    push(type: TreeseedSceneProgressEventType, data?: Record<string, unknown>, options?: {
+        chapterId?: string | null;
+        segmentId?: string | null;
+        stepId?: string | null;
+        checkpointId?: string | null;
+        status?: string;
+    }): TreeseedSceneProgressEvent;
+};

package/dist/scenes/progress.js

@@ -0,0 +1,24 @@
+import { appendTreeseedSceneJsonl } from "./artifacts.js";
+function createTreeseedSceneProgress(input) {
+  const now = input.now ?? (() => /* @__PURE__ */ new Date());
+  return {
+    push(type, data = {}, options = {}) {
+      const timestamp = now();
+      const event = {
+        type,
+        sceneId: input.sceneId,
+        runId: input.runId,
+        timestamp: timestamp.toISOString(),
+        offsetMs: Math.max(0, timestamp.getTime() - input.startedAtMs),
+        data,
+        ...options
+      };
+      if (input.progressPath) appendTreeseedSceneJsonl(input.progressPath, event);
+      input.onProgress?.(event);
+      return event;
+    }
+  };
+}
+export {
+  createTreeseedSceneProgress
+};

package/dist/scenes/publish-destinations.d.ts

@@ -0,0 +1,12 @@
+import type { TreeseedSceneExternalPublishTarget, TreeseedScenePublishedArtifact, TreeseedScenePublishDestination } from './types.js';
+export declare const DEFAULT_TREESEED_SCENE_PUBLICATION_TARGETS: TreeseedSceneExternalPublishTarget[];
+export declare const TREESEED_SCENE_EXTERNAL_PUBLICATION_TARGETS: TreeseedSceneExternalPublishTarget[];
+export declare function isTreeseedSceneExternalPublishTarget(value: unknown): value is TreeseedSceneExternalPublishTarget;
+export declare function createTreeseedScenePublishDestinations(input: {
+    runRoot: string;
+    targets: TreeseedSceneExternalPublishTarget[];
+}): TreeseedScenePublishDestination[];
+export declare function destinationIdsForTreeseedScenePublishedArtifact(input: {
+    artifact: TreeseedScenePublishedArtifact;
+    targets: TreeseedSceneExternalPublishTarget[];
+}): string[];

package/dist/scenes/publish-destinations.js

@@ -0,0 +1,99 @@
+import { join } from "node:path";
+const DEFAULT_TREESEED_SCENE_PUBLICATION_TARGETS = [
+  "docs",
+  "training",
+  "release-evidence"
+];
+const TREESEED_SCENE_EXTERNAL_PUBLICATION_TARGETS = [
+  "docs",
+  "training",
+  "release-evidence",
+  "artifact-store"
+];
+function isTreeseedSceneExternalPublishTarget(value) {
+  return typeof value === "string" && TREESEED_SCENE_EXTERNAL_PUBLICATION_TARGETS.includes(value);
+}
+function createTreeseedScenePublishDestinations(input) {
+  return input.targets.map((target) => {
+    const relativePath = join("publish-plan", "export", target);
+    const title = target === "docs" ? "Documentation evidence publication" : target === "training" ? "Training artifact publication" : target === "release-evidence" ? "Release evidence publication" : "Remote artifact-store publication plan";
+    const provider = target === "artifact-store" ? "artifact-store" : "local";
+    return {
+      id: target,
+      target,
+      title,
+      root: join(input.runRoot, relativePath),
+      relativePath,
+      plannedUrl: null,
+      reconciliationResource: {
+        type: "scene-evidence-publication",
+        provider,
+        environment: target === "release-evidence" ? "release" : null,
+        desiredState: {
+          target,
+          sourceRunRoot: input.runRoot,
+          exportRoot: join(input.runRoot, relativePath),
+          phase: 11,
+          mode: "plan-only"
+        }
+      }
+    };
+  });
+}
+function publishedPath(artifact) {
+  return artifact.publishedPath ?? artifact.sourcePath;
+}
+function isTrainingMarkdown(relativePath) {
+  return /(^|[/\\])training[/\\](transcript\.md|glossary\.md|chapter-clips\.json)$/u.test(relativePath);
+}
+function isTrainingOutput(relativePath) {
+  return /(^|[/\\])training[/\\]/u.test(relativePath);
+}
+function isRenderReport(relativePath) {
+  return /(^|[/\\])render[/\\][^/\\]+[/\\]report\.json$/u.test(relativePath);
+}
+function destinationIdsForTreeseedScenePublishedArtifact(input) {
+  const artifact = input.artifact;
+  if (artifact.decision !== "include") return [];
+  const path = artifact.relativePath;
+  const destinations = [];
+  if (input.targets.includes("docs")) {
+    if (artifact.kind === "markdown-report" || artifact.kind === "render-report" || isTrainingMarkdown(path) || isRenderReport(path)) {
+      destinations.push("docs");
+    }
+  }
+  if (input.targets.includes("training")) {
+    if (artifact.kind === "training-output" || isTrainingOutput(path) || artifact.kind === "render-report") {
+      destinations.push("training");
+    }
+  }
+  if (input.targets.includes("release-evidence")) {
+    if ([
+      "run-report",
+      "markdown-report",
+      "timeline",
+      "setup",
+      "progress",
+      "segment",
+      "checkpoint",
+      "render-report",
+      "training-output",
+      "screenshot"
+    ].includes(artifact.kind)) {
+      destinations.push("release-evidence");
+    }
+  }
+  if (input.targets.includes("artifact-store")) {
+    if (publishedPath(artifact) && artifact.kind !== "render-video" && artifact.kind !== "log-summary") {
+      destinations.push("artifact-store");
+    }
+  }
+  return destinations;
+}
+export {
+  DEFAULT_TREESEED_SCENE_PUBLICATION_TARGETS,
+  TREESEED_SCENE_EXTERNAL_PUBLICATION_TARGETS,
+  createTreeseedScenePublishDestinations,
+  destinationIdsForTreeseedScenePublishedArtifact,
+  isTreeseedSceneExternalPublishTarget
+};

package/dist/scenes/publish-plan-report.d.ts

@@ -0,0 +1,10 @@
+import type { TreeseedSceneDiagnostic, TreeseedScenePublishPlanManifest, TreeseedScenePublishPlanPaths } from './types.js';
+export declare function formatTreeseedScenePublishPlanMarkdownReport(manifest: TreeseedScenePublishPlanManifest): string;
+export declare function writeTreeseedScenePublishPlanReport(input: {
+    manifest: TreeseedScenePublishPlanManifest;
+    paths: TreeseedScenePublishPlanPaths;
+}): void;
+export declare function appendTreeseedScenePublishPlanPaths(input: {
+    runPath: string;
+    paths: TreeseedScenePublishPlanPaths;
+}): TreeseedSceneDiagnostic[];

package/dist/scenes/publish-plan-report.js

@@ -0,0 +1,70 @@
+import { mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+import { sceneWarningDiagnostic } from "./diagnostics.js";
+function writeJson(path, value) {
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, `${JSON.stringify(value, null, 2)}
+`, "utf8");
+}
+function writeText(path, value) {
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, value, "utf8");
+}
+function formatTreeseedScenePublishPlanMarkdownReport(manifest) {
+  const lines = [
+    `# Treeseed Scene Publish Plan: ${manifest.sceneId ?? "(unknown scene)"}`,
+    "",
+    `Scene: ${manifest.sceneId ?? "(unknown)"}`,
+    `Source run: ${manifest.sourceRunId ?? "(unknown)"}`,
+    `Workflow: ${manifest.workflowStatus}`,
+    `Mode: ${manifest.mode}`,
+    `Targets: ${manifest.targets.join(", ") || "(none)"}`,
+    `Destinations: ${manifest.destinations.length}`,
+    `Artifacts: ${manifest.artifacts.length}`,
+    "",
+    "## Destinations",
+    "",
+    "| Target | Root | Provider | Action |",
+    "| --- | --- | --- | --- |",
+    ...manifest.destinations.length > 0 ? manifest.destinations.map((destination) => `| ${destination.target} | ${destination.relativePath} | ${destination.reconciliationResource.provider} | plan-only |`) : ["| (none) | (none) | (none) | (none) |"],
+    "",
+    "## Artifacts",
+    "",
+    "| Kind | Source | Destinations | Decision | SHA-256 |",
+    "| --- | --- | --- | --- | --- |",
+    ...manifest.artifacts.length > 0 ? manifest.artifacts.map((artifact) => `| ${artifact.kind} | ${artifact.relativePath} | ${artifact.destinationIds.join(", ") || "(none)"} | ${artifact.redactionDecision} | ${artifact.sha256 ?? "(none)"} |`) : ["| (none) | (none) | (none) | (none) | (none) |"],
+    "",
+    "## Reconciliation Intents",
+    "",
+    "| Target | Action | Reason |",
+    "| --- | --- | --- |",
+    ...manifest.reconciliationIntents.length > 0 ? manifest.reconciliationIntents.map((intent) => `| ${intent.target} | ${intent.action} | ${intent.reason} |`) : ["| (none) | (none) | (none) |"],
+    ""
+  ];
+  return lines.join("\n");
+}
+function writeTreeseedScenePublishPlanReport(input) {
+  writeJson(input.paths.manifestPath, input.manifest);
+  writeText(input.paths.reportPath, formatTreeseedScenePublishPlanMarkdownReport(input.manifest));
+}
+function appendTreeseedScenePublishPlanPaths(input) {
+  try {
+    if ((statSync(input.runPath).mode & 146) === 0) {
+      throw new Error("run.json is not writable.");
+    }
+    const run = JSON.parse(readFileSync(input.runPath, "utf8"));
+    writeJson(input.runPath, {
+      ...run,
+      publishPlanPaths: input.paths,
+      logs: run.logs ? { ...run.logs, publishPlan: input.paths.publishPlanRoot } : run.logs
+    });
+    return [];
+  } catch (error) {
+    return [sceneWarningDiagnostic("scene.publish_plan_run_update_failed", `Publish plan artifacts were written but run.json could not be updated. ${error instanceof Error ? error.message : String(error ?? "")}`.trim(), "run.json")];
+  }
+}
+export {
+  appendTreeseedScenePublishPlanPaths,
+  formatTreeseedScenePublishPlanMarkdownReport,
+  writeTreeseedScenePublishPlanReport
+};

package/dist/scenes/publish-plan.d.ts

@@ -0,0 +1,15 @@
+import type { TreeseedSceneExternalPublishTarget, TreeseedScenePublishManifest, TreeseedScenePublishPlanManifest, TreeseedScenePublishPlanMode, TreeseedScenePublishPlanOptions, TreeseedScenePublishPlanPaths, TreeseedScenePublishPlanReport } from './types.js';
+export declare function buildTreeseedScenePublishPlanManifest(input: {
+    publish: TreeseedScenePublishManifest;
+    publishManifestPath: string;
+    runRoot: string;
+    targets: TreeseedSceneExternalPublishTarget[];
+    mode: TreeseedScenePublishPlanMode;
+    timestamp?: string;
+}): TreeseedScenePublishPlanManifest;
+export declare function writeTreeseedScenePublishPlan(input: {
+    runRoot: string;
+    manifest: TreeseedScenePublishPlanManifest;
+}): TreeseedScenePublishPlanPaths;
+export declare function planTreeseedScenePublication(input: TreeseedScenePublishPlanOptions): Promise<TreeseedScenePublishPlanReport>;
+export declare function exportTreeseedScenePublication(input: Omit<TreeseedScenePublishPlanOptions, 'mode'>): Promise<TreeseedScenePublishPlanReport>;