@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.
- package/bin/framekit.mjs +2 -1
- package/dist-package/adapters/final-cut/typescript/src/assets.js +157 -35
- package/dist-package/adapters/final-cut/typescript/src/background-export.js +384 -0
- package/dist-package/adapters/final-cut/typescript/src/background-materialization.js +175 -0
- package/dist-package/adapters/final-cut/typescript/src/canonical.js +189 -32
- package/dist-package/adapters/final-cut/typescript/src/connection.js +55 -17
- package/dist-package/adapters/final-cut/typescript/src/disposable-native.js +33 -7
- package/dist-package/adapters/final-cut/typescript/src/fcpxml-console-experiment.js +74 -0
- package/dist-package/adapters/final-cut/typescript/src/fcpxml.js +615 -49
- package/dist-package/adapters/final-cut/typescript/src/index.js +10 -0
- package/dist-package/adapters/final-cut/typescript/src/library-inspection.js +390 -0
- package/dist-package/adapters/final-cut/typescript/src/live.js +16 -6
- package/dist-package/adapters/final-cut/typescript/src/media.js +151 -0
- package/dist-package/adapters/final-cut/typescript/src/native-session.js +412 -0
- package/dist-package/adapters/final-cut/typescript/src/native.js +1192 -364
- package/dist-package/adapters/final-cut/typescript/src/publisher.js +225 -32
- package/dist-package/adapters/final-cut/typescript/src/session.js +163 -17
- package/dist-package/adapters/final-cut/typescript/src/shadow-mutation.js +120 -0
- package/dist-package/adapters/final-cut/typescript/src/sqlite-inspection.js +433 -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 +41 -8
- package/dist-package/apps/mcp-server/src/materialization-jobs.js +326 -0
- package/dist-package/apps/mcp-server/src/routing.js +227 -39
- package/dist-package/apps/mcp-server/src/server.js +642 -97
- package/dist-package/apps/mcp-server/src/version.js +109 -1
- package/dist-package/packages/runtime/src/application/media-analysis-service.js +1 -3
- package/dist-package/packages/runtime/src/application/project-service.js +46 -7
- package/dist-package/packages/runtime/src/capabilities.js +55 -7
- package/dist-package/packages/runtime/src/context/project-catalog.js +159 -0
- package/dist-package/packages/runtime/src/domain/capabilities.js +33 -0
- package/dist-package/packages/runtime/src/domain/context.js +14 -1
- package/dist-package/packages/runtime/src/domain/index.js +1 -0
- package/dist-package/packages/runtime/src/domain/timeline-target.js +217 -0
- package/dist-package/packages/runtime/src/editing/edit-service.js +15 -1
- package/dist-package/packages/runtime/src/editing/intent.js +178 -2
- package/dist-package/packages/runtime/src/index.js +3 -0
- package/dist-package/packages/runtime/src/runtime.js +2 -2
- 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/dist-package/packages/testkit/src/in-memory-editor.js +5 -4
- package/package.json +12 -6
package/bin/framekit.mjs
CHANGED
|
@@ -6,7 +6,8 @@ import { fileURLToPath } from "node:url";
|
|
|
6
6
|
|
|
7
7
|
const packagedEntrypoint = fileURLToPath(new URL("../dist-package/apps/cli/src/main.js", import.meta.url));
|
|
8
8
|
const developmentEntrypoint = fileURLToPath(new URL("../apps/cli/src/main.ts", import.meta.url));
|
|
9
|
-
const
|
|
9
|
+
const development = existsSync(developmentEntrypoint);
|
|
10
|
+
const packaged = !development && existsSync(packagedEntrypoint);
|
|
10
11
|
const child = spawn(
|
|
11
12
|
process.execPath,
|
|
12
13
|
[...(packaged ? [] : ["--import", "tsx"]), packaged ? packagedEntrypoint : developmentEntrypoint, ...process.argv.slice(2)],
|
|
@@ -1,6 +1,7 @@
|
|
|
1
|
-
import {
|
|
1
|
+
import { createHash } from "node:crypto";
|
|
2
|
+
import { readFile, readdir, stat } from "node:fs/promises";
|
|
2
3
|
import { homedir } from "node:os";
|
|
3
|
-
import { basename, join, resolve } from "node:path";
|
|
4
|
+
import { basename, join, relative, resolve } from "node:path";
|
|
4
5
|
const CATEGORY_BY_DIRECTORY = {
|
|
5
6
|
"Audio Effects.localized": "audio-effect",
|
|
6
7
|
"Effects.localized": "effect",
|
|
@@ -20,45 +21,93 @@ export function defaultFinalCutAssetRoots() {
|
|
|
20
21
|
export class FinalCutAssetRegistry {
|
|
21
22
|
roots;
|
|
22
23
|
nativeTitleProvider;
|
|
24
|
+
nativeTransitionProvider;
|
|
23
25
|
cached;
|
|
24
26
|
constructor(options = {}) {
|
|
25
27
|
this.roots = (options.roots ?? defaultFinalCutAssetRoots()).map((root) => resolve(root));
|
|
26
28
|
this.nativeTitleProvider = options.nativeTitleProvider;
|
|
29
|
+
this.nativeTransitionProvider = options.nativeTransitionProvider;
|
|
27
30
|
}
|
|
28
31
|
async listAssets(query) {
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
32
|
+
const scanned = await this.scan();
|
|
33
|
+
if (!this.cached || this.cached.signature !== scanned.signature)
|
|
34
|
+
this.cached = scanned;
|
|
35
|
+
const discovery = query?.discovery ?? "background";
|
|
36
|
+
const filesystemAssets = discovery === "native" ? [] : filterAssets(this.cached.assets, query);
|
|
37
|
+
if (discovery === "background")
|
|
33
38
|
return filesystemAssets;
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
39
|
+
if (discovery === "native" && query?.kind === "title" && !this.nativeTitleProvider) {
|
|
40
|
+
throw new Error("CAPABILITY_UNAVAILABLE: native title discovery is not configured");
|
|
41
|
+
}
|
|
42
|
+
if (discovery === "native" && query?.kind === "transition" && !this.nativeTransitionProvider) {
|
|
43
|
+
throw new Error("CAPABILITY_UNAVAILABLE: native transition discovery is not configured");
|
|
44
|
+
}
|
|
45
|
+
if (discovery === "native" && !query?.kind && !this.nativeTitleProvider && !this.nativeTransitionProvider) {
|
|
46
|
+
throw new Error("CAPABILITY_UNAVAILABLE: native asset discovery is not configured");
|
|
47
|
+
}
|
|
48
|
+
let nativeTitleAssets = [];
|
|
49
|
+
let nativeTransitionAssets = [];
|
|
50
|
+
let nativeTitleError;
|
|
51
|
+
let nativeTransitionError;
|
|
52
|
+
if (this.nativeTitleProvider && (!query?.kind || query.kind === "title")) {
|
|
53
|
+
let nativeTitles;
|
|
54
|
+
try {
|
|
55
|
+
nativeTitles = await this.nativeTitleProvider.searchTitles(query?.query ?? "");
|
|
56
|
+
if (nativeTitles.length === 0) {
|
|
57
|
+
throw new Error("FINAL_CUT_NATIVE_TITLE_DISCOVERY_EMPTY: native title provider returned no title assets");
|
|
58
|
+
}
|
|
59
|
+
}
|
|
60
|
+
catch (error) {
|
|
61
|
+
nativeTitleError = error;
|
|
62
|
+
nativeTitles = [];
|
|
63
|
+
}
|
|
64
|
+
nativeTitleAssets = nativeTitles.map(nativeTitleAsset);
|
|
37
65
|
}
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
66
|
+
const nativeTransitionProvider = this.nativeTransitionProvider;
|
|
67
|
+
const shouldSearchNativeTransitions = nativeTransitionProvider
|
|
68
|
+
&& (!query?.kind || query.kind === "transition");
|
|
69
|
+
if (shouldSearchNativeTransitions) {
|
|
70
|
+
let nativeTransitions;
|
|
71
|
+
try {
|
|
72
|
+
nativeTransitions = await nativeTransitionProvider.searchTransitions(query?.query ?? "");
|
|
73
|
+
}
|
|
74
|
+
catch (error) {
|
|
75
|
+
nativeTransitionError = error;
|
|
76
|
+
nativeTransitions = [];
|
|
77
|
+
}
|
|
78
|
+
nativeTransitionAssets = nativeTransitions.map(nativeTransitionAsset);
|
|
44
79
|
}
|
|
45
|
-
const
|
|
46
|
-
|
|
80
|
+
const nativeError = nativeTransitionError ?? nativeTitleError;
|
|
81
|
+
const filesystemResults = nativeError && filesystemAssets.length > 0
|
|
82
|
+
? withNativeDiscoveryDiagnostic(filesystemAssets, nativeError)
|
|
83
|
+
: filesystemAssets;
|
|
84
|
+
const assets = filterAssets(dedupeAssets([
|
|
85
|
+
...filesystemResults,
|
|
86
|
+
...nativeTitleAssets,
|
|
87
|
+
...nativeTransitionAssets,
|
|
88
|
+
]), query);
|
|
89
|
+
if (assets.length === 0 && nativeError)
|
|
90
|
+
throw nativeError;
|
|
91
|
+
return assets;
|
|
47
92
|
}
|
|
48
93
|
refresh() {
|
|
49
94
|
this.cached = undefined;
|
|
50
95
|
}
|
|
51
96
|
async scan() {
|
|
52
97
|
const assets = [];
|
|
98
|
+
const signatures = [];
|
|
53
99
|
for (const root of this.roots) {
|
|
54
|
-
await scanDirectory(root, assets);
|
|
100
|
+
await scanDirectory(root, assets, signatures, root);
|
|
55
101
|
}
|
|
56
|
-
return
|
|
57
|
-
.sort(
|
|
58
|
-
|
|
102
|
+
return {
|
|
103
|
+
signature: signatures.sort().join("\n"),
|
|
104
|
+
assets: assets
|
|
105
|
+
.sort((left, right) => `${left.kind}:${left.name}:${left.id}`.localeCompare(`${right.kind}:${right.name}:${right.id}`))
|
|
106
|
+
.filter((asset, index, all) => index === all.findIndex((candidate) => candidate.id === asset.id)),
|
|
107
|
+
};
|
|
59
108
|
}
|
|
60
109
|
}
|
|
61
|
-
async function scanDirectory(directory, assets) {
|
|
110
|
+
async function scanDirectory(directory, assets, signatures, root) {
|
|
62
111
|
let entries;
|
|
63
112
|
try {
|
|
64
113
|
entries = await readdir(directory, { withFileTypes: true });
|
|
@@ -69,14 +118,14 @@ async function scanDirectory(directory, assets) {
|
|
|
69
118
|
for (const entry of entries) {
|
|
70
119
|
const path = join(directory, entry.name);
|
|
71
120
|
if (entry.isDirectory() && CATEGORY_BY_DIRECTORY[entry.name]) {
|
|
72
|
-
await scanCategory(path, CATEGORY_BY_DIRECTORY[entry.name], assets);
|
|
121
|
+
await scanCategory(path, CATEGORY_BY_DIRECTORY[entry.name], assets, signatures, root);
|
|
73
122
|
}
|
|
74
123
|
else if (entry.isDirectory()) {
|
|
75
|
-
await scanDirectory(path, assets);
|
|
124
|
+
await scanDirectory(path, assets, signatures, root);
|
|
76
125
|
}
|
|
77
126
|
}
|
|
78
127
|
}
|
|
79
|
-
async function scanCategory(directory, kind, assets) {
|
|
128
|
+
async function scanCategory(directory, kind, assets, signatures, root) {
|
|
80
129
|
let entries;
|
|
81
130
|
try {
|
|
82
131
|
entries = await readdir(directory, { withFileTypes: true });
|
|
@@ -88,6 +137,8 @@ async function scanCategory(directory, kind, assets) {
|
|
|
88
137
|
if (!entry.isDirectory() || !BUNDLE_SUFFIXES.has(extension(entry.name)))
|
|
89
138
|
continue;
|
|
90
139
|
const path = join(directory, entry.name);
|
|
140
|
+
const fingerprint = await bundleFingerprint(path);
|
|
141
|
+
signatures.push(fingerprint.signature);
|
|
91
142
|
const metadata = await readMetadata(path);
|
|
92
143
|
assets.push({
|
|
93
144
|
id: `filesystem:${kind}:${path}`,
|
|
@@ -98,25 +149,71 @@ async function scanCategory(directory, kind, assets) {
|
|
|
98
149
|
path,
|
|
99
150
|
...metadata,
|
|
100
151
|
identity: path,
|
|
152
|
+
sourceDigest: fingerprint.sourceDigest,
|
|
101
153
|
provider: "filesystem-motion-template",
|
|
102
154
|
source: "filesystem",
|
|
103
155
|
discovery: {
|
|
104
156
|
backend: "filesystem-motion-template",
|
|
105
157
|
guarantee: "observed",
|
|
106
158
|
},
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
operation: "editor.native.title.add",
|
|
113
|
-
},
|
|
114
|
-
}
|
|
115
|
-
: {}),
|
|
159
|
+
installation: {
|
|
160
|
+
path,
|
|
161
|
+
root,
|
|
162
|
+
relativePath: relative(root, path),
|
|
163
|
+
},
|
|
116
164
|
},
|
|
117
165
|
});
|
|
118
166
|
}
|
|
119
167
|
}
|
|
168
|
+
async function bundleFingerprint(path) {
|
|
169
|
+
const files = [];
|
|
170
|
+
await collectBundleFiles(path, files);
|
|
171
|
+
files.sort((left, right) => left.path.localeCompare(right.path));
|
|
172
|
+
const digest = createHash("sha256");
|
|
173
|
+
for (const file of files) {
|
|
174
|
+
digest.update(file.path).update("\0");
|
|
175
|
+
try {
|
|
176
|
+
digest.update(await readFile(file.path));
|
|
177
|
+
}
|
|
178
|
+
catch {
|
|
179
|
+
digest.update("missing");
|
|
180
|
+
}
|
|
181
|
+
}
|
|
182
|
+
return {
|
|
183
|
+
signature: files.map((file) => `${file.path}:${file.size}:${file.modifiedAt}`).join("\n"),
|
|
184
|
+
sourceDigest: `sha256:${digest.digest("hex")}`,
|
|
185
|
+
};
|
|
186
|
+
}
|
|
187
|
+
async function collectBundleFiles(path, files) {
|
|
188
|
+
let details;
|
|
189
|
+
try {
|
|
190
|
+
details = await stat(path);
|
|
191
|
+
}
|
|
192
|
+
catch {
|
|
193
|
+
return;
|
|
194
|
+
}
|
|
195
|
+
if (details.isFile()) {
|
|
196
|
+
files.push({ path, size: details.size, modifiedAt: details.mtimeMs });
|
|
197
|
+
return;
|
|
198
|
+
}
|
|
199
|
+
if (!details.isDirectory())
|
|
200
|
+
return;
|
|
201
|
+
let entries;
|
|
202
|
+
try {
|
|
203
|
+
entries = await readdir(path, { withFileTypes: true });
|
|
204
|
+
}
|
|
205
|
+
catch {
|
|
206
|
+
return;
|
|
207
|
+
}
|
|
208
|
+
for (const entry of entries) {
|
|
209
|
+
if (entry.isDirectory())
|
|
210
|
+
await collectBundleFiles(join(path, entry.name), files);
|
|
211
|
+
}
|
|
212
|
+
for (const entry of entries) {
|
|
213
|
+
if (entry.isFile())
|
|
214
|
+
await collectBundleFiles(join(path, entry.name), files);
|
|
215
|
+
}
|
|
216
|
+
}
|
|
120
217
|
function nativeTitleAsset(match) {
|
|
121
218
|
if (!match.id.startsWith("final-cut:title:") || !match.identity.trim() || !match.name.trim()) {
|
|
122
219
|
throw new Error("FINAL_CUT_NATIVE_TITLE_ID_UNAVAILABLE: native title provider returned an unstable identity");
|
|
@@ -142,12 +239,37 @@ function nativeTitleAsset(match) {
|
|
|
142
239
|
},
|
|
143
240
|
};
|
|
144
241
|
}
|
|
242
|
+
function nativeTransitionAsset(match) {
|
|
243
|
+
if (!match.id.startsWith("final-cut:transition:") || !match.identity.trim() || !match.name.trim()) {
|
|
244
|
+
throw new Error("FINAL_CUT_NATIVE_TRANSITION_ID_UNAVAILABLE: native transition provider returned an unstable identity");
|
|
245
|
+
}
|
|
246
|
+
return {
|
|
247
|
+
id: match.id,
|
|
248
|
+
kind: "transition",
|
|
249
|
+
name: match.name,
|
|
250
|
+
vendor: match.vendor,
|
|
251
|
+
metadata: {
|
|
252
|
+
identity: match.identity,
|
|
253
|
+
provider: "final-cut-accessibility",
|
|
254
|
+
source: "final-cut-transitions-browser",
|
|
255
|
+
discovery: {
|
|
256
|
+
backend: "final-cut-accessibility",
|
|
257
|
+
guarantee: "observed",
|
|
258
|
+
},
|
|
259
|
+
placement: {
|
|
260
|
+
backend: "final-cut-accessibility",
|
|
261
|
+
guarantee: "native-verified",
|
|
262
|
+
operation: "editor.native.transition.add.preview",
|
|
263
|
+
},
|
|
264
|
+
},
|
|
265
|
+
};
|
|
266
|
+
}
|
|
145
267
|
function dedupeAssets(assets) {
|
|
146
268
|
return assets
|
|
147
269
|
.sort((left, right) => `${left.kind}:${left.name}:${left.id}`.localeCompare(`${right.kind}:${right.name}:${right.id}`))
|
|
148
270
|
.filter((asset, index, all) => index === all.findIndex((candidate) => candidate.id === asset.id));
|
|
149
271
|
}
|
|
150
|
-
function
|
|
272
|
+
function withNativeDiscoveryDiagnostic(assets, error) {
|
|
151
273
|
const native = {
|
|
152
274
|
backend: "final-cut-accessibility",
|
|
153
275
|
guarantee: "none",
|
|
@@ -0,0 +1,384 @@
|
|
|
1
|
+
import { createHash, randomUUID } from "node:crypto";
|
|
2
|
+
import { createReadStream, createWriteStream } from "node:fs";
|
|
3
|
+
import { access, constants, link, rename, stat, unlink } from "node:fs/promises";
|
|
4
|
+
import { basename, dirname, extname, join, resolve } from "node:path";
|
|
5
|
+
import { Transform } from "node:stream";
|
|
6
|
+
import { pipeline } from "node:stream/promises";
|
|
7
|
+
/**
|
|
8
|
+
* Runs an injected background renderer against a staged output.
|
|
9
|
+
*
|
|
10
|
+
* This provider is intentionally external/artifact-derived. It does not invoke
|
|
11
|
+
* Final Cut UI and never labels its result as native Final Cut rendering.
|
|
12
|
+
*/
|
|
13
|
+
export class BackgroundRenderExportProvider {
|
|
14
|
+
enabled;
|
|
15
|
+
renderer;
|
|
16
|
+
probe;
|
|
17
|
+
defaultTimeoutMs;
|
|
18
|
+
constructor(options = {}) {
|
|
19
|
+
this.enabled = options.enabled ?? false;
|
|
20
|
+
this.renderer = options.renderer;
|
|
21
|
+
this.probe = options.probe;
|
|
22
|
+
this.defaultTimeoutMs = options.defaultTimeoutMs ?? 120_000;
|
|
23
|
+
}
|
|
24
|
+
isAvailable() {
|
|
25
|
+
return this.enabled && this.renderer !== undefined && this.probe !== undefined;
|
|
26
|
+
}
|
|
27
|
+
start(request) {
|
|
28
|
+
if (!this.isAvailable()) {
|
|
29
|
+
throw new Error("BACKGROUND_RENDER_UNAVAILABLE: no configured background renderer and verifier are available");
|
|
30
|
+
}
|
|
31
|
+
validateRequest(request);
|
|
32
|
+
const job = new BackgroundRenderJobHandle(request, this.renderer, this.probe, this.defaultTimeoutMs);
|
|
33
|
+
job.start();
|
|
34
|
+
return job;
|
|
35
|
+
}
|
|
36
|
+
}
|
|
37
|
+
class BackgroundRenderJobHandle {
|
|
38
|
+
request;
|
|
39
|
+
renderer;
|
|
40
|
+
probe;
|
|
41
|
+
defaultTimeoutMs;
|
|
42
|
+
id = `background-render-${randomUUID()}`;
|
|
43
|
+
controller = new AbortController();
|
|
44
|
+
listeners = new Set();
|
|
45
|
+
completion;
|
|
46
|
+
resolveCompletion;
|
|
47
|
+
rejectCompletion;
|
|
48
|
+
current = {
|
|
49
|
+
jobId: this.id,
|
|
50
|
+
state: "queued",
|
|
51
|
+
progress: 0,
|
|
52
|
+
message: "background render queued",
|
|
53
|
+
};
|
|
54
|
+
cancelRequested = false;
|
|
55
|
+
committed = false;
|
|
56
|
+
constructor(request, renderer, probe, defaultTimeoutMs) {
|
|
57
|
+
this.request = request;
|
|
58
|
+
this.renderer = renderer;
|
|
59
|
+
this.probe = probe;
|
|
60
|
+
this.defaultTimeoutMs = defaultTimeoutMs;
|
|
61
|
+
this.completion = new Promise((resolveCompletion, rejectCompletion) => {
|
|
62
|
+
this.resolveCompletion = resolveCompletion;
|
|
63
|
+
this.rejectCompletion = rejectCompletion;
|
|
64
|
+
});
|
|
65
|
+
}
|
|
66
|
+
start() {
|
|
67
|
+
queueMicrotask(() => void this.run());
|
|
68
|
+
}
|
|
69
|
+
status() {
|
|
70
|
+
return { ...this.current, ...(this.current.error ? { error: { ...this.current.error } } : {}) };
|
|
71
|
+
}
|
|
72
|
+
onProgress(listener) {
|
|
73
|
+
this.listeners.add(listener);
|
|
74
|
+
return () => this.listeners.delete(listener);
|
|
75
|
+
}
|
|
76
|
+
result() {
|
|
77
|
+
return this.completion;
|
|
78
|
+
}
|
|
79
|
+
async cancel() {
|
|
80
|
+
if (isTerminal(this.current.state))
|
|
81
|
+
return;
|
|
82
|
+
this.cancelRequested = true;
|
|
83
|
+
this.controller.abort(backgroundRenderError("BACKGROUND_RENDER_CANCELLED", "background render cancelled by caller"));
|
|
84
|
+
await this.completion.catch(() => undefined);
|
|
85
|
+
}
|
|
86
|
+
async run() {
|
|
87
|
+
const outputPath = resolve(this.request.outputPath.trim());
|
|
88
|
+
const stagingPath = createStagingPath(outputPath);
|
|
89
|
+
const timeout = setTimeout(() => {
|
|
90
|
+
this.controller.abort(backgroundRenderError("BACKGROUND_RENDER_TIMEOUT", "background render exceeded its deadline"));
|
|
91
|
+
}, this.request.timeoutMs ?? this.defaultTimeoutMs);
|
|
92
|
+
let sourceSnapshotPath;
|
|
93
|
+
let completionResult;
|
|
94
|
+
let completionError;
|
|
95
|
+
try {
|
|
96
|
+
if (this.controller.signal.aborted)
|
|
97
|
+
throw this.controller.signal.reason;
|
|
98
|
+
await assertOutputDirectory(outputPath);
|
|
99
|
+
await assertOutputCanBeReplaced(outputPath, this.request.overwrite ?? false);
|
|
100
|
+
sourceSnapshotPath = await snapshotSource(this.request.source, outputPath, this.controller.signal);
|
|
101
|
+
const renderRequest = sourceSnapshotPath === undefined
|
|
102
|
+
? this.request
|
|
103
|
+
: {
|
|
104
|
+
...this.request,
|
|
105
|
+
source: { ...this.request.source, artifactPath: sourceSnapshotPath },
|
|
106
|
+
};
|
|
107
|
+
this.update("rendering", 0, "background renderer started");
|
|
108
|
+
await this.runRenderer(stagingPath, renderRequest);
|
|
109
|
+
throwIfAborted(this.controller.signal);
|
|
110
|
+
this.update("verifying", 0.9, "verifying staged output");
|
|
111
|
+
const details = await stat(stagingPath);
|
|
112
|
+
throwIfAborted(this.controller.signal);
|
|
113
|
+
if (!details.isFile() || details.size <= 0) {
|
|
114
|
+
throw backgroundRenderError("BACKGROUND_RENDER_VERIFICATION_FAILED", "renderer produced no non-empty staged output");
|
|
115
|
+
}
|
|
116
|
+
const probed = await this.probe(stagingPath);
|
|
117
|
+
throwIfAborted(this.controller.signal);
|
|
118
|
+
validateProbe(probed);
|
|
119
|
+
const outputDigest = await sha256File(stagingPath, this.controller.signal);
|
|
120
|
+
throwIfAborted(this.controller.signal);
|
|
121
|
+
const metadata = {
|
|
122
|
+
outputPath,
|
|
123
|
+
sizeBytes: details.size,
|
|
124
|
+
format: outputFormat(outputPath),
|
|
125
|
+
outputDigest,
|
|
126
|
+
...probed,
|
|
127
|
+
};
|
|
128
|
+
await commitOutput(stagingPath, outputPath, this.request.overwrite ?? false, this.controller.signal);
|
|
129
|
+
this.committed = true;
|
|
130
|
+
const result = {
|
|
131
|
+
jobId: this.id,
|
|
132
|
+
outputPath,
|
|
133
|
+
preset: this.request.preset,
|
|
134
|
+
completed: true,
|
|
135
|
+
verified: true,
|
|
136
|
+
metadata,
|
|
137
|
+
provenance: {
|
|
138
|
+
renderer: "external-renderer",
|
|
139
|
+
evidenceTier: this.request.source.kind === "fcpxml-artifact" ? "artifact-rendered" : "external-rendered",
|
|
140
|
+
source: this.request.source,
|
|
141
|
+
},
|
|
142
|
+
};
|
|
143
|
+
this.update("completed", 1, "background render verified and committed");
|
|
144
|
+
completionResult = result;
|
|
145
|
+
}
|
|
146
|
+
catch (error) {
|
|
147
|
+
const normalized = normalizeBackgroundRenderError(error, this.cancelRequested);
|
|
148
|
+
const cancelled = normalized.code === "BACKGROUND_RENDER_CANCELLED";
|
|
149
|
+
this.update(cancelled ? "cancelled" : "failed", this.current.progress, normalized.message, normalized);
|
|
150
|
+
completionError = normalized;
|
|
151
|
+
}
|
|
152
|
+
finally {
|
|
153
|
+
clearTimeout(timeout);
|
|
154
|
+
if (!this.committed)
|
|
155
|
+
await removeIfPresent(stagingPath);
|
|
156
|
+
if (sourceSnapshotPath)
|
|
157
|
+
await removeIfPresent(sourceSnapshotPath);
|
|
158
|
+
}
|
|
159
|
+
if (completionResult)
|
|
160
|
+
this.resolveCompletion(completionResult);
|
|
161
|
+
else
|
|
162
|
+
this.rejectCompletion(completionError);
|
|
163
|
+
}
|
|
164
|
+
async runRenderer(stagingPath, request) {
|
|
165
|
+
throwIfAborted(this.controller.signal);
|
|
166
|
+
const renderPromise = this.renderer({
|
|
167
|
+
request,
|
|
168
|
+
stagingPath,
|
|
169
|
+
signal: this.controller.signal,
|
|
170
|
+
reportProgress: (progress, message) => {
|
|
171
|
+
if (this.current.state !== "rendering")
|
|
172
|
+
return;
|
|
173
|
+
this.update("rendering", progress, message ?? "background renderer in progress");
|
|
174
|
+
},
|
|
175
|
+
});
|
|
176
|
+
const abortPromise = new Promise((_, reject) => {
|
|
177
|
+
if (this.controller.signal.aborted) {
|
|
178
|
+
reject(this.controller.signal.reason);
|
|
179
|
+
return;
|
|
180
|
+
}
|
|
181
|
+
this.controller.signal.addEventListener("abort", () => reject(this.controller.signal.reason), { once: true });
|
|
182
|
+
});
|
|
183
|
+
try {
|
|
184
|
+
await Promise.race([renderPromise, abortPromise]);
|
|
185
|
+
}
|
|
186
|
+
catch (error) {
|
|
187
|
+
if (this.controller.signal.aborted)
|
|
188
|
+
await renderPromise.catch(() => undefined);
|
|
189
|
+
throw error;
|
|
190
|
+
}
|
|
191
|
+
}
|
|
192
|
+
update(state, progress, message, error) {
|
|
193
|
+
this.current = {
|
|
194
|
+
jobId: this.id,
|
|
195
|
+
state,
|
|
196
|
+
progress: Math.max(0, Math.min(1, progress)),
|
|
197
|
+
message,
|
|
198
|
+
...(error ? { error } : {}),
|
|
199
|
+
};
|
|
200
|
+
for (const listener of this.listeners) {
|
|
201
|
+
try {
|
|
202
|
+
listener(this.status());
|
|
203
|
+
}
|
|
204
|
+
catch {
|
|
205
|
+
// Progress observers must not affect job execution or settlement.
|
|
206
|
+
}
|
|
207
|
+
}
|
|
208
|
+
}
|
|
209
|
+
}
|
|
210
|
+
function validateRequest(request) {
|
|
211
|
+
if (!request.outputPath.trim())
|
|
212
|
+
throw backgroundRenderError("BACKGROUND_RENDER_INVALID_REQUEST", "outputPath is required");
|
|
213
|
+
if (!request.preset.trim())
|
|
214
|
+
throw backgroundRenderError("BACKGROUND_RENDER_INVALID_REQUEST", "preset is required");
|
|
215
|
+
const { target } = request.source;
|
|
216
|
+
if (!target.projectId.trim() || !target.sequenceId.trim()) {
|
|
217
|
+
throw backgroundRenderError("BACKGROUND_RENDER_INVALID_SOURCE", "source target requires projectId and sequenceId");
|
|
218
|
+
}
|
|
219
|
+
if (!target.revision && !target.digest) {
|
|
220
|
+
throw backgroundRenderError("BACKGROUND_RENDER_INVALID_SOURCE", "source target requires a revision or digest binding");
|
|
221
|
+
}
|
|
222
|
+
if (request.source.kind === "final-cut-timeline") {
|
|
223
|
+
throw backgroundRenderError("BACKGROUND_RENDER_NATIVE_UNAVAILABLE", "no supported background-native Final Cut renderer is configured");
|
|
224
|
+
}
|
|
225
|
+
if (target.digest !== undefined && !target.digest.trim()) {
|
|
226
|
+
throw backgroundRenderError("BACKGROUND_RENDER_INVALID_SOURCE", "source digest cannot be empty");
|
|
227
|
+
}
|
|
228
|
+
if (request.source.kind === "fcpxml-artifact") {
|
|
229
|
+
if (!request.source.artifactPath?.trim()) {
|
|
230
|
+
throw backgroundRenderError("BACKGROUND_RENDER_INVALID_SOURCE", "fcpxml-artifact source requires artifactPath");
|
|
231
|
+
}
|
|
232
|
+
if (!target.digest) {
|
|
233
|
+
throw backgroundRenderError("BACKGROUND_RENDER_INVALID_SOURCE", "fcpxml-artifact source requires a digest binding");
|
|
234
|
+
}
|
|
235
|
+
}
|
|
236
|
+
if (request.timeoutMs !== undefined && (!Number.isFinite(request.timeoutMs) || request.timeoutMs <= 0)) {
|
|
237
|
+
throw backgroundRenderError("BACKGROUND_RENDER_INVALID_REQUEST", "timeoutMs must be a positive finite number");
|
|
238
|
+
}
|
|
239
|
+
}
|
|
240
|
+
async function snapshotSource(source, outputPath, signal) {
|
|
241
|
+
if (source.kind !== "fcpxml-artifact")
|
|
242
|
+
return undefined;
|
|
243
|
+
const snapshotPath = createSourceSnapshotPath(outputPath, source.artifactPath);
|
|
244
|
+
const hash = createHash("sha256");
|
|
245
|
+
try {
|
|
246
|
+
await pipeline(createReadStream(source.artifactPath, { signal }), new Transform({
|
|
247
|
+
transform(chunk, _encoding, callback) {
|
|
248
|
+
hash.update(chunk);
|
|
249
|
+
callback(null, chunk);
|
|
250
|
+
},
|
|
251
|
+
}), createWriteStream(snapshotPath, { flags: "wx" }), { signal });
|
|
252
|
+
throwIfAborted(signal);
|
|
253
|
+
const observedDigest = `sha256:${hash.digest("hex")}`;
|
|
254
|
+
if (source.target.digest !== observedDigest) {
|
|
255
|
+
throw backgroundRenderError("BACKGROUND_RENDER_SOURCE_CHANGED", `source digest changed for ${source.artifactPath}`);
|
|
256
|
+
}
|
|
257
|
+
return snapshotPath;
|
|
258
|
+
}
|
|
259
|
+
catch (error) {
|
|
260
|
+
await removeIfPresent(snapshotPath);
|
|
261
|
+
if (signal.aborted)
|
|
262
|
+
throw signal.reason;
|
|
263
|
+
if (isNodeError(error) && typeof error.code === "string" && error.code.startsWith("BACKGROUND_RENDER_")) {
|
|
264
|
+
throw error;
|
|
265
|
+
}
|
|
266
|
+
throw backgroundRenderError("BACKGROUND_RENDER_SOURCE_UNAVAILABLE", `could not read source artifact ${source.artifactPath} (${String(error)})`);
|
|
267
|
+
}
|
|
268
|
+
}
|
|
269
|
+
function validateProbe(probe) {
|
|
270
|
+
if (!Number.isFinite(probe.durationSeconds) || probe.durationSeconds <= 0) {
|
|
271
|
+
throw backgroundRenderError("BACKGROUND_RENDER_VERIFICATION_FAILED", "output duration is missing or invalid");
|
|
272
|
+
}
|
|
273
|
+
if (!Number.isInteger(probe.width) || probe.width <= 0 || !Number.isInteger(probe.height) || probe.height <= 0) {
|
|
274
|
+
throw backgroundRenderError("BACKGROUND_RENDER_VERIFICATION_FAILED", "output resolution is missing or invalid");
|
|
275
|
+
}
|
|
276
|
+
if (!Number.isFinite(probe.frameRate) || probe.frameRate <= 0 || typeof probe.hasAudio !== "boolean") {
|
|
277
|
+
throw backgroundRenderError("BACKGROUND_RENDER_VERIFICATION_FAILED", "output frame rate or audio presence is missing or invalid");
|
|
278
|
+
}
|
|
279
|
+
}
|
|
280
|
+
function createStagingPath(outputPath) {
|
|
281
|
+
const extension = extname(outputPath);
|
|
282
|
+
const stem = basename(outputPath, extension);
|
|
283
|
+
return join(dirname(outputPath), `.${stem}.framekit-${randomUUID()}${extension}`);
|
|
284
|
+
}
|
|
285
|
+
function createSourceSnapshotPath(outputPath, artifactPath) {
|
|
286
|
+
const extension = extname(artifactPath) || ".fcpxml";
|
|
287
|
+
const stem = basename(artifactPath, extension);
|
|
288
|
+
return join(dirname(outputPath), `.${stem}.framekit-source-${randomUUID()}${extension}`);
|
|
289
|
+
}
|
|
290
|
+
async function assertOutputDirectory(outputPath) {
|
|
291
|
+
const parent = dirname(outputPath);
|
|
292
|
+
try {
|
|
293
|
+
const details = await stat(parent);
|
|
294
|
+
if (!details.isDirectory())
|
|
295
|
+
throw new Error("parent path is not a directory");
|
|
296
|
+
await access(parent, constants.W_OK);
|
|
297
|
+
}
|
|
298
|
+
catch (error) {
|
|
299
|
+
throw backgroundRenderError("BACKGROUND_RENDER_PATH_UNAVAILABLE", `output directory is not writable (${String(error)})`);
|
|
300
|
+
}
|
|
301
|
+
}
|
|
302
|
+
async function assertOutputCanBeReplaced(outputPath, overwrite) {
|
|
303
|
+
try {
|
|
304
|
+
const details = await stat(outputPath);
|
|
305
|
+
if (!details.isFile())
|
|
306
|
+
throw backgroundRenderError("BACKGROUND_RENDER_OUTPUT_EXISTS", `output path is not a file: ${outputPath}`);
|
|
307
|
+
if (!overwrite)
|
|
308
|
+
throw backgroundRenderError("BACKGROUND_RENDER_OUTPUT_EXISTS", `refusing to replace existing output ${outputPath}`);
|
|
309
|
+
}
|
|
310
|
+
catch (error) {
|
|
311
|
+
if (isNodeError(error) && error.code === "ENOENT")
|
|
312
|
+
return;
|
|
313
|
+
throw error;
|
|
314
|
+
}
|
|
315
|
+
}
|
|
316
|
+
async function commitOutput(stagingPath, outputPath, overwrite, signal) {
|
|
317
|
+
if (!overwrite) {
|
|
318
|
+
try {
|
|
319
|
+
throwIfAborted(signal);
|
|
320
|
+
await link(stagingPath, outputPath);
|
|
321
|
+
await unlink(stagingPath);
|
|
322
|
+
return;
|
|
323
|
+
}
|
|
324
|
+
catch (error) {
|
|
325
|
+
if (isNodeError(error) && error.code === "EEXIST") {
|
|
326
|
+
throw backgroundRenderError("BACKGROUND_RENDER_OUTPUT_EXISTS", `output appeared while rendering ${outputPath}`);
|
|
327
|
+
}
|
|
328
|
+
if (isNodeError(error) && typeof error.code === "string" && error.code.startsWith("BACKGROUND_RENDER_")) {
|
|
329
|
+
throw error;
|
|
330
|
+
}
|
|
331
|
+
throw backgroundRenderError("BACKGROUND_RENDER_COMMIT_FAILED", `could not commit ${outputPath} (${String(error)})`);
|
|
332
|
+
}
|
|
333
|
+
}
|
|
334
|
+
throwIfAborted(signal);
|
|
335
|
+
try {
|
|
336
|
+
await rename(stagingPath, outputPath);
|
|
337
|
+
}
|
|
338
|
+
catch (error) {
|
|
339
|
+
throw backgroundRenderError("BACKGROUND_RENDER_COMMIT_FAILED", `could not commit ${outputPath} (${String(error)})`);
|
|
340
|
+
}
|
|
341
|
+
}
|
|
342
|
+
function throwIfAborted(signal) {
|
|
343
|
+
if (signal.aborted) {
|
|
344
|
+
throw signal.reason ?? backgroundRenderError("BACKGROUND_RENDER_CANCELLED", "background render cancelled");
|
|
345
|
+
}
|
|
346
|
+
}
|
|
347
|
+
async function sha256File(filePath, signal) {
|
|
348
|
+
const hash = createHash("sha256");
|
|
349
|
+
for await (const chunk of createReadStream(filePath, { signal }))
|
|
350
|
+
hash.update(chunk);
|
|
351
|
+
return `sha256:${hash.digest("hex")}`;
|
|
352
|
+
}
|
|
353
|
+
function outputFormat(outputPath) {
|
|
354
|
+
return extname(outputPath).slice(1).toLowerCase() || "unknown";
|
|
355
|
+
}
|
|
356
|
+
async function removeIfPresent(filePath) {
|
|
357
|
+
try {
|
|
358
|
+
await unlink(filePath);
|
|
359
|
+
}
|
|
360
|
+
catch (error) {
|
|
361
|
+
if (!(isNodeError(error) && error.code === "ENOENT"))
|
|
362
|
+
throw error;
|
|
363
|
+
}
|
|
364
|
+
}
|
|
365
|
+
function isNodeError(error) {
|
|
366
|
+
return error instanceof Error && "code" in error;
|
|
367
|
+
}
|
|
368
|
+
function isTerminal(state) {
|
|
369
|
+
return state === "completed" || state === "cancelled" || state === "failed";
|
|
370
|
+
}
|
|
371
|
+
function backgroundRenderError(code, message) {
|
|
372
|
+
const error = new Error(`${code}: ${message}`);
|
|
373
|
+
error.code = code;
|
|
374
|
+
return error;
|
|
375
|
+
}
|
|
376
|
+
function normalizeBackgroundRenderError(error, cancelRequested) {
|
|
377
|
+
if (isNodeError(error) && typeof error.code === "string" && error.code.startsWith("BACKGROUND_RENDER_")) {
|
|
378
|
+
return error;
|
|
379
|
+
}
|
|
380
|
+
if (cancelRequested || error instanceof DOMException && error.name === "AbortError") {
|
|
381
|
+
return backgroundRenderError("BACKGROUND_RENDER_CANCELLED", "background render cancelled by caller");
|
|
382
|
+
}
|
|
383
|
+
return backgroundRenderError("BACKGROUND_RENDER_FAILED", String(error));
|
|
384
|
+
}
|