noslopui 0.0.1 → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 noslopUI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,5 +1,79 @@
 # noslopui
 
-Connect your coding agent to [noslopUI](https://noslopui.com), a catalog of hand-crafted UI components and design systems.
+Connect your coding agent to [noslopUI](https://noslopui.com) — hand-crafted UI components and portable design systems, over MCP.
 
-The one-command installer (`npx noslopui init`) is in progress. Until it ships, see [noslopui.com/mcp](https://noslopui.com/mcp) for manual setup.
+```bash
+npx noslopui@latest init
+```
+
+That one command finds your agent, signs you in through the browser, adds the MCP server to your agent's **user-level** config, and installs the workflow skill. Restart your agent and ask it to build something.
+
+## Why
+
+Ask any agent for a landing page and you get the same page: gradient headline, purple on purple, three cards, everything centred. noslopUI gives it a real catalog to work from — components someone designed, and design systems that are a set of rules rather than a folder of parts, so a five-page build reads as one site.
+
+The MCP server is what your agent calls. The skill is what makes it think to call it at all when you say "build me a website" — so `init` installs both, and you can skip the skill with `--no-skill`.
+
+## Commands
+
+| | |
+|---|---|
+| `npx noslopui init` | Set up an agent: sign in, add the server, install the skill |
+| `npx noslopui doctor` | Check what's set up, and say what to do about anything that isn't |
+| `npx noslopui login` | Get a fresh key for an agent that's already set up |
+| `npx noslopui update` | Re-download the skill |
+| `npx noslopui remove` | Take the noslopUI server back out |
+
+Options: `--agent <id>`, `--no-skill`, `--no-browser`, `--key <key>`, `-y/--yes`.
+
+## Supported agents
+
+**Claude Code.** That's the list.
+
+Other agents are added one at a time, and only after a real install has been done on a real machine, end to end — an agent named here is one we're claiming works. The server enforces the same list: asking for a key for an agent that hasn't passed gets refused, so an out-of-date copy of this CLI can't get one either.
+
+## What it does to your machine
+
+It edits your agent's user-level config, and nothing else. Concretely, for Claude Code:
+
+- Adds one entry, `noslopui`, under `mcpServers` in `~/.claude.json`.
+- **Copies the file first.** The backup is written next to the original as `.claude.json.noslopui-backup-<timestamp>`, and its path is printed.
+- **Never touches another server's entry**, or any of the other state Claude Code keeps in that file.
+- **Never writes to a project config.** A key in a project file is a key that gets committed.
+- **Stops if the config doesn't parse.** It will not overwrite a file it couldn't read — that file is the only copy of your setup, and guessing at its contents would be worse than doing nothing.
+- Writes the skill to `~/.claude/skills/noslopui/SKILL.md`.
+
+`remove` takes the entry back out and leaves everything else, including the skill unless you pass `--skill`. It does **not** revoke your key: the key belongs to your account, not to this machine. Revoke it at [noslopui.com/account](https://noslopui.com/account?tab=mcp).
+
+### If Claude Code is running
+
+`~/.claude.json` is also Claude Code's own state file, and a running Claude Code rewrites it from memory. Quit it before running `init`, or the entry can be overwritten seconds later. `doctor` re-reads the file rather than trusting the write, so it will tell you if that happened.
+
+## Your key
+
+`init` issues one key per agent, named after the agent and this machine, so you can tell them apart and revoke one without breaking the others. The key is written to your agent's config and nowhere else — this tool never prints it in full, and never sends it anywhere except noslopui.com.
+
+`--key <key>` skips the browser and uses a key you already made on the account page, for CI or a machine with no browser.
+
+## The skill
+
+The workflow has one source, and it isn't this repo: it's assembled on the server and served at [noslopui.com/skill/SKILL.md](https://noslopui.com/skill/SKILL.md). That's the same text the MCP server sends as its `instructions` on every connection, so an agent gets the rules whether or not the skill is installed.
+
+`init` downloads it fresh. The copy in this repo exists so `npx skills add noslopUI/cli` has something to find, and as a fallback when the site is unreachable — `npm run sync-skill` refreshes it and CI fails if it has drifted.
+
+## Development
+
+```bash
+npm install
+npm run build
+npm test          # adapter contract tests, against fixture configs in a throwaway HOME
+npm run typecheck
+```
+
+`NOSLOPUI_ORIGIN` points the CLI at a different server, which is how the flow is exercised against a local one.
+
+Adding an agent is one module implementing `Adapter` (`src/adapters/types.ts`), one line in the registry, and a real install before it goes in the list.
+
+## Licence
+
+MIT

package/SKILL.md

@@ -0,0 +1,249 @@
+---
+name: noslopui
+description: Build a stunning, non-generic UI using noslopUI's hand-crafted catalog over MCP — either from a collection the user curated themselves, or by choosing one Design System and applying it consistently across every component. Use when asked to build a landing page, dashboard, marketing site, or any new page/section from scratch, when the user mentions a noslopUI collection, or when a UI you're building looks like "AI slop" (gradient text, purple-on-purple, bounce easing, everything centered) and needs a real design system instead.
+---
+
+# noslopUI
+
+You have access to the **noslopUI MCP server** — a catalog of hand-crafted (not
+AI-generated) UI components, full page examples, and portable Design Systems.
+
+## The rules
+
+1. **Choose one design system before fetching any component, then restyle every component to it** — colours, type scale, spacing, radius, motion. One system applied everywhere is what stops a multi-page build reading as a collage.
+2. **Search the whole catalog on fit.** A design system is a set of rules, not an inventory of parts: any component can be built in any system, so nothing is off-limits once one is chosen.
+3. **Never substitute a catalog component for one the user explicitly saved** in a collection. Their pick was a decision, not an oversight.
+4. **Ask about their brand before building** — logo, brand colours, typeface, real photography. Put their values into the system's tokens (their colour replaces `accent`) and keep the system's rules.
+5. **Check for a collection first:** call `list_collections`. If one fits the request, build from it. If none fits, or no key is configured, don't guess a collection — shortlist two or three design systems with `search_design_systems` and let the user pick.
+6. **If a gated tool says the trial has ended or the fair-use limit is reached, tell the user and stop** — don't retry, and don't swap in something generated from scratch.
+
+Setup, if a tool says no key is configured: the user creates an API key at
+`noslopui.com/account` (MCP tab) and adds it to this MCP server's config as an
+`Authorization: Bearer <key>` header. Search, metadata and design-system token
+tools work without one. Code, prompts and DESIGN.md files need a key on a paid
+plan or inside the account's free 3-day trial, which the first such call
+starts.
+
+---
+
+## Step 0 — Which path?
+
+**Call `list_collections` first.** It's free on every account.
+
+- A relevant collection exists → **Path A**. The user already did the choosing.
+- No collection, or nothing relevant → **Path B**.
+- It says no key is configured → **Path B**, without calling `get_collection`
+  (it needs the same key, and a guessed collection name finds nothing). Tell the
+  user once that code and DESIGN.md files will need a key — see Setup above —
+  and carry on with everything that works without one.
+
+Several collections and no obvious match → ask. Don't guess between two curated
+sets.
+
+---
+
+## Step 1 — Requirements, including brand
+
+Do this on both paths, before choosing a system. Two groups of things.
+
+**The build:**
+
+1. **Purpose** — what is this for? (SaaS product, local service business,
+   portfolio, storefront, internal dashboard, docs site, …)
+2. **Audience** — who is it for?
+3. **Tone** — 2-3 words ("calm and minimal", "bold and playful", "editorial and
+   serif-driven", "warm and local"). This is what Step 2 matches against.
+4. **Required sections** — the concrete list of what must exist.
+
+**Their brand** — skip this and you ship a beautiful page that isn't theirs:
+
+5. **Logo or wordmark** — do they have one, and in what format?
+6. **Brand colours** — hex values if they have them, and whether they are fixed
+   (a franchise or a rebrand-in-progress changes the answer).
+7. **Existing typeface** — anything already in use they need to stay with?
+8. **Photography or illustration** — real assets to work from, or
+   placeholder-and-replace-later?
+9. **An existing site or profile** to stay consistent with.
+
+No brand at all → say so plainly and use the design system's own palette. Don't
+invent a logo.
+
+If the user already stated all this, don't re-ask — restate it in one line and
+move on.
+
+---
+
+## Path A — the user curated a collection
+
+`get_collection({ listId })` (or `name`). Every item carries a `kind` —
+`design_systems` or `ui_blocks` — plus a top-level `designSystems` array and a
+`guidance` line.
+
+1. **The collection's design system wins.** One in it → that is the system, no
+   searching; `get_design_system_file` for its DESIGN.md. More than one → ask
+   which; they saved both deliberately. None → say so, choose one as in Path B,
+   and tell them which and why.
+2. **Cover each required section from the collection first.** If the user saved
+   something that covers a section, use it. Always. **Never substitute a
+   catalog component for one they explicitly saved**, even if you found
+   something you think is better — that was their call, not an oversight.
+3. **Fill the gaps with `search_components`**, searching the whole catalog on
+   fit, and restyle what you find to the collection's design system.
+4. **Report what you filled in.** "Hero, pricing and footer from your
+   collection; you had no testimonial section saved, so I pulled one from the
+   catalog and restyled it." They should never have to diff the result to find
+   out what they didn't choose.
+
+Continue to Step 3.
+
+---
+
+## Path B — you choose
+
+### B1. Shortlist design systems, then ask
+
+Design systems are classified by **tag**, not by category — there is no tree to
+walk. Call `search_design_systems` with no arguments first if you don't know
+what exists: it returns every system plus `availableTags`, the full filterable
+vocabulary (`theme:`, `style:`, `industry:` and so on).
+
+Then filter with `tags` (ANDed) and/or a free-text `query` built from the tone
+words plus purpose:
+
+```
+search_design_systems({ tags: ["theme:light", "industry:local-business"] })
+search_design_systems({ query: "calm minimal saas", tags: ["theme:light"] })
+```
+
+A system can carry several `industry:` tags — a developer-tools system is
+often a SaaS system too — so don't treat one tag as excluding the others.
+
+Every result comes back with its tags, its token summary (colours, fonts,
+radius) and a `previewUrl`. **Present the 2-3 best matches to the user with
+their names, one-line descriptions, palettes and preview URLs, and ask which
+they want.** Don't pick silently. This single choice shapes every screen, it
+costs one question, and the user has taste you cannot infer from "a roofing
+business".
+
+Then `get_design_system` on their pick for the ungated token summary, and
+`get_design_system_file` for the full DESIGN.md.
+
+If nothing matches well, say so and ask whether to go with the closest or with
+a system they describe by hand — don't quietly fall back to stock Tailwind
+defaults, which is the "AI slop" this workflow exists to avoid.
+
+**Read the whole DESIGN.md before fetching any component.** It's short by
+design — tokens plus a page or two of intent prose, meant to be held in context
+for the entire build. Its **Do's and Don'ts** section is the part doing the real
+work.
+
+### B2. Find components on fit
+
+For each required section, call `search_components` — `section`, `framework`
+and `tags` filters as needed, with `tags` ANDed the same way
+(`["style:editorial"]`, `["animation:carousel"]`). Pick the best
+**structural** match: the thing that actually does what the section needs.
+Largely ignore how it currently looks; you are restyling it regardless.
+
+Then `get_component_code` for the ones you'll use.
+
+---
+
+## Step 3 — Apply the system, and fit the brand into it
+
+Two moves, in this order.
+
+**A. Restyle everything to the design system.** Same colour variables, same type
+scale, same radius, same spacing scale, same motion durations and easing, across
+every component. Where a fetched component's own defaults conflict with the
+system, the system wins — adapt the component, and never leave both looks in
+play at once.
+
+**B. Substitute the brand into the system's tokens.** This is what makes the
+result *theirs* rather than a nice demo:
+
+- Their primary colour replaces the system's `accent` token. A secondary, if
+  they have one, replaces a supporting token — not a second accent.
+- Their wordmark typeface replaces the `display` face if it suits headlines.
+  Body text stays the system's text face unless they insist.
+- Their photography replaces placeholder imagery at the same crops and ratios.
+
+**Substitute values, keep the rules.** The system's spacing scale, radius
+discipline, contrast requirements and "one accent moment per screen" all still
+apply after the swap — that is the point of a system: it survives a brand
+change. A roofing company's green goes where the indigo was, and the restraint
+around it is unchanged.
+
+**Check contrast after substituting.** A brand colour that fails the system's
+stated contrast pairs is a real problem: tell the user, propose a darker or
+lighter variant of their colour for text, and keep the original for large
+fills. Don't silently ship unreadable text because it was their hex.
+
+DESIGN.md files follow the open [DESIGN.md
+format](https://github.com/google-labs-code/design.md): YAML front matter with
+machine-readable tokens (`colors`, `typography`, `rounded`, `spacing`,
+`components`, with `{colors.accent}` references already resolved), then prose
+sections. Take concrete values from the front matter and the rules from the
+prose.
+
+## Step 4 — Polish pass (before calling anything done)
+
+Run this against the assembled result. These are the "AI slop" tells noslopUI
+exists to avoid — catch them here rather than shipping them:
+
+- **Typography** — one display face used sparingly (headlines only, not buttons
+  or body), one text face for everything else. Nothing outside the DESIGN.md's
+  stated scale.
+- **Color/contrast** — one accent moment per screen, not accent bleeding into
+  every icon, border and badge. Real contrast on text over any background,
+  checked against the DESIGN.md's own stated pairs.
+- **Spacing** — compose from the DESIGN.md's spacing scale; don't invent
+  in-between values. Prefer more whitespace over a denser grid.
+- **Motion** — only where it communicates a real state change; the DESIGN.md's
+  durations and easing, never a default bounce or spring.
+- **Named slop-tells to actively reject**: gradient text, purple-on-purple
+  palettes, bounce/spring easing on everything, every layout centered with no
+  asymmetry, decorative-only animation.
+
+## Step 5 — Point back to the catalog for variations
+
+If the result doesn't land, don't re-prompt the same component blind. Point the
+user at `noslopui.com/explore` (cross-catalog search across UI Blocks and
+Design Systems in one grid) to browse real alternatives, and at the
+Collections tab on `noslopui.com/account` to save the ones they like — which
+turns the next build into Path A. Then repeat from Step 3 with whatever they
+pick.
+
+---
+
+## Quick reference — tool call shape
+
+```
+list_collections({})                                           -> { collections: [{ id, name, itemCount }] }
+get_collection({ listId?, name? })                             -> { collection, designSystems: [{id,name}], items: [{ id, name, kind, ... }], guidance }
+
+search_design_systems({ query?, tags?, tag?, limit? })          -> { results: [{ id, name, description, tags, tokens, previewUrl, url }], availableTags }
+get_design_system({ id })                                       -> { id, name, tokens, previewUrl, detailUrl }
+get_design_system_file({ id })                                  -> { id, name, designMd }       [gated: paid or trial]
+
+search_components({ query?, section?, framework?, tags?, tag?, limit? }) -> { results: [{ id, name, kind, tags, url }] }
+get_component({ id })                                             -> { id, name, dependencies, builtWithDesignSystem, previewUrl, detailUrl }
+get_component_code({ id })                                         -> { id, name, snippets: [{ language, code }] } [gated: paid or trial]
+get_component_prompt({ id })                                        -> { id, name, promptText }   [gated: paid or trial]
+```
+
+The key rides on the connection (the `Authorization` header), so no tool needs
+an `apiKey` argument. Every search, metadata and collection tool is free on
+every account; `get_design_system_file`, `get_component_code` and
+`get_component_prompt` need the account on a paid plan or inside its free
+3-day trial.
+
+- If a gated call's result carries a `trial` field, that call just started the
+  user's trial — tell them, with the end date it gives.
+- A trial covers up to 30 different items per 24 hours, far more than one site
+  needs. Fetch what the build uses, not the catalog speculatively; re-fetching
+  an item you already opened never counts again.
+- If a gated call says the trial has ended (or the fair-use limit is reached),
+  stop and tell the user plainly — don't retry, and don't quietly swap in
+  something generated from scratch in its place. Search and collections keep
+  working, so the plan itself can still be finished.

package/dist/adapters/claude-code.js

@@ -0,0 +1,146 @@
+// Claude Code.
+//
+// User-level MCP servers live at the top level of `~/.claude.json`, under
+// `mcpServers`, as `{ type: 'http', url, headers }`. Project-scoped ones live
+// under `projects["<path>"].mcpServers` — we never write there: a key in a
+// project file is a key that gets committed.
+//
+// WHY WE WRITE THE FILE RATHER THAN SHELLING OUT TO `claude mcp add`:
+// the documented command takes the key as `--header "Authorization: Bearer …"`,
+// which puts the key in the process list for as long as the command runs,
+// where any other process on the machine can read it. Writing the file
+// ourselves keeps the key in two places only — the config and the account.
+// The format is small and we verify our write by reading it back.
+//
+// KNOWN LIMITATION: `~/.claude.json` is also Claude Code's own state file, and
+// a running Claude Code rewrites it from memory on all sorts of events. If it
+// is open while this runs, it can overwrite our entry when it next saves.
+// That's why install tells the user to quit Claude Code first, and why
+// `doctor` re-checks rather than trusting that the write stuck.
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { delimiter, dirname, join } from 'node:path';
+import { backupFile, detectIndent, readJsonFile, writeJsonFile } from '../lib/json-file.js';
+/** The name the server appears under. Also what the user types: `/mcp__noslopui__build_ui`. */
+export const SERVER_NAME = 'noslopui';
+const SKILL_DIR_NAME = 'noslopui';
+function onPath(binary) {
+    const paths = (process.env.PATH ?? '').split(delimiter).filter(Boolean);
+    const suffixes = process.platform === 'win32' ? (process.env.PATHEXT ?? '.EXE;.CMD;.BAT').split(';') : [''];
+    for (const dir of paths) {
+        for (const suffix of suffixes) {
+            try {
+                if (existsSync(join(dir, binary + suffix)))
+                    return true;
+            }
+            catch {
+                // An unreadable PATH entry is not our problem; keep looking.
+            }
+        }
+    }
+    return false;
+}
+export class ClaudeCodeAdapter {
+    id = 'claude-code';
+    label = 'Claude Code';
+    configPath() {
+        return join(homedir(), '.claude.json');
+    }
+    skillPath() {
+        return join(homedir(), '.claude', 'skills', SKILL_DIR_NAME, 'SKILL.md');
+    }
+    async detect() {
+        try {
+            return onPath('claude') || existsSync(this.configPath()) || existsSync(join(homedir(), '.claude'));
+        }
+        catch {
+            return false;
+        }
+    }
+    async install(entry) {
+        const path = this.configPath();
+        const config = readJsonFile(path) ?? {};
+        const backupPath = backupFile(path);
+        const servers = (typeof config.mcpServers === 'object' && config.mcpServers !== null && !Array.isArray(config.mcpServers)
+            ? config.mcpServers
+            : {});
+        const replacedExisting = SERVER_NAME in servers;
+        // Spread the existing entry so anything Claude Code (or the user) added to
+        // it that we don't know about survives the update.
+        const existing = (typeof servers[SERVER_NAME] === 'object' && servers[SERVER_NAME] !== null ? servers[SERVER_NAME] : {});
+        const existingHeaders = (typeof existing.headers === 'object' && existing.headers !== null ? existing.headers : {});
+        servers[SERVER_NAME] = {
+            ...existing,
+            type: 'http',
+            url: entry.url,
+            headers: { ...existingHeaders, Authorization: `Bearer ${entry.key}` },
+        };
+        config.mcpServers = servers;
+        writeJsonFile(path, config, { indent: existsSync(path) ? detectIndent(path) : 2 });
+        // Read back: this file has another writer, so a successful write is not
+        // the same as a config that says what we think it says.
+        const after = await this.status();
+        if (!after.installed || after.url !== entry.url || !after.hasKey) {
+            throw new Error(`The entry was written to ${path} but reading it back didn't show it. If Claude Code is running, quit it and run this again.`);
+        }
+        return { configPath: path, backupPath, method: 'config-file', replacedExisting };
+    }
+    async status() {
+        const path = this.configPath();
+        const config = readJsonFile(path);
+        if (!config)
+            return { installed: false, configPath: path, url: null, hasKey: false };
+        const servers = config.mcpServers;
+        const entry = servers?.[SERVER_NAME];
+        if (!entry)
+            return { installed: false, configPath: path, url: null, hasKey: false };
+        const url = typeof entry.url === 'string' ? entry.url : null;
+        const headers = (entry.headers ?? {});
+        const auth = typeof headers.Authorization === 'string' ? headers.Authorization : '';
+        const hasKey = /^Bearer\s+\S+/i.test(auth);
+        let problem;
+        if (!url)
+            problem = 'The entry has no url.';
+        else if (!hasKey)
+            problem = 'The entry has no Authorization header, so gated tools will be refused.';
+        else if (entry.type !== 'http')
+            problem = `The entry's type is "${String(entry.type)}", expected "http".`;
+        return { installed: true, configPath: path, url, hasKey, ...(problem ? { problem } : {}) };
+    }
+    async uninstall() {
+        const path = this.configPath();
+        const config = readJsonFile(path);
+        if (!config)
+            return false;
+        const servers = config.mcpServers;
+        if (!servers || !(SERVER_NAME in servers))
+            return false;
+        backupFile(path);
+        delete servers[SERVER_NAME];
+        writeJsonFile(path, config, { indent: detectIndent(path) });
+        return true;
+    }
+    async installSkill(markdown) {
+        const path = this.skillPath();
+        if (existsSync(path)) {
+            try {
+                if (readFileSync(path, 'utf8') === markdown)
+                    return { path, changed: false };
+            }
+            catch {
+                // Unreadable but present: fall through and replace it.
+            }
+        }
+        mkdirSync(dirname(path), { recursive: true });
+        writeFileSync(path, markdown, 'utf8');
+        return { path, changed: true };
+    }
+    async removeSkill() {
+        const path = this.skillPath();
+        if (!existsSync(path))
+            return false;
+        // Only our own folder, and only because we created it.
+        rmSync(dirname(path), { recursive: true, force: true });
+        return true;
+    }
+}

package/dist/adapters/index.js

@@ -0,0 +1,19 @@
+// The adapter registry.
+//
+// One entry today. Every other agent stays out of this list until it has been
+// installed for real, end to end, on a real machine — an agent that appears
+// here is an agent we're promising works.
+import { ClaudeCodeAdapter } from './claude-code.js';
+export const ADAPTERS = [new ClaudeCodeAdapter()];
+export function adapterById(id) {
+    return ADAPTERS.find((a) => a.id === id);
+}
+/** Adapters whose agent is actually on this machine. */
+export async function detectAdapters() {
+    const found = [];
+    for (const adapter of ADAPTERS) {
+        if (await adapter.detect())
+            found.push(adapter);
+    }
+    return found;
+}

package/dist/adapters/types.js

@@ -0,0 +1,8 @@
+// The shape every agent adapter fills in.
+//
+// Adding an agent is meant to be this file's worth of work and nothing else:
+// one module implementing `Adapter`, one entry in the registry, one row in the
+// project's Phase 0 table, and one real install before it's offered on the
+// site. Deliberately small, because the interesting part of supporting a new
+// agent is finding out how it actually behaves, not writing code.
+export {};

package/dist/commands/doctor.js

@@ -0,0 +1,118 @@
+// `noslopui doctor` — what's set up, what's wrong, and what to do about it.
+//
+// The rule for every line: if something is broken, say the one thing that
+// fixes it. A diagnostic that only reports a state leaves the user exactly
+// where they started.
+import { existsSync, readFileSync } from 'node:fs';
+import { checkServer, mcpUrl, origin } from '../lib/api.js';
+import { ADAPTERS } from '../adapters/index.js';
+import { ConfigUnreadableError, readJsonFile } from '../lib/json-file.js';
+import { SERVER_NAME } from '../adapters/claude-code.js';
+import { color, fail, hint, ok, say, warn } from '../lib/ui.js';
+/** Read back the configured key so we can ask the server whether it still works. */
+function configuredKey(configPath) {
+    try {
+        const config = readJsonFile(configPath);
+        const entry = config?.mcpServers?.[SERVER_NAME];
+        const headers = (entry?.headers ?? {});
+        const auth = typeof headers.Authorization === 'string' ? headers.Authorization : '';
+        const match = auth.match(/^Bearer\s+(\S+)$/i);
+        return match?.[1] ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+export async function doctor() {
+    let problems = 0;
+    say();
+    say(`${color.bold('noslopUI doctor')} ${color.dim(`— ${origin()}`)}`);
+    say();
+    say(color.bold('Server'));
+    const reach = await checkServer();
+    if (reach.reachable)
+        ok(`${mcpUrl()} — ${reach.detail}`);
+    else {
+        fail(reach.detail);
+        hint('If you are behind a proxy or VPN, that is the usual cause.');
+        problems++;
+    }
+    for (const adapter of ADAPTERS) {
+        say();
+        say(color.bold(adapter.label));
+        if (!(await adapter.detect())) {
+            say(`${color.dim('–')} ${color.dim('not installed on this machine')}`);
+            continue;
+        }
+        let status;
+        try {
+            status = await adapter.status();
+        }
+        catch (err) {
+            if (err instanceof ConfigUnreadableError) {
+                fail(err.message);
+                hint('Fix that file by hand — this tool will not overwrite a config it cannot read.');
+                problems++;
+                continue;
+            }
+            throw err;
+        }
+        if (!status.installed) {
+            warn('noslopUI is not set up here.');
+            hint('Run "npx noslopui init".');
+            problems++;
+        }
+        else {
+            ok(`Configured in ${status.configPath}`);
+            if (status.url !== mcpUrl()) {
+                warn(`The configured url is ${status.url}, but this CLI expects ${mcpUrl()}.`);
+                hint('Run "npx noslopui init" to update it.');
+                problems++;
+            }
+            if (status.problem) {
+                warn(status.problem);
+                hint('Run "npx noslopui init" to repair the entry.');
+                problems++;
+            }
+            const key = configuredKey(status.configPath);
+            if (key) {
+                const probe = await checkServer(key);
+                if (probe.keyState === 'ok') {
+                    ok('The configured key works.');
+                }
+                else if (probe.keyState === 'rejected') {
+                    fail(probe.keyDetail ?? 'The configured key was refused.');
+                    hint(`Create a new key at ${origin()}/account?tab=mcp, or run "npx noslopui login".`);
+                    problems++;
+                }
+            }
+        }
+        const skillPath = adapter.skillPath();
+        if (existsSync(skillPath)) {
+            let current = '';
+            try {
+                current = readFileSync(skillPath, 'utf8');
+            }
+            catch {
+                current = '';
+            }
+            if (current.includes('noslopui'))
+                ok(`Skill installed at ${skillPath}`);
+            else
+                warn(`${skillPath} exists but doesn't look like the noslopUI skill.`);
+        }
+        else {
+            warn('The skill is not installed.');
+            hint('Optional, but it is what makes "build me a website" use noslopUI at all. Run "npx noslopui init".');
+        }
+    }
+    say();
+    if (problems === 0) {
+        ok('Everything checks out.');
+        say();
+        return 0;
+    }
+    fail(`${problems} ${problems === 1 ? 'problem' : 'problems'} found.`);
+    say();
+    return 1;
+}