@garthub/gart-npm 0.1.1

package/src/archive.js

@@ -0,0 +1,271 @@
+const fs = require('node:fs');
+const path = require('node:path');
+const zlib = require('node:zlib');
+const {listFilesRecursively} = require('./hash');
+
+const LOCAL_FILE_HEADER_SIGNATURE = 0x04034b50;
+const CENTRAL_DIRECTORY_HEADER_SIGNATURE = 0x02014b50;
+const END_OF_CENTRAL_DIRECTORY_SIGNATURE = 0x06054b50;
+const COMPRESSION_STORE = 0;
+const COMPRESSION_DEFLATE = 8;
+const VERSION_NEEDED = 20;
+
+function createZipArchive(
+	sourceDirectory,
+	zipPath,
+) {
+	fs.mkdirSync(path.dirname(zipPath), {recursive: true});
+	if (fs.existsSync(zipPath)) {
+		fs.unlinkSync(zipPath);
+	}
+
+	const files = listFilesRecursively(sourceDirectory)
+		.map((absolutePath) => ({
+			absolutePath,
+			relativePath: normalizeArchivePath(path.relative(sourceDirectory, absolutePath)),
+			stats: fs.statSync(absolutePath),
+		}))
+		.sort((
+			left,
+			right,
+		) => left.relativePath.localeCompare(right.relativePath));
+
+	const localParts = [];
+	const centralParts = [];
+	let offset = 0;
+
+	for (const file of files) {
+		const fileName = Buffer.from(file.relativePath, 'utf8');
+		const content = fs.readFileSync(file.absolutePath);
+		const compressed = zlib.deflateRawSync(content);
+		const compressionMethod = compressed.length < content.length ? COMPRESSION_DEFLATE : COMPRESSION_STORE;
+		const payload = compressionMethod === COMPRESSION_DEFLATE ? compressed : content;
+		const crc32 = computeCrc32(content);
+		const timestamp = toDosDateTime(file.stats.mtime);
+
+		const localHeader = Buffer.alloc(30);
+		localHeader.writeUInt32LE(LOCAL_FILE_HEADER_SIGNATURE, 0);
+		localHeader.writeUInt16LE(VERSION_NEEDED, 4);
+		localHeader.writeUInt16LE(0, 6);
+		localHeader.writeUInt16LE(compressionMethod, 8);
+		localHeader.writeUInt16LE(timestamp.time, 10);
+		localHeader.writeUInt16LE(timestamp.date, 12);
+		localHeader.writeUInt32LE(crc32, 14);
+		localHeader.writeUInt32LE(payload.length, 18);
+		localHeader.writeUInt32LE(content.length, 22);
+		localHeader.writeUInt16LE(fileName.length, 26);
+		localHeader.writeUInt16LE(0, 28);
+
+		localParts.push(localHeader, fileName, payload);
+
+		const centralHeader = Buffer.alloc(46);
+		centralHeader.writeUInt32LE(CENTRAL_DIRECTORY_HEADER_SIGNATURE, 0);
+		centralHeader.writeUInt16LE(VERSION_NEEDED, 4);
+		centralHeader.writeUInt16LE(VERSION_NEEDED, 6);
+		centralHeader.writeUInt16LE(0, 8);
+		centralHeader.writeUInt16LE(compressionMethod, 10);
+		centralHeader.writeUInt16LE(timestamp.time, 12);
+		centralHeader.writeUInt16LE(timestamp.date, 14);
+		centralHeader.writeUInt32LE(crc32, 16);
+		centralHeader.writeUInt32LE(payload.length, 20);
+		centralHeader.writeUInt32LE(content.length, 24);
+		centralHeader.writeUInt16LE(fileName.length, 28);
+		centralHeader.writeUInt16LE(0, 30);
+		centralHeader.writeUInt16LE(0, 32);
+		centralHeader.writeUInt16LE(0, 34);
+		centralHeader.writeUInt16LE(0, 36);
+		centralHeader.writeUInt32LE(0, 38);
+		centralHeader.writeUInt32LE(offset, 42);
+		centralParts.push(centralHeader, fileName);
+
+		offset += localHeader.length + fileName.length + payload.length;
+	}
+
+	const centralDirectory = Buffer.concat(centralParts);
+	const endOfCentralDirectory = Buffer.alloc(22);
+	endOfCentralDirectory.writeUInt32LE(END_OF_CENTRAL_DIRECTORY_SIGNATURE, 0);
+	endOfCentralDirectory.writeUInt16LE(0, 4);
+	endOfCentralDirectory.writeUInt16LE(0, 6);
+	endOfCentralDirectory.writeUInt16LE(files.length, 8);
+	endOfCentralDirectory.writeUInt16LE(files.length, 10);
+	endOfCentralDirectory.writeUInt32LE(centralDirectory.length, 12);
+	endOfCentralDirectory.writeUInt32LE(offset, 16);
+	endOfCentralDirectory.writeUInt16LE(0, 20);
+
+	fs.writeFileSync(zipPath, Buffer.concat([...localParts, centralDirectory, endOfCentralDirectory]));
+}
+
+function extractZipArchive(
+	zipPath,
+	destinationPath,
+) {
+	fs.rmSync(destinationPath, {recursive: true, force: true});
+	fs.mkdirSync(destinationPath, {recursive: true});
+
+	const archive = fs.readFileSync(zipPath);
+	const entries = readCentralDirectoryEntries(archive);
+
+	for (const entry of entries) {
+		if (entry.fileName.endsWith('/')) {
+			continue;
+		}
+
+		const destinationFilePath = resolveEntryDestination(destinationPath, entry.fileName);
+		const content = readEntryContent(archive, entry);
+
+		fs.mkdirSync(path.dirname(destinationFilePath), {recursive: true});
+		fs.writeFileSync(destinationFilePath, content);
+	}
+}
+
+function readCentralDirectoryEntries(archive) {
+	const endRecordOffset = findEndOfCentralDirectoryOffset(archive);
+
+	if (endRecordOffset < 0) {
+		throw new Error('Failed to extract ZIP archive: end of central directory record was not found.');
+	}
+
+	const centralDirectoryOffset = archive.readUInt32LE(endRecordOffset + 16);
+	const entryCount = archive.readUInt16LE(endRecordOffset + 10);
+	const entries = [];
+	let offset = centralDirectoryOffset;
+
+	for (let index = 0; index < entryCount; index += 1) {
+		if (archive.readUInt32LE(offset) !== CENTRAL_DIRECTORY_HEADER_SIGNATURE) {
+			throw new Error('Failed to extract ZIP archive: central directory entry is invalid.');
+		}
+
+		const compressionMethod = archive.readUInt16LE(offset + 10);
+		const crc32 = archive.readUInt32LE(offset + 16);
+		const compressedSize = archive.readUInt32LE(offset + 20);
+		const uncompressedSize = archive.readUInt32LE(offset + 24);
+		const fileNameLength = archive.readUInt16LE(offset + 28);
+		const extraFieldLength = archive.readUInt16LE(offset + 30);
+		const fileCommentLength = archive.readUInt16LE(offset + 32);
+		const localHeaderOffset = archive.readUInt32LE(offset + 42);
+		const fileName = archive.slice(offset + 46, offset + 46 + fileNameLength).toString('utf8');
+
+		entries.push({
+			fileName,
+			compressionMethod,
+			crc32,
+			compressedSize,
+			uncompressedSize,
+			localHeaderOffset,
+		});
+
+		offset += 46 + fileNameLength + extraFieldLength + fileCommentLength;
+	}
+
+	return entries;
+}
+
+function readEntryContent(
+	archive,
+	entry,
+) {
+	if (archive.readUInt32LE(entry.localHeaderOffset) !== LOCAL_FILE_HEADER_SIGNATURE) {
+		throw new Error(`Failed to extract ZIP archive: local header is invalid for ${entry.fileName}.`);
+	}
+
+	const fileNameLength = archive.readUInt16LE(entry.localHeaderOffset + 26);
+	const extraFieldLength = archive.readUInt16LE(entry.localHeaderOffset + 28);
+	const dataOffset = entry.localHeaderOffset + 30 + fileNameLength + extraFieldLength;
+	const compressed = archive.slice(dataOffset, dataOffset + entry.compressedSize);
+
+	let content;
+
+	if (entry.compressionMethod === COMPRESSION_STORE) {
+		content = compressed;
+	} else if (entry.compressionMethod === COMPRESSION_DEFLATE) {
+		content = zlib.inflateRawSync(compressed);
+	} else {
+		throw new Error(
+			`Failed to extract ZIP archive: unsupported compression method ${entry.compressionMethod} for ${entry.fileName}.`,
+		);
+	}
+
+	if (content.length !== entry.uncompressedSize) {
+		throw new Error(`Failed to extract ZIP archive: size mismatch for ${entry.fileName}.`);
+	}
+
+	if (computeCrc32(content) !== entry.crc32) {
+		throw new Error(`Failed to extract ZIP archive: CRC mismatch for ${entry.fileName}.`);
+	}
+
+	return content;
+}
+
+function findEndOfCentralDirectoryOffset(archive) {
+	const minimumOffset = Math.max(0, archive.length - 65557);
+
+	for (let offset = archive.length - 22; offset >= minimumOffset; offset -= 1) {
+		if (archive.readUInt32LE(offset) === END_OF_CENTRAL_DIRECTORY_SIGNATURE) {
+			return offset;
+		}
+	}
+
+	return -1;
+}
+
+function resolveEntryDestination(
+	destinationPath,
+	fileName,
+) {
+	const normalizedName = normalizeArchivePath(fileName);
+	const segments = normalizedName.split('/').filter(Boolean);
+
+	if (segments.length === 0) {
+		throw new Error('Failed to extract ZIP archive: encountered an empty file entry.');
+	}
+
+	if (segments.some((segment) => segment === '..')) {
+		throw new Error(`Failed to extract ZIP archive: unsafe path ${fileName}.`);
+	}
+
+	const resolvedPath = path.resolve(destinationPath, ...segments);
+	const relativePath = path.relative(destinationPath, resolvedPath);
+
+	if (relativePath.startsWith('..') || path.isAbsolute(relativePath)) {
+		throw new Error(`Failed to extract ZIP archive: unsafe path ${fileName}.`);
+	}
+
+	return resolvedPath;
+}
+
+function normalizeArchivePath(relativePath) {
+	return String(relativePath).replace(/\\/g, '/');
+}
+
+function toDosDateTime(date) {
+	const value = date instanceof Date ? date : new Date(date);
+	const year = Math.min(Math.max(value.getFullYear(), 1980), 2107);
+
+	return {
+		time: ((value.getHours() & 0x1f) << 11) | ((value.getMinutes() & 0x3f) << 5) | Math.floor(value.getSeconds() / 2),
+		date: (((year - 1980) & 0x7f) << 9) | (((value.getMonth() + 1) & 0x0f) << 5) | (value.getDate() & 0x1f),
+	};
+}
+
+function computeCrc32(buffer) {
+	let crc = 0xffffffff;
+
+	for (const byte of buffer) {
+		crc ^= byte;
+
+		for (let index = 0; index < 8; index += 1) {
+			const mask = -(crc & 1);
+			crc = (crc >>> 1) ^ (0xedb88320 & mask);
+		}
+	}
+
+	return (crc ^ 0xffffffff) >>> 0;
+}
+
+module.exports = {
+	createZipArchive,
+	extractZipArchive,
+	computeCrc32,
+	readCentralDirectoryEntries,
+	resolveEntryDestination,
+};

