@polycore/runner 0.1.0

package/src/connector.ts

@@ -0,0 +1,215 @@
+import type { z } from "zod";
+
+import type { Action, ActionLogger, LoadedAction } from "./action.js";
+import type { EnvironmentConfig, ProjectConfig } from "./config.js";
+
+/**
+ * Hazard class for a connector. Lane 1 connectors are always `read`: * they exist precisely because they are mutation-incapable, which is what
+ * lets them run with no human approval. Mutating operations are modeled as
+ * blessed *actions*, not connectors, and run behind the approval gate.
+ */
+export type ConnectorEffect = "read";
+
+/** Hazard class of any capability (connector or action). */
+export type CapabilityEffect = "read" | "mutate";
+
+/** Whether a capability is a built-in connector or a customer-authored action. */
+export type CapabilityKind = "connector" | "action";
+
+/** Everything a connector needs to execute one request. */
+export interface ConnectorContext {
+  /** The project this request targets (a slug from the runner config). */
+  readonly project: string;
+  /** The environment to run against (e.g. "dev"), within the project. */
+  readonly environment: string;
+  /** The resolved environment config (per-connector-family credentials). */
+  readonly env: EnvironmentConfig;
+  /** Structured log sink for human-facing progress. */
+  readonly log: (message: string) => void;
+}
+
+/**
+ * A connector is a generic, read-only-constrained transport that ships in
+ * the runner, not a per-operation function. `sql.query` covers every
+ * database read; `firestore.query` covers every Firestore read. The caller
+ * supplies the query/path at request time via `params`.
+ */
+export interface Connector<Args = unknown, Result = unknown> {
+  /** Dotted capability name, e.g. `firestore.query`. */
+  readonly name: string;
+  /** One-line description for catalogs and the agent. */
+  readonly description: string;
+  /** Always `read`: see {@link ConnectorEffect}. */
+  readonly effect: ConnectorEffect;
+  /**
+   * Which environment-config family this connector needs (e.g. `firestore`).
+   * A built-in connector is registered for a project only when at least one
+   * of the project's environments configures that family; unset means the
+   * connector needs no per-environment credentials.
+   */
+  readonly configKey?: keyof EnvironmentConfig;
+  /** Zod schema the caller's arguments are validated against at the boundary. */
+  readonly params: z.ZodType<Args>;
+  /** Execute the request. Must perform reads only. */
+  run(args: Args, ctx: ConnectorContext): Promise<Result>;
+}
+
+/**
+ * Whether a project's environments satisfy a connector's config family
+ * (the advertise-time filter), so a project without e.g. Firestore
+ * credentials never advertises the Firestore connectors.
+ */
+export function connectorAvailableFor(
+  connector: Connector,
+  project: ProjectConfig,
+): boolean {
+  const key = connector.configKey;
+  if (key === undefined) return true;
+  return Object.values(project.environments).some(
+    (env) => env[key] !== undefined,
+  );
+}
+
+/**
+ * A normalized capability the registry stores and dispatches uniformly,
+ * whether it originated as a connector or an action. The descriptor sent to
+ * the control plane is derived from these fields.
+ */
+export interface RegisteredCapability {
+  readonly name: string;
+  readonly description: string;
+  readonly effect: CapabilityEffect;
+  readonly kind: CapabilityKind;
+  readonly params: z.ZodType;
+  run(args: unknown, ctx: ConnectorContext): Promise<unknown>;
+}
+
+/** Result of dispatching a connector request. */
+export interface DispatchResult {
+  readonly capability: string;
+  readonly environment: string;
+  readonly result: unknown;
+}
+
+/** Source of secret values an action declares; resolved at registration. */
+export type SecretSource = Readonly<Record<string, string>>;
+
+/** Funnel an action's leveled logger into the connector context's flat sink. */
+function actionLogger(log: ConnectorContext["log"]): ActionLogger {
+  return {
+    info: (message) => log(message),
+    warn: (message) => log(`WARN: ${message}`),
+    error: (message) => log(`ERROR: ${message}`),
+    success: (message) => log(message),
+  };
+}
+
+/** Resolve the subset of secrets an action declared, failing loud if missing. */
+function resolveSecrets(
+  action: Action,
+  source: SecretSource,
+): Record<string, string> {
+  const resolved: Record<string, string> = {};
+  for (const key of Object.keys(action.secrets ?? {})) {
+    const value = source[key] ?? process.env[key];
+    if (value === undefined || value.length === 0) {
+      throw new Error(
+        `Missing secret "${key}" required by action "${action.title}". ` +
+          `Provide it in the runner config's "secrets" or the environment.`,
+      );
+    }
+    resolved[key] = value;
+  }
+  return resolved;
+}
+
+/** Thrown when a capability name is not registered. */
+export class UnknownConnectorError extends Error {
+  constructor(requested: string, available: string[]) {
+    const list = available.map((n) => `"${n}"`).join(", ");
+    super(
+      `Unknown connector "${requested}". Available connectors: ${list || "(none)"}.`,
+    );
+    this.name = "UnknownConnectorError";
+  }
+}
+
+/**
+ * The runner's connector registry: register connectors, then dispatch a
+ * request by capability name. Dispatch validates the caller's arguments
+ * against the connector's Zod schema *before* `run` executes, so a
+ * malformed or hallucinated request is rejected before it touches a
+ * datastore.
+ */
+export class ConnectorRegistry {
+  private readonly capabilities = new Map<string, RegisteredCapability>();
+
+  private add(capability: RegisteredCapability): void {
+    if (this.capabilities.has(capability.name)) {
+      throw new Error(`Capability "${capability.name}" is already registered.`);
+    }
+    this.capabilities.set(capability.name, capability);
+  }
+
+  public register(connector: Connector): void {
+    this.add({
+      name: connector.name,
+      description: connector.description,
+      effect: connector.effect,
+      kind: "connector",
+      params: connector.params,
+      run: (args, ctx) => connector.run(args, ctx),
+    });
+  }
+
+  public registerAll(connectors: readonly Connector[]): void {
+    for (const connector of connectors) {
+      this.register(connector);
+    }
+  }
+
+  /**
+   * Register a customer-authored action as a capability. The action's `input`
+   * schema becomes the capability params; its declared secrets are resolved
+   * from `secrets` (falling back to `process.env`) at dispatch.
+   */
+  public registerAction(loaded: LoadedAction, secrets: SecretSource): void {
+    const { id, action } = loaded;
+    this.add({
+      name: id,
+      description: action.description,
+      effect: action.effect ?? "mutate",
+      kind: "action",
+      params: action.input,
+      run: (args, ctx) =>
+        Promise.resolve(
+          action.run({
+            input: args,
+            secrets: resolveSecrets(action, secrets),
+            environment: ctx.environment,
+            log: actionLogger(ctx.log),
+          }),
+        ),
+    });
+  }
+
+  public list(): RegisteredCapability[] {
+    return [...this.capabilities.values()];
+  }
+
+  public async dispatch(
+    capability: string,
+    rawArgs: unknown,
+    ctx: ConnectorContext,
+  ): Promise<DispatchResult> {
+    const entry = this.capabilities.get(capability);
+    if (!entry) {
+      throw new UnknownConnectorError(capability, [
+        ...this.capabilities.keys(),
+      ]);
+    }
+    const args = entry.params.parse(rawArgs);
+    const result = await entry.run(args, ctx);
+    return { capability, environment: ctx.environment, result };
+  }
+}

