@kb-labs/scaffold 2.29.0

package/templates/plugin/blocks/base/files/packages/__name__-entry/package.json.eta

@@ -0,0 +1,41 @@
+{
+  "name": "<%= it.scope ? it.scope + '/' : '' %><%= it.name %>-entry",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "V3 manifest + CLI handlers for <%= it.name %>",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./plugin-manifest": {
+      "import": "./dist/manifest.js",
+      "types": "./dist/manifest.d.ts"
+    }
+  },
+  "kb": {
+    "manifest": "./dist/manifest.js"
+  },
+  "files": ["dist"],
+  "sideEffects": false,
+  "scripts": {
+    "clean": "rimraf dist",
+    "build": "tsup",
+    "type-check": "tsc --noEmit",
+    "test": "vitest run --passWithNoTests"
+  },
+  "dependencies": {
+    "<%= it.scope ? it.scope + '/' : '' %><%= it.name %>-core": "<%= it.mode === 'in-workspace' ? 'workspace:*' : '^0.1.0' %>",
+    "<%= it.scope ? it.scope + '/' : '' %><%= it.name %>-contracts": "<%= it.mode === 'in-workspace' ? 'workspace:*' : '^0.1.0' %>",
+    "@kb-labs/sdk": "<%= it.mode === 'in-workspace' ? 'workspace:*' : '^' + it.versions.sdk %>"
+  },
+  "devDependencies": {
+    "@kb-labs/devkit": "<%= it.mode === 'in-workspace' ? 'workspace:*' : '^' + it.versions.devkit %>",
+    "rimraf": "^6.0.1",
+    "tsup": "^8.5.0",
+    "typescript": "^5.6.3",
+    "vitest": "^3.2.4"
+  }
+}

package/templates/plugin/blocks/base/files/packages/__name__-entry/src/commands/hello.ts.eta

@@ -0,0 +1,39 @@
+import { defineCommand, type PluginContextV3 } from '@kb-labs/sdk';
+import { hello } from '<%= it.scope ? it.scope + '/' : '' %><%= it.name %>-core';
+
+type HelloFlags = {
+  who?: string;
+  json?: boolean;
+};
+
+type HelloResult = {
+  exitCode: number;
+  result?: { greeting: string };
+};
+
+/**
+ * `kb <%= it.name %> hello` — prints a friendly greeting.
+ *
+ * This handler demonstrates the bare minimum: receive flags, call into
+ * `-core`, write output via `ctx.ui`. As you grow, reach for the patterns
+ * sketched inside `<%= it.name %>-core/src/hello.ts` — LLM calls, caching,
+ * structured logging — ALL through `@kb-labs/sdk`.
+ */
+export default defineCommand({
+  id: '<%= it.name %>:hello',
+  description: 'Say hello from <%= it.name %>',
+
+  handler: {
+    async execute(ctx: PluginContextV3, input: HelloFlags): Promise<HelloResult> {
+      const { greeting } = hello({ who: input.who ?? 'World' });
+
+      if (input.json) {
+        ctx.ui?.json?.({ greeting });
+      } else {
+        ctx.ui?.info?.(greeting);
+      }
+
+      return { exitCode: 0, result: { greeting } };
+    },
+  },
+});

package/templates/plugin/blocks/base/files/packages/__name__-entry/src/index.ts.eta

@@ -0,0 +1,4 @@
+// Re-export the manifest as a side-channel for tooling that imports the
+// package directly (e.g. the marketplace linker). The primary entry point
+// is the "kb.manifest" field in package.json pointing at ./dist/manifest.js.
+export { default as manifest } from './manifest.js';

package/templates/plugin/blocks/base/files/packages/__name__-entry/tsconfig.json

@@ -0,0 +1,8 @@
+{
+  "extends": "@kb-labs/devkit/tsconfig/node.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "dist"
+  },
+  "include": ["src"]
+}

package/templates/plugin/blocks/base/files/packages/__name__-entry/tsup.config.ts

