@aglyn/aglyn 1.0.0-beta.143

package/src/lib/app-utils/deployment-shape.d.ts

@@ -0,0 +1,167 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * Which SHAPE this runtime is: a deployment, or a developer's machine
+ * (AGL-2177, AGL-2180).
+ *
+ * ## Why this needs a name
+ *
+ * `process.env.VERCEL` was doing duty as "is this a real deployment" in four
+ * places, and Aglyn's cloud is not the only deployment shape the product
+ * supports. On a self-host container `docker/*.Dockerfile` sets
+ * `AGLYN_STANDALONE=1` and never sets `VERCEL`, so every one of those checks
+ * read a production install as a developer's laptop:
+ *
+ *  - `apps/tenant/middleware.ts` resolved no host at all and 307'd every
+ *    visitor to `app.aglyn.com` — the serving half of self-hosting, inert
+ *    (AGL-2177).
+ *  - `apps/console/app/api/domains/verify/route.ts` enabled its DEV soft-pass,
+ *    so any domain carrying any CNAME to anywhere verified — the AGL-733
+ *    defect, reinstated on every self-host install.
+ *  - `apps/tenant/.../load-page-data.ts` never redirected a platform subdomain
+ *    to its connected custom domain, so every site served at two addresses.
+ *
+ * The question those checks are asking is not "are we on Vercel". Naming it
+ * separately is what stops the next one from reaching for the vendor variable
+ * again.
+ *
+ * ## The two predicates are not interchangeable
+ *
+ * {@link isDeployedRuntime} is the broad one, and it is what a branch about
+ * *any* deployment wants. But a security relaxation must not key off it, and
+ * that distinction is the whole of AGL-2180: a check that loosens because it
+ * cannot find a hosting vendor's environment variable is failing open on an
+ * axis unrelated to the thing it is protecting. For those, use
+ * {@link isDevelopmentRuntime}, which keys on `NODE_ENV` — the variable that
+ * actually means "this is not production", is set by every runtime including
+ * containers, and cannot be absent by accident on a production build.
+ *
+ * ## Not importable from an edge bundle
+ *
+ * `apps/tenant/middleware.ts` keeps its own local copy of the deployed
+ * predicate, for the same reason it keeps a local `PLATFORM_GENERATOR_NAME`:
+ * middleware runs in the edge runtime, and every middleware in this repo
+ * imports only app-local constants precisely so a server-only graph never gets
+ * dragged into an edge bundle. The copy is kept honest by an assertion in
+ * `apps/tenant/specs/selfhost-host-resolution.spec.ts` rather than by hope.
+ */
+/**
+ * True when this process is a real deployment — Aglyn's cloud, or an
+ * operator's own container — as opposed to a developer's machine.
+ *
+ * Use for behaviour that should be live wherever the product is actually
+ * serving. Do NOT use to decide whether a security check may be relaxed; see
+ * {@link isDevelopmentRuntime}.
+ */
+export declare function isDeployedRuntime(env?: Record<string, string | undefined>): boolean;
+/**
+ * True only on a PRODUCTION deployment — Vercel production, or an operator's
+ * container running in production.
+ *
+ * Narrower than {@link isDeployedRuntime} on purpose, and the difference is a
+ * preview. The canonical custom-domain redirect keys on this: a preview
+ * deployment that bounced a reviewer onto the customer's live site would be
+ * useless, and a dev machine that did it would be baffling — so "any
+ * deployment" is the wrong question there even though it is the right one for
+ * host resolution.
+ *
+ * That distinction was caught by `canonical-domain-redirect.spec.ts` refusing
+ * a broader predicate, which is the test suite doing its job: the first
+ * attempt at AGL-2180 used {@link isDeployedRuntime} here and would have
+ * started redirecting reviewers off every preview build.
+ */
+export declare function isProductionDeployment(env?: Record<string, string | undefined>): boolean;
+/**
+ * What to call this deployment's environment in a health report (AGL-2436).
+ *
+ * Both health routes read `process.env.VERCEL_ENV ?? 'development'`, so an
+ * operator's production container reported `"environment": "development"` —
+ * to them, and to whatever monitoring they point at it. A health endpoint is
+ * the one surface whose entire job is to say what is running, and it was
+ * saying the opposite for every deployment that is not ours.
+ *
+ * `VERCEL_ENV` still wins where it exists, because it distinguishes a preview
+ * from production and nothing else can. Off Vercel the answer comes from the
+ * predicates above rather than from the absence of a vendor's variable.
+ */
+export declare function deploymentEnvironmentLabel(env?: Record<string, string | undefined>): string;
+/**
+ * True only on a development runtime.
+ *
+ * The predicate a relaxation is allowed to key on. `NODE_ENV` is set to
+ * `production` by every production build in this repo — Next sets it, and
+ * both Dockerfiles set it explicitly — so unlike a vendor variable it cannot
+ * be quietly absent on a real install and hand a production deployment the
+ * developer's rules.
+ */
+export declare function isDevelopmentRuntime(env?: Record<string, string | undefined>): boolean;
+/**
+ * WHERE this instance is serving from, for a forensic marker (AGL-2436).
+ *
+ * The rate-limit degradation marker stamped `VERCEL_REGION` directly, so on
+ * any deployment that is not Aglyn's cloud every episode recorded
+ * `region: null`. Nothing reads the field yet, so this is honest rather than
+ * misleading — but an operator running several replicas has no way to tell
+ * which one shed load, which is the only question the field exists to answer.
+ *
+ * `AGLYN_REGION` is first so an operator can supply the answer their platform
+ * does not: a Kubernetes deployment can pass the node's zone or the pod name
+ * through the downward API, and a compose file can hard-code the site name.
+ * The rest are read because the platforms that set them set them for free.
+ *
+ * Null rather than a guess when nothing is set: a marker that says it does not
+ * know where it ran is usable, and one that invents a locality is not.
+ */
+export declare function deploymentRegion(env?: Record<string, string | undefined>): string | null;
+/**
+ * Which BUILD answered, on any deployment shape (AGL-2091).
+ *
+ * Every `/api/health*` route read `VERCEL_GIT_COMMIT_SHA` directly, which is
+ * unset everywhere except Aglyn's cloud — so a self-hosted install's health
+ * body said `"commit": null`, and the operator's only way to say what they
+ * were running was to guess. The endpoint whose entire job is to describe the
+ * running build described nobody else's.
+ *
+ * The precedence deliberately matches the console footer's (AGL-2181), so the
+ * two surfaces cannot disagree about the same build:
+ *
+ *  1. `BUILD_ID` — an explicit stamp, which is what a self-host operator sets
+ *     when they cut their own build and want their own identifier back.
+ *  2. `COMMIT_REF` — already resolved from four candidates by
+ *     `with-aglyn.nextjs.config.js` and already exported from `global.ts`; it
+ *     had no consumers at all until this one.
+ *  3. `VERCEL_GIT_COMMIT_SHA` — Aglyn's cloud, unchanged.
+ *
+ * Shortened to seven characters, the form `/api/health` has always reported,
+ * so an existing uptime series stays comparable across the change.
+ */
+export declare function deploymentCommitRef(env?: Record<string, string | undefined>): string | null;
+/**
+ * Which VERSION of the platform this is (AGL-2091).
+ *
+ * The number a self-hoster quotes in a bug report, and the one that answers
+ * "has the fix reached me yet". It needs no operator configuration:
+ * `with-aglyn.nextjs.config.js` reads it out of the root `package.json` and
+ * inlines it as `PACKAGE_VERSION`, so a container built from a release tag
+ * reports that release the first time it starts — unlike the commit, which an
+ * operator has to stamp if they want it.
+ *
+ * Null rather than `'NULL'` when a build missed the define: a health body that
+ * admits it does not know is honest, and one that reports a version of "NULL"
+ * teaches whoever reads it to ignore the field.
+ */
+export declare function platformVersion(env?: Record<string, string | undefined>): string | null;

