@devrouter/cli 0.5.6 → 0.6.0

package/README.md

@@ -8,7 +8,8 @@ can share their standard ports through TLS/SNI hostname routing.
 
 ## What devrouter owns
 
-- One strict per-repository configuration file: `.devrouter.yml`.
+- One strict local routing/profile configuration: `.devrouter.yml`.
+- Opt-in remote previews in `.devrouter.preview.yml`, with reviewed GitHub/GitLab controller source and Northflank qualification gates.
 - Machine setup, the shared `devnet` network, Traefik, local TLS, and route state.
 - Host, Docker, proxy, and dependency-only application definitions.
 - Exact-checkout devcontainer workspace lifecycle (DevPod or Devsy) for primary and linked Git worktrees.
@@ -153,7 +154,9 @@ explicit `--write-agents` or `--write-skill` flags.
 - [Domain context](./CONTEXT.md) — shared vocabulary consumed by Matt Pocock planning skills.
 - [Contributor guide](./AGENTS.md) — source map, invariants, validation, and release checklist.
 - [Examples](./examples/routing/README.md) — routing without a devcontainer; see also the [managed DevPod example](./examples/devcontainer/README.md) and [parallel workspace example](./examples/workspace/README.md).
-- [Project records](./docs/project/index.md) — dated plans and roadmap state.
+- [Project records](./docs/project/) — dated plans and roadmap state.
 - [Release history](./CHANGELOG.md) and [adaptation prompts](./upgrade-prompts/) — versioned change guidance.
 
 Run `devrouter --help` for the complete current command and option reference.
+
+Remote review environments use opt-in [planning and reviewed installation commands](docs/PREVIEWS.md).

package/assets/preview/github-sweep.yml

@@ -0,0 +1,23 @@
+name: Devrouter installation sweep
+on:
+  schedule:
+    - cron: '*/5 * * * *'
+  workflow_dispatch:
+permissions:
+  contents: read
+  id-token: write
+jobs:
+  sweep:
+    if: github.event_name == 'schedule' || github.ref_name == github.event.repository.default_branch
+    uses: rschlaefli/devrouter/.github/workflows/preview.yml@__CONTROLLER_REF__
+    with:
+      controller-ref: __CONTROLLER_REF__
+      policy-repository: __POLICY_REPOSITORY__
+      policy-ref: __POLICY_REF__
+      installation: __INSTALLATION__
+      mode: sweep
+      azure-client-id: ${{ vars.DEVROUTER_PREVIEW_AZURE_CLIENT_ID }}
+      azure-tenant-id: ${{ vars.DEVROUTER_PREVIEW_AZURE_TENANT_ID }}
+    secrets:
+      policy-read-token: ${{ secrets.DEVROUTER_PREVIEW_POLICY_READ_TOKEN }}
+      credentials: ${{ secrets.DEVROUTER_PREVIEW_CREDENTIALS }}

package/assets/preview/github.yml

@@ -0,0 +1,35 @@
+name: Devrouter previews
+on:
+  issue_comment:
+    types: [created]
+  pull_request_target:
+    types: [closed, synchronize, reopened]
+  workflow_dispatch:
+    inputs:
+      change:
+        description: PR number
+        type: string
+        required: true
+# Install a separate central caller with mode=sweep and a */5 schedule once per installation.
+permissions:
+  contents: read
+  id-token: write
+jobs:
+  preview:
+    if: >-
+      (github.event_name == 'issue_comment' && github.event.issue.pull_request && startsWith(github.event.comment.body, '/preview ')) ||
+      github.event_name == 'pull_request_target' ||
+      (github.event_name == 'workflow_dispatch' && github.ref_name == github.event.repository.default_branch)
+    uses: rschlaefli/devrouter/.github/workflows/preview.yml@__CONTROLLER_REF__
+    with:
+      controller-ref: __CONTROLLER_REF__
+      policy-repository: __POLICY_REPOSITORY__
+      policy-ref: __POLICY_REF__
+      installation: __INSTALLATION__
+      project: __PROJECT__
+      change: ${{ format('{0}', github.event.issue.number || github.event.pull_request.number || inputs.change) }}
+      azure-client-id: ${{ vars.DEVROUTER_PREVIEW_AZURE_CLIENT_ID }}
+      azure-tenant-id: ${{ vars.DEVROUTER_PREVIEW_AZURE_TENANT_ID }}
+    secrets:
+      policy-read-token: ${{ secrets.DEVROUTER_PREVIEW_POLICY_READ_TOKEN }}
+      credentials: ${{ secrets.DEVROUTER_PREVIEW_CREDENTIALS }}

