create-forge-plugin 1.0.0

package/dist/names.d.ts

@@ -0,0 +1,27 @@
+export type PluginType = 'ui' | 'backend' | 'fullstack';
+export interface PluginNames {
+    /** Short plugin ID, consistent with backend's derivePluginId(). e.g. "pagerduty" */
+    pluginId: string;
+    /** Full npm package name. e.g. "@myorg/forge-plugin-pagerduty" */
+    packageName: string;
+    /** Output directory name. e.g. "forge-plugin-pagerduty" */
+    dirName: string;
+    /** PascalCase for component/class names. e.g. "Pagerduty" | "MyPlugin" */
+    pascalName: string;
+    /** camelCase for variable names. e.g. "pagerduty" | "myPlugin" */
+    camelName: string;
+    /** Human-readable title. e.g. "Pagerduty" | "My Plugin" */
+    title: string;
+    /** Optional org scope. e.g. "@myorg" (with @) */
+    org?: string;
+}
+/**
+ * Derives all naming variants from a short plugin identifier.
+ *
+ * @param pluginId - Short ID, e.g. "pagerduty" or "my-custom-plugin". No scope, no prefix.
+ * @param org      - Optional npm scope with @, e.g. "@myorg"
+ *
+ * Convention: pluginId MUST be kebab-case, lowercase, no special chars.
+ */
+export declare function deriveNames(pluginId: string, org?: string): PluginNames;
+//# sourceMappingURL=names.d.ts.map

package/dist/names.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"names.d.ts","sourceRoot":"","sources":["../src/names.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,UAAU,GAAG,IAAI,GAAG,SAAS,GAAG,WAAW,CAAC;AAExD,MAAM,WAAW,WAAW;IAC1B,oFAAoF;IACpF,QAAQ,EAAK,MAAM,CAAC;IACpB,kEAAkE;IAClE,WAAW,EAAE,MAAM,CAAC;IACpB,2DAA2D;IAC3D,OAAO,EAAM,MAAM,CAAC;IACpB,0EAA0E;IAC1E,UAAU,EAAG,MAAM,CAAC;IACpB,kEAAkE;IAClE,SAAS,EAAI,MAAM,CAAC;IACpB,2DAA2D;IAC3D,KAAK,EAAQ,MAAM,CAAC;IACpB,iDAAiD;IACjD,GAAG,CAAC,EAAS,MAAM,CAAC;CACrB;AAED;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,WAAW,CAmCvE"}

package/dist/names.js

@@ -0,0 +1,34 @@
+/**
+ * Derives all naming variants from a short plugin identifier.
+ *
+ * @param pluginId - Short ID, e.g. "pagerduty" or "my-custom-plugin". No scope, no prefix.
+ * @param org      - Optional npm scope with @, e.g. "@myorg"
+ *
+ * Convention: pluginId MUST be kebab-case, lowercase, no special chars.
+ */
+export function deriveNames(pluginId, org) {
+    if (!/^[a-z][a-z0-9-]*$/.test(pluginId)) {
+        throw new Error(`Invalid plugin ID "${pluginId}". Must be lowercase kebab-case (e.g. "pagerduty", "my-plugin").`);
+    }
+    if (org && !/^@[a-z][a-z0-9-]*$/.test(org)) {
+        throw new Error(`Invalid org scope "${org}". Must start with @ and be lowercase (e.g. "@myorg").`);
+    }
+    const packageName = org
+        ? `${org}/forge-plugin-${pluginId}`
+        : `forge-plugin-${pluginId}`;
+    const dirName = `forge-plugin-${pluginId}`;
+    const parts = pluginId.split('-');
+    const pascalName = parts
+        .map((p) => p.charAt(0).toUpperCase() + p.slice(1))
+        .join('');
+    const camelName = (parts[0] ?? '') +
+        parts
+            .slice(1)
+            .map((p) => p.charAt(0).toUpperCase() + p.slice(1))
+            .join('');
+    const title = parts
+        .map((p) => p.charAt(0).toUpperCase() + p.slice(1))
+        .join(' ');
+    return { pluginId, packageName, dirName, pascalName, camelName, title, org };
+}
+//# sourceMappingURL=names.js.map

