@morshoto/framekit 0.1.16 → 0.1.18

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 (30) hide show
  1. package/README.md +10 -4
  2. package/dist-package/adapters/final-cut/typescript/src/canonical.js +19 -7
  3. package/dist-package/adapters/final-cut/typescript/src/connection.js +13 -8
  4. package/dist-package/adapters/final-cut/typescript/src/fcpxml.js +147 -34
  5. package/dist-package/adapters/final-cut/typescript/src/index.js +1 -0
  6. package/dist-package/adapters/final-cut/typescript/src/library-inspection.js +60 -1
  7. package/dist-package/adapters/final-cut/typescript/src/live.js +2 -2
  8. package/dist-package/adapters/final-cut/typescript/src/publish-readback.js +213 -0
  9. package/dist-package/adapters/final-cut/typescript/src/publisher.js +762 -238
  10. package/dist-package/adapters/final-cut/typescript/src/session.js +6 -1
  11. package/dist-package/adapters/final-cut/typescript/src/timeline-ir-fcpxml.js +293 -59
  12. package/dist-package/adapters/headless/typescript/src/ffmpeg-renderer.js +137 -19
  13. package/dist-package/adapters/headless/typescript/src/ffmpeg-verifier.js +2 -2
  14. package/dist-package/apps/cli/src/main.js +34 -19
  15. package/dist-package/apps/mcp-server/src/build-alignment.js +59 -0
  16. package/dist-package/apps/mcp-server/src/build-identity.js +30 -0
  17. package/dist-package/apps/mcp-server/src/build-identity.json +5 -0
  18. package/dist-package/apps/mcp-server/src/headless-project-snapshot.js +101 -0
  19. package/dist-package/apps/mcp-server/src/headless-projects.js +473 -3
  20. package/dist-package/apps/mcp-server/src/main.js +33 -6
  21. package/dist-package/apps/mcp-server/src/server.js +367 -52
  22. package/dist-package/apps/mcp-server/src/version.js +21 -2
  23. package/dist-package/packages/runtime/src/application/media-analysis-service.js +360 -30
  24. package/dist-package/packages/runtime/src/application/semantic-media-index-store.js +86 -0
  25. package/dist-package/packages/runtime/src/index.js +1 -0
  26. package/dist-package/packages/runtime/src/planning/rough-cut.js +103 -7
  27. package/dist-package/packages/runtime/src/render/render-contract.js +3 -0
  28. package/dist-package/packages/runtime/src/runtime.js +11 -2
  29. package/dist-package/packages/runtime/src/timeline/editing-session.js +7 -2
  30. package/package.json +9 -9
