@mevdragon/vidfarm-devcli 0.2.14 → 0.3.1

package/README.md

@@ -35,10 +35,17 @@ npm run cdk:deploy:prod-serverless
 
 Never call bare `cdk deploy` — the npm scripts load the correct `.env.<stage>` and select the right stack.
 
-## Deprecated: `@mevdragon/vidfarm-devcli`
+## Local editor: `@mevdragon/vidfarm-devcli`
 
-The `vidfarm-devcli` CLI (`src/cli.ts`) is **deprecated and no longer maintained**. It was built around the old REST-API template model — templates with `src/template.ts`, workflows, operations, viral DNA extraction, and the hosted publish/approve/activate flow. That entire paradigm has been superseded by the browser-based **Trackpad Editor** at `https://vidfarm.cc/editor/`.
+Pair a local composition directory with the hosted Trackpad Editor so an AI agent (Claude Code, Codex, etc.) or a human can edit `composition.html` on disk and see live preview in the browser.
 
-The CLI still exists in the repo and may partially work, but it will print a deprecation banner on every invocation. No fixes will land. Do not build new tooling on it.
+```bash
+npx -y @mevdragon/vidfarm-devcli <template_id>
+# → downloads the current composition into .vidfarm/<template_id>/
+# → starts dev-serve on localhost:4321
+# → prints an https://vidfarm.cc/editor/<template_id>?fork=…&dev=… URL to open
+```
+
+Flags: `--port`, `--dir`, `--host`, `--fork`, `--api-key` (or `VIDFARM_API_KEY`), `--share`, `--refetch`. Use `dev-serve` as an explicit subcommand to skip the fetch step and just serve an existing directory.
 
-See `SKILL.platform.md` for the current architecture.
+See `SKILL.platform.md` § "Local editor dev loop" for the request-rewrite / SSE reload flow.

package/SKILL.director.md

@@ -118,6 +118,14 @@ The editor persists to:
 
 Automation that needs to bypass the UI can call these endpoints directly.
 
+Reads also work anonymously since the `compositions/forks/*` S3 prefix is public-read — clients that only need to fetch (not mutate) can bypass the API and hit S3 directly:
+
+- `GET https://<bucket>.s3.<region>.amazonaws.com/compositions/forks/<forkId>/working/composition.html`
+- `GET .../working/composition.json`
+- `GET .../working/manifest.json` — fork identity + genealogy (`parent_fork_id`, `parent_version`, `latest_version`, direct URLs for html/json/parent manifest). Also served via `GET /api/v1/compositions/:forkId/manifest.json` and `.../versions/:v/manifest.json`.
+
+Treat the `forkId` as an unguessable bearer token — anyone with it can view the composition.
+
 ## Auto-decompose
 
 If the fork's source is a raw video (not a pre-decomposed template), call auto-decompose to split it into scenes:
@@ -246,6 +254,23 @@ For agents that operate Vidfarm headlessly, the typical loop is:
 
 Always send a stable `tracer` on publish to make retries idempotent.
 
