@magic-spells/constellation 0.1.0

package/dist/core/indexer.js.map

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

package/dist/core/lint.d.ts

@@ -0,0 +1,9 @@
+import type { Issue, PlanIndex } from './types.js';
+export interface LintResult {
+    index: PlanIndex;
+    issues: Issue[];
+    errors: Issue[];
+    warnings: Issue[];
+}
+/** Structural checks (indexer) + schema validation, sorted by file then code. */
+export declare function lintPlan(root: string): Promise<LintResult>;

package/dist/core/lint.js

@@ -0,0 +1,19 @@
+import { loadPlan } from './indexer.js';
+import { loadSchemas } from './validate.js';
+/** Structural checks (indexer) + schema validation, sorted by file then code. */
+export async function lintPlan(root) {
+    const index = await loadPlan(root);
+    const schemas = await loadSchemas();
+    const issues = [...index.issues];
+    for (const card of index.cards.values()) {
+        issues.push(...schemas.validateCard(card));
+    }
+    issues.sort((x, y) => x.file.localeCompare(y.file) || x.code.localeCompare(y.code));
+    return {
+        index,
+        issues,
+        errors: issues.filter((i) => i.severity === 'error'),
+        warnings: issues.filter((i) => i.severity === 'warning'),
+    };
+}
+//# sourceMappingURL=lint.js.map

package/dist/core/lint.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lint.js","sourceRoot":"","sources":["../../src/core/lint.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AACxC,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAU5C,iFAAiF;AACjF,MAAM,CAAC,KAAK,UAAU,QAAQ,CAAC,IAAY;IACzC,MAAM,KAAK,GAAG,MAAM,QAAQ,CAAC,IAAI,CAAC,CAAC;IACnC,MAAM,OAAO,GAAG,MAAM,WAAW,EAAE,CAAC;IAEpC,MAAM,MAAM,GAAY,CAAC,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC;IAC1C,KAAK,MAAM,IAAI,IAAI,KAAK,CAAC,KAAK,CAAC,MAAM,EAAE,EAAE,CAAC;QACxC,MAAM,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,YAAY,CAAC,IAAI,CAAC,CAAC,CAAC;IAC7C,CAAC;IAED,MAAM,CAAC,IAAI,CACT,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC,CAAC,IAAI,CAAC,CACvE,CAAC;IAEF,OAAO;QACL,KAAK;QACL,MAAM;QACN,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,KAAK,OAAO,CAAC;QACpD,QAAQ,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,KAAK,SAAS,CAAC;KACzD,CAAC;AACJ,CAAC"}

package/dist/core/parse.d.ts

@@ -0,0 +1,7 @@
+export interface ParsedFile {
+    frontmatter: Record<string, unknown>;
+    body: string;
+    /** Set when the frontmatter is not valid YAML; frontmatter is {} in that case. */
+    yamlError?: string;
+}
+export declare function parseFile(raw: string): ParsedFile;

package/dist/core/parse.js

@@ -0,0 +1,19 @@
+import matter from 'gray-matter';
+export function parseFile(raw) {
+    try {
+        const parsed = matter(raw);
+        const data = parsed.data;
+        const frontmatter = data && typeof data === 'object' && !Array.isArray(data)
+            ? data
+            : {};
+        return { frontmatter, body: parsed.content };
+    }
+    catch (err) {
+        return {
+            frontmatter: {},
+            body: raw,
+            yamlError: err instanceof Error ? err.message.split('\n')[0] : String(err),
+        };
+    }
+}
+//# sourceMappingURL=parse.js.map

package/dist/core/parse.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"parse.js","sourceRoot":"","sources":["../../src/core/parse.ts"],"names":[],"mappings":"AAAA,OAAO,MAAM,MAAM,aAAa,CAAC;AASjC,MAAM,UAAU,SAAS,CAAC,GAAW;IACnC,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC;QAC3B,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC;QACzB,MAAM,WAAW,GACf,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC;YACtD,CAAC,CAAE,IAAgC;YACnC,CAAC,CAAC,EAAE,CAAC;QACT,OAAO,EAAE,WAAW,EAAE,IAAI,EAAE,MAAM,CAAC,OAAO,EAAE,CAAC;IAC/C,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,OAAO;YACL,WAAW,EAAE,EAAE;YACf,IAAI,EAAE,GAAG;YACT,SAAS,EAAE,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC;SAC3E,CAAC;IACJ,CAAC;AACH,CAAC"}

