@morshoto/framekit 0.1.17 → 0.2.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (58) hide show
  1. package/README.md +25 -14
  2. package/dist-package/adapters/final-cut/typescript/src/background-materialization.js +8 -2
  3. package/dist-package/adapters/final-cut/typescript/src/canonical-recovery-guard.js +275 -0
  4. package/dist-package/adapters/final-cut/typescript/src/canonical.js +557 -84
  5. package/dist-package/adapters/final-cut/typescript/src/connection.js +10 -3
  6. package/dist-package/adapters/final-cut/typescript/src/disposable-native.js +6 -0
  7. package/dist-package/adapters/final-cut/typescript/src/experimental.js +8 -0
  8. package/dist-package/adapters/final-cut/typescript/src/fcpxml.js +150 -37
  9. package/dist-package/adapters/final-cut/typescript/src/index.js +2 -7
  10. package/dist-package/adapters/final-cut/typescript/src/library-inspection.js +60 -1
  11. package/dist-package/adapters/final-cut/typescript/src/live.js +29 -4
  12. package/dist-package/adapters/final-cut/typescript/src/native-recovery-inspection.js +175 -0
  13. package/dist-package/adapters/final-cut/typescript/src/native-session.js +11 -6
  14. package/dist-package/adapters/final-cut/typescript/src/native.js +201 -82
  15. package/dist-package/adapters/final-cut/typescript/src/publish-readback.js +214 -0
  16. package/dist-package/adapters/final-cut/typescript/src/publisher.js +1008 -243
  17. package/dist-package/adapters/final-cut/typescript/src/session.js +49 -14
  18. package/dist-package/adapters/final-cut/typescript/src/timeline-ir-fcpxml.js +203 -49
  19. package/dist-package/adapters/headless/typescript/src/audio-output.js +3 -0
  20. package/dist-package/adapters/headless/typescript/src/ffmpeg-renderer.js +48 -20
  21. package/dist-package/adapters/headless/typescript/src/ffmpeg-verifier.js +9 -4
  22. package/dist-package/apps/cli/src/dev-doctor.js +198 -0
  23. package/dist-package/apps/cli/src/headless-projects.js +5 -0
  24. package/dist-package/apps/cli/src/main.js +76 -19
  25. package/dist-package/apps/mcp-server/runtime/speech-analyzer-wrapper.mjs +54 -0
  26. package/dist-package/apps/mcp-server/runtime/whisper-speech-backend.py +181 -0
  27. package/dist-package/apps/mcp-server/src/build-alignment.js +59 -0
  28. package/dist-package/apps/mcp-server/src/build-identity.js +30 -0
  29. package/dist-package/apps/mcp-server/src/build-identity.json +5 -0
  30. package/dist-package/apps/mcp-server/src/canonical-native-snapshot.js +18 -0
  31. package/dist-package/apps/mcp-server/src/final-cut-runtime-config.js +3 -0
  32. package/dist-package/apps/mcp-server/src/headless-project-snapshot.js +101 -0
  33. package/dist-package/apps/mcp-server/src/main.js +50 -21
  34. package/dist-package/apps/mcp-server/src/materialization-jobs.js +143 -10
  35. package/dist-package/apps/mcp-server/src/routing.js +2 -0
  36. package/dist-package/apps/mcp-server/src/server.js +986 -180
  37. package/dist-package/apps/mcp-server/src/tools/skills/catalog.js +142 -0
  38. package/dist-package/apps/mcp-server/src/tools/skills/metadata.js +71 -0
  39. package/dist-package/apps/mcp-server/src/tools/skills/register.js +101 -0
  40. package/dist-package/apps/mcp-server/src/version.js +21 -2
  41. package/dist-package/packages/headless-application/src/headless-projects.js +942 -0
  42. package/dist-package/packages/headless-application/src/index.js +1 -0
  43. package/dist-package/packages/runtime/src/application/media-analysis-service.js +15 -5
  44. package/dist-package/packages/runtime/src/application/project-service.js +5 -1
  45. package/dist-package/packages/runtime/src/application/project-store.js +13 -36
  46. package/dist-package/packages/runtime/src/application/transaction-store.js +1 -1
  47. package/dist-package/packages/runtime/src/capabilities.js +1 -1
  48. package/dist-package/packages/runtime/src/context/context-engine.js +22 -16
  49. package/dist-package/packages/runtime/src/context/context-service.js +2 -2
  50. package/dist-package/packages/runtime/src/editing/edit-service.js +76 -10
  51. package/dist-package/packages/runtime/src/index.js +1 -0
  52. package/dist-package/packages/runtime/src/runtime.js +22 -7
  53. package/dist-package/packages/runtime/src/timeline/editing-session.js +23 -2
  54. package/dist-package/packages/testkit/src/in-memory-editor.js +3 -3
  55. package/dist-package/packages/testkit/src/index.js +1 -0
  56. package/dist-package/packages/testkit/src/sender-lifecycle-fixture.js +192 -0
  57. package/package.json +36 -14
  58. package/dist-package/apps/mcp-server/src/headless-projects.js +0 -370
