@zhama/tego-plugin-sdk 1.37.1 → 1.37.2

package/agent/rules.json

@@ -0,0 +1,500 @@
+{
+  "catalogVersion": 1,
+  "rules": [
+    {
+      "id": "TP-MAN-001",
+      "severity": "error",
+      "guide": "manifest.md",
+      "title": "tego.plugin.json is valid",
+      "appliesTo": [
+        "tego.plugin.json",
+        "package.json"
+      ],
+      "enforcedBy": "doctor"
+    },
+    {
+      "id": "TP-MAN-002",
+      "severity": "error",
+      "guide": "host-api-versions.md",
+      "title": "hostApiRange admits every host capability the code uses",
+      "appliesTo": [
+        "tego.plugin.json"
+      ],
+      "enforcedBy": "doctor"
+    },
+    {
+      "id": "TP-PKG-001",
+      "severity": "error",
+      "guide": "manifest.md",
+      "title": "SDK packages come from npm aliases or workspace links, never a plain @tego/* name",
+      "appliesTo": [
+        "tego.plugin.json",
+        "package.json"
+      ],
+      "enforcedBy": "doctor"
+    },
+    {
+      "id": "TP-PKG-002",
+      "severity": "warning",
+      "guide": "testing.md",
+      "title": "package.json has the lint, type-check, test and build gates",
+      "appliesTo": [
+        "**/*.test.ts"
+      ],
+      "enforcedBy": "doctor"
+    },
+    {
+      "id": "TP-PKG-003",
+      "severity": "error",
+      "guide": "manifest.md",
+      "title": "No imports of @tego/shared or host app code; only published packages",
+      "appliesTo": [
+        "tego.plugin.json",
+        "package.json"
+      ],
+      "enforcedBy": "doctor"
+    },
+    {
+      "id": "TP-CLAW-002",
+      "severity": "warning",
+      "guide": "claw.md",
+      "title": "Each claw skill's frontmatter name matches its folder",
+      "appliesTo": [
+        "claw/**"
+      ],
+      "enforcedBy": "doctor"
+    },
+    {
+      "id": "TP-DESK-001",
+      "severity": "error",
+      "guide": "desktop-web.md",
+      "title": "No eval or new Function (the desktop CSP refuses them)",
+      "appliesTo": [
+        "frontend/src/**"
+      ],
+      "enforcedBy": "doctor"
+    },
+    {
+      "id": "TP-DESK-002",
+      "severity": "error",
+      "guide": "desktop-web.md",
+      "title": "No addresses built from location.origin (tauri://localhost on desktop)",
+      "appliesTo": [
+        "frontend/src/**"
+      ],
+      "enforcedBy": "doctor"
+    },
+    {
+      "id": "TP-DESK-003",
+      "severity": "error",
+      "guide": "desktop-web.md",
+      "title": "External links open with ctx.openExternal, not window.open",
+      "appliesTo": [
+        "frontend/src/**"
+      ],
+      "enforcedBy": "doctor"
+    },
+    {
+      "id": "TP-DESK-004",
+      "severity": "error",
+      "guide": "desktop-web.md",
+      "title": "Files are saved with ctx.download, not <a download> or a.download",
+      "appliesTo": [
+        "frontend/src/**"
+      ],
+      "enforcedBy": "doctor"
+    },
+    {
+      "id": "TP-DESK-005",
+      "severity": "warning",
+      "guide": "desktop-web.md",
+      "title": "No streamed responses or EventSource from the frontend (the desktop proxy buffers; use ctx.events)",
+      "appliesTo": [
+        "frontend/src/**"
+      ],
+      "enforcedBy": "doctor"
+    },
+    {
+      "id": "TP-DESK-006",
+      "severity": "warning",
+      "guide": "desktop-web.md",
+      "title": "Clipboard writes go through ctx.copyText",
+      "appliesTo": [
+        "frontend/src/**"
+      ],
+      "enforcedBy": "doctor"
+    },
+    {
+      "id": "TP-WEB-001",
+      "severity": "error",
+      "guide": "desktop-web.md",
+      "title": "The frontend calls no third-party URL (the web CSP blocks it); call the backend, which declares egress",
+      "appliesTo": [
+        "frontend/src/**"
+      ],
+      "enforcedBy": "doctor"
+    },
+    {
+      "id": "TP-WEB-002",
+      "severity": "error",
+      "guide": "desktop-web.md",
+      "title": "No remote or injected scripts; everything ships in the bundle",
+      "appliesTo": [
+        "frontend/src/**"
+      ],
+      "enforcedBy": "doctor"
+    },
+    {
+      "id": "TP-WEB-003",
+      "severity": "error",
+      "guide": "frontend.md",
+      "title": "The frontend calls its backend through ctx.api (createApiClient), never a raw fetch of a path",
+      "appliesTo": [
+        "frontend/src/**"
+      ],
+      "enforcedBy": "doctor"
+    },
+    {
+      "id": "TP-WEB-004",
+      "severity": "error",
+      "guide": "desktop-web.md",
+      "title": "No cookie-based auth (document.cookie, hono/cookie); ctx.api carries the credentials",
+      "appliesTo": [
+        "frontend/src/**"
+      ],
+      "enforcedBy": "doctor"
+    },
+    {
+      "id": "TP-UI-001",
+      "severity": "error",
+      "guide": "ui.md",
+      "title": "Colors come from token classes: no hex, rgb(), palette classes or dark: overrides",
+      "appliesTo": [
+        "frontend/src/**/*.tsx",
+        "frontend/src/**/*.css"
+      ],
+      "enforcedBy": "doctor"
+    },
+    {
+      "id": "TP-UI-002",
+      "severity": "error",
+      "guide": "ui.md",
+      "title": "No direct @radix-ui/* imports; use @tego/ui",
+      "appliesTo": [
+        "frontend/src/**/*.tsx",
+        "frontend/src/**/*.css"
+      ],
+      "enforcedBy": "doctor"
+    },
+    {
+      "id": "TP-UI-003",
+      "severity": "error",
+      "guide": "ui.md",
+      "title": "The plugin's root element carries its scope class (.<pluginId>) when it compiles its own Tailwind",
+      "appliesTo": [
+        "frontend/src/**/*.tsx",
+        "frontend/src/**/*.css"
+      ],
+      "enforcedBy": "doctor"
+    },
+    {
+      "id": "TP-UI-004",
+      "severity": "error",
+      "guide": "frontend.md",
+      "title": "The frontend has its own error boundary",
+      "appliesTo": [
+        "frontend/src/**"
+      ],
+      "enforcedBy": "doctor"
+    },
+    {
+      "id": "TP-UI-005",
+      "severity": "warning",
+      "guide": "ui.md",
+      "title": "Interface copy stays within budget: explanations ≤ 24 characters, any string ≤ 40 (zh-CN)",
+      "appliesTo": [
+        "frontend/src/**/*.tsx",
+        "frontend/src/**/*.css"
+      ],
+      "enforcedBy": "doctor"
+    },
+    {
+      "id": "TP-I18N-001",
+      "severity": "error",
+      "guide": "i18n.md",
+      "title": "All ten locales, with the same keys as zh-CN, and every nav label defined",
+      "appliesTo": [
+        "frontend/i18n/**"
+      ],
+      "enforcedBy": "doctor"
+    },
+    {
+      "id": "TP-I18N-002",
+      "severity": "error",
+      "guide": "i18n.md",
+      "title": "Every locale value keeps the {{placeholders}} of zh-CN and is not empty",
+      "appliesTo": [
+        "frontend/i18n/**"
+      ],
+      "enforcedBy": "doctor"
+    },
+    {
+      "id": "TP-I18N-003",
+      "severity": "error",
+      "guide": "i18n.md",
+      "title": "Every literal t('…') key exists in zh-CN",
+      "appliesTo": [
+        "frontend/i18n/**"
+      ],
+      "enforcedBy": "doctor"
+    },
+    {
+      "id": "TP-I18N-004",
+      "severity": "warning",
+      "guide": "i18n.md",
+      "title": "Current terminology: 数字员工 / Employee, never 数字分身 / digital avatar",
+      "appliesTo": [
+        "frontend/i18n/**"
+      ],
+      "enforcedBy": "doctor"
+    },
+    {
+      "id": "TP-I18N-005",
+      "severity": "error",
+      "guide": "i18n.md",
+      "title": "tegoAccess.* strings are merged by pack; the plugin locales do not copy them",
+      "appliesTo": [
+        "frontend/i18n/**"
+      ],
+      "enforcedBy": "doctor"
+    },
+    {
+      "id": "TP-BE-001",
+      "severity": "error",
+      "guide": "backend.md",
+      "title": "Identity comes from the verified ctx, never from the raw x-tego-plugin-* headers",
+      "appliesTo": [
+        "backend/src/**"
+      ],
+      "enforcedBy": "doctor"
+    },
+    {
+      "id": "TP-BE-002",
+      "severity": "error",
+      "guide": "access.md",
+      "title": "No host role names in business code; ask the access engine",
+      "appliesTo": [
+        "shared/access.json",
+        "backend/src/access*.ts",
+        "backend/src/**/access/**"
+      ],
+      "enforcedBy": "doctor"
+    },
+    {
+      "id": "TP-BE-003",
+      "severity": "error",
+      "guide": "migrations.md",
+      "title": "Migrations are <ordinal>_<name>.sql with unique ordinals",
+      "appliesTo": [
+        "backend/migrations/**",
+        "backend/src/**/schema*.ts",
+        "backend/drizzle.config.ts"
+      ],
+      "enforcedBy": "doctor"
+    },
+    {
+      "id": "TP-BE-004",
+      "severity": "error",
+      "guide": "migrations.md",
+      "title": "Committed migrations are never edited or deleted",
+      "appliesTo": [
+        "backend/migrations/**",
+        "backend/src/**/schema*.ts",
+        "backend/drizzle.config.ts"
+      ],
+      "enforcedBy": "doctor"
+    },
+    {
+      "id": "TP-BE-005",
+      "severity": "warning",
+      "guide": "backend.md",
+      "title": "Backend errors are logged through host.log, not console",
+      "appliesTo": [
+        "backend/src/**"
+      ],
+      "enforcedBy": "doctor"
+    },
+    {
+      "id": "TP-BE-006",
+      "severity": "error",
+      "guide": "backend.md",
+      "title": "Configuration comes from host.config, never process.env",
+      "appliesTo": [
+        "backend/src/**"
+      ],
+      "enforcedBy": "doctor"
+    },
+    {
+      "id": "TP-BE-007",
+      "severity": "warning",
+      "guide": "backend.md",
+      "title": "The backend app turns every error into JSON with pluginErrorHandler",
+      "appliesTo": [
+        "backend/src/**"
+      ],
+      "enforcedBy": "doctor"
+    },
+    {
+      "id": "TP-ACC-001",
+      "severity": "error",
+      "guide": "access.md",
+      "title": "With an access catalog, a test asserts every route has a policy (assertRouteCoverage)",
+      "appliesTo": [
+        "shared/access.json",
+        "backend/src/access*.ts",
+        "backend/src/**/access/**"
+      ],
+      "enforcedBy": "doctor"
+    },
+    {
+      "id": "TP-ACC-002",
+      "severity": "error",
+      "guide": "access.md",
+      "title": "With an access catalog, start() reconciles it (reconcile(host))",
+      "appliesTo": [
+        "shared/access.json",
+        "backend/src/access*.ts",
+        "backend/src/**/access/**"
+      ],
+      "enforcedBy": "doctor"
+    },
+    {
+      "id": "TP-TEST-001",
+      "severity": "warning",
+      "guide": "testing.md",
+      "title": "The plugin has tests",
+      "appliesTo": [
+        "**/*.test.ts"
+      ],
+      "enforcedBy": "doctor"
+    },
+    {
+      "id": "TP-TEST-002",
+      "severity": "warning",
+      "guide": "testing.md",
+      "title": "Each test file starts with a Business Cases list",
+      "appliesTo": [
+        "**/*.test.ts"
+      ],
+      "enforcedBy": "doctor"
+    },
+    {
+      "id": "TP-TPL-001",
+      "severity": "error",
+      "guide": "agent-templates.md",
+      "title": "A template whose content changed raises its version (existing employees only see updates by version)",
+      "appliesTo": [
+        "templates/**"
+      ],
+      "enforcedBy": "doctor"
+    },
+    {
+      "id": "TP-TPL-002",
+      "severity": "warning",
+      "guide": "agent-templates.md",
+      "title": "usageGuide.summary is at most 30 characters and quickPrompts lists 3–4 prompts",
+      "appliesTo": [
+        "templates/**"
+      ],
+      "enforcedBy": "doctor"
+    }
+  ],
+  "guides": [
+    {
+      "file": "manifest.md",
+      "appliesTo": [
+        "tego.plugin.json",
+        "package.json"
+      ]
+    },
+    {
+      "file": "host-api-versions.md",
+      "appliesTo": [
+        "tego.plugin.json"
+      ]
+    },
+    {
+      "file": "desktop-web.md",
+      "appliesTo": [
+        "frontend/src/**"
+      ]
+    },
+    {
+      "file": "frontend.md",
+      "appliesTo": [
+        "frontend/src/**"
+      ]
+    },
+    {
+      "file": "ui.md",
+      "appliesTo": [
+        "frontend/src/**/*.tsx",
+        "frontend/src/**/*.css"
+      ]
+    },
+    {
+      "file": "i18n.md",
+      "appliesTo": [
+        "frontend/i18n/**"
+      ]
+    },
+    {
+      "file": "backend.md",
+      "appliesTo": [
+        "backend/src/**"
+      ]
+    },
+    {
+      "file": "storage.md",
+      "appliesTo": [
+        "backend/src/**/storage*",
+        "backend/src/**/upload*",
+        "backend/src/**/files*"
+      ]
+    },
+    {
+      "file": "migrations.md",
+      "appliesTo": [
+        "backend/migrations/**",
+        "backend/src/**/schema*.ts",
+        "backend/drizzle.config.ts"
+      ]
+    },
+    {
+      "file": "access.md",
+      "appliesTo": [
+        "shared/access.json",
+        "backend/src/access*.ts",
+        "backend/src/**/access/**"
+      ]
+    },
+    {
+      "file": "claw.md",
+      "appliesTo": [
+        "claw/**"
+      ]
+    },
+    {
+      "file": "testing.md",
+      "appliesTo": [
+        "**/*.test.ts"
+      ]
+    },
+    {
+      "file": "agent-templates.md",
+      "appliesTo": [
+        "templates/**"
+      ]
+    }
+  ]
+}

