Skip to content

Commit 049a75b

Browse files
authored
feat(server,frontend): Vite MPA + Go API for systems/scopes (#36)
* feat(frontend): scaffold Vite SPA from essays Astro layout port Bootstraps frontend/ as a Vite + TypeScript SPA. Nav, footer, layouts, and pages are ported from tsaqib/essays (Astro) into vanilla TS render functions; data is deferred to a follow-up. BeerCSS, Geist Variable, and material-dynamic-colors are carried over for visual parity with the source. Build emits a single bundle.js + bundle.css (Terser, ES2022, three compress passes) with font assets in dist/assets/. SPA routing via history API; URLSearchParams threaded so pages can react to query strings. Tooling: Biome (lint + format), tsc --noEmit, and Knip (dead code), with matching npm scripts. Signed-off-by: Tanzim Saqib <[email protected]> * chore(tooling): wire frontend setup + checks into Task and lefthook task setup now also runs `npm install` inside frontend/ (no-op when the directory is absent). task prepush gains a frontend-check pre-push hook (tsc + Biome + Knip), glob-gated to frontend/** so Go-only pushes skip it. A frontend-fmt pre-commit hook runs Biome auto-fix tree-wide on the frontend when any frontend file is staged, mirroring the golangci-lint pattern used on the Go side. Adds frontend:* namespaced tasks for dev, build, check, lint:fix, and fmt. Signed-off-by: Tanzim Saqib <[email protected]> * feat(server): add --cwd flag + loopback HTTP server serving embedded SPA Wires every cwd-dependent subcommand to an optional --cwd <PATH> flag (git -C semantics). Replaces bare-stax's placeholder browser open with a loopback server on 127.0.0.1:7829 that serves the embedded frontend/dist Vite SPA at root, plus internal /api/hello and /api/systems endpoints (the latter reads .stax/_data_systems.yaml from cwd / --cwd target; 200 with empty list when missing). --no-browser keeps the server running but suppresses the OS-default browser handoff. --cwd is rejected on `skills remove --user` because the wipe is rooted at $HOME regardless of cwd. e2e tests gain a background-spawn helper for both bash and PowerShell; the update- check cases that previously used --no-browser switch to --version (still seeds + fires maybeNotifyUpdate, exits cleanly). Signed-off-by: Tanzim Saqib <[email protected]> * fix(server): clean-URL fallback + branded 404 for the embedded SPA The Vite dist tree ships flat *.html files at the root, not nested <page>/index.html dirs, so net/http's bare FileServer 404s on every clean URL (/systems, /search, /minibooks, /essay). handleFrontend now: 1. tries the exact path, 2. for extension-less paths, falls back to <path>.html when it exists, 3. otherwise serves frontend/dist/404.html with a 404 status so the error page keeps the UI's design language. Pinned by TestNewServerMux_CleanURLs and TestNewServerMux_ 404FallbackServesBrandedPage. Signed-off-by: Tanzim Saqib <[email protected]> * feat(server): clean URLs, port fallback, embed-aware build deps server.go: - handleFrontend adds clean-URL fallback (/systems → systems.html) and a branded 404.html for unknown paths. - listenWithFallback walks up to serverPortFallbackAttempts (100) adjacent ports when the preferred one is in use. Verified locally with 10 back-to-back spawns landing on 7830..7839. - bind stays pinned to 127.0.0.1 (deterministic); display URL switches to http://localhost:7829 (secure-context + friendlier). Taskfile.yml + release.yml: task run / task build / release workflow now build the frontend first so the //go:embed directive picks up the latest dist. scripts/e2e_test.sh: bg_spawn_stax extracts the runtime URL from the banner instead of hard-coding 7829 — robust against an already-bound preferred port AND stale-zombie-PID races. ps1 mirror follows. Signed-off-by: Tanzim Saqib <[email protected]> * feat(frontend): rewrite as Vite MPA with handlebars layouts - Convert SPA to MPA: 6 HTML entries (index, search, systems, minibooks, essay, 404) sharing one bundle.js + bundle.css. - vite-plugin-handlebars block partials provide the shared chrome (layout.html + header / mobile-nav / footer); each page declares its own title / page / active variables. - Drop HTML-in-JS: page markup lives in .html files, dynamic content uses <template> + textContent + cloneNode (XSS-safe). - Single JS dispatcher (src/bundle.ts) routes per-page init by body[data-page]; shared modules under src/shared/. - Categories renamed to Systems (icon: hub). /systems renders cards from /api/systems (unwraps the systems-response envelope). - Home calls /api/hello live; placeholder grid removed. - Dev proxy /api -> localhost:7829; htmlFallback middleware rewrites /systems -> /systems.html in dev so URL shape matches production. - Post-build renameBundle plugin restores bundle.js after Rollup auto-suffixes the deduplicated entry chunk. - Delete obsolete sources: main.ts, router.ts, layouts/essay.ts, components/essay-card.ts, pages/categories.ts, pages/not-found.ts. - Seed .stax.example/ with 100 sample plans + _data_systems.yaml so the /systems page has data to render in demos. Signed-off-by: Tanzim Saqib <[email protected]> * ci: build frontend before Go in Test + Windows workflows server.go's //go:embed all:frontend/dist directive resolves at compile time, but frontend/dist is gitignored, so CI containers have nothing to embed and every Go command fails with "pattern all:frontend/dist: no matching files found". Wire setup-node + npm ci + npm run build (or apt-get install nodejs + task frontend:build for the windows-cli builder) before the Go steps so the embed has fresh dist bytes on every PR run. Signed-off-by: Tanzim Saqib <[email protected]> * chore(frontend): regenerate package-lock.json to satisfy npm ci The shipped lockfile was missing @emnapi/core and @emnapi/runtime entries that other locked deps transitively require. npm ci's strict parity check refused to install in the Test + Windows CI workflows (error EUSAGE: Missing @emnapi/[email protected] from lock file). Regenerated from scratch (rm -rf node_modules package-lock.json && npm install) so the lockfile fully reflects the dep graph. Signed-off-by: Tanzim Saqib <[email protected]> * fix(ci): install frontend deps before task build in windows-cli The windows-cli build job installed Node but never ran `npm ci`, so `task build` -> `task frontend:build` -> `npm run build` exited 127 with `vite: not found`. cc0e518 added the Node install but stopped short of installing the deps it enables. Add an explicit `npm ci` step in frontend/ between Node install and task build. Signed-off-by: Tanzim Saqib <[email protected]> * chore: hourly wording + testable skills-remove validator Signed-off-by: Tanzim Saqib <[email protected]> * feat(server,scopes): add /api/scopes + /api/scope and matching pages Signed-off-by: Tanzim Saqib <[email protected]> * feat(server,frontend): add /system + /scope detail pages backed by /api server.go - /api/systems?id=<slug>: extends the existing list endpoint with a detail mode that returns the named system plus every plan whose frontmatter `systems:` array contains the id (title/status/created per plan, no body). Unknown id -> 404 with `{"error":"..."}`. Plans sorted DESC by filename slug (newest first). - /api/scopes: lists every plan in .stax/ (slug, title, status, created, systems[]), also DESC. - /api/scope?id=<slug>: serves a single plan's detail with the markdown body pre-rendered to HTML via goldmark (GFM enabled, raw HTML escaped). 404 on unknown slug. - go.mod adds github.com/yuin/goldmark for the markdown render. - readPlanTitleAndCreated helper extracts the title:/created: frontmatter parsePlan doesn't surface. constants.go - apiScopesPath / apiScopePath alongside apiHelloPath / apiSystemsPath. plan.go, server.go - #nosec G304,G703 -- the linter's taint analyzer now flags G703 on every os.ReadFile(path) where path arrives via function param; paths are CLI-driven staxDir + slug/glob, not external input. server_test.go - readSystemDetail happy/unknown/empty-plans cases. - handleAPISystems detail mode + 404 cases. - clean-URL fallback test updated: /scopes, /scope, /system added; /minibooks removed. frontend - New pages: system.html + src/pages/system.ts (plans for one system, title left, date . status right-aligned, links to /scope?id=); scope.html + src/pages/scope.ts (single plan detail with server-rendered HTML body, system chips back to /system). - Rename minibooks -> scopes (HTML + page TS); nav icon/label flipped from "Minibooks/menu_book" to "Scopes/flag" in partials/header.html and partials/mobile-nav.html. - scopes.html row: title left, systems + date . status right- aligned to match the system page. - src/shared/relative-time.ts: relativeTime(iso, now?) emits "8 months 12 days ago" / "5 minutes ago". Used by scopes.ts, scope.ts, and system.ts. - bundle.ts wires the new pages into the data-page dispatcher; vite.config.ts lists scopes/scope/system as Rollup inputs. - essay.ts and systems.ts: chip / card links updated from /systems?id= (list URL) to /system?id= (singular detail). scripts/e2e_test.sh - Adds /api/systems?id=<known> detail case and a 404 case for unknown id. Signed-off-by: Tanzim Saqib <[email protected]> * style(scopes): tint clickable system-link chips primary The system chips on /scopes cards and /scope detail are <a> tags that deep-link into /system?id=<id>. Without a color class they rendered as neutral surfaces with no clickable affordance — visually indistinguishable from a plain badge. The non-clickable scope-status chip on /scope stays muted because it's a <span>, not a link. Signed-off-by: Tanzim Saqib <[email protected]> * fix(frontend): use bordered chips for status + clickable system links The previous templates left status spans and system-link anchors with just the bare `chip small no-elevate` classes, which inherits the parent surface-variant tint and reads as a primary-action button on the scope/system pages. Adding `border` gives them a neutral outlined look so clickable buttons stay distinguishable from row-card hover without competing for visual weight. Signed-off-by: Tanzim Saqib <[email protected]> * fix(frontend): drop primary/border from chips, use default color Signed-off-by: Tanzim Saqib <[email protected]> * style(scope): suppress disc bullet next to GFM task checkbox goldmark's GFM extension emits <li><input type=checkbox disabled>…</li> inside a regular <ul> without adding GitHub's task-list-item class, so the browser draws both a disc bullet AND the checkbox. Scoped CSS in .scope-body sets list-style:none on any <li> whose first child is a checkbox, and pulls the row back into alignment with the rest of the text. Other <ul>s on the page keep their default bullets. Signed-off-by: Tanzim Saqib <[email protected]> * style(scopes): primary color on clickable system chips The system chip on scope cards (and the scope detail header) is an <a> that deep-links to /system?id=<id>. Plain default chip makes it visually indistinguishable from a static badge — primary tints it brand color so the click affordance reads. The scope-status chip stays muted because it's a <span>, not a link. Signed-off-by: Tanzim Saqib <[email protected]> * fix(security): validate slug + replace /api/hello with /api/stats CodeQL flagged three "Uncontrolled data used in path expression" (CWE-22) alerts on this PR: - plan.go:336 readPlanBody(path) os.ReadFile(path) - plan.go:482 parsePlan(path, ...) os.ReadFile(path) - server.go:402 readPlanTitleAndCreated(planPath) os.ReadFile(planPath) The taint comes from /api/scope?id=<slug>, where slug is joined into a plan-file path. A malicious id like ../../etc/passwd would resolve outside the project's .stax/ directory. Fix landed in code (no #nosec suppressions): - planSlugRe (^\d+-[a-z0-9-]+$) validates the slug at the API boundary (readScopeDetail) before any path is composed. Malicious input never reaches filepath.Join. - isSafePlanPath() rejects paths containing a `..` segment after filepath.Clean, applied at the top of all three readers as defense-in-depth. - os.ReadFile(path) replaced with iofs.ReadFile(os.DirFS(dir), base) — Go's sandbox-FS API refuses traversal at the stdlib layer. - All previously-suppressed #nosec G304,G703 lines removed. Also in this commit (the home-page rewrite the user asked for): - Drop /api/hello entirely. apiHelloPath/handleAPIHello/helloResponse replaced with apiStatsPath/handleAPIStats/statsResponse returning {version, systems, scopes} counts. /api/stats doubles as the liveness probe e2e and bg_spawn_stax used to hit /api/hello for. - constants_e2e_test.go, main_test.go banned-leak list, and scripts/e2e_test.sh updated to the new path + assertions. - Home page redesigned: two horizontal cards (Systems count -> /systems, Scopes count -> /scopes) plus a "Latest scopes" list (top 10, descending) matching the /scopes row UI. Both counts default to zero when the project is empty. Signed-off-by: Tanzim Saqib <[email protected]> * fix(frontend): vertically center checkbox + label in scope markdown Signed-off-by: Tanzim Saqib <[email protected]> * refactor: rename plan.go and plan_test.go to scope.go and scope_test.go Signed-off-by: Tanzim Saqib <[email protected]> * chore(samples): add superseded + deprecated scope examples The .stax.example/ tree had every scope at status: valid, so the sample data didn't exercise the other two allowed statuses ('superseded' and 'deprecated') that downstream consumers (the /scopes web view, plans lint, plans list --status filter) need to render and pin against. Two coherent supersedes pairs plus one standalone deprecated scope: - 0030 add-tax-exempt-customer-flag → superseded by 0034 add-stripe- tax-integration (Stripe Tax handles exemption certificates natively, obsoleting the bespoke flag). Bidirectional supersedes / superseded_by links per the plans-lint contract. - 0086 throttle-email-notifications-per-hour → superseded by 0089 add- quiet-hours-per-timezone (timezone-aware quiet hours replace the blunt per-hour rate limit on the notification-bus). - 0023 add-apple-pay-support → deprecated (Stripe Checkout offers Apple Pay natively; no replacement plan needed). stax plans lint passes 100/100 on both folders. The same edits are applied to the local .stax/ (gitignored) so the running web UI shows the new statuses. Signed-off-by: Tanzim Saqib <[email protected]> * fix(server): rename text var to body (shadows io/text import) Signed-off-by: Tanzim Saqib <[email protected]> * feat(scope,home): resolve relation titles + drop redundant rows + align scope.go (server.go) + scope.html + scope.ts - scopeDetail.supersedes / supersededBy are now {slug, title} pairs instead of bare slug strings. New enrichRelationSlugs helper reads each linked plan's frontmatter title via the existing readPlanTitleAndCreated path (slug-as-title fallback when the linked file is missing). Chips render the human title with the slug as the hover tooltip. - The "Supersedes:" row is gone from scope.html — the status chip already conveys that this plan was superseded, and the row was showing empty even when there were no predecessors. - The "Superseded by:" row uses `row left-align middle-align wrap` so the label and chips hug the left edge instead of getting centered by the parent flex container. Status colors via shared/status.ts - applyStatusClass(el, status) tints status nodes per lifecycle: valid → default, superseded → tertiary, deprecated → error. Picks `-container` on chips (background tint) or `-text` on plain spans, based on the element's existing classes. - Wired in /scopes list, /system plan rows, /scope detail chip, and home page "Latest scopes" rows so every place a status appears, it carries the same color cue. Home page - Systems and Scopes cards add `left-align` alongside `middle-align` so count + label hug the left edge of the card rather than the row's default justify-content. Signed-off-by: Tanzim Saqib <[email protected]> * fix(frontend): drop icons and left-align from home cards Signed-off-by: Tanzim Saqib <[email protected]> * fix(scope): honor [hidden] over BeerCSS .row display The /scope page's superseded-by row is <div class="row …" hidden>. BeerCSS sets display: flex on .row, which has the same specificity as the UA stylesheet's [hidden] { display: none } but wins by source order — so the row stayed visible on every scope (including plans with no superseded_by relation at all). A global [hidden] rule with !important restores the expected collapse. Defensive fix in CSS rather than per-row class toggling so the same problem can't bite any future row that mixes a layout class with the hidden attribute. Signed-off-by: Tanzim Saqib <[email protected]> * fix(frontend): truncate brief inline on /systems rows Signed-off-by: Tanzim Saqib <[email protected]> * feat(server,systems): real scope count per system on /systems systemEntry grows a Scopes int field that readSystemsForAPI fills by walking .stax/*.md once and tallying each plan's frontmatter systems: array. handleAPISystems passes staxDir (not the registry file path) so the same walk powers list + count without a second caller dancing around the new signature. Frontend drops the hash-derived 'N / M chapters' placeholder and renders 'N scope(s)' with singular/plural agreement, fed from the new live count. Verified locally against the project's .stax/ tree: six systems report 16-18 scopes each (matches the plan files declaring them). TestReadSystemsForAPI rewritten to seed plans alongside the registry and pin the tally. Signed-off-by: Tanzim Saqib <[email protected]> * feat(scopes): tint flag icon when a scope has open tasks Signed-off-by: Tanzim Saqib <[email protected]> * feat: tint flag icon primary on rows with open tasks Signed-off-by: Tanzim Saqib <[email protected]> * feat(search,systems): wire /api/search and align /systems row CSS Backend adds /api/search?q=<query>: returns two grouped lists (scopes, then systems) filtered by case-insensitive substring across slug/title/status/system-ids/body for scopes and id/name/brief for systems. Frontend /search renders the two sections using the same row templates the /scopes and /systems list pages use, plus debounced input + URL ?q= sync. /systems and /search system rows shrink the heading to h6.small (matching /scopes) and widen the name→brief gap from ml-s to ml-m so the row reads cleanly instead of the title crashing into the brief. Signed-off-by: Tanzim Saqib <[email protected]> * chore(frontend): serve Geist from CDN instead of bundling the woff2 Drop the @fontsource-variable/geist npm dep (and its 5 latin/cyrillic woff2 files in dist/assets/) in favor of a single @font-face rule in app.scss that points at jsdelivr's fontsource CDN for the latin variable-weight subset. Shaves the build output and lets the browser cache the font across other sites that pull the same URL. The src/ bundle no longer imports the npm CSS; env.d.ts loses its module shim. Signed-off-by: Tanzim Saqib <[email protected]> * chore(samples): add extends + extended_by scope pairs The .stax.example/ tree had every scope at status: valid with no extends/extended_by links, so downstream consumers (lint symmetry check, /scope detail page's relation rows when those land, /api/scope's enriched relation arrays) never exercised the 'this scope builds on that one' shape. Two coherent extends pairs, both stay status: valid because extends doesn't retire anything: - 0051 add-kafka-consumer ← extended by 0055 add-backpressure- handling. Backpressure pauses the same Kafka consumer 0051 stands up. Same ingest-pipeline system. - 0068 add-online-feature-serving ← extended by 0077 add-feature- drift-detection. Drift detection compares against distributions the live serving path 0068 ships emits. Same feature-store system. Bidirectional extends / extended_by per the plans-lint contract. stax plans lint passes 100/100 on both .stax/ and .stax.example/. The same edits land in the local .stax/ (gitignored) so the running web UI surfaces the new relations. Signed-off-by: Tanzim Saqib <[email protected]> * feat(server): gate bare stax on .stax/_config.lock; print init banner Bare `stax` (and `stax --no-browser`) now refuses to bind the listener or launch a browser when cwd / --cwd points at a directory that hasn't been initialized as a stax project. The check fires after ensureBundledAgents (the user-scope embed still materializes on first run) and after the --version short-circuit (installer scripts depend on --version working in any directory), then either proceeds to runServer or prints `notProjectBanner` on stderr and exits 2. The marker is .stax/_config.lock — same one stax plans * and stax skills remove --project key on. checkProject() and the banner string are both reused so the UX stays uniform across every command that gates on project state. scripts/e2e_test.sh - Existing "stax --no-browser starts the loopback API server" case now seeds a fresh project + passes --cwd so it crosses the new gate. - New "stax --cwd <not-a-project> prints init banner and exits 2" case exercises the negative path (exit 2, no stdout, stderr carries the banner and the `stax init` hint). scripts/e2e_test.ps1 - Mirrors both updates so the Windows runner exercises the same contract. Signed-off-by: Tanzim Saqib <[email protected]> * chore(samples): richer extends/supersedes/deprecated coverage Apply 5 extends pairs sourced from the existing dataset and add 6 new scopes (0101-0106) that establish 3 more supersedes pairs, 2 more extends pairs, and a second standalone deprecated case. Extends — new pairs (foundation ← extension): 0019 retry-stripe-webhooks ← 0029 reconcile-payouts-daily 0021 usage-based-pricing ← 0033 partial-refunds-on-usage 0053 schema-validation ← 0054 dlq-for-malformed 0068 online-feature-serving ← 0071 redis-cache (joins 0077) 0085 sms-delivery-2fa ← 0091 sms-delivery-receipts Supersedes — new retirements: 0022 eu-vat-eea → 0034 stripe-tax (joins 0030 in 0034's multi-element supersedes) 0020 generate-pdf-invoices → 0101 stripe-hosted-invoice-pages 0028 percentage-discounts → 0102 stripe-coupons 0043 mask-pii-bi-layer → 0103 mask-pii-warehouse-views Deprecated — second standalone case: 0106 cross-region-active-active-failover-for-ingest Final tally per folder (.stax + .stax.example): 106 scopes / 98 valid / 6 superseded / 2 deprecated 9 extends links (1 multi-element on 0068) 5 supersedes records (1 multi-element on 0034) retiring 6 scopes stax plans lint passes 106/106 on both folders. Signed-off-by: Tanzim Saqib <[email protected]> * docs(agents): add frontend stack and conventions section The CLI hard rules in AGENTS.md are silent on what the web UI under `frontend/` is built with and how it's organized, which leaves a future contributor to reverse-engineer the MPA shape, the `<template>` + `textContent` rendering pattern, the status-color helper, the shared module layout, and the API shape conventions every time. Codify the conventions next to the existing CLI rules so the contract is one read. Covers: Vite MPA with handlebars block partials, BeerCSS + Material Symbols + Geist via CDN @font-face, Biome/Knip/Terser, server-side goldmark for plan markdown; the no-HTML-in-JS rule, single bundle.js/bundle.css output, `data-page` / `data-active` dispatcher keys, color cues via `shared/status.ts`, relative time via `shared/relative-time.ts`, shared module discipline, API shape conventions, and dev proxy as the single backend URL source. Signed-off-by: Tanzim Saqib <[email protected]> * fix(frontend): regen lock with optional deps Signed-off-by: Tanzim Saqib <[email protected]> * docs(internal): manual eval prompts + contradiction cases Extract the prompts the skills-evals/ suite drives Claude / Cline / Codex / Pi / omp / OpenCode / Copilot CLI with, so a human can run the same flows by hand and watch the SKILL files behave end-to-end: one-shot scope, scope+ship, extends pair, supersedes pair, stream- json smoke, and the Claude hook-firing smoke. Add Part 2-4: contradiction cases the lint will never catch (mutually exclusive responses, same-window contradictions, retain-vs-purge, stale-foundation extends, supersedes-without-cleanup, EARS-subject ambiguity), six concrete contradictions keyed to .stax.example scopes (token-expiry, dedup-window, archive-vs-purge, auto-cancel- vs-manual-review, quiet-hours carve-out, cleanup-gap supersede), and the SKILL-rule coverage gaps no automated check can see (plan-only contract, status flip discipline, Approach without covering Tasks, vague EARS responses, system granularity drift). Answers the implicit 'what else are we missing to fully exercise both SKILL files?' — most remaining gaps are semantic, not structural. Signed-off-by: Tanzim Saqib <[email protected]> * docs: align with bare-stax gate + plan.go -> scope.go rename docs/public/reference.md - The bare `stax` / `stax --no-browser` rows now mention the project-marker requirement and link to the marker-check section. - Project-scope marker check section: rewritten to cover the bare-stax entry too, named the actual marker file (`.stax/_config.lock`), and replaced the stale two-line banner with the real one-line text from `notProjectBanner` in init.go. docs/internal/telemetry.md - `plans_lint` / `plans_next_prefix` event source rows updated to point at `scope.go` (was `plan.go`, renamed in a58925d). Signed-off-by: Tanzim Saqib <[email protected]> * fix(installers): swap INSTALL_LOCAL bare-stax seed for post-install INSTALL_LOCAL.{sh,ps1} ran bare `stax` to seed ~/.stax/agents/ from the binary's embed, matching the release installers' historical behavior. Bare `stax` now launches the loopback web UI AND short- circuits with 'not a stax project' when cwd has no .stax/_config.lock (per runDefault's checkProject call) — both INSTALL_LOCAL scripts have been calling that branch from a fresh / non-project directory since the marker check landed, so the Windows-CLI smoke job has been failing every PR run with 'stax first-run seed failed'. Switch both local installers to `stax post-install` — the dedicated installer hook that materialises ~/.stax/agents/ and exits silently regardless of cwd, same fix the release installers (INSTALL.sh / INSTALL.ps1) already use. Also adds a 'Browsing your project' section to docs/public/getting-started.md introducing bare `stax` as the web-UI entry point, since the public docs previously stopped at /scope and /ship without mentioning the UI at all. Signed-off-by: Tanzim Saqib <[email protected]> * docs(frontend): heavy inline doc for shared utils and 2 page entries Signed-off-by: Tanzim Saqib <[email protected]> * ci(windows): build frontend in smoke job so e2e go build resolves embed scripts/e2e_test.ps1 does its own `go build` (release-flavored, version-stamped to v0.0.0-e2e for assertions). server.go embeds `frontend/dist/` via `//go:embed all:frontend/dist`, and the dist tree is gitignored — the upstream build job populated it inside its own container, but that workspace doesn't survive the artifact handoff to the windows smoke runner. Result: every smoke run since the frontend landed fails with `pattern all:frontend/dist: no matching files found` before any test case runs. Mirror the build job's preparation in the smoke job: setup-node, install task, `npm ci` (frontend:build deliberately skips deps so `task run` stays snappy in the dev loop), `task frontend:build`. The in-harness rebuild then resolves the embed and the test cases get to execute. Signed-off-by: Tanzim Saqib <[email protected]> * ci(windows): use npm directly so PowerShell finds the frontend build The previous attempt installed task via the taskfile.dev shell installer in a bash step, which drops `task.exe` at `/c/Users/runneradmin/bin` and appends that mingw-style path to `$GITHUB_PATH`. PowerShell can't resolve the bash-style path, so the next step's `task frontend:build` aborts with `The term 'task' is not recognized`. `task frontend:build` is literally `npm run build` under `frontend/` per the Taskfile, and the smoke job doesn't need task for anything else. Drop the installer, call npm directly, and pick up consistency with test.yml as a bonus. Signed-off-by: Tanzim Saqib <[email protected]> * test(e2e): port /api/hello -> /api/stats rename into the windows harness The `/api/hello` endpoint was retired in favor of `/api/stats` (the new liveness + counts probe), and `scripts/e2e_test.sh` was updated for the rename — but `scripts/e2e_test.ps1` still pinned `/api/hello`. Every Windows smoke run since that landed timed out in `Start-StaxServer` waiting for a 200 from a path the server no longer registers. Mirror the bash harness: rename `STAX_API_HELLO_PATH` to `STAX_API_STATS_PATH`, point the readiness probe at it, and replace the hello-shape assertions (`"message":"hello"` + version) with the stats shape used in the bash case (`"version":...`, `"systems":`, `"scopes":`). Also rename the no-leak assertion in `stax -h` to follow. Satisfies the AGENTS.md "Windows e2e parity" rule that was missed when the rename landed. Signed-off-by: Tanzim Saqib <[email protected]> * test(e2e): wait on banner, not a hardcoded URL, in Start-StaxServer `Start-StaxServer` was hammering `http://localhost:7829/api/stats` on a fixed 5s deadline and discarding the spawned process's stdout/stderr on timeout — so a server that fell forward to an adjacent port (per `serverPortFallbackAttempts`) or printed its diagnostic to stderr looked identical to "server hung". The bash harness handles this by parsing the "Stax server listening on <URL>" banner and probing that URL; mirror that here. `Start-StaxServer` now: - Polls the spawn's captured stdout for the listening banner. - Extracts the runtime URL and probes /api/stats against it. - Attaches the URL as `StaxUrl` on the returned Process object so every caller probes the same URL the server actually bound. - On timeout, dumps stdout and stderr into the throw message so CI log readers can diagnose without a verbose re-run. Updates the three server-spawning cases (`--no-browser` stats, scoped `/api/systems`, empty-project `/api/systems`) and the banner-content assertion to read `$srv.StaxUrl` instead of the static constant. Signed-off-by: Tanzim Saqib <[email protected]> * test(e2e): probe via 127.0.0.1 on windows to dodge IPv6 localhost Diagnostic dump from the prior smoke run showed the server printed the listening banner ("Stax server listening on http://localhost:7829") and stayed up — but every Invoke-WebRequest against that URL timed out. Root cause: `serverListenAddr` binds 127.0.0.1 (IPv4 only), Windows' resolver returns ::1 first for `localhost`, so the probe hits an IPv6 endpoint nothing is listening on. curl on Linux prefers the IPv4 address for localhost, which is why the bash harness never tripped on this. Probe via the IPv4 literal while keeping the banner URL for banner-content assertions: - Add `StaxProbeUrl` on the returned Process object: the banner URL with `http://localhost` rewritten to `http://127.0.0.1`. - Probes (in-poller and the three test cases) use `StaxProbeUrl`. - `StaxUrl` stays as the literal banner URL so the "banner contains the listen URL" assertion keeps checking what the server actually printed. Signed-off-by: Tanzim Saqib <[email protected]> * test(e2e): seed a project for the version-vs-banner case `stax --version differs from the bare-stax server banner` spawns the server via `Start-StaxServer --no-browser` with no `--cwd`. After the project-marker gate landed (commit 68455a1), bare `stax --no-browser` exits 2 with the `not a stax project` banner unless it can see a `.stax/_config.lock` in cwd. The other three server-spawning cases were updated when the gate landed; this one was missed and Start-StaxServer threw "process exited before listening" the moment the case ran. Because `$ErrorActionPreference = 'Stop'` is set globally, that throw aborts the script before the remaining ~600 cases get a chance to run. Seed a fresh project + Initialize-ProjectScaffold and pass --cwd to it, and switch the URL assertions from the static `$STAX_SERVER_DISPLAY_URL` constant to `$srv.StaxUrl` (the URL the server actually printed in the banner). Same intent — pin the divergence between --version notice and the server banner — without the gate-induced false negative. Signed-off-by: Tanzim Saqib <[email protected]> * feat(frontend): scope icon, FOUT fix, essay drop, sample lock Five orthogonal threads bundled together; each is small enough on its own that splitting them would be more churn than signal. - chore: ignore frontend/.stax (local dev scaffold) and rename the home page <title> from "Stax" to "Home" so the tab matches the active sidebar item like every other page. - chore(frontend): drop the essay/minibook scaffold. essay.html, src/pages/essay.ts, public/default-cover.jpg, the .essay-meta CSS, the svg text font override (only needed because Essay SVGs hard-coded font-family), and the essay entries in vite.config.ts/bundle.ts and the /essay clean-URL test. The page was a layout-only placeholder with PLACEHOLDER content and never connected to a backend endpoint. - docs(stax.example): seed .stax.example/_config.lock with the defaults writePlansScaffold pins (prefix_width=4, max_plan_lines=30, review_per=task). The example tree already shipped _data_systems.yaml + sample plans; the lock was the missing piece that makes the directory pass checkProject if copied into cwd. - feat(scope): the /scope?id= title icon now honors the same primary-text-on-hasOpenTasks convention scopes.ts:58-61 applies to list rows. Adds HasOpenTasks (`json:"hasOpenTasks"`) to scopeDetail and populates it via strings.Contains(body, "- [ ]") — mirroring readPlanForAPI server.go:428. Pinned by TestReadScopeDetail_HasOpenTasks. scope.html gives the flag <i> an id; scope.ts adds the class when data.hasOpenTasks is true. - perf(frontend): eliminate the Material Symbols FOUT. * layout.html preloads /assets/material-symbols-outlined.woff2 with rel=preload, as=font, crossorigin (crossorigin is mandatory — an anonymous-CORS mismatch makes the browser refetch). * server.go attaches Cache-Control: public, max-age=31536000, immutable to /assets/*.woff2 inside handleFrontend's exact-file branch (only fires for files that exist, so 404s don't inherit the long cache). New constants frontendAssetsURLPrefix, woff2Ext, assetImmutableCacheControl per the path-as-constant rule, pinned by TestHandleFrontend_WOFF2HasImmutableCacheControl with a negative twin so the narrow stays narrow. * vite.config.ts's new dropUnusedSymbolFonts plugin runs closeBundle to strip the @font-face blocks for Rounded/Sharp/Subset (~1.4 MB of dist/assets/ that BeerCSS emits but no element ever requests since --font-icon defaults to "Material Symbols Outlined") and delete the orphan woff2 files. Net dist/ size: ~1.5 MB → 848 KB. Signed-off-by: Tanzim Saqib <[email protected]> --------- Signed-off-by: Tanzim Saqib <[email protected]>
1 parent 3558d4e commit 049a75b

189 files changed

Lines changed: 10232 additions & 256 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.github/workflows/release.yml‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -26,6 +26,27 @@ jobs:
2626
with:
2727
go-version-file: go.mod
2828

29+
# The Go binary embeds `frontend/dist/` via //go:embed all:frontend/dist
30+
# in server.go — that directive is baked at compile time, so the
31+
# frontend MUST be built before the Go cross-compile fires.
32+
# Without these steps the released binaries would ship whatever
33+
# dist tree happened to be checked in (likely stale or empty,
34+
# depending on .gitignore), and the web UI on bare `stax` would
35+
# 404 in the wild even though local builds worked.
36+
- uses: actions/setup-node@v4
37+
with:
38+
node-version: "22"
39+
cache: "npm"
40+
cache-dependency-path: frontend/package-lock.json
41+
42+
- name: Install frontend deps
43+
working-directory: frontend
44+
run: npm ci
45+
46+
- name: Build frontend (produces frontend/dist for the Go embed)
47+
working-directory: frontend
48+
run: npm run build
49+
2950
- name: Validate version format
3051
run: |
3152
if ! echo "${{ inputs.version }}" | grep -qE '^[0-9]+\.[0-9]+\.[0-9]+(-[a-zA-Z0-9.]+)?$'; then

‎.github/workflows/test.yml‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -45,6 +45,24 @@ jobs:
4545
go-version-file: go.mod
4646
cache: false
4747

48+
# The Go binary embeds `frontend/dist/` via //go:embed all:frontend/dist
49+
# in server.go — `frontend/dist/` is gitignored, so we MUST build it
50+
# before `go vet` / `go test` / e2e. Without these steps every Go
51+
# command fails with "pattern all:frontend/dist: no matching files".
52+
- uses: actions/setup-node@v4
53+
with:
54+
node-version: "22"
55+
cache: "npm"
56+
cache-dependency-path: frontend/package-lock.json
57+
58+
- name: Install frontend deps
59+
working-directory: frontend
60+
run: npm ci
61+
62+
- name: Build frontend (produces frontend/dist for the Go embed)
63+
working-directory: frontend
64+
run: npm run build
65+
4866
- name: go vet
4967
run: go vet ./...
5068

‎.github/workflows/windows-cli.yml‎

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -84,6 +84,26 @@ jobs:
8484
which task
8585
task --version
8686
87+
# `task build` depends on `task frontend:build` (per Taskfile.yml)
88+
# so the //go:embed all:frontend/dist directive resolves against a
89+
# fresh dist tree. The golang:1.26-bookworm container ships Go but
90+
# not Node — install it explicitly here so `npm ci && npm run
91+
# build` succeeds before the cross-compile loop runs.
92+
- name: install node
93+
run: |
94+
set -x
95+
curl -fsSL https://deb.nodesource.com/setup_22.x | bash -
96+
apt-get install -y nodejs
97+
node --version
98+
npm --version
99+
100+
# `task build` -> `task frontend:build` -> `npm run build` needs vite
101+
# on PATH, which only exists after `npm ci` populates frontend/node_modules.
102+
# The Taskfile's frontend:build does not install deps, so we install them here.
103+
- name: install frontend deps
104+
working-directory: frontend
105+
run: npm ci
106+
87107
- name: task build
88108
run: |
89109
set -x
@@ -197,6 +217,33 @@ jobs:
197217
& $bin -h
198218
if ($LASTEXITCODE -ne 0) { throw "$bin -h exited $LASTEXITCODE" }
199219
220+
# scripts/e2e_test.ps1 does its own `go build` (release-flavored,
221+
# version-stamped to v0.0.0-e2e for harness assertions). server.go's
222+
# `//go:embed all:frontend/dist` requires `frontend/dist/` on disk at
223+
# compile time, and `frontend/dist/` is gitignored — the upstream
224+
# `build` job populated it inside its own container, but that
225+
# workspace doesn't survive the artifact handoff. Mirror what the
226+
# test.yml workflow does so the in-harness rebuild resolves the embed.
227+
#
228+
# Skipping `task frontend:build` and going straight to `npm run build`
229+
# because the taskfile.dev installer drops `task.exe` at a mingw-style
230+
# path (e.g. /c/Users/runneradmin/bin) that does not resolve on
231+
# PowerShell's PATH, and `task frontend:build` is literally `npm run
232+
# build` in `frontend/` anyway.
233+
- uses: actions/setup-node@v4
234+
with:
235+
node-version: "22"
236+
cache: "npm"
237+
cache-dependency-path: frontend/package-lock.json
238+
239+
- name: install frontend deps
240+
working-directory: frontend
241+
run: npm ci
242+
243+
- name: build frontend (produces frontend/dist for the in-harness go build)
244+
working-directory: frontend
245+
run: npm run build
246+
200247
- name: run e2e suite
201248
run: |
202249
Write-Host "=== invoking e2e_test.ps1 (verbose=${{ inputs.verbose }}) ==="

‎.gitignore‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
.DS_Store
22
/bin/
3+
.stax
34

45
# /stax and /stax.exe — accidental `go build` output at the module root.
56
# Go names a main package's binary after its directory, so a bare
Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
---
2+
title: Add OAuth2 PKCE support for native mobile clients
3+
status: valid
4+
systems: [auth-service]
5+
created: 2025-05-28T17:26:42Z
6+
---
7+
8+
## Goal
9+
Allow iOS and Android clients to complete the OAuth2 authorization code flow without a confidential client secret by requiring PKCE.
10+
11+
## Approach
12+
- Accept S256 PKCE code challenges on the authorize endpoint.
13+
- Require the code verifier on the token exchange.
14+
- Reject plain-text PKCE method to enforce S256.
15+
16+
## Tasks
17+
- [x] When a native client initiates authorization, the Auth Service shall require an S256 code challenge.
18+
- [x] When the token exchange omits the code verifier, the Auth Service shall reject the request with invalid_grant.
19+
- [x] If a client submits a plain code challenge method, then the Auth Service shall reject the authorization request.
Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
---
2+
title: Rotate session tokens every twenty four hours on active sessions
3+
status: valid
4+
systems: [auth-service]
5+
created: 2025-06-10T13:34:42Z
6+
---
7+
8+
## Goal
9+
Shrink the window of a stolen session token by rotating the cookie value daily while keeping the user signed in.
10+
11+
## Approach
12+
- Issue a new opaque session id on every 24h boundary.
13+
- Invalidate the previous id after a five-minute grace.
14+
15+
## Tasks
16+
- [x] While a session is older than twenty four hours, the Auth Service shall issue a new session id on the next request.
17+
- [x] When a session id is rotated, the Auth Service shall accept the previous id for five minutes.
18+
- [x] If a request presents an id that was rotated more than five minutes ago, then the Auth Service shall return 401.
Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
---
2+
title: Add WebAuthn passkey enrollment for end users
3+
status: valid
4+
systems: [auth-service]
5+
created: 2025-06-11T10:00:55Z
6+
---
7+
8+
## Goal
9+
Let users register a platform passkey as an additional authentication factor and use it for subsequent sign-ins.
10+
11+
## Approach
12+
- Expose enrollment and assertion endpoints.
13+
- Store credential ids and public keys per user.
14+
15+
## Tasks
16+
- [x] When a user enrolls a passkey, the Auth Service shall store its credential id and public key.
17+
- [x] When a user signs in with a passkey assertion, the Auth Service shall verify the assertion against the stored public key.
18+
- [x] If a passkey assertion signature is invalid, then the Auth Service shall reject the sign-in attempt.
Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
---
2+
title: Enforce multi factor authentication on all admin accounts
3+
status: valid
4+
systems: [auth-service]
5+
created: 2025-06-14T00:50:36Z
6+
---
7+
8+
## Goal
9+
Every account with the admin role must complete a second factor on each sign-in within thirty days.
10+
11+
## Approach
12+
- Add an admin-role MFA enforcement gate.
13+
- Block password-only sign-ins for admins after the deadline.
14+
15+
## Tasks
16+
- [x] While an account holds the admin role, the Auth Service shall require a second factor on every sign-in.
17+
- [x] If an admin attempts a password-only sign-in after the deadline, then the Auth Service shall block the session and prompt enrollment.
Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
---
2+
title: Lock accounts after five consecutive failed login attempts
3+
status: valid
4+
systems: [auth-service]
5+
created: 2025-06-14T23:43:03Z
6+
---
7+
8+
## Goal
9+
Defend against credential stuffing by locking an account for fifteen minutes after five failed password attempts in a row.
10+
11+
## Approach
12+
- Track failure counter per account id.
13+
- Reset the counter on a successful sign-in.
14+
15+
## Tasks
16+
- [x] When an account has five consecutive failed sign-ins, the Auth Service shall lock the account for fifteen minutes.
17+
- [x] When a successful sign-in occurs, the Auth Service shall reset the failure counter.
18+
- [x] If a sign-in is attempted on a locked account, then the Auth Service shall return account_locked without revealing whether the password was correct.
Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
---
2+
title: Migrate session storage from Redis to Postgres
3+
status: valid
4+
systems: [auth-service]
5+
created: 2025-06-15T17:33:56Z
6+
---
7+
8+
## Goal
9+
Move session records into Postgres so sessions survive a Redis outage and gain transactional guarantees with the user table.
10+
11+
## Approach
12+
- Dual-write to Redis and Postgres for one release.
13+
- Cut reads over to Postgres once parity is confirmed.
14+
- Decommission the Redis namespace.
15+
16+
## Tasks
17+
- [x] While dual-write is enabled, the Auth Service shall write each session to Redis and Postgres.
18+
- [x] When Postgres is the read source, the Auth Service shall stop reading from Redis.
19+
- [x] If Postgres is unavailable during dual-write, then the Auth Service shall reject the sign-in instead of falling back silently.

0 commit comments

Comments
 (0)