@growthub/cli 0.3.53 → 0.3.54

package/assets/worker-kits/growthub-postiz-social-v1/output-standards.md

@@ -0,0 +1,127 @@
+# Output Standards
+
+**All Postiz Social Media Operator outputs must meet these standards before being delivered to a client.**
+
+---
+
+## Output Directory Structure
+
+```
+output/
+  <client-slug>/
+    <project-slug>/
+      SocialCampaignBrief_v<N>_<YYYYMMDD>.md
+      ContentCalendar_v<N>_<YYYYMMDD>.md
+      PlatformPublishingPlan_v<N>_<YYYYMMDD>.md
+      CaptionCopyDeck_v<N>_<YYYYMMDD>.md
+      SchedulingManifest_v<N>_<YYYYMMDD>.md    (if scheduling requested)
+      AnalyticsBrief_v<N>_<YYYYMMDD>.md        (if analytics data available)
+      ClientProposal_v<N>_<YYYYMMDD>.md        (if requested)
+      scheduling-manifest.json                  (always when scheduling — powers Postiz API)
+```
+
+---
+
+## File Naming Convention
+
+```
+<ClientSlug>_<OutputType>_v<N>_<YYYYMMDD>.md
+```
+
+| Part | Rules | Example |
+|---|---|---|
+| ClientSlug | TitleCase, no spaces, no special chars | `UrbanCycle` |
+| OutputType | CamelCase from the list below | `ContentCalendar` |
+| Version | `v` + integer, starting at 1 | `v1` |
+| Date | `YYYYMMDD` format | `20260415` |
+
+**Output type names:**
+
+| Artifact | OutputType string |
+|---|---|
+| Social Campaign Brief | `SocialCampaignBrief` |
+| Content Calendar | `ContentCalendar` |
+| Platform Publishing Plan | `PlatformPublishingPlan` |
+| Caption Copy Deck | `CaptionCopyDeck` |
+| Scheduling Manifest | `SchedulingManifest` |
+| Analytics Brief | `AnalyticsBrief` |
+| Client Proposal | `ClientProposal` |
+
+---
+
+## Required Sections Per Artifact
+
+Each artifact must include all sections from its template. Incomplete sections must be marked `<!-- data-gap: reason -->` — never left blank without explanation.
+
+| Artifact | Minimum Required Sections |
+|---|---|
+| SocialCampaignBrief | Project Overview, Campaign Objective, Target Platforms, Audience Profile, KPI Targets, Content Theme Pillars, Brand Voice |
+| ContentCalendar | Calendar Header (client, period, platforms), Calendar Table (all rows with all columns), Posting Cadence Summary |
+| PlatformPublishingPlan | Per-platform rows (all selected platforms), Format spec, Frequency, Best posting times, Content mix ratio |
+| CaptionCopyDeck | Per-post entries (A/B/C variants each), Hashtag sets, Character counts, Media asset notes |
+| SchedulingManifest | Manifest header, All post entries (postId, platform, scheduledAt, content, mediaAssets, status) |
+| AnalyticsBrief | Period summary, Per-platform metrics table, Top 3 posts, Bottom 3 posts, Recommendations |
+| ClientProposal | Campaign Overview, Platform Mix rationale, Content Strategy, Deliverables scope, Pricing (3 tiers), ROI Projection |
+
+---
+
+## Quality Bar
+
+### Platform-Accurate
+
+- All platform IDs must match the official list in `docs/platform-coverage.md`
+- Character limits must be respected for every caption variant
+- Post types must be valid for the target platform (e.g., no carousels on TikTok)
+
+### Caption Quality
+
+- Every caption must have an explicit CTA — "Learn more" is acceptable; blank is not
+- All 3 variants (A/B/C) must be meaningfully different — not minor word swaps
+- Hashtags must be relevant to the content — no generic filler (#love, #instagood) unless platform context demands it
+
+### Scheduling Manifest
+
+- `scheduledAt` timestamps must be ISO 8601 format with timezone offset
+- `postId` must follow the naming convention: `<client-slug>-<YYYYMMDD>-<platform>-<sequence>`
+- All posts in the manifest must have a corresponding entry in the ContentCalendar
+- `workspaceId` must be present when Postiz API is targeted (even if placeholder in agent-only mode)
+
+### No Filler
+
+- Every sentence must either present data, explain a constraint, or specify an action
+- Remove phrases like "Great content is key" — replace with the actual content specification
+- Recommendations must be specific: name the exact platform, posting time, content format, and expected impact
+
+### Actionable
+
+- Every post entry in the ContentCalendar must have a ready-to-use caption variant
+- Every platform in the PlatformPublishingPlan must have a posting time recommendation
+- Every finding in the AnalyticsBrief must have a corresponding action item
+
+### Consistent
+
+- Platform names in all artifacts must use the same slug format from `docs/platform-coverage.md`
+- Dates must be consistent across all artifacts
+- Client name must match the brand kit exactly
+
+---
+
+## Versioning Rules
+
+| Scenario | Action |
+|---|---|
+| First campaign for a client | All files at v1 |
+| Campaign revised post-approval | Increment all files to v2 |
+| Partial update (one artifact revised) | Increment only the revised artifact's version |
+| New campaign, same client | Start new project-slug, all files at v1 |
+
+---
+
+## scheduling-manifest.json
+
+This file must always be written to the output directory when scheduling is requested. It is the machine-readable record required for:
+- Postiz API bulk scheduling (`POST /api/v1/posts/bulk`)
+- Manual review before submitting to Postiz
+- Campaign audit trail
+
+See `templates/scheduling-manifest.md` for the complete format with all required fields.

package/assets/worker-kits/growthub-postiz-social-v1/runtime-assumptions.md

@@ -0,0 +1,159 @@
+# Runtime Assumptions
+
+**Frozen at kit creation: 2026-04-15. Update this file when upstream Postiz fork behavior changes.**
+
+---
+
+## Execution Mode Overview
+
+| Mode | Requirements | Fork Used? | Postiz API? | Scheduling? | Caption AI? |
+|---|---|---|---|---|---|
+| `local-fork` | Node 18+, Docker, Postiz running | Yes | Yes | Yes | Yes |
+| `agent-only` | Nothing (Claude Code only) | No | No | Dry-run JSON only | Yes |
+| `hybrid` | ANTHROPIC_API_KEY + Postiz running | Yes | Yes | Yes | Yes |
+
+### Choosing a Mode
+
+- **Use `local-fork`** when you need real Postiz API scheduling, multi-workspace support, or live BullMQ queue management.
+- **Use `agent-only`** when Postiz is not installed or when you only need campaign planning, content calendars, and caption drafts.
+- **Use `hybrid`** when you want enhanced AI caption generation via Anthropic API alongside live Postiz scheduling.
+
+---
+
+## Postiz Upstream Assumptions
+
+These are the assumptions frozen at kit creation time about the Postiz fork at https://github.com/gitroomhq/postiz-app.
+
+### Service Topology
+
+| Service | Container | Default Port | Purpose |
+|---|---|---|---|
+| Postiz App | `postiz` | 3000 | NestJS API + Next.js frontend |
+| PostgreSQL | `postiz-postgres` | 5432 | Primary data store |
+| Redis | `postiz-redis` | 6379 | BullMQ job queue, session cache |
+
+All services are defined in `docker-compose.yml` at the fork root.
+
+### Node.js Environment
+
+| Requirement | Value | Notes |
+|---|---|---|
+| Node version | 18+ | Tested on 18 and 20 LTS |
+| Package manager | pnpm | `pnpm install` from repo root |
+| Monorepo structure | Turborepo | `apps/` and `libraries/` |
+| Backend framework | NestJS | `apps/backend/` |
+| Frontend framework | Next.js 14 | `apps/frontend/` |
+
+### 28+ Platform Integrations (at time of freeze)
+
+The following platform integrations ship with the Postiz codebase under `libraries/nestjs-libraries/src/integrations/`:
+
+| Platform | Integration ID | Auth Method |
+|---|---|---|
+| Instagram | `instagram` | Meta OAuth |
+| LinkedIn | `linkedin` | LinkedIn OAuth |
+| TikTok | `tiktok` | TikTok OAuth |
+| X/Twitter | `twitter` | Twitter OAuth 2.0 |
+| YouTube | `youtube` | Google OAuth |
+| Pinterest | `pinterest` | Pinterest OAuth |
+| Reddit | `reddit` | Reddit OAuth |
+| Facebook | `facebook` | Meta OAuth |
+| Bluesky | `bluesky` | AT Protocol credentials |
+| Mastodon | `mastodon` | Mastodon OAuth (instance-specific) |
+| Slack | `slack` | Slack OAuth |
+| Telegram | `telegram` | Telegram Bot API token |
+| Discord | `discord` | Discord Bot token |
+| Threads | `threads` | Meta OAuth |
+| Dribbble | `dribbble` | Dribbble OAuth |
+| Tumblr | `tumblr` | Tumblr OAuth |
+| Medium | `medium` | Medium OAuth |
+| DevTo | `devto` | DEV API key |
+| Hashnode | `hashnode` | Hashnode API key |
+| Lemmy | `lemmy` | Lemmy credentials |
+| Nostr | `nostr` | Nostr keypair |
+
+*Additional platforms may be available in newer Postiz releases. Check `libraries/nestjs-libraries/src/integrations/` in the fork for the current list.*
+
+### BullMQ Queue Architecture
+
+- Queue name: `post` (primary publishing queue)
+- Job type: `publish-post`
+- Delay scheduling: supported via BullMQ `delay` option (milliseconds from now)
+- Retry logic: 3 attempts, exponential backoff (configurable in Postiz admin)
+- Dead letter queue: failed jobs visible in Postiz admin at `/admin/queues`
+
+### AI Caption Generation
+
+Postiz ships with optional AI caption generation. At time of freeze:
+- OpenAI GPT-4o: enabled when `OPENAI_API_KEY` is set in Postiz `.env`
+- Anthropic Claude: enabled when `ANTHROPIC_API_KEY` is set
+- AI captions are generated via `POST /api/v1/posts/ai/generate`
+- This kit uses the agent's own Anthropic API key (via `ANTHROPIC_API_KEY` in this kit's `.env`) for caption drafts — independent of the Postiz instance's AI config
+
+---
+
+## Execution Surface Flows
+
+### Local-Fork Mode
+
+```
+User request → Environment gate (Step 0)
+  ↓
+Read skills.md + brand kit (Step 1)
+  ↓
+Read runtime docs (Step 2)
+  ↓
+Inspect Postiz fork: docker ps, API healthcheck, platform list (Step 3)
+  ↓
+4-question gate (Step 4)
+  ↓
+Select /postiz command (Step 5)
+  ↓
+Phase 1: Campaign strategy + platform selection (Step 6)
+  ↓
+Phase 2: Content calendar + caption copy deck (Step 7)
+  ↓
+Phase 3: Scheduling manifest → POST /api/v1/posts/bulk (Step 8)
+  ↓
+Artifact package: 5–7 Markdown files + scheduling-manifest.json (Step 9)
+  ↓
+Log deliverable → brand kit DELIVERABLES LOG (Step 10)
+```
+
+### Agent-Only Mode
+
+```
+User request → Environment gate (Step 0 — confirm agent-only)
+  ↓
+Read skills.md + brand kit (Step 1)
+  ↓
+Read runtime docs (Step 2)
+  ↓
+Skip fork inspection (Step 3 — N/A)
+  ↓
+4-question gate (Step 4)
+  ↓
+Select /postiz command (Step 5)
+  ↓
+Phase 1: Campaign strategy + platform selection (Step 6)
+  ↓
+Phase 2: Content calendar + caption copy deck (Step 7)
+  ↓
+Phase 3: Dry-run scheduling manifest (JSON — for manual submission) (Step 8)
+  ↓
+Artifact package: 5–7 Markdown files + scheduling-manifest.json (Step 9)
+  ↓
+Log deliverable → brand kit DELIVERABLES LOG (Step 10)
+```
+
+---
+
+## Output Assumption
+
+All outputs are Markdown files written to:
+
+```
+output/<client-slug>/<project-slug>/
+```
+
+The scheduling manifest is a JSON file (`scheduling-manifest.json`) written alongside the Markdown artifacts. It is the machine-readable record for Postiz API submission.

