@kb-labs/scaffold 2.29.0

package/dist/manifest.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/manifest.ts"],"names":[],"mappings":"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","file":"manifest.js","sourcesContent":["import { combinePermissions, kbPlatformPreset } from '@kb-labs/sdk';\n\nconst permissions = combinePermissions()\n  .with(kbPlatformPreset)\n  .withFs({\n    mode: 'readWrite',\n    allow: [\n      '.kb/plugins/**',\n      '.kb/marketplace.lock',\n      'plugins/**',\n      'adapters/**',\n    ],\n  })\n  .withShell({\n    // Needed to call `kb marketplace plugins link` after scaffolding,\n    // so the generated plugin lands in .kb/marketplace.lock automatically.\n    allow: ['kb'],\n  })\n  .withQuotas({ timeoutMs: 120000, memoryMb: 256 })\n  .build();\n\nconst manifest = {\n  schema: 'kb.plugin/3',\n  id: '@kb-labs/scaffold',\n  version: '0.1.0',\n  display: {\n    name: 'Scaffold',\n    description:\n      'Generic entity scaffolder for KB Labs plugins, adapters, and friends.',\n    tags: ['scaffold', 'generator', 'dx'],\n  },\n  cli: {\n    groupMeta: [\n      { name: 'scaffold', describe: 'Scaffold KB Labs entities' },\n    ],\n    commands: [\n      {\n        id: 'run',\n        group: 'scaffold',\n        describe: 'Scaffold <entity> <name> from blocks',\n        handler: './commands/scaffold.js#default',\n        handlerPath: './commands/scaffold.js',\n        flags: [\n          {\n            name: 'blocks',\n            type: 'string',\n            description: 'Comma-separated block ids',\n          },\n          {\n            name: 'yes',\n            alias: 'y',\n            type: 'boolean',\n            description: 'Accept defaults and skip prompts',\n          },\n          {\n            name: 'force',\n            type: 'boolean',\n            description: 'Overwrite non-empty target directory',\n          },\n          {\n            name: 'dry-run',\n            type: 'boolean',\n            description: 'Print the tree that would be written and exit',\n          },\n          {\n            name: 'out',\n            type: 'string',\n            description: 'Override the output directory',\n          },\n          {\n            name: 'scope',\n            type: 'string',\n            description: 'npm scope for the generated package',\n          },\n          {\n            name: 'mode',\n            type: 'string',\n            description:\n              'Layout mode: \"in-workspace\" (workspace:* deps) or \"standalone\" (semver deps + pnpm-workspace.yaml)',\n          },\n        ],\n        examples: [\n          'kb scaffold run plugin my-plugin',\n          'kb scaffold run adapter my-llm --blocks base',\n          'kb scaffold run plugin ui --scope @acme --yes',\n          'kb scaffold run plugin demo --dry-run',\n        ],\n      },\n      {\n        id: 'doctor',\n        group: 'scaffold',\n        describe: 'Scan user plugins for common issues',\n        handler: './commands/doctor.js#default',\n        handlerPath: './commands/doctor.js',\n        flags: [\n          {\n            name: 'path',\n            type: 'string',\n            description: 'Path to scan (default: .kb/plugins)',\n          },\n          {\n            name: 'json',\n            type: 'boolean',\n            description: 'Emit JSON instead of text',\n          },\n        ],\n        examples: [\n          'kb scaffold doctor',\n          'kb scaffold doctor --path ./plugins',\n          'kb scaffold doctor --json',\n        ],\n      },\n    ],\n  },\n  permissions,\n} as const;\n\nexport default manifest;\n"]}

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@kb-labs/scaffold",
+  "version": "2.29.0",
+  "type": "module",
+  "description": "Generic entity scaffolder for KB Labs plugins, adapters, and friends.",
+  "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",
+    "templates"
+  ],
+  "sideEffects": false,
+  "dependencies": {
+    "@clack/prompts": "^0.11.0",
+    "@kb-labs/scaffold-contracts": "2.29.0",
+    "@kb-labs/scaffold-core": "2.29.0",
+    "@kb-labs/sdk": "2.18.1"
+  },
+  "devDependencies": {
+    "@types/node": "^24.3.3",
+    "eslint": "^9",
+    "rimraf": "^6.0.1",
+    "tsup": "^8.5.0",
+    "typescript": "^5.6.3",
+    "vitest": "^3.2.4",
+    "@kb-labs/devkit": "2.29.0",
+    "@kb-labs/plugin-contracts": "2.29.0"
+  },
+  "engines": {
+    "node": ">=20.0.0",
+    "pnpm": ">=9.0.0"
+  },
+  "scripts": {
+    "clean": "rimraf dist",
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "type-check": "tsc --noEmit",
+    "test": "vitest run --passWithNoTests",
+    "test:watch": "vitest",
+    "lint": "eslint src --ext .ts"
+  }
+}

