@agentprojectcontext/apx 1.59.0 → 1.60.0

package/src/core/integrations/store.js

@@ -0,0 +1,118 @@
+// IntegrationStore: CRUD over one project's integrations.json, plus the
+// cross-scope resolution used by agent tools. Pure filesystem + data logic —
+// no Express, no plugin HTTP calls (those live in ./plugins/*). This keeps the
+// storage layer testable in isolation (see tests/integrations.test.js).
+import {
+  readIntegrations,
+  writeIntegrations,
+  defaultIntegrationsStorage,
+} from "./sources.js";
+
+// Keys inside `config` that hold secrets — never sent to the web UI in clear.
+const SECRET_KEYS = new Set([
+  "personal_access_token",
+  "token",
+  "api_key",
+  "client_secret",
+]);
+
+// Return a shallow copy of a record with secret config values masked, safe to
+// send to the browser. A present secret becomes `true` under `config.<key>_set`
+// so the UI can show "configured" without leaking the value.
+export function redactRecord(record) {
+  if (!record) return record;
+  const config = { ...(record.config || {}) };
+  for (const key of Object.keys(config)) {
+    if (SECRET_KEYS.has(key)) {
+      const hasValue = typeof config[key] === "string" && config[key].length > 0;
+      delete config[key];
+      config[`${key}_set`] = hasValue;
+    }
+  }
+  return { ...record, config };
+}
+
+export class IntegrationStore {
+  // `storagePath` is a project's ~/.apx/projects/<apxId>/ directory.
+  constructor(storagePath) {
+    if (!storagePath) throw new Error("IntegrationStore: storagePath required");
+    this.storagePath = storagePath;
+  }
+
+  list() {
+    return readIntegrations(this.storagePath);
+  }
+
+  get(slug) {
+    return this.list().find((r) => r.slug === slug) || null;
+  }
+
+  // Insert or merge a record by slug. `patch` is shallow-merged; `patch.config`
+  // is deep-merged one level so callers can update a single config key without
+  // clobbering the token. Returns the persisted record.
+  upsert(slug, patch = {}) {
+    const entries = this.list();
+    const idx = entries.findIndex((r) => r.slug === slug);
+    const now = new Date().toISOString();
+    if (idx === -1) {
+      const record = {
+        slug,
+        name: patch.name || slug,
+        type: patch.type || "custom",
+        description: patch.description || "",
+        source: patch.source || "builtin",
+        status: patch.status || "disconnected",
+        is_enabled: patch.is_enabled ?? false,
+        config: patch.config || {},
+        created_at: now,
+        updated_at: now,
+      };
+      entries.push(record);
+      writeIntegrations(this.storagePath, entries);
+      return record;
+    }
+    const prev = entries[idx];
+    const merged = {
+      ...prev,
+      ...patch,
+      config: { ...(prev.config || {}), ...(patch.config || {}) },
+      updated_at: now,
+    };
+    entries[idx] = merged;
+    writeIntegrations(this.storagePath, entries);
+    return merged;
+  }
+
+  remove(slug) {
+    const entries = this.list();
+    const next = entries.filter((r) => r.slug !== slug);
+    if (next.length === entries.length) return false;
+    writeIntegrations(this.storagePath, next);
+    return true;
+  }
+}
+
+// Resolve the effective integration for `slug` in a project, applying the
+// project→default precedence: a project's OWN enabled record wins; otherwise
+// the default project's enabled record is used. Returns { record, scope } or
+// null when neither is usable. `defaultStorage` defaults to the default
+// project's storage so callers only need the current project's storagePath.
+export function resolveIntegration({
+  projectStorage,
+  slug,
+  defaultStorage = defaultIntegrationsStorage(),
+  requireEnabled = true,
+}) {
+  const usable = (record) =>
+    !!record && (!requireEnabled || (record.is_enabled && record.status === "active"));
+
+  if (projectStorage) {
+    const own = new IntegrationStore(projectStorage).get(slug);
+    if (usable(own)) return { record: own, scope: "project", storagePath: projectStorage };
+  }
+  if (defaultStorage && defaultStorage !== projectStorage) {
+    const fallback = new IntegrationStore(defaultStorage).get(slug);
+    if (usable(fallback)) return { record: fallback, scope: "global", storagePath: defaultStorage };
+  }
+  return null;
+}

package/src/host/daemon/api/integrations.js

