DD-338 Phase E.ts — stallari-mcp-helpers (TS) v0.1.0 initial release #1

Merged

piersdd merged 1 commit from feat/dd-338-e-ts-mcp-helpers-v0.1.0 into main

2026-05-24 00:27:14 +00:00

piersdd commented

2026-05-24 00:26:33 +00:00

(Migrated from github.com)

Summary

First-cut public API for the TypeScript sister of stallari-mcp-helpers (Python v0.1.1) — canonical _meta audit envelope builder for Stallari-conformant MCP servers. Spec: 2026-05-24-dd-338-e-ts-mcp-helpers-package.

src/meta.ts lifted from byte-identical cloudflare-blade-mcp reference (sha256 d56cb4a0a0e6ea7472eb7a0455d6858e49fa72d0c9ec88fe7b478a3a6120772b; verified identical with vultr-blade-mcp at lift time).
Wire-shape canonicalisation — redactions and next_cursor promoted from optional / omit-when-empty to REQUIRED / always-present (defaulting to [] and null). error_notes stays optional / omit-when-empty per Convention #22. Key emission order locked at matched_total, returned, filtered_by, latency_ms, redactions, next_cursor, [error_notes] for cross-language byte parity with the Python canonical.
22 tests covering all enumerated cases in the spec (tests/meta.test.ts), 100% line + branch coverage on both src/meta.ts and src/index.ts. Smoke test (tests/smoke.test.ts) untouched as the permanent import-smoke guard.
CHANGELOG.md [0.1.0] Added section extended with the exact public-API surface shipped.
No modifications outside the 4 spec-scoped files (src/meta.ts, src/index.ts, tests/meta.test.ts, CHANGELOG.md).

Public API

export interface MetaEnvelope {
  matched_total: number;
  returned: number;
  filtered_by: string[];
  latency_ms: number;
  redactions: string[];           // REQUIRED — always present
  next_cursor: string | null;     // REQUIRED — always present (literal null OK)
  error_notes?: string[];         // OPTIONAL — omit-when-empty
}

export function formatMetaLine(meta: MetaEnvelope): string;
export function appendMeta(payload: string, metaLine: string): string;

Verification (within worktree)

Gate	Result
`npm test`	23 passed (22 meta + 1 smoke)
`npm run test:coverage`	100% line + branch on `src/meta.ts` + `src/index.ts`
`npm run typecheck`	clean (strict + `noUncheckedIndexedAccess` + `noImplicitOverride` + `noFallthroughCasesInSwitch` + `noUnusedLocals` + `noUnusedParameters`)
`npm run build`	emits `dist/{meta,index}.{js,d.ts,d.ts.map,js.map}` (8 artefacts)

Test plan

CI green on this PR (lint + test on Node 20 / 22 matrix)
Merge to main
Architect runs npm publish --access public from CLI to establish the package on npm (first publish; subsequent versions via Trusted Publishing OIDC)
Tag v0.1.0 after first publish so v0.1.1+ flow through tag-triggered CI publish
Spec B dispatches to flip cloudflare-blade-mcp + vultr-blade-mcp to consume the published package

🤖 Generated with Claude Code

## Summary First-cut public API for the TypeScript sister of `stallari-mcp-helpers` (Python v0.1.1) — canonical `_meta` audit envelope builder for Stallari-conformant MCP servers. Spec: [2026-05-24-dd-338-e-ts-mcp-helpers-package](../../../../master-ai/atlas/utilities/agent-harness/specs/2026-05-24-dd-338-e-ts-mcp-helpers-package.md). - **`src/meta.ts`** lifted from byte-identical `cloudflare-blade-mcp` reference (sha256 `d56cb4a0a0e6ea7472eb7a0455d6858e49fa72d0c9ec88fe7b478a3a6120772b`; verified identical with `vultr-blade-mcp` at lift time). - **Wire-shape canonicalisation** — `redactions` and `next_cursor` promoted from optional / omit-when-empty to REQUIRED / always-present (defaulting to `[]` and `null`). `error_notes` stays optional / omit-when-empty per Convention #22. Key emission order locked at `matched_total, returned, filtered_by, latency_ms, redactions, next_cursor, [error_notes]` for cross-language byte parity with the Python canonical. - **22 tests** covering all enumerated cases in the spec (`tests/meta.test.ts`), 100% line + branch coverage on both `src/meta.ts` and `src/index.ts`. Smoke test (`tests/smoke.test.ts`) untouched as the permanent import-smoke guard. - **CHANGELOG.md** `[0.1.0]` Added section extended with the exact public-API surface shipped. - **No modifications** outside the 4 spec-scoped files (`src/meta.ts`, `src/index.ts`, `tests/meta.test.ts`, `CHANGELOG.md`). ## Public API ```typescript export interface MetaEnvelope { matched_total: number; returned: number; filtered_by: string[]; latency_ms: number; redactions: string[]; // REQUIRED — always present next_cursor: string | null; // REQUIRED — always present (literal null OK) error_notes?: string[]; // OPTIONAL — omit-when-empty } export function formatMetaLine(meta: MetaEnvelope): string; export function appendMeta(payload: string, metaLine: string): string; ``` ## Verification (within worktree) | Gate | Result | |---|---| | `npm test` | 23 passed (22 meta + 1 smoke) | | `npm run test:coverage` | 100% line + branch on `src/meta.ts` + `src/index.ts` | | `npm run typecheck` | clean (strict + `noUncheckedIndexedAccess` + `noImplicitOverride` + `noFallthroughCasesInSwitch` + `noUnusedLocals` + `noUnusedParameters`) | | `npm run build` | emits `dist/{meta,index}.{js,d.ts,d.ts.map,js.map}` (8 artefacts) | ## Test plan - [ ] CI green on this PR (lint + test on Node 20 / 22 matrix) - [ ] Merge to `main` - [ ] Architect runs `npm publish --access public` from CLI to establish the package on npm (first publish; subsequent versions via Trusted Publishing OIDC) - [ ] Tag `v0.1.0` after first publish so v0.1.1+ flow through tag-triggered CI publish - [ ] Spec B dispatches to flip `cloudflare-blade-mcp` + `vultr-blade-mcp` to consume the published package 🤖 Generated with [Claude Code](https://claude.com/claude-code)