@morshoto/framekit 0.1.10 → 0.1.12

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 (31) hide show
  1. package/README.md +1 -0
  2. package/dist-package/adapters/final-cut/typescript/src/analyzers.js +68 -5
  3. package/dist-package/adapters/final-cut/typescript/src/background-materialization.js +175 -0
  4. package/dist-package/adapters/final-cut/typescript/src/canonical-recovery.js +31 -0
  5. package/dist-package/adapters/final-cut/typescript/src/canonical-verification.js +16 -0
  6. package/dist-package/adapters/final-cut/typescript/src/canonical.js +600 -56
  7. package/dist-package/adapters/final-cut/typescript/src/connection.js +52 -14
  8. package/dist-package/adapters/final-cut/typescript/src/fcpxml-console-experiment.js +74 -0
  9. package/dist-package/adapters/final-cut/typescript/src/index.js +9 -0
  10. package/dist-package/adapters/final-cut/typescript/src/live.js +11 -4
  11. package/dist-package/adapters/final-cut/typescript/src/native.js +321 -19
  12. package/dist-package/adapters/final-cut/typescript/src/session.js +19 -1
  13. package/dist-package/adapters/final-cut/typescript/src/shadow-mutation.js +174 -0
  14. package/dist-package/adapters/final-cut/typescript/src/sqlite-experiment.js +472 -0
  15. package/dist-package/adapters/final-cut/typescript/src/sqlite-inspection.js +433 -0
  16. package/dist-package/adapters/final-cut/typescript/src/sqlite-materialization.js +230 -0
  17. package/dist-package/adapters/final-cut/typescript/src/timeline-ir-fcpxml.js +372 -0
  18. package/dist-package/adapters/final-cut/typescript/src/unattended-editing.js +66 -0
  19. package/dist-package/apps/mcp-server/src/headless-sessions.js +112 -0
  20. package/dist-package/apps/mcp-server/src/main.js +36 -2
  21. package/dist-package/apps/mcp-server/src/materialization-jobs.js +326 -0
  22. package/dist-package/apps/mcp-server/src/routing.js +17 -0
  23. package/dist-package/apps/mcp-server/src/server.js +146 -12
  24. package/dist-package/packages/runtime/src/application/media-analysis-service.js +52 -6
  25. package/dist-package/packages/runtime/src/context/project-catalog.js +46 -1
  26. package/dist-package/packages/runtime/src/index.js +2 -0
  27. package/dist-package/packages/runtime/src/skills/builtin.js +99 -8
  28. package/dist-package/packages/runtime/src/skills/runtime.js +1 -0
  29. package/dist-package/packages/runtime/src/timeline/drift-reconciliation.js +295 -0
  30. package/dist-package/packages/runtime/src/timeline/editing-session.js +490 -0
  31. package/package.json +10 -6
