Repository navigation
Commit 049a75b
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
- .github/workflows
- .stax.example
- docs
- internal
- public
- frontend
- partials
- public
- src
- pages
- styles
- scripts
Some content is hidden
Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
26 | 26 | | |
27 | 27 | | |
28 | 28 | | |
| 29 | + | |
| 30 | + | |
| 31 | + | |
| 32 | + | |
| 33 | + | |
| 34 | + | |
| 35 | + | |
| 36 | + | |
| 37 | + | |
| 38 | + | |
| 39 | + | |
| 40 | + | |
| 41 | + | |
| 42 | + | |
| 43 | + | |
| 44 | + | |
| 45 | + | |
| 46 | + | |
| 47 | + | |
| 48 | + | |
| 49 | + | |
29 | 50 | | |
30 | 51 | | |
31 | 52 | | |
| |||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
45 | 45 | | |
46 | 46 | | |
47 | 47 | | |
| 48 | + | |
| 49 | + | |
| 50 | + | |
| 51 | + | |
| 52 | + | |
| 53 | + | |
| 54 | + | |
| 55 | + | |
| 56 | + | |
| 57 | + | |
| 58 | + | |
| 59 | + | |
| 60 | + | |
| 61 | + | |
| 62 | + | |
| 63 | + | |
| 64 | + | |
| 65 | + | |
48 | 66 | | |
49 | 67 | | |
50 | 68 | | |
| |||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
84 | 84 | | |
85 | 85 | | |
86 | 86 | | |
| 87 | + | |
| 88 | + | |
| 89 | + | |
| 90 | + | |
| 91 | + | |
| 92 | + | |
| 93 | + | |
| 94 | + | |
| 95 | + | |
| 96 | + | |
| 97 | + | |
| 98 | + | |
| 99 | + | |
| 100 | + | |
| 101 | + | |
| 102 | + | |
| 103 | + | |
| 104 | + | |
| 105 | + | |
| 106 | + | |
87 | 107 | | |
88 | 108 | | |
89 | 109 | | |
| |||
197 | 217 | | |
198 | 218 | | |
199 | 219 | | |
| 220 | + | |
| 221 | + | |
| 222 | + | |
| 223 | + | |
| 224 | + | |
| 225 | + | |
| 226 | + | |
| 227 | + | |
| 228 | + | |
| 229 | + | |
| 230 | + | |
| 231 | + | |
| 232 | + | |
| 233 | + | |
| 234 | + | |
| 235 | + | |
| 236 | + | |
| 237 | + | |
| 238 | + | |
| 239 | + | |
| 240 | + | |
| 241 | + | |
| 242 | + | |
| 243 | + | |
| 244 | + | |
| 245 | + | |
| 246 | + | |
200 | 247 | | |
201 | 248 | | |
202 | 249 | | |
| |||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
1 | 1 | | |
2 | 2 | | |
| 3 | + | |
3 | 4 | | |
4 | 5 | | |
5 | 6 | | |
| |||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
| 1 | + | |
| 2 | + | |
| 3 | + | |
| 4 | + | |
| 5 | + | |
| 6 | + | |
| 7 | + | |
| 8 | + | |
| 9 | + | |
| 10 | + | |
| 11 | + | |
| 12 | + | |
| 13 | + | |
| 14 | + | |
| 15 | + | |
| 16 | + | |
| 17 | + | |
| 18 | + | |
| 19 | + | |
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
| 1 | + | |
| 2 | + | |
| 3 | + | |
| 4 | + | |
| 5 | + | |
| 6 | + | |
| 7 | + | |
| 8 | + | |
| 9 | + | |
| 10 | + | |
| 11 | + | |
| 12 | + | |
| 13 | + | |
| 14 | + | |
| 15 | + | |
| 16 | + | |
| 17 | + | |
| 18 | + | |
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
| 1 | + | |
| 2 | + | |
| 3 | + | |
| 4 | + | |
| 5 | + | |
| 6 | + | |
| 7 | + | |
| 8 | + | |
| 9 | + | |
| 10 | + | |
| 11 | + | |
| 12 | + | |
| 13 | + | |
| 14 | + | |
| 15 | + | |
| 16 | + | |
| 17 | + | |
| 18 | + | |
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
| 1 | + | |
| 2 | + | |
| 3 | + | |
| 4 | + | |
| 5 | + | |
| 6 | + | |
| 7 | + | |
| 8 | + | |
| 9 | + | |
| 10 | + | |
| 11 | + | |
| 12 | + | |
| 13 | + | |
| 14 | + | |
| 15 | + | |
| 16 | + | |
| 17 | + | |
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
| 1 | + | |
| 2 | + | |
| 3 | + | |
| 4 | + | |
| 5 | + | |
| 6 | + | |
| 7 | + | |
| 8 | + | |
| 9 | + | |
| 10 | + | |
| 11 | + | |
| 12 | + | |
| 13 | + | |
| 14 | + | |
| 15 | + | |
| 16 | + | |
| 17 | + | |
| 18 | + | |
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
| 1 | + | |
| 2 | + | |
| 3 | + | |
| 4 | + | |
| 5 | + | |
| 6 | + | |
| 7 | + | |
| 8 | + | |
| 9 | + | |
| 10 | + | |
| 11 | + | |
| 12 | + | |
| 13 | + | |
| 14 | + | |
| 15 | + | |
| 16 | + | |
| 17 | + | |
| 18 | + | |
| 19 | + | |
0 commit comments