feat: initial commit - Jhonny Editor

- Adicionado estrutura completa do projeto - Configurado MCP server para Premiere Pro - Adicionado documentação e skills - Configurado Gitignore para o projeto
2026-09-08 09:59:31 -04:00
commit b541f502ba
1507 changed files with 387650 additions and 0 deletions
@@ -0,0 +1,25 @@
+# Recommendation 01: exact HTTP route admission
+
+## Evidence
+
+The MCP HTTP transport is a security boundary. The current server accepts any URL
+whose text starts with `/mcp`, so `/mcp-typo` reaches the authenticated transport.
+The latest MCP transport guidance expects one configured endpoint, and the existing
+roadmap already requires rejection before server construction.
+
+- [MCP 2026-07-28 transport specification](https://modelcontextprotocol.io/specification/2026-07-28/basic/transports)
+
+## Proposed improvement
+
+Parse the request URL once and admit only the exact `/mcp` pathname. Allow only the
+methods supported by Streamable HTTP, return `404` for other paths and `405` with an
+`Allow` header for other methods, and do this before authentication telemetry or MCP
+server allocation.
+
+## Acceptance
+
+- `/mcp`, `/mcp?client=x`, and the health route retain documented behavior.
+- `/mcp-typo`, encoded separator variants, and unsupported methods never construct a server.
+- Unit tests cover malformed URLs without exposing request headers or tokens.
+
+This is transport hardening only; it does not validate a live Premiere host.
@@ -0,0 +1,24 @@
+# Recommendation 02: bound HTTP requests and sockets
+
+## Evidence
+
+Remote MCP requests can currently consume an unbounded body and inherit Node's
+generic timeout behavior. MCP tools can drive Premiere, so parsing and socket limits
+must apply before a transport or host operation is allocated.
+
+- [MCP security best practices](https://modelcontextprotocol.io/specification/2026-07-28/basic/security_best_practices)
+- [Node HTTP server timeouts](https://nodejs.org/api/http.html#class-httpserver)
+
+## Proposed improvement
+
+Add validated environment settings for maximum body bytes, headers timeout, request
+timeout, keep-alive timeout, and maximum requests per socket. Count bytes while the
+request streams and return deterministic `408` or `413` responses before MCP parsing.
+
+## Acceptance
+
+- Oversized and slow requests never invoke `createServer` or a Premiere bridge.
+- Invalid configuration fails startup instead of silently disabling a limit.
+- Boundary tests cover chunked bodies, declared lengths, disconnects, and exact limits.
+
+This is remote-transport containment, not proof of host cancellation.
@@ -0,0 +1,24 @@
+# Recommendation 03: authorization-scoped throttling
+
+## Evidence
+
+Authentication establishes who may call tools but does not bound request rate. MCP
+security guidance recommends defense in depth for exposed authorization boundaries.
+
+- [MCP authorization security](https://modelcontextprotocol.io/specification/2026-07-28/basic/authorization)
+
+## Proposed improvement
+
+Add a bounded token-bucket limiter keyed by a one-way credential fingerprint, with
+trusted-proxy-aware IP fallback only when explicitly configured. Reject before MCP
+server construction, cap key cardinality, expire idle buckets, and emit aggregate
+telemetry without tokens, IP addresses, arguments, or project data.
+
+## Acceptance
+
+- Burst and sustained limits have deterministic `429` behavior and `Retry-After`.
+- Different credentials do not consume each other's budgets.
+- Memory remains bounded under rotating identifiers and process restart semantics are documented.
+- Fly/edge limits remain recommended because one-process counters are not account-wide.
+
+This control supplements authentication; it does not replace it.
@@ -0,0 +1,25 @@
+# Recommendation 04: Premiere operation scheduler
+
+## Evidence
+
+Concurrent MCP requests can reach one interactive Premiere host. Adobe UXP mutations
+are committed through project transactions, but that does not serialize independent
+requests or make a timed-out mutation safe to replay.
+
+- [Adobe Project.executeTransaction](https://developer.adobe.com/premiere-pro/uxp/ppro-reference/classes/project/#executetransaction)
+- [MCP cancellation](https://modelcontextprotocol.io/specification/2026-07-28/basic/utilities/cancellation)
+
+## Proposed improvement
+
+Introduce one FIFO mutation lane plus configurable safe-read concurrency. Classify
+before enqueueing, bound queue length and wait time, attach operation IDs, and stop
+queued work on disconnect. Never claim cancellation after the host commit boundary.
+
+## Acceptance
+
+- Mutations cannot overlap; explicitly safe reads demonstrate bounded parallelism.
+- Queue overflow and expiry return stable overload errors without host calls.
+- Tests cover fairness, disconnects, timeouts, and mutation/read classification.
+- Metrics expose counts and timings only, never project or tool arguments.
+
+Contract tests cannot replace a real-host concurrency run.
@@ -0,0 +1,26 @@
+# Recommendation 05: negotiated MCP Tasks
+
+## Evidence
+
+The 2026-07-28 MCP release adds standardized long-running task semantics. Premiere
+exports, proxy generation, transcription, and analysis can exceed an interactive
+request, while Adobe APIs may offer no mid-call cancellation point.
+
+- [MCP 2026-07-28 release](https://blog.modelcontextprotocol.io/posts/2026-07-28)
+- [MCP Tasks extension](https://modelcontextprotocol.io/seps/2663-tasks-extension)
+
+## Proposed improvement
+
+Negotiate Tasks and initially wrap exports only. Use authorization-scoped random
+IDs, bounded retention, progress, expiry, and precise queued/running/committed states.
+Keep the synchronous path for clients without support and persist no project args or
+results containing media data.
+
+## Acceptance
+
+- Compatible clients can start, inspect, cancel, and retrieve an export result.
+- Incompatible clients never receive an unknown task handle.
+- Restart and cancellation tests define recoverable states and commit boundaries.
+- Task count, retention bytes, and telemetry cardinality are capped.
+
+Tasks do not make a blocking Adobe export API cancellable.
@@ -0,0 +1,24 @@
+# Recommendation 06: strict tool output schemas
+
+## Evidence
+
+MCP 2026-07-28 tools may advertise `outputSchema`. The server returns structured
+results but does not publish or validate per-tool output contracts, leaving clients
+unable to distinguish schema drift from host failures.
+
+- [MCP tools specification](https://modelcontextprotocol.io/specification/2026-07-28/server/tools)
+
+## Proposed improvement
+
+Add shared success/error/verification schemas and migrate read-only diagnostics first.
+Validate `structuredContent` before return, preserve the text block for compatibility,
+and maintain a machine-readable waiver list for unmigrated tools.
+
+## Acceptance
+
+- Every migrated tool publishes valid JSON Schema 2020-12 output.
+- Representative success and failure paths reject schema drift in CI.
+- Error codes, operation semantics, and verification boundaries are typed.
+- Schema failure never converts an ambiguous host mutation into a retry.
+
+Start with read-only tools; mutation migration needs separate host evidence.
@@ -0,0 +1,25 @@
+# Recommendation 07: JSON Schema constraint fidelity
+
+## Evidence
+
+Tool parameters are authored as JSON Schema but the server's JSON-Schema-to-Zod
+adapter currently preserves types and string enums while dropping bounds such as
+`minLength`, `maxLength`, numeric limits, and array limits. MCP treats input schemas
+as the tool contract.
+
+- [MCP tools specification](https://modelcontextprotocol.io/specification/2026-07-28/server/tools)
+
+## Proposed improvement
+
+Compile supported constraints into Zod, reject unsupported schema keywords during CI,
+add integer and non-string enum support, and cap schema depth/size. Do not silently
+coerce values or apply defaults that change existing tool behavior.
+
+## Acceptance
+
+- Boundary tests cover strings, numbers, integers, arrays, enums, and nested objects.
+- Every catalog schema compiles deterministically with a bounded cache.
+- Unsupported keywords produce a build-time migration report.
+- Existing valid client calls remain compatible.
+
+This improves server-side validation; it does not validate Adobe host semantics.
@@ -0,0 +1,25 @@
+# Recommendation 08: contained artifact resource links
+
+## Evidence
+
+MCP tool results can return resource links and embedded resources. Export, AAF, and
+compatibility reports currently describe paths in ordinary result data, which is
+hard for clients to consume safely.
+
+- [MCP tool result content](https://modelcontextprotocol.io/specification/2026-07-28/server/tools)
+- [MCP resource security](https://modelcontextprotocol.io/specification/2026-07-28/server/resources)
+
+## Proposed improvement
+
+Create authorization-scoped artifact IDs and expose only registered, size-bounded
+files under a dedicated URI scheme. Canonicalize paths, reject links/reparse points,
+set short expirations, and never turn an arbitrary tool-supplied path into a resource.
+
+## Acceptance
+
+- Export/report results include a resource link only after artifact registration.
+- Traversal, alternate separators, symlinks, oversized files, and expired IDs fail closed.
+- Resource reads recheck authorization and MIME type.
+- Existing text and structured results remain available to older clients.
+
+Artifact existence still requires post-export verification.
@@ -0,0 +1,24 @@
+# Recommendation 09: workflow-scoped tool packs
+
+## Evidence
+
+The server advertises 285 core tools. Large discovery payloads consume client context
+and make correct-tool selection harder. MCP discovery is capability-driven, and the
+2026-07-28 release adds cache metadata for list results.
+
+- [MCP 2026-07-28 release](https://blog.modelcontextprotocol.io/posts/2026-07-28)
+
+## Proposed improvement
+
+Define versioned essential, rough-cut, audio, captions, color, delivery, inspection,
+and advanced packs. Operator selection controls visibility only; authority checks
+remain separate and direct calls to hidden unauthorized tools stay denied.
+
+## Acceptance
+
+- Every tool belongs to at least one pack and retains an authority classification.
+- Essential completes diagnosis, inspection, safe preview, save, and delivery.
+- Full-catalog mode remains available through a documented compatibility window.
+- Benchmarks measure list bytes, schema time, prompt tokens, and correct-tool selection.
+
+Tool packs are context optimization, not an authorization mechanism.
@@ -0,0 +1,24 @@
+# Recommendation 10: cacheable discovery with invalidation
+
+## Evidence
+
+MCP 2026-07-28 adds `ttlMs` and `cacheScope` to list results. This server repeatedly
+builds large tool catalogs whose contents vary with authority and UXP connection state.
+
+- [MCP 2026-07-28 release](https://blog.modelcontextprotocol.io/posts/2026-07-28)
+
+## Proposed improvement
+
+Return private cache metadata for tools, prompts, and resources when the installed SDK
+supports it. Key caches by server version, authority profile, selected tool pack, UXP
+protocol/capabilities, and connector state. Emit list-changed notifications only to
+clients that negotiate them, coalescing connection churn.
+
+## Acceptance
+
+- Cache keys never cross authorization profiles.
+- UXP connect/disconnect and pack changes invalidate discovery deterministically.
+- Repeated list benchmarks show lower serialization work and bytes transferred.
+- Older clients retain current behavior without unknown fields or notifications.
+
+No cache may preserve tools after their authority is revoked.
@@ -0,0 +1,24 @@
+# Recommendation 11: UXP bridge backpressure
+
+## Evidence
+
+The authenticated UXP bridge bounds each WebSocket frame but its pending-request map
+has no count limit. A burst can therefore allocate timers and request state faster
+than a single interactive Premiere host can complete commands.
+
+- [Adobe UXP network operations](https://developer.adobe.com/premiere-pro/uxp/resources/recipes/network)
+
+## Proposed improvement
+
+Add configurable pending and queued limits, reject excess work before generating a
+request ID, and expose aggregate active/rejected counters. Coordinate with the future
+operation scheduler so only one component owns mutation ordering.
+
+## Acceptance
+
+- Pending entries and timers never exceed the configured cap.
+- Rejections have a stable `UXP_OVERLOADED` code and never reach the panel.
+- Timeout, send failure, disconnect, replacement connection, and stop release capacity.
+- Load tests demonstrate bounded heap and telemetry cardinality.
+
+Backpressure does not imply that Adobe host calls are cancellable.
@@ -0,0 +1,24 @@
+# Recommendation 12: remove UXP tokens from URLs
+
+## Evidence
+
+The loopback bridge authenticates with a token query parameter. URLs are more likely
+than headers to appear in diagnostics, proxy logs, screenshots, or error strings.
+Adobe UXP WebSocket access remains permission-gated by the manifest and runtime URL checks.
+
+- [Adobe UXP network security](https://developer.adobe.com/premiere-pro/uxp/resources/recipes/network)
+
+## Proposed improvement
+
+Move the secret to a WebSocket subprotocol or supported authorization header while
+retaining constant-time comparison, loopback binding, exact path checks, and a short
+documented compatibility window for query authentication. Redact both forms everywhere.
+
+## Acceptance
+
+- New panel connections contain no secret in the URL.
+- Missing, duplicate, malformed, and wrong credentials fail before upgrade.
+- Logs, telemetry, status UI, and errors never contain credential material.
+- Compatibility mode is opt-in, warned, tested, and assigned a removal version.
+
+The chosen mechanism must be proven in Premiere 26.3 UXP, not only browser mocks.
@@ -0,0 +1,24 @@
+# Recommendation 13: UXP connection liveness
+
+## Evidence
+
+A TCP/WebSocket connection can remain open while Premiere is modal, suspended, or no
+longer processing panel messages. Current state reports connected until socket closure
+or a command timeout, delaying diagnosis and tying up pending work.
+
+- [Adobe UXP WebSocket guidance](https://developer.adobe.com/premiere-pro/uxp/resources/recipes/network)
+
+## Proposed improvement
+
+Add protocol-level heartbeat sequence numbers and bounded round-trip measurements.
+Classify `connected`, `degraded`, and `stale`; stop admitting new mutations when stale,
+but never replay a timed-out mutation after reconnection.
+
+## Acceptance
+
+- Heartbeats are authenticated, size-bounded, and excluded from tool telemetry.
+- Miss thresholds tolerate short event-loop stalls without reconnect storms.
+- Stale connections reject new work and settle pending requests deterministically.
+- Diagnostics distinguish socket liveness from successful Premiere host execution.
+
+Live-host tests must cover modal dialogs, sleep/wake, panel reload, and Premiere exit.
@@ -0,0 +1,25 @@
+# Recommendation 14: revisioned in-panel project index
+
+## Evidence
+
+Several UXP commands traverse the complete project tree to resolve items. Adobe exposes
+stable project/item identities and project events; repeated breadth-first traversal
+scales poorly and duplicate names must not resolve silently.
+
+- [Adobe Premiere UXP Project API](https://developer.adobe.com/premiere-pro/uxp/ppro-reference/classes/project)
+- [Adobe UXP events](https://developer.adobe.com/premiere-pro/uxp/resources/fundamentals/events)
+
+## Proposed improvement
+
+Maintain a bounded index by item GUID, exact name, normalized path hash, type, and
+parent identity. Increment revisions from documented events and successful commands;
+when event evidence is incomplete, mark stale and rebuild instead of guessing.
+
+## Acceptance
+
+- Duplicate names return bounded matches or require a stable identity.
+- Entry count/memory are capped and cleared on project close or disconnect.
+- Lost/coalesced event tests prove a full rebuild restores correctness.
+- Large fixtures improve p50/p95 lookup without changing command results.
+
+Mock benchmarks are not live-host performance evidence.
@@ -0,0 +1,24 @@
+# Recommendation 15: paginated project discovery
+
+## Evidence
+
+Large Premiere projects can contain thousands of items. Returning an entire tree in
+one tool response increases host traversal time, MCP payload size, and model context.
+Adobe's Project API provides stable items; MCP tools can expose bounded cursors.
+
+- [Adobe Premiere UXP Project API](https://developer.adobe.com/premiere-pro/uxp/ppro-reference/classes/project)
+
+## Proposed improvement
+
+Add cursor-based, revision-locked project-item discovery with explicit page and field
+limits. Cursors should be opaque, authorization-scoped, short-lived, and invalidated
+when the project-index revision changes. Default fields exclude native paths.
+
+## Acceptance
+
+- Page size, response bytes, traversal time, and cursor count are bounded.
+- Changed projects return `refresh_required` rather than mixed-revision pages.
+- Duplicate names retain stable IDs and parent identity.
+- Tests cover expired, forged, cross-project, and cross-credential cursors.
+
+Pagination depends on stable identity but not on undocumented QE behavior.
@@ -0,0 +1,24 @@
+# Recommendation 16: project-context delta capture
+
+## Evidence
+
+The durable context engine correctly separates source and timeline revisions, but a
+capture still rebuilds a bounded active-sequence snapshot. Documented project events
+and stable identities can reduce repeated work if event loss fails closed.
+
+- [Adobe UXP events](https://developer.adobe.com/premiere-pro/uxp/resources/fundamentals/events)
+
+## Proposed improvement
+
+Accept an optional prior revision and return added, changed, removed, and retained
+record IDs. Coalesce event hints, re-read affected records, and force a full capture
+when event continuity, project identity, truncation, or schema compatibility is uncertain.
+
+## Acceptance
+
+- Applying a delta to its exact base equals a fresh full snapshot.
+- Wrong/stale bases return `full_refresh_required` without partial persistence.
+- Deltas and event queues are count/byte/time bounded.
+- Source enrichments survive timeline-only changes and invalidate on source revision changes.
+
+Events are hints; correctness continues to come from bounded readback.
@@ -0,0 +1,24 @@
+# Recommendation 17: reproducible live-host compatibility lab
+
+## Evidence
+
+Adobe's 26.3 UXP changelog includes breaking and new APIs, while automated adapters
+cannot establish behavior in licensed Premiere builds. The coverage manifest keeps
+live-host evidence separate but lacks a reproducible collection protocol.
+
+- [Adobe Premiere UXP changelog](https://developer.adobe.com/premiere-pro/uxp/changelog)
+
+## Proposed improvement
+
+Package privacy-safe small/medium/large fixture manifests and a manual host runner.
+Record host/OS versions, artifact SHA-256, backend, command, timing phases, observable
+readback, and outcome—never project/media names, paths, transcripts, or arguments.
+
+## Acceptance
+
+- Reports distinguish verified, committed-unverified, unsupported, failed, and not-run.
+- Evidence promotion requires exact host, OS, artifact hash, command, and readback.
+- CI validates schemas/fixtures without labeling mocks as Premiere.
+- Reports include p50/p95/max dispatch, host, verification, and total latency.
+
+The lab remains manual because CI is not a licensed interactive Premiere host.
@@ -0,0 +1,25 @@
+# Recommendation 18: capability-aware transcript language cache
+
+## Evidence
+
+Premiere 26.3 adds `Transcript.querySupportedLanguages()`. Re-querying immutable host
+metadata for every planning workflow adds round trips, while assuming languages from
+locale or prior hosts would misrepresent installed capability.
+
+- [Adobe Premiere UXP changelog](https://developer.adobe.com/premiere-pro/uxp/changelog)
+- [Adobe Transcript API](https://developer.adobe.com/premiere-pro/uxp/ppro-reference/classes/transcript)
+
+## Proposed improvement
+
+Cache the bounded normalized language list by exact Premiere version, UXP protocol,
+and connection generation. Invalidate on reconnect or capability change, return cache
+age/source, and never infer language-pack installation beyond Adobe's returned data.
+
+## Acceptance
+
+- Repeated reads on one connection use one host call.
+- Reconnect, version change, probe failure, and explicit refresh invalidate safely.
+- Codes/names are normalized, deduplicated, size-bounded, and preserve unknown fields only in debug fixtures.
+- A query failure returns unavailable, never a stale claim from another host.
+
+This optimizes capability discovery; it does not start transcription.
@@ -0,0 +1,24 @@
+# Recommendation 19: bounded Object Mask audit
+
+## Evidence
+
+Premiere 26.3 exposes `ObjectMaskUtils`, while the public surface currently supports
+inspection rather than object selection, mask creation, tracking, or parameter edits.
+The repository correctly exposes a single-target check but not a project-wide audit.
+
+- [Adobe Premiere UXP changelog](https://developer.adobe.com/premiere-pro/uxp/changelog)
+
+## Proposed improvement
+
+Add a read-only, paginated audit over explicit sequence/project-item identities using
+only documented `hasObjectMask` probes. Reuse the revisioned index, cap host calls per
+page, return per-item errors, and do not infer mask quality, tracking state, or editability.
+
+## Acceptance
+
+- Inputs require stable IDs; duplicate names never choose a target.
+- Page size, host calls, duration, response bytes, and error count are bounded.
+- Stale project revisions require refresh.
+- Capability reports continue to label creation/tracking/editing unsupported.
+
+Live Premiere validation must confirm which documented item types the probe accepts.
@@ -0,0 +1,26 @@
+# Recommendation 20: AAF artifact verification
+
+## Evidence
+
+Premiere 26.3 adds `ProjectConverter.exportAAF()` and `AAFExportOptions`. The existing
+UXP tool truthfully records Adobe's boolean return with `outputVerified: false`; a host
+return alone does not prove that a usable artifact exists.
+
+- [Adobe Premiere UXP changelog](https://developer.adobe.com/premiere-pro/uxp/changelog)
+- [Adobe ProjectConverter API](https://developer.adobe.com/premiere-pro/uxp/ppro-reference/classes/projectconverter)
+
+## Proposed improvement
+
+After a successful host return, verify the approved destination is contained, exists,
+is a regular non-link file, has a stable nonzero size, and was modified by this operation.
+Return a scoped artifact link and preserve `usable_in_target_nle: not_verified` unless an
+independent importer validates it.
+
+## Acceptance
+
+- Pre-existing, missing, empty, unstable, linked, and outside-root paths fail verification.
+- Verification never changes Adobe's host return or silently retries export.
+- Results separate host-return, filesystem-artifact, and downstream-usability evidence.
+- Windows/macOS live runs cover success, cancellation, overwrite, and permission failure.
+
+File existence is not proof that another NLE can import the AAF correctly.