@geraldmaron/construct 1.4.1 → 1.5.0

package/lib/packs/loader.mjs

@@ -0,0 +1,176 @@
+/**
+ * lib/packs/loader.mjs — pack manifest directory loader and merger.
+ *
+ * Three manifest tiers exist: builtin (shipped with Construct), user (in
+ * ~/.config/construct/packs/), and project (in .cx/packs/). Project packs
+ * take highest precedence; user packs override builtin. The core pack is
+ * programmatically injected at the builtin tier via loadCorePack().
+ *
+ * `loadPacksFromDir` reads every subdirectory containing pack.manifest.json
+ * and validates each one. `mergePackTiers` merges the three tiers by id.
+ * `resolvePackDirs` returns the canonical paths for each tier.
+ * `loadAllPacks` is a convenience that loads from all tiers.
+ *
+ * Prompt validation (LMCP-E2): in team/enterprise deployment mode a pack whose
+ * declared prompt files are missing or lack valid frontmatter is rejected at
+ * load time — the error names the missing file — rather than letting the
+ * worker discover the gap mid-run and silently substitute a generic persona.
+ * Solo mode does not hard-fail here; the worker records the miss as a visible
+ * degraded fallback instead (lib/orchestration/worker.mjs).
+ *
+ * embedBindings validation (LMCP-E4): every pack's `embedBindings` block is
+ * cross-checked against the builtin extension manifests (lib/extensions) so
+ * a binding naming an unknown provider id or an undeclared capability fails
+ * pack validation with a path, rather than the authority guard discovering
+ * the gap at proposal time.
+ */
+
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { validatePackManifest } from './validate.mjs';
+import { validatePackPrompts } from './prompts.mjs';
+import { loadCorePack } from './core-pack.mjs';
+import { getDeploymentMode } from '../deployment-mode.mjs';
+import { loadManifestsFromDir, resolveManifestDirs } from '../extensions/loader.mjs';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const PACKAGE_ROOT = resolve(__dirname, '..', '..');
+
+const PROMPT_HARD_FAIL_MODES = new Set(['team', 'enterprise']);
+
+/**
+ * Load builtin extension manifests keyed by id, for embedBindings
+ * cross-validation. Only the builtin tier is consulted — the same set every
+ * `construct doctor` / pack loader run sees, independent of project overrides.
+ */
+function loadKnownProviderManifests(packageRoot) {
+  const { builtin } = resolveManifestDirs({ rootDir: packageRoot });
+  const { manifests } = loadManifestsFromDir(builtin);
+  const byId = {};
+  for (const m of manifests) byId[m.id] = m;
+  return byId;
+}
+
+export function loadPacksFromDir(packsBaseDir, opts = {}) {
+  const packs = [];
+  const errors = [];
+
+  if (!existsSync(packsBaseDir)) {
+    return { packs, errors };
+  }
+
+  let entries;
+  try {
+    entries = readdirSync(packsBaseDir, { withFileTypes: true });
+  } catch (err) {
+    errors.push(`${packsBaseDir}: failed to read directory (${err.message})`);
+    return { packs, errors };
+  }
+
+  const packDirs = entries.filter(e => e.isDirectory()).map(e => join(packsBaseDir, e.name)).sort();
+  const deploymentMode = opts.deploymentMode || getDeploymentMode(opts.env);
+  const packageRoot = opts.packageRoot || PACKAGE_ROOT;
+  const knownProviders = opts.knownProviders || loadKnownProviderManifests(packageRoot);
+
+  for (const packDir of packDirs) {
+    const manifestPath = join(packDir, 'pack.manifest.json');
+    if (!existsSync(manifestPath)) continue;
+
+    let parsed;
+    try {
+      parsed = JSON.parse(readFileSync(manifestPath, 'utf8'));
+    } catch (err) {
+      errors.push(`${manifestPath}: failed to parse JSON (${err.message})`);
+      continue;
+    }
+
+    const result = validatePackManifest(parsed, { filePath: manifestPath, strict: opts.strict, knownProviders });
+    if (!result.valid) {
+      errors.push(...result.errors);
+      continue;
+    }
+
+    if (PROMPT_HARD_FAIL_MODES.has(deploymentMode)) {
+      const promptResult = validatePackPrompts({ ...parsed, _packDir: packDir }, { packageRoot });
+      if (!promptResult.valid) {
+        errors.push(...promptResult.errors.map((e) => `${manifestPath}: ${e}`));
+        continue;
+      }
+    }
+
+    packs.push({ ...parsed, _tier: opts.tier || 'unknown', _manifestPath: manifestPath, _packDir: packDir });
+  }
+
+  return { packs, errors };
+}
+
+export function mergePackTiers(builtin = [], user = [], project = []) {
+  const map = new Map();
+
+  for (const p of builtin) map.set(p.id, p);
+  for (const p of user) map.set(p.id, p);
+  for (const p of project) map.set(p.id, p);
+
+  return [...map.values()];
+}
+
+export function resolvePackDirs({ rootDir, homeDir } = {}) {
+  const home = homeDir ?? (process.env.HOME || process.env.USERPROFILE || '');
+
+  return {
+    builtin: join(PACKAGE_ROOT, 'lib', 'packs', 'manifests'),
+    user: join(home, '.config', 'construct', 'packs'),
+    project: join(rootDir || process.cwd(), '.cx', 'packs'),
+  };
+}
+
+export function loadAllPacks(opts = {}) {
+  const dirs = resolvePackDirs(opts);
+  const allErrors = [];
+  const deploymentMode = opts.deploymentMode || getDeploymentMode(opts.env);
+  const packageRoot = opts.packageRoot || PACKAGE_ROOT;
+  const knownProviders = opts.knownProviders || loadKnownProviderManifests(packageRoot);
+
+  const builtinResult = loadPacksFromDir(dirs.builtin, { ...opts, tier: 'builtin', deploymentMode, packageRoot, knownProviders });
+  allErrors.push(...builtinResult.errors);
+
+  const userResult = loadPacksFromDir(dirs.user, { ...opts, tier: 'user', deploymentMode, packageRoot, knownProviders });
+  allErrors.push(...userResult.errors);
+
+  const projectResult = loadPacksFromDir(dirs.project, { ...opts, tier: 'project', deploymentMode, packageRoot, knownProviders });
+  allErrors.push(...projectResult.errors);
+
+  const corePack = loadCorePack(packageRoot);
+  let builtinPacks = [...builtinResult.packs, corePack];
+
+  // The core pack ships with Construct and is not read from a manifest file,
+  // bypassing loadPacksFromDir's validation loop above; the same hard-fail
+  // check still applies under team/enterprise, naming the missing file. The
+  // same is true of embedBindings — validated explicitly here so an unknown
+  // provider id or undeclared capability in the core pack's own bindings
+  // fails loudly instead of silently granting excess authority.
+  if (PROMPT_HARD_FAIL_MODES.has(deploymentMode)) {
+    const coreResult = validatePackPrompts(corePack, { packageRoot });
+    if (!coreResult.valid) {
+      allErrors.push(...coreResult.errors.map((e) => `${corePack._sourceDir || '@construct/core'}: ${e}`));
+      builtinPacks = builtinResult.packs;
+    }
+  }
+
+  if (corePack.embedBindings) {
+    const coreBindingResult = validatePackManifest(
+      { id: corePack.id, version: corePack.version, compatVersion: corePack.compatVersion, embedBindings: corePack.embedBindings },
+      { filePath: corePack._sourceDir || '@construct/core', knownProviders }
+    );
+    if (!coreBindingResult.valid) {
+      allErrors.push(...coreBindingResult.errors);
+      builtinPacks = builtinPacks.filter((p) => p.id !== corePack.id);
+    }
+  }
+
+  const merged = mergePackTiers(builtinPacks, userResult.packs, projectResult.packs);
+
+  return { packs: merged, errors: allErrors };
+}

