@mevdragon/vidfarm-devcli 0.2.2 → 0.2.3

package/GETTING_STARTED.developers.md

@@ -1,178 +1,87 @@
-# Vidfarm Third-Party Developer Guide
+# Vidfarm Developers
 
-This guide is for external developers building Vidfarm templates locally.
+## Interview Phase
 
-It covers:
+Prepare for your Interview:
 
-- the local setup
-- the template contract
-- the local CLI workflow
-- the minimum hosted-platform context you need
+1. Browse the Winning Formats Gallery of viral TikTok videos here. These are samples of what you'd be recreating for customers:
+   https://winning-formats-gallery-tiktok.cloud.zoomgtm.com/
 
-It does not cover platform internals, admin release flow, or cloud infrastructure.
+2. Setup OpenAI Codex on your computer with free tier. This is your primary AI coding agent (really good to know, even for future jobs)
+   https://developers.openai.com/codex/cli
+   https://www.youtube.com/watch?v=GJsx_FuiwNg
 
-## Local Setup
+3. Setup Remotion Skill on your computer. Codex will handle all the coding work, you just need to be able to get it to render the output videos/images. no need for suno, just image gen is enough.
+   https://www.youtube.com/watch?v=Xdy1vkhSz-M
 
-1. Create a working folder for your template project.
-2. Install the CLI from npm.
-3. Create a local `.env` from `.env.example`.
-4. Add at least one AI provider key.
+4. You’ll need to acquire an ai api key that can generate images at least. There’s many free and paid ones out there. Part of the skills test is to be resourceful and find it so you can test with (hint: check huggingface, openrouter, and ask codex to suggest others). You will not be penalized for using a weaker free ai
 
-Typical `.env`:
+5. Once you are ready, request the interview with @zoom_gtm and he will give you the skills test, gemini api key, and invite to first week trial run hands on helping customers (you will be paid for your time). You'd be recreating from the winning formats gallery
 
-```env
-GEMINI_API_KEY=""
-OPENAI_API_KEY=""
-OPENROUTER_API_KEY=""
-PERPLEXITY_API_KEY=""
-```
+The skills test:
 
-Start the local runtime:
+try to build your own workflow in VSCode + Codex cli + prompt.md files to generate a winning template. It should be easy to re-run your template to generate infinite content of that type. You may ask codex to explain what I mean
 
-```bash
-npx @mevdragon/vidfarm-devcli dev --port 3310 --reset
-```
+## Pre-Setup for Skills Test
 
-This starts:
+Hello Creative Directors! You can
 
-- the local Vidfarm API
-- the local worker
-- local SQLite state
-- local filesystem-backed media storage
-- local Remotion rendering when your template uses Remotion
+1. Create a Github account and setup SSH key so you can save your work & login on github CLI (ask codex how):
+   https://github.com
 
-## Local Session
+2. Create an NPM account and login on npm CLI (ask codex how):
+   https://www.npmjs.com
 
-Run:
+3. DM me your github username & npm username. congrats! you are a developer now
 
-```bash
-npx @mevdragon/vidfarm-devcli session
-```
+4. Make sure you are familiar with codex & api keys prepared and have tried all of the above. I will provide a gemini ai api key for the skills test.
 
-This prints a reusable local session so you can test the API with `curl` or your own scripts.
+MAKE SURE YOU ARE PREPARED. If I have to babysit you during the call, I will immediatlely end the interview early to not waste anyones time.
 
-## Generate A Starter Template
+5. Final step, schedule your 1:1 skills test interview. do not book time until you have finished prior steps.
 
-To scaffold a new template:
+https://calendly.com/zoom-gtm/creative-director-interviews
 
-```bash
-npx @mevdragon/vidfarm-devcli generate-template \
-  --slug-id template_0001 \
-  --template-dir ./templates/template_0001
-```
+## Setup for Job
 
-That scaffold includes:
+0. Tell your manager your email so he can whitelist you access to Vidfarm. After he confirms you have access, login at https://vidfarm.cloud.zoomgtm.com
 
-- template source files
-- a template-local `SKILL.md`
-- `research/source_notes.md`
-- `research/preview/`
-- `src/template-dna.ts`
+1. Open VSCode in a new project called "Vidfarm-Developer"
 
-If preview media is present, the scaffold can also help generate `viral_dna` and `visual_dna`.
+2. Open terminal and login to github cli and npm cli (ask ai/codex if you need help). ask your manager if they gave you npm access to "vidfarm-devcli" yet.
 
-## Validate Your Template
+3. Open Codex cli in terminal, with /permissions set to "Full Access"
 
