@polycore/runner 0.1.0 → 0.2.0

package/README.md

@@ -93,7 +93,6 @@ environment can carry credentials for several backends:
           "firestore": { "projectId": "alpha-prod" }
         }
       },
-      "actionsDir": "/absolute/path/to/alpha/polycore-actions",
       "contextFile": "/absolute/path/to/alpha/schema.md"
     },
     "beta": {
@@ -113,10 +112,16 @@ environment can carry credentials for several backends:
 }
 ```
 
+Actions are discovered by **convention**, not a config field: put a project's
+actions in an `actions/<slug>/` directory beside the config file, or — when the
+runner serves a single project — directly in `actions/`. They are loaded
+alongside the built-in connectors. (There is no `actionsDir` field.)
+
 Per-project extras:
 
-- `actionsDir`: customer-authored actions for that project, loaded alongside
-  the built-in connectors.
+- `defaultEnvironment`: the environment an unqualified ask targets. It is the
+  runner's local-CLI default AND is advertised to the control plane as the
+  front-door default. Must be one of the project's `environments`.
 - `secrets`: per-project action secret values (falls back to the runner-level
   `secrets` map, then `process.env`). These never reach the control plane.
 - `context` / `contextFile`: an agent-grounding document (e.g. the product's
@@ -246,8 +251,11 @@ gcloud run deploy polycore-runner \
 
 When `POLYCORE_PROJECTS` is set and no `--config` file is given, the runner
 builds its config from these vars; a missing/invalid one fails loud at startup.
-Per-project settings that reference local files (`actionsDir`, `contextFile`,
+Per-project settings that reference local files (`contextFile`,
 `serviceAccountKeyPath`) point at paths baked into or mounted on the container.
+Actions can only be discovered via the `actions/` convention beside a `--config`
+file, so an env-only config serves just the built-in connectors — prefer a
+committed `polycore.json` (loaded with `--config` / `POLYCORE_RUNNER_CONFIG`).
 
 ## Tests
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@polycore/runner",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "private": false,
   "description": "Polycore runner: executes governed, read-only-constrained connectors against a customer's datastores. Runs in the customer's own infrastructure; holds scoped credentials and connects outbound to the control plane.",
   "type": "module",
@@ -30,7 +30,7 @@
     "tsx": "4.21.0",
     "ws": "8.18.3",
     "zod": "4.4.3",
-    "@polycore/protocol": "^0.1.0"
+    "@polycore/protocol": "^0.2.0"
   },
   "devDependencies": {
     "@types/node": "25.6.2",

package/src/cli.ts

@@ -1,10 +1,12 @@
 import { createServer } from "node:http";
+import { dirname } from "node:path";
 import process from "node:process";
 
 import {
   buildRunnerConfigFromEnv,
   hasEnvConfig,
   loadRunnerConfig,
+  overlayEnvSecrets,
   resolveEnvironment,
   resolveProject,
   RUNNER_CONFIG_ENV,
@@ -19,10 +21,10 @@ import { buildProjectRegistries } from "./index.js";
  * before the control-plane connection exists. Logs go to stderr; the JSON
  * result goes to stdout, so output is pipeable.
  *
- *   pnpm --filter @polycore/runner runner list --config ./runner.config.json
+ *   pnpm --filter @polycore/runner runner list --config ./polycore.json
  *   pnpm --filter @polycore/runner runner firestore.count \
  *     --project alpha --env dev --args '{"collection":"users"}' \
- *     --config ./runner.config.json
+ *     --config ./polycore.json
  */
 
 interface ParsedArgs {
@@ -82,13 +84,21 @@ function printUsage(): void {
 }
 
 /**
- * Pick the config source: an explicit file (flag or `POLYCORE_RUNNER_CONFIG`)
- * for local use, else an env-driven config when the container path is set
- * (`POLYCORE_PROJECTS` present).
+ * Pick the config source, in priority order:
+ *
+ * 1. An explicit config **file** (flag or `POLYCORE_RUNNER_CONFIG`). This is
+ *    the committed, code-as-source-of-truth path: the file declares the whole
+ *    structural surface (projects, environments, actions, context) with
+ *    portable relative paths, and any deploy-time secrets it omits
+ *    (`controlPlane` creds, runner-level `secrets`) are overlaid from env, so
+ *    the production container bakes in the file and injects only secrets.
+ * 2. Else a fully env-driven config (`POLYCORE_PROJECTS` present), the legacy
+ *    path where the whole structure arrives as env JSON.
  */
-function resolveConfig(configFlag: string | undefined): RunnerConfig {
-  const configPath = configFlag ?? process.env[RUNNER_CONFIG_ENV];
-  if (configPath !== undefined) return loadRunnerConfig(configPath);
+function resolveConfig(configPath: string | undefined): RunnerConfig {
+  if (configPath !== undefined) {
+    return overlayEnvSecrets(loadRunnerConfig(configPath), process.env);
+  }
   if (hasEnvConfig(process.env)) return buildRunnerConfigFromEnv(process.env);
   throw new Error(
     `No runner config. Pass --config <path>, set ${RUNNER_CONFIG_ENV}, ` +
@@ -133,8 +143,14 @@ async function main(): Promise<void> {
     maybeStartHealthServer((message) => process.stderr.write(`${message}\n`));
   }
 
-  const config = resolveConfig(flags.get("config"));
-  const registries = await buildProjectRegistries(config);
+  const configPath = flags.get("config") ?? process.env[RUNNER_CONFIG_ENV];
+  const config = resolveConfig(configPath);
+  // Actions are discovered from the `actions/` convention beside the config
+  // file; an env-driven config (no file) serves only the built-in connectors.
+  const registries = await buildProjectRegistries(
+    config,
+    configPath === undefined ? undefined : dirname(configPath),
+  );
 
   if (command === "list") {
     for (const [slug, registry] of registries) {

package/src/config.ts

@@ -1,4 +1,5 @@
 import { readFileSync } from "node:fs";
+import { dirname, isAbsolute, resolve } from "node:path";
 
 import { z } from "zod";
 
@@ -51,15 +52,14 @@ export const ProjectConfigSchema = z
       .refine((envs) => Object.keys(envs).length > 0, {
         message: "At least one environment must be configured.",
       }),
-    /** Local-CLI default for `runner <capability>` runs. The control plane
-     * keeps its own per-project default for front-door asks. */
-    defaultEnvironment: z.string().min(1).optional(),
     /**
-     * Absolute path to a directory of customer-authored actions for this
-     * project (one folder per action, each with an `action.ts`). Loaded and
-     * served alongside the built-in connectors.
+     * The environment an unqualified ask targets: the runner's local-CLI
+     * default AND the value advertised to the control plane, which uses it as
+     * the front-door default when a caller names no environment. One source of
+     * truth for "the default env of this project"; must be one of the
+     * `environments` keys to take effect.
      */
-    actionsDir: z.string().min(1).optional(),
+    defaultEnvironment: z.string().min(1).optional(),
     /**
      * Secret values for this project's actions, keyed by the names actions
      * declare in `secrets`. Missing keys fall back to the runner-level
@@ -132,9 +132,78 @@ export function parseRunnerConfig(json: string): RunnerConfig {
   return RunnerConfigSchema.parse(data);
 }
 
-/** Read and validate a runner config from a JSON file path. */
+/**
+ * Read and validate a runner config from a JSON file path, then absolute-
+ * resolve its file-referencing fields (`contextFile`, each environment's
+ * `serviceAccountKeyPath`) against the config file's own directory. This is
+ * what lets a committed config use portable, repo-relative paths
+ * (`"./context/app.md"`): the customer's config file is the source of truth and
+ * the runner does the path bookkeeping. Absolute paths (e.g. a mounted secret
+ * at `/secrets/read.json`) pass through unchanged. Actions are discovered by
+ * convention from an `actions/` directory beside the config file (see
+ * `buildProjectRegistries`), not via a config field.
+ */
 export function loadRunnerConfig(path: string): RunnerConfig {
-  return parseRunnerConfig(readFileSync(path, "utf8"));
+  const config = parseRunnerConfig(readFileSync(path, "utf8"));
+  return resolveConfigPaths(config, dirname(path));
+}
+
+/** Absolute-resolve one path field against `baseDir` when it is relative. */
+function resolveConfigPath(value: string, baseDir: string): string {
+  return isAbsolute(value) ? value : resolve(baseDir, value);
+}
+
+/** Absolute-resolve an environment's `serviceAccountKeyPath` against `baseDir`. */
+function resolveEnvironmentPaths(
+  env: EnvironmentConfig,
+  baseDir: string,
+): EnvironmentConfig {
+  const firestore = env.firestore;
+  if (firestore?.serviceAccountKeyPath === undefined) return env;
+  return {
+    ...env,
+    firestore: {
+      ...firestore,
+      serviceAccountKeyPath: resolveConfigPath(
+        firestore.serviceAccountKeyPath,
+        baseDir,
+      ),
+    },
+  };
+}
+
+/** Absolute-resolve one project's file-referencing fields against `baseDir`. */
+function resolveProjectPaths(
+  project: ProjectConfig,
+  baseDir: string,
+): ProjectConfig {
+  const environments = Object.fromEntries(
+    Object.entries(project.environments).map(([name, env]) => [
+      name,
+      resolveEnvironmentPaths(env, baseDir),
+    ]),
+  );
+  return {
+    ...project,
+    environments,
+    ...(project.contextFile === undefined
+      ? {}
+      : { contextFile: resolveConfigPath(project.contextFile, baseDir) }),
+  };
+}
+
+/** Absolute-resolve every project's file-referencing fields against `baseDir`. */
+function resolveConfigPaths(
+  config: RunnerConfig,
+  baseDir: string,
+): RunnerConfig {
+  const projects = Object.fromEntries(
+    Object.entries(config.projects).map(([slug, project]) => [
+      slug,
+      resolveProjectPaths(project, baseDir),
+    ]),
+  );
+  return { ...config, projects };
 }
 
 /** Env var carrying the projects map (JSON) for env-driven config. */
@@ -169,41 +238,80 @@ export function buildRunnerConfigFromEnv(
       `${RUNNER_PROJECTS_ENV} is required to build a config from the environment.`,
     );
   }
-  // Include the control-plane block only when at least one of its vars is set.
-  // Omitting it entirely keeps `controlPlane` validly optional (so `runner list`
-  // can load actions in a container without enrollment creds), while a *partial*
-  // block stays included so the schema pinpoints the missing field.
-  const cpUrl = source["POLYCORE_CONTROL_PLANE_URL"];
-  const cpRunnerId = source["POLYCORE_RUNNER_ID"];
-  const cpJoinToken = source["POLYCORE_JOIN_TOKEN"];
-  const cpSigningSecret = source["POLYCORE_SIGNING_SECRET"];
-  const hasAnyControlPlane =
-    cpUrl !== undefined ||
-    cpRunnerId !== undefined ||
-    cpJoinToken !== undefined ||
-    cpSigningSecret !== undefined;
-
+  const controlPlane = controlPlaneFromEnv(source);
+  const secrets = secretsFromEnv(source);
   const candidate = {
     projects: parseJsonEnv(projectsRaw, RUNNER_PROJECTS_ENV),
-    ...(hasAnyControlPlane
-      ? {
-          controlPlane: {
-            url: cpUrl,
-            runnerId: cpRunnerId,
-            joinToken: cpJoinToken,
-            signingSecret: cpSigningSecret,
-          },
-        }
-      : {}),
-    ...(source["POLYCORE_SECRETS"] === undefined
-      ? {}
-      : {
-          secrets: parseJsonEnv(source["POLYCORE_SECRETS"], "POLYCORE_SECRETS"),
-        }),
+    ...(controlPlane === undefined ? {} : { controlPlane }),
+    ...(secrets === undefined ? {} : { secrets }),
   };
   return RunnerConfigSchema.parse(candidate);
 }
 
+/**
+ * Overlay deploy-time secrets from the environment onto a **file-loaded**
+ * config: the committed config holds only the code-defined structure
+ * (projects, environments, actions, context), while the outbound link's creds
+ * (`controlPlane`) and runner-level action `secrets` arrive as env vars from a
+ * secret manager and are never written to the repo. Env only *fills* what the
+ * file left unset; a value already present in the file always wins.
+ *
+ * This is the counterpart to {@link loadRunnerConfig} for the production path:
+ * bake the structural config into the image, inject secrets as env at runtime.
+ */
+export function overlayEnvSecrets(
+  config: RunnerConfig,
+  source: NodeJS.ProcessEnv,
+): RunnerConfig {
+  const controlPlane = config.controlPlane ?? controlPlaneFromEnv(source);
+  const secrets = config.secrets ?? secretsFromEnv(source);
+  return {
+    ...config,
+    ...(controlPlane === undefined ? {} : { controlPlane }),
+    ...(secrets === undefined ? {} : { secrets }),
+  };
+}
+
+/**
+ * Build the control-plane block from env vars, or `undefined` when none is set
+ * (so `runner list` can load actions in a container without enrollment creds).
+ * A *partial* block is passed through to the schema so it pinpoints exactly
+ * which field is missing rather than silently dropping the block.
+ */
+function controlPlaneFromEnv(
+  source: NodeJS.ProcessEnv,
+): ControlPlaneConfig | undefined {
+  const url = source["POLYCORE_CONTROL_PLANE_URL"];
+  const runnerId = source["POLYCORE_RUNNER_ID"];
+  const joinToken = source["POLYCORE_JOIN_TOKEN"];
+  const signingSecret = source["POLYCORE_SIGNING_SECRET"];
+  if (
+    url === undefined &&
+    runnerId === undefined &&
+    joinToken === undefined &&
+    signingSecret === undefined
+  ) {
+    return undefined;
+  }
+  return ControlPlaneConfigSchema.parse({
+    url,
+    runnerId,
+    joinToken,
+    signingSecret,
+  });
+}
+
+const runnerSecretsSchema = z.record(z.string(), z.string());
+
+/** Runner-level action secrets from `POLYCORE_SECRETS`, or `undefined`. */
+function secretsFromEnv(
+  source: NodeJS.ProcessEnv,
+): Record<string, string> | undefined {
+  const raw = source["POLYCORE_SECRETS"];
+  if (raw === undefined) return undefined;
+  return runnerSecretsSchema.parse(parseJsonEnv(raw, "POLYCORE_SECRETS"));
+}
+
 function parseJsonEnv(raw: string, name: string): unknown {
   try {
     return JSON.parse(raw) as unknown;

package/src/connect.ts

@@ -47,6 +47,9 @@ export function describeProjects(
       slug,
       environments: Object.keys(project.environments),
       connectors: describeConnectors(registry),
+      ...(project.defaultEnvironment === undefined
+        ? {}
+        : { defaultEnvironment: project.defaultEnvironment }),
       ...(context === undefined ? {} : { context }),
     };
   });

package/src/index.ts

@@ -1,3 +1,6 @@
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+
 import type { LoadedAction } from "./action.js";
 import type { ProjectConfig, RunnerConfig } from "./config.js";
 import {
@@ -30,6 +33,7 @@ export {
   FirestoreEnvironmentSchema,
   hasEnvConfig,
   loadRunnerConfig,
+  overlayEnvSecrets,
   parseRunnerConfig,
   ProjectConfigSchema,
   resolveEnvironment,
@@ -102,20 +106,53 @@ export function createRegistry(
   return registry;
 }
 
+/** The conventional directory customer actions live in, beside the config. */
+export const ACTIONS_DIRNAME = "actions";
+
+/**
+ * Resolve a project's actions directory by convention, relative to the config
+ * file's directory (`baseDir`): a project's actions live in `actions/<slug>/`,
+ * and when the runner serves a single project they may live directly in
+ * `actions/`. Returns `undefined` when neither exists (a project with no
+ * actions, or an env-driven config with no file directory) — the runner then
+ * serves only the built-in connectors. There is no `actionsDir` config field:
+ * the layout is a fixed convention, exactly like the desktop `src/actions/`.
+ */
+export function resolveActionsDir(
+  baseDir: string,
+  slug: string,
+  projectCount: number,
+): string | undefined {
+  const namespaced = join(baseDir, ACTIONS_DIRNAME, slug);
+  if (existsSync(namespaced)) return namespaced;
+  const shared = join(baseDir, ACTIONS_DIRNAME);
+  if (projectCount === 1 && existsSync(shared)) return shared;
+  return undefined;
+}
+
 /**
  * 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).
+ *
+ * `actionsBaseDir` is the config file's directory; actions are discovered from
+ * the `actions/` convention under it (see {@link resolveActionsDir}). Omit it
+ * for an env-driven config with no file location — the runner then serves only
+ * the built-in connectors.
  */
 export async function buildProjectRegistries(
   config: RunnerConfig,
+  actionsBaseDir?: string,
 ): Promise<Map<string, ConnectorRegistry>> {
   const registries = new Map<string, ConnectorRegistry>();
+  const projectCount = Object.keys(config.projects).length;
   for (const [slug, project] of Object.entries(config.projects)) {
-    const actions = project.actionsDir
-      ? await loadActions(project.actionsDir)
-      : [];
+    const dir =
+      actionsBaseDir === undefined
+        ? undefined
+        : resolveActionsDir(actionsBaseDir, slug, projectCount);
+    const actions = dir ? await loadActions(dir) : [];
     registries.set(
       slug,
       createRegistry({