@piut/cli 1.0.0

package/README.md

@@ -0,0 +1,110 @@
+# pıut
+
+**Give every AI tool persistent memory about you.**
+
+pıut is a personal context service that works via [MCP (Model Context Protocol)](https://modelcontextprotocol.io). Connect once, and every AI tool you use — Claude, ChatGPT, Cursor, Copilot, and more — knows who you are, what you're working on, and how you like to work.
+
+## Quick Start
+
+```bash
+npx piut
+```
+
+That's it. The CLI auto-detects your AI tools and configures them.
+
+Or set up manually:
+
+1. Sign up at [piut.com](https://piut.com)
+2. Generate an API key at [piut.com/dashboard/keys](https://piut.com/dashboard/keys)
+3. Add the MCP server to your AI tool:
+
+```json
+{
+  "mcpServers": {
+    "piut-context": {
+      "type": "http",
+      "url": "https://piut.com/api/mcp/YOUR_SLUG",
+      "headers": {
+        "Authorization": "Bearer YOUR_KEY"
+      }
+    }
+  }
+}
+```
+
+See [piut.com/docs](https://piut.com/docs#add-to-ai) for setup guides for 14+ AI tools.
+
+## CLI
+
+Install globally or run with `npx`:
+
+```bash
+npx piut              # Auto-detect and configure AI tools
+npx piut status       # Show which tools are connected
+npx piut remove       # Remove pıut from selected tools
+```
+
+**Options:**
+
+```bash
+npx piut --key pb_... # Pass API key non-interactively
+npx piut --tool cursor # Configure a single tool
+npx piut --skip-skill  # Skip skill.md file placement
+```
+
+**Supported tools:** Claude Code, Claude Desktop, Cursor, Windsurf, GitHub Copilot, Amazon Q, Zed
+
+## How It Works
+
+1. **Build your context** — Answer 5 questions or import existing files from your AI tools
+2. **Connect your tools** — Run `npx piut` or add one config, and every connected AI knows your context
+3. **Stay in sync** — Update your context once, and it's reflected everywhere
+
+Your context is organized into 5 sections:
+
+| Section | What it stores |
+|---------|---------------|
+| **About** | Bio, preferences, goals — the AI's mental model of you |
+| **Soul** | Behavioral instructions for AI — tone, guardrails, priorities |
+| **Areas** | Long-term life/work domains (Health, Finances, Marketing) |
+| **Projects** | Active, time-bound work with goals and deadlines |
+| **Memory** | Bookmarks, links, ideas, notes, reference material |
+
+## Documentation
+
+| Document | Description |
+|----------|-------------|
+| [**skill.md**](skill.md) | AI skill file — MCP tools, rate limits, error codes |
+| [**Add to your AI**](https://piut.com/docs#add-to-ai) | Setup guides for Claude, ChatGPT, Cursor, Copilot, and more |
+| [**API Reference**](https://piut.com/docs#api-examples) | Code examples in cURL, Python, Node.js, Go, and Ruby |
+| [**Rate Limits**](https://piut.com/docs#limits) | Limits by plan, error codes, and response headers |
+| [**Context Files**](https://piut.com/docs#context-files) | Where to find your existing context in 14 AI platforms |
+
+All documentation is maintained at [piut.com/docs](https://piut.com/docs) — the interactive version with credential auto-fill and setup guides.
+
+## MCP Tools
+
+pıut provides 6 tools via MCP:
+
+| Tool | Purpose |
+|------|---------|
+| `get_context` | Read all 5 context sections |
+| `get_section` | Read a specific section |
+| `search_brain` | Search across all sections |
+| `add_memory` | Append content to a section |
+| `update_brain` | AI-powered smart update across sections |
+| `prompt_brain` | Natural language command (edit, delete, reorganize) |
+
+Full tool documentation: [skill.md](skill.md)
+
+## Links
+
+- [piut.com](https://piut.com) — Sign up and manage your context
+- [piut.com/docs](https://piut.com/docs) — Interactive documentation with credential injection
+- [skill.md (raw)](https://raw.githubusercontent.com/M-Flat-Inc/piut/main/skill.md) — Direct link for AI tool configs
+
+## License
+
+Copyright (c) 2025 M-Flat Inc. All rights reserved.
+
+The documentation in this repository is provided for reference and integration purposes. The pıut service is proprietary software.

package/dist/cli.js

@@ -0,0 +1,514 @@
+#!/usr/bin/env node
+
+// src/cli.ts
+import { Command } from "commander";
+
+// src/commands/setup.ts
+import fs3 from "fs";
+import path5 from "path";
+import { execSync } from "child_process";
+import { password, confirm, checkbox } from "@inquirer/prompts";
+import chalk2 from "chalk";
+
+// src/lib/api.ts
+var API_BASE = process.env.PIUT_API_BASE || "https://piut.com";
+async function validateKey(key) {
+  const res = await fetch(`${API_BASE}/api/cli/validate`, {
+    headers: { Authorization: `Bearer ${key}` }
+  });
+  if (!res.ok) {
+    const body = await res.json().catch(() => ({ error: "Unknown error" }));
+    throw new Error(body.error || `Validation failed (HTTP ${res.status})`);
+  }
+  return res.json();
+}
+
+// src/lib/tools.ts
+import os from "os";
+import path from "path";
+var MCP_URL = (slug) => `https://piut.com/api/mcp/${slug}`;
+var AUTH_HEADER = (key) => ({ Authorization: `Bearer ${key}` });
+function appData() {
+  return process.env.APPDATA || path.join(os.homedir(), "AppData", "Roaming");
+}
+var TOOLS = [
+  {
+    id: "claude-code",
+    name: "Claude Code",
+    configKey: "mcpServers",
+    configPaths: {
+      darwin: ["~/.claude.json"],
+      win32: ["~/.claude.json"],
+      linux: ["~/.claude.json"]
+    },
+    skillFilePath: "CLAUDE.md",
+    quickCommand: (slug, key) => `claude mcp add-json piut-context '${JSON.stringify({
+      type: "http",
+      url: MCP_URL(slug),
+      headers: AUTH_HEADER(key)
+    })}'`,
+    generateConfig: (slug, key) => ({
+      type: "http",
+      url: MCP_URL(slug),
+      headers: AUTH_HEADER(key)
+    })
+  },
+  {
+    id: "claude-desktop",
+    name: "Claude Desktop",
+    configKey: "mcpServers",
+    configPaths: {
+      darwin: ["~/Library/Application Support/Claude/claude_desktop_config.json"],
+      win32: [path.join(appData(), "Claude", "claude_desktop_config.json")],
+      linux: ["~/.config/Claude/claude_desktop_config.json"]
+    },
+    generateConfig: (slug, key) => ({
+      command: "npx",
+      args: [
+        "-y",
+        "mcp-remote",
+        MCP_URL(slug),
+        "--header",
+        `Authorization: Bearer ${key}`
+      ]
+    })
+  },
+  {
+    id: "cursor",
+    name: "Cursor",
+    configKey: "mcpServers",
+    configPaths: {
+      darwin: ["~/.cursor/mcp.json"],
+      win32: ["~/.cursor/mcp.json"],
+      linux: ["~/.cursor/mcp.json"],
+      project: [".cursor/mcp.json"]
+    },
+    skillFilePath: ".cursor/rules/piut.mdc",
+    generateConfig: (slug, key) => ({
+      url: MCP_URL(slug),
+      headers: AUTH_HEADER(key)
+    })
+  },
+  {
+    id: "windsurf",
+    name: "Windsurf",
+    configKey: "mcpServers",
+    configPaths: {
+      darwin: ["~/.codeium/windsurf/mcp_config.json"],
+      win32: ["~/.codeium/windsurf/mcp_config.json"],
+      linux: ["~/.codeium/windsurf/mcp_config.json"]
+    },
+    skillFilePath: ".windsurf/rules/piut.md",
+    generateConfig: (slug, key) => ({
+      serverUrl: MCP_URL(slug),
+      headers: AUTH_HEADER(key)
+    })
+  },
+  {
+    id: "copilot",
+    name: "GitHub Copilot",
+    configKey: "servers",
+    configPaths: {
+      project: [".vscode/mcp.json"]
+    },
+    skillFilePath: ".github/copilot-instructions.md",
+    generateConfig: (slug, key) => ({
+      type: "http",
+      url: MCP_URL(slug),
+      headers: AUTH_HEADER(key)
+    })
+  },
+  {
+    id: "amazon-q",
+    name: "Amazon Q",
+    configKey: "mcpServers",
+    configPaths: {
+      darwin: ["~/.aws/amazonq/mcp.json"],
+      win32: ["~/.aws/amazonq/mcp.json"],
+      linux: ["~/.aws/amazonq/mcp.json"]
+    },
+    skillFilePath: "CONVENTIONS.md",
+    generateConfig: (slug, key) => ({
+      type: "http",
+      url: MCP_URL(slug),
+      headers: AUTH_HEADER(key)
+    })
+  },
+  {
+    id: "zed",
+    name: "Zed",
+    configKey: "context_servers",
+    configPaths: {
+      darwin: ["~/.config/zed/settings.json"],
+      linux: ["~/.config/zed/settings.json"]
+    },
+    skillFilePath: ".zed/rules.md",
+    generateConfig: (slug, key) => ({
+      settings: {
+        url: MCP_URL(slug),
+        headers: AUTH_HEADER(key)
+      }
+    })
+  }
+];
+
+// src/lib/paths.ts
+import os2 from "os";
+import path2 from "path";
+var home = os2.homedir();
+var platform = process.platform;
+function expandPath(p) {
+  return p.replace(/^~/, home);
+}
+function resolveConfigPaths(configPaths) {
+  const resolved = [];
+  const platformKey = platform;
+  const globalPaths = configPaths[platformKey] || [];
+  for (const p of globalPaths) {
+    resolved.push(expandPath(p));
+  }
+  const projectPaths = configPaths.project || [];
+  for (const p of projectPaths) {
+    resolved.push(path2.resolve(process.cwd(), p));
+  }
+  return resolved;
+}
+
+// src/lib/config.ts
+import fs from "fs";
+import path3 from "path";
+function readConfig(filePath) {
+  let raw;
+  try {
+    raw = fs.readFileSync(filePath, "utf-8");
+  } catch (err) {
+    if (err.code === "ENOENT") return null;
+    throw err;
+  }
+  try {
+    return JSON.parse(raw);
+  } catch {
+    try {
+      const cleaned = raw.replace(/\/\*[\s\S]*?\*\//g, "").replace(/^(\s*)\/\/.*$/gm, "$1");
+      return JSON.parse(cleaned);
+    } catch {
+      return null;
+    }
+  }
+}
+function writeConfig(filePath, data) {
+  fs.mkdirSync(path3.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, JSON.stringify(data, null, 2) + "\n", "utf-8");
+}
+function isPiutConfigured(filePath, configKey) {
+  const config = readConfig(filePath);
+  if (!config) return false;
+  const servers = config[configKey];
+  return !!servers?.["piut-context"];
+}
+function mergeConfig(filePath, configKey, serverConfig) {
+  const existing = readConfig(filePath) || {};
+  const servers = existing[configKey] || {};
+  servers["piut-context"] = serverConfig;
+  existing[configKey] = servers;
+  writeConfig(filePath, existing);
+}
+function removeFromConfig(filePath, configKey) {
+  const config = readConfig(filePath);
+  if (!config) return false;
+  const servers = config[configKey];
+  if (!servers?.["piut-context"]) return false;
+  delete servers["piut-context"];
+  if (Object.keys(servers).length === 0) {
+    delete config[configKey];
+  }
+  writeConfig(filePath, config);
+  return true;
+}
+
+// src/lib/skill.ts
+import fs2 from "fs";
+import path4 from "path";
+var SKILL_SNIPPET = `## p\u0131ut Context
+
+This project uses p\u0131ut for persistent personal context.
+Skill reference: https://raw.githubusercontent.com/M-Flat-Inc/piut/main/skill.md
+
+Always call \`get_context\` at the start of a conversation to understand the user.
+Read the \`soul\` section first \u2014 it contains behavioral instructions for how to interact.
+Use \`update_brain\` for substantial new information, \`append_brain\` for quick notes.`;
+var SEPARATOR = "\n\n---\n\n";
+function placeSkillFile(filePath) {
+  const absPath = path4.isAbsolute(filePath) ? filePath : path4.resolve(process.cwd(), filePath);
+  try {
+    const existing = fs2.readFileSync(absPath, "utf-8");
+    if (existing.includes("p\u0131ut Context")) {
+      return { created: false, appended: false };
+    }
+    fs2.appendFileSync(absPath, SEPARATOR + SKILL_SNIPPET + "\n");
+    return { created: false, appended: true };
+  } catch (err) {
+    if (err.code === "ENOENT") {
+      fs2.mkdirSync(path4.dirname(absPath), { recursive: true });
+      fs2.writeFileSync(absPath, SKILL_SNIPPET + "\n", "utf-8");
+      return { created: true, appended: false };
+    }
+    throw err;
+  }
+}
+
+// src/lib/ui.ts
+import chalk from "chalk";
+var brand = chalk.hex("#8B5CF6");
+var success = chalk.green;
+var warning = chalk.yellow;
+var error = chalk.red;
+var dim = chalk.dim;
+function banner() {
+  console.log();
+  console.log(brand.bold("  p\u0131ut") + dim(" \u2014 personal context for AI"));
+  console.log();
+}
+function toolLine(name, status, icon) {
+  console.log(`  ${icon} ${name.padEnd(20)} ${status}`);
+}
+
+// src/commands/setup.ts
+async function setupCommand(options) {
+  banner();
+  let apiKey = options.key;
+  if (!apiKey) {
+    if (options.yes) {
+      console.log(chalk2.red("  \u2717 --key is required when using --yes"));
+      process.exit(1);
+    }
+    apiKey = await password({
+      message: "Enter your p\u0131ut API key:",
+      mask: "*",
+      validate: (v) => v.startsWith("pb_") || "Key must start with pb_"
+    });
+  }
+  console.log(dim("  Validating key..."));
+  let validationResult;
+  try {
+    validationResult = await validateKey(apiKey);
+  } catch (err) {
+    console.log(chalk2.red(`  \u2717 ${err.message}`));
+    console.log(dim("  Get a key at https://piut.com/dashboard/keys"));
+    process.exit(1);
+  }
+  const { slug, displayName } = validationResult;
+  console.log(success(`  \u2714 Authenticated as ${displayName} (${slug})`));
+  console.log();
+  const detected = [];
+  const toolFilter = options.tool;
+  for (const tool of TOOLS) {
+    if (toolFilter && tool.id !== toolFilter) continue;
+    const paths = resolveConfigPaths(tool.configPaths);
+    for (const configPath of paths) {
+      const exists = fs3.existsSync(configPath);
+      const parentExists = fs3.existsSync(path5.dirname(configPath));
+      if (exists || parentExists) {
+        detected.push({
+          tool,
+          configPath,
+          exists,
+          alreadyConfigured: exists && isPiutConfigured(configPath, tool.configKey)
+        });
+        break;
+      }
+    }
+  }
+  if (detected.length === 0) {
+    console.log(warning("  No supported AI tools detected."));
+    console.log(dim("  Supported: Claude Code, Claude Desktop, Cursor, Windsurf, GitHub Copilot, Amazon Q, Zed"));
+    console.log(dim("  See https://piut.com/docs for manual setup."));
+    console.log();
+    return;
+  }
+  let selected;
+  if (options.yes) {
+    selected = detected.filter((d) => !d.alreadyConfigured);
+    if (selected.length === 0) {
+      console.log(dim("  All detected tools are already configured."));
+      console.log();
+      return;
+    }
+  } else {
+    const choices = detected.map((d) => ({
+      name: d.alreadyConfigured ? `${d.tool.name} ${dim("(already configured)")}` : d.tool.name,
+      value: d,
+      checked: !d.alreadyConfigured
+    }));
+    selected = await checkbox({
+      message: "Select tools to configure:",
+      choices
+    });
+    if (selected.length === 0) {
+      console.log(dim("  No tools selected."));
+      return;
+    }
+  }
+  console.log();
+  const configured = [];
+  const skipped = [];
+  for (const det of selected) {
+    const { tool, configPath, alreadyConfigured } = det;
+    if (alreadyConfigured) {
+      if (options.yes) {
+        skipped.push(tool.name);
+        continue;
+      }
+      const update = await confirm({
+        message: `p\u0131ut is already configured in ${tool.name}. Update it?`,
+        default: true
+      });
+      if (!update) {
+        skipped.push(tool.name);
+        continue;
+      }
+    }
+    if (tool.id === "claude-code" && tool.quickCommand && isCommandAvailable("claude")) {
+      try {
+        execSync(tool.quickCommand(slug, apiKey), { stdio: "pipe" });
+        configured.push(tool.name);
+        toolLine(tool.name, success("configured via CLI"), "\u2714");
+        continue;
+      } catch {
+        console.log(dim("  Claude CLI command failed, using config file..."));
+      }
+    }
+    const serverConfig = tool.generateConfig(slug, apiKey);
+    mergeConfig(configPath, tool.configKey, serverConfig);
+    configured.push(tool.name);
+    toolLine(tool.name, success("configured"), "\u2714");
+  }
+  if (!options.skipSkill && configured.length > 0) {
+    const addSkill = options.yes ? true : await confirm({
+      message: "Add skill.md reference to rules files? (teaches AI how to use p\u0131ut)",
+      default: true
+    });
+    if (addSkill) {
+      console.log();
+      for (const det of selected) {
+        if (!det.tool.skillFilePath) continue;
+        if (!configured.includes(det.tool.name)) continue;
+        const result = placeSkillFile(det.tool.skillFilePath);
+        if (result.created) {
+          console.log(dim(`  Created ${det.tool.skillFilePath}`));
+        } else if (result.appended) {
+          console.log(dim(`  Updated ${det.tool.skillFilePath}`));
+        } else {
+          console.log(dim(`  ${det.tool.skillFilePath} already has skill reference`));
+        }
+      }
+    }
+  }
+  console.log();
+  console.log(brand.bold("  Setup complete!"));
+  if (configured.length > 0) {
+    console.log(success(`  Configured: ${configured.join(", ")}`));
+  }
+  if (skipped.length > 0) {
+    console.log(dim(`  Skipped: ${skipped.join(", ")}`));
+  }
+  console.log();
+  console.log(dim("  Restart your AI tools for changes to take effect."));
+  console.log(dim('  Verify: ask any AI "What do you know about me from my context?"'));
+  console.log();
+}
+function isCommandAvailable(cmd) {
+  try {
+    execSync(process.platform === "win32" ? `where ${cmd}` : `which ${cmd}`, { stdio: "pipe" });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// src/commands/status.ts
+import fs4 from "fs";
+function statusCommand() {
+  banner();
+  console.log("  AI tool configuration status:");
+  console.log();
+  let foundAny = false;
+  for (const tool of TOOLS) {
+    const paths = resolveConfigPaths(tool.configPaths);
+    for (const configPath of paths) {
+      if (!fs4.existsSync(configPath)) continue;
+      foundAny = true;
+      const configured = isPiutConfigured(configPath, tool.configKey);
+      if (configured) {
+        toolLine(tool.name, success("connected"), "\u2714");
+      } else {
+        toolLine(tool.name, dim("installed, not connected"), "\u25CB");
+      }
+      break;
+    }
+  }
+  if (!foundAny) {
+    console.log(warning("  No supported AI tools detected."));
+    console.log(dim("  Supported: Claude Code, Claude Desktop, Cursor, Windsurf, GitHub Copilot, Amazon Q, Zed"));
+  }
+  console.log();
+}
+
+// src/commands/remove.ts
+import fs5 from "fs";
+import { checkbox as checkbox2, confirm as confirm2 } from "@inquirer/prompts";
+async function removeCommand() {
+  banner();
+  const configured = [];
+  for (const tool of TOOLS) {
+    const paths = resolveConfigPaths(tool.configPaths);
+    for (const configPath of paths) {
+      if (fs5.existsSync(configPath) && isPiutConfigured(configPath, tool.configKey)) {
+        configured.push({ tool, configPath });
+        break;
+      }
+    }
+  }
+  if (configured.length === 0) {
+    console.log(dim("  p\u0131ut is not configured in any detected AI tools."));
+    console.log();
+    return;
+  }
+  const choices = configured.map((c) => ({
+    name: c.tool.name,
+    value: c
+  }));
+  const selected = await checkbox2({
+    message: "Select tools to remove p\u0131ut from:",
+    choices
+  });
+  if (selected.length === 0) {
+    console.log(dim("  No tools selected."));
+    return;
+  }
+  const proceed = await confirm2({
+    message: `Remove p\u0131ut from ${selected.length} tool(s)?`,
+    default: false
+  });
+  if (!proceed) return;
+  console.log();
+  for (const { tool, configPath } of selected) {
+    const removed = removeFromConfig(configPath, tool.configKey);
+    if (removed) {
+      toolLine(tool.name, success("removed"), "\u2714");
+    } else {
+      toolLine(tool.name, warning("not found"), "\xD7");
+    }
+  }
+  console.log();
+  console.log(dim("  Restart your AI tools for changes to take effect."));
+  console.log();
+}
+
+// src/cli.ts
+var program = new Command();
+program.name("piut").description("Configure your AI tools to use p\u0131ut personal context").version("1.0.0");
+program.command("setup", { isDefault: true }).description("Auto-detect and configure AI tools").option("-k, --key <key>", "API key (prompts interactively if not provided)").option("-t, --tool <id>", "Configure a single tool (claude-code, cursor, windsurf, etc.)").option("-y, --yes", "Skip interactive prompts (auto-select all detected tools)").option("--project", "Prefer project-local config files").option("--skip-skill", "Skip skill.md file placement").action(setupCommand);
+program.command("status").description("Show which AI tools are configured with p\u0131ut").action(statusCommand);
+program.command("remove").description("Remove p\u0131ut configuration from AI tools").action(removeCommand);
+program.parse();

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@piut/cli",
+  "version": "1.0.0",
+  "description": "Configure your AI tools to use pıut personal context",
+  "type": "module",
+  "bin": {
+    "piut": "dist/cli.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run build && npm test"
+  },
+  "keywords": [
+    "mcp",
+    "ai",
+    "context",
+    "cli",
+    "claude",
+    "cursor",
+    "copilot",
+    "windsurf"
+  ],
+  "author": "M-Flat Inc",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/M-Flat-Inc/piut"
+  },
+  "homepage": "https://piut.com",
+  "dependencies": {
+    "@inquirer/prompts": "^7.0.0",
+    "chalk": "^5.4.0",
+    "commander": "^13.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.0.0",
+    "vitest": "^3.0.0"
+  }
+}