@morshoto/framekit 0.1.11 → 0.1.13

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 (29) hide show
  1. package/README.md +1 -0
  2. package/dist-package/adapters/final-cut/typescript/src/analyzers.js +68 -5
  3. package/dist-package/adapters/final-cut/typescript/src/canonical-recovery.js +31 -0
  4. package/dist-package/adapters/final-cut/typescript/src/canonical-verification.js +16 -0
  5. package/dist-package/adapters/final-cut/typescript/src/canonical.js +978 -98
  6. package/dist-package/adapters/final-cut/typescript/src/fcpxml.js +26 -7
  7. package/dist-package/adapters/final-cut/typescript/src/index.js +3 -0
  8. package/dist-package/adapters/final-cut/typescript/src/library-inspection.js +2 -0
  9. package/dist-package/adapters/final-cut/typescript/src/native.js +321 -19
  10. package/dist-package/adapters/final-cut/typescript/src/shadow-mutation.js +71 -17
  11. package/dist-package/adapters/final-cut/typescript/src/sqlite-experiment.js +472 -0
  12. package/dist-package/adapters/final-cut/typescript/src/sqlite-materialization.js +230 -0
  13. package/dist-package/apps/mcp-server/src/headless-sessions.js +47 -4
  14. package/dist-package/apps/mcp-server/src/main.js +33 -1
  15. package/dist-package/apps/mcp-server/src/routing.js +17 -0
  16. package/dist-package/apps/mcp-server/src/server.js +87 -28
  17. package/dist-package/packages/runtime/src/application/media-analysis-service.js +52 -6
  18. package/dist-package/packages/runtime/src/context/context-engine.js +313 -8
  19. package/dist-package/packages/runtime/src/context/context-service.js +5 -2
  20. package/dist-package/packages/runtime/src/context/project-catalog.js +58 -2
  21. package/dist-package/packages/runtime/src/domain/incremental-sync.js +153 -0
  22. package/dist-package/packages/runtime/src/domain/index.js +1 -0
  23. package/dist-package/packages/runtime/src/editing/edit-service.js +8 -2
  24. package/dist-package/packages/runtime/src/runtime.js +5 -2
  25. package/dist-package/packages/runtime/src/skills/builtin.js +99 -8
  26. package/dist-package/packages/runtime/src/skills/runtime.js +1 -0
  27. package/dist-package/packages/runtime/src/timeline/editing-session.js +13 -0
  28. package/dist-package/packages/runtime/src/timeline/snapshot-diff.js +169 -10
  29. package/package.json +9 -5
@@ -3,7 +3,7 @@ import { ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
3
3
  import { resolve as resolvePath } from "node:path";
4
4
  import { z } from "zod";
5
5
  import { createCapabilityPreflight, resolveEditingIntent, serializeCapabilityUnavailableError, withCanonicalTimelineMode, withCapabilityFamilies, } from "../../../packages/runtime/src/index.js";
6
- import { NATIVE_MEDIA_IMPORT_DIRECTORY_ERROR_CODE, serializeFinalCutLibraryInspectionError, serializeNativeFinalCutMediaImportError, } from "../../../adapters/final-cut/typescript/src/index.js";
6
+ import { NATIVE_MEDIA_IMPORT_DIRECTORY_ERROR_CODE, serializeFinalCutLibraryInspectionError, serializeNativeFinalCutMediaImportError, serializeNativeFinalCutPartialMutationError, } from "../../../adapters/final-cut/typescript/src/index.js";
7
7
  import { BACKGROUND_ARTIFACT_WORKFLOW, EDITOR_FIRST_MCP_INSTRUCTIONS, resolveEditingRoute, } from "./routing.js";
8
8
  import { FRAMEKIT_BUILD_FINGERPRINT, FRAMEKIT_VERSION, } from "./version.js";
9
9
  import { EditingSessionRepository } from "./headless-sessions.js";
@@ -14,6 +14,14 @@ const revisionValueSchema = z.object({
14
14
  timestamp: z.string(),
15
15
  });
16
16
  const revisionSchema = revisionValueSchema.optional();
17
+ const contextTargetSchema = z.object({
18
+ projectId: z.string().min(1),
19
+ sequenceId: z.string().min(1),
20
+ }).strict();
21
+ const contextCursorSchema = z.object({
22
+ revision: revisionValueSchema,
23
+ target: contextTargetSchema.optional(),
24
+ }).strict();
17
25
  const rationalTimeSchema = z.object({
18
26
  value: z.string().regex(/^-?\d+$/),
19
27
  timescale: z.string().regex(/^\d+$/).refine((value) => Number(value) > 0),
@@ -702,6 +710,20 @@ function nativeMediaImportErrorResult(error) {
702
710
  }],
703
711
  };
704
712
  }