package/templates/adapter/blocks/base/block.yaml

@@ -0,0 +1,4 @@
+id: base
+describe: |
+  Required. Single-package layout with a stub implementation and working
+  AdapterManifest. All imports go through @kb-labs/sdk/adapters.

package/templates/adapter/blocks/base/files/README.md.eta

@@ -0,0 +1,28 @@
+# <%= it.scope ? it.scope + '/' : '' %><%= it.name %>
+
+<%= it.vars.description %>
+
+## Layout
+
+```
+src/
+  index.ts      # createAdapter factory — instantiated by the host
+  manifest.ts   # AdapterManifest (id, type, what this adapter implements)
+```
+
+All imports come from `@kb-labs/sdk/adapters`. **Never** reach into
+`@kb-labs/core-platform` directly — that's internal and will break on
+core majors. If you need something not re-exported by SDK, open an issue
+on `@kb-labs/sdk` rather than working around it.
+
+## Using it
+
+Register the adapter in your project's `.kb/kb.config.jsonc` (the host
+plugin will resolve this package via npm or `workspace:*`). Then the
+runtime wires it up to whichever capability it `implements`.
+
+## Health check
+
+```bash
+pnpm kb scaffold doctor --path .
+```

package/templates/adapter/blocks/base/files/package.json.eta

@@ -0,0 +1,37 @@
+{
+  "name": "<%= it.scope ? it.scope + '/' : '' %><%= it.name %>",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "<%= it.vars.description %>",
+  "license": "<%= it.vars.license %>",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./manifest": {
+      "import": "./dist/manifest.js",
+      "types": "./dist/manifest.d.ts"
+    }
+  },
+  "files": ["dist"],
+  "sideEffects": false,
+  "scripts": {
+    "clean": "rimraf dist",
+    "build": "tsup",
+    "type-check": "tsc --noEmit",
+    "test": "vitest run --passWithNoTests"
+  },
+  "dependencies": {
+    "@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/adapter/blocks/base/files/src/manifest.ts.eta

@@ -0,0 +1,24 @@
+import { defineAdapterManifest } from '@kb-labs/sdk/adapters';
+
+/**
+ * AdapterManifest for <%= it.name %>.
+ *
+ * `implements` names the capability interface this adapter provides
+ * (e.g. "ILLM", "ILogger", "ICache"). The host resolves adapters by this
+ * string at bind time.
+ *
+ * Types:
+ *  - "core"      — shipped with the platform, always available
+ *  - "extension" — third-party or in-project, opt-in via config
+ *  - "proxy"     — forwards calls to a remote runtime
+ */
+export const manifest = defineAdapterManifest({
+  manifestVersion: '1.0.0',
+  id: '<%= it.name %>',
+  name: '<%= it.name %>',
+  version: '0.1.0',
+  type: 'extension',
+  implements: 'ILLM',
+});
+
+export default manifest;

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

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

package/templates/adapter/blocks/base/files/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'],
+  dts: { resolve: true, skipLibCheck: true },
+  clean: true,
+  sourcemap: true,
+});

