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,21 @@
+# Recommendation 21: stateless MCP 2026-07-28 migration
+
+## Evidence
+
+MCP 2026-07-28 removes the initialization handshake and protocol session. Each request carries its protocol version and client capabilities, while discovery moves to `server/discover`.
+
+- [MCP 2026-07-28 release](https://blog.modelcontextprotocol.io/posts/2026-07-28)
+- [MCP stateless proposal](https://modelcontextprotocol.io/seps/2575-stateless-mcp)
+
+## Proposed improvement
+
+Add a negotiated 2026-07-28 HTTP path while preserving the current legacy path. Make every request independently validate version, client capabilities, authentication, and server identity; remove any hidden dependency on transport affinity.
+
+## Acceptance criteria
+
+- Tests distribute consecutive requests across fresh server instances without losing application handles.
+- Legacy clients negotiate the existing protocol rather than receiving partial 2026 behavior.
+- Unsupported versions fail with the specified typed error.
+- A migration document identifies every session-derived assumption.
+
+Stateless transport does not make Premiere project state stateless or prove host execution.
@@ -0,0 +1,21 @@
+# Recommendation 22: MRTR confirmation for consequential edits
+
+## Evidence
+
+MCP 2026-07-28 introduces `InputRequiredResult` so a server can request user input during an active call and the client can retry with `inputResponses`.
+
+- [MCP key changes](https://modelcontextprotocol.io/specification/2026-07-28/changelog)
+- [MCP release candidate details](https://blog.modelcontextprotocol.io/posts/2026-07-28-release-candidate)
+
+## Proposed improvement
+
+Use MRTR for overwrite, delete, relink, and export-overwrite confirmations when the client advertises support. Bind the response to a canonical operation digest, project revision, expiry, and authenticated principal.
+
+## Acceptance criteria
+
+- A changed plan, project revision, principal, or expired prompt invalidates the response.
+- Clients without MRTR receive the existing explicit-token flow.
+- Retries are idempotent before the host commit boundary.
+- Tests cover approve, decline, replay, mismatch, and disconnect.
+
+MRTR is a confirmation transport, not evidence that a human understood the edit.
@@ -0,0 +1,21 @@
+# Recommendation 23: MCP routing-header integrity
+
+## Evidence
+
+MCP 2026-07-28 adds `Mcp-Method` and `Mcp-Name` headers for routing without parsing request bodies and defines `HeaderMismatchError` when they disagree with the JSON-RPC payload.
+
+- [MCP key changes](https://modelcontextprotocol.io/specification/2026-07-28/changelog)
+- [MCP SDK release overview](https://blog.modelcontextprotocol.io/posts/sdk-betas-2026-07-28)
+
+## Proposed improvement
+
+Validate routing headers against the parsed body before authentication scope selection or dispatch. Treat headers as bounded routing hints, never as independent authorization facts, and redact sensitive resource names from access logs.
+
+## Acceptance criteria
+
+- Missing, duplicate, oversized, and mismatched headers have deterministic outcomes.
+- Proxies cannot authorize one tool while dispatching another.
+- Header values use strict byte and character limits.
+- Compatibility tests cover clients from both protocol generations.
+
+This complements exact HTTP route admission; it addresses semantic routing after admission.
@@ -0,0 +1,21 @@
+# Recommendation 24: per-request capability envelope
+
+## Evidence
+
+In stateless MCP, every request carries protocol version and client capabilities in `_meta`; servers publish their identity and capabilities through discovery and result metadata.
+
+- [SEP-2575: Make MCP Stateless](https://modelcontextprotocol.io/seps/2575-stateless-mcp)
+- [MCP 2026-07-28 release](https://blog.modelcontextprotocol.io/posts/2026-07-28)
+
+## Proposed improvement
+
+Create one validated request envelope used by tool, prompt, and resource handlers. It should normalize protocol version, client capabilities, client identity, auth scope, request ID, and advertised response features before business logic runs.
+
+## Acceptance criteria
+
+- Missing required capabilities fail before any bridge call.
+- Unknown optional capabilities are ignored and recorded with bounded cardinality.
+- Result metadata reports the actual server version handling the call.
+- Fuzz tests cover malformed and adversarial `_meta` objects.
+
+Client metadata is self-asserted unless independently authenticated.
@@ -0,0 +1,21 @@
+# Recommendation 25: formal MCP extension negotiation
+
+## Evidence
+
+MCP 2026-07-28 establishes a formal extensions framework so optional features can evolve without silently changing the protocol core.
+
+- [MCP 2026-07-28 release](https://blog.modelcontextprotocol.io/posts/2026-07-28)
+- [MCP release candidate](https://blog.modelcontextprotocol.io/posts/2026-07-28-release-candidate)
+
+## Proposed improvement
+
+Add a single extension registry describing supported versions, stability, required client capabilities, configuration gates, and fallback behavior. Route Tasks and future UI integrations through it instead of scattered feature flags.
+
+## Acceptance criteria
+
+- Unknown or incompatible extensions never alter core tool behavior.
+- Experimental extensions are disabled by default and labeled in discovery.
+- Registry snapshots are contract-tested across releases.
+- Each extension documents downgrade and removal behavior.
+
+Advertising an extension means protocol support only, not Premiere host support.
@@ -0,0 +1,21 @@
+# Recommendation 26: request-scoped observability migration
+
+## Evidence
+
+MCP 2026-07-28 removes `logging/setLevel`; protocol logs become a per-request opt-in through `_meta`. The specification also formalizes deprecation of the older logging capability.
+
+- [MCP stateless proposal](https://modelcontextprotocol.io/seps/2575-stateless-mcp)
+- [Python SDK migration guide](https://py.sdk.modelcontextprotocol.io/migration)
+
+## Proposed improvement
+
+Separate client-visible diagnostic logs from server telemetry. Honor the negotiated request log level, correlate all records with operation and bridge IDs, and export privacy-filtered traces and metrics independently of MCP notifications.
+
+## Acceptance criteria
+
+- No protocol log is emitted without explicit per-request opt-in.
+- Secrets, media paths, transcript text, and project names are redacted by default.
+- Trace sampling and label cardinality are bounded.
+- Legacy logging behavior is version-gated and removal-dated.
+
+Telemetry can diagnose a call but cannot prove the visual result in Premiere.
@@ -0,0 +1,21 @@
+# Recommendation 27: protocol deprecation ledger
+
+## Evidence
+
+The 2026-07-28 MCP revision removes the initialization handshake, protocol sessions, `logging/setLevel`, and top-level `roots/list`, while establishing a formal deprecation policy.
+
+- [MCP 2026-07-28 changelog](https://modelcontextprotocol.io/specification/2026-07-28/changelog)
+- [SEP-2575](https://modelcontextprotocol.io/seps/2575-stateless-mcp)
+
+## Proposed improvement
+
+Maintain a machine-readable ledger for every deprecated protocol behavior: first warning version, replacement, telemetry signal, planned removal, compatibility tests, and operator override.
+
+## Acceptance criteria
+
+- CI fails when deprecated code lacks an owner or removal condition.
+- Release notes are generated from the ledger without overstating compatibility.
+- Usage telemetry is aggregate and privacy-safe.
+- Removing a path requires zero observed use or an explicit breaking release decision.
+
+The ledger governs server compatibility, not Adobe API deprecations unless separately listed.
@@ -0,0 +1,20 @@
+# Recommendation 28: MCP error taxonomy and allocation
+
+## Evidence
+
+MCP 2026-07-28 reserves JSON-RPC server error codes `-32020` through `-32099` for the specification and defines typed errors for header mismatch, missing capability, and unsupported version.
+
+- [MCP key changes](https://modelcontextprotocol.io/specification/2026-07-28/changelog)
+
+## Proposed improvement
+
+Create a central error registry that keeps protocol-reserved errors separate from Premiere, bridge, validation, authentication, and internal failures. Map errors to retryability, mutation certainty, safe client text, and telemetry class.
+
+## Acceptance criteria
+
+- No implementation-defined error uses the protocol-reserved range.
+- Every bridge failure states whether a host mutation may have committed.
+- Stack traces and private paths never reach clients.
+- Snapshot tests lock codes, shapes, and backward-compatible text fallbacks.
+
+A structured error reports uncertainty; it must not convert unknown host state into failure or success.
@@ -0,0 +1,21 @@
+# Recommendation 29: UXP API-era compatibility adapter
+
+## Evidence
+
+Adobe changed `Sequence.setSelection` in Premiere 26.3 from asynchronous `Promise<boolean>` to synchronous `boolean`, demonstrating that host-version differences can change call semantics.
+
+- [Adobe UXP changelog](https://developer.adobe.com/premiere-pro/uxp/changelog)
+- [Adobe Sequence reference](https://developer.adobe.com/premiere-pro/uxp/ppro-reference/classes/sequence)
+
+## Proposed improvement
+
+Centralize version-sensitive Adobe calls behind typed adapters that normalize sync/async returns without guessing support. Generate an audited compatibility table from official declarations and runtime probes.
+
+## Acceptance criteria
+
+- The 25.x and 26.3 selection signatures have explicit contract fixtures.
+- Unknown versions fail closed for mutations and expose diagnostics.
+- Runtime probes do not mutate user projects.
+- Direct version-sensitive calls outside the adapter fail lint or review checks.
+
+Contract fixtures are not a substitute for runs in each licensed host version.
@@ -0,0 +1,21 @@
+# Recommendation 30: signed host capability attestation
+
+## Evidence
+
+Adobe documents host and UXP runtime version inspection, while Premiere APIs declare minimum versions per method. Static package declarations can therefore differ from the connected runtime.
+
+- [Understanding UXP APIs](https://developer.adobe.com/premiere-pro/uxp/resources/fundamentals/apis)
+- [Adobe UXP changelog](https://developer.adobe.com/premiere-pro/uxp/changelog)
+
+## Proposed improvement
+
+Have the authenticated panel produce a nonce-bound capability attestation containing host version, UXP version, plugin build hash, probed stable methods, and timestamp. Bind it to the current WebSocket connection and expire it quickly.
+
+## Acceptance criteria
+
+- Replayed, expired, cross-connection, and mismatched-build attestations are rejected.
+- Probes are read-only and bounded.
+- Tool discovery uses the attested intersection, not package-version assumptions.
+- Diagnostics distinguish declared, probed, and live-verified capability.
+
+Attestation proves what the panel observed, not that a later host operation succeeded.
@@ -0,0 +1,20 @@
+# Recommendation 31: Adobe sample parity drift check
+
+## Evidence
+
+Adobe’s official Premiere UXP samples exercise projects, sequences, markers, metadata, effects, exports, encoder, transcripts, and project conversion, with manifests treated as authoritative for version compatibility.
+
+- [Adobe Premiere UXP samples](https://github.com/AdobeDocs/uxp-premiere-pro-samples)
+
+## Proposed improvement
+
+Add a scheduled, review-only drift job that compares pinned Adobe sample manifests and package versions with this repository’s coverage manifest. Produce candidate gaps without automatically enabling tools or beta APIs.
+
+## Acceptance criteria
+
+- Inputs are pinned by commit SHA and artifact hash.
+- Changes open an auditable report, not an automatic production mutation.
+- Stable and beta declarations remain separate.
+- Removed or changed APIs create blocking review items for affected tools.
+
+Sample usage is implementation guidance, not a compatibility guarantee.
@@ -0,0 +1,21 @@
+# Recommendation 32: transaction deadline and readback budget
+
+## Evidence
+
+Adobe UXP mutations are expressed as actions and executed through project transactions; many surrounding reads remain asynchronous and can stall independently.
+
+- [Adobe Sequence reference](https://developer.adobe.com/premiere-pro/uxp/ppro-reference/classes/sequence)
+- [Understanding UXP APIs](https://developer.adobe.com/premiere-pro/uxp/resources/fundamentals/apis)
+
+## Proposed improvement
+
+Define separate deadlines for preflight, synchronous action construction, transaction execution, and post-commit readback. Return a receipt that identifies the last known phase and never retries an uncertain mutation automatically.
+
+## Acceptance criteria
+
+- Tests inject timeouts at every phase and assert mutation certainty.
+- Readback exhaustion returns `committed_unverified`, not false failure.
+- The scheduler prevents a timed-out call from releasing unsafe conflicting work.
+- Phase budgets are configurable within capped limits.
+
+A completed transaction still requires host readback or human observation for outcome claims.
@@ -0,0 +1,21 @@
+# Recommendation 33: generated UXP permission minimization
+
+## Evidence
+
+Adobe UXP manifests explicitly declare network and local-file-system permissions. Permission scope is part of the install-time trust boundary.
+
+- [Adobe UXP manifest](https://developer.adobe.com/premiere-pro/uxp/plugins/concepts/manifest/)
+- [Adobe UXP network recipe](https://developer.adobe.com/premiere-pro/uxp/resources/recipes/network)
+
+## Proposed improvement
+
+Generate release manifests from a reviewed permission policy and fail CI on undeclared expansion. Separate development, benchmark, and production permissions; include a human-readable permission diff in releases.
+
+## Acceptance criteria
+
+- Production never inherits development-only addon or network permissions.
+- New permissions require rationale, threat analysis, and explicit review.
+- Runtime endpoints are still validated even when Adobe requires a broad domain declaration.
+- Packaged manifest hashes are verified in release provenance.
+
+Manifest minimization reduces exposure but does not replace runtime authentication.
@@ -0,0 +1,21 @@
+# Recommendation 34: UXP filesystem token lifecycle
+
+## Evidence
+
+UXP local filesystem access is permission-gated and user-selected entries may be represented by persistent tokens rather than unrestricted native paths.
+
+- [Adobe UXP manifest](https://developer.adobe.com/premiere-pro/uxp/plugins/concepts/manifest/)
+- [Adobe UXP file-system recipes](https://developer.adobe.com/premiere-pro/uxp/resources/recipes/)
+
+## Proposed improvement
+
+Introduce a token broker that records purpose, project binding, creation time, last use, and revocation without exposing raw tokens to MCP clients. Re-prompt when a token is stale or no longer resolves.
+
+## Acceptance criteria
+
+- Tokens are encrypted at rest or remain solely in UXP-managed storage.
+- Logs and tool results never contain token values.
+- Revocation, moved files, and denied reauthorization fail deterministically.
+- Cleanup is bounded by age and count with explicit user controls.
+
+A valid token authorizes filesystem access only; it does not validate media contents.
@@ -0,0 +1,21 @@
+# Recommendation 35: versioned UXP bridge protocol
+
+## Evidence
+
+Adobe’s UXP runtime and Premiere API surface evolve independently, while this project connects the panel through an authenticated loopback WebSocket.
+
+- [Understanding UXP APIs](https://developer.adobe.com/premiere-pro/uxp/resources/fundamentals/apis)
+- [Adobe UXP changelog](https://developer.adobe.com/premiere-pro/uxp/changelog)
+
+## Proposed improvement
+
+Version the panel/server hello, command envelope, event envelope, error shape, and feature flags. Negotiate the highest mutually supported bridge version and reject ambiguous downgrade.
+
+## Acceptance criteria
+
+- Cross-version fixtures cover the current and previous supported bridge version.
+- Unknown commands and fields have documented forward-compatibility behavior.
+- Downgrade cannot bypass authentication or capability checks.
+- Fuzz tests bound nesting, arrays, strings, and numeric values after frame parsing.
+
+Bridge negotiation is distinct from MCP protocol and Adobe host-version negotiation.
@@ -0,0 +1,20 @@
+# Recommendation 36: privacy-safe context retention policy
+
+## Evidence
+
+Stateless MCP permits explicit application handles for state that must survive calls; it does not require indefinite application storage.
+
+- [MCP stateless release candidate](https://blog.modelcontextprotocol.io/posts/2026-07-28-release-candidate)
+
+## Proposed improvement
+
+Add per-project TTL, byte quota, transcript opt-in, field-level redaction, compaction receipts, and delete/export controls to the project-context store. Keep operational state separate from model-ready summaries.
+
+## Acceptance criteria
+
+- Raw transcript text is disabled by default for persistent context.
+- Quota enforcement is deterministic and never evicts an active write silently.
+- Delete removes primary and derived records with an audit receipt that contains no content.
+- Tests cover crash recovery, clock skew, corruption, and concurrent compaction.
+
+Retention policy reduces stored data; it does not make model inference private by itself.
@@ -0,0 +1,20 @@
+# Recommendation 37: transcript round-trip integrity
+
+## Evidence
+
+Adobe’s stable UXP `Transcript` API can export transcript JSON, import JSON into text segments, create an import action, query supported languages, and test transcript presence.
+
+- [Adobe Transcript reference](https://developer.adobe.com/premiere-pro/uxp/ppro-reference/classes/transcript)
+
+## Proposed improvement
+
+Add a dry-run transcript importer that validates schema, language metadata, time ordering, clip identity, and a canonical content digest before constructing an Adobe action. Verify post-commit presence and bounded export equivalence.
+
+## Acceptance criteria
+
+- Malformed, overlapping, out-of-range, and wrong-clip segments fail before mutation.
+- Confirmation binds the canonical digest and project revision.
+- Readback reports semantic differences without leaking transcript text into logs.
+- Real-host fixtures cover supported languages and large transcripts.
+
+JSON equivalence does not prove word-level alignment or transcription accuracy.
@@ -0,0 +1,20 @@
+# Recommendation 38: metadata batch planner
+
+## Evidence
+
+Adobe’s production-style metadata sample supports column copy/exchange, batch prefix/suffix/numbering, metadata export, and clip-marker export.
+
+- [Adobe Premiere UXP samples](https://github.com/AdobeDocs/uxp-premiere-pro-samples)
+
+## Proposed improvement
+
+Create a bounded metadata plan/preview/apply workflow with explicit namespaces, typed coercion, per-item expected values, conflict detection, and chunked transactions. Default to exporting a rollback artifact before changes.
+
+## Acceptance criteria
+
+- Preview identifies writable fields, collisions, truncation, and no-op edits.
+- Apply requires exact project revision and plan digest.
+- Partial batches return per-item certainty and never retry unknown commits.
+- Sensitive metadata fields are excluded unless explicitly allowlisted.
+
+Adobe’s sample demonstrates a workflow pattern; real project schemas still require host validation.
@@ -0,0 +1,20 @@
+# Recommendation 39: sequence-sandbox verification mode
+
+## Evidence
+
+Adobe’s stable `Sequence.createCloneAction` can clone a sequence through an undoable action.
+
+- [Adobe Sequence reference](https://developer.adobe.com/premiere-pro/uxp/ppro-reference/classes/sequence)
+
+## Proposed improvement
+
+Offer an opt-in verification mode that clones the target sequence, applies a proposed edit plan only to the clone, captures bounded structural diffs, and requires a separate confirmation before applying an independently revalidated plan to the original.
+
+## Acceptance criteria
+
+- Clone names and IDs are collision-safe and traceable to an operation receipt.
+- The original sequence is never targeted during sandbox execution.
+- Cleanup is explicit and refuses deletion if identity or revision changed.
+- Tests cover clone failure, partial apply, user edits, and stale confirmation.
+
+Success on a clone does not guarantee identical rendering or a safe original apply.
@@ -0,0 +1,21 @@
+# Recommendation 40: export artifact reconciliation
+
+## Evidence
+
+Adobe’s stable `EncoderManager` supports Premiere and AME export workflows, and its events distinguish queue, progress, completion, error, and cancellation.
+
+- [Adobe EncoderManager reference](https://developer.adobe.com/premiere-pro/uxp/ppro-reference/classes/encodermanager/)
+- [Adobe UXP changelog](https://developer.adobe.com/premiere-pro/uxp/changelog)
+
+## Proposed improvement
+
+Add an export reconciler that joins operation receipts, encoder events, expected destination, artifact stat/hash, and optional media probe into one state machine. On restart, recover only from durable evidence and never re-submit an uncertain job automatically.
+
+## Acceptance criteria
+
+- States distinguish queued, rendering, cancelled, failed, completed-no-artifact, and verified-artifact.
+- Event gaps and duplicate events produce explicit uncertainty.
+- Overwrite policy and artifact identity are bound to the original confirmation.
+- Windows/macOS live-host runs cover Premiere and AME paths.
+
+An artifact hash proves file identity, not visual or editorial correctness.