@geraldmaron/construct 1.1.1 → 1.2.1

package/examples/distribution/sources/runbook.md

@@ -0,0 +1,103 @@
+---
+description: Distribution example — operational runbook with diagnostic flow and severity table.
+artifactType: runbook
+subtitle: Publish pipeline degraded — Pandoc or figure tooling missing
+version: "1.1"
+doc_id: RUNBOOK-PUBLISH-001
+classification: internal
+status: accepted
+owner: cx-sre
+last_verified_at: 2026-06-22
+---
+
+# Runbook: construct publish / export failures
+
+- **Service**: document-export (`construct publish`, `construct export`)
+- **Owner**: platform on-call
+- **Last tested**: 2026-06-22
+- **Severity**: SEV-2 when exports block release; SEV-3 when examples only
+
+## Alert trigger
+
+`construct publish` exits 2 with `missing: pandoc` or `Figure tooling` in `construct tools detect --figures` output. CI job `release:check` fails on export certification scenarios.
+
+## Symptoms
+
+- PDF export fails before Typst invocation
+- `--figures` renders empty diagram placeholders
+- `npm run examples:distribution` reports partial failures in summary
+
+## Impact
+
+| Audience | Impact |
+|---|---|
+| Release managers | Cannot ship branded PRDs/ADRs |
+| Developers | Local previews blocked |
+| Agents | `publish_run` MCP tool returns remediation hints |
+
+## Severity and response
+
+| Severity | Trigger condition | Page within | Comms | Error budget |
+|----------|-------------------|-------------|-------|--------------|
+| SEV-1 | All publish paths down in CI | 5 min | #incident + status | breach → freeze |
+| SEV-2 | PDF down, HTML OK | 15 min | #platform | partial spend |
+| SEV-3 | Examples script only | business hours | team channel | none |
+
+## Diagnostic steps
+
+1. Run `construct tools detect --figures --json` and read `steps.export` + `steps.figures`.
+2. Confirm `pandoc` and `typst` on PATH; confirm `d2` and `mmdc` when `--figures` is set.
+3. Re-run a single fixture: `node bin/construct export examples/distribution/sources/adr.md --to=pdf --figures`.
+
+```mermaid
+flowchart TD
+  A[Alert fires] --> B{export.present?}
+  B -->|No| C[Install pandoc + typst]
+  B -->|Yes| D{figures.present?}
+  D -->|No| E[brew install d2; npm i -g @mermaid-js/mermaid-cli]
+  D -->|Yes| F[Re-run examples:distribution]
+  C --> F
+  E --> F
+```
+
+```d2
+direction: down
+
+detect: tools detect
+pandoc: pandoc + typst
+figures: d2 + mmdc
+ok: Green export
+
+detect -> pandoc: if missing
+detect -> figures: if --figures
+pandoc -> ok
+figures -> ok
+```
+
+## Remediation
+
+```bash
+brew install pandoc typst d2 graphviz
+npm install -g @mermaid-js/mermaid-cli
+npm run examples:distribution
+open .tmp/distribution-examples/index.html
+```
+
+Expected: index lists PDF and HTML links for each artifact type; no `FAILED` lines in script output.
+
+## Rollback
+
+Not applicable — this runbook restores tooling, not application state. If a bad template change caused failures, revert the Typst commit and re-run exports.
+
+## Escalation
+
+After 30 minutes without restore: page cx-platform-engineer. After 60 minutes with release blocked: page cx-release-manager.
+
+## Post-incident
+
+Preserve `construct tools detect --json` output and the failing pandoc/typst stderr in the incident ticket.
+
+## References
+
+- `docs/reference/document-io.md`
+- `docs/cookbook/diagram-and-demo.md`

package/examples/distribution/sources/strategy.md