package/dist/names.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"names.js","sourceRoot":"","sources":["../src/names.ts"],"names":[],"mappings":"AAmBA;;;;;;;GAOG;AACH,MAAM,UAAU,WAAW,CAAC,QAAgB,EAAE,GAAY;IACxD,IAAI,CAAC,mBAAmB,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC;QACxC,MAAM,IAAI,KAAK,CACb,sBAAsB,QAAQ,kEAAkE,CACjG,CAAC;IACJ,CAAC;IACD,IAAI,GAAG,IAAI,CAAC,oBAAoB,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;QAC3C,MAAM,IAAI,KAAK,CACb,sBAAsB,GAAG,wDAAwD,CAClF,CAAC;IACJ,CAAC;IAED,MAAM,WAAW,GAAG,GAAG;QACrB,CAAC,CAAC,GAAG,GAAG,iBAAiB,QAAQ,EAAE;QACnC,CAAC,CAAC,gBAAgB,QAAQ,EAAE,CAAC;IAE/B,MAAM,OAAO,GAAG,gBAAgB,QAAQ,EAAE,CAAC;IAE3C,MAAM,KAAK,GAAG,QAAQ,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAClC,MAAM,UAAU,GAAG,KAAK;SACrB,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,WAAW,EAAE,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;SAClD,IAAI,CAAC,EAAE,CAAC,CAAC;IAEZ,MAAM,SAAS,GACb,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;QAChB,KAAK;aACF,KAAK,CAAC,CAAC,CAAC;aACR,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,WAAW,EAAE,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;aAClD,IAAI,CAAC,EAAE,CAAC,CAAC;IAEd,MAAM,KAAK,GAAG,KAAK;SAChB,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,WAAW,EAAE,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;SAClD,IAAI,CAAC,GAAG,CAAC,CAAC;IAEb,OAAO,EAAE,QAAQ,EAAE,WAAW,EAAE,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,KAAK,EAAE,GAAG,EAAE,CAAC;AAC/E,CAAC"}

package/dist/scaffolder.d.ts

@@ -0,0 +1,11 @@
+import type { PluginNames, PluginType } from './names.js';
+export interface ScaffoldResult {
+    targetDir: string;
+    filesCreated: string[];
+}
+/**
+ * Writes all generated files for the plugin to the target directory.
+ * Throws if the target directory already exists.
+ */
+export declare function scaffoldPlugin(names: PluginNames, type: PluginType, parentDir: string): Promise<ScaffoldResult>;
+//# sourceMappingURL=scaffolder.d.ts.map

package/dist/scaffolder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scaffolder.d.ts","sourceRoot":"","sources":["../src/scaffolder.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAQ1D,MAAM,WAAW,cAAc;IAC7B,SAAS,EAAK,MAAM,CAAC;IACrB,YAAY,EAAE,MAAM,EAAE,CAAC;CACxB;AAED;;;GAGG;AACH,wBAAsB,cAAc,CAClC,KAAK,EAAM,WAAW,EACtB,IAAI,EAAO,UAAU,EACrB,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,cAAc,CAAC,CAgDzB"}

package/dist/scaffolder.js

