@crouton-kit/crouter 0.3.18 → 0.3.19

package/dist/commands/memory/find.js

@@ -0,0 +1,180 @@
+import { defineLeaf } from '../../core/command.js';
+import { usage } from '../../core/errors.js';
+import { listAllMemoryDocs } from '../../core/memory-resolver.js';
+import { parseSubstrateDoc } from '../../core/substrate/index.js';
+import { listAllSkills } from '../../core/resolver.js';
+import { parseFrontmatter } from '../../core/frontmatter.js';
+import { readText } from '../../core/fs-utils.js';
+import { MEMORY_KINDS } from './shared.js';
+function substrateUnit(d) {
+    return {
+        name: d.name,
+        kind: d.kind,
+        scope: d.scope,
+        path: d.path,
+        when: d.when,
+        why: d.why,
+        shortForm: d.shortForm,
+        loadBody: () => d.body,
+    };
+}
+function skillUnit(s) {
+    const desc = s.frontmatter.description ?? '';
+    const keywords = s.frontmatter.keywords ? s.frontmatter.keywords.join(' ') : '';
+    return {
+        name: s.name,
+        kind: 'skill',
+        scope: s.scope,
+        path: s.path,
+        // A skill's description plays the when+why role; keywords ride along so the
+        // ranker weighs them too. short_form surfaces the description as the hook.
+        when: [desc, keywords].filter((x) => x).join(' '),
+        why: '',
+        shortForm: desc,
+        loadBody: () => parseFrontmatter(readText(s.path)).body,
+    };
+}
+/** The unioned candidate set: every substrate memory document + every skill,
+ *  optionally narrowed to one kind. find searches EVERYTHING — it never applies
+ *  gate or visibility-rung filtering (design §11#3). The skill half is wrapped
+ *  defensively: the skill corpus is parsed by the resolver, which currently
+ *  hard-throws on at least one shipped skill's frontmatter (a pre-existing
+ *  regression in the yaml-parser swap, owned by the frontmatter/skill track). A
+ *  broken skill corpus must degrade the union to substrate-docs-only, never
+ *  crash `memory find`.
+ *
+ *  Dedup by (scope, name): the substrate and skill-plugin corpora overlap
+ *  (builtin-memory/ contains migrated copies of builtin-skills/; a skill name
+ *  can also appear in multiple installed plugins at the same scope). The FIRST
+ *  unit encountered for a given identity wins — substrate docs before skill-plugin
+ *  docs, which mirrors the memory resolver's own precedence. */
+function candidates(kindFilter) {
+    const seen = new Set(); // "scope/name" → first wins
+    const add = (u) => {
+        const id = `${u.scope}/${u.name}`;
+        if (seen.has(id))
+            return;
+        seen.add(id);
+        units.push(u);
+    };
+    const units = [];
+    for (const doc of listAllMemoryDocs()) {
+        const sub = parseSubstrateDoc(doc);
+        if (sub === null)
+            continue;
+        if (kindFilter !== undefined && sub.kind !== kindFilter)
+            continue;
+        add(substrateUnit(sub));
+    }
+    if (kindFilter === undefined || kindFilter === 'skill') {
+        try {
+            for (const skill of listAllSkills())
+                add(skillUnit(skill));
+        }
+        catch {
+            /* skill corpus unavailable — search substrate documents alone */
+        }
+    }
+    return units;
+}
+export const findLeaf = defineLeaf({
+    name: 'find',
+    description: 'relevance search across memory documents',
+    whenToUse: 'you do not yet know which document applies and need to discover what is stored — ranks documents by relevance, weighted over name, when, why, and short-form (add --body to also weigh body text). Searches the full scope set regardless of any visibility gate. Use --grep instead when you need an exact regex or literal-string match across document bodies rather than a ranked topic match.',
+    help: {
+        name: 'memory find',
+        summary: 'relevance search across memory documents, weighted over name/when/why/short-form (and body with --body)',
+        params: [
+            { kind: 'positional', name: 'query', required: true, constraint: 'With ranked search (default): whitespace-separated terms, matched case-insensitively and weighted over name, when, why, and short-form (plus body with --body); documents matching more/stronger fields rank higher. With --grep: an ECMAScript regex applied to each document body line.' },
+            { kind: 'flag', name: 'kind', type: 'enum', choices: [...MEMORY_KINDS], required: false, constraint: 'Filter to a single kind. Default: all kinds.' },
+            { kind: 'flag', name: 'grep', type: 'bool', required: false, constraint: 'Treat the query as an ECMAScript regex and match it against document bodies, instead of weighted relevance ranking. Mutually exclusive with --body.' },
+            { kind: 'flag', name: 'body', type: 'bool', required: false, constraint: 'Also weigh document body text in the relevance ranking (in addition to name/when/why/short-form). Ignored under --grep, which always scans bodies.' },
+        ],
+        output: [
+            { name: 'query', type: 'string', required: true, constraint: 'Echo of the input query.' },
+            { name: 'hits', type: 'object[]', required: true, constraint: 'Ranked mode — each: {name, kind, scope, score, short_form}, sorted by score descending. Under --grep instead — each: {path, line, text} for every body line matching the regex, sorted by path then line ascending.' },
+            { name: 'follow_up', type: 'string', required: true, constraint: 'Concrete next commands for reading a hit in full or refining the search.' },
+        ],
+        outputKind: 'object',
+        effects: ['None. Read-only.'],
+    },
+    run: async (input) => {
+        const query = input['query'];
+        const kindFilter = input['kind'];
+        const grep = input['grep'];
+        const weighBody = input['body'];
+        if (grep && weighBody) {
+            throw usage('--grep and --body are mutually exclusive (--grep always scans bodies).');
+        }
+        const units = candidates(kindFilter);
+        // --- grep mode: regex over every unit's body, one row per matching line ---
+        if (grep) {
+            let regex;
+            try {
+                regex = new RegExp(query);
+            }
+            catch {
+                throw usage(`invalid regex pattern: ${query}`);
+            }
+            const matches = [];
+            for (const u of units) {
+                const lines = u.loadBody().split('\n');
+                lines.forEach((text, idx) => {
+                    if (regex.test(text))
+                        matches.push({ path: u.path, line: idx + 1, text });
+                });
+            }
+            matches.sort((a, b) => {
+                const pc = a.path.localeCompare(b.path);
+                return pc !== 0 ? pc : a.line - b.line;
+            });
+            return {
+                query,
+                hits: matches,
+                follow_up: 'Read a document in full with `crtr memory read <name>`. Drop --grep for a ranked topic search.',
+            };
+        }
+        // --- ranked mode: weighted relevance over name/when/why/short-form(+body) ---
+        const terms = query
+            .toLowerCase()
+            .split(/\s+/)
+            .filter((t) => t.length > 0);
+        if (terms.length === 0)
+            throw usage('query must contain at least one non-whitespace term');
+        const hits = [];
+        for (const u of units) {
+            const nameLc = u.name.toLowerCase();
+            const whenLc = u.when.toLowerCase();
+            const whyLc = u.why.toLowerCase();
+            const shortLc = u.shortForm.toLowerCase();
+            const bodyLc = weighBody ? u.loadBody().toLowerCase() : null;
+            let score = 0;
+            for (const term of terms) {
+                if (nameLc.includes(term))
+                    score += 10;
+                if (whenLc.includes(term))
+                    score += 5;
+                if (whyLc.includes(term))
+                    score += 4;
+                if (shortLc.includes(term))
+                    score += 3;
+                if (bodyLc !== null && bodyLc.includes(term))
+                    score += 1;
+            }
+            if (score > 0)
+                hits.push({ unit: u, score });
+        }
+        hits.sort((a, b) => b.score - a.score || a.unit.name.localeCompare(b.unit.name));
+        return {
+            query,
+            hits: hits.map((h) => ({
+                name: h.unit.name,
+                kind: h.unit.kind,
+                scope: h.unit.scope,
+                score: h.score,
+                short_form: h.unit.shortForm,
+            })),
+            follow_up: 'Read a hit in full with `crtr memory read <name>`. Add --body to weigh body text, or --grep for an exact regex.',
+        };
+    },
+});

