@crouton-kit/crouter 0.3.37 → 0.3.39

package/dist/core/memory-resolver.js

@@ -6,26 +6,41 @@ import { listInstalledPlugins, listInstalledPluginsInRoot, parseSkillQualifier }
 import { ambiguous, notFound, usage } from './errors.js';
 import { warn } from './output.js';
 import { pluginMemoryDir, projectScopeRoot, projectScopeRoots, scopeMemoryDir } from './scope.js';
+import { normalizeDocName, normalizeNameSegment } from './substrate/schema.js';
+import { loadProfileManifest, profileMemoryDir } from './profiles/manifest.js';
 /** Canonical, unambiguous identifier for a memory document: `<scope>/<name>`. */
 export function memoryDocId(doc) {
     return `${doc.scope}/${doc.name}`;
 }
-/** The memory scopes in resolution precedence: project > user > builtin.
- *  Project is included only when a project scope exists for the cwd. A single
- *  `scope` narrows to just that scope. */
+/** The selected profile id from the process env, or '' when none. The single
+ *  seam every profile-aware memory/config path reads through — see the plan's
+ *  synthesis decision on why this is process env, not a threaded parameter. */
+function selectedProfileId() {
+    return process.env['CRTR_PROFILE_ID'] || '';
+}
+/** The memory scopes in resolution precedence: project stack > profile > user >
+ *  builtin. Project is included only when a project scope exists for the cwd
+ *  (or the selected profile's project stack); profile is included only when a
+ *  profile is selected. A single `scope` narrows to just that scope. */
 function scopesInPrecedence(scope) {
     if (scope)
         return [scope];
     const out = [];
     if (projectScopeRoot())
         out.push('project');
+    if (selectedProfileId() !== '')
+        out.push('profile');
     out.push('user');
     out.push('builtin');
     return out;
 }
 /** Memory loads project scopes as a stack, not a single nearest root: every
- *  ancestor `.crouter/` from cwd upward contributes, nearest first. User and
- *  builtin remain singleton scopes after that stack. */
+ *  ancestor `.crouter/` from cwd upward (widened by a selected profile's
+ *  `projects`) contributes, nearest first. Profile is a singleton store
+ *  resolved through the centralized `loadProfileManifest` — never a raw path
+ *  join — and drops out silently (never throws the resolver) when the
+ *  selected profile id no longer resolves to a manifest. User and builtin
+ *  remain singleton scopes after that. */
 function memorySourcesInPrecedence(scope) {
     const out = [];
     for (const s of scopesInPrecedence(scope)) {
@@ -38,6 +53,18 @@ function memorySourcesInPrecedence(scope) {
                 });
             }
         }
