@sx4im/skillcheck 0.1.1 → 0.2.1

package/docs/skillcheck-cloud.md

@@ -0,0 +1,111 @@
+# Skillcheck Cloud setup
+
+Use this when you want users to install the CLI and run checks without configuring model-provider secrets locally.
+
+## Architecture
+
+```text
+skillcheck CLI
+  -> Skillcheck Cloud API
+  -> model provider
+
+Dashboard
+  -> user signs up
+  -> user creates a Skillcheck token
+  -> token is stored hashed in your database
+```
+
+The CLI only needs:
+
+```bash
+skillcheck setup
+```
+
+The setup wizard asks for:
+
+```bash
+https://api.yourdomain.com/v1
+```
+
+For token-gated private beta, users can additionally set:
+
+```bash
+export SKILLCHECK_TOKEN=sk_live_...
+```
+
+If you want public free trials, the proxy can allow anonymous requests with strict rate limits and no token.
+
+## API contract
+
+The CLI expects an OpenAI-compatible endpoint:
+
+```http
+POST /v1/chat/completions
+Authorization: Bearer <skillcheck-token>
+Content-Type: application/json
+```
+
+Response should match OpenAI chat completions enough for the `openai` Node SDK:
+
+```json
+{
+  "id": "chatcmpl_...",
+  "object": "chat.completion",
+  "created": 1780000000,
+  "model": "your-model",
+  "choices": [
+    {
+      "index": 0,
+      "message": {
+        "role": "assistant",
+        "content": "..."
+      },
+      "finish_reason": "stop"
+    }
+  ],
+  "usage": {
+    "prompt_tokens": 1,
+    "completion_tokens": 1,
+    "total_tokens": 2
+  }
+}
+```
+
+## Minimal proxy
+
+The repo includes a tiny Node proxy in `examples/nvidia-proxy/`. It is useful for testing the `SKILLCHECK_API_URL` flow before building the dashboard.
+
+Run it on a server:
+
+```bash
+export NVIDIA_API_KEY=...
+export SKILLCHECK_PROXY_TOKEN=dev-token
+node examples/nvidia-proxy/server.mjs
+```
+
+Point the CLI at it:
+
+```bash
+export SKILLCHECK_API_URL=https://your-proxy.example.com/v1
+export SKILLCHECK_TOKEN=dev-token
+skillcheck check path/to/SKILL.md
+```
+
+## Dashboard requirements
+
+- `users`: id, email, password/session provider, created_at.
+- `tokens`: id, user_id, token_hash, prefix, created_at, last_used_at, revoked_at.
+- `usage_events`: user_id, token_id, request_id, model, prompt_tokens, completion_tokens, created_at.
+- Rate limit by token and IP.
+- Store model-provider secrets only on the server.
+- Never expose upstream provider secrets to the browser or CLI.
+
+## First production path
+
+1. Deploy the proxy API at `https://api.yourdomain.com/v1`.
+2. Add dashboard auth with GitHub or email login.
+3. Add “Create token” in the dashboard and show the token once.
+4. Hash tokens before storing them.
+5. Verify `Authorization: Bearer <token>` in the proxy.
+6. Add rate limits and usage logging.
+7. Ship the CLI with docs telling users to set `SKILLCHECK_API_URL` and `SKILLCHECK_TOKEN`.

package/examples/nvidia-proxy/README.md

@@ -0,0 +1,19 @@
+# skillcheck NVIDIA proxy
+
+This is the safe way to let CLI users run `skillcheck` without seeing your NVIDIA key.
+
+Run the proxy on a server:
+
+```bash
+export NVIDIA_API_KEY=...
+node examples/nvidia-proxy/server.mjs
+```
+
+Point the CLI at the proxy:
+
+```bash
+export SKILLCHECK_API_URL=https://your-proxy.example.com/v1
+skillcheck check path/to/SKILL.md
+```
+
+Do not publish `NVIDIA_API_KEY` inside the npm package. If the proxy is public, put it behind rate limiting, quotas, or authentication before sharing it broadly.

