@magic-spells/constellation 0.1.0

package/README.md

@@ -0,0 +1,147 @@
+# Constellation
+
+Your project's architecture plan as markdown files in the repo: typed cards,
+connected into a graph, validated by lint, diffed by git, readable by humans on
+GitHub and by AI agents with nothing more than file access.
+
+```
+constellation/
+  plan.md                      ← the living project plan (PLAN-PROJECT)
+  api/API-TICKETS.md           ← one file per card; the filename IS the handle
+  datatype/DATATYPE-TICKET.md
+  db/DB-TICKETS.md
+  flow/FLOW-CREATE-TICKET.md
+  ...
+```
+
+Each card is frontmatter (structure) + markdown (narrative). Connections are a
+plain list of handles — plus `[[HANDLE]]` links in prose, handle-shaped values in
+frontmatter fields, and handles used as Mermaid node IDs. The indexer derives the
+graph; nothing derived is ever stored.
+
+**Why files?** Plans drift from code when they live somewhere else. Here a plan
+change is a commit: it rides the same branch and PR as the code it describes,
+merges per-card, and "what changed in the plan" is `git diff -- constellation/`.
+
+## Install
+
+```sh
+npm install -g @magic-spells/constellation   # the `constellation` binary
+# or run without installing:
+npx @magic-spells/constellation lint
+```
+
+Requires Node ≥ 22.
+
+## Usage
+
+```sh
+constellation init          # scaffold constellation/ with a starter plan.md
+constellation lint          # validate handles, references, folders, schemas
+constellation mcp           # run the MCP server (stdio) for AI agents
+constellation serve         # open the local viewer (editable; --readonly to disable)
+```
+
+Lint errors (broken graph: bad handles, dangling structured references,
+duplicates) exit non-zero for CI; warnings (wrong folder, schema violations,
+unknown fields, dangling prose links) don't block.
+
+## Repo layout
+
+| Path | What |
+|---|---|
+| `docs/001-file-format.md` | The normative format spec |
+| `docs/002-mcp.md` | MCP design: tool surface, hydration, write semantics, git layer |
+| `schemas/` | JSON Schemas: `card.json` (reserved keys) + one per type |
+| `skill/` | AI authoring skill: `SKILL.md` + per-type references with golden examples |
+| `src/core/` | Parser, reference extraction, indexer, schema validation, lint |
+| `src/cli/` | The `constellation` binary (`lint`, `init`, `mcp`) |
+| `src/mcp/` | MCP server: hydrated retrieval, validated writes, git tools |
+| `examples/constellation/` | Golden sample plan — one card of every type, lints clean, doubles as the test fixture |
+
+## Development
+
+```sh
+npm install
+npm test                 # vitest
+npm run lint:examples    # lint the golden plan
+npm run build            # tsc → dist/
+```
+
+## MCP
+
+`constellation mcp` exposes the plan to AI agents over stdio:
+
+- **Hydrated retrieval**: `get_card`, `search`, and `traverse` can return
+  connected cards with their complete frontmatter and body in one call.
+- **Validated writes**: `create_card`, `update_card`, `delete_card`,
+  `add_connection`, `remove_connection` — every write lints and returns issues.
+  Body-only updates never reformat frontmatter.
+- **Git-powered change tracking**: `diff_plan` (per-card changes since the sync
+  marker), `plan_log`, `set_sync_point`, `check_integrity`.
+- **Visual viewer**: `start_viewer` / `stop_viewer` open and close the local web
+  viewer from inside an agent session, returning a clickable URL.
+
+### Add to Claude Code
+
+Run from your repo root, so the server starts there and finds the plan:
+
+```sh
+# Run straight from npm — no install needed:
+claude mcp add constellation -- npx -y @magic-spells/constellation mcp
+
+# Or, if installed globally (npm i -g @magic-spells/constellation):
+claude mcp add constellation -- constellation mcp
+
+# Share with everyone who clones the repo (writes .mcp.json):
+claude mcp add --scope project constellation -- npx -y @magic-spells/constellation mcp
+```
+
+Manage it with `claude mcp list`, `claude mcp get constellation`, and
+`claude mcp remove constellation`.
+
+### Other MCP clients
+
+Hand-edit the client's config (Claude Desktop, a project `.mcp.json`, etc.):
+
+```json
+{
+  "mcpServers": {
+    "constellation": {
+      "command": "constellation",
+      "args": ["mcp"],
+      "cwd": "/path/to/your/repo"
+    }
+  }
+}
+```
+
+Set `cwd` to your repo root (or any folder inside it). The server finds the plan by
+walking up from its working directory; without `cwd` it inherits the client's, which
+may not be your project — in which case tools return `NO_PLAN_FOUND`.
+
+## Viewer
+
+`constellation serve` renders the plan as a local website, **editable in place**
+(pass `--readonly` to disable writes). Five themes toggle in the header:
+**observatory** (dark, star-field), **claw** (cream paper, serif, coral accents),
+**black**, **synthwave**, and **sumi**. Card pages show structured fields, the
+markdown body, connection chips in both directions, and a small constellation
+diagram of the card's neighborhood — its nodes tinted by card type. Mermaid blocks
+render in-browser, `[[HANDLE]]` links navigate, and the page live-reloads when plan
+files change on disk.
+
+```sh
+constellation serve     # http://localhost:4747 (assets ship prebuilt with the package)
+npm run build:viewer    # only when developing from source
+```
+
+In an agent session you don't need the CLI — ask Claude to open the viewer and it
+calls the `start_viewer` MCP tool, which returns the URL (`stop_viewer` closes it).
+
+---
+
+<p align="center">
+  Made by <a href="https://github.com/coryschulz">Cory Schulz</a>
+</p>
+

