From 470f8a210d1dfa4a2cf488c160c65dc38dbc7a3a Mon Sep 17 00:00:00 2001
From: Huakun Shen <huakun.shen@huakunshen.com>
Date: Mon, 6 Jan 2025 14:37:42 -0500
Subject: [PATCH] Feature: headless template (#48)

* feat: add a headless extension template

* feat: add headless template support for create-kunkun package

* chore: bump create-kunkun version to 0.1.38
---
 apps/create-kunkun/CHANGELOG.md               |   6 +
 apps/create-kunkun/README.md                  |   4 +-
 apps/create-kunkun/index.ts                   |  13 +-
 apps/create-kunkun/package.json               |   2 +-
 apps/create-kunkun/src/constants.ts           |   2 +-
 .../template-ext-headless/.gitignore          | 177 ++++++++++++++++++
 .../template-ext-headless/CHANGELOG.md        |  15 ++
 .../templates/template-ext-headless/README.md | 125 +++++++++++++
 .../templates/template-ext-headless/build.ts  |  30 +++
 .../template-ext-headless/package.json        |  46 +++++
 .../template-ext-headless/src/index.ts        |  18 ++
 .../template-ext-headless/tsconfig.json       |  27 +++
 pnpm-lock.yaml                                |  19 ++
 13 files changed, 478 insertions(+), 6 deletions(-)
 create mode 100644 packages/templates/template-ext-headless/.gitignore
 create mode 100644 packages/templates/template-ext-headless/CHANGELOG.md
 create mode 100644 packages/templates/template-ext-headless/README.md
 create mode 100644 packages/templates/template-ext-headless/build.ts
 create mode 100644 packages/templates/template-ext-headless/package.json
 create mode 100644 packages/templates/template-ext-headless/src/index.ts
 create mode 100644 packages/templates/template-ext-headless/tsconfig.json

diff --git a/apps/create-kunkun/CHANGELOG.md b/apps/create-kunkun/CHANGELOG.md
index 09c2af9..09cd648 100644
--- a/apps/create-kunkun/CHANGELOG.md
+++ b/apps/create-kunkun/CHANGELOG.md
@@ -1,5 +1,11 @@
 # create-kunkun
 
+## 0.1.38
+
+### Patch Changes
+
+- Add headless command template
+
 ## 0.1.37
 
 ### Patch Changes
diff --git a/apps/create-kunkun/README.md b/apps/create-kunkun/README.md
index 01e5733..dd77335 100644
--- a/apps/create-kunkun/README.md
+++ b/apps/create-kunkun/README.md
@@ -11,6 +11,6 @@ npx create-kunkun@latest
 ## Develop
 
 ```bash
-bun index.ts --help
-bun index.ts
+pnpm build
+node dist/index.mjs
 ```
diff --git a/apps/create-kunkun/index.ts b/apps/create-kunkun/index.ts
index 3c2fe54..42e8d02 100644
--- a/apps/create-kunkun/index.ts
+++ b/apps/create-kunkun/index.ts
@@ -33,6 +33,7 @@ program
 	.addOption(
 		new Option("-t, --template <template>", "Extension Template").choices([
 			"template",
+			"headless",
 			"react",
 			"vue",
 			"svelte",
@@ -45,7 +46,7 @@ program
 	.addOption(new Option("-f, --force", "Overwrite existing files").default(false))
 	.addOption(new Option("-o, --outdir <outdir>", "Output directory").default(cwd))
 	.parse(process.argv)
-type Template = "react" | "template" | "vue" | "svelte" | "nuxt" | "sveltekit" | "next"
+type Template = "react" | "template" | "headless" | "vue" | "svelte" | "nuxt" | "sveltekit" | "next"
 const options = program.opts<{
 	template?: Template
 	outdir: string
@@ -98,6 +99,12 @@ async function copyTemplate(templateTgz: string, targetFolderName: string): Prom
 					description:
 						"Write regular logic in TypeScript in OOP manner to render extension UI based on predefined template."
 				},
+				{
+					name: "Headless Command",
+					value: "headless",
+					description:
+						'Write regular logic in TypeScript to implement "fire and forget" style command.'
+				},
 				{
 					name: "React Custom UI",
 					value: "react",
@@ -147,7 +154,9 @@ async function copyTemplate(templateTgz: string, targetFolderName: string): Prom
 	if (template === "template") {
 		destDir = await copyTemplate(path.join(templateRoot, "template-ext-worker.tgz"), name)
 		cleanExtension(destDir)
-	} else if (["react", "vue", "svelte", "nuxt", "sveltekit", "next"].includes(template)) {
+	} else if (
+		["react", "vue", "svelte", "nuxt", "sveltekit", "next", "headless"].includes(template)
+	) {
 		destDir = await copyTemplate(path.join(templateRoot, `template-ext-${template}.tgz`), name)
 		cleanExtension(destDir)
 	} else {
diff --git a/apps/create-kunkun/package.json b/apps/create-kunkun/package.json
index a05ce17..1f408e5 100644
--- a/apps/create-kunkun/package.json
+++ b/apps/create-kunkun/package.json
@@ -1,7 +1,7 @@
 {
 	"name": "create-kunkun",
 	"type": "module",
-	"version": "0.1.37",
+	"version": "0.1.38",
 	"bin": {
 		"create-kunkun": "dist/index.mjs"
 	},
diff --git a/apps/create-kunkun/src/constants.ts b/apps/create-kunkun/src/constants.ts
index 898b39c..e6b3857 100644
--- a/apps/create-kunkun/src/constants.ts
+++ b/apps/create-kunkun/src/constants.ts
@@ -12,7 +12,7 @@ export function getRootDir() {
 export function getTemplateRoot() {
 	return isProduction
 		? path.join(getRootDir(), "templates")
-		: path.join(getRootDir(), "../../templates")
+		: path.join(getRootDir(), "../../packages/templates")
 }
 
 export const createKunkunVersion = version
diff --git a/packages/templates/template-ext-headless/.gitignore b/packages/templates/template-ext-headless/.gitignore
new file mode 100644
index 0000000..8c67a06
--- /dev/null
+++ b/packages/templates/template-ext-headless/.gitignore
@@ -0,0 +1,177 @@
+# Based on https://raw.githubusercontent.com/github/gitignore/main/Node.gitignore
+
+# Logs
+
+logs
+_.log
+npm-debug.log_
+yarn-debug.log*
+yarn-error.log*
+lerna-debug.log*
+.pnpm-debug.log*
+
+# Caches
+
+.cache
+
+# Diagnostic reports (https://nodejs.org/api/report.html)
+
+report.[0-9]_.[0-9]_.[0-9]_.[0-9]_.json
+
+# Runtime data
+
+pids
+_.pid
+_.seed
+*.pid.lock
+
+# Directory for instrumented libs generated by jscoverage/JSCover
+
+lib-cov
+
+# Coverage directory used by tools like istanbul
+
+coverage
+*.lcov
+
+# nyc test coverage
+
+.nyc_output
+
+# Grunt intermediate storage (https://gruntjs.com/creating-plugins#storing-task-files)
+
+.grunt
+
+# Bower dependency directory (https://bower.io/)
+
+bower_components
+
+# node-waf configuration
+
+.lock-wscript
+
+# Compiled binary addons (https://nodejs.org/api/addons.html)
+
+build/Release
+
+# Dependency directories
+
+node_modules/
+jspm_packages/
+
+# Snowpack dependency directory (https://snowpack.dev/)
+
+web_modules/
+
+# TypeScript cache
+
+*.tsbuildinfo
+
+# Optional npm cache directory
+
+.npm
+
+# Optional eslint cache
+
+.eslintcache
+
+# Optional stylelint cache
+
+.stylelintcache
+
+# Microbundle cache
+
+.rpt2_cache/
+.rts2_cache_cjs/
+.rts2_cache_es/
+.rts2_cache_umd/
+
+# Optional REPL history
+
+.node_repl_history
+
+# Output of 'npm pack'
+
+*.tgz
+
+# Yarn Integrity file
+
+.yarn-integrity
+
+# dotenv environment variable files
+
+.env
+.env.development.local
+.env.test.local
+.env.production.local
+.env.local
+
+# parcel-bundler cache (https://parceljs.org/)
+
+.parcel-cache
+
+# Next.js build output
+
+.next
+out
+
+# Nuxt.js build / generate output
+
+.nuxt
+dist
+
+# Gatsby files
+
+# Comment in the public line in if your project uses Gatsby and not Next.js
+
+# https://nextjs.org/blog/next-9-1#public-directory-support
+
+# public
+
+# vuepress build output
+
+.vuepress/dist
+
+# vuepress v2.x temp and cache directory
+
+.temp
+
+# Docusaurus cache and generated files
+
+.docusaurus
+
+# Serverless directories
+
+.serverless/
+
+# FuseBox cache
+
+.fusebox/
+
+# DynamoDB Local files
+
+.dynamodb/
+
+# TernJS port file
+
+.tern-port
+
+# Stores VSCode versions used for testing VSCode extensions
+
+.vscode-test
+
+# yarn v2
+
+.yarn/cache
+.yarn/unplugged
+.yarn/build-state.yml
+.yarn/install-state.gz
+.pnp.*
+
+# IntelliJ based IDEs
+.idea
+
+# Finder (MacOS) folder config
+.DS_Store
+extensions_support/
+
diff --git a/packages/templates/template-ext-headless/CHANGELOG.md b/packages/templates/template-ext-headless/CHANGELOG.md
new file mode 100644
index 0000000..c95bcc7
--- /dev/null
+++ b/packages/templates/template-ext-headless/CHANGELOG.md
@@ -0,0 +1,15 @@
+# template-ext-worker
+
+## 0.0.4
+
+### Patch Changes
+
+- Updated dependencies
+  - @kksh/api@0.0.48
+
+## 0.0.3
+
+### Patch Changes
+
+- Updated dependencies
+  - @kksh/api@0.0.47
diff --git a/packages/templates/template-ext-headless/README.md b/packages/templates/template-ext-headless/README.md
new file mode 100644
index 0000000..e1c7cc7
--- /dev/null
+++ b/packages/templates/template-ext-headless/README.md
@@ -0,0 +1,125 @@
+# Kunkun Template UI Extension
+
+This is a template for a template UI extension. (UI follows pre-defined template)
+
+[./src/index.ts](./src/index.ts) is the default entrypoint for the extension. You can import any other files in this file, but the build process will bundle them into a single file.
+
+## Pros and Cons
+
+This type of extension is suitable for simple use cases, such as a list or form. All components are pre-defined, so there is not much room for customization. If you want more flexibility on the UI, consider using [Custom UI Extension](https://docs.kunkun.sh/extensions/custom-ui-ext/), which requires some frontend knowledge but gives you full control over the UI.
+
+Read documentation at https://docs.kunkun.sh/extensions/worker-template/
+
+Make sure you understand what this type of extension is capable of.
+
+### Pros
+
+- Simple to develop, no need for any frontend knowledge.
+- Small bundle size (~40KB)
+  - [Custom UI Extension](https://docs.kunkun.sh/extensions/custom-ui-ext/) are usually larger than 300KB.
+
+### Cons
+
+- Limited UI customization. Not suitable for complex use cases.
+
+Consider [Custom UI Extension](https://docs.kunkun.sh/extensions/custom-ui-ext/) if you need more complex UI.
+
+## Development
+
+```bash
+pnpm install
+```
+
+Start extension in development mode. Every save will trigger a hot reload in Kunkun.
+
+```bash
+pnpm dev
+```
+
+- During development, right click in Kunkun to open the developer tools.
+  - Error messages will be shown in the console.
+  - If you got any permission error while calling Kunknu's APIs, make sure you've declared the permission in `package.json`. Then go back to home page and enter the extension again to re-apply the permission.
+- To develop and preview the extension in Kunkun, you need to run the `Add Dev Extension` command in Kunkun, and register this extension's path.
+
+Build the extension. Your extension source code can contain many files, but the build process will bundle them into a single file.
+
+```bash
+pnpm build
+# Due to Bun's bug, if you are on windows, and install dependencies with pnpm, you may get error during build.
+# Try install dependencies with bun or npm instead.
+```
+
+## i18n
+
+[./src/i18n](./src/i18n/) contains optional internationalization support starter code.
+
+If you want to support i18n, you can use the `t` function to translate the strings in the extension.
+
+User's language setting is available via `app.language()`.
+
+```ts
+import { app } from "@kksh/api/ui/worker"
+import { setupI18n, t } from "./src/i18n"
+
+setupI18n("zh")
+console.log(t("welcome"))
+
+setupI18n(await app.language())
+console.log(t("welcome"))
+```
+
+## Add More Commands
+
+If you want to add more template worker extension commands, simply modify the `entrypoints` array in [./build.ts](./build.ts).
+
+Then in `package.json`, register the new command.
+
+## Verify Build and Publish
+
+```bash
+pnpm build # make sure the build npm script works
+npx kksh@latest verify # Verify some basic settings
+npx kksh@latest verify --publish # Verify some basic settings before publishing
+```
+
+It is recommended to build the extension with the same environment our CI uses.
+
+The docker image used by our CI is `huakunshen/kunkun-ext-builder:latest`.
+
+You can use the following command to build the extension with the same environment our CI uses.
+This requires you to have docker installed, and the shell you are using has access to it via `docker` command.
+
+```bash
+npx kksh@latest build # Build the extension with
+```
+
+`pnpm` is used to install dependencies and build the extension.
+
+The docker image environment also has `node`, `pnpm`, `npm`, `bun`, `deno` installed.
+If your build failed, try debug with `huakunshen/kunkun-ext-builder:latest` image in interative mode and bind your extension volume to `/workspace`.
+
+After build successfully, you should find a tarball file ends with `.tgz` in the root of your extension.
+The tarball is packaged with `npm pack` command. You can uncompress it to see if it contains all the necessary files.
+
+This tarball is the final product that will be published and installed in Kunkun. You can further verify your extension by installing this tarball directly in Kunkun.
+
+After verifying the tarball, it's ready to be published.
+
+Fork [KunkunExtensions](https://github.com/kunkunsh/KunkunExtensions) repo, add your extension to the `extensions` directory, and create a PR.
+
+Once CI passed and PR merged, you can use your extension in Kunkun.
+
+## Potential Error
+
+Our CI uses `pnpm` to install dependencies. If you are on Windows, you may get error during build.
+
+See issue https://github.com/kunkunsh/kunkun/issues/78
+
+`bun` had problem building the extension when `pnpm` is used to install dependencies.
+
+### Options
+
+1. Install an older version of `bun` (1.1.27 should work)
+2. Install dependencies with `bun` or `npm` instead of `pnpm`
+
+Our CI always builds the extension with on Linux and shouldn't have this problem.
diff --git a/packages/templates/template-ext-headless/build.ts b/packages/templates/template-ext-headless/build.ts
new file mode 100644
index 0000000..a99deb5
--- /dev/null
+++ b/packages/templates/template-ext-headless/build.ts
@@ -0,0 +1,30 @@
+import { watch } from "fs"
+import { join } from "path"
+import { refreshTemplateWorkerExtension } from "@kksh/api/dev"
+import { $ } from "bun"
+
+const entrypoints = ["./src/index.ts"]
+
+async function build() {
+	try {
+		for (const entrypoint of entrypoints) {
+			await $`bun build --minify --target=browser --outdir=./dist ${entrypoint}`
+		}
+		if (Bun.argv.includes("dev")) {
+			await refreshTemplateWorkerExtension()
+		}
+	} catch (error) {
+		console.error(error)
+	}
+}
+
+const srcDir = join(import.meta.dir, "src")
+
+await build()
+
+if (Bun.argv.includes("dev")) {
+	console.log(`Watching ${srcDir} for changes...`)
+	watch(srcDir, { recursive: true }, async (event, filename) => {
+		await build()
+	})
+}
diff --git a/packages/templates/template-ext-headless/package.json b/packages/templates/template-ext-headless/package.json
new file mode 100644
index 0000000..517d19d
--- /dev/null
+++ b/packages/templates/template-ext-headless/package.json
@@ -0,0 +1,46 @@
+{
+	"$schema": "./node_modules/@kksh/api/dist/schema.json",
+	"name": "template-ext-headless",
+	"version": "0.0.4",
+	"type": "module",
+	"kunkun": {
+		"name": "TODO: Extension Display Name",
+		"shortDescription": "A headless Extension Template",
+		"longDescription": "A headless Extension Template",
+		"identifier": "template-ext-headless",
+		"permissions": [
+			"clipboard:write-text"
+		],
+		"demoImages": [],
+		"icon": {
+			"type": "iconify",
+			"value": "tabler:code"
+		},
+		"headlessCmds": [
+			{
+				"name": "Template: Headless Command UUID",
+				"main": "dist/index.js",
+				"cmds": []
+			}
+		]
+	},
+	"scripts": {
+		"dev": "bun build.ts dev",
+		"build": "bun build.ts"
+	},
+	"dependencies": {
+		"@kksh/api": "workspace:*",
+		"i18next": "^23.15.1",
+		"uuid": "^11.0.3"
+	},
+	"devDependencies": {
+		"@types/bun": "latest"
+	},
+	"peerDependencies": {
+		"typescript": "^5.0.0"
+	},
+	"files": [
+		"./dist",
+		".gitignore"
+	]
+}
diff --git a/packages/templates/template-ext-headless/src/index.ts b/packages/templates/template-ext-headless/src/index.ts
new file mode 100644
index 0000000..4e8b6df
--- /dev/null
+++ b/packages/templates/template-ext-headless/src/index.ts
@@ -0,0 +1,18 @@
+import { clipboard, expose, HeadlessWorkerExtension, toast } from "@kksh/api/headless"
+import { v4 as uuidv4 } from "uuid"
+
+class UuidExt extends HeadlessWorkerExtension {
+	async load() {
+		const uuid = uuidv4()
+		return clipboard
+			.writeText(uuid)
+			.then(() => {
+				toast.success(`Copied UUID: ${uuid}`)
+			})
+			.catch((err) => {
+				toast.error(`Failed to copy UUID: ${err}`)
+			})
+	}
+}
+
+expose(new UuidExt())
diff --git a/packages/templates/template-ext-headless/tsconfig.json b/packages/templates/template-ext-headless/tsconfig.json
new file mode 100644
index 0000000..49ca356
--- /dev/null
+++ b/packages/templates/template-ext-headless/tsconfig.json
@@ -0,0 +1,27 @@
+{
+  "compilerOptions": {
+    // Enable latest features
+    "lib": [
+      "ESNext",
+      "DOM"
+    ],
+    "target": "ESNext",
+    "module": "ESNext",
+    "moduleDetection": "force",
+    "jsx": "react-jsx",
+    "allowJs": true,
+    // Bundler mode
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": false,
+    "verbatimModuleSyntax": true,
+    "noEmit": true,
+    // Best practices
+    "strict": true,
+    "skipLibCheck": true,
+    "noFallthroughCasesInSwitch": true,
+    // Some stricter flags (disabled by default)
+    "noUnusedLocals": false,
+    "noUnusedParameters": false,
+    "noPropertyAccessFromIndexSignature": false
+  }
+}
\ No newline at end of file
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 2ea1166..821537b 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -719,6 +719,25 @@ importers:
         specifier: latest
         version: 1.1.14
 
+  packages/templates/template-ext-headless:
+    dependencies:
+      '@kksh/api':
+        specifier: workspace:*
+        version: link:../../api
+      i18next:
+        specifier: ^23.15.1
+        version: 23.16.5
+      typescript:
+        specifier: ^5.0.0
+        version: 5.6.3
+      uuid:
+        specifier: ^11.0.3
+        version: 11.0.3
+    devDependencies:
+      '@types/bun':
+        specifier: latest
+        version: 1.1.14
+
   packages/templates/template-ext-next:
     dependencies:
       '@kksh/api':