package/src/lib/app-utils/deployment-shape.js

@@ -0,0 +1,238 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */ /**
+ * Which SHAPE this runtime is: a deployment, or a developer's machine
+ * (AGL-2177, AGL-2180).
+ *
+ * ## Why this needs a name
+ *
+ * `process.env.VERCEL` was doing duty as "is this a real deployment" in four
+ * places, and Aglyn's cloud is not the only deployment shape the product
+ * supports. On a self-host container `docker/*.Dockerfile` sets
+ * `AGLYN_STANDALONE=1` and never sets `VERCEL`, so every one of those checks
+ * read a production install as a developer's laptop:
+ *
+ *  - `apps/tenant/middleware.ts` resolved no host at all and 307'd every
+ *    visitor to `app.aglyn.com` — the serving half of self-hosting, inert
+ *    (AGL-2177).
+ *  - `apps/console/app/api/domains/verify/route.ts` enabled its DEV soft-pass,
+ *    so any domain carrying any CNAME to anywhere verified — the AGL-733
+ *    defect, reinstated on every self-host install.
+ *  - `apps/tenant/.../load-page-data.ts` never redirected a platform subdomain
+ *    to its connected custom domain, so every site served at two addresses.
+ *
+ * The question those checks are asking is not "are we on Vercel". Naming it
+ * separately is what stops the next one from reaching for the vendor variable
+ * again.
+ *
+ * ## The two predicates are not interchangeable
+ *
+ * {@link isDeployedRuntime} is the broad one, and it is what a branch about
+ * *any* deployment wants. But a security relaxation must not key off it, and
+ * that distinction is the whole of AGL-2180: a check that loosens because it
+ * cannot find a hosting vendor's environment variable is failing open on an
+ * axis unrelated to the thing it is protecting. For those, use
+ * {@link isDevelopmentRuntime}, which keys on `NODE_ENV` — the variable that
+ * actually means "this is not production", is set by every runtime including
+ * containers, and cannot be absent by accident on a production build.
+ *
+ * ## Not importable from an edge bundle
+ *
+ * `apps/tenant/middleware.ts` keeps its own local copy of the deployed
+ * predicate, for the same reason it keeps a local `PLATFORM_GENERATOR_NAME`:
+ * middleware runs in the edge runtime, and every middleware in this repo
+ * imports only app-local constants precisely so a server-only graph never gets
+ * dragged into an edge bundle. The copy is kept honest by an assertion in
+ * `apps/tenant/specs/selfhost-host-resolution.spec.ts` rather than by hope.
+ */ /**
+ * True when this process is a real deployment — Aglyn's cloud, or an
+ * operator's own container — as opposed to a developer's machine.
+ *
+ * Use for behaviour that should be live wherever the product is actually
+ * serving. Do NOT use to decide whether a security check may be relaxed; see
+ * {@link isDevelopmentRuntime}.
+ */ export function isDeployedRuntime(env = process.env) {
+    return Boolean(env['VERCEL']) || env['AGLYN_STANDALONE'] === '1';
+}
+/**
+ * True only on a PRODUCTION deployment — Vercel production, or an operator's
+ * container running in production.
+ *
+ * Narrower than {@link isDeployedRuntime} on purpose, and the difference is a
+ * preview. The canonical custom-domain redirect keys on this: a preview
+ * deployment that bounced a reviewer onto the customer's live site would be
+ * useless, and a dev machine that did it would be baffling — so "any
+ * deployment" is the wrong question there even though it is the right one for
+ * host resolution.
+ *
+ * That distinction was caught by `canonical-domain-redirect.spec.ts` refusing
+ * a broader predicate, which is the test suite doing its job: the first
+ * attempt at AGL-2180 used {@link isDeployedRuntime} here and would have
+ * started redirecting reviewers off every preview build.
+ */ export function isProductionDeployment(env = process.env) {
+    if (env['VERCEL_ENV'] === 'production') return true;
+    return env['AGLYN_STANDALONE'] === '1' && env['NODE_ENV'] === 'production';
+}
+/**
+ * What to call this deployment's environment in a health report (AGL-2436).
+ *
+ * Both health routes read `process.env.VERCEL_ENV ?? 'development'`, so an
+ * operator's production container reported `"environment": "development"` —
+ * to them, and to whatever monitoring they point at it. A health endpoint is
+ * the one surface whose entire job is to say what is running, and it was
+ * saying the opposite for every deployment that is not ours.
+ *
+ * `VERCEL_ENV` still wins where it exists, because it distinguishes a preview
+ * from production and nothing else can. Off Vercel the answer comes from the
+ * predicates above rather than from the absence of a vendor's variable.
+ */ export function deploymentEnvironmentLabel(env = process.env) {
+    const vercel = env['VERCEL_ENV'];
+    if (vercel) return vercel;
+    if (isProductionDeployment(env)) return 'production';
+    if (isDeployedRuntime(env)) return 'deployment';
+    return 'development';
+}
+/**
+ * True only on a development runtime.
+ *
+ * The predicate a relaxation is allowed to key on. `NODE_ENV` is set to
+ * `production` by every production build in this repo — Next sets it, and
+ * both Dockerfiles set it explicitly — so unlike a vendor variable it cannot
+ * be quietly absent on a real install and hand a production deployment the
+ * developer's rules.
+ */ export function isDevelopmentRuntime(env = process.env) {
+    return env['NODE_ENV'] !== 'production';
+}
+/**
+ * WHERE this instance is serving from, for a forensic marker (AGL-2436).
+ *
+ * The rate-limit degradation marker stamped `VERCEL_REGION` directly, so on
+ * any deployment that is not Aglyn's cloud every episode recorded
+ * `region: null`. Nothing reads the field yet, so this is honest rather than
+ * misleading — but an operator running several replicas has no way to tell
+ * which one shed load, which is the only question the field exists to answer.
+ *
+ * `AGLYN_REGION` is first so an operator can supply the answer their platform
+ * does not: a Kubernetes deployment can pass the node's zone or the pod name
+ * through the downward API, and a compose file can hard-code the site name.
+ * The rest are read because the platforms that set them set them for free.
+ *
+ * Null rather than a guess when nothing is set: a marker that says it does not
+ * know where it ran is usable, and one that invents a locality is not.
+ */ export function deploymentRegion(env = process.env) {
+    for (const name of [
+        'AGLYN_REGION',
+        'VERCEL_REGION',
+        'FLY_REGION',
+        'AWS_REGION',
+        'AWS_DEFAULT_REGION'
+    ]){
+        var _env_name;
+        const value = String((_env_name = env[name]) != null ? _env_name : '').trim();
+        if (value) return value;
+    }
+    return null;
+}
+/**
+ * Build metadata that is unset, in every spelling this repo produces.
+ *
+ * `libs/shared/data/enums/src/lib/global.ts` renders unset build metadata as
+ * the literal string `'NULL'`, and a Docker `ARG` referenced with no value
+ * hands the same text through the build. Treating those as a real answer is
+ * how a health endpoint ends up reporting that it is running commit "NULL".
+ */ const UNSTAMPED = new Set([
+    '',
+    'NULL',
+    'null',
+    'undefined'
+]);
+/**
+ * Build metadata, read as LITERALS at module scope — and that is load-bearing.
+ *
+ * `PACKAGE_VERSION`, `BUILD_ID` and `COMMIT_REF` are not runtime environment
+ * variables. They are build-time defines: `with-aglyn.nextjs.config.js` lists
+ * them in `env`, and the bundler replaces the literal text
+ * `process.env.PACKAGE_VERSION` with the value. Nothing sets them in the
+ * process — the Dockerfiles set `COMMIT_REF` in the BUILD stage, not the
+ * runner — so a read that the bundler cannot see statically resolves to
+ * `undefined` at runtime.
+ *
+ * A parameterised read is exactly such a read: with `env = process.env`,
+ * `env['PACKAGE_VERSION']` is a property access on an alias and no bundler
+ * replaces it. The functions below therefore default to this snapshot rather
+ * than to `process.env`, which is the difference between a health body that
+ * reports a version and one that reports null while every unit test passes.
+ * `deploymentEnvironmentLabel()` above can default to `process.env` because
+ * `VERCEL_ENV`, `NODE_ENV` and `AGLYN_STANDALONE` are genuine runtime
+ * variables — the distinction is the variable, not the style.
+ *
+ * `VERCEL_GIT_COMMIT_SHA` is both, and is read here for uniformity; it is set
+ * in the Vercel runtime as well as inlined, and `/api/health` has been
+ * answering `"commit"` from it in production all along.
+ */ const BUILD_METADATA = {
+    BUILD_ID: process.env.BUILD_ID,
+    COMMIT_REF: process.env.COMMIT_REF,
+    PACKAGE_VERSION: process.env.PACKAGE_VERSION,
+    VERCEL_GIT_COMMIT_SHA: process.env.VERCEL_GIT_COMMIT_SHA
+};
+function stamped(value) {
+    const trimmed = String(value != null ? value : '').trim();
+    return UNSTAMPED.has(trimmed) ? null : trimmed;
+}
+/**
+ * Which BUILD answered, on any deployment shape (AGL-2091).
+ *
+ * Every `/api/health*` route read `VERCEL_GIT_COMMIT_SHA` directly, which is
+ * unset everywhere except Aglyn's cloud — so a self-hosted install's health
+ * body said `"commit": null`, and the operator's only way to say what they
+ * were running was to guess. The endpoint whose entire job is to describe the
+ * running build described nobody else's.
+ *
+ * The precedence deliberately matches the console footer's (AGL-2181), so the
+ * two surfaces cannot disagree about the same build:
+ *
+ *  1. `BUILD_ID` — an explicit stamp, which is what a self-host operator sets
+ *     when they cut their own build and want their own identifier back.
+ *  2. `COMMIT_REF` — already resolved from four candidates by
+ *     `with-aglyn.nextjs.config.js` and already exported from `global.ts`; it
+ *     had no consumers at all until this one.
+ *  3. `VERCEL_GIT_COMMIT_SHA` — Aglyn's cloud, unchanged.
+ *
+ * Shortened to seven characters, the form `/api/health` has always reported,
+ * so an existing uptime series stays comparable across the change.
+ */ export function deploymentCommitRef(env = BUILD_METADATA) {
+    var _ref, _stamped;
+    const ref = (_ref = (_stamped = stamped(env['BUILD_ID'])) != null ? _stamped : stamped(env['COMMIT_REF'])) != null ? _ref : stamped(env['VERCEL_GIT_COMMIT_SHA']);
+    return ref === null ? null : ref.slice(0, 7);
+}
+/**
+ * Which VERSION of the platform this is (AGL-2091).
+ *
+ * The number a self-hoster quotes in a bug report, and the one that answers
+ * "has the fix reached me yet". It needs no operator configuration:
+ * `with-aglyn.nextjs.config.js` reads it out of the root `package.json` and
+ * inlines it as `PACKAGE_VERSION`, so a container built from a release tag
+ * reports that release the first time it starts — unlike the commit, which an
+ * operator has to stamp if they want it.
+ *
+ * Null rather than `'NULL'` when a build missed the define: a health body that
+ * admits it does not know is honest, and one that reports a version of "NULL"
+ * teaches whoever reads it to ignore the field.
+ */ export function platformVersion(env = BUILD_METADATA) {
+    return stamped(env['PACKAGE_VERSION']);
+}
+
+//# sourceMappingURL=deployment-shape.js.map

