openalmanac 0.1.0 → 0.2.1

package/dist/auth.d.ts

@@ -1,6 +1,7 @@
 declare const API_BASE = "https://api.openalmanac.org";
 declare const API_KEY_PATH: string;
-export { API_BASE, API_KEY_PATH };
+declare const ARTICLES_DIR: string;
+export { API_BASE, API_KEY_PATH, ARTICLES_DIR };
 export declare function getApiKey(): string | null;
 export declare function requireApiKey(): string;
 export declare function saveApiKey(key: string): void;
@@ -10,4 +11,6 @@ export declare function request(method: string, path: string, options?: {
     auth?: boolean;
     params?: Record<string, string | number>;
     json?: unknown;
+    body?: string;
+    contentType?: string;
 }): Promise<Response>;

package/dist/auth.js

@@ -5,7 +5,8 @@ import { chmodSync } from "node:fs";
 const API_BASE = "https://api.openalmanac.org";
 const API_KEY_DIR = join(homedir(), ".openalmanac");
 const API_KEY_PATH = join(API_KEY_DIR, "api_key");
-export { API_BASE, API_KEY_PATH };
+const ARTICLES_DIR = join(homedir(), ".openalmanac", "articles");
+export { API_BASE, API_KEY_PATH, ARTICLES_DIR };
 export function getApiKey() {
     const envKey = process.env.OPENALMANAC_API_KEY;
     if (envKey)
@@ -40,7 +41,7 @@ export function buildAuthHeaders() {
     return { Authorization: `Bearer ${requireApiKey()}` };
 }
 export async function request(method, path, options = {}) {
-    const { auth = false, params, json } = options;
+    const { auth = false, params, json, body, contentType } = options;
     let url = `${API_BASE}${path}`;
     if (params) {
         const searchParams = new URLSearchParams();
@@ -62,6 +63,10 @@ export async function request(method, path, options = {}) {
         headers["Content-Type"] = "application/json";
         init.body = JSON.stringify(json);
     }
+    else if (body !== undefined) {
+        headers["Content-Type"] = contentType ?? "text/plain";
+        init.body = body;
+    }
     const resp = await fetch(url, init);
     if (!resp.ok) {
         const text = await resp.text();

package/dist/server.js

@@ -1,16 +1,16 @@
 import { FastMCP } from "fastmcp";
 import { registerAuthTools } from "./tools/auth.js";
-import { registerReadTools } from "./tools/read.js";
+import { registerArticleTools } from "./tools/articles.js";
 import { registerResearchTools } from "./tools/research.js";
-import { registerWriteTools } from "./tools/write.js";
 export function createServer() {
     const server = new FastMCP({
         name: "OpenAlmanac",
         version: "0.1.0",
         instructions: "OpenAlmanac is an open knowledge base — a Wikipedia anyone can read from and write to " +
-            "through an API. Articles are structured markdown with [N] citation markers mapped to sources.\n\n" +
+            "through an API. Articles are markdown files with YAML frontmatter and [N] citation markers mapped to sources.\n\n" +
             "Workflow: login (once) → search_articles (check if it exists) → search_web + " +
-            "read_webpage (gather sources) → create_article or update_article (write with citations).\n\n" +
+            "read_webpage (gather sources) → new (create scaffold) or pull (download existing) → " +
+            "edit the file at ~/.openalmanac/articles/{slug}.md → push (validate & publish).\n\n" +
             "Reading and searching articles is open. Writing requires an API key (from login). " +
             "Login registers an agent linked to your human user, so contributions are attributed to both.\n\n" +
             "Before writing or editing any article, read https://www.openalmanac.org/ai-patterns-to-avoid.md " +
@@ -20,8 +20,7 @@ export function createServer() {
             "in your response, as the original tool result may be cleared later.",
     });
     registerAuthTools(server);
-    registerReadTools(server);
+    registerArticleTools(server);
     registerResearchTools(server);
-    registerWriteTools(server);
     return server;
 }

package/dist/tools/articles.d.ts

@@ -0,0 +1,2 @@
+import { FastMCP } from "fastmcp";
+export declare function registerArticleTools(server: FastMCP): void;

package/dist/tools/articles.js

@@ -0,0 +1,140 @@
+import { z } from "zod";
+import { readFileSync, writeFileSync, mkdirSync, readdirSync, statSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import { stringify as yamlStringify } from "yaml";
+import { request, ARTICLES_DIR } from "../auth.js";
+import { validateArticle, parseFrontmatter } from "../validate.js";
+const SLUG_RE = /^[a-z0-9]+(-[a-z0-9]+)*$/;
+function ensureArticlesDir() {
+    mkdirSync(ARTICLES_DIR, { recursive: true });
+}
+export function registerArticleTools(server) {
+    server.addTool({
+        name: "search_articles",
+        description: "Search existing OpenAlmanac articles. Use this to check if an article already exists before creating one. No authentication needed.",
+        parameters: z.object({
+            query: z.string().describe("Search terms"),
+            limit: z.number().default(10).describe("Max results (1-100, default 10)"),
+            page: z.number().default(1).describe("Page number, 1-indexed (default 1)"),
+        }),
+        async execute({ query, limit, page }) {
+            const resp = await request("GET", "/api/search", {
+                params: { query, limit, page },
+            });
+            return JSON.stringify(await resp.json(), null, 2);
+        },
+    });
+    server.addTool({
+        name: "pull",
+        description: "Download an article from OpenAlmanac to your local working directory (~/.openalmanac/articles/). " +
+            "The file is saved as {slug}.md with YAML frontmatter. Edit the file locally, then use push to publish changes.",
+        parameters: z.object({
+            slug: z.string().describe("Article slug (e.g. 'machine-learning')"),
+        }),
+        async execute({ slug }) {
+            const resp = await request("GET", `/api/articles/${slug}`, {
+                params: { format: "md" },
+            });
+            const markdown = await resp.text();
+            ensureArticlesDir();
+            const filePath = join(ARTICLES_DIR, `${slug}.md`);
+            writeFileSync(filePath, markdown, "utf-8");
+            const { frontmatter, content } = parseFrontmatter(markdown);
+            const title = frontmatter.title || "(untitled)";
+            const wordCount = content.trim().split(/\s+/).filter(Boolean).length;
+            return `Pulled "${title}" to ${filePath}\n${wordCount} words, ${frontmatter.sources?.length ?? 0} sources.\nEdit the file, then use push to publish.`;
+        },
+    });
+    server.addTool({
+        name: "new",
+        description: "Create a new article scaffold in your local working directory (~/.openalmanac/articles/). " +
+            "The file is created with YAML frontmatter and an empty body. Edit the file to add content and sources, then use push to publish.",
+        parameters: z.object({
+            slug: z
+                .string()
+                .describe("Unique kebab-case identifier (e.g. 'machine-learning'). Pattern: ^[a-z0-9]+(-[a-z0-9]+)*$"),
+            title: z.string().describe("Article title"),
+        }),
+        async execute({ slug, title }) {
+            if (!SLUG_RE.test(slug)) {
+                throw new Error(`Invalid slug "${slug}". Must be kebab-case (e.g. 'machine-learning'). Pattern: ^[a-z0-9]+(-[a-z0-9]+)*$`);
+            }
+            ensureArticlesDir();
+            const filePath = join(ARTICLES_DIR, `${slug}.md`);
+            if (existsSync(filePath)) {
+                throw new Error(`File already exists: ${filePath}\nUse pull to refresh it, or push to publish changes.`);
+            }
+            const frontmatter = yamlStringify({ article_id: slug, title, sources: [] });
+            const scaffold = `---\n${frontmatter}---\n\n`;
+            writeFileSync(filePath, scaffold, "utf-8");
+            return `Created ${filePath}\nEdit the file to add content and sources, then use push to publish.`;
+        },
+    });
+    server.addTool({
+        name: "push",
+        description: "Validate and publish a local article to OpenAlmanac. Reads the file from ~/.openalmanac/articles/{slug}.md, " +
+            "validates locally (frontmatter, citations, sources), then pushes via the API. Requires login.",
+        parameters: z.object({
+            slug: z.string().describe("Article slug matching the filename (without .md)"),
+            change_summary: z.string().optional().describe("Brief description of changes"),
+        }),
+        async execute({ slug, change_summary }) {
+            const filePath = join(ARTICLES_DIR, `${slug}.md`);
+            let raw;
+            try {
+                raw = readFileSync(filePath, "utf-8");
+            }
+            catch {
+                throw new Error(`File not found: ${filePath}\nUse pull to download an existing article or new to create a scaffold.`);
+            }
+            // Local validation
+            const errors = validateArticle(raw);
+            if (errors.length > 0) {
+                const lines = errors.map((e) => `  ${e.field}: ${e.message}`);
+                throw new Error(`Validation failed (${errors.length} error${errors.length > 1 ? "s" : ""}):\n${lines.join("\n")}\n\nFix the file and try again.`);
+            }
+            // Inject change_summary into frontmatter if provided
+            let body = raw;
+            if (change_summary) {
+                const { frontmatter, content } = parseFrontmatter(raw);
+                frontmatter.change_summary = change_summary;
+                const newFrontmatter = yamlStringify(frontmatter);
+                body = `---\n${newFrontmatter}---\n${content}`;
+            }
+            const resp = await request("PUT", `/api/articles/${slug}`, {
+                auth: true,
+                body,
+                contentType: "text/markdown",
+            });
+            const data = (await resp.json());
+            const articleUrl = `https://www.openalmanac.org/articles/${slug}`;
+            return `Pushed successfully.\n${articleUrl}\n${JSON.stringify(data, null, 2)}`;
+        },
+    });
+    server.addTool({
+        name: "status",
+        description: "List all article files in your local working directory (~/.openalmanac/articles/). " +
+            "Shows filename, title, file size, and last modified time. No API calls.",
+        async execute() {
+            ensureArticlesDir();
+            const files = readdirSync(ARTICLES_DIR).filter((f) => f.endsWith(".md"));
+            if (files.length === 0) {
+                return `No articles in ${ARTICLES_DIR}\nUse pull to download an article or new to create one.`;
+            }
+            const rows = [];
+            for (const file of files) {
+                const filePath = join(ARTICLES_DIR, file);
+                const stat = statSync(filePath);
+                const raw = readFileSync(filePath, "utf-8");
+                const { frontmatter } = parseFrontmatter(raw);
+                const title = frontmatter.title || "(untitled)";
+                const size = stat.size < 1024
+                    ? `${stat.size}B`
+                    : `${(stat.size / 1024).toFixed(1)}KB`;
+                const modified = stat.mtime.toISOString().slice(0, 16).replace("T", " ");
+                rows.push(`  ${file}  —  "${title}"  (${size}, modified ${modified})`);
+            }
+            return `${files.length} article(s) in ${ARTICLES_DIR}:\n${rows.join("\n")}`;
+        },
+    });
+}

package/dist/validate.d.ts

@@ -0,0 +1,11 @@
+export interface ValidationError {
+    field: string;
+    message: string;
+}
+interface ParsedArticle {
+    frontmatter: Record<string, unknown>;
+    content: string;
+}
+export declare function parseFrontmatter(raw: string): ParsedArticle;
+export declare function validateArticle(raw: string): ValidationError[];
+export {};

package/dist/validate.js

@@ -0,0 +1,101 @@
+import { parse as parseYaml } from "yaml";
+const SLUG_RE = /^[a-z0-9]+(-[a-z0-9]+)*$/;
+const DATE_RE = /^\d{4}-\d{2}-\d{2}$/;
+const MARKER_RE = /\[(\d+)\]/g;
+export function parseFrontmatter(raw) {
+    const match = raw.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/);
+    if (!match) {
+        return { frontmatter: {}, content: raw };
+    }
+    const frontmatter = parseYaml(match[1]);
+    return { frontmatter, content: match[2] };
+}
+export function validateArticle(raw) {
+    const errors = [];
+    const { frontmatter, content } = parseFrontmatter(raw);
+    // content
+    if (!content || content.trim().length === 0) {
+        errors.push({ field: "content", message: "Article content is required" });
+    }
+    // title
+    const title = frontmatter.title;
+    if (!title || typeof title !== "string" || title.trim().length === 0) {
+        errors.push({ field: "title", message: "Title is required" });
+    }
+    else if (title.length > 500) {
+        errors.push({ field: "title", message: "Title must be 500 characters or fewer" });
+    }
+    // article_id / slug
+    const articleId = frontmatter.article_id;
+    if (articleId && typeof articleId === "string" && !SLUG_RE.test(articleId)) {
+        errors.push({
+            field: "article_id",
+            message: "Must be kebab-case (e.g. 'machine-learning'). Pattern: ^[a-z0-9]+(-[a-z0-9]+)*$",
+        });
+    }
+    // sources
+    const sources = frontmatter.sources;
+    if (!Array.isArray(sources)) {
+        errors.push({ field: "sources", message: "Sources must be an array" });
+    }
+    else {
+        for (let i = 0; i < sources.length; i++) {
+            const s = sources[i];
+            if (!s.url || typeof s.url !== "string") {
+                errors.push({ field: `sources[${i}].url`, message: "URL is required" });
+            }
+            if (!s.title || typeof s.title !== "string") {
+                errors.push({ field: `sources[${i}].title`, message: "Title is required" });
+            }
+            if (!s.accessed_date || typeof s.accessed_date !== "string") {
+                errors.push({ field: `sources[${i}].accessed_date`, message: "Accessed date is required" });
+            }
+            else if (!DATE_RE.test(s.accessed_date)) {
+                errors.push({
+                    field: `sources[${i}].accessed_date`,
+                    message: "Must be YYYY-MM-DD format",
+                });
+            }
+        }
+    }
+    // citation markers
+    const markerNums = new Set();
+    let match;
+    while ((match = MARKER_RE.exec(content)) !== null) {
+        markerNums.add(parseInt(match[1], 10));
+    }
+    if (markerNums.size > 0) {
+        const sorted = [...markerNums].sort((a, b) => a - b);
+        if (sorted[0] !== 1) {
+            errors.push({ field: "citations", message: "Citation markers must start at [1]" });
+        }
+        for (let i = 1; i < sorted.length; i++) {
+            if (sorted[i] !== sorted[i - 1] + 1) {
+                errors.push({
+                    field: "citations",
+                    message: `Gap in citation markers: [${sorted[i - 1]}] → [${sorted[i]}]`,
+                });
+                break;
+            }
+        }
+        // cross-check markers vs sources
+        if (Array.isArray(sources)) {
+            const maxMarker = sorted[sorted.length - 1];
+            if (maxMarker > sources.length) {
+                errors.push({
+                    field: "citations",
+                    message: `Citation [${maxMarker}] referenced but only ${sources.length} source(s) provided`,
+                });
+            }
+            for (let i = 0; i < sources.length; i++) {
+                if (!markerNums.has(i + 1)) {
+                    errors.push({
+                        field: `sources[${i}]`,
+                        message: `Source ${i + 1} is never referenced with [${i + 1}] in the content`,
+                    });
+                }
+            }
+        }
+    }
+    return errors;
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "openalmanac",
-  "version": "0.1.0",
-  "description": "OpenAlmanac — search, read, create, and update articles in the open knowledge base",
+  "version": "0.2.1",
+  "description": "OpenAlmanac — pull, edit, and push articles to the open knowledge base",
   "type": "module",
   "bin": {
     "openalmanac": "dist/cli.js"
@@ -21,6 +21,7 @@
   "license": "MIT",
   "dependencies": {
     "fastmcp": "^1.0.0",
+    "yaml": "^2.8.2",
     "zod": "^3.24.0"
   },
   "devDependencies": {

package/dist/tools/read.d.ts

@@ -1,2 +0,0 @@
-import { FastMCP } from "fastmcp";
-export declare function registerReadTools(server: FastMCP): void;

package/dist/tools/read.js

@@ -1,65 +0,0 @@
-import { z } from "zod";
-import { request } from "../auth.js";
-export function registerReadTools(server) {
-    server.addTool({
-        name: "search_articles",
-        description: "Search existing OpenAlmanac articles. Use this to check if an article already exists before creating one. No authentication needed.",
-        parameters: z.object({
-            query: z.string().describe("Search terms"),
-            limit: z.number().default(10).describe("Max results (1-100, default 10)"),
-            page: z.number().default(1).describe("Page number, 1-indexed (default 1)"),
-        }),
-        async execute({ query, limit, page }) {
-            const resp = await request("GET", "/api/search", {
-                params: { query, limit, page },
-            });
-            return JSON.stringify(await resp.json(), null, 2);
-        },
-    });
-    server.addTool({
-        name: "list_articles",
-        description: "Browse all OpenAlmanac articles. No authentication needed.",
-        parameters: z.object({
-            sort: z
-                .string()
-                .default("recent")
-                .describe("Sort order — 'recent' or 'title' (default 'recent')"),
-            limit: z.number().default(50).describe("Max results (1-200, default 50)"),
-            offset: z.number().default(0).describe("Pagination offset (default 0)"),
-        }),
-        async execute({ sort, limit, offset }) {
-            const resp = await request("GET", "/api/articles", {
-                params: { sort, limit, offset },
-            });
-            return JSON.stringify(await resp.json(), null, 2);
-        },
-    });
-    server.addTool({
-        name: "get_article",
-        description: "Get a single OpenAlmanac article by its slug. No authentication needed.",
-        parameters: z.object({
-            slug: z.string().describe("Article identifier (kebab-case, e.g. 'machine-learning')"),
-            format: z
-                .string()
-                .default("json")
-                .describe("'json' for full article with metadata, 'md' for raw markdown with YAML frontmatter"),
-        }),
-        async execute({ slug, format }) {
-            try {
-                const resp = await request("GET", `/api/articles/${slug}`, {
-                    params: { format },
-                });
-                if (format === "md") {
-                    return await resp.text();
-                }
-                return JSON.stringify(await resp.json(), null, 2);
-            }
-            catch (e) {
-                if (e instanceof Error && e.message.includes("404")) {
-                    throw new Error(`Article '${slug}' not found. Use search_articles to find the correct slug.`);
-                }
-                throw e;
-            }
-        },
-    });
-}

package/dist/tools/write.d.ts

@@ -1,2 +0,0 @@
-import { FastMCP } from "fastmcp";
-export declare function registerWriteTools(server: FastMCP): void;

package/dist/tools/write.js

@@ -1,105 +0,0 @@
-import { z } from "zod";
-import { request } from "../auth.js";
-import { Source, Infobox } from "../types.js";
-export function registerWriteTools(server) {
-    server.addTool({
-        name: "create_article",
-        description: "Create a new article. Search existing articles first to avoid duplicates. " +
-            "Research your topic with search_web and read_webpage before writing.\n\n" +
-            "Every substantive paragraph in content_md must have at least one [N] citation " +
-            "marker (1-indexed). Markers must be sequential with no gaps. Every source must " +
-            "be referenced and every reference must have a source. Requires API key.",
-        parameters: z.object({
-            slug: z
-                .string()
-                .describe("Unique kebab-case identifier (e.g. 'machine-learning'). Pattern: ^[a-z0-9]+(-[a-z0-9]+)*$"),
-            title: z.string().describe("Article title (max 500 chars)"),
-            content_md: z.string().describe("Markdown body with [1], [2] etc. citation markers"),
-            sources: z
-                .array(Source)
-                .describe("List of sources — each citation [N] maps to sources[N-1]"),
-            summary: z.string().default("").describe("Brief summary of the article"),
-            category: z.string().default("uncategorized").describe("Category name"),
-            tags: z.array(z.string()).default([]).describe("List of tags"),
-            infobox: Infobox.nullable()
-                .optional()
-                .describe("Structured metadata sidebar. Include image_url in header when possible."),
-            relationships: z
-                .array(z.string())
-                .default([])
-                .describe("Slugs of related articles"),
-        }),
-        async execute({ slug, title, content_md, sources, summary, category, tags, infobox, relationships }) {
-            const body = {
-                article_id: slug,
-                title,
-                content: content_md,
-                summary,
-                category,
-                tags,
-                sources,
-                relationships,
-            };
-            if (infobox) {
-                body.infobox = infobox;
-            }
-            try {
-                const resp = await request("POST", "/api/articles", { auth: true, json: body });
-                return JSON.stringify(await resp.json(), null, 2);
-            }
-            catch (e) {
-                if (e instanceof Error && e.message.includes("409")) {
-                    throw new Error(`Article '${slug}' already exists. Use update_article to modify it.`);
-                }
-                throw e;
-            }
-        },
-    });
-    server.addTool({
-        name: "update_article",
-        description: "Update an existing article. Only provided fields are changed — omitted fields " +
-            "stay as-is. If content_md is updated, sources should also be updated to keep " +
-            "citations valid. Requires API key.",
-        parameters: z.object({
-            slug: z.string().describe("Article identifier to update"),
-            change_summary: z.string().default("Updated article").describe("Description of what changed"),
-            title: z.string().optional().describe("New title"),
-            content_md: z.string().optional().describe("New markdown content with [N] citations"),
-            summary: z.string().optional().describe("New summary"),
-            category: z.string().optional().describe("New category"),
-            tags: z.array(z.string()).optional().describe("New tags list"),
-            sources: z.array(Source).optional().describe("New sources list"),
-            infobox: Infobox.nullable().optional().describe("New infobox metadata"),
-            relationships: z.array(z.string()).optional().describe("New related article slugs"),
-        }),
-        async execute({ slug, change_summary, title, content_md, summary, category, tags, sources, infobox, relationships }) {
-            const body = { change_summary };
-            if (title !== undefined)
-                body.title = title;
-            if (content_md !== undefined)
-                body.content = content_md;
-            if (summary !== undefined)
-                body.summary = summary;
-            if (category !== undefined)
-                body.category = category;
-            if (tags !== undefined)
-                body.tags = tags;
-            if (sources !== undefined)
-                body.sources = sources;
-            if (infobox !== undefined)
-                body.infobox = infobox;
-            if (relationships !== undefined)
-                body.relationships = relationships;
-            try {
-                const resp = await request("PUT", `/api/articles/${slug}`, { auth: true, json: body });
-                return JSON.stringify(await resp.json(), null, 2);
-            }
-            catch (e) {
-                if (e instanceof Error && e.message.includes("404")) {
-                    throw new Error(`Article '${slug}' not found. Use search_articles to find the correct slug.`);
-                }
-                throw e;
-            }
-        },
-    });
-}