@dmthepm/commune 0.6.3 → 0.6.5

package/README.md

@@ -12,7 +12,7 @@ Start a wiki in one paste. You need Node 22.12 or newer, npm and Git.
 git clone --depth 1 https://github.com/dmthepm/commune-wiki.git && node commune-wiki/scripts/create-wiki.mjs my-wiki && cd my-wiki && npm install && npm run dev
 ```
 
-Open the address Astro prints. The clone is only the source of the copy, and you can delete it afterward. If you stop or have to guess, [tell me where it broke](https://github.com/dmthepm/commune-wiki/issues/85). A failed attempt is useful.
+Open the address Astro prints. The clone is only the source of the copy, and you can delete it afterward. To run the paste again, delete `commune-wiki` and `my-wiki` first, since both commands refuse to overwrite a folder. Run by a coding agent on macOS or Linux, Astro 7 starts the dev server in the background and prints its address as JSON. `npx astro dev stop` stops it. If you stop or have to guess, [tell me where it broke](https://github.com/dmthepm/commune-wiki/issues/85). A failed attempt is useful.
 
 ## Start a wiki
 
@@ -265,16 +265,18 @@ export async function GET(context) {
 
 Find connections and check your notes while you write, without building the site. The `commune` executable reads markdown directly from disk and answers without an Astro process running.
 
+In a wiki, the executable lives in `node_modules/.bin`, so run it through `npx`. The paths below are the starter's sample notes.
+
 ```bash
-commune check
-commune graph query --collection notes --orphans
-commune graph query --recent 7d
-commune update --recent 7d
-commune graph related src/content/notes/hello.md
-echo "a rough dump that mentions World" | commune graph related -
-commune render src/content/notes/hello.md
-echo '[[World]]' | commune render -
-commune gate
+npx commune check
+npx commune graph query --collection notes --orphans
+npx commune graph query --recent 7d
+npx commune update --recent 7d
+npx commune graph related src/content/notes/welcome.md
+echo "a rough dump that mentions Connected notes" | npx commune graph related -
+npx commune render src/content/notes/welcome.md
+echo '[[Connected notes]]' | npx commune render -
+npx commune gate
 ```
 
 | Verb | What it answers |
@@ -305,16 +307,16 @@ Exit codes report whether the command finished, never what it found — `0` fini
 These optional skills require an existing Commune wiki and access to Claude Code or Codex. They do not install the engine or scaffold a site. Install the four authoring skills from this repository.
 
 ```bash