package/src/lib/app-utils/deployment-shape.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/app-utils/deployment-shape.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\n/**\n * Which SHAPE this runtime is: a deployment, or a developer's machine\n * (AGL-2177, AGL-2180).\n *\n * ## Why this needs a name\n *\n * `process.env.VERCEL` was doing duty as \"is this a real deployment\" in four\n * places, and Aglyn's cloud is not the only deployment shape the product\n * supports. On a self-host container `docker/*.Dockerfile` sets\n * `AGLYN_STANDALONE=1` and never sets `VERCEL`, so every one of those checks\n * read a production install as a developer's laptop:\n *\n *  - `apps/tenant/middleware.ts` resolved no host at all and 307'd every\n *    visitor to `app.aglyn.com` — the serving half of self-hosting, inert\n *    (AGL-2177).\n *  - `apps/console/app/api/domains/verify/route.ts` enabled its DEV soft-pass,\n *    so any domain carrying any CNAME to anywhere verified — the AGL-733\n *    defect, reinstated on every self-host install.\n *  - `apps/tenant/.../load-page-data.ts` never redirected a platform subdomain\n *    to its connected custom domain, so every site served at two addresses.\n *\n * The question those checks are asking is not \"are we on Vercel\". Naming it\n * separately is what stops the next one from reaching for the vendor variable\n * again.\n *\n * ## The two predicates are not interchangeable\n *\n * {@link isDeployedRuntime} is the broad one, and it is what a branch about\n * *any* deployment wants. But a security relaxation must not key off it, and\n * that distinction is the whole of AGL-2180: a check that loosens because it\n * cannot find a hosting vendor's environment variable is failing open on an\n * axis unrelated to the thing it is protecting. For those, use\n * {@link isDevelopmentRuntime}, which keys on `NODE_ENV` — the variable that\n * actually means \"this is not production\", is set by every runtime including\n * containers, and cannot be absent by accident on a production build.\n *\n * ## Not importable from an edge bundle\n *\n * `apps/tenant/middleware.ts` keeps its own local copy of the deployed\n * predicate, for the same reason it keeps a local `PLATFORM_GENERATOR_NAME`:\n * middleware runs in the edge runtime, and every middleware in this repo\n * imports only app-local constants precisely so a server-only graph never gets\n * dragged into an edge bundle. The copy is kept honest by an assertion in\n * `apps/tenant/specs/selfhost-host-resolution.spec.ts` rather than by hope.\n */\n\n/**\n * True when this process is a real deployment — Aglyn's cloud, or an\n * operator's own container — as opposed to a developer's machine.\n *\n * Use for behaviour that should be live wherever the product is actually\n * serving. Do NOT use to decide whether a security check may be relaxed; see\n * {@link isDevelopmentRuntime}.\n */\nexport function isDeployedRuntime(\n  env: Record<string, string | undefined> = process.env,\n): boolean {\n  return Boolean(env['VERCEL']) || env['AGLYN_STANDALONE'] === '1'\n}\n\n/**\n * True only on a PRODUCTION deployment — Vercel production, or an operator's\n * container running in production.\n *\n * Narrower than {@link isDeployedRuntime} on purpose, and the difference is a\n * preview. The canonical custom-domain redirect keys on this: a preview\n * deployment that bounced a reviewer onto the customer's live site would be\n * useless, and a dev machine that did it would be baffling — so \"any\n * deployment\" is the wrong question there even though it is the right one for\n * host resolution.\n *\n * That distinction was caught by `canonical-domain-redirect.spec.ts` refusing\n * a broader predicate, which is the test suite doing its job: the first\n * attempt at AGL-2180 used {@link isDeployedRuntime} here and would have\n * started redirecting reviewers off every preview build.\n */\nexport function isProductionDeployment(\n  env: Record<string, string | undefined> = process.env,\n): boolean {\n  if (env['VERCEL_ENV'] === 'production') return true\n  return env['AGLYN_STANDALONE'] === '1' && env['NODE_ENV'] === 'production'\n}\n\n/**\n * What to call this deployment's environment in a health report (AGL-2436).\n *\n * Both health routes read `process.env.VERCEL_ENV ?? 'development'`, so an\n * operator's production container reported `\"environment\": \"development\"` —\n * to them, and to whatever monitoring they point at it. A health endpoint is\n * the one surface whose entire job is to say what is running, and it was\n * saying the opposite for every deployment that is not ours.\n *\n * `VERCEL_ENV` still wins where it exists, because it distinguishes a preview\n * from production and nothing else can. Off Vercel the answer comes from the\n * predicates above rather than from the absence of a vendor's variable.\n */\nexport function deploymentEnvironmentLabel(\n  env: Record<string, string | undefined> = process.env,\n): string {\n  const vercel = env['VERCEL_ENV']\n  if (vercel) return vercel\n  if (isProductionDeployment(env)) return 'production'\n  if (isDeployedRuntime(env)) return 'deployment'\n  return 'development'\n}\n\n/**\n * True only on a development runtime.\n *\n * The predicate a relaxation is allowed to key on. `NODE_ENV` is set to\n * `production` by every production build in this repo — Next sets it, and\n * both Dockerfiles set it explicitly — so unlike a vendor variable it cannot\n * be quietly absent on a real install and hand a production deployment the\n * developer's rules.\n */\nexport function isDevelopmentRuntime(\n  env: Record<string, string | undefined> = process.env,\n): boolean {\n  return env['NODE_ENV'] !== 'production'\n}\n\n/**\n * WHERE this instance is serving from, for a forensic marker (AGL-2436).\n *\n * The rate-limit degradation marker stamped `VERCEL_REGION` directly, so on\n * any deployment that is not Aglyn's cloud every episode recorded\n * `region: null`. Nothing reads the field yet, so this is honest rather than\n * misleading — but an operator running several replicas has no way to tell\n * which one shed load, which is the only question the field exists to answer.\n *\n * `AGLYN_REGION` is first so an operator can supply the answer their platform\n * does not: a Kubernetes deployment can pass the node's zone or the pod name\n * through the downward API, and a compose file can hard-code the site name.\n * The rest are read because the platforms that set them set them for free.\n *\n * Null rather than a guess when nothing is set: a marker that says it does not\n * know where it ran is usable, and one that invents a locality is not.\n */\nexport function deploymentRegion(\n  env: Record<string, string | undefined> = process.env,\n): string | null {\n  for (const name of [\n    'AGLYN_REGION',\n    'VERCEL_REGION',\n    'FLY_REGION',\n    'AWS_REGION',\n    'AWS_DEFAULT_REGION',\n  ]) {\n    const value = String(env[name] ?? '').trim()\n    if (value) return value\n  }\n  return null\n}\n\n/**\n * Build metadata that is unset, in every spelling this repo produces.\n *\n * `libs/shared/data/enums/src/lib/global.ts` renders unset build metadata as\n * the literal string `'NULL'`, and a Docker `ARG` referenced with no value\n * hands the same text through the build. Treating those as a real answer is\n * how a health endpoint ends up reporting that it is running commit \"NULL\".\n */\nconst UNSTAMPED = new Set(['', 'NULL', 'null', 'undefined'])\n\n/**\n * Build metadata, read as LITERALS at module scope — and that is load-bearing.\n *\n * `PACKAGE_VERSION`, `BUILD_ID` and `COMMIT_REF` are not runtime environment\n * variables. They are build-time defines: `with-aglyn.nextjs.config.js` lists\n * them in `env`, and the bundler replaces the literal text\n * `process.env.PACKAGE_VERSION` with the value. Nothing sets them in the\n * process — the Dockerfiles set `COMMIT_REF` in the BUILD stage, not the\n * runner — so a read that the bundler cannot see statically resolves to\n * `undefined` at runtime.\n *\n * A parameterised read is exactly such a read: with `env = process.env`,\n * `env['PACKAGE_VERSION']` is a property access on an alias and no bundler\n * replaces it. The functions below therefore default to this snapshot rather\n * than to `process.env`, which is the difference between a health body that\n * reports a version and one that reports null while every unit test passes.\n * `deploymentEnvironmentLabel()` above can default to `process.env` because\n * `VERCEL_ENV`, `NODE_ENV` and `AGLYN_STANDALONE` are genuine runtime\n * variables — the distinction is the variable, not the style.\n *\n * `VERCEL_GIT_COMMIT_SHA` is both, and is read here for uniformity; it is set\n * in the Vercel runtime as well as inlined, and `/api/health` has been\n * answering `\"commit\"` from it in production all along.\n */\nconst BUILD_METADATA: Record<string, string | undefined> = {\n  BUILD_ID: process.env.BUILD_ID,\n  COMMIT_REF: process.env.COMMIT_REF,\n  PACKAGE_VERSION: process.env.PACKAGE_VERSION,\n  VERCEL_GIT_COMMIT_SHA: process.env.VERCEL_GIT_COMMIT_SHA,\n}\n\nfunction stamped(value: string | undefined): string | null {\n  const trimmed = String(value ?? '').trim()\n  return UNSTAMPED.has(trimmed) ? null : trimmed\n}\n\n/**\n * Which BUILD answered, on any deployment shape (AGL-2091).\n *\n * Every `/api/health*` route read `VERCEL_GIT_COMMIT_SHA` directly, which is\n * unset everywhere except Aglyn's cloud — so a self-hosted install's health\n * body said `\"commit\": null`, and the operator's only way to say what they\n * were running was to guess. The endpoint whose entire job is to describe the\n * running build described nobody else's.\n *\n * The precedence deliberately matches the console footer's (AGL-2181), so the\n * two surfaces cannot disagree about the same build:\n *\n *  1. `BUILD_ID` — an explicit stamp, which is what a self-host operator sets\n *     when they cut their own build and want their own identifier back.\n *  2. `COMMIT_REF` — already resolved from four candidates by\n *     `with-aglyn.nextjs.config.js` and already exported from `global.ts`; it\n *     had no consumers at all until this one.\n *  3. `VERCEL_GIT_COMMIT_SHA` — Aglyn's cloud, unchanged.\n *\n * Shortened to seven characters, the form `/api/health` has always reported,\n * so an existing uptime series stays comparable across the change.\n */\nexport function deploymentCommitRef(\n  env: Record<string, string | undefined> = BUILD_METADATA,\n): string | null {\n  const ref =\n    stamped(env['BUILD_ID']) ??\n    stamped(env['COMMIT_REF']) ??\n    stamped(env['VERCEL_GIT_COMMIT_SHA'])\n  return ref === null ? null : ref.slice(0, 7)\n}\n\n/**\n * Which VERSION of the platform this is (AGL-2091).\n *\n * The number a self-hoster quotes in a bug report, and the one that answers\n * \"has the fix reached me yet\". It needs no operator configuration:\n * `with-aglyn.nextjs.config.js` reads it out of the root `package.json` and\n * inlines it as `PACKAGE_VERSION`, so a container built from a release tag\n * reports that release the first time it starts — unlike the commit, which an\n * operator has to stamp if they want it.\n *\n * Null rather than `'NULL'` when a build missed the define: a health body that\n * admits it does not know is honest, and one that reports a version of \"NULL\"\n * teaches whoever reads it to ignore the field.\n */\nexport function platformVersion(\n  env: Record<string, string | undefined> = BUILD_METADATA,\n): string | null {\n  return stamped(env['PACKAGE_VERSION'])\n}\n"],"names":["isDeployedRuntime","env","process","Boolean","isProductionDeployment","deploymentEnvironmentLabel","vercel","isDevelopmentRuntime","deploymentRegion","name","value","String","trim","UNSTAMPED","Set","BUILD_METADATA","BUILD_ID","COMMIT_REF","PACKAGE_VERSION","VERCEL_GIT_COMMIT_SHA","stamped","trimmed","has","deploymentCommitRef","ref","slice","platformVersion"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA4CC,GAED;;;;;;;CAOC,GACD,OAAO,SAASA,kBACdC,MAA0CC,QAAQD,GAAG;IAErD,OAAOE,QAAQF,GAAG,CAAC,SAAS,KAAKA,GAAG,CAAC,mBAAmB,KAAK;AAC/D;AAEA;;;;;;;;;;;;;;;CAeC,GACD,OAAO,SAASG,uBACdH,MAA0CC,QAAQD,GAAG;IAErD,IAAIA,GAAG,CAAC,aAAa,KAAK,cAAc,OAAO;IAC/C,OAAOA,GAAG,CAAC,mBAAmB,KAAK,OAAOA,GAAG,CAAC,WAAW,KAAK;AAChE;AAEA;;;;;;;;;;;;CAYC,GACD,OAAO,SAASI,2BACdJ,MAA0CC,QAAQD,GAAG;IAErD,MAAMK,SAASL,GAAG,CAAC,aAAa;IAChC,IAAIK,QAAQ,OAAOA;IACnB,IAAIF,uBAAuBH,MAAM,OAAO;IACxC,IAAID,kBAAkBC,MAAM,OAAO;IACnC,OAAO;AACT;AAEA;;;;;;;;CAQC,GACD,OAAO,SAASM,qBACdN,MAA0CC,QAAQD,GAAG;IAErD,OAAOA,GAAG,CAAC,WAAW,KAAK;AAC7B;AAEA;;;;;;;;;;;;;;;;CAgBC,GACD,OAAO,SAASO,iBACdP,MAA0CC,QAAQD,GAAG;IAErD,KAAK,MAAMQ,QAAQ;QACjB;QACA;QACA;QACA;QACA;KACD,CAAE;YACoBR;QAArB,MAAMS,QAAQC,QAAOV,YAAAA,GAAG,CAACQ,KAAK,YAATR,YAAa,IAAIW,IAAI;QAC1C,IAAIF,OAAO,OAAOA;IACpB;IACA,OAAO;AACT;AAEA;;;;;;;CAOC,GACD,MAAMG,YAAY,IAAIC,IAAI;IAAC;IAAI;IAAQ;IAAQ;CAAY;AAE3D;;;;;;;;;;;;;;;;;;;;;;;CAuBC,GACD,MAAMC,iBAAqD;IACzDC,UAAUd,QAAQD,GAAG,CAACe,QAAQ;IAC9BC,YAAYf,QAAQD,GAAG,CAACgB,UAAU;IAClCC,iBAAiBhB,QAAQD,GAAG,CAACiB,eAAe;IAC5CC,uBAAuBjB,QAAQD,GAAG,CAACkB,qBAAqB;AAC1D;AAEA,SAASC,QAAQV,KAAyB;IACxC,MAAMW,UAAUV,OAAOD,gBAAAA,QAAS,IAAIE,IAAI;IACxC,OAAOC,UAAUS,GAAG,CAACD,WAAW,OAAOA;AACzC;AAEA;;;;;;;;;;;;;;;;;;;;;CAqBC,GACD,OAAO,SAASE,oBACdtB,MAA0Cc,cAAc;QAGtDK,MAAAA;IADF,MAAMI,OACJJ,QAAAA,WAAAA,QAAQnB,GAAG,CAAC,WAAW,aAAvBmB,WACAA,QAAQnB,GAAG,CAAC,aAAa,aADzBmB,OAEAA,QAAQnB,GAAG,CAAC,wBAAwB;IACtC,OAAOuB,QAAQ,OAAO,OAAOA,IAAIC,KAAK,CAAC,GAAG;AAC5C;AAEA;;;;;;;;;;;;;CAaC,GACD,OAAO,SAASC,gBACdzB,MAA0Cc,cAAc;IAExD,OAAOK,QAAQnB,GAAG,CAAC,kBAAkB;AACvC"}

