@north-light/crouter 0.3.216 → 0.3.218

package/dist/commands/memory/shared.js

@@ -6,7 +6,9 @@
 import { existsSync, readdirSync, realpathSync, rmdirSync, statSync } from 'node:fs';
 import { dirname, join, resolve as resolvePath } from 'node:path';
 import { stringify as yamlStringify, parse as yamlParse } from 'yaml';
+import { stateBlock } from '../../core/help.js';
 import { usage } from '../../core/errors.js';
+import { memoryExtensionValidationCatalog, } from '../../core/memory/extensions.js';
 import { CRTR_DIR_NAME } from '../../types.js';
 import { scopeMemoryDir, projectScopeRoot, ensureProjectScopeRoot, resetScopeCache, } from '../../core/scope.js';
 import { loadProfileManifest, profileMemoryDir } from '../../core/profiles/manifest.js';
@@ -309,6 +311,183 @@ export function serializeMemoryDocLiteral(frontmatter, bodySegment) {
     const yamlText = yamlStringify(ordered).replace(/\n+$/, '');
     return `---\n${yamlText}\n---\n${bodySegment}`;
 }
+/** Resolve declarations at the same scope and path a document will use. The
+ * catalog intentionally includes disabled plugins: they still authorize typed
+ * edits to values that stay inert until their plugin is enabled again. */
+export function memoryExtensionCatalogForDoc(doc) {
+    return memoryExtensionValidationCatalog(doc);
+}
+function declarationValueDescription(declaration) {
+    if (declaration.type !== 'enum')
+        return declaration.type;
+    return `enum (${declaration.values.join('|')})`;
+}
+function extensionHelpValue(value) {
+    return typeof value === 'string' ? JSON.stringify(value) : String(value);
+}
+/** A bounded declaration catalog for the two authoring leaves. The manifest is
+ * the source for both the type and operation-specific guidance. */
+export function memoryExtensionFieldCatalogHelp(operation) {
+    const scope = projectScopeRoot() === null ? 'user' : 'project';
+    const memoryDir = scopeMemoryDir(scope);
+    if (memoryDir === null)
+        return null;
+    const catalog = memoryExtensionCatalogForDoc({ scope, path: join(memoryDir, '.extension-help.md') });
+    const fields = Object.entries(catalog)
+        .flatMap(([namespace, declarations]) => Object.entries(declarations).map(([field, declaration]) => ({ namespace, field, declaration })))
+        .sort((left, right) => `${left.namespace}.${left.field}`.localeCompare(`${right.namespace}.${right.field}`));
+    if (fields.length === 0)
+        return null;
+    const maxRows = 50;
+    const rows = fields.slice(0, maxRows).map(({ namespace, field, declaration }) => {
+        const defaultValue = declaration.default === undefined ? '' : `; default ${extensionHelpValue(declaration.default)}`;
+        const help = operation === 'write' ? declaration.write_help : declaration.edit_help;
+        return `- \`extensions.${namespace}.${field}\` — ${declarationValueDescription(declaration)}${defaultValue}. ${help}`;
+    });
+    if (fields.length > maxRows)
+        rows.push(`- ${fields.length - maxRows} additional declared fields omitted from help.`);
+    return stateBlock('memory-extension-fields', { count: fields.length }, rows.join('\n'));
+}
+function parseExtensionPath(raw, flag) {
+    const match = /^extensions\.([^.]+)\.([^.]+)$/.exec(raw);
+    if (match === null)
+        return `${flag} requires the full path extensions.<plugin>.<field>: ${raw}`;
+    return { path: raw, namespace: match[1], field: match[2] };
+}
+function parseExtensionValue(path, raw, declaration) {
+    if (declaration.type === 'boolean') {
+        if (raw === 'true')
+            return true;
+        if (raw === 'false')
+            return false;
+        return `${path} expects boolean true or false, received ${JSON.stringify(raw)}`;
+    }
+    if (declaration.type === 'number') {
+        if (!/^[+-]?(?:\d+(?:\.\d*)?|\.\d+)(?:[eE][+-]?\d+)?$/.test(raw)) {
+            return `${path} expects finite numeric syntax, received ${JSON.stringify(raw)}`;
+        }
+        const value = Number(raw);
+        return Number.isFinite(value) ? value : `${path} expects a finite number, received ${JSON.stringify(raw)}`;
+    }
+    if (declaration.type === 'enum' && !declaration.values.includes(raw)) {
+        return `${path} expects one of ${declaration.values.join('|')}, received ${JSON.stringify(raw)}`;
+    }
+    return raw;
+}
+/** Parse every requested extension mutation before the caller constructs any
+ * frontmatter. Set values are deliberately declaration-typed rather than YAML. */
+export function parseRequestedExtensionChanges(setRaw, unsetRaw, catalog) {
+    const errors = [];
+    const sets = [];
+    const unsets = [];
+    const setPaths = new Set();
+    const unsetPaths = new Set();
+    for (const raw of setRaw ?? []) {
+        const delimiter = raw.indexOf('=');
+        if (delimiter < 0) {
+            errors.push(`--extension requires extensions.<plugin>.<field>=VALUE: ${raw}`);
+            continue;
+        }
+        const parsedPath = parseExtensionPath(raw.slice(0, delimiter), '--extension');
+        if (typeof parsedPath === 'string') {
+            errors.push(parsedPath);
+            continue;
+        }
+        if (setPaths.has(parsedPath.path)) {
+            errors.push(`duplicate --extension path: ${parsedPath.path}`);
+            continue;
+        }
+        setPaths.add(parsedPath.path);
+        const declaration = catalog[parsedPath.namespace]?.[parsedPath.field];
+        if (declaration === undefined) {
+            errors.push(`${parsedPath.path} is not declared by an installed plugin`);
+            continue;
+        }
+        const value = parseExtensionValue(parsedPath.path, raw.slice(delimiter + 1), declaration);
+        if (typeof value === 'string' && declaration.type !== 'string' && declaration.type !== 'enum') {
+            errors.push(value);
+            continue;
+        }
+        if (typeof value === 'string' && declaration.type === 'enum' && !declaration.values.includes(value)) {
+            errors.push(`${parsedPath.path} expects one of ${declaration.values.join('|')}, received ${JSON.stringify(value)}`);
+            continue;
+        }
+        sets.push({ ...parsedPath, value });
+    }
+    for (const raw of unsetRaw ?? []) {
+        const parsedPath = parseExtensionPath(raw, '--unset-extension');
+        if (typeof parsedPath === 'string') {
+            errors.push(parsedPath);
+            continue;
+        }
+        if (unsetPaths.has(parsedPath.path)) {
+            errors.push(`duplicate --unset-extension path: ${parsedPath.path}`);
+            continue;
+        }
+        unsetPaths.add(parsedPath.path);
+        if (catalog[parsedPath.namespace]?.[parsedPath.field] === undefined) {
+            errors.push(`${parsedPath.path} is not declared by an installed plugin`);
+            continue;
+        }
+        unsets.push(parsedPath);
+    }
+    for (const path of setPaths) {
+        if (unsetPaths.has(path))
+            errors.push(`${path} was requested in both --extension and --unset-extension`);
+    }
+    if (errors.length > 0) {
+        throw usage(`invalid plugin memory extension request:\n- ${errors.join('\n- ')}`, {
+            received: [...(setRaw ?? []), ...(unsetRaw ?? [])].join(', '),
+            next: 'Run `crtr memory write -h` or `crtr memory edit -h` for the installed field catalog and value syntax.',
+        });
+    }
+    return { sets, unsets };
+}
+/** Apply only requested extension paths. Existing unknown namespaces remain
+ * untouched; an unset prunes the empty namespace and empty root mapping. */
+export function applyExtensionChanges(frontmatter, sets, unsets) {
+    if (sets.length === 0 && unsets.length === 0)
+        return;
+    const current = frontmatter['extensions'];
+    if (current !== undefined && (current === null || typeof current !== 'object' || Array.isArray(current))) {
+        throw usage('existing extensions frontmatter must be a mapping before extension fields can be changed', {
+            received: JSON.stringify(current),
+            next: 'Repair the extensions mapping, or make a core-field-only edit that preserves it unchanged.',
+        });
+    }
+    const extensions = { ...(current ?? {}) };
+    for (const set of sets) {
+        const existing = extensions[set.namespace];
+        if (existing !== undefined && (existing === null || typeof existing !== 'object' || Array.isArray(existing))) {
+            throw usage(`existing ${`extensions.${set.namespace}`} frontmatter must be a mapping before ${set.path} can change`, {
+                received: JSON.stringify(existing),
+                next: 'Repair the namespace mapping, or make a core-field-only edit that preserves it unchanged.',
+            });
+        }
+        extensions[set.namespace] = { ...(existing ?? {}), [set.field]: set.value };
+    }
+    for (const unset of unsets) {
+        const existing = extensions[unset.namespace];
+        if (existing === undefined)
+            continue;
+        if (existing === null || typeof existing !== 'object' || Array.isArray(existing)) {
+            throw usage(`existing ${`extensions.${unset.namespace}`} frontmatter must be a mapping before ${unset.path} can change`, {
+                received: JSON.stringify(existing),
+                next: 'Repair the namespace mapping, or make a core-field-only edit that preserves it unchanged.',
+            });
+        }
+        const fields = { ...existing };
+        delete fields[unset.field];
+        if (Object.keys(fields).length === 0)
+            delete extensions[unset.namespace];
+        else
+            extensions[unset.namespace] = fields;
+    }
+    if (Object.keys(extensions).length === 0)
+        delete frontmatter['extensions'];
+    else
+        frontmatter['extensions'] = extensions;
+}
 // ---------------------------------------------------------------------------
 // Help material shared by `write` and `edit`
 //
