Skip to content

feat(m7.2): TypeScript capabilities — schema, classification, linter - #28

Merged
shamspias merged 1 commit into
mainfrom
build/m7.2-ts-capabilities
Jul 5, 2026
Merged

feat(m7.2): TypeScript capabilities — schema, classification, linter#28
shamspias merged 1 commit into
mainfrom
build/m7.2-ts-capabilities

Conversation

@shamspias

Copy link
Copy Markdown
Owner
  • capability(name, config, handler) → BoundCapability {spec, handler, returnsRaw}; access is classified from the name unless config.reads/destructive overrides it. An optional Args type parameter types the handler's arguments for the caller.
  • Schema authoring, TS-appropriately: types are erased at runtime, so instead of reflecting them the package offers params({order_id:'integer', reason:'string?', tags:'string[]'}) — a tiny JSON Schema builder (? = optional, [] = array) with ZERO dependencies — and Zod v4 users just pass z.toJSONSchema(schema), so no converter and no hard zod dep are needed.
  • classify/classifyWith mirror the exact Python/Go verb sets (read/write/ destructive), ambiguous ⇒ write (§2.4), and throw a hinted error if a capability is marked both reads and destructive.
  • lint/lintCapability + LintReport with the same four language-neutral violation codes (opaque_name, missing_description, too_many_params, raw_response), MAX_PARAMS=7, MIN_DESCRIPTION_CHARS=10, and the same opaque-name rule (clean snake_case with at least one 4+ char token). Both conformance linter shapes (linter_rejects_raw_capability / linter_accepts_clean_capability) are reproduced as unit tests.

Verified: make js-check green — format, typecheck, 35 tests (classification across all verb classes + ambiguous default + overrides; linter pass/fail shapes and each code; capability construction, handler context/args, params builder incl. arrays, optionals, and hinted errors on unknown types).

- capability(name, config, handler) → BoundCapability {spec, handler, returnsRaw};
  access is classified from the name unless config.reads/destructive overrides it.
  An optional Args type parameter types the handler's arguments for the caller.
- Schema authoring, TS-appropriately: types are erased at runtime, so instead of
  reflecting them the package offers params({order_id:'integer', reason:'string?',
  tags:'string[]'}) — a tiny JSON Schema builder (? = optional, [] = array) with
  ZERO dependencies — and Zod v4 users just pass z.toJSONSchema(schema), so no
  converter and no hard zod dep are needed.
- classify/classifyWith mirror the exact Python/Go verb sets (read/write/
  destructive), ambiguous ⇒ write (§2.4), and throw a hinted error if a capability
  is marked both reads and destructive.
- lint/lintCapability + LintReport with the same four language-neutral violation
  codes (opaque_name, missing_description, too_many_params, raw_response),
  MAX_PARAMS=7, MIN_DESCRIPTION_CHARS=10, and the same opaque-name rule (clean
  snake_case with at least one 4+ char token). Both conformance linter shapes
  (linter_rejects_raw_capability / linter_accepts_clean_capability) are reproduced
  as unit tests.

Verified: make js-check green — format, typecheck, 35 tests (classification across
all verb classes + ambiguous default + overrides; linter pass/fail shapes and each
code; capability construction, handler context/args, params builder incl. arrays,
optionals, and hinted errors on unknown types).
@shamspias
shamspias merged commit c5d544c into main Jul 5, 2026
3 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant