@jini-ai/agent-plugins 0.6.17 → 0.6.19

package/railway/deploy-configs/railway.mjs

@@ -0,0 +1,135 @@
+/**
+ * @file The Railway deploy-config generator: renders `railway.json` from the host's
+ * `DeploymentDescriptor`. Pure: no I/O; the host passes the kit and appends its own notes after render.
+ * Schema verified via context7 against Railway's own current docs (`/railwayapp/docs`), fetched
+ * 2026-08-31, not written from memory:
+ * - `build.builder: "DOCKERFILE"` + `build.dockerfilePath` and `deploy.healthcheckPath` /
+ *   `deploy.restartPolicyType: "ON_FAILURE"` are confirmed real config-as-code fields (the Rails and
+ *   Jupyter deploy guides' own worked `railway.json` examples).
+ * - Railway's config-as-code has NO env-var / secrets section at all (variables are managed only via
+ *   the Dashboard, the CLI (`railway variables set`), or the GraphQL API). Emitting an invented
+ *   `envVars`/`variables` key would just be ignored or misread, so this renderer emits none, and
+ *   every secret appears in `notes` instead.
+ * - Railway's config-as-code has NO volume field either (the docs' own reference snippet is captioned
+ *   "railway.toml format (no volume mount support)"). The volume-creation step appears in `notes`,
+ *   via the plain CLI command the docs show (`railway volume add --mount-path <path>`).
+ * - No plain single-service `region` field exists in `railway.json`/`railway.toml`, only
+ *   `deploy.multiRegionConfig`, a map of region to replica count. Pinning to exactly one region is a
+ *   single-entry map with `numReplicas: 1`: a server whose state lives on one volume must run as
+ *   exactly one replica.
+ *
+ * Plain JS by owner decision (2026-09-29). Built through `JSON.stringify`, so it needs no injection
+ * guard.
+ */
+
+/**
+ * @typedef {{ readonly name: string, readonly requirement: "boot-blocking" | "recommended" }} DeploymentSecret
+ * @typedef {{ readonly appName: string, readonly port: number, readonly dockerfilePath: string, readonly volumeMountPath: string, readonly volumeName: string, readonly healthCheckPath: string, readonly secrets: readonly DeploymentSecret[] }} DeploymentDescriptor
+ * @typedef {{ readonly region: string, readonly env?: Readonly<Record<string, string>> }} RenderDeployConfigOptions
+ * @typedef {{ readonly assertNoConfigInjection: (fieldLabel: string, value: string) => void, readonly validationError: (message: string) => Error, readonly migrationsNote: string }} DeployConfigKit
+ * @typedef {{ readonly filename: string, readonly contents: string, readonly notes: readonly string[] }} RenderedDeployConfig
+ */
+
+/**
+ * Railway's 4 selectable region identifiers (service settings, apply identically to
+ * `multiRegionConfig` keys). Source: context7 `/railwayapp/docs`, "Deployment regions table",
+ * fetched 2026-08-31.
+ */
+export const RAILWAY_VALID_REGIONS = Object.freeze(["us-west2", "us-east4-eqdc4a", "europe-west4-drams3a", "asia-southeast1-eqsg3a"]);
+
+/**
+ * True when `value` holds a C0 control (NUL, tab, LF, CR…), DEL or a C1 control. Checked by code
+ * point rather than a regex character class, which eslint's no-control-regex rejects.
+ * @param {string} value
+ * @returns {boolean}
+ * @complexity O(n) for n UTF-16 code units.
+ */
+function hasControlCharacter(value) {
+  for (let index = 0; index < value.length; index++) {
+    const code = value.charCodeAt(index);
+    if (code < 0x20 || (code >= 0x7f && code <= 0x9f)) {
+      return true;
+    }
+  }
+  return false;
+}
+
+/**
+ * railway.json cannot hold variables, so each explicit non-secret one the host passes in `options.env`
+ * becomes a `railway variables set` step, single-quoted for the shell.
+ * Values with control characters (C0, DEL, C1) are refused rather than quoted: a raw newline breaks a
+ * copy-pasted one-line command, NUL cannot exist in a shell argument at all, and the only quoting that
+ * spells them (`$'...'`) is not POSIX sh. Like the Render generator's newline refusal, the operator
+ * sets such a value through the Dashboard instead.
+ * @param {{ env: Readonly<Record<string, string>>, secrets: readonly DeploymentSecret[] }} input
+ * @param {DeployConfigKit} kit
+ * @returns {string[]}
+ * @throws {Error} For an invalid name, a non-string value, a declared secret name or a value with a
+ * control character; never echoes the value.
+ * @complexity O(n + s) for n variable characters and s declared secrets.
+ */
+function envNotes({ env, secrets }, kit) {
+  const secretNames = new Set(secrets.map((secret) => secret.name));
+  return Object.entries(env).map(([name, value]) => {
+    if (!/^[A-Za-z_]\w*$/.test(name) || typeof value !== "string" || secretNames.has(name)) {
+      throw kit.validationError("env must contain only non-secret string variables with valid names");
+    }
+    if (hasControlCharacter(value)) {
+      throw kit.validationError(
+        `env ${name} contains a newline or other control character, which a copy-pasteable shell command cannot carry — set it in the Railway Dashboard instead`
+      );
+    }
+    return `Set ${name} with: railway variables set ${name}='${value.replace(/'/g, "'\\''")}' — railway.json has no env-var section.`;
+  });
+}
+
+/**
+ * @param {DeploymentDescriptor} descriptor
+ * @param {RenderDeployConfigOptions} options
+ * @param {DeployConfigKit} kit
+ * @returns {RenderedDeployConfig}
+ */
+function render(descriptor, options, kit) {
+  const region = options.region.trim();
+  if (!region) {
+    throw kit.validationError("--region is required for --target railway (no default region is assumed)");
+  }
+  if (!RAILWAY_VALID_REGIONS.includes(region)) {
+    throw kit.validationError(`--region "${region}" is not a valid Railway region — one of: ${RAILWAY_VALID_REGIONS.join(", ")}`);
+  }
+
+  const variableNotes = envNotes({ env: options.env ?? {}, secrets: descriptor.secrets }, kit);
+  const config = {
+    $schema: "https://railway.com/railway.schema.json",
+    build: {
+      builder: "DOCKERFILE",
+      dockerfilePath: descriptor.dockerfilePath,
+    },
+    deploy: {
+      healthcheckPath: descriptor.healthCheckPath,
+      restartPolicyType: "ON_FAILURE",
+      multiRegionConfig: {
+        [region]: { numReplicas: 1 },
+      },
+    },
+  };
+
+  const contents = `${JSON.stringify(config, null, 2)}\n`;
+
+  const notes = [
+    `Create the volume once, before the first deploy — railway.json has no field for this (Railway's ` +
+      `config-as-code does not support declaring volumes): railway volume add --mount-path ${descriptor.volumeMountPath} ` +
+      `(name it "${descriptor.volumeName}" to match the host's other platform configs).`,
+    kit.migrationsNote,
+    ...descriptor.secrets.map(
+      (secret) =>
+        `Set ${secret.name} (${secret.requirement}) with: railway variables set ${secret.name}=<value> — railway.json has no ` +
+        "env-var section; Railway manages variables outside config-as-code."
+    ),
+    ...variableNotes,
+  ];
+
+  return { filename: "railway.json", contents, notes };
+}
+
+export default { render };

