@julioventura/opensquad 0.1.17

package/skills/run-dashboard/SKILL.md

@@ -0,0 +1,173 @@
+---
+name: run-dashboard
+description: Generate a modern DASHBOARD-RUN HTML snapshot plus JSON data for a completed squad run, including checklist, publishing links, artifacts, errors, and refreshable platform metrics when credentials are available.
+description_pt-BR: Gera um DASHBOARD-RUN em HTML e um snapshot JSON para uma run concluída, com checklist, links de publicação, artefatos, erros e métricas atualizáveis quando houver credenciais.
+type: script
+version: "1.0.0"
+script:
+  path: scripts/generate.js
+  runtime: node
+  invoke: "node --env-file=.env {skill_path}/scripts/generate.js --run-dir \"{run_dir}\""
+env:
+  - INSTAGRAM_ACCESS_TOKEN
+  - INSTAGRAM_USER_ID
+  - FACEBOOK_PAGE_ID
+  - FACEBOOK_PAGE_ACCESS_TOKEN
+  - YOUTUBE_CLIENT_ID
+  - YOUTUBE_CLIENT_SECRET
+  - YOUTUBE_REFRESH_TOKEN
+  - YOUTUBE_CHANNEL_ID
+  - SUPABASE_URL
+  - SUPABASE_ANON_KEY
+  - SUPABASE_SERVICE_ROLE_KEY
+categories: [reporting, dashboard, html, publishing, operations]
+---
+
+# Run Dashboard
+
+Use this skill after a run completes to generate a standalone HTML dashboard and a sibling JSON snapshot inside the run folder.
+
+Inside Opensquad, this skill is part of automatic run finalization. Do not stop to ask for separate confirmation before generating the dashboard. Run it, validate the files, and report the result.
+
+The generated HTML should be branded as `DASHBOARD-RUN`.
+
+## When to use
+
+- Finalizing any completed run that should leave behind a visual operational report
+- Regenerating a dashboard after publishing recovery, metric refresh, or manual edits to run artifacts
+- Producing an editable HTML file that can be opened in a simple code-and-preview editor
+- Closing the operational report after Instagram, Facebook, YouTube, and optional `jornal-matutino` outputs have already finished
+
+## Output contract
+
+Always generate both files in the run folder:
+
+- `run-dashboard.html`
+- `run-dashboard.data.json`
+
+The HTML must stay standalone and editable with inline CSS/JS. The JSON is the refreshable data source for the dashboard.
+
+If the squad `channel-config.yaml` declares `dashboard.static_publish.enabled: true`, generating the dashboard should also publish the latest and archived static snapshots automatically as part of the same finalization pass.
+
+## Static publish mode
+
+When you need to force static publish explicitly, generate it with:
+
+```bash
+node --env-file=.env skills/run-dashboard/scripts/generate.js \
+  --workspace-root . \
+  --run-dir "squads/musicplay-club/output/2026-05-19-020010" \
+  --publish-static
+```
+
+Prefer passing a concrete run folder. Skills that consume versioned artifacts may point to the sibling `v1/` directory, but the run dashboard itself should target the parent run folder.
+
+If the squad channel config declares `dashboard.static_publish.publish_dir_env` and the corresponding env var points to the server webroot folder, the command publishes:
+
+- latest snapshot as `index.html`
+- archived snapshot as `<run-id>.html`
+- supporting copied files under `assets/latest/` and `assets/<run-id>/`
+
+The published HTML remains standalone with the embedded snapshot and does not require the local dashboard server to open.
+
+If `dashboard.static_publish.transport` is set to `ftp`, the same command uploads the generated snapshot to the remote folder declared by `publish_dir_env`, using the FTP env keys declared in the squad config.
+
+If `dashboard.static_publish.transport` is `both`, treat local publish and remote FTP publish as two separate validations. A successful write to the local publish dir does not prove the public site is updated.
+
+Before treating a run as closed, preflight the static publish inputs declared in `channel-config.yaml`:
+
+- the env key referenced by `publish_dir_env`
+- the FTP env keys referenced by `dashboard.static_publish.ftp.*` when transport is `ftp` or `both`
+
+If these env keys are missing, report the configuration defect explicitly. Do not misclassify it as a dashboard rendering failure.
+
+After a `both` or `ftp` publish, validate the public latest URLs explicitly, not just the local files:
+
+- `index.html`
+- `run-dashboard.data.json`
+- `youtube.html` when the run includes a YouTube link
+
+Also validate the archive URL generated from the run ID. The archive file name comes from the dashboard payload `runId`, not from the publish timestamp shown in `publish-result.md`.
+
+If the archive URLs update but the fixed latest URLs stay stale, treat that as a remote sync issue on the latest files. The operational recovery path is to overwrite the remote `index.html`, `run-dashboard.data.json`, and `youtube.html` explicitly via FTP using the freshly generated local publish directory contents, then revalidate the public URLs before closing the run.
+
+If `dashboard.static_publish.enabled: true` is already present in the squad config, the default run-finalization call should do this automatically even without an explicit `--publish-static` flag.
+
+## Required content
+
+- Header with squad, run ID, status, date/time, and last refresh timestamp
+- Checklist display summarizing what was completed in the run
+- Publishing display showing where the content was posted
+- Link buttons for Instagram, Facebook, and YouTube when URLs exist
+- Error/problem display summarizing residual issues and blocking incidents
+- Artifact display with the important run files used to build the dashboard
+- Metrics display with the best snapshot available from Instagram, Facebook, and YouTube
+
+## Metrics rules
+
+- Instagram: try likes plus the first available metric among views, video views, plays, or impressions
+- Facebook: try post reactions, comments, and shares when a Page token can be resolved
+- YouTube: try views, likes, comments, and published timestamp using the channel OAuth credentials
+- If a metric cannot be fetched, render `N/A` without failing the dashboard
+
+## Refresh behavior
+
+- The HTML refresh button should try to fetch `run-dashboard.data.json` from the same folder with cache-busting
+- If the JSON cannot be fetched in the current environment, keep showing the embedded snapshot instead of breaking the page
+- When the dashboard is served through the local `serve.js` helper, the refresh button should first call the local regeneration endpoint so the JSON snapshot and metrics are rebuilt before the page re-renders
+
+## Visual previews
+
+- When slide renders exist in `images/`, show them as preview cards and prefer linking each card to the editable `slide-xx.html` source
+- When a YouTube thumbnail exists in `thumbs/` or is declared in `publish-result.md`, show it in the preview section and link it to the published video when possible
+
+## Supabase policy
+
+- Dashboard generation must not depend on Supabase
+- If a future run persists dashboard snapshots, templates, profiles, or customization data in Supabase, every Opensquad-managed table name must use the `os_` prefix
+- Examples: `os_profiles`, `os_run_reports`, `os_dashboard_templates`
+
+## Default layout (simplified format — v2)
+
+All squads should use the simplified `run-dashboard-simple.template.html` layout unless the squad's local config explicitly overrides it. The original complex template (`run-dashboard.template.html`) remains available for squads that need metrics refresh, collapsible panels, and modal zoom.
+
+The simplified layout contains exactly these containers, in order:
+
+1. **Header** — Squad name, run ID, publish date, status badge
+2. **Row 1 (2 columns):**
+   - **Resumo do Tema** — Pauta, ângulo editorial, tom aplicado
+   - **Publicações** — Links clicáveis para Instagram, Facebook, YouTube e newsletter status
+3. **Row 2 (full width):**
+   - **Legenda e Metadados** — Legenda completa + hashtags
+4. **Carrossel Visual Produzido** — Grid de **4 slides por linha** (responsivo: 2 em tablet, 1 em mobile)
+5. **Row 3 (3 columns):**
+   - **Descrição — Instagram** — Texto exato usado no post do Instagram
+   - **Descrição — Facebook** — Texto exato usado no post do Facebook
+   - **Descrição — YouTube** — Texto exato usado na descrição do vídeo (incluindo FONTES VERIFICADAS)
+
+### Template placeholders
+
+The template uses `{{PLACEHOLDER}}` tokens that agents must replace with actual run data:
+
+| Placeholder | Source |
+|---|---|
+| `{{SQUAD_NAME}}` | Squad directory name |
+| `{{RUN_ID}}` | Run folder name |
+| `{{TOPIC}}` | `content-package.md` → Tema central |
+| `{{ANGLE}}` | `content-package.md` → Ângulo editorial |
+| `{{TONE}}` | `content-package.md` → Tom aplicado |
+| `{{IG_URL}}` | `publish-result.md` → Instagram URL |
+| `{{FB_URL}}` | `publish-result.md` → Facebook URL |
+| `{{YT_URL}}` | `publish-result.md` → YouTube URL |
+| `{{CAPTION_FULL}}` | `content-package.md` → Legenda section |
+| `{{HASHTAGS}}` | `content-package.md` → Hashtags section |
+| `{{DESC_INSTAGRAM}}` | Exact caption sent to Instagram publish script |
+| `{{DESC_FACEBOOK}}` | Exact caption sent to Facebook publish script |
+| `{{DESC_YOUTUBE}}` | Exact description sent to YouTube publish script |
+
+### Squads using this format
+
+- `odontologia-news` — default
+- `musicplay-club` — default
+
+Any new squad inherits this layout unless its pipeline explicitly specifies `dashboard_template: complex`.

