@morshoto/framekit 0.1.18 → 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 (51) hide show
  1. package/README.md +17 -12
  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 +538 -77
  5. package/dist-package/adapters/final-cut/typescript/src/connection.js +6 -1
  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 +22 -8
  9. package/dist-package/adapters/final-cut/typescript/src/index.js +1 -7
  10. package/dist-package/adapters/final-cut/typescript/src/live.js +27 -2
  11. package/dist-package/adapters/final-cut/typescript/src/native-recovery-inspection.js +175 -0
  12. package/dist-package/adapters/final-cut/typescript/src/native-session.js +11 -6
  13. package/dist-package/adapters/final-cut/typescript/src/native.js +201 -82
  14. package/dist-package/adapters/final-cut/typescript/src/publish-readback.js +1 -0
  15. package/dist-package/adapters/final-cut/typescript/src/publisher.js +255 -14
  16. package/dist-package/adapters/final-cut/typescript/src/session.js +43 -13
  17. package/dist-package/adapters/final-cut/typescript/src/timeline-ir-fcpxml.js +3 -1
  18. package/dist-package/adapters/headless/typescript/src/audio-output.js +3 -0
  19. package/dist-package/adapters/headless/typescript/src/ffmpeg-renderer.js +32 -14
  20. package/dist-package/adapters/headless/typescript/src/ffmpeg-verifier.js +9 -4
  21. package/dist-package/apps/cli/src/dev-doctor.js +198 -0
  22. package/dist-package/apps/cli/src/headless-projects.js +5 -0
  23. package/dist-package/apps/cli/src/main.js +42 -0
  24. package/dist-package/apps/mcp-server/runtime/speech-analyzer-wrapper.mjs +54 -0
  25. package/dist-package/apps/mcp-server/runtime/whisper-speech-backend.py +181 -0
  26. package/dist-package/apps/mcp-server/src/build-identity.json +2 -2
  27. package/dist-package/apps/mcp-server/src/canonical-native-snapshot.js +18 -0
  28. package/dist-package/apps/mcp-server/src/final-cut-runtime-config.js +3 -0
  29. package/dist-package/apps/mcp-server/src/main.js +24 -19
  30. package/dist-package/apps/mcp-server/src/materialization-jobs.js +143 -10
  31. package/dist-package/apps/mcp-server/src/routing.js +2 -0
  32. package/dist-package/apps/mcp-server/src/server.js +737 -152
  33. package/dist-package/apps/mcp-server/src/tools/skills/catalog.js +142 -0
  34. package/dist-package/apps/mcp-server/src/tools/skills/metadata.js +71 -0
  35. package/dist-package/apps/mcp-server/src/tools/skills/register.js +101 -0
  36. package/dist-package/{apps/mcp-server → packages/headless-application}/src/headless-projects.js +391 -58
  37. package/dist-package/packages/headless-application/src/index.js +1 -0
  38. package/dist-package/packages/runtime/src/application/project-service.js +5 -1
  39. package/dist-package/packages/runtime/src/application/project-store.js +13 -36
  40. package/dist-package/packages/runtime/src/application/transaction-store.js +1 -1
  41. package/dist-package/packages/runtime/src/capabilities.js +1 -1
  42. package/dist-package/packages/runtime/src/context/context-engine.js +22 -16
  43. package/dist-package/packages/runtime/src/context/context-service.js +2 -2
  44. package/dist-package/packages/runtime/src/editing/edit-service.js +76 -10
  45. package/dist-package/packages/runtime/src/index.js +1 -0
  46. package/dist-package/packages/runtime/src/runtime.js +16 -7
  47. package/dist-package/packages/runtime/src/timeline/editing-session.js +16 -0
  48. package/dist-package/packages/testkit/src/in-memory-editor.js +3 -3
  49. package/dist-package/packages/testkit/src/index.js +1 -0
  50. package/dist-package/packages/testkit/src/sender-lifecycle-fixture.js +192 -0
  51. package/package.json +32 -10
@@ -1,10 +1,11 @@
1
1
  import { createHash } from "node:crypto";
2
2
  import { execFile } from "node:child_process";
3
3
  import { createReadStream } from "node:fs";
4
- import { access, link, lstat, mkdtemp, rename, rm, unlink } from "node:fs/promises";
4
+ import { access, link, lstat, mkdtemp, rename, rm, unlink, writeFile } from "node:fs/promises";
5
5
  import { existsSync } from "node:fs";
6
6
  import { dirname, join, resolve } from "node:path";
7
7
  import { promisify } from "node:util";
8
+ import { HEADLESS_AUDIO_CHANNELS, HEADLESS_AUDIO_CODEC, HEADLESS_AUDIO_SAMPLE_RATE } from "./audio-output.js";
8
9
  import { createFramekitRenderResult, } from "../../../../packages/runtime/src/index.js";
9
10
  const execFileAsync = promisify(execFile);