package/src/build-resources.js

@@ -0,0 +1,150 @@
+const fs = require('node:fs');
+const path = require('node:path');
+const {computeFileSha256, listFilesRecursively} = require('./hash');
+const {createZipArchive} = require('./archive');
+
+function buildSkillsArchive(
+	config,
+	options = {},
+) {
+	const archiver = options.archiver || createZipArchive;
+	const projectInfo = readProjectInfo(config.cwd);
+	const existingSourceDirectories = collectExistingSourceDirectories(config);
+	const collectedFiles = collectSourceFiles(existingSourceDirectories);
+	validateDuplicateRelativePaths(collectedFiles);
+
+	const stagingDirectory = path.join(config.buildDir, 'build', 'staging');
+	const distDirectory = path.join(config.buildDir, 'dist');
+	const archivePath = path.join(distDirectory, `${projectInfo.artifactId}-skills.zip`);
+	const manifestPath = path.join(config.buildDir, 'build.json');
+
+	fs.rmSync(stagingDirectory, {recursive: true, force: true});
+	fs.mkdirSync(stagingDirectory, {recursive: true});
+	fs.mkdirSync(distDirectory, {recursive: true});
+
+	stageCollectedFiles(stagingDirectory, collectedFiles);
+	archiver(stagingDirectory, archivePath);
+	const archiveSha256 = computeFileSha256(archivePath);
+
+	const manifest = {
+		version: 1,
+		generatedAt: new Date().toISOString(),
+		projectName: projectInfo.packageName,
+		artifactId: projectInfo.artifactId,
+		archivePath,
+		archiveSha256,
+		stagingDirectory,
+		sourceDirectories: existingSourceDirectories.map((sourceDirectory) => ({
+			configuredPath: sourceDirectory.configuredPath,
+			absolutePath: sourceDirectory.absolutePath,
+		})),
+		files: collectedFiles.map((file) => ({
+			relativePath: file.relativePath,
+			sourceDirectory: file.sourceDirectory,
+			sha256: computeFileSha256(file.absolutePath),
+		})),
+	};
+
+	fs.writeFileSync(manifestPath, JSON.stringify(manifest, null, 2));
+
+	return {
+		archivePath,
+		archiveSha256,
+		manifestPath,
+		manifest,
+	};
+}
+
+function collectExistingSourceDirectories(config) {
+	return config.srcDirs
+		.map((configuredPath) => ({
+			configuredPath,
+			absolutePath: path.resolve(config.cwd, configuredPath),
+		}))
+		.filter((entry) => fs.existsSync(entry.absolutePath) && fs.statSync(entry.absolutePath).isDirectory());
+}
+
+function collectSourceFiles(sourceDirectories) {
+	const collectedFiles = [];
+
+	for (const sourceDirectory of sourceDirectories) {
+		for (const absolutePath of listFilesRecursively(sourceDirectory.absolutePath)) {
+			collectedFiles.push({
+				absolutePath,
+				relativePath: normalizeRelativePath(path.relative(sourceDirectory.absolutePath, absolutePath)),
+				sourceDirectory: sourceDirectory.configuredPath,
+			});
+		}
+	}
+
+	return collectedFiles;
+}
+
+function validateDuplicateRelativePaths(collectedFiles) {
+	const seen = new Map();
+
+	for (const file of collectedFiles) {
+		if (!seen.has(file.relativePath)) {
+			seen.set(file.relativePath, file);
+			continue;
+		}
+
+		const existing = seen.get(file.relativePath);
+		throw new Error(
+			`Duplicate build resource path detected: ${file.relativePath} from ${existing.sourceDirectory} and ${file.sourceDirectory}.`,
+		);
+	}
+}
+
+function stageCollectedFiles(
+	stagingDirectory,
+	collectedFiles,
+) {
+	for (const file of collectedFiles) {
+		const targetPath = path.join(stagingDirectory, ...file.relativePath.split('/'));
+		fs.mkdirSync(path.dirname(targetPath), {recursive: true});
+		fs.copyFileSync(file.absolutePath, targetPath);
+	}
+}
+
+function readProjectInfo(cwd) {
+	const packageJsonPath = path.join(cwd, 'package.json');
+
+	if (!fs.existsSync(packageJsonPath)) {
+		const fallbackName = path.basename(cwd);
+		return {
+			packageName: fallbackName,
+			artifactId: fallbackName,
+			version: null,
+		};
+	}
+
+	const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, 'utf8'));
+	const packageName = packageJson.name || path.basename(cwd);
+	return {
+		packageName,
+		artifactId: toArtifactId(packageName),
+		version: packageJson.version || null,
+	};
+}
+
+function toArtifactId(packageName) {
+	if (!String(packageName).includes('/')) {
+		return String(packageName);
+	}
+
+	return String(packageName).split('/').pop();
+}
+
+function normalizeRelativePath(relativePath) {
+	return relativePath.split(path.sep).join('/');
+}
+
+module.exports = {
+	buildSkillsArchive,
+	collectExistingSourceDirectories,
+	collectSourceFiles,
+	validateDuplicateRelativePaths,
+	readProjectInfo,
+	toArtifactId,
+};

