@gasboost/vite 0.1.0

package/README.md

@@ -0,0 +1,332 @@
+# @gasboost/vite
+
+`@gasboost/app` で構築したアプリケーションを Google Apps Script 向けにビルドするための Vite プラグインです。
+
+アプリケーションの entry file を静的解析し、`AppsScript` に登録されたハンドラを検出して、Google Apps Script が認識するためのグローバル関数宣言を生成します。
+
+## インストール
+
+```bash
+pnpm add @gasboost/app
+pnpm add -D @gasboost/vite vite
+```
+
+npm:
+
+```bash
+npm install @gasboost/app
+npm install -D @gasboost/vite vite
+```
+
+## 使い方
+
+まず通常の Gasboost アプリケーションを作成します。
+
+```ts
+// src/main.ts
+
+import { AppsScript } from "@gasboost/app";
+
+const app = new AppsScript()
+  .get((request) => {
+    return HtmlService.createHtmlOutput("Hello");
+  })
+  .post((request) => {
+    return ContentService.createTextOutput(request.text());
+  })
+  .call("sum", (a: number, b: number) => a + b);
+
+export default app;
+```
+
+Vite を設定します。
+
+```ts
+// vite.config.ts
+
+import { defineConfig } from "vite";
+import { gasboost } from "@gasboost/vite";
+
+export default defineConfig({
+  plugins: [
+    gasboost({
+      entry: "src/main.ts",
+    }),
+  ],
+});
+```
+
+通常通りビルドできます。
+
+```bash
+vite build
+```
+
+## オプション
+
+### `entry`
+
+必須です。
+
+`AppsScript` アプリケーションを定義している entry file のパスを指定します。
+
+```ts
+gasboost({
+  entry: "src/main.ts",
+});
+```
+
+entry file には1つの `AppsScript` インスタンスを定義し、そのインスタンスを default export する必要があります。
+
+```ts
+const app = new AppsScript();
+
+export default app;
+```
+
+チェーン形式の登録に対応しています。
+
+```ts
+const app = new AppsScript()
+  .get(...)
+  .post(...)
+  .call("getUser", ...);
+
+export default app;
+```
+
+インスタンス生成後に登録する形式にも対応しています。
+
+```ts
+const app = new AppsScript();
+
+app.get(...);
+app.call("getUser", ...);
+
+export default app;
+```
+
+### `envDir`
+
+任意です。
+
+Vite が環境変数ファイルを読み込むディレクトリを指定します。
+
+```ts
+gasboost({
+  entry: "src/main.ts",
+  envDir: "config",
+});
+```
+
+例えば以下の構成を利用できます。
+
+```text
+config/
+├── .env
+├── .env.development
+└── .env.production
+```
+
+## 生成されるグローバル関数
+
+Google Apps Script はトップレベルのグローバル関数を entry point として認識します。
+
+例えば次のアプリケーションを定義した場合:
+
+```ts
+const app = new AppsScript()
+  .get(...)
+  .post(...)
+  .call("getUser", ...)
+  .call("sum", ...);
+
+export default app;
+```
+
+ビルド結果には以下に対応するグローバル関数宣言が生成されます。
+
+```js
+function doGet() {}
+function doPost() {}
+function getUser() {}
+function sum() {}
+```
+
+これらの宣言は Google Apps Script に関数名を認識させるためのものです。
+
+実際の dispatch 処理は行いません。
+
+ハンドラの実体は `@gasboost/app` がランタイム上で登録します。
+
+責務は次のように分離されています。
+
+```text
+@gasboost/app
+  runtime registration
+  handler dispatch
+  globalThis implementation
+
+@gasboost/vite
+  static analysis
+  GAS build configuration
+  global function declarations
+```
+
+## 静的解析
+
+プラグインは指定された entry file を静的解析します。
+
+対象となる `AppsScript` インスタンスに対する登録を検出します。
+
+```ts
+app.get(...);
+app.post(...);
+app.call("getUser", ...);
+```
+
+別オブジェクトの同名メソッドは無視されます。
+
+```ts
+other.get(...);
+other.call("something", ...);
+```
+
+### RPC 名
+
+RPC 名は文字列リテラルで指定する必要があります。
+
+対応:
+
+```ts
+app.call("getUser", handler);
+```
+
+非対応:
+
+```ts
+const name = "getUser";
+
+app.call(name, handler);
+```
+
+ビルド時に生成する GAS グローバル関数名を静的に確定するため、この制約があります。
+
+### 重複登録
+
+以下の曖昧な登録はエラーになります。
+
+- GET ハンドラの重複
+- POST ハンドラの重複
+- RPC 名の重複
+- entry 内に複数の `AppsScript` インスタンスが存在する場合
+
+`AppsScript` インスタンスは default export されている必要があります。
+
+## GAS 向けビルド設定
+
+`gasboost()` が Google Apps Script 向けの Vite build configuration を提供します。
+
+現在は以下の設定を利用します。
+
+- target: ECMAScript 2019
+- output format: CommonJS
+- output directory: `dist`
+- `entry` で指定されたファイルを build input として利用
+
+利用側の Vite config で GAS 固有の build setting を重複して定義する必要はありません。
+
+## 環境変数
+
+環境変数は Vite 標準の仕組みを利用します。
+
+例えば:
+
+```text
+config/.env
+```
+
+```env
+VITE_API_URL=https://example.com
+```
+
+`envDir` を設定します。
+
+```ts
+gasboost({
+  entry: "src/main.ts",
+  envDir: "config",
+});
+```
+
+アプリケーションから通常通り参照できます。
+
+```ts
+const apiUrl = import.meta.env.VITE_API_URL;
+```
+
+mode ごとの環境変数ファイルにも対応します。
+
+```bash
+vite build --mode production
+```
+
+`envDir: "config"` の場合、例えば以下が読み込まれます。
+
+```text
+config/.env.production
+```
+
+## 責務
+
+`@gasboost/vite` はビルド時の処理のみを担当します。
+
+主な責務:
+
+- `AppsScript` 登録内容の静的解析
+- Google Apps Script 向け Vite configuration
+- GAS グローバル関数宣言の生成
+- Vite 環境変数との統合
+
+以下は担当しません。
+
+- GET ハンドラの実行
+- POST ハンドラの実行
+- RPC dispatch
+- ハンドラ実体のランタイム登録
+- Google Apps Script API 自体の抽象化
+
+これらの runtime responsibility は `@gasboost/app` が担当します。
+
+## 現在の制約
+
+Analyzer は、意図的にシンプルな entry file 構造のみを対象としています。
+
+以下のような alias を介した default export は現在対象外です。
+
+```ts
+const app = new AppsScript();
+const exported = app;
+
+export default exported;
+```
+
+別関数の内部に登録処理を隠す形式も対象外です。
+
+```ts
+registerHandlers(app);
+```
+
+別ファイルに登録処理を分散する形式も現在対象外です。
+
+```ts
+import { registerHandlers } from "./handlers";
+
+registerHandlers(app);
+```
+
+登録内容を entry file から静的に確定できるようにすることで、生成する GAS グローバル関数を決定的にしています。
+
+## 関連パッケージ
+
+アプリケーションの runtime と handler registration には `@gasboost/app` を利用してください。

