lastlight 0.1.8 → 0.2.0

package/skills/building/SKILL.md

@@ -0,0 +1,95 @@
+---
+name: building
+description: Install dependencies and run the test/lint/typecheck gate for a change inside the sandbox — package-manager detection, install-first, and (when implementing) TDD discipline. Use when implementing, fixing, or verifying code in a pre-cloned repo.
+version: 1.0.0
+tags: [build, test, sandbox]
+---
+
+# Building
+
+How to install, build, test, and gate a change in the sandbox. The same
+discipline whether you're implementing a feature, fixing review feedback, or
+verifying someone else's PR.
+
+## Workspace & git
+
+The harness pre-cloned the repo; your cwd is the repo root (or a `<repo>/`
+subdirectory — check with `ls -la`). Git is configured for clone/push/pull/fetch.
+If auth fails after ~1 hour, call the `github_refresh_git_auth` MCP tool. Suppress
+noise where it helps: `git clone --quiet`, `git push --quiet`, `CI=true`.
+
+## Install-first
+
+`node_modules` (and any other dependency dir) is **always** absent on arrival —
+by design, not a blocker. **Installing is the first step, not a reason to skip
+verification.** Detect the package manager from the lockfile and use the
+frozen/CI variant:
+
+- `package-lock.json` → `npm ci`
+- `pnpm-lock.yaml` → `corepack pnpm install --frozen-lockfile`
+- `yarn.lock` → `corepack yarn install --frozen-lockfile`
+
+Node is available via `fnm` + `corepack`; the egress allowlist permits the public
+package registries, so install works. For a monorepo, install at the root, then
+operate on the changed package. For non-Node repos, use the ecosystem's
+equivalent (`pip install`, `cargo build`, `go mod download`, …) read from the
+project's manifest.
+
+The **only** acceptable "couldn't verify" is when the install or build command
+*itself* fails — quote the exact command and error, and scope your work to what
+you could check. Never cite "deps aren't installed" as the reason: you install them.
+
+**If the repo's only test path needs an external service that won't run in the
+sandbox** (a live database, a cloud API, a running daemon), do **not** report
+that verification "could not run." Add a focused unit or CLI test project that
+exercises your change against in-memory fixtures or fakes, run *that*, and paste
+its output. A change you couldn't execute even once is unverified — building a
+runnable path is part of the work, not an optional extra.
+
+## The gate
+
+While iterating, run **only the tests covering the files you touched** — not the
+whole suite on every edit. Then, **once before committing or claiming done, run
+the full gate and require all of it to pass:**
+
+1. Full test command — zero failures.
+2. Lint command (if present) — fix all errors.
+3. Typecheck command (if present) — fix all errors.
+
+If any step fails, fix it and re-run only what failed until clean. Do not commit
+or report done until the full suite, lint, and typecheck all pass. Cite the
+actual command output — static reasoning is not verification.
+
+## TDD (when implementing)
+
+When you are *writing* code (not just verifying a PR): write the **failing test
+first**, watch it go red, then implement until it goes green, then refactor.
+Test behaviour through the public interface, not implementation details. The red
+test is the proof the test can fail — a test that was never red proves nothing.
+
+## Decomposition budget (when implementing)
+
+The gate passing is necessary, not sufficient — a green test does not excuse an
+unmaintainable function. Before you commit, decompose:
+
+- Keep each function under **roughly 15 cyclomatic complexity** (branches +
+  loops + boolean operators). If you're past that, extract helpers.
+- One function = one responsibility. A function that **parses, validates, and
+  emits is three functions** — split it before committing, not "later."
+- The refactor step of red-green-refactor is where this happens. Don't skip it
+  because the tests already pass.
+
+## Type safety — no compiler-silencing assertions
+
+The gate requires `tsc` (or the project's typechecker) to pass — but passing it
+by *suppressing* it is a regression, not a fix. **Never** use `as any`, an
+unchecked `as`-cast, `@ts-ignore`/`@ts-expect-error`, `# type: ignore`, or the
+equivalent to:
+
+- silence a compiler error instead of fixing the underlying type, or
+- bypass a validator/guard the same code path defines (e.g. casting past a Zod
+  schema, a runtime type guard, or a parse function so the value skips the very
+  check that file exists to enforce).
+
+If the types genuinely can't express something, narrow with a real type guard or
+fix the type — don't assert your way past it.

package/skills/chat/SKILL.md

@@ -1,17 +1,36 @@
+---
+name: chat
+description: Conversational assistant for messaging-platform threads (Slack, Discord). Answer questions about repos, PRs, and issues, explain code, and guide users to natural-language triggers (e.g. "build owner/repo#N", "triage owner/repo", "review PRs on owner/repo", "status").
+---
+
 # Chat
 
-Conversational assistant for messaging platforms (Slack, Discord, etc.).
+You are answering in a messaging thread (Slack, Discord). The conversation is
+the job — answer the question that was asked, don't expand it into a report.
+
+## What you do
+
+- Answer questions about repositories, issues, pull requests, and code.
+- Explain how the bot's workflows behave.
+- Report status on running work when asked.
+
+## What you don't do
+
+Chat is **read-and-explain only**. You don't review PRs, triage issues, run
+builds, or change anything. When the user wants an *action*, name the
+natural-language trigger and stop:
 
-## Behavior
+- code changes → `build owner/repo#N`
+- issue triage → `triage owner/repo`
+- PR review → `review PRs on owner/repo`
+- security scan → `security review owner/repo`
+- running-task status → `status`
 
-- Answer questions about repositories, issues, and pull requests
-- Explain code and development workflows
-- Provide status on running tasks when asked
-- Suggest commands for actions: `/build`, `/triage`, `/review`, `/status`
+Phrase triggers as natural language — never with a leading `/`, which Slack
+intercepts before it reaches Last Light.
 
-## Guidelines
+## Style
 
-- Keep responses concise — messaging platforms have limited rendering
-- Use markdown sparingly (bold for emphasis, code blocks for code)
-- Be direct and actionable
-- If the user wants to trigger an action, guide them to the appropriate slash command
+- Concise — messaging panes are narrow. A few sentences beats a wall of text.
+- Markdown sparingly: bold for emphasis, fenced blocks for code.
+- Lead with the answer. Cite `path:line` when pointing at code.

package/skills/code-review/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: code-review
+description: The shared rubric for reviewing a code change — finding tiers (Critical/Important/Suggestions/Nits) and what to check (correctness, security, edge cases, regression risk, test coverage). Use when reviewing a PR or a branch diff.
+version: 1.0.0
+tags: [review, code-quality]
+---
+
+# Code Review
+
+The shared rubric for assessing a code change. Used both by a PR review and by
+the build cycle's branch-diff reviewer — the *procedure* differs (where the diff
+comes from, how the verdict is recorded), but the rubric below is the same.
+
+Review the change **in full context** — read each changed file, not just the
+hunk. For a large change (>300 lines or >5 files): trace data flow through
+modified functions, check callers of anything whose signature or behaviour
+changed for regression risk, and check that tests cover the actual risk areas,
+not just the happy path.
+
+## Finding tiers
+
+Categorise every finding into exactly one tier:
+
+- **Critical** — security issues, data loss, breaking changes, silent
+  data-dropping (see Correctness below). Blocks merge.
+- **Important** — missing tests, performance problems, type errors, **avoidable
+  duplication**, **excessive complexity**, **compiler-silencing assertions**.
+  Should fix.
+- **Suggestions** — clarity, naming, minor DRY tidy-ups. Nice to have.
+- **Nits** — style, formatting. Optional.
+
+## What to check
+
+- **Correctness** — does it do what it claims? Logic errors, off-by-one, wrong
+  conditions, mishandled async. **A silent default or a dropped output for an
+  input the code doesn't support is a correctness bug, not graceful handling** —
+  flag any unsupported case that is silently defaulted, skipped, or omitted
+  instead of warned-and-skipped or warned-and-surfaced.
+- **Edge cases** — empty/null inputs, boundaries, error paths, concurrency.
+- **Security** — injection, auth/authorization, secret handling, untrusted input.
+- **Complexity** — flag functions past ~15 cyclomatic complexity or that mix
+  parse/validate/emit responsibilities; ask for helper extraction. This is an
+  **Important** finding, not a nit.
+- **Duplication** — flag avoidable duplicated logic (two or more clone groups of
+  the same code/branching). DRY is **should-fix** here, not merely "nice to have."
+- **Type safety** — flag `as any`, unchecked `as`-casts, or `@ts-ignore` used to
+  silence the compiler or to bypass a validator the same code path defines.
+- **Regression risk** — existing callers of changed functions; behaviour changes
+  that ripple.
+- **Test coverage** — do the tests exercise the real risk, or just the happy path?
+- **Fit** — does it match the codebase's existing patterns and conventions?
+
+## Calibration
+
+- Don't nitpick generated files (lockfiles, compiled assets).
+- Don't repeat what linters/CI already catch.
+- Don't block over style preferences alone.
+- Read the room: if a human reviewer already approved, lower the bar for blocking
+  — prefer a comment over requesting changes on non-critical findings.