package/examples/nvidia-proxy/server.mjs

@@ -0,0 +1,96 @@
+#!/usr/bin/env node
+import { createServer } from 'node:http';
+
+const port = Number(process.env.PORT || 8787);
+const nvidiaApiKey = process.env.NVIDIA_API_KEY?.trim();
+const nvidiaBaseUrl = process.env.NVIDIA_BASE_URL?.trim() || 'https://integrate.api.nvidia.com/v1';
+const proxyToken = process.env.SKILLCHECK_PROXY_TOKEN?.trim();
+const maxBodyBytes = Number(process.env.MAX_BODY_BYTES || 5_000_000);
+
+if (!nvidiaApiKey) {
+  throw new Error('Missing NVIDIA_API_KEY. Set it on the server, never inside the npm CLI.');
+}
+
+function writeJson(res, status, body) {
+  res.writeHead(status, {
+    'access-control-allow-headers': 'authorization, content-type',
+    'access-control-allow-methods': 'POST, OPTIONS',
+    'access-control-allow-origin': '*',
+    'content-type': 'application/json'
+  });
+  res.end(`${JSON.stringify(body)}\n`);
+}
+
+function readBody(req) {
+  return new Promise((resolve, reject) => {
+    const chunks = [];
+    let size = 0;
+    req.on('data', (chunk) => {
+      size += chunk.length;
+      if (size > maxBodyBytes) {
+        reject(new Error('Request body is too large'));
+        req.destroy();
+        return;
+      }
+      chunks.push(chunk);
+    });
+    req.on('end', () => resolve(Buffer.concat(chunks).toString('utf8')));
+    req.on('error', reject);
+  });
+}
+
+function isAuthorized(req) {
+  if (!proxyToken) {
+    return true;
+  }
+  return req.headers.authorization === `Bearer ${proxyToken}`;
+}
+
+const server = createServer(async (req, res) => {
+  const url = new URL(req.url || '/', `http://${req.headers.host || 'localhost'}`);
+
+  if (req.method === 'OPTIONS') {
+    writeJson(res, 204, {});
+    return;
+  }
+
+  if (req.method === 'GET' && url.pathname === '/health') {
+    writeJson(res, 200, { ok: true });
+    return;
+  }
+
+  if (req.method !== 'POST' || url.pathname !== '/v1/chat/completions') {
+    writeJson(res, 404, { error: 'Not found' });
+    return;
+  }
+
+  if (!isAuthorized(req)) {
+    writeJson(res, 401, { error: 'Unauthorized' });
+    return;
+  }
+
+  try {
+    const body = await readBody(req);
+    const upstream = await fetch(`${nvidiaBaseUrl}/chat/completions`, {
+      method: 'POST',
+      headers: {
+        authorization: `Bearer ${nvidiaApiKey}`,
+        'content-type': 'application/json'
+      },
+      body
+    });
+
+    res.writeHead(upstream.status, {
+      'access-control-allow-origin': '*',
+      'content-type': upstream.headers.get('content-type') || 'application/json'
+    });
+    res.end(await upstream.text());
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    writeJson(res, 500, { error: message });
+  }
+});
+
+server.listen(port, () => {
+  console.log(`skillcheck NVIDIA proxy listening on http://localhost:${port}`);
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sx4im/skillcheck",
-  "version": "0.1.1",
+  "version": "0.2.1",
   "description": "Measure whether agent skills improve task performance.",
   "type": "module",
   "license": "MIT",
@@ -28,11 +28,13 @@
   },
   "files": [
     "dist",
+    "docs",
+    "examples",
     "README.md",
     "METHODOLOGY.md"
   ],
   "scripts": {
-    "build": "rm -rf dist && tsc -p tsconfig.json",
+    "build": "rm -rf dist && tsc -p tsconfig.json && chmod +x dist/bin/skillcheck.js",
     "m0": "tsx packages/cli/bin/skillcheck.ts m0",
     "site:build": "next build packages/site",
     "test": "vitest run",