@mevdragon/vidfarm-devcli 0.2.11 → 0.2.13

package/readme.secret.md

@@ -0,0 +1,89 @@
+# Secret Admin Provisioning
+
+This file contains the production `SUPERAGENCY_KEY` and an example admin provisioning request.
+
+## Literal `SUPERAGENCY_KEY`
+
+```txt
+24084dsafjl428042454
+```
+
+PUBLIC_BASE_URL="https://vidfarm.cc"
+
+## Provision A User
+
+```bash
+curl -X POST "$PUBLIC_BASE_URL/api/v1/admin/auth/provision-user-account" \
+  -H "content-type: application/json" \
+  -H "x-superagency-key: 24084dsafjl428042454" \
+  --data '{
+    "email": "newuser@example.com",
+    "password": "StrongPassword123",
+    "name": "New User"
+  }'
+```
+
+## Expected Response
+
+```json
+{
+  "customer": {
+    "id": "cus_01jvexample",
+    "email": "newuser@example.com",
+    "name": "New User",
+    "defaultWebhookUrl": null,
+    "isDeveloper": false,
+    "isPaidPlan": true,
+    "about": null,
+    "groupchatUrl": null,
+    "flockposterApiKey": null
+  },
+  "credentials": {
+    "email": "newuser@example.com",
+    "password": "StrongPassword123",
+    "api_key": "vf_key_01jvexample"
+  },
+  "action": "created"
+}
+```
+
+If the email already exists, the same route returns `200` with `"action": "updated"`.
+
+## Demo Account
+
+Email: demo@vidfarm.cc
+Password: VidfarmDemo-4102ff1f64be
+
+## Filming Demo
+
+## Filming VidFarm Tutorial
+
+1. Explain VidFarm & how its Agentic Viral Content Creation (with built-in AI chat or Claude Code/Codex). built for marketing agencies to create content for their clients.
+   show /discover tab and how its always adding more viral templates
+
+Login:
+Email: demo@vidfarm.cc
+Password: VidfarmDemo-4102ff1f64be
+
+2. Setup AI API Key --> bring your own API key is great because it saves you money
+3. Setup Flockposter --> 3rd party tool to automate posting
+4. Establish Profile Settings --> save info about your company, upload logo
+
+SuperLungs - Lung recovery & strengthening app for athletes & smokers
+Practicing Winhoff Breathing Exercises
+
+5. Demo templates:
+
+vidfarm_template_funnychat --> mention how AI cant reliably do this, this is actually a video template. then bulk create 3 pieces of content
+
+shock_reaction_question --> upload mp4 app demo
+
+videogame_prizebox --> show inpaint editor, then bulk create content, slideshows
+
+6. Approve post, share preview --> make sure you also mention we want to put captions and title and pinned comment. also show off the different features like download zip or editor, toggle video/slides
+7. Schedule post --> show email channels, show flockposter channels
+
+8. Show /calendar tab
+9. Show /library tab --> can talk to AI to bulk schedule
+10. Show /job-runs tab --> explain tracers
+11. Show /settings wallet tab --> explain how this is way cheaper than any option out there

package/templates/vidfarm_template_0000/README.md

@@ -0,0 +1,106 @@
+# vidfarm_template_0000
+
+Standalone GitHub-distributable package for the Vidfarm `template_0000` starter template.
+
+This package exists to give third-party developers a concrete example of the Vidfarm template contract.
+
+Developers should treat this repo as an authoring and review unit.
+The canonical template implementation lives in `src/template.ts`; the build emits `src/template.js` for runtime loading.
+
+When a template is ready, it is handed off for Vidfarm admin review and approval before it becomes available on the hosted platform.
+
+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
+
+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
+- the template module path, which should be the TypeScript source entrypoint `src/template.ts`
+- the local Remotion composition settings used by the starter template
+
+## Required template contract
+
+Every new template copied from `template_0000` should keep the current required `defineTemplate(...)` contract intact.
+
+- `id`, `slugId`, and `version`
+- `about.title` and `about.description`
+- `about.viral_dna`, `about.visual_dna`, `about.preview_media`, and `about.link_to_original`
+- `about.links_to_inspiration`, as a string array of source/inspiration URLs
+- `about.sound`, with `sound_title` and `sound_url`
+- `about.proposal_generator`, which teaches a director or agent how to turn business context into template-native post proposals
+- `about.skeleton_prompt`, which gives directors and agents a template-native fill-in-the-blanks prompt scaffold
+- `about.sample_prompts`, which shows multiple concrete high-signal prompts for the template
+- `configSchema`
+- at least one operation with a `smokeTestPayload`
+- a matching workflow implementation in `jobs`
+- a template-local `SKILL.md`
+
+The starter already ships with example `proposal_generator`, `skeleton_prompt`, and `sample_prompts` values in `src/template.ts`. When you adapt this template, replace them with instructions and examples that fit the new format instead of leaving the starter language in place.
+
+## Included
+
+- `SKILL.md` for customer AI-agent usage
+- `src/template.ts` for the Vidfarm platform contract
+- `src/remotion/*` for local video rendering
+- `src/lib/images.ts` for non-cropping portrait normalization
+- `composition.json` sample props for local render 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 defaults to the platform caption standard in `src/style-options.ts`, including TikTok Sans SemiBold, Montserrat SemiBold, Source Code Pro Bold, Yesteryear, Georgia-style Bold, Abel, and the canonical TikTok text background colors
+- custom caption styling is supported with `captionFont: "custom"` plus custom font/color config fields when the user intentionally wants text outside the standard
+
+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
+- avoid web-style caption shadows; native white captions use centered black halo layers around the glyphs, not a heavy downward/rightward drop shadow
+
+## 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.
+
+After DNA analysis, review and customize the remaining human-authored metadata before calling the template ready:
+
+- refresh `about.proposal_generator`
+- refresh `about.skeleton_prompt`
+- refresh `about.sample_prompts`
+- update `SKILL.md` to match the actual operations and payload shapes
+- run `vidfarm validate-template --template-id <slug-or-id>` and at least one real local job