-Use the CLI before handing a template off:
+4. Install the private skill by copying it from https://vidfarm.cloud.zoomgtm.com/settings in "Developer SKILL.md" button and pasting it into the below prompt for codex.
 
-```bash
-npx @mevdragon/vidfarm-devcli validate-template --template-id template_0000
+```txt
+Please take this agent skill and install it locally. Then install the vidfarm-devcli from npm, ask me for the otp if need, I will enter it. Here is the agent skill: [pasted]
 ```
 
-You should also run real local jobs for the operations you added and inspect the results.
-
-## Template Contract
-
-Vidfarm expects templates to fit a consistent contract.
-
-Each template should define:
-
-- `id`
-- `slugId`
-- `version`
-- `about`
-- `configSchema`
-- `operations`
-- `jobs`
-
-The important idea is:
-
-- `operations` are the public actions
-- `jobs` do the actual work
-- every meaningful action should fit the async job pattern
-
-Each operation should include a `smokeTestPayload`.
-
-Each template should also include:
-
-- a template-local `SKILL.md`
-- `about.viral_dna`
-- `about.visual_dna`
-- `about.preview_media`
-- `about.link_to_original` when relevant
-
-## How The Hosted Platform Uses Your Template
-
-The hosted platform loads templates behind a standard wrapper.
-
-From the caller's perspective, templates are used through routes like:
+5. Create a .env file at folder root with your AI API KEY. You need at least 1 of 3 and it doesn't matter which. We recommend Gemini. Ask your manager for an AI API key.
 
-- `GET /api/v1/templates/:templateId`
-- `GET /api/v1/templates/:templateId/skill`
-- `POST /api/v1/templates/:templateId/config`
-- `POST /api/v1/templates/:templateId/operations/:operationName`
-- `GET /api/v1/templates/:templateId/jobs/:jobId`
-- `GET /api/v1/templates/:templateId/jobs/:jobId/logs`
-
-This means your template should focus on:
-
-- clear metadata
-- strong input schemas
-- repeatable workflow logic
-- useful job output
-
-Avoid building custom standalone HTTP APIs inside the template.
-
-## Review And Approval
-
-Finishing a template locally does not make it live automatically.
-
-The expected flow is:
-
-1. build and validate the template locally
-2. hand off the template source for review
-3. wait for Vidfarm admin approval before the template is made available on the hosted platform
-
-This is the key production boundary external developers need to understand. Your job is to produce a clean, repeatable template package that passes review.
-
-## Hosted Auth Context
-
-When you call a hosted Vidfarm API directly, authenticated requests use:
-
-- `vidfarm-user-id`
-- `vidfarm-api-key`
-
-Those values come from Vidfarm user auth and settings.
-
-For local development, the CLI session command handles this for you by printing a seeded local session.
+```.env
+GEMINI_API_KEY="______"
+OPENAI_API_KEY="______"
+OPENROUTER_API_KEY="______"
+```
 
-## Remotion
+6. Extend that .env file with another secret VIDFARM_API_KEY, you can get it at https://vidfarm.cloud.zoomgtm.com/settings
 
-For third-party template authors, Remotion is local-only in this workflow.
+```.env
+VIDFARM_API_KEY="_______"
+```
 
-If your template uses Remotion:
+6. Create a new folder called `src/`, this is where we are going to do most of our development work.
 
-- build it locally
-- validate it locally
-- keep the template code compatible with local CLI execution
+7. Tell codex to:
 
-You do not need shared cloud Remotion infrastructure details to author a template.
+```txt
+use the vidfarm-devcli to copy-reference-template into src/vidfarm_template_0000 so i can view it as example
+```
 
-## Recommended Reading
+That will populate with a reference folder of what a template code looks like. We are going to create a new template.
 
-Start with:
+8. Create a new folder beside src called `drafts/` which is where we will put messy files when needed.
 
-1. `README.md`
-2. `SKILL.developer.md`
-3. `templates/template_0000/SKILL.md`
-4. `templates/template_0000/src/template.ts`
+9. Now find an easy winning format from https://winning-formats-gallery-tiktok.cloud.zoomgtm.com/ and save the image to your drafts/ folder. then tell Codex to look at that image (right click, copy relative path, paste to codex), then tell codex please make a new template based on the image.

package/README.md

@@ -29,9 +29,11 @@ Useful commands:
 npx @mevdragon/vidfarm-devcli dev --port 3310 --reset
 npx @mevdragon/vidfarm-devcli session
 npx @mevdragon/vidfarm-devcli validate-template --template-id template_0000
-npx @mevdragon/vidfarm-devcli generate-template --slug-id template_0001 --template-dir ./templates/template_0001
-npx @mevdragon/vidfarm-devcli analyze-viral-dna --template-dir ./templates/template_0001
-npx @mevdragon/vidfarm-devcli analyze-visual-dna --template-dir ./templates/template_0001
+npx @mevdragon/vidfarm-devcli copy-reference-template --template-dir ./src/vidfarm_template_0000
+npx @mevdragon/vidfarm-devcli generate-template --slug-id template_0001 --template-dir ./templates/vidfarm_template_0001
+npx @mevdragon/vidfarm-devcli analyze-viral-dna --template-dir ./templates/vidfarm_template_0001
+npx @mevdragon/vidfarm-devcli analyze-visual-dna --template-dir ./templates/vidfarm_template_0001
+npx @mevdragon/vidfarm-devcli presign-preview-media --file ./drafts/preview/example.png --directory drafts/preview
 ```
 
 After install, the package exposes both `vidfarm` and `vidfarm-devcli` as local binaries.
