@ts-for-gir/cli 4.0.0-beta.9 → 4.0.0-rc.10

package/src/commands/create.ts

@@ -0,0 +1,223 @@
+/**
+ * Everything you need for the `ts-for-gir create` command is located here
+ */
+
+import { spawnSync } from "node:child_process";
+import { cpSync, existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { input, select } from "@inquirer/prompts";
+import { APP_NAME, type ConfigFlags, Logger } from "@ts-for-gir/lib";
+
+import { createOptions } from "../config.ts";
+import type { CreateCommandArgs, CreateTemplateId } from "../types/index.ts";
+import { createBuilder } from "./command-builder.ts";
+
+const command = "create [name]";
+
+const description = "Scaffold a new GJS TypeScript project from a template";
+
+const examples: ReadonlyArray<[string, string?]> = [
+	[`${APP_NAME} create my-app --template types-npm`, "Scaffold using the @girs/* NPM types"],
+	[`${APP_NAME} create my-app --template types-locally`, "Scaffold and generate types into ./@types/ locally"],
+	[
+		`${APP_NAME} create my-app --template types-workspace`,
+		"Scaffold an npm workspace with types as workspace packages",
+	],
+	[`${APP_NAME} create`, "Interactive: prompts for name and template"],
+];
+
+const TEMPLATE_CHOICES: ReadonlyArray<{ value: CreateTemplateId; name: string; description: string }> = [
+	{
+		value: "types-locally",
+		name: "types-locally",
+		description: "Generate GIR types directly into ./@types/ (no package format, no @girs/* deps)",
+	},
+	{
+		value: "types-npm",
+		name: "types-npm",
+		description: "Use pre-generated types from the @girs/* NPM packages",
+	},
+	{
+		value: "types-workspace",
+		name: "types-workspace",
+		description: "npm workspace; generate @girs/* as workspace packages under ./@girs/",
+	},
+];
+
+const PROJECT_NAME_PLACEHOLDER = "__PROJECT_NAME__";
+
+const TEXT_FILE_EXT = new Set([".json", ".md", ".ts", ".tsx", ".js", ".mjs", ".cjs"]);
+
+const builder = createBuilder<CreateCommandArgs>(createOptions, examples);
+
+function findTemplatesRoot(): string {
+	const __filename = fileURLToPath(import.meta.url);
+	const __dirname = dirname(__filename);
+	const candidates = [
+		// Bundled production binary (bin/ts-for-gir): ../dist-templates
+		resolve(__dirname, "..", "dist-templates"),
+		// Source layout (src/commands/create.ts): ../../dist-templates then ../../templates
+		resolve(__dirname, "..", "..", "dist-templates"),
+		resolve(__dirname, "..", "..", "templates"),
+	];
+	for (const path of candidates) {
+		if (existsSync(path)) return path;
+	}
+	throw new Error(
+		`Could not locate templates directory. Looked in:\n  ${candidates.join("\n  ")}\n` +
+			"If you are running from source, make sure packages/cli/templates/ exists. " +
+			"If you are running the published CLI, make sure dist-templates/ was packed.",
+	);
+}
+
+function listTemplates(templatesRoot: string): CreateTemplateId[] {
+	const knownIds = TEMPLATE_CHOICES.map((c) => c.value) as readonly string[];
+	return readdirSync(templatesRoot, { withFileTypes: true })
+		.filter((entry) => entry.isDirectory())
+		.map((entry) => entry.name)
+		.filter((name): name is CreateTemplateId => knownIds.includes(name));
+}
+
+function sanitizeProjectName(raw: string): string {
+	const trimmed = raw.trim();
+	if (!trimmed) throw new Error("Project name cannot be empty");
+	// npm package name rules: lowercase letters, digits, dashes, underscores, dots; no leading dot/underscore
+	const cleaned = trimmed
+		.toLowerCase()
+		.replace(/[^a-z0-9._-]+/g, "-")
+		.replace(/^[._-]+/, "")
+		.replace(/[._-]+$/, "");
+	if (!cleaned) throw new Error(`"${raw}" is not a valid npm package name`);
+	return cleaned;
+}
+
+function isDirEmpty(path: string): boolean {
+	if (!existsSync(path)) return true;
+	return readdirSync(path).length === 0;
+}
+
+function substituteInFile(filePath: string, projectName: string): void {
+	const content = readFileSync(filePath, "utf8");
+	if (!content.includes(PROJECT_NAME_PLACEHOLDER)) return;
+	writeFileSync(filePath, content.replaceAll(PROJECT_NAME_PLACEHOLDER, projectName));
+}
+
+function walkAndSubstitute(rootDir: string, projectName: string): void {
+	for (const entry of readdirSync(rootDir, { withFileTypes: true })) {
+		const full = join(rootDir, entry.name);
+		if (entry.isDirectory()) {
+			if (entry.name === "node_modules") continue;
+			walkAndSubstitute(full, projectName);
+			continue;
+		}
+		if (!entry.isFile()) continue;
+		const ext = entry.name.slice(entry.name.lastIndexOf("."));
+		if (!TEXT_FILE_EXT.has(ext)) continue;
+		substituteInFile(full, projectName);
+	}
+}
+
+declare const __GJS_BUNDLE__: boolean | undefined;
+
+const handler = async (args: ConfigFlags) => {
+	if (typeof __GJS_BUNDLE__ !== "undefined") {
+		process.stderr.write(
+			"The 'create' command is not yet supported in the GJS bundle.\nUse Node.js instead: npx @ts-for-gir/cli create ...\n",
+		);
+		process.exitCode = 1;
+		return;
+	}
+	const opts = args as unknown as CreateCommandArgs;
+	const log = new Logger(opts.verbose ?? false, "CreateCommand");
+
+	const templatesRoot = findTemplatesRoot();
+	const available = listTemplates(templatesRoot);
+	if (available.length === 0) {
+		throw new Error(`No templates found in ${templatesRoot}`);
+	}
+
+	let template: CreateTemplateId | undefined = opts.template;
+	if (template && !available.includes(template)) {
+		throw new Error(`Unknown template "${template}". Available: ${available.join(", ")}`);
+	}
+	if (!template) {
+		if (!process.stdin.isTTY) {
+			throw new Error(`--template is required (non-TTY). Available: ${available.join(", ")}`);
+		}
+		template = await select<CreateTemplateId>({
+			message: "Choose a template:",
+			choices: TEMPLATE_CHOICES.filter((c) => available.includes(c.value)).map((c) => ({
+				value: c.value,
+				name: c.name,
+				description: c.description,
+			})),
+		});
+	}
+
+	let nameRaw = opts.name;
+	if (!nameRaw) {
+		if (!process.stdin.isTTY) {
+			throw new Error("Project name is required (non-TTY). Pass it as the first positional argument.");
+		}
+		nameRaw = await input({
+			message: "Project name:",
+			default: "my-gjs-app",
+			validate: (v) => (v.trim().length > 0 ? true : "Project name cannot be empty"),
+		});
+	}
+	const projectName = sanitizeProjectName(nameRaw);
+
+	const targetDir = resolve(process.cwd(), projectName);
+	if (existsSync(targetDir) && !isDirEmpty(targetDir) && !opts.force) {
+		throw new Error(
+			`Target directory ${targetDir} exists and is not empty. Use --force to scaffold into a non-empty directory.`,
+		);
+	}
+	mkdirSync(targetDir, { recursive: true });
+
+	const templateDir = join(templatesRoot, template);
+	cpSync(templateDir, targetDir, { recursive: true });
+	walkAndSubstitute(targetDir, projectName);
+
+	log.success(`Scaffolded ${template} into ${targetDir}`);
+
+	if (opts.install) {
+		log.info("Running npm install...");
+		const result = spawnSync("npm", ["install", "--no-audit", "--no-fund"], {
+			cwd: targetDir,
+			stdio: "inherit",
+		});
+		if (result.status !== 0) {
+			log.warn("npm install failed; you can re-run it manually in the project directory.");
+		}
+	}
+
+	log.info("\nNext steps:");
+	log.white(`  cd ${projectName}`);
+	if (!opts.install) log.white("  npm install");
+	switch (template) {
+		case "types-locally":
+			log.white("  npm run generate");
+			log.white("  npm run check:types");
+			log.white("  npm run build && npm start");
+			break;
+		case "types-npm":
+			log.white("  npm run check");
+			log.white("  npm run build && npm start");
+			break;
+		case "types-workspace":
+			log.white("  npm run build:types && npm install");
+			log.white("  npm run build:app && npm start");
+			break;
+	}
+};
+
+export const create = {
+	command,
+	description,
+	builder,
+	handler,
+	examples,
+};

package/src/commands/doc.ts

@@ -1,58 +1,55 @@
 /**
- * Everything you need for the `ts-for-gir generate` command is located here
+ * Everything you need for the `ts-for-gir doc` command is located here
  */
 
-import { Argv, BuilderCallback } from 'yargs'
-import { Logger, ERROR_NO_MODULES_FOUND } from '@ts-for-gir/lib'
-import { GeneratorType } from '@ts-for-gir/generator-base'
-import { GenerationHandler } from '../generation-handler.js'
-import { Config } from '../config.js'
-import { ModuleLoader } from '../module-loader.js'
+import { GeneratorType } from "@ts-for-gir/generator-base";
+import { HtmlDocGenerator } from "@ts-for-gir/generator-html-doc";
+import { APP_NAME, type ConfigFlags, NSRegistry } from "@ts-for-gir/lib";
+import { docOptions, getOptionsGeneration, load } from "../config.ts";
+import { TypeScriptFormatter } from "../formatters/typescript-formatter.ts";
+import type { DocCommandArgs } from "../types/index.ts";
+import { createBuilder } from "./command-builder.ts";
+import { runGenerationCommand } from "./run-generation-command.ts";
 
-import type { ConfigFlags } from '@ts-for-gir/lib'
+const command = "doc [modules..]";
 
-const command = 'doc [modules..]'
+const description = "Generates HTML documentation from GIR files using TypeDoc";
 
-const description = 'The HTML documentation generator is not yet implemented, but feel free to implement it 🤗'
+const examples: ReadonlyArray<[string, string?]> = [
+	[`${APP_NAME} doc Gtk-4.0 --outdir ./docs`, "Generate HTML documentation for Gtk-4.0"],
+	[`${APP_NAME} doc '*' --outdir ./docs`, "Generate documentation for all locally installed GIR modules"],
+	[
+		`${APP_NAME} doc --merge --jsonDir ./json-output --outdir ./docs`,
+		"Generate HTML from pre-generated JSON files (low memory)",
+	],
+];
 
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-const builder: BuilderCallback<any, ConfigFlags> = (yargs: Argv<any>) => {
-    const optionNames = Object.keys(Config.docOptions)
-    for (const optionName of optionNames) {
-        yargs = yargs.option(optionName, Config.docOptions[optionName])
-    }
-    return yargs.example(examples) as Argv<ConfigFlags>
-}
+const builder = createBuilder<DocCommandArgs>(docOptions, examples);
 
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
 const handler = async (args: ConfigFlags) => {
-    const config = await Config.load(args)
-
-    const generateConfig = Config.getOptionsGeneration(config)
-    const moduleLoader = new ModuleLoader(generateConfig)
-    const { keep } = await moduleLoader.getModulesResolved(
-        config.modules,
-        config.ignore || [],
-        config.ignoreVersionConflicts,
-    )
-    if (keep.length === 0) {
-        return Logger.error(ERROR_NO_MODULES_FOUND(config.girDirectories))
-    }
-    const tsForGir = new GenerationHandler(generateConfig, GeneratorType.HTML_DOC)
-    const registry = moduleLoader.dependencyManager
-
-    await tsForGir.start(
-        Array.from(keep).map((girModuleResolvedBy) => girModuleResolvedBy.module),
-        registry,
-    )
-}
-
-const examples: ReadonlyArray<[string, string?]> = []
+	const config = getOptionsGeneration(await load(args));
+	if (config.merge) {
+		if (!config.jsonDir) {
+			throw new Error("--jsonDir is required when using --merge mode");
+		}
+		const generator = new HtmlDocGenerator(config, new NSRegistry());
+		await generator.generateFromJson(config.jsonDir);
+		return;
+	}
+
+	await runGenerationCommand(args, {
+		generatorType: GeneratorType.HTML_DOC,
+		loggerName: "DocCommand",
+		configureRegistry: (registry) => {
+			registry.registerFormatter("dts", new TypeScriptFormatter());
+		},
+	});
+};
 
 export const doc = {
-    command,
-    description,
-    builder,
-    handler,
-    examples,
-}
+	command,
+	description,
+	builder,
+	handler,
+	examples,
+};

