gitorial-cli 1.0.1 → 2.0.0

package/README.md

@@ -1,97 +1,152 @@
-# cli
+# gitorial-cli
 
-The gitorial-cli is a CLI tool for helping manage and work with a Git repo following the [Gitorial format](https://github.com/gitorial-sdk).
+Tools for building step-by-step tutorials that are easy to contribute to and easy to render as clean, commit-based Gitorials.
 
-## Install
+This CLI helps you move between two tutorial representations:
+
+- `master` (or your workshop branch): mdBook-friendly, contributor-friendly structure
+- `gitorial`: commit-driven tutorial flow (`section`, `action`, `template`, `solution`)
 
-Install this CLI via NPM:
+## Install
 
 ```sh
 npm install -g gitorial-cli
 ```
 
+For local development in this repo:
+
+```sh
+npm install
+```
+
 ## Commands
 
-The CLI exposes various commands for managing a Gitorial.
+### `build-gitorial`
+
+Generate a gitorial branch from your mdBook workshop branch.
 
 ```sh
-Commands:
-  unpack [options]  Unpack a Gitorial into another branch.
-  repack [options]  Create a repacked Gitorial from an unpacked Gitorial. Must repack into a new branch.
-  mdbook [options]  Scaffold the contents of a Gitorial in a new branch in the mdBook source format. You need to initialize an mdBook yourself
+gitorial-cli build-gitorial -r /path/to/repo -i master -o gitorial -s src --force
 ```
 
-### unpack
+Options:
 
-```sh
-Usage: index unpack [options]
+- `-r, --repo <path>` repo path (default: current directory)
+- `-i, --input <branch>` workshop branch (default: `master`)
+- `-o, --output <branch>` gitorial branch (default: `gitorial`)
+- `-s, --source <dir>` mdBook source directory in input branch (default: `src`)
+- `--force` recreate output branch if it exists
+- `--verbose` verbose logs
 
-Unpack a Gitorial into another branch.
+Behavior:
 
-Options:
-  -p, --path <path>                  The local path for the git repo containing the Gitorial.
-  -i, --inputBranch <inputBranch>    The branch in the repo with the Gitorial.
-  -o, --outputBranch <outputBranch>  The branch where you want to unpack the Gitorial.
-  -s, --subFolder <subFolder>        The subfolder (relative to the <path>) where you want the unpacked Gitorial to be placed.
-  -h, --help                         display help for command
-```
+- Rebuilds `output` as a fresh orphan branch.
+- Rewrites commit history on the output branch by design.
+- Copies full step snapshots per commit, so output branch content is tutorial snapshot content.
+
+### `build-mdbook`
 
-Example: Convert an Gitorial repository from branch `gitorial` into branch `master` as an unpacked set of numbered steps in a folder named `steps`.
+Generate or update an mdBook workshop branch from a gitorial branch.
 
 ```sh
-gitorial-cli unpack -p /path/to/project -i gitorial -o master -s steps
+gitorial-cli build-mdbook -r /path/to/repo -i gitorial -o master -s src
 ```
 
-Output:
+Options:
 
-```sh
-# git branch: master
-steps/
-├─ 0/
-├─ 1/
-├─ 2/
-├─ ...
-```
+- `-r, --repo <path>` repo path (default: current directory)
+- `-i, --input <branch>` gitorial branch (default: `gitorial`)
+- `-o, --output <branch>` workshop branch (default: `master`)
+- `-s, --source <dir>` output mdBook source directory (default: `src`)
+- `--force` accepted but ignored (history is preserved)
+- `--verbose` verbose logs
 
-### repack
+Behavior:
 
-```sh
-Usage: index repack [options]
+- Preserves output branch history.
+- Replaces only the `source` directory content (for example `src/` or `example/src/`).
+- Leaves files outside that directory untouched.
 
-Create a repacked Gitorial from an unpacked Gitorial. Must repack into a new branch.
+## Step Types
 
-Options:
-  -p, --path <path>                  The local path for the git repo containing the Gitorial.
-  -i, --inputBranch <inputBranch>    The branch in the repo with the unpacked Gitorial.
-  -o, --outputBranch <outputBranch>  The branch where you want to repack the Gitorial. Branch must not exist.
-  -s, --subFolder <subFolder>        The subfolder (relative to the <path>) where you can find the unpacked Gitorial
-  --force                            Force the repack, even if it would replace an existing branch. WARNING: this can delete the branch history!
-  -h, --help                         display help for command
-```
+A gitorial step must map to one of these types:
 
-Example: Convert an "unpacked" Gitorial on branch `master` in folder `steps` to a branch `gitorial`
+- `section`: intro/context step, README only
+- `action`: non-template operational step
+- `template`: TODO step, must be followed by a `solution`
+- `solution`: working result of preceding template
 
-```sh
-gitorial-cli repack -p /path/to/project -i master -s steps -o gitorial
+Declare type in markdown using a hidden comment:
+
+```md
+<!-- gitorial: action -->
 ```
 
-### mdBook
+Supported forms:
+
+- `<!-- gitorial: section -->`
+- `<!-- gitorial: action -->`
+- `<!-- gitorial: template -->`
+- `<!-- gitorial: solution -->`
+
+## mdBook Workshop Layout
+
+Expected source layout:
+
+```text
+src/
+  SUMMARY.md
+  0/
+    README.md                     # section-only step (optional)
+  1/
+    README.md                     # generated step page with Monaco
+    source/
+      README.md                   # action/section source content
+      ...
+  2/
+    README.md                     # generated step page with Monaco
+    template/
+      README.md
+      ...
+    solution/
+      README.md
+      ...
+  _gitorial/
+    monaco-setup.js
+    monaco-setup.css
+```
 
-```sh
-Usage: index mdbook [options]
+Notes:
 
-Scaffold the contents of a Gitorial in a new branch in the mdBook source format. You need to initialize an mdBook yourself
+- `README.md` inside each step folder is the rendered page shell.
+- `files.json` is generated per interactive step to drive Monaco file selection.
+- Section-only steps are represented as numbered folders with only `README.md`.
 
-Options:
-  -p, --path <path>                  The local path for the git repo containing the Gitorial.
-  -i, --inputBranch <inputBranch>    The branch in the repo with the Gitorial.
-  -o, --outputBranch <outputBranch>  The branch where you want your mdBook to live
-  -s, --subFolder <subFolder>        The subfolder (relative to the <path>) where you want the mdBook source material to be placed. (default: "src")
-  -h, --help                         display help for command
-```
+## Workflow Expectations
+
+- Run commands from a clean working tree.
+- Commands switch branches in the target repo.
+- Use dedicated branches for workshop and gitorial.
+
+## CI
+
+Template workflow:
+
+- `templates/gitorial-sync.yml`
+- Syncs `gitorial` on pushes to `master`
+
+This repo also includes a concrete workflow:
+
+- `.github/workflows/sync-gitorial.yml`
+- Builds `gitorial` from `example/src` on pushes to `master`
+
+## Example in This Repo
+
+See `example/` for a complete fixture with all step types.
 
-Example: Convert a Gitorial at branch `gitorial` to an [mdBook](https://rust-lang.github.io/mdBook/) rendered at branch `mdbook`.
+Round-trip commands for this repo:
 
 ```sh
-gitorial-cli mdbook -p /path/to/project -i gitorial -o mdbook
+node src/index.js build-gitorial -r . -i master -o gitorial -s example/src --force
+node src/index.js build-mdbook -r . -i gitorial -o master -s example/src
 ```

package/package.json

@@ -1,9 +1,11 @@
 {
   "name": "gitorial-cli",
-  "version": "1.0.1",
-  "description": "CLI Tools for Creating and Managing a Gitorial",
+  "version": "2.0.0",
+  "description": "CLI tools for building and maintaining Gitorial tutorials",
   "main": "src/index.js",
-  "bin": "src/index.js",
+  "bin": {
+    "gitorial-cli": "src/index.js"
+  },
   "scripts": {
     "start": "node src/index.js"
   },
@@ -22,6 +24,6 @@
     "simple-git": "^3.24.0"
   },
   "files": [
-    "src/*"
+    "src/**/*"
   ]
 }

package/src/commands/build-gitorial.js

@@ -0,0 +1,152 @@
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { createLogger } = require('../lib/logger');
+const { createGit, ensureBranchExists, createOrphanBranch } = require('../lib/git');
+const {
+	copyDir,
+	hasNonDocFiles,
+	listNumericDirs,
+	readFirstHeading,
+	readGitorialType,
+	removeAllExcept,
+} = require('../lib/fs');
+
+function getStepTitle(stepDir) {
+	const candidates = [
+		path.join(stepDir, 'template', 'README.md'),
+		path.join(stepDir, 'source', 'README.md'),
+		path.join(stepDir, 'solution', 'README.md'),
+		path.join(stepDir, 'README.md'),
+	];
+	for (const candidate of candidates) {
+		const title = readFirstHeading(candidate);
+		if (title) {
+			return title;
+		}
+	}
+	return path.basename(stepDir);
+}
+
+function copySnapshot(sourceDir, repoPath) {
+	const filter = (sourcePath, isDirectory) => {
+		const baseName = path.basename(sourcePath);
+		if (baseName === '.git') {
+			return false;
+		}
+		if (!isDirectory && baseName.endsWith('.diff')) {
+			return false;
+		}
+		return true;
+	};
+	removeAllExcept(repoPath, ['.git']);
+	copyDir(sourceDir, repoPath, filter);
+}
+
+function resolveStepType(readmePath, defaultType) {
+	const declaredType = readGitorialType(readmePath);
+	if (!declaredType) {
+		return defaultType;
+	}
+	return declaredType;
+}
+
+function assertStepType(step, actualType, allowedTypes) {
+	if (!allowedTypes.includes(actualType)) {
+		throw new Error(`Step ${step} has unsupported gitorial type "${actualType}". Allowed: ${allowedTypes.join(', ')}`);
+	}
+}
+
+async function buildGitorial(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-'));
+	const sourceGit = createGit(tempDir);
+
+	try {
+		logger.info(`Cloning ${inputBranch} into temporary workspace...`);
+		await sourceGit.clone(repoPath, tempDir, ['--branch', inputBranch]);
+
+		const mdbookSourceDir = path.join(tempDir, sourceDirName);
+		if (!fs.existsSync(mdbookSourceDir)) {
+			throw new Error(`mdBook source directory not found: ${mdbookSourceDir}`);
+		}
+
+		const steps = listNumericDirs(mdbookSourceDir);
+		if (steps.length === 0) {
+			throw new Error(`No step folders found in ${mdbookSourceDir}`);
+		}
+
+		await createOrphanBranch(git, outputBranch, {
+			force: options.force,
+			fromBranch: inputBranch,
+		});
+
+		for (const step of steps) {
+			const stepDir = path.join(mdbookSourceDir, step);
+			const stepTitle = getStepTitle(stepDir);
+			const templateDir = path.join(stepDir, 'template');
+			const solutionDir = path.join(stepDir, 'solution');
+			const sourceDir = path.join(stepDir, 'source');
+			const sectionReadme = path.join(stepDir, 'README.md');
+
+			const hasTemplate = fs.existsSync(templateDir);
+			const hasSolution = fs.existsSync(solutionDir);
+			const hasSource = fs.existsSync(sourceDir);
+			const hasSectionReadme = fs.existsSync(sectionReadme);
+
+			if (hasTemplate && hasSolution) {
+				logger.info(`Step ${step}: template/solution → ${stepTitle}`);
+				const templateType = resolveStepType(path.join(templateDir, 'README.md'), 'template');
+				const solutionType = resolveStepType(path.join(solutionDir, 'README.md'), 'solution');
+				assertStepType(step, templateType, ['template']);
+				assertStepType(step, solutionType, ['solution']);
+
+				copySnapshot(templateDir, repoPath);
+				await git.add('.');
+				await git.commit(`${templateType}: ${stepTitle}`);
+
+				copySnapshot(solutionDir, repoPath);
+				await git.add('.');
+				await git.commit(`${solutionType}: ${stepTitle}`);
+				continue;
+			}
+
+			if (hasSource) {
+				logger.info(`Step ${step}: source/action → ${stepTitle}`);
+				const stepType = resolveStepType(path.join(sourceDir, 'README.md'), hasNonDocFiles(sourceDir) ? 'action' : 'section');
+				assertStepType(step, stepType, ['action', 'section']);
+
+				copySnapshot(sourceDir, repoPath);
+				await git.add('.');
+				await git.commit(`${stepType}: ${stepTitle}`);
+				continue;
+			}
+
+			if (hasSectionReadme) {
+				const stepType = resolveStepType(sectionReadme, 'section');
+				assertStepType(step, stepType, ['section']);
+				logger.info(`Step ${step}: section → ${stepTitle}`);
+				fs.copyFileSync(sectionReadme, path.join(repoPath, 'README.md'));
+				await git.add('README.md');
+				await git.commit(`${stepType}: ${stepTitle}`);
+				continue;
+			}
+
+			logger.warn(`Skipping step ${step}: no template/solution/source folder found.`);
+		}
+
+		logger.info('Gitorial branch generated successfully.');
+	} finally {
+		fs.rmSync(tempDir, { recursive: true, force: true });
+	}
+}
+
+module.exports = { buildGitorial };