@morshoto/framekit 0.1.17 → 0.2.2
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 +25 -14
- package/dist-package/adapters/final-cut/typescript/src/background-materialization.js +8 -2
- package/dist-package/adapters/final-cut/typescript/src/canonical-recovery-guard.js +275 -0
- package/dist-package/adapters/final-cut/typescript/src/canonical.js +557 -84
- package/dist-package/adapters/final-cut/typescript/src/connection.js +10 -3
- package/dist-package/adapters/final-cut/typescript/src/disposable-native.js +6 -0
- package/dist-package/adapters/final-cut/typescript/src/experimental.js +8 -0
- package/dist-package/adapters/final-cut/typescript/src/fcpxml.js +150 -37
- package/dist-package/adapters/final-cut/typescript/src/index.js +2 -7
- package/dist-package/adapters/final-cut/typescript/src/library-inspection.js +60 -1
- package/dist-package/adapters/final-cut/typescript/src/live.js +29 -4
- package/dist-package/adapters/final-cut/typescript/src/native-recovery-inspection.js +175 -0
- package/dist-package/adapters/final-cut/typescript/src/native-session.js +11 -6
- package/dist-package/adapters/final-cut/typescript/src/native.js +201 -82
- package/dist-package/adapters/final-cut/typescript/src/publish-readback.js +214 -0
- package/dist-package/adapters/final-cut/typescript/src/publisher.js +1008 -243
- package/dist-package/adapters/final-cut/typescript/src/session.js +49 -14
- package/dist-package/adapters/final-cut/typescript/src/timeline-ir-fcpxml.js +203 -49
- package/dist-package/adapters/headless/typescript/src/audio-output.js +3 -0
- package/dist-package/adapters/headless/typescript/src/ffmpeg-renderer.js +48 -20
- package/dist-package/adapters/headless/typescript/src/ffmpeg-verifier.js +9 -4
- package/dist-package/apps/cli/src/dev-doctor.js +198 -0
- package/dist-package/apps/cli/src/headless-projects.js +5 -0
- package/dist-package/apps/cli/src/main.js +76 -19
- package/dist-package/apps/mcp-server/runtime/speech-analyzer-wrapper.mjs +54 -0
- package/dist-package/apps/mcp-server/runtime/whisper-speech-backend.py +181 -0
- 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/canonical-native-snapshot.js +18 -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.js +101 -0
- package/dist-package/apps/mcp-server/src/main.js +50 -21
- package/dist-package/apps/mcp-server/src/materialization-jobs.js +143 -10
- package/dist-package/apps/mcp-server/src/routing.js +2 -0
- package/dist-package/apps/mcp-server/src/server.js +986 -180
- package/dist-package/apps/mcp-server/src/tools/skills/catalog.js +142 -0
- package/dist-package/apps/mcp-server/src/tools/skills/metadata.js +71 -0
- package/dist-package/apps/mcp-server/src/tools/skills/register.js +101 -0
- package/dist-package/apps/mcp-server/src/version.js +21 -2
- package/dist-package/packages/headless-application/src/headless-projects.js +942 -0
- package/dist-package/packages/headless-application/src/index.js +1 -0
- package/dist-package/packages/runtime/src/application/media-analysis-service.js +15 -5
- package/dist-package/packages/runtime/src/application/project-service.js +5 -1
- package/dist-package/packages/runtime/src/application/project-store.js +13 -36
- package/dist-package/packages/runtime/src/application/transaction-store.js +1 -1
- package/dist-package/packages/runtime/src/capabilities.js +1 -1
- package/dist-package/packages/runtime/src/context/context-engine.js +22 -16
- package/dist-package/packages/runtime/src/context/context-service.js +2 -2
- package/dist-package/packages/runtime/src/editing/edit-service.js +76 -10
- package/dist-package/packages/runtime/src/index.js +1 -0
- package/dist-package/packages/runtime/src/runtime.js +22 -7
- package/dist-package/packages/runtime/src/timeline/editing-session.js +23 -2
- package/dist-package/packages/testkit/src/in-memory-editor.js +3 -3
- package/dist-package/packages/testkit/src/index.js +1 -0
- package/dist-package/packages/testkit/src/sender-lifecycle-fixture.js +192 -0
- package/package.json +36 -14
- package/dist-package/apps/mcp-server/src/headless-projects.js +0 -370
|
@@ -1,16 +1,19 @@
|
|
|
1
1
|
import { createHash, randomUUID } from "node:crypto";
|
|
2
2
|
import { mkdir, readFile, rename, unlink, writeFile } from "node:fs/promises";
|
|
3
3
|
import { dirname, join } from "node:path";
|
|
4
|
+
import { types as utilTypes } from "node:util";
|
|
4
5
|
import { timelineIrDigest, validateTimelineIr } from "../../../packages/runtime/src/index.js";
|
|
5
|
-
import { compileTimelineIrToFcpxml, } from "../../../adapters/final-cut/typescript/src/index.js";
|
|
6
|
+
import { compileTimelineIrToFcpxml, FinalCutBackgroundMaterializationPublisher, validateFinalCutBackgroundMaterializationRequest, } from "../../../adapters/final-cut/typescript/src/index.js";
|
|
6
7
|
export class SessionMaterializationJobs {
|
|
7
8
|
directory;
|
|
8
9
|
sessions;
|
|
9
10
|
publisher;
|
|
10
|
-
|
|
11
|
+
recoveryGuard;
|
|
12
|
+
constructor(directory, sessions, publisher, recoveryGuard) {
|
|
11
13
|
this.directory = directory;
|
|
12
14
|
this.sessions = sessions;
|
|
13
15
|
this.publisher = publisher;
|
|
16
|
+
this.recoveryGuard = recoveryGuard;
|
|
14
17
|
}
|
|
15
18
|
async preview(sessionId, target) {
|
|
16
19
|
const session = await this.sessions.loadForMaterialization(sessionId);
|
|
@@ -168,12 +171,20 @@ export class SessionMaterializationJobs {
|
|
|
168
171
|
const claim = await this.claim(job);
|
|
169
172
|
if (!claim.owned)
|
|
170
173
|
return claim.job;
|
|
171
|
-
|
|
174
|
+
let claimed = claim.job;
|
|
175
|
+
let reservation;
|
|
176
|
+
let providerRequested = false;
|
|
177
|
+
// Do not evaluate provider properties before acquiring the reservation.
|
|
178
|
+
let dispatched = false;
|
|
172
179
|
try {
|
|
173
180
|
const finalFailure = await this.validateStagedJob(claimed);
|
|
174
181
|
if (finalFailure)
|
|
175
182
|
return this.fail(claimed, finalFailure);
|
|
176
|
-
|
|
183
|
+
if (claimed.destination.mode !== "versioned")
|
|
184
|
+
return this.fail(claimed, {
|
|
185
|
+
code: "MATERIALIZATION_DESTINATION_INVALID", message: "Versioned destination required", retryable: false, providerRequested: false,
|
|
186
|
+
});
|
|
187
|
+
const request = {
|
|
177
188
|
jobId: claimed.jobId,
|
|
178
189
|
artifactPath: claimed.artifactPath,
|
|
179
190
|
artifactDigest: claimed.artifactDigest,
|
|
@@ -186,12 +197,85 @@ export class SessionMaterializationJobs {
|
|
|
186
197
|
baseRevision: structuredClone(claimed.baseRevision),
|
|
187
198
|
coverage: structuredClone(claimed.coverage),
|
|
188
199
|
provenance: structuredClone(claimed.provenance),
|
|
189
|
-
}
|
|
200
|
+
};
|
|
201
|
+
try {
|
|
202
|
+
// The built-in adapter's pure request checks must run before the
|
|
203
|
+
// dispatch boundary, while the staged request is still inert data.
|
|
204
|
+
validateFinalCutBackgroundMaterializationRequest(request);
|
|
205
|
+
}
|
|
206
|
+
catch (error) {
|
|
207
|
+
return this.fail(claimed, materializationFailure(error, false));
|
|
208
|
+
}
|
|
209
|
+
// This check invokes no provider operation and is limited to the exact
|
|
210
|
+
// built-in implementation. Custom providers remain untrusted.
|
|
211
|
+
if (hasInertUnavailableMaterializationOptions(this.publisher)) {
|
|
212
|
+
const blocked = {
|
|
213
|
+
...claimed, state: "blocked", nextAction: "retry", claim: undefined,
|
|
214
|
+
verification: { tier: "artifact", status: "blocked", artifactDigest: claimed.artifactDigest,
|
|
215
|
+
desiredDigest: claimed.desiredDigest, reason: "No non-UI materialization capability is configured; the provider was not called" },
|
|
216
|
+
error: { code: "FINAL_CUT_BACKGROUND_MATERIALIZATION_UNAVAILABLE", message: "No explicit non-UI Final Cut materialization capability is configured", retryable: true },
|
|
217
|
+
};
|
|
218
|
+
await this.save(blocked);
|
|
219
|
+
return blocked;
|
|
220
|
+
}
|
|
221
|
+
if (this.recoveryGuard) {
|
|
222
|
+
try {
|
|
223
|
+
const id = createHash("sha256").update(claimed.jobId).digest("hex");
|
|
224
|
+
reservation = await this.recoveryGuard.beginNative(`native.materialize.${id}`, {
|
|
225
|
+
kind: "materialization", jobId: claimed.jobId, dispatchId: randomUUID(),
|
|
226
|
+
requestedTarget: { libraryUid: claimed.target.libraryUid, eventUid: claimed.target.eventUid,
|
|
227
|
+
projectUid: claimed.target.projectUid, sequenceUid: claimed.target.sequenceUid },
|
|
228
|
+
artifactDigest: claimed.artifactDigest, desiredDigest: claimed.desiredDigest,
|
|
229
|
+
destination: { ...structuredClone(claimed.destination), mode: "versioned" },
|
|
230
|
+
executorIdentity: null, nativeQuiescence: "unproven",
|
|
231
|
+
});
|
|
232
|
+
}
|
|
233
|
+
catch {
|
|
234
|
+
const blocked = {
|
|
235
|
+
...claimed, state: "blocked", nextAction: "retry", claim: undefined,
|
|
236
|
+
verification: {
|
|
237
|
+
tier: "artifact", status: "blocked", artifactDigest: claimed.artifactDigest, desiredDigest: claimed.desiredDigest,
|
|
238
|
+
reason: "An unresolved native reservation prevents materialization; the provider was not called",
|
|
239
|
+
},
|
|
240
|
+
error: { code: "FINAL_CUT_CANONICAL_RECOVERY_REQUIRED", message: "An unresolved native reservation prevents materialization; the provider was not called", retryable: true },
|
|
241
|
+
};
|
|
242
|
+
await this.save(blocked);
|
|
243
|
+
return blocked;
|
|
244
|
+
}
|
|
245
|
+
claimed = { ...claimed, recoveryReservation: { reservationId: reservation.reservationId, reason: "native-quiescence-unproven" } };
|
|
246
|
+
await this.save(claimed);
|
|
247
|
+
}
|
|
248
|
+
const invoke = async () => {
|
|
249
|
+
const intent = {
|
|
250
|
+
...claimed, providerRequestPhase: "dispatch-intent",
|
|
251
|
+
evidence: { ...claimed.evidence, providerRequested: true },
|
|
252
|
+
};
|
|
253
|
+
await this.save(intent);
|
|
254
|
+
claimed = intent;
|
|
255
|
+
providerRequested = true;
|
|
256
|
+
return this.publisher.publish(request);
|
|
257
|
+
};
|
|
258
|
+
// A tracker is executable provider code. It may defer invoking the
|
|
259
|
+
// supplied operation even if it returns or throws first.
|
|
260
|
+
dispatched = true;
|
|
261
|
+
// Persist uncertainty before executing even the tracker: untrusted
|
|
262
|
+
// tracker code may invoke or defer the provider without acknowledgement.
|
|
263
|
+
if (reservation)
|
|
264
|
+
await reservation.markDispatchPossible();
|
|
265
|
+
const result = this.publisher.trackNativeDispatch
|
|
266
|
+
? await this.publisher.trackNativeDispatch(invoke, () => { dispatched = true; })
|
|
267
|
+
: await invoke();
|
|
268
|
+
claimed = { ...claimed, providerRequestPhase: "returned" };
|
|
269
|
+
if (reservation && !providerRequested && !dispatched) {
|
|
270
|
+
await reservation.release();
|
|
271
|
+
reservation = undefined;
|
|
272
|
+
claimed = { ...claimed, recoveryReservation: undefined };
|
|
273
|
+
}
|
|
190
274
|
if (result.state === "blocked") {
|
|
191
275
|
const blocked = {
|
|
192
276
|
...claimed,
|
|
193
277
|
state: "blocked",
|
|
194
|
-
nextAction: "retry",
|
|
278
|
+
nextAction: claimed.recoveryReservation ? "none" : "retry",
|
|
195
279
|
claim: undefined,
|
|
196
280
|
evidence: { ...claimed.evidence, providerRequested: true },
|
|
197
281
|
verification: {
|
|
@@ -202,7 +286,10 @@ export class SessionMaterializationJobs {
|
|
|
202
286
|
reason: result.message,
|
|
203
287
|
...(result.delivery ? { delivery: result.delivery } : { delivery: deliveryEvidenceForBlockedCode(result.code) }),
|
|
204
288
|
},
|
|
205
|
-
|
|
289
|
+
...(claimed.recoveryReservation ? { providerError: { code: result.code, message: result.message, retryable: result.retryable } } : {}),
|
|
290
|
+
error: claimed.recoveryReservation
|
|
291
|
+
? { code: "FINAL_CUT_CANONICAL_RECOVERY_REQUIRED", message: "Materialization may have been dispatched; native quiescence is unproven and it must not be retried", retryable: false }
|
|
292
|
+
: { code: result.code, message: result.message, retryable: result.retryable },
|
|
206
293
|
};
|
|
207
294
|
await this.save(blocked);
|
|
208
295
|
return blocked;
|
|
@@ -260,11 +347,22 @@ export class SessionMaterializationJobs {
|
|
|
260
347
|
reason: "Canonical readback verified this handoff once. Re-read the materialized target before later edits to detect subsequent manual Final Cut changes.",
|
|
261
348
|
},
|
|
262
349
|
};
|
|
263
|
-
|
|
264
|
-
|
|
350
|
+
const outcome = claimed.recoveryReservation
|
|
351
|
+
? {
|
|
352
|
+
...completed, state: "blocked", nextAction: "none",
|
|
353
|
+
error: { code: "FINAL_CUT_CANONICAL_RECOVERY_REQUIRED", message: "Canonical readback was verified but native quiescence is unproven; do not retry publication", retryable: false },
|
|
354
|
+
continuation: { state: "canonical-resync-required", reason: "Recovery is required before a fresh canonical session can be created from this verified readback." },
|
|
355
|
+
}
|
|
356
|
+
: completed;
|
|
357
|
+
await this.save(outcome);
|
|
358
|
+
return outcome;
|
|
265
359
|
}
|
|
266
360
|
catch (error) {
|
|
267
|
-
|
|
361
|
+
if (reservation && !providerRequested && !dispatched) {
|
|
362
|
+
await reservation.release();
|
|
363
|
+
claimed = { ...claimed, recoveryReservation: undefined };
|
|
364
|
+
}
|
|
365
|
+
return this.fail(claimed, materializationFailure(error, providerRequested || claimed.evidence.providerRequested));
|
|
268
366
|
}
|
|
269
367
|
finally {
|
|
270
368
|
await this.release(claimed.jobId, claimed.claim.id);
|
|
@@ -538,6 +636,41 @@ function collectStructuralChanges(before, after, path, changes) {
|
|
|
538
636
|
}
|
|
539
637
|
changes.push({ path, ...(before !== undefined ? { before } : {}), ...(after !== undefined ? { after } : {}) });
|
|
540
638
|
}
|
|
639
|
+
// Only inspect own data properties on ordinary, non-proxy objects. Calling
|
|
640
|
+
// isAvailable() here could execute a caller-supplied getter before a native
|
|
641
|
+
// reservation exists, so every unfamiliar shape must take the guarded path.
|
|
642
|
+
const builtinStringTrim = String.prototype.trim;
|
|
643
|
+
const builtinMaterializationMethods = new Map([
|
|
644
|
+
["publish", FinalCutBackgroundMaterializationPublisher.prototype.publish],
|
|
645
|
+
["trackNativeDispatch", FinalCutBackgroundMaterializationPublisher.prototype.trackNativeDispatch],
|
|
646
|
+
["isAvailable", FinalCutBackgroundMaterializationPublisher.prototype.isAvailable],
|
|
647
|
+
]);
|
|
648
|
+
function hasInertUnavailableMaterializationOptions(publisher) {
|
|
649
|
+
if (utilTypes.isProxy(publisher) || Object.getPrototypeOf(publisher) !== FinalCutBackgroundMaterializationPublisher.prototype)
|
|
650
|
+
return false;
|
|
651
|
+
for (const [name, method] of builtinMaterializationMethods) {
|
|
652
|
+
if (Object.getOwnPropertyDescriptor(publisher, name)
|
|
653
|
+
|| Object.getOwnPropertyDescriptor(FinalCutBackgroundMaterializationPublisher.prototype, name)?.value !== method)
|
|
654
|
+
return false;
|
|
655
|
+
}
|
|
656
|
+
const optionsProperty = Object.getOwnPropertyDescriptor(publisher, "options");
|
|
657
|
+
if (!optionsProperty || !("value" in optionsProperty))
|
|
658
|
+
return false;
|
|
659
|
+
const options = optionsProperty.value;
|
|
660
|
+
if (!options || typeof options !== "object" || utilTypes.isProxy(options))
|
|
661
|
+
return false;
|
|
662
|
+
const prototype = Object.getPrototypeOf(options);
|
|
663
|
+
if (prototype !== null && prototype !== Object.prototype)
|
|
664
|
+
return false;
|
|
665
|
+
if (prototype && (Object.getOwnPropertyDescriptor(prototype, "executor") || Object.getOwnPropertyDescriptor(prototype, "command")))
|
|
666
|
+
return false;
|
|
667
|
+
const executor = Object.getOwnPropertyDescriptor(options, "executor");
|
|
668
|
+
const command = Object.getOwnPropertyDescriptor(options, "command");
|
|
669
|
+
if ((executor && (!("value" in executor) || executor.value !== undefined)) || (command && !("value" in command)))
|
|
670
|
+
return false;
|
|
671
|
+
const value = command?.value;
|
|
672
|
+
return value === undefined || value === null || (typeof value === "string" && builtinStringTrim.call(value) === "");
|
|
673
|
+
}
|
|
541
674
|
function isRecord(value) {
|
|
542
675
|
return Boolean(value) && typeof value === "object" && !Array.isArray(value);
|
|
543
676
|
}
|
|
@@ -250,6 +250,8 @@ function routingReadiness(context) {
|
|
|
250
250
|
nextAction: readiness.nextAction,
|
|
251
251
|
retryable: readiness.retryable,
|
|
252
252
|
...(readiness.firstMissing ? { firstMissing: readiness.firstMissing } : {}),
|
|
253
|
+
...(readiness.targetKind ? { targetKind: readiness.targetKind } : {}),
|
|
254
|
+
...(readiness.targetBound !== undefined ? { targetBound: readiness.targetBound } : {}),
|
|
253
255
|
guidance: readiness.guidance,
|
|
254
256
|
};
|
|
255
257
|
}
|