713
+ async function nativeMutationResult(action) {
714
+ try {
715
+ return jsonResult(await action());
716
+ }
717
+ catch (error) {
718
+ const serialized = serializeNativeFinalCutPartialMutationError(error);
719
+ if (!serialized)
720
+ throw error;
721
+ return {
722
+ isError: true,
723
+ content: [{ type: "text", text: JSON.stringify(serialized) }],
724
+ };
725
+ }
726
+ }
705
727
  function capabilityUnavailableErrorResult(error) {
706
728
  const serialized = serializeCapabilityUnavailableError(error);
707
729
  if (!serialized)
@@ -804,7 +826,9 @@ export function createMcpServer(runtime, options = {}) {
804
826
  runtime.registerBuiltinSkills();
805
827
  const server = new McpServer({ name: "framekit", version: FRAMEKIT_VERSION }, { instructions: EDITOR_FIRST_MCP_INSTRUCTIONS });
806
828
  const nativeTransitionAssets = new Map();
807
- const sessions = options.sessionDirectory ? new EditingSessionRepository(options.sessionDirectory) : undefined;
829
+ const sessions = options.sessionDirectory
830
+ ? new EditingSessionRepository(options.sessionDirectory, options.sessionChangeSource)
831
+ : undefined;
808
832
  const materializations = sessions && options.materializationDirectory
809
833
  ? new SessionMaterializationJobs(options.materializationDirectory, sessions, options.sessionMaterializationPublisher)
810
834
  : undefined;
@@ -1110,7 +1134,7 @@ export function createMcpServer(runtime, options = {}) {
1110
1134
  if (!options.nativeEditor)
1111
1135
  throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native writes are not configured");
1112
1136
  const operation = nativeEditSchema.parse(input);
1113
- return jsonResult(await options.nativeEditor.edit(operation, { signal: extra.signal }));
1137
+ return nativeMutationResult(() => options.nativeEditor.edit(operation, { signal: extra.signal }));
1114
1138
  });
1115
1139
  server.registerTool("editor.native.disposable.preview", {
1116
1140
  description: "Preview a disposable native Final Cut rename after canonical target, revision, and native preflight checks.",
@@ -1183,7 +1207,7 @@ export function createMcpServer(runtime, options = {}) {
1183
1207
  }, async ({ previewToken }, extra) => {
1184
1208
  if (!options.nativeEditor)
1185
1209
  throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native title placement is not configured");
1186
- return jsonResult(await options.nativeEditor.executeTitleAdd(previewToken, { signal: extra.signal }));
1210
+ return nativeMutationResult(() => options.nativeEditor.executeTitleAdd(previewToken, { signal: extra.signal }));
1187
1211
  });
1188
1212
  server.registerTool("editor.native.picture-in-picture.preview", {
1189
1213
  description: "Preview connecting selected Final Cut Browser video to a stable timeline occurrence with verified transform properties.",
@@ -1201,7 +1225,7 @@ export function createMcpServer(runtime, options = {}) {
1201
1225
  if (!options.nativeEditor)
1202
1226
  throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native picture-in-picture placement is not configured");
1203
1227
  await requireEditingRoute(runtime, options, "editor.native.picture-in-picture");
1204
- return jsonResult(await options.nativeEditor.executePictureInPicture(previewToken, { signal: extra.signal }));
1228
+ return nativeMutationResult(() => options.nativeEditor.executePictureInPicture(previewToken, { signal: extra.signal }));
1205
1229
  });
1206
1230
  server.registerTool("editor.native.transition.search", {
1207
1231
  description: "Search the visible Final Cut Transitions browser and return only transitions with stable native identities.",
@@ -1236,7 +1260,7 @@ export function createMcpServer(runtime, options = {}) {
1236
1260
  }, async ({ previewToken }, extra) => {
1237
1261
  if (!options.nativeEditor)
1238
1262
  throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native transition placement is not configured");
1239
- return jsonResult(await options.nativeEditor.executeTransitionAdd(previewToken, { signal: extra.signal }));
1263
+ return nativeMutationResult(() => options.nativeEditor.executeTransitionAdd(previewToken, { signal: extra.signal }));
1240
1264
  });
1241
1265
  server.registerTool("editor.native.mask.preview", {
1242
1266
  description: "Preview adding a bounded native Final Cut Draw Mask to one located occurrence without mutating the timeline.",
@@ -1252,7 +1276,7 @@ export function createMcpServer(runtime, options = {}) {
1252
1276
  }, async ({ previewToken }, extra) => {
1253
1277
  if (!options.nativeEditor)
1254
1278
  throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native masking is not configured");
1255
- return jsonResult(await options.nativeEditor.executeMask(previewToken, { signal: extra.signal }));
1279
+ return nativeMutationResult(() => options.nativeEditor.executeMask(previewToken, { signal: extra.signal }));
1256
1280
  });
1257
1281
  server.registerTool("editor.native.undo", {
1258
1282
  description: "Undo a previously accepted native Final Cut UI edit using Final Cut's native Undo command.",
@@ -1292,7 +1316,7 @@ export function createMcpServer(runtime, options = {}) {
1292
1316
  }, async ({ previewToken }, extra) => {
1293
1317
  if (!options.nativeEditor)
1294
1318
  throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native media append is not configured");
1295
- return jsonResult(await options.nativeEditor.executeAppendMedia(previewToken, { signal: extra.signal }));
1319
+ return nativeMutationResult(() => options.nativeEditor.executeAppendMedia(previewToken, { signal: extra.signal }));
1296
1320
  });
1297
1321
  server.registerTool("editor.native.media.append.selected.preview", {
1298
1322
  description: "Preview appending the currently selected Final Cut Browser media to the end of the active timeline.",
@@ -1308,7 +1332,7 @@ export function createMcpServer(runtime, options = {}) {
1308
1332
  }, async ({ previewToken }, extra) => {
1309
1333
  if (!options.nativeEditor)
1310
1334
  throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native selected-media append is not configured");
1311
- return jsonResult(await options.nativeEditor.executeAppendSelectedMedia(previewToken, { signal: extra.signal }));
1335
+ return nativeMutationResult(() => options.nativeEditor.executeAppendSelectedMedia(previewToken, { signal: extra.signal }));
1312
1336
  });
1313
1337
  server.registerTool("editor.native.media.insert.preview", {
1314
1338
  description: "Preview inserting the selected Final Cut Browser media at the current playhead.",
@@ -1324,7 +1348,7 @@ export function createMcpServer(runtime, options = {}) {
1324
1348
  }, async ({ previewToken }, extra) => {
1325
1349
  if (!options.nativeEditor)
1326
1350
  throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native media insert is not configured");
1327
- return jsonResult(await options.nativeEditor.executeInsertMedia(previewToken, { signal: extra.signal }));
1351
+ return nativeMutationResult(() => options.nativeEditor.executeInsertMedia(previewToken, { signal: extra.signal }));
1328
1352
  });
1329
1353
  server.registerTool("editor.native.timeline.locate", {
1330
1354
  description: "Locate matching occurrences of a live Browser media result in the active Final Cut timeline.",
@@ -1356,7 +1380,7 @@ export function createMcpServer(runtime, options = {}) {
1356
1380
  }, async ({ previewToken }, extra) => {
1357
1381
  if (!options.nativeEditor)
1358
1382
  throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native Blade is not configured");
1359
- return jsonResult(await options.nativeEditor.executeBlade(previewToken, { signal: extra.signal }));
1383
+ return nativeMutationResult(() => options.nativeEditor.executeBlade(previewToken, { signal: extra.signal }));
1360
1384
  });
1361
1385
  server.registerTool("editor.native.delete-range.preview", {
1362
1386
  description: "Preview a destructive ripple-delete of an explicit rational time range from the Final Cut primary storyline.",
@@ -1372,7 +1396,7 @@ export function createMcpServer(runtime, options = {}) {
1372
1396
  }, async ({ previewToken }, extra) => {
1373
1397
  if (!options.nativeEditor)
1374
1398
  throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native range deletion is not configured");
1375
- return jsonResult(await options.nativeEditor.executeDeleteRange(previewToken, { signal: extra.signal }));
1399
+ return nativeMutationResult(() => options.nativeEditor.executeDeleteRange(previewToken, { signal: extra.signal }));
1376
1400
  });
1377
1401
  server.registerTool("editor.native.trim-to-duration.preview", {
1378
1402
  description: "Preview a destructive operation that preserves the beginning of the Final Cut sequence and removes everything after the requested rational duration.",
@@ -1388,7 +1412,7 @@ export function createMcpServer(runtime, options = {}) {
1388
1412
  }, async ({ previewToken }, extra) => {
1389
1413
  if (!options.nativeEditor)
1390
1414
  throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native duration trimming is not configured");
1391
- return jsonResult(await options.nativeEditor.executeTrimToDuration(previewToken, { signal: extra.signal }));
1415
+ return nativeMutationResult(() => options.nativeEditor.executeTrimToDuration(previewToken, { signal: extra.signal }));
1392
1416
  });
1393
1417
  server.registerTool("artifact.publish.preview", {
1394
1418
  description: "Prepare a headed-only publish handoff for a verified FCPXML artifact without opening Final Cut.",
@@ -1548,14 +1572,21 @@ export function createMcpServer(runtime, options = {}) {
1548
1572
  server.registerTool("context.changes", {
1549
1573
  description: "Read incremental timeline, live-state, and native-asset changes after a context revision.",
1550
1574
  inputSchema: {
1551
- sequence: z.number().int().nonnegative(),
1575
+ cursor: contextCursorSchema.optional(),
1576
+ revision: revisionValueSchema.optional(),
1577
+ sequence: z.number().int().nonnegative().optional(),
1552
1578
  waitMs: z.number().int().min(0).max(30_000).optional(),
1553
1579
  },
1554
- }, async ({ sequence, waitMs }) => jsonResult(await runtime.contextChangesSince({
1555
- id: `rev-${sequence}`,
1556
- sequence,
1557
- timestamp: new Date(sequence).toISOString(),
1558
- }, waitMs ?? 0)));
1580
+ }, async ({ cursor, revision, sequence, waitMs }) => {
1581
+ const after = cursor ?? revision ?? (sequence === undefined ? undefined : {
1582
+ id: `rev-${sequence}`,
1583
+ sequence,
1584
+ timestamp: new Date(sequence).toISOString(),
1585
+ });
1586
+ if (!after)
1587
+ throw new Error("INVALID_CONTEXT_CURSOR: cursor, revision, or sequence is required");
1588
+ return jsonResult(await runtime.contextChangesSince(after, waitMs ?? 0));
1589
+ });
1559
1590
  server.registerTool("editor.live.inspect", {
1560
1591
  description: "Read observed live Final Cut state without requiring canonical timeline snapshot capability.",
1561
1592
  inputSchema: {},
@@ -1654,15 +1685,33 @@ export function createMcpServer(runtime, options = {}) {
1654
1685
  },
1655
1686
  }, async (query) => jsonResult(await runtime.listAssets(query)));
1656
1687
  server.registerTool("timeline.changes", {
1657
- description: "Return the canonical timeline diff since a previously observed revision.",
1658
- inputSchema: { sequence: z.number().int().nonnegative() },
1659
- }, async ({ sequence }) => {
1660
- const project = await runtime.inspectProject();
1661
- return jsonResult(await runtime.changesSince({
1662
- id: `rev-${sequence}`,
1663
- sequence,
1664
- timestamp: new Date(0 + sequence).toISOString(),
1665
- }));
1688
+ description: "Return ordered canonical timeline changes for one selected project and sequence.",
1689
+ inputSchema: {
1690
+ projectId: z.string().min(1).optional(),
1691
+ sequenceId: z.string().min(1).optional(),
1692
+ revision: revisionValueSchema.optional(),
1693
+ /** Legacy cursor retained for existing MCP clients. */
1694
+ sequence: z.number().int().nonnegative().optional(),
1695
+ },
1696
+ }, async ({ projectId, sequenceId, revision, sequence }) => {
1697
+ const project = projectId && sequenceId && revision
1698
+ ? undefined
1699
+ : await runtime.inspectProject();
1700
+ const from = revision ?? {
1701
+ id: `rev-${sequence ?? project.revision.sequence}`,
1702
+ sequence: sequence ?? project.revision.sequence,
1703
+ timestamp: new Date(sequence ?? project.revision.sequence).toISOString(),
1704
+ };
1705
+ const result = await runtime.timelineChangesSince({
1706
+ target: {
1707
+ projectId: projectId ?? project.projectId,
1708
+ sequenceId: sequenceId ?? project.timeline.id,
1709
+ },
1710
+ from,
1711
+ });
1712
+ return jsonResult(result.status === "ready" && result.timeline
1713
+ ? { ...result.timeline, ...result }
1714
+ : result);
1666
1715
  });
1667
1716
  server.registerTool("timeline.edit", {
1668
1717
  description: "Apply one supported edit after editing.route confirms the required capabilities; return read-after-write plus its diff.",
@@ -2115,6 +2164,15 @@ async function requireEditingRoute(runtime, options, operation) {
2115
2164
  }
2116
2165
  async function editingRouteContext(runtime, options) {
2117
2166
  const connection = await effectiveConnectionStatus(runtime, options);
2167
+ let nativeReadiness;
2168
+ if (options.nativeEditor && typeof options.nativeEditor.inspect === "function") {
2169
+ try {
2170
+ nativeReadiness = (await options.nativeEditor.inspect()).readiness;
2171
+ }
2172
+ catch {
2173
+ nativeReadiness = undefined;
2174
+ }
2175
+ }
2118
2176
  let editor;
2119
2177
  try {
2120
2178
  editor = await inspectMcpEditor(runtime, options);
@@ -2126,5 +2184,6 @@ async function editingRouteContext(runtime, options) {
2126
2184
  connection,
2127
2185
  ...(editor ? { editor } : {}),
2128
2186
  ...(options.nativeEditor ? { native: { ...options.nativeEditor.capabilities() } } : {}),
2187
+ ...(nativeReadiness ? { nativeReadiness } : {}),
2129
2188
  };
2130
2189
  }
@@ -1,3 +1,4 @@
1
+ import { sameMediaSourceIdentity } from "../domain/media.js";
1
2
  import { planRoughCut } from "../planning/rough-cut.js";
2
3
  import { bindSpeechAnalysis } from "../speech/analysis.js";
3
4
  import { parseRational } from "../timeline/rational-time.js";
@@ -45,7 +46,22 @@ export class MediaAnalysisService {
45
46
  const sourceStart = clip.sourceStart ?? 0;
46
47
  const requestedRange = { start: sourceStart, end: sourceStart + clip.duration };
47
48
  const analysis = await this.options.audioAnalyzer.analyze({ project, media }, requestedRange);
48
- const analyzedDurationSeconds = analysis.analyzedDurationSeconds ?? clip.duration;
49
+ validateAudioProvenance(analysis, {
50
+ media,
51
+ mediaId,
52
+ project,
53
+ provider: this.options.audioAnalyzer.descriptor,
54
+ requestedRange,
55
+ });
56
+ const measuredRange = analysis.measuredRange ?? {
57
+ start: requestedRange.start,
58
+ end: requestedRange.start + (analysis.analyzedDurationSeconds ?? clip.duration),
59
+ };
60
+ validateAudioRange(measuredRange, requestedRange, "measured audio range");
61
+ const analyzedDurationSeconds = analysis.analyzedDurationSeconds ?? measuredRange.end - measuredRange.start;
62
+ if (Math.abs(analyzedDurationSeconds - (measuredRange.end - measuredRange.start)) > 0.000001) {
63
+ throw new Error("ANALYSIS_INVALID: audio measured duration does not match its measured range");
64
+ }
49
65
  const valid = analysis.valid !== false
50
66
  && Number.isFinite(analysis.integratedLufs)
51
67
  && Number.isFinite(analysis.truePeakDb)
@@ -56,12 +72,9 @@ export class MediaAnalysisService {
56
72
  mediaId,
57
73
  occurrenceId,
58
74
  requestedRange,
59
- measuredRange: {
60
- start: 0,
61
- end: Number.isFinite(analyzedDurationSeconds) ? analyzedDurationSeconds : clip.duration,
62
- },
75
+ measuredRange,
63
76
  revision: project.revision,
64
- provider: this.options.audioAnalyzer.descriptor ?? { id: "framekit.audio", provider: "unknown" },
77
+ provider: analysis.provider ?? this.options.audioAnalyzer.descriptor ?? { id: "framekit.audio", provider: "unknown" },
65
78
  dialoguePresent: analysis.dialoguePresent
66
79
  ?? Boolean(media.speech?.words.some((word) => word.filler !== true)),
67
80
  integratedLufs: analysis.integratedLufs,
@@ -470,3 +483,36 @@ function findMedia(project, mediaId) {
470
483
  throw new Error(`MEDIA_NOT_FOUND: ${mediaId}`);
471
484
  return media;
472
485
  }
486
+ function validateAudioProvenance(analysis, expected) {
487
+ if (analysis.schemaVersion !== undefined && analysis.schemaVersion !== 1) {
488
+ throw new Error("ANALYSIS_INVALID: unsupported audio analysis schema version");
489
+ }
490
+ if (analysis.mediaId !== undefined && analysis.mediaId !== expected.mediaId) {
491
+ throw new Error("TARGET_MISMATCH: audio analysis media identity does not match the requested media");
492
+ }
493
+ if (analysis.sourceIdentity !== undefined
494
+ && !sameMediaSourceIdentity(analysis.sourceIdentity, sourceIdentityOf(expected.media))) {
495
+ throw new Error("TARGET_MISMATCH: audio analysis source identity does not match the requested media");
496
+ }
497
+ if (analysis.requestedRange !== undefined && !sameRange(analysis.requestedRange, expected.requestedRange)) {
498
+ throw new Error("ANALYSIS_INVALID: audio requested range does not match the runtime request");
499
+ }
500
+ if (analysis.revision !== undefined
501
+ && (analysis.revision.id !== expected.project.revision.id || analysis.revision.sequence !== expected.project.revision.sequence)) {
502
+ throw new Error("ANALYSIS_STALE: audio analysis revision does not match the inspected project");
503
+ }
504
+ if (analysis.provider !== undefined && expected.provider !== undefined
505
+ && !sameDescriptor(analysis.provider, expected.provider)) {
506
+ throw new Error("ANALYSIS_INVALID: audio provider identity does not match the configured analyzer");
507
+ }
508
+ }
509
+ function validateAudioRange(range, requested, label) {
510
+ if (!Number.isFinite(range.start) || !Number.isFinite(range.end)
511
+ || range.start < requested.start || range.end > requested.end || range.end <= range.start) {
512
+ throw new Error(`ANALYSIS_INVALID: ${label} must fit inside the requested occurrence range`);
513
+ }
514
+ }
515
+ function sameRange(left, right) {
516
+ return Math.abs(left.start - right.start) <= 0.000001
517
+ && Math.abs(left.end - right.end) <= 0.000001;
518
+ }