@@ -0,0 +1,52 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { genManifest, genPackageJson, genTsConfig, genReadme, genUiIndex, genUiTab, genBackendIndex, genBackendAction, genBackendRoutes, genFullstackUiIndex, genFullstackCard, genFullstackBackendIndex, } from './templates.js';
+/**
+ * Writes all generated files for the plugin to the target directory.
+ * Throws if the target directory already exists.
+ */
+export async function scaffoldPlugin(names, type, parentDir) {
+    const targetDir = path.join(parentDir, names.dirName);
+    const filesCreated = [];
+    // Guard: refuse to overwrite existing directory
+    try {
+        await fs.access(targetDir);
+        throw new Error(`Directory "${names.dirName}" already exists in ${parentDir}. ` +
+            `Remove it first or choose a different plugin ID.`);
+    }
+    catch (err) {
+        if (err.code !== 'ENOENT')
+            throw err;
+    }
+    async function write(relPath, content) {
+        const absPath = path.join(targetDir, relPath);
+        await fs.mkdir(path.dirname(absPath), { recursive: true });
+        await fs.writeFile(absPath, content, 'utf8');
+        filesCreated.push(relPath);
+    }
+    // ── Shared files ────────────────────────────────────────────────────────────
+    await write('forgeportal-plugin.json', genManifest(names, type));
+    await write('package.json', genPackageJson(names, type));
+    await write('tsconfig.json', genTsConfig(type));
+    await write('README.md', genReadme(names, type));
+    // ── Type-specific files ─────────────────────────────────────────────────────
+    if (type === 'ui') {
+        await write('src/index.ts', genUiIndex(names));
+        await write(`src/${names.pascalName}Tab.tsx`, genUiTab(names));
+    }
+    else if (type === 'backend') {
+        await write('src/index.ts', genBackendIndex(names));
+        await write(`src/actions/${names.camelName}Action.ts`, genBackendAction(names));
+        await write('src/routes.ts', genBackendRoutes(names));
+    }
+    else if (type === 'fullstack') {
+        await write('src/ui/index.ts', genFullstackUiIndex(names));
+        await write(`src/ui/${names.pascalName}Card.tsx`, genFullstackCard(names));
+        await write('src/backend/index.ts', genFullstackBackendIndex(names));
+        await write(`src/backend/actions/${names.camelName}Action.ts`, genBackendAction(names));
+        await write('src/backend/routes.ts', genBackendRoutes(names));
+        await write('src/index.ts', `// Re-export entry points for both plugin types\nexport * from './ui/index.js';\nexport * from './backend/index.js';\n`);
+    }
+    return { targetDir, filesCreated };
+}
+//# sourceMappingURL=scaffolder.js.map

package/dist/scaffolder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scaffolder.js","sourceRoot":"","sources":["../src/scaffolder.ts"],"names":[],"mappings":"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"}

package/dist/templates.d.ts

@@ -0,0 +1,14 @@
+import type { PluginNames, PluginType } from './names.js';
+export declare function genManifest(names: PluginNames, type: PluginType): string;
+export declare function genPackageJson(names: PluginNames, type: PluginType): string;
+export declare function genTsConfig(type: PluginType): string;
+export declare function genReadme(names: PluginNames, type: PluginType): string;
+export declare function genUiIndex(names: PluginNames): string;
+export declare function genUiTab(names: PluginNames): string;
+export declare function genBackendIndex(names: PluginNames): string;
+export declare function genBackendAction(names: PluginNames): string;
+export declare function genBackendRoutes(names: PluginNames): string;
+export declare function genFullstackUiIndex(names: PluginNames): string;
+export declare function genFullstackCard(names: PluginNames): string;
+export declare function genFullstackBackendIndex(names: PluginNames): string;
+//# sourceMappingURL=templates.d.ts.map