+## Local dev loop with `vidfarm-devcli`
+
+For iterating on a composition on disk (e.g. Claude Code editing HTML directly), pair the hosted editor with a local composition directory:
+
+```bash
+npx -y @mevdragon/vidfarm-devcli <template_id>
+# → downloads composition.html/json + manifest.json into .vidfarm/<template_id>/
+# → starts dev-serve on http://localhost:4321
+# → prints https://vidfarm.cc/editor/<template_id>?fork=<forkId>&dev=http%3A%2F%2Flocalhost%3A4321
+```
+
+Open the printed URL in your browser. An orange **LOCAL DEV MODE** banner pins to the top with an Exit button. All fork API fetches now route to your local dir instead of the deployed API; disk edits push an SSE reload event and the editor re-fetches automatically.
+
+Flags: `--port`, `--dir`, `--host`, `--fork`, `--api-key` (or set `VIDFARM_API_KEY`), `--share`, `--refetch`. For a fork that already has composition files on disk (or that you've populated manually), use `vidfarm-devcli dev-serve --dir ./my-fork --port 4321` to skip the fetch step.
+
+The dev source is persisted in `localStorage.VIDFARM_DEV_SOURCE`, so you don't need to keep the `?dev=` param in the URL after the first load.
+
 ## What NOT to do
 
 - Do **not** manipulate composition HTML by string concatenation. Always parse, edit, and re-serialize the DOM. The editor and runtime rely on `data-start`, `data-duration`, `data-track-index`, `data-hf-id`, `data-composition-id` attributes being well-formed.
@@ -291,3 +316,78 @@ curl -X POST "$VIDFARM_BASE/api/v1/primitives/images/remove-background" \
   -H "content-type: application/json" \
   -d '{"source_image_url": "https://cdn.example.com/photo.jpg"}'
 ```
+
+## Primitive: media_dedupe
+
+Apply subtle camouflage transforms (zoom, tilt, rotate, saturation, playback speed, contrast, brightness, hue rotate, blur, horizontal flip, tint overlay) to any source **image or video** URL. Useful when reposting existing media and you want small perceptual differences to reduce duplicate-detection.
+
+- `POST /api/v1/primitives/media/dedupe`
+- Body: `{ "tracer": "...", "payload": { ...fields... }, "webhook_url"?: "..." }`
+- Response: standard primitive job. Poll to completion, then read `primary_file_url` (also `video.file_url` for MP4 or `image.file_url` for stills)
+- Billing: metered as a Remotion render (via `remotion_lambda` on prod, local fallback in dev)
+
+Payload fields:
+
+- `source_media_url` (required, URL) — the image or video to transform
+- `media_type` (`"image" | "video"`, optional) — auto-detected from URL extension if omitted (`.mp4/.mov/.webm/.m4v` → video, else image)
+- `effects` (optional object). All fields optional; defaults camouflage lightly:
+  - `zoom` (default `1.04`) — scale factor
+  - `tilt` (default `3`) — degrees of 3D X-axis tilt (perspective 1000px)
+  - `rotate` (default `3`) — degrees of 2D rotation
+  - `saturation` (default `1.05`)
+  - `speed` (default `1.05`, video only) — playback rate, also compresses output duration accordingly
+  - `horizontal_flip` (default `false`)
+  - `contrast` (default `1.05`)
+  - `brightness` (default `1.05`)
+  - `hue_rotate` (default `0`) — degrees
+  - `blur` (default `0`) — pixels
+- `tint_color` (default `"#FF8C00"`), `tint_opacity` (default `0.08`) — subtle color overlay
+- `width` (default `1080`), `height` (default `1920`) — output canvas
+- `duration_ms` — output duration for video; if omitted, `fallback_duration_ms` (default `5000`) is used
+- `object_fit` (`"cover" | "contain" | "fill" | "none" | "scale-down"`, default `"cover"`)
+- `background_color` (default `"#000000"`) — visible when `object_fit` leaves letterboxing
+- `muted` (default `false`), `volume` (default `1`) — audio pass-through on video
+- `output_format` (`"png" | "jpeg" | "webp"`, default `"png"`) — image mode only; video mode always outputs MP4
+
+Video example (camouflage a reused clip):
+
+```bash
+curl -X POST "$VIDFARM_BASE/api/v1/primitives/media/dedupe" \
+  -H "authorization: Bearer $VIDFARM_API_KEY" \
+  -H "content-type: application/json" \
+  -d '{
+    "tracer": "dedupe-2026-07-01-abc",
+    "payload": {
+      "source_media_url": "https://cdn.example.com/reel.mp4",
+      "media_type": "video",
+      "duration_ms": 8500,
+      "effects": {
+        "zoom": 1.05,
+        "tilt": 2,
+        "rotate": -2,
+        "speed": 1.03,
+        "hue_rotate": 4,
+        "horizontal_flip": true
+      },
+      "tint_color": "#00A3FF",
+      "tint_opacity": 0.06
+    }
+  }'
+```
+
+Image example:
+
+```bash
+curl -X POST "$VIDFARM_BASE/api/v1/primitives/media/dedupe" \
+  -H "authorization: Bearer $VIDFARM_API_KEY" \
+  -H "content-type: application/json" \
+  -d '{
+    "tracer": "dedupe-still-01",
+    "payload": {
+      "source_media_url": "https://cdn.example.com/photo.jpg",
+      "media_type": "image",
+      "effects": { "zoom": 1.06, "rotate": -1, "hue_rotate": 8 },
+      "output_format": "webp"
+    }
+  }'
+```

package/SKILL.platform.md

@@ -58,19 +58,23 @@ Query patterns use GSIs on `customerId`, `forkId`, `granteeId`, `slug`, and `sta
 
 ### S3 — composition storage
 
