@devrouter/cli 0.5.5 → 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.
@@ -82,6 +83,14 @@ Dev Container clients still see the full source configuration. Check
 `devrouter status` or `devrouter doctor` when you need the desired, active, and
 drift state.
 
+Managed repositories can also declare a separate runtime variant in
+`managedRuntime.variants` and select it with
+`devrouter ensure . --variant <name>`. A profile continues to select resources;
+the variant changes the managed process startup input. Declared
+loopback-only service ports are available through `devrouter env . --json`. See
+the [managed devcontainer contract](./docs/DEVCONTAINER.md) for ownership,
+Compose, recovery, and capacity rules.
+
 Automation can inspect the same profile contract without touching a workspace,
 Docker, DevPod, Devsy, Traefik, Git, or global state:
 
@@ -145,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/bin/devrouter-process

@@ -9,8 +9,9 @@ Usage:
   devrouter-process status --name <name>
 
 Options:
-  --fingerprint <value>  Runtime identity. Defaults to command, workspace, adapter, and safe allowlisted environment identity.
-                        An explicit fingerprint is caller-owned, including preparation identity.
+  --fingerprint <value>  Runtime identity. Defaults to command, workspace, adapter, non-default
+                        managed variant, and safe allowlisted environment identity.
+                        An explicit fingerprint remains caller-owned for preparation identity.
   --prepare-command <shell command>
                         Ensure only: run a nonempty command with bash before a changed/new runtime.
                         Included byte-for-byte in the default fingerprint; skipped on runtime reuse.
@@ -22,6 +23,7 @@ Options:
 Environment:
   DEVROUTER_PROCESS_ADAPTER_SHA256   Exact managed-adapter SHA-256 supplied by devrouter.
   DEVROUTER_PROCESS_FINGERPRINT_ENV  Comma-separated non-secret environment names to fingerprint.
+  DEVROUTER_RUNTIME_VARIANT          Managed runtime variant; defaults to 'default'. Non-default values are part of identity.
 EOF
 }
 
@@ -141,6 +143,18 @@ if [[ -v DEVROUTER_PROCESS_ADAPTER_SHA256 ]] &&
   die "DEVROUTER_PROCESS_ADAPTER_SHA256 must be a SHA-256 digest."
 fi
 
+runtime_variant="${DEVROUTER_RUNTIME_VARIANT-default}"
+if [ "${#runtime_variant}" -gt 64 ] ||
+  ! [[ "$runtime_variant" =~ ^[a-z0-9]+(-[a-z0-9]+)*$ ]]; then
+  die "DEVROUTER_RUNTIME_VARIANT must use lowercase alphanumeric segments separated by hyphens and be at most 64 characters."
+fi
+managed_variant_identity=0
+[ "$runtime_variant" = "default" ] || managed_variant_identity=1
+host_ports_identity="${DEVROUTER_PROCESS_HOST_PORTS_SHA256:-}"
+if [ -n "$host_ports_identity" ] && ! [[ "$host_ports_identity" =~ ^[a-f0-9]{64}$ ]]; then
+  die "DEVROUTER_PROCESS_HOST_PORTS_SHA256 must be a SHA-256 digest."
+fi
+
 if [ "$action" != "ensure" ] && [ "$#" -gt 0 ]; then
   die "Unexpected arguments for $action."
 fi
@@ -163,6 +177,12 @@ if [ -z "$fingerprint" ]; then
     emit_environment_field workspace WORKSPACE
     emit_environment_field devrouter-workspace DEVROUTER_WORKSPACE
     emit_environment_field adapter-sha256 DEVROUTER_PROCESS_ADAPTER_SHA256
+    if [ "$managed_variant_identity" -eq 1 ]; then
+      printf 'runtime-variant\0%s\0' "$runtime_variant"
+    fi
+    if [ -n "$host_ports_identity" ]; then
+      printf 'host-ports\0%s\0' "$host_ports_identity"
+    fi
     for argument in "$@"; do
       printf 'argv\0%s\0' "$argument"
     done
@@ -174,6 +194,13 @@ if [ -z "$fingerprint" ]; then
       emit_environment_field environment-value "$env_name"
     done
   } | LC_ALL=C sha256sum | awk '{print $1}')"
+elif [ "$managed_variant_identity" -eq 1 ] || [ -n "$host_ports_identity" ]; then
+  fingerprint="$({
+    printf 'format\0devrouter-process-managed-variant-v1\0'
+    printf 'explicit-fingerprint\0%s\0' "$fingerprint"
+    printf 'runtime-variant\0%s\0' "$runtime_variant"
+    printf 'host-ports\0%s\0' "$host_ports_identity"
+  } | LC_ALL=C sha256sum | awk '{print $1}')"
 fi
 [[ "$fingerprint" =~ ^[a-zA-Z0-9][a-zA-Z0-9._:-]*$ ]] || die "--fingerprint must be a safe identifier."