@10kdevs/matha 0.1.0

package/dist/storage/reader.js

@@ -0,0 +1,29 @@
+import * as fs from 'fs/promises';
+/**
+ * Reads and parses a JSON file.
+ *
+ * Throws if the file does not exist or contains invalid JSON.
+ * Use {@link readJsonOrNull} when a missing file is an expected case.
+ */
+export async function readJson(filePath) {
+    const content = await fs.readFile(filePath, 'utf-8');
+    return JSON.parse(content);
+}
+/**
+ * Reads and parses a JSON file, returning `null` when the file is absent.
+ *
+ * - Returns `null` if the file (or any parent directory) does not exist.
+ * - **Never throws on missing files.**
+ * - Still throws on invalid JSON — that is a data-integrity issue, not a
+ *   missing-file issue.
+ */
+export async function readJsonOrNull(filePath) {
+    try {
+        return await readJson(filePath);
+    }
+    catch (err) {
+        if (err.code === 'ENOENT')
+            return null;
+        throw err;
+    }
+}

package/dist/storage/writer.js

@@ -0,0 +1,111 @@
+import * as fs from 'fs/promises';
+import * as path from 'path';
+import * as crypto from 'crypto';
+/**
+ * Atomically writes JSON data to a file.
+ *
+ * Pattern: serialize → validate → write to .tmp → rename to final path.
+ * Never writes directly to the target file.
+ *
+ * @param filePath  Absolute path to the target file.
+ * @param data      Data to serialize as JSON. Must be JSON-serializable.
+ * @param options.overwrite  If true, replaces an existing file. Default: false.
+ */
+export async function writeAtomic(filePath, data, options) {
+    // ── 1. Validate JSON serialization ────────────────────────────
+    let json;
+    try {
+        json = JSON.stringify(data, null, 2);
+    }
+    catch (err) {
+        throw new Error(`Data is not JSON-serializable: ${err.message}`);
+    }
+    if (typeof json !== 'string') {
+        throw new Error('Data cannot be serialized to JSON');
+    }
+    // ── 2. Guard against silent overwrite ─────────────────────────
+    if (!options?.overwrite) {
+        let exists = true;
+        try {
+            await fs.access(filePath);
+        }
+        catch {
+            exists = false;
+        }
+        if (exists) {
+            throw new Error(`File already exists and overwrite is not enabled: ${filePath}`);
+        }
+    }
+    // ── 3. Ensure parent directories exist ────────────────────────
+    await fs.mkdir(path.dirname(filePath), { recursive: true });
+    // ── 4. Atomic write: temp file → rename ───────────────────────
+    const tmpSuffix = `${process.pid}.${crypto.randomBytes(4).toString('hex')}.tmp`;
+    const tmpPath = `${filePath}.${tmpSuffix}`;
+    try {
+        await fs.writeFile(tmpPath, json, 'utf-8');
+        await fs.rename(tmpPath, filePath);
+    }
+    catch (err) {
+        // Best-effort cleanup of the temp file
+        try {
+            await fs.unlink(tmpPath);
+        }
+        catch {
+            /* ignore cleanup errors */
+        }
+        throw err;
+    }
+}
+/**
+ * Appends an item to a JSON array file.
+ *
+ * - Creates the file with `[item]` if it does not yet exist.
+ * - Throws if the existing file does not contain a JSON array.
+ * - Uses the atomic-write pattern internally.
+ */
+export async function appendToArray(filePath, item) {
+    let existing = [];
+    try {
+        const raw = await fs.readFile(filePath, 'utf-8');
+        const parsed = JSON.parse(raw);
+        if (!Array.isArray(parsed)) {
+            throw new Error(`Cannot append to non-array. File contains ${typeof parsed}`);
+        }
+        existing = parsed;
+    }
+    catch (err) {
+        if (err.code !== 'ENOENT')
+            throw err;
+        // File does not exist — start with an empty array
+    }
+    existing.push(item);
+    await writeAtomic(filePath, existing, { overwrite: true });
+}
+/**
+ * Shallow-merges a partial object into a JSON object file.
+ *
+ * - Creates the file with `partial` if it does not yet exist.
+ * - Throws if the existing file is not a plain JSON object (rejects arrays
+ *   and primitives).
+ * - Uses the atomic-write pattern internally.
+ */
+export async function mergeObject(filePath, partial) {
+    let existing = {};
+    try {
+        const raw = await fs.readFile(filePath, 'utf-8');
+        const parsed = JSON.parse(raw);
+        if (typeof parsed !== 'object' ||
+            parsed === null ||
+            Array.isArray(parsed)) {
+            throw new Error(`Cannot merge into non-object. File contains ${Array.isArray(parsed) ? 'array' : typeof parsed}`);
+        }
+        existing = parsed;
+    }
+    catch (err) {
+        if (err.code !== 'ENOENT')
+            throw err;
+        // File does not exist — start with an empty object
+    }
+    const merged = { ...existing, ...partial };
+    await writeAtomic(filePath, merged, { overwrite: true });
+}

package/dist/utils/markdown-parser.js