package/dist/cli/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli/index.js

@@ -0,0 +1,127 @@
+#!/usr/bin/env node
+import path from 'node:path';
+import process from 'node:process';
+import { Command } from 'commander';
+import pc from 'picocolors';
+import { lintPlan } from '../core/lint.js';
+import { resolvePlanDir } from '../core/resolve.js';
+const program = new Command();
+program
+    .name('constellation')
+    .description('Files-first architecture planning for AI-assisted development');
+program
+    .command('lint')
+    .argument('[path]', 'plan folder, or a directory containing constellation/ (default: walk up from cwd)')
+    .description('Validate the plan: handles, references, folders, schemas')
+    .action(async (target) => {
+    const root = await resolvePlanDir(target ?? undefined);
+    if (!root) {
+        console.error(pc.red('No constellation/ folder found.') +
+            ' Run `constellation init` to create one.');
+        process.exit(2);
+    }
+    const result = await lintPlan(root);
+    const byFile = new Map();
+    for (const issue of result.issues) {
+        if (!byFile.has(issue.file))
+            byFile.set(issue.file, []);
+        byFile.get(issue.file).push(issue);
+    }
+    for (const [file, issues] of byFile) {
+        console.log(pc.underline(file));
+        for (const issue of issues) {
+            const tag = issue.severity === 'error'
+                ? pc.red(`error ${issue.code}`)
+                : pc.yellow(`warn  ${issue.code}`);
+            console.log(`  ${tag}  ${issue.message}`);
+        }
+    }
+    if (byFile.size > 0)
+        console.log();
+    const summary = [
+        `${result.index.cards.size} cards`,
+        `${result.index.connections.length} connections`,
+        result.errors.length > 0
+            ? pc.red(`${result.errors.length} errors`)
+            : pc.green('0 errors'),
+        result.warnings.length > 0
+            ? pc.yellow(`${result.warnings.length} warnings`)
+            : '0 warnings',
+    ].join(', ');
+    console.log(`${result.errors.length > 0 ? pc.red('✗') : pc.green('✓')} ${summary}`);
+    process.exit(result.errors.length > 0 ? 1 : 0);
+});
+program
+    .command('init')
+    .argument('[path]', 'directory to create the plan in (default: cwd)', '.')
+    .description('Scaffold a constellation/ folder with a starter plan.md')
+    .action(async (target) => {
+    const { initPlan } = await import('../core/scaffold.js');
+    try {
+        const root = await initPlan(target);
+        console.log(pc.green('✓') + ` Created ${path.relative(process.cwd(), root)}/plan.md`);
+        console.log('\nAdd cards as <type>/<HANDLE>.md (e.g. api/API-LIST-USERS.md),\nthen run `constellation lint` to validate.');
+    }
+    catch (err) {
+        console.error(pc.red(err instanceof Error ? err.message : String(err)));
+        process.exit(2);
+    }
+});
+program
+    .command('mcp')
+    .description('Run the Constellation MCP server over stdio')
+    .action(async () => {
+    const { startMcpServer } = await import('../mcp/server.js');
+    await startMcpServer();
+});
+program
+    .command('serve')
+    .argument('[path]', 'plan folder or a directory containing constellation/')
+    .option('-p, --port <port>', 'port to listen on', '4747')
+    .option('--no-open', 'do not open the browser')
+    .option('--readonly', 'disable editing from the browser')
+    .description('Serve a website rendering the plan, editable in place')
+    .action(async (target, opts) => {
+    const root = await resolvePlanDir(target ?? undefined);
+    if (!root) {
+        console.error(pc.red('No constellation/ folder found.'));
+        process.exit(2);
+    }
+    const { startServer } = await import('../serve/server.js');
+    let running;
+    try {
+        running = await startServer({
+            planRoot: root,
+            port: Number(opts.port),
+            readonly: opts.readonly ?? false,
+        });
+    }
+    catch (err) {
+        const code = err?.code;
+        if (code === 'EADDRINUSE') {
+            console.error(pc.red(`Port ${opts.port} is already in use.`) +
+                ` Pick another with: constellation serve -p <port>`);
+        }
+        else {
+            console.error(pc.red(err instanceof Error ? err.message : String(err)));
+        }
+        process.exit(2);
+    }
+    const url = `http://localhost:${running.port}`;
+    console.log(`${pc.green('✓')} Constellation viewer at ${pc.underline(url)}`);
+    console.log(pc.dim(`  plan: ${root}`));
+    if (opts.open) {
+        const { spawn } = await import('node:child_process');
+        const cmd = process.platform === 'darwin'
+            ? 'open'
+            : process.platform === 'win32'
+                ? 'start'
+                : 'xdg-open';
+        spawn(cmd, [url], { stdio: 'ignore', detached: true }).unref();
+    }
+});
+program.parseAsync(process.argv).catch((err) => {
+    console.error(pc.red(err instanceof Error ? err.message : String(err)));
+    process.exit(1);
+});
+//# sourceMappingURL=index.js.map

