@aksp/opencrew 1.4.1 → 1.5.0

package/templates/skills/image-ai-generator/SKILL.md

@@ -14,7 +14,7 @@ type: script
 version: "1.0.0"
 script:
   path: scripts/generate.py
-  runtime: python3
+  runtime: python
   invoke: "python3 {skill_path}/scripts/generate.py --prompt \"{prompt}\" --output \"{output}\" --mode \"{mode}\""
 env:
   - OPENROUTER_API_KEY
@@ -52,10 +52,14 @@ Use the Image Generator when you need to create visual assets from text prompts.
 
 ## Instructions
 
+`{skill_path}` is this skill's folder (normally `skills/image-ai-generator`). The commands below use
+`python3` (macOS/Linux). **On Windows** use `py -3` instead (or `python` if the `py` launcher is
+not installed).
+
 ### Single image generation
 
 ```bash
-python3 skills/image-generator/scripts/generate.py \
+python3 {skill_path}/scripts/generate.py \
   --prompt "A detailed description of the image to generate" \
   --output "crews/{crew}/output/{run_id}/assets/image-name.jpg" \
   --mode test
@@ -66,7 +70,7 @@ python3 skills/image-generator/scripts/generate.py \
 Use `--reference` to send a local image to the model as visual context. The model will incorporate the referenced image (e.g., a logo or mascot) into the generated output.
 
 ```bash
-python3 skills/image-generator/scripts/generate.py \
+python3 {skill_path}/scripts/generate.py \
   --prompt "A social media banner featuring the company logo prominently in the center" \
   --output "crews/{crew}/output/{run_id}/assets/banner.jpg" \
   --reference "crews/{crew}/assets/logo.png" \
@@ -78,7 +82,7 @@ Supported reference formats: PNG, JPEG, WEBP, GIF.
 ### Batch generation
 
 ```bash
-python3 skills/image-generator/scripts/generate.py \
+python3 {skill_path}/scripts/generate.py \
   --batch "crews/{crew}/output/{run_id}/assets/batch.json" \
   --mode production
 ```
@@ -96,7 +100,7 @@ Each item can optionally include a `"reference": "path/to/ref.png"` field.
 ### Prompt guidelines
 
 - Be specific about composition, lighting, style, and mood
-- Specify aspect ratio or orientation when relevant (e.g., "portrait 3:4", "landscape 16:9")
+- Specify aspect ratio or orientation when relevant (e.g., "portrait 4:5", "landscape 16:9")
 - Include "hyper realistic, 4K quality" for photographic styles
 - Include "clean composition" to avoid cluttered outputs
 - Avoid requesting text in images — AI models struggle with text rendering

package/templates/skills/image-creator/SKILL.md

@@ -46,7 +46,8 @@ Use the Visual Renderer when you need to generate production-ready images from H
 4. **Render** -- Use Playwright to:
    - `browser_navigate` to `http://localhost:8765/slide-01.html` (filename only, not full path)
    - `browser_resize` to target viewport dimensions
-   - `browser_take_screenshot` to save as PNG
+   - `browser_take_screenshot` to save as PNG — **except when the images will be published to
+     Instagram**: Instagram accepts JPEG only, so save with `type: "jpeg"` (`slide-01.jpg`)
 
 5. **Verify** -- Read the screenshot to confirm quality. Re-render if needed.
 
@@ -59,7 +60,7 @@ Use the Visual Renderer when you need to generate production-ready images from H
 
 Use these standard dimensions:
 - Instagram Post: 1080 x 1080
-- Instagram Carousel: 1080 x 1440
+- Instagram Carousel: 1080 x 1350
 - Instagram Story/Reel: 1080 x 1920
 - Facebook Post: 1200 x 630
 - Twitter/X Post: 1200 x 675
@@ -85,7 +86,7 @@ Example minimal structure:
   <meta charset="UTF-8">
   <style>
     * { margin: 0; padding: 0; box-sizing: border-box; }
