@morshoto/framekit 0.1.18 → 0.2.3

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 (192) hide show
  1. package/README.md +17 -12
  2. package/dist-package/adapters/final-cut/typescript/src/analyzers.d.ts +58 -0
  3. package/dist-package/adapters/final-cut/typescript/src/analyzers.js +52 -13
  4. package/dist-package/adapters/final-cut/typescript/src/assets.d.ts +24 -0
  5. package/dist-package/adapters/final-cut/typescript/src/background-export.d.ts +98 -0
  6. package/dist-package/adapters/final-cut/typescript/src/background-materialization.d.ts +47 -0
  7. package/dist-package/adapters/final-cut/typescript/src/background-materialization.js +8 -2
  8. package/dist-package/adapters/final-cut/typescript/src/canonical-recovery-guard.d.ts +32 -0
  9. package/dist-package/adapters/final-cut/typescript/src/canonical-recovery-guard.js +275 -0
  10. package/dist-package/adapters/final-cut/typescript/src/canonical-recovery.d.ts +22 -0
  11. package/dist-package/adapters/final-cut/typescript/src/canonical-verification.d.ts +11 -0
  12. package/dist-package/adapters/final-cut/typescript/src/canonical.d.ts +184 -0
  13. package/dist-package/adapters/final-cut/typescript/src/canonical.js +571 -78
  14. package/dist-package/adapters/final-cut/typescript/src/connection.d.ts +103 -0
  15. package/dist-package/adapters/final-cut/typescript/src/connection.js +6 -1
  16. package/dist-package/adapters/final-cut/typescript/src/disposable-native.d.ts +90 -0
  17. package/dist-package/adapters/final-cut/typescript/src/disposable-native.js +6 -0
  18. package/dist-package/adapters/final-cut/typescript/src/documents.d.ts +3 -0
  19. package/dist-package/adapters/final-cut/typescript/src/documents.js +3 -0
  20. package/dist-package/adapters/final-cut/typescript/src/experimental.d.ts +8 -0
  21. package/dist-package/adapters/final-cut/typescript/src/experimental.js +8 -0
  22. package/dist-package/adapters/final-cut/typescript/src/export.d.ts +125 -0
  23. package/dist-package/adapters/final-cut/typescript/src/fcpxml-console-experiment.d.ts +54 -0
  24. package/dist-package/adapters/final-cut/typescript/src/fcpxml.d.ts +75 -0
  25. package/dist-package/adapters/final-cut/typescript/src/fcpxml.js +28 -9
  26. package/dist-package/adapters/final-cut/typescript/src/index.d.ts +22 -0
  27. package/dist-package/adapters/final-cut/typescript/src/index.js +1 -7
  28. package/dist-package/adapters/final-cut/typescript/src/library-inspection.d.ts +101 -0
  29. package/dist-package/adapters/final-cut/typescript/src/live.d.ts +101 -0
  30. package/dist-package/adapters/final-cut/typescript/src/live.js +35 -2
  31. package/dist-package/adapters/final-cut/typescript/src/media.d.ts +12 -0
  32. package/dist-package/adapters/final-cut/typescript/src/native-operation.d.ts +6 -0
  33. package/dist-package/adapters/final-cut/typescript/src/native-recovery-inspection.d.ts +77 -0
  34. package/dist-package/adapters/final-cut/typescript/src/native-recovery-inspection.js +175 -0
  35. package/dist-package/adapters/final-cut/typescript/src/native-session.d.ts +130 -0
  36. package/dist-package/adapters/final-cut/typescript/src/native-session.js +11 -6
  37. package/dist-package/adapters/final-cut/typescript/src/native.d.ts +828 -0
  38. package/dist-package/adapters/final-cut/typescript/src/native.js +475 -189
  39. package/dist-package/adapters/final-cut/typescript/src/pasteboard-snapshot.d.ts +114 -0
  40. package/dist-package/adapters/final-cut/typescript/src/publish-readback.d.ts +26 -0
  41. package/dist-package/adapters/final-cut/typescript/src/publish-readback.js +19 -2
  42. package/dist-package/adapters/final-cut/typescript/src/publisher.d.ts +215 -0
  43. package/dist-package/adapters/final-cut/typescript/src/publisher.js +255 -14
  44. package/dist-package/adapters/final-cut/typescript/src/session.d.ts +43 -0
  45. package/dist-package/adapters/final-cut/typescript/src/session.js +43 -13
  46. package/dist-package/adapters/final-cut/typescript/src/shadow-mutation.d.ts +51 -0
  47. package/dist-package/adapters/final-cut/typescript/src/sqlite-experiment.d.ts +156 -0
  48. package/dist-package/adapters/final-cut/typescript/src/sqlite-inspection.d.ts +134 -0
  49. package/dist-package/adapters/final-cut/typescript/src/sqlite-materialization.d.ts +110 -0
  50. package/dist-package/adapters/final-cut/typescript/src/sqlite-wal-observation.d.ts +132 -0
  51. package/dist-package/adapters/final-cut/typescript/src/timeline-ir-fcpxml.d.ts +61 -0
  52. package/dist-package/adapters/final-cut/typescript/src/timeline-ir-fcpxml.js +31 -5
  53. package/dist-package/adapters/final-cut/typescript/src/unattended-editing.d.ts +54 -0
  54. package/dist-package/adapters/headless/typescript/src/audio-output.d.ts +3 -0
  55. package/dist-package/adapters/headless/typescript/src/audio-output.js +3 -0
  56. package/dist-package/adapters/headless/typescript/src/ffmpeg-media-probe.d.ts +11 -0
  57. package/dist-package/adapters/headless/typescript/src/ffmpeg-media-probe.js +26 -2
  58. package/dist-package/adapters/headless/typescript/src/ffmpeg-renderer.d.ts +25 -0
  59. package/dist-package/adapters/headless/typescript/src/ffmpeg-renderer.js +37 -14
  60. package/dist-package/adapters/headless/typescript/src/ffmpeg-verifier.d.ts +15 -0
  61. package/dist-package/adapters/headless/typescript/src/ffmpeg-verifier.js +9 -4
  62. package/dist-package/adapters/headless/typescript/src/index.d.ts +3 -0
  63. package/dist-package/apps/cli/src/dev-doctor.d.ts +25 -0
  64. package/dist-package/apps/cli/src/dev-doctor.js +198 -0
  65. package/dist-package/apps/cli/src/headless-projects.d.ts +3 -0
  66. package/dist-package/apps/cli/src/headless-projects.js +5 -0
  67. package/dist-package/apps/cli/src/main.d.ts +10 -0
  68. package/dist-package/apps/cli/src/main.js +42 -0
  69. package/dist-package/apps/mcp-server/runtime/ffmpeg-audio-backend.py +129 -0
  70. package/dist-package/apps/mcp-server/runtime/speech-analyzer-wrapper.mjs +54 -0
  71. package/dist-package/apps/mcp-server/runtime/whisper-speech-backend.py +271 -0
  72. package/dist-package/apps/mcp-server/src/build-alignment.d.ts +10 -0
  73. package/dist-package/apps/mcp-server/src/build-identity.d.ts +7 -0
  74. package/dist-package/apps/mcp-server/src/build-identity.json +2 -2
  75. package/dist-package/apps/mcp-server/src/canonical-native-snapshot.d.ts +8 -0
  76. package/dist-package/apps/mcp-server/src/canonical-native-snapshot.js +18 -0
  77. package/dist-package/apps/mcp-server/src/final-cut-runtime-config.d.ts +5 -0
  78. package/dist-package/apps/mcp-server/src/final-cut-runtime-config.js +3 -0
  79. package/dist-package/apps/mcp-server/src/headless-project-snapshot.d.ts +3 -0
  80. package/dist-package/apps/mcp-server/src/headless-sessions.d.ts +89 -0
  81. package/dist-package/apps/mcp-server/src/main.d.ts +1 -0
  82. package/dist-package/apps/mcp-server/src/main.js +24 -19
  83. package/dist-package/apps/mcp-server/src/materialization-jobs.d.ts +204 -0
  84. package/dist-package/apps/mcp-server/src/materialization-jobs.js +143 -10
  85. package/dist-package/apps/mcp-server/src/readback-policy.d.ts +18 -0
  86. package/dist-package/apps/mcp-server/src/routing.d.ts +90 -0
  87. package/dist-package/apps/mcp-server/src/routing.js +2 -0
  88. package/dist-package/apps/mcp-server/src/server.d.ts +75 -0
  89. package/dist-package/apps/mcp-server/src/server.js +813 -158
  90. package/dist-package/apps/mcp-server/src/tools/skills/catalog.d.ts +19 -0
  91. package/dist-package/apps/mcp-server/src/tools/skills/catalog.js +142 -0
  92. package/dist-package/apps/mcp-server/src/tools/skills/metadata.d.ts +37 -0
  93. package/dist-package/apps/mcp-server/src/tools/skills/metadata.js +71 -0
  94. package/dist-package/apps/mcp-server/src/tools/skills/register.d.ts +11 -0
  95. package/dist-package/apps/mcp-server/src/tools/skills/register.js +101 -0
  96. package/dist-package/apps/mcp-server/src/version.d.ts +4 -0
  97. package/dist-package/packages/headless-application/src/external-edit.d.ts +30 -0
  98. package/dist-package/packages/headless-application/src/external-edit.js +72 -0
  99. package/dist-package/packages/headless-application/src/headless-projects.d.ts +233 -0
  100. package/dist-package/{apps/mcp-server → packages/headless-application}/src/headless-projects.js +392 -59
  101. package/dist-package/packages/headless-application/src/index.d.ts +2 -0
  102. package/dist-package/packages/headless-application/src/index.js +2 -0
  103. package/dist-package/packages/runtime/src/application/duration-policy-service.d.ts +4 -0
  104. package/dist-package/packages/runtime/src/application/local-media.d.ts +46 -0
  105. package/dist-package/packages/runtime/src/application/media-analysis-service.d.ts +40 -0
  106. package/dist-package/packages/runtime/src/application/media-analysis-service.js +105 -15
  107. package/dist-package/packages/runtime/src/application/project-service.d.ts +35 -0
  108. package/dist-package/packages/runtime/src/application/project-service.js +5 -1
  109. package/dist-package/packages/runtime/src/application/project-store.d.ts +56 -0
  110. package/dist-package/packages/runtime/src/application/project-store.js +13 -36
  111. package/dist-package/packages/runtime/src/application/project-transactions.d.ts +51 -0
  112. package/dist-package/packages/runtime/src/application/runtime-options.d.ts +15 -0
  113. package/dist-package/packages/runtime/src/application/semantic-media-index-store.d.ts +28 -0
  114. package/dist-package/packages/runtime/src/application/transaction-store.d.ts +10 -0
  115. package/dist-package/packages/runtime/src/application/transaction-store.js +1 -1
  116. package/dist-package/packages/runtime/src/audio/analysis.d.ts +3 -0
  117. package/dist-package/packages/runtime/src/audio/analysis.js +95 -0
  118. package/dist-package/packages/runtime/src/audio/dialogue-normalization.d.ts +47 -0
  119. package/dist-package/packages/runtime/src/audio/noise-reduction.d.ts +34 -0
  120. package/dist-package/packages/runtime/src/capabilities.d.ts +45 -0
  121. package/dist-package/packages/runtime/src/capabilities.js +1 -1
  122. package/dist-package/packages/runtime/src/color-correction.d.ts +33 -0
  123. package/dist-package/packages/runtime/src/context/context-engine.d.ts +28 -0
  124. package/dist-package/packages/runtime/src/context/context-engine.js +22 -16
  125. package/dist-package/packages/runtime/src/context/context-service.d.ts +20 -0
  126. package/dist-package/packages/runtime/src/context/context-service.js +2 -2
  127. package/dist-package/packages/runtime/src/context/project-catalog.d.ts +12 -0
  128. package/dist-package/packages/runtime/src/context/revision.d.ts +2 -0
  129. package/dist-package/packages/runtime/src/domain/capabilities.d.ts +170 -0
  130. package/dist-package/packages/runtime/src/domain/context.d.ts +179 -0
  131. package/dist-package/packages/runtime/src/domain/diff.d.ts +104 -0
  132. package/dist-package/packages/runtime/src/domain/duration.d.ts +63 -0
  133. package/dist-package/packages/runtime/src/domain/editing.d.ts +227 -0
  134. package/dist-package/packages/runtime/src/domain/incremental-sync.d.ts +67 -0
  135. package/dist-package/packages/runtime/src/domain/index.d.ts +14 -0
  136. package/dist-package/packages/runtime/src/domain/media.d.ts +406 -0
  137. package/dist-package/packages/runtime/src/domain/ports.d.ts +62 -0
  138. package/dist-package/packages/runtime/src/domain/primitives.d.ts +21 -0
  139. package/dist-package/packages/runtime/src/domain/project.d.ts +119 -0
  140. package/dist-package/packages/runtime/src/domain/rough-cut.d.ts +27 -0
  141. package/dist-package/packages/runtime/src/domain/skills.d.ts +145 -0
  142. package/dist-package/packages/runtime/src/domain/timeline-target.d.ts +57 -0
  143. package/dist-package/packages/runtime/src/domain/timeline-target.js +19 -1
  144. package/dist-package/packages/runtime/src/domain/types.d.ts +5 -0
  145. package/dist-package/packages/runtime/src/domain/verification.d.ts +92 -0
  146. package/dist-package/packages/runtime/src/editing/dialogue-normalization-service.d.ts +18 -0
  147. package/dist-package/packages/runtime/src/editing/duration-policy.d.ts +3 -0
  148. package/dist-package/packages/runtime/src/editing/edit-service.d.ts +44 -0
  149. package/dist-package/packages/runtime/src/editing/edit-service.js +76 -10
  150. package/dist-package/packages/runtime/src/editing/filler-removal-service.d.ts +23 -0
  151. package/dist-package/packages/runtime/src/editing/intent.d.ts +97 -0
  152. package/dist-package/packages/runtime/src/editing/music-service.d.ts +9 -0
  153. package/dist-package/packages/runtime/src/index.d.ts +32 -0
  154. package/dist-package/packages/runtime/src/index.js +2 -0
  155. package/dist-package/packages/runtime/src/planning/rough-cut.d.ts +3 -0
  156. package/dist-package/packages/runtime/src/render/render-and-verify.d.ts +71 -0
  157. package/dist-package/packages/runtime/src/render/render-contract.d.ts +96 -0
  158. package/dist-package/packages/runtime/src/runtime.d.ts +85 -0
  159. package/dist-package/packages/runtime/src/runtime.js +16 -7
  160. package/dist-package/packages/runtime/src/skills/builtin.d.ts +2 -0
  161. package/dist-package/packages/runtime/src/skills/index.d.ts +3 -0
  162. package/dist-package/packages/runtime/src/skills/registry.d.ts +10 -0
  163. package/dist-package/packages/runtime/src/skills/requirements.d.ts +38 -0
  164. package/dist-package/packages/runtime/src/skills/runtime.d.ts +38 -0
  165. package/dist-package/packages/runtime/src/speech/analysis.d.ts +18 -0
  166. package/dist-package/packages/runtime/src/speech/analysis.js +67 -0
  167. package/dist-package/packages/runtime/src/speech/filler-detector.d.ts +49 -0
  168. package/dist-package/packages/runtime/src/speech/filler-removal.d.ts +37 -0
  169. package/dist-package/packages/runtime/src/speech/mapping.d.ts +56 -0
  170. package/dist-package/packages/runtime/src/speech/mapping.js +27 -4
  171. package/dist-package/packages/runtime/src/speech/safe-cut-resolver.d.ts +52 -0
  172. package/dist-package/packages/runtime/src/timeline/drift-reconciliation.d.ts +42 -0
  173. package/dist-package/packages/runtime/src/timeline/editing-session.d.ts +271 -0
  174. package/dist-package/packages/runtime/src/timeline/editing-session.js +48 -2
  175. package/dist-package/packages/runtime/src/timeline/fast-observation.d.ts +77 -0
  176. package/dist-package/packages/runtime/src/timeline/rational-time.d.ts +11 -0
  177. package/dist-package/packages/runtime/src/timeline/reorder-preview.d.ts +32 -0
  178. package/dist-package/packages/runtime/src/timeline/reorder-preview.js +202 -0
  179. package/dist-package/packages/runtime/src/timeline/snapshot-diff.d.ts +3 -0
  180. package/dist-package/packages/runtime/src/timeline/snapshot-diff.js +1 -0
  181. package/dist-package/packages/runtime/src/timeline/snapshot-digest.d.ts +3 -0
  182. package/dist-package/packages/runtime/src/timeline/snapshot-digest.js +1 -1
  183. package/dist-package/packages/runtime/src/verification/verification.d.ts +6 -0
  184. package/dist-package/packages/testkit/src/fixture-analyzers.d.ts +37 -0
  185. package/dist-package/packages/testkit/src/in-memory-editor.d.ts +55 -0
  186. package/dist-package/packages/testkit/src/in-memory-editor.js +3 -3
  187. package/dist-package/packages/testkit/src/index.d.ts +4 -0
  188. package/dist-package/packages/testkit/src/index.js +1 -0
  189. package/dist-package/packages/testkit/src/sender-lifecycle-fixture.d.ts +47 -0
  190. package/dist-package/packages/testkit/src/sender-lifecycle-fixture.js +192 -0
  191. package/dist-package/packages/testkit/src/skill-fixtures.d.ts +3 -0
  192. package/package.json +41 -14