package/agent/skills/add-agent-template/SKILL.md

@@ -0,0 +1,19 @@
+---
+name: add-agent-template
+description: Add or update a 数字员工 template shipped with a Tego plugin (template.config.json, workspace files, usage guide, quick prompts, version). Use when the plugin should offer a ready-made employee or an existing template changes.
+---
+
+# Add or update an agent template
+
+Read first: `guides/agent-templates.md`, `guides/claw.md`.
+
+1. Create `templates/<key>/template.config.json`, `workspace/*.md` (IDENTITY, SOUL, AGENTS,
+   TOOLS…) and `avatar.png`; experts go in `experts/<id>/` matching `agents` (main first).
+2. Declare it in `tego.plugin.json` → `agentTemplates: [{ key, entry: "templates/<key>/template.json", icon }]`.
+3. Fill `content.usageGuide` (`summary` ≤ 30 characters, `setup` with host-checkable items only,
+   `outputs`, `boundaries`) and 3–4 `quickPrompts` with unique keys (TP-TPL-002). Plugin business
+   readiness goes through the manifest's `agentReadiness`, not the template.
+4. When changing an existing template, raise its `version` (TP-TPL-001), or existing employees
+   will not see the update.
+5. Rebuild `template.json` with `tego-plugin-pack templates` (never your own script) and commit it.
+6. Run `tego-plugin check`.