package/dist/commands/memory/lint.d.ts

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

package/dist/commands/memory/lint.js

@@ -0,0 +1,140 @@
+// `crtr memory lint` — the permanent valid-YAML gate over the bounded corpus
+// (the CTO green-checkpoint: zero frontmatter parse errors at authoring time,
+// so an invalid doc fails HERE instead of being silently isolated at runtime).
+// Bounded corpus = the substrate memory dirs (project/user/builtin) +
+// every installed plugin's skills tree + ~/.claude/skills. Never a
+// filesystem-wide scan.
+import { homedir } from 'node:os';
+import { basename, join, relative, sep } from 'node:path';
+import { defineLeaf } from '../../core/command.js';
+import { general } from '../../core/errors.js';
+import { warn } from '../../core/output.js';
+import { pathExists, readText, walkFiles } from '../../core/fs-utils.js';
+import { parseFrontmatterGeneric } from '../../core/frontmatter.js';
+import { listAllPlugins } from '../../core/resolver.js';
+import { scopeMemoryDir } from '../../core/scope.js';
+import { isDocKind, RUNGS } from '../../core/substrate/index.js';
+import { SKILL_ENTRY_FILE, SKILLS_DIR } from '../../types.js';
+/** The parser normalizes the `always` alias to `content`, so it lints valid. */
+const VALID_RUNGS = [...RUNGS, 'always'];
+const RUNG_FIELDS = ['system-prompt-visibility', 'file-read-visibility'];
+/** Schema checks for a doc living in a substrate memory dir: a memory store
+ *  holds ONLY substrate docs, so a missing/invalid `kind` is an authoring
+ *  error here (elsewhere it just means "not a substrate doc"). Rung and gate
+ *  values are checked RAW — the runtime parser silently falls back to kind
+ *  defaults / inert gates, which is exactly the silent tolerance this lint
+ *  exists to catch at authoring time. */
+function lintSubstrateSchema(fm) {
+    if (fm === null)
+        return 'missing frontmatter: a memory store doc requires `kind: skill|reference|preference`';
+    if (!isDocKind(fm.kind)) {
+        return `invalid kind: ${JSON.stringify(fm.kind)} (expected skill|reference|preference)`;
+    }
+    for (const field of RUNG_FIELDS) {
+        const v = fm[field];
+        if (v !== undefined && (typeof v !== 'string' || !VALID_RUNGS.includes(v))) {
+            return `invalid ${field}: ${JSON.stringify(v)} (expected ${RUNGS.join('|')})`;
+        }
+    }
+    const gate = fm.gate;
+    if (gate !== undefined && (gate === null || typeof gate !== 'object' || Array.isArray(gate))) {
+        return `invalid gate: ${JSON.stringify(gate)} (expected a field→matcher object)`;
+    }
+    const appliesTo = fm['applies-to'];
+    if (appliesTo !== undefined &&
+        typeof appliesTo !== 'string' &&
+        !(Array.isArray(appliesTo) && appliesTo.every((g) => typeof g === 'string'))) {
+        return `invalid applies-to: ${JSON.stringify(appliesTo)} (expected a glob or glob list)`;
+    }
+    return null;
+}
+/** Strict-parse one file; push a finding on a YAML error, then run the
+ *  schema check when the file lives in a substrate store. */
+function lintFile(file, substrateStore, findings) {
+    let fm;
+    try {
+        fm = parseFrontmatterGeneric(readText(file)).data;
+    }
+    catch (e) {
+        const msg = (e instanceof Error ? e.message : String(e)).split('\n')[0];
+        findings.push({ path: file, error: `invalid YAML frontmatter: ${msg}` });
+        return;
+    }
+    if (!substrateStore)
+        return;
+    const schemaError = lintSubstrateSchema(fm);
+    if (schemaError !== null)
+        findings.push({ path: file, error: schemaError });
+}
+export const lintLeaf = defineLeaf({
+    name: 'lint',
+    description: 'validate frontmatter across the whole bounded document corpus',
+    whenToUse: 'you authored or migrated documents and want the authoring-time gate: strict-parse every doc in the bounded corpus (memory stores, plugin skills, ~/.claude/skills) and fail loudly on any invalid YAML or substrate schema violation. Run it before shipping doc changes; CI-friendly (non-zero exit on any finding).',
+    help: {
+        name: 'memory lint',
+        summary: 'strict-parse frontmatter across the bounded corpus; non-zero exit on any finding',
+        params: [],
+        output: [
+            { name: 'checked', type: 'number', required: true, constraint: 'Files linted across all corpora.' },
+            { name: 'corpora', type: 'object', required: true, constraint: 'Per-corpus file counts: {memory_stores, plugin_skills, claude_skills}.' },
+            { name: 'findings', type: 'object[]', required: true, constraint: 'One row per failure: {path, error}. Empty when green.' },
+        ],
+        outputKind: 'object',
+        effects: ['None. Read-only. Exits non-zero when any finding exists.'],
+    },
+    run: async () => {
+        const findings = [];
+        let memoryCount = 0;
+        let pluginCount = 0;
+        let claudeCount = 0;
+        // 1. Substrate memory stores (project/user/builtin), schema-aware.
+        //    MEMORY.md index files are not substrate docs — YAML-parse only.
+        for (const scope of ['project', 'user', 'builtin']) {
+            const dir = scopeMemoryDir(scope);
+            if (!dir || !pathExists(dir))
+                continue;
+            for (const file of walkFiles(dir, (n) => n.endsWith('.md'))) {
+                if (!relative(dir, file).split(sep).join('/'))
+                    continue;
+                memoryCount += 1;
+                lintFile(file, basename(file) !== 'MEMORY.md', findings);
+            }
+        }
+        // 2. Every installed plugin's skills tree (builtin + plugin + marketplace).
+        for (const plugin of listAllPlugins()) {
+            const skillsRoot = join(plugin.root, SKILLS_DIR);
+            if (!pathExists(skillsRoot))
+                continue;
+            for (const file of walkFiles(skillsRoot, (n) => n === SKILL_ENTRY_FILE)) {
+                pluginCount += 1;
+                lintFile(file, false, findings);
+            }
+        }
+        // 3. ~/.claude/skills — read by the runtime, so it lints too.
+        const claudeSkills = join(homedir(), '.claude', SKILLS_DIR);
+        if (pathExists(claudeSkills)) {
+            for (const file of walkFiles(claudeSkills, (n) => n === SKILL_ENTRY_FILE)) {
+                claudeCount += 1;
+                lintFile(file, false, findings);
+            }
+        }
+        const checked = memoryCount + pluginCount + claudeCount;
+        if (findings.length > 0) {
+            // Human/agent path renders only the message — surface every offender as
+            // a scoped stderr notice (the --json path carries them in details too).
+            for (const f of findings)
+                warn(`memory lint: ${f.path}: ${f.error}`);
+            throw general(`memory lint: ${findings.length} finding(s) across ${checked} files`, {
+                checked,
+                findings: findings.map((f) => ({ path: f.path, error: f.error })),
+                next: 'Fix each doc (quote YAML values containing `: `; use a valid kind/rung/gate), then re-run `crtr memory lint`.',
+            });
+        }
+        return {
+            checked,
+            corpora: { memory_stores: memoryCount, plugin_skills: pluginCount, claude_skills: claudeCount },
+            findings: [],
+            follow_up: 'Corpus green — zero invalid frontmatter docs.',
+        };
+    },
+});

