From 8b7a586629b34ec169bcc237c20d4edcdd418e18 Mon Sep 17 00:00:00 2001 From: theworker02 Date: Fri, 14 Aug 2026 21:53:41 -0400 Subject: [PATCH] docs: expand Pages site, README, and release notes Put the Cursor plugin listing on the README and docs CTAs, and keep write-docs from overwriting the hand-crafted home. Co-authored-by: Cursor --- .github/workflows/release.yml | 26 +- CHANGELOG.md | 7 + CONTRIBUTING.md | 13 +- README.md | 493 +++++++++++++++------ apps/docs/.vitepress/config.ts | 12 +- apps/docs/.vitepress/theme/HomeLanding.vue | 247 +++++++++++ apps/docs/.vitepress/theme/custom.css | 437 ++++++++++++++++++ apps/docs/.vitepress/theme/index.ts | 13 + apps/docs/getting-started/cursor-setup.md | 31 +- apps/docs/getting-started/installation.md | 25 +- apps/docs/getting-started/introduction.md | 12 + apps/docs/index.md | 16 +- apps/docs/mcp/setup.md | 14 +- apps/docs/mcp/tools.md | 4 +- apps/docs/reference/cli.md | 6 +- apps/docs/reference/troubleshooting.md | 14 +- apps/docs/tools/releases.md | 15 +- docs/RELEASE.md | 238 ++++++++++ scripts/build-plugin.mjs | 9 +- scripts/package-release.mjs | 8 +- scripts/write-docs.mjs | 142 +++++- tests/plugin-ui.test.ts | 8 + 22 files changed, 1616 insertions(+), 174 deletions(-) create mode 100644 apps/docs/.vitepress/theme/HomeLanding.vue create mode 100644 apps/docs/.vitepress/theme/custom.css create mode 100644 apps/docs/.vitepress/theme/index.ts create mode 100644 docs/RELEASE.md diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index ce4e882..c6bc692 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -38,16 +38,22 @@ jobs: dist-release/stackglass-cursor-plugin.zip dist-release/checksums.txt body: | - Stackglass 1.1.0 is a **GitHub Release**, not an npm package. Do not `npm install stackglass` or `npm link`. + Stackglass is a **GitHub Release**, not an npm package. Do not `npm install stackglass`, `npm link`, or `npm publish`. Requires **Node.js >= 22.13.0**. + Cursor plugin: https://cursor.directory/plugins/stackglass + + Full artifact instructions: https://github.com/theworker02/stackglass/blob/master/docs/RELEASE.md + ## Artifacts - - `stackglass-cli.zip` — built CLI plus the MCP server and production dependencies - - `stackglass-mcp.zip` — same runtime; start with `node scripts/stackglass-mcp.mjs` - - `stackglass-cursor-plugin.zip` — Cursor Open Plugins layout - - `checksums.txt` — SHA-256 of the zips + - `stackglass-cli.zip` — built CLI plus the MCP server and production dependencies. Run `node cli/dist/bin.js help`. + - `stackglass-mcp.zip` — same runtime tree as the CLI zip. Start with `STACKGLASS_ROOT=/your/project node scripts/stackglass-mcp.mjs`. + - `stackglass-cursor-plugin.zip` — Cursor Open Plugins layout (`.cursor-plugin/plugin.json`). Prefer the cursor.directory listing when you can. + - `checksums.txt` — SHA-256 of the three zips. Verify before you run an extracted tree. + + The CLI zip and MCP zip are the same runnable tree. The plugin zip is a different layout and does not include `cli/dist`. ## CLI @@ -58,14 +64,20 @@ jobs: node scripts/glass.mjs init ``` - ## MCP (22 tools) + If `node_modules` is missing: `npm install --omit=dev --ignore-scripts` inside the extracted tree only. + + ## MCP (exactly 22 tools) ```bash STACKGLASS_ROOT=/path/to/your/project node scripts/stackglass-mcp.mjs ``` + `STACKGLASS_ROOT` is the workspace to observe. New capability is an optional argument, never a 23rd tool. + ## Cursor plugin - Extract `stackglass-cursor-plugin.zip` and add that folder as a Cursor plugin. `mcp.json` starts `node scripts/stackglass-mcp.mjs`. + Install from https://cursor.directory/plugins/stackglass or extract `stackglass-cursor-plugin.zip` and add that folder as a Cursor plugin. `mcp.json` starts `node scripts/stackglass-mcp.mjs` and sets `STACKGLASS_ROOT` to the workspace. + + You still need the CLI zip or a built clone to run `init`, `status`, and `dashboard`. Docs: https://theworker02.github.io/stackglass/ diff --git a/CHANGELOG.md b/CHANGELOG.md index 7d6b387..7df1730 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -9,8 +9,15 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ### Added +- Documentation site landing with glass/stacked-pane theme, Cursor plugin CTA, and sections for the 22 tools, GlassLab, GlassLens, dashboard, privacy, and install +- In-repo [docs/RELEASE.md](docs/RELEASE.md) covering each GitHub Release zip, checksums, and plugin vs CLI vs MCP +- README install CTA for the Cursor plugin at https://cursor.directory/plugins/stackglass + ### Changed +- README, getting-started docs, troubleshooting, and published v1.1.0 release notes expanded with source install, `STACKGLASS_ROOT`, and artifact usage +- `scripts/write-docs.mjs` refuses to overwrite the hand-crafted `apps/docs/index.md` + ### Fixed ### Deprecated diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 01bc5dc..956c3bd 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -45,17 +45,24 @@ The public MCP surface is 22 tools. Prefer new arguments or UI/CLI commands over Docs are VitePress in `apps/docs`. Keep README commands accurate. Update CHANGELOG for user-facing changes. +The homepage (`apps/docs/index.md` plus `.vitepress/theme`) is hand-crafted. `scripts/write-docs.mjs` must not write `index.md`. After regenerating inner pages, run `DOCS_BASE=/stackglass/ npm run docs:build`. + +The Cursor plugin listing to link from README and the site is https://cursor.directory/plugins/stackglass. + ## Pull requests Use the pull request template. Small, focused changes. Do not commit `.env`, credentials, or `.stackglass/local.json`. ## Release process +Follow [docs/RELEASE.md](docs/RELEASE.md). Short version: + 1. `npm test` and `npm run build` -2. `npx glass release` against this repository (dogfood) -3. Update CHANGELOG -4. Tag `vX.Y.Z` and push the tag +2. `node cli/dist/bin.js release` against this repository (dogfood). Never `npx glass` from npm. +3. Update CHANGELOG and `docs/RELEASE.md` if artifact usage changed +4. Tag `vX.Y.Z` and push the tag. `master` is protected: require a pull request, no force-push. 5. GitHub Actions `release.yml` attaches `stackglass-cli.zip`, `stackglass-mcp.zip`, `stackglass-cursor-plugin.zip`, and `checksums.txt`. `docs.yml` deploys GitHub Pages. +6. Expand the published release body so it matches `docs/RELEASE.md` (`gh release edit vX.Y.Z --notes-file docs/RELEASE.md`). The Cursor plugin files belong at the repository root. Do not add `.cursor-plugin/marketplace.json` unless this repo becomes a multi-plugin marketplace. diff --git a/README.md b/README.md index 6532826..0362a10 100644 --- a/README.md +++ b/README.md @@ -6,14 +6,23 @@

See what your project is actually doing.

-

Developer observability and verification for Cursor.

+

Local-first observability and verification for Cursor. Not another coding assistant.

+ +

+ Install Cursor plugin +

+ +

+ Install the Cursor plugin: + https://cursor.directory/plugins/stackglass +

CI - Release + Release License Tests - MCP + MCP Documentation

