@north-light/crouter 0.3.186 → 0.3.187

package/dist/commands/pkg/plugin-manage.js

@@ -5,7 +5,7 @@ import { defineLeaf } from '../../core/command.js';
 import { notFound, usage, general, network } from '../../core/errors.js';
 import { findMarketplaceByName, findPluginByName, listAllPlugins } from '../../core/resolver.js';
 import { pluginsDir, ensureProjectScopeRoot, userScopeRoot, resolveScopeArg, projectScopeRoot, requireScopeRoot, } from '../../core/scope.js';
-import { updateConfig, updateState, ensureScopeInitialized } from '../../core/config.js';
+import { updateConfig, updateState, ensureScopeInitialized, invalidPluginKindsReasons } from '../../core/config.js';
 import { pathExists, ensureDir, removePath, nowIso, linkOrCopy, isSymlink, atomicWriteJson } from '../../core/fs-utils.js';
 import { clone, pull, deriveNameFromUrl, currentSha, isGitRepo } from '../../core/git.js';
 import { readMarketplaceManifest, readPluginManifest } from '../../core/manifest.js';
@@ -45,6 +45,19 @@ function validateHttpInstall(name, endpoint, authEnv) {
         throw usage(`invalid HTTP plugin transport: ${transportValidation.errors.join('; ')}`);
     return transportValidation.transport;
 }
+/** Fail a SOURCE install (git/local/marketplace) loudly when the plugin's
+ *  authored manifest declares an invalid `kinds` block — the same install-time
+ *  strictness `validatePluginBundle` applies to an archive's bundle.json. The
+ *  read side (`mergeKinds`) drops invalid entries silently, so without this
+ *  the plugin would install cleanly and its kind would just never register. */
+function assertManifestKindsValid(manifest, where) {
+    if (manifest.kinds === undefined)
+        return;
+    const reasons = invalidPluginKindsReasons(manifest.kinds);
+    if (reasons.length > 0) {
+        throw general(`plugin manifest at ${where} declares an invalid kinds block`, { issues: reasons });
+    }
+}
 function invocationTransport(bundle) {
     return { kind: 'http', endpoint: new URL(bundle.endpoint).origin, ...(bundle.authEnv !== undefined ? { authEnv: bundle.authEnv } : {}) };
 }
@@ -115,6 +128,11 @@ async function replaceBundlePlugin(name, bundleSource, scope, options) {
         commands: 'commands.json',
         transport,
         bundle,
+        // Kind-registry contributions declared in the archive's bundle.json,
+        // already strictly validated by validatePluginBundle. Copying them here is
+        // what registers them: readMergedLaunchConfig reads kinds from installed
+        // plugin MANIFESTS, never from bundle.json directly.
+        ...(validated.bundle.kinds !== undefined ? { kinds: validated.bundle.kinds } : {}),
     };
     const tmpRoot = join(scopeRootPath, 'tmp');
     const staging = join(tmpRoot, `${name}.${process.pid}`);
