@mevdragon/vidfarm-devcli 0.2.5 → 0.2.7

package/GETTING_STARTED.developers.md

@@ -85,3 +85,32 @@ That will populate with a reference folder of what a template code looks like. W
 8. Create a new folder beside src called `drafts/` which is where we will put messy files when needed.
 
 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.
+
+## Publish Responsibility
+
+When your template is ready for hosted Vidfarm, your responsibility is only:
+
+1. push your template code to GitHub
+2. register or update the template source metadata so Vidfarm knows the repo URL, branch, and template folder path
+
+Your responsibility does not include:
+
+1. importing the source into the live platform
+2. activating the release
+3. making the template public/live
+
+Those are platform-admin steps. If an API route says `403 Admin access required` for import or activate, that means you reached the correct handoff boundary.
+
+When you need to register your template with hosted Vidfarm, use the dev CLI command below from your repo root:
+
+```bash
+npx @mevdragon/vidfarm-devcli register-source-hosted \
+  --env-file .env \
+  --template-id <uuid-v4> \
+  --slug-id <template_slug> \
+  --repo-url https://github.com/<you>/<repo> \
+  --branch main \
+  --template-module-path templates/vidfarm_template_<slug>/src/template.ts
+```
+
+That command uses your `VIDFARM_API_KEY` and sends the registration to the hosted REST API, so the template appears in Vidfarm's review queue with `pending_review` status.

package/README.md