package/skills/run-dashboard/scripts/finalize-state.js

@@ -0,0 +1,273 @@
+import { readFile, writeFile } from 'node:fs/promises';
+import { fileURLToPath } from 'node:url';
+import { join, resolve } from 'node:path';
+import process from 'node:process';
+
+const DEFAULT_ARGS = {
+  runDir: '',
+  workspaceRoot: process.cwd(),
+  force: false,
+};
+
+function parseArgs(argv) {
+  const args = { ...DEFAULT_ARGS };
+
+  for (let index = 2; index < argv.length; index += 1) {
+    const current = argv[index];
+    if (current === '--run-dir' && index + 1 < argv.length) args.runDir = argv[++index];
+    else if (current === '--workspace-root' && index + 1 < argv.length) args.workspaceRoot = argv[++index];
+    else if (current === '--force') args.force = true;
+  }
+
+  return args;
+}
+
+async function main() {
+  const args = parseArgs(process.argv);
+  if (!args.runDir) throw new Error('--run-dir is required');
+
+  const result = await ensureRunStateFile({
+    runDir: args.runDir,
+    workspaceRoot: args.workspaceRoot,
+    force: args.force,
+    strict: true,
+  });
+
+  console.log(`${result.action} run state: ${result.statePath}`);
+}
+
+const __filename = fileURLToPath(import.meta.url);
+
+export async function ensureRunStateFile(options) {
+  const runDir = resolve(options.runDir);
+  const workspaceRoot = resolve(options.workspaceRoot || process.cwd());
+  const statePath = join(runDir, 'state.json');
+  const existingState = await readJsonIfExists(statePath);
+
+  if (!options.force && isFinalizedState(existingState)) {
+    return { action: 'kept', state: existingState, statePath };
+  }
+
+  const squadName = inferSquadName(runDir);
+  let nextState = null;
+
+  try {
+    const squadDir = join(workspaceRoot, 'squads', squadName);
+    const squadYaml = await readRequiredText(join(squadDir, 'squad.yaml'));
+    const squadCode = extractYamlScalar(squadYaml, 'code') || squadName;
+    const pipelineFile = extractPipelineFile(squadYaml) || 'pipeline/pipeline.yaml';
+    const pipelineYaml = await readRequiredText(join(squadDir, pipelineFile));
+    const agents = parseSquadParty(await readRequiredText(join(squadDir, 'squad-party.csv')));
+    const publishResult = parsePublishResult(await firstExistingText(runDir, ['publish-result.md', 'v1/publish-result.md']));
+    nextState = buildRunStateFromMetadata({
+      runDir,
+      squadCode,
+      totalSteps: countPipelineSteps(pipelineYaml),
+      agents,
+      existingState,
+      publishResult,
+    });
+  } catch (error) {
+    if (options.strict) throw error;
+    return { action: 'skipped', state: existingState || null, statePath };
+  }
+
+  if (!nextState) {
+    if (options.strict) {
+      throw new Error(`Could not infer final state for '${runDir}'. Add publish-result.md or rerun with a complete run folder.`);
+    }
+    return { action: 'skipped', state: existingState || null, statePath };
+  }
+
+  await writeFile(statePath, `${JSON.stringify(nextState, null, 2)}\n`, 'utf-8');
+  return { action: existingState ? 'updated' : 'created', state: nextState, statePath };
+}
+
+export function buildRunStateFromMetadata({ runDir, squadCode, totalSteps, agents, existingState, publishResult }) {
+  const finalStatus = inferFinalStatus(existingState, publishResult);
+  if (!finalStatus) return null;
+
+  const finalTimestamp = inferFinalTimestamp(existingState, publishResult) || new Date().toISOString();
+  const startedAt = existingState?.startedAt || inferStartedAtFromRunDir(runDir) || finalTimestamp;
+  const baseState = {
+    squad: squadCode,
+    status: finalStatus,
+    step: {
+      current: totalSteps,
+      total: totalSteps,
+      label: finalStatus === 'failed' ? 'Pipeline failed' : 'Pipeline completed',
+    },
+    agents: agents.map((agent) => ({
+      ...agent,
+      status: finalStatus === 'failed' ? 'error' : 'done',
+    })),
+    handoff: existingState?.handoff || null,
+    startedAt,
+    updatedAt: finalTimestamp,
+  };
+
+  if (finalStatus === 'failed') {
+    return {
+      ...baseState,
+      error: publishResult.error || existingState?.error || 'Run failed during publication or closure.',
+      failedAt: existingState?.failedAt || finalTimestamp,
+    };
+  }
+
+  return {
+    ...baseState,
+    completedAt: existingState?.completedAt || finalTimestamp,
+  };
+}
+
+function inferFinalStatus(existingState, publishResult) {
+  const existingStatus = normalizeValue(existingState?.status).toLowerCase();
+  if (existingStatus === 'completed' || existingStatus === 'failed') return existingStatus;
+
+  const publishStatus = normalizeValue(publishResult.status).toLowerCase();
+  if (publishStatus === 'published') return 'completed';
+  if (publishStatus === 'failed' || publishStatus === 'error') return 'failed';
+  if (publishResult.error && normalizeValue(publishResult.error).toLowerCase() !== 'null') return 'failed';
+
+  return '';
+}
+
+function inferFinalTimestamp(existingState, publishResult) {
+  return existingState?.completedAt
+    || existingState?.failedAt
+    || publishResult.publishedAt
+    || existingState?.updatedAt
+    || '';
+}
+
+function inferStartedAtFromRunDir(runDir) {
+  const normalized = runDir.replace(/\\/g, '/');
+  const runId = normalized.split('/').filter(Boolean).at(-1) || '';
+  const match = runId.match(/^(\d{4})-(\d{2})-(\d{2})-(\d{2})(\d{2})(\d{2})$/);
+  if (!match) return '';
+
+  const [, year, month, day, hours, minutes, seconds] = match;
+  const date = new Date(Number(year), Number(month) - 1, Number(day), Number(hours), Number(minutes), Number(seconds));
+  if (Number.isNaN(date.getTime())) return '';
+  return date.toISOString();
+}
+
+function inferSquadName(runDir) {
+  const normalized = resolve(runDir).replace(/\\/g, '/');
+  const parts = normalized.split('/');
+  const squadsIndex = parts.lastIndexOf('squads');
+  return squadsIndex !== -1 ? parts[squadsIndex + 1] : 'unknown-squad';
+}
+
+function extractPipelineFile(content) {
+  const lines = content.split(/\r?\n/);
+  const pipelineIndex = lines.findIndex((line) => /^pipeline:\s*$/.test(line.trim()));
+  if (pipelineIndex === -1) return '';
+
+  for (let index = pipelineIndex + 1; index < lines.length; index += 1) {
+    const line = lines[index];
+    if (/^\S/.test(line)) break;
+    const match = line.match(/^\s+file:\s*"?([^"\n]+)"?\s*$/);
+    if (match) return match[1].trim();
+  }
+
+  return '';
+}
+
+function countPipelineSteps(content) {
+  const lines = content.split(/\r?\n/);
+  const stepsIndex = lines.findIndex((line) => /^steps:\s*$/.test(line.trim()));
+  if (stepsIndex === -1) return 0;
+
+  let total = 0;
+  for (let index = stepsIndex + 1; index < lines.length; index += 1) {
+    const line = lines[index];
+    if (/^\S/.test(line)) break;
+    if (/^\s*-\s+file:\s+/.test(line)) total += 1;
+  }
+
+  return total;
+}
+
+function parseSquadParty(content) {
+  const lines = content.split(/\r?\n/).filter(Boolean);
+  return lines.slice(1).map((line, index) => {
+    const [name, icon, path] = line.split(',');
+    return {
+      id: String(path || '')
+        .trim()
+        .replace(/^\.\/agents\//, '')
+        .replace(/\.agent\.md$/i, ''),
+      name: normalizeValue(name),
+      icon: normalizeValue(icon),
+      desk: {
+        col: (index % 3) + 1,
+        row: Math.floor(index / 3) + 1,
+      },
+    };
+  }).filter((entry) => entry.id && entry.name);
+}
+
+function parsePublishResult(content) {
+  return {
+    status: extractLabeledValue(content, 'Status'),
+    publishedAt: extractLabeledValue(content, 'Publicado em'),
+    error: extractLabeledValue(content, 'Erro remanescente'),
+  };
+}
+
+function extractYamlScalar(content, key) {
+  const match = content.match(new RegExp(`^${key}:\\s*"?([^"\\n]+)"?\\s*$`, 'm'));
+  return match ? match[1].trim() : '';
+}
+
+function extractLabeledValue(content, label) {
+  if (!content) return '';
+  const escapedLabel = label.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  const match = content.match(new RegExp(`\\*\\*${escapedLabel}:\\*\\*\\s*(.+)`, 'i'));
+  return match ? normalizeValue(match[1]) : '';
+}
+
+function normalizeValue(value) {
+  return String(value || '')
+    .replace(/^['"`<]+/, '')
+    .replace(/['"`>]+$/, '')
+    .trim();
+}
+
+function isFinalizedState(state) {
+  if (!state || typeof state !== 'object') return false;
+  const status = normalizeValue(state.status).toLowerCase();
+  return (status === 'completed' && Boolean(state.completedAt)) || (status === 'failed' && Boolean(state.failedAt));
+}
+
+async function firstExistingText(runDir, relativePaths) {
+  for (const relativePath of relativePaths) {
+    try {
+      return await readFile(join(runDir, relativePath), 'utf-8');
+    } catch {
+      // Try next file.
+    }
+  }
+
+  return '';
+}
+
+async function readJsonIfExists(filePath) {
+  try {
+    return JSON.parse(await readFile(filePath, 'utf-8'));
+  } catch {
+    return null;
+  }
+}
+
+async function readRequiredText(filePath) {
+  return readFile(filePath, 'utf-8');
+}
+
+if (process.argv[1] && resolve(process.argv[1]) === __filename) {
+  main().catch((error) => {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exitCode = 1;
+  });
+}