package/templates/adapter/blocks/base/files/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/adapter/blocks/provider-example/block.yaml

@@ -0,0 +1,6 @@
+id: provider-example
+describe: |
+  Adds a stub ILLM implementation showing how to wire an adapter factory
+  (createAdapter), how the manifest's `implements` string maps to the
+  interface, and how to declare capabilities. Requires `base`.
+requires: [base]

package/templates/adapter/blocks/provider-example/files/src/index.ts.eta

@@ -0,0 +1,6 @@
+export { manifest } from './manifest.js';
+export { createAdapter } from './llm.js';
+export type {
+  <%= it.name.replace(/(^|-)(\w)/g, (_, _s, c) => c.toUpperCase()) %>Config,
+} from './llm.js';
+export { default } from './manifest.js';

package/templates/adapter/blocks/provider-example/files/src/llm.ts.eta

@@ -0,0 +1,46 @@
+import type {
+  ILLM,
+  LLMOptions,
+  LLMResponse,
+  IDisposable,
+} from '@kb-labs/sdk/adapters';
+
+/**
+ * Minimal ILLM implementation.
+ *
+ * Replace the `complete` body with a real API call (OpenAI, Anthropic,
+ * local llama.cpp, whatever). `dispose` is called by the host on shutdown
+ * — use it to close connection pools, flush buffers, etc.
+ *
+ * Cookbook:
+ *   - Use `useLogger(ctx)` / `useCache(ctx)` from '@kb-labs/sdk' inside
+ *     the host, not here. Adapters should stay capability-focused.
+ *   - Declare streaming / batch support via AdapterCapabilities in the
+ *     manifest so the router can pick the right adapter for a request.
+ */
+export class <%= it.name.replace(/(^|-)(\w)/g, (_, _s, c) => c.toUpperCase()) %>LLM implements ILLM, IDisposable {
+  constructor(private readonly config: { apiKey?: string } = {}) {}
+
+  async complete(options: LLMOptions): Promise<LLMResponse> {
+    // TODO: call your provider here.
+    return {
+      text: `(stub) <%= it.name %> would answer: ${options.prompt}`,
+      model: 'stub',
+      usage: { promptTokens: 0, completionTokens: 0, totalTokens: 0 },
+    };
+  }
+
+  async dispose(): Promise<void> {
+    // TODO: tear down connections / flush buffers.
+  }
+}
+
+export interface <%= it.name.replace(/(^|-)(\w)/g, (_, _s, c) => c.toUpperCase()) %>Config {
+  apiKey?: string;
+}
+
+export function createAdapter(
+  config: <%= it.name.replace(/(^|-)(\w)/g, (_, _s, c) => c.toUpperCase()) %>Config = {},
+): ILLM {
+  return new <%= it.name.replace(/(^|-)(\w)/g, (_, _s, c) => c.toUpperCase()) %>LLM(config);
+}

package/templates/adapter/entity.yaml

@@ -0,0 +1,37 @@
+id: adapter
+displayName: KB Labs Adapter
+description: |
+  A KB Labs adapter: implements a replaceable platform capability (LLM,
+  logger, cache, storage, etc). Single package, everything imported
+  through @kb-labs/sdk/adapters — never from @kb-labs/core-platform.
+
+output: adapters/<%= it.name %>
+
+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 adapter
+    default: A KB Labs adapter
+  - name: license
+    type: string
+    describe: License identifier
+    default: MIT
+  - name: mode
+    type: select
+    describe: Where will this adapter live?
+    default: in-workspace
+    choices:
+      - value: in-workspace
+        label: Inside a KB Labs workspace (workspace:* deps)
+      - value: standalone
+        label: Standalone repo (semver-pinned deps)
+
+defaults:
+  blocks:
+    - base
+    - provider-example

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