package/templates/vidfarm_template_0000/SKILL.md

@@ -0,0 +1,266 @@
+# 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
+- the hosted platform later runs the approved template behind the standard Vidfarm API wrapper
+- a Vidfarm admin reviews and approves the template before it is made available in production
+
+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
+- when chaining operations, pass `result.renderVideoInput` from `create_slideshow` into `render_video` without re-encoding or HTML-escaping the slide URLs
+- 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
+- renders colored text backgrounds as per-line inline highlight chips measured from each wrapped line's glyph bounds, not from the caption block width
+- renders native white caption contrast as a radial black halo/outline around the full multiline text block, not as a large one-direction web drop shadow
+- restricts caption fonts and text background colors to the platform caption standard in `src/style-options.ts`
+
+AI dependency contract for agents:
+
+- the current Vidfarm template standard does not have a first-class `dependencies` field, so this section is the authoritative dependency declaration for this template
+- `defaultProvider`, `textModel`, and `imageModel` are config values, not a validated provider-model matrix
+- agents should keep provider and model choices inside the combinations listed below unless they are intentionally extending runtime support
+
+Documented provider-model combinations for this template:
+
+- `openai`
+  models:
+  `image`: `gpt-image-1`, `gpt-image-2`
+  `text` and `layout_analysis`: `gpt-5.4`
+  planned but not wired here: `sora-2`
+- `gemini`
+  models:
+  `image`: `gemini-3.1-flash-image-preview`, `gemini-2.5-flash-image`
+  `text` and `layout_analysis`: `gemini-3.1-flash-lite`, `gemini-2.5-flash-lite`
+  planned but not wired here: `veo-3.0-generate-001`
+- `openrouter`
+  models:
+  `text` and `layout_analysis`: `qwen/qwen3.6-flash`
+  aspirational image models: `bytedance/seedance-2.0`, `bytedance-seed/seedream-4.5`
+
+Runtime caveats:
+
+- `openrouter` text and layout-analysis calls work through the OpenRouter chat-completions path
+- `openrouter` image generation is not a first-class adapter path in the current runtime, so do not assume `seedance-2.0` or `seedream-4.5` will work end to end without provider-runtime changes
+- OpenAI image generation in the current runtime does not support `image_prompt_attachments`; Gemini is the safest path when reference-image attachments matter
+- OpenAI image generation does not expose an exact native `9:16` output size in the current API. For `template_0000`, use portrait output plus explicit `9:16` framing instructions, then preserve composition with contain-plus-blur normalization instead of crop-zooming.
+- this template does not expose a video-generation operation, so `sora-2` and `veo-3.0-generate-001` are documented here for future dependency planning only
+
+Allowed caption fonts:
+
+- `tiktok_sans_semibold`
+- `montserrat_semibold`
+- `source_code_pro_bold`
+- `georgia_bold`
+- `abel`
+- `yesteryear`
+- `custom`
+- legacy alias: `montserrat`
+- legacy alias: `source_code_pro`
+
+Caption font labels:
+
+- TikTok Sans SemiBold
+- Montserrat SemiBold
+- Source Code Pro Bold
+- Yesteryear
+- Georgia-style Bold, bundled as Libre Baskerville
+- Abel
+- Custom, using `customCaptionFontFamily`, optional `customCaptionFontWeight`, and optional `customCaptionFontAssetPath`
+
+Deprecated starter-only font IDs:
+
+- `source_code_pro`
+- `montserrat`
+- `dm_serif_display`
+
+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`
+
+Typical 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[@]}"
+```
+
+The metadata response includes free-form `price_lines`. For actual billed numbers, read the job status response, which returns totals under `billing`.
+
+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": "tiktok_sans_semibold",
+      "captionBackgroundColor": "none",
+      "renderCompositionId": "template-0000"
+    }
+  }'
+```
+
+Custom caption styling:
+
+```json
+{
+  "config": {
+    "captionFont": "custom",
+    "customCaptionFontFamily": "My Brand Font",
+    "customCaptionFontWeight": 700,
+    "customCaptionFontAssetPath": "assets/MyBrandFont-Bold.ttf",
+    "customCaptionTextColorHex": "#F7D7E9",
+    "customCaptionBackgroundColorHex": "#000000"
+  }
+}
+```
+
+Use custom caption styling only when the user intentionally wants text outside the platform caption standard. Prefer bundled template assets for `customCaptionFontAssetPath`; if no asset path is provided or found, rendering falls back to the runtime text renderer for the declared family.
+
+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/vidfarm_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
+}