@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.
Files changed (58) hide show
  1. package/README.md +25 -14
  2. package/dist-package/adapters/final-cut/typescript/src/background-materialization.js +8 -2
  3. package/dist-package/adapters/final-cut/typescript/src/canonical-recovery-guard.js +275 -0
  4. package/dist-package/adapters/final-cut/typescript/src/canonical.js +557 -84
  5. package/dist-package/adapters/final-cut/typescript/src/connection.js +10 -3
  6. package/dist-package/adapters/final-cut/typescript/src/disposable-native.js +6 -0
  7. package/dist-package/adapters/final-cut/typescript/src/experimental.js +8 -0
  8. package/dist-package/adapters/final-cut/typescript/src/fcpxml.js +150 -37
  9. package/dist-package/adapters/final-cut/typescript/src/index.js +2 -7
  10. package/dist-package/adapters/final-cut/typescript/src/library-inspection.js +60 -1
  11. package/dist-package/adapters/final-cut/typescript/src/live.js +29 -4
  12. package/dist-package/adapters/final-cut/typescript/src/native-recovery-inspection.js +175 -0
  13. package/dist-package/adapters/final-cut/typescript/src/native-session.js +11 -6
  14. package/dist-package/adapters/final-cut/typescript/src/native.js +201 -82
  15. package/dist-package/adapters/final-cut/typescript/src/publish-readback.js +214 -0
  16. package/dist-package/adapters/final-cut/typescript/src/publisher.js +1008 -243
  17. package/dist-package/adapters/final-cut/typescript/src/session.js +49 -14
  18. package/dist-package/adapters/final-cut/typescript/src/timeline-ir-fcpxml.js +203 -49
  19. package/dist-package/adapters/headless/typescript/src/audio-output.js +3 -0
  20. package/dist-package/adapters/headless/typescript/src/ffmpeg-renderer.js +48 -20
  21. package/dist-package/adapters/headless/typescript/src/ffmpeg-verifier.js +9 -4
  22. package/dist-package/apps/cli/src/dev-doctor.js +198 -0
  23. package/dist-package/apps/cli/src/headless-projects.js +5 -0
  24. package/dist-package/apps/cli/src/main.js +76 -19
  25. package/dist-package/apps/mcp-server/runtime/speech-analyzer-wrapper.mjs +54 -0
  26. package/dist-package/apps/mcp-server/runtime/whisper-speech-backend.py +181 -0
  27. package/dist-package/apps/mcp-server/src/build-alignment.js +59 -0
  28. package/dist-package/apps/mcp-server/src/build-identity.js +30 -0
  29. package/dist-package/apps/mcp-server/src/build-identity.json +5 -0
  30. package/dist-package/apps/mcp-server/src/canonical-native-snapshot.js +18 -0
  31. package/dist-package/apps/mcp-server/src/final-cut-runtime-config.js +3 -0
  32. package/dist-package/apps/mcp-server/src/headless-project-snapshot.js +101 -0
  33. package/dist-package/apps/mcp-server/src/main.js +50 -21
  34. package/dist-package/apps/mcp-server/src/materialization-jobs.js +143 -10
  35. package/dist-package/apps/mcp-server/src/routing.js +2 -0
  36. package/dist-package/apps/mcp-server/src/server.js +986 -180
  37. package/dist-package/apps/mcp-server/src/tools/skills/catalog.js +142 -0
  38. package/dist-package/apps/mcp-server/src/tools/skills/metadata.js +71 -0
  39. package/dist-package/apps/mcp-server/src/tools/skills/register.js +101 -0
  40. package/dist-package/apps/mcp-server/src/version.js +21 -2
  41. package/dist-package/packages/headless-application/src/headless-projects.js +942 -0
  42. package/dist-package/packages/headless-application/src/index.js +1 -0
  43. package/dist-package/packages/runtime/src/application/media-analysis-service.js +15 -5
  44. package/dist-package/packages/runtime/src/application/project-service.js +5 -1
  45. package/dist-package/packages/runtime/src/application/project-store.js +13 -36
  46. package/dist-package/packages/runtime/src/application/transaction-store.js +1 -1
  47. package/dist-package/packages/runtime/src/capabilities.js +1 -1
  48. package/dist-package/packages/runtime/src/context/context-engine.js +22 -16
  49. package/dist-package/packages/runtime/src/context/context-service.js +2 -2
  50. package/dist-package/packages/runtime/src/editing/edit-service.js +76 -10
  51. package/dist-package/packages/runtime/src/index.js +1 -0
  52. package/dist-package/packages/runtime/src/runtime.js +22 -7
  53. package/dist-package/packages/runtime/src/timeline/editing-session.js +23 -2
  54. package/dist-package/packages/testkit/src/in-memory-editor.js +3 -3
  55. package/dist-package/packages/testkit/src/index.js +1 -0
  56. package/dist-package/packages/testkit/src/sender-lifecycle-fixture.js +192 -0
  57. package/package.json +36 -14
  58. package/dist-package/apps/mcp-server/src/headless-projects.js +0 -370