package/agent/skills/add-claw-tool/SKILL.md

@@ -0,0 +1,21 @@
+---
+name: add-claw-tool
+description: Add a tool (and the skill that teaches the employee to use it) to a Tego plugin's claw part. Use when the plugin's 数字员工 needs a new capability or an existing tool changes.
+---
+
+# Add a claw tool
+
+Read first: `guides/claw.md`, `guides/access.md`, `guides/testing.md`.
+
+1. Register the tool in `claw/src/index.ts`; `register()` is idempotent and tolerates
+   early-phase config. Log with `api.logger` (one string).
+2. The tool calls your backend through the Tego API request
+   (`/api/v1/tego-os/plugin-api/<id>/…`) with the delegation the runtime provides, so the backend
+   applies the user's permissions. If the employee needs a permission, declare `agent.requires`
+   in the catalog; never widen it silently.
+3. List the tool in `contracts.tools` in `tego.plugin.json`.
+4. Teach it in a skill: `claw/skills/<name>/SKILL.md` whose frontmatter `name` equals the folder
+   (TP-CLAW-002) and whose `description` says when to use it; every tool it mentions exists.
+5. Test with `assertClawSkills(skillsDir, toolNames)` and check the registered tools equal
+   `contracts.tools`.
+6. Run `tego-plugin check`.

package/agent/skills/add-i18n-strings/SKILL.md

@@ -0,0 +1,19 @@
+---
+name: add-i18n-strings
+description: Add or change user-visible text in a Tego plugin across all ten locales with matching keys and placeholders. Use whenever a change adds, renames or rewords any string the user sees.
+---
+
+# Add i18n strings
+
+Read first: `guides/i18n.md`, the copy rules in `guides/ui.md`.
+
+1. Add the key to `frontend/i18n/zh-CN.json` first, under the plugin's root key
+   (`notes.home.title`). Keep it short: explanations ≤ 24 characters, any string ≤ 40 (TP-UI-005).
+2. Add the same key to every other locale: `zh-TW en ja ko de es fr it pt` (TP-I18N-001), with a
+   real translation (not empty, not the zh-CN text) and exactly the same `{{placeholders}}`
+   (TP-I18N-002).
+3. Use the key literally (`t('notes.home.title')`) so doctor can verify it exists (TP-I18N-003);
+   for keys built at runtime, list every variant in a test.
+4. Say 数字员工 / Employee through `{{avatarTerm}}`, never 数字分身 / digital avatar (TP-I18N-004).
+   Never copy `tegoAccess.*` strings into the plugin (TP-I18N-005).
+5. Run `tego-plugin check` (`assertLocaleParity` in the i18n test keeps the files in step).