package/assets/worker-kits/growthub-postiz-social-v1/setup/check-deps.sh

@@ -0,0 +1,117 @@
+#!/usr/bin/env bash
+# check-deps.sh — Verify system dependencies for the Postiz Social Media Studio
+# Usage: bash setup/check-deps.sh
+set -e
+
+GREEN="\033[0;32m"
+RED="\033[0;31m"
+YELLOW="\033[0;33m"
+RESET="\033[0m"
+
+PASS=0
+FAIL=0
+WARN=0
+
+ok() {
+  echo -e "  ${GREEN}✓${RESET}  $1"
+  PASS=$((PASS + 1))
+}
+
+fail() {
+  echo -e "  ${RED}✗${RESET}  $1"
+  FAIL=$((FAIL + 1))
+}
+
+warn() {
+  echo -e "  ${YELLOW}⚠${RESET}  $1"
+  WARN=$((WARN + 1))
+}
+
+echo "=== Growthub Postiz Social Media Studio — Dependency Check ==="
+echo ""
+
+# --- Node.js ---
+if command -v node &>/dev/null; then
+  NODE_VER=$(node --version | sed 's/v//')
+  NODE_MAJOR=$(echo "$NODE_VER" | cut -d. -f1)
+  if [ "$NODE_MAJOR" -ge 18 ]; then
+    ok "node v${NODE_VER} (18+ required)"
+  else
+    fail "node v${NODE_VER} — version 18+ required. Install from https://nodejs.org"
+  fi
+else
+  fail "node — not found. Install from https://nodejs.org"
+fi
+
+# --- npm ---
+if command -v npm &>/dev/null; then
+  ok "npm $(npm --version)"
+else
+  warn "npm — not found. Usually installed with Node.js."
+fi
+
+# --- pnpm (used by Postiz monorepo) ---
+if command -v pnpm &>/dev/null; then
+  ok "pnpm $(pnpm --version)"
+else
+  warn "pnpm — not found. Required if building Postiz from source. Install: npm install -g pnpm"
+fi
+
+# --- Docker ---
+if command -v docker &>/dev/null; then
+  DOCKER_VER=$(docker --version | awk '{print $3}' | sed 's/,//')
+  ok "docker $DOCKER_VER"
+  # Check Docker daemon is running
+  if docker info &>/dev/null 2>&1; then
+    ok "docker daemon is running"
+  else
+    fail "docker daemon is not running. Start Docker Desktop or: sudo systemctl start docker"
+  fi
+else
+  fail "docker — not found. Install from https://docker.com"
+fi
+
+# --- Docker Compose ---
+if docker compose version &>/dev/null 2>&1; then
+  COMPOSE_VER=$(docker compose version --short 2>/dev/null || echo "unknown")
+  ok "docker compose $COMPOSE_VER"
+elif command -v docker-compose &>/dev/null; then
+  warn "docker-compose (standalone) found. Prefer Docker Compose V2 plugin (docker compose)."
+else
+  fail "docker compose — not found. Install Docker Desktop or the Docker Compose plugin."
+fi
+
+# --- Git ---
+if command -v git &>/dev/null; then
+  ok "git $(git --version | awk '{print $3}')"
+else
+  fail "git — not found. Install from https://git-scm.com/downloads"
+fi
+
+# --- curl ---
+if command -v curl &>/dev/null; then
+  ok "curl $(curl --version | head -1 | awk '{print $2}')"
+else
+  warn "curl — not found. Used for API healthchecks."
+fi
+
+# --- Summary ---
+echo ""
+echo "=== Summary ==="
+echo "  Passed:   $PASS"
+if [ "$WARN" -gt 0 ]; then
+  echo -e "  ${YELLOW}Warnings: $WARN${RESET}"
+fi
+if [ "$FAIL" -gt 0 ]; then
+  echo -e "  ${RED}Failed:   $FAIL${RESET}"
+  echo ""
+  echo "Install missing dependencies and re-run this script."
+  exit 1
+else
+  echo ""
+  if [ "$WARN" -gt 0 ]; then
+    echo -e "${YELLOW}Dependencies OK with warnings. Local-fork mode may need attention.${RESET}"
+  else
+    echo -e "${GREEN}All dependencies satisfied.${RESET}"
+  fi
+fi

