@mevdragon/vidfarm-devcli 0.1.0

package/.env.example

@@ -0,0 +1,41 @@
+NODE_ENV="development"
+PORT="3000"
+
+VIDFARM_DB_PATH="./data/vidfarm.sqlite"
+VIDFARM_DATA_DIR="./data"
+
+ENCRYPTION_SECRET="replace-with-a-long-random-secret"
+API_KEY_SALT="replace-with-a-second-long-random-secret"
+WEBHOOK_SECRET="replace-with-a-third-long-random-secret"
+
+WORKER_POLL_MS="1500"
+WORKER_BATCH_SIZE="4"
+DEFAULT_JOB_DELAY_SECONDS="20"
+
+PUBLIC_BASE_URL="http://localhost:3000"
+STORAGE_DRIVER="local"
+AWS_REGION="us-east-1"
+AWS_S3_BUCKET=""
+AWS_S3_ENDPOINT=""
+AWS_ACCESS_KEY_ID=""
+AWS_SECRET_ACCESS_KEY=""
+
+RESEND_API_KEY=""
+RESEND_FROM_EMAIL="noreply@example.com"
+
+OPENAI_API_KEY=""
+OPENROUTER_API_KEY=""
+GEMINI_API_KEY=""
+PERPLEXITY_API_KEY=""
+
+REMOTION_FUNCTION_NAME=""
+REMOTION_REGION="us-east-1"
+REMOTION_BUCKET_NAME=""
+REMOTION_SITE_NAME="vidfarm-demo-template"
+REMOTION_SERVE_URL=""
+REMOTION_COMPOSITION_ID="demo-template"
+REMOTION_AWS_ACCESS_KEY_ID=""
+REMOTION_AWS_SECRET_ACCESS_KEY=""
+REMOTION_MODE="auto"
+
+MOCK_PROVIDER_RESPONSES="true"

package/AWS_REMOTION_HANDOFF.md

