gitorial-cli 1.1.0 → 2.0.0

package/src/commands/build-mdbook.js

@@ -0,0 +1,321 @@
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { createLogger } = require('../lib/logger');
+const { createGit, ensureBranchExists, checkoutBranch } = require('../lib/git');
+const {
+	copyDir,
+	ensureDir,
+	readFirstHeading,
+	removeAllExcept,
+} = require('../lib/fs');
+const { stepMarkdown } = require('../lib/mdbook-templates');
+const { monacoCss, monacoSetup, monacoEmbed } = require('../lib/monaco-assets');
+
+const EMPTY_TREE = '4b825dc642cb6eb9a060e54bf8d69288fbee4904';
+
+function classifyCommit(message) {
+	const lower = message.toLowerCase();
+	if (lower.startsWith('starting-template')) {
+		return 'starting-template';
+	}
+	if (lower.startsWith('readme:')) {
+		return 'readme';
+	}
+	if (lower.startsWith('section:')) {
+		return 'section';
+	}
+	if (lower.startsWith('action:')) {
+		return 'action';
+	}
+	if (lower.startsWith('template:')) {
+		return 'template';
+	}
+	if (lower.startsWith('solution:')) {
+		return 'solution';
+	}
+	return 'unknown';
+}
+
+function parseFileStatuses(diffOutput) {
+	return diffOutput
+		.split('\n')
+		.map((line) => line.trim())
+		.filter(Boolean)
+		.map((line) => {
+			const [status, file] = line.split('\t');
+			return { status, file };
+		});
+}
+
+function filterFileEntries(entries, rootFolder) {
+	const result = [];
+	for (const entry of entries) {
+		if (!entry.file) {
+			continue;
+		}
+		if (entry.status === 'D') {
+			continue;
+		}
+		if (entry.file.startsWith('.')) {
+			continue;
+		}
+		const filename = path.parse(entry.file).base;
+		if (filename === 'README.md') {
+			continue;
+		}
+		if (filename.startsWith('.')) {
+			continue;
+		}
+		if (filename === 'Cargo.lock') {
+			continue;
+		}
+
+		result.push({
+			label: entry.file,
+			path: `./${rootFolder}/${entry.file}`,
+			status: entry.status,
+		});
+	}
+	return result;
+}
+
+function getStepTitle(folder) {
+	const markdownPath = path.join(folder, 'README.md');
+	const title = readFirstHeading(markdownPath);
+	if (title) {
+		return title;
+	}
+	throw new Error(`Missing step title in ${markdownPath}`);
+}
+
+function copySnapshot(sourceDir, targetDir) {
+	const filter = (sourcePath, isDirectory) => {
+		const baseName = path.basename(sourcePath);
+		if (baseName === '.git') {
+			return false;
+		}
+		if (!isDirectory && baseName.endsWith('.diff')) {
+			return false;
+		}
+		return true;
+	};
+	copyDir(sourceDir, targetDir, filter);
+}
+
+async function checkoutOrCreateBranch(git, outputBranch, baseBranch) {
+	const branches = await git.branchLocal();
+	if (branches.all.includes(outputBranch)) {
+		await checkoutBranch(git, outputBranch);
+		return;
+	}
+	await checkoutBranch(git, baseBranch);
+	await git.checkoutLocalBranch(outputBranch);
+}
+
+async function buildMdbook(options) {
+	const logger = createLogger(options);
+	const repoPath = path.resolve(options.repo);
+	const inputBranch = options.input;
+	const outputBranch = options.output;
+	const sourceDirName = options.source;
+
+	const git = createGit(repoPath);
+	await ensureBranchExists(git, inputBranch);
+
+	const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'gitorial-mdbook-source-'));
+	const sourceGit = createGit(tempDir);
+
+	try {
+		logger.info(`Cloning ${inputBranch} into temporary workspace...`);
+		await sourceGit.clone(repoPath, tempDir, ['--branch', inputBranch]);
+
+		const logs = await sourceGit.log();
+		const commits = logs.all.reverse();
+
+		await checkoutOrCreateBranch(git, outputBranch, inputBranch);
+		if (options.force) {
+			logger.warn('--force is ignored for build-mdbook to preserve branch history.');
+		}
+
+		const outputRoot = path.join(repoPath, sourceDirName);
+		ensureDir(outputRoot);
+		removeAllExcept(outputRoot, []);
+		const assetRoot = path.join(outputRoot, '_gitorial');
+		ensureDir(assetRoot);
+		fs.writeFileSync(path.join(assetRoot, 'monaco-setup.js'), monacoSetup);
+		fs.writeFileSync(path.join(assetRoot, 'monaco-setup.css'), monacoCss);
+
+		let stepCounter = 0;
+		let pendingTemplate = null;
+		let stepEntries = [];
+
+		let previousCommit = EMPTY_TREE;
+
+		for (const commit of commits) {
+			const commitHash = commit.hash;
+			const commitMessage = commit.message;
+			const commitType = classifyCommit(commitMessage);
+
+			if (commitType === 'starting-template') {
+				previousCommit = commitHash;
+				continue;
+			}
+
+			if (commitType === 'unknown') {
+				throw new Error(`Unknown Gitorial commit type: ${commitMessage}`);
+			}
+
+			if (commitType === 'template') {
+				if (pendingTemplate) {
+					throw new Error('Found a template commit before completing a solution.');
+				}
+				pendingTemplate = { ...commit, baseCommit: previousCommit };
+				continue;
+			}
+
+			if (commitType === 'solution') {
+				if (!pendingTemplate) {
+					throw new Error('Found a solution commit without a preceding template.');
+				}
+				const stepFolder = path.join(outputRoot, stepCounter.toString());
+				ensureDir(stepFolder);
+
+				const templateFolder = path.join(stepFolder, 'template');
+				const solutionFolder = path.join(stepFolder, 'solution');
+				ensureDir(templateFolder);
+				ensureDir(solutionFolder);
+
+				await sourceGit.checkout(pendingTemplate.hash);
+				copySnapshot(tempDir, templateFolder);
+
+				const templateDiff = await sourceGit.diff([
+					'--name-status',
+					pendingTemplate.baseCommit,
+					pendingTemplate.hash,
+				]);
+
+				await sourceGit.checkout(commitHash);
+				copySnapshot(tempDir, solutionFolder);
+
+				const solutionDiff = await sourceGit.diff(['--name-status', pendingTemplate.hash, commitHash]);
+
+				const templateEntries = filterFileEntries(parseFileStatuses(templateDiff), 'template');
+				const solutionEntries = filterFileEntries(parseFileStatuses(solutionDiff), 'solution');
+
+				const manifestPath = path.join(stepFolder, 'files.json');
+				fs.writeFileSync(
+					manifestPath,
+					JSON.stringify(
+						{
+							template: templateEntries,
+							solution: solutionEntries,
+						},
+						null,
+						2
+					)
+				);
+
+				let markdown = stepMarkdown;
+				markdown = markdown.replace('<!-- insert_step_readme -->', './template/README.md');
+				markdown = markdown.replace(
+					'<!-- insert_monaco -->',
+					monacoEmbed('../_gitorial', './files.json')
+				);
+
+				fs.writeFileSync(path.join(stepFolder, 'README.md'), markdown);
+
+				const stepTitle = getStepTitle(templateFolder);
+				stepEntries.push({ name: stepTitle, isSection: false });
+
+				stepCounter += 1;
+				pendingTemplate = null;
+				previousCommit = commitHash;
+				continue;
+			}
+
+			if (pendingTemplate) {
+				throw new Error('Template commit must be followed by a solution commit.');
+			}
+
+			if (commitType === 'section' || commitType === 'readme') {
+				const stepFolder = path.join(outputRoot, stepCounter.toString());
+				ensureDir(stepFolder);
+
+				await sourceGit.checkout(commitHash);
+
+				const sourceReadme = path.join(tempDir, 'README.md');
+				if (!fs.existsSync(sourceReadme)) {
+					throw new Error(`Section/readme commit ${commitHash} is missing README.md`);
+				}
+
+				fs.copyFileSync(sourceReadme, path.join(stepFolder, 'README.md'));
+
+				const stepTitle = getStepTitle(stepFolder);
+				stepEntries.push({ name: stepTitle, isSection: true });
+
+				stepCounter += 1;
+				previousCommit = commitHash;
+				continue;
+			}
+
+			const stepFolder = path.join(outputRoot, stepCounter.toString());
+			ensureDir(stepFolder);
+			const sourceFolder = path.join(stepFolder, 'source');
+			ensureDir(sourceFolder);
+
+			await sourceGit.checkout(commitHash);
+			copySnapshot(tempDir, sourceFolder);
+
+			const diffOutput = await sourceGit.diff(['--name-status', previousCommit, commitHash]);
+			const sourceEntries = filterFileEntries(parseFileStatuses(diffOutput), 'source');
+
+			const manifestPath = path.join(stepFolder, 'files.json');
+			fs.writeFileSync(
+				manifestPath,
+				JSON.stringify({ template: sourceEntries, solution: [] }, null, 2)
+			);
+
+			let markdown = stepMarkdown;
+			markdown = markdown.replace('<!-- insert_step_readme -->', './source/README.md');
+			markdown = markdown.replace(
+				'<!-- insert_monaco -->',
+				monacoEmbed('../_gitorial', './files.json')
+			);
+			fs.writeFileSync(path.join(stepFolder, 'README.md'), markdown);
+
+			const stepTitle = getStepTitle(sourceFolder);
+			stepEntries.push({ name: stepTitle, isSection: false });
+
+			stepCounter += 1;
+			previousCommit = commitHash;
+		}
+
+		if (pendingTemplate) {
+			throw new Error('Template commit did not have a matching solution.');
+		}
+
+		const summaryPath = path.join(outputRoot, 'SUMMARY.md');
+		let summary = '# Summary\n\n';
+		stepEntries.forEach((entry, index) => {
+			if (!entry.isSection) {
+				summary += '    ';
+			}
+			summary += `- [${index}. ${entry.name}](${index}/README.md)\n`;
+		});
+		fs.writeFileSync(summaryPath, summary);
+
+		await git.raw(['add', '-A', sourceDirName]);
+		const status = await git.status();
+		if (!status.isClean()) {
+			await git.commit(`mdBook generated from ${inputBranch}`);
+			logger.info('mdBook branch generated successfully.');
+		} else {
+			logger.info('No mdBook changes detected.');
+		}
+	} finally {
+		fs.rmSync(tempDir, { recursive: true, force: true });
+	}
+}
+
+module.exports = { buildMdbook };