package/railway/deploy-ops/railway.mjs

@@ -0,0 +1,167 @@
+/** Railway GraphQL adapter. The host owns auth, HTTP policy, cancellation, polling and auditing. */
+const ENDPOINT = "https://backboard.railway.com/graphql/v2";
+const UUID = /^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/i;
+const QUERIES = {
+  targets: `query targets($workspaceId: String) {
+  projects(workspaceId: $workspaceId, first: 10) {
+    pageInfo { hasNextPage }
+    edges { node { id name environments(first: 10) {
+      pageInfo { hasNextPage }
+      edges { node { id name serviceInstances(first: 50) {
+        pageInfo { hasNextPage }
+        edges { node { serviceId serviceName } }
+      } } }
+    } } }
+  }
+}`,
+  deployment: `query deployment($id: String!) {
+  deployment(id: $id) { id serviceId environmentId status }
+}`,
+  latest: `query latest($serviceId: String!, $environmentId: String!) {
+  serviceInstance(serviceId: $serviceId, environmentId: $environmentId) {
+    latestDeployment { id serviceId environmentId status }
+  }
+}`,
+  deploy: `mutation deploy($serviceId: String!, $environmentId: String!, $commitSha: String) {
+  serviceInstanceDeployV2(serviceId: $serviceId, environmentId: $environmentId, commitSha: $commitSha)
+}`,
+  logs: `query logs($deploymentId: String!, $limit: Int) {
+  deploymentLogs(deploymentId: $deploymentId, limit: $limit) { timestamp message severity }
+}`,
+  variables: `query variables($projectId: String!, $environmentId: String!, $serviceId: String) {
+  variables(projectId: $projectId, environmentId: $environmentId, serviceId: $serviceId)
+}`,
+  set: `mutation set($input: VariableUpsertInput!) { variableUpsert(input: $input) }`,
+  unset: `mutation unset($input: VariableDeleteInput!) { variableDelete(input: $input) }`,
+};
+
+/** Never echo GraphQL errors: partial data and provider diagnostics may contain variable values. */
+async function gql(ctx, { query, variables }) {
+  const response = await ctx.send({ method: "POST", url: ENDPOINT, body: { query, variables } });
+  if (Array.isArray(response.json?.errors)) ctx.fail("Railway could not complete the request. Check the credential and target; check status before retrying a write.");
+  if (response.truncated || !response.json?.data || typeof response.json.data !== "object") ctx.fail("Railway returned an incomplete response. Check status before retrying a write.");
+  return response.json.data;
+}
+function id({ ctx, value }, _options = {}) {
+  if (typeof value !== "string" || !UUID.test(value)) ctx.fail("Railway IDs must be UUIDs.");
+  return value;
+}
+/** Project is needed for variables; environment/service are needed for every deploy operation. */
+function targetIds({ ctx, target }, _options = {}) {
+  if (typeof target !== "string" || target.split(":").length !== 3) ctx.fail("Choose a Railway target from list targets: project:environment:service.");
+  const [projectId, environmentId, serviceId] = target.split(":").map(value => id({ ctx, value }));
+  return { projectId, environmentId, serviceId };
+}
+function name({ ctx, value }, _options = {}) {
+  if (typeof value !== "string" || !/^[A-Za-z_]\w{0,127}$/.test(value)) ctx.fail("Secret name must be an environment variable name.");
+  return value;
+}
+function text({ value }, _options = {}) { return String(value ?? "").slice(0, 2000); }
+/** Refuse partial discovery rather than inventing service/environment combinations or hiding pages. */
+function nodes({ ctx, connection, cap }, _options = {}) {
+  if (!Array.isArray(connection?.edges) || typeof connection?.pageInfo?.hasNextPage !== "boolean") ctx.fail("Railway target discovery returned incomplete data.");
+  if (connection.pageInfo.hasNextPage || connection.edges.length > cap) ctx.fail("Railway target discovery is incomplete at its limit. Supply an exact project:environment:service target from the Railway console.");
+  if (connection.edges.some(edge => !edge?.node || typeof edge.node !== "object")) ctx.fail("Railway target discovery returned invalid data.");
+  return connection.edges.map(edge => edge.node);
+}
+function label({ ctx, value }, _options = {}) {
+  if (typeof value !== "string" || !value) ctx.fail("Railway target discovery returned an invalid name.");
+  return text({ value });
+}
+/** One bounded query: at most 10 projects × 10 environments × 50 actual service instances. */
+async function listTargets(ctx, { org } = {}) {
+  const variables = org === undefined ? {} : { workspaceId: id({ ctx, value: org }) };
+  const data = await gql(ctx, { query: QUERIES.targets, variables });
+  const targets = nodes({ ctx, connection: data.projects, cap: 10 }).flatMap(project => projectTargets({ ctx, project }));
+  if (targets.length > 500) ctx.fail("Railway target discovery exceeds 500 targets. Supply an exact target from the Railway console.");
+  return { platform: "railway", targets };
+}
+function projectTargets({ ctx, project }, _options = {}) {
+  const projectId = id({ ctx, value: project.id });
+  const projectName = label({ ctx, value: project.name });
+  return nodes({ ctx, connection: project.environments, cap: 10 }).flatMap(environment => {
+    const environmentId = id({ ctx, value: environment.id });
+    const environmentName = label({ ctx, value: environment.name });
+    return nodes({ ctx, connection: environment.serviceInstances, cap: 50 }).map(instance => ({
+      id: `${projectId}:${environmentId}:${id({ ctx, value: instance.serviceId })}`,
+      name: text({ value: `${projectName} / ${environmentName} / ${label({ ctx, value: instance.serviceName })}` }),
+    }));
+  });
+}
+function overall({ status }, _options = {}) {
+  const states = {
+    SUCCESS: "healthy", FAILED: "failing", CRASHED: "failing",
+    BUILDING: "deploying", DEPLOYING: "deploying", INITIALIZING: "deploying", QUEUED: "deploying", WAITING: "deploying",
+    REMOVED: "stopped", REMOVING: "stopped", SLEEPING: "stopped", SKIPPED: "stopped",
+  };
+  return Object.hasOwn(states, status) ? states[status] : "unknown";
+}
+async function readDeployment({ ctx, ids, runId }, _options = {}) {
+  const { serviceId, environmentId } = ids;
+  const query = runId === undefined ? QUERIES.latest : QUERIES.deployment;
+  const variables = runId === undefined ? { serviceId, environmentId } : { id: id({ ctx, value: runId }) };
+  const data = await gql(ctx, { query, variables });
+  if (runId !== undefined) return data.deployment;
+  if (!data.serviceInstance) ctx.fail("Railway did not return the service instance.");
+  return data.serviceInstance.latestDeployment;
+}
+/** Ownership is read with status, avoiding a separate membership request and its race. */
+async function deployment({ ctx, ids, runId }, _options = {}) {
+  const result = await readDeployment({ ctx, ids, runId });
+  if (result === null && runId === undefined) return null;
+  if (!result || typeof result.status !== "string") ctx.fail("Railway did not return a deployment status.");
+  id({ ctx, value: result.id });
+  if (runId !== undefined && result.id !== runId) ctx.fail("Railway returned a different deployment.");
+  if (result.serviceId !== ids.serviceId || result.environmentId !== ids.environmentId) ctx.fail("The Railway deployment does not belong to this target.");
+  return result;
+}
+async function status(ctx, { target, runId }) {
+  const result = await deployment({ ctx, ids: targetIds({ ctx, target }), runId });
+  const state = result ? overall({ status: result.status }) : "stopped";
+  return { platform: "railway", target, state, summary: result ? `Deployment: ${text({ value: result.status })}` : "No deployment exists for this service.", items: result ? [{ id: result.id, state: text({ value: result.status }) }] : [], checkedAt: ctx.nowIso() };
+}
+async function deploy(ctx, { target, ref }) {
+  const { serviceId, environmentId } = targetIds({ ctx, target });
+  if (ref !== undefined && (typeof ref !== "string" || !/^[a-f0-9]{40}$/i.test(ref))) ctx.fail("Railway ref must be a full 40-character commit SHA, or omitted to use the service's current commit.");
+  const data = await gql(ctx, { query: QUERIES.deploy, variables: { serviceId, environmentId, ...(ref === undefined ? {} : { commitSha: ref }) } });
+  // No retries: a lost response may still mean Railway accepted the deployment.
+  const runId = id({ ctx, value: data.serviceInstanceDeployV2 });
+  return { platform: "railway", target, started: true, runId, ...(ref === undefined ? {} : { sha: ref }), summary: "Railway accepted the deployment. Wait for its status before checking the live site." };
+}
+function logLine({ ctx, entry }, _options = {}) {
+  if (!entry || typeof entry.message !== "string") ctx.fail("Railway returned an invalid log entry.");
+  return { message: text({ value: entry.message }), ...(typeof entry.timestamp === "string" ? { at: text({ value: entry.timestamp }) } : {}), ...(typeof entry.severity === "string" ? { level: text({ value: entry.severity }) } : {}) };
+}
+async function logs(ctx, { target, runId, limit }) {
+  if (!Number.isInteger(limit) || limit < 1 || limit > 500) ctx.fail("Log limit must be between 1 and 500.");
+  const result = await deployment({ ctx, ids: targetIds({ ctx, target }), runId });
+  if (!result) return { platform: "railway", target, lines: [], truncated: false };
+  // Read one extra entry to detect a full page without implying this is a streaming log feed.
+  const data = await gql(ctx, { query: QUERIES.logs, variables: { deploymentId: result.id, limit: limit + 1 } });
+  if (!Array.isArray(data.deploymentLogs)) ctx.fail("Railway did not return log entries.");
+  const entries = data.deploymentLogs;
+  const lines = entries.slice(0, limit).map(entry => logLine({ ctx, entry }));
+  return { platform: "railway", target, lines, truncated: entries.length > limit || entries.slice(0, limit).some(entry => entry.message.length > 2000) };
+}
+/** Variable values arrive from Railway but are discarded here; no readSecret capability is exported. */
+async function listSecrets(ctx, { target }) {
+  const data = await gql(ctx, { query: QUERIES.variables, variables: targetIds({ ctx, target }) });
+  if (!data.variables || typeof data.variables !== "object" || Array.isArray(data.variables)) ctx.fail("Railway did not return a variables map.");
+  const names = Object.keys(data.variables);
+  return { secrets: names.slice(0, 500).map(value => ({ name: name({ ctx, value }) })), truncated: names.length > 500 };
+}
+async function setSecret(ctx, { target, name: key, value }) {
+  const input = { ...targetIds({ ctx, target }), name: name({ ctx, value: key }), value, skipDeploys: true };
+  const data = await gql(ctx, { query: QUERIES.set, variables: { input } });
+  if (data.variableUpsert !== true) ctx.fail("Railway did not confirm the variable write. Check the provider console before retrying.");
+  return {};
+}
+/** The host refuses removal without revision metadata; this required export only defines the vendor call. */
+async function unsetSecret(ctx, { target, name: key }) {
+  const input = { ...targetIds({ ctx, target }), name: name({ ctx, value: key }) };
+  const data = await gql(ctx, { query: QUERIES.unset, variables: { input } });
+  if (data.variableDelete !== true) ctx.fail("Railway did not confirm the variable removal. Check the provider console before retrying.");
+  return {};
+}
+const secretCapabilities = { appliesOn: "next-deploy", supportsStaging: true };
+export default { listTargets, deploy, status, logs, secretCapabilities, listSecrets, setSecret, unsetSecret };