@@ -0,0 +1,181 @@
1
+ #!/usr/bin/env python3
2
+ """Run an optional local Whisper implementation against Framekit's JSON protocol.
3
+
4
+ The script intentionally has no Python package dependency of its own. Install
5
+ either mlx-whisper or openai-whisper in the environment that runs it and select
6
+ the model with FRAMEKIT_WHISPER_MODEL.
7
+ """
8
+
9
+ import importlib
10
+ import json
11
+ import math
12
+ import os
13
+ import sys
14
+ from typing import Any
15
+
16
+
17
+ def fail(code: int, message: str) -> None:
18
+ print(message, file=sys.stderr)
19
+ raise SystemExit(code)
20
+
21
+
22
+ def read_request() -> dict[str, Any]:
23
+ try:
24
+ value = json.load(sys.stdin)
25
+ except json.JSONDecodeError as error:
26
+ fail(65, f"WHISPER_REQUEST_INVALID: backend received invalid JSON: {error}")
27
+ if not isinstance(value, dict):
28
+ fail(65, "WHISPER_REQUEST_INVALID: backend request must be an object")
29
+ return value
30
+
31
+
32
+ def required_record(value: Any, name: str) -> dict[str, Any]:
33
+ if not isinstance(value, dict):
34
+ fail(65, f"WHISPER_REQUEST_INVALID: {name} must be an object")
35
+ return value
36
+
37
+
38
+ def finite_number(value: Any, name: str) -> float:
39
+ if isinstance(value, bool) or not isinstance(value, (int, float)) or not math.isfinite(value):
40
+ fail(65, f"WHISPER_OUTPUT_INVALID: {name} must be a finite number")
41
+ return float(value)
42
+
43
+
44
+ def load_backend() -> tuple[str, Any]:
45
+ requested = os.environ.get("FRAMEKIT_WHISPER_BACKEND", "auto").strip().lower()
46
+ candidates = {
47
+ "mlx-whisper": ("mlx_whisper", "MLX Whisper"),
48
+ "openai-whisper": ("whisper", "openai-whisper"),
49
+ }
50
+ if requested not in {"auto", *candidates}:
51
+ fail(78, "WHISPER_SETUP_REQUIRED: FRAMEKIT_WHISPER_BACKEND must be auto, mlx-whisper, or openai-whisper")
52
+
53
+ ordered = list(candidates) if requested == "auto" else [requested]
54
+ errors: list[str] = []
55
+ for name in ordered:
56
+ module_name, label = candidates[name]
57
+ try:
58
+ return label, importlib.import_module(module_name)
59
+ except ImportError as error:
60
+ errors.append(f"{name}: {error}")
61
+ detail = "; ".join(errors)
62
+ fail(78, f"WHISPER_SETUP_REQUIRED: install a selected local backend ({detail})")
63
+ raise AssertionError("unreachable")
64
+
65
+
66
+ def transcribe(module_label: str, module: Any, source: str) -> dict[str, Any]:
67
+ model = os.environ.get("FRAMEKIT_WHISPER_MODEL", "").strip()
68
+ if not model:
69
+ fail(78, "WHISPER_SETUP_REQUIRED: set FRAMEKIT_WHISPER_MODEL to a local model or model repository")
70
+ language = os.environ.get("FRAMEKIT_WHISPER_LANGUAGE", "").strip() or None
71
+
72
+ try:
73
+ if module_label == "MLX Whisper":
74
+ options: dict[str, Any] = {
75
+ "path_or_hf_repo": model,
76
+ "word_timestamps": True,
77
+ }
78
+ if language:
79
+ options["language"] = language
80
+ result = module.transcribe(source, **options)
81
+ else:
82
+ model_instance = module.load_model(model)
83
+ options = {"word_timestamps": True, "verbose": False, "fp16": False}
84
+ if language:
85
+ options["language"] = language
86
+ result = model_instance.transcribe(source, **options)
87
+ except Exception as error: # noqa: BLE001 - provider diagnostics must cross the process boundary
88
+ fail(78, f"WHISPER_ANALYZER_FAILED: {module_label} could not transcribe the source: {error}")
89
+ if not isinstance(result, dict):
90
+ fail(65, "WHISPER_OUTPUT_INVALID: Whisper backend must return an object")
91
+ return result
92
+
93
+
94
+ def confidence(value: Any) -> float:
95
+ if value is None:
96
+ # Whisper implementations may omit probability even when they expose
97
+ # reliable timestamps. Zero preserves that uncertainty for selectors.
98
+ return 0.0
99
+ number = finite_number(value, "word confidence")
100
+ if number < 0 or number > 1:
101
+ fail(65, "WHISPER_OUTPUT_INVALID: word confidence must be between 0 and 1")
102
+ return number
103
+
104
+
105
+ def normalized_words(result: dict[str, Any], requested: dict[str, Any] | None) -> list[dict[str, Any]]:
106
+ entries: list[dict[str, Any]] = []
107
+ segments = result.get("segments", [])
108
+ if not isinstance(segments, list):
109
+ fail(65, "WHISPER_OUTPUT_INVALID: segments must be an array")
110
+ for segment in segments:
111
+ segment_record = required_record(segment, "segment")
112
+ segment_start = finite_number(segment_record.get("start"), "segment start")
113
+ segment_end = finite_number(segment_record.get("end"), "segment end")
114
+ if segment_start < 0 or segment_end < segment_start:
115
+ fail(65, "WHISPER_OUTPUT_INVALID: segment boundaries are invalid")
116
+ words = segment_record.get("words")
117
+ text = str(segment_record.get("text", "")).strip()
118
+ if segment_start == segment_end:
119
+ if not text and (words is None or words == []):
120
+ continue
121
+ fail(65, "WHISPER_OUTPUT_INVALID: segment boundaries are invalid")
122
+ if not isinstance(words, list) or not words:
123
+ words = [{"word": text, "start": segment_start, "end": segment_end}]
124
+ for word in words:
125
+ word_record = required_record(word, "word")
126
+ text = str(word_record.get("word", word_record.get("text", ""))).strip()
127
+ if not text:
128
+ continue
129
+ start = finite_number(word_record.get("start"), "word start")
130
+ end = finite_number(word_record.get("end"), "word end")
131
+ if start < 0 or end < start:
132
+ fail(65, "WHISPER_OUTPUT_INVALID: word boundaries are invalid")
133
+ if start == end:
134
+ continue
135
+ if requested is not None:
136
+ request_start = finite_number(requested.get("start"), "request start")
137
+ request_end = finite_number(requested.get("end"), "request end")
138
+ if start < request_start or end > request_end:
139
+ continue
140
+ entries.append({
141
+ "text": text,
142
+ "start": start,
143
+ "end": end,
144
+ "confidence": confidence(word_record.get("probability", word_record.get("confidence"))),
145
+ })
146
+
147
+ entries.sort(key=lambda value: (value["start"], value["end"], value["text"]))
148
+ for previous, current in zip(entries, entries[1:]):
149
+ if current["start"] < previous["end"]:
150
+ fail(65, "WHISPER_OUTPUT_INVALID: word timestamps overlap")
151
+ return entries
152
+
153
+
154
+ def main() -> None:
155
+ request = read_request()
156
+ media = required_record(request.get("media"), "media")
157
+ source = media.get("source")
158
+ if not isinstance(source, str) or not source:
159
+ fail(65, "WHISPER_REQUEST_INVALID: media.source is required")
160
+ if not os.path.isfile(source):
161
+ fail(78, f"WHISPER_MEDIA_UNAVAILABLE: source does not exist: {source}")
162
+
163
+ requested = request.get("range")
164
+ if requested is not None:
165
+ requested = required_record(requested, "range")
166
+ start = finite_number(requested.get("start"), "request start")
167
+ end = finite_number(requested.get("end"), "request end")
168
+ if start < 0 or end <= start:
169
+ fail(65, "WHISPER_REQUEST_INVALID: range boundaries are invalid")
170
+
171
+ module_label, module = load_backend()
172
+ result = transcribe(module_label, module, source)
173
+ output = {
174
+ "words": normalized_words(result, requested),
175
+ "sourceTimebase": {"value": "1", "timescale": "1000"},
176
+ }
177
+ print(json.dumps(output, separators=(",", ":")))
178
+
179
+
180
+ if __name__ == "__main__":
181
+ main()
@@ -0,0 +1,59 @@
1
+ export function assessBuildAlignment(runtime, extension, targetCommit = runtime.commit) {
2
+ const target = { version: runtime.version, commit: targetCommit };
3
+ const unavailableCommit = [
4
+ ["runtime", runtime.commit],
5
+ ["target", target.commit],
6
+ ...(extension ? [["extension", extension.commit]] : []),
7
+ ].find(([, commit]) => !commit.trim() || commit.trim().toLowerCase() === "unknown");
8
+ if (unavailableCommit) {
9
+ return {
10
+ status: "missing",
11
+ target,
12
+ runtime,
13
+ ...(extension ? { extension } : {}),
14
+ message: `${unavailableCommit[0]} commit identity is unavailable`,
15
+ };
16
+ }
17
+ if (runtime.commit !== target.commit) {
18
+ return {
19
+ status: "mismatched",
20
+ target,
21
+ runtime,
22
+ ...(extension ? { extension } : {}),
23
+ message: `runtime commit ${runtime.commit} does not match target commit ${target.commit}`,
24
+ };
25
+ }
26
+ if (!extension) {
27
+ return {
28
+ status: "missing",
29
+ target,
30
+ runtime,
31
+ message: "extension fingerprint is unavailable",
32
+ };
33
+ }
34
+ if (extension.version !== runtime.version) {
35
+ return {
36
+ status: "mismatched",
37
+ target,
38
+ runtime,
39
+ extension,
40
+ message: `extension version ${extension.version} does not match runtime version ${runtime.version}`,
41
+ };
42
+ }
43
+ if (extension.commit !== runtime.commit) {
44
+ return {
45
+ status: "mismatched",
46
+ target,
47
+ runtime,
48
+ extension,
49
+ message: `extension commit ${extension.commit} does not match runtime commit ${runtime.commit}`,
50
+ };
51
+ }
52
+ return {
53
+ status: "matched",
54
+ target,
55
+ runtime,
56
+ extension,
57
+ message: "runtime and extension fingerprints match",
58
+ };
59
+ }
@@ -0,0 +1,30 @@
1
+ const fullCommitPattern = /^[0-9a-f]{40}$/i;
2
+ export function createPackageBuildIdentity(version, commit) {
3
+ if (!version.trim() || !fullCommitPattern.test(commit)) {
4
+ throw new Error("FRAMEKIT_PACKAGE_BUILD_IDENTITY_INVALID: version and full commit are required");
5
+ }
6
+ return { schemaVersion: 1, version, commit: commit.toLowerCase() };
7
+ }
8
+ export function parsePackageBuildIdentity(value, expectedVersion) {
9
+ if (value === undefined || value === null)
10
+ return undefined;
11
+ if (!value || typeof value !== "object" || Array.isArray(value)) {
12
+ throw new Error("FRAMEKIT_PACKAGE_BUILD_IDENTITY_INVALID: expected an object");
13
+ }
14
+ const identity = value;
15
+ const commit = identity.commit;
16
+ if (identity.schemaVersion !== 1
17
+ || typeof identity.version !== "string"
18
+ || typeof commit !== "string"
19
+ || !fullCommitPattern.test(commit)) {
20
+ throw new Error("FRAMEKIT_PACKAGE_BUILD_IDENTITY_INVALID: schema or commit is invalid");
21
+ }
22
+ if (identity.version !== expectedVersion) {
23
+ throw new Error("FRAMEKIT_PACKAGE_BUILD_IDENTITY_VERSION_MISMATCH");
24
+ }
25
+ return {
26
+ schemaVersion: 1,
27
+ version: identity.version,
28
+ commit: commit.toLowerCase(),
29
+ };
30
+ }
@@ -0,0 +1,5 @@
1
+ {
2
+ "schemaVersion": 1,
3
+ "version": "0.2.2",
4
+ "commit": "3af4f3f6cc6b31ddb309c9a32f62d9d4de6bc9fd"
5
+ }
@@ -0,0 +1,18 @@
1
+ export function createCanonicalNativeSnapshotReader(readLiveState, readSnapshot) {
2
+ return async () => {
3
+ const live = await readLiveState();
4
+ const project = live.project;
5
+ const sequence = live.sequence;
6
+ if (!project?.id || project.id.startsWith("final-cut:")
7
+ || !project.name.trim() || !sequence?.id || sequence.id.startsWith("final-cut:")
8
+ || !sequence.name.trim()) {
9
+ throw new Error("TARGET_UNAVAILABLE: stable live project and sequence identities are required for canonical export");
10
+ }
11
+ return readSnapshot({
12
+ projectId: project.id,
13
+ sequenceId: sequence.id,
14
+ projectName: project.name,
15
+ sequenceName: sequence.name,
16
+ });
17
+ };
18
+ }
@@ -0,0 +1,3 @@
1
+ export function shouldConfigureFinalCutProjectPublisher(input) {
2
+ return input.liveMode && (Boolean(input.fcpxmlPath) || input.canonicalNativeProviderEnabled);
3
+ }
@@ -0,0 +1,101 @@
1
+ /** Adapt the persisted headless Timeline IR to the runtime's analysis contract. */
2
+ export function projectSnapshotFromTimelineIr(timeline) {
3
+ const occurrences = timeline.sequence.occurrences;
4
+ const seconds = (time) => {
5
+ const value = Number(time.value) / Number(time.timescale);
6
+ if (!Number.isFinite(value))
7
+ throw new Error("HEADLESS_TIMELINE_INVALID: rational time is outside the supported range");
8
+ return value;
9
+ };
10
+ const stories = timeline.sequence.storyElements.map((element) => {
11
+ const occurrence = occurrences.find((candidate) => candidate.id === element.occurrenceId);
12
+ return {
13
+ id: element.id,
14
+ kind: element.kind,
15
+ start: seconds(element.startTime),
16
+ duration: seconds(element.durationTime),
17
+ startTime: structuredClone(element.startTime),
18
+ durationTime: structuredClone(element.durationTime),
19
+ ...(element.lane !== undefined ? { lane: element.lane } : {}),
20
+ ...(occurrence?.mediaId ? { mediaId: occurrence.mediaId } : {}),
21
+ ...(element.text !== undefined ? { text: element.text } : {}),
22
+ ...(element.attachedTo ? { attachedTo: element.attachedTo } : {}),
23
+ };
24
+ });
25
+ for (const title of timeline.sequence.titles ?? []) {
26
+ stories.push({
27
+ id: title.id,
28
+ kind: "title",
29
+ start: seconds(title.startTime),
30
+ duration: seconds(title.durationTime),
31
+ startTime: structuredClone(title.startTime),
32
+ durationTime: structuredClone(title.durationTime),
33
+ lane: title.lane,
34
+ text: title.text,
35
+ });
36
+ }
37
+ return {
38
+ projectId: timeline.project.id,
39
+ projectName: timeline.project.name,
40
+ timeline: {
41
+ id: timeline.sequence.id,
42
+ name: timeline.sequence.name,
43
+ duration: seconds(timeline.sequence.durationTime),
44
+ durationTime: structuredClone(timeline.sequence.durationTime),
45
+ frameDuration: structuredClone(timeline.sequence.frameDuration),
46
+ clips: occurrences.map((occurrence) => ({
47
+ id: occurrence.id,
48
+ ...(occurrence.mediaId ? { mediaId: occurrence.mediaId } : {}),
49
+ name: occurrence.name,
50
+ start: seconds(occurrence.startTime),
51
+ duration: seconds(occurrence.durationTime),
52
+ ...(occurrence.sourceStartTime ? {
53
+ sourceStart: seconds(occurrence.sourceStartTime),
54
+ sourceStartTime: structuredClone(occurrence.sourceStartTime),
55
+ } : {}),
56
+ track: occurrence.track,
57
+ ...(occurrence.gainDb !== undefined ? { gainDb: occurrence.gainDb } : {}),
58
+ ...(occurrence.fadeIn !== undefined ? { fadeIn: occurrence.fadeIn } : {}),
59
+ ...(occurrence.fadeOut !== undefined ? { fadeOut: occurrence.fadeOut } : {}),
60
+ ...(occurrence.enabled !== undefined ? { enabled: occurrence.enabled } : {}),
61
+ ...(occurrence.role ? { role: occurrence.role } : {}),
62
+ ...(occurrence.attachedTo ? { attachedTo: occurrence.attachedTo } : {}),
63
+ startTime: structuredClone(occurrence.startTime),
64
+ durationTime: structuredClone(occurrence.durationTime),
65
+ })),
66
+ storyElements: stories,
67
+ markers: timeline.sequence.markers.map((marker) => ({
68
+ id: marker.id,
69
+ name: marker.name,
70
+ start: seconds(marker.startTime),
71
+ duration: seconds(marker.durationTime),
72
+ startTime: structuredClone(marker.startTime),
73
+ durationTime: structuredClone(marker.durationTime),
74
+ })),
75
+ captions: timeline.sequence.captions.map((caption) => ({
76
+ id: caption.id,
77
+ text: caption.text,
78
+ start: seconds(caption.startTime),
79
+ duration: seconds(caption.durationTime),
80
+ startTime: structuredClone(caption.startTime),
81
+ durationTime: structuredClone(caption.durationTime),
82
+ })),
83
+ },
84
+ media: timeline.resources.flatMap((resource) => {
85
+ if (!resource.source)
86
+ return [];
87
+ const mediaKind = resource.mediaKind === "audio" || resource.mediaKind === "video"
88
+ ? resource.mediaKind
89
+ : undefined;
90
+ const durationTime = resource.metadata?.durationTime;
91
+ return [{
92
+ mediaId: resource.id,
93
+ source: resource.source,
94
+ ...(mediaKind ? { mediaKind } : {}),
95
+ ...(resource.sourceDigest ? { sourceDigest: resource.sourceDigest } : {}),
96
+ ...(durationTime ? { duration: seconds(durationTime) } : {}),
97
+ }];
98
+ }),
99
+ revision: structuredClone(timeline.revision),
100
+ };
101
+ }
@@ -2,13 +2,15 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
2
2
  import { homedir } from "node:os";
