@geraldmaron/construct 1.1.1 → 1.2.1

package/lib/providers/contract/adapters/slack/index.mjs

@@ -0,0 +1,175 @@
+/**
+ * providers/slack/index.mjs — Slack provider.
+ *
+ * Transport: Slack Web API (direct fetch, no SDK).
+ * Auth: Bot token via SLACK_BOT_TOKEN env var, or config.token.
+ *
+ * Capabilities: read, write, watch
+ *
+ * read refs:
+ *   "channels"                     → list of public channels the bot is in
+ *   "channel:<id>:messages"        → recent messages in a channel (default 20)
+ *   "channel:<id>:messages:<n>"    → last n messages
+ *   "thread:<channel>:<ts>"        → thread replies
+ *   "user:<id>"                    → user profile
+ *
+ * write items:
+ *   { type: 'message', channel, text, thread_ts? }   → post a message
+ *   { type: 'reaction', channel, timestamp, emoji }  → add a reaction
+ *
+ * watch: poll a channel for new messages since last seen timestamp
+ *   watch({ channel, since? }, callback) → returns unsubscribe fn
+ */
+
+import { AuthError, NotFoundError, RateLimitError } from '../../errors.mjs';
+
+const SLACK_API = 'https://slack.com/api';
+
+export default {
+  name: 'slack',
+  capabilities: ['read', 'write', 'watch'],
+
+  _token: null,
+  _pollIntervals: new Map(),
+
+  async init(config = {}) {
+    const token = config.token ?? process.env.SLACK_BOT_TOKEN;
+    if (!token) {
+      throw new AuthError(
+        'Slack provider requires SLACK_BOT_TOKEN or config.token',
+        { provider: 'slack' },
+      );
+    }
+    this._token = token;
+    const res = await this._call('auth.test', {});
+    if (!res.ok) {
+      throw new AuthError(`Slack auth failed: ${res.error}`, { provider: 'slack' });
+    }
+  },
+
+  async _call(method, params) {
+    const url = `${SLACK_API}/${method}`;
+    const res = await fetch(url, {
+      method: 'POST',
+      headers: {
+        Authorization: `Bearer ${this._token}`,
+        'Content-Type': 'application/json; charset=utf-8',
+      },
+      body: JSON.stringify(params),
+    });
+    if (res.status === 429) {
+      const retryAfter = parseInt(res.headers.get('Retry-After') ?? '30', 10);
+      throw new RateLimitError('Slack rate limit hit', { provider: 'slack', retryAfter });
+    }
+    return res.json();
+  },
+
+  async read(ref, _opts = {}) {
+    if (ref === 'channels') {
+      const data = await this._call('conversations.list', { types: 'public_channel,private_channel', limit: 200 });
+      if (!data.ok) throw new Error(`Slack error: ${data.error}`);
+      return (data.channels ?? []).map((c) => ({
+        type: 'channel',
+        id: c.id,
+        name: c.name,
+        isPrivate: c.is_private,
+        memberCount: c.num_members,
+      }));
+    }
+
+    const channelMsgMatch = ref.match(/^channel:([^:]+):messages(?::(\d+))?$/);
+    if (channelMsgMatch) {
+      const channel = channelMsgMatch[1];
+      const limit = parseInt(channelMsgMatch[2] ?? '20', 10);
+      const data = await this._call('conversations.history', { channel, limit });
+      if (!data.ok) {
+        if (data.error === 'channel_not_found') throw new NotFoundError(`Channel not found: ${channel}`, { provider: 'slack' });
+        throw new Error(`Slack error: ${data.error}`);
+      }
+      return (data.messages ?? []).map(normalizeMessage);
+    }
+
+    const threadMatch = ref.match(/^thread:([^:]+):(.+)$/);
+    if (threadMatch) {
+      const [, channel, ts] = threadMatch;
+      const data = await this._call('conversations.replies', { channel, ts });
+      if (!data.ok) throw new Error(`Slack error: ${data.error}`);
+      return (data.messages ?? []).map(normalizeMessage);
+    }
+
+    if (ref.startsWith('user:')) {
+      const userId = ref.slice(5);
+      const data = await this._call('users.info', { user: userId });
+      if (!data.ok) {
+        if (data.error === 'user_not_found') throw new NotFoundError(`User not found: ${userId}`, { provider: 'slack' });
+        throw new Error(`Slack error: ${data.error}`);
+      }
+      const u = data.user;
+      return [{ type: 'user', id: u.id, name: u.name, realName: u.real_name, email: u.profile?.email }];
+    }
+
+    throw new NotFoundError(`Unknown Slack read ref: "${ref}"`, { provider: 'slack' });
+  },
+
+  async write(item) {
+    if (item.type === 'message') {
+      const params = { channel: item.channel, text: item.text };
+      if (item.thread_ts) params.thread_ts = item.thread_ts;
+      if (item.blocks) params.blocks = item.blocks;
+      const data = await this._call('chat.postMessage', params);
+      if (!data.ok) throw new Error(`Slack error: ${data.error}`);
+      return { type: 'message-posted', ts: data.ts, channel: data.channel };
+    }
+
+    if (item.type === 'reaction') {
+      const data = await this._call('reactions.add', {
+        channel: item.channel,
+        timestamp: item.timestamp,
+        name: item.emoji,
+      });
+      if (!data.ok && data.error !== 'already_reacted') throw new Error(`Slack error: ${data.error}`);
+      return { type: 'reaction-added', emoji: item.emoji };
+    }
+
+    throw new Error(`Unknown Slack write item type: "${item.type}"`);
+  },
+
+  watch(filter, callback) {
+    const channel = filter.channel;
+    let since = filter.since ?? String(Date.now() / 1000 - 60);
+    const intervalMs = filter.intervalMs ?? 15000;
+
+    const id = setInterval(async () => {
+      try {
+        const data = await this._call('conversations.history', {
+          channel,
+          oldest: since,
+          limit: 50,
+        });
+        if (!data.ok) return;
+        const messages = (data.messages ?? []).filter((m) => m.ts > since);
+        if (messages.length) {
+          since = messages[0].ts; // Slack returns newest first
+          for (const msg of messages.reverse()) callback(normalizeMessage(msg));
+        }
+      } catch { /* swallow poll errors — network blip shouldn't kill the watcher */ }
+    }, intervalMs);
+
+    this._pollIntervals.set(id, true);
+    return () => {
+      clearInterval(id);
+      this._pollIntervals.delete(id);
+    };
+  },
+};
+
+function normalizeMessage(m) {
+  return {
+    type: 'message',
+    ts: m.ts,
+    user: m.user ?? m.bot_id,
+    text: m.text,
+    threadTs: m.thread_ts ?? null,
+    replyCount: m.reply_count ?? 0,
+  };
+}

