feat: Tolgee Apps PoC

.claude/tolgee/.github-username

@@ -0,0 +1 @@
+jancizmar

.gitignore

@@ -90,6 +90,9 @@ ngrok.local.yml
 # Worktree
 /worktree-env.sh
 
+# Workspace package node_modules (apps/*, apps/example-apps/*)
+**/node_modules/
+
 # mcp-publisher auth tokens
 /.mcpregistry_github_token
 /.mcpregistry_registry_token

apps/README.md

@@ -0,0 +1,15 @@
+# apps/
+
+Code related to the Tolgee Apps plugin system lives here.
+
+## Layout
+
+- `tolgee-apps-sdk/` — the SDK package that plugin authors install
+  (`@tolgee/apps-sdk`). Currently a skeleton; will hold the typed
+  postMessage handshake, manifest schema, webhook signature verifier,
+  and JWT context helpers. To be published from this directory once
+  the contract stabilises.
+- `example-apps/` — runnable example plugins built against the SDK.
+  - `dev-plugin/` — the in-tree reference plugin used during PoC
+    development. Demonstrates every module type and serves as the
+    template `create-tolgee-app` will copy from.

apps/create-tolgee-app/.gitignore

@@ -0,0 +1 @@
+dist

apps/create-tolgee-app/README.md

@@ -0,0 +1,77 @@
+# create-tolgee-app
+
+Scaffolds a new Tolgee Apps plugin with a working dev environment in one
+command.
+
+> **Status: PoC**. Not yet published. The generated project resolves
+> `@tolgee/apps-sdk` via npm workspaces, so today the generator only
+> works when invoked inside this repo. Run it under `apps/example-apps/`
+> and the SDK symlink will pick up automatically.
+
+## What you get
+
+A project pre-wired with:
+
+- **Vite + React + TypeScript** for iframe modules
+- **Express + tsx watch** for the webhook + decorator + manifest server
+- **Cloudflare quick tunnel** (`scripts/dev.ts`) that boots on `npm run dev`,
+  captures a `*.trycloudflare.com` URL, and PATCHes your Tolgee install
+  so iframe loads and webhook deliveries reach the local services
+- A `manifest.template.json` whose base URL is substituted at request time —
+  no manual editing on every restart
+- **`@tolgee/apps-sdk`** wired in for the postMessage handshake, REST
+  client, webhook signature verification, and typed event dispatch
+
+## Wizard
+
+`npm run dev` (or once published, `npm create tolgee-app@latest`) walks
+you through:
+
+1. **App identifier** — kebab-case slug used as `manifest.id`, the
+   target directory name, and the `name` in `package.json`.
+2. **Display name** — shown in the Tolgee admin UI.
+3. **Modules** — pick any subset of the 10 module types.
+   Iframe-bearing modules (`project-dashboard-page`, `translation-tools-panel`,
+   `key-edit-tab`, `modal`) get source-file stubs; the rest get manifest
+   entries pointing back at those iframes.
+4. **Webhook events** — pick from a curated list of common
+   `ActivityType` values. The webhook route gets a typed `onWebhook(…)`
+   stub per event.
+5. **Tolgee URL** — defaults to `https://apps.preview.tolgee.io`.
+6. **Install deps** + **git init** prompts.
+
+## After generation
+
+```bash
+cd <your-app>
+npm install          # if you skipped it
+npm run register     # one-time: pick org, register the plugin
+npm run dev          # starts vite + express + tunnel, PATCHes manifest URL
+```
+
+Subsequent `npm run dev` restarts re-PATCH the install with the new
+tunnel URL automatically — no manual reinstall.
+
+## Layout
+
+```
+apps/create-tolgee-app/
+├── src/
+│   ├── index.ts        — entry, runs wizard, orchestrates copy
+│   ├── wizard.ts       — @clack/prompts flow
+│   ├── copy.ts         — recursive copy with mustache substitution
+│   ├── manifest.ts     — synthesizes manifest.template.json
+│   └── registry.ts     — module + webhook-event registry
+├── template/
+│   ├── base/           — files every project gets
+│   └── modules/<key>/  — iframe stubs per module type
+└── package.json
+```
+
+## Local build
+
+```bash
+npm run --workspace=create-tolgee-app build
+```
+
+Outputs an ESM shebang script at `dist/index.js`.

