@zhama/tego-plugin-sdk 0.0.0-stage → 1.36.0

package/dist/scaffold.cjs

@@ -0,0 +1,523 @@
+"use strict";var u=Object.defineProperty;var i=(e,t)=>u(e,"name",{value:t,configurable:!0});var chunkC2OCOPZQ_cjs=require("./chunk-C2OCOPZQ.cjs"),fs=require("fs"),path=require("path"),PUBLISHED_SDK_PACKAGES={"@tego/plugin-access-ui":"@zhama/tego-plugin-access-ui","@tego/plugin-sdk":"@zhama/tego-plugin-sdk","@tego/ui":"@zhama/tego-ui"};function sdkSpec(e,t,n){if(n==="workspace")return"workspace:*";const o=PUBLISHED_SDK_PACKAGES[e];if(!o)throw new Error(`${e} is not a published SDK package`);return`npm:${o}@${t.hostApiRange}`}i(sdkSpec,"sdkSpec");var STANDALONE_PRETTIER={semi:!0,trailingComma:"es5",singleQuote:!0,printWidth:80,tabWidth:2,useTabs:!1,bracketSpacing:!0,bracketSameLine:!1,arrowParens:"avoid",endOfLine:"lf",quoteProps:"as-needed",jsxSingleQuote:!0,proseWrap:"preserve"},STANDALONE_GITIGNORE=`node_modules/
+build/
+dist/
+frontend/dist/
+backend/dist/
+claw/dist/
+coverage/
+.turbo/
+`,STANDALONE_PNPM_WORKSPACE=`allowBuilds:
+  esbuild: true
+`,STANDALONE_TSCONFIG_FILES={"tsconfig.base.json":{$schema:"https://json.schemastore.org/tsconfig",compilerOptions:{strict:!0,useUnknownInCatchVariables:!0,allowJs:!0,skipLibCheck:!0,forceConsistentCasingInFileNames:!0,resolveJsonModule:!0,isolatedModules:!0,verbatimModuleSyntax:!0,declaration:!0,declarationMap:!0,esModuleInterop:!0,incremental:!1,noUncheckedIndexedAccess:!0,moduleDetection:"force",exactOptionalPropertyTypes:!0,target:"ES2022",lib:["ES2022","DOM","DOM.Iterable"],module:"ESNext",moduleResolution:"bundler"},exclude:["node_modules"]},"tsconfig.frontend.json":{$schema:"https://json.schemastore.org/tsconfig",extends:"./tsconfig.base.json",compilerOptions:{target:"ES2020",lib:["ES2020","DOM","DOM.Iterable"],module:"ESNext",moduleResolution:"bundler",jsx:"react-jsx",noEmit:!1,declaration:!0,declarationMap:!0,outDir:"dist"}},"tsconfig.backend.json":{$schema:"https://json.schemastore.org/tsconfig",extends:"./tsconfig.base.json",compilerOptions:{target:"ES2022",lib:["ES2022"],module:"ESNext",moduleResolution:"bundler",types:["node"],noEmit:!1,declaration:!0,declarationMap:!0,outDir:"dist"}}};function tsconfigPreset(e,t){return t==="workspace"?`@tego/tsconfig/plugin-${e}.json`:`../tsconfig.${e}.json`}i(tsconfigPreset,"tsconfigPreset");var STANDALONE_ESLINT_CONFIG=`import js from '@eslint/js';
+import prettierConfig from 'eslint-config-prettier';
+import prettier from 'eslint-plugin-prettier';
+import reactHooks from 'eslint-plugin-react-hooks';
+import globals from 'globals';
+import tseslint from 'typescript-eslint';
+
+export default tseslint.config(
+  {
+    ignores: [
+      'build/**',
+      'dist/**',
+      '**/dist/**',
+      '.turbo/**',
+      'node_modules/**',
+    ],
+  },
+  js.configs.recommended,
+  ...tseslint.configs.recommended,
+  {
+    files: ['**/*.{ts,tsx,js,mjs}'],
+    languageOptions: {
+      globals: { ...globals.browser, ...globals.node },
+    },
+    plugins: { 'react-hooks': reactHooks, prettier },
+    rules: {
+      ...reactHooks.configs.recommended.rules,
+      'prettier/prettier': 'warn',
+    },
+  },
+  prettierConfig
+);
+`,STANDALONE_LINT_DEPENDENCIES={"@eslint/js":"^9.16.0","eslint-config-prettier":"^10.1.8","eslint-plugin-prettier":"^5.5.4","eslint-plugin-react-hooks":"^5.2.0",globals:"^15.13.0","typescript-eslint":"^8.17.0"};function standaloneRootFiles(){return[{path:".prettierrc.json",contents:json(STANDALONE_PRETTIER)},{path:".gitignore",contents:STANDALONE_GITIGNORE},{path:"pnpm-workspace.yaml",contents:STANDALONE_PNPM_WORKSPACE},...Object.entries(STANDALONE_TSCONFIG_FILES).map(([e,t])=>({path:e,contents:json(t)}))]}i(standaloneRootFiles,"standaloneRootFiles");var STANDALONE_TOOLCHAIN={"@typescript/native-preview":"7.0.0-dev.20260519.1",eslint:"^9.39.1",prettier:"^3.7.4",typescript:"^5.9.3"},SUPPORTED_LOCALES=["zh-CN","zh-TW","en","ja","ko","de","es","fr","it","pt"];function packageNameFor(e){return`@tego/plugin-${e.replace(/^tego-/,"")}`}i(packageNameFor,"packageNameFor");function keyNamespaceFor(e){return e.replace(/^tego-/,"")}i(keyNamespaceFor,"keyNamespaceFor");function json(e){return`${JSON.stringify(e,null,2)}
+`}i(json,"json");function manifest(e){const t=keyNamespaceFor(e.id),n=e.parts.includes("frontend"),o=e.parts.includes("backend"),a=e.parts.includes("claw"),s={};n&&(s.frontend={icon:"puzzle",nav:[{key:"home",labelKey:`${t}.nav.home`,icon:"layout-dashboard",order:0,path:"/home"}]}),o&&(s.backend={limits:{memoryMb:256,requestTimeoutMs:15e3}}),a&&(s.claw={hooks:{}});const r={manifestVersion:1,id:e.id,version:"0.1.0",displayName:{"zh-CN":e.displayNameZh,en:e.displayNameEn},description:{"zh-CN":e.descriptionZh,en:e.descriptionEn},author:"Tego"};return(n||o)&&(r.hostApiRange=e.hostApiRange),r.scope=e.scope,o&&(r.declares={database:!0}),r.parts=s,{path:"tego.plugin.json",contents:json(r)}}i(manifest,"manifest");function rootPackageJson(e,t){const n=e.parts.includes("frontend"),o=e.parts.includes("backend"),a=e.parts.includes("claw"),s=["tsgo --noEmit -p shared/tsconfig.json"];n&&s.push("tsgo --noEmit -p frontend/tsconfig.json"),o&&s.push("tsgo --noEmit -p backend/tsconfig.json"),a&&s.push("tsgo --noEmit -p claw/tsconfig.json");const r={"@tego/plugin-sdk":sdkSpec("@tego/plugin-sdk",e,t),"@types/node":"^22.10.1",vitest:"^4.1.10"};t==="workspace"&&Object.assign(r,{"@tego/eslint-config":"workspace:*","@tego/tsconfig":"workspace:*"}),n&&Object.assign(r,{"@tanstack/react-query":"^5.62.7","@tego/ui":sdkSpec("@tego/ui",e,t),"@types/react":"^19.2.1","@types/react-dom":"^19.2.1","lucide-react":"^0.469.0",react:"^19.0.0","react-dom":"^19.0.0","react-i18next":"15.4.1",vite:"^6.3.5"}),o&&Object.assign(r,{"@types/pg":"^8.11.10",hono:"^4.10.7",pg:"^8.13.1"}),a&&(r.typebox="1.3.16"),t==="npm"&&Object.assign(r,STANDALONE_TOOLCHAIN,STANDALONE_LINT_DEPENDENCIES);const c={name:packageNameFor(e.id),version:"0.1.0",private:!0,type:"module",description:e.descriptionEn,scripts:{build:"tego-plugin-pack",watch:"tego-plugin-pack --watch","type-check":s.join(" && "),lint:"eslint .","lint:fix":"eslint . --fix",test:"vitest run"},devDependencies:sortedRecord(r)};return{path:"package.json",contents:json(c)}}i(rootPackageJson,"rootPackageJson");function sortedRecord(e){const t={};for(const n of Object.keys(e).sort())t[n]=e[n];return t}i(sortedRecord,"sortedRecord");function eslintConfig(e){return e==="npm"?{path:"eslint.config.js",contents:STANDALONE_ESLINT_CONFIG}:{path:"eslint.config.js",contents:`import baseConfig from '@tego/eslint-config';
+
+export default [
+  ...baseConfig,
+  {
+    ignores: ['build/**', 'dist/**', '**/dist/**', '.turbo/**'],
+  },
+];
+`}}i(eslintConfig,"eslintConfig");function sharedFiles(e){return[{path:"shared/tsconfig.json",contents:json({extends:tsconfigPreset("backend",e),compilerOptions:{noEmit:!0,declaration:!1,declarationMap:!1},include:["**/*.ts"]})},{path:"shared/index.ts",contents:`export {};
+`}]}i(sharedFiles,"sharedFiles");function vitestConfig(){return{path:"vitest.config.ts",contents:`import { defineConfig } from 'vitest/config';
+
+/**
+ * Node environment, no jsdom: components are not unit tested here by policy
+ * (\`ui-no-unit-tests.mdc\`). Pure logic in shared/frontend/claw is tested along
+ * with backend SQL against a throwaway schema through \`createTestPluginHost\`.
+ *
+ * \`fileParallelism: false\` because each database-backed suite creates and drops
+ * a schema in one shared Postgres; running them concurrently works until two
+ * pick the same clock-derived name.
+ */
+export default defineConfig({
+  test: {
+    environment: 'node',
+    include: [
+      'shared/**/*.test.ts',
+      'backend/src/**/*.test.ts',
+      'claw/src/**/*.test.ts',
+      'frontend/src/**/*.test.ts',
+    ],
+    fileParallelism: false,
+    testTimeout: 20_000,
+    hookTimeout: 30_000,
+  },
+});
+`}}i(vitestConfig,"vitestConfig");function readme(e,t){if(t==="npm")return standaloneReadme(e);const n=packageNameFor(e.id);return{path:"README.md",contents:`# ${e.displayNameEn}
+
+${e.descriptionEn}
+
+Generated by \`pnpm plugin:new\`. The workflow, gates and local-dev loop are in
+[\`plugins/README.md\`](../README.md); the manifest and host API contracts are in
+[\`packages/plugin-sdk/README.md\`](../../packages/plugin-sdk/README.md).
+
+## Gates
+
+\`\`\`bash
+pnpm -F ${n} lint
+pnpm -F ${n} type-check
+pnpm -F ${n} test
+pnpm -F ${n} build
+\`\`\`
+
+Run \`pnpm install\` once after generating, so the new package links into the
+workspace and \`@tego/plugin-sdk\` resolves.
+`}}i(readme,"readme");function standaloneReadme(e){return{path:"README.md",contents:`# ${e.displayNameEn}
+
+${e.descriptionEn}
+
+A Tego plugin. The SDK packages are installed from npm under their \`@tego/*\`
+names (see \`devDependencies\`), so code reads the same as plugins built inside
+the Tego repository. The manifest, host API contracts and local-dev loop are
+documented in \`node_modules/@tego/plugin-sdk/README.md\`.
+
+## Gates
+
+\`\`\`bash
+npm install
+npm run lint
+npm run type-check
+npm test
+npm run build      # writes the uploadable archive
+\`\`\`
+
+\`hostApiRange\` in \`tego.plugin.json\` and the SDK ranges in \`package.json\`
+move together: raise both when the plugin starts using a newer host API.
+`}}i(standaloneReadme,"standaloneReadme");function frontendFiles(e,t){const n=keyNamespaceFor(e.id),o=`import { readFile, readdir } from 'node:fs/promises';
+import { resolve } from 'node:path';
+
+import { tegoPluginFrontend } from '@tego/plugin-sdk/vite';
+
+const config = tegoPluginFrontend({
+  entry: 'frontend/src/index.tsx',
+  outDir: 'frontend/dist',
+  pluginId: '${e.id}',
+});
+
+// The local override must serve translations from the same build as the UI.
+config.plugins!.push({
+  name: '${e.id}-locales',
+  async buildStart() {
+    const directory = resolve(import.meta.dirname, 'i18n');
+    for (const name of await readdir(directory)) {
+      if (!name.endsWith('.json')) continue;
+      const file = resolve(directory, name);
+      this.addWatchFile(file);
+      this.emitFile({
+        type: 'asset',
+        fileName: \`i18n/\${name}\`,
+        source: await readFile(file, 'utf8'),
+      });
+    }
+  },
+});
+export default config;
+`,a=json({extends:tsconfigPreset("frontend",t),compilerOptions:{rootDir:"..",noEmit:!0,declaration:!1,declarationMap:!1,types:["node"]},include:["src/**/*","vite.config.ts"],exclude:["node_modules"]}),s=`import { definePluginFrontend } from '@tego/plugin-sdk/frontend';
+import { createRoot } from 'react-dom/client';
+
+import { App } from './app';
+
+/**
+ * The frontend part's entry.
+ *
+ * React comes from the shell (\`SHARED_MODULE_IDS\`), so this root shares the
+ * host's instance \u2014 but not its providers: a root mounted here sits outside the
+ * shell's tree, so anything provider-shaped this plugin needs it establishes
+ * itself. \`App\` is where that happens.
+ */
+export default definePluginFrontend({
+  mount(el, ctx) {
+    const root = createRoot(el);
+    root.render(<App ctx={ctx} />);
+    return () => root.unmount();
+  },
+});
+`,r=`import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
+import { pluginI18nNamespace } from '@tego/plugin-sdk';
+import type { PluginHostContext } from '@tego/plugin-sdk/frontend';
+import { EmptyState } from '@tego/ui';
+import { Puzzle } from 'lucide-react';
+import { Component, type ReactNode, useMemo } from 'react';
+import { getI18n, I18nextProvider, useTranslation } from 'react-i18next';
+
+/**
+ * The plugin's own error boundary.
+ *
+ * The shell's boundary sits outside this React root and never sees an error
+ * thrown inside it, so without one here a screen that throws renders as a blank
+ * rectangle that reads like the platform lost the page.
+ */
+class PluginErrorBoundary extends Component<
+  { children: ReactNode; fallback: ReactNode },
+  { failed: boolean }
+> {
+  state = { failed: false };
+  static getDerivedStateFromError() {
+    return { failed: true };
+  }
+  render() {
+    return this.state.failed ? this.props.fallback : this.props.children;
+  }
+}
+
+function Home() {
+  const { t } = useTranslation();
+  return (
+    <EmptyState
+      icon={<Puzzle />}
+      title={t('${n}.home.title')}
+      description={t('${n}.home.description')}
+    />
+  );
+}
+
+/**
+ * The plugin's root.
+ *
+ * Two things the shell would normally provide have to be re-established here,
+ * because context does not cross React roots: a query client, and the i18n
+ * namespace this plugin's bundle was merged under. The theme is *not*
+ * re-established \u2014 it rides on the document's root class that \`@tego/ui\` reads.
+ */
+export function App({ ctx }: { ctx: PluginHostContext }) {
+  const queryClient = useMemo(() => new QueryClient(), []);
+  return (
+    <PluginErrorBoundary fallback={<EmptyState icon={<Puzzle />} title='\u2014' />}>
+      <QueryClientProvider client={queryClient}>
+        <I18nextProvider
+          i18n={getI18n()}
+          defaultNS={pluginI18nNamespace(ctx.pluginId)}
+        >
+          <Home />
+        </I18nextProvider>
+      </QueryClientProvider>
+    </PluginErrorBoundary>
+  );
+}
+`,c=[{path:"frontend/vite.config.ts",contents:o},{path:"frontend/tsconfig.json",contents:a},{path:"frontend/src/index.tsx",contents:s},{path:"frontend/src/app.tsx",contents:r}];for(const l of SUPPORTED_LOCALES){const d=l==="zh-CN",p={[n]:{nav:{home:d?"\u9996\u9875":"Home"},home:{title:d?e.displayNameZh:e.displayNameEn,description:d?e.descriptionZh:e.descriptionEn}}};c.push({path:`frontend/i18n/${l}.json`,contents:json(p)})}return c}i(frontendFiles,"frontendFiles");function backendFiles(e){return[{path:"backend/tsconfig.json",contents:json({extends:tsconfigPreset("backend",e),compilerOptions:{noEmit:!0,declaration:!1,declarationMap:!1,rootDir:".."},include:["src/**/*"],exclude:["node_modules"]})},{path:"backend/src/index.ts",contents:`import { serveBackend } from '@tego/plugin-sdk/server-runtime';
+
+import { backend } from './app';
+
+/**
+ * The backend part's entry, run as \`node index.js\` by the plugin runner.
+ *
+ * \`serveBackend\` owns the socket, the health path and the caller-context
+ * headers; everything below it is a plain fetch handler.
+ */
+serveBackend(backend);
+`},{path:"backend/src/app.ts",contents:`import { definePluginBackend } from '@tego/plugin-sdk/server';
+import type { PluginHostApi, PluginUserContext } from '@tego/plugin-sdk/server';
+import { Hono } from 'hono';
+
+/**
+ * The backend's HTTP surface, reached at \`/plugin-api/<id>/\`.
+ *
+ * The gateway authenticates the caller, strips their credentials and forwards
+ * what is left here, so there is no auth code below: \`ctx\` is already a
+ * resolved identity. The host capabilities (\`db\`, \`storage\`, \`events\`, \`log\`)
+ * arrive per request and are handed to handlers through \`c.env\`.
+ */
+interface Env {
+  Bindings: { host: PluginHostApi; user: PluginUserContext };
+}
+
+const app = new Hono<Env>();
+
+app.get('/ping', c => c.json({ ok: true }));
+
+app.get('/notes', async c => {
+  const notes = await c.env.host.db.query<{ id: string; body: string }>(
+    'SELECT id, body FROM notes ORDER BY created_at DESC'
+  );
+  return c.json({ notes });
+});
+
+app.post('/notes', async c => {
+  const { body } = await c.req.json<{ body?: unknown }>();
+  if (typeof body !== 'string' || body.trim() === '') {
+    return c.json({ error: 'body is required' }, 400);
+  }
+  const [row] = await c.env.host.db.query<{ id: string }>(
+    'INSERT INTO notes (author_id, body) VALUES ($1, $2) RETURNING id',
+    [c.env.user.userId, body]
+  );
+  return c.json({ id: row!.id }, 201);
+});
+
+export const backend = definePluginBackend({
+  async fetch(request, ctx, host) {
+    return app.fetch(request, { host, user: ctx });
+  },
+});
+`},{path:"backend/src/app.test.ts",contents:`import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import {
+  createTestPluginHost,
+  type TestPluginHost,
+} from '@tego/plugin-sdk/testing';
+import { afterAll, beforeEach, describe, expect, it } from 'vitest';
+
+import { backend } from './app';
+
+/**
+ * Business Cases
+ *
+ * The scaffold's backend is a starting point, so these guard the two things a
+ * generated plugin must get right before its author changes anything.
+ *
+ * SCAF-001  GET /ping answers 200 with { ok: true } \u2014 the liveness contract the
+ *           platform's health check depends on.
+ * SCAF-002  POST a note then GET the list round-trips through the plugin's own
+ *           schema: the write is visible on the next read, which only holds if
+ *           the migration applied and the scoped db writes where it reads.
+ * SCAF-003  POST with an empty body is refused with 400, not written \u2014 the one
+ *           negative branch the handler encodes.
+ */
+
+const migrationsDir = join(
+  dirname(fileURLToPath(import.meta.url)),
+  '..',
+  'migrations'
+);
+
+const CALLER = { userId: 'user_test', tenantId: 'tenant_test', roles: [] };
+
+function request(
+  host: TestPluginHost['host'],
+  method: string,
+  path: string,
+  body?: unknown
+): Promise<Response> {
+  // Built conditionally rather than \`body: undefined\`: RequestInit.body has no
+  // undefined member, so spelling it out fails the plugin's own type-check.
+  const init: RequestInit =
+    body === undefined
+      ? { method }
+      : {
+          method,
+          headers: { 'content-type': 'application/json' },
+          body: JSON.stringify(body),
+        };
+  return backend.fetch(
+    new Request(\`http://plugin.internal\${path}\`, init),
+    CALLER,
+    host
+  );
+}
+
+describe('scaffold backend', () => {
+  let harness: TestPluginHost;
+
+  beforeEach(async () => {
+    harness = await createTestPluginHost({
+      pluginId: 'scaffold',
+      migrationsDir,
+    });
+  });
+  afterAll(() => harness?.close());
+
+  it('[SCAF-001] answers /ping with 200 and { ok: true }', async () => {
+    const res = await request(harness.host, 'GET', '/ping');
+    expect(res.status).toBe(200);
+    expect(await res.json()).toEqual({ ok: true });
+  });
+
+  it('[SCAF-002] a posted note is visible on the next read', async () => {
+    const created = await request(harness.host, 'POST', '/notes', {
+      body: 'first note',
+    });
+    expect(created.status).toBe(201);
+    const { id } = (await created.json()) as { id: string };
+    expect(id).toMatch(/./);
+
+    const listed = await request(harness.host, 'GET', '/notes');
+    expect(listed.status).toBe(200);
+    expect(await listed.json()).toEqual({
+      notes: [{ id, body: 'first note' }],
+    });
+  });
+
+  it('[SCAF-003] refuses an empty body with 400 and writes nothing', async () => {
+    const res = await request(harness.host, 'POST', '/notes', { body: '  ' });
+    expect(res.status).toBe(400);
+
+    const listed = await request(harness.host, 'GET', '/notes');
+    expect(await listed.json()).toEqual({ notes: [] });
+  });
+});
+`},{path:"backend/migrations/0001_init.sql",contents:`-- The backend part's schema.
+--
+-- Applied by the host once, inside a transaction whose \`search_path\` is this
+-- install's own schema and nothing else. So nothing here is schema-qualified,
+-- nothing references a platform table, and there is no \`tenant_id\`: one schema
+-- per (tenant, plugin) install is the isolation boundary.
+--
+-- \`gen_random_uuid()\` is in \`pg_catalog\`, always on the path, so it needs no
+-- extension. Migrations are append-only \u2014 correct a past one with a new file.
+
+CREATE TABLE notes (
+  id text PRIMARY KEY DEFAULT gen_random_uuid(),
+  author_id text NOT NULL,
+  body text NOT NULL,
+  created_at timestamptz NOT NULL DEFAULT now()
+);
+`}]}i(backendFiles,"backendFiles");function clawFiles(e,t){const n=json({id:e.id,name:e.displayNameEn,description:e.descriptionEn,enabledByDefault:!0,activation:{onStartup:!0},configSchema:{type:"object",additionalProperties:!1,properties:{}}}),o=json({name:e.id,private:!0,type:"module",openclaw:{extensions:["./index.js"]},version:"0.1.0"}),a=`{
+  "extends": "${tsconfigPreset("backend",t)}",
+  "compilerOptions": {
+    "rootDir": "..",
+    "noEmit": true,
+    "declaration": false,
+    "declarationMap": false,
+    /*
+     * The claw part imports \`openclaw/plugin-sdk/*\`, resolved at runtime by
+     * claw's own alias map inside the container and not installable here. Types
+     * for those specifiers come from the local \`openclaw-plugin-sdk.d.ts\` shim.
+     */
+    "paths": {}
+  },
+  "include": ["src/**/*", "types/**/*"],
+  "exclude": ["node_modules"]
+}
+`,s=`/**
+ * The slice of claw's plugin SDK this extension uses.
+ *
+ * Declared here rather than imported because a plugin builds outside claw's
+ * workspace: \`openclaw/plugin-sdk/*\` is resolved at runtime by claw's own alias
+ * map inside the container, and claw ships no declaration files. Keep it narrow
+ * \u2014 only what \`claw/src\` calls \u2014 so it drifts on a small surface. Grow it as
+ * the plugin registers more; the full surface lives in \`plugins/tego-crm\`.
+ */
+
+declare module 'openclaw/plugin-sdk/tego' {
+  /**
+   * \`api.logger\` takes one string. A second structured argument throws inside
+   * claw (\`message.startsWith is not a function\`) \u2014 serialize context into it.
+   */
+  export interface OpenClawPluginLogger {
+    info(message: string): void;
+    warn(message: string): void;
+    error(message: string): void;
+    debug?(message: string): void;
+  }
+
+  /** A tool's parameter schema \u2014 claw's own \`TSchema\` from typebox. */
+  export type OpenClawToolSchema = import('typebox').TSchema;
+
+  export interface OpenClawToolResult<TDetails = unknown> {
+    content: { type: 'text'; text: string }[];
+    details: TDetails;
+  }
+
+  export interface OpenClawAgentTool {
+    name: string;
+    label: string;
+    description: string;
+    parameters: OpenClawToolSchema;
+    execute(
+      toolCallId: string,
+      params: unknown,
+      signal?: AbortSignal
+    ): Promise<OpenClawToolResult<unknown>>;
+  }
+
+  export interface OpenClawPluginApi {
+    readonly id: string;
+    /**
+     * Absent or partial during claw's early registration phases \u2014 only fields
+     * carrying a \`default\` in \`configSchema\` are present then. Always guard.
+     */
+    readonly pluginConfig?: Record<string, unknown>;
+    readonly logger: OpenClawPluginLogger;
+    /**
+     * Refused unless every registered name appears in the manifest's
+     * \`contracts.tools\` \u2014 and the refusal happens inside the container, at
+     * startup, where nobody is watching.
+     */
+    registerTool(tool: OpenClawAgentTool): void;
+  }
+
+  export interface DefinePluginEntryOptions {
+    id: string;
+    name: string;
+    description: string;
+    register(api: OpenClawPluginApi): void | Promise<void>;
+  }
+
+  export function definePluginEntry(
+    options: DefinePluginEntryOptions
+  ): DefinePluginEntryOptions;
+}
+
+declare module 'openclaw/plugin-sdk/tego-api' {
+  /**
+   * The hub is installed by claw's own tego plugin at startup. A plugin that
+   * registers tools before it exists produces tool calls that always fail, so
+   * check this in \`register()\` and skip registration instead.
+   */
+  export function isTegoApiInstalled(): boolean;
+}
+`,r=`import {
+  definePluginEntry,
+  type OpenClawPluginApi,
+} from 'openclaw/plugin-sdk/tego';
+import { isTegoApiInstalled } from 'openclaw/plugin-sdk/tego-api';
+
+/**
+ * The claw part's entry.
+ *
+ * \`register()\` runs once per agent during startup (dozens of times), so
+ * everything below it must be idempotent and free of global side effects. Tools
+ * reach the plugin's own backend through the tego API hub, which claw installs
+ * at startup \u2014 so if it is absent, skip registration rather than register tools
+ * that would fail on every call.
+ */
+export default definePluginEntry({
+  id: '${e.id}',
+  name: '${e.displayNameEn}',
+  description: '${e.descriptionEn}',
+  register(api: OpenClawPluginApi) {
+    if (!isTegoApiInstalled()) {
+      api.logger.warn(
+        '${e.id}: tego-api hub not installed \u2014 tools will not be registered'
+      );
+      return;
+    }
+    // Register tools here with \`api.registerTool(...)\`. Each tool's name must
+    // also appear in \`contracts.tools\` in \`openclaw.plugin.json\`, or claw
+    // refuses the registration.
+  },
+});
+`;return[{path:"claw/openclaw.plugin.json",contents:n},{path:"claw/package.json",contents:o},{path:"claw/tsconfig.json",contents:a},{path:"claw/types/openclaw-plugin-sdk.d.ts",contents:s},{path:"claw/src/index.ts",contents:r}]}i(clawFiles,"clawFiles");function buildPluginFiles(e,{dependencies:t="workspace"}={}){const n=[manifest(e),rootPackageJson(e,t),eslintConfig(t),...sharedFiles(t),vitestConfig(),readme(e,t)];return t==="npm"&&n.push(...standaloneRootFiles()),e.parts.includes("frontend")&&n.push(...frontendFiles(e,t)),e.parts.includes("backend")&&n.push(...backendFiles(t)),e.parts.includes("claw")&&n.push(...clawFiles(e,t)),n}i(buildPluginFiles,"buildPluginFiles");var PLUGIN_ID_PATTERN=/^[a-z0-9][a-z0-9._-]*$/,PLUGIN_PARTS=["frontend","backend","claw"],PLUGIN_SCOPES=["avatar","tenant"],PLUGIN_ID_HINT="lowercase letters and digits, may contain . _ -, starting with a letter or digit";function validatePluginAnswers(e,t){if(typeof e!="object"||e===null||Array.isArray(e))throw new Error("answers must be a JSON object");const n=e,o=i(c=>{const l=n[c];if(typeof l!="string"||l.trim()==="")throw new Error(`${c} is required`);return l.trim()},"text"),a=o("id");if(!PLUGIN_ID_PATTERN.test(a))throw new Error(`id must be ${PLUGIN_ID_HINT}`);const s=n.parts;if(!Array.isArray(s)||s.length===0||s.some(c=>!PLUGIN_PARTS.includes(c)))throw new Error(`parts must be a non-empty list of ${PLUGIN_PARTS.join(", ")}`);const r=n.scope??"avatar";if(!PLUGIN_SCOPES.includes(r))throw new Error(`scope must be one of ${PLUGIN_SCOPES.join(", ")}`);return{id:a,displayNameZh:o("displayNameZh"),displayNameEn:o("displayNameEn"),descriptionZh:o("descriptionZh"),descriptionEn:o("descriptionEn"),parts:[...new Set(s)],scope:r,hostApiRange:t}}i(validatePluginAnswers,"validatePluginAnswers");function writePlugin(e,t){return writePluginDirectory(path.join(e,"plugins"),t,buildPluginFiles(t))}i(writePlugin,"writePlugin");function writeStandalonePlugin(e,t){return writePluginDirectory(e,t,buildPluginFiles(t,{dependencies:"npm"}))}i(writeStandalonePlugin,"writeStandalonePlugin");function writePluginDirectory(e,t,n){const o=path.join(e,t.id);if(fs.existsSync(o))throw new Error(`${o} already exists \u2014 pick another id or remove it first`);fs.mkdirSync(e,{recursive:!0});const a=fs.mkdtempSync(path.join(e,`.${t.id}-`));try{for(const s of n){const r=path.join(a,s.path);fs.mkdirSync(path.dirname(r),{recursive:!0}),fs.writeFileSync(r,s.contents)}fs.renameSync(a,o)}catch(s){throw fs.rmSync(a,{recursive:!0,force:!0}),s}return{directory:o,files:n.map(s=>s.path)}}i(writePluginDirectory,"writePluginDirectory");function createStandalonePlugin(e,t){let n;try{n=JSON.parse(e)}catch(a){throw new Error(`answers must be JSON: ${a instanceof Error?a.message:String(a)}`)}const o=validatePluginAnswers(n,`^${chunkC2OCOPZQ_cjs.HOST_API_VERSION}`);return writeStandalonePlugin(path.resolve(t.cwd,t.parent),o)}i(createStandalonePlugin,"createStandalonePlugin"),exports.PLUGIN_ID_HINT=PLUGIN_ID_HINT,exports.PLUGIN_ID_PATTERN=PLUGIN_ID_PATTERN,exports.PLUGIN_PARTS=PLUGIN_PARTS,exports.PLUGIN_SCOPES=PLUGIN_SCOPES,exports.PUBLISHED_SDK_PACKAGES=PUBLISHED_SDK_PACKAGES,exports.STANDALONE_TSCONFIG_FILES=STANDALONE_TSCONFIG_FILES,exports.buildPluginFiles=buildPluginFiles,exports.createStandalonePlugin=createStandalonePlugin,exports.packageNameFor=packageNameFor,exports.validatePluginAnswers=validatePluginAnswers,exports.writePlugin=writePlugin,exports.writeStandalonePlugin=writeStandalonePlugin;