package/src/connectors/firestore.ts

@@ -0,0 +1,192 @@
+import {
+  applicationDefault,
+  cert,
+  getApps,
+  initializeApp,
+} from "firebase-admin/app";
+import {
+  type Firestore,
+  getFirestore,
+  type Query,
+} from "firebase-admin/firestore";
+import { z } from "zod";
+
+import type { FirestoreEnvironment } from "../config.js";
+import type { Connector, ConnectorContext } from "../connector.js";
+
+/**
+ * Firestore read connectors: the Lane 1 engine for a Firestore-backed
+ * project. They are read-only twice over: Layer 1 is the service
+ * account's `roles/datastore.viewer` IAM role (GCP rejects any write at the
+ * API boundary), and Layer 2 is this code, which only ever calls read
+ * methods. Mutations are never expressed as a connector.
+ *
+ * The Firebase Admin SDK bypasses Firestore Security Rules, so the
+ * read-only guarantee comes from the IAM role on the key, not from rules.
+ */
+
+const DEFAULT_LIMIT = 100;
+const MAX_LIMIT = 1000;
+
+const whereOpSchema = z.enum([
+  "==",
+  "!=",
+  "<",
+  "<=",
+  ">",
+  ">=",
+  "array-contains",
+  "array-contains-any",
+  "in",
+  "not-in",
+]);
+
+const whereSchema = z.object({
+  field: z.string().min(1),
+  op: whereOpSchema,
+  value: z.unknown(),
+});
+
+const orderBySchema = z.object({
+  field: z.string().min(1),
+  direction: z.enum(["asc", "desc"]).optional(),
+});
+
+function firestoreConfig(ctx: ConnectorContext): FirestoreEnvironment {
+  const firestore = ctx.env.firestore;
+  if (!firestore) {
+    throw new Error(
+      `Environment "${ctx.environment}" of project "${ctx.project}" has no firestore configuration.`,
+    );
+  }
+  return firestore;
+}
+
+/** Resolve (and cache, via the Admin SDK app registry) a Firestore handle. */
+function firestoreFor(ctx: ConnectorContext): Firestore {
+  const env = firestoreConfig(ctx);
+  const appName = `polycore-runner-${ctx.project}-${ctx.environment}`;
+  const existing = getApps().find((a) => a.name === appName);
+  // A key path uses that file's credential (local/dev); without one we fall
+  // back to Application Default Credentials, the GCP runtime service account
+  // (Cloud Run / GCE), which must itself carry `roles/datastore.viewer`.
+  const credential = env.serviceAccountKeyPath
+    ? cert(env.serviceAccountKeyPath)
+    : applicationDefault();
+  const app =
+    existing ??
+    initializeApp({ credential, projectId: env.projectId }, appName);
+  return getFirestore(app);
+}
+
+type WhereClause = z.infer<typeof whereSchema>;
+
+function applyWhere(query: Query, clauses: WhereClause[] | undefined): Query {
+  let next = query;
+  for (const clause of clauses ?? []) {
+    next = next.where(clause.field, clause.op, clause.value);
+  }
+  return next;
+}
+
+const queryParams = z.object({
+  collection: z.string().min(1),
+  where: z.array(whereSchema).optional(),
+  orderBy: orderBySchema.optional(),
+  limit: z.number().int().positive().max(MAX_LIMIT).optional(),
+});
+
+const firestoreQuery: Connector<z.infer<typeof queryParams>, unknown> = {
+  name: "firestore.query",
+  description:
+    "Read documents from a Firestore collection with optional where filters, ordering, and a limit. Returns at most `limit` documents (a capped page for inspection); do NOT use it to count or total; use firestore.count for that. Read-only.",
+  effect: "read",
+  configKey: "firestore",
+  params: queryParams,
+  async run(args, ctx) {
+    const db = firestoreFor(ctx);
+    let query: Query = db.collection(args.collection);
+    query = applyWhere(query, args.where);
+    if (args.orderBy) {
+      query = query.orderBy(
+        args.orderBy.field,
+        args.orderBy.direction ?? "asc",
+      );
+    }
+    query = query.limit(Math.min(args.limit ?? DEFAULT_LIMIT, MAX_LIMIT));
+
+    ctx.log(`Querying ${args.collection} in ${ctx.environment}…`);
+    const snap = await query.get();
+    return snap.docs.map((doc) => ({
+      id: doc.id,
+      data: doc.data(),
+    }));
+  },
+};
+
+const getParams = z.object({
+  collection: z.string().min(1),
+  id: z.string().min(1),
+});
+
+const firestoreGet: Connector<z.infer<typeof getParams>, unknown> = {
+  name: "firestore.get",
+  description:
+    "Read a single Firestore document by collection and id. Read-only.",
+  effect: "read",
+  configKey: "firestore",
+  params: getParams,
+  async run(args, ctx) {
+    const db = firestoreFor(ctx);
+    ctx.log(`Reading ${args.collection}/${args.id} in ${ctx.environment}…`);
+    const doc = await db.collection(args.collection).doc(args.id).get();
+    if (!doc.exists) {
+      return null;
+    }
+    return { id: doc.id, data: doc.data() as Record<string, unknown> };
+  },
+};
+
+const countParams = z.object({
+  collection: z.string().min(1),
+  where: z.array(whereSchema).optional(),
+});
+
+const firestoreCount: Connector<z.infer<typeof countParams>, number> = {
+  name: "firestore.count",
+  description:
+    "Count documents in a Firestore collection (optionally filtered) using a server-side aggregation. It counts EVERY matching document, so it is the correct, exact tool for any 'how many' / total question. For 'how many <record>s', count the <record> collection (e.g. users → the \"users\" collection) with NO filter unless a subset is explicitly asked for; if unsure of the exact collection name, call firestore.listCollections first. Read-only.",
+  effect: "read",
+  configKey: "firestore",
+  params: countParams,
+  async run(args, ctx) {
+    const db = firestoreFor(ctx);
+    const query = applyWhere(db.collection(args.collection), args.where);
+    ctx.log(`Counting ${args.collection} in ${ctx.environment}…`);
+    const snap = await query.count().get();
+    return snap.data().count;
+  },
+};
+
+const listCollections: Connector<Record<string, never>, string[]> = {
+  name: "firestore.listCollections",
+  description:
+    "List the top-level Firestore collection ids. Call this FIRST to ground yourself whenever you are not certain which collection holds the kind of record the question is about, then count/query that collection. Map the record asked about (a 'user', an 'order', a 'workspace') to its collection. The name of an organization, product, team, or environment is NEVER a collection: it only identifies whose system you are querying, so never treat it as a collection, id, or filter. Read-only.",
+  effect: "read",
+  configKey: "firestore",
+  params: z.object({}),
+  async run(_args, ctx) {
+    const db = firestoreFor(ctx);
+    ctx.log(`Listing collections in ${ctx.environment}…`);
+    const collections = await db.listCollections();
+    return collections.map((c) => c.id);
+  },
+};
+
+/** All Firestore read connectors, ready to register. */
+export const firestoreConnectors: readonly Connector[] = [
+  firestoreQuery,
+  firestoreGet,
+  firestoreCount,
+  listCollections,
+];