@@ -159,7 +177,7 @@ async function replaceBundlePlugin(name, bundleSource, scope, options) {
     const commands = await commandReport(name, scope);
     if (commands === undefined)
         throw general(`bundle plugin "${name}" has no staged command report`);
-    return { name, scope, path: root, transport: 'http', version, docs: validated.bundle.memory.length, commands };
+    return { name, scope, path: root, transport: 'http', version, docs: validated.bundle.memory.length, kinds: Object.keys(validated.bundle.kinds ?? {}).length, commands };
 }
 async function installHttpPlugin(name, endpoint, authEnv, scope) {
     const source = validateHttpInstall(name, endpoint, authEnv);
@@ -256,6 +274,13 @@ function installFromGit(source, ref, scope) {
         removePath(tempDir);
         throw general(`cloned repo does not contain a valid .crouter-plugin/plugin.json: ${source}`);
     }
+    try {
+        assertManifestKindsValid(manifest, `${source}/.crouter-plugin/plugin.json`);
+    }
+    catch (error) {
+        removePath(tempDir);
+        throw error;
+    }
     const finalName = manifest.name;
     let finalDir = tempDir;
     if (finalName !== tempName) {
@@ -281,6 +306,7 @@ function installFromLocal(source, scope) {
     if (manifest === null) {
         throw notFound(`plugin manifest not found at ${sourcePath}/.crouter-plugin/plugin.json`);
     }
+    assertManifestKindsValid(manifest, `${sourcePath}/.crouter-plugin/plugin.json`);
     const scopeRootPath = scope === 'project' ? ensureProjectScopeRoot() : userScopeRoot();
     ensureScopeInitialized(scope, scopeRootPath);
     const destDir = join(scopeRootPath, 'plugins', manifest.name);
@@ -328,6 +354,13 @@ export function installFromMarketplace(ref, scope) {
         removePath(destPluginDir);
         throw notFound(`plugin manifest not found at ${destPluginDir}/.crouter-plugin/plugin.json`);
     }
+    try {
+        assertManifestKindsValid(pluginManifest, `${destPluginDir}/.crouter-plugin/plugin.json`);
+    }
+    catch (error) {
+        removePath(destPluginDir);
+        throw error;
+    }
     const version = entry.version ?? pluginManifest.version;
     updateConfig(scope, (cfg) => {
         const pluginCfg = {
@@ -344,7 +377,7 @@ async function updateOnePlugin(plugin, marketplaceCache, opts) {
     const sourceInstalled = isSourceInstalled(plugin);
     if (!sourceInstalled && plugin.manifest.bundle !== undefined) {
         const replaced = await replaceBundlePlugin(plugin.name, plugin.manifest.bundle, plugin.scope, { enable: plugin.enabled });
-        return { name: plugin.name, transport: 'http', updated: true, version: replaced.version, docs: replaced.docs, commands: replaced.commands };
+        return { name: plugin.name, transport: 'http', updated: true, version: replaced.version, docs: replaced.docs, kinds: replaced.kinds, commands: replaced.commands };
     }
     if (plugin.manifest.transport?.kind === 'http' && !sourceInstalled)
         rejectLegacyHttpPlugin(plugin.name);
@@ -400,12 +433,13 @@ export const pluginInstall = defineLeaf({
             { name: 'transport', type: 'string', required: false, constraint: 'exec or http when the plugin declares commands. Always http for an --endpoint install.' },
             { name: 'version', type: 'string', required: false, constraint: 'First 12 hex characters of the fetched archive SHA-256 for an --endpoint install.' },
             { name: 'docs', type: 'integer', required: false, constraint: 'Memory document count written from an --endpoint archive.' },
+            { name: 'kinds', type: 'integer', required: false, constraint: 'Kind-registry entry count declared by an --endpoint archive\u2019s bundle.json.' },
             { name: 'commands', type: 'object', required: false, constraint: 'Present only when the plugin declares a command manifest. {mounts: string[] (accepted top-level command names now live for the next invocation), issues: object[] (typed validation issues that rejected a contribution — {code, path?, message, received, expected, next})}. Validated statically; commands are never executed.' },
         ],
         outputKind: 'object',
         effects: [
             'A ref install clones, links, or copies the plugin into the scope plugins directory and registers it with enabled=true. Marketplace installs refresh the source marketplace before resolving the plugin entry.',
-            'An --endpoint install fetches and validates one authenticated uncompressed tar archive before writing. It replaces the complete plugin directory with synthesized provenance and invocation metadata, commands.json, and memory docs; a fetch or validation failure preserves the prior package.',
+            'An --endpoint install fetches and validates one authenticated uncompressed tar archive before writing. It replaces the complete plugin directory with synthesized provenance and invocation metadata, commands.json, memory docs, and any kind-registry entries the bundle.json declares (they join the launch registry below this scope\u2019s own config.json kinds); a fetch or validation failure preserves the prior package.',
             'If the plugin declares a command manifest, its commands go live on the next crtr invocation. Exec commands run trusted local code only when explicitly invoked; HTTP commands call their declared endpoint only when explicitly invoked.',
         ],
     },
@@ -552,7 +586,7 @@ export const pluginUpdate = defineLeaf({
             { kind: 'flag', name: 'scope', type: 'enum', choices: ['user', 'project'], required: false, constraint: 'Narrows resolution.' },
         ],
         output: [
-            { name: 'updated', type: 'object[]', required: true, constraint: 'One entry per plugin processed: {name, transport?, updated, sha?, version?, docs?, commands?, error?}. Archive plugins report transport=http and replace their complete directory after an authenticated refetch; version is the archive content identifier and docs is the written memory-document count. sha is present for git updates. A bulk update reports and skips a failed archive plugin. commands is present for validated command plugins: {mounts: string[], issues: object[]}.' },
+            { name: 'updated', type: 'object[]', required: true, constraint: 'One entry per plugin processed: {name, transport?, updated, sha?, version?, docs?, commands?, error?}. Archive plugins report transport=http and replace their complete directory after an authenticated refetch; version is the archive content identifier, docs is the written memory-document count, and kinds is the declared kind-registry entry count. sha is present for git updates. A bulk update reports and skips a failed archive plugin. commands is present for validated command plugins: {mounts: string[], issues: object[]}.' },
         ],
         outputKind: 'object',
         effects: ['Archive plugins unconditionally re-fetch, validate, and replace their complete package; a named failure exits nonzero and preserves the prior package. Bulk update reports a failed archive plugin and continues. Source-installed plugins retain their source update, version, and last_updated behavior.'],

package/dist/core/__tests__/plugin-kinds.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/core/__tests__/plugin-kinds.test.js

@@ -0,0 +1,167 @@
+// Run with: node --conditions=crtr-src --import tsx/esm --test src/core/__tests__/plugin-kinds.test.ts
+//
+// Wiring pins for plugin-declared kinds — the layer whose absence is SILENT:
+// `mergeKinds` drops nothing loudly at read time, so if `readMergedLaunchConfig`
+// stopped layering enabled plugins' manifest `kinds` blocks (or layered them in
+// the wrong precedence slot), every plugin-shipped persona kind would simply
+// vanish from the registry with all suites green. Precedence under pin:
+//   builtin → user plugins → user config → profile → per project root:
+//   (root plugins → root config)
+// Plus the archive path: `validatePluginBundle` must carry a valid bundle.json
+// `kinds` block into `ValidatedBundle.kinds` (what the installer copies into
+// the synthesized manifest) and reject an invalid one loudly.
+import { test, before, beforeEach, afterEach, after } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync, realpathSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import * as tar from 'tar';
+import { resetScopeCache } from '../scope.js';
+import { readMergedLaunchConfig } from '../config.js';
+import { validatePluginBundle } from '../command-plugins/bundle.js';
+let isolatedHome;
+let isolatedCwd;
+let prevHome;
+let prevCwd;
+before(() => {
+    prevHome = process.env.HOME;
+    prevCwd = process.cwd();
+});
+beforeEach(() => {
+    isolatedHome = realpathSync(mkdtempSync(join(tmpdir(), 'crtr-plugin-kinds-home-')));
+    isolatedCwd = realpathSync(mkdtempSync(join(tmpdir(), 'crtr-plugin-kinds-cwd-')));
+    process.env.HOME = isolatedHome;
+    process.chdir(isolatedCwd);
+    resetScopeCache();
+});
+afterEach(() => {
+    process.chdir(prevCwd);
+    rmSync(isolatedHome, { recursive: true, force: true });
+    rmSync(isolatedCwd, { recursive: true, force: true });
+});
+after(() => {
+    process.chdir(prevCwd);
+    process.env.HOME = prevHome;
+    resetScopeCache();
+});
+/** Plant a manifest-only plugin (kinds need no commands or executable). */
+function plantPlugin(scopeRootPath, name, kinds) {
+    const root = join(scopeRootPath, 'plugins', name, '.crouter-plugin');
+    mkdirSync(root, { recursive: true });
+    writeFileSync(join(root, 'plugin.json'), JSON.stringify({ name, version: '0.1.0', kinds }));
+}
+function userRoot() {
+    const root = join(isolatedHome, '.crouter');
+    mkdirSync(root, { recursive: true });
+    return root;
+}
+function projectRoot() {
+    const root = join(isolatedCwd, '.crouter');
+    mkdirSync(root, { recursive: true });
+    return root;
+}
+test('an enabled user-scope plugin adds a full kind and patches a builtin kind', () => {
+    plantPlugin(userRoot(), 'northlight', {
+        'applet-builder': { whenToUse: 'Build a Northlight applet.', model: 'anthropic/strong' },
+        general: { model: 'openai/light' },
+    });
+    const kinds = readMergedLaunchConfig().kinds;
+    assert.equal(kinds['applet-builder']?.whenToUse, 'Build a Northlight applet.');
+    assert.equal(kinds['applet-builder']?.model, 'anthropic/strong');
+    assert.equal(kinds['general']?.model, 'openai/light');
+    // Patch semantics: the builtin general keeps its whenToUse.
+    assert.ok((kinds['general']?.whenToUse ?? '').length > 0);
+});
+test('the scope\u2019s own config.json overrides its plugins; a disabled plugin contributes nothing', () => {
+    const root = userRoot();
+    plantPlugin(root, 'northlight', { 'applet-builder': { whenToUse: 'plugin gloss', model: 'anthropic/strong' } });
+    plantPlugin(root, 'zzz-disabled', { ghost: { whenToUse: 'never registers' } });
+    writeFileSync(join(root, 'config.json'), JSON.stringify({
+        plugins: { 'zzz-disabled': { enabled: false } },
+        kinds: { 'applet-builder': { model: 'openai/medium' } },
+    }));
+    const kinds = readMergedLaunchConfig().kinds;
+    assert.equal(kinds['applet-builder']?.model, 'openai/medium'); // config patch wins
+    assert.equal(kinds['applet-builder']?.whenToUse, 'plugin gloss'); // patch merges, not replaces
+    assert.equal(kinds['ghost'], undefined);
+});
+test('a project-root plugin layers above user config, and the project config above the plugin', () => {
+    const uRoot = userRoot();
+    writeFileSync(join(uRoot, 'config.json'), JSON.stringify({ kinds: { shared: { whenToUse: 'user gloss', model: 'openai/light' } } }));
+    const pRoot = projectRoot();
+    plantPlugin(pRoot, 'proj-plugin', { shared: { model: 'anthropic/strong' }, 'proj-kind': { whenToUse: 'project plugin kind' } });
+    writeFileSync(join(pRoot, 'config.json'), JSON.stringify({ kinds: { 'proj-kind': { model: 'openai/medium' } } }));
+    const kinds = readMergedLaunchConfig().kinds;
+    assert.equal(kinds['shared']?.model, 'anthropic/strong'); // project plugin > user config
+    assert.equal(kinds['shared']?.whenToUse, 'user gloss');
+    assert.equal(kinds['proj-kind']?.model, 'openai/medium'); // project config > project plugin
+    assert.equal(kinds['proj-kind']?.whenToUse, 'project plugin kind');
+});
+// --- archive path -----------------------------------------------------------
+function minimalCommandsJson() {
+    return {
+        schemaVersion: 1,
+        mounts: [
+            {
+                parent: [],
+                node: {
+                    kind: 'branch',
+                    name: 'app',
+                    description: 'application lifecycle and inspection',
+                    whenToUse: 'you need to inspect an application',
+                    rootEntry: {
+                        concept: 'applications hosted by a crouter home',
+                        description: 'application lifecycle and inspection',
+                        whenToUse: 'you need to inspect an application',
+                    },
+                    summary: 'application lifecycle and inspection',
+                    model: 'Applications are product resources owned by the selected home.',
+                    children: [
+                        {
+                            kind: 'leaf',
+                            name: 'show',
+                            description: 'show one application',
+                            whenToUse: 'inspect a single application by id',
+                            tier: 'important',
+                            summary: 'show one application details',
+                            params: [{ kind: 'positional', name: 'app-id', required: true, constraint: 'the application id' }],
+                            output: [{ name: 'app_id', type: 'string', required: true, constraint: 'the echoed application id' }],
+                            effects: ['None. Read-only.'],
+                            rest: { method: 'GET', path: '/v1/apps/{app-id}', params: { 'app-id': { in: 'path' } } },
+                        },
+                    ],
+                },
+            },
+        ],
+    };
+}
+function makeArchive(bundleJson) {
+    const dir = mkdtempSync(join(tmpdir(), 'crtr-plugin-kinds-tar-'));
+    try {
+        writeFileSync(join(dir, 'bundle.json'), JSON.stringify(bundleJson));
+        writeFileSync(join(dir, 'commands.json'), JSON.stringify(minimalCommandsJson()));
+        const pack = tar.create({ sync: true, cwd: dir, portable: true }, ['bundle.json', 'commands.json']);
+        const chunks = [];
+        let chunk;
+        while ((chunk = pack.read()) !== null)
+            chunks.push(chunk);
+        return new Uint8Array(Buffer.concat(chunks));
+    }
+    finally {
+        rmSync(dir, { recursive: true, force: true });
+    }
+}
+test('validatePluginBundle carries a valid bundle.json kinds block into ValidatedBundle', async () => {
+    const archive = makeArchive({ bundleVersion: 1, kinds: { 'applet-builder': { whenToUse: 'Build an applet.', model: 'anthropic/strong' } } });
+    const validated = await validatePluginBundle(archive, { reservedCoreNames: new Set(['node']) });
+    assert.deepEqual(validated.issues, []);
+    assert.deepEqual(validated.bundle?.kinds, { 'applet-builder': { whenToUse: 'Build an applet.', model: 'anthropic/strong' } });
+});
+test('validatePluginBundle rejects an invalid kinds block loudly', async () => {
+    const archive = makeArchive({ bundleVersion: 1, kinds: { broken: { when_to_use: 'typo field' } } });
+    const validated = await validatePluginBundle(archive, { reservedCoreNames: new Set(['node']) });
+    assert.equal(validated.bundle, undefined);
+    assert.equal(validated.issues.length, 1);
+    assert.match(validated.issues[0].message, /kinds block is invalid/);
+    assert.match(validated.issues[0].received, /when_to_use/);
+});

package/dist/core/command-plugins/bundle.d.ts

@@ -1,4 +1,5 @@
 import { type ValidatedCommandManifest } from '../command-manifests/manifest.js';
+import type { KindConfig } from '../../types.js';
 export interface BundleIssue {
     code: string;
     path?: string;
@@ -9,6 +10,11 @@ export interface BundleIssue {
 }
 export interface ValidatedBundle {
     bundleVersion: 1;
+    /** Kind-registry contributions declared in `bundle.json` (optional). The
+     *  installer copies this validated block into the synthesized plugin
+     *  manifest, where `readMergedLaunchConfig` layers it — see
+     *  `PluginManifest.kinds`. */
+    kinds?: Record<string, Partial<KindConfig>>;
     commands: ValidatedCommandManifest;
     commandsBytes: Uint8Array;
     directories: ReadonlyArray<{

package/dist/core/command-plugins/bundle.js

@@ -1,5 +1,6 @@
 import { Parser } from 'tar';
 import { validateCommandManifest } from '../command-manifests/manifest.js';
+import { invalidPluginKindsReasons } from '../config.js';
 function issue(code, message, received, expected, next, path) {
     return { code, message, received, expected, next, ...(path !== undefined ? { path } : {}) };
 }
@@ -134,12 +135,32 @@ function parseBundleMetadata(bytes) {
         raw = JSON.parse(Buffer.from(bytes).toString('utf8'));
     }
     catch {
-        return bundleInvalid('bundle.json is not valid JSON', 'invalid JSON', '{"bundleVersion":1}', 'Write valid bundle metadata.', 'bundle.json');
+        return { issue: bundleInvalid('bundle.json is not valid JSON', 'invalid JSON', '{"bundleVersion":1}', 'Write valid bundle metadata.', 'bundle.json') };
     }
-    if (typeof raw !== 'object' || raw === null || Array.isArray(raw) || Object.keys(raw).length !== 1 || raw['bundleVersion'] !== 1) {
-        return bundleInvalid('bundle.json must contain exactly {"bundleVersion":1}', JSON.stringify(raw), 'an object with only bundleVersion set to 1', 'Set bundle.json to {"bundleVersion":1}.', 'bundle.json');
+    if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) {
+        return {
+            issue: bundleInvalid('bundle.json must be a JSON object', JSON.stringify(raw), 'an object with bundleVersion set to 1 and optionally kinds', 'Set bundle.json to {"bundleVersion":1}.', 'bundle.json'),
+        };
     }
-    return undefined;
+    const record = raw;
+    const unknownKeys = Object.keys(record).filter((key) => key !== 'bundleVersion' && key !== 'kinds');
+    if (record['bundleVersion'] !== 1 || unknownKeys.length > 0) {
+        return {
+            issue: bundleInvalid('bundle.json must contain bundleVersion 1 and at most a kinds block', JSON.stringify(raw), 'an object with bundleVersion set to 1 and optionally kinds', 'Set bundle.json to {"bundleVersion":1} plus an optional kinds object.', 'bundle.json'),
+        };
+    }
+    if (record['kinds'] === undefined)
+        return {};
+    // Install-time strictness: a bad kinds block fails the install loudly here,
+    // because the read side (`mergeKinds`) drops invalid entries silently and
+    // would otherwise ship a kind that never registers.
+    const reasons = invalidPluginKindsReasons(record['kinds']);
+    if (reasons.length > 0) {
+        return {
+            issue: bundleInvalid('bundle.json kinds block is invalid', reasons.join('; '), 'each entry a full KindConfig (whenToUse required) or a sparse patch of launch fields', 'Fix the kinds entries in bundle.json.', 'bundle.json'),
+        };
+    }
+    return { kinds: record['kinds'] };
 }
 function parseCommands(bytes, reservedCoreNames, coreCommandPaths) {
     let raw;
@@ -175,15 +196,16 @@ export async function validatePluginBundle(archive, options) {
             issues: [bundleInvalid('bundle must contain exactly one bundle.json and one commands.json regular file', `bundle.json=${bundle !== undefined}, commands.json=${commands !== undefined}`, 'one regular bundle.json and one regular commands.json member', 'Add the required metadata members to the archive.')],
         };
     }
-    const metadataIssue = parseBundleMetadata(bundle.bytes);
-    if (metadataIssue !== undefined)
-        return { issues: [metadataIssue] };
+    const metadata = parseBundleMetadata(bundle.bytes);
+    if (metadata.issue !== undefined)
+        return { issues: [metadata.issue] };
     const commandValidation = parseCommands(commands.bytes, options.reservedCoreNames, options.coreCommandPaths);
     if (commandValidation.commands === undefined)
         return { issues: commandValidation.issues };
     return {
         bundle: {
             bundleVersion: 1,
+            ...(metadata.kinds !== undefined ? { kinds: metadata.kinds } : {}),
             commands: commandValidation.commands,
             commandsBytes: commands.bytes,
             directories: parsed.members

package/dist/core/config.d.ts

@@ -26,6 +26,14 @@ export declare function ensureScopeInitialized(scope: Scope, root: string): void
 /** Normalize the user-owned list of attach actions allowed to bridge through an
  * occupied tmux root binding. Unknown and non-attach ids have no effect. */
 export declare function normalizeTmuxPassthrough(raw: unknown): BindingId[];
+/** STRICT install-time validation for a plugin-declared `kinds` block —
+ *  the loud counterpart to `mergeKinds`'s silent read-time dropping. Read
+ *  paths must never throw on bad config, but an INSTALL delivering a bad
+ *  block must fail the install, not ship a kind that silently never
+ *  registers. Returns one human-readable reason per defect; empty = valid.
+ *  Used by the archive-bundle validator (`command-plugins/bundle.ts`) on
+ *  `bundle.json`'s optional `kinds` member. */
+export declare function invalidPluginKindsReasons(raw: unknown): string[];
 /** Raw (un-defaulted) partial config for one scope, or null if the scope has
  *  no root or no config.json. Used by `readMergedLaunchConfig` to layer
  *  scopes onto each other WITHOUT each scope's own default-fill masking a
@@ -49,7 +57,10 @@ export interface MergedLaunchConfig {
 }
 /** Merge launch knobs (`kinds`, `modelLadders`) across scopes in
  *  project stack > profile > user > builtin precedence — the same precedence
- *  order used for memory resolution. A kind or ladder cell declared at a
+ *  order used for memory resolution. For `kinds` only, each plugin-bearing
+ *  scope (user, each project root) additionally layers its enabled plugins'
+ *  manifest `kinds` blocks directly BELOW that scope's own raw config — see
+ *  `layerPluginKinds`. A kind or ladder cell declared at a
  *  more-specific scope shadows the same key from a less-specific scope; the
  *  project STACK (`findProjectScopeRoots` — every ancestor `.crouter/`,
  *  widened by a selected profile's `projects`) layers nearest-root-strongest;

package/dist/core/config.js

@@ -5,6 +5,7 @@ import { BINDING_CATALOG, BINDING_IDS, isAttachPaneBinding } from './keybindings
 import { emitEvent } from './events/emit.js';
 import { atomicWriteJson, readJsonIfExists, writeJson, ensureDir } from './fs-utils.js';
 import { scopeRoot, requireScopeRoot, findProjectScopeRoots } from './scope.js';
+import { listInstalledPluginsInRoot } from './installed-plugins.js';
 import { profileRoot } from './profiles/manifest.js';
 import { withExclusiveDirectoryLock } from './exclusive-lock.js';
 import { SCOPE_CONFIG_KEYS } from './user-settings.js';
@@ -341,6 +342,71 @@ function mergeKinds(raw, base = defaultKindsConfig()) {
     }
     return out;
 }
+/** Layer the `kinds` contributions of every ENABLED plugin installed under
+ *  `scopeRootPath` over `base`, plugin name-sorted for determinism (directory
+ *  listing order is filesystem-dependent). Each plugin's block goes through
+ *  the same `mergeKinds` a scope `config.json` does — full entries add or
+ *  shadow, patches field-merge, invalid entries drop. Called by
+ *  `readMergedLaunchConfig` BELOW the host scope's own raw `kinds`, so the
+ *  scope's config.json always overrides its plugins. */
+function layerPluginKinds(scope, scopeRootPath, base) {
+    if (scopeRootPath === null)
+        return base;
+    const plugins = listInstalledPluginsInRoot(scope, scopeRootPath)
+        .filter((p) => p.enabled && p.manifest.kinds !== undefined)
+        .sort((a, b) => a.name.localeCompare(b.name));
+    let out = base;
+    for (const plugin of plugins)
+        out = mergeKinds(plugin.manifest.kinds, out);
+    return out;
+}
+const KIND_CONFIG_KEYS = new Set(['whenToUse', 'model', 'orchestratorModel', 'tools', 'extensions', 'availableTo']);
+/** STRICT install-time validation for a plugin-declared `kinds` block —
+ *  the loud counterpart to `mergeKinds`'s silent read-time dropping. Read
+ *  paths must never throw on bad config, but an INSTALL delivering a bad
+ *  block must fail the install, not ship a kind that silently never
+ *  registers. Returns one human-readable reason per defect; empty = valid.
+ *  Used by the archive-bundle validator (`command-plugins/bundle.ts`) on
+ *  `bundle.json`'s optional `kinds` member. */
+export function invalidPluginKindsReasons(raw) {
+    if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) {
+        return ['kinds must be a JSON object keyed by kind name'];
+    }
+    const reasons = [];
+    const isStringArray = (v) => Array.isArray(v) && v.every((item) => typeof item === 'string');
+    for (const [kind, value] of Object.entries(raw)) {
+        if (kind.trim() === '') {
+            reasons.push('kinds contains an empty kind name');
+            continue;
+        }
+        if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+            reasons.push(`kinds.${kind} must be a JSON object`);
+            continue;
+        }
+        const entry = value;
+        for (const key of Object.keys(entry)) {
+            if (!KIND_CONFIG_KEYS.has(key))
+                reasons.push(`kinds.${kind}.${key} is not a KindConfig field (expected one of: ${[...KIND_CONFIG_KEYS].join(', ')})`);
+        }
+        if (entry['whenToUse'] !== undefined && (typeof entry['whenToUse'] !== 'string' || entry['whenToUse'].trim() === '')) {
+            reasons.push(`kinds.${kind}.whenToUse must be a non-empty string`);
+        }
+        for (const field of ['model', 'orchestratorModel']) {
+            if (entry[field] !== undefined && (typeof entry[field] !== 'string' || entry[field].trim() === '')) {
+                reasons.push(`kinds.${kind}.${field} must be a non-empty string`);
+            }
+        }
+        for (const field of ['tools', 'extensions', 'availableTo']) {
+            if (entry[field] !== undefined && !isStringArray(entry[field])) {
+                reasons.push(`kinds.${kind}.${field} must be an array of strings`);
+            }
+        }
+        if (normalizeKindEntry(value) === null && normalizeKindPatch(value) === null) {
+            reasons.push(`kinds.${kind} is neither a full kind (whenToUse required) nor a patch with at least one launch field`);
+        }
+    }
+    return reasons;
+}
 /** Validate one raw `remoteCanvas.targets.<name>` entry, or drop it (return
  *  null) rather than throwing — same rule `normalizeKindEntry` follows. A
  *  valid entry needs a non-empty `previewEndpoint` and `relayTokenRef`; the
@@ -492,17 +558,16 @@ function readRawProfileConfig(profileId) {
 function readRawProjectScopeConfigs(targetCwd, targetProfileId) {
     const nearestFirst = findProjectScopeRoots(targetCwd, targetProfileId);
     const farthestFirst = [...nearestFirst].reverse();
-    const out = [];
-    for (const root of farthestFirst) {
-        const raw = readJsonIfExists(configPathFor(root));
-        if (raw !== null)
-            out.push(raw);
-    }
-    return out;
+    // A root with no config.json still contributes: its installed plugins may
+    // declare kinds, so the ROOT rides along and `raw` stays null.
+    return farthestFirst.map((root) => ({ root, raw: readJsonIfExists(configPathFor(root)) }));
 }
 /** Merge launch knobs (`kinds`, `modelLadders`) across scopes in
  *  project stack > profile > user > builtin precedence — the same precedence
- *  order used for memory resolution. A kind or ladder cell declared at a
+ *  order used for memory resolution. For `kinds` only, each plugin-bearing
+ *  scope (user, each project root) additionally layers its enabled plugins'
+ *  manifest `kinds` blocks directly BELOW that scope's own raw config — see
+ *  `layerPluginKinds`. A kind or ladder cell declared at a
  *  more-specific scope shadows the same key from a less-specific scope; the
  *  project STACK (`findProjectScopeRoots` — every ancestor `.crouter/`,
  *  widened by a selected profile's `projects`) layers nearest-root-strongest;
@@ -533,8 +598,13 @@ export function readMergedLaunchConfig(targetCwd = process.cwd(), targetProfileI
     const defaults = defaultScopeConfig();
     const userRaw = readRawScopeConfig('user');
     const profileRaw = readRawProfileConfig(targetProfileId);
-    const projectRawsFarthestFirst = readRawProjectScopeConfigs(targetCwd, targetProfileId);
-    let kinds = mergeKinds(userRaw?.kinds, defaults.kinds);
+    const projectLayersFarthestFirst = readRawProjectScopeConfigs(targetCwd, targetProfileId);
+    // Kinds layer per scope as: that scope's enabled PLUGINS first, then the
+    // scope's own raw config — so a plugin can add or shadow a kind (registry
+    // entry in its manifest + gated persona docs in its memory tree) and the
+    // scope's config.json still overrides its plugins. Other launch knobs
+    // (ladders/routes/spawnEnv) have no plugin channel.
+    let kinds = mergeKinds(userRaw?.kinds, layerPluginKinds('user', scopeRoot('user'), defaults.kinds));
     let modelLadders = mergeModelLadders(userRaw?.modelLadders, defaults.modelLadders);
     let modelRoutes = mergeModelRoutes(userRaw?.modelRoutes);
     let modelRouting = mergeModelRouting(userRaw?.modelRouting, undefined);
@@ -546,8 +616,10 @@ export function readMergedLaunchConfig(targetCwd = process.cwd(), targetProfileI
         modelRouting = mergeModelRouting(profileRaw.modelRouting, modelRouting);
         spawnEnv = mergeSpawnEnv(profileRaw.spawnEnv, spawnEnv.allow);
     }
-    for (const raw of projectRawsFarthestFirst) {
-        kinds = mergeKinds(raw.kinds, kinds);
+    for (const { root, raw } of projectLayersFarthestFirst) {
+        kinds = mergeKinds(raw?.kinds, layerPluginKinds('project', root, kinds));
+        if (raw === null)
+            continue;
         modelLadders = mergeModelLadders(raw.modelLadders, modelLadders);
         modelRoutes = mergeModelRoutes(raw.modelRoutes, modelRoutes);
         modelRouting = mergeModelRouting(raw.modelRouting, modelRouting);

package/dist/core/installed-plugins.d.ts

@@ -0,0 +1,2 @@
+import type { InstalledPlugin, Scope } from '../types.js';
+export declare function listInstalledPluginsInRoot(scope: Scope, scopeRootPath: string): InstalledPlugin[];

package/dist/core/installed-plugins.js

@@ -0,0 +1,42 @@
+// installed-plugins.ts — the LEAF-LEVEL installed-plugin reader: list the
+// plugin packages physically present under one scope root, with their
+// manifests and enabled-state from that root's config.json `plugins` block.
+//
+// This lives below resolver.ts (which re-exports it for its existing callers)
+// so that config.ts can layer plugin-declared launch config (`kinds`) into
+// `readMergedLaunchConfig` without an import cycle: resolver.ts imports
+// config.ts, so config.ts can never import resolver.ts. Imports here stay
+// leaf-safe: types, fs-utils, manifest only.
+import { join } from 'node:path';
+import { CONFIG_FILE } from '../types.js';
+import { listDirs, pathExists, readJsonIfExists } from './fs-utils.js';
+import { readPluginManifest } from './manifest.js';
+function pluginConfigForRoot(root) {
+    const cfg = readJsonIfExists(join(root, CONFIG_FILE));
+    return cfg && cfg.plugins && typeof cfg.plugins === 'object' ? cfg.plugins : {};
+}
+export function listInstalledPluginsInRoot(scope, scopeRootPath) {
+    const dir = join(scopeRootPath, 'plugins');
+    if (!pathExists(dir))
+        return [];
+    const cfg = pluginConfigForRoot(scopeRootPath);
+    const out = [];
+    for (const name of listDirs(dir)) {
+        const root = join(dir, name);
+        const manifest = readPluginManifest(root);
+        if (!manifest)
+            continue;
+        const entry = cfg[name];
+        const version = typeof entry?.version === 'string' ? entry.version : manifest.version;
+        out.push({
+            name,
+            scope,
+            root,
+            manifest,
+            enabled: typeof entry?.enabled === 'boolean' ? entry.enabled : true,
+            sourceMarketplace: typeof entry?.source_marketplace === 'string' ? entry.source_marketplace : undefined,
+            version,
+        });
+    }
+    return out;
+}

package/dist/core/resolver.d.ts

@@ -1,5 +1,5 @@
 import type { InstalledMarketplace, InstalledPlugin, Scope } from '../types.js';
-export declare function listInstalledPluginsInRoot(scope: Scope, scopeRootPath: string): InstalledPlugin[];
+export { listInstalledPluginsInRoot } from './installed-plugins.js';
 export declare function listInstalledPlugins(scope: Scope): InstalledPlugin[];
 export declare function listAllPlugins(): InstalledPlugin[];
 export declare function findPluginByName(name: string, scope?: Scope): InstalledPlugin | null;

package/dist/core/resolver.js

@@ -1,39 +1,14 @@
 import { join } from 'node:path';
-import { CONFIG_FILE } from '../types.js';
 import { readConfig } from './config.js';
-import { listDirs, pathExists, readJsonIfExists } from './fs-utils.js';
-import { readMarketplaceManifest, readPluginManifest } from './manifest.js';
+import { listDirs, pathExists } from './fs-utils.js';
+import { readMarketplaceManifest } from './manifest.js';
 import { InputError } from './io.js';
 import { marketplacesDir, projectScopeRoot, scopeRoot, userScopeRoot, } from './scope.js';
-function pluginConfigForRoot(root) {
-    const cfg = readJsonIfExists(join(root, CONFIG_FILE));
-    return cfg && cfg.plugins && typeof cfg.plugins === 'object' ? cfg.plugins : {};
-}
-export function listInstalledPluginsInRoot(scope, scopeRootPath) {
-    const dir = join(scopeRootPath, 'plugins');
-    if (!pathExists(dir))
-        return [];
-    const cfg = pluginConfigForRoot(scopeRootPath);
-    const out = [];
-    for (const name of listDirs(dir)) {
-        const root = join(dir, name);
-        const manifest = readPluginManifest(root);
-        if (!manifest)
-            continue;
-        const entry = cfg[name];
-        const version = typeof entry?.version === 'string' ? entry.version : manifest.version;
-        out.push({
-            name,
-            scope,
-            root,
-            manifest,
-            enabled: typeof entry?.enabled === 'boolean' ? entry.enabled : true,
-            sourceMarketplace: typeof entry?.source_marketplace === 'string' ? entry.source_marketplace : undefined,
-            version,
-        });
-    }
-    return out;
-}
+// Moved to installed-plugins.ts (a leaf module below config.ts) so
+// `readMergedLaunchConfig` can layer plugin-declared kinds without an import
+// cycle; re-exported here for this module's existing callers.
+export { listInstalledPluginsInRoot } from './installed-plugins.js';
+import { listInstalledPluginsInRoot } from './installed-plugins.js';
 export function listInstalledPlugins(scope) {
     // The builtin scope has no scopeRoot, so this returns [] — builtin content is
     // the memory substrate, not plugins.