@@ -0,0 +1,175 @@
1
+ import { createHash } from "node:crypto";
2
+ import { constants } from "node:fs";
3
+ import { lstat, open } from "node:fs/promises";
4
+ import { isAbsolute, join } from "node:path";
5
+ function validPublishContext(value, operation) {
6
+ if (!value || typeof value !== "object" || Array.isArray(value))
7
+ return false;
8
+ const c = value;
9
+ const path = c.requestedTarget?.libraryPath;
10
+ return c.kind === "publish"
11
+ && typeof c.jobId === "string" && /^publish-job-[a-z0-9-]{1,80}$/.test(c.jobId)
12
+ && operation === `native.publish.${createHash("sha256").update(c.jobId).digest("hex")}`
13
+ && typeof c.dispatchId === "string" && /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(c.dispatchId)
14
+ && typeof path === "string" && path.length <= 4096 && isAbsolute(path) && path.endsWith(".fcpbundle")
15
+ && typeof c.artifactDigest === "string" && /^[a-f0-9]{64}$/.test(c.artifactDigest)
16
+ && c.executorIdentity === null && c.nativeQuiescence === "unproven";
17
+ }
18
+ export function validRecoveryContext(value, operation) {
19
+ return validMaterializationContext(value, operation) || validPublishContext(value, operation);
20
+ }
21
+ function validRecoverableContext(value, operation) {
22
+ if (!value || typeof value !== "object" || Array.isArray(value))
23
+ return false;
24
+ const c = value;
25
+ if (typeof c.executorIdentity !== "string" || !/^[a-zA-Z0-9][a-zA-Z0-9._:-]{0,127}$/.test(c.executorIdentity)
26
+ || c.dispatchState !== "intent" || !/^[a-f0-9]{64}$/.test(c.expectedCanonicalDigest)
27
+ || (c.expectedRestoreDigest !== undefined && !/^[a-f0-9]{64}$/.test(c.expectedRestoreDigest))
28
+ || !validRecoveryContext({ ...c, executorIdentity: null }, operation))
29
+ return false;
30
+ const t = c.canonicalTarget;
31
+ if (!t || typeof t !== "object" || Array.isArray(t))
32
+ return false;
33
+ const keys = c.kind === "publish" ? ["libraryPath", "projectUid", "sequenceUid"] : ["libraryUid", "eventUid", "projectUid", "sequenceUid"];
34
+ if (Object.keys(t).length !== keys.length || !keys.every((key) => typeof t[key] === "string" && t[key].trim().length > 0 && t[key].length <= 1024))
35
+ return false;
36
+ if (c.kind === "publish")
37
+ return t.libraryPath === c.requestedTarget.libraryPath;
38
+ return keys.every((key) => t[key] === c.requestedTarget[key])
39
+ && c.expectedCanonicalDigest === c.desiredDigest;
40
+ }
41
+ function validMaterializationContext(value, operation) {
42
+ if (!value || typeof value !== "object" || Array.isArray(value))
43
+ return false;
44
+ const c = value;
45
+ const t = c.requestedTarget;
46
+ return c.kind === "materialization"
47
+ && typeof c.jobId === "string" && /^materialization-[a-z0-9-]{1,80}$/.test(c.jobId)
48
+ && operation === `native.materialize.${createHash("sha256").update(c.jobId).digest("hex")}`
49
+ && typeof c.dispatchId === "string" && /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(c.dispatchId)
50
+ && Boolean(t && [t.libraryUid, t.eventUid, t.projectUid, t.sequenceUid].every((x) => typeof x === "string" && x.trim().length > 0 && x.length <= 1024))
51
+ && typeof c.artifactDigest === "string" && /^[a-f0-9]{64}$/.test(c.artifactDigest)
52
+ && typeof c.desiredDigest === "string" && /^[a-f0-9]{64}$/.test(c.desiredDigest)
53
+ && (c.destination === undefined || (c.destination.mode === "versioned" &&
54
+ [c.destination.projectUid, c.destination.sequenceUid, c.destination.projectName, c.destination.sequenceName]
55
+ .every((x) => typeof x === "string" && x.trim().length > 0 && x.length <= 1024)))
56
+ && c.executorIdentity === null && c.nativeQuiescence === "unproven";
57
+ }
58
+ const unknown = () => ({ status: "unknown", nativeQuiescence: "unproven", recoveryEligibility: "unavailable", sender: { status: "unknown" } });
59
+ const uuid = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
60
+ /** Read a bounded regular file, refusing symlinks, replacement and in-place changes. */
61
+ async function readStable(path) {
62
+ let handle;
63
+ try {
64
+ handle = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
65
+ const before = await handle.stat();
66
+ if (!before.isFile() || before.size > 16_384)
67
+ throw new Error("invalid evidence file");
68
+ const data = await handle.readFile();
69
+ const after = await handle.stat();
70
+ const current = await lstat(path);
71
+ if (!current.isFile() || before.dev !== current.dev || before.ino !== current.ino || before.size !== after.size
72
+ || before.mtimeMs !== after.mtimeMs || before.ctimeMs !== after.ctimeMs || data.length !== after.size)
73
+ throw new Error("evidence changed");
74
+ return data.toString("utf8");
75
+ }
76
+ catch (error) {
77
+ if (error.code === "ENOENT")
78
+ return undefined;
79
+ throw error;
80
+ }
81
+ finally {
82
+ await handle?.close();
83
+ }
84
+ }
85
+ async function exists(path) {
86
+ try {
87
+ await lstat(path);
88
+ return true;
89
+ }
90
+ catch (error) {
91
+ if (error.code === "ENOENT")
92
+ return false;
93
+ throw error;
94
+ }
95
+ }
96
+ async function readSettlement(path, id) {
97
+ const directory = `${path}.sender-settled`;
98
+ try {
99
+ const info = await lstat(directory);
100
+ if (!info.isDirectory() || info.isSymbolicLink())
101
+ throw new Error("invalid sender directory");
102
+ return await readStable(join(directory, id));
103
+ }
104
+ catch (error) {
105
+ if (error.code === "ENOENT")
106
+ return undefined;
107
+ throw error;
108
+ }
109
+ }
110
+ function markerMatches(raw, reservationId) {
111
+ try {
112
+ const value = JSON.parse(raw);
113
+ return value !== null && value.reservationId === reservationId && typeof value.owner === "string" && uuid.test(value.owner);
114
+ }
115
+ catch {
116
+ return false;
117
+ }
118
+ }
119
+ /**
120
+ * Read-only, point-in-time observation; old writers do not share a lock, so even
121
+ * repeated reads cannot exclude concurrent changes or establish quiescence.
122
+ */
123
+ export async function inspectNativeRecoveryReadOnly(path) {
124
+ try {
125
+ if (await exists(`${path}.lock`))
126
+ return unknown();
127
+ const contents = await readStable(path);
128
+ const active = await readStable(`${path}.active`);
129
+ if (contents === undefined) {
130
+ if (active !== undefined || await exists(`${path}.lock`) || await readStable(path) !== undefined || await readStable(`${path}.active`) !== undefined)
131
+ return unknown();
132
+ return { status: "clear", nativeQuiescence: "unproven", recoveryEligibility: "unavailable", sender: { status: "unknown" } };
133
+ }
134
+ const record = JSON.parse(contents);
135
+ if (!record || typeof record !== "object" || Array.isArray(record) || ![2, 3, 4].includes(record.version)
136
+ || record.kind !== "native-operation" || typeof record.owner !== "string" || !uuid.test(record.owner)
137
+ || typeof record.operation !== "string" || !/^[a-z][a-z0-9.-]{0,127}$/.test(record.operation))
138
+ return unknown();
139
+ if (record.version === 3 && !validRecoveryContext(record.recoveryContext, record.operation))
140
+ return unknown();
141
+ if (record.version === 4 && !validRecoverableContext(record.recoveryContext, record.operation))
142
+ return unknown();
143
+ if (record.senderTracked !== undefined && typeof record.senderTracked !== "boolean")
144
+ return unknown();
145
+ const reservationId = createHash("sha256").update(contents).digest("hex");
146
+ const boundary = await readStable(`${path}.dispatch-${reservationId}`);
147
+ let boundaryEvidence = "unknown";
148
+ if (boundary !== undefined) {
149
+ try {
150
+ const marker = JSON.parse(boundary);
151
+ if (marker.version === 1 && marker.reservationId === reservationId && marker.owner === record.owner)
152
+ boundaryEvidence = "dispatch-possible-recorded";
153
+ }
154
+ catch { /* A damaged marker provides no proof. */ }
155
+ }
156
+ const settled = await readSettlement(path, reservationId);
157
+ const sender = record.senderTracked !== true ? (active !== undefined || settled !== undefined ? "unknown" : "untracked")
158
+ : active !== undefined ? (settled === undefined && markerMatches(active, reservationId) ? "active-or-interrupted" : "unknown")
159
+ : settled !== undefined && markerMatches(settled, reservationId) ? "sender-settled" : "unknown";
160
+ if (await exists(`${path}.lock`) || await readStable(path) !== contents || await readStable(`${path}.active`) !== active
161
+ || await readSettlement(path, reservationId) !== settled || await readStable(`${path}.dispatch-${reservationId}`) !== boundary)
162
+ return unknown();
163
+ const context = record.version === 3 || record.version === 4 ? record.recoveryContext : undefined;
164
+ return { status: "recovery-required", nativeQuiescence: "unproven", recoveryEligibility: "unavailable", sender: { status: sender },
165
+ dispatchState: "possibly-dispatched", boundaryEvidence, missingEvidence: ["receiver-terminal-quiescence", "independent-target-outcome", "legacy-writer-exclusion"],
166
+ safeNextActions: ["inspect", "retain-reservation"],
167
+ ...(context ? { intent: { requestedTarget: context.requestedTarget, artifactDigest: context.artifactDigest,
168
+ ...(context.kind === "materialization" ? { desiredDigest: context.desiredDigest, ...(context.destination ? { destination: context.destination } : {}) } : {}) } } : {}),
169
+ reservation: { version: record.version, reservationId, operation: record.operation,
170
+ ...(context ? { jobId: context.jobId, dispatchId: context.dispatchId, jobCorrelation: "unverified" } : {}) } };
171
+ }
172
+ catch {
173
+ return unknown();
174
+ }
175
+ }
@@ -281,14 +281,19 @@ export function createDisposableNativeOperationSession(options) {
281
281
  }
282
282
  },
283
283
  execute: async (request, context) => {
284
- const result = await options.workflow.execute(request.previewToken, {
284
+ const reservation = await options.recoveryGuard?.beginNative("native.job.disposable-rename");
285
+ // Trackers and workflows may defer work even after they return or fail.
286
+ // Persist uncertainty before invoking either and retain the reservation.
287
+ await reservation?.markDispatchPossible();
288
+ const invoke = () => options.workflow.execute(request.previewToken, {
285
289
  signal: context.signal,
286
- onMutationStart: context.markMutationStarted,
290
+ onMutationStart: () => { context.markMutationStarted(); },
287
291
  });
288
- return {
289
- outcome: result.status === "VERIFIED" ? "completed" : "rolled_back",
290
- evidence: disposableEvidence(result),
291
- };
292
+ const result = options.native.trackNativeDispatch
293
+ ? await options.native.trackNativeDispatch(invoke, () => { })
294
+ : await invoke();
295
+ const evidence = disposableEvidence(result);
296
+ return { outcome: result.status === "VERIFIED" ? "completed" : "rolled_back", evidence };
292
297
  },
293
298
  },
294
299
  });