@@ -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,3 @@
1
+ import { type HeadlessProjectServiceOptions, type HeadlessProjectWorkflow } from "../../../packages/headless-application/src/index.js";
2
+ /** Creates the shared headless workflow for CLI-owned operations. */
3
+ export declare function createCliHeadlessProjectService(options: HeadlessProjectServiceOptions): HeadlessProjectWorkflow;
@@ -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
+ }
@@ -0,0 +1,10 @@
1
+ import { spawn } from "node:child_process";
2
+ import { FinalCutConnectionManager } from "../../../adapters/final-cut/typescript/src/index.js";
3
+ type StatusOutput = Pick<NodeJS.WriteStream, "write">;
4
+ export interface McpStartupDependencies {
5
+ connectDevelopmentExtension?: (args: string[], output: StatusOutput) => Promise<ReturnType<FinalCutConnectionManager["getStatus"]>>;
6
+ spawnChild?: typeof spawn;
7
+ stderr?: StatusOutput;
8
+ }
9
+ export declare function runMcp(args: string[], dependencies?: McpStartupDependencies): Promise<void>;
10
+ export {};
@@ -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,129 @@
1
+ #!/usr/bin/env python3
2
+ """Measure source audio through Framekit's optional JSON command protocol."""
3
+
4
+ import json
5
+ import math
6
+ import os
7
+ from pathlib import Path
8
+ import re
9
+ import subprocess
10
+ import sys
11
+ import tempfile
12
+
13
+
14
+ def fail(code: str, message: str) -> None:
15
+ print(f"{code}: {message}", file=sys.stderr)
16
+ raise SystemExit(78)
17
+
18
+
19
+ def number(value: object) -> float:
20
+ if isinstance(value, bool) or not isinstance(value, (int, float)) or not math.isfinite(value):
21
+ fail("AUDIO_REQUEST_INVALID", "range coordinates must be finite numbers")
22
+ return float(value)
23
+
24
+
25
+ def run(args: list[str], code: str) -> subprocess.CompletedProcess:
26
+ try:
27
+ return subprocess.run(args, capture_output=True, text=True, check=True, timeout=45,
28
+ env={**os.environ, "LC_ALL": "C"})
29
+ except (OSError, subprocess.SubprocessError):
30
+ fail(code, "required local media tool failed or exceeded its deadline")
31
+ raise AssertionError("unreachable")
32
+
33
+
34
+ def sample_coordinate(seconds: float, rate: int, start: bool) -> int:
35
+ samples = seconds * rate
36
+ if not math.isfinite(samples) or samples > 2**53 - 1:
37
+ fail("AUDIO_REQUEST_INVALID", "range exceeds supported sample coordinates")
38
+ nearest = round(samples)
39
+ inward = nearest / rate >= seconds if start else nearest / rate <= seconds
40
+ if abs(samples - nearest) < 1e-7 and inward:
41
+ return nearest
42
+ return math.ceil(samples) if start else math.floor(samples)
43
+
44
+
45
+ def main() -> None:
46
+ try:
47
+ request = json.load(sys.stdin)
48
+ except (ValueError, TypeError):
49
+ fail("AUDIO_REQUEST_INVALID", "expected one JSON request")
50
+ if not isinstance(request, dict) or not isinstance(request.get("media"), dict):
51
+ fail("AUDIO_REQUEST_INVALID", "media is required")
52
+ if request.get("occurrenceId") is not None:
53
+ fail("AUDIO_SCOPE_UNAVAILABLE", "this backend measures source audio, not an occurrence or editor output")
54
+ requested = request.get("range")
55
+ if requested is not None:
56
+ if not isinstance(requested, dict):
57
+ fail("AUDIO_REQUEST_INVALID", "range must be an object")
58
+ start, end = number(requested.get("start")), number(requested.get("end"))
59
+ if start < 0 or end <= start:
60
+ fail("AUDIO_REQUEST_INVALID", "range must be nonnegative and positive in duration")
61
+ source = request["media"].get("source")
62
+ if not isinstance(source, str) or not os.path.isfile(source):
63
+ fail("AUDIO_SOURCE_UNAVAILABLE", "a readable local source file is required")
64
+ probe = run(["ffprobe", "-v", "error", "-select_streams", "a", "-show_streams", "-show_format", "-of", "json", source],
65
+ "AUDIO_SOURCE_UNAVAILABLE")
66
+ try:
67
+ metadata = json.loads(probe.stdout)
68
+ streams = metadata["streams"]
69
+ if not isinstance(streams, list) or len(streams) != 1:
70
+ raise ValueError("ambiguous audio streams")
71
+ audio = streams[0]
72
+ rate, channels = int(audio["sample_rate"]), audio["channels"]
73
+ if audio.get("codec_type") != "audio" or rate <= 0 or isinstance(channels, bool) or channels not in (1, 2):
74
+ raise ValueError("unsupported format")
75
+ offset = float(audio.get("start_time", 0))
76
+ if not math.isfinite(offset) or abs(offset) > 1e-9:
77
+ raise ValueError("source offset is not supported")
78
+ layout = audio.get("channel_layout")
79
+ if layout is not None and layout not in ("mono" if channels == 1 else "stereo", "unknown"):
80
+ raise ValueError("unsupported channel layout")
81
+ if requested is None:
82
+ start = 0.0
83
+ end = float(audio.get("duration", metadata.get("format", {}).get("duration")))
84
+ if not math.isfinite(end) or end <= 0:
85
+ raise ValueError("unknown source duration")
86
+ except (ValueError, TypeError, KeyError):
87
+ fail("AUDIO_SOURCE_UNAVAILABLE", "expected one mono/stereo audio stream with supported source timing")
88
+ first, last = sample_coordinate(start, rate, True), sample_coordinate(end, rate, False)
89
+ count = last - first
90
+ if count / rate < 0.4:
91
+ fail("AUDIO_MEASUREMENT_UNAVAILABLE", "at least 400 ms of sample-aligned signal is required")
92
+ with tempfile.TemporaryDirectory(prefix="framekit-source-meter-") as temporary:
93
+ pcm = Path(temporary) / "source.f32le"
94
+ run(["ffmpeg", "-hide_banner", "-nostdin", "-loglevel", "error", "-i", source,
95
+ "-map", "0:a:0", "-vn", "-af", f"atrim=start_sample={first}:end_sample={last},asetpts=PTS-STARTPTS",
96
+ "-ar", str(rate), "-ac", str(channels), "-c:a", "pcm_f32le", "-f", "f32le", "-y", str(pcm)],
97
+ "AUDIO_MEASUREMENT_UNAVAILABLE")
98
+ if pcm.stat().st_size != count * channels * 4:
99
+ fail("AUDIO_MEASUREMENT_UNAVAILABLE", "decoded samples do not cover the requested source interval")
100
+ measured = run(["ffmpeg", "-hide_banner", "-nostdin", "-loglevel", "info", "-f", "f32le",
101
+ "-ar", str(rate), "-ac", str(channels), "-i", str(pcm), "-af",
102
+ "silencedetect=noise=-60dB:d=0.1,ebur128=peak=true:framelog=verbose", "-f", "null", "-"],
103
+ "AUDIO_MEASUREMENT_UNAVAILABLE").stderr
104
+ summary = measured[measured.rfind("Summary:"):]
105
+ try:
106
+ integrated = float(re.search(r"Integrated loudness:\s+I:\s+(\S+)\s+LUFS", summary)[1])
107
+ peak = float(re.search(r"True peak:\s+Peak:\s+(\S+)\s+dBFS", summary)[1])
108
+ silence = sum(float(value) * 1000 for value in re.findall(r"silence_duration:\s*(\S+)", measured))
109
+ if not all(math.isfinite(value) for value in (integrated, peak, silence)) or integrated <= -70 or not 0 <= silence <= count / rate * 1000 + 1:
110
+ raise ValueError("unavailable metrics")
111
+ except (ValueError, TypeError):
112
+ fail("AUDIO_MEASUREMENT_UNAVAILABLE", "signal is silent, below the loudness gate or lacks a valid measurement summary")
113
+ result = {
114
+ "signalScope": "source", "integratedLufs": integrated, "truePeakDb": peak, "silenceMs": silence,
115
+ "sourceTimebase": {"value": "1", "timescale": str(rate)},
116
+ "signalFormat": {"sampleRate": rate, "channels": channels},
117
+ "requestedRange": {"start": start, "end": end},
118
+ "measuredRange": {"start": first / rate, "end": last / rate,
119
+ "startTime": {"value": str(first), "timescale": str(rate)},
120
+ "durationTime": {"value": str(count), "timescale": str(rate)}},
121
+ "analyzedDurationSeconds": count / rate,
122
+ }
123
+ if layout in ("mono", "stereo"):
124
+ result["signalFormat"]["channelLayout"] = layout
125
+ print(json.dumps(result, separators=(",", ":"), allow_nan=False))
126
+
127
+
128
+ if __name__ == "__main__":
129
+ main()
@@ -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
+ }