@@ -104,13 +104,19 @@ export class FinalCutConnectionManager {
104
104
  try {
105
105
  this.update({ state: "detecting", lastError: undefined });
106
106
  const existing = await this.tryProbe();
107
- if (existing)
108
- return this.ready(existing);
107
+ this.update({ extensionInstalled: await pathExists(this.extensionInstallPath) });
108
+ if (existing.result)
109
+ return this.ready(existing.result);
109
110
  if (this.canonicalProviderRequired) {
110
111
  return this.fail("FINAL_CUT_CANONICAL_PROVIDER_UNAVAILABLE", `Canonical live provider is unavailable at ${this.socketPath}; metadata-only fallback is disabled`, "needs-user-action");
111
112
  }
112
113
  if (this.headless) {
113
- return this.fail("FINAL_CUT_HEADLESS_SOCKET_UNAVAILABLE", `Headless mode only probes the existing Workflow Extension socket at ${this.socketPath}; it does not launch or activate Final Cut Pro`, "unavailable");
114
+ this.update({ state: "waiting-for-socket" });
115
+ const waiting = await this.waitForHeadlessBridge(existing.error);
116
+ if (waiting.result)
117
+ return this.ready(waiting.result);
118
+ const failure = headlessProbeFailure(waiting.error, this.socketPath);
119
+ return this.fail(failure.code, failure.message, "unavailable");
114
120
  }
115
121
  const editorDetected = await this.detectFinalCut();
116
122
  this.update({ editorDetected });
@@ -157,8 +163,8 @@ export class FinalCutConnectionManager {
157
163
  let nextActivationAt = Date.now() + this.activationRetryIntervalMs;
158
164
  while (Date.now() < deadline) {
159
165
  const result = await this.tryProbe();
160
- if (result)
161
- return this.ready(result);
166
+ if (result.result)
167
+ return this.ready(result.result);
162
168
  if (Date.now() >= nextActivationAt) {
163
169
  try {
164
170
  await this.activateWithDeadline(deadline);
@@ -186,11 +192,24 @@ export class FinalCutConnectionManager {
186
192
  }
187
193
  async tryProbe() {
188
194
  try {
189
- return await this.probe();
195
+ return { result: await this.probe() };
190
196
  }
191
- catch {
192
- return undefined;
197
+ catch (error) {
198
+ return { error };
199
+ }
200
+ }
201
+ async waitForHeadlessBridge(initialError) {
202
+ const deadline = Date.now() + this.startupTimeoutMs;
203
+ let attempt = { error: initialError };
204
+ while (Date.now() < deadline) {
205
+ if (isIncompatibleProbeError(attempt.error))
206
+ return attempt;
207
+ await this.sleep(Math.min(this.pollIntervalMs, Math.max(1, deadline - Date.now())));
208
+ attempt = await this.tryProbe();
209
+ if (attempt.result)
210
+ return attempt;
193
211
  }
212
+ return attempt;
194
213
  }
195
214
  ready(result) {
196
215
  const capabilities = withCanonicalTimelineMode(withCapabilityFamilies(result.capabilities, {
@@ -203,7 +222,6 @@ export class FinalCutConnectionManager {
203
222
  this.update({
204
223
  state: "ready",
205
224
  editorDetected: true,
206
- extensionInstalled: true,
207
225
  identity: result.identity,
208
226
  capabilities,
209
227
  lastError: undefined,
@@ -211,7 +229,12 @@ export class FinalCutConnectionManager {
211
229
  return this.getStatus();
212
230
  }
213
231
  fail(code, message, state) {
214
- this.update({ state, lastError: { code, message } });
232
+ this.update({
233
+ state,
234
+ identity: undefined,
235
+ capabilities: undefined,
236
+ lastError: { code, message },
237
+ });
215
238
  return this.getStatus();
216
239
  }
217
240
  update(patch) {
@@ -304,10 +327,7 @@ export class FinalCutConnectionManager {
304
327
  }
305
328
  function defaultProbe(socketPath) {
306
329
  const adapter = createFinalCutLiveAdapter(socketPath);
307
- return async () => ({
308
- identity: await adapter.getIdentity(),
309
- capabilities: await adapter.getCapabilities(),
310
- });
330
+ return () => adapter.inspect();
311
331
  }
312
332
  async function defaultDetectFinalCut(appPath) {
313
333
  try {
@@ -396,3 +416,21 @@ function isActivationTimeout(error) {
396
416
  const message = String(error);
397
417
  return message.includes("-1712") || message.includes("ETIMEDOUT") || message.includes("timed out");
398
418
  }
419
+ function isIncompatibleProbeError(error) {
420
+ return String(error).includes("FINAL_CUT_LIVE_PROTOCOL")
421
+ || String(error).includes("UNSUPPORTED_METHOD")
422
+ || String(error).includes("CAPABILITY_UNAVAILABLE");
423
+ }
424
+ function headlessProbeFailure(error, socketPath) {
425
+ const detail = error instanceof Error ? error.message : String(error ?? "unknown probe failure");
426
+ if (isIncompatibleProbeError(error)) {
427
+ return {
428
+ code: "FINAL_CUT_HEADLESS_PROTOCOL_INCOMPATIBLE",
429
+ message: `The Workflow Extension endpoint at ${socketPath} is incompatible with Framekit's live protocol: ${detail}`,
430
+ };
431
+ }
432
+ return {
433
+ code: "FINAL_CUT_HEADLESS_SOCKET_UNAVAILABLE",
434
+ message: `Headless mode could not connect to the Workflow Extension socket at ${socketPath}: ${detail}. It does not launch or activate Final Cut Pro`,
435
+ };
436
+ }
@@ -0,0 +1,74 @@
1
+ /**
2
+ * Classifies evidence collected around the FCPXML programmatic/artifact path.
3
+ * This function never authorizes a write: a headed result is preflight only,
4
+ * and target-bound import readback remains unavailable until independently
5
+ * proven by a native provider.
6
+ */
7
+ export function classifyFinalCutFcpxmlExperiment(observation) {
8
+ validateArtifact(observation.artifact);
9
+ if (!observation.console.source.trim())
10
+ throw new Error("FCPXML_EXPERIMENT_INVALID: console source is required");
11
+ if (!Number.isInteger(observation.log.lineCount) || observation.log.lineCount < 0) {
12
+ throw new Error("FCPXML_EXPERIMENT_INVALID: log lineCount must be a non-negative integer");
13
+ }
14
+ const base = {
15
+ schemaVersion: 1,
16
+ observation: structuredClone(observation),
17
+ capabilities: {
18
+ artifactRead: "verified",
19
+ targetBoundReadback: "unavailable",
20
+ },
21
+ mutationAttempted: false,
22
+ nativeImportVerified: false,
23
+ safeToOverwrite: false,
24
+ };
25
+ if (observation.console.state === "locked") {
26
+ return {
27
+ ...base,
28
+ status: "blocked",
29
+ capabilities: { ...base.capabilities, headedImport: "blocked" },
30
+ blockers: [{
31
+ code: "FINAL_CUT_NATIVE_CONSOLE_LOCKED",
32
+ retryable: observation.console.retryable,
33
+ message: "The macOS console is locked; no headed FCPXML import was attempted",
34
+ }],
35
+ };
36
+ }
37
+ if (observation.console.state === "unknown") {
38
+ return {
39
+ ...base,
40
+ status: "blocked",
41
+ capabilities: { ...base.capabilities, headedImport: "blocked" },
42
+ blockers: [{
43
+ code: "FINAL_CUT_NATIVE_CONSOLE_LOCK_STATE_UNKNOWN",
44
+ retryable: observation.console.retryable,
45
+ message: "macOS did not expose one consistent supported console lock state",
46
+ }],
47
+ };
48
+ }
49
+ if (observation.process !== "running") {
50
+ return artifactOnly(base, "FINAL_CUT_NOT_RUNNING", true, "Final Cut Pro is not running; only the FCPXML artifact was inspected");
51
+ }
52
+ if (observation.frontmost !== "final-cut") {
53
+ return artifactOnly(base, "FINAL_CUT_NOT_FRONTMOST", true, "Final Cut Pro is not frontmost; only the FCPXML artifact was inspected");
54
+ }
55
+ return {
56
+ ...base,
57
+ status: "headed-preflight-ready",
58
+ capabilities: { ...base.capabilities, headedImport: "preflight-only" },
59
+ blockers: [],
60
+ };
61
+ }
62
+ function artifactOnly(base, code, retryable, message) {
63
+ return {
64
+ ...base,
65
+ status: "artifact-only",
66
+ capabilities: { ...base.capabilities, headedImport: "blocked" },
67
+ blockers: [{ code, retryable, message }],
68
+ };
69
+ }
70
+ function validateArtifact(artifact) {
71
+ if (artifact.format !== "fcpxml" || !artifact.valid || artifact.version !== "1.11" || !/^[a-f0-9]{64}$/i.test(artifact.digest)) {
72
+ throw new Error("FCPXML_ARTIFACT_INVALID: experiment requires a valid FCPXML 1.11 artifact and SHA-256 digest");
73
+ }
74
+ }
@@ -2,6 +2,8 @@ export * from "./fcpxml.js";
2
2
  export * from "./live.js";
3
3
  export * from "./connection.js";
4
4
  export * from "./canonical.js";
5
+ export * from "./canonical-recovery.js";
6
+ export * from "./canonical-verification.js";
5
7
  export * from "./session.js";
6
8
  export * from "./analyzers.js";
7
9
  export * from "./assets.js";
@@ -11,6 +13,13 @@ export * from "./disposable-native.js";
11
13
  export * from "./publisher.js";
12
14
  export * from "./export.js";
13
15
  export * from "./background-export.js";
16
+ export * from "./background-materialization.js";
14
17
  export * from "./library-inspection.js";
18
+ export * from "./sqlite-inspection.js";
19
+ export * from "./sqlite-experiment.js";
20
+ export * from "./shadow-mutation.js";
15
21
  export * from "./native-operation.js";
16
22
  export * from "./native-session.js";
23
+ export * from "./timeline-ir-fcpxml.js";
24
+ export * from "./fcpxml-console-experiment.js";
25
+ export * from "./unattended-editing.js";
@@ -71,13 +71,20 @@ export class FinalCutLiveAdapter {
71
71
  this.transport = transport;
72
72
  this.socketPath = socketPath;
73
73
  }
74
- async getIdentity() {
74
+ async inspect() {
75
75
  const response = await this.request({ method: "capabilities" });
76
- return response.identity;
76
+ return {
77
+ identity: response.identity,
78
+ capabilities: withCanonicalTimelineMode(withCapabilityFamilies(response.capabilities, {
79
+ backend: response.identity.backend,
80
+ })),
81
+ };
82
+ }
83
+ async getIdentity() {
84
+ return (await this.inspect()).identity;
77
85
  }
78
86
  async getCapabilities() {
79
- const response = await this.request({ method: "capabilities" });
80
- return withCanonicalTimelineMode(withCapabilityFamilies(response.capabilities, { backend: response.identity.backend }));
87
+ return (await this.inspect()).capabilities;
81
88
  }
82
89
  async read() {
83
90
  return this.readProject();