package/src/cli.js

@@ -0,0 +1,49 @@
+#!/usr/bin/env node
+const {loadConfig} = require('./config');
+const {runResolve} = require('./commands/resolve');
+const {runBuild} = require('./commands/build');
+const {runClean} = require('./commands/clean');
+const {runPublish} = require('./commands/publish');
+const {resolveExecutionCwd} = require('./runtime');
+
+const COMMANDS = {
+	resolve: runResolve,
+	build: runBuild,
+	clean: runClean,
+	publish: runPublish,
+};
+
+async function main() {
+	const [, , commandName, ...args] = process.argv;
+
+	if (!commandName || commandName === '--help' || commandName === '-h') {
+		printHelp();
+		return;
+	}
+
+	const command = COMMANDS[commandName];
+
+	if (!command) {
+		throw new Error(`Unknown command: ${commandName}`);
+	}
+
+	const context = {
+		commandName,
+		args,
+		cwd: resolveExecutionCwd(commandName, args, process.env, process.cwd()),
+	};
+
+	context.config = loadConfig(context.cwd);
+
+	await command(context);
+}
+
+function printHelp() {
+	console.log('gart <resolve|build|clean|publish>');
+}
+
+main().catch((error) => {
+	const message = error && error.message ? error.message : String(error);
+	console.error(`[gart] ${message}`);
+	process.exitCode = 1;
+});

