@north-light/crouter 0.3.227 → 0.3.229

package/dist/migrations/__tests__/deletion-and-root-declaration.test.js

@@ -0,0 +1,149 @@
+import assert from 'node:assert/strict';
+import { existsSync, mkdtempSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import test from 'node:test';
+import { runConvergentMigrations } from '../convergent.js';
+import { runCorpusMigrations } from '../corpus.js';
+function inTemp(run) {
+    const root = mkdtempSync(join(tmpdir(), 'crtr-migration-deletion-'));
+    try {
+        run(root);
+    }
+    finally {
+        rmSync(root, { recursive: true, force: true });
+    }
+}
+function plan(overrides = {}) {
+    return {
+        blockers: [],
+        consumers: [],
+        identities: [],
+        repositories: [],
+        storePrefixes: [],
+        renames: [],
+        references: [],
+        ...overrides,
+    };
+}
+function corpus(storeRoot, docs) {
+    return {
+        stores: [{
+                key: storeRoot,
+                descriptor: { scope: 'project', storeRoot, namespace: '', mountStatus: 'ready', projectMemory: 'memory' },
+                snapshot: { root: storeRoot, docs },
+                discovery: [],
+                targets: [],
+                writable: true,
+            }],
+        targets: [],
+        roots: [],
+        store: () => undefined,
+        storesForTarget: () => [],
+    };
+}
+function doc(path, relPath, source) {
+    return { path, relPath, source, frontmatter: null, body: source };
+}
+test('convergent deletion folds dry runs without writing, writes real deletions, and skips absent paths', () => {
+    inTemp((root) => {
+        const target = join(root, 'obsolete.md');
+        const absent = join(root, 'already-gone.md');
+        writeFileSync(target, '# obsolete\n');
+        const migration = {
+            id: 'delete',
+            lane: 'convergent',
+            description: 'delete obsolete docs',
+            apply: () => [{ path: target, after: null }, { path: absent, after: null }],
+        };
+        const dry = runConvergentMigrations(root, { dryRun: true, migrations: [migration] });
+        assert.deepEqual(dry.applied, [{ migration: migration.description, files: [target] }]);
+        assert.deepEqual(dry.snapshot.docs, []);
+        assert.equal(existsSync(target), true);
+        const wrote = runConvergentMigrations(root, { migrations: [migration] });
+        assert.deepEqual(wrote.applied, [{ migration: migration.description, files: [target] }]);
+        assert.equal(existsSync(target), false);
+    });
+});
+test('corpus deletion folds before later migration plans and leaves dry-run disk bytes untouched', () => {
+    inTemp((root) => {
+        const storeRoot = join(root, 'child', '.crouter', 'memory');
+        const target = join(storeRoot, 'obsolete.md');
+        mkdirSync(storeRoot, { recursive: true });
+        writeFileSync(target, '# obsolete\n');
+        let laterSaw;
+        const deletion = {
+            id: 'delete',
+            lane: 'corpus',
+            description: 'delete obsolete docs',
+            plan: () => plan({ identities: [{ path: target, after: null }] }),
+        };
+        const observer = {
+            id: 'observe',
+            lane: 'corpus',
+            description: 'observe folded deletion',
+            plan: (working) => {
+                laterSaw = working.stores[0]?.snapshot.docs.length;
+                return plan();
+            },
+        };
+        const input = corpus(storeRoot, [doc(target, 'obsolete.md', '# obsolete\n')]);
+        const dry = runCorpusMigrations(input, { dryRun: true, migrations: [deletion, observer] });
+        assert.equal(laterSaw, 0);
+        assert.deepEqual(dry.wrote.identities, [target]);
+        assert.equal(readFileSync(target, 'utf8'), '# obsolete\n');
+        runCorpusMigrations(input, { migrations: [deletion] });
+        assert.equal(existsSync(target), false);
+    });
+});
+test('corpus permits a plan-authorized repository-root declaration outside discovered stores', () => {
+    inTemp((repositoryRoot) => {
+        const descendantStore = join(repositoryRoot, 'packages', 'tool', '.crouter', 'memory');
+        const declarationPath = join(repositoryRoot, '.crouter', 'memory', 'INDEX.md');
+        mkdirSync(descendantStore, { recursive: true });
+        const migration = {
+            id: 'create-root-declaration',
+            lane: 'corpus',
+            description: 'create root declaration',
+            plan: () => plan({
+                identities: [{ path: declarationPath, after: '# root declaration\n' }],
+                repositories: [{
+                        repositoryRoot,
+                        repositoryKey: 'repository',
+                        declarationPath,
+                        namespace: 'repository',
+                        source: 'declared',
+                        action: 'created',
+                    }],
+            }),
+        };
+        runCorpusMigrations(corpus(descendantStore, []), { migrations: [migration] });
+        assert.equal(readFileSync(declarationPath, 'utf8'), '# root declaration\n');
+    });
+});
+test('corpus rejects every outside-store path other than the plan declaration path', () => {
+    inTemp((repositoryRoot) => {
+        const descendantStore = join(repositoryRoot, 'packages', 'tool', '.crouter', 'memory');
+        const declarationPath = join(repositoryRoot, '.crouter', 'memory', 'INDEX.md');
+        const otherPath = join(repositoryRoot, '.crouter', 'memory', 'other.md');
+        mkdirSync(descendantStore, { recursive: true });
+        const migration = {
+            id: 'reject-other-outside-path',
+            lane: 'corpus',
+            description: 'reject other outside path',
+            plan: () => plan({
+                identities: [{ path: otherPath, after: '# not authorized\n' }],
+                repositories: [{
+                        repositoryRoot,
+                        repositoryKey: 'repository',
+                        declarationPath,
+                        namespace: 'repository',
+                        source: 'declared',
+                        action: 'created',
+                    }],
+            }),
+        };
+        assert.throws(() => runCorpusMigrations(corpus(descendantStore, []), { migrations: [migration] }), new RegExp(`outside every discovered store: ${otherPath}`));
+        assert.equal(existsSync(otherPath), false);
+    });
+});

package/dist/migrations/activation.d.ts

@@ -0,0 +1,16 @@
+import { runOnDiskMigrations, type OnDiskMigrationRunResult } from './runner.js';
+export type OnDiskMigrationRunner = typeof runOnDiskMigrations;
+interface CoordinationOptions {
+    timeoutMs?: number;
+    runner?: OnDiskMigrationRunner;
+}
+export interface ForcedMigrationOptions extends CoordinationOptions {
+    dryRun?: boolean;
+    explicitDirs?: readonly string[];
+}
+/** Run startup migration only when this home lacks the current completion marker. */
+export declare function activateOnDiskMigrations(options?: CoordinationOptions): Promise<OnDiskMigrationRunResult | null>;
+export declare function ensureOnDiskMigrations(): Promise<void>;
+/** Run migrations regardless of the marker; dry runs leave marker state untouched. */
+export declare function runForcedOnDiskMigrations(options: ForcedMigrationOptions): Promise<OnDiskMigrationRunResult>;
+export {};

package/dist/migrations/activation.js

@@ -0,0 +1,78 @@
+import { mkdirSync, rmSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { onDiskMigrationLockPath, onDiskMigrationMarkerPath } from '../core/canvas/paths.js';
+import { withExclusiveDirectoryLockAsync } from '../core/exclusive-lock.js';
+import { DAEMON_STARTUP_WINDOW_MS } from '../daemon/startup-policy.js';
+import { atomicWriteJson, readJsonOrNull } from '../core/fs-utils.js';
+import { onDiskMigrationIdentity } from './registry.js';
+import { runOnDiskMigrations } from './runner.js';
+function markerIsCurrent() {
+    const stored = readJsonOrNull(onDiskMigrationMarkerPath());
+    return JSON.stringify(stored) === JSON.stringify(onDiskMigrationIdentity());
+}
+function writeCurrentMarker() {
+    atomicWriteJson(onDiskMigrationMarkerPath(), onDiskMigrationIdentity());
+}
+function blockerPaths(result) {
+    return [...new Set(result.blockers.flatMap((blocker) => [
+            ...(blocker.path === undefined ? [] : [blocker.path]),
+            ...(blocker.paths ?? []),
+            ...(blocker.storeRoot === undefined ? [] : [blocker.storeRoot]),
+        ]))];
+}
+function activationError(result) {
+    const paths = blockerPaths(result);
+    const findings = result.blockers.map((blocker) => `${blocker.kind}: ${blocker.message}`);
+    const writes = [
+        ...result.wrote.profileManifests,
+        ...result.wrote.documents,
+        ...result.wrote.corpusConsumers,
+        ...result.wrote.corpusIdentities,
+    ];
+    const lines = result.blockers.length > 0
+        ? [`on-disk migration blocked by ${result.blockers.length} finding(s)`, ...findings]
+        : ['on-disk migration did not complete final verification'];
+    if (paths.length > 0)
+        lines.push(`Blocker paths: ${paths.join(', ')}`);
+    if (writes.length > 0)
+        lines.push(`Writes completed before failure: ${writes.join(', ')}`);
+    lines.push('Repair: crtr sys migrate');
+    return new Error(lines.join('\n'));
+}
+async function coordinate(mode, options) {
+    const lockPath = onDiskMigrationLockPath();
+    mkdirSync(dirname(lockPath), { recursive: true, mode: 0o700 });
+    return withExclusiveDirectoryLockAsync(lockPath, async () => {
+        if (mode === 'activation' && markerIsCurrent())
+            return null;
+        const dryRun = options.dryRun === true;
+        if (!dryRun)
+            rmSync(onDiskMigrationMarkerPath(), { force: true });
+        const result = await (options.runner ?? runOnDiskMigrations)({
+            dryRun,
+            explicitDirs: options.explicitDirs,
+        });
+        if (!dryRun && result.finalVerificationSucceeded)
+            writeCurrentMarker();
+        if (mode === 'activation' && !result.finalVerificationSucceeded)
+            throw activationError(result);
+        return result;
+    }, {
+        timeoutMs: options.timeoutMs ?? DAEMON_STARTUP_WINDOW_MS,
+        timeoutError: () => new Error(`timed out waiting for on-disk migration lock: ${lockPath}`),
+    });
+}
+/** Run startup migration only when this home lacks the current completion marker. */
+export async function activateOnDiskMigrations(options = {}) {
+    return coordinate('activation', options);
+}
+export async function ensureOnDiskMigrations() {
+    await activateOnDiskMigrations();
+}
+/** Run migrations regardless of the marker; dry runs leave marker state untouched. */
+export async function runForcedOnDiskMigrations(options) {
+    const result = await coordinate('forced', options);
+    if (result === null)
+        throw new Error('forced on-disk migration unexpectedly skipped');
+    return result;
+}

package/dist/migrations/convergent.d.ts

@@ -1,4 +1,4 @@
-import type { ConvergentMigrationContext, StateMigration, StoreSnapshot } from './types.js';
+import type { DocChange, StateMigration, StoreSnapshot } from './types.js';
 /** A doc excluded from the snapshot because its frontmatter is not valid YAML.
  *  Per-doc throw isolation at the collection layer: the bad file is named and
  *  the rest of the store still migrates. */
@@ -14,13 +14,25 @@ export interface ConvergentRunResult {
         files: string[];
     }[];
     skipped: SkippedDoc[];
+    /** The store's docs with every planned change folded in — the bytes on disk
+     *  after a write run, and the bytes a write run WOULD have produced under
+     *  `--dry-run`. What the corpus lane plans against. */
+    snapshot: StoreSnapshot;
 }
 /** Snapshot every parseable `.md` under `root` (hidden dirs — `.history`
- *  sidecars and the like — skipped, mirroring substrate doc enumeration). */
+ *  sidecars and the like — skipped, mirroring substrate doc enumeration).
+ *  `SKILL.md` bundles are Agent Skills, not memory docs: they carry no
+ *  canonical identity and are never rewritten. */
 export declare function loadStoreSnapshot(root: string): {
     snapshot: StoreSnapshot;
     skipped: SkippedDoc[];
 };
