@knosi/cli 0.1.0 → 0.1.2

package/README.md

@@ -1,8 +1,12 @@
 # @knosi/cli
 
-Local Claude Code daemon for [Second Brain](https://github.com/zhousiyao03-cyber/second-brain).
+Knosi CLI for [Second Brain](https://github.com/zhousiyao03-cyber/second-brain).
 
-Runs on your machine, picks up AI tasks from the hosted Second Brain instance, executes them via your local Claude CLI, and pushes results back.
+Runs on your machine and supports three workflows:
+
+1. the existing Claude Code daemon
+2. OAuth login against your Knosi deployment
+3. explicit raw AI capture saves for Claude Code skills
 
 ## Prerequisites
 
@@ -22,6 +26,49 @@ The daemon will:
 
 Press Ctrl+C to stop.
 
+### OAuth Login
+
+```bash
+npx @knosi/cli auth login https://www.knosi.xyz
+```
+
+This starts a local callback server on `127.0.0.1:6274`, opens the browser, completes OAuth against Knosi, and stores CLI credentials in `~/.knosi/cli.json`.
+
+### Save a Raw AI Capture
+
+```bash
+cat payload.json | npx @knosi/cli save-ai-note --json
+```
+
+Payload shape:
+
+```json
+{
+  "sourceApp": "claude-code",
+  "title": "Optional custom title",
+  "capturedAtLabel": "2026-04-12 15:20 SGT",
+  "messages": [
+    { "role": "user", "content": "Question" },
+    { "role": "assistant", "content": "Answer" }
+  ],
+  "sourceMeta": {
+    "projectPath": "/Users/bytedance/second-brain"
+  }
+}
+```
+
+### Install the Claude Code Skill
+
+```bash
+npx @knosi/cli install-skill
+```
+
+This copies the bundled template to:
+
+```text
+~/.claude/skills/save-to-knosi/SKILL.md
+```
+
 ## Options
 
 | Flag | Description | Default |

package/package.json

@@ -1,14 +1,15 @@
 {
   "name": "@knosi/cli",
-  "version": "0.1.0",
-  "description": "Local Claude Code daemon for Second Brain — run AI tasks on your machine",
+  "version": "0.1.2",
+  "description": "Knosi CLI for Claude Code daemon, OAuth login, raw AI capture saves, and skill install",
   "license": "AGPL-3.0-or-later",
   "type": "module",
   "bin": {
     "knosi": "./src/index.mjs"
   },
   "files": [
-    "src/"
+    "src/",
+    "templates/"
   ],
   "engines": {
     "node": ">=20"
@@ -17,6 +18,9 @@
     "second-brain",
     "claude",
     "ai",
-    "daemon"
+    "daemon",
+    "oauth",
+    "mcp",
+    "knowledge-base"
   ]
 }

package/src/commands/auth-login.mjs

@@ -0,0 +1,107 @@
+import crypto from "node:crypto";
+import http from "node:http";
+import { spawn } from "node:child_process";
+import { getDefaultBaseUrl, saveConfig } from "../config.mjs";
+
+export function createPkceVerifier() {
+  return crypto.randomBytes(32).toString("base64url");
+}
+
+export function createPkceChallenge(verifier) {
+  return crypto.createHash("sha256").update(verifier).digest("base64url");
+}
+
+export function buildAuthorizationUrl({
+  baseUrl,
+  codeChallenge,
+  redirectUri,
+}) {
+  const url = new URL("/oauth/authorize", baseUrl);
+  url.searchParams.set("response_type", "code");
+  url.searchParams.set("client_id", "knosi-cli");
+  url.searchParams.set("redirect_uri", redirectUri);
+  url.searchParams.set("scope", "knowledge:read knowledge:write_inbox");
+  url.searchParams.set("code_challenge", codeChallenge);
+  url.searchParams.set("code_challenge_method", "S256");
+  return url.toString();
+}
+
+function openUrl(url) {
+  const command = process.platform === "darwin" ? "open" : "xdg-open";
+  try {
+    spawn(command, [url], { stdio: "ignore", detached: true }).unref();
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function waitForCallback(port) {
+  return new Promise((resolve, reject) => {
+    const server = http.createServer((req, res) => {
+      const url = new URL(req.url ?? "/", `http://127.0.0.1:${port}`);
+      const code = url.searchParams.get("code");
+      const error = url.searchParams.get("error");
+
+      res.writeHead(200, { "Content-Type": "text/plain; charset=utf-8" });
+      res.end(error ? `Login failed: ${error}\n` : "Knosi CLI login complete. You can return to Claude Code.\n");
+      server.close();
+
+      if (error) {
+        reject(new Error(`OAuth login failed: ${error}`));
+      } else if (!code) {
+        reject(new Error("OAuth callback did not include a code."));
+      } else {
+        resolve(code);
+      }
+    });
+
+    server.listen(port, "127.0.0.1");
+  });
+}
+
+export async function runAuthLogin(args) {
+  const baseUrl = args[0] && args[0].startsWith("http") ? args[0] : getDefaultBaseUrl();
+  const port = 6274;
+  const redirectUri = `http://127.0.0.1:${port}/oauth/callback`;
+  const verifier = createPkceVerifier();
+  const challenge = createPkceChallenge(verifier);
+  const authorizationUrl = buildAuthorizationUrl({
+    baseUrl,
+    codeChallenge: challenge,
+    redirectUri,
+  });
+
+  console.log(`Opening browser for Knosi login at ${baseUrl} ...`);
+  if (!openUrl(authorizationUrl)) {
+    console.log("Open this URL manually:");
+    console.log(authorizationUrl);
+  }
+
+  const code = await waitForCallback(port);
+  const response = await fetch(`${baseUrl}/api/oauth/token`, {
+    method: "POST",
+    headers: { "Content-Type": "application/x-www-form-urlencoded" },
+    body: new URLSearchParams({
+      grant_type: "authorization_code",
+      client_id: "knosi-cli",
+      code,
+      redirect_uri: redirectUri,
+      code_verifier: verifier,
+    }),
+  });
+
+  if (!response.ok) {
+    throw new Error(`OAuth token exchange failed: ${await response.text()}`);
+  }
+
+  const body = await response.json();
+  await saveConfig({
+    baseUrl,
+    accessToken: body.access_token,
+    refreshToken: body.refresh_token,
+    clientId: "knosi-cli",
+  });
+
+  console.log("✓ Saved Knosi CLI credentials.");
+}

package/src/commands/auth-login.test.mjs

@@ -0,0 +1,17 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { buildAuthorizationUrl, createPkceChallenge } from "./auth-login.mjs";
+
+test("buildAuthorizationUrl encodes the Knosi CLI OAuth request", () => {
+  const url = new URL(
+    buildAuthorizationUrl({
+      baseUrl: "https://www.knosi.xyz",
+      codeChallenge: createPkceChallenge("a".repeat(43)),
+      redirectUri: "http://127.0.0.1:6274/oauth/callback",
+    })
+  );
+
+  assert.equal(url.pathname, "/oauth/authorize");
+  assert.equal(url.searchParams.get("client_id"), "knosi-cli");
+  assert.equal(url.searchParams.get("code_challenge_method"), "S256");
+});

package/src/commands/install-skill.mjs

@@ -0,0 +1,16 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+
+const SKILL_TEMPLATE_PATH = new URL("../../templates/save-to-knosi/SKILL.md", import.meta.url);
+
+export async function runInstallSkill() {
+  const targetDir = path.join(os.homedir(), ".claude", "skills", "save-to-knosi");
+  const targetPath = path.join(targetDir, "SKILL.md");
+  const template = await readFile(SKILL_TEMPLATE_PATH, "utf8");
+
+  await mkdir(targetDir, { recursive: true });
+  await writeFile(targetPath, template, "utf8");
+
+  console.log(`✓ Installed Claude Code skill at ${targetPath}`);
+}

package/src/commands/save-ai-note.mjs

@@ -0,0 +1,34 @@
+import { authorizedFetch } from "../http.mjs";
+
+export async function readStdinJson() {
+  const chunks = [];
+  for await (const chunk of process.stdin) {
+    chunks.push(chunk);
+  }
+  const raw = Buffer.concat(chunks).toString("utf8").trim();
+  if (!raw) {
+    throw new Error("Expected JSON on stdin.");
+  }
+  return JSON.parse(raw);
+}
+
+export async function runSaveAiNote(args) {
+  const useJson = args.includes("--json");
+  if (!useJson) {
+    throw new Error("Use `knosi save-ai-note --json` and pipe the payload on stdin.");
+  }
+
+  const payload = await readStdinJson();
+  const response = await authorizedFetch("/api/integrations/ai-captures", {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(payload),
+  });
+
+  if (!response.ok) {
+    throw new Error(`save-ai-note failed: ${await response.text()}`);
+  }
+
+  const body = await response.json();
+  console.log(JSON.stringify(body, null, 2));
+}

package/src/commands/save-ai-note.test.mjs

@@ -0,0 +1,7 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { readStdinJson } from "./save-ai-note.mjs";
+
+test("save-ai-note exports stdin JSON reader", () => {
+  assert.equal(typeof readStdinJson, "function");
+});

package/src/config.mjs

@@ -0,0 +1,36 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+
+const CONFIG_DIR = path.join(os.homedir(), ".knosi");
+const CONFIG_PATH = path.join(CONFIG_DIR, "cli.json");
+const DEFAULT_BASE_URL = "https://www.knosi.xyz";
+
+export function getConfigPath() {
+  return CONFIG_PATH;
+}
+
+export function getDefaultBaseUrl() {
+  return DEFAULT_BASE_URL;
+}
+
+export async function loadConfig() {
+  try {
+    const content = await readFile(CONFIG_PATH, "utf8");
+    return JSON.parse(content);
+  } catch {
+    return null;
+  }
+}
+
+export async function saveConfig(config) {
+  await mkdir(CONFIG_DIR, { recursive: true });
+  await writeFile(CONFIG_PATH, JSON.stringify(config, null, 2) + "\n", "utf8");
+}
+
+export async function updateConfig(patch) {
+  const current = (await loadConfig()) ?? {};
+  const next = { ...current, ...patch };
+  await saveConfig(next);
+  return next;
+}

package/src/daemon.mjs

@@ -0,0 +1,108 @@
+import { execSync } from "node:child_process";
+import { configure, claimTask, sendHeartbeat } from "./api.mjs";
+import { setClaudeBin } from "./spawn-claude.mjs";
+import { handleChatTask } from "./handler-chat.mjs";
+import { handleStructuredTask } from "./handler-structured.mjs";
+
+function getArg(args, flag) {
+  const idx = args.indexOf(flag);
+  return idx !== -1 && idx + 1 < args.length ? args[idx + 1] : undefined;
+}
+
+function checkClaude(claudeBinArg) {
+  try {
+    const version = execSync(`${claudeBinArg} --version`, { encoding: "utf8" }).trim();
+    console.log(`✓ Claude CLI: ${version}`);
+    return true;
+  } catch {
+    console.error(`✗ Claude CLI not found at "${claudeBinArg}"`);
+    console.error("  Install: npm install -g @anthropic-ai/claude-code");
+    console.error("  Or specify: --claude-bin /path/to/claude");
+    return false;
+  }
+}
+
+function ts() {
+  return new Date().toLocaleTimeString("en-GB", { hour12: false });
+}
+
+export async function runDaemon(args) {
+  const serverUrl = getArg(args, "--url") || "https://second-brain-self-alpha.vercel.app";
+  const isOnce = args.includes("--once");
+  const claudeBinArg = getArg(args, "--claude-bin") || "claude";
+
+  const CHAT_POLL_MS = 2_000;
+  const STRUCTURED_POLL_MS = 1_000;
+  const HEARTBEAT_MS = 120_000;
+  const MAX_CONCURRENT_CHAT = 3;
+  const MAX_CONCURRENT_STRUCTURED = 5;
+
+  configure(serverUrl);
+  setClaudeBin(claudeBinArg);
+
+  if (!checkClaude(claudeBinArg)) process.exit(1);
+
+  let chatRunning = 0;
+  let structuredRunning = 0;
+
+  async function pollChat() {
+    if (chatRunning >= MAX_CONCURRENT_CHAT) return;
+    try {
+      const task = await claimTask("chat");
+      if (!task) return;
+      chatRunning++;
+      handleChatTask(task)
+        .catch(() => {})
+        .finally(() => {
+          chatRunning--;
+        });
+    } catch {}
+  }
+
+  async function pollStructured() {
+    if (structuredRunning >= MAX_CONCURRENT_STRUCTURED) return;
+    try {
+      const task = await claimTask("structured");
+      if (!task) return;
+      structuredRunning++;
+      handleStructuredTask(task)
+        .catch(() => {})
+        .finally(() => {
+          structuredRunning--;
+        });
+    } catch {}
+  }
+
+  if (isOnce) {
+    console.log("🔍 Single-run mode...");
+    await pollChat();
+    await pollStructured();
+    console.log("Done.");
+    return;
+  }
+
+  console.log("");
+  console.log("🚀 Knosi AI Daemon");
+  console.log(`   Server: ${serverUrl}`);
+  console.log(
+    `   Chat poll: ${CHAT_POLL_MS / 1000}s | Structured poll: ${STRUCTURED_POLL_MS / 1000}s`
+  );
+  console.log(
+    `   Max concurrent: chat=${MAX_CONCURRENT_CHAT} structured=${MAX_CONCURRENT_STRUCTURED}`
+  );
+  console.log("");
+  console.log("   Waiting for tasks... (Ctrl+C to stop)");
+  console.log("");
+
+  await sendHeartbeat("daemon");
+  setInterval(() => sendHeartbeat("daemon"), HEARTBEAT_MS);
+  setInterval(pollChat, CHAT_POLL_MS);
+  setInterval(pollStructured, STRUCTURED_POLL_MS);
+
+  for (const sig of ["SIGINT", "SIGTERM"]) {
+    process.on(sig, () => {
+      console.log(`\n[${ts()}] daemon stopped`);
+      process.exit(0);
+    });
+  }
+}

package/src/http.mjs

@@ -0,0 +1,58 @@
+import { loadConfig, saveConfig } from "./config.mjs";
+
+async function refreshAccessToken(config) {
+  if (!config?.refreshToken || !config?.baseUrl) {
+    return null;
+  }
+
+  const response = await fetch(`${config.baseUrl}/api/oauth/token`, {
+    method: "POST",
+    headers: { "Content-Type": "application/x-www-form-urlencoded" },
+    body: new URLSearchParams({
+      grant_type: "refresh_token",
+      client_id: "knosi-cli",
+      refresh_token: config.refreshToken,
+    }),
+  });
+
+  if (!response.ok) {
+    return null;
+  }
+
+  const body = await response.json();
+  const nextConfig = {
+    ...config,
+    accessToken: body.access_token,
+  };
+  await saveConfig(nextConfig);
+  return nextConfig;
+}
+
+export async function authorizedFetch(pathname, init = {}) {
+  let config = await loadConfig();
+  if (!config?.accessToken || !config?.baseUrl) {
+    throw new Error("Not logged in. Run `knosi auth login` first.");
+  }
+
+  const makeRequest = async (token) =>
+    fetch(`${config.baseUrl}${pathname}`, {
+      ...init,
+      headers: {
+        ...(init.headers ?? {}),
+        Authorization: `Bearer ${token}`,
+      },
+    });
+
+  let response = await makeRequest(config.accessToken);
+  if (response.status !== 401) {
+    return response;
+  }
+
+  config = await refreshAccessToken(config);
+  if (!config?.accessToken) {
+    return response;
+  }
+
+  response = await makeRequest(config.accessToken);
+  return response;
+}

package/src/index.mjs

@@ -1,118 +1,42 @@
 #!/usr/bin/env node
-/**
- * @knosi/cli — Local Claude Code daemon for Second Brain
- *
- * Usage:
- *   npx @knosi/cli --url https://your-instance.vercel.app
- *   npx @knosi/cli --once
- */
-import { execSync } from "node:child_process";
-import { configure, claimTask, sendHeartbeat } from "./api.mjs";
-import { setClaudeBin } from "./spawn-claude.mjs";
-import { handleChatTask } from "./handler-chat.mjs";
-import { handleStructuredTask } from "./handler-structured.mjs";
+import { runAuthLogin } from "./commands/auth-login.mjs";
+import { runInstallSkill } from "./commands/install-skill.mjs";
+import { runSaveAiNote } from "./commands/save-ai-note.mjs";
+import { runDaemon } from "./daemon.mjs";
 
-// ── Parse args ──────────────────────────────────────────────────────────
 const args = process.argv.slice(2);
+const [command, subcommand, ...rest] = args;
 
-function getArg(flag) {
-  const idx = args.indexOf(flag);
-  return idx !== -1 && idx + 1 < args.length ? args[idx + 1] : undefined;
-}
-
-const serverUrl = getArg("--url") || "https://second-brain-self-alpha.vercel.app";
-const isOnce = args.includes("--once");
-const claudeBinArg = getArg("--claude-bin") || "claude";
-
-const CHAT_POLL_MS = 2_000;
-const STRUCTURED_POLL_MS = 1_000;
-const HEARTBEAT_MS = 120_000;
-const MAX_CONCURRENT_CHAT = 3;
-const MAX_CONCURRENT_STRUCTURED = 5;
-
-// ── Preflight ───────────────────────────────────────────────────────────
-function checkClaude() {
-  try {
-    const version = execSync(`${claudeBinArg} --version`, { encoding: "utf8" }).trim();
-    console.log(`✓ Claude CLI: ${version}`);
-    return true;
-  } catch {
-    console.error(`✗ Claude CLI not found at "${claudeBinArg}"`);
-    console.error("  Install: npm install -g @anthropic-ai/claude-code");
-    console.error("  Or specify: --claude-bin /path/to/claude");
-    return false;
+async function main() {
+  if (!command || command.startsWith("--")) {
+    await runDaemon(args);
+    return;
   }
-}
-
-// ── Main ────────────────────────────────────────────────────────────────
-configure(serverUrl);
-setClaudeBin(claudeBinArg);
-
-if (!checkClaude()) process.exit(1);
-
-function ts() {
-  return new Date().toLocaleTimeString("en-GB", { hour12: false });
-}
 
-let chatRunning = 0;
-let structuredRunning = 0;
-
-async function pollChat() {
-  if (chatRunning >= MAX_CONCURRENT_CHAT) return;
-  try {
-    const task = await claimTask("chat");
-    if (!task) return;
-    chatRunning++;
-    handleChatTask(task)
-      .catch(() => {})
-      .finally(() => { chatRunning--; });
-  } catch {
-    // server unreachable
+  if (command === "daemon") {
+    await runDaemon([subcommand, ...rest].filter(Boolean));
+    return;
   }
-}
 
-async function pollStructured() {
-  if (structuredRunning >= MAX_CONCURRENT_STRUCTURED) return;
-  try {
-    const task = await claimTask("structured");
-    if (!task) return;
-    structuredRunning++;
-    handleStructuredTask(task)
-      .catch(() => {})
-      .finally(() => { structuredRunning--; });
-  } catch {
-    // server unreachable
+  if (command === "auth" && subcommand === "login") {
+    await runAuthLogin(rest);
+    return;
   }
-}
-
-if (isOnce) {
-  console.log("🔍 Single-run mode...");
-  await pollChat();
-  await pollStructured();
-  console.log("Done.");
-} else {
-  console.log("");
-  console.log("🚀 Knosi AI Daemon");
-  console.log(`   Server: ${serverUrl}`);
-  console.log(`   Chat poll: ${CHAT_POLL_MS / 1000}s | Structured poll: ${STRUCTURED_POLL_MS / 1000}s`);
-  console.log(`   Max concurrent: chat=${MAX_CONCURRENT_CHAT} structured=${MAX_CONCURRENT_STRUCTURED}`);
-  console.log("");
-  console.log("   Waiting for tasks... (Ctrl+C to stop)");
-  console.log("");
 
-  // Heartbeat
-  await sendHeartbeat("daemon");
-  setInterval(() => sendHeartbeat("daemon"), HEARTBEAT_MS);
-
-  // Poll loops
-  setInterval(pollChat, CHAT_POLL_MS);
-  setInterval(pollStructured, STRUCTURED_POLL_MS);
+  if (command === "save-ai-note") {
+    await runSaveAiNote([subcommand, ...rest].filter(Boolean));
+    return;
+  }
 
-  // Graceful shutdown
-  for (const sig of ["SIGINT", "SIGTERM"]) {
-    process.on(sig, () => {
-      console.log(`\n[${ts()}] daemon stopped`);
-      process.exit(0);
-    });
+  if (command === "install-skill") {
+    await runInstallSkill();
+    return;
   }
+
+  throw new Error(`Unknown command: ${args.join(" ")}`);
 }
+
+main().catch((error) => {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exit(1);
+});

package/templates/save-to-knosi/SKILL.md

@@ -0,0 +1,21 @@
+---
+name: save-to-knosi
+description: Save the current Claude Code exchange into Knosi as one raw AI Inbox note. Use only when the user explicitly asks to save or archive something to Knosi.
+---
+
+When the user explicitly asks to save the current exchange to Knosi:
+
+1. Collect the message excerpt that should be saved.
+2. Build JSON with:
+   - `sourceApp`: `claude-code`
+   - `title` if the user provided one
+   - `messages`: the raw user/assistant turns to preserve
+   - `sourceMeta.projectPath` when it is useful
+3. Run:
+
+```bash
+knosi save-ai-note --json
+```
+
+4. Pipe the JSON payload to stdin.
+5. After the command succeeds, reply with the created note id or title.