@morshoto/framekit 0.1.6 → 0.1.10

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 (33) 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/canonical.js +189 -32
  5. package/dist-package/adapters/final-cut/typescript/src/connection.js +3 -3
  6. package/dist-package/adapters/final-cut/typescript/src/disposable-native.js +33 -7
  7. package/dist-package/adapters/final-cut/typescript/src/fcpxml.js +615 -49
  8. package/dist-package/adapters/final-cut/typescript/src/index.js +4 -0
  9. package/dist-package/adapters/final-cut/typescript/src/library-inspection.js +390 -0
  10. package/dist-package/adapters/final-cut/typescript/src/live.js +6 -3
  11. package/dist-package/adapters/final-cut/typescript/src/media.js +151 -0
  12. package/dist-package/adapters/final-cut/typescript/src/native-session.js +412 -0
  13. package/dist-package/adapters/final-cut/typescript/src/native.js +1192 -364
  14. package/dist-package/adapters/final-cut/typescript/src/publisher.js +225 -32
  15. package/dist-package/adapters/final-cut/typescript/src/session.js +145 -17
  16. package/dist-package/apps/mcp-server/src/main.js +26 -7
  17. package/dist-package/apps/mcp-server/src/routing.js +227 -39
  18. package/dist-package/apps/mcp-server/src/server.js +532 -97
  19. package/dist-package/apps/mcp-server/src/version.js +109 -1
  20. package/dist-package/packages/runtime/src/application/media-analysis-service.js +1 -3
  21. package/dist-package/packages/runtime/src/application/project-service.js +46 -7
  22. package/dist-package/packages/runtime/src/capabilities.js +55 -7
  23. package/dist-package/packages/runtime/src/context/project-catalog.js +159 -0
  24. package/dist-package/packages/runtime/src/domain/capabilities.js +33 -0
  25. package/dist-package/packages/runtime/src/domain/context.js +14 -1
  26. package/dist-package/packages/runtime/src/domain/index.js +1 -0
  27. package/dist-package/packages/runtime/src/domain/timeline-target.js +217 -0
  28. package/dist-package/packages/runtime/src/editing/edit-service.js +15 -1
  29. package/dist-package/packages/runtime/src/editing/intent.js +178 -2
  30. package/dist-package/packages/runtime/src/index.js +1 -0
  31. package/dist-package/packages/runtime/src/runtime.js +2 -2
  32. package/dist-package/packages/testkit/src/in-memory-editor.js +5 -4
  33. package/package.json +7 -2
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 packaged = existsSync(packagedEntrypoint);
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 { readFile, readdir } from "node:fs/promises";
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
- if (!this.cached)
30
- this.cached = await this.scan();
31
- const filesystemAssets = filterAssets(this.cached, query);
32
- if (!this.nativeTitleProvider || (query?.kind && query.kind !== "title"))
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
- let nativeTitles;
35
- try {
36
- nativeTitles = await this.nativeTitleProvider.searchTitles(query?.query ?? "");
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
- catch (error) {
39
- // Filesystem assets remain usable when the optional native browser is
40
- // unavailable, but keep the native diagnostic visible in the response.
41
- if (filesystemAssets.length > 0)
42
- return withNativeTitleDiagnostic(filesystemAssets, error);
43
- throw error;
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 composed = [...filesystemAssets, ...nativeTitles.map(nativeTitleAsset)];
46
- return filterAssets(dedupeAssets(composed), query);
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 assets
57
- .sort((left, right) => `${left.kind}:${left.name}:${left.id}`.localeCompare(`${right.kind}:${right.name}:${right.id}`))
58
- .filter((asset, index, all) => index === all.findIndex((candidate) => candidate.id === asset.id));
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
- ...(kind === "title"
108
- ? {
109
- placement: {
110
- backend: "final-cut-accessibility",
111
- guarantee: "native-verified",
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 withNativeTitleDiagnostic(assets, error) {
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
+ }