scriptonia 0.2.0

package/README.md

@@ -0,0 +1,54 @@
+# scriptonia
+
+Product memory for your coding agent. One command, browser sign-in, and your
+agent reads what your customers actually asked for — with sources it can cite.
+
+## Quick start
+
+```sh
+npx scriptonia login
+```
+
+That's it. A browser opens, you sign in with Google, and:
+
+- your project is created (with a sample dataset so you can try it immediately),
+- an API key is minted and stored for you (you never see or paste a key),
+- the Claude Code skill is installed to `~/.claude/skills/scriptonia/`.
+
+Then your agent — or you — can ask the product brain:
+
+```sh
+scriptonia query "audit log filtering"
+```
+
+## Commands
+
+| command | what it does |
+|---|---|
+| `scriptonia login` | Browser sign-in. Stores creds in `~/.scriptonia/config.json`, installs the skill. |
+| `scriptonia query "<topic>"` | Ask the product brain. Flags: `--window 7d\|30d\|90d\|all`, `--segment enterprise\|mid_market\|smb\|free`, `--json`. |
+| `scriptonia link "<signal_id>"` | Resolve a signal id (from `query` sources) to its full text. |
+| `scriptonia status` | Who you are / which project. |
+| `scriptonia logout` | Forget credentials. |
+| `scriptonia mcp` | Run as an MCP server over stdio (for MCP-native agents like Codex). |
+
+## For MCP-native agents
+
+Point your agent at:
+
+```json
+{
+  "command": "npx",
+  "args": ["-y", "scriptonia", "mcp"]
+}
+```
+
+It exposes `get_context`, `link_back`, and `flag_contradiction`, reading your
+stored credentials — no env vars needed after `scriptonia login`.
+
+## Self-hosting
+
+By default the CLI talks to `https://scriptonia.dev`. Point it elsewhere with
+`SCRIPTONIA_URL=https://your.host scriptonia login` (or `--url`).
+
+Requires Node 18+.

package/bin/scriptonia.mjs