apps/create-tolgee-app/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "create-tolgee-app",
+  "version": "0.0.1-alpha.7",
+  "description": "Scaffold a new Tolgee Apps plugin with a working dev environment in one command.",
+  "type": "module",
+  "bin": {
+    "create-tolgee-app": "./dist/index.js"
+  },
+  "files": [
+    "dist",
+    "template"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsx src/index.ts"
+  },
+  "dependencies": {
+    "@clack/prompts": "^0.11.0",
+    "picocolors": "^1.1.1"
+  },
+  "devDependencies": {
+    "@tolgee/apps-sdk": "*",
+    "@types/node": "^24.12.3",
+    "tsup": "^8.3.5",
+    "tsx": "^4.19.2",
+    "typescript": "~6.0.2"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}

apps/create-tolgee-app/src/copy.ts

@@ -0,0 +1,91 @@
+import { mkdir, readdir, readFile, writeFile } from 'node:fs/promises'
+import { dirname, join, relative } from 'node:path'
+
+type Vars = Record<string, string>
+
+const isProbablyBinary = (filename: string): boolean => {
+  return /\.(png|jpg|jpeg|gif|svg|ico|webp|woff2?|ttf|otf|eot|mp4|webm)$/i.test(
+    filename
+  )
+}
+
+/**
+ * Mustache-style replacement: `{{name}}` → vars.name. Only single-word
+ * keys are substituted; missing keys leave the placeholder intact (so
+ * literal `{{` appearances in user-facing copy survive).
+ */
+const substitute = (text: string, vars: Vars): string => {
+  return text.replace(/\{\{(\w+)\}\}/g, (match, key: string) => {
+    return key in vars ? vars[key]! : match
+  })
+}
+
+/**
+ * Renames template-only file conventions to their real names:
+ *   `_package.json` → `package.json` (avoids npm seeing the template as a real package)
+ *   `_X`            → `.X`           (lets the template ship dotfiles)
+ */
+const targetFilename = (name: string): string => {
+  if (name === '_package.json') return 'package.json'
+  return name.startsWith('_') ? '.' + name.slice(1) : name
+}
+
+export type CopyOptions = {
+  /** Source directory inside the template. */
+  src: string
+  /** Destination directory for the generated project. */
+  dst: string
+  /** Variables substituted into text files. */
+  vars: Vars
+}
+
+/**
+ * Recursively copies `src` → `dst`, substituting `{{var}}` placeholders
+ * in text files and renaming `_*` files to `.*`.
+ */
+export async function copyTree(opts: CopyOptions): Promise<void> {
+  const entries = await readdir(opts.src, { withFileTypes: true })
+  await mkdir(opts.dst, { recursive: true })
+  for (const entry of entries) {
+    const srcPath = join(opts.src, entry.name)
+    const dstPath = join(opts.dst, targetFilename(entry.name))
+    if (entry.isDirectory()) {
+      await copyTree({ ...opts, src: srcPath, dst: dstPath })
+    } else if (entry.isFile()) {
+      if (isProbablyBinary(entry.name)) {
+        const buf = await readFile(srcPath)
+        await mkdir(dirname(dstPath), { recursive: true })
+        await writeFile(dstPath, buf)
+      } else {
+        const text = await readFile(srcPath, 'utf8')
+        await mkdir(dirname(dstPath), { recursive: true })
+        await writeFile(dstPath, substitute(text, opts.vars), 'utf8')
+      }
+    }
+  }
+}
+
+/**
+ * Like {@link copyTree} but takes a list of relative source files.
+ * Useful when only some files from a directory should be copied.
+ */
+export async function copyFiles(
+  baseSrc: string,
+  baseDst: string,
+  relativePaths: string[],
+  vars: Vars
+): Promise<void> {
+  for (const relPath of relativePaths) {
+    const segments = relPath.split('/').map((s) => targetFilename(s))
+    const srcPath = join(baseSrc, relPath)
+    const dstPath = join(baseDst, segments.join('/'))
+    const text = await readFile(srcPath, 'utf8')
+    await mkdir(dirname(dstPath), { recursive: true })
+    await writeFile(dstPath, substitute(text, vars), 'utf8')
+  }
+}
+
+/** For diagnostics only — relative path from a template root. */
+export const fromTemplate = (templateRoot: string, abs: string): string => {
+  return relative(templateRoot, abs)
+}