openalmanac 0.4.0 → 0.4.1

package/dist/tools/{pages.js → pages/index.js}

@@ -1,168 +1,12 @@
 import { z } from "zod";
-import { readFileSync, writeFileSync, mkdirSync, readdirSync, existsSync, unlinkSync } from "node:fs";
-import { join } from "node:path";
+import { readFileSync, writeFileSync, mkdirSync, readdirSync, existsSync } from "node:fs";
 import { stringify as yamlStringify } from "yaml";
-import { request, PAGES_DIR } from "../auth.js";
-import { openBrowser } from "../browser.js";
-import { coerceJson } from "../utils.js";
-const SLUG_RE = /^[a-z0-9]+(-[a-z0-9]+)*$/;
-function resolvePageDir(wikiSlug) {
-    return join(PAGES_DIR, wikiSlug);
-}
-function resolvePagePaths(slug, wikiSlug) {
-    const dir = resolvePageDir(wikiSlug);
-    return {
-        dir,
-        filePath: join(dir, `${slug}.md`),
-        refPath: join(dir, `.${slug}.ref`),
-    };
-}
-const WRITING_GUIDE = `
-## Page structure
-
-\`\`\`yaml
----
-title: Page Title
-wiki: wiki-slug
-topics: [topic-one, topic-two]
-sources:
-  - key: example-source
-    url: https://example.com
-    title: Source Title
-    accessed_date: "2025-01-15"
-infobox:
-  header:
-    image_url: https://...
-    subtitle: Short tagline
-    details:
-      - key: Born
-        value: January 1, 1990
----
-
-Page body with [@key] citation markers and [[wikilinks]]...
-\`\`\`
-
-## Wikilinks
-
-- Write natural text in double brackets: [[spool pins]], [[pin tumbler locks]]
-- Display text: [[spool-pins|spool pins]]
-- Cross-wiki: [[global:reddit|Reddit]], [[lockpicking:spool-pins|spool pins]]
-
-## Citations
-
-- Mark claims with [@key] after punctuation
-- Keys must be kebab-case with at least one hyphen
-- Every source must be referenced; every reference must have a source
-
-## Quoting
-
-For any string value with punctuation, quotes, or special characters (common in \`sources[].title\`), use YAML block-literal syntax:
-
-\`\`\`yaml
-sources:
-  - key: farza-yc
-    title: |-
-      "I'm joining Y Combinator, again" — Farza Majeed
-    url: https://...
-\`\`\`
-
-This sidesteps every YAML escaping rule. If you skip this, inner double quotes or em-dashes will break the parser.
-
-## Images
-
-Use search_images to find relevant images. Syntax: \`![Caption](url "position")\`
-Positions: "right" (default), "left", "center". Every image needs a descriptive caption.
-`.trim();
-function formatPublishResults(results, targetSlugs, wiki_slug, dry_run) {
-    const allAutoStubs = new Set();
-    const lines = [];
-    let okCount = 0;
-    let errorCount = 0;
-    for (let i = 0; i < results.length; i++) {
-        const r = results[i];
-        const slug = targetSlugs[i] ?? r.slug;
-        if (dry_run && r.plan) {
-            const plan = r.plan;
-            const hasError = plan.validation.status === "failed" ||
-                !plan.authorization.can_write ||
-                plan.action === "error";
-            if (hasError) {
-                errorCount++;
-                const reasons = [];
-                for (const e of plan.validation.errors) {
-                    reasons.push(`${e.field}: ${e.message}`);
-                }
-                if (!plan.authorization.can_write && plan.authorization.reason) {
-                    reasons.push(`auth: ${plan.authorization.reason}`);
-                }
-                lines.push(`- ${slug}: **error** — ${reasons.join("; ")}`);
-            }
-            else {
-                okCount++;
-                let line = `- ${plan.slug}: **${plan.action}**`;
-                if (plan.renamed_from)
-                    line += ` (rename: ${plan.renamed_from} → ${plan.slug})`;
-                const details = [];
-                if (plan.source_keys.referenced.length > 0) {
-                    details.push(`${plan.source_keys.referenced.length} source(s)`);
-                }
-                if (plan.wikilinks.will_auto_stub.length > 0) {
-                    details.push(`${plan.wikilinks.will_auto_stub.length} new stub(s)`);
-                    plan.wikilinks.will_auto_stub.forEach(s => allAutoStubs.add(s));
-                }
-                const inBatchLinks = plan.wikilinks.in_batch ?? [];
-                if (inBatchLinks.length > 0) {
-                    details.push(`${inBatchLinks.length} in-batch link(s)`);
-                }
-                if (plan.source_keys.orphaned.length > 0) {
-                    details.push(`missing source key(s): ${plan.source_keys.orphaned.join(", ")}`);
-                }
-                if (plan.source_keys.unreferenced.length > 0) {
-                    details.push(`unreferenced source(s): ${plan.source_keys.unreferenced.join(", ")}`);
-                }
-                if (details.length > 0)
-                    line += ` (${details.join(", ")})`;
-                lines.push(line);
-            }
-        }
-        else {
-            // Real publish result
-            if (r.status === "error") {
-                errorCount++;
-                lines.push(`- ${r.slug}: **error** — ${r.error}`);
-            }
-            else {
-                okCount++;
-                // Clean up local files — pre-rename slug names the file
-                const fileSlug = r.renamed_from ?? slug;
-                const { filePath, refPath } = resolvePagePaths(fileSlug, wiki_slug);
-                try {
-                    unlinkSync(filePath);
-                }
-                catch { /* ok */ }
-                try {
-                    unlinkSync(refPath);
-                }
-                catch { /* ok */ }
-                let line = `- ${r.slug}: **${r.status}**`;
-                if (r.renamed_from)
-                    line += ` (renamed from ${r.renamed_from})`;
-                if (r.stubs_created?.length) {
-                    r.stubs_created.forEach(s => allAutoStubs.add(s));
-                }
-                lines.push(line);
-            }
-        }
-    }
-    const verb = dry_run ? "Dry-run" : "Published";
-    const summary = `${verb}: ${okCount}/${targetSlugs.length} OK${errorCount > 0 ? `, ${errorCount} error(s)` : ""}.`;
-    const parts = [summary, "", ...lines];
-    if (allAutoStubs.size > 0) {
-        const stubVerb = dry_run ? "Stubs that will be auto-created" : "Stubs auto-created";
-        parts.push("", `${stubVerb}: ${[...allAutoStubs].join(", ")}`);
-    }
-    return parts.join("\n");
-}
+import { request } from "../../auth.js";
+import { openBrowser } from "../../browser.js";
+import { coerceJson } from "../../utils.js";
+import { formatPublishResults } from "./publish-format.js";
+import { resolvePageDir, resolvePagePaths, SLUG_RE } from "./workspace.js";
+import { WRITING_GUIDE } from "./writing-guide.js";
 export function registerPageTools(server) {
     server.addTool({
         name: "search_pages",
@@ -312,7 +156,7 @@ export function registerPageTools(server) {
                         .replace(/^-+|-+$/g, "")
                         .replace(/-{2,}/g, "-") || "untitled";
                 }
-                const filePath = join(dir, `${fileSlug}.md`);
+                const { filePath } = resolvePagePaths(fileSlug, wiki_slug);
                 if (existsSync(filePath)) {
                     skipped.push(`${fileSlug}.md already exists`);
                     continue;

package/dist/tools/pages/publish-format.d.ts

@@ -0,0 +1,48 @@
+export type PublishPlanValidation = {
+    status: string;
+    errors: Array<{
+        field: string;
+        message: string;
+    }>;
+};
+export type PublishPlanAuthorization = {
+    can_write: boolean;
+    reason?: string;
+};
+export type PublishPlanWikilinks = {
+    found: string[];
+    in_batch?: string[];
+    stubs: string[];
+    will_auto_stub: string[];
+};
+export type PublishPlanSourceKeys = {
+    referenced: string[];
+    unreferenced: string[];
+    orphaned: string[];
+};
+export type PublishPlanInfobox = {
+    status: string;
+    errors: Array<{
+        field: string;
+        message: string;
+    }>;
+};
+export type PublishPlan = {
+    action: string;
+    slug: string;
+    renamed_from?: string;
+    validation: PublishPlanValidation;
+    authorization: PublishPlanAuthorization;
+    wikilinks: PublishPlanWikilinks;
+    source_keys: PublishPlanSourceKeys;
+    infobox: PublishPlanInfobox;
+};
+export type PublishResult = {
+    slug: string;
+    status: string;
+    renamed_from?: string;
+    stubs_created?: string[];
+    error?: string;
+    plan?: PublishPlan;
+};
+export declare function formatPublishResults(results: PublishResult[], targetSlugs: string[], wiki_slug: string, dry_run: boolean): string;

package/dist/tools/pages/publish-format.js

@@ -0,0 +1,92 @@
+import { unlinkSync } from "node:fs";
+import { resolvePagePaths } from "./workspace.js";
+export function formatPublishResults(results, targetSlugs, wiki_slug, dry_run) {
+    const allAutoStubs = new Set();
+    const lines = [];
+    let okCount = 0;
+    let errorCount = 0;
+    for (let i = 0; i < results.length; i++) {
+        const r = results[i];
+        const slug = targetSlugs[i] ?? r.slug;
+        if (dry_run && r.plan) {
+            const plan = r.plan;
+            const hasError = plan.validation.status === "failed" ||
+                !plan.authorization.can_write ||
+                plan.action === "error";
+            if (hasError) {
+                errorCount++;
+                const reasons = [];
+                for (const e of plan.validation.errors) {
+                    reasons.push(`${e.field}: ${e.message}`);
+                }
+                if (!plan.authorization.can_write && plan.authorization.reason) {
+                    reasons.push(`auth: ${plan.authorization.reason}`);
+                }
+                lines.push(`- ${slug}: **error** — ${reasons.join("; ")}`);
+            }
+            else {
+                okCount++;
+                let line = `- ${plan.slug}: **${plan.action}**`;
+                if (plan.renamed_from)
+                    line += ` (rename: ${plan.renamed_from} → ${plan.slug})`;
+                const details = [];
+                if (plan.source_keys.referenced.length > 0) {
+                    details.push(`${plan.source_keys.referenced.length} source(s)`);
+                }
+                if (plan.wikilinks.will_auto_stub.length > 0) {
+                    details.push(`${plan.wikilinks.will_auto_stub.length} new stub(s)`);
+                    plan.wikilinks.will_auto_stub.forEach(s => allAutoStubs.add(s));
+                }
+                const inBatchLinks = plan.wikilinks.in_batch ?? [];
+                if (inBatchLinks.length > 0) {
+                    details.push(`${inBatchLinks.length} in-batch link(s)`);
+                }
+                if (plan.source_keys.orphaned.length > 0) {
+                    details.push(`missing source key(s): ${plan.source_keys.orphaned.join(", ")}`);
+                }
+                if (plan.source_keys.unreferenced.length > 0) {
+                    details.push(`unreferenced source(s): ${plan.source_keys.unreferenced.join(", ")}`);
+                }
+                if (details.length > 0)
+                    line += ` (${details.join(", ")})`;
+                lines.push(line);
+            }
+        }
+        else {
+            // Real publish result
+            if (r.status === "error") {
+                errorCount++;
+                lines.push(`- ${r.slug}: **error** — ${r.error}`);
+            }
+            else {
+                okCount++;
+                // Clean up local files — pre-rename slug names the file
+                const fileSlug = r.renamed_from ?? slug;
+                const { filePath, refPath } = resolvePagePaths(fileSlug, wiki_slug);
+                try {
+                    unlinkSync(filePath);
+                }
+                catch { /* ok */ }
+                try {
+                    unlinkSync(refPath);
+                }
+                catch { /* ok */ }
+                let line = `- ${r.slug}: **${r.status}**`;
+                if (r.renamed_from)
+                    line += ` (renamed from ${r.renamed_from})`;
+                if (r.stubs_created?.length) {
+                    r.stubs_created.forEach(s => allAutoStubs.add(s));
+                }
+                lines.push(line);
+            }
+        }
+    }
+    const verb = dry_run ? "Dry-run" : "Published";
+    const summary = `${verb}: ${okCount}/${targetSlugs.length} OK${errorCount > 0 ? `, ${errorCount} error(s)` : ""}.`;
+    const parts = [summary, "", ...lines];
+    if (allAutoStubs.size > 0) {
+        const stubVerb = dry_run ? "Stubs that will be auto-created" : "Stubs auto-created";
+        parts.push("", `${stubVerb}: ${[...allAutoStubs].join(", ")}`);
+    }
+    return parts.join("\n");
+}

package/dist/tools/pages/workspace.d.ts

@@ -0,0 +1,7 @@
+export declare const SLUG_RE: RegExp;
+export declare function resolvePageDir(wikiSlug: string): string;
+export declare function resolvePagePaths(slug: string, wikiSlug: string): {
+    dir: string;
+    filePath: string;
+    refPath: string;
+};

package/dist/tools/pages/workspace.js

@@ -0,0 +1,14 @@
+import { join } from "node:path";
+import { PAGES_DIR } from "../../auth.js";
+export const SLUG_RE = /^[a-z0-9]+(-[a-z0-9]+)*$/;
+export function resolvePageDir(wikiSlug) {
+    return join(PAGES_DIR, wikiSlug);
+}
+export function resolvePagePaths(slug, wikiSlug) {
+    const dir = resolvePageDir(wikiSlug);
+    return {
+        dir,
+        filePath: join(dir, `${slug}.md`),
+        refPath: join(dir, `.${slug}.ref`),
+    };
+}

package/dist/tools/pages/writing-guide.d.ts

@@ -0,0 +1 @@
+export declare const WRITING_GUIDE: string;

package/dist/tools/pages/writing-guide.js

@@ -0,0 +1,56 @@
+export const WRITING_GUIDE = `
+## Page structure
+
+\`\`\`yaml
+---
+title: Page Title
+wiki: wiki-slug
+topics: [topic-one, topic-two]
+sources:
+  - key: example-source
+    url: https://example.com
+    title: Source Title
+    accessed_date: "2025-01-15"
+infobox:
+  header:
+    image_url: https://...
+    subtitle: Short tagline
+    details:
+      - key: Born
+        value: January 1, 1990
+---
+
+Page body with [@key] citation markers and [[wikilinks]]...
+\`\`\`
+
+## Wikilinks
+
+- Write natural text in double brackets: [[spool pins]], [[pin tumbler locks]]
+- Display text: [[spool-pins|spool pins]]
+- Cross-wiki: [[global:reddit|Reddit]], [[lockpicking:spool-pins|spool pins]]
+
+## Citations
+
+- Mark claims with [@key] after punctuation
+- Keys must be kebab-case with at least one hyphen
+- Every source must be referenced; every reference must have a source
+
+## Quoting
+
+For any string value with punctuation, quotes, or special characters (common in \`sources[].title\`), use YAML block-literal syntax:
+
+\`\`\`yaml
+sources:
+  - key: farza-yc
+    title: |-
+      "I'm joining Y Combinator, again" — Farza Majeed
+    url: https://...
+\`\`\`
+
+This sidesteps every YAML escaping rule. If you skip this, inner double quotes or em-dashes will break the parser.
+
+## Images
+
+Use search_images to find relevant images. Syntax: \`![Caption](url "position")\`
+Positions: "right" (default), "left", "center". Every image needs a descriptive caption.
+`.trim();

package/package.json

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