package/dist/analyzer.d.ts

@@ -0,0 +1,6 @@
+export interface AppsScriptAnalysis {
+    hasGet: boolean;
+    hasPost: boolean;
+    calls: string[];
+}
+export declare function analyzeAppsScript(entry: string): AppsScriptAnalysis;

package/dist/config.d.ts

@@ -0,0 +1,3 @@
+import type { UserConfig } from "vite";
+import type { GasboostOptions } from "./gasboost";
+export declare function createGasboostConfig(options: GasboostOptions): UserConfig;

package/dist/gasboost.d.ts

@@ -0,0 +1,6 @@
+import type { Plugin } from "vite";
+export interface GasboostOptions {
+    entry: string;
+    envDir?: string;
+}
+export declare function gasboost(options: GasboostOptions): Plugin;

package/dist/globals.d.ts

@@ -0,0 +1,2 @@
+import type { AppsScriptAnalysis } from "./analyzer";
+export declare function createGlobalCode(analysis: AppsScriptAnalysis): string;

package/dist/index.d.ts

@@ -0,0 +1 @@
+export { gasboost, type GasboostOptions } from "./gasboost";

package/dist/index.js

@@ -0,0 +1,135 @@
+import e from "node:fs";
+import t from "node:path";
+import { isCallExpression as n, isIdentifier as r, isNewExpression as i, isPropertyAccessExpression as a, isStringLiteral as o, isVariableDeclaration as s } from "typescript/unstable/ast/is";
+import { createVirtualFileSystem as c } from "typescript/unstable/fs";
+import { API as l } from "typescript/unstable/sync";
+//#region src/analyzer.ts
+function u(r) {
+	let i = t.resolve(r);
+	if (!e.existsSync(i)) throw Error(`Entry file not found: ${i}`);
+	let s = d(i, e.readFileSync(i, "utf8")), c = f(s);
+	if (c.length === 0) throw Error("AppsScript instance not found.");
+	if (c.length > 1) throw Error("Multiple AppsScript instances found in entry.");
+	let l = c[0];
+	g(s, l);
+	let u = {
+		hasGet: !1,
+		hasPost: !1,
+		calls: []
+	}, p = /* @__PURE__ */ new Set();
+	function m(e) {
+		if (!a(e.expression)) return;
+		let t = e.expression, n = t.name.text;
+		if (!h(t.expression, l)) return;
+		if (n === "get") {
+			if (u.hasGet) throw Error("Duplicate GET handler registration.");
+			u.hasGet = !0;
+			return;
+		}
+		if (n === "post") {
+			if (u.hasPost) throw Error("Duplicate POST handler registration.");
+			u.hasPost = !0;
+			return;
+		}
+		if (n !== "call") return;
+		let r = e.arguments[0];
+		if (!r) throw Error(".call() requires a function name.");
+		if (!o(r)) throw Error(".call() function name must be a string literal.");
+		if (p.has(r.text)) throw Error(`Duplicate RPC registration: "${r.text}".`);
+		p.add(r.text), u.calls.unshift(r.text);
+	}
+	function _(e) {
+		n(e) && m(e), e.forEachChild(_);
+	}
+	return _(s), u;
+}
+function d(e, t) {
+	let n = "/entry.ts", r = "/tsconfig.json", i = c({
+		[r]: JSON.stringify({ files: [n] }),
+		[n]: t
+	}), a = new l({
+		cwd: "/",
+		fs: i
+	}).updateSnapshot({ openProject: r }).getProject(r);
+	if (!a) throw Error("Failed to create TypeScript project.");
+	let o = a.program.getSourceFile(n);
+	if (!o) throw Error(`Failed to parse entry: ${e}`);
+	return o;
+}
+function f(e) {
+	let t = [];
+	function n(e) {
+		s(e) && p(e) && t.push(e.name.text), e.forEachChild(n);
+	}
+	return n(e), t;
+}
+function p(e) {
+	return !r(e.name) || !e.initializer ? !1 : m(e.initializer);
+}
+function m(e) {
+	return i(e) && r(e.expression) && e.expression.text === "AppsScript" ? !0 : n(e) && a(e.expression) ? m(e.expression.expression) : !1;
+}
+function h(e, t) {
+	return r(e) && e.text === t || i(e) && r(e.expression) && e.expression.text === "AppsScript" ? !0 : n(e) && a(e.expression) ? h(e.expression.expression, t) : !1;
+}
+function g(e, t) {
+	let n = !1;
+	for (let r of e.statements) if (r.getText() === `export default ${t};`) {
+		n = !0;
+		break;
+	}
+	if (!n) throw Error("AppsScript instance must be default exported.");
+}
+//#endregion
+//#region src/config.ts
+function _(e) {
+	let n = t.resolve(e.entry);
+	return {
+		envDir: e.envDir,
+		build: {
+			target: "es2019",
+			outDir: "dist",
+			emptyOutDir: !1,
+			rollupOptions: {
+				input: n,
+				output: {
+					format: "cjs",
+					entryFileNames: t.basename(n, t.extname(n)) + ".js"
+				}
+			}
+		}
+	};
+}
+//#endregion
+//#region src/globals.ts
+var v = /* @__PURE__ */ new Set(["doGet", "doPost"]);
+function y(e) {
+	if (v.has(e)) throw Error(`RPC name "${e}" is reserved by Google Apps Script.`);
+	if (!/^[$A-Z_a-z][$\w]*$/u.test(e)) throw Error(`RPC name "${e}" is not a valid JavaScript identifier.`);
+}
+function b(e) {
+	let t = [];
+	e.hasGet && t.push("function doGet() {}"), e.hasPost && t.push("function doPost() {}");
+	for (let n of e.calls) y(n), t.push(`function ${n}() {}`);
+	return t.join("\n");
+}
+//#endregion
+//#region src/gasboost.ts
+function x(e) {
+	let t;
+	return {
+		name: "gasboost",
+		config() {
+			return _(e);
+		},
+		buildStart() {
+			t = u(e.entry);
+		},
+		generateBundle(e, n) {
+			let r = b(t);
+			for (let e of Object.values(n)) e.type === "chunk" && e.isEntry && (e.code = `${r}\n\n${e.code}`);
+		}
+	};
+}
+//#endregion
+export { x as gasboost };

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@gasboost/vite",
+  "version": "0.1.0",
+  "description": "A Vite plugin for building @gasboost/app applications for Google Apps Script.",
+  "keywords": [
+    "google-apps-script",
+    "gas",
+    "vite",
+    "typescript",
+    "plugin",
+    "build",
+    "bundler",
+    "serverless",
+    "gasboost"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/gasboost/app.git",
+    "directory": "packages/vite"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "default": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "type": "module",
+  "devDependencies": {
+    "vite": "^8.2.2"
+  },
+  "dependencies": {
+    "typescript": "^7.0.2"
+  },
+  "scripts": {
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run",
+    "build": "rm -rf dist && vite build --config vite.package.config.ts && tsc -p tsconfig.build.json"
+  }
+}