@north-light/crouter 0.3.217 → 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`
 //

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