package/src/commands/generate.ts

@@ -2,89 +2,45 @@
  * Everything you need for the `ts-for-gir generate` command is located here
  */
 
-import { Argv, BuilderCallback } from 'yargs'
-import { ERROR_NO_MODULES_FOUND, Logger } from '@ts-for-gir/lib'
-import { GeneratorType } from '@ts-for-gir/generator-base'
-import { GenerationHandler } from '../generation-handler.js'
-import { Config } from '../config.js'
-import { ModuleLoader } from '../module-loader.js'
-import prettier from 'prettier'
+import { GeneratorType } from "@ts-for-gir/generator-base";
+import { APP_NAME, type ConfigFlags } from "@ts-for-gir/lib";
+import { generateOptions } from "../config.ts";
+import { TypeScriptFormatter } from "../formatters/typescript-formatter.ts";
+import type { GenerateCommandArgs } from "../types/index.ts";
+import { createBuilder } from "./command-builder.ts";
+import { runGenerationCommand } from "./run-generation-command.ts";
 
-import type { ConfigFlags } from '@ts-for-gir/lib'
-import { Formatter } from '@ts-for-gir/lib'
+const command = "generate [modules..]";
 
-const command = 'generate [modules..]'
-
-const description = 'Generates Typescript type definition .d.ts files from GIR for GJS'
-
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-const builder: BuilderCallback<any, ConfigFlags> = (yargs: Argv<any>) => {
-    const optionNames = Object.keys(Config.generateOptions)
-    for (const optionName of optionNames) {
-        yargs = yargs.option(optionName, Config.generateOptions[optionName])
-    }
-    return yargs.example(examples) as Argv<ConfigFlags>
-}
-
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-const handler = async (args: ConfigFlags) => {
-    const config = await Config.load(args)
-
-    const generateConfig = Config.getOptionsGeneration(config)
-    const moduleLoader = new ModuleLoader(generateConfig)
-    const { keep } = await moduleLoader.getModulesResolved(
-        config.modules,
-        config.ignore || [],
-        config.ignoreVersionConflicts,
-    )
-
-    if (keep.length === 0) {
-        return Logger.error(ERROR_NO_MODULES_FOUND(config.girDirectories))
-    }
-
-    moduleLoader.parse(keep)
-
-    const tsForGir = new GenerationHandler(generateConfig, GeneratorType.TYPES)
-
-    const girModules = Array.from(keep).map((girModuleResolvedBy) => girModuleResolvedBy.module)
-
-    moduleLoader.dependencyManager.registerFormatter('dts', new TypeScriptFormatter())
-    await tsForGir.start(girModules, moduleLoader.dependencyManager)
-}
+const description = "Generates Typescript type definition .d.ts files from GIR for GJS";
 
 const examples: ReadonlyArray<[string, string?]> = [
-    [
-        `${Config.appName} generate`,
-        `Run '${Config.appName} generate' in your gjs project to generate typings for your project, pass the gir modules you need for your project`,
-    ],
-    [`${Config.appName} generate Gtk*`, 'You can also use wild cards'],
-    [`${Config.appName} generate '*'`, 'If you want to parse all of your locally installed gir modules run'],
-    [`${Config.appName} generate --configName='.ts-for-gir.gtk4.rc.js`, 'Use a special config file'],
-    [
-        `${Config.appName} generate --ignore=Gtk-4.0 xrandr-1.3`,
-        'Generate .d.ts. files but not for Gtk-4.0 and xrandr-1.3',
-    ],
-]
+	[
+		`${APP_NAME} generate`,
+		`Run '${APP_NAME} generate' in your gjs project to generate typings for your project, pass the gir modules you need for your project`,
+	],
+	[`${APP_NAME} generate 'Gtk*'`, "You can also use wild cards"],
+	[`${APP_NAME} generate '*'`, "If you want to parse all of your locally installed gir modules run"],
+	[`${APP_NAME} generate --configName='.ts-for-gir.gtk4.rc.js`, "Use a special config file"],
+	[`${APP_NAME} generate --ignore=Gtk-4.0 xrandr-1.3`, "Generate .d.ts. files but not for Gtk-4.0 and xrandr-1.3"],
+];
+
+const builder = createBuilder<GenerateCommandArgs>(generateOptions, examples);
 
