@growthub/cli 0.3.38 → 0.3.40

package/assets/worker-kits/growthub-open-higgsfield-studio-v1/growthub-meta/kit-standard.md

@@ -0,0 +1,47 @@
+# Kit Standard — Open Higgsfield Studio v1
+
+This document defines the locked contract for this kit.
+
+---
+
+## Required files contract
+
+Every path in `kit.json -> frozenAssetPaths` must exist in every valid release.
+
+---
+
+## Bundle contract
+
+The bundle manifest must remain aligned with `kit.json`:
+- `bundle.kitId` matches `kit.id`
+- `bundle.workerId` matches `entrypoint.workerId`
+- `requiredFrozenAssets` stays a subset of `frozenAssetPaths`
+
+---
+
+## Agent operating rules
+
+The entrypoint file is the operating law. `skills.md` is the methodology.
+
+Required invariants:
+- strict workflow order
+- repo inspection before planning when a fork exists
+- one primary studio selection
+- model recommendation with fallback
+- explicit provider adapter assumptions
+- operational output artifacts, not ideation-only text
+
+---
+
+## Runtime rules
+
+- no secrets stored in kit files
+- Muapi is the reference adapter, not a permanent monopoly
+- browser, desktop, and local-fork modes are all first-class
+- outputs are Markdown only
+
+---
+
+## Versioning rules
+
+Additive template/docs changes are minor-version work. Entry-point path changes or export-name changes require a major version bump.

package/assets/worker-kits/growthub-open-higgsfield-studio-v1/kit.json

@@ -0,0 +1,108 @@
+{
+  "schemaVersion": 2,
+  "kit": {
+    "id": "growthub-open-higgsfield-studio-v1",
+    "version": "1.0.0",
+    "name": "Growthub Agent Worker Kit — Open Higgsfield Studio",
+    "description": "Self-contained local execution environment for Open Higgsfield AI visual production. Produces implementation-ready visual briefs, prompt systems, shot plans, generation batches, model selections, and execution handoff artifacts for browser, desktop, and local fork workflows.",
+    "type": "worker",
+    "visibility": "public-open-source",
+    "sourceRepo": "growthub-local"
+  },
+  "entrypoint": {
+    "workerId": "open-higgsfield-studio-operator",
+    "path": "workers/open-higgsfield-studio-operator/CLAUDE.md"
+  },
+  "workerIds": [
+    "open-higgsfield-studio-operator"
+  ],
+  "agentContractPath": "workers/open-higgsfield-studio-operator/CLAUDE.md",
+  "brandTemplatePath": "brands/_template/brand-kit.md",
+  "publicExampleBrandPaths": [
+    "brands/growthub/brand-kit.md"
+  ],
+  "frozenAssetPaths": [
+    "QUICKSTART.md",
+    ".env.example",
+    "skills.md",
+    "output-standards.md",
+    "runtime-assumptions.md",
+    "validation-checklist.md",
+    "workers/open-higgsfield-studio-operator/CLAUDE.md",
+    "brands/_template/brand-kit.md",
+    "brands/growthub/brand-kit.md",
+    "brands/NEW-CLIENT.md",
+    "setup/clone-fork.sh",
+    "setup/patch-cors-proxy.sh",
+    "setup/verify-env.mjs",
+    "setup/check-deps.sh",
+    "output/README.md",
+    "templates/visual-campaign-brief.md",
+    "templates/studio-selection-brief.md",
+    "templates/model-selection-recommendation.md",
+    "templates/shot-plan.md",
+    "templates/prompt-matrix.md",
+    "templates/generation-batch-plan.md",
+    "templates/asset-tracking.md",
+    "templates/review-qa-checklist.md",
+    "templates/platform-ready-execution-handoff.md",
+    "templates/frame-analysis.md",
+    "templates/prompt-templates/image-generation.md",
+    "templates/prompt-templates/video-generation.md",
+    "templates/prompt-templates/lip-sync-generation.md",
+    "templates/prompt-templates/cinema-generation.md",
+    "examples/visual-campaign-brief-sample.md",
+    "examples/shot-plan-sample.md",
+    "examples/prompt-matrix-sample.md",
+    "examples/platform-ready-handoff-sample.md",
+    "docs/open-higgsfield-fork-integration.md",
+    "docs/provider-adapter-layer.md",
+    "growthub-meta/README.md",
+    "growthub-meta/kit-standard.md"
+  ],
+  "setupPaths": {
+    "quickstart": "QUICKSTART.md",
+    "envExample": ".env.example",
+    "setupDir": "setup/",
+    "outputDir": "output/"
+  },
+  "outputStandard": {
+    "type": "working-directory",
+    "description": "Exported folder is intended to be pointed at directly by the agent Working Directory. All outputs are Markdown files written to output/<client-slug>/<project-slug>/.",
+    "requiredPaths": [
+      "QUICKSTART.md",
+      ".env.example",
+      "kit.json",
+      "bundles/growthub-open-higgsfield-studio-v1.json",
+      "skills.md",
+      "workers/open-higgsfield-studio-operator/CLAUDE.md",
+      "brands/_template/brand-kit.md",
+      "brands/growthub/brand-kit.md",
+      "brands/NEW-CLIENT.md",
+      "setup/clone-fork.sh",
+      "setup/patch-cors-proxy.sh",
+      "setup/verify-env.mjs",
+      "setup/check-deps.sh",
+      "output/README.md",
+      "templates",
+      "docs",
+      "growthub-meta"
+    ]
+  },
+  "bundles": [
+    {
+      "id": "growthub-open-higgsfield-studio-v1",
+      "version": "1.0.0",
+      "path": "bundles/growthub-open-higgsfield-studio-v1.json"
+    }
+  ],
+  "executionMode": "export",
+  "activationModes": ["export"],
+  "compatibility": {
+    "cliMinVersion": "0.3.37"
+  },
+  "provenance": {
+    "sourceRepo": "growthub-local",
+    "frozenAt": "2026-04-10T00:00:00.000Z"
+  }
+}

package/assets/worker-kits/growthub-open-higgsfield-studio-v1/output/README.md

@@ -0,0 +1,34 @@
+# Output Directory
+
+All agent-generated deliverables are written here, organized by client and project.
+
+## Structure
+
+```
+output/
+  <client-slug>/
+    <project-slug>/
+      visual-campaign-brief.md
+      studio-selection-brief.md
+      model-selection-recommendation.md
+      shot-plan.md
+      prompt-matrix.md
+      generation-batch-plan.md
+      asset-tracking.md
+      review-qa-checklist.md
+      platform-ready-execution-handoff.md
+```
+
+## Usage
+
+The agent creates this structure automatically when it writes its first deliverable. You do not need to create folders manually.
+
+Use the `<client-slug>` to match your brand kit name (e.g. `growthub`, `acme-corp`) and the `<project-slug>` to identify the campaign or shoot (e.g. `q2-product-launch`, `founder-brand-video`).
+
+## Tracking deliverables
+
+Each completed package is logged in the active brand kit under `Deliverable History`:
+
+```
+- YYYY-MM-DD | Open Higgsfield Visual Package v<N> — <Project Name> | output/<client-slug>/<project-slug>/
+```

package/assets/worker-kits/growthub-open-higgsfield-studio-v1/output-standards.md