package/lib/packs/manifest-schema.mjs

@@ -0,0 +1,58 @@
+/**
+ * lib/packs/manifest-schema.mjs — canonical pack manifest schema descriptor.
+ *
+ * Defines the vocabulary for pack manifests as per ADR-0055 (A5 pack schema).
+ * A plain JS descriptor, not JSON Schema — the validator in validate.mjs
+ * consumes it directly. The schema is intentionally additive: new optional
+ * fields may be added in a minor version bump; new required fields are
+ * breaking and require a PACK_COMPAT_VERSION increment.
+ *
+ * `embedBindings` (LMCP-E4) is one such additive field: per-specialist
+ * provider read/search grants and external-write proposal grants, closing
+ * the excessive-agency gap where an embedded specialist could read any
+ * provider and propose any write with no declared authorization.
+ */
+
+export const PACK_REQUIRED_FIELDS = ['id', 'version', 'compatVersion'];
+
+export const PACK_OPTIONAL_FIELDS = [
+  'teams', 'specialists', 'prompts', 'frameworks', 'perspectives',
+  'modelTierHints', 'toolGrantsRequested', 'workflowContributions',
+  'handoffContracts', 'outputContracts', 'gates', 'tests', 'docs',
+  'installConditions', 'enableConditions', 'deprecation', 'embedBindings',
+];
+
+export const PACK_COMPAT_VERSION = 1;
+export const PACK_ID_RE = /^[a-z0-9\-./@]+$/;
+export const PACK_SOURCE_TIERS = ['builtin', 'user', 'project'];
+
+/**
+ * embedBindings shape (LMCP-E4) — per-specialist read/propose grant.
+ *
+ * `embedBindings` is a pack-level map keyed by specialist id:
+ *
+ *   {
+ *     "<specialistId>": {
+ *       "providers": [
+ *         { "id": "<extension-manifest-id>", "capabilities": ["read"], "filters": { ... ADR-0060 filter block ... } }
+ *       ],
+ *       "proposals": ["jira.createIssue"]
+ *     }
+ *   }
+ *
+ * `providers[].capabilities` values must be drawn from EMBED_BINDING_CAPABILITIES
+ * and must each be declared by the referenced extension manifest's own
+ * `capabilities` array — the binding cannot grant a capability the provider
+ * itself never advertises. `providers[].filters` reuses the ADR-0060 provider
+ * filter block verbatim (scope/predicates/nativeQuery); it is optional and,
+ * when present, validated with the same rules poll-time filters use.
+ * `proposals` is a flat list of `<providerId>.<writeKind>` tokens the
+ * specialist may propose (never execute autonomously — see authority-guard.mjs).
+ */
+export const EMBED_BINDING_CAPABILITIES = ['read', 'search'];
+
+export const EMBED_BINDING_FIELDS = ['providers', 'proposals'];
+
+export const EMBED_BINDING_PROVIDER_FIELDS = ['id', 'capabilities', 'filters'];
+
+export const EMBED_BINDING_PROPOSAL_RE = /^[a-z0-9-]+\.[a-zA-Z0-9]+$/;

