docs(alpha): simplify native setup and verify generic starter creation

This commit is contained in:
2026-10-20 21:42:34 +01:00
parent dce2d759d7
commit a40898f79a
10 changed files with 272 additions and 529 deletions
+22 -1
View File
@@ -8,6 +8,26 @@ test, or a code change without a capture, is `partial` at best.
Status legend: `todo` · `partial` (some of it works) · `done` (working + captured).
### Generic alpha starters (2026-10-20)
The embedded catalogue now presents small code change/review, research/fact-check,
document summary, option comparison, and plan/checklist starters, alongside the
retained legacy keys. No project path, stack, provider account or model is baked
into these starter definitions. No existing published definitions are changed.
`test/ui-smoke.mjs --scratch` verified all eight entries and the real
validate/create/list flow against a current-source Go server on a free loopback
port with a scratch database and explicitly enabled authoring. Desktop and 390px
gallery captures check overflow and card metadata containment; grid rows now
keep their content height rather than clipping the stage counts. The browser
driver scrolls instantly before measuring click targets, avoiding stale positions
under CSS smooth scrolling. Captures: approved OpenCode temporary
`alpha-template-browser-captures/51-template-create-dialog.png`,
`52-template-created.png`, `53-pipeline-created-list.png`,
`54-alpha-starter-gallery-desktop.png`, `55-alpha-starter-gallery-mobile.png`.
These checks create no live definitions and perform no inference. Real research
tools, provider outcomes and deployment are not established by this check.
### Session capture and export recovery (2026-10-20)
**Partial against the live-server gate.** The Session tab now distinguishes a
@@ -22,7 +42,8 @@ Export-gated waits are nonterminal and show no human decision controls.
successful export-only retry at 390px, with sandboxed iframe and unchanged-frame
checks. Captures: approved OpenCode temporary `session-audit-captures/`,
`01-recorded-identity-export-failed.png` and
`02-complete-repair-refreshes-open-audit.png`. These use fixture session data,
`02-complete-repair-refreshes-open-audit.png`, plus
`03-export-wait-is-not-a-human-decision.png`. These use fixture session data,
not a deployed-service claim. Separately, read-only API verification exported
all five original run #19 sessions completely (14/11/10/16/11 messages), without
rerunning stages. No deployment or live evidence mutation was performed.
+15 -6
View File
@@ -13,11 +13,14 @@ what is done; this file covers how to run, test and verify it.
headless Chrome against a live server (`test/ui-smoke.mjs`); a unit test alone
never marks a parity row done.
## Safety (unchanged from the Android client)
## Safety
- **Trusted LAN/VPN only.** The Pipelines API has **no authentication** and is
**not internet-safe**. Do not expose the server or this page to untrusted
networks.
- **Authenticated browser proxy.** Pages, assets, artifacts, and `/connect`
require a signed session cookie. The proxy refuses to start without its
configured password/secret file. Never disable authentication on a real service.
- **Private control APIs.** Pipelines and harness APIs have **no authentication**.
Keep them on loopback; expose only the authenticated proxy on a trusted LAN/VPN.
Use TLS/VPN for remote access, not an Internet-facing raw API.
- **No secrets.** The page stores only the server URL and its own small UI
preferences (sort/filter choices, attention dismissals, device-local chat
overrides) in `localStorage`; nothing is sent anywhere but the configured
@@ -25,7 +28,12 @@ what is done; this file covers how to run, test and verify it.
- **No hardcoded server.** The URL is entered by the user, prefilled from the page
origin, and can be overridden.
## Run it
## Run it for development
For normal installation, use [`./install`](../docs/install.md). The following
commands are for a separate development process with an existing web-auth file
(`PIPELINES_WEB_AUTH_FILE`, default `~/.config/pipelines/web-auth.json`). They do
not create an account or configure autostart.
```sh
cd web
@@ -40,7 +48,8 @@ first time; the endpoint is then remembered and re-opened on later loads. Nothin
is baked in.
On a deployment where ntfy already uses 8090, pick another port for the page
(e.g. `--port 8095`). The page is a foreground Node process, not a service.
(e.g. `--port 8095`). These commands are foreground processes; managed startup is
described in the [installation guide](../docs/install.md).
## Test it
+1 -1
View File
@@ -226,7 +226,7 @@
.pane-head-compact .pane-head-actions { margin-left: auto; }
.gallery { padding-bottom: 8px; }
.cards { display: grid; gap: var(--space-xs); padding: var(--space-s); align-content: start; }
.cards { display: grid; grid-auto-rows: max-content; gap: var(--space-xs); padding: var(--space-s); align-content: start; }
.card {
display: block;
width: 100%;
+4 -2
View File
@@ -246,7 +246,9 @@ export async function launchChrome({ width = 1440, height = 900, chromePath } =
return api.evaluate(`(() => {
const el = document.querySelector(${JSON.stringify(selector)});
if (!el) return null;
el.scrollIntoView({ block: "center", inline: "center" });
// CSS smooth scrolling is asynchronous; measuring immediately after
// it can click outside the viewport instead of the target control.
el.scrollIntoView({ block: "center", inline: "center", behavior: "instant" });
const r = el.getBoundingClientRect();
return { x: r.x + r.width / 2, y: r.y + r.height / 2 };
})()`);
@@ -267,7 +269,7 @@ export async function launchChrome({ width = 1440, height = 900, chromePath } =
const all = [...document.querySelectorAll(${JSON.stringify(selector)})];
const el = all.find((node) => (node.textContent ?? "").includes(wanted));
if (!el) return false;
el.scrollIntoView({ block: "center" });
el.scrollIntoView({ block: "center", behavior: "instant" });
el.setAttribute("data-test-click", "1");
return true;
})()`);
+13
View File
@@ -1453,6 +1453,19 @@ async function runScratchCreate() {
await ensureConnected();
await openTemplates();
await page.waitForSelector(".cards button.card", { timeout: 25000 });
const starterKeys = await page.evaluate(`Array.from(document.querySelectorAll('[data-template-key]'), node => node.dataset.templateKey)`);
for (const key of ["task", "research", "summarize", "compare", "plan", "three-stage", "review", "debug"]) {
if (!starterKeys.includes(key)) throw new Error(`Missing alpha starter ${key}`);
}
await shot("54-alpha-starter-gallery-desktop.png");
await page.resize(390, 844);
await settle();
if (await page.evaluate("document.documentElement.scrollWidth > innerWidth")) throw new Error("Starter gallery overflows at 390px");
const clipped = await page.evaluate(`Array.from(document.querySelectorAll('[data-template-key]')).filter(card => card.querySelector('.card-meta')?.getBoundingClientRect().bottom > card.getBoundingClientRect().bottom).map(card => card.dataset.templateKey)`);
if (clipped.length) throw new Error(`Starter metadata outside cards: ${clipped.join(", ")}`);
await shot("55-alpha-starter-gallery-mobile.png");
await page.resize(1440, 900);
await settle();
await page.click(".cards button.card");
await page.waitForSelector("#detailTitle", { timeout: 25000 });
await page.waitForSelector(".template-create-open", { timeout: 15000 });