@@ -0,0 +1,88 @@
+---
+description: Distribution example — strategy memo with goals, metrics, and landscape diagram.
+artifactType: strategy
+subtitle: Make Construct the default governed layer for agentic IDE workflows
+version: "1.0"
+doc_id: STRATEGY-2026-H1
+classification: internal
+status: draft
+owner: cx-product-manager
+last_verified_at: 2026-06-22
+---
+
+# Strategy: Governed agentic workflows for IDE-native teams
+
+- **Date**: 2026-06-22
+- **Owner**: cx-product-manager
+- **Status**: draft
+- **Horizon**: H1 2026 – H1 2027
+
+> Platform and product teams want specialist routing without losing citation discipline, branded exports, or profile-aware terminology. Construct wins when evaluators can open one gallery of PDFs and see the same ink, typography, and diagram styling across document types.
+
+## Problem
+
+Host-native agents optimize for single-session chat. Enterprise platform teams need durable invoke plans, manifest-enforced artifacts, and distribution that looks intentional — not markdown attachments with host fonts.
+
+## Goals
+
+1. **Prove value in five minutes** — `npm run examples:distribution` produces a browsable gallery with figures.
+2. **One brand contract** — `docs/reference/branding.md` + `03d-brand` audit ratchet.
+3. **Profile-aware language** — intake queue labels follow active profile rebrand in CLI, session prelude, and dashboard API.
+
+## Non-goals
+
+Replacing host LLM execution. Mandating cloud render farms. Re-linting every historical doc for marketing voice.
+
+## Landscape
+
+```mermaid
+flowchart TB
+  subgraph hosts [IDE hosts]
+    CC[Claude Code]
+    OC[OpenCode]
+    CX[Cursor]
+  end
+  subgraph construct [Construct]
+    R[Router]
+    V[Validate]
+    P[Publish]
+  end
+  hosts --> R --> V --> P
+  P --> PDF[Branded PDF]
+  P --> HTML[HTML / deck]
+```
+
+```d2
+direction: down
+
+construct: Construct {
+  style.fill: "#f3f4f6"
+}
+
+hosts: IDE hosts
+validate: Release gate
+export: Branded export
+
+hosts -> construct -> validate -> export
+```
+
+## Success metrics
+
+| Metric | Baseline | Target |
+|---|---|---|
+| Brand audit findings | unknown | 0 in `03d-brand` |
+| Example types with figures | 1 (PRD) | ≥6 layouts |
+| Dashboard rebrand coverage | partial | intake API + pages |
+
+## Risks and mitigations
+
+| Risk | Mitigation |
+|---|---|
+| Toolchain missing on contributor laptops | `construct tools detect --figures` in runbook |
+| Template drift | Functional tests on `construct-brand.typ` + HTML decks |
+| Profile label regressions | `intake-rebrand.functional.test.mjs` |
+
+## References
+
+- `examples/distribution/manifest.json`
+- https://langchain-ai.github.io/langgraph/ (accessed 2026-06-22)

package/lib/adapters-sync.mjs