package/lib/packs/prompts.mjs

@@ -0,0 +1,120 @@
+/**
+ * lib/packs/prompts.mjs — pack prompt-file validation and registry resolution.
+ *
+ * A pack manifest's `prompts` map declares `{ specialistId: relativePath }`,
+ * relative to that pack's own directory (`_packDir`, set by
+ * lib/packs/loader.mjs for every manifest-loaded pack) — a project pack's
+ * prompt paths are relative to the project, not to the Construct install.
+ * The core pack (lib/packs/core-pack.mjs) has no `_packDir`; its prompts map
+ * uses paths relative to `packageRoot` (the Construct install), the fallback
+ * root used whenever a pack carries no `_packDir` of its own.
+ *
+ * validatePackPrompts() confirms every declared file exists AND carries
+ * parseable YAML frontmatter with a `role` field — the two things worker.mjs
+ * needs before it can trust a persona prompt. In team/enterprise deployment
+ * mode a miss is a hard load-time error (the pack is rejected, naming the
+ * missing file) per LMCP-E2: a governed pack must never let a specialist run
+ * under the wrong persona.
+ *
+ * resolvePersonaPrompt() is the ONLY path worker.mjs uses to read a persona
+ * body: a walk of the pack list in the order given (the caller sorts by tier
+ * precedence — project before user before builtin, per ADR-0055), returning
+ * the first pack that declares the role, or `{ found: false }` when no pack
+ * in the registry declares it. No fallback to reading specialists/prompts/
+ * directly exists — that would defeat the pack boundary the registry is
+ * meant to enforce.
+ */
+
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import yaml from 'js-yaml';
+
+const FRONTMATTER_RE = /^---\n([\s\S]*?)\n---\n?/;
+
+function parseFrontmatter(content) {
+  const match = content.match(FRONTMATTER_RE);
+  if (!match) return null;
+  try {
+    return yaml.load(match[1]) || {};
+  } catch {
+    return null;
+  }
+}
+
+function packPromptRoot(pack, fallbackRoot) {
+  return pack?._packDir || fallbackRoot;
+}
+
+/**
+ * Validate every prompt file a pack declares.
+ *
+ * @param {object} pack        a manifest object carrying `prompts: {id: relPath}`
+ * @param {object} opts
+ * @param {string} opts.packageRoot   fallback root for packs with no `_packDir` (e.g. the core pack)
+ * @returns {{valid: boolean, errors: string[]}}
+ */
+export function validatePackPrompts(pack, { packageRoot } = {}) {
+  const errors = [];
+  const prompts = pack?.prompts || {};
+  const root = packPromptRoot(pack, packageRoot);
+
+  for (const [specId, relPath] of Object.entries(prompts)) {
+    if (typeof relPath !== 'string' || !relPath) {
+      errors.push(`pack '${pack.id}': prompt entry for '${specId}' has no file path`);
+      continue;
+    }
+    const absPath = join(root, relPath);
+    if (!existsSync(absPath)) {
+      errors.push(`pack '${pack.id}': declared prompt file missing for '${specId}': ${relPath}`);
+      continue;
+    }
+    let raw;
+    try {
+      raw = readFileSync(absPath, 'utf8');
+    } catch (err) {
+      errors.push(`pack '${pack.id}': declared prompt file unreadable for '${specId}': ${relPath} (${err.message})`);
+      continue;
+    }
+    const fm = parseFrontmatter(raw);
+    if (!fm) {
+      errors.push(`pack '${pack.id}': prompt file missing or invalid frontmatter for '${specId}': ${relPath}`);
+      continue;
+    }
+    if (!fm.role || typeof fm.role !== 'string') {
+      errors.push(`pack '${pack.id}': prompt frontmatter missing 'role' for '${specId}': ${relPath}`);
+    }
+  }
+
+  return { valid: errors.length === 0, errors };
+}
+
+/**
+ * Resolve one specialist's persona prompt through the pack registry only.
+ *
+ * Packs are tried in the order given (the caller sorts by tier precedence;
+ * see the module header) — the first pack declaring the role wins.
+ *
+ * @param {string} role         specialist id, e.g. 'cx-engineer' (accepts 'engineer' too)
+ * @param {object} opts
+ * @param {object[]} opts.packs      pack list, tier-precedence ordered (see loadAllPacks)
+ * @param {string} opts.packageRoot  fallback root for packs with no `_packDir` (e.g. the core pack)
+ * @returns {{found: true, content: string, packId: string} | {found: false}}
+ */
+export function resolvePersonaPrompt(role, { packs, packageRoot }) {
+  const slug = String(role || '').replace(/^cx-/, '');
+  const specId = `cx-${slug}`;
+
+  for (const pack of packs || []) {
+    const relPath = pack?.prompts?.[specId];
+    if (!relPath) continue;
+    const absPath = join(packPromptRoot(pack, packageRoot), relPath);
+    if (!existsSync(absPath)) continue;
+    try {
+      return { found: true, content: readFileSync(absPath, 'utf8'), packId: pack.id };
+    } catch {
+      continue;
+    }
+  }
+
+  return { found: false };
+}