-    body { width: 1080px; height: 1440px; overflow: hidden; }
+    body { width: 1080px; height: 1350px; overflow: hidden; }
     /* ... your design ... */
   </style>
 </head>
@@ -103,6 +104,7 @@ For multi-image outputs like carousels:
 3. Render each slide sequentially (step 4 repeated per slide)
 4. Stop the HTTP server **once** after all slides are done (step 6 of Core Workflow)
 5. Name output files with zero-padded numbers: slide-01.png, slide-02.png, slide-03.png
+   (`.jpg` when the destination is Instagram — see step 4)
 6. Keep all slides at the same viewport dimensions
 
 ### Best Practices

package/templates/skills/image-fetcher/SKILL.md

@@ -47,7 +47,7 @@ When taking a screenshot:
 1. Navigate to the URL with `browser_navigate`
 2. Set viewport: `browser_resize` with width/height for target format
    - Instagram post: 1080x1080
-   - Instagram carousel: 1080x1440
+   - Instagram carousel: 1080x1350
    - Story/Reel: 1080x1920
    - Generic: 1280x720
 3. Wait for page load (`browser_wait_for` if needed)

package/templates/skills/instagram-publisher/SKILL.md

@@ -20,7 +20,8 @@ version: "1.0.0"
 script:
   path: scripts/publish.js
   runtime: node
-  invoke: "node --env-file=.env {skill_path}/scripts/publish.js --images \"{images}\" --caption \"{caption}\""
+  invoke: "node --env-file=.env {skill_path}/scripts/publish.js --images \"{images}\" --caption-file \"{caption_file}\""
+side_effects: irreversible
 env:
   - INSTAGRAM_ACCESS_TOKEN
   - INSTAGRAM_USER_ID
@@ -39,36 +40,53 @@ Use the Instagram Publisher when you need to publish carousel posts directly to
 
 ### Workflow
 