@@ -0,0 +1,133 @@
+# Output Standards — Open Higgsfield Studio v1
+
+This document defines the output contract for every artifact produced by this kit.
+
+---
+
+## OUTPUT FOLDER STRUCTURE
+
+```text
+output/
+└── <client-slug>/
+    └── <project-slug>/
+        ├── <ClientSlug>_VisualCampaignBrief_v<N>_<YYYYMMDD>.md
+        ├── <ClientSlug>_StudioSelectionBrief_v<N>_<YYYYMMDD>.md
+        ├── <ClientSlug>_ModelSelectionRecommendation_v<N>_<YYYYMMDD>.md
+        ├── <ClientSlug>_ShotPlan_v<N>_<YYYYMMDD>.md
+        ├── <ClientSlug>_PromptMatrix_v<N>_<YYYYMMDD>.md
+        ├── <ClientSlug>_GenerationBatchPlan_v<N>_<YYYYMMDD>.md
+        ├── <ClientSlug>_AssetTracking_v<N>_<YYYYMMDD>.md
+        ├── <ClientSlug>_ReviewQAChecklist_v<N>_<YYYYMMDD>.md
+        └── <ClientSlug>_PlatformReadyExecutionHandoff_v<N>_<YYYYMMDD>.md
+```
+
+---
+
+## REQUIRED OUTPUT TYPES
+
+Every full package must include:
+- visual campaign brief
+- studio selection brief
+- model selection recommendation
+- shot plan
+- prompt matrix
+- generation batch plan
+- asset tracking
+- review QA checklist
+- platform-ready execution handoff
+
+---
+
+## REQUIRED SECTIONS
+
+### Visual campaign brief
+1. Goal and deliverable
+2. Audience and platform context
+3. Brand and visual rules
+4. Content objective to visual strategy translation
+5. Asset inventory
+6. Studio hypothesis
+7. Output package summary
+
+### Studio selection brief
+1. Requested outcome
+2. Recommended studio
+3. Why this studio fits
+4. Input requirements
+5. Risks and fallback studio
+
+### Model selection recommendation
+1. Primary model table
+2. Fallback model table
+3. Endpoint and control assumptions
+4. Constraint notes
+
+### Shot plan
+1. Shot table
+2. Narrative arc notes
+3. Asset dependencies
+4. Review gates
+
+### Prompt matrix
+1. Prompt set metadata
+2. One row per output or shot
+3. Base prompt
+4. Variation prompt
+5. Negative / exclusion language
+6. Control settings
+
+### Generation batch plan
+1. Batch sequence table
+2. Submit order
+3. Polling / review cadence
+4. Retry rules
+
+### Asset tracking
+1. Asset inventory table
+2. Reuse status
+3. Upload status
+4. Ownership / notes
+
+### Review QA checklist
+1. Creative review
+2. Technical review
+3. Studio-specific review
+4. Handoff sign-off
+
+### Platform-ready execution handoff
+1. Runtime mode
+2. Repo inspection summary
+3. Provider adapter assumptions
+4. Exact execution steps
+5. Expected outputs
+6. Open questions
+
+---
+
+## FILE NAMING RULES
+
+Pattern:
+
+```text
+<ClientSlug>_<OutputType>_v<N>_<YYYYMMDD>.md
+```
+
+Rules:
+- `ClientSlug` is PascalCase
+- never overwrite an existing version
+- keep one artifact per file
+- Markdown only
+
+---
+
+## QUALITY BAR
+
+An output is complete when:
+- no placeholder text remains
+- the primary studio is explicit
+- the model recommendation includes a fallback
+- prompts are paste-ready
+- every shot has a defined asset path or asset request
+- batch sequencing reflects async submit/poll execution
+- browser / desktop / local-fork mode is named
+- review checklist is filled, not empty

package/assets/worker-kits/growthub-open-higgsfield-studio-v1/runtime-assumptions.md

