@o3co/create-auth-policy-verifier 0.3.1 → 0.5.0

package/README.ja.md

@@ -5,7 +5,7 @@ auth.policy-verifier 用の CLI スキャフォルダーです。組み込みテ
 ## 使い方
 
 ```sh
-npx @o3co/create-auth-policy-verifier <project-name> [--dir <dir-name>]
+npx @o3co/create-auth-policy-verifier <project-name> [--dir <dir-name>] [--no-lockfile]
 ```
 
 `<project-name>` はスコープ付き npm 名 (`@scope/pkg`) とスコープなしの名前 (`pkg`) のどちらでも指定できます。
@@ -15,8 +15,8 @@ npx @o3co/create-auth-policy-verifier <project-name> [--dir <dir-name>]
 ```sh
 npx @o3co/create-auth-policy-verifier my-verifier
 cd my-verifier
-npm install
-npm run debug
+pnpm install
+pnpm run debug
 ```
 
 スコープ付きの例（ディレクトリ名はパッケージ部分がデフォルト）:
@@ -24,8 +24,8 @@ npm run debug
 ```sh
 npx @o3co/create-auth-policy-verifier @my-org/auth.policy-verifier
 cd auth.policy-verifier
-npm install
-npm run debug
+pnpm install
+pnpm run debug
 ```
 
 `--dir` でディレクトリ名を明示指定:
@@ -42,7 +42,25 @@ cd verifier
 3. 生成先ディレクトリがすでに存在する場合はエラーを出力して終了する。
 4. `templates/standalone/` を生成先ディレクトリにコピーする（`node_modules/` と `dist/` は除外）。
 5. `package.json` を書き換える: `name` を `<project-name>` をそのまま設定し（スコープを保持）、`private` を削除し、`workspace:*` のバージョン参照を `templates/versions.json` の公開 semver バージョンに置き換える。
-6. 次のステップの手順を表示する。
+6. その依存セットを `pnpm-lock.yaml` に解決する（`pnpm install --lockfile-only --ignore-workspace`）。`--no-lockfile` 指定時は省略。
+7. 次のステップの手順を表示する。
+
+### 生成される `pnpm-lock.yaml`
+
+テンプレートの `Dockerfile` は `pnpm install --frozen-lockfile` でインストール
+するため、生成されたプロジェクトは lockfile が無いとそもそもビルドできません。
+これはテンプレートに同梱できません: 手順 5 が `workspace:*` を公開バージョンに
+置き換えるまで、lockfile が固定すべき依存セットは存在しないからです。そのため
+書き換え後の `package.json` に対してここで一度だけ解決します。**コミットして
+ください** — `docker build` を再現可能にしているのはこれです。
+
+手順 6 には `pnpm`（または `corepack`）と到達可能なレジストリが必要ですが、
+スキャフォルダーを実行するマシンにそれらがある保証はありません。したがって
+best-effort です: 失敗しても scaffold 自体は成功し、対処方法を表示します。
+lockfile が無くても生成されたプロジェクトは問題なく使えます — 一度
+`pnpm install` を実行するまでイメージにビルドできないだけです。手順そのものを
+省略するには `--no-lockfile` を指定します（オフラインでの scaffold や、
+後段でどのみちインストールするパイプライン向け）。
 
 ## バリデーションルール
 
@@ -72,6 +90,7 @@ cd verifier
 ├── docker-compose.yml
 ├── docker-compose.test.yml
 ├── package.json
+├── pnpm-lock.yaml          # scaffold 時に生成 — コミットすること
 └── tsconfig.json
 ```
 
@@ -86,7 +105,8 @@ import { scaffold, main } from "@o3co/create-auth-policy-verifier";
 | エクスポート | シグネチャ | 説明 |
 |---|---|---|
 | `scaffold` | `(targetDir: string, projectName: string): void` | テンプレートをコピーして `package.json` を書き換える |
-| `main` | `(): void` | CLI エントリポイント — `process.argv` を解析して `scaffold` を呼び出す |
+| `generateLockfile` | `(targetDir: string): LockfileResult` | scaffold 済みディレクトリで `pnpm-lock.yaml` を解決する。失敗は throw せず結果として返す |
+| `main` | `(): void` | CLI エントリポイント — `process.argv` を解析し `scaffold` → `generateLockfile` を呼び出す |
 
 ## 関連
 

package/README.md

@@ -5,7 +5,7 @@ CLI scaffolder for auth.policy-verifier. Generates a new standalone server proje
 ## Usage
 
 ```sh