package/assets/worker-kits/growthub-postiz-social-v1/setup/clone-fork.sh

@@ -0,0 +1,83 @@
+#!/usr/bin/env bash
+# clone-fork.sh — Clone Postiz and start the local workspace via Docker Compose
+# Usage: bash setup/clone-fork.sh
+set -e
+
+FORK_DIR="${POSTIZ_FORK_PATH:-$HOME/postiz-app}"
+REPO_URL="https://github.com/gitroomhq/postiz-app"
+
+echo "=== Growthub Postiz Social Media Studio — Fork Setup ==="
+echo ""
+
+if [ -d "$FORK_DIR" ]; then
+  echo "Fork already exists at $FORK_DIR — skipping clone."
+  echo "To re-clone, remove the directory first: rm -rf $FORK_DIR"
+else
+  echo "Cloning Postiz → $FORK_DIR"
+  git clone "$REPO_URL" "$FORK_DIR"
+  echo "Clone complete."
+fi
+
+echo ""
+echo "Checking for .env configuration..."
+if [ ! -f "$FORK_DIR/.env" ]; then
+  if [ -f "$FORK_DIR/.env.example" ]; then
+    cp "$FORK_DIR/.env.example" "$FORK_DIR/.env"
+    echo "Copied .env.example to .env — edit $FORK_DIR/.env with your credentials before starting services."
+    echo ""
+    echo "  Minimum required values in $FORK_DIR/.env:"
+    echo "    DATABASE_URL=..."
+    echo "    REDIS_URL=..."
+    echo "    JWT_SECRET=..."
+    echo "    NEXTAUTH_SECRET=..."
+    echo ""
+    echo "  Then re-run this script to start the services."
+    exit 0
+  else
+    echo "WARNING: No .env.example found in the Postiz repo. Create $FORK_DIR/.env manually."
+    echo "See https://docs.postiz.com/configuration/environment-variables for required variables."
+    exit 1
+  fi
+fi
+
+echo ""
+echo "Starting Postiz services via Docker Compose..."
+cd "$FORK_DIR"
+docker compose up -d
+
+echo ""
+echo "Waiting for Postiz API to become healthy..."
+MAX_WAIT=60
+WAITED=0
+while [ "$WAITED" -lt "$MAX_WAIT" ]; do
+  if curl -s http://localhost:3000/api/healthcheck > /dev/null 2>&1; then
+    echo "Postiz API is healthy."
+    break
+  fi
+  sleep 2
+  WAITED=$((WAITED + 2))
+  echo "  Waiting... (${WAITED}s elapsed)"
+done
+
+if [ "$WAITED" -ge "$MAX_WAIT" ]; then
+  echo ""
+  echo "WARNING: Postiz API did not become healthy within ${MAX_WAIT}s."
+  echo "Check docker logs: docker compose logs -f postiz"
+  echo "The services may still be starting — try again in 30 seconds."
+  exit 1
+fi
+
+echo ""
+echo "=== Postiz workspace is ready ==="
+echo ""
+echo "  Admin UI:  http://localhost:3000"
+echo "  API:       http://localhost:3000/api"
+echo ""
+echo "Next steps:"
+echo "  1. Open http://localhost:3000 and complete the initial setup wizard"
+echo "  2. Connect your social media accounts in Settings > Integrations"
+echo "  3. Copy your Workspace ID from Settings > Workspace"
+echo "  4. Set POSTIZ_WORKSPACE_ID in this kit's .env file"
+echo "  5. Run: node setup/verify-env.mjs"
+echo ""
+echo "To stop Postiz: docker compose stop (from $FORK_DIR)"

