@geraldmaron/construct 1.2.0 → 1.2.1

package/lib/config/source-targets.mjs

@@ -0,0 +1,311 @@
+/**
+ * lib/config/source-targets.mjs — typed integration source targets in construct.config.json.
+ *
+ * Validates GitHub, Jira, Linear, and Slack selector records, merges legacy env
+ * target lists additively, deduplicates by provider+selector signature, and
+ * converts resolved targets into embed provider source records for auto-discovery.
+ */
+
+export const SOURCE_PROVIDERS = Object.freeze(['github', 'jira', 'linear', 'slack']);
+
+export const SLACK_INTENTS = Object.freeze(['internal', 'risk', 'decision', 'external', 'how-to']);
+
+const ID_RE = /^[a-z][a-z0-9_-]{0,63}$/i;
+const GITHUB_REPO_RE = /^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/;
+const JIRA_PROJECT_RE = /^[A-Z][A-Z0-9]{1,9}$/;
+
+export function validateSourceTarget(target, index = 0) {
+  const errors = [];
+  const at = `sources.targets[${index}]`;
+
+  if (!target || typeof target !== 'object' || Array.isArray(target)) {
+    return [`${at}: must be an object`];
+  }
+
+  if (typeof target.id !== 'string' || !ID_RE.test(target.id)) {
+    errors.push(`${at}.id: required stable id (letters, numbers, hyphens, underscores; max 64 chars)`);
+  }
+
+  if (!SOURCE_PROVIDERS.includes(target.provider)) {
+    errors.push(`${at}.provider: must be one of ${SOURCE_PROVIDERS.join(', ')}`);
+  }
+
+  if (!target.selector || typeof target.selector !== 'object' || Array.isArray(target.selector)) {
+    errors.push(`${at}.selector: required object`);
+    return errors;
+  }
+
+  const sel = target.selector;
+  switch (target.provider) {
+    case 'github':
+      if (typeof sel.repo !== 'string' || !GITHUB_REPO_RE.test(sel.repo.trim())) {
+        errors.push(`${at}.selector.repo: required owner/repo slug`);
+      }
+      break;
+    case 'jira':
+      if (typeof sel.project !== 'string' || !JIRA_PROJECT_RE.test(sel.project.trim().toUpperCase())) {
+        errors.push(`${at}.selector.project: required Jira project key (2–10 uppercase letters/digits)`);
+      }
+      break;
+    case 'linear':
+      if (typeof sel.team !== 'string' || !sel.team.trim()) {
+        errors.push(`${at}.selector.team: required Linear team key or name`);
+      }
+      break;
+    case 'slack': {
+      if (typeof sel.channel !== 'string' || !sel.channel.trim()) {
+        errors.push(`${at}.selector.channel: required Slack channel name or ID`);
+      }
+      if (sel.intent !== undefined && !SLACK_INTENTS.includes(sel.intent)) {
+        errors.push(`${at}.selector.intent: must be one of ${SLACK_INTENTS.join(', ')}`);
+      }
+      break;
+    }
+    default:
+      break;
+  }
+
+  return errors;
+}
+
+export function validateSourceTargets(targets) {
+  const errors = [];
+  if (targets === undefined) return errors;
+  if (!Array.isArray(targets)) {
+    return ['sources.targets: must be an array'];
+  }
+
+  const seenIds = new Set();
+  for (let i = 0; i < targets.length; i++) {
+    errors.push(...validateSourceTarget(targets[i], i));
+    const id = targets[i]?.id;
+    if (typeof id === 'string') {
+      const key = id.toLowerCase();
+      if (seenIds.has(key)) {
+        errors.push(`sources.targets[${i}].id: duplicate id "${id}"`);
+      }
+      seenIds.add(key);
+    }
+  }
+  return errors;
+}
+
+function parseCsv(value) {
+  return String(value ?? '')
+    .split(',')
+    .map((s) => s.trim())
+    .filter(Boolean);
+}
+
+function slugId(value) {
+  return String(value).toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '');
+}
+
+function parseSlackChannelEntry(raw) {
+  const trimmed = String(raw).trim().replace(/^#/, '');
+  const colon = trimmed.indexOf(':');
+  if (colon === -1) {
+    return { channel: trimmed, intent: 'internal' };
+  }
+  return { channel: trimmed.slice(0, colon), intent: trimmed.slice(colon + 1) || 'internal' };
+}
+
+export function legacyEnvSourceTargets(env = process.env) {
+  const targets = [];
+
+  for (const repo of parseCsv(env.GITHUB_REPOS ?? env.GITHUB_REPO)) {
+    targets.push({
+      id: `env-github-${slugId(repo)}`,
+      provider: 'github',
+      selector: { repo },
+      provenance: 'env:GITHUB_REPOS',
+    });
+  }
+
+  for (const project of parseCsv(env.JIRA_PROJECTS)) {
+    const key = project.toUpperCase();
+    targets.push({
+      id: `env-jira-${slugId(key)}`,
+      provider: 'jira',
+      selector: { project: key },
+      provenance: 'env:JIRA_PROJECTS',
+    });
+  }
+
+  for (const team of parseCsv(env.LINEAR_TEAMS)) {
+    targets.push({
+      id: `env-linear-${slugId(team)}`,
+      provider: 'linear',
+      selector: { team },
+      provenance: 'env:LINEAR_TEAMS',
+    });
+  }
+
+  for (const entry of parseCsv(env.SLACK_CHANNELS ?? env.SLACK_CHANNEL)) {
+    const { channel, intent } = parseSlackChannelEntry(entry);
+    targets.push({
+      id: `env-slack-${slugId(channel)}`,
+      provider: 'slack',
+      selector: { channel, intent: SLACK_INTENTS.includes(intent) ? intent : 'internal' },
+      provenance: 'env:SLACK_CHANNELS',
+    });
+  }
+
+  return targets;
+}
+
+export function targetSignature(target) {
+  const sel = target.selector ?? {};
+  switch (target.provider) {
+    case 'github':
+      return `github:repo:${sel.repo?.trim().toLowerCase()}`;
+    case 'jira':
+      return `jira:project:${String(sel.project ?? '').trim().toUpperCase()}`;
+    case 'linear':
+      return `linear:team:${String(sel.team ?? '').trim().toLowerCase()}`;
+    case 'slack':
+      return `slack:channel:${String(sel.channel ?? '').trim().toLowerCase()}:intent:${sel.intent ?? 'internal'}`;
+    default:
+      return `${target.provider}:${JSON.stringify(sel)}`;
+  }
+}
+
+export function mergeSourceTargets(configTargets = [], envTargets = []) {
+  const merged = [];
+  const seen = new Set();
+
+  for (const target of [...configTargets, ...envTargets]) {
+    const sig = targetSignature(target);
+    if (seen.has(sig)) continue;
+    seen.add(sig);
+    merged.push(target);
+  }
+  return merged;
+}
+
+export function normalizeConfigTarget(raw) {
+  const out = {
+    id: String(raw.id).trim(),
+    provider: raw.provider,
+    selector: { ...raw.selector },
+    provenance: raw.provenance ?? 'config',
+  };
+
+  if (out.provider === 'jira' && out.selector.project) {
+    out.selector.project = String(out.selector.project).trim().toUpperCase();
+  }
+  if (out.provider === 'github' && out.selector.repo) {
+    out.selector.repo = String(out.selector.repo).trim();
+  }
+  if (out.provider === 'linear' && out.selector.team) {
+    out.selector.team = String(out.selector.team).trim();
+  }
+  if (out.provider === 'slack' && out.selector.channel) {
+    out.selector.channel = String(out.selector.channel).trim().replace(/^#/, '');
+    if (!out.selector.intent) out.selector.intent = 'internal';
+  }
+  return out;
+}
+
+export function resolveEffectiveSourceTargetsFromConfig(config, env = process.env) {
+  const configTargets = (config?.sources?.targets ?? []).map(normalizeConfigTarget);
+  const envTargets = legacyEnvSourceTargets(env);
+  return mergeSourceTargets(configTargets, envTargets);
+}
+
+export function targetsToEmbedSources(targets) {
+  const sources = [];
+  const githubRepos = targets.filter((t) => t.provider === 'github').map((t) => t.selector.repo);
+  if (githubRepos.length) {
+    sources.push({
+      provider: 'github',
+      repos: githubRepos,
+      refs: ['prs', 'issues', 'commits'],
+      limit: 25,
+    });
+    sources.push({
+      provider: 'github',
+      repos: githubRepos,
+      refs: ['meta', 'readme', 'docs'],
+      limit: 25,
+    });
+  }
+
+  for (const target of targets.filter((t) => t.provider === 'jira')) {
+    sources.push({
+      provider: 'jira',
+      project: target.selector.project,
+      refs: ['issues'],
+      limit: 50,
+    });
+  }
+
+  for (const target of targets.filter((t) => t.provider === 'linear')) {
+    sources.push({
+      provider: 'linear',
+      team: target.selector.team,
+      refs: ['issues'],
+      limit: 50,
+    });
+  }
+
+  const slackByIntent = new Map();
+  for (const target of targets.filter((t) => t.provider === 'slack')) {
+    const intent = target.selector.intent ?? 'internal';
+    if (!slackByIntent.has(intent)) slackByIntent.set(intent, []);
+    slackByIntent.get(intent).push(target.selector.channel);
+  }
+  for (const [intent, channels] of slackByIntent) {
+    sources.push({
+      provider: 'slack',
+      channels,
+      intent,
+      refs: ['messages'],
+      oldest: 86400,
+      limit: 50,
+    });
+  }
+
+  return sources;
+}
+
+export function resolveKnownSourcesFromTargets(targets) {
+  const sources = [];
+
+  for (const target of targets) {
+    const sel = target.selector ?? {};
+    if (target.provider === 'github' && sel.repo) {
+      const repo = sel.repo;
+      const short = repo.split('/').pop();
+      sources.push({ id: repo.toLowerCase(), provider: 'github', ref: repo, display: repo, targetId: target.id });
+      sources.push({ id: short.toLowerCase(), provider: 'github', ref: repo, display: repo, targetId: target.id });
+      sources.push({ id: short.replace(/-/g, '').toLowerCase(), provider: 'github', ref: repo, display: repo, targetId: target.id });
+      const words = short.split('-');
+      if (words.length > 1) {
+        sources.push({ id: words[words.length - 1].toLowerCase(), provider: 'github', ref: repo, display: repo, targetId: target.id });
+      }
+    }
+    if (target.provider === 'jira' && sel.project) {
+      const key = sel.project;
+      sources.push({ id: key.toLowerCase(), provider: 'jira', ref: key, display: `Jira/${key}`, targetId: target.id });
+    }
+    if (target.provider === 'linear' && sel.team) {
+      const team = sel.team;
+      sources.push({ id: team.toLowerCase(), provider: 'linear', ref: team, display: `Linear/${team}`, targetId: target.id });
+    }
+    if (target.provider === 'slack' && sel.channel) {
+      const ch = sel.channel;
+      sources.push({ id: ch.toLowerCase(), provider: 'slack', ref: ch, display: `Slack/${ch}`, targetId: target.id });
+    }
+  }
+
+  const providers = new Set(targets.map((t) => t.provider));
+  if (providers.has('jira')) {
+    sources.push({ id: 'jira', provider: 'jira', ref: null, display: 'Jira' });
+  }
+  if (providers.has('linear')) {
+    sources.push({ id: 'linear', provider: 'linear', ref: null, display: 'Linear' });
+  }
+
+  return sources;
+}

package/lib/doctor/source-checkout.mjs

@@ -0,0 +1,16 @@
+/**
+ * lib/doctor/source-checkout.mjs — distinguish Construct source tree vs npm install.
+ *
+ * `isConstructPackageRepo` is true for both checkouts and consumer installs.
+ * Source-only doctor checks (dashboard static export, certification role cards)
+ * should run only when this returns true.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+export function isConstructSourceCheckout(rootDir) {
+  const root = path.resolve(rootDir);
+  return fs.existsSync(path.join(root, 'apps', 'dashboard'))
+    || fs.existsSync(path.join(root, 'tests', 'certification', 'specialists'));
+}

package/lib/document-export.mjs

@@ -27,6 +27,7 @@ import {
 import { exportDeckPptx, pptxgenPresent } from './deck-export-pptx.mjs';
 import { pdfUsesBundledBrandSans } from './brand-fonts.mjs';
 import { convertDocxToDoc, libreOfficeInstallHint, libreOfficePresent, resolveLibreOfficeBin } from './libreoffice-export.mjs';
+import { resolveExportBranding } from './export-branding.mjs';
 
 export const EXPORT_FORMATS = ['pdf', 'docx', 'doc', 'deck', 'pptx', 'html', 'rtf', 'odt', 'epub', 'tex', 'txt', 'md', 'mdx'];
 
@@ -153,6 +154,7 @@ function installHint(name) {
   if (name === 'mmdc') return 'Install mermaid-cli for mermaid blocks (`npm install -g @mermaid-js/mermaid-cli`).';
   if (name === 'pptxgenjs') return 'Install pptxgenjs to enable PPTX export (`npm install pptxgenjs` in the Construct package).';
   if (name === 'construct-deck.html') return 'Bundled deck template missing from templates/distribution/construct-deck.html (Construct install integrity issue).';
+  if (name === 'construct-reference.docx') return 'Bundled branded reference doc missing from templates/distribution/construct-reference.docx; construct-branded DOCX export degrades to pandoc default styling. Regenerate from a source checkout with `node scripts/build-reference-docx.mjs`.';
   if (name === 'libreoffice') return libreOfficeInstallHint();
   return `Install ${name} to enable this export format.`;
 }
@@ -160,13 +162,17 @@ function installHint(name) {
 export function detect(format, env = process.env, {
   figures = false,
   artifactType = null,
+  branding = 'construct',
   cwd = process.cwd(),
   repoRoot = REPO_ROOT,
 } = {}) {
-  const config = FORMAT_ENGINES[format];
-  if (!config) return { ok: false, format, present: false, missing: [], message: `Unsupported format: ${format}. Supported: ${EXPORT_FORMATS.join(', ')}.` };
+  const brandingPolicy = resolveExportBranding(format, branding);
+  const config = format === 'pptx' && brandingPolicy.applied === 'plain'
+    ? { engine: 'pandoc', writer: 'pptx', pdfEngine: null, extraBinaries: [] }
+    : FORMAT_ENGINES[format];
+  if (!config) return { ok: false, format, branding: brandingPolicy, present: false, missing: [], message: `Unsupported format: ${format}. Supported: ${EXPORT_FORMATS.join(', ')}.` };
   if (config.engine === 'copy') {
-    return { ok: true, format, figures: false, present: true, binaries: [], missing: [], message: `Ready: source emit (${format})` };
+    return { ok: true, format, branding: brandingPolicy, figures: false, present: true, binaries: [], missing: [], message: `Ready: source emit (${format})` };
   }
   const required = [];
   if (config.engine === 'pptxgenjs') {
@@ -174,13 +180,19 @@ export function detect(format, env = process.env, {
   } else {
     required.push(config.engine, ...(config.extraBinaries || []));
   }
-  if (format === 'pdf') {
+  if (format === 'pdf' && brandingPolicy.applied === 'construct') {
     const template = detectPdfTemplate({ artifactType, cwd, repoRoot });
     if (!template.present) required.push('construct-pdf.typ');
   }
-  if (format === 'deck' && !deckTemplatePath(repoRoot)) {
+  if (format === 'deck' && brandingPolicy.applied === 'construct' && !deckTemplatePath(repoRoot)) {
     required.push('construct-deck.html');
   }
+  if (format === 'html' && brandingPolicy.applied === 'construct' && !htmlTemplatePath(repoRoot)) required.push('construct-web.html');
+
+  // The DOCX reference doc only restyles pandoc output; pandoc emits a valid file without it and
+  // the export passes --reference-doc only when present, so unlike the PDF/HTML/deck templates a
+  // missing reference degrades gracefully rather than blocking the export.
+
   if (format === 'doc' && !libreOfficePresent(env)) {
     required.push('libreoffice');
   }
@@ -193,9 +205,10 @@ export function detect(format, env = process.env, {
     if (name.endsWith('.lua')) {
       return { name, path: fs.existsSync(diagramFilterPath()) ? diagramFilterPath() : null, version: null };
     }
-    if (name.endsWith('.html')) {
+    if (name === 'construct-deck.html') {
       return { name, path: deckTemplatePath(repoRoot), version: null };
     }
+    if (name === 'construct-web.html') return { name, path: htmlTemplatePath(repoRoot), version: null };
     if (name === 'pptxgenjs') {
       return { name, path: pptxgenPresent() ? 'bundled' : null, version: null };
     }
@@ -213,6 +226,7 @@ export function detect(format, env = process.env, {
   return {
     ok: true,
     format,
+    branding: brandingPolicy,
     figures,
     present: missing.length === 0,
     binaries: status,
@@ -290,6 +304,7 @@ export function exportMarkdown({
   outputPath,
   format,
   figures = false,
+  branding = 'construct',
   artifactType = null,
   env = process.env,
   spawnFn = spawnSync,
@@ -304,21 +319,24 @@ export function exportMarkdown({
   const resolvedType = artifactType || metadata.artifactType || null;
   const effectiveEnv = figures ? buildDistributionDiagramEnv(env) : env;
 
-  const detection = detect(format, effectiveEnv, { figures, artifactType: resolvedType, cwd, repoRoot });
+  const brandingPolicy = resolveExportBranding(format, branding);
+  const detection = detect(format, effectiveEnv, { figures, artifactType: resolvedType, branding, cwd, repoRoot });
   if (!detection.present) {
     return { ok: false, format, inputPath, missing: detection.missing, message: detection.message };
   }
 
-  const config = FORMAT_ENGINES[format];
+  const config = format === 'pptx' && brandingPolicy.applied === 'plain'
+    ? { engine: 'pandoc', writer: 'pptx', pdfEngine: null, extraBinaries: [] }
+    : FORMAT_ENGINES[format];
   const target = path.resolve(outputPath || defaultOutputPath(inputPath, format));
   fs.mkdirSync(path.dirname(target), { recursive: true });
 
   if (config.engine === 'copy') {
-    return exportSourceCopy({ inputPath, target, format });
+    return { ...exportSourceCopy({ inputPath, target, format }), branding: brandingPolicy };
   }
 
-  if (format === 'pptx') {
-    return exportDeckPptx({ inputPath, outputPath: target, metadata, repoRoot });
+  if (format === 'pptx' && brandingPolicy.applied === 'construct') {
+    return { ...exportDeckPptx({ inputPath, outputPath: target, metadata, repoRoot }), branding: brandingPolicy };
   }
 
   if (format === 'doc') {
@@ -328,6 +346,7 @@ export function exportMarkdown({
       outputPath: intermediate,
       format: 'docx',
       figures,
+      branding,
       artifactType: resolvedType,
       env: effectiveEnv,
       spawnFn,
@@ -356,12 +375,13 @@ export function exportMarkdown({
       pdfEngine: null,
       figures,
       template: null,
+      branding: brandingPolicy,
       message: loResult.message,
     };
   }
 
   const prepared = prepareExportInput(inputPath, { format, figures, metadata });
-  const templatePath = format === 'pdf'
+  const templatePath = format === 'pdf' && brandingPolicy.applied === 'construct'
     ? resolvePdfTemplatePath({ artifactType: resolvedType, cwd, repoRoot })
     : null;
 
@@ -378,25 +398,26 @@ export function exportMarkdown({
   });
 
   const args = ['-f', 'markdown', '-o', target, '--standalone'];
+  if (config.writer) args.push('-t', config.writer);
   if (config.pdfEngine) args.push(`--pdf-engine=${config.pdfEngine}`);
   if (format === 'pdf') {
     if (templatePath) args.push('--template', templatePath);
-    args.push(...pdfEngineFontOpts(repoRoot));
+    if (brandingPolicy.applied === 'construct') args.push(...pdfEngineFontOpts(repoRoot));
     args.push(...metadataArgs);
   } else if (format === 'html') {
     const htmlTpl = htmlTemplatePath(repoRoot);
-    if (htmlTpl) args.push('--template', htmlTpl);
+    if (htmlTpl && brandingPolicy.applied === 'construct') args.push('--template', htmlTpl);
     args.push('--embed-resources');
     args.push(...metadataArgs);
   } else if (format === 'deck') {
     const deckTpl = deckTemplatePath(repoRoot);
-    if (deckTpl) args.push('--template', deckTpl);
+    if (deckTpl && brandingPolicy.applied === 'construct') args.push('--template', deckTpl);
     args.push('--section-divs');
     args.push('--embed-resources');
     args.push(...metadataArgs);
   } else if (format === 'docx') {
     const ref = docxReferencePath(repoRoot);
-    if (ref) args.push('--reference-doc', ref);
+    if (ref && brandingPolicy.applied === 'construct') args.push('--reference-doc', ref);
     args.push(...metadataArgs);
   }
   if (figures && fs.existsSync(diagramFilterPath())) {
@@ -443,6 +464,7 @@ export function exportMarkdown({
     pdfEngine: config.pdfEngine,
     figures,
     template: templatePath,
+    branding: brandingPolicy,
     message: `Wrote ${path.relative(process.cwd(), target)}`,
   };
 }

package/lib/embed/auto-sources.mjs

@@ -0,0 +1,44 @@
+/**
+ * lib/embed/auto-sources.mjs — resolve embed auto-discovery sources from project config.
+ *
+ * When embed.yaml is absent, builds provider source records from typed
+ * construct.config.json targets merged with legacy env lists. Falls back
+ * to broad provider defaults only when no targets are configured.
+ */
+
+import { loadProjectConfig } from '../config/project-config.mjs';
+import {
+  resolveEffectiveSourceTargetsFromConfig,
+  targetsToEmbedSources,
+  legacyEnvSourceTargets,
+} from '../config/source-targets.mjs';
+
+export function resolveAutoEmbedSources({ cwd = process.cwd(), env = process.env, registry }) {
+  const { config } = loadProjectConfig(cwd, env);
+  const targets = resolveEffectiveSourceTargetsFromConfig(config, env);
+
+  if (targets.length === 0) {
+    return registry.autoSources(env);
+  }
+
+  const configuredProviders = new Set(targets.map((t) => t.provider));
+  const hasLegacyForUnconfigured = (provider) =>
+    legacyEnvSourceTargets(env).some((t) => t.provider === provider);
+
+  const sources = targetsToEmbedSources(targets);
+
+  for (const name of registry.names()) {
+    if (configuredProviders.has(name)) continue;
+    if (hasLegacyForUnconfigured(name)) continue;
+    const instance = registry.get(name);
+    if (typeof instance?.defaultSources !== 'function') continue;
+  }
+
+  const seen = new Set();
+  return sources.filter((s) => {
+    const key = `${s.provider}:${(s.refs ?? []).join(',')}:${JSON.stringify(s.repos ?? s.project ?? s.team ?? s.channels ?? '')}`;
+    if (seen.has(key)) return false;
+    seen.add(key);
+    return true;
+  });
+}

package/lib/embed/cli.mjs

@@ -401,7 +401,8 @@ async function cmdEmbedSnapshot(args, { homeDir = os.homedir() } = {}) {
   if (fs.existsSync(configPath)) {
     cfg = loadEmbedConfig(configPath);
   } else {
-    cfg = { ...EMPTY_CONFIG, sources: registry.autoSources(env) };
+    const { resolveAutoEmbedSources } = await import('./auto-sources.mjs');
+    cfg = { ...EMPTY_CONFIG, sources: resolveAutoEmbedSources({ cwd: process.cwd(), env, registry }) };
   }
 
   if (!cfg.sources.length) {