@geraldmaron/construct 1.0.0 → 1.0.1

package/lib/init-update.mjs

@@ -0,0 +1,168 @@
+#!/usr/bin/env node
+/**
+ * lib/init-update.mjs — update existing projects with latest AGENTS.md template.
+ * 
+ * For projects that already have AGENTS.md but need to sync with the latest
+ * Construct operating rules and CI enforcement.
+ * 
+ * Usage:
+ *   node lib/init-update.mjs [--dry-run] [--cwd=path]
+ *   construct init:update [--dry-run]
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import { readFileSync, writeFileSync, existsSync } from "node:fs";
+
+const args = process.argv.slice(2);
+const dryRun = args.includes("--dry-run");
+const cwdArg = args.find(arg => arg.startsWith("--cwd="));
+const cwd = cwdArg ? path.resolve(cwdArg.split("=")[1]) : process.cwd();
+
+console.log(`📝 Updating project documentation in ${cwd}`);
+
+// Load the AGENTS.md template from project-init-shared
+async function loadAgentsTemplate(projectName) {
+  const modulePath = path.join(import.meta.dirname, 'project-init-shared.mjs');
+  try {
+    // Import the module and call the buildAgentsGuide function
+    const module = await import(modulePath);
+    if (module.buildAgentsGuide) {
+      return module.buildAgentsGuide(projectName);
+    }
+    throw new Error('Could not find buildAgentsGuide function in project-init-shared.mjs');
+  } catch (error) {
+    console.error(`❌ Failed to load AGENTS.md template: ${error.message}`);
+    process.exit(1);
+  }
+}
+
+function updateAgentsMd(existingContent, newTemplate) {
+  // We'll do a simple replacement for now
+  // In a real implementation, we'd parse the existing file and merge sections
+  
+  console.log(`🔄 Updating AGENTS.md`);
+  
+  if (dryRun) {
+    console.log(`📋 Dry run - would update AGENTS.md`);
+    console.log(`--- Current AGENTS.md (first 200 chars) ---`);
+    console.log(existingContent.substring(0, 200) + '...');
+    console.log(`--- New AGENTS.md (first 200 chars) ---`);
+    console.log(newTemplate.substring(0, 200) + '...');
+    return null;
+  }
+  
+  // Backup existing file
+  const backupPath = path.join(cwd, 'AGENTS.md.backup');
+  writeFileSync(backupPath, existingContent, 'utf8');
+  console.log(`📦 Created backup at ${backupPath}`);
+  
+  // Write new template
+  const agentsPath = path.join(cwd, 'AGENTS.md');
+  writeFileSync(agentsPath, newTemplate, 'utf8');
+  console.log(`✅ Updated AGENTS.md`);
+  
+  return newTemplate;
+}
+
+function updateCiWorkflow(cwd) {
+  const workflowPath = path.join(cwd, '.github', 'workflows', 'ci.yml');
+  if (!existsSync(workflowPath)) {
+    console.log(`⚠️  No CI workflow found at ${workflowPath}`);
+    return false;
+  }
+  
+  let content = readFileSync(workflowPath, 'utf8');
+  
+  // Check if docs:verify is already in the workflow
+  if (content.includes('construct docs:verify')) {
+    console.log(`✅ CI workflow already has docs:verify check`);
+    return false;
+  }
+  
+  // Find the test job and add docs:verify after doctor
+  if (content.includes('node bin/construct doctor')) {
+    const updatedContent = content.replace(
+      /(\s+- run: node bin\/construct doctor\s*)/,
+      '$1      - run: node bin/construct docs:verify\n'
+    );
+    
+    if (dryRun) {
+      console.log(`📋 Dry run - would update CI workflow to include docs:verify`);
+      return true;
+    }
+    
+    const backupPath = workflowPath + '.backup';
+    writeFileSync(backupPath, content, 'utf8');
+    writeFileSync(workflowPath, updatedContent, 'utf8');
+    console.log(`✅ Updated CI workflow to include docs:verify check`);
+    return true;
+  }
+  
+  console.log(`⚠️  Could not find 'construct doctor' in CI workflow to add docs:verify`);
+  return false;
+}
+
+async function main() {
+  console.log(`\n🔍 Checking project structure...`);
+  
+  // Check for AGENTS.md
+  const agentsPath = path.join(cwd, 'AGENTS.md');
+  if (!existsSync(agentsPath)) {
+    console.log(`❌ AGENTS.md not found. Run 'construct init' first.`);
+    process.exit(1);
+  }
+  
+  const existingAgents = readFileSync(agentsPath, 'utf8');
+  
+  // Get project name from package.json or directory name
+  let projectName = path.basename(cwd);
+  const packagePath = path.join(cwd, 'package.json');
+  if (existsSync(packagePath)) {
+    try {
+      const pkg = JSON.parse(readFileSync(packagePath, 'utf8'));
+      if (pkg.name) projectName = pkg.name;
+    } catch (error) {
+      console.log(`⚠️  Could not read package.json: ${error.message}`);
+    }
+  }
+  
+  const template = await loadAgentsTemplate(projectName);
+  
+  console.log(`\n📊 Analysis:`);
+  console.log(`   • AGENTS.md found (${existingAgents.length} chars)`);
+  console.log(`   • Latest template loaded (${template.length} chars)`);
+  console.log(`   • Project name: ${projectName}`);
+  
+  // Check if AGENTS.md has documentation enforcement section
+  const hasDocEnforcement = existingAgents.includes('Documentation Rules');
+  console.log(`   • Has documentation enforcement: ${hasDocEnforcement ? '✅' : '❌'}`);
+  
+  // Check for CI workflow
+  const ciUpdated = updateCiWorkflow(cwd);
+  
+  // Update AGENTS.md if it doesn't have the latest sections
+  if (!hasDocEnforcement) {
+    updateAgentsMd(existingAgents, template);
+  } else {
+    console.log(`✅ AGENTS.md already has documentation enforcement rules`);
+  }
+  
+  console.log(`\n🎉 Update complete!`);
+  console.log(`\nNext steps:`);
+  console.log(`   1. Review the updated AGENTS.md`);
+  console.log(`   2. Run 'construct docs:verify' to test documentation checks`);
+  console.log(`   3. Commit changes: git add AGENTS.md .github/workflows/ci.yml`);
+  console.log(`   4. Push and verify CI passes`);
+  
+  if (dryRun) {
+    console.log(`\n⚠️  This was a dry run. Use 'construct init:update' without --dry-run to apply changes.`);
+  }
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  main().catch(error => {
+    console.error(`❌ Error: ${error.message}`);
+    process.exit(1);
+  });
+}

package/lib/init.mjs

@@ -0,0 +1,107 @@
+#!/usr/bin/env node
+/**
+ * lib/init.mjs — bootstrap Construct project state in an existing repo.
+ *
+ * Intentionally separate from `init-docs`: `construct init` creates the
+ * baseline agent/workflow context for a repo, while `construct init-docs`
+ * stands up a documentation system and lane-specific templates.
+ *
+ * Usage:
+ *   node lib/init.mjs [target-path]
+ *   construct init [path]
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+
+import {
+  buildAgentsGuide,
+  buildContextJson,
+  buildContextMarkdown,
+  buildPlanTemplate,
+  writeStampedIfMissing,
+} from "./project-init-shared.mjs";
+
+const args = process.argv.slice(2);
+const targetArg = args.find((arg) => !arg.startsWith("--"));
+const target = path.resolve(targetArg ?? process.cwd());
+
+const created = [];
+const skipped = [];
+
+function inferProjectName(targetPath) {
+  const packageJsonPath = path.join(targetPath, "package.json");
+  if (fs.existsSync(packageJsonPath)) {
+    try {
+      const pkg = JSON.parse(fs.readFileSync(packageJsonPath, "utf8"));
+      return pkg.name || path.basename(targetPath);
+    } catch {}
+  }
+  return path.basename(targetPath);
+}
+
+function main() {
+  const projectName = inferProjectName(target);
+
+  writeStampedIfMissing({
+    targetRoot: target,
+    created,
+    skipped,
+    filePath: path.join(target, "AGENTS.md"),
+    content: buildAgentsGuide(projectName),
+    generator: "construct/init",
+  });
+  writeStampedIfMissing({
+    targetRoot: target,
+    created,
+    skipped,
+    filePath: path.join(target, "plan.md"),
+    content: buildPlanTemplate(),
+    generator: "construct/init",
+  });
+  writeStampedIfMissing({
+    targetRoot: target,
+    created,
+    skipped,
+    filePath: path.join(target, ".cx", "context.json"),
+    content: buildContextJson(projectName),
+    generator: "construct/init",
+  });
+  writeStampedIfMissing({
+    targetRoot: target,
+    created,
+    skipped,
+    filePath: path.join(target, ".cx", "context.md"),
+    content: buildContextMarkdown(),
+    generator: "construct/init",
+  });
+  writeStampedIfMissing({
+    targetRoot: target,
+    created,
+    skipped,
+    filePath: path.join(target, ".cx", ".gitkeep"),
+    content: "",
+    generator: "construct/init",
+  });
+  writeStampedIfMissing({
+    targetRoot: target,
+    created,
+    skipped,
+    filePath: path.join(target, ".cx", "inbox", ".gitkeep"),
+    content: "",
+    generator: "construct/init",
+  });
+
+  process.stdout.write(`\nConstruct init → ${target}\n\n`);
+  if (created.length) {
+    process.stdout.write("Created:\n");
+    for (const file of created) process.stdout.write(`  + ${file}\n`);
+  }
+  if (skipped.length) {
+    process.stdout.write("\nSkipped (already exist):\n");
+    for (const file of skipped) process.stdout.write(`  ~ ${file}\n`);
+  }
+  process.stdout.write(`\n${created.length} created, ${skipped.length} skipped.\n`);
+}
+
+main();

package/lib/install/first-invocation.mjs

@@ -0,0 +1,119 @@
+/**
+ * lib/install/first-invocation.mjs — one-shot resource probe on first use.
+ *
+ * Construct's postinstall is silent and idempotent (per the husky / prisma /
+ * supabase pattern — npm swallows postinstall output, so prompting from there
+ * is unreliable). Instead, the first time a user invokes ANY `construct`
+ * command on a machine that hasn't been bootstrapped, this probe runs:
+ *   1. Quick check whether `BOOTSTRAP_CHECKED=1` is cached in config.env.
+ *      If yes → silent, return immediately.
+ *   2. Otherwise, run `probeAll()` from lib/bootstrap/resources.mjs.
+ *   3. If everything's healthy → silent, set BOOTSTRAP_CHECKED=1.
+ *   4. If anything's missing → print the status table to stderr; on TTY,
+ *      prompt to run `construct init` now. Always set BOOTSTRAP_CHECKED=1
+ *      so we don't re-prompt on subsequent commands.
+ *
+ * Skipped entirely for hook invocations (would corrupt hook output), for
+ * `setup`/`uninstall`/`version` (those handle their own flow), and on
+ * non-TTY runs (CI / scripts — keep them silent).
+ */
+
+import readline from 'node:readline';
+
+import { parseEnvFile, writeEnvValues, getUserEnvPath } from '../env-config.mjs';
+import { probeAll, formatProbe } from '../bootstrap/resources.mjs';
+
+const BOOTSTRAP_CHECKED_KEY = 'BOOTSTRAP_CHECKED';
+const SKIP_COMMANDS = new Set([
+  'hook', 'setup', 'uninstall', 'version', 'help', 'completions', 'doctor',
+]);
+
+export function shouldSkipProbe({ command, env = process.env, stdin = process.stdin } = {}) {
+  if (!command) return true;
+  if (SKIP_COMMANDS.has(command)) return true;
+  if (command.startsWith('-')) return true;
+  if (env[BOOTSTRAP_CHECKED_KEY] === '1') return true;
+  if (env.CONSTRUCT_SKIP_BOOTSTRAP_PROBE === '1') return true;
+  return false;
+}
+
+export async function maybeFirstInvocationProbe({
+  command,
+  homeDir,
+  env = process.env,
+  stdin = process.stdin,
+  stdout = process.stderr,
+  readlineModule = readline,
+  probeAllFn = probeAll,
+  formatProbeFn = formatProbe,
+  writeEnvFn = writeEnvValues,
+} = {}) {
+  if (shouldSkipProbe({ command, env, stdin })) {
+    return { ran: false, reason: 'skipped' };
+  }
+
+  const envPath = getUserEnvPath(homeDir);
+  const persisted = parseEnvFile(envPath);
+  if (persisted[BOOTSTRAP_CHECKED_KEY] === '1') {
+    return { ran: false, reason: 'already-checked' };
+  }
+
+  const probes = await probeAllFn();
+  const missingRequired = probes.filter((p) => p.required && !p.present);
+  const missingOptional = probes.filter((p) => !p.required && !p.present);
+
+  if (missingRequired.length === 0 && missingOptional.length === 0) {
+    writeEnvFn(envPath, { [BOOTSTRAP_CHECKED_KEY]: '1' });
+    return { ran: true, reason: 'all-healthy', missingRequired: 0, missingOptional: 0 };
+  }
+
+  stdout.write('\n[construct] First-run Resource check\n');
+  for (const probe of probes) stdout.write(formatProbeFn(probe) + '\n');
+
+  if (missingRequired.length > 0) {
+    stdout.write(`\n[construct] ${missingRequired.length} required resource(s) missing. Run \`construct init\` to install.\n\n`);
+  } else {
+    stdout.write(`\n[construct] ${missingOptional.length} optional resource(s) missing. Run \`construct init\` to install (Postgres, telemetry, embedding model), or continue in degraded mode.\n\n`);
+  }
+
+  if (stdin.isTTY && stdout.isTTY !== false) {
+    const wants = await promptYesNo({
+      question: 'Run `construct init` now?',
+      defaultYes: missingRequired.length > 0,
+      readlineModule,
+      stdin,
+      stdout,
+    });
+    writeEnvFn(envPath, { [BOOTSTRAP_CHECKED_KEY]: '1' });
+    return {
+      ran: true,
+      reason: 'prompted',
+      missingRequired: missingRequired.length,
+      missingOptional: missingOptional.length,
+      runSetup: wants,
+    };
+  }
+
+  writeEnvFn(envPath, { [BOOTSTRAP_CHECKED_KEY]: '1' });
+  return {
+    ran: true,
+    reason: 'reported-non-tty',
+    missingRequired: missingRequired.length,
+    missingOptional: missingOptional.length,
+  };
+}
+
+async function promptYesNo({ question, defaultYes, readlineModule, stdin, stdout }) {
+  const suffix = defaultYes ? '[Y/n]' : '[y/N]';
+  return new Promise((resolve) => {
+    const rl = readlineModule.createInterface({ input: stdin, output: stdout });
+    rl.question(`${question} ${suffix} `, (raw) => {
+      rl.close();
+      const trimmed = String(raw || '').trim().toLowerCase();
+      if (!trimmed) return resolve(defaultYes);
+      if (['y', 'yes'].includes(trimmed)) return resolve(true);
+      if (['n', 'no'].includes(trimmed)) return resolve(false);
+      resolve(defaultYes);
+    });
+  });
+}