@@ -0,0 +1,5 @@
+id: base
+describe: |
+  Required. Scaffolds the three-package layout (entry / core / contracts)
+  with a working `hello` CLI command and inline examples showing how to use
+  the LLM, cache, and logger from the platform.

package/templates/plugin/blocks/base/files/README.md.eta

@@ -0,0 +1,54 @@
+# <%= it.scope ? it.scope + '/' : '' %><%= it.name %>
+
+<%= it.vars.description %>
+
+## Layout
+
+```
+packages/
+  <%= it.name %>-contracts/   # public types (request/response shapes)
+  <%= it.name %>-core/        # pure business logic (testable in isolation)
+  <%= it.name %>-entry/       # V3 manifest + CLI command handlers
+```
+
+All three packages are published together. `entry` depends on `core`, `core`
+depends on `contracts`. The runtime discovers the plugin through the `"kb"`
+field in `<%= it.name %>-entry/package.json`.
+
+## Getting started
+
+```bash
+pnpm install
+pnpm -w build
+pnpm kb <%= it.name %> hello                # say hi
+pnpm kb <%= it.name %> hello --who=World    # same, explicit
+```
+
+## What to edit
+
+- **Business logic:** [packages/<%= it.name %>-core/src/hello.ts](./packages/<%= it.name %>-core/src/hello.ts)
+  Inline comments show how to call the LLM, use the cache, and log through
+  the platform — everything goes through `@kb-labs/sdk`, never through
+  `@kb-labs/core-*` or `@kb-labs/platform-*`.
+- **CLI surface:** [packages/<%= it.name %>-entry/src/manifest.ts](./packages/<%= it.name %>-entry/src/manifest.ts)
+  Add more commands by appending to `cli.commands[]` and creating a handler
+  in `src/commands/`.
+- **Shared types:** [packages/<%= it.name %>-contracts/src/index.ts](./packages/<%= it.name %>-contracts/src/index.ts)
+  Input/output shapes go here so `core` and `entry` agree on them.
+
+## Linking into a workspace (development)
+
+```bash
+pnpm kb marketplace plugins link .
+pnpm kb plugins clear-cache
+```
+
+## Health check
+
+```bash
+pnpm kb scaffold doctor --path .
+```
+
+## License
+
+<%= it.vars.license %>

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

@@ -0,0 +1,14 @@
+{
+  "name": "<%= it.scope ? it.scope + '/' : '' %><%= it.name %>",
+  "version": "0.1.0",
+  "private": true,
+  "description": "<%= it.vars.description %>",
+  "license": "<%= it.vars.license %>",
+  "type": "module",
+  "scripts": {
+    "build": "pnpm -r build",
+    "clean": "pnpm -r clean",
+    "type-check": "pnpm -r type-check",
+    "test": "pnpm -r test"
+  }
+}

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

@@ -0,0 +1,29 @@
+{
+  "name": "<%= it.scope ? it.scope + '/' : '' %><%= it.name %>-contracts",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Public types for <%= it.name %>",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": ["dist"],
+  "sideEffects": false,
+  "scripts": {
+    "clean": "rimraf dist",
+    "build": "tsup",
+    "type-check": "tsc --noEmit",
+    "test": "vitest run --passWithNoTests"
+  },
+  "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__-contracts/src/index.ts.eta

@@ -0,0 +1,14 @@
+/**
+ * Public contracts for <%= it.name %>.
+ *
+ * Keep this package tiny — it is the stable boundary between `-core` and
+ * `-entry`. If a type is only used inside one package, it does not belong here.
+ */
+
+export interface HelloInput {
+  who: string;
+}
+
+export interface HelloResult {
+  greeting: string;
+}

package/templates/plugin/blocks/base/files/packages/__name__-contracts/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__-contracts/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'],
+  dts: { resolve: true, skipLibCheck: true },
+  clean: true,
+  sourcemap: true,
+});

package/templates/plugin/blocks/base/files/packages/__name__-contracts/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/packages/__name__-core/package.json.eta