package/dist/cli/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/cli/index.ts"],"names":[],"mappings":"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"}

package/dist/core/extract.d.ts

@@ -0,0 +1,9 @@
+/** [[HANDLE]] wiki-links. Non-handle-shaped link targets are ignored. */
+export declare function extractWikiLinks(body: string): string[];
+/** Handle-shaped identifiers inside ```mermaid fences. */
+export declare function extractMermaidRefs(body: string): string[];
+/**
+ * Handle-shaped string values anywhere in frontmatter, excluding the
+ * `connections` key (collected separately) and the card's own handle.
+ */
+export declare function extractFrontmatterRefs(frontmatter: Record<string, unknown>, ownHandle: string): string[];

package/dist/core/extract.js

@@ -0,0 +1,56 @@
+import { isKnownHandle } from './handles.js';
+const WIKI_LINK = /\[\[([^\[\]]+)\]\]/g;
+const MERMAID_BLOCK = /```mermaid[^\n]*\n([\s\S]*?)```/g;
+const HANDLE_TOKEN = /(?<![A-Za-z0-9-])[A-Z][A-Z0-9]*-[A-Z0-9][A-Z0-9-]*(?![A-Za-z0-9-])/g;
+/** [[HANDLE]] wiki-links. Non-handle-shaped link targets are ignored. */
+export function extractWikiLinks(body) {
+    const out = [];
+    for (const match of body.matchAll(WIKI_LINK)) {
+        const target = match[1].trim();
+        if (isKnownHandle(target))
+            out.push(target);
+    }
+    return dedupe(out);
+}
+/** Handle-shaped identifiers inside ```mermaid fences. */
+export function extractMermaidRefs(body) {
+    const out = [];
+    for (const block of body.matchAll(MERMAID_BLOCK)) {
+        for (const token of block[1].matchAll(HANDLE_TOKEN)) {
+            if (isKnownHandle(token[0]))
+                out.push(token[0]);
+        }
+    }
+    return dedupe(out);
+}
+/**
+ * Handle-shaped string values anywhere in frontmatter, excluding the
+ * `connections` key (collected separately) and the card's own handle.
+ */
+export function extractFrontmatterRefs(frontmatter, ownHandle) {
+    const out = [];
+    for (const [key, value] of Object.entries(frontmatter)) {
+        if (key === 'connections')
+            continue;
+        walk(value, out);
+    }
+    return dedupe(out.filter((h) => h !== ownHandle));
+}
+function walk(value, out) {
+    if (typeof value === 'string') {
+        if (isKnownHandle(value))
+            out.push(value);
+    }
+    else if (Array.isArray(value)) {
+        for (const item of value)
+            walk(item, out);
+    }
+    else if (value && typeof value === 'object') {
+        for (const item of Object.values(value))
+            walk(item, out);
+    }
+}
+function dedupe(items) {
+    return [...new Set(items)];
+}
+//# sourceMappingURL=extract.js.map

