@xsynaptic/astro-build-logger 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alexander Synaptic
+
+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

@@ -0,0 +1,48 @@
+# @xsynaptic/astro-build-logger
+
+An [Astro][] integration that records how long each build takes and appends a structured entry to a [JSONL][] file. Each entry captures the build duration, page count, total output size, and the Astro and Node versions used, making it easy to track build performance over time.
+
+_Note_: this package is ESM-only.
+
+## Install
+
+```sh
+npm install @xsynaptic/astro-build-logger
+```
+
+## Use
+
+Add the integration to your Astro config:
+
+```ts
+import buildLogger from '@xsynaptic/astro-build-logger';
+import { defineConfig } from 'astro/config';
+
+export default defineConfig({
+	integrations: [buildLogger()],
+});
+```
+
+After each build, an entry is appended to `astro-build.jsonl` in the project root:
+
+```text
+{"timestamp":"2026-06-07T12:00:00.000Z","durationSeconds":42.5,"pageCount":1280,"outputBytes":83214946,"astroVersion":"6.4.4","nodeVersion":"22.22.2","summary":"42s (1280 pages, 79.4 MB)"}
+```
+
+One JSON object per line means the file is append-only and trivially parseable: read it line by line, or pipe it through tools like `jq`.
+
+## Options
+
+```ts
+buildLogger({ logFileName: 'logs/build-times.jsonl' });
+```
+
+- `logFileName` (default `'astro-build.jsonl'`): path to the JSONL log file, resolved relative to the current working directory. Parent directories are not created automatically.
+
+## License
+
+[MIT][mit-license]
+
+[astro]: https://astro.build
+[jsonl]: https://jsonlines.org
+[mit-license]: https://opensource.org/licenses/MIT

package/dist/index.d.mts

