lastlight 0.1.15 → 0.2.1

package/sandbox.Dockerfile

@@ -1,36 +1,108 @@
-# Sandbox image for Last Light agent tasks.
+# Sandbox image for Last Light agent tasks (LASTLIGHT_SANDBOX=docker
+# fallback only — the default production sandbox is gondolin, invoked
+# in-process by agentic-pi without docker).
+#
 # Immutable assets baked at /app/. Entrypoint wires them into the workspace
 # after volumes are mounted, then drops to the runtime user.
 FROM node:20-slim
 
 RUN apt-get update && apt-get install -y --no-install-recommends \
     git ripgrep curl jq ca-certificates gettext-base gosu \
+    build-essential pkg-config python3 unzip \
     && rm -rf /var/lib/apt/lists/*
 
-# Create non-root agent user
-RUN useradd -m -s /bin/bash agent
+# fnm + multiple Node versions so repos pinning a specific Node via .nvmrc /
+# package.json#engines just work. System node from the base image stays at
+# /usr/local/bin; fnm-managed versions are pre-installed under FNM_DIR and
+# selected per-shell by the bashrc hook below.
+ENV FNM_DIR=/usr/local/share/fnm
+ENV PATH=$FNM_DIR/aliases/default/bin:$PATH
+RUN curl -fsSL https://fnm.vercel.app/install \
+      | bash -s -- --install-dir "$FNM_DIR" --skip-shell \
+ && ln -s "$FNM_DIR/fnm" /usr/local/bin/fnm \
+ && fnm install 22 \
+ && fnm install 24 \
+ && fnm default 22 \
+ && chmod -R a+rX "$FNM_DIR" \
+ && mkdir -p "$FNM_DIR/multishells" \
+ && chmod 1777 "$FNM_DIR/multishells"
 
-# Install Claude Code CLI (binary goes to ~/.local/bin/)
-# Remove ~/.claude/ after install — entrypoint recreates it at runtime.
-USER agent
-RUN curl -fsSL https://claude.ai/install.sh | bash && rm -rf /home/agent/.claude
-USER root
-ENV PATH="/home/agent/.local/bin:${PATH}"
+# Source fnm in every bash invocation (interactive or not). BASH_ENV makes
+# non-interactive `bash -c` read this file — that's how opencode's bash tool
+# inherits the right node version when it runs `npm ci` inside a repo with
+# an .nvmrc pinning Node 24.
+RUN printf '%s\n' \
+    'export FNM_DIR=/usr/local/share/fnm' \
+    'export PATH="$FNM_DIR:$PATH"' \
+    '# --shell bash is required: when sourced via BASH_ENV the parent process' \
+    '# is not a shell so fnm cannot auto-detect.' \
+    'eval "$(fnm env --shell bash --use-on-cd --version-file-strategy=recursive)"' \
+    '# The cd hook fires only on cd. Tools often launch `bash -c "..."` with' \
+    '# cwd already set via the spawn options — no cd happens — so also' \
+    '# auto-switch on shell start when the cwd has a version file.' \
+    'if [ -f "$PWD/.nvmrc" ] || [ -f "$PWD/.node-version" ]; then' \
+    '  fnm use --silent-if-unchanged 2>/dev/null \' \
+    '    || { fnm install 2>/dev/null && fnm use --silent-if-unchanged 2>/dev/null; } \' \
+    '    || true' \
+    'fi' \
+    > /etc/bash.bashrc.fnm \
+ && printf '\n[ -r /etc/bash.bashrc.fnm ] && . /etc/bash.bashrc.fnm\n' >> /etc/bash.bashrc \
+ && ln -s /etc/bash.bashrc.fnm /etc/profile.d/fnm.sh
+# Source the fnm file directly — Debian's /etc/bash.bashrc bails early on
+# non-interactive shells (`[ -z "$PS1" ] && return`), so pointing BASH_ENV
+# at it would skip our setup for `bash -c` invocations (which is the path
+# the agent's bash tool uses).
+ENV BASH_ENV=/etc/bash.bashrc.fnm
 
-# MCP server (baked at /app/)
-COPY mcp-github-app/package.json /app/mcp-github-app/package.json
-RUN cd /app/mcp-github-app && npm install --prefer-offline --no-audit && npm cache clean --force
-COPY mcp-github-app/ /app/mcp-github-app/
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    python3 python3-pip pipx \
+    && PIPX_HOME=/opt/pipx PIPX_BIN_DIR=/usr/local/bin pipx install semgrep \
+    && curl -sSfL https://github.com/gitleaks/gitleaks/releases/download/v8.21.2/gitleaks_8.21.2_linux_x64.tar.gz \
+       | tar -xz -C /usr/local/bin gitleaks \
+    && apt-get purge -y python3-pip \
+    && rm -rf /var/lib/apt/lists/*
 
-# Skills (baked at /app/ — entrypoint symlinks into ~/.claude/skills/)
-COPY skills/ /app/skills/
+# Create non-root agent user, UID/GID pinned to 10001 to MATCH the harness
+# `lastlight` user (see Dockerfile: `useradd -u 10001 lastlight`). The
+# entrypoint chowns the bind-mounted workspace to `agent`; per-PR workspaces
+# are persistent and reused across runs (issue #107), so the harness re-stages
+# AGENTS.md + skills into them on the next run. If `agent` lands on the default
+# uid (1001) those files become unwritable by the harness (10001) on reuse —
+# EACCES, and the review silently runs with no skill/AGENTS.md. Sharing the uid
+# keeps the reused workspace mutually writable by both the agent (in-container)
+# and the harness (host). Also self-heals dirs left at 1001 by older images:
+# the entrypoint's `chown -R agent:agent` re-owns them to 10001 on next reuse.
+RUN groupadd -g 10001 agent && useradd -m -s /bin/bash -u 10001 -g 10001 agent
 
-# Agent context (baked at /app/ — entrypoint cats into workspace/CLAUDE.md)
+# Install agentic-pi globally so the harness can `docker exec ...
+# agentic-pi run ...` against this container. The version + integrity
+# come straight from lastlight's `package-lock.json` so `npm i agentic-pi@…`
+# in the harness automatically flows into the sandbox image — no
+# manual Dockerfile bumps. `npm install -g <tarball>` itself doesn't
+# consult a lockfile, hence the explicit integrity verification.
+COPY package-lock.json /tmp/lastlight-lock.json
+RUN node -e "const p=require('/tmp/lastlight-lock.json').packages['node_modules/agentic-pi']; \
+             if(!p) throw new Error('agentic-pi missing from lockfile'); \
+             process.stdout.write(p.version + '\n' + p.integrity + '\n')" > /tmp/agentic-pi.pin \
+ && version=$(sed -n '1p' /tmp/agentic-pi.pin) \
+ && expected=$(sed -n '2p' /tmp/agentic-pi.pin) \
+ && echo "Installing agentic-pi@${version} (${expected})" \
+ && curl -fsSL "https://registry.npmjs.org/agentic-pi/-/agentic-pi-${version}.tgz" -o /tmp/agentic-pi.tgz \
+ && actual="sha512-$(node -e "const c=require('crypto'),f=require('fs');process.stdout.write(c.createHash('sha512').update(f.readFileSync('/tmp/agentic-pi.tgz')).digest('base64'))")" \
+ && if [ "$actual" != "$expected" ]; then \
+      echo "agentic-pi tarball integrity mismatch:" >&2; \
+      echo "  expected: $expected" >&2; \
+      echo "  actual:   $actual" >&2; \
+      exit 1; \
+    fi \
+ && npm install -g --no-audit --no-fund /tmp/agentic-pi.tgz \
+ && rm /tmp/agentic-pi.tgz /tmp/agentic-pi.pin /tmp/lastlight-lock.json
+
+# Agent context (baked at /app/ — entrypoint cats into workspace/AGENTS.md)
 COPY agent-context/ /app/agent-context/
 
-# Entrypoint + MCP config template
+# Entrypoint
 COPY deploy/sandbox-entrypoint.sh /app/sandbox-entrypoint.sh
-COPY deploy/mcp-config.tmpl.json /app/mcp-config.tmpl.json
 RUN chmod +x /app/sandbox-entrypoint.sh
 
 # Own app dir for agent user
@@ -38,6 +110,13 @@ RUN chown -R agent:agent /app /home/agent
 
 WORKDIR /home/agent/workspace
 
+# Image-level env so every `docker exec` (the entrypoint just runs once at
+# container start) sees these. Exporting them in sandbox-entrypoint.sh only
+# affects PID 1 — subsequent `docker exec agentic-pi run …` calls get a
+# fresh environment and would otherwise miss these paths.
+ENV LASTLIGHT_WORKSPACE=/home/agent/workspace
+ENV LASTLIGHT_GIT_CREDENTIALS=/home/agent/.lastlight-git-credentials
+
 # Entrypoint runs as root, fixes permissions, then drops to agent via gosu
 ENTRYPOINT ["/app/sandbox-entrypoint.sh"]
 CMD ["sleep", "infinity"]

package/skills/README.md

@@ -0,0 +1,40 @@
+# Skills
+
+Skill directories staged into the sandbox per workflow phase (and a subset into
+chat). A phase declares `skill: <name>` / `skills: [<name>, …]`; the runner
+stages the whole directory into `<agentCwd>/.agents/skills/<name>/` and
+pi-coding-agent surfaces `name` + `description` in the system prompt. The agent
+reads SKILL.md (and any `references/`) on demand via its `read` tool.
+
+**Authoring guide:** [`docs/agents/writing-skills.md`](../docs/agents/writing-skills.md)
+— the loading contract, the craft, and house conventions. Read it before adding
+or editing a skill.
+
+## Skills
+
+| Skill | Used by | Purpose |
+|-------|---------|---------|
+| [`chat`](chat/) | chat | Conversational assistant for Slack/Discord threads — answer repo/PR/issue questions, guide to natural-language triggers. |
+| [`issue-triage`](issue-triage/) | `issue-triage.yaml`, chat | Move issues through the canonical triage state machine — categorise, label, dedupe, manage stale, write agent briefs. |
+| [`issue-comment`](issue-comment/) | `issue-comment.yaml` | Handle non-build maintainer comments on issues/PRs — close, label, answer briefly, redirect build requests. |
+| [`pr-review`](pr-review/) | `pr-review.yaml`, chat | Review a PR with structured, tiered feedback; build and test from the local checkout; post a formal review. |
+| [`pr-comment`](pr-comment/) | `pr-comment.yaml` | Answer a maintainer's question about an open PR with concrete, code-cited evidence (not a full review). |
+| [`repo-health`](repo-health/) | `repo-health.yaml`, chat | Generate a repository health report — open issues, PR backlog, CI status, action items. |
+| [`security-review`](security-review/) | `security-review.yaml` | Diff-scoped SDLC security review; file one dated summary issue with a task-list of findings. |
+| [`security-feedback`](security-feedback/) | `security-feedback.yaml` | Process a maintainer's comment on a security scan summary — break findings into issues or record suppressions. |
+| [`building`](building/) | build (executor, reviewer), `pr-fix.yaml`, `pr-review.yaml` | Shared craft: install-first + package-manager detection, the test/lint/typecheck gate, and TDD discipline in the sandbox. |
+| [`code-review`](code-review/) | build (reviewer), `pr-review.yaml` | Shared rubric: finding tiers (Critical/Important/Suggestions/Nits) and what-to-check. Referenced by both the branch-diff reviewer and the PR reviewer. |
+| [`verify`](verify/) | `verify.yaml` | Test a behaviour claim as an investigator — CONFIRMED / REFUTED / INCONCLUSIVE with bash-captured evidence. |
+| [`qa-test`](qa-test/) | `qa-test.yaml` | Run an automated QA flow against a CLI or locally-served app and report step-level pass/fail with evidence. |
+| [`browser-qa`](browser-qa/) | `verify.yaml`, `qa-test.yaml`, `demo.yaml` | Drive a real headless browser against a locally-served web UI and capture screenshot (and, for `demo`, video) evidence. Gated to the docker QA image. |
+| [`demo`](demo/) | `demo.yaml` | Record a short demo VIDEO of a PR/feature — drive the web UI, screen-record, and composite a titled, size-capped mp4 with ffmpeg. Gated to the docker QA image. |
+
+`building` and `code-review` are **shared building blocks** — referenced by the
+build-cycle prompts (`workflows/prompts/*.md`) and the PR skills so the install
+gate and review rubric live in one place. They're staged alongside the phase's
+primary skill/prompt and read on demand.
+
+The live set is enforced at startup: `validateAssets()` (`src/workflows/loader.ts`)
+resolves every workflow `skill:` reference and `CHAT_SKILL_NAMES`
+(`src/engine/chat-skills.ts`). Adding a skill here does nothing until a phase or
+the chat list references it.

package/skills/browser-qa/SKILL.md

@@ -0,0 +1,193 @@
+---
+name: browser-qa
+description: Drive a real headless browser against a locally-served web UI and capture screenshot evidence, reporting step-level PASS/FAIL/BLOCKED with extracted DOM text and console errors. Use when a phase on the docker QA image must exercise a rendered UI and attach screenshots — it complements the text-evidence verify/qa-test skills.
+version: 1.0.0
+tags: [browser, qa, screenshots, evidence]
+---
+
+# Browser QA
+
+Drive a web UI with a real headless Chromium and report **step-level
+pass/fail with evidence**: extracted DOM text, assertion results, console
+errors, and screenshot files. The deliverable is a QA report — partial
+coverage with documented failures is the expected output.
+
+This skill is the **browser/screenshot path** that `verify` and `qa-test`
+scope out to "a separate docker-gated capability". It only works on the
+`lastlight-sandbox-qa:latest` docker image, which bakes in Playwright +
+Chromium. You have bash + file tools but **no vision** — you reason over the
+driver's JSON stdout (extracted text, assertion results, console errors).
+The PNG screenshots are **human evidence only**; you never see them.
+
+This skill uses the **building** skill for installing dependencies and
+starting the repo's dev-server.
+
+## When this applies
+
+A phase running on the docker QA image whose target is a **web app** the
+repo serves on `localhost` and where rendered-UI behaviour or visual
+evidence matters. For a CLI or a curl-able API, use `qa-test`/`verify`
+instead — don't launch a browser you don't need.
+
+## FIRST — probe for a browser
+
+The driver lives in this skill's bundle at
+`<skill-dir>/scripts/agent-browser.mjs`. Resolve `<skill-dir>` from the
+available-skills catalogue (it gives the absolute staged path of this
+skill); do not assume a relative path from `$PWD` — the agent's cwd is the
+checked-out repo, the bundle is a sibling.
+
+Run the runtime probe before anything else:
+
+```bash
+node <skill-dir>/scripts/agent-browser.mjs doctor
+```
+
+- Exit 0 with `{"ok":true,"chromium":"..."}` → Chromium is available; proceed.
+- Exit non-zero (e.g. `playwright not available …`, or no Chromium — the lean
+  default image, or a gondolin run) → **DO NOT attempt browser QA.** Fall back
+  to the text path (`verify`/`qa-test` style: curl the dev-server, capture
+  stdout) and **say in your report that the browser path was unavailable** and
+  you used the text path.
+
+## Start the app
+
+Follow the **building** skill to install dependencies, then start the repo's
+dev-server **in the background** and wait until it is listening on
+`localhost:PORT` (poll with `curl` until it answers). Note the port — you
+pass it as `--base-url`.
+
+## Author a flow
+
+Write a `flow.json` describing the QA flow. Shape:
+
+```json
+{
+  "baseUrl": "http://localhost:3000",
+  "viewport": { "width": 1280, "height": 800 },
+  "steps": [
+    { "name": "home", "goto": "/" },
+    { "click": "text=Login" },
+    { "fill": ["#email", "a@b.com"] },
+    { "type": ["#password", "hunter2"] },
+    { "press": "Enter" },
+    { "waitFor": "#dashboard" },
+    { "assertText": "Welcome" },
+    { "text": "h1" },
+    { "screenshot": "after-login" }
+  ]
+}
+```
+
+Step keys (a step may combine an action **plus** a trailing `screenshot`):
+
+| Key          | Value                | Effect                                                            |
+|--------------|----------------------|------------------------------------------------------------------|
+| `goto`       | path or URL          | Navigate (resolved against `baseUrl`). **Failure is fatal.**      |
+| `click`      | selector             | Click the element.                                               |
+| `fill`       | `[selector, value]`  | Set an input's value.                                            |
+| `type`       | `[selector, value]`  | Type key-by-key into an input.                                   |
+| `press`      | key (e.g. `Enter`)   | Press a keyboard key.                                            |
+| `waitFor`    | selector             | Wait until the element is visible (~10s timeout).                |
+| `assertText` | string               | Pass if the text is visible anywhere on the page; else step FAIL.|
+| `text`       | selector             | Extract `textContent` into the step result (for you to read).    |
+| `screenshot` | basename             | Write `<out-dir>/<basename>.png` (full page).                    |
+
+The whole flow runs in **one Chromium session** — login state, cookies, and
+navigation persist across steps.
+
+## Run the flow
+
+```bash
+node <skill-dir>/scripts/agent-browser.mjs run flow.json \
+  --base-url http://localhost:PORT \
+  --out-dir <artifact-dir>
+```
+
+The driver prints a single JSON report:
+
+```json
+{ "ok": false,
+  "baseUrl": "http://localhost:3000",
+  "steps": [
+    { "index": 0, "action": "goto", "ok": true, "ms": 412 },
+    { "index": 6, "action": "assertText", "ok": false, "ms": 10003,
+      "error": "assertText not found: \"Welcome\"" },
+    { "index": 7, "action": "text", "ok": true, "ms": 5, "text": "Dashboard" },
+    { "index": 8, "action": "screenshot", "ok": true, "ms": 88,
+      "screenshot": "/…/after-login.png" }
+  ],
+  "consoleErrors": ["Uncaught TypeError: …"],
+  "screenshots": ["/…/after-login.png"] }
+```
+
+- A step error (selector not found, assertion miss, timeout) is recorded
+  `ok:false` and the run **continues** — best-effort coverage. The exception
+  is a `goto` that fails: that is fatal and the remaining steps are skipped.
+- `ok` at the top level is true only when **every** step passed. The process
+  exits 0 even when steps failed — judge from the JSON, not the exit code.
+  A non-zero exit means a fatal harness error (bad flow file, launch failure).
+
+## Screenshots & artifacts
+
+Pass `--out-dir <artifact-dir>` pointing at the run's artifact directory the
+**prompt provides** (commonly the run's `.lastlight/<issueKey>/` dir,
+referenced as the template variable the prompt passes in). Saving there lets
+the harness **harvest** the PNGs into the dashboard Artifacts view. Reference
+each screenshot path in your report.
+
+Screenshot delivery requires **server-mode build-assets**. If the PNGs can't
+be persisted (no artifact dir was provided, or build-assets is repo-mode),
+still report the text/DOM observations and console errors, and say the
+screenshots were **not retained**.
+
+## Evidence rules
+
+Mirror `verify`/`qa-test` — you are an investigator, not an advocate:
+
+- **Never fake a pass.** Don't hardcode expected text or edit the code under
+  test to force a green step.
+- **Report real failures.** A step that genuinely fails is a finding — record
+  it `FAIL` with the assertion/selector and the driver's error, and don't bury
+  it.
+- **Treat `consoleErrors` and page errors as findings**, even if the visible
+  flow "worked" — surface them in the report.
+- If the browser is unavailable (probe failed), fall back to text and say so —
+  don't pretend a UI step ran.
+
+## Report
+
+Produce your report as your **final message** — the workflow posts it for you
+(don't `github_add_issue_comment` yourself; that would double-post).
+
+**Be concise, and stay in the browser.** The deliverable is short: a one-line
+environment summary, the results table, the screenshots, console errors, and a
+one-line coverage note. Do **not** read or analyse the repo's source code (the
+text pass already did) and do **not** narrate every step or dump extracted DOM
+text — surface a `text`/assertion value only when it's the actual evidence for a
+row (e.g. a FAIL).
+
+```
+## Browser QA: <target>
+
+**Environment:** <branch / commit, package manager, how served, Chromium version>
+
+### Results
+| Step | Status | Evidence |
+|------|--------|----------|
+| <step description> | PASS / FAIL / BLOCKED | <terse evidence + inline screenshot if any> |
+
+### Console errors
+- <each consoleErrors / pageerror entry, or "none observed">
+
+### Coverage
+<one or two lines: what was driven, and anything not tested and why>
+```
+
+Reference screenshots **inline** as raw Markdown images when the prompt gives
+you a public artifact base URL — write `![caption](<base>/<name>.png)` directly
+in the report body (or table cell), **never** wrapped in backticks or a code
+fence (inside a code span it renders as literal text, not an image). Otherwise
+reference them by filename. Every step in the flow must
+have a row and a result. Never report a flow as "passed" with steps you didn't
+actually run — list them as untested instead.