@@ -0,0 +1,322 @@
+#!/usr/bin/env node
+/**
+ * scriptonia — product memory for your coding agent.
+ *
+ *   scriptonia login              browser sign-in; stores creds; installs the skill
+ *   scriptonia query "<topic>"    ask the product brain (what the agent calls)
+ *   scriptonia link "<signal_id>" resolve a signal to its full text
+ *   scriptonia status             who am I / which project
+ *   scriptonia logout             forget creds
+ *   scriptonia mcp                speak MCP over stdio (for MCP-native agents)
+ *
+ * After `login`, everything lives in ~/.scriptonia/config.json. No env vars,
+ * no key pasting. The installed Claude Code skill just runs `scriptonia query`.
+ *
+ * Pure ESM, zero build step — runs on Node 18+.
+ */
+import fs from "node:fs";
+import http from "node:http";
+import os from "node:os";
+import path from "node:path";
+import { spawn } from "node:child_process";
+import { randomBytes } from "node:crypto";
+
+const DEFAULT_URL = process.env.SCRIPTONIA_URL || "https://scriptonia.dev";
+const CONFIG_DIR = path.join(os.homedir(), ".scriptonia");
+const CONFIG_PATH = path.join(CONFIG_DIR, "config.json");
+
+const [, , cmd, ...rest] = process.argv;
+
+const commands = { login, query, link, status, logout, init: reinstallSkill, mcp, help: async () => usage() };
+const run = commands[cmd ?? "help"] ?? (async () => { usage(); process.exit(1); });
+run(rest).catch((e) => {
+  console.error("error:", e instanceof Error ? e.message : String(e));
+  process.exit(1);
+});
+
+// ─────────────────────────────────────────────────────────────
+// login — the one command
+// ─────────────────────────────────────────────────────────────
+async function login(args) {
+  const flags = parseFlags(args);
+  const url = (flags.url ?? DEFAULT_URL).replace(/\/$/, "");
+  const state = randomBytes(16).toString("hex");
+
+  const result = await new Promise((resolve, reject) => {
+    let timer;
+    const done = (fn) => { clearTimeout(timer); fn(); };
+    const server = http.createServer((req, res) => {
+      const u = new URL(req.url ?? "/", "http://127.0.0.1");
+      if (u.pathname !== "/callback") { res.writeHead(404); res.end(); return; }
+      const token = u.searchParams.get("token");
+      const returnedState = u.searchParams.get("state");
+      const email = u.searchParams.get("email") ?? "";
+      const project = u.searchParams.get("project") ?? "";
+      if (!token || returnedState !== state) {
+        res.writeHead(400, { "content-type": "text/html" });
+        res.end(pageHtml("Login failed", "State mismatch — run <code>scriptonia login</code> again."));
+        return;
+      }
+      res.writeHead(200, { "content-type": "text/html" });
+      res.end(pageHtml("You're in ✓", `Signed in as <b>${escapeHtml(email)}</b> · project <b>${escapeHtml(project)}</b>.<br>Return to your terminal.`));
+      done(() => { server.close(); resolve({ url, token, email, project }); });
+    });
+
+    server.listen(0, "127.0.0.1", () => {
+      const addr = server.address();
+      const port = typeof addr === "object" && addr ? addr.port : 0;
+      const authUrl =
+        `${url}/auth/cli?port=${port}&state=${state}` +
+        (flags.dev ? `&dev=1&email=${encodeURIComponent(flags.email ?? "you@example.com")}` : "");
+      console.log("\n  Opening your browser to sign in…");
+      console.log("  If it doesn't open, visit:\n  " + authUrl + "\n");
+      openBrowser(authUrl);
+    });
+
+    timer = setTimeout(() => { server.close(); reject(new Error("timed out waiting for browser login (120s)")); }, 120_000);
+  });
+
+  saveConfig(result);
+  installSkill();
+
+  console.log(`\n  ✓ Signed in as ${result.email}`);
+  console.log(`  ✓ Project "${result.project}" ready (with a sample dataset to try)`);
+  console.log(`  ✓ Skill installed → ~/.claude/skills/scriptonia/SKILL.md`);
+  console.log(`\n  Your agent now reads your customers. Try it:\n`);
+  console.log(`    scriptonia query "audit log filtering"\n`);
+}
+
+// ─────────────────────────────────────────────────────────────
+// query — what the agent (and you) call
+// ─────────────────────────────────────────────────────────────
+async function query(args) {
+  const cfg = requireConfig();
+  const flags = parseFlags(args);
+  const q = args.filter((a) => !a.startsWith("--")).join(" ").trim();
+  if (!q) fail('usage: scriptonia query "<topic>" [--window 30d] [--segment enterprise] [--json]');
+
+  const res = await fetch(`${cfg.url}/api/query`, {
+    method: "POST",
+    headers: { authorization: `Bearer ${cfg.token}`, "content-type": "application/json" },
+    body: JSON.stringify({ query: q, window: flags.window, segment: flags.segment }),
+  });
+  const data = await res.json();
+  if (!res.ok) fail(`query failed (${res.status}): ${JSON.stringify(data)}`);
+
+  const wantJson = flags.json !== undefined || !process.stdout.isTTY;
+  if (wantJson) { process.stdout.write(JSON.stringify(data)); return; }
+  printPretty(data);
+}
+
+// ─────────────────────────────────────────────────────────────
+// link — resolve a signal_id to its full body
+// ─────────────────────────────────────────────────────────────
+async function link(args) {
+  const cfg = requireConfig();
+  const id = args.find((a) => !a.startsWith("--"));
+  if (!id) fail('usage: scriptonia link "<signal_id>"');
+  const res = await fetch(`${cfg.url}/api/link_back?signal_id=${encodeURIComponent(id)}`, {
+    headers: { authorization: `Bearer ${cfg.token}` },
+  });
+  const data = await res.json();
+  if (!res.ok) fail(`link failed (${res.status}): ${JSON.stringify(data)}`);
+  process.stdout.write(JSON.stringify(data));
+}
+
+// ─────────────────────────────────────────────────────────────
+// status / logout
+// ─────────────────────────────────────────────────────────────
+async function status() {
+  const cfg = loadConfig();
+  if (!cfg) { console.log("not logged in — run `scriptonia login`"); return; }
+  console.log(`signed in as ${cfg.email}`);
+  console.log(`project      ${cfg.project}`);
+  console.log(`endpoint     ${cfg.url}`);
+  console.log(`config       ${CONFIG_PATH}`);
+}
+
+async function logout() {
+  if (fs.existsSync(CONFIG_PATH)) fs.rmSync(CONFIG_PATH);
+  console.log("logged out.");
+}
+
+// ─────────────────────────────────────────────────────────────
+// skill install
+// ─────────────────────────────────────────────────────────────
+async function reinstallSkill() {
+  requireConfig();
+  installSkill();
+  console.log("✓ skill reinstalled → ~/.claude/skills/scriptonia/SKILL.md");
+}
+
+function installSkill() {
+  const dir = path.join(os.homedir(), ".claude", "skills", "scriptonia");
+  fs.mkdirSync(dir, { recursive: true });
+  fs.writeFileSync(path.join(dir, "SKILL.md"), skillMarkdown());
+}
+
+function skillMarkdown() {
+  return `---
+name: scriptonia
+description: >
+  BEFORE planning any user-facing change — a feature, a bug fix, a refactor with
+  UX impact, or a non-trivial default — run \`scriptonia query "<topic>"\`. It
+  returns what THIS project's customers actually asked for (with source ids you
+  can cite), what prior decisions your plan might contradict, and known edge
+  cases. Skipping it means shipping a plan that isn't grounded in customer signal.
+---
+
+# Scriptonia — Product Memory
+
+Before writing a plan for anything user-facing, call:
+
+\`\`\`sh
+scriptonia query "<the topic you're about to build>"
+\`\`\`
+
+Optional flags: \`--window 7d|30d|90d|all\` (default 30d), \`--segment enterprise|mid_market|smb|free\`.
+
+Output (JSON when piped) contains:
+- **requirements[]** — each with \`source_ids\` and a \`context_url\`. Cite the
+  source_ids next to the matching step in your plan.
+- **contradictions[]** — if non-empty, STOP and surface it to the human before
+  writing code. Each has a \`decision_ref\`.
+- **edge_cases[]** — fold these into the plan.
+- **sources[]** — quote a customer verbatim with \`scriptonia link "<signal_id>"\`.
+
+Rule: every plan step for a user-facing change should cite at least one
+source_id. If it can't, you're inventing demand — query first.
+`;
+}
+
+// ─────────────────────────────────────────────────────────────
+// mcp — MCP stdio server (for MCP-native agents)
+// ─────────────────────────────────────────────────────────────
+async function mcp() {
+  const cfg = requireConfig();
+  const { McpServer } = await import("@modelcontextprotocol/sdk/server/mcp.js");
+  const { StdioServerTransport } = await import("@modelcontextprotocol/sdk/server/stdio.js");
+  const { z } = await import("zod");
+
+  const server = new McpServer({ name: "scriptonia", version: "0.2.0" }, { capabilities: { tools: {} } });
+  const auth = () => ({ authorization: `Bearer ${cfg.token}`, "content-type": "application/json" });
+
+  server.registerTool(
+    "get_context",
+    {
+      description:
+        "Query the product brain: what customers said about a topic, prior decisions your plan may contradict, and known edge cases. Call BEFORE planning any user-facing change.",
+      inputSchema: {
+        query: z.string(),
+        window: z.enum(["7d", "30d", "90d", "all"]).optional(),
+        segment: z.enum(["enterprise", "mid_market", "smb", "free", "unknown"]).optional(),
+      },
+    },
+    async ({ query: q, window, segment }) => {
+      const r = await fetch(`${cfg.url}/api/query`, { method: "POST", headers: auth(), body: JSON.stringify({ query: q, window, segment }) });
+      return { content: [{ type: "text", text: await r.text() }], isError: !r.ok };
+    },
+  );
+  server.registerTool(
+    "link_back",
+    { description: "Resolve a signal_id from get_context.sources[] to its full body and author.", inputSchema: { signal_id: z.string() } },
+    async ({ signal_id }) => {
+      const r = await fetch(`${cfg.url}/api/link_back?signal_id=${encodeURIComponent(signal_id)}`, { headers: { authorization: `Bearer ${cfg.token}` } });
+      return { content: [{ type: "text", text: await r.text() }], isError: !r.ok };
+    },
+  );
+  server.registerTool(
+    "flag_contradiction",
+    { description: "Report that your plan conflicts with a context. Persists for audit.", inputSchema: { plan_id: z.string(), context_id: z.string().optional(), note: z.string().optional() } },
+    async ({ plan_id, context_id, note }) => {
+      const r = await fetch(`${cfg.url}/api/flag_contradiction`, { method: "POST", headers: auth(), body: JSON.stringify({ plan_id, context_id, note }) });
+      return { content: [{ type: "text", text: await r.text() }], isError: !r.ok };
+    },
+  );
+
+  await server.connect(new StdioServerTransport());
+}
+
+// ─────────────────────────────────────────────────────────────
+// helpers
+// ─────────────────────────────────────────────────────────────
+function loadConfig() {
+  try { return JSON.parse(fs.readFileSync(CONFIG_PATH, "utf8")); } catch { return null; }
+}
+function requireConfig() {
+  const cfg = loadConfig();
+  if (!cfg) fail("not logged in — run `scriptonia login`");
+  return cfg;
+}
+function saveConfig(cfg) {
+  fs.mkdirSync(CONFIG_DIR, { recursive: true });
+  fs.writeFileSync(CONFIG_PATH, JSON.stringify(cfg, null, 2), { mode: 0o600 });
+}
+
+function parseFlags(args) {
+  const out = {};
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (!a.startsWith("--")) continue;
+    const eq = a.indexOf("=");
+    if (eq > 0) out[a.slice(2, eq)] = a.slice(eq + 1);
+    else {
+      const next = args[i + 1];
+      if (next && !next.startsWith("--")) out[a.slice(2)] = args[++i];
+      else out[a.slice(2)] = "true";
+    }
+  }
+  return out;
+}
+
+function openBrowser(url) {
+  const cmd = process.platform === "darwin" ? "open" : process.platform === "win32" ? "cmd" : "xdg-open";
+  const args = process.platform === "win32" ? ["/c", "start", "", url] : [url];
+  try { spawn(cmd, args, { stdio: "ignore", detached: true }).unref(); } catch { /* click the printed URL */ }
+}
+
+function printPretty(d) {
+  const c = { dim: "\x1b[2m", b: "\x1b[1m", v: "\x1b[35m", w: "\x1b[33m", g: "\x1b[32m", r: "\x1b[0m" };
+  console.log(`\n${c.b}${d.tldr ?? ""}${c.r}\n`);
+  for (const req of d.requirements ?? []) {
+    console.log(`  ${c.g}●${c.r} ${c.b}${req.title}${c.r} ${c.dim}[${req.strength}]${c.r}`);
+    console.log(`    ${req.detail}`);
+    console.log(`    ${c.dim}sources: ${(req.source_ids ?? []).join(", ")}${c.r}`);
+    if (req.context_url) console.log(`    ${c.v}${req.context_url}${c.r}`);
+  }
+  for (const con of d.contradictions ?? []) {
+    console.log(`\n  ${c.w}⚠ CONTRADICTS${c.r} ${con.detail}`);
+    console.log(`    ${c.dim}${con.decision_ref}${c.r}`);
+  }
+  if ((d.edge_cases ?? []).length) {
+    console.log(`\n  ${c.dim}edge cases:${c.r}`);
+    for (const e of d.edge_cases) console.log(`    · ${e}`);
+  }
+  console.log(`\n  ${c.dim}${(d.sources ?? []).length} sources · ${d.meta?.ms ?? "?"}ms${c.r}\n`);
+}
+
+function pageHtml(title, body) {
+  return `<!doctype html><meta charset=utf8><body style="font-family:ui-monospace,monospace;background:#08080A;color:#EDEDF0;display:grid;place-items:center;height:100vh;margin:0">
+  <div style="text-align:center;max-width:420px">
+    <div style="font-size:28px;letter-spacing:-.02em;margin-bottom:12px">${title}</div>
+    <div style="color:#9a9aa5;line-height:1.6">${body}</div>
+  </div></body>`;
+}
+function escapeHtml(s) {
+  return s.replace(/[&<>"]/g, (ch) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;" }[ch]));
+}
+function fail(msg) { console.error(msg); process.exit(1); }
+function usage() {
+  console.log(`scriptonia — product memory for your coding agent
+
+  scriptonia login              sign in (browser) — installs the skill, no keys to copy
+  scriptonia query "<topic>"    ask the product brain
+  scriptonia link "<id>"        resolve a signal to its full text
+  scriptonia status             show who you are
+  scriptonia logout             forget credentials
+  scriptonia mcp                run as an MCP server (stdio)
+
+  login flags: --dev --email you@co.com   (local testing; skips Google)
+  query flags: --window 30d --segment enterprise --json
+`);
+}

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "scriptonia",
+  "version": "0.2.0",
+  "description": "Product memory for your coding agent. One command, browser sign-in, your agent reads your customers.",
+  "type": "module",
+  "bin": {
+    "scriptonia": "bin/scriptonia.mjs"
+  },
+  "files": [
+    "bin",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "zod": "^3.25.76"
+  },
+  "keywords": [
+    "scriptonia",
+    "claude-code",
+    "mcp",
+    "product-memory",
+    "customer-signal",
+    "agent",
+    "cli"
+  ],
+  "homepage": "https://scriptonia.dev",
+  "license": "MIT"
+}