@geraldmaron/construct 1.0.0 → 1.0.2

package/lib/codex-config.mjs

@@ -87,7 +87,9 @@ export function buildCodexMcpEntry(id, mcpDef, resolvedValues = {}) {
       tool_timeout_sec: 60,
     };
 
-    if (id !== 'github') {
+    if (id === 'github') {
+      entry.bearer_token_env_var = 'GITHUB_TOKEN';
+    } else {
       const authorization = mcpDef.headers?.Authorization;
       const match = typeof authorization === 'string' ? authorization.match(/^Bearer __([A-Z0-9_]+)__$/) : null;
       if (match) entry.bearer_token_env_var = match[1];

package/lib/comment-lint.mjs

@@ -35,8 +35,13 @@ function relPath(rootDir, absPath) {
 
 function requiresHeader(rel) {
   const ext = path.extname(rel);
+  if (['.yaml', '.yml', '.json', '.jsonl', '.toml'].includes(ext)) return { required: false, type: null };
   const jsMatch = JS_HEADER_GLOBS.some(r => r.test(rel));
   const mdMatch = MD_HEADER_GLOBS.some(r => r.test(rel));
+  // Exclude static assets under lib/server/static from requiring headers
+  if (rel.startsWith('lib/server/static/')) {
+    return { required: false, type: null };
+  }
   const type = (jsMatch && ext !== '.html') ? 'js' : (jsMatch || mdMatch) ? 'md' : null;
   return { required: jsMatch || mdMatch, type };
 }
@@ -54,22 +59,66 @@ function hasHeader(content, type) {
 }
 
 // --- banned comment patterns ---
+//
+// Comment-line prefix matches both `//` line comments and JSDoc body lines
+// (those start with optional whitespace + `*`). The leading `^\s*\*(?!\/)`
+// keeps it from matching `*/` block-end lines or arithmetic.
+
+const CMT = '(?:\\/\\/|^\\s*\\*(?!\\/))';
 
 const BANNED = [
-  { pattern: /\/\/.*\b(?:added for|added recently|recently added|just added|new:)\b/i, label: 'point-in-time: "added for / recently / just / new:"' },
-  { pattern: /\/\/.*\b(?:used by|called from|only consumer)\b/i, label: 'caller reference: "used by / called from"' },
-  { pattern: /\/\/.*\bpreviously\b.*\bwe used to\b/i, label: 'point-in-time: "previously / we used to"' },
-  { pattern: /\/\/.*(?:#\d{3,}|GH-\d+|JIRA-\d+|closes #|fixes #|ticket )/i, label: 'issue/PR reference in source comment (put in commit message instead)' },
+  // point-in-time
+  { pattern: new RegExp(`${CMT}.*\\b(?:added for|added recently|recently added|just added|new:)\\b`, 'i'), label: 'point-in-time: "added for / recently / just / new:"' },
+  { pattern: new RegExp(`${CMT}.*\\b(?:previously|no longer|used to|was replaced|replaced by)\\b`, 'i'), label: 'point-in-time: history belongs in git log, not source' },
+  { pattern: new RegExp(`${CMT}.*\\b(?:replaces the (?:old|previous|prior)|consolidates what was|instead of (?:only|the|a) (?:old|prior|previous))\\b`, 'i'), label: 'comparative narrative: describe what the code does, not what it used to do' },
+  { pattern: new RegExp(`${CMT}.*\\b(?:the (?:new|current) (?:path|approach|impl|implementation|design) (?:uses|writes|reads|does|fires|spins))\\b`, 'i'), label: 'comparative narrative: "the new X uses/does Y" — describe the design directly' },
+  { pattern: new RegExp(`${CMT}.*(?:#\\d{3,}|GH-\\d+|JIRA-\\d+|closes #|fixes #|ticket )`, 'i'), label: 'issue/PR reference in source comment (put in commit message instead)' },
+  // narrative voice
+  { pattern: new RegExp(`${CMT}\\s+(?:We |This |It |Now )\\w`, 'i'), label: 'narrative voice: avoid "We/This/It/Now" — describe the constraint, not the story' },
+  // noise sentinels
+  { pattern: new RegExp(`${CMT}\\s*(?:ok|OK|skip|Skip|best effort)\\s*$`, 'i'), label: 'noise sentinel: "ok / skip / best effort" carries no decision content' },
+  // caller references
+  { pattern: new RegExp(`${CMT}.*\\b(?:used by|called from|only consumer)\\b`, 'i'), label: 'caller reference: "used by / called from"' },
+  // step markers — only flag in `//` comments. Ordered lists are
+  // conventional inside JSDoc decision-tree and flow documentation.
+  { pattern: /\/\/\s+\d+\.\s+\w/, label: 'step marker: use function names or block structure instead of "// 1. Step"' },
+  // markdown equivalents
   { pattern: /<!--.*\b(?:added for|added recently|just added|new:)\b.*-->/i, label: 'point-in-time in markdown comment' },
   { pattern: /<!--.*\b(?:used by|called from|only consumer)\b.*-->/i, label: 'caller reference in markdown comment' },
-  { pattern: /\/\/\s*TODO(?:\((\w+)\))?:?(?!\s*\(\w+\):)/i, label: 'TODO without owner — use: TODO(owner): what and why' },
+  // TODO without owner
+  { pattern: new RegExp(`${CMT}\\s*TODO(?:\\((\\w+)\\))?:?(?!\\s*\\(\\w+\\):)`, 'i'), label: 'TODO without owner — use: TODO(owner): what and why' }, // construct-lint-ignore
+];
+
+// Files whose content is authored precisely to demonstrate banned patterns
+// (the linter itself, the canonical rule file, test fixtures that feed the
+// linter banned strings, and teaching docs that show patterns to avoid).
+// Linting them would flag the demonstrations as violations.
+const BANNED_CHECK_SKIP = [
+  'lib/comment-lint.mjs',
+  'rules/common/comments.md',
+  'tests/comment-lint.test.mjs',
+  'commands/work/clean.md',
+  'skills/utility/clean-code.md',
 ];
 
+function isBannedCheckSkipped(filePath) {
+  if (!filePath) return false;
+  return BANNED_CHECK_SKIP.some((suffix) => filePath.endsWith(suffix));
+}
+
 function checkBanned(content, filePath) {
-  if (filePath && (filePath.endsWith('comment-lint.mjs') || filePath.endsWith('comments.md'))) return [];
+  if (isBannedCheckSkipped(filePath)) return [];
+
+  // Banned patterns are JS/TS comment conventions — they don't apply to markdown prose.
+  if (filePath && path.extname(filePath) === '.md') return [];
+
   const warnings = [];
   const lines = content.split('\n');
   for (let i = 0; i < lines.length; i++) {
+    // Per-line escape hatch for the rare legitimate case — a section label
+    // describing the pattern it detects, e.g. "// TODO/FIXME/HACK comments"
+    // in a detector. Marker must appear on the same line.
+    if (lines[i].includes('construct-lint-ignore')) continue;
     for (const { pattern, label } of BANNED) {
       if (pattern.test(lines[i])) {
         warnings.push({ line: i + 1, label });

package/lib/completions.mjs

@@ -1,7 +1,7 @@
 /**
  * completions.mjs — generates bash and zsh completion scripts for construct.
  *
- * Called by sync-agents.mjs after each sync.
+ * Called by scripts/sync-agents.mjs after each sync.
  * Outputs to a platform-appropriate per-user completions directory.
  */
 
@@ -14,13 +14,22 @@ const COMPLETIONS_DIR = process.platform === 'win32'
   ? join(process.env.APPDATA ?? join(homedir(), 'AppData', 'Roaming'), 'construct', 'completions')
   : join(homedir(), '.local', 'share', 'construct', 'completions');
 
+function subcommandName(subcommand) {
+  return typeof subcommand === 'string' ? subcommand : subcommand.name;
+}
+
+function subcommandDesc(subcommand) {
+  if (typeof subcommand === 'string') return '';
+  return subcommand.desc || '';
+}
+
 function buildBash() {
   const names = CLI_COMMANDS.map(c => c.name).join(' ');
 
   const subcommandCases = CLI_COMMANDS
     .filter(c => c.subcommands?.length)
     .map(c => {
-      const subs = c.subcommands.map(s => s.name).join(' ');
+      const subs = c.subcommands.map(subcommandName).filter(Boolean).join(' ');
       return `        ${c.name}) COMPREPLY=($(compgen -W "${subs}" -- "$cur")) ;;`;
     })
     .join('\n');
@@ -86,21 +95,21 @@ complete -F _construct_completions construct
 
 function buildZsh() {
   const commandDescriptions = CLI_COMMANDS
-    .map(c => `    '${c.name}:${c.emoji} ${c.description.replace(/'/g, "\\'")}' \\`)
+    .map(c => `    '${c.name}:${c.emoji || ''} ${(c.description || '').replace(/'/g, "\\'")}' \\`)
     .join('\n');
 
   const subcommandFunctions = CLI_COMMANDS
     .filter(c => c.subcommands?.length)
     .map(c => {
       const subs = c.subcommands
-        .map(s => `      '${s.name}:${s.desc.replace(/'/g, "\\'")}'`)
+        .map(s => `      '${(subcommandName(s) || '')}:${subcommandDesc(s).replace(/'/g, "\\'")}'`)
         .join('\n');
-      return `_construct_${c.name.replace(/-/g, '_')}() {
+      return `_construct_${(c.name || '').replace(/-/g, '_')}() {
   local subcmds
   subcmds=(
 ${subs}
   )
-  _describe -t subcommands '${c.name} subcommand' subcmds
+  _describe -t subcommands '${c.name}' subcmds
 }`;
     })
     .join('\n\n');
@@ -153,6 +162,12 @@ _construct
 `;
 }
 
+export function getCompletionScript(shell) {
+  if (shell === 'bash') return buildBash();
+  if (shell === 'zsh') return buildZsh();
+  throw new Error(`Unsupported shell: ${shell}`);
+}
+
 export function generateCompletions() {
   try {
     mkdirSync(COMPLETIONS_DIR, { recursive: true });

package/lib/config/alias.mjs

@@ -0,0 +1,56 @@
+/**
+ * lib/config/alias.mjs — resolves the user-facing Construct alias.
+ *
+ * Lookup precedence:
+ *   1. CONSTRUCT_ALIAS env var (per-session override)
+ *   2. ~/.construct/config.json.aliasOverride (user-level, lets each
+ *      user on the same project see their own branding without
+ *      committing it)
+ *   3. construct.config.json.alias (project-level, committed)
+ *   4. "Construct" (the default)
+ *
+ * Pure resolution — no fs writes. The alias flows to the dashboard
+ * wordmark (via /api/alias), persona prompts ({{alias}} template at
+ * sync time), and CLI banner output.
+ */
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { loadProjectConfig } from './project-config.mjs';
+
+export const DEFAULT_ALIAS = 'Construct';
+export const ALIAS_ENV_KEY = 'CONSTRUCT_ALIAS';
+export const ALIAS_TEMPLATE_TOKEN = /\{\{alias\}\}/g;
+
+export function resolveAlias({ cwd = process.cwd(), env = process.env, homeDir = os.homedir() } = {}) {
+  const envAlias = env?.[ALIAS_ENV_KEY];
+  if (typeof envAlias === 'string' && envAlias.trim()) {
+    return { value: envAlias.trim(), source: 'env' };
+  }
+
+  try {
+    const userCfgPath = path.join(homeDir, '.construct', 'config.json');
+    if (fs.existsSync(userCfgPath)) {
+      const userCfg = JSON.parse(fs.readFileSync(userCfgPath, 'utf8'));
+      const userAlias = userCfg?.aliasOverride;
+      if (typeof userAlias === 'string' && userAlias.trim()) {
+        return { value: userAlias.trim(), source: 'user' };
+      }
+    }
+  } catch { /* user file is best-effort */ }
+
+  try {
+    const { config, source } = loadProjectConfig(cwd, env);
+    if (source === 'file' && typeof config?.alias === 'string' && config.alias.trim()) {
+      return { value: config.alias.trim(), source: 'project' };
+    }
+  } catch { /* project config is best-effort */ }
+
+  return { value: DEFAULT_ALIAS, source: 'default' };
+}
+
+export function applyAliasToTemplate(text, alias) {
+  if (typeof text !== 'string') return text;
+  const safe = String(alias ?? DEFAULT_ALIAS).trim() || DEFAULT_ALIAS;
+  return text.replace(ALIAS_TEMPLATE_TOKEN, safe);
+}

package/lib/config/project-config.mjs

@@ -0,0 +1,335 @@
+/**
+ * lib/config/project-config.mjs — read and write construct.config.json.
+ *
+ * Source-of-truth loader for project-level Construct settings. Resolves
+ * the path by walking up from cwd (stops at git root or filesystem root),
+ * validates against the v1 schema, and applies secret interpolation:
+ * any string value of the form `$VAR_NAME` is replaced with the
+ * corresponding env-var value at load time. Pointers keep API keys in
+ * `.env` where they belong; the JSON config never sees a secret literal.
+ *
+ * Precedence rule for consumers: env var if set > config.json > default.
+ * `resolveSetting(config, jsonPath, env, envKey, default)` encodes it
+ * once so call sites stay consistent.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { CONFIG_SCHEMA_VERSION, DEFAULT_PROJECT_CONFIG, validateProjectConfig, FIELD_RULES } from './schema.mjs';
+
+export const PROJECT_CONFIG_FILENAME = 'construct.config.json';
+
+export function findProjectConfigPath(cwd = process.cwd()) {
+  let dir = path.resolve(cwd);
+  const root = path.parse(dir).root;
+  while (dir !== root) {
+    const candidate = path.join(dir, PROJECT_CONFIG_FILENAME);
+    if (fs.existsSync(candidate)) return candidate;
+    if (fs.existsSync(path.join(dir, '.git'))) {
+      const inGitRoot = path.join(dir, PROJECT_CONFIG_FILENAME);
+      return fs.existsSync(inGitRoot) ? inGitRoot : null;
+    }
+    dir = path.dirname(dir);
+  }
+  return null;
+}
+
+const ENV_POINTER_RE = /^\$([A-Z_][A-Z0-9_]*)$/;
+
+export function interpolateSecrets(value, env = process.env) {
+  if (typeof value === 'string') {
+    const match = value.match(ENV_POINTER_RE);
+    if (!match) return value;
+    const resolved = env[match[1]];
+    return resolved === undefined ? null : resolved;
+  }
+  if (Array.isArray(value)) return value.map((v) => interpolateSecrets(v, env));
+  if (value !== null && typeof value === 'object') {
+    const out = {};
+    for (const [k, v] of Object.entries(value)) out[k] = interpolateSecrets(v, env);
+    return out;
+  }
+  return value;
+}
+
+function deepMerge(base, override) {
+  if (override === undefined) return base;
+  if (override === null || typeof override !== 'object' || Array.isArray(override)) return override;
+  const out = Array.isArray(base) ? [...(base || [])] : { ...(base || {}) };
+  for (const [k, v] of Object.entries(override)) {
+    out[k] = deepMerge(base?.[k], v);
+  }
+  return out;
+}
+
+export function loadProjectConfig(cwd = process.cwd(), env = process.env) {
+  const configPath = findProjectConfigPath(cwd);
+  if (!configPath) {
+    return {
+      path: null,
+      raw: null,
+      config: structuredClone(DEFAULT_PROJECT_CONFIG),
+      source: 'default',
+      errors: [],
+    };
+  }
+  let raw;
+  try {
+    raw = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+  } catch (err) {
+    return {
+      path: configPath,
+      raw: null,
+      config: structuredClone(DEFAULT_PROJECT_CONFIG),
+      source: 'invalid',
+      errors: [`failed to parse ${configPath}: ${err.message}`],
+    };
+  }
+  const validation = validateProjectConfig(raw);
+  if (!validation.valid) {
+    return {
+      path: configPath,
+      raw,
+      config: structuredClone(DEFAULT_PROJECT_CONFIG),
+      source: 'invalid',
+      errors: validation.errors,
+    };
+  }
+  const merged = deepMerge(structuredClone(DEFAULT_PROJECT_CONFIG), raw);
+  const resolved = interpolateSecrets(merged, env);
+  return {
+    path: configPath,
+    raw,
+    config: resolved,
+    source: 'file',
+    errors: [],
+  };
+}
+
+export function writeProjectConfig(filePath, config, options = {}) {
+  const { 
+    validate = true,           // Perform validation before write
+    interactive = false,       // Prompt for fixes in interactive mode
+    dryRun = false,           // Validate only, don't write
+    strict = false,           // Reject unknown fields
+  } = options;
+  
+  // Pre-validation: Check for common mistakes
+  const preErrors = [];
+  const warnings = [];
+  
+  // Check 1: Version mismatch
+  if (config.version && config.version !== CONFIG_SCHEMA_VERSION) {
+    preErrors.push(`version mismatch: file has v${config.version}, expected v${CONFIG_SCHEMA_VERSION}`);
+  }
+  
+  // Check 2: Unknown top-level fields (warning in non-strict mode)
+  if (typeof config === 'object' && config !== null) {
+    const knownFields = Object.keys(FIELD_RULES);
+    const unknownFields = Object.keys(config).filter(k => !knownFields.includes(k));
+    if (unknownFields.length > 0) {
+      const msg = `unknown fields will be ignored: ${unknownFields.join(', ')}`;
+      if (strict) {
+        preErrors.push(msg);
+      } else {
+        warnings.push(msg);
+      }
+    }
+  }
+  
+  // Check 3: Secret literals (security warning)
+  const secretPattern = /(api[_-]?key|token|secret|password)/i;
+  function findSecretLiterals(obj, path = '') {
+    const found = [];
+    for (const [key, value] of Object.entries(obj)) {
+      const currentPath = path ? `${path}.${key}` : key;
+      if (secretPattern.test(key) && typeof value === 'string' && !value.startsWith('$')) {
+        found.push(currentPath);
+      }
+      if (typeof value === 'object' && value !== null) {
+        found.push(...findSecretLiterals(value, currentPath));
+      }
+    }
+    return found;
+  }
+  
+  const secretPaths = findSecretLiterals(config);
+  if (secretPaths.length > 0) {
+    warnings.push(`potential secrets detected at: ${secretPaths.join(', ')}. Use "$ENV_VAR" syntax instead.`);
+  }
+  
+  // Run full schema validation
+  let validation = { valid: true, errors: [] };
+  if (validate) {
+    validation = validateProjectConfig(config);
+  }
+  
+  // Combine all errors (handle case where validation.errors is undefined)
+  const validationErrors = validation.errors || [];
+  const allErrors = [...preErrors, ...validationErrors];
+  
+  // Build comprehensive feedback
+  const feedback = {
+    valid: allErrors.length === 0,
+    errors: allErrors,
+    warnings,
+    filePath,
+    wouldWrite: !dryRun && allErrors.length === 0,
+  };
+  
+  // Throw on validation errors
+  if (allErrors.length > 0) {
+    const errorMessage = formatValidationErrors(allErrors, warnings, filePath);
+    throw new Error(errorMessage);
+  }
+  
+  // Log warnings
+  if (warnings.length > 0 && !options.silent) {
+    console.error('Config warnings:');
+    warnings.forEach(w => console.error(`  ⚠ ${w}`));
+  }
+  
+  // Perform dry-run or actual write
+  if (dryRun) {
+    feedback.written = false;
+    return feedback;
+  }
+  
+  // Write the file
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, `${JSON.stringify(config, null, 2)}\n`);
+  
+  feedback.written = true;
+  return feedback;
+}
+
+function formatValidationErrors(errors, warnings, filePath) {
+  let msg = `refusing to write invalid config: ${errors.join('; ')}`;
+  msg += `\n\nInvalid config (${filePath}):\n\n`;
+  
+  msg += 'Errors:\n';
+  errors.forEach(e => {
+    msg += `  ✗ ${e}\n`;
+  });
+  
+  if (warnings.length > 0) {
+    msg += '\nWarnings:\n';
+    warnings.forEach(w => {
+      msg += `  ⚠ ${w}\n`;
+    });
+  }
+  
+  msg += '\nFix these issues before the config can be saved.';
+  msg += '\nRun with --dry-run to validate without writing.';
+  
+  return msg;
+}
+
+export function initProjectConfig(cwd = process.cwd(), overrides = {}) {
+  const filePath = path.join(cwd, PROJECT_CONFIG_FILENAME);
+  if (fs.existsSync(filePath)) {
+    throw new Error(`${PROJECT_CONFIG_FILENAME} already exists at ${filePath}`);
+  }
+  const config = deepMerge(structuredClone(DEFAULT_PROJECT_CONFIG), { version: CONFIG_SCHEMA_VERSION, ...overrides });
+  writeProjectConfig(filePath, config);
+  return filePath;
+}
+
+export function getConfigValue(config, keyPath, defaultValue) {
+  if (!keyPath) return config;
+  const parts = keyPath.split('.');
+  let cur = config;
+  for (const part of parts) {
+    if (cur === null || typeof cur !== 'object') return defaultValue;
+    cur = cur[part];
+  }
+  return cur === undefined ? defaultValue : cur;
+}
+
+export function setConfigValue(config, keyPath, value) {
+  if (!keyPath) throw new Error('keyPath required');
+  const parts = keyPath.split('.');
+  const out = structuredClone(config);
+  let cur = out;
+  for (let i = 0; i < parts.length - 1; i++) {
+    const part = parts[i];
+    if (cur[part] === null || typeof cur[part] !== 'object') cur[part] = {};
+    cur = cur[part];
+  }
+  cur[parts[parts.length - 1]] = value;
+  return out;
+}
+
+/**
+ * Set a config value with immediate validation and feedback.
+ * Recommended way to update configuration from CLI/commands.
+ * 
+ * @param {string} keyPath - Dot-notation path (e.g., 'deployment.mode')
+ * @param {any} value - Value to set
+ * @param {Object} options
+ * @returns {Object} Validation result with immediate feedback
+ */
+export function setConfigValueWithValidation(keyPath, value, options = {}) {
+  const { cwd = process.cwd(), dryRun = false } = options;
+  
+  // Load current config
+  const current = loadProjectConfig(cwd);
+  const configPath = current.path || path.join(cwd, PROJECT_CONFIG_FILENAME);
+  
+  // Apply the change
+  const newConfig = setConfigValue(current.config, keyPath, value);
+  
+  // Validate before writing
+  const validation = validateProjectConfig(newConfig);
+  
+  if (!validation.valid) {
+    return {
+      success: false,
+      keyPath,
+      value,
+      errors: validation.errors,
+      message: `Cannot set ${keyPath}: validation failed`,
+    };
+  }
+  
+  // Write if not dry-run
+  if (!dryRun) {
+    try {
+      writeProjectConfig(configPath, newConfig, { validate: true });
+      return {
+        success: true,
+        keyPath,
+        value,
+        configPath,
+        message: `Set ${keyPath} = ${JSON.stringify(value)}`,
+      };
+    } catch (error) {
+      return {
+        success: false,
+        keyPath,
+        value,
+        errors: [error.message],
+        message: `Failed to write config: ${error.message}`,
+      };
+    }
+  }
+  
+  // Dry-run mode
+  return {
+    success: true,
+    keyPath,
+    value,
+    dryRun: true,
+    message: `Would set ${keyPath} = ${JSON.stringify(value)} (dry-run)`,
+  };
+}
+
+export function resolveSetting({ config, jsonPath, env, envKey, defaultValue }) {
+  if (env && envKey && env[envKey] !== undefined && env[envKey] !== '') {
+    return { value: env[envKey], source: 'env', envKey };
+  }
+  const fromJson = getConfigValue(config, jsonPath, undefined);
+  if (fromJson !== undefined && fromJson !== null) {
+    return { value: fromJson, source: 'config', jsonPath };
+  }
+  return { value: defaultValue, source: 'default' };
+}