@ysk-kit/cli 1.2.2 → 1.2.3

package/package.json

@@ -1,14 +1,14 @@
 {
   "name": "@ysk-kit/cli",
-  "version": "1.2.2",
+  "version": "1.2.3",
   "type": "module",
   "bin": {
     "ysk-kit": "./dist/index.js",
     "yskk": "./dist/index.js"
   },
   "dependencies": {
-    "@ysk-kit/api-http": "1.2.2",
-    "@ysk-kit/contracts": "1.2.2",
+    "@ysk-kit/api-http": "1.2.3",
+    "@ysk-kit/contracts": "1.2.3",
     "zod": "^4.6.5"
   },
   "devDependencies": {

package/templates/agent/nested/api.md

@@ -8,3 +8,4 @@ Local notes for `apps/api`. Root law: `AGENTS.md`.
 - Envelope exceptions stay listed in the root guide. Do not add one silently.
 - Tests use in-memory ports. Do not start Redis, Stripe, Twilio, FCM, Jaeger, or Grafana.
 - Plan cases with `docs/skills/test-plan.md`. Write them with `docs/skills/write-tests.md`.
+- LLM product features: `docs/skills/llm-feature.md`. Red tests: `docs/skills/debug-issue.md`.

package/templates/agent/nested/contracts.md

@@ -8,3 +8,4 @@ Local notes for `@ysk-kit/contracts`. Root law: `AGENTS.md`.
 - Do not import apps, Prisma, Express, Fastify, React, or BullMQ.
 - After path changes run `pnpm gen:openapi`. Still call paths through `@ysk-kit/sdk`.
 - Contract tests live in this package. Follow `docs/skills/write-tests.md`.
+- DTO / path / error-code diffs: `docs/skills/contract-change.md`.

package/templates/agent/rules/api-modules.mdc

@@ -6,4 +6,4 @@ alwaysApply: false
 
 Local reminder. Law: `AGENTS.md` (also `apps/api/AGENTS.md`).
 
-Prisma stays in `src/modules/*/infra` and shared `src/infra`. Domain and application do not import Express, Fastify, Prisma, React, or BullMQ. JSON uses `{ ok: true, data }` / `{ ok: false, error }`. Tests use in-memory ports. Schema changes: `docs/skills/db-migration.md`.
+Prisma stays in `src/modules/*/infra` and shared `src/infra`. Domain and application do not import Express, Fastify, Prisma, React, or BullMQ. JSON uses `{ ok: true, data }` / `{ ok: false, error }`. Tests use in-memory ports. Schema changes: `docs/skills/db-migration.md`. LLM product features: `docs/skills/llm-feature.md`.

package/templates/agent/rules/contracts.mdc

@@ -6,4 +6,4 @@ alwaysApply: false
 
 Local reminder. Law: `AGENTS.md` (also `packages/contracts/AGENTS.md`).
 
-Add DTO + `OkSchema` / `ErrSchema` before handlers or clients. No TypeScript `enum`. This package does not import apps, Prisma, Express, Fastify, React, or BullMQ.
+Add DTO + `OkSchema` / `ErrSchema` before handlers or clients. No TypeScript `enum`. This package does not import apps, Prisma, Express, Fastify, React, or BullMQ. Contract diffs: `docs/skills/contract-change.md`.

package/templates/agent/rules/security.mdc

@@ -6,4 +6,4 @@ alwaysApply: false
 
 Local reminder. Law: `AGENTS.md`.
 
-Procedure: `docs/skills/security-review.md`. Org-scoped use cases check membership in `application/` (template: `requireBiller`). Never log OTP, JWT, Stripe `sk_`, or webhook secrets. Inbound webhooks: `docs/skills/webhook-handling.md`.
+Procedure: `docs/skills/security-review.md`. Org-scoped use cases check membership in `application/` (template: `requireBiller`). Never log OTP, JWT, Stripe `sk_`, or webhook secrets. Inbound webhooks: `docs/skills/webhook-handling.md`. LLM product prompts: `docs/skills/llm-feature.md`.

package/templates/agent/rules/tests.mdc

@@ -6,4 +6,4 @@ alwaysApply: false
 
 Local reminder. Law: `AGENTS.md`.
 
-Plan with `docs/skills/test-plan.md`, then write with `docs/skills/write-tests.md`. In-memory ports only. Assert `{ ok, data }` / `{ ok, error }`. Do not start Redis, Stripe, Twilio, FCM, Jaeger, or Grafana.
+Plan with `docs/skills/test-plan.md`, then write with `docs/skills/write-tests.md`. Red CI or a user report: `docs/skills/debug-issue.md`. In-memory ports only. Assert `{ ok, data }` / `{ ok, error }`. Do not start Redis, Stripe, Twilio, FCM, Jaeger, or Grafana.

package/templates/agent/skills/add-capability/SKILL.md

@@ -3,6 +3,15 @@ name: add-capability
 description: >
   Merge a catalogued YSK Kit capability (llm, team, billing, push, jobs, mail, …) with ysk-kit add.
   Use when the user wants ysk-kit add llm/team/billing/push, restore a thin capability, or /add-capability.
+  中文：加能力、llm、billing、push、doctor。
+  Do not use to invent a capability outside the catalogue or to add industry domain.
 ---
 
 Read `docs/skills/add-capability.md`. Law: `AGENTS.md`.
+
+1. Catalogue name only. `billing` needs `team` first.
+2. `pnpm ysk-kit add <name>`. Prisma → db-migration.
+3. Before production: billing→webhook-handling, llm→llm-feature, push credentials, apikey scope/rotation. Then doctor.
+Gotcha: second add is a no-op when the skip token exists.
+Verify: `pnpm ysk-kit doctor` then the five verify commands.
+Full steps: `docs/skills/add-capability.md`.

package/templates/agent/skills/add-module/SKILL.md

@@ -3,6 +3,15 @@ name: add-module
 description: >
   Add a hexagonal HTTP module with ysk-kit add module (contract, DTO, Express+Fastify, SDK, web page).
   Use when the user wants a new resource, new API route, ysk-kit add module, or /add-module.
+  中文：加模組、HTTP 切片、org 範圍、Express 與 Fastify 測試。
+  Do not use to mkdir apps/api/src/modules by hand or to restore llm/team/billing/push (add-capability).
 ---
 
 Read `docs/skills/add-module.md`. Law: `AGENTS.md`.
+
+1. `pnpm ysk-kit add module <kebab> --prisma --web`. Do not mkdir the slice.
+2. Fill DTO then `application/` rules. Schema → db-migration. Org-scoped: requireBiller + negative test.
+3. App tests on Express AND Fastify. Then verify-change.
+Gotcha: no parallel tree; no TypeScript enum; clients use the SDK only.
+Verify: `pnpm layers && pnpm typecheck && pnpm test && pnpm gen:openapi && pnpm ysk-kit check agent`
+Full steps: `docs/skills/add-module.md`.

package/templates/agent/skills/contract-change/SKILL.md

@@ -0,0 +1,19 @@
+---
+name: contract-change
+description: >
+  Change YSK Kit contracts first: breaking-change table, gen:openapi diff
+  (optional oasdiff), deprecation, new error codes, lockstep changeset bump.
+  Use when editing packages/contracts, ts-rest paths, DTOs, error codes,
+  OpenAPI, or a client-visible field.
+  中文：合約、OpenAPI、破壞性變更、錯誤碼、changeset。
+  Do not use for application-only rules with no DTO/path change, or for Prisma SQL (use db-migration).
+---
+
+Read `docs/skills/contract-change.md`. Law: `AGENTS.md`.
+
+1. Classify additive vs breaking. Ask before dropping a published field.
+2. Edit `@ysk-kit/contracts` first. `pnpm gen:openapi` then `git diff --exit-code docs/openapi.yaml`.
+3. Lockstep changeset (all 26) + CHANGELOG. Optional `npx oasdiff`.
+Gotcha: new error codes need ERROR_MESSAGE zh-HK+en and HTTP_STATUS.
+Verify: `pnpm --filter @ysk-kit/contracts test && pnpm gen:openapi`
+Full steps: `docs/skills/contract-change.md`.

package/templates/agent/skills/debug-issue/SKILL.md

@@ -0,0 +1,18 @@
+---
+name: debug-issue
+description: >
+  Debug a YSK Kit failure by building a red feedback loop first: memory-port
+  tests, then HTTP on Express AND Fastify, then SDK, then e2e, then git bisect.
+  Use when a test, CI job, or user report is red; a flake; or /debug-issue.
+  中文：除錯、紅燈迴圈、回歸測試、bisect、日誌遮罩。
+  Do not use for green-field features (plan-feature) or a security audit (security-review).
+---
+
+Read `docs/skills/debug-issue.md`. Law: `AGENTS.md`.
+
+1. Write or isolate a red test first (memory-port, then Express+Fastify HTTP).
+2. Triage by error code. Fix the cause. Keep the regression test.
+3. Climb to SDK / e2e / git bisect only if the lower loop cannot see it.
+Gotcha: do not log OTP/sk_/whsec_. Do not set RATE_LIMIT_MAX=0 in production.
+Verify: the named Vitest is green, then the five verify commands.
+Full steps: `docs/skills/debug-issue.md`.

package/templates/agent/skills/desktop-electron/SKILL.md

@@ -12,7 +12,9 @@ description: >
 
 Read `docs/skills/desktop-electron.md`. Law: `AGENTS.md`.
 
-1. Keep contextIsolation, nodeIntegration false, sandbox, webSecurity. Add CSP.
-2. Deny navigation / new windows by default; allowlist `https:` for openExternal.
-3. Validate IPC `senderFrame`. `safeStorage` only — no plaintext token fallback.
+1. Keep contextIsolation, nodeIntegration false, sandbox, webSecurity, session CSP.
+2. Deny unexpected navigation / window.open. Validate IPC `senderFrame`.
+3. `safeStorage` only; memory if unavailable. No plaintext token file.
+Gotcha: do not `openExternal` a renderer string without an allowlist.
+Verify: `pnpm --filter @ysk-kit/desktop test`
 Full steps: `docs/skills/desktop-electron.md`.

package/templates/agent/skills/envelope-api/SKILL.md

@@ -3,6 +3,15 @@ name: envelope-api
 description: >
   Keep YSK Kit JSON routes on { ok, data } / { ok, error } unless the change is one of the four exceptions.
   Use when adding a route, SSE, PDF, error shape, or /envelope-api.
+  中文：envelope、錯誤碼、AppError、webhook JSON。
+  Do not use to invent a parallel error JSON or a fifth envelope exception without asking.
 ---
 
 Read `docs/skills/envelope-api.md`. Law: `AGENTS.md`.
+
+1. DTO + OkSchema/ErrSchema first. `throw new AppError('<CODE>')`.
+2. JSON stays envelope. Exceptions: LLM SSE, invoice PDF 302, GET /docs, GET /openapi.json.
+3. Webhooks: still envelope, raw body, off ts-rest. Sync ERROR_MESSAGE zh-HK and en.
+Gotcha: ask before a fifth exception. New codes need HTTP_STATUS too.
+Verify: fixtures show `{ ok, data }` / `{ ok, error }`.
+Full steps: `docs/skills/envelope-api.md`.

package/templates/agent/skills/fix-layers/SKILL.md

@@ -3,6 +3,15 @@ name: fix-layers
 description: >
   Repair a pnpm layers (dependency-cruiser) failure without disabling hexagonal rules.
   Use when pnpm layers fails, a client imported Prisma, or /fix-layers.
+  中文：分層、dependency-cruiser、客戶端 Prisma。
+  Do not use to edit .dependency-cruiser.cjs without explicit approval.
 ---
 
 Read `docs/skills/fix-layers.md`. Law: `AGENTS.md`.
+
+1. Read the cruiser rule name (`clients-no-server-infra`, `domain-no-infra`, …).
+2. Move the import (SDK / port in infra / type in contracts). Do not disable the rule.
+3. Re-run `pnpm layers`, then verify-change.
+Gotcha: never edit `.dependency-cruiser.cjs` without explicit this-turn approval.
+Verify: `pnpm layers`
+Full steps: `docs/skills/fix-layers.md`.

package/templates/agent/skills/llm-feature/SKILL.md

@@ -0,0 +1,19 @@
+---
+name: llm-feature
+description: >
+  Build a YSK Kit LLM feature with a server-owned prompt, Zod-validated
+  output, untrusted-content delimiting, quota, and createFakeLlm evals.
+  Use when adding or changing /v1/llm, a product prompt, streaming, or ysk-kit add llm.
+  中文：LLM、system prompt、配額、createFakeLlm、評測。
+  Do not use for generic chat UI with no server prompt, or for a security
+  audit of non-LLM code (security-review).
+---
+
+Read `docs/skills/llm-feature.md`. Law: `AGENTS.md`.
+
+1. Client roles are user/assistant only (`LlmClientRoleSchema`). Server prepends `LLM_SYSTEM_PROMPT`.
+2. Fence untrusted user text. Parse structured output with Zod in application/.
+3. Quota `LLM_QUOTA_*` → RATE_LIMITED. Evals: ≥5 normal + ≥3 adversarial `createFakeLlm`. No live provider in CI.
+Gotcha: v1.2.2 already removed client `system` and added quota — describe current code, do not list those as gaps.
+Verify: `pnpm --filter @ysk-kit/api exec vitest run src/modules/llm`
+Full steps: `docs/skills/llm-feature.md`.

package/templates/agent/skills/new-product/SKILL.md

@@ -3,6 +3,15 @@ name: new-product
 description: >
   Scaffold a product from YSK Kit with create-ysk-app (flavor, preset, database).
   Use when the user wants a new product, create-ysk-app, or /new-product.
+  中文：開新產品、create-ysk-app、flavor、doctor。
+  Do not use to add a module inside this kit (add-module) or to invent a parallel monorepo.
 ---
 
 Read `docs/skills/new-product.md`. Law: `AGENTS.md`.
+
+1. Pick flavor (saas default; desktop / gateway / php-bridge / trading / static-web3).
+2. `pnpm create @ysk-kit/app <name> --preset thin --db mysql --flavor saas --yes`.
+3. migrate/seed when the flavor has an API. Run `pnpm ysk-kit doctor`.
+Gotcha: leave `eas.json` / `app.config.ts` projectId as `replace-me` for a human.
+Verify: `pnpm ysk-kit doctor`
+Full steps: `docs/skills/new-product.md`.

package/templates/agent/skills/plan-feature/SKILL.md

@@ -3,6 +3,15 @@ name: plan-feature
 description: >
   Write a YSK Kit feature plan to docs/plans/<yyyy-mm-dd>-<slug>.md before contracts and code.
   Use when the user wants a plan, plan.md, design, or a multi-surface change.
+  中文：計劃、plan.md、合約之前。
+  Do not use for typo-only or one-file mechanical renames.
 ---
 
 Read `docs/skills/plan-feature.md`. Law: `AGENTS.md`.
+
+1. Confirm a plan is required. Explore the tree (modules, contracts, SDK) first.
+2. `pnpm ysk-kit plan <slug>` and fill every template heading.
+3. `pnpm ysk-kit plan --check` both language files. Wait for approval.
+Gotcha: do not implement first and backfill. If rejected as too short, expand.
+Verify: `pnpm ysk-kit plan --check docs/plans/<date>-<slug>.md`
+Full steps: `docs/skills/plan-feature.md`.

package/templates/agent/skills/review-change/SKILL.md

@@ -0,0 +1,20 @@
+---
+name: review-change
+description: >
+  Review a YSK Kit diff on two axes: Law (AGENTS.md hard rules, definition of
+  done, Do-not list) and Spec (the dated plan's scope and checklist). Flag
+  high-risk items for a human.
+  Use when asked to review a PR, a branch vs main, or uncommitted work; or /review-change.
+  中文：審查、法律軸、計劃軸、高風險人工、合理化表。
+  Do not use for implementing the change (plan-feature) or a dedicated
+  security/Prisma deep dive (security-review, db-migration).
+---
+
+Read `docs/skills/review-change.md`. Law: `AGENTS.md`.
+
+1. Diff is the report. Score Law (hard rules/DoD/Do-not) and Spec (dated plan).
+2. Flag authz, webhooks, SQL DROP, secrets, LLM, breaking contracts for a human.
+3. Run verify-change. Fill the rationalization table (no empty reasons).
+Gotcha: do not self-approve high-risk; link security-review / db-migration.
+Verify: `pnpm layers && pnpm typecheck && pnpm test && pnpm gen:openapi && pnpm ysk-kit check agent`
+Full steps: `docs/skills/review-change.md`.

package/templates/agent/skills/test-plan/SKILL.md

@@ -5,6 +5,15 @@ description: >
   mapped to contract, memory-port, API, SDK, client, and Playwright layers.
   Use when the user asks how to test a feature, what cases to cover, or for a QA
   checklist before writing tests or shipping.
+  中文：測試計劃、風險、given/when/then。
+  Do not use for comment-only edits or to write the tests themselves (write-tests).
 ---
 
 Read `docs/skills/test-plan.md`. Law: `AGENTS.md`.
+
+1. Restate the change. Rank data loss, auth, money, tenancy, secrets first.
+2. Map each risk to a layer and file. Write given/when/then cases.
+3. Name in-memory fixtures and explicit out of scope. Then write-tests.
+Gotcha: do not start Redis or Stripe to plan tests. E2E stays thin.
+Verify: every case has layer + file; out of scope is written.
+Full steps: `docs/skills/test-plan.md`.

package/templates/agent/skills/ui-design/SKILL.md

@@ -4,6 +4,15 @@ description: >
   Design and implement YSK Kit UI with existing tokens, @ysk-kit/ui, WCAG 2.2 AA,
   forms mapped from the API envelope, and no generic AI-slop chrome.
   Use when adding or changing web, admin, mobile, or desktop screens.
+  中文：畫面、zinc、表單、可及性。
+  Do not use for API-only changes or to invent a second component library.
 ---
 
 Read `docs/skills/ui-design.md`. Law: `AGENTS.md`.
+
+1. Reuse `@ysk-kit/ui` zinc tokens (`rounded-md`, `h-9`). No new palette.
+2. Loading / empty / error / disabled. Forms: FormField + contracts Zod.
+3. WCAG 2.2 AA, `zh-HK` length, no raw fetch. Then ui-review.
+Gotcha: no purple gradients, no placeholder-as-label, no `div` buttons.
+Verify: ui-review checklist, then verify-change.
+Full steps: `docs/skills/ui-design.md`.

package/templates/agent/skills/ui-review/SKILL.md

@@ -4,6 +4,15 @@ description: >
   QA checklist before declaring YSK Kit UI work done: visual, a11y, responsive,
   states, copy, performance — with Playwright, keyboard, and axe verification.
   Use when finishing a screen or when the user asks to review UI / UX / a11y.
+  中文：UI 審查、鍵盤、375 視埠。
+  Do not use to design the screen (ui-design) or to treat one screenshot as proof.
 ---
 
 Read `docs/skills/ui-review.md`. Law: `AGENTS.md`.
+
+1. Walk visual, a11y, states, copy. Fail if any required box is unchecked.
+2. Keyboard-only on web/admin/desktop. Check 375 / 768 / 1280.
+3. Exercise the flow (click, type, submit). Screenshot is not proof.
+Gotcha: do not add axe or screenshot diffs to CI unless asked.
+Verify: checklist + `pnpm e2e` when login/shell changed.
+Full steps: `docs/skills/ui-review.md`.

package/templates/agent/skills/verify-change/SKILL.md

@@ -3,6 +3,15 @@ name: verify-change
 description: >
   Run the YSK Kit verification chain after every feature (layers, typecheck, test, OpenAPI, check agent).
   Use when finishing a change, after add module/capability, or /verify-change.
+  中文：驗證、layers、typecheck、OpenAPI、check agent。
+  Do not use to skip commands and claim done, or to start Redis/Stripe in unit tests.
 ---
 
 Read `docs/skills/verify-change.md`. Law: `AGENTS.md`.
+
+1. Run `pnpm layers && pnpm typecheck && pnpm test && pnpm gen:openapi && pnpm ysk-kit check agent`.
+2. `git diff --exit-code docs/openapi.yaml` (commit YAML if HTTP changed).
+3. Conditional: lint, check:links, zh pair, lockstep changeset, e2e.
+Gotcha: never claim done without running the five commands in this turn.
+Verify: emit the verification report in the skill output format.
+Full steps: `docs/skills/verify-change.md`.

package/templates/agent/skills/webhook-handling/SKILL.md

@@ -12,7 +12,9 @@ description: >
 
 Read `docs/skills/webhook-handling.md`. Law: `AGENTS.md`.
 
-1. Mount raw body before JSON parsers (Express + Fastify). Verify signature.
-2. Persist event id, return `{ ok: true, data: { received: true } }`, fulfil via jobs.
-3. Do not trust event order. Replay tests in memory; never call Stripe in CI.
+1. Mount raw body before JSON parsers on Express and Fastify.
+2. Verify HMAC; persist Stripe `event.id`; 200 envelope; skip duplicates.
+3. Replay tests in-memory. Do not call Stripe in CI.
+Gotcha: 401 on bad signature. Fulfilment should queue, not block the ack.
+Verify: `pnpm --filter @ysk-kit/api test`
 Full steps: `docs/skills/webhook-handling.md`.

package/templates/agent/skills/write-tests/SKILL.md

@@ -4,6 +4,15 @@ description: >
   Write professional YSK Kit tests: trophy per layer, in-memory ports, given/when/then,
   deterministic fixtures, envelope and authz cases, exact Vitest/Playwright commands.
   Use when adding tests, fixing a bug, or after test-plan.
+  中文：寫測試、Vitest、Playwright、回歸。
+  Do not use to plan cases (test-plan) or to start Redis/Stripe in CI.
 ---
 
 Read `docs/skills/write-tests.md`. Law: `AGENTS.md`.
+
+1. Put the case at the lowest layer that can fail it. Extend the generator test file.
+2. given/when/then; envelope `ok` / `error.code`; other-tenant negative when owned.
+3. Bug fixes: red regression test first. Express and Fastify for HTTP.
+Gotcha: in-memory ports only. Never mock Prisma from a client.
+Verify: `pnpm --filter @ysk-kit/<pkg> exec vitest run <file>`
+Full steps: `docs/skills/write-tests.md`.

package/templates/agent/ysk-kit.mdc

@@ -3,4 +3,4 @@ description: YSK Kit agent law — follow root AGENTS.md
 alwaysApply: true
 ---
 
-Follow `AGENTS.md` at the repo root (Chinese: `AGENTS.zh.md`). Do not copy that file here. Procedures: `docs/skills/`. Plan first when required: `pnpm ysk-kit plan <slug>` → `docs/plans/<yyyy-mm-dd>-<slug>.md`. New HTTP features start with `pnpm ysk-kit add module <kebab-name> --prisma --web`. Verify with `pnpm layers && pnpm typecheck && pnpm test && pnpm gen:openapi && pnpm ysk-kit check agent`. Security / Prisma / webhooks / Electron: `docs/skills/security-review.md`, `db-migration.md`, `webhook-handling.md`, `desktop-electron.md`.
+Follow `AGENTS.md` at the repo root (Chinese: `AGENTS.zh.md`). Do not copy that file here. Procedures: `docs/skills/`. Plan first when required: `pnpm ysk-kit plan <slug>` → `docs/plans/<yyyy-mm-dd>-<slug>.md`. New HTTP features start with `pnpm ysk-kit add module <kebab-name> --prisma --web`. Verify with `pnpm layers && pnpm typecheck && pnpm test && pnpm gen:openapi && pnpm ysk-kit check agent`. Daily loop: `contract-change`, `debug-issue`, `review-change`, `llm-feature`. Security / Prisma / webhooks / Electron: `docs/skills/security-review.md`, `db-migration.md`, `webhook-handling.md`, `desktop-electron.md`.