ricord 1.0.0

package/dist/scripts/utils.js

@@ -0,0 +1,165 @@
+/**
+ * Shared utilities for Ricord scripts.
+ *
+ * Helpers for state tracking, file hashing, daily log manipulation,
+ * credential scrubbing, and JSONL transcript parsing.
+ */
+import { readFileSync, writeFileSync, existsSync, mkdirSync, readdirSync, appendFileSync } from "node:fs";
+import { createHash } from "node:crypto";
+import { join } from "node:path";
+import { execSync } from "node:child_process";
+import { STATE_FILE, FLUSH_STATE_FILE, DAILY_DIR, FLUSH_LOG_FILE } from "./config.js";
+export function loadState() {
+    try {
+        if (existsSync(STATE_FILE)) {
+            return JSON.parse(readFileSync(STATE_FILE, "utf8"));
+        }
+    }
+    catch { }
+    return { ingested: {}, total_cost: 0, query_count: 0, last_lint: "" };
+}
+export function saveState(state) {
+    const dir = join(STATE_FILE, "..");
+    if (!existsSync(dir))
+        mkdirSync(dir, { recursive: true });
+    writeFileSync(STATE_FILE, JSON.stringify(state, null, 2), "utf8");
+}
+export function loadFlushState() {
+    try {
+        if (existsSync(FLUSH_STATE_FILE)) {
+            return JSON.parse(readFileSync(FLUSH_STATE_FILE, "utf8"));
+        }
+    }
+    catch { }
+    return null;
+}
+export function saveFlushState(state) {
+    const dir = join(FLUSH_STATE_FILE, "..");
+    if (!existsSync(dir))
+        mkdirSync(dir, { recursive: true });
+    writeFileSync(FLUSH_STATE_FILE, JSON.stringify(state), "utf8");
+}
+// ── File hashing ─────────────────────────────────────────────────────
+export function fileHash(path) {
+    const content = readFileSync(path);
+    return createHash("sha256").update(content).digest("hex").slice(0, 16);
+}
+// ── Daily log operations ─────────────────────────────────────────────
+export function ensureDailyDir() {
+    if (!existsSync(DAILY_DIR))
+        mkdirSync(DAILY_DIR, { recursive: true });
+}
+export function todayLogPath() {
+    const today = new Date().toLocaleDateString("en-CA"); // YYYY-MM-DD
+    return join(DAILY_DIR, `${today}.md`);
+}
+export function appendToDailyLog(content, section = "Session") {
+    ensureDailyDir();
+    const logPath = todayLogPath();
+    const today = new Date().toLocaleDateString("en-CA");
+    if (!existsSync(logPath)) {
+        writeFileSync(logPath, `# Daily Log: ${today}\n\n## Sessions\n\n## Memory Maintenance\n\n`, "utf8");
+    }
+    const timeStr = new Date().toLocaleTimeString("en-GB", { hour: "2-digit", minute: "2-digit" });
+    const entry = `### ${section} (${timeStr})\n\n${content}\n\n`;
+    appendFileSync(logPath, entry, "utf8");
+}
+export function listDailyLogs() {
+    ensureDailyDir();
+    return readdirSync(DAILY_DIR)
+        .filter(f => f.endsWith(".md"))
+        .sort();
+}
+export function extractConversation(transcriptPath, maxTurns = 30, maxChars = 15_000) {
+    const allTurns = [];
+    const content = readFileSync(transcriptPath, "utf8");
+    for (const line of content.split("\n")) {
+        if (!line.trim())
+            continue;
+        try {
+            const entry = JSON.parse(line);
+            const msg = entry.message || entry;
+            const role = msg.role || "";
+            let text = msg.content || "";
+            if (!["user", "assistant"].includes(role))
+                continue;
+            if (Array.isArray(text)) {
+                text = text
+                    .filter((b) => typeof b === "string" || (b.type === "text" && b.text))
+                    .map((b) => (typeof b === "string" ? b : b.text))
+                    .join("\n");
+            }
+            if (typeof text === "string" && text.trim()) {
+                allTurns.push({ role: role, text: text.trim() });
+            }
+        }
+        catch {
+            continue;
+        }
+    }
+    const recent = allTurns.slice(-maxTurns);
+    let context = recent
+        .map(t => `**${t.role === "user" ? "User" : "Assistant"}:** ${t.text}`)
+        .join("\n\n");
+    if (context.length > maxChars) {
+        context = context.slice(-maxChars);
+        const boundary = context.indexOf("\n**");
+        if (boundary > 0)
+            context = context.slice(boundary + 1);
+    }
+    return { turns: recent, context, turnCount: recent.length };
+}
+// ── Credential scrubbing ─────────────────────────────────────────────
+const SCRUB_PATTERNS = [
+    /sk-[a-zA-Z0-9]{20,}/g, // OpenAI
+    /AKIA[A-Z0-9]{16}/g, // AWS
+    /ghp_[a-zA-Z0-9]{36,}/g, // GitHub
+    /gho_[a-zA-Z0-9]{36,}/g, // GitHub OAuth
+    /rc_(?:live|test)_[a-zA-Z0-9_]{10,}/g, // Ricord
+    /Bearer\s+[a-zA-Z0-9._\-]{20,}/gi, // Bearer tokens
+    /(?:api[_-]?key|password|secret|token)\s*[:=]\s*["']?[^\s"']{8,}/gi, // Generic secrets
+    /[a-zA-Z0-9+/]{40,200}={0,2}/g, // Base64 blobs
+];
+export function scrubCredentials(text) {
+    let result = text;
+    for (const pattern of SCRUB_PATTERNS) {
+        result = result.replace(pattern, "[REDACTED]");
+    }
+    return result;
+}
+// ── Git helpers ──────────────────────────────────────────────────────
+export function detectProject() {
+    try {
+        const remote = execSync("git remote get-url origin 2>/dev/null", { encoding: "utf8" }).trim();
+        const match = remote.match(/\/([^/]+?)(?:\.git)?$/);
+        return match?.[1] || "";
+    }
+    catch {
+        return "";
+    }
+}
+export function detectGitRepo() {
+    try {
+        return execSync("git remote get-url origin 2>/dev/null", { encoding: "utf8" }).trim();
+    }
+    catch {
+        return "";
+    }
+}
+export function detectGitBranch() {
+    try {
+        return execSync("git rev-parse --abbrev-ref HEAD 2>/dev/null", { encoding: "utf8" }).trim();
+    }
+    catch {
+        return "";
+    }
+}
+// ── Logging ──────────────────────────────────────────────────────────
+export function logToFile(message, file = FLUSH_LOG_FILE) {
+    const timestamp = new Date().toISOString().slice(0, 19).replace("T", " ");
+    const dir = join(file, "..");
+    if (!existsSync(dir))
+        mkdirSync(dir, { recursive: true });
+    appendFileSync(file, `${timestamp} ${message}\n`, "utf8");
+}
+//# sourceMappingURL=utils.js.map

package/dist/scripts/utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.js","sourceRoot":"","sources":["../../src/scripts/utils.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,74 @@
+{
+  "name": "ricord",
+  "version": "1.0.0",
+  "description": "Ricord — knowledge wiki, auto-organized. Ships an MCP server (`ricord-mcp`) and a wiki authoring CLI (`ricord build`, `ricord push`, `ricord compile`, …).",
+  "type": "module",
+  "bin": {
+    "ricord-mcp": "dist/index.js",
+    "ricord": "dist/cli/cli.js"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "commands",
+    "scripts/postinstall.mjs",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsx src/index.ts",
+    "dev:cli": "tsx src/cli/cli.ts",
+    "start": "node dist/index.js",
+    "flush": "node dist/scripts/flush.js",
+    "compile": "node dist/scripts/compile.js",
+    "lint:kb": "node dist/scripts/lint.js",
+    "compile:all": "node dist/scripts/compile.js --all",
+    "compile:dry-run": "node dist/scripts/compile.js --dry-run",
+    "lint:kb:structural": "node dist/scripts/lint.js --structural-only",
+    "test": "vitest run",
+    "test:smoke": "tsx src/index.ts --help || true",
+    "postinstall": "node scripts/postinstall.mjs",
+    "prepublishOnly": "npm run build && npm test"
+  },
+  "keywords": [
+    "ricord",
+    "mcp",
+    "memory",
+    "knowledge",
+    "ai",
+    "claude-code",
+    "cursor",
+    "windsurf",
+    "vscode",
+    "model-context-protocol",
+    "persistent-memory",
+    "knowledge-graph"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ricord-ai/ricord-mcp.git"
+  },
+  "homepage": "https://ricord.ai",
+  "bugs": {
+    "url": "https://github.com/ricord-ai/ricord-mcp/issues"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "publishConfig": {},
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.1",
+    "ignore": "^5.3.1",
+    "kleur": "^4.1.5",
+    "typescript": "^5.7.0",
+    "zod": "^3.23.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "tsx": "^4.19.0",
+    "vitest": "^4.1.5"
+  }
+}

package/scripts/postinstall.mjs

@@ -0,0 +1,56 @@
+#!/usr/bin/env node
+// Best-effort: copy bundled slash commands into ~/.claude/commands/ on install.
+// Never fails the install — prints a hint on error and exits 0.
+
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+function main() {
+  try {
+    if (process.env.RICORD_SKIP_POSTINSTALL === "1") return 0;
+    if (process.env.CI === "true" && process.env.RICORD_FORCE_POSTINSTALL !== "1") return 0;
+
+    const here = path.dirname(fileURLToPath(import.meta.url));
+    const sourceDir = path.resolve(here, "..", "commands");
+    if (!fs.existsSync(sourceDir)) return 0;
+
+    const home = os.homedir();
+    if (!home) return 0;
+
+    const claudeDir = path.join(home, ".claude");
+    if (!fs.existsSync(claudeDir)) return 0;
+
+    const targetDir = path.join(claudeDir, "commands");
+    fs.mkdirSync(targetDir, { recursive: true });
+
+    const files = fs.readdirSync(sourceDir).filter((f) => f.endsWith(".md"));
+    let installed = 0;
+    let updated = 0;
+    for (const f of files) {
+      const src = path.join(sourceDir, f);
+      const dst = path.join(targetDir, f);
+      const newContent = fs.readFileSync(src, "utf8");
+      if (fs.existsSync(dst)) {
+        const oldContent = fs.readFileSync(dst, "utf8");
+        if (oldContent === newContent) continue;
+        updated++;
+      } else {
+        installed++;
+      }
+      fs.writeFileSync(dst, newContent, "utf8");
+    }
+    if (installed + updated > 0) {
+      console.log(`[ricord] installed ${installed} + updated ${updated} Claude Code slash command(s) into ${targetDir}`);
+      console.log(`[ricord] restart Claude Code to pick them up. Disable with RICORD_SKIP_POSTINSTALL=1.`);
+    }
+    return 0;
+  } catch (err) {
+    const msg = err && err.message ? err.message : String(err);
+    console.log(`[ricord] postinstall skipped (${msg}). Run 'ricord install-commands' to install slash commands.`);
+    return 0;
+  }
+}
+
+process.exit(main());