@mevdragon/vidfarm-devcli 0.1.0 → 0.2.1

package/SKILL.developer.md

@@ -0,0 +1,258 @@
+---
+name: vidfarm-developer
+description: Build and extend Vidfarm templates as a third-party developer. Use this when the task is to create or modify a template, add or adjust template operations, improve local template testing, wire AI generation through the developer's own provider keys, or document the external developer workflow. Do not use this skill for platform internals, shared AWS infrastructure, admin release flow, or production runtime changes.
+---
+
+# Vidfarm Third-Party Developer
+
+This skill is for third-party template developers authoring Vidfarm templates locally.
+
+Scope this skill to:
+
+- creating a new template
+- extending an existing template under `templates/*`
+- adding or refining template operations and jobs
+- improving local template authoring workflow
+- wiring template behavior to the developer's own AI provider keys
+- validating template behavior through the local CLI and API
+
+Do not use this skill for:
+
+- platform auth, billing, storage, webhook, or database internals
+- developer console work under `/dev`
+- production Docker or deployment changes
+- shared AWS or release-admin workflows
+- cloud Remotion publishing or cloud render setup
+
+For third-party developers, Remotion is local. Do not require cloud Remotion credentials or shared AWS details in this skill.
+
+## Required Developer Env
+
+Third-party developers should only need their own API credentials and Vidfarm API auth.
+
+Typical `.env`:
+
+```env
+GEMINI_API_KEY=""
+OPENAI_API_KEY=""
+OPENROUTER_API_KEY=""
+PERPLEXITY_API_KEY=""
+
+VIDFARM_USER_ID=""
+VIDFARM_API_KEY=""
+```
+
+Notes:
+
+- at least one AI provider key is usually enough
+- `VIDFARM_USER_ID` and `VIDFARM_API_KEY` are needed when calling the Vidfarm API directly
+- do not ask third-party developers for platform secrets like `ENCRYPTION_SECRET`, `API_KEY_SALT`, `WEBHOOK_SECRET`, admin emails, S3 config, or generic AWS credentials
+- do not ask third-party developers for `REMOTION_AWS_ACCESS_KEY_ID` or `REMOTION_AWS_SECRET_ACCESS_KEY`
+
+## First Read
+
+Read these files first when working on a template:
+
+1. [GETTING_STARTED.developers.md](/Users/localghost/Projects/OfficeX/OfficeX/ZoomGTM/vidfarm/GETTING_STARTED.developers.md)
+2. [templates/template_0000/SKILL.md](/Users/localghost/Projects/OfficeX/OfficeX/ZoomGTM/vidfarm/templates/template_0000/SKILL.md)
+3. [templates/template_0000/src/template.ts](/Users/localghost/Projects/OfficeX/OfficeX/ZoomGTM/vidfarm/templates/template_0000/src/template.ts)
+4. [src/template-sdk.ts](/Users/localghost/Projects/OfficeX/OfficeX/ZoomGTM/vidfarm/src/template-sdk.ts)
+5. [src/cli.ts](/Users/localghost/Projects/OfficeX/OfficeX/ZoomGTM/vidfarm/src/cli.ts)
+
+If the task is narrow, read only the template files and CLI slice relevant to that task.
+
+## Mental Model
+
+A template is an internal module loaded by Vidfarm, but third-party developers should work at the template layer, not the platform layer.
+
+The normal workflow is:
+
+1. define template metadata and schemas
+2. expose one or more operations
+3. implement the job workflows behind those operations
+4. test locally through the Vidfarm CLI and REST API
+5. iterate until the template can be rerun reliably
+
+Every public template action should remain async and job-based. Prefer fitting new behavior into the existing operation and job pattern instead of inventing one-off synchronous endpoints.
+
+## When Adding A New Template
+
+Follow this checklist:
+
+1. create a new folder under `templates/template_<nnnn>/`
+2. put template code in that folder, not under `src/*`
+3. export `defineTemplate({...})`
+4. define:
+   - `id`
+   - `slugId`
+   - `version`
+   - `about`
+   - `configSchema`
+   - `operations`
+   - `jobs`
+5. add a template-local `SKILL.md`
+6. put source research in `research/source_notes.md`
+7. put source screenshots or videos in `research/preview/`
+8. add `smokeTestPayload` for every operation
+9. verify the template locally end to end
+
+Use [templates/template_0000/src/template.ts](/Users/localghost/Projects/OfficeX/OfficeX/ZoomGTM/vidfarm/templates/template_0000/src/template.ts) as the baseline pattern.
+
+## Template Contract
+
+Each template should expose operations, not ad hoc endpoints.
+
+Use this shape:
+
+```ts
+export const myTemplate = defineTemplate({
+  id: "123e4567-e89b-42d3-a456-426614174000",
+  slugId: "ugc_hooks_v1",
+  version: "1.0.0",
+  about: {
+    title: "UGC Hooks V1",
+    description: "Generate hooks, previews, and final render inputs.",
+    viral_dna: "Fast creator-style hooks with simple repeatable structure.",
+    visual_dna: "Presentation-led mobile layouts with recognizable creator-native framing.",
+    preview_media: ["https://cdn.example.com/templates/ugc_hooks_v1/about/preview-01.jpg"],
+    link_to_original: "https://www.tiktok.com/@example/video/1234567890"
+  },
+  configSchema: z.object({
+    defaultProvider: z.enum(["openai", "openrouter", "gemini", "perplexity"]).default("openai")
+  }),
+  operations: {
+    scaffold: {
+      description: "Generate a script scaffold.",
+      inputSchema: z.object({
+        topic: z.string()
+      }),
+      workflow: "scaffoldWorkflow",
+      providerHint: "openai",
+      webhookSupport: true,
+      smokeTestPayload: {
+        topic: "creator hooks"
+      }
+    }
+  },
+  jobs: {
+    async scaffoldWorkflow(ctx, input) {
+      return {
+        progress: 1,
+        output: {}
+      };
+    }
+  }
+});
+```
+
+Keep these roles clear:
+
+- `id` is the UUID-style template identifier
+- `slugId` is the human-readable stable identifier
+- `operations` define the public API
+- `jobs` implement the actual work
+
+## Local Workflow
+
+Preferred local third-party developer workflow:
+
+```bash
+npx @mevdragon/vidfarm-devcli dev --port 3310 --reset
+npx @mevdragon/vidfarm-devcli session
+npx @mevdragon/vidfarm-devcli validate-template --template-id template_0000
+```
+
+That CLI should be the default path because it:
+
+- boots the local API and worker
+- provisions local state automatically
+- creates a local developer session
+- seeds provider keys from local env vars when present
+- uses local Remotion rendering
+
+For third-party developers, local rendering is the default and expected path. Do not document or require cloud Remotion setup here.
+
+Reset local state when needed:
+
+```bash
+rm -rf .vidfarm/local
+npx @mevdragon/vidfarm-devcli dev --port 3310 --reset
+```
+
+## Provider Usage
+
+Templates should prefer the Vidfarm provider abstractions already available in context.
+
+Rules:
+
+- use the configured provider path instead of hardcoding one provider everywhere
+- let templates work with whichever supported provider key the developer actually has
+- keep prompts and model choices configurable when useful
+- avoid requiring multiple provider accounts unless the template genuinely needs them
+
+If a task only needs image generation, do not force extra model providers for text or research.
+
+## Storage Namespaces
+
+Use the built-in storage namespace conventions instead of inventing one-off key layouts.
+
+Current namespaces:
+
+- `user/:user_id/*` for user-owned uploaded assets
+- `developer/:user_id/*` for developer-scoped authoring assets or scratch files
+- `templates/:template_id/users/:user_id/jobs/:job_id/*` for template job artifacts
+- `templates/:template_id/about/*` for template about-page media
+
+Rules:
+
+- keep user uploads under the `user/` namespace
+- keep developer-only working files under the `developer/` namespace
+- keep generated job outputs under the template job namespace
+- do not scatter files across arbitrary top-level prefixes
+- prefer the shared storage helpers over handwritten string concatenation for new paths
+
+## API Usage
+
+When testing through the API, use:
+
+- `vidfarm-user-id`
+- `vidfarm-api-key`
+
+The template-local `SKILL.md` should show the concrete routes and example payloads for that template.
+
+## Validation Checklist
+
+After changes, validate with as many of these as apply:
+
+1. `npm run check`
+2. `npm run build`
+3. `npx @mevdragon/vidfarm-devcli validate-template --template-id <templateIdOrSlug>`
+4. run the template locally through the CLI session
+5. save template config if the template exposes config
+6. launch a real job
+7. poll job status and logs
+8. inspect produced artifacts
+
+If you changed slideshow or text-overlay behavior, also validate:
+
+1. output images are the expected aspect ratio
+2. captions remain readable and do not clip
+3. final local video output matches expected pacing and framing
+
+## What To Avoid
+
+- asking third-party developers for platform secrets
+- mixing admin release instructions into template authoring guidance
+- requiring cloud Remotion setup for normal template work
+- adding one-off custom endpoints when an operation already fits the job
+- hardcoding a developer's personal provider choice into template logic
+- omitting `SKILL.md` or `smokeTestPayload`
+
+## Output Style For Vidfarm Work
+
+When reporting back after Vidfarm template changes:
+
+- name the template changed
+- mention the operation or workflow affected
+- state how you verified it locally
+- call out any remaining gap such as mocked provider responses or unexercised optional paths