@geraldmaron/construct 1.4.1 → 1.5.0

package/lib/output-quality.mjs

@@ -8,8 +8,17 @@
  * screenshot evidence recorded. Every check degrades with a typed reason when its tool is absent
  * rather than failing the publish; only a real, document-scoped validity failure (a zero-page PDF,
  * dropped content, a missing local reference) marks the result not-ok.
+ *
+ * Markup visual gate (HTML only): invisible text (opacity:0, matched fg/bg color) and hard-overlapping
+ * absolutely-positioned elements are detected from the produced file's own markup, closing the blind
+ * spot where the text roundtrip passes because hidden glyphs are still extractable.
+ *
+ * Render-smoke hard-fail: for pdf and pptx deliverables at render-smoke+, a missing required renderer
+ * is a hard failure rather than a graceful degrade — a user inspecting output before claiming done
+ * cannot accept a quality claim that rests on a tool that was never invoked.
  */
 
+import fs from 'node:fs';
 import { validatePdf, contentRoundtrip, referenceIntegrity } from './export-validate.mjs';
 import { validateBrandContrast } from './brand-contrast.mjs';
 import { captureRenderEvidence } from './render-evidence.mjs';
@@ -18,6 +27,49 @@ import { auditAccessibility } from './a11y-audit.mjs';
 
 const RENDER_GATE_LEVELS = new Set(['render-smoke', 'full-certification', 'human-reviewed']);
 