package/dist/templates.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"templates.d.ts","sourceRoot":"","sources":["../src/templates.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAI1D,wBAAgB,WAAW,CAAC,KAAK,EAAE,WAAW,EAAE,IAAI,EAAE,UAAU,GAAG,MAAM,CAgCxE;AAED,wBAAgB,cAAc,CAAC,KAAK,EAAE,WAAW,EAAE,IAAI,EAAE,UAAU,GAAG,MAAM,CAmD3E;AAED,wBAAgB,WAAW,CAAC,IAAI,EAAE,UAAU,GAAG,MAAM,CA6BpD;AAED,wBAAgB,SAAS,CAAC,KAAK,EAAE,WAAW,EAAE,IAAI,EAAE,UAAU,GAAG,MAAM,CAwEtE;AAID,wBAAgB,UAAU,CAAC,KAAK,EAAE,WAAW,GAAG,MAAM,CAmBrD;AAED,wBAAgB,QAAQ,CAAC,KAAK,EAAE,WAAW,GAAG,MAAM,CAiCnD;AAID,wBAAgB,eAAe,CAAC,KAAK,EAAE,WAAW,GAAG,MAAM,CA6B1D;AAED,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,WAAW,GAAG,MAAM,CAuD3D;AAED,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,WAAW,GAAG,MAAM,CA4B3D;AAID,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,WAAW,GAAG,MAAM,CAa9D;AAED,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,WAAW,GAAG,MAAM,CA4C3D;AAED,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,WAAW,GAAG,MAAM,CA0BnE"}

package/dist/templates.js

