@ts-for-gir/cli 4.0.0 → 4.0.2

package/dist-templates/types-gjsify/README.md

@@ -0,0 +1,32 @@
+# __PROJECT_NAME__
+
+GJS + TypeScript starter, fully Node-free at runtime. Uses pre-generated [`@girs/*`](https://www.npmjs.com/org/girs) types and the [`gjsify` CLI](https://gjsify.github.io/gjsify/) for install, build, run, format and lint — no `npm`, no `node`, no `esbuild` ceremony.
+
+## Setup
+
+```sh
+gjsify install
+gjsify run build && gjsify run start
+```
+
+That's it. `gjsify build` produces a single GJS bundle with the right `firefox*` target + `gi://*` externals; `gjsify run` launches it with `LD_LIBRARY_PATH` / `GI_TYPELIB_PATH` pre-wired for any native typelib deps.
+
+## Scripts
+
+| Script | What it does |
+|---|---|
+| `gjsify install` | Install deps (Node-free; reads `gjsify-lock.json`) |
+| `gjsify run check` | TypeScript `tsc --noEmit` |
+| `gjsify run build` | Bundle `main.ts` → `dist/main.js` |
+| `gjsify run start` | Launch the bundle under `gjs -m` |
+| `gjsify run format` | Format via Biome |
+| `gjsify run fix` | Format + safe-fix lint + organize imports |
+| `gjsify run clear` | Remove `dist/` |
+
+## Adding GIR modules
+
+Install the matching `@girs/<name>-<version>` package and add it to `tsconfig.json`'s `types` array. Example for GStreamer:
+
+```sh
+gjsify install @girs/gst-1.0
+```

package/dist-templates/types-gjsify/biome.json

@@ -0,0 +1,38 @@
+{
+	"$schema": "https://biomejs.dev/schemas/2.4.13/schema.json",
+	"formatter": {
+		"enabled": true,
+		"indentStyle": "tab",
+		"lineWidth": 120,
+		"lineEnding": "lf"
+	},
+	"linter": {
+		"enabled": true,
+		"rules": {
+			"recommended": true,
+			"style": {
+				"useImportType": "warn",
+				"useNodejsImportProtocol": "error",
+				"noNonNullAssertion": "off"
+			},
+			"suspicious": {
+				"noExplicitAny": "warn",
+				"noConsole": "off"
+			},
+			"correctness": {
+				"noUnusedImports": "warn"
+			}
+		}
+	},
+	"javascript": {
+		"formatter": {
+			"quoteStyle": "double",
+			"semicolons": "always",
+			"trailingCommas": "all",
+			"arrowParentheses": "always"
+		}
+	},
+	"files": {
+		"includes": ["**", "!**/node_modules", "!**/dist", "!**/.cache"]
+	}
+}

package/dist-templates/types-gjsify/main.ts

@@ -0,0 +1,19 @@
+import Adw from "gi://Adw?version=1";
+import Gio from "gi://Gio?version=2.0";
+import Gtk from "gi://Gtk?version=4.0";
+
+const app = new Adw.Application({
+	applicationId: "com.example.__PROJECT_NAME__",
+	flags: Gio.ApplicationFlags.FLAGS_NONE,
+});
+
+app.connect("activate", (app: Adw.Application) => {
+	const label = new Gtk.Label({ label: "Hello from __PROJECT_NAME__" });
+	const window = new Gtk.ApplicationWindow({ application: app });
+	window.set_title("__PROJECT_NAME__");
+	window.set_default_size(320, 120);
+	window.set_child(label);
+	window.present();
+});
+
+app.run([imports.system.programInvocationName].concat(ARGV));

package/dist-templates/types-gjsify/package.json

@@ -0,0 +1,26 @@
+{
+	"name": "__PROJECT_NAME__",
+	"version": "0.1.0",
+	"type": "module",
+	"private": true,
+	"scripts": {
+		"check": "tsc --noEmit",
+		"build": "gjsify build main.ts --app gjs --outfile dist/main.js",
+		"start": "gjsify run dist/main.js",
+		"format": "gjsify format",
+		"fix": "gjsify fix",
+		"clear": "rm -rf dist"
+	},
+	"devDependencies": {
+		"@biomejs/biome": "^2.4.13",
+		"@gjsify/cli": "^0.4.25",
+		"typescript": "^6.0.2"
+	},
+	"dependencies": {
+		"@girs/adw-1": "^1.10.0-4.0.0-rc.17",
+		"@girs/gio-2.0": "^2.88.0-4.0.1",
+		"@girs/gjs": "^4.0.1",
+		"@girs/glib-2.0": "^2.88.0-4.0.1",
+		"@girs/gtk-4.0": "^4.23.0-4.0.0-rc.17"
+	}
+}

package/dist-templates/types-gjsify/tsconfig.json

@@ -0,0 +1,15 @@
+{
+	"compilerOptions": {
+		"lib": ["ESNext"],
+		"types": ["@girs/gjs", "@girs/adw-1"],
+		"target": "ESNext",
+		"module": "ESNext",
+		"moduleResolution": "bundler",
+		"strict": true,
+		"noImplicitAny": true,
+		"strictNullChecks": true,
+		"noImplicitThis": true,
+		"alwaysStrict": true
+	},
+	"files": ["main.ts"]
+}

package/dist-templates/types-locally/.ts-for-girrc.js

@@ -0,0 +1,6 @@
+export default {
+	modules: ["Adw-1", "Gtk-4.0"],
+	outdir: "./@types",
+	package: false,
+	ignoreVersionConflicts: true,
+};

package/dist-templates/types-locally/README.md

@@ -0,0 +1,15 @@
+# __PROJECT_NAME__
+
+GJS + TypeScript starter that generates GObject Introspection types **locally** into `./@types/`, without using the `@girs/*` NPM packages.
+
+## Setup
+
+```sh
+npm install
+npm run generate     # writes types into ./@types/
+npm run check:types  # tsc --noEmit
+npm run build        # bundles main.ts to dist/ via esbuild
+npm start            # runs dist/main.js with gjs
+```
+
+`@types/index.d.ts` is regenerated each time you run `npm run generate`. Add or remove modules in `.ts-for-girrc.js`.

package/dist-templates/types-locally/esbuild.ts

@@ -0,0 +1,10 @@
+import { build } from "esbuild";
+
+await build({
+	entryPoints: ["main.ts"],
+	outdir: "dist",
+	bundle: true,
+	target: "firefox128",
+	format: "esm",
+	external: ["gi://*", "resource://*", "gettext", "system", "cairo"],
+});

package/dist-templates/types-locally/main.ts

@@ -0,0 +1,21 @@
+/// <reference path="./@types/index.d.ts" />
+
+import Adw from "gi://Adw?version=1";
+import Gio from "gi://Gio?version=2.0";
+import Gtk from "gi://Gtk?version=4.0";
+
+const app = new Adw.Application({
+	applicationId: "com.example.__PROJECT_NAME__",
+	flags: Gio.ApplicationFlags.FLAGS_NONE,
+});
+
+app.connect("activate", (app: Adw.Application) => {
+	const label = new Gtk.Label({ label: "Hello from __PROJECT_NAME__" });
+	const window = new Gtk.ApplicationWindow({ application: app });
+	window.set_title("__PROJECT_NAME__");
+	window.set_default_size(320, 120);
+	window.set_child(label);
+	window.present();
+});
+
+app.run([imports.system.programInvocationName].concat(ARGV));

package/dist-templates/types-locally/package.json

@@ -0,0 +1,18 @@
+{
+	"name": "__PROJECT_NAME__",
+	"version": "0.1.0",
+	"type": "module",
+	"private": true,
+	"scripts": {
+		"generate": "ts-for-gir generate",
+		"check:types": "tsc --noEmit",
+		"build": "node --experimental-strip-types --experimental-transform-types --no-warnings esbuild.ts",
+		"start": "gjs -m dist/main.js",
+		"clear": "rm -rf dist @types"
+	},
+	"devDependencies": {
+		"@ts-for-gir/cli": "^4.0.2",
+		"esbuild": "^0.28.0",
+		"typescript": "^6.0.2"
+	}
+}

package/dist-templates/types-locally/tsconfig.json

@@ -0,0 +1,17 @@
+{
+	"compilerOptions": {
+		"target": "ESNext",
+		"module": "ESNext",
+		"lib": ["ESNext"],
+		"moduleResolution": "bundler",
+		"skipLibCheck": false,
+		"types": [],
+		"strict": true,
+		"noImplicitAny": true,
+		"strictNullChecks": true,
+		"noImplicitThis": true,
+		"alwaysStrict": true
+	},
+	"include": ["main.ts", "@types/index.d.ts"],
+	"exclude": []
+}

package/dist-templates/types-npm/README.md

@@ -0,0 +1,14 @@
+# __PROJECT_NAME__
+
+GJS + TypeScript starter that consumes pre-generated GObject Introspection types from the [`@girs/*`](https://www.npmjs.com/org/girs) NPM packages.
+
+## Setup
+
+```sh
+npm install
+npm run check   # tsc --noEmit
+npm run build   # bundles main.ts to dist/ via esbuild
+npm start       # runs dist/main.js with gjs
+```
+
+To add another GIR module, install the matching `@girs/<name>-<version>` package and add it to `tsconfig.json`'s `types` array.

package/dist-templates/types-npm/esbuild.ts

@@ -0,0 +1,10 @@
+import { build } from "esbuild";
+
+await build({
+	entryPoints: ["main.ts"],
+	outdir: "dist",
+	bundle: true,
+	target: "firefox128",
+	format: "esm",
+	external: ["gi://*", "resource://*", "gettext", "system", "cairo"],
+});

package/dist-templates/types-npm/main.ts

@@ -0,0 +1,19 @@
+import Adw from "gi://Adw?version=1";
+import Gio from "gi://Gio?version=2.0";
+import Gtk from "gi://Gtk?version=4.0";
+
+const app = new Adw.Application({
+	applicationId: "com.example.__PROJECT_NAME__",
+	flags: Gio.ApplicationFlags.FLAGS_NONE,
+});
+
+app.connect("activate", (app: Adw.Application) => {
+	const label = new Gtk.Label({ label: "Hello from __PROJECT_NAME__" });
+	const window = new Gtk.ApplicationWindow({ application: app });
+	window.set_title("__PROJECT_NAME__");
+	window.set_default_size(320, 120);
+	window.set_child(label);
+	window.present();
+});
+
+app.run([imports.system.programInvocationName].concat(ARGV));

package/dist-templates/types-npm/package.json

@@ -0,0 +1,23 @@
+{
+	"name": "__PROJECT_NAME__",
+	"version": "0.1.0",
+	"type": "module",
+	"private": true,
+	"scripts": {
+		"check": "tsc --noEmit",
+		"build": "node --experimental-strip-types --experimental-transform-types --no-warnings esbuild.ts",
+		"start": "gjs -m dist/main.js",
+		"clear": "rm -rf dist"
+	},
+	"devDependencies": {
+		"esbuild": "^0.28.0",
+		"typescript": "^6.0.2"
+	},
+	"dependencies": {
+		"@girs/adw-1": "^1.10.0-4.0.0-rc.17",
+		"@girs/gio-2.0": "^2.88.0-4.0.1",
+		"@girs/gjs": "^4.0.1",
+		"@girs/glib-2.0": "^2.88.0-4.0.1",
+		"@girs/gtk-4.0": "^4.23.0-4.0.0-rc.17"
+	}
+}

package/dist-templates/types-npm/tsconfig.json

@@ -0,0 +1,15 @@
+{
+	"compilerOptions": {
+		"lib": ["ESNext"],
+		"types": ["@girs/gjs", "@girs/adw-1"],
+		"target": "ESNext",
+		"module": "ESNext",
+		"moduleResolution": "bundler",
+		"strict": true,
+		"noImplicitAny": true,
+		"strictNullChecks": true,
+		"noImplicitThis": true,
+		"alwaysStrict": true
+	},
+	"files": ["main.ts"]
+}

package/dist-templates/types-workspace/.ts-for-girrc.js

@@ -0,0 +1,12 @@
+export default {
+	modules: ["Adw-1", "Gtk-4.0"],
+	outdir: "./@girs",
+	package: true,
+	// npm does not support the workspace: protocol. `caret` emits ^<version>
+	// which npm, yarn and pnpm all resolve to the local workspace when the ref
+	// matches, falling back to the registry otherwise — the most portable
+	// default for a generated monorepo. Falls back to "exact" on CLI versions
+	// that predate this option, which is also npm-compatible.
+	depVersionFormat: "caret",
+	ignoreVersionConflicts: true,
+};

package/dist-templates/types-workspace/README.md

@@ -0,0 +1,26 @@
+# __PROJECT_NAME__
+
+GJS + TypeScript starter that uses an **npm workspace** with the `@girs/*` types generated locally as workspace packages. Useful when you want pinned, hermetic types under version control without depending on the published `@girs/*` packages on NPM.
+
+## Setup
+
+```sh
+npm install
+npm run build:types   # generates @girs/* packages into ./@girs/
+npm install           # picks up the freshly generated @girs/* workspace packages
+npm run build:app
+npm start
+```
+
+Or shorthand: `npm run build` runs all three steps in order.
+
+The application lives in [`packages/app/`](./packages/app/). Its dependencies on `@girs/*` are written as `"*"` which works across all three package managers — npm, yarn, pnpm all resolve to the locally generated workspace packages in `./@girs/`.
+
+### About the dependency version format
+
+Two deliberate choices keep the template portable:
+
+1. **Generated `@girs/*` packages** reference each other via `^<version>` (not `workspace:^`). Controlled by `depVersionFormat: "caret"` in [`.ts-for-girrc.js`](./.ts-for-girrc.js). npm and yarn/pnpm all prefer the local workspace match; the registry serves as fallback for transitive GIR packages outside your `modules` set.
+2. **Sub-package deps** (`packages/app/package.json`) use `"*"`. Same reasoning — all managers resolve to the local workspace.
+
+If you run yarn or pnpm exclusively and want strict workspace-only resolution, switch both: add `workspace: true` and `depVersionFormat: "workspace"` in `.ts-for-girrc.js`, plus `"workspace:^"` specs in `packages/app/package.json`. npm does **not** support the `workspace:` protocol.

package/dist-templates/types-workspace/package.json

@@ -0,0 +1,22 @@
+{
+	"name": "__PROJECT_NAME__",
+	"version": "0.1.0",
+	"type": "module",
+	"private": true,
+	"workspaces": [
+		"packages/*",
+		"@girs/*"
+	],
+	"scripts": {
+		"build:types": "ts-for-gir generate --package --outdir=./@girs",
+		"build:app": "npm run --workspace=@__PROJECT_NAME__/app build",
+		"build": "npm run build:types && npm install && npm run build:app",
+		"check": "npm run --workspaces --if-present check",
+		"start": "npm run --workspace=@__PROJECT_NAME__/app start",
+		"clear": "rm -rf @girs packages/*/dist"
+	},
+	"devDependencies": {
+		"@ts-for-gir/cli": "^4.0.2",
+		"typescript": "^6.0.2"
+	}
+}

package/dist-templates/types-workspace/packages/app/esbuild.ts

@@ -0,0 +1,10 @@
+import { build } from "esbuild";
+
+await build({
+	entryPoints: ["main.ts"],
+	outdir: "dist",
+	bundle: true,
+	target: "firefox128",
+	format: "esm",
+	external: ["gi://*", "resource://*", "gettext", "system", "cairo"],
+});

package/dist-templates/types-workspace/packages/app/main.ts

@@ -0,0 +1,19 @@
+import Adw from "gi://Adw?version=1";
+import Gio from "gi://Gio?version=2.0";
+import Gtk from "gi://Gtk?version=4.0";
+
+const app = new Adw.Application({
+	applicationId: "com.example.__PROJECT_NAME__",
+	flags: Gio.ApplicationFlags.FLAGS_NONE,
+});
+
+app.connect("activate", (app: Adw.Application) => {
+	const label = new Gtk.Label({ label: "Hello from __PROJECT_NAME__" });
+	const window = new Gtk.ApplicationWindow({ application: app });
+	window.set_title("__PROJECT_NAME__");
+	window.set_default_size(320, 120);
+	window.set_child(label);
+	window.present();
+});
+
+app.run([imports.system.programInvocationName].concat(ARGV));

package/dist-templates/types-workspace/packages/app/package.json

@@ -0,0 +1,23 @@
+{
+	"name": "@__PROJECT_NAME__/app",
+	"version": "0.1.0",
+	"type": "module",
+	"private": true,
+	"scripts": {
+		"check": "tsc --noEmit",
+		"build": "node --experimental-strip-types --experimental-transform-types --no-warnings esbuild.ts",
+		"start": "gjs -m dist/main.js",
+		"clear": "rm -rf dist"
+	},
+	"devDependencies": {
+		"esbuild": "^0.28.0",
+		"typescript": "^6.0.2"
+	},
+	"dependencies": {
+		"@girs/adw-1": "*",
+		"@girs/gio-2.0": "*",
+		"@girs/gjs": "*",
+		"@girs/glib-2.0": "*",
+		"@girs/gtk-4.0": "*"
+	}
+}

package/dist-templates/types-workspace/packages/app/tsconfig.json

@@ -0,0 +1,15 @@
+{
+	"compilerOptions": {
+		"lib": ["ESNext"],
+		"types": ["@girs/gjs", "@girs/adw-1"],
+		"target": "ESNext",
+		"module": "ESNext",
+		"moduleResolution": "bundler",
+		"strict": true,
+		"noImplicitAny": true,
+		"strictNullChecks": true,
+		"noImplicitThis": true,
+		"alwaysStrict": true
+	},
+	"files": ["main.ts"]
+}

package/dist-templates/types-workspace/tsconfig.json

@@ -0,0 +1,11 @@
+{
+	"compilerOptions": {
+		"lib": ["ESNext"],
+		"target": "ESNext",
+		"module": "ESNext",
+		"moduleResolution": "bundler",
+		"strict": true,
+		"noEmit": true
+	},
+	"references": [{ "path": "./packages/app" }]
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@ts-for-gir/cli",
-	"version": "4.0.0",
+	"version": "4.0.2",
 	"description": "TypeScript type definition generator for GObject introspection GIR files",
 	"main": "src/index.ts",
 	"module": "src/index.ts",
@@ -124,7 +124,7 @@
 	"scripts": {
 		"start": "node bin/ts-for-gir-dev",
 		"start:prod": "node bin/ts-for-gir",
-		"build": "node --experimental-specifier-resolution=node --experimental-strip-types --experimental-transform-types --no-warnings esbuild.ts && chmod +x bin/ts-for-gir-dev && chmod +x bin/ts-for-gir",
+		"build": "node --experimental-specifier-resolution=node --experimental-strip-types --experimental-transform-types --no-warnings esbuild.ts && chmod +x bin/ts-for-gir-dev && chmod +x bin/ts-for-gir && node scripts/process-templates.mjs",
 		"build:gjs": "gjsify build",
 		"build:templates": "node scripts/process-templates.mjs",
 		"prepack": "node scripts/process-templates.mjs",
@@ -164,15 +164,15 @@
 		".": "./src/index.ts"
 	},
 	"devDependencies": {
-		"@gi.ts/parser": "^4.0.0",
-		"@gjsify/cli": "^0.4.19",
-		"@ts-for-gir/generator-base": "^4.0.0",
-		"@ts-for-gir/generator-html-doc": "^4.0.0",
-		"@ts-for-gir/generator-json": "^4.0.0",
-		"@ts-for-gir/generator-typescript": "^4.0.0",
-		"@ts-for-gir/lib": "^4.0.0",
-		"@ts-for-gir/reporter": "^4.0.0",
-		"@ts-for-gir/tsconfig": "^4.0.0",
+		"@gi.ts/parser": "^4.0.2",
+		"@gjsify/cli": "^0.4.25",
+		"@ts-for-gir/generator-base": "^4.0.2",
+		"@ts-for-gir/generator-html-doc": "^4.0.2",
+		"@ts-for-gir/generator-json": "^4.0.2",
+		"@ts-for-gir/generator-typescript": "^4.0.2",
+		"@ts-for-gir/lib": "^4.0.2",
+		"@ts-for-gir/reporter": "^4.0.2",
+		"@ts-for-gir/tsconfig": "^4.0.2",
 		"@types/ejs": "^3.1.5",
 		"@types/inquirer": "^9.0.9",
 		"@types/node": "^25.6.2",
@@ -183,7 +183,7 @@
 	},
 	"dependencies": {
 		"@inquirer/prompts": "^8.4.2",
-		"@ts-for-gir/templates": "^4.0.0",
+		"@ts-for-gir/templates": "^4.0.2",
 		"colorette": "^2.0.20",
 		"cosmiconfig": "^9.0.1",
 		"ejs": "^5.0.2",

package/src/commands/self-update.ts

@@ -17,11 +17,37 @@ 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;
+	// Refuse to update in dev mode — running from a source `.ts` file or
+	// from a project-local `node_modules/` (in which case the user should
+	// update via their package manager, not by replacing the binary in
+	// place).
+	if (p.endsWith(".ts")) return null;
+	if (p.includes("/node_modules/") && !isGjsifyGlobalLocation(p)) return null;
 	return p;
 }
 
+/**
+ * Recognise the gjsify-install global location (`~/.local/share/gjsify/global/
+ * node_modules/<pkg>/...`, set up by `gjsify install -g` and `install.js`).
+ *
+ * The previous broad `path.includes("node_modules")` check rejected this
+ * location alongside genuine project-local installs, even though the
+ * gjsify-global location IS the canonical install spot for `ts-for-gir
+ * self-update`. The fix: only refuse updates for paths that contain
+ * `node_modules` AND aren't under the gjsify-global root.
+ *
+ * Matches both XDG_DATA_HOME-rooted and the documented fallback
+ * (`$HOME/.local/share/gjsify/global/`).
+ */
+function isGjsifyGlobalLocation(p: string): boolean {
+	const xdgData = process.env.XDG_DATA_HOME;
+	const home = process.env.HOME;
+	const candidates: string[] = [];
+	if (xdgData) candidates.push(`${xdgData}/gjsify/global/`);
+	if (home) candidates.push(`${home}/.local/share/gjsify/global/`);
+	return candidates.some((root) => p.startsWith(root));
+}
+
 async function fetchJson(url: string): Promise<unknown> {
 	const headers: Record<string, string> = {
 		Accept: "application/vnd.github.v3+json",