replicas-engine 0.1.595 → 0.1.597

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "replicas-engine",
-  "version": "0.1.595",
+  "version": "0.1.597",
   "description": "Lightweight API server for Replicas workspaces",
   "type": "module",
   "main": "dist/src/index.js",
@@ -10,13 +10,14 @@
   },
   "files": [
     "dist",
+    "workspace-sdk",
     "scripts/opencode",
     "scripts/engine-watchdog.sh",
     "scripts/lockmem.c"
   ],
   "scripts": {
     "dev": "tsx watch --conditions=development src/index.ts",
-    "build": "tsup",
+    "build": "bun run --cwd ../shared build && node scripts/generate-workspace-sdk-types.mjs && tsup",
     "dev-pack": "bun run build && node scripts/pack-dev-tarball.mjs",
     "start": "node dist/src/index.js",
     "dev-sync": "scripts/dev-sync.sh",

package/workspace-sdk/index.d.ts

@@ -0,0 +1,14 @@
+import type { ReplicasSdk } from './shared/workspace-sdk';
+
+export type {
+  PluginConnectionStatus,
+  PluginId,
+  PluginScope,
+  PluginToolSchema,
+  ProviderRequestOptions,
+  ReplicasSdk,
+  WorkspaceIntegrationsResponse,
+  WorkspacePluginSummary,
+} from './shared/workspace-sdk';
+export declare const replicas: ReplicasSdk;
+export default replicas;

package/workspace-sdk/index.js

@@ -0,0 +1,118 @@
+function config() {
+  const monolithUrl = process.env.REPLICAS_MONOLITH_URL;
+  const engineSecret = process.env.REPLICAS_ENGINE_SECRET;
+  const workspaceId = process.env.REPLICAS_WORKSPACE_ID;
+  if (!monolithUrl || !engineSecret || !workspaceId) {
+    throw new Error('This process is missing Replicas workspace credentials');
+  }
+  return { monolithUrl: monolithUrl.replace(/\/$/, ''), engineSecret, workspaceId };
+}
+
+async function request(path, options = {}) {
+  const { monolithUrl, engineSecret, workspaceId } = config();
+  const headers = new Headers(options.headers);
+  headers.set('Authorization', `Bearer ${engineSecret}`);
+  headers.set('X-Workspace-Id', workspaceId);
+  if (options.body !== undefined) headers.set('Content-Type', 'application/json');
+  const response = await fetch(`${monolithUrl}${path}`, {
+    ...options,
+    headers,
+    body: options.body === undefined ? undefined : JSON.stringify(options.body),
+  });
+  if (response.status === 204) return undefined;
+  const text = await response.text();
+  let data;
+  try {
+    data = JSON.parse(text);
+  } catch {
+    data = { error: text };
+  }
+  if (!response.ok) {
+    throw new Error(data && typeof data.error === 'string' ? data.error : `Replicas request failed (${response.status})`);
+  }
+  return data;
+}
+
+function providerPath(path) {
+  if (
+    typeof path !== 'string' ||
+    !path.startsWith('/') ||
+    path.startsWith('//') ||
+    path.split('/').includes('..')
+  ) {
+    throw new Error('Provider API paths must be relative and start with /');
+  }
+  return path;
+}
+
+const integrations = {
+  list: () => request('/v1/engine/integrations'),
+};
+
+const plugins = {
+  async list() {
+    return (await integrations.list()).plugins;
+  },
+  search: (input) => request('/v1/engine/plugins/search', { method: 'POST', body: input }),
+  describe: (input) => request('/v1/engine/plugins/describe', { method: 'POST', body: input }),
+  execute: (input) => request('/v1/engine/plugins/execute', { method: 'POST', body: input }),
+};
+
+const linear = {
+  graphql: ({ query, variables, operationName }) =>
+    request('/v1/engine/linear/graphql', {
+      method: 'POST',
+      body: { query, variables, operationName },
+    }),
+};
+
+const slack = {
+  call: (method, arguments_ = {}) =>
+    request('/v1/engine/slack/api', {
+      method: 'POST',
+      body: { method, arguments: arguments_ },
+    }),
+  attachThread: ({ channel, threadTs }) =>
+    request('/v1/slack/threads/attach', {
+      method: 'POST',
+      body: { channel_id: channel, thread_ts: threadTs },
+    }),
+};
+
+const google = {
+  request(path, options = {}) {
+    const normalized = path.startsWith('/v1/gdrive/')
+      ? path
+      : `/v1/gdrive/${path.replace(/^\/+/, '')}`;
+    if (!normalized.startsWith('/v1/gdrive/')) throw new Error('Google paths must use the Replicas Google gateway');
+    return request(normalized, options);
+  },
+};
+
+const github = {
+  request: (path, options = {}) =>
+    request('/v1/engine/github/api', {
+      method: 'POST',
+      body: { path: providerPath(path), method: options.method, body: options.body },
+    }),
+};
+
+const gitlab = {
+  request: (path, options = {}) =>
+    request('/v1/engine/gitlab/api', {
+      method: 'POST',
+      body: {
+        path: providerPath(path),
+        method: options.method,
+        body: options.body,
+        host: options.host,
+      },
+    }),
+};
+
+const sentry = {
+  request: (path) => request('/v1/engine/sentry/api', { method: 'POST', body: { path } }),
+};
+
+export const replicas = { integrations, plugins, linear, slack, google, github, gitlab, sentry };
+export default replicas;

package/workspace-sdk/index.test.ts

@@ -0,0 +1,94 @@
+import { afterEach, describe, expect, test } from 'bun:test';
+import { replicas } from './index.js';
+
+const previous = {
+  url: process.env.REPLICAS_MONOLITH_URL,
+  secret: process.env.REPLICAS_ENGINE_SECRET,
+  workspace: process.env.REPLICAS_WORKSPACE_ID,
+};
+
+afterEach(() => {
+  if (previous.url === undefined) delete process.env.REPLICAS_MONOLITH_URL;
+  else process.env.REPLICAS_MONOLITH_URL = previous.url;
+  if (previous.secret === undefined) delete process.env.REPLICAS_ENGINE_SECRET;
+  else process.env.REPLICAS_ENGINE_SECRET = previous.secret;
+  if (previous.workspace === undefined) delete process.env.REPLICAS_WORKSPACE_ID;
+  else process.env.REPLICAS_WORKSPACE_ID = previous.workspace;
+});
+
+describe('@replicas/sdk', () => {
+  test('sends only workspace identity to the scoped gateway', async () => {
+    let observed: { path: string; authorization: string | null; workspace: string | null; body: unknown } | null = null;
+    const server = Bun.serve({
+      port: 0,
+      async fetch(request) {
+        observed = {
+          path: new URL(request.url).pathname,
+          authorization: request.headers.get('authorization'),
+          workspace: request.headers.get('x-workspace-id'),
+          body: await request.json(),
+        };
+        return Response.json({ data: { ok: true }, logId: 'log-1' });
+      },
+    });
+    process.env.REPLICAS_MONOLITH_URL = server.url.toString().replace(/\/$/, '');
+    process.env.REPLICAS_ENGINE_SECRET = 'engine-secret';
+    process.env.REPLICAS_WORKSPACE_ID = 'workspace-1';
+    try {
+      await replicas.plugins.execute({
+        plugin: 'stripe',
+        tool: 'STRIPE_RETRIEVE_BALANCE',
+      });
+      expect(observed).toEqual({
+        path: '/v1/engine/plugins/execute',
+        authorization: 'Bearer engine-secret',
+        workspace: 'workspace-1',
+        body: { plugin: 'stripe', tool: 'STRIPE_RETRIEVE_BALANCE' },
+      });
+    } finally {
+      server.stop(true);
+    }
+  });
+
+  test('refuses to run outside an authenticated workspace', async () => {
+    delete process.env.REPLICAS_MONOLITH_URL;
+    delete process.env.REPLICAS_ENGINE_SECRET;
+    delete process.env.REPLICAS_WORKSPACE_ID;
+    await expect(replicas.plugins.list()).rejects.toThrow('missing Replicas workspace credentials');
+  });
+
+  test('keeps native provider credentials behind the workspace gateway', async () => {
+    let observed: { path: string; authorization: string | null; body: unknown } | null = null;
+    const server = Bun.serve({
+      port: 0,
+      async fetch(request) {
+        observed = {
+          path: new URL(request.url).pathname,
+          authorization: request.headers.get('authorization'),
+          body: await request.json(),
+        };
+        return Response.json({ login: 'replicas' });
+      },
+    });
+    process.env.REPLICAS_MONOLITH_URL = server.url.toString().replace(/\/$/, '');
+    process.env.REPLICAS_ENGINE_SECRET = 'engine-secret';
+    process.env.REPLICAS_WORKSPACE_ID = 'workspace-1';
+    try {
+      await replicas.github.request('/user');
+      expect(observed).toEqual({
+        path: '/v1/engine/github/api',
+        authorization: 'Bearer engine-secret',
+        body: { path: '/user' },
+      });
+    } finally {
+      server.stop(true);
+    }
+  });
+
+  test('rejects provider URLs that can escape the allowed origin', async () => {
+    process.env.REPLICAS_MONOLITH_URL = 'https://api.example.com';
+    process.env.REPLICAS_ENGINE_SECRET = 'engine-secret';
+    process.env.REPLICAS_WORKSPACE_ID = 'workspace-1';
+    expect(() => replicas.github.request('//attacker.example/path')).toThrow('relative');
+  });
+});

package/workspace-sdk/package.json

@@ -0,0 +1,14 @@
+{
+  "name": "@replicas/sdk",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "./index.js",
+  "types": "./index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "import": "./index.js",
+      "default": "./index.js"
+    }
+  }
+}

