@fragno-dev/cli 0.1.14 → 0.1.16

package/dist/cli.js

@@ -1,13 +1,18 @@
 #!/usr/bin/env node
-import { cli, define, parseArgs, resolveArgs } from "gunshi";
+import { cli, define } from "gunshi";
 import { mkdir, writeFile } from "node:fs/promises";
-import { dirname, relative, resolve } from "node:path";
+import { dirname, join, relative, resolve } from "node:path";
 import { executeMigrations, generateMigrationsOrSchema } from "@fragno-dev/db/generation-engine";
 import { FragnoDatabase, isFragnoDatabase } from "@fragno-dev/db";
 import { fragnoDatabaseAdapterNameFakeSymbol, fragnoDatabaseAdapterVersionFakeSymbol } from "@fragno-dev/db/adapters";
 import { instantiatedFragmentFakeSymbol } from "@fragno-dev/core/api/fragment-instantiation";
 import { loadConfig } from "c12";
-import { getSubject, getSubjects } from "@fragno-dev/corpus";
+import { getAllSubjects, getSubject, getSubjectChildren, getSubjectParent, getSubjects } from "@fragno-dev/corpus";
+import { marked } from "marked";
+import { markedTerminal } from "marked-terminal";
+import { stripVTControlCharacters } from "node:util";
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
 
 //#region src/utils/find-fragno-databases.ts
 async function importFragmentFile(path) {
@@ -391,75 +396,360 @@ const searchCommand = define({
 
 //#endregion
 //#region src/commands/corpus.ts
+marked.use(markedTerminal());
 /**
-* Print a subject with its examples
+* Build markdown content for multiple subjects
 */
-function printSubject(subject) {
-	console.log(`\n${"=".repeat(60)}`);
-	console.log(`${subject.title}`);
-	console.log(`${"=".repeat(60)}\n`);
-	if (subject.description) {
-		console.log(subject.description);
-		console.log();
+function buildSubjectsMarkdown(subjects) {
+	let fullMarkdown = "";
+	for (const subject of subjects) {
+		fullMarkdown += `# ${subject.title}\n\n`;
+		if (subject.description) fullMarkdown += `${subject.description}\n\n`;
+		if (subject.imports) fullMarkdown += `### Imports\n\n\`\`\`typescript\n${subject.imports}\n\`\`\`\n\n`;
+		if (subject.prelude.length > 0) {
+			fullMarkdown += `### Prelude\n\n`;
+			for (const block of subject.prelude) fullMarkdown += `\`\`\`typescript\n${block.code}\n\`\`\`\n\n`;
+		}
+		for (const section of subject.sections) fullMarkdown += `## ${section.heading}\n\n${section.content}\n\n`;
+	}
+	return fullMarkdown;
+}
+/**
+* Add line numbers to content
+*/
+function addLineNumbers(content, startFrom = 1) {
+	const lines = content.split("\n");
+	const maxDigits = String(startFrom + lines.length - 1).length;
+	return lines.map((line, index) => {
+		const lineNum = startFrom + index;
+		return `${String(lineNum).padStart(maxDigits, " ")}│ ${line}`;
+	}).join("\n");
+}
+/**
+* Filter content by line range
+*/
+function filterByLineRange(content, startLine, endLine) {
+	const lines = content.split("\n");
+	const start = Math.max(0, startLine - 1);
+	const end = Math.min(lines.length, endLine);
+	return lines.slice(start, end).join("\n");
+}
+/**
+* Extract headings and code block information with line numbers
+*/
+function extractHeadingsAndBlocks(subjects) {
+	let output = "";
+	let currentLine = 1;
+	let lastOutputLine = 0;
+	const addGapIfNeeded = () => {
+		if (lastOutputLine > 0 && currentLine > lastOutputLine + 1) output += `    │\n`;
+	};
+	output += "Use --start N --end N flags to show specific line ranges\n\n";
+	for (const subject of subjects) {
+		addGapIfNeeded();
+		output += `${currentLine.toString().padStart(4, " ")}│ # ${subject.title}\n`;
+		lastOutputLine = currentLine;
+		currentLine += 1;
+		output += `${currentLine.toString().padStart(4, " ")}│\n`;
+		lastOutputLine = currentLine;
+		currentLine += 1;
+		if (subject.description) {
+			const descLines = subject.description.split("\n");
+			for (const line of descLines) {
+				output += `${currentLine.toString().padStart(4, " ")}│ ${line}\n`;
+				lastOutputLine = currentLine;
+				currentLine += 1;
+			}
+			output += `${currentLine.toString().padStart(4, " ")}│\n`;
+			lastOutputLine = currentLine;
+			currentLine += 1;
+		}
+		if (subject.imports) {
+			addGapIfNeeded();
+			output += `${currentLine.toString().padStart(4, " ")}│ ### Imports\n`;
+			lastOutputLine = currentLine;
+			currentLine += 1;
+			output += `${currentLine.toString().padStart(4, " ")}│\n`;
+			lastOutputLine = currentLine;
+			currentLine += 1;
+			output += `${currentLine.toString().padStart(4, " ")}│ \`\`\`typescript\n`;
+			lastOutputLine = currentLine;
+			currentLine += 1;
+			const importLines = subject.imports.split("\n");
+			for (const line of importLines) {
+				output += `${currentLine.toString().padStart(4, " ")}│ ${line}\n`;
+				lastOutputLine = currentLine;
+				currentLine += 1;
+			}
+			output += `${currentLine.toString().padStart(4, " ")}│ \`\`\`\n`;
+			lastOutputLine = currentLine;
+			currentLine += 1;
+			output += `${currentLine.toString().padStart(4, " ")}│\n`;
+			lastOutputLine = currentLine;
+			currentLine += 1;
+		}
+		if (subject.prelude.length > 0) {
+			addGapIfNeeded();
+			output += `${currentLine.toString().padStart(4, " ")}│ ### Prelude\n`;
+			lastOutputLine = currentLine;
+			currentLine += 1;
+			output += `${currentLine.toString().padStart(4, " ")}│\n`;
+			lastOutputLine = currentLine;
+			currentLine += 1;
+			for (const block of subject.prelude) {
+				const id = block.id || "(no-id)";
+				const blockStartLine = currentLine + 1;
+				const codeLines = block.code.split("\n").length;
+				const blockEndLine = currentLine + 1 + codeLines;
+				output += `${currentLine.toString().padStart(4, " ")}│   - id: \`${id}\`, L${blockStartLine}-${blockEndLine}\n`;
+				lastOutputLine = currentLine;
+				currentLine += codeLines + 3;
+			}
+			lastOutputLine = currentLine - 1;
+		}
+		const sectionToExamples = /* @__PURE__ */ new Map();
+		for (const example of subject.examples) for (const section of subject.sections) if (section.content.includes(example.code.substring(0, Math.min(50, example.code.length)))) {
+			if (!sectionToExamples.has(section.heading)) sectionToExamples.set(section.heading, []);
+			sectionToExamples.get(section.heading).push(example);
+			break;
+		}
+		for (const section of subject.sections) {
+			addGapIfNeeded();
+			output += `${currentLine.toString().padStart(4, " ")}│ ## ${section.heading}\n`;
+			lastOutputLine = currentLine;
+			currentLine += 1;
+			const examples = sectionToExamples.get(section.heading) || [];
+			if (examples.length > 0) {
+				const sectionStartLine = currentLine;
+				const lines = section.content.split("\n");
+				for (const example of examples) {
+					const id = example.id || "(no-id)";
+					let blockStartLine = sectionStartLine;
+					let blockEndLine = sectionStartLine;
+					let foundBlock = false;
+					for (let i = 0; i < lines.length; i++) if (lines[i].trim().startsWith("```") && true) {
+						const codeStart = i + 1;
+						let matches = true;
+						const exampleLines = example.code.split("\n");
+						for (let j = 0; j < Math.min(3, exampleLines.length); j++) if (lines[codeStart + j]?.trim() !== exampleLines[j]?.trim()) {
+							matches = false;
+							break;
+						}
+						if (matches) {
+							blockStartLine = sectionStartLine + i + 1;
+							blockEndLine = sectionStartLine + i + exampleLines.length;
+							foundBlock = true;
+							break;
+						}
+					}
+					if (foundBlock) output += `${currentLine.toString().padStart(4, " ")}│   - id: \`${id}\`, L${blockStartLine}-${blockEndLine}\n`;
+					else output += `${currentLine.toString().padStart(4, " ")}│   - id: \`${id}\`\n`;
+					lastOutputLine = currentLine;
+				}
+			}
+			const sectionLines = section.content.split("\n");
+			for (const _line of sectionLines) currentLine += 1;
+			currentLine += 1;
+			lastOutputLine = currentLine - 1;
+		}
 	}
-	if (subject.imports) {
-		console.log("### Imports\n");
-		console.log("```typescript");
-		console.log(subject.imports);
-		console.log("```\n");
+	return output;
+}
+/**
+* Print subjects with the given options
+*/
+async function printSubjects(subjects, options) {
+	if (options.headingsOnly) {
+		const headingsOutput = extractHeadingsAndBlocks(subjects);
+		console.log(headingsOutput);
+		return;
 	}
-	if (subject.init) {
-		console.log("### Initialization\n");
-		console.log("```typescript");
-		console.log(subject.init);
-		console.log("```\n");
+	const markdown = buildSubjectsMarkdown(subjects);
+	let output = await marked.parse(markdown);
+	const startLine = options.startLine ?? 1;
+	if (options.startLine !== void 0 || options.endLine !== void 0) {
+		const end = options.endLine ?? output.split("\n").length;
+		output = filterByLineRange(output, startLine, end);
 	}
-	for (let i = 0; i < subject.examples.length; i++) {
-		const example = subject.examples[i];
-		console.log(`### Example ${i + 1}\n`);
-		console.log("```typescript");
-		console.log(example.code);
-		console.log("```");
-		if (example.explanation) {
-			console.log();
-			console.log(example.explanation);
+	if (options.showLineNumbers) output = addLineNumbers(output, startLine);
+	console.log(output);
+}
+/**
+* Find and print code blocks by ID
+*/
+async function printCodeBlockById(id, topics, showLineNumbers) {
+	const subjects = topics.length > 0 ? getSubject(...topics) : getAllSubjects();
+	const matches = [];
+	for (const subject of subjects) {
+		const fullMarkdown = buildSubjectsMarkdown([subject]);
+		const renderedLines = (await marked.parse(fullMarkdown)).split("\n");
+		for (const block of subject.prelude) if (block.id === id) {
+			let startLine;
+			let endLine;
+			const codeLines = block.code.split("\n");
+			const firstCodeLine = codeLines[0].trim();
+			for (let i = 0; i < renderedLines.length; i++) if (stripVTControlCharacters(renderedLines[i]).trim() === firstCodeLine) {
+				startLine = i + 1;
+				endLine = i + codeLines.length;
+				break;
+			}
+			matches.push({
+				subjectId: subject.id,
+				subjectTitle: subject.title,
+				section: "Prelude",
+				code: block.code,
+				type: "prelude",
+				startLine,
+				endLine
+			});
+		}
+		for (const example of subject.examples) if (example.id === id) {
+			let sectionName = "Unknown Section";
+			let startLine;
+			let endLine;
+			for (const section of subject.sections) if (section.content.includes(example.code.substring(0, Math.min(50, example.code.length)))) {
+				sectionName = section.heading;
+				const codeLines = example.code.split("\n");
+				const firstCodeLine = codeLines[0].trim();
+				for (let i = 0; i < renderedLines.length; i++) if (stripVTControlCharacters(renderedLines[i]).trim() === firstCodeLine) {
+					startLine = i + 1;
+					endLine = i + codeLines.length;
+					break;
+				}
+				break;
+			}
+			matches.push({
+				subjectId: subject.id,
+				subjectTitle: subject.title,
+				section: sectionName,
+				code: example.code,
+				type: "example",
+				startLine,
+				endLine
+			});
 		}
-		console.log();
+	}
+	if (matches.length === 0) {
+		console.error(`Error: No code block found with id "${id}"`);
+		if (topics.length > 0) console.error(`Searched in topics: ${topics.join(", ")}`);
+		else console.error("Searched in all available topics");
+		process.exit(1);
+	}
+	for (let i = 0; i < matches.length; i++) {
+		const match = matches[i];
+		if (matches.length > 1 && i > 0) console.log("\n---\n");
+		let matchMarkdown = `# ${match.subjectTitle}\n\n`;
+		matchMarkdown += `## ${match.section}\n\n`;
+		if (showLineNumbers && match.startLine && match.endLine) console.log(`Lines ${match.startLine}-${match.endLine} (use with --start/--end)\n`);
+		matchMarkdown += `\`\`\`typescript\n${match.code}\n\`\`\`\n`;
+		const rendered = await marked.parse(matchMarkdown);
+		console.log(rendered);
 	}
 }
 /**
 * Print information about the corpus command
 */
 function printCorpusHelp() {
-	console.log("Fragno Corpus - Code examples and documentation");
+	console.log("Fragno Corpus - Code examples and documentation (similar to LLMs.txt");
+	console.log("");
+	console.log("Usage: fragno-cli corpus [options] [topic...]");
 	console.log("");
-	console.log("Usage: fragno-cli corpus [topic...]");
+	console.log("Options:");
+	console.log("  -n, --no-line-numbers      Hide line numbers (shown by default)");
+	console.log("  -s, --start N              Starting line number to display from");
+	console.log("  -e, --end N                Ending line number to display to");
+	console.log("  --headings                 Show only headings and code block IDs");
+	console.log("  --id <id>                  Retrieve a specific code block by ID");
 	console.log("");
 	console.log("Examples:");
 	console.log("  fragno-cli corpus                           # List all available topics");
 	console.log("  fragno-cli corpus defining-routes           # Show route definition examples");
+	console.log("  fragno-cli corpus --headings database-querying");
+	console.log("                                              # Show structure overview");
+	console.log("  fragno-cli corpus --start 10 --end 50 database-querying");
+	console.log("                                              # Show specific lines");
+	console.log("  fragno-cli corpus --id create-user          # Get code block by ID");
 	console.log("  fragno-cli corpus database-adapters kysely-adapter");
 	console.log("                                              # Show multiple topics");
 	console.log("");
 	console.log("Available topics:");
 	const subjects = getSubjects();
-	for (const subject of subjects) console.log(`  ${subject.id.padEnd(30)} ${subject.title}`);
+	const rootSubjects = [];
+	const subjectMap = new Map(subjects.map((s) => [s.id, s]));
+	for (const subject of subjects) if (!getSubjectParent(subject.id)) {
+		const children = getSubjectChildren(subject.id);
+		rootSubjects.push({
+			id: subject.id,
+			title: subject.title,
+			children: children.map((childId) => ({
+				id: childId,
+				title: subjectMap.get(childId)?.title || childId
+			}))
+		});
+	}
+	for (const root of rootSubjects) {
+		console.log(`  ${root.id.padEnd(30)} ${root.title}`);
+		for (let i = 0; i < root.children.length; i++) {
+			const child = root.children[i];
+			const connector = i === root.children.length - 1 ? "└─" : "├─";
+			console.log(`    ${connector} ${child.id.padEnd(26)} ${child.title}`);
+		}
+	}
 }
 const corpusCommand = define({
 	name: "corpus",
 	description: "View code examples and documentation for Fragno",
-	run: (ctx) => {
+	args: {
+		"no-line-numbers": {
+			type: "boolean",
+			short: "n",
+			description: "Hide line numbers (line numbers are shown by default)"
+		},
+		start: {
+			type: "number",
+			short: "s",
+			description: "Starting line number (1-based) to display from"
+		},
+		end: {
+			type: "number",
+			short: "e",
+			description: "Ending line number (1-based) to display to"
+		},
+		headings: {
+			type: "boolean",
+			description: "Show only section headings and code block IDs with line numbers"
+		},
+		id: {
+			type: "string",
+			description: "Retrieve a specific code block by ID"
+		}
+	},
+	run: async (ctx) => {
 		const topics = ctx.positionals;
+		const showLineNumbers = !(ctx.values["no-line-numbers"] ?? false);
+		const startLine = ctx.values.start;
+		const endLine = ctx.values.end;
+		const headingsOnly = ctx.values.headings ?? false;
+		const codeBlockId = ctx.values.id;
+		if (codeBlockId) {
+			await printCodeBlockById(codeBlockId, topics, showLineNumbers);
+			return;
+		}
 		if (topics.length === 0) {
 			printCorpusHelp();
 			return;
 		}
+		if (startLine !== void 0 && endLine !== void 0 && startLine > endLine) {
+			console.error("Error: --start must be less than or equal to --end");
+			process.exit(1);
+		}
 		try {
-			const subjects = getSubject(...topics);
-			for (const subject of subjects) printSubject(subject);
-			console.log(`${"=".repeat(60)}`);
-			console.log(`Displayed ${subjects.length} topic(s)`);
-			console.log(`${"=".repeat(60)}\n`);
+			await printSubjects(getSubject(...topics), {
+				showLineNumbers,
+				startLine,
+				endLine,
+				headingsOnly
+			});
 		} catch (error) {
 			console.error("Error loading topics:", error instanceof Error ? error.message : error);
 			console.log("\nRun 'fragno-cli corpus' to see available topics.");
@@ -470,75 +760,91 @@ const corpusCommand = define({
 
 //#endregion
 //#region src/cli.ts
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const version = JSON.parse(readFileSync(join(__dirname, "../package.json"), "utf-8")).version;
 const dbSubCommands = /* @__PURE__ */ new Map();
 dbSubCommands.set("generate", generateCommand);
 dbSubCommands.set("migrate", migrateCommand);
 dbSubCommands.set("info", infoCommand);
-function printDbHelp() {
-	console.log("Database management commands for Fragno");
-	console.log("");
-	console.log("Usage: fragno-cli db <command> [options]");
-	console.log("");
-	console.log("Commands:");
-	console.log("  generate    Generate schema files from FragnoDatabase definitions");
-	console.log("  migrate     Run database migrations");
-	console.log("  info        Display database information and migration status");
-	console.log("");
-	console.log("Run 'fragno-cli db <command> --help' for more information.");
-}
 const dbCommand = define({
 	name: "db",
-	description: "Database management commands",
-	run: printDbHelp
+	description: "Database management commands"
 });
-const rootSubCommands = /* @__PURE__ */ new Map();
-rootSubCommands.set("db", dbCommand);
-rootSubCommands.set("search", searchCommand);
-rootSubCommands.set("corpus", corpusCommand);
 const mainCommand = define({
 	name: "fragno-cli",
-	description: "Fragno CLI - Tools for working with Fragno fragments",
-	run: () => {
-		console.log("Fragno CLI - Tools for working with Fragno fragments");
-		console.log("");
-		console.log("Usage: fragno-cli <command> [options]");
-		console.log("");
-		console.log("Commands:");
-		console.log("  db       Database management commands");
-		console.log("  search   Search the Fragno documentation");
-		console.log("  corpus   View code examples and documentation");
-		console.log("");
-		console.log("Run 'fragno-cli <command> --help' for more information.");
-	}
+	description: "Tools for working with Fragno fragments"
 });
 if (import.meta.main) try {
 	const args = process.argv.slice(2);
-	if (args[0] === "search") await cli(args.slice(1), searchCommand);
-	else if (args[0] === "corpus") await cli(args.slice(1), corpusCommand);
-	else if (args[0] === "db" && args.length > 1) {
+	if (args[0] === "search") await cli(args.slice(1), searchCommand, {
+		name: "fragno-cli search",
+		version
+	});
+	else if (args[0] === "corpus") await cli(args.slice(1), corpusCommand, {
+		name: "fragno-cli corpus",
+		version
+	});
+	else if (args[0] === "db") {
 		const subCommandName = args[1];
-		if (subCommandName === "--help" || subCommandName === "-h") {
-			printDbHelp();
-			process.exit(0);
-		}
-		const subCommand = dbSubCommands.get(subCommandName);
-		if (!subCommand) {
-			console.error(`Unknown command: ${subCommandName}`);
+		if (!subCommandName || subCommandName === "--help" || subCommandName === "-h") {
+			console.log("Database management commands");
 			console.log("");
-			printDbHelp();
-			process.exit(1);
-		}
-		const subArgs = args.slice(2);
-		const isSubCommandHelp = subArgs.includes("--help") || subArgs.includes("-h");
-		let hasValidationError = false;
-		if (!isSubCommandHelp && subCommand.args) {
-			const tokens = parseArgs(subArgs);
-			hasValidationError = !!resolveArgs(subCommand.args, tokens).error;
+			console.log("USAGE:");
+			console.log("  fragno-cli db <COMMAND>");
+			console.log("");
+			console.log("COMMANDS:");
+			console.log("  generate              Generate schema files from FragnoDatabase definitions");
+			console.log("  migrate               Run database migrations");
+			console.log("  info                  Display database information and migration status");
+			console.log("");
+			console.log("For more info, run any command with the `--help` flag:");
+			console.log("  fragno-cli db generate --help");
+			console.log("  fragno-cli db migrate --help");
+			console.log("  fragno-cli db info --help");
+			console.log("");
+			console.log("OPTIONS:");
+			console.log("  -h, --help             Display this help message");
+			console.log("  -v, --version          Display this version");
+		} else if (subCommandName === "--version" || subCommandName === "-v") console.log(version);
+		else {
+			const subCommand = dbSubCommands.get(subCommandName);
+			if (!subCommand) {
+				console.error(`Unknown command: ${subCommandName}`);
+				console.log("");
+				console.log("Run 'fragno-cli db --help' for available commands.");
+				process.exit(1);
+			}
+			await cli(args.slice(2), subCommand, {
+				name: `fragno-cli db ${subCommandName}`,
+				version
+			});
 		}
-		await cli(subArgs, subCommand);
-		if (hasValidationError) process.exit(1);
-	} else if (args[0] === "db") printDbHelp();
-	else await cli(args, mainCommand, { subCommands: rootSubCommands });
+	} else if (!args.length || args[0] === "--help" || args[0] === "-h") {
+		console.log("Tools for working with Fragno");
+		console.log("");
+		console.log("USAGE:");
+		console.log("  fragno-cli <COMMAND>");
+		console.log("");
+		console.log("COMMANDS:");
+		console.log("  db                    Database management commands");
+		console.log("  search                Search the Fragno documentation");
+		console.log("  corpus                View code examples and documentation for Fragno");
+		console.log("");
+		console.log("For more info, run any command with the `--help` flag:");
+		console.log("  fragno-cli db --help");
+		console.log("  fragno-cli search --help");
+		console.log("  fragno-cli corpus --help");
+		console.log("");
+		console.log("OPTIONS:");
+		console.log("  -h, --help             Display this help message");
+		console.log("  -v, --version          Display this version");
+	} else if (args[0] === "--version" || args[0] === "-v") console.log(version);
+	else {
+		console.error(`Unknown command: ${args[0]}`);
+		console.log("");
+		console.log("Run 'fragno-cli --help' for available commands.");
+		process.exit(1);
+	}
 } catch (error) {
 	console.error("Error:", error instanceof Error ? error.message : error);
 	process.exit(1);