3
3
  import { join } from "node:path";
4
4
  import { InMemoryEditorAdapter } from "../../../packages/testkit/src/index.js";
5
- import { createCommandAnalyzers, createFinalCutLiveAdapter, FcpxmlDocumentAdapter, FinalCutAssetRegistry, FinalCutMediaRegistry, FinalCutConnectionManager, assertCanonicalProviderConfiguration, FinalCutCanonicalNativeProvider, FinalCutCanonicalSnapshotSource, FinalCutLibraryInspectionProvider, FinalCutNativeAutomationAdapter, createFinalCutNativeTargetResolver, DisposableNativeEditWorkflow, FinalCutBackgroundMaterializationPublisher, FinalCutProjectPublisher, FinalCutSqliteInspectionProvider, FinalCutVideoExporter, FinalCutSessionAdapter, createNativeOperationLease, createDisposableNativeOperationSession, isFinalCutVideoProbeAvailable, } from "../../../adapters/final-cut/typescript/src/index.js";
5
+ import { createCommandAnalyzers, createFinalCutLiveAdapter, FcpxmlDocumentAdapter, FinalCutAssetRegistry, FinalCutMediaRegistry, FinalCutConnectionManager, assertCanonicalProviderConfiguration, FinalCutCanonicalNativeProvider, FileCanonicalRecoveryGuard, FinalCutCanonicalSnapshotSource, FinalCutLibraryInspectionProvider, FinalCutNativeAutomationAdapter, createFinalCutNativeTargetResolver, DisposableNativeEditWorkflow, FinalCutBackgroundMaterializationPublisher, FinalCutProjectPublisher, parseFinalCutProjectPublishRoute, FinalCutVideoExporter, FinalCutSessionAdapter, createNativeOperationLease, createDisposableNativeOperationSession, isFinalCutVideoProbeAvailable, } from "../../../adapters/final-cut/typescript/src/index.js";
6
6
  import { FixtureAudioAnalyzer, FixtureMetadataAnalyzer, FixtureSpeechAnalyzer, FixtureVisualAnalyzer } from "../../../packages/testkit/src/index.js";
