@miragon/pulse-widget-shell 0.0.0-stage → 0.21.0

package/dist/composition.d.ts

@@ -0,0 +1,155 @@
+import type { AppConfig, AppConfigEntry, AppPlugin } from "@miragon/mcp-toolkit-core";
+import type { MCPServer } from "mcp-use";
+import type { ToolsetSource, ToolsetVocabulary } from "./toolsets.js";
+/**
+ * The composition-root machinery every server (the stock app AND a customer's
+ * composed server) previously copied: module selection via
+ * `MCP_ACTIVE_MODULES` (with the `module:toolset` suffix), the env-typo
+ * warner, boot warnings, and the mcp-use `AppConfig`/plugin assembly.
+ *
+ * The module PORT SHAPE lives here ({@link ComposableModule}); what stays
+ * app-owned by design is its instantiation: each composition root declares its
+ * own shared-resources type (`ComposableModule<MyShared>`), its module list,
+ * and the cross-module wiring — which module's capability reaches which other
+ * module is configuration knowledge, never a module-to-module import.
+ * Modules keep conforming STRUCTURALLY and never import this type.
+ */
+export interface ComposableModule<TShared> {
+    /** Module key used in `MCP_ACTIVE_MODULES` and as the `activeApps` entry name. */
+    name: string;
+    /** Pure env → raw-config mapping; must not read `process.env` or perform I/O side effects beyond config sources. */
+    configFromEnv(env: NodeJS.ProcessEnv): Record<string, unknown>;
+    /** Env vars this module reads — composed into the root's unknown-var typo warner. */
+    knownEnvVars: readonly string[];
+    /**
+     * The module's toolset vocabulary (`createToolsetVocabulary`). Declaring it
+     * opts the module into the `module:toolset` suffix: the composition resolves
+     * ONE concrete toolset per boot — the suffix, or the auth-dependent default,
+     * never "everything" — and threads it into `config.toolset`. Absent = the
+     * module has no toolsets: a suffix is ignored (with a warning) and its config
+     * never carries a `toolset`.
+     */
+    toolsets?: ToolsetVocabulary<string>;
+    /** Optional boot-time hints (returned, and logged by the root) for active deployments. */
+    bootWarnings?(env: NodeJS.ProcessEnv): string[];
+    /**
+     * Optional model-facing usage notes for this module — routing rules,
+     * argument conventions, which tool answers which question — joined into
+     * the server `instructions` ({@link ModuleComposition.instructions}), so
+     * the rule is stated ONCE instead of in every tool description. Receives
+     * the module's boot config (incl. its effective `toolset`) and the boot's
+     * auth mode; `undefined` contributes nothing.
+     */
+    instructions?(config: Record<string, unknown>, context: InstructionsContext): string | undefined;
+    /** Validates the raw config and builds the plugin; receives the shared resources. */
+    createPlugin(config: Record<string, unknown>, shared: TShared): AppPlugin<MCPServer>;
+}
+/** What a module's {@link ComposableModule.instructions} may depend on besides its config. */
+export interface InstructionsContext {
+    /** Whether the root installed OAuth — a caller identity (and per-user saves) exists. */
+    authenticated: boolean;
+}
+export interface ActiveModuleRef {
+    name: string;
+    /**
+     * The raw toolset suffix from the `module:toolset` syntax, e.g.
+     * `camunda7:read-only` — trimmed, and kept even when EMPTY (`camunda7:` →
+     * `""`), so an empty suffix fails closed like an unknown one instead of
+     * reading as "no suffix". Absent = no suffix: the auth-dependent default.
+     */
+    toolset?: string;
+}
+/** The toolset one active module runs with — one entry of the boot log. */
+export interface EffectiveToolset {
+    module: string;
+    /** The concrete toolset; absent for a module without toolsets. */
+    toolset?: string;
+    /**
+     * Why: the suffix named it, the auth-dependent default applied, an empty or
+     * unknown suffix fell back to the floor — or `none` for a module without
+     * toolsets.
+     */
+    source: ToolsetSource | "none";
+    /**
+     * Whether the toolset permits durable writes. A module without toolsets
+     * declares no restriction (`true`).
+     */
+    durableWrites: boolean;
+}
+/** One boot's module selection, resolved ONCE by the composition root. */
+export interface ResolvedBoot {
+    /** Whether the root installed OAuth (a caller identity exists). */
+    authenticated: boolean;
+    /** The active modules' mcp-use config entries, each carrying its effective toolset. */
+    entries: AppConfigEntry[];
+    toolsets: EffectiveToolset[];
+}
+export interface ResolveBootOptions {
+    /**
+     * Whether the composition root INSTALLED OAuth on `/mcp`. Only the root
+     * knows — never infer it from an env var the root may not honor (a server
+     * without OAuth wiring would read a stray `MCP_OAUTH` as authenticated and
+     * fail open). Omitted = `false`, the fail-closed reading.
+     */
+    authenticated?: boolean;
+}
+/**
+ * All members are `this`-free closures (function properties, not methods), so
+ * composition roots may destructure or re-export them directly
+ * (`export const warnUnknownEnvVars = composition.warnUnknownEnvVars`).
+ */
+export interface ModuleComposition<TShared> {
+    /** Every known env var: the root's own plus each module's slice. */
+    knownEnvVars: ReadonlySet<string>;
+    /** The `MCP_ACTIVE_MODULES` selection (unset/`all` = every module); unknown names warn and are skipped. */
+    activeModules: (env?: NodeJS.ProcessEnv) => ActiveModuleRef[];
+    /**
+     * Resolve the boot ONCE: every toolset-bearing module gets a concrete
+     * effective toolset in its config (suffix → itself; empty/unknown → the
+     * module's floor, with one warning; none → the floor without OAuth, the
+     * module's standard toolset with it). Call it once per boot and derive
+     * plugins, `AppConfig` and the boot log from the result.
+     */
+    resolveBoot: (env?: NodeJS.ProcessEnv, options?: ResolveBootOptions) => ResolvedBoot;
+    /** `resolveBoot(env, options).entries`. */
+    appEntries: (env?: NodeJS.ProcessEnv, options?: ResolveBootOptions) => AppConfigEntry[];
+    appConfig: (env?: NodeJS.ProcessEnv, options?: ResolveBootOptions) => AppConfig;
+    /** Instantiate the active modules' plugins with the root's shared resources. */
+    pluginsFor: (entries: AppConfigEntry[], shared: TShared) => AppPlugin<MCPServer>[];
+    /** Report unknown env vars under any watched prefix; returns the offenders. */
+    warnUnknownEnvVars: (env?: NodeJS.ProcessEnv, extraKnown?: Iterable<string>) => string[];
+    /** Collect + log the active modules' boot-time hints. */
+    emitBootWarnings: (env?: NodeJS.ProcessEnv) => string[];
+    /** Log (console.info) and return the one boot line that states each active module's effective toolset. */
+    logEffectiveToolsets: (boot: ResolvedBoot) => string;
+    /**
+     * The active modules' instruction snippets for this boot, in module order,
+     * joined by a blank line — `undefined` when none contributes. The root
+     * prepends its own preamble (`createComposedServer` does).
+     */
+    instructions: (boot: ResolvedBoot) => string | undefined;
+}
+export declare function composeModules<TShared>(options: {
+    /** Log prefix for every warning, e.g. `pulse`. */
+    label: string;
+    modules: readonly ComposableModule<TShared>[];
+    /** The root's own env vars (module vars come from each module's `knownEnvVars`). */
+    appEnvVars?: readonly string[];
+    /**
+     * Prefixes owned by dependencies, exempt from the typo warner
+     * (mcp-use itself + the dev inspector by default).
+     */
+    foreignEnvPrefixes?: readonly string[];
+    /** Optional pointer appended to the unknown-var warning, e.g. `see docs/operations.md`. */
+    envVarHint?: string;
+}): ModuleComposition<TShared>;
+/**
+ * Whether the server may register FRAMEWORK durable writes — the toolkit
+ * builder's `save-dashboard`/`delete-dashboard` and the shell's
+ * `shell_save_settings`, which no module toolset filters. Only with a caller
+ * identity (records are keyed by user; without OAuth every record is shared
+ * and ownerless) and only when no active module sits on its read-only floor:
+ * the most restrictive module wins.
+ */
+export declare function frameworkWritesAllowed(boot: ResolvedBoot): boolean;
+//# sourceMappingURL=composition.d.ts.map