@@ -0,0 +1,311 @@
+# New Repo AWS Remotion Handoff
+
+This document is for a fresh repo that wants to keep using the current shared Remotion AWS setup.
+
+It is not a description of how this repo is organized. It is the operating contract a new repo should follow.
+
+## Live AWS resources to reuse
+
+These were verified from AWS on 2026-05-16:
+
+- AWS account: `994816277608`
+- Region: `us-east-1`
+- Remotion render bucket: `remotionlambda-useast1-ujg7c0h43q`
+- Shared Lambda function: `remotion-render-4-0-355-mem2048mb-disk2048mb-180sec`
+- Lambda ARN: `arn:aws:lambda:us-east-1:994816277608:function:remotion-render-4-0-355-mem2048mb-disk2048mb-180sec`
+- Lambda execution role: `arn:aws:iam::994816277608:role/remotion-lambda-role`
+- Lambda runtime: `nodejs20.x`
+- Lambda architecture: `arm64`
+- Lambda timeout: `180`
+- Lambda memory: `2048`
+- Lambda ephemeral storage: `2048`
+
+The bucket is in `us-east-1` and site URLs follow this pattern:
+
+```text
+https://remotionlambda-useast1-ujg7c0h43q.s3.us-east-1.amazonaws.com/sites/<site-name>/index.html
+```
+
+## New repo rule set
+
+The new repo should treat AWS in two layers:
+
+1. Shared infrastructure you are reusing
+2. Repo-specific site bundle you will publish
+
+Shared infrastructure:
+
+- the AWS account
+- the Remotion render bucket
+- the existing Lambda render function
+- the Lambda execution role
+
+Repo-specific asset:
+
+- your new site bundle under `sites/<site-name>/index.html`
+
+That means a new repo does not need to deploy a new Lambda function just to render a new composition. It only needs to:
+
+1. use the same Remotion major/minor version as the shared Lambda
+2. publish a new site bundle
+3. render against that site URL and the shared function name
+
+## Required package versions
+
+The shared Lambda is tied to Remotion `4.0.355`, so the new repo should pin:
+
+```json
+{
+  "dependencies": {
+    "@remotion/cli": "4.0.355",
+    "@remotion/lambda": "4.0.355",
+    "@remotion/renderer": "4.0.355",
+    "remotion": "4.0.355"
+  }
+}
+```
+
+If you upgrade Remotion later, treat that as shared infra work, not normal app work.
+
+## What the new repo should configure
+
+The new repo should store these values in env or a small config module:
+
+```bash
+REMOTION_REGION=us-east-1
+REMOTION_FUNCTION_NAME=remotion-render-4-0-355-mem2048mb-disk2048mb-180sec
+REMOTION_BUCKET_NAME=remotionlambda-useast1-ujg7c0h43q
+REMOTION_SITE_NAME=my-new-site
+REMOTION_SERVE_URL=https://remotionlambda-useast1-ujg7c0h43q.s3.us-east-1.amazonaws.com/sites/my-new-site/index.html
+REMOTION_COMPOSITION_ID=MyComposition
+```
+
+Do not hard-code old values like `tweet-to-tiktok-2`.
+
+## Publish flow for the new repo
+
+The new repo should publish its own dedicated site name:
+
+```bash
+npx -y --package remotion@4.0.355 remotion lambda sites create src/index.ts \
+  --site-name=my-new-site \
+  --region=us-east-1
+```
+
+That writes your bundle into the shared bucket under:
+
+```text
+sites/my-new-site/index.html
+```
+
+Use a dedicated site name per repo or per video format. Do not reuse another repo’s site name unless you intentionally want one repo to overwrite another repo’s published bundle.
+
+## Render flow for the new repo
+
+CLI:
+
+```bash
+npx -y --package remotion@4.0.355 remotion lambda render \
+  "https://remotionlambda-useast1-ujg7c0h43q.s3.us-east-1.amazonaws.com/sites/my-new-site/index.html" \
+  "MyComposition" \
+  --props="./src/my-format/composition.json" \
+  --region="us-east-1" \
+  --timeout="120000" \
+  --function-name="remotion-render-4-0-355-mem2048mb-disk2048mb-180sec" \
+  --frames-per-lambda=100
+```
+
+Node:
+
+```ts
+import { renderMediaOnLambda } from "@remotion/lambda/client";
+
+await renderMediaOnLambda({
+  region: "us-east-1",
+  functionName: "remotion-render-4-0-355-mem2048mb-disk2048mb-180sec",
+  serveUrl:
+    "https://remotionlambda-useast1-ujg7c0h43q.s3.us-east-1.amazonaws.com/sites/my-new-site/index.html",
+  composition: "MyComposition",
+  inputProps: {},
+  codec: "h264",
+  timeoutInMilliseconds: 120000,
+  privacy: "private",
+});
+```
+
+## IAM: what already exists on the Lambda side
+
+The current Lambda execution role is:
+
+- `arn:aws:iam::994816277608:role/remotion-lambda-role`
+
+Trust policy:
+
+- principal: `lambda.amazonaws.com`
+- action: `sts:AssumeRole`
+
+Attached managed policy:
+
+- `arn:aws:iam::994816277608:policy/remotion-lambda-policy`
+
+The attached policy currently grants:
+
+- `s3:ListAllMyBuckets` on `*`
+- `s3:CreateBucket`
+- `s3:ListBucket`
+- `s3:PutBucketAcl`
+- `s3:GetObject`
+- `s3:DeleteObject`
+- `s3:PutObjectAcl`
+- `s3:PutObject`
+- `s3:GetBucketLocation`
+  on `arn:aws:s3:::remotionlambda-*`
+- `lambda:InvokeFunction`
+  on `arn:aws:lambda:*:*:function:remotion-render-*`
+- `logs:CreateLogGroup`
+  on `/aws/lambda-insights`
+- `logs:CreateLogStream`
+- `logs:PutLogEvents`
+  on `/aws/lambda/remotion-render-*` and `/aws/lambda-insights:*`
+
+The new repo does not need to recreate this role if it is reusing the existing shared Lambda.
+
+## IAM: what the new repo runner should have
+
+There are two separate permission sets to think about.
+
+### Option A: publish site bundles and render, but do not manage shared infra
+
+This is the safest default for a new repo.
+
+The repo runner needs enough permission to:
+
+- upload a site bundle into the shared Remotion bucket
+- render with the existing Lambda function
+- optionally inspect function metadata
+
+Recommended policy shape:
+
+```json
+{
+  "Version": "2012-10-17",
+  "Statement": [
+    {
+      "Sid": "RemotionBucketAccess",
+      "Effect": "Allow",
+      "Action": [
+        "s3:CreateBucket",
+        "s3:ListBucket",
+        "s3:GetBucketLocation",
+        "s3:GetObject",
+        "s3:PutObject",
+        "s3:DeleteObject",
+        "s3:PutBucketAcl",
+        "s3:PutObjectAcl"
+      ],
+      "Resource": [
+        "arn:aws:s3:::remotionlambda-useast1-ujg7c0h43q",
+        "arn:aws:s3:::remotionlambda-useast1-ujg7c0h43q/*"
+      ]
+    },
+    {
+      "Sid": "RemotionRenderInvoke",
+      "Effect": "Allow",
+      "Action": [
+        "lambda:InvokeFunction",
+        "lambda:GetFunctionConfiguration"
+      ],
+      "Resource": [
+        "arn:aws:lambda:us-east-1:994816277608:function:remotion-render-4-0-355-mem2048mb-disk2048mb-180sec"
+      ]
+    }
+  ]
+}
+```
+
+If the repo uses Remotion commands that list functions or sites, add:
+
+- `lambda:ListFunctions`
+
+If the repo needs broader compatibility across future Remotion function versions, widen the Lambda ARN to:
+
+- `arn:aws:lambda:us-east-1:994816277608:function:remotion-render-*`
+
+### Option B: also allow shared infra changes
+
+Only use this if the new repo is allowed to:
+
+- redeploy the shared Lambda function
+- rotate or replace the Lambda execution role
+- manage future Remotion infra upgrades
+
+That requires more than render permissions. At minimum, expect to need permissions in these areas:
+
+- `lambda:*` for create/update of the Remotion function family
+- `iam:PassRole` for `remotion-lambda-role`
+- potentially IAM role/policy create/update if Remotion is allowed to create or change roles
+- S3 bucket/object permissions on the shared Remotion bucket
+- CloudWatch Logs permissions
+
+Do not give this to a normal app repo unless that repo really owns shared infrastructure.
+
+## Recommended IAM split
+
+For a clean handoff, use two identities:
+
+1. `remotion-app-runner`
+   For normal repo use. Can publish sites and render videos.
+2. `remotion-infra-admin`
+   Rarely used. Can redeploy shared Lambda infra and manage IAM if needed.
+
+That prevents a content-format repo from accidentally mutating the shared Remotion backend.
+
+## What the new repo should not do
+
+- Do not store long-lived AWS keys in repo `.env` files.
+- Do not hard-code old site names from previous repos.
+- Do not assume this repo’s multi-site router pattern is required.
+- Do not redeploy the shared Lambda function during ordinary composition work.
+
+## Suggested new repo scripts
+
+`package.json`:
+
+```json
+{
+  "scripts": {
+    "create-site": "npx -y --package remotion@4.0.355 remotion lambda sites create src/index.ts --site-name=$REMOTION_SITE_NAME --region=$REMOTION_REGION",
+    "render:cloud": "npx -y --package remotion@4.0.355 remotion lambda render $REMOTION_SERVE_URL $REMOTION_COMPOSITION_ID --props=./src/composition.json --region=$REMOTION_REGION --function-name=$REMOTION_FUNCTION_NAME --timeout=120000 --frames-per-lambda=100"
+  }
+}
+```
+
+If shell interpolation in `package.json` is awkward in your environment, wrap these in small shell scripts instead.
+
+## Bootstrap checklist for the new repo
+
+1. Pin Remotion packages to `4.0.355`.
+2. Add the config variables listed above.
+3. Create a new dedicated site name.
+4. Use a non-admin AWS identity that can publish and render.
+5. Publish the site bundle once.
+6. Run one smoke render against the shared function.
+7. Save the resulting serve URL and composition ID in repo config.
+
+## Verified facts vs inferred guidance
+
+Verified from AWS:
+
+- account id
+- region
+- bucket name
+- function name
+- function config
+- Lambda execution role name
+- attached Lambda execution policy
+
+Not directly readable with the current AWS identity:
+
+- the current IAM policies attached to the calling IAM user `remotion-user`
+
+Because of that, the caller policy in this document is the recommended minimum policy for a new repo runner, derived from the live setup and the operations the new repo needs to perform.