@@ -0,0 +1,67 @@
+/**
+ * lib/adapters-sync.mjs — project adapter sync for the Construct tool repo and
+ * `npm run adapters`. Detects installed hosts, runs sync-specialists --project,
+ * and is invoked from postinstall when developing inside the package itself.
+ */
+
+import { spawnSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { detectHostCapabilities } from './host-capabilities.mjs';
+import { isConstructPackageRepo } from './host-disposition.mjs';
+import { stageProjectAdapters } from './install/stage-project.mjs';
+
+const MODULE_DIR = path.dirname(fileURLToPath(import.meta.url));
+const PKG_ROOT = path.resolve(MODULE_DIR, '..');
+
+const HOST_ID_MAP = {
+  'Claude Code': 'claude',
+  OpenCode: 'opencode',
+  Codex: 'codex',
+  'VS Code': 'vscode',
+  Cursor: 'cursor',
+  Copilot: 'copilot',
+};
+
+export function resolveAdapterHosts({ forceAll = false, extra = [] } = {}) {
+  if (forceAll) return ['claude', 'opencode', 'codex', 'vscode', 'cursor'];
+  const hosts = new Set(extra);
+  for (const entry of detectHostCapabilities()) {
+    if (entry.availability !== 'installed') continue;
+    const id = HOST_ID_MAP[entry.host];
+    if (id) hosts.add(id);
+  }
+  if (hosts.size === 0) hosts.add('claude');
+  return [...hosts];
+}
+
+export function syncProjectAdapters({
+  projectRoot = process.cwd(),
+  packageRoot = PKG_ROOT,
+  hosts = null,
+  log = () => {},
+} = {}) {
+  const resolvedHosts = hosts ?? resolveAdapterHosts({ forceAll: isConstructPackageRepo(projectRoot) });
+  return stageProjectAdapters({
+    projectRoot,
+    packageRoot,
+    pkgVersion: null,
+    log,
+    hosts: resolvedHosts,
+  });
+}
+
+export function runAdaptersScript({ cwd = process.cwd(), hosts = null } = {}) {
+  const result = syncProjectAdapters({ projectRoot: cwd, hosts, log: (m) => process.stdout.write(`[adapters] ${m}\n`) });
+  return result.synced ? 0 : 1;
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  const args = new Set(process.argv.slice(2));
+  const forceAll = args.has('--all-hosts');
+  const hosts = forceAll ? resolveAdapterHosts({ forceAll: true }) : null;
+  const code = runAdaptersScript({ cwd: process.cwd(), hosts });
+  process.exit(code);
+}

package/lib/artifact-gate-notice.mjs

@@ -0,0 +1,38 @@
+/**
+ * lib/artifact-gate-notice.mjs — Shared PostToolUse artifact structure/visual check.
+ *
+ * Returns violations for typed docs under docs/** and .cx/research/** without
+ * applying TTY/CI suppression (callers decide whether to emit).
+ */
+
+import path from 'node:path';
+import { inferArtifactTypeFromPath, isArtifactGatePath } from './artifact-type-from-path.mjs';
+import { lintDocStructure, lintDocVisuals } from './templates/visual-requirements.mjs';
+
+export function checkArtifactGateNotice(filePath, { cwd = process.cwd() } = {}) {
+  const rel = filePath.startsWith(cwd)
+    ? filePath.slice(cwd.length).replace(/^\/+/, '')
+    : filePath;
+  if (!isArtifactGatePath(rel)) return null;
+
+  const type = inferArtifactTypeFromPath(filePath, { rootDir: cwd });
+  if (!type) return null;
+
+  const errors = [
+    ...lintDocStructure(filePath, type),
+    ...lintDocVisuals(filePath, type),
+  ];
+  if (errors.length === 0) return null;
+
+  return { type, rel, errors };
+}
+
+export function formatArtifactGateNotice({ type, rel, errors }) {
+  const lines = [
+    `\nartifact-release-gate (${type}): ${errors.length} structure/visual issue(s). `
+    + 'Fix before calling the artifact done; full gate: '
+    + `\`construct artifact validate ${rel} --type=${type}\`\n`,
+  ];
+  for (const e of errors) lines.push(`  - ${e}\n`);
+  return lines.join('');
+}

package/lib/artifact-manifest.mjs

@@ -0,0 +1,258 @@
+/**
+ * lib/artifact-manifest.mjs — Load and resolve the artifact capability manifest.
+ *
+ * specialists/artifact-manifest.json is the single source of truth for document
+ * type metadata: templates, tone, structure, visuals, and release gates.
+ * Consumer projects without a local copy resolve the shipped manifest from the
+ * Construct package root.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const PACKAGE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const EMPTY_MANIFEST = { version: 1, artifacts: {} };
+
+// Kept here, next to the manifest resolver, so every public workflow surface
+// uses one answer for what can carry Construct styling. Source formats remain
+// deliberately plain unless a caller explicitly asks otherwise.
+export const BRAND_CAPABLE_FORMATS = Object.freeze(['pdf', 'docx', 'doc', 'deck', 'pptx', 'html', 'rtf', 'odt', 'epub', 'tex']);
+export const PLAIN_OUTPUT_FORMATS = Object.freeze(['txt', 'md', 'mdx']);
+
+let cached = null;
+let cachedRoot = null;
+
+function manifestPathForRoot(root) {
+  return path.join(root, 'specialists', 'artifact-manifest.json');
+}
+
+export function findConstructRoot(startPath = process.cwd()) {
+  let current = path.resolve(startPath);
+  while (true) {
+    const manifest = manifestPathForRoot(current);
+    if (fs.existsSync(manifest)) return current;
+    const parent = path.dirname(current);
+    if (parent === current) break;
+    current = parent;
+  }
+  if (fs.existsSync(manifestPathForRoot(PACKAGE_ROOT))) return PACKAGE_ROOT;
+  return null;
+}
+
+export function loadArtifactManifest({ rootDir, force = false, cwd = process.cwd() } = {}) {
+  const resolvedRoot = rootDir ?? findConstructRoot(cwd) ?? PACKAGE_ROOT;
+  if (cached && !force && cachedRoot === resolvedRoot) return cached;
+
+  const p = manifestPathForRoot(resolvedRoot);
+  if (!fs.existsSync(p)) {
+    cached = EMPTY_MANIFEST;
+    cachedRoot = resolvedRoot;
+    return cached;
+  }
+
+  cached = JSON.parse(fs.readFileSync(p, 'utf8'));
+  cachedRoot = resolvedRoot;
+  return cached;
+}
+
+export function getArtifactEntry(type, opts = {}) {
+  const manifest = loadArtifactManifest(opts);
+  return manifest.artifacts?.[type] ?? null;
+}
+
+export function artifactTypes(opts = {}) {
+  const manifest = loadArtifactManifest(opts);
+  return Object.keys(manifest.artifacts ?? {});
+}
+
+function isObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function mergeObjects(...values) {
+  const out = {};
+  for (const value of values) {
+    if (!isObject(value)) continue;
+    for (const [key, next] of Object.entries(value)) {
+      out[key] = isObject(next) && isObject(out[key]) ? mergeObjects(out[key], next) : structuredClone(next);
+    }
+  }
+  return out;
+}
+
+function unique(items) {
+  return [...new Set(items.filter(Boolean))];
+}
+
+/**
+ * Resolve a user-facing type or registered alias. The result intentionally
+ * distinguishes an unknown request from a fallback: callers must ask for
+ * classification/registration instead of silently turning it into a PRD.
+ */
+export function resolveArtifactType(type, opts = {}) {
+  const requestedType = String(type ?? '').trim().toLowerCase();
+  const manifest = loadArtifactManifest(opts);
+  if (!requestedType) {
+    return {
+      status: 'unrecognized',
+      requestedType: null,
+      type: null,
+      guidance: 'Specify a registered document class or register one in specialists/artifact-manifest.json.',
+    };
+  }
+  for (const [registeredType, entry] of Object.entries(manifest.artifacts ?? {})) {
+    const aliases = [registeredType, ...(entry.aliases ?? [])].map((value) => String(value).toLowerCase());
+    if (aliases.includes(requestedType)) {
+      return { status: 'registered', requestedType, type: registeredType, entry };
+    }
+  }
+  return {
+    status: 'unrecognized',
+    requestedType,
+    type: null,
+    guidance: `Document class '${requestedType}' is not registered. Classify the request or add it to specialists/artifact-manifest.json.`,
+  };
+}
+
+/**
+ * Resolve the canonical workflow contract for a registered document class.
+ * Precedence is deliberately explicit: invocation > project config > manifest
+ * defaults. Existing entries remain compatible: primaryOwners and releaseGate
+ * are the fallback author and reviewer/validation declarations.
+ */
+export function resolveArtifactWorkflowContract(type, {
+  rootDir,
+  cwd = process.cwd(),
+  projectConfig = null,
+  overrides = null,
+} = {}) {
+  const resolved = resolveArtifactType(type, { rootDir, cwd });
+  if (resolved.status !== 'registered') return resolved;
+
+  const manifest = loadArtifactManifest({ rootDir, cwd });
+  const entry = resolved.entry;
+  const config = projectConfig?.artifactWorkflow ?? {};
+  const manifestDefaults = manifest.workflowDefaults ?? {};
+  const projectType = config.types?.[resolved.type] ?? {};
+  const appliedOverrides = [];
+  if (isObject(config.defaults) && Object.keys(config.defaults).length) appliedOverrides.push('project.defaults');
+  if (isObject(projectType) && Object.keys(projectType).length) appliedOverrides.push(`project.types.${resolved.type}`);
+  if (isObject(overrides) && Object.keys(overrides).length) appliedOverrides.push('invocation');
+
+  const configured = mergeObjects(manifestDefaults, entry, config.defaults, projectType, overrides);
+  const releaseGate = configured.releaseGate ?? {};
+  const authorChain = unique(configured.authorChain ?? configured.primaryOwners ?? []);
+  const reviewerChain = unique(configured.reviewerChain ?? [
+    ...(releaseGate.requiredReviewers ?? []),
+    ...(releaseGate.optionalReviewers ?? []),
+  ]);
+  const outputs = mergeObjects({
+    formats: [...BRAND_CAPABLE_FORMATS, ...PLAIN_OUTPUT_FORMATS],
+    branding: 'construct',
+  }, configured.outputs);
+  const validation = mergeObjects({ releaseGate: true }, configured.validation);
+
+  return {
+    status: 'registered',
+    requestedType: resolved.requestedType,
+    type: resolved.type,
+    documentClass: configured.documentClass ?? resolved.type,
+    template: configured.template ?? null,
+    workflowSkill: configured.workflowSkill ?? null,
+    authorChain,
+    reviewerChain,
+    requiredReviewers: unique(releaseGate.requiredReviewers ?? []),
+    optionalReviewers: unique(releaseGate.optionalReviewers ?? []),
+    researchProfile: configured.researchProfile ?? null,
+    validation,
+    releaseGate,
+    outputs,
+    appliedOverrides,
+  };
+}
+
+/** A dependency-free validator used by startup checks and tests. */
+export function validateArtifactManifest(manifest) {
+  const errors = [];
+  if (!isObject(manifest)) return { valid: false, errors: ['root: must be an object'] };
+  if (!Number.isInteger(manifest.version) || manifest.version < 1) errors.push('version: must be an integer >= 1');
+  if (!isObject(manifest.artifacts)) errors.push('artifacts: must be an object');
+  for (const [type, entry] of Object.entries(manifest.artifacts ?? {})) {
+    const prefix = `artifacts.${type}`;
+    if (!isObject(entry)) { errors.push(`${prefix}: must be an object`); continue; }
+    if (typeof entry.template !== 'string' || !entry.template) errors.push(`${prefix}.template: required string missing`);
+    if (!Array.isArray(entry.primaryOwners) || entry.primaryOwners.some((owner) => typeof owner !== 'string')) {
+      errors.push(`${prefix}.primaryOwners: required string array missing`);
+    }
+    for (const field of ['authorChain', 'reviewerChain', 'aliases']) {
+      if (entry[field] !== undefined && (!Array.isArray(entry[field]) || entry[field].some((value) => typeof value !== 'string'))) {
+        errors.push(`${prefix}.${field}: must be an array of strings`);
+      }
+    }
+    if (entry.outputs?.formats !== undefined && (!Array.isArray(entry.outputs.formats) || entry.outputs.formats.length === 0)) {
+      errors.push(`${prefix}.outputs.formats: must be a non-empty array`);
+    }
+    if (entry.outputs?.branding !== undefined && !['construct', 'plain'].includes(entry.outputs.branding)) {
+      errors.push(`${prefix}.outputs.branding: must be construct or plain`);
+    }
+  }
+  return errors.length ? { valid: false, errors } : { valid: true, errors: [] };
+}
+
+export function structureRequirementsFromManifest(opts = {}) {
+  const manifest = loadArtifactManifest(opts);
+  const out = {};
+  for (const [type, entry] of Object.entries(manifest.artifacts ?? {})) {
+    if (entry.structureRequirements?.length) out[type] = entry.structureRequirements;
+  }
+  return out;
+}
+
+export function visualRequirementsFromManifest(opts = {}) {
+  const manifest = loadArtifactManifest(opts);
+  const out = {};
+  for (const [type, entry] of Object.entries(manifest.artifacts ?? {})) {
+    if (entry.visualRequirements?.length) out[type] = entry.visualRequirements;
+  }
+  return out;
+}
+
+export function loadBrandVoice(cwd = process.cwd()) {
+  const p = path.join(cwd, '.cx', 'brand-voice.json');
+  if (!fs.existsSync(p)) return null;
+  try {
+    return JSON.parse(fs.readFileSync(p, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+export function resolveToneForArtifact(type, { cwd = process.cwd(), rootDir } = {}) {
+  const entry = getArtifactEntry(type, { rootDir, cwd });
+  const brand = loadBrandVoice(cwd);
+  const override = brand?.toneOverride?.[type];
+  if (override) return override;
+  return entry?.toneDefault ?? 'direct';
+}
+
+export function templateMetadata(type, { cwd = process.cwd(), rootDir } = {}) {
+  const workflow = resolveArtifactWorkflowContract(type, { rootDir, cwd });
+  if (workflow.status !== 'registered') return null;
+  const entry = getArtifactEntry(workflow.type, { rootDir, cwd });
+  return {
+    type: workflow.type,
+    documentClass: workflow.documentClass,
+    tone: resolveToneForArtifact(workflow.type, { cwd, rootDir }),
+    toneAllowed: entry.toneAllowed ?? [],
+    structureRequirements: entry.structureRequirements ?? [],
+    visualRequirements: entry.visualRequirements ?? [],
+    primaryOwners: entry.primaryOwners ?? [],
+    workflowSkill: entry.workflowSkill ?? null,
+    releaseGate: entry.releaseGate ?? null,
+    authorChain: workflow.authorChain,
+    reviewerChain: workflow.reviewerChain,
+    validation: workflow.validation,
+    outputs: workflow.outputs,
+  };
+}