@@ -0,0 +1,145 @@
+# Runtime Assumptions — Open Higgsfield Studio v1
+
+This document defines the runtime boundary for this kit.
+
+---
+
+## OVERVIEW
+
+This kit targets a self-contained local working directory used by an agent operating against one of three execution surfaces:
+
+| Mode | When to use | Assumption |
+|---|---|---|
+| `local-fork` | local checkout of Open Higgsfield AI is available | repo files can be inspected before planning |
+| `browser-hosted` | operator uses the hosted browser app | studio behavior follows the public hosted workflow |
+| `desktop-app` | operator uses the Electron app | same shared studio substrate, local desktop packaging |
+
+Default planning mode is `local-fork` when a checkout exists. Otherwise use `browser-hosted`.
+
+---
+
+## OPEN HIGGSFIELD AI ASSUMPTIONS
+
+Frozen upstream assumptions for this kit:
+- repo exposes four studios: image, video, lip sync, cinema
+- browser and desktop workflows both exist
+- `packages/studio/src/models.js` is the model source of truth
+- Muapi is the reference provider engine
+- API auth uses `x-api-key`
+- request flow is submit -> poll -> result
+- uploads are first-class for image-conditioned and audio-conditioned workflows
+- generation history and upload history matter to repeatability
+
+If the local fork differs, the fork wins.
+
+---
+
+## KNOWN FORK ISSUE — CORS POLICY (local-fork mode)
+
+**Status:** Fixed. Patch is applied automatically by `setup/clone-fork.sh`.
+
+**Root cause:** The upstream repo hardcodes `const BASE_URL = 'https://api.muapi.ai'` in
+`packages/studio/src/muapi.js`. All browser fetch/XHR calls go directly to the external
+API. `api.muapi.ai` does not return `Access-Control-Allow-Origin` headers, so every call
+from `localhost:3001` is blocked by the browser's CORS policy.
+
+**Errors you will see without the patch:**
+```
+Access to fetch at 'https://api.muapi.ai/api/v1/account/balance'
+from origin 'http://localhost:3001' has been blocked by CORS policy:
+No 'Access-Control-Allow-Origin' header is present on the requested resource.
+```
+
+**The fix:**
+1. `next.config.mjs` — rewrites `/muapi-proxy/:path*` → `https://api.muapi.ai/:path*` server-side
+2. `packages/studio/src/muapi.js` — `BASE_URL` changed to `'/muapi-proxy'`
+
+All browser calls now hit `localhost:3001/muapi-proxy/...` (same origin, no CORS).
+Next.js proxies them to `api.muapi.ai` from the server where CORS does not apply.
+
+**To apply manually if not already patched:**
+```bash
+bash setup/patch-cors-proxy.sh [path-to-fork]
+# defaults to ~/open-higgsfield-ai
+```
+
+**Affected functions in muapi.js:**
+- `getUserBalance` — `/api/v1/account/balance`
+- `submitAndPoll` — `/api/v1/${endpoint}`
+- `pollForResult` — `/api/v1/predictions/${requestId}/result`
+- `uploadFile` (XHR) — `/api/v1/upload_file`
+
+---
+
+## EXECUTION SURFACES
+
+### Local fork
+
+Expected operator flow:
+1. inspect `README.md`
+2. inspect `packages/studio/src/models.js`
+3. inspect `packages/studio/src/muapi.js`
+4. inspect relevant studio component
+5. prepare prompts, assets, and batch order
+6. execute through the local app surface the fork provides
+
+### Browser-hosted
+
+Expected operator flow:
+1. open hosted app
+2. load or enter API key
+3. select studio
+4. upload or reuse assets
+5. submit prompts in planned order
+6. poll and review results
+7. save result links and notes into output docs
+
+### Desktop app
+
+Expected operator flow:
+1. launch Electron app
+2. confirm API key availability
+3. select studio
+4. reuse locally stored asset history when possible
+5. run generation batches
+6. collect outputs and review notes
+
+---
+
+## LOCAL STATE ASSUMPTIONS
+
+The upstream repo describes persistent local state for:
+- API key storage
+- upload history
+- generation history
+- lip sync pending-job recovery
+
+The agent should treat these as workflow assets:
+- prefer reuse before re-upload
+- document when history should be checked
+- avoid assuming server-side persistence beyond the provider result URL
+
+---
+
+## FRAME ANALYSIS PRIMITIVE
+
+When a local reference video exists, frame extraction can be used for shot planning:
+
+```bash
+mkdir -p /tmp/open_higgsfield_frames
+ffmpeg -i "/path/to/reference.mp4" -vf fps=1/2 /tmp/open_higgsfield_frames/frame_%04d.jpg
+```
+
+Use this only when a local file is available. Do not promise it from a remote social URL alone.
+
+---
+
+## OUTPUT WRITING ASSUMPTION
+
+All deliverables are written as Markdown in:
+
+```text
+output/<client-slug>/<project-slug>/
+```
+
+The kit does not require its own npm install or custom CLI to be operational.

package/assets/worker-kits/growthub-open-higgsfield-studio-v1/setup/check-deps.sh