package/lib/providers/contract/contract-tests.mjs

@@ -0,0 +1,57 @@
+/**
+ * providers/lib/contract-tests.mjs — shared contract tests for any provider.
+ *
+ * Import and call runContractTests(provider) from a provider's own test file.
+ * Uses node:test + node:assert — zero external deps.
+ */
+
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { validate, hasCapability, CAPABILITIES } from './interface.mjs';
+import { CapabilityNotSupported } from './errors.mjs';
+
+/**
+ * Run the standard contract test suite against a provider instance.
+ * Call this from your provider's test file:
+ *
+ *   import { runContractTests } from '../../lib/providers/contract/contract-tests.mjs';
+ *   import provider from './index.mjs';
+ *   runContractTests(provider);
+ */
+export function runContractTests(provider) {
+  describe(`Provider contract: ${provider?.name ?? 'unnamed'}`, () => {
+    it('passes interface validation', () => {
+      const result = validate(provider);
+      assert.ok(result.valid, `Validation errors: ${result.errors.join('; ')}`);
+    });
+
+    it('has a non-empty string name', () => {
+      assert.ok(typeof provider.name === 'string' && provider.name.length > 0);
+    });
+
+    it('declares capabilities as an array of known values', () => {
+      assert.ok(Array.isArray(provider.capabilities));
+      for (const cap of provider.capabilities) {
+        assert.ok(CAPABILITIES.includes(cap), `Unknown capability: ${cap}`);
+      }
+    });
+
+    it('implements a function for each declared capability', () => {
+      for (const cap of provider.capabilities) {
+        assert.equal(typeof provider[cap], 'function', `Missing function for capability "${cap}"`);
+      }
+    });
+
+    it('implements init as a function', () => {
+      assert.equal(typeof provider.init, 'function');
+    });
+
+    for (const cap of CAPABILITIES) {
+      if (provider && Array.isArray(provider.capabilities) && !provider.capabilities.includes(cap)) {
+        it(`does not claim unsupported capability "${cap}"`, () => {
+          assert.ok(!hasCapability(provider, cap));
+        });
+      }
+    }
+  });
+}

package/lib/providers/contract/errors.mjs

@@ -0,0 +1,48 @@
+/**
+ * providers/lib/errors.mjs — typed error hierarchy for providers.
+ *
+ * Core catches these by type to decide retry, fallback, or user-facing messaging.
+ */
+
+export class ProviderError extends Error {
+  constructor(message, { provider, capability, code, cause } = {}) {
+    super(message, { cause });
+    this.name = 'ProviderError';
+    this.provider = provider;
+    this.capability = capability;
+    this.code = code;
+  }
+}
+
+export class CapabilityNotSupported extends ProviderError {
+  constructor(provider, capability) {
+    super(`Provider "${provider}" does not support capability "${capability}"`, {
+      provider,
+      capability,
+      code: 'CAPABILITY_NOT_SUPPORTED',
+    });
+    this.name = 'CapabilityNotSupported';
+  }
+}
+
+export class AuthError extends ProviderError {
+  constructor(message, opts = {}) {
+    super(message, { ...opts, code: 'AUTH_ERROR' });
+    this.name = 'AuthError';
+  }
+}
+
+export class RateLimitError extends ProviderError {
+  constructor(message, { retryAfter, ...opts } = {}) {
+    super(message, { ...opts, code: 'RATE_LIMIT' });
+    this.name = 'RateLimitError';
+    this.retryAfter = retryAfter;
+  }
+}
+
+export class NotFoundError extends ProviderError {
+  constructor(message, opts = {}) {
+    super(message, { ...opts, code: 'NOT_FOUND' });
+    this.name = 'NotFoundError';
+  }
+}