@@ -21,11 +30,18 @@ Stackglass is the **observability and verification layer for AI-assisted develop Cursor writes and reasons about code. Stackglass gives that agent evidence about state, tests, failures, history, configuration, contracts, and documentation — so it does not have to guess. -It is not another coding assistant. +It is not another coding assistant. It is not an npm package. It does not upload your source. It exposes **exactly 22 MCP tools** and will not invent a 23rd. -## What is Stackglass? +| Start here | URL | +| --------------------- | ------------------------------------------------------------- | +| **Cursor plugin** | https://cursor.directory/plugins/stackglass | +| Documentation | https://theworker02.github.io/stackglass/ | +| GitHub Release v1.1.0 | https://github.com/theworker02/stackglass/releases/tag/v1.1.0 | +| Source | https://github.com/theworker02/stackglass | -A local-first developer platform: +## What Stackglass is + +A local-first developer platform that lives in the workspace: ```text Developer flight recorder @@ -33,13 +49,12 @@ Developer flight recorder + Change inspector + Debugging assistant + Project status console -+ MCP server -+ Cursor agent toolkit ++ MCP server (22 tools) ++ Cursor agent toolkit (rules, skills, agents, commands, hooks) + GlassLens (narrative, session, heat, clusters) ++ Local dashboard (glass dashboard on 127.0.0.1) ``` -## Why Stackglass? - Agents constantly struggle with questions like: what changed, what is broken, why, which tests matter, whether a failure is new, whether coverage regressed, and whether the README still describes reality. Stackglass connects those events. Example: @@ -52,61 +67,47 @@ Ask Cursor _what happened?_ and Stackglass answers with evidence. `glass why` turns the same evidence into a narrative. `glass session` replays the timeline. `glass heat` shows which files are actually noisy. Failure clusters group related failures so you do not fix them one-by-one. -## Features +## What Stackglass is not -- **GlassCore** workspace runtime, config, process execution, permissions, logging -- **GlassIndex** files, packages, tests, imports, public exports -- **GlassTrace** development timeline -- **GlassWatch** classified file events; optional `watch.autoRun` related tests -- **GlassLab** discovery, plans, runs, flakes, coverage, mutation, contracts -- **GlassLens** narrative, session replay, heat, clusters, snapshot compare, suspicious commits -- **22 MCP tools** plus resources and prompts (new capability is optional args, never a 23rd tool) -- **CLI** `glass` / `stackglass` -- **Cursor plugin** rules, skills, agents, commands, hooks -- **Local dashboard** `glass dashboard` with live Why / Session / Heat / Clusters views +- **Not a coding assistant.** Cursor already writes and edits code. Stackglass observes and verifies. +- **Not an npm package.** There is no `bin` field, no `npm link`, and no `npm publish`. Install from this repository or from a GitHub Release zip. +- **Not a 23rd MCP tool.** New capability is an optional argument or a resource, never another tool name. +- **Not a cloud.** Core functionality does not require an account. Source is not uploaded to a Stackglass service. +- **Not a publisher.** `glass release` / `release_readiness` reports readiness and never ships a release. -## GlassLab +## Install the Cursor plugin -GlassLab is not `npm test` with a coat of paint. It discovers frameworks, selects related tests with reasons, parses failures, stores history, and will not invent coverage. +The fastest way to use Stackglass inside Cursor is the plugin listing: -Repeat a run with `glass test repeat 5` to probe flakes. A mixed pass/fail across repeats is a candidate flake. A single failure is never labeled a flake. +**https://cursor.directory/plugins/stackglass** -Dogfood: this repository runs its own tests through the same adapters and CLI. +That page is the install CTA for this repository. After the plugin is available in Cursor: -## 22 MCP Tools +1. Confirm MCP server `stackglass` is listed. It runs `node scripts/stackglass-mcp.mjs` from the plugin root and sets `STACKGLASS_ROOT` to the current workspace. +2. In the project you want to observe, run the CLI init (from a clone or a release zip — see below). +3. Ask Cursor to inspect project state, related tests, or a failure. The agent should call Stackglass tools before guessing. -Project intelligence: `project_snapshot`, `project_activity_timeline`, `code_context`, `dependency_trace`, `change_impact` +The plugin layout lives at the **repository root**, not in a nested marketplace package: -Version control: `git_change_summary`, `git_history_context` - -Runtime & debugging: `runtime_status`, `runtime_logs`, `error_analyze`, `error_trace` - -GlassLab: `test_discover`, `test_plan`, `test_run`, `test_failure_analyze`, `coverage_inspect`, `mutation_test`, `contract_verify` - -Integrity: `config_audit`, `env_usage`, `docs_check`, `release_readiness` - -Optional modes (same 22 tools): - -| Tool | Optional args | -| --------------------------- | ----------------- | -| `project_snapshot` | `narrative` | -| `project_activity_timeline` | `session` | -| `change_impact` | `heat` | -| `git_history_context` | `rank_suspicious` | -| `test_run` | `files`, `repeat` | -| `test_failure_analyze` | `cluster` | - -Resources (not tools): `stackglass://project`, `timeline`, `session`, `attention`, `clusters`, `heat`, `tests`, `failures`, `coverage`, `runtime`, `changes`, `configuration`, `release`. - -Full schemas: [MCP documentation](https://theworker02.github.io/stackglass/mcp/tools-reference). +```text +.cursor-plugin/plugin.json +mcp.json +rules/ +skills/ +agents/ +commands/ +hooks/ +scripts/stackglass-mcp.mjs +assets/logo.svg +``` -## Architecture +Cursor's plugin format does not provide a custom editor sidebar API. The UI is the local dashboard (`glass dashboard`) plus MCP resources. Do not add `.cursor-plugin/marketplace.json` unless this repository becomes a multi-plugin marketplace. -See [docs/architecture.md](docs/architecture.md). MCP, CLI, dashboard, and plugin share GlassCore. +You can also load this checkout as a local Open Plugin after `npm install` and `npm run build`. -## Installation +## Installation from source -Requires Node.js 22.13+. Stackglass is not an npm package. Download `stackglass-cli.zip` from [GitHub Releases](https://github.com/theworker02/stackglass/releases) or clone and build: +Requires **Node.js >= 22.13.0**. Stackglass is **not** published to the npm registry. Do not run `npm install -g stackglass`, `npm link`, or `npx stackglass`. ```bash git clone https://github.com/theworker02/stackglass.git @@ -116,107 +117,177 @@ npm run build node cli/dist/bin.js --help ``` -From another project, point at the extracted release or built checkout: +From another project, point at the built checkout: ```bash node /path/to/stackglass/cli/dist/bin.js init +node /path/to/stackglass/cli/dist/bin.js status +node /path/to/stackglass/cli/dist/bin.js why ``` -Docs: [theworker02.github.io/stackglass](https://theworker02.github.io/stackglass/) +There is no global `glass` binary from npm. After a local build you can call the same entry as: + +```bash +node cli/dist/bin.js +# or, from this repo's scripts: +node scripts/glass.mjs +``` -## Quick Start +If a `glass` or `stackglass` command is on your PATH, it must be something you created yourself (alias or wrapper). This project does not install one. + +Set `STACKGLASS_ROOT` when the process working directory is the Stackglass checkout but the workspace to observe is elsewhere: ```bash -cd your-project -glass init -glass status -glass why -glass test related -glass dashboard +# macOS / Linux +STACKGLASS_ROOT=/path/to/your/project node /path/to/stackglass/cli/dist/bin.js status + +# Windows PowerShell +$env:STACKGLASS_ROOT="C:\path\to\your\project" +node C:\path\to\stackglass\cli\dist\bin.js status ``` -## Cursor Setup +Docs: [theworker02.github.io/stackglass](https://theworker02.github.io/stackglass/) + +## GitHub Release artifacts (v1.1.0) -1. Clone this repository and run `npm install` then `npm run build` -2. `node /path/to/stackglass/cli/dist/bin.js init` in the project -3. Install this repository as a Cursor plugin (layout is at the repo root: `.cursor-plugin/plugin.json`, `mcp.json`, `rules/`, `skills/`, `agents/`, `commands/`, `hooks/`) -4. Confirm MCP server `stackglass` is available in Cursor (`node` runs `scripts/stackglass-mcp.mjs` from the plugin root; `STACKGLASS_ROOT` = workspace) +Every tagged release attaches four files. Current release: [v1.1.0](https://github.com/theworker02/stackglass/releases/tag/v1.1.0). -The plugin UI is the local dashboard (`glass dashboard`) plus MCP resources. Cursor's plugin format does not provide a custom editor sidebar API; Stackglass keeps the capability in CLI/MCP rather than inventing one. +| Artifact | What it is | How to use it | +| ------------------------------ | ---------------------------------------------- | --------------------------------------------------------------- | +| `stackglass-cli.zip` | Built CLI, MCP server, production dependencies | Extract, then `node cli/dist/bin.js help` | +| `stackglass-mcp.zip` | Same runtime as the CLI zip | `STACKGLASS_ROOT=/your/project node scripts/stackglass-mcp.mjs` | +| `stackglass-cursor-plugin.zip` | Cursor Open Plugins layout | Extract and add that folder as a Cursor plugin | +| `checksums.txt` | SHA-256 of the three zips | Verify before you trust an extracted tree | -## Testing +The CLI zip and MCP zip contain the same runnable tree. The split exists so release notes and download UIs can name the job you came for. The plugin zip is different: it is the Open Plugins layout, not a Node workspace you `npm install`. + +### Verify checksums ```bash -glass test related -glass test changed -glass test failed -glass test flakes -glass test repeat 5 -glass test mutation src/auth/token.ts -glass test coverage -glass test contracts +# download checksums.txt and the zips into the same directory +# Linux / macOS +sha256sum -c checksums.txt + +# Windows PowerShell +Get-FileHash .\stackglass-cli.zip -Algorithm SHA256 +Get-Content .\checksums.txt ``` -## Failure Investigation +Compare the computed hashes to the lines in `checksums.txt`. Do not run a zip whose hash does not match. -User: _Why did the authentication tests suddenly start failing?_ +### Use the CLI zip -Stackglass can provide the agent: +```bash +unzip stackglass-cli.zip -d stackglass +cd stackglass +node cli/dist/bin.js help +node scripts/glass.mjs init +``` -```text -current failures (new / recurring / regression / flake) -failure clusters -timeline + session replay -file heat -recent Git changes -suspicious commits ranked by overlapping files -related source -previous passing run -dependency relationships +If `node_modules` is missing after extract: + +```bash +npm install --omit=dev --ignore-scripts ``` -The agent forms a grounded diagnosis instead of editing at random. Newest commit is not assumed guilty. +That install is local to the extracted tree. It is not `npm publish` and it does not register a global binary. -## Timeline +### Use the MCP zip -```text -14:21:03 file.changed src/auth/token.ts -14:21:11 typecheck.failed -14:21:31 typecheck.passed -14:21:44 test.failed token expiration +```bash +unzip stackglass-mcp.zip -d stackglass +cd stackglass +STACKGLASS_ROOT=/path/to/your/project node scripts/stackglass-mcp.mjs ``` -`glass session` compresses that into beats. `glass heat` scores files by events, changes, and failures. +On Windows PowerShell: + +```powershell +$env:STACKGLASS_ROOT="C:\path\to\your\project" +node scripts\stackglass-mcp.mjs +``` + +The server speaks MCP over stdio. Cursor's `mcp.json` already does this when you install the plugin. + +### Use the Cursor plugin zip -## Runtime +1. Extract `stackglass-cursor-plugin.zip`. +2. In Cursor, add that extracted folder as a plugin (Open Plugins layout: `.cursor-plugin/plugin.json` at the folder root). +3. Confirm MCP server `stackglass` starts with `node scripts/stackglass-mcp.mjs`. +4. Still prefer the listing at **https://cursor.directory/plugins/stackglass** when you want the published plugin page rather than a manual folder. -`runtime_status` and `runtime_logs` cover processes launched or registered through Stackglass only. +Full artifact instructions: [docs/RELEASE.md](docs/RELEASE.md). -## Configuration +## Quick start -`glass config` audits package managers, CI Node versions, ports, and duplicated lockfiles. +```bash +cd your-project +node /path/to/stackglass/cli/dist/bin.js init +node /path/to/stackglass/cli/dist/bin.js status +node /path/to/stackglass/cli/dist/bin.js why +node /path/to/stackglass/cli/dist/bin.js test related +node /path/to/stackglass/cli/dist/bin.js dashboard +``` + +`init` is idempotent. It detects languages, packages, and test frameworks, creates `.stackglass/`, initializes the local database, and writes a first snapshot. -## Documentation Verification +## Cursor setup -If README says `pnpm dev:web` and that script is gone, `docs_check` reports a documentation mismatch. +1. Install the plugin from **https://cursor.directory/plugins/stackglass** (or extract `stackglass-cursor-plugin.zip` / load this repo root). +2. Clone this repository (or extract `stackglass-cli.zip`) and, for a source checkout, run `npm install` then `npm run build`. +3. In the project you want to observe: `node /path/to/stackglass/cli/dist/bin.js init`. +4. Confirm MCP server `stackglass` is available. The plugin `mcp.json` runs `node ${PLUGIN_ROOT}/scripts/stackglass-mcp.mjs` and sets `STACKGLASS_ROOT` to `${workspaceFolder}`. +5. Open the local dashboard when you want a UI: `node /path/to/stackglass/cli/dist/bin.js dashboard` (binds 127.0.0.1). -## Release Verification +The plugin ships: -`glass release` / `release_readiness` never publishes. Publishing requires deliberate user action. +- **22 MCP tools** plus resources and prompts +- **Rules** in `rules/` (observe-before-changing, test integrity, no blind snapshot updates, environment safety, release safety) +- **Skills** in `skills/` (Failure Investigator, Regression Hunter, Test Architect, Flake Hunter, Coverage Analyst, Contract Guardian, Runtime Investigator, Configuration Auditor, Documentation Verifier, Release Inspector) +- **Agents** and **commands** for investigate / verify / release flows +- **Hooks** including session start -## CLI +If MCP does not appear, check that Node 22.13+ is on PATH, that `scripts/stackglass-mcp.mjs` exists in the plugin root, and that `STACKGLASS_ROOT` points at the user workspace rather than the Stackglass checkout. + +## CLI catalog + +Entry point: `node cli/dist/bin.js` (or `node scripts/glass.mjs` from a release zip). If you have a local alias named `glass` or `stackglass`, the commands are the same. ```text -glass init | status | why | session | heat | clusters | compare | attention -glass doctor | snapshot | timeline | watch -glass test | test related | test changed | test failed | test history -glass test flakes | test repeat | test mutation | test coverage | test contracts -glass error | runtime | changes | config | env | docs | release -glass mcp | adapters | logs | cache | dashboard +glass init Initialize .stackglass/ in this workspace +glass status Show current project state +glass why Narrative of current state from evidence +glass session Replay recent timeline as a session +glass heat Rank files by events, changes, and failures +glass clusters Group stored failures by shared files +glass compare Diff the two most recent snapshots +glass attention Tests, docs, config, and flake attention items +glass doctor [bundle] Diagnostics; bundle writes a sanitized archive +glass snapshot Write a project snapshot +glass timeline Show recent development events +glass watch Smart watch; optional autoRun of related tests +glass test [mode] related | changed | failed | workspace +glass test history Last stored test run +glass test flakes Flake candidates (never from a single failure) +glass test repeat [n] Repeat a run to probe flakes +glass test mutation Isolated mutation testing +glass test coverage Coverage if a provider produced it +glass test contracts Observable contract verification +glass error [text] Analyze an error from stdin or an argument +glass runtime Stackglass-managed processes only +glass changes Git change summary +glass config Configuration audit +glass env Environment variable names only +glass docs Documentation checker +glass release Release readiness (never publishes) +glass mcp Start the MCP server on stdio +glass adapters List detected test adapters +glass logs Show the Stackglass log file path +glass cache Manage local cache (clear) +glass dashboard Serve the local dashboard on 127.0.0.1 +glass help Show help ``` -If `glass` is unavailable, use `stackglass`. - ### Sample `glass status` (documentation only) The following is a **documentation sample**, not live output from this repository: @@ -233,28 +304,197 @@ Attention 3 item(s) MCP local ``` -Your actual `glass status` prints values from the current workspace. Unavailable fields say `no_data` / `unavailable` / `not_configured`. +Your actual `glass status` prints values from the current workspace. Unavailable fields say `no_data` / `unavailable` / `not_configured`. Stackglass will not invent coverage percentages or test counts. + +## 22 MCP tools + +The public MCP surface is **exactly 22 tools**. Resources and prompts are not tools. New intelligence lands as optional arguments on these names. -## Rules +### Project intelligence -Fifteen Cursor rules ship in `rules/`, including observe-before-changing, test integrity, no blind snapshot updates, environment safety, and release safety. +| Tool | Purpose | +| --------------------------- | ------------------------------------------------------------- | +| `project_snapshot` | Current observable project state. Optional `narrative`. | +| `project_activity_timeline` | Flight-recorder events. Optional `session`. | +| `code_context` | Source excerpt, symbols, related tests. | +| `dependency_trace` | Imports and dependents. | +| `change_impact` | Affected files, tests, public surface, risk. Optional `heat`. | -## Skills +### Version control -Failure Investigator, Regression Hunter, Test Architect, Flake Hunter, Coverage Analyst, Contract Guardian, Runtime Investigator, Configuration Auditor, Documentation Verifier, Release Inspector. +| Tool | Purpose | +| --------------------- | ------------------------------------------------------ | +| `git_change_summary` | Structured working-tree diff. | +| `git_history_context` | Recent commits for a path. Optional `rank_suspicious`. | -## Adapters +### Runtime and debugging -`defineTestAdapter` in `@stackglass/core`. Built-in: Vitest, Jest, Node Test Runner, Playwright, Cypress, pytest, unittest, cargo test, go test, .NET test, JUnit. +| Tool | Purpose | +| ---------------- | --------------------------------------------------------- | +| `runtime_status` | Processes launched or registered through Stackglass only. | +| `runtime_logs` | Sanitized logs. Never secret values. | +| `error_analyze` | Parse compiler, test, or runtime errors. | +| `error_trace` | Connect an error to source, git, tests, and history. | + +### GlassLab + +| Tool | Purpose | +| ---------------------- | -------------------------------------------------------------------------- | +| `test_discover` | Frameworks, files, and cases. A framework is available only with evidence. | +| `test_plan` | Smallest useful verification plan, with a reason per item. | +| `test_run` | Execute a plan or mode. Optional `files`, `repeat`. | +| `test_failure_analyze` | Expected/actual, history, correlated failures. Optional `cluster`. | +| `coverage_inspect` | Coverage if a provider produced an artifact. Otherwise `no_data`. | +| `mutation_test` | Isolated workspace mutants. The working tree is not permanently changed. | +| `contract_verify` | Contracts and breaking JSON compare. | + +### Integrity + +| Tool | Purpose | +| ------------------- | ----------------------------------------------------------------------- | +| `config_audit` | Config drift, package managers, CI Node versions, duplicated lockfiles. | +| `env_usage` | Environment variable **names and locations only**. Never values. | +| `docs_check` | README commands and file references versus the index. | +| `release_readiness` | Release report. **Never publishes.** | + +Optional modes (same 22 tools): + +| Tool | Optional args | +| --------------------------- | ----------------- | +| `project_snapshot` | `narrative` | +| `project_activity_timeline` | `session` | +| `change_impact` | `heat` | +| `git_history_context` | `rank_suspicious` | +| `test_run` | `files`, `repeat` | +| `test_failure_analyze` | `cluster` | + +Resources (not tools): `stackglass://project`, `timeline`, `session`, `attention`, `clusters`, `heat`, `tests`, `failures`, `coverage`, `runtime`, `changes`, `configuration`, `release`. + +Start the server from a built checkout or release zip: + +```bash +node scripts/stackglass-mcp.mjs +# or +node servers/mcp/dist/bin.js +# or +node cli/dist/bin.js mcp +``` + +Full schemas: [MCP documentation](https://theworker02.github.io/stackglass/mcp/tools-reference). + +## GlassLab + +GlassLab is not `npm test` with a coat of paint. It discovers frameworks, selects related tests with reasons, parses failures, stores history, and will not invent coverage. + +```bash +node cli/dist/bin.js test related +node cli/dist/bin.js test changed +node cli/dist/bin.js test failed +node cli/dist/bin.js test flakes +node cli/dist/bin.js test repeat 5 +node cli/dist/bin.js test mutation src/auth/token.ts +node cli/dist/bin.js test coverage +node cli/dist/bin.js test contracts +``` + +Repeat a run with `test repeat 5` to probe flakes. A mixed pass/fail across repeats is a candidate flake. A single failure is never labeled a flake. + +Built-in adapters: Vitest, Jest, Node Test Runner, Playwright, Cypress, pytest, unittest, cargo test, go test, .NET test, JUnit. Extend with `defineTestAdapter` in `@stackglass/core` (workspace package name only — not on the npm registry). + +Dogfood: this repository runs its own tests through the same adapters and CLI. + +## GlassLens + +GlassLens turns stored evidence into something an agent (or a human) can read: + +- `why` — narrative of current state; unanswered items stay unanswered +- `session` — compressed timeline beats +- `heat` — files scored by events, changes, and failures +- `clusters` — failures grouped by shared files +- `compare` — diff of the two most recent snapshots +- Suspicious-commit ranking that does **not** assume the newest commit is guilty + +## Local dashboard + +`node cli/dist/bin.js dashboard` serves a live UI on 127.0.0.1 with Why, Session, Heat, Clusters, GlassLab, failures, coverage, runtime, configuration, documentation, and release views. It reads the same GlassCore data as the CLI and MCP server. + +## Failure investigation + +User: _Why did the authentication tests suddenly start failing?_ + +Stackglass can provide the agent: + +```text +current failures (new / recurring / regression / flake) +failure clusters +timeline + session replay +file heat +recent Git changes +suspicious commits ranked by overlapping files +related source +previous passing run +dependency relationships +``` + +The agent forms a grounded diagnosis instead of editing at random. + +```text +14:21:03 file.changed src/auth/token.ts +14:21:11 typecheck.failed +14:21:31 typecheck.passed +14:21:44 test.failed token expiration +``` + +`glass session` compresses that into beats. `glass heat` scores files by events, changes, and failures. ## Privacy Local-first. No account for core functionality. Source is not uploaded to a Stackglass service. Telemetry is off by default. +Generated data lives in `.stackglass/` and is rebuildable. Human configuration is `config.json`. Machine-local files (`local.json`, cache, sqlite) are gitignored. + ## Security See [SECURITY.md](SECURITY.md). Secrets are redacted from MCP, logs, timeline metadata, and doctor bundles. +- Do not ask Stackglass for `.env` contents. It will not return secret values. +- `env_usage` reports names and locations only. +- Sensitive path patterns include `.env`, `*.pem`, `*.key`, `credentials*`, `secrets*`, and `id_rsa*`. +- `glass doctor bundle` excludes source code and secret values by default. +- Mutation testing copies the project into a temporary workspace and deletes it afterward. + +## Architecture + +See [docs/architecture.md](docs/architecture.md). MCP, CLI, dashboard, and plugin share GlassCore. They do not maintain a second model of the project. + +```text +Cursor + → Plugin (MCP + rules + skills + commands + hooks) + → GlassCore (Index / Trace / Watch / Lens / Lab) + → Adapters (tests, build, runtime, errors) + → Repository / processes +``` + +Internal package names (`@stackglass/core`, and so on) exist so this checkout can build. They are not npm packages. + +## Troubleshooting + +Run `node cli/dist/bin.js doctor` in the **user workspace**, not only in the Stackglass checkout. + +| Symptom | Likely cause | What to do | +| ----------------------------------- | ----------------------------- | ------------------------------------------------------------------------- | +| `database not initialized` | No `.stackglass/` yet | `node …/cli/dist/bin.js init` | +| Coverage `no_data` | No provider artifact | Run the framework's coverage reporter first | +| Tests `unavailable` | No adapter evidence | Confirm a known framework config or manifest exists | +| Git `unavailable` | Directory is not a repository | Run inside a git checkout | +| MCP missing in Cursor | Plugin path or Node version | Reinstall from https://cursor.directory/plugins/stackglass; Node >= 22.13 | +| MCP observes the wrong tree | `STACKGLASS_ROOT` unset | Point it at the user workspace | +| `glass` not found | Not an npm binary | Use `node cli/dist/bin.js` | +| Doctor looks at the Stackglass repo | Wrong cwd | Run doctor from the project you care about | +| Secrets in output | Should not happen | File a private advisory; do not paste secrets into issues | + +More: [docs site troubleshooting](https://theworker02.github.io/stackglass/reference/troubleshooting) and [docs/RELEASE.md](docs/RELEASE.md). + ## Development ```bash @@ -262,15 +502,20 @@ npm install npm run typecheck npm test npm run build +npm run docs:build ``` +Docs site is VitePress in `apps/docs`. GitHub Pages publishes to https://theworker02.github.io/stackglass/ with `DOCS_BASE=/stackglass/`. + +The landing page (`apps/docs/index.md` plus `.vitepress/theme`) is hand-crafted. `scripts/write-docs.mjs` must not overwrite `index.md`. + ## Roadmap -See [ROADMAP.md](ROADMAP.md). +See [ROADMAP.md](ROADMAP.md). Later work deepens adapters and coverage providers rather than adding unbounded MCP tools. ## Contributing -See [CONTRIBUTING.md](CONTRIBUTING.md) and [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md). +See [CONTRIBUTING.md](CONTRIBUTING.md), [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md), and [docs/RELEASE.md](docs/RELEASE.md). ## License diff --git a/apps/docs/.vitepress/config.ts b/apps/docs/.vitepress/config.ts index ee52b86..0f21d21 100644 --- a/apps/docs/.vitepress/config.ts +++ b/apps/docs/.vitepress/config.ts @@ -5,7 +5,8 @@ const site = "https://theworker02.github.io/stackglass/"; export default defineConfig({ title: "Stackglass", - description: "See what your project is actually doing.", + description: + "Local-first observability and verification for Cursor. Evidence for agents — not another coding assistant.", base, lang: "en-US", lastUpdated: true, @@ -18,7 +19,8 @@ export default defineConfig({ "meta", { property: "og:description", - content: "See what your project is actually doing.", + content: + "Local-first observability and verification for Cursor. Evidence for agents — not another coding assistant.", }, ], ["meta", { property: "og:image", content: `${site}og.svg` }], @@ -32,6 +34,7 @@ export default defineConfig({ { text: "GlassLab", link: "/glasslab/overview" }, { text: "MCP", link: "/mcp/setup" }, { text: "CLI", link: "/reference/cli" }, + { text: "Plugin", link: "https://cursor.directory/plugins/stackglass" }, { text: "GitHub", link: "https://github.com/theworker02/stackglass" }, ], search: { provider: "local" }, @@ -114,8 +117,9 @@ export default defineConfig({ ], socialLinks: [{ icon: "github", link: "https://github.com/theworker02/stackglass" }], footer: { - message: "Local-first developer observability. Distributed from GitHub, not npm.", - copyright: "MIT License", + message: + 'Local-first developer observability. Distributed from GitHub, not npm. Install the Cursor plugin.', + copyright: "MIT License · Stackglass 1.1.0", }, }, }); diff --git a/apps/docs/.vitepress/theme/HomeLanding.vue b/apps/docs/.vitepress/theme/HomeLanding.vue new file mode 100644 index 0000000..0c3d2a0 --- /dev/null +++ b/apps/docs/.vitepress/theme/HomeLanding.vue @@ -0,0 +1,247 @@ + + + diff --git a/apps/docs/.vitepress/theme/custom.css b/apps/docs/.vitepress/theme/custom.css new file mode 100644 index 0000000..e50f9e7 --- /dev/null +++ b/apps/docs/.vitepress/theme/custom.css @@ -0,0 +1,437 @@ +:root { + --sg-bg: #090b0e; + --sg-surface: #12161b; + --sg-elevated: #191e25; + --sg-primary: #61d6c5; + --sg-accent: #93f1e4; + --sg-blue: #72a7ff; + --sg-text: #f3f6f8; + --sg-muted: #8c98a5; + --sg-line: #1f2630; + --sg-fail: #ef6262; + --sg-warn: #e7b14c; + --sg-ok: #57c785; + --vp-c-brand-1: #61d6c5; + --vp-c-brand-2: #7ee4d4; + --vp-c-brand-3: #3aa89a; + --vp-c-brand-soft: rgba(97, 214, 197, 0.16); + --vp-c-bg: #090b0e; + --vp-c-bg-alt: #0c1014; + --vp-c-bg-elv: #12161b; + --vp-c-bg-soft: #12161b; + --vp-c-gutter: #090b0e; + --vp-c-text-1: #f3f6f8; + --vp-c-text-2: #c5ced6; + --vp-c-text-3: #8c98a5; + --vp-c-divider: #1f2630; + --vp-c-border: #243040; + --vp-c-tip-1: #61d6c5; + --vp-c-tip-soft: rgba(97, 214, 197, 0.12); + --vp-home-hero-name-color: transparent; + --vp-home-hero-name-background: linear-gradient(120deg, #93f1e4 0%, #61d6c5 42%, #72a7ff 100%); + --vp-button-brand-bg: #61d6c5; + --vp-button-brand-hover-bg: #93f1e4; + --vp-button-brand-active-bg: #4ec4b3; + --vp-button-brand-text: #090b0e; + --vp-button-brand-hover-text: #090b0e; + --vp-button-alt-bg: transparent; + --vp-button-alt-text: #f3f6f8; + --vp-button-alt-border: #2a3644; + --vp-button-alt-hover-bg: rgba(97, 214, 197, 0.08); + --vp-button-alt-hover-border: #61d6c5; + --vp-button-alt-hover-text: #93f1e4; + --vp-nav-bg-color: rgba(9, 11, 14, 0.78); + --vp-sidebar-bg-color: #0c1014; + --vp-code-block-bg: #10151b; + --vp-font-family-base: + "Segoe UI Variable", "Segoe UI", "SF Pro Display", "Inter", system-ui, sans-serif; + --vp-font-family-mono: + "Cascadia Code", "SF Mono", ui-monospace, SFMono-Regular, Menlo, Consolas, monospace; +} + +html, +.dark { + color-scheme: dark; +} + +.VPNavBar { + border-bottom-color: rgba(97, 214, 197, 0.12) !important; + backdrop-filter: blur(18px); +} + +.VPNavBarTitle .title { + letter-spacing: 0.16em; + font-weight: 650; + font-size: 13px; +} + +.VPNavBarMenuLink[href*="cursor.directory"] { + color: var(--sg-primary) !important; + font-weight: 650; +} + +.VPHero { + position: relative; + isolation: isolate; + padding-top: 48px !important; +} + +.VPHero::before { + content: ""; + position: absolute; + inset: -12% -8% auto; + height: 520px; + background: + radial-gradient(ellipse at 22% 20%, rgba(97, 214, 197, 0.22), transparent 42%), + radial-gradient(ellipse at 78% 8%, rgba(114, 167, 255, 0.18), transparent 38%), + radial-gradient(ellipse at 60% 70%, rgba(147, 241, 228, 0.08), transparent 46%); + pointer-events: none; + z-index: -1; +} + +.VPHero::after { + content: ""; + position: absolute; + inset: 0; + background-image: + linear-gradient(rgba(147, 241, 228, 0.035) 1px, transparent 1px), + linear-gradient(90deg, rgba(147, 241, 228, 0.035) 1px, transparent 1px); + background-size: 48px 48px; + mask-image: radial-gradient(ellipse at 50% 30%, #000 20%, transparent 72%); + pointer-events: none; + z-index: -1; +} + +.VPHero .name { + letter-spacing: 0.18em; + font-size: clamp(2.4rem, 6vw, 4.4rem) !important; + font-weight: 750 !important; + line-height: 1.05 !important; +} + +.VPHero .text { + max-width: 16ch; + font-size: clamp(1.6rem, 3.4vw, 2.5rem) !important; + line-height: 1.15 !important; + letter-spacing: -0.03em; +} + +.VPHero .tagline { + max-width: 42rem; + font-size: 1.05rem !important; + color: var(--sg-muted) !important; +} + +.VPHero .actions { + padding-top: 12px; +} + +.VPButton.brand { + box-shadow: + 0 0 0 1px rgba(147, 241, 228, 0.25), + 0 10px 40px rgba(97, 214, 197, 0.18); +} + +.VPHero .image-bg { + display: none; +} + +.VPHero .image-src { + filter: drop-shadow(0 18px 40px rgba(97, 214, 197, 0.28)); + animation: sg-float 7s ease-in-out infinite; +} + +.VPHero .image-container { + position: relative; +} + +.VPHero .image-container::before, +.VPHero .image-container::after { + content: ""; + position: absolute; + width: 58%; + height: 42%; + border-radius: 22px; + border: 1px solid rgba(147, 241, 228, 0.22); + background: linear-gradient(160deg, rgba(156, 196, 255, 0.16), rgba(97, 214, 197, 0.05)); + backdrop-filter: blur(10px); + z-index: -1; +} + +.VPHero .image-container::before { + top: 8%; + left: 18%; + transform: rotate(-9deg); +} + +.VPHero .image-container::after { + bottom: 10%; + left: 24%; + transform: rotate(9deg); + background: linear-gradient(160deg, rgba(231, 255, 249, 0.12), rgba(97, 214, 197, 0.04)); +} + +.VPFeatures { + position: relative; +} + +.VPFeature { + border-color: rgba(97, 214, 197, 0.14) !important; + background: linear-gradient(180deg, rgba(25, 30, 37, 0.92), rgba(18, 22, 27, 0.88)) !important; + box-shadow: inset 0 1px 0 rgba(147, 241, 228, 0.08); +} + +.VPFeature .title { + letter-spacing: 0.02em; +} + +.VPSidebar { + border-right-color: var(--sg-line) !important; +} + +.VPDoc .content-container { + max-width: 52rem; +} + +.VPDoc h1, +.VPDoc h2 { + letter-spacing: -0.02em; +} + +.VPFooter { + border-top-color: var(--sg-line) !important; +} + +.sg-landing { + position: relative; + margin: 0 auto; + max-width: 1120px; + padding: 24px 24px 96px; +} + +.sg-landing section { + margin-top: 72px; +} + +.sg-kicker { + display: inline-block; + margin-bottom: 10px; + color: var(--sg-primary); + font-size: 12px; + font-weight: 650; + letter-spacing: 0.18em; + text-transform: uppercase; +} + +.sg-landing h2 { + margin: 0 0 12px; + font-size: clamp(1.7rem, 3vw, 2.2rem); + letter-spacing: -0.03em; + line-height: 1.15; +} + +.sg-landing p.lead { + max-width: 46rem; + color: var(--sg-muted); + font-size: 1.05rem; +} + +.sg-split { + display: grid; + grid-template-columns: 1fr 1fr; + gap: 18px; +} + +.sg-card { + position: relative; + overflow: hidden; + padding: 22px 22px 20px; + border: 1px solid rgba(97, 214, 197, 0.14); + border-radius: 18px; + background: + linear-gradient(180deg, rgba(25, 30, 37, 0.88), rgba(12, 16, 20, 0.92)), + linear-gradient(140deg, rgba(97, 214, 197, 0.07), transparent 46%); + box-shadow: inset 0 1px 0 rgba(147, 241, 228, 0.08); +} + +.sg-card::before { + content: ""; + position: absolute; + top: 0; + left: 16px; + right: 16px; + height: 1px; + background: linear-gradient(90deg, transparent, rgba(147, 241, 228, 0.45), transparent); +} + +.sg-card h3 { + margin: 0 0 10px; + font-size: 1.05rem; +} + +.sg-card ul { + margin: 0; + padding-left: 1.1rem; + color: var(--vp-c-text-2); +} + +.sg-card li + li { + margin-top: 6px; +} + +.sg-card.is-not { + border-color: rgba(231, 177, 76, 0.18); +} + +.sg-card.is-not h3 { + color: var(--sg-warn); +} + +.sg-tools { + display: grid; + grid-template-columns: repeat(4, minmax(0, 1fr)); + gap: 14px; +} + +.sg-tool-group h3 { + margin: 0 0 10px; + color: var(--sg-accent); + font-size: 13px; + letter-spacing: 0.08em; + text-transform: uppercase; +} + +.sg-tool-group ul { + margin: 0; + padding: 0; + list-style: none; +} + +.sg-tool-group li { + display: flex; + flex-direction: column; + gap: 2px; + padding: 8px 0; + border-bottom: 1px solid rgba(255, 255, 255, 0.04); + color: var(--vp-c-text-2); + font-size: 0.92rem; +} + +.sg-tool-group code { + color: var(--sg-text); + font-size: 0.86rem; +} + +.sg-panes { + display: grid; + grid-template-columns: repeat(3, minmax(0, 1fr)); + gap: 16px; +} + +.sg-pane { + min-height: 180px; +} + +.sg-pane .sg-kicker { + margin-bottom: 8px; +} + +.sg-install { + display: grid; + grid-template-columns: 1.1fr 0.9fr; + gap: 18px; +} + +.sg-install pre { + margin: 14px 0 0; + padding: 14px 16px; + overflow: auto; + border: 1px solid var(--sg-line); + border-radius: 12px; + background: #0b0f13; + color: var(--sg-accent); + font-size: 0.86rem; +} + +.sg-cta { + display: flex; + flex-wrap: wrap; + gap: 10px; + margin-top: 18px; +} + +.sg-btn { + display: inline-flex; + align-items: center; + justify-content: center; + min-height: 40px; + padding: 0 16px; + border-radius: 10px; + border: 1px solid transparent; + font-size: 14px; + font-weight: 650; + text-decoration: none; + transition: + background 0.15s ease, + border-color 0.15s ease, + color 0.15s ease; +} + +.sg-btn.primary { + background: var(--sg-primary); + color: #090b0e; + box-shadow: 0 10px 30px rgba(97, 214, 197, 0.16); +} + +.sg-btn.primary:hover { + background: var(--sg-accent); +} + +.sg-btn.ghost { + border-color: #2a3644; + color: var(--sg-text); +} + +.sg-btn.ghost:hover { + border-color: var(--sg-primary); + color: var(--sg-accent); +} + +.sg-band { + margin-top: 80px; + padding: 36px; + border: 1px solid rgba(97, 214, 197, 0.2); + border-radius: 24px; + background: + radial-gradient(ellipse at 10% 0%, rgba(97, 214, 197, 0.16), transparent 46%), + radial-gradient(ellipse at 90% 100%, rgba(114, 167, 255, 0.12), transparent 42%), #10151b; +} + +.sg-band h2 { + max-width: 18ch; +} + +@media (max-width: 960px) { + .sg-split, + .sg-tools, + .sg-panes, + .sg-install { + grid-template-columns: 1fr; + } +} + +@media (prefers-reduced-motion: reduce) { + .VPHero .image-src { + animation: none; + } +} + +@keyframes sg-float { + 0%, + 100% { + transform: translateY(0); + } + 50% { + transform: translateY(-8px); + } +} diff --git a/apps/docs/.vitepress/theme/index.ts b/apps/docs/.vitepress/theme/index.ts new file mode 100644 index 0000000..8c5bd2a --- /dev/null +++ b/apps/docs/.vitepress/theme/index.ts @@ -0,0 +1,13 @@ +import DefaultTheme from "vitepress/theme"; +import type { Theme } from "vitepress"; +import { h } from "vue"; +import HomeLanding from "./HomeLanding.vue"; +import "./custom.css"; + +export default { + extends: DefaultTheme, + Layout: () => + h(DefaultTheme.Layout, null, { + "home-features-after": () => h(HomeLanding), + }), +} satisfies Theme; diff --git a/apps/docs/getting-started/cursor-setup.md b/apps/docs/getting-started/cursor-setup.md index e29bdf2..756b376 100644 --- a/apps/docs/getting-started/cursor-setup.md +++ b/apps/docs/getting-started/cursor-setup.md @@ -1,12 +1,33 @@ # Cursor Setup -Stackglass integrates with Cursor through the official plugin format: +Install the plugin from [https://cursor.directory/plugins/stackglass](https://cursor.directory/plugins/stackglass). -- MCP server `stackglass-mcp` (22 tools, resources, prompts) +Stackglass integrates with Cursor through the official Open Plugins layout at the **repository root**: + +- MCP server `stackglass` — `node scripts/stackglass-mcp.mjs`, 22 tools, resources, prompts - Rules in `rules/` - Skills in `skills/` -- Commands and agents in the plugin package +- Agents in `agents/` +- Commands in `commands/` +- Hooks in `hooks/` +- `mcp.json` sets `STACKGLASS_ROOT` to the current workspace + +```text +.cursor-plugin/plugin.json +mcp.json +rules/ +skills/ +agents/ +commands/ +hooks/ +scripts/stackglass-mcp.mjs +``` + +After the plugin is available: -The plugin lives at the repository root (`.cursor-plugin/plugin.json`, `mcp.json`, `rules/`, `skills/`, `agents/`, `commands/`, `hooks/`). Install it from this repo in Cursor, then run `glass init` in the project so the agent has a database and index. +1. Clone this repository (or extract `stackglass-cli.zip`) and, for a source checkout, run `npm install` then `npm run build`. +2. In the project you want to observe: `node /path/to/stackglass/cli/dist/bin.js init`. +3. Confirm MCP server `stackglass` is listed in Cursor. +4. Open the UI with `node /path/to/stackglass/cli/dist/bin.js dashboard` (127.0.0.1). -The dashboard is `glass dashboard` (127.0.0.1). Cursor plugins do not expose a custom sidebar API; the local dashboard and MCP resources provide the UI and evidence surface. +Cursor plugins do not expose a custom sidebar API. The local dashboard and MCP resources are the evidence surface. Do not add `.cursor-plugin/marketplace.json` unless this repository becomes a multi-plugin marketplace. diff --git a/apps/docs/getting-started/installation.md b/apps/docs/getting-started/installation.md index a36c21d..7005040 100644 --- a/apps/docs/getting-started/installation.md +++ b/apps/docs/getting-started/installation.md @@ -1,6 +1,14 @@ # Installation -Requires Node.js 22.13 or later. Stackglass is not an npm package. +Requires **Node.js 22.13** or later. Stackglass is **not** an npm package. Do not `npm install -g stackglass`, `npm link`, or `npx stackglass`. + +## Cursor plugin + +Install from [https://cursor.directory/plugins/stackglass](https://cursor.directory/plugins/stackglass). + +That listing is the install CTA for the repository. You can also extract `stackglass-cursor-plugin.zip` from [GitHub Release v1.1.0](https://github.com/theworker02/stackglass/releases/tag/v1.1.0) and add the folder as an Open Plugin. + +## Clone and build ```bash git clone https://github.com/theworker02/stackglass.git @@ -11,3 +19,18 @@ node cli/dist/bin.js --help ``` From another project: `node /path/to/stackglass/cli/dist/bin.js init`. + +There is no global `glass` binary from npm. Use `node cli/dist/bin.js` or `node scripts/glass.mjs`. + +## Release zips + +Download from [v1.1.0](https://github.com/theworker02/stackglass/releases/tag/v1.1.0): + +- `stackglass-cli.zip` — `node cli/dist/bin.js help` +- `stackglass-mcp.zip` — `STACKGLASS_ROOT=/your/project node scripts/stackglass-mcp.mjs` +- `stackglass-cursor-plugin.zip` — Cursor Open Plugins layout +- `checksums.txt` — SHA-256 of the zips + +Verify hashes before you run an extracted tree. Full artifact instructions: [docs/RELEASE.md](https://github.com/theworker02/stackglass/blob/master/docs/RELEASE.md). + +`STACKGLASS_ROOT` is the workspace to observe. If you launch the CLI or MCP from the Stackglass checkout, set it to the user project. diff --git a/apps/docs/getting-started/introduction.md b/apps/docs/getting-started/introduction.md index 233142f..530235b 100644 --- a/apps/docs/getting-started/introduction.md +++ b/apps/docs/getting-started/introduction.md @@ -5,3 +5,15 @@ Stackglass is a local-first developer observability and verification platform fo It is **not** an AI that writes code. Cursor already provides the coding agent. Stackglass gives that agent evidence about project state, tests, failures, history, configuration, contracts, and documentation. The defining principle: **give coding agents evidence instead of forcing them to guess.** + +Install the Cursor plugin: [https://cursor.directory/plugins/stackglass](https://cursor.directory/plugins/stackglass) + +## What it is + +A flight recorder, testing laboratory (GlassLab), change inspector, MCP server with **exactly 22 tools**, Cursor plugin, GlassLens, and a local dashboard. Version **1.1.0**. + +## What it is not + +Not a coding assistant. Not an npm package (`bin`, `npm link`, and `npm publish` are not part of this project). Not a 23rd MCP tool. Not a cloud that uploads source. `release_readiness` never publishes. + +Missing data is reported as `no_data`, `unavailable`, or `not_configured`. Stackglass will not invent coverage or test results. diff --git a/apps/docs/index.md b/apps/docs/index.md index e296fac..e5f2704 100644 --- a/apps/docs/index.md +++ b/apps/docs/index.md @@ -9,16 +9,28 @@ hero: alt: Stackglass actions: - theme: brand + text: Install Cursor plugin + link: https://cursor.directory/plugins/stackglass + - theme: alt text: Get started link: /getting-started/introduction - theme: alt text: GitHub link: https://github.com/theworker02/stackglass + - theme: alt + text: Release v1.1.0 + link: https://github.com/theworker02/stackglass/releases/tag/v1.1.0 features: - title: GlassLab details: Discover tests, plan related runs, inspect failures, coverage, flakes, and contracts. Never invent results. + - title: GlassLens + details: Narrative, session replay, file heat, failure clusters, and suspicious-commit ranking from stored evidence. - title: 22 MCP tools details: Canonical tools plus resources and prompts. New capability is an optional argument, never a 23rd tool. - - title: Flight recorder - details: Timeline, session replay, file heat, and failure clusters from what actually happened in the workspace. + - title: Local dashboard + details: glass dashboard serves live Why, Session, Heat, and Clusters views on 127.0.0.1. + - title: Cursor plugin + details: Rules, skills, agents, commands, hooks, and MCP at the repository root. Install from cursor.directory. + - title: Local-first + details: No account for core functionality. Source is not uploaded. Secrets are never returned. --- diff --git a/apps/docs/mcp/setup.md b/apps/docs/mcp/setup.md index 76f8ad3..ff8df16 100644 --- a/apps/docs/mcp/setup.md +++ b/apps/docs/mcp/setup.md @@ -1,5 +1,15 @@ # MCP Setup -Start the MCP server with `node scripts/stackglass-mcp.mjs` after cloning this repository and running `npm install && npm run build`. +The Cursor plugin at [https://cursor.directory/plugins/stackglass](https://cursor.directory/plugins/stackglass) starts the server for you. -Set `STACKGLASS_ROOT` to the user workspace. Cursor plugin `mcp.json` does this automatically. +To run it yourself, clone this repository, `npm install && npm run build`, then: + +```bash +STACKGLASS_ROOT=/path/to/your/project node scripts/stackglass-mcp.mjs +``` + +Equivalent: `node servers/mcp/dist/bin.js` or `node cli/dist/bin.js mcp`. + +From a GitHub Release, extract `stackglass-mcp.zip` (same tree as `stackglass-cli.zip`) and use the same command. Set `STACKGLASS_ROOT` to the user workspace. Cursor plugin `mcp.json` does this automatically. + +The public surface is **exactly 22 tools**. See [Tools](/mcp/tools) and [tool reference](/mcp/tools-reference). diff --git a/apps/docs/mcp/tools.md b/apps/docs/mcp/tools.md index fb4409b..8018933 100644 --- a/apps/docs/mcp/tools.md +++ b/apps/docs/mcp/tools.md @@ -1,5 +1,7 @@ # MCP Tools -Stackglass exposes **exactly 22** canonical tools. Do not add dozens of tiny tools. +Stackglass exposes **exactly 22** canonical tools. Do not add dozens of tiny tools. New capability is an optional argument or an MCP resource, never a 23rd tool. See [MCP tool reference](/mcp/tools-reference) for schemas, examples, errors, and security notes for each tool. + +Install the Cursor plugin: [https://cursor.directory/plugins/stackglass](https://cursor.directory/plugins/stackglass). diff --git a/apps/docs/reference/cli.md b/apps/docs/reference/cli.md index 3b4202e..df1c123 100644 --- a/apps/docs/reference/cli.md +++ b/apps/docs/reference/cli.md @@ -1,3 +1,7 @@ # CLI -Binary: `glass` (fallback `stackglass`). See the README CLI tree. `glass mcp` starts the MCP server on stdio. `glass doctor bundle` writes a sanitized support archive without source or secrets. +There is no npm `bin`. The entry point is `node cli/dist/bin.js` (or `node scripts/glass.mjs` from a release zip). If you create a local alias named `glass` or `stackglass`, the command tree is the same. + +See the [README CLI catalog](https://github.com/theworker02/stackglass#cli-catalog). `glass mcp` starts the MCP server on stdio. `glass doctor bundle` writes a sanitized support archive without source or secrets. `glass dashboard` binds 127.0.0.1. + +Release zips: [v1.1.0](https://github.com/theworker02/stackglass/releases/tag/v1.1.0). Artifact usage: [docs/RELEASE.md](https://github.com/theworker02/stackglass/blob/master/docs/RELEASE.md). diff --git a/apps/docs/reference/troubleshooting.md b/apps/docs/reference/troubleshooting.md index c518a87..bb0bfb4 100644 --- a/apps/docs/reference/troubleshooting.md +++ b/apps/docs/reference/troubleshooting.md @@ -1,5 +1,15 @@ # Troubleshooting -Run `glass doctor`. +Run `node cli/dist/bin.js doctor` in the **user workspace**. -Common states: database not initialized (`glass init`), coverage `no_data` (no provider artifact), tests `unavailable` (no adapter detected), git `unavailable` (not a repository). +| Symptom | Likely cause | What to do | +| --------------------------- | --------------------------- | ---------------------------------------------------------------------------------------------------------------- | +| Database not initialized | No `.stackglass/` | `node …/cli/dist/bin.js init` | +| Coverage `no_data` | No provider artifact | Run the framework coverage reporter first | +| Tests `unavailable` | No adapter evidence | Confirm a known framework config exists | +| Git `unavailable` | Not a repository | Run inside a git checkout | +| MCP missing in Cursor | Plugin path or Node version | Reinstall from [cursor.directory/plugins/stackglass](https://cursor.directory/plugins/stackglass); Node >= 22.13 | +| MCP observes the wrong tree | `STACKGLASS_ROOT` unset | Point it at the user workspace | +| `glass` not found | Not an npm binary | Use `node cli/dist/bin.js` | + +Secrets must never appear in MCP, logs, or doctor bundles. Report redaction failures privately via GitHub Security Advisories. diff --git a/apps/docs/tools/releases.md b/apps/docs/tools/releases.md index 8be17aa..8f5edd3 100644 --- a/apps/docs/tools/releases.md +++ b/apps/docs/tools/releases.md @@ -1,3 +1,16 @@ # Releases -`release_readiness` never publishes. It reports git, tests, docs, config, changelog, and version checks. +`release_readiness` / `glass release` never publishes. It reports git, tests, docs, config, changelog, and version checks. + +Stackglass itself is distributed as GitHub Release zips, not npm. Current release: [v1.1.0](https://github.com/theworker02/stackglass/releases/tag/v1.1.0). + +| Artifact | Use | +| ------------------------------ | ---------------------------------------------------------- | +| `stackglass-cli.zip` | `node cli/dist/bin.js help` | +| `stackglass-mcp.zip` | `STACKGLASS_ROOT=/project node scripts/stackglass-mcp.mjs` | +| `stackglass-cursor-plugin.zip` | Cursor Open Plugins folder | +| `checksums.txt` | SHA-256 of the three zips | + +Cursor plugin listing: [https://cursor.directory/plugins/stackglass](https://cursor.directory/plugins/stackglass). + +Full instructions: [docs/RELEASE.md](https://github.com/theworker02/stackglass/blob/master/docs/RELEASE.md). diff --git a/docs/RELEASE.md b/docs/RELEASE.md new file mode 100644 index 0000000..262abaa --- /dev/null +++ b/docs/RELEASE.md @@ -0,0 +1,238 @@ +# Stackglass 1.1.0 + +See what your project is actually doing. Local-first observability and verification for Cursor — not another coding assistant. + +- **Cursor plugin:** https://cursor.directory/plugins/stackglass +- **Docs:** https://theworker02.github.io/stackglass/ +- **Source:** https://github.com/theworker02/stackglass + +This is a **GitHub Release**, not an npm package. Do not `npm install stackglass`, `npm link`, `npm pack`, or `npm publish`. Requires **Node.js >= 22.13.0**. There is no `bin` field and no global `glass` from the registry. Run `node cli/dist/bin.js` from a clone or from `stackglass-cli.zip`. + +## 1.1.0 highlights + +- **GlassLens** — `glass why`, `glass session`, `glass heat`, `glass clusters`, snapshot compare, and suspicious-commit ranking that does not assume the newest commit is guilty +- Optional modes on the existing **22 MCP tools** (`narrative`, `session`, `heat`, `rank_suspicious`, `files`, `repeat`, `cluster`). Never a 23rd tool. +- Live `glass dashboard` on 127.0.0.1 (Why / Session / Heat / Clusters) +- Watch `autoRun` for related tests +- Cursor plugin flattened to the repository root (`.cursor-plugin/plugin.json`) +- Distribution via GitHub Release zips instead of npm + +Full changelog: https://github.com/theworker02/stackglass/blob/master/CHANGELOG.md + +# Release artifacts and instructions + +Stackglass **1.1.0** is distributed as a **GitHub Release**, not an npm package. Do not `npm install stackglass`, `npm link`, `npm pack`, or `npm publish`. + +Requires **Node.js >= 22.13.0**. + +- Release page: https://github.com/theworker02/stackglass/releases/tag/v1.1.0 +- Cursor plugin listing: https://cursor.directory/plugins/stackglass +- Documentation: https://theworker02.github.io/stackglass/ + +This file is the in-repo companion to the published GitHub release notes. Maintainers update both when artifact usage changes. + +## What each zip is for + +| File | Audience | Contains | Does not contain | +| ------------------------------ | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------- | +| `stackglass-cli.zip` | Humans and scripts that want the CLI | Built `cli/dist`, `servers/mcp/dist`, `packages/core/dist`, `scripts/glass.mjs`, `scripts/stackglass-mcp.mjs`, production `node_modules`, a private `package.json` | Cursor rules/skills/plugin layout | +| `stackglass-mcp.zip` | MCP host configuration | The **same runtime tree** as the CLI zip | A different server binary. Start it with `node scripts/stackglass-mcp.mjs` | +| `stackglass-cursor-plugin.zip` | Cursor Open Plugins | `.cursor-plugin/plugin.json`, `mcp.json`, `rules/`, `skills/`, `agents/`, `commands/`, `hooks/`, MCP launcher scripts, logo | A full Node workspace. Do not expect `cli/dist` here | +| `checksums.txt` | Everyone | SHA-256 lines for the three zips | The zips themselves | + +The CLI and MCP zips are identical on purpose. Naming them separately makes the release page honest about the two jobs people come for: run commands, or speak MCP. If the hashes in `checksums.txt` differ between those two zips, the release is broken — do not use it. + +The plugin zip is a different tree. Cursor loads the folder that contains `.cursor-plugin/plugin.json`. + +## Verify checksums + +Download `checksums.txt` and the zips into one directory. + +```bash +# Linux +sha256sum -c checksums.txt + +# macOS (if sha256sum is missing) +shasum -a 256 -c checksums.txt +``` + +Windows PowerShell: + +```powershell +Get-FileHash .\stackglass-cli.zip -Algorithm SHA256 +Get-FileHash .\stackglass-mcp.zip -Algorithm SHA256 +Get-FileHash .\stackglass-cursor-plugin.zip -Algorithm SHA256 +Get-Content .\checksums.txt +``` + +Each computed hash must match the corresponding line. A mismatch means a truncated download or a tampered file. Delete the zip and download again from the official release URL. + +`scripts/package-release.mjs` writes `checksums.txt` as: + +```text + stackglass-cli.zip + stackglass-mcp.zip + stackglass-cursor-plugin.zip +``` + +## CLI zip + +```bash +unzip stackglass-cli.zip -d stackglass +cd stackglass +node cli/dist/bin.js help +node scripts/glass.mjs init +``` + +Against another project: + +```bash +node /path/to/extracted/stackglass/cli/dist/bin.js init +node /path/to/extracted/stackglass/cli/dist/bin.js status +node /path/to/extracted/stackglass/cli/dist/bin.js why +node /path/to/extracted/stackglass/cli/dist/bin.js dashboard +``` + +If `node_modules` is missing (or you want a clean install inside the extracted tree): + +```bash +npm install --omit=dev --ignore-scripts +``` + +That command only installs dependencies for the extracted workspace. It does not publish anything and it does not create a global `glass` binary. + +Windows: + +```powershell +Expand-Archive .\stackglass-cli.zip -DestinationPath .\stackglass +cd .\stackglass +node cli\dist\bin.js help +``` + +## MCP zip (22 tools) + +```bash +unzip stackglass-mcp.zip -d stackglass +cd stackglass +STACKGLASS_ROOT=/path/to/your/project node scripts/stackglass-mcp.mjs +``` + +Equivalent entry points in the same tree: + +```bash +node servers/mcp/dist/bin.js +node cli/dist/bin.js mcp +``` + +Windows PowerShell: + +```powershell +$env:STACKGLASS_ROOT="C:\path\to\your\project" +node scripts\stackglass-mcp.mjs +``` + +`STACKGLASS_ROOT` is the workspace to observe (the user's project). If you omit it, the server uses the process working directory, which is wrong when you launched it from the extracted Stackglass folder. + +The server is local stdio. It does not open a network port. Cursor's plugin `mcp.json` already sets: + +```json +{ + "mcpServers": { + "stackglass": { + "command": "node", + "args": ["${PLUGIN_ROOT}/scripts/stackglass-mcp.mjs"], + "env": { + "STACKGLASS_ROOT": "${workspaceFolder}" + } + } + } +} +``` + +There are exactly 22 tools. See the [README MCP catalog](../README.md#22-mcp-tools) and the [tool reference](https://theworker02.github.io/stackglass/mcp/tools-reference). + +## Cursor plugin zip + +Prefer the published listing when you can: + +**https://cursor.directory/plugins/stackglass** + +To install from the release zip instead: + +1. Extract `stackglass-cursor-plugin.zip` to a stable folder you will not delete on reboot. +2. In Cursor, add that folder as an Open Plugin. The folder root must contain `.cursor-plugin/plugin.json`. +3. Confirm MCP server `stackglass` appears. +4. In the project you want to observe, run the CLI `init` from the CLI zip or a source checkout. + +Plugin layout after extract: + +```text +.cursor-plugin/plugin.json +mcp.json +rules/ +skills/ +agents/ +commands/ +hooks/ +scripts/session-start.mjs +scripts/stackglass-mcp.mjs +assets/logo.svg +README.md +``` + +The plugin zip is **not** the CLI. After install you still need a built CLI (source checkout or `stackglass-cli.zip`) to run `init`, `status`, `dashboard`, and GlassLab commands. + +Do not add `.cursor-plugin/marketplace.json` unless this repository becomes a multi-plugin marketplace. + +## Plugin vs CLI vs MCP + +| Job | Use | +| ----------------------------------------------------- | ----------------------------------------------------------------- | +| Give Cursor rules, skills, and an MCP server | Plugin listing or `stackglass-cursor-plugin.zip` | +| Initialize a workspace, run tests, open the dashboard | `stackglass-cli.zip` or `node cli/dist/bin.js` from a built clone | +| Speak MCP to a host that is not the Cursor plugin | `stackglass-mcp.zip` or `node scripts/stackglass-mcp.mjs` | +| Read evidence in a browser on this machine | `node cli/dist/bin.js dashboard` (127.0.0.1) | + +All three paths share GlassCore. They must not grow a second project model. New MCP capability is an optional argument, never a 23rd tool. + +## Source checkout (maintainers and contributors) + +```bash +git clone https://github.com/theworker02/stackglass.git +cd stackglass +npm install +npm run build +node cli/dist/bin.js --help +npm run plugin:build +node scripts/package-release.mjs +``` + +`package-release.mjs` writes `dist-release/stackglass-cli.zip`, `stackglass-mcp.zip`, `stackglass-cursor-plugin.zip`, and `checksums.txt`. CI does the same on a version tag via `.github/workflows/release.yml`. + +## How a GitHub Release is cut + +1. `npm test` and `npm run build` on a clean tree. +2. `node cli/dist/bin.js release` against this repository (dogfood). It never publishes. +3. Update [CHANGELOG.md](../CHANGELOG.md). +4. Tag `vX.Y.Z` and push the tag. Do not force-push tags or `master`. +5. GitHub Actions attaches the zips and checksums. `docs.yml` deploys GitHub Pages when `master` updates. +6. Expand the published release body (this file is the source of truth for artifact usage). Example: + +```bash +gh release edit v1.1.0 --notes-file docs/RELEASE.md +``` + +`master` is protected: require a pull request, no force-push. + +Stackglass is not an npm package. Do not add `bin`, `files`, `publishConfig`, or registry publish steps. + +## Version 1.1.0 highlights + +- GlassLens: `why`, `session`, `heat`, `clusters`, snapshot compare, suspicious-commit ranking +- Optional modes on the existing 22 tools (`narrative`, `session`, `heat`, `rank_suspicious`, `files`, `repeat`, `cluster`) +- Live `glass dashboard` as the canonical UI +- Watch `autoRun` for related tests +- Cursor plugin flattened to the repository root +- GitHub Release zips instead of npm distribution + +See [CHANGELOG.md](../CHANGELOG.md) for the full 1.1.0 list. diff --git a/scripts/build-plugin.mjs b/scripts/build-plugin.mjs index c0e80e3..c8c9049 100644 --- a/scripts/build-plugin.mjs +++ b/scripts/build-plugin.mjs @@ -59,10 +59,11 @@ scripts/stackglass-mcp.mjs assets/logo.svg \`\`\` -Clone this repository, run \`npm install\` and \`npm run build\`, then -\`node cli/dist/bin.js init\` in the target workspace. \`mcp.json\` starts -\`node \${PLUGIN_ROOT}/scripts/stackglass-mcp.mjs\` and sets \`STACKGLASS_ROOT\` -to the current workspace. +Install from https://cursor.directory/plugins/stackglass when you want the +published listing. Otherwise clone this repository, run \`npm install\` and +\`npm run build\`, then \`node cli/dist/bin.js init\` in the target workspace. +\`mcp.json\` starts \`node \${PLUGIN_ROOT}/scripts/stackglass-mcp.mjs\` and sets +\`STACKGLASS_ROOT\` to the current workspace. `, ); diff --git a/scripts/package-release.mjs b/scripts/package-release.mjs index bbc2006..f45830c 100644 --- a/scripts/package-release.mjs +++ b/scripts/package-release.mjs @@ -121,7 +121,13 @@ On macOS/Linux: \`STACKGLASS_ROOT=/path/to/your/project node scripts/stackglass- ## Cursor plugin -Use \`stackglass-cursor-plugin.zip\` from the same GitHub Release. That zip is the Open Plugins layout (\`.cursor-plugin/plugin.json\`, \`mcp.json\`, rules, skills, agents, commands, hooks). +Prefer https://cursor.directory/plugins/stackglass + +Or use \`stackglass-cursor-plugin.zip\` from the same GitHub Release. That zip is the Open Plugins layout (\`.cursor-plugin/plugin.json\`, \`mcp.json\`, rules, skills, agents, commands, hooks). + +## Checksums + +Verify SHA-256 lines in \`checksums.txt\` before you run an extracted tree. See https://github.com/theworker02/stackglass/blob/master/docs/RELEASE.md Docs: https://theworker02.github.io/stackglass/ `, diff --git a/scripts/write-docs.mjs b/scripts/write-docs.mjs index 78ca830..3ea5131 100644 --- a/scripts/write-docs.mjs +++ b/scripts/write-docs.mjs @@ -4,7 +4,14 @@ import path from "node:path"; const root = path.join(process.cwd(), "apps/docs"); +// Hand-crafted landing lives in apps/docs/index.md plus .vitepress/theme. +// Never write index.md from this generator — docs:build must keep the custom home. +const HAND_CRAFTED = new Set(["index.md"]); + function page(rel, title, body) { + if (HAND_CRAFTED.has(rel) || rel === "index.md") { + throw new Error(`refusing to overwrite hand-crafted page: ${rel}`); + } const abs = path.join(root, rel); mkdirSync(path.dirname(abs), { recursive: true }); writeFileSync(abs, `# ${title}\n\n${body.trim()}\n`, "utf8"); @@ -17,13 +24,33 @@ page( It is **not** an AI that writes code. Cursor already provides the coding agent. Stackglass gives that agent evidence about project state, tests, failures, history, configuration, contracts, and documentation. -The defining principle: **give coding agents evidence instead of forcing them to guess.**`, +The defining principle: **give coding agents evidence instead of forcing them to guess.** + +Install the Cursor plugin: [https://cursor.directory/plugins/stackglass](https://cursor.directory/plugins/stackglass) + +## What it is + +A flight recorder, testing laboratory (GlassLab), change inspector, MCP server with **exactly 22 tools**, Cursor plugin, GlassLens, and a local dashboard. Version **1.1.0**. + +## What it is not + +Not a coding assistant. Not an npm package (\`bin\`, \`npm link\`, and \`npm publish\` are not part of this project). Not a 23rd MCP tool. Not a cloud that uploads source. \`release_readiness\` never publishes. + +Missing data is reported as \`no_data\`, \`unavailable\`, or \`not_configured\`. Stackglass will not invent coverage or test results.`, ); page( "getting-started/installation.md", "Installation", - `Requires Node.js 22.13 or later. Stackglass is not an npm package. + `Requires **Node.js 22.13** or later. Stackglass is **not** an npm package. Do not \`npm install -g stackglass\`, \`npm link\`, or \`npx stackglass\`. + +## Cursor plugin + +Install from [https://cursor.directory/plugins/stackglass](https://cursor.directory/plugins/stackglass). + +That listing is the install CTA for the repository. You can also extract \`stackglass-cursor-plugin.zip\` from [GitHub Release v1.1.0](https://github.com/theworker02/stackglass/releases/tag/v1.1.0) and add the folder as an Open Plugin. + +## Clone and build \`\`\`bash git clone https://github.com/theworker02/stackglass.git @@ -33,7 +60,22 @@ npm run build node cli/dist/bin.js --help \`\`\` -From another project: \`node /path/to/stackglass/cli/dist/bin.js init\`.`, +From another project: \`node /path/to/stackglass/cli/dist/bin.js init\`. + +There is no global \`glass\` binary from npm. Use \`node cli/dist/bin.js\` or \`node scripts/glass.mjs\`. + +## Release zips + +Download from [v1.1.0](https://github.com/theworker02/stackglass/releases/tag/v1.1.0): + +- \`stackglass-cli.zip\` — \`node cli/dist/bin.js help\` +- \`stackglass-mcp.zip\` — \`STACKGLASS_ROOT=/your/project node scripts/stackglass-mcp.mjs\` +- \`stackglass-cursor-plugin.zip\` — Cursor Open Plugins layout +- \`checksums.txt\` — SHA-256 of the zips + +Verify hashes before you run an extracted tree. Full artifact instructions: [docs/RELEASE.md](https://github.com/theworker02/stackglass/blob/master/docs/RELEASE.md). + +\`STACKGLASS_ROOT\` is the workspace to observe. If you launch the CLI or MCP from the Stackglass checkout, set it to the user project.`, ); page( @@ -53,16 +95,37 @@ glass dashboard page( "getting-started/cursor-setup.md", "Cursor Setup", - `Stackglass integrates with Cursor through the official plugin format: + `Install the plugin from [https://cursor.directory/plugins/stackglass](https://cursor.directory/plugins/stackglass). -- MCP server \`stackglass-mcp\` (22 tools, resources, prompts) +Stackglass integrates with Cursor through the official Open Plugins layout at the **repository root**: + +- MCP server \`stackglass\` — \`node scripts/stackglass-mcp.mjs\`, 22 tools, resources, prompts - Rules in \`rules/\` - Skills in \`skills/\` -- Commands and agents in the plugin package +- Agents in \`agents/\` +- Commands in \`commands/\` +- Hooks in \`hooks/\` +- \`mcp.json\` sets \`STACKGLASS_ROOT\` to the current workspace + +\`\`\`text +.cursor-plugin/plugin.json +mcp.json +rules/ +skills/ +agents/ +commands/ +hooks/ +scripts/stackglass-mcp.mjs +\`\`\` -The plugin lives at the repository root (\`.cursor-plugin/plugin.json\`, \`mcp.json\`, \`rules/\`, \`skills/\`, \`agents/\`, \`commands/\`, \`hooks/\`). Install it from this repo in Cursor, then run \`glass init\` in the project so the agent has a database and index. +After the plugin is available: -The dashboard is \`glass dashboard\` (127.0.0.1). Cursor plugins do not expose a custom sidebar API; the local dashboard and MCP resources provide the UI and evidence surface.`, +1. Clone this repository (or extract \`stackglass-cli.zip\`) and, for a source checkout, run \`npm install\` then \`npm run build\`. +2. In the project you want to observe: \`node /path/to/stackglass/cli/dist/bin.js init\`. +3. Confirm MCP server \`stackglass\` is listed in Cursor. +4. Open the UI with \`node /path/to/stackglass/cli/dist/bin.js dashboard\` (127.0.0.1). + +Cursor plugins do not expose a custom sidebar API. The local dashboard and MCP resources are the evidence surface. Do not add \`.cursor-plugin/marketplace.json\` unless this repository becomes a multi-plugin marketplace.`, ); page( @@ -194,17 +257,29 @@ Insufficient history is not presented as a confident statistic.`, page( "mcp/setup.md", "MCP Setup", - `Start the MCP server with \`node scripts/stackglass-mcp.mjs\` after cloning this repository and running \`npm install && npm run build\`. + `The Cursor plugin at [https://cursor.directory/plugins/stackglass](https://cursor.directory/plugins/stackglass) starts the server for you. + +To run it yourself, clone this repository, \`npm install && npm run build\`, then: + +\`\`\`bash +STACKGLASS_ROOT=/path/to/your/project node scripts/stackglass-mcp.mjs +\`\`\` -Set \`STACKGLASS_ROOT\` to the user workspace. Cursor plugin \`mcp.json\` does this automatically.`, +Equivalent: \`node servers/mcp/dist/bin.js\` or \`node cli/dist/bin.js mcp\`. + +From a GitHub Release, extract \`stackglass-mcp.zip\` (same tree as \`stackglass-cli.zip\`) and use the same command. Set \`STACKGLASS_ROOT\` to the user workspace. Cursor plugin \`mcp.json\` does this automatically. + +The public surface is **exactly 22 tools**. See [Tools](/mcp/tools) and [tool reference](/mcp/tools-reference).`, ); page( "mcp/tools.md", "MCP Tools", - `Stackglass exposes **exactly 22** canonical tools. Do not add dozens of tiny tools. + `Stackglass exposes **exactly 22** canonical tools. Do not add dozens of tiny tools. New capability is an optional argument or an MCP resource, never a 23rd tool. -See [MCP tool reference](/mcp/tools-reference) for schemas, examples, errors, and security notes for each tool.`, +See [MCP tool reference](/mcp/tools-reference) for schemas, examples, errors, and security notes for each tool. + +Install the Cursor plugin: [https://cursor.directory/plugins/stackglass](https://cursor.directory/plugins/stackglass).`, ); const tools = [ @@ -343,7 +418,20 @@ page( page( "tools/releases.md", "Releases", - "`release_readiness` never publishes. It reports git, tests, docs, config, changelog, and version checks.", + `\`release_readiness\` / \`glass release\` never publishes. It reports git, tests, docs, config, changelog, and version checks. + +Stackglass itself is distributed as GitHub Release zips, not npm. Current release: [v1.1.0](https://github.com/theworker02/stackglass/releases/tag/v1.1.0). + +| Artifact | Use | +| --- | --- | +| \`stackglass-cli.zip\` | \`node cli/dist/bin.js help\` | +| \`stackglass-mcp.zip\` | \`STACKGLASS_ROOT=/project node scripts/stackglass-mcp.mjs\` | +| \`stackglass-cursor-plugin.zip\` | Cursor Open Plugins folder | +| \`checksums.txt\` | SHA-256 of the three zips | + +Cursor plugin listing: [https://cursor.directory/plugins/stackglass](https://cursor.directory/plugins/stackglass). + +Full instructions: [docs/RELEASE.md](https://github.com/theworker02/stackglass/blob/master/docs/RELEASE.md).`, ); page( @@ -380,7 +468,11 @@ page( page( "reference/cli.md", "CLI", - "Binary: `glass` (fallback `stackglass`). See the README CLI tree. `glass mcp` starts the MCP server on stdio. `glass doctor bundle` writes a sanitized support archive without source or secrets.", + `There is no npm \`bin\`. The entry point is \`node cli/dist/bin.js\` (or \`node scripts/glass.mjs\` from a release zip). If you create a local alias named \`glass\` or \`stackglass\`, the command tree is the same. + +See the [README CLI catalog](https://github.com/theworker02/stackglass#cli-catalog). \`glass mcp\` starts the MCP server on stdio. \`glass doctor bundle\` writes a sanitized support archive without source or secrets. \`glass dashboard\` binds 127.0.0.1. + +Release zips: [v1.1.0](https://github.com/theworker02/stackglass/releases/tag/v1.1.0). Artifact usage: [docs/RELEASE.md](https://github.com/theworker02/stackglass/blob/master/docs/RELEASE.md).`, ); page( "reference/configuration.md", @@ -404,13 +496,31 @@ The MCP server and CLI use the same core.`, page( "reference/troubleshooting.md", "Troubleshooting", - `Run \`glass doctor\`. + `Run \`node cli/dist/bin.js doctor\` in the **user workspace**. -Common states: database not initialized (\`glass init\`), coverage \`no_data\` (no provider artifact), tests \`unavailable\` (no adapter detected), git \`unavailable\` (not a repository).`, +| Symptom | Likely cause | What to do | +| --- | --- | --- | +| Database not initialized | No \`.stackglass/\` | \`node …/cli/dist/bin.js init\` | +| Coverage \`no_data\` | No provider artifact | Run the framework coverage reporter first | +| Tests \`unavailable\` | No adapter evidence | Confirm a known framework config exists | +| Git \`unavailable\` | Not a repository | Run inside a git checkout | +| MCP missing in Cursor | Plugin path or Node version | Reinstall from [cursor.directory/plugins/stackglass](https://cursor.directory/plugins/stackglass); Node >= 22.13 | +| MCP observes the wrong tree | \`STACKGLASS_ROOT\` unset | Point it at the user workspace | +| \`glass\` not found | Not an npm binary | Use \`node cli/dist/bin.js\` | + +Secrets must never appear in MCP, logs, or doctor bundles. Report redaction failures privately via GitHub Security Advisories.`, ); const brand = spawnSync(process.execPath, [path.join(process.cwd(), "scripts/sync-brand.mjs")], { stdio: "inherit", }); if (brand.status) process.exit(brand.status); + +const prettier = spawnSync( + process.platform === "win32" ? "npx.cmd" : "npx", + ["prettier", "--write", "apps/docs/**/*.md"], + { stdio: "inherit", shell: process.platform === "win32" }, +); +if (prettier.status) process.exit(prettier.status); + console.log("docs pages written"); diff --git a/tests/plugin-ui.test.ts b/tests/plugin-ui.test.ts index 065f39c..56a5ce5 100644 --- a/tests/plugin-ui.test.ts +++ b/tests/plugin-ui.test.ts @@ -29,6 +29,14 @@ describe("plugin UI navigation contract", () => { const dash = readFileSync(path.join(root, "apps/dashboard/index.html"), "utf8"); expect(docs).toContain('logo: "/logo.svg"'); expect(home).toContain("src: /logo.svg"); + expect(home).toContain("https://cursor.directory/plugins/stackglass"); expect(dash).toContain('src="/logo.svg"'); }); + + it("README promotes the Cursor plugin listing", () => { + const readme = readFileSync(path.join(root, "README.md"), "utf8"); + expect(readme).toContain("https://cursor.directory/plugins/stackglass"); + expect(readme).toContain("node cli/dist/bin.js"); + expect(readme).toContain("exactly 22 MCP tools"); + }); });