package/lib/install/stage-project.mjs

@@ -0,0 +1,69 @@
+/**
+ * lib/install/stage-project.mjs — shared staging logic for a consumer project.
+ *
+ * Same work as `bin/construct-postinstall.mjs` but callable from both the
+ * npm postinstall hook and `construct init`. Stages `.construct/{run.mjs,
+ * bootstrap.sh, bootstrap.ps1, version}` and runs `sync-agents.mjs --project`
+ * to materialise `.claude/agents/` and `.claude/settings.json` from the
+ * bundled registry. Idempotent — re-runs overwrite the launcher files but
+ * leave existing `.construct/version` and project state untouched beyond
+ * what `sync-agents.mjs --project` writes itself.
+ */
+
+import { spawnSync } from 'node:child_process';
+import { existsSync, copyFileSync, writeFileSync, mkdirSync, chmodSync } from 'node:fs';
+import path from 'node:path';
+
+export function stageProjectAdapters({ projectRoot, packageRoot, pkgVersion, log }) {
+  if (!projectRoot) throw new Error('stageProjectAdapters: projectRoot is required');
+  if (!packageRoot) throw new Error('stageProjectAdapters: packageRoot is required');
+  const emit = typeof log === 'function' ? log : () => {};
+
+  const templateDir = path.join(packageRoot, 'templates', 'distribution');
+  const syncScript = path.join(packageRoot, 'scripts', 'sync-agents.mjs');
+
+  ensureProjectLauncher({ projectRoot, templateDir, pkgVersion });
+  emit(`staged .construct/ launcher in ${projectRoot}`);
+
+  if (!existsSync(syncScript)) {
+    emit(`sync-agents.mjs not found at ${syncScript}; skipping adapter sync`);
+    return { staged: true, synced: false };
+  }
+
+  emit(`syncing project adapters into ${projectRoot}/.claude/`);
+  const result = spawnSync(process.execPath, [syncScript, '--project'], {
+    cwd: projectRoot,
+    stdio: 'inherit',
+    env: { ...process.env, CONSTRUCT_PROJECT_ROOT: projectRoot },
+  });
+
+  if (result.status !== 0) {
+    emit(`sync failed (exit ${result.status}); project left in a clean state`);
+    return { staged: true, synced: false };
+  }
+  return { staged: true, synced: true };
+}
+
+function ensureProjectLauncher({ projectRoot, templateDir, pkgVersion }) {
+  const dotConstruct = path.join(projectRoot, '.construct');
+  mkdirSync(dotConstruct, { recursive: true });
+  mkdirSync(path.join(dotConstruct, 'cache', 'bin'), { recursive: true });
+
+  const versionPath = path.join(dotConstruct, 'version');
+  if (!existsSync(versionPath) && pkgVersion) {
+    writeFileSync(versionPath, pkgVersion + '\n');
+  }
+
+  const copies = [
+    ['run.mjs',       0o644],
+    ['bootstrap.sh',  0o755],
+    ['bootstrap.ps1', 0o644],
+  ];
+  for (const [name, mode] of copies) {
+    const src = path.join(templateDir, name);
+    const dst = path.join(dotConstruct, name);
+    if (!existsSync(src)) continue;
+    copyFileSync(src, dst);
+    try { chmodSync(dst, mode); } catch { /* mode set is best-effort on Windows */ }
+  }
+}