noslopui 0.0.1 → 0.2.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,119 @@
 # 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 the agents on your machine, signs you in once through the browser, adds the MCP server to each agent's **user-level** config, and installs the workflow skill. Restart your agents and ask one 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`.
+
+## Supported agents
+
+| Agent | `--agent` | Config it writes | Skill it installs |
+|---|---|---|---|
+| Claude Code | `claude-code` | `~/.claude.json` | `~/.claude/skills/noslopui/` |
+| Codex | `codex` | `~/.codex/config.toml` | `~/.agents/skills/noslopui/` |
+| Cursor | `cursor` | `~/.cursor/mcp.json` | `~/.agents/skills/noslopui/` |
+| VS Code (Copilot) | `vscode` | your user `mcp.json` ¹ | `~/.agents/skills/noslopui/` |
+| Devin Desktop | `devin` | `~/.config/devin/mcp_config.json` ² | `~/.codeium/windsurf/skills/noslopui/` |
+| Windsurf (Cascade) | `windsurf` | `~/.codeium/windsurf/mcp_config.json` | `~/.codeium/windsurf/skills/noslopui/` |
+| OpenCode | `opencode` | `~/.config/opencode/opencode.json` | `~/.agents/skills/noslopui/` |
+| Antigravity | `antigravity` | `~/.gemini/config/mcp_config.json` | `~/.gemini/config/skills/noslopui/` |
+
+¹ `%APPDATA%\Code\User\mcp.json` on Windows, `~/Library/Application Support/Code/User/mcp.json` on macOS, `~/.config/Code/User/mcp.json` on Linux.
+² `%APPDATA%\devin\mcp_config.json` on Windows. Windsurf became Devin Desktop in June 2026: its default agent (Devin Local) reads this file, the older Cascade agent reads the Windsurf one, so they're set up separately.
+
+Every path and field comes from that agent's own documentation. Several agents read the same skills folder, so one copy there serves all of them.
+
+Anything else that speaks MCP over HTTP can be connected by hand — add `https://noslopui.com/api/mcp` and sign in when it asks. Steps for each client: [noslopui.com/mcp](https://noslopui.com/mcp).
+
+## Commands
+
+**Set up**
+
+| | |
+|---|---|
+| `npx noslopui init` | Set up your agents: one sign-in, then the server and the skill for each |
+| `npx noslopui doctor` | Check what's set up, and say what to do about anything that isn't |
+| `npx noslopui update` | Re-download the skill |
+| `npx noslopui skill` | Install only the skill, for an agent you connected by hand (`--agent <id>`) |
+| `npx noslopui remove` | Take the noslopUI server back out |
+
+**Account**
+
+| | |
+|---|---|
+| `npx noslopui login` | Sign this CLI in, for the catalog commands below |
+| `npx noslopui login --agent <id>` | A fresh key for an agent that's already set up |
+| `npx noslopui whoami` | The account and plan this CLI is signed in to |
+| `npx noslopui logout` | Forget this CLI's sign-in |
+
+**Catalog**
+
+| | |
+|---|---|
+| `npx noslopui search <query>` | Search components and blocks (`--tag style:editorial`, `--framework`, `--limit`) |
+| `npx noslopui get <id>` | Print a component's code, or `--write src/Hero.tsx` (`--format tsx\|html\|vue`) |
+| `npx noslopui prompt <id>` | Print a component's AI-prompt version |
+| `npx noslopui design-systems [query]` | Search design systems (`--tag theme:dark`) |
+| `npx noslopui design-system <id>` | Print a DESIGN.md, or `--write DESIGN.md` |
+| `npx noslopui collections` | Your saved collections |
+| `npx noslopui collection <name>` | What's in one |
+
+The catalog commands call the same MCP tools your agent does, with the same access: search and collections are free on every account; code, prompts and DESIGN.md files need a paid plan or the account's free trial. Output is only the thing you asked for, so `get <id> > Hero.tsx` works; `--json` gives the raw result.
+
+Options: `--agent <id>` (repeatable), `--no-skill`, `--no-browser`, `--key <key>`, `--json`, `--force`, `-y/--yes`.
+
+## What it does to your machine
+
+It edits your agents' user-level config, and nothing else:
+
+- Adds one entry, `noslopui`, to each agent you choose, in the file listed above.
+- **Copies the file first.** The backup sits next to the original as `<file>.noslopui-backup-<timestamp>`, and its path is printed.
+- **Never touches another server's entry**, or anything else in the file. Codex's `config.toml` is edited table by table: every line outside `[mcp_servers.noslopui]` is left byte for byte as it was.
+- **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**, or if the `noslopui` entry is written in a form it doesn't recognise. It will not overwrite a file it couldn't read — that file is the only copy of your setup.
+- Writes the skill to the folders listed above.
+- Saves the CLI's own sign-in in `~/.config/noslopui/credentials.json` (`%APPDATA%\noslopui\` on Windows), readable only by you.
+
+`remove` takes the entry back out and leaves everything else, including the skill unless you pass `--skill` — and even then it keeps a skill folder another configured agent still reads. 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 keys
+
+`init` issues one key per agent, named after the agent and this machine, so you can tell them apart on the account page and revoke one without breaking the others — plus one for the CLI itself if it isn't signed in yet. Keys are written to each agent's config and nowhere else; this tool never prints one 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. `NOSLOPUI_API_KEY` does the same for the catalog commands.
+
+## 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 its facts in `src/adapters/json-agents.ts` (or its own module, if its config isn't JSON), one line in the registry, the same id in the server's `CLI_AGENTS`, and a row in `test/agents.test.ts`.
+
+## Licence
+
+MIT

package/SKILL.md

@@ -0,0 +1,245 @@
+---
+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, 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 the noslopUI tools aren't available: the user runs
+`npx noslopui@latest init`, or adds `https://noslopui.com/api/mcp` in their
+agent and signs in when it asks (steps for each agent: `noslopui.com/mcp`).
+Every call runs as the user's account. Search, metadata and collections are
+free on every account. Code, prompts and DESIGN.md files need a paid plan or
+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**.
+
+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 account rides on the connection (a key or a sign-in, sent as the
+`Authorization` header), so no tool takes a credential 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,46 @@
+// 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 { join } from 'node:path';
+import { JsonConfigAdapter, SERVER_NAME } from './json-adapter.js';
+import { home } from '../lib/paths.js';
+import { installSkillAt } from '../lib/skill-file.js';
+export { SERVER_NAME };
+export class ClaudeCodeAdapter extends JsonConfigAdapter {
+    constructor() {
+        super({
+            id: 'claude-code',
+            label: 'Claude Code',
+            configPath: () => join(home(), '.claude.json'),
+            container: 'mcpServers',
+            urlField: 'url',
+            fixed: { type: 'http' },
+            detectPaths: () => [join(home(), '.claude.json'), join(home(), '.claude')],
+            detectBinaries: ['claude'],
+            skillPath: () => join(home(), '.claude', 'skills', 'noslopui', 'SKILL.md'),
+            readBackHint: 'If Claude Code is running, quit it and run this again.',
+        });
+    }
+    skillPath() {
+        return join(home(), '.claude', 'skills', 'noslopui', 'SKILL.md');
+    }
+    async installSkill(markdown) {
+        return installSkillAt(this.skillPath(), markdown);
+    }
+}

package/dist/adapters/codex.js

@@ -0,0 +1,196 @@
+// Codex (the CLI, the IDE extension and the app share one config).
+//
+// User-level MCP servers live in `~/.codex/config.toml`, one table each:
+//
+//   [mcp_servers.noslopui]
+//   url = "https://noslopui.com/api/mcp"
+//   http_headers = { "Authorization" = "Bearer nsui_…" }
+//
+// Checked against learn.chatgpt.com/docs/extend/mcp (2026-09-21): `url`,
+// `http_headers` (a static map) and `bearer_token_env_var` are all supported.
+// We write the static header, like every other agent, so the key lives in the
+// config and nowhere else — an env var would have to be set in every shell
+// Codex is ever started from, which is exactly the fragility this tool exists
+// to remove.
+//
+// NO TOML PARSER. This package has zero runtime dependencies, so instead of
+// parsing the file we edit one table and leave every other byte as it was:
+// find `[mcp_servers.noslopui]` (and any `[mcp_servers.noslopui.*]`
+// sub-tables), replace our keys in it, keep any other key the user put there.
+// If our server appears in a form we don't recognise — an inline table under
+// `[mcp_servers]`, or a dotted key — we stop and say so, rather than guess.
+// Skills: Codex reads user-level skills from ~/.agents/skills
+// (learn.chatgpt.com/docs/build-skills).
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { backupFile, ConfigUnreadableError, writeTextFile } from '../lib/json-file.js';
+import { home, onPath, sharedSkillPath } from '../lib/paths.js';
+import { installSkillAt, removeSkillAt } from '../lib/skill-file.js';
+import { SERVER_NAME } from './json-adapter.js';
+/** `[mcp_servers.noslopui]` or one of its sub-tables, in any quoting TOML allows. */
+const OUR_HEADER = new RegExp(`^\\s*\\[\\s*mcp_servers\\s*\\.\\s*(?:${SERVER_NAME}|"${SERVER_NAME}"|'${SERVER_NAME}')\\s*(\\]|\\.)`);
+/** `[mcp_servers.noslopui.http_headers]` — replaced by our inline map, or TOML would see the key twice. */
+const OUR_HEADERS_SUBTABLE = new RegExp(`^\\s*\\[\\s*mcp_servers\\s*\\.\\s*["']?${SERVER_NAME}["']?\\s*\\.\\s*["']?http_headers["']?\\s*\\]`);
+const ANY_HEADER = /^\s*\[/;
+/** Our server declared some other way: `noslopui = {…}` or `mcp_servers.noslopui.url = …`. */
+const FOREIGN_FORM = new RegExp(`^\\s*(?:mcp_servers\\s*\\.\\s*)?["']?${SERVER_NAME}["']?\\s*(?:=|\\.)`);
+/** Keys we own inside our table; every other key the user wrote there is kept. */
+const OUR_KEYS = /^\s*(url|http_headers|bearer_token_env_var)\s*=/;
+const tomlString = (s) => `"${s.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`;
+function parse(path) {
+    if (!existsSync(path))
+        return null;
+    let raw;
+    try {
+        raw = readFileSync(path, 'utf8');
+    }
+    catch (err) {
+        throw new ConfigUnreadableError(path, err);
+    }
+    const eol = raw.includes('\r\n') ? '\r\n' : '\n';
+    const lines = raw.split(/\r?\n/);
+    const blocks = [];
+    let open = null;
+    lines.forEach((line, i) => {
+        if (ANY_HEADER.test(line)) {
+            if (open !== null) {
+                blocks.push([open, i]);
+                open = null;
+            }
+            if (OUR_HEADER.test(line))
+                open = i;
+            return;
+        }
+        if (open === null && !line.trim().startsWith('#') && FOREIGN_FORM.test(line)) {
+            throw new ConfigUnreadableError(path, new Error(`"${SERVER_NAME}" is declared in a form this tool doesn't edit`));
+        }
+    });
+    if (open !== null)
+        blocks.push([open, lines.length]);
+    return { lines, eol, blocks };
+}
+function ourLines(parsed) {
+    return parsed.blocks.flatMap(([a, b]) => parsed.lines.slice(a, b));
+}
+export class CodexAdapter {
+    id = 'codex';
+    label = 'Codex';
+    configPath() {
+        return join(home(), '.codex', 'config.toml');
+    }
+    skillPath() {
+        return sharedSkillPath();
+    }
+    async detect() {
+        try {
+            return onPath('codex') || existsSync(join(home(), '.codex'));
+        }
+        catch {
+            return false;
+        }
+    }
+    async install(entry) {
+        const path = this.configPath();
+        const parsed = parse(path);
+        const backupPath = backupFile(path);
+        const lines = parsed?.lines ?? [];
+        const eol = parsed?.eol ?? '\n';
+        const blocks = parsed?.blocks ?? [];
+        const replacedExisting = blocks.length > 0;
+        // Keys the user added to our main table (enabled, tool_timeout_sec, …)
+        // and any sub-table other than http_headers survive the rewrite.
+        const kept = [];
+        const keptSubtables = [];
+        for (const [a, b] of blocks) {
+            const header = lines[a] ?? '';
+            const body = lines.slice(a + 1, b);
+            if (OUR_HEADERS_SUBTABLE.test(header))
+                continue;
+            if (/\]\s*(#.*)?$/.test(header) && new RegExp(`${SERVER_NAME}["']?\\s*\\]`).test(header)) {
+                kept.push(...body.filter((l) => !OUR_KEYS.test(l)));
+            }
+            else {
+                keptSubtables.push(header, ...body);
+            }
+        }
+        while (kept.length && !kept[kept.length - 1].trim())
+            kept.pop();
+        const block = [
+            `[mcp_servers.${SERVER_NAME}]`,
+            `url = ${tomlString(entry.url)}`,
+            `http_headers = { "Authorization" = ${tomlString(`Bearer ${entry.key}`)} }`,
+            ...kept,
+            '',
+            ...keptSubtables,
+        ];
+        while (block.length && !block[block.length - 1].trim())
+            block.pop();
+        let out;
+        if (blocks.length) {
+            const first = blocks[0][0];
+            const inBlocks = (i) => blocks.some(([a, b]) => i >= a && i < b);
+            out = [...lines.slice(0, first).filter((_, i) => !inBlocks(i)), ...block, '', ...lines.slice(first).filter((_, j) => !inBlocks(first + j))];
+        }
+        else {
+            const body = [...lines];
+            while (body.length && !body[body.length - 1].trim())
+                body.pop();
+            out = body.length ? [...body, '', ...block] : [...block];
+        }
+        while (out.length && !out[out.length - 1].trim())
+            out.pop();
+        writeTextFile(path, out.join(eol) + eol);
+        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.`);
+        }
+        return { configPath: path, backupPath, method: 'config-file', replacedExisting };
+    }
+    async status() {
+        const path = this.configPath();
+        const parsed = parse(path);
+        if (!parsed || !parsed.blocks.length)
+            return { installed: false, configPath: path, url: null, hasKey: false };
+        const text = ourLines(parsed).join('\n');
+        const url = text.match(/^\s*url\s*=\s*"([^"]*)"/m)?.[1] ?? null;
+        const hasKey = /"?Authorization"?\s*=\s*"Bearer\s+\S+"/i.test(text) || /^\s*bearer_token_env_var\s*=/m.test(text);
+        let problem;
+        if (!url)
+            problem = 'The entry has no url.';
+        else if (!hasKey)
+            problem = 'The entry has no Authorization header, so Codex will be asked to sign in ("codex mcp login noslopui").';
+        return { installed: true, configPath: path, url, hasKey, ...(problem ? { problem } : {}) };
+    }
+    async configuredKey() {
+        try {
+            const parsed = parse(this.configPath());
+            if (!parsed)
+                return null;
+            return ourLines(parsed).join('\n').match(/"?Authorization"?\s*=\s*"Bearer\s+([^"\s]+)"/i)?.[1] ?? null;
+        }
+        catch {
+            return null;
+        }
+    }
+    async uninstall() {
+        const path = this.configPath();
+        const parsed = parse(path);
+        if (!parsed || !parsed.blocks.length)
+            return false;
+        backupFile(path);
+        const inBlocks = (i) => parsed.blocks.some(([a, b]) => i >= a && i < b);
+        const out = parsed.lines.filter((_, i) => !inBlocks(i));
+        // Collapse the blank lines our table leaves behind.
+        const tidy = out.filter((l, i) => l.trim() || (out[i - 1]?.trim() ?? '') !== '');
+        while (tidy.length && !tidy[tidy.length - 1].trim())
+            tidy.pop();
+        writeTextFile(path, tidy.length ? tidy.join(parsed.eol) + parsed.eol : '');
+        return true;
+    }
+    async installSkill(markdown) {
+        return installSkillAt(this.skillPath(), markdown);
+    }
+    async removeSkill() {
+        return removeSkillAt(this.skillPath());
+    }
+}

package/dist/adapters/index.js

@@ -0,0 +1,30 @@
+// The adapter registry — every agent `npx noslopui init` can set up.
+//
+// The server keeps the same list (CLI_AGENTS in the website's lib/cli-auth.ts)
+// and refuses a key for any agent not on it, so the two change together.
+// Order is the order they're offered in.
+import { ClaudeCodeAdapter } from './claude-code.js';
+import { CodexAdapter } from './codex.js';
+import { antigravity, cursor, devin, opencode, vscode, windsurf } from './json-agents.js';
+export const ADAPTERS = [
+    new ClaudeCodeAdapter(),
+    new CodexAdapter(),
+    cursor(),
+    vscode(),
+    devin(),
+    windsurf(),
+    opencode(),
+    antigravity(),
+];
+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;
+}