package/agent/skills/add-migration/SKILL.md

@@ -0,0 +1,22 @@
+---
+name: add-migration
+description: Change a Tego plugin's database schema with a new append-only migration generated from the drizzle schema. Use when adding or changing tables, columns or indexes.
+---
+
+# Add a database migration
+
+Read first: `guides/migrations.md`, `guides/storage.md`.
+
+1. **Never edit or delete a committed migration** (TP-BE-004): an install may have applied it.
+   Every change is a new file.
+2. Change the drizzle schema (`backend/src/**/schema*.ts`), then generate SQL with drizzle-kit and
+   copy it into place with `tego-plugin migrations sync`. Hand-write only what drizzle cannot
+   express (functions, triggers, RLS), in a new `<ordinal>_<name>.sql` with the next ordinal
+   (TP-BE-003).
+3. Keep data in your own schema (`host.db`); never reference another plugin's or the host's
+   tables.
+4. With an access catalog, the `tego_access_*` tables come from your own migration (re-export
+   `@tego/plugin-sdk/access/drizzle` in the schema before generating).
+5. **Test** the new SQL against a real database: `createTestPluginHost({ pluginId, migrationsDir })`
+   (`TEST_DATABASE_URL`) applies every migration from scratch.
+6. Run `tego-plugin migrations check` and `tego-plugin check`.

package/agent/skills/add-route-with-access/SKILL.md