package/src/lib/app-utils/detect-template-placeholders.d.ts

@@ -0,0 +1,30 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * Bare `{{name}}` tokens in the captured content (AGL-672).
+ *
+ * Deliberately ignores the id-form `{{var:…}}` and `{{fn:…}}` host bindings:
+ * those resolve against the site's own variables and functions at render
+ * time, so turning one into a template placeholder would break the binding
+ * it already has. Only the plain named form is a placeholder candidate,
+ * which is the same form `resolveNamedTokens` substitutes.
+ *
+ * A `{{prop.*}}` token is not a candidate either (AGL-2932): it binds to a
+ * property the component or layout declares, which the template carries, and
+ * a placeholder filled in on use would erase the binding from what is made.
+ */
+export declare function detectTemplatePlaceholders(nodes: Record<string, unknown>): string[];

package/src/lib/app-utils/detect-template-placeholders.js

@@ -0,0 +1,53 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */ import { COMPONENT_PROP_TOKEN_PREFIX } from "./reusable-component-keys.js";
+/**
+ * Bare `{{name}}` tokens in the captured content (AGL-672).
+ *
+ * Deliberately ignores the id-form `{{var:…}}` and `{{fn:…}}` host bindings:
+ * those resolve against the site's own variables and functions at render
+ * time, so turning one into a template placeholder would break the binding
+ * it already has. Only the plain named form is a placeholder candidate,
+ * which is the same form `resolveNamedTokens` substitutes.
+ *
+ * A `{{prop.*}}` token is not a candidate either (AGL-2932): it binds to a
+ * property the component or layout declares, which the template carries, and
+ * a placeholder filled in on use would erase the binding from what is made.
+ */ export function detectTemplatePlaceholders(nodes) {
+    const found = new Set();
+    const pattern = /\{\{\s*([a-zA-Z][\w.-]*)\s*\}\}/g;
+    // Explicit return type: the function is recursive, so inference has
+    // nothing to anchor on and `noImplicitAny` rejects it in this lib.
+    const walk = (value)=>{
+        if (typeof value === 'string') {
+            for (const match of value.matchAll(pattern)){
+                const name = match[1];
+                if (!name || name.includes(':')) continue;
+                if (name.startsWith(COMPONENT_PROP_TOKEN_PREFIX)) continue;
+                found.add(name);
+            }
+            return;
+        }
+        if (Array.isArray(value)) return void value.forEach(walk);
+        if (value && typeof value === 'object') {
+            Object.values(value).forEach(walk);
+        }
+    };
+    walk(nodes);
+    return Array.from(found).sort();
+}
+
+//# sourceMappingURL=detect-template-placeholders.js.map