@@ -49,6 +51,8 @@ The local CLI runs the same template contract used by the hosted platform, but w
 
 Use `vidfarm session` to print reusable auth headers and a sample `curl` request for the local REST API.
 
+For hosted preview-media uploads, use `vidfarm-devcli presign-preview-media`. It calls the authenticated Vidfarm API with `VIDFARM_API_KEY` and returns a presigned PUT URL under `developer/<user_id>/preview_media/*` plus the resulting Vidfarm media URL.
+
 ## What The Hosted Platform Expects From Templates
 
 Vidfarm treats templates as async job producers, not as ad hoc endpoints.
@@ -57,6 +61,7 @@ Each template should provide:
 
 - stable template metadata
 - a `SKILL.md` file for users and agents
+- a TypeScript entrypoint at `src/template.ts`
 - one or more named operations
 - workflow functions behind those operations
 - a `smokeTestPayload` for each operation
@@ -79,6 +84,36 @@ Third-party developers build and validate templates locally first.
 
 After handoff, a Vidfarm admin reviews the template before it is made available on the hosted platform. Template authors should assume there is an approval step between local development and production availability.
 
+## Template Deploy Cycle
+
+When someone says "template deploy cycle" in this repo, they mean this exact sequence:
+
+1. commit and `git push` the repo that contains the template folder, such as `templates/vidfarm_template_<slug>/` inside a monorepo or a standalone template repo
+2. as the platform admin, pull/import that template commit into Vidfarm
+3. approve and activate the imported template release in the hosted platform
+4. run the prod deploy script if platform-runtime code changed, or reuse the current prod image if the change was template-only and you just need a formal deploy-cycle restart
+
+For `template_0000`, that usually means:
+
+```bash
+git -C templates/vidfarm_template_0000 push origin production
+# then run the platform operator command
+node dist/src/cli.js deploy-template-cycle \
+  --env-file .env.production \
+  --stack-name VidfarmProdStack \
+  --template-id 4c7a7e1a-7f35-4f30-9f86-9c8a63c7f2db \
+  --slug-id template_0000 \
+  --repo-url https://github.com/your-org/your-template-repo \
+  --branch production \
+  --template-module-path templates/vidfarm_template_0000/src/template.ts
+```
+
+The important distinction is:
+
+- template repo changes ship through template source import and activation
+- platform code changes ship through the root prod deploy script
+- multiple templates can live in one git repo as long as each template has its own folder and its `template_module_path` points at that folder's `src/template.ts`
+
 ## Authentication Context
 
 When calling a hosted Vidfarm API directly, authenticated requests use:
@@ -86,7 +121,12 @@ When calling a hosted Vidfarm API directly, authenticated requests use:
 - `vidfarm-user-id`
 - `vidfarm-api-key`
 
-Those values come from Vidfarm login and settings, not from platform infrastructure secrets.
+The API key comes from Vidfarm login and settings, not from platform infrastructure secrets.
+If you need to discover the authenticated customer ID first, resolve it from `GET /api/v1/user/me` and then send both headers on subsequent requests.
+
+For hosted template source registration, treat `template_module_path` as repo-relative and point it at the template's TypeScript entrypoint, for example `templates/vidfarm_template_hooks/src/template.ts`. Each template folder must start with `vidfarm_template_`. The import flow builds the repo and loads the compiled `src/template.js` sibling at activation time.
+
+For private GitHub repos, export `VIDFARM_GITHUB_TOKEN` (or `GITHUB_TOKEN`) before running `import-source-prod` or `deploy-template-cycle`. The prod operator command injects that token into the live container's git config for the import and keeps the stored `repo_url` clean.
 
 For local CLI usage, the `session` command gives you a local seeded session so you can test without manually wiring auth state.