+        else if (s === 'profile') {
+            const profileId = selectedProfileId();
+            if (profileId !== '') {
+                try {
+                    const { profileId: resolvedId } = loadProfileManifest(profileId);
+                    out.push({ scope: 'profile', memoryDir: profileMemoryDir(resolvedId), plugins: [] });
+                }
+                catch {
+                    // Missing/deleted/invalid selected profile: no profile memory source.
+                }
+            }
+        }
         else {
             out.push({
                 scope: s,
@@ -56,7 +83,7 @@ function loadMemoryDoc(name, scope, path) {
  *  subdirs supported), sorted by path-derived name. SKILL.md bundles are legacy
  *  Agent Skills and are ignored; crouter memory docs are plain .md files under
  *  memory/. */
-function listMemoryDocsInDir(scope, dir) {
+function listMemoryDocsInDir(scope, dir, quiet = false) {
     if (!dir || !pathExists(dir))
         return [];
     const docs = [];
@@ -76,7 +103,8 @@ function listMemoryDocsInDir(scope, dir) {
                 stack.push(join(d, e.name));
             else if (e.isFile() && e.name.endsWith('.md') && e.name !== 'SKILL.md') {
                 const file = join(d, e.name);
-                const name = relative(dir, file).replace(/\.md$/i, '').split(sep).join('/');
+                const raw = relative(dir, file).replace(/\.md$/i, '').split(sep).join('/');
+                const name = normalizeDocName(raw);
                 if (name)
                     found.push({ path: file, name });
             }
@@ -86,35 +114,52 @@ function listMemoryDocsInDir(scope, dir) {
         // COLLECTION layer: the strict frontmatter parser throws on invalid YAML.
         // Isolate one malformed doc with a clear scoped notice + skip, so a single
         // bad file can't brick `memory list`/`find` or the substrate boot render.
+        // `quiet` suppresses the notice for a targeted resolve (a leaf-name read),
+        // where another doc's health is irrelevant noise before the result.
         try {
             docs.push(loadMemoryDoc(name, scope, path));
         }
         catch (e) {
             const msg = (e instanceof Error ? e.message : String(e)).split('\n')[0];
-            warn(`invalid frontmatter in ${path}: ${msg}`);
+            if (!quiet)
+                warn(`invalid frontmatter in ${path}: ${msg}`);
         }
     }
     return docs.sort((a, b) => a.name.localeCompare(b.name));
 }
 /** All native memory docs for a scope. Project scope is a nearest-first stack of
- *  every ancestor `.crouter/memory/`; user and builtin are singleton stores. */
-export function listMemoryDocs(scope) {
+ *  every ancestor `.crouter/memory/` (widened by a selected profile's project
+ *  stack); profile is the selected profile's own singleton store, resolved
+ *  through `loadProfileManifest`; user and builtin are singleton stores. */
+export function listMemoryDocs(scope, quiet = false) {
     if (scope === 'project') {
-        return projectScopeRoots().flatMap((root) => listMemoryDocsInDir('project', join(root, 'memory')));
+        return projectScopeRoots().flatMap((root) => listMemoryDocsInDir('project', join(root, 'memory'), quiet));
     }
-    return listMemoryDocsInDir(scope, scopeMemoryDir(scope));
+    if (scope === 'profile') {
+        const profileId = selectedProfileId();
+        if (profileId === '')
+            return [];
+        try {
+            const { profileId: resolvedId } = loadProfileManifest(profileId);
+            return listMemoryDocsInDir('profile', profileMemoryDir(resolvedId), quiet);
+        }
+        catch {
+            return [];
+        }
+    }
+    return listMemoryDocsInDir(scope, scopeMemoryDir(scope), quiet);
 }
 /** All of one plugin's substrate docs, mounted under the virtual `<pluginName>/`
  *  namespace. Walks `pluginMemoryDir(plugin)` recursively for *.md, deriving each
  *  doc's name exactly as `listMemoryDocs` does (path-relative, no extension,
  *  slash-separated) then prefixing the plugin name. Builtin has no plugins. */
-export function listPluginMemoryDocs(plugin, scope) {
+export function listPluginMemoryDocs(plugin, scope, quiet = false) {
     const dir = pluginMemoryDir(plugin);
     if (!pathExists(dir))
         return [];
     const docs = [];
     for (const file of walkFiles(dir, (n) => n.endsWith('.md') && n !== 'SKILL.md')) {
-        const derived = relative(dir, file).replace(/\.md$/i, '').split(sep).join('/');
+        const derived = normalizeDocName(relative(dir, file).replace(/\.md$/i, '').split(sep).join('/'));
         if (!derived)
             continue;
         const name = `${plugin.name}/${derived}`;
@@ -123,21 +168,84 @@ export function listPluginMemoryDocs(plugin, scope) {
         }
         catch (e) {
             const msg = (e instanceof Error ? e.message : String(e)).split('\n')[0];
-            warn(`invalid frontmatter in ${file}: ${msg}`);
+            if (!quiet)
+                warn(`invalid frontmatter in ${file}: ${msg}`);
         }
     }
     return docs.sort((a, b) => a.name.localeCompare(b.name));
 }
 /** All memory docs across the resolved sources, in precedence order: each
- *  ancestor project `.crouter/` from nearest to farthest, then user, then
- *  builtin. Within each source, native docs are emitted before enabled-plugin
- *  docs, so native wins on the caller's first-wins dedup. */
-export function listAllMemoryDocs(scope) {
+ *  ancestor project `.crouter/` from nearest to farthest, then the selected
+ *  profile's memory (if any), then user, then builtin. Within each source,
+ *  native docs are emitted before enabled-plugin docs, so native wins on the
+ *  caller's first-wins dedup. */
+export function listAllMemoryDocs(scope, quiet = false) {
     return memorySourcesInPrecedence(scope).flatMap((source) => [
-        ...listMemoryDocsInDir(source.scope, source.memoryDir),
-        ...source.plugins.flatMap((p) => listPluginMemoryDocs(p, source.scope)),
+        ...listMemoryDocsInDir(source.scope, source.memoryDir, quiet),
+        ...source.plugins.flatMap((p) => listPluginMemoryDocs(p, source.scope, quiet)),
     ]);
 }
+/** Find the direct child of `dir` — a `.md` file (matched on name minus
+ *  extension) or a directory — whose NORMALIZED display name equals
+ *  `segment`. An exact literal match (no prefix to strip) wins over a
+ *  normalized match, so a `spine` dir sitting beside a `01-spine` dir (a
+ *  malformed corpus) never masks the literal one; a well-formed corpus has at
+ *  most one candidate either way. Returns the absolute child path, or null. */
+function matchNormalizedChild(dir, segment, want) {
+    let entries;
+    try {
+        entries = readdirSync(dir, { withFileTypes: true });
+    }
+    catch {
+        return null;
+    }
+    let normalizedHit = null;
+    for (const e of entries) {
+        if (want === 'dir') {
+            if (!e.isDirectory())
+                continue;
+            if (e.name === segment)
+                return join(dir, e.name);
+            if (normalizedHit === null && normalizeNameSegment(e.name) === segment) {
+                normalizedHit = join(dir, e.name);
+            }
+        }
+        else {
+            if (!(e.isFile() && e.name.endsWith('.md')))
+                continue;
+            const base = e.name.slice(0, -3);
+            if (base === segment)
+                return join(dir, e.name);
+            if (normalizedHit === null && normalizeNameSegment(base) === segment) {
+                normalizedHit = join(dir, e.name);
+            }
+        }
+    }
+    return normalizedHit;
+}
+/** Resolve a NORMALIZED (numeric-prefix-stripped) segment path against a
+ *  physical memory dir: walk intermediate segments matching each as a
+ *  directory by normalized name, then resolve the final segment as either a
+ *  `.md` file or a directory (the bare-dir -> INDEX.md fallback needs the dir
+ *  match even when a same-named file also exists). Either half is null when
+ *  the segment path does not resolve that way. This is what makes
+ *  `00-runtime-base.md` findable as `runtime-base` and `01-spine/00-has-manager`
+ *  findable as `spine/has-manager` — the physical path keeps its pins, only
+ *  lookup is prefix-blind. */
+function resolveNormalizedPath(baseDir, segments) {
+    let curDir = baseDir;
+    for (let i = 0; i < segments.length - 1; i++) {
+        const next = matchNormalizedChild(curDir, segments[i], 'dir');
+        if (!next)
+            return { filePath: null, dirPath: null };
+        curDir = next;
+    }
+    const last = segments[segments.length - 1];
+    return {
+        filePath: matchNormalizedChild(curDir, last, 'file'),
+        dirPath: matchNormalizedChild(curDir, last, 'dir'),
+    };
+}
 /** Direct full-path lookup of memory/<name>.md across scopes, precedence-first.
  *  Returns every scope's hit in precedence order; the resolver takes the first
  *  (highest-precedence) one — a fully-specified name is never ambiguous.
@@ -145,7 +253,12 @@ export function listAllMemoryDocs(scope) {
  *  A directory INDEX is the cleaner contract: when `<name>.md` is absent but
  *  `<name>/INDEX.md` exists, the bare dir name (`taste`) resolves to the dir's
  *  INDEX doc — carrying the dir name as its identity. (`taste/INDEX` still
- *  resolves directly as the file path.) */
+ *  resolves directly as the file path.)
+ *
+ *  `name`'s segments are already normalized (a caller-supplied identifier is
+ *  never authored with a numeric prefix); resolution against the physical tree
+ *  is prefix-blind via `resolveNormalizedPath` so a normalized name finds an
+ *  `NN-`-pinned physical file/dir. */
 function findMemoryMatches(name, scope) {
     const matches = [];
     const segments = name.split('/');
@@ -156,15 +269,17 @@ function findMemoryMatches(name, scope) {
         // ancestor `.crouter/`, then user, then builtin.
         const dir = source.memoryDir;
         if (dir) {
-            const path = join(dir, ...segments) + '.md';
-            if (!isLegacySkillDoc && pathExists(path)) {
-                matches.push(loadMemoryDoc(name, source.scope, path));
+            const { filePath, dirPath } = resolveNormalizedPath(dir, segments);
+            if (!isLegacySkillDoc && filePath !== null) {
+                matches.push(loadMemoryDoc(name, source.scope, filePath));
                 continue;
             }
-            const indexPath = join(dir, ...segments, 'INDEX.md');
-            if (pathExists(indexPath)) {
-                matches.push(loadMemoryDoc(name, source.scope, indexPath));
-                continue;
+            if (dirPath !== null) {
+                const indexPath = join(dirPath, 'INDEX.md');
+                if (pathExists(indexPath)) {
+                    matches.push(loadMemoryDoc(name, source.scope, indexPath));
+                    continue;
+                }
             }
         }
         // Plugin memory dir: a `<plugin>/<rest>` name resolves against that enabled
@@ -179,21 +294,22 @@ function findMemoryMatches(name, scope) {
             if (p.name !== pluginName)
                 continue;
             const pdir = pluginMemoryDir(p);
+            const restSegments = rest ? rest.split('/') : [];
             if (rest) {
-                const restSegments = rest.split('/');
-                const ppath = join(pdir, ...restSegments) + '.md';
-                if (restSegments.at(-1) !== 'SKILL' && pathExists(ppath)) {
-                    matches.push(loadMemoryDoc(name, source.scope, ppath));
+                const { filePath } = resolveNormalizedPath(pdir, restSegments);
+                if (restSegments.at(-1) !== 'SKILL' && filePath !== null) {
+                    matches.push(loadMemoryDoc(name, source.scope, filePath));
                     break;
                 }
             }
             // Bare name -> <plugin>/memory/INDEX.md; slashed name -> dir INDEX.
-            const pindex = rest
-                ? join(pdir, ...rest.split('/'), 'INDEX.md')
-                : join(pdir, 'INDEX.md');
-            if (pathExists(pindex)) {
-                matches.push(loadMemoryDoc(name, source.scope, pindex));
-                break;
+            const pIndexDir = rest ? resolveNormalizedPath(pdir, restSegments).dirPath : pdir;
+            if (pIndexDir !== null) {
+                const pindex = join(pIndexDir, 'INDEX.md');
+                if (pathExists(pindex)) {
+                    matches.push(loadMemoryDoc(name, source.scope, pindex));
+                    break;
+                }
             }
         }
     }
@@ -207,7 +323,9 @@ function findMemoryByLeaf(leaf, scope) {
         return [];
     let all;
     try {
-        all = listAllMemoryDocs(scope);
+        // Quiet: a targeted read must not spew other docs' frontmatter warnings
+        // before its own result (esp. a not_found) — corpus health is `lint`'s job.
+        all = listAllMemoryDocs(scope, true);
     }
     catch {
         return [];

package/dist/core/profiles/manifest.d.ts

@@ -0,0 +1,33 @@
+import type { ProfileManifest } from '../../types.js';
+export declare function profilesRoot(): string;
+export declare function profileRoot(profileId: string): string;
+export declare function profileManifestPath(profileId: string): string;
+export declare function profileMemoryDir(profileId: string): string;
+export interface ProfileEntry {
+    profileId: string;
+    manifest: ProfileManifest;
+}
+/** Every profile with a readable manifest, in directory-listing order.
+ *  Enumerates ONLY immediate children of `profilesRoot()` — never recurses,
+ *  never trusts a caller-supplied id. A dir whose name doesn't match the
+ *  generated id shape, or whose `profile.json` is missing/corrupt, is skipped
+ *  rather than crashing the whole listing. */
+export declare function listProfiles(): ProfileEntry[];
+/** Resolve a CLI operand to its profile — exact id first (checked against the
+ *  actually-enumerated dirs, never a blind join), then a unique manifest
+ *  `name` match. Ambiguous names fail listing every matching id; no match
+ *  fails naming `profile list`/`profile new` as recovery. This is the ONLY
+ *  function every command leaf and future runtime consumer (Phase 5/6) should
+ *  call to turn a `<profile>` operand or `CRTR_PROFILE_ID` into a concrete,
+ *  safe profile id. */
+export declare function loadProfileManifest(profileIdOrName: string): ProfileEntry;
+/** Hold the per-profile manifest lock for the duration of `fn`. ALL manifest
+ *  mutations (create/rename/add-project/remove-project/delete/last-used)
+ *  below run inside this. */
+export declare function withProfileManifestLock<T>(profileId: string, fn: () => T): T;
+export declare function createProfile(name: string, projects?: string[]): ProfileEntry;
+export declare function updateProfileLastUsed(profileId: string): ProfileEntry;
+export declare function renameProfile(profileId: string, name: string): ProfileEntry;
+export declare function addProfileProject(profileId: string, dir: string): ProfileEntry;
+export declare function removeProfileProject(profileId: string, dir: string): ProfileEntry;
+export declare function deleteProfile(profileId: string): void;