+// PDF and PPTX require external renderers; their absence at render-smoke+ is a hard failure.
+const RENDER_REQUIRED_FORMATS = new Set(['pdf', 'pptx']);
+
+// Detect invisible and hard-overlapping text in a produced HTML deliverable. The text roundtrip
+// passes even when body text is invisible because hidden glyphs are still extractable; this gate
+// catches opacity:0, matched foreground/background color, and hard-stacked absolute elements.
+
+function markupVisualGate(exportPath, format) {
+  if (format !== 'html') return { ok: true, issues: [], degradation: null };
+  let html;
+  try { html = fs.readFileSync(exportPath, 'utf8'); } catch { return { ok: true, issues: [], degradation: null }; }
+
+  const issues = [];
+
+  if (/\bopacity\s*:\s*0(?!\.\d)/i.test(html)) {
+    issues.push('invisible-text: opacity:0 on element');
+  }
+
+  for (const m of html.matchAll(/style\s*=\s*["']([^"']*)["']/gi)) {
+    const style = m[1];
+    const fgM = style.match(/\bcolor\s*:\s*(#[0-9a-f]{3,6}|[a-z]+)/i);
+    const bgM = style.match(/\bbackground(?:-color)?\s*:\s*(#[0-9a-f]{3,6}|[a-z]+)/i);
+    if (fgM && bgM && fgM[1].toLowerCase() === bgM[1].toLowerCase()) {
+      issues.push(`invisible-text: foreground and background both "${fgM[1].toLowerCase()}"`);
+    }
+  }
+
+  const positions = new Map();
+  for (const m of html.matchAll(/style\s*=\s*["']([^"']*)["']/gi)) {
+    const style = m[1];
+    if (!/position\s*:\s*absolute/i.test(style)) continue;
+    const top = (style.match(/\btop\s*:\s*([^;,"'\s]+)/) || [])[1] ?? '';
+    const left = (style.match(/\bleft\s*:\s*([^;,"'\s]+)/) || [])[1] ?? '';
+    if (top === '' && left === '') continue;
+    const key = `${top}|${left}`;
+    const cnt = (positions.get(key) || 0) + 1;
+    positions.set(key, cnt);
+    if (cnt === 2) issues.push(`overlapping-text: elements stacked at top:${top} left:${left}`);
+  }
+
+  return { ok: issues.length === 0, issues, degradation: null };
+}
+
 // render-pipeline keys an export format to an image renderer; deck is HTML under the hood. A
 // format with no renderer skips the screenshot capture rather than guessing one.
 
@@ -42,7 +94,8 @@ export function runOutputQuality({
 
   if (format === 'pdf') checks.pdf = validatePdf(exportPath, env);
   checks.roundtrip = contentRoundtrip({ exportPath, format, sourceMarkdown, env });
-  if (sourceMarkdown && baseDir) checks.references = referenceIntegrity(sourceMarkdown, baseDir);
+  if (sourceMarkdown && baseDir) checks.references = referenceIntegrity(sourceMarkdown, baseDir, exportPath);
+  if (format === 'html') checks.markup = markupVisualGate(exportPath, format);
 
   // Diagram legibility is advisory by default; `cx_diagram_quality: strict` escalates it.
   const diagrams = lintDocumentDiagrams(sourceMarkdown);
@@ -62,12 +115,18 @@ export function runOutputQuality({
   }
 
   // A typed degradation (tool absent) never fails the publish; only a non-degraded,
-  // document-scoped check whose ok is explicitly false does.
+  // document-scoped check whose ok is explicitly false does. Exception: at render-smoke+ gate
+  // levels, a missing required renderer for pdf/pptx is a hard failure — the quality claim depends
+  // on a tool that was never invoked.
 
   const failures = Object.entries(checks)
     .filter(([, result]) => result && result.ok === false && !result.degradation)
     .map(([name, result]) => `${name}: ${result.message || 'failed'}`);
 
+  if (RENDER_GATE_LEVELS.has(gateLevel) && RENDER_REQUIRED_FORMATS.has(format) && render?.result?.degradation === 'missing-dependency') {
+    failures.push(`render: required ${format} renderer absent at gate level '${gateLevel}'`);
+  }
+
   if (diagramStrict && !diagrams.ok) {
     for (const w of diagrams.warnings) failures.push(`diagram ${w.diagram} (${w.kind}): ${w.code}`);
   }

package/lib/packs/cli.mjs

@@ -0,0 +1,144 @@
+/**
+ * lib/packs/cli.mjs — `construct pack` command surface (LMCP-E3).
+ *
+ * Subcommands:
+ *   list             Every pack discovered across builtin/user/project tiers
+ *                     (loader.mjs precedence merge), each annotated with its
+ *                     durable enabled state (enablement.mjs).
+ *   enable <id>      Validate the pack's on-disk manifest and record it as
+ *                     enabled in .cx/packs.json. Refuses — naming the exact
+ *                     validation error — on an incompatible compatVersion or
+ *                     any other manifest defect.
+ *   disable <id>     Remove the pack's enabled entry. Idempotent. Refuses to
+ *                     disable the core pack.
+ *   info <id>        Full manifest plus enabled state for one pack.
+ *
+ * `--json` on every subcommand emits a machine-readable payload; the text
+ * form is the human-readable default.
+ */
+
+import { loadAllPacks } from './loader.mjs';
+import { readEnablementState, isEnabled, enablePack, disablePack } from './enablement.mjs';
+
+function annotatedPacks({ rootDir, homeDir, packageRoot, env, deploymentMode }) {
+  const { packs, errors } = loadAllPacks({ rootDir, homeDir, packageRoot, env, deploymentMode });
+  const state = readEnablementState(rootDir);
+  const annotated = packs.map((p) => ({
+    id: p.id,
+    version: p.version,
+    tier: p._tier,
+    enabled: isEnabled(p.id, state, { packageRoot }),
+    manifestPath: p._manifestPath || p._packDir || null,
+  }));
+  return { packs: annotated, errors, state };
+}
+
+function runList({ rootDir, packageRoot, json }) {
+  const { packs, errors } = annotatedPacks({ rootDir, packageRoot });
+  if (json) {
+    process.stdout.write(JSON.stringify({ packs, errors }, null, 2) + '\n');
+    return 0;
+  }
+  process.stdout.write(`Packs (${packs.length}):\n`);
+  for (const p of packs) {
+    process.stdout.write(`  ${p.enabled ? '●' : '○'} ${p.id}@${p.version} [${p.tier}]${p.enabled ? ' (enabled)' : ''}\n`);
+  }
+  for (const e of errors) process.stdout.write(`  ! ${e}\n`);
+  return 0;
+}
+
+/**
+ * Splits a `<pack-id>[@version]` spec on the last '@', so a scoped id like
+ * '@fixture/sample' (no version) stays intact while '@fixture/sample@2.0.0'
+ * splits into id '@fixture/sample' and version '2.0.0'.
+ */
+function parsePackSpec(spec) {
+  const at = spec.lastIndexOf('@');
+  if (at <= 0) return { packId: spec, requestedVersion: undefined };
+  return { packId: spec.slice(0, at), requestedVersion: spec.slice(at + 1) };
+}
+
+function runEnable(args, { rootDir, packageRoot, json }) {
+  const id = args.find((a) => !a.startsWith('--'));
+  if (!id) {
+    process.stderr.write('Usage: construct pack enable <pack-id>[@version] [--json]\n');
+    return 1;
+  }
+  const { packId, requestedVersion } = parsePackSpec(id);
+
+  const result = enablePack(packId, { rootDir, packageRoot, requestedVersion });
+  if (json) {
+    process.stdout.write(JSON.stringify(result, null, 2) + '\n');
+    return result.ok ? 0 : 1;
+  }
+  if (!result.ok) {
+    process.stderr.write(`✖ ${result.error}\n`);
+    return 1;
+  }
+  process.stdout.write(result.alreadyCore ? `✓ ${packId} is the core pack (always enabled)\n` : `✓ enabled ${packId}@${result.pack.version} [${result.tier}]\n`);
+  return 0;
+}
+
+function runDisable(args, { rootDir, packageRoot, json }) {
+  const id = args.find((a) => !a.startsWith('--'));
+  if (!id) {
+    process.stderr.write('Usage: construct pack disable <pack-id> [--json]\n');
+    return 1;
+  }
+  const result = disablePack(id, { rootDir, packageRoot });
+  if (json) {
+    process.stdout.write(JSON.stringify(result, null, 2) + '\n');
+    return result.ok ? 0 : 1;
+  }
+  if (!result.ok) {
+    process.stderr.write(`✖ ${result.error}\n`);
+    return 1;
+  }
+  process.stdout.write(result.wasEnabled ? `✓ disabled ${id}\n` : `${id} was not enabled (no-op)\n`);
+  return 0;
+}
+
+function runInfo(args, { rootDir, packageRoot, json }) {
+  const id = args.find((a) => !a.startsWith('--'));
+  if (!id) {
+    process.stderr.write('Usage: construct pack info <pack-id> [--json]\n');
+    return 1;
+  }
+  const { packs: rawPacks } = loadAllPacks({ rootDir, packageRoot });
+  const pack = rawPacks.find((p) => p.id === id);
+  if (!pack) {
+    process.stderr.write(`pack not found: ${id}\n`);
+    return 1;
+  }
+  const state = readEnablementState(rootDir);
+  const enabled = isEnabled(id, state, { packageRoot });
+  const result = { ...pack, enabled, enabledDetail: state.enabled[id] || null };
+  if (json) {
+    process.stdout.write(JSON.stringify(result, null, 2) + '\n');
+    return 0;
+  }
+  process.stdout.write(`${pack.id}@${pack.version} [${pack._tier}] ${enabled ? '(enabled)' : '(disabled)'}\n`);
+  if (pack.specialists) process.stdout.write(`  specialists: ${Object.keys(pack.specialists).length}\n`);
+  if (pack.prompts) process.stdout.write(`  prompts: ${Object.keys(pack.prompts).length}\n`);
+  if (pack.frameworks) process.stdout.write(`  frameworks: ${Object.keys(pack.frameworks).length}\n`);
+  return 0;
+}
+
+/**
+ * @param {string[]} args
+ * @param {{ rootDir: string, packageRoot?: string }} ctx
+ * @returns {number} exit code
+ */
+export function runPackCli(args, { rootDir, packageRoot } = {}) {
+  const sub = args[0];
+  const rest = args.slice(1);
+  const json = args.includes('--json');
+
+  if (sub === 'list') return runList({ rootDir, packageRoot, json });
+  if (sub === 'enable') return runEnable(rest, { rootDir, packageRoot, json });
+  if (sub === 'disable') return runDisable(rest, { rootDir, packageRoot, json });
+  if (sub === 'info') return runInfo(rest, { rootDir, packageRoot, json });
+
+  process.stderr.write(`Unknown pack subcommand: ${sub}. Available: list, enable, disable, info\n`);
+  return 1;
+}

package/lib/packs/core-pack.mjs

@@ -0,0 +1,112 @@
+/**
+ * lib/packs/core-pack.mjs — programmatic builtin core pack loader.
+ *
+ * Reads specialists/org/ directory structure and wraps it as the
+ * @construct/core pack. This is the builtin tier pack that provides
+ * all default specialists, teams, prompts, and reasoning frameworks
+ * (ADR-0062) shipped with Construct.
+ *
+ * `embedBindings` (LMCP-E4) ships default per-specialist provider read/
+ * search grants and write-proposal grants for the built-in specialists most
+ * likely to run embedded: cx-product-manager, cx-operations, cx-engineer.
+ * These are defaults only — a project may override them via a project-tier
+ * pack (.cx/packs) under the same specialist id.
+ */
+
+import { readFileSync, readdirSync, existsSync } from 'node:fs';
+import { join, dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import yaml from 'js-yaml';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const PACKAGE_ROOT = resolve(__dirname, '..', '..');
+
+const FRONTMATTER_RE = /^---\n([\s\S]*?)\n---\n?/;
+
+// Default per-specialist embed bindings (LMCP-E4). Read/search only — no
+// specialist gets an autonomous write; `proposals` names the write kinds a
+// specialist may propose, and every proposal still passes through
+// AuthorityGuard's approval-queued path before anything executes.
+const DEFAULT_EMBED_BINDINGS = Object.freeze({
+  'cx-product-manager': {
+    providers: [
+      { id: 'atlassian-jira', capabilities: ['read', 'search'] },
+      { id: 'atlassian-confluence', capabilities: ['read', 'search'] },
+    ],
+    proposals: ['atlassian-jira.createIssue'],
+  },
+  'cx-operations': {
+    providers: [
+      { id: 'atlassian-jira', capabilities: ['read', 'search'] },
+      { id: 'atlassian-confluence', capabilities: ['read', 'search'] },
+      { id: 'slack', capabilities: ['read', 'search'] },
+    ],
+    proposals: ['atlassian-jira.createIssue', 'slack.postMessage'],
+  },
+  'cx-engineer': {
+    providers: [
+      { id: 'github', capabilities: ['read', 'search'] },
+      { id: 'atlassian-jira', capabilities: ['read', 'search'] },
+    ],
+    proposals: ['github.createIssue'],
+  },
+});
+
+export function loadCorePack(rootDir = PACKAGE_ROOT) {
+  const orgDir = join(rootDir, 'specialists', 'org');
+  const specialistDir = join(orgDir, 'specialists');
+  const teamDir = join(orgDir, 'teams');
+  const frameworkDir = join(orgDir, 'frameworks');
+
+  const specialists = existsSync(specialistDir)
+    ? readdirSync(specialistDir).filter(f => f.endsWith('.json')).map(f => f.replace(/\.json$/, ''))
+    : [];
+
+  const teams = existsSync(teamDir)
+    ? readdirSync(teamDir).filter(f => f.endsWith('.json')).map(f => f.replace(/\.json$/, ''))
+    : [];
+
+  const prompts = {};
+  for (const specId of specialists) {
+    try {
+      const spec = JSON.parse(readFileSync(join(specialistDir, `${specId}.json`), 'utf8'));
+      if (spec.promptFile) prompts[specId] = spec.promptFile;
+    } catch {}
+  }
+
+  // frameworks map keys by frontmatter `id` (not filename) so a project-tier
+  // override in .cx/packs can declare the same id from a differently named
+  // file and still win under mergePackTiers/resolveFramework precedence.
+  const frameworks = {};
+  if (existsSync(frameworkDir)) {
+    for (const file of readdirSync(frameworkDir).filter(f => f.endsWith('.md'))) {
+      try {
+        const raw = readFileSync(join(frameworkDir, file), 'utf8');
+        const match = raw.match(FRONTMATTER_RE);
+        const fm = match ? yaml.load(match[1]) : null;
+        if (fm?.id) frameworks[fm.id] = join('specialists', 'org', 'frameworks', file);
+      } catch {}
+    }
+  }
+
+  // Only bind specialists actually present on disk — a stripped-down or
+  // customized org directory should not surface bindings for personas it
+  // doesn't ship.
+  const embedBindings = {};
+  for (const [specId, binding] of Object.entries(DEFAULT_EMBED_BINDINGS)) {
+    if (specialists.includes(specId)) embedBindings[specId] = binding;
+  }
+
+  return {
+    id: '@construct/core',
+    version: '0.0.0',
+    compatVersion: 1,
+    teams,
+    specialists,
+    prompts,
+    embedBindings,
+    frameworks,
+    _tier: 'builtin',
+    _sourceDir: orgDir,
+  };
+}

package/lib/packs/enablement.mjs

@@ -0,0 +1,187 @@
+/**
+ * lib/packs/enablement.mjs — durable pack enable/disable lifecycle (LMCP-E3).
+ *
+ * `loadAllPacks` (loader.mjs) merges every pack it finds on disk across the
+ * builtin/user/project tiers unconditionally — correct for authoring-time
+ * precedence resolution, but it means dropping a pack manifest into
+ * `.cx/packs/` makes it "configured" and already influencing prompt/framework
+ * resolution with no explicit operator action (the OTel lesson this bead is
+ * named for: configured is not enabled). This module adds an explicit,
+ * durable enablement layer on top without changing loadAllPacks' own
+ * semantics — existing callers merging all discovered packs (precedence
+ * tests, `construct doctor`) are unaffected; a caller that wants
+ * enablement-gated packs calls `loadEnabledPacks` instead.
+ *
+ * State lives at `<rootDir>/.cx/packs.json`:
+ *   { "version": 1, "enabled": { "<packId>": { "version": "1.0.0", "enabledAt": "<ISO>", "tier": "project" } } }
+ *
+ * `@construct/core` (the programmatically-injected builtin foundation pack,
+ * see core-pack.mjs) is always enabled — it is not optional and carries no
+ * manifest file to enable/disable.
+ *
+ * `enablePack` refuses to enable a pack whose manifest fails validation —
+ * including a compatVersion that exceeds this runtime's PACK_COMPAT_VERSION —
+ * naming the exact validation error rather than half-enabling it.
+ */
+
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+
+import { loadAllPacks, resolvePackDirs } from './loader.mjs';
+import { validatePackManifest } from './validate.mjs';
+import { loadCorePack } from './core-pack.mjs';
+
+const STATE_VERSION = 1;
+
+export function resolveEnablementStatePath(rootDir = process.cwd()) {
+  return join(rootDir, '.cx', 'packs.json');
+}
+
+/**
+ * @param {string} [rootDir]
+ * @returns {{ version: number, enabled: Record<string, {version: string, enabledAt: string, tier: string}> }}
+ */
+export function readEnablementState(rootDir = process.cwd()) {
+  const statePath = resolveEnablementStatePath(rootDir);
+  if (!existsSync(statePath)) {
+    return { version: STATE_VERSION, enabled: {} };
+  }
+  try {
+    const parsed = JSON.parse(readFileSync(statePath, 'utf8'));
+    if (!parsed || typeof parsed !== 'object' || typeof parsed.enabled !== 'object' || parsed.enabled === null) {
+      return { version: STATE_VERSION, enabled: {} };
+    }
+    return { version: parsed.version || STATE_VERSION, enabled: parsed.enabled };
+  } catch {
+    return { version: STATE_VERSION, enabled: {} };
+  }
+}
+
+export function writeEnablementState(rootDir, state) {
+  const statePath = resolveEnablementStatePath(rootDir);
+  mkdirSync(dirname(statePath), { recursive: true });
+  writeFileSync(statePath, JSON.stringify({ version: state.version || STATE_VERSION, enabled: state.enabled || {} }, null, 2) + '\n', 'utf8');
+}
+
+/**
+ * The core pack ships with Construct and is always enabled — it has no
+ * manifest file on disk to toggle and every specialist/framework/prompt it
+ * carries is the foundation every deployment mode depends on.
+ */
+export function isCorePackId(packId, packageRoot) {
+  return packId === loadCorePack(packageRoot).id;
+}
+
+export function isEnabled(packId, state, { packageRoot } = {}) {
+  if (isCorePackId(packId, packageRoot)) return true;
+  return Boolean(state?.enabled?.[packId]);
+}
+
+/**
+ * Scans the three tier directories (project, user, builtin — highest
+ * precedence first) for a `pack.manifest.json` whose parsed `id` matches.
+ * Returns the parsed manifest alongside its tier/path even when validation
+ * would reject it, so `enablePack` can name the exact validation failure
+ * instead of reporting a generic "not found".
+ *
+ * @returns {{ tier: string, packDir: string, manifestPath: string, parsed: object } | null}
+ */
+function findPackManifest(packId, { rootDir, homeDir } = {}) {
+  const dirs = resolvePackDirs({ rootDir, homeDir });
+  const tiers = [
+    { tier: 'project', dir: dirs.project },
+    { tier: 'user', dir: dirs.user },
+    { tier: 'builtin', dir: dirs.builtin },
+  ];
+
+  for (const { tier, dir } of tiers) {
+    if (!existsSync(dir)) continue;
+    const entries = readdirSync(dir, { withFileTypes: true }).filter((e) => e.isDirectory());
+    for (const entry of entries) {
+      const packDir = join(dir, entry.name);
+      const manifestPath = join(packDir, 'pack.manifest.json');
+      if (!existsSync(manifestPath)) continue;
+      let parsed;
+      try {
+        parsed = JSON.parse(readFileSync(manifestPath, 'utf8'));
+      } catch {
+        continue;
+      }
+      if (parsed?.id === packId) {
+        return { tier, packDir, manifestPath, parsed };
+      }
+    }
+  }
+  return null;
+}
+
+/**
+ * @param {string} packId
+ * @param {{ rootDir?: string, homeDir?: string, packageRoot?: string, requestedVersion?: string, knownProviders?: object }} [opts]
+ * @returns {{ ok: true, pack: object, tier: string, alreadyCore?: true } | { ok: false, error: string }}
+ */
+export function enablePack(packId, opts = {}) {
+  const { rootDir = process.cwd(), homeDir, packageRoot, requestedVersion, knownProviders } = opts;
+
+  if (isCorePackId(packId, packageRoot)) {
+    return { ok: true, alreadyCore: true, pack: { id: packId }, tier: 'builtin' };
+  }
+
+  const found = findPackManifest(packId, { rootDir, homeDir });
+  if (!found) {
+    const dirs = resolvePackDirs({ rootDir, homeDir });
+    return { ok: false, error: `pack '${packId}' not found in any builtin/user/project pack directory (looked under ${dirs.project}, ${dirs.user}, ${dirs.builtin})` };
+  }
+
+  if (requestedVersion && found.parsed.version !== requestedVersion) {
+    return { ok: false, error: `pack '${packId}' on disk is version ${found.parsed.version}, requested ${requestedVersion}` };
+  }
+
+  const result = validatePackManifest(found.parsed, { filePath: found.manifestPath, knownProviders });
+  if (!result.valid) {
+    return { ok: false, error: `pack '${packId}' failed validation: ${result.errors.join('; ')}` };
+  }
+
+  const state = readEnablementState(rootDir);
+  state.enabled[packId] = { version: found.parsed.version, enabledAt: new Date().toISOString(), tier: found.tier };
+  writeEnablementState(rootDir, state);
+
+  return { ok: true, pack: found.parsed, tier: found.tier };
+}
+
+/**
+ * Idempotent — disabling an already-disabled (or never-enabled) pack still
+ * returns ok:true. The core pack cannot be disabled (ADR-0055 foundation tier).
+ *
+ * @param {string} packId
+ * @param {{ rootDir?: string, packageRoot?: string }} [opts]
+ * @returns {{ ok: true, wasEnabled: boolean } | { ok: false, error: string }}
+ */
+export function disablePack(packId, opts = {}) {
+  const { rootDir = process.cwd(), packageRoot } = opts;
+  if (isCorePackId(packId, packageRoot)) {
+    return { ok: false, error: `pack '${packId}' is the core pack and cannot be disabled` };
+  }
+  const state = readEnablementState(rootDir);
+  const wasEnabled = Boolean(state.enabled[packId]);
+  delete state.enabled[packId];
+  writeEnablementState(rootDir, state);
+  return { ok: true, wasEnabled };
+}
+
+/**
+ * Enablement-gated counterpart to `loadAllPacks` — same merge/precedence,
+ * filtered to only the core pack plus whatever the durable state marks
+ * enabled. Consumers that must not act on a merely-configured-but-unenabled
+ * pack (prompt/framework resolution, embed bindings) should call this
+ * instead of loadAllPacks directly.
+ *
+ * @param {object} opts  same shape as loadAllPacks' opts
+ * @returns {{packs: object[], errors: string[], state: object}}
+ */
+export function loadEnabledPacks(opts = {}) {
+  const { packs, errors } = loadAllPacks(opts);
+  const state = readEnablementState(opts.rootDir);
+  const filtered = packs.filter((p) => isEnabled(p.id, state, { packageRoot: opts.packageRoot }));
+  return { packs: filtered, errors, state };
+}

package/lib/packs/index.mjs

@@ -0,0 +1,23 @@
+/**
+ * lib/packs/index.mjs — public API for the pack manifest system.
+ *
+ * Re-exports all symbols from the five pack sub-modules so consumers
+ * can import from a single entry point:
+ *
+ *   import { validatePackManifest, loadAllPacks, PACK_REQUIRED_FIELDS } from './packs/index.mjs';
+ */
+
+export {
+  PACK_REQUIRED_FIELDS, PACK_OPTIONAL_FIELDS, PACK_COMPAT_VERSION,
+  PACK_ID_RE, PACK_SOURCE_TIERS,
+} from './manifest-schema.mjs';
+
+export { validatePackManifest } from './validate.mjs';
+
+export { validatePackPrompts, resolvePersonaPrompt } from './prompts.mjs';
+
+export { loadCorePack } from './core-pack.mjs';
+
+export {
+  loadPacksFromDir, mergePackTiers, resolvePackDirs, loadAllPacks,
+} from './loader.mjs';