@mevdragon/vidfarm-devcli 0.1.0 → 0.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mevdragon/vidfarm-devcli",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Developer CLI for running the Vidfarm local template platform.",
   "type": "module",
   "bin": {
@@ -9,7 +9,9 @@
   },
   "files": [
     "dist",
+    "templates/template_0000",
     "README.md",
+    "SKILL.developer.md",
     "PLATFORM_SPEC.md",
     "AWS_REMOTION_HANDOFF.md",
     ".env.example"
@@ -27,9 +29,13 @@
   "scripts": {
     "dev": "tsx watch src/index.ts",
     "dev:cli": "tsx src/cli.ts dev",
+    "deploy:prod-inplace": "bash scripts/deploy-prod-inplace.sh",
+    "rollback:prod-inplace": "bash scripts/rollback-prod-inplace.sh",
     "build": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\" && tsc -p tsconfig.json",
     "start": "node dist/src/index.js",
     "check": "tsc -p tsconfig.json --noEmit",
+    "cdk:synth": "npm run build && npx aws-cdk synth --app 'node dist/infra/cdk/bin/vidfarm-prod.js'",
+    "cdk:deploy": "npm run build && npx aws-cdk deploy --app 'node dist/infra/cdk/bin/vidfarm-prod.js'",
     "prepack": "npm run build"
   },
   "dependencies": {
@@ -53,6 +59,8 @@
     "@types/node": "^24.0.1",
     "@types/react": "^18.3.23",
     "@types/react-dom": "^18.3.7",
+    "aws-cdk-lib": "^2.196.0",
+    "constructs": "^10.4.2",
     "tsx": "^4.19.4",
     "typescript": "^5.8.3"
   }

package/templates/template_0000/README.md

@@ -0,0 +1,121 @@
+# vidfarm_template_0000
+
+Standalone GitHub-distributable package for the Vidfarm `template_0000` starter template.
+
+This package exists for two operational reasons:
+
+- keep the template code in its own private GitHub repo for manual admin review/import
+- preserve the exact checked-in config and build shape the release admin will later promote to shared Remotion AWS and the production Docker image
+
+Developers should treat this repo as an authoring and review unit, not as an authorized deployment unit.
+
+Every new template should keep its source-format research checked in:
+
+- `research/source_notes.md` for notes on the original winning format
+- `research/preview/` for the screenshots or source video the DNA analyzers inspect
+- `src/template-dna.ts` for the generated viral and visual DNA that feed the published template metadata
+
+The production release flow is:
+
+1. developer pushes template code to GitHub
+2. admin reviews the repo and selects a commit from `production`
+3. admin publishes the approved Remotion site bundle to shared AWS
+4. admin imports and activates the approved commit in Vidfarm
+5. admin rebuilds and redeploys the production Docker image
+
+Template authors do not publish directly to shared Remotion Lambda and do not directly promote templates into production Docker.
+
+Production integration settings are checked into `template.config.json`. AI agents and developers should treat that file as the source of truth for:
+
+- project identity
+- `template_id` as the self-issued UUIDv4 platform identifier
+- `slug_id` as the human-readable stable slug
+- GitHub repo target
+- production source branch
+- Remotion region/function/bucket/site/composition settings
+- release control expectations for admin promotion
+
+## Included
+
+- `SKILL.md` for customer AI-agent usage
+- `src/template.ts` for the Vidfarm platform contract
+- `src/remotion/*` for local and cloud video rendering
+- `src/lib/images.ts` for non-cropping portrait normalization
+- `composition.json` sample props for cloud render smoke tests
+
+## Template behavior
+
+`template_0000` is intentionally opinionated because later templates will likely start from it.
+
+- stage 1 operation: `create_slideshow`
+- stage 2 operation: `render_video`
+- `create_slideshow` accepts either legacy `[imagePrompt, caption]` or `[imagePrompt, caption, durationMs]` slide tuples, or structured slide objects with optional `image_prompt_attachments` and `duration_ms`
+- `create_slideshow` also accepts optional `meta_details_prompt` guidance and returns generated `title`, `description`, `pinned_comment`, `location`, and `song` metadata plus the normalized metadata input args
+- slide generation is strict 9:16 with TikTok-safe reserved UI zones
+- finished slide images already include the text overlay
+- the video stage only accepts explicit `slides` input and sequences those finished slide images using per-slide `durationMs`
+- caption placement is center-biased and image-aware, using provider layout analysis first with a local fallback
+- caption styling is restricted to the checked-in starter option lists in `src/style-options.ts`
+
+The starter is optimized to:
+
+- avoid subject cut-off during portrait normalization
+- keep the right-side TikTok action rail clear
+- keep the top tabs area clear
+- keep the bottom caption/audio area clear
+- avoid fake full-width caption panels; if a text background is used, it renders as a tight line chip behind the words only
+
+## Install
+
+```bash
+npm install
+```
+
+## Validate
+
+```bash
+npm run check
+```
+
+## Analyze Template DNA
+
+After you add source notes and preview media, run:
+
+```bash
+vidfarm analyze-viral-dna --template-dir .
+vidfarm analyze-visual-dna --template-dir .
+```
+
+If you scaffold a template with `vidfarm generate-template` and provide `--source-preview-dir`, the CLI will run both analyzers automatically unless `--skip-dna-analysis` is set.
+
+## Shared Remotion AWS
+
+Expected shared infra:
+
+- region: stored in `template.config.json`
+- function: stored in `template.config.json`
+- bucket: stored in `template.config.json`
+
+The only runtime secrets expected from the execution environment are AWS credentials. The production Remotion topology is intentionally checked into `template.config.json`, not spread across `.env` values.
+
+These shared-AWS operations are release-admin tasks. Template developers should not run them against the shared production AWS account.
+
+Release admin create-site:
+
+```bash
+npm run admin:create-site
+```
+
+Release admin cloud render smoke test:
+
+```bash
+npm run admin:render:cloud
+```
+
+Release admin cloud render from a real stage-1 manifest:
+
+```bash
+npm run admin:render:cloud -- --manifest /abs/path/to/template-0000.json
+```
+
+Use the manifest mode when you want the cloud render verification to include the actual composited slide frames with text overlays, not just the static sample props.

package/templates/template_0000/SKILL.md

@@ -0,0 +1,193 @@
+# Template 0000 Skill
+
+Use this template when the customer wants a fast vertical slideshow for TikTok-style distribution, built from a short list of scene prompts and exact overlay text.
+
+Operational rule:
+
+- template developers author and test this template locally
+- only the release admin publishes the approved Remotion site bundle to shared AWS
+- only the release admin promotes the approved template into production Docker
+
+Inputs:
+
+- `slides`: either ordered tuples like `[imagePrompt, overlayText]` or `[imagePrompt, overlayText, durationMs]`, or objects like `{ image_prompt, image_prompt_attachments, caption, duration_ms }`
+- `image_prompt_attachments`: optional public media URLs used as visual reference attachments during image generation
+- `meta_details_prompt`: optional guidance for generated title, description, pinned comment, location, and song metadata
+
+Behavior:
+
+- `create_slideshow` generates exact 9:16 images, preserves the exact overlay text, and outputs finished slide frames plus a manifest
+- `render_video` turns explicit finished slide frames into an auto-advancing vertical MP4
+- reserves space for TikTok UI chrome at the top, right edge, and bottom caption area
+- keeps subjects away from edge crops and avoids cutting off faces, pets, hands, and products
+- prefers centered native-caption placement using image analysis first, with local fallback scoring
+- never uses a full paragraph wash behind captions; when enabled, text backgrounds render as tight chips around the words
+- restricts caption fonts and text background colors to the checked-in starter option lists in `src/style-options.ts`
+
+Allowed caption fonts:
+
+- `source_code_pro`
+- `montserrat`
+- `yesteryear`
+- `dm_serif_display`
+- `abel`
+
+Allowed text background colors:
+
+- `none`
+- `black`
+- `red`
+- `orange`
+- `yellow`
+- `lime_green`
+- `teal`
+- `light_blue`
+- `dark_blue`
+- `violet`
+- `pink`
+- `brown`
+- `dark_green`
+- `blue_gray`
+- `light_gray`
+- `dark_gray`
+
+REST API routes for this template:
+
+- `GET /templates/template_0000`
+- `GET /templates/template_0000/skill`
+- `POST /templates/template_0000/config`
+- `POST /templates/template_0000/operations/create_slideshow`
+- `POST /templates/template_0000/operations/render_video`
+- `GET /templates/template_0000/jobs`
+- `GET /templates/template_0000/jobs/:jobId`
+- `GET /templates/template_0000/jobs/:jobId/logs`
+- `POST /templates/template_0000/jobs/:jobId/cancel`
+
+Shared shell variables:
+
+```bash
+BASE_URL="http://localhost:3000"
+VIDFARM_USER_ID="replace-me"
+VIDFARM_API_KEY="replace-me"
+COMMON_HEADERS=(
+  -H "vidfarm-user-id: ${VIDFARM_USER_ID}"
+  -H "vidfarm-api-key: ${VIDFARM_API_KEY}"
+)
+JSON_HEADERS=(
+  "${COMMON_HEADERS[@]}"
+  -H "content-type: application/json"
+)
+```
+
+Get template metadata:
+
+```bash
+curl "${BASE_URL}/templates/template_0000" \
+  "${COMMON_HEADERS[@]}"
+```
+
+Get the published `SKILL.md` URL contents:
+
+```bash
+curl "${BASE_URL}/templates/template_0000/skill" \
+  "${COMMON_HEADERS[@]}"
+```
+
+Save template config:
+
+```bash
+curl -X POST "${BASE_URL}/templates/template_0000/config" \
+  "${JSON_HEADERS[@]}" \
+  -d '{
+    "config": {
+      "defaultProvider": "openrouter",
+      "textModel": "openai/gpt-4.1-mini",
+      "imageModel": "bytedance-seed/seedream-4.5",
+      "captionFont": "montserrat",
+      "captionBackgroundColor": "none",
+      "renderCompositionId": "template-0000"
+    }
+  }'
+```
+
+Create a slideshow:
+
+```bash
+curl -X POST "${BASE_URL}/templates/template_0000/operations/create_slideshow" \
+  "${JSON_HEADERS[@]}" \
+  -d '{
+    "tracer": "launch-story-001",
+    "payload": {
+      "slides": [
+        ["late night founder at laptop", "launching after hours", 2200],
+        {
+          "image_prompt": "skincare serum bottle on a clean bathroom counter near a window",
+          "caption": "the routine was simpler than i thought",
+          "duration_ms": 2800
+        }
+      ],
+      "meta_details_prompt": "Write native TikTok metadata for a US audience. Keep it curiosity-driven and casual."
+    }
+  }'
+```
+
+Render the final video:
+
+```bash
+curl -X POST "${BASE_URL}/templates/template_0000/operations/render_video" \
+  "${JSON_HEADERS[@]}" \
+  -d '{
+    "tracer": "launch-story-001-render",
+    "payload": {
+      "slides": [
+        {
+          "imageUrl": "https://example.com/slide-1.png",
+          "durationMs": 2200
+        },
+        {
+          "imageUrl": "https://example.com/slide-2.png",
+          "durationMs": 2800
+        }
+      ]
+    }
+  }'
+```
+
+List jobs for this template:
+
+```bash
+curl "${BASE_URL}/templates/template_0000/jobs" \
+  "${COMMON_HEADERS[@]}"
+```
+
+List jobs filtered by tracer and date range:
+
+```bash
+curl "${BASE_URL}/templates/template_0000/jobs?tracer=launch-story-001&start_time=2026-05-17T00:00:00.000Z&end_time=2026-05-18T00:00:00.000Z&limit=20" \
+  "${COMMON_HEADERS[@]}"
+```
+
+Get one job:
+
+```bash
+JOB_ID="job_replace_me"
+
+curl "${BASE_URL}/templates/template_0000/jobs/${JOB_ID}" \
+  "${COMMON_HEADERS[@]}"
+```
+
+Get one job's logs:
+
+```bash
+curl "${BASE_URL}/templates/template_0000/jobs/${JOB_ID}/logs?start_time=2026-05-17T00:00:00.000Z&end_time=2026-05-18T00:00:00.000Z&limit=200" \
+  "${COMMON_HEADERS[@]}"
+```
+
+Cancel one job:
+
+```bash
+curl -X POST "${BASE_URL}/templates/template_0000/jobs/${JOB_ID}/cancel" \
+  "${COMMON_HEADERS[@]}"
+```
+
+Use this template for short-form product explainers, founder clips, launch teasers, and simple storyboarding workflows where speed matters more than deep custom motion design.

package/templates/template_0000/composition.json

@@ -0,0 +1,11 @@
+{
+  "slides": [
+    {
+      "imageUrl": "https://images.unsplash.com/photo-1519389950473-47ba0277781c?auto=format&fit=crop&w=1080&q=80"
+    },
+    {
+      "imageUrl": "https://images.unsplash.com/photo-1520607162513-77705c0f0d4a?auto=format&fit=crop&w=1080&q=80"
+    }
+  ],
+  "secondsPerSlide": 2
+}