house-lights 1.1.0 → 1.2.0

package/skills/cast-list/scripts/browser.mjs

@@ -0,0 +1,198 @@
+// A Chrome, Chromium or Edge without a window: opens a built page in one of its modes (#review, #snapshots, #svg…) and
+// reads back what the page wrote in <pre id="chalk-<mode>">. It talks to the browser over the DevTools protocol on a
+// pipe (--remote-debugging-pipe) and waits for that <pre> itself: --dump-dom hangs on some machines, the pipe does not.
+// The browsers are tried in order; one that does not start or does not answer in time gives way to the next.
+// Part of the skills kit (chalk-talk/kit): copied into each skill by its tools/assets.mjs. Node only, no dependency.
+import { execFileSync, spawn } from 'node:child_process'
+import { existsSync, mkdtempSync, readdirSync, rmSync } from 'node:fs'
+import { createRequire } from 'node:module'
+import { homedir, tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { pathToFileURL } from 'node:url'
+
+/** Playwright's own Chromium: the package's answer when it is installed here, else what it downloaded. */
+function playwright() {
+  const found = []
+  const req = createRequire(join(process.cwd(), 'noop.js'))
+  for (const name of ['playwright', 'playwright-core']) {
+    try {
+      const p = req(name).chromium.executablePath()
+      if (p) found.push(p)
+    } catch {}
+  }
+  const caches = [process.env.PLAYWRIGHT_BROWSERS_PATH, join(homedir(), '.cache/ms-playwright'), join(homedir(), 'Library/Caches/ms-playwright'), '/opt/pw-browsers'].filter(Boolean)
+  const inside = ['chrome-linux64/chrome', 'chrome-linux/chrome', 'chrome-linux-arm64/chrome', 'chrome-mac-arm64/Google Chrome for Testing.app/Contents/MacOS/Google Chrome for Testing', 'chrome-mac/Chromium.app/Contents/MacOS/Chromium']
+  for (const cache of caches) {
+    let dirs = []
+    try {
+      dirs = readdirSync(cache).filter((d) => /^chromium-\d+$/.test(d)).sort().reverse()
+    } catch {}
+    for (const d of dirs) for (const p of inside) found.push(join(cache, d, p))
+  }
+  return found
+}
+
+/** Every browser worth trying, in order: CHROME_PATH, PUPPETEER_EXECUTABLE_PATH, Playwright's Chromium, the usual places
+ * on macOS and Windows, then `which` on Linux. Only paths that exist, each once. */
+export function candidates() {
+  const paths = [process.env.CHROME_PATH, process.env.PUPPETEER_EXECUTABLE_PATH, ...playwright(),
+    '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome',
+    '/Applications/Chromium.app/Contents/MacOS/Chromium',
+    '/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge',
+    'C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe',
+    'C:\\Program Files (x86)\\Microsoft\\Edge\\Application\\msedge.exe']
+  if (process.platform !== 'win32') {
+    for (const name of ['google-chrome', 'google-chrome-stable', 'chromium', 'chromium-browser', 'microsoft-edge']) {
+      try {
+        paths.push(execFileSync('which', [name], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim())
+      } catch {}
+    }
+  }
+  return [...new Set(paths.filter((p) => p && existsSync(p)))]
+}
+
+/** The first browser there is, or null. */
+export function browser() {
+  return candidates()[0] ?? null
+}
+
+/** What the browser needs besides the usual: on Linux no sandbox as root (Chromium refuses to start otherwise) and no
+ * /dev/shm (small in containers). */
+export function launchFlags(platform = process.platform, uid = process.getuid?.()) {
+  const flags = ['--headless=new', '--disable-gpu', '--no-first-run', '--no-default-browser-check', '--allow-file-access-from-files',
+    '--disable-background-networking', '--disable-component-update', '--disable-sync', '--remote-debugging-pipe']
+  if (platform === 'linux') flags.push('--disable-dev-shm-usage')
+  if (platform === 'linux' && uid === 0) flags.push('--no-sandbox')
+  return flags
+}
+
+class BrowserFailed extends Error {}
+
+// A wait that never keeps Node running by itself.
+const pause = (ms) => new Promise((ok) => setTimeout(ok, ms).unref())
+
+/** One browser, started with a profile of its own, spoken to over the pipe. */
+async function start(exe) {
+  const profile = mkdtempSync(join(tmpdir(), 'chalk-talk-'))
+  const child = spawn(exe, [...launchFlags(), `--user-data-dir=${profile}`, 'about:blank'], { stdio: ['ignore', 'ignore', 'ignore', 'pipe', 'pipe'] })
+  const waiting = new Map()
+  let id = 0
+  let dead
+  // a failure of the whole browser rejects every call still waiting
+  const fail = (why) => {
+    dead ??= why
+    for (const { reject } of waiting.values()) reject(new BrowserFailed(dead))
+    waiting.clear()
+  }
+  child.on('error', (e) => fail(e.message))
+  const exited = new Promise((ok) => child.once('exit', (code) => (fail(`it stopped (exit ${code})`), ok())))
+  let buf = Buffer.alloc(0)
+  child.stdio[4].on('data', (d) => {
+    buf = Buffer.concat([buf, d])
+    let at
+    while ((at = buf.indexOf(0)) >= 0) {
+      const msg = JSON.parse(buf.subarray(0, at).toString('utf8'))
+      buf = buf.subarray(at + 1)
+      const call = msg.id && waiting.get(msg.id)
+      if (!call) continue
+      waiting.delete(msg.id)
+      if (msg.error) call.reject(new Error(msg.error.message))
+      else call.ok(msg.result)
+    }
+  })
+  child.stdio[3].on('error', (e) => fail(e.message))
+  const send = (method, params = {}, sessionId) => new Promise((ok, reject) => {
+    if (dead) return reject(new BrowserFailed(dead))
+    const n = ++id
+    waiting.set(n, { ok, reject })
+    child.stdio[3].write(JSON.stringify({ id: n, method, params, ...(sessionId ? { sessionId } : {}) }) + '\0')
+  })
+  const close = async () => {
+    if (!dead) {
+      send('Browser.close').catch(() => {})
+      await Promise.race([exited, pause(3000)])
+    }
+    child.kill()
+    await Promise.race([exited, pause(2000)])
+    rmSync(profile, { recursive: true, force: true })
+  }
+  return { send, close }
+}
+
+/** Opens `file` at `#mode` (with `query`) in a tab of its own and returns what the page wrote, parsed — { error } when
+ * the page could not be opened or wrote nothing in `ms`. */
+async function open(b, file, mode, query, ms, shot) {
+  const until = Date.now() + ms
+  let sessionId
+  // Every call waits at most until the page's time is up: a page busy forever does not hold the build.
+  const ask = (method, params, wait = until - Date.now()) => {
+    let timer
+    const late = new Promise((_, reject) => (timer = setTimeout(() => reject(new BrowserFailed(`no answer in ${Math.round(ms / 1000)} s`)), Math.max(0, wait))))
+    return Promise.race([b.send(method, params, sessionId), late]).finally(() => clearTimeout(timer))
+  }
+  const { targetId } = await ask('Target.createTarget', { url: 'about:blank' })
+  try {
+    ;({ sessionId } = await ask('Target.attachToTarget', { targetId, flatten: true }))
+    if (shot) await ask('Emulation.setDeviceMetricsOverride', { width: shot.width, height: shot.height, deviceScaleFactor: 1, mobile: false })
+    if (shot?.scheme) await ask('Emulation.setEmulatedMedia', { features: [{ name: 'prefers-color-scheme', value: shot.scheme }] })
+    const nav = await ask('Page.navigate', { url: `${pathToFileURL(file).href}${query ? `?${query}` : ''}${mode ? `#${mode}` : ''}` })
+    if (nav.errorText) return { error: `the page did not open (${nav.errorText})` }
+    // A picture of the page as it is once loaded, its fonts in and (when it says so) data-ready on the body.
+    if (shot) {
+      const ready = "document.readyState === 'complete' && document.fonts.status === 'loaded' && (document.body?.dataset.ready ?? '1') === '1'"
+      while (Date.now() < until) {
+        const r = await ask('Runtime.evaluate', { expression: ready, returnByValue: true })
+        if (r.result?.value === true) {
+          await pause(shot.settle ?? 400)
+          const { data } = await ask('Page.captureScreenshot', { format: 'png' })
+          return { png: `data:image/png;base64,${data}` }
+        }
+        await pause(50)
+      }
+      throw new BrowserFailed(`the page was not ready in ${Math.round(ms / 1000)} s`)
+    }
+    while (Date.now() < until) {
+      const r = await ask('Runtime.evaluate', { expression: `document.getElementById('chalk-${mode}')?.textContent ?? null`, returnByValue: true })
+      const text = r.result?.value
+      if (typeof text === 'string' && text) return JSON.parse(decodeURIComponent(text))
+      await pause(50)
+    }
+    const at = await ask('Runtime.evaluate', { expression: 'location.href', returnByValue: true }, 1000).catch(() => undefined)
+    throw new BrowserFailed(`no answer in ${Math.round(ms / 1000)} s${at?.result?.value ? ` at ${at.result.value}` : ''}`)
+  } finally {
+    sessionId = undefined
+    b.send('Target.closeTarget', { targetId }).catch(() => {})
+  }
+}
+
+/** Runs `jobs` ({ file, mode, query, shot }) in one browser — `shot: { width, height }` answers with { png } (a
+ * picture of the page once loaded) instead of what the page wrote — and returns their results in order, with the browser used —
+ * `results` null when there is no browser at all. A browser that fails (does not start, stops, or a page gets no answer
+ * in `timeout` seconds) gives way to the next one, which runs every job again; when none works, each result is
+ * { error } naming what was tried. */
+export async function runPages(jobs, { timeout = 20 } = {}) {
+  const list = candidates()
+  if (!list.length) return { results: null, tried: [] }
+  const tried = []
+  for (const exe of list) {
+    let b
+    try {
+      b = await start(exe)
+      const results = []
+      for (const { file, mode = '', query = '', shot } of jobs) results.push(await open(b, file, mode, query, timeout * 1000, shot))
+      return { results, used: exe, tried }
+    } catch (e) {
+      tried.push(`${exe}: ${e instanceof BrowserFailed ? e.message : e.message.split('\n')[0]}`)
+    } finally {
+      await b?.close()
+    }
+  }
+  const error = `no browser answered — ${tried.join('; ')}. Point CHROME_PATH at another one, or give it more time with --review-timeout`
+  return { results: jobs.map(() => ({ error })), tried }
+}
+
+/** One page: what it wrote, parsed; null without a browser, { error } when it failed. */
+export async function runPage(file, mode, query = '', opts) {
+  const { results } = await runPages([{ file, mode, query }], opts)
+  return results ? results[0] : null
+}

package/skills/cast-list/scripts/build.mjs

@@ -0,0 +1,179 @@
+#!/usr/bin/env node
+// Compares the Copilot Studio agents cloned in a folder: what most of them do (a pattern), who is off it, what only
+// one has, the team's rules not met — and makes the map (one HTML page that opens with no internet), the workbook
+// (.xlsx) and the cast file (what people said, what was decided). No model, no install, no network: Node 18 or later.
+//
+//   node build.mjs <agents-folder> --check [--profile <p.cast.yaml>] [--lang en|pt]     only compare: nothing is written
+//   node build.mjs <agents-folder> [--profile <p.cast.yaml>] [--html] [--xlsx] [--lesson] [--all] [--lang en|pt] [--out <folder>]
+//   node build.mjs <agents-folder> --facts [--out <folder>]                         only the facts, for a model: <id>.facts.json
+//   node build.mjs <agents-folder> --from <edited.xlsx> [--take <key,key…|all>] [--out <folder>]
+//                                  what was filled in the workbook (Declared, the Decision column): listed with a key each,
+//                                  and with --take written to the cast file
+//
+// With no --html/--xlsx/--lesson it makes the map. Files go in --out (or beside the folder), named by the folder:
+// <id>.html, <id>.xlsx, <id>.lesson.html (a chalk-talk lesson), and <id>.cast.yaml, kept up to date (read again on every
+// run). Exit codes: 0 done (what to look at is printed, and is not an error); 1 the profile or the cast file breaks its
+// format (each problem with its line), or no agent in the folder; 2 bad arguments; 3 made, but the lesson's reviewer
+// found something to fix. The outputs hold the client's data: keep them in the client's environment. The lesson's
+// review uses Chrome, Chromium or Edge when there is one.
+import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from 'node:fs'
+import { basename, dirname, join, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { runPage } from './browser.mjs'
+import { agentsIn, applyChanges, compare, DEFAULT_PROFILE, extractAgent, fromSheets, knownKinds, labelOf, lessonOf, problemText, readCast, readProfile, reviewCast, validateScene, workbookFile, workbookOf, writeCast } from './engine.mjs'
+import { readXlsx } from './read-xlsx.mjs'
+import { fill, inline } from './page.mjs'
+
+const here = dirname(fileURLToPath(import.meta.url))
+const argv = process.argv.slice(2)
+const valued = new Set(['--lang', '--out', '--profile', '--from', '--take'])
+const flags = new Set(['--check', '--html', '--xlsx', '--lesson', '--all', '--facts', ...valued])
+const option = (name) => {
+  const at = argv.indexOf(name)
+  return at >= 0 ? argv[at + 1] : undefined
+}
+const args = argv.filter((a, i) => !a.startsWith('--') && !valued.has(argv[i - 1]))
+const usage = `usage: node build.mjs <agents-folder> --check [--profile <p.cast.yaml>] [--lang en|pt]
+       node build.mjs <agents-folder> [--profile <p.cast.yaml>] [--html] [--xlsx] [--lesson] [--all] [--lang en|pt] [--out <folder>]
+       node build.mjs <agents-folder> --facts [--out <folder>]
+       node build.mjs <agents-folder> --from <edited.xlsx> [--take <key,key…|all>] [--out <folder>]`
+const lang = option('--lang') ?? 'en'
+const fail = (msg) => {
+  console.error(`${msg}\n${usage}`)
+  process.exit(2)
+}
+if (args.length !== 1 || !existsSync(args[0]) || !statSync(args[0]).isDirectory()) fail('✗ one folder with the cloned agents')
+const unknown = argv.find((a) => a.startsWith('--') && !flags.has(a))
+if (unknown) fail(`✗ unknown option ${unknown}`)
+if (!['en', 'pt'].includes(lang)) fail('✗ --lang is en or pt')
+for (const v of valued) if (argv.includes(v) && !option(v)) fail(`✗ ${v} needs a value`)
+if (argv.includes('--take') && !argv.includes('--from')) fail('✗ --take goes with --from')
+
+const T = {
+  en: {
+    found: (n, o, s) => `✓ ${n} in the cast: ${o} orchestrator${o === 1 ? '' : 's'}, ${s} specialist${s === 1 ? '' : 's'}`,
+    result: (p, off, solos) => `✓ ${p} patterns · ${off} off a pattern · ${solos} only one has`,
+    look: 'to look at', nothing: '✓ nothing to look at', facts: (f) => `✓ facts     ${f}`,
+    changes: (n) => (n ? `${n} change${n === 1 ? '' : 's'} in the workbook (take them with --take <key,…> or --take all):` : '✓ the workbook changes nothing'),
+    took: (n, f) => `✓ took ${n} change${n === 1 ? '' : 's'} into ${f}`, unknownKey: (k) => `✗ no change with the key «${k}»`,
+    declared: 'declared', decision: 'decision', add: '+', set: '~', remove: '−', accepted: 'accepted', rejected: 'rejected', platform: 'platform', specialist: 'specialist', orchestrator: 'orchestrator', none: (f) => `✗ ${f} has no folder with agent.mcs.yml`, privacy: '• the files hold the client’s data: keep them in the client’s environment',
+  },
+  pt: {
+    found: (n, o, s) => `✓ ${n} no elenco: ${o} ${o === 1 ? 'orquestrador' : 'orquestradores'}, ${s} ${s === 1 ? 'especialista' : 'especialistas'}`,
+    result: (p, off, solos) => `✓ ${p} padrões · ${off} fora do padrão · ${solos} só um tem`,
+    look: 'para olhar', nothing: '✓ nada para olhar', facts: (f) => `✓ fatos     ${f}`,
+    changes: (n) => (n ? `${n} ${n === 1 ? 'mudança' : 'mudanças'} na planilha (aceite com --take <chave,…> ou --take all):` : '✓ a planilha não muda nada'),
+    took: (n, f) => `✓ ${n} ${n === 1 ? 'mudança gravada' : 'mudanças gravadas'} em ${f}`, unknownKey: (k) => `✗ nenhuma mudança com a chave «${k}»`,
+    declared: 'declarado', decision: 'decisão', add: '+', set: '~', remove: '−', accepted: 'aceito', rejected: 'rejeitado', platform: 'plataforma', specialist: 'especialista', orchestrator: 'orquestrador', none: (f) => `✗ ${f} não tem nenhuma pasta com agent.mcs.yml`, privacy: '• os arquivos têm dados do cliente: deixe-os no ambiente dele',
+  },
+}[lang]
+
+const folder = resolve(args[0])
+const id = basename(folder)
+const read = (file, reader) => {
+  const r = reader(readFileSync(file, 'utf8'))
+  if (r.problems.length) {
+    for (const p of r.problems) console.error(`✗ ${basename(file)}:${p.line}: ${problemText(p, lang)}`)
+    process.exit(1)
+  }
+  return r
+}
+const profile = option('--profile') ? read(resolve(option('--profile')), readProfile).profile : DEFAULT_PROFILE
+const out = resolve(option('--out') ?? dirname(folder))
+const castFile = join(out, `${id}.cast.yaml`)
+const castText = existsSync(castFile) ? readFileSync(castFile, 'utf8') : undefined
+const cast = castText !== undefined ? read(castFile, readCast).cast : { ...(profile.name ? { name: profile.name } : {}), agents: [], declared: [], decisions: [] }
+
+// ---- the way back: an edited workbook as the changes it proposes ----
+if (argv.includes('--from')) {
+  const edited = fromSheets(cast, readXlsx(readFileSync(resolve(option('--from')))))
+  if (edited.problems.length) {
+    for (const p of edited.problems) console.error(`✗ ${basename(option('--from'))}: ${p}`)
+    process.exit(1)
+  }
+  const line = (c) => {
+    const x = c.after ?? c.before
+    // a key with no kind («kpi») is something only people know: declared:<key>
+    if (c.kind === 'declared') return `${T[c.op]} ${T.declared}  ${x.agent} · ${labelOf(x.key.includes(':') ? x.key : `declared:${x.key}`, lang)}${x.value ? ` = «${x.value}»` : ''}${x.source ? ` (${x.source})` : ''}`
+    return `${T[c.op]} ${T.decision}  ${labelOf(x.key, lang)}: ${T[x.status]} (${T[x.scope]})${x.why ? ` — ${x.why}` : ''}`
+  }
+  const take = option('--take')
+  if (!take) {
+    console.log(T.changes(edited.changes.length))
+    for (const c of edited.changes) console.log(`  ${c.key}  ${line(c)}`)
+    process.exit(0)
+  }
+  const keys = take === 'all' ? edited.changes.map((c) => c.key) : take.split(',').map((k) => k.trim()).filter(Boolean)
+  const missing = keys.find((k) => !edited.changes.some((c) => c.key === k))
+  if (missing) {
+    console.error(T.unknownKey(missing))
+    process.exit(2)
+  }
+  mkdirSync(out, { recursive: true })
+  writeFileSync(castFile, writeCast(applyChanges(cast, edited.changes, keys), castText))
+  console.log(T.took(keys.length, basename(castFile)))
+  process.exit(0)
+}
+
+// the schema's kinds, to tell a made-up one; without the schema every kind is taken as real
+const schema = join(here, '../vendor/microsoft/reference/bot.schema.yaml-authoring.json')
+const kinds = existsSync(schema) ? knownKinds(JSON.parse(readFileSync(schema, 'utf8'))) : undefined
+const found = agentsIn(folder).map((a) => extractAgent(a.id, a.files, kinds))
+if (!found.length) {
+  console.error(T.none(args[0]))
+  process.exit(1)
+}
+// only the facts, for a model to read: what was seen in each agent, with the file and line
+if (argv.includes('--facts')) {
+  mkdirSync(out, { recursive: true })
+  const file = join(out, `${id}.facts.json`)
+  writeFileSync(file, `${JSON.stringify({ format: 'cast-list/facts-v1', agents: found }, null, 2)}\n`)
+  console.log(T.facts(file))
+  console.log(T.privacy)
+  process.exit(0)
+}
+const result = compare(found, profile, cast)
+const looks = reviewCast(result)
+const roles = Object.values(result.roles)
+console.log(T.found(found.length, roles.filter((r) => r === 'orchestrator').length, roles.filter((r) => r === 'specialist').length))
+console.log(T.result(result.patterns.length, new Set(result.offPattern.map((o) => o.agent)).size, looks.filter((l) => l.key === 'solo').length))
+if (looks.length) for (const l of looks) console.log(`! ${T.look}: ${l[lang]}`)
+else console.log(T.nothing)
+if (argv.includes('--check')) process.exit(0)
+
+const all = argv.includes('--all')
+const want = { html: all || argv.includes('--html'), xlsx: all || argv.includes('--xlsx'), lesson: all || argv.includes('--lesson') }
+if (!want.xlsx && !want.lesson) want.html = true
+mkdirSync(out, { recursive: true })
+// the cast file keeps this run's roles, under what people wrote in it
+const kept = { ...cast, agents: result.agents.map((a) => ({ id: a.id, role: a.role })) }
+const castYaml = writeCast(kept, castText)
+writeFileSync(castFile, castYaml)
+console.log(`✓ cast      ${castFile}`)
+if (want.html) {
+  const page = join(out, `${id}.html`)
+  const map = readFileSync(join(here, '../assets/map.html'), 'utf8')
+  writeFileSync(page, fill(map, { CAST: inline({ id, lang, result, looks, cast: kept, castYaml, focusAreas: profile.focusAreas, threshold: profile.threshold }) }))
+  console.log(`✓ map       ${page}`)
+}
+if (want.xlsx) {
+  const book = join(out, `${id}.xlsx`)
+  writeFileSync(book, workbookFile(workbookOf(result, looks, kept, lang)))
+  console.log(`✓ workbook  ${book}`)
+}
+let exit = 0
+if (want.lesson) {
+  const page = join(out, `${id}.lesson.html`)
+  writeFileSync(page, fill(readFileSync(join(here, '../assets/lesson.html'), 'utf8'), { RECIPE: inline(validateScene(lessonOf(result, looks, lang))) }))
+  console.log(`✓ lesson    ${page}`)
+  const r = await runPage(page, 'review')
+  if (r === null) console.log('• review    no Chrome, Chromium or Edge here: the lesson checks itself when opened')
+  else if (r.error) console.log(`✗ review    not checked: ${r.error}`)
+  else if (!r.problems.length) console.log(`✓ review    ${r.combos} ${r.combos === 1 ? 'setting' : 'settings'}: nothing off the paper, no text over text`)
+  else {
+    for (const p of r.problems) console.log(`! review    ${p}`)
+    exit = 3
+  }
+}
+console.log(T.privacy)
+process.exit(exit)