package/lib/packs/validate.mjs

@@ -0,0 +1,208 @@
+/**
+ * lib/packs/validate.mjs — pack manifest validator.
+ *
+ * Validates a plain-JS pack manifest object against the canonical schema
+ * defined in manifest-schema.mjs. All errors are returned in a structured
+ * result; this function never throws. Error messages are single-line,
+ * actionable, and prefixed with the filePath (when provided).
+ *
+ * `embedBindings` validation (LMCP-E4) additionally cross-checks each bound
+ * provider id and capability against `knownProviders` — a map of provider id
+ * to its loaded extension manifest (lib/extensions/loader.mjs). A binding
+ * naming a provider id absent from that map, or granting a capability the
+ * provider's own manifest does not declare, fails validation with a path.
+ */
+
+import {
+  PACK_REQUIRED_FIELDS, PACK_OPTIONAL_FIELDS, PACK_COMPAT_VERSION,
+  EMBED_BINDING_CAPABILITIES, EMBED_BINDING_FIELDS, EMBED_BINDING_PROVIDER_FIELDS,
+  EMBED_BINDING_PROPOSAL_RE,
+} from './manifest-schema.mjs';
+import { validateFilterConfig } from '../providers/contract.mjs';
+
+const SEMVER_RE = /^\d+\.\d+\.\d+(?:[-+].+)?$/;
+
+const PACK_ID_RE = /^[a-z0-9\-./@]+$/;
+
+/**
+ * Validate the `embedBindings` block (LMCP-E4) against known extension
+ * manifests. `knownProviders` is a map of providerId → manifest (as loaded
+ * by lib/extensions/loader.mjs); each bound provider must exist in that map
+ * and must itself declare every capability the binding grants — a pack
+ * cannot hand a specialist a read/search grant the provider never advertises.
+ * Every error names the JSON path of the offending field.
+ */
+function validateEmbedBindings(embedBindings, { prefix, knownProviders = {} }) {
+  const errors = [];
+
+  if (typeof embedBindings !== 'object' || embedBindings === null || Array.isArray(embedBindings)) {
+    return [`${prefix}embedBindings must be an object keyed by specialist id`];
+  }
+
+  for (const [specialistId, binding] of Object.entries(embedBindings)) {
+    const bindingPath = `embedBindings.${specialistId}`;
+
+    if (typeof binding !== 'object' || binding === null || Array.isArray(binding)) {
+      errors.push(`${prefix}${bindingPath} must be an object`);
+      continue;
+    }
+
+    for (const key of Object.keys(binding)) {
+      if (!EMBED_BINDING_FIELDS.includes(key)) {
+        errors.push(`${prefix}${bindingPath}.${key} is not a recognized embedBindings field (allowed: ${EMBED_BINDING_FIELDS.join(', ')})`);
+      }
+    }
+
+    const providers = binding.providers;
+    if (providers !== undefined) {
+      if (!Array.isArray(providers)) {
+        errors.push(`${prefix}${bindingPath}.providers must be an array`);
+      } else {
+        providers.forEach((entry, idx) => {
+          const entryPath = `${bindingPath}.providers[${idx}]`;
+
+          if (typeof entry !== 'object' || entry === null || Array.isArray(entry)) {
+            errors.push(`${prefix}${entryPath} must be an object`);
+            return;
+          }
+
+          for (const key of Object.keys(entry)) {
+            if (!EMBED_BINDING_PROVIDER_FIELDS.includes(key)) {
+              errors.push(`${prefix}${entryPath}.${key} is not a recognized provider binding field (allowed: ${EMBED_BINDING_PROVIDER_FIELDS.join(', ')})`);
+            }
+          }
+
+          const providerId = entry.id;
+          if (typeof providerId !== 'string' || providerId.length === 0) {
+            errors.push(`${prefix}${entryPath}.id must be a non-empty string`);
+            return;
+          }
+
+          const providerManifest = knownProviders[providerId];
+          if (!providerManifest) {
+            errors.push(`${prefix}${entryPath}.id references unknown provider "${providerId}" (no extension manifest declares this id)`);
+            return;
+          }
+
+          const declaredCapabilities = new Set(providerManifest.capabilities || []);
+
+          if (!Array.isArray(entry.capabilities) || entry.capabilities.length === 0) {
+            errors.push(`${prefix}${entryPath}.capabilities must be a non-empty array`);
+          } else {
+            entry.capabilities.forEach((cap, capIdx) => {
+              const capPath = `${entryPath}.capabilities[${capIdx}]`;
+              if (!EMBED_BINDING_CAPABILITIES.includes(cap)) {
+                errors.push(`${prefix}${capPath} "${cap}" is not a recognized embed capability (allowed: ${EMBED_BINDING_CAPABILITIES.join(', ')})`);
+              } else if (!declaredCapabilities.has(cap)) {
+                errors.push(`${prefix}${capPath} "${cap}" is not declared by provider "${providerId}"'s manifest capabilities (${[...declaredCapabilities].join(', ') || '(none)'})`);
+              }
+            });
+          }
+
+          if (entry.filters !== undefined) {
+            try {
+              validateFilterConfig(providerId, entry.filters);
+            } catch (err) {
+              errors.push(`${prefix}${entryPath}.filters: ${err.message}`);
+            }
+          }
+        });
+      }
+    }
+
+    const proposals = binding.proposals;
+    if (proposals !== undefined) {
+      if (!Array.isArray(proposals)) {
+        errors.push(`${prefix}${bindingPath}.proposals must be an array`);
+      } else {
+        const boundProviderIds = new Set((Array.isArray(providers) ? providers : []).map((p) => p?.id).filter(Boolean));
+        proposals.forEach((token, idx) => {
+          const tokenPath = `${bindingPath}.proposals[${idx}]`;
+          if (typeof token !== 'string' || !EMBED_BINDING_PROPOSAL_RE.test(token)) {
+            errors.push(`${prefix}${tokenPath} "${token}" must be a "<providerId>.<writeKind>" token (e.g. "jira.createIssue")`);
+            return;
+          }
+          const [providerId] = token.split('.');
+          if (!knownProviders[providerId]) {
+            errors.push(`${prefix}${tokenPath} "${token}" references unknown provider "${providerId}" (no extension manifest declares this id)`);
+          } else if (boundProviderIds.size > 0 && !boundProviderIds.has(providerId)) {
+            errors.push(`${prefix}${tokenPath} "${token}" proposes against provider "${providerId}" which is not in this specialist's providers[] grant`);
+          }
+        });
+      }
+    }
+  }
+
+  return errors;
+}
+
+export function validatePackManifest(manifest, { filePath, strict = false, knownProviders = {} } = {}) {
+  const prefix = filePath ? `${filePath}: ` : '';
+  const errors = [];
+
+  if (!manifest || typeof manifest !== 'object' || Array.isArray(manifest)) {
+    return { valid: false, errors: [`${prefix}manifest must be a JSON object`] };
+  }
+
+  for (const field of PACK_REQUIRED_FIELDS) {
+    if (!(field in manifest) || manifest[field] === undefined || manifest[field] === null) {
+      errors.push(`${prefix}missing required field: ${field}`);
+    }
+  }
+
+  if ('id' in manifest && manifest.id !== undefined && manifest.id !== null) {
+    if (typeof manifest.id !== 'string' || manifest.id.length === 0) {
+      errors.push(`${prefix}id must be a non-empty string`);
+    } else if (!PACK_ID_RE.test(manifest.id)) {
+      errors.push(`${prefix}id must match [a-z0-9-./@]+ (got '${manifest.id}')`);
+    }
+  }
+
+  if ('version' in manifest && manifest.version !== undefined && manifest.version !== null) {
+    if (typeof manifest.version !== 'string' || !SEMVER_RE.test(manifest.version)) {
+      errors.push(`${prefix}version must be a semver string`);
+    }
+  }
+
+  if (manifest.compatVersion !== undefined && manifest.compatVersion !== null) {
+    if (typeof manifest.compatVersion !== 'number' || !Number.isInteger(manifest.compatVersion)) {
+      errors.push(`${prefix}compatVersion must be an integer`);
+    } else if (manifest.compatVersion > PACK_COMPAT_VERSION) {
+      errors.push(
+        `${prefix}compatVersion ${manifest.compatVersion} exceeds supported version ${PACK_COMPAT_VERSION}; upgrade Construct to use this pack`
+      );
+    }
+  }
+
+  if (manifest.deprecation !== undefined && manifest.deprecation !== null) {
+    if (typeof manifest.deprecation !== 'object' || Array.isArray(manifest.deprecation)) {
+      errors.push(`${prefix}deprecation must be an object`);
+    } else {
+      if (!('since' in manifest.deprecation)) {
+        errors.push(`${prefix}deprecation must include 'since' field`);
+      }
+      if (!('message' in manifest.deprecation)) {
+        errors.push(`${prefix}deprecation must include 'message' field`);
+      }
+    }
+  }
+
+  if (manifest.embedBindings !== undefined && manifest.embedBindings !== null) {
+    errors.push(...validateEmbedBindings(manifest.embedBindings, { prefix, knownProviders }));
+  }
+
+  if (strict) {
+    const knownFields = new Set([...PACK_REQUIRED_FIELDS, ...PACK_OPTIONAL_FIELDS]);
+    for (const key of Object.keys(manifest)) {
+      if (key.startsWith('_')) continue;
+      if (!knownFields.has(key)) {
+        errors.push(`${prefix}unknown field '${key}' in strict mode`);
+      }
+    }
+  }
+
+  if (errors.length > 0) {
+    return { valid: false, errors };
+  }
+  return { valid: true };
+}