@@ -0,0 +1,12 @@
+import { z } from "zod";
+import { AstroIntegration } from "astro";
+
+//#region src/index.d.ts
+declare const optionsSchema: z.ZodOptional<z.ZodObject<{
+  logFileName: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>>;
+type Options = z.input<typeof optionsSchema>;
+declare function buildLogger(options?: Options): AstroIntegration;
+//#endregion
+export { buildLogger as default };
+//# sourceMappingURL=index.d.mts.map

package/dist/index.mjs

@@ -0,0 +1,89 @@
+import astroPackage from "astro/package.json" with { type: "json" };
+import { appendFile, readdir, stat } from "node:fs/promises";
+import { z } from "zod";
+//#region src/index.ts
+const optionsSchema = z.object({ 
+/**
+* Path to the JSONL log file
+*
+* @default `"astro-build.jsonl"`
+*/
+logFileName: z.string().optional() }).optional();
+function formatDuration(totalSeconds) {
+	const hours = Math.floor(totalSeconds / 3600);
+	const minutes = Math.floor(totalSeconds % 3600 / 60);
+	const seconds = Math.round(totalSeconds % 60);
+	if (hours > 0) return `${String(hours)}h ${String(minutes)}m ${String(seconds)}s`;
+	if (minutes > 0) return `${String(minutes)}m ${String(seconds)}s`;
+	return `${String(seconds)}s`;
+}
+function formatBytes(bytes) {
+	const units = [
+		"B",
+		"KB",
+		"MB",
+		"GB"
+	];
+	let value = bytes;
+	let unitIndex = 0;
+	while (value >= 1024 && unitIndex < units.length - 1) {
+		value /= 1024;
+		unitIndex += 1;
+	}
+	const precision = value >= 10 || unitIndex === 0 ? 0 : 1;
+	return `${value.toFixed(precision)} ${units[unitIndex] ?? "B"}`;
+}
+function formatSummary(durationSeconds, pageCount, outputBytes) {
+	return `${formatDuration(durationSeconds)} (${String(pageCount)} pages, ${formatBytes(outputBytes)})`;
+}
+async function getDirectorySize(dir) {
+	const entries = await readdir(dir, { withFileTypes: true });
+	let total = 0;
+	for (const entry of entries) {
+		const child = new URL(entry.isDirectory() ? `${entry.name}/` : entry.name, dir);
+		if (entry.isDirectory()) total += await getDirectorySize(child);
+		else if (entry.isFile()) {
+			const stats = await stat(child);
+			total += stats.size;
+		}
+	}
+	return total;
+}
+function buildLogger(options) {
+	const logFileName = optionsSchema.parse(options)?.logFileName ?? "astro-build.jsonl";
+	let buildStartTime;
+	return {
+		name: "@xsynaptic/astro-build-logger",
+		hooks: {
+			"astro:build:start": ({ logger }) => {
+				buildStartTime = Date.now();
+				logger.info(`Build timing started at ${new Date(buildStartTime).toISOString()}`);
+			},
+			"astro:build:done": async ({ logger, pages, dir }) => {
+				const buildEndTime = Date.now();
+				const durationSeconds = Number(((buildEndTime - buildStartTime) / 1e3).toFixed(2));
+				const outputBytes = await getDirectorySize(dir);
+				const summary = formatSummary(durationSeconds, pages.length, outputBytes);
+				const entry = {
+					timestamp: new Date(buildEndTime).toISOString(),
+					durationSeconds,
+					pageCount: pages.length,
+					outputBytes,
+					astroVersion: astroPackage.version,
+					nodeVersion: process.versions.node,
+					summary
+				};
+				try {
+					await appendFile(logFileName, JSON.stringify(entry) + "\n");
+					logger.info(`Build time logged: ${summary}`);
+				} catch (error) {
+					logger.error(`Failed to write build log: ${error instanceof Error ? error.message : "unknown error"}`);
+				}
+			}
+		}
+	};
+}
+//#endregion
+export { buildLogger as default };
+
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.mjs","names":[],"sources":["../src/index.ts"],"sourcesContent":["import type { AstroIntegration } from 'astro';\n\nimport astroPackage from 'astro/package.json' with { type: 'json' };\nimport { appendFile, readdir, stat } from 'node:fs/promises';\nimport { z } from 'zod';\n\nconst optionsSchema = z\n\t.object({\n\t\t/**\n\t\t * Path to the JSONL log file\n\t\t *\n\t\t * @default `\"astro-build.jsonl\"`\n\t\t */\n\t\tlogFileName: z.string().optional(),\n\t})\n\t.optional();\n\ntype Options = z.input<typeof optionsSchema>;\n\ninterface BuildLogEntry {\n\ttimestamp: string;\n\tdurationSeconds: number;\n\tpageCount: number;\n\toutputBytes: number;\n\tastroVersion: string;\n\tnodeVersion: string;\n\tsummary: string;\n\tnotes?: string;\n}\n\nfunction formatDuration(totalSeconds: number): string {\n\tconst hours = Math.floor(totalSeconds / 3600);\n\tconst minutes = Math.floor((totalSeconds % 3600) / 60);\n\tconst seconds = Math.round(totalSeconds % 60);\n\n\tif (hours > 0) return `${String(hours)}h ${String(minutes)}m ${String(seconds)}s`;\n\tif (minutes > 0) return `${String(minutes)}m ${String(seconds)}s`;\n\n\treturn `${String(seconds)}s`;\n}\n\nfunction formatBytes(bytes: number): string {\n\tconst units = ['B', 'KB', 'MB', 'GB'];\n\tlet value = bytes;\n\tlet unitIndex = 0;\n\n\twhile (value >= 1024 && unitIndex < units.length - 1) {\n\t\tvalue /= 1024;\n\t\tunitIndex += 1;\n\t}\n\n\tconst precision = value >= 10 || unitIndex === 0 ? 0 : 1;\n\n\treturn `${value.toFixed(precision)} ${units[unitIndex] ?? 'B'}`;\n}\n\nfunction formatSummary(durationSeconds: number, pageCount: number, outputBytes: number): string {\n\treturn `${formatDuration(durationSeconds)} (${String(pageCount)} pages, ${formatBytes(outputBytes)})`;\n}\n\nasync function getDirectorySize(dir: URL): Promise<number> {\n\tconst entries = await readdir(dir, { withFileTypes: true });\n\tlet total = 0;\n\n\tfor (const entry of entries) {\n\t\tconst child = new URL(entry.isDirectory() ? `${entry.name}/` : entry.name, dir);\n\n\t\tif (entry.isDirectory()) {\n\t\t\ttotal += await getDirectorySize(child);\n\t\t} else if (entry.isFile()) {\n\t\t\tconst stats = await stat(child);\n\t\t\ttotal += stats.size;\n\t\t}\n\t}\n\treturn total;\n}\n\nexport default function buildLogger(options?: Options): AstroIntegration {\n\tconst parsed = optionsSchema.parse(options);\n\tconst logFileName = parsed?.logFileName ?? 'astro-build.jsonl';\n\n\tlet buildStartTime: number;\n\n\treturn {\n\t\tname: '@xsynaptic/astro-build-logger',\n\t\thooks: {\n\t\t\t'astro:build:start': ({ logger }) => {\n\t\t\t\tbuildStartTime = Date.now();\n\t\t\t\tlogger.info(`Build timing started at ${new Date(buildStartTime).toISOString()}`);\n\t\t\t},\n\t\t\t'astro:build:done': async ({ logger, pages, dir }) => {\n\t\t\t\tconst buildEndTime = Date.now();\n\t\t\t\tconst durationSeconds = Number(((buildEndTime - buildStartTime) / 1000).toFixed(2));\n\t\t\t\tconst outputBytes = await getDirectorySize(dir);\n\t\t\t\tconst summary = formatSummary(durationSeconds, pages.length, outputBytes);\n\n\t\t\t\tconst entry: BuildLogEntry = {\n\t\t\t\t\ttimestamp: new Date(buildEndTime).toISOString(),\n\t\t\t\t\tdurationSeconds,\n\t\t\t\t\tpageCount: pages.length,\n\t\t\t\t\toutputBytes,\n\t\t\t\t\tastroVersion: astroPackage.version,\n\t\t\t\t\tnodeVersion: process.versions.node,\n\t\t\t\t\tsummary,\n\t\t\t\t};\n\n\t\t\t\ttry {\n\t\t\t\t\tawait appendFile(logFileName, JSON.stringify(entry) + '\\n');\n\t\t\t\t\tlogger.info(`Build time logged: ${summary}`);\n\t\t\t\t} catch (error) {\n\t\t\t\t\tlogger.error(\n\t\t\t\t\t\t`Failed to write build log: ${error instanceof Error ? error.message : 'unknown error'}`,\n\t\t\t\t\t);\n\t\t\t\t}\n\t\t\t},\n\t\t},\n\t};\n}\n"],"mappings":";;;;AAMA,MAAM,gBAAgB,EACpB,OAAO;;;;;;AAMP,aAAa,EAAE,OAAO,CAAC,CAAC,SAAS,EAClC,CAAC,CAAC,CACD,SAAS;AAeX,SAAS,eAAe,cAA8B;CACrD,MAAM,QAAQ,KAAK,MAAM,eAAe,IAAI;CAC5C,MAAM,UAAU,KAAK,MAAO,eAAe,OAAQ,EAAE;CACrD,MAAM,UAAU,KAAK,MAAM,eAAe,EAAE;CAE5C,IAAI,QAAQ,GAAG,OAAO,GAAG,OAAO,KAAK,EAAE,IAAI,OAAO,OAAO,EAAE,IAAI,OAAO,OAAO,EAAE;CAC/E,IAAI,UAAU,GAAG,OAAO,GAAG,OAAO,OAAO,EAAE,IAAI,OAAO,OAAO,EAAE;CAE/D,OAAO,GAAG,OAAO,OAAO,EAAE;AAC3B;AAEA,SAAS,YAAY,OAAuB;CAC3C,MAAM,QAAQ;EAAC;EAAK;EAAM;EAAM;CAAI;CACpC,IAAI,QAAQ;CACZ,IAAI,YAAY;CAEhB,OAAO,SAAS,QAAQ,YAAY,MAAM,SAAS,GAAG;EACrD,SAAS;EACT,aAAa;CACd;CAEA,MAAM,YAAY,SAAS,MAAM,cAAc,IAAI,IAAI;CAEvD,OAAO,GAAG,MAAM,QAAQ,SAAS,EAAE,GAAG,MAAM,cAAc;AAC3D;AAEA,SAAS,cAAc,iBAAyB,WAAmB,aAA6B;CAC/F,OAAO,GAAG,eAAe,eAAe,EAAE,IAAI,OAAO,SAAS,EAAE,UAAU,YAAY,WAAW,EAAE;AACpG;AAEA,eAAe,iBAAiB,KAA2B;CAC1D,MAAM,UAAU,MAAM,QAAQ,KAAK,EAAE,eAAe,KAAK,CAAC;CAC1D,IAAI,QAAQ;CAEZ,KAAK,MAAM,SAAS,SAAS;EAC5B,MAAM,QAAQ,IAAI,IAAI,MAAM,YAAY,IAAI,GAAG,MAAM,KAAK,KAAK,MAAM,MAAM,GAAG;EAE9E,IAAI,MAAM,YAAY,GACrB,SAAS,MAAM,iBAAiB,KAAK;OAC/B,IAAI,MAAM,OAAO,GAAG;GAC1B,MAAM,QAAQ,MAAM,KAAK,KAAK;GAC9B,SAAS,MAAM;EAChB;CACD;CACA,OAAO;AACR;AAEA,SAAwB,YAAY,SAAqC;CAExE,MAAM,cADS,cAAc,MAAM,OACV,CAAC,EAAE,eAAe;CAE3C,IAAI;CAEJ,OAAO;EACN,MAAM;EACN,OAAO;GACN,sBAAsB,EAAE,aAAa;IACpC,iBAAiB,KAAK,IAAI;IAC1B,OAAO,KAAK,2BAA2B,IAAI,KAAK,cAAc,CAAC,CAAC,YAAY,GAAG;GAChF;GACA,oBAAoB,OAAO,EAAE,QAAQ,OAAO,UAAU;IACrD,MAAM,eAAe,KAAK,IAAI;IAC9B,MAAM,kBAAkB,SAAS,eAAe,kBAAkB,IAAA,CAAM,QAAQ,CAAC,CAAC;IAClF,MAAM,cAAc,MAAM,iBAAiB,GAAG;IAC9C,MAAM,UAAU,cAAc,iBAAiB,MAAM,QAAQ,WAAW;IAExE,MAAM,QAAuB;KAC5B,WAAW,IAAI,KAAK,YAAY,CAAC,CAAC,YAAY;KAC9C;KACA,WAAW,MAAM;KACjB;KACA,cAAc,aAAa;KAC3B,aAAa,QAAQ,SAAS;KAC9B;IACD;IAEA,IAAI;KACH,MAAM,WAAW,aAAa,KAAK,UAAU,KAAK,IAAI,IAAI;KAC1D,OAAO,KAAK,sBAAsB,SAAS;IAC5C,SAAS,OAAO;KACf,OAAO,MACN,8BAA8B,iBAAiB,QAAQ,MAAM,UAAU,iBACxE;IACD;GACD;EACD;CACD;AACD"}

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@xsynaptic/astro-build-logger",
+  "version": "0.1.0",
+  "description": "Astro integration that appends build duration, page count, and output size to a JSONL log file",
+  "type": "module",
+  "license": "MIT",
+  "author": "Alexander Synaptic <x@synapticism.com>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/xsynaptic/astro-lab.git",
+    "directory": "packages/astro-build-logger"
+  },
+  "homepage": "https://github.com/xsynaptic/astro-lab/tree/main/packages/astro-build-logger#readme",
+  "bugs": {
+    "url": "https://github.com/xsynaptic/astro-lab/issues"
+  },
+  "keywords": [
+    "astro",
+    "astro-integration",
+    "build",
+    "logging",
+    "metrics"
+  ],
+  "main": "./dist/index.mjs",
+  "types": "./dist/index.d.mts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "import": "./dist/index.mjs"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "dependencies": {
+    "zod": "^4.4.3"
+  },
+  "peerDependencies": {
+    "astro": "^6.0.0"
+  },
+  "devDependencies": {
+    "astro": "^6.4.4"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "dev": "tsdown --watch",
+    "check-types": "tsc --noEmit"
+  }
+}