@vue-godot/cli 0.0.1

package/README.md

@@ -0,0 +1,112 @@
+# @vue-godot/cli
+
+CLI tool for vue-godot projects — scaffolds new projects, integrates Vue into existing Godot projects, and generates type declarations.
+
+## Installation
+
+```bash
+npm install -D @vue-godot/cli
+```
+
+Or run directly with `npx`:
+
+```bash
+npx vue-godot <command> [options]
+```
+
+## Commands
+
+### `create`
+
+Create a new Godot project with vue-godot set up and ready to go.
+
+```bash
+vue-godot create [name] [options]
+```
+
+| Argument | Description                                           |
+| -------- | ----------------------------------------------------- |
+| `name`   | Project name (used as dir name). Prompted if omitted. |
+
+| Option | Description                                 |
+| ------ | ------------------------------------------- |
+| `-f`   | Force overwrite if directory already exists |
+
+**Example:**
+
+```bash
+npx vue-godot create my-game
+cd my-game
+npm install
+npm run build
+```
+
+### `integrate`
+
+Scaffold a `vue/` folder with Vite + Vue configuration for an existing Godot project.
+
+```bash
+vue-godot integrate [dir] [options]
+```
+
+| Argument | Description                        |
+| -------- | ---------------------------------- |
+| `dir`    | Target directory (defaults to `.`) |
+
+| Option | Description                              |
+| ------ | ---------------------------------------- |
+| `-f`   | Force overwrite if `vue/` already exists |
+
+This command:
+
+1. Copies a Vue + Vite template into `<dir>/vue/`
+2. Creates or updates `package.json` with the necessary scripts and dependencies
+3. Resolves `node_modules` paths for the generated `tsconfig.json`
+
+**Example:**
+
+```bash
+cd my-existing-godot-project
+npx vue-godot integrate
+npm install
+npm run gen:types
+npm run dev
+```
+
+### `gen-types`
+
+Generate Vue `GlobalComponents` type augmentation from GodotJS typings. This gives Volar full autocomplete and type checking for Godot node tags (e.g. `<Button>`, `<Label>`) in `.vue` templates.
+
+```bash
+vue-godot gen-types [options]
+```
+
+| Option       | Default                                   | Description                                        |
+| ------------ | ----------------------------------------- | -------------------------------------------------- |
+| `--typings`  | `./typings`                               | Directory containing `godot*.gen.d.ts` files       |
+| `--out`      | `<typings>/godot.vue-components.gen.d.ts` | Output file path for the generated `.d.ts`         |
+| `--ancestor` | `Control`                                 | Base class — only descendants are included         |
+| `--vue-src`  | `./vue/src`                               | Vue source dir — generates an `env.d.ts` shim here |
+
+**Example:**
+
+```bash
+cd apps/v-model
+npx vue-godot gen-types
+```
+
+Re-run whenever Godot typings are regenerated (e.g. after a Godot version upgrade).
+
+## Development (monorepo)
+
+From the repository root:
+
+```bash
+npm install
+npm run build        # builds all packages via Turborepo
+npx vue-godot        # runs the locally-built CLI
+```
+
+## License
+
+MIT

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,188 @@
+#!/usr/bin/env node
+import * as path from 'node:path';
+import * as readline from 'node:readline/promises';
+import { create } from './create.js';
+import { generate } from './index.js';
+import { integrate } from './integrate.js';
+const args = process.argv.slice(2);
+const command = args[0];
+function mainUsage() {
+    console.error(`Usage: vue-godot <command> [options]
+
+Commands:
+  create      Create a new Godot project with vue-godot set up and ready to go
+  integrate   Scaffold a vue/ folder with Vite + Vue configs for an existing Godot project
+  gen-types   Generate Vue GlobalComponents type augmentation from Godot typings
+
+Run \`vue-godot <command> --help\` for command-specific options.
+`);
+    process.exit(1);
+}
+function genTypesUsage() {
+    console.error(`Usage: vue-godot gen-types [options]
+
+Generate Vue GlobalComponents type augmentation from GodotJS typings.
+
+Options:
+  --typings   Path to the typings directory containing godot*.gen.d.ts files.
+              Defaults to ./typings
+  --out       Output file path for the generated .d.ts file.
+              Defaults to <typings>/godot.vue-components.gen.d.ts
+  --ancestor  Base class to filter by inheritance. Only descendants are included.
+              Defaults to Control
+  --vue-src   Path to the Vue source directory (e.g. vue/src).
+              When set, generates an env.d.ts shim for Vue SFC support.
+              Defaults to ./vue/src
+`);
+    process.exit(1);
+}
+function parseGenTypesArgs(argv) {
+    let typingsDir;
+    let outFile;
+    let ancestor;
+    let vueSrcDir;
+    for (let i = 0; i < argv.length; i++) {
+        switch (argv[i]) {
+            case '--typings':
+                typingsDir = argv[++i];
+                break;
+            case '--out':
+                outFile = argv[++i];
+                break;
+            case '--ancestor':
+                ancestor = argv[++i];
+                break;
+            case '--vue-src':
+                vueSrcDir = argv[++i];
+                break;
+            case '--help':
+            case '-h':
+                genTypesUsage();
+            default:
+                console.error(`Unknown option: ${argv[i]}`);
+                genTypesUsage();
+        }
+    }
+    return { typingsDir, outFile, ancestor, vueSrcDir };
+}
+function createUsage() {
+    console.error(`Usage: vue-godot create [name] [options]
+
+Create a new Godot project with vue-godot set up and ready to go.
+If no name is given you will be prompted for one.
+
+Arguments:
+  name        Project name (used as directory name)
+
+Options:
+  -f          Force overwrite if directory already exists
+`);
+    process.exit(1);
+}
+function parseCreateArgs(argv) {
+    let projectName;
+    let force = false;
+    for (let i = 0; i < argv.length; i++) {
+        switch (argv[i]) {
+            case '-f':
+                force = true;
+                break;
+            case '--help':
+            case '-h':
+                createUsage();
+            default:
+                if (argv[i].startsWith('-')) {
+                    console.error(`Unknown option: ${argv[i]}`);
+                    createUsage();
+                }
+                if (!projectName) {
+                    projectName = argv[i];
+                }
+                else {
+                    console.error(`Unexpected argument: ${argv[i]}`);
+                    createUsage();
+                }
+        }
+    }
+    return { projectName, force };
+}
+function integrateUsage() {
+    console.error(`Usage: vue-godot integrate [dir] [options]
+
+Scaffold a vue/ folder with Vite + Vue configuration for a Godot project.
+
+Arguments:
+  dir         Target directory (defaults to the current directory)
+
+Options:
+  -f          Force overwrite if vue/ already exists (no prompt)
+`);
+    process.exit(1);
+}
+function parseIntegrateArgs(argv) {
+    let targetDir;
+    let force = false;
+    for (let i = 0; i < argv.length; i++) {
+        switch (argv[i]) {
+            case '-f':
+                force = true;
+                break;
+            case '--help':
+            case '-h':
+                integrateUsage();
+            default:
+                if (argv[i].startsWith('-')) {
+                    console.error(`Unknown option: ${argv[i]}`);
+                    integrateUsage();
+                }
+                if (!targetDir) {
+                    targetDir = argv[i];
+                }
+                else {
+                    console.error(`Unexpected argument: ${argv[i]}`);
+                    integrateUsage();
+                }
+        }
+    }
+    return { targetDir: targetDir ?? '.', force };
+}
+if (!command || command === '--help' || command === '-h') {
+    mainUsage();
+}
+switch (command) {
+    case 'create': {
+        const parsed = parseCreateArgs(args.slice(1));
+        let { projectName } = parsed;
+        if (!projectName) {
+            const rl = readline.createInterface({
+                input: process.stdin,
+                output: process.stdout,
+            });
+            projectName = (await rl.question('Project name: ')).trim();
+            rl.close();
+            if (!projectName) {
+                console.error('Project name is required.');
+                process.exit(1);
+            }
+        }
+        await create({ projectName, force: parsed.force });
+        break;
+    }
+    case 'gen-types': {
+        const parsed = parseGenTypesArgs(args.slice(1));
+        const typingsDir = path.resolve(parsed.typingsDir ?? './typings');
+        const outFile = path.resolve(parsed.outFile ?? path.join(typingsDir, 'godot.vue-components.gen.d.ts'));
+        const ancestor = parsed.ancestor ?? 'Control';
+        const vueSrcDir = path.resolve(parsed.vueSrcDir ?? './vue/src');
+        generate({ typingsDir, outFile, ancestor, vueSrcDir });
+        break;
+    }
+    case 'integrate': {
+        const parsed = parseIntegrateArgs(args.slice(1));
+        await integrate(parsed);
+        break;
+    }
+    default:
+        console.error(`Unknown command: ${command}`);
+        mainUsage();
+}

