@geraldmaron/construct 1.0.0 → 1.0.1

package/lib/providers/github/index.mjs

@@ -0,0 +1,126 @@
+/**
+ * lib/providers/github/index.mjs — GitHub data-source provider.
+ *
+ * Capabilities: read, search, webhook.
+ *
+ * Auth: reads `GITHUB_TOKEN` (or `GH_TOKEN`) from env. Without a token,
+ * unauthenticated GitHub API rate limits apply (60 req/h/IP).
+ *
+ * Config (per call):
+ *   - repo:       "owner/name" — required for read
+ *   - query:      free-text search (issues, PRs, code) for search
+ *   - kind:       'issues' | 'prs' | 'code' (default 'issues')
+ *
+ * The provider is intentionally narrow in v1 — issue + PR + code search +
+ * a single repo metadata read. Webhook signature verification is in place
+ * so consumers can mount a receiver without re-implementing it.
+ */
+
+import crypto from 'node:crypto';
+
+const API = 'https://api.github.com';
+
+function authHeader(env) {
+  const token = env.GITHUB_TOKEN || env.GH_TOKEN;
+  return token ? { Authorization: `Bearer ${token}` } : {};
+}
+
+async function ghFetch(pathOrUrl, env, init = {}) {
+  const url = pathOrUrl.startsWith('http') ? pathOrUrl : `${API}${pathOrUrl}`;
+  const headers = {
+    'Accept': 'application/vnd.github+json',
+    'X-GitHub-Api-Version': '2022-11-28',
+    'User-Agent': 'construct-github-provider',
+    ...authHeader(env),
+    ...(init.headers || {}),
+  };
+  const res = await fetch(url, { ...init, headers });
+  if (!res.ok) {
+    const body = await res.text().catch(() => '');
+    const err = new Error(`GitHub ${res.status} ${res.statusText}: ${body.slice(0, 200)}`);
+    err.status = res.status;
+    err.rateLimitRemaining = Number(res.headers.get('x-ratelimit-remaining'));
+    throw err;
+  }
+  return res.json();
+}
+
+export function create({ env = process.env } = {}) {
+  return {
+    meta: {
+      id: 'github',
+      displayName: 'GitHub',
+      capabilities: ['read', 'search', 'webhook'],
+      description: 'Repos, issues, PRs, and code search.',
+    },
+
+    configSchema: {
+      $schema: 'https://json-schema.org/draft/2020-12/schema',
+      type: 'object',
+      properties: {
+        repo: { type: 'string', pattern: '^[^/]+/[^/]+$', description: 'owner/name' },
+        kind: { enum: ['issues', 'prs', 'code'], default: 'issues' },
+        query: { type: 'string' },
+        webhookSecret: { type: 'string', description: 'webhook signature secret' },
+      },
+    },
+
+    async health() {
+      try {
+        const r = await fetch(`${API}/rate_limit`, { headers: authHeader(env) });
+        if (!r.ok) return { ok: false, detail: `rate_limit endpoint ${r.status}` };
+        const data = await r.json();
+        const remaining = data?.resources?.core?.remaining;
+        return {
+          ok: true,
+          detail: `${data?.resources?.core?.limit || 0} req/h limit; ${remaining ?? 0} remaining`,
+          authenticated: !!(env.GITHUB_TOKEN || env.GH_TOKEN),
+        };
+      } catch (err) {
+        return { ok: false, detail: err.message };
+      }
+    },
+
+    async read(config) {
+      if (!config?.repo) throw new Error('github.read: config.repo required (owner/name)');
+      return ghFetch(`/repos/${config.repo}`, env);
+    },
+
+    async search(config) {
+      const kind = config?.kind || 'issues';
+      const query = config?.query;
+      if (!query) throw new Error('github.search: config.query required');
+      const path = kind === 'code'
+        ? `/search/code?q=${encodeURIComponent(query)}`
+        : kind === 'prs'
+          ? `/search/issues?q=${encodeURIComponent(query + ' is:pr')}`
+          : `/search/issues?q=${encodeURIComponent(query + ' is:issue')}`;
+      const data = await ghFetch(path, env);
+      return Array.isArray(data?.items) ? data.items : [];
+    },
+
+    async webhook(config, request) {
+      const secret = config?.webhookSecret;
+      if (!secret) {
+        return { ok: false, error: 'webhookSecret not configured' };
+      }
+      const signature = request?.headers?.['x-hub-signature-256'];
+      if (!signature || !signature.startsWith('sha256=')) {
+        return { ok: false, error: 'missing or malformed signature header' };
+      }
+      const expected = 'sha256=' + crypto
+        .createHmac('sha256', secret)
+        .update(typeof request.body === 'string' ? request.body : Buffer.from(request.body))
+        .digest('hex');
+      const valid = crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
+      if (!valid) return { ok: false, error: 'signature mismatch' };
+      return {
+        ok: true,
+        event: request?.headers?.['x-github-event'] || 'unknown',
+        delivery: request?.headers?.['x-github-delivery'] || null,
+      };
+    },
+  };
+}
+
+export default create;