package/assets/preview/gitlab-template.yml

@@ -0,0 +1,34 @@
+# Before activation, set controller project pipeline-variable overrides to no_one_allowed.
+# A trusted controller project vendors or immutably includes this template.
+spec:
+  inputs:
+    controller_image:
+      regex: '^[A-Za-z0-9][A-Za-z0-9._:/-]*@sha256:[a-f0-9]{64}$'
+    preview_mode:
+      default: sweep
+      options: [handle-event, sweep]
+    preview_project:
+      default: ''
+      regex: '^[a-z0-9-]*$'
+    preview_change:
+      default: ''
+      regex: '^[0-9]*$'
+---
+devrouter:preview:
+  image: $[[ inputs.controller_image ]]
+  stage: deploy
+  timeout: 18m
+  variables:
+    GIT_STRATEGY: none
+  id_tokens:
+    DEVROUTER_PREVIEW_AZURE_ASSERTION:
+      aud: api://AzureADTokenExchange
+  rules:
+    - if: '$CI_COMMIT_REF_PROTECTED == "true" && ($CI_PIPELINE_SOURCE == "trigger" || $CI_PIPELINE_SOURCE == "schedule")'
+    - when: never
+  script:
+    - >-
+      node /opt/devrouter/dist/devrouter.js preview '$[[ inputs.preview_mode ]]'
+      --installation /opt/devrouter-policy/installation.json
+      --project '$[[ inputs.preview_project ]]'
+      --change '$[[ inputs.preview_change ]]' --json

package/assets/preview/gitlab.yml

@@ -0,0 +1,22 @@
+# Install in a trusted controller project, outside candidate branch pipelines.
+spec:
+  inputs:
+    preview_mode:
+      default: sweep
+      options: [handle-event, sweep]
+    preview_project:
+      default: ''
+      regex: '^[a-z0-9-]*$'
+    preview_change:
+      default: ''
+      regex: '^[0-9]*$'
+---
+stages: [deploy]
+include:
+  - remote: https://raw.githubusercontent.com/rschlaefli/devrouter/__CONTROLLER_REF__/assets/preview/gitlab-template.yml
+    integrity: __TEMPLATE_INTEGRITY__
+    inputs:
+      controller_image: __CONTROLLER_IMAGE__
+      preview_mode: $[[ inputs.preview_mode ]]
+      preview_project: $[[ inputs.preview_project ]]
+      preview_change: $[[ inputs.preview_change ]]

package/assets/preview/installation.json

@@ -0,0 +1,54 @@
+{
+  "version": 1,
+  "installationId": "example",
+  "state": {
+    "containerUrl": "https://examplestore.blob.core.windows.net/previews",
+    "tokenEnv": "DEVROUTER_PREVIEW_STATE_TOKEN"
+  },
+  "maxActive": 2,
+  "maxReservedCents": 500,
+  "projects": [
+    {
+      "key": "web",
+      "forge": {
+        "kind": "github",
+        "host": "github.com",
+        "apiUrl": "https://api.github.com/",
+        "repository": "example/app",
+        "projectId": "1",
+        "botId": "2",
+        "tokenEnv": "DEVROUTER_PREVIEW_GITHUB_TOKEN"
+      },
+      "config": { "file": "app/.devrouter.yml", "sha256": "REPLACE_WITH_REVIEWED_FILE_SHA256" },
+      "manifest": {
+        "file": "app/.devrouter.preview.yml",
+        "sha256": "REPLACE_WITH_REVIEWED_FILE_SHA256"
+      },
+      "northflank": {
+        "projectId": "example-previews",
+        "tokenEnv": "DEVROUTER_PREVIEW_NORTHFLANK_TOKEN",
+        "graph": {
+          "namespace": "example",
+          "baseDomain": "preview.example.org",
+          "allowedNetworks": ["192.0.2.0/24"],
+          "resources": {
+            "web": {
+              "deploymentPlan": "nf-compute-10",
+              "readiness": { "port": "http", "path": "/health" }
+            }
+          }
+        },
+        "qualification": {
+          "fixedDeadline": false,
+          "sameEnvironment": false,
+          "deletionFence": false,
+          "scopedRuntimeSecrets": false,
+          "restrictedIngress": false
+        },
+        "runtimeSecrets": {}
+      },
+      "hourlyCents": { "web": 1 },
+      "acceptance": { "command": ["/bin/false"], "environment": [] }
+    }
+  ]
+}