@@ -0,0 +1,37 @@
+#!/usr/bin/env bash
+# check-deps.sh — Verify local dependencies required for local-fork and frame-analysis workflows.
+# Run before your first local-fork session.
+set -e
+
+PASS=0
+FAIL=0
+
+check() {
+  local name="$1"
+  local cmd="$2"
+  local install_hint="$3"
+  if command -v "$cmd" >/dev/null 2>&1; then
+    echo "OK   $name ($(command -v "$cmd"))"
+    PASS=$((PASS + 1))
+  else
+    echo "MISSING  $name — $install_hint"
+    FAIL=$((FAIL + 1))
+  fi
+}
+
+echo "=== Growthub Open Higgsfield — Dependency Check ==="
+echo ""
+check "git"    "git"    "https://git-scm.com/downloads"
+check "node"   "node"   "https://nodejs.org"
+check "npm"    "npm"    "Comes with Node.js"
+check "ffmpeg" "ffmpeg" "brew install ffmpeg  OR  https://ffmpeg.org/download.html"
+echo ""
+echo "Passed: $PASS  |  Missing: $FAIL"
+
+if [ "$FAIL" -gt 0 ]; then
+  echo ""
+  echo "Install missing tools before running local-fork or frame-analysis workflows."
+  exit 1
+fi
+
+echo "All dependencies present. You are ready for local-fork execution."

package/assets/worker-kits/growthub-open-higgsfield-studio-v1/setup/clone-fork.sh

@@ -0,0 +1,40 @@
+#!/usr/bin/env bash
+# clone-fork.sh — Clone and boot the Open Higgsfield AI local fork
+# Run from any location. Installs to ~/open-higgsfield-ai and starts dev server on port 3001.
+set -e
+
+FORK_DIR="$HOME/open-higgsfield-ai"
+REPO_URL="https://github.com/Anil-matcha/Open-Higgsfield-AI"
+PORT=3001
+
+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 Open Higgsfield AI → $FORK_DIR"
+  git clone "$REPO_URL" "$FORK_DIR"
+fi
+
+cd "$FORK_DIR"
+
+echo "Installing dependencies..."
+npm install
+
+echo ""
+echo "Applying CORS proxy patch..."
+# The upstream repo calls api.muapi.ai directly from the browser, which is blocked
+# by CORS policy. This patch routes all API calls through the Next.js server.
+# See setup/patch-cors-proxy.sh for full explanation.
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+if [ -f "$SCRIPT_DIR/patch-cors-proxy.sh" ]; then
+  bash "$SCRIPT_DIR/patch-cors-proxy.sh" "$FORK_DIR"
+else
+  echo "WARNING: patch-cors-proxy.sh not found — skipping CORS patch."
+  echo "You may hit CORS errors when the studio calls api.muapi.ai from the browser."
+fi
+
+echo ""
+echo "Starting dev server on http://localhost:$PORT"
+echo "Press Ctrl+C to stop."
+echo ""
+npm run dev -- --port "$PORT"

package/assets/worker-kits/growthub-open-higgsfield-studio-v1/setup/patch-cors-proxy.sh

