@mevdragon/vidfarm-devcli 0.2.8 → 0.2.10

package/templates/vidfarm_template_0000/README.md

@@ -1,100 +0,0 @@
-# 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.proposal_generator`, which teaches a director or agent how to turn business context into template-native post proposals
-- `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` 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 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.
-
-After DNA analysis, review and customize the remaining human-authored metadata before calling the template ready:
-
-- refresh `about.proposal_generator`
-- 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

@@ -1,225 +0,0 @@
-# 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
-- restricts caption fonts and text background colors to the checked-in starter option lists 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:
-
-- `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`
-
-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[@]}"
-```
-
-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/vidfarm_template_0000/composition.json

@@ -1,11 +0,0 @@
-{
-  "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
-}

package/templates/vidfarm_template_0000/package.json

@@ -1,27 +0,0 @@
-{
-  "name": "vidfarm_template_0000",
-  "version": "1.0.0",
-  "private": true,
-  "description": "Standalone Vidfarm template_0000 starter project for local template authoring.",
-  "type": "module",
-  "scripts": {
-    "check": "tsc -p tsconfig.json --noEmit",
-    "build": "tsc -p tsconfig.json",
-    "studio": "remotion studio src/remotion/index.tsx"
-  },
-  "dependencies": {
-    "@remotion/bundler": "4.0.355",
-    "@remotion/cli": "4.0.355",
-    "@remotion/renderer": "4.0.355",
-    "react": "^18.3.1",
-    "react-dom": "^18.3.1",
-    "remotion": "4.0.355",
-    "sharp": "^0.34.2"
-  },
-  "devDependencies": {
-    "@types/node": "^24.0.1",
-    "@types/react": "^18.3.23",
-    "@types/react-dom": "^18.3.7",
-    "typescript": "^5.8.3"
-  }
-}

package/templates/vidfarm_template_0000/research/preview/.gitkeep

@@ -1 +0,0 @@
-

package/templates/vidfarm_template_0000/research/source_notes.md

@@ -1,7 +0,0 @@
-# Source Notes
-
-- original format URL:
-- creator/account:
-- why it wins:
-- what must survive adaptation:
-- what can change for new brands:

package/templates/vidfarm_template_0000/src/lib/images.js

@@ -1,202 +0,0 @@
-import sharp from "sharp";
-export async function normalizeToPortraitFrame(input, target = { width: 1080, height: 1920 }) {
-    const buffer = Buffer.isBuffer(input) ? input : Buffer.from(input);
-    const oriented = sharp(buffer, { density: 144 }).rotate();
-    const trimmed = await trimFlatBorders(oriented);
-    const targetAspect = target.width / target.height;
-    const shouldPreserveFraming = await isCloseToAspect(trimmed, targetAspect, 0.025);
-    const cropped = shouldPreserveFraming ? trimmed : await cropToActiveImageRegion(trimmed);
-    const normalized = await resizeWithBlurredContain(cropped, target, targetAspect);
-    return {
-        bytes: normalized,
-        contentType: "image/png",
-        width: target.width,
-        height: target.height
-    };
-}
-async function resizeWithBlurredContain(image, target, targetAspect) {
-    const metadata = await image.metadata();
-    const width = metadata.width ?? 0;
-    const height = metadata.height ?? 0;
-    if (!width || !height) {
-        return image
-            .resize(target.width, target.height, {
-            fit: "cover",
-            position: sharp.strategy.attention
-        })
-            .png()
-            .toBuffer();
-    }
-    const aspect = width / height;
-    if (Math.abs(aspect - targetAspect) <= 0.015) {
-        return image
-            .resize(target.width, target.height, {
-            fit: "fill"
-        })
-            .png()
-            .toBuffer();
-    }
-    const foreground = await image
-        .clone()
-        .resize(target.width, target.height, {
-        fit: "contain",
-        background: { r: 0, g: 0, b: 0, alpha: 0 }
-    })
-        .png()
-        .toBuffer();
-    const background = await image
-        .clone()
-        .resize(target.width, target.height, {
-        fit: "cover",
-        position: sharp.strategy.attention
-    })
-        .blur(20)
-        .modulate({ brightness: 0.92, saturation: 0.9 })
-        .png()
-        .toBuffer();
-    return sharp(background)
-        .composite([{ input: foreground }])
-        .png()
-        .toBuffer();
-}
-async function isCloseToAspect(image, targetAspect, tolerance) {
-    const metadata = await image.metadata();
-    const width = metadata.width ?? 0;
-    const height = metadata.height ?? 0;
-    if (!width || !height) {
-        return false;
-    }
-    return Math.abs(width / height - targetAspect) <= tolerance;
-}
-async function trimFlatBorders(image) {
-    const metadata = await image.metadata();
-    const sourceWidth = metadata.width ?? 0;
-    const sourceHeight = metadata.height ?? 0;
-    if (!sourceWidth || !sourceHeight || sourceWidth < 3 || sourceHeight < 3) {
-        return image;
-    }
-    const { data, info } = await image
-        .clone()
-        .trim({ threshold: 16 })
-        .png()
-        .toBuffer({ resolveWithObject: true });
-    const widthRatio = info.width / sourceWidth;
-    const heightRatio = info.height / sourceHeight;
-    if (widthRatio > 0.985 && heightRatio > 0.985) {
-        return image;
-    }
-    return sharp(data).rotate();
-}
-async function cropToActiveImageRegion(image) {
-    const metadata = await image.metadata();
-    const sourceWidth = metadata.width ?? 0;
-    const sourceHeight = metadata.height ?? 0;
-    if (!sourceWidth || !sourceHeight) {
-        return image;
-    }
-    const sampleWidth = 96;
-    const sampleHeight = 170;
-    const sample = await image
-        .clone()
-        .resize(sampleWidth, sampleHeight, { fit: "fill" })
-        .grayscale()
-        .raw()
-        .toBuffer();
-    const bounds = detectActiveBounds(sample, sampleWidth, sampleHeight);
-    if (!bounds) {
-        return image;
-    }
-    const left = Math.max(0, Math.floor((bounds.left / sampleWidth) * sourceWidth));
-    const top = Math.max(0, Math.floor((bounds.top / sampleHeight) * sourceHeight));
-    const width = Math.min(sourceWidth - left, Math.max(1, Math.ceil((bounds.width / sampleWidth) * sourceWidth)));
-    const height = Math.min(sourceHeight - top, Math.max(1, Math.ceil((bounds.height / sampleHeight) * sourceHeight)));
-    return image.extract({ left, top, width, height });
-}
-function detectActiveBounds(sample, width, height) {
-    const rowActivity = new Array(height).fill(0);
-    const colActivity = new Array(width).fill(0);
-    for (let y = 0; y < height; y += 1) {
-        for (let x = 0; x < width; x += 1) {
-            const index = y * width + x;
-            const current = sample[index] ?? 0;
-            const left = x > 0 ? sample[index - 1] ?? current : current;
-            const up = y > 0 ? sample[index - width] ?? current : current;
-            const right = x < width - 1 ? sample[index + 1] ?? current : current;
-            const down = y < height - 1 ? sample[index + width] ?? current : current;
-            const energy = Math.abs(current - left) +
-                Math.abs(current - right) +
-                Math.abs(current - up) +
-                Math.abs(current - down);
-            rowActivity[y] += energy;
-            colActivity[x] += energy;
-        }
-    }
-    const smoothedRows = smoothSeries(rowActivity.map((value) => value / width), 9);
-    const smoothedCols = smoothSeries(colActivity.map((value) => value / height), 7);
-    const rowBounds = findActiveRange(smoothedRows, Math.round(height * 0.18));
-    const colBounds = findActiveRange(smoothedCols, Math.round(width * 0.16));
-    if (!rowBounds || !colBounds) {
-        return null;
-    }
-    const topMargin = rowBounds.start / height;
-    const bottomMargin = (height - rowBounds.end - 1) / height;
-    const leftMargin = colBounds.start / width;
-    const rightMargin = (width - colBounds.end - 1) / width;
-    const croppedWidth = colBounds.end - colBounds.start + 1;
-    const croppedHeight = rowBounds.end - rowBounds.start + 1;
-    const croppedAreaRatio = (croppedWidth * croppedHeight) / (width * height);
-    const significantMargins = topMargin > 0.11 || bottomMargin > 0.11 || leftMargin > 0.08 || rightMargin > 0.08;
-    if (!significantMargins && croppedAreaRatio > 0.9) {
-        return null;
-    }
-    return {
-        left: colBounds.start,
-        top: rowBounds.start,
-        width: croppedWidth,
-        height: croppedHeight
-    };
-}
-function findActiveRange(values, minSpan) {
-    const mean = values.reduce((sum, value) => sum + value, 0) / Math.max(values.length, 1);
-    const max = values.reduce((best, value) => Math.max(best, value), 0);
-    if (max <= 0) {
-        return null;
-    }
-    const threshold = mean + (max - mean) * 0.18;
-    let start = 0;
-    while (start < values.length && values[start] < threshold) {
-        start += 1;
-    }
-    let end = values.length - 1;
-    while (end >= 0 && values[end] < threshold) {
-        end -= 1;
-    }
-    if (start >= end) {
-        return null;
-    }
-    const desiredSpan = Math.max(minSpan, end - start + 1);
-    const extra = desiredSpan - (end - start + 1);
-    const expandStart = Math.floor(extra / 2);
-    const expandEnd = extra - expandStart;
-    start = Math.max(0, start - expandStart - 4);
-    end = Math.min(values.length - 1, end + expandEnd + 4);
-    return { start, end };
-}
-function smoothSeries(values, radius) {
-    return values.map((_, index) => {
-        let total = 0;
-        let count = 0;
-        for (let offset = -radius; offset <= radius; offset += 1) {
-            const value = values[index + offset];
-            if (value === undefined) {
-                continue;
-            }
-            total += value;
-            count += 1;
-        }
-        return total / Math.max(count, 1);
-    });
-}
-function clamp(value, min, max) {
-    return Math.min(Math.max(value, min), max);
-}