-npx skills add dmthepm/commune-wiki
+npx skills add dmthepm/commune-wiki -a claude-code codex -s '*' -y
 ```
 
-The skills install for Claude Code and Codex, globally or into one project. They call the wiki's existing `node_modules/.bin/commune` directly, so authoring and publishing use the same CLI. They require version 0.4.0 or newer, check it first and install nothing themselves.
+That installs all four skills into the current project for Claude Code and Codex without prompts. Without the flags the installer asks, starts with no skills selected and lists Claude Code unticked among dozens of agents. Add `-g` to install for every project instead. They call the wiki's existing `node_modules/.bin/commune` directly, so authoring and publishing use the same CLI. They require version 0.4.0 or newer, check it first and install nothing themselves.
 
 `commune-setup` runs once per wiki and writes its `WRITING.md` rules. `commune-dump` saves dictated or pasted text verbatim to `dumps/<slug>.md` and records connection candidates and the check baseline in `dumps/<slug>.connect.md`. Here `<slug>` includes the capture date.
 
 `commune-write` asks one short round of editorial questions and waits for answers in `dumps/<slug>.answers.md`. It then drafts into the note and renders the original and draft side by side in `dumps/<slug>.review.html` for the author to review.
 
-On the author's instruction, `commune-ship` compares finding identities against the baseline, files an update, builds, gates and verifies each new href and destination file. It commits according to `WRITING.md`'s `dumps.commit` policy, opens a PR and records the receipt in `dumps/<slug>.ship.md`. The author approves the content. This skill never merges. That boundary governs authored content, while code maintenance follows the repository's contribution rules.
+On the author's instruction, `commune-ship` compares finding identities against the baseline, files an update, builds, gates and verifies each new href and destination file. It commits according to `WRITING.md`'s `dumps.commit` policy, opens a PR and records the receipt in `dumps/<slug>.ship.md`. That needs the wiki to be a Git repository with a GitHub remote and a way to open a pull request, such as `gh` signed in. The starter copy is neither, so run `git init` in it and push it to a repository of your own first. The author approves the content. This skill never merges. That boundary governs authored content, while code maintenance follows the repository's contribution rules.
 
 The four skills, their tests and the `WRITING.md` template ship today. An end to end run of the installed skills on a fresh starter wiki, from dictation to a gated commit, passed on October 1, 2026. Pushing and opening the pull request were not part of that run.
 

package/lib/cli/check.js

@@ -10,9 +10,9 @@
  * v1 is scoped to link integrity so it does not block on #17's collection
  * collapse. Frontmatter drift is a follow-up.
  */
-import { buildGraph, checkEntries, loadContentEntries, } from "../lib/graph.js";
-import { SCHEMA, writeJson, writeLines } from "./output.js";
-import { EXIT_OK } from "./errors.js";
+import { buildGraph, checkEntries, loadContentEntries, } from '../lib/graph.js';
+import { SCHEMA, writeJson, writeLines } from './output.js';
+import { EXIT_OK } from './errors.js';
 const RULES = [
     'broken-link',
     'ambiguous-target',

package/lib/cli/gate.js

@@ -28,9 +28,9 @@
  */
 import { readFile } from 'node:fs/promises';
 import path from 'node:path';
-import { findNoncanonicalTitles, loadContentEntries, stripCode, } from "../lib/graph.js";
-import { EXIT_FAILED, EXIT_OK, failure } from "./errors.js";
-import { SCHEMA, writeJson } from "./output.js";
+import { findNoncanonicalTitles, loadContentEntries, stripCode, } from '../lib/graph.js';
+import { EXIT_FAILED, EXIT_OK, failure } from './errors.js';
+import { SCHEMA, writeJson } from './output.js';
 const WIKILINK = /\[\[([^\]|]+)(?:\|[^\]]+)?\]\]/g;
 async function readSearchIndex(root) {
     // The public artifact, not the built one: `public/backlinks.json` is what
@@ -148,7 +148,14 @@ export async function gateCommand(root, dist, json) {
         ...(await pageLinksRender(entries, pages, distDir)),
     ];
     const passed = failures.length === 0;
-    const summary = `${pages.length} standalone page${pages.length === 1 ? '' : 's'} indexed for search and linked from notes`;
+    // Name what was checked, not only the standalone-page count. A starter
+    // wiki has no standalone pages, and "0 pages indexed" alone reads as if
+    // the gate looked at nothing.
+    const checked = `${entries.length} ${entries.length === 1 ? 'entry' : 'entries'} checked, every resolved WikiLink uses its target's exact title`;
+    const indexed = pages.length
+        ? `${pages.length} standalone page${pages.length === 1 ? '' : 's'} indexed for search and linked from notes`
+        : 'no standalone pages to index';
+    const summary = `${checked}, ${indexed}`;
     if (json) {
         writeJson({ schema: SCHEMA, passed, failures });
     }

package/lib/cli/main.js

@@ -12,17 +12,17 @@
  * JSON: `--json` is known before the strict parse that rejects the argv.
  */
 import { parseArgs } from 'node:util';
