@morshoto/framekit 0.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +67 -0
- package/bin/framekit.mjs +26 -0
- package/dist-package/adapters/final-cut/typescript/src/analyzers.js +116 -0
- package/dist-package/adapters/final-cut/typescript/src/assets.js +112 -0
- package/dist-package/adapters/final-cut/typescript/src/connection.js +379 -0
- package/dist-package/adapters/final-cut/typescript/src/disposable-native.js +282 -0
- package/dist-package/adapters/final-cut/typescript/src/export.js +382 -0
- package/dist-package/adapters/final-cut/typescript/src/fcpxml.js +503 -0
- package/dist-package/adapters/final-cut/typescript/src/index.js +11 -0
- package/dist-package/adapters/final-cut/typescript/src/live.js +415 -0
- package/dist-package/adapters/final-cut/typescript/src/native-operation.js +18 -0
- package/dist-package/adapters/final-cut/typescript/src/native.js +3134 -0
- package/dist-package/adapters/final-cut/typescript/src/publisher.js +102 -0
- package/dist-package/adapters/final-cut/typescript/src/session.js +171 -0
- package/dist-package/apps/cli/src/main.js +130 -0
- package/dist-package/apps/mcp-server/src/main.js +146 -0
- package/dist-package/apps/mcp-server/src/server.js +617 -0
- package/dist-package/packages/runtime/src/capabilities.js +24 -0
- package/dist-package/packages/runtime/src/context/context-engine.js +142 -0
- package/dist-package/packages/runtime/src/diff/diff.js +145 -0
- package/dist-package/packages/runtime/src/domain/types.js +1 -0
- package/dist-package/packages/runtime/src/editing/intent.js +83 -0
- package/dist-package/packages/runtime/src/index.js +8 -0
- package/dist-package/packages/runtime/src/runtime.js +890 -0
- package/dist-package/packages/runtime/src/snapshot-digest.js +24 -0
- package/dist-package/packages/runtime/src/speech/filler-removal.js +87 -0
- package/dist-package/packages/runtime/src/verification/verification.js +113 -0
- package/dist-package/packages/testkit/src/fixture-analyzers.js +39 -0
- package/dist-package/packages/testkit/src/in-memory-editor.js +520 -0
- package/dist-package/packages/testkit/src/index.js +2 -0
- package/package.json +64 -0
package/README.md
ADDED
|
@@ -0,0 +1,67 @@
|
|
|
1
|
+
<div align="center">
|
|
2
|
+
<img width="300" height="300" alt="image" src="https://github.com/user-attachments/assets/64248af3-2738-4f60-8155-11d63990624d" />
|
|
3
|
+
</div>
|
|
4
|
+
|
|
5
|
+
<p align="center">
|
|
6
|
+
<img src="https://img.shields.io/badge/Swift-5.9%2B-F05138?logo=swift&logoColor=white" alt="Swift 5.9 or newer" />
|
|
7
|
+
<img src="https://img.shields.io/badge/Python-3.13-3776AB?logo=python&logoColor=white" alt="Python 3.13" />
|
|
8
|
+
<img src="https://img.shields.io/badge/platform-Apple%20Silicon%20macOS-000000?logo=apple&logoColor=white" alt="Apple Silicon macOS" />
|
|
9
|
+
<a href="https://discord.gg/Dmp8FSF4vg"><img src="https://img.shields.io/badge/Discord-Join%20Chat-5865F2?logo=discord&logoColor=white" alt="Join the Framekit Discord" /></a>
|
|
10
|
+
</p>
|
|
11
|
+
|
|
12
|
+
# Framekit
|
|
13
|
+
|
|
14
|
+
Agentic video editing runtime.
|
|
15
|
+
|
|
16
|
+
## Installation
|
|
17
|
+
|
|
18
|
+
Requirements:
|
|
19
|
+
|
|
20
|
+
```sh
|
|
21
|
+
pnpm install --frozen-lockfile
|
|
22
|
+
pnpm run hooks:install
|
|
23
|
+
pnpm run test
|
|
24
|
+
pnpm run build
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
## Quick Start
|
|
28
|
+
|
|
29
|
+
The reproducible Node shell and native toolchain contract live under [`nix/`](nix/). Enter it with `nix develop ./nix`, then run `pnpm run xcode:check` before building the Final Cut Workflow Extension.
|
|
30
|
+
|
|
31
|
+
## MCP server
|
|
32
|
+
|
|
33
|
+
The local MCP server uses the deterministic in-memory Phase 2 fixture:
|
|
34
|
+
|
|
35
|
+
```sh
|
|
36
|
+
pnpm run mcp
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
The default `.env.example` starts the Diffusers visual service without the optional music stack. `Cmd-D` toggles Developer Mode and `Cmd-F` toggles the borderless exhibition presentation.
|
|
40
|
+
|
|
41
|
+
## Connect Codex to Final Cut
|
|
42
|
+
|
|
43
|
+
Install the signed Framekit Workflow Extension from the latest release, then
|
|
44
|
+
configure the Framekit marketplace once:
|
|
45
|
+
|
|
46
|
+
```sh
|
|
47
|
+
codex plugin marketplace add morshoto/framekit
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
Open `/plugins` in Codex, find **Framekit**, and select **Install**. Start a new
|
|
51
|
+
Codex session to load the Framekit MCP tools. No repository checkout or manual
|
|
52
|
+
`codex mcp add` is required.
|
|
53
|
+
|
|
54
|
+
The plugin runs the published package in headless mode. It connects only to an
|
|
55
|
+
existing Workflow Extension bridge and does not launch, activate, focus, or
|
|
56
|
+
edit Final Cut through macOS UI automation. See the
|
|
57
|
+
[first-run setup and capability boundaries](./docs/final-cut/installation.md).
|
|
58
|
+
|
|
59
|
+
## Further Docs
|
|
60
|
+
|
|
61
|
+
- [Documentation index](./docs/README.md)
|
|
62
|
+
- [Architecture](./docs/ARCHITECTURE.md)
|
|
63
|
+
- [Clean Codex and Claude Code MCP validation](./docs/tests/clean-mcp-clients.md)
|
|
64
|
+
|
|
65
|
+
## Development
|
|
66
|
+
|
|
67
|
+
Contributor setup, including the local pre-commit hook, is documented in [`CONTRIBUTOR.md`](CONTRIBUTOR.md).
|
package/bin/framekit.mjs
ADDED
|
@@ -0,0 +1,26 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
|
|
3
|
+
import { spawn } from "node:child_process";
|
|
4
|
+
import { existsSync } from "node:fs";
|
|
5
|
+
import { fileURLToPath } from "node:url";
|
|
6
|
+
|
|
7
|
+
const packagedEntrypoint = fileURLToPath(new URL("../dist-package/apps/cli/src/main.js", import.meta.url));
|
|
8
|
+
const developmentEntrypoint = fileURLToPath(new URL("../apps/cli/src/main.ts", import.meta.url));
|
|
9
|
+
const packaged = existsSync(packagedEntrypoint);
|
|
10
|
+
const child = spawn(
|
|
11
|
+
process.execPath,
|
|
12
|
+
[...(packaged ? [] : ["--import", "tsx"]), packaged ? packagedEntrypoint : developmentEntrypoint, ...process.argv.slice(2)],
|
|
13
|
+
{
|
|
14
|
+
stdio: "inherit",
|
|
15
|
+
env: process.env,
|
|
16
|
+
},
|
|
17
|
+
);
|
|
18
|
+
|
|
19
|
+
child.once("error", (error) => {
|
|
20
|
+
process.stderr.write(`framekit failed to start: ${String(error)}\n`);
|
|
21
|
+
process.exitCode = 1;
|
|
22
|
+
});
|
|
23
|
+
|
|
24
|
+
child.once("exit", (code, signal) => {
|
|
25
|
+
process.exitCode = code ?? (signal ? 1 : 0);
|
|
26
|
+
});
|
|
@@ -0,0 +1,116 @@
|
|
|
1
|
+
import { spawn } from "node:child_process";
|
|
2
|
+
import { access } from "node:fs/promises";
|
|
3
|
+
export function createCommandAnalyzers(options) {
|
|
4
|
+
return {
|
|
5
|
+
...(options.speechCommand ? { speechAnalyzer: new CommandSpeechAnalyzer({ command: options.speechCommand, timeoutMs: options.timeoutMs }) } : {}),
|
|
6
|
+
...(options.audioCommand ? { audioAnalyzer: new CommandAudioAnalyzer({ command: options.audioCommand, timeoutMs: options.timeoutMs }) } : {}),
|
|
7
|
+
...(options.visualCommand ? { visualAnalyzer: new CommandVisualAnalyzer({ command: options.visualCommand, timeoutMs: options.timeoutMs }) } : {}),
|
|
8
|
+
};
|
|
9
|
+
}
|
|
10
|
+
export class CommandSpeechAnalyzer {
|
|
11
|
+
options;
|
|
12
|
+
constructor(options) {
|
|
13
|
+
this.options = options;
|
|
14
|
+
}
|
|
15
|
+
async analyze(input, range) {
|
|
16
|
+
return runCommand(this.options, { ...input, range }, "speech");
|
|
17
|
+
}
|
|
18
|
+
}
|
|
19
|
+
export class CommandAudioAnalyzer {
|
|
20
|
+
options;
|
|
21
|
+
constructor(options) {
|
|
22
|
+
this.options = options;
|
|
23
|
+
}
|
|
24
|
+
async analyze(input, range) {
|
|
25
|
+
return runCommand(this.options, { ...input, range }, "audio");
|
|
26
|
+
}
|
|
27
|
+
}
|
|
28
|
+
export class CommandVisualAnalyzer {
|
|
29
|
+
options;
|
|
30
|
+
constructor(options) {
|
|
31
|
+
this.options = options;
|
|
32
|
+
}
|
|
33
|
+
async analyze(input, range) {
|
|
34
|
+
return runCommand(this.options, { ...input, range }, "visual");
|
|
35
|
+
}
|
|
36
|
+
}
|
|
37
|
+
async function runCommand(options, request, kind) {
|
|
38
|
+
const source = request.media.source;
|
|
39
|
+
try {
|
|
40
|
+
await access(source);
|
|
41
|
+
}
|
|
42
|
+
catch {
|
|
43
|
+
throw new Error(`ANALYZER_MEDIA_UNAVAILABLE: ${kind} source is not readable: ${source}`);
|
|
44
|
+
}
|
|
45
|
+
const timeoutMs = options.timeoutMs ?? 120_000;
|
|
46
|
+
const child = spawn(options.command, [], { stdio: ["pipe", "pipe", "pipe"] });
|
|
47
|
+
const stdout = [];
|
|
48
|
+
const stderr = [];
|
|
49
|
+
let settled = false;
|
|
50
|
+
return new Promise((resolve, reject) => {
|
|
51
|
+
const timer = setTimeout(() => {
|
|
52
|
+
if (settled)
|
|
53
|
+
return;
|
|
54
|
+
settled = true;
|
|
55
|
+
child.kill("SIGTERM");
|
|
56
|
+
reject(new Error(`ANALYZER_TIMEOUT: ${kind} analyzer exceeded ${timeoutMs}ms`));
|
|
57
|
+
}, timeoutMs);
|
|
58
|
+
child.stdout.on("data", (chunk) => stdout.push(chunk));
|
|
59
|
+
child.stderr.on("data", (chunk) => stderr.push(chunk));
|
|
60
|
+
child.once("error", (error) => {
|
|
61
|
+
if (settled)
|
|
62
|
+
return;
|
|
63
|
+
settled = true;
|
|
64
|
+
clearTimeout(timer);
|
|
65
|
+
reject(new Error(`ANALYZER_FAILED: ${kind} analyzer could not start: ${String(error)}`));
|
|
66
|
+
});
|
|
67
|
+
child.once("close", (code, signal) => {
|
|
68
|
+
if (settled)
|
|
69
|
+
return;
|
|
70
|
+
settled = true;
|
|
71
|
+
clearTimeout(timer);
|
|
72
|
+
const diagnostic = stderr.length > 0 ? `: ${Buffer.concat(stderr).toString("utf8").trim()}` : "";
|
|
73
|
+
if (code !== 0) {
|
|
74
|
+
reject(new Error(`ANALYZER_FAILED: ${kind} analyzer exited with ${signal ?? `code ${code}`}${diagnostic}`));
|
|
75
|
+
return;
|
|
76
|
+
}
|
|
77
|
+
try {
|
|
78
|
+
const value = JSON.parse(Buffer.concat(stdout).toString("utf8"));
|
|
79
|
+
validateResult(value, kind);
|
|
80
|
+
resolve(value);
|
|
81
|
+
}
|
|
82
|
+
catch (error) {
|
|
83
|
+
reject(new Error(`ANALYZER_INVALID_OUTPUT: ${kind} analyzer returned invalid JSON or schema: ${String(error)}`));
|
|
84
|
+
}
|
|
85
|
+
});
|
|
86
|
+
child.stdin.end(JSON.stringify(request));
|
|
87
|
+
});
|
|
88
|
+
}
|
|
89
|
+
function validateResult(value, kind) {
|
|
90
|
+
if (!value || typeof value !== "object")
|
|
91
|
+
throw new Error("result must be an object");
|
|
92
|
+
const record = value;
|
|
93
|
+
if (kind === "speech") {
|
|
94
|
+
if (!Array.isArray(record.words) || record.words.some((word) => !isSpeechWord(word)))
|
|
95
|
+
throw new Error("speech result requires typed words");
|
|
96
|
+
return;
|
|
97
|
+
}
|
|
98
|
+
if (kind === "audio") {
|
|
99
|
+
if (!["integratedLufs", "truePeakDb", "silenceMs"].every((key) => typeof record[key] === "number"))
|
|
100
|
+
throw new Error("audio result requires loudness fields");
|
|
101
|
+
return;
|
|
102
|
+
}
|
|
103
|
+
if (!Array.isArray(record.scenes) || !Array.isArray(record.subjects) || !Array.isArray(record.keyframes)) {
|
|
104
|
+
throw new Error("visual result requires scenes, subjects, and keyframes");
|
|
105
|
+
}
|
|
106
|
+
}
|
|
107
|
+
function isSpeechWord(value) {
|
|
108
|
+
if (!value || typeof value !== "object")
|
|
109
|
+
return false;
|
|
110
|
+
const word = value;
|
|
111
|
+
return typeof word.text === "string"
|
|
112
|
+
&& typeof word.start === "number"
|
|
113
|
+
&& typeof word.end === "number"
|
|
114
|
+
&& typeof word.confidence === "number"
|
|
115
|
+
&& (word.filler === undefined || typeof word.filler === "boolean");
|
|
116
|
+
}
|
|
@@ -0,0 +1,112 @@
|
|
|
1
|
+
import { readFile, readdir } from "node:fs/promises";
|
|
2
|
+
import { homedir } from "node:os";
|
|
3
|
+
import { basename, join, resolve } from "node:path";
|
|
4
|
+
const CATEGORY_BY_DIRECTORY = {
|
|
5
|
+
"Audio Effects.localized": "audio-effect",
|
|
6
|
+
"Effects.localized": "effect",
|
|
7
|
+
"Generators.localized": "generator",
|
|
8
|
+
"Titles.localized": "title",
|
|
9
|
+
"Transitions.localized": "transition",
|
|
10
|
+
"Templates.localized": "template",
|
|
11
|
+
};
|
|
12
|
+
const BUNDLE_SUFFIXES = new Set([".moef", ".moti", ".motn", ".motr"]);
|
|
13
|
+
export function defaultFinalCutAssetRoots() {
|
|
14
|
+
return [
|
|
15
|
+
join(homedir(), "Movies", "Motion Templates.localized"),
|
|
16
|
+
join(homedir(), "Library", "Application Support", "Final Cut Pro", "Motion Templates.localized"),
|
|
17
|
+
"/Library/Application Support/Final Cut Pro/Motion Templates.localized",
|
|
18
|
+
];
|
|
19
|
+
}
|
|
20
|
+
export class FinalCutAssetRegistry {
|
|
21
|
+
roots;
|
|
22
|
+
cached;
|
|
23
|
+
constructor(options = {}) {
|
|
24
|
+
this.roots = (options.roots ?? defaultFinalCutAssetRoots()).map((root) => resolve(root));
|
|
25
|
+
}
|
|
26
|
+
async listAssets(query) {
|
|
27
|
+
if (!this.cached)
|
|
28
|
+
this.cached = await this.scan();
|
|
29
|
+
return filterAssets(this.cached, query);
|
|
30
|
+
}
|
|
31
|
+
refresh() {
|
|
32
|
+
this.cached = undefined;
|
|
33
|
+
}
|
|
34
|
+
async scan() {
|
|
35
|
+
const assets = [];
|
|
36
|
+
for (const root of this.roots) {
|
|
37
|
+
await scanDirectory(root, assets);
|
|
38
|
+
}
|
|
39
|
+
return assets
|
|
40
|
+
.sort((left, right) => `${left.kind}:${left.name}:${left.id}`.localeCompare(`${right.kind}:${right.name}:${right.id}`))
|
|
41
|
+
.filter((asset, index, all) => index === all.findIndex((candidate) => candidate.id === asset.id));
|
|
42
|
+
}
|
|
43
|
+
}
|
|
44
|
+
async function scanDirectory(directory, assets) {
|
|
45
|
+
let entries;
|
|
46
|
+
try {
|
|
47
|
+
entries = await readdir(directory, { withFileTypes: true });
|
|
48
|
+
}
|
|
49
|
+
catch {
|
|
50
|
+
return;
|
|
51
|
+
}
|
|
52
|
+
for (const entry of entries) {
|
|
53
|
+
const path = join(directory, entry.name);
|
|
54
|
+
if (entry.isDirectory() && CATEGORY_BY_DIRECTORY[entry.name]) {
|
|
55
|
+
await scanCategory(path, CATEGORY_BY_DIRECTORY[entry.name], assets);
|
|
56
|
+
}
|
|
57
|
+
else if (entry.isDirectory()) {
|
|
58
|
+
await scanDirectory(path, assets);
|
|
59
|
+
}
|
|
60
|
+
}
|
|
61
|
+
}
|
|
62
|
+
async function scanCategory(directory, kind, assets) {
|
|
63
|
+
let entries;
|
|
64
|
+
try {
|
|
65
|
+
entries = await readdir(directory, { withFileTypes: true });
|
|
66
|
+
}
|
|
67
|
+
catch {
|
|
68
|
+
return;
|
|
69
|
+
}
|
|
70
|
+
for (const entry of entries) {
|
|
71
|
+
if (!entry.isDirectory() || !BUNDLE_SUFFIXES.has(extension(entry.name)))
|
|
72
|
+
continue;
|
|
73
|
+
const path = join(directory, entry.name);
|
|
74
|
+
const metadata = await readMetadata(path);
|
|
75
|
+
assets.push({
|
|
76
|
+
id: path,
|
|
77
|
+
kind,
|
|
78
|
+
name: metadata.name ?? basename(entry.name, extension(entry.name)),
|
|
79
|
+
vendor: metadata.vendor ?? "Unknown",
|
|
80
|
+
metadata: { path, ...metadata },
|
|
81
|
+
});
|
|
82
|
+
}
|
|
83
|
+
}
|
|
84
|
+
async function readMetadata(bundlePath) {
|
|
85
|
+
try {
|
|
86
|
+
const infoPath = join(bundlePath, "Contents", "Info.plist");
|
|
87
|
+
const contents = await readFile(infoPath, "utf8");
|
|
88
|
+
const name = contents.match(/<key>(?:CFBundleDisplayName|CFBundleName)<\/key>\s*<string>([^<]+)<\/string>/)?.[1];
|
|
89
|
+
const vendor = contents.match(/<key>(?:Vendor|CFBundleIdentifier)<\/key>\s*<string>([^<]+)<\/string>/)?.[1];
|
|
90
|
+
return { ...(name ? { name } : {}), ...(vendor ? { vendor } : {}) };
|
|
91
|
+
}
|
|
92
|
+
catch {
|
|
93
|
+
return {};
|
|
94
|
+
}
|
|
95
|
+
}
|
|
96
|
+
function filterAssets(assets, query) {
|
|
97
|
+
const text = query?.query?.trim().toLowerCase();
|
|
98
|
+
const vendor = query?.vendor?.trim().toLowerCase();
|
|
99
|
+
return assets.filter((asset) => {
|
|
100
|
+
if (text && ![asset.id, asset.name, asset.vendor].some((value) => value.toLowerCase().includes(text)))
|
|
101
|
+
return false;
|
|
102
|
+
if (query?.kind && asset.kind !== query.kind)
|
|
103
|
+
return false;
|
|
104
|
+
if (vendor && asset.vendor.toLowerCase() !== vendor)
|
|
105
|
+
return false;
|
|
106
|
+
return true;
|
|
107
|
+
}).map((asset) => structuredClone(asset));
|
|
108
|
+
}
|
|
109
|
+
function extension(name) {
|
|
110
|
+
const index = name.lastIndexOf(".");
|
|
111
|
+
return index >= 0 ? name.slice(index).toLowerCase() : "";
|
|
112
|
+
}
|