@magic-spells/constellation 0.1.0 → 0.2.0

package/README.md

@@ -40,6 +40,7 @@ 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)
+constellation repos         # list sibling repos declared in connected_repos
 ```
 
 Lint errors (broken graph: bad handles, dangling structured references,
@@ -55,7 +56,7 @@ unknown fields, dangling prose links) don't block.
 | `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/cli/` | The `constellation` binary (`init`, `lint`, `mcp`, `serve`, `repos`) |
 | `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 |
 
@@ -79,6 +80,10 @@ npm run build            # tsc → dist/
   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`.
+- **Connected repos (multi-repo)**: a plan can declare sibling repos
+  (`add_connected_repo` / `list_connected_repos` / `remove_connected_repo`); every
+  tool takes an optional `repo` selector to read or write a sibling's plan. Omit it
+  and single-repo behavior is unchanged.
 - **Visual viewer**: `start_viewer` / `stop_viewer` open and close the local web
   viewer from inside an agent session, returning a clickable URL.
 
@@ -100,6 +105,38 @@ claude mcp add --scope project constellation -- npx -y @magic-spells/constellati
 Manage it with `claude mcp list`, `claude mcp get constellation`, and
 `claude mcp remove constellation`.
 
+To build a plan from an existing codebase (or audit one), ask the agent to bootstrap or
+audit — the server ships **`bootstrap_plan`** and **`audit_plan`** prompts (slash commands
+in Claude Code) that walk the code macro→micro: follow the data, follow the user/auth, then
+step back and pressure-test the plan for blind spots (missing unhappy paths, auth gaps,
+forgotten cross-cutting concerns) and recommend. The full method is in
+[`skill/methodology.md`](skill/methodology.md).
+
+### Add to Codex
+
+Codex CLI keeps MCP servers in `~/.codex/config.toml` (TOML, not JSON). Add it with the CLI:
+
+```sh
+# Run straight from npm — no install needed:
+codex mcp add constellation -- npx -y @magic-spells/constellation mcp
+
+# Or, if installed globally (npm i -g @magic-spells/constellation):
+codex mcp add constellation -- constellation mcp
+```
+
+…or hand-edit the config (a project-scoped `.codex/config.toml` also works in trusted repos):
+
+```toml
+[mcp_servers.constellation]
+command = "npx"
+args = ["-y", "@magic-spells/constellation", "mcp"]
+cwd = "/path/to/your/repo"   # so the server walks up to your plan
+```
+
+Launch `codex` from your repo root (or set `cwd` above) so the server starts there and finds
+the plan — otherwise tools return `NO_PLAN_FOUND`. Run `/mcp` inside a Codex session to confirm
+it's connected; manage it with `codex mcp list` and `codex mcp remove constellation`.
+
 ### Other MCP clients
 
 Hand-edit the client's config (Claude Desktop, a project `.mcp.json`, etc.):
@@ -123,9 +160,10 @@ 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:
+(pass `--readonly` to disable writes). Nine 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
+**black**, **synthwave**, **sumi**, **daylight**, **frost**, **ember**, and **corona**.
+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
@@ -144,4 +182,3 @@ calls the `start_viewer` MCP tool, which returns the URL (`stop_viewer` closes i
 <p align="center">
   Made by <a href="https://github.com/coryschulz">Cory Schulz</a>
 </p>
-

package/dist/cli/index.js

@@ -1,14 +1,42 @@
 #!/usr/bin/env node
+import { createRequire } from 'node:module';
 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 { listConnectedRepos } from '../core/repos.js';
 import { resolvePlanDir } from '../core/resolve.js';
+import { notifyUpdate } from './update-check.js';
+const require = createRequire(import.meta.url);
+const { name, version } = require('../../package.json');
 const program = new Command();
+async function openUrl(url) {
+    try {
+        const { spawn } = await import('node:child_process');
+        const child = process.platform === 'darwin'
+            ? spawn('open', [url], { stdio: 'ignore', detached: true })
+            : process.platform === 'win32'
+                ? spawn('cmd', ['/c', 'start', '', url], {
+                    stdio: 'ignore',
+                    detached: true,
+                    windowsHide: true,
+                })
+                : spawn('xdg-open', [url], { stdio: 'ignore', detached: true });
+        child.on('error', () => { });
+        child.unref();
+    }
+    catch {
+        // Opening the browser is best-effort; the server URL is still printed.
+    }
+}
 program
     .name('constellation')
-    .description('Files-first architecture planning for AI-assisted development');
+    .description('Files-first architecture planning for AI-assisted development')
+    .version(version);
+// Update notice on every human command, but never for `mcp` (its stdout is JSON-RPC).
+if (process.argv[2] !== 'mcp')
+    notifyUpdate(name, version);
 program
     .command('lint')
     .argument('[path]', 'plan folder, or a directory containing constellation/ (default: walk up from cwd)')
@@ -54,12 +82,14 @@ program
 program
     .command('init')
     .argument('[path]', 'directory to create the plan in (default: cwd)', '.')
+    .option('-n, --name <name>', 'project name shown as the viewer title (default: a title-cased folder name)')
     .description('Scaffold a constellation/ folder with a starter plan.md')
-    .action(async (target) => {
+    .action(async (target, opts) => {
     const { initPlan } = await import('../core/scaffold.js');
     try {
-        const root = await initPlan(target);
+        const { root, name: projectName } = await initPlan(target, { name: opts.name });
         console.log(pc.green('✓') + ` Created ${path.relative(process.cwd(), root)}/plan.md`);
+        console.log(`  Project name: ${pc.bold(projectName)} ${pc.dim('— edit the name: field in plan.md to change it')}`);
         console.log('\nAdd cards as <type>/<HANDLE>.md (e.g. api/API-LIST-USERS.md),\nthen run `constellation lint` to validate.');
     }
     catch (err) {
@@ -111,14 +141,36 @@ program
     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();
+        await openUrl(url);
+    }
+});
+program
+    .command('repos')
+    .argument('[path]', 'plan folder, or a directory containing constellation/ (default: walk up from cwd)')
+    .description('List the sibling repos declared in connected_repos')
+    .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 repos = await listConnectedRepos(root);
+    if (repos.length === 0) {
+        console.log(pc.dim('No connected repos declared in plan.md (connected_repos).'));
+        return;
+    }
+    for (const r of repos) {
+        const status = r.reachable
+            ? pc.green('✓ reachable')
+            : pc.yellow('• not found here');
+        console.log(`${pc.bold(r.name)}  ${pc.dim(r.path)}  ${status}`);
+        if (r.description)
+            console.log(`  ${r.description}`);
     }
+    console.log();
+    console.log(pc.dim(`${repos.length} connected repo${repos.length === 1 ? '' : 's'}. ` +
+        'Paths are relative to this repo; "not found here" just means a different local layout.'));
 });
 program.parseAsync(process.argv).catch((err) => {
     console.error(pc.red(err instanceof Error ? err.message : String(err)));

package/dist/cli/index.js.map

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

package/dist/cli/update-check.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Print an "update available" notice on stderr (from cache — never hits the
+ * network on this path, so it never blocks), then kick off a detached
+ * background refresh if the cache is stale. Do NOT call this for `mcp`.
+ */
+export declare function notifyUpdate(name: string, current: string): void;

package/dist/cli/update-check.js

@@ -0,0 +1,70 @@
+import { spawn } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import process from 'node:process';
+import pc from 'picocolors';
+const CACHE_FILE = join(process.env.XDG_CACHE_HOME || join(homedir(), '.cache'), 'constellation', 'update.json');
+const ONE_DAY = 24 * 60 * 60 * 1000;
+/**
+ * Print an "update available" notice on stderr (from cache — never hits the
+ * network on this path, so it never blocks), then kick off a detached
+ * background refresh if the cache is stale. Do NOT call this for `mcp`.
+ */
+export function notifyUpdate(name, current) {
+    if (!process.stderr.isTTY)
+        return; // not a terminal (pipe / redirect)
+    if (process.env.CI || process.env.NO_UPDATE_NOTIFIER)
+        return;
+    const cache = readCache();
+    if (cache?.latest && isNewer(cache.latest, current)) {
+        process.stderr.write(`\n  ${pc.yellow('▲ Update available')} ${pc.dim(`${current} →`)} ${pc.green(cache.latest)}\n` +
+            `  ${pc.dim('Run')} ${pc.cyan(`npm i -g ${name}`)}\n\n`);
+    }
+    if (!cache || Date.now() - cache.checkedAt > ONE_DAY)
+        scheduleRefresh(name);
+}
+function readCache() {
+    try {
+        return JSON.parse(readFileSync(CACHE_FILE, 'utf8'));
+    }
+    catch {
+        return null;
+    }
+}
+/** Detached child fetches the registry, writes the cache, then exits — outlives us. */
+function scheduleRefresh(name) {
+    const script = `
+    const fs = require('node:fs'), path = require('node:path'), file = process.argv[2];
+    fetch('https://registry.npmjs.org/' + process.argv[1] + '/latest')
+      .then((r) => r.json())
+      .then((j) => {
+        if (!j?.version) return;
+        fs.mkdirSync(path.dirname(file), { recursive: true });
+        fs.writeFileSync(file, JSON.stringify({ latest: j.version, checkedAt: Date.now() }));
+      })
+      .catch(() => {});
+  `;
+    try {
+        spawn(process.execPath, ['-e', script, name, CACHE_FILE], {
+            detached: true,
+            stdio: 'ignore',
+        }).unref();
+    }
+    catch {
+        /* a failed background check must never affect the CLI */
+    }
+}
+/** Is `a` a newer release than `b`? Compares major.minor.patch; ignores prerelease tags. */
+function isNewer(a, b) {
+    const pa = a.split('-')[0].split('.').map(Number);
+    const pb = b.split('-')[0].split('.').map(Number);
+    for (let i = 0; i < 3; i++) {
+        const da = pa[i] || 0;
+        const db = pb[i] || 0;
+        if (da !== db)
+            return da > db;
+    }
+    return false;
+}
+//# sourceMappingURL=update-check.js.map

package/dist/cli/update-check.js.map

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

package/dist/{mcp → core}/git.d.ts

@@ -32,3 +32,22 @@ export interface LogEntry {
     subject: string;
 }
 export declare function planLog(planRoot: string, cardRelPath: string, limit?: number): Promise<LogEntry[]>;
+export interface SyncActivity {
+    sha: string;
+    short_sha: string;
+    date: string;
+    subject: string;
+    cards: string[];
+    is_sync_point: boolean;
+}
+/**
+ * Recent commits that touched the plan folder, newest first. Each entry lists the
+ * plan-card handles it changed and flags sync-point commits (those that moved the
+ * .sync.json marker). Derived live from git — the activity log is never stored.
+ */
+export declare function recentPlanActivity(planRoot: string, limit?: number): Promise<SyncActivity[]>;
+/**
+ * How many commits between `sinceSha` and HEAD touch files OUTSIDE the plan folder
+ * — i.e. how far the code has moved since the plan was last reconciled.
+ */
+export declare function countCodeCommitsSince(planRoot: string, sinceSha: string): Promise<number>;

package/dist/{mcp → core}/git.js

@@ -2,8 +2,8 @@ import { execFile } from 'node:child_process';
 import { readFile, realpath, writeFile } from 'node:fs/promises';
 import path from 'node:path';
 import { promisify } from 'node:util';
-import { isHandleShaped, typeForHandle } from '../core/handles.js';
-import { parseFile } from '../core/parse.js';
+import { isHandleShaped, typeForHandle } from './handles.js';
+import { parseFile } from './parse.js';
 const exec = promisify(execFile);
 async function git(cwd, ...args) {
     const { stdout } = await exec('git', args, {
@@ -169,4 +169,61 @@ export async function planLog(planRoot, cardRelPath, limit = 20) {
         return { sha, date, subject: subject.join('\t') };
     });
 }
+/**
+ * Recent commits that touched the plan folder, newest first. Each entry lists the
+ * plan-card handles it changed and flags sync-point commits (those that moved the
+ * .sync.json marker). Derived live from git — the activity log is never stored.
+ */
+export async function recentPlanActivity(planRoot, limit = 6) {
+    const realRoot = await realpath(planRoot);
+    const repoRoot = await repoRootFor(realRoot);
+    const planRel = path.relative(repoRoot, realRoot) || '.';
+    // %x1e (record separator) prefixes each commit; %x1f (unit separator) splits the
+    // header fields; --name-only then lists that commit's files (scoped to the plan
+    // folder) on their own lines. One git call, parsed defensively.
+    const out = await git(repoRoot, 'log', `-n${limit}`, '--pretty=format:%x1e%H%x1f%aI%x1f%s', '--name-only', '--', planRel);
+    const activity = [];
+    for (const record of out.split('\x1e')) {
+        if (!record.trim())
+            continue;
+        const newline = record.indexOf('\n');
+        const header = newline === -1 ? record : record.slice(0, newline);
+        const [sha, date, subject] = header.split('\x1f');
+        if (!sha)
+            continue;
+        const files = (newline === -1 ? '' : record.slice(newline + 1))
+            .split('\n')
+            .map((f) => f.trim())
+            .filter(Boolean);
+        const cards = [];
+        let isSyncPoint = false;
+        for (const file of files) {
+            if (path.basename(file) === SYNC_FILE)
+                isSyncPoint = true;
+            const handle = handleForRepoPath(file, planRel);
+            if (handle && !cards.includes(handle))
+                cards.push(handle);
+        }
+        activity.push({
+            sha,
+            short_sha: sha.slice(0, 8),
+            date: date ?? '',
+            subject: subject ?? '',
+            cards,
+            is_sync_point: isSyncPoint,
+        });
+    }
+    return activity;
+}
+/**
+ * How many commits between `sinceSha` and HEAD touch files OUTSIDE the plan folder
+ * — i.e. how far the code has moved since the plan was last reconciled.
+ */
+export async function countCodeCommitsSince(planRoot, sinceSha) {
+    const realRoot = await realpath(planRoot);
+    const repoRoot = await repoRootFor(realRoot);
+    const planRel = path.relative(repoRoot, realRoot) || '.';
+    const out = await git(repoRoot, 'rev-list', '--count', `${sinceSha}..HEAD`, '--', '.', `:(exclude)${planRel}`);
+    return Number.parseInt(out.trim(), 10) || 0;
+}
 //# sourceMappingURL=git.js.map

package/dist/core/git.js.map

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

package/dist/core/index.d.ts

@@ -6,3 +6,4 @@ export * from './indexer.js';
 export * from './validate.js';
 export * from './lint.js';
 export * from './writer.js';
+export * from './repos.js';

package/dist/core/index.js

@@ -6,4 +6,5 @@ export * from './indexer.js';
 export * from './validate.js';
 export * from './lint.js';
 export * from './writer.js';
+export * from './repos.js';
 //# sourceMappingURL=index.js.map

package/dist/core/index.js.map

@@ -1 +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"}
+{"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;AAC5B,cAAc,YAAY,CAAC"}

package/dist/core/repos.d.ts

@@ -0,0 +1,40 @@
+import type { ConnectedRepo } from './types.js';
+/**
+ * Read the connected_repos declared on PLAN-PROJECT (plan.md at the plan root).
+ * Returns [] when there is no plan.md, no frontmatter, or no connected_repos.
+ * Malformed entries are skipped silently — lint surfaces the schema warning
+ * (W002) separately; this reader stays lenient so a broken entry never crashes
+ * a resolution that other entries could still satisfy.
+ */
+export declare function readConnectedRepos(planRoot: string): Promise<ConnectedRepo[]>;
+export interface ResolvedRepo {
+    /** The connected repo's plan root (its constellation/ folder). */
+    root: string;
+    /** The connected repo's root directory. */
+    repoRoot: string;
+    /** The connected_repos name when resolved by name; null when resolved by raw path. */
+    name: string | null;
+}
+/**
+ * Resolve a `repo` selector against a home plan. `nameOrPath` is either the name
+ * of a connected_repos entry on the home plan, or a path (relative to the home
+ * repo root, or absolute). Returns null when it can't be resolved to a plan.
+ */
+export declare function resolveConnectedRepo(homePlanRoot: string, nameOrPath: string): Promise<ResolvedRepo | null>;
+export interface ConnectedRepoStatus extends ConnectedRepo {
+    /** Whether the path resolves to an existing plan on this machine. */
+    reachable: boolean;
+    /** The resolved plan root, or null when unreachable. */
+    planRoot: string | null;
+}
+/** The home plan's connected repos, each annotated with use-time reachability. */
+export declare function listConnectedRepos(homePlanRoot: string): Promise<ConnectedRepoStatus[]>;
+/** Upsert an entry by name (replacing any existing entry with the same name). */
+export declare function upsertConnectedRepo(existing: ConnectedRepo[], entry: ConnectedRepo): ConnectedRepo[];
+/** Remove the entry with the given name. */
+export declare function removeConnectedRepoEntry(existing: ConnectedRepo[], name: string): ConnectedRepo[];
+/**
+ * Serialize a ConnectedRepo to a plain frontmatter object, omitting an empty
+ * description so we never write `description: null` into a card.
+ */
+export declare function connectedRepoToFm(repo: ConnectedRepo): Record<string, unknown>;

package/dist/core/repos.js

@@ -0,0 +1,93 @@
+import path from 'node:path';
+import { readFile } from 'node:fs/promises';
+import { parseFile } from './parse.js';
+import { resolvePlanDir } from './resolve.js';
+/**
+ * Connected repos are repo-level links declared on PLAN-PROJECT (plan.md).
+ * They never become card connections and the indexer never sees them — they
+ * are read on demand here, so a connected repo's plan can be resolved and
+ * targeted by the `repo` selector without ever merging two plans.
+ */
+/** The directory containing the plan folder — the repo root in the normal layout. */
+function repoRootOf(planRoot) {
+    return path.dirname(planRoot);
+}
+/**
+ * Read the connected_repos declared on PLAN-PROJECT (plan.md at the plan root).
+ * Returns [] when there is no plan.md, no frontmatter, or no connected_repos.
+ * Malformed entries are skipped silently — lint surfaces the schema warning
+ * (W002) separately; this reader stays lenient so a broken entry never crashes
+ * a resolution that other entries could still satisfy.
+ */
+export async function readConnectedRepos(planRoot) {
+    let raw;
+    try {
+        raw = await readFile(path.join(planRoot, 'plan.md'), 'utf8');
+    }
+    catch {
+        return [];
+    }
+    const list = parseFile(raw).frontmatter.connected_repos;
+    if (!Array.isArray(list))
+        return [];
+    const repos = [];
+    for (const entry of list) {
+        if (!entry || typeof entry !== 'object' || Array.isArray(entry))
+            continue;
+        const e = entry;
+        if (typeof e.name !== 'string' || typeof e.path !== 'string')
+            continue;
+        repos.push({
+            name: e.name,
+            path: e.path,
+            description: typeof e.description === 'string' ? e.description : undefined,
+        });
+    }
+    return repos;
+}
+/** Resolve a path (relative to the home repo root, or absolute) to a plan root, or null. */
+async function resolveRepoPath(homePlanRoot, rawPath) {
+    const abs = path.isAbsolute(rawPath)
+        ? rawPath
+        : path.resolve(repoRootOf(homePlanRoot), rawPath);
+    return resolvePlanDir(abs);
+}
+/**
+ * Resolve a `repo` selector against a home plan. `nameOrPath` is either the name
+ * of a connected_repos entry on the home plan, or a path (relative to the home
+ * repo root, or absolute). Returns null when it can't be resolved to a plan.
+ */
+export async function resolveConnectedRepo(homePlanRoot, nameOrPath) {
+    const byName = (await readConnectedRepos(homePlanRoot)).find((r) => r.name === nameOrPath);
+    const root = await resolveRepoPath(homePlanRoot, byName ? byName.path : nameOrPath);
+    if (!root)
+        return null;
+    return { root, repoRoot: repoRootOf(root), name: byName?.name ?? null };
+}
+/** The home plan's connected repos, each annotated with use-time reachability. */
+export async function listConnectedRepos(homePlanRoot) {
+    const repos = await readConnectedRepos(homePlanRoot);
+    return Promise.all(repos.map(async (r) => {
+        const planRoot = await resolveRepoPath(homePlanRoot, r.path);
+        return { ...r, reachable: planRoot !== null, planRoot };
+    }));
+}
+/** Upsert an entry by name (replacing any existing entry with the same name). */
+export function upsertConnectedRepo(existing, entry) {
+    return [...existing.filter((r) => r.name !== entry.name), entry];
+}
+/** Remove the entry with the given name. */
+export function removeConnectedRepoEntry(existing, name) {
+    return existing.filter((r) => r.name !== name);
+}
+/**
+ * Serialize a ConnectedRepo to a plain frontmatter object, omitting an empty
+ * description so we never write `description: null` into a card.
+ */
+export function connectedRepoToFm(repo) {
+    const out = { name: repo.name, path: repo.path };
+    if (repo.description)
+        out.description = repo.description;
+    return out;
+}
+//# sourceMappingURL=repos.js.map

package/dist/core/repos.js.map

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

package/dist/core/resolve.js

@@ -11,7 +11,10 @@ export async function resolvePlanDir(target) {
         const nested = path.join(abs, 'constellation');
         if (await isDirectory(nested))
             return nested;
-        if (await isDirectory(abs))
+        // Only adopt the target itself when it actually looks like a plan root —
+        // otherwise an explicit path to an unrelated directory would be linted or
+        // served as if its markdown files were cards.
+        if ((await isDirectory(abs)) && (await looksLikePlanRoot(abs)))
             return abs;
         return null;
     }
@@ -37,6 +40,12 @@ export async function findPlanUp(startDir) {
         dir = parent;
     }
 }
+/** A directory is a plan root if it's named `constellation` or contains a plan.md. */
+async function looksLikePlanRoot(dir) {
+    if (path.basename(dir) === 'constellation')
+        return true;
+    return exists(path.join(dir, 'plan.md'));
+}
 export async function exists(p) {
     try {
         await access(p);

package/dist/core/resolve.js.map

@@ -1 +1 @@
-{"version":3,"file":"resolve.js","sourceRoot":"","sources":["../../src/core/resolve.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AAChD,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,OAAO,MAAM,cAAc,CAAC;AAEnC;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAAC,MAAe;IAClD,IAAI,MAAM,EAAE,CAAC;QACX,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;QACjC,MAAM,MAAM,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,eAAe,CAAC,CAAC;QAC/C,IAAI,MAAM,WAAW,CAAC,MAAM,CAAC;YAAE,OAAO,MAAM,CAAC;QAC7C,IAAI,MAAM,WAAW,CAAC,GAAG,CAAC;YAAE,OAAO,GAAG,CAAC;QACvC,OAAO,IAAI,CAAC;IACd,CAAC;IACD,OAAO,UAAU,CAAC,OAAO,CAAC,GAAG,EAAE,CAAC,CAAC;AACnC,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,UAAU,CAAC,QAAgB;IAC/C,IAAI,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;IACjC,SAAS,CAAC;QACR,MAAM,SAAS,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,eAAe,CAAC,CAAC;QAClD,IAAI,MAAM,MAAM,CAAC,SAAS,CAAC;YAAE,OAAO,SAAS,CAAC;QAC9C,kEAAkE;QAClE,IAAI,MAAM,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;YAAE,OAAO,IAAI,CAAC;QACtD,MAAM,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;QACjC,IAAI,MAAM,KAAK,GAAG;YAAE,OAAO,IAAI,CAAC;QAChC,GAAG,GAAG,MAAM,CAAC;IACf,CAAC;AACH,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,MAAM,CAAC,CAAS;IACpC,IAAI,CAAC;QACH,MAAM,MAAM,CAAC,CAAC,CAAC,CAAC;QAChB,OAAO,IAAI,CAAC;IACd,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAED,KAAK,UAAU,WAAW,CAAC,CAAS;IAClC,IAAI,CAAC;QACH,OAAO,CAAC,MAAM,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC;IACvC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC"}
+{"version":3,"file":"resolve.js","sourceRoot":"","sources":["../../src/core/resolve.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AAChD,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,OAAO,MAAM,cAAc,CAAC;AAEnC;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAAC,MAAe;IAClD,IAAI,MAAM,EAAE,CAAC;QACX,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;QACjC,MAAM,MAAM,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,eAAe,CAAC,CAAC;QAC/C,IAAI,MAAM,WAAW,CAAC,MAAM,CAAC;YAAE,OAAO,MAAM,CAAC;QAC7C,yEAAyE;QACzE,0EAA0E;QAC1E,8CAA8C;QAC9C,IAAI,CAAC,MAAM,WAAW,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,MAAM,iBAAiB,CAAC,GAAG,CAAC,CAAC;YAAE,OAAO,GAAG,CAAC;QAC3E,OAAO,IAAI,CAAC;IACd,CAAC;IACD,OAAO,UAAU,CAAC,OAAO,CAAC,GAAG,EAAE,CAAC,CAAC;AACnC,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,UAAU,CAAC,QAAgB;IAC/C,IAAI,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;IACjC,SAAS,CAAC;QACR,MAAM,SAAS,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,eAAe,CAAC,CAAC;QAClD,IAAI,MAAM,MAAM,CAAC,SAAS,CAAC;YAAE,OAAO,SAAS,CAAC;QAC9C,kEAAkE;QAClE,IAAI,MAAM,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;YAAE,OAAO,IAAI,CAAC;QACtD,MAAM,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;QACjC,IAAI,MAAM,KAAK,GAAG;YAAE,OAAO,IAAI,CAAC;QAChC,GAAG,GAAG,MAAM,CAAC;IACf,CAAC;AACH,CAAC;AAED,sFAAsF;AACtF,KAAK,UAAU,iBAAiB,CAAC,GAAW;IAC1C,IAAI,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,KAAK,eAAe;QAAE,OAAO,IAAI,CAAC;IACxD,OAAO,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,SAAS,CAAC,CAAC,CAAC;AAC3C,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,MAAM,CAAC,CAAS;IACpC,IAAI,CAAC;QACH,MAAM,MAAM,CAAC,CAAC,CAAC,CAAC;QAChB,OAAO,IAAI,CAAC;IACd,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAED,KAAK,UAAU,WAAW,CAAC,CAAS;IAClC,IAAI,CAAC;QACH,OAAO,CAAC,MAAM,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC;IACvC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC"}