@magic-spells/constellation 0.1.0 → 0.2.0

package/dist/core/scaffold.d.ts

@@ -1,3 +1,16 @@
-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>;
+/** Turn a folder slug into a human-readable project name: pyramid-server → Pyramid Server. */
+export declare function titleCaseFromSlug(slug: string): string;
+/** The starter plan.md body, parameterized by the project's display name. */
+export declare function starterPlan(name: string): string;
+/**
+ * Create constellation/ with a starter plan.md. Throws if it already exists.
+ * The project name defaults to a title-cased version of the target folder
+ * (so pyramid-server → "Pyramid Server"); pass opts.name to override it. The
+ * resolved name is returned so callers can echo / confirm it.
+ */
+export declare function initPlan(targetDir: string, opts?: {
+    name?: string;
+}): Promise<{
+    root: string;
+    name: string;
+}>;

package/dist/core/scaffold.js

@@ -1,7 +1,20 @@
 import { access, mkdir, writeFile } from 'node:fs/promises';
 import path from 'node:path';
-export const STARTER_PLAN = `---
-name: Project plan
+/** Turn a folder slug into a human-readable project name: pyramid-server → Pyramid Server. */
+export function titleCaseFromSlug(slug) {
+    return slug
+        .replace(/[-_]+/g, ' ') // kebab / snake → spaces
+        .replace(/([a-z0-9])([A-Z])/g, '$1 $2') // split camelCase
+        .trim()
+        .split(/\s+/)
+        .filter(Boolean)
+        .map((w) => w.charAt(0).toUpperCase() + w.slice(1))
+        .join(' ');
+}
+/** The starter plan.md body, parameterized by the project's display name. */
+export function starterPlan(name) {
+    return `---
+name: ${name}
 ---
 
 # Project Plan
@@ -18,9 +31,19 @@ name: Project plan
 
 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');
+}
+/**
+ * Create constellation/ with a starter plan.md. Throws if it already exists.
+ * The project name defaults to a title-cased version of the target folder
+ * (so pyramid-server → "Pyramid Server"); pass opts.name to override it. The
+ * resolved name is returned so callers can echo / confirm it.
+ */
+export async function initPlan(targetDir, opts = {}) {
+    const resolvedTarget = path.resolve(targetDir);
+    const root = path.join(resolvedTarget, 'constellation');
+    const name = opts.name?.trim() ||
+        titleCaseFromSlug(path.basename(resolvedTarget)) ||
+        'Project plan';
     try {
         await access(root);
         throw new Error(`${root} already exists`);
@@ -30,7 +53,7 @@ export async function initPlan(targetDir) {
             throw err;
     }
     await mkdir(root, { recursive: true });
-    await writeFile(path.join(root, 'plan.md'), STARTER_PLAN, { flag: 'wx' });
-    return root;
+    await writeFile(path.join(root, 'plan.md'), starterPlan(name), { flag: 'wx' });
+    return { root, name };
 }
 //# sourceMappingURL=scaffold.js.map

package/dist/core/scaffold.js.map

@@ -1 +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"}
+{"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,8FAA8F;AAC9F,MAAM,UAAU,iBAAiB,CAAC,IAAY;IAC5C,OAAO,IAAI;SACR,OAAO,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC,yBAAyB;SAChD,OAAO,CAAC,oBAAoB,EAAE,OAAO,CAAC,CAAC,kBAAkB;SACzD,IAAI,EAAE;SACN,KAAK,CAAC,KAAK,CAAC;SACZ,MAAM,CAAC,OAAO,CAAC;SACf,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,WAAW,EAAE,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;SAClD,IAAI,CAAC,GAAG,CAAC,CAAC;AACf,CAAC;AAED,6EAA6E;AAC7E,MAAM,UAAU,WAAW,CAAC,IAAY;IACtC,OAAO;QACD,IAAI;;;;;;;;;;;;;;;;CAgBX,CAAC;AACF,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,QAAQ,CAC5B,SAAiB,EACjB,OAA0B,EAAE;IAE5B,MAAM,cAAc,GAAG,IAAI,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IAC/C,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,cAAc,EAAE,eAAe,CAAC,CAAC;IACxD,MAAM,IAAI,GACR,IAAI,CAAC,IAAI,EAAE,IAAI,EAAE;QACjB,iBAAiB,CAAC,IAAI,CAAC,QAAQ,CAAC,cAAc,CAAC,CAAC;QAChD,cAAc,CAAC;IACjB,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,WAAW,CAAC,IAAI,CAAC,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;IAC/E,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;AACxB,CAAC"}

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":"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"}

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;