package/dist/core/extract.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"extract.js","sourceRoot":"","sources":["../../src/core/extract.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAE7C,MAAM,SAAS,GAAG,qBAAqB,CAAC;AACxC,MAAM,aAAa,GAAG,kCAAkC,CAAC;AACzD,MAAM,YAAY,GAAG,qEAAqE,CAAC;AAE3F,yEAAyE;AACzE,MAAM,UAAU,gBAAgB,CAAC,IAAY;IAC3C,MAAM,GAAG,GAAa,EAAE,CAAC;IACzB,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC;QAC7C,MAAM,MAAM,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;QAC/B,IAAI,aAAa,CAAC,MAAM,CAAC;YAAE,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IAC9C,CAAC;IACD,OAAO,MAAM,CAAC,GAAG,CAAC,CAAC;AACrB,CAAC;AAED,0DAA0D;AAC1D,MAAM,UAAU,kBAAkB,CAAC,IAAY;IAC7C,MAAM,GAAG,GAAa,EAAE,CAAC;IACzB,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,QAAQ,CAAC,aAAa,CAAC,EAAE,CAAC;QACjD,KAAK,MAAM,KAAK,IAAI,KAAK,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,YAAY,CAAC,EAAE,CAAC;YACpD,IAAI,aAAa,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;gBAAE,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;QAClD,CAAC;IACH,CAAC;IACD,OAAO,MAAM,CAAC,GAAG,CAAC,CAAC;AACrB,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,sBAAsB,CACpC,WAAoC,EACpC,SAAiB;IAEjB,MAAM,GAAG,GAAa,EAAE,CAAC;IACzB,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,WAAW,CAAC,EAAE,CAAC;QACvD,IAAI,GAAG,KAAK,aAAa;YAAE,SAAS;QACpC,IAAI,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;IACnB,CAAC;IACD,OAAO,MAAM,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,KAAK,SAAS,CAAC,CAAC,CAAC;AACpD,CAAC;AAED,SAAS,IAAI,CAAC,KAAc,EAAE,GAAa;IACzC,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC9B,IAAI,aAAa,CAAC,KAAK,CAAC;YAAE,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAC5C,CAAC;SAAM,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QAChC,KAAK,MAAM,IAAI,IAAI,KAAK;YAAE,IAAI,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;IAC5C,CAAC;SAAM,IAAI,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC9C,KAAK,MAAM,IAAI,IAAI,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC;YAAE,IAAI,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;IAC3D,CAAC;AACH,CAAC;AAED,SAAS,MAAM,CAAC,KAAe;IAC7B,OAAO,CAAC,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC;AAC7B,CAAC"}

package/dist/core/handles.d.ts

@@ -0,0 +1,13 @@
+import { type TypeName } from './types.js';
+/** Handle grammar: PREFIX-NAME, uppercase letters/digits/dashes. */
+export declare const HANDLE_PATTERN: RegExp;
+export declare const HANDLE_MIN_LENGTH = 3;
+export declare const HANDLE_MAX_LENGTH = 135;
+/** Folder each type's cards live in, relative to the plan root. */
+export declare const TYPE_FOLDERS: Record<TypeName, string>;
+/** True when the string matches the handle grammar (prefix may be unknown). */
+export declare function isHandleShaped(value: string): boolean;
+/** Type for a handle's prefix, or null when the prefix is not one of the 17. */
+export declare function typeForHandle(handle: string): TypeName | null;
+/** Shaped AND carries a known prefix — the test used for reference extraction. */
+export declare function isKnownHandle(value: string): boolean;

package/dist/core/handles.js

