@geraldmaron/construct 1.0.20 → 1.0.23

package/lib/setup.mjs

@@ -27,41 +27,54 @@ import {
 } from './deployment-mode.mjs';
 import { getCanonicalOpenCodeConfigPath, readOpenCodeConfig, writeOpenCodeConfig } from './opencode-config.mjs';
 import { syncFileStateToSql } from './storage/sync.mjs';
+import { runMigrations } from './storage/migrations.mjs';
 import { createSqlClient, closeSqlClient } from './storage/backend.mjs';
 import { getEmbeddingModelInfo, warmupEmbeddingModel } from './storage/embeddings-engine.mjs';
 import { restoreConstructDb } from './storage/postgres-backup.mjs';
 import { buildPressureGuardValues, installPressureGuardLaunchAgent, loadPressureGuardLaunchAgent } from './runtime-pressure.mjs';
 import { consentToInstall } from './setup-prompts.mjs';
+import { postgresPort, postgresContainerName } from './home-namespace.mjs';
 
 const ROOT_DIR = path.resolve(import.meta.dirname, '..');
 const HOME = os.homedir();
-const LOCAL_POSTGRES_PORT = '54329';
 const LOCAL_POSTGRES_USER = 'construct';
 const LOCAL_POSTGRES_PASSWORD = 'construct';
 const LOCAL_POSTGRES_DB = 'construct';
-const LOCAL_DATABASE_URL = `postgresql://${LOCAL_POSTGRES_USER}:${LOCAL_POSTGRES_PASSWORD}@127.0.0.1:${LOCAL_POSTGRES_PORT}/${LOCAL_POSTGRES_DB}`;
+
+// The local DB URL's port is derived per home (construct-lb7b), so build it at
+// the call site from the active homeDir rather than a single module-level const.
+
+function localDatabaseUrl(env = process.env, home = HOME) {
+  return `postgresql://${LOCAL_POSTGRES_USER}:${LOCAL_POSTGRES_PASSWORD}@127.0.0.1:${postgresPort(env, home)}/${LOCAL_POSTGRES_DB}`;
+}
 
 function printHelp() {
   console.log(`Construct install — machine setup (once per machine)
 
 Usage:
-  construct install [--yes] [--no-docker] [--reconfigure]
+  construct install [--scope=project|user|both] [--yes] [--no-docker] [--no-launch-agent] [--reconfigure]
 
 Flags:
-  --yes          accept detected defaults without prompting
-  --no-docker    skip local Postgres / Docker service setup
-  --reconfigure  re-prompt for service consent, ignoring cached answers
-
-What it does:
+  --scope=<s>       project | user | both (default: project — see ADR-0029)
+                      project: no-op + scope guidance; Construct's project artifacts
+                               are written by \`construct init\` inside a repo.
+                      user:    write machine-scope state (~/.construct/, MCP configs,
+                               local Postgres, ~/.claude/* via consent-gated sync).
+                      both:    print project guidance, then run user-scope install.
+  --yes             accept detected defaults without prompting
+  --no-docker       skip local Postgres / Docker service setup
+  --no-launch-agent skip macOS LaunchAgent background service registration
+  --reconfigure     re-prompt for service consent, ignoring cached answers
+
+What --scope=user does:
   - creates ~/.construct/config.env
   - ensures OpenCode config exists
   - configures managed defaults for local vector retrieval
   - starts local Postgres with Docker when available
   - checks required runtime tools and installs cm and cass when available
   - wires Memory, GitHub, and telemetry configuration
-  - runs construct sync (which also regenerates AUTO docs regions)
+  - runs construct sync --global (which writes ~/.claude/* per consent)
   - runs construct doctor
-  - detects the project tech stack and writes .cx/project-profile.json
 
 For project setup (once per repo): construct init`);
 }