package/railway/mcp.json

@@ -0,0 +1,4 @@
+{
+  "$schema": "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json",
+  "mcpServers": {}
+}

package/railway/plugin.json

@@ -0,0 +1,45 @@
+{
+  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
+  "name": "railway",
+  "version": "1.0.0",
+  "description": "Deploys existing Railway services, checks deployment status and logs, stages variables, and generates railway.json for the host's server.",
+  "author": "Tovu",
+  "license": "Apache-2.0",
+  "extensions": {
+    "tovu": {
+      "maturity": "soon",
+      "displayName": "Railway",
+      "summary": "Deploys and checks an existing Railway service, stages variables, and writes the server settings file.",
+      "id": "tovu/railway",
+      "provides": [
+        "deploy-config:railway",
+        "deploy-ops:railway"
+      ],
+      "credentialCards": [
+        {
+          "target": "railway",
+          "title": "Connect Railway",
+          "label": "Railway API",
+          "ownedApiLabel": "Railway API",
+          "category": "hosting",
+          "intro": "Save a Railway token for deploying this site from Tovu. The assistant can look up your Railway projects, deploy your server, check status and logs, and stage variables. Writing the deployment settings file needs no token. Untested: this connection hasn't been tried end to end yet.",
+          "usedFor": [
+            "Looks up your Railway projects",
+            "Deploys your server"
+          ],
+          "keyHint": "In Railway, open Account Settings → Tokens → Create Token and select the workspace that holds the site. The token can do anything in that workspace; Railway has no read-only option.",
+          "saveKind": "api",
+          "helpUrl": "https://railway.com/account/tokens",
+          "helpLabel": "Create a Railway token",
+          "baseUrl": "https://backboard.railway.com/graphql/v2"
+        }
+      ]
+    }
+  },
+  "keywords": [
+    "railway",
+    "deploy",
+    "deploy-config:railway",
+    "deploy-ops:railway"
+  ]
+}