package/src/index.ts

@@ -0,0 +1,129 @@
+import type { LoadedAction } from "./action.js";
+import type { ProjectConfig, RunnerConfig } from "./config.js";
+import {
+  connectorAvailableFor,
+  ConnectorRegistry,
+  type SecretSource,
+} from "./connector.js";
+import { firestoreConnectors } from "./connectors/firestore.js";
+import { loadActions } from "./load-actions.js";
+
+export type {
+  Action,
+  ActionEffect,
+  ActionLogger,
+  ActionRunContext,
+  LoadedAction,
+} from "./action.js";
+export { defineAction } from "./action.js";
+export type {
+  ControlPlaneConfig,
+  EnvironmentConfig,
+  FirestoreEnvironment,
+  ProjectConfig,
+  RunnerConfig,
+} from "./config.js";
+export {
+  buildRunnerConfigFromEnv,
+  ControlPlaneConfigSchema,
+  EnvironmentConfigSchema,
+  FirestoreEnvironmentSchema,
+  hasEnvConfig,
+  loadRunnerConfig,
+  parseRunnerConfig,
+  ProjectConfigSchema,
+  resolveEnvironment,
+  resolveProject,
+  resolveProjectContext,
+  RUNNER_CONFIG_ENV,
+  RUNNER_PROJECTS_ENV,
+  RunnerConfigSchema,
+} from "./config.js";
+export type { RunnerClientOptions } from "./connect.js";
+export {
+  describeConnectors,
+  describeProjects,
+  RunnerClient,
+} from "./connect.js";
+export type {
+  CapabilityEffect,
+  CapabilityKind,
+  Connector,
+  ConnectorContext,
+  ConnectorEffect,
+  DispatchResult,
+  RegisteredCapability,
+  SecretSource,
+} from "./connector.js";
+export {
+  connectorAvailableFor,
+  ConnectorRegistry,
+  UnknownConnectorError,
+} from "./connector.js";
+export { firestoreConnectors } from "./connectors/firestore.js";
+export { loadActions } from "./load-actions.js";
+// The pinned Zod, re-exported so action authors share the runner's exact
+// instance, schemas must be introspectable by the runner's `z.toJSONSchema`.
+// Authors import `{ defineAction, z }` from "@polycore/runner", never from a
+// desktop package or a second `zod` copy.
+export { z } from "zod";
+
+/** All built-in (Lane 1) connectors; SQL/HTTP families register here as they land. */
+const builtinConnectors = [...firestoreConnectors];
+
+export interface CreateRegistryOptions {
+  /** Customer actions to serve alongside the built-in connectors. */
+  readonly actions?: readonly LoadedAction[];
+  /** Secret values available to those actions. */
+  readonly secrets?: SecretSource;
+  /**
+   * When given, built-in connectors are filtered to those whose config
+   * family at least one of the project's environments configures.
+   */
+  readonly project?: ProjectConfig;
+}
+
+/**
+ * Build a registry with the runner's built-in connectors (Lane 1) plus any
+ * customer-authored actions (Lane 2/3).
+ */
+export function createRegistry(
+  options: CreateRegistryOptions = {},
+): ConnectorRegistry {
+  const registry = new ConnectorRegistry();
+  const project = options.project;
+  const builtins = project
+    ? builtinConnectors.filter((c) => connectorAvailableFor(c, project))
+    : builtinConnectors;
+  registry.registerAll(builtins);
+  for (const loaded of options.actions ?? []) {
+    registry.registerAction(loaded, options.secrets ?? {});
+  }
+  return registry;
+}
+
+/**
+ * Build one registry per configured project: built-in connectors filtered
+ * by what the project's environments configure, plus the project's own
+ * actions with its secrets (project secrets win over runner-level secrets;
+ * both fall back to `process.env` at dispatch).
+ */
+export async function buildProjectRegistries(
+  config: RunnerConfig,
+): Promise<Map<string, ConnectorRegistry>> {
+  const registries = new Map<string, ConnectorRegistry>();
+  for (const [slug, project] of Object.entries(config.projects)) {
+    const actions = project.actionsDir
+      ? await loadActions(project.actionsDir)
+      : [];
+    registries.set(
+      slug,
+      createRegistry({
+        project,
+        actions,
+        secrets: { ...config.secrets, ...project.secrets },
+      }),
+    );
+  }
+  return registries;
+}

