noslopui 0.0.1 → 0.2.0

package/dist/lib/api.js

@@ -0,0 +1,241 @@
+// Talking to noslopui.com: the device-code sign-in, and a health probe for
+// `doctor`. Everything here is plain fetch against documented endpoints.
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { CLI_VERSION } from './version.js';
+export const DEFAULT_ORIGIN = 'https://noslopui.com';
+/**
+ * Identify ourselves on every request. A tool that talks to a server should
+ * say what it is: it makes our own logs readable, and it gives anything
+ * sitting in front of the server (a CDN, a bot filter) something honest to
+ * recognise instead of a bare runtime default.
+ */
+export const USER_AGENT = `noslopui-cli/${CLI_VERSION} (+https://github.com/noslopUI/cli)`;
+/** Overridable so the flow can be exercised against a local server in tests. */
+export const origin = () => (process.env.NOSLOPUI_ORIGIN || DEFAULT_ORIGIN).replace(/\/$/, '');
+export const mcpUrl = () => `${origin()}/api/mcp`;
+export class ApiError extends Error {
+    status;
+    constructor(message, status) {
+        super(message);
+        this.status = status;
+        this.name = 'ApiError';
+    }
+}
+async function post(path, body) {
+    let res;
+    try {
+        res = await fetch(`${origin()}${path}`, {
+            method: 'POST',
+            headers: { 'content-type': 'application/json', 'user-agent': USER_AGENT },
+            body: JSON.stringify(body),
+        });
+    }
+    catch (err) {
+        throw new ApiError(`Could not reach ${origin()}. Check your connection, then run the command again.`);
+    }
+    const text = await res.text();
+    let json = null;
+    try {
+        json = JSON.parse(text);
+    }
+    catch {
+        // A proxy or captive portal answering instead of us.
+        throw new ApiError(`${origin()} returned something that isn't JSON (HTTP ${res.status}).`, res.status);
+    }
+    return { status: res.status, json };
+}
+export async function startSignIn(clientName, agents) {
+    const { status, json } = await post('/api/cli/auth/start', { clientName, agents });
+    if (status !== 201)
+        throw new ApiError(json?.message ?? `Sign-in could not be started (HTTP ${status}).`, status);
+    return json;
+}
+/** One poll. Everything that isn't "keep waiting" is thrown, with the server's own wording. */
+export async function pollSignIn(deviceCode) {
+    const { status, json } = await post('/api/cli/auth/poll', { deviceCode });
+    if (status === 200 && json?.status === 'approved')
+        return { done: true, keys: json.keys };
+    if (status === 200)
+        return { done: false }; // pending, or told to slow down
+    throw new ApiError(json?.message ?? `Sign-in failed (HTTP ${status}).`, status);
+}
+/**
+ * Waits for the browser half to finish. Polls on the interval the server asked
+ * for, and gives up when the code the user is looking at has expired.
+ */
+export async function waitForApproval(started, onTick) {
+    const deadline = Date.now() + started.expiresIn * 1000;
+    const intervalMs = Math.max(1, started.interval) * 1000;
+    while (Date.now() < deadline) {
+        await new Promise((r) => setTimeout(r, intervalMs));
+        const outcome = await pollSignIn(started.deviceCode);
+        if (outcome.done)
+            return outcome.keys;
+        onTick?.(Math.max(0, Math.round((deadline - Date.now()) / 1000)));
+    }
+    throw new ApiError('The code expired before it was approved. Run the command again to get a new one.');
+}
+const MCP_HEADERS = {
+    'content-type': 'application/json',
+    accept: 'application/json, text/event-stream',
+    'mcp-protocol-version': '2025-06-18',
+    'user-agent': USER_AGENT,
+};
+/** The last JSON-RPC message in a reply, whether it came as plain JSON or SSE-framed. */
+function rpcBody(text) {
+    const line = text.split(/\r?\n/).filter((l) => l.startsWith('data: ')).pop();
+    return JSON.parse(line ? line.slice(6) : text);
+}
+/**
+ * `doctor`'s probe: can we reach the MCP server, and does this key still work?
+ *
+ * Every MCP call needs a key or a sign-in, so without one the right answer is
+ * our own 401 pointing at the OAuth metadata — that's "reachable", and a
+ * challenge page or a proxy error is not. With a key it calls list_collections,
+ * the one tool that costs the account nothing: no trial clock, no fair-use count.
+ */
+export async function checkServer(key) {
+    let res;
+    const headers = { ...MCP_HEADERS };
+    if (key)
+        headers.authorization = `Bearer ${key}`;
+    try {
+        res = await fetch(mcpUrl(), {
+            method: 'POST',
+            headers,
+            body: JSON.stringify({
+                jsonrpc: '2.0',
+                id: 1,
+                method: key ? 'tools/call' : 'tools/list',
+                params: key ? { name: 'list_collections', arguments: {} } : {},
+            }),
+        });
+    }
+    catch {
+        return { reachable: false, detail: `Could not reach ${mcpUrl()}.` };
+    }
+    const text = await res.text();
+    if (res.status === 401) {
+        const ours = /resource_metadata=/.test(res.headers.get('www-authenticate') ?? '');
+        if (!ours)
+            return { reachable: false, detail: `${mcpUrl()} answered 401, but not in the way noslopUI does — something in between is answering.` };
+        if (!key)
+            return { reachable: true, detail: 'Server reachable, and asking for sign-in as it should.' };
+        let message = 'The configured key was refused.';
+        try {
+            message = rpcBody(text)?.error?.message ?? message;
+        }
+        catch { }
+        return { reachable: true, detail: 'Server reachable.', keyState: 'rejected', keyDetail: message.split('. ')[0] };
+    }
+    if (!res.ok)
+        return { reachable: false, detail: `${mcpUrl()} answered HTTP ${res.status}.` };
+    let json;
+    try {
+        json = rpcBody(text);
+    }
+    catch {
+        return { reachable: false, detail: 'The server answered with something unreadable.' };
+    }
+    if (!key)
+        return { reachable: true, detail: `${(json?.result?.tools ?? []).length} tools available.` };
+    if (json?.result?.isError === true) {
+        // The server writes these for an agent to relay; they're already the right
+        // words for a person, so pass them through rather than inventing our own.
+        const body = json?.result?.content?.[0]?.text ?? '';
+        return { reachable: true, detail: 'Server reachable.', keyState: 'rejected', keyDetail: body.split('. ')[0] };
+    }
+    return { reachable: true, detail: 'Server reachable.', keyState: 'ok', keyDetail: 'Key accepted.' };
+}
+/**
+ * One MCP tool call — what the terminal commands are built on, so the CLI and
+ * an agent can never see different things, and every gate (plan, trial,
+ * fair use) is the server's.
+ */
+export async function callTool(key, name, args = {}) {
+    let res;
+    try {
+        res = await fetch(mcpUrl(), {
+            method: 'POST',
+            headers: { ...MCP_HEADERS, authorization: `Bearer ${key}` },
+            body: JSON.stringify({ jsonrpc: '2.0', id: 1, method: 'tools/call', params: { name, arguments: args } }),
+        });
+    }
+    catch {
+        throw new ApiError(`Could not reach ${origin()}. Check your connection, then run the command again.`);
+    }
+    const text = await res.text();
+    let json;
+    try {
+        json = rpcBody(text);
+    }
+    catch {
+        throw new ApiError(`${origin()} returned something that isn't JSON (HTTP ${res.status}).`, res.status);
+    }
+    if (res.status === 401) {
+        throw new ApiError(`${json?.error?.message ?? 'Not signed in.'}\n  Run "npx noslopui login" to sign in again.`, 401);
+    }
+    if (json?.error)
+        throw new ApiError(json.error.message ?? `The server refused the call (${json.error.code}).`);
+    const out = json?.result?.content?.[0]?.text ?? '';
+    let data = null;
+    try {
+        data = JSON.parse(out);
+    }
+    catch { }
+    return { isError: json?.result?.isError === true, text: out, data };
+}
+export async function whoami(key) {
+    let res;
+    try {
+        res = await fetch(`${origin()}/api/cli/me`, { headers: { authorization: `Bearer ${key}`, 'user-agent': USER_AGENT } });
+    }
+    catch {
+        throw new ApiError(`Could not reach ${origin()}. Check your connection, then run the command again.`);
+    }
+    let json = null;
+    try {
+        json = await res.json();
+    }
+    catch {
+        throw new ApiError(`${origin()} returned something that isn't JSON (HTTP ${res.status}).`, res.status);
+    }
+    if (!res.ok)
+        throw new ApiError(json?.message ?? `HTTP ${res.status}`, res.status);
+    return json;
+}
+/**
+ * The workflow file. Fetched from the site, because the site is where it's
+ * assembled — the same text the MCP server sends as its instructions, so the
+ * two can never disagree.
+ *
+ * The copy shipped in this package is a fallback for an unreachable site, not
+ * an equal: it's only as fresh as the last publish, so the caller says so.
+ */
+export async function fetchSkill() {
+    try {
+        const res = await fetch(`${origin()}/skill/SKILL.md`, { headers: { 'user-agent': USER_AGENT } });
+        if (res.ok) {
+            const text = await res.text();
+            if (text.startsWith('---'))
+                return { markdown: text, source: 'server' };
+        }
+    }
+    catch {
+        // Fall through to the bundled copy.
+    }
+    const bundled = bundledSkill();
+    if (bundled)
+        return { markdown: bundled, source: 'bundled' };
+    throw new ApiError(`Could not download the skill from ${origin()}, and this package has no copy to fall back on.`);
+}
+function bundledSkill() {
+    try {
+        // dist/lib/api.js → the package root.
+        return readFileSync(fileURLToPath(new URL('../../SKILL.md', import.meta.url)), 'utf8');
+    }
+    catch {
+        return null;
+    }
+}

package/dist/lib/json-file.js

@@ -0,0 +1,103 @@
+// Reading and writing a config file that belongs to somebody else.
+//
+// The rules this file exists to enforce, in order of how badly they'd hurt:
+//
+//   1. If the file doesn't parse, STOP. Never overwrite a config we couldn't
+//      read — `~/.claude.json` carries onboarding state, project history and
+//      every other MCP server the user has set up. Rewriting it from scratch
+//      because we couldn't parse it would be the worst thing this tool could
+//      possibly do.
+//   2. Back up before the first write, and tell the user where the backup is.
+//   3. Merge. Only our own key changes; every sibling is written back exactly
+//      as it was read.
+//   4. Write atomically — a temp file in the same directory, then rename — so
+//      a crash or a full disk can't leave a half-written config behind.
+import { copyFileSync, existsSync, mkdirSync, readFileSync, renameSync, writeFileSync, unlinkSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+export class ConfigUnreadableError extends Error {
+    path;
+    cause_;
+    constructor(path, cause_) {
+        const why = cause_ instanceof Error && cause_.message ? ` (${cause_.message})` : '';
+        super(`${path} couldn't be read safely${why}, so it was left untouched.`);
+        this.path = path;
+        this.cause_ = cause_;
+        this.name = 'ConfigUnreadableError';
+    }
+}
+/** Reads a JSON object, or `null` when the file simply isn't there yet. */
+export function readJsonFile(path) {
+    if (!existsSync(path))
+        return null;
+    let raw;
+    try {
+        raw = readFileSync(path, 'utf8');
+    }
+    catch (err) {
+        throw new ConfigUnreadableError(path, err);
+    }
+    if (!raw.trim())
+        return {};
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (err) {
+        throw new ConfigUnreadableError(path, err);
+    }
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+        throw new ConfigUnreadableError(path, new Error('top level is not an object'));
+    }
+    return parsed;
+}
+/**
+ * A timestamped copy beside the original: `.claude.json.noslopui-backup-<ts>`.
+ * Beside it rather than in a temp directory so the user can find it without
+ * being told twice, and timestamped so a second run can't clobber the first
+ * backup — which would defeat the point of having one.
+ */
+export function backupFile(path) {
+    if (!existsSync(path))
+        return null;
+    const stamp = new Date().toISOString().replace(/[:.]/g, '-');
+    const backup = `${path}.noslopui-backup-${stamp}`;
+    copyFileSync(path, backup);
+    return backup;
+}
+/** Write via a temp file in the same directory, then rename over the target. */
+export function writeJsonFile(path, value, { indent = 2 } = {}) {
+    writeTextFile(path, `${JSON.stringify(value, null, indent)}\n`);
+}
+/** The same atomic write for a file that isn't JSON (Codex's config.toml). */
+export function writeTextFile(path, text) {
+    const dir = dirname(path);
+    mkdirSync(dir, { recursive: true });
+    const temp = join(dir, `.noslopui-write-${process.pid}-${Date.now()}.tmp`);
+    try {
+        writeFileSync(temp, text, 'utf8');
+        renameSync(temp, path);
+    }
+    catch (err) {
+        try {
+            if (existsSync(temp))
+                unlinkSync(temp);
+        }
+        catch {
+            // The rename is what matters; a stray temp file is not worth a second error.
+        }
+        throw err;
+    }
+}
+/** Indentation of an existing file, so we write it back the way we found it. */
+export function detectIndent(path) {
+    try {
+        const raw = readFileSync(path, 'utf8');
+        const match = raw.match(/\n(\s+)"/);
+        if (match?.[1] && !match[1].includes('\t'))
+            return match[1].length;
+    }
+    catch {
+        // Not worth failing a write over; fall through to the default.
+    }
+    return 2;
+}

package/dist/lib/paths.js

@@ -0,0 +1,41 @@
+// Where agents keep their files. Every path starts from the home directory or
+// an environment variable the OS sets for it, never a hardcoded user folder, so
+// the tests can point all of them at a throwaway directory.
+import { existsSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { delimiter, join } from 'node:path';
+export const home = () => homedir();
+/** `%APPDATA%` on Windows (Roaming), where Electron apps and Devin keep user config. */
+export function appData() {
+    return process.env.APPDATA || join(homedir(), 'AppData', 'Roaming');
+}
+/** `$XDG_CONFIG_HOME`, or `~/.config` — the Linux/macOS home for CLI config. */
+export function xdgConfig() {
+    return process.env.XDG_CONFIG_HOME || join(homedir(), '.config');
+}
+/** Where a VS Code-family app keeps its user settings, per OS. */
+export function vscodeUserDir(product = 'Code') {
+    if (process.platform === 'win32')
+        return join(appData(), product, 'User');
+    if (process.platform === 'darwin')
+        return join(homedir(), 'Library', 'Application Support', product, 'User');
+    return join(xdgConfig(), product, 'User');
+}
+/** The skills folder several agents share: Codex, Cursor, OpenCode, VS Code. */
+export const sharedSkillPath = () => join(homedir(), '.agents', 'skills', 'noslopui', 'SKILL.md');
+export 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;
+}

package/dist/lib/session.js

@@ -0,0 +1,49 @@
+// The CLI's own sign-in — what `noslopui search`, `get` and `whoami` use.
+//
+// It's an ordinary noslopUI API key, issued for the agent id `cli` by the same
+// browser approval `init` uses, and named after this machine on the account
+// page, where it can be revoked like any other. It's stored in the user's
+// config folder with owner-only permissions, and never printed in full.
+//
+// Agent keys stay in each agent's own config; this file is only the CLI's.
+import { chmodSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { appData, xdgConfig } from './paths.js';
+export function sessionPath() {
+    const dir = process.platform === 'win32' ? join(appData(), 'noslopui') : join(xdgConfig(), 'noslopui');
+    return join(dir, 'credentials.json');
+}
+export function readSession() {
+    if (process.env.NOSLOPUI_API_KEY)
+        return { key: process.env.NOSLOPUI_API_KEY, savedAt: 'env' };
+    const path = sessionPath();
+    if (!existsSync(path))
+        return null;
+    try {
+        const parsed = JSON.parse(readFileSync(path, 'utf8'));
+        return typeof parsed?.key === 'string' && parsed.key ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
+export function saveSession(key) {
+    const path = sessionPath();
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, `${JSON.stringify({ key, savedAt: new Date().toISOString() }, null, 2)}\n`, { encoding: 'utf8', mode: 0o600 });
+    try {
+        // mode only applies when the file is created; tighten an existing one too.
+        chmodSync(path, 0o600);
+    }
+    catch {
+        // Windows ignores POSIX modes; the file is under the user's own profile.
+    }
+    return path;
+}
+export function clearSession() {
+    const path = sessionPath();
+    if (!existsSync(path))
+        return false;
+    rmSync(path, { force: true });
+    return true;
+}

package/dist/lib/skill-file.js

@@ -0,0 +1,26 @@
+// Writing and removing the skill file. Shared by every adapter, because several
+// agents read the same folder (`~/.agents/skills/` is read by Codex, Cursor,
+// OpenCode and VS Code alike) — one copy there serves all of them.
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+export function installSkillAt(path, markdown) {
+    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 };
+}
+export function removeSkillAt(path) {
+    if (!existsSync(path))
+        return false;
+    // Only our own folder (…/skills/noslopui/), and only because we created it.
+    rmSync(dirname(path), { recursive: true, force: true });
+    return true;
+}

package/dist/lib/ui.js

@@ -0,0 +1,75 @@
+// Terminal output and prompts. No dependencies on purpose: this package is run
+// with `npx`, so every dependency is something the user waits to download
+// before anything happens.
+import { createInterface } from 'node:readline/promises';
+import { hostname } from 'node:os';
+import { stdin, stdout } from 'node:process';
+const useColor = stdout.isTTY && !process.env.NO_COLOR && process.env.TERM !== 'dumb';
+const wrap = (open, close) => (s) => (useColor ? `${open}${s}${close}` : s);
+export const color = {
+    bold: wrap('\u001b[1m', '\u001b[22m'),
+    dim: wrap('\u001b[2m', '\u001b[22m'),
+    green: wrap('\u001b[32m', '\u001b[39m'),
+    yellow: wrap('\u001b[33m', '\u001b[39m'),
+    red: wrap('\u001b[31m', '\u001b[39m'),
+    cyan: wrap('\u001b[36m', '\u001b[39m'),
+};
+export const say = (line = '') => stdout.write(`${line}\n`);
+export const step = (line) => say(`${color.cyan('›')} ${line}`);
+export const ok = (line) => say(`${color.green('✔')} ${line}`);
+export const warn = (line) => say(`${color.yellow('!')} ${line}`);
+export const fail = (line) => say(`${color.red('✘')} ${line}`);
+export const hint = (line) => say(`  ${color.dim(line)}`);
+/** True when there's a human to answer a prompt. */
+export const interactive = () => Boolean(stdin.isTTY && stdout.isTTY);
+/**
+ * A key is only ever shown like this. `npx noslopui init` runs in a terminal
+ * people screenshot and paste into issues, and the key is the account.
+ */
+export function maskKey(key) {
+    return key.length <= 11 ? '…' : `${key.slice(0, 11)}…`;
+}
+export async function confirm(question, fallback) {
+    if (!interactive())
+        return fallback;
+    const rl = createInterface({ input: stdin, output: stdout });
+    try {
+        const suffix = fallback ? 'Y/n' : 'y/N';
+        const answer = (await rl.question(`${color.cyan('?')} ${question} ${color.dim(`(${suffix})`)} `)).trim().toLowerCase();
+        if (!answer)
+            return fallback;
+        return answer === 'y' || answer === 'yes';
+    }
+    finally {
+        rl.close();
+    }
+}
+/** Wait for Enter, or return immediately when nobody's watching. */
+export async function pressEnter(question) {
+    if (!interactive())
+        return;
+    const rl = createInterface({ input: stdin, output: stdout });
+    try {
+        await rl.question(`${color.cyan('?')} ${question} `);
+    }
+    finally {
+        rl.close();
+    }
+}
+/**
+ * A name for this machine, used to label the key on the account page and on
+ * the approval screen. The hostname only — never a username, path or anything
+ * else that would say more about the person than "which laptop is this".
+ * `os.hostname()` rather than $HOSTNAME, which isn't exported on every shell.
+ */
+export function machineLabel() {
+    let raw = '';
+    try {
+        raw = hostname();
+    }
+    catch {
+        raw = '';
+    }
+    const cleaned = (raw.trim().split('.')[0] ?? '').replace(/[^\w .-]/g, '');
+    return cleaned.slice(0, 40) || 'this machine';
+}

package/dist/lib/version.js

@@ -0,0 +1,3 @@
+// One place for the version, so package.json, --version and the User-Agent
+// can't disagree. Checked against package.json by a test.
+export const CLI_VERSION = '0.2.0';

package/package.json

@@ -1,25 +1,48 @@
 {
   "name": "noslopui",
-  "version": "0.0.1",
-  "description": "Connect your coding agent to noslopUI's hand-crafted UI catalog. Installer coming soon.",
-  "homepage": "https://noslopui.com/mcp",
+  "version": "0.2.0",
+  "description": "Connect your coding agent to noslopUI \u2014 hand-crafted UI components and portable design systems, over MCP.",
+  "keywords": [
+    "mcp",
+    "claude-code",
+    "ui",
+    "design-system",
+    "components",
+    "cli"
+  ],
+  "homepage": "https://noslopui.com",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/noslopUI/cli.git"
+  },
+  "bugs": {
+    "url": "https://github.com/noslopUI/cli/issues"
+  },
   "license": "MIT",
+  "type": "module",
   "bin": {
-    "noslopui": "bin/noslopui.js"
+    "noslopui": "dist/index.js"
   },
   "files": [
-    "bin"
+    "dist",
+    "SKILL.md",
+    "README.md",
+    "LICENSE"
   ],
   "engines": {
-    "node": ">=18"
+    "node": ">=20.10"
   },
-  "keywords": [
-    "noslopui",
-    "mcp",
-    "ui",
-    "design-system",
-    "claude-code",
-    "cursor",
-    "codex"
-  ]
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "build:test": "tsc -p tsconfig.test.json",
+    "test": "npm run build:test && node scripts/run-tests.mjs",
+    "typecheck": "tsc -p tsconfig.test.json --noEmit",
+    "sync-skill": "node scripts/sync-skill.mjs",
+    "check-skill": "node scripts/sync-skill.mjs --check",
+    "prepack": "npm run build"
+  },
+  "devDependencies": {
+    "@types/node": "^24.3.0",
+    "typescript": "^5.9.2"
+  }
 }

package/bin/noslopui.js

@@ -1,3 +0,0 @@
-#!/usr/bin/env node
-console.log('The noslopUI installer is coming soon.');
-console.log('Until then, set up by hand: https://noslopui.com/mcp');