7
7
  import { AgentVideoRuntime, JsonSemanticMediaIndexStore } from "../../../packages/runtime/src/index.js";
8
+ import { HeadlessProjectService } from "../../../packages/headless-application/src/index.js";
8
9
  import { createMcpServer } from "./server.js";
9
10
  import { createCanonicalSessionChangeSource } from "./headless-sessions.js";
10
- import { HeadlessProjectService } from "./headless-projects.js";
11
+ import { createCanonicalNativeSnapshotReader } from "./canonical-native-snapshot.js";
11
12
  import { FfmpegMediaMetadataProbe, FfmpegRenderVerifier, FfmpegTimelineRenderer } from "../../../adapters/headless/typescript/src/index.js";
13
+ import { shouldConfigureFinalCutProjectPublisher } from "./final-cut-runtime-config.js";
12
14
  const fixture = new InMemoryEditorAdapter({
13
15
  projectId: "project-1",
14
16
  projectName: "Phase 2 Fixture",
@@ -53,6 +55,7 @@ const fixture = new InMemoryEditorAdapter({
53
55
  },
54
56
  }],
55
57
  });
58
+ const framekitStateDirectory = process.env.FRAMEKIT_STATE_DIR ?? join(homedir(), ".framekit");
56
59
  const liveMode = process.env.FRAMEKIT_EDITOR === "final-cut-live";