package/dist/commands/memory/list.d.ts

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

package/dist/commands/memory/list.js

@@ -0,0 +1,79 @@
+import { defineLeaf } from '../../core/command.js';
+import { listAllMemoryDocs } from '../../core/memory-resolver.js';
+import { parseSubstrateDoc } from '../../core/substrate/index.js';
+import { listAllSkills } from '../../core/resolver.js';
+import { MEMORY_KINDS, MEMORY_SCOPES, scopeRank } from './shared.js';
+export const listLeaf = defineLeaf({
+    name: 'list',
+    description: 'inventory of stored memory documents',
+    whenToUse: 'browse everything stored — one line per document with its title, short-form hook, kind, and scope. This is the one surface that shows short-form. Reach for `crtr memory find` instead when you already have a topic or keyword in mind rather than wanting the whole inventory.',
+    help: {
+        name: 'memory list',
+        summary: 'inventory every memory document across the resolved scopes, one line each',
+        params: [
+            { kind: 'flag', name: 'kind', type: 'enum', choices: [...MEMORY_KINDS], required: false, constraint: 'Filter to a single kind. Default: all kinds.' },
+            { kind: 'flag', name: 'scope', type: 'enum', choices: [...MEMORY_SCOPES], required: false, constraint: 'Filter to a single scope. Default: all resolved scopes.' },
+        ],
+        output: [
+            { name: 'items', type: 'object[]', required: true, constraint: 'One row per document. Each: {name, title, short_form, kind, scope}. short_form is the abbreviated hook — shown here and nowhere else. Sorted by scope then kind then name ascending.' },
+            { name: 'follow_up', type: 'string', required: true, constraint: 'Concrete next commands — read a document in full or narrow the inventory.' },
+        ],
+        outputKind: 'object',
+        effects: ['None. Read-only.'],
+    },
+    run: async (input) => {
+        const kindFilter = input['kind'];
+        const scopeFilter = input['scope'];
+        const seen = new Set(); // "scope/name" → first wins
+        const items = [];
+        const addItem = (item) => {
+            const id = `${item.scope}/${item.name}`;
+            if (seen.has(id))
+                return;
+            seen.add(id);
+            items.push(item);
+        };
+        // Substrate memory docs (project > user > builtin precedence).
+        for (const doc of listAllMemoryDocs(scopeFilter)) {
+            const sub = parseSubstrateDoc(doc);
+            if (sub === null)
+                continue;
+            if (kindFilter !== undefined && sub.kind !== kindFilter)
+                continue;
+            addItem({ name: sub.name, kind: sub.kind, scope: sub.scope, shortForm: sub.shortForm });
+        }
+        // Skill-plugin corpus (scope-root skills + plugin/marketplace skills).
+        // Only include when the kindFilter is absent or explicitly 'skill'.
+        if (kindFilter === undefined || kindFilter === 'skill') {
+            try {
+                for (const skill of listAllSkills(scopeFilter)) {
+                    const raw = skill.frontmatter.description;
+                    const desc = typeof raw === 'string' ? raw : '';
+                    addItem({ name: skill.name, kind: 'skill', scope: skill.scope, shortForm: desc });
+                }
+            }
+            catch {
+                /* skill corpus unavailable — list substrate documents alone */
+            }
+        }
+        items.sort((a, b) => {
+            const sr = scopeRank(a.scope) - scopeRank(b.scope);
+            if (sr !== 0)
+                return sr;
+            const kc = a.kind.localeCompare(b.kind);
+            if (kc !== 0)
+                return kc;
+            return a.name.localeCompare(b.name);
+        });
+        return {
+            items: items.map((d) => ({
+                name: d.name,
+                title: d.name,
+                short_form: d.shortForm,
+                kind: d.kind,
+                scope: d.scope,
+            })),
+            follow_up: 'Read one in full with `crtr memory read <name>`. Narrow with --kind / --scope, or search a topic with `crtr memory find <query>`.',
+        };
+    },
+});