-npx @o3co/create-auth-policy-verifier <project-name> [--dir <dir-name>]
+npx @o3co/create-auth-policy-verifier <project-name> [--dir <dir-name>] [--no-lockfile]
 ```
 
 `<project-name>` may be either a scoped npm name (`@scope/pkg`) or an unscoped name (`pkg`).
@@ -15,8 +15,8 @@ Unscoped example:
 ```sh
 npx @o3co/create-auth-policy-verifier my-verifier
 cd my-verifier
-npm install
-npm run debug
+pnpm install
+pnpm run debug
 ```
 
 Scoped example (directory defaults to the package portion):
@@ -24,8 +24,8 @@ Scoped example (directory defaults to the package portion):
 ```sh
 npx @o3co/create-auth-policy-verifier @my-org/auth.policy-verifier
 cd auth.policy-verifier
-npm install
-npm run debug
+pnpm install
+pnpm run debug
 ```
 
 Override the directory name with `--dir`:
@@ -42,7 +42,25 @@ cd verifier
 3. Aborts with an error if the target directory already exists.
 4. Copies `templates/standalone/` to the target directory, excluding `node_modules/` and `dist/`.
 5. Rewrites `package.json`: sets `name` to `<project-name>` verbatim (scope-preserving), removes `private`, and replaces `workspace:*` dependency versions with published semver versions from `templates/versions.json`.
-6. Prints next-step instructions.
+6. Resolves that dependency set into `pnpm-lock.yaml` (`pnpm install --lockfile-only --ignore-workspace`), unless `--no-lockfile` was passed.
+7. Prints next-step instructions.
+
+### The generated `pnpm-lock.yaml`
+
+The template's `Dockerfile` installs with `pnpm install --frozen-lockfile`, so
+the generated project needs a lockfile to build at all. It cannot ship with the
+template: until step 5 has replaced every `workspace:*` with a published
+version, the dependency set the lockfile would have to pin does not exist. So
+it is resolved once, here, against the rewritten `package.json`. **Commit it** —
+it is what makes `docker build` reproducible.
+
+Step 6 needs `pnpm` (or `corepack`) and a reachable registry, and neither is
+guaranteed on the machine running the scaffolder. It is therefore best-effort:
+on failure the scaffold still succeeds and prints what to do, because the
+generated project is perfectly usable without a lockfile — it just cannot be
+built into an image until `pnpm install` has been run once. Pass
+`--no-lockfile` to skip the step outright (offline scaffolding, or a pipeline
+that installs later anyway).
 
 ## Validation Rules
 
@@ -72,6 +90,7 @@ The bundled template's `README.md` / `README.ja.md` still carry the upstream tit
 ├── docker-compose.yml
 ├── docker-compose.test.yml
 ├── package.json
+├── pnpm-lock.yaml          # Generated at scaffold time — commit it
 └── tsconfig.json
 ```
 
@@ -86,7 +105,8 @@ import { scaffold, main } from "@o3co/create-auth-policy-verifier";
 | Export | Signature | Description |
 |---|---|---|
 | `scaffold` | `(targetDir: string, projectName: string): void` | Copies the template and rewrites `package.json` |
-| `main` | `(): void` | CLI entry point — parses `process.argv` and calls `scaffold` |
+| `generateLockfile` | `(targetDir: string): LockfileResult` | Resolves `pnpm-lock.yaml` in an already-scaffolded directory; reports failure rather than throwing |
+| `main` | `(): void` | CLI entry point — parses `process.argv`, calls `scaffold`, then `generateLockfile` |
 
 ## See Also
 

package/dist/index.d.mts

