@easysociable/cli 0.1.17 → 0.1.18

package/skills/easysociable-slideshow/scripts/check-pages.mjs

@@ -0,0 +1,136 @@
+#!/usr/bin/env node
+// Render every page of a content-pack.v1 with the system Chrome (no npm deps) and check it
+// the way a phone viewer sees it. Exit 0 = pass, 1 = errors (fix before create), 2 = no Chrome.
+//
+//   node check-pages.mjs pack.json --out ./shots [--brand brand.json | --theme theme.json]
+//
+// --brand takes `easysociable brands get --id <id> --json` output; without it the Studio
+// default (dark) theme is used, same as a Run without a Brand.
+import { execFileSync } from 'node:child_process'
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { join, resolve } from 'node:path'
+import { pathToFileURL } from 'node:url'
+
+const args = process.argv.slice(2)
+const flag = name => { const i = args.indexOf(name); return i >= 0 ? args[i + 1] : undefined }
+const packPath = args.find(a => !a.startsWith('--') && a !== flag('--out') && a !== flag('--brand') && a !== flag('--theme'))
+if (!packPath) { console.error('usage: node check-pages.mjs pack.json --out <dir> [--brand brand.json]'); process.exit(1) }
+const outDir = resolve(flag('--out') ?? 'shots')
+mkdirSync(outDir, { recursive: true })
+
+const pack = JSON.parse(readFileSync(packPath, 'utf8'))
+const themeFile = flag('--brand') ?? flag('--theme')
+const brandRaw = themeFile ? JSON.parse(readFileSync(themeFile, 'utf8')) : null
+const brand = brandRaw?.data ?? brandRaw
+const c = brand?.colors ?? brand?.color ?? {}
+// Studio default theme (apps/easysociable/app/lib/themeTokens.ts DEFAULT_AUTHORING_THEME_TOKENS).
+const colors = { canvas: c.canvas ?? '#0f1419', text: c.text ?? '#e8eef5', muted: c.textMuted ?? c.muted ?? '#8b9bb0', accent: c.accent ?? '#5b8cff', primary: c.primary ?? c.accent ?? '#5b8cff' }
+
+const chrome = [process.env.CHROME_PATH,
+  '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome',
+  '/Applications/Chromium.app/Contents/MacOS/Chromium',
+  '/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge',
+  '/usr/bin/google-chrome', '/usr/bin/chromium', '/usr/bin/chromium-browser',
+  'C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe'].find(p => p && existsSync(p))
+if (!chrome) { console.error('No Chrome/Chromium found (set CHROME_PATH). Render checks skipped.'); process.exit(2) }
+
+// ponytail: mirrors Studio's forced semantic colors by data-type; update if themeTokens.ts changes.
+const themeCss = `[data-authoring-theme]{--es-color-canvas:${colors.canvas};--es-color-text:${colors.text};--es-color-muted:${colors.muted};--es-color-accent:${colors.accent};--es-color-primary:${colors.primary}}
+[data-authoring-theme] [data-type="post"]{background-color:var(--es-color-canvas);color:var(--es-color-text)}
+[data-authoring-theme] [data-type="title"],[data-authoring-theme] [data-type="subtitle"]{color:var(--es-color-text)!important}
+[data-authoring-theme] [data-type="kicker"]{color:var(--es-color-accent)!important}
+[data-authoring-theme] [data-type="metric"]{color:var(--es-color-primary)!important}
+[data-authoring-theme] [data-type="caption"]{color:var(--es-color-muted)!important}
+html,body{margin:0;background:#fff}#report{display:none}`
+
+// Runs inside the Chrome page: JSX source → DOM, then measure. Source is evaluated in the page sandbox, not in Node.
+const pageScript = String.raw`
+const UNITLESS = new Set(['fontWeight','lineHeight','opacity','zIndex','flex','flexGrow','flexShrink'])
+const toCss = o => Object.entries(o).map(([k,v]) => k.replace(/[A-Z]/g, m => '-' + m.toLowerCase()) + ':' + (typeof v === 'number' && !UNITLESS.has(k) ? v + 'px' : v)).join(';')
+const toHtml = jsx => jsx
+  .replace(/style=\{\{([\s\S]*?)\}\}/g, (_, body) => 'style="' + toCss(Function('return {' + body + '}')()).replace(/"/g, "'") + '"')
+  .replace(/style="([^"]*)"/g, (_, body) => 'style="' + body.replace(/(^|;)\s*([a-z]+[A-Z][A-Za-z]*)\s*:/g, (m, sep, k) => sep + k.replace(/[A-Z]/g, c => '-' + c.toLowerCase()) + ':') + '"')
+  .replace(/className=/g, 'class=').replace(/\{' '\}/g, ' ')
+  .replace(/<(div|p|h1|h2|h3|span|img)(\s[^>]*?)\s*\/>/g, (_, t, a) => t === 'img' ? '<img' + a + '>' : '<' + t + a + '></' + t + '>')
+const stage = document.getElementById('stage'), GRID = location.hash === '#grid', S = 0.5
+for (const [i, src] of SOURCES.entries()) {
+  const box = document.createElement('div')
+  box.setAttribute('data-authoring-theme', '')
+  box.innerHTML = toHtml(src.json)
+  if (GRID) { box.style.cssText = 'width:' + src.width * S + 'px;height:' + src.height * S + 'px;overflow:hidden'; box.firstElementChild.style.transform = 'scale(' + S + ')'; box.firstElementChild.style.transformOrigin = '0 0' }
+  stage.appendChild(box)
+}
+if (GRID) stage.style.cssText = 'display:grid;grid-template-columns:repeat(' + COLS + ',max-content);gap:16px;padding:16px;background:#888'
+const lum = rgb => { const [r,g,b] = rgb.map(v => { v /= 255; return v <= 0.03928 ? v / 12.92 : ((v + 0.055) / 1.055) ** 2.4 }); return 0.2126*r + 0.7152*g + 0.0722*b }
+const parse = s => { const m = s.match(/rgba?\(([^)]+)\)/); if (!m) return null; const p = m[1].split(/[ ,\/]+/).filter(Boolean).map(Number); return { rgb: p.slice(0,3), a: p[3] ?? 1 } }
+const ratio = (a, b) => { const [x,y] = [lum(a), lum(b)].sort((m,n) => n - m); return (x + 0.05) / (y + 0.05) }
+function measure(root) {
+  const R = root.getBoundingClientRect(), W = R.width, H = R.height, k = W / 1080
+  const errors = [], warnings = []
+  const texts = [...root.querySelectorAll('[data-variable^="text"], p, h1, h2, h3')].filter((e, i, all) => e.textContent.trim() && !all.some(o => o !== e && o.contains(e)))
+  const label = e => (e.dataset.variable ? e.dataset.variable + ' ' : '') + JSON.stringify(e.textContent.trim().slice(0, 40))
+  let words = 0
+  for (const e of texts) {
+    const cs = getComputedStyle(e), r = e.getBoundingClientRect(), size = parseFloat(cs.fontSize), n = e.textContent.trim().split(/\s+/).length
+    if (e.dataset.type !== 'decoration' && e.dataset.type !== 'label') words += n
+    if (e.scrollHeight > e.clientHeight + 2 || e.scrollWidth > e.clientWidth + 2) errors.push('overflow: ' + label(e) + ' needs ' + e.scrollWidth + 'x' + e.scrollHeight + ', box ' + e.clientWidth + 'x' + e.clientHeight)
+    if (r.left < R.left - 2 || r.top < R.top - 2 || r.right > R.right + 2 || r.bottom > R.bottom + 2) errors.push('off-canvas: ' + label(e))
+    if (n >= 6 && size < 28 * k) warnings.push('small text (' + size + 'px, min ' + Math.round(28 * k) + '): ' + label(e))
+    // Contrast: the element and each coloured span against the first opaque background under its centre.
+    const stack = document.elementsFromPoint(r.left + r.width / 2, r.top + Math.min(r.height / 2, size))
+    let bg = null
+    for (const el of stack) { if (el.tagName === 'IMG') break; const p = parse(getComputedStyle(el).backgroundColor); if (p && p.a > 0.5) { bg = p.rgb; break } }
+    if (bg) for (const part of [e, ...e.querySelectorAll('span')]) {
+      if (part !== e && !part.textContent.trim()) continue
+      const pc = getComputedStyle(part), fg = parse(pc.color), fs = parseFloat(pc.fontSize), large = fs >= 36 * k || (fs >= 28 * k && Number(pc.fontWeight) >= 700)
+      const cr = fg && ratio(fg.rgb, bg)
+      if (cr && cr < 3) errors.push('contrast ' + cr.toFixed(2) + ':1 (min ' + (large ? 3 : 4.5) + '): ' + label(part))
+      else if (cr && !large && cr < 4.5) warnings.push('contrast ' + cr.toFixed(2) + ':1 on small text (min 4.5): ' + label(part))
+    }
+  }
+  for (let i = 0; i < texts.length; i++) for (let j = i + 1; j < texts.length; j++) {
+    const a = texts[i].getBoundingClientRect(), b = texts[j].getBoundingClientRect()
+    const ix = Math.min(a.right, b.right) - Math.max(a.left, b.left), iy = Math.min(a.bottom, b.bottom) - Math.max(a.top, b.top)
+    if (ix > 4 && iy > 4) errors.push('text overlap: ' + label(texts[i]) + ' / ' + label(texts[j]))
+  }
+  if (words > 60) warnings.push(words + ' words on one page (aim <= 45): split it')
+  // Largest empty horizontal band, ignoring full-bleed backgrounds.
+  const spans = [...root.querySelectorAll('*')].map(e => e.getBoundingClientRect()).filter(r => r.width * r.height > 0 && r.width * r.height < 0.8 * W * H).map(r => [r.top - R.top, r.bottom - R.top]).sort((a, b) => a[0] - b[0])
+  let cursor = 0, gap = 0
+  for (const [t, b] of spans) { gap = Math.max(gap, t - cursor); cursor = Math.max(cursor, b) }
+  gap = Math.max(gap, H - cursor)
+  if (gap > 0.25 * H) warnings.push('empty band ' + Math.round(gap) + 'px (' + Math.round(100 * gap / H) + '% of height): rebalance the layout')
+  return { errors, warnings }
+}
+if (!GRID) document.fonts.ready.then(() => {
+  document.getElementById('report').textContent = JSON.stringify([...stage.children].map(box => { try { return measure(box.firstElementChild) } catch (e) { return { errors: ['render failed: ' + e.message], warnings: [] } } }))
+})
+`
+
+const pages = pack.pages.map((page, i) => ({ n: i + 1, role: page.role, json: page.layout?.studioJson, ...(page.layout?.canvas ?? { width: 1080, height: 1350 }) })).filter(p => p.json)
+for (const page of pack.pages) if (!page.layout?.studioJson) console.log(`page ${pack.pages.indexOf(page) + 1}: no layout.studioJson (catalog page) — skipped`)
+const COLS = 4
+const html = `<!doctype html><meta charset="utf-8"><link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700;800&display=block">
+<style>${themeCss}</style><div id="stage"></div><pre id="report"></pre>
+<script>const SOURCES = ${JSON.stringify(pages).replace(/</g, '\\u003c')}, COLS = ${COLS};${pageScript}</script>`
+const file = join(outDir, 'pages.html')
+writeFileSync(file, html)
+const W = Math.max(...pages.map(p => p.width)), Hs = pages.map(p => p.height)
+const base = ['--headless=new', '--disable-gpu', '--hide-scrollbars', '--virtual-time-budget=5000']
+// Measure at full size (all pages stacked, so every page is inside the viewport).
+const dom = execFileSync(chrome, [...base, `--window-size=${W},${Hs.reduce((a, b) => a + b, 0)}`, '--dump-dom', pathToFileURL(file).href], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], maxBuffer: 64 << 20 })
+// One contact sheet at 50% for the visual review.
+const rows = Math.ceil(pages.length / COLS)
+execFileSync(chrome, [...base, `--window-size=${Math.min(COLS, pages.length) * (W / 2 + 16) + 16},${rows * (Math.max(...Hs) / 2 + 16) + 16}`, `--screenshot=${join(outDir, 'grid.png')}`, pathToFileURL(file).href + '#grid'], { stdio: 'ignore' })
+const raw = dom.match(/<pre id="report">([\s\S]*?)<\/pre>/)?.[1]?.replace(/&quot;/g, '"').replace(/&lt;/g, '<').replace(/&gt;/g, '>').replace(/&amp;/g, '&')
+const reports = raw ? JSON.parse(raw) : pages.map(() => ({ errors: ['no report (page script did not finish)'], warnings: [] }))
+let failed = false
+for (const [i, page] of pages.entries()) {
+  const report = reports[i]
+  if (report.errors.length) failed = true
+  console.log(`page ${page.n} (${page.role}): ${report.errors.length ? 'FAIL' : 'ok'}`)
+  for (const e of report.errors) console.log(`  ERROR ${e}`)
+  for (const w of report.warnings) console.log(`  warn  ${w}`)
+}
+console.log(`contact sheet: ${join(outDir, 'grid.png')} — look at it before creating the Run.`)
+process.exit(failed ? 1 : 0)