@@ -51,7 +51,7 @@ 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`, mints a presigned PUT URL under `developer/<user_id>/*`, stores each uploaded file under a UUID path segment while preserving the original filename, uploads the file automatically when `--file` is provided, and returns a public-read media URL for the uploaded object.
+For hosted preview-media uploads, use `vidfarm-devcli presign-preview-media`. It calls the authenticated Vidfarm API with `VIDFARM_API_KEY`, mints a presigned PUT URL under `developer/<user_id>/*`, stores each uploaded file under a UUID path segment while preserving the original filename, uploads the file automatically when `--file` is provided, and returns a public-read media URL for the uploaded object. Public readability is granted by bucket policy for `developer/*`, not by public write or list access.
 
 ## What The Hosted Platform Expects From Templates
 
@@ -84,6 +84,19 @@ 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.
 
+The developer handoff ends at:
+
+- `git push` of the template code
+- template source registration or registration update
+
+The developer handoff does not include:
+
+- importing the source into the live platform
+- activating a release
+- making the template public/live
+
+If a developer receives `403 Admin access required` while trying to import or activate a registered source, that is expected. Those routes are for platform admins.
+
 ## Template Deploy Cycle
 
 When someone says "template deploy cycle" in this repo, they mean this exact sequence:
@@ -97,6 +110,15 @@ For `template_0000`, that usually means:
 
 ```bash
 git -C templates/vidfarm_template_0000 push origin production
+# third-party developer registration step
+node dist/src/cli.js register-source-hosted \
+  --env-file .env.production \
+  --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
+
 # then run the platform operator command
 node dist/src/cli.js deploy-template-cycle \
   --env-file .env.production \
@@ -110,7 +132,10 @@ node dist/src/cli.js deploy-template-cycle \
 
 The important distinction is:
 
-- template repo changes ship through template source import and activation
+- third-party developers only ship template repo changes plus registration metadata
+- platform admins import and activate those template repo changes
+- new source registrations land in the hosted review queue before approval
+- newly imported releases can be approved while an older active release stays live
 - 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`
 
@@ -126,7 +151,9 @@ If you need to discover the authenticated customer ID first, resolve it from `GE
 
 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 hosted registration, use `register-source-hosted`. It talks to the Vidfarm REST API directly, so the source record lands in the production database that backs the hosted review queue. `register-source-prod` remains as a compatibility alias for internal/operator workflows.
+
+For private GitHub repos, set `VIDFARM_GITHUB_TOKEN` or `GITHUB_TOKEN` in the hosted runtime environment before using the REST import and approval flow. The production API now performs the clone/import itself, so the token must be available to the server process rather than injected from the operator shell.
 
 For local CLI usage, the `session` command gives you a local seeded session so you can test without manually wiring auth state.
 

package/SKILL.developer.md

@@ -26,6 +26,26 @@ Do not use this skill for:
 - production deploys, release admin, or shared cloud infrastructure
 - asking for AWS, S3, Remotion cloud, or other platform secrets
 
+## Third-Party Publish Rule
+
+Third-party template developers publish template code by pushing git commits to GitHub. That is the only code-distribution step they own.
+
+The third-party developer responsibility is:
+
+- build and validate the template locally
+- commit and push the template folder to GitHub
+- register or update the hosted template source metadata with `register-source-hosted` so Vidfarm knows which repo, branch, and template folder to import from
+- stop there and hand off to the platform team
+
+The third-party developer should not:
+
+- run `import-source-prod`
+- use AWS CloudFormation, SSM, EC2, or shared prod credentials
+- treat platform import/activation as part of template authoring
+- assume "make this template public/live" is their duty
+
+`import-source-prod` and `deploy-template-cycle` are platform-operator commands. They are for internal admin flow, not for external template authors.
+
 For third-party developers, Remotion is local and storage should be accessed through Vidfarm helpers. Do not require cloud Remotion setup or hand-written S3 integration for normal template work.
 
 ## Agent Operating Rule
@@ -95,23 +115,47 @@ Notes:
 - at least one runtime AI provider key is usually enough
 - `GEMINI_API_KEY` is the key used by the built-in DNA analysis commands
 - `VIDFARM_API_KEY` is needed when calling a hosted Vidfarm API directly, including when minting presigned preview-media uploads through `vidfarm-devcli presign-preview-media`
+- `VIDFARM_API_KEY` is also what `vidfarm-devcli register-source-hosted` uses for hosted source registration
 - local `vidfarm-devcli session` already gives you a seeded local API key for the local runtime
 - when calling the hosted API directly, include both `vidfarm-user-id` and `vidfarm-api-key` headers
 - for local `vidfarm-devcli` sessions, you usually do not need to supply `VIDFARM_USER_ID` manually
 - template authoring is TypeScript-first; create and edit template source as `src/template.ts`, not `src/template.js`
 - keep exploratory scripts, one-off test runners, scratch validation files, and temporary job-driving code out of `src/`; place them in a repo-local tmp folder that is a sibling to `src` instead, for example `templates/vidfarm_template_0007/tmp/`
 - when registering a hosted template source, set `template_module_path` to the repo-relative TypeScript entrypoint inside the template folder, for example `templates/vidfarm_template_example/src/template.ts`; the platform build/import flow resolves the compiled `src/template.js` sibling after `npm run build`
+- hosted template registration is git metadata only: repo URL, branch, template entrypoint path, and optionally an explicit commit SHA for a specific import
+- if a template moves folders or switches branches, update the registration metadata; if the template code changed but the location stayed the same, just push a new Git commit
+- the platform determines whether an update exists by comparing the registered branch head against the latest imported release commit
 - do not ask for platform secrets like `ENCRYPTION_SECRET`, `API_KEY_SALT`, `WEBHOOK_SECRET`, admin emails, S3 config, or generic AWS credentials
 - do not ask for `REMOTION_AWS_ACCESS_KEY_ID` or `REMOTION_AWS_SECRET_ACCESS_KEY`
 
-## Template Deploy Cycle
+## Hosted Registration Flow
 
-If the user says "do a template deploy cycle", interpret that as:
+For a third-party developer, the hosted publish handoff is:
 
 1. push the repo changes that contain the target template folder
-2. import that template commit into the hosted platform as a template source release
-3. approve and activate the new release
-4. run the prod deploy script if platform code changed, or reuse the current prod image for a formal restart if the change was template-only
+2. register the source location if it is new, or update the existing registration if the repo, branch, or template path changed
+3. stop there, then tell the platform operator which branch head or commit SHA should be imported if they ask
+
+Registration data should be treated like this:
+
+- `repo_url`: the GitHub repo that contains the template code
+- `branch`: the branch Vidfarm should watch for the latest version, usually `main`
+- `template_module_path`: the repo-relative path to the template TypeScript entrypoint, for example `src/vidfarm_template_funnychat/src/template.ts`
+- `commit_sha`: optional and only needed when you want to import a specific commit instead of the current branch head
+
+Do not tell third-party developers to run AWS-backed operator commands just to publish template code. If the task is only "make my updated template available to Vidfarm", the correct answer is GitHub push plus source registration metadata.
+
+If a developer can register a source but receives `403 Admin access required` when trying to import or activate it, that is the expected boundary, not a blocker they are supposed to solve. It means the handoff point was reached correctly.
+
+Hosted registration should use `register-source-hosted`, not a local DB-backed command. That command calls the Vidfarm REST API so the source appears in the production review queue with `pending_review` status.
+
+## Template Deploy Cycle
+
+If the user explicitly says "template deploy cycle", interpret that as the internal platform-operator sequence:
+
+1. import that template commit into the hosted platform as a template source release
+2. approve and activate the new release
+3. run the prod deploy script if platform code changed, or reuse the current prod image for a formal restart if the change was template-only
 
 Do not assume "template deploy cycle" means "deploy the entire dirty root repo". If the root worktree has unrelated changes and the release is template-only, prefer reusing the current prod image with:
 
@@ -229,7 +273,7 @@ npx @mevdragon/vidfarm-devcli presign-preview-media \
   --directory drafts/preview
 ```
 
-That command calls the hosted Vidfarm API with the user's `VIDFARM_API_KEY`, mints a presigned PUT URL scoped under `developer/<user_id>/*`, stores each uploaded file under a UUID path segment while preserving the original filename, uploads the file automatically when `--file` is provided, and returns both the `storage_key` and a public-read `preview_media_url`. Objects under `developer/<user_id>/*` may be read directly by URL but should not be treated as listable or writable without authenticated API access. Agents should prefer that path for hosted preview uploads whenever the input is a local media file path.
+That command calls the hosted Vidfarm API with the user's `VIDFARM_API_KEY`, mints a presigned PUT URL scoped under `developer/<user_id>/*`, stores each uploaded file under a UUID path segment while preserving the original filename, uploads the file automatically when `--file` is provided, and returns both the `storage_key` and a public-read `preview_media_url`. Public readability for `developer/<user_id>/*` comes from Vidfarm bucket policy, not from public write access, so objects may be read directly by URL but should not be treated as listable or writable without authenticated API access. Agents should prefer that path for hosted preview uploads whenever the input is a local media file path.
 
 ### 2. Start local runtime
 

package/dist/src/app.js

@@ -15,6 +15,7 @@ import { AuthService } from "./services/auth.js";
 import { JobsService } from "./services/jobs.js";
 import { StorageService } from "./services/storage.js";
 import { TemplateSourceService } from "./services/template-sources.js";
+import { TemplateSourceAlreadyRegisteredError } from "./services/template-sources.js";
 const auth = new AuthService();
 const jobs = new JobsService();
 const storage = new StorageService();
@@ -66,6 +67,8 @@ const developerPreviewPresignSchema = z.object({
     content_type: z.string().trim().min(1).max(255).optional(),
     directory: z.string().trim().max(500).optional()
 });
+const templateSourceStatusSchema = z.enum(["pending_review", "approved", "rejected", "disabled"]);
+const templateReleaseStatusSchema = z.enum(["imported", "pending_approval", "approved", "rejected", "failed", "active"]);
 const listJobsQuerySchema = z.object({
     tracer: z.string().min(1).optional(),
     start_time: z.string().min(1).optional(),
@@ -287,7 +290,7 @@ function getReleaseTimestamp(release) {
 function getApprovedHomepageTemplates(c) {
     const approvedReleaseByTemplateId = new Map();
     for (const release of database.listTemplateReleases()) {
-        if (release.status !== "active" && release.status !== "certified") {
+        if (release.status !== "active" && release.status !== "approved") {
             continue;
         }
         const current = approvedReleaseByTemplateId.get(release.templateId);
@@ -644,6 +647,12 @@ function requireDeveloper(c) {
     }
     return customer;
 }
+function templatePublishingAdminError() {
+    return {
+        error: "Admin access required.",
+        detail: "Reviewing, importing, approving, or activating a registered template source is platform-managed. Third-party developers only push to GitHub and register/update the source metadata."
+    };
+}
 function requireSuperagency(c) {
     const provided = c.req.header("x-superagency-key");
     if (!config.SUPERAGENCY_KEY || provided !== config.SUPERAGENCY_KEY) {
@@ -983,7 +992,7 @@ app.post(`${USER_PREFIX}/me/developer/preview-media/presign`, async (c) => {
         const storageKey = storage.developerScopedKey(customer.id, directory, randomUUID(), fileName);
         const upload = await storage.createWriteUrl(storageKey, {
             contentType,
-            publicRead: true,
+            publicRead: false,
             expiresIn: 3600
         });
         const publicUrl = storage.getPublicUrl(storageKey) ?? buildAbsoluteUrl(c, `/template-media?key=${encodeURIComponent(storageKey)}`);
@@ -1045,7 +1054,9 @@ app.get(`${TEMPLATES_PREFIX}/sources`, (c) => {
     catch (error) {
         return c.json({ error: error instanceof Error ? error.message : "Forbidden" }, 403);
     }
-    return c.json({ sources: templateSources.listSources() });
+    const status = c.req.query("status");
+    const parsedStatus = status ? templateSourceStatusSchema.parse(status) : undefined;
+    return c.json({ sources: templateSources.listSources(parsedStatus) });
 });
 app.post(`${TEMPLATES_PREFIX}/sources`, async (c) => {
     try {
@@ -1065,7 +1076,7 @@ app.post(`${TEMPLATES_PREFIX}/sources`, async (c) => {
             install_command: z.string().min(1).default("npm install"),
             build_command: z.string().min(1).default("npm run build")
         }).parse(await c.req.json());
-        const source = templateSources.registerSource({
+        const registration = await templateSources.registerSource({
             templateId: body.template_id,
             slugId: body.slug_id,
             repoUrl: body.repo_url,
@@ -1075,9 +1086,27 @@ app.post(`${TEMPLATES_PREFIX}/sources`, async (c) => {
             installCommand: body.install_command,
             buildCommand: body.build_command
         });
-        return c.json({ source }, 201);
+        return c.json({
+            source: registration.source,
+            registration_action: registration.action,
+            sync: registration.sync,
+            developer_handoff: {
+                completed: true,
+                responsibility_boundary: "third_party_developer_done",
+                message: "Template source registration is complete. Your responsibility stops at GitHub push plus source registration metadata. Importing, activating, and making the template live/public are platform-admin steps.",
+                next_step_for_platform: "A Vidfarm admin can now import this source from the registered branch head or a chosen commit SHA."
+            }
+        }, registration.action === "created" ? 201 : 200);
     }
     catch (error) {
+        if (error instanceof TemplateSourceAlreadyRegisteredError) {
+            return c.json({
+                error: error.message,
+                registration_status: error.existingSource.status,
+                existing_source: error.existingSource,
+                conflict_field: error.conflictField
+            }, 409);
+        }
         const message = error instanceof Error ? error.message : "Unable to register template source.";
         const status = /already exists/i.test(message) ? 409 : 400;
         return c.json({ error: message }, status);
@@ -1090,15 +1119,52 @@ app.get(`${TEMPLATES_PREFIX}/releases`, (c) => {
     catch (error) {
         return c.json({ error: error instanceof Error ? error.message : "Forbidden" }, 403);
     }
-    return c.json({ releases: templateSources.listReleases(c.req.query("template_id") || undefined) });
+    const status = c.req.query("status");
+    const parsedStatus = status ? templateReleaseStatusSchema.parse(status) : undefined;
+    return c.json({
+        releases: templateSources.listReleases({
+            templateId: c.req.query("template_id") || undefined,
+            status: parsedStatus
+        })
+    });
 });
-app.post(`${TEMPLATES_PREFIX}/sources/:sourceId/import`, async (c) => {
+app.get(`${TEMPLATES_PREFIX}/review-queue`, (c) => {
     try {
         requireAdmin(c);
     }
     catch (error) {
         return c.json({ error: error instanceof Error ? error.message : "Forbidden" }, 403);
     }
+    return c.json({
+        pending_sources: templateSources.listSources("pending_review"),
+        pending_releases: templateSources.listReleases({ status: "pending_approval" })
+    });
+});
+app.post(`${TEMPLATES_PREFIX}/sources/:sourceId/approve`, (c) => {
+    try {
+        requireAdmin(c);
+    }
+    catch (error) {
+        return c.json(templatePublishingAdminError(), 403);
+    }
+    return c.json({ source: templateSources.approveSource({ sourceId: c.req.param("sourceId") }) });
+});
+app.post(`${TEMPLATES_PREFIX}/sources/:sourceId/reject`, (c) => {
+    try {
+        requireAdmin(c);
+    }
+    catch (error) {
+        return c.json(templatePublishingAdminError(), 403);
+    }
+    return c.json({ source: templateSources.rejectSource({ sourceId: c.req.param("sourceId") }) });
+});
+app.post(`${TEMPLATES_PREFIX}/sources/:sourceId/import`, async (c) => {
+    try {
+        requireAdmin(c);
+    }
+    catch (error) {
+        return c.json(templatePublishingAdminError(), 403);
+    }
     const body = z.object({
         commit_sha: z.string().min(7).optional()
     }).parse(await c.req.json().catch(() => ({})));
@@ -1108,12 +1174,30 @@ app.post(`${TEMPLATES_PREFIX}/sources/:sourceId/import`, async (c) => {
     });
     return c.json({ release }, 201);
 });
+app.post(`${TEMPLATES_PREFIX}/releases/:releaseId/approve`, (c) => {
+    try {
+        requireAdmin(c);
+    }
+    catch (error) {
+        return c.json(templatePublishingAdminError(), 403);
+    }
+    return c.json({ release: templateSources.approveRelease({ releaseId: c.req.param("releaseId") }) });
+});
+app.post(`${TEMPLATES_PREFIX}/releases/:releaseId/reject`, (c) => {
+    try {
+        requireAdmin(c);
+    }
+    catch (error) {
+        return c.json(templatePublishingAdminError(), 403);
+    }
+    return c.json({ release: templateSources.rejectRelease({ releaseId: c.req.param("releaseId") }) });
+});
 app.post(`${TEMPLATES_PREFIX}/releases/:releaseId/activate`, async (c) => {
     try {
         requireAdmin(c);
     }
     catch (error) {
-        return c.json({ error: error instanceof Error ? error.message : "Forbidden" }, 403);
+        return c.json(templatePublishingAdminError(), 403);
     }
     const { release, template } = await templateSources.activateRelease({
         releaseId: c.req.param("releaseId")

package/dist/src/cli.js

@@ -37,6 +37,14 @@ async function main() {
         await runImportSourceProdCommand(process.argv.slice(3));
         return;
     }
+    if (command === "register-source-hosted") {
+        await runRegisterSourceHostedCommand(process.argv.slice(3));
+        return;
+    }
+    if (command === "register-source-prod") {
+        await runRegisterSourceProdCommand(process.argv.slice(3));
+        return;
+    }
     if (command === "deploy-template-cycle") {
         await runDeployTemplateCycleCommand(process.argv.slice(3));
         return;
@@ -235,7 +243,7 @@ async function runImportSourceCommand(argv) {
         import("./registry.js")
     ]);
     const sources = new TemplateSourceService();
-    const source = sources.registerSource({
+    const registration = await sources.registerSource({
         templateId,
         slugId,
         repoUrl,
@@ -246,17 +254,22 @@ async function runImportSourceCommand(argv) {
         buildCommand: parsed.values["build-command"]
     });
     const release = await sources.importRelease({
-        sourceId: source.id,
+        sourceId: registration.source.id,
         commitSha: parsed.values["commit-sha"] ?? null
     });
+    let sourceRecord = registration.source;
     let activated = null;
     if (parsed.values.activate) {
+        sourceRecord = sources.approveSource({ sourceId: registration.source.id });
+        sources.approveRelease({ releaseId: release.id });
         const result = await sources.activateRelease({ releaseId: release.id });
         templateRegistry.registerRuntimeTemplate(result.template);
         activated = result.release;
     }
     console.log(JSON.stringify({
-        source,
+        source: sourceRecord,
+        registration_action: registration.action,
+        sync: registration.sync,
         release,
         activated_release: activated
     }, null, 2));
@@ -358,17 +371,47 @@ async function runGenerateTemplateCommand(argv) {
         dna_analysis_runs: dnaRuns
     }, null, 2));
 }
+async function runRegisterSourceProdCommand(argv) {
+    const input = parseProdTemplateCommandArgs(argv, {
+        envFile: ".env.production",
+        baseUrl: "https://vidfarm.cloud.zoomgtm.com",
+        activate: false
+    });
+    const registration = await registerSourceViaApi(input);
+    console.log(JSON.stringify({
+        mode: "prod-register-source",
+        base_url: input.baseUrl,
+        source: registration.source,
+        registration_action: registration.registration_action,
+        sync: registration.sync ?? null
+    }, null, 2));
+}
+async function runRegisterSourceHostedCommand(argv) {
+    const input = parseProdTemplateCommandArgs(argv, {
+        envFile: ".env",
+        baseUrl: process.env.VIDFARM_BASE_URL ?? "https://vidfarm.cloud.zoomgtm.com",
+        activate: false
+    });
+    const registration = await registerSourceViaApi(input);
+    console.log(JSON.stringify({
+        mode: "hosted-register-source",
+        base_url: input.baseUrl,
+        source: registration.source,
+        registration_action: registration.registration_action,
+        sync: registration.sync ?? null,
+        next_step: "Platform admin reviews the source, imports a release, approves it, and activates it."
+    }, null, 2));
+}
 async function runImportSourceProdCommand(argv) {
     const input = parseProdTemplateCommandArgs(argv, {
         envFile: ".env.production",
-        stackName: "VidfarmProdStack",
+        baseUrl: "https://vidfarm.cloud.zoomgtm.com",
         activate: true
     });
     const result = await importSourceIntoProd(input);
     console.log(JSON.stringify({
         mode: "prod-import-source",
-        stack_name: input.stackName,
-        instance_id: result.instanceId,
+        base_url: input.baseUrl,
         source: result.payload.source,
         release: result.payload.release,
         activated_release: result.payload.activated_release ?? null
@@ -377,9 +420,13 @@ async function runImportSourceProdCommand(argv) {
 async function runDeployTemplateCycleCommand(argv) {
     const input = parseProdTemplateCommandArgs(argv, {
         envFile: ".env.production",
+        baseUrl: "https://vidfarm.cloud.zoomgtm.com",
         stackName: "VidfarmProdStack",
         activate: true
     });
+    if (!input.stackName) {
+        throw new Error("deploy-template-cycle requires --stack-name.");
+    }
     const importResult = await importSourceIntoProd(input);
     const currentImage = await getProdCurrentImage({
         stackName: input.stackName,
@@ -397,7 +444,6 @@ async function runDeployTemplateCycleCommand(argv) {
     console.log(JSON.stringify({
         mode: "deploy-template-cycle",
         stack_name: input.stackName,
-        instance_id: importResult.instanceId,
         release: importResult.payload.activated_release ?? importResult.payload.release,
         restart_image: currentImage.image
     }, null, 2));
@@ -678,6 +724,8 @@ function parseProdTemplateCommandArgs(argv, defaults) {
             "build-command": { type: "string", default: "npm run build" },
             "commit-sha": { type: "string" },
             "env-file": { type: "string", default: defaults.envFile },
+            "base-url": { type: "string", default: defaults.baseUrl },
+            "api-key": { type: "string" },
             "stack-name": { type: "string", default: defaults.stackName }
         }
     });
@@ -689,6 +737,11 @@ function parseProdTemplateCommandArgs(argv, defaults) {
         throw new Error("Command requires --template-id, --slug-id, --repo-url, and --template-module-path.");
     }
     deriveTemplateRootDirFromModulePath(templateModulePath);
+    loadEnvFile(parsed.values["env-file"]);
+    const apiKey = parsed.values["api-key"] ?? process.env.VIDFARM_API_KEY;
+    if (!apiKey) {
+        throw new Error("Missing Vidfarm API key. Pass --api-key or set VIDFARM_API_KEY in the selected env file.");
+    }
     return {
         templateId,
         slugId,
@@ -700,56 +753,62 @@ function parseProdTemplateCommandArgs(argv, defaults) {
         buildCommand: parsed.values["build-command"],
         commitSha: parsed.values["commit-sha"] ?? undefined,
         envFile: parsed.values["env-file"],
-        stackName: parsed.values["stack-name"],
+        baseUrl: normalizeBaseUrl(parsed.values["base-url"]),
+        apiKey,
+        stackName: parsed.values["stack-name"] || undefined,
         activate: defaults.activate
     };
 }
 async function importSourceIntoProd(input) {
-    loadEnvFile(input.envFile);
-    const instanceId = await resolveStackOutput(input.stackName, "VidfarmInstanceId");
-    const containerScript = buildContainerImportCommand(input);
-    const hostScript = [
-        "set -euo pipefail",
-        `sudo docker exec -e GITHUB_TOKEN=${shellQuote(resolveGithubToken())} vidfarm /bin/bash -lc ${shellQuote(containerScript)}`
-    ].join("\n");
-    const stdout = await runSsmScript({
-        instanceId,
-        comment: `Vidfarm import ${input.slugId}`,
-        script: hostScript
+    const registration = await registerSourceViaApi(input);
+    const source = await postProdTemplateApi(input, `/api/v1/templates/sources/${registration.source.id}/approve`, { method: "POST" });
+    const releaseResponse = await postProdTemplateApi(input, `/api/v1/templates/sources/${registration.source.id}/import`, {
+        method: "POST",
+        body: JSON.stringify({
+            commit_sha: input.commitSha ?? undefined
+        })
     });
+    const approvedRelease = await postProdTemplateApi(input, `/api/v1/templates/releases/${releaseResponse.release.id}/approve`, { method: "POST" });
+    const activatedRelease = input.activate
+        ? await postProdTemplateApi(input, `/api/v1/templates/releases/${releaseResponse.release.id}/activate`, { method: "POST" })
+        : null;
     return {
-        instanceId,
-        payload: extractLastJson(stdout)
+        payload: {
+            source: source.source,
+            release: approvedRelease.release,
+            activated_release: activatedRelease?.release ?? null
+        }
     };
 }
-function buildContainerImportCommand(input) {
-    const args = [
-        "node",
-        "/app/dist/src/cli.js",
-        "import-source",
-        "--template-id", input.templateId,
-        "--slug-id", input.slugId,
-        "--repo-url", input.repoUrl,
-        "--branch", input.branch,
-        "--template-module-path", input.templateModulePath,
-        "--skill-path", input.skillPath,
-        "--install-command", input.installCommand,
-        "--build-command", input.buildCommand
-    ];
-    if (input.commitSha) {
-        args.push("--commit-sha", input.commitSha);
-    }
-    if (!input.activate) {
-        throw new Error("Non-activating prod import is not implemented.");
-    }
-    const lines = [
-        "set -euo pipefail",
-        "if [ -n \"${GITHUB_TOKEN:-}\" ]; then",
-        "  git config --global url.\"https://x-access-token:${GITHUB_TOKEN}@github.com/\".insteadOf \"https://github.com/\"",
-        "fi",
-        args.map(shellQuote).join(" ")
-    ];
-    return lines.join("\n");
+async function registerSourceViaApi(input) {
+    return postProdTemplateApi(input, "/api/v1/templates/sources", {
+        method: "POST",
+        body: JSON.stringify({
+            template_id: input.templateId,
+            slug_id: input.slugId,
+            repo_url: input.repoUrl,
+            branch: input.branch,
+            template_module_path: input.templateModulePath,
+            skill_path: input.skillPath,
+            install_command: input.installCommand,
+            build_command: input.buildCommand
+        })
+    });
+}
+async function postProdTemplateApi(input, pathname, init) {
+    const response = await fetch(`${input.baseUrl}${pathname}`, {
+        ...init,
+        headers: {
+            "content-type": "application/json",
+            "vidfarm-api-key": input.apiKey,
+            ...(init.headers ?? {})
+        }
+    });
+    const payload = await response.json().catch(() => ({}));
+    if (!response.ok) {
+        throw new Error(typeof payload.error === "string" ? payload.error : `Request failed with ${response.status}.`);
+    }
+    return payload;
 }
 function loadEnvFile(envFile) {
     const resolved = path.resolve(process.cwd(), envFile);
@@ -821,12 +880,6 @@ function inferUploadContentType(fileName) {
             return "application/octet-stream";
     }
 }
-function resolveGithubToken() {
-    return process.env.VIDFARM_GITHUB_TOKEN
-        ?? process.env.GITHUB_TOKEN
-        ?? process.env.GH_TOKEN
-        ?? "";
-}
 async function resolveStackOutput(stackName, outputKey) {
     const { stdout } = await runLocalCommand("aws", [
         "cloudformation",

package/dist/src/config.js

@@ -44,6 +44,8 @@ const schema = z.object({
     MOCK_PROVIDER_RESPONSES: z.string().optional(),
     VIDFARM_ADMIN_EMAILS: z.string().default(""),
     VIDFARM_DEVELOPER_EMAILS: z.string().default(""),
+    VIDFARM_GITHUB_TOKEN: z.string().optional(),
+    GITHUB_TOKEN: z.string().optional(),
     TEMPLATE_SOURCE_ROOT: z.string().default("./data/template-sources")
 });
 const parsed = schema.parse(process.env);

package/dist/src/db.js

@@ -235,6 +235,16 @@ db.exec(`
   where slug_id is null or trim(slug_id) = '';
 `);
 db.exec(`create unique index if not exists idx_template_sources_slug_id on template_sources(slug_id);`);
+db.exec(`
+  update template_sources
+  set status = 'approved'
+  where status = 'active';
+`);
+db.exec(`
+  update template_releases
+  set status = 'pending_approval'
+  where status = 'certified';
+`);
 db.exec(`drop index if exists idx_job_events_job_time;`);
 db.exec(`drop table if exists job_events;`);
 function mapJob(row) {
@@ -845,6 +855,35 @@ export const database = {
         });
         return this.getTemplateSourceByTemplateId(record.templateId);
     },
+    updateTemplateSource(input) {
+        const current = this.getTemplateSource(input.id);
+        if (!current) {
+            throw new Error("Template source not found.");
+        }
+        db.prepare(`
+      update template_sources
+      set repo_url = @repo_url,
+          branch = @branch,
+          template_module_path = @template_module_path,
+          skill_path = @skill_path,
+          install_command = @install_command,
+          build_command = @build_command,
+          status = @status,
+          updated_at = @updated_at
+      where id = @id
+    `).run({
+            id: input.id,
+            repo_url: input.repoUrl,
+            branch: input.branch,
+            template_module_path: input.templateModulePath,
+            skill_path: input.skillPath,
+            install_command: input.installCommand,
+            build_command: input.buildCommand,
+            status: input.status ?? current.status,
+            updated_at: nowIso()
+        });
+        return this.getTemplateSource(input.id);
+    },
     getTemplateSource(id) {
         const row = db.prepare(`select * from template_sources where id = ?`).get(id);
         return row ? mapTemplateSource(row) : null;
@@ -857,8 +896,20 @@ export const database = {
         const row = db.prepare(`select * from template_sources where slug_id = ?`).get(slugId);
         return row ? mapTemplateSource(row) : null;
     },
-    listTemplateSources() {
-        return db.prepare(`select * from template_sources order by template_id asc`).all().map(mapTemplateSource);
+    getTemplateSourceByLocation(repoUrl, branch, templateModulePath) {
+        const row = db.prepare(`
+      select *
+      from template_sources
+      where repo_url = ? and branch = ? and template_module_path = ?
+      limit 1
+    `).get(repoUrl, branch, templateModulePath);
+        return row ? mapTemplateSource(row) : null;
+    },
+    listTemplateSources(status) {
+        const rows = status
+            ? db.prepare(`select * from template_sources where status = ? order by created_at asc`).all(status)
+            : db.prepare(`select * from template_sources order by created_at asc`).all();
+        return rows.map(mapTemplateSource);
     },
     createTemplateRelease(record) {
         const timestamp = nowIso();
@@ -903,10 +954,26 @@ export const database = {
         const row = db.prepare(`select * from template_releases where source_id = ? and commit_sha = ?`).get(sourceId, commitSha);
         return row ? mapTemplateRelease(row) : null;
     },
-    listTemplateReleases(templateId) {
-        const rows = templateId
-            ? db.prepare(`select * from template_releases where template_id = ? order by created_at desc`).all(templateId)
-            : db.prepare(`select * from template_releases order by created_at desc`).all();
+    getLatestTemplateReleaseForSource(sourceId) {
+        const row = db.prepare(`
+      select *
+      from template_releases
+      where source_id = ?
+      order by created_at desc
+      limit 1
+    `).get(sourceId);
+        return row ? mapTemplateRelease(row) : null;
+    },
+    listTemplateReleases(input) {
+        const templateId = input?.templateId;
+        const status = input?.status;
+        const rows = templateId && status
+            ? db.prepare(`select * from template_releases where template_id = ? and status = ? order by created_at desc`).all(templateId, status)
+            : templateId
+                ? db.prepare(`select * from template_releases where template_id = ? order by created_at desc`).all(templateId)
+                : status
+                    ? db.prepare(`select * from template_releases where status = ? order by created_at desc`).all(status)
+                    : db.prepare(`select * from template_releases order by created_at desc`).all();
         return rows.map(mapTemplateRelease);
     },
     getActiveTemplateReleases() {
@@ -931,12 +998,16 @@ export const database = {
             updated_at: nowIso()
         });
     },
-    clearActiveTemplateReleases(templateId) {
+    clearActiveTemplateReleases(templateId, fallbackStatus = "approved") {
         db.prepare(`
       update template_releases
-      set status = case when status = 'active' then 'certified' else status end,
-          updated_at = ?
-      where template_id = ?
-    `).run(nowIso(), templateId);
+      set status = case when status = 'active' then @fallback_status else status end,
+          updated_at = @updated_at
+      where template_id = @template_id
+    `).run({
+            fallback_status: fallbackStatus,
+            updated_at: nowIso(),
+            template_id: templateId
+        });
     }
 };

package/dist/src/services/template-sources.js

@@ -10,36 +10,117 @@ import { nowIso } from "../lib/time.js";
 import { loadTemplateFromModule } from "./template-loader.js";
 import { TemplateCertificationService } from "./template-certification.js";
 const execFileAsync = promisify(execFile);
+export class TemplateSourceAlreadyRegisteredError extends Error {
+    existingSource;
+    conflictField;
+    constructor(input) {
+        super(input.message);
+        this.name = "TemplateSourceAlreadyRegisteredError";
+        this.existingSource = input.existingSource;
+        this.conflictField = input.conflictField;
+    }
+}
 export class TemplateSourceService {
     certification = new TemplateCertificationService();
-    listSources() {
-        return database.listTemplateSources();
+    listSources(status) {
+        return database.listTemplateSources(status);
     }
-    listReleases(templateId) {
-        return database.listTemplateReleases(templateId);
+    listReleases(input) {
+        return database.listTemplateReleases(input);
     }
-    registerSource(input) {
+    async registerSource(input) {
         deriveTemplateRootDirFromModulePath(input.templateModulePath);
+        const branch = input.branch ?? "production";
         const existingByTemplateId = database.getTemplateSourceByTemplateId(input.templateId);
-        if (existingByTemplateId) {
-            throw new Error("A template with this template_id already exists. Generate a new UUIDv4 and try again.");
+        if (existingByTemplateId && existingByTemplateId.slugId !== input.slugId) {
+            throw new TemplateSourceAlreadyRegisteredError({
+                message: `Template ${input.templateId} is already registered with slug ${existingByTemplateId.slugId}.`,
+                existingSource: existingByTemplateId,
+                conflictField: "template_id"
+            });
         }
         const existingBySlugId = database.getTemplateSourceBySlugId(input.slugId);
-        if (existingBySlugId) {
-            throw new Error(`A template with slug_id ${input.slugId} already exists.`);
-        }
-        return database.createTemplateSource({
-            id: createId("tsrc"),
-            templateId: input.templateId,
-            slugId: input.slugId,
-            repoUrl: input.repoUrl,
-            branch: input.branch ?? "production",
-            templateModulePath: input.templateModulePath,
-            skillPath: input.skillPath ?? defaultSkillPathForTemplateModule(input.templateModulePath),
-            installCommand: input.installCommand ?? "npm install",
-            buildCommand: input.buildCommand ?? "npm run build",
-            status: "active"
-        });
+        if (existingBySlugId && existingBySlugId.templateId !== input.templateId) {
+            throw new TemplateSourceAlreadyRegisteredError({
+                message: `Template slug ${input.slugId} is already registered to template ${existingBySlugId.templateId}.`,
+                existingSource: existingBySlugId,
+                conflictField: "slug_id"
+            });
+        }
+        const existingByLocation = database.getTemplateSourceByLocation(input.repoUrl, branch, input.templateModulePath);
+        if (existingByLocation &&
+            (existingByLocation.templateId !== input.templateId || existingByLocation.slugId !== input.slugId)) {
+            throw new TemplateSourceAlreadyRegisteredError({
+                message: `Template source ${input.repoUrl}#${branch}:${input.templateModulePath} is already registered to ${existingByLocation.templateId}/${existingByLocation.slugId}.`,
+                existingSource: existingByLocation,
+                conflictField: "source_location"
+            });
+        }
+        const existingSource = existingByTemplateId ?? existingBySlugId ?? existingByLocation ?? null;
+        const installCommand = input.installCommand ?? "npm install";
+        const buildCommand = input.buildCommand ?? "npm run build";
+        const skillPath = input.skillPath ?? defaultSkillPathForTemplateModule(input.templateModulePath);
+        if (existingSource) {
+            const metadataChanged = existingSource.repoUrl !== input.repoUrl ||
+                existingSource.branch !== branch ||
+                existingSource.templateModulePath !== input.templateModulePath ||
+                existingSource.skillPath !== skillPath ||
+                existingSource.installCommand !== installCommand ||
+                existingSource.buildCommand !== buildCommand;
+            const nextSource = metadataChanged
+                ? database.updateTemplateSource({
+                    id: existingSource.id,
+                    repoUrl: input.repoUrl,
+                    branch,
+                    templateModulePath: input.templateModulePath,
+                    skillPath,
+                    installCommand,
+                    buildCommand,
+                    status: existingSource.status === "disabled" ? "disabled" : "pending_review"
+                })
+                : existingSource;
+            return {
+                source: nextSource,
+                action: nextSource.updatedAt === existingSource.updatedAt ? "unchanged" : "updated",
+                sync: await this.getSourceSyncStatus(nextSource.id)
+            };
+        }
+        try {
+            const source = database.createTemplateSource({
+                id: createId("tsrc"),
+                templateId: input.templateId,
+                slugId: input.slugId,
+                repoUrl: input.repoUrl,
+                branch,
+                templateModulePath: input.templateModulePath,
+                skillPath,
+                installCommand,
+                buildCommand,
+                status: "pending_review"
+            });
+            return {
+                source,
+                action: "created",
+                sync: await this.getSourceSyncStatus(source.id)
+            };
+        }
+        catch (error) {
+            const existingSource = database.getTemplateSourceByTemplateId(input.templateId) ??
+                database.getTemplateSourceBySlugId(input.slugId) ??
+                database.getTemplateSourceByLocation(input.repoUrl, branch, input.templateModulePath);
+            if (existingSource) {
+                throw new TemplateSourceAlreadyRegisteredError({
+                    message: `Template registration already exists with status ${existingSource.status}.`,
+                    existingSource,
+                    conflictField: existingSource.templateId === input.templateId
+                        ? "template_id"
+                        : existingSource.slugId === input.slugId
+                            ? "slug_id"
+                            : "source_location"
+                });
+            }
+            throw error;
+        }
     }
     async importRelease(input) {
         const source = database.getTemplateSource(input.sourceId);
@@ -49,9 +130,10 @@ export class TemplateSourceService {
         const commitSha = input.commitSha ?? await this.resolveBranchHead(source.repoUrl, source.branch);
         const checkoutPath = path.join(config.TEMPLATE_SOURCE_ROOT, source.templateId, commitSha);
         const skillPath = path.join(checkoutPath, source.skillPath);
+        const authRepoUrl = this.resolveGitRemoteUrl(source.repoUrl);
         if (!existsSync(checkoutPath)) {
             mkdirSync(path.dirname(checkoutPath), { recursive: true });
-            await this.runShell(["git", "clone", "--branch", source.branch, source.repoUrl, checkoutPath], process.cwd());
+            await this.runShell(["git", "clone", "--branch", source.branch, authRepoUrl, checkoutPath], process.cwd());
             await this.runShell(["git", "checkout", commitSha], checkoutPath);
             if (source.installCommand.trim()) {
                 await this.runCommandString(source.installCommand, checkoutPath);
@@ -69,7 +151,7 @@ export class TemplateSourceService {
             throw new Error(`Imported template slug_id ${template.slugId} does not match source slug_id ${source.slugId}.`);
         }
         const certificationReport = await this.certification.certify({ template, skillPath });
-        const status = certificationReport.passed ? "certified" : "failed";
+        const status = certificationReport.passed ? "pending_approval" : "failed";
         return database.createTemplateRelease({
             id: createId("trel"),
             sourceId: source.id,
@@ -84,13 +166,77 @@ export class TemplateSourceService {
             activatedAt: null
         });
     }
+    approveSource(input) {
+        const source = database.getTemplateSource(input.sourceId);
+        if (!source) {
+            throw new Error("Template source not found.");
+        }
+        return database.updateTemplateSource({
+            id: source.id,
+            repoUrl: source.repoUrl,
+            branch: source.branch,
+            templateModulePath: source.templateModulePath,
+            skillPath: source.skillPath,
+            installCommand: source.installCommand,
+            buildCommand: source.buildCommand,
+            status: "approved"
+        });
+    }
+    rejectSource(input) {
+        const source = database.getTemplateSource(input.sourceId);
+        if (!source) {
+            throw new Error("Template source not found.");
+        }
+        return database.updateTemplateSource({
+            id: source.id,
+            repoUrl: source.repoUrl,
+            branch: source.branch,
+            templateModulePath: source.templateModulePath,
+            skillPath: source.skillPath,
+            installCommand: source.installCommand,
+            buildCommand: source.buildCommand,
+            status: "rejected"
+        });
+    }
+    approveRelease(input) {
+        const release = database.getTemplateRelease(input.releaseId);
+        if (!release) {
+            throw new Error("Template release not found.");
+        }
+        if (release.status !== "pending_approval" && release.status !== "approved" && release.status !== "active") {
+            throw new Error("Only pending-approval releases can be approved.");
+        }
+        if (release.status === "active") {
+            return release;
+        }
+        database.updateTemplateReleaseStatus({
+            id: release.id,
+            status: "approved",
+            certificationReport: release.certificationReport,
+            activatedAt: null
+        });
+        return database.getTemplateRelease(release.id);
+    }
+    rejectRelease(input) {
+        const release = database.getTemplateRelease(input.releaseId);
+        if (!release) {
+            throw new Error("Template release not found.");
+        }
+        database.updateTemplateReleaseStatus({
+            id: release.id,
+            status: "rejected",
+            certificationReport: release.certificationReport,
+            activatedAt: null
+        });
+        return database.getTemplateRelease(release.id);
+    }
     async activateRelease(input) {
         const release = database.getTemplateRelease(input.releaseId);
         if (!release) {
             throw new Error("Template release not found.");
         }
-        if (release.status !== "certified" && release.status !== "active") {
-            throw new Error("Only certified releases can be activated.");
+        if (release.status !== "approved" && release.status !== "active") {
+            throw new Error("Only approved releases can be activated.");
         }
         const template = await loadTemplateFromModule(release.modulePath);
         const certificationReport = release.certificationReport ?? await this.certification.certify({
@@ -120,8 +266,34 @@ export class TemplateSourceService {
             }
         };
     }
+    async getSourceSyncStatus(sourceId) {
+        const source = database.getTemplateSource(sourceId);
+        if (!source) {
+            throw new Error("Template source not found.");
+        }
+        const latestRelease = database.getLatestTemplateReleaseForSource(source.id);
+        try {
+            const headCommitSha = await this.resolveBranchHead(source.repoUrl, source.branch);
+            return {
+                headCommitSha,
+                latestReleaseCommitSha: latestRelease?.commitSha ?? null,
+                importTargetCommitSha: headCommitSha,
+                hasUnimportedUpdate: latestRelease ? latestRelease.commitSha !== headCommitSha : true,
+                headLookupError: null
+            };
+        }
+        catch (error) {
+            return {
+                headCommitSha: null,
+                latestReleaseCommitSha: latestRelease?.commitSha ?? null,
+                importTargetCommitSha: latestRelease?.commitSha ?? null,
+                hasUnimportedUpdate: null,
+                headLookupError: error instanceof Error ? error.message : String(error)
+            };
+        }
+    }
     async resolveBranchHead(repoUrl, branch) {
-        const { stdout } = await execFileAsync("git", ["ls-remote", repoUrl, branch], { cwd: process.cwd() });
+        const { stdout } = await execFileAsync("git", ["ls-remote", this.resolveGitRemoteUrl(repoUrl), branch], { cwd: process.cwd() });
         const line = stdout.trim().split("\n").find(Boolean);
         if (!line) {
             throw new Error(`Unable to resolve branch ${branch} for ${repoUrl}`);
@@ -143,6 +315,16 @@ export class TemplateSourceService {
             }
         });
     }
+    resolveGitRemoteUrl(repoUrl) {
+        const githubToken = config.VIDFARM_GITHUB_TOKEN || config.GITHUB_TOKEN;
+        if (!githubToken) {
+            return repoUrl;
+        }
+        if (!/^https:\/\/github\.com\//i.test(repoUrl)) {
+            return repoUrl;
+        }
+        return repoUrl.replace(/^https:\/\/github\.com\//i, `https://x-access-token:${encodeURIComponent(githubToken)}@github.com/`);
+    }
     resolveImportableModulePath(checkoutPath, declaredModulePath) {
         const sourceModulePath = path.join(checkoutPath, declaredModulePath);
         const extension = path.extname(sourceModulePath).toLowerCase();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mevdragon/vidfarm-devcli",
-  "version": "0.2.5",
+  "version": "0.2.7",
   "description": "Developer CLI for running the Vidfarm local template platform.",
   "type": "module",
   "bin": {