@morshoto/framekit 0.1.6 → 0.1.11

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (43) hide show
  1. package/bin/framekit.mjs +2 -1
  2. package/dist-package/adapters/final-cut/typescript/src/assets.js +157 -35
  3. package/dist-package/adapters/final-cut/typescript/src/background-export.js +384 -0
  4. package/dist-package/adapters/final-cut/typescript/src/background-materialization.js +175 -0
  5. package/dist-package/adapters/final-cut/typescript/src/canonical.js +189 -32
  6. package/dist-package/adapters/final-cut/typescript/src/connection.js +55 -17
  7. package/dist-package/adapters/final-cut/typescript/src/disposable-native.js +33 -7
  8. package/dist-package/adapters/final-cut/typescript/src/fcpxml-console-experiment.js +74 -0
  9. package/dist-package/adapters/final-cut/typescript/src/fcpxml.js +615 -49
  10. package/dist-package/adapters/final-cut/typescript/src/index.js +10 -0
  11. package/dist-package/adapters/final-cut/typescript/src/library-inspection.js +390 -0
  12. package/dist-package/adapters/final-cut/typescript/src/live.js +16 -6
  13. package/dist-package/adapters/final-cut/typescript/src/media.js +151 -0
  14. package/dist-package/adapters/final-cut/typescript/src/native-session.js +412 -0
  15. package/dist-package/adapters/final-cut/typescript/src/native.js +1192 -364
  16. package/dist-package/adapters/final-cut/typescript/src/publisher.js +225 -32
  17. package/dist-package/adapters/final-cut/typescript/src/session.js +163 -17
  18. package/dist-package/adapters/final-cut/typescript/src/shadow-mutation.js +120 -0
  19. package/dist-package/adapters/final-cut/typescript/src/sqlite-inspection.js +433 -0
  20. package/dist-package/adapters/final-cut/typescript/src/timeline-ir-fcpxml.js +372 -0
  21. package/dist-package/adapters/final-cut/typescript/src/unattended-editing.js +66 -0
  22. package/dist-package/apps/mcp-server/src/headless-sessions.js +112 -0
  23. package/dist-package/apps/mcp-server/src/main.js +41 -8
  24. package/dist-package/apps/mcp-server/src/materialization-jobs.js +326 -0
  25. package/dist-package/apps/mcp-server/src/routing.js +227 -39
  26. package/dist-package/apps/mcp-server/src/server.js +642 -97
  27. package/dist-package/apps/mcp-server/src/version.js +109 -1
  28. package/dist-package/packages/runtime/src/application/media-analysis-service.js +1 -3
  29. package/dist-package/packages/runtime/src/application/project-service.js +46 -7
  30. package/dist-package/packages/runtime/src/capabilities.js +55 -7
  31. package/dist-package/packages/runtime/src/context/project-catalog.js +159 -0
  32. package/dist-package/packages/runtime/src/domain/capabilities.js +33 -0
  33. package/dist-package/packages/runtime/src/domain/context.js +14 -1
  34. package/dist-package/packages/runtime/src/domain/index.js +1 -0
  35. package/dist-package/packages/runtime/src/domain/timeline-target.js +217 -0
  36. package/dist-package/packages/runtime/src/editing/edit-service.js +15 -1
  37. package/dist-package/packages/runtime/src/editing/intent.js +178 -2
  38. package/dist-package/packages/runtime/src/index.js +3 -0
  39. package/dist-package/packages/runtime/src/runtime.js +2 -2
  40. package/dist-package/packages/runtime/src/timeline/drift-reconciliation.js +295 -0
  41. package/dist-package/packages/runtime/src/timeline/editing-session.js +490 -0
  42. package/dist-package/packages/testkit/src/in-memory-editor.js +5 -4
  43. package/package.json +12 -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
+ }