package/src/index.js

@@ -1,47 +1,41 @@
 #!/usr/bin/env node
 
 const { program } = require('commander');
+const { buildGitorial } = require('./commands/build-gitorial');
+const { buildMdbook } = require('./commands/build-mdbook');
 
 program
-	.version('1.0.0')
-	.description('Node.js CLI application to manage Git repositories');
+	.name('gitorial-cli')
+	.description('CLI tools for building and maintaining Gitorial tutorials')
+	.version('2.0.0');
 
-// Command to unpack a Gitorial into another branch.
 program
-	.command('unpack')
-	.description('Unpack a Gitorial into another branch.')
-	.requiredOption('-p, --path <path>', 'The local path for the git repo containing the Gitorial.')
-	.requiredOption('-i, --inputBranch <inputBranch>', 'The branch in the repo with the Gitorial.')
-	.requiredOption('-o, --outputBranch <outputBranch>', 'The branch where you want to unpack the Gitorial.')
-	.option('-s, --subFolder <subFolder>', 'The subfolder (relative to the <path>) where you want the unpacked Gitorial to be placed.')
-	.action(({ path, inputBranch, outputBranch, subFolder }) => {
-		require('./unpack')(path, inputBranch, outputBranch, subFolder);
+	.command('build-gitorial')
+	.description('Generate a gitorial branch from an mdBook workshop branch')
+	.option('-r, --repo <path>', 'Path to the tutorial repo', process.cwd())
+	.option('-i, --input <branch>', 'Input workshop branch', 'master')
+	.option('-o, --output <branch>', 'Output gitorial branch', 'gitorial')
+	.option('-s, --source <dir>', 'mdBook source directory', 'src')
+	.option('--force', 'Replace output branch if it exists', false)
+	.option('--verbose', 'Verbose logging', false)
+	.action(async (options) => {
+		await buildGitorial(options);
 	});
 
-
-// Command to create a repacked Gitorial from an unpacked Gitorial.
-program
-	.command('repack')
-	.description('Create a repacked Gitorial from an unpacked Gitorial. Must repack into a new branch.')
-	.requiredOption('-p, --path <path>', 'The local path for the git repo containing the Gitorial.')
-	.requiredOption('-i, --inputBranch <inputBranch>', 'The branch in the repo with the unpacked Gitorial.')
-	.requiredOption('-o, --outputBranch <outputBranch>', 'The branch where you want to repack the Gitorial. Branch must not exist.')
-	.option('-s, --subFolder <subFolder>', 'The subfolder (relative to the <path>) where you can find the unpacked Gitorial')
-	.option('--force', 'Force the repack, even if it would replace an existing branch. WARNING: this can delete the branch history!')
-	.action(({ path, inputBranch, outputBranch, subFolder, force }) => {
-		require('./repack')(path, inputBranch, outputBranch, subFolder, force);
-	});
-
-// Command to scaffold an mdBook source from a Gitorial.
 program
-	.command('mdbook')
-	.description('Scaffold the contents of a Gitorial in a new branch in the mdBook source format. You need to initialize an mdBook yourself ')
-	.requiredOption('-p, --path <path>', 'The local path for the git repo containing the Gitorial.')
-	.requiredOption('-i, --inputBranch <inputBranch>', 'The branch in the repo with the Gitorial.')
-	.requiredOption('-o, --outputBranch <outputBranch>', 'The branch where you want your mdBook to live')
-	.option('-s, --subFolder <subFolder>', 'The subfolder (relative to the <path>) where you want the mdBook source material to be placed.', 'src')
-	.action(({ path, inputBranch, outputBranch, subFolder }) => {
-		require('./mdbook')(path, inputBranch, outputBranch, subFolder);
+	.command('build-mdbook')
+	.description('Generate an mdBook workshop branch from a gitorial branch')
+	.option('-r, --repo <path>', 'Path to the tutorial repo', process.cwd())
+	.option('-i, --input <branch>', 'Input gitorial branch', 'gitorial')
+	.option('-o, --output <branch>', 'Output workshop branch', 'master')
+	.option('-s, --source <dir>', 'mdBook source directory', 'src')
+	.option('--force', 'Replace output branch if it exists', false)
+	.option('--verbose', 'Verbose logging', false)
+	.action(async (options) => {
+		await buildMdbook(options);
 	});
 
-program.parse(process.argv);
+program.parseAsync(process.argv).catch((error) => {
+	console.error(error.message || error);
+	process.exitCode = 1;
+});

package/src/lib/fs.js

@@ -0,0 +1,112 @@
+const fs = require('fs');
+const path = require('path');
+
+function ensureDir(dirPath) {
+	if (!fs.existsSync(dirPath)) {
+		fs.mkdirSync(dirPath, { recursive: true });
+	}
+}
+
+function removeAllExcept(targetDir, preserveNames = ['.git']) {
+	if (!fs.existsSync(targetDir)) {
+		return;
+	}
+	const items = fs.readdirSync(targetDir);
+	items.forEach((item) => {
+		if (preserveNames.includes(item)) {
+			return;
+		}
+		fs.rmSync(path.join(targetDir, item), { recursive: true, force: true });
+	});
+}
+
+function copyDir(sourceDir, targetDir, filterFn = () => true) {
+	ensureDir(targetDir);
+	const items = fs.readdirSync(sourceDir);
+	items.forEach((item) => {
+		const sourcePath = path.join(sourceDir, item);
+		const targetPath = path.join(targetDir, item);
+		const stats = fs.statSync(sourcePath);
+		if (!filterFn(sourcePath, stats.isDirectory())) {
+			return;
+		}
+		if (stats.isDirectory()) {
+			copyDir(sourcePath, targetPath, filterFn);
+		} else {
+			fs.copyFileSync(sourcePath, targetPath);
+		}
+	});
+}
+
+function listNumericDirs(dirPath) {
+	if (!fs.existsSync(dirPath)) {
+		return [];
+	}
+	return fs.readdirSync(dirPath)
+		.filter((entry) => /^\d+$/.test(entry))
+		.filter((entry) => fs.statSync(path.join(dirPath, entry)).isDirectory())
+		.sort((a, b) => parseInt(a) - parseInt(b));
+}
+
+function hasNonDocFiles(folderPath) {
+	if (!fs.existsSync(folderPath)) {
+		return false;
+	}
+
+	const entries = fs.readdirSync(folderPath);
+	for (const entry of entries) {
+		if (entry.startsWith('.')) {
+			continue;
+		}
+		const fullPath = path.join(folderPath, entry);
+		const stats = fs.statSync(fullPath);
+		if (stats.isDirectory()) {
+			if (hasNonDocFiles(fullPath)) {
+				return true;
+			}
+			continue;
+		}
+		if (entry === 'README.md') {
+			continue;
+		}
+		if (entry.endsWith('.diff')) {
+			continue;
+		}
+		return true;
+	}
+	return false;
+}
+
+function readFirstHeading(markdownPath) {
+	if (!fs.existsSync(markdownPath)) {
+		return null;
+	}
+	const content = fs.readFileSync(markdownPath, 'utf8');
+	const match = content.match(/^#\s+(.*)/m);
+	return match ? match[1].trim() : null;
+}
+
+function readGitorialType(markdownPath) {
+	if (!fs.existsSync(markdownPath)) {
+		return null;
+	}
+	const content = fs.readFileSync(markdownPath, 'utf8');
+
+	// Hidden HTML comment metadata, safe for included markdown.
+	// Example: <!-- gitorial: template -->
+	const commentMatch = content.match(/<!--\s*gitorial(?:_type)?\s*:\s*([a-z-]+)\s*-->/i);
+	if (commentMatch) {
+		return commentMatch[1].toLowerCase();
+	}
+	return null;
+}
+
+module.exports = {
+	ensureDir,
+	removeAllExcept,
+	copyDir,
+	listNumericDirs,
+	hasNonDocFiles,
+	readFirstHeading,
+	readGitorialType,
+};

package/src/lib/git.js

@@ -0,0 +1,45 @@
+const simpleGit = require('simple-git');
+
+function createGit(repoPath) {
+	return simpleGit(repoPath);
+}
+
+async function ensureBranchExists(git, branchName) {
+	const branches = await git.branchLocal();
+	if (!branches.all.includes(branchName)) {
+		throw new Error(`Branch not found: ${branchName}`);
+	}
+}
+
+async function checkoutBranch(git, branchName) {
+	await git.checkout(branchName);
+}
+
+async function deleteBranchIfExists(git, branchName) {
+	const branches = await git.branchLocal();
+	if (branches.all.includes(branchName)) {
+		await git.raw(['branch', '-D', branchName]);
+	}
+}
+
+async function createOrphanBranch(git, branchName, { force, fromBranch }) {
+	if (fromBranch) {
+		await checkoutBranch(git, fromBranch);
+	}
+	if (force) {
+		await deleteBranchIfExists(git, branchName);
+	} else {
+		const branches = await git.branchLocal();
+		if (branches.all.includes(branchName)) {
+			throw new Error(`Branch already exists: ${branchName}`);
+		}
+	}
+	await git.raw(['switch', '--orphan', branchName]);
+}
+
+module.exports = {
+	createGit,
+	ensureBranchExists,
+	checkoutBranch,
+	createOrphanBranch,
+};

package/src/lib/logger.js

@@ -0,0 +1,22 @@
+function createLogger({ verbose } = {}) {
+	const isVerbose = Boolean(verbose);
+
+	return {
+		info(message) {
+			console.log(message);
+		},
+		warn(message) {
+			console.warn(message);
+		},
+		error(message) {
+			console.error(message);
+		},
+		debug(message) {
+			if (isVerbose) {
+				console.log(message);
+			}
+		},
+	};
+}
+
+module.exports = { createLogger };

package/src/lib/mdbook-templates.js

@@ -0,0 +1,18 @@
+const stepMarkdown = `
+<div class="gitorial-step">
+<div class="gitorial-step-text">
+
+{{#include <!-- insert_step_readme -->}}
+
+</div>
+<div class="gitorial-step-editor">
+
+<!-- insert_monaco -->
+
+</div>
+</div>
+`;
+
+module.exports = {
+	stepMarkdown,
+};