@@ -1,3 +1,14 @@
+/**
+ * Decides whether one entry of the template tree is copied into a new project.
+ *
+ * The exclusion is judged on the path RELATIVE to the template root, which is
+ * the whole point: the scaffolder ships inside `node_modules` whenever it is
+ * run the documented way (`npm create`, `npx`), so every absolute source path
+ * it copies from contains a `node_modules` segment. Matching against the
+ * absolute path therefore rejected the entire template and produced an empty
+ * project directory — the scaffolder only ever worked from a source checkout.
+ */
+export declare const isTemplateEntryIncluded: (templatesDir: string, source: string) => boolean;
 export declare const isValidProjectName: (name: string) => boolean;
 export declare const isValidDirName: (name: string) => boolean;
 /**
@@ -9,6 +20,29 @@ export declare const isValidDirName: (name: string) => boolean;
  * workspace dependency is not pinned in `versions.json`.
  */
 export declare const scaffold: (targetDir: string, projectName: string) => void;
+/** Outcome of the scaffold-time lockfile generation. */
+export type LockfileResult = {
+    readonly ok: true;
+    readonly command: string;
+} | {
+    readonly ok: false;
+    readonly reason: string;
+};
+/**
+ * Generates `pnpm-lock.yaml` inside an already-scaffolded `targetDir`.
+ *
+ * This is what makes the template's `pnpm install --frozen-lockfile` build
+ * possible: the lockfile cannot be shipped with the template, because the
+ * template's dependency set does not exist until `scaffold` has replaced every
+ * `workspace:*` with a published version. So it is resolved here, once, against
+ * the rewritten `package.json`, and the project commits the result.
+ *
+ * Best-effort by design: it needs a package manager and a reachable registry,
+ * and neither is guaranteed on the machine running the scaffolder. Failure is
+ * reported, never thrown — the generated project is perfectly usable without
+ * it, the operator just has to run `pnpm install` before `docker build`.
+ */
+export declare const generateLockfile: (targetDir: string) => LockfileResult;
 /**
  * CLI entry point: parses argv, validates project name and optional --dir flag,
  * ensures the target directory does not exist, and scaffolds the template.

package/dist/index.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.mts","sourceRoot":"","sources":["../src/index.mts"],"names":[],"mappings":"AA2BA,eAAO,MAAM,kBAAkB,GAAI,MAAM,MAAM,KAAG,OAIjD,CAAC;AAEF,eAAO,MAAM,cAAc,GAAI,MAAM,MAAM,KAAG,OAI7C,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,QAAQ,GAAI,WAAW,MAAM,EAAE,aAAa,MAAM,KAAG,IA0CjE,CAAC;AAqDF;;;;GAIG;AACH,eAAO,MAAM,IAAI,QAAO,IA4CvB,CAAC"}
+{"version":3,"file":"index.d.mts","sourceRoot":"","sources":["../src/index.mts"],"names":[],"mappings":"AA2BA;;;;;;;;;GASG;AACH,eAAO,MAAM,uBAAuB,GAAI,cAAc,MAAM,EAAE,QAAQ,MAAM,KAAG,OAI9E,CAAC;AAMF,eAAO,MAAM,kBAAkB,GAAI,MAAM,MAAM,KAAG,OAIjD,CAAC;AAEF,eAAO,MAAM,cAAc,GAAI,MAAM,MAAM,KAAG,OAI7C,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,QAAQ,GAAI,WAAW,MAAM,EAAE,aAAa,MAAM,KAAG,IA0CjE,CAAC;AAEF,wDAAwD;AACxD,MAAM,MAAM,cAAc,GACvB;IAAE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GAC/C;IAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAyBnD;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,gBAAgB,GAAI,WAAW,MAAM,KAAG,cA6BpD,CAAC;AAyDF;;;;GAIG;AACH,eAAO,MAAM,IAAI,QAAO,IAgEvB,CAAC"}

package/dist/index.mjs

@@ -1,7 +1,8 @@
 // SPDX-FileCopyrightText: 2026 1o1 Co. Ltd.
 // SPDX-License-Identifier: Apache-2.0
+import { spawnSync } from "node:child_process";
 import { cpSync, existsSync, readFileSync, writeFileSync } from "node:fs";
-import { dirname, resolve, sep } from "node:path";
+import { dirname, relative, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const TEMPLATES_DIR = resolve(__dirname, "../templates/standalone");
@@ -17,6 +18,24 @@ const getPackageVersions = () => {
     }
     return {};
 };
+/** Directories that are build output inside the template, never scaffolded. */
+const EXCLUDED_DIRS = new Set(["node_modules", "dist"]);
+/**
+ * Decides whether one entry of the template tree is copied into a new project.
+ *
+ * The exclusion is judged on the path RELATIVE to the template root, which is
+ * the whole point: the scaffolder ships inside `node_modules` whenever it is
+ * run the documented way (`npm create`, `npx`), so every absolute source path
+ * it copies from contains a `node_modules` segment. Matching against the
+ * absolute path therefore rejected the entire template and produced an empty
+ * project directory — the scaffolder only ever worked from a source checkout.
+ */
+export const isTemplateEntryIncluded = (templatesDir, source) => {
+    const rel = relative(templatesDir, source);
+    if (rel === "")
+        return true;
+    return !rel.split(sep).some((segment) => EXCLUDED_DIRS.has(segment));
+};
 const UNSCOPED_NAME_RE = /^[a-z0-9][a-z0-9-._~]*$/;
 const SCOPED_NAME_RE = /^@[a-z0-9][a-z0-9-._~]*\/[a-z0-9][a-z0-9-._~]*$/;
 const MAX_NAME_LEN = 214;
