@north-light/crouter 0.3.154

package/dist/commands/sys/sync-project-guidance.js

@@ -0,0 +1,345 @@
+// `crtr sys sync project-guidance` — one-way migration of a project's own
+// CLAUDE.md/AGENTS.md/.claude/rules into that SAME directory's OWN
+// `.crouter/memory/`, so the doc travels with the repo and gets positional
+// on-read for free. See `crtr memory read taste/document-substrate` for the
+// content-rung ruling this migration relies on.
+import { existsSync, readdirSync, realpathSync, statSync } from 'node:fs';
+import { basename, dirname, join, relative, resolve, sep } from 'node:path';
+import { defineLeaf } from '../../core/command.js';
+import { parseFrontmatterGeneric } from '../../core/frontmatter.js';
+import { gitSync } from '../../core/git.js';
+import { pathExists, readText, walkFiles, writeText } from '../../core/fs-utils.js';
+import { loadProfileManifest } from '../../core/profiles/manifest.js';
+import { CRTR_DIR_NAME } from '../../types.js';
+import { memoryFilePath, serializeMemoryDoc } from '../memory/shared.js';
+import { normalizedName, routeFromDescription, scalarString } from './sync-shared.js';
+// Directories a project-doc walk never descends into — build/dependency trees
+// plus crouter's own state dir.
+const PROJECT_DOC_JUNK_DIRS = new Set([
+    'node_modules', '.git', '.venv', 'venv', 'dist', 'build', '.next', '.cache', '.yalc', '.sisyphus', CRTR_DIR_NAME,
+]);
+// First-match-per-dir order mirrors pi's own loader (AGENTS.md wins over CLAUDE.md).
+const PROJECT_DOC_FILENAMES = ['AGENTS.md', 'CLAUDE.md'];
+/** Discovery roots for the project-doc walk: an explicit `--source` pins a
+ *  single dir; otherwise cwd plus (when a profile is selected) every project
+ *  in its purview — the same profile-widened idea `findProjectScopeRoots`
+ *  applies to the boot render, so one invocation can migrate a whole
+ *  workspace instead of one repo at a time. Deduped, cwd first; never throws
+ *  on a missing/unreadable profile (cwd-only fallback). */
+function projectDocRoots(sourceArg) {
+    if (sourceArg !== undefined)
+        return [resolve(sourceArg)];
+    const roots = [resolve(process.cwd())];
+    const profileId = process.env['CRTR_PROFILE_ID'];
+    if (profileId !== undefined && profileId !== '') {
+        try {
+            const { manifest } = loadProfileManifest(profileId);
+            for (const p of manifest.projects) {
+                const r = resolve(p);
+                if (!roots.includes(r))
+                    roots.push(r);
+            }
+        }
+        catch {
+            // No/unreadable profile — cwd-only root.
+        }
+    }
+    return roots;
+}
+/** Walk `root` (skipping PROJECT_DOC_JUNK_DIRS) collecting every dir's
+ *  CLAUDE.md/AGENTS.md (first match per dir) plus every `.claude/rules/*.md`.
+ *  Each result names the directory whose OWN `.crouter/memory/` it targets. */
+function collectProjectDocCandidates(root) {
+    const out = [];
+    if (!existsSync(root) || !statSync(root).isDirectory())
+        return out;
+    const rootResolved = resolve(root);
+    const stack = [rootResolved];
+    while (stack.length > 0) {
+        const dir = stack.pop();
+        for (const name of PROJECT_DOC_FILENAMES) {
+            const p = join(dir, name);
+            if (existsSync(p) && statSync(p).isFile()) {
+                out.push({ kind: 'agents', path: p, sourceDir: dir, walkRoot: rootResolved });
+                break;
+            }
+        }
+        const rulesDir = join(dir, '.claude', 'rules');
+        if (existsSync(rulesDir)) {
+            for (const file of walkFiles(rulesDir, (n) => n.endsWith('.md'))) {
+                out.push({ kind: 'rule', path: file, sourceDir: dir, walkRoot: rootResolved });
+            }
+        }
+        let entries;
+        try {
+            entries = readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        for (const e of entries) {
+            if (e.isDirectory() && !PROJECT_DOC_JUNK_DIRS.has(e.name))
+                stack.push(join(dir, e.name));
+        }
+    }
+    return out;
+}
+/** First non-empty line, heading markers stripped, truncated — the `short-form`
+ *  gist synthesized from a body with no frontmatter description to draw from. */
+function synthesizeShortForm(body) {
+    for (const raw of body.split('\n')) {
+        const cleaned = raw.replace(/^#+\s*/, '').replace(/\s+/g, ' ').trim();
+        if (cleaned !== '')
+            return cleaned.length > 200 ? `${cleaned.slice(0, 197)}...` : cleaned;
+    }
+    return 'Migrated project guidance.';
+}
+/** `.claude/rules` frontmatter `paths:` normalizes to a glob list — a single
+ *  string, an array, or absent (positional, unconditional rule). */
+function normalizeRulePaths(v) {
+    if (typeof v === 'string')
+        return v.trim() === '' ? [] : [v.trim()];
+    if (Array.isArray(v))
+        return v.filter((g) => typeof g === 'string' && g.trim() !== '');
+    return [];
+}
+/** The main repo root's directory name, found via `git rev-parse
+ *  --git-common-dir` — unlike `--show-toplevel`, this resolves through a
+ *  LINKED WORKTREE to the shared `.git` of the repo it belongs to, so a
+ *  canvas worktree checked out under a node-id path (e.g.
+ *  `.../worktrees/mr9vsbtn-ecd74d1b`) still resolves to the real project
+ *  name (`crouter`), not the worktree's own basename. Returns undefined when
+ *  `dir` isn't inside a git repo at all. */
+function gitRepoRootName(dir) {
+    const res = gitSync(['rev-parse', '--path-format=absolute', '--git-common-dir'], dir);
+    if (res.status !== 0)
+        return undefined;
+    const gitCommonDir = res.stdout.trim();
+    if (gitCommonDir === '')
+        return undefined;
+    return basename(dirname(gitCommonDir));
+}
+/** The current git worktree's OWN top-level directory (`git rev-parse
+ *  --show-toplevel`) — unlike `--git-common-dir` above, this does NOT resolve
+ *  through a linked worktree to the shared repo storage; it is the actual
+ *  checked-out tree containing `dir`. This is the stable root to compute a
+ *  doc's subdir suffix against, even when the discovery walk itself started
+ *  strictly inside that tree — e.g. `--source` pointed directly at a nested
+ *  package dir, so the walk root and the source dir are the same directory
+ *  and a walk-root-relative suffix would be empty. Returns undefined when
+ *  `dir` isn't inside a git working tree at all (the non-git fallback keeps
+ *  using the walk root itself). */
+function gitWorktreeRoot(dir) {
+    const res = gitSync(['rev-parse', '--path-format=absolute', '--show-toplevel'], dir);
+    if (res.status !== 0)
+        return undefined;
+    const top = res.stdout.trim();
+    return top === '' ? undefined : resolve(top);
+}
+/** `realpathSync`, tolerant of a path that doesn't exist or can't be resolved
+ *  (falls back to the path as given). */
+function realpathOrSelf(p) {
+    try {
+        return realpathSync(p);
+    }
+    catch {
+        return p;
+    }
+}
+/** First Markdown H1 heading in the doc body, heading marker stripped. */
+function h1Title(body) {
+    for (const raw of body.split('\n')) {
+        const m = raw.match(/^#\s+(.+)$/);
+        if (m) {
+            const title = m[1].replace(/\s+/g, ' ').trim();
+            if (title !== '')
+                return title;
+        }
+    }
+    return undefined;
+}
+/** Namespace label for a walk root: the raw basename of that directory is
+ *  unreliable (a worktree/canvas checkout's basename is a node id, not the
+ *  project name), so prefer the actual git repo's root dirname, then the root
+ *  doc's own H1 title if one exists there, then the raw basename. */
+function projectRootLabel(root) {
+    const gitLabel = gitRepoRootName(root);
+    if (gitLabel !== undefined)
+        return normalizedName(gitLabel);
+    for (const name of PROJECT_DOC_FILENAMES) {
+        const p = join(root, name);
+        if (existsSync(p) && statSync(p).isFile()) {
+            const title = h1Title(parseFrontmatterGeneric(readText(p)).body);
+            if (title !== undefined)
+                return normalizedName(title);
+        }
+    }
+    return normalizedName(basename(root) || root);
+}
+/** Explicit substrate identity for one migrated project doc: the root label
+ *  from the walk root (repo name/H1/basename), plus any relative subdir under
+ *  the STABLE SUFFIX ROOT. That suffix root is the git worktree top-level
+ *  when the source is git-backed, NOT the supplied walk root — so a
+ *  `--source` pointed directly at a nested subdir (walk root === source dir,
+ *  a walk-root-relative suffix would be empty) still gets a suffix relative
+ *  to the real project root and cannot collide with that root's own doc
+ *  identity. Non-git sources have no stable project root to prefer, so they
+ *  keep the walk-root fallback unchanged. Root AGENTS.md docs become
+ *  `crouter`/`hearth`-shaped identities while nested AGENTS.md docs get a
+ *  deterministic `root/subdir` name — regardless of whether the walk started
+ *  at that root or at the nested dir itself. */
+function projectDocLabel(candidate) {
+    const rootLabel = projectRootLabel(candidate.walkRoot);
+    const suffixRoot = gitWorktreeRoot(candidate.walkRoot) ?? candidate.walkRoot;
+    // `git rev-parse --show-toplevel` resolves through symlinks (e.g. macOS's
+    // /tmp -> /private/tmp); realpath BOTH sides before diffing so a symlinked
+    // walk root doesn't produce a bogus `../../..` suffix against the git-
+    // resolved top-level.
+    const relDir = relative(realpathOrSelf(suffixRoot), realpathOrSelf(candidate.sourceDir))
+        .split(sep)
+        .join('/')
+        .replace(/^\.$/, '');
+    return relDir === '' ? rootLabel : normalizedName(`${rootLabel}/${relDir}`);
+}
+/** AGENTS.md/CLAUDE.md → `<sourceDir>/.crouter/memory/AGENTS.md` at
+ *  content/content (the CTO's ruling, 2026-07-06: an AGENTS.md-style doc is
+ *  always-relevant AND wholly-important, so full-body at `content` is
+ *  sanctioned — see `taste/document-substrate`). The on-disk filename stays
+ *  `AGENTS.md`, but the substrate identity is the explicit project label so
+ *  sibling roots do not collapse on a shared `AGENTS` leaf. */
+function prepareAgentsCandidate(candidate) {
+    const body = parseFrontmatterGeneric(readText(candidate.path)).body;
+    const docLabel = projectDocLabel(candidate);
+    const frontmatter = {
+        kind: 'knowledge',
+        name: docLabel,
+        'when-and-why-to-read': `When working in ${docLabel}, this knowledge should be read because it is the project's operating guide.`,
+        'short-form': synthesizeShortForm(body),
+        'system-prompt-visibility': 'content',
+        'file-read-visibility': 'content',
+    };
+    return {
+        candidate,
+        name: docLabel,
+        target: memoryFilePath(join(candidate.sourceDir, CRTR_DIR_NAME, 'memory'), 'AGENTS'),
+        frontmatter,
+        body,
+    };
+}
+/** `.claude/rules/<name>.md` → `<sourceDir>/.crouter/memory/<name>.md`. A
+ *  `paths:` rule becomes an `applies-to` glob trigger at none/content; a
+ *  pathless rule is positional (surfaces like AGENTS.md on any read under its
+ *  own project scope) at the same none/content rungs. */
+function prepareRuleCandidate(candidate) {
+    const raw = readText(candidate.path);
+    const parsed = parseFrontmatterGeneric(raw);
+    const fm = parsed.data ?? {};
+    const name = normalizedName(basename(candidate.path));
+    const description = scalarString(fm['description']) ?? '';
+    const dirLabel = projectDocLabel(candidate);
+    const frontmatter = {
+        kind: 'knowledge',
+        'when-and-why-to-read': description !== ''
+            ? routeFromDescription(description, 'knowledge')
+            : `When working under ${dirLabel}, this knowledge should be read because it is migrated project rule guidance.`,
+        'short-form': description !== '' ? description.replace(/\s+/g, ' ').trim() : synthesizeShortForm(parsed.body),
+        'system-prompt-visibility': 'none',
+        'file-read-visibility': 'content',
+    };
+    const globs = normalizeRulePaths(fm['paths']);
+    if (globs.length > 0)
+        frontmatter['applies-to'] = globs;
+    return {
+        candidate,
+        name,
+        target: memoryFilePath(join(candidate.sourceDir, CRTR_DIR_NAME, 'memory'), name),
+        frontmatter,
+        body: parsed.body,
+    };
+}
+/** Write (or dry-run report) a prepared project doc — copy-not-move,
+ *  skip-existing unless `--overwrite`. */
+function convertProjectDoc(prepared, opts) {
+    if (pathExists(prepared.target) && !opts.overwrite) {
+        return {
+            source: prepared.candidate.path,
+            target: prepared.target,
+            name: prepared.name,
+            scope: 'project',
+            status: 'skipped',
+            reason: 'target memory doc already exists; re-run with --overwrite to replace it',
+        };
+    }
+    if (!opts.dryRun)
+        writeText(prepared.target, serializeMemoryDoc(prepared.frontmatter, prepared.body));
+    return {
+        source: prepared.candidate.path,
+        target: prepared.target,
+        name: prepared.name,
+        scope: 'project',
+        status: opts.dryRun ? 'would-import' : 'imported',
+    };
+}
+function renderSummary(results) {
+    const imported = results.filter((r) => r.status === 'imported').length;
+    const wouldImport = results.filter((r) => r.status === 'would-import').length;
+    const skipped = results.filter((r) => r.status === 'skipped').length;
+    const header = wouldImport > 0
+        ? `crtr sys sync project-guidance — dry run: ${wouldImport} would import, ${skipped} skipped`
+        : `crtr sys sync project-guidance — ${imported} imported, ${skipped} skipped`;
+    const rows = results.map((r) => {
+        const reason = r.reason ? ` (${r.reason})` : '';
+        return `| ${r.status} | ${r.scope}/${r.name || '—'} | ${r.target} | ${r.source}${reason} |`;
+    });
+    const body = rows.length === 0
+        ? ['No sync candidates.']
+        : ['| status | memory doc | target | source |', '| --- | --- | --- | --- |', ...rows];
+    return [header, '', ...body].join('\n');
+}
+export const sysSyncProjectGuidanceLeaf = defineLeaf({
+    name: 'project-guidance',
+    description: "migrate CLAUDE.md/AGENTS.md/.claude/rules into that directory's own crouter memory docs",
+    whenToUse: "migrating per-project CLAUDE.md/AGENTS.md/.claude/rules into the crouter memory-doc model: one-way copy into that same directory's OWN .crouter/memory/, so the doc travels with the repo and gets positional on-read for free. Never exports memory docs back to these files; crouter stops reading the originals unconditionally.",
+    help: {
+        name: 'sys sync project-guidance',
+        summary: "one-way migration: CLAUDE.md/AGENTS.md/.claude/rules → that dir's own crouter memory docs",
+        params: [
+            { kind: 'flag', name: 'source', type: 'string', required: false, constraint: "The root to walk recursively for CLAUDE.md/AGENTS.md/.claude/rules files. Default: cwd plus every project in the current profile's purview (when one is selected)." },
+            { kind: 'flag', name: 'dry-run', type: 'bool', required: false, constraint: 'Show what would be migrated without writing memory docs.' },
+            { kind: 'flag', name: 'overwrite', type: 'bool', required: false, constraint: 'Replace an existing target memory doc. Default: skip existing docs to avoid clobbering user-authored memory.' },
+        ],
+        output: [
+            { name: 'imported', type: 'number', required: true, constraint: 'Count of memory docs written.' },
+            { name: 'wouldImport', type: 'number', required: true, constraint: 'Count of memory docs that would be written under --dry-run.' },
+            { name: 'skipped', type: 'number', required: true, constraint: 'Count of source files skipped (existing target without --overwrite).' },
+            { name: 'results', type: 'object[]', required: true, constraint: 'Each: {source,target,name,scope,status,reason?}; status is one of imported, skipped, would-import.' },
+        ],
+        outputKind: 'object',
+        effects: [
+            "Copies each discovered CLAUDE.md/AGENTS.md into <dir>/.crouter/memory/AGENTS.md at system-prompt-visibility/file-read-visibility content/content, and each .claude/rules/*.md into <dir>/.crouter/memory/<name>.md at none/content (applies-to set from the rule's paths: globs when present) — copy, not move; original files are left untouched.",
+            'Skips existing memory docs unless --overwrite is present.',
+            'With --dry-run: read-only; writes nothing.',
+        ],
+    },
+    run: async (input) => {
+        const sourceArg = input['source'];
+        const dryRun = input['dryRun'] ?? false;
+        const overwrite = input['overwrite'] ?? false;
+        const results = [];
+        const docSeen = new Set();
+        for (const root of projectDocRoots(sourceArg)) {
+            for (const c of collectProjectDocCandidates(root)) {
+                if (docSeen.has(c.path))
+                    continue;
+                docSeen.add(c.path);
+                const prepared = c.kind === 'agents' ? prepareAgentsCandidate(c) : prepareRuleCandidate(c);
+                results.push(convertProjectDoc(prepared, { dryRun, overwrite }));
+            }
+        }
+        const imported = results.filter((r) => r.status === 'imported').length;
+        const wouldImport = results.filter((r) => r.status === 'would-import').length;
+        const skipped = results.filter((r) => r.status === 'skipped').length;
+        return { imported, wouldImport, skipped, results };
+    },
+    render: (result) => renderSummary(result.results),
+});

package/dist/commands/sys/sync-shared.d.ts

@@ -0,0 +1,7 @@
+export declare function scalarString(value: unknown): string | undefined;
+export declare function routeFromDescription(description: string, kind: string): string;
+/** Slugify a raw name/path segment into a memory-doc-safe identity: lowercase,
+ *  `.md` stripped, path separators normalized to `/`, each segment reduced to
+ *  `[a-z0-9._-]`. Shared by the skills lane (bundle names) and the
+ *  project-guidance lane (project/subdir labels). */
+export declare function normalizedName(raw: string): string;

package/dist/commands/sys/sync-shared.js

@@ -0,0 +1,49 @@
+// sync-shared.ts — pure helpers shared by all three `crtr sys sync` leaves
+// (skills, project-guidance, deps): frontmatter scalar coercion, routing-prose
+// synthesis, and memory-doc name normalization. No other dependencies, so this
+// module has no import direction to police.
+export function scalarString(value) {
+    if (typeof value === 'string')
+        return value;
+    if (typeof value === 'number' || typeof value === 'boolean')
+        return String(value);
+    return undefined;
+}
+function cleanClause(s) {
+    let out = s.replace(/\s+/g, ' ').trim();
+    out = out.replace(/^[,;:.\s]+/, '').replace(/[,;:.\s]+$/, '');
+    if (/^[A-Z][a-z]/.test(out))
+        out = out.charAt(0).toLowerCase() + out.slice(1);
+    return out;
+}
+const USE_WHEN_RE = /\b(?:use\s+this\s+skill\s+when|use\s+this\s+when|this\s+skill\s+should\s+be\s+used\s+when|used\s+when|use\s+when)\b\s*/i;
+export function routeFromDescription(description, kind) {
+    const desc = description.replace(/\s+/g, ' ').trim();
+    if (desc === '')
+        return `When this migrated ${kind} applies, this ${kind} should be read.`;
+    const m = desc.match(USE_WHEN_RE);
+    if (m && m.index !== undefined) {
+        const gist = cleanClause(desc.slice(0, m.index));
+        const situation = cleanClause(desc.slice(m.index + m[0].length));
+        if (situation !== '') {
+            let out = `When ${situation}, this ${kind} should be read`;
+            if (gist !== '')
+                out += ` because ${gist}`;
+            return `${out}.`;
+        }
+    }
+    return `When ${cleanClause(desc)}, this ${kind} should be read.`;
+}
+/** Slugify a raw name/path segment into a memory-doc-safe identity: lowercase,
+ *  `.md` stripped, path separators normalized to `/`, each segment reduced to
+ *  `[a-z0-9._-]`. Shared by the skills lane (bundle names) and the
+ *  project-guidance lane (project/subdir labels). */
+export function normalizedName(raw) {
+    const segments = raw
+        .replace(/\\/g, '/')
+        .replace(/\.md$/i, '')
+        .split('/')
+        .map((s) => s.trim().toLowerCase().replace(/[^a-z0-9._-]+/g, '-').replace(/^-+|-+$/g, ''))
+        .filter(Boolean);
+    return segments.join('/');
+}

package/dist/commands/sys/sync-skills.d.ts

@@ -0,0 +1 @@
+export declare const sysSyncSkillsLeaf: import("../../core/command.js").LeafDef;