10
11
  export class FfmpegRenderError extends Error {
@@ -64,10 +65,11 @@ export class FfmpegTimelineRenderer {
64
65
  const stagingDirectory = await mkdtemp(join(outputDirectory, ".framekit-render-"));
65
66
  const stagingPath = join(stagingDirectory, `render.${plan.parameters.format}`);
66
67
  try {
67
- const args = buildFfmpegArguments(model, stagingPath, this.fontFile);
68
+ const titleTextFiles = await writeTitleTextFiles(model.timeline.sequence.titles ?? [], stagingDirectory);
69
+ const args = buildFfmpegArguments(model, stagingPath, this.fontFile, titleTextFiles);
68
70
  try {
69
71
  await execFileAsync(this.ffmpegPath, args, {
70
- cwd: process.cwd(),
72
+ cwd: stagingDirectory,
71
73
  env: this.environment,
72
74
  maxBuffer: 8 * 1024 * 1024,
73
75
  });
@@ -292,7 +294,7 @@ async function assertSourcesUnchanged(model) {
292
294
  }
293
295
  }
294
296
  }
295
- function buildFfmpegArguments(model, stagingPath, fontFile) {
297
+ function buildFfmpegArguments(model, stagingPath, fontFile, titleTextFiles) {
296
298
  const filters = [];
297
299
  const inputArguments = [];
298
300
  const videoLabels = [];
@@ -319,7 +321,7 @@ function buildFfmpegArguments(model, stagingPath, fontFile) {
319
321
  if (hasAudio) {
320
322
  const audioLabel = `clipa${index}`;
321
323
  const gain = occurrence.gainDb ?? 0;
322
- filters.push(`${`[${index}:a]`}atrim=start=${formatNumber(sourceStart)}:duration=${formatNumber(duration)},asetpts=PTS-STARTPTS,aresample=48000,volume=${formatNumber(Math.pow(10, gain / 20))}[${audioLabel}]`);
324
+ filters.push(`${`[${index}:a]`}atrim=start=${formatNumber(sourceStart)}:duration=${formatNumber(duration)},asetpts=PTS-STARTPTS,aresample=${HEADLESS_AUDIO_SAMPLE_RATE},volume=${formatNumber(Math.pow(10, gain / 20))}[${audioLabel}]`);
323
325
  audioLabels.push(`[${audioLabel}]`);
324
326
  }
325
327
  }
@@ -329,15 +331,15 @@ function buildFfmpegArguments(model, stagingPath, fontFile) {
329
331
  const start = rationalSeconds(occurrence.startTime, `${occurrence.id}.startTime`);
330
332
  const duration = rationalSeconds(occurrence.durationTime, `${occurrence.id}.durationTime`);
331
333
  const gain = occurrence.gainDb ?? 0;
332
- const delaySamples = Math.round(start * 48_000);
334
+ const delaySamples = Math.round(start * HEADLESS_AUDIO_SAMPLE_RATE);
333
335
  const audioLabel = `bed-audio${index}`;
334
- filters.push(`[${index}:a]atrim=start=${formatNumber(sourceStart)}:duration=${formatNumber(duration)},asetpts=PTS-STARTPTS,aresample=48000,aformat=channel_layouts=mono,volume=${formatNumber(Math.pow(10, gain / 20))},adelay=${delaySamples}S:all=1,apad,atrim=duration=${formatNumber(model.duration)},asetpts=PTS-STARTPTS[${audioLabel}]`);
336
+ filters.push(`[${index}:a]atrim=start=${formatNumber(sourceStart)}:duration=${formatNumber(duration)},asetpts=PTS-STARTPTS,aresample=${HEADLESS_AUDIO_SAMPLE_RATE},aformat=channel_layouts=mono,volume=${formatNumber(Math.pow(10, gain / 20))},adelay=${delaySamples}S:all=1,apad=whole_dur=${formatNumber(model.duration)},asetpts=PTS-STARTPTS[${audioLabel}]`);
335
337
  musicLabels.push(`[${audioLabel}]`);
336
338
  }
337
339
  const transition = model.timeline.sequence.transitions?.[0];
338
340
  const videoBase = addVideoComposition(filters, videoLabels, model, transition);
339
341
  const videoWithTail = addBlackVideoTail(filters, videoBase, model.tailDuration);
340
- const videoOutput = addTitleOverlays(filters, videoWithTail, model, fontFile);
342
+ const videoOutput = addTitleOverlays(filters, videoWithTail, model, fontFile, titleTextFiles);
341
343
  let audioOutput;
342
344
  if (audioLabels.length > 0)
343
345
  audioOutput = addAudioComposition(filters, audioLabels, model, transition);
@@ -348,7 +350,7 @@ function buildFfmpegArguments(model, stagingPath, fontFile) {
348
350
  const args = ["-hide_banner", "-loglevel", "error", "-nostdin", "-y", ...inputArguments, "-filter_complex", filters.join(";")];
349
351
  args.push("-map", `[${videoOutput}]`, "-c:v", "libx264", "-preset", "ultrafast", "-threads", "1", "-pix_fmt", "yuv420p", "-r", fps);
350
352
  if (audioOutput) {
351
- args.push("-map", `[${audioOutput}]`, "-c:a", "aac", "-b:a", "128k", "-ar", "48000", "-ac", "1");
353
+ args.push("-map", `[${audioOutput}]`, "-c:a", HEADLESS_AUDIO_CODEC, "-b:a", "128k", "-ar", String(HEADLESS_AUDIO_SAMPLE_RATE), "-ac", String(HEADLESS_AUDIO_CHANNELS));
352
354
  }
353
355
  args.push("-map_metadata", "-1", "-t", formatNumber(model.duration), "-movflags", "+faststart", stagingPath);
354
356
  return args;
@@ -405,9 +407,22 @@ function addAudioComposition(filters, labels, model, transition) {
405
407
  filters.push(`${labels.join("")}concat=n=${labels.length}:v=0:a=1[${output}]`);
406
408
  return output;
407
409
  }
408
- function addTitleOverlays(filters, input, model, fontFile) {
409
- let current = input;
410
- for (const [index, title] of (model.timeline.sequence.titles ?? []).entries()) {
410
+ async function writeTitleTextFiles(titles, stagingDirectory) {
411
+ const files = [];
412
+ for (const [index, title] of titles.entries()) {
413
+ const filename = `title-${index}.txt`;
414
+ await writeFile(join(stagingDirectory, filename), title.text, "utf8");
415
+ files.push(filename);
416
+ }
417
+ return files;
418
+ }
419
+ function addTitleOverlays(filters, input, model, fontFile, titleTextFiles) {
420
+ const titles = model.timeline.sequence.titles ?? [];
421
+ if (titles.length === 0)
422
+ return input;
423
+ filters.push(`[${input}]format=yuv420p[video-titles-base]`);
424
+ let current = "video-titles-base";
425
+ for (const [index, title] of titles.entries()) {
411
426
  const start = rationalSeconds(title.startTime, `${title.id}.startTime`);
412
427
  const end = start + rationalSeconds(title.durationTime, `${title.id}.durationTime`);
413
428
  const style = title.style;
@@ -421,7 +436,10 @@ function addTitleOverlays(filters, input, model, fontFile) {
421
436
  : "(h-text_h)/2";
422
437
  const output = `title-${index}`;
423
438
  const font = fontFile ? `fontfile='${escapeFilterValue(fontFile)}':` : "";
424
- filters.push(`[${current}]drawtext=${font}text='${escapeFilterValue(title.text)}':fontcolor=${color}:fontsize=${size}:x=${x}:y=${y}:enable='between(t,${formatNumber(start)},${formatNumber(end)})'[${output}]`);
439
+ const textFile = titleTextFiles[index];
440
+ if (!textFile)
441
+ throw new FfmpegRenderError("HEADLESS_RENDER_FAILED", `title text file is missing: ${index}`);
442
+ filters.push(`[${current}]drawtext=${font}textfile='${textFile}':expansion=none:fontcolor=${color}:fontsize=${size}:x=${x}:y=${y}:enable='between(t,${formatNumber(start)},${formatNumber(end)})'[${output}]`);
425
443
  current = output;
426
444
  }
427
445
  return current;
@@ -548,7 +566,7 @@ function formatNumber(value) {
548
566
  return Number(value.toFixed(6)).toString();
549
567
  }
550
568
  function escapeFilterValue(value) {
551
- return value.replaceAll("\\", "\\\\").replaceAll("'", "\\'").replaceAll(":", "\\:").replaceAll(",", "\\,").replaceAll("[", "\\[").replaceAll("]", "\\]").replaceAll("\n", "\\n");
569
+ return value.replaceAll("\\", "\\\\").replaceAll("'", "'\\''").replaceAll(":", "\\:").replaceAll(",", "\\,").replaceAll("[", "\\[").replaceAll("]", "\\]").replaceAll("\n", "\\n");
552
570
  }
553
571
  function resolveFontFile(preferred) {
554
572
  const candidates = [
@@ -4,6 +4,7 @@ import { createReadStream } from "node:fs";
4
4
  import { lstat, stat } from "node:fs/promises";
5
5
  import { resolve } from "node:path";
6
6
  import { promisify } from "node:util";
7
+ import { HEADLESS_AUDIO_CHANNELS, HEADLESS_AUDIO_CODEC, HEADLESS_AUDIO_SAMPLE_RATE } from "./audio-output.js";
7
8
  const execFileAsync = promisify(execFile);
8
9
  /** Independently verifies the committed output; it does not trust provider metadata. */
9
10
  export class FfmpegRenderVerifier {
@@ -78,8 +79,9 @@ export class FfmpegRenderVerifier {
78
79
  checks.push({ name: "frame-rate", passed: frameRatePassed, detail: "output rational frame rate matches the explicit request", expected: expectedFrameRate, observed: observedFrameRate });
79
80
  const audioPassed = expectedAudio === undefined || (audio !== undefined
80
81
  && (expectedAudio.sampleRate === undefined || Number(audio.sample_rate) === expectedAudio.sampleRate)
81
- && (expectedAudio.channels === undefined || audio.channels === expectedAudio.channels));
82
- checks.push({ name: "audio-stream", passed: audioPassed, detail: "timeline audio is present in the renderer's normalized format", expected: expectedAudio ?? { kind: "none" }, observed: audio ?? { kind: "none" } });
82
+ && (expectedAudio.channels === undefined || audio.channels === expectedAudio.channels)
83
+ && (expectedAudio.codec === undefined || audio.codec_name === expectedAudio.codec));
84
+ checks.push({ name: "audio-stream", passed: audioPassed, detail: "audio stream matches the expected output contract", expected: expectedAudio ?? { kind: "none" }, observed: audio ?? { kind: "none" } });
83
85
  checks.push({ name: "duration", passed: durationPassed, detail: `output duration is within ${tolerance} seconds of the canonical sequence`, expected: expectedDuration, observed: probe.format.duration });
84
86
  const artifact = {
85
87
  path: result.output.path,
@@ -118,8 +120,11 @@ function expectedAudioStream(plan) {
118
120
  for (const occurrence of plan.timeline.sequence.occurrences) {
119
121
  const resource = occurrence.mediaId ? resources.get(occurrence.mediaId) : undefined;
120
122
  const stream = resource?.metadata?.streams.find((candidate) => candidate.kind === "audio");
121
- if (stream)
122
- return { sampleRate: 48_000, channels: 1 };
123
+ if (stream) {
124
+ return plan.renderer.id === "ffmpeg-headless"
125
+ ? { sampleRate: HEADLESS_AUDIO_SAMPLE_RATE, channels: HEADLESS_AUDIO_CHANNELS, codec: HEADLESS_AUDIO_CODEC }
126
+ : { sampleRate: stream.sampleRate, channels: stream.channels };
127
+ }
123
128
  }
124
129
  return undefined;
125
130
  }
@@ -0,0 +1,198 @@
1
+ import { execFile as execFileCallback } from "node:child_process";
2
+ import { constants } from "node:fs";
3
+ import { access, readFile, stat } from "node:fs/promises";
4
+ import { homedir } from "node:os";
5
+ import { dirname, join, resolve } from "node:path";
6
+ import { promisify } from "node:util";
7
+ const execFile = promisify(execFileCallback);
8
+ const tools = [
9
+ { name: "FFmpeg", command: "ffmpeg", args: ["-version"], install: "ffmpeg" },
10
+ { name: "ffprobe", command: "ffprobe", args: ["-version"], install: "ffmpeg" },
11
+ { name: "SQLite", command: "sqlite3", args: ["--version"], install: "sqlite" },
12
+ ];
13
+ export async function collectDevDoctorReport(options) {
14
+ const environment = options.environment ?? process.env;
15
+ const homeDirectory = options.homeDirectory ?? environment.HOME ?? homedir();
16
+ const runCommand = options.runCommand ?? defaultRunCommand;
17
+ const isPathWritable = options.isPathWritable ?? defaultIsPathWritable;
18
+ const platform = options.platform ?? process.platform;
19
+ const pins = await readToolchainPins(options.rootDirectory);
20
+ const checks = [];
21
+ if (!pins.node) {
22
+ checks.push({
23
+ name: "Node.js",
24
+ requirement: "required",
25
+ status: "fail",
26
+ message: "The repository .node-version pin is missing or invalid.",
27
+ });
28
+ }
29
+ else {
30
+ const currentNode = options.nodeVersion ?? process.version;
31
+ const supported = versionAtLeast(currentNode, pins.node);
32
+ checks.push({
33
+ name: "Node.js",
34
+ requirement: "required",
35
+ status: supported ? "pass" : "fail",
36
+ message: supported
37
+ ? `Node.js ${currentNode.replace(/^v/, "")} meets the ${pins.node} contributor minimum.`
38
+ : `Node.js ${pins.node} or newer is required; found ${currentNode}. Use nix develop ./nix or install the contributor toolchain.`,
39
+ });
40
+ }
41
+ if (!pins.pnpm) {
42
+ checks.push({
43
+ name: "pnpm",
44
+ requirement: "required",
45
+ status: "fail",
46
+ message: "package.json must pin an exact pnpm version in packageManager.",
47
+ });
48
+ }
49
+ else {
50
+ try {
51
+ const actual = (await runCommand("pnpm", ["--version"])).trim();
52
+ const matches = actual === pins.pnpm;
53
+ checks.push({
54
+ name: "pnpm",
55
+ requirement: "required",
56
+ status: matches ? "pass" : "fail",
57
+ message: matches
58
+ ? `pnpm ${actual} matches the repository pin.`
59
+ : `pnpm ${pins.pnpm} is required; found ${actual || "an unknown version"}. Run pnpm through Corepack inside nix develop ./nix.`,
60
+ });
61
+ }
62
+ catch {
63
+ checks.push({
64
+ name: "pnpm",
65
+ requirement: "required",
66
+ status: "fail",
67
+ message: `pnpm ${pins.pnpm} is required; it was not available. Run pnpm through Corepack inside nix develop ./nix.`,
68
+ });
69
+ }
70
+ }
71
+ const statePath = resolve(environment.FRAMEKIT_STATE_DIR ?? join(homeDirectory, ".framekit"));
72
+ const cachePath = resolve(environment.XDG_CACHE_HOME
73
+ ?? environment.npm_config_cache
74
+ ?? environment.NPM_CONFIG_CACHE
75
+ ?? join(homeDirectory, ".cache"));
76
+ for (const [name, path] of [["State directory", statePath], ["Cache directory", cachePath]]) {
77
+ const writable = await isPathWritable(path);
78
+ checks.push({
79
+ name,
80
+ requirement: "required",
81
+ status: writable ? "pass" : "fail",
82
+ path,
83
+ message: writable
84
+ ? `${path} is writable or can be created under a writable parent.`
85
+ : `${path} is not writable. Choose a writable path with ${name === "State directory" ? "FRAMEKIT_STATE_DIR" : "XDG_CACHE_HOME"}.`,
86
+ });
87
+ }
88
+ const requiredTools = options.profile === "fixture" ? new Set() : new Set(["ffmpeg", "ffprobe", "sqlite3"]);
89
+ for (const tool of tools) {
90
+ const requirement = requiredTools.has(tool.command) ? "required" : "optional";
91
+ try {
92
+ await runCommand(tool.command, [...tool.args]);
93
+ checks.push({
94
+ name: tool.name,
95
+ requirement,
96
+ status: "pass",
97
+ message: `${tool.command} is available.`,
98
+ });
99
+ }
100
+ catch {
101
+ checks.push({
102
+ name: tool.name,
103
+ requirement,
104
+ status: requirement === "required" ? "fail" : "unavailable",
105
+ message: requirement === "required"
106
+ ? `${tool.command} is required for the ${options.profile} profile. Install ${tool.install} with nix develop ./nix.`
107
+ : `${tool.command} is unavailable; the fixture profile does not require it.`,
108
+ });
109
+ }
110
+ }
111
+ if (options.profile === "native") {
112
+ if (platform !== "darwin") {
113
+ checks.push({
114
+ name: "Xcode",
115
+ requirement: "required",
116
+ status: "fail",
117
+ message: "The native profile requires macOS with Xcode selected; fixture and headless profiles do not.",
118
+ });
119
+ }
120
+ else {
121
+ try {
122
+ await runCommand("xcodebuild", ["-version"]);
123
+ checks.push({
124
+ name: "Xcode",
125
+ requirement: "required",
126
+ status: "pass",
127
+ message: "xcodebuild is available.",
128
+ });
129
+ }
130
+ catch {
131
+ checks.push({
132
+ name: "Xcode",
133
+ requirement: "required",
134
+ status: "fail",
135
+ message: "The native profile requires Xcode selected with xcode-select.",
136
+ });
137
+ }
138
+ }
139
+ }
140
+ return {
141
+ profile: options.profile,
142
+ ready: checks.every((check) => check.requirement !== "required" || check.status === "pass"),
143
+ checks,
144
+ };
145
+ }
146
+ async function readToolchainPins(rootDirectory) {
147
+ try {
148
+ const [node, packageJson] = await Promise.all([
149
+ readFile(join(rootDirectory, ".node-version"), "utf8"),
150
+ readFile(join(rootDirectory, "package.json"), "utf8"),
151
+ ]);
152
+ const packageManager = JSON.parse(packageJson).packageManager;
153
+ return {
154
+ node: /^\d+\.\d+\.\d+$/.test(node.trim()) ? node.trim() : "",
155
+ pnpm: typeof packageManager === "string" ? packageManager.match(/^pnpm@(\d+\.\d+\.\d+)$/)?.[1] ?? "" : "",
156
+ };
157
+ }
158
+ catch {
159
+ return { node: "", pnpm: "" };
160
+ }
161
+ }
162
+ function versionAtLeast(actualVersion, minimumVersion) {
163
+ const actual = actualVersion.replace(/^v/, "").split(".").map(Number);
164
+ const minimum = minimumVersion.split(".").map(Number);
165
+ if (actual.length < 3 || actual.some((part) => !Number.isInteger(part)) || minimum.length < 3)
166
+ return false;
167
+ for (let index = 0; index < 3; index += 1) {
168
+ if (actual[index] > minimum[index])
169
+ return true;
170
+ if (actual[index] < minimum[index])
171
+ return false;
172
+ }
173
+ return true;
174
+ }
175
+ async function defaultRunCommand(command, args) {
176
+ const result = await execFile(command, args, { timeout: 5_000, maxBuffer: 1024 * 1024 });
177
+ return result.stdout;
178
+ }
179
+ async function defaultIsPathWritable(path) {
180
+ let candidate = path;
181
+ while (true) {
182
+ try {
183
+ const information = await stat(candidate);
184
+ if (!information.isDirectory())
185
+ return false;
186
+ await access(candidate, constants.W_OK | constants.X_OK);
187
+ return true;
188
+ }
189
+ catch (error) {
190
+ if (error.code !== "ENOENT")
191
+ return false;
192
+ const parent = dirname(candidate);
193
+ if (parent === candidate)
194
+ return false;
195
+ candidate = parent;
196
+ }
197
+ }
198
+ }
@@ -0,0 +1,5 @@
1
+ import { HeadlessProjectService, } from "../../../packages/headless-application/src/index.js";
2
+ /** Creates the shared headless workflow for CLI-owned operations. */
3
+ export function createCliHeadlessProjectService(options) {
4
+ return new HeadlessProjectService(options);
5
+ }
@@ -4,6 +4,7 @@ import { fileURLToPath } from "node:url";
4
4
  import { dirname, join, resolve } from "node:path";
5
5
  import { promisify } from "node:util";
6
6
  import { FinalCutConnectionManager } from "../../../adapters/final-cut/typescript/src/index.js";
7
+ import { collectDevDoctorReport } from "./dev-doctor.js";
7
8
  const execFile = promisify(execFileCallback);
8
9
  async function main() {
9
10
  const argv = process.argv.slice(2);
@@ -15,6 +16,10 @@ async function main() {
15
16
  return;
16
17
  }
17
18
  if (command === "doctor") {
19
+ if (args[0] === "dev") {
20
+ await doctorDev(args.slice(1));
21
+ return;
22
+ }
18
23
  await doctorFinalCut(args);
19
24
  return;
20
25
  }
@@ -56,6 +61,31 @@ async function doctorFinalCut(args) {
56
61
  if (status.state !== "ready")
57
62
  process.exitCode = 1;
58
63
  }
64
+ async function doctorDev(args) {
65
+ let profile = "fixture";
66
+ let json = false;
67
+ for (let index = 0; index < args.length; index += 1) {
68
+ const argument = args[index];
69
+ if (argument === "--json") {
70
+ json = true;
71
+ continue;
72
+ }
73
+ if (argument === "--profile") {
74
+ const value = args[index + 1];
75
+ if (value !== "fixture" && value !== "headless" && value !== "native") {
76
+ throw new Error("Usage: framekit doctor dev [--profile fixture|headless|native] [--json]");
77
+ }
78
+ profile = value;
79
+ index += 1;
80
+ continue;
81
+ }
82
+ throw new Error("Usage: framekit doctor dev [--profile fixture|headless|native] [--json]");
83
+ }
84
+ const report = await collectDevDoctorReport({ profile, rootDirectory: repoRoot() });
85
+ printDevDoctorReport(report, json);
86
+ if (!report.ready)
87
+ process.exitCode = 1;
88
+ }
59
89
  export async function runMcp(args, dependencies = {}) {
60
90
  const editorIndex = args.indexOf("--editor");
61
91
  const editor = editorIndex >= 0 ? args[editorIndex + 1] : "final-cut-live";
@@ -124,12 +154,24 @@ function printStatus(status, json, output = process.stdout) {
124
154
  if (status.lastError)
125
155
  output.write(`Reason: ${status.lastError.code}: ${status.lastError.message}\n`);
126
156
  }
157
+ function printDevDoctorReport(report, json) {
158
+ if (json) {
159
+ process.stdout.write(`${JSON.stringify(report)}\n`);
160
+ return;
161
+ }
162
+ process.stdout.write(`Framekit development profile ${report.profile}: ${report.ready ? "ready" : "needs attention"}\n`);
163
+ for (const check of report.checks) {
164
+ const status = check.status === "pass" ? "OK" : check.status === "unavailable" ? "OPTIONAL" : "MISSING";
165
+ process.stdout.write(`${status} ${check.name}: ${check.message}\n`);
166
+ }
167
+ }
127
168
  function printHelp() {
128
169
  process.stdout.write([
129
170
  "Framekit local editor connection",
130
171
  "",
131
172
  " framekit connect finalcut [--development] [--json]",
132
173
  " framekit doctor finalcut [--json]",
174
+ " framekit doctor dev [--profile fixture|headless|native] [--json]",
133
175
  " framekit mcp --editor final-cut-live [--headless] [--development]",
134
176
  "",
135
177
  "Codex registration:",
@@ -0,0 +1,54 @@
1
+ #!/usr/bin/env node
2
+
3
+ import { spawn } from "node:child_process";
4
+ import { access } from "node:fs/promises";
5
+ import { constants } from "node:fs";
6
+
7
+ const backend = process.env.FRAMEKIT_SPEECH_BACKEND?.trim();
8
+ if (!backend) fail(78, "SPEECH_ANALYZER_SETUP_REQUIRED: set FRAMEKIT_SPEECH_BACKEND to one executable Whisper/VAD backend path");
9
+
10
+ try {
11
+ await access(backend, constants.X_OK);
12
+ } catch {
13
+ fail(78, `SPEECH_ANALYZER_SETUP_REQUIRED: speech backend is not executable: ${backend}`);
14
+ }
15
+
16
+ let input = "";
17
+ for await (const chunk of process.stdin) input += chunk;
18
+
19
+ let request;
20
+ try {
21
+ request = JSON.parse(input);
22
+ } catch (error) {
23
+ fail(65, `SPEECH_ANALYZER_REQUEST_INVALID: wrapper received invalid JSON: ${String(error)}`);
24
+ }
25
+
26
+ const child = spawn(backend, [], { stdio: ["pipe", "pipe", "pipe"] });
27
+ const stdout = [];
28
+ const stderr = [];
29
+ child.stdout.on("data", (chunk) => stdout.push(chunk));
30
+ child.stderr.on("data", (chunk) => stderr.push(chunk));
31
+ child.once("error", (error) => {
32
+ fail(78, `SPEECH_ANALYZER_SETUP_REQUIRED: speech backend could not start: ${String(error)}`);
33
+ });
34
+ child.stdin.end(JSON.stringify(request));
35
+
36
+ const exitCode = await new Promise((resolve) => child.once("close", (code) => resolve(code ?? 1)));
37
+ const diagnostic = stderr.length > 0 ? `: ${Buffer.concat(stderr).toString("utf8").trim()}` : "";
38
+ if (exitCode !== 0) fail(78, `SPEECH_ANALYZER_BACKEND_FAILED: backend exited with code ${exitCode}${diagnostic}`);
39
+
40
+ let result;
41
+ try {
42
+ result = JSON.parse(Buffer.concat(stdout).toString("utf8"));
43
+ } catch (error) {
44
+ fail(65, `SPEECH_ANALYZER_BACKEND_INVALID_OUTPUT: backend returned invalid JSON: ${String(error)}`);
45
+ }
46
+ if (!result || typeof result !== "object" || Array.isArray(result)) {
47
+ fail(65, "SPEECH_ANALYZER_BACKEND_INVALID_OUTPUT: backend must return one JSON object");
48
+ }
49
+ process.stdout.write(JSON.stringify(result));
50
+
51
+ function fail(code, message) {
52
+ process.stderr.write(`${message}\n`);
53
+ process.exit(code);
54
+ }
@@ -0,0 +1,181 @@
1
+ #!/usr/bin/env python3
2
+ """Run an optional local Whisper implementation against Framekit's JSON protocol.
3
+
4
+ The script intentionally has no Python package dependency of its own. Install
5
+ either mlx-whisper or openai-whisper in the environment that runs it and select
6
+ the model with FRAMEKIT_WHISPER_MODEL.
7
+ """
8
+
9
+ import importlib
10
+ import json
11
+ import math
12
+ import os
13
+ import sys
14
+ from typing import Any
15
+
16
+
17
+ def fail(code: int, message: str) -> None:
18
+ print(message, file=sys.stderr)
19
+ raise SystemExit(code)
20
+
21
+
22
+ def read_request() -> dict[str, Any]:
23
+ try:
24
+ value = json.load(sys.stdin)
25
+ except json.JSONDecodeError as error:
26
+ fail(65, f"WHISPER_REQUEST_INVALID: backend received invalid JSON: {error}")
27
+ if not isinstance(value, dict):
28
+ fail(65, "WHISPER_REQUEST_INVALID: backend request must be an object")
29
+ return value
30
+
31
+
32
+ def required_record(value: Any, name: str) -> dict[str, Any]:
33
+ if not isinstance(value, dict):
34
+ fail(65, f"WHISPER_REQUEST_INVALID: {name} must be an object")
35
+ return value
36
+
37
+
38
+ def finite_number(value: Any, name: str) -> float:
39
+ if isinstance(value, bool) or not isinstance(value, (int, float)) or not math.isfinite(value):
40
+ fail(65, f"WHISPER_OUTPUT_INVALID: {name} must be a finite number")
41
+ return float(value)
42
+
43
+
44
+ def load_backend() -> tuple[str, Any]:
45
+ requested = os.environ.get("FRAMEKIT_WHISPER_BACKEND", "auto").strip().lower()
46
+ candidates = {
47
+ "mlx-whisper": ("mlx_whisper", "MLX Whisper"),
48
+ "openai-whisper": ("whisper", "openai-whisper"),
49
+ }
50
+ if requested not in {"auto", *candidates}:
51
+ fail(78, "WHISPER_SETUP_REQUIRED: FRAMEKIT_WHISPER_BACKEND must be auto, mlx-whisper, or openai-whisper")
52
+
53
+ ordered = list(candidates) if requested == "auto" else [requested]
54
+ errors: list[str] = []
55
+ for name in ordered:
56
+ module_name, label = candidates[name]
57
+ try:
58
+ return label, importlib.import_module(module_name)
59
+ except ImportError as error:
60
+ errors.append(f"{name}: {error}")
61
+ detail = "; ".join(errors)
62
+ fail(78, f"WHISPER_SETUP_REQUIRED: install a selected local backend ({detail})")
63
+ raise AssertionError("unreachable")
64
+
65
+
66
+ def transcribe(module_label: str, module: Any, source: str) -> dict[str, Any]:
67
+ model = os.environ.get("FRAMEKIT_WHISPER_MODEL", "").strip()
68
+ if not model:
69
+ fail(78, "WHISPER_SETUP_REQUIRED: set FRAMEKIT_WHISPER_MODEL to a local model or model repository")
70
+ language = os.environ.get("FRAMEKIT_WHISPER_LANGUAGE", "").strip() or None
71
+
72
+ try:
73
+ if module_label == "MLX Whisper":
74
+ options: dict[str, Any] = {
75
+ "path_or_hf_repo": model,
76
+ "word_timestamps": True,
77
+ }
78
+ if language:
79
+ options["language"] = language
80
+ result = module.transcribe(source, **options)
81
+ else:
82
+ model_instance = module.load_model(model)
83
+ options = {"word_timestamps": True, "verbose": False, "fp16": False}
84
+ if language:
85
+ options["language"] = language
86
+ result = model_instance.transcribe(source, **options)
87
+ except Exception as error: # noqa: BLE001 - provider diagnostics must cross the process boundary
88
+ fail(78, f"WHISPER_ANALYZER_FAILED: {module_label} could not transcribe the source: {error}")
89
+ if not isinstance(result, dict):
90
+ fail(65, "WHISPER_OUTPUT_INVALID: Whisper backend must return an object")
91
+ return result
92
+
93
+
94
+ def confidence(value: Any) -> float:
95
+ if value is None:
96
+ # Whisper implementations may omit probability even when they expose
97
+ # reliable timestamps. Zero preserves that uncertainty for selectors.
98
+ return 0.0
99
+ number = finite_number(value, "word confidence")
100
+ if number < 0 or number > 1:
101
+ fail(65, "WHISPER_OUTPUT_INVALID: word confidence must be between 0 and 1")
102
+ return number
103
+
104
+
105
+ def normalized_words(result: dict[str, Any], requested: dict[str, Any] | None) -> list[dict[str, Any]]:
106
+ entries: list[dict[str, Any]] = []
107
+ segments = result.get("segments", [])
108
+ if not isinstance(segments, list):
109
+ fail(65, "WHISPER_OUTPUT_INVALID: segments must be an array")
110
+ for segment in segments:
111
+ segment_record = required_record(segment, "segment")
112
+ segment_start = finite_number(segment_record.get("start"), "segment start")
113
+ segment_end = finite_number(segment_record.get("end"), "segment end")
114
+ if segment_start < 0 or segment_end < segment_start:
115
+ fail(65, "WHISPER_OUTPUT_INVALID: segment boundaries are invalid")
116
+ words = segment_record.get("words")
117
+ text = str(segment_record.get("text", "")).strip()
118
+ if segment_start == segment_end:
119
+ if not text and (words is None or words == []):
120
+ continue
121
+ fail(65, "WHISPER_OUTPUT_INVALID: segment boundaries are invalid")
122
+ if not isinstance(words, list) or not words:
123
+ words = [{"word": text, "start": segment_start, "end": segment_end}]
124
+ for word in words:
125
+ word_record = required_record(word, "word")
126
+ text = str(word_record.get("word", word_record.get("text", ""))).strip()
127
+ if not text:
128
+ continue
129
+ start = finite_number(word_record.get("start"), "word start")
130
+ end = finite_number(word_record.get("end"), "word end")
131
+ if start < 0 or end < start:
132
+ fail(65, "WHISPER_OUTPUT_INVALID: word boundaries are invalid")
133
+ if start == end:
134
+ continue
135
+ if requested is not None:
136
+ request_start = finite_number(requested.get("start"), "request start")
137
+ request_end = finite_number(requested.get("end"), "request end")
138
+ if start < request_start or end > request_end:
139
+ continue
140
+ entries.append({
141
+ "text": text,
142
+ "start": start,
143
+ "end": end,
144
+ "confidence": confidence(word_record.get("probability", word_record.get("confidence"))),
145
+ })
146
+
147
+ entries.sort(key=lambda value: (value["start"], value["end"], value["text"]))
148
+ for previous, current in zip(entries, entries[1:]):
149
+ if current["start"] < previous["end"]:
150
+ fail(65, "WHISPER_OUTPUT_INVALID: word timestamps overlap")
151
+ return entries
152
+
153
+
154
+ def main() -> None:
155
+ request = read_request()
156
+ media = required_record(request.get("media"), "media")
157
+ source = media.get("source")
158
+ if not isinstance(source, str) or not source:
159
+ fail(65, "WHISPER_REQUEST_INVALID: media.source is required")
160
+ if not os.path.isfile(source):
161
+ fail(78, f"WHISPER_MEDIA_UNAVAILABLE: source does not exist: {source}")
162
+
163
+ requested = request.get("range")
164
+ if requested is not None:
165
+ requested = required_record(requested, "range")
166
+ start = finite_number(requested.get("start"), "request start")
167
+ end = finite_number(requested.get("end"), "request end")
168
+ if start < 0 or end <= start:
169
+ fail(65, "WHISPER_REQUEST_INVALID: range boundaries are invalid")
170
+
171
+ module_label, module = load_backend()
172
+ result = transcribe(module_label, module, source)
173
+ output = {
174
+ "words": normalized_words(result, requested),
175
+ "sourceTimebase": {"value": "1", "timescale": "1000"},
176
+ }
177
+ print(json.dumps(output, separators=(",", ":")))
178
+
179
+
180
+ if __name__ == "__main__":
181
+ main()