create-omniflow-plugin 0.1.0

package/README.md

@@ -0,0 +1,165 @@
+# create-omniflow-plugin
+
+Interactive CLI scaffolder for [OmniFlow](https://github.com/agnistack/omniflow) plugins.
+
+Generates a ready-to-build Gradle project with a Java ingestor, optional Next.js micro UI, and all the wiring needed to upload the plugin as a JAR to a running OmniFlow backend.
+
+## Usage
+
+Run directly with `npx` (no install needed):
+
+```sh
+npx create-omniflow-plugin
+```
+
+Or with `pnpm`/`yarn`:
+
+```sh
+pnpm dlx create-omniflow-plugin
+yarn dlx create-omniflow-plugin
+```
+
+The CLI will ask a few questions and scaffold a new directory named after your plugin ID.
+
+### Prompts
+
+| Prompt | Description |
+|---|---|
+| Plugin ID | Lowercase, hyphen-separated identifier (e.g. `gradle-build-scan`) |
+| Display name | Human-readable name shown in the OmniFlow UI |
+| Description | Short description of what the plugin ingests |
+| Author | Your name or organisation |
+| Java base package | Root Java package (e.g. `io.github.acme.plugins.myingestor`) |
+| Ingestor type key | Used in API paths — `/api/ingest/{type}` |
+| Include Next.js UI? | Whether to scaffold a micro frontend |
+| OmniFlow plugin-api version | Version of `omniflow-plugin-api` to depend on |
+| OmniFlow API base URL | Backend URL for local UI dev (e.g. `http://localhost:8080`) |
+
+## What gets generated
+
+```
+<plugin-id>/
+├── build.gradle          # Gradle build — Java + optional node-gradle plugin
+├── settings.gradle
+├── gradlew / gradlew.bat # Wrapper stubs (run `gradle wrapper` for the real ones)
+├── src/main/java/…/
+│   ├── <Name>Plugin.java     # OmniflowPlugin implementation
+│   └── <Name>Ingestor.java   # PluginIngestor implementation
+└── ui/                   # Only when "Include Next.js UI?" = yes
+    ├── package.json
+    ├── tsconfig.json
+    ├── next.config.ts
+    ├── tailwind.config.ts
+    ├── postcss.config.mjs
+    ├── eslint.config.mjs
+    ├── .env.local
+    ├── app/
+    │   ├── globals.css
+    │   ├── layout.tsx
+    │   └── page.tsx
+    ├── components/
+    │   └── ThemeSync.tsx
+    └── lib/
+        └── api.ts
+```
+
+## Build
+
+### Prerequisites
+
+- **Java 25+** and **Gradle** on your `PATH`
+- **Node.js 22+** (only required if you included the UI — node-gradle will download it automatically during `./gradlew jar`)
+
+### Build the JAR
+
+```sh
+cd <plugin-id>
+gradle wrapper        # generate the real Gradle wrapper (one-time)
+./gradlew jar
+```
+
+The fat JAR is written to `build/libs/<plugin-id>-1.0.0.jar`. It includes all runtime dependencies and, if you chose to include a UI, the compiled Next.js static export embedded as resources.
+
+To skip the UI build during development:
+
+```sh
+./gradlew jar -PskipUi
+```
+
+## Upload to OmniFlow
+
+```sh
+curl -X POST http://localhost:8080/api/plugins/upload \
+  -b "JSESSIONID=<your-session>" \
+  -F "file=@build/libs/<plugin-id>-1.0.0.jar"
+```
+
+Replace `http://localhost:8080` and the session cookie with your actual backend URL and credentials.
+
+## Develop the UI locally
+
+When you include a Next.js UI you can run it standalone against a live OmniFlow backend — no JAR build required:
+
+```sh
+cd <plugin-id>/ui
+npm install
+npm run dev        # starts on http://localhost:3000
+```
+
+The `NEXT_PUBLIC_API_URL` variable in `.env.local` controls which OmniFlow backend the UI talks to.
+
+---
+
+## Contributing to `create-omniflow-plugin`
+
+### Prerequisites
+
+- Node.js 18+
+- npm / pnpm
+
+### Install dependencies
+
+```sh
+npm install
+```
+
+### Build
+
+```sh
+npm run build
+```
+
+Compiled output lands in `dist/`.
+
+### Watch mode (rebuild on save)
+
+```sh
+npm run dev
+```
+
+### Test locally
+
+```sh
+node dist/index.js
+```
+
+Or link it globally so `create-omniflow-plugin` works in any directory:
+
+```sh
+npm link
+create-omniflow-plugin
+```
+
+## Publish to npm
+
+1. Bump the version in `package.json`.
+2. Build:
+   ```sh
+   npm run build
+   ```
+3. Publish:
+   ```sh
+   npm publish --access public
+   ```
+
+The `files` field in `package.json` ensures only `dist/` is included in the published package.

package/dist/index.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node

package/dist/index.js

@@ -0,0 +1,683 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import * as p from "@clack/prompts";
+import pc from "picocolors";
+
+// src/scaffold.ts
+import fs from "fs";
+import path from "path";
+
+// src/templates/java.ts
+function toPascalCase(id) {
+  return id.split("-").map((w) => w[0].toUpperCase() + w.slice(1)).join("");
+}
+function javaTemplates(a) {
+  const className = toPascalCase(a.pluginId);
+  const pkgPath = a.javaPackage.replace(/\./g, "/");
+  return {
+    // ── Gradle wrapper stub (real wrapper needs `gradle wrapper` to generate) ──
+    "gradlew": gradlew(),
+    "gradlew.bat": gradlewBat(),
+    "settings.gradle": settingsGradle(a),
+    "build.gradle": buildGradle(a, className),
+    // ── Java sources ──────────────────────────────────────────────────────────
+    [`src/main/java/${pkgPath}/${className}Plugin.java`]: pluginClass(a, className),
+    [`src/main/java/${pkgPath}/${className}Ingestor.java`]: ingestorClass(a, className),
+    // ── CI / ingestor scripts ─────────────────────────────────────────────────
+    "scripts/ingest.sh": ingestScript(a),
+    "scripts/upload-plugin.sh": uploadPluginScript(a)
+  };
+}
+function settingsGradle(a) {
+  return `rootProject.name = '${a.pluginId}'
+`;
+}
+function buildGradle(a, className) {
+  const uiBlock = a.hasUi ? `
+import com.github.gradle.node.npm.task.NpmTask
+
+node {
+  version        = '22.14.0'
+  npmVersion     = '10.9.2'
+  download       = true
+  nodeProjectDir = file("\${projectDir}/ui")
+}
+
+def uiOutDir      = file("\${projectDir}/ui/out")
+def uiResourceDir = file("\${projectDir}/src/main/resources/static-ui")
+def skipUi        = { project.hasProperty('skipUi') }
+
+tasks.named('nodeSetup')  { onlyIf { !skipUi() } }
+tasks.named('npmSetup')   { onlyIf { !skipUi() } }
+tasks.named('npmInstall') { onlyIf { !skipUi() } }
+
+tasks.register('buildUi', NpmTask) {
+  dependsOn tasks.named('npmInstall')
+  onlyIf { !skipUi() }
+  args        = ['run', 'build']
+  environment = ['NEXT_BUILD_FOR_JAR': '1']
+  inputs.dir("\${projectDir}/ui/app")
+  inputs.dir("\${projectDir}/ui/components")
+  inputs.dir("\${projectDir}/ui/lib")
+  inputs.file("\${projectDir}/ui/next.config.ts")
+  outputs.dir(uiOutDir)
+}
+
+tasks.register('copyUiAssets', Copy) {
+  dependsOn tasks.named('buildUi')
+  onlyIf { !skipUi() }
+  from uiOutDir
+  into uiResourceDir
+}
+
+processResources.dependsOn tasks.named('copyUiAssets')
+
+clean {
+  delete uiResourceDir
+}
+` : "";
+  const plugins = a.hasUi ? `  id 'java'
+  id 'com.github.node-gradle.node' version '7.1.0'` : `  id 'java'`;
+  return `${a.hasUi ? "import com.github.gradle.node.npm.task.NpmTask\n\n" : ""}plugins {
+${plugins}
+}
+
+group   = 'io.github.omniflow.plugins'
+version = '1.0.0'
+description = '${a.description}'
+
+java {
+  toolchain {
+    languageVersion = JavaLanguageVersion.of(25)
+  }
+}
+
+repositories {
+  mavenCentral()
+  mavenLocal()
+}
+
+dependencies {
+  compileOnly 'io.github.agnistack:omniflow-plugin-api:${a.omniflowVersion}'
+  implementation 'com.fasterxml.jackson.core:jackson-databind:2.17.2'
+}
+${uiBlock}
+jar {
+  archiveBaseName = '${a.pluginId}'
+  from {
+    configurations.runtimeClasspath.collect { it.isDirectory() ? it : zipTree(it) }
+  }
+  duplicatesStrategy = DuplicatesStrategy.EXCLUDE
+  manifest {
+    attributes(
+      'Plugin-Id'     : '${a.pluginId}',
+      'Plugin-Version': project.version,
+      'Plugin-Class'  : '${a.javaPackage}.${className}Plugin'
+    )
+  }
+}
+`;
+}
+function pluginClass(a, className) {
+  return `package ${a.javaPackage};
+
+import io.github.agnistack.omniflow.pluginapi.*;
+import java.util.List;
+
+public class ${className}Plugin implements OmniflowPlugin {
+
+    @Override
+    public PluginMetadata metadata() {
+        return PluginMetadata.builder()
+            .id("${a.pluginId}")
+            .name("${a.pluginName}")
+            .version("1.0.0")
+            .description("${a.description}")
+            .author("${a.author}")
+            .build();
+    }
+
+    @Override
+    public List<PluginIngestor<?>> ingestors() {
+        return List.of(new ${className}Ingestor());
+    }
+
+    @Override
+    public List<PluginAction> actions() {
+        return List.of();
+    }
+
+    @Override
+    public boolean hasUi() {
+        return ${a.hasUi};
+    }
+
+    @Override
+    public void onLoad(PluginContext context) {
+        // Called when the plugin is loaded \u2014 register schemas, etc.
+    }
+
+    @Override
+    public void onUnload() {
+        // Called when the plugin is unloaded \u2014 release resources.
+    }
+}
+`;
+}
+function ingestorClass(a, className) {
+  return `package ${a.javaPackage};
+
+import com.fasterxml.jackson.databind.ObjectMapper;
+import io.github.agnistack.omniflow.pluginapi.*;
+import java.io.InputStream;
+import java.time.Instant;
+import java.util.Map;
+import java.util.UUID;
+
+public class ${className}Ingestor implements PluginIngestor<PluginDataRecord> {
+
+    private static final ObjectMapper MAPPER = new ObjectMapper();
+
+    @Override
+    public String getType() {
+        return "${a.ingestorType}";
+    }
+
+    @Override
+    public PluginDataRecord ingest(InputStream data) throws Exception {
+        // TODO: parse your data format here
+        @SuppressWarnings("unchecked")
+        Map<String, Object> parsed = MAPPER.readValue(data, Map.class);
+
+        return PluginDataRecord.builder()
+            .id(UUID.randomUUID().toString())
+            .type(getType())
+            .timestamp(Instant.now())
+            .fields(parsed)
+            .build();
+    }
+}
+`;
+}
+function gradlew() {
+  return `#!/bin/sh
+# Run: gradle wrapper  \u2014 to generate the real Gradle wrapper files
+# Or install Gradle and run: gradle <task>
+exec gradle "$@"
+`;
+}
+function gradlewBat() {
+  return `@rem Run: gradle wrapper  \u2014 to generate the real Gradle wrapper files
+@rem Or install Gradle and run: gradle <task>
+@gradle %*
+`;
+}
+function ingestScript(a) {
+  return `#!/usr/bin/env bash
+# Ingest a JSON file into OmniFlow as type "${a.ingestorType}".
+#
+# Usage:
+#   ./scripts/ingest.sh data.json
+#   ./scripts/ingest.sh data.json https://omniflow.example.com
+#
+# Set OMNIFLOW_API_KEY in your environment or CI secrets.
+
+set -euo pipefail
+
+FILE=\${1:?Usage: $0 <data.json> [api-url]}
+API_URL=\${2:-${a.apiUrl}}
+API_KEY=\${OMNIFLOW_API_KEY:?Set OMNIFLOW_API_KEY environment variable}
+
+echo "Ingesting \${FILE} as type '${a.ingestorType}'..."
+
+HTTP_STATUS=$(curl -s -o /tmp/ingest_response.json -w "%{http_code}" \\
+  -X POST "\${API_URL}/api/ingest/${a.ingestorType}" \\
+  -H "X-Api-Key: \${API_KEY}" \\
+  -H "Content-Type: application/json" \\
+  --data-binary "@\${FILE}")
+
+if [ "\${HTTP_STATUS}" -ge 200 ] && [ "\${HTTP_STATUS}" -lt 300 ]; then
+  echo "Success (\${HTTP_STATUS}):"
+  cat /tmp/ingest_response.json
+else
+  echo "Failed (\${HTTP_STATUS}):"
+  cat /tmp/ingest_response.json
+  exit 1
+fi
+`;
+}
+function uploadPluginScript(a) {
+  return `#!/usr/bin/env bash
+# Build and upload the plugin JAR to a running OmniFlow backend.
+#
+# Usage:
+#   ./scripts/upload-plugin.sh
+#   ./scripts/upload-plugin.sh https://omniflow.example.com
+#
+# Set OMNIFLOW_API_KEY in your environment or CI secrets.
+
+set -euo pipefail
+
+API_URL=\${1:-${a.apiUrl}}
+API_KEY=\${OMNIFLOW_API_KEY:?Set OMNIFLOW_API_KEY environment variable}
+JAR="build/libs/${a.pluginId}-1.0.0.jar"
+
+echo "Building JAR..."
+./gradlew jar
+
+echo "Uploading \${JAR} to \${API_URL}..."
+
+HTTP_STATUS=$(curl -s -o /tmp/upload_response.json -w "%{http_code}" \\
+  -X POST "\${API_URL}/api/plugins/upload" \\
+  -H "X-Api-Key: \${API_KEY}" \\
+  -F "file=@\${JAR}")
+
+if [ "\${HTTP_STATUS}" -ge 200 ] && [ "\${HTTP_STATUS}" -lt 300 ]; then
+  echo "Plugin uploaded successfully (\${HTTP_STATUS}):"
+  cat /tmp/upload_response.json
+else
+  echo "Upload failed (\${HTTP_STATUS}):"
+  cat /tmp/upload_response.json
+  exit 1
+fi
+`;
+}
+
+// src/templates/ui.ts
+function uiTemplates(a) {
+  return {
+    "ui/package.json": uiPackageJson(a),
+    "ui/tsconfig.json": uiTsConfig(),
+    "ui/next.config.ts": uiNextConfig(a),
+    "ui/tailwind.config.ts": uiTailwindConfig(),
+    "ui/postcss.config.mjs": uiPostcss(),
+    "ui/eslint.config.mjs": uiEslintConfig(),
+    "ui/.env.local": uiEnvLocal(a),
+    "ui/app/globals.css": uiGlobalsCss(),
+    "ui/app/layout.tsx": uiLayout(a),
+    "ui/app/page.tsx": uiPage(a),
+    "ui/components/ThemeSync.tsx": uiThemeSync(),
+    "ui/lib/api.ts": uiApi(a)
+  };
+}
+function uiPackageJson(a) {
+  return JSON.stringify(
+    {
+      name: `${a.pluginId}-ui`,
+      version: "1.0.0",
+      private: true,
+      scripts: {
+        dev: "next dev",
+        build: "next build",
+        start: "next start",
+        lint: "next lint"
+      },
+      dependencies: {
+        "@omniflow/ui": "latest",
+        next: "16.2.1",
+        react: "19.2.4",
+        "react-dom": "19.2.4",
+        swr: "^2.3.3"
+      },
+      devDependencies: {
+        "@types/node": "^22",
+        "@types/react": "19.2.14",
+        "@types/react-dom": "19.2.3",
+        autoprefixer: "^10.4.21",
+        eslint: "^9.39.4",
+        "eslint-config-next": "^16.2.1",
+        postcss: "^8.5.3",
+        tailwindcss: "^3.4.17",
+        typescript: "^5"
+      },
+      overrides: {
+        "@types/react": "19.2.14",
+        "@types/react-dom": "19.2.3"
+      }
+    },
+    null,
+    2
+  ) + "\n";
+}
+function uiTsConfig() {
+  return JSON.stringify(
+    {
+      compilerOptions: {
+        target: "ES2017",
+        lib: ["dom", "dom.iterable", "esnext"],
+        allowJs: true,
+        skipLibCheck: true,
+        strict: true,
+        noEmit: true,
+        esModuleInterop: true,
+        module: "esnext",
+        moduleResolution: "bundler",
+        resolveJsonModule: true,
+        isolatedModules: true,
+        jsx: "preserve",
+        incremental: true,
+        plugins: [{ name: "next" }],
+        paths: { "@/*": ["./*"] }
+      },
+      include: ["next-env.d.ts", "**/*.ts", "**/*.tsx", ".next/types/**/*.ts"],
+      exclude: ["node_modules"]
+    },
+    null,
+    2
+  ) + "\n";
+}
+function uiNextConfig(a) {
+  return `import type { NextConfig } from 'next';
+
+const forJar = process.env.NEXT_BUILD_FOR_JAR === '1';
+
+const config: NextConfig = {
+  transpilePackages: ['@omniflow/ui'],
+  output: 'export',
+  // basePath and assetPrefix match the host's /api/plugins/{id}/ui/** route.
+  basePath:    forJar ? '/api/plugins/${a.pluginId}/ui' : '',
+  assetPrefix: forJar ? '/api/plugins/${a.pluginId}/ui' : '',
+  images: { unoptimized: true },
+  trailingSlash: false,
+};
+
+export default config;
+`;
+}
+function uiTailwindConfig() {
+  return `import type { Config } from 'tailwindcss';
+
+const config: Config = {
+  content: [
+    './app/**/*.{ts,tsx}',
+    './components/**/*.{ts,tsx}',
+    './lib/**/*.{ts,tsx}',
+    './node_modules/@omniflow/ui/src/**/*.{ts,tsx}',
+  ],
+  darkMode: 'class',
+  theme: { extend: {} },
+  plugins: [],
+};
+
+export default config;
+`;
+}
+function uiPostcss() {
+  return `const config = { plugins: { tailwindcss: {}, autoprefixer: {} } };
+export default config;
+`;
+}
+function uiEslintConfig() {
+  return `import nextCoreWebVitals from 'eslint-config-next/core-web-vitals';
+import nextTypescript from 'eslint-config-next/typescript';
+
+const eslintConfig = [
+  ...nextCoreWebVitals,
+  ...nextTypescript,
+  {
+    ignores: ['node_modules/**', '.next/**', 'out/**', 'build/**', 'next-env.d.ts'],
+  },
+];
+
+export default eslintConfig;
+`;
+}
+function uiEnvLocal(a) {
+  return `# OmniFlow backend URL \u2014 used by the UI when running outside the JAR (npm run dev)
+NEXT_PUBLIC_API_URL=${a.apiUrl}
+`;
+}
+function uiGlobalsCss() {
+  return `@tailwind base;
+@tailwind components;
+@tailwind utilities;
+
+:root {
+  color-scheme: light;
+}
+
+html.dark {
+  color-scheme: dark;
+}
+
+body {
+  @apply bg-gray-50 text-gray-900 dark:bg-slate-950 dark:text-slate-300;
+}
+`;
+}
+function uiLayout(a) {
+  return `import type { Metadata } from 'next';
+import './globals.css';
+import ThemeSync from '@/components/ThemeSync';
+
+export const metadata: Metadata = { title: '${a.pluginName} \u2014 OmniFlow' };
+
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <html lang="en" suppressHydrationWarning>
+      <head>
+        <script dangerouslySetInnerHTML={{ __html: \`(function(){var p=new URLSearchParams(location.search).get('theme'),t=p||sessionStorage.getItem('omniflow-plugin-theme'),s=window.matchMedia('(prefers-color-scheme:dark)').matches?'dark':'light';if(p)sessionStorage.setItem('omniflow-plugin-theme',p);if((t||s)==='dark')document.documentElement.classList.add('dark')})()\` }} />
+      </head>
+      <body className="min-h-screen flex flex-col">
+        <ThemeSync />
+        <header className="bg-white dark:bg-slate-900 border-b border-gray-200 dark:border-slate-800 px-6 py-3 flex items-center gap-3 flex-shrink-0">
+          <span className="text-sm font-bold text-gray-900 dark:text-slate-100">${a.pluginName}</span>
+          <span className="text-xs bg-purple-100 dark:bg-purple-900/50 text-purple-700 dark:text-purple-300 border border-purple-200 dark:border-purple-900 px-2 py-0.5 rounded-full">OmniFlow Plugin</span>
+        </header>
+        <main className="flex-1 p-6">{children}</main>
+      </body>
+    </html>
+  );
+}
+`;
+}
+function uiPage(a) {
+  return `'use client';
+
+import useSWR from 'swr';
+import { EmptyState, cls } from '@omniflow/ui';
+import { fetchRecords, type PluginRecord } from '@/lib/api';
+
+export default function HomePage() {
+  const { data: records, isLoading } = useSWR<PluginRecord[]>(
+    'records',
+    () => fetchRecords(50),
+    { refreshInterval: 30_000 },
+  );
+
+  if (isLoading) return <p className="text-gray-500 dark:text-slate-500 text-sm">Loading\u2026</p>;
+  if (!records?.length) return (
+    <EmptyState
+      title="No ${a.pluginName} data ingested yet."
+      description="POST data to /api/ingest/${a.ingestorType} to get started."
+    />
+  );
+
+  return (
+    <div className="max-w-4xl space-y-6">
+      {/* Records table */}
+      <div className={\`\${cls.card} p-4\`}>
+        <p className={\`\${cls.heading} mb-3\`}>Records</p>
+        <div className="overflow-x-auto">
+          <table className="w-full text-sm">
+            <thead>
+              <tr className={cls.table.header}>
+                <th className="text-left py-2 px-2">ID</th>
+                <th className="text-left py-2 px-2">Timestamp</th>
+              </tr>
+            </thead>
+            <tbody>
+              {records.map(r => (
+                <tr key={r.id} className={cls.table.row}>
+                  <td className="py-1.5 px-2 font-mono text-gray-500 dark:text-slate-400">{r.id}</td>
+                  <td className="py-1.5 px-2 text-gray-500 dark:text-slate-400">
+                    {new Date(r.timestamp).toLocaleString()}
+                  </td>
+                </tr>
+              ))}
+            </tbody>
+          </table>
+        </div>
+      </div>
+    </div>
+  );
+}
+`;
+}
+function uiThemeSync() {
+  return `'use client';
+
+import { useEffect } from 'react';
+
+export default function ThemeSync() {
+  useEffect(() => {
+    const param  = new URLSearchParams(window.location.search).get('theme');
+    const stored = sessionStorage.getItem('omniflow-plugin-theme');
+    const theme  = param ?? stored;
+    if (param) sessionStorage.setItem('omniflow-plugin-theme', param);
+    if (theme === 'dark') document.documentElement.classList.add('dark');
+    else if (theme === 'light') document.documentElement.classList.remove('dark');
+    else document.documentElement.classList.toggle('dark', window.matchMedia('(prefers-color-scheme: dark)').matches);
+  }, []);
+  return null;
+}
+`;
+}
+function uiApi(a) {
+  return `// The OmniFlow backend URL. Defaults to same origin in production (assets
+// are served by the OmniFlow host at /api/plugins/${a.pluginId}/ui).
+const BASE = process.env.NEXT_PUBLIC_API_URL ?? '';
+
+async function get<T>(path: string): Promise<T> {
+  const res = await fetch(BASE + path);
+  if (!res.ok) throw new Error(\`\${res.status} \${res.statusText}\`);
+  return res.json() as Promise<T>;
+}
+
+// \u2500\u2500 Types \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+
+// Extend PluginFields to match your ingestor's output shape.
+export interface PluginFields {
+  [key: string]: unknown;
+}
+
+export interface PluginRecord {
+  id:        string;
+  type:      string;
+  timestamp: string;
+  fields:    PluginFields;
+}
+
+// \u2500\u2500 API calls \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+
+export const fetchRecords = (limit = 50) =>
+  get<PluginRecord[]>(\`/api/analytics/builds?type=${a.ingestorType}&limit=\${limit}\`);
+`;
+}
+
+// src/scaffold.ts
+async function scaffold(answers) {
+  const outDir = path.resolve(process.cwd(), answers.pluginId);
+  const files = javaTemplates(answers);
+  if (answers.hasUi) {
+    Object.assign(files, uiTemplates(answers));
+  }
+  for (const [relPath, content] of Object.entries(files)) {
+    const abs = path.join(outDir, relPath);
+    fs.mkdirSync(path.dirname(abs), { recursive: true });
+    fs.writeFileSync(abs, content, "utf8");
+  }
+  for (const script of ["gradlew", "scripts/ingest.sh", "scripts/upload-plugin.sh"]) {
+    const abs = path.join(outDir, script);
+    if (fs.existsSync(abs)) fs.chmodSync(abs, 493);
+  }
+  return answers.pluginId;
+}
+
+// src/index.ts
+function toPascalCase2(id) {
+  return id.split("-").map((w) => w[0].toUpperCase() + w.slice(1)).join("");
+}
+async function main() {
+  console.log("");
+  p.intro(pc.bgMagenta(pc.white("  create-omniflow-plugin  ")));
+  const answers = await p.group(
+    {
+      pluginId: () => p.text({
+        message: "Plugin ID",
+        placeholder: "my-ingestor",
+        validate: (v) => /^[a-z][a-z0-9-]*$/.test(v) ? void 0 : "Use lowercase letters, numbers and hyphens only"
+      }),
+      pluginName: ({ results }) => p.text({
+        message: "Plugin display name",
+        initialValue: toPascalCase2(results.pluginId ?? "").replace(/([A-Z])/g, " $1").trim()
+      }),
+      description: () => p.text({
+        message: "Description",
+        placeholder: "Ingests ... data into OmniFlow"
+      }),
+      author: () => p.text({
+        message: "Author",
+        placeholder: "Your Name"
+      }),
+      javaPackage: ({ results }) => p.text({
+        message: "Java base package",
+        initialValue: `io.github.omniflow.plugins.${(results.pluginId ?? "").replace(/-/g, "")}`
+      }),
+      ingestorType: ({ results }) => p.text({
+        message: "Ingestor type key  (used in API paths, e.g. /api/ingest/{type})",
+        initialValue: results.pluginId
+      }),
+      hasUi: () => p.confirm({
+        message: "Include a Next.js micro UI?",
+        initialValue: true
+      }),
+      omniflowVersion: () => p.text({
+        message: "OmniFlow plugin-api version to depend on",
+        initialValue: "1.0.0"
+      }),
+      apiUrl: () => p.text({
+        message: "OmniFlow API base URL (for local dev)",
+        initialValue: "http://localhost:8080"
+      })
+    },
+    {
+      onCancel: () => {
+        p.cancel("Cancelled.");
+        process.exit(0);
+      }
+    }
+  );
+  const spinner2 = p.spinner();
+  spinner2.start("Scaffolding plugin\u2026");
+  const outDir = await scaffold(answers);
+  spinner2.stop("Done!");
+  const hasUi = answers.hasUi;
+  p.note(
+    [
+      `cd ${outDir}`,
+      "",
+      "# Build the JAR (includes UI if enabled):",
+      `./gradlew jar`,
+      "",
+      "# Upload to a running OmniFlow backend:",
+      `curl -X POST ${answers.apiUrl}/api/plugins/upload \\`,
+      `  -H "X-Api-Key: <your-api-key>" \\`,
+      `  -F "file=@build/libs/${answers.pluginId}-1.0.0.jar"`,
+      "",
+      "# Ingest data (see scripts/ingest.sh for a ready-made script):",
+      `curl -X POST ${answers.apiUrl}/api/ingest/${answers.ingestorType} \\`,
+      `  -H "X-Api-Key: <your-api-key>" \\`,
+      `  -H "Content-Type: application/json" \\`,
+      `  -d @data.json`,
+      ...hasUi ? ["", "# Dev UI standalone (no JAR needed):", "cd ui && npm install && npm run dev"] : []
+    ].join("\n"),
+    "Next steps"
+  );
+  p.outro(pc.green("Plugin scaffolded successfully!"));
+}
+main().catch((err) => {
+  console.error(pc.red("Error: ") + String(err));
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "create-omniflow-plugin",
+  "version": "0.1.0",
+  "description": "Scaffold a new OmniFlow plugin — Java ingestor/action + optional Next.js micro UI",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "create-omniflow-plugin": "./dist/index.js"
+  },
+  "files": ["dist"],
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts --clean",
+    "dev": "tsup src/index.ts --format esm --watch",
+    "start": "node dist/index.js"
+  },
+  "dependencies": {
+    "@clack/prompts": "^0.9.0",
+    "picocolors": "^1.1.1"
+  },
+  "devDependencies": {
+    "@types/node": "^22",
+    "tsup": "^8",
+    "typescript": "^5"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}