package/dist/create.d.ts

@@ -0,0 +1,5 @@
+export interface CreateOptions {
+    projectName: string;
+    force: boolean;
+}
+export declare function create(options: CreateOptions): Promise<void>;

package/dist/create.js

@@ -0,0 +1,77 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { spawn } from 'node:child_process';
+import { copyTemplateDir, getTemplatesDir, newPackageJson } from './integrate.js';
+function runCommand(command, args, cwd) {
+    return new Promise((resolve, reject) => {
+        const child = spawn(command, args, {
+            cwd,
+            stdio: 'inherit',
+            shell: false,
+        });
+        child.on('error', reject);
+        child.on('close', (code) => {
+            if (code === 0) {
+                resolve();
+                return;
+            }
+            reject(new Error(`Command failed (${code ?? 'unknown'}): ${command} ${args.join(' ')}`));
+        });
+    });
+}
+export async function create(options) {
+    const { projectName, force } = options;
+    const absTarget = path.resolve(projectName);
+    const packageName = path.basename(absTarget);
+    /* --- guard: directory already exists --- */
+    if (fs.existsSync(absTarget)) {
+        if (!force) {
+            console.error(`Directory "${absTarget}" already exists. Use -f to overwrite.`);
+            process.exit(1);
+        }
+        fs.rmSync(absTarget, { recursive: true });
+    }
+    fs.mkdirSync(absTarget, { recursive: true });
+    const templatesDir = getTemplatesDir();
+    /* --- copy Godot project template --- */
+    const godotTplDir = path.join(templatesDir, 'godot');
+    if (!fs.existsSync(godotTplDir)) {
+        console.error(`Template directory not found: ${godotTplDir}\nThe CLI package may not be installed correctly.`);
+        process.exit(1);
+    }
+    copyTemplateDir(godotTplDir, absTarget, { '{{PROJECT_NAME}}': projectName }, process.cwd());
+    /* --- copy Vue template --- */
+    const vueTplDir = path.join(templatesDir, 'vue');
+    const vueDir = path.join(absTarget, 'vue');
+    if (!fs.existsSync(vueTplDir)) {
+        console.error(`Template directory not found: ${vueTplDir}\nThe CLI package may not be installed correctly.`);
+        process.exit(1);
+    }
+    // node_modules will live in the project root after npm install
+    const nodeModulesRelPath = '../node_modules';
+    copyTemplateDir(vueTplDir, vueDir, { '{{NODE_MODULES}}': nodeModulesRelPath }, process.cwd());
+    /* --- package.json --- */
+    const typingsTplDir = path.join(templatesDir, 'typings');
+    const typingsDir = path.join(absTarget, 'typings');
+    if (!fs.existsSync(typingsTplDir)) {
+        console.error(`Template directory not found: ${typingsTplDir}\nThe CLI package may not be installed correctly.`);
+        process.exit(1);
+    }
+    copyTemplateDir(typingsTplDir, typingsDir, {}, process.cwd());
+    const pkgJsonPath = path.join(absTarget, 'package.json');
+    fs.writeFileSync(pkgJsonPath, JSON.stringify(newPackageJson(packageName), null, 2) + '\n');
+    console.log(`  created ${path.relative(process.cwd(), pkgJsonPath)}`);
+    const npmCmd = process.platform === 'win32' ? 'npm.cmd' : 'npm';
+    console.log(`\nRunning project setup...`);
+    console.log(`  npm install`);
+    await runCommand(npmCmd, ['install'], absTarget);
+    console.log(`  npm run gen:types`);
+    await runCommand(npmCmd, ['run', 'gen:types'], absTarget);
+    console.log(`\n✔ Project "${packageName}" created at ${path.relative(process.cwd(), absTarget)}`);
+    console.log(`\nCompleted setup:`);
+    console.log(`  cd ${projectName}`);
+    console.log(`  npm install        (executed)`);
+    console.log(`  npm run gen:types  (executed)`);
+    console.log(`  npm run dev          # rebuilds on change; Godot hot-reloads dist/app.js`);
+    console.log(`  # Open the project in Godot and hit Play`);
+}