@@ -0,0 +1,45 @@
+import { TYPE_NAMES } from './types.js';
+/** Handle grammar: PREFIX-NAME, uppercase letters/digits/dashes. */
+export const HANDLE_PATTERN = /^[A-Z][A-Z0-9]*-[A-Z0-9][A-Z0-9-]*$/;
+export const HANDLE_MIN_LENGTH = 3;
+export const HANDLE_MAX_LENGTH = 135;
+/** Folder each type's cards live in, relative to the plan root. */
+export const TYPE_FOLDERS = {
+    API: 'api',
+    DB: 'db',
+    DATATYPE: 'datatype',
+    ROLE: 'role',
+    DOC: 'doc',
+    FILE: 'file',
+    TEST: 'test',
+    EXTERNAL: 'external',
+    EVENT: 'event',
+    COMPONENT: 'component',
+    PAGE: 'page',
+    JOB: 'job',
+    FLOW: 'flow',
+    STATE: 'state',
+    DIAGRAM: 'diagram',
+    AGENT: 'agent',
+    PLAN: 'plan',
+};
+const TYPE_SET = new Set(TYPE_NAMES);
+/** True when the string matches the handle grammar (prefix may be unknown). */
+export function isHandleShaped(value) {
+    return (value.length >= HANDLE_MIN_LENGTH &&
+        value.length <= HANDLE_MAX_LENGTH &&
+        HANDLE_PATTERN.test(value));
+}
+/** Type for a handle's prefix, or null when the prefix is not one of the 17. */
+export function typeForHandle(handle) {
+    const dash = handle.indexOf('-');
+    if (dash <= 0)
+        return null;
+    const prefix = handle.slice(0, dash);
+    return TYPE_SET.has(prefix) ? prefix : null;
+}
+/** Shaped AND carries a known prefix — the test used for reference extraction. */
+export function isKnownHandle(value) {
+    return isHandleShaped(value) && typeForHandle(value) !== null;
+}
+//# sourceMappingURL=handles.js.map

package/dist/core/handles.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"handles.js","sourceRoot":"","sources":["../../src/core/handles.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAiB,MAAM,YAAY,CAAC;AAEvD,oEAAoE;AACpE,MAAM,CAAC,MAAM,cAAc,GAAG,qCAAqC,CAAC;AAEpE,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,CAAC;AACnC,MAAM,CAAC,MAAM,iBAAiB,GAAG,GAAG,CAAC;AAErC,mEAAmE;AACnE,MAAM,CAAC,MAAM,YAAY,GAA6B;IACpD,GAAG,EAAE,KAAK;IACV,EAAE,EAAE,IAAI;IACR,QAAQ,EAAE,UAAU;IACpB,IAAI,EAAE,MAAM;IACZ,GAAG,EAAE,KAAK;IACV,IAAI,EAAE,MAAM;IACZ,IAAI,EAAE,MAAM;IACZ,QAAQ,EAAE,UAAU;IACpB,KAAK,EAAE,OAAO;IACd,SAAS,EAAE,WAAW;IACtB,IAAI,EAAE,MAAM;IACZ,GAAG,EAAE,KAAK;IACV,IAAI,EAAE,MAAM;IACZ,KAAK,EAAE,OAAO;IACd,OAAO,EAAE,SAAS;IAClB,KAAK,EAAE,OAAO;IACd,IAAI,EAAE,MAAM;CACb,CAAC;AAEF,MAAM,QAAQ,GAAG,IAAI,GAAG,CAAS,UAAU,CAAC,CAAC;AAE7C,+EAA+E;AAC/E,MAAM,UAAU,cAAc,CAAC,KAAa;IAC1C,OAAO,CACL,KAAK,CAAC,MAAM,IAAI,iBAAiB;QACjC,KAAK,CAAC,MAAM,IAAI,iBAAiB;QACjC,cAAc,CAAC,IAAI,CAAC,KAAK,CAAC,CAC3B,CAAC;AACJ,CAAC;AAED,gFAAgF;AAChF,MAAM,UAAU,aAAa,CAAC,MAAc;IAC1C,MAAM,IAAI,GAAG,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IACjC,IAAI,IAAI,IAAI,CAAC;QAAE,OAAO,IAAI,CAAC;IAC3B,MAAM,MAAM,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC;IACrC,OAAO,QAAQ,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,CAAE,MAAmB,CAAC,CAAC,CAAC,IAAI,CAAC;AAC5D,CAAC;AAED,kFAAkF;AAClF,MAAM,UAAU,aAAa,CAAC,KAAa;IACzC,OAAO,cAAc,CAAC,KAAK,CAAC,IAAI,aAAa,CAAC,KAAK,CAAC,KAAK,IAAI,CAAC;AAChE,CAAC"}