@@ -47,19 +66,19 @@ export const scaffold = (targetDir, projectName) => {
         throw new Error(`Template directory not found at ${TEMPLATES_DIR}. If developing locally, run the prebuild script first.`);
     }
     // Copy template to target
-    const EXCLUDED_DIRS = new Set(["node_modules", "dist"]);
     cpSync(TEMPLATES_DIR, targetDir, {
         recursive: true,
-        filter: (source) => {
-            const segments = source.split(sep);
-            return !segments.some((s) => EXCLUDED_DIRS.has(s));
-        },
+        filter: (source) => isTemplateEntryIncluded(TEMPLATES_DIR, source),
     });
     // Rewrite package.json
     const pkgPath = resolve(targetDir, "package.json");
     const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
     pkg.name = projectName;
-    delete pkg.private;
+    // `"private": true` is deliberately KEPT (#126 item 4). The scaffold is an
+    // authorization service — policy code and config — and deleting the field
+    // made an accidental `npm publish` succeed by default. Publishing a
+    // scaffolded service is the rare intent; the operator who has it states it
+    // by removing the field.
     // Replace all workspace:* references with per-package published versions
     const versions = getPackageVersions();
     for (const section of ["dependencies", "devDependencies", "peerDependencies"]) {
@@ -78,10 +97,73 @@ export const scaffold = (targetDir, projectName) => {
     }
     writeFileSync(pkgPath, `${JSON.stringify(pkg, null, 2)}\n`);
 };