+/** Fold one applied change back into the in-memory snapshot so the NEXT
+ *  migration plans against post-change state (dry runs included — that is what
+ *  makes a dry-run diff equal the real run's writes). A migration that emits
+ *  invalid YAML is a defect and throws here, before anything else compounds
+ *  on its output. */
+export declare function foldDocChange(snapshot: StoreSnapshot, change: DocChange): void;
 /** Run every registered convergent migration over the store at `root`, in
  *  registry order. No-op changes (identical text) are filtered; each real
  *  change is written atomically unless `dryRun`. Journaled migrations in the
@@ -28,5 +40,4 @@ export declare function loadStoreSnapshot(root: string): {
 export declare function runConvergentMigrations(root: string, opts?: {
     dryRun?: boolean;
     migrations?: readonly StateMigration[];
-    context?: ConvergentMigrationContext;
 }): ConvergentRunResult;

package/dist/migrations/convergent.js

@@ -4,7 +4,7 @@
 // whatever still matches an old shape, so a doc that arrives later (sync,
 // restore, hand-edit) is caught by the next run.
 import { relative, sep } from 'node:path';
-import { atomicWriteText, readText, walkFiles } from '../core/fs-utils.js';
+import { atomicWriteText, readText, removePath, walkFiles } from '../core/fs-utils.js';
 import { parseFrontmatterGeneric } from '../core/frontmatter.js';
 import { STATE_MIGRATIONS } from './registry.js';
 function parseDoc(root, file) {
@@ -19,11 +19,13 @@ function parseDoc(root, file) {
     }
 }
 /** Snapshot every parseable `.md` under `root` (hidden dirs — `.history`
- *  sidecars and the like — skipped, mirroring substrate doc enumeration). */
+ *  sidecars and the like — skipped, mirroring substrate doc enumeration).
+ *  `SKILL.md` bundles are Agent Skills, not memory docs: they carry no
+ *  canonical identity and are never rewritten. */
 export function loadStoreSnapshot(root) {
     const docs = [];
     const skipped = [];
-    for (const file of walkFiles(root, (n) => n.endsWith('.md'), (d) => d.startsWith('.'))) {
+    for (const file of walkFiles(root, (n) => n.endsWith('.md') && n !== 'SKILL.md', (d) => d.startsWith('.'))) {
         const parsed = parseDoc(root, file);
         if ('doc' in parsed)
             docs.push(parsed.doc);
@@ -37,11 +39,16 @@ export function loadStoreSnapshot(root) {
  *  makes a dry-run diff equal the real run's writes). A migration that emits
  *  invalid YAML is a defect and throws here, before anything else compounds
  *  on its output. */
-function refreshDoc(snapshot, change) {
+export function foldDocChange(snapshot, change) {
+    const i = snapshot.docs.findIndex((d) => d.path === change.path);
+    if (change.after === null) {
+        if (i >= 0)
+            snapshot.docs.splice(i, 1);
+        return;
+    }
     const relPath = relative(snapshot.root, change.path).split(sep).join('/');
     const { data, body } = parseFrontmatterGeneric(change.after);
     const doc = { path: change.path, relPath, source: change.after, frontmatter: data, body };
-    const i = snapshot.docs.findIndex((d) => d.path === change.path);
     if (i >= 0)
         snapshot.docs[i] = doc;
     else
@@ -57,15 +64,19 @@ export function runConvergentMigrations(root, opts = {}) {
     const applied = [];
     for (const migration of migrations) {
         const bySource = new Map(snapshot.docs.map((d) => [d.path, d.source]));
-        const changes = migration.apply(snapshot, opts.context).filter((c) => bySource.get(c.path) !== c.after);
+        const changes = migration.apply(snapshot).filter((change) => change.after === null ? bySource.has(change.path) : bySource.get(change.path) !== change.after);
         if (changes.length === 0)
             continue;
         for (const change of changes) {
-            if (opts.dryRun !== true)
-                atomicWriteText(change.path, change.after);
-            refreshDoc(snapshot, change);
+            if (opts.dryRun !== true) {
+                if (change.after === null)
+                    removePath(change.path);
+                else
+                    atomicWriteText(change.path, change.after);
+            }
+            foldDocChange(snapshot, change);
         }
         applied.push({ migration: migration.description, files: changes.map((c) => c.path) });
     }
-    return { root, applied, skipped };
+    return { root, applied, skipped, snapshot };
 }

package/dist/migrations/corpus.d.ts

@@ -0,0 +1,78 @@
+import type { CorpusBlocker, CorpusDiscoveryRoot, CorpusIdentityRename, CorpusReferenceRewrite, CorpusRepositoryDecision, CorpusSnapshot, CorpusStore, CorpusStorePrefix, CorpusTarget, ProfileManifestSnapshot, StateMigration, StoreSnapshot } from './types.js';
+/** A store before its documents are read. */
+export type DiscoveredStore = Omit<CorpusStore, 'snapshot'>;
+export interface CorpusDiscovery {
+    /** Every place discovery looked, in the order it looked. */
+    roots: CorpusDiscoveryRoot[];
+    /** Deduped by realpath, in discovery order. Stores whose directory does not
+     *  exist are absent: there is nothing to migrate and nothing to point at. */
+    stores: DiscoveredStore[];
+    targets: CorpusTarget[];
+    /** Roots and targets discovery could not read. */
+    blockers: CorpusBlocker[];
+    nodeMetadata: {
+        available: boolean;
+        nodes: number;
+        error?: string;
+    };
+}
+export interface CorpusSkippedDoc {
+    storeRoot: string;
+    relPath: string;
+    error: string;
+}
+export interface CorpusRunResult {
+    /** Corpus migrations in the registry. Zero means the lane is inert. */
+    migrations: number;
+    /** True when blockers exist and a corpus migration was registered to gate. */
+    blocked: boolean;
+    blockers: CorpusBlocker[];
+    planned: {
+        migration: string;
+        consumers: string[];
+        identities: string[];
+    }[];
+    repositories: CorpusRepositoryDecision[];
+    storePrefixes: CorpusStorePrefix[];
+    renames: CorpusIdentityRename[];
+    references: CorpusReferenceRewrite[];
+    /** Files written, or under `--dry-run` the files that would be written. */
+    wrote: {
+        consumers: string[];
+        identities: string[];
+    };
+    /** True when the post-write rebuild ran every migration's `verify`. */
+    verified: boolean;
+}
+/** Discover the whole reachable corpus: every store, the targets that mount
+ *  them, and the frontier searched to find them. `profiles` are the manifest
+ *  lane's post-migration snapshots — a pre-migration manifest reads as corrupt,
+ *  so discovery must run after that lane, not against `listProfiles()`. */
+export declare function discoverCorpus(opts: {
+    cwd?: string;
+    profiles: readonly ProfileManifestSnapshot[];
+    explicitDirs?: readonly string[];
+}): Promise<CorpusDiscovery>;
+/** Read every discovered store's documents. `preloaded` supplies the per-store
+ *  convergent lane's FOLDED snapshots so the corpus plans against the bytes a
+ *  write run leaves behind — identical under `--dry-run`, where the same fold
+ *  ran and nothing was written. */
+export declare function loadCorpusSnapshots(discovery: CorpusDiscovery, opts?: {
+    preloaded?: ReadonlyMap<string, StoreSnapshot>;
+}): {
+    snapshots: Map<string, StoreSnapshot>;
+    skipped: CorpusSkippedDoc[];
+};
+export declare function parseFailureBlockers(skipped: readonly CorpusSkippedDoc[]): CorpusBlocker[];
+export declare function buildCorpusSnapshot(discovery: CorpusDiscovery, snapshots: ReadonlyMap<string, StoreSnapshot>): CorpusSnapshot;
+/** Plan every corpus migration over the whole corpus, then — only when the
+ *  global plan is blocker-free — write every migration's consumer rewrites
+ *  before any identity rewrite. `rebuild` re-reads the corpus from file truth
+ *  for the post-write `verify` pass. */
+export declare function runCorpusMigrations(corpus: CorpusSnapshot, opts?: {
+    dryRun?: boolean;
+    migrations?: readonly StateMigration[];
+    /** Discovery and parse-failure blockers, gating identically to plan ones. */
+    blockers?: readonly CorpusBlocker[];
+    rebuild?: () => CorpusSnapshot;
+}): CorpusRunResult;