@@ -39,6 +39,7 @@ export class FfmpegTimelineRenderer {
39
39
  "local-media": supportsLocalMedia(timeline) ? "supported" : "unsupported",
40
40
  "structural-edits": supportsStructuralEdits(timeline) ? "supported" : "unsupported",
41
41
  "audio-gain": supportsAudioGain(timeline) ? "supported" : "unsupported",
42
+ "audio-mixing": supportsAudioMixing(timeline) ? "supported" : "unsupported",
42
43
  transform: supportsTransforms(timeline) ? "supported" : "unsupported",
43
44
  titles: supportsTitles(timeline) ? "supported" : "unsupported",
44
45
  "cross-dissolve": supportsCrossDissolve(timeline) ? "supported" : "unsupported",
@@ -107,7 +108,12 @@ export class FfmpegTimelineRenderer {
107
108
  async function prepareRenderModel(plan) {
108
109
  const timeline = structuredClone(plan.timeline);
109
110
  const sequence = timeline.sequence;
110
- const occurrences = [...sequence.occurrences].sort((left, right) => compareSeconds(left.startTime, right.startTime));
111
+ const occurrences = sequence.occurrences
112
+ .filter(isPrimaryVideoOccurrence)
113
+ .sort((left, right) => compareSeconds(left.startTime, right.startTime));
114
+ const audioOccurrences = sequence.occurrences
115
+ .filter(isIndependentAudioOccurrence)
116
+ .sort((left, right) => compareSeconds(left.startTime, right.startTime));
111
117
  if (!supportsStructuralEdits(timeline)) {
112
118
  throw new FfmpegRenderError("HEADLESS_RENDER_UNSUPPORTED", "markers, captions, story elements, disabled clips, and non-primary tracks are not supported");
113
119
  }
@@ -116,9 +122,12 @@ async function prepareRenderModel(plan) {
116
122
  }
117
123
  if (occurrences.length === 0)
118
124
  throw new FfmpegRenderError("HEADLESS_RENDER_UNSUPPORTED", "at least one video occurrence is required");
125
+ if (occurrences.length + audioOccurrences.length !== sequence.occurrences.length) {
126
+ throw new FfmpegRenderError("HEADLESS_RENDER_UNSUPPORTED", "occurrence roles and lanes do not form a primary video storyline with connected audio layers");
127
+ }
119
128
  const duration = rationalSeconds(sequence.durationTime, "sequence duration");
120
- const frameRate = 1 / rationalSeconds(sequence.frameDuration, "sequence frame duration");
121
- if (!Number.isFinite(duration) || duration <= 0 || !Number.isFinite(frameRate) || frameRate <= 0) {
129
+ const sequenceFrameRate = 1 / rationalSeconds(sequence.frameDuration, "sequence frame duration");
130
+ if (!Number.isFinite(duration) || duration <= 0 || !Number.isFinite(sequenceFrameRate) || sequenceFrameRate <= 0) {
122
131
  throw new FfmpegRenderError("HEADLESS_RENDER_UNSUPPORTED", "sequence duration and frame rate must be finite and positive");
123
132
  }
124
133
  if (!Number.isSafeInteger(plan.parameters.width) || !Number.isSafeInteger(plan.parameters.height)) {
@@ -130,12 +139,12 @@ async function prepareRenderModel(plan) {
130
139
  const audioAvailability = new Set();
131
140
  let previousEnd = 0;
132
141
  for (const occurrence of occurrences) {
133
- if (occurrence.track !== 0 || occurrence.role === "audio" || occurrence.role === "music" || occurrence.role === "title") {
134
- throw new FfmpegRenderError("HEADLESS_RENDER_UNSUPPORTED", `occurrence role or track is not renderable: ${occurrence.id}`);
135
- }
136
142
  if (occurrence.enabled === false || occurrence.attachedTo) {
137
143
  throw new FfmpegRenderError("HEADLESS_RENDER_UNSUPPORTED", `occurrence has unsupported state: ${occurrence.id}`);
138
144
  }
145
+ if (occurrence.fadeIn !== undefined || occurrence.fadeOut !== undefined) {
146
+ throw new FfmpegRenderError("HEADLESS_RENDER_UNSUPPORTED", `audio fades are not renderable: ${occurrence.id}`);
147
+ }
139
148
  const start = rationalSeconds(occurrence.startTime, `${occurrence.id}.startTime`);
140
149
  const clipDuration = rationalSeconds(occurrence.durationTime, `${occurrence.id}.durationTime`);
141
150
  if (Math.abs(start - previousEnd) > 1e-7) {
@@ -145,6 +154,8 @@ async function prepareRenderModel(plan) {
145
154
  const resource = occurrence.mediaId ? resources.get(occurrence.mediaId) : undefined;
146
155
  if (!resource)
147
156
  throw new FfmpegRenderError("HEADLESS_RENDER_UNSUPPORTED", `occurrence has no registered media: ${occurrence.id}`);
157
+ if (resource.mediaKind !== "video")
158
+ throw new FfmpegRenderError("HEADLESS_RENDER_UNSUPPORTED", `primary occurrence does not reference video media: ${occurrence.id}`);
148
159
  const source = await verifyResource(resource, occurrence, clipDuration);
149
160
  const sourcePath = source.path;
150
161
  audioAvailability.add(resource.metadata?.streams.some((stream) => stream.kind === "audio") ?? false);
@@ -154,11 +165,34 @@ async function prepareRenderModel(plan) {
154
165
  sourceIdentities.push(source);
155
166
  }
156
167
  }
168
+ for (const occurrence of audioOccurrences) {
169
+ if (occurrence.enabled === false || occurrence.attachedTo) {
170
+ throw new FfmpegRenderError("HEADLESS_RENDER_UNSUPPORTED", `audio occurrence has unsupported state: ${occurrence.id}`);
171
+ }
172
+ if (occurrence.fadeIn !== undefined || occurrence.fadeOut !== undefined) {
173
+ throw new FfmpegRenderError("HEADLESS_RENDER_UNSUPPORTED", `audio fades are not renderable: ${occurrence.id}`);
174
+ }
175
+ const start = rationalSeconds(occurrence.startTime, `${occurrence.id}.startTime`);
176
+ const clipDuration = rationalSeconds(occurrence.durationTime, `${occurrence.id}.durationTime`);
177
+ if (clipDuration <= 0 || start + clipDuration > duration + 1e-7) {
178
+ throw new FfmpegRenderError("HEADLESS_RENDER_UNSUPPORTED", `audio occurrence exceeds the sequence duration: ${occurrence.id}`);
179
+ }
180
+ const resource = occurrence.mediaId ? resources.get(occurrence.mediaId) : undefined;
181
+ if (!resource)
182
+ throw new FfmpegRenderError("HEADLESS_RENDER_UNSUPPORTED", `audio occurrence has no registered media: ${occurrence.id}`);
183
+ const source = await verifyAudioResource(resource, occurrence, clipDuration);
184
+ if (!sourcePaths.includes(source.path))
185
+ sourcePaths.push(source.path);
186
+ if (!sourceIdentities.some((identity) => identity.path === source.path && identity.digest === source.digest)) {
187
+ sourceIdentities.push(source);
188
+ }
189
+ }
157
190
  if (audioAvailability.size > 1) {
158
191
  throw new FfmpegRenderError("HEADLESS_RENDER_UNSUPPORTED", "all primary occurrences must agree on audio availability");
159
192
  }
160
- if (Math.abs(previousEnd - duration) > 1e-7) {
161
- throw new FfmpegRenderError("HEADLESS_RENDER_UNSUPPORTED", "occurrences do not cover the sequence duration");
193
+ const tailDuration = duration - previousEnd;
194
+ if (tailDuration < -1e-7) {
195
+ throw new FfmpegRenderError("HEADLESS_RENDER_UNSUPPORTED", "primary occurrences exceed the sequence duration");
162
196
  }
163
197
  const transitions = timeline.sequence.transitions ?? [];
164
198
  if (transitions.length > 1) {
@@ -167,10 +201,12 @@ async function prepareRenderModel(plan) {
167
201
  return {
168
202
  timeline,
169
203
  occurrences,
204
+ audioOccurrences,
170
205
  resources,
171
206
  sourcePaths,
172
207
  duration,
173
- frameRate,
208
+ tailDuration: Math.max(0, tailDuration),
209
+ frameRate: structuredClone(plan.parameters.frameRate),
174
210
  width: plan.parameters.width,
175
211
  height: plan.parameters.height,
176
212
  format: plan.parameters.format,
@@ -210,6 +246,38 @@ async function verifyResource(resource, occurrence, duration) {
210
246
  }
211
247
  return { path: sourcePath, digest: actualDigest };
212
248
  }
249
+ async function verifyAudioResource(resource, occurrence, duration) {
250
+ if (resource.mediaKind !== "audio" || resource.sourceKind !== "local-file" || !resource.source || !resource.sourceDigest) {
251
+ throw new FfmpegRenderError("HEADLESS_RENDER_UNSUPPORTED", `resource is not registered local audio: ${resource.id}`);
252
+ }
253
+ const sourcePath = resolve(resource.source);
254
+ let details;
255
+ try {
256
+ details = await lstat(sourcePath);
257
+ }
258
+ catch (error) {
259
+ if (error.code === "ENOENT") {
260
+ throw new FfmpegRenderError("HEADLESS_RENDER_MEDIA_MISSING", `registered source is missing: ${sourcePath}`);
261
+ }
262
+ throw error;
263
+ }
264
+ if (!details.isFile() || details.isSymbolicLink()) {
265
+ throw new FfmpegRenderError("HEADLESS_RENDER_MEDIA_MISSING", `registered source is not a regular file: ${sourcePath}`);
266
+ }
267
+ const actualDigest = await digestFile(sourcePath);
268
+ if (actualDigest !== resource.sourceDigest) {
269
+ throw new FfmpegRenderError("HEADLESS_RENDER_MEDIA_CHANGED", `registered source changed: ${sourcePath}`);
270
+ }
271
+ if (!resource.metadata?.streams.some((stream) => stream.kind === "audio")) {
272
+ throw new FfmpegRenderError("HEADLESS_RENDER_UNSUPPORTED", `resource is missing audio metadata: ${resource.id}`);
273
+ }
274
+ const sourceStart = occurrence.sourceStartTime ? rationalSeconds(occurrence.sourceStartTime, `${occurrence.id}.sourceStartTime`) : 0;
275
+ const sourceDuration = resource.metadata ? rationalSeconds(resource.metadata.durationTime, `${resource.id}.durationTime`) : 0;
276
+ if (sourceStart < 0 || duration <= 0 || sourceStart + duration > sourceDuration + 1e-7) {
277
+ throw new FfmpegRenderError("HEADLESS_RENDER_UNSUPPORTED", `source audio range exceeds registered media: ${occurrence.id}`);
278
+ }
279
+ return { path: sourcePath, digest: actualDigest };
280
+ }
213
281
  async function assertSourcesUnchanged(model) {
214
282
  for (const identity of model.sourceIdentities) {
215
283
  let details;
@@ -229,11 +297,18 @@ function buildFfmpegArguments(model, stagingPath, fontFile) {
229
297
  const inputArguments = [];
230
298
  const videoLabels = [];
231
299
  const audioLabels = [];
232
- const fps = formatNumber(model.frameRate);
233
- for (const [index, occurrence] of model.occurrences.entries()) {
300
+ const musicLabels = [];
301
+ const fps = `${model.frameRate.value}/${model.frameRate.timescale}`;
302
+ const inputIndices = new Map();
303
+ for (const [index, occurrence] of [...model.occurrences, ...model.audioOccurrences].entries()) {
234
304
  const resource = model.resources.get(occurrence.mediaId);
235
305
  const inputPath = resolve(resource.source);
236
306
  inputArguments.push("-i", inputPath);
307
+ inputIndices.set(occurrence.id, index);
308
+ }
309
+ for (const occurrence of model.occurrences) {
310
+ const index = inputIndices.get(occurrence.id);
311
+ const resource = model.resources.get(occurrence.mediaId);
237
312
  const sourceStart = occurrence.sourceStartTime ? rationalSeconds(occurrence.sourceStartTime, `${occurrence.id}.sourceStartTime`) : 0;
238
313
  const duration = rationalSeconds(occurrence.durationTime, `${occurrence.id}.durationTime`);
239
314
  const videoInput = `[${index}:v]`;
@@ -248,12 +323,28 @@ function buildFfmpegArguments(model, stagingPath, fontFile) {
248
323
  audioLabels.push(`[${audioLabel}]`);
249
324
  }
250
325
  }
326
+ for (const occurrence of model.audioOccurrences) {
327
+ const index = inputIndices.get(occurrence.id);
328
+ const sourceStart = occurrence.sourceStartTime ? rationalSeconds(occurrence.sourceStartTime, `${occurrence.id}.sourceStartTime`) : 0;
329
+ const start = rationalSeconds(occurrence.startTime, `${occurrence.id}.startTime`);
330
+ const duration = rationalSeconds(occurrence.durationTime, `${occurrence.id}.durationTime`);
331
+ const gain = occurrence.gainDb ?? 0;
332
+ const delaySamples = Math.round(start * 48_000);
333
+ const audioLabel = `bed-audio${index}`;
334
+ filters.push(`[${index}:a]atrim=start=${formatNumber(sourceStart)}:duration=${formatNumber(duration)},asetpts=PTS-STARTPTS,aresample=48000,aformat=channel_layouts=mono,volume=${formatNumber(Math.pow(10, gain / 20))},adelay=${delaySamples}S:all=1,apad,atrim=duration=${formatNumber(model.duration)},asetpts=PTS-STARTPTS[${audioLabel}]`);
335
+ musicLabels.push(`[${audioLabel}]`);
336
+ }
251
337
  const transition = model.timeline.sequence.transitions?.[0];
252
338
  const videoBase = addVideoComposition(filters, videoLabels, model, transition);
253
- const videoOutput = addTitleOverlays(filters, videoBase, model, fontFile);
339
+ const videoWithTail = addBlackVideoTail(filters, videoBase, model.tailDuration);
340
+ const videoOutput = addTitleOverlays(filters, videoWithTail, model, fontFile);
254
341
  let audioOutput;
255
342
  if (audioLabels.length > 0)
256
343
  audioOutput = addAudioComposition(filters, audioLabels, model, transition);
344
+ if (musicLabels.length > 0) {
345
+ const inputs = [...(audioOutput ? [`[${audioOutput}]`] : []), ...musicLabels];
346
+ audioOutput = addAudioMix(filters, inputs, model.duration);
347
+ }
257
348
  const args = ["-hide_banner", "-loglevel", "error", "-nostdin", "-y", ...inputArguments, "-filter_complex", filters.join(";")];
258
349
  args.push("-map", `[${videoOutput}]`, "-c:v", "libx264", "-preset", "ultrafast", "-threads", "1", "-pix_fmt", "yuv420p", "-r", fps);
259
350
  if (audioOutput) {
@@ -262,6 +353,20 @@ function buildFfmpegArguments(model, stagingPath, fontFile) {
262
353
  args.push("-map_metadata", "-1", "-t", formatNumber(model.duration), "-movflags", "+faststart", stagingPath);
263
354
  return args;
264
355
  }
356
+ function addAudioMix(filters, labels, duration) {
357
+ if (labels.length === 1)
358
+ return labels[0].slice(1, -1);
359
+ const output = "audio-mix";
360
+ filters.push(`${labels.join("")}amix=inputs=${labels.length}:duration=longest:dropout_transition=0:normalize=0,apad,atrim=duration=${formatNumber(duration)},asetpts=PTS-STARTPTS[${output}]`);
361
+ return output;
362
+ }
363
+ function addBlackVideoTail(filters, input, duration) {
364
+ if (duration <= 1e-7)
365
+ return input;
366
+ const output = "video-black-tail";
367
+ filters.push(`[${input}]tpad=stop_mode=add:stop_duration=${formatNumber(duration)}:color=black[${output}]`);
368
+ return output;
369
+ }
265
370
  function addVideoComposition(filters, labels, model, transition) {
266
371
  if (labels.length === 1) {
267
372
  const output = "video-base";
@@ -345,16 +450,28 @@ function supportsLocalMedia(timeline) {
345
450
  });
346
451
  }
347
452
  function supportsStructuralEdits(timeline) {
453
+ const primaryOccurrences = timeline.sequence.occurrences.filter(isPrimaryVideoOccurrence);
348
454
  return timeline.sequence.storyElements.length === 0
349
455
  && timeline.sequence.markers.length === 0
350
456
  && timeline.sequence.captions.length === 0
351
- && timeline.sequence.occurrences.length > 0
352
- && timeline.sequence.occurrences.every((occurrence) => occurrence.track === 0
353
- && occurrence.role !== "audio"
354
- && occurrence.role !== "music"
355
- && occurrence.role !== "title"
457
+ && primaryOccurrences.length > 0
458
+ && primaryOccurrences.length + timeline.sequence.occurrences.filter(isIndependentAudioOccurrence).length === timeline.sequence.occurrences.length
459
+ && timeline.sequence.occurrences.every((occurrence) => (isPrimaryVideoOccurrence(occurrence) || isIndependentAudioOccurrence(occurrence))
356
460
  && occurrence.enabled !== false
357
- && !occurrence.attachedTo);
461
+ && !occurrence.attachedTo
462
+ && occurrence.fadeIn === undefined
463
+ && occurrence.fadeOut === undefined);
464
+ }
465
+ function supportsAudioMixing(timeline) {
466
+ return timeline.sequence.occurrences
467
+ .filter((occurrence) => occurrence.role === "audio" || occurrence.role === "music")
468
+ .every(isIndependentAudioOccurrence);
469
+ }
470
+ function isPrimaryVideoOccurrence(occurrence) {
471
+ return occurrence.track === 0 && (occurrence.role === undefined || occurrence.role === "video");
472
+ }
473
+ function isIndependentAudioOccurrence(occurrence) {
474
+ return occurrence.track > 0 && (occurrence.role === "audio" || occurrence.role === "music");
358
475
  }
359
476
  function supportsAudioGain(timeline) {
360
477
  return timeline.sequence.occurrences.every((occurrence) => occurrence.gainDb === undefined || Number.isFinite(occurrence.gainDb));
@@ -373,9 +490,10 @@ function supportsTitles(timeline) {
373
490
  }
374
491
  function supportsCrossDissolve(timeline) {
375
492
  const transitions = timeline.sequence.transitions ?? [];
493
+ const primaryCount = timeline.sequence.occurrences.filter(isPrimaryVideoOccurrence).length;
376
494
  return transitions.length <= 1
377
495
  && transitions.every((transition) => transition.kind === "cross-dissolve")
378
- && (transitions.length === 0 || timeline.sequence.occurrences.length === 2);
496
+ && (transitions.length === 0 || primaryCount === 2);
379
497
  }
380
498
  async function assertOutputPath(outputPath, overwrite, sourcePaths) {
381
499
  if (sourcePaths.includes(outputPath)) {
@@ -79,7 +79,7 @@ export class FfmpegRenderVerifier {
79
79
  const audioPassed = expectedAudio === undefined || (audio !== undefined
80
80
  && (expectedAudio.sampleRate === undefined || Number(audio.sample_rate) === expectedAudio.sampleRate)
81
81
  && (expectedAudio.channels === undefined || audio.channels === expectedAudio.channels));
82
- checks.push({ name: "audio-stream", passed: audioPassed, detail: "canonical audio stream presence and metadata are preserved", expected: expectedAudio ?? { kind: "none" }, observed: audio ?? { kind: "none" } });
82
+ checks.push({ name: "audio-stream", passed: audioPassed, detail: "timeline audio is present in the renderer's normalized format", expected: expectedAudio ?? { kind: "none" }, observed: audio ?? { kind: "none" } });
83
83
  checks.push({ name: "duration", passed: durationPassed, detail: `output duration is within ${tolerance} seconds of the canonical sequence`, expected: expectedDuration, observed: probe.format.duration });
84
84
  const artifact = {
85
85
  path: result.output.path,
@@ -119,7 +119,7 @@ function expectedAudioStream(plan) {
119
119
  const resource = occurrence.mediaId ? resources.get(occurrence.mediaId) : undefined;
120
120
  const stream = resource?.metadata?.streams.find((candidate) => candidate.kind === "audio");
121
121
  if (stream)
122
- return { sampleRate: stream.sampleRate, channels: stream.channels };
122
+ return { sampleRate: 48_000, channels: 1 };
123
123
  }
124
124
  return undefined;
125
125
  }
@@ -1,7 +1,7 @@
1
1
  import { execFile as execFileCallback, spawn } from "node:child_process";
2
2
  import { access } from "node:fs/promises";
3
3
  import { fileURLToPath } from "node:url";
4
- import { dirname, join } from "node:path";
4
+ import { dirname, join, resolve } from "node:path";
5
5
  import { promisify } from "node:util";
6
6
  import { FinalCutConnectionManager } from "../../../adapters/final-cut/typescript/src/index.js";
7
7
  const execFile = promisify(execFileCallback);
@@ -26,7 +26,7 @@ async function main() {
26
26
  if (command !== "help")
27
27
  process.exitCode = 1;
28
28
  }
29
- async function connectFinalCut(args) {
29
+ async function connectFinalCut(args, output = process.stdout) {
30
30
  if (args[0] !== "finalcut") {
31
31
  throw new Error("Usage: framekit connect finalcut [--development] [--json]");
32
32
  }
@@ -40,11 +40,13 @@ async function connectFinalCut(args) {
40
40
  const manager = new FinalCutConnectionManager({
41
41
  extensionSourcePath,
42
42
  restartAfterInstall: true,
43
+ installBeforeProbe: development,
43
44
  });
44
45
  const status = await manager.ensureConnected();
45
- printStatus(status, json);
46
+ printStatus(status, json, output);
46
47
  if (status.state !== "ready")
47
48
  process.exitCode = 1;
49
+ return status;
48
50
  }
49
51
  async function doctorFinalCut(args) {
50
52
  if (args[0] !== "finalcut")
@@ -54,24 +56,35 @@ async function doctorFinalCut(args) {
54
56
  if (status.state !== "ready")
55
57
  process.exitCode = 1;
56
58
  }
57
- async function runMcp(args) {
59
+ export async function runMcp(args, dependencies = {}) {
58
60
  const editorIndex = args.indexOf("--editor");
59
61
  const editor = editorIndex >= 0 ? args[editorIndex + 1] : "final-cut-live";
60
62
  const headless = args.includes("--headless");
63
+ const development = args.includes("--development");
61
64
  if (editor !== "final-cut-live" && editor !== "fixture") {
62
- throw new Error("Usage: framekit mcp [--editor final-cut-live|fixture] [--headless]");
65
+ throw new Error("Usage: framekit mcp [--editor final-cut-live|fixture] [--headless] [--development]");
63
66
  }
64
67
  if (headless && editor !== "final-cut-live") {
65
68
  throw new Error("Usage: --headless is only supported with --editor final-cut-live");
66
69
  }
70
+ if (development && editor !== "final-cut-live") {
71
+ throw new Error("Usage: --development is only supported with --editor final-cut-live");
72
+ }
73
+ if (development) {
74
+ const connect = dependencies.connectDevelopmentExtension ?? connectFinalCut;
75
+ const status = await connect(["finalcut", "--development", "--json"], dependencies.stderr ?? process.stderr);
76
+ if (status.state !== "ready")
77
+ return;
78
+ }
67
79
  const root = repoRoot();
68
80
  const compiled = fileURLToPath(import.meta.url).endsWith(".js");
69
81
  const entrypoint = join(root, `apps/mcp-server/src/main.${compiled ? "js" : "ts"}`);
70
- const child = spawn(process.execPath, [...(compiled ? [] : ["--import", "tsx"]), entrypoint], {
82
+ const child = (dependencies.spawnChild ?? spawn)(process.execPath, [...(compiled ? [] : ["--import", "tsx"]), entrypoint], {
71
83
  stdio: "inherit",
72
84
  env: {
73
85
  ...process.env,
74
86
  FRAMEKIT_EDITOR: editor,
87
+ ...(development ? { FRAMEKIT_REQUIRE_BUILD_ALIGNMENT: "1" } : {}),
75
88
  ...(headless
76
89
  ? {
77
90
  FRAMEKIT_FINAL_CUT_HEADLESS: "1",
@@ -97,19 +110,19 @@ async function buildDevelopmentExtension() {
97
110
  function repoRoot() {
98
111
  return join(dirname(fileURLToPath(import.meta.url)), "../../..");
99
112
  }
100
- function printStatus(status, json) {
113
+ function printStatus(status, json, output = process.stdout) {
101
114
  if (json) {
102
- process.stdout.write(`${JSON.stringify(status)}\n`);
115
+ output.write(`${JSON.stringify(status)}\n`);
103
116
  return;
104
117
  }
105
- process.stdout.write(`Framekit Final Cut: ${status.state}\n`);
106
- process.stdout.write(`Final Cut detected: ${status.editorDetected ? "yes" : "no"}\n`);
107
- process.stdout.write(`Extension: ${status.extensionInstalled ? status.extensionPath : "not installed"}\n`);
108
- process.stdout.write(`Socket: ${status.socketPath}\n`);
118
+ output.write(`Framekit Final Cut: ${status.state}\n`);
119
+ output.write(`Final Cut detected: ${status.editorDetected ? "yes" : "no"}\n`);
120
+ output.write(`Extension: ${status.extensionInstalled ? status.extensionPath : "not installed"}\n`);
121
+ output.write(`Socket: ${status.socketPath}\n`);
109
122
  if (status.identity)
110
- process.stdout.write(`Editor: ${status.identity.name} (${status.identity.backend})\n`);
123
+ output.write(`Editor: ${status.identity.name} (${status.identity.backend})\n`);
111
124
  if (status.lastError)
112
- process.stdout.write(`Reason: ${status.lastError.code}: ${status.lastError.message}\n`);
125
+ output.write(`Reason: ${status.lastError.code}: ${status.lastError.message}\n`);
113
126
  }
114
127
  function printHelp() {
115
128
  process.stdout.write([
@@ -117,14 +130,16 @@ function printHelp() {
117
130
  "",
118
131
  " framekit connect finalcut [--development] [--json]",
119
132
  " framekit doctor finalcut [--json]",
120
- " framekit mcp --editor final-cut-live [--headless]",
133
+ " framekit mcp --editor final-cut-live [--headless] [--development]",
121
134
  "",
122
135
  "Codex registration:",
123
136
  " codex mcp add framekit -- framekit mcp --editor final-cut-live --headless",
124
137
  "",
125
138
  ].join("\n"));
126
139
  }
127
- void main().catch((error) => {
128
- process.stderr.write(`${String(error)}\n`);
129
- process.exitCode = 1;
130
- });
140
+ if (process.argv[1] && fileURLToPath(import.meta.url) === resolve(process.argv[1])) {
141
+ void main().catch((error) => {
142
+ process.stderr.write(`${String(error)}\n`);
143
+ process.exitCode = 1;
144
+ });
145
+ }
@@ -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.1.18",
4
+ "commit": "cc0fc08ebc4ecf62897918d93a54dd35a7c73bf3"
5
+ }
@@ -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
+ }