+/**
+ * Arguments that make pnpm resolve the dependency graph and write
+ * `pnpm-lock.yaml` without linking `node_modules` or running any lifecycle
+ * script. `--ignore-workspace` keeps the new project's lockfile its own even
+ * when the target directory happens to sit inside another pnpm workspace.
+ */
+const LOCKFILE_ARGS = ["install", "--lockfile-only", "--ignore-workspace"];
+/**
+ * Launchers tried in order. `pnpm` on PATH is the common case; `corepack pnpm`
+ * covers a machine that only has Node, and honours the `packageManager` field
+ * the template ships.
+ *
+ * The fallback is narrow on purpose: it applies to `ENOENT` and nothing else,
+ * because `ENOENT` is the one failure that means "this binary is not here" and
+ * is therefore the only one a different launcher can answer. Any other launch
+ * error (`EACCES`, `EPERM`, …) says the binary IS there and could not be run,
+ * and a package manager that ran and exited non-zero has already reported that
+ * resolution failed — retrying either would hide the real cause behind
+ * "package manager missing" and hand the operator the wrong instruction.
+ */
+const LOCKFILE_LAUNCHERS = [["pnpm"], ["corepack", "pnpm"]];
+/**
+ * Generates `pnpm-lock.yaml` inside an already-scaffolded `targetDir`.
+ *
+ * This is what makes the template's `pnpm install --frozen-lockfile` build
+ * possible: the lockfile cannot be shipped with the template, because the
+ * template's dependency set does not exist until `scaffold` has replaced every
+ * `workspace:*` with a published version. So it is resolved here, once, against
+ * the rewritten `package.json`, and the project commits the result.
+ *
+ * Best-effort by design: it needs a package manager and a reachable registry,
+ * and neither is guaranteed on the machine running the scaffolder. Failure is
+ * reported, never thrown — the generated project is perfectly usable without
+ * it, the operator just has to run `pnpm install` before `docker build`.
+ */
+export const generateLockfile = (targetDir) => {
+    const attempts = [];
+    for (const launcher of LOCKFILE_LAUNCHERS) {
+        const [bin, ...prefix] = launcher;
+        const args = [...prefix, ...LOCKFILE_ARGS];
+        const printable = [bin, ...args].join(" ");
+        const result = spawnSync(bin, args, {
+            cwd: targetDir,
+            stdio: "inherit",
+            shell: false,
+            env: { ...process.env, COREPACK_ENABLE_DOWNLOAD_PROMPT: "0" },
+        });
+        if (result.error) {
+            attempts.push(`${printable}: ${result.error.message}`);
+            // Only "not on PATH" is worth asking a different launcher about.
+            if (result.error.code === "ENOENT")
+                continue;
+            break;
+        }
+        if (result.status === 0)
+            return { ok: true, command: printable };
+        const how = result.status === null ? `killed by signal ${result.signal}` : `exit code ${result.status}`;
+        attempts.push(`${printable}: ${how}`);
+        break;
+    }
+    return { ok: false, reason: attempts.join("; ") };
+};
 const parseArgs = (args) => {
     const positionals = [];
     let dir;
     let dirSeen = false;
+    let lockfile = true;
     for (let i = 0; i < args.length; i++) {
         const a = args[i];
         if (a === "--dir") {
@@ -99,6 +181,9 @@ const parseArgs = (args) => {
             dir = a.slice("--dir=".length);
             dirSeen = true;
         }
+        else if (a === "--no-lockfile") {
+            lockfile = false;
+        }
         else if (a.startsWith("-")) {
             // Treats `--` and any --unknown as an unknown flag.
             throw new Error(`unknown flag: ${a}`);
@@ -111,7 +196,7 @@ const parseArgs = (args) => {
         throw new Error("missing <project-name>");
     if (positionals.length > 1)
         throw new Error("too many positional arguments");
-    return { projectName: positionals[0], dir };
+    return { projectName: positionals[0], dir, lockfile };
 };
 const deriveDirName = (projectName, dir) => {
     if (dir !== undefined)
@@ -141,10 +226,10 @@ export const main = () => {
     }
     catch (e) {
         console.error(`Error: ${e.message}`);
-        console.error("Usage: @o3co/create-auth-policy-verifier <project-name> [--dir <dir-name>]");
+        console.error("Usage: @o3co/create-auth-policy-verifier <project-name> [--dir <dir-name>] [--no-lockfile]");
         process.exit(1);
     }
-    const { projectName, dir } = parsed;
+    const { projectName, dir, lockfile } = parsed;
     if (!isValidProjectName(projectName)) {
         console.error("Error: <project-name> must be a valid npm package name (scoped like @scope/pkg, or unscoped; max 214 chars; no backslashes; no extra '/' beyond the single scope separator).");
         process.exit(1);
@@ -161,9 +246,22 @@ export const main = () => {
     }
     console.log(`Creating ${projectName}...`);
     scaffold(targetDir, projectName);
+    let lockfileGenerated = false;
+    if (lockfile) {
+        console.log("\nResolving dependencies into pnpm-lock.yaml...");
+        const result = generateLockfile(targetDir);
+        lockfileGenerated = result.ok;
+        if (!result.ok) {
+            console.error(`\nWarning: could not generate pnpm-lock.yaml (${result.reason}).`);
+            console.error(`Run 'pnpm install' in ${dirName} and commit pnpm-lock.yaml: the Dockerfile installs with --frozen-lockfile and will not build without it.`);
+        }
+    }
     console.log(`\nDone! Created ${projectName} at ${targetDir}`);
+    if (lockfileGenerated) {
+        console.log("\nCommit pnpm-lock.yaml along with the rest: it is what makes 'docker build' reproducible.");
+    }
     console.log(`\nNext steps:`);
     console.log(`  cd ${dirName}`);
-    console.log("  npm install");
-    console.log("  npm run debug");
+    console.log("  pnpm install");
+    console.log("  pnpm run debug");
 };

package/package.json

@@ -1,31 +1,41 @@
 {
-	"name": "@o3co/create-auth-policy-verifier",
-	"version": "0.3.1",
-	"description": "Scaffold a new o3co/auth.policy-verifier project from the standalone template",
-	"license": "Apache-2.0",
-	"type": "module",
-	"repository": {
-		"type": "git",
-		"url": "https://github.com/o3co/auth.policy-verifier.git",
-		"directory": "create-app"
-	},
-	"engines": {
-		"node": ">=22.0.0"
-	},
-	"bin": {
-		"create-auth-policy-verifier": "./dist/cli.mjs"
-	},
-	"files": [
-		"dist",
-		"templates"
-	],
-	"scripts": {
-		"build": "tsc",
-		"prebuild": "node scripts/copy-templates.mjs",
-		"test": "vitest run"
-	},
-	"devDependencies": {
-		"@types/node": "^25.1.0",
-		"vitest": "^4.1.4"
-	}
-}
+  "name": "@o3co/create-auth-policy-verifier",
+  "version": "0.5.0",
+  "description": "Scaffold a new o3co/auth.policy-verifier project from the standalone template",
+  "license": "Apache-2.0",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/o3co/auth.policy-verifier.git",
+    "directory": "create-app"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "main": "./dist/index.mjs",
+  "types": "./dist/index.d.mts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "import": "./dist/index.mjs"
+    }
+  },
+  "bin": {
+    "create-auth-policy-verifier": "./dist/cli.mjs"
+  },
+  "files": [
+    "dist",
+    "templates"
+  ],
+  "devDependencies": {
+    "@types/node": "^26.4.0",
+    "vitest": "^4.1.11"
+  },
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit -p tsconfig.typecheck.json",
+    "prebuild": "node scripts/copy-templates.mjs",
+    "pretest": "node scripts/copy-templates.mjs",
+    "test": "vitest run"
+  }
+}

package/templates/standalone/Dockerfile

@@ -1,9 +1,18 @@
-FROM node:24-alpine AS node-base
+# The base image is pinned by digest, not just by tag: `node:24-alpine` is a
+# moving pointer, so the same source produced a different image on every
+# rebuild. The digest is the multi-arch index, so amd64 and arm64 both resolve
+# from it. Dependabot's `docker` ecosystem keeps the pair in step — bump the
+# tag and the digest together, never the tag alone.
+FROM node:24-alpine@sha256:d32cdf619f63fe0471182d08996dd516c6275bb5fd31ae06e55a570bd9e1ad43 AS node-base
 
 ENV HOME=/home/node
 
+# corepack is pinned too. `npm install -g corepack --force` resolved whatever
+# was latest at build time, which is a mutable dependency of every build. The
+# pnpm version itself comes from the `packageManager` field in package.json,
+# which corepack reads.
 RUN apk add --no-cache tini \
- && npm install -g corepack --force \
+ && npm install -g corepack@0.35.0 --force \
  && corepack enable
 
 WORKDIR /home/node
@@ -11,34 +20,89 @@ WORKDIR /home/node
 #############################################
 FROM node-base AS deps
 
-COPY package.json ./
+# pnpm-lock.yaml is a required build input: `create-auth-policy-verifier`
+# generates it at scaffold time and the project commits it. Without it this
+# COPY fails, which is the intended outcome — a build that silently re-resolves
+# every dependency range is the thing this file stopped doing.
+COPY --chown=node:node package.json pnpm-lock.yaml ./
 
-RUN pnpm install
+USER node
+
+# --frozen-lockfile: install exactly what the lockfile pins, and fail if
+# package.json and the lockfile disagree, rather than quietly rewriting it.
+RUN pnpm install --frozen-lockfile
 
 #############################################
 FROM deps AS builder
 
-COPY tsconfig.json ./
-COPY config/ ./config/
-COPY src/ ./src/
+# USER node inherited from deps stage; repeated here to make the builder
+# hardening invariant obvious in Dockerfile reviews.
+USER node
+
+# tsconfig*.json, not tsconfig.json: the template also ships
+# tsconfig.typecheck.json, which is what `pnpm run typecheck` reads. Copying the
+# whole set keeps the test and develop stages able to run it.
+COPY --chown=node:node tsconfig*.json ./
+COPY --chown=node:node config/ ./config/
+COPY --chown=node:node src/ ./src/
 
 RUN pnpm run build
 
+#############################################
+# Dependencies are resolved once, in `deps`. This stage drops the dev half of
+# that same tree instead of running a second `pnpm install --prod` in the
+# runtime stage: a second install is a second resolution, and therefore a
+# second chance for the runtime image to hold something the build never saw.
+FROM deps AS prod-deps
+
+USER node
+
+RUN pnpm prune --prod
+
 #############################################
 FROM node-base AS runtime
 
 ENV NODE_ENV=production
 
 COPY --from=deps /home/node/package.json /home/node/pnpm-lock.yaml ./
-
-RUN pnpm install --prod \
- && pnpm store prune
-
+COPY --from=prod-deps /home/node/node_modules/ ./node_modules/
 COPY --from=builder /home/node/dist/ ./dist/
 COPY --from=builder /home/node/config/ ./config/
 
 USER node
 
+ENV HTTP_PORT=3000
+EXPOSE ${HTTP_PORT}
+
+# Probes the container's own routable address, NOT 127.0.0.1 — deliberately.
+#
+# `application.conf` binds loopback by default (#108), because /verify answers
+# with an authorization decision and a reachable port is a decision oracle. A
+# container that keeps that default is reachable from nothing: the published
+# port never connects. A probe against 127.0.0.1 passes anyway — inside the
+# container loopback is exactly where the server is listening — so it would
+# report "healthy" for a container no caller can reach. That is the one failure
+# this check exists to catch, so it asks the same question a caller does:
+# "does the port answer at the address the container is reachable at?"
+#
+# `hostname -i` yields the container's IP; a v6 literal is bracketed for the
+# URL. `${HTTP_PATH_PREFIX}` keeps the probe on the mount point the server
+# actually used (`http.pathPrefix`), and `${HTTP_PORT}` keeps it on the
+# operator's port — the config reads `${?HTTP_PORT}`, so app.listen() and the
+# probe stay in sync. Shell form, so both expand at probe time.
+#
+# `GET /healthcheck` is never gated by `http.callerAuth`, so setting
+# HTTP_CALLER_AUTH_TOKEN does not require a credential here.
+#
+# The deployment where loopback is genuinely correct — a sidecar sharing a
+# network namespace with its caller — is the one shape this check is wrong for.
+# That deployment overrides `healthcheck:` per service, which keeps the
+# restart-driving signal honest for everyone else.
+HEALTHCHECK --interval=30s --timeout=3s --start-period=10s --retries=3 \
+  CMD addr="$(hostname -i | cut -d' ' -f1)"; \
+      case "$addr" in *:*) addr="[$addr]" ;; esac; \
+      wget -q -O /dev/null "http://${addr}:${HTTP_PORT}${HTTP_PATH_PREFIX%/}/healthcheck" || exit 1
+
 ENTRYPOINT ["tini", "--"]
 CMD ["node", "dist/main.mjs"]