package/lib/path-policy.mjs

@@ -0,0 +1,56 @@
+/**
+ * lib/path-policy.mjs — root containment for model-supplied file paths.
+ *
+ * MCP file tools take paths from model arguments. resolveWithinRoot pins each path to a
+ * declared root: it rejects backslash/UNC separators, out-of-root absolute or ../ targets,
+ * and symlinks whose real target escapes the root. Containment is checked on the realpath
+ * of the longest existing ancestor, so a not-yet-existing target is still anchored through
+ * real directories. On any escape it throws PathContainmentError whose message names the
+ * denial; otherwise it returns the canonical absolute path.
+ */
+import { realpathSync } from 'node:fs';
+import path from 'node:path';
+
+export class PathContainmentError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'PathContainmentError';
+  }
+}
+
+// A target may not exist yet (a delete of an already-gone file, a path with a missing
+// tail). Resolve symlinks on the longest existing prefix, then re-append the remaining
+// segments, so the escape check still sees through real ancestors.
+
+function canonical(p) {
+  const abs = path.resolve(p);
+  let cur = abs;
+  const tail = [];
+  while (true) {
+    try {
+      const real = realpathSync(cur);
+      return tail.length ? path.join(real, ...tail) : real;
+    } catch {
+      const parent = path.dirname(cur);
+      if (parent === cur) return abs;
+      tail.unshift(path.basename(cur));
+      cur = parent;
+    }
+  }
+}
+
+export function resolveWithinRoot(root, candidate) {
+  if (typeof candidate !== 'string' || candidate.length === 0) {
+    throw new PathContainmentError('path denied: empty or non-string file path');
+  }
+  if (candidate.includes('\\')) {
+    throw new PathContainmentError('path denied: backslash/UNC separators escape the allowed root');
+  }
+  const base = canonical(root);
+  const requested = path.isAbsolute(candidate) ? candidate : path.join(path.resolve(root), candidate);
+  const resolved = canonical(requested);
+  if (resolved !== base && !resolved.startsWith(base + path.sep)) {
+    throw new PathContainmentError(`path denied: ${candidate} resolves outside the allowed root`);
+  }
+  return resolved;
+}