@@ -0,0 +1,191 @@
+// Integration plugins per project. Companion to api/mcps.js: MCP servers are
+// raw tool endpoints; integrations are higher-level plugins (Asana today) that
+// own a credential + lifecycle and expose named tools to agents.
+//
+// Scoping (see core/integrations/store.js): every record lives in one project's
+// integrations.json. `?scope=global` targets the DEFAULT project's store, so
+// "global" integrations are literally the default project's — a project without
+// its own record falls back to that one. This keeps "which Asana runs here?"
+// unambiguous when you have both a base Asana and a per-project Asana.
+//
+//   GET    /projects/:pid/integrations?scope=project|global      list stored (redacted)
+//   GET    /projects/:pid/integrations/catalog                   roster + resolved status
+//   GET    /projects/:pid/integrations/:slug?scope=…             one plugin status
+//   POST   /projects/:pid/integrations/:slug/configure?scope=…   save credentials
+//   POST   /projects/:pid/integrations/:slug/validate?scope=…    verify against provider
+//   POST   /projects/:pid/integrations/:slug/deactivate?scope=…  disable
+//   POST   /projects/:pid/integrations/:slug/action/:action?scope=…  plugin read action
+//   DELETE /projects/:pid/integrations/:slug?scope=…             remove
+import {
+  IntegrationStore,
+  resolveIntegration,
+  redactRecord,
+  defaultIntegrationsStorage,
+  listCatalog,
+  getPluginService,
+} from "#core/integrations/index.js";
+
+function normalizeScope(raw) {
+  if (!raw) return "project";
+  const s = String(raw).toLowerCase();
+  if (s === "global" || s === "default") return "global";
+  if (s === "project" || s === "shared" || s === "runtime") return "project";
+  return null;
+}
+
+// Resolve the storagePath for the requested scope. `global` → default project
+// store; `project` → the current project's store.
+function storagePathForScope(scope, p, projects) {
+  if (scope === "global") {
+    const base = projects.get(0);
+    return base?.storagePath || defaultIntegrationsStorage();
+  }
+  return p.storagePath || null;
+}
+
+export function register(app, { projects, project }) {
+  // List stored integrations in the chosen scope (secrets redacted).
+  app.get("/projects/:pid/integrations", (req, res) => {
+    const p = project(req, res);
+    if (!p) return;
+    const scope = normalizeScope(req.query?.scope);
+    if (scope === null) return res.status(400).json({ error: `unknown scope "${req.query?.scope}"` });
+    const storagePath = storagePathForScope(scope, p, projects);
+    if (!storagePath) return res.status(400).json({ error: "project has no storage path" });
+    const records = new IntegrationStore(storagePath).list().map(redactRecord);
+    res.json(records);
+  });
+
+  // The full plugin roster with each plugin's resolved status for this project
+  // (project record wins over the default/global one).
+  app.get("/projects/:pid/integrations/catalog", (req, res) => {
+    const p = project(req, res);
+    if (!p) return;
+    const catalog = listCatalog().map((entry) => {
+      const svc = getPluginService(entry.slug);
+      let status = { slug: entry.slug, status: "disconnected", is_enabled: false };
+      let scope = null;
+      if (svc) {
+        const resolved = resolveIntegration({
+          projectStorage: p.storagePath,
+          slug: entry.slug,
+          requireEnabled: false,
+        });
+        status = svc.status(resolved?.record || null);
+        scope = resolved?.scope || null;
+      }
+      return { ...entry, status, resolved_scope: scope };
+    });
+    res.json(catalog);
+  });
+
+  // Status for a single plugin in the chosen scope.
+  app.get("/projects/:pid/integrations/:slug", (req, res) => {
+    const p = project(req, res);
+    if (!p) return;
+    const svc = getPluginService(req.params.slug);
+    if (!svc) return res.status(404).json({ error: `unknown plugin "${req.params.slug}"` });
+    const scope = normalizeScope(req.query?.scope);
+    if (scope === null) return res.status(400).json({ error: `unknown scope "${req.query?.scope}"` });
+    const storagePath = storagePathForScope(scope, p, projects);
+    if (!storagePath) return res.status(400).json({ error: "project has no storage path" });
+    const record = new IntegrationStore(storagePath).get(req.params.slug);
+    res.json(svc.status(record));
+  });
+
+  // Save credentials / config. Creates the record if missing.
+  app.post("/projects/:pid/integrations/:slug/configure", (req, res) => {
+    const p = project(req, res);
+    if (!p) return;
+    const svc = getPluginService(req.params.slug);
+    if (!svc) return res.status(404).json({ error: `unknown plugin "${req.params.slug}"` });
+    const scope = normalizeScope(req.query?.scope);
+    if (scope === null) return res.status(400).json({ error: `unknown scope "${req.query?.scope}"` });
+    const storagePath = storagePathForScope(scope, p, projects);
+    if (!storagePath) return res.status(400).json({ error: "project has no storage path" });
+    const store = new IntegrationStore(storagePath);
+    try {
+      const { patch } = svc.configure(store.get(req.params.slug), req.body || {});
+      const record = store.upsert(req.params.slug, patch);
+      res.status(201).json(redactRecord(record));
+    } catch (e) {
+      res.status(400).json({ error: e.message });
+    }
+  });
+
+  // Verify the stored credentials against the provider, then persist the result.
+  app.post("/projects/:pid/integrations/:slug/validate", async (req, res) => {
+    const p = project(req, res);
+    if (!p) return;
+    const svc = getPluginService(req.params.slug);
+    if (!svc) return res.status(404).json({ error: `unknown plugin "${req.params.slug}"` });
+    const scope = normalizeScope(req.query?.scope);
+    if (scope === null) return res.status(400).json({ error: `unknown scope "${req.query?.scope}"` });
+    const storagePath = storagePathForScope(scope, p, projects);
+    if (!storagePath) return res.status(400).json({ error: "project has no storage path" });
+    const store = new IntegrationStore(storagePath);
+    const record = store.get(req.params.slug);
+    if (!record) return res.status(404).json({ error: "integration not configured" });
+    try {
+      const { patch, result } = await svc.validate(record);
+      store.upsert(req.params.slug, patch);
+      if (result && result.ok === false) return res.status(400).json(result);
+      res.json(result);
+    } catch (e) {
+      res.status(400).json({ error: e.message });
+    }
+  });
+
+  // Disable a plugin without deleting its stored credentials.
+  app.post("/projects/:pid/integrations/:slug/deactivate", (req, res) => {
+    const p = project(req, res);
+    if (!p) return;
+    const svc = getPluginService(req.params.slug);
+    if (!svc) return res.status(404).json({ error: `unknown plugin "${req.params.slug}"` });
+    const scope = normalizeScope(req.query?.scope);
+    if (scope === null) return res.status(400).json({ error: `unknown scope "${req.query?.scope}"` });
+    const storagePath = storagePathForScope(scope, p, projects);
+    if (!storagePath) return res.status(400).json({ error: "project has no storage path" });
+    const store = new IntegrationStore(storagePath);
+    if (!store.get(req.params.slug)) return res.status(404).json({ error: "integration not configured" });
+    const { patch } = svc.deactivate(store.get(req.params.slug));
+    const record = store.upsert(req.params.slug, patch);
+    res.json(svc.status(record));
+  });
+
+  // Plugin-specific read action (e.g. Asana → list workspaces for the token).
+  app.post("/projects/:pid/integrations/:slug/action/:action", async (req, res) => {
+    const p = project(req, res);
+    if (!p) return;
+    const svc = getPluginService(req.params.slug);
+    if (!svc) return res.status(404).json({ error: `unknown plugin "${req.params.slug}"` });
+    const fn = svc.actions?.[req.params.action];
+    if (typeof fn !== "function") {
+      return res.status(404).json({ error: `unknown action "${req.params.action}"` });
+    }
+    const scope = normalizeScope(req.query?.scope);
+    if (scope === null) return res.status(400).json({ error: `unknown scope "${req.query?.scope}"` });
+    const storagePath = storagePathForScope(scope, p, projects);
+    if (!storagePath) return res.status(400).json({ error: "project has no storage path" });
+    const record = new IntegrationStore(storagePath).get(req.params.slug);
+    if (!record) return res.status(404).json({ error: "integration not configured" });
+    try {
+      res.json(await fn.call(svc.actions, record));
+    } catch (e) {
+      res.status(400).json({ error: e.message });
+    }
+  });
+
+  // Remove a stored integration entirely.
+  app.delete("/projects/:pid/integrations/:slug", (req, res) => {
+    const p = project(req, res);
+    if (!p) return;
+    const scope = normalizeScope(req.query?.scope);
+    if (scope === null) return res.status(400).json({ error: `unknown scope "${req.query?.scope}"` });
+    const storagePath = storagePathForScope(scope, p, projects);
+    if (!storagePath) return res.status(400).json({ error: "project has no storage path" });
+    const removed = new IntegrationStore(storagePath).remove(req.params.slug);
+    if (!removed) return res.status(404).end();
+    res.status(204).end();
+  });
+}

package/src/host/daemon/api.js

@@ -18,6 +18,7 @@ import { register as registerProjects } from "./api/projects.js";
 import { register as registerAgents } from "./api/agents.js";
 import { register as registerSessions } from "./api/sessions.js";
 import { register as registerMcps } from "./api/mcps.js";
+import { register as registerIntegrations } from "./api/integrations.js";
 import { register as registerVars } from "./api/vars.js";
 import { register as registerMessages } from "./api/messages.js";
 import { register as registerTelegram } from "./api/telegram.js";
@@ -109,6 +110,7 @@ export function buildApi({
   registerAgents(app, ctx);
   registerSessions(app, ctx);
   registerMcps(app, ctx);
+  registerIntegrations(app, ctx);
   registerVars(app, ctx);
   registerMessages(app, ctx);
   registerEngines(app, ctx);