package/railway/skills/railway/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: railway
+description: Deploy existing Railway services, inspect status and logs, stage variables, and generate railway.json for the host's server.
+---
+
+# Railway server deployment
+
+This plugin is **Untested**: the connection has not been tried end to end with live credentials.
+Offline fake tests do not establish live compatibility. Deploying ships code, not site content.
+Use the deployment tools in chat, never Bash or a Railway CLI.
+
+## Railway token
+
+Choose the card yourself from its `usedFor` list. Reuse a saved key or working sign-in for that
+task. Never offer a replacement unless the person asks. Saving a token deploys nothing.
+
+First check `content_read.custom_credential {}` for a saved token and reuse it.
+Otherwise open **Connect Railway** with
+`credential_save { kind: "plugin-provider", target: "railway" }`; it saves as `Railway API`.
+The person creates the token under Account Settings → Tokens and selects the site's workspace.
+A project token from a project's settings will not work here.
+Never ask for a token in chat. Never offer to replace a working token unless asked.
+
+Railway has no save-time probe. `custom_credential_verify` cannot tell whether a Railway key
+works: it sends a GET to the GraphQL URL, so the result is "unreachable". Use
+`deployment_ops_list_targets { platform: "railway", org: "<workspace UUID>" }` to check the key.
+The existing `org` input carries the workspace ID, not its display name. Omitting it lists the
+personal projects accessible to an account token; supply it for a workspace token.
+
+## Select and deploy an existing service
+
+List targets first. Each target is `projectUUID:environmentUUID:serviceUUID`; copy the returned
+ID exactly. Discovery lists actual service instances, bounded to 10 projects, 10 environments
+per project, 50 instances per environment and 500 targets overall. If discovery is incomplete,
+it refuses the result. Obtain the exact IDs from Railway's console rather than guessing a target.
+No service, disk, region, volume or billing resource is created by this adapter.
+
+Call `deployment_ops_deploy` with `platform: "railway"` and the selected `target`.
+`ref` accepts a full 40-character commit SHA only. Omitting it deploys the service's currently
+associated commit; it does not promise the latest branch head. Branches and tags are refused.
+The service must already have a source configured in Railway.
+
+A returned `started: true` means Railway accepted the request. Keep its `runId` and pass it
+with the same target to `deployment_ops_wait` until finished, then check the live URL with
+`fetch_live_url`. Status without a run ID inspects the latest deployment. Unknown vendor states
+remain unknown. Read bounded runtime logs with `deployment_ops_logs`; logs are snapshots,
+not a stream. If a write loses its connection, check status before deciding whether to retry.
+Never automatically retry a deployment or variable write.
+
+## Variables
+
+Use `deployment_ops_list_secrets` to list names only. Use the host's masked entry/site-key flow
+and overwrite confirmation with `deployment_ops_set_secret`. Values never belong in chat.
+Writes use `skipDeploys: true`: stage all variables, then deploy once. Running instances keep
+their current values until that deploy. Secret readback/copy is unavailable.
+Removal must be done in the provider console: Railway's list has no digest or update time,
+so the host cannot perform its required revision check for `deployment_ops_unset_secret`.
+
+## Generate the settings file
+
+Writing `railway.json` needs **no token**. Do not open a key card for that task.
+Follow the host guidance first: it names how this host generates `railway.json`. The
+generator uses the host's server descriptor for the Dockerfile, port and health check. Follow
+its notes to create the volume and set required variables before the first deploy. Secret
+values never appear in the generated file. Keep one instance when state lives on the volume
+(SQLite).