57
60
  const headlessFinalCut = liveMode && process.env.FRAMEKIT_FINAL_CUT_HEADLESS === "1";
58
61
  const fcpxmlPath = liveMode ? process.env.FRAMEKIT_FCPXML_PATH : undefined;
@@ -68,7 +71,11 @@ const canonicalProviderRequired = liveMode
68
71
  && !canonicalNativeProviderEnabled;
69
72
  assertCanonicalProviderConfiguration({ required: canonicalProviderRequired || canonicalNativeProviderEnabled, fcpxmlPath });
70
73
  const connection = liveMode
71
- ? new FinalCutConnectionManager({ headless: headlessFinalCut, canonicalProviderRequired })
74
+ ? new FinalCutConnectionManager({
75
+ headless: headlessFinalCut,
76
+ canonicalProviderRequired,
77
+ existingSocketOnly: process.env.FRAMEKIT_FINAL_CUT_EXISTING_SOCKET_ONLY === "1",
78
+ })
72
79
  : undefined;
73
80
  const autoConnect = liveMode && process.env.FRAMEKIT_AUTO_CONNECT !== "0";
74
81
  if (autoConnect)
@@ -95,8 +102,12 @@ const canonicalNativeMutationEditor = canonicalNativeProviderEnabled
95
102
  const canonicalNativeTargetResolver = canonicalNativeProviderEnabled