package/assets/worker-kits/growthub-postiz-social-v1/setup/verify-env.mjs

@@ -0,0 +1,99 @@
+#!/usr/bin/env node
+// verify-env.mjs — Verify Postiz fork and kit environment configuration
+// Usage: node setup/verify-env.mjs
+
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+
+const RED = "\x1b[31m";
+const GREEN = "\x1b[32m";
+const YELLOW = "\x1b[33m";
+const RESET = "\x1b[0m";
+
+let allPassed = true;
+const results = [];
+
+function check(label, passed, detail = "") {
+  const icon = passed ? `${GREEN}✓${RESET}` : `${RED}✗${RESET}`;
+  results.push({ label, passed, detail, icon });
+  if (!passed) allPassed = false;
+}
+
+function warn(label, detail = "") {
+  results.push({ label, passed: null, detail, icon: `${YELLOW}⚠${RESET}` });
+}
+
+console.log("Growthub Postiz Social Media Studio — Environment Verification");
+console.log("=".repeat(60));
+console.log("");
+
+// --- Check 1: Postiz fork path ---
+const forkPath = process.env.POSTIZ_FORK_PATH ?? join(homedir(), "postiz-app");
+const forkExists = existsSync(forkPath);
+check("Postiz fork directory exists", forkExists, forkExists ? forkPath : `Not found at ${forkPath}`);
+
+if (forkExists) {
+  const dockerCompose = existsSync(join(forkPath, "docker-compose.yml"));
+  check("docker-compose.yml present in fork", dockerCompose);
+
+  const envFile = existsSync(join(forkPath, ".env"));
+  check("Postiz .env file present", envFile, envFile ? "" : `Run: cp ${forkPath}/.env.example ${forkPath}/.env`);
+}
+
+// --- Check 2: Postiz API reachability ---
+const postizApiUrl = process.env.POSTIZ_API_URL ?? "http://localhost:3000";
+let apiHealthy = false;
+try {
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), 3000);
+  const res = await fetch(`${postizApiUrl}/api/healthcheck`, { signal: controller.signal });
+  clearTimeout(timeout);
+  apiHealthy = res.ok;
+} catch {
+  apiHealthy = false;
+}
+check("Postiz API is reachable", apiHealthy, apiHealthy ? postizApiUrl : `Not reachable at ${postizApiUrl} — run: bash setup/clone-fork.sh`);
+
+// --- Check 3: Workspace ID ---
+const workspaceId = process.env.POSTIZ_WORKSPACE_ID;
+if (workspaceId && workspaceId !== "your_workspace_uuid_here") {
+  check("POSTIZ_WORKSPACE_ID is set", true, workspaceId.slice(0, 8) + "...");
+} else {
+  warn("POSTIZ_WORKSPACE_ID not set", "Required for scheduling manifest submission — find it in Postiz Settings > Workspace");
+}
+
+// --- Check 4: Anthropic API key ---
+const anthropicKey = process.env.ANTHROPIC_API_KEY;
+if (!anthropicKey || anthropicKey === "your_anthropic_key_here") {
+  warn("ANTHROPIC_API_KEY not set", "Optional — required for AI-enhanced caption generation in agent-only and hybrid modes");
+} else if (anthropicKey.startsWith("sk-ant-")) {
+  check("ANTHROPIC_API_KEY format is valid", true);
+} else {
+  check("ANTHROPIC_API_KEY format is valid", false, "Key does not start with sk-ant- — check your Anthropic console");
+}
+
+// --- Print results ---
+console.log("Results:");
+for (const { icon, label, detail } of results) {
+  const detailStr = detail ? `  → ${detail}` : "";
+  console.log(`  ${icon}  ${label}${detailStr}`);
+}
+
+console.log("");
+
+if (allPassed) {
+  console.log(`${GREEN}All checks passed. Ready for local-fork or hybrid mode.${RESET}`);
+} else {
+  const warnings = results.filter((r) => r.passed === null);
+  const failures = results.filter((r) => r.passed === false);
+  if (failures.length > 0) {
+    console.log(`${RED}${failures.length} check(s) failed. See details above.${RESET}`);
+    if (!apiHealthy) {
+      console.log(`\n  To start Postiz: bash setup/clone-fork.sh`);
+    }
+  }
+  if (warnings.length > 0 && failures.length === 0) {
+    console.log(`${YELLOW}Checks passed with warnings. Agent-only mode is available.${RESET}`);
+  }
+}