package/skills/debug-production/SKILL.md

@@ -0,0 +1,108 @@
+---
+name: debug-production
+description: Debug a running Last Light instance (usually production) via the `lastlight` CLI instead of SSH. Use when investigating a failed/stuck workflow, a bad agent run, a phase error, or "why didn't the bot do X" — anything that previously meant SSHing in to read SQLite or session logs.
+version: 1.0.0
+tags: [ops, debugging, cli]
+---
+
+# Debug a Last Light instance via the CLI
+
+Read a running instance's state over its admin API with the `lastlight` CLI —
+no SSH, no poking SQLite or jsonl files on the box. Every command takes
+`--json` for machine-parseable output; prefer it when you need to extract
+fields.
+
+## 0. Connect
+
+The CLI talks to whatever instance you logged into (saved in
+`~/.lastlight/config.json`). Confirm you're pointed at the right one and the
+token is valid:
+
+```bash
+lastlight status            # instance URL, server health, token validity
+```
+
+If the token is missing/expired, authenticate (the prod instance URL lives in
+local agent memory — see the "Last Light production server" note):
+
+```bash
+lastlight login https://<instance>     # browser handoff (password/Slack/GitHub)
+lastlight login https://<instance> --password   # headless fallback
+```
+
+For one-off targeting without saving, pass `--url` / `--token` on any command,
+or set `LASTLIGHT_URL` / `LASTLIGHT_TOKEN` (env wins over the saved config).
+
+## 1. Find the broken run
+
+```bash
+lastlight workflow list --status failed          # recent failures
+lastlight workflow list --status active          # running + paused now
+lastlight workflow list --workflow pr-review --limit 50
+```
+
+Copy the run `ID` from the table.
+
+## 2. Inspect the run's phases
+
+```bash
+lastlight workflow log <run-id>          # run header + per-phase table (✓/✗, duration, session id, error)
+lastlight workflow log <run-id> --follow # then tail the current phase live
+```
+
+The phase table shows which phase failed, its error snippet, and the `SESSION`
+id you need for the transcript.
+
+## 3. Read / tail the agent transcript
+
+```bash
+lastlight session list                   # recent sandbox sessions (TYPE, MODEL, LIVE)
+lastlight session log <session-id>       # full transcript
+lastlight session log <session-id> --follow   # live tail (SSE) of an in-flight phase
+```
+
+## 4. Search across runs
+
+```bash
+lastlight logs search "ECONNREFUSED"                 # errors ledger (default)
+lastlight logs search "rate limit" --scope all       # errors + transcript content
+lastlight logs search "could not clone" --scope messages --limit 20
+```
+
+`--scope errors` (default) matches the executions ledger (error/skill/repo);
+`messages` greps recent session transcripts; `all` does both.
+
+## 5. Raw server / docker logs
+
+When the workflow + session views aren't enough — a crash before any session
+was written, a sidecar misbehaving, harness boot errors — read the actual
+container logs (`docker logs`) over the API:
+
+```bash
+lastlight server list                    # the lastlight-* containers + status
+lastlight server logs                    # the agent harness (default), last 200 lines
+lastlight server logs --tail 500 --since 10m
+lastlight server logs --follow           # live tail (Ctrl-C to stop)
+lastlight server logs coredns-strict     # a specific sidecar by service or container name
+```
+
+## 6. Approvals & health
+
+```bash
+lastlight approvals list                 # paused gates waiting on a human
+lastlight approvals approve <id> --reason "looks good"
+lastlight approvals reject  <id> --reason "wrong approach"
+
+lastlight stats                          # totals + per-skill success/fail
+lastlight stats --daily 14               # last 14 days of cost/tokens
+```
+
+## Tips
+
+- Add `--json` to any command to pipe into `jq` (e.g.
+  `lastlight workflow list --status failed --json | jq -r '.workflowRuns[].id'`).
+- Triage flow: `workflow list --status failed` → `workflow log <id>` → grab the
+  failed phase's session → `session log <session-id>` → if it's a recurring
+  symptom, `logs search "<error text>"` to see how often it happens.
+- These are read-only except `approvals approve/reject` and the trigger
+  commands (`build`/`triage`/`review`/…) — debugging never mutates the box.

