@morshoto/framekit 0.1.18 → 0.2.3
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.
- package/README.md +17 -12
- package/dist-package/adapters/final-cut/typescript/src/analyzers.d.ts +58 -0
- package/dist-package/adapters/final-cut/typescript/src/analyzers.js +52 -13
- package/dist-package/adapters/final-cut/typescript/src/assets.d.ts +24 -0
- package/dist-package/adapters/final-cut/typescript/src/background-export.d.ts +98 -0
- package/dist-package/adapters/final-cut/typescript/src/background-materialization.d.ts +47 -0
- package/dist-package/adapters/final-cut/typescript/src/background-materialization.js +8 -2
- package/dist-package/adapters/final-cut/typescript/src/canonical-recovery-guard.d.ts +32 -0
- package/dist-package/adapters/final-cut/typescript/src/canonical-recovery-guard.js +275 -0
- package/dist-package/adapters/final-cut/typescript/src/canonical-recovery.d.ts +22 -0
- package/dist-package/adapters/final-cut/typescript/src/canonical-verification.d.ts +11 -0
- package/dist-package/adapters/final-cut/typescript/src/canonical.d.ts +184 -0
- package/dist-package/adapters/final-cut/typescript/src/canonical.js +571 -78
- package/dist-package/adapters/final-cut/typescript/src/connection.d.ts +103 -0
- package/dist-package/adapters/final-cut/typescript/src/connection.js +6 -1
- package/dist-package/adapters/final-cut/typescript/src/disposable-native.d.ts +90 -0
- package/dist-package/adapters/final-cut/typescript/src/disposable-native.js +6 -0
- package/dist-package/adapters/final-cut/typescript/src/documents.d.ts +3 -0
- package/dist-package/adapters/final-cut/typescript/src/documents.js +3 -0
- package/dist-package/adapters/final-cut/typescript/src/experimental.d.ts +8 -0
- package/dist-package/adapters/final-cut/typescript/src/experimental.js +8 -0
- package/dist-package/adapters/final-cut/typescript/src/export.d.ts +125 -0
- package/dist-package/adapters/final-cut/typescript/src/fcpxml-console-experiment.d.ts +54 -0
- package/dist-package/adapters/final-cut/typescript/src/fcpxml.d.ts +75 -0
- package/dist-package/adapters/final-cut/typescript/src/fcpxml.js +28 -9
- package/dist-package/adapters/final-cut/typescript/src/index.d.ts +22 -0
- package/dist-package/adapters/final-cut/typescript/src/index.js +1 -7
- package/dist-package/adapters/final-cut/typescript/src/library-inspection.d.ts +101 -0
- package/dist-package/adapters/final-cut/typescript/src/live.d.ts +101 -0
- package/dist-package/adapters/final-cut/typescript/src/live.js +35 -2
- package/dist-package/adapters/final-cut/typescript/src/media.d.ts +12 -0
- package/dist-package/adapters/final-cut/typescript/src/native-operation.d.ts +6 -0
- package/dist-package/adapters/final-cut/typescript/src/native-recovery-inspection.d.ts +77 -0
- package/dist-package/adapters/final-cut/typescript/src/native-recovery-inspection.js +175 -0
- package/dist-package/adapters/final-cut/typescript/src/native-session.d.ts +130 -0
- package/dist-package/adapters/final-cut/typescript/src/native-session.js +11 -6
- package/dist-package/adapters/final-cut/typescript/src/native.d.ts +828 -0
- package/dist-package/adapters/final-cut/typescript/src/native.js +475 -189
- package/dist-package/adapters/final-cut/typescript/src/pasteboard-snapshot.d.ts +114 -0
- package/dist-package/adapters/final-cut/typescript/src/publish-readback.d.ts +26 -0
- package/dist-package/adapters/final-cut/typescript/src/publish-readback.js +19 -2
- package/dist-package/adapters/final-cut/typescript/src/publisher.d.ts +215 -0
- package/dist-package/adapters/final-cut/typescript/src/publisher.js +255 -14
- package/dist-package/adapters/final-cut/typescript/src/session.d.ts +43 -0
- package/dist-package/adapters/final-cut/typescript/src/session.js +43 -13
- package/dist-package/adapters/final-cut/typescript/src/shadow-mutation.d.ts +51 -0
- package/dist-package/adapters/final-cut/typescript/src/sqlite-experiment.d.ts +156 -0
- package/dist-package/adapters/final-cut/typescript/src/sqlite-inspection.d.ts +134 -0
- package/dist-package/adapters/final-cut/typescript/src/sqlite-materialization.d.ts +110 -0
- package/dist-package/adapters/final-cut/typescript/src/sqlite-wal-observation.d.ts +132 -0
- package/dist-package/adapters/final-cut/typescript/src/timeline-ir-fcpxml.d.ts +61 -0
- package/dist-package/adapters/final-cut/typescript/src/timeline-ir-fcpxml.js +31 -5
- package/dist-package/adapters/final-cut/typescript/src/unattended-editing.d.ts +54 -0
- package/dist-package/adapters/headless/typescript/src/audio-output.d.ts +3 -0
- package/dist-package/adapters/headless/typescript/src/audio-output.js +3 -0
- package/dist-package/adapters/headless/typescript/src/ffmpeg-media-probe.d.ts +11 -0
- package/dist-package/adapters/headless/typescript/src/ffmpeg-media-probe.js +26 -2
- package/dist-package/adapters/headless/typescript/src/ffmpeg-renderer.d.ts +25 -0
- package/dist-package/adapters/headless/typescript/src/ffmpeg-renderer.js +37 -14
- package/dist-package/adapters/headless/typescript/src/ffmpeg-verifier.d.ts +15 -0
- package/dist-package/adapters/headless/typescript/src/ffmpeg-verifier.js +9 -4
- package/dist-package/adapters/headless/typescript/src/index.d.ts +3 -0
- package/dist-package/apps/cli/src/dev-doctor.d.ts +25 -0
- package/dist-package/apps/cli/src/dev-doctor.js +198 -0
- package/dist-package/apps/cli/src/headless-projects.d.ts +3 -0
- package/dist-package/apps/cli/src/headless-projects.js +5 -0
- package/dist-package/apps/cli/src/main.d.ts +10 -0
- package/dist-package/apps/cli/src/main.js +42 -0
- package/dist-package/apps/mcp-server/runtime/ffmpeg-audio-backend.py +129 -0
- package/dist-package/apps/mcp-server/runtime/speech-analyzer-wrapper.mjs +54 -0
- package/dist-package/apps/mcp-server/runtime/whisper-speech-backend.py +271 -0
- package/dist-package/apps/mcp-server/src/build-alignment.d.ts +10 -0
- package/dist-package/apps/mcp-server/src/build-identity.d.ts +7 -0
- package/dist-package/apps/mcp-server/src/build-identity.json +2 -2
- package/dist-package/apps/mcp-server/src/canonical-native-snapshot.d.ts +8 -0
- package/dist-package/apps/mcp-server/src/canonical-native-snapshot.js +18 -0
- package/dist-package/apps/mcp-server/src/final-cut-runtime-config.d.ts +5 -0
- package/dist-package/apps/mcp-server/src/final-cut-runtime-config.js +3 -0
- package/dist-package/apps/mcp-server/src/headless-project-snapshot.d.ts +3 -0
- package/dist-package/apps/mcp-server/src/headless-sessions.d.ts +89 -0
- package/dist-package/apps/mcp-server/src/main.d.ts +1 -0
- package/dist-package/apps/mcp-server/src/main.js +24 -19
- package/dist-package/apps/mcp-server/src/materialization-jobs.d.ts +204 -0
- package/dist-package/apps/mcp-server/src/materialization-jobs.js +143 -10
- package/dist-package/apps/mcp-server/src/readback-policy.d.ts +18 -0
- package/dist-package/apps/mcp-server/src/routing.d.ts +90 -0
- package/dist-package/apps/mcp-server/src/routing.js +2 -0
- package/dist-package/apps/mcp-server/src/server.d.ts +75 -0
- package/dist-package/apps/mcp-server/src/server.js +813 -158
- package/dist-package/apps/mcp-server/src/tools/skills/catalog.d.ts +19 -0
- package/dist-package/apps/mcp-server/src/tools/skills/catalog.js +142 -0
- package/dist-package/apps/mcp-server/src/tools/skills/metadata.d.ts +37 -0
- package/dist-package/apps/mcp-server/src/tools/skills/metadata.js +71 -0
- package/dist-package/apps/mcp-server/src/tools/skills/register.d.ts +11 -0
- package/dist-package/apps/mcp-server/src/tools/skills/register.js +101 -0
- package/dist-package/apps/mcp-server/src/version.d.ts +4 -0
- package/dist-package/packages/headless-application/src/external-edit.d.ts +30 -0
- package/dist-package/packages/headless-application/src/external-edit.js +72 -0
- package/dist-package/packages/headless-application/src/headless-projects.d.ts +233 -0
- package/dist-package/{apps/mcp-server → packages/headless-application}/src/headless-projects.js +392 -59
- package/dist-package/packages/headless-application/src/index.d.ts +2 -0
- package/dist-package/packages/headless-application/src/index.js +2 -0
- package/dist-package/packages/runtime/src/application/duration-policy-service.d.ts +4 -0
- package/dist-package/packages/runtime/src/application/local-media.d.ts +46 -0
- package/dist-package/packages/runtime/src/application/media-analysis-service.d.ts +40 -0
- package/dist-package/packages/runtime/src/application/media-analysis-service.js +105 -15
- package/dist-package/packages/runtime/src/application/project-service.d.ts +35 -0
- package/dist-package/packages/runtime/src/application/project-service.js +5 -1
- package/dist-package/packages/runtime/src/application/project-store.d.ts +56 -0
- package/dist-package/packages/runtime/src/application/project-store.js +13 -36
- package/dist-package/packages/runtime/src/application/project-transactions.d.ts +51 -0
- package/dist-package/packages/runtime/src/application/runtime-options.d.ts +15 -0
- package/dist-package/packages/runtime/src/application/semantic-media-index-store.d.ts +28 -0
- package/dist-package/packages/runtime/src/application/transaction-store.d.ts +10 -0
- package/dist-package/packages/runtime/src/application/transaction-store.js +1 -1
- package/dist-package/packages/runtime/src/audio/analysis.d.ts +3 -0
- package/dist-package/packages/runtime/src/audio/analysis.js +95 -0
- package/dist-package/packages/runtime/src/audio/dialogue-normalization.d.ts +47 -0
- package/dist-package/packages/runtime/src/audio/noise-reduction.d.ts +34 -0
- package/dist-package/packages/runtime/src/capabilities.d.ts +45 -0
- package/dist-package/packages/runtime/src/capabilities.js +1 -1
- package/dist-package/packages/runtime/src/color-correction.d.ts +33 -0
- package/dist-package/packages/runtime/src/context/context-engine.d.ts +28 -0
- package/dist-package/packages/runtime/src/context/context-engine.js +22 -16
- package/dist-package/packages/runtime/src/context/context-service.d.ts +20 -0
- package/dist-package/packages/runtime/src/context/context-service.js +2 -2
- package/dist-package/packages/runtime/src/context/project-catalog.d.ts +12 -0
- package/dist-package/packages/runtime/src/context/revision.d.ts +2 -0
- package/dist-package/packages/runtime/src/domain/capabilities.d.ts +170 -0
- package/dist-package/packages/runtime/src/domain/context.d.ts +179 -0
- package/dist-package/packages/runtime/src/domain/diff.d.ts +104 -0
- package/dist-package/packages/runtime/src/domain/duration.d.ts +63 -0
- package/dist-package/packages/runtime/src/domain/editing.d.ts +227 -0
- package/dist-package/packages/runtime/src/domain/incremental-sync.d.ts +67 -0
- package/dist-package/packages/runtime/src/domain/index.d.ts +14 -0
- package/dist-package/packages/runtime/src/domain/media.d.ts +406 -0
- package/dist-package/packages/runtime/src/domain/ports.d.ts +62 -0
- package/dist-package/packages/runtime/src/domain/primitives.d.ts +21 -0
- package/dist-package/packages/runtime/src/domain/project.d.ts +119 -0
- package/dist-package/packages/runtime/src/domain/rough-cut.d.ts +27 -0
- package/dist-package/packages/runtime/src/domain/skills.d.ts +145 -0
- package/dist-package/packages/runtime/src/domain/timeline-target.d.ts +57 -0
- package/dist-package/packages/runtime/src/domain/timeline-target.js +19 -1
- package/dist-package/packages/runtime/src/domain/types.d.ts +5 -0
- package/dist-package/packages/runtime/src/domain/verification.d.ts +92 -0
- package/dist-package/packages/runtime/src/editing/dialogue-normalization-service.d.ts +18 -0
- package/dist-package/packages/runtime/src/editing/duration-policy.d.ts +3 -0
- package/dist-package/packages/runtime/src/editing/edit-service.d.ts +44 -0
- package/dist-package/packages/runtime/src/editing/edit-service.js +76 -10
- package/dist-package/packages/runtime/src/editing/filler-removal-service.d.ts +23 -0
- package/dist-package/packages/runtime/src/editing/intent.d.ts +97 -0
- package/dist-package/packages/runtime/src/editing/music-service.d.ts +9 -0
- package/dist-package/packages/runtime/src/index.d.ts +32 -0
- package/dist-package/packages/runtime/src/index.js +2 -0
- package/dist-package/packages/runtime/src/planning/rough-cut.d.ts +3 -0
- package/dist-package/packages/runtime/src/render/render-and-verify.d.ts +71 -0
- package/dist-package/packages/runtime/src/render/render-contract.d.ts +96 -0
- package/dist-package/packages/runtime/src/runtime.d.ts +85 -0
- package/dist-package/packages/runtime/src/runtime.js +16 -7
- package/dist-package/packages/runtime/src/skills/builtin.d.ts +2 -0
- package/dist-package/packages/runtime/src/skills/index.d.ts +3 -0
- package/dist-package/packages/runtime/src/skills/registry.d.ts +10 -0
- package/dist-package/packages/runtime/src/skills/requirements.d.ts +38 -0
- package/dist-package/packages/runtime/src/skills/runtime.d.ts +38 -0
- package/dist-package/packages/runtime/src/speech/analysis.d.ts +18 -0
- package/dist-package/packages/runtime/src/speech/analysis.js +67 -0
- package/dist-package/packages/runtime/src/speech/filler-detector.d.ts +49 -0
- package/dist-package/packages/runtime/src/speech/filler-removal.d.ts +37 -0
- package/dist-package/packages/runtime/src/speech/mapping.d.ts +56 -0
- package/dist-package/packages/runtime/src/speech/mapping.js +27 -4
- package/dist-package/packages/runtime/src/speech/safe-cut-resolver.d.ts +52 -0
- package/dist-package/packages/runtime/src/timeline/drift-reconciliation.d.ts +42 -0
- package/dist-package/packages/runtime/src/timeline/editing-session.d.ts +271 -0
- package/dist-package/packages/runtime/src/timeline/editing-session.js +48 -2
- package/dist-package/packages/runtime/src/timeline/fast-observation.d.ts +77 -0
- package/dist-package/packages/runtime/src/timeline/rational-time.d.ts +11 -0
- package/dist-package/packages/runtime/src/timeline/reorder-preview.d.ts +32 -0
- package/dist-package/packages/runtime/src/timeline/reorder-preview.js +202 -0
- package/dist-package/packages/runtime/src/timeline/snapshot-diff.d.ts +3 -0
- package/dist-package/packages/runtime/src/timeline/snapshot-diff.js +1 -0
- package/dist-package/packages/runtime/src/timeline/snapshot-digest.d.ts +3 -0
- package/dist-package/packages/runtime/src/timeline/snapshot-digest.js +1 -1
- package/dist-package/packages/runtime/src/verification/verification.d.ts +6 -0
- package/dist-package/packages/testkit/src/fixture-analyzers.d.ts +37 -0
- package/dist-package/packages/testkit/src/in-memory-editor.d.ts +55 -0
- package/dist-package/packages/testkit/src/in-memory-editor.js +3 -3
- package/dist-package/packages/testkit/src/index.d.ts +4 -0
- package/dist-package/packages/testkit/src/index.js +1 -0
- package/dist-package/packages/testkit/src/sender-lifecycle-fixture.d.ts +47 -0
- package/dist-package/packages/testkit/src/sender-lifecycle-fixture.js +192 -0
- package/dist-package/packages/testkit/src/skill-fixtures.d.ts +3 -0
- package/package.json +41 -14
|
@@ -1,16 +1,40 @@
|
|
|
1
1
|
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
|
|
2
2
|
import { ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
|
|
3
|
-
import {
|
|
3
|
+
import { createHash, randomUUID } from "node:crypto";
|
|
4
|
+
import { closeSync, constants, fstatSync, openSync, readFileSync } from "node:fs";
|
|
5
|
+
import { types as utilTypes } from "node:util";
|
|
6
|
+
import { isAbsolute, resolve as resolvePath } from "node:path";
|
|
4
7
|
import { z } from "zod/v3";
|
|
5
|
-
import { createCapabilityPreflight, resolveEditingIntent, serializeCapabilityUnavailableError, withCanonicalTimelineMode, withCapabilityFamilies, createTimelineIrFromProjectSnapshot, } from "../../../packages/runtime/src/index.js";
|
|
6
|
-
import { NATIVE_MEDIA_IMPORT_DIRECTORY_ERROR_CODE, serializeFinalCutLibraryInspectionError, serializeNativeFinalCutMediaImportError, serializeNativeFinalCutPartialMutationError, } from "../../../adapters/final-cut/typescript/src/index.js";
|
|
8
|
+
import { canonicalSnapshotDigest, createCapabilityPreflight, resolveEditingIntent, serializeCapabilityUnavailableError, withCanonicalTimelineMode, withCapabilityFamilies, createTimelineIrFromProjectSnapshot, } from "../../../packages/runtime/src/index.js";
|
|
9
|
+
import { NATIVE_MEDIA_IMPORT_DIRECTORY_ERROR_CODE, NativeFinalCutMediaImportError, serializeFinalCutLibraryInspectionError, serializeNativeFinalCutMediaImportError, nativeMediaSearchQueryError, FinalCutProjectPublisher, FinalCutNativeAutomationAdapter, disabledNativeFocusContext, serializeNativeFinalCutPartialMutationError, } from "../../../adapters/final-cut/typescript/src/index.js";
|
|
7
10
|
import { BACKGROUND_ARTIFACT_WORKFLOW, EDITING_ROUTE_EDIT_TYPES, EDITOR_FIRST_MCP_INSTRUCTIONS, HEADLESS_TIMELINE_EDIT_TYPES, HEADLESS_FIRST_MCP_INSTRUCTIONS, resolveEditingRoute, } from "./routing.js";
|
|
8
11
|
import { assessBuildAlignment } from "./build-alignment.js";
|
|
9
12
|
import { FRAMEKIT_BUILD_FINGERPRINT, FRAMEKIT_VERSION, } from "./version.js";
|
|
10
13
|
import { EditingSessionRepository } from "./headless-sessions.js";
|
|
11
14
|
import { SessionMaterializationJobs, } from "./materialization-jobs.js";
|
|
15
|
+
import { externalEditOperations, externalEditPlanDigest, verifyExternalEditExportable, } from "../../../packages/headless-application/src/index.js";
|
|
12
16
|
import { projectSnapshotFromTimelineIr } from "./headless-project-snapshot.js";
|
|
13
17
|
import { chooseTimelineReadback } from "./readback-policy.js";
|
|
18
|
+
import { registerSkillTools, skillPreviewResult } from "./tools/skills/register.js";
|
|
19
|
+
const builtInPublishExecute = FinalCutProjectPublisher.prototype.executePublishJob;
|
|
20
|
+
const builtInPublishGetJob = FinalCutProjectPublisher.prototype.getPublishJob;
|
|
21
|
+
const builtInPublishTrack = FinalCutProjectPublisher.prototype.trackNativeDispatch;
|
|
22
|
+
const builtInPublishPersist = Reflect.get(FinalCutProjectPublisher.prototype, "persistPublishJob");
|
|
23
|
+
const builtInNativeMethods = new Map(Reflect.ownKeys(FinalCutNativeAutomationAdapter.prototype)
|
|
24
|
+
.map((key) => [key, Object.getOwnPropertyDescriptor(FinalCutNativeAutomationAdapter.prototype, key)?.value]));
|
|
25
|
+
const builtInMapGet = Map.prototype.get;
|
|
26
|
+
const builtInMapSet = Map.prototype.set;
|
|
27
|
+
const builtInMapHas = Map.prototype.has;
|
|
28
|
+
// Target identities are opaque: reject blank values without rewriting the
|
|
29
|
+
// caller's approval before the adapter compares it with the observed target.
|
|
30
|
+
const nativeImportTargetIdentity = z.string().min(1).refine((value) => value.trim().length > 0);
|
|
31
|
+
const nativeImportTargetSchema = z.object({
|
|
32
|
+
libraryId: nativeImportTargetIdentity,
|
|
33
|
+
eventId: nativeImportTargetIdentity,
|
|
34
|
+
projectId: nativeImportTargetIdentity,
|
|
35
|
+
sequenceId: nativeImportTargetIdentity,
|
|
36
|
+
revision: nativeImportTargetIdentity,
|
|
37
|
+
});
|
|
14
38
|
const revisionValueSchema = z.object({
|
|
15
39
|
id: z.string(),
|
|
16
40
|
sequence: z.number().int().nonnegative(),
|
|
@@ -25,6 +49,8 @@ const timelineReadbackSchema = z.object({
|
|
|
25
49
|
sessionId: z.string().min(1).optional(),
|
|
26
50
|
requestedCanonical: z.boolean().optional().default(false),
|
|
27
51
|
finalVerification: z.boolean().optional().default(false),
|
|
52
|
+
confirmHeadedRead: z.boolean().optional(),
|
|
53
|
+
expectedTarget: contextTargetSchema.optional(),
|
|
28
54
|
}).strict();
|
|
29
55
|
const contextCursorSchema = z.object({
|
|
30
56
|
revision: revisionValueSchema,
|
|
@@ -55,6 +81,8 @@ const mediaIndexQuerySchema = z.object({
|
|
|
55
81
|
const timelineSemanticContextQuerySchema = z.object({
|
|
56
82
|
query: z.string().optional(),
|
|
57
83
|
occurrenceIds: z.array(z.string().min(1)).optional(),
|
|
84
|
+
confirmHeadedRead: z.boolean().optional(),
|
|
85
|
+
expectedTarget: contextTargetSchema.optional(),
|
|
58
86
|
}).strict();
|
|
59
87
|
const roughCutPlanSchema = mediaIndexQuerySchema.extend({
|
|
60
88
|
maxShots: z.number().int().positive().optional(),
|
|
@@ -149,7 +177,14 @@ const colorCorrectionSchema = z.object({
|
|
|
149
177
|
}),
|
|
150
178
|
baseRevision: revisionSchema,
|
|
151
179
|
});
|
|
152
|
-
const rippleDeleteSchema = z.object({
|
|
180
|
+
const rippleDeleteSchema = z.object({
|
|
181
|
+
type: z.literal("ripple-delete"),
|
|
182
|
+
timelineId: z.string().min(1),
|
|
183
|
+
// The editor validates this range against the active timeline and reports its actual bounds.
|
|
184
|
+
range: z.object({ start: z.number().finite(), end: z.number().finite() }),
|
|
185
|
+
reason: z.string().optional(),
|
|
186
|
+
baseRevision: revisionSchema,
|
|
187
|
+
});
|
|
153
188
|
const addMarkerSchema = z.object({ type: z.literal("add-marker"), timelineId: z.string().min(1), marker: markerSchema, baseRevision: revisionSchema });
|
|
154
189
|
const roughCutImportSchema = z.object({
|
|
155
190
|
type: z.literal("media.import"),
|
|
@@ -325,6 +360,7 @@ const artifactPublishInputSchema = z.object({
|
|
|
325
360
|
targetLibraryPath: z.string().trim().min(1),
|
|
326
361
|
transactionId: z.string().min(1),
|
|
327
362
|
confirm: z.boolean(),
|
|
363
|
+
confirmVerification: z.boolean().optional(),
|
|
328
364
|
}).strict();
|
|
329
365
|
const artifactTransactionInputSchema = z.object({
|
|
330
366
|
artifactPath: z.string().trim().min(1),
|
|
@@ -760,32 +796,6 @@ function isDirectoryMediaImportError(error) {
|
|
|
760
796
|
&& typeof guidance.previewTool === "string"
|
|
761
797
|
&& typeof guidance.executeTool === "string";
|
|
762
798
|
}
|
|
763
|
-
function skillErrorResult(error) {
|
|
764
|
-
const value = error && typeof error === "object" ? error : {};
|
|
765
|
-
const message = error instanceof Error ? error.message : String(error);
|
|
766
|
-
const code = error instanceof z.ZodError
|
|
767
|
-
? "SKILL_INPUT_INVALID"
|
|
768
|
-
: typeof value.code === "string" ? value.code : message.split(":", 1)[0] || "SKILL_ERROR";
|
|
769
|
-
return {
|
|
770
|
-
isError: true,
|
|
771
|
-
content: [{
|
|
772
|
-
type: "text",
|
|
773
|
-
text: JSON.stringify({
|
|
774
|
-
code,
|
|
775
|
-
message,
|
|
776
|
-
...(value.availability ? { availability: value.availability } : {}),
|
|
777
|
-
}),
|
|
778
|
-
}],
|
|
779
|
-
};
|
|
780
|
-
}
|
|
781
|
-
function skillPreviewResult(preview) {
|
|
782
|
-
const details = preview.plan.details ?? {};
|
|
783
|
-
return jsonResult({
|
|
784
|
-
...preview,
|
|
785
|
-
...details,
|
|
786
|
-
plan: { ...preview.plan, ...details },
|
|
787
|
-
});
|
|
788
|
-
}
|
|
789
799
|
function normalizeConnectionStatus(value) {
|
|
790
800
|
if (!value || typeof value !== "object")
|
|
791
801
|
return value;
|
|
@@ -839,6 +849,9 @@ function frameResult(value) {
|
|
|
839
849
|
};
|
|
840
850
|
}
|
|
841
851
|
export function createMcpServer(runtime, options = {}) {
|
|
852
|
+
// Inspect only inert descriptors before wrapping. Unknown providers remain
|
|
853
|
+
// guarded rather than being executed to determine whether dispatch is safe.
|
|
854
|
+
const builtinImportUnavailable = isBuiltinImportObservationUnavailable(options.nativeEditor);
|
|
842
855
|
runtime.registerBuiltinSkills();
|
|
843
856
|
if (options.requireBuildAlignment) {
|
|
844
857
|
const assertAlignment = () => assertRequiredBuildAlignment(runtime, options);
|
|
@@ -855,7 +868,7 @@ export function createMcpServer(runtime, options = {}) {
|
|
|
855
868
|
: {}),
|
|
856
869
|
...(options.projectPublisher
|
|
857
870
|
? {
|
|
858
|
-
projectPublisher: withBuildAlignmentGuard(options.projectPublisher, assertAlignment, ["isAvailable", "inspectReadiness", "executionMode", "getPublishJob"]),
|
|
871
|
+
projectPublisher: withBuildAlignmentGuard(options.projectPublisher, assertAlignment, ["isAvailable", "inspectReadiness", "executionMode", "getPublishJob", "loadPublishJob"]),
|
|
859
872
|
}
|
|
860
873
|
: {}),
|
|
861
874
|
...(options.videoExporter
|
|
@@ -863,13 +876,51 @@ export function createMcpServer(runtime, options = {}) {
|
|
|
863
876
|
: {}),
|
|
864
877
|
};
|
|
865
878
|
}
|
|
879
|
+
const publishRouteIsGuarded = Boolean(options.canonicalRecovery && options.projectPublisher);
|
|
880
|
+
if (options.canonicalRecovery) {
|
|
881
|
+
const recovery = options.canonicalRecovery;
|
|
882
|
+
options = {
|
|
883
|
+
...options,
|
|
884
|
+
...(options.nativeEditor
|
|
885
|
+
? { nativeEditor: withRecoveryCheckpointGuard(options.nativeEditor, recovery, ["capabilities", "inspect"], [
|
|
886
|
+
"edit", "undo", "executeBlade", "executeMask", "executeTitleAdd", "executeTransitionAdd",
|
|
887
|
+
"executeAppendMedia", "executeAppendSelectedMedia", "executeInsertMedia", "executeDeleteRange",
|
|
888
|
+
"executeTrimToDuration", "executePictureInPicture", "importMedia", "executeImportMediaDirectory",
|
|
889
|
+
"focusTimeline", "selectMedia", "selectOccurrence", "selectCanonicalOccurrence", "targetMedia",
|
|
890
|
+
"searchMedia", "searchMediaForCanonicalTarget", "searchTitles", "searchTransitions", "locateOccurrence", "locateOccurrenceForCanonicalTarget",
|
|
891
|
+
"previewBlade", "previewMask", "previewDeleteRange", "previewTrimToDuration", "previewAppendMedia",
|
|
892
|
+
"previewAppendSelectedMedia", "previewInsertMedia", "previewTitleAdd", "previewPictureInPicture", "previewTransitionAdd",
|
|
893
|
+
]) }
|
|
894
|
+
: {}),
|
|
895
|
+
...(options.disposableNative
|
|
896
|
+
? { disposableNative: withRecoveryCheckpointGuard(options.disposableNative, recovery, [], ["preview", "execute", "undo"], "disposable") }
|
|
897
|
+
: {}),
|
|
898
|
+
...(options.nativeOperationSession
|
|
899
|
+
? { nativeOperationSession: withRecoveryCheckpointGuard(options.nativeOperationSession, recovery, ["status", "cancel"]) }
|
|
900
|
+
: {}),
|
|
901
|
+
...(options.projectPublisher
|
|
902
|
+
? { projectPublisher: withPublishRecoveryGuard(options.projectPublisher, recovery, async (publisher, property) => {
|
|
903
|
+
if (property === "executePublishJob") {
|
|
904
|
+
if (publisher.isAvailable() && requiresHeadedPublishingRoute(publisher))
|
|
905
|
+
await requireEditingRoute(runtime, options, "timeline.publish.new-project");
|
|
906
|
+
}
|
|
907
|
+
else {
|
|
908
|
+
if (!publisher.isAvailable())
|
|
909
|
+
throw new Error("CAPABILITY_UNAVAILABLE: Final Cut project publishing requires FRAMEKIT_FCPXML_PATH, native writes, live project verification, and a target-binding provider");
|
|
910
|
+
if (requiresHeadedPublishingRoute(publisher))
|
|
911
|
+
await requireEditingRoute(runtime, options, "timeline.publish.new-project");
|
|
912
|
+
}
|
|
913
|
+
}) }
|
|
914
|
+
: {}),
|
|
915
|
+
};
|
|
916
|
+
}
|
|
866
917
|
const server = new McpServer({ name: "framekit", version: FRAMEKIT_VERSION }, { instructions: options.headlessProjects ? HEADLESS_FIRST_MCP_INSTRUCTIONS : EDITOR_FIRST_MCP_INSTRUCTIONS });
|
|
867
918
|
const nativeTransitionAssets = new Map();
|
|
868
919
|
const sessions = options.sessionDirectory
|
|
869
920
|
? new EditingSessionRepository(options.sessionDirectory, options.sessionChangeSource)
|
|
870
921
|
: undefined;
|
|
871
922
|
const materializations = sessions && options.materializationDirectory
|
|
872
|
-
? new SessionMaterializationJobs(options.materializationDirectory, sessions, options.sessionMaterializationPublisher)
|
|
923
|
+
? new SessionMaterializationJobs(options.materializationDirectory, sessions, options.sessionMaterializationPublisher, options.canonicalRecovery)
|
|
873
924
|
: undefined;
|
|
874
925
|
const requireSessions = () => {
|
|
875
926
|
if (!sessions)
|
|
@@ -982,7 +1033,11 @@ export function createMcpServer(runtime, options = {}) {
|
|
|
982
1033
|
server.registerTool("session.materialize.execute", {
|
|
983
1034
|
description: "Confirm, stage, checkpoint, and request publication of a versioned FCPXML project.",
|
|
984
1035
|
inputSchema: { sessionId: z.string().min(1), target: sessionMaterializationTargetSchema, confirm: z.boolean() },
|
|
985
|
-
}, async ({ sessionId, target, confirm }) => sessionResult(async () =>
|
|
1036
|
+
}, async ({ sessionId, target, confirm }) => sessionResult(async () => {
|
|
1037
|
+
if (options.sessionMaterializationPublisher)
|
|
1038
|
+
await options.canonicalRecovery?.assertClear();
|
|
1039
|
+
return requireMaterializations().execute(sessionId, target, confirm);
|
|
1040
|
+
}));
|
|
986
1041
|
server.registerTool("session.materialize.status", {
|
|
987
1042
|
description: "Inspect a persisted materialization job after completion, blockage, or server restart.",
|
|
988
1043
|
inputSchema: { jobId: z.string().min(1) },
|
|
@@ -990,7 +1045,11 @@ export function createMcpServer(runtime, options = {}) {
|
|
|
990
1045
|
server.registerTool("session.materialize.retry", {
|
|
991
1046
|
description: "Resume a retryable persisted materialization job with its verified immutable artifact.",
|
|
992
1047
|
inputSchema: { jobId: z.string().min(1) },
|
|
993
|
-
}, async ({ jobId }) => sessionResult(async () =>
|
|
1048
|
+
}, async ({ jobId }) => sessionResult(async () => {
|
|
1049
|
+
if (options.sessionMaterializationPublisher)
|
|
1050
|
+
await options.canonicalRecovery?.assertClear();
|
|
1051
|
+
return requireMaterializations().retry(jobId);
|
|
1052
|
+
}));
|
|
994
1053
|
server.registerTool("session.materialize.resync", {
|
|
995
1054
|
description: "Read the completed versioned handoff target and create a fresh editing-session baseline for continuation.",
|
|
996
1055
|
inputSchema: { jobId: z.string().min(1), sessionId: z.string().min(1) },
|
|
@@ -1003,71 +1062,107 @@ export function createMcpServer(runtime, options = {}) {
|
|
|
1003
1062
|
description: "Read native Final Cut handoff readiness without launching, activating, importing, or mutating Final Cut.",
|
|
1004
1063
|
inputSchema: { publishJobId: z.string().trim().min(1).optional() },
|
|
1005
1064
|
}, async ({ publishJobId }) => jsonResult(await inspectNativeHandoffReadiness(runtime, options, publishJobId)));
|
|
1006
|
-
server.registerTool("
|
|
1007
|
-
description: "
|
|
1065
|
+
server.registerTool("editor.native.recovery.evidence.inspect", {
|
|
1066
|
+
description: "Read point-in-time native reservation and sender evidence without changing state or proving receiver quiescence. Recovery eligibility is unavailable.",
|
|
1008
1067
|
inputSchema: {},
|
|
1009
|
-
}, async () => {
|
|
1010
|
-
|
|
1011
|
-
|
|
1012
|
-
|
|
1013
|
-
|
|
1014
|
-
|
|
1015
|
-
|
|
1016
|
-
|
|
1017
|
-
|
|
1018
|
-
|
|
1019
|
-
|
|
1020
|
-
|
|
1021
|
-
description: "Inspect one registered Framekit Skill version and its current capability availability.",
|
|
1022
|
-
inputSchema: { skill: z.string().min(1), version: z.string().min(1).optional() },
|
|
1023
|
-
}, async ({ skill, version }) => {
|
|
1068
|
+
}, async () => sessionResult(async () => {
|
|
1069
|
+
if (!options.canonicalRecovery?.inspectNativeRecoveryEvidence)
|
|
1070
|
+
throw new Error("CAPABILITY_UNAVAILABLE: native recovery evidence inspection is not configured");
|
|
1071
|
+
return options.canonicalRecovery.inspectNativeRecoveryEvidence();
|
|
1072
|
+
}));
|
|
1073
|
+
server.registerTool("editor.native.recovery.inspect", {
|
|
1074
|
+
description: "Inspect recovery checkpoint evidence in the configured state directory without contacting Final Cut or clearing the checkpoint.",
|
|
1075
|
+
inputSchema: {},
|
|
1076
|
+
}, async () => sessionResult(async () => {
|
|
1077
|
+
if (!options.canonicalRecovery)
|
|
1078
|
+
throw new Error("CAPABILITY_UNAVAILABLE: canonical recovery checkpoint inspection is not configured");
|
|
1079
|
+
let evidence;
|
|
1024
1080
|
try {
|
|
1025
|
-
|
|
1026
|
-
return jsonResult({ ...manifest, availability });
|
|
1081
|
+
evidence = await options.canonicalRecovery.inspectVersioned();
|
|
1027
1082
|
}
|
|
1028
1083
|
catch (error) {
|
|
1029
|
-
|
|
1084
|
+
const nativeReservation = await options.canonicalRecovery.inspectNativeReservation();
|
|
1085
|
+
if (!nativeReservation)
|
|
1086
|
+
throw error;
|
|
1087
|
+
return { status: "recovery-required", scope: "configured-state-directory", nativeReservation };
|
|
1030
1088
|
}
|
|
1031
|
-
|
|
1032
|
-
|
|
1033
|
-
|
|
1089
|
+
return evidence
|
|
1090
|
+
? { status: "recovery-required", scope: "configured-state-directory", ...evidence }
|
|
1091
|
+
: { status: "clear", scope: "configured-state-directory" };
|
|
1092
|
+
}));
|
|
1093
|
+
server.registerTool("editor.native.recovery.preview", {
|
|
1094
|
+
description: "Compare a separately authorized headed canonical read with one target-bound checkpoint. Confirmation alone does not establish authorization. Never clears the checkpoint or proves native operation quiescence.",
|
|
1034
1095
|
inputSchema: {
|
|
1035
|
-
|
|
1036
|
-
|
|
1037
|
-
|
|
1096
|
+
confirmHeadedRead: z.boolean().optional(),
|
|
1097
|
+
expectedTarget: contextTargetSchema.optional(),
|
|
1098
|
+
expectedCheckpointId: z.string().regex(/^[a-f0-9]{64}$/).optional(),
|
|
1038
1099
|
},
|
|
1039
|
-
}, async ({
|
|
1100
|
+
}, async ({ confirmHeadedRead, expectedTarget, expectedCheckpointId }) => {
|
|
1101
|
+
const operation = "editor.native.recovery.preview";
|
|
1102
|
+
if (!confirmHeadedRead || !expectedTarget || !expectedCheckpointId) {
|
|
1103
|
+
return mcpReadErrorResult("HEADED_READ_CONFIRMATION_REQUIRED", "recovery preview requires confirmation, target IDs, and the inspected checkpoint ID", operation);
|
|
1104
|
+
}
|
|
1105
|
+
if (!options.canonicalRecovery)
|
|
1106
|
+
return mcpReadErrorResult("CAPABILITY_UNAVAILABLE", "canonical recovery checkpoint inspection is not configured", operation);
|
|
1107
|
+
let evidence;
|
|
1040
1108
|
try {
|
|
1041
|
-
|
|
1042
|
-
const { baseRevision: _baseRevision, ...input } = skillArguments;
|
|
1043
|
-
return skillPreviewResult(await runtime.previewSkill({
|
|
1044
|
-
skillId: skill,
|
|
1045
|
-
...(version ? { version } : {}),
|
|
1046
|
-
baseRevision,
|
|
1047
|
-
input,
|
|
1048
|
-
}));
|
|
1109
|
+
evidence = await options.canonicalRecovery.inspectVersioned();
|
|
1049
1110
|
}
|
|
1050
1111
|
catch (error) {
|
|
1051
|
-
return
|
|
1112
|
+
return mcpReadErrorResult("FINAL_CUT_CANONICAL_RECOVERY_REQUIRED", error instanceof Error ? error.message : String(error), operation);
|
|
1113
|
+
}
|
|
1114
|
+
if (!evidence || evidence.checkpointId !== expectedCheckpointId)
|
|
1115
|
+
return mcpReadErrorResult("CHECKPOINT_MISMATCH", "recovery checkpoint is missing or changed", operation);
|
|
1116
|
+
if (evidence.checkpoint.projectId !== expectedTarget.projectId || evidence.checkpoint.sequenceId !== expectedTarget.sequenceId) {
|
|
1117
|
+
return mcpReadErrorResult("TARGET_MISMATCH", "requested target differs from the checkpoint", operation);
|
|
1118
|
+
}
|
|
1119
|
+
const passive = await inspectMcpEditor(runtime, options);
|
|
1120
|
+
if (passive.identity.backend !== "final-cut-native-canonical") {
|
|
1121
|
+
return mcpReadErrorResult("CAPABILITY_UNAVAILABLE", "recovery preview requires the canonical native provider", operation);
|
|
1052
1122
|
}
|
|
1053
|
-
});
|
|
1054
|
-
server.registerTool("skill.execute", {
|
|
1055
|
-
description: "Execute only a runtime-issued Skill preview token and return verification/rollback evidence.",
|
|
1056
|
-
inputSchema: {
|
|
1057
|
-
previewToken: z.string().min(1),
|
|
1058
|
-
},
|
|
1059
|
-
}, async ({ previewToken }) => {
|
|
1060
1123
|
try {
|
|
1061
|
-
return
|
|
1124
|
+
return await inspectCanonicalReadForMcp(runtime, options, operation, true, expectedTarget, async () => {
|
|
1125
|
+
const beforeLive = await runtime.inspectLiveEditor();
|
|
1126
|
+
if (!liveTargetMatches(beforeLive, expectedTarget) || !beforeLive.revision?.id || !Number.isSafeInteger(beforeLive.revision.sequence)) {
|
|
1127
|
+
throw new Error("STALE_CONTEXT: live target or revision is unavailable before recovery read");
|
|
1128
|
+
}
|
|
1129
|
+
const snapshot = await runtime.inspectProject();
|
|
1130
|
+
const afterLive = await runtime.inspectLiveEditor();
|
|
1131
|
+
if (!liveTargetMatches(afterLive, expectedTarget) || afterLive.revision?.id !== beforeLive.revision.id
|
|
1132
|
+
|| afterLive.revision?.sequence !== beforeLive.revision.sequence) {
|
|
1133
|
+
throw new Error("STALE_CONTEXT: live target or revision changed during recovery read");
|
|
1134
|
+
}
|
|
1135
|
+
if (snapshot.projectId !== expectedTarget.projectId || snapshot.timeline.id !== expectedTarget.sequenceId) {
|
|
1136
|
+
throw new Error("TARGET_MISMATCH: canonical snapshot differs from the checkpoint target");
|
|
1137
|
+
}
|
|
1138
|
+
const after = await options.canonicalRecovery.inspectVersioned();
|
|
1139
|
+
if (!after || after.checkpointId !== expectedCheckpointId)
|
|
1140
|
+
throw new Error("CHECKPOINT_MISMATCH: checkpoint changed during canonical read");
|
|
1141
|
+
const observedDigest = canonicalSnapshotDigest(snapshot);
|
|
1142
|
+
const comparison = evidence.checkpoint.expectedRestoreDigest === observedDigest
|
|
1143
|
+
? "matches-expected-restoration"
|
|
1144
|
+
: evidence.checkpoint.beforeDigest === observedDigest ? "matches-before" : "different";
|
|
1145
|
+
return { checkpointId: expectedCheckpointId, target: expectedTarget, observedRevision: snapshot.revision, observedLiveRevision: afterLive.revision, observedDigest, comparison, pointInTime: true, quiescence: "unproven", checkpointCleared: false };
|
|
1146
|
+
}, (result) => result.target);
|
|
1062
1147
|
}
|
|
1063
1148
|
catch (error) {
|
|
1064
|
-
|
|
1149
|
+
const message = error instanceof Error ? error.message : String(error);
|
|
1150
|
+
if (message.startsWith("STALE_CONTEXT:"))
|
|
1151
|
+
return mcpReadErrorResult("STALE_CONTEXT", message, operation);
|
|
1152
|
+
if (message.startsWith("TARGET_MISMATCH:"))
|
|
1153
|
+
return mcpReadErrorResult("TARGET_MISMATCH", message, operation);
|
|
1154
|
+
if (message.startsWith("CHECKPOINT_MISMATCH:"))
|
|
1155
|
+
return mcpReadErrorResult("CHECKPOINT_MISMATCH", message, operation);
|
|
1156
|
+
if (message.startsWith("FINAL_CUT_CANONICAL_RECOVERY_REQUIRED:"))
|
|
1157
|
+
return mcpReadErrorResult("FINAL_CUT_CANONICAL_RECOVERY_REQUIRED", message, operation);
|
|
1158
|
+
throw error;
|
|
1065
1159
|
}
|
|
1066
1160
|
});
|
|
1161
|
+
registerSkillTools(server, runtime);
|
|
1067
1162
|
server.registerTool("project.inspect", {
|
|
1068
1163
|
description: "Read a bound session baseline or perform an explicit canonical project resync before editing.route selects a capability-checked path.",
|
|
1069
1164
|
inputSchema: timelineReadbackSchema,
|
|
1070
|
-
}, async ({ sessionId, requestedCanonical, finalVerification }) => {
|
|
1165
|
+
}, async ({ sessionId, requestedCanonical, finalVerification, confirmHeadedRead, expectedTarget }) => {
|
|
1071
1166
|
if (sessionId) {
|
|
1072
1167
|
const { stored, decision } = await prepareSessionReadback(sessionId, requestedCanonical, finalVerification);
|
|
1073
1168
|
if (decision.route === "session" || decision.route === "fast-observation") {
|
|
@@ -1078,20 +1173,9 @@ export function createMcpServer(runtime, options = {}) {
|
|
|
1078
1173
|
snapshot: stored.document.base,
|
|
1079
1174
|
});
|
|
1080
1175
|
}
|
|
1081
|
-
|
|
1082
|
-
return jsonResult({ sessionId, readback: decision, ...resynced });
|
|
1083
|
-
}
|
|
1084
|
-
const inspected = await inspectMcpEditor(runtime, options);
|
|
1085
|
-
const capability = inspected.capabilities.families.canonicalDocument.read;
|
|
1086
|
-
if (!capability.available) {
|
|
1087
|
-
return capabilityErrorResult("project.inspect", "canonicalDocument.read", capability);
|
|
1088
|
-
}
|
|
1089
|
-
try {
|
|
1090
|
-
return jsonResult(await runtime.inspectProject());
|
|
1091
|
-
}
|
|
1092
|
-
catch (error) {
|
|
1093
|
-
return capabilityUnavailableErrorResult(error);
|
|
1176
|
+
return inspectCanonicalReadForMcp(runtime, options, "project.inspect", confirmHeadedRead, expectedTarget, async () => ({ sessionId, readback: decision, ...await canonicalResyncSession(sessionId, stored.document.provider?.id) }), (result) => ({ projectId: result.snapshot.projectId, sequenceId: result.snapshot.timeline.id }));
|
|
1094
1177
|
}
|
|
1178
|
+
return inspectCanonicalReadForMcp(runtime, options, "project.inspect", confirmHeadedRead, expectedTarget, () => runtime.inspectProject(), (result) => ({ projectId: result.projectId, sequenceId: result.timeline.id }));
|
|
1095
1179
|
});
|
|
1096
1180
|
server.registerTool("artifact.inspect", {
|
|
1097
1181
|
description: "Identify the managed FCPXML artifact used by the background artifact.edit and artifact.publish workflows.",
|
|
@@ -1153,6 +1237,49 @@ export function createMcpServer(runtime, options = {}) {
|
|
|
1153
1237
|
expectedRevision: revisionValueSchema.optional(),
|
|
1154
1238
|
},
|
|
1155
1239
|
}, async ({ projectId, sourcePath, expectedRevision }) => sessionResult(() => requireHeadlessProjects().registerMedia(projectId, sourcePath, expectedRevision)));
|
|
1240
|
+
server.registerTool("headless.media.search", {
|
|
1241
|
+
description: "Search one Framekit-owned project's registered media by ID, name, or source path without contacting Final Cut.",
|
|
1242
|
+
inputSchema: { projectId: z.string().min(1), query: z.string() },
|
|
1243
|
+
}, async ({ projectId, query }) => sessionResult(() => requireHeadlessProjects().searchMedia(projectId, query)));
|
|
1244
|
+
const externalEditSchema = z.object({
|
|
1245
|
+
schemaVersion: z.literal(1),
|
|
1246
|
+
clips: z.array(z.object({
|
|
1247
|
+
id: z.string().min(1), mediaId: z.string().min(1),
|
|
1248
|
+
sourceStartTime: rationalTimeSchema, durationTime: rationalTimeSchema,
|
|
1249
|
+
}).strict()).min(1),
|
|
1250
|
+
title: z.object({
|
|
1251
|
+
id: z.string().min(1), text: z.string().min(1),
|
|
1252
|
+
startTime: rationalTimeSchema, durationTime: rationalTimeSchema,
|
|
1253
|
+
}).strict(),
|
|
1254
|
+
music: z.object({
|
|
1255
|
+
id: z.string().min(1), mediaId: z.string().min(1), sourceStartTime: rationalTimeSchema,
|
|
1256
|
+
startTime: rationalTimeSchema, durationTime: rationalTimeSchema, gainDb: z.number().finite(),
|
|
1257
|
+
}).strict(),
|
|
1258
|
+
}).strict();
|
|
1259
|
+
server.registerTool("headless.edit-json.preview", {
|
|
1260
|
+
description: "Preview a versioned external edit against a Framekit project without mutation.",
|
|
1261
|
+
inputSchema: { projectId: z.string().min(1), sequenceId: z.string().min(1), expectedRevision: revisionValueSchema, edit: externalEditSchema },
|
|
1262
|
+
}, async ({ projectId, sequenceId, expectedRevision, edit }) => sessionResult(async () => {
|
|
1263
|
+
const service = requireHeadlessProjects();
|
|
1264
|
+
const project = await service.inspect(projectId);
|
|
1265
|
+
const operations = externalEditOperations(edit, project.timeline, expectedRevision);
|
|
1266
|
+
const preview = await service.previewEdit(projectId, { schemaVersion: 1, expectedRevision, operations }, sequenceId);
|
|
1267
|
+
verifyExternalEditExportable(preview.after.timeline);
|
|
1268
|
+
return { ...preview, planDigest: externalEditPlanDigest(preview.command) };
|
|
1269
|
+
}));
|
|
1270
|
+
server.registerTool("headless.edit-json.execute", {
|
|
1271
|
+
description: "Execute a versioned external edit against a Framekit project revision.",
|
|
1272
|
+
inputSchema: { projectId: z.string().min(1), sequenceId: z.string().min(1), expectedRevision: revisionValueSchema, edit: externalEditSchema, approved: z.literal(true), planDigest: z.string().regex(/^[a-f0-9]{64}$/) },
|
|
1273
|
+
}, async ({ projectId, sequenceId, expectedRevision, edit, planDigest }) => sessionResult(async () => {
|
|
1274
|
+
const service = requireHeadlessProjects();
|
|
1275
|
+
const project = await service.inspect(projectId);
|
|
1276
|
+
const operations = externalEditOperations(edit, project.timeline, expectedRevision);
|
|
1277
|
+
const preview = await service.previewEdit(projectId, { schemaVersion: 1, expectedRevision, operations }, sequenceId);
|
|
1278
|
+
verifyExternalEditExportable(preview.after.timeline);
|
|
1279
|
+
if (externalEditPlanDigest(preview.command) !== planDigest)
|
|
1280
|
+
throw new Error("EXTERNAL_EDIT_STALE_PREVIEW: approved edit does not match preview");
|
|
1281
|
+
return service.executeEdit(projectId, { schemaVersion: 1, expectedRevision, operations }, sequenceId);
|
|
1282
|
+
}));
|
|
1156
1283
|
server.registerTool("headless.edit.preview", {
|
|
1157
1284
|
description: "Preview supported Framekit Timeline IR edits without persisting or mutating the project.",
|
|
1158
1285
|
inputSchema: {
|
|
@@ -1179,6 +1306,10 @@ export function createMcpServer(runtime, options = {}) {
|
|
|
1179
1306
|
expectedRevision,
|
|
1180
1307
|
operations: operations,
|
|
1181
1308
|
}, sequenceId)));
|
|
1309
|
+
server.registerTool("headless.edit.undo", {
|
|
1310
|
+
description: "Restore the prior Framekit-owned timeline at the expected revision and independently verify the persisted result.",
|
|
1311
|
+
inputSchema: { projectId: z.string().min(1), sequenceId: z.string().min(1), undoId: z.string().min(1), expectedRevision: revisionValueSchema },
|
|
1312
|
+
}, async ({ projectId, sequenceId, undoId, expectedRevision }) => sessionResult(() => requireHeadlessProjects().undoEdit(projectId, sequenceId, undoId, expectedRevision)));
|
|
1182
1313
|
const headlessRenderParametersSchema = z.object({
|
|
1183
1314
|
outputPath: z.string().min(1),
|
|
1184
1315
|
format: z.enum(["mp4", "mov"]),
|
|
@@ -1236,6 +1367,10 @@ export function createMcpServer(runtime, options = {}) {
|
|
|
1236
1367
|
eventName: z.string().min(1).optional(),
|
|
1237
1368
|
materialization: z.enum(["versioned", "reuse-existing"]).optional(),
|
|
1238
1369
|
}).strict();
|
|
1370
|
+
server.registerTool("headless.fcpxml.export", {
|
|
1371
|
+
description: "Compile an exact Framekit-owned project revision to a new FCPXML artifact without contacting Final Cut.",
|
|
1372
|
+
inputSchema: { projectId: z.string().min(1), sequenceId: z.string().min(1), expectedRevision: revisionValueSchema, outputPath: z.string().min(1), target: headlessFcpxmlTargetSchema },
|
|
1373
|
+
}, async ({ projectId, sequenceId, expectedRevision, outputPath, target }) => sessionResult(() => requireHeadlessProjects().exportFcpxml(projectId, sequenceId, expectedRevision, outputPath, target)));
|
|
1239
1374
|
const headlessRoughCutRequestSchema = z.object({
|
|
1240
1375
|
projectId: z.string().min(1),
|
|
1241
1376
|
sequenceId: z.string().min(1),
|
|
@@ -1348,12 +1483,16 @@ export function createMcpServer(runtime, options = {}) {
|
|
|
1348
1483
|
: { available: false, error: { code: "CAPABILITY_UNAVAILABLE", message: "Final Cut native writes are not configured" } }));
|
|
1349
1484
|
server.registerTool("editor.native.media.import", {
|
|
1350
1485
|
description: "Import one local video or audio file into the active Final Cut Browser and wait for a stable media handle.",
|
|
1351
|
-
inputSchema: { path: z.string().min(1) },
|
|
1352
|
-
}, async ({ path }, extra) => {
|
|
1486
|
+
inputSchema: { path: z.string().min(1), expectedImportTarget: nativeImportTargetSchema.optional() },
|
|
1487
|
+
}, async ({ path, expectedImportTarget }, extra) => {
|
|
1353
1488
|
if (!options.nativeEditor)
|
|
1354
1489
|
throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native media import is not configured");
|
|
1490
|
+
if (builtinImportUnavailable) {
|
|
1491
|
+
await options.canonicalRecovery?.assertClear();
|
|
1492
|
+
return nativeMediaImportErrorResult(new NativeFinalCutMediaImportError("CAPABILITY_UNAVAILABLE", "native media import requires independently observed original source binding", { stage: "pre-import-browser-discovery", elapsedMs: 0, stageElapsedMs: 0, partialImportPossible: false }));
|
|
1493
|
+
}
|
|
1355
1494
|
try {
|
|
1356
|
-
return jsonResult(await options.nativeEditor.importMedia(path, { signal: extra.signal }));
|
|
1495
|
+
return jsonResult(await options.nativeEditor.importMedia(path, { signal: extra.signal, ...(expectedImportTarget ? { expectedImportTarget } : {}) }));
|
|
1357
1496
|
}
|
|
1358
1497
|
catch (error) {
|
|
1359
1498
|
return nativeMediaImportErrorResult(error);
|
|
@@ -1361,11 +1500,11 @@ export function createMcpServer(runtime, options = {}) {
|
|
|
1361
1500
|
});
|
|
1362
1501
|
server.registerTool("editor.native.media.directory.preview", {
|
|
1363
1502
|
description: "Enumerate supported top-level video files in a local directory without mutating Final Cut and return an expiring import preview.",
|
|
1364
|
-
inputSchema: { path: z.string().trim().min(1) },
|
|
1365
|
-
}, async ({ path }, extra) => {
|
|
1503
|
+
inputSchema: { path: z.string().trim().min(1), expectedImportTarget: nativeImportTargetSchema.optional() },
|
|
1504
|
+
}, async ({ path, expectedImportTarget }, extra) => {
|
|
1366
1505
|
if (!options.nativeEditor)
|
|
1367
1506
|
throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native media import is not configured");
|
|
1368
|
-
return jsonResult(await options.nativeEditor.previewImportMediaDirectory(path, { signal: extra.signal }));
|
|
1507
|
+
return jsonResult(await options.nativeEditor.previewImportMediaDirectory(path, { signal: extra.signal, ...(expectedImportTarget ? { expectedImportTarget } : {}) }));
|
|
1369
1508
|
});
|
|
1370
1509
|
server.registerTool("editor.native.media.directory.execute", {
|
|
1371
1510
|
description: "Import every file from a directory preview after explicit confirmation and return per-file stable media handles or failures.",
|
|
@@ -1373,6 +1512,10 @@ export function createMcpServer(runtime, options = {}) {
|
|
|
1373
1512
|
}, async ({ previewToken, confirm }, extra) => {
|
|
1374
1513
|
if (!options.nativeEditor)
|
|
1375
1514
|
throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native media import is not configured");
|
|
1515
|
+
if (builtinImportUnavailable) {
|
|
1516
|
+
await options.canonicalRecovery?.assertClear();
|
|
1517
|
+
return nativeMediaImportErrorResult(new NativeFinalCutMediaImportError("CAPABILITY_UNAVAILABLE", "native media import requires independently observed original source binding", { stage: "pre-import-browser-discovery", elapsedMs: 0, stageElapsedMs: 0, partialImportPossible: false }));
|
|
1518
|
+
}
|
|
1376
1519
|
return jsonResult(await options.nativeEditor.executeImportMediaDirectory(previewToken, confirm, { signal: extra.signal }));
|
|
1377
1520
|
});
|
|
1378
1521
|
server.registerTool("editor.native.edit", {
|
|
@@ -1535,11 +1678,18 @@ export function createMcpServer(runtime, options = {}) {
|
|
|
1535
1678
|
return jsonResult(await options.nativeEditor.undo(operationId, { signal: extra.signal }));
|
|
1536
1679
|
});
|
|
1537
1680
|
server.registerTool("editor.native.media.search", {
|
|
1538
|
-
description: "Search the active Final Cut Browser
|
|
1681
|
+
description: "Search the active Final Cut Browser by literal text and return short-lived media handles; wildcard operators are unsupported.",
|
|
1539
1682
|
inputSchema: { query: z.string().min(1) },
|
|
1540
1683
|
}, async ({ query }, extra) => {
|
|
1541
1684
|
if (!options.nativeEditor)
|
|
1542
1685
|
throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native media search is not configured");
|
|
1686
|
+
const queryError = nativeMediaSearchQueryError(query);
|
|
1687
|
+
if (queryError) {
|
|
1688
|
+
return {
|
|
1689
|
+
isError: true,
|
|
1690
|
+
content: [{ type: "text", text: JSON.stringify(queryError) }],
|
|
1691
|
+
};
|
|
1692
|
+
}
|
|
1543
1693
|
return jsonResult(await options.nativeEditor.searchMedia(query, { signal: extra.signal }));
|
|
1544
1694
|
});
|
|
1545
1695
|
server.registerTool("editor.native.media.select", {
|
|
@@ -1707,18 +1857,19 @@ export function createMcpServer(runtime, options = {}) {
|
|
|
1707
1857
|
return jsonResult({ ...job, ...(sourceProof ? { sourceProof } : {}) });
|
|
1708
1858
|
});
|
|
1709
1859
|
server.registerTool("artifact.publish.execute", {
|
|
1710
|
-
description: "
|
|
1860
|
+
description: "Dispatch a prepared native handoff with confirm=true; for a pending job separately authorize headed readback with confirmVerification=true. Dispatch does not prove project creation.",
|
|
1711
1861
|
inputSchema: {
|
|
1712
1862
|
jobId: z.string().trim().min(1),
|
|
1713
1863
|
confirm: z.literal(true),
|
|
1864
|
+
confirmVerification: z.boolean().optional(),
|
|
1714
1865
|
},
|
|
1715
|
-
}, async ({ jobId, confirm }) => {
|
|
1866
|
+
}, async ({ jobId, confirm, confirmVerification }) => {
|
|
1716
1867
|
if (!options.projectPublisher)
|
|
1717
1868
|
throw new Error("CAPABILITY_UNAVAILABLE: Final Cut project publishing requires FRAMEKIT_FCPXML_PATH and native writes");
|
|
1718
|
-
if (options.projectPublisher.isAvailable() && requiresHeadedPublishingRoute(options.projectPublisher)) {
|
|
1869
|
+
if (!publishRouteIsGuarded && options.projectPublisher.isAvailable() && requiresHeadedPublishingRoute(options.projectPublisher)) {
|
|
1719
1870
|
await requireEditingRoute(runtime, options, "timeline.publish.new-project");
|
|
1720
1871
|
}
|
|
1721
|
-
return jsonResult(await options.projectPublisher.executePublishJob(jobId, confirm));
|
|
1872
|
+
return jsonResult(await options.projectPublisher.executePublishJob(jobId, confirm, confirmVerification));
|
|
1722
1873
|
});
|
|
1723
1874
|
server.registerTool("artifact.publish.status", {
|
|
1724
1875
|
description: "Read the current state of a prepared artifact publish job without opening Final Cut or retrying it.",
|
|
@@ -1726,16 +1877,19 @@ export function createMcpServer(runtime, options = {}) {
|
|
|
1726
1877
|
}, async ({ jobId }) => {
|
|
1727
1878
|
if (!options.projectPublisher)
|
|
1728
1879
|
throw new Error("CAPABILITY_UNAVAILABLE: Final Cut project publishing requires FRAMEKIT_FCPXML_PATH and native writes");
|
|
1729
|
-
return jsonResult(options.projectPublisher.
|
|
1880
|
+
return jsonResult(await options.projectPublisher.loadPublishJob(jobId));
|
|
1730
1881
|
});
|
|
1731
1882
|
server.registerTool("artifact.publish", {
|
|
1732
|
-
description: "Experimental
|
|
1883
|
+
description: "Experimental direct import; explicitly confirm both creation and headed readback for this artifact. Dispatch alone does not prove project creation.",
|
|
1733
1884
|
inputSchema: artifactPublishInputSchema,
|
|
1734
|
-
}, async ({ artifactPath, targetLibraryPath, transactionId, confirm }) => {
|
|
1735
|
-
if (!options.projectPublisher
|
|
1885
|
+
}, async ({ artifactPath, targetLibraryPath, transactionId, confirm, confirmVerification }) => {
|
|
1886
|
+
if (!options.projectPublisher)
|
|
1736
1887
|
throw new Error("CAPABILITY_UNAVAILABLE: Final Cut project publishing requires FRAMEKIT_FCPXML_PATH, native writes, live project verification, and a target-binding provider");
|
|
1737
|
-
if (
|
|
1738
|
-
|
|
1888
|
+
if (!publishRouteIsGuarded) {
|
|
1889
|
+
if (!options.projectPublisher.isAvailable())
|
|
1890
|
+
throw new Error("CAPABILITY_UNAVAILABLE: Final Cut project publishing requires FRAMEKIT_FCPXML_PATH, native writes, live project verification, and a target-binding provider");
|
|
1891
|
+
if (requiresHeadedPublishingRoute(options.projectPublisher))
|
|
1892
|
+
await requireEditingRoute(runtime, options, "timeline.publish.new-project");
|
|
1739
1893
|
}
|
|
1740
1894
|
const transaction = runtime.getTransaction(transactionId);
|
|
1741
1895
|
if (transaction.target?.kind !== "artifact" || transaction.target.artifactPath !== artifactPath) {
|
|
@@ -1753,20 +1907,25 @@ export function createMcpServer(runtime, options = {}) {
|
|
|
1753
1907
|
artifactDigest: transaction.artifactDigest,
|
|
1754
1908
|
targetLibraryPath,
|
|
1755
1909
|
confirm,
|
|
1910
|
+
confirmVerification,
|
|
1756
1911
|
}));
|
|
1757
1912
|
});
|
|
1758
1913
|
server.registerTool("timeline.publish.new-project", {
|
|
1759
|
-
description: "Experimental
|
|
1914
|
+
description: "Experimental direct import of a verified artifact; explicitly confirm creation and headed readback before verified delivery.",
|
|
1760
1915
|
inputSchema: {
|
|
1761
1916
|
transactionId: z.string().min(1),
|
|
1762
1917
|
targetLibraryPath: z.string().trim().min(1),
|
|
1763
1918
|
confirm: z.literal(true),
|
|
1919
|
+
confirmVerification: z.boolean().optional(),
|
|
1764
1920
|
},
|
|
1765
|
-
}, async ({ transactionId, targetLibraryPath, confirm }) => {
|
|
1766
|
-
if (!options.projectPublisher
|
|
1921
|
+
}, async ({ transactionId, targetLibraryPath, confirm, confirmVerification }) => {
|
|
1922
|
+
if (!options.projectPublisher)
|
|
1767
1923
|
throw new Error("CAPABILITY_UNAVAILABLE: Final Cut project publishing requires FRAMEKIT_FCPXML_PATH, native writes, live project verification, and a target-binding provider");
|
|
1768
|
-
if (
|
|
1769
|
-
|
|
1924
|
+
if (!publishRouteIsGuarded) {
|
|
1925
|
+
if (!options.projectPublisher.isAvailable())
|
|
1926
|
+
throw new Error("CAPABILITY_UNAVAILABLE: Final Cut project publishing requires FRAMEKIT_FCPXML_PATH, native writes, live project verification, and a target-binding provider");
|
|
1927
|
+
if (requiresHeadedPublishingRoute(options.projectPublisher))
|
|
1928
|
+
await requireEditingRoute(runtime, options, "timeline.publish.new-project");
|
|
1770
1929
|
}
|
|
1771
1930
|
const transaction = runtime.getTransaction(transactionId);
|
|
1772
1931
|
if (transaction.target?.kind !== "artifact") {
|
|
@@ -1784,6 +1943,7 @@ export function createMcpServer(runtime, options = {}) {
|
|
|
1784
1943
|
artifactDigest: transaction.artifactDigest,
|
|
1785
1944
|
targetLibraryPath,
|
|
1786
1945
|
confirm,
|
|
1946
|
+
confirmVerification,
|
|
1787
1947
|
}));
|
|
1788
1948
|
});
|
|
1789
1949
|
server.registerTool("timeline.export", {
|
|
@@ -1848,9 +2008,28 @@ export function createMcpServer(runtime, options = {}) {
|
|
|
1848
2008
|
});
|
|
1849
2009
|
});
|
|
1850
2010
|
server.registerTool("context.inspect", {
|
|
1851
|
-
description: "Read
|
|
1852
|
-
inputSchema: {
|
|
1853
|
-
|
|
2011
|
+
description: "Read editing context passively, or explicitly confirm a headed read for the expected project and sequence.",
|
|
2012
|
+
inputSchema: {
|
|
2013
|
+
confirmHeadedRead: z.boolean().optional(),
|
|
2014
|
+
expectedTarget: contextTargetSchema.optional(),
|
|
2015
|
+
},
|
|
2016
|
+
}, async ({ confirmHeadedRead, expectedTarget }) => sessionResult(async () => {
|
|
2017
|
+
if (!confirmHeadedRead)
|
|
2018
|
+
return runtime.inspectContext({ probeCanonicalSnapshot: false });
|
|
2019
|
+
if (!expectedTarget)
|
|
2020
|
+
throw new Error("EXPECTED_TARGET_REQUIRED: headed context read requires a project and sequence");
|
|
2021
|
+
const matches = (live) => live.project?.id === expectedTarget.projectId && live.sequence?.id === expectedTarget.sequenceId;
|
|
2022
|
+
if (!matches(await runtime.inspectLiveEditor()))
|
|
2023
|
+
throw new Error("TARGET_MISMATCH: active project or sequence differs from expected target");
|
|
2024
|
+
const context = await runtime.inspectContext({ probeCanonicalSnapshot: true });
|
|
2025
|
+
if (!context.project)
|
|
2026
|
+
throw new Error("CAPABILITY_UNAVAILABLE: headed canonical context could not be read");
|
|
2027
|
+
if (!matches(await runtime.inspectLiveEditor()) ||
|
|
2028
|
+
context.project.projectId !== expectedTarget.projectId || context.project.timeline.id !== expectedTarget.sequenceId) {
|
|
2029
|
+
throw new Error("TARGET_MISMATCH: context target changed during headed read");
|
|
2030
|
+
}
|
|
2031
|
+
return context;
|
|
2032
|
+
}));
|
|
1854
2033
|
server.registerTool("context.changes", {
|
|
1855
2034
|
description: "Read incremental timeline, live-state, and native-asset changes after a context revision.",
|
|
1856
2035
|
inputSchema: {
|
|
@@ -1899,7 +2078,7 @@ export function createMcpServer(runtime, options = {}) {
|
|
|
1899
2078
|
server.registerTool("timeline.inspect", {
|
|
1900
2079
|
description: "Read a bound session baseline or perform an explicit canonical timeline resync after canonical capability checks.",
|
|
1901
2080
|
inputSchema: timelineReadbackSchema,
|
|
1902
|
-
}, async ({ sessionId, requestedCanonical, finalVerification }) => {
|
|
2081
|
+
}, async ({ sessionId, requestedCanonical, finalVerification, confirmHeadedRead, expectedTarget }) => {
|
|
1903
2082
|
if (sessionId) {
|
|
1904
2083
|
const { stored, decision } = await prepareSessionReadback(sessionId, requestedCanonical, finalVerification);
|
|
1905
2084
|
if (decision.route === "session" || decision.route === "fast-observation") {
|
|
@@ -1910,41 +2089,19 @@ export function createMcpServer(runtime, options = {}) {
|
|
|
1910
2089
|
timeline: stored.document.base,
|
|
1911
2090
|
});
|
|
1912
2091
|
}
|
|
1913
|
-
|
|
1914
|
-
|
|
1915
|
-
sessionId,
|
|
1916
|
-
|
|
1917
|
-
snapshot: resynced.snapshot.timeline,
|
|
1918
|
-
session: resynced.session,
|
|
1919
|
-
});
|
|
1920
|
-
}
|
|
1921
|
-
const inspected = await inspectMcpEditor(runtime, options);
|
|
1922
|
-
const capability = inspected.capabilities.families.canonicalDocument.read;
|
|
1923
|
-
if (!capability.available) {
|
|
1924
|
-
return capabilityErrorResult("timeline.inspect", "canonicalDocument.read", capability);
|
|
1925
|
-
}
|
|
1926
|
-
try {
|
|
1927
|
-
return jsonResult(await runtime.inspectTimeline());
|
|
1928
|
-
}
|
|
1929
|
-
catch (error) {
|
|
1930
|
-
return capabilityUnavailableErrorResult(error);
|
|
2092
|
+
return inspectCanonicalReadForMcp(runtime, options, "timeline.inspect", confirmHeadedRead, expectedTarget, async () => {
|
|
2093
|
+
const resynced = await canonicalResyncSession(sessionId, stored.document.provider?.id);
|
|
2094
|
+
return { sessionId, readback: decision, snapshot: resynced.snapshot.timeline, session: resynced.session };
|
|
2095
|
+
}, (result) => ({ sequenceId: result.snapshot.id }));
|
|
1931
2096
|
}
|
|
2097
|
+
return inspectCanonicalReadForMcp(runtime, options, "timeline.inspect", confirmHeadedRead, expectedTarget, () => runtime.inspectTimeline(), (result) => ({ sequenceId: result.id }));
|
|
1932
2098
|
});
|
|
1933
2099
|
server.registerTool("timeline.semantic.inspect", {
|
|
1934
2100
|
description: "Enrich timeline occurrences with source-range-bound semantic speech, visual, and metadata context without mutating the timeline.",
|
|
1935
2101
|
inputSchema: timelineSemanticContextQuerySchema.shape,
|
|
1936
2102
|
}, async (query) => {
|
|
1937
|
-
const
|
|
1938
|
-
|
|
1939
|
-
if (!capability.available) {
|
|
1940
|
-
return capabilityErrorResult("timeline.semantic.inspect", "canonicalDocument.read", capability);
|
|
1941
|
-
}
|
|
1942
|
-
try {
|
|
1943
|
-
return jsonResult(await runtime.inspectTimelineSemanticContext(query));
|
|
1944
|
-
}
|
|
1945
|
-
catch (error) {
|
|
1946
|
-
return capabilityUnavailableErrorResult(error);
|
|
1947
|
-
}
|
|
2103
|
+
const { confirmHeadedRead, expectedTarget, ...contextQuery } = query;
|
|
2104
|
+
return inspectCanonicalReadForMcp(runtime, options, "timeline.semantic.inspect", confirmHeadedRead, expectedTarget, () => runtime.inspectTimelineSemanticContext(contextQuery), (result) => ({ sequenceId: result.timelineId }));
|
|
1948
2105
|
});
|
|
1949
2106
|
server.registerTool("timeline.frame.capture", {
|
|
1950
2107
|
description: "Capture an image at an exact timeline position with project, sequence, clip, and optional visual-analysis metadata.",
|
|
@@ -2026,6 +2183,18 @@ export function createMcpServer(runtime, options = {}) {
|
|
|
2026
2183
|
sequence: z.number().int().nonnegative().optional(),
|
|
2027
2184
|
},
|
|
2028
2185
|
}, async ({ projectId, sequenceId, revision, sequence }) => {
|
|
2186
|
+
if (!(projectId && sequenceId && revision)) {
|
|
2187
|
+
const inspected = await inspectMcpEditor(runtime, options);
|
|
2188
|
+
const capability = inspected.capabilities.families.canonicalDocument.read;
|
|
2189
|
+
if (!capability.available)
|
|
2190
|
+
return capabilityErrorResult("timeline.changes", "canonicalDocument.read", capability);
|
|
2191
|
+
if (capability.evidenceTier === "headed-native") {
|
|
2192
|
+
return capabilityErrorResult("timeline.changes", "canonicalDocument.read", {
|
|
2193
|
+
available: false, backend: capability.backend, guarantee: "none",
|
|
2194
|
+
unavailableReason: "canonical timeline changes require an explicitly authorized headed read",
|
|
2195
|
+
});
|
|
2196
|
+
}
|
|
2197
|
+
}
|
|
2029
2198
|
const project = projectId && sequenceId && revision
|
|
2030
2199
|
? undefined
|
|
2031
2200
|
: await runtime.inspectProject();
|
|
@@ -2402,8 +2571,52 @@ async function effectiveConnectionStatus(runtime, options) {
|
|
|
2402
2571
|
});
|
|
2403
2572
|
}
|
|
2404
2573
|
}
|
|
2405
|
-
async function
|
|
2406
|
-
const
|
|
2574
|
+
async function inspectCanonicalReadForMcp(runtime, options, operation, confirmHeadedRead, expectedTarget, read, targetOf) {
|
|
2575
|
+
const passive = await inspectMcpEditor(runtime, options);
|
|
2576
|
+
const headed = passive.identity.backend === "final-cut-native-canonical";
|
|
2577
|
+
if (headed && (!confirmHeadedRead || !expectedTarget)) {
|
|
2578
|
+
return mcpReadErrorResult("HEADED_READ_CONFIRMATION_REQUIRED", `${operation} requires confirmHeadedRead and expectedTarget projectId and sequenceId before exporting a canonical snapshot`, operation);
|
|
2579
|
+
}
|
|
2580
|
+
if (headed && expectedTarget) {
|
|
2581
|
+
const before = await runtime.inspectLiveEditor();
|
|
2582
|
+
if (!liveTargetMatches(before, expectedTarget)) {
|
|
2583
|
+
return mcpReadErrorResult("TARGET_MISMATCH", `${operation} active project or sequence differs from expectedTarget`, operation);
|
|
2584
|
+
}
|
|
2585
|
+
}
|
|
2586
|
+
return runtime.withCanonicalReadScope(async () => {
|
|
2587
|
+
const inspected = await inspectMcpEditor(runtime, options, true);
|
|
2588
|
+
const capability = inspected.capabilities.families.canonicalDocument.read;
|
|
2589
|
+
if (!capability.available)
|
|
2590
|
+
return capabilityErrorResult(operation, "canonicalDocument.read", capability);
|
|
2591
|
+
try {
|
|
2592
|
+
const result = await read();
|
|
2593
|
+
if (headed && expectedTarget) {
|
|
2594
|
+
const live = await runtime.inspectLiveEditor();
|
|
2595
|
+
const returnedTarget = targetOf(result);
|
|
2596
|
+
if (!liveTargetMatches(live, expectedTarget)
|
|
2597
|
+
|| (returnedTarget.projectId !== undefined && returnedTarget.projectId !== expectedTarget.projectId)
|
|
2598
|
+
|| (returnedTarget.sequenceId !== undefined && returnedTarget.sequenceId !== expectedTarget.sequenceId)) {
|
|
2599
|
+
return mcpReadErrorResult("TARGET_MISMATCH", `${operation} result or active target changed during the headed read`, operation);
|
|
2600
|
+
}
|
|
2601
|
+
}
|
|
2602
|
+
return jsonResult(result);
|
|
2603
|
+
}
|
|
2604
|
+
catch (error) {
|
|
2605
|
+
return capabilityUnavailableErrorResult(error);
|
|
2606
|
+
}
|
|
2607
|
+
});
|
|
2608
|
+
}
|
|
2609
|
+
function liveTargetMatches(live, target) {
|
|
2610
|
+
return live.project?.id === target.projectId && live.sequence?.id === target.sequenceId;
|
|
2611
|
+
}
|
|
2612
|
+
function mcpReadErrorResult(code, message, operation) {
|
|
2613
|
+
return {
|
|
2614
|
+
isError: true,
|
|
2615
|
+
content: [{ type: "text", text: JSON.stringify({ code, message, operation }) }],
|
|
2616
|
+
};
|
|
2617
|
+
}
|
|
2618
|
+
async function inspectMcpEditor(runtime, options, probeCanonicalSnapshot = false) {
|
|
2619
|
+
const inspected = await runtime.inspectEditor({ probeCanonicalSnapshot });
|
|
2407
2620
|
const fingerprint = options.buildFingerprint ?? FRAMEKIT_BUILD_FINGERPRINT;
|
|
2408
2621
|
const buildAlignment = assessBuildAlignment(fingerprint, inspected.identity.buildFingerprint, options.validationCommit);
|
|
2409
2622
|
if (options.requireBuildAlignment && buildAlignment.status !== "matched") {
|
|
@@ -2428,6 +2641,7 @@ async function inspectMcpEditor(runtime, options) {
|
|
|
2428
2641
|
...inspected.capabilities.editor,
|
|
2429
2642
|
artifactPublish: publishingAvailable,
|
|
2430
2643
|
artifactPublishMode: publishingMode,
|
|
2644
|
+
...(publishingAvailable ? { artifactPublishDispatchGuarantee: "requested-unverified" } : {}),
|
|
2431
2645
|
...(publishingAvailable ? {} : { timelinePublishNewProject: false }),
|
|
2432
2646
|
videoExport: exportAvailable,
|
|
2433
2647
|
backgroundRender: backgroundExportAvailable,
|
|
@@ -2462,6 +2676,7 @@ async function inspectMcpEditor(runtime, options) {
|
|
|
2462
2676
|
},
|
|
2463
2677
|
publishing: publishingAvailable,
|
|
2464
2678
|
publishingBackend: publishingMode === "background-capable" ? "fcpxml-document-open" : "fcpxml-publisher",
|
|
2679
|
+
publishingGuarantee: "native-verified",
|
|
2465
2680
|
export: exportAvailable,
|
|
2466
2681
|
exportBackend: "final-cut-native-export",
|
|
2467
2682
|
backgroundExport: {
|
|
@@ -2497,7 +2712,7 @@ async function inspectMcpEditor(runtime, options) {
|
|
|
2497
2712
|
}),
|
|
2498
2713
|
fingerprint,
|
|
2499
2714
|
buildAlignment,
|
|
2500
|
-
nativeHandoffReadiness: createNativeHandoffReadiness(options.projectPublisher, buildAlignment),
|
|
2715
|
+
nativeHandoffReadiness: await createNativeHandoffReadiness(options.projectPublisher, buildAlignment),
|
|
2501
2716
|
},
|
|
2502
2717
|
...(native ? { native } : {}),
|
|
2503
2718
|
};
|
|
@@ -2506,7 +2721,7 @@ async function inspectNativeHandoffReadiness(runtime, options, publishJobId) {
|
|
|
2506
2721
|
const fingerprint = options.buildFingerprint ?? FRAMEKIT_BUILD_FINGERPRINT;
|
|
2507
2722
|
let extensionFingerprint;
|
|
2508
2723
|
try {
|
|
2509
|
-
extensionFingerprint = (await runtime.inspectEditor()).identity.buildFingerprint;
|
|
2724
|
+
extensionFingerprint = (await runtime.inspectEditor({ probeCanonicalSnapshot: false })).identity.buildFingerprint;
|
|
2510
2725
|
}
|
|
2511
2726
|
catch {
|
|
2512
2727
|
const status = await connectionStatus(options).catch(() => undefined);
|
|
@@ -2515,7 +2730,7 @@ async function inspectNativeHandoffReadiness(runtime, options, publishJobId) {
|
|
|
2515
2730
|
const buildAlignment = assessBuildAlignment(fingerprint, extensionFingerprint, options.validationCommit);
|
|
2516
2731
|
return createNativeHandoffReadiness(options.projectPublisher, buildAlignment, publishJobId);
|
|
2517
2732
|
}
|
|
2518
|
-
function createNativeHandoffReadiness(publisher, buildAlignment, publishJobId) {
|
|
2733
|
+
async function createNativeHandoffReadiness(publisher, buildAlignment, publishJobId) {
|
|
2519
2734
|
const publisherReadiness = inspectProjectPublisherReadiness(publisher);
|
|
2520
2735
|
const reasons = [...publisherReadiness.reasons];
|
|
2521
2736
|
if (buildAlignment.status !== "matched") {
|
|
@@ -2537,15 +2752,36 @@ function createNativeHandoffReadiness(publisher, buildAlignment, publishJobId) {
|
|
|
2537
2752
|
}
|
|
2538
2753
|
else {
|
|
2539
2754
|
try {
|
|
2540
|
-
const job = publisher.
|
|
2755
|
+
const job = typeof publisher.loadPublishJob === "function"
|
|
2756
|
+
? await publisher.loadPublishJob(publishJobId)
|
|
2757
|
+
: publisher.getPublishJob(publishJobId);
|
|
2541
2758
|
publish = { jobId: job.jobId, state: job.state };
|
|
2542
2759
|
const resultTarget = job.result?.createdTarget;
|
|
2543
2760
|
const targetMatches = job.createdTarget
|
|
2544
2761
|
&& resultTarget
|
|
2545
|
-
&& job.createdTarget
|
|
2546
|
-
&& job.createdTarget.sequenceId === resultTarget.sequenceId;
|
|
2762
|
+
&& nativeTargetIdentityMatches(job.createdTarget, resultTarget);
|
|
2547
2763
|
if (job.state === "verified" && job.result?.verified === true && targetMatches) {
|
|
2548
|
-
|
|
2764
|
+
if (typeof publisher.verifyCreatedTarget === "function") {
|
|
2765
|
+
try {
|
|
2766
|
+
const reboundTarget = await publisher.verifyCreatedTarget(job.jobId);
|
|
2767
|
+
if (!nativeTargetIdentityMatches(resultTarget, reboundTarget)) {
|
|
2768
|
+
throw new Error("persisted target identity changed during live rebind");
|
|
2769
|
+
}
|
|
2770
|
+
verifiedTarget = reboundTarget;
|
|
2771
|
+
}
|
|
2772
|
+
catch (error) {
|
|
2773
|
+
reasons.push({
|
|
2774
|
+
code: "FINAL_CUT_PUBLISH_TARGET_REBIND_FAILED",
|
|
2775
|
+
message: `Publish job ${job.jobId} no longer matches the live native target: ${error instanceof Error ? error.message : String(error)}`,
|
|
2776
|
+
});
|
|
2777
|
+
}
|
|
2778
|
+
}
|
|
2779
|
+
else {
|
|
2780
|
+
reasons.push({
|
|
2781
|
+
code: "FINAL_CUT_PUBLISH_TARGET_REBIND_UNAVAILABLE",
|
|
2782
|
+
message: `Publish job ${job.jobId} cannot be rebound because the publisher cannot revalidate the native library and active target`,
|
|
2783
|
+
});
|
|
2784
|
+
}
|
|
2549
2785
|
}
|
|
2550
2786
|
else {
|
|
2551
2787
|
reasons.push({
|
|
@@ -2578,6 +2814,13 @@ function createNativeHandoffReadiness(publisher, buildAlignment, publishJobId) {
|
|
|
2578
2814
|
...(ready && verifiedTarget ? { createdTarget: verifiedTarget } : {}),
|
|
2579
2815
|
};
|
|
2580
2816
|
}
|
|
2817
|
+
function nativeTargetIdentityMatches(left, right) {
|
|
2818
|
+
return left.kind === right.kind
|
|
2819
|
+
&& left.projectId === right.projectId
|
|
2820
|
+
&& left.sequenceId === right.sequenceId
|
|
2821
|
+
&& left.libraryId === right.libraryId
|
|
2822
|
+
&& left.eventId === right.eventId;
|
|
2823
|
+
}
|
|
2581
2824
|
function inspectProjectPublisherReadiness(publisher) {
|
|
2582
2825
|
if (!publisher) {
|
|
2583
2826
|
return {
|
|
@@ -2603,13 +2846,425 @@ function inspectProjectPublisherReadiness(publisher) {
|
|
|
2603
2846
|
};
|
|
2604
2847
|
}
|
|
2605
2848
|
async function assertRequiredBuildAlignment(runtime, options) {
|
|
2606
|
-
const inspected = await runtime.inspectEditor();
|
|
2849
|
+
const inspected = await runtime.inspectEditor({ probeCanonicalSnapshot: false });
|
|
2607
2850
|
const fingerprint = options.buildFingerprint ?? FRAMEKIT_BUILD_FINGERPRINT;
|
|
2608
2851
|
const alignment = assessBuildAlignment(fingerprint, inspected.identity.buildFingerprint, options.validationCommit);
|
|
2609
2852
|
if (alignment.status !== "matched") {
|
|
2610
2853
|
throw new Error(`FRAMEKIT_BUILD_ALIGNMENT_MISMATCH: ${alignment.message}`);
|
|
2611
2854
|
}
|
|
2612
2855
|
}
|
|
2856
|
+
function withPublishRecoveryGuard(provider, recovery, validateRoute) {
|
|
2857
|
+
const allowed = new Set(["isAvailable", "inspectReadiness", "executionMode", "getPublishJob", "loadPublishJob", "preparePublish"]);
|
|
2858
|
+
let current;
|
|
2859
|
+
return new Proxy(provider, {
|
|
2860
|
+
get(target, property) {
|
|
2861
|
+
if (property !== "executePublishJob" && property !== "publishNewProject") {
|
|
2862
|
+
const value = Reflect.get(target, property, target);
|
|
2863
|
+
if (typeof value !== "function")
|
|
2864
|
+
return value;
|
|
2865
|
+
if (allowed.has(property))
|
|
2866
|
+
return value.bind(target);
|
|
2867
|
+
return async (...args) => {
|
|
2868
|
+
await recovery.assertClear();
|
|
2869
|
+
return Reflect.apply(value, target, args);
|
|
2870
|
+
};
|
|
2871
|
+
}
|
|
2872
|
+
return async (...args) => {
|
|
2873
|
+
const jobId = property === "executePublishJob" && typeof args[0] === "string" ? args[0] : undefined;
|
|
2874
|
+
let provenDisabled = false;
|
|
2875
|
+
let entry = current;
|
|
2876
|
+
const acquiringReservation = !entry;
|
|
2877
|
+
if (entry) {
|
|
2878
|
+
if (entry.active || !jobId || entry.jobId !== jobId || args[1] !== true || args[2] !== true) {
|
|
2879
|
+
throw new Error("FINAL_CUT_CANONICAL_RECOVERY_REQUIRED: publish reservation only permits verification of its settled pending job");
|
|
2880
|
+
}
|
|
2881
|
+
entry.active = true;
|
|
2882
|
+
try {
|
|
2883
|
+
const observed = await recovery.inspectNativeReservation();
|
|
2884
|
+
if (observed?.reservationId !== entry.reservation.reservationId) {
|
|
2885
|
+
throw new Error("FINAL_CUT_CANONICAL_RECOVERY_REQUIRED: publish reservation changed before verification");
|
|
2886
|
+
}
|
|
2887
|
+
const getJob = Reflect.get(target, "getPublishJob", target);
|
|
2888
|
+
const job = getJob.call(target, jobId);
|
|
2889
|
+
if (job?.state !== "verification-pending" || (job.jobId !== undefined && job.jobId !== jobId)) {
|
|
2890
|
+
throw new Error("FINAL_CUT_CANONICAL_RECOVERY_REQUIRED: publish job changed before verification");
|
|
2891
|
+
}
|
|
2892
|
+
}
|
|
2893
|
+
catch (error) {
|
|
2894
|
+
entry.active = false;
|
|
2895
|
+
throw error;
|
|
2896
|
+
}
|
|
2897
|
+
}
|
|
2898
|
+
else {
|
|
2899
|
+
// Never invoke caller-controlled job lookup before the reservation.
|
|
2900
|
+
const job = jobId ? inertBuiltInPublishJob(target, jobId) : undefined;
|
|
2901
|
+
if (job && job.jobId !== jobId)
|
|
2902
|
+
throw new Error("FINAL_CUT_CANONICAL_RECOVERY_REQUIRED: publish job identity mismatch");
|
|
2903
|
+
const pending = job?.state === "verification-pending";
|
|
2904
|
+
const operation = jobId
|
|
2905
|
+
? `native.publish.${createHash("sha256").update(jobId).digest("hex")}`
|
|
2906
|
+
: "native.publish.direct";
|
|
2907
|
+
const path = job?.targetLibraryPath;
|
|
2908
|
+
const digest = job?.artifactDigest;
|
|
2909
|
+
const context = jobId && !pending && /^publish-job-[a-z0-9-]{1,80}$/.test(jobId)
|
|
2910
|
+
&& typeof path === "string" && path.length <= 4096 && isAbsolute(path) && path.endsWith(".fcpbundle")
|
|
2911
|
+
&& typeof digest === "string" && /^[a-f0-9]{64}$/.test(digest)
|
|
2912
|
+
? Object.freeze({ kind: "publish", jobId, dispatchId: randomUUID(), requestedTarget: Object.freeze({ libraryPath: path }),
|
|
2913
|
+
artifactDigest: digest, executorIdentity: null, nativeQuiescence: "unproven" })
|
|
2914
|
+
: undefined;
|
|
2915
|
+
// Capture primitives and data descriptors before awaiting the guard;
|
|
2916
|
+
// its implementation must not rewrite the evidence used for rechecks.
|
|
2917
|
+
const configurationKeys = ["enabled", "liveState", "readCanonicalSnapshot", "sourcePath", "publishJobsDirectory"];
|
|
2918
|
+
const requestedConfiguration = job ? configurationKeys.map((key) => Object.getOwnPropertyDescriptor(target, key)) : undefined;
|
|
2919
|
+
const requestedIntent = context && job ? { libraryPath: context.requestedTarget.libraryPath,
|
|
2920
|
+
artifactDigest: context.artifactDigest, state: job.state } : undefined;
|
|
2921
|
+
const reservation = await recovery.beginNative(operation, context);
|
|
2922
|
+
entry = { jobId, reservation, active: true, dispatched: pending, needsBinding: !context,
|
|
2923
|
+
...(requestedIntent ? { requestedIntent } : {}), ...(requestedConfiguration ? { requestedConfiguration } : {}) };
|
|
2924
|
+
current = entry;
|
|
2925
|
+
}
|
|
2926
|
+
try {
|
|
2927
|
+
if (acquiringReservation && jobId && entry.requestedIntent) {
|
|
2928
|
+
const currentJob = inertBuiltInPublishJob(target, jobId);
|
|
2929
|
+
const expected = entry.requestedIntent;
|
|
2930
|
+
if (!currentJob || currentJob.jobId !== jobId || currentJob.targetLibraryPath !== expected.libraryPath
|
|
2931
|
+
|| currentJob.artifactDigest !== expected.artifactDigest || currentJob.state !== expected.state) {
|
|
2932
|
+
entry.dispatched = true;
|
|
2933
|
+
await entry.reservation.markDispatchPossible();
|
|
2934
|
+
throw new Error("FINAL_CUT_CANONICAL_RECOVERY_REQUIRED: publish intent changed during reservation acquisition");
|
|
2935
|
+
}
|
|
2936
|
+
}
|
|
2937
|
+
// Property getters on arbitrary providers may themselves dispatch.
|
|
2938
|
+
const trustedShape = !utilTypes.isProxy(target) && property === "executePublishJob"
|
|
2939
|
+
&& Object.getPrototypeOf(target) === FinalCutProjectPublisher.prototype
|
|
2940
|
+
&& [["executePublishJob", builtInPublishExecute], ["getPublishJob", builtInPublishGetJob],
|
|
2941
|
+
["persistPublishJob", builtInPublishPersist], ["trackNativeDispatch", builtInPublishTrack]].every(([key, method]) => typeof key === "string" && !Object.getOwnPropertyDescriptor(target, key)
|
|
2942
|
+
&& Object.getOwnPropertyDescriptor(FinalCutProjectPublisher.prototype, key)?.value === method);
|
|
2943
|
+
if (acquiringReservation && !trustedShape) {
|
|
2944
|
+
entry.dispatched = true;
|
|
2945
|
+
await entry.reservation.markDispatchPossible();
|
|
2946
|
+
// A custom lookup may execute arbitrary provider code. Run it only
|
|
2947
|
+
// after durable uncertainty, then bind any eligible requested intent.
|
|
2948
|
+
if (jobId && entry.needsBinding) {
|
|
2949
|
+
const lookup = Reflect.get(target, "getPublishJob", target);
|
|
2950
|
+
if (typeof lookup === "function") {
|
|
2951
|
+
const requested = Reflect.apply(lookup, target, [jobId]);
|
|
2952
|
+
if (requested?.jobId !== undefined && requested.jobId !== jobId) {
|
|
2953
|
+
throw new Error("FINAL_CUT_CANONICAL_RECOVERY_REQUIRED: publish job identity mismatch");
|
|
2954
|
+
}
|
|
2955
|
+
if (requested?.state === "verification-pending") {
|
|
2956
|
+
throw new Error("FINAL_CUT_CANONICAL_RECOVERY_REQUIRED: unowned pending publish cannot be invoked again");
|
|
2957
|
+
}
|
|
2958
|
+
const path = requested?.targetLibraryPath;
|
|
2959
|
+
const digest = requested?.artifactDigest;
|
|
2960
|
+
if (requested?.state !== "verification-pending" && /^publish-job-[a-z0-9-]{1,80}$/.test(jobId)
|
|
2961
|
+
&& typeof path === "string" && path.length <= 4096 && isAbsolute(path) && path.endsWith(".fcpbundle")
|
|
2962
|
+
&& typeof digest === "string" && /^[a-f0-9]{64}$/.test(digest)) {
|
|
2963
|
+
await entry.reservation.bindRecoveryContext({ kind: "publish", jobId, dispatchId: randomUUID(),
|
|
2964
|
+
requestedTarget: { libraryPath: path }, artifactDigest: digest,
|
|
2965
|
+
executorIdentity: null, nativeQuiescence: "unproven" });
|
|
2966
|
+
}
|
|
2967
|
+
}
|
|
2968
|
+
}
|
|
2969
|
+
}
|
|
2970
|
+
const value = trustedShape ? builtInPublishExecute : Reflect.get(target, property, target);
|
|
2971
|
+
const track = trustedShape ? builtInPublishTrack : Reflect.get(target, "trackNativeDispatch", target);
|
|
2972
|
+
if (typeof value !== "function")
|
|
2973
|
+
throw new Error("CAPABILITY_UNAVAILABLE: publisher operation is not available");
|
|
2974
|
+
if (acquiringReservation && jobId && property === "executePublishJob"
|
|
2975
|
+
&& trustedShape) {
|
|
2976
|
+
const stores = ["publishJobs", "publishJobRuntime"].map((key) => Object.getOwnPropertyDescriptor(target, key)?.value);
|
|
2977
|
+
const ordinaryStores = stores.every((store) => !utilTypes.isProxy(store) && utilTypes.isMap(store)
|
|
2978
|
+
&& Object.getPrototypeOf(store) === Map.prototype
|
|
2979
|
+
&& !Object.getOwnPropertyDescriptor(store, "get") && !Object.getOwnPropertyDescriptor(store, "set") && !Object.getOwnPropertyDescriptor(store, "has")
|
|
2980
|
+
&& Object.getOwnPropertyDescriptor(Map.prototype, "get")?.value === builtInMapGet
|
|
2981
|
+
&& Object.getOwnPropertyDescriptor(Map.prototype, "set")?.value === builtInMapSet
|
|
2982
|
+
&& Object.getOwnPropertyDescriptor(Map.prototype, "has")?.value === builtInMapHas);
|
|
2983
|
+
const job = ordinaryStores ? inertBuiltInPublishJob(target, jobId) : undefined;
|
|
2984
|
+
if (!ordinaryStores || (!job && builtInMapHas.call(stores[0], jobId))) {
|
|
2985
|
+
// A present but non-inert job may execute getters or identify a
|
|
2986
|
+
// different operation. Do not invoke it even after the marker.
|
|
2987
|
+
entry.dispatched = true;
|
|
2988
|
+
await entry.reservation.markDispatchPossible();
|
|
2989
|
+
throw new Error("FINAL_CUT_CANONICAL_RECOVERY_REQUIRED: publish job identity cannot be inspected safely");
|
|
2990
|
+
}
|
|
2991
|
+
if (job) {
|
|
2992
|
+
const enabled = Object.getOwnPropertyDescriptor(target, "enabled");
|
|
2993
|
+
const directory = Object.getOwnPropertyDescriptor(target, "publishJobsDirectory");
|
|
2994
|
+
const configurationKeys = ["enabled", "liveState", "readCanonicalSnapshot", "sourcePath", "publishJobsDirectory"];
|
|
2995
|
+
const configurationUnchanged = Boolean(entry.requestedConfiguration && configurationKeys.every((key, index) => {
|
|
2996
|
+
const before = entry.requestedConfiguration?.[index];
|
|
2997
|
+
const after = Object.getOwnPropertyDescriptor(target, key);
|
|
2998
|
+
return before && after && "value" in before && "value" in after && Object.is(before.value, after.value);
|
|
2999
|
+
}));
|
|
3000
|
+
const safePersistence = Boolean(configurationUnchanged && directory && "value" in directory
|
|
3001
|
+
&& (directory.value === undefined
|
|
3002
|
+
|| (typeof directory.value === "string" && !builtInMapHas.call(stores[1], jobId))));
|
|
3003
|
+
provenDisabled = (job.state === "awaiting-confirmation" || job.state === "awaiting-final-cut")
|
|
3004
|
+
&& enabled?.value === false && safePersistence;
|
|
3005
|
+
const liveState = Object.getOwnPropertyDescriptor(target, "liveState");
|
|
3006
|
+
if (args[1] === true && enabled?.value === true && safePersistence
|
|
3007
|
+
&& (job.state === "awaiting-confirmation" || job.state === "awaiting-final-cut")
|
|
3008
|
+
&& liveState && "value" in liveState && liveState.value === undefined) {
|
|
3009
|
+
// This preflight uses only inert data and never invokes the
|
|
3010
|
+
// provider or its mutable dependencies.
|
|
3011
|
+
const blocked = { ...job, state: "awaiting-final-cut", nextAction: "retry", retryable: true,
|
|
3012
|
+
error: { code: "FINAL_CUT_PUBLISH_VERIFICATION_UNAVAILABLE", message: "Final Cut project state verification is unavailable; retry this job when the live provider is ready" } };
|
|
3013
|
+
builtInPublishPersist.call(target, blocked);
|
|
3014
|
+
return blocked;
|
|
3015
|
+
}
|
|
3016
|
+
const readback = Object.getOwnPropertyDescriptor(target, "readCanonicalSnapshot");
|
|
3017
|
+
if (args[1] === true && enabled?.value === true && safePersistence
|
|
3018
|
+
&& (job.state === "awaiting-confirmation" || job.state === "awaiting-final-cut")
|
|
3019
|
+
&& liveState && "value" in liveState && typeof liveState.value === "function"
|
|
3020
|
+
&& readback && "value" in readback && readback.value === undefined) {
|
|
3021
|
+
const failed = { ...job, state: "failed", nextAction: "none", retryable: false,
|
|
3022
|
+
error: { code: "FINAL_CUT_PUBLISH_READBACK_UNAVAILABLE", message: "FINAL_CUT_PUBLISH_READBACK_UNAVAILABLE: headed canonical timeline readback is not configured; no import was attempted" } };
|
|
3023
|
+
builtInPublishPersist.call(target, failed);
|
|
3024
|
+
return failed;
|
|
3025
|
+
}
|
|
3026
|
+
// A mismatching managed artifact can be rejected without invoking
|
|
3027
|
+
// the publisher or its tracker. Keep this synchronous so the
|
|
3028
|
+
// trusted store and publisher checks cannot race an await.
|
|
3029
|
+
const source = Object.getOwnPropertyDescriptor(target, "sourcePath");
|
|
3030
|
+
if (args[1] === true && enabled?.value === true && !provenDisabled
|
|
3031
|
+
&& (job.state === "awaiting-confirmation" || job.state === "awaiting-final-cut")
|
|
3032
|
+
&& !job.sourceTransactionId.startsWith("headless-rough-cut:")
|
|
3033
|
+
&& typeof source?.value === "string" && source.value === job.sourcePath
|
|
3034
|
+
&& safePersistence
|
|
3035
|
+
&& managedArtifactChanged(job.sourcePath, job.artifactDigest)) {
|
|
3036
|
+
const failed = { ...job, state: "failed", nextAction: "none", retryable: false,
|
|
3037
|
+
error: { code: "PUBLISH_SOURCE_CHANGED", message: "Managed FCPXML artifact changed after transaction verification" } };
|
|
3038
|
+
builtInPublishPersist.call(target, failed);
|
|
3039
|
+
return failed;
|
|
3040
|
+
}
|
|
3041
|
+
}
|
|
3042
|
+
}
|
|
3043
|
+
const invoke = async () => {
|
|
3044
|
+
// Once the provider is invoked, a missing callback is not proof of non-dispatch.
|
|
3045
|
+
if (!provenDisabled)
|
|
3046
|
+
entry.dispatched = true;
|
|
3047
|
+
return Reflect.apply(value, target, args);
|
|
3048
|
+
};
|
|
3049
|
+
// Custom tracking code can defer invocation and return or throw first.
|
|
3050
|
+
if (!provenDisabled)
|
|
3051
|
+
entry.dispatched = true;
|
|
3052
|
+
// Record uncertainty before entering any untrusted tracker or provider.
|
|
3053
|
+
// Resumed verification reuses the already marked reservation.
|
|
3054
|
+
if (acquiringReservation && trustedShape && !provenDisabled)
|
|
3055
|
+
await entry.reservation.markDispatchPossible();
|
|
3056
|
+
if (!provenDisabled)
|
|
3057
|
+
await validateRoute(target, property);
|
|
3058
|
+
const result = typeof track === "function"
|
|
3059
|
+
? await Reflect.apply(track, target, [invoke, () => { entry.dispatched = true; }])
|
|
3060
|
+
: await invoke();
|
|
3061
|
+
if (entry.dispatched && result && typeof result === "object" && !Array.isArray(result)) {
|
|
3062
|
+
return { ...result, recoveryReservation: { status: "recovery-required", reservationId: entry.reservation.reservationId, reason: "native-quiescence-unproven" } };
|
|
3063
|
+
}
|
|
3064
|
+
return result;
|
|
3065
|
+
}
|
|
3066
|
+
finally {
|
|
3067
|
+
entry.active = false;
|
|
3068
|
+
if (!entry.dispatched) {
|
|
3069
|
+
await entry.reservation.release();
|
|
3070
|
+
if (current === entry)
|
|
3071
|
+
current = undefined;
|
|
3072
|
+
}
|
|
3073
|
+
}
|
|
3074
|
+
};
|
|
3075
|
+
},
|
|
3076
|
+
});
|
|
3077
|
+
}
|
|
3078
|
+
function inertBuiltInPublishJob(target, jobId) {
|
|
3079
|
+
if (utilTypes.isProxy(target) || Object.getPrototypeOf(target) !== FinalCutProjectPublisher.prototype
|
|
3080
|
+
|| Object.getOwnPropertyDescriptor(target, "getPublishJob")
|
|
3081
|
+
|| Object.getOwnPropertyDescriptor(FinalCutProjectPublisher.prototype, "getPublishJob")?.value !== builtInPublishGetJob)
|
|
3082
|
+
return undefined;
|
|
3083
|
+
const store = Object.getOwnPropertyDescriptor(target, "publishJobs")?.value;
|
|
3084
|
+
if (utilTypes.isProxy(store) || !utilTypes.isMap(store) || Object.getPrototypeOf(store) !== Map.prototype
|
|
3085
|
+
|| Object.getOwnPropertyDescriptor(Map.prototype, "get")?.value !== builtInMapGet)
|
|
3086
|
+
return undefined;
|
|
3087
|
+
const job = builtInMapGet.call(store, jobId);
|
|
3088
|
+
const seen = new Set();
|
|
3089
|
+
const inert = (value) => {
|
|
3090
|
+
if (value === null || ["string", "boolean", "number", "undefined"].includes(typeof value))
|
|
3091
|
+
return true;
|
|
3092
|
+
if (typeof value !== "object" || utilTypes.isProxy(value) || seen.has(value) || seen.size >= 10_000)
|
|
3093
|
+
return false;
|
|
3094
|
+
seen.add(value);
|
|
3095
|
+
const prototype = Object.getPrototypeOf(value);
|
|
3096
|
+
if (prototype !== Object.prototype && prototype !== Array.prototype && prototype !== null)
|
|
3097
|
+
return false;
|
|
3098
|
+
return Reflect.ownKeys(value).every((key) => {
|
|
3099
|
+
if (typeof key !== "string")
|
|
3100
|
+
return false;
|
|
3101
|
+
const descriptor = Object.getOwnPropertyDescriptor(value, key);
|
|
3102
|
+
return Boolean(descriptor && "value" in descriptor && inert(descriptor.value));
|
|
3103
|
+
});
|
|
3104
|
+
};
|
|
3105
|
+
return inert(job) && job && typeof job === "object" ? structuredClone(job) : undefined;
|
|
3106
|
+
}
|
|
3107
|
+
function managedArtifactChanged(path, digest) {
|
|
3108
|
+
let fd;
|
|
3109
|
+
try {
|
|
3110
|
+
fd = openSync(path, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
|
|
3111
|
+
const info = fstatSync(fd);
|
|
3112
|
+
if (!info.isFile() || info.size > 64 * 1024 * 1024)
|
|
3113
|
+
return false;
|
|
3114
|
+
return createHash("sha256").update(readFileSync(fd, "utf8")).digest("hex") !== digest;
|
|
3115
|
+
}
|
|
3116
|
+
catch {
|
|
3117
|
+
return false;
|
|
3118
|
+
}
|
|
3119
|
+
finally {
|
|
3120
|
+
if (fd !== undefined)
|
|
3121
|
+
closeSync(fd);
|
|
3122
|
+
}
|
|
3123
|
+
}
|
|
3124
|
+
function isBuiltinImportObservationUnavailable(provider) {
|
|
3125
|
+
if (!provider || utilTypes.isProxy(provider) || Object.getPrototypeOf(provider) !== FinalCutNativeAutomationAdapter.prototype)
|
|
3126
|
+
return false;
|
|
3127
|
+
const observer = Object.getOwnPropertyDescriptor(provider, "importSourceObserver");
|
|
3128
|
+
if (!observer || !("value" in observer) || observer.value !== undefined)
|
|
3129
|
+
return false;
|
|
3130
|
+
return ["importMedia", "executeImportMediaDirectory", "capabilities"].every((key) => !Object.getOwnPropertyDescriptor(provider, key)
|
|
3131
|
+
&& Object.getOwnPropertyDescriptor(FinalCutNativeAutomationAdapter.prototype, key)?.value === builtInNativeMethods.get(key));
|
|
3132
|
+
}
|
|
3133
|
+
function withRecoveryCheckpointGuard(provider, recovery, allowedMethods = [], reservedMethods = [], reservationKind = "native") {
|
|
3134
|
+
const allowed = new Set(allowedMethods);
|
|
3135
|
+
const reserved = new Set(reservedMethods);
|
|
3136
|
+
const contextMethods = new Set(["focusTimeline", "selectMedia", "selectOccurrence", "selectCanonicalOccurrence"]);
|
|
3137
|
+
const searchMethods = new Set(["searchMedia", "searchMediaForCanonicalTarget", "searchTitles", "searchTransitions"]);
|
|
3138
|
+
return new Proxy(provider, {
|
|
3139
|
+
get(target, property) {
|
|
3140
|
+
if (!reserved.has(property)) {
|
|
3141
|
+
const value = Reflect.get(target, property, target);
|
|
3142
|
+
if (typeof value !== "function")
|
|
3143
|
+
return value;
|
|
3144
|
+
if (allowed.has(property))
|
|
3145
|
+
return value.bind(target);
|
|
3146
|
+
return async (...args) => {
|
|
3147
|
+
await recovery.assertClear();
|
|
3148
|
+
return Reflect.apply(value, target, args);
|
|
3149
|
+
};
|
|
3150
|
+
}
|
|
3151
|
+
// Inspect descriptors without invoking provider accessors while another
|
|
3152
|
+
// native reservation may be held. Unknown proxy shapes stay guarded.
|
|
3153
|
+
if (!utilTypes.isProxy(target)) {
|
|
3154
|
+
let object = target;
|
|
3155
|
+
while (object && !utilTypes.isProxy(object)) {
|
|
3156
|
+
const descriptor = Object.getOwnPropertyDescriptor(object, property);
|
|
3157
|
+
if (descriptor) {
|
|
3158
|
+
if ("value" in descriptor && typeof descriptor.value !== "function")
|
|
3159
|
+
return descriptor.value;
|
|
3160
|
+
break;
|
|
3161
|
+
}
|
|
3162
|
+
object = Object.getPrototypeOf(object);
|
|
3163
|
+
}
|
|
3164
|
+
if (!object)
|
|
3165
|
+
return undefined;
|
|
3166
|
+
}
|
|
3167
|
+
return async (...args) => {
|
|
3168
|
+
if (reserved.has(property)) {
|
|
3169
|
+
const reservation = await recovery.beginNative(`native.${reservationKind === "disposable" ? "disposable." : ""}${String(property).toLowerCase()}`);
|
|
3170
|
+
// Reject a disabled operation without invoking any adapter code. For all
|
|
3171
|
+
// other cases, callbacks and mutable internals may schedule dispatch.
|
|
3172
|
+
const disabledPreflight = !utilTypes.isProxy(target)
|
|
3173
|
+
&& Object.getPrototypeOf(target) === FinalCutNativeAutomationAdapter.prototype
|
|
3174
|
+
&& Object.getOwnPropertyDescriptor(target, "enabled")?.value === false
|
|
3175
|
+
&& Reflect.ownKeys(target).every((key) => {
|
|
3176
|
+
const descriptor = Object.getOwnPropertyDescriptor(target, key);
|
|
3177
|
+
return Boolean(descriptor && "value" in descriptor);
|
|
3178
|
+
})
|
|
3179
|
+
&& [...builtInNativeMethods].every(([key, method]) => key === "constructor" || typeof method !== "function"
|
|
3180
|
+
|| (!Object.getOwnPropertyDescriptor(target, key)
|
|
3181
|
+
&& Object.getOwnPropertyDescriptor(FinalCutNativeAutomationAdapter.prototype, key)?.value === method));
|
|
3182
|
+
const untrustedProvider = !disabledPreflight;
|
|
3183
|
+
let dispatched = untrustedProvider;
|
|
3184
|
+
try {
|
|
3185
|
+
if (untrustedProvider)
|
|
3186
|
+
await reservation.markDispatchPossible();
|
|
3187
|
+
if (disabledPreflight) {
|
|
3188
|
+
if (property === "focusTimeline") {
|
|
3189
|
+
await reservation.release();
|
|
3190
|
+
return disabledNativeFocusContext();
|
|
3191
|
+
}
|
|
3192
|
+
throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native writes are disabled");
|
|
3193
|
+
}
|
|
3194
|
+
const value = Reflect.get(target, property, target);
|
|
3195
|
+
const track = Reflect.get(target, "trackNativeDispatch", target);
|
|
3196
|
+
if (typeof value !== "function")
|
|
3197
|
+
throw new Error("CAPABILITY_UNAVAILABLE: native operation is not available");
|
|
3198
|
+
const invoke = async () => Reflect.apply(value, target, args);
|
|
3199
|
+
const result = typeof track === "function"
|
|
3200
|
+
? await Reflect.apply(track, target, [invoke, () => { dispatched = true; }])
|
|
3201
|
+
: await invoke();
|
|
3202
|
+
const evidence = result;
|
|
3203
|
+
const restored = typeof evidence?.beforeDigest === "string" && /^[a-f0-9]{64}$/.test(evidence.beforeDigest)
|
|
3204
|
+
&& evidence.restoredDigest === evidence.beforeDigest;
|
|
3205
|
+
const media = (value) => {
|
|
3206
|
+
if (!value || typeof value !== "object")
|
|
3207
|
+
return false;
|
|
3208
|
+
const item = value;
|
|
3209
|
+
return typeof item.mediaHandle === "string" && item.mediaHandle.length > 0
|
|
3210
|
+
&& item.verification?.verified === true && item.verification.stage === "post-import-browser-discovery";
|
|
3211
|
+
};
|
|
3212
|
+
const directory = result;
|
|
3213
|
+
const verifiedDirectory = () => {
|
|
3214
|
+
if (directory?.status !== "completed" || directory.partial !== false || directory.failedCount !== 0
|
|
3215
|
+
|| !Array.isArray(directory.files) || directory.files.length === 0
|
|
3216
|
+
|| directory.importedCount !== directory.files.length || !Array.isArray(directory.results)
|
|
3217
|
+
|| directory.results.length !== directory.files.length)
|
|
3218
|
+
return false;
|
|
3219
|
+
const expected = new Set();
|
|
3220
|
+
for (const file of directory.files) {
|
|
3221
|
+
if (!file || typeof file.sourcePath !== "string" || !file.sourcePath || expected.has(file.sourcePath))
|
|
3222
|
+
return false;
|
|
3223
|
+
expected.add(file.sourcePath);
|
|
3224
|
+
}
|
|
3225
|
+
const handles = new Set();
|
|
3226
|
+
for (const entry of directory.results) {
|
|
3227
|
+
if (!entry || entry.status !== "imported" || typeof entry.sourcePath !== "string"
|
|
3228
|
+
|| !expected.delete(entry.sourcePath) || !media(entry.media))
|
|
3229
|
+
return false;
|
|
3230
|
+
const item = entry.media;
|
|
3231
|
+
if (item.sourcePath !== entry.sourcePath || handles.has(item.mediaHandle))
|
|
3232
|
+
return false;
|
|
3233
|
+
handles.add(item.mediaHandle);
|
|
3234
|
+
}
|
|
3235
|
+
return expected.size === 0;
|
|
3236
|
+
};
|
|
3237
|
+
const preview = typeof property === "string" && property.startsWith("preview");
|
|
3238
|
+
const prepared = result;
|
|
3239
|
+
const verified = preview ? typeof prepared?.previewToken === "string" && prepared.previewToken.length > 0
|
|
3240
|
+
: contextMethods.has(property) ? prepared?.available === true
|
|
3241
|
+
: searchMethods.has(property) ? Array.isArray(result)
|
|
3242
|
+
: property === "locateOccurrence" || property === "locateOccurrenceForCanonicalTarget" ? ["none", "unique", "ambiguous"].includes(String(prepared?.status)) && Array.isArray(prepared?.occurrences)
|
|
3243
|
+
: property === "targetMedia" ? prepared?.status === "unique" && prepared.selected === true
|
|
3244
|
+
: property === "importMedia" ? media(result)
|
|
3245
|
+
: property === "executeImportMediaDirectory" ? verifiedDirectory()
|
|
3246
|
+
: reservationKind === "disposable"
|
|
3247
|
+
? property === "undo"
|
|
3248
|
+
? evidence?.undone === true && evidence.verification?.passed === true && restored
|
|
3249
|
+
: (evidence?.status === "VERIFIED" && evidence.verification?.passed === true)
|
|
3250
|
+
|| (evidence?.status === "ROLLED_BACK" && restored)
|
|
3251
|
+
: evidence?.verification?.verified === true && (property !== "undo" || evidence.undone === true);
|
|
3252
|
+
if (!untrustedProvider && (verified || (!dispatched && contextMethods.has(property) && prepared?.available === false))) {
|
|
3253
|
+
await reservation.release();
|
|
3254
|
+
}
|
|
3255
|
+
return result;
|
|
3256
|
+
}
|
|
3257
|
+
catch (error) {
|
|
3258
|
+
if (!dispatched)
|
|
3259
|
+
await reservation.release();
|
|
3260
|
+
throw error;
|
|
3261
|
+
}
|
|
3262
|
+
}
|
|
3263
|
+
throw new Error("CAPABILITY_UNAVAILABLE: native operation is not available");
|
|
3264
|
+
};
|
|
3265
|
+
},
|
|
3266
|
+
});
|
|
3267
|
+
}
|
|
2613
3268
|
function withBuildAlignmentGuard(provider, assertAlignment, synchronousMethods = []) {
|
|
2614
3269
|
const synchronous = new Set(synchronousMethods);
|
|
2615
3270
|
return new Proxy(provider, {
|