package/dist/devrouter-lifecycle-worker.js

@@ -5490,7 +5490,7 @@ function retain(session, previous) {
 
 // src/core/reliability-operation-store.ts
 function installedCliVersion() {
-  return true ? "0.5.6" : "0.0.0-dev";
+  return true ? "0.6.0" : "0.0.0-dev";
 }
 function compareCliVersions(left, right) {
   const parts = (value) => value.split(".").map((part) => Number.parseInt(part, 10) || 0);
@@ -7578,6 +7578,9 @@ function resolveRepoPath(repoPath) {
 function getRepoConfigPath(repoPath) {
   return import_node_path23.default.join(resolveRepoPath(repoPath), CONFIG_FILE_NAME);
 }
+function parseRepoConfigSource(source, configPath) {
+  return parseConfig(import_yaml3.default.parse(source) ?? {}, configPath);
+}
 function loadRepoConfig(repoPath, read2 = (file) => import_node_fs19.default.readFileSync(file, "utf-8")) {
   const resolvedRepoPath = resolveRepoPath(repoPath);
   const configPath = getRepoConfigPath(resolvedRepoPath);
@@ -7587,11 +7590,10 @@ function loadRepoConfig(repoPath, read2 = (file) => import_node_fs19.default.rea
     );
   }
   const raw = read2(configPath);
-  const parsed = import_yaml3.default.parse(raw);
-  const config = parseConfig(parsed ?? {}, configPath);
+  const config = parseRepoConfigSource(raw, configPath);
   const requiredVersion = config.devrouter?.version;
   if (requiredVersion && !hasWarnedVersionMismatch) {
-    const cliVersion = true ? "0.5.6" : "0.0.0-dev";
+    const cliVersion = true ? "0.6.0" : "0.0.0-dev";
     if (cliVersion !== "0.0.0-dev" && compareSemver2(requiredVersion, cliVersion) > 0) {
       hasWarnedVersionMismatch = true;
       process.stderr.write(

package/dist/devrouter-preview-gitlab-ingress.js

@@ -0,0 +1,182 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/core/preview/ingress/gitlab.ts
+var gitlab_exports = {};
+__export(gitlab_exports, {
+  createGitLabPreviewIngress: () => createGitLabPreviewIngress
+});
+module.exports = __toCommonJS(gitlab_exports);
+var import_node_crypto = require("crypto");
+
+// src/core/preview/command.ts
+var MAX_COMMAND_BYTES = 512;
+var MAX_ALIAS_LENGTH = 63;
+var ALIAS_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+function parsePreviewCommand(text) {
+  if (Buffer.byteLength(text, "utf8") > MAX_COMMAND_BYTES || /[\r\n]/u.test(text)) {
+    return null;
+  }
+  const command = text.trim();
+  if (command === "/preview start") {
+    return { kind: "start", aliases: [] };
+  }
+  if (command.startsWith("/preview start ")) {
+    return parseStart(command.slice("/preview start ".length));
+  }
+  if (command === "/preview extend" || command === "/preview extend 1h") {
+    return { kind: "extend" };
+  }
+  if (command === "/preview stop") return { kind: "stop" };
+  if (command === "/preview status") return { kind: "status" };
+  if (command === "/preview profiles") return { kind: "profiles" };
+  return null;
+}
+function isPreviewAlias(alias) {
+  return typeof alias === "string" && alias.length <= MAX_ALIAS_LENGTH && ALIAS_PATTERN.test(alias);
+}
+function parseStart(rawAliases) {
+  const aliases = rawAliases.split(",");
+  if (aliases.some((alias) => !isPreviewAlias(alias)) || new Set(aliases).size !== aliases.length) {
+    return null;
+  }
+  return { kind: "start", aliases };
+}
+
+// src/core/preview/http.ts
+var MAX_STATE_BYTES = 1024 * 1024;
+async function readPreviewResponse(response, label, maxBytes = MAX_STATE_BYTES) {
+  if (!Number.isSafeInteger(maxBytes) || maxBytes < 1 || maxBytes > 16 * MAX_STATE_BYTES)
+    throw new Error("Invalid response size bound.");
+  const length = response.headers.get("content-length");
+  if (length !== null && (!/^\d+$/.test(length) || Number(length) > maxBytes)) {
+    await response.body?.cancel();
+    throw new Error(`${label} response exceeds its size bound.`);
+  }
+  const reader = response.body?.getReader();
+  if (!reader) throw new Error(`${label} response is empty.`);
+  const chunks = [];
+  let size = 0;
+  try {
+    for (; ; ) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      size += value.byteLength;
+      if (size > maxBytes) throw new Error(`${label} response exceeds its size bound.`);
+      chunks.push(value);
+    }
+  } finally {
+    await reader.cancel();
+  }
+  return Buffer.concat(chunks).toString("utf8");
+}
+
+// src/core/preview/forge/status.ts
+function forgeObject(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value))
+    throw new Error("Invalid forge object.");
+  return value;
+}
+function forgeId(value) {
+  const id = typeof value === "number" && Number.isSafeInteger(value) ? String(value) : value;
+  if (typeof id !== "string" || !/^[1-9][0-9]{0,19}$/.test(id))
+    throw new Error("Invalid forge numeric identity.");
+  return id;
+}
+
+// src/core/preview/ingress/gitlab.ts
+function createGitLabPreviewIngress(options) {
+  const base = new URL(options.apiUrl);
+  if (base.protocol !== "https:" || base.username || base.password || base.search || base.hash || base.port || base.pathname !== "/api/v4/" || !/^[A-Za-z0-9_./-]{1,128}$/.test(options.controllerRef) || options.controllerRef.includes("..") || !/^[a-z][a-z0-9-]{0,62}$/.test(options.installedProjectKey))
+    throw new Error("Invalid registered GitLab ingress policy.");
+  forgeId(options.controllerProjectId);
+  forgeId(options.candidateProjectId);
+  return async (request) => {
+    if (request.method !== "POST") return new Response(null, { status: 405 });
+    let secret;
+    try {
+      secret = await options.hookSecret();
+    } catch {
+      return new Response(null, { status: 503 });
+    }
+    const presented = request.headers.get("x-gitlab-token") ?? "";
+    if (secret.length < 32 || secret.length > 256 || presented.length > 256 || Buffer.byteLength(secret) !== Buffer.byteLength(presented) || !(0, import_node_crypto.timingSafeEqual)(Buffer.from(secret), Buffer.from(presented)))
+      return new Response(null, { status: 401 });
+    if (request.headers.get("content-type")?.split(";")[0] !== "application/json")
+      return new Response(null, { status: 415 });
+    if (request.headers.get("x-gitlab-event") !== "Note Hook" || !/^[a-f0-9-]{36}$/i.test(request.headers.get("x-gitlab-event-uuid") ?? ""))
+      return new Response(null, { status: 400 });
+    let payload;
+    try {
+      payload = forgeObject(
+        JSON.parse(await readPreviewResponse(new Response(request.body), "GitLab hook", 64 * 1024))
+      );
+    } catch {
+      return new Response(null, { status: 400 });
+    }
+    try {
+      if (payload.object_kind !== "note") return new Response(null, { status: 204 });
+      const note = forgeObject(payload.object_attributes);
+      if (note.noteable_type !== "MergeRequest") return new Response(null, { status: 204 });
+      const merge = forgeObject(payload.merge_request), project = forgeObject(payload.project);
+      if (forgeId(project.id) !== options.candidateProjectId || forgeId(note.project_id) !== options.candidateProjectId || note.action !== "create" || note.system !== false || note.created_at !== note.updated_at || note.line_code || typeof note.note !== "string" || !parsePreviewCommand(note.note) || merge.target_project_id !== Number(options.candidateProjectId) || merge.source_project_id !== Number(options.candidateProjectId))
+        return new Response(null, { status: 204 });
+      const change = forgeId(merge.iid);
+      forgeId(note.id);
+      let token;
+      try {
+        token = await options.triggerToken();
+      } catch {
+        return new Response(null, { status: 503 });
+      }
+      if (!token || /\s/.test(token)) return new Response(null, { status: 503 });
+      let response;
+      try {
+        response = await (options.fetch ?? fetch)(
+          new URL(`projects/${options.controllerProjectId}/trigger/pipeline`, base),
+          {
+            method: "POST",
+            redirect: "error",
+            signal: AbortSignal.timeout(1e4),
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({
+              token,
+              ref: options.controllerRef,
+              inputs: {
+                preview_mode: "handle-event",
+                preview_project: options.installedProjectKey,
+                preview_change: change
+              }
+            })
+          }
+        );
+      } catch {
+        return new Response(null, { status: 503 });
+      }
+      await response.body?.cancel();
+      return new Response(null, { status: response.ok ? 202 : 503 });
+    } catch {
+      return new Response(null, { status: 400 });
+    }
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  createGitLabPreviewIngress
+});