@crouton-kit/crouter 0.3.17 → 0.3.19

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`;
+}

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

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

package/dist/commands/memory/write.js

@@ -0,0 +1,85 @@
+import { defineLeaf } from '../../core/command.js';
+import { usage } from '../../core/errors.js';
+import { parseFrontmatterGeneric } from '../../core/frontmatter.js';
+import { readText, writeText, pathExists } from '../../core/fs-utils.js';
+import { MEMORY_KINDS, MEMORY_SCOPES, VISIBILITY_RUNGS, resolveWriteTarget, memoryFilePath, coerceGate, coerceAppliesTo, serializeMemoryDoc, } from './shared.js';
+export const writeLeaf = defineLeaf({
+    name: 'write',
+    description: 'create or update a memory document',
+    whenToUse: 'you are recording a new skill, reference, or preference — or revising one that already exists. Writes memory/<name>.md at the resolved scope from the frontmatter flags plus a body piped on stdin. Identity is path-derived: if <name> already exists at the scope it is updated in place, otherwise it is created.',
+    help: {
+        name: 'memory write',
+        summary: 'create or update memory/<name>.md at the resolved scope from frontmatter flags + a stdin body',
+        params: [
+            { kind: 'positional', name: 'name', required: true, constraint: 'Path-derived identity (e.g. `topic` or `area/topic`) → memory/<name>.md at the resolved scope. Updated in place if it already exists, otherwise created.' },
+            { kind: 'flag', name: 'kind', type: 'enum', choices: [...MEMORY_KINDS], required: true, constraint: 'Document kind.' },
+            { kind: 'flag', name: 'when', type: 'string', required: false, constraint: 'Frontmatter whenText — a short string describing when this document should be read.' },
+            { kind: 'flag', name: 'why', type: 'string', required: false, constraint: 'Frontmatter whyText — a short string describing why this document matters.' },
+            { kind: 'flag', name: 'short-form', type: 'string', required: false, constraint: 'Frontmatter short-form — a very abbreviated version of the content, the hook shown in `crtr memory list`.' },
+            { kind: 'flag', name: 'system-prompt-visibility', type: 'enum', choices: [...VISIBILITY_RUNGS], required: false, constraint: 'Rung controlling how much of this document auto-loads into the system prompt / CLI help.' },
+            { kind: 'flag', name: 'file-read-visibility', type: 'enum', choices: [...VISIBILITY_RUNGS], required: false, constraint: 'Rung controlling how much of this document surfaces when it is read off disk.' },
+            { kind: 'flag', name: 'gate', type: 'string', required: false, constraint: 'Frontmatter gate — expression/condition that determines when this document applies.' },
+            { kind: 'flag', name: 'applies-to', type: 'string', required: false, constraint: 'Frontmatter applies-to — glob/path scope the document applies to.' },
+            { kind: 'flag', name: 'scope', type: 'enum', choices: [...MEMORY_SCOPES], required: false, constraint: 'Target scope. Default: project when inside a project, else user.' },
+            { kind: 'stdin', name: 'body', required: true, constraint: 'Document body (markdown, no frontmatter). Piped on stdin, or passed as the bare positional after <name>.' },
+        ],
+        output: [
+            { name: 'name', type: 'string', required: true, constraint: 'The path-derived document name written.' },
+            { name: 'kind', type: 'string', required: true, constraint: 'Kind recorded in frontmatter.' },
+            { name: 'scope', type: 'string', required: true, constraint: 'Scope the document was written to: user or project.' },
+            { name: 'path', type: 'string', required: true, constraint: 'Absolute path to the written document.' },
+            { name: 'created', type: 'boolean', required: true, constraint: 'true when a new document was created, false when an existing one was updated in place.' },
+            { name: 'follow_up', type: 'string', required: true, constraint: 'Concrete next commands — read it back or list the inventory.' },
+        ],
+        outputKind: 'object',
+        effects: [
+            'Creates or overwrites memory/<name>.md at the resolved scope with the given frontmatter fields + stdin body.',
+        ],
+    },
+    run: async (input) => {
+        const name = input['name'];
+        const kind = input['kind'];
+        const scopeArg = input['scope'];
+        const body = input['body'] ?? '';
+        const { scope, memoryDir } = resolveWriteTarget(scopeArg);
+        const path = memoryFilePath(memoryDir, name);
+        const created = !pathExists(path);
+        // CREATE requires the two prose fields that compose the generated preview
+        // routing line — without them every preview renders the degenerate
+        // '", read this <kind>. ."'. UPDATE inherits them from the existing doc.
+        if (created && (input['when'] === undefined || input['why'] === undefined)) {
+            throw usage(`creating ${name} requires --when and --why (they compose the preview routing line "{when}, read this ${kind}. {why}.")`);
+        }
+        // In-place update: start from the existing frontmatter (preserving fields
+        // not passed this time), then overlay the provided ones. Create: start clean.
+        const frontmatter = created
+            ? {}
+            : { ...(parseFrontmatterGeneric(readText(path)).data ?? {}) };
+        // kind is required, always set. Optionals only overlay when provided so an
+        // update never erases a field the caller did not mention.
+        frontmatter['kind'] = kind;
+        const setIf = (key, value) => {
+            if (value !== undefined)
+                frontmatter[key] = value;
+        };
+        setIf('when', input['when']);
+        setIf('why', input['why']);
+        setIf('short-form', input['shortForm']);
+        setIf('system-prompt-visibility', input['systemPromptVisibility']);
+        setIf('file-read-visibility', input['fileReadVisibility']);
+        if (input['gate'] !== undefined)
+            frontmatter['gate'] = coerceGate(input['gate']);
+        if (input['appliesTo'] !== undefined) {
+            frontmatter['applies-to'] = coerceAppliesTo(input['appliesTo']);
+        }
+        writeText(path, serializeMemoryDoc(frontmatter, body));
+        return {
+            name,
+            kind,
+            scope,
+            path,
+            created,
+            follow_up: `Read it back with \`crtr memory read ${name}\`, or browse the inventory with \`crtr memory list\`.`,
+        };
+    },
+});