package/dist/commands/memory/read.js

@@ -0,0 +1,103 @@
+import { defineLeaf } from '../../core/command.js';
+import { CrtrError, notFound } from '../../core/errors.js';
+import { resolveMemoryDoc } from '../../core/memory-resolver.js';
+import { parseSubstrateDoc } from '../../core/substrate/index.js';
+import { resolveSkill } from '../../core/resolver.js';
+import { parseFrontmatter } from '../../core/frontmatter.js';
+import { readText } from '../../core/fs-utils.js';
+import { MEMORY_KINDS } from './shared.js';
+export const readLeaf = defineLeaf({
+    name: 'read',
+    description: 'load a memory document body by name',
+    whenToUse: 'a task in front of you matches a stored document and you already know its name — read it before improvising. Resolves the path-derived name across scopes by precedence (project > user > builtin), with leaf-name fallback like skills. You name the document by its crtr identifier, never a file path — do not cat or find the markdown off disk. Reach for `crtr memory find` first when you do not yet know which document applies.',
+    help: {
+        name: 'memory read',
+        summary: 'resolve a path-derived name to its document body, frontmatter stripped unless --frontmatter',
+        params: [
+            { kind: 'positional', name: 'name', required: true, constraint: 'Path-derived memory identifier (e.g. `topic` or `area/topic`). Resolved across scopes by precedence: project > user > builtin, with leaf-name fallback.' },
+            { kind: 'flag', name: 'kind', type: 'enum', choices: [...MEMORY_KINDS], required: false, constraint: 'Narrows resolution when the name is ambiguous across kinds.' },
+            { kind: 'flag', name: 'frontmatter', type: 'bool', required: false, constraint: 'When present, includes the YAML frontmatter in the returned body. Off by default — only the body is returned.' },
+        ],
+        output: [
+            { name: 'name', type: 'string', required: true, constraint: 'Resolved document name.' },
+            { name: 'kind', type: 'string', required: true, constraint: 'Resolved kind: skill, reference, or preference.' },
+            { name: 'scope', type: 'string', required: true, constraint: 'Scope the document was resolved from: project, user, or builtin.' },
+            { name: 'path', type: 'string', required: true, constraint: 'Absolute path to the document on disk.' },
+            { name: 'content', type: 'string', required: true, constraint: 'Document body. Frontmatter stripped unless --frontmatter is set.' },
+            { name: 'follow_up', type: 'string', required: true, constraint: 'Hints at variant flags or next commands.' },
+        ],
+        outputKind: 'object',
+        effects: ['None. Read-only.'],
+    },
+    run: async (input) => {
+        const nameRaw = input['name'];
+        const kindFilter = input['kind'];
+        const includeFrontmatter = input['frontmatter'];
+        // 1) Primary: resolve a substrate/memory document (memory/ dirs across
+        //    project>user>builtin). A not_found here is not fatal — it falls through
+        //    to the skill resolver below (the D4 union).
+        let doc;
+        try {
+            doc = resolveMemoryDoc(nameRaw);
+        }
+        catch (e) {
+            if (!(e instanceof CrtrError && e.code === 'not_found'))
+                throw e;
+        }
+        if (doc !== undefined) {
+            const sub = parseSubstrateDoc(doc);
+            const kind = sub !== null
+                ? sub.kind
+                : typeof doc.frontmatter?.['kind'] === 'string'
+                    ? doc.frontmatter['kind']
+                    : 'reference';
+            // --kind asserts the resolved kind; a mismatch falls through to skills
+            // (which only satisfy --kind=skill).
+            if (kindFilter === undefined || kind === kindFilter) {
+                const content = includeFrontmatter ? readText(doc.path) : doc.body;
+                return {
+                    name: doc.name,
+                    kind,
+                    scope: doc.scope,
+                    path: doc.path,
+                    content,
+                    follow_up: 'Add --frontmatter to include the YAML header. Browse the inventory with `crtr memory list`.',
+                };
+            }
+        }
+        // 2) D4 union fallthrough: the name is not a memory document (or its kind
+        //    did not match --kind) — resolve it as a plugin/marketplace/scope skill
+        //    so skills are readable through `crtr memory read` too. Skills are kind
+        //    "skill", so honor --kind by skipping this path for other kinds.
+        if (kindFilter === undefined || kindFilter === 'skill') {
+            let skill;
+            try {
+                skill = resolveSkill(nameRaw);
+            }
+            catch (e) {
+                // not_found → fall through to the memory-not-found below. A genuine
+                // CrtrError (e.g. ambiguous) propagates. Any other throw means the skill
+                // corpus is currently unparseable (the yaml-parser regression owned by
+                // the frontmatter/skill track) — degrade to not-found rather than 500.
+                if (e instanceof CrtrError && e.code !== 'not_found')
+                    throw e;
+            }
+            if (skill !== undefined) {
+                const raw = readText(skill.path);
+                const content = includeFrontmatter ? raw : parseFrontmatter(raw).body;
+                return {
+                    name: skill.name,
+                    kind: 'skill',
+                    scope: skill.scope,
+                    path: skill.path,
+                    content,
+                    follow_up: 'Add --frontmatter to include the YAML header. Browse the inventory with `crtr memory list`.',
+                };
+            }
+        }
+        throw notFound(`memory document not found: ${nameRaw}`, {
+            memory: nameRaw,
+            next: 'Run `crtr memory find <query>` to discover documents, or `crtr memory list` to browse the inventory.',
+        });
+    },
+});