-Bucket per stage. Layout is **ownership-agnostic** — the customerId does not appear in the S3 key. Access control is enforced at the API layer via the DynamoDB permission records.
+Bucket per stage. Layout is **ownership-agnostic** — the customerId does not appear in the S3 key.
 
 ```
 compositions/forks/<forkId>/
 ├── working/
 │   ├── composition.html       # current editor state
 │   ├── composition.json       # current metadata (scenes, captions, viral DNA)
+│   ├── manifest.json          # fork identity + genealogy pointer
 │   └── ghostcut.json          # GhostCut subtitle-removal task state (optional)
 └── versions/<version>/
     ├── composition.html
-    └── composition.json
+    ├── composition.json
+    └── manifest.json          # frozen version manifest
 ```
 
+The `compositions/forks/*` prefix is **public-read** in the bucket resource policy — any client with a `forkId` can fetch `composition.html` / `composition.json` / `manifest.json` directly from S3 without a Lambda proxy hop. The `forkId` is treated as an unguessable bearer token (revoking share = generating a new fork). Write access is still gated at the API by `assertForkAccess(..., "edit" | "publish" | "share" | "delete")`. See `isPublicStorageKey` in `src/services/storage.ts`.
+
 Additional prefixes:
 
 - `renders/vidfarm/<slug>/<render-id>/output.mp4` — published MP4s
@@ -78,7 +82,35 @@ Additional prefixes:
 - `template-assets/<slug>/...` — template media
 - `user-attachments/<customerId>/...` — chat panel uploads (only ownership-keyed area remaining)
 
-Old ownership-keyed composition paths (`compositions/users/<customerId>/forks/...`) were migrated away by `scripts/migrate-compositions-to-ownership-agnostic.ts`. Old `decomposition.json` was renamed to `composition.json` by `scripts/migrate-decomposition-to-composition.ts`.
+Old ownership-keyed composition paths (`compositions/users/<customerId>/forks/...`) were migrated away by `scripts/migrate-compositions-to-ownership-agnostic.ts`. Old `decomposition.json` was renamed to `composition.json` by `scripts/migrate-decomposition-to-composition.ts`. Forks written before the manifest rollout won't have `manifest.json` until their next mutation — reads must tolerate 404.
+
+### manifest.json
+
+Written next to `composition.html` / `composition.json` in both `working/` and `versions/<n>/`. Lets clients traverse fork genealogy and jump between versions without a DynamoDB round-trip.
+
+```json
+{
+  "fork_id": "...",
+  "customer_id": "...",
+  "is_working": true,
+  "version": null,
+  "latest_version": 3,
+  "parent_fork_id": "fork_abc" | null,
+  "parent_version": 2 | null,
+  "source_slug_id": "...",
+  "source_video_id": "..." | null,
+  "visibility": "private" | "unlisted" | "public",
+  "title": "...",
+  "composition_url": "https://.../composition.html",
+  "composition_json_url": "https://.../composition.json",
+  "manifest_url": "https://.../manifest.json",
+  "parent_manifest_url": "https://.../versions/2/manifest.json" | null,
+  "created_at": "...",
+  "updated_at": "..."
+}
+```
+
+Writes are centralized in `writeForkManifest()` in `src/services/fork-manifest.ts`. `snapshotForkVersion()` writes both the version manifest AND refreshes the working manifest (so `latest_version` stays in sync). Every working-only mutation site (create, PUT html, PATCH json, visibility, decompose, ghostcut swap, export) also calls it.
 
 ## Composition model
 