package/dist/commands/memory.d.ts

@@ -0,0 +1,2 @@
+import type { BranchDef } from '../core/command.js';
+export declare function registerMemory(): BranchDef;

package/dist/commands/memory.js

@@ -0,0 +1,27 @@
+// `crtr memory` subtree — the document substrate (skills, references,
+// preferences) accessed via the CLI. Four flat leaves: list, read, find, write.
+// SKELETON ONLY (task B1): the `-h` contracts here are final; the leaf handlers
+// are stubs that B2 fills in. Mirrors `skill.ts` minus the loaded-skills
+// catalog dynamicState.
+import { defineBranch } from '../core/command.js';
+import { listLeaf } from './memory/list.js';
+import { readLeaf } from './memory/read.js';
+import { findLeaf } from './memory/find.js';
+import { writeLeaf } from './memory/write.js';
+import { lintLeaf } from './memory/lint.js';
+export function registerMemory() {
+    return defineBranch({
+        name: 'memory',
+        rootEntry: {
+            concept: 'a memory document you read on demand — a skill, reference, or preference',
+            desc: 'list, read, search, and write memory documents',
+            useWhen: 'a task matches a stored skill, reference, or preference — read it before improvising. `crtr memory read <name>` loads one by name; `crtr memory list` browses the inventory; `crtr memory find` searches by topic when you do not yet know the name. Names are path-derived crtr identifiers, not file paths — never cat or find the markdown off disk.',
+        },
+        help: {
+            name: 'memory',
+            summary: 'list, read, search, and write memory documents — skills, references, preferences',
+            model: '`list` for a human inventory of what is stored — one line per document, the only surface that shows short-form. `read` (leaf) loads one document body by name, resolved project > user > builtin with leaf-name fallback; --frontmatter keeps the YAML header. `find` when you do not yet know which document applies — it ranks by relevance over name/when/why/short-form, --body to also weigh bodies, --grep for an exact regex over bodies. `write` creates or updates memory/<name>.md at a scope from frontmatter flags + a body piped on stdin. `lint` strict-parses the whole bounded corpus and fails on any invalid frontmatter — run it after authoring. Append `-h` at any leaf for its full schema.',
+        },
+        children: [listLeaf, readLeaf, findLeaf, writeLeaf, lintLeaf],
+    });
+}

package/dist/commands/node.d.ts

@@ -6,8 +6,9 @@ import { type BranchDef } from '../core/command.js';
 export declare function childFollowUp(spawnerId: string | undefined): string;
 /** The live node occupying a tmux pane (pane → window → node), or undefined.
  *  Defaults to $TMUX_PANE / the caller's current pane when `pane` is omitted —
- *  shared by `node demote` and `node cycle`, both of which act on "the agent in
- *  front of you". Exported for the `canvas chord` / `canvas tmux-spread` leaves,
+ *  shared by `node recycle` / `node demote` / `node lifecycle` / `node close` /
+ *  `node cycle`, all of which act on "the agent in front of you". Exported for
+ *  the `canvas chord` / `canvas tmux-spread` leaves,
  *  which resolve the active pane's node the same way. */
 export declare function nodeInPane(pane?: string): string | undefined;
 export declare function registerNode(): BranchDef;