package/dist/core/resolve.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Find the plan folder. With a target: the target itself or target/constellation.
+ * Without: walk up from cwd looking for constellation/, bounded by the repo root.
+ */
+export declare function resolvePlanDir(target?: string): Promise<string | null>;
+/**
+ * Walk up from `startDir` for a `constellation/` folder, stopping at the repo
+ * root (the first ancestor containing `.git`). Returns null rather than crossing
+ * the repo boundary, so a repo with no plan never adopts a sibling repo's plan.
+ */
+export declare function findPlanUp(startDir: string): Promise<string | null>;
+export declare function exists(p: string): Promise<boolean>;

package/dist/core/resolve.js

@@ -0,0 +1,57 @@
+import { access, stat } from 'node:fs/promises';
+import path from 'node:path';
+import process from 'node:process';
+/**
+ * Find the plan folder. With a target: the target itself or target/constellation.
+ * Without: walk up from cwd looking for constellation/, bounded by the repo root.
+ */
+export async function resolvePlanDir(target) {
+    if (target) {
+        const abs = path.resolve(target);
+        const nested = path.join(abs, 'constellation');
+        if (await isDirectory(nested))
+            return nested;
+        if (await isDirectory(abs))
+            return abs;
+        return null;
+    }
+    return findPlanUp(process.cwd());
+}
+/**
+ * Walk up from `startDir` for a `constellation/` folder, stopping at the repo
+ * root (the first ancestor containing `.git`). Returns null rather than crossing
+ * the repo boundary, so a repo with no plan never adopts a sibling repo's plan.
+ */
+export async function findPlanUp(startDir) {
+    let dir = path.resolve(startDir);
+    for (;;) {
+        const candidate = path.join(dir, 'constellation');
+        if (await exists(candidate))
+            return candidate;
+        // Stop at the repo root — never ascend past it into another repo.
+        if (await exists(path.join(dir, '.git')))
+            return null;
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            return null;
+        dir = parent;
+    }
+}
+export async function exists(p) {
+    try {
+        await access(p);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function isDirectory(p) {
+    try {
+        return (await stat(p)).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=resolve.js.map

package/dist/core/resolve.js.map

@@ -0,0 +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"}

package/dist/core/scaffold.d.ts

@@ -0,0 +1,3 @@
+export declare const STARTER_PLAN = "---\nname: Project plan\n---\n\n# Project Plan\n\n## Current state\n\n- (what exists, what is in flight)\n\n## Conventions\n\n- (project-wide rules cards should follow)\n\n## Last synced\n\nCode has not been reconciled against this plan yet.\n";
+/** Create constellation/ with a starter plan.md. Throws if it already exists. */
+export declare function initPlan(targetDir: string): Promise<string>;

package/dist/core/scaffold.js

@@ -0,0 +1,36 @@
+import { access, mkdir, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+export const STARTER_PLAN = `---
+name: Project plan
+---
+
+# Project Plan
+
+## Current state
+
+- (what exists, what is in flight)
+
+## Conventions
+
+- (project-wide rules cards should follow)
+
+## Last synced
+
+Code has not been reconciled against this plan yet.
+`;
+/** Create constellation/ with a starter plan.md. Throws if it already exists. */
+export async function initPlan(targetDir) {
+    const root = path.resolve(targetDir, 'constellation');
+    try {
+        await access(root);
+        throw new Error(`${root} already exists`);
+    }
+    catch (err) {
+        if (err instanceof Error && err.message.endsWith('already exists'))
+            throw err;
+    }
+    await mkdir(root, { recursive: true });
+    await writeFile(path.join(root, 'plan.md'), STARTER_PLAN, { flag: 'wx' });
+    return root;
+}
+//# sourceMappingURL=scaffold.js.map

package/dist/core/scaffold.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scaffold.js","sourceRoot":"","sources":["../../src/core/scaffold.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAC5D,OAAO,IAAI,MAAM,WAAW,CAAC;AAE7B,MAAM,CAAC,MAAM,YAAY,GAAG;;;;;;;;;;;;;;;;;CAiB3B,CAAC;AAEF,iFAAiF;AACjF,MAAM,CAAC,KAAK,UAAU,QAAQ,CAAC,SAAiB;IAC9C,MAAM,IAAI,GAAG,IAAI,CAAC,OAAO,CAAC,SAAS,EAAE,eAAe,CAAC,CAAC;IACtD,IAAI,CAAC;QACH,MAAM,MAAM,CAAC,IAAI,CAAC,CAAC;QACnB,MAAM,IAAI,KAAK,CAAC,GAAG,IAAI,iBAAiB,CAAC,CAAC;IAC5C,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,IAAI,GAAG,YAAY,KAAK,IAAI,GAAG,CAAC,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAC;YAAE,MAAM,GAAG,CAAC;IAChF,CAAC;IACD,MAAM,KAAK,CAAC,IAAI,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IACvC,MAAM,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,SAAS,CAAC,EAAE,YAAY,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;IAC1E,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/core/types.d.ts

@@ -0,0 +1,50 @@
+export declare const TYPE_NAMES: readonly ["API", "DB", "DATATYPE", "ROLE", "DOC", "FILE", "TEST", "EXTERNAL", "EVENT", "COMPONENT", "PAGE", "JOB", "FLOW", "STATE", "DIAGRAM", "AGENT", "PLAN"];
+export type TypeName = (typeof TYPE_NAMES)[number];
+export interface CardRefs {
+    /** Handles listed in the frontmatter `connections` key. */
+    connections: string[];
+    /** Handle-shaped values found elsewhere in frontmatter (e.g. response_schema). */
+    frontmatter: string[];
+    /** [[HANDLE]] wiki-links in the body. */
+    body: string[];
+    /** Handle-shaped identifiers inside ```mermaid blocks. */
+    mermaid: string[];
+}
+export interface Card {
+    handle: string;
+    type: TypeName;
+    /** Path relative to the plan root, e.g. api/API-TICKETS.md */
+    relPath: string;
+    /** Absolute path on disk. */
+    filePath: string;
+    frontmatter: Record<string, unknown>;
+    body: string;
+    name?: string;
+    kind?: string;
+    status?: string;
+    refs: CardRefs;
+}
+/** Undirected connection; endpoints are stored in sorted order so each pair is unique. */
+export interface Connection {
+    a: string;
+    b: string;
+}
+export type Severity = 'error' | 'warning';
+export interface Issue {
+    severity: Severity;
+    code: string;
+    message: string;
+    /** Path relative to the plan root. */
+    file: string;
+}
+export interface PlanIndex {
+    /** Absolute path of the plan root (the constellation/ folder). */
+    root: string;
+    /** Cards by handle. */
+    cards: Map<string, Card>;
+    connections: Connection[];
+    /** handle -> set of connected handles (both directions). */
+    connectedHandles: Map<string, Set<string>>;
+    /** Structural issues found while loading (E001–E006, W001, W004). */
+    issues: Issue[];
+}

package/dist/core/types.js

@@ -0,0 +1,5 @@
+export const TYPE_NAMES = [
+    'API', 'DB', 'DATATYPE', 'ROLE', 'DOC', 'FILE', 'TEST', 'EXTERNAL', 'EVENT',
+    'COMPONENT', 'PAGE', 'JOB', 'FLOW', 'STATE', 'DIAGRAM', 'AGENT', 'PLAN',
+];
+//# sourceMappingURL=types.js.map

package/dist/core/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/core/types.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,UAAU,GAAG;IACxB,KAAK,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,OAAO;IAC3E,WAAW,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM;CAC/D,CAAC"}

package/dist/core/validate.d.ts

@@ -0,0 +1,6 @@
+import type { Card, Issue } from './types.js';
+export interface SchemaSet {
+    /** Schema-violation (W002) and unknown-field (W003) issues for one card. */
+    validateCard(card: Card): Issue[];
+}
+export declare function loadSchemas(schemasDir?: string): Promise<SchemaSet>;

package/dist/core/validate.js

@@ -0,0 +1,64 @@
+import { readdir, readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { createRequire } from 'node:module';
+import { TYPE_FOLDERS } from './handles.js';
+// ajv ships CJS; createRequire sidesteps ESM default-export interop quirks.
+const require = createRequire(import.meta.url);
+const ajvModule = require('ajv/dist/2020.js');
+const Ajv2020 = ajvModule.default ?? ajvModule;
+const RESERVED_KEYS = ['name', 'kind', 'status', 'connections'];
+export async function loadSchemas(schemasDir) {
+    const dir = schemasDir ?? path.join(fileURLToPath(new URL('../..', import.meta.url)), 'schemas');
+    const ajv = new Ajv2020({ allErrors: true, allowUnionTypes: true });
+    const files = (await readdir(dir)).filter((f) => f.endsWith('.json'));
+    const raw = new Map();
+    for (const file of files) {
+        const schema = JSON.parse(await readFile(path.join(dir, file), 'utf8'));
+        raw.set(file, schema);
+        ajv.addSchema(schema, file);
+    }
+    const cardValidator = ajv.getSchema('card.json');
+    const typeValidators = new Map();
+    const knownKeys = new Map();
+    for (const [type, folder] of Object.entries(TYPE_FOLDERS)) {
+        const file = `${folder}.json`;
+        const schema = raw.get(file);
+        if (!schema)
+            continue;
+        typeValidators.set(type, ajv.getSchema(file));
+        const props = Object.keys(schema.properties ?? {});
+        knownKeys.set(type, new Set([...RESERVED_KEYS, ...props]));
+    }
+    return {
+        validateCard(card) {
+            const issues = [];
+            const validators = [cardValidator, typeValidators.get(card.type)].filter(Boolean);
+            for (const validate of validators) {
+                if (!validate(card.frontmatter)) {
+                    for (const err of validate.errors ?? []) {
+                        issues.push({
+                            severity: 'warning',
+                            code: 'W002',
+                            message: `Frontmatter${err.instancePath || ''} ${err.message ?? 'is invalid'}`,
+                            file: card.relPath,
+                        });
+                    }
+                }
+            }
+            const known = knownKeys.get(card.type) ?? new Set(RESERVED_KEYS);
+            for (const key of Object.keys(card.frontmatter)) {
+                if (!known.has(key)) {
+                    issues.push({
+                        severity: 'warning',
+                        code: 'W003',
+                        message: `Unknown frontmatter field for ${card.type}: ${key}`,
+                        file: card.relPath,
+                    });
+                }
+            }
+            return issues;
+        },
+    };
+}
+//# sourceMappingURL=validate.js.map

package/dist/core/validate.js.map

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

package/dist/core/writer.d.ts

@@ -0,0 +1,34 @@
+export declare function reservedFieldKeys(fields?: Record<string, unknown>): string[];
+/**
+ * Deep-merge a patch into a frontmatter object. Plain objects merge recursively,
+ * arrays replace wholesale, explicit null deletes the key. Returns a new object
+ * preserving the target's key order (new keys append).
+ */
+export declare function deepMerge(target: Record<string, unknown>, patch: Record<string, unknown>): Record<string, unknown>;
+export interface CardPatch {
+    name?: string | null;
+    kind?: string | null;
+    status?: string | null;
+    /** Replaces the whole list; null deletes it. */
+    connections?: string[] | null;
+    /** Type-specific frontmatter; deep-merged (arrays replace, null deletes). */
+    fields?: Record<string, unknown>;
+}
+/** Shared patch semantics for MCP update_card and the viewer's PATCH endpoint. */
+export declare function applyCardPatch(frontmatter: Record<string, unknown>, patch: CardPatch): Record<string, unknown>;
+export declare function composeCard(fm: Record<string, unknown>, body: string): string;
+/** Path a handle's card file belongs at, relative to the plan root. */
+export declare function relPathForHandle(handle: string): string;
+export declare function createCardFile(planRoot: string, handle: string, fm: Record<string, unknown>, body: string): Promise<string>;
+export interface CardFileUpdate {
+    /** Complete new frontmatter object. Omit to leave frontmatter bytes untouched. */
+    frontmatter?: Record<string, unknown>;
+    /** Complete new body. Omit to leave the body untouched. */
+    body?: string;
+}
+/**
+ * Rewrite a card file. A body-only update preserves the original frontmatter
+ * block byte-for-byte; a frontmatter update re-serializes only the top-level
+ * keys whose values changed, keeping everything else byte-identical.
+ */
+export declare function updateCardFile(filePath: string, update: CardFileUpdate): Promise<void>;

package/dist/core/writer.js

@@ -0,0 +1,170 @@
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import yaml from 'js-yaml';
+import { TYPE_FOLDERS, typeForHandle } from './handles.js';
+const FM_BLOCK = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?/;
+const RESERVED_FRONTMATTER_KEYS = new Set(['name', 'kind', 'status', 'connections']);
+export function reservedFieldKeys(fields) {
+    return Object.keys(fields ?? {}).filter((key) => RESERVED_FRONTMATTER_KEYS.has(key));
+}
+/**
+ * Deep-merge a patch into a frontmatter object. Plain objects merge recursively,
+ * arrays replace wholesale, explicit null deletes the key. Returns a new object
+ * preserving the target's key order (new keys append).
+ */
+export function deepMerge(target, patch) {
+    const out = { ...target };
+    for (const [key, value] of Object.entries(patch)) {
+        if (value === null) {
+            delete out[key];
+        }
+        else if (isPlainObject(value) && isPlainObject(out[key])) {
+            out[key] = deepMerge(out[key], value);
+        }
+        else {
+            out[key] = value;
+        }
+    }
+    return out;
+}
+/** Shared patch semantics for MCP update_card and the viewer's PATCH endpoint. */
+export function applyCardPatch(frontmatter, patch) {
+    const reserved = reservedFieldKeys(patch.fields);
+    if (reserved.length > 0) {
+        throw new Error(`fields cannot contain reserved keys: ${reserved.join(', ')}`);
+    }
+    const patchObject = { ...(patch.fields ?? {}) };
+    if (patch.name !== undefined)
+        patchObject.name = patch.name;
+    if (patch.kind !== undefined)
+        patchObject.kind = patch.kind;
+    if (patch.status !== undefined)
+        patchObject.status = patch.status;
+    if (patch.connections !== undefined) {
+        patchObject.connections =
+            patch.connections === null
+                ? null
+                : patch.connections.map((c) => c.toUpperCase());
+    }
+    return deepMerge(frontmatter, patchObject);
+}
+function isPlainObject(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        !Array.isArray(value) &&
+        Object.getPrototypeOf(value) === Object.prototype);
+}
+function dumpFrontmatter(fm) {
+    // js-yaml dumps in insertion order; deepMerge preserves it, so existing key
+    // order survives a rewrite. Style normalizes (flow maps may become block).
+    return yaml.dump(fm, { lineWidth: 100, noRefs: true });
+}
+export function composeCard(fm, body) {
+    const fmText = Object.keys(fm).length > 0 ? `---\n${dumpFrontmatter(fm)}---\n\n` : '';
+    return `${fmText}${body.replace(/\s+$/, '')}\n`;
+}
+/** Path a handle's card file belongs at, relative to the plan root. */
+export function relPathForHandle(handle) {
+    if (handle === 'PLAN-PROJECT')
+        return 'plan.md';
+    const type = typeForHandle(handle);
+    if (!type)
+        throw new Error(`Unknown handle prefix: ${handle}`);
+    return path.join(TYPE_FOLDERS[type], `${handle}.md`);
+}
+export async function createCardFile(planRoot, handle, fm, body) {
+    const relPath = relPathForHandle(handle);
+    const filePath = path.join(planRoot, relPath);
+    await mkdir(path.dirname(filePath), { recursive: true });
+    await writeFile(filePath, composeCard(fm, body), { flag: 'wx' });
+    return relPath;
+}
+/**
+ * Re-serialize frontmatter while keeping the original text of every top-level
+ * key whose value is unchanged — a status flip must not reformat the columns
+ * table next to it. Returns null when the original can't be segmented safely.
+ */
+function rewriteFrontmatter(originalInner, next) {
+    let originalParsed;
+    try {
+        const parsed = yaml.load(originalInner);
+        if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed))
+            return null;
+        originalParsed = parsed;
+    }
+    catch {
+        return null;
+    }
+    // Split the original YAML into one text segment per top-level key.
+    const segments = new Map();
+    let currentKey = null;
+    let currentLines = [];
+    for (const line of originalInner.split('\n')) {
+        const keyMatch = /^([A-Za-z0-9_-]+)\s*:/.exec(line);
+        if (keyMatch) {
+            if (currentKey)
+                segments.set(currentKey, currentLines.join('\n'));
+            currentKey = keyMatch[1];
+            currentLines = [line];
+        }
+        else if (currentKey) {
+            currentLines.push(line);
+        }
+        else if (line.trim() !== '') {
+            // Leading content that is not a plain key (quoted key, doc marker…).
+            return null;
+        }
+    }
+    if (currentKey)
+        segments.set(currentKey, currentLines.join('\n'));
+    if (segments.size !== Object.keys(originalParsed).length)
+        return null;
+    const parts = [];
+    for (const [key, value] of Object.entries(next)) {
+        const original = segments.get(key);
+        if (original !== undefined &&
+            JSON.stringify(originalParsed[key]) === JSON.stringify(value)) {
+            parts.push(original.replace(/\n+$/, ''));
+        }
+        else {
+            parts.push(yaml.dump({ [key]: value }, { lineWidth: 100, noRefs: true }).trimEnd());
+        }
+    }
+    return `${parts.join('\n')}\n`;
+}
+/**
+ * Rewrite a card file. A body-only update preserves the original frontmatter
+ * block byte-for-byte; a frontmatter update re-serializes only the top-level
+ * keys whose values changed, keeping everything else byte-identical.
+ */
+export async function updateCardFile(filePath, update) {
+    const raw = await readFile(filePath, 'utf8');
+    const match = raw.match(FM_BLOCK);
+    const originalFmBlock = match ? match[0] : '';
+    const originalBody = match ? raw.slice(match[0].length) : raw;
+    let fmText;
+    if (update.frontmatter !== undefined) {
+        if (Object.keys(update.frontmatter).length === 0) {
+            fmText = '';
+        }
+        else {
+            const inner = (match && rewriteFrontmatter(match[1], update.frontmatter)) ??
+                dumpFrontmatter(update.frontmatter);
+            fmText = `---\n${inner}---\n\n`;
+        }
+    }
+    else {
+        fmText = originalFmBlock;
+        // Keep the original separation when we keep the original block.
+        if (fmText && update.body !== undefined && !fmText.endsWith('\n\n')) {
+            fmText = `${fmText}\n`;
+        }
+    }
+    let body = update.body !== undefined ? update.body.replace(/\s+$/, '') : originalBody;
+    // The frontmatter block already supplies the blank-line separation.
+    if (fmText.endsWith('\n\n'))
+        body = body.replace(/^\n+/, '');
+    const trailingNewline = update.body !== undefined ? '\n' : '';
+    await writeFile(filePath, `${fmText}${body}${trailingNewline}`, 'utf8');
+}
+//# sourceMappingURL=writer.js.map

package/dist/core/writer.js.map

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

package/dist/mcp/git.d.ts

@@ -0,0 +1,34 @@
+export declare function repoRootFor(planRoot: string): Promise<string>;
+export interface SyncPoint {
+    synced_sha: string;
+    synced_at: string;
+}
+export declare function readSyncPoint(planRoot: string): Promise<SyncPoint | null>;
+export declare function writeSyncPoint(planRoot: string, sha?: string): Promise<SyncPoint>;
+/**
+ * True when the plan folder has uncommitted (staged or unstaged) changes,
+ * ignoring the .sync.json marker itself (writing the marker shouldn't count as
+ * the plan being dirty).
+ */
+export declare function planDirty(planRoot: string): Promise<boolean>;
+export type ChangeKind = 'added' | 'modified' | 'removed' | 'renamed';
+export interface PlanChange {
+    handle: string;
+    file: string;
+    change: ChangeKind;
+    changed_keys?: string[];
+    body_changed?: boolean;
+}
+export interface PlanDiff {
+    base: string;
+    base_source: 'argument' | 'sync-marker' | 'HEAD';
+    head: string;
+    changes: PlanChange[];
+}
+export declare function diffPlan(planRoot: string, base?: string, head?: string): Promise<PlanDiff>;
+export interface LogEntry {
+    sha: string;
+    date: string;
+    subject: string;
+}
+export declare function planLog(planRoot: string, cardRelPath: string, limit?: number): Promise<LogEntry[]>;