@zenrick/zenkit 0.0.0-stage → 0.5.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.claude-plugin/marketplace.json +19 -0
- package/.cursor-plugin/marketplace.json +22 -0
- package/INSTALL.md +73 -0
- package/LICENSE +202 -0
- package/NOTICE +5 -0
- package/README.md +69 -3
- package/TERMS.md +48 -0
- package/THIRD-PARTY-NOTICES.md +109 -0
- package/kit/agents/backend-specialist.md +263 -0
- package/kit/agents/code-archaeologist.md +106 -0
- package/kit/agents/database-architect.md +226 -0
- package/kit/agents/debugger.md +226 -0
- package/kit/agents/devops-engineer.md +242 -0
- package/kit/agents/documentation-writer.md +104 -0
- package/kit/agents/explorer-agent.md +73 -0
- package/kit/agents/frontend-specialist.md +593 -0
- package/kit/agents/game-developer.md +162 -0
- package/kit/agents/mobile-developer.md +377 -0
- package/kit/agents/orchestrator.md +489 -0
- package/kit/agents/penetration-tester.md +188 -0
- package/kit/agents/performance-optimizer.md +187 -0
- package/kit/agents/product-manager.md +112 -0
- package/kit/agents/product-owner.md +95 -0
- package/kit/agents/project-planner.md +409 -0
- package/kit/agents/qa-automation-engineer.md +103 -0
- package/kit/agents/security-auditor.md +170 -0
- package/kit/agents/seo-specialist.md +111 -0
- package/kit/agents/test-engineer.md +158 -0
- package/kit/bundles/agent-building.yaml +26 -0
- package/kit/bundles/backend-data.yaml +14 -0
- package/kit/bundles/base.yaml +10 -0
- package/kit/bundles/core.yaml +21 -0
- package/kit/bundles/kit-engenharia.yaml +8 -0
- package/kit/bundles/kit-lite.yaml +9 -0
- package/kit/bundles/security.yaml +11 -0
- package/kit/bundles/ship-run.yaml +16 -0
- package/kit/bundles/web-ui.yaml +18 -0
- package/kit/commands/docs.md +33 -0
- package/kit/commands/explain.md +41 -0
- package/kit/commands/fix.md +65 -0
- package/kit/commands/implement.md +35 -0
- package/kit/commands/refactor.md +59 -0
- package/kit/commands/review.md +55 -0
- package/kit/commands/test.md +63 -0
- package/kit/modules/bridge/rules/cross-ide-bridge.mdc +73 -0
- package/kit/modules/bridge/zenkit-layer.yaml +1 -0
- package/kit/modules/nexuscore/sections/convivencia.md +12 -0
- package/kit/modules/nexuscore/sections/memoria.md +9 -0
- package/kit/modules/nexuscore/skills/quadro-agentes/SKILL.md +186 -0
- package/kit/modules/nexuscore/zenkit-layer.yaml +1 -0
- package/kit/rules/ZENKIT.mdc +294 -0
- package/kit/rules/git.mdc +51 -0
- package/kit/rules/karpathy-guidelines.mdc +70 -0
- package/kit/rules/model-routing.mdc +89 -0
- package/kit/rules/security-headers.mdc +41 -0
- package/kit/rules/social-automation.mdc +69 -0
- package/kit/rules/toc.mdc +40 -0
- package/kit/skills/api-patterns/SKILL.md +95 -0
- package/kit/skills/api-patterns/api-style.md +42 -0
- package/kit/skills/api-patterns/auth.md +24 -0
- package/kit/skills/api-patterns/documentation.md +26 -0
- package/kit/skills/api-patterns/graphql.md +41 -0
- package/kit/skills/api-patterns/rate-limiting.md +31 -0
- package/kit/skills/api-patterns/references/backend/backend-api-design.md +495 -0
- package/kit/skills/api-patterns/references/backend/backend-architecture.md +454 -0
- package/kit/skills/api-patterns/references/backend/backend-authentication.md +338 -0
- package/kit/skills/api-patterns/references/backend/backend-code-quality.md +659 -0
- package/kit/skills/api-patterns/references/backend/backend-debugging.md +904 -0
- package/kit/skills/api-patterns/references/backend/backend-devops.md +494 -0
- package/kit/skills/api-patterns/references/backend/backend-mindset.md +387 -0
- package/kit/skills/api-patterns/references/backend/backend-performance.md +397 -0
- package/kit/skills/api-patterns/references/backend/backend-security.md +290 -0
- package/kit/skills/api-patterns/references/backend/backend-technologies.md +256 -0
- package/kit/skills/api-patterns/references/backend/backend-testing.md +429 -0
- package/kit/skills/api-patterns/response.md +37 -0
- package/kit/skills/api-patterns/rest.md +40 -0
- package/kit/skills/api-patterns/scripts/api_validator.py +211 -0
- package/kit/skills/api-patterns/security-testing.md +122 -0
- package/kit/skills/api-patterns/trpc.md +41 -0
- package/kit/skills/api-patterns/versioning.md +22 -0
- package/kit/skills/app-builder/SKILL.md +76 -0
- package/kit/skills/app-builder/agent-coordination.md +71 -0
- package/kit/skills/app-builder/feature-building.md +53 -0
- package/kit/skills/app-builder/project-detection.md +34 -0
- package/kit/skills/app-builder/scaffolding.md +118 -0
- package/kit/skills/app-builder/tech-stack.md +41 -0
- package/kit/skills/app-builder/templates/SKILL.md +39 -0
- package/kit/skills/app-builder/templates/astro-static/TEMPLATE.md +76 -0
- package/kit/skills/app-builder/templates/chrome-extension/TEMPLATE.md +92 -0
- package/kit/skills/app-builder/templates/cli-tool/TEMPLATE.md +88 -0
- package/kit/skills/app-builder/templates/electron-desktop/TEMPLATE.md +88 -0
- package/kit/skills/app-builder/templates/express-api/TEMPLATE.md +83 -0
- package/kit/skills/app-builder/templates/flutter-app/TEMPLATE.md +90 -0
- package/kit/skills/app-builder/templates/monorepo-turborepo/TEMPLATE.md +90 -0
- package/kit/skills/app-builder/templates/nextjs-fullstack/TEMPLATE.md +122 -0
- package/kit/skills/app-builder/templates/nextjs-saas/TEMPLATE.md +122 -0
- package/kit/skills/app-builder/templates/nextjs-static/TEMPLATE.md +169 -0
- package/kit/skills/app-builder/templates/nuxt-app/TEMPLATE.md +134 -0
- package/kit/skills/app-builder/templates/python-fastapi/TEMPLATE.md +83 -0
- package/kit/skills/app-builder/templates/react-native-app/TEMPLATE.md +119 -0
- package/kit/skills/architecture/SKILL.md +56 -0
- package/kit/skills/architecture/context-discovery.md +43 -0
- package/kit/skills/architecture/examples.md +94 -0
- package/kit/skills/architecture/pattern-selection.md +68 -0
- package/kit/skills/architecture/patterns-reference.md +50 -0
- package/kit/skills/architecture/trade-off-analysis.md +77 -0
- package/kit/skills/bash-linux/SKILL.md +203 -0
- package/kit/skills/batch-operations/SKILL.md +112 -0
- package/kit/skills/behavioral-modes/SKILL.md +255 -0
- package/kit/skills/brainstorming/SKILL.md +189 -0
- package/kit/skills/brainstorming/dynamic-questioning.md +350 -0
- package/kit/skills/brainstorming/references/problem-solving/attribution.md +69 -0
- package/kit/skills/brainstorming/references/problem-solving/collision-zone-thinking.md +79 -0
- package/kit/skills/brainstorming/references/problem-solving/inversion-exercise.md +91 -0
- package/kit/skills/brainstorming/references/problem-solving/meta-pattern-recognition.md +87 -0
- package/kit/skills/brainstorming/references/problem-solving/scale-game.md +95 -0
- package/kit/skills/brainstorming/references/problem-solving/simplification-cascades.md +80 -0
- package/kit/skills/brainstorming/references/problem-solving/when-stuck.md +72 -0
- package/kit/skills/claude-exec/SKILL.md +185 -0
- package/kit/skills/clean-code/SKILL.md +210 -0
- package/kit/skills/code-review-checklist/SKILL.md +115 -0
- package/kit/skills/code-review-graph/SKILL.md +50 -0
- package/kit/skills/code-review-graph/references/alternatives-comparison.md +12 -0
- package/kit/skills/code-review-graph/references/best-practices.md +9 -0
- package/kit/skills/code-review-graph/references/configuration.md +43 -0
- package/kit/skills/code-review-graph/references/core-workflows.md +61 -0
- package/kit/skills/code-review-graph/references/how-it-works-4-layers.md +20 -0
- package/kit/skills/code-review-graph/references/installation.md +67 -0
- package/kit/skills/code-review-graph/references/integration-with-zenkit.md +23 -0
- package/kit/skills/code-review-graph/references/known-limitations.md +13 -0
- package/kit/skills/code-review-graph/references/when-to-use-vs-when-to-skip.md +21 -0
- package/kit/skills/codex-exec/SKILL.md +161 -0
- package/kit/skills/context-compression/SKILL.md +145 -0
- package/kit/skills/coordinator-mode/SKILL.md +215 -0
- package/kit/skills/cursor-exec/SKILL.md +152 -0
- package/kit/skills/database-design/SKILL.md +53 -0
- package/kit/skills/database-design/database-selection.md +43 -0
- package/kit/skills/database-design/indexing.md +39 -0
- package/kit/skills/database-design/migrations.md +48 -0
- package/kit/skills/database-design/optimization.md +36 -0
- package/kit/skills/database-design/orm-selection.md +30 -0
- package/kit/skills/database-design/schema-design.md +56 -0
- package/kit/skills/database-design/scripts/schema_validator.py +172 -0
- package/kit/skills/deployment-procedures/SKILL.md +242 -0
- package/kit/skills/deprecation-and-migration/SKILL.md +149 -0
- package/kit/skills/documentation-templates/SKILL.md +195 -0
- package/kit/skills/entrega-com-agentes/SKILL.md +177 -0
- package/kit/skills/frontend-design/NOTICE.md +6 -0
- package/kit/skills/frontend-design/SKILL.md +456 -0
- package/kit/skills/frontend-design/animation-guide.md +331 -0
- package/kit/skills/frontend-design/color-system.md +311 -0
- package/kit/skills/frontend-design/decision-trees.md +418 -0
- package/kit/skills/frontend-design/motion-graphics.md +306 -0
- package/kit/skills/frontend-design/references/aesthetic/design-guideline-template.md +163 -0
- package/kit/skills/frontend-design/references/aesthetic/design-principles.md +62 -0
- package/kit/skills/frontend-design/references/aesthetic/design-resources.md +75 -0
- package/kit/skills/frontend-design/references/aesthetic/design-story-template.md +135 -0
- package/kit/skills/frontend-design/references/aesthetic/micro-interactions.md +53 -0
- package/kit/skills/frontend-design/references/aesthetic/storytelling-design.md +50 -0
- package/kit/skills/frontend-design/scripts/accessibility_checker.py +183 -0
- package/kit/skills/frontend-design/scripts/ux_audit.py +722 -0
- package/kit/skills/frontend-design/typography-system.md +345 -0
- package/kit/skills/frontend-design/ux-psychology.md +1116 -0
- package/kit/skills/frontend-design/visual-effects.md +383 -0
- package/kit/skills/game-development/2d-games/SKILL.md +119 -0
- package/kit/skills/game-development/3d-games/SKILL.md +135 -0
- package/kit/skills/game-development/SKILL.md +168 -0
- package/kit/skills/game-development/game-art/SKILL.md +185 -0
- package/kit/skills/game-development/game-audio/SKILL.md +190 -0
- package/kit/skills/game-development/game-design/SKILL.md +129 -0
- package/kit/skills/game-development/mobile-games/SKILL.md +108 -0
- package/kit/skills/game-development/multiplayer/SKILL.md +132 -0
- package/kit/skills/game-development/pc-games/SKILL.md +144 -0
- package/kit/skills/game-development/vr-ar/SKILL.md +123 -0
- package/kit/skills/game-development/web-games/SKILL.md +150 -0
- package/kit/skills/gemini-exec/SKILL.md +80 -0
- package/kit/skills/geo-fundamentals/SKILL.md +157 -0
- package/kit/skills/geo-fundamentals/scripts/geo_checker.py +289 -0
- package/kit/skills/git-worktrees/SKILL.md +107 -0
- package/kit/skills/i18n-localization/SKILL.md +145 -0
- package/kit/skills/i18n-localization/scripts/i18n_checker.py +241 -0
- package/kit/skills/intelligent-routing/SKILL.md +128 -0
- package/kit/skills/intelligent-routing/references/4-response-format.md +16 -0
- package/kit/skills/intelligent-routing/references/complexity-assessment.md +29 -0
- package/kit/skills/intelligent-routing/references/debug-intelligent-routing.md +9 -0
- package/kit/skills/intelligent-routing/references/debugging-agent-selection.md +7 -0
- package/kit/skills/intelligent-routing/references/domain-detection-rules.md +29 -0
- package/kit/skills/intelligent-routing/references/edge-cases.md +29 -0
- package/kit/skills/intelligent-routing/references/implementation-rules.md +35 -0
- package/kit/skills/intelligent-routing/references/integration-with-existing-workflows.md +21 -0
- package/kit/skills/intelligent-routing/references/performance-considerations.md +14 -0
- package/kit/skills/intelligent-routing/references/summary.md +16 -0
- package/kit/skills/intelligent-routing/references/testing-the-system.md +36 -0
- package/kit/skills/intelligent-routing/references/tier-0-automatic-analysis-always-active.md +27 -0
- package/kit/skills/intelligent-routing/references/user-education.md +12 -0
- package/kit/skills/karpathy-guidelines/SKILL.md +67 -0
- package/kit/skills/karpathy-guidelines/references/EXAMPLES.md +522 -0
- package/kit/skills/lint-and-validate/SKILL.md +46 -0
- package/kit/skills/lint-and-validate/scripts/lint_runner.py +184 -0
- package/kit/skills/lint-and-validate/scripts/type_coverage.py +173 -0
- package/kit/skills/mcp-atuacao/SKILL.md +238 -0
- package/kit/skills/mcp-builder/NOTICE.md +6 -0
- package/kit/skills/mcp-builder/SKILL.md +259 -0
- package/kit/skills/memory-system/SKILL.md +181 -0
- package/kit/skills/mobile-design/SKILL.md +395 -0
- package/kit/skills/mobile-design/decision-trees.md +516 -0
- package/kit/skills/mobile-design/mobile-backend.md +491 -0
- package/kit/skills/mobile-design/mobile-color-system.md +420 -0
- package/kit/skills/mobile-design/mobile-debugging.md +122 -0
- package/kit/skills/mobile-design/mobile-design-thinking.md +357 -0
- package/kit/skills/mobile-design/mobile-navigation.md +458 -0
- package/kit/skills/mobile-design/mobile-performance.md +767 -0
- package/kit/skills/mobile-design/mobile-testing.md +356 -0
- package/kit/skills/mobile-design/mobile-typography.md +433 -0
- package/kit/skills/mobile-design/platform-android.md +666 -0
- package/kit/skills/mobile-design/platform-ios.md +561 -0
- package/kit/skills/mobile-design/scripts/mobile_audit.py +670 -0
- package/kit/skills/mobile-design/touch-psychology.md +537 -0
- package/kit/skills/negocio-agente-conversa/SKILL.md +168 -0
- package/kit/skills/negocio-atendimento/SKILL.md +134 -0
- package/kit/skills/negocio-linguagem/SKILL.md +166 -0
- package/kit/skills/negocio-preco/SKILL.md +174 -0
- package/kit/skills/negocio-preco/scripts/preco.mjs +160 -0
- package/kit/skills/negocio-qualificacao/SKILL.md +140 -0
- package/kit/skills/nextjs-react-expert/1-async-eliminating-waterfalls.md +351 -0
- package/kit/skills/nextjs-react-expert/2-bundle-bundle-size-optimization.md +240 -0
- package/kit/skills/nextjs-react-expert/3-server-server-side-performance.md +490 -0
- package/kit/skills/nextjs-react-expert/4-client-client-side-data-fetching.md +264 -0
- package/kit/skills/nextjs-react-expert/5-rerender-re-render-optimization.md +581 -0
- package/kit/skills/nextjs-react-expert/6-rendering-rendering-performance.md +432 -0
- package/kit/skills/nextjs-react-expert/7-js-javascript-performance.md +684 -0
- package/kit/skills/nextjs-react-expert/8-advanced-advanced-patterns.md +150 -0
- package/kit/skills/nextjs-react-expert/9-cache-components.md +103 -0
- package/kit/skills/nextjs-react-expert/SKILL.md +308 -0
- package/kit/skills/nextjs-react-expert/resources/app-patterns/common-patterns.md +331 -0
- package/kit/skills/nextjs-react-expert/resources/app-patterns/complete-examples.md +872 -0
- package/kit/skills/nextjs-react-expert/resources/app-patterns/component-patterns.md +502 -0
- package/kit/skills/nextjs-react-expert/resources/app-patterns/data-fetching.md +767 -0
- package/kit/skills/nextjs-react-expert/resources/app-patterns/file-organization.md +502 -0
- package/kit/skills/nextjs-react-expert/resources/app-patterns/loading-and-error-states.md +501 -0
- package/kit/skills/nextjs-react-expert/resources/app-patterns/performance.md +406 -0
- package/kit/skills/nextjs-react-expert/resources/app-patterns/routing-guide.md +364 -0
- package/kit/skills/nextjs-react-expert/resources/app-patterns/styling-guide.md +428 -0
- package/kit/skills/nextjs-react-expert/resources/app-patterns/typescript-standards.md +418 -0
- package/kit/skills/nextjs-react-expert/scripts/convert_rules.py +222 -0
- package/kit/skills/nextjs-react-expert/scripts/react_performance_checker.py +252 -0
- package/kit/skills/nodejs-best-practices/SKILL.md +78 -0
- package/kit/skills/nodejs-best-practices/references/10-anti-patterns-to-avoid.md +21 -0
- package/kit/skills/nodejs-best-practices/references/11-decision-checklist.md +14 -0
- package/kit/skills/nodejs-best-practices/references/2-runtime-considerations-2025.md +36 -0
- package/kit/skills/nodejs-best-practices/references/3-architecture-principles.md +35 -0
- package/kit/skills/nodejs-best-practices/references/4-error-handling-principles.md +42 -0
- package/kit/skills/nodejs-best-practices/references/5-async-patterns-principles.md +35 -0
- package/kit/skills/nodejs-best-practices/references/6-validation-principles.md +29 -0
- package/kit/skills/nodejs-best-practices/references/7-security-principles.md +29 -0
- package/kit/skills/nodejs-best-practices/references/8-testing-principles.md +28 -0
- package/kit/skills/observability-and-instrumentation/SKILL.md +150 -0
- package/kit/skills/opencode-go-exec/SKILL.md +101 -0
- package/kit/skills/parallel-agents/SKILL.md +184 -0
- package/kit/skills/performance-profiling/SKILL.md +145 -0
- package/kit/skills/performance-profiling/scripts/lighthouse_audit.py +76 -0
- package/kit/skills/plan-writing/SKILL.md +213 -0
- package/kit/skills/powershell-windows/SKILL.md +196 -0
- package/kit/skills/provider-orchestration/SKILL.md +269 -0
- package/kit/skills/python-patterns/SKILL.md +80 -0
- package/kit/skills/python-patterns/references/10-decision-checklist.md +14 -0
- package/kit/skills/python-patterns/references/11-anti-patterns-to-avoid.md +20 -0
- package/kit/skills/python-patterns/references/2-async-vs-sync-decision.md +44 -0
- package/kit/skills/python-patterns/references/3-type-hints-strategy.md +56 -0
- package/kit/skills/python-patterns/references/4-project-structure-principles.md +56 -0
- package/kit/skills/python-patterns/references/5-django-principles-2025.md +40 -0
- package/kit/skills/python-patterns/references/6-fastapi-principles.md +50 -0
- package/kit/skills/python-patterns/references/7-background-tasks.md +31 -0
- package/kit/skills/python-patterns/references/8-error-handling-principles.md +29 -0
- package/kit/skills/python-patterns/references/9-testing-principles.md +37 -0
- package/kit/skills/red-team-tactics/SKILL.md +201 -0
- package/kit/skills/research/SKILL.md +166 -0
- package/kit/skills/rust-pro/SKILL.md +177 -0
- package/kit/skills/seo-fundamentals/SKILL.md +130 -0
- package/kit/skills/seo-fundamentals/scripts/seo_checker.py +219 -0
- package/kit/skills/sequential-thinking/.env.example +8 -0
- package/kit/skills/sequential-thinking/README.md +183 -0
- package/kit/skills/sequential-thinking/SKILL.md +95 -0
- package/kit/skills/sequential-thinking/package.json +31 -0
- package/kit/skills/sequential-thinking/references/advanced-strategies.md +79 -0
- package/kit/skills/sequential-thinking/references/advanced-techniques.md +76 -0
- package/kit/skills/sequential-thinking/references/core-patterns.md +95 -0
- package/kit/skills/sequential-thinking/references/examples-api.md +88 -0
- package/kit/skills/sequential-thinking/references/examples-architecture.md +94 -0
- package/kit/skills/sequential-thinking/references/examples-debug.md +90 -0
- package/kit/skills/sequential-thinking/scripts/format-thought.js +159 -0
- package/kit/skills/sequential-thinking/scripts/process-thought.js +236 -0
- package/kit/skills/server-management/SKILL.md +162 -0
- package/kit/skills/simplify-code/SKILL.md +133 -0
- package/kit/skills/skillify/SKILL.md +116 -0
- package/kit/skills/system-design-interview/SKILL.md +268 -0
- package/kit/skills/systematic-debugging/SKILL.md +110 -0
- package/kit/skills/tailwind-patterns/SKILL.md +283 -0
- package/kit/skills/tailwind-patterns/references/shadcn-ui/canvas-design-system.md +320 -0
- package/kit/skills/tailwind-patterns/references/shadcn-ui/shadcn-accessibility.md +471 -0
- package/kit/skills/tailwind-patterns/references/shadcn-ui/shadcn-components.md +424 -0
- package/kit/skills/tailwind-patterns/references/shadcn-ui/shadcn-theming.md +373 -0
- package/kit/skills/tailwind-patterns/references/shadcn-ui/tailwind-customization.md +483 -0
- package/kit/skills/tailwind-patterns/references/shadcn-ui/tailwind-responsive.md +382 -0
- package/kit/skills/tailwind-patterns/references/shadcn-ui/tailwind-utilities.md +455 -0
- package/kit/skills/tdd-workflow/SKILL.md +150 -0
- package/kit/skills/testing-patterns/SKILL.md +196 -0
- package/kit/skills/testing-patterns/scripts/test_runner.py +219 -0
- package/kit/skills/ui-ux-pro-max/SKILL.md +135 -0
- package/kit/skills/verify-changes/SKILL.md +125 -0
- package/kit/skills/vulnerability-scanner/SKILL.md +278 -0
- package/kit/skills/vulnerability-scanner/checklists.md +121 -0
- package/kit/skills/vulnerability-scanner/scripts/security_scan.py +458 -0
- package/kit/skills/web-design-guidelines/SKILL.md +58 -0
- package/kit/skills/webapp-testing/NOTICE.md +6 -0
- package/kit/skills/webapp-testing/SKILL.md +188 -0
- package/kit/skills/webapp-testing/scripts/playwright_runner.py +173 -0
- package/kit/workflows/brainstorm.md +113 -0
- package/kit/workflows/coordinate.md +72 -0
- package/kit/workflows/create.md +59 -0
- package/kit/workflows/debug.md +103 -0
- package/kit/workflows/deploy.md +176 -0
- package/kit/workflows/enhance.md +63 -0
- package/kit/workflows/orchestrate.md +237 -0
- package/kit/workflows/plan.md +89 -0
- package/kit/workflows/preview.md +81 -0
- package/kit/workflows/remember.md +67 -0
- package/kit/workflows/status.md +86 -0
- package/kit/workflows/test.md +144 -0
- package/kit/workflows/ui-ux-pro-max.md +296 -0
- package/kit/workflows/verify.md +72 -0
- package/licenses/Apache-2.0.txt +202 -0
- package/package.json +60 -6
- package/scripts/avaliar-vigilancia-mandato.mjs +38 -0
- package/scripts/bundle.mjs +158 -0
- package/scripts/check-deps.mjs +178 -0
- package/scripts/check-models.mjs +150 -0
- package/scripts/cli.mjs +295 -0
- package/scripts/continuidade-mandato.mjs +47 -0
- package/scripts/discriminar-turno.mjs +191 -0
- package/scripts/doctor.mjs +615 -0
- package/scripts/generate.mjs +676 -0
- package/scripts/install.mjs +11 -0
- package/scripts/layer-remote.mjs +344 -0
- package/scripts/layers.mjs +208 -0
- package/scripts/marketplace.mjs +77 -0
- package/scripts/product.mjs +32 -0
- package/scripts/ruleset-core.mjs +68 -0
- package/scripts/social-hooks.mjs +293 -0
- package/scripts/social-pacer.mjs +219 -0
- package/scripts/validate-bundles.mjs +14 -0
- package/scripts/validate-skills.mjs +174 -0
- package/scripts/zenkit-daemon-task.cmd +3 -0
|
@@ -0,0 +1,184 @@
|
|
|
1
|
+
#!/usr/bin/env python3
|
|
2
|
+
"""
|
|
3
|
+
Lint Runner - Unified linting and type checking
|
|
4
|
+
Runs appropriate linters based on project type.
|
|
5
|
+
|
|
6
|
+
Usage:
|
|
7
|
+
python lint_runner.py <project_path>
|
|
8
|
+
|
|
9
|
+
Supports:
|
|
10
|
+
- Node.js: npm run lint, npx tsc --noEmit
|
|
11
|
+
- Python: ruff check, mypy
|
|
12
|
+
"""
|
|
13
|
+
|
|
14
|
+
import subprocess
|
|
15
|
+
import sys
|
|
16
|
+
import json
|
|
17
|
+
import platform
|
|
18
|
+
import shutil
|
|
19
|
+
from pathlib import Path
|
|
20
|
+
from datetime import datetime
|
|
21
|
+
|
|
22
|
+
# Fix Windows console encoding
|
|
23
|
+
try:
|
|
24
|
+
sys.stdout.reconfigure(encoding='utf-8', errors='replace')
|
|
25
|
+
except:
|
|
26
|
+
pass
|
|
27
|
+
|
|
28
|
+
|
|
29
|
+
def detect_project_type(project_path: Path) -> dict:
|
|
30
|
+
"""Detect project type and available linters."""
|
|
31
|
+
result = {
|
|
32
|
+
"type": "unknown",
|
|
33
|
+
"linters": []
|
|
34
|
+
}
|
|
35
|
+
|
|
36
|
+
# Node.js project
|
|
37
|
+
package_json = project_path / "package.json"
|
|
38
|
+
if package_json.exists():
|
|
39
|
+
result["type"] = "node"
|
|
40
|
+
try:
|
|
41
|
+
pkg = json.loads(package_json.read_text(encoding='utf-8'))
|
|
42
|
+
scripts = pkg.get("scripts", {})
|
|
43
|
+
deps = {**pkg.get("dependencies", {}), **pkg.get("devDependencies", {})}
|
|
44
|
+
|
|
45
|
+
# Check for lint script
|
|
46
|
+
if "lint" in scripts:
|
|
47
|
+
result["linters"].append({"name": "npm lint", "cmd": ["npm", "run", "lint"]})
|
|
48
|
+
elif "eslint" in deps:
|
|
49
|
+
result["linters"].append({"name": "eslint", "cmd": ["npx", "eslint", "."]})
|
|
50
|
+
|
|
51
|
+
# Check for TypeScript
|
|
52
|
+
if "typescript" in deps or (project_path / "tsconfig.json").exists():
|
|
53
|
+
result["linters"].append({"name": "tsc", "cmd": ["npx", "tsc", "--noEmit"]})
|
|
54
|
+
|
|
55
|
+
except:
|
|
56
|
+
pass
|
|
57
|
+
|
|
58
|
+
# Python project
|
|
59
|
+
if (project_path / "pyproject.toml").exists() or (project_path / "requirements.txt").exists():
|
|
60
|
+
result["type"] = "python"
|
|
61
|
+
|
|
62
|
+
# Check for ruff
|
|
63
|
+
result["linters"].append({"name": "ruff", "cmd": ["ruff", "check", "."]})
|
|
64
|
+
|
|
65
|
+
# Check for mypy
|
|
66
|
+
if (project_path / "mypy.ini").exists() or (project_path / "pyproject.toml").exists():
|
|
67
|
+
result["linters"].append({"name": "mypy", "cmd": ["mypy", "."]})
|
|
68
|
+
|
|
69
|
+
return result
|
|
70
|
+
|
|
71
|
+
|
|
72
|
+
def run_linter(linter: dict, cwd: Path) -> dict:
|
|
73
|
+
"""Run a single linter and return results."""
|
|
74
|
+
result = {
|
|
75
|
+
"name": linter["name"],
|
|
76
|
+
"passed": False,
|
|
77
|
+
"output": "",
|
|
78
|
+
"error": ""
|
|
79
|
+
}
|
|
80
|
+
|
|
81
|
+
try:
|
|
82
|
+
cmd = linter["cmd"]
|
|
83
|
+
|
|
84
|
+
# Windows compatibility for npm/npx
|
|
85
|
+
if platform.system() == "Windows":
|
|
86
|
+
if cmd[0] in ["npm", "npx"]:
|
|
87
|
+
# Force .cmd extension on Windows
|
|
88
|
+
if not cmd[0].lower().endswith(".cmd"):
|
|
89
|
+
cmd[0] = f"{cmd[0]}.cmd"
|
|
90
|
+
|
|
91
|
+
proc = subprocess.run(
|
|
92
|
+
cmd,
|
|
93
|
+
cwd=str(cwd),
|
|
94
|
+
capture_output=True,
|
|
95
|
+
text=True,
|
|
96
|
+
encoding='utf-8',
|
|
97
|
+
errors='replace',
|
|
98
|
+
timeout=120,
|
|
99
|
+
shell=platform.system() == "Windows" # Shell=True often helps with path resolution on Windows
|
|
100
|
+
)
|
|
101
|
+
|
|
102
|
+
result["output"] = proc.stdout[:2000] if proc.stdout else ""
|
|
103
|
+
result["error"] = proc.stderr[:500] if proc.stderr else ""
|
|
104
|
+
result["passed"] = proc.returncode == 0
|
|
105
|
+
|
|
106
|
+
except FileNotFoundError:
|
|
107
|
+
result["error"] = f"Command not found: {linter['cmd'][0]}"
|
|
108
|
+
except subprocess.TimeoutExpired:
|
|
109
|
+
result["error"] = "Timeout after 120s"
|
|
110
|
+
except Exception as e:
|
|
111
|
+
result["error"] = str(e)
|
|
112
|
+
|
|
113
|
+
return result
|
|
114
|
+
|
|
115
|
+
|
|
116
|
+
def main():
|
|
117
|
+
project_path = Path(sys.argv[1] if len(sys.argv) > 1 else ".").resolve()
|
|
118
|
+
|
|
119
|
+
print(f"\n{'='*60}")
|
|
120
|
+
print(f"[LINT RUNNER] Unified Linting")
|
|
121
|
+
print(f"{'='*60}")
|
|
122
|
+
print(f"Project: {project_path}")
|
|
123
|
+
print(f"Time: {datetime.now().strftime('%Y-%m-%d %H:%M:%S')}")
|
|
124
|
+
|
|
125
|
+
# Detect project type
|
|
126
|
+
project_info = detect_project_type(project_path)
|
|
127
|
+
print(f"Type: {project_info['type']}")
|
|
128
|
+
print(f"Linters: {len(project_info['linters'])}")
|
|
129
|
+
print("-"*60)
|
|
130
|
+
|
|
131
|
+
if not project_info["linters"]:
|
|
132
|
+
print("No linters found for this project type.")
|
|
133
|
+
output = {
|
|
134
|
+
"script": "lint_runner",
|
|
135
|
+
"project": str(project_path),
|
|
136
|
+
"type": project_info["type"],
|
|
137
|
+
"checks": [],
|
|
138
|
+
"passed": True,
|
|
139
|
+
"message": "No linters configured"
|
|
140
|
+
}
|
|
141
|
+
print(json.dumps(output, indent=2))
|
|
142
|
+
sys.exit(0)
|
|
143
|
+
|
|
144
|
+
# Run each linter
|
|
145
|
+
results = []
|
|
146
|
+
all_passed = True
|
|
147
|
+
|
|
148
|
+
for linter in project_info["linters"]:
|
|
149
|
+
print(f"\nRunning: {linter['name']}...")
|
|
150
|
+
result = run_linter(linter, project_path)
|
|
151
|
+
results.append(result)
|
|
152
|
+
|
|
153
|
+
if result["passed"]:
|
|
154
|
+
print(f" [PASS] {linter['name']}")
|
|
155
|
+
else:
|
|
156
|
+
print(f" [FAIL] {linter['name']}")
|
|
157
|
+
if result["error"]:
|
|
158
|
+
print(f" Error: {result['error'][:200]}")
|
|
159
|
+
all_passed = False
|
|
160
|
+
|
|
161
|
+
# Summary
|
|
162
|
+
print("\n" + "="*60)
|
|
163
|
+
print("SUMMARY")
|
|
164
|
+
print("="*60)
|
|
165
|
+
|
|
166
|
+
for r in results:
|
|
167
|
+
icon = "[PASS]" if r["passed"] else "[FAIL]"
|
|
168
|
+
print(f"{icon} {r['name']}")
|
|
169
|
+
|
|
170
|
+
output = {
|
|
171
|
+
"script": "lint_runner",
|
|
172
|
+
"project": str(project_path),
|
|
173
|
+
"type": project_info["type"],
|
|
174
|
+
"checks": results,
|
|
175
|
+
"passed": all_passed
|
|
176
|
+
}
|
|
177
|
+
|
|
178
|
+
print("\n" + json.dumps(output, indent=2))
|
|
179
|
+
|
|
180
|
+
sys.exit(0 if all_passed else 1)
|
|
181
|
+
|
|
182
|
+
|
|
183
|
+
if __name__ == "__main__":
|
|
184
|
+
main()
|
|
@@ -0,0 +1,173 @@
|
|
|
1
|
+
#!/usr/bin/env python3
|
|
2
|
+
"""
|
|
3
|
+
Type Coverage Checker - Measures TypeScript/Python type coverage.
|
|
4
|
+
Identifies untyped functions, any usage, and type safety issues.
|
|
5
|
+
"""
|
|
6
|
+
import sys
|
|
7
|
+
import re
|
|
8
|
+
import subprocess
|
|
9
|
+
from pathlib import Path
|
|
10
|
+
|
|
11
|
+
# Fix Windows console encoding for Unicode output
|
|
12
|
+
try:
|
|
13
|
+
sys.stdout.reconfigure(encoding='utf-8', errors='replace')
|
|
14
|
+
sys.stderr.reconfigure(encoding='utf-8', errors='replace')
|
|
15
|
+
except AttributeError:
|
|
16
|
+
pass # Python < 3.7
|
|
17
|
+
|
|
18
|
+
def check_typescript_coverage(project_path: Path) -> dict:
|
|
19
|
+
"""Check TypeScript type coverage."""
|
|
20
|
+
issues = []
|
|
21
|
+
passed = []
|
|
22
|
+
stats = {'any_count': 0, 'untyped_functions': 0, 'total_functions': 0}
|
|
23
|
+
|
|
24
|
+
ts_files = list(project_path.rglob("*.ts")) + list(project_path.rglob("*.tsx"))
|
|
25
|
+
ts_files = [f for f in ts_files if 'node_modules' not in str(f) and '.d.ts' not in str(f)]
|
|
26
|
+
|
|
27
|
+
if not ts_files:
|
|
28
|
+
return {'type': 'typescript', 'files': 0, 'passed': [], 'issues': ["[!] No TypeScript files found"], 'stats': stats}
|
|
29
|
+
|
|
30
|
+
for file_path in ts_files[:30]: # Limit
|
|
31
|
+
try:
|
|
32
|
+
content = file_path.read_text(encoding='utf-8', errors='ignore')
|
|
33
|
+
|
|
34
|
+
# Count 'any' usage
|
|
35
|
+
any_matches = re.findall(r':\s*any\b', content)
|
|
36
|
+
stats['any_count'] += len(any_matches)
|
|
37
|
+
|
|
38
|
+
# Find functions without return types
|
|
39
|
+
# function name(params) { - no return type
|
|
40
|
+
untyped = re.findall(r'function\s+\w+\s*\([^)]*\)\s*{', content)
|
|
41
|
+
# Arrow functions without types: const fn = (x) => or (x) =>
|
|
42
|
+
untyped += re.findall(r'=\s*\([^:)]*\)\s*=>', content)
|
|
43
|
+
stats['untyped_functions'] += len(untyped)
|
|
44
|
+
|
|
45
|
+
# Count typed functions
|
|
46
|
+
typed = re.findall(r'function\s+\w+\s*\([^)]*\)\s*:\s*\w+', content)
|
|
47
|
+
typed += re.findall(r':\s*\([^)]*\)\s*=>\s*\w+', content)
|
|
48
|
+
stats['total_functions'] += len(typed) + len(untyped)
|
|
49
|
+
|
|
50
|
+
except Exception:
|
|
51
|
+
continue
|
|
52
|
+
|
|
53
|
+
# Analyze results
|
|
54
|
+
if stats['any_count'] == 0:
|
|
55
|
+
passed.append("[OK] No 'any' types found")
|
|
56
|
+
elif stats['any_count'] <= 5:
|
|
57
|
+
issues.append(f"[!] {stats['any_count']} 'any' types found (acceptable)")
|
|
58
|
+
else:
|
|
59
|
+
issues.append(f"[X] {stats['any_count']} 'any' types found (too many)")
|
|
60
|
+
|
|
61
|
+
if stats['total_functions'] > 0:
|
|
62
|
+
typed_ratio = (stats['total_functions'] - stats['untyped_functions']) / stats['total_functions'] * 100
|
|
63
|
+
if typed_ratio >= 80:
|
|
64
|
+
passed.append(f"[OK] Type coverage: {typed_ratio:.0f}%")
|
|
65
|
+
elif typed_ratio >= 50:
|
|
66
|
+
issues.append(f"[!] Type coverage: {typed_ratio:.0f}% (improve)")
|
|
67
|
+
else:
|
|
68
|
+
issues.append(f"[X] Type coverage: {typed_ratio:.0f}% (too low)")
|
|
69
|
+
|
|
70
|
+
passed.append(f"[OK] Analyzed {len(ts_files)} TypeScript files")
|
|
71
|
+
|
|
72
|
+
return {'type': 'typescript', 'files': len(ts_files), 'passed': passed, 'issues': issues, 'stats': stats}
|
|
73
|
+
|
|
74
|
+
def check_python_coverage(project_path: Path) -> dict:
|
|
75
|
+
"""Check Python type hints coverage."""
|
|
76
|
+
issues = []
|
|
77
|
+
passed = []
|
|
78
|
+
stats = {'untyped_functions': 0, 'typed_functions': 0, 'any_count': 0}
|
|
79
|
+
|
|
80
|
+
py_files = list(project_path.rglob("*.py"))
|
|
81
|
+
py_files = [f for f in py_files if not any(x in str(f) for x in ['venv', '__pycache__', '.git', 'node_modules'])]
|
|
82
|
+
|
|
83
|
+
if not py_files:
|
|
84
|
+
return {'type': 'python', 'files': 0, 'passed': [], 'issues': ["[!] No Python files found"], 'stats': stats}
|
|
85
|
+
|
|
86
|
+
for file_path in py_files[:30]: # Limit
|
|
87
|
+
try:
|
|
88
|
+
content = file_path.read_text(encoding='utf-8', errors='ignore')
|
|
89
|
+
|
|
90
|
+
# Count Any usage
|
|
91
|
+
any_matches = re.findall(r':\s*Any\b', content)
|
|
92
|
+
stats['any_count'] += len(any_matches)
|
|
93
|
+
|
|
94
|
+
# Find functions with type hints
|
|
95
|
+
typed_funcs = re.findall(r'def\s+\w+\s*\([^)]*:[^)]+\)', content)
|
|
96
|
+
typed_funcs += re.findall(r'def\s+\w+\s*\([^)]*\)\s*->', content)
|
|
97
|
+
stats['typed_functions'] += len(typed_funcs)
|
|
98
|
+
|
|
99
|
+
# Find functions without type hints
|
|
100
|
+
all_funcs = re.findall(r'def\s+\w+\s*\(', content)
|
|
101
|
+
stats['untyped_functions'] += len(all_funcs) - len(typed_funcs)
|
|
102
|
+
|
|
103
|
+
except Exception:
|
|
104
|
+
continue
|
|
105
|
+
|
|
106
|
+
total = stats['typed_functions'] + stats['untyped_functions']
|
|
107
|
+
|
|
108
|
+
if total > 0:
|
|
109
|
+
typed_ratio = stats['typed_functions'] / total * 100
|
|
110
|
+
if typed_ratio >= 70:
|
|
111
|
+
passed.append(f"[OK] Type hints coverage: {typed_ratio:.0f}%")
|
|
112
|
+
elif typed_ratio >= 40:
|
|
113
|
+
issues.append(f"[!] Type hints coverage: {typed_ratio:.0f}%")
|
|
114
|
+
else:
|
|
115
|
+
issues.append(f"[X] Type hints coverage: {typed_ratio:.0f}% (add type hints)")
|
|
116
|
+
|
|
117
|
+
if stats['any_count'] == 0:
|
|
118
|
+
passed.append("[OK] No 'Any' types found")
|
|
119
|
+
elif stats['any_count'] <= 3:
|
|
120
|
+
issues.append(f"[!] {stats['any_count']} 'Any' types found")
|
|
121
|
+
else:
|
|
122
|
+
issues.append(f"[X] {stats['any_count']} 'Any' types found")
|
|
123
|
+
|
|
124
|
+
passed.append(f"[OK] Analyzed {len(py_files)} Python files")
|
|
125
|
+
|
|
126
|
+
return {'type': 'python', 'files': len(py_files), 'passed': passed, 'issues': issues, 'stats': stats}
|
|
127
|
+
|
|
128
|
+
def main():
|
|
129
|
+
target = sys.argv[1] if len(sys.argv) > 1 else "."
|
|
130
|
+
project_path = Path(target)
|
|
131
|
+
|
|
132
|
+
print("\n" + "=" * 60)
|
|
133
|
+
print(" TYPE COVERAGE CHECKER")
|
|
134
|
+
print("=" * 60 + "\n")
|
|
135
|
+
|
|
136
|
+
results = []
|
|
137
|
+
|
|
138
|
+
# Check TypeScript
|
|
139
|
+
ts_result = check_typescript_coverage(project_path)
|
|
140
|
+
if ts_result['files'] > 0:
|
|
141
|
+
results.append(ts_result)
|
|
142
|
+
|
|
143
|
+
# Check Python
|
|
144
|
+
py_result = check_python_coverage(project_path)
|
|
145
|
+
if py_result['files'] > 0:
|
|
146
|
+
results.append(py_result)
|
|
147
|
+
|
|
148
|
+
if not results:
|
|
149
|
+
print("[!] No TypeScript or Python files found.")
|
|
150
|
+
sys.exit(0)
|
|
151
|
+
|
|
152
|
+
# Print results
|
|
153
|
+
critical_issues = 0
|
|
154
|
+
for result in results:
|
|
155
|
+
print(f"\n[{result['type'].upper()}]")
|
|
156
|
+
print("-" * 40)
|
|
157
|
+
for item in result['passed']:
|
|
158
|
+
print(f" {item}")
|
|
159
|
+
for item in result['issues']:
|
|
160
|
+
print(f" {item}")
|
|
161
|
+
if item.startswith("[X]"):
|
|
162
|
+
critical_issues += 1
|
|
163
|
+
|
|
164
|
+
print("\n" + "=" * 60)
|
|
165
|
+
if critical_issues == 0:
|
|
166
|
+
print("[OK] TYPE COVERAGE: ACCEPTABLE")
|
|
167
|
+
sys.exit(0)
|
|
168
|
+
else:
|
|
169
|
+
print(f"[X] TYPE COVERAGE: {critical_issues} critical issues")
|
|
170
|
+
sys.exit(1)
|
|
171
|
+
|
|
172
|
+
if __name__ == "__main__":
|
|
173
|
+
main()
|
|
@@ -0,0 +1,238 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: mcp-atuacao
|
|
3
|
+
description: Single contract for MCP servers that actuate real devices (lights, locks, HVAC, gates). Caller identity, declared scope, read-back verification, type validation, audit log, refusal codes.
|
|
4
|
+
when_to_use: "When building or calling MCP tools that write to real hardware (smart home, Tuya, Zigbee, relays). When the user mentions set_power, physical actuation, smart device control, or when implementing actuation servers beside mcp-builder."
|
|
5
|
+
allowed-tools: Read, Write, Edit, Glob, Grep
|
|
6
|
+
---
|
|
7
|
+
|
|
8
|
+
# MCP Atuação (dispositivos reais)
|
|
9
|
+
|
|
10
|
+
> Um write que não lê de volta é opinião. Relatar sucesso só pelo `ok` do driver é como apagar uma luz que nunca mudou.
|
|
11
|
+
|
|
12
|
+
## Por que existe
|
|
13
|
+
|
|
14
|
+
**DEM-ZEN-DEB-55 (nov/2026):** em teste, sessões acionaram luzes reais sem lease, sem cartão no quadro e sem o dono no loop. O MCP devolveu `ok` em `set_power` quando o valor chegou como string (`"true"` em vez de boolean): o driver aceitou, nada mudou no dispositivo, o agente reportou sucesso. Conhecimento `agent_generated` com confidence 0,6 justificou o write.
|
|
15
|
+
|
|
16
|
+
**Caso motivador (Tuya):** brilho confundido com datapoint de countdown (dp 26). O write parecia correto no schema; o estado físico era outro. Só read-back expõe isso.
|
|
17
|
+
|
|
18
|
+
Esta skill é o contrato único para servidores MCP de atuação. Para transporte e desenho genérico de tools, use `mcp-builder`; para **efeito no mundo físico**, tudo abaixo é obrigatório.
|
|
19
|
+
|
|
20
|
+
---
|
|
21
|
+
|
|
22
|
+
## 1. Identidade do caller (todo write)
|
|
23
|
+
|
|
24
|
+
Cada chamada de escrita deve receber e persistir identidade resolvida:
|
|
25
|
+
|
|
26
|
+
| Campo | Obrigatório | Uso |
|
|
27
|
+
| --- | --- | --- |
|
|
28
|
+
| `caller_agent` | sim | agente ou papel ZenKit |
|
|
29
|
+
| `caller_session` | sim | id de sessão |
|
|
30
|
+
| `caller_client` | sim | `session_client_id` / ref do runtime |
|
|
31
|
+
|
|
32
|
+
Se o transporte não permitir inferir os três, a tool **recusa** com `NO_CALLER_IDENTITY`. Não executar write anônimo em dispositivo real.
|
|
33
|
+
|
|
34
|
+
---
|
|
35
|
+
|
|
36
|
+
## 2. Escopo declarado (por chamada)
|
|
37
|
+
|
|
38
|
+
Além dos parâmetros do dispositivo, o input do write inclui:
|
|
39
|
+
|
|
40
|
+
| Campo | Descrição |
|
|
41
|
+
| --- | --- |
|
|
42
|
+
| `device_id` | id estável no backend |
|
|
43
|
+
| `room` | cômodo ou zona humana |
|
|
44
|
+
| `intended_state` | o que o humano pediu, em texto curto |
|
|
45
|
+
|
|
46
|
+
Ausência de escopo explícito → `SCOPE_NOT_DECLARED`.
|
|
47
|
+
|
|
48
|
+
O agente no ZenKit também declara o mesmo escopo no lease e no cartão do quadro antes do write (ver ZENKIT §10.2.2).
|
|
49
|
+
|
|
50
|
+
---
|
|
51
|
+
|
|
52
|
+
## 3. Resposta padrão do write (sempre com read-back)
|
|
53
|
+
|
|
54
|
+
O retorno do write **nunca** é só `ok`. Fluxo obrigatório:
|
|
55
|
+
|
|
56
|
+
1. Validar tipos e faixa (ver §4).
|
|
57
|
+
2. Enviar comando ao dispositivo.
|
|
58
|
+
3. **Ler de volta** o estado relevante (poll ou get_status).
|
|
59
|
+
4. Comparar com o pedido.
|
|
60
|
+
|
|
61
|
+
```json
|
|
62
|
+
{
|
|
63
|
+
"requested": { "power": true, "brightness": 80 },
|
|
64
|
+
"actual": { "power": true, "brightness": 80 },
|
|
65
|
+
"verified": true
|
|
66
|
+
}
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
| Campo | Significado |
|
|
70
|
+
| --- | --- |
|
|
71
|
+
| `requested` | valor normalizado que o servidor tentou aplicar |
|
|
72
|
+
| `actual` | valor lido do dispositivo após o write |
|
|
73
|
+
| `verified` | `true` só se `actual` equivale ao `requested` dentro da tolerância documentada |
|
|
74
|
+
|
|
75
|
+
Se `verified` é `false` → código `READBACK_MISMATCH` (pode incluir HTTP/MCP error junto). O agente **não** pode reportar sucesso ao humano.
|
|
76
|
+
|
|
77
|
+
Conhecimento da memória compartilhada com confidence < 0,8 ou `agent_generated` sem confirmação humana → `LOW_CONFIDENCE_SOURCE` (recusa antes do write).
|
|
78
|
+
|
|
79
|
+
---
|
|
80
|
+
|
|
81
|
+
## 4. Validação de tipos
|
|
82
|
+
|
|
83
|
+
| Regra | Exemplo |
|
|
84
|
+
| --- | --- |
|
|
85
|
+
| Boolean estrito | Rejeitar `"true"`, `"1"`, `1` onde o schema pede `boolean` |
|
|
86
|
+
| Numérico em faixa | Brilho 0–100; rejeitar 101 ou string numérica se o driver for permissivo |
|
|
87
|
+
| Enum / dp conhecido | Mapear datapoint para semântica (não tratar dp de countdown como brilho) |
|
|
88
|
+
|
|
89
|
+
Falha de validação → erro antes de tocar o hardware (não confundir com `READBACK_MISMATCH`).
|
|
90
|
+
|
|
91
|
+
---
|
|
92
|
+
|
|
93
|
+
## 5. Audit log (campos mínimos)
|
|
94
|
+
|
|
95
|
+
Cada write gera uma linha estruturada (arquivo, DB ou observability):
|
|
96
|
+
|
|
97
|
+
| Campo | Tipo |
|
|
98
|
+
| --- | --- |
|
|
99
|
+
| `ts` | ISO 8601 |
|
|
100
|
+
| `caller` | objeto `{ agent, session, client }` |
|
|
101
|
+
| `device` | id |
|
|
102
|
+
| `room` | string |
|
|
103
|
+
| `requested` | objeto |
|
|
104
|
+
| `actual` | objeto |
|
|
105
|
+
| `verified` | boolean |
|
|
106
|
+
| `latency_ms` | número |
|
|
107
|
+
| `ip` | origem da conexão MCP, se remoto |
|
|
108
|
+
|
|
109
|
+
Sem PII extra no log. IP só para auditoria de atuação remota.
|
|
110
|
+
|
|
111
|
+
---
|
|
112
|
+
|
|
113
|
+
## 6. Códigos de recusa
|
|
114
|
+
|
|
115
|
+
| Código | Quando |
|
|
116
|
+
| --- | --- |
|
|
117
|
+
| `NO_CALLER_IDENTITY` | Caller incompleto ou não autenticável |
|
|
118
|
+
| `SCOPE_NOT_DECLARED` | Falta `room` / `intended_state` / `device_id` |
|
|
119
|
+
| `READBACK_MISMATCH` | Write executou mas `actual` ≠ `requested` |
|
|
120
|
+
| `LOW_CONFIDENCE_SOURCE` | Fonte de decisão abaixo do limiar ou só agent_generated sem humano |
|
|
121
|
+
|
|
122
|
+
---
|
|
123
|
+
|
|
124
|
+
## 7. Checklist (servidor + agente)
|
|
125
|
+
|
|
126
|
+
**Servidor MCP**
|
|
127
|
+
|
|
128
|
+
- [ ] Write exige `caller_*` + escopo declarado
|
|
129
|
+
- [ ] Boolean e ranges validados antes do driver
|
|
130
|
+
- [ ] Read-back após todo write que altera estado
|
|
131
|
+
- [ ] Retorno `{ requested, actual, verified }`
|
|
132
|
+
- [ ] Audit log com os campos §5
|
|
133
|
+
- [ ] Recusas usam códigos §6
|
|
134
|
+
|
|
135
|
+
**Agente consumidor**
|
|
136
|
+
|
|
137
|
+
- [ ] Lease + cartão no quadro para o dispositivo/cômodo
|
|
138
|
+
- [ ] Não confiar em `ok` isolado do vendor
|
|
139
|
+
- [ ] Reportar ao humano só com `verified: true` e `actual` citado
|
|
140
|
+
- [ ] Não atuar com confidence < 0,8 sem confirmação
|
|
141
|
+
- [ ] Fork de atuação física (ZENKIT §10.2): dono no loop
|
|
142
|
+
|
|
143
|
+
---
|
|
144
|
+
|
|
145
|
+
## 8. Exemplo: tool `set_power` com read-back
|
|
146
|
+
|
|
147
|
+
### TypeScript (esboço)
|
|
148
|
+
|
|
149
|
+
```typescript
|
|
150
|
+
type ActuationResult = {
|
|
151
|
+
requested: { power: boolean };
|
|
152
|
+
actual: { power: boolean };
|
|
153
|
+
verified: boolean;
|
|
154
|
+
};
|
|
155
|
+
|
|
156
|
+
function parsePower(value: unknown): boolean {
|
|
157
|
+
if (typeof value === "boolean") return value;
|
|
158
|
+
throw new Error("TYPE_INVALID: power must be boolean");
|
|
159
|
+
}
|
|
160
|
+
|
|
161
|
+
export async function setPower(input: {
|
|
162
|
+
device_id: string;
|
|
163
|
+
room: string;
|
|
164
|
+
intended_state: string;
|
|
165
|
+
power: unknown;
|
|
166
|
+
caller_agent: string;
|
|
167
|
+
caller_session: string;
|
|
168
|
+
caller_client: string;
|
|
169
|
+
}): Promise<ActuationResult> {
|
|
170
|
+
if (!input.caller_agent || !input.caller_session || !input.caller_client) {
|
|
171
|
+
throw Object.assign(new Error("NO_CALLER_IDENTITY"), { code: "NO_CALLER_IDENTITY" });
|
|
172
|
+
}
|
|
173
|
+
if (!input.room?.trim() || !input.intended_state?.trim()) {
|
|
174
|
+
throw Object.assign(new Error("SCOPE_NOT_DECLARED"), { code: "SCOPE_NOT_DECLARED" });
|
|
175
|
+
}
|
|
176
|
+
const power = parsePower(input.power);
|
|
177
|
+
const requested = { power };
|
|
178
|
+
await deviceDriver.setPower(input.device_id, power);
|
|
179
|
+
const raw = await deviceDriver.getPower(input.device_id);
|
|
180
|
+
const actual = { power: parsePower(raw) };
|
|
181
|
+
const verified = actual.power === requested.power;
|
|
182
|
+
auditLog({ /* ts, caller, device, room, requested, actual, verified, latency_ms, ip */ });
|
|
183
|
+
if (!verified) {
|
|
184
|
+
throw Object.assign(new Error("READBACK_MISMATCH"), { code: "READBACK_MISMATCH", requested, actual });
|
|
185
|
+
}
|
|
186
|
+
return { requested, actual, verified };
|
|
187
|
+
}
|
|
188
|
+
```
|
|
189
|
+
|
|
190
|
+
### Python (esboço)
|
|
191
|
+
|
|
192
|
+
```python
|
|
193
|
+
from dataclasses import dataclass
|
|
194
|
+
from typing import Any
|
|
195
|
+
|
|
196
|
+
@dataclass
|
|
197
|
+
class ActuationResult:
|
|
198
|
+
requested: dict[str, Any]
|
|
199
|
+
actual: dict[str, Any]
|
|
200
|
+
verified: bool
|
|
201
|
+
|
|
202
|
+
def parse_power(value: Any) -> bool:
|
|
203
|
+
if isinstance(value, bool):
|
|
204
|
+
return value
|
|
205
|
+
raise ValueError("TYPE_INVALID: power must be boolean")
|
|
206
|
+
|
|
207
|
+
def set_power(
|
|
208
|
+
*,
|
|
209
|
+
device_id: str,
|
|
210
|
+
room: str,
|
|
211
|
+
intended_state: str,
|
|
212
|
+
power: Any,
|
|
213
|
+
caller_agent: str,
|
|
214
|
+
caller_session: str,
|
|
215
|
+
caller_client: str,
|
|
216
|
+
) -> ActuationResult:
|
|
217
|
+
if not all([caller_agent, caller_session, caller_client]):
|
|
218
|
+
raise RuntimeError("NO_CALLER_IDENTITY")
|
|
219
|
+
if not room.strip() or not intended_state.strip():
|
|
220
|
+
raise RuntimeError("SCOPE_NOT_DECLARED")
|
|
221
|
+
requested_power = parse_power(power)
|
|
222
|
+
requested = {"power": requested_power}
|
|
223
|
+
driver.set_power(device_id, requested_power)
|
|
224
|
+
actual = {"power": parse_power(driver.get_power(device_id))}
|
|
225
|
+
verified = actual == requested
|
|
226
|
+
audit_log(...) # ts, caller, device, room, requested, actual, verified, latency_ms, ip
|
|
227
|
+
if not verified:
|
|
228
|
+
raise RuntimeError("READBACK_MISMATCH")
|
|
229
|
+
return ActuationResult(requested=requested, actual=actual, verified=verified)
|
|
230
|
+
```
|
|
231
|
+
|
|
232
|
+
---
|
|
233
|
+
|
|
234
|
+
## 9. Integração
|
|
235
|
+
|
|
236
|
+
- **Agente:** `backend-specialist` + esta skill ao implementar ou revisar MCP de casa/dispositivos.
|
|
237
|
+
- **Bundle:** `agent-building` (junto de `mcp-builder`).
|
|
238
|
+
- **Roteamento:** `intelligent-routing` (intenção de atuação física / smart home).
|