@b12k/caddy 0.0.0-stage → 2.11.7-v.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Bogdan Kolesnyk
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,139 @@
-# Temporary Holding Version
+# The missing npm wrapper for [Caddy](https://caddyserver.com)
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[Caddy](https://caddyserver.com) is a web server and reverse proxy with automatic HTTPS.
+
+This library is a thin wrapper which automatically downloads the correct Caddy binary for your platform on install, verifies its SHA-512 checksum, and exposes it as a CLI command.
+
+## Installation
+
+Typically installed as a dev dependency:
+
+**Local (project)**
+
+```bash
+npm install --save-dev @b12k/caddy
+```
+
+Recent npm versions require approving dependency install scripts. Approve this package so its postinstall script can download the Caddy binary:
+
+```bash
+npm approve-scripts @b12k/caddy
+```
+
+```bash
+pnpm add -D --allow-build=@b12k/caddy @b12k/caddy
+```
+
+pnpm 11 and later require the `--allow-build` flag so this package's postinstall script can download the Caddy binary.
+
+```bash
+yarn add --dev @b12k/caddy
+```
+
+**Global**
+
+```bash
+npm install -g --allow-scripts=@b12k/caddy @b12k/caddy
+```
+
+Global npm installs cannot use `npm approve-scripts`; use `--allow-scripts` instead.
+
+```bash
+pnpm add -g --allow-build=@b12k/caddy @b12k/caddy
+```
+
+pnpm 11 and later require the `--allow-build` flag during global install as well.
+
+```bash
+yarn global add @b12k/caddy
+```
+
+The postinstall script downloads the standard Caddy binary for your platform from the [official GitHub release](https://github.com/caddyserver/caddy/releases). Custom builds and additional plugins are not included.
+
+If you already installed with npm or pnpm and the build was blocked, approve and rebuild it:
+
+```bash
+npm approve-scripts @b12k/caddy
+npm rebuild @b12k/caddy
+```
+
+```bash
+pnpm approve-builds @b12k/caddy
+pnpm rebuild @b12k/caddy
+```
+
+## Usage
+
+See the [Caddy CLI documentation](https://caddyserver.com/docs/command-line) for the full list of commands and flags.
+
+**Local install**
+
+```bash
+npx caddy run --config Caddyfile
+```
+
+```bash
+pnpm exec caddy run --config Caddyfile
+```
+
+```bash
+yarn caddy run --config Caddyfile
+```
+
+**Global install**
+
+```bash
+caddy run --config Caddyfile
+```
+
+**`package.json` script**
+
+```json
+{ "scripts": { "serve": "caddy run --config Caddyfile" } }
+```
+
+To serve the current directory without a Caddyfile:
+
+```bash
+pnpm exec caddy file-server --listen localhost:8080
+```
+
+To check the installed binary version:
+
+```bash
+pnpm exec caddy version
+```
+
+## Troubleshooting
+
+If the binary fails to install, re-run with `--foreground-scripts` to see the postinstall output:
+
+```bash
+npm install --save-dev @b12k/caddy --foreground-scripts
+```
+
+```bash
+pnpm add -D --allow-build=@b12k/caddy @b12k/caddy --foreground-scripts
+```
+
+```bash
+yarn add --dev @b12k/caddy --foreground-scripts
+```
+
+## Supported platforms
+
+- Linux — x64, arm64
+- macOS — x64, arm64
+- Windows — x64, arm64
+
+## Version
+
+The npm package version mirrors the Caddy release version, with a wrapper revision suffix (for example, `2.11.7-v.0`).
+
+To install a different Caddy release, define it in `.caddy-version` as `v2.11.7` or `2.11.7` before installing the package. The file is read from the install command's initial working directory (`INIT_CWD`), or the current working directory when `INIT_CWD` is unset.
+
+If you add or change `.caddy-version` after installing, run from that directory:
+
+```bash
+pnpm exec caddy-install
+```

package/dist/cli.js

@@ -0,0 +1,42 @@
+#!/usr/bin/env node
+import { spawn } from "node:child_process";
+import { access } from "node:fs/promises";
+import update_notifier from "update-notifier";
+import { binaryPath, name as external_config_js_name, version } from "./config.js";
+import { logError } from "./log.js";
+function setErrorExitCode(errorName, metaInfo) {
+    try {
+        logError(errorName, metaInfo);
+    } catch  {
+        process.exitCode = 1;
+    }
+}
+update_notifier({
+    pkg: {
+        name: external_config_js_name,
+        version: version
+    },
+    shouldNotifyInNpmScript: true,
+    updateCheckInterval: 86400000
+}).notify({
+    defer: false
+});
+let canSpawn = true;
+try {
+    await access(binaryPath);
+} catch  {
+    setErrorExitCode('binaryNotFound');
+    canSpawn = false;
+}
+if (canSpawn) {
+    const childProcess = spawn(binaryPath, process.argv.slice(2), {
+        stdio: 'inherit'
+    });
+    childProcess.on('error', (error)=>{
+        setErrorExitCode('executionFailed', error.message);
+    });
+    childProcess.on('exit', (code, signal)=>{
+        if (signal) return void process.kill(process.pid, signal);
+        process.exitCode = code ?? 1;
+    });
+}

package/dist/config.js

@@ -0,0 +1,50 @@
+import { readFile } from "node:fs/promises";
+import node_path from "node:path";
+import package_0 from "../package.json" with {
+    type: "json"
+};
+const platform = 'win32' === process.platform ? 'windows' : process.platform;
+const isWindows = 'windows' === platform;
+const { arch: architecture } = process;
+const { name: config_name, version: version } = package_0;
+const [defaultVersion = ''] = version.split('-', 1);
+const versionFileName = '.caddy-version';
+const versionFilePath = node_path.join(process.env['INIT_CWD'] ?? process.cwd(), versionFileName);
+let versionOverride;
+try {
+    const fileContents = await readFile(versionFilePath, 'utf8');
+    versionOverride = fileContents.trim().replace(/^v/u, '');
+} catch (error) {
+    if (!(error instanceof Error && 'code' in error && 'ENOENT' === error.code)) {
+        const message = Error.isError(error) ? error.message : 'Unknown error.';
+        throw new Error(`Failed to read ${versionFileName}: ${message}`, {
+            cause: error
+        });
+    }
+    versionOverride = '';
+}
+const libraryVersion = versionOverride || defaultVersion;
+const currentDirectory = import.meta.dirname;
+const libraryName = 'caddy';
+const binaryExtension = isWindows ? '.exe' : '';
+const binaryFileName = `${libraryName}${binaryExtension}`;
+const binaryPath = node_path.join(currentDirectory, binaryFileName);
+const archiveExtension = isWindows ? '.zip' : '.tar.gz';
+const archivePlatform = 'darwin' === platform ? 'mac' : platform;
+const archiveArchitecture = 'x64' === architecture ? 'amd64' : architecture;
+const archiveFileName = `${libraryName}_${libraryVersion}_${archivePlatform}_${archiveArchitecture}${archiveExtension}`;
+const checksumsFileName = `${libraryName}_${libraryVersion}_checksums.txt`;
+const caddyGithubUrl = `https://github.com/caddyserver/caddy/releases/download/v${libraryVersion}`;
+const archiveGithubUrl = `${caddyGithubUrl}/${archiveFileName}`;
+const checksumsGithubUrl = `${caddyGithubUrl}/${checksumsFileName}`;
+const archivePath = node_path.join(currentDirectory, archiveFileName);
+const supportedPlatforms = [
+    'darwin',
+    'windows',
+    'linux'
+];
+const supportedArchitectures = [
+    'x64',
+    'arm64'
+];
+export { architecture, archiveFileName, archiveGithubUrl, archivePath, binaryPath, checksumsGithubUrl, config_name as name, currentDirectory, libraryName, libraryVersion, platform, supportedArchitectures, supportedPlatforms, version };

package/dist/errors.js

@@ -0,0 +1,27 @@
+const ERRORS_BY_KEY = {
+    binaryNotFound: {
+        instruction: 'Try re-installing the library.',
+        message: 'Binary not found.'
+    },
+    executionFailed: {
+        instruction: 'Try re-installing the library.',
+        message: 'Failed to execute the binary.'
+    },
+    installationFailed: {
+        instruction: '',
+        message: 'Failed to install the binary.'
+    },
+    unsupportedArchitecture: {
+        instruction: 'Supported architectures are x64 and arm64.',
+        message: 'Unsupported architecture.'
+    },
+    unsupportedArchiveFormat: {
+        instruction: 'Supported archive formats are .zip and .tar.gz.',
+        message: 'Unsupported archive format.'
+    },
+    unsupportedPlatform: {
+        instruction: 'Supported platforms are darwin, windows and linux.',
+        message: 'Unsupported platform.'
+    }
+};
+export { ERRORS_BY_KEY };

package/dist/extract-archive.js

@@ -0,0 +1,23 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { extract } from "tar";
+import { logError } from "./log.js";
+const execFileAsync = promisify(execFile);
+async function extractArchive(archivePath, targetDirectoryPath) {
+    if (archivePath.endsWith('.zip')) {
+        const quotedArchivePath = `'${archivePath.replaceAll("'", "''")}'`;
+        const quotedTargetDirectoryPath = `'${targetDirectoryPath.replaceAll("'", "''")}'`;
+        await execFileAsync('powershell.exe', [
+            '-NoProfile',
+            '-Command',
+            `Expand-Archive -LiteralPath ${quotedArchivePath} -DestinationPath ${quotedTargetDirectoryPath} -Force`
+        ]);
+        return;
+    }
+    if (archivePath.endsWith('.tar.gz')) return void await extract({
+        cwd: targetDirectoryPath,
+        file: archivePath
+    });
+    logError('unsupportedArchiveFormat', archivePath);
+}
+export { extractArchive };

package/dist/log.js

@@ -0,0 +1,19 @@
+import boxen from "boxen";
+import { libraryName } from "./config.js";
+import { ERRORS_BY_KEY } from "./errors.js";
+function log(message, options) {
+    console.log(boxen(message, options));
+}
+const errorPrefix = `[${libraryName}]`;
+function logError(errorName, metaInfo) {
+    const error = ERRORS_BY_KEY[errorName];
+    let logMessage = error.message;
+    if (error.instruction) logMessage += `\n\n${error.instruction}`;
+    if (metaInfo) logMessage += `\n\n${metaInfo}`;
+    log(logMessage, {
+        borderColor: 'red',
+        title: errorPrefix
+    });
+    throw new Error(`${errorPrefix} ${error.message}`);
+}
+export { log, logError };

package/dist/postinstall.js

@@ -0,0 +1,73 @@
+#!/usr/bin/env node
+import { createHash } from "node:crypto";
+import { createWriteStream } from "node:fs";
+import { readFile, rm } from "node:fs/promises";
+import { pipeline } from "node:stream/promises";
+import { architecture, archiveFileName, archiveGithubUrl, archivePath, binaryPath, checksumsGithubUrl, currentDirectory, libraryName, platform, supportedArchitectures, supportedPlatforms } from "./config.js";
+import { extractArchive } from "./extract-archive.js";
+import { log, logError } from "./log.js";
+const DOWNLOAD_TIMEOUT_MS = 300000;
+if (!supportedPlatforms.includes(platform)) logError('unsupportedPlatform');
+if (!supportedArchitectures.includes(architecture)) logError('unsupportedArchitecture');
+async function createFetchResponse(url) {
+    const response = await fetch(url, {
+        signal: AbortSignal.timeout(DOWNLOAD_TIMEOUT_MS)
+    });
+    if (!response.ok) throw new Error(String(response.status));
+    return response;
+}
+async function downloadArchive() {
+    log(archiveGithubUrl, {
+        borderColor: 'green',
+        title: `${libraryName}:download`
+    });
+    const response = await createFetchResponse(archiveGithubUrl);
+    if (!response.body) throw new Error('Archive download returned no body.');
+    log(archivePath, {
+        borderColor: 'green',
+        title: `${libraryName}:save`
+    });
+    await pipeline(response.body, createWriteStream(archivePath));
+}
+async function ensureArchiveChecksum() {
+    log(checksumsGithubUrl, {
+        borderColor: 'green',
+        title: `${libraryName}:verify`
+    });
+    const response = await createFetchResponse(checksumsGithubUrl);
+    const checksums = await response.text();
+    const checksum = checksums.split('\n').find((line)=>line.endsWith(` ${archiveFileName}`))?.split(/\s+/u, 1)[0];
+    if (!checksum) throw new Error(`Checksum not found for ${archiveFileName}.`);
+    const archive = await readFile(archivePath);
+    const actualChecksum = createHash('sha512').update(archive).digest('hex');
+    if (actualChecksum !== checksum) throw new Error(`Checksum mismatch for ${archiveFileName}.`);
+}
+async function install() {
+    await downloadArchive();
+    await ensureArchiveChecksum();
+    log(currentDirectory, {
+        borderColor: 'green',
+        title: `${libraryName}:extract`
+    });
+    await extractArchive(archivePath, currentDirectory);
+    log(binaryPath, {
+        borderColor: 'green',
+        title: `${libraryName}:installed`
+    });
+}
+async function installWithCleanup() {
+    try {
+        await install();
+    } finally{
+        await rm(archivePath, {
+            force: true
+        });
+    }
+}
+try {
+    await installWithCleanup();
+} catch (error) {
+    let message = 'Unknown error.';
+    if (Error.isError(error)) message = error.message;
+    logError('installationFailed', message);
+}

package/package.json

@@ -1,6 +1,93 @@
 {
   "name": "@b12k/caddy",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "2.11.7-v.0",
+  "description": "The missing NPM wrapper for Caddy",
+  "keywords": [
+    "automatic-https",
+    "caddy",
+    "cli",
+    "development",
+    "http",
+    "https",
+    "npm",
+    "reverse-proxy",
+    "server",
+    "static-files",
+    "web-server",
+    "wrapper"
+  ],
+  "license": "MIT",
+  "author": "Bogdan Kolesnyk",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/b12k/caddy.git"
+  },
+  "bin": {
+    "caddy": "dist/cli.js",
+    "caddy-install": "dist/postinstall.js"
+  },
+  "files": [
+    "dist",
+    "scripts"
+  ],
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "rslib",
+    "check": "run-p -l check:*",
+    "check:format": "oxfmt . --check",
+    "check:scripts": "oxlint",
+    "check:types": "tsc --noEmit",
+    "deps:check": "ncu -e 2 -c 1",
+    "deps:update": "ncu -du --doctorInstall \"pnpm deps:update:install\" --doctorTest \"pnpm deps:update:doctor\" -c 1",
+    "deps:update:doctor": "run-p -l check:types check:scripts build",
+    "deps:update:install": "pnpm i --no-frozen-lockfile",
+    "dev": "rslib --watch",
+    "fix": "run-s -l fix:*",
+    "fix:format": "oxfmt . --write",
+    "fix:scripts": "oxlint --fix",
+    "ga:notify": "tsx .github/notify.ts",
+    "ga:update-caddy": "tsx .github/update-caddy.ts",
+    "husky:commit-msg": "commitlint",
+    "husky:pre-commit": "lint-staged",
+    "husky:pre-push": "branch-name-lint",
+    "postinstall": "node scripts/postinstall.js",
+    "prepack": "run-p check build",
+    "prepare": "husky",
+    "release": "release-it --preRelease=v"
+  },
+  "dependencies": {
+    "boxen": "9.0.0",
+    "pnpm": "12.16.1",
+    "tar": "7.5.22",
+    "update-notifier": "7.3.1"
+  },
+  "devDependencies": {
+    "@b12k/branch-name-lint": "1.3.0",
+    "@commitlint/config-conventional": "21.2.4",
+    "@release-it/conventional-changelog": "12.0.2",
+    "@rslib/core": "1.0.5",
+    "@types/node": "26.6.6",
+    "@types/semver": "7.8.0",
+    "@types/update-notifier": "6.0.9",
+    "commitlint": "21.2.4",
+    "eslint-plugin-perfectionist": "5.13.0",
+    "husky": "9.1.7",
+    "lint-staged": "17.6.0",
+    "npm-check-updates": "23.1.1",
+    "npm-run-all2": "9.0.4",
+    "oxfmt": "0.75.0",
+    "oxlint": "1.90.0",
+    "oxlint-tsgolint": "7.0.2005",
+    "release-it": "21.1.2",
+    "semver": "7.8.5",
+    "tsx": "4.23.15",
+    "typescript": "7.0.2"
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "packageManager": "pnpm@12.16.1"
+}

package/scripts/postinstall.js

@@ -0,0 +1,7 @@
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+const directory = import.meta.dirname;
+// oxlint-disable-next-line unicorn/no-process-exit
+if (!directory.includes('node_modules')) process.exit(0);
+await import(pathToFileURL(path.join(directory, '../dist/postinstall.js')).href);