@geraldmaron/construct 1.2.0 → 1.2.1

package/README.md

@@ -148,7 +148,7 @@ The embed daemon writes its supervisor stdout log to `~/.cx/runtime/embed-daemon
 
 | Command | What it does |
 |---|---|
-| `construct artifact` | Validate typed document artifacts against the release gate |
+| `construct artifact` | Plan or locally execute manifest-backed artifact workflows with execution provenance |
 | `construct ask` | One-shot ask against the active knowledge index |
 | `construct bootstrap` | Import seed observation corpus into local memory store for cold-start acceleration |
 | `construct customer` | Manage customer profiles for product intelligence |
@@ -257,6 +257,7 @@ The embed daemon writes its supervisor stdout log to `~/.cx/runtime/embed-daemon
 | `construct roles:set` | Activate a role contract |
 | `construct scheduler` | Manage scheduled background jobs (tag-mining, doc-hygiene, skill-rollup) |
 | `construct skills` | Skill relevance detection |
+| `construct sources` | Manage typed integration source targets in construct.config.json |
 | `construct uninstall` | Remove Construct state |
 | `construct update` | Reinstall this checkout |
 | `construct upgrade` | Upgrade to latest npm version |

package/bin/construct

@@ -500,15 +500,19 @@ async function cmdDoctor() {
 
   const checks = [];
   const add = (label, pass, optional = false) => checks.push({ label, pass, optional });
+  const { isConstructSourceCheckout } = await import('../lib/doctor/source-checkout.mjs');
+  const isSourceCheckout = isConstructSourceCheckout(ROOT_DIR);
   add('registry.json exists', fs.existsSync(path.join(ROOT_DIR, 'specialists', 'registry.json')));
   add('sync-specialists.mjs exists', fs.existsSync(path.join(ROOT_DIR, 'scripts', 'sync-specialists.mjs')));
 
-  // Dashboard static build output. The Next.js app under apps/dashboard
-  // emits a static export into lib/server/static/ via its postbuild script;
-  // an empty static dir means lib/server/index.mjs will serve 404s.
+  // Dashboard static build output is absent from published npm installs.
 
-  const dashboardIndex = path.join(ROOT_DIR, 'lib', 'server', 'static', 'index.html');
-  add('Dashboard built (lib/server/static/index.html)', fs.existsSync(dashboardIndex));
+  if (isSourceCheckout) {
+    const dashboardIndex = path.join(ROOT_DIR, 'lib', 'server', 'static', 'index.html');
+    add('Dashboard built (lib/server/static/index.html)', fs.existsSync(dashboardIndex));
+  } else {
+    add('Dashboard built (skipped — published package)', true, true);
+  }
 
   // Project .gitignore must cover .cx/. Auto-fix via --fix-gitignore.
   // Only checks when cwd looks like a Construct project (has .cx/ or
@@ -858,8 +862,21 @@ async function cmdDoctor() {
     add('Headhunt classifier agents exist in registry', classifierOrphans.length === 0);
     const skillAudit = auditSkills({ rootDir: ROOT_DIR, silent: true });
     add('No declared skills missing on disk', skillAudit.pass, false);
-    const specialistAudit = auditSpecialists({ rootDir: ROOT_DIR, silent: true });
-    add('Specialist/skill audit cross-checks', specialistAudit.pass, false);
+    if (isSourceCheckout) {
+      const specialistAudit = auditSpecialists({ rootDir: ROOT_DIR, silent: true });
+      add('Specialist/skill audit cross-checks', specialistAudit.pass, false);
+
+      // The catalog is the public-service source of truth; doctor joins it to runtime dispatch
+      // and the generated reference so a command that is unroutable or undocumented surfaces here.
+
+      const { buildCliServiceInventory } = await import('../lib/cli-service-inventory.mjs');
+      const cliDrift = buildCliServiceInventory({ rootDir: ROOT_DIR })
+        .filter((entry) => !entry.runnable || !entry.documented);
+      add('Public CLI dispatch/reference parity', cliDrift.length === 0, false);
+    } else {
+      add('Specialist/skill audit cross-checks (skipped — published package)', true, true);
+      add('Public CLI dispatch/reference parity (skipped — published package)', true, true);
+    }
     const { lintResearchRepo } = await import('../lib/research-lint.mjs');
     const researchLintResults = lintResearchRepo({ rootDir: process.cwd() });
     add('Research artifacts meet minimum evidence structure', researchLintResults.every((entry) => entry.errors.length === 0), true);
@@ -1561,17 +1578,18 @@ async function cmdExport(args) {
   const outFlag = args.find((a) => a.startsWith('--output='))?.split('=')[1];
   const detectOnly = args.includes('--detect');
   const figures = !args.includes('--no-figures');
+  const branding = args.includes('--plain') || args.includes('--no-brand') ? 'plain' : 'construct';
 
   const { detect, exportMarkdown, EXPORT_FORMATS } = await import('../lib/document-export.mjs');
 
   if (detectOnly) {
     const format = toFlag || 'pdf';
-    println(JSON.stringify(detect(format), null, 2));
+    println(JSON.stringify(detect(format, process.env, { branding }), null, 2));
     return;
   }
 
   if (!inputPath) {
-    errorln('Usage: construct export <markdown-file> --to=<pdf|docx|html> [--output=<path>] [--figures|--no-figures] [--detect]');
+    errorln('Usage: construct export <markdown-file> --to=<pdf|docx|html> [--output=<path>] [--figures|--no-figures] [--plain] [--detect]');
     process.exit(1);
   }
   if (!toFlag) {
@@ -1586,6 +1604,7 @@ async function cmdExport(args) {
     outputPath: resolvedOut,
     format: toFlag,
     figures: toFlag === 'pdf' ? figures : false,
+    branding,
     repoRoot: ROOT_DIR,
   });
   if (!result.ok) {
@@ -2837,12 +2856,25 @@ async function cmdIntakeConfig(args) {
   const cwd = process.cwd();
 
   const action = args[0];
+  if (action === 'migrate') {
+    const { migrateLegacyIntakeConfig } = await import('../lib/intake/intake-config.mjs');
+    const result = migrateLegacyIntakeConfig(cwd);
+    if (!result.migrated) {
+      info(result.reason ?? 'nothing to migrate');
+      return;
+    }
+    info('Migrated .cx/intake-config.json → construct.config.json intakePolicy');
+    println(JSON.stringify(result.policy, null, 2));
+    return;
+  }
+
   if (!action || action === 'show') {
     const cfg = loadIntakeConfig(cwd, process.env);
     const desc = describeIntakeDepth(cfg.maxDepth);
     println(`Intake config (root: ${cwd})`);
     println('');
     println(`  includeProjectInbox: ${cfg.includeProjectInbox ? 'on' : 'off'} (.cx/inbox)`);
+    println(`  includeRootInbox:    ${(cfg.includeRootInbox ?? cfg.includeArchetypeInbox) ? 'on' : 'off'} (inbox/)`);
     println(`  includeDocsIntake:   ${cfg.includeDocsIntake ? 'on' : 'off'} (docs/intake)`);
     println(`  maxDepth:            ${cfg.maxDepth} — ${desc.label}`);
     println(`                       ${desc.detail}`);
@@ -2877,6 +2909,9 @@ async function cmdIntakeConfig(args) {
   const docsFlag = tail.find((a) => a.startsWith('--include-docs-intake='));
   if (docsFlag) patch.includeDocsIntake = /^(on|true|1|yes)$/i.test(docsFlag.split('=')[1] || '');
 
+  const rootFlag = tail.find((a) => a.startsWith('--include-root-inbox='));
+  if (rootFlag) patch.includeRootInbox = /^(on|true|1|yes)$/i.test(rootFlag.split('=')[1] || '');
+
   const addFlags = tail.filter((a) => a.startsWith('--add-dir='));
   const removeFlags = tail.filter((a) => a.startsWith('--remove-dir='));
 
@@ -2903,6 +2938,123 @@ async function cmdIntakeConfig(args) {
   }
 }
 
+async function cmdSources(args) {
+  const {
+    validateSourceTargets,
+    normalizeConfigTarget,
+    resolveEffectiveSourceTargetsFromConfig,
+    legacyEnvSourceTargets,
+    SOURCE_PROVIDERS,
+  } = await import('../lib/config/source-targets.mjs');
+  const {
+    loadProjectConfig,
+    writeProjectConfig,
+    findProjectConfigPath,
+    PROJECT_CONFIG_FILENAME,
+  } = await import('../lib/config/project-config.mjs');
+
+  const cwd = process.cwd();
+  const action = args[0] ?? 'list';
+
+  if (action === 'list' || action === 'show') {
+    const { config, path: cfgPath } = loadProjectConfig(cwd, process.env);
+    const configTargets = (config.sources?.targets ?? []).map(normalizeConfigTarget);
+    const envTargets = legacyEnvSourceTargets(process.env);
+    const effective = resolveEffectiveSourceTargetsFromConfig(config, process.env);
+    println(`Source targets (config: ${cfgPath ?? 'default'})`);
+    println('');
+    if (configTargets.length === 0) println('  (no targets in construct.config.json)');
+    for (const t of configTargets) {
+      println(`  ${t.id} · ${t.provider} · ${JSON.stringify(t.selector)}`);
+    }
+    if (envTargets.length) {
+      println('');
+      println('Legacy env targets (merged at runtime):');
+      for (const t of envTargets) {
+        println(`  ${t.id} · ${t.provenance} · ${t.provider} · ${JSON.stringify(t.selector)}`);
+      }
+    }
+    println('');
+    println(`Effective targets: ${effective.length}`);
+    return;
+  }
+
+  if (action === 'validate') {
+    const loaded = loadProjectConfig(cwd, process.env);
+    const targetErrors = validateSourceTargets(loaded.raw?.sources?.targets ?? loaded.config?.sources?.targets ?? []);
+    const all = [...(loaded.errors ?? []), ...targetErrors];
+    if (!all.length) {
+      info(`${loaded.path ?? PROJECT_CONFIG_FILENAME}: source targets valid`);
+      return;
+    }
+    errorln(`Source target validation failed (${all.length}):`);
+    for (const e of all) errorln(`  - ${e}`);
+    process.exit(1);
+  }
+
+  if (action === 'add') {
+    const provider = args[1];
+    const id = args[2];
+    const selectorRaw = args[3];
+    if (!provider || !id || !selectorRaw) {
+      errorln('Usage: construct sources add <provider> <id> <selector-json>');
+      process.exit(1);
+    }
+    if (!SOURCE_PROVIDERS.includes(provider)) {
+      errorln(`Unknown provider: ${provider}. Expected: ${SOURCE_PROVIDERS.join(', ')}`);
+      process.exit(1);
+    }
+    let selector;
+    try { selector = JSON.parse(selectorRaw); } catch (err) {
+      errorln(`Invalid selector JSON: ${err.message}`);
+      process.exit(1);
+    }
+    const target = normalizeConfigTarget({ id, provider, selector });
+    const targetErrors = validateSourceTargets([target]);
+    if (targetErrors.length) {
+      for (const e of targetErrors) errorln(`  - ${e}`);
+      process.exit(1);
+    }
+    const cfgPath = findProjectConfigPath(cwd) || path.join(cwd, PROJECT_CONFIG_FILENAME);
+    const { config } = loadProjectConfig(cwd, process.env);
+    const existing = config.sources?.targets ?? [];
+    if (existing.some((t) => t.id === id)) {
+      errorln(`Target id already exists: ${id}`);
+      process.exit(1);
+    }
+    const next = {
+      ...config,
+      sources: { ...(config.sources ?? {}), targets: [...existing, target] },
+    };
+    writeProjectConfig(cfgPath, next);
+    info(`added source target ${id}`);
+    return;
+  }
+
+  if (action === 'remove') {
+    const id = args[1];
+    if (!id) {
+      errorln('Usage: construct sources remove <id>');
+      process.exit(1);
+    }
+    const cfgPath = findProjectConfigPath(cwd) || path.join(cwd, PROJECT_CONFIG_FILENAME);
+    const { config } = loadProjectConfig(cwd, process.env);
+    const existing = config.sources?.targets ?? [];
+    const nextTargets = existing.filter((t) => t.id !== id);
+    if (nextTargets.length === existing.length) {
+      errorln(`No target with id: ${id}`);
+      process.exit(1);
+    }
+    const next = { ...config, sources: { ...(config.sources ?? {}), targets: nextTargets } };
+    writeProjectConfig(cfgPath, next);
+    info(`removed source target ${id}`);
+    return;
+  }
+
+  errorln(`Unknown sources action: ${action}. Available: list, add, remove, validate`);
+  process.exit(1);
+}
+
 async function cmdIntakeMetrics() {
   try {
     const { computeIntakeMetrics, pendingAge } = await import('../lib/embed/intake-metrics.mjs');
@@ -5400,6 +5552,7 @@ const handlers = new Map([
   ['status', cmdStatus],
   ['install', cmdInstall],
   ['config', cmdConfig],
+  ['sources', cmdSources],
   ['intake', cmdIntake],
   ['recommendations', cmdRecommendations],
   ['integrations', cmdIntegrations],
@@ -5648,7 +5801,24 @@ const handlers = new Map([
   ['artifact', async (args) => {
     const sub = args[0];
     if (sub === 'validate') return runArtifactValidateCli(args.slice(1));
-    errorln(`Unknown artifact subcommand: ${sub || '(none)'}. Available: validate`);
+    if (sub === 'workflow') {
+      const rest = args.slice(1);
+      const request = rest.filter((arg) => !arg.startsWith('--')).join(' ');
+      const read = (name) => rest.find((arg) => arg.startsWith(`${name}=`))?.slice(name.length + 1);
+      const { runArtifactWorkflow } = await import('../lib/artifact-workflow.mjs');
+      const result = runArtifactWorkflow({
+        input: request,
+        artifactType: read('--type'),
+        filePath: read('--file'),
+        format: read('--to'),
+        outputPath: read('--output'),
+        branding: rest.includes('--plain') ? 'plain' : undefined,
+        approvalMode: rest.includes('--apply') ? 'allow-durable-write' : (read('--approval-mode') || 'proposal-only'),
+      }, { cwd: process.cwd(), rootDir: ROOT_DIR });
+      println(JSON.stringify(result, null, 2));
+      return;
+    }
+    errorln(`Unknown artifact subcommand: ${sub || '(none)'}. Available: validate, workflow`);
     process.exit(1);
   }],
   ['doc', async (args) => {

package/lib/artifact-manifest.mjs

@@ -14,6 +14,12 @@ 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;
 
@@ -60,6 +66,140 @@ export function artifactTypes(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 = {};
@@ -97,16 +237,22 @@ export function resolveToneForArtifact(type, { cwd = process.cwd(), rootDir } =
 }
 
 export function templateMetadata(type, { cwd = process.cwd(), rootDir } = {}) {
-  const entry = getArtifactEntry(type, { rootDir, cwd });
-  if (!entry) return null;
+  const workflow = resolveArtifactWorkflowContract(type, { rootDir, cwd });
+  if (workflow.status !== 'registered') return null;
+  const entry = getArtifactEntry(workflow.type, { rootDir, cwd });
   return {
-    type,
-    tone: resolveToneForArtifact(type, { cwd, rootDir }),
+    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,
   };
 }