96
103
  ? createFinalCutNativeTargetResolver(nativeEditor)
97
104
  : undefined;
105
+ const canonicalRecovery = liveMode
106
+ ? new FileCanonicalRecoveryGuard(join(framekitStateDirectory, "canonical-recovery", "pending.json"))
107
+ : undefined;
98
108
  const canonicalNativeProvider = canonicalNativeProviderEnabled
99
109
  ? new FinalCutCanonicalNativeProvider({
110
+ recoveryGuard: canonicalRecovery,
100
111
  live: liveAdapter,
101
112
  native: {
102
113
  renameSelectedClip: async (name) => {
@@ -125,17 +136,7 @@ const canonicalNativeProvider = canonicalNativeProviderEnabled
125
136
  return { undone: result.undone, verification: result.verification };
126
137
  },
127
138
  },
128
- readSnapshot: async () => {
129
- const live = await liveAdapter.readLiveState();
130
- const projectId = live.project?.id;
131
- const sequenceId = live.sequence?.id;
132
- if (!projectId || projectId.startsWith("final-cut:") || !sequenceId || sequenceId.startsWith("final-cut:")) {
133
- throw new Error("TARGET_UNAVAILABLE: stable live project and sequence identities are required for canonical export");
134
- }
135
- return new FinalCutCanonicalSnapshotSource({
136
- target: { projectId, projectUid: projectId, sequenceId },
137
- }).readSnapshot();
138
- },
139
+ readSnapshot: createCanonicalNativeSnapshotReader(() => liveAdapter.readLiveState(), (target) => new FinalCutCanonicalSnapshotSource({ readbackTarget: target }).readSnapshot()),
139
140
  resolveTarget: canonicalNativeTargetResolver,
140
141
  backgroundCatalog: backgroundLibraryProvider,
141
142
  })
