@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
package/README.md
CHANGED
|
@@ -1,9 +1,16 @@
|
|
|
1
1
|
import { spawn } from "node:child_process";
|
|
2
2
|
import { access } from "node:fs/promises";
|
|
3
|
-
import { bindSpeechAnalysis } from "../../../../packages/runtime/src/index.js";
|
|
3
|
+
import { bindSpeechAnalysis, sameMediaSourceIdentity } from "../../../../packages/runtime/src/index.js";
|
|
4
4
|
export function createCommandAnalyzers(options) {
|
|
5
5
|
return {
|
|
6
|
-
...(options.speechCommand ? {
|
|
6
|
+
...(options.speechCommand ? {
|
|
7
|
+
speechAnalyzer: new CommandSpeechAnalyzer({
|
|
8
|
+
command: options.speechCommand,
|
|
9
|
+
timeoutMs: options.timeoutMs,
|
|
10
|
+
...(options.speechProviderVersion ? { providerVersion: options.speechProviderVersion } : {}),
|
|
11
|
+
...(options.speechRequireVad ? { requireVad: true } : {}),
|
|
12
|
+
}),
|
|
13
|
+
} : {}),
|
|
7
14
|
...(options.audioCommand ? { audioAnalyzer: new CommandAudioAnalyzer({ command: options.audioCommand, timeoutMs: options.timeoutMs }) } : {}),
|
|
8
15
|
...(options.visualCommand ? { visualAnalyzer: new CommandVisualAnalyzer({ command: options.visualCommand, timeoutMs: options.timeoutMs }) } : {}),
|
|
9
16
|
...(options.metadataCommand ? { metadataAnalyzer: new CommandMetadataAnalyzer({ command: options.metadataCommand, timeoutMs: options.timeoutMs }) } : {}),
|
|
@@ -11,15 +18,31 @@ export function createCommandAnalyzers(options) {
|
|
|
11
18
|
}
|
|
12
19
|
export class CommandSpeechAnalyzer {
|
|
13
20
|
options;
|
|
14
|
-
descriptor
|
|
15
|
-
capabilities
|
|
21
|
+
descriptor;
|
|
22
|
+
capabilities;
|
|
16
23
|
constructor(options) {
|
|
17
24
|
this.options = options;
|
|
25
|
+
if (options.requireVad === true && !options.providerVersion?.trim()) {
|
|
26
|
+
throw new Error("ANALYZER_SETUP_REQUIRED: speech provider version is required when VAD is required");
|
|
27
|
+
}
|
|
28
|
+
this.descriptor = {
|
|
29
|
+
id: "command.speech",
|
|
30
|
+
provider: "command",
|
|
31
|
+
...(options.providerVersion ? { version: options.providerVersion } : {}),
|
|
32
|
+
};
|
|
33
|
+
this.capabilities = { transcription: true, vad: options.requireVad === true };
|
|
18
34
|
}
|
|
19
35
|
async analyze(input, range) {
|
|
20
36
|
const result = await runCommand(this.options, { ...input, range }, "speech");
|
|
21
37
|
try {
|
|
22
|
-
|
|
38
|
+
if (this.options.requireVad) {
|
|
39
|
+
requireStrictSpeechProvenance(result, input, range, this.descriptor);
|
|
40
|
+
}
|
|
41
|
+
const analysis = bindSpeechAnalysis(result, { input, range, provider: this.descriptor });
|
|
42
|
+
if (this.options.requireVad && analysis.capability !== "transcription-plus-vad") {
|
|
43
|
+
throw new Error("ANALYZER_INVALID_OUTPUT: configured speech provider must return VAD evidence");
|
|
44
|
+
}
|
|
45
|
+
return analysis;
|
|
23
46
|
}
|
|
24
47
|
catch (error) {
|
|
25
48
|
throw new Error(`ANALYZER_INVALID_OUTPUT: speech analyzer returned invalid JSON or schema: ${String(error)}`);
|
|
@@ -127,6 +150,46 @@ function sourceIdentityOf(media) {
|
|
|
127
150
|
...(media.duration !== undefined ? { duration: media.duration } : {}),
|
|
128
151
|
};
|
|
129
152
|
}
|
|
153
|
+
function requireStrictSpeechProvenance(value, input, range, provider) {
|
|
154
|
+
if (!value || typeof value !== "object") {
|
|
155
|
+
throw new Error("ANALYZER_INVALID_OUTPUT: speech response must include complete trusted provenance");
|
|
156
|
+
}
|
|
157
|
+
const record = value;
|
|
158
|
+
const required = ["schemaVersion", "mediaId", "sourceIdentity", "requestedRange", "revision", "provider"];
|
|
159
|
+
const missing = required.filter((field) => record[field] === undefined);
|
|
160
|
+
if (missing.length > 0) {
|
|
161
|
+
throw new Error(`ANALYZER_INVALID_OUTPUT: speech response is missing provenance: ${missing.join(", ")}`);
|
|
162
|
+
}
|
|
163
|
+
if (!sameAnalyzerDescriptor(record.provider, provider)) {
|
|
164
|
+
throw new Error("ANALYZER_INVALID_OUTPUT: speech response provider provenance does not match the configured provider");
|
|
165
|
+
}
|
|
166
|
+
const sourceIdentity = sourceIdentityOf(input.media);
|
|
167
|
+
if (record.mediaId !== sourceIdentity.mediaId
|
|
168
|
+
|| !sameMediaSourceIdentity(record.sourceIdentity, sourceIdentity)) {
|
|
169
|
+
throw new Error("ANALYZER_INVALID_OUTPUT: speech response source identity does not match the requested media");
|
|
170
|
+
}
|
|
171
|
+
if (record.schemaVersion !== 1) {
|
|
172
|
+
throw new Error("ANALYZER_INVALID_OUTPUT: speech response schema version is not supported");
|
|
173
|
+
}
|
|
174
|
+
const expectedRange = range ?? (input.media.duration === undefined ? undefined : { start: 0, end: input.media.duration });
|
|
175
|
+
if (expectedRange && !sameRange(record.requestedRange, expectedRange)) {
|
|
176
|
+
throw new Error("ANALYZER_INVALID_OUTPUT: speech response range does not match the runtime request");
|
|
177
|
+
}
|
|
178
|
+
}
|
|
179
|
+
function sameAnalyzerDescriptor(value, expected) {
|
|
180
|
+
if (!value || typeof value !== "object")
|
|
181
|
+
return false;
|
|
182
|
+
const descriptor = value;
|
|
183
|
+
return descriptor.id === expected.id
|
|
184
|
+
&& descriptor.provider === expected.provider
|
|
185
|
+
&& descriptor.version === expected.version;
|
|
186
|
+
}
|
|
187
|
+
function sameRange(value, expected) {
|
|
188
|
+
if (!value || typeof value !== "object")
|
|
189
|
+
return false;
|
|
190
|
+
const range = value;
|
|
191
|
+
return range.start === expected.start && range.end === expected.end;
|
|
192
|
+
}
|
|
130
193
|
function validateResult(value, kind) {
|
|
131
194
|
if (!value || typeof value !== "object")
|
|
132
195
|
throw new Error("result must be an object");
|
|
@@ -0,0 +1,175 @@
|
|
|
1
|
+
import { createHash } from "node:crypto";
|
|
2
|
+
import { spawn } from "node:child_process";
|
|
3
|
+
import { readFile } from "node:fs/promises";
|
|
4
|
+
import { timelineIrDigest, validateTimelineIr } from "../../../../packages/runtime/src/index.js";
|
|
5
|
+
const DEFAULT_COMMAND_TIMEOUT_MS = 30_000;
|
|
6
|
+
/**
|
|
7
|
+
* Publishes an immutable FCPXML artifact through an explicit non-UI Final Cut
|
|
8
|
+
* capability. The command owns Final Cut import and target-bound canonical
|
|
9
|
+
* readback; this adapter never activates Final Cut or falls back to UI calls.
|
|
10
|
+
*/
|
|
11
|
+
export class FinalCutBackgroundMaterializationPublisher {
|
|
12
|
+
options;
|
|
13
|
+
commandTimeoutMs;
|
|
14
|
+
constructor(options = {}) {
|
|
15
|
+
this.options = options;
|
|
16
|
+
if (options.commandTimeoutMs !== undefined && (!Number.isFinite(options.commandTimeoutMs) || options.commandTimeoutMs <= 0)) {
|
|
17
|
+
throw new Error("FINAL_CUT_BACKGROUND_MATERIALIZATION_TIMEOUT_INVALID: command timeout must be greater than zero");
|
|
18
|
+
}
|
|
19
|
+
this.commandTimeoutMs = options.commandTimeoutMs ?? DEFAULT_COMMAND_TIMEOUT_MS;
|
|
20
|
+
}
|
|
21
|
+
isAvailable() {
|
|
22
|
+
return this.options.executor !== undefined || Boolean(this.options.command?.trim());
|
|
23
|
+
}
|
|
24
|
+
async publish(request) {
|
|
25
|
+
validateRequest(request);
|
|
26
|
+
const executor = this.options.executor ?? (this.options.command?.trim()
|
|
27
|
+
? commandExecutor(this.options.command.trim(), this.commandTimeoutMs)
|
|
28
|
+
: undefined);
|
|
29
|
+
if (!executor) {
|
|
30
|
+
return {
|
|
31
|
+
state: "blocked",
|
|
32
|
+
code: "FINAL_CUT_BACKGROUND_MATERIALIZATION_UNAVAILABLE",
|
|
33
|
+
message: "No explicit non-UI Final Cut materialization capability is configured",
|
|
34
|
+
retryable: true,
|
|
35
|
+
};
|
|
36
|
+
}
|
|
37
|
+
const artifact = await readFile(request.artifactPath, "utf8");
|
|
38
|
+
if (createHash("sha256").update(artifact).digest("hex") !== request.artifactDigest) {
|
|
39
|
+
throw new Error("MATERIALIZATION_ARTIFACT_CHANGED: the staged FCPXML artifact no longer matches its immutable digest");
|
|
40
|
+
}
|
|
41
|
+
if (timelineIrDigest(request.desired) !== request.desiredDigest) {
|
|
42
|
+
throw new Error("MATERIALIZATION_DESIRED_SNAPSHOT_INVALID: the staged desired Timeline IR digest is invalid");
|
|
43
|
+
}
|
|
44
|
+
const result = await executor({ ...request, desired: structuredClone(request.desired) });
|
|
45
|
+
return validateResult(result);
|
|
46
|
+
}
|
|
47
|
+
}
|
|
48
|
+
function validateRequest(request) {
|
|
49
|
+
if (!request.jobId.trim())
|
|
50
|
+
throw new Error("MATERIALIZATION_REQUEST_INVALID: jobId is required");
|
|
51
|
+
if (!request.artifactPath.trim() || !request.artifactDigest.trim()) {
|
|
52
|
+
throw new Error("MATERIALIZATION_REQUEST_INVALID: immutable artifact path and digest are required");
|
|
53
|
+
}
|
|
54
|
+
if (!request.desiredDigest.trim())
|
|
55
|
+
throw new Error("MATERIALIZATION_REQUEST_INVALID: desired digest is required");
|
|
56
|
+
if (request.collisionPolicy !== "create-only")
|
|
57
|
+
throw new Error("MATERIALIZATION_REQUEST_INVALID: publication must be create-only");
|
|
58
|
+
const { target } = request;
|
|
59
|
+
if (target.provider !== "final-cut" || !target.libraryUid.trim() || !target.eventUid.trim() || !target.projectUid.trim() || !target.sequenceUid.trim()) {
|
|
60
|
+
throw new Error("FCPXML_TARGET_BINDING_INVALID: library, event, project, and sequence identities are required");
|
|
61
|
+
}
|
|
62
|
+
if (request.destination.mode !== "versioned") {
|
|
63
|
+
throw new Error("FINAL_CUT_BACKGROUND_MATERIALIZATION_REUSE_FORBIDDEN: background publication cannot overwrite an existing project");
|
|
64
|
+
}
|
|
65
|
+
if (!request.destination.projectUid.trim() || !request.destination.sequenceUid.trim()) {
|
|
66
|
+
throw new Error("MATERIALIZATION_DESTINATION_INVALID: versioned project and sequence identities are required");
|
|
67
|
+
}
|
|
68
|
+
validateTimelineIr(request.desired);
|
|
69
|
+
}
|
|
70
|
+
function validateResult(result) {
|
|
71
|
+
if (!result || (result.state !== "completed" && result.state !== "blocked")) {
|
|
72
|
+
throw new Error("FINAL_CUT_BACKGROUND_MATERIALIZATION_RESPONSE_INVALID: capability returned an invalid result");
|
|
73
|
+
}
|
|
74
|
+
if (result.state === "blocked") {
|
|
75
|
+
if (typeof result.code !== "string" || typeof result.message !== "string" || !result.code.trim() || !result.message.trim()) {
|
|
76
|
+
throw new Error("FINAL_CUT_BACKGROUND_MATERIALIZATION_RESPONSE_INVALID: blocked result is missing code or message");
|
|
77
|
+
}
|
|
78
|
+
return result;
|
|
79
|
+
}
|
|
80
|
+
validateTimelineIr(result.canonicalReadback);
|
|
81
|
+
validateTargetIdentity(result.canonicalTarget);
|
|
82
|
+
if (result.headedNativeVerified !== false) {
|
|
83
|
+
throw new Error("FINAL_CUT_BACKGROUND_MATERIALIZATION_RESPONSE_INVALID: background publisher cannot claim headed-native verification");
|
|
84
|
+
}
|
|
85
|
+
return result;
|
|
86
|
+
}
|
|
87
|
+
function validateTargetIdentity(target) {
|
|
88
|
+
if (!target || !target.libraryUid?.trim() || !target.eventUid?.trim() || !target.projectUid?.trim() || !target.sequenceUid?.trim()) {
|
|
89
|
+
throw new Error("FINAL_CUT_BACKGROUND_MATERIALIZATION_RESPONSE_INVALID: canonical target identity is incomplete");
|
|
90
|
+
}
|
|
91
|
+
}
|
|
92
|
+
function commandExecutor(command, timeoutMs) {
|
|
93
|
+
return async (request) => {
|
|
94
|
+
let output;
|
|
95
|
+
try {
|
|
96
|
+
output = await runCommand(command, request, timeoutMs);
|
|
97
|
+
}
|
|
98
|
+
catch (error) {
|
|
99
|
+
const detail = error instanceof Error ? error.message : String(error);
|
|
100
|
+
const timedOut = detail.startsWith("FINAL_CUT_BACKGROUND_MATERIALIZATION_COMMAND_TIMEOUT");
|
|
101
|
+
return {
|
|
102
|
+
state: "blocked",
|
|
103
|
+
code: timedOut
|
|
104
|
+
? "FINAL_CUT_BACKGROUND_MATERIALIZATION_COMMAND_TIMEOUT"
|
|
105
|
+
: "FINAL_CUT_BACKGROUND_MATERIALIZATION_COMMAND_UNAVAILABLE",
|
|
106
|
+
message: detail,
|
|
107
|
+
retryable: true,
|
|
108
|
+
};
|
|
109
|
+
}
|
|
110
|
+
let parsed;
|
|
111
|
+
try {
|
|
112
|
+
parsed = JSON.parse(output);
|
|
113
|
+
}
|
|
114
|
+
catch (error) {
|
|
115
|
+
throw new Error(`FINAL_CUT_BACKGROUND_MATERIALIZATION_RESPONSE_INVALID: ${error instanceof Error ? error.message : String(error)}`);
|
|
116
|
+
}
|
|
117
|
+
return validateResult(parsed);
|
|
118
|
+
};
|
|
119
|
+
}
|
|
120
|
+
function runCommand(command, request, timeoutMs) {
|
|
121
|
+
return new Promise((resolve, reject) => {
|
|
122
|
+
const child = spawn(command, [], { stdio: ["pipe", "pipe", "pipe"] });
|
|
123
|
+
let stdout = "";
|
|
124
|
+
let stderr = "";
|
|
125
|
+
let settled = false;
|
|
126
|
+
let closed = false;
|
|
127
|
+
let timeoutHandle;
|
|
128
|
+
let forceKillHandle;
|
|
129
|
+
const cleanup = () => {
|
|
130
|
+
if (timeoutHandle !== undefined)
|
|
131
|
+
clearTimeout(timeoutHandle);
|
|
132
|
+
if (forceKillHandle !== undefined)
|
|
133
|
+
clearTimeout(forceKillHandle);
|
|
134
|
+
};
|
|
135
|
+
const settle = (callback) => {
|
|
136
|
+
if (settled)
|
|
137
|
+
return;
|
|
138
|
+
settled = true;
|
|
139
|
+
cleanup();
|
|
140
|
+
callback();
|
|
141
|
+
};
|
|
142
|
+
child.stdout.setEncoding("utf8");
|
|
143
|
+
child.stderr.setEncoding("utf8");
|
|
144
|
+
child.stdout.on("data", (chunk) => { stdout += chunk; });
|
|
145
|
+
child.stderr.on("data", (chunk) => { stderr += chunk; });
|
|
146
|
+
child.once("error", (error) => settle(() => reject(error)));
|
|
147
|
+
child.once("close", (code) => {
|
|
148
|
+
closed = true;
|
|
149
|
+
if (settled) {
|
|
150
|
+
cleanup();
|
|
151
|
+
return;
|
|
152
|
+
}
|
|
153
|
+
if (code === 0) {
|
|
154
|
+
settle(() => resolve(stdout));
|
|
155
|
+
}
|
|
156
|
+
else {
|
|
157
|
+
settle(() => reject(new Error(`FINAL_CUT_BACKGROUND_MATERIALIZATION_COMMAND_FAILED: command exited ${code}: ${stderr.trim()}`)));
|
|
158
|
+
}
|
|
159
|
+
});
|
|
160
|
+
timeoutHandle = setTimeout(() => {
|
|
161
|
+
if (settled)
|
|
162
|
+
return;
|
|
163
|
+
child.kill("SIGTERM");
|
|
164
|
+
forceKillHandle = setTimeout(() => {
|
|
165
|
+
if (!closed)
|
|
166
|
+
child.kill("SIGKILL");
|
|
167
|
+
}, 1_000);
|
|
168
|
+
settled = true;
|
|
169
|
+
if (timeoutHandle !== undefined)
|
|
170
|
+
clearTimeout(timeoutHandle);
|
|
171
|
+
reject(new Error(`FINAL_CUT_BACKGROUND_MATERIALIZATION_COMMAND_TIMEOUT: command exceeded ${timeoutMs}ms`));
|
|
172
|
+
}, timeoutMs);
|
|
173
|
+
child.stdin.end(`${JSON.stringify(request)}\n`);
|
|
174
|
+
});
|
|
175
|
+
}
|
|
@@ -0,0 +1,31 @@
|
|
|
1
|
+
import { assertTimelineTargetReadAfterWrite, canonicalSnapshotDigest, } from "../../../../packages/runtime/src/index.js";
|
|
2
|
+
/** Recover one verified native mutation and prove the original target digest. */
|
|
3
|
+
export async function recoverCanonicalNativeMutation(request) {
|
|
4
|
+
if (!request.operationId.trim()) {
|
|
5
|
+
throw new Error("FINAL_CUT_CANONICAL_ROLLBACK_FAILED: native operation handle is missing");
|
|
6
|
+
}
|
|
7
|
+
let undone;
|
|
8
|
+
try {
|
|
9
|
+
undone = await request.undo(request.operationId);
|
|
10
|
+
}
|
|
11
|
+
catch (error) {
|
|
12
|
+
throw new Error(`FINAL_CUT_CANONICAL_ROLLBACK_FAILED: native Undo failed: ${String(error)}`);
|
|
13
|
+
}
|
|
14
|
+
if (!undone.undone || undone.verification?.verified !== true) {
|
|
15
|
+
throw new Error("FINAL_CUT_CANONICAL_ROLLBACK_FAILED: native Undo did not verify restoration");
|
|
16
|
+
}
|
|
17
|
+
const restored = await request.readSnapshot();
|
|
18
|
+
assertTimelineTargetReadAfterWrite(request.target, request.before, restored);
|
|
19
|
+
const beforeDigest = canonicalSnapshotDigest(request.before);
|
|
20
|
+
const restoredDigest = canonicalSnapshotDigest(restored);
|
|
21
|
+
if (restoredDigest !== beforeDigest) {
|
|
22
|
+
throw new Error("FINAL_CUT_CANONICAL_ROLLBACK_FAILED: restored canonical digest does not match the pre-edit state");
|
|
23
|
+
}
|
|
24
|
+
return {
|
|
25
|
+
attempted: true,
|
|
26
|
+
succeeded: true,
|
|
27
|
+
operationId: request.operationId,
|
|
28
|
+
beforeDigest,
|
|
29
|
+
restoredDigest,
|
|
30
|
+
};
|
|
31
|
+
}
|
|
@@ -0,0 +1,16 @@
|
|
|
1
|
+
import { assertTimelineTargetReadAfterWrite, canonicalSnapshotDigest, diffSnapshots, } from "../../../../packages/runtime/src/index.js";
|
|
2
|
+
/** Validate one canonical before/after pair and return its durable evidence. */
|
|
3
|
+
export function verifyCanonicalReadback(before, after, target, options = {}) {
|
|
4
|
+
const beforeDigest = canonicalSnapshotDigest(before);
|
|
5
|
+
const afterDigest = canonicalSnapshotDigest(after);
|
|
6
|
+
if (beforeDigest === afterDigest) {
|
|
7
|
+
throw new Error("FINAL_CUT_CANONICAL_READBACK_FAILED: native edit did not change the canonical digest");
|
|
8
|
+
}
|
|
9
|
+
if (after.revision.id === before.revision.id || after.revision.sequence <= before.revision.sequence) {
|
|
10
|
+
throw new Error("FINAL_CUT_CANONICAL_READBACK_FAILED: revision did not advance after native mutation");
|
|
11
|
+
}
|
|
12
|
+
assertTimelineTargetReadAfterWrite(target, before, after);
|
|
13
|
+
const diff = diffSnapshots(before, after);
|
|
14
|
+
options.validateDiff?.(diff);
|
|
15
|
+
return { beforeDigest, afterDigest, diff };
|
|
16
|
+
}
|