@dmthepm/commune 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-2026 Devon Meadows
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,468 @@
+# Commune Wiki
+
+An Astro wiki engine — WikiLinks, sliding panes, backlinks, static search — and a `commune` CLI that queries the content graph and checks links.
+
+**License**: MIT · **Live example**: [devonmeadows.com](https://devonmeadows.com)
+
+---
+
+## ✨ Features
+
+- 🔗 **WikiLinks**: `[[Note Title]]` automatically converts to links
+- 📑 **Sliding Panes**: Andy Matuschak-style cascading note navigation
+- 👁️ **Hover Previews**: See note content on hover before clicking
+- 🔄 **Backlinks**: Auto-generated bidirectional link graph
+- 🎨 **Design System**: Custom CSS variables with light/dark mode
+- 🔍 **Search**: Cmd-K palette with Pagefind static search
+- 📝 **Markdown-First**: Git-backed content, version controlled
+- 🚀 **Fast**: Static site generation (no runtime database)
+- 🎯 **Zero Config**: Works out of the box, customize as needed
+
+---
+
+## 🎯 Who Is This For?
+
+**Personal Knowledge Management**:
+- Researchers building interconnected notes (Zettelkasten/Evergreen Notes)
+- Writers managing drafts, research, and published content
+- Developers documenting code, decisions, and learnings
+- Anyone tired of silo'd notes in proprietary apps
+
+**vs. Other Tools**:
+| Tool | Approach | Commune Wiki |
+|------|----------|--------------|
+| Obsidian | Desktop app, proprietary sync | Web-first, self-hosted, MIT |
+| Notion | Cloud SaaS, vendor lock-in | Git-backed, own your data |
+| Roam | SaaS, $15/mo | Free, open source, MIT |
+| Logseq | Local-first, complex setup | Simple Astro build, deploy anywhere |
+
+---
+
+## 🚀 Quick Start
+
+### Prerequisites
+
+- Node.js 22.18+ and pnpm
+
+### Install & Run
+
+```bash
+# Clone repository
+git clone git@github.com:dmthepm/commune-wiki.git
+cd commune-wiki
+
+# Install dependencies
+pnpm install
+
+# Start dev server (http://localhost:4321)
+pnpm dev
+
+# Build for production
+pnpm build
+
+# Preview production build
+pnpm preview
+```
+
+### Install
+
+The engine is a package. Add it to an Astro 7 project:
+
+```bash
+pnpm add @dmthepm/commune
+```
+
+npm and yarn take the same line. The published tarball ships `lib/` already
+compiled, so nothing builds on install, no build script needs approving, and a
+consumer needs only Node 22.12+ — Astro's own floor.[^git]
+
+[^git]: **Before `v0.1.0` reaches npm, install from a git ref instead** —
+    `pnpm add github:dmthepm/commune-wiki#<tag>` — and pnpm consumers need one
+    extra line for it, because a git dependency arrives as source and compiles
+    itself in its `prepare` script. pnpm 10 refuses to run that unless your
+    project names the package, and without the entry the install fails with
+    `ERR_PNPM_GIT_DEP_PREPARE_NOT_ALLOWED`. The details are folded below; all
+    of it goes away on the first npm publish, which is what this footnote is
+    counting down to.
+
+<details>
+<summary>Installing from a git ref, in full</summary>
+
+```jsonc
+// your package.json
+{
+  "dependencies": {
+    "@dmthepm/commune": "github:dmthepm/commune-wiki#<tag>"
+  },
+  "pnpm": {
+    "onlyBuiltDependencies": ["@dmthepm/commune@github:dmthepm/commune-wiki#<tag>"]
+  }
+}
+```
+
+Note the entry is `name@spec`, not the bare name — a bare name approves a
+package from the registry, and for a git dependency pnpm matches the whole
+specifier, so a name on its own is silently not a match. It has to be the same
+specifier you wrote in `dependencies`, which means it changes when you bump the
+tag. The same entry works in `pnpm-workspace.yaml` if you keep pnpm settings
+there.
+
+**Older pnpm 10 wants the other spelling.** Around 10.19 the `name@spec` form is
+rejected with `ERR_PNPM_INVALID_VERSION_UNION` ("Use exact versions only") and
+the bare `"@dmthepm/commune"` is what works — those releases also approve a git
+dependency's build scripts on their own, so you may need nothing at all. Do not
+guess which side of the line you are on: run the install and read the error.
+pnpm prints the exact entry your version expects.
+
+npm and yarn need nothing extra — they run a git dependency's `prepare` without
+asking.
+
+</details>
+
+### Create Your First Note
+
+```bash
+# Create a note in src/content/notes/
+cat > src/content/notes/hello-world.md << 'MDEOF'
+---
+title: "Hello World"
+visibility: "public"
+status: "evergreen"
+summary: "My first note"
+tags: [getting-started]
+---
+
+Welcome to your personal wiki!
+
+Link to other notes with [[Note Title]] syntax.
+MDEOF
+
+# Start dev server and visit http://localhost:4321
+pnpm dev
+```
+
+---
+
+## 📁 Project Structure
+
+```
+commune-wiki/
+├── src/
+│   ├── content/
+│   │   ├── config.ts       # Content collection schemas
+│   │   └── notes/          # Your markdown notes
+│   ├── components/
+│   │   ├── Header.astro    # Site header
+│   │   ├── SearchModal.astro
+│   │   └── Backlinks.astro
+│   ├── pages/
+│   │   ├── index.astro     # Homepage
+│   │   └── notes/
+│   │       └── [...slug].astro   # Note pages + pane logic
+│   └── styles/
+│       ├── design-system.css  # Custom CSS variables
+│       └── notes.css          # Note typography
+├── public/
+│   └── backlinks.json      # Auto-generated backlinks graph
+├── astro.config.mjs        # Astro config + remark plugins
+└── package.json
+```
+
+---
+
+## ✍️ Writing Notes
+
+### Note Schema
+
+Every note requires frontmatter:
+
+```markdown
+---
+title: "Note Title"
+visibility: "public"        # public | private | draft
+status: "evergreen"         # seed | growing | evergreen
+summary: "Brief description for previews"
+tags: [tag1, tag2]
+aliases: ["Short Name"]
+updated: 2025-10-21
+---
+
+Your note content here with [[WikiLinks]] to other notes.
+```
+
+**Visibility**:
+- `public` - Published to site (default: only public notes shown)
+- `private` - Not published
+- `draft` - Work in progress, not indexed
+
+**Status**:
+- `seed` - Early idea, needs development
+- `growing` - Actively being refined
+- `evergreen` - Well-developed, stable
+
+### WikiLinks Syntax
+
+```markdown
+[[Note Title]]                    → Links to note
+[[Note Title|Display Text]]       → Custom text
+[[Multi-word Note]]               → Normalized matching
+```
+
+**How it works**:
+1. Build-time plugin scans all notes
+2. Creates title → slug lookup index
+3. Transforms `[[Title]]` to `<a href="/notes/slug/">`
+4. Broken links render as plain text (not clickable)
+
+---
+
+## 🎨 Customization
+
+### Design System
+
+Edit `src/styles/design-system.css`:
+
+```css
+:root {
+  --c-bg: #0a0a0b;
+  --c-accent: #8b7bff;
+  --c-text: #e8e6e3;
+  /* ... customize colors ... */
+}
+
+[data-theme="light"] {
+  --c-bg: #fafaf9;
+  /* ... light mode overrides ... */
+}
+```
+
+### Typography
+
+Edit `src/styles/notes.css` for note-specific styling (headings, lists, code blocks).
+
+### Pane Behavior
+
+Pane logic in `src/pages/notes/[...slug].astro`:
+
+```javascript
+// Customize pane behavior:
+setupPanes()        // Initialize
+openPane(url)       // Open new pane
+closePane(pane)     // Remove pane
+```
+
+---
+
+## 🔍 Search
+
+**Pagefind** generates a static search index at build time:
+
+- No server required
+- Instant client-side search
+- Automatically indexes all public notes
+- Cmd-K hotkey to open search modal
+
+**Dev mode**: Falls back to backlinks.json when Pagefind not available.
+
+---
+
+## 📊 Backlinks
+
+Backlinks are auto-generated at build time via the `src/integration.ts` integration:
+
+1. Scans all notes for WikiLinks
+2. Creates bidirectional graph
+3. Outputs to `public/backlinks.json` and `<outDir>/backlinks.json`
+4. Displayed in `Backlinks.astro` component ("Links to this note")
+
+---
+
+## 🚀 Deployment
+
+### Static Hosting (Recommended)
+
+**Cloudflare Pages / Vercel / Netlify**:
+
+```bash
+# Build command
+pnpm build
+
+# Output directory
+dist/
+
+# Deploy
+# Connect GitHub repo, auto-deploy on push
+```
+
+### Self-Hosted (Caddy)
+
+```yaml
+# docker-compose.yml
+caddy:
+  image: caddy:alpine
+  volumes:
+    - ./dist:/srv:ro
+    - ./Caddyfile:/etc/caddy/Caddyfile
+  ports:
+    - "80:80"
+    - "443:443"
+```
+
+```Caddyfile
+# Caddyfile
+yourdomain.com {
+    root * /srv
+    file_server
+    try_files {path} {path}/ /index.html
+    encode gzip
+}
+```
+
+### Self-Hosted (Railway)
+
+```bash
+# Install Railway CLI
+npm install -g railway
+
+# Deploy
+railway init
+railway up
+```
+
+Railway auto-detects Astro and builds with `pnpm build`.
+
+---
+
+## 🛠️ Development
+
+### Commands
+
+```bash
+pnpm dev           # Start dev server (port 4321)
+pnpm build         # Build production site
+pnpm preview       # Preview production build
+```
+
+### Testing
+
+```bash
+# Run the test suite
+pnpm test
+
+# Check the content graph (broken links, duplicate names, ambiguous targets)
+node bin/commune.mjs check --json
+
+# Preview before deploying
+pnpm preview
+```
+
+### Debugging WikiLinks
+
+**Issue**: Links not working?
+
+```bash
+# Check cache consistency (should show same count each time)
+pnpm build 2>&1 | grep "Lookup built with"
+
+# Find broken links
+pnpm build 2>&1 | grep "Broken link"
+```
+
+---
+
+## 📦 Tech Stack
+
+- **Astro** - Static site generator
+- **Tailwind CSS** - Utility-first styling
+- **Pagefind** - Static search index
+- **remark-wikilinks** - WikiLink transformation plugin (custom, `src/remark-wikilinks.ts`)
+- **No framework dependencies** - Vanilla JS for interactivity
+
+---
+
+## 📖 Documentation
+
+**For Contributors**:
+- Architecture details in original README (check git history)
+- Pane system implementation in `src/pages/notes/[...slug].astro`
+- WikiLink plugin in `src/remark-wikilinks.ts`
+- Backlinks integration in `src/integration.ts`
+
+**For Users**:
+- This README covers installation and usage
+- See [devonmeadows.com](https://devonmeadows.com) for live example
+- Issues/questions: [GitHub Issues](https://github.com/dmthepm/commune-wiki/issues)
+
+---
+
+## 🤝 Contributing
+
+This is an open-source project under the MIT License. Contributions welcome!
+
+**How to contribute**:
+1. Fork the repository
+2. Create a feature branch (`git checkout -b feature/your-feature`)
+3. Make changes and test locally (`pnpm dev`)
+4. Build to verify (`pnpm build`)
+5. Commit with clear message
+6. Push and create Pull Request
+
+**Areas for contribution**:
+- [ ] Automated tests (Puppeteer or Playwright)
+- [ ] Additional themes/design systems
+- [ ] Search improvements (fuzzy matching, ranking)
+- [ ] Graph visualization of backlinks
+- [ ] Mobile responsiveness improvements
+- [ ] Performance optimizations
+
+---
+
+## 🐛 Known Issues
+
+### WikiLink Cache Bug (FIXED)
+
+**Symptom**: Links only work on last note built.
+
+**Fix**: Ensure cache size check in `src/remark-wikilinks.ts`:
+
+```typescript
+if (notesCache && notesCache.size > 0) {  // MUST check .size!
+  return buildFromCache();
+}
+```
+
+### Pane Styling Not Applied
+
+**Symptom**: Panes don't stack correctly.
+
+**Fix**: Use `<style is:global>` in `[...slug].astro` for dynamic panes.
+
+---
+
+## 📄 License
+
+MIT - See [LICENSE](LICENSE) file.
+
+**What this means**:
+- Free to use, modify, distribute, and sell
+- Commercial use allowed, with no obligation to open-source your changes
+- Keep the copyright notice; that's the whole obligation
+
+---
+
+## 🔗 Related Projects
+
+**Commune Ecosystem**:
+- **Devon's Homelab** - Personal infrastructure (private, showcase only)
+
+**Inspired by**:
+- [Andy Matuschak's Notes](https://notes.andymatuschak.org/)
+- [Maggie Appleton's Digital Garden](https://maggieappleton.com/garden)
+- [Obsidian](https://obsidian.md/) (proprietary alternative)
+- [Logseq](https://logseq.com/) (local-first alternative)
+
+---
+
+**Created by**: [Devon Meadows](https://devonmeadows.com)  
+**Repository**: [dmthepm/commune-wiki](https://github.com/dmthepm/commune-wiki)  
+**Support**: [GitHub Issues](https://github.com/dmthepm/commune-wiki/issues)

package/bin/commune.mjs

@@ -0,0 +1,29 @@
+#!/usr/bin/env node
+
+/**
+ * The `commune` entry point.
+ *
+ * One line on purpose, and this is the line #18 promised would change: it now
+ * imports the compiled CLI rather than the TypeScript source. Node refuses to
+ * strip types from any file under a `node_modules` path, so a `.ts` import here
+ * works from a checkout and dies the moment this package is installed.
+ *
+ * Two things have to be true for the import below to resolve on an install,
+ * and both are in `package.json`. `prepare` runs `tsc`, which pnpm executes
+ * inside its own clone of a git dependency, so `lib/` gets *built*. And the
+ * `files` allowlist names `lib`, so `lib/` gets *packed* — without that field
+ * the pack falls back to `.gitignore`, which ignores build output, and the
+ * installed package would arrive with a bin and nothing for it to run.
+ * `tests/install.test.mjs` and the CI stranger-install step exist to catch
+ * exactly that, because a checkout never notices it.
+ *
+ * The package compiles to `lib/`, not `dist/`: `dist/` is Astro's, and
+ * `astro build` empties its output directory before every run, so a site build
+ * would delete the CLI that is about to check it.
+ *
+ * If `lib/` is missing in a checkout, `pnpm build:lib` writes it.
+ */
+
+import { run } from '../lib/cli/main.js';
+
+process.exitCode = await run(process.argv.slice(2));

package/lib/cli/check.d.ts

@@ -0,0 +1,13 @@
+/**
+ * `commune check` — link integrity as a payload.
+ *
+ * Exits 0 whether or not it finds anything. The exit code answers "did the
+ * command finish", not "is your content clean" — those are different questions
+ * and an agent that cannot tell them apart has to parse stderr to find out
+ * whether the tool crashed. `commune gate` is the documented exception — it keeps
+ * its exit 1, because a gate's job *is* to fail.
+ *
+ * v1 is scoped to link integrity so it does not block on #17's collection
+ * collapse. Frontmatter drift is a follow-up.
+ */
+export declare function checkCommand(root: string, json: boolean): Promise<number>;

package/lib/cli/check.js

@@ -0,0 +1,58 @@
+/**
+ * `commune check` — link integrity as a payload.
+ *
+ * Exits 0 whether or not it finds anything. The exit code answers "did the
+ * command finish", not "is your content clean" — those are different questions
+ * and an agent that cannot tell them apart has to parse stderr to find out
+ * whether the tool crashed. `commune gate` is the documented exception — it keeps
+ * its exit 1, because a gate's job *is* to fail.
+ *
+ * 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 "./render.js";
+import { EXIT_OK } from "./errors.js";
+const RULES = [
+    'broken-link',
+    'ambiguous-target',
+    'duplicate-name',
+    'noncanonical-title',
+];
+/** A finding as it appears in the payload: no internal rendering fields. */
+function toFinding(diagnostic) {
+    return {
+        rule: diagnostic.rule,
+        severity: diagnostic.severity,
+        file: diagnostic.file,
+        ...(diagnostic.line !== undefined ? { line: diagnostic.line } : {}),
+        message: diagnostic.message,
+        ...(diagnostic.target !== undefined ? { target: diagnostic.target } : {}),
+        ...(diagnostic.candidates ? { candidates: diagnostic.candidates } : {}),
+        ...(diagnostic.canonical !== undefined ? { canonical: diagnostic.canonical } : {}),
+    };
+}
+export async function checkCommand(root, json) {
+    const entries = await loadContentEntries({ root });
+    const graph = buildGraph(entries);
+    const findings = checkEntries(entries, graph);
+    const byRule = Object.fromEntries(RULES.map((rule) => [rule, findings.filter((finding) => finding.rule === rule).length]));
+    const summary = {
+        entries: Object.keys(graph.nodes).length,
+        // Resolved edges. Every resolved outbound link is one inbound link on the
+        // far side, so this is the same number counted from either end.
+        edges: graph.totalBacklinks,
+        errors: findings.filter((finding) => finding.severity === 'error').length,
+        warnings: findings.filter((finding) => finding.severity === 'warning').length,
+        byRule,
+    };
+    if (json) {
+        writeJson({ schema: SCHEMA, root, summary, findings: findings.map(toFinding) });
+        return EXIT_OK;
+    }
+    writeLines([
+        ...findings.map((finding) => `${finding.severity}\t${finding.rule}\t${finding.file}\t${finding.message}`),
+        `${summary.entries} entries, ${summary.edges} edges, ${summary.errors} errors, ${summary.warnings} warnings`,
+    ]);
+    return EXIT_OK;
+}

package/lib/cli/errors.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Exit codes and the errors that produce them.
+ *
+ * The codes report *completion*, not findings: a `check` that reports 28 broken
+ * links has finished its job and exits 0. An agent that cannot tell "your
+ * content has problems" from "the tool fell over" has to parse stderr to find
+ * out, which is the failure mode this contract exists to prevent.
+ */
+/** The command ran to completion. Findings, if any, are in the payload. */
+export declare const EXIT_OK = 0;
+/** The command could not finish: bad root, unreadable file, unparseable frontmatter. */
+export declare const EXIT_FAILED = 1;
+/** The command was invoked wrongly: unknown flag, missing value, unknown subcommand. */
+export declare const EXIT_USAGE = 2;
+export type ErrorCode = 'EUSAGE' | 'ENOCONTENT' | 'EPARSE' | 'EINTERNAL';
+/** An error the CLI knows how to render on either side of the `--json` switch. */
+export declare class CliError extends Error {
+    readonly code: ErrorCode;
+    readonly exitCode: number;
+    /** Extra lines for text mode only — usage, for instance. Never in the JSON object. */
+    readonly detail?: string;
+    constructor(code: ErrorCode, message: string, exitCode: number, detail?: string);
+}
+export declare function usageError(message: string, detail?: string): CliError;
+export declare function failure(code: ErrorCode, message: string): CliError;
+/** `parseArgs` throws typed errors; every one of them means the invocation was wrong. */
+export declare function isParseArgsError(error: unknown): error is Error & {
+    code: string;
+};

package/lib/cli/errors.js

@@ -0,0 +1,41 @@
+/**
+ * Exit codes and the errors that produce them.
+ *
+ * The codes report *completion*, not findings: a `check` that reports 28 broken
+ * links has finished its job and exits 0. An agent that cannot tell "your
+ * content has problems" from "the tool fell over" has to parse stderr to find
+ * out, which is the failure mode this contract exists to prevent.
+ */
+/** The command ran to completion. Findings, if any, are in the payload. */
+export const EXIT_OK = 0;
+/** The command could not finish: bad root, unreadable file, unparseable frontmatter. */
+export const EXIT_FAILED = 1;
+/** The command was invoked wrongly: unknown flag, missing value, unknown subcommand. */
+export const EXIT_USAGE = 2;
+/** An error the CLI knows how to render on either side of the `--json` switch. */
+export class CliError extends Error {
+    code;
+    exitCode;
+    /** Extra lines for text mode only — usage, for instance. Never in the JSON object. */
+    detail;
+    constructor(code, message, exitCode, detail) {
+        super(message);
+        this.name = 'CliError';
+        this.code = code;
+        this.exitCode = exitCode;
+        this.detail = detail;
+    }
+}
+export function usageError(message, detail) {
+    return new CliError('EUSAGE', message, EXIT_USAGE, detail);
+}
+export function failure(code, message) {
+    return new CliError(code, message, EXIT_FAILED);
+}
+/** `parseArgs` throws typed errors; every one of them means the invocation was wrong. */
+export function isParseArgsError(error) {
+    if (!(error instanceof Error))
+        return false;
+    const code = error.code;
+    return typeof code === 'string' && code.startsWith('ERR_PARSE_ARGS_');
+}

package/lib/cli/gate.d.ts

@@ -0,0 +1,34 @@
+/**
+ * `commune gate` — the build check, as a verb.
+ *
+ * This is the one command in the CLI whose exit code answers a question about
+ * your *content* rather than about the command. Everywhere else the contract is
+ * "0 means I finished, findings or not", precisely so an agent can tell a dirty
+ * vault from a broken tool. A gate inverts that on purpose: its whole job is to
+ * stop a build, and a build stops on a non-zero exit. `usage.ts` says so out
+ * loud, because a reader who has internalised the rule needs to be told where
+ * the exception is.
+ *
+ * It was `scripts/test-search-index.mjs`, which imported the graph core by
+ * relative path. That works from a checkout and is unreachable from
+ * `node_modules`, so the one repo that most needs this check — a wiki built
+ * with the package — was the one repo that could not run it. The three
+ * assertions are unchanged; only the way you invoke them is.
+ *
+ * Three assertions:
+ *   1. every page in the `pages` collection is present in the search index
+ *   2. every WikiLink that resolves uses the target's exact title (no pipes,
+ *      no case drift) — the canonical-title rule
+ *   3. WikiLinks pointing at standalone pages actually render as hrefs
+ *
+ * The canonical-title rule itself lives in the graph core, where `commune
+ * check` reports it as a `noncanonical-title` finding. This verb is the *gate*:
+ * same rule, same findings, but a build that violates it stops. Two copies of
+ * one rule is the bug #3 was opened to kill, so there is only ever one.
+ */
+/** Which assertion failed, and what it saw. */
+export interface GateFailure {
+    assertion: 'pages-indexed' | 'canonical-titles' | 'page-links-rendered';
+    message: string;
+}
+export declare function gateCommand(root: string, dist: string, json: boolean): Promise<number>;