@morshoto/framekit 0.1.10 → 0.1.12
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 +1 -0
- package/dist-package/adapters/final-cut/typescript/src/analyzers.js +68 -5
- package/dist-package/adapters/final-cut/typescript/src/background-materialization.js +175 -0
- package/dist-package/adapters/final-cut/typescript/src/canonical-recovery.js +31 -0
- package/dist-package/adapters/final-cut/typescript/src/canonical-verification.js +16 -0
- package/dist-package/adapters/final-cut/typescript/src/canonical.js +600 -56
- package/dist-package/adapters/final-cut/typescript/src/connection.js +52 -14
- package/dist-package/adapters/final-cut/typescript/src/fcpxml-console-experiment.js +74 -0
- package/dist-package/adapters/final-cut/typescript/src/index.js +9 -0
- package/dist-package/adapters/final-cut/typescript/src/live.js +11 -4
- package/dist-package/adapters/final-cut/typescript/src/native.js +321 -19
- package/dist-package/adapters/final-cut/typescript/src/session.js +19 -1
- package/dist-package/adapters/final-cut/typescript/src/shadow-mutation.js +174 -0
- package/dist-package/adapters/final-cut/typescript/src/sqlite-experiment.js +472 -0
- package/dist-package/adapters/final-cut/typescript/src/sqlite-inspection.js +433 -0
- package/dist-package/adapters/final-cut/typescript/src/sqlite-materialization.js +230 -0
- package/dist-package/adapters/final-cut/typescript/src/timeline-ir-fcpxml.js +372 -0
- package/dist-package/adapters/final-cut/typescript/src/unattended-editing.js +66 -0
- package/dist-package/apps/mcp-server/src/headless-sessions.js +112 -0
- package/dist-package/apps/mcp-server/src/main.js +36 -2
- package/dist-package/apps/mcp-server/src/materialization-jobs.js +326 -0
- package/dist-package/apps/mcp-server/src/routing.js +17 -0
- package/dist-package/apps/mcp-server/src/server.js +146 -12
- package/dist-package/packages/runtime/src/application/media-analysis-service.js +52 -6
- package/dist-package/packages/runtime/src/context/project-catalog.js +46 -1
- package/dist-package/packages/runtime/src/index.js +2 -0
- package/dist-package/packages/runtime/src/skills/builtin.js +99 -8
- package/dist-package/packages/runtime/src/skills/runtime.js +1 -0
- package/dist-package/packages/runtime/src/timeline/drift-reconciliation.js +295 -0
- package/dist-package/packages/runtime/src/timeline/editing-session.js +490 -0
- package/package.json +10 -6
|
@@ -0,0 +1,326 @@
|
|
|
1
|
+
import { createHash, randomUUID } from "node:crypto";
|
|
2
|
+
import { mkdir, readFile, rename, unlink, writeFile } from "node:fs/promises";
|
|
3
|
+
import { dirname, join } from "node:path";
|
|
4
|
+
import { timelineIrDigest } from "../../../packages/runtime/src/index.js";
|
|
5
|
+
import { compileTimelineIrToFcpxml, } from "../../../adapters/final-cut/typescript/src/index.js";
|
|
6
|
+
export class SessionMaterializationJobs {
|
|
7
|
+
directory;
|
|
8
|
+
sessions;
|
|
9
|
+
publisher;
|
|
10
|
+
constructor(directory, sessions, publisher) {
|
|
11
|
+
this.directory = directory;
|
|
12
|
+
this.sessions = sessions;
|
|
13
|
+
this.publisher = publisher;
|
|
14
|
+
}
|
|
15
|
+
async preview(sessionId, target) {
|
|
16
|
+
const session = await this.sessions.loadForMaterialization(sessionId);
|
|
17
|
+
this.assertProvider(session.document().provider?.id, target.provider);
|
|
18
|
+
session.assertMaterializationReady(session.base().revision);
|
|
19
|
+
const artifact = compileTimelineIrToFcxmlVersioned(session.desired(), target);
|
|
20
|
+
return {
|
|
21
|
+
sessionId,
|
|
22
|
+
mutating: false,
|
|
23
|
+
sessionState: session.state(),
|
|
24
|
+
target: artifact.target,
|
|
25
|
+
destination: artifact.destination,
|
|
26
|
+
collisionPolicy: "create-only",
|
|
27
|
+
artifactDigest: artifact.digest,
|
|
28
|
+
evidence: { artifact: { verified: true, format: "fcpxml", digest: artifact.digest } },
|
|
29
|
+
};
|
|
30
|
+
}
|
|
31
|
+
async execute(sessionId, target, confirm) {
|
|
32
|
+
if (!confirm)
|
|
33
|
+
throw new Error("MATERIALIZATION_CONFIRMATION_REQUIRED: set confirm=true to stage and publish a versioned project");
|
|
34
|
+
const session = await this.sessions.loadForMaterialization(sessionId);
|
|
35
|
+
this.assertProvider(session.document().provider?.id, target.provider);
|
|
36
|
+
session.assertMaterializationReady(session.base().revision);
|
|
37
|
+
const desired = session.desired();
|
|
38
|
+
const artifact = compileTimelineIrToFcxmlVersioned(desired, target);
|
|
39
|
+
const jobId = `materialization-${randomUUID()}`;
|
|
40
|
+
const artifactPath = join(this.directory, "artifacts", `${jobId}.fcpxml`);
|
|
41
|
+
await mkdir(dirname(artifactPath), { recursive: true });
|
|
42
|
+
await writeFile(artifactPath, artifact.xml, { encoding: "utf8", flag: "wx" });
|
|
43
|
+
session.markWaitingForMaterialization();
|
|
44
|
+
await this.sessions.checkpoint(sessionId, session);
|
|
45
|
+
let job = {
|
|
46
|
+
schemaVersion: 1,
|
|
47
|
+
jobId,
|
|
48
|
+
sessionId,
|
|
49
|
+
state: "blocked",
|
|
50
|
+
nextAction: "retry",
|
|
51
|
+
artifactPath,
|
|
52
|
+
artifactDigest: artifact.digest,
|
|
53
|
+
target: artifact.target,
|
|
54
|
+
destination: artifact.destination,
|
|
55
|
+
desired: structuredClone(desired),
|
|
56
|
+
desiredDigest: timelineIrDigest(desired),
|
|
57
|
+
sessionDigest: digestSession(session),
|
|
58
|
+
evidence: {
|
|
59
|
+
artifact: { verified: true, format: "fcpxml", digest: artifact.digest },
|
|
60
|
+
providerRequested: false,
|
|
61
|
+
canonicalReadback: false,
|
|
62
|
+
headedNative: false,
|
|
63
|
+
},
|
|
64
|
+
error: {
|
|
65
|
+
code: "MATERIALIZATION_PROVIDER_UNAVAILABLE",
|
|
66
|
+
message: "No Final Cut materialization publisher is configured; retry when a provider is available",
|
|
67
|
+
retryable: true,
|
|
68
|
+
},
|
|
69
|
+
};
|
|
70
|
+
await this.save(job);
|
|
71
|
+
return this.attempt(job);
|
|
72
|
+
}
|
|
73
|
+
async status(jobId) {
|
|
74
|
+
try {
|
|
75
|
+
const job = JSON.parse(await readFile(this.jobPath(jobId), "utf8"));
|
|
76
|
+
if (job.schemaVersion !== 1 || job.jobId !== jobId)
|
|
77
|
+
throw new Error("MATERIALIZATION_JOB_INVALID: persisted job is invalid");
|
|
78
|
+
return structuredClone(job);
|
|
79
|
+
}
|
|
80
|
+
catch (error) {
|
|
81
|
+
if (error.code === "ENOENT") {
|
|
82
|
+
throw new Error(`MATERIALIZATION_JOB_NOT_FOUND: unknown materialization job ${jobId}`);
|
|
83
|
+
}
|
|
84
|
+
throw error;
|
|
85
|
+
}
|
|
86
|
+
}
|
|
87
|
+
async retry(jobId) {
|
|
88
|
+
const job = await this.status(jobId);
|
|
89
|
+
if (job.state === "publishing" || job.state === "completed" || job.state === "failed")
|
|
90
|
+
return job;
|
|
91
|
+
if (!job.error?.retryable)
|
|
92
|
+
throw new Error(`MATERIALIZATION_NOT_RETRYABLE: job ${jobId} cannot be retried`);
|
|
93
|
+
return this.attempt(job);
|
|
94
|
+
}
|
|
95
|
+
async attempt(job) {
|
|
96
|
+
if (!this.publisher || job.state === "publishing")
|
|
97
|
+
return job;
|
|
98
|
+
const initialFailure = await this.validateStagedJob(job);
|
|
99
|
+
if (initialFailure)
|
|
100
|
+
return this.fail(job, initialFailure);
|
|
101
|
+
const claim = await this.claim(job);
|
|
102
|
+
if (!claim.owned)
|
|
103
|
+
return claim.job;
|
|
104
|
+
const claimed = claim.job;
|
|
105
|
+
try {
|
|
106
|
+
const finalFailure = await this.validateStagedJob(claimed);
|
|
107
|
+
if (finalFailure)
|
|
108
|
+
return this.fail(claimed, finalFailure);
|
|
109
|
+
const result = await this.publisher.publish({
|
|
110
|
+
jobId: claimed.jobId,
|
|
111
|
+
artifactPath: claimed.artifactPath,
|
|
112
|
+
artifactDigest: claimed.artifactDigest,
|
|
113
|
+
target: claimed.target,
|
|
114
|
+
destination: claimed.destination,
|
|
115
|
+
collisionPolicy: "create-only",
|
|
116
|
+
desired: structuredClone(claimed.desired),
|
|
117
|
+
desiredDigest: claimed.desiredDigest,
|
|
118
|
+
});
|
|
119
|
+
if (result.state === "blocked") {
|
|
120
|
+
const blocked = {
|
|
121
|
+
...claimed,
|
|
122
|
+
state: "blocked",
|
|
123
|
+
nextAction: "retry",
|
|
124
|
+
claim: undefined,
|
|
125
|
+
evidence: { ...claimed.evidence, providerRequested: true },
|
|
126
|
+
error: { code: result.code, message: result.message, retryable: result.retryable },
|
|
127
|
+
};
|
|
128
|
+
await this.save(blocked);
|
|
129
|
+
return blocked;
|
|
130
|
+
}
|
|
131
|
+
if (timelineIrDigest(result.canonicalReadback) !== claimed.desiredDigest) {
|
|
132
|
+
return this.fail(claimed, {
|
|
133
|
+
code: "MATERIALIZATION_READBACK_MISMATCH",
|
|
134
|
+
message: "Canonical provider readback does not match the desired Timeline IR",
|
|
135
|
+
retryable: false,
|
|
136
|
+
providerRequested: true,
|
|
137
|
+
});
|
|
138
|
+
}
|
|
139
|
+
const expectedTarget = {
|
|
140
|
+
libraryUid: claimed.target.libraryUid,
|
|
141
|
+
eventUid: claimed.target.eventUid,
|
|
142
|
+
projectUid: claimed.destination.projectUid,
|
|
143
|
+
sequenceUid: claimed.destination.sequenceUid,
|
|
144
|
+
};
|
|
145
|
+
if (!sameTarget(result.canonicalTarget, expectedTarget)) {
|
|
146
|
+
return this.fail(claimed, {
|
|
147
|
+
code: "MATERIALIZATION_TARGET_READBACK_MISMATCH",
|
|
148
|
+
message: "Canonical provider readback does not identify the staged versioned target",
|
|
149
|
+
retryable: false,
|
|
150
|
+
providerRequested: true,
|
|
151
|
+
});
|
|
152
|
+
}
|
|
153
|
+
const completed = {
|
|
154
|
+
...claimed,
|
|
155
|
+
state: "completed",
|
|
156
|
+
nextAction: "none",
|
|
157
|
+
claim: undefined,
|
|
158
|
+
evidence: {
|
|
159
|
+
...claimed.evidence,
|
|
160
|
+
providerRequested: true,
|
|
161
|
+
canonicalReadback: true,
|
|
162
|
+
headedNative: result.headedNativeVerified,
|
|
163
|
+
},
|
|
164
|
+
error: undefined,
|
|
165
|
+
};
|
|
166
|
+
await this.save(completed);
|
|
167
|
+
return completed;
|
|
168
|
+
}
|
|
169
|
+
catch (error) {
|
|
170
|
+
return this.fail(claimed, materializationFailure(error, true));
|
|
171
|
+
}
|
|
172
|
+
finally {
|
|
173
|
+
await this.release(claimed.jobId, claimed.claim.id);
|
|
174
|
+
}
|
|
175
|
+
}
|
|
176
|
+
async validateStagedJob(job) {
|
|
177
|
+
if (!job.desired || !job.desiredDigest || timelineIrDigest(job.desired) !== job.desiredDigest) {
|
|
178
|
+
return {
|
|
179
|
+
code: "MATERIALIZATION_DESIRED_SNAPSHOT_INVALID",
|
|
180
|
+
message: "The staged desired Timeline IR is unavailable or does not match its immutable digest",
|
|
181
|
+
retryable: false,
|
|
182
|
+
};
|
|
183
|
+
}
|
|
184
|
+
if (!job.sessionDigest) {
|
|
185
|
+
return {
|
|
186
|
+
code: "MATERIALIZATION_SESSION_SNAPSHOT_INVALID",
|
|
187
|
+
message: "The materialization job has no immutable session snapshot digest",
|
|
188
|
+
retryable: false,
|
|
189
|
+
};
|
|
190
|
+
}
|
|
191
|
+
try {
|
|
192
|
+
const session = await this.sessions.loadForMaterialization(job.sessionId);
|
|
193
|
+
if (digestSession(session) !== job.sessionDigest) {
|
|
194
|
+
return {
|
|
195
|
+
code: "MATERIALIZATION_SESSION_CHANGED",
|
|
196
|
+
message: "The editing session changed after materialization staging; reconcile before retrying",
|
|
197
|
+
retryable: false,
|
|
198
|
+
};
|
|
199
|
+
}
|
|
200
|
+
const artifact = await readFile(job.artifactPath, "utf8");
|
|
201
|
+
if (createHash("sha256").update(artifact).digest("hex") !== job.artifactDigest) {
|
|
202
|
+
return {
|
|
203
|
+
code: "MATERIALIZATION_ARTIFACT_CHANGED",
|
|
204
|
+
message: "The staged FCPXML artifact no longer matches its immutable digest",
|
|
205
|
+
retryable: false,
|
|
206
|
+
};
|
|
207
|
+
}
|
|
208
|
+
return undefined;
|
|
209
|
+
}
|
|
210
|
+
catch (error) {
|
|
211
|
+
return materializationFailure(error, false);
|
|
212
|
+
}
|
|
213
|
+
}
|
|
214
|
+
async claim(job) {
|
|
215
|
+
const claimPath = this.claimPath(job.jobId);
|
|
216
|
+
const claim = { id: randomUUID(), claimedAt: new Date().toISOString() };
|
|
217
|
+
try {
|
|
218
|
+
await writeFile(claimPath, `${JSON.stringify({ jobId: job.jobId, ...claim })}\n`, { encoding: "utf8", flag: "wx" });
|
|
219
|
+
}
|
|
220
|
+
catch (error) {
|
|
221
|
+
if (error.code !== "EEXIST")
|
|
222
|
+
throw error;
|
|
223
|
+
const current = await this.status(job.jobId);
|
|
224
|
+
if (current.state !== "blocked")
|
|
225
|
+
return { job: current, owned: false };
|
|
226
|
+
try {
|
|
227
|
+
const existing = JSON.parse(await readFile(claimPath, "utf8"));
|
|
228
|
+
if (existing.id && existing.claimedAt) {
|
|
229
|
+
return {
|
|
230
|
+
job: { ...current, state: "publishing", nextAction: "status", claim: { id: existing.id, claimedAt: existing.claimedAt } },
|
|
231
|
+
owned: false,
|
|
232
|
+
};
|
|
233
|
+
}
|
|
234
|
+
}
|
|
235
|
+
catch {
|
|
236
|
+
// The owner may be between creating the claim and persisting state.
|
|
237
|
+
}
|
|
238
|
+
return { job: { ...current, state: "publishing", nextAction: "status" }, owned: false };
|
|
239
|
+
}
|
|
240
|
+
const claimed = {
|
|
241
|
+
...job,
|
|
242
|
+
state: "publishing",
|
|
243
|
+
nextAction: "status",
|
|
244
|
+
claim,
|
|
245
|
+
};
|
|
246
|
+
try {
|
|
247
|
+
await this.save(claimed);
|
|
248
|
+
return { job: claimed, owned: true };
|
|
249
|
+
}
|
|
250
|
+
catch (error) {
|
|
251
|
+
await unlink(claimPath).catch(() => undefined);
|
|
252
|
+
throw error;
|
|
253
|
+
}
|
|
254
|
+
}
|
|
255
|
+
async release(jobId, claimId) {
|
|
256
|
+
const path = this.claimPath(jobId);
|
|
257
|
+
try {
|
|
258
|
+
const current = JSON.parse(await readFile(path, "utf8"));
|
|
259
|
+
if (current.id === claimId)
|
|
260
|
+
await unlink(path);
|
|
261
|
+
}
|
|
262
|
+
catch (error) {
|
|
263
|
+
if (error.code !== "ENOENT")
|
|
264
|
+
throw error;
|
|
265
|
+
}
|
|
266
|
+
}
|
|
267
|
+
async fail(job, failure) {
|
|
268
|
+
const failed = {
|
|
269
|
+
...job,
|
|
270
|
+
state: "failed",
|
|
271
|
+
nextAction: "none",
|
|
272
|
+
claim: undefined,
|
|
273
|
+
evidence: {
|
|
274
|
+
...job.evidence,
|
|
275
|
+
providerRequested: failure.providerRequested ?? job.evidence.providerRequested,
|
|
276
|
+
},
|
|
277
|
+
error: {
|
|
278
|
+
code: failure.code,
|
|
279
|
+
message: failure.message,
|
|
280
|
+
retryable: failure.retryable,
|
|
281
|
+
},
|
|
282
|
+
};
|
|
283
|
+
await this.save(failed);
|
|
284
|
+
return failed;
|
|
285
|
+
}
|
|
286
|
+
async save(job) {
|
|
287
|
+
const path = this.jobPath(job.jobId);
|
|
288
|
+
await mkdir(dirname(path), { recursive: true });
|
|
289
|
+
const temporary = `${path}.${randomUUID()}.tmp`;
|
|
290
|
+
await writeFile(temporary, `${JSON.stringify(job)}\n`, { encoding: "utf8", flag: "wx" });
|
|
291
|
+
await rename(temporary, path);
|
|
292
|
+
}
|
|
293
|
+
jobPath(jobId) {
|
|
294
|
+
if (!/^materialization-[A-Za-z0-9-]+$/.test(jobId))
|
|
295
|
+
throw new Error("MATERIALIZATION_JOB_ID_INVALID: invalid jobId");
|
|
296
|
+
return join(this.directory, "jobs", `${jobId}.json`);
|
|
297
|
+
}
|
|
298
|
+
claimPath(jobId) {
|
|
299
|
+
return `${this.jobPath(jobId)}.claim`;
|
|
300
|
+
}
|
|
301
|
+
assertProvider(sessionProvider, targetProvider) {
|
|
302
|
+
if (sessionProvider && sessionProvider !== targetProvider) {
|
|
303
|
+
throw new Error(`SESSION_PROVIDER_MISMATCH: expected ${sessionProvider}, received ${targetProvider}`);
|
|
304
|
+
}
|
|
305
|
+
}
|
|
306
|
+
}
|
|
307
|
+
function digestSession(session) {
|
|
308
|
+
return createHash("sha256").update(session.serialize()).digest("hex");
|
|
309
|
+
}
|
|
310
|
+
function compileTimelineIrToFcxmlVersioned(desired, target) {
|
|
311
|
+
if (target.materialization === "reuse-existing") {
|
|
312
|
+
throw new Error("FINAL_CUT_BACKGROUND_MATERIALIZATION_REUSE_FORBIDDEN: materialization jobs are create-only");
|
|
313
|
+
}
|
|
314
|
+
return compileTimelineIrToFcpxml(desired, { target: { ...target, materialization: "versioned" } });
|
|
315
|
+
}
|
|
316
|
+
function materializationFailure(error, providerRequested) {
|
|
317
|
+
const message = error instanceof Error ? error.message : String(error);
|
|
318
|
+
const code = message.match(/^([A-Z][A-Z0-9_]*):/)?.[1] ?? "MATERIALIZATION_PUBLISH_FAILED";
|
|
319
|
+
return { code, message, retryable: false, providerRequested };
|
|
320
|
+
}
|
|
321
|
+
function sameTarget(actual, expected) {
|
|
322
|
+
return actual?.libraryUid === expected.libraryUid
|
|
323
|
+
&& actual.eventUid === expected.eventUid
|
|
324
|
+
&& actual.projectUid === expected.projectUid
|
|
325
|
+
&& actual.sequenceUid === expected.sequenceUid;
|
|
326
|
+
}
|
|
@@ -99,6 +99,7 @@ export function resolveEditingRoute(request, context) {
|
|
|
99
99
|
const missingRequirements = requirements.filter((requirement) => !requirement.satisfied(context));
|
|
100
100
|
const missingCapabilities = missingRequirements.map((requirement) => requirement.label);
|
|
101
101
|
const editor = context.editor?.identity;
|
|
102
|
+
const readiness = routingReadiness(context);
|
|
102
103
|
const workflow = request.operation === "artifact.edit"
|
|
103
104
|
? BACKGROUND_ARTIFACT_WORKFLOW
|
|
104
105
|
: request.operation === "project.list"
|
|
@@ -113,6 +114,7 @@ export function resolveEditingRoute(request, context) {
|
|
|
113
114
|
requiredCapabilities,
|
|
114
115
|
missingCapabilities,
|
|
115
116
|
...(editor ? { editor } : {}),
|
|
117
|
+
...(readiness ? { readiness } : {}),
|
|
116
118
|
workflow: [...workflow],
|
|
117
119
|
reason: {
|
|
118
120
|
code: "EXTERNAL_FALLBACK_SELECTED",
|
|
@@ -133,6 +135,7 @@ export function resolveEditingRoute(request, context) {
|
|
|
133
135
|
requiredCapabilities,
|
|
134
136
|
missingCapabilities,
|
|
135
137
|
...(editor ? { editor } : {}),
|
|
138
|
+
...(readiness ? { readiness } : {}),
|
|
136
139
|
workflow: [...workflow],
|
|
137
140
|
reason: editorUnavailableReason(context, missingRequirements),
|
|
138
141
|
};
|
|
@@ -145,6 +148,7 @@ export function resolveEditingRoute(request, context) {
|
|
|
145
148
|
requiredCapabilities,
|
|
146
149
|
missingCapabilities,
|
|
147
150
|
...(editor ? { editor } : {}),
|
|
151
|
+
...(readiness ? { readiness } : {}),
|
|
148
152
|
workflow: [...workflow],
|
|
149
153
|
reason: capabilityUnavailableReason(context, missingRequirements, request.operation),
|
|
150
154
|
};
|
|
@@ -157,6 +161,7 @@ export function resolveEditingRoute(request, context) {
|
|
|
157
161
|
requiredCapabilities,
|
|
158
162
|
missingCapabilities: [],
|
|
159
163
|
...(provider ? { provider } : {}),
|
|
164
|
+
...(readiness ? { readiness } : {}),
|
|
160
165
|
editor,
|
|
161
166
|
workflow: [...workflow],
|
|
162
167
|
reason: {
|
|
@@ -166,6 +171,18 @@ export function resolveEditingRoute(request, context) {
|
|
|
166
171
|
},
|
|
167
172
|
};
|
|
168
173
|
}
|
|
174
|
+
function routingReadiness(context) {
|
|
175
|
+
const readiness = context.nativeReadiness;
|
|
176
|
+
if (!readiness)
|
|
177
|
+
return undefined;
|
|
178
|
+
return {
|
|
179
|
+
state: readiness.state,
|
|
180
|
+
nextAction: readiness.nextAction,
|
|
181
|
+
retryable: readiness.retryable,
|
|
182
|
+
...(readiness.firstMissing ? { firstMissing: readiness.firstMissing } : {}),
|
|
183
|
+
guidance: readiness.guidance,
|
|
184
|
+
};
|
|
185
|
+
}
|
|
169
186
|
function canonicalRequirement() {
|
|
170
187
|
return {
|
|
171
188
|
name: "canonicalDocument.read",
|
|
@@ -3,9 +3,11 @@ import { ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
|
|
|
3
3
|
import { resolve as resolvePath } from "node:path";
|
|
4
4
|
import { z } from "zod";
|
|
5
5
|
import { createCapabilityPreflight, resolveEditingIntent, serializeCapabilityUnavailableError, withCanonicalTimelineMode, withCapabilityFamilies, } from "../../../packages/runtime/src/index.js";
|
|
6
|
-
import { NATIVE_MEDIA_IMPORT_DIRECTORY_ERROR_CODE, serializeFinalCutLibraryInspectionError, serializeNativeFinalCutMediaImportError, } from "../../../adapters/final-cut/typescript/src/index.js";
|
|
6
|
+
import { NATIVE_MEDIA_IMPORT_DIRECTORY_ERROR_CODE, serializeFinalCutLibraryInspectionError, serializeNativeFinalCutMediaImportError, serializeNativeFinalCutPartialMutationError, } from "../../../adapters/final-cut/typescript/src/index.js";
|
|
7
7
|
import { BACKGROUND_ARTIFACT_WORKFLOW, EDITOR_FIRST_MCP_INSTRUCTIONS, resolveEditingRoute, } from "./routing.js";
|
|
8
8
|
import { FRAMEKIT_BUILD_FINGERPRINT, FRAMEKIT_VERSION, } from "./version.js";
|
|
9
|
+
import { EditingSessionRepository } from "./headless-sessions.js";
|
|
10
|
+
import { SessionMaterializationJobs, } from "./materialization-jobs.js";
|
|
9
11
|
const revisionValueSchema = z.object({
|
|
10
12
|
id: z.string(),
|
|
11
13
|
sequence: z.number().int().nonnegative(),
|
|
@@ -645,6 +647,21 @@ function jsonResult(value) {
|
|
|
645
647
|
content: [{ type: "text", text: JSON.stringify(value) }],
|
|
646
648
|
};
|
|
647
649
|
}
|
|
650
|
+
async function sessionResult(action) {
|
|
651
|
+
try {
|
|
652
|
+
return jsonResult(await action());
|
|
653
|
+
}
|
|
654
|
+
catch (error) {
|
|
655
|
+
const message = error instanceof Error ? error.message : String(error);
|
|
656
|
+
return {
|
|
657
|
+
isError: true,
|
|
658
|
+
content: [{
|
|
659
|
+
type: "text",
|
|
660
|
+
text: JSON.stringify({ code: message.split(":", 1)[0] || "SESSION_ERROR", message }),
|
|
661
|
+
}],
|
|
662
|
+
};
|
|
663
|
+
}
|
|
664
|
+
}
|
|
648
665
|
function capabilityErrorResult(operation, capabilityName, capability) {
|
|
649
666
|
return {
|
|
650
667
|
isError: true,
|
|
@@ -685,6 +702,20 @@ function nativeMediaImportErrorResult(error) {
|
|
|
685
702
|
}],
|
|
686
703
|
};
|
|
687
704
|
}
|
|
705
|
+
async function nativeMutationResult(action) {
|
|
706
|
+
try {
|
|
707
|
+
return jsonResult(await action());
|
|
708
|
+
}
|
|
709
|
+
catch (error) {
|
|
710
|
+
const serialized = serializeNativeFinalCutPartialMutationError(error);
|
|
711
|
+
if (!serialized)
|
|
712
|
+
throw error;
|
|
713
|
+
return {
|
|
714
|
+
isError: true,
|
|
715
|
+
content: [{ type: "text", text: JSON.stringify(serialized) }],
|
|
716
|
+
};
|
|
717
|
+
}
|
|
718
|
+
}
|
|
688
719
|
function capabilityUnavailableErrorResult(error) {
|
|
689
720
|
const serialized = serializeCapabilityUnavailableError(error);
|
|
690
721
|
if (!serialized)
|
|
@@ -787,6 +818,99 @@ export function createMcpServer(runtime, options = {}) {
|
|
|
787
818
|
runtime.registerBuiltinSkills();
|
|
788
819
|
const server = new McpServer({ name: "framekit", version: FRAMEKIT_VERSION }, { instructions: EDITOR_FIRST_MCP_INSTRUCTIONS });
|
|
789
820
|
const nativeTransitionAssets = new Map();
|
|
821
|
+
const sessions = options.sessionDirectory ? new EditingSessionRepository(options.sessionDirectory) : undefined;
|
|
822
|
+
const materializations = sessions && options.materializationDirectory
|
|
823
|
+
? new SessionMaterializationJobs(options.materializationDirectory, sessions, options.sessionMaterializationPublisher)
|
|
824
|
+
: undefined;
|
|
825
|
+
const requireSessions = () => {
|
|
826
|
+
if (!sessions)
|
|
827
|
+
throw new Error("SESSION_STORAGE_UNAVAILABLE: configure a session directory");
|
|
828
|
+
return sessions;
|
|
829
|
+
};
|
|
830
|
+
const requireMaterializations = () => {
|
|
831
|
+
if (!materializations)
|
|
832
|
+
throw new Error("MATERIALIZATION_STORAGE_UNAVAILABLE: configure a materialization directory");
|
|
833
|
+
return materializations;
|
|
834
|
+
};
|
|
835
|
+
const sessionOperationSchema = z.array(z.unknown());
|
|
836
|
+
server.registerTool("session.create", {
|
|
837
|
+
description: "Create and atomically persist a provider-neutral editing session without mutating Final Cut.",
|
|
838
|
+
inputSchema: {
|
|
839
|
+
sessionId: z.string().min(1).optional(),
|
|
840
|
+
provider: z.object({ id: z.string().min(1), version: z.string().min(1).optional() }).optional(),
|
|
841
|
+
base: z.unknown(),
|
|
842
|
+
},
|
|
843
|
+
}, async ({ sessionId, provider, base }) => sessionResult(async () => requireSessions().create({
|
|
844
|
+
...(sessionId ? { sessionId } : {}),
|
|
845
|
+
...(provider ? { provider } : {}),
|
|
846
|
+
base: base,
|
|
847
|
+
})));
|
|
848
|
+
server.registerTool("session.inspect", {
|
|
849
|
+
description: "Inspect a persisted editing session and its exact base and desired Timeline IR.",
|
|
850
|
+
inputSchema: { sessionId: z.string().min(1) },
|
|
851
|
+
}, async ({ sessionId }) => sessionResult(async () => requireSessions().inspect(sessionId)));
|
|
852
|
+
server.registerTool("session.edit.preview", {
|
|
853
|
+
description: "Preview provider-neutral session edits without persisting or mutating Final Cut.",
|
|
854
|
+
inputSchema: {
|
|
855
|
+
sessionId: z.string().min(1),
|
|
856
|
+
expectedRevision: revisionValueSchema.optional(),
|
|
857
|
+
operations: sessionOperationSchema,
|
|
858
|
+
},
|
|
859
|
+
}, async ({ sessionId, expectedRevision, operations }) => sessionResult(async () => requireSessions().preview(sessionId, operations, expectedRevision)));
|
|
860
|
+
server.registerTool("session.edit.execute", {
|
|
861
|
+
description: "Apply edits only to a persisted session's desired Timeline IR.",
|
|
862
|
+
inputSchema: {
|
|
863
|
+
sessionId: z.string().min(1),
|
|
864
|
+
expectedRevision: revisionValueSchema.optional(),
|
|
865
|
+
operations: sessionOperationSchema,
|
|
866
|
+
},
|
|
867
|
+
}, async ({ sessionId, expectedRevision, operations }) => sessionResult(async () => requireSessions().execute(sessionId, operations, expectedRevision)));
|
|
868
|
+
server.registerTool("session.status", {
|
|
869
|
+
description: "Read editing-session readiness, provider binding, and revisions.",
|
|
870
|
+
inputSchema: { sessionId: z.string().min(1) },
|
|
871
|
+
}, async ({ sessionId }) => sessionResult(async () => requireSessions().status(sessionId)));
|
|
872
|
+
server.registerTool("session.reconcile", {
|
|
873
|
+
description: "Reconcile a fresh provider Timeline IR with the session base and desired state.",
|
|
874
|
+
inputSchema: {
|
|
875
|
+
sessionId: z.string().min(1),
|
|
876
|
+
provider: z.object({ id: z.string().min(1), version: z.string().min(1).optional() }),
|
|
877
|
+
providerState: z.unknown(),
|
|
878
|
+
},
|
|
879
|
+
}, async ({ sessionId, provider, providerState }) => sessionResult(async () => requireSessions().reconcile(sessionId, provider, providerState)));
|
|
880
|
+
server.registerTool("session.observe", {
|
|
881
|
+
description: "Bind read-only non-canonical Final Cut SQLite evidence to session freshness.",
|
|
882
|
+
inputSchema: { sessionId: z.string().min(1), sourcePath: z.string().min(1) },
|
|
883
|
+
}, async ({ sessionId, sourcePath }) => sessionResult(async () => {
|
|
884
|
+
if (!options.sqliteObservationProvider) {
|
|
885
|
+
throw new Error("FINAL_CUT_SQLITE_INSPECTION_UNAVAILABLE: no read-only observation provider is configured");
|
|
886
|
+
}
|
|
887
|
+
return requireSessions().observe(sessionId, sourcePath, options.sqliteObservationProvider);
|
|
888
|
+
}));
|
|
889
|
+
const sessionMaterializationTargetSchema = z.object({
|
|
890
|
+
provider: z.literal("final-cut"),
|
|
891
|
+
libraryUid: z.string().min(1),
|
|
892
|
+
eventUid: z.string().min(1),
|
|
893
|
+
projectUid: z.string().min(1),
|
|
894
|
+
sequenceUid: z.string().min(1),
|
|
895
|
+
eventName: z.string().min(1).optional(),
|
|
896
|
+
materialization: z.literal("versioned").optional(),
|
|
897
|
+
}).strict();
|
|
898
|
+
server.registerTool("session.materialize.preview", {
|
|
899
|
+
description: "Preview deterministic versioned FCPXML materialization without staging or publishing it.",
|
|
900
|
+
inputSchema: { sessionId: z.string().min(1), target: sessionMaterializationTargetSchema },
|
|
901
|
+
}, async ({ sessionId, target }) => sessionResult(async () => requireMaterializations().preview(sessionId, target)));
|
|
902
|
+
server.registerTool("session.materialize.execute", {
|
|
903
|
+
description: "Confirm, stage, checkpoint, and request publication of a versioned FCPXML project.",
|
|
904
|
+
inputSchema: { sessionId: z.string().min(1), target: sessionMaterializationTargetSchema, confirm: z.boolean() },
|
|
905
|
+
}, async ({ sessionId, target, confirm }) => sessionResult(async () => requireMaterializations().execute(sessionId, target, confirm)));
|
|
906
|
+
server.registerTool("session.materialize.status", {
|
|
907
|
+
description: "Inspect a persisted materialization job after completion, blockage, or server restart.",
|
|
908
|
+
inputSchema: { jobId: z.string().min(1) },
|
|
909
|
+
}, async ({ jobId }) => sessionResult(async () => requireMaterializations().status(jobId)));
|
|
910
|
+
server.registerTool("session.materialize.retry", {
|
|
911
|
+
description: "Resume a retryable persisted materialization job with its verified immutable artifact.",
|
|
912
|
+
inputSchema: { jobId: z.string().min(1) },
|
|
913
|
+
}, async ({ jobId }) => sessionResult(async () => requireMaterializations().retry(jobId)));
|
|
790
914
|
server.registerTool("connection.status", {
|
|
791
915
|
description: "Read Framekit's Final Cut connection state before editor-first capability discovery.",
|
|
792
916
|
inputSchema: {},
|
|
@@ -1000,7 +1124,7 @@ export function createMcpServer(runtime, options = {}) {
|
|
|
1000
1124
|
if (!options.nativeEditor)
|
|
1001
1125
|
throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native writes are not configured");
|
|
1002
1126
|
const operation = nativeEditSchema.parse(input);
|
|
1003
|
-
return
|
|
1127
|
+
return nativeMutationResult(() => options.nativeEditor.edit(operation, { signal: extra.signal }));
|
|
1004
1128
|
});
|
|
1005
1129
|
server.registerTool("editor.native.disposable.preview", {
|
|
1006
1130
|
description: "Preview a disposable native Final Cut rename after canonical target, revision, and native preflight checks.",
|
|
@@ -1073,7 +1197,7 @@ export function createMcpServer(runtime, options = {}) {
|
|
|
1073
1197
|
}, async ({ previewToken }, extra) => {
|
|
1074
1198
|
if (!options.nativeEditor)
|
|
1075
1199
|
throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native title placement is not configured");
|
|
1076
|
-
return
|
|
1200
|
+
return nativeMutationResult(() => options.nativeEditor.executeTitleAdd(previewToken, { signal: extra.signal }));
|
|
1077
1201
|
});
|
|
1078
1202
|
server.registerTool("editor.native.picture-in-picture.preview", {
|
|
1079
1203
|
description: "Preview connecting selected Final Cut Browser video to a stable timeline occurrence with verified transform properties.",
|
|
@@ -1091,7 +1215,7 @@ export function createMcpServer(runtime, options = {}) {
|
|
|
1091
1215
|
if (!options.nativeEditor)
|
|
1092
1216
|
throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native picture-in-picture placement is not configured");
|
|
1093
1217
|
await requireEditingRoute(runtime, options, "editor.native.picture-in-picture");
|
|
1094
|
-
return
|
|
1218
|
+
return nativeMutationResult(() => options.nativeEditor.executePictureInPicture(previewToken, { signal: extra.signal }));
|
|
1095
1219
|
});
|
|
1096
1220
|
server.registerTool("editor.native.transition.search", {
|
|
1097
1221
|
description: "Search the visible Final Cut Transitions browser and return only transitions with stable native identities.",
|
|
@@ -1126,7 +1250,7 @@ export function createMcpServer(runtime, options = {}) {
|
|
|
1126
1250
|
}, async ({ previewToken }, extra) => {
|
|
1127
1251
|
if (!options.nativeEditor)
|
|
1128
1252
|
throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native transition placement is not configured");
|
|
1129
|
-
return
|
|
1253
|
+
return nativeMutationResult(() => options.nativeEditor.executeTransitionAdd(previewToken, { signal: extra.signal }));
|
|
1130
1254
|
});
|
|
1131
1255
|
server.registerTool("editor.native.mask.preview", {
|
|
1132
1256
|
description: "Preview adding a bounded native Final Cut Draw Mask to one located occurrence without mutating the timeline.",
|
|
@@ -1142,7 +1266,7 @@ export function createMcpServer(runtime, options = {}) {
|
|
|
1142
1266
|
}, async ({ previewToken }, extra) => {
|
|
1143
1267
|
if (!options.nativeEditor)
|
|
1144
1268
|
throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native masking is not configured");
|
|
1145
|
-
return
|
|
1269
|
+
return nativeMutationResult(() => options.nativeEditor.executeMask(previewToken, { signal: extra.signal }));
|
|
1146
1270
|
});
|
|
1147
1271
|
server.registerTool("editor.native.undo", {
|
|
1148
1272
|
description: "Undo a previously accepted native Final Cut UI edit using Final Cut's native Undo command.",
|
|
@@ -1182,7 +1306,7 @@ export function createMcpServer(runtime, options = {}) {
|
|
|
1182
1306
|
}, async ({ previewToken }, extra) => {
|
|
1183
1307
|
if (!options.nativeEditor)
|
|
1184
1308
|
throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native media append is not configured");
|
|
1185
|
-
return
|
|
1309
|
+
return nativeMutationResult(() => options.nativeEditor.executeAppendMedia(previewToken, { signal: extra.signal }));
|
|
1186
1310
|
});
|
|
1187
1311
|
server.registerTool("editor.native.media.append.selected.preview", {
|
|
1188
1312
|
description: "Preview appending the currently selected Final Cut Browser media to the end of the active timeline.",
|
|
@@ -1198,7 +1322,7 @@ export function createMcpServer(runtime, options = {}) {
|
|
|
1198
1322
|
}, async ({ previewToken }, extra) => {
|
|
1199
1323
|
if (!options.nativeEditor)
|
|
1200
1324
|
throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native selected-media append is not configured");
|
|
1201
|
-
return
|
|
1325
|
+
return nativeMutationResult(() => options.nativeEditor.executeAppendSelectedMedia(previewToken, { signal: extra.signal }));
|
|
1202
1326
|
});
|
|
1203
1327
|
server.registerTool("editor.native.media.insert.preview", {
|
|
1204
1328
|
description: "Preview inserting the selected Final Cut Browser media at the current playhead.",
|
|
@@ -1214,7 +1338,7 @@ export function createMcpServer(runtime, options = {}) {
|
|
|
1214
1338
|
}, async ({ previewToken }, extra) => {
|
|
1215
1339
|
if (!options.nativeEditor)
|
|
1216
1340
|
throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native media insert is not configured");
|
|
1217
|
-
return
|
|
1341
|
+
return nativeMutationResult(() => options.nativeEditor.executeInsertMedia(previewToken, { signal: extra.signal }));
|
|
1218
1342
|
});
|
|
1219
1343
|
server.registerTool("editor.native.timeline.locate", {
|
|
1220
1344
|
description: "Locate matching occurrences of a live Browser media result in the active Final Cut timeline.",
|
|
@@ -1246,7 +1370,7 @@ export function createMcpServer(runtime, options = {}) {
|
|
|
1246
1370
|
}, async ({ previewToken }, extra) => {
|
|
1247
1371
|
if (!options.nativeEditor)
|
|
1248
1372
|
throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native Blade is not configured");
|
|
1249
|
-
return
|
|
1373
|
+
return nativeMutationResult(() => options.nativeEditor.executeBlade(previewToken, { signal: extra.signal }));
|
|
1250
1374
|
});
|
|
1251
1375
|
server.registerTool("editor.native.delete-range.preview", {
|
|
1252
1376
|
description: "Preview a destructive ripple-delete of an explicit rational time range from the Final Cut primary storyline.",
|
|
@@ -1262,7 +1386,7 @@ export function createMcpServer(runtime, options = {}) {
|
|
|
1262
1386
|
}, async ({ previewToken }, extra) => {
|
|
1263
1387
|
if (!options.nativeEditor)
|
|
1264
1388
|
throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native range deletion is not configured");
|
|
1265
|
-
return
|
|
1389
|
+
return nativeMutationResult(() => options.nativeEditor.executeDeleteRange(previewToken, { signal: extra.signal }));
|
|
1266
1390
|
});
|
|
1267
1391
|
server.registerTool("editor.native.trim-to-duration.preview", {
|
|
1268
1392
|
description: "Preview a destructive operation that preserves the beginning of the Final Cut sequence and removes everything after the requested rational duration.",
|
|
@@ -1278,7 +1402,7 @@ export function createMcpServer(runtime, options = {}) {
|
|
|
1278
1402
|
}, async ({ previewToken }, extra) => {
|
|
1279
1403
|
if (!options.nativeEditor)
|
|
1280
1404
|
throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native duration trimming is not configured");
|
|
1281
|
-
return
|
|
1405
|
+
return nativeMutationResult(() => options.nativeEditor.executeTrimToDuration(previewToken, { signal: extra.signal }));
|
|
1282
1406
|
});
|
|
1283
1407
|
server.registerTool("artifact.publish.preview", {
|
|
1284
1408
|
description: "Prepare a headed-only publish handoff for a verified FCPXML artifact without opening Final Cut.",
|
|
@@ -2005,6 +2129,15 @@ async function requireEditingRoute(runtime, options, operation) {
|
|
|
2005
2129
|
}
|
|
2006
2130
|
async function editingRouteContext(runtime, options) {
|
|
2007
2131
|
const connection = await effectiveConnectionStatus(runtime, options);
|
|
2132
|
+
let nativeReadiness;
|
|
2133
|
+
if (options.nativeEditor && typeof options.nativeEditor.inspect === "function") {
|
|
2134
|
+
try {
|
|
2135
|
+
nativeReadiness = (await options.nativeEditor.inspect()).readiness;
|
|
2136
|
+
}
|
|
2137
|
+
catch {
|
|
2138
|
+
nativeReadiness = undefined;
|
|
2139
|
+
}
|
|
2140
|
+
}
|
|
2008
2141
|
let editor;
|
|
2009
2142
|
try {
|
|
2010
2143
|
editor = await inspectMcpEditor(runtime, options);
|
|
@@ -2016,5 +2149,6 @@ async function editingRouteContext(runtime, options) {
|
|
|
2016
2149
|
connection,
|
|
2017
2150
|
...(editor ? { editor } : {}),
|
|
2018
2151
|
...(options.nativeEditor ? { native: { ...options.nativeEditor.capabilities() } } : {}),
|
|
2152
|
+
...(nativeReadiness ? { nativeReadiness } : {}),
|
|
2019
2153
|
};
|
|
2020
2154
|
}
|