openalmanac 0.2.33 → 0.2.34

package/dist/tools/articles.js

@@ -142,6 +142,54 @@ External image URLs are auto-persisted on publish — no extra steps needed.
 function ensureArticlesDir() {
     mkdirSync(ARTICLES_DIR, { recursive: true });
 }
+function resolveArticleDir(communitySlug) {
+    return communitySlug ? join(ARTICLES_DIR, communitySlug) : ARTICLES_DIR;
+}
+function resolveArticlePaths(slug, communitySlug) {
+    const dir = resolveArticleDir(communitySlug);
+    return {
+        dir,
+        filePath: join(dir, `${slug}.md`),
+        originalPath: join(dir, `.${slug}.original.md`),
+    };
+}
+function findDraftCandidates(slug) {
+    const matches = [];
+    const root = resolveArticlePaths(slug);
+    if (existsSync(root.filePath)) {
+        matches.push({ communitySlug: null, filePath: root.filePath, originalPath: root.originalPath });
+    }
+    try {
+        const dirs = readdirSync(ARTICLES_DIR).filter((d) => {
+            try {
+                return statSync(join(ARTICLES_DIR, d)).isDirectory();
+            }
+            catch {
+                return false;
+            }
+        });
+        for (const communitySlug of dirs) {
+            const scoped = resolveArticlePaths(slug, communitySlug);
+            if (existsSync(scoped.filePath)) {
+                matches.push({ communitySlug, filePath: scoped.filePath, originalPath: scoped.originalPath });
+            }
+        }
+    }
+    catch { /* ignore readdir errors */ }
+    return matches;
+}
+function resolvePublishCandidate(slug) {
+    const matches = findDraftCandidates(slug);
+    if (matches.length === 0) {
+        const fallback = resolveArticlePaths(slug);
+        throw new Error(`File not found: ${fallback.filePath}\nUse download to get an existing article or new to create a scaffold.`);
+    }
+    if (matches.length > 1) {
+        const paths = matches.map((match) => `  - ${match.filePath}`).join("\n");
+        throw new Error(`Multiple local drafts found for slug "${slug}". Publish is ambiguous.\n${paths}\nRemove the duplicate draft or publish from the exact community context.`);
+    }
+    return matches[0];
+}
 export function registerArticleTools(server) {
     server.addTool({
         name: "search_articles",
@@ -167,8 +215,16 @@ export function registerArticleTools(server) {
             "For editing articles locally, use 'download' instead. No authentication needed.",
         parameters: z.object({
             slugs: coerceJson(z.array(z.string()).min(1).max(20)).describe("Article slugs to read (1-20)"),
+            community_slug: z.string().optional().describe("Community slug for reading community-owned wiki articles. Omit for global almanac articles."),
         }),
-        async execute({ slugs }) {
+        async execute({ slugs, community_slug }) {
+            if (community_slug) {
+                const results = await Promise.all(slugs.map(async (slug) => {
+                    const resp = await request("GET", `/api/communities/${community_slug}/wiki/${slug}`);
+                    return await resp.json();
+                }));
+                return JSON.stringify({ results }, null, 2);
+            }
             const resp = await request("POST", "/api/articles/batch", {
                 json: { slugs },
             });
@@ -179,6 +235,7 @@ export function registerArticleTools(server) {
         name: "create_stubs",
         description: "Create stub articles — placeholders for entities that don't have full articles yet. " +
             "Use this for every entity (person, organization, topic, etc.) mentioned in an article. " +
+            "For community wiki stubs, include community_slug on each stub. " +
             "Idempotent: existing slugs return their current status. Requires login.",
         parameters: z.object({
             stubs: coerceJson(z.array(z.object({
@@ -205,6 +262,8 @@ export function registerArticleTools(server) {
                     .optional()
                     .describe("2-4 sentence summary of the entity. This becomes the stub page content. " +
                     "Be informative — include key facts, dates, and context."),
+                community_slug: z.string().optional().describe("Community slug for community-owned stubs. Omit for global stubs."),
+                topics: z.array(z.string()).optional().describe("Topic slugs for community wiki stubs (e.g. ['techniques', 'tools'])."),
             })).min(1).max(50)).describe("Stubs to create (1-50)"),
         }),
         async execute({ stubs }) {
@@ -217,24 +276,33 @@ export function registerArticleTools(server) {
     });
     server.addTool({
         name: "download",
-        description: "Download an article to your local workspace for editing. The file is saved to ~/.openalmanac/articles/{slug}.md " +
-            "with YAML frontmatter. Returns a writing guide covering article structure, infobox format, citations, and quality rules. " +
+        description: "Download an article to your local workspace for editing. Global articles are saved to ~/.openalmanac/articles/{slug}.md. " +
+            "Community wiki articles are saved to ~/.openalmanac/articles/{community_slug}/{slug}.md. " +
+            "Returns a writing guide covering article structure, infobox format, citations, and quality rules. " +
             "After editing, use 'publish' to push your changes live.",
         parameters: z.object({
             slug: z.string().describe("Article slug (e.g. 'machine-learning')"),
+            community_slug: z.string().optional().describe("Community slug for downloading a community-owned wiki article. " +
+                "Omit for global almanac articles."),
         }),
-        async execute({ slug }) {
+        async execute({ slug, community_slug }) {
             if (!SLUG_RE.test(slug)) {
                 throw new Error(`Invalid slug "${slug}". Must be kebab-case (e.g. 'machine-learning').`);
             }
-            const resp = await request("GET", `/api/articles/${slug}`, {
+            const apiPath = community_slug
+                ? `/api/communities/${community_slug}/wiki/${slug}`
+                : `/api/articles/${slug}`;
+            const resp = await request("GET", apiPath, {
                 params: { format: "md" },
             });
             const markdown = await resp.text();
             ensureArticlesDir();
-            const filePath = join(ARTICLES_DIR, `${slug}.md`);
+            // Community articles go in a subdirectory
+            const { dir, filePath, originalPath } = resolveArticlePaths(slug, community_slug);
+            if (community_slug) {
+                mkdirSync(dir, { recursive: true });
+            }
             writeFileSync(filePath, markdown, "utf-8");
-            const originalPath = join(ARTICLES_DIR, `.${slug}.original.md`);
             writeFileSync(originalPath, markdown, "utf-8");
             const { frontmatter, content } = parseFrontmatter(markdown);
             const title = frontmatter.title || "(untitled)";
@@ -250,6 +318,8 @@ export function registerArticleTools(server) {
     server.addTool({
         name: "new",
         description: "Create a new article scaffold in your local working directory (~/.openalmanac/articles/). " +
+            "For community wiki articles, provide community_slug and optional topics — the file is saved under " +
+            "~/.openalmanac/articles/{community_slug}/{slug}.md. " +
             "The file is created with YAML frontmatter and an empty body. Returns a writing guide covering article structure, infobox format, citations, and quality rules. " +
             "Edit the file to add content and sources, then use publish to go live.",
         parameters: z.object({
@@ -257,17 +327,36 @@ export function registerArticleTools(server) {
                 .string()
                 .describe("Unique kebab-case identifier (e.g. 'machine-learning'). Pattern: ^[a-z0-9]+(-[a-z0-9]+)*$"),
             title: z.string().describe("Article title"),
+            community_slug: z.string().optional().describe("Community slug for community-owned wiki articles (e.g. 'lockpicking'). " +
+                "Omit for global almanac articles."),
+            topics: coerceJson(z.array(z.string()).default([])).describe("Topic slugs for community wiki articles (e.g. ['techniques', 'tools']). " +
+                "Topics are community-specific categories."),
         }),
-        async execute({ slug, title }) {
+        async execute({ slug, title, community_slug, topics }) {
             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]+)*$`);
             }
+            if (community_slug && !SLUG_RE.test(community_slug)) {
+                throw new Error(`Invalid community_slug "${community_slug}". Must be kebab-case.`);
+            }
             ensureArticlesDir();
-            const filePath = join(ARTICLES_DIR, `${slug}.md`);
+            // Community articles are saved in a subdirectory
+            let dir = ARTICLES_DIR;
+            if (community_slug) {
+                dir = join(ARTICLES_DIR, community_slug);
+                mkdirSync(dir, { recursive: true });
+            }
+            const filePath = join(dir, `${slug}.md`);
             if (existsSync(filePath)) {
                 throw new Error(`File already exists: ${filePath}\nUse download to refresh it, or publish to push changes.`);
             }
-            const frontmatter = yamlStringify({ article_id: slug, title, sources: [] });
+            const meta = { article_id: slug, title };
+            if (community_slug)
+                meta.community_slug = community_slug;
+            if (topics && topics.length > 0)
+                meta.topics = topics;
+            meta.sources = [];
+            const frontmatter = yamlStringify(meta);
             const scaffold = `---\n${frontmatter}---\n\n`;
             writeFileSync(filePath, scaffold, "utf-8");
             return `Created ${filePath}\n\n${WRITING_GUIDE}`;
@@ -275,7 +364,7 @@ export function registerArticleTools(server) {
     });
     server.addTool({
         name: "publish",
-        description: "Validate and publish an article from your local workspace. Reads ~/.openalmanac/articles/{slug}.md, " +
+        description: "Validate and publish an article from your local workspace. Reads ~/.openalmanac/articles/{slug}.md or the matching community draft, " +
             "validates content and sources, and publishes to OpenAlmanac. Requires login.",
         parameters: z.object({
             slug: z.string().describe("Article slug matching the filename (without .md)"),
@@ -286,14 +375,8 @@ export function registerArticleTools(server) {
             if (!SLUG_RE.test(slug)) {
                 throw new Error(`Invalid slug "${slug}". Must be kebab-case (e.g. 'machine-learning').`);
             }
-            const filePath = join(ARTICLES_DIR, `${slug}.md`);
-            let raw;
-            try {
-                raw = readFileSync(filePath, "utf-8");
-            }
-            catch {
-                throw new Error(`File not found: ${filePath}\nUse download to get an existing article or new to create a scaffold.`);
-            }
+            const { communitySlug, filePath, originalPath } = resolvePublishCandidate(slug);
+            const raw = readFileSync(filePath, "utf-8");
             // Local validation
             const errors = validateArticle(raw);
             if (errors.length > 0) {
@@ -317,7 +400,12 @@ export function registerArticleTools(server) {
                 contentType: "text/markdown",
             });
             const data = (await resp.json());
-            const articleUrl = `https://www.openalmanac.org/article/${slug}?celebrate=true`;
+            const canonicalPath = typeof data.canonical_path === "string"
+                ? data.canonical_path
+                : communitySlug
+                    ? `/communities/${communitySlug}/wiki/${slug}`
+                    : `/article/${slug}`;
+            const articleUrl = `https://www.openalmanac.org${canonicalPath}?celebrate=true`;
             const inGui = process.env.OPENALMANAC_GUI === "1";
             // Skip browser open when running inside the GUI — it handles navigation itself
             if (!inGui) {
@@ -334,7 +422,7 @@ export function registerArticleTools(server) {
                 }
             }
             try {
-                unlinkSync(join(ARTICLES_DIR, `.${slug}.original.md`));
+                unlinkSync(originalPath);
             }
             catch (e) {
                 if (e.code !== "ENOENT") {
@@ -404,9 +492,6 @@ export function registerArticleTools(server) {
                 ? `Logged in as ${auth.name}.`
                 : "Not logged in. Use login to authenticate.";
             const files = readdirSync(ARTICLES_DIR).filter((f) => f.endsWith(".md") && !f.startsWith("."));
-            if (files.length === 0) {
-                return `${authLine}\n\nLocal articles (0 files in ${ARTICLES_DIR}):\n  (none — use download or new to get started)`;
-            }
             const rows = [];
             for (const file of files) {
                 const filePath = join(ARTICLES_DIR, file);
@@ -420,7 +505,37 @@ export function registerArticleTools(server) {
                 const modified = stat.mtime.toISOString().slice(0, 16).replace("T", " ");
                 rows.push(`  ${file}  —  "${title}"  (${size}, modified ${modified})`);
             }
-            return `${authLine}\n\nLocal articles (${files.length} file(s) in ${ARTICLES_DIR}):\n${rows.join("\n")}`;
+            try {
+                const dirs = readdirSync(ARTICLES_DIR).filter((entry) => {
+                    try {
+                        return statSync(join(ARTICLES_DIR, entry)).isDirectory();
+                    }
+                    catch {
+                        return false;
+                    }
+                });
+                for (const communitySlug of dirs) {
+                    const dir = join(ARTICLES_DIR, communitySlug);
+                    const communityFiles = readdirSync(dir).filter((f) => f.endsWith(".md") && !f.startsWith("."));
+                    for (const file of communityFiles) {
+                        const filePath = join(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(`  ${communitySlug}/${file}  —  "${title}"  (${size}, modified ${modified})`);
+                    }
+                }
+            }
+            catch { /* ignore subdir scan errors */ }
+            if (rows.length === 0) {
+                return `${authLine}\n\nLocal articles (0 files in ${ARTICLES_DIR}):\n  (none — use download or new to get started)`;
+            }
+            return `${authLine}\n\nLocal articles (${rows.length} file(s) in ${ARTICLES_DIR}):\n${rows.join("\n")}`;
         },
     });
 }

package/dist/validate.js

@@ -34,6 +34,30 @@ export function validateArticle(raw) {
             message: "Must be kebab-case (e.g. 'machine-learning'). Pattern: ^[a-z0-9]+(-[a-z0-9]+)*$",
         });
     }
+    const communitySlug = frontmatter.community_slug;
+    if (communitySlug != null && (typeof communitySlug !== "string" || !SLUG_RE.test(communitySlug))) {
+        errors.push({
+            field: "community_slug",
+            message: "Must be kebab-case (e.g. 'lockpicking'). Pattern: ^[a-z0-9]+(-[a-z0-9]+)*$",
+        });
+    }
+    const topics = frontmatter.topics;
+    if (topics != null) {
+        if (!Array.isArray(topics)) {
+            errors.push({ field: "topics", message: "Topics must be an array of kebab-case slugs" });
+        }
+        else {
+            for (let i = 0; i < topics.length; i++) {
+                const topic = topics[i];
+                if (typeof topic !== "string" || !SLUG_RE.test(topic)) {
+                    errors.push({
+                        field: `topics[${i}]`,
+                        message: "Must be kebab-case (e.g. 'spool-pins')",
+                    });
+                }
+            }
+        }
+    }
     // sources
     const sources = frontmatter.sources;
     if (!Array.isArray(sources)) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openalmanac",
-  "version": "0.2.33",
+  "version": "0.2.34",
   "description": "OpenAlmanac — pull, edit, and push articles to the open knowledge base",
   "type": "module",
   "bin": {