@@ -164,7 +165,6 @@ const editor = liveMode
164
165
  : {}),
165
166
  })
166
167
  : fixture;
167
- const framekitStateDirectory = process.env.FRAMEKIT_STATE_DIR ?? join(homedir(), ".framekit");
168
168
  const analyzers = liveMode
169
169
  ? createCommandAnalyzers({
170
170
  speechCommand: process.env.FRAMEKIT_SPEECH_ANALYZER,
@@ -187,11 +187,11 @@ const runtime = new AgentVideoRuntime(editor, {
187
187
  });
188
188
  const headlessProjects = new HeadlessProjectService({
189
189
  directory: join(framekitStateDirectory, "projects"),
190
+ protectedStateDirectory: framekitStateDirectory,
190
191
  mediaProbe: new FfmpegMediaMetadataProbe(),
191
192
  renderer: new FfmpegTimelineRenderer(),
192
193
  verifier: new FfmpegRenderVerifier(),
193
194
  });
194
- const sqliteObservationProvider = new FinalCutSqliteInspectionProvider();
195
195
  const disposableNative = liveMode && !headlessFinalCut && !fcpxmlPath && nativeEditor
196
196
  ? new DisposableNativeEditWorkflow({
197
197
  native: nativeEditor,
@@ -206,16 +206,41 @@ const disposableNative = liveMode && !headlessFinalCut && !fcpxmlPath && nativeE
206
206
  })
207
207
  : undefined;
208
208
  const nativeOperationSession = disposableNative && nativeEditor
209
- ? createDisposableNativeOperationSession({ workflow: disposableNative, native: nativeEditor })
209
+ ? createDisposableNativeOperationSession({ workflow: disposableNative, native: nativeEditor, recoveryGuard: canonicalRecovery })
210
210
  : undefined;
211
- const projectPublisher = liveMode && fcpxmlPath
211
+ const projectPublisher = shouldConfigureFinalCutProjectPublisher({
212
+ liveMode,
213
+ fcpxmlPath,
214
+ canonicalNativeProviderEnabled,
215
+ })
212
216
  ? new FinalCutProjectPublisher({
213
217
  enabled: !headlessFinalCut && process.env.FRAMEKIT_FINAL_CUT_NATIVE_WRITES === "1",
214
218
  sourcePath: fcpxmlPath,
219
+ publishJobDirectory: join(framekitStateDirectory, "publish-jobs"),
220
+ publishJobsDirectory: join(framekitStateDirectory, "publish-jobs"),
215
221
  documentDelivery: liveAdapter,
216
- targetLibraryUid: process.env.FRAMEKIT_FINAL_CUT_LIBRARY_UID,
217
- allowHeadedFallback: process.env.FRAMEKIT_FINAL_CUT_ALLOW_HEADED_IMPORT === "1",
222
+ publishRoute: parseFinalCutProjectPublishRoute(process.env.FRAMEKIT_FINAL_CUT_PUBLISH_ROUTE, Boolean(liveAdapter)),
218
223
  liveState: () => liveAdapter.readLiveState(),
224
+ readCanonicalSnapshot: (targetBinding, identity) => new FinalCutCanonicalSnapshotSource({
225
+ readbackTarget: { ...targetBinding, ...identity },
226
+ }).readSnapshot(),
227
+ targetBinding: (targetLibraryPath, identity) => {
228
+ if (!targetLibraryPath || !backgroundLibraryProvider) {
229
+ throw new Error("FINAL_CUT_PUBLISH_TARGET_BINDING_UNAVAILABLE: a target library path and Final Cut library catalog are required");
230
+ }
231
+ return backgroundLibraryProvider.resolveProjectBinding(targetLibraryPath, identity);
232
+ },
233
+ headlessSourceVerifier: async (request) => {
234
+ const proof = await headlessProjects.verifyPublishableRoughCutTransaction({
235
+ sourceTransactionId: request.sourceTransactionId,
236
+ artifactPath: request.artifactPath,
237
+ artifactDigest: request.artifactDigest,
238
+ });
239
+ return {
240
+ targetLibraryUid: proof.targetLibraryUid,
241
+ sourceMediaDigests: proof.sourceMediaDigests,
242
+ };
243
+ },
219
244
  })
220
245
  : undefined;
221
246
  const backgroundMaterializationCommand = liveMode
@@ -242,12 +267,16 @@ const server = createMcpServer(runtime, {
242
267
  disposableNative,
243
268
  nativeOperationSession,
244
269
  projectPublisher,
270
+ canonicalRecovery,
245
271
  ...(sessionMaterializationPublisher?.isAvailable() ? { sessionMaterializationPublisher } : {}),
246
272
  videoExporter,
273
+ requireBuildAlignment: process.env.FRAMEKIT_REQUIRE_BUILD_ALIGNMENT === "1",
274
+ ...(process.env.FRAMEKIT_VALIDATION_COMMIT?.trim()
275
+ ? { validationCommit: process.env.FRAMEKIT_VALIDATION_COMMIT.trim() }
276
+ : {}),
247
277
  sessionDirectory: join(framekitStateDirectory, "sessions"),
248
278
  sessionChangeSource: createCanonicalSessionChangeSource(() => runtime.inspectProject()),
249
279
  materializationDirectory: join(framekitStateDirectory, "materializations"),
250
- sqliteObservationProvider,
251
280
  headlessProjects,
252
281
  });
253
282
  const transport = new StdioServerTransport();