package/dist/core/index.d.ts

@@ -0,0 +1,8 @@
+export * from './types.js';
+export * from './handles.js';
+export * from './parse.js';
+export * from './extract.js';
+export * from './indexer.js';
+export * from './validate.js';
+export * from './lint.js';
+export * from './writer.js';

package/dist/core/index.js

@@ -0,0 +1,9 @@
+export * from './types.js';
+export * from './handles.js';
+export * from './parse.js';
+export * from './extract.js';
+export * from './indexer.js';
+export * from './validate.js';
+export * from './lint.js';
+export * from './writer.js';
+//# sourceMappingURL=index.js.map

package/dist/core/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/core/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,cAAc,CAAC;AAC7B,cAAc,YAAY,CAAC;AAC3B,cAAc,cAAc,CAAC;AAC7B,cAAc,cAAc,CAAC;AAC7B,cAAc,eAAe,CAAC;AAC9B,cAAc,WAAW,CAAC;AAC1B,cAAc,aAAa,CAAC"}

package/dist/core/indexer.d.ts

@@ -0,0 +1,3 @@
+import type { PlanIndex } from './types.js';
+/** Load a plan folder into an index: cards, edges, and structural issues. */
+export declare function loadPlan(root: string): Promise<PlanIndex>;

package/dist/core/indexer.js