@@ -125,19 +138,27 @@ export function localPostgresComposePath(homeDir = HOME) {
 export function writeLocalPostgresCompose(homeDir = HOME) {
   const composePath = localPostgresComposePath(homeDir);
   fs.mkdirSync(path.dirname(composePath), { recursive: true });
+
+  // Container, port, and volume are derived per home so isolated HOMEs do not
+  // collide (construct-lb7b). The runtime (service-manager) derives the same
+  // values from the same home, so they match.
+
+  const container = postgresContainerName(process.env, homeDir);
+  const port = postgresPort(process.env, homeDir);
+  const volume = `${container}-data`;
   const content = `services:
   postgres:
     image: pgvector/pgvector:pg16
-    container_name: construct-postgres
+    container_name: ${container}
     restart: unless-stopped
     environment:
       POSTGRES_USER: ${LOCAL_POSTGRES_USER}
       POSTGRES_PASSWORD: ${LOCAL_POSTGRES_PASSWORD}
       POSTGRES_DB: ${LOCAL_POSTGRES_DB}
     ports:
-      - "127.0.0.1:${LOCAL_POSTGRES_PORT}:5432"
+      - "127.0.0.1:${port}:5432"
     volumes:
-      - construct-postgres-data:/var/lib/postgresql/data
+      - ${volume}:/var/lib/postgresql/data
     healthcheck:
       test: ["CMD-SHELL", "pg_isready -U ${LOCAL_POSTGRES_USER} -d ${LOCAL_POSTGRES_DB}"]
       interval: 5s
@@ -145,7 +166,7 @@ export function writeLocalPostgresCompose(homeDir = HOME) {
       retries: 20
 
 volumes:
-  construct-postgres-data:
+  ${volume}:
 `;
   fs.writeFileSync(composePath, content, 'utf8');
   return composePath;
@@ -372,7 +393,7 @@ export function startManagedPostgres({ homeDir = HOME, env = process.env, spawn
 
   return {
     status: 'ok',
-    databaseUrl: LOCAL_DATABASE_URL,
+    databaseUrl: localDatabaseUrl(env, homeDir),
     composePath,
     message: 'Managed local Postgres is running.',
   };
@@ -431,50 +452,13 @@ function ensureOpenCodeConfig() {
 // repo but never executed by git. Idempotent: leaves a user-set value alone
 // rather than clobbering it.
 
-export function ensureGitHooksPath({ cwd = process.cwd() } = {}) {
-  const hooksDir = path.join(cwd, '.beads', 'hooks');
-  if (!fs.existsSync(path.join(hooksDir, 'pre-commit'))) {
-    return { status: 'skipped', reason: 'no .beads/hooks/pre-commit in this directory' };
-  }
-  const inGit = spawnSync('git', ['rev-parse', '--is-inside-work-tree'], { cwd, stdio: 'pipe', encoding: 'utf8' });
-  if (inGit.status !== 0) {
-    return { status: 'skipped', reason: 'not a git working tree' };
-  }
-  const current = spawnSync('git', ['config', '--get', 'core.hooksPath'], { cwd, stdio: 'pipe', encoding: 'utf8' });
-  const currentValue = current.status === 0 ? (current.stdout || '').trim() : '';
-  const desired = '.beads/hooks';
-  if (currentValue === desired) {
-    return { status: 'ok', message: 'core.hooksPath already wired to .beads/hooks' };
-  }
-
-  // Treat the git default (`.git/hooks` or an absolute path to it) as
-  // equivalent to unset. A user who has accepted the default has not made an
-  // active choice that justifies "leave alone" semantics; without this branch
-  // an install that happens to land while `.git/hooks` is already in play
-  // leaves policy gates inactive permanently.
-  const isGitDefault =
-    !currentValue ||
-    currentValue === '.git/hooks' ||
-    currentValue === path.join(cwd, '.git', 'hooks') ||
-    currentValue.replace(/\/+$/, '').endsWith(`${path.sep}.git${path.sep}hooks`);
-  if (!isGitDefault) {
-    return {
-      status: 'warning',
-      message: `core.hooksPath is set to '${currentValue}'. Leaving alone. Set to '.beads/hooks' to activate Construct policy gates.`,
-    };
-  }
-  const result = spawnSync('git', ['config', 'core.hooksPath', desired], { cwd, stdio: 'pipe', encoding: 'utf8' });
-  if (result.status !== 0) {
-    return {
-      status: 'error',
-      message: `failed to set core.hooksPath: ${(result.stderr || '').trim() || 'unknown error'}`,
-    };
-  }
-  return {
-    status: 'set',
-    message: `core.hooksPath set to .beads/hooks (activates pre-commit secret-scan + Construct policy gates + beads dispatcher)`,
-  };
-}
+// Project-scoped git-hooks wiring lives in its own module and is owned by
+// `construct init`. Re-exported here for importers that reference it via
+// setup.mjs (e.g. tests/setup-git-hooks-path.test.mjs). `construct install`
+// must never mutate the cwd repo (ADR-0027 §3), so the install flow leaves
+// hooks wiring to init.
+
+export { ensureGitHooksPath } from './git-hooks-path.mjs';
 
 // $HOME/.construct/lib/hooks/* is the resolution path for Claude Code
 // Stop-hook commands. Absent symlink → every Stop hook fails silently,
@@ -505,6 +489,36 @@ export function ensureLibSymlink({ homeDir = HOME, rootDir = ROOT_DIR } = {}) {
   };
 }
 
+// ADR-0029: install is explicitly scoped. Default is `project`, which writes
+// nothing and prints scope guidance — silent global writes are the failure mode
+// that ADR retires. `user` runs the machine-state body below; `both` prints the
+// project guidance and then runs user-scope.
+
+const VALID_SCOPES = new Set(['project', 'user', 'both']);
+const DEFAULT_SCOPE = 'project';
+
+function parseScopeFlag(args) {
+  for (const a of args) {
+    if (a === '--scope') return { invalid: '--scope requires a value (project|user|both)' };
+    if (!a.startsWith('--scope=')) continue;
+    const v = a.slice('--scope='.length);
+    if (!VALID_SCOPES.has(v)) return { invalid: `--scope=${v} is not one of project|user|both` };
+    return { scope: v };
+  }
+  return { scope: DEFAULT_SCOPE };
+}
+
+function printProjectScopeGuidance() {
+  console.log('Construct install — scope: project (no-op)');
+  console.log('────────────────────────────────────────');
+  console.log('Project artifacts are written by `construct init` inside a repo.');
+  console.log('To install machine-scope state on this user account:');
+  console.log('  construct install --scope=user');
+  console.log('To do both project (guidance) and user-scope install:');
+  console.log('  construct install --scope=both');
+  console.log('\nSee ADR-0029 (docs/adr/0029-install-scopes-and-hook-budgets.md) for the contract.');
+}
+
 export async function runSetup({ rootDir = ROOT_DIR, args = [], homeDir = HOME } = {}) {
   const argSet = new Set(args);
   const isYes = argSet.has('--yes');
@@ -519,16 +533,39 @@ export async function runSetup({ rootDir = ROOT_DIR, args = [], homeDir = HOME }
   // Reject unknown flags loudly so a typo (e.g. --reconfig) fails fast with the
   // help text instead of silently running defaults.
 
-  const KNOWN_FLAGS = new Set(['--yes', '--no-docker', '--reconfigure', '--help', '-h']);
-  const unknownFlags = args.filter((a) => a.startsWith('-') && !KNOWN_FLAGS.has(a));
+  const KNOWN_FLAGS = new Set(['--yes', '--no-docker', '--no-launch-agent', '--reconfigure', '--help', '-h']);
+  const unknownFlags = args.filter((a) => {
+    if (!a.startsWith('-')) return false;
+    if (a.startsWith('--scope=') || a === '--scope') return false;
+    return !KNOWN_FLAGS.has(a);
+  });
   if (unknownFlags.length) {
     console.error(`Unknown flag(s): ${unknownFlags.join(', ')}`);
     printHelp();
     throw new Error(`Unknown setup flag(s): ${unknownFlags.join(', ')}`);
   }
 
+  const scopeResult = parseScopeFlag(args);
+  if (scopeResult.invalid) {
+    console.error(scopeResult.invalid);
+    printHelp();
+    throw new Error(`Invalid setup scope: ${scopeResult.invalid}`);
+  }
+  const scope = scopeResult.scope;
+
+  if (scope === 'project') {
+    printProjectScopeGuidance();
+    return;
+  }
+
+  if (scope === 'both') {
+    printProjectScopeGuidance();
+    console.log('');
+  }
+
   console.log('Construct setup');
   console.log('────────────────');
+  console.log(`Scope: ${scope}`);
 
   const envPath = ensureUserConfig(homeDir);
   const opencodePath = ensureOpenCodeConfig();
@@ -671,12 +708,6 @@ export async function runSetup({ rootDir = ROOT_DIR, args = [], homeDir = HOME }
     console.log('Cheapest provider: already enabled — skipping prompt.');
   }
 
-  const hooksResult = ensureGitHooksPath({ cwd: process.cwd() });
-  if (hooksResult.status === 'set') console.log(`Git hooks: ${hooksResult.message}`);
-  else if (hooksResult.status === 'ok') console.log('Git hooks: wired');
-  else if (hooksResult.status === 'warning') console.log(`Git hooks: ${hooksResult.message}`);
-  else if (hooksResult.status === 'error') console.log(`Git hooks: ${hooksResult.message}`);
-
   // Ensure workspace directory with docs lanes exists
   ensureWorkspace(homeDir);
 
@@ -688,14 +719,29 @@ export async function runSetup({ rootDir = ROOT_DIR, args = [], homeDir = HOME }
   writeEnvValues(envPath, managedValues);
   let pressureGuardAgent = null;
   let pressureGuardLoad = null;
-  if (process.platform === 'darwin') {
-    pressureGuardAgent = installPressureGuardLaunchAgent({
-      homeDir,
-      rootDir,
-      intervalSeconds: Number(managedValues.CONSTRUCT_PRESSURE_GUARD_INTERVAL_SECONDS || 300),
-      nodePath: process.execPath,
+  if (process.platform === 'darwin' && !argSet.has('--no-launch-agent')) {
+    const laConsent = await consentToInstall({
+      name: 'launchagent',
+      question: 'Install background pressure-release service (macOS LaunchAgent)?',
+      isYes,
+      force: reconfigure,
+      alreadyConfigured: fs.existsSync(path.join(homeDir, 'Library', 'LaunchAgents', 'dev.construct.pressure-release.plist')),
+      alreadyConfiguredNote: 'Background pressure-release service already installed.',
+      envPath,
     });
-    pressureGuardLoad = loadPressureGuardLaunchAgent({ plistPath: pressureGuardAgent.plistPath });
+    if (laConsent.decision) {
+      pressureGuardAgent = installPressureGuardLaunchAgent({
+        homeDir,
+        rootDir,
+        intervalSeconds: Number(managedValues.CONSTRUCT_PRESSURE_GUARD_INTERVAL_SECONDS || 300),
+        nodePath: process.execPath,
+      });
+      pressureGuardLoad = loadPressureGuardLaunchAgent({ plistPath: pressureGuardAgent.plistPath });
+    } else {
+      console.log(`LaunchAgent: skipped (${laConsent.note})`);
+    }
+  } else if (argSet.has('--no-launch-agent')) {
+    console.log('LaunchAgent: skipped (--no-launch-agent)');
   }
 
   if (isYes) {
@@ -716,67 +762,54 @@ export async function runSetup({ rootDir = ROOT_DIR, args = [], homeDir = HOME }
       console.log(`  LaunchAgent: ${pressureGuardAgent.plistPath}`);
       console.log(`  LaunchAgent load: ${pressureGuardLoad?.loaded ? 'active' : pressureGuardLoad?.reason || 'pending manual load'}`);
     }
+  }
 
+  // Schema init runs whenever postgres is reachable — pgvector tables must exist before any
+  // retrieval call. Idempotent via construct_schema_migrations hash tracking.
+
+  if (serviceResult.status === 'ok') {
+    try {
+      await waitForSqlReady({ ...process.env, ...managedValues });
+      const readyClient = createSqlClient({ ...process.env, ...managedValues });
+      if (readyClient) {
+        try {
+          const { applied } = await runMigrations(readyClient);
+          if (applied.length) console.log(`Postgres schema: applied ${applied.length} migration(s) — ${applied.join(', ')}`);
+          else console.log('Postgres schema: up to date');
+        } finally {
+          await closeSqlClient(readyClient).catch(() => {});
+        }
+      }
+    } catch (error) {
+      console.log(`Postgres schema init failed: ${error?.message || 'unknown error'}`);
+    }
+  }
+
+  if (isYes && serviceResult.status === 'ok') {
     const sqlClient = createSqlClient({ ...process.env, ...managedValues });
     if (sqlClient) {
-      let readyClient = null;
-      let sqlClientClosed = false;
       try {
-        if (serviceResult.status === 'ok') {
-          await closeSqlClient(sqlClient);
-          sqlClientClosed = true;
-          await waitForSqlReady({ ...process.env, ...managedValues });
-        }
-        readyClient = createSqlClient({ ...process.env, ...managedValues });
-        const migration = await import('node:fs/promises').then((fs) => fs.readFile(new URL('../db/schema/001_init.sql', import.meta.url), 'utf8'));
-        await readyClient.unsafe(migration);
-        console.log('\nPostgres schema initialized.');
-
-        // Restore data from the most recent stash (if any) before syncing.
-        if (serviceResult.status === 'ok') {
-          const restore = restoreConstructDb({ homeDir });
-          if (restore.status === 'restored') {
-            console.log(`Construct DB restored from stash: ${restore.stashPath}`);
-          } else if (restore.status === 'no-stash') {
-            console.log('No stash found — starting with empty construct DB.');
-          } else if (restore.status !== 'no-stash') {
-            console.log(`Construct DB restore: ${restore.status}`);
-          }
+        const restore = restoreConstructDb({ homeDir });
+        if (restore.status === 'restored') {
+          console.log(`Construct DB restored from stash: ${restore.stashPath}`);
+        } else if (restore.status === 'no-stash') {
+          console.log('No stash found — starting with empty construct DB.');
+        } else {
+          console.log(`Construct DB restore: ${restore.status}`);
         }
 
+        // Index Construct's own package docs (rootDir, machine-scoped) into the
+        // shared hybrid store. Seeding a downstream project's corpus is project
+        // state and belongs to `construct init` / `construct ingest`, never to
+        // machine install (ADR-0027 §3): install reads no cwd.
+
         const syncResult = await syncFileStateToSql(rootDir, { env: { ...process.env, ...managedValues }, project: 'construct' });
         console.log(`Hybrid storage sync: ${syncResult.status}`);
         if (syncResult.embeddingModel) console.log(`Embedding model: ${syncResult.embeddingModel}`);
-
-        // When setup runs inside a downstream project (cwd is not the
-        // Construct package itself), seed the vector index from the
-        // project's existing docs / AGENTS / plan so the agent has
-        // context to compare new intake against from day one. No-op
-        // when there's nothing project-like in cwd.
-
-        const projectCwd = process.cwd();
-        const isDownstreamProject = projectCwd !== rootDir && (
-          fs.existsSync(path.join(projectCwd, 'docs')) ||
-          fs.existsSync(path.join(projectCwd, 'AGENTS.md')) ||
-          fs.existsSync(path.join(projectCwd, 'package.json'))
-        );
-        if (isDownstreamProject) {
-          try {
-            const projectName = path.basename(projectCwd);
-            const projectSync = await syncFileStateToSql(projectCwd, {
-              env: { ...process.env, ...managedValues },
-              project: projectName,
-            });
-            console.log(`Project corpus indexed: ${projectName} (${projectSync.documentsSynced || 0} docs, ${projectSync.embeddingsSynced || 0} embeddings) — agent can now compare new intake against existing material.`);
-          } catch (err) {
-            console.log(`Project corpus index skipped: ${err?.message || 'unknown error'} — run \`construct ingest\` later to seed manually.`);
-          }
-        }
       } catch (error) {
-        console.log(`Hybrid storage init failed: ${error?.message || 'unknown error'}`);
+        console.log(`Hybrid storage sync failed: ${error?.message || 'unknown error'}`);
       } finally {
-        await closeSqlClient(readyClient).catch(() => {});
-        if (!sqlClientClosed) await closeSqlClient(sqlClient);
+        await closeSqlClient(sqlClient).catch(() => {});
       }
     }
   }
@@ -796,26 +829,17 @@ export async function runSetup({ rootDir = ROOT_DIR, args = [], homeDir = HOME }
 
   // Install is machine setup: the global front-door agent must land on every
   // user-scope surface (opencode/claude/codex/copilot) or a fresh machine fails
-  // cross-surface parity. Plain sync writes global hooks + project tier but not
-  // the front-door agent — `--global` is what populates it, so run both.
-
-  runConstruct(['sync']);
+  // cross-surface parity. Both `sync` and `sync --global` are kept to preserve
+  // every write across the project-detected and forced-global paths; in a
+  // non-project install cwd both resolve to the same global branch and would
+  // print the "Synced … to global scope" summary twice. The first call runs
+  // --quiet so the canonical summary prints exactly once from `sync --global`,
+  // with no change to what either writes.
+
+  runConstruct(['sync', '--quiet']);
   runConstruct(['sync', '--global']);
   runConstruct(['doctor']);
 
-  // Profile the CWD so per-host skill filtering layers downstream have
-  // a cached, host-agnostic signal to work from. Non-fatal on failure.
-  try {
-    const { detectProjectProfile, writeProfile } = await import('./project-profile.mjs');
-    const profile = detectProjectProfile(process.cwd());
-    if (profile.tags.length > 0) {
-      const profilePath = writeProfile(profile, process.cwd());
-      console.log(`\nProject profile: ${profile.tags.join(', ')}`);
-      console.log(`  Saved to ${profilePath}`);
-      console.log(`  Run \`construct skills scope\` to see which installed skills apply to this project.`);
-    }
-  } catch { /* best effort */ }
-
   // ── Summary panel ────────────────────────────────────────────────────────
   const setupTs = new Date().toISOString().slice(0, 19).replace(/[:.]/g, '-');
   const setupLogPath = path.join(HOME, '.cx', `setup-${setupTs}.log`);

package/lib/storage/backend.mjs

@@ -19,6 +19,19 @@ function cleanUrl(url) {
   return String(url || '').trim();
 }
 
+// postgres surfaces NOTICE/INFO/DEBUG chatter on idempotent DDL ("extension
+// vector already exists, skipping") through its default onnotice handler, which
+// prints the raw message object to the console and clutters install/init output.
+// Drop that chatter; still surface WARNING and worse to stderr so real problems
+// are not swallowed.
+
+function notify(notice) {
+  const severity = String(notice?.severity || notice?.severity_local || '').toUpperCase();
+  if (severity && !['NOTICE', 'INFO', 'DEBUG', 'LOG'].includes(severity)) {
+    process.stderr.write(`[postgres ${severity}] ${notice?.message || ''}\n`);
+  }
+}
+
 export function createSqlClient(env = process.env) {
   const databaseUrl = cleanUrl(resolveDatabaseUrl(env));
   if (!databaseUrl || !postgres) return null;
@@ -26,6 +39,7 @@ export function createSqlClient(env = process.env) {
     max: Number.parseInt(env.CONSTRUCT_DB_POOL_SIZE || '5', 10),
     idle_timeout: Number.parseInt(env.CONSTRUCT_DB_IDLE_TIMEOUT_MS || '30000', 10),
     connect_timeout: Number.parseInt(env.CONSTRUCT_DB_CONNECT_TIMEOUT_MS || '5000', 10),
+    onnotice: notify,
   });
 }