package/lib/providers/registry.mjs

@@ -0,0 +1,184 @@
+/**
+ * lib/providers/registry.mjs — provider resolution + lifecycle.
+ *
+ * Resolution order (last-write wins):
+ *
+ *   1. Built-in factories under `lib/providers/<id>/index.mjs` (loaded lazily).
+ *   2. Operator overrides at `~/.construct/providers.json`:
+ *        { "providers": [{ "id": "...", "package": "...", "options": {} }] }
+ *   3. Project overrides at `<projectRoot>/.cx/providers.json` (same shape).
+ *
+ * Built-in providers ship with the package. Plugin providers are arbitrary
+ * npm modules (or local paths) that export the contract. The registry runs
+ * `assertProviderContract` against every loaded provider before returning
+ * it, so a misconfigured plugin produces a clear error rather than a runtime
+ * surprise inside core code.
+ *
+ * Provider config (auth tokens, default queries, allowlists) is layered:
+ * `~/.construct/config.env` for credentials, `<projectRoot>/.cx/providers.yaml`
+ * for non-secret per-project settings. The YAML file references env vars
+ * by name so secrets never land in source control.
+ */
+
+import { readFileSync, existsSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join, isAbsolute, resolve, dirname } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { assertProviderContract } from './contract.mjs';
+import { getBreaker } from './circuit-breaker.mjs';
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+
+export const BUILT_INS = ['github', 'atlassian-jira', 'atlassian-confluence', 'slack', 'salesforce'];
+
+function readJsonIfExists(path) {
+  try {
+    if (!existsSync(path)) return null;
+    return JSON.parse(readFileSync(path, 'utf8'));
+  } catch { return null; }
+}
+
+async function loadFactoryFromPackage(pkg, rootDir) {
+  if (!pkg || typeof pkg !== 'string') {
+    throw new Error('provider plugin package must be a non-empty string');
+  }
+  if (pkg.startsWith('github:')) {
+    throw new Error(
+      `github: plugin spec '${pkg}' is not auto-installed. ` +
+      `Install via 'npm install ${pkg}' first, then reference by package name.`
+    );
+  }
+  if (isAbsolute(pkg) || pkg.startsWith('./') || pkg.startsWith('../')) {
+    const abs = isAbsolute(pkg) ? pkg : resolve(rootDir, pkg);
+    return import(pathToFileURL(abs).href);
+  }
+  return import(pkg);
+}
+
+async function loadBuiltIn(id) {
+  const candidate = join(HERE, id, 'index.mjs');
+  if (!existsSync(candidate)) return null;
+  return import(pathToFileURL(candidate).href);
+}
+
+// Wrap every async I/O method on a provider with its per-id circuit breaker
+// so a downed remote system fails fast for the cooldown window instead of
+// blocking every caller on the same broken backend. `health` is intentionally
+// not wrapped — it's the probe consumers use to surface the breaker's state.
+const BREAKER_METHODS = ['read', 'search', 'watch', 'write', 'webhook'];
+
+function wrapWithBreaker(provider) {
+  const breaker = getBreaker(`provider:${provider.meta.id}`, {
+    failureThreshold: 5,
+    cooldownMs: 30_000,
+  });
+  for (const method of BREAKER_METHODS) {
+    if (typeof provider[method] !== 'function') continue;
+    const original = provider[method].bind(provider);
+    provider[method] = (...args) => breaker.run(original, ...args);
+  }
+  return provider;
+}
+
+async function instantiate(mod, options) {
+  const factory = mod?.create || mod?.default;
+  if (typeof factory !== 'function') {
+    throw new Error(`provider module must export a 'create' or default factory`);
+  }
+  const instance = await factory(options || {});
+  assertProviderContract(instance);
+  return wrapWithBreaker(instance);
+}
+
+function gatherOverrides(rootDir) {
+  const out = [];
+  const userConfig = readJsonIfExists(join(homedir(), '.construct', 'providers.json'));
+  if (userConfig?.providers) out.push(...userConfig.providers);
+  const projectConfig = readJsonIfExists(join(rootDir, '.cx', 'providers.json'));
+  if (projectConfig?.providers) out.push(...projectConfig.providers);
+  return out;
+}
+
+/**
+ * Resolve every provider Construct should know about. Returns:
+ *
+ *   { providers: { [id]: instance }, errors: [...], sources: { [id]: 'built-in'|'plugin:<pkg>' } }
+ */
+export async function resolveProviders({ rootDir = process.cwd(), env = process.env } = {}) {
+  const providers = {};
+  const sources = {};
+  const errors = [];
+
+  for (const id of BUILT_INS) {
+    try {
+      const mod = await loadBuiltIn(id);
+      if (!mod) continue;
+      const instance = await instantiate(mod, { env });
+      providers[id] = instance;
+      sources[id] = 'built-in';
+    } catch (err) {
+      errors.push({ id, source: 'built-in', error: err.message });
+    }
+  }
+
+  for (const entry of gatherOverrides(rootDir)) {
+    const id = entry?.id;
+    const pkg = entry?.package;
+    if (!id || !pkg) {
+      errors.push({ id: id || '(unknown)', source: 'override', error: 'override entry must have id and package' });
+      continue;
+    }
+    try {
+      const mod = await loadFactoryFromPackage(pkg, rootDir);
+      const instance = await instantiate(mod, { env, ...(entry.options || {}) });
+      if (instance.meta.id !== id) {
+        errors.push({ id, source: pkg, error: `meta.id is '${instance.meta.id}' but override declared id='${id}'` });
+        continue;
+      }
+      providers[id] = instance;
+      sources[id] = `plugin:${pkg}`;
+    } catch (err) {
+      errors.push({ id, source: pkg, error: err.message });
+    }
+  }
+
+  return { providers, sources, errors };
+}
+
+export async function describeProviders({ rootDir = process.cwd(), env = process.env } = {}) {
+  const { providers, sources, errors } = await resolveProviders({ rootDir, env });
+  const summary = await Promise.all(
+    Object.entries(providers).map(async ([id, p]) => {
+      let health = { ok: false, detail: 'health probe not invoked' };
+      try { health = await p.health({}); } catch (err) { health = { ok: false, detail: err.message }; }
+      return {
+        id,
+        displayName: p.meta.displayName,
+        description: p.meta.description || null,
+        capabilities: [...p.meta.capabilities],
+        source: sources[id],
+        health,
+      };
+    })
+  );
+  return { summary, errors };
+}
+
+// Standalone validation for a candidate override entry: imports the package
+// and runs the contract check without touching the on-disk overrides. Lets
+// callers (e.g. dashboard write endpoint) verify before persisting.
+
+export async function validateProviderEntry({ id, package: pkg, options = {} }, { rootDir = process.cwd(), env = process.env } = {}) {
+  if (!id || typeof id !== 'string') return { ok: false, error: 'id required' };
+  if (!pkg || typeof pkg !== 'string') return { ok: false, error: 'package required' };
+  try {
+    const mod = await loadFactoryFromPackage(pkg, rootDir);
+    const instance = await instantiate(mod, { env, ...options });
+    if (instance.meta.id !== id) {
+      return { ok: false, error: `meta.id is '${instance.meta.id}' but entry declared id='${id}'` };
+    }
+    return { ok: true };
+  } catch (err) {
+    return { ok: false, error: err.message };
+  }
+}