package/lib/providers/contract/interface.mjs

@@ -0,0 +1,50 @@
+/**
+ * providers/lib/interface.mjs — abstract provider interface and validation.
+ *
+ * Every provider must export an object matching this shape. The validate()
+ * function checks a provider at registration time; capability dispatch
+ * uses hasCapability() before calling.
+ */
+
+const CAPABILITIES = ['read', 'write', 'search', 'watch', 'webhook'];
+
+/**
+ * Validate a provider object against the interface contract.
+ * Returns { valid: boolean, errors: string[] }.
+ */
+export function validate(provider) {
+  const errors = [];
+
+  if (!provider || typeof provider !== 'object') {
+    return { valid: false, errors: ['Provider must be a non-null object'] };
+  }
+  if (typeof provider.name !== 'string' || !provider.name) {
+    errors.push('Provider must have a non-empty string "name"');
+  }
+  if (!Array.isArray(provider.capabilities)) {
+    errors.push('Provider must declare "capabilities" as an array');
+  } else {
+    for (const cap of provider.capabilities) {
+      if (!CAPABILITIES.includes(cap)) {
+        errors.push(`Unknown capability "${cap}". Valid: ${CAPABILITIES.join(', ')}`);
+      }
+      if (typeof provider[cap] !== 'function') {
+        errors.push(`Provider declares capability "${cap}" but does not implement it as a function`);
+      }
+    }
+  }
+  if (typeof provider.init !== 'function') {
+    errors.push('Provider must implement init(config)');
+  }
+
+  return { valid: errors.length === 0, errors };
+}
+
+/**
+ * Check if a provider supports a given capability.
+ */
+export function hasCapability(provider, capability) {
+  return Array.isArray(provider.capabilities) && provider.capabilities.includes(capability);
+}
+
+export { CAPABILITIES };

package/lib/providers/contract/registry.mjs

@@ -0,0 +1,102 @@
+/**
+ * providers/lib/registry.mjs — load and manage provider instances.
+ *
+ * Reads provider config from .cx/providers.yaml (or programmatic config),
+ * validates each provider against the interface contract, and provides
+ * a dispatch surface for core.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { validate, hasCapability } from './interface.mjs';
+import { CapabilityNotSupported } from './errors.mjs';
+
+/**
+ * In-memory provider registry.
+ */
+export class ProviderRegistry {
+  #providers = new Map();
+
+  /**
+   * Register a provider instance. Validates against the interface contract.
+   * Throws if validation fails.
+   */
+  register(provider) {
+    const result = validate(provider);
+    if (!result.valid) {
+      throw new Error(`Invalid provider "${provider?.name ?? '(unnamed)'}": ${result.errors.join('; ')}`);
+    }
+    this.#providers.set(provider.name, provider);
+  }
+
+  /**
+   * Get a registered provider by name.
+   */
+  get(name) {
+    return this.#providers.get(name) ?? null;
+  }
+
+  /**
+   * List all registered provider names.
+   */
+  list() {
+    return [...this.#providers.keys()];
+  }
+
+  /**
+   * List providers that support a given capability.
+   */
+  withCapability(capability) {
+    return [...this.#providers.values()].filter((p) => hasCapability(p, capability));
+  }
+
+  /**
+   * Dispatch a capability call to a named provider.
+   * Throws CapabilityNotSupported if the provider doesn't implement it.
+   */
+  async dispatch(providerName, capability, ...args) {
+    const provider = this.#providers.get(providerName);
+    if (!provider) {
+      throw new Error(`Provider "${providerName}" not registered`);
+    }
+    if (!hasCapability(provider, capability)) {
+      throw new CapabilityNotSupported(providerName, capability);
+    }
+    return provider[capability](...args);
+  }
+
+  /**
+   * Initialize all registered providers with their configs.
+   */
+  async initAll(configs = {}) {
+    const results = [];
+    for (const [name, provider] of this.#providers) {
+      try {
+        await provider.init(configs[name] ?? {});
+        results.push({ name, status: 'ready' });
+      } catch (err) {
+        results.push({ name, status: 'error', error: err.message });
+      }
+    }
+    return results;
+  }
+}
+
+/**
+ * Load provider config from a YAML file.
+ * Returns parsed config or null if file doesn't exist.
+ * Note: requires a YAML parser — deferred to avoid adding deps to provider lib.
+ * For now, returns raw file content for the caller to parse.
+ */
+export function loadProviderConfigFile(projectRoot) {
+  const candidates = [
+    path.join(projectRoot, '.cx', 'providers.yaml'),
+    path.join(projectRoot, '.cx', 'providers.yml'),
+  ];
+  for (const candidate of candidates) {
+    if (fs.existsSync(candidate)) {
+      return { path: candidate, raw: fs.readFileSync(candidate, 'utf8') };
+    }
+  }
+  return null;
+}