package/src/commands/build.js

@@ -0,0 +1,19 @@
+const fs = require('node:fs');
+const {buildSkillsArchive, collectExistingSourceDirectories} = require('../build-resources');
+
+async function runBuild(context) {
+	const {config, archiver} = context;
+	fs.mkdirSync(config.buildDir, {recursive: true});
+	const existingSourceDirectories = collectExistingSourceDirectories(config);
+	const build = buildSkillsArchive(config, {archiver});
+
+	console.log('[gart] Build completed.');
+	console.log(`[gart] Configured source directories: ${config.srcDirs.join(', ') || '(none)'}.`);
+	console.log(`[gart] Existing source directories: ${existingSourceDirectories.map((entry) => entry.configuredPath).join(', ') || '(none)'}.`);
+	console.log(`[gart] Archive written to ${build.archivePath}.`);
+	console.log(`[gart] Build manifest written to ${build.manifestPath}.`);
+}
+
+module.exports = {
+	runBuild,
+};

package/src/commands/clean.js

@@ -0,0 +1,147 @@
+const fs = require('node:fs');
+const path = require('node:path');
+const {computeFileSha256} = require('../hash');
+const {cleanupManagedSkills, readManagedIndex} = require('../managed-skills');
+
+async function runClean(context) {
+	const {config} = context;
+	const indexPath = path.join(config.managedSkillsDir, 'gart.json');
+
+	if (!fs.existsSync(indexPath)) {
+		console.log('[gart] Nothing to clean. Managed index file was not found.');
+		return;
+	}
+
+	const previousIndex = readManagedIndex(config.managedSkillsDir);
+
+	try {
+		const cleaned = cleanupManagedSkills(config);
+		const cacheCleanup = cleanupResolvedArtifactCache(previousIndex.resolvedArtifacts || []);
+		const nextIndex = {
+			...previousIndex,
+			version: previousIndex.version || 1,
+			generatedAt: new Date().toISOString(),
+			status: 'skillsCleaned',
+			managedDir: config.managedSkillsDir,
+			managedFiles: cleaned.managedFiles,
+			removedFiles: cleaned.removedFiles,
+			removedCacheFiles: cacheCleanup.removedCacheFiles,
+			skippedCacheFiles: cacheCleanup.skippedCacheFiles,
+			writtenFiles: [],
+			resolvedArtifacts: [],
+			unresolved: [],
+			note: 'Managed skill cleanup completed successfully.',
+		};
+
+		fs.writeFileSync(indexPath, JSON.stringify(nextIndex, null, 2));
+
+		console.log(`[gart] Removed ${cleaned.removedFiles.length} managed skill file(s).`);
+		console.log(`[gart] Removed ${cacheCleanup.removedCacheFiles.length} cached artifact file(s).`);
+		if (cacheCleanup.skippedCacheFiles.length > 0) {
+			console.log(`[gart] Skipped ${cacheCleanup.skippedCacheFiles.length} cached artifact file(s) because their checksums no longer match the managed index.`);
+		}
+		console.log(`[gart] Clean index written to ${indexPath}.`);
+	} catch (error) {
+		const failedIndex = {
+			...previousIndex,
+			version: previousIndex.version || 1,
+			generatedAt: new Date().toISOString(),
+			status: 'cleanFailed',
+			managedDir: config.managedSkillsDir,
+			cleanError: error.message,
+			note: 'Managed skill cleanup failed.',
+		};
+
+		fs.writeFileSync(indexPath, JSON.stringify(failedIndex, null, 2));
+		throw error;
+	}
+}
+
+function cleanupResolvedArtifactCache(resolvedArtifacts) {
+	const removedCacheFiles = [];
+	const skippedCacheFiles = [];
+	const candidateEntries = collectCacheCleanupEntries(resolvedArtifacts);
+
+	for (const entry of candidateEntries) {
+		const filePath = entry.path;
+		if (!fs.existsSync(filePath)) {
+			continue;
+		}
+
+		if (entry.sha256) {
+			const actualSha256 = computeFileSha256(filePath);
+			if (actualSha256 !== entry.sha256) {
+				skippedCacheFiles.push({
+					path: filePath,
+					kind: entry.kind,
+					expectedSha256: entry.sha256,
+					actualSha256,
+					reason: 'sha256Mismatch',
+				});
+				continue;
+			}
+		}
+
+		fs.unlinkSync(filePath);
+		removeEmptyParentDirectories(path.dirname(filePath));
+		removedCacheFiles.push(filePath);
+	}
+
+	return {
+		removedCacheFiles,
+		skippedCacheFiles,
+	};
+}
+
+function collectCacheCleanupEntries(resolvedArtifacts) {
+	const candidateEntries = [];
+	const seen = new Set();
+
+	for (const artifact of resolvedArtifacts) {
+		for (const entry of [
+			{
+				path: artifact.artifactPath,
+				sha256: artifact.archiveSha256 || null,
+				kind: 'artifact',
+			},
+			{
+				path: artifact.pomPath,
+				sha256: artifact.pomSha256 || null,
+				kind: 'pom',
+			},
+		]) {
+			if (!entry.path || typeof entry.path !== 'string') {
+				continue;
+			}
+
+			const key = `${entry.kind}:${entry.path}`;
+			if (seen.has(key)) {
+				continue;
+			}
+
+			seen.add(key);
+			candidateEntries.push(entry);
+		}
+	}
+
+	return candidateEntries;
+}
+
+function removeEmptyParentDirectories(startDir) {
+	let currentDir = startDir;
+
+	while (fs.existsSync(currentDir) && fs.statSync(currentDir).isDirectory()) {
+		if (fs.readdirSync(currentDir).length > 0) {
+			return;
+		}
+
+		fs.rmdirSync(currentDir);
+		currentDir = path.dirname(currentDir);
+	}
+}
+
+module.exports = {
+	runClean,
+	cleanupResolvedArtifactCache,
+	collectCacheCleanupEntries,
+};

package/src/commands/publish.js

@@ -0,0 +1,15 @@
+const {publishSkillsPackage} = require('../publish-artifacts');
+
+async function runPublish(context) {
+	const {config, archiver} = context;
+	const publication = await publishSkillsPackage(config, {archiver});
+
+	console.log(`[gart] Published ${publication.coordinates.coordinates}.`);
+	console.log(`[gart] Archive published to ${publication.publishedArtifact.location}.`);
+	console.log(`[gart] POM published to ${publication.publishedPom.location}.`);
+	console.log(`[gart] Publish manifest written to ${publication.publishManifestPath}.`);
+}
+
+module.exports = {
+	runPublish,
+};