package/src/lib/app-utils/detect-template-placeholders.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/app-utils/detect-template-placeholders.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport { COMPONENT_PROP_TOKEN_PREFIX } from './reusable-component-keys'\n\n/**\n * Bare `{{name}}` tokens in the captured content (AGL-672).\n *\n * Deliberately ignores the id-form `{{var:…}}` and `{{fn:…}}` host bindings:\n * those resolve against the site's own variables and functions at render\n * time, so turning one into a template placeholder would break the binding\n * it already has. Only the plain named form is a placeholder candidate,\n * which is the same form `resolveNamedTokens` substitutes.\n *\n * A `{{prop.*}}` token is not a candidate either (AGL-2932): it binds to a\n * property the component or layout declares, which the template carries, and\n * a placeholder filled in on use would erase the binding from what is made.\n */\nexport function detectTemplatePlaceholders(nodes: Record<string, unknown>): string[] {\n  const found = new Set<string>()\n  const pattern = /\\{\\{\\s*([a-zA-Z][\\w.-]*)\\s*\\}\\}/g\n  // Explicit return type: the function is recursive, so inference has\n  // nothing to anchor on and `noImplicitAny` rejects it in this lib.\n  const walk = (value: unknown): void => {\n    if (typeof value === 'string') {\n      for (const match of value.matchAll(pattern)) {\n        const name = match[1]\n        if (!name || name.includes(':')) continue\n        if (name.startsWith(COMPONENT_PROP_TOKEN_PREFIX)) continue\n        found.add(name)\n      }\n      return\n    }\n    if (Array.isArray(value)) return void value.forEach(walk)\n    if (value && typeof value === 'object') {\n      Object.values(value as Record<string, unknown>).forEach(walk)\n    }\n  }\n  walk(nodes)\n  return Array.from(found).sort()\n}\n"],"names":["COMPONENT_PROP_TOKEN_PREFIX","detectTemplatePlaceholders","nodes","found","Set","pattern","walk","value","match","matchAll","name","includes","startsWith","add","Array","isArray","forEach","Object","values","from","sort"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED,SAASA,2BAA2B,QAAQ,+BAA2B;AAEvE;;;;;;;;;;;;CAYC,GACD,OAAO,SAASC,2BAA2BC,KAA8B;IACvE,MAAMC,QAAQ,IAAIC;IAClB,MAAMC,UAAU;IAChB,oEAAoE;IACpE,mEAAmE;IACnE,MAAMC,OAAO,CAACC;QACZ,IAAI,OAAOA,UAAU,UAAU;YAC7B,KAAK,MAAMC,SAASD,MAAME,QAAQ,CAACJ,SAAU;gBAC3C,MAAMK,OAAOF,KAAK,CAAC,EAAE;gBACrB,IAAI,CAACE,QAAQA,KAAKC,QAAQ,CAAC,MAAM;gBACjC,IAAID,KAAKE,UAAU,CAACZ,8BAA8B;gBAClDG,MAAMU,GAAG,CAACH;YACZ;YACA;QACF;QACA,IAAII,MAAMC,OAAO,CAACR,QAAQ,OAAO,KAAKA,MAAMS,OAAO,CAACV;QACpD,IAAIC,SAAS,OAAOA,UAAU,UAAU;YACtCU,OAAOC,MAAM,CAACX,OAAkCS,OAAO,CAACV;QAC1D;IACF;IACAA,KAAKJ;IACL,OAAOY,MAAMK,IAAI,CAAChB,OAAOiB,IAAI;AAC/B"}