package/workspace-sdk/shared/routes/integrations.d.ts

@@ -0,0 +1,11 @@
+// Generated from shared/src by generate-workspace-sdk-types.mjs; do not edit.
+export interface NativeIntegrationStatus {
+    github: boolean;
+    gitlab: boolean;
+    linear: boolean;
+    slack: boolean;
+    google: boolean;
+}
+export interface WorkspaceNativeIntegrationStatus extends NativeIntegrationStatus {
+    sentry: boolean;
+}

package/workspace-sdk/shared/routes/plugins.d.ts

@@ -0,0 +1,119 @@
+// Generated from shared/src by generate-workspace-sdk-types.mjs; do not edit.
+import type { WorkspaceNativeIntegrationStatus } from './integrations';
+export declare const PLUGIN_CATALOG: readonly [{
+    readonly id: "attio";
+    readonly toolkit: "attio";
+    readonly name: "Attio";
+    readonly description: "Search CRM records, people, companies, lists, and notes.";
+}, {
+    readonly id: "clickhouse";
+    readonly toolkit: "clickhouse";
+    readonly name: "ClickHouse";
+    readonly description: "Inspect databases, tables, schemas, and query results.";
+}, {
+    readonly id: "googleads";
+    readonly toolkit: "googleads";
+    readonly name: "Google Ads";
+    readonly description: "Inspect campaigns, customers, accounts, and reporting data.";
+}, {
+    readonly id: "googledocs";
+    readonly toolkit: "googledocs";
+    readonly name: "Google Docs";
+    readonly description: "Read documents, structure, comments, and exported content.";
+}, {
+    readonly id: "googledrive";
+    readonly toolkit: "googledrive";
+    readonly name: "Google Drive";
+    readonly description: "Search files, folders, metadata, permissions, and shared drives.";
+}, {
+    readonly id: "googlesearch";
+    readonly toolkit: "google_search_console";
+    readonly name: "Google Search";
+    readonly description: "Inspect Search Console performance, indexing, sites, and sitemaps.";
+}, {
+    readonly id: "googlesheets";
+    readonly toolkit: "googlesheets";
+    readonly name: "Google Sheets";
+    readonly description: "Read spreadsheets, worksheets, ranges, tables, and charts.";
+}, {
+    readonly id: "posthog";
+    readonly toolkit: "posthog";
+    readonly name: "PostHog";
+    readonly description: "Inspect projects, events, insights, dashboards, flags, and recordings.";
+}, {
+    readonly id: "stripe";
+    readonly toolkit: "stripe";
+    readonly name: "Stripe";
+    readonly description: "Inspect customers, payments, invoices, subscriptions, and balances.";
+}];
+export type PluginId = (typeof PLUGIN_CATALOG)[number]['id'];
+export type PluginScope = 'organization' | 'personal';
+export declare const PLUGIN_CONNECTION_STATUSES: readonly ["initiated", "active", "expired", "failed"];
+export type PluginConnectionStatus = (typeof PLUGIN_CONNECTION_STATUSES)[number];
+export interface PluginCatalogItem {
+    id: PluginId;
+    toolkit: string;
+    name: string;
+    description: string;
+}
+export interface PluginConnectionSummary {
+    id: string;
+    pluginId: PluginId;
+    scope: PluginScope;
+    status: PluginConnectionStatus;
+    accountLabel?: string;
+    connectedAt?: string;
+}
+export interface PluginConnectionsResponse {
+    plugins: PluginCatalogItem[];
+    organization: PluginConnectionSummary[];
+    personal: PluginConnectionSummary[];
+}
+export interface PluginStartOAuthResponse {
+    authorizationUrl: string;
+}
+export interface PluginConnectionDeleteResponse {
+    success: boolean;
+}
+export interface WorkspacePluginSummary extends PluginCatalogItem {
+    connected: boolean;
+    scope?: PluginScope;
+    status?: PluginConnectionStatus;
+    accountLabel?: string;
+}
+export interface WorkspaceIntegrationsResponse {
+    plugins: WorkspacePluginSummary[];
+    native: WorkspaceNativeIntegrationStatus;
+}
+export interface PluginSearchRequest {
+    plugin: PluginId;
+    query: string;
+}
+export interface PluginToolSchema {
+    slug: string;
+    toolkit: string;
+    description: string;
+    inputSchema: Record<string, unknown>;
+    outputSchema?: Record<string, unknown>;
+}
+export interface PluginSearchResponse {
+    tools: PluginToolSchema[];
+}
+export interface PluginDescribeRequest {
+    plugin: PluginId;
+    tools: string[];
+}
+export interface PluginDescribeResponse {
+    tools: PluginToolSchema[];
+}
+export interface PluginExecuteRequest {
+    plugin: PluginId;
+    tool: string;
+    arguments?: Record<string, unknown>;
+}
+export interface PluginExecuteResponse {
+    data: unknown;
+    logId: string;
+}
+export declare function isPluginId(value: string): value is PluginId;
+export declare function isPluginConnectionStatus(value: string): value is PluginConnectionStatus;