package/lib/providers/salesforce/index.mjs

@@ -0,0 +1,100 @@
+/**
+ * lib/providers/salesforce/index.mjs — Salesforce data-source provider.
+ *
+ * Capabilities: search, read.
+ *
+ * Auth: OAuth password flow via env:
+ *   SALESFORCE_INSTANCE_URL  e.g. https://yourorg.my.salesforce.com
+ *   SALESFORCE_ACCESS_TOKEN  bearer token (operator obtains via sfdx or OAuth flow)
+ *
+ * Config (per call):
+ *   - soql:     SOQL query string
+ *   - sobject:  object type (Account|Opportunity|Contact|Custom__c) for read
+ *   - id:       record id for read
+ *
+ * The provider intentionally avoids embedding an OAuth flow itself —
+ * operators are expected to supply an access token. A future enhancement
+ * can land an interactive OAuth flow with refresh-token persistence.
+ */
+
+const API_VERSION = 'v60.0';
+
+function authConfig(env) {
+  const instanceUrl = (env.SALESFORCE_INSTANCE_URL || '').replace(/\/$/, '');
+  const accessToken = env.SALESFORCE_ACCESS_TOKEN || '';
+  return { instanceUrl, accessToken, ok: Boolean(instanceUrl && accessToken) };
+}
+
+async function sfFetch(path, env, init = {}) {
+  const auth = authConfig(env);
+  if (!auth.ok) throw new Error('salesforce: SALESFORCE_INSTANCE_URL and SALESFORCE_ACCESS_TOKEN required');
+  const res = await fetch(`${auth.instanceUrl}${path}`, {
+    ...init,
+    headers: {
+      'Accept': 'application/json',
+      'Content-Type': 'application/json',
+      Authorization: `Bearer ${auth.accessToken}`,
+      ...(init.headers || {}),
+    },
+  });
+  if (!res.ok) {
+    const body = await res.text().catch(() => '');
+    throw new Error(`Salesforce ${res.status} ${res.statusText}: ${body.slice(0, 200)}`);
+  }
+  return res.json();
+}
+
+export function create({ env = process.env } = {}) {
+  return {
+    meta: {
+      id: 'salesforce',
+      displayName: 'Salesforce',
+      capabilities: ['read', 'search'],
+      description: 'Accounts, opportunities, custom objects, SOQL.',
+    },
+
+    configSchema: {
+      $schema: 'https://json-schema.org/draft/2020-12/schema',
+      type: 'object',
+      properties: {
+        soql: { type: 'string' },
+        sobject: { type: 'string' },
+        id: { type: 'string', pattern: '^[a-zA-Z0-9]{15,18}$' },
+      },
+    },
+
+    async health() {
+      const auth = authConfig(env);
+      if (!auth.ok) {
+        return { ok: false, detail: 'SALESFORCE_INSTANCE_URL / SALESFORCE_ACCESS_TOKEN not set' };
+      }
+      try {
+        await sfFetch(`/services/data/${API_VERSION}/`, env);
+        return { ok: true, detail: `connected to ${auth.instanceUrl}` };
+      } catch (err) {
+        return { ok: false, detail: err.message };
+      }
+    },
+
+    async read(config) {
+      if (!config?.sobject || !config?.id) {
+        throw new Error('salesforce.read: config.sobject and config.id required');
+      }
+      return sfFetch(
+        `/services/data/${API_VERSION}/sobjects/${encodeURIComponent(config.sobject)}/${encodeURIComponent(config.id)}`,
+        env
+      );
+    },
+
+    async search(config) {
+      if (!config?.soql) throw new Error('salesforce.search: config.soql required');
+      const data = await sfFetch(
+        `/services/data/${API_VERSION}/query?q=${encodeURIComponent(config.soql)}`,
+        env
+      );
+      return Array.isArray(data?.records) ? data.records : [];
+    },
+  };
+}
+
+export default create;