package/dist/commands/memory/shared.d.ts

@@ -0,0 +1,30 @@
+import type { Scope } from '../../types.js';
+export declare const MEMORY_KINDS: readonly ["skill", "reference", "preference"];
+export declare const VISIBILITY_RUNGS: readonly ["none", "name", "preview", "content"];
+export declare const MEMORY_SCOPES: readonly ["user", "project"];
+/** Scope sort weight matching resolution precedence (project > user > builtin).
+ *  Used by `list` for its "scope then kind then name" ordering. */
+export declare function scopeRank(scope: Scope): number;
+/** Resolve the write target scope + its memory dir. Default: project when a
+ *  project scope exists for the cwd, else user. An explicit `--scope project`
+ *  with no project scope yet scaffolds one (ensureProjectScopeRoot). User scope
+ *  always resolves. Returns the absolute `<root>/memory` dir to write under. */
+export declare function resolveWriteTarget(scopeArg: string | undefined): {
+    scope: Scope;
+    memoryDir: string;
+};
+/** Map a path-derived name (`topic` or `area/topic`) to its file path under a
+ *  memory dir, guarding against traversal/absolute escapes. */
+export declare function memoryFilePath(memoryDir: string, name: string): string;
+export declare function coerceGate(raw: string): Record<string, unknown>;
+/** Coerce a `--applies-to` string to the schema's glob form: a comma-separated
+ *  list becomes an array, a single glob stays a string. */
+export declare function coerceAppliesTo(raw: string): unknown;
+/** Serialize a substrate frontmatter record + body into a complete `.md`
+ *  document. Frontmatter is emitted as a `---` fenced YAML block (the `yaml`
+ *  package — the same one the parser uses — so nested gate maps and applies-to
+ *  arrays round-trip), in canonical field order with preserved extras last. The
+ *  skill-shaped `serializeFrontmatter` in core can only represent
+ *  name/description/type/keywords, so it cannot carry the substrate fields —
+ *  hence this focused serializer. */
+export declare function serializeMemoryDoc(frontmatter: Record<string, unknown>, body: string): string;