@@ -0,0 +1,173 @@
+import * as fs from 'fs/promises';
+import * as path from 'path';
+// ──────────────────────────────────────────────────────────────
+// HEADING KEYWORD GROUPS (case-insensitive substring match)
+// ──────────────────────────────────────────────────────────────
+const WHY_KEYWORDS = ['overview', 'purpose', 'why', 'problem', 'about'];
+const RULES_KEYWORDS = [
+    'business rules',
+    'non-negotiable',
+    'constraints',
+    'requirements',
+    'rules',
+];
+const BOUNDARIES_KEYWORDS = [
+    'out of scope',
+    'not in scope',
+    'exclusions',
+    'not doing',
+    'boundaries',
+    'limitations',
+];
+const OWNER_KEYWORDS = ['owner', 'team', 'contact', 'maintainer'];
+const SUPPORTED_EXTENSIONS = new Set(['.md', '.txt']);
+/**
+ * Parse a markdown or text file and extract brain seed data.
+ *
+ * **Throws** only on:
+ * - File not found
+ * - Unsupported file extension
+ *
+ * **Never throws** on parse failures — returns empty/partial seed.
+ */
+export async function parseMarkdownFile(filepath) {
+    // Validate extension
+    const ext = path.extname(filepath).toLowerCase();
+    if (!SUPPORTED_EXTENSIONS.has(ext)) {
+        throw new Error('Only .md and .txt files are supported');
+    }
+    // Read file (throws on not found)
+    let content;
+    try {
+        content = await fs.readFile(filepath, 'utf-8');
+    }
+    catch (err) {
+        if (err.code === 'ENOENT') {
+            throw new Error(`File not found: ${filepath}`);
+        }
+        throw err;
+    }
+    // Parse — never throw from here
+    try {
+        return parseContent(content);
+    }
+    catch {
+        return { why: null, rules: [], boundaries: [], owner: null };
+    }
+}
+/**
+ * Split markdown content into sections keyed by heading.
+ * Returns an array of { heading, lines } where lines are the
+ * content lines under that heading (not including the heading itself).
+ * The first section has heading '' (content before any heading).
+ */
+function splitSections(content) {
+    const lines = content.split('\n');
+    const sections = [];
+    let current = { heading: '', lines: [] };
+    for (const line of lines) {
+        const headingMatch = line.match(/^#{1,6}\s+(.+)$/);
+        if (headingMatch) {
+            sections.push(current);
+            current = { heading: headingMatch[1].trim(), lines: [] };
+        }
+        else {
+            current.lines.push(line);
+        }
+    }
+    sections.push(current);
+    return sections;
+}
+/**
+ * Find a section whose heading contains one of the given keywords
+ * (case-insensitive substring match).
+ */
+function findSection(sections, keywords) {
+    for (const section of sections) {
+        const lower = section.heading.toLowerCase();
+        for (const kw of keywords) {
+            if (lower.includes(kw)) {
+                return section;
+            }
+        }
+    }
+    return null;
+}
+/**
+ * Extract the first non-empty paragraph (consecutive non-blank lines)
+ * from an array of lines.
+ */
+function firstParagraph(lines) {
+    const paraLines = [];
+    let started = false;
+    for (const line of lines) {
+        const trimmed = line.trim();
+        if (trimmed === '') {
+            if (started)
+                break;
+            continue;
+        }
+        // Skip bullet lines
+        if (/^[-*]\s+/.test(trimmed)) {
+            if (started)
+                break;
+            continue;
+        }
+        started = true;
+        paraLines.push(trimmed);
+    }
+    return paraLines.length > 0 ? paraLines.join(' ') : null;
+}
+/**
+ * Extract all bullet points (- item or * item) from an array of lines.
+ * Strips leading -/* and whitespace.
+ */
+function extractBullets(lines) {
+    const bullets = [];
+    for (const line of lines) {
+        const match = line.match(/^\s*[-*]\s+(.+)$/);
+        if (match) {
+            const text = match[1].trim();
+            if (text)
+                bullets.push(text);
+        }
+    }
+    return bullets;
+}
+/**
+ * Extract the first non-empty line from an array of lines.
+ */
+function firstNonEmptyLine(lines) {
+    for (const line of lines) {
+        const trimmed = line.trim();
+        if (trimmed)
+            return trimmed;
+    }
+    return null;
+}
+function parseContent(content) {
+    const sections = splitSections(content);
+    // WHY: look for matching heading, fall back to first paragraph of document
+    let why = null;
+    const whySection = findSection(sections, WHY_KEYWORDS);
+    if (whySection) {
+        why = firstParagraph(whySection.lines);
+    }
+    if (!why) {
+        // Fallback: first paragraph of the entire document (all sections)
+        const allLines = sections.flatMap((s) => s.lines);
+        why = firstParagraph(allLines);
+    }
+    // RULES
+    const rulesSection = findSection(sections, RULES_KEYWORDS);
+    const rules = rulesSection ? extractBullets(rulesSection.lines) : [];
+    // BOUNDARIES
+    const boundariesSection = findSection(sections, BOUNDARIES_KEYWORDS);
+    const boundaries = boundariesSection
+        ? extractBullets(boundariesSection.lines)
+        : [];
+    // OWNER
+    const ownerSection = findSection(sections, OWNER_KEYWORDS);
+    const owner = ownerSection ? firstNonEmptyLine(ownerSection.lines) : null;
+    return { why, rules, boundaries, owner };
+}

package/dist/utils/schema-version.js

@@ -0,0 +1,91 @@
+import * as fs from 'fs/promises';
+import * as path from 'path';
+/**
+ * Single source of truth for the current schema version.
+ * Bump this when the .matha/ directory structure changes.
+ */
+export const CURRENT_SCHEMA_VERSION = '0.1.0';
+/**
+ * Compare two semver strings (major.minor.patch).
+ * Returns -1 if a < b, 0 if a === b, 1 if a > b.
+ */
+function compareSemver(a, b) {
+    const pa = a.split('.').map(Number);
+    const pb = b.split('.').map(Number);
+    for (let i = 0; i < 3; i++) {
+        const av = pa[i] ?? 0;
+        const bv = pb[i] ?? 0;
+        if (av < bv)
+            return -1;
+        if (av > bv)
+            return 1;
+    }
+    return 0;
+}
+/**
+ * Check the schema version in .matha/config.json.
+ *
+ * **Never throws** — always returns a result, even on malformed or
+ * missing config files.
+ */
+export async function checkSchemaVersion(mathaDir) {
+    try {
+        const configPath = path.join(mathaDir, 'config.json');
+        let raw;
+        try {
+            raw = await fs.readFile(configPath, 'utf-8');
+        }
+        catch {
+            // File does not exist → uninitialised
+            return { status: 'uninitialised', version: null };
+        }
+        let config;
+        try {
+            config = JSON.parse(raw);
+        }
+        catch {
+            // Malformed JSON → treat as uninitialised (safe fallback)
+            return { status: 'uninitialised', version: null };
+        }
+        if (config === null || typeof config !== 'object') {
+            return { status: 'uninitialised', version: null };
+        }
+        const schemaVersion = config.schema_version;
+        if (schemaVersion === undefined || schemaVersion === null) {
+            return { status: 'legacy', version: null };
+        }
+        const version = String(schemaVersion);
+        const cmp = compareSemver(version, CURRENT_SCHEMA_VERSION);
+        if (cmp === 0)
+            return { status: 'ok', version };
+        if (cmp < 0)
+            return { status: 'outdated', version };
+        return { status: 'newer', version };
+    }
+    catch {
+        // Catch-all: never throw, always return a result
+        return { status: 'uninitialised', version: null };
+    }
+}
+/**
+ * Return a human-readable message for the given schema check result.
+ * Returns `null` when no message is needed (ok, uninitialised).
+ */
+export function getSchemaMessage(result) {
+    switch (result.status) {
+        case 'ok':
+        case 'uninitialised':
+            return null;
+        case 'legacy':
+            return ('⚠ This .matha/ was created before schema versioning. ' +
+                'Run `matha migrate` to upgrade. (Coming in v0.2.0)');
+        case 'outdated':
+            return (`⚠ This .matha/ uses schema v${result.version}. ` +
+                `Current is v${CURRENT_SCHEMA_VERSION}. ` +
+                'Run `matha migrate` to upgrade. (Coming in v0.2.0)');
+        case 'newer':
+            return (`✗ This .matha/ uses schema v${result.version} which is newer ` +
+                `than this version of MATHA (v${CURRENT_SCHEMA_VERSION}). ` +
+                'Upgrade MATHA: npm install -g matha');
+    }
+}

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@10kdevs/matha",
+  "version": "0.1.0",
+  "description": "The persistent cognitive layer for AI-assisted development. Gives AI agents the project context that currently only exists inside a senior engineer's head.",
+  "main": "./dist/index.js",
+  "bin": {
+    "matha": "dist/index.js"
+  },
+  "files": [
+    "dist/",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc && tsc-alias",
+    "test": "vitest",
+    "dev": "tsx src/index.ts",
+    "serve": "tsx src/index.ts serve",
+    "cli": "tsx src/index.ts",
+    "prepublishOnly": "npm run build && npx vitest run"
+  },
+  "type": "module",
+  "keywords": [
+    "ai",
+    "mcp",
+    "llm",
+    "context",
+    "memory",
+    "claude",
+    "cursor",
+    "copilot",
+    "developer-tools",
+    "productivity",
+    "model-context-protocol"
+  ],
+  "author": "Bhupesh",
+  "license": "MIT",
+  "homepage": "https://github.com/bhupesh003/matha#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/bhupesh003/matha.git"
+  },
+  "bugs": {
+    "url": "https://github.com/bhupesh003/matha/issues"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.27.1",
+    "commander": "^14.0.3",
+    "inquirer": "^13.3.0",
+    "simple-git": "^3.32.3",
+    "typescript": "^5.9.3"
+  },
+  "devDependencies": {
+    "@types/node": "^25.3.3",
+    "tsc-alias": "^1.8.16",
+    "tsx": "^4.21.0",
+    "vitest": "^4.0.18"
+  }
+}