package/skills/demo/SKILL.md

@@ -0,0 +1,194 @@
+---
+name: demo
+description: Record a short demo VIDEO of a PR or feature — drive the repo's web UI in a real headless browser, capture the session, and composite a titled, size-capped mp4 with ffmpeg. Use on the docker QA image when the deliverable is a playable demo clip (single walkthrough or before/after comparison), not a text/screenshot report.
+version: 1.0.0
+tags: [demo, video, browser, ffmpeg, evidence]
+---
+
+# Demo
+
+Turn a PR or feature into a short, polished **demo video**: drive the repo's
+web UI in a real headless Chromium, screen-record the session, and composite a
+titled, size-capped **mp4** the maintainer can watch inline.
+
+This is the **video** sibling of `browser-qa` (screenshots) and `verify`/
+`qa-test` (text evidence). It only works on the `lastlight-sandbox-qa:latest`
+docker image, which bakes in Playwright + Chromium **and ffmpeg**. You have
+bash + file tools but **no vision** — you reason over the driver's JSON stdout
+and the ffprobe summary; you never "see" the video.
+
+Compositing is **ffmpeg only** — there is no Remotion / cinematic-effects
+pipeline. You get a title card, optional before/after side-by-side, trim/speed,
+and a size cap. That's the deliverable: a clear, honest walkthrough, not a
+marketing reel.
+
+This skill uses **browser-qa** (the headless driver) and **building** (install
++ start the dev-server).
+
+## When this applies
+
+A phase on the docker QA image whose target is a **web app** the repo serves on
+`localhost`, where a *moving* demonstration adds value over a screenshot. For a
+CLI, a curl-able API, or pure pass/fail evidence, use `qa-test`/`verify`. For
+static screenshot evidence, use `browser-qa`. Don't record a video you don't
+need.
+
+## FIRST — probe for a browser
+
+The browser driver lives in the **browser-qa** skill bundle at
+`<browser-qa-dir>/scripts/agent-browser.mjs`, and this skill's compositor at
+`<demo-dir>/scripts/compose-demo.sh`. Resolve both `<…-dir>` paths from the
+available-skills catalogue (it gives each skill's absolute staged path); do not
+assume a relative path from `$PWD` — your cwd is the checked-out repo, the
+bundles are siblings.
+
+Run the runtime probe before anything else:
+
+```bash
+node <browser-qa-dir>/scripts/agent-browser.mjs doctor
+```
+
+- Exit 0 with `{"ok":true,...}` → proceed.
+- Exit non-zero (lean image / gondolin / no Chromium) → **DO NOT attempt a demo.**
+  Report that the demo path was unavailable on this host and stop. (The workflow
+  gates this phase to the QA image, so this should be rare — but never fake a
+  recording.)
+
+## Understand what to prove
+
+Read the PR (description, diff, linked issue) from the context the prompt gives
+you. For each change, ask: *what could a viewer confuse this with?* Design the
+demo so the viewer sees something that **only happens if the feature works as
+claimed** — both states (before/after, input/result) must appear on screen.
+
+State your **commitments** up front, then honour them:
+
+- **Layout** — `single` (default: a new feature, a fix proof, a walkthrough) or
+  `side-by-side` (only when the story is fundamentally a comparison: regression
+  fixed, behaviour-preserving refactor). Never fabricate a "before" to justify
+  side-by-side.
+- **Speed** — target a watchable length; speed up dead time rather than leaving
+  it. 30–60s is a good single-feature target.
+
+## Build and run the app
+
+Follow the **building** skill to install dependencies, then start the repo's
+dev-server **in the background** and poll with `curl` until it answers on
+`localhost:PORT`. Note the port — you pass it as `--base-url`.
+
+## Capture the session
+
+Author a `flow.json` (same shape as **browser-qa**) that scripts the
+interaction as a *director*, not an operator:
+
+- **Record the baseline first** — the starting state is act one.
+- **Hold after state changes** — add a `waitFor`/short pause so text is readable.
+- **Verify between steps** — `waitFor` the expected element before the next
+  action; don't blindly fire keys into an unsettled page.
+
+Record the session by passing `--record-dir`:
+
+```bash
+node <browser-qa-dir>/scripts/agent-browser.mjs run flow.json \
+  --base-url http://localhost:PORT \
+  --record-dir /tmp/demo-cap
+# → writes /tmp/demo-cap/session.webm, reports {"video":"…/session.webm", …}
+```
+
+Pick the viewport to match the layout so the clip isn't letterboxed:
+`1280x720` for `single`; `~960x1000` per panel for `side-by-side` (set it in the
+flow's `viewport`).
+
+**Before/after comparison:** check out and run each branch in turn (the
+`building` skill), recording the **same** scripted interaction against each —
+`session-before.webm` (base branch) and `session-after.webm` (PR head). Only the
+behaviour should differ.
+
+## Compose the video
+
+Composite the raw recording(s) into the final mp4 with the bundled wrapper:
+
+```bash
+# Single walkthrough
+<demo-dir>/scripts/compose-demo.sh \
+  --output <artifact-dir>/demo.mp4 \
+  --title "PR #42 — Add dark mode toggle" \
+  --subtitle "Toggling persists the theme across reloads" \
+  --layout single --speed 1.5 --target-size-mb 5 \
+  /tmp/demo-cap/session.webm
+
+# Before/after comparison
+<demo-dir>/scripts/compose-demo.sh \
+  --output <artifact-dir>/demo.mp4 \
+  --title "PR #51 — Fix flicker on load" \
+  --layout side-by-side --labels "BEFORE (main)" "AFTER (PR)" \
+  --target-size-mb 5 \
+  /tmp/before/session-before.webm /tmp/after/session-after.webm
+```
+
+Flags: `--title` (required, on the card), `--subtitle`, `--layout
+single|side-by-side`, `--labels A B` (side-by-side), `--speed N`, `--trim
+START:END` (seconds, single layout), `--target-size-mb` (default 5),
+`--width/--height` (default 1280×720), `--title-secs`. The script normalizes,
+lays out, adds the title card, and does a **two-pass** encode to land under the
+size cap (`+faststart`, `yuv420p`). It prints a JSON summary line:
+`{"output":"…","resolution":"1280x720","duration":"38.4","size_mb":3.1}`.
+
+## Guardrails — self-check before reporting
+
+Confirm the output with `ffprobe` (the script's summary already reports these):
+
+- **Resolution** matches the requested size (default 1920-free 1280×720).
+- **Duration** is sane — not 0s, within a watchable band (~15–90s).
+- **Size ≤ 5 MB** so GitHub embeds it inline (25 MB hard limit). If over, re-run
+  with a lower `--target-size-mb` or a higher `--speed`.
+
+If the recording is too short to be meaningful (a couple of seconds), go back
+and add interaction steps — don't ship a clip that proves nothing.
+
+## Output location
+
+Write `demo.mp4` into the **artifact directory the prompt provides** (the run's
+`.lastlight/<issueKey>/` dir, referenced by the template variable the prompt
+passes). The harness harvests it into the dashboard Artifacts view, and the
+public artifact URL makes it playable inline on GitHub. Do **not** commit the
+mp4 into the repo, and do **not** post it yourself — the workflow embeds it.
+
+Video delivery requires **server-mode build-assets**. If the mp4 can't be
+persisted (no artifact dir provided, or repo-mode), say so in the report and
+describe what the demo showed instead.
+
+## Evidence rules
+
+Mirror `verify`/`browser-qa` — you are demonstrating real behaviour, not selling
+it:
+
+- **Never fake it.** Don't edit the code under test to force a nicer demo, and
+  don't stage a result the feature didn't actually produce.
+- **Show the disambiguating moment** — the thing that only happens if the change
+  works. Off-camera claims don't count.
+- If something doesn't work, the honest demo shows that — report it; don't trim
+  the failure out and call it a success.
+
+## Report
+
+Produce your report as your **final message** — the workflow posts it (don't
+comment yourself). Keep it short:
+
+```
+## Demo: <target>
+
+**Environment:** <branch / commit, package manager, how served, Chromium version>
+
+<one or two sentences: what the video demonstrates and the key moment to watch>
+
+- **Layout:** single | side-by-side
+- **Video:** demo.mp4 (<resolution>, <duration>s, <size>MB)
+
+### Not covered
+<one line: anything the demo doesn't show, and why>
+```
+
+The workflow embeds the playable video from the artifact store; reference it as
+`demo.mp4`. If the browser or compositor was unavailable, say so plainly instead
+of pretending a clip exists.