@@ -343,6 +522,6 @@ export function overlayParam(name, overrides = {}, extraConstraint) {
  *  happening. Same field, same prose, two flag names that cannot be confused. */
 export const DOC_RATIONALE_CONSTRAINT = 'Frontmatter rationale \u2014 the observed agent failure that made this doc necessary. Maintainer-facing only: never ships in any delivered surface (boot render, on-read injection, `memory read` content), visible only via `memory read --frontmatter`. Omitting the flag preserves an existing rationale unchanged.';
 export const GUIDE_SURFACES = 'Every doc appears in its directory’s listing by default (suppress with --unlisted); everything beyond the listing is explicit `surfaces` routing — entries declaring WHEN the doc delivers and how much. Events: `boot` delivers in the boot catalog every agent sees; `workspace-open` delivers in first-message context when cwd/profile mounts the doc’s project store (project stores only); `read` fires when the agent reads a matching file (globs vs the file’s absolute path and basename, `./`-anchored globs vs its path relative to the store’s owning repo dir, `match-frontmatter` predicates over the read file’s own YAML frontmatter); `memory-read` fires when another memory doc is read (globs vs that doc’s canonical name, `./` anchored to this doc’s own name directory); `command` fires when a matching shell command runs (globs vs the whole command string, `*` crossing `/`). `at` sets how much delivers: `name` the bare tag, `preview` the routing line, `content` the whole body. Each entry is paid by every future agent it fires on, so default down: no surfaces at all is correct for reference depth reached through listings and [[links]], and when a doc fits in a single sentence, deliver `content` directly — a `preview` routing line would run longer than the doc itself. Sentence-length `content` docs are correct; never pad a memory to be more verbose than the rule or fact it carries.';
-export const GUIDE_ROUTING_LINE = 'The routing line (--when-and-why-to-read) is the only text an agent reads before deciding to load the doc. The test for its because-clause: if it can be derived by paraphrasing the doc\u2019s advice, it is a restatement, not a payoff \u2014 a real payoff names a consequence in the reader\u2019s world that the document itself never asserts. Bad: "because only genuine first principles belong in taste memory." Bad: "because keeping the test loop fast and free of speculative tests protects the development pace" \u2014 the doc\u2019s rule as an outcome, derivable straight from its advice. Good: "because identifying throughlines in user taste lets future decisions be made faster and with less re-litigation." Someone mid-task who has not read the doc must be able to decide from this line alone whether the read is worth it. If you cannot name the concrete situation that triggers it, you do not yet understand the memory \u2014 ask the user one sharp question instead of improvising.';
+export const GUIDE_ROUTING_LINE = 'The routing line (--when-and-why-to-read) is the only text an agent reads before deciding to load the doc. The test for its when-clause: it names an observable circumstance in the reader\u2019s current work, not the doc\u2019s topic reworded as an activity. If the WHEN can be inferred from the title alone, it is not a real trigger. Bad on a todo list: "When planning or prioritizing work across this profile." Good: "When the user mentions something from their todos, or asks what is still outstanding across this profile." The test for its because-clause: if it can be derived by paraphrasing the doc\u2019s advice, it is a restatement, not a payoff \u2014 a real payoff names a consequence in the reader\u2019s world that the document itself never asserts. Bad: "because only genuine first principles belong in taste memory." Bad: "because keeping the test loop fast and free of speculative tests protects the development pace" \u2014 the doc\u2019s rule as an outcome, derivable straight from its advice. Good: "because identifying throughlines in user taste lets future decisions be made faster and with less re-litigation." Someone mid-task who has not read the doc must be able to decide from this line alone whether the read is worth it. If you cannot name the concrete situation that triggers it, you do not yet understand the memory \u2014 ask the user one sharp question instead of improvising.';
 export const GUIDE_PREDICATE_VOCABULARY = 'Gate and match-frontmatter share the same predicate language: a field map is AND-ed across fields; dotted fields resolve nested values; field matchers may be scalar, array, or object. Scalar matchers do exact equality, with arrays matching any element. Array matchers do membership or intersection. Object matchers accept `eq`, `ne`, `in`, `nin`, `exists`, `contains`, `containsAll`, `containsAny`, `matches`, `imatches`, `gt`, `gte`, `lt`, and `lte`. Combinators are `all`, `any`, and `not`; sibling field matchers next to them are AND-ed in. An empty condition is inert. An unknown op never matches.';
 export const GUIDE_DOC_LINKS = 'Link related docs with `[[canonical/name]]`. A doc link in any body is a first-class cross-reference to another memory document by its exact canonical name \u2014 the same identifier `crtr memory read` takes. A bare directory name is a valid link too: following it returns that directory\u2019s listing, a browse entrance rather than a doc. Links are pointers, never transclusion: the linked body is loaded only when a reader follows it, so a link costs nothing until needed. `crtr memory lint` fails on a link that resolves to no document or directory, and `crtr memory read` lists a doc\u2019s resolvable links alongside its body. There is no alias or label form.';

package/dist/commands/memory/write.js

@@ -2,7 +2,7 @@ import { defineLeaf } from '../../core/command.js';
 import { usage } from '../../core/errors.js';
 import { writeText, pathExists } from '../../core/fs-utils.js';
 import { appendHistoryRecord, buildHistoryRecord, historyLogPathFor, } from '../../core/memory/history.js';
-import { DOC_RATIONALE_CONSTRAINT, GUIDE_DOC_LINKS, GUIDE_PREDICATE_VOCABULARY, GUIDE_ROUTING_LINE, GUIDE_SURFACES, MEMORY_SCOPES, resolveWriteTarget, memoryFilePath, buildOrigin, coerceGate, coerceSurface, overlayParam, serializeMemoryDoc, } from './shared.js';
+import { DOC_RATIONALE_CONSTRAINT, GUIDE_DOC_LINKS, GUIDE_PREDICATE_VOCABULARY, GUIDE_ROUTING_LINE, GUIDE_SURFACES, MEMORY_SCOPES, resolveWriteTarget, memoryFilePath, buildOrigin, coerceGate, coerceSurface, memoryExtensionCatalogForDoc, memoryExtensionFieldCatalogHelp, overlayParam, parseRequestedExtensionChanges, applyExtensionChanges, serializeMemoryDoc, } from './shared.js';
 // A topic's memory set stays usable only when authors treat cohesion as a creation
 // gate; otherwise small corrections accumulate as overlapping leaves whose routing
 // lines cannot tell a future reader which one owns the topic.
@@ -38,6 +38,7 @@ export const writeLeaf = defineLeaf({
             overlayParam('gate'),
             overlayParam('slash'),
             { kind: 'flag', name: 'rationale', type: 'string', required: false, constraint: DOC_RATIONALE_CONSTRAINT },
+            { kind: 'flag', name: 'extension', type: 'string', required: false, repeatable: true, constraint: 'Set one declared plugin field as `extensions.<plugin>.<field>=VALUE`. The path is required in full; booleans accept only true or false, numbers require finite numeric syntax, and strings/enums preserve the literal text after the first =. Every requested field validates before the document is written.' },
             { kind: 'flag', name: 'scope', type: 'enum', choices: [...MEMORY_SCOPES], required: false, constraint: 'Target scope. Default: project when inside a project, else user. `project` resolves to the NEAREST ancestor `.crouter/` walking up from cwd — in a nested workspace that can be a parent’s store, not the dir you are standing in; pass --dir to pin the exact project directory. `profile` requires a selected profile (CRTR_PROFILE_ID) or an explicit --profile. `node` writes to the this-node store (`nodes/<CRTR_NODE_ID>/context/memory/`) — the nearest scope, seen only by this running node, requires a node context.' },
             { kind: 'flag', name: 'dir', type: 'string', required: false, constraint: 'Exact project directory to write under — targets `<dir>/.crouter/memory/` regardless of cwd or ancestor stores, scaffolding `.crouter/` there if absent. THE way to place a doc in a specific project’s store (e.g. another project in your profile’s purview) without cd’ing there, and the only way to target a dir shadowed by an ancestor store. Implies --scope project; rejects --scope user/profile.' },
             { kind: 'flag', name: 'profile', type: 'string', required: false, constraint: 'Profile id or name to write under, for --scope profile. Default: the process CRTR_PROFILE_ID (the node\u2019s selected profile). Resolved through the same profile lookup as `crtr profile show`. Rejected (usage error) unless --scope profile is also selected \u2014 never silently ignored for another scope.' },
@@ -54,6 +55,7 @@ export const writeLeaf = defineLeaf({
             { name: 'follow_up', type: 'string', required: true, constraint: 'Concrete next commands — read it back, revise it, or list the inventory.' },
         ],
         outputKind: 'object',
+        dynamicState: () => memoryExtensionFieldCatalogHelp('write'),
         effects: [
             'Creates memory/<name>.md at the resolved scope with the given frontmatter fields + stdin body, and opens memory/.history/<name>.jsonl with a `create` record.',
         ],
@@ -67,6 +69,7 @@ export const writeLeaf = defineLeaf({
         const dirArg = input['dir'];
         const { scope, memoryDir } = resolveWriteTarget(scopeArg, profileArg, dirArg);
         const path = memoryFilePath(memoryDir, name);
+        const extensionChanges = parseRequestedExtensionChanges(input['extension'], undefined, memoryExtensionCatalogForDoc({ scope, path }));
         // Create-only. Revision goes through `edit`, which requires a rationale and
         // records the change — a write that still overwrote would be a standing
         // bypass of the audit trail. The error is the migration path.
@@ -97,6 +100,7 @@ export const writeLeaf = defineLeaf({
         if (input['slash'] === true)
             frontmatter['slash'] = true;
         setIf('rationale', input['rationale']);
+        applyExtensionChanges(frontmatter, extensionChanges.sets, extensionChanges.unsets);
         // One field consumers read for recency, live from the first byte.
         frontmatter['last-updated'] = origin['created'];
         // A workspace-open entry fires only when cwd/profile mounts the doc's
@@ -124,6 +128,7 @@ export const writeLeaf = defineLeaf({
             ...(input['gate'] !== undefined ? ['gate'] : []),
             ...(input['slash'] === true ? ['slash'] : []),
             ...(input['rationale'] !== undefined ? ['rationale'] : []),
+            ...(extensionChanges.sets.length > 0 ? ['extensions'] : []),
         ];
         const selectedFrontmatter = selectedKeys.map((key) => ({ key, value: frontmatter[key] }));
         return {

package/dist/commands/pkg/browse/catalog.js

@@ -8,6 +8,7 @@ import { qualifiedTopLevelCommandName } from "../../../core/command-manifests/re
 import { listDirs, pathExists, walkFiles } from "../../../core/fs-utils.js";
 import { currentSha, gitSync } from "../../../core/git.js";
 import { listPluginMemoryDocs } from "../../../core/memory-resolver.js";
+import { memoryExtensionEffectiveCatalog, projectEffectiveMemoryExtensions } from "../../../core/memory/extensions.js";
 import { readMarketplaceManifest, readPluginManifest } from "../../../core/manifest.js";
 import { readConfig } from "../../../core/config.js";
 import { parseSubstrateDoc } from "../../../core/substrate/schema.js";
@@ -365,6 +366,7 @@ function docDetails(plugin) {
                 slash: parsed.slash,
                 ...(parsed.gate !== undefined ? { gate: parsed.gate } : {}),
                 ...(parsed.rationale !== undefined ? { rationale: parsed.rationale } : {}),
+                extensions: projectEffectiveMemoryExtensions(doc.frontmatter?.["extensions"], memoryExtensionEffectiveCatalog(doc)),
                 body: parsed.body,
             }];
     });

package/dist/commands/pkg/browse/model.d.ts

@@ -1,6 +1,6 @@
 import type { Field, InputParam } from "../../../core/help.js";
 import type { SurfaceEntry } from "../../../core/substrate/schema.js";
-import type { OwnerRef, Scope } from "../../../types.js";
+import type { MemoryExtensionScalar, OwnerRef, Scope } from "../../../types.js";
 /** The scopes that can hold a marketplace, and that a plugin can be installed
  *  into. Narrower than `Scope`: `builtin` names plugins that ship with crtr, and
  *  `listAllMarketplaces()` never yields it, so a builtin marketplace or a
@@ -100,6 +100,9 @@ export interface DocDetail {
     /** Frontmatter `rationale`: the observed failure the doc exists to close.
      *  Maintainer-facing — never delivered to a reading agent. */
     rationale?: string;
+    /** Effective valid plugin-owned metadata. Enabled declaration defaults appear
+     * here without materializing in the memory document. */
+    extensions: Record<string, Record<string, MemoryExtensionScalar>>;
     /** Markdown body, frontmatter stripped. */
     body: string;
 }