@@ -0,0 +1,10 @@
+import { defineConfig } from 'tsup';
+import nodePreset from '@kb-labs/devkit/tsup/node';
+
+export default defineConfig({
+  ...nodePreset,
+  entry: ['src/index.ts', 'src/manifest.ts', 'src/commands/*.ts'],
+  dts: { resolve: true, skipLibCheck: true },
+  clean: true,
+  sourcemap: true,
+});

package/templates/plugin/blocks/base/files/packages/__name__-entry/vitest.config.ts

@@ -0,0 +1,12 @@
+import { defineConfig } from 'vitest/config';
+import baseConfig from '@kb-labs/devkit/vitest/node';
+
+export default defineConfig({
+  ...baseConfig,
+  test: {
+    ...baseConfig.test,
+    globals: true,
+    include: ['tests/**/*.test.ts', 'src/**/*.test.ts'],
+    environment: 'node',
+  },
+});

package/templates/plugin/blocks/base/files/pnpm-workspace.yaml.eta

@@ -0,0 +1,3 @@
+<% if (it.vars.mode === 'standalone') { %>packages:
+  - packages/*
+<% } else { %><!--@@scaffold:skip@@--><% } %>

package/templates/plugin/blocks/base/files/tsconfig.base.json

@@ -0,0 +1,3 @@
+{
+  "extends": "@kb-labs/devkit/tsconfig/base.json"
+}

package/templates/plugin/blocks/base/manifest.patch.yaml

@@ -0,0 +1,28 @@
+schema: kb.plugin/3
+id: "<%= it.scope ? it.scope + '/' : '' %><%= it.name %>"
+version: "0.1.0"
+display:
+  name: "<%= it.name %>"
+  description: "<%= it.vars.description %>"
+cli:
+  groupMeta:
+    - name: "<%= it.name %>"
+      description: "<%= it.vars.description %>"
+  commands:
+    - id: hello
+      group: "<%= it.name %>"
+      describe: "Say hello from <%= it.name %>"
+      handler: "./commands/hello.js#default"
+      handlerPath: "./commands/hello.js"
+      flags:
+        - name: who
+          type: string
+          description: "Who to greet"
+          default: World
+        - name: json
+          type: boolean
+          description: "Emit JSON instead of text"
+      examples:
+        - "kb <%= it.name %> hello"
+        - "kb <%= it.name %> hello --who=Developer"
+        - "kb <%= it.name %> hello --json"

package/templates/plugin/blocks/base/manifest.snippets.yaml

@@ -0,0 +1,4 @@
+imports:
+  - "import { combinePermissions, kbPlatformPreset } from '@kb-labs/sdk';"
+permissions:
+  - "with(kbPlatformPreset)"

package/templates/plugin/blocks/cli/block.yaml

@@ -0,0 +1,5 @@
+id: cli
+describe: |
+  Adds a second CLI command (`ping`) as an example of how to register
+  additional commands. Requires `base`.
+requires: [base]

package/templates/plugin/blocks/cli/files/packages/__name__-entry/src/commands/ping.ts.eta

@@ -0,0 +1,25 @@
+import { defineCommand, type PluginContextV3 } from '@kb-labs/sdk';
+
+type PingFlags = { json?: boolean };
+
+/**
+ * `kb <%= it.name %> ping` — a second command to show how to add more.
+ * Duplicate this file, add an entry in `manifest.ts` under `cli.commands[]`,
+ * and you have a new command.
+ */
+export default defineCommand({
+  id: '<%= it.name %>:ping',
+  description: 'Health ping for <%= it.name %>',
+
+  handler: {
+    async execute(ctx: PluginContextV3, input: PingFlags) {
+      const payload = { ok: true, at: new Date().toISOString() };
+      if (input.json) {
+        ctx.ui?.json?.(payload);
+      } else {
+        ctx.ui?.info?.(`pong @ ${payload.at}`);
+      }
+      return { exitCode: 0, result: payload };
+    },
+  },
+});

package/templates/plugin/blocks/cli/manifest.patch.yaml

@@ -0,0 +1,14 @@
+cli:
+  commands:
+    - id: ping
+      group: "<%= it.name %>"
+      describe: "Health ping for <%= it.name %>"
+      handler: "./commands/ping.js#default"
+      handlerPath: "./commands/ping.js"
+      flags:
+        - name: json
+          type: boolean
+          description: "Emit JSON instead of text"
+      examples:
+        - "kb <%= it.name %> ping"
+        - "kb <%= it.name %> ping --json"

package/templates/plugin/blocks/contracts/block.yaml

@@ -0,0 +1,5 @@
+id: contracts
+describe: |
+  Seeds the contracts package with a second types file (`events.ts`) to
+  demonstrate how to organise multiple type modules. Requires `base`.
+requires: [base]

package/templates/plugin/blocks/contracts/files/packages/__name__-contracts/src/events.ts.eta

@@ -0,0 +1,13 @@
+/**
+ * Example event shapes — expand as the plugin grows.
+ *
+ * Contracts are deliberately small: put ONLY the types that both `-core`
+ * and `-entry` need to agree on here. Internal types belong in their
+ * respective packages.
+ */
+
+export interface GreetingEmitted {
+  kind: '<%= it.name %>.greeting.emitted';
+  who: string;
+  at: string;
+}

package/templates/plugin/blocks/rest/block.yaml

@@ -0,0 +1,6 @@
+id: rest
+describe: |
+  Adds a REST route (`GET /<name>/hello`) backed by the same `-core` logic.
+  Routes are handled through the gateway when the host plugin runs.
+  Requires `base`.
+requires: [base]

package/templates/plugin/blocks/rest/files/packages/__name__-entry/src/rest/hello.ts.eta

@@ -0,0 +1,22 @@
+import { defineRoute, type PluginContextV3 } from '@kb-labs/sdk';
+import { hello } from '<%= it.scope ? it.scope + '/' : '' %><%= it.name %>-core';
+
+type HelloQuery = { who?: string };
+
+/**
+ * `GET /<%= it.name %>/hello?who=World` — the REST twin of the CLI command.
+ *
+ * Route handlers receive the parsed query/body through the second argument.
+ * Keep them thin: call into `-core`, return the response shape.
+ */
+export default defineRoute({
+  id: '<%= it.name %>:rest:hello',
+  description: 'Say hello over HTTP',
+
+  handler: {
+    async execute(_ctx: PluginContextV3, input: HelloQuery) {
+      const { greeting } = hello({ who: input.who ?? 'World' });
+      return { status: 200, body: { greeting } };
+    },
+  },
+});

package/templates/plugin/blocks/rest/manifest.patch.yaml

@@ -0,0 +1,9 @@
+rest:
+  basePath: "/<%= it.name %>"
+  routes:
+    - id: hello
+      method: GET
+      path: "/hello"
+      handler: "./rest/hello.js#default"
+      handlerPath: "./rest/hello.js"
+      describe: "Say hello over HTTP"

package/templates/plugin/entity.yaml

@@ -0,0 +1,39 @@
+id: plugin
+displayName: KB Labs Plugin
+description: |
+  A KB Labs plugin: three workspace packages (entry, core, contracts) that
+  register CLI commands, REST routes, Studio pages, or daemons via a V3
+  manifest. Everything extends @kb-labs/devkit configs and talks to the
+  platform exclusively through @kb-labs/sdk.
+
+output: .kb/plugins/<%= it.name %>
+manifestTarget: packages/<%= it.name %>-entry/src/manifest.ts
+
+variables:
+  - name: scope
+    type: string
+    describe: npm scope (e.g. @kb-labs, @acme). Leave blank for unscoped.
+    default: "@kb-labs"
+    validate: npmScope
+  - name: description
+    type: string
+    describe: Short description of the plugin
+    default: A KB Labs plugin
+  - name: license
+    type: string
+    describe: License identifier
+    default: MIT
+  - name: mode
+    type: select
+    describe: Where will this plugin live?
+    default: in-workspace
+    choices:
+      - value: in-workspace
+        label: Inside an existing KB Labs workspace (use workspace:* deps)
+      - value: standalone
+        label: Standalone repo (semver-pinned deps, own pnpm-workspace.yaml)
+
+defaults:
+  blocks:
+    - base
+    - cli