-1. List JPEG files in `crews/{crew}/output/images/` sorted by name.
-   If no files found: stop and ask the user to add images before continuing.
-2. Present the image list to the user to confirm order (use your IDE's native interactive-choice mechanism if it has one; otherwise a numbered list).
-3. Extract the caption from the content draft:
-   - Use the hook slide text + CTA slide text
-   - Max 2200 characters (Instagram limit)
-4. Run the publish script:
+Publishing is **irreversible**: a post cannot be taken back once it is live. This step
+runs only at the end of the pipeline, after the Review and the Final Approval checkpoint,
+and is **never** retried automatically.
+
+1. Find the images produced by the rendering step **of this run** in
+   `crews/{crew}/output/{run_id}/` (use the latest `vN/` folder if there are versions),
+   JPEG only, sorted by name. If there are no `.jpg`/`.jpeg` files: stop and ask the user
+   (PNG renders must be re-rendered as JPEG — Instagram accepts JPEG only).
+2. Extract the caption from the approved content draft (hook slide text + CTA slide text,
+   max 2200 characters) and **write it to a file**:
+   `crews/{crew}/output/{run_id}/caption.txt`. Never put the caption inside a shell command.
+3. **Preview**: show the user the ordered image list and the full caption, and let them
+   confirm the order (use your IDE's native interactive-choice mechanism if it has one;
+   otherwise a numbered list).
+4. **Dry run** — validates images, credentials and containers without posting:
    ```
-   node --env-file=.env crews/{crew}/tools/publish.js \
+   node --env-file=.env {skill_path}/scripts/publish.js \
      --images "<comma-separated-ordered-paths>" \
-     --caption "<caption>"
+     --caption-file "crews/{crew}/output/{run_id}/caption.txt" \
+     --dry-run
    ```
-   Add `--dry-run` to test the full flow without actually publishing.
-5. On success: save the post URL and post ID to the step output file.
-6. On failure: display the error and ask the user how to proceed.
+   If it fails: show the error and stop.
+5. **Ask for explicit confirmation** before going live: the user must answer with the
+   word **publish** (or **publicar**). Any other answer — including silence, "ok" or an
+   ambiguous reply — means do not publish.
+6. **Live publish** — the same command without `--dry-run`. Run it **once**.
+7. On success: save the post URL and post ID to the step output file immediately.
+8. On failure or missing output: do NOT run the command again. Tell the user the post may
+   already be live, ask them to check the Instagram profile, and let them decide.
 
 ### Constraints
 
-- Images: JPEG only, 2-10 per carousel
+- Images: JPEG only (`.jpg`/`.jpeg`), 2-10 per carousel, inside `crews/*/output/` — the
+  script refuses anything else before uploading
+- Images are hosted on imgBB for 24h only (enough for Instagram to fetch them)
 - Caption: max 2200 characters
 - Requires Instagram Business account (not Personal or Creator)
 - Rate limit: 25 API-published posts per 24 hours
 
 ### Setup (first-time)
 
-Copy `.env.example` to `.env` and fill in the two required variables:
+Copy `.env.example` to `.env` and fill in the three required variables:
 
 ```
 INSTAGRAM_ACCESS_TOKEN=
 INSTAGRAM_USER_ID=
+IMGBB_API_KEY=
 ```
 
 #### INSTAGRAM_ACCESS_TOKEN
@@ -115,5 +133,5 @@ Pré-requisito: conta Instagram Business conectada a uma Página do Facebook, e
 
 - **Publish Carousel** -- Upload images and publish a carousel post to Instagram
 - **Dry Run** -- Test the full publishing flow without actually posting (use `--dry-run` flag)
-- **Image Upload** -- Upload local JPEG images to imgBB (requires API key)
+- **Image Upload** -- Upload the crew's JPEG renders to imgBB for 24h (requires API key)
 - **Status Check** -- Monitor media container processing status before publishing

package/templates/skills/instagram-publisher/scripts/publish.js

@@ -1,20 +1,32 @@
 #!/usr/bin/env node
 // Instagram Carousel Publisher
-// Usage: node --env-file=.env publish.js --images "slide1.jpg,slide2.jpg" --caption "..." [--dry-run]
+// Usage: node --env-file=.env publish.js --images "a.jpg,b.jpg" --caption-file caption.txt [--dry-run]
+//
+// Safety rules (specs/fase-1-hotfix.md F1-10):
+// - the caption comes from a FILE, never from a shell-interpolated argument;
+// - only .jpg/.jpeg files inside crews/*/output/ can be uploaded (public hosting);
+// - imgBB uploads expire; the Graph API token goes in POST bodies, not URLs.
 
 import { readFileSync } from 'node:fs';
-import { resolve } from 'node:path';
+import { readFile } from 'node:fs/promises';
+import { resolve, relative, isAbsolute, sep, extname } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
+const IMGBB_EXPIRATION_SECONDS = 86_400; // Instagram fetches the images right away; 1 day is plenty.
+
 // ── Argument parsing ──────────────────────────────────────────
 
 export function parseArgs(argv) {
-  const args = { images: [], caption: '', dryRun: false };
+  const args = { images: [], caption: '', captionFile: '', dryRun: false };
   for (let i = 2; i < argv.length; i++) {
     if (argv[i] === '--images') {
-      if (i + 1 < argv.length) args.images = argv[++i].split(',').map(s => s.trim());
+      if (i + 1 < argv.length) args.images = argv[++i].split(',').map(s => s.trim()).filter(Boolean);
+    }
+    else if (argv[i] === '--caption-file') {
+      if (i + 1 < argv.length) args.captionFile = argv[++i];
     }
     else if (argv[i] === '--caption') {
+      // Legacy: prefer --caption-file (a caption in a shell command can execute code).
       if (i + 1 < argv.length) args.caption = argv[++i];
     }
     else if (argv[i] === '--dry-run') args.dryRun = true;
@@ -22,15 +34,32 @@ export function parseArgs(argv) {
   return args;
 }
 
+export async function readCaption(args) {
+  return args.captionFile ? readFile(args.captionFile, 'utf8') : args.caption;
+}
+
+/** Throws unless every path is a .jpg/.jpeg inside <cwd>/crews/<crew>/output/. */
+export function validateImagePaths(images, cwd = process.cwd()) {
+  const crewsDir = resolve(cwd, 'crews');
+  for (const img of images) {
+    const rel = relative(crewsDir, resolve(cwd, img));
+    const parts = rel.split(sep);
+    const inside = rel && !rel.startsWith('..') && !isAbsolute(rel) && parts.length >= 3 && parts[1] === 'output';
+    const jpeg = ['.jpg', '.jpeg'].includes(extname(img).toLowerCase());
+    if (!inside || !jpeg) {
+      throw new Error(`Refusing to upload ${img}: only .jpg/.jpeg files inside crews/*/output/ are allowed.`);
+    }
+  }
+}
+
 // ── Image upload (imgBB) ──────────────────────────────────────
 
 export async function uploadToImgBB(imagePath, apiKey) {
-  const absolutePath = resolve(imagePath);
-  const fileBuffer = readFileSync(absolutePath);
-  const base64Image = fileBuffer.toString('base64');
+  const base64Image = readFileSync(resolve(imagePath)).toString('base64');
   const form = new FormData();
   form.append('key', apiKey);
   form.append('image', base64Image);
+  form.append('expiration', String(IMGBB_EXPIRATION_SECONDS));
   const res = await fetch('https://api.imgbb.com/1/upload', {
     method: 'POST',
     body: form,
@@ -45,15 +74,19 @@ export async function uploadToImgBB(imagePath, apiKey) {
 
 const IG_BASE = 'https://graph.facebook.com/v21.0';
 
+// POST with form-encoded body: keeps the access token out of URLs (and out of server/proxy logs).
+async function igPost(path, params, label) {
+  const res = await fetch(`${IG_BASE}/${path}`, { method: 'POST', body: new URLSearchParams(params) });
+  if (!res.ok) throw new Error(`${label} failed [${res.status}]: ${await res.text()}`);
+  return (await res.json()).id;
+}
+
 export async function createChildContainer(userId, imageUrl, accessToken) {
-  const params = new URLSearchParams({
+  return igPost(`${userId}/media`, {
     image_url: imageUrl,
     is_carousel_item: 'true',
     access_token: accessToken,
-  });
-  const res = await fetch(`${IG_BASE}/${userId}/media?${params}`, { method: 'POST' });
-  if (!res.ok) throw new Error(`createChildContainer failed [${res.status}]: ${await res.text()}`);
-  return (await res.json()).id;
+  }, 'createChildContainer');
 }
 
 export async function getContainerStatus(containerId, accessToken) {
@@ -75,22 +108,16 @@ export async function pollUntilFinished(containerId, accessToken, timeoutMs = 60
 }
 
 export async function createCarouselContainer(userId, childIds, caption, accessToken) {
-  const params = new URLSearchParams({
+  return igPost(`${userId}/media`, {
     media_type: 'CAROUSEL',
     children: childIds.join(','),
     caption,
     access_token: accessToken,
-  });
-  const res = await fetch(`${IG_BASE}/${userId}/media?${params}`, { method: 'POST' });
-  if (!res.ok) throw new Error(`createCarouselContainer failed [${res.status}]: ${await res.text()}`);
-  return (await res.json()).id;
+  }, 'createCarouselContainer');
 }
 
 export async function publishMedia(userId, containerId, accessToken) {
-  const params = new URLSearchParams({ creation_id: containerId, access_token: accessToken });
-  const res = await fetch(`${IG_BASE}/${userId}/media_publish?${params}`, { method: 'POST' });
-  if (!res.ok) throw new Error(`publishMedia failed [${res.status}]: ${await res.text()}`);
-  return (await res.json()).id;
+  return igPost(`${userId}/media_publish`, { creation_id: containerId, access_token: accessToken }, 'publishMedia');
 }
 
 export async function getPermalink(mediaId, accessToken) {
@@ -103,25 +130,29 @@ export async function getPermalink(mediaId, accessToken) {
 
 // ── Main ──────────────────────────────────────────────────────
 
-async function main() {
-  const { images, caption, dryRun } = parseArgs(process.argv);
+export async function main(argv = process.argv, { env = process.env, cwd = process.cwd() } = {}) {
+  const args = parseArgs(argv);
+  const { images, dryRun } = args;
 
   if (!images.length) throw new Error('--images is required (e.g. --images "slide1.jpg,slide2.jpg")');
-  if (!caption) throw new Error('--caption is required');
   if (images.length < 2 || images.length > 10) {
     throw new Error(`Instagram carousels require 2–10 images (got ${images.length})`);
   }
+  validateImagePaths(images, cwd);
+
+  const caption = await readCaption(args);
+  if (!caption) throw new Error('--caption-file is required');
   if (caption.length > 2200) {
     throw new Error(`Caption exceeds Instagram's 2200-character limit (got ${caption.length})`);
   }
 
-  const { INSTAGRAM_ACCESS_TOKEN, INSTAGRAM_USER_ID, IMGBB_API_KEY } = process.env;
+  const { INSTAGRAM_ACCESS_TOKEN, INSTAGRAM_USER_ID, IMGBB_API_KEY } = env;
   if (!INSTAGRAM_ACCESS_TOKEN) throw new Error('INSTAGRAM_ACCESS_TOKEN is not set in environment');
   if (!INSTAGRAM_USER_ID) throw new Error('INSTAGRAM_USER_ID is not set in environment');
   if (!IMGBB_API_KEY) throw new Error('IMGBB_API_KEY is not set in environment. Get one at https://api.imgbb.com/');
 
-  console.log(`📸 Uploading ${images.length} image(s) to imgBB...`);
-  const imageUrls = await Promise.all(images.map(p => uploadToImgBB(p, IMGBB_API_KEY)));
+  console.log(`📸 Uploading ${images.length} image(s) to imgBB (expire in 24h)...`);
+  const imageUrls = await Promise.all(images.map(p => uploadToImgBB(resolve(cwd, p), IMGBB_API_KEY)));
   imageUrls.forEach((url, i) => console.log(`   [${i + 1}] ${url}`));
 
   console.log('\n📦 Creating Instagram media containers...');

package/templates/skills/template-designer/SKILL.md

@@ -46,7 +46,7 @@ Before generating any template, read and internalize the design best practices:
 - `_opencrew/core/best-practices/image-design.md` — **REQUIRED reading**. Contains platform-specific minimum font sizes, typography rules, spacing guidelines, color palette constraints, contrast requirements, and layout methodology. Every template you generate MUST comply with these rules.
 
 Key rules to always follow:
-- **Font sizes**: Hero 58px, Heading 43px, Body 34px, Caption 24px minimum for Instagram carousel (1080x1440). Absolute minimum 20px for any readable text on any platform.
+- **Font sizes**: Hero 58px, Heading 43px, Body 34px, Caption 24px minimum for Instagram carousel (1080x1350). Absolute minimum 20px for any readable text on any platform.
 - **Font weight**: 500 or higher for body text and above.
 - **Colors**: Maximum 5 colors per design system (primary, secondary, accent, background, text).
 - **Contrast**: WCAG AA minimum 4.5:1 for all text against background.
@@ -61,7 +61,7 @@ You should also apply general web design best practices: proper white space, vis
 These rules are NON-NEGOTIABLE. Every template must comply:
 
 **Fixed Dimensions (never use height: auto or flexible height):**
-- Instagram Carousel: `width: 1080px; height: 1440px` (3:4 portrait)
+- Instagram Carousel: `width: 1080px; height: 1350px` (4:5 portrait)
 - Instagram Story/Reel: `width: 1080px; height: 1920px` (9:16 portrait)
 - Instagram Post: `width: 1080px; height: 1080px` (1:1 square)
 - LinkedIn Post: `width: 1200px; height: 627px` (1.91:1 horizontal)
@@ -155,7 +155,7 @@ When the user approves, create two files:
 
 Save to: `crews/{code}/pipeline/data/template-reference.html`
 
-The complete, self-contained HTML/CSS of the approved template at full resolution (e.g., 1080x1440). This is the literal example the design agent will use.
+The complete, self-contained HTML/CSS of the approved template at full resolution (e.g., 1080x1350). This is the literal example the design agent will use.
 
 ### 2. Visual Identity Rules
 

package/templates/skills/template-designer/base-templates/model-a.html

@@ -2,7 +2,7 @@
 <!-- Style: Black background, tweet-style layout with avatar, verified badge, editorial text, contextual image -->
 <!-- Fonts: Inter (body), weight 400-700 -->
 <!-- Colors: #000 bg, #fff text, #1D9BF0 verified, #71767B muted, #2a2a2a borders/avatar, #1a1a2e image gradient -->
-<div style="width:1080px;height:1440px;background:#000;color:#fff;font-family:'Inter',sans-serif;display:flex;flex-direction:column;padding:72px;gap:0;position:relative;overflow:hidden;">
+<div style="width:1080px;height:1350px;background:#000;color:#fff;font-family:'Inter',sans-serif;display:flex;flex-direction:column;padding:72px;gap:0;position:relative;overflow:hidden;">
   <!-- Tweet header -->
   <div style="display:flex;gap:24px;align-items:center;">
     <div style="width:80px;height:80px;border-radius:50%;background:#2a2a2a;flex-shrink:0;"></div>

package/templates/skills/template-designer/base-templates/model-b.html

@@ -2,7 +2,7 @@
 <!-- Style: Warm cream background, bold uppercase title, numbered cards with warm gradient progression -->
 <!-- Fonts: Montserrat 900 (title), Inter 500-700 (body) -->
 <!-- Colors: #FDF6EE bg, #E85D2A primary orange, #D4742A/#C05A1A/#A04010 gradient steps, #FFF5E6-#D07030 card backgrounds -->
-<div style="width:1080px;height:1440px;background:#FDF6EE;color:#111;font-family:'Inter',sans-serif;display:flex;flex-direction:column;padding:72px;justify-content:center;gap:48px;position:relative;overflow:hidden;">
+<div style="width:1080px;height:1350px;background:#FDF6EE;color:#111;font-family:'Inter',sans-serif;display:flex;flex-direction:column;padding:72px;justify-content:center;gap:48px;position:relative;overflow:hidden;">
   <!-- Title -->
   <div style="text-align:center;">
     <h1 style="font-size:58px;font-weight:900;line-height:1.15;margin:0;text-transform:uppercase;font-family:'Montserrat',sans-serif;">

package/templates/skills/template-designer/base-templates/model-c.html

@@ -2,7 +2,7 @@
 <!-- Style: Purple-dark gradient, data metric cards, decorative glow effects -->
 <!-- Fonts: Montserrat 900 (title, metrics), Inter 500 (body, labels) -->
 <!-- Colors: gradient #0f0326-#1a0a3e-#0d0d0d bg, #F59E0B yellow, #EC4899 pink, #7C3AED purple, #4ADE80 green accents -->
-<div style="width:1080px;height:1440px;background:linear-gradient(160deg,#0f0326,#1a0a3e 40%,#0d0d0d);color:#fff;font-family:'Inter',sans-serif;display:flex;flex-direction:column;padding:72px;position:relative;overflow:hidden;">
+<div style="width:1080px;height:1350px;background:linear-gradient(160deg,#0f0326,#1a0a3e 40%,#0d0d0d);color:#fff;font-family:'Inter',sans-serif;display:flex;flex-direction:column;padding:72px;position:relative;overflow:hidden;">
   <!-- Glow effects -->
   <div style="position:absolute;top:-120px;right:-120px;width:480px;height:480px;background:radial-gradient(circle,#7C3AED33,transparent 70%);pointer-events:none;"></div>
   <div style="position:absolute;bottom:-100px;left:-100px;width:400px;height:400px;background:radial-gradient(circle,#F59E0B22,transparent 70%);pointer-events:none;"></div>