package/dist/composition.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"composition.d.ts","sourceRoot":"","sources":["../src/composition.ts"],"names":[],"mappings":"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"}

package/dist/composition.js

@@ -0,0 +1,163 @@
+export function composeModules(options) {
+    const { label, modules, appEnvVars = [], foreignEnvPrefixes = ["MCP_USE_", "MCP_INSPECTOR_"], envVarHint, } = options;
+    const registry = Object.fromEntries(modules.map((m) => [m.name, m]));
+    const knownEnvVars = new Set([...appEnvVars, ...modules.flatMap((m) => [...m.knownEnvVars])]);
+    // Watched prefixes derive from every known var (NOTES_TITLE contributes
+    // NOTES_, PROMETHEUS_URL contributes PROMETHEUS_, …) so custom modules get
+    // the same typo coverage as the CAMUNDA_/MCP_ families — a hardcoded prefix
+    // list would silently exempt every non-Camunda module.
+    const watchedPrefixes = [
+        ...new Set([...knownEnvVars]
+            .map((name) => name.slice(0, name.indexOf("_") + 1))
+            .filter((prefix) => prefix.length > 1)),
+    ];
+    /**
+     * `MCP_ACTIVE_MODULES` → the known modules (with their raw suffix) and the
+     * unknown names. Deliberately not the toolkit's `parseActiveModules`: that
+     * one reads an empty qualifier (`camunda7:`) as no qualifier, which would
+     * turn it into the auth-dependent default instead of failing closed. A name
+     * that appears twice is refused — two entries would build two plugins with
+     * colliding steps, and which suffix wins would be a guess.
+     */
+    const parseActiveModules = (env) => {
+        const envValue = env.MCP_ACTIVE_MODULES?.trim();
+        if (!envValue || envValue === "all") {
+            return { known: modules.map(({ name }) => ({ name })), unknown: [] };
+        }
+        const refs = envValue
+            .split(",")
+            .map((s) => s.trim())
+            .filter(Boolean)
+            .map((entry) => {
+            // Everything after the FIRST colon is the suffix, kept even when empty
+            // or when it contains further colons — both are then unknown toolset
+            // names and fail closed, instead of reading as "no suffix".
+            const colon = entry.indexOf(":");
+            if (colon === -1)
+                return { name: entry };
+            return { name: entry.slice(0, colon).trim(), toolset: entry.slice(colon + 1).trim() };
+        });
+        const repeated = [...new Set(refs.map(({ name }) => name))].filter((name) => refs.filter((ref) => ref.name === name).length > 1);
+        if (repeated.length > 0) {
+            throw new Error(`[${label}] MCP_ACTIVE_MODULES names ${repeated.map((name) => `"${name}"`).join(", ")} more than once — list each module once, with at most one :toolset.`);
+        }
+        return {
+            known: refs.filter(({ name }) => registry[name]),
+            unknown: refs.filter(({ name }) => !registry[name]).map(({ name }) => name),
+        };
+    };
+    /** The known active modules; the unknown ones warn once per boot, in `emitBootWarnings`. */
+    const activeModules = (env = process.env) => parseActiveModules(env).known;
+    // The one place a suffix becomes a toolset: per module, per boot.
+    const effectiveToolset = (module, suffix, authenticated) => {
+        const vocabulary = module.toolsets;
+        if (vocabulary) {
+            const { toolset, source } = vocabulary.effective(suffix, { authenticated });
+            return {
+                module: module.name,
+                toolset,
+                source,
+                durableWrites: vocabulary.allowsDurableWrites(toolset),
+            };
+        }
+        if (suffix !== undefined) {
+            console.warn(`[${label}] Module "${module.name}" has no toolsets — ignoring ":${suffix}"`);
+        }
+        return { module: module.name, source: "none", durableWrites: true };
+    };
+    const resolveBoot = (env = process.env, { authenticated = false } = {}) => {
+        const toolsets = [];
+        const entries = activeModules(env).map(({ name, toolset: suffix }) => {
+            const effective = effectiveToolset(registry[name], suffix, authenticated);
+            toolsets.push(effective);
+            const { toolset } = effective;
+            return {
+                app: name,
+                config: {
+                    ...registry[name].configFromEnv(env),
+                    ...(toolset === undefined ? {} : { toolset }),
+                },
+            };
+        });
+        return { authenticated, entries, toolsets };
+    };
+    const appEntries = (env, options) => resolveBoot(env, options).entries;
+    return {
+        knownEnvVars,
+        activeModules,
+        resolveBoot,
+        appEntries,
+        appConfig(env, options) {
+            return { activeApps: appEntries(env, options), pipelines: {} };
+        },
+        pluginsFor(entries, shared) {
+            return entries
+                .filter((entry) => registry[entry.app])
+                .map((entry) => registry[entry.app].createPlugin(entry.config, shared));
+        },
+        warnUnknownEnvVars(env = process.env, extraKnown = []) {
+            const known = new Set([...knownEnvVars, ...extraKnown]);
+            // `<KNOWN_VAR>_*` extensions (DATABASE_URL_FILE, REDIS_URL_2, …) are
+            // conventions addressed at OTHER processes — docker secrets, sidecars —
+            // never a typo of the var they extend, so they don't warn.
+            const extendsKnownVar = (name) => [...known].some((knownName) => name.startsWith(`${knownName}_`));
+            const unknown = Object.keys(env).filter((name) => watchedPrefixes.some((prefix) => name.startsWith(prefix)) &&
+                !known.has(name) &&
+                !extendsKnownVar(name) &&
+                !foreignEnvPrefixes.some((prefix) => name.startsWith(prefix)));
+            for (const name of unknown) {
+                console.warn(`[${label}] Unknown environment variable "${name}" — the server does not read it; ` +
+                    `check for a typo${envVarHint ? ` (${envVarHint})` : ""}.`);
+            }
+            return unknown;
+        },
+        emitBootWarnings(env = process.env) {
+            // Deliberately separate from `configFromEnv` (which runs inside
+            // `resolveBoot` and stays side-effect free).
+            const { known, unknown } = parseActiveModules(env);
+            const warnings = [
+                ...unknown.map((name) => `Unknown module "${name}" in MCP_ACTIVE_MODULES — skipping`),
+                ...known.flatMap(({ name }) => registry[name].bootWarnings?.(env) ?? []),
+            ];
+            for (const warning of warnings) {
+                console.warn(`[${label}] ${warning}`);
+            }
+            return warnings;
+        },
+        logEffectiveToolsets(boot) {
+            // console.info, deliberately not a boot WARNING: it states the surface
+            // on every boot, the restrictive default included.
+            const describe = ({ module, toolset, source }) => {
+                if (toolset === undefined)
+                    return `${module} (no toolsets)`;
+                if (source === "default") {
+                    return `${module}:${toolset} (default ${boot.authenticated ? "with" : "without"} OAuth)`;
+                }
+                return `${module}:${toolset} (${source})`;
+            };
+            const modules = boot.toolsets.map(describe).join(", ");
+            const line = `[${label}] Toolsets — ${modules || "no active modules"}`;
+            console.info(line);
+            return line;
+        },
+        instructions(boot) {
+            const context = { authenticated: boot.authenticated };
+            const snippets = boot.entries
+                .map((entry) => registry[entry.app]?.instructions?.(entry.config, context)?.trim())
+                .filter((snippet) => Boolean(snippet));
+            return snippets.length > 0 ? snippets.join("\n\n") : undefined;
+        },
+    };
+}
+/**
+ * Whether the server may register FRAMEWORK durable writes — the toolkit
+ * builder's `save-dashboard`/`delete-dashboard` and the shell's
+ * `shell_save_settings`, which no module toolset filters. Only with a caller
+ * identity (records are keyed by user; without OAuth every record is shared
+ * and ownerless) and only when no active module sits on its read-only floor:
+ * the most restrictive module wins.
+ */
+export function frameworkWritesAllowed(boot) {
+    return boot.authenticated && boot.toolsets.every(({ durableWrites }) => durableWrites);
+}
+//# sourceMappingURL=composition.js.map