@@ -0,0 +1,209 @@
+import { readdir, readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { isHandleShaped, isKnownHandle, typeForHandle, TYPE_FOLDERS, } from './handles.js';
+import { parseFile } from './parse.js';
+import { extractFrontmatterRefs, extractMermaidRefs, extractWikiLinks, } from './extract.js';
+/** Load a plan folder into an index: cards, edges, and structural issues. */
+export async function loadPlan(root) {
+    const absRoot = path.resolve(root);
+    const issues = [];
+    const cards = new Map();
+    for (const relPath of await listMarkdownFiles(absRoot)) {
+        const filePath = path.join(absRoot, relPath);
+        const raw = await readFile(filePath, 'utf8');
+        const card = readCard(relPath, filePath, raw, issues);
+        if (!card)
+            continue;
+        const existing = cards.get(card.handle);
+        if (existing) {
+            issues.push({
+                severity: 'error',
+                code: 'E003',
+                message: `Duplicate handle ${card.handle} (also defined in ${existing.relPath})`,
+                file: relPath,
+            });
+            continue;
+        }
+        cards.set(card.handle, card);
+    }
+    resolveRefs(cards, issues);
+    const connections = buildConnections(cards);
+    const connectedHandles = new Map();
+    for (const conn of connections) {
+        if (!connectedHandles.has(conn.a))
+            connectedHandles.set(conn.a, new Set());
+        if (!connectedHandles.has(conn.b))
+            connectedHandles.set(conn.b, new Set());
+        connectedHandles.get(conn.a).add(conn.b);
+        connectedHandles.get(conn.b).add(conn.a);
+    }
+    return { root: absRoot, cards, connections, connectedHandles, issues };
+}
+function readCard(relPath, filePath, raw, issues) {
+    // The one special file: plan.md at the plan root is PLAN-PROJECT.
+    const isRootPlan = relPath === 'plan.md';
+    const handle = isRootPlan ? 'PLAN-PROJECT' : path.basename(relPath, '.md');
+    if (!isHandleShaped(handle)) {
+        issues.push({
+            severity: 'error',
+            code: 'E001',
+            message: `Filename is not a valid handle: ${handle}`,
+            file: relPath,
+        });
+        return null;
+    }
+    const type = typeForHandle(handle);
+    if (!type) {
+        issues.push({
+            severity: 'error',
+            code: 'E002',
+            message: `Unknown handle prefix: ${handle.split('-')[0]}- (expected one of the 17 canonical prefixes)`,
+            file: relPath,
+        });
+        return null;
+    }
+    const parsed = parseFile(raw);
+    if (parsed.yamlError) {
+        issues.push({
+            severity: 'error',
+            code: 'E006',
+            message: `Invalid YAML frontmatter: ${parsed.yamlError}`,
+            file: relPath,
+        });
+    }
+    if (!isRootPlan) {
+        const folder = relPath.includes(path.sep) ? relPath.split(path.sep)[0] : '';
+        const expected = TYPE_FOLDERS[type];
+        if (folder !== expected) {
+            issues.push({
+                severity: 'warning',
+                code: 'W001',
+                message: `${handle} is a ${type} card and belongs in ${expected}/`,
+                file: relPath,
+            });
+        }
+    }
+    const fm = parsed.frontmatter;
+    const connections = [];
+    if (fm.connections !== undefined) {
+        const list = Array.isArray(fm.connections) ? fm.connections : null;
+        if (list === null) {
+            issues.push({
+                severity: 'error',
+                code: 'E004',
+                message: `connections must be a list of handles`,
+                file: relPath,
+            });
+        }
+        else {
+            for (const entry of list) {
+                if (typeof entry === 'string' && isKnownHandle(entry)) {
+                    if (entry !== handle)
+                        connections.push(entry);
+                }
+                else {
+                    issues.push({
+                        severity: 'error',
+                        code: 'E004',
+                        message: `connections entry is not a valid handle: ${JSON.stringify(entry)}`,
+                        file: relPath,
+                    });
+                }
+            }
+        }
+    }
+    return {
+        handle,
+        type,
+        relPath,
+        filePath,
+        frontmatter: fm,
+        body: parsed.body,
+        name: typeof fm.name === 'string' ? fm.name : undefined,
+        kind: typeof fm.kind === 'string' ? fm.kind : undefined,
+        status: typeof fm.status === 'string' ? fm.status : undefined,
+        refs: {
+            connections: [...new Set(connections)],
+            frontmatter: extractFrontmatterRefs(fm, handle),
+            body: extractWikiLinks(parsed.body),
+            mermaid: extractMermaidRefs(parsed.body),
+        },
+    };
+}
+function resolveRefs(cards, issues) {
+    for (const card of cards.values()) {
+        // Structured references are contracts: missing targets are errors.
+        for (const target of [...card.refs.connections, ...card.refs.frontmatter]) {
+            if (!cards.has(target)) {
+                issues.push({
+                    severity: 'error',
+                    code: 'E005',
+                    message: `Reference to ${target} does not resolve to a card`,
+                    file: card.relPath,
+                });
+            }
+        }
+        // Prose references may point at cards not yet written: warnings.
+        for (const target of [...card.refs.body, ...card.refs.mermaid]) {
+            if (target !== card.handle && !cards.has(target)) {
+                issues.push({
+                    severity: 'warning',
+                    code: 'W004',
+                    message: `Body reference [[${target}]] does not resolve to a card`,
+                    file: card.relPath,
+                });
+            }
+        }
+    }
+}
+function buildConnections(cards) {
+    const seen = new Set();
+    const connections = [];
+    for (const card of cards.values()) {
+        const targets = [
+            ...card.refs.connections,
+            ...card.refs.frontmatter,
+            ...card.refs.body,
+            ...card.refs.mermaid,
+        ];
+        for (const target of targets) {
+            if (target === card.handle || !cards.has(target))
+                continue;
+            const [a, b] = card.handle < target ? [card.handle, target] : [target, card.handle];
+            const key = `${a}\u0000${b}`;
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            connections.push({ a, b });
+        }
+    }
+    return connections;
+}
+async function listMarkdownFiles(root) {
+    const out = [];
+    await walk(root, '');
+    return out.sort();
+    async function walk(dir, rel) {
+        let entries;
+        try {
+            entries = await readdir(dir, { withFileTypes: true });
+        }
+        catch (err) {
+            if (rel === '')
+                throw err;
+            return;
+        }
+        for (const entry of entries) {
+            if (entry.name.startsWith('.'))
+                continue;
+            const relPath = rel ? path.join(rel, entry.name) : entry.name;
+            if (entry.isDirectory()) {
+                await walk(path.join(dir, entry.name), relPath);
+            }
+            else if (entry.isFile() && entry.name.endsWith('.md')) {
+                out.push(relPath);
+            }
+        }
+    }
+}
+//# sourceMappingURL=indexer.js.map