@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.
- package/README.md +17 -12
- package/dist-package/adapters/final-cut/typescript/src/background-materialization.js +8 -2
- package/dist-package/adapters/final-cut/typescript/src/canonical-recovery-guard.js +275 -0
- package/dist-package/adapters/final-cut/typescript/src/canonical.js +538 -77
- package/dist-package/adapters/final-cut/typescript/src/connection.js +6 -1
- package/dist-package/adapters/final-cut/typescript/src/disposable-native.js +6 -0
- package/dist-package/adapters/final-cut/typescript/src/experimental.js +8 -0
- package/dist-package/adapters/final-cut/typescript/src/fcpxml.js +22 -8
- package/dist-package/adapters/final-cut/typescript/src/index.js +1 -7
- package/dist-package/adapters/final-cut/typescript/src/live.js +27 -2
- package/dist-package/adapters/final-cut/typescript/src/native-recovery-inspection.js +175 -0
- package/dist-package/adapters/final-cut/typescript/src/native-session.js +11 -6
- package/dist-package/adapters/final-cut/typescript/src/native.js +201 -82
- package/dist-package/adapters/final-cut/typescript/src/publish-readback.js +1 -0
- package/dist-package/adapters/final-cut/typescript/src/publisher.js +255 -14
- package/dist-package/adapters/final-cut/typescript/src/session.js +43 -13
- package/dist-package/adapters/final-cut/typescript/src/timeline-ir-fcpxml.js +3 -1
- package/dist-package/adapters/headless/typescript/src/audio-output.js +3 -0
- package/dist-package/adapters/headless/typescript/src/ffmpeg-renderer.js +32 -14
- package/dist-package/adapters/headless/typescript/src/ffmpeg-verifier.js +9 -4
- package/dist-package/apps/cli/src/dev-doctor.js +198 -0
- package/dist-package/apps/cli/src/headless-projects.js +5 -0
- package/dist-package/apps/cli/src/main.js +42 -0
- package/dist-package/apps/mcp-server/runtime/speech-analyzer-wrapper.mjs +54 -0
- package/dist-package/apps/mcp-server/runtime/whisper-speech-backend.py +181 -0
- package/dist-package/apps/mcp-server/src/build-identity.json +2 -2
- package/dist-package/apps/mcp-server/src/canonical-native-snapshot.js +18 -0
- package/dist-package/apps/mcp-server/src/final-cut-runtime-config.js +3 -0
- package/dist-package/apps/mcp-server/src/main.js +24 -19
- package/dist-package/apps/mcp-server/src/materialization-jobs.js +143 -10
- package/dist-package/apps/mcp-server/src/routing.js +2 -0
- package/dist-package/apps/mcp-server/src/server.js +737 -152
- package/dist-package/apps/mcp-server/src/tools/skills/catalog.js +142 -0
- package/dist-package/apps/mcp-server/src/tools/skills/metadata.js +71 -0
- package/dist-package/apps/mcp-server/src/tools/skills/register.js +101 -0
- package/dist-package/{apps/mcp-server → packages/headless-application}/src/headless-projects.js +391 -58
- package/dist-package/packages/headless-application/src/index.js +1 -0
- package/dist-package/packages/runtime/src/application/project-service.js +5 -1
- package/dist-package/packages/runtime/src/application/project-store.js +13 -36
- package/dist-package/packages/runtime/src/application/transaction-store.js +1 -1
- package/dist-package/packages/runtime/src/capabilities.js +1 -1
- package/dist-package/packages/runtime/src/context/context-engine.js +22 -16
- package/dist-package/packages/runtime/src/context/context-service.js +2 -2
- package/dist-package/packages/runtime/src/editing/edit-service.js +76 -10
- package/dist-package/packages/runtime/src/index.js +1 -0
- package/dist-package/packages/runtime/src/runtime.js +16 -7
- package/dist-package/packages/runtime/src/timeline/editing-session.js +16 -0
- package/dist-package/packages/testkit/src/in-memory-editor.js +3 -3
- package/dist-package/packages/testkit/src/index.js +1 -0
- package/dist-package/packages/testkit/src/sender-lifecycle-fixture.js +192 -0
- package/package.json +32 -10
|
@@ -0,0 +1,142 @@
|
|
|
1
|
+
/** Combine the public tools/list contract with its explicitly declared family metadata. */
|
|
2
|
+
export function buildSkillToolCatalog(metadata, listedTools) {
|
|
3
|
+
const errors = validateMetadata(metadata);
|
|
4
|
+
const skillTools = listedTools.filter(({ name }) => name.startsWith("skill."));
|
|
5
|
+
const listedByName = new Map();
|
|
6
|
+
for (const tool of skillTools) {
|
|
7
|
+
if (listedByName.has(tool.name))
|
|
8
|
+
errors.push(`duplicate tools/list name ${tool.name}`);
|
|
9
|
+
else
|
|
10
|
+
listedByName.set(tool.name, tool);
|
|
11
|
+
}
|
|
12
|
+
const metadataByName = new Map();
|
|
13
|
+
for (const entry of metadata) {
|
|
14
|
+
if (!isSkillToolMetadata(entry))
|
|
15
|
+
continue;
|
|
16
|
+
metadataByName.set(entry.name, entry);
|
|
17
|
+
const listed = listedByName.get(entry.name);
|
|
18
|
+
if (!listed) {
|
|
19
|
+
errors.push(`${entry.name} missing from tools/list`);
|
|
20
|
+
continue;
|
|
21
|
+
}
|
|
22
|
+
if (listed.description !== entry.description) {
|
|
23
|
+
errors.push(`${entry.name} description drift from tools/list`);
|
|
24
|
+
}
|
|
25
|
+
compareInputContract(entry, listed, errors);
|
|
26
|
+
}
|
|
27
|
+
for (const name of listedByName.keys()) {
|
|
28
|
+
if (!metadataByName.has(name))
|
|
29
|
+
errors.push(`${name} missing typed metadata`);
|
|
30
|
+
}
|
|
31
|
+
const catalogTools = metadata.flatMap((entry) => {
|
|
32
|
+
if (!isSkillToolMetadata(entry))
|
|
33
|
+
return [];
|
|
34
|
+
const listed = listedByName.get(entry.name);
|
|
35
|
+
if (!listed || !isRecord(listed.inputSchema))
|
|
36
|
+
return [];
|
|
37
|
+
const { inputSchema: _schema, ...declaredMetadata } = entry;
|
|
38
|
+
return [{ ...declaredMetadata, inputSchema: structuredClone(listed.inputSchema) }];
|
|
39
|
+
});
|
|
40
|
+
return { catalog: { schemaVersion: 1, tools: catalogTools }, errors };
|
|
41
|
+
}
|
|
42
|
+
function validateMetadata(metadata) {
|
|
43
|
+
const errors = [];
|
|
44
|
+
const names = new Set();
|
|
45
|
+
for (const entry of metadata) {
|
|
46
|
+
if (!isRecord(entry)) {
|
|
47
|
+
errors.push("metadata entry must be an object");
|
|
48
|
+
continue;
|
|
49
|
+
}
|
|
50
|
+
const name = typeof entry.name === "string" ? entry.name : undefined;
|
|
51
|
+
if (!name) {
|
|
52
|
+
errors.push("metadata entry missing required field name");
|
|
53
|
+
}
|
|
54
|
+
else if (names.has(name)) {
|
|
55
|
+
errors.push(`duplicate metadata name ${name}`);
|
|
56
|
+
}
|
|
57
|
+
else {
|
|
58
|
+
names.add(name);
|
|
59
|
+
}
|
|
60
|
+
if (name && !name.startsWith("skill."))
|
|
61
|
+
errors.push(`${name} must use the skill. tool family prefix`);
|
|
62
|
+
if (name && (typeof entry.description !== "string" || !entry.description.trim())) {
|
|
63
|
+
errors.push(`${name} missing required metadata field description`);
|
|
64
|
+
}
|
|
65
|
+
if (name && !isZodRawShape(entry.inputSchema))
|
|
66
|
+
errors.push(`${name} missing required metadata field inputSchema`);
|
|
67
|
+
if (name && (typeof entry.outputContract !== "string" || !entry.outputContract.trim())) {
|
|
68
|
+
errors.push(`${name} missing required metadata field outputContract`);
|
|
69
|
+
}
|
|
70
|
+
if (name && !validModes(entry.capabilityModes))
|
|
71
|
+
errors.push(`${name} missing required metadata field capabilityModes`);
|
|
72
|
+
if (name && !nonEmptyStringArray(entry.capabilities))
|
|
73
|
+
errors.push(`${name} missing required metadata field capabilities`);
|
|
74
|
+
if (name && !["read", "preview", "write"].includes(String(entry.effect))) {
|
|
75
|
+
errors.push(`${name} missing required metadata field effect`);
|
|
76
|
+
}
|
|
77
|
+
if (name && !validApproval(entry.approval))
|
|
78
|
+
errors.push(`${name} missing required metadata field approval`);
|
|
79
|
+
if (name && !stringArray(entry.errorCodes))
|
|
80
|
+
errors.push(`${name} missing required metadata field errorCodes`);
|
|
81
|
+
if (name && !Array.isArray(entry.examples))
|
|
82
|
+
errors.push(`${name} missing required metadata field examples`);
|
|
83
|
+
}
|
|
84
|
+
return errors;
|
|
85
|
+
}
|
|
86
|
+
function compareInputContract(metadata, listed, errors) {
|
|
87
|
+
const actualSchema = isRecord(listed.inputSchema) ? listed.inputSchema : {};
|
|
88
|
+
const actualProperties = isRecord(actualSchema.properties) ? Object.keys(actualSchema.properties).sort() : [];
|
|
89
|
+
const expectedProperties = Object.keys(metadata.inputSchema).sort();
|
|
90
|
+
if (!sameStrings(expectedProperties, actualProperties)) {
|
|
91
|
+
errors.push(`${metadata.name} input property drift from tools/list`);
|
|
92
|
+
}
|
|
93
|
+
const expectedRequired = Object.entries(metadata.inputSchema)
|
|
94
|
+
.filter(([, schema]) => !schema.isOptional())
|
|
95
|
+
.map(([name]) => name)
|
|
96
|
+
.sort();
|
|
97
|
+
const actualRequired = Array.isArray(actualSchema.required)
|
|
98
|
+
? actualSchema.required.filter((item) => typeof item === "string").sort()
|
|
99
|
+
: [];
|
|
100
|
+
if (!sameStrings(expectedRequired, actualRequired)) {
|
|
101
|
+
errors.push(`${metadata.name} required input drift from tools/list`);
|
|
102
|
+
}
|
|
103
|
+
}
|
|
104
|
+
function isSkillToolMetadata(value) {
|
|
105
|
+
return isRecord(value)
|
|
106
|
+
&& typeof value.name === "string"
|
|
107
|
+
&& typeof value.description === "string"
|
|
108
|
+
&& isZodRawShape(value.inputSchema)
|
|
109
|
+
&& typeof value.outputContract === "string"
|
|
110
|
+
&& validModes(value.capabilityModes)
|
|
111
|
+
&& nonEmptyStringArray(value.capabilities)
|
|
112
|
+
&& ["read", "preview", "write"].includes(String(value.effect))
|
|
113
|
+
&& validApproval(value.approval)
|
|
114
|
+
&& stringArray(value.errorCodes)
|
|
115
|
+
&& Array.isArray(value.examples);
|
|
116
|
+
}
|
|
117
|
+
function isZodRawShape(value) {
|
|
118
|
+
return isRecord(value) && Object.values(value).every((schema) => (isRecord(schema) && typeof schema.isOptional === "function"));
|
|
119
|
+
}
|
|
120
|
+
function validModes(value) {
|
|
121
|
+
return Array.isArray(value)
|
|
122
|
+
&& value.length > 0
|
|
123
|
+
&& value.every((mode) => ["fixture", "headless", "editor"].includes(String(mode)));
|
|
124
|
+
}
|
|
125
|
+
function validApproval(value) {
|
|
126
|
+
if (!isRecord(value))
|
|
127
|
+
return false;
|
|
128
|
+
return value.kind === "none" && value.required === false
|
|
129
|
+
|| value.kind === "runtime-preview-token" && value.required === true;
|
|
130
|
+
}
|
|
131
|
+
function nonEmptyStringArray(value) {
|
|
132
|
+
return Array.isArray(value) && value.length > 0 && value.every((item) => typeof item === "string" && item.trim().length > 0);
|
|
133
|
+
}
|
|
134
|
+
function stringArray(value) {
|
|
135
|
+
return Array.isArray(value) && value.every((item) => typeof item === "string" && item.trim().length > 0);
|
|
136
|
+
}
|
|
137
|
+
function sameStrings(left, right) {
|
|
138
|
+
return left.length === right.length && left.every((value, index) => value === right[index]);
|
|
139
|
+
}
|
|
140
|
+
function isRecord(value) {
|
|
141
|
+
return value !== null && typeof value === "object" && !Array.isArray(value);
|
|
142
|
+
}
|
|
@@ -0,0 +1,71 @@
|
|
|
1
|
+
import { z } from "zod/v3";
|
|
2
|
+
export const skillRevisionValueSchema = z.object({
|
|
3
|
+
id: z.string(),
|
|
4
|
+
sequence: z.number().int().nonnegative(),
|
|
5
|
+
timestamp: z.string(),
|
|
6
|
+
});
|
|
7
|
+
const allSkillToolModes = ["fixture", "headless", "editor"];
|
|
8
|
+
export const SKILL_TOOL_METADATA = [
|
|
9
|
+
{
|
|
10
|
+
name: "skill.list",
|
|
11
|
+
description: "List registered versioned Framekit Skills with current capability availability.",
|
|
12
|
+
inputSchema: {},
|
|
13
|
+
outputContract: "SkillInspection[]",
|
|
14
|
+
capabilityModes: allSkillToolModes,
|
|
15
|
+
capabilities: ["skill-availability"],
|
|
16
|
+
effect: "read",
|
|
17
|
+
approval: { kind: "none", required: false },
|
|
18
|
+
errorCodes: ["SKILL_ERROR"],
|
|
19
|
+
examples: [{ input: {} }],
|
|
20
|
+
},
|
|
21
|
+
{
|
|
22
|
+
name: "skill.inspect",
|
|
23
|
+
description: "Inspect one registered Framekit Skill version and its current capability availability.",
|
|
24
|
+
inputSchema: {
|
|
25
|
+
skill: z.string().min(1),
|
|
26
|
+
version: z.string().min(1).optional(),
|
|
27
|
+
},
|
|
28
|
+
outputContract: "SkillInspection",
|
|
29
|
+
capabilityModes: allSkillToolModes,
|
|
30
|
+
capabilities: ["skill-availability"],
|
|
31
|
+
effect: "read",
|
|
32
|
+
approval: { kind: "none", required: false },
|
|
33
|
+
errorCodes: ["SKILL_NOT_FOUND", "SKILL_VERSION_NOT_FOUND", "SKILL_ERROR"],
|
|
34
|
+
examples: [{ input: { skill: "color-correction" } }],
|
|
35
|
+
},
|
|
36
|
+
{
|
|
37
|
+
name: "skill.preview",
|
|
38
|
+
description: "Validate and preview a registered Skill without mutating the editor.",
|
|
39
|
+
inputSchema: {
|
|
40
|
+
skill: z.string().min(1),
|
|
41
|
+
version: z.string().min(1).optional(),
|
|
42
|
+
arguments: z.record(z.unknown()),
|
|
43
|
+
},
|
|
44
|
+
outputContract: "SkillPreview",
|
|
45
|
+
capabilityModes: allSkillToolModes,
|
|
46
|
+
capabilities: ["runtime-skill-requirements", "revision-bound-preview"],
|
|
47
|
+
effect: "preview",
|
|
48
|
+
approval: { kind: "none", required: false },
|
|
49
|
+
errorCodes: ["SKILL_INPUT_INVALID", "SKILL_REQUIREMENTS_UNMET", "STALE_CONTEXT", "SKILL_ERROR"],
|
|
50
|
+
examples: [{
|
|
51
|
+
input: {
|
|
52
|
+
skill: "color-correction",
|
|
53
|
+
arguments: { baseRevision: { id: "revision-1", sequence: 1, timestamp: "2026-10-01T00:00:00.000Z" }, clipId: "clip-1", preset: "warm" },
|
|
54
|
+
},
|
|
55
|
+
}],
|
|
56
|
+
},
|
|
57
|
+
{
|
|
58
|
+
name: "skill.execute",
|
|
59
|
+
description: "Execute only a runtime-issued Skill preview token and return verification/rollback evidence.",
|
|
60
|
+
inputSchema: {
|
|
61
|
+
previewToken: z.string().min(1),
|
|
62
|
+
},
|
|
63
|
+
outputContract: "SkillExecution",
|
|
64
|
+
capabilityModes: allSkillToolModes,
|
|
65
|
+
capabilities: ["runtime-issued-preview-token", "revision-check", "verification", "rollback"],
|
|
66
|
+
effect: "write",
|
|
67
|
+
approval: { kind: "runtime-preview-token", required: true },
|
|
68
|
+
errorCodes: ["SKILL_PREVIEW_TOKEN_INVALID", "SKILL_PREVIEW_TOKEN_EXPIRED", "SKILL_REQUIREMENTS_UNMET", "STALE_CONTEXT", "SKILL_ERROR"],
|
|
69
|
+
examples: [{ input: { previewToken: "skill-preview-issued-by-runtime" } }],
|
|
70
|
+
},
|
|
71
|
+
];
|
|
@@ -0,0 +1,101 @@
|
|
|
1
|
+
import { z } from "zod/v3";
|
|
2
|
+
import { SKILL_TOOL_METADATA, skillRevisionValueSchema } from "./metadata.js";
|
|
3
|
+
const metadataByName = new Map(SKILL_TOOL_METADATA.map((metadata) => [metadata.name, metadata]));
|
|
4
|
+
export function registerSkillTools(server, runtime) {
|
|
5
|
+
const list = toolMetadata("skill.list");
|
|
6
|
+
server.registerTool(list.name, {
|
|
7
|
+
description: list.description,
|
|
8
|
+
inputSchema: list.inputSchema,
|
|
9
|
+
}, async () => {
|
|
10
|
+
try {
|
|
11
|
+
return jsonResult((await runtime.listSkillAvailability()).map(({ manifest, availability }) => ({
|
|
12
|
+
...manifest,
|
|
13
|
+
availability,
|
|
14
|
+
})));
|
|
15
|
+
}
|
|
16
|
+
catch (error) {
|
|
17
|
+
return skillErrorResult(error);
|
|
18
|
+
}
|
|
19
|
+
});
|
|
20
|
+
const inspect = toolMetadata("skill.inspect");
|
|
21
|
+
server.registerTool(inspect.name, {
|
|
22
|
+
description: inspect.description,
|
|
23
|
+
inputSchema: inspect.inputSchema,
|
|
24
|
+
}, async ({ skill, version }) => {
|
|
25
|
+
try {
|
|
26
|
+
const { manifest, availability } = await runtime.inspectSkillAvailability(skill, version);
|
|
27
|
+
return jsonResult({ ...manifest, availability });
|
|
28
|
+
}
|
|
29
|
+
catch (error) {
|
|
30
|
+
return skillErrorResult(error);
|
|
31
|
+
}
|
|
32
|
+
});
|
|
33
|
+
const preview = toolMetadata("skill.preview");
|
|
34
|
+
server.registerTool(preview.name, {
|
|
35
|
+
description: preview.description,
|
|
36
|
+
inputSchema: preview.inputSchema,
|
|
37
|
+
}, async ({ skill, version, arguments: skillArguments }) => {
|
|
38
|
+
try {
|
|
39
|
+
const baseRevision = skillRevisionValueSchema.parse(skillArguments.baseRevision);
|
|
40
|
+
const { baseRevision: _baseRevision, ...input } = skillArguments;
|
|
41
|
+
return skillPreviewResult(await runtime.previewSkill({
|
|
42
|
+
skillId: skill,
|
|
43
|
+
...(version ? { version } : {}),
|
|
44
|
+
baseRevision,
|
|
45
|
+
input,
|
|
46
|
+
}));
|
|
47
|
+
}
|
|
48
|
+
catch (error) {
|
|
49
|
+
return skillErrorResult(error);
|
|
50
|
+
}
|
|
51
|
+
});
|
|
52
|
+
const execute = toolMetadata("skill.execute");
|
|
53
|
+
server.registerTool(execute.name, {
|
|
54
|
+
description: execute.description,
|
|
55
|
+
inputSchema: execute.inputSchema,
|
|
56
|
+
}, async ({ previewToken }) => {
|
|
57
|
+
try {
|
|
58
|
+
return jsonResult(await runtime.executeSkill(previewToken));
|
|
59
|
+
}
|
|
60
|
+
catch (error) {
|
|
61
|
+
return skillErrorResult(error);
|
|
62
|
+
}
|
|
63
|
+
});
|
|
64
|
+
}
|
|
65
|
+
function toolMetadata(name) {
|
|
66
|
+
const metadata = metadataByName.get(name);
|
|
67
|
+
if (!metadata)
|
|
68
|
+
throw new Error(`SKILL_TOOL_METADATA_MISSING: ${name}`);
|
|
69
|
+
return metadata;
|
|
70
|
+
}
|
|
71
|
+
function jsonResult(value) {
|
|
72
|
+
return {
|
|
73
|
+
content: [{ type: "text", text: JSON.stringify(value) }],
|
|
74
|
+
};
|
|
75
|
+
}
|
|
76
|
+
function skillErrorResult(error) {
|
|
77
|
+
const value = error && typeof error === "object" ? error : {};
|
|
78
|
+
const message = error instanceof Error ? error.message : String(error);
|
|
79
|
+
const code = error instanceof z.ZodError
|
|
80
|
+
? "SKILL_INPUT_INVALID"
|
|
81
|
+
: typeof value.code === "string" ? value.code : message.split(":", 1)[0] || "SKILL_ERROR";
|
|
82
|
+
return {
|
|
83
|
+
isError: true,
|
|
84
|
+
content: [{
|
|
85
|
+
type: "text",
|
|
86
|
+
text: JSON.stringify({
|
|
87
|
+
code,
|
|
88
|
+
message,
|
|
89
|
+
...(value.availability ? { availability: value.availability } : {}),
|
|
90
|
+
}),
|
|
91
|
+
}],
|
|
92
|
+
};
|
|
93
|
+
}
|
|
94
|
+
export function skillPreviewResult(preview) {
|
|
95
|
+
const details = preview.plan.details ?? {};
|
|
96
|
+
return jsonResult({
|
|
97
|
+
...preview,
|
|
98
|
+
...details,
|
|
99
|
+
plan: { ...preview.plan, ...details },
|
|
100
|
+
});
|
|
101
|
+
}
|