@@ -119,7 +151,7 @@ A composition is a single HTML document plus a JSON sidecar.
 }
 ```
 
-Both files are treated as immutable per version. The working state is mutable.
+All three files (`composition.html`, `composition.json`, `manifest.json`) are treated as immutable per version. The working state is mutable.
 
 ## Composition runtime
 
@@ -287,7 +319,7 @@ Top-level:
 
 Legacy but still active:
 
-- `auto-create-templates/` — extractor prompts for the older template creation flow. Still consumed by `src/cli.ts` (`autocreate-template` command) and `demo/scripts/dev.mjs`. Migrate the CLI before deleting.
+- `auto-create-templates/` — extractor prompts for the older template creation flow. Only `extractor-system-prompt.md` and `production-graph.schema.json` are still live (loaded by `demo/scripts/dev.mjs`); the rest is inert docs kept for reference.
 - `src/account-pages-legacy.ts`, `src/dev-app-legacy.ts` — HTML-string page renderers wrapped by `.tsx` React shells (`account-pages.tsx`, `dev-app.tsx`). Still active.
 
 ## Common failure modes
@@ -302,11 +334,39 @@ Legacy but still active:
 
 - Composition endpoints — `src/app.ts` under `COMPOSITIONS_PREFIX` (~line 6970+)
 - Fork CRUD & permissions — `src/services/serverless-records.ts`, `src/services/fork-access.ts`
-- Storage keys — `src/services/storage.ts`
+- Storage keys + public-read prefix list — `src/services/storage.ts`
+- Fork manifest.json helper — `src/services/fork-manifest.ts`
 - Composition runtime script — `src/composition-runtime.ts`
 - Trackpad Editor — `demo/src/HyperframesStudioEditor.tsx`
+- Editor local-mode bootstrap — `demo/src/dev-mode.ts`
+- Devcli (`vidfarm-devcli`) — `src/cli.ts` (edit-mode fetch + banner), `src/dev-serve.ts` (raw HTTP shim)
 - Auto-decompose logic — `src/hyperframes/composition.ts` (time-slice), `src/services/hyperframes.ts` (smart)
 - Publish flow — `src/app.ts` `publishCompositionToRenderer()`
 - Ghostcut — `src/services/ghostcut.ts`
 - CDK stack — `infra/cdk/lib/vidfarm-serverless-staging-stack.ts`, `infra/cdk/lib/vidfarm-prod-stack.ts`
+
+## Local editor dev loop
+
+`@mevdragon/vidfarm-devcli` (`src/cli.ts` + `src/dev-serve.ts`) pairs a local directory of composition files with the hosted Trackpad Editor so Claude Code, Codex, or a human can edit `composition.html` on disk and see instant preview reload in the browser.
+
+```bash
+# One-shot: fetch composition, start dev-serve, print editor URL.
+vidfarm-devcli <template_id>
+# → downloads composition.html/json + manifest.json into .vidfarm/<template_id>/
+# → listens on http://localhost:4321
+# → prints https://vidfarm.cc/editor/<template_id>?fork=<forkId>&dev=http%3A%2F%2Flocalhost%3A4321
+
+# Advanced: skip fetch, serve an existing directory.
+vidfarm-devcli dev-serve --dir ./my-fork --port 4321
+# Then open the editor with ?dev=1 (or ?dev=host:port / ?dev=<full-url>)
+```
+
+Edit flags: `--port`, `--dir`, `--host`, `--fork`, `--api-key` (or `VIDFARM_API_KEY`), `--share`, `--refetch`.
+
+`dev-serve` behavior:
+- Serves `composition.html` / `composition.json` / `manifest.json` (and `/versions/{n}/…`) with CORS `*`.
+- Accepts `PUT /composition.html` and `PATCH /composition.json`.
+- Watches the dir with `fs.watch`, coalesces bursts, fans out reload events via `GET /_events` SSE.
+
+The editor side lives in `demo/src/dev-mode.ts` — a self-installing module imported at the top of `demo/src/main.tsx`. It reads `?dev=<url>` (persisted to `localStorage.VIDFARM_DEV_SOURCE`), monkey-patches `window.fetch` to rewrite `/api/v1/compositions/{forkId}/*` → `${devSource}/*`, injects a persistent orange banner with an Exit button, and dispatches `vidfarm:dev-reload` on SSE reload events. `HyperframesStudioEditor.tsx` listens for that event and re-runs the composition fetch effect with `cache: "reload"`.
 - Lambdas — `infra/lambda/*.ts`