@repomem/memory 0.0.0-stage → 0.1.0

package/dist/validate.js

@@ -0,0 +1,164 @@
+/**
+ * validate.ts — pure validation logic for `repomem validate`.
+ *
+ * Checks performed:
+ *  1. Every `.md` entry under the memory root has valid frontmatter.
+ *  2. Every `supersedes` reference points at an existing entry id.
+ *  3. No obvious secrets (API keys, tokens, private keys) appear in any entry.
+ *
+ * This module is I/O-light and returns a structured report; the CLI decides
+ * the process exit code. Nothing here writes to stdout.
+ */
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import matter from "gray-matter";
+import { frontmatterSchema, TYPE_DIRS, ENTRY_TYPES, } from "./schema.js";
+/**
+ * High-confidence secret patterns. Tuned to minimize false positives; this is
+ * a safety net, not a replacement for a dedicated secret scanner.
+ */
+export const SECRET_PATTERNS = [
+    { rule: "aws-access-key-id", re: /\bAKIA[0-9A-Z]{16}\b/ },
+    { rule: "github-token", re: /\bgh[pousr]_[A-Za-z0-9]{36,}\b/ },
+    { rule: "slack-token", re: /\bxox[baprs]-[A-Za-z0-9-]{10,}\b/ },
+    { rule: "google-api-key", re: /\bAIza[0-9A-Za-z_\-]{35}\b/ },
+    { rule: "private-key-block", re: /-----BEGIN (?:RSA |EC |OPENSSH |DSA |PGP )?PRIVATE KEY-----/ },
+    {
+        rule: "generic-secret-assignment",
+        // key-like name = long opaque value (>= 16 chars, no spaces)
+        re: /\b(?:api[_-]?key|secret|token|passwd|password|access[_-]?key)\b\s*[:=]\s*["']?[A-Za-z0-9+/_\-]{16,}["']?/i,
+    },
+];
+/** Scan a block of text for secrets, returning one finding per match line. */
+export function scanSecrets(text, file) {
+    const findings = [];
+    const lines = text.split(/\r?\n/);
+    lines.forEach((lineText, idx) => {
+        for (const { rule, re } of SECRET_PATTERNS) {
+            if (re.test(lineText)) {
+                findings.push({
+                    severity: "error",
+                    file,
+                    line: idx + 1,
+                    rule: `secret:${rule}`,
+                    message: `possible secret detected (${rule})`,
+                });
+            }
+        }
+    });
+    return findings;
+}
+/** Collect every .md file under the memory root, grouped by its folder type. */
+async function collectFiles(root) {
+    const out = [];
+    for (const type of ENTRY_TYPES) {
+        const dir = path.join(root, TYPE_DIRS[type]);
+        let names;
+        try {
+            names = await fs.readdir(dir);
+        }
+        catch {
+            continue;
+        }
+        for (const name of names) {
+            if (name.endsWith(".md"))
+                out.push({ file: path.join(dir, name), type });
+        }
+    }
+    return out;
+}
+/**
+ * Validate every entry under `root`. Returns a structured report. `ok` is true
+ * only when there are no error-severity findings.
+ */
+export async function validateRoot(root) {
+    const findings = [];
+    const files = await collectFiles(root);
+    const validEntries = [];
+    const knownIds = new Set();
+    for (const { file, type } of files) {
+        const id = path.basename(file, ".md");
+        let raw;
+        try {
+            raw = await fs.readFile(file, "utf8");
+        }
+        catch (err) {
+            findings.push({
+                severity: "error",
+                file,
+                rule: "io",
+                message: `could not read file: ${err.message}`,
+            });
+            continue;
+        }
+        // Secret scan runs over the whole file regardless of frontmatter validity.
+        findings.push(...scanSecrets(raw, file));
+        let parsed;
+        try {
+            parsed = matter(raw);
+        }
+        catch (err) {
+            findings.push({
+                severity: "error",
+                file,
+                rule: "frontmatter",
+                message: `unparseable frontmatter: ${err.message}`,
+            });
+            continue;
+        }
+        const result = frontmatterSchema.safeParse(parsed.data);
+        if (!result.success) {
+            for (const issue of result.error.issues) {
+                findings.push({
+                    severity: "error",
+                    file,
+                    rule: "frontmatter",
+                    message: `${issue.path.join(".") || "(root)"}: ${issue.message}`,
+                });
+            }
+            continue;
+        }
+        if (result.data.type !== type) {
+            findings.push({
+                severity: "error",
+                file,
+                rule: "type-folder-mismatch",
+                message: `declared type "${result.data.type}" does not match folder "${TYPE_DIRS[type]}"`,
+            });
+            continue;
+        }
+        knownIds.add(id);
+        validEntries.push({ file, id, type, data: result.data, raw });
+    }
+    // supersedes references must resolve to a known id.
+    for (const entry of validEntries) {
+        const supersedes = entry.data.supersedes;
+        if (supersedes && !knownIds.has(supersedes)) {
+            findings.push({
+                severity: "error",
+                file: entry.file,
+                rule: "dangling-supersedes",
+                message: `supersedes "${supersedes}" does not match any existing entry id`,
+            });
+        }
+    }
+    const ok = !findings.some((f) => f.severity === "error");
+    return { findings, checked: files.length, ok };
+}
+/** Format a report as human-readable lines (for stderr/stdout in the CLI). */
+export function formatReport(report, root) {
+    const lines = [];
+    lines.push(`Validated ${report.checked} entr${report.checked === 1 ? "y" : "ies"} under ${root}`);
+    if (report.findings.length === 0) {
+        lines.push("No issues found.");
+        return lines.join("\n");
+    }
+    for (const f of report.findings) {
+        const where = f.line ? `${f.file}:${f.line}` : f.file;
+        lines.push(`  [${f.severity}] ${where} (${f.rule}): ${f.message}`);
+    }
+    const errors = report.findings.filter((f) => f.severity === "error").length;
+    lines.push(`${errors} error(s), ${report.findings.length - errors} warning(s).`);
+    return lines.join("\n");
+}
+//# sourceMappingURL=validate.js.map

package/dist/validate.js.map

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

package/package.json

@@ -1,6 +1,68 @@
 {
   "name": "@repomem/memory",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Your repo's memory, available to every AI tool your team uses. A local MCP server that turns a memory/ folder into searchable shared context.",
+  "license": "MIT",
+  "author": "Nicolás Rickert",
+  "type": "module",
+  "engines": {
+    "node": ">=22"
+  },
+  "bin": {
+    "repomem": "dist/cli.js"
+  },
+  "main": "dist/index.js",
+  "exports": {
+    ".": "./dist/index.js"
+  },
+  "files": [
+    "dist",
+    "templates",
+    "assets",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nicorickert/repomem.git",
+    "directory": "packages/memory"
+  },
+  "homepage": "https://github.com/nicorickert/repomem/tree/main/packages/memory#readme",
+  "bugs": {
+    "url": "https://github.com/nicorickert/repomem/issues"
+  },
+  "keywords": [
+    "repomem",
+    "mcp",
+    "memory",
+    "ai",
+    "context",
+    "model-context-protocol"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "clean": "rm -rf dist",
+    "start": "node dist/index.js",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.32.0",
+    "@repomem/core": "^0.1.0",
+    "fast-glob": "^3.3.2",
+    "gray-matter": "^4.0.3",
+    "minisearch": "^7.1.0",
+    "picomatch": "^4.0.2",
+    "zod": "^4.6.5"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "@types/picomatch": "^3.0.1",
+    "typescript": "^5.6.0",
+    "vitest": "^4.1.11"
+  }
+}

package/templates/context.md

@@ -0,0 +1,25 @@
+---
+type: context
+title: Short context title
+status: draft
+date: 2026-01-01
+scope: project
+tags: []
+related_paths: []
+---
+
+## What this is
+
+The project or module this entry describes, in a sentence or two.
+
+## Why it exists
+
+The purpose, the problem it solves, and who it serves.
+
+## How it works
+
+The shape of the thing: main components, flows, and how they fit together.
+
+## Key constraints
+
+Boundaries, assumptions, and things to keep in mind when working here.

package/templates/convention.md

@@ -0,0 +1,16 @@
+---
+type: convention
+title: Short convention title
+status: draft
+date: 2026-01-01
+tags: []
+related_paths: []
+---
+
+## Rule
+
+State the convention as a clear, actionable rule.
+
+## Rationale
+
+Why this convention exists and what it prevents.

package/templates/decision.md

@@ -0,0 +1,20 @@
+---
+type: decision
+title: Short decision title
+status: draft
+date: 2026-01-01
+tags: []
+related_paths: []
+---
+
+## Context
+
+What problem or situation prompted this decision?
+
+## Decision
+
+What did we decide, stated plainly?
+
+## Consequences
+
+What follows from this — tradeoffs, follow-ups, things to watch.

package/templates/learning.md

@@ -0,0 +1,16 @@
+---
+type: learning
+title: Short learning title
+status: draft
+date: 2026-01-01
+tags: []
+related_paths: []
+---
+
+## What happened
+
+The situation and what surprised us.
+
+## Takeaway
+
+The durable lesson worth remembering.

package/templates/limitation.md

@@ -0,0 +1,16 @@
+---
+type: limitation
+title: Short limitation title
+status: draft
+date: 2026-01-01
+tags: []
+related_paths: []
+---
+
+## Limitation
+
+What the system cannot (currently) do, or where it breaks down.
+
+## Impact / Workaround
+
+Who it affects and how to work around it, if at all.