-import { CliError, EXIT_OK, EXIT_USAGE, isParseArgsError, usageError } from "./errors.js";
-import { writeError } from "./output.js";
-import { resolveRoot } from "./root.js";
-import { toIsoDay } from "../lib/graph.js";
-import { parseRecent, queryCommand } from "./query.js";
-import { checkCommand } from "./check.js";
-import { gateCommand } from "./gate.js";
-import { relatedCommand } from "./related.js";
-import { updateCommand } from "./update.js";
-import { COMMAND_USAGE, USAGE } from "./usage.js";
-import { readVersion } from "./version.js";
+import { CliError, EXIT_OK, EXIT_USAGE, isParseArgsError, usageError } from './errors.js';
+import { writeError } from './output.js';
+import { resolveRoot } from './root.js';
+import { toIsoDay } from '../lib/graph.js';
+import { parseRecent, queryCommand } from './query.js';
+import { checkCommand } from './check.js';
+import { gateCommand } from './gate.js';
+import { relatedCommand } from './related.js';
+import { updateCommand } from './update.js';
+import { COMMAND_USAGE, USAGE } from './usage.js';
+import { readVersion } from './version.js';
 /** Options understood everywhere, in any position. */
 const GLOBAL = {
     root: { type: 'string' },
@@ -173,7 +173,7 @@ async function dispatch(args) {
             // `check`, and an outright failure in a project that has the CLI but
             // not the renderer, which is the opposite of the promise the rest of
             // this CLI makes about running without Astro.
-            const { renderCommand } = await import("./render.js");
+            const { renderCommand } = await import('./render.js');
             return renderCommand(await resolveRoot(values.root), positionals[0], site, values.json);
         }
         case 'check': {

package/lib/cli/query.js

@@ -6,9 +6,9 @@
  * per note. Filters narrow which entries are *returned*; they never change how
  * links resolve, so an entry's degree is the same whether or not you filtered.
  */
-import { buildGraph, loadContentEntries, toIsoDay, } from "../lib/graph.js";
-import { SCHEMA, writeJson, writeLines } from "./output.js";
-import { EXIT_OK } from "./errors.js";
+import { buildGraph, loadContentEntries, toIsoDay, } from '../lib/graph.js';
+import { SCHEMA, writeJson, writeLines } from './output.js';
+import { EXIT_OK } from './errors.js';
 /**
  * Resolve `--recent` to the day it means.
  *

package/lib/cli/related.js

@@ -17,10 +17,10 @@
  * written `Noontide` are the same name spelled two ways, and matching them is
  * still an exact match — just of the right string.
  */
-import { buildGraph, buildLinkLookup, buildUrlLookup, extractLinks, loadContentEntries, resolveLink, stripCode, } from "../lib/graph.js";
-import { SCHEMA, writeJson, writeLines } from "./output.js";
-import { EXIT_OK } from "./errors.js";
-import { readSource } from "./source.js";
+import { buildGraph, buildLinkLookup, buildUrlLookup, extractLinks, loadContentEntries, resolveLink, stripCode, } from '../lib/graph.js';
+import { SCHEMA, writeJson, writeLines } from './output.js';
+import { EXIT_OK } from './errors.js';
+import { readSource } from './source.js';
 /**
  * Shortest name worth matching, measured after normalisation. Below this, a
  * mention is noise — `B` would make every capital B a connection.

package/lib/cli/render.js

@@ -19,12 +19,12 @@
  * the time there is HTML the broken link is indistinguishable from a sentence,
  * and the one thing a reviewer most needs to be told is gone.
  */
-import { communeMarkdown } from "../markdown.js";
-import { buildLinkLookup, buildUrlLookup, extractLinks, loadContentEntries, resolveLink, } from "../lib/graph.js";
-import { SCHEMA, writeJson } from "./output.js";
-import { EXIT_OK } from "./errors.js";
-import { readSource } from "./source.js";
-import { resolveSite } from "./site.js";
+import { communeMarkdown } from '../markdown.js';
+import { buildLinkLookup, buildUrlLookup, extractLinks, loadContentEntries, resolveLink, } from '../lib/graph.js';
+import { SCHEMA, writeJson } from './output.js';
+import { EXIT_OK } from './errors.js';
+import { readSource } from './source.js';
+import { resolveSite } from './site.js';
 export async function renderCommand(root, input, siteFlag, json) {
     // Read before anything else: `-` has to consume stdin before a slow scan of
     // the content tree, or a producer writing into the pipe waits on us.

package/lib/cli/root.js

@@ -10,7 +10,7 @@
  */
 import { stat } from 'node:fs/promises';
 import path from 'node:path';
-import { failure } from "./errors.js";
+import { failure } from './errors.js';
 export async function resolveRoot(value) {
     const root = path.resolve(value ?? process.cwd());
     const content = path.join(root, 'src', 'content');

package/lib/cli/source.js

@@ -15,7 +15,7 @@
 import { readFile, stat } from 'node:fs/promises';
 import path from 'node:path';
 import matter from 'gray-matter';
-import { failure } from "./errors.js";
+import { failure } from './errors.js';
 async function isFile(candidate) {
     try {
         return (await stat(candidate)).isFile();

package/lib/cli/update.js

@@ -15,9 +15,9 @@
  */
 import { mkdir, stat, writeFile } from 'node:fs/promises';
 import path from 'node:path';
-import { CONTENT_DIRS, loadContentEntries } from "../lib/graph.js";
-import { SCHEMA, writeJson, writeLines } from "./output.js";
-import { EXIT_OK, failure } from "./errors.js";
+import { CONTENT_DIRS, loadContentEntries } from '../lib/graph.js';
+import { SCHEMA, writeJson, writeLines } from './output.js';
+import { EXIT_OK, failure } from './errors.js';
 /**
  * The entry, as markdown.
  *

package/lib/integration.js

@@ -8,10 +8,10 @@
  * core in `src/lib/graph.ts`, so the `commune` CLI produces the same graph
  * without an Astro process anywhere in sight.
  */
-import { copyFile, writeFile, mkdir } from 'node:fs/promises';
+import { copyFile, readFile, writeFile, mkdir } from 'node:fs/promises';
 import { fileURLToPath } from 'node:url';
 import path from 'node:path';
-import { buildGraph, formatDiagnostic, loadContentEntries, summarizeSite, toBacklinksJson, toMarkdownPath, } from "./lib/graph.js";
+import { buildGraph, formatDiagnostic, loadContentEntries, summarizeSite, toBacklinksJson, toMarkdownPath, } from './lib/graph.js';
 function buildBacklinksGraph(entries, logger) {
     const graph = buildGraph(entries);
     logger.info(`📝 Found ${Object.keys(graph.nodes).length} public content entries`);
@@ -64,6 +64,37 @@ async function writeMarkdownFiles(entries, root, outDir) {
     }
     return entries.length;
 }
+/**
+ * The dev server's answer to a `<url>.md` request: the same source file the
+ * build copies, read on each request so an edit shows up without a restart.
+ *
+ * The build writes twins in `astro:build:done`, which `astro dev` never runs,
+ * so without this a page's "view as markdown" link 404s in exactly the server
+ * a first run lands in. The lookup goes through `toMarkdownPath`, the mapping
+ * the build writer uses, so dev and build cannot disagree about which URL is
+ * which file. Anything that is not a twin falls through to Astro.
+ */
+async function findMarkdownTwin(root, pathname) {
+    if (!pathname.endsWith('.md'))
+        return undefined;
+    let requested;
+    try {
+        requested = decodeURI(pathname).replace(/^\/+/, '');
+    }
+    catch {
+        return undefined;
+    }
+    const entries = await loadContentEntries({ root });
+    const entry = entries.find((candidate) => {
+        try {
+            return toMarkdownPath(candidate.urlPath) === requested;
+        }
+        catch {
+            return false;
+        }
+    });
+    return entry ? path.join(root, entry.file) : undefined;
+}
 function summarize(graph) {
     return `📊 ${graph.totalBacklinks} total backlinks across ${Object.keys(graph.nodes).length} entries`;
 }
@@ -105,6 +136,32 @@ export default function commune(_options = {}) {
                     throw error;
                 }
             },
+            'astro:server:setup': ({ server, logger }) => {
+                server.middlewares.use((request, response, next) => {
+                    const pathname = new URL(request.url ?? '/', 'http://localhost').pathname;
+                    if (request.method !== 'GET' && request.method !== 'HEAD')
+                        return next();
+                    if (!pathname.endsWith('.md'))
+                        return next();
+                    // Vite's own module and file requests are never twins, and each
+                    // lookup reads the whole vault, so they skip it.
+                    if (/^\/(?:src\/|node_modules\/|@)/.test(pathname))
+                        return next();
+                    findMarkdownTwin(root, pathname)
+                        .then(async (file) => {
+                        if (!file)
+                            return next();
+                        const source = await readFile(file);
+                        response.setHeader('Content-Type', 'text/markdown; charset=utf-8');
+                        response.setHeader('Content-Length', source.byteLength);
+                        response.end(request.method === 'HEAD' ? undefined : source);
+                    })
+                        .catch((error) => {
+                        logger.error(`Failed to serve ${pathname}: ${String(error)}`);
+                        next(error);
+                    });
+                });
+            },
             'astro:build:done': async ({ dir, logger }) => {
                 logger.info('🔗 Building backlinks index...');
                 try {

package/lib/lib/graph.js

@@ -16,13 +16,13 @@
  *   - the title/alias lookup used to resolve `[[WikiLinks]]`
  *   - which link forms count as an edge, and how each one resolves
  */
-import { globby } from 'globby';
+import { glob } from 'tinyglobby';
 import { slug as githubSlug } from 'github-slugger';
 import matter from 'gray-matter';
 import { readFile } from 'node:fs/promises';
 import path from 'node:path';
-import { readContentHistory, readMtimeDate, } from "./dates.js";
-export { SHALLOW_WARNING, toIsoDay } from "./dates.js";
+import { readContentHistory, readMtimeDate, } from './dates.js';
+export { SHALLOW_WARNING, toIsoDay } from './dates.js';
 /** Where each collection's markdown lives, relative to the project root. */
 export const CONTENT_DIRS = {
     notes: 'src/content/notes',
@@ -206,9 +206,12 @@ export async function loadContentEntries(options = {}) {
     // alternative is a `git log` per file, which is a child process per note.
     const history = await readContentHistory(root, Object.values(CONTENT_DIRS));
     for (const collection of COLLECTIONS) {
-        // `cwd` keeps globby's results root-relative, which is exactly the
+        // `cwd` keeps tinyglobby's results root-relative, which is exactly the
         // spelling `ContentEntry.file` promises; only the read needs the join.
-        const files = await globby(`${CONTENT_DIRS[collection]}/**/*.{md,mdx}`, { cwd: root });
+        const files = await glob(`${CONTENT_DIRS[collection]}/**/*.{md,mdx}`, {
+            cwd: root,
+            expandDirectories: false,
+        });
         files.sort();
         for (const file of files) {
             const source = await readFile(path.join(root, file), 'utf8');

package/lib/markdown.js

@@ -14,8 +14,8 @@
  * own origin, which lives once in their `defineConfig({ site })`.
  */
 import { unified } from '@astrojs/markdown-remark';
-import remarkWikiLinks from "./remark-wikilinks.js";
-import rehypeExternalLinks from "./rehype-external-links.js";
+import remarkWikiLinks from './remark-wikilinks.js';
+import rehypeExternalLinks from './rehype-external-links.js';
 export function communeMarkdown({ site, root } = {}) {
     return unified({
         remarkPlugins: [[remarkWikiLinks, { root }]],

package/lib/remark-wikilinks.js

@@ -10,7 +10,7 @@
  * graph core in `src/lib/graph.ts` — not here.
  */
 import { visit } from 'unist-util-visit';
-import { getLinkLookup, linkKey } from "./lib/graph.js";
+import { getLinkLookup, linkKey } from './lib/graph.js';
 /**
  * Remark plugin function.
  *

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@dmthepm/commune",
   "type": "module",
-  "version": "0.6.3",
+  "version": "0.6.5",
   "description": "Maintain a personal wiki from markdown notes, dictated thoughts and everyday work with authoring tools, a shared link graph and portable Astro publishing.",
   "license": "MIT",
   "keywords": [
@@ -82,8 +82,8 @@
   },
   "dependencies": {
     "github-slugger": "^2.0.0",
-    "globby": "^16.2.4",
     "gray-matter": "^4.0.3",
+    "tinyglobby": "^0.2.17",
     "unist-util-visit": "^5.1.0"
   },
   "devDependencies": {
@@ -94,6 +94,6 @@
     "@types/node": "^22.20.1",
     "astro": "^7.2.10",
     "tailwindcss": "^3.4.0",
-    "typescript": "^5.6.0"
+    "typescript": "^7.0.2"
   }
 }