@@ -0,0 +1,33 @@
+{
+  "name": "<%= it.scope ? it.scope + '/' : '' %><%= it.name %>-core",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Business logic for <%= it.name %> (pure, testable in isolation).",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "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 %>-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__-core/src/hello.ts.eta

@@ -0,0 +1,59 @@
+import type { HelloInput, HelloResult } from '<%= it.scope ? it.scope + '/' : '' %><%= it.name %>-contracts';
+
+/**
+ * Business logic for the `hello` command.
+ *
+ * This is a pure function so it can be unit-tested without any platform
+ * scaffolding. The handler in `-entry` is responsible for wiring platform
+ * services (logger, cache, LLM) and passing the results in — keep this
+ * function free of side effects.
+ */
+export function hello(input: HelloInput): HelloResult {
+  const who = input.who?.trim() || 'World';
+  return { greeting: `Hello, ${who} from <%= it.name %>!` };
+}
+
+/*
+ * ───────────────────────────────────────────────────────────────────────────
+ *  Cookbook: reach for these patterns when you grow past "hello".
+ *  Everything flows through `@kb-labs/sdk` — DO NOT import from
+ *  `@kb-labs/core-*` or `@kb-labs/platform-*` directly.
+ * ───────────────────────────────────────────────────────────────────────────
+ */
+
+// ── 1. Call an LLM ─────────────────────────────────────────────────────────
+//
+// import { useLLM, type PluginContextV3 } from '@kb-labs/sdk';
+//
+// export async function greetWithLLM(ctx: PluginContextV3, who: string) {
+//   const llm = await useLLM(ctx);            // throws if no LLM adapter bound
+//   const res = await llm.complete({
+//     prompt: `Write a one-line greeting for ${who}.`,
+//     maxTokens: 40,
+//   });
+//   return res.text;
+// }
+
+// ── 2. Cache the result ────────────────────────────────────────────────────
+//
+// import { useCache, type PluginContextV3 } from '@kb-labs/sdk';
+//
+// export async function cachedGreeting(ctx: PluginContextV3, who: string) {
+//   const cache = await useCache(ctx);        // namespaced per plugin
+//   const key = `greeting:${who}`;
+//   const hit = await cache.get<string>(key);
+//   if (hit) return hit;
+//
+//   const greeting = `Hello, ${who}!`;
+//   await cache.set(key, greeting, { ttlMs: 60_000 });
+//   return greeting;
+// }
+
+// ── 3. Structured logging ──────────────────────────────────────────────────
+//
+// import { useLogger, type PluginContextV3 } from '@kb-labs/sdk';
+//
+// export function logGreeting(ctx: PluginContextV3, who: string) {
+//   const log = useLogger(ctx);
+//   log.info({ who }, 'computed greeting');
+// }

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

@@ -0,0 +1 @@
+export { hello } from './hello.js';

package/templates/plugin/blocks/base/files/packages/__name__-core/tests/hello.test.ts.eta

@@ -0,0 +1,16 @@
+import { describe, it, expect } from 'vitest';
+import { hello } from '../src/hello.js';
+
+describe('hello', () => {
+  it('greets a named person', () => {
+    expect(hello({ who: 'Kirill' })).toEqual({
+      greeting: 'Hello, Kirill from <%= it.name %>!',
+    });
+  });
+
+  it('falls back to World when empty', () => {
+    expect(hello({ who: '' })).toEqual({
+      greeting: 'Hello, World from <%= it.name %>!',
+    });
+  });
+});

package/templates/plugin/blocks/base/files/packages/__name__-core/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__-core/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'],
+  dts: { resolve: true, skipLibCheck: true },
+  clean: true,
+  sourcemap: true,
+});

package/templates/plugin/blocks/base/files/packages/__name__-core/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/packages/__name__-entry/eslint.config.js

@@ -0,0 +1,3 @@
+import nodePreset from '@kb-labs/devkit/eslint/node.js';
+
+export default [...nodePreset];