package/lib/plugin-registry.mjs

@@ -6,11 +6,10 @@
  */
 import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
-import { dirname, extname, join, resolve } from "node:path";
-import { fileURLToPath } from "node:url";
+import { extname, join, resolve } from "node:path";
 import { configDir } from "./config/xdg.mjs";
+import { packageRoot } from "./roots.mjs";
 
-const __dirname = dirname(fileURLToPath(import.meta.url));
 export const MANIFEST_VERSION = 1;
 
 function readJson(filePath) {
@@ -97,7 +96,7 @@ export function validatePluginManifest(manifest, { manifestPath = "<memory>" } =
 
 function loadBuiltinPlugin(rootDir) {
   const rootCatalogPath = join(rootDir, "lib", "mcp-catalog.json");
-  const catalogPath = existsSync(rootCatalogPath) ? rootCatalogPath : join(__dirname, "mcp-catalog.json");
+  const catalogPath = existsSync(rootCatalogPath) ? rootCatalogPath : join(packageRoot, "lib", "mcp-catalog.json");
   const catalog = readJson(catalogPath);
   const plugin = {
     id: "construct-builtins",
@@ -142,7 +141,7 @@ function findManifestFiles(pluginDirs) {
   return files.sort();
 }
 
-export function loadPluginRegistry({ cwd = process.cwd(), homeDir = homedir(), rootDir = resolve(__dirname, ".."), env = process.env } = {}) {
+export function loadPluginRegistry({ cwd = process.cwd(), homeDir = homedir(), rootDir = packageRoot, env = process.env } = {}) {
   const errors = [];
   const plugins = [loadBuiltinPlugin(rootDir)];
   const pluginDirs = resolvePluginDirs({ cwd, homeDir, env });