@morshoto/framekit 0.1.17 → 0.1.18
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +10 -4
- package/dist-package/adapters/final-cut/typescript/src/canonical.js +19 -7
- package/dist-package/adapters/final-cut/typescript/src/connection.js +5 -3
- package/dist-package/adapters/final-cut/typescript/src/fcpxml.js +128 -29
- package/dist-package/adapters/final-cut/typescript/src/index.js +1 -0
- package/dist-package/adapters/final-cut/typescript/src/library-inspection.js +60 -1
- package/dist-package/adapters/final-cut/typescript/src/live.js +2 -2
- package/dist-package/adapters/final-cut/typescript/src/publish-readback.js +213 -0
- package/dist-package/adapters/final-cut/typescript/src/publisher.js +762 -238
- package/dist-package/adapters/final-cut/typescript/src/session.js +6 -1
- package/dist-package/adapters/final-cut/typescript/src/timeline-ir-fcpxml.js +200 -48
- package/dist-package/adapters/headless/typescript/src/ffmpeg-renderer.js +17 -7
- package/dist-package/adapters/headless/typescript/src/ffmpeg-verifier.js +2 -2
- package/dist-package/apps/cli/src/main.js +34 -19
- package/dist-package/apps/mcp-server/src/build-alignment.js +59 -0
- package/dist-package/apps/mcp-server/src/build-identity.js +30 -0
- package/dist-package/apps/mcp-server/src/build-identity.json +5 -0
- package/dist-package/apps/mcp-server/src/headless-project-snapshot.js +101 -0
- package/dist-package/apps/mcp-server/src/headless-projects.js +255 -16
- package/dist-package/apps/mcp-server/src/main.js +27 -3
- package/dist-package/apps/mcp-server/src/server.js +270 -49
- package/dist-package/apps/mcp-server/src/version.js +21 -2
- package/dist-package/packages/runtime/src/application/media-analysis-service.js +15 -5
- package/dist-package/packages/runtime/src/runtime.js +6 -0
- package/dist-package/packages/runtime/src/timeline/editing-session.js +7 -2
- package/package.json +9 -9
|
@@ -1,13 +1,15 @@
|
|
|
1
1
|
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
|
|
2
2
|
import { ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
|
|
3
3
|
import { resolve as resolvePath } from "node:path";
|
|
4
|
-
import { z } from "zod";
|
|
4
|
+
import { z } from "zod/v3";
|
|
5
5
|
import { createCapabilityPreflight, resolveEditingIntent, serializeCapabilityUnavailableError, withCanonicalTimelineMode, withCapabilityFamilies, createTimelineIrFromProjectSnapshot, } from "../../../packages/runtime/src/index.js";
|
|
6
6
|
import { NATIVE_MEDIA_IMPORT_DIRECTORY_ERROR_CODE, serializeFinalCutLibraryInspectionError, serializeNativeFinalCutMediaImportError, serializeNativeFinalCutPartialMutationError, } from "../../../adapters/final-cut/typescript/src/index.js";
|
|
7
7
|
import { BACKGROUND_ARTIFACT_WORKFLOW, EDITING_ROUTE_EDIT_TYPES, EDITOR_FIRST_MCP_INSTRUCTIONS, HEADLESS_TIMELINE_EDIT_TYPES, HEADLESS_FIRST_MCP_INSTRUCTIONS, resolveEditingRoute, } from "./routing.js";
|
|
8
|
+
import { assessBuildAlignment } from "./build-alignment.js";
|
|
8
9
|
import { FRAMEKIT_BUILD_FINGERPRINT, FRAMEKIT_VERSION, } from "./version.js";
|
|
9
10
|
import { EditingSessionRepository } from "./headless-sessions.js";
|
|
10
11
|
import { SessionMaterializationJobs, } from "./materialization-jobs.js";
|
|
12
|
+
import { projectSnapshotFromTimelineIr } from "./headless-project-snapshot.js";
|
|
11
13
|
import { chooseTimelineReadback } from "./readback-policy.js";
|
|
12
14
|
const revisionValueSchema = z.object({
|
|
13
15
|
id: z.string(),
|
|
@@ -56,6 +58,7 @@ const timelineSemanticContextQuerySchema = z.object({
|
|
|
56
58
|
}).strict();
|
|
57
59
|
const roughCutPlanSchema = mediaIndexQuerySchema.extend({
|
|
58
60
|
maxShots: z.number().int().positive().optional(),
|
|
61
|
+
projectId: z.string().min(1).optional(),
|
|
59
62
|
});
|
|
60
63
|
const durationRangeSchema = z.object({
|
|
61
64
|
startSeconds: z.number().finite().nonnegative(),
|
|
@@ -319,6 +322,7 @@ function installMcpSchemaCompatibility(server) {
|
|
|
319
322
|
}
|
|
320
323
|
const artifactPublishInputSchema = z.object({
|
|
321
324
|
artifactPath: z.string().trim().min(1),
|
|
325
|
+
targetLibraryPath: z.string().trim().min(1),
|
|
322
326
|
transactionId: z.string().min(1),
|
|
323
327
|
confirm: z.boolean(),
|
|
324
328
|
}).strict();
|
|
@@ -836,6 +840,29 @@ function frameResult(value) {
|
|
|
836
840
|
}
|
|
837
841
|
export function createMcpServer(runtime, options = {}) {
|
|
838
842
|
runtime.registerBuiltinSkills();
|
|
843
|
+
if (options.requireBuildAlignment) {
|
|
844
|
+
const assertAlignment = () => assertRequiredBuildAlignment(runtime, options);
|
|
845
|
+
options = {
|
|
846
|
+
...options,
|
|
847
|
+
...(options.nativeEditor
|
|
848
|
+
? { nativeEditor: withBuildAlignmentGuard(options.nativeEditor, assertAlignment, ["capabilities"]) }
|
|
849
|
+
: {}),
|
|
850
|
+
...(options.disposableNative
|
|
851
|
+
? { disposableNative: withBuildAlignmentGuard(options.disposableNative, assertAlignment) }
|
|
852
|
+
: {}),
|
|
853
|
+
...(options.nativeOperationSession
|
|
854
|
+
? { nativeOperationSession: withBuildAlignmentGuard(options.nativeOperationSession, assertAlignment) }
|
|
855
|
+
: {}),
|
|
856
|
+
...(options.projectPublisher
|
|
857
|
+
? {
|
|
858
|
+
projectPublisher: withBuildAlignmentGuard(options.projectPublisher, assertAlignment, ["isAvailable", "inspectReadiness", "executionMode", "getPublishJob"]),
|
|
859
|
+
}
|
|
860
|
+
: {}),
|
|
861
|
+
...(options.videoExporter
|
|
862
|
+
? { videoExporter: withBuildAlignmentGuard(options.videoExporter, assertAlignment, ["isAvailable"]) }
|
|
863
|
+
: {}),
|
|
864
|
+
};
|
|
865
|
+
}
|
|
839
866
|
const server = new McpServer({ name: "framekit", version: FRAMEKIT_VERSION }, { instructions: options.headlessProjects ? HEADLESS_FIRST_MCP_INSTRUCTIONS : EDITOR_FIRST_MCP_INSTRUCTIONS });
|
|
840
867
|
const nativeTransitionAssets = new Map();
|
|
841
868
|
const sessions = options.sessionDirectory
|
|
@@ -972,6 +999,10 @@ export function createMcpServer(runtime, options = {}) {
|
|
|
972
999
|
description: "Read Framekit's Final Cut connection state before editor-first capability discovery.",
|
|
973
1000
|
inputSchema: {},
|
|
974
1001
|
}, async () => jsonResult(await effectiveConnectionStatus(runtime, options)));
|
|
1002
|
+
server.registerTool("editor.native.handoff.readiness", {
|
|
1003
|
+
description: "Read native Final Cut handoff readiness without launching, activating, importing, or mutating Final Cut.",
|
|
1004
|
+
inputSchema: { publishJobId: z.string().trim().min(1).optional() },
|
|
1005
|
+
}, async ({ publishJobId }) => jsonResult(await inspectNativeHandoffReadiness(runtime, options, publishJobId)));
|
|
975
1006
|
server.registerTool("skill.list", {
|
|
976
1007
|
description: "List registered versioned Framekit Skills with current capability availability.",
|
|
977
1008
|
inputSchema: {},
|
|
@@ -1287,7 +1318,11 @@ export function createMcpServer(runtime, options = {}) {
|
|
|
1287
1318
|
editType: z.enum(EDITING_ROUTE_EDIT_TYPES).optional(),
|
|
1288
1319
|
},
|
|
1289
1320
|
}, async ({ operation, fallback, path, editType }) => {
|
|
1290
|
-
const
|
|
1321
|
+
const headlessOnly = fallback === "none"
|
|
1322
|
+
&& (path === "headless" || (Boolean(options.headlessProjects) && operation === "timeline.edit" && path !== "headed"));
|
|
1323
|
+
const context = headlessOnly
|
|
1324
|
+
? { connection: { state: "disconnected" }, ...headlessRoutingContext(options) }
|
|
1325
|
+
: await editingRouteContext(runtime, options);
|
|
1291
1326
|
return jsonResult(resolveEditingRoute({
|
|
1292
1327
|
operation,
|
|
1293
1328
|
fallback,
|
|
@@ -1387,7 +1422,7 @@ export function createMcpServer(runtime, options = {}) {
|
|
|
1387
1422
|
}, async ({ jobId }) => {
|
|
1388
1423
|
if (!options.nativeOperationSession)
|
|
1389
1424
|
throw new Error("CAPABILITY_UNAVAILABLE: native operation session is not configured");
|
|
1390
|
-
return jsonResult(options.nativeOperationSession.status(jobId));
|
|
1425
|
+
return jsonResult(await options.nativeOperationSession.status(jobId));
|
|
1391
1426
|
});
|
|
1392
1427
|
server.registerTool("editor.native.operation.retry", {
|
|
1393
1428
|
description: "Retry a waiting native Final Cut operation after the required headed session becomes ready.",
|
|
@@ -1628,32 +1663,51 @@ export function createMcpServer(runtime, options = {}) {
|
|
|
1628
1663
|
return nativeMutationResult(() => options.nativeEditor.executeTrimToDuration(previewToken, { signal: extra.signal }));
|
|
1629
1664
|
});
|
|
1630
1665
|
server.registerTool("artifact.publish.preview", {
|
|
1631
|
-
description: "Prepare
|
|
1666
|
+
description: "Prepare an experimental, opt-in native handoff from a verified artifact without opening Final Cut.",
|
|
1632
1667
|
inputSchema: {
|
|
1633
1668
|
artifactPath: z.string().trim().min(1),
|
|
1634
|
-
|
|
1669
|
+
targetLibraryPath: z.string().trim().min(1),
|
|
1670
|
+
transactionId: z.string().min(1).optional(),
|
|
1671
|
+
headlessExecutionId: z.string().min(1).optional(),
|
|
1635
1672
|
},
|
|
1636
|
-
}, async ({ artifactPath, transactionId }) => {
|
|
1673
|
+
}, async ({ artifactPath, targetLibraryPath, transactionId, headlessExecutionId }) => {
|
|
1637
1674
|
if (!options.projectPublisher)
|
|
1638
1675
|
throw new Error("CAPABILITY_UNAVAILABLE: Final Cut project publishing requires FRAMEKIT_FCPXML_PATH and native writes");
|
|
1639
|
-
|
|
1640
|
-
|
|
1641
|
-
throw new Error(`PUBLISH_TARGET_MISMATCH: transaction ${transactionId} is not verified for artifact ${artifactPath}`);
|
|
1676
|
+
if (Boolean(transactionId) === Boolean(headlessExecutionId)) {
|
|
1677
|
+
throw new Error("PUBLISH_SOURCE_REQUIRED: provide exactly one of transactionId or headlessExecutionId");
|
|
1642
1678
|
}
|
|
1643
|
-
|
|
1644
|
-
|
|
1679
|
+
let sourceTransactionId;
|
|
1680
|
+
let artifactDigest;
|
|
1681
|
+
let sourceProof;
|
|
1682
|
+
if (headlessExecutionId) {
|
|
1683
|
+
sourceProof = await requireHeadlessProjects().verifyPublishableRoughCut(headlessExecutionId, artifactPath);
|
|
1684
|
+
sourceTransactionId = sourceProof.sourceTransactionId;
|
|
1685
|
+
artifactDigest = sourceProof.artifactDigest;
|
|
1645
1686
|
}
|
|
1646
|
-
|
|
1647
|
-
|
|
1648
|
-
|
|
1649
|
-
|
|
1650
|
-
|
|
1687
|
+
else {
|
|
1688
|
+
const transaction = runtime.getTransaction(transactionId);
|
|
1689
|
+
if (transaction.target?.kind !== "artifact" || transaction.target.artifactPath !== artifactPath) {
|
|
1690
|
+
throw new Error(`PUBLISH_TARGET_MISMATCH: transaction ${transactionId} is not verified for artifact ${artifactPath}`);
|
|
1691
|
+
}
|
|
1692
|
+
if (!transaction.artifactDigest) {
|
|
1693
|
+
throw new Error(`PUBLISH_SOURCE_CHANGED: transaction ${transactionId} has no immutable artifact digest`);
|
|
1694
|
+
}
|
|
1695
|
+
const verification = await runtime.verifyTransaction(transactionId);
|
|
1696
|
+
if (!verification.passed)
|
|
1697
|
+
throw new Error(`FINAL_CUT_PUBLISH_VALIDATION_FAILED: source transaction ${transactionId} did not pass verification`);
|
|
1698
|
+
sourceTransactionId = transactionId;
|
|
1699
|
+
artifactDigest = transaction.artifactDigest;
|
|
1700
|
+
}
|
|
1701
|
+
const job = await options.projectPublisher.preparePublish({
|
|
1702
|
+
sourceTransactionId,
|
|
1651
1703
|
artifactPath,
|
|
1652
|
-
artifactDigest
|
|
1653
|
-
|
|
1704
|
+
artifactDigest,
|
|
1705
|
+
targetLibraryPath,
|
|
1706
|
+
});
|
|
1707
|
+
return jsonResult({ ...job, ...(sourceProof ? { sourceProof } : {}) });
|
|
1654
1708
|
});
|
|
1655
1709
|
server.registerTool("artifact.publish.execute", {
|
|
1656
|
-
description: "Execute
|
|
1710
|
+
description: "Execute an experimental native handoff after explicit confirmation; dispatch alone is not project-creation proof, and success requires target readback.",
|
|
1657
1711
|
inputSchema: {
|
|
1658
1712
|
jobId: z.string().trim().min(1),
|
|
1659
1713
|
confirm: z.literal(true),
|
|
@@ -1661,6 +1715,9 @@ export function createMcpServer(runtime, options = {}) {
|
|
|
1661
1715
|
}, async ({ jobId, confirm }) => {
|
|
1662
1716
|
if (!options.projectPublisher)
|
|
1663
1717
|
throw new Error("CAPABILITY_UNAVAILABLE: Final Cut project publishing requires FRAMEKIT_FCPXML_PATH and native writes");
|
|
1718
|
+
if (options.projectPublisher.isAvailable() && requiresHeadedPublishingRoute(options.projectPublisher)) {
|
|
1719
|
+
await requireEditingRoute(runtime, options, "timeline.publish.new-project");
|
|
1720
|
+
}
|
|
1664
1721
|
return jsonResult(await options.projectPublisher.executePublishJob(jobId, confirm));
|
|
1665
1722
|
});
|
|
1666
1723
|
server.registerTool("artifact.publish.status", {
|
|
@@ -1672,11 +1729,14 @@ export function createMcpServer(runtime, options = {}) {
|
|
|
1672
1729
|
return jsonResult(options.projectPublisher.getPublishJob(jobId));
|
|
1673
1730
|
});
|
|
1674
1731
|
server.registerTool("artifact.publish", {
|
|
1675
|
-
description: "
|
|
1732
|
+
description: "Experimental, opt-in native import of validated FCPXML. Dispatch alone does not prove project creation; success requires matching created-target readback and explicit confirmation.",
|
|
1676
1733
|
inputSchema: artifactPublishInputSchema,
|
|
1677
|
-
}, async ({ artifactPath, transactionId, confirm }) => {
|
|
1678
|
-
if (!options.projectPublisher)
|
|
1679
|
-
throw new Error("CAPABILITY_UNAVAILABLE: Final Cut project publishing requires FRAMEKIT_FCPXML_PATH and
|
|
1734
|
+
}, async ({ artifactPath, targetLibraryPath, transactionId, confirm }) => {
|
|
1735
|
+
if (!options.projectPublisher?.isAvailable())
|
|
1736
|
+
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 (requiresHeadedPublishingRoute(options.projectPublisher)) {
|
|
1738
|
+
await requireEditingRoute(runtime, options, "timeline.publish.new-project");
|
|
1739
|
+
}
|
|
1680
1740
|
const transaction = runtime.getTransaction(transactionId);
|
|
1681
1741
|
if (transaction.target?.kind !== "artifact" || transaction.target.artifactPath !== artifactPath) {
|
|
1682
1742
|
throw new Error(`PUBLISH_TARGET_MISMATCH: transaction ${transactionId} is not verified for artifact ${artifactPath}`);
|
|
@@ -1691,15 +1751,23 @@ export function createMcpServer(runtime, options = {}) {
|
|
|
1691
1751
|
sourceTransactionId: transactionId,
|
|
1692
1752
|
artifactPath,
|
|
1693
1753
|
artifactDigest: transaction.artifactDigest,
|
|
1754
|
+
targetLibraryPath,
|
|
1694
1755
|
confirm,
|
|
1695
1756
|
}));
|
|
1696
1757
|
});
|
|
1697
1758
|
server.registerTool("timeline.publish.new-project", {
|
|
1698
|
-
description: "
|
|
1699
|
-
inputSchema: {
|
|
1700
|
-
|
|
1759
|
+
description: "Experimental, opt-in native import of a verified artifact transaction; reports verified delivery only after matching created-target readback and explicit confirmation.",
|
|
1760
|
+
inputSchema: {
|
|
1761
|
+
transactionId: z.string().min(1),
|
|
1762
|
+
targetLibraryPath: z.string().trim().min(1),
|
|
1763
|
+
confirm: z.literal(true),
|
|
1764
|
+
},
|
|
1765
|
+
}, async ({ transactionId, targetLibraryPath, confirm }) => {
|
|
1701
1766
|
if (!options.projectPublisher?.isAvailable())
|
|
1702
|
-
throw new Error("CAPABILITY_UNAVAILABLE: Final Cut project publishing requires FRAMEKIT_FCPXML_PATH and
|
|
1767
|
+
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 (requiresHeadedPublishingRoute(options.projectPublisher)) {
|
|
1769
|
+
await requireEditingRoute(runtime, options, "timeline.publish.new-project");
|
|
1770
|
+
}
|
|
1703
1771
|
const transaction = runtime.getTransaction(transactionId);
|
|
1704
1772
|
if (transaction.target?.kind !== "artifact") {
|
|
1705
1773
|
throw new Error(`PUBLISH_TARGET_MISMATCH: transaction ${transactionId} is not verified for a managed artifact`);
|
|
@@ -1714,7 +1782,8 @@ export function createMcpServer(runtime, options = {}) {
|
|
|
1714
1782
|
sourceTransactionId: transactionId,
|
|
1715
1783
|
artifactPath: transaction.target.artifactPath,
|
|
1716
1784
|
artifactDigest: transaction.artifactDigest,
|
|
1717
|
-
|
|
1785
|
+
targetLibraryPath,
|
|
1786
|
+
confirm,
|
|
1718
1787
|
}));
|
|
1719
1788
|
});
|
|
1720
1789
|
server.registerTool("timeline.export", {
|
|
@@ -1916,13 +1985,28 @@ export function createMcpServer(runtime, options = {}) {
|
|
|
1916
1985
|
},
|
|
1917
1986
|
}, async ({ mediaId, range }) => jsonResult(await runtime.analyzeVisual(mediaId, range)));
|
|
1918
1987
|
server.registerTool("media.understand", {
|
|
1919
|
-
description: "Return combined speech, audio, and visual understanding for one media item.",
|
|
1920
|
-
inputSchema: { mediaId: z.string().min(1) },
|
|
1921
|
-
}, async ({ mediaId }) =>
|
|
1988
|
+
description: "Return combined speech, audio, and visual understanding for one media item in the selected editor project or a named headless project.",
|
|
1989
|
+
inputSchema: { mediaId: z.string().min(1), projectId: z.string().min(1).optional() },
|
|
1990
|
+
}, async ({ mediaId, projectId }) => {
|
|
1991
|
+
if (!projectId)
|
|
1992
|
+
return jsonResult(await runtime.understandMedia(mediaId));
|
|
1993
|
+
return sessionResult(async () => {
|
|
1994
|
+
const project = await requireHeadlessProjects().open(projectId);
|
|
1995
|
+
return runtime.understandMediaInProject(mediaId, projectSnapshotFromTimelineIr(project.timeline));
|
|
1996
|
+
});
|
|
1997
|
+
});
|
|
1922
1998
|
server.registerTool("rough-cut.plan", {
|
|
1923
|
-
description: "Create a deterministic, explainable, read-only shot plan from analyzed media; does not mutate the timeline.",
|
|
1999
|
+
description: "Create a deterministic, explainable, read-only shot plan from analyzed editor or named headless project media; does not mutate the timeline.",
|
|
1924
2000
|
inputSchema: roughCutPlanSchema.shape,
|
|
1925
|
-
}, async (request) =>
|
|
2001
|
+
}, async (request) => {
|
|
2002
|
+
const { projectId, ...planRequest } = request;
|
|
2003
|
+
if (!projectId)
|
|
2004
|
+
return jsonResult(await runtime.planRoughCut(planRequest));
|
|
2005
|
+
return sessionResult(async () => {
|
|
2006
|
+
const project = await requireHeadlessProjects().open(projectId);
|
|
2007
|
+
return runtime.planRoughCutInProject(planRequest, projectSnapshotFromTimelineIr(project.timeline));
|
|
2008
|
+
});
|
|
2009
|
+
});
|
|
1926
2010
|
server.registerTool("editor.assets", {
|
|
1927
2011
|
description: "Search installed transitions, effects, titles, generators, and templates; filesystem discovery is the default and native Browser discovery is explicit.",
|
|
1928
2012
|
inputSchema: {
|
|
@@ -2309,7 +2393,7 @@ async function effectiveConnectionStatus(runtime, options) {
|
|
|
2309
2393
|
...status,
|
|
2310
2394
|
state: "unavailable",
|
|
2311
2395
|
lastError: {
|
|
2312
|
-
code: "CAPABILITY_UNAVAILABLE",
|
|
2396
|
+
code: message.match(/\bFRAMEKIT_[A-Z_]+\b/)?.[0] ?? "CAPABILITY_UNAVAILABLE",
|
|
2313
2397
|
message: `effective runtime capability inspection failed: ${message}`,
|
|
2314
2398
|
},
|
|
2315
2399
|
identity: undefined,
|
|
@@ -2320,13 +2404,22 @@ async function effectiveConnectionStatus(runtime, options) {
|
|
|
2320
2404
|
}
|
|
2321
2405
|
async function inspectMcpEditor(runtime, options) {
|
|
2322
2406
|
const inspected = await runtime.inspectEditor();
|
|
2407
|
+
const fingerprint = options.buildFingerprint ?? FRAMEKIT_BUILD_FINGERPRINT;
|
|
2408
|
+
const buildAlignment = assessBuildAlignment(fingerprint, inspected.identity.buildFingerprint, options.validationCommit);
|
|
2409
|
+
if (options.requireBuildAlignment && buildAlignment.status !== "matched") {
|
|
2410
|
+
throw new Error(`FRAMEKIT_BUILD_ALIGNMENT_MISMATCH: ${buildAlignment.message}`);
|
|
2411
|
+
}
|
|
2323
2412
|
const native = options.nativeEditor?.capabilities();
|
|
2324
|
-
const
|
|
2325
|
-
const
|
|
2413
|
+
const processMode = options.processMode ?? (native ? "headed" : "headless");
|
|
2414
|
+
const configuredPublisher = Boolean(options.projectPublisher && (typeof options.projectPublisher.isAvailable !== "function" || options.projectPublisher.isAvailable()));
|
|
2415
|
+
const publisherExecutionMode = configuredPublisher
|
|
2326
2416
|
? (typeof options.projectPublisher?.executionMode === "function"
|
|
2327
2417
|
? options.projectPublisher.executionMode()
|
|
2328
2418
|
: "headed-only")
|
|
2329
2419
|
: "unavailable";
|
|
2420
|
+
const publishingAvailable = configuredPublisher && (publisherExecutionMode === "background-capable"
|
|
2421
|
+
|| processMode === "headed");
|
|
2422
|
+
const publishingMode = publishingAvailable ? publisherExecutionMode : "unavailable";
|
|
2330
2423
|
const exportAvailable = Boolean(options.videoExporter?.isAvailable());
|
|
2331
2424
|
const backgroundExportAvailable = Boolean(options.backgroundRenderer?.isAvailable());
|
|
2332
2425
|
const capabilities = withCapabilityFamilies({
|
|
@@ -2399,14 +2492,138 @@ async function inspectMcpEditor(runtime, options) {
|
|
|
2399
2492
|
},
|
|
2400
2493
|
preflight: {
|
|
2401
2494
|
...createCapabilityPreflight(inspected.identity, capabilities, {
|
|
2402
|
-
processMode
|
|
2495
|
+
processMode,
|
|
2403
2496
|
nativeWrite: Boolean(native?.selectionEdit),
|
|
2404
2497
|
}),
|
|
2405
|
-
fingerprint
|
|
2498
|
+
fingerprint,
|
|
2499
|
+
buildAlignment,
|
|
2500
|
+
nativeHandoffReadiness: createNativeHandoffReadiness(options.projectPublisher, buildAlignment),
|
|
2406
2501
|
},
|
|
2407
2502
|
...(native ? { native } : {}),
|
|
2408
2503
|
};
|
|
2409
2504
|
}
|
|
2505
|
+
async function inspectNativeHandoffReadiness(runtime, options, publishJobId) {
|
|
2506
|
+
const fingerprint = options.buildFingerprint ?? FRAMEKIT_BUILD_FINGERPRINT;
|
|
2507
|
+
let extensionFingerprint;
|
|
2508
|
+
try {
|
|
2509
|
+
extensionFingerprint = (await runtime.inspectEditor()).identity.buildFingerprint;
|
|
2510
|
+
}
|
|
2511
|
+
catch {
|
|
2512
|
+
const status = await connectionStatus(options).catch(() => undefined);
|
|
2513
|
+
extensionFingerprint = status?.identity?.buildFingerprint;
|
|
2514
|
+
}
|
|
2515
|
+
const buildAlignment = assessBuildAlignment(fingerprint, extensionFingerprint, options.validationCommit);
|
|
2516
|
+
return createNativeHandoffReadiness(options.projectPublisher, buildAlignment, publishJobId);
|
|
2517
|
+
}
|
|
2518
|
+
function createNativeHandoffReadiness(publisher, buildAlignment, publishJobId) {
|
|
2519
|
+
const publisherReadiness = inspectProjectPublisherReadiness(publisher);
|
|
2520
|
+
const reasons = [...publisherReadiness.reasons];
|
|
2521
|
+
if (buildAlignment.status !== "matched") {
|
|
2522
|
+
reasons.push({
|
|
2523
|
+
code: buildAlignment.status === "mismatched"
|
|
2524
|
+
? "FRAMEKIT_BUILD_ALIGNMENT_MISMATCH"
|
|
2525
|
+
: "FRAMEKIT_BUILD_ALIGNMENT_MISSING",
|
|
2526
|
+
message: `Workflow Extension build alignment is ${buildAlignment.status}: ${buildAlignment.message}`,
|
|
2527
|
+
});
|
|
2528
|
+
}
|
|
2529
|
+
let publish;
|
|
2530
|
+
let verifiedTarget;
|
|
2531
|
+
if (publishJobId) {
|
|
2532
|
+
if (!publisher || typeof publisher.getPublishJob !== "function") {
|
|
2533
|
+
reasons.push({
|
|
2534
|
+
code: "FINAL_CUT_PUBLISH_JOB_UNAVAILABLE",
|
|
2535
|
+
message: `Publish job ${publishJobId} cannot be inspected because the publisher is unavailable`,
|
|
2536
|
+
});
|
|
2537
|
+
}
|
|
2538
|
+
else {
|
|
2539
|
+
try {
|
|
2540
|
+
const job = publisher.getPublishJob(publishJobId);
|
|
2541
|
+
publish = { jobId: job.jobId, state: job.state };
|
|
2542
|
+
const resultTarget = job.result?.createdTarget;
|
|
2543
|
+
const targetMatches = job.createdTarget
|
|
2544
|
+
&& resultTarget
|
|
2545
|
+
&& job.createdTarget.projectId === resultTarget.projectId
|
|
2546
|
+
&& job.createdTarget.sequenceId === resultTarget.sequenceId;
|
|
2547
|
+
if (job.state === "verified" && job.result?.verified === true && targetMatches) {
|
|
2548
|
+
verifiedTarget = resultTarget;
|
|
2549
|
+
}
|
|
2550
|
+
else {
|
|
2551
|
+
reasons.push({
|
|
2552
|
+
code: "FINAL_CUT_PUBLISH_TARGET_UNVERIFIED",
|
|
2553
|
+
message: job.error?.message
|
|
2554
|
+
? `Publish job ${job.jobId} is ${job.state}; native project and sequence IDs remain withheld: ${job.error.message}`
|
|
2555
|
+
: `Publish job ${job.jobId} is ${job.state}; native project and sequence IDs are reported only after native readback verifies them`,
|
|
2556
|
+
});
|
|
2557
|
+
}
|
|
2558
|
+
}
|
|
2559
|
+
catch (error) {
|
|
2560
|
+
const message = error instanceof Error ? error.message : String(error);
|
|
2561
|
+
reasons.push({
|
|
2562
|
+
code: "FINAL_CUT_PUBLISH_JOB_UNAVAILABLE",
|
|
2563
|
+
message: `Publish job ${publishJobId} could not be inspected: ${message}`,
|
|
2564
|
+
});
|
|
2565
|
+
}
|
|
2566
|
+
}
|
|
2567
|
+
}
|
|
2568
|
+
const ready = reasons.length === 0;
|
|
2569
|
+
return {
|
|
2570
|
+
status: ready ? (publishJobId ? "verified" : "ready") : "blocked",
|
|
2571
|
+
reasons,
|
|
2572
|
+
targetBinding: {
|
|
2573
|
+
available: publisherReadiness.targetBindingAvailable,
|
|
2574
|
+
guarantee: publisherReadiness.targetBindingAvailable ? "native-readback" : "none",
|
|
2575
|
+
},
|
|
2576
|
+
buildAlignment,
|
|
2577
|
+
...(publish ? { publish } : {}),
|
|
2578
|
+
...(ready && verifiedTarget ? { createdTarget: verifiedTarget } : {}),
|
|
2579
|
+
};
|
|
2580
|
+
}
|
|
2581
|
+
function inspectProjectPublisherReadiness(publisher) {
|
|
2582
|
+
if (!publisher) {
|
|
2583
|
+
return {
|
|
2584
|
+
available: false,
|
|
2585
|
+
targetBindingAvailable: false,
|
|
2586
|
+
reasons: [{
|
|
2587
|
+
code: "FINAL_CUT_PUBLISH_PROVIDER_UNAVAILABLE",
|
|
2588
|
+
message: "No Final Cut project publisher is configured",
|
|
2589
|
+
}],
|
|
2590
|
+
};
|
|
2591
|
+
}
|
|
2592
|
+
if (typeof publisher.inspectReadiness === "function")
|
|
2593
|
+
return publisher.inspectReadiness();
|
|
2594
|
+
// Keep older injected publisher implementations fail-closed but inspectable.
|
|
2595
|
+
const available = typeof publisher.isAvailable === "function" && publisher.isAvailable();
|
|
2596
|
+
return {
|
|
2597
|
+
available,
|
|
2598
|
+
targetBindingAvailable: available,
|
|
2599
|
+
reasons: available ? [] : [{
|
|
2600
|
+
code: "FINAL_CUT_PUBLISH_TARGET_BINDING_UNAVAILABLE",
|
|
2601
|
+
message: "Native publisher readiness or target-binding provider is unavailable",
|
|
2602
|
+
}],
|
|
2603
|
+
};
|
|
2604
|
+
}
|
|
2605
|
+
async function assertRequiredBuildAlignment(runtime, options) {
|
|
2606
|
+
const inspected = await runtime.inspectEditor();
|
|
2607
|
+
const fingerprint = options.buildFingerprint ?? FRAMEKIT_BUILD_FINGERPRINT;
|
|
2608
|
+
const alignment = assessBuildAlignment(fingerprint, inspected.identity.buildFingerprint, options.validationCommit);
|
|
2609
|
+
if (alignment.status !== "matched") {
|
|
2610
|
+
throw new Error(`FRAMEKIT_BUILD_ALIGNMENT_MISMATCH: ${alignment.message}`);
|
|
2611
|
+
}
|
|
2612
|
+
}
|
|
2613
|
+
function withBuildAlignmentGuard(provider, assertAlignment, synchronousMethods = []) {
|
|
2614
|
+
const synchronous = new Set(synchronousMethods);
|
|
2615
|
+
return new Proxy(provider, {
|
|
2616
|
+
get(target, property) {
|
|
2617
|
+
const value = Reflect.get(target, property, target);
|
|
2618
|
+
if (typeof value !== "function" || synchronous.has(property))
|
|
2619
|
+
return value;
|
|
2620
|
+
return async (...args) => {
|
|
2621
|
+
await assertAlignment();
|
|
2622
|
+
return Reflect.apply(value, target, args);
|
|
2623
|
+
};
|
|
2624
|
+
},
|
|
2625
|
+
});
|
|
2626
|
+
}
|
|
2410
2627
|
function requireArtifactTransaction(runtime, transactionId, artifactPath) {
|
|
2411
2628
|
const transaction = runtime.getTransaction(transactionId);
|
|
2412
2629
|
const target = transaction.target;
|
|
@@ -2428,6 +2645,9 @@ async function requireEditingRoute(runtime, options, operation, path, editType)
|
|
|
2428
2645
|
throw new Error(`${route.reason.code}: ${route.reason.message}`);
|
|
2429
2646
|
}
|
|
2430
2647
|
}
|
|
2648
|
+
function requiresHeadedPublishingRoute(publisher) {
|
|
2649
|
+
return publisher.executionMode() !== "background-capable";
|
|
2650
|
+
}
|
|
2431
2651
|
async function editingRouteContext(runtime, options) {
|
|
2432
2652
|
const connection = await effectiveConnectionStatus(runtime, options);
|
|
2433
2653
|
let nativeReadiness;
|
|
@@ -2449,18 +2669,19 @@ async function editingRouteContext(runtime, options) {
|
|
|
2449
2669
|
return {
|
|
2450
2670
|
connection,
|
|
2451
2671
|
...(editor ? { editor } : {}),
|
|
2452
|
-
...(options
|
|
2453
|
-
headless: {
|
|
2454
|
-
available: true,
|
|
2455
|
-
backend: "framekit-project-store",
|
|
2456
|
-
guarantee: "canonical-write",
|
|
2457
|
-
// Advertise only concrete Timeline IR edit capabilities. The legacy
|
|
2458
|
-
// timeline.edit surface also accepts operations that the headless
|
|
2459
|
-
// transaction layer does not implement.
|
|
2460
|
-
supportedOperations: HEADLESS_TIMELINE_EDIT_TYPES.map((editType) => `timeline.edit:${editType}`),
|
|
2461
|
-
},
|
|
2462
|
-
} : {}),
|
|
2672
|
+
...headlessRoutingContext(options),
|
|
2463
2673
|
...(options.nativeEditor ? { native: { ...options.nativeEditor.capabilities() } } : {}),
|
|
2464
2674
|
...(nativeReadiness ? { nativeReadiness } : {}),
|
|
2465
2675
|
};
|
|
2466
2676
|
}
|
|
2677
|
+
function headlessRoutingContext(options) {
|
|
2678
|
+
return options.headlessProjects ? {
|
|
2679
|
+
headless: {
|
|
2680
|
+
available: true,
|
|
2681
|
+
backend: "framekit-project-store",
|
|
2682
|
+
guarantee: "canonical-write",
|
|
2683
|
+
// The legacy timeline.edit surface also includes unsupported operations.
|
|
2684
|
+
supportedOperations: HEADLESS_TIMELINE_EDIT_TYPES.map((editType) => `timeline.edit:${editType}`),
|
|
2685
|
+
},
|
|
2686
|
+
} : {};
|
|
2687
|
+
}
|
|
@@ -1,6 +1,7 @@
|
|
|
1
1
|
import { readFileSync } from "node:fs";
|
|
2
2
|
import { dirname, isAbsolute, join, resolve } from "node:path";
|
|
3
3
|
import { fileURLToPath } from "node:url";
|
|
4
|
+
import { parsePackageBuildIdentity } from "./build-identity.js";
|
|
4
5
|
const FRAMEKIT_PACKAGE_NAME = "@morshoto/framekit";
|
|
5
6
|
export const FRAMEKIT_VERSION = readFramekitVersion();
|
|
6
7
|
export const FRAMEKIT_BUILD_FINGERPRINT = Object.freeze({
|
|
@@ -38,8 +39,15 @@ function isMissingFile(error) {
|
|
|
38
39
|
}
|
|
39
40
|
function readFramekitCommit() {
|
|
40
41
|
const configured = process.env.FRAMEKIT_BUILD_COMMIT?.trim();
|
|
41
|
-
if (configured)
|
|
42
|
-
|
|
42
|
+
if (configured) {
|
|
43
|
+
if (!/^[0-9a-f]{40}$/i.test(configured)) {
|
|
44
|
+
throw new Error("FRAMEKIT_BUILD_COMMIT_INVALID: expected a full commit SHA");
|
|
45
|
+
}
|
|
46
|
+
return configured.toLowerCase();
|
|
47
|
+
}
|
|
48
|
+
const packaged = readPackageBuildIdentity();
|
|
49
|
+
if (packaged)
|
|
50
|
+
return packaged.commit;
|
|
43
51
|
const repositoryRoot = findRepositoryRoot(dirname(fileURLToPath(import.meta.url)));
|
|
44
52
|
if (!repositoryRoot)
|
|
45
53
|
return "unknown";
|
|
@@ -85,6 +93,17 @@ function readFramekitCommit() {
|
|
|
85
93
|
}
|
|
86
94
|
return "unknown";
|
|
87
95
|
}
|
|
96
|
+
function readPackageBuildIdentity() {
|
|
97
|
+
try {
|
|
98
|
+
const identityPath = join(dirname(fileURLToPath(import.meta.url)), "build-identity.json");
|
|
99
|
+
return parsePackageBuildIdentity(JSON.parse(readFileSync(identityPath, "utf8")), FRAMEKIT_VERSION);
|
|
100
|
+
}
|
|
101
|
+
catch (error) {
|
|
102
|
+
if (isMissingFile(error))
|
|
103
|
+
return undefined;
|
|
104
|
+
throw error;
|
|
105
|
+
}
|
|
106
|
+
}
|
|
88
107
|
function findRepositoryRoot(start) {
|
|
89
108
|
let directory = start;
|
|
90
109
|
while (true) {
|
|
@@ -121,10 +121,14 @@ export class MediaAnalysisService {
|
|
|
121
121
|
}
|
|
122
122
|
async understandMedia(mediaId) {
|
|
123
123
|
const project = await this.project.inspectProject();
|
|
124
|
+
return this.understandMediaInProject(mediaId, project, true);
|
|
125
|
+
}
|
|
126
|
+
async understandMediaInProject(mediaId, project, attachToLiveContext = false) {
|
|
124
127
|
const media = findMedia(project, mediaId);
|
|
125
128
|
const cached = await this.loadCachedUnderstanding(project, media);
|
|
126
129
|
if (cached) {
|
|
127
|
-
|
|
130
|
+
if (attachToLiveContext)
|
|
131
|
+
this.context.attachMediaUnderstanding(cached);
|
|
128
132
|
return structuredClone(cached);
|
|
129
133
|
}
|
|
130
134
|
const input = { project, media };
|
|
@@ -160,7 +164,8 @@ export class MediaAnalysisService {
|
|
|
160
164
|
],
|
|
161
165
|
analysisRevision: project.revision,
|
|
162
166
|
};
|
|
163
|
-
|
|
167
|
+
if (attachToLiveContext)
|
|
168
|
+
this.context.attachMediaUnderstanding(understanding);
|
|
164
169
|
await this.options.semanticMediaIndexStore?.save(understanding);
|
|
165
170
|
return structuredClone(understanding);
|
|
166
171
|
}
|
|
@@ -179,10 +184,15 @@ export class MediaAnalysisService {
|
|
|
179
184
|
}
|
|
180
185
|
async planRoughCut(request) {
|
|
181
186
|
const project = await this.project.inspectProject();
|
|
187
|
+
return this.planRoughCutInProject(request, project);
|
|
188
|
+
}
|
|
189
|
+
async planRoughCutInProject(request, project) {
|
|
182
190
|
const { maxShots: _maxShots, ...query } = request;
|
|
183
191
|
const current = this.indexFromProject(project, query);
|
|
184
192
|
const persisted = await this.persistedIndexEntries(query);
|
|
185
|
-
|
|
193
|
+
const projectMedia = project.media.map(sourceIdentityOf);
|
|
194
|
+
const matchingPersisted = persisted.filter((entry) => projectMedia.some((source) => sameMediaSourceIdentity(source, entry.sourceIdentity)));
|
|
195
|
+
return planRoughCut(mergeIndexEntries(matchingPersisted, current), project.revision, request);
|
|
186
196
|
}
|
|
187
197
|
async inspectTimelineSemanticContext(query = {}) {
|
|
188
198
|
const project = await this.project.inspectProject();
|
|
@@ -706,7 +716,7 @@ function emptySemanticDescription() {
|
|
|
706
716
|
};
|
|
707
717
|
}
|
|
708
718
|
function matchesMediaIndexQuery(entry, query) {
|
|
709
|
-
const
|
|
719
|
+
const terms = query.query?.trim().toLowerCase().split(/\s+/u).filter(Boolean) ?? [];
|
|
710
720
|
const values = [
|
|
711
721
|
entry.sourceIdentity.mediaId,
|
|
712
722
|
entry.sourceIdentity.source,
|
|
@@ -717,7 +727,7 @@ function matchesMediaIndexQuery(entry, query) {
|
|
|
717
727
|
...entry.semantic.timeOfDay.map((tag) => tag.value),
|
|
718
728
|
...entry.semantic.moods.map((tag) => tag.value),
|
|
719
729
|
].map((value) => value.toLowerCase());
|
|
720
|
-
if (
|
|
730
|
+
if (terms.length > 0 && !values.some((value) => terms.some((term) => value.includes(term))))
|
|
721
731
|
return false;
|
|
722
732
|
if (query.subject && !matchesTag(entry.semantic.subjects, query.subject))
|
|
723
733
|
return false;
|
|
@@ -165,6 +165,9 @@ export class AgentVideoRuntime {
|
|
|
165
165
|
async understandMedia(mediaId) {
|
|
166
166
|
return this.media.understandMedia(mediaId);
|
|
167
167
|
}
|
|
168
|
+
async understandMediaInProject(mediaId, project) {
|
|
169
|
+
return this.media.understandMediaInProject(mediaId, project);
|
|
170
|
+
}
|
|
168
171
|
planDuration(request) {
|
|
169
172
|
return this.durationPolicy.plan(request);
|
|
170
173
|
}
|
|
@@ -180,6 +183,9 @@ export class AgentVideoRuntime {
|
|
|
180
183
|
async planRoughCut(request) {
|
|
181
184
|
return this.media.planRoughCut(request);
|
|
182
185
|
}
|
|
186
|
+
async planRoughCutInProject(request, project) {
|
|
187
|
+
return this.media.planRoughCutInProject(request, project);
|
|
188
|
+
}
|
|
183
189
|
async inspectTimelineSemanticContext(query = {}) {
|
|
184
190
|
return this.media.inspectTimelineSemanticContext(query);
|
|
185
191
|
}
|
|
@@ -386,8 +386,13 @@ function validateMediaMetadata(metadata, field) {
|
|
|
386
386
|
if (stream.codec !== undefined)
|
|
387
387
|
requireText(stream.codec, `${streamField}.codec`);
|
|
388
388
|
if (stream.kind === "video") {
|
|
389
|
-
|
|
390
|
-
|
|
389
|
+
if ((stream.width === undefined) !== (stream.height === undefined)) {
|
|
390
|
+
throw new Error(`TIMELINE_IR_INVALID: ${streamField}.width and height must be provided together`);
|
|
391
|
+
}
|
|
392
|
+
if (stream.width !== undefined && stream.height !== undefined) {
|
|
393
|
+
requirePositiveInteger(stream.width, `${streamField}.width`);
|
|
394
|
+
requirePositiveInteger(stream.height, `${streamField}.height`);
|
|
395
|
+
}
|
|
391
396
|
if (!stream.frameRate)
|
|
392
397
|
throw new Error(`TIMELINE_IR_INVALID: ${streamField}.frameRate is required`);
|
|
393
398
|
validateRational(stream.frameRate, `${streamField}.frameRate`, true);
|