@@ -0,0 +1,139 @@
+#!/usr/bin/env bash
+# patch-cors-proxy.sh — Apply Next.js CORS proxy patch to the Open Higgsfield AI local fork
+#
+# WHY THIS EXISTS
+# ---------------
+# The upstream repo calls api.muapi.ai directly from the browser (BASE_URL in muapi.js).
+# api.muapi.ai does not return Access-Control-Allow-Origin headers, so every browser
+# request from localhost:3001 is blocked by CORS policy.
+#
+# THE FIX
+# -------
+# 1. next.config.mjs — adds a rewrites() block:
+#      /muapi-proxy/:path* → https://api.muapi.ai/:path*   (server-side, no CORS)
+#
+# 2. packages/studio/src/muapi.js — changes BASE_URL:
+#      'https://api.muapi.ai'  →  '/muapi-proxy'
+#
+# All fetch/XHR calls now hit the local Next.js server which proxies them server-side.
+# No browser cross-origin request is made. CORS policy never fires.
+#
+# USAGE
+# -----
+#   bash setup/patch-cors-proxy.sh [path-to-fork]
+#
+# Defaults to ~/open-higgsfield-ai if no path given.
+# Safe to run multiple times — idempotent.
+
+set -e
+
+FORK_DIR="${1:-$HOME/open-higgsfield-ai}"
+NEXT_CONFIG="$FORK_DIR/next.config.mjs"
+MUAPI_JS="$FORK_DIR/packages/studio/src/muapi.js"
+
+echo ""
+echo "=== CORS Proxy Patch ==="
+echo "Fork: $FORK_DIR"
+echo ""
+
+# ── Guard: fork must exist ──────────────────────────────────────────────────
+if [ ! -d "$FORK_DIR" ]; then
+  echo "ERROR: Fork not found at $FORK_DIR"
+  echo "Run setup/clone-fork.sh first."
+  exit 1
+fi
+
+if [ ! -f "$NEXT_CONFIG" ]; then
+  echo "ERROR: next.config.mjs not found at $NEXT_CONFIG"
+  exit 1
+fi
+
+if [ ! -f "$MUAPI_JS" ]; then
+  echo "ERROR: muapi.js not found at $MUAPI_JS"
+  exit 1
+fi
+
+# ── Idempotency check ───────────────────────────────────────────────────────
+if grep -q "muapi-proxy" "$NEXT_CONFIG" 2>/dev/null; then
+  echo "✓ next.config.mjs already patched — skipping."
+  NEXT_DONE=1
+else
+  NEXT_DONE=0
+fi
+
+if grep -q "muapi-proxy" "$MUAPI_JS" 2>/dev/null; then
+  echo "✓ muapi.js already patched — skipping."
+  MUAPI_DONE=1
+else
+  MUAPI_DONE=0
+fi
+
+if [ "$NEXT_DONE" -eq 1 ] && [ "$MUAPI_DONE" -eq 1 ]; then
+  echo ""
+  echo "Both files already patched. Nothing to do."
+  exit 0
+fi
+
+# ── Backup originals ────────────────────────────────────────────────────────
+if [ "$NEXT_DONE" -eq 0 ]; then
+  cp "$NEXT_CONFIG" "$NEXT_CONFIG.orig"
+fi
+if [ "$MUAPI_DONE" -eq 0 ]; then
+  cp "$MUAPI_JS" "$MUAPI_JS.orig"
+fi
+
+# ── Patch next.config.mjs ───────────────────────────────────────────────────
+if [ "$NEXT_DONE" -eq 0 ]; then
+  cat > "$NEXT_CONFIG" << 'NEXTEOF'
+/** @type {import('next').NextConfig} */
+const nextConfig = {
+  transpilePackages: ['studio'],
+
+  // CORS proxy — forward all Muapi API calls through the Next.js server so
+  // the browser never makes cross-origin requests to api.muapi.ai directly.
+  // muapi.js uses BASE_URL = '/muapi-proxy', so every fetch/XHR hits
+  // /muapi-proxy/api/v1/... which Next.js rewrites to api.muapi.ai server-side.
+  async rewrites() {
+    return [
+      {
+        source: '/muapi-proxy/:path*',
+        destination: 'https://api.muapi.ai/:path*',
+      },
+    ];
+  },
+};
+
+export default nextConfig;
+NEXTEOF
+  echo "✓ next.config.mjs patched — added /muapi-proxy rewrites()"
+fi
+
+# ── Patch muapi.js ──────────────────────────────────────────────────────────
+if [ "$MUAPI_DONE" -eq 0 ]; then
+  # Replace the BASE_URL line only (targeted sed, not full file rewrite)
+  sed -i.bak \
+    "s|const BASE_URL = 'https://api.muapi.ai';|// Proxy through Next.js to avoid CORS. All calls route through /muapi-proxy/:path*\n// which next.config.mjs rewrites to api.muapi.ai server-side — no CORS headers needed.\nconst BASE_URL = '/muapi-proxy';|" \
+    "$MUAPI_JS"
+  # Remove sed backup (we already made our own)
+  rm -f "$MUAPI_JS.bak"
+  echo "✓ muapi.js patched — BASE_URL changed to '/muapi-proxy'"
+fi
+
+# ── Verify ───────────────────────────────────────────────────────────────────
+echo ""
+echo "Verifying patch..."
+
+if grep -q "muapi-proxy" "$NEXT_CONFIG" && grep -q "muapi-proxy" "$MUAPI_JS"; then
+  echo "✓ Patch verified. Both files updated correctly."
+else
+  echo "ERROR: Patch verification failed. Check the files manually."
+  echo "  $NEXT_CONFIG"
+  echo "  $MUAPI_JS"
+  exit 1
+fi
+
+echo ""
+echo "CORS proxy patch complete."
+echo "Restart the dev server to pick up next.config.mjs changes:"
+echo "  npm run dev -- --port 3001"
+echo ""