package/skills/easysociable-slideshow/workflows/CREATE_RUN.md

@@ -1,45 +1,14 @@
 # Create Run
 
-1. Write one arc line (`references/ARC.md`). Forbidden default:
-   Cover → Point → Steps → Recap → CTA.
-2. Prefer a Content Engine `pack.md` that already has **Page Contracts**,
-   **Media**, and **Template Selection** filled. If contracts are missing,
-   stop and hand back to **easysociable-content** — do not invent page
-   purposes from catalog family names.
-3. Build `content-pack.v1` from that argument. Page count follows the beats
-   (TikTok often 4–8), not the number of P0 families. Each page carries an
-   explicit `layoutFamilyId` (explicit — server must not silent-replace):
-   Formula handoff with a Look → `look.slides[slideNumber] ?? look.layouts[beat.role]`; else the pack's
-   Template Selection. One Run covers every platform the families support.
-4. Check platform hardMin/hardMax.
-5. No Look and no Template Selection → shortlist with
-   `easysociable slideshows recommend --file contracts.json --seed <slug> --json`
-   (MCP `recommend_slideshow_templates`). Input is the Page Contracts:
-   `{ platform, pages: [{ role, density?, slotSummary?: { text, number, image }, requiresImage? }] }`.
-   Pick one candidate `familyId` per page and record the reason; `supportedRoles` is a
-   weak tag. `pages[0]` must be cover/hook class. Do not use that class on
-   later pages. W- judgments (`fits` / `avoid`) with comparable evidence may
-   override the recommender's order. Surface `gaps` to the user.
-6. If `contentSlug` already has a Run: update only when topology matches
-   (same page count and Layout Families). Otherwise create a new Run.
-7. **Before** `create_run` / `slideshows create` (every create except
-   Formula handoff Runs): check the knowledge hard gate — Identity Role / What I build /
-   Point of view have no `(fill)` and are non-empty; `boundaries.md` exists
-   with Not covering and Never claim non-empty; if `needs/` exists, ≥3 `N-`
-   rows, else skip. Read the files or run
-   `easysociable engine validate --run <run-dir> --require-knowledge`.
-   Fail → hand back to **easysociable-content** / refuse create; list missing
-   files. User must say **强制继续** / **force continue** to call Gateway.
-   No new Gateway or MCP params.
-7b. **Identity chain (ADR-0036):** confirm CLI auth is the user's Dashboard
-    Workspace API key (not `workspace_local` / `test-key`). If needed run
-    `easysociable auth login` (browser approval; `--api-key <key>` only when
-    headless). Refuse create on fixture
-    identity unless the user asked for `--allow-local-fixture`.
-8. Call `create_run` / `slideshows create` through Gateway with the explicit
-   `layoutFamilyId`s from the pack. `LAYOUT_FAMILY_NOT_FOUND` → the family has
-   no template for this platform; tell the user, do not guess.
-9. Save `runId`, `studioUrl`, and `status=draft`. Tell the user to open
-   `studioUrl` **while logged into the same Studio account**.
-10. Do not call a Deck API, create a carousel template, or send a product
-    `pageSequence` / `arc` field.
+Follow the Workflow in `SKILL.md` (login → Brand → facts → hook/structure →
+Deck Style pages → images → `scripts/check-pages.mjs` → create).
+
+Notes for updates:
+
+- Revise the same Run (SKILL.md step 8): `slideshows get`, then `slideshows
+  update` with `baseRevision` and only the changed `pages[]` (`pageIndex`,
+  `layout`, `slots`). Page count and order stay fixed; a new Run only for a
+  new topic or an alternative the user asked for.
+- Save `runId` and `studioUrl`; the user opens `studioUrl` while logged into
+  the same account.
+- Do not call a Deck API or send a product `pageSequence` / `arc` field.

