@magic-spells/constellation 0.1.1 → 0.2.1

package/README.md

@@ -40,6 +40,9 @@ 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
+constellation version       # print the CLI version (`v` also works)
+constellation upgrade       # npm install -g @magic-spells/constellation@latest
 ```
 
 Lint errors (broken graph: bad handles, dangling structured references,
@@ -55,7 +58,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 +82,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.
 
@@ -107,6 +114,31 @@ step back and pressure-test the plan for blind spots (missing unhappy paths, aut
 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.):
@@ -130,9 +162,9 @@ 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). Eight 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**, **sumi**, **daylight**, **frost**, and **ember**.
+**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

package/dist/cli/index.js

@@ -5,11 +5,43 @@ 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.
+    }
+}
+async function upgradeCli() {
+    const { spawn } = await import('node:child_process');
+    const npm = process.platform === 'win32' ? 'npm.cmd' : 'npm';
+    const child = spawn(npm, ['install', '-g', `${name}@latest`], {
+        stdio: 'inherit',
+    });
+    const code = await new Promise((resolve) => {
+        child.on('error', () => resolve(1));
+        child.on('close', (exitCode) => resolve(exitCode ?? 1));
+    });
+    process.exit(code);
+}
 program
     .name('constellation')
     .description('Files-first architecture planning for AI-assisted development')
@@ -17,6 +49,20 @@ program
 // Update notice on every human command, but never for `mcp` (its stdout is JSON-RPC).
 if (process.argv[2] !== 'mcp')
     notifyUpdate(name, version);
+for (const command of ['version', 'v']) {
+    program
+        .command(command)
+        .description('Print the Constellation CLI version')
+        .action(() => {
+        console.log(version);
+    });
+}
+program
+    .command('upgrade')
+    .description('Upgrade the globally installed Constellation CLI with npm')
+    .action(async () => {
+    await upgradeCli();
+});
 program
     .command('lint')
     .argument('[path]', 'plan folder, or a directory containing constellation/ (default: walk up from cwd)')
@@ -121,14 +167,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/{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/sync.d.ts

@@ -0,0 +1,28 @@
+import { type SyncActivity, type SyncPoint } from './git.js';
+export type SyncState = 'in-sync' | 'drifted' | 'dirty' | 'never-synced' | 'no-git';
+export interface SyncStatus {
+    state: SyncState;
+    marker: SyncPoint | null;
+    plan_dirty: boolean;
+    plan_changes_since_marker: number;
+    code_commits_since_marker: number;
+    integrity: {
+        errors: number;
+        warnings: number;
+        orphans: number;
+    };
+    status_rollup: Record<string, number>;
+    total_cards: number;
+    activity: SyncActivity[];
+}
+/**
+ * The plan's freshness/trust state, computed live from git + lint on every call —
+ * never stored, so it cannot go stale or lie. Composes the sync marker
+ * (.sync.json), working-tree state, drift since the marker, lint integrity, the
+ * card-status rollup, and recent plan activity into one glanceable verdict. When
+ * the plan isn't in a git repo, returns `state: 'no-git'` (the viewer hides the
+ * freshness pill) but still reports the git-independent lint + rollup.
+ */
+export declare function computeSyncStatus(planRoot: string, options?: {
+    activityLimit?: number;
+}): Promise<SyncStatus>;

package/dist/core/sync.js

@@ -0,0 +1,85 @@
+import { countCodeCommitsSince, diffPlan, planDirty, readSyncPoint, recentPlanActivity, } from './git.js';
+import { lintPlan } from './lint.js';
+const STATUS_KEYS = ['planned', 'building', 'built', 'verified'];
+/**
+ * The plan's freshness/trust state, computed live from git + lint on every call —
+ * never stored, so it cannot go stale or lie. Composes the sync marker
+ * (.sync.json), working-tree state, drift since the marker, lint integrity, the
+ * card-status rollup, and recent plan activity into one glanceable verdict. When
+ * the plan isn't in a git repo, returns `state: 'no-git'` (the viewer hides the
+ * freshness pill) but still reports the git-independent lint + rollup.
+ */
+export async function computeSyncStatus(planRoot, options = {}) {
+    const lint = await lintPlan(planRoot);
+    const orphans = [...lint.index.cards.keys()].filter((h) => (lint.index.connectedHandles.get(h)?.size ?? 0) === 0);
+    const status_rollup = { none: 0 };
+    for (const key of STATUS_KEYS)
+        status_rollup[key] = 0;
+    for (const card of lint.index.cards.values()) {
+        const key = card.status ?? 'none';
+        status_rollup[key] = (status_rollup[key] ?? 0) + 1;
+    }
+    const base = {
+        integrity: {
+            errors: lint.errors.length,
+            warnings: lint.warnings.length,
+            orphans: orphans.length,
+        },
+        status_rollup,
+        total_cards: lint.index.cards.size,
+    };
+    let marker = null;
+    let plan_dirty = false;
+    let plan_changes_since_marker = 0;
+    let code_commits_since_marker = 0;
+    let activity = [];
+    try {
+        marker = await readSyncPoint(planRoot);
+        plan_dirty = await planDirty(planRoot);
+        activity = await recentPlanActivity(planRoot, options.activityLimit ?? 6);
+        if (marker) {
+            try {
+                const diff = await diffPlan(planRoot, marker.synced_sha, 'HEAD');
+                plan_changes_since_marker = diff.changes.length;
+            }
+            catch {
+                // marker sha unreachable (e.g. rebased history) — leave 0
+            }
+            try {
+                code_commits_since_marker = await countCodeCommitsSince(planRoot, marker.synced_sha);
+            }
+            catch {
+                // ignore — drift count is best-effort
+            }
+        }
+    }
+    catch {
+        // repoRootFor threw → not a git repo; no freshness signal is available.
+        return {
+            state: 'no-git',
+            marker: null,
+            plan_dirty: false,
+            plan_changes_since_marker: 0,
+            code_commits_since_marker: 0,
+            activity: [],
+            ...base,
+        };
+    }
+    const state = !marker
+        ? 'never-synced'
+        : plan_changes_since_marker > 0 || code_commits_since_marker > 0
+            ? 'drifted'
+            : plan_dirty
+                ? 'dirty'
+                : 'in-sync';
+    return {
+        state,
+        marker,
+        plan_dirty,
+        plan_changes_since_marker,
+        code_commits_since_marker,
+        activity,
+        ...base,
+    };
+}
+//# sourceMappingURL=sync.js.map

package/dist/core/sync.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sync.js","sourceRoot":"","sources":["../../src/core/sync.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,qBAAqB,EACrB,QAAQ,EACR,SAAS,EACT,aAAa,EACb,kBAAkB,GAGnB,MAAM,UAAU,CAAC;AAClB,OAAO,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AAqBrC,MAAM,WAAW,GAAG,CAAC,SAAS,EAAE,UAAU,EAAE,OAAO,EAAE,UAAU,CAAU,CAAC;AAE1E;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CACrC,QAAgB,EAChB,UAAsC,EAAE;IAExC,MAAM,IAAI,GAAG,MAAM,QAAQ,CAAC,QAAQ,CAAC,CAAC;IACtC,MAAM,OAAO,GAAG,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC,MAAM,CACjD,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,gBAAgB,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,IAAI,IAAI,CAAC,CAAC,KAAK,CAAC,CAC7D,CAAC;IACF,MAAM,aAAa,GAA2B,EAAE,IAAI,EAAE,CAAC,EAAE,CAAC;IAC1D,KAAK,MAAM,GAAG,IAAI,WAAW;QAAE,aAAa,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IACtD,KAAK,MAAM,IAAI,IAAI,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,MAAM,EAAE,EAAE,CAAC;QAC7C,MAAM,GAAG,GAAG,IAAI,CAAC,MAAM,IAAI,MAAM,CAAC;QAClC,aAAa,CAAC,GAAG,CAAC,GAAG,CAAC,aAAa,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC;IACrD,CAAC;IAED,MAAM,IAAI,GAAG;QACX,SAAS,EAAE;YACT,MAAM,EAAE,IAAI,CAAC,MAAM,CAAC,MAAM;YAC1B,QAAQ,EAAE,IAAI,CAAC,QAAQ,CAAC,MAAM;YAC9B,OAAO,EAAE,OAAO,CAAC,MAAM;SACxB;QACD,aAAa;QACb,WAAW,EAAE,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,IAAI;KACnC,CAAC;IAEF,IAAI,MAAM,GAAqB,IAAI,CAAC;IACpC,IAAI,UAAU,GAAG,KAAK,CAAC;IACvB,IAAI,yBAAyB,GAAG,CAAC,CAAC;IAClC,IAAI,yBAAyB,GAAG,CAAC,CAAC;IAClC,IAAI,QAAQ,GAAmB,EAAE,CAAC;IAClC,IAAI,CAAC;QACH,MAAM,GAAG,MAAM,aAAa,CAAC,QAAQ,CAAC,CAAC;QACvC,UAAU,GAAG,MAAM,SAAS,CAAC,QAAQ,CAAC,CAAC;QACvC,QAAQ,GAAG,MAAM,kBAAkB,CAAC,QAAQ,EAAE,OAAO,CAAC,aAAa,IAAI,CAAC,CAAC,CAAC;QAC1E,IAAI,MAAM,EAAE,CAAC;YACX,IAAI,CAAC;gBACH,MAAM,IAAI,GAAG,MAAM,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC,UAAU,EAAE,MAAM,CAAC,CAAC;gBACjE,yBAAyB,GAAG,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC;YAClD,CAAC;YAAC,MAAM,CAAC;gBACP,0DAA0D;YAC5D,CAAC;YACD,IAAI,CAAC;gBACH,yBAAyB,GAAG,MAAM,qBAAqB,CACrD,QAAQ,EACR,MAAM,CAAC,UAAU,CAClB,CAAC;YACJ,CAAC;YAAC,MAAM,CAAC;gBACP,sCAAsC;YACxC,CAAC;QACH,CAAC;IACH,CAAC;IAAC,MAAM,CAAC;QACP,wEAAwE;QACxE,OAAO;YACL,KAAK,EAAE,QAAQ;YACf,MAAM,EAAE,IAAI;YACZ,UAAU,EAAE,KAAK;YACjB,yBAAyB,EAAE,CAAC;YAC5B,yBAAyB,EAAE,CAAC;YAC5B,QAAQ,EAAE,EAAE;YACZ,GAAG,IAAI;SACR,CAAC;IACJ,CAAC;IAED,MAAM,KAAK,GAAc,CAAC,MAAM;QAC9B,CAAC,CAAC,cAAc;QAChB,CAAC,CAAC,yBAAyB,GAAG,CAAC,IAAI,yBAAyB,GAAG,CAAC;YAC9D,CAAC,CAAC,SAAS;YACX,CAAC,CAAC,UAAU;gBACV,CAAC,CAAC,OAAO;gBACT,CAAC,CAAC,SAAS,CAAC;IAElB,OAAO;QACL,KAAK;QACL,MAAM;QACN,UAAU;QACV,yBAAyB;QACzB,yBAAyB;QACzB,QAAQ;QACR,GAAG,IAAI;KACR,CAAC;AACJ,CAAC"}

package/dist/core/types.d.ts

@@ -29,6 +29,18 @@ export interface Connection {
     a: string;
     b: string;
 }
+/**
+ * A sibling repo declared in PLAN-PROJECT `connected_repos`. A repo-level link
+ * only — never a card connection. The path is local topology (relative to the
+ * repo root, or absolute) and is never validated by lint.
+ */
+export interface ConnectedRepo {
+    /** Lowercase id used as the `repo` selector. */
+    name: string;
+    /** Path to the connected repo's root, relative to this repo's root (or absolute). */
+    path: string;
+    description?: string;
+}
 export type Severity = 'error' | 'warning';
 export interface Issue {
     severity: Severity;