@@ -0,0 +1,30 @@
+---
+name: add-route-with-access
+description: Add a backend route (with its permission, policy, validation and tests) to a Tego plugin. Use when the plugin needs a new API endpoint, a new action users can take, or data some users may see and others may not.
+---
+
+# Add a backend route with access control
+
+Read first: `guides/backend.md`, `guides/access.md`, `guides/testing.md`.
+
+1. **Decide who may call it.** Find or add the permission in the access catalog
+   (`shared/access.json`): a permission id, its scope, which built-in roles get it, and the host
+   role bindings. Raise the catalog `version` if the meaning of an existing permission changes.
+   Never check host role names in code (TP-BE-002).
+2. **Validate the input** with zod (`readBody` / `readQuery` from `@tego/plugin-sdk/hono`).
+3. **Write the route** in the backend Hono app with exactly one policy:
+   `policy.authenticated()`, `policy.permission('<id>')` or `policy.resource(...)` for a single
+   record; lists use `session.filter('<permission>', { alias })` in the SQL. `policy.public()` only
+   for routes listed in the manifest's `publicRoutes`.
+4. **Data and config:** only your schema through `host.db`; configuration from
+   `host.config.current()`, never `process.env` (TP-BE-006). Schema changes → the
+   `add-migration` skill.
+5. **Errors:** throw coded errors; the app's `app.onError(pluginErrorHandler())` turns them into
+   JSON (TP-BE-007). Log with `host.log`, never `console.error` (TP-BE-005).
+6. **Tests** (`backend/src/*.test.ts`, starting with a Business Cases list): an allow case and a
+   deny case for the permission, the happy path against `createTestPluginHost`, and keep
+   `assertRouteCoverage(app)` passing (TP-ACC-001).
+7. **Frontend:** call it through the `createApiClient` client (`ctx.api`), never a raw `fetch`
+   (TP-WEB-003); hide what the user may not do with `useAccess()` / `<Can>` (presentation only).
+8. **New strings** for permissions or errors go into all ten locales (`add-i18n-strings`).
+9. Run `tego-plugin check` and fix everything it reports.

package/agent/skills/add-screen/SKILL.md

@@ -0,0 +1,27 @@
+---
+name: add-screen
+description: Add a page or screen to a Tego plugin's frontend (route, navigation, data loading, UI with @tego/ui, i18n). Use when the user wants a new page, view, form, list or dashboard in the plugin.
+---
+
+# Add a frontend screen
+
+Read first: `guides/frontend.md`, `guides/ui.md`, `guides/desktop-web.md`, `guides/i18n.md`.
+
+1. **Route:** add the path to the pure `lib/route.ts` parser (`parseRoute(path, search)` returns a
+   union) and test it. Navigate with `ctx.navigate`; paths live under `ctx.basePath` and have no
+   dotted segment. If it is a top-level page, add a nav entry in `tego.plugin.json` with a
+   `labelKey` that exists in every locale.
+2. **Data:** load through the `createApiClient` client with TanStack Query; show errors with
+   `describeApiError(error, '<ns>')`. Live changes: `useLiveUpdates(...)` (ctx.events), never
+   `EventSource` (TP-DESK-005).
+3. **UI:** compose `@tego/ui` components, never `@radix-ui/*` (TP-UI-002). Colors only through
+   token classes, no hex or `dark:` (TP-UI-001). Status with text or an icon, not color alone;
+   ids, numbers and times in `font-mono tabular-nums`. No card inside a card.
+4. **Copy:** short labels (≤ 40 characters, explanations ≤ 24 in zh-CN, TP-UI-005); longer help
+   goes into an `InfoTip`; an empty state is one sentence and one action. Every string in all ten
+   locales (`add-i18n-strings`).
+5. **Shell differences:** links with `ctx.openExternal`, files with `ctx.download`, copying with
+   `ctx.copyText` (hostApiRange ^1.37.0 or feature-detect), never `location.origin`.
+6. **Access:** gate actions with `useAccess()` / `<Can>`; the backend still enforces them.
+7. Run `tego-plugin check`; open the toolbar's Dev preview to look at the page in the web and the
+   desktop shell.