package/dist/composition.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"composition.js","sourceRoot":"","sources":["../src/composition.ts"],"names":[],"mappings":"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"}

package/dist/composition.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=composition.test.d.ts.map

package/dist/composition.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"composition.test.d.ts","sourceRoot":"","sources":["../src/composition.test.ts"],"names":[],"mappings":""}

package/dist/composition.test.js

@@ -0,0 +1,275 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { composeModules, frameworkWritesAllowed, } from "./composition.js";
+import { createToolsetVocabulary } from "./toolsets.js";
+const moduleOf = (name, overrides = {}) => ({
+    name,
+    configFromEnv: (env) => ({ url: env[`${name.toUpperCase()}_URL`] ?? "default" }),
+    knownEnvVars: [`${name.toUpperCase()}_URL`],
+    toolsets: createToolsetVocabulary(name, ["read-only", "operations", "admin"], "read-only", {
+        authenticatedDefault: "operations",
+    }),
+    createPlugin: (config, shared) => ({ definition: { name }, config, shared }),
+    ...overrides,
+});
+const compose = (modules = [moduleOf("alpha"), moduleOf("beta")]) => composeModules({
+    label: "test-root",
+    modules,
+    appEnvVars: ["MCP_ACTIVE_MODULES", "MCP_PROFILE_DIR"],
+});
+afterEach(() => {
+    vi.restoreAllMocks();
+});
+describe("activeModules / appEntries", () => {
+    it("activates every module when MCP_ACTIVE_MODULES is unset or 'all'", () => {
+        expect(compose().activeModules({})).toEqual([{ name: "alpha" }, { name: "beta" }]);
+        expect(compose().activeModules({ MCP_ACTIVE_MODULES: "all" })).toEqual([
+            { name: "alpha" },
+            { name: "beta" },
+        ]);
+    });
+    it("parses the comma list with optional module:toolset suffixes", () => {
+        expect(compose().activeModules({ MCP_ACTIVE_MODULES: "beta:read-only, alpha" })).toEqual([
+            { name: "beta", toolset: "read-only" },
+            { name: "alpha" },
+        ]);
+    });
+    it("keeps an EMPTY suffix distinct from no suffix, trims both halves, keeps extra colons", () => {
+        expect(compose().activeModules({ MCP_ACTIVE_MODULES: "alpha:, beta : admin:read-only" })).toEqual([
+            { name: "alpha", toolset: "" },
+            { name: "beta", toolset: "admin:read-only" },
+        ]);
+    });
+    it("skips unknown modules, warning ONCE per boot in the boot warnings", () => {
+        const warn = vi.spyOn(console, "warn").mockImplementation(() => { });
+        const env = { MCP_ACTIVE_MODULES: "nope:read-only,alpha" };
+        const composition = compose();
+        expect(composition.activeModules(env)).toEqual([{ name: "alpha" }]);
+        composition.resolveBoot(env);
+        expect(warn).not.toHaveBeenCalled();
+        composition.emitBootWarnings(env);
+        expect(warn).toHaveBeenCalledOnce();
+        expect(warn).toHaveBeenCalledWith(expect.stringContaining('[test-root] Unknown module "nope"'));
+    });
+    it("refuses a module named twice, whichever suffixes it carries", () => {
+        for (const value of ["alpha,alpha:read-only", "alpha:admin, beta, alpha"]) {
+            expect(() => compose().resolveBoot({ MCP_ACTIVE_MODULES: value })).toThrow(/MCP_ACTIVE_MODULES names "alpha" more than once/);
+        }
+    });
+    it("threads the EFFECTIVE toolset into every module config; config comes from configFromEnv(env)", () => {
+        const entries = compose().appEntries({
+            MCP_ACTIVE_MODULES: "alpha:admin,beta",
+            ALPHA_URL: "http://a",
+        });
+        expect(entries).toEqual([
+            { app: "alpha", config: { url: "http://a", toolset: "admin" } },
+            { app: "beta", config: { url: "default", toolset: "read-only" } },
+        ]);
+    });
+    it("strips the toolset suffix (warning) for modules without toolsets", () => {
+        const warn = vi.spyOn(console, "warn").mockImplementation(() => { });
+        const modules = [moduleOf("alpha", { toolsets: undefined })];
+        const entries = compose(modules).appEntries({ MCP_ACTIVE_MODULES: "alpha:read-only" });
+        expect(entries[0].config).not.toHaveProperty("toolset");
+        expect(warn).toHaveBeenCalledWith('[test-root] Module "alpha" has no toolsets — ignoring ":read-only"');
+    });
+    it("passes no raw suffix through: the removed supportsToolsets flag makes no module toolset-bearing", () => {
+        // The pass-through is gone — a module declares a `toolsets` vocabulary
+        // or has none. A definition still carrying the old flag is a module
+        // WITHOUT toolsets: its suffix is ignored (warning) and its config never
+        // carries an unresolved name it might read as "everything".
+        const warn = vi.spyOn(console, "warn").mockImplementation(() => { });
+        const stale = { ...moduleOf("alpha", { toolsets: undefined }), supportsToolsets: true };
+        const composition = compose([stale]);
+        const boot = composition.resolveBoot({ MCP_ACTIVE_MODULES: "alpha:admin" }, { authenticated: true });
+        expect(boot.entries[0].config).not.toHaveProperty("toolset");
+        expect(boot.toolsets).toEqual([{ module: "alpha", source: "none", durableWrites: true }]);
+        expect(warn).toHaveBeenCalledTimes(1);
+        expect(warn).toHaveBeenCalledWith('[test-root] Module "alpha" has no toolsets — ignoring ":admin"');
+        vi.spyOn(console, "info").mockImplementation(() => { });
+        expect(composition.logEffectiveToolsets(boot)).toBe("[test-root] Toolsets — alpha (no toolsets)");
+    });
+    it("appConfig wraps the entries in the mcp-use shape", () => {
+        expect(compose().appConfig({ MCP_ACTIVE_MODULES: "alpha" })).toEqual({
+            activeApps: [{ app: "alpha", config: { url: "default", toolset: "read-only" } }],
+            pipelines: {},
+        });
+        expect(compose().appConfig({ MCP_ACTIVE_MODULES: "alpha" }, { authenticated: true })).toEqual({
+            activeApps: [{ app: "alpha", config: { url: "default", toolset: "operations" } }],
+            pipelines: {},
+        });
+    });
+});
+describe("resolveBoot — the fail-closed toolset rule", () => {
+    const toolsetsOf = (boot) => Object.fromEntries(boot.toolsets.map(({ module, toolset }) => [module, toolset]));
+    it.each([undefined, "", "all", "alpha,beta"])("MCP_ACTIVE_MODULES=%j defaults to the floor without OAuth and to the standard toolset with it — never admin", (value) => {
+        const env = value === undefined ? {} : { MCP_ACTIVE_MODULES: value };
+        const anonymous = compose().resolveBoot(env);
+        expect(anonymous.authenticated).toBe(false);
+        expect(toolsetsOf(anonymous)).toEqual({ alpha: "read-only", beta: "read-only" });
+        expect(anonymous.toolsets.every(({ source }) => source === "default")).toBe(true);
+        expect(toolsetsOf(compose().resolveBoot(env, { authenticated: true }))).toEqual({
+            alpha: "operations",
+            beta: "operations",
+        });
+    });
+    it.each(["alpha:,beta:", "alpha: ,beta:  ", "alpha:bogus,beta:admin:read-only"])("empty or unknown suffixes (%j) fail closed to the floor, even under OAuth", (value) => {
+        vi.spyOn(console, "warn").mockImplementation(() => { });
+        const boot = compose().resolveBoot({ MCP_ACTIVE_MODULES: value }, { authenticated: true });
+        expect(toolsetsOf(boot)).toEqual({ alpha: "read-only", beta: "read-only" });
+        expect(boot.toolsets.every(({ source }) => source === "fallback")).toBe(true);
+        expect(boot.entries.map(({ config }) => config.toolset)).toEqual(["read-only", "read-only"]);
+    });
+    it("an explicit suffix wins over the default in both auth modes", () => {
+        for (const authenticated of [false, true]) {
+            const boot = compose().resolveBoot({ MCP_ACTIVE_MODULES: "alpha:admin,beta:read-only" }, { authenticated });
+            expect(toolsetsOf(boot)).toEqual({ alpha: "admin", beta: "read-only" });
+            expect(boot.toolsets.map(({ source }) => source)).toEqual(["suffix", "suffix"]);
+        }
+    });
+    it("warns ONCE per boot for an unknown suffix", () => {
+        const warn = vi.spyOn(console, "warn").mockImplementation(() => { });
+        compose().resolveBoot({ MCP_ACTIVE_MODULES: "alpha:typo" });
+        expect(warn).toHaveBeenCalledTimes(1);
+        expect(warn).toHaveBeenCalledWith(expect.stringContaining('[alpha] Unknown toolset "typo"'));
+    });
+    it("reports whether each effective toolset permits durable writes", () => {
+        const boot = compose().resolveBoot({ MCP_ACTIVE_MODULES: "alpha:operations,beta" });
+        expect(boot.toolsets).toEqual([
+            { module: "alpha", toolset: "operations", source: "suffix", durableWrites: true },
+            { module: "beta", toolset: "read-only", source: "default", durableWrites: false },
+        ]);
+    });
+    it("leaves modules without toolsets unrestricted and toolset-free", () => {
+        const boot = compose([moduleOf("alpha", { toolsets: undefined })]).resolveBoot({});
+        expect(boot.toolsets).toEqual([{ module: "alpha", source: "none", durableWrites: true }]);
+        expect(boot.entries[0].config).not.toHaveProperty("toolset");
+    });
+});
+describe("logEffectiveToolsets", () => {
+    it("logs ONE info line naming each module's toolset and why", () => {
+        const info = vi.spyOn(console, "info").mockImplementation(() => { });
+        const warn = vi.spyOn(console, "warn").mockImplementation(() => { });
+        const modules = [
+            moduleOf("alpha"),
+            moduleOf("beta"),
+            moduleOf("gamma", { toolsets: undefined }),
+        ];
+        const composition = compose(modules);
+        const boot = composition.resolveBoot({ MCP_ACTIVE_MODULES: "alpha:admin,beta:typo,gamma" });
+        const line = composition.logEffectiveToolsets(boot);
+        expect(line).toBe("[test-root] Toolsets — alpha:admin (suffix), beta:read-only (fallback), gamma (no toolsets)");
+        expect(info).toHaveBeenCalledTimes(1);
+        expect(info).toHaveBeenCalledWith(line);
+        expect(warn).toHaveBeenCalledTimes(1); // the typo, nothing from the log itself
+    });
+    it("names the auth mode behind a default", () => {
+        vi.spyOn(console, "info").mockImplementation(() => { });
+        const composition = compose([moduleOf("alpha"), moduleOf("beta", { toolsets: undefined })]);
+        const env = { MCP_ACTIVE_MODULES: "alpha,beta" };
+        expect(composition.logEffectiveToolsets(composition.resolveBoot(env))).toBe("[test-root] Toolsets — alpha:read-only (default without OAuth), beta (no toolsets)");
+        expect(composition.logEffectiveToolsets(composition.resolveBoot(env, { authenticated: true }))).toBe("[test-root] Toolsets — alpha:operations (default with OAuth), beta (no toolsets)");
+    });
+    it("says so when no module is active", () => {
+        vi.spyOn(console, "info").mockImplementation(() => { });
+        vi.spyOn(console, "warn").mockImplementation(() => { });
+        const composition = compose();
+        expect(composition.logEffectiveToolsets(composition.resolveBoot({ MCP_ACTIVE_MODULES: "nope" }))).toBe("[test-root] Toolsets — no active modules");
+    });
+});
+describe("instructions", () => {
+    const instructed = (name) => moduleOf(name, {
+        instructions: (config, { authenticated }) => `${name}: toolset ${String(config.toolset)}, url ${String(config.url)}, ` +
+            `${authenticated ? "signed in" : "anonymous"}`,
+    });
+    it("joins the ACTIVE modules' snippets in selection order, each from its own boot config", () => {
+        const composition = compose([instructed("alpha"), instructed("beta"), instructed("gamma")]);
+        const boot = composition.resolveBoot({ MCP_ACTIVE_MODULES: "beta:admin,alpha", ALPHA_URL: "http://a" }, { authenticated: true });
+        expect(composition.instructions(boot)).toBe("beta: toolset admin, url default, signed in\n\n" +
+            "alpha: toolset operations, url http://a, signed in");
+    });
+    it("skips modules without a snippet or with an empty one; none at all is undefined", () => {
+        const composition = compose([
+            instructed("alpha"),
+            moduleOf("beta"),
+            moduleOf("gamma", { instructions: () => "  " }),
+        ]);
+        expect(composition.instructions(composition.resolveBoot({}))).toBe("alpha: toolset read-only, url default, anonymous");
+        expect(composition.instructions(composition.resolveBoot({ MCP_ACTIVE_MODULES: "beta,gamma" }))).toBeUndefined();
+    });
+});
+describe("frameworkWritesAllowed", () => {
+    const boot = (authenticated, env) => compose([
+        moduleOf("alpha"),
+        moduleOf("beta"),
+        moduleOf("gamma", { toolsets: undefined }),
+    ]).resolveBoot(env, { authenticated });
+    it("requires OAuth — without a caller identity framework records are ownerless", () => {
+        expect(frameworkWritesAllowed(boot(false, { MCP_ACTIVE_MODULES: "alpha:admin,beta:admin" }))).toBe(false);
+    });
+    it("allows them under OAuth when every module permits durable writes", () => {
+        expect(frameworkWritesAllowed(boot(true, {}))).toBe(true);
+        expect(frameworkWritesAllowed(boot(true, { MCP_ACTIVE_MODULES: "alpha:admin,gamma" }))).toBe(true);
+    });
+    it("refuses them when ANY module sits on its read-only floor — the most restrictive wins", () => {
+        expect(frameworkWritesAllowed(boot(true, { MCP_ACTIVE_MODULES: "alpha:admin,beta:read-only" }))).toBe(false);
+    });
+});
+describe("pluginsFor", () => {
+    it("instantiates each entry's plugin with the shared resources", () => {
+        const composition = compose();
+        const entries = composition.appEntries({ MCP_ACTIVE_MODULES: "beta" });
+        const plugins = composition.pluginsFor(entries, { tag: "shared-1" });
+        expect(plugins).toHaveLength(1);
+        expect(plugins[0]).toMatchObject({ shared: { tag: "shared-1" } });
+    });
+});
+describe("warnUnknownEnvVars", () => {
+    it("watches every prefix derived from known vars, not just a hardcoded family", () => {
+        const warn = vi.spyOn(console, "warn").mockImplementation(() => { });
+        const unknown = compose().warnUnknownEnvVars({
+            ALPHA_URLX: "typo", // derived prefix ALPHA_
+            MCP_PROFILE_DIRX: "typo", // derived prefix MCP_
+            PATH: "/usr/bin", // unwatched prefix
+            BETA_URL: "http://ok", // known
+        });
+        expect(unknown.sort()).toEqual(["ALPHA_URLX", "MCP_PROFILE_DIRX"]);
+        expect(warn).toHaveBeenCalledTimes(2);
+    });
+    it("exempts foreign prefixes and honors the extra allowlist", () => {
+        expect(compose().warnUnknownEnvVars({ MCP_USE_ANONYMIZED_TELEMETRY: "false", MCP_SECRET: "x" }, [
+            "MCP_SECRET",
+        ])).toEqual([]);
+    });
+    it("exempts `<KNOWN_VAR>_*` extensions (docker-secrets style), but not near-misses", () => {
+        const warn = vi.spyOn(console, "warn").mockImplementation(() => { });
+        const unknown = compose().warnUnknownEnvVars({
+            BETA_URL_FILE: "/run/secrets/beta", // extends the known BETA_URL — another process's var
+            BETA_URLX: "typo", // near-miss, not an extension — still warns
+        });
+        expect(unknown).toEqual(["BETA_URLX"]);
+        expect(warn).toHaveBeenCalledTimes(1);
+    });
+    it("appends the optional hint to the warning", () => {
+        const warn = vi.spyOn(console, "warn").mockImplementation(() => { });
+        composeModules({
+            label: "test-root",
+            modules: [moduleOf("alpha")],
+            envVarHint: "see docs/operations.md",
+        }).warnUnknownEnvVars({ ALPHA_TYPO: "x" });
+        expect(warn).toHaveBeenCalledWith(expect.stringContaining("(see docs/operations.md)"));
+    });
+});
+describe("emitBootWarnings", () => {
+    it("collects and logs hints from ACTIVE modules only", () => {
+        const warn = vi.spyOn(console, "warn").mockImplementation(() => { });
+        const modules = [
+            moduleOf("alpha", { bootWarnings: () => ["alpha hint"] }),
+            moduleOf("beta", { bootWarnings: () => ["beta hint"] }),
+        ];
+        const warnings = compose(modules).emitBootWarnings({ MCP_ACTIVE_MODULES: "beta" });
+        expect(warnings).toEqual(["beta hint"]);
+        expect(warn).toHaveBeenCalledWith("[test-root] beta hint");
+        expect(warn).not.toHaveBeenCalledWith(expect.stringContaining("alpha hint"));
+    });
+});
+//# sourceMappingURL=composition.test.js.map