package/skills/easysociable-slideshow/workflows/MCP_FIRST.md

@@ -5,9 +5,7 @@ Fallback commands use the same Gateway client:
 
 ```bash
 easysociable slideshows create --file ./pack.json --json
-easysociable slideshows render --id run_xxx --idempotency-key run_xxx-final-1 --json
-easysociable renders wait --id job_xxx --json
-easysociable renders export --id job_xxx --output ./exports/run_xxx/tiktok --json
+easysociable slideshows get --id run_xxx --json
 ```
 
 Neither path may call a private service, Local API, Directus, R2 or a separate

package/skills/easysociable-slideshow/workflows/OUT_OF_SCOPE.md

@@ -1,7 +1,7 @@
 # Out of scope
 
 - DeckTemplate creation, `list_decks`, `CREATE_DECK`, or `BIND_P0_DECKS`.
-- Product-level `arc` / Deck `pageSequence` SKUs (ADR-0026). Structure stays in the Content Pack.
+- Product-level `arc` / Deck `pageSequence` SKUs. Structure stays in the Content Pack.
 - Defaulting every Run to Cover → Point → Steps → Recap → CTA.
 - Cover/hook class templates on page 2+ (they belong on `pages[0]` only).
 - ContentDocument as a render input (ADR-0021).