package/railway/tovu-deploy-configs.json

@@ -0,0 +1,16 @@
+{
+  "schemaVersion": 1,
+  "generators": [
+    {
+      "id": "railway",
+      "label": "Railway",
+      "module": "deploy-configs/railway.mjs",
+      "candidatePaths": [
+        {
+          "path": "railway.toml",
+          "order": 3
+        }
+      ]
+    }
+  ]
+}

package/railway/tovu-deploy-ops.json

@@ -0,0 +1,11 @@
+{
+  "schemaVersion": 1,
+  "platforms": [
+    {
+      "id": "railway",
+      "label": "Railway",
+      "module": "deploy-ops/railway.mjs",
+      "hosts": ["backboard.railway.com"]
+    }
+  ]
+}

package/render/deploy-configs/render.mjs

@@ -0,0 +1,141 @@
+/**
+ * @file The Render deploy-config generator: renders `render.yaml` (a Render Blueprint) from the
+ * host's `DeploymentDescriptor`. Pure: no I/O; the host passes the kit (`assertNoConfigInjection`,
+ * `validationError(message)`, `migrationsNote`). Schema verified via context7 against Render's own
+ * current docs (`/websites/render`, "Blueprint Specification" + `llms-full.txt`'s example
+ * `render.yaml`), fetched 2026-08-31, not written from memory:
+ * - A Dockerfile-built `type: web` service uses `runtime: docker`; with no `rootDir` given, the build
+ *   looks for `Dockerfile` at the repo root by default, so no `dockerfilePath`-shaped override field
+ *   is emitted.
+ * - `region` is a fixed enum (see {@link RENDER_VALID_REGIONS}), "cannot be modified after service
+ *   creation", which is exactly why this renderer refuses to guess or default it.
+ * - `envVars[].sync: false` is Render's mechanism for "this key exists, prompt for its value in the
+ *   Dashboard". No value ever appears next to it here.
+ * - `disk` (name/mountPath/sizeGB) is valid on `type: web` for paid services, which is why
+ *   `plan: starter` is set explicitly: the free tier does not support persistent disks at all.
+ * - Every web service must bind `0.0.0.0:$PORT`, defaulting to 10000 if unset, so `PORT` is declared
+ *   from the descriptor's container port.
+ *
+ * Host-specific runtime switches and follow-up notes are the host's input: it passes non-secret
+ * variables in `options.env` and appends its own notes after render. This module defaults none.
+ */
+
+/**
+ * @typedef {{ readonly name: string, readonly requirement: "boot-blocking" | "recommended" }} DeploymentSecret
+ * @typedef {{ readonly appName: string, readonly port: number, readonly dockerfilePath: string, readonly volumeMountPath: string, readonly volumeName: string, readonly healthCheckPath: string, readonly secrets: readonly DeploymentSecret[] }} DeploymentDescriptor
+ * @typedef {{ readonly region: string, readonly env?: Readonly<Record<string, string>> }} RenderDeployConfigOptions
+ * @typedef {{ readonly assertNoConfigInjection: (fieldLabel: string, value: string) => void, readonly validationError: (message: string) => Error, readonly migrationsNote: string }} DeployConfigKit
+ * @typedef {{ readonly filename: string, readonly contents: string, readonly notes: readonly string[] }} RenderedDeployConfig
+ */
+
+/**
+ * Render's Blueprint `region` enum. Source: context7 `/websites/render`, "Blueprint Specification >
+ * region": "The region field specifies where a service is deployed, with options including oregon,
+ * ohio, virginia, frankfurt, and singapore. This value cannot be modified after service creation."
+ * Fetched 2026-08-31.
+ */
+export const RENDER_VALID_REGIONS = Object.freeze(["oregon", "ohio", "virginia", "frankfurt", "singapore"]);
+
+/**
+ * Quotes a value as a YAML double-quoted scalar. JSON string escapes are valid YAML escapes; YAML
+ * additionally forbids raw DEL, C1 controls and U+FFFE/U+FFFF, so those are escaped too.
+ * @param {string} value
+ * @returns {string}
+ * @complexity O(n) in the value length.
+ */
+function yamlString(value) {
+  return JSON.stringify(value).replace(/[\u007f-\u009f\ufffe\uffff]/g, (char) => `\\u${char.charCodeAt(0).toString(16).padStart(4, "0")}`);
+}
+
+/** Upper-case environment variable names only (plan v2 §5.1). */
+const ENV_NAME = /^[A-Z][A-Z0-9_]*$/;
+
+/**
+ * Checks the explicit non-secret variables the host passes in `options.env`. Values are strings
+ * with no line break: a Blueprint value is one quoted scalar, and a multi-line secret-shaped value
+ * belongs in the platform's secret store instead.
+ * @param {{ env: Readonly<Record<string, string>>, secrets: readonly DeploymentSecret[] }} input
+ * @param {DeployConfigKit} kit
+ * @returns {[string, string][]}
+ * @throws {Error} For an invalid name, a non-string or multi-line value, or a declared secret name; never
+ *   echoes the value.
+ * @complexity O(n + s) for n variables and s declared secrets.
+ */
+function checkedEnv({ env, secrets }, kit) {
+  const secretNames = new Set(secrets.map((secret) => secret.name));
+  const entries = Object.entries(env);
+  for (const [name, value] of entries) {
+    if (!ENV_NAME.test(name) || typeof value !== "string" || /[\r\n]/.test(value) || secretNames.has(name)) {
+      throw kit.validationError("env must contain only non-secret single-line string variables with upper-case names");
+    }
+  }
+  return entries;
+}
+
+/**
+ * `PORT` comes from the descriptor unless `options.env` overrides it; explicit entries follow, then
+ * each declared secret as `sync: false`.
+ * @param {DeploymentDescriptor} descriptor
+ * @param {Readonly<Record<string, string>>} env
+ * @param {DeployConfigKit} kit
+ * @returns {string}
+ * @complexity O(n + s) for n variables and s declared secrets.
+ */
+function renderEnvVarsBlock(descriptor, env, kit) {
+  const explicit = checkedEnv({ env, secrets: descriptor.secrets }, kit);
+  const lines = [];
+  if (!("PORT" in env)) lines.push("      - key: PORT", `        value: "${descriptor.port}"`);
+  for (const [name, value] of explicit) lines.push(`      - key: ${name}`, `        value: ${yamlString(value)}`);
+  for (const secret of descriptor.secrets) {
+    lines.push(`      - key: ${secret.name}`, "        sync: false");
+  }
+  return lines.join("\n");
+}
+
+/**
+ * @param {DeploymentDescriptor} descriptor
+ * @param {RenderDeployConfigOptions} options
+ * @param {DeployConfigKit} kit
+ * @returns {RenderedDeployConfig}
+ */
+function render(descriptor, options, kit) {
+  const region = options.region.trim();
+  if (!region) {
+    throw kit.validationError("--region is required for --target render (no default region is assumed)");
+  }
+  if (!RENDER_VALID_REGIONS.includes(region)) {
+    throw kit.validationError(`--region "${region}" is not a valid Render region — one of: ${RENDER_VALID_REGIONS.join(", ")}`);
+  }
+  // `region` itself needs no separate injection check here: it just passed the allow-list above, so
+  // it can only be one of RENDER_VALID_REGIONS's five known-safe literals.
+  kit.assertNoConfigInjection("the derived Render service name", descriptor.appName);
+  kit.assertNoConfigInjection("the derived Render disk name", descriptor.volumeName);
+
+  const contents = `services:
+  - type: web
+    name: ${descriptor.appName}
+    runtime: docker
+    plan: starter
+    region: ${region}
+    healthCheckPath: ${descriptor.healthCheckPath}
+    envVars:
+${renderEnvVarsBlock(descriptor, options.env ?? {}, kit)}
+    disk:
+      name: ${descriptor.volumeName}
+      mountPath: ${descriptor.volumeMountPath}
+      sizeGB: 10
+`;
+
+  const notes = [
+    "Persistent disks require a paid plan — \"plan: starter\" above is the cheapest tier that supports " +
+      "one; the free tier cannot attach this disk at all.",
+    "Render prompts for each `sync: false` env var's real value in the Dashboard the first time this " +
+      "Blueprint is applied — no value is stored in this file.",
+    kit.migrationsNote,
+    ...descriptor.secrets.map((secret) => `${secret.name} is ${secret.requirement} — set its value in the Render Dashboard.`),
+  ];
+
+  return { filename: "render.yaml", contents, notes };
+}
+
+export default { render };