-class TypeScriptFormatter extends Formatter {
-    format(input: string): Promise<string> {
-        try {
-            return prettier.format(input, {
-                singleQuote: true,
-                parser: 'typescript',
-                printWidth: 120,
-                tabWidth: 4,
-            })
-        } catch (error) {
-            return Promise.resolve(input)
-        }
-    }
-}
+const handler = async (args: ConfigFlags) => {
+	await runGenerationCommand(args, {
+		generatorType: GeneratorType.TYPES,
+		loggerName: "GenerateCommand",
+		configureRegistry: (registry) => {
+			registry.registerFormatter("dts", new TypeScriptFormatter());
+		},
+	});
+};
 
 export const generate = {
-    command,
-    description,
-    builder,
-    handler,
-    examples,
-}
+	command,
+	description,
+	builder,
+	handler,
+	examples,
+};

package/src/commands/index.ts

@@ -1,4 +1,8 @@
-export * from './copy.js'
-export * from './doc.js'
-export * from './generate.js'
-export * from './list.js'
+export * from "./analyze.ts";
+export * from "./copy.ts";
+export * from "./create.ts";
+export * from "./doc.ts";
+export * from "./generate.ts";
+export * from "./json.ts";
+export * from "./list.ts";
+export * from "./self-update.ts";