package/dist/index.d.ts

@@ -0,0 +1,29 @@
+export interface GenerateOptions {
+    /** Directory containing godot*.gen.d.ts files */
+    typingsDir: string;
+    /** Output file path for the generated .d.ts */
+    outFile: string;
+    /**
+     * Base class name to filter by inheritance.
+     * Only classes derived from this ancestor will be included.
+     * @default 'Control'
+     */
+    ancestor?: string;
+    /**
+     * Directory containing Vue source files (e.g. `vue/src`).
+     * When set, an `env.d.ts` shim will be generated there.
+     */
+    vueSrcDir?: string;
+}
+/**
+ * Generate the `declare module "@vue/runtime-core"` augmentation source text.
+ */
+export declare function generateSource(options: GenerateOptions): string;
+/**
+ * Generate the Vue env.d.ts shim source text.
+ */
+export declare function generateEnvDtsSource(): string;
+/**
+ * Generate and write the augmentation file (and optionally env.d.ts).
+ */
+export declare function generate(options: GenerateOptions): void;

package/dist/index.js

@@ -0,0 +1,129 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+/**
+ * Parse all `class Foo<…> extends Bar<…>` declarations from godot*.gen.d.ts
+ * and build a { className → parentClassName } map.
+ */
+function parseClassHierarchy(typingsDir) {
+    const classes = new Map();
+    const files = fs
+        .readdirSync(typingsDir)
+        .filter((f) => /^godot\d*\.gen\.d\.ts$/.test(f) || f === 'godot.mix.d.ts');
+    for (const file of files.sort()) {
+        const content = fs.readFileSync(path.join(typingsDir, file), 'utf-8');
+        const re = /class\s+(\w+)\s*<.*?>\s+extends\s+(\w+)/g;
+        let m;
+        while ((m = re.exec(content)) !== null) {
+            classes.set(m[1], m[2]);
+        }
+    }
+    return classes;
+}
+/**
+ * Walk the inheritance chain of `cls` and return all ancestor class names.
+ */
+function getAncestors(cls, classes) {
+    const chain = [];
+    const visited = new Set();
+    let current = cls;
+    while (classes.has(current) && !visited.has(current)) {
+        visited.add(current);
+        const parent = classes.get(current);
+        chain.push(parent);
+        current = parent;
+    }
+    return chain;
+}
+/**
+ * Return all class names that inherit (directly or transitively) from `ancestor`,
+ * plus the ancestor itself.
+ */
+function getDescendants(classes, ancestor) {
+    const result = [];
+    for (const cls of classes.keys()) {
+        if (cls === ancestor || getAncestors(cls, classes).includes(ancestor)) {
+            result.push(cls);
+        }
+    }
+    return result.sort();
+}
+/**
+ * Generate the `declare module "@vue/runtime-core"` augmentation source text.
+ */
+export function generateSource(options) {
+    const { typingsDir, ancestor = 'Control' } = options;
+    const classes = parseClassHierarchy(typingsDir);
+    const nodes = getDescendants(classes, ancestor);
+    const lines = [
+        '// AUTO-GENERATED by @vue-godot/cli — do not edit manually',
+        '// Augments @vue/runtime-core GlobalComponents so Volar provides',
+        '// typed props when using Godot nodes in Vue templates.',
+        '',
+        'import type { AllowedComponentProps, VNodeProps } from "@vue/runtime-core"',
+        '',
+        '/**',
+        ' * Extracts settable (non-method) instance properties from a Godot node class.',
+        ' * All keys become optional since props are optional in Vue templates.',
+        ' */',
+        'type GodotProps<T> = {',
+        '  [K in keyof T as T[K] extends (...args: any[]) => any ? never : K]?: T[K]',
+        '}',
+        '',
+        'type VueGodotComponentProps<T> = GodotProps<T> & AllowedComponentProps & VNodeProps',
+        '',
+        'declare module "@vue/runtime-core" {',
+        '  interface GlobalComponents {',
+    ];
+    for (const node of nodes) {
+        lines.push(`    ${node}: new () => { $props: VueGodotComponentProps<import("godot").${node}> }`);
+    }
+    lines.push('  }', '}', '', 'declare module "vue" {', '  export interface GlobalComponents {');
+    for (const node of nodes) {
+        lines.push(`    ${node}: new () => { $props: VueGodotComponentProps<import("godot").${node}> }`);
+    }
+    lines.push('  }', '}', '');
+    return lines.join('\n');
+}
+/**
+ * Generate the Vue env.d.ts shim source text.
+ */
+export function generateEnvDtsSource() {
+    return [
+        '// AUTO-GENERATED by @vue-godot/cli — do not edit manually',
+        '/// <reference types="vite/client" />',
+        '',
+        "declare module '*.vue' {",
+        "  import type { DefineComponent } from '@vue/runtime-core'",
+        '  const component: DefineComponent<{}, {}, any>',
+        '  export default component',
+        '}',
+        '',
+    ].join('\n');
+}
+/**
+ * Generate and write the augmentation file (and optionally env.d.ts).
+ */
+export function generate(options) {
+    const source = generateSource(options);
+    const outDir = path.dirname(options.outFile);
+    if (!fs.existsSync(outDir)) {
+        fs.mkdirSync(outDir, { recursive: true });
+    }
+    fs.writeFileSync(options.outFile, source, 'utf-8');
+    // Count unique components (the source augments both "@vue/runtime-core" and "vue")
+    const count = new Set(source
+        .split('\n')
+        .map((l) => l.match(/^\s{4}(\w+):/))
+        .filter((m) => m !== null)
+        .map((m) => m[1])).size;
+    console.log(`@vue-godot/cli: wrote ${count} ${options.ancestor ?? 'Control'}-derived component types → ${options.outFile}`);
+    // Generate env.d.ts shim for Vue SFC support
+    if (options.vueSrcDir) {
+        const envFile = path.join(options.vueSrcDir, 'env.d.ts');
+        if (!fs.existsSync(options.vueSrcDir)) {
+            fs.mkdirSync(options.vueSrcDir, { recursive: true });
+        }
+        fs.writeFileSync(envFile, generateEnvDtsSource(), 'utf-8');
+        console.log(`@vue-godot/cli: wrote env.d.ts → ${envFile}`);
+    }
+}

package/dist/integrate.d.ts

@@ -0,0 +1,13 @@
+export interface IntegrateOptions {
+    targetDir: string;
+    force: boolean;
+}
+/** Resolve the bundled templates/ directory (lives next to dist/). */
+export declare function getTemplatesDir(): string;
+/**
+ * Recursively copy a directory, applying placeholder replacements to every
+ * text file. Binary files are copied as-is.
+ */
+export declare function copyTemplateDir(srcDir: string, destDir: string, replacements: Record<string, string>, cwd: string): void;
+export declare function newPackageJson(name: string): Record<string, unknown>;
+export declare function integrate(options: IntegrateOptions): Promise<void>;