package/dist/commands/memory/shared.js

@@ -0,0 +1,122 @@
+// Shared constants + helpers for the `crtr memory` command family (task B2).
+// The leaf handlers (list/read/find/write) consume the resolver, substrate
+// schema, scope, and skill-resolver modules and build their documented output
+// objects on top of the small helpers here. Nothing in this file forks on kind
+// or re-implements the schema/gate/resolver — it only composes them.
+import { join } from 'node:path';
+import { stringify as yamlStringify, parse as yamlParse } from 'yaml';
+import { usage } from '../../core/errors.js';
+import { scopeMemoryDir, projectScopeRoot, ensureProjectScopeRoot, } from '../../core/scope.js';
+// The three memory kinds — procedural (skill), referential (reference),
+// preferential (preference). Used as the `--kind` enum choices everywhere.
+export const MEMORY_KINDS = ['skill', 'reference', 'preference'];
+// Visibility rungs — how much of a document surfaces (none → name → preview →
+// content). Shared by --system-prompt-visibility and --file-read-visibility.
+export const VISIBILITY_RUNGS = ['none', 'name', 'preview', 'content'];
+// Scope choices for filtering / targeting (builtin is read-only, not writable).
+export const MEMORY_SCOPES = ['user', 'project'];
+/** Scope sort weight matching resolution precedence (project > user > builtin).
+ *  Used by `list` for its "scope then kind then name" ordering. */
+export function scopeRank(scope) {
+    return scope === 'project' ? 0 : scope === 'user' ? 1 : 2;
+}
+/** Resolve the write target scope + its memory dir. Default: project when a
+ *  project scope exists for the cwd, else user. An explicit `--scope project`
+ *  with no project scope yet scaffolds one (ensureProjectScopeRoot). User scope
+ *  always resolves. Returns the absolute `<root>/memory` dir to write under. */
+export function resolveWriteTarget(scopeArg) {
+    let scope;
+    if (scopeArg === 'user' || scopeArg === 'project') {
+        scope = scopeArg;
+    }
+    else if (scopeArg !== undefined) {
+        throw usage(`invalid --scope: ${scopeArg} (expected user|project)`);
+    }
+    else {
+        scope = projectScopeRoot() !== null ? 'project' : 'user';
+    }
+    let memoryDir = scopeMemoryDir(scope);
+    if (!memoryDir && scope === 'project') {
+        // Explicit --scope project with no project root yet → scaffold it.
+        memoryDir = join(ensureProjectScopeRoot(), 'memory');
+    }
+    if (!memoryDir)
+        throw usage(`no ${scope} scope available for writing memory documents`);
+    return { scope, memoryDir };
+}
+/** Map a path-derived name (`topic` or `area/topic`) to its file path under a
+ *  memory dir, guarding against traversal/absolute escapes. */
+export function memoryFilePath(memoryDir, name) {
+    const segments = name.split('/').filter((s) => s.length > 0);
+    if (segments.length === 0)
+        throw usage('memory document name required');
+    if (segments.some((s) => s === '.' || s === '..')) {
+        throw usage(`invalid memory document name: ${name}`);
+    }
+    return join(memoryDir, ...segments) + '.md';
+}
+/** Coerce a `--gate` string into a predicate tree. The gate field MUST be a
+ *  YAML/JSON object (the field→matcher map the schema expects). Throws a usage
+ *  error when the input fails to parse or does not parse to a non-null,
+ *  non-array object — a scalar or array gate silently makes a doc never-eligible
+ *  (the matcher engine ignores non-object predicates), so passing one is always
+ *  a mistake and must be caught at authoring time rather than stored. */
+function parseYamlObject(raw) {
+    const parsed = yamlParse(raw);
+    if (parsed !== null && typeof parsed === 'object' && !Array.isArray(parsed)) {
+        return parsed;
+    }
+    return `expected an object, got ${JSON.stringify(parsed)}`;
+}
+export function coerceGate(raw) {
+    const result = parseYamlObject(raw);
+    if (typeof result === 'string') {
+        throw usage(`--gate must be a YAML/JSON object (field→matcher map): ${result}. ` +
+            `Example: --gate '{kind: design}' or --gate '{orchestration.depth: {gte: 2}}'`);
+    }
+    return result;
+}
+/** Coerce a `--applies-to` string to the schema's glob form: a comma-separated
+ *  list becomes an array, a single glob stays a string. */
+export function coerceAppliesTo(raw) {
+    const parts = raw
+        .split(',')
+        .map((s) => s.trim())
+        .filter((s) => s.length > 0);
+    if (parts.length === 0)
+        return raw;
+    return parts.length === 1 ? parts[0] : parts;
+}
+// Canonical frontmatter field order for a substrate document. Known fields come
+// first in this order; any preserved-on-update extras append after.
+const FRONTMATTER_ORDER = [
+    'kind',
+    'when',
+    'why',
+    'short-form',
+    'system-prompt-visibility',
+    'file-read-visibility',
+    'gate',
+    'applies-to',
+];
+/** Serialize a substrate frontmatter record + body into a complete `.md`
+ *  document. Frontmatter is emitted as a `---` fenced YAML block (the `yaml`
+ *  package — the same one the parser uses — so nested gate maps and applies-to
+ *  arrays round-trip), in canonical field order with preserved extras last. The
+ *  skill-shaped `serializeFrontmatter` in core can only represent
+ *  name/description/type/keywords, so it cannot carry the substrate fields —
+ *  hence this focused serializer. */
+export function serializeMemoryDoc(frontmatter, body) {
+    const ordered = {};
+    for (const key of FRONTMATTER_ORDER) {
+        if (frontmatter[key] !== undefined)
+            ordered[key] = frontmatter[key];
+    }
+    for (const key of Object.keys(frontmatter)) {
+        if (!(key in ordered) && frontmatter[key] !== undefined)
+            ordered[key] = frontmatter[key];
+    }
+    const yamlText = yamlStringify(ordered).replace(/\n+$/, '');
+    const cleanBody = body.replace(/^\n+/, '').replace(/\s+$/, '');
+    return `---\n${yamlText}\n---\n\n${cleanBody}\n`;
+}