package/src/commands/json.ts

@@ -0,0 +1,43 @@
+/**
+ * Everything you need for the `ts-for-gir json` command is located here
+ */
+
+import { GeneratorType } from "@ts-for-gir/generator-base";
+import { APP_NAME, type ConfigFlags } from "@ts-for-gir/lib";
+import { generateOptions } from "../config.ts";
+import { TypeScriptFormatter } from "../formatters/typescript-formatter.ts";
+import type { GenerateCommandArgs } from "../types/index.ts";
+import { createBuilder } from "./command-builder.ts";
+import { runGenerationCommand } from "./run-generation-command.ts";
+
+const command = "json [modules..]";
+
+const description = "Generates JSON representation from GIR files for analysis and tooling";
+
+const examples: ReadonlyArray<[string, string?]> = [
+	[`${APP_NAME} json`, `Run '${APP_NAME} json' in your gjs project to generate JSON files for your project`],
+	[`${APP_NAME} json 'Gtk*'`, "You can also use wild cards"],
+	[`${APP_NAME} json '*'`, "If you want to parse all of your locally installed gir modules run"],
+	[`${APP_NAME} json --configName='.ts-for-gir.gtk4.rc.js`, "Use a special config file"],
+	[`${APP_NAME} json --ignore=Gtk-4.0 xrandr-1.3`, "Generate JSON files but not for Gtk-4.0 and xrandr-1.3"],
+];
+
+const builder = createBuilder<GenerateCommandArgs>(generateOptions, examples);
+
+const handler = async (args: ConfigFlags) => {
+	await runGenerationCommand(args, {
+		generatorType: GeneratorType.JSON,
+		loggerName: "JsonCommand",
+		configureRegistry: (registry) => {
+			registry.registerFormatter("dts", new TypeScriptFormatter());
+		},
+	});
+};
+
+export const json = {
+	command,
+	description,
+	builder,
+	handler,
+	examples,
+};