package/skills/easysociable-template/references/CATALOG_METADATA.md

@@ -5,7 +5,7 @@ Private AST/bindings stay server-side; this document is the **public selection c
 
 ## Design choices (locked)
 
-1. **One closed `pageRoles` set** (stored as `supportedRoles`) — a **retrieval tag for layout kind**, not page position and not a story recipe. `cover` means poster-like slots, not “must be page 1”. Do not add a parallel `arc` / `pageSequence` taxonomy (ADR-0026).
+1. **One closed `pageRoles` set** (stored as `supportedRoles`) — a **retrieval tag for layout kind**, not page position and not a story recipe. `cover` means poster-like slots, not “must be page 1”. Do not add a parallel `arc` / `pageSequence` taxonomy.
 2. **`platforms` is a multi-select array**. Include `generic` when the page fits any platform at that aspect.
 3. **P0 fields are required to Publish.** P1 should be filled when known; P2 optional.
 4. **Family `name` describes layout**, not a narrative beat. Prefer Poster / Stack / Count / Stair / Close (plus platform). Do not name families Cover / Point / Steps / Recap / CTA — choosers will glue those five names into one default pack.
@@ -99,7 +99,7 @@ hero | screenshot | avatar | product
 
 | Field | Type | Notes |
 |---|---|---|
