@geraldmaron/construct 1.1.1 → 1.2.1

package/lib/providers/secret-resolver.mjs

@@ -0,0 +1,159 @@
+/**
+ * lib/providers/secret-resolver.mjs — single credential resolver for the LLM path.
+ *
+ * Resolves a canonical environment variable (for example ANTHROPIC_API_KEY) by
+ * walking the same sources the rest of Construct trusts, in priority order:
+ * process env, ~/.construct/config.env, ~/.env, the project .env, then shell rc
+ * files (.zshrc/.bashrc/.bash_profile/.profile). When the value carries a
+ * 1Password reference — a bare `op://vault/item/field` or the shell form
+ * `$(op read 'op://...')` — it is resolved through the `op` CLI and cached for
+ * the process lifetime so a single launch prompts at most once per reference.
+ *
+ * resolveSecret performs the `op read` (and may surface a structured
+ * SecretResolutionError); hasSecret only checks presence and never invokes the
+ * CLI, so detection stays fast and free of biometric prompts. The plaintext
+ * value lives only in this module's cache and is never logged. allowAmbient lets
+ * a hermetic caller (tests, embedded callers that inject their own env) suppress
+ * file/rc discovery so a developer key never bleeds into an isolated run.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { spawnSync } from 'node:child_process';
+import { discoverAlternateRawForVar } from './credential-sources.mjs';
+
+// The 1Password desktop integration prompts for biometric unlock on the first
+// read after the vault locks, and that interactive round-trip routinely takes
+// 7–8s — well past a snappy 5s budget. Allow enough headroom that an approved
+// Touch ID unlock resolves instead of being killed mid-prompt; cached reads
+// afterward return in well under a second.
+const OP_READ_TIMEOUT_MS = 20000;
+
+const opCache = new Map();
+
+export class SecretResolutionError extends Error {
+  constructor(message, code) {
+    super(message);
+    this.name = 'SecretResolutionError';
+    this.code = code;
+  }
+}
+
+function unquote(value) {
+  return String(value).trim().replace(/^(['"])([\s\S]*)\1$/, '$2').trim();
+}
+
+// Two op:// carriers are accepted: a bare reference, or the `$(op read '...')`
+// command-substitution form commonly written into dotenv and shell rc files.
+
+export function extractOpRef(rawValue) {
+  if (!rawValue) return null;
+  const value = unquote(rawValue);
+  if (value.startsWith('op://')) return value;
+  const m = value.match(/\$\(\s*op\s+read\s+(['"]?)(op:\/\/[^'")\s]+)\1\s*\)/);
+  return m ? m[2] : null;
+}
+
+function defaultOpRead(opRef) {
+  const result = spawnSync('op', ['read', opRef], { encoding: 'utf8', timeout: OP_READ_TIMEOUT_MS });
+  if (result.error && result.error.code === 'ENOENT') {
+    throw new SecretResolutionError('1Password CLI not found — install `op` or set the key directly.', 'OP_NOT_INSTALLED');
+  }
+  if (result.status !== 0) {
+    const stderr = String(result.stderr || '').toLowerCase();
+    if (/sign in|signin|session|not currently|authenticate|authorization|no account/.test(stderr)) {
+      throw new SecretResolutionError('1Password CLI is not signed in — run `op signin` and retry.', 'OP_NOT_SIGNED_IN');
+    }
+    throw new SecretResolutionError(`op read failed for ${opRef}: ${String(result.stderr || '').trim().slice(0, 160)}`, 'OP_READ_FAILED');
+  }
+  const secret = String(result.stdout || '').trim();
+  if (!secret) throw new SecretResolutionError(`op read returned an empty value for ${opRef}`, 'OP_EMPTY');
+  return secret;
+}
+
+export function resolveOpRef(opRef, { opRead = defaultOpRead } = {}) {
+  if (opCache.has(opRef)) return opCache.get(opRef);
+  const secret = opRead(opRef);
+  opCache.set(opRef, secret);
+  return secret;
+}
+
+function materialize(rawValue, opts) {
+  const ref = extractOpRef(rawValue);
+  return ref ? resolveOpRef(ref, opts) : unquote(rawValue);
+}
+
+function readDotenvVar(file, varName) {
+  try {
+    if (!fs.existsSync(file)) return null;
+    const m = fs.readFileSync(file, 'utf8').match(new RegExp(`^${varName}=(.+)$`, 'm'));
+    return m ? m[1].trim() : null;
+  } catch {
+    return null;
+  }
+}
+
+function readShellRcVar(varName, home) {
+  const files = ['.zshrc', '.bashrc', '.bash_profile', '.profile'].map((f) => path.join(home, f));
+  for (const rc of files) {
+    try {
+      if (!fs.existsSync(rc)) continue;
+      const m = fs.readFileSync(rc, 'utf8').match(new RegExp(`^\\s*export\\s+${varName}=(.+)$`, 'm'));
+      if (m) return m[1].trim();
+    } catch {
+      continue;
+    }
+  }
+  return null;
+}
+
+function rawCandidate(varName, { env, cwd, home }) {
+  const direct = env?.[varName];
+  if (typeof direct === 'string' && direct.length > 0) return direct;
+  const files = [path.join(home, '.construct', 'config.env'), path.join(home, '.env'), path.join(cwd, '.env')];
+  for (const file of files) {
+    const value = readDotenvVar(file, varName);
+    if (value) return value;
+  }
+  const alt = discoverAlternateRawForVar(varName, { home });
+  if (alt) return alt;
+  return readShellRcVar(varName, home);
+}
+
+export function resolveSecret(varName, { env = process.env, cwd = process.cwd(), allowAmbient = true, opRead } = {}) {
+  const direct = env?.[varName];
+  if (typeof direct === 'string' && direct.length > 0) return materialize(direct, { opRead });
+  if (!allowAmbient) return null;
+  const home = os.homedir();
+  const raw = rawCandidate(varName, { env, cwd, home });
+  return raw ? materialize(raw, { opRead }) : null;
+}
+
+export function resolveFirstSecret(varNames, opts = {}) {
+  for (const name of varNames) {
+    const value = resolveSecret(name, opts);
+    if (value) return value;
+  }
+  return null;
+}
+
+// Presence check that never runs `op read`: a stored op:// reference counts as
+// configured because the plaintext is resolved lazily at call time.
+
+export function hasSecret(varName, { env = process.env, cwd = process.cwd(), allowAmbient = true } = {}) {
+  const direct = env?.[varName];
+  if (typeof direct === 'string' && direct.length > 0) return true;
+  if (!allowAmbient) return false;
+  const home = os.homedir();
+  const raw = rawCandidate(varName, { env, cwd, home });
+  return typeof raw === 'string' && raw.length > 0;
+}
+
+export function hasAnySecret(varNames, opts = {}) {
+  return varNames.some((name) => hasSecret(name, opts));
+}
+
+export function __clearSecretCache() {
+  opCache.clear();
+}

package/lib/publish-template.mjs

@@ -0,0 +1,163 @@
+/**
+ * lib/publish-template.mjs — type-specific PDF template routing and brand tokens
+ * for Construct distribution exports.
+ *
+ * Projects override via `.cx/publish-theme.typ`. Otherwise artifactType selects
+ * bundled editorial (PRD), analytics (research), or decision (ADR/RFC) layouts.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import yaml from 'js-yaml';
+import { BRAND, BRAND_TOKENS } from './brand-tokens.mjs';
+
+export { BRAND, BRAND_TOKENS };
+
+export const ARTIFACT_TEMPLATE_MAP = {
+  prd: 'construct-prd.typ',
+  'prd-platform': 'construct-prd.typ',
+  'prd-business': 'construct-prd.typ',
+  'meta-prd': 'construct-prd.typ',
+  strategy: 'construct-prd.typ',
+  runbook: 'construct-prd.typ',
+  memo: 'construct-prd.typ',
+  'one-pager': 'construct-prd.typ',
+  prfaq: 'construct-prd.typ',
+  'backlog-proposal': 'construct-prd.typ',
+  'customer-profile': 'construct-prd.typ',
+  'test-plan': 'construct-prd.typ',
+  'qa-strategy': 'construct-prd.typ',
+  'changelog-entry': 'construct-prd.typ',
+  'incident-report': 'construct-prd.typ',
+  postmortem: 'construct-prd.typ',
+  'research-brief': 'construct-research.typ',
+  'evidence-brief': 'construct-research.typ',
+  'signal-brief': 'construct-research.typ',
+  'research-finding': 'construct-research.typ',
+  'product-intelligence-report': 'construct-research.typ',
+  adr: 'construct-decision.typ',
+  rfc: 'construct-decision.typ',
+  'rfc-platform': 'construct-decision.typ',
+  'security-audit-report': 'construct-decision.typ',
+};
+
+const FALLBACK_TEMPLATE = 'construct-pdf.typ';
+
+export function bundledTemplateDir(repoRoot) {
+  return path.join(repoRoot, 'templates', 'distribution');
+}
+
+export function distributionFontsDir(repoRoot) {
+  return path.join(bundledTemplateDir(repoRoot), 'fonts');
+}
+
+export function resolvePdfTemplatePath({
+  artifactType = null,
+  cwd = process.cwd(),
+  repoRoot,
+} = {}) {
+  const root = repoRoot || cwd;
+  const projectOverride = path.join(cwd, '.cx', 'publish-theme.typ');
+  if (fs.existsSync(projectOverride)) return projectOverride;
+
+  const dir = bundledTemplateDir(root);
+  const mapped = artifactType ? ARTIFACT_TEMPLATE_MAP[artifactType] : null;
+  if (mapped) {
+    const typePath = path.join(dir, mapped);
+    if (fs.existsSync(typePath)) return typePath;
+  }
+
+  const fallback = path.join(dir, FALLBACK_TEMPLATE);
+  if (fs.existsSync(fallback)) return fallback;
+  return null;
+}
+
+export function templateForArtifactType(artifactType) {
+  if (!artifactType) return FALLBACK_TEMPLATE;
+  return ARTIFACT_TEMPLATE_MAP[artifactType] || FALLBACK_TEMPLATE;
+}
+
+export function formatPublishDate(value) {
+  if (value == null || value === '') return '';
+  if (value instanceof Date) {
+    if (Number.isNaN(value.getTime())) return '';
+    return value.toISOString().slice(0, 10);
+  }
+  const text = String(value).trim();
+  if (/^\d{4}-\d{2}-\d{2}/.test(text)) return text.slice(0, 10);
+  const parsed = new Date(text);
+  if (!Number.isNaN(parsed.getTime())) return parsed.toISOString().slice(0, 10);
+  return text;
+}
+
+function escapeRegExp(text) {
+  return String(text).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+function stripCoverDuplicatesFromBody(body, metadata = {}) {
+  let out = String(body || '').replace(/^\s+/, '');
+  const title = metadata.title?.trim();
+  if (title) {
+    const h1Re = new RegExp(`^#\\s+${escapeRegExp(title)}\\s*\\n+`, 'i');
+    out = out.replace(h1Re, '');
+  }
+  const lines = out.split('\n');
+  while (lines.length && /^-\s+\*\*(Date|Owner|Status)\*\*:/i.test(lines[0].trim())) {
+    lines.shift();
+  }
+  while (lines.length && lines[0].trim() === '') lines.shift();
+  return `${lines.join('\n')}\n`;
+}
+
+export function preprocessMarkdownForPdfExport(content, metadata = {}) {
+  if (!metadata?.title) return content;
+  if (!content.startsWith('---')) return stripCoverDuplicatesFromBody(content, metadata);
+  const end = content.indexOf('\n---', 3);
+  if (end === -1) return stripCoverDuplicatesFromBody(content, metadata);
+  const frontmatter = content.slice(0, end + 4);
+  const body = stripCoverDuplicatesFromBody(content.slice(end + 4), metadata);
+  return `${frontmatter}\n${body}`;
+}
+
+export function parseArtifactMetadata(inputPath) {
+  const content = fs.readFileSync(inputPath, 'utf8');
+  let fm = {};
+  let body = content;
+  if (content.startsWith('---')) {
+    const end = content.indexOf('\n---', 3);
+    if (end !== -1) {
+      try {
+        fm = yaml.load(content.slice(3, end)) || {};
+      } catch {
+        fm = {};
+      }
+      body = content.slice(end + 4);
+    }
+  }
+
+  const h1 = body.match(/^#\s+(.+)$/m);
+  const ownerMatch = body.match(/\*\*Owner\*\*:\s*(\S+)/);
+  const dateMatch = body.match(/\*\*Date\*\*:\s*(\S+)/);
+
+  return {
+    title: fm.title || (h1 ? h1[1].trim() : path.basename(inputPath, path.extname(inputPath))),
+    subtitle: fm.subtitle || '',
+    date: formatPublishDate(fm.date || fm.last_verified_at || (dateMatch ? dateMatch[1] : '')),
+    status: fm.status || '',
+    owner: fm.owner || (ownerMatch ? ownerMatch[1] : ''),
+    artifactType: fm.artifactType || fm.artifact_type || '',
+    version: fm.version != null ? String(fm.version) : '',
+    docId: fm.doc_id || fm.docId || '',
+    classification: fm.classification || '',
+  };
+}
+
+export function pandocMetadataArgs(metadata = {}) {
+  const args = [];
+  for (const [key, value] of Object.entries(metadata)) {
+    if (value == null || value === '') continue;
+    const safe = String(value).replace(/"/g, '\\"');
+    args.push('-M', `${key}=${safe}`);
+  }
+  return args;
+}

package/lib/publish-tooling.mjs

@@ -0,0 +1,119 @@
+/**
+ * lib/publish-tooling.mjs — detect optional binaries for the publish pipeline.
+ *
+ * Composes export (Pandoc/Typst), diagram (D2/mmdc), terminal demo (VHS), and
+ * dashboard demo (Playwright workspace) probes for `construct tools detect`,
+ * `construct publish --strict`, and doctor one-shot checks.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { detect as detectExport } from './document-export.mjs';
+import { locateRenderer } from './diagram.mjs';
+import { locateRecorder } from './demo.mjs';
+import { detectDashboardDemo } from './dashboard-demo.mjs';
+import { detectIngestPipeline } from './ingest-tooling.mjs';
+
+const REPO_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+
+export function diagramFilterPath() {
+  return path.join(REPO_ROOT, 'vendor', 'pandoc-ext', 'diagram.lua');
+}
+
+function whichBin(name) {
+  const cmd = process.platform === 'win32' ? 'where' : 'which';
+  const result = spawnSync(cmd, [name], { encoding: 'utf8' });
+  if (result.status !== 0) return null;
+  return (result.stdout || '').trim().split('\n')[0] || null;
+}
+
+export function detectFigureBinaries(env = process.env) {
+  const d2 = whichBin('d2');
+  const mmdc = whichBin('mmdc');
+  const dot = whichBin('dot');
+  const filter = fs.existsSync(diagramFilterPath());
+  const missing = [];
+  if (!filter) missing.push('diagram.lua (vendor/pandoc-ext/diagram.lua)');
+  if (!d2 && !dot) missing.push('d2 or graphviz dot');
+  if (!mmdc) missing.push('mmdc (@mermaid-js/mermaid-cli)');
+  return {
+    ok: true,
+    present: missing.length === 0,
+    filter,
+    d2,
+    dot,
+    mmdc,
+    missing,
+    message: missing.length === 0
+      ? 'Figure tooling ready (pandoc-ext/diagram + d2/mmdc)'
+      : `Install figure tooling: ${missing.join('; ')}`,
+  };
+}
+
+export function detectPublishPipeline({
+  format = 'pdf',
+  includeFigures = true,
+  includeTerminalDemo = false,
+  includeDashboardDemo = false,
+  includeIngest = true,
+  cwd = process.cwd(),
+  repoRoot = REPO_ROOT,
+  env = process.env,
+} = {}) {
+  const steps = {};
+  const missing = [];
+
+  const exportDetect = detectExport(format, env, { figures: includeFigures, cwd, repoRoot });
+  steps.export = exportDetect;
+  if (!exportDetect.present) missing.push(...(exportDetect.missing || []));
+
+  if (includeIngest) {
+    steps.ingest = detectIngestPipeline({ cwd, env, repoRoot });
+  }
+
+  if (includeFigures) {
+    const figures = detectFigureBinaries(env);
+    steps.figures = figures;
+    if (!figures.present) missing.push(...figures.missing);
+  }
+
+  if (includeTerminalDemo) {
+    const recorder = locateRecorder();
+    steps.terminalDemo = {
+      present: Boolean(recorder),
+      engine: recorder?.engine || null,
+      missing: recorder ? [] : ['vhs or asciinema'],
+    };
+    if (!recorder) missing.push('vhs');
+  }
+
+  if (includeDashboardDemo) {
+    const dashboard = detectDashboardDemo({ cwd, repoRoot: REPO_ROOT });
+    steps.dashboardDemo = dashboard;
+    if (!dashboard.present) missing.push(...dashboard.missing);
+  }
+
+  const uniqueMissing = [...new Set(missing)];
+  return {
+    ok: true,
+    present: uniqueMissing.length === 0,
+    format,
+    steps,
+    missing: uniqueMissing,
+    message: uniqueMissing.length === 0
+      ? 'Publish pipeline ready'
+      : `Missing: ${uniqueMissing.join(', ')}`,
+  };
+}
+
+export function formatToolsDetectReport(detection, { json = false } = {}) {
+  if (json) return JSON.stringify(detection, null, 2);
+  const lines = [`Publish pipeline: ${detection.present ? 'ready' : 'degraded'}`];
+  for (const [key, step] of Object.entries(detection.steps || {})) {
+    lines.push(`  ${key}: ${step.present ? 'ok' : 'missing'}${step.message ? ` — ${step.message}` : ''}`);
+  }
+  if (detection.missing?.length) lines.push(`Install: ${detection.missing.join('; ')}`);
+  return lines.join('\n');
+}