package/src/load-actions.ts

@@ -0,0 +1,104 @@
+import { readdir } from "node:fs/promises";
+import { join, relative } from "node:path";
+
+import { tsImport } from "tsx/esm/api";
+
+import type { Action, LoadedAction } from "./action.js";
+
+/**
+ * Discover and load customer-authored actions from a directory. Layout mirrors
+ * the rest of the framework: one folder per action, each holding an `action.ts`
+ * (or `.js`); the folder path relative to `dir` is the action's id (and its
+ * dispatch capability name). A subfolder without an action file is a group and
+ * is recursed into.
+ *
+ * Modules are loaded via tsx's programmatic importer so the runner can load
+ * raw `.ts` regardless of how its own process was started, exactly like the
+ * desktop runtime's loader.
+ */
+export async function loadActions(dir: string): Promise<LoadedAction[]> {
+  const loaded: LoadedAction[] = [];
+  await walk(dir, dir, loaded);
+  loaded.sort((a, b) => a.id.localeCompare(b.id));
+  return loaded;
+}
+
+const ACTION_FILES = ["action.ts", "action.js"];
+
+async function walk(
+  root: string,
+  current: string,
+  out: LoadedAction[],
+): Promise<void> {
+  const entries = await readdir(current, { withFileTypes: true });
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    const childDir = join(current, entry.name);
+    const children = await readdir(childDir, { withFileTypes: true });
+    const actionFile = children.find(
+      (child) => child.isFile() && ACTION_FILES.includes(child.name),
+    );
+    if (actionFile) {
+      const action = await importAction(join(childDir, actionFile.name));
+      out.push({ id: toPosixId(relative(root, childDir)), action });
+    } else {
+      await walk(root, childDir, out);
+    }
+  }
+}
+
+function toPosixId(relativePath: string): string {
+  return relativePath.split(/[\\/]/).join("/");
+}
+
+async function importAction(file: string): Promise<Action> {
+  const mod: unknown = await tsImport(file, import.meta.url);
+  const exported = unwrapDefaultExport(mod);
+  assertAction(exported, file);
+  return exported;
+}
+
+/** ESM gives `default`; tsx's CJS bridge nests `{ __esModule, default }`. */
+function unwrapDefaultExport(mod: unknown): unknown {
+  if (mod === null || typeof mod !== "object" || !("default" in mod)) {
+    return mod;
+  }
+  const direct: unknown = mod.default;
+  if (
+    direct !== null &&
+    typeof direct === "object" &&
+    "__esModule" in direct &&
+    "default" in direct
+  ) {
+    return direct.default;
+  }
+  return direct;
+}
+
+function assertAction(value: unknown, file: string): asserts value is Action {
+  // The SDK's `defineAction` returns a *callable* handle (a function with the
+  // spec assigned as properties), while the runner's own `defineAction`
+  // returns a plain object. Accept both: what matters is the action shape.
+  if (
+    value === null ||
+    (typeof value !== "object" && typeof value !== "function")
+  ) {
+    throw new Error(`Action module "${file}" must default-export an action.`);
+  }
+  const candidate = value as Record<string, unknown>;
+  if (typeof candidate["run"] !== "function") {
+    throw new Error(`Action "${file}" is missing a "run" function.`);
+  }
+  if (!isSchema(candidate["input"]) || !isSchema(candidate["output"])) {
+    throw new Error(`Action "${file}" must declare Zod "input" and "output".`);
+  }
+}
+
+function isSchema(value: unknown): boolean {
+  return (
+    value !== null &&
+    typeof value === "object" &&
+    "safeParse" in value &&
+    typeof value.safeParse === "function"
+  );
+}