package/lib/providers/slack/index.mjs

@@ -0,0 +1,80 @@
+/**
+ * lib/providers/slack/index.mjs — Slack data-source provider.
+ *
+ * Capabilities: read, search.
+ *
+ * Auth: `SLACK_BOT_TOKEN` (xoxb-...) or `SLACK_USER_TOKEN` (xoxp-...) from env.
+ *
+ * Config (per call):
+ *   - channel:  channel id or name (#engineering or C0123)
+ *   - query:    free-text search.messages query
+ *   - count:    integer (default 20, max 100)
+ */
+
+const API = 'https://slack.com/api';
+const DEFAULT_COUNT = 20;
+const HARD_COUNT = 100;
+
+function token(env) {
+  return env.SLACK_BOT_TOKEN || env.SLACK_USER_TOKEN || '';
+}
+
+async function slackFetch(method, env, params = {}) {
+  const tok = token(env);
+  if (!tok) throw new Error('slack: SLACK_BOT_TOKEN or SLACK_USER_TOKEN required');
+  const url = new URL(`${API}/${method}`);
+  for (const [k, v] of Object.entries(params)) url.searchParams.set(k, String(v));
+  const res = await fetch(url, { headers: { Authorization: `Bearer ${tok}` } });
+  if (!res.ok) throw new Error(`slack ${res.status} ${res.statusText}`);
+  const data = await res.json();
+  if (!data.ok) throw new Error(`slack api error: ${data.error || 'unknown'}`);
+  return data;
+}
+
+export function create({ env = process.env } = {}) {
+  return {
+    meta: {
+      id: 'slack',
+      displayName: 'Slack',
+      capabilities: ['read', 'search'],
+      description: 'Channel messages, threads, search.',
+    },
+
+    configSchema: {
+      $schema: 'https://json-schema.org/draft/2020-12/schema',
+      type: 'object',
+      properties: {
+        channel: { type: 'string' },
+        query: { type: 'string' },
+        count: { type: 'integer', minimum: 1, maximum: HARD_COUNT, default: DEFAULT_COUNT },
+      },
+    },
+
+    async health() {
+      const tok = token(env);
+      if (!tok) return { ok: false, detail: 'SLACK_BOT_TOKEN or SLACK_USER_TOKEN not set' };
+      try {
+        const data = await slackFetch('auth.test', env);
+        return { ok: true, detail: `team=${data.team || '?'} user=${data.user || '?'}` };
+      } catch (err) {
+        return { ok: false, detail: err.message };
+      }
+    },
+
+    async read(config) {
+      if (!config?.channel) throw new Error('slack.read: config.channel required');
+      const limit = Math.min(config?.count || DEFAULT_COUNT, HARD_COUNT);
+      const data = await slackFetch('conversations.history', env, { channel: config.channel, limit });
+      return data.messages || [];
+    },
+
+    async search(config) {
+      if (!config?.query) throw new Error('slack.search: config.query required');
+      const count = Math.min(config?.count || DEFAULT_COUNT, HARD_COUNT);
+      const data = await slackFetch('search.messages', env, { query: config.query, count });
+      return data.messages?.matches || [];
+    },
+  };
+}
+
+export default create;

