@garthub/gart-npm 0.1.1

package/src/managed-skills.js

@@ -0,0 +1,365 @@
+const fs = require('node:fs');
+const path = require('node:path');
+const {extractZipArchive} = require('./archive');
+const {computeFileSha256, maybeComputeFileSha256, listFilesRecursively} = require('./hash');
+
+const MANAGED_GITIGNORE_START = '# gart managed start';
+const MANAGED_GITIGNORE_END = '# gart managed end';
+
+async function synchronizeManagedSkills(
+	config,
+	resolvedArtifacts,
+	options = {},
+) {
+	const extractor = options.extractor || extractArtifactArchive;
+	const previousIndex = readManagedIndex(config.managedSkillsDir);
+	fs.mkdirSync(config.buildDir, {recursive: true});
+	ensureManagedSkillsDirectory(config.managedSkillsDir);
+	const stagingRoot = fs.mkdtempSync(path.join(config.buildDir, 'reconcile-'));
+
+	try {
+		const stagedArtifacts = [];
+		const desiredFiles = new Map();
+
+		for (const artifact of resolvedArtifacts) {
+			const stagedArtifact = await stageArtifactFiles(artifact, stagingRoot, extractor);
+			stagedArtifacts.push(stagedArtifact);
+
+			for (const file of stagedArtifact.files) {
+				if (desiredFiles.has(file.relativePath)) {
+					const existing = desiredFiles.get(file.relativePath);
+					throw new Error(
+						`Duplicate managed skill path detected: ${file.relativePath} from ${existing.coordinates} and ${file.coordinates}.`,
+					);
+				}
+
+				desiredFiles.set(file.relativePath, file);
+			}
+		}
+
+		validateManagedSkillChanges(config, desiredFiles, previousIndex.managedFiles || []);
+		const removedFiles = removeStaleManagedFiles(config, desiredFiles, previousIndex.managedFiles || []);
+		const writtenFiles = writeManagedFiles(config, desiredFiles);
+		const managedFiles = buildManagedFilesSnapshot(config, desiredFiles);
+		const gitignoreEntries = updateManagedGitignore(config.managedSkillsDir, managedFiles);
+
+		return {
+			resolvedArtifacts: stagedArtifacts.map((artifact) => ({
+				...artifact,
+				files: artifact.files.map((file) => ({
+					relativePath: file.relativePath,
+					sha256: file.sha256,
+				})),
+			})),
+			managedFiles,
+			gitignoreEntries,
+			removedFiles,
+			writtenFiles,
+		};
+	} finally {
+		fs.rmSync(stagingRoot, {recursive: true, force: true});
+	}
+}
+
+function cleanupManagedSkills(config) {
+	const previousIndex = readManagedIndex(config.managedSkillsDir);
+	const desiredFiles = new Map();
+
+	validateManagedSkillChanges(config, desiredFiles, previousIndex.managedFiles || []);
+	const removedFiles = removeStaleManagedFiles(config, desiredFiles, previousIndex.managedFiles || []);
+	const managedFiles = buildManagedFilesSnapshot(config, desiredFiles);
+	const gitignoreEntries = updateManagedGitignore(config.managedSkillsDir, managedFiles);
+
+	return {
+		managedFiles,
+		gitignoreEntries,
+		removedFiles,
+		previousManagedFiles: previousIndex.managedFiles || [],
+	};
+}
+
+async function stageArtifactFiles(
+	artifact,
+	stagingRoot,
+	extractor,
+) {
+	const artifactDir = path.join(stagingRoot, sanitizeArtifactKey(artifact.dependency.coordinates));
+	await extractor(artifact, artifactDir);
+
+	const files = listFilesRecursively(artifactDir).map((filePath) => ({
+		relativePath: normalizeRelativePath(path.relative(artifactDir, filePath)),
+		absolutePath: filePath,
+		sha256: computeFileSha256(filePath),
+		coordinates: artifact.dependency.coordinates,
+	}));
+
+	return {
+		...artifact,
+		archiveSha256: computeFileSha256(artifact.artifactPath),
+		pomSha256: maybeComputeFileSha256(artifact.pomPath),
+		files,
+	};
+}
+
+async function extractArtifactArchive(
+	artifact,
+	destinationPath,
+) {
+	extractZipArchive(artifact.artifactPath, destinationPath);
+}
+
+function readManagedIndex(managedSkillsDir) {
+	ensureManagedSkillsDirectory(managedSkillsDir);
+	const indexPath = path.join(managedSkillsDir, 'gart.json');
+
+	if (!fs.existsSync(indexPath)) {
+		return {managedFiles: []};
+	}
+
+	return JSON.parse(fs.readFileSync(indexPath, 'utf8'));
+}
+
+function validateManagedSkillChanges(
+	config,
+	desiredFiles,
+	previousManagedFiles,
+) {
+	const previousManagedMap = new Map(previousManagedFiles.map((file) => [file.relativePath, file]));
+
+	for (const [relativePath] of desiredFiles) {
+		const targetPath = resolveManagedTargetPath(config, relativePath);
+
+		if (!fs.existsSync(targetPath)) {
+			continue;
+		}
+
+		const currentSha = computeFileSha256(targetPath);
+		const previousManagedFile = previousManagedMap.get(relativePath);
+
+		if (!previousManagedFile) {
+			throw new Error(
+				`Managed skill path conflicts with a user-authored file: ${relativePath}.`,
+			);
+		}
+
+		if (currentSha !== previousManagedFile.sha256) {
+			throw new Error(
+				`Managed skill file was modified manually and cannot be overwritten safely: ${relativePath}.`,
+			);
+		}
+	}
+
+	for (const previousManagedFile of previousManagedFiles) {
+		if (desiredFiles.has(previousManagedFile.relativePath)) {
+			continue;
+		}
+
+		const targetPath = resolveManagedTargetPath(config, previousManagedFile.relativePath);
+
+		if (!fs.existsSync(targetPath)) {
+			continue;
+		}
+
+		const currentSha = computeFileSha256(targetPath);
+		if (currentSha !== previousManagedFile.sha256) {
+			throw new Error(
+				`Managed skill file was modified manually and cannot be removed safely: ${previousManagedFile.relativePath}.`,
+			);
+		}
+	}
+}
+
+function removeStaleManagedFiles(
+	config,
+	desiredFiles,
+	previousManagedFiles,
+) {
+	const removedFiles = [];
+
+	for (const previousManagedFile of previousManagedFiles) {
+		if (desiredFiles.has(previousManagedFile.relativePath)) {
+			continue;
+		}
+
+		const targetPath = resolveManagedTargetPath(config, previousManagedFile.relativePath);
+		if (!fs.existsSync(targetPath)) {
+			continue;
+		}
+
+		fs.unlinkSync(targetPath);
+		removeEmptyParentDirectories(path.dirname(targetPath), config.managedSkillsDir);
+		removedFiles.push(previousManagedFile.relativePath);
+	}
+
+	return removedFiles;
+}
+
+function writeManagedFiles(
+	config,
+	desiredFiles,
+) {
+	const writtenFiles = [];
+
+	for (const file of desiredFiles.values()) {
+		const targetPath = resolveManagedTargetPath(config, file.relativePath);
+		fs.mkdirSync(path.dirname(targetPath), {recursive: true});
+		fs.copyFileSync(file.absolutePath, targetPath);
+		writtenFiles.push(file.relativePath);
+	}
+
+	return writtenFiles;
+}
+
+function buildManagedFilesSnapshot(
+	config,
+	desiredFiles,
+) {
+	return [...desiredFiles.values()].map((file) => ({
+		relativePath: file.relativePath,
+		sha256: computeFileSha256(resolveManagedTargetPath(config, file.relativePath)),
+		coordinates: file.coordinates,
+	}));
+}
+
+function updateManagedGitignore(
+	managedSkillsDir,
+	managedFiles,
+) {
+	const gitignorePath = path.join(managedSkillsDir, '.gitignore');
+	const existingContent = fs.existsSync(gitignorePath)
+		? fs.readFileSync(gitignorePath, 'utf8')
+		: '';
+	const preservedContent = stripManagedGitignoreBlock(existingContent);
+	const managedEntries = buildManagedGitignoreEntries(managedFiles);
+	const nextContent = buildGitignoreContent(preservedContent, managedEntries);
+
+	if (nextContent === null) {
+		if (fs.existsSync(gitignorePath)) {
+			fs.unlinkSync(gitignorePath);
+		}
+		return [];
+	}
+
+	fs.writeFileSync(gitignorePath, nextContent);
+	return managedEntries;
+}
+
+function buildManagedGitignoreEntries(managedFiles) {
+	const entries = new Set();
+
+	for (const file of managedFiles) {
+		const segments = file.relativePath.split('/').filter(Boolean);
+		if (segments.length === 0) {
+			continue;
+		}
+
+		const firstSegment = segments[0];
+		if (firstSegment === '.gitignore' || firstSegment === 'gart.json') {
+			continue;
+		}
+
+		if (segments.length === 1) {
+			entries.add(`/${firstSegment}`);
+			continue;
+		}
+
+		entries.add(`/${firstSegment}/`);
+	}
+
+	return [...entries].sort();
+}
+
+function buildGitignoreContent(
+	existingContent,
+	managedEntries,
+) {
+	const normalizedExisting = normalizeGitignoreContent(existingContent);
+	const trimmedExisting = normalizedExisting.trim();
+
+	if (managedEntries.length === 0) {
+		if (trimmedExisting.length === 0) {
+			return null;
+		}
+
+		return `${trimmedExisting}\n`;
+	}
+
+	const managedBlock = [
+		MANAGED_GITIGNORE_START,
+		...managedEntries,
+		MANAGED_GITIGNORE_END,
+	].join('\n');
+
+	if (trimmedExisting.length === 0) {
+		return `${managedBlock}\n`;
+	}
+
+	return `${trimmedExisting}\n\n${managedBlock}\n`;
+}
+
+function stripManagedGitignoreBlock(content) {
+	const normalized = normalizeGitignoreContent(content);
+	const blockPattern = new RegExp(
+		`${escapeForRegex(MANAGED_GITIGNORE_START)}\\n[\\s\\S]*?${escapeForRegex(MANAGED_GITIGNORE_END)}\\n?`,
+		'g',
+	);
+
+	return normalized.replace(blockPattern, '').replace(/\n{3,}/g, '\n\n').replace(/^\n+|\n+$/g, '');
+}
+
+function normalizeGitignoreContent(content) {
+	return String(content || '').replace(/\r\n/g, '\n');
+}
+
+function escapeForRegex(value) {
+	return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+function resolveManagedTargetPath(
+	config,
+	relativePath,
+) {
+	return path.join(config.managedSkillsDir, ...relativePath.split('/'));
+}
+
+function normalizeRelativePath(relativePath) {
+	return relativePath.split(path.sep).join('/');
+}
+
+function sanitizeArtifactKey(value) {
+	return value.replace(/[^a-zA-Z0-9._-]+/g, '_');
+}
+
+function ensureManagedSkillsDirectory(managedSkillsDir) {
+	fs.mkdirSync(managedSkillsDir, {recursive: true});
+}
+
+function removeEmptyParentDirectories(
+	startDir,
+	boundaryDir,
+) {
+	let currentDir = startDir;
+	const normalizedBoundary = path.resolve(boundaryDir);
+
+	while (path.resolve(currentDir).startsWith(normalizedBoundary) && path.resolve(currentDir) !== normalizedBoundary) {
+		if (fs.readdirSync(currentDir).length > 0) {
+			return;
+		}
+
+		fs.rmdirSync(currentDir);
+		currentDir = path.dirname(currentDir);
+	}
+}
+
+module.exports = {
+	cleanupManagedSkills,
+	synchronizeManagedSkills,
+	readManagedIndex,
+	validateManagedSkillChanges,
+	removeStaleManagedFiles,
+	updateManagedGitignore,
+	buildManagedGitignoreEntries,
+	stripManagedGitignoreBlock,
+	MANAGED_GITIGNORE_START,
+	MANAGED_GITIGNORE_END,
+};

package/src/maven.js

@@ -0,0 +1,155 @@
+const os = require('node:os');
+const path = require('node:path');
+
+const DEFAULT_CLASSIFIER = 'skills';
+const DEFAULT_EXTENSION = 'zip';
+const DEFAULT_POM_EXTENSION = 'pom';
+
+function defaultMavenLocalRepository() {
+	return path.join(os.homedir(), '.m2', 'repository');
+}
+
+function parseSkillCoordinates(coordinates) {
+	const parts = String(coordinates).split(':');
+
+	if (parts.length !== 3 || parts.some((part) => !part)) {
+		throw new Error(`Invalid skill coordinates: ${coordinates}`);
+	}
+
+	return {
+		coordinates,
+		groupId: parts[0],
+		artifactId: parts[1],
+		version: parts[2],
+		classifier: DEFAULT_CLASSIFIER,
+		extension: DEFAULT_EXTENSION,
+	};
+}
+
+function buildMavenRelativeArtifactPath(coordinates) {
+	const parsed = typeof coordinates === 'string' ? parseSkillCoordinates(coordinates) : coordinates;
+	const groupPath = parsed.groupId.split('.').join('/');
+	const fileName = `${parsed.artifactId}-${parsed.version}-${parsed.classifier}.${parsed.extension}`;
+
+	return `${groupPath}/${parsed.artifactId}/${parsed.version}/${fileName}`;
+}
+
+function buildMavenRelativePomPath(coordinates) {
+	const parsed = typeof coordinates === 'string' ? parseSkillCoordinates(coordinates) : coordinates;
+	const groupPath = parsed.groupId.split('.').join('/');
+	const fileName = `${parsed.artifactId}-${parsed.version}.${DEFAULT_POM_EXTENSION}`;
+
+	return `${groupPath}/${parsed.artifactId}/${parsed.version}/${fileName}`;
+}
+
+function buildMavenArtifactUrl(
+	repository,
+	coordinates,
+) {
+	const baseUrl = repository.url.replace(/\/+$/, '');
+	return `${baseUrl}/${buildMavenRelativeArtifactPath(coordinates)}`;
+}
+
+function buildMavenPomUrl(
+	repository,
+	coordinates,
+) {
+	const baseUrl = repository.url.replace(/\/+$/, '');
+	return `${baseUrl}/${buildMavenRelativePomPath(coordinates)}`;
+}
+
+function normalizeRepository(
+	repository,
+	cwd,
+	id,
+) {
+	if (typeof repository === 'string') {
+		if (repository === 'mavenLocal') {
+			return {
+				id,
+				type: 'mavenLocal',
+				rootDir: defaultMavenLocalRepository(),
+			};
+		}
+
+		return {
+			id,
+			type: 'maven',
+			url: repository,
+		};
+	}
+
+	if (!repository || typeof repository !== 'object') {
+		throw new Error('Repository entries must be strings or objects');
+	}
+
+	if (repository.type === 'mavenLocal') {
+		return {
+			id,
+			type: 'mavenLocal',
+			rootDir: repository.rootDir
+				? path.resolve(cwd, repository.rootDir)
+				: defaultMavenLocalRepository(),
+		};
+	}
+
+	if (repository.type === 'maven') {
+		if (!repository.url || typeof repository.url !== 'string') {
+			throw new Error('Maven repositories must define a string url');
+		}
+
+		return {
+			id,
+			type: 'maven',
+			url: repository.url,
+			credentials: repository.credentials || null,
+		};
+	}
+
+	if (repository.type === 'npm') {
+		if (!repository.url || typeof repository.url !== 'string') {
+			throw new Error('Npm repositories must define a string url');
+		}
+
+		return {
+			id,
+			type: 'npm',
+			url: repository.url,
+			authTokenEnv: repository.authTokenEnv || null,
+		};
+	}
+
+	throw new Error(`Unsupported repository type: ${repository.type}`);
+}
+
+function buildRepositoryHeaders(repository) {
+	if (!repository.credentials) {
+		return {};
+	}
+
+	const username = repository.credentials.username || process.env[repository.credentials.usernameEnv || ''];
+	const password = repository.credentials.password || process.env[repository.credentials.passwordEnv || ''];
+
+	if (!username && !password) {
+		return {};
+	}
+
+	const token = Buffer.from(`${username || ''}:${password || ''}`).toString('base64');
+	return {
+		Authorization: `Basic ${token}`,
+	};
+}
+
+module.exports = {
+	parseSkillCoordinates,
+	buildMavenRelativeArtifactPath,
+	buildMavenRelativePomPath,
+	buildMavenArtifactUrl,
+	buildMavenPomUrl,
+	normalizeRepository,
+	buildRepositoryHeaders,
+	defaultMavenLocalRepository,
+	DEFAULT_CLASSIFIER,
+	DEFAULT_EXTENSION,
+	DEFAULT_POM_EXTENSION,
+};

package/src/pom.js

@@ -0,0 +1,64 @@
+function parseTransitiveSkillDependenciesFromPom(pomContent) {
+	const dependencies = [];
+	const dependencyBlocks = String(pomContent).match(/<dependency\b[\s\S]*?<\/dependency>/g) || [];
+
+	for (const block of dependencyBlocks) {
+		const groupId = readPomTag(block, 'groupId');
+		const artifactId = readPomTag(block, 'artifactId');
+		const version = readPomTag(block, 'version');
+		const classifier = readPomTag(block, 'classifier');
+		const type = readPomTag(block, 'type');
+		const optional = readPomTag(block, 'optional');
+		const scope = readPomTag(block, 'scope');
+
+		if (optional === 'true') {
+			continue;
+		}
+
+		if (classifier !== 'skills' || type !== 'zip') {
+			continue;
+		}
+
+		if (!groupId || !artifactId || !version) {
+			throw new Error('Encountered a transitive skill dependency in POM without groupId, artifactId, or version.');
+		}
+
+		dependencies.push({
+			coordinates: `${groupId}:${artifactId}:${version}`,
+			groupId,
+			artifactId,
+			version,
+			classifier,
+			type,
+			scope: scope || null,
+		});
+	}
+
+	return dependencies;
+}
+
+function readPomTag(
+	xml,
+	tagName,
+) {
+	const match = String(xml).match(new RegExp(`<${tagName}>\\s*([^<]+?)\\s*</${tagName}>`));
+
+	if (!match) {
+		return null;
+	}
+
+	return decodeXmlEntities(match[1].trim());
+}
+
+function decodeXmlEntities(value) {
+	return value
+		.replace(/&lt;/g, '<')
+		.replace(/&gt;/g, '>')
+		.replace(/&amp;/g, '&')
+		.replace(/&quot;/g, '"')
+		.replace(/&apos;/g, '\'');
+}
+
+module.exports = {
+	parseTransitiveSkillDependenciesFromPom,
+};