package/workspace-sdk/shared/workspace-sdk.d.ts

@@ -0,0 +1,58 @@
+// Generated from shared/src by generate-workspace-sdk-types.mjs; do not edit.
+import type { PluginDescribeRequest, PluginDescribeResponse, PluginExecuteRequest, PluginExecuteResponse, PluginSearchRequest, PluginSearchResponse, WorkspaceIntegrationsResponse, WorkspacePluginSummary } from './routes/plugins';
+export type { PluginConnectionStatus, PluginId, PluginScope, PluginToolSchema, WorkspaceIntegrationsResponse, WorkspacePluginSummary, } from './routes/plugins';
+export interface ProviderRequestOptions {
+    method?: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+    body?: unknown;
+}
+export interface ReplicasSdk {
+    integrations: {
+        list(): Promise<WorkspaceIntegrationsResponse>;
+    };
+    plugins: {
+        list(): Promise<WorkspacePluginSummary[]>;
+        search(input: PluginSearchRequest): Promise<PluginSearchResponse>;
+        describe(input: PluginDescribeRequest): Promise<PluginDescribeResponse>;
+        execute<T = unknown>(input: PluginExecuteRequest): Promise<Omit<PluginExecuteResponse, 'data'> & {
+            data: T;
+        }>;
+    };
+    linear: {
+        graphql<T = unknown>(input: {
+            query: string;
+            variables?: Record<string, unknown> | null;
+            operationName?: string | null;
+        }): Promise<T>;
+    };
+    slack: {
+        call<T = unknown>(method: string, args?: Record<string, unknown>): Promise<T>;
+        attachThread(input: {
+            channel: string;
+            threadTs: string;
+        }): Promise<{
+            thread: unknown;
+            workspace: {
+                id: string;
+                name: string;
+            };
+        }>;
+    };
+    google: {
+        request<T = unknown>(path: string, options?: {
+            method?: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+            body?: unknown;
+            headers?: HeadersInit;
+        }): Promise<T>;
+    };
+    github: {
+        request<T = unknown>(path: string, options?: ProviderRequestOptions): Promise<T>;
+    };
+    gitlab: {
+        request<T = unknown>(path: string, options?: ProviderRequestOptions & {
+            host?: string;
+        }): Promise<T>;
+    };
+    sentry: {
+        request<T = unknown>(path: string): Promise<T>;
+    };
+}