package/lib/reflect.mjs

@@ -0,0 +1,137 @@
+/**
+ * lib/reflect.mjs — construct reflect command implementation.
+ *
+ * Captures improvement feedback from chat sessions and updates Construct core
+ * knowledge base with actionable insights for continuous self-improvement.
+ */
+
+import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { addObservation } from './observation-store.mjs';
+import { loadConstructEnv } from './env-config.mjs';
+import { KNOWLEDGE_ROOT, KNOWLEDGE_SUBDIRS, inferKnowledgeTarget } from './knowledge/layout.mjs';
+
+const HOME = process.env.HOME || process.env.USERPROFILE;
+const USER_ENV_PATH = join(HOME, '.construct', 'config.env');
+
+/**
+ * Main reflect command handler.
+ * @param {string[]} args - Command line arguments
+ */
+export async function runReflectCli(args) {
+  // Parse arguments
+  let target = 'internal';
+  let summary = '';
+
+  for (const arg of args) {
+    if (arg.startsWith('--target=')) {
+      target = arg.split('=')[1];
+    } else if (arg.startsWith('--summary=')) {
+      summary = arg.split('=')[1];
+    }
+  }
+
+  // Validate target
+  const validTargets = KNOWLEDGE_SUBDIRS.map(s => `knowledge/${s}`);
+  const validShorthandTargets = KNOWLEDGE_SUBDIRS; // internal, external, etc.
+  const isValidTarget = validTargets.includes(target) || validShorthandTargets.includes(target);
+  if (!isValidTarget) {
+    console.error(`Error: Invalid target '${target}'. Valid targets: ${validTargets.join(', ')}`);
+    process.exit(1);
+  }
+  
+  // Normalize target to full format if shorthand was provided
+  if (validShorthandTargets.includes(target) && !target.startsWith('knowledge/')) {
+    target = `knowledge/${target}`;
+  }
+
+  // If no summary provided, try to get it from stdin or prompt
+  if (!summary) {
+    // For now, we'll require explicit summary - in future could read from chat context
+    console.error('Error: --summary=<text> is required to capture improvement feedback');
+    console.error('Example: construct reflect --target=internal --summary="Improve Slack channel intent parsing to handle edge cases"');
+    process.exit(1);
+  }
+
+  // Resolve the knowledge directory for this target
+  const knowledgeSubdir = target.replace('knowledge/', '');
+  const knowledgeDir = join(process.cwd(), KNOWLEDGE_ROOT, knowledgeSubdir);
+  
+  // Ensure the knowledge directory exists
+  if (!existsSync(knowledgeDir)) {
+    mkdirSync(knowledgeDir, { recursive: true });
+  }
+
+  // Generate a filename based on timestamp and summary hash
+  const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
+  const summarySlug = summary
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-|-$/g, '')
+    .slice(0, 50);
+  const filename = `${timestamp}-${summarySlug}.md`;
+  const filePath = join(knowledgeDir, filename);
+
+  // Create the markdown content
+  const content = [
+    '---',
+    `source_path: reflect-command`,
+    `source_relative_path: ${filename}`,
+    `source_extension: .md`,
+    `extracted_at: ${new Date().toISOString()}`,
+    `extraction_method: reflect-command`,
+    `characters: ${summary.length}`,
+    `truncated: false`,
+    `output_path: ${JSON.stringify(filePath)}`,
+    `output_relative_path: ${JSON.stringify(filename)}`,
+    '---',
+    '',
+    `# Improvement Feedback`,
+    '',
+    summary,
+    '',
+    '## Context',
+    '',
+    `- Captured via: construct reflect`,
+    `- Timestamp: ${new Date().toISOString()}`,
+    `- Target knowledge directory: ${knowledgeSubdir}/`,
+    '',
+    '## Action Items',
+    '',
+    '- [ ] Review this feedback for validity and actionability',
+    '- [ ] Determine if this requires code changes, documentation updates, or process improvements',
+    '- [ ] If actionable, create appropriate issues in the tracker',
+    '- [ ] Update relevant documentation or code based on this insight',
+    '',
+  ].join('\n');
+
+  // Write the file
+  writeFileSync(filePath, content);
+
+  // Record an observation about this feedback
+  const observationSummary = `[reflect] Improvement feedback captured: ${summary.slice(0, 100)}${summary.length > 100 ? '...' : ''}`;
+  addObservation(process.cwd(), {
+    role: 'construct',
+    category: 'insight', // Feedback is typically an insight unless it's about a problem
+    summary: observationSummary,
+    content: `Feedback captured via construct reflect:\n\n${summary}\n\nStored as: ${filePath}\nTarget: ${knowledgeSubdir}/`,
+    tags: ['reflect', 'improvement-feedback', `knowledge:${knowledgeSubdir}`],
+    confidence: 0.9,
+    source: 'reflect-command',
+  });
+
+  console.log(`✓ Improvement feedback captured and stored as: ${filePath}`);
+  console.log(`  Target knowledge directory: ${knowledgeSubdir}/`);
+  console.log(`  Use 'construct ingest --target=${target} <file>' to manually add similar feedback in the future`);
+}
+
+/**
+ * CLI entry point for direct execution.
+ */
+if (import.meta.url === `file://${process.argv[1]}`) {
+  const args = process.argv.slice(2);
+  runReflectCli(args).catch((err) => {
+    console.error(`Error: ${err.message}`);
+    process.exit(1);
+  });
+}