@geraldmaron/construct 1.0.0 → 1.0.1

package/lib/embed/supervision.mjs

@@ -0,0 +1,235 @@
+/**
+ * lib/embed/supervision.mjs — platform supervisor integration for the embed daemon.
+ *
+ * Writes a platform service file so the embed daemon is automatically
+ * restarted with exponential backoff if it crashes, and started on login/boot.
+ *
+ * Platform support:
+ *   macOS   — launchd plist at ~/Library/LaunchAgents/com.construct.embed.plist
+ *   Linux   — systemd user unit at ~/.config/systemd/user/construct-embed.service
+ *   Windows — Task Scheduler (schtasks) entry named "Construct.Embed"
+ *
+ * Usage:
+ *   import { installSupervision, uninstallSupervision, supervisionStatus } from './supervision.mjs';
+ *   await installSupervision();
+ *   await uninstallSupervision();
+ *   const info = await supervisionStatus();
+ */
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+
+const HOME = os.homedir();
+const PLATFORM = process.platform;
+const NODE_BIN = process.execPath;
+
+// Path to the construct bin — we use absolute path so launchd/systemd can find it.
+function constructBin() {
+  const local = path.join(HOME, '.construct', 'bin', 'construct');
+  if (fs.existsSync(local)) return local;
+  const result = spawnSync('which', ['construct'], { encoding: 'utf8' });
+  return result.status === 0 ? result.stdout.trim() : 'construct';
+}
+
+// ── macOS launchd ───────────────────────────────────────────────────────────
+
+const LAUNCHD_LABEL = 'com.construct.embed';
+const LAUNCHD_PLIST = path.join(HOME, 'Library', 'LaunchAgents', `${LAUNCHD_LABEL}.plist`);
+
+function launchdPlist(bin, logPath) {
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
+  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key>
+  <string>${LAUNCHD_LABEL}</string>
+  <key>ProgramArguments</key>
+  <array>
+    <string>${NODE_BIN}</string>
+    <string>${bin}</string>
+    <string>embed</string>
+    <string>start</string>
+    <string>--foreground</string>
+  </array>
+  <key>RunAtLoad</key>
+  <true/>
+  <key>KeepAlive</key>
+  <dict>
+    <key>Crashed</key>
+    <true/>
+  </dict>
+  <key>ThrottleInterval</key>
+  <integer>10</integer>
+  <key>StandardOutPath</key>
+  <string>${logPath}</string>
+  <key>StandardErrorPath</key>
+  <string>${logPath}</string>
+  <key>EnvironmentVariables</key>
+  <dict>
+    <key>HOME</key>
+    <string>${HOME}</string>
+  </dict>
+</dict>
+</plist>
+`;
+}
+
+async function installLaunchd(bin, logPath) {
+  fs.mkdirSync(path.dirname(LAUNCHD_PLIST), { recursive: true });
+  fs.writeFileSync(LAUNCHD_PLIST, launchdPlist(bin, logPath));
+  const load = spawnSync('launchctl', ['load', '-w', LAUNCHD_PLIST], { encoding: 'utf8' });
+  if (load.status !== 0) {
+    throw new Error(`launchctl load failed: ${load.stderr}`);
+  }
+  return { method: 'launchd', file: LAUNCHD_PLIST };
+}
+
+async function uninstallLaunchd() {
+  if (!fs.existsSync(LAUNCHD_PLIST)) return { method: 'launchd', wasInstalled: false };
+  spawnSync('launchctl', ['unload', '-w', LAUNCHD_PLIST], { encoding: 'utf8' });
+  fs.rmSync(LAUNCHD_PLIST, { force: true });
+  return { method: 'launchd', wasInstalled: true };
+}
+
+function launchdStatus() {
+  if (!fs.existsSync(LAUNCHD_PLIST)) return { installed: false };
+  const result = spawnSync('launchctl', ['list', LAUNCHD_LABEL], { encoding: 'utf8' });
+  return {
+    installed: true,
+    active: result.status === 0,
+    file: LAUNCHD_PLIST,
+  };
+}
+
+// ── Linux systemd ───────────────────────────────────────────────────────────
+
+const SYSTEMD_UNIT_NAME = 'construct-embed.service';
+const SYSTEMD_UNIT_DIR = path.join(HOME, '.config', 'systemd', 'user');
+const SYSTEMD_UNIT_FILE = path.join(SYSTEMD_UNIT_DIR, SYSTEMD_UNIT_NAME);
+
+function systemdUnit(bin, logPath) {
+  return `[Unit]
+Description=Construct embed daemon
+After=network.target
+
+[Service]
+Type=simple
+ExecStart=${NODE_BIN} ${bin} embed start --foreground
+Restart=on-failure
+RestartSec=10
+RestartMaxDelay=300
+StandardOutput=append:${logPath}
+StandardError=append:${logPath}
+Environment=HOME=${HOME}
+
+[Install]
+WantedBy=default.target
+`;
+}
+
+async function installSystemd(bin, logPath) {
+  fs.mkdirSync(SYSTEMD_UNIT_DIR, { recursive: true });
+  fs.writeFileSync(SYSTEMD_UNIT_FILE, systemdUnit(bin, logPath));
+
+  const reload = spawnSync('systemctl', ['--user', 'daemon-reload'], { encoding: 'utf8' });
+  if (reload.status !== 0) throw new Error(`daemon-reload failed: ${reload.stderr}`);
+
+  const enable = spawnSync('systemctl', ['--user', 'enable', '--now', SYSTEMD_UNIT_NAME], { encoding: 'utf8' });
+  if (enable.status !== 0) throw new Error(`systemctl enable failed: ${enable.stderr}`);
+
+  return { method: 'systemd', file: SYSTEMD_UNIT_FILE };
+}
+
+async function uninstallSystemd() {
+  if (!fs.existsSync(SYSTEMD_UNIT_FILE)) return { method: 'systemd', wasInstalled: false };
+  spawnSync('systemctl', ['--user', 'disable', '--now', SYSTEMD_UNIT_NAME], { encoding: 'utf8' });
+  fs.rmSync(SYSTEMD_UNIT_FILE, { force: true });
+  spawnSync('systemctl', ['--user', 'daemon-reload'], { encoding: 'utf8' });
+  return { method: 'systemd', wasInstalled: true };
+}
+
+function systemdStatus() {
+  if (!fs.existsSync(SYSTEMD_UNIT_FILE)) return { installed: false };
+  const result = spawnSync('systemctl', ['--user', 'is-active', SYSTEMD_UNIT_NAME], { encoding: 'utf8' });
+  return {
+    installed: true,
+    active: result.stdout.trim() === 'active',
+    file: SYSTEMD_UNIT_FILE,
+  };
+}
+
+// ── Windows Task Scheduler ──────────────────────────────────────────────────
+
+const WIN_TASK_NAME = 'Construct.Embed';
+
+async function installWindows(bin, logPath) {
+  const cmd = [
+    'schtasks', '/Create', '/F',
+    '/TN', WIN_TASK_NAME,
+    '/TR', `"${NODE_BIN}" "${bin}" embed start --foreground >> "${logPath}" 2>&1`,
+    '/SC', 'ONLOGON',
+    '/RL', 'HIGHEST',
+  ].join(' ');
+  const result = spawnSync('cmd', ['/c', cmd], { encoding: 'utf8' });
+  if (result.status !== 0) throw new Error(`schtasks failed: ${result.stderr}`);
+  return { method: 'task-scheduler', taskName: WIN_TASK_NAME };
+}
+
+async function uninstallWindows() {
+  const result = spawnSync('schtasks', ['/Query', '/TN', WIN_TASK_NAME], { encoding: 'utf8' });
+  if (result.status !== 0) return { method: 'task-scheduler', wasInstalled: false };
+  spawnSync('schtasks', ['/Delete', '/TN', WIN_TASK_NAME, '/F'], { encoding: 'utf8' });
+  return { method: 'task-scheduler', wasInstalled: true };
+}
+
+function windowsStatus() {
+  const result = spawnSync('schtasks', ['/Query', '/TN', WIN_TASK_NAME, '/FO', 'CSV'], { encoding: 'utf8' });
+  if (result.status !== 0) return { installed: false };
+  const running = result.stdout.includes('Running');
+  return { installed: true, active: running, taskName: WIN_TASK_NAME };
+}
+
+// ── Public API ──────────────────────────────────────────────────────────────
+
+function logPath() {
+  return path.join(HOME, '.cx', 'runtime', 'embed-daemon.log');
+}
+
+/**
+ * Install the platform supervisor so the embed daemon auto-restarts on crash.
+ */
+export async function installSupervision() {
+  const bin = constructBin();
+  const log = logPath();
+  fs.mkdirSync(path.dirname(log), { recursive: true });
+
+  if (PLATFORM === 'darwin') return installLaunchd(bin, log);
+  if (PLATFORM === 'linux')  return installSystemd(bin, log);
+  if (PLATFORM === 'win32')  return installWindows(bin, log);
+  throw new Error(`supervision not supported on platform: ${PLATFORM}`);
+}
+
+/**
+ * Remove the platform supervisor entry. Does not stop a currently-running daemon.
+ */
+export async function uninstallSupervision() {
+  if (PLATFORM === 'darwin') return uninstallLaunchd();
+  if (PLATFORM === 'linux')  return uninstallSystemd();
+  if (PLATFORM === 'win32')  return uninstallWindows();
+  throw new Error(`supervision not supported on platform: ${PLATFORM}`);
+}
+
+/**
+ * Check whether the supervisor is installed and active.
+ *
+ * @returns {{ installed: boolean, active?: boolean, method?: string, file?: string }}
+ */
+export function supervisionStatus() {
+  if (PLATFORM === 'darwin') return { method: 'launchd', ...launchdStatus() };
+  if (PLATFORM === 'linux')  return { method: 'systemd', ...systemdStatus() };
+  if (PLATFORM === 'win32')  return { method: 'task-scheduler', ...windowsStatus() };
+  return { installed: false, method: 'unsupported' };
+}

package/lib/embed/target-resolver.mjs

@@ -0,0 +1,186 @@
+/**
+ * lib/embed/target-resolver.mjs — target discovery and routing for embed mode.
+ *
+ * Resolution order:
+ *   1. Explicit targets from config (targets[])
+ *   2. Provider-linked discovery (e.g., Jira issue references a GitHub repo)
+ *   3. Broadened search if nothing actionable matched
+ *   4. Workspace fallback (~/.construct/workspace) — always present
+ *
+ * Each resolved target is a normalized object:
+ *   { type, ref?, path?, access, provider?, docs? }
+ *
+ * access:
+ *   - 'local'   → filesystem path exists, read/write via fs
+ *   - 'remote'  → interact via provider API only
+ *   - 'hybrid'  → local clone exists AND remote provider available
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { DEFAULT_WORKSPACE_PATH, WORKSPACE_DOCS_LANES } from './config.mjs';
+
+/**
+ * Resolve all actionable targets for this embed cycle.
+ *
+ * @param {object} config           - Parsed embed config (from loadEmbedConfig/normalize)
+ * @param {object} providerRegistry - ProviderRegistry instance for remote lookups
+ * @param {object} [opts]
+ * @param {object[]} [opts.signals] - Signals from sources (issues, PRs, etc.) that may reference repos
+ * @returns {Promise<ResolvedTarget[]>}
+ */
+export async function resolveTargets(config, providerRegistry, opts = {}) {
+  const resolved = [];
+  const seen = new Set();
+
+  // Phase 1: Explicit targets from config
+  for (const t of config.targets ?? []) {
+    const rt = resolveExplicit(t);
+    const key = targetKey(rt);
+    if (!seen.has(key)) {
+      seen.add(key);
+      resolved.push(rt);
+    }
+  }
+
+  // Phase 2: Provider-linked discovery from source signals
+  if (opts.signals?.length) {
+    const discovered = discoverFromSignals(opts.signals, providerRegistry);
+    for (const rt of discovered) {
+      const key = targetKey(rt);
+      if (!seen.has(key)) {
+        seen.add(key);
+        resolved.push(rt);
+      }
+    }
+  }
+
+  // Phase 3: Ensure workspace fallback
+  const hasWorkspace = resolved.some((t) => t.type === 'workspace');
+  if (!hasWorkspace) {
+    resolved.push({
+      type: 'workspace',
+      path: DEFAULT_WORKSPACE_PATH,
+      access: 'local',
+      docs: WORKSPACE_DOCS_LANES,
+    });
+  }
+
+  return resolved;
+}
+
+/**
+ * Resolve a single explicit target config entry into a normalized target.
+ */
+function resolveExplicit(target) {
+  if (target.type === 'workspace') {
+    return {
+      type: 'workspace',
+      path: target.path ?? DEFAULT_WORKSPACE_PATH,
+      access: 'local',
+      docs: WORKSPACE_DOCS_LANES,
+    };
+  }
+
+  // type: repo
+  const hasLocal = target.path && fs.existsSync(target.path);
+  const hasRemote = !!target.ref;
+
+  let access = 'remote';
+  if (hasLocal && hasRemote) access = 'hybrid';
+  else if (hasLocal) access = 'local';
+
+  return {
+    type: target.type,
+    ref: target.ref ?? null,
+    path: hasLocal ? target.path : null,
+    access,
+    provider: target.provider ?? inferProvider(target.ref),
+    docs: target.docs ?? null,
+  };
+}
+
+/**
+ * Extract repo references from source signals (issues, PRs, commits that mention repos).
+ */
+function discoverFromSignals(signals, _providerRegistry) {
+  const discovered = [];
+  const repoPattern = /(?:github\.com|gitlab\.com)[/:]([A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+)/g;
+
+  for (const signal of signals) {
+    const text = signal.body ?? signal.description ?? signal.title ?? '';
+    let match;
+    while ((match = repoPattern.exec(text)) !== null) {
+      const ref = match[0].replace(/^(github\.com|gitlab\.com)[/:]/, '$1/');
+      discovered.push({
+        type: 'repo',
+        ref,
+        path: null,
+        access: 'remote',
+        provider: ref.startsWith('github') ? 'github' : 'gitlab',
+        docs: null,
+        discoveredFrom: signal.id ?? signal.url ?? 'signal',
+      });
+    }
+  }
+
+  return discovered;
+}
+
+/**
+ * Infer provider from a ref string.
+ */
+function inferProvider(ref) {
+  if (!ref) return null;
+  if (ref.includes('github.com') || ref.includes('github:')) return 'github';
+  if (ref.includes('gitlab.com') || ref.includes('gitlab:')) return 'gitlab';
+  if (ref.includes('bitbucket')) return 'bitbucket';
+  return null;
+}
+
+/**
+ * Deduplication key for a target.
+ */
+function targetKey(t) {
+  if (t.type === 'workspace') return 'workspace:' + (t.path ?? 'default');
+  return `${t.type}:${t.ref ?? ''}:${t.path ?? ''}`;
+}
+
+/**
+ * Given resolved targets and an artifact type, determine where to route output.
+ *
+ * Routing logic:
+ *   - If a target has a matching docs lane, route there
+ *   - If no specific target matches, route to workspace
+ *
+ * @param {ResolvedTarget[]} targets
+ * @param {string} artifactType - e.g. 'adrs', 'prds', 'memos', 'notes', 'intake'
+ * @returns {ResolvedTarget}
+ */
+export function routeArtifact(targets, artifactType) {
+  // Prefer non-workspace target with matching docs lane
+  for (const t of targets) {
+    if (t.type === 'workspace') continue;
+    if (t.access === 'local' || t.access === 'hybrid') {
+      // Local targets can receive docs directly
+      return t;
+    }
+  }
+
+  // Fall back to workspace
+  const workspace = targets.find((t) => t.type === 'workspace');
+  return workspace ?? { type: 'workspace', path: DEFAULT_WORKSPACE_PATH, access: 'local', docs: WORKSPACE_DOCS_LANES };
+}
+
+/**
+ * Resolve the filesystem path for writing an artifact to a target.
+ *
+ * @param {ResolvedTarget} target
+ * @param {string} artifactType - docs lane (adrs, prds, memos, notes, intake)
+ * @param {string} filename
+ * @returns {string} Absolute file path
+ */
+export function resolveArtifactPath(target, artifactType, filename) {
+  const base = target.path ?? DEFAULT_WORKSPACE_PATH;
+  return path.join(base, 'docs', artifactType, filename);
+}

package/lib/embed/worker.mjs

@@ -0,0 +1,62 @@
+#!/usr/bin/env node
+/**
+ * lib/embed/worker.mjs — Long-running embed daemon worker.
+ *
+ * Spawned detached by `construct embed start`. Runs until SIGTERM.
+ * Reads --config <path> from argv, or auto-discovers sources from config.env.
+ */
+
+import os from 'node:os';
+import path from 'node:path';
+import { loadConstructEnv } from '../env-config.mjs';
+import { EmbedDaemon } from './daemon.mjs';
+
+function parseArgv(argv) {
+  for (let i = 0; i < argv.length; i++) {
+    if (argv[i] === '--config' && argv[i + 1]) return argv[i + 1];
+  }
+  return null;
+}
+
+const configPath = parseArgv(process.argv.slice(2));
+const env = loadConstructEnv();
+
+// If no config file, build an auto-discovered config inline and inject it
+let daemonOpts = { env };
+if (configPath) {
+  daemonOpts.configPath = configPath;
+} else {
+  const { ProviderRegistry } = await import('./providers/registry.mjs');
+  const { EMPTY_CONFIG } = await import('./config.mjs');
+  const registry = await ProviderRegistry.fromEnv(env);
+  const sources = registry.autoSources(env);
+  daemonOpts.registry = registry;
+  daemonOpts.config = {
+    ...EMPTY_CONFIG,
+    sources,
+    // Default snapshot sink so operators always have a current markdown copy on disk.
+    outputs: [{ type: 'markdown', path: '.cx/snapshot.md' }],
+  };
+}
+
+const daemon = new EmbedDaemon(daemonOpts);
+
+process.on('SIGTERM', () => {
+  daemon.stop();
+  process.exit(0);
+});
+
+process.on('SIGINT', () => {
+  daemon.stop();
+  process.exit(0);
+});
+
+process.on('uncaughtException', (err) => {
+  process.stderr.write(`[embed/worker] uncaughtException: ${err.message}\n${err.stack}\n`);
+});
+
+process.on('unhandledRejection', (reason) => {
+  process.stderr.write(`[embed/worker] unhandledRejection: ${reason}\n`);
+});
+
+await daemon.start();