@@ -0,0 +1,425 @@
+// ─── Shared templates ────────────────────────────────────────────────────────
+export function genManifest(names, type) {
+    const capabilities = {};
+    if (type === 'ui' || type === 'fullstack') {
+        capabilities['ui'] = { entityTabs: [`${names.pluginId}-tab`] };
+    }
+    if (type === 'backend' || type === 'fullstack') {
+        capabilities['backend'] = {
+            routes: ['/status'],
+            actionProviders: [`${names.pluginId}.myAction@v1`],
+        };
+    }
+    return JSON.stringify({
+        name: names.packageName,
+        version: '1.0.0',
+        forgeportal: {
+            engineVersion: '^1.0.0',
+            type,
+            capabilities,
+            config: {
+                apiEndpoint: {
+                    type: 'string',
+                    description: `${names.title} API endpoint`,
+                    required: false,
+                },
+            },
+        },
+    }, null, 2);
+}
+export function genPackageJson(names, type) {
+    const hasUi = type === 'ui' || type === 'fullstack';
+    const hasBackend = type === 'backend' || type === 'fullstack';
+    const peerDeps = {
+        '@forgeportal/plugin-sdk': '^1.0.0',
+    };
+    const devDeps = {
+        '@forgeportal/plugin-sdk': '^1.0.0',
+        '@types/node': '^22',
+        typescript: '^5',
+    };
+    if (hasUi) {
+        peerDeps['react'] = '>=19';
+        devDeps['@types/react'] = '^19';
+        devDeps['react'] = '^19';
+    }
+    if (hasBackend) {
+        devDeps['fastify'] = '^5';
+        devDeps['@types/node'] = '^22';
+    }
+    const exports = {
+        '.': { types: './dist/index.d.ts', import: './dist/index.js' },
+    };
+    if (type === 'fullstack') {
+        exports['./ui'] = { types: './dist/ui/index.d.ts', import: './dist/ui/index.js' };
+        exports['./backend'] = { types: './dist/backend/index.d.ts', import: './dist/backend/index.js' };
+    }
+    return JSON.stringify({
+        name: names.packageName,
+        version: '1.0.0',
+        description: `ForgePortal ${type} plugin — ${names.title}`,
+        type: 'module',
+        main: 'dist/index.js',
+        types: 'dist/index.d.ts',
+        exports,
+        scripts: {
+            build: 'tsc',
+            dev: 'tsc --watch',
+            lint: 'eslint src/',
+        },
+        peerDependencies: peerDeps,
+        devDependencies: devDeps,
+    }, null, 2);
+}
+export function genTsConfig(type) {
+    const hasUi = type === 'ui' || type === 'fullstack';
+    const compilerOptions = {
+        target: 'ES2022',
+        module: 'NodeNext',
+        moduleResolution: 'NodeNext',
+        strict: true,
+        esModuleInterop: true,
+        skipLibCheck: true,
+        declaration: true,
+        declarationMap: true,
+        sourceMap: true,
+        outDir: 'dist',
+        rootDir: 'src',
+    };
+    if (hasUi) {
+        compilerOptions['jsx'] = 'react-jsx';
+    }
+    return JSON.stringify({
+        compilerOptions,
+        include: ['src'],
+        exclude: ['node_modules', 'dist'],
+    }, null, 2);
+}
+export function genReadme(names, type) {
+    const uiSection = type === 'ui' || type === 'fullstack'
+        ? `**UI** — add to \`apps/ui/src/plugins/index.ts\`:
+\`\`\`typescript
+import { registerPlugin } from '${names.packageName}${type === 'fullstack' ? '/ui' : ''}';
+registerPluginById('${names.pluginId}', registerPlugin);
+\`\`\``
+        : '';
+    const backendSection = type === 'backend' || type === 'fullstack'
+        ? `**Backend** — add to \`forgeportal.yaml\`:
+\`\`\`yaml
+pluginPackages:
+  packages:
+    - "${names.packageName}"
+\`\`\``
+        : '';
+    return `# ${names.packageName}
+
+> ForgePortal ${type} plugin — ${names.title}
+
+## Overview
+
+This plugin was generated with [create-forge-plugin](https://github.com/your-org/forgeportal).
+
+## Plugin Type
+
+**${type}** — ${type === 'ui' ? 'Provides UI components (entity tabs, cards, routes).' :
+        type === 'backend' ? 'Provides backend routes and action providers.' :
+            'Provides both UI components and backend capabilities.'}
+
+## Installation
+
+In your ForgePortal monorepo:
+
+\`\`\`bash
+pnpm add ${names.packageName}
+\`\`\`
+
+Then register the plugin:
+
+${uiSection}
+
+${backendSection}
+
+## Configuration
+
+Add to \`forgeportal.yaml\`:
+
+\`\`\`yaml
+plugins:
+  ${names.pluginId}:
+    enabled: true
+    config:
+      apiEndpoint: "https://your-service.example.com"
+\`\`\`
+
+## Development
+
+\`\`\`bash
+pnpm install
+pnpm build      # compile TypeScript
+pnpm dev        # watch mode
+\`\`\`
+
+## License
+
+MIT
+`;
+}
+// ─── UI plugin templates ─────────────────────────────────────────────────────
+export function genUiIndex(names) {
+    return `import type { ForgePluginSDK } from '@forgeportal/plugin-sdk';
+import { ${names.pascalName}Tab } from './${names.pascalName}Tab.js';
+
+/**
+ * Register this plugin's UI capabilities with ForgePortal.
+ * Called at UI startup by apps/ui/src/plugins/index.ts.
+ *
+ * To register: registerPluginById('${names.pluginId}', registerPlugin)
+ */
+export function registerPlugin(sdk: ForgePluginSDK): void {
+  sdk.registerEntityTab({
+    id:        '${names.pluginId}-tab',
+    title:     '${names.title}',
+    component: ${names.pascalName}Tab,
+    appliesTo: { kinds: ['service'] }, // Adjust to your target entity kinds
+  });
+}
+`;
+}
+export function genUiTab(names) {
+    return `import { useEntity, useConfig } from '@forgeportal/plugin-sdk/react';
+
+/**
+ * ${names.title} entity tab.
+ * Rendered inside the entity detail page for entities of matching kinds.
+ *
+ * useEntity()        — access the current catalog entity
+ * useConfig<T>(key) — access plugin config from forgeportal.yaml
+ */
+export function ${names.pascalName}Tab() {
+  const { entity }     = useEntity();
+  const apiEndpoint    = useConfig<string>('apiEndpoint');
+
+  return (
+    <div className="p-4">
+      <h3 className="text-lg font-semibold mb-3">${names.title}</h3>
+
+      <div className="rounded-lg border border-gray-200 p-4 text-sm text-gray-600">
+        <p>Entity: <strong>{entity.name}</strong> ({entity.kind})</p>
+        {apiEndpoint && (
+          <p className="mt-1 text-xs text-gray-400">API: {apiEndpoint}</p>
+        )}
+      </div>
+
+      {/* TODO: Implement your plugin UI here */}
+      <p className="mt-4 text-sm text-gray-400 italic">
+        This is a generated placeholder — implement ${names.title} content above.
+      </p>
+    </div>
+  );
+}
+`;
+}
+// ─── Backend plugin templates ─────────────────────────────────────────────────
+export function genBackendIndex(names) {
+    return `import type { ForgeBackendPluginSDK } from '@forgeportal/plugin-sdk';
+import { ${names.camelName}Action } from './actions/${names.camelName}Action.js';
+
+/**
+ * Register this plugin's backend capabilities with ForgePortal.
+ * Called at API server startup by apps/api/src/plugins/plugin-loader.ts.
+ *
+ * To register: add "${names.packageName}" to pluginPackages.packages in forgeportal.yaml
+ */
+export function registerBackendPlugin(sdk: ForgeBackendPluginSDK): void {
+  // Register action providers (available in action runner and templates)
+  sdk.registerActionProvider(${names.camelName}Action);
+
+  // Register backend routes (mounted at /api/v1/plugins/${names.pluginId}/)
+  sdk.registerBackendRoute({
+    path: '/status',
+    async handler(fastify) {
+      fastify.get('/', async () => ({
+        status: 'ok',
+        plugin: '${names.pluginId}',
+      }));
+
+      // TODO: Add more routes here
+      // Example: fastify.get('/data/:entityId', async (request) => { ... });
+    },
+  });
+}
+`;
+}
+export function genBackendAction(names) {
+    return `import type { ActionProvider } from '@forgeportal/plugin-sdk';
+
+/**
+ * ${names.title} action provider.
+ * Registered as action ID: "${names.pluginId}.myAction@v1"
+ *
+ * Available in:
+ *   - Action runner (POST /api/v1/actions/run)
+ *   - Template steps (action: "${names.pluginId}.myAction@v1")
+ */
+export const ${names.camelName}Action: ActionProvider = {
+  id:      '${names.pluginId}.myAction',
+  version: 'v1',
+  schema: {
+    input: {
+      type: 'object',
+      properties: {
+        message: {
+          type:        'string',
+          title:       'Message',
+          description: 'The message to process',
+        },
+      },
+      required: ['message'],
+    },
+    output: {
+      type: 'object',
+      properties: {
+        result: { type: 'string', description: 'Action result' },
+      },
+    },
+  },
+
+  async handler(ctx, input) {
+    ctx.logger.info('Running ${names.pluginId}.myAction', { input });
+    await ctx.log('info', \`Processing: \${String(input['message'])}\`);
+
+    // Available context:
+    //   ctx.config.get<string>('apiEndpoint')  — plugin config
+    //   ctx.scm.getFile(repoUrl, path)          — SCM file access (read-only)
+    //   ctx.db.query(sql, params)               — DB read-only queries
+    //   ctx.acquireRepoLock(repoUrl)            — prevent concurrent SCM writes
+
+    // TODO: Implement your action logic here
+    const result = \`Processed: \${String(input['message'])}\`;
+
+    return {
+      status:  'success',
+      outputs: { result },
+      links:   [],
+    };
+  },
+};
+`;
+}
+export function genBackendRoutes(names) {
+    return `import type { FastifyInstance } from 'fastify';
+
+/**
+ * Backend routes for the ${names.title} plugin.
+ * Mounted at: /api/v1/plugins/${names.pluginId}/
+ *
+ * Import and use this in registerBackendPlugin:
+ *   sdk.registerBackendRoute({ path: '/...', handler: registerRoutes });
+ */
+export async function registerRoutes(fastify: FastifyInstance): Promise<void> {
+  // GET /api/v1/plugins/${names.pluginId}/status
+  fastify.get('/status', async () => ({
+    status: 'ok',
+    plugin: '${names.pluginId}',
+  }));
+
+  // TODO: Add your plugin routes here
+  // All routes in this function are automatically scoped to /api/v1/plugins/${names.pluginId}/
+  //
+  // Example:
+  // fastify.get('/data/:entityId', async (request) => {
+  //   const { entityId } = request.params as { entityId: string };
+  //   // fetch from your service ...
+  //   return { entityId, data: [...] };
+  // });
+}
+`;
+}
+// ─── Fullstack plugin templates ───────────────────────────────────────────────
+export function genFullstackUiIndex(names) {
+    return `import type { ForgePluginSDK } from '@forgeportal/plugin-sdk';
+import { ${names.pascalName}Card } from './${names.pascalName}Card.js';
+
+export function registerPlugin(sdk: ForgePluginSDK): void {
+  sdk.registerEntityCard({
+    id:        '${names.pluginId}-card',
+    title:     '${names.title}',
+    component: ${names.pascalName}Card,
+    appliesTo: { kinds: ['service'] },
+  });
+}
+`;
+}
+export function genFullstackCard(names) {
+    return `import { useEntity, useApi } from '@forgeportal/plugin-sdk/react';
+
+interface ${names.pascalName}Data {
+  // TODO: Define the shape of data returned by your backend route
+  message: string;
+}
+
+/**
+ * ${names.title} entity card.
+ * Fetches data from the backend route: GET /api/v1/plugins/${names.pluginId}/data/:entityId
+ */
+export function ${names.pascalName}Card() {
+  const { entity } = useEntity();
+  const { data, isPending, isError } = useApi<${names.pascalName}Data>(
+    \`/api/v1/plugins/${names.pluginId}/data/\${entity.id}\`
+  );
+
+  if (isPending) {
+    return (
+      <div className="p-3 text-sm text-gray-400 animate-pulse">
+        Loading ${names.title} data\u2026
+      </div>
+    );
+  }
+
+  if (isError || !data) {
+    return (
+      <div className="p-3 text-sm text-red-500">
+        Failed to load ${names.title} data.
+      </div>
+    );
+  }
+
+  return (
+    <div className="p-3 text-sm text-gray-700">
+      {/* TODO: Render your plugin data here */}
+      <pre className="text-xs bg-gray-50 rounded p-2 overflow-auto">
+        {JSON.stringify(data, null, 2)}
+      </pre>
+    </div>
+  );
+}
+`;
+}
+export function genFullstackBackendIndex(names) {
+    return `import type { ForgeBackendPluginSDK } from '@forgeportal/plugin-sdk';
+
+export function registerBackendPlugin(sdk: ForgeBackendPluginSDK): void {
+  sdk.registerBackendRoute({
+    path: '/',
+    async handler(fastify) {
+      // GET /api/v1/plugins/${names.pluginId}/data/:entityId
+      fastify.get('/data/:entityId', async (request) => {
+        const { entityId } = request.params as { entityId: string };
+
+        // TODO: Fetch data from your external service
+        return {
+          entityId,
+          message: 'Hello from ${names.title} plugin!',
+        };
+      });
+
+      fastify.get('/status', async () => ({
+        status: 'ok',
+        plugin: '${names.pluginId}',
+      }));
+    },
+  });
+}
+`;
+}
+//# sourceMappingURL=templates.js.map

package/dist/templates.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"templates.js","sourceRoot":"","sources":["../src/templates.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "create-forge-plugin",
+  "version": "1.0.0",
+  "description": "Scaffolder CLI for ForgePortal plugins — generate a new plugin in under 2 minutes.",
+  "type": "module",
+  "bin": {
+    "create-forge-plugin": "dist/index.js"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@clack/prompts": "^0.9.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22",
+    "tsx": "*",
+    "vitest": "*"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "keywords": [
+    "forgeportal",
+    "plugin",
+    "scaffolder",
+    "cli",
+    "idp"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsx src/index.ts",
+    "test": "vitest run",
+    "lint": "eslint src/",
+    "clean": "rm -rf dist"
+  }
+}