@ts-for-gir/cli 4.0.0-rc.1 → 4.0.0-rc.12

package/src/commands/run-generation-command.ts

@@ -6,6 +6,7 @@ import {
 	Logger,
 	NSRegistry,
 	ReporterService,
+	ResolveType,
 } from "@ts-for-gir/lib";
 import { getOptionsGeneration, load } from "../config.ts";
 import { GenerationHandler } from "../generation-handler.ts";
@@ -45,7 +46,11 @@ export async function runGenerationCommand(args: ConfigFlags, options: Generatio
 
 		moduleLoader.parse(keep);
 
-		const girModules = Array.from(keep).map((girModuleResolvedBy) => girModuleResolvedBy.module as GirModule);
+		// In external-deps mode, only generate the user-requested module(s). Transitively-loaded
+		// deps stay in the registry for type resolution but must not produce their own output.
+		const toGenerate = generateConfig.externalDeps ? keep.filter((m) => m.resolvedBy === ResolveType.BY_HAND) : keep;
+
+		const girModules = Array.from(toGenerate).map((girModuleResolvedBy) => girModuleResolvedBy.module as GirModule);
 
 		await tsForGir.start(girModules);
 	} catch (error) {

package/src/commands/self-update.ts

@@ -0,0 +1,142 @@
+/**
+ * Everything you need for the `ts-for-gir self-update` command is located here
+ */
+
+import { chmodSync, existsSync, renameSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { APP_NAME, APP_VERSION } from "@ts-for-gir/lib";
+
+import type { SelfUpdateCommandArgs } from "../types/index.ts";
+
+const REPO = "gjsify/ts-for-gir";
+const GITHUB_API = "https://api.github.com";
+const GJS_ASSET_NAME = "ts-for-gir-gjs";
+
+function getCurrentBinaryPath(): string | null {
+	const p = process.argv[1] ?? null;
+	if (!p) return null;
+	// Refuse to update in dev mode (source file or node_modules path)
+	if (p.endsWith(".ts") || p.includes("node_modules")) return null;
+	return p;
+}
+
+async function fetchJson(url: string): Promise<unknown> {
+	const headers: Record<string, string> = {
+		Accept: "application/vnd.github.v3+json",
+		"User-Agent": `ts-for-gir/${APP_VERSION}`,
+	};
+	const token = process.env.GITHUB_TOKEN;
+	if (token) headers.Authorization = `token ${token}`;
+
+	const response = await fetch(url, { headers });
+	if (!response.ok) {
+		throw new Error(`HTTP ${response.status} from ${url}`);
+	}
+	return response.json();
+}
+
+async function downloadBinary(url: string, destPath: string): Promise<void> {
+	const response = await fetch(url, {
+		headers: { "User-Agent": `ts-for-gir/${APP_VERSION}` },
+	});
+	if (!response.ok) {
+		throw new Error(`HTTP ${response.status} downloading binary`);
+	}
+	const buffer = await response.arrayBuffer();
+	const tmpPath = join(tmpdir(), `ts-for-gir-update-${Date.now()}`);
+	writeFileSync(tmpPath, Buffer.from(buffer));
+	chmodSync(tmpPath, 0o755);
+	renameSync(tmpPath, destPath); // atomic on POSIX
+}
+
+const command = "self-update";
+const description = "Update ts-for-gir to the latest version from GitHub releases";
+const examples: ReadonlyArray<[string, string?]> = [
+	[`${APP_NAME} self-update`, "Check for updates and install the latest version"],
+	[`${APP_NAME} self-update --check`, "Only check for a newer version, do not install"],
+	[`${APP_NAME} self-update --force`, "Force reinstall even if already on the latest version"],
+];
+
+const builder = (yargs: import("yargs").Argv) =>
+	yargs
+		.option("check", {
+			description: "Only check for a newer version, do not install",
+			type: "boolean",
+			default: false,
+		})
+		.option("force", {
+			description: "Force reinstall even if already on the latest version",
+			type: "boolean",
+			default: false,
+		})
+		.example(examples as [string, string?][]);
+
+const handler = async (args: SelfUpdateCommandArgs): Promise<void> => {
+	console.log(`Checking for updates... (current: v${APP_VERSION})`);
+
+	let release: Record<string, unknown>;
+	try {
+		release = (await fetchJson(`${GITHUB_API}/repos/${REPO}/releases/latest`)) as Record<string, unknown>;
+	} catch (err) {
+		const msg = err instanceof Error ? err.message : String(err);
+		process.stderr.write(`Failed to fetch release information: ${msg}\n`);
+		process.exitCode = 1;
+		return;
+	}
+
+	const latestVersion = (release.tag_name as string).replace(/^v/, "");
+
+	if (latestVersion === APP_VERSION && !args.force) {
+		console.log(`Already up to date (v${APP_VERSION})`);
+		return;
+	}
+
+	if (args.check) {
+		console.log(`New version available: v${latestVersion} (current: v${APP_VERSION})`);
+		console.log(`Run \`${APP_NAME} self-update\` to install it.`);
+		return;
+	}
+
+	console.log(`Updating to v${latestVersion}...`);
+
+	const assets = release.assets as Array<Record<string, string>>;
+	const asset = assets.find((a) => a.name === GJS_ASSET_NAME);
+	if (!asset) {
+		process.stderr.write(
+			`No GJS binary found in release ${release.tag_name}.\n` +
+				"self-update requires the GJS bundle to be installed via install.js.\n" +
+				"For npm installations use: npm update -g @ts-for-gir/cli\n",
+		);
+		process.exitCode = 1;
+		return;
+	}
+
+	const currentPath = getCurrentBinaryPath();
+	if (!currentPath || !existsSync(currentPath)) {
+		process.stderr.write(
+			"Cannot determine current binary path for update.\n" +
+				"self-update only works when running the installed GJS binary.\n",
+		);
+		process.exitCode = 1;
+		return;
+	}
+
+	try {
+		await downloadBinary(asset.browser_download_url, currentPath);
+		console.log(`Successfully updated to v${latestVersion}`);
+	} catch (err) {
+		const msg = err instanceof Error ? err.message : String(err);
+		process.stderr.write(`Update failed: ${msg}\n`);
+		process.exitCode = 1;
+	}
+};
+
+export const selfUpdate = {
+	command,
+	description,
+	builder,
+	handler,
+	examples,
+};

package/src/config/config-loader.ts

@@ -59,6 +59,24 @@ export function getOptionsGeneration(config: UserConfig): OptionsGeneration {
 	return generateConfig;
 }
 
+/**
+ * Parse `Namespace=npm-package` strings (from repeatable `--external-package` flag) into a
+ * map. Silently drops entries that don't contain `=`. Empty input returns undefined so the
+ * field stays absent in the merged config (rather than `{}`, which would shadow rc values).
+ */
+function parseExternalPackagePairs(pairs: string[] | undefined): Record<string, string> | undefined {
+	if (!pairs || pairs.length === 0) return undefined;
+	const map: Record<string, string> = {};
+	for (const pair of pairs) {
+		const eq = pair.indexOf("=");
+		if (eq < 1) continue;
+		const ns = pair.slice(0, eq).trim();
+		const pkg = pair.slice(eq + 1).trim();
+		if (ns && pkg) map[ns] = pkg;
+	}
+	return Object.keys(map).length > 0 ? map : undefined;
+}
+
 /**
  * Validate the configuration
  */
@@ -111,9 +129,21 @@ export async function load(cliOptions: ConfigFlags): Promise<UserConfig> {
 	const configFile = await loadConfigFile(cliOptions.configName);
 	const configFileData = configFile?.config || {};
 
+	// `--external-package GLib=@girs/glib-2.0` arrives as a string[]; collapse to Record.
+	// Drop the raw array so it doesn't pollute the merged UserConfig surface.
+	const externalPackagesFromCli = parseExternalPackagePairs(
+		(cliOptions as { externalPackage?: string[] }).externalPackage,
+	);
+	const { externalPackage: _externalPackage, ...cliOptionsClean } = cliOptions as ConfigFlags & {
+		externalPackage?: string[];
+	};
+
 	const userConfig: UserConfig = {
-		...cliOptions,
+		...cliOptionsClean,
 	};
+	if (externalPackagesFromCli) {
+		userConfig.externalPackages = externalPackagesFromCli;
+	}
 
 	if (configFileData) {
 		// Boolean options — config file overrides CLI defaults
@@ -130,6 +160,8 @@ export async function load(cliOptions: ConfigFlags): Promise<UserConfig> {
 			["noAdvancedVariants", options.noAdvancedVariants.default],
 			["package", options.package.default],
 			["reporter", options.reporter.default],
+			["externalDeps", options.externalDeps.default],
+			["allowMissingDeps", options.allowMissingDeps.default],
 			["combined", docOptions.combined.default],
 			["merge", docOptions.merge.default],
 		];
@@ -141,6 +173,7 @@ export async function load(cliOptions: ConfigFlags): Promise<UserConfig> {
 		const stringKeys: Array<[keyof UserConfig, unknown]> = [
 			["npmScope", options.npmScope.default],
 			["reporterOutput", options.reporterOutput.default],
+			["depVersionFormat", undefined],
 			["theme", docOptions.theme.default],
 			["sourceLinkTemplate", undefined],
 			["readme", undefined],
@@ -152,7 +185,6 @@ export async function load(cliOptions: ConfigFlags): Promise<UserConfig> {
 
 		// Array options — config file overrides CLI defaults
 		const arrayKeys: Array<[keyof UserConfig, unknown]> = [
-			["girDirectories", options.girDirectories.default],
 			["ignore", options.ignore.default],
 			["modules", options.modules.default],
 		];
@@ -160,6 +192,18 @@ export async function load(cliOptions: ConfigFlags): Promise<UserConfig> {
 			mergeConfigValue(userConfig, configFileData, key, defaultVal);
 		}
 
+		// girDirectories: rc-file entries are prepended to the current dirs (CLI-provided or
+		// system defaults) rather than replacing them. This lets projects add local GIR dirs
+		// (e.g. a Vala build output) without having to enumerate all system paths in the rc.
+		// To use ONLY the specified dirs (no system fallback), pass --girDirectories on the CLI.
+		if (configFileData.girDirectories?.length) {
+			const current = userConfig.girDirectories as string[];
+			const toAdd = (configFileData.girDirectories as string[]).filter((d) => !current.includes(d));
+			if (toAdd.length > 0) {
+				userConfig.girDirectories = [...toAdd, ...current];
+			}
+		}
+
 		// Special handling for root
 		if (userConfig.root === options.root.default && (configFileData.root || configFile?.filepath)) {
 			userConfig.root =
@@ -171,6 +215,11 @@ export async function load(cliOptions: ConfigFlags): Promise<UserConfig> {
 		if (isDefaultOutdir && configFileData.outdir) {
 			userConfig.outdir = userConfig.print ? null : configFileData.outdir;
 		}
+
+		// externalPackages is a Record<string, string> in rc files; CLI overrides take precedence.
+		if (!externalPackagesFromCli && configFileData.externalPackages) {
+			userConfig.externalPackages = configFileData.externalPackages;
+		}
 	}
 
 	// Make paths absolute relative to root
@@ -185,6 +234,5 @@ export async function load(cliOptions: ConfigFlags): Promise<UserConfig> {
 	if (userConfig.girDirectories) {
 		userConfig.girDirectories = userConfig.girDirectories.map(resolveToRoot);
 	}
-
 	return validate(userConfig);
 }

package/src/config/defaults.ts

@@ -31,6 +31,8 @@ export const defaults = {
 	package: false,
 	reporter: false,
 	reporterOutput: "ts-for-gir-report.json",
+	externalDeps: false,
+	allowMissingDeps: false,
 	combined: true,
 	/** Default theme for `ts-for-gir doc` (HTML documentation). */
 	theme: "gi-docgen",

package/src/config/index.ts

@@ -5,4 +5,12 @@
 export { getOptionsGeneration, load, validate } from "./config-loader.ts";
 export { addToConfig, configFilePath } from "./config-writer.ts";
 export { defaults } from "./defaults.ts";
-export { analyzeOptions, copyOptions, docOptions, generateOptions, listOptions, options } from "./options.ts";
+export {
+	analyzeOptions,
+	copyOptions,
+	createOptions,
+	docOptions,
+	generateOptions,
+	listOptions,
+	options,
+} from "./options.ts";

package/src/config/options.ts

@@ -103,6 +103,12 @@ export const options: { [name: string]: Options } = {
 		default: defaults.workspace,
 		normalize: true,
 	},
+	depVersionFormat: {
+		type: "string",
+		description:
+			"Dependency version spec format in generated package.json files. Defaults to 'workspace' when --workspace, else 'exact'",
+		choices: ["workspace", "caret", "any", "exact"] as const,
+	},
 	onlyVersionPrefix: {
 		type: "boolean",
 		description:
@@ -140,6 +146,26 @@ export const options: { [name: string]: Options } = {
 		default: defaults.reporterOutput,
 		normalize: true,
 	},
+	externalDeps: {
+		type: "boolean",
+		description:
+			"Emit imports from installed @girs/* npm packages instead of regenerating dep types. Implies single-file ambient .d.ts output. Designed for project-local Vala/C bridges. Strict by default — missing transitive dep GIRs abort the run; pass --allow-missing-deps to override.",
+		default: defaults.externalDeps,
+		normalize: true,
+	},
+	allowMissingDeps: {
+		type: "boolean",
+		description:
+			"In --external-deps mode, allow generation to proceed when app-specific transitive dep GIRs are missing (e.g. CI without libsoup3-devel). Note: GLib/Gio/GObject GIRs are still architecturally required for class-hierarchy resolution. Default strict behavior prevents silent type-quality drift between environments.",
+		default: defaults.allowMissingDeps,
+		normalize: true,
+	},
+	externalPackage: {
+		type: "string",
+		description:
+			"Override the default namespace→npm package mapping for --external-deps mode. Repeatable. Format: 'Namespace=@scope/pkg'. Example: --external-package Soup=@girs/soup-3.0",
+		array: true,
+	},
 };
 
 /**
@@ -160,12 +186,16 @@ export const generateOptions = {
 	promisify: options.promisify,
 	npmScope: options.npmScope,
 	workspace: options.workspace,
+	depVersionFormat: options.depVersionFormat,
 	onlyVersionPrefix: options.onlyVersionPrefix,
 	noPrettyPrint: options.noPrettyPrint,
 	noAdvancedVariants: options.noAdvancedVariants,
 	package: options.package,
 	reporter: options.reporter,
 	reporterOutput: options.reporterOutput,
+	externalDeps: options.externalDeps,
+	allowMissingDeps: options.allowMissingDeps,
+	externalPackage: options.externalPackage,
 };
 
 export const listOptions = {
@@ -223,6 +253,26 @@ export const docOptions = {
 	},
 };
 
+export const createOptions = {
+	template: {
+		type: "string" as const,
+		alias: "t",
+		description: "Template to scaffold (types-locally, types-npm, types-workspace)",
+		choices: ["types-locally", "types-npm", "types-workspace"] as const,
+	},
+	install: {
+		type: "boolean" as const,
+		description: "Run npm install after scaffolding (use --no-install to skip)",
+		default: true,
+	},
+	force: {
+		type: "boolean" as const,
+		description: "Allow scaffolding into a non-empty target directory",
+		default: false,
+	},
+	verbose: options.verbose,
+};
+
 export const analyzeOptions = {
 	reportFile: {
 		type: "string" as const,

package/src/formatters/typescript-formatter.ts

@@ -1,24 +1,17 @@
 /**
- * TypeScript formatter using Prettier
+ * TypeScript formatter — pass-through.
+ *
+ * The generator's templates and string-builders emit the desired output
+ * shape directly; we no longer round-trip through Prettier. This shrinks
+ * the generation pipeline (no AST parse + reprint per file), drops a
+ * heavy bundler-hostile dependency for non-Node consumers, and makes
+ * generated output deterministic without an external formatter.
  */
 
-import { Formatter, Logger } from "@ts-for-gir/lib";
-import prettier from "prettier";
-
-const logger = new Logger(false, "TypeScriptFormatter");
+import { Formatter } from "@ts-for-gir/lib";
 
 export class TypeScriptFormatter extends Formatter {
 	format(input: string): Promise<string> {
-		try {
-			return prettier.format(input, {
-				singleQuote: true,
-				parser: "typescript",
-				printWidth: 120,
-				tabWidth: 4,
-			});
-		} catch (error) {
-			logger.warn("Failed to format with prettier, returning original input", error);
-			return Promise.resolve(input);
-		}
+		return Promise.resolve(input);
 	}
 }

package/src/module-loader.ts

@@ -168,7 +168,13 @@ export class ModuleLoader {
 				const girModule = await this.loadAndCreateGirModule(dependency);
 				if (!girModule) {
 					if (!failedGirModules.has(dependency.packageName)) {
-						this.log.warn(WARN_NO_GIR_FILE_FOUND_FOR_PACKAGE(dependency.packageName));
+						// In external-deps mode the strict check after loading turns missing
+						// transitive deps into a hard error; suppress the per-dep warn here so
+						// the user sees one consolidated error instead of a wall of warnings.
+						// `--allow-missing-deps` opts into the same suppression with a soft fail.
+						if (!this.config.externalDeps) {
+							this.log.warn(WARN_NO_GIR_FILE_FOUND_FOR_PACKAGE(dependency.packageName));
+						}
 						failedGirModules.add(dependency.packageName);
 					}
 				} else if (girModule?.packageName) {
@@ -239,23 +245,49 @@ export class ModuleLoader {
 
 		const dependencies = await this.fileFinder.girFilePathToDependencies(girFiles);
 
+		// Load GJS force-loads as DEPENDENCE so they are never treated as user-requested
+		// modules. This ensures --external-deps mode doesn't emit output files for them.
+		const { loaded: forceLoaded, failed: forceFailed } = await this.loadGirModules(
+			[GLib, Gio, GObject, Cairo],
+			ignore,
+			[],
+			ResolveType.DEPENDENCE,
+		);
+
+		// Load user-requested modules (and their transitive deps) starting from the
+		// already-loaded force-load registry so they are not double-loaded.
 		const { loaded, failed } = await this.loadGirModules(
-			[
-				GLib,
-				Gio,
-				GObject,
-				Cairo,
-				...dependencies.filter(
-					(dep) =>
-						dep.namespace !== "GLib" &&
-						dep.namespace !== "Gio" &&
-						dep.namespace !== "GObject" &&
-						dep.namespace !== "cairo",
-				),
-			],
+			dependencies.filter(
+				(dep) =>
+					dep.namespace !== "GLib" &&
+					dep.namespace !== "Gio" &&
+					dep.namespace !== "GObject" &&
+					dep.namespace !== "cairo",
+			),
 			ignore,
+			forceLoaded,
+			ResolveType.BY_HAND,
+			forceFailed,
 		);
 
+		// External-deps mode is strict by default: any transitive dep GIR that couldn't be
+		// loaded would silently degrade type quality. The hardcoded GLib/Gio/GObject/cairo
+		// force-loads above are exempt (they exist for runtime convenience, not because the
+		// input GIR references them).
+		if (this.config.externalDeps && !this.config.allowMissingDeps && failed.size > 0) {
+			const exempt = new Set(["GLib-2.0", "Gio-2.0", "GObject-2.0", "cairo-1.0"]);
+			const critical = Array.from(failed).filter((pkg) => !exempt.has(pkg));
+			if (critical.length > 0) {
+				throw new Error(
+					`Missing GIR files for transitive dependencies in --external-deps mode:\n` +
+						critical.map((pkg) => `  - ${pkg}`).join("\n") +
+						`\n\nInstall the corresponding -devel packages, add their directories to ` +
+						`--girDirectories, or pass --allow-missing-deps to generate anyway ` +
+						`(warning: degraded type quality).`,
+				);
+			}
+		}
+
 		let keep: GirModuleResolvedBy[] = [];
 		if (doNotAskForVersionOnConflict) {
 			keep = loaded;

package/src/start.ts

@@ -2,19 +2,37 @@ import { APP_NAME, APP_USAGE, APP_VERSION } from "@ts-for-gir/lib";
 import yargs, { type CommandModule } from "yargs";
 import { hideBin } from "yargs/helpers";
 
-import { analyze, copy, doc, generate, json, list } from "./commands/index.ts";
+import { analyze, copy, create, doc, generate, json, list, selfUpdate } from "./commands/index.ts";
 
-void yargs(hideBin(process.argv))
-	.scriptName(APP_NAME)
-	.strict()
-	.usage(APP_USAGE)
-	.version(APP_VERSION)
-	// TODO: Fix this
-	.command(analyze as unknown as CommandModule)
-	.command(generate as unknown as CommandModule)
-	.command(json as unknown as CommandModule)
-	.command(list as unknown as CommandModule)
-	.command(copy as unknown as CommandModule)
-	.command(doc as unknown as CommandModule)
-	.demandCommand(1)
-	.help().argv;
+try {
+	await yargs(hideBin(process.argv))
+		.scriptName(APP_NAME)
+		.strict()
+		.usage(APP_USAGE)
+		.version(APP_VERSION)
+		// Disable yargs's internal `process.exit` and route both success
+		// and failure through `parseAsync` + an explicit `process.exit` so
+		// async command handlers complete and stdout drains before the
+		// runtime (Node or the gjsify Node-compat loader on GJS, which
+		// keeps a GLib main loop alive that would otherwise prevent the
+		// process from exiting after main() returns) tears down.
+		.exitProcess(false)
+		.fail(false)
+		// TODO: Fix this
+		.command(analyze as unknown as CommandModule)
+		.command(create as unknown as CommandModule)
+		.command(generate as unknown as CommandModule)
+		.command(json as unknown as CommandModule)
+		.command(list as unknown as CommandModule)
+		.command(copy as unknown as CommandModule)
+		.command(doc as unknown as CommandModule)
+		.command(selfUpdate as unknown as CommandModule)
+		.demandCommand(1)
+		.help()
+		.parseAsync();
+	process.exit(0);
+} catch (err) {
+	const message = err instanceof Error ? err.message : String(err);
+	process.stderr.write(`${message}\n`);
+	process.exit(1);
+}

package/src/types/command-args.ts

@@ -36,6 +36,8 @@ export interface GenerateCommandArgs extends BaseCommandArgs {
 	npmScope: string;
 	/** Uses the workspace protocol for the generated packages which can be used with package managers like Yarn and PNPM */
 	workspace: boolean;
+	/** Dependency version spec format in generated package.json files */
+	depVersionFormat?: "workspace" | "caret" | "any" | "exact";
 	/** Only use the version prefix for the ambient module exports */
 	onlyVersionPrefix: boolean;
 	/** Do not prettify the generated types */
@@ -48,6 +50,12 @@ export interface GenerateCommandArgs extends BaseCommandArgs {
 	reporter: boolean;
 	/** Output file path for the reporter */
 	reporterOutput: string;
+	/** Emit imports from installed @girs/* npm packages instead of regenerating dep types */
+	externalDeps: boolean;
+	/** Allow externalDeps generation when transitive dep GIRs are missing (degraded type quality) */
+	allowMissingDeps: boolean;
+	/** Override default namespace→npm package mapping. Repeatable. Format: `Namespace=@girs/pkg` */
+	externalPackage?: string[];
 }
 
 /**
@@ -83,6 +91,27 @@ export interface DocCommandArgs extends GenerateCommandArgs {
 	jsonDir?: string;
 }
 
+/**
+ * Available scaffolding template identifiers for the create command.
+ */
+export type CreateTemplateId = "types-locally" | "types-npm" | "types-workspace";
+
+/**
+ * Arguments for the create command
+ */
+export interface CreateCommandArgs {
+	/** Project name and target directory (positional) */
+	name?: string;
+	/** Template identifier */
+	template?: CreateTemplateId;
+	/** Run npm install after scaffolding (use --no-install to skip) */
+	install: boolean;
+	/** Allow scaffolding into a non-empty target directory */
+	force: boolean;
+	/** Switch on/off the verbose mode */
+	verbose: boolean;
+}
+
 /**
  * Arguments for the analyze command
  */
@@ -116,3 +145,10 @@ export interface AnalyzeCommandArgs {
 	/** Switch on/off the verbose mode */
 	verbose?: boolean;
 }
+
+export interface SelfUpdateCommandArgs {
+	/** Only check for a newer version, do not install */
+	check: boolean;
+	/** Force reinstall even if already on the latest version */
+	force: boolean;
+}