-| `name` | string | Human title — **layout**, not beat (e.g. `P0 Poster TikTok`, not `P0 Cover TikTok`) |
+| `name` | string | Public card title: what the layout is + style, then the ratio (e.g. `Five-Step How-To List — Quiet Ledger 9:16`). No internal prefixes (`P0`), no single platform name — the family spans platforms; the ratio suffix is stripped on cards. Keep equal to the page `name` |
 | `shortDescription` | string | One sentence for chooser UI |
 | `platforms` | `Platform[]` | Multi-select; use `generic` when truly cross-platform |
 | `canvasPreset` | preset enum | Plus exact `canvas` pixels |

package/skills/easysociable-tweet-image/SKILL.md

@@ -0,0 +1,57 @@
+---
+name: easysociable-tweet-image
+description: >
+  Turn one or many X (Twitter) posts into clean PNG images with the `easysociable tweets render`
+  CLI. Use when the user pastes x.com / twitter.com status links (or tweet ids) and wants
+  images, screenshots or "cards" of them — e.g. "tweet to image", "turn these tweets into
+  pictures", "推文转图片", "把这几条推特做成图". One link → one PNG; never a carousel.
+  Do not use for writing new tweets, multi-slide carousels (use easysociable-slideshow), or
+  scraping profiles/timelines.
+---
+
+# EasySociable Tweet Image
+
+Renders each X post as its own PNG: avatar, display name, verified badge, @handle, text,
+up to 4 media thumbnails, timestamp and reply/like counts on a gradient background.
+Tweets are fetched through the EasySociable gateway (login required, free quota) and
+rendered locally on this machine.
+
+## Run
+
+```bash
+easysociable tweets render <link-or-id> [more links…] --json
+easysociable tweets render --file links.txt --json      # one link per line
+```
+
+| Flag | Default | Values |
+|---|---|---|
+| `--size` | `auto` | `auto` (card height fits the tweet) · `4:5` · `3:4` · `9:16` · `1:1` |
+| `--theme` | `light` | `light` · `dark` |
+| `--background` | `plum-plate` | `none` · `#hex` · `plum-plate` `sunset` `oceanic` `hyper` `cotton-candy` `gotham-dark` `neon` `emerald` `night-fade` `midnight` |
+| `--hide-metrics` | off | hide reply/like counts |
+| `--out` | `./tweets` | output folder; files are `tweet-<handle>-<id>.png` |
+
+If the command says `EASYSOCIABLE_API_KEY is required`, ask the user to run
+`easysociable auth login` (opens the browser), then retry.
+
+## Rules
+
+1. **Never rewrite, translate, summarize or "fix" tweet text.** The image must show the post exactly as published. Same for author name, @handle and avatar — do not swap or hide them.
+2. **One link → one image.** Do not merge tweets, build threads or carousels. Duplicates are rendered once.
+3. **Do not ask about size, theme or background up front.** Use the defaults unless the user already said what they want (e.g. "for Instagram" → `--size 4:5`, "for Stories/TikTok" → `--size 9:16`, "dark mode" → `--theme dark`, "no background"/"transparent" → `--background none`).
+4. **Failures are final, not something to work around.** `TWEET_NOT_FOUND` (deleted), `TWEET_UNAVAILABLE` (protected, age-restricted, suspended) and `INVALID_TWEET_URL` must be reported as failed. Never reconstruct a tweet from memory, search results or another site.
+5. `RATE_LIMITED` is retried automatically; if it still fails, tell the user to rerun just the failed links in a minute. `UPSTREAM_UNAVAILABLE` → suggest retrying later.
+6. Pass every link the user gave in one command (batch); don't loop one call per link.
+
+## Report
+
+Exit code 1 means at least one item failed; the others still rendered. Reply with a short
+per-link table from the `--json` items:
+
+| Link | Result |
+|---|---|
+| x.com/jack/status/20 | `./tweets/tweet-jack-20.png` |
+| x.com/foo/status/123 | failed — deleted (`TWEET_NOT_FOUND`) |
+
+Mention `warnings` only if present (e.g. avatar or media could not be downloaded, so a
+placeholder was used). Repost and view counts are not available from X and are never shown.