@trainheroic-unofficial/core 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Alan Cohen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,59 @@
+# @trainheroic-unofficial/core
+
+The shared MCP tool layer for TrainHeroic. Each tool is defined once here and reused by both
+servers: the local stdio server (`@trainheroic-unofficial/coach-mcp`) and the hosted
+Cloudflare worker (`@trainheroic-unofficial/cloudflare`). Keeping the tools here is what
+makes the two transports behave identically.
+
+Part of the [trainheroic-unofficial](../../README.md) workspace.
+
+## How a server uses it
+
+A server builds a `ToolContext` (an authenticated `TrainHeroicClient` plus something that
+implements the `ExerciseIndex` interface) and calls the `registerXxxTools(server, ctx)`
+functions:
+
+```ts
+import {
+  registerReadTools,
+  registerRawTools,
+  registerExerciseTools,
+  registerWorkoutTools,
+  registerMessagingTools,
+  type ToolContext,
+} from "@trainheroic-unofficial/core";
+
+const ctx: ToolContext = { client, index };
+registerReadTools(server, ctx);
+registerExerciseTools(server, ctx);
+// ...and the rest
+```
+
+Because the context depends on the `ExerciseIndex` interface rather than a concrete store,
+the same tools run against the local in-memory library and the hosted D1 mirror without
+change.
+
+## What the tools cover
+
+The tools group into coach reads (profile, athletes, teams, programs, notifications,
+analytics), exercise library operations (resolve, search, get, sync, create, forget,
+stats), the workout lifecycle (build a draft, read it back, publish, remove), messaging
+(list, read, draft, send, delete), and a `th_request` escape hatch for any endpoint the
+dedicated tools do not cover.
+
+Tools return their result in-band. A failure comes back as an error result the model can
+read and correct, not a thrown exception. Reads are marked read-only. Athlete-facing or
+destructive actions (publish, remove, send, delete, and non-GET `th_request`) pass through a
+confirmation gate before they run.
+
+The D1-backed warehouse sync tools are not here; they live in the `cloudflare` package
+because they depend on its storage.
+
+## Develop
+
+```bash
+pnpm build       # tsdown
+pnpm typecheck
+pnpm test
+pnpm exec vitest run test/confirm.test.ts   # one file
+```

package/dist/index.d.mts

@@ -0,0 +1,90 @@
+import { ExerciseIndex, RequestOptions, TrainHeroicClient } from "@trainheroic-unofficial/js";
+import { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+
+//#region src/context.d.ts
+/** A tool argument that accepts a numeric id as a number or a string of digits. */
+declare const idParam: import("zod").ZodUnion<readonly [import("zod").ZodNumber, import("zod").ZodString]>;
+declare function toId(value: string | number): number;
+declare const READ: {
+  readonly readOnlyHint: true;
+  readonly openWorldHint: true;
+};
+declare const SYNC: {
+  readonly readOnlyHint: false;
+  readonly idempotentHint: true;
+  readonly destructiveHint: false;
+  readonly openWorldHint: true;
+};
+declare const DESTRUCTIVE: {
+  readonly readOnlyHint: false;
+  readonly destructiveHint: true;
+  readonly openWorldHint: true;
+};
+/** Everything a tool handler needs: the authenticated client and the exercise index. */
+type ToolContext = {
+  client: TrainHeroicClient;
+  index: ExerciseIndex;
+};
+/** Run a tool body, converting thrown errors into an in-band tool error. */
+declare function attempt(fn: () => Promise<CallToolResult>): Promise<CallToolResult>;
+/** Conservative per-result character cap, below the smallest host cap. */
+declare const DEFAULT_RESULT_BUDGET = 60000;
+/** Active budget. Overridable via TH_MCP_RESULT_BUDGET on Node; the default on workerd. */
+declare function resultBudget(): number;
+/**
+ * Serialize `data` as JSON within `budget` characters. Small results are pretty-printed.
+ * Oversized results degrade in order: trim a top-level array (wrapping it as
+ * `{ items, __truncated }`), then a top-level object's largest array property (annotated
+ * with `__truncated`), then a last-resort hard character cap. Pure and side-effect free.
+ */
+declare function boundedSerialize(data: unknown, budget: number, hint?: string): string;
+/** Per-tool guidance threaded into the truncation marker when a result is too large. */
+type BudgetHint = {
+  hint?: string | undefined;
+};
+/** A successful tool result carrying JSON (or text) for the model, size-bounded. */
+declare function jsonResult(data: unknown, opts?: BudgetHint): CallToolResult;
+/** A tool-level error: returned in-band (isError) so the model can self-correct. */
+declare function errorResult(message: string): CallToolResult;
+/** Issue a TrainHeroic request and format the outcome as a tool result. */
+declare function apiCall(ctx: ToolContext, method: string, path: string, options?: RequestOptions, hint?: string): Promise<CallToolResult>;
+//#endregion
+//#region src/confirm.d.ts
+declare const NOT_CONFIRMED = "Not confirmed. Re-run with confirm:true, or connect a client that supports MCP elicitation.";
+/**
+ * Confirm a destructive/athlete-facing action. Prefers MCP elicitation (an
+ * in-the-moment user prompt); falls back to an explicit confirm:true argument when
+ * the client does not support elicitation. Never proceeds without one of the two.
+ */
+declare function confirmGate(server: McpServer, requestId: string | number | undefined, message: string, confirmArg: boolean | undefined): Promise<boolean>;
+//#endregion
+//#region src/tools/reads.d.ts
+/** Read-only coach/athlete queries. Exercise lookups live in the exercise store tools. */
+declare function registerReadTools(server: McpServer, ctx: ToolContext): void;
+//#endregion
+//#region src/tools/raw.d.ts
+/**
+ * Escape hatch covering every endpoint without a dedicated tool (e.g. the analytics
+ * POSTs). GET is ungated; mutating methods go through the same confirmation gate as
+ * the dedicated destructive tools so this cannot be used to bypass it.
+ */
+declare function registerRawTools(server: McpServer, ctx: ToolContext): void;
+//#endregion
+//#region src/tools/exercises.d.ts
+/**
+ * Exercise library tools over the ExerciseIndex — a D1 mirror on the hosted server, an
+ * on-disk/in-memory cache locally. The descriptions stay at the interface level so they
+ * read correctly on both backends.
+ */
+declare function registerExerciseTools(server: McpServer, ctx: ToolContext): void;
+//#endregion
+//#region src/tools/workout.d.ts
+/** Workout building, read-back, publishing, and removal. */
+declare function registerWorkoutTools(server: McpServer, ctx: ToolContext): void;
+//#endregion
+//#region src/tools/messaging.d.ts
+/** Live messaging: list/read conversations, draft a message, and the gated send/delete. */
+declare function registerMessagingTools(server: McpServer, ctx: ToolContext): void;
+//#endregion
+export { BudgetHint, DEFAULT_RESULT_BUDGET, DESTRUCTIVE, NOT_CONFIRMED, READ, SYNC, ToolContext, apiCall, attempt, boundedSerialize, confirmGate, errorResult, idParam, jsonResult, registerExerciseTools, registerMessagingTools, registerRawTools, registerReadTools, registerWorkoutTools, resultBudget, toId };

package/dist/index.mjs

@@ -0,0 +1,584 @@
+import { blockSpecSchema, commentDraftSchema, exerciseCreateSchema, idArgSchema, parseWorkoutDate } from "@trainheroic-unofficial/dto";
+import { z } from "zod";
+import { buildCommentPayload, buildSession, collectAdvisories, deleteComment, fetchStreams, publishSession, readLive, readSession, removeSession, sendComment } from "@trainheroic-unofficial/js";
+//#region src/context.ts
+/** A tool argument that accepts a numeric id as a number or a string of digits. */
+const idParam = idArgSchema;
+function toId(value) {
+	return typeof value === "number" ? value : Number(value);
+}
+const READ = {
+	readOnlyHint: true,
+	openWorldHint: true
+};
+const SYNC = {
+	readOnlyHint: false,
+	idempotentHint: true,
+	destructiveHint: false,
+	openWorldHint: true
+};
+const DESTRUCTIVE = {
+	readOnlyHint: false,
+	destructiveHint: true,
+	openWorldHint: true
+};
+/** Run a tool body, converting thrown errors into an in-band tool error. */
+async function attempt(fn) {
+	try {
+		return await fn();
+	} catch (err) {
+		return errorResult(err instanceof Error ? err.message : String(err));
+	}
+}
+/** Conservative per-result character cap, below the smallest host cap. */
+const DEFAULT_RESULT_BUDGET = 6e4;
+/** Reserve for the `__truncated` marker so wrapping cannot push back over budget. */
+const MARKER_RESERVE = 300;
+const DEFAULT_ARRAY_HINT = "Result was truncated to fit the size budget. Narrow it with a filter/search argument or paginate to see the rest.";
+const DEFAULT_OBJECT_HINT = "Result was truncated to fit the size budget. Request a more specific id or sub-resource.";
+/** Active budget. Overridable via TH_MCP_RESULT_BUDGET on Node; the default on workerd. */
+function resultBudget() {
+	const raw = (globalThis.process?.env)?.TH_MCP_RESULT_BUDGET;
+	const n = raw ? Number(raw) : NaN;
+	return Number.isFinite(n) && n > 0 ? n : DEFAULT_RESULT_BUDGET;
+}
+function isPlainObject(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/** Largest count k such that the JSON of the first k pre-serialized pieces fits. O(n). */
+function largestPrefixCount(pieces, charBudget) {
+	let used = 2;
+	let k = 0;
+	for (const piece of pieces) {
+		const add = piece.length + (k > 0 ? 1 : 0);
+		if (used + add > charBudget) break;
+		used += add;
+		k += 1;
+	}
+	return k;
+}
+/** Last resort: cap a string at the budget and label it as truncated, non-JSON output. */
+function hardCap(text, budget, hint) {
+	if (text.length <= budget) return text;
+	const note = `\n\n[TRUNCATED: output exceeded ${budget} chars and is NOT valid JSON. ${hint ?? "Narrow the query (filter, paginate, or fetch a specific id)."}]`;
+	const keep = Math.max(0, budget - note.length);
+	return text.slice(0, keep) + note;
+}
+function largestArrayValuedKey(obj) {
+	let best = null;
+	let bestLen = -1;
+	for (const [key, value] of Object.entries(obj)) {
+		if (!Array.isArray(value)) continue;
+		const len = (JSON.stringify(value) ?? "[]").length;
+		if (len > bestLen) {
+			best = key;
+			bestLen = len;
+		}
+	}
+	return best;
+}
+/**
+* Serialize `data` as JSON within `budget` characters. Small results are pretty-printed.
+* Oversized results degrade in order: trim a top-level array (wrapping it as
+* `{ items, __truncated }`), then a top-level object's largest array property (annotated
+* with `__truncated`), then a last-resort hard character cap. Pure and side-effect free.
+*/
+function boundedSerialize(data, budget, hint) {
+	if (typeof data === "string") return hardCap(data, budget, hint);
+	const compact = JSON.stringify(data) ?? "null";
+	if (compact.length <= budget) {
+		const pretty = JSON.stringify(data, null, 2) ?? "null";
+		return pretty.length <= budget ? pretty : compact;
+	}
+	if (Array.isArray(data)) {
+		const k = largestPrefixCount(data.map((el) => JSON.stringify(el) ?? "null"), budget - MARKER_RESERVE);
+		const wrapped = {
+			items: data.slice(0, k),
+			__truncated: {
+				returned: k,
+				total: data.length,
+				omitted: data.length - k,
+				hint: hint ?? DEFAULT_ARRAY_HINT
+			}
+		};
+		const out = JSON.stringify(wrapped);
+		if (out.length <= budget) return out;
+	} else if (isPlainObject(data)) {
+		const key = largestArrayValuedKey(data);
+		if (key !== null) {
+			const arr = data[key];
+			const pieces = arr.map((el) => JSON.stringify(el) ?? "null");
+			const restLen = (JSON.stringify({
+				...data,
+				[key]: []
+			}) ?? "{}").length;
+			const k = largestPrefixCount(pieces, Math.max(0, budget - MARKER_RESERVE - restLen));
+			const clone = {
+				...data,
+				[key]: arr.slice(0, k),
+				__truncated: {
+					field: key,
+					returned: k,
+					total: arr.length,
+					omitted: arr.length - k,
+					hint: hint ?? DEFAULT_OBJECT_HINT
+				}
+			};
+			const out = JSON.stringify(clone);
+			if (out.length <= budget) return out;
+		}
+	}
+	return hardCap(compact, budget, hint);
+}
+/** A successful tool result carrying JSON (or text) for the model, size-bounded. */
+function jsonResult(data, opts) {
+	return { content: [{
+		type: "text",
+		text: boundedSerialize(data, resultBudget(), opts?.hint)
+	}] };
+}
+/** A tool-level error: returned in-band (isError) so the model can self-correct. */
+function errorResult(message) {
+	return {
+		isError: true,
+		content: [{
+			type: "text",
+			text: message
+		}]
+	};
+}
+/** Issue a TrainHeroic request and format the outcome as a tool result. */
+async function apiCall(ctx, method, path, options, hint) {
+	return attempt(async () => {
+		const res = await ctx.client.request(method, path, options);
+		if (!res.ok) {
+			const detail = hardCap(typeof res.data === "string" ? res.data : JSON.stringify(res.data) ?? "", resultBudget());
+			return errorResult(`TrainHeroic API error (HTTP ${res.status}): ${detail}`);
+		}
+		return jsonResult(res.data, { hint });
+	});
+}
+//#endregion
+//#region src/confirm.ts
+const NOT_CONFIRMED = "Not confirmed. Re-run with confirm:true, or connect a client that supports MCP elicitation.";
+/**
+* Confirm a destructive/athlete-facing action. Prefers MCP elicitation (an
+* in-the-moment user prompt); falls back to an explicit confirm:true argument when
+* the client does not support elicitation. Never proceeds without one of the two.
+*/
+async function confirmGate(server, requestId, message, confirmArg) {
+	if (confirmArg === true) return true;
+	try {
+		const result = await server.server.elicitInput({
+			message,
+			requestedSchema: {
+				type: "object",
+				properties: { confirm: {
+					type: "boolean",
+					title: "Confirm",
+					description: message
+				} },
+				required: ["confirm"]
+			}
+		}, requestId === void 0 ? void 0 : { relatedRequestId: requestId });
+		return result.action === "accept" && result.content?.confirm === true;
+	} catch (err) {
+		console.warn("MCP elicitation unavailable; treating as not confirmed", err);
+		return false;
+	}
+}
+//#endregion
+//#region src/tools/reads.ts
+function enc(value) {
+	return encodeURIComponent(String(value));
+}
+/** No-argument GET endpoints, registered from a table to keep the wiring compact. */
+const SIMPLE_GETS = [
+	{
+		name: "whoami",
+		title: "Who am I",
+		description: "The authenticated TrainHeroic coach profile (id, org_id, name, roles, trial days).",
+		path: "/user/simple"
+	},
+	{
+		name: "head_coach",
+		title: "Head coach / org",
+		description: "Org, license, and trial status for the head coach account.",
+		path: "/v5/headCoach"
+	},
+	{
+		name: "list_programs",
+		title: "List programs",
+		description: "Coach programs (standalone). Team group-programs come from list_teams.",
+		path: "/1.0/coach/programs"
+	},
+	{
+		name: "notifications",
+		title: "Notification counts",
+		description: "Unread counts including countMessagingNotViewed (cheap 'anything new?' poll).",
+		path: "/v5/notifications/counts"
+	},
+	{
+		name: "analytics_categories",
+		title: "Analytics categories",
+		description: "Lists available analytics types. Pull the data via th_request POST /v5/analytics/*.",
+		path: "/v5/analytics"
+	}
+];
+/** Read-only coach/athlete queries. Exercise lookups live in the exercise store tools. */
+function registerReadTools(server, ctx) {
+	for (const t of SIMPLE_GETS) server.registerTool(t.name, {
+		title: t.title,
+		description: t.description,
+		inputSchema: {},
+		annotations: READ
+	}, () => apiCall(ctx, "GET", t.path));
+	server.registerTool("list_athletes", {
+		title: "List athletes",
+		description: "Athletes visible to this coach. Optional q (case-insensitive substring filter over each athlete record) and limit, applied client-side, to keep large rosters small.",
+		inputSchema: {
+			q: z.string().optional(),
+			limit: z.number().int().positive().max(500).optional()
+		},
+		annotations: READ
+	}, ({ q, limit }) => attempt(async () => {
+		const res = await ctx.client.request("GET", "/v5/athletes");
+		if (!res.ok) {
+			const detail = typeof res.data === "string" ? res.data : JSON.stringify(res.data);
+			throw new Error(`TrainHeroic API error (HTTP ${res.status}): ${detail}`);
+		}
+		if (!Array.isArray(res.data)) return jsonResult(res.data);
+		let rows = res.data;
+		if (q !== void 0) {
+			const needle = q.toLowerCase();
+			rows = rows.filter((row) => JSON.stringify(row).toLowerCase().includes(needle));
+		}
+		const total = rows.length;
+		if (limit !== void 0 && rows.length > limit) return jsonResult({
+			items: rows.slice(0, limit),
+			returned: limit,
+			total,
+			note: "Limited client-side. Raise limit or narrow with q for the rest."
+		});
+		return jsonResult(rows, { hint: "Filter with q (name/email substring) or cap with limit to shrink this list." });
+	}));
+	server.registerTool("list_teams", {
+		title: "List teams",
+		description: "Coach teams. Optional pagination and search.",
+		inputSchema: {
+			page: z.number().int().positive().optional(),
+			pageSize: z.number().int().positive().optional(),
+			q: z.string().optional()
+		},
+		annotations: READ
+	}, ({ page, pageSize, q }) => {
+		const qs = new URLSearchParams();
+		if (page !== void 0) qs.set("page", String(page));
+		if (pageSize !== void 0) qs.set("pageSize", String(pageSize));
+		if (q !== void 0) qs.set("q", q);
+		const query = qs.toString();
+		return apiCall(ctx, "GET", `/1.0/coach/teams${query ? `?${query}` : ""}`);
+	});
+	server.registerTool("get_team", {
+		title: "Get team",
+		description: "Full team object by team id.",
+		inputSchema: { teamId: idParam },
+		annotations: READ
+	}, ({ teamId }) => apiCall(ctx, "GET", `/v5/teams/${enc(teamId)}`));
+	server.registerTool("list_team_codes", {
+		title: "List team access codes",
+		description: "Join/access codes for a team.",
+		inputSchema: { teamId: idParam },
+		annotations: READ
+	}, ({ teamId }) => apiCall(ctx, "GET", `/v5/teams/${enc(teamId)}/teamCodes`));
+	server.registerTool("get_program", {
+		title: "Get program detail",
+		description: "Full nested program structure (blocks + sessions) live from the API, by program id.",
+		inputSchema: { programId: idParam },
+		annotations: READ
+	}, ({ programId }) => apiCall(ctx, "GET", `/3.0/coach/program/${enc(programId)}`, void 0, "This is a large, deep object. If it is truncated, fetch a narrower view (a specific session) instead."));
+}
+//#endregion
+//#region src/tools/raw.ts
+/**
+* Escape hatch covering every endpoint without a dedicated tool (e.g. the analytics
+* POSTs). GET is ungated; mutating methods go through the same confirmation gate as
+* the dedicated destructive tools so this cannot be used to bypass it.
+*/
+function registerRawTools(server, ctx) {
+	server.registerTool("th_request", {
+		title: "Raw TrainHeroic request",
+		description: "Call any TrainHeroic endpoint directly. `path` is everything after the host. `base` selects the host: 'coach' = api.trainheroic.com (default), 'apis' = apis.trainheroic.com. Prefer dedicated tools where they exist. POST/PUT/DELETE act on the live account and require confirmation.",
+		inputSchema: {
+			method: z.enum([
+				"GET",
+				"POST",
+				"PUT",
+				"DELETE"
+			]),
+			path: z.string().min(1),
+			body: z.unknown().optional(),
+			base: z.enum(["coach", "apis"]).optional(),
+			confirm: z.boolean().optional()
+		},
+		annotations: DESTRUCTIVE
+	}, async ({ method, path, body, base, confirm }, extra) => {
+		if (method !== "GET") {
+			if (!await confirmGate(server, extra.requestId, `Run ${method} ${path} against the live TrainHeroic account?`, confirm)) return errorResult(NOT_CONFIRMED);
+		}
+		const options = {};
+		if (body !== void 0) options.body = body;
+		if (base !== void 0) options.base = base;
+		return apiCall(ctx, method, path, options, "Large or unfiltered response. Add query params to narrow it, or use a dedicated tool for this endpoint if one exists.");
+	});
+}
+//#endregion
+//#region src/tools/exercises.ts
+/**
+* Exercise library tools over the ExerciseIndex — a D1 mirror on the hosted server, an
+* on-disk/in-memory cache locally. The descriptions stay at the interface level so they
+* read correctly on both backends.
+*/
+function registerExerciseTools(server, ctx) {
+	const index = ctx.index;
+	server.registerTool("exercise_resolve", {
+		title: "Resolve exercise name",
+		description: "Map a name to an exercise id via the local mirror. Returns the match plus ranked candidates; when ambiguous, match is null and you should pick from candidates. Units (param_1_unit/param_2_unit) are fixed per exercise — check them before prescribing.",
+		inputSchema: { name: z.string().min(1) },
+		annotations: READ
+	}, ({ name }) => attempt(async () => jsonResult(await index.resolve(name))));
+	server.registerTool("exercise_search", {
+		title: "Search exercises",
+		description: "Ranked fuzzy search over exercise titles. Returns candidates with units.",
+		inputSchema: {
+			query: z.string().min(1),
+			limit: z.number().int().positive().max(100).optional()
+		},
+		annotations: READ
+	}, ({ query, limit }) => attempt(async () => jsonResult(await index.search(query, limit ?? 20))));
+	server.registerTool("exercise_get", {
+		title: "Get exercise",
+		description: "Full exercise object (with units) by id.",
+		inputSchema: { id: idParam },
+		annotations: READ
+	}, ({ id }) => attempt(async () => {
+		const ex = await index.get(toId(id));
+		return ex ? jsonResult(ex) : errorResult(`No exercise with id ${toId(id)}.`);
+	}));
+	server.registerTool("exercise_sync", {
+		title: "Sync exercise library",
+		description: "Refresh the cached exercise index from TrainHeroic.",
+		inputSchema: { force: z.boolean().optional() },
+		annotations: SYNC
+	}, ({ force }) => attempt(async () => {
+		if (force ?? false) return jsonResult(await index.refresh());
+		await index.ensureFresh();
+		return jsonResult(await index.stats());
+	}));
+	server.registerTool("exercise_create", {
+		title: "Create custom exercise",
+		description: "Create a custom exercise (POST /2.0/coach/exercise/create) and write it through to the mirror. Body example: {\"title\":\"Sandbag Clean\",\"param_1_type\":3,\"param_2_type\":1}.",
+		inputSchema: { exercise: exerciseCreateSchema },
+		annotations: {
+			readOnlyHint: false,
+			destructiveHint: false,
+			openWorldHint: true
+		}
+	}, ({ exercise }) => attempt(async () => jsonResult(await index.create(exercise))));
+	server.registerTool("exercise_forget", {
+		title: "Forget exercise (cache only)",
+		description: "Remove an exercise from the local mirror only. Run after deleting it via the API.",
+		inputSchema: { id: idParam },
+		annotations: {
+			readOnlyHint: false,
+			idempotentHint: true,
+			openWorldHint: false
+		}
+	}, ({ id }) => attempt(async () => {
+		await index.recordDelete(toId(id));
+		return jsonResult({ forgotten: toId(id) });
+	}));
+	server.registerTool("store_stats", {
+		title: "Exercise index stats",
+		description: "Row counts and sync state for the cached exercise index.",
+		inputSchema: {},
+		annotations: READ
+	}, () => attempt(async () => jsonResult(await index.stats())));
+}
+//#endregion
+//#region src/tools/workout.ts
+/** Workout building, read-back, publishing, and removal. */
+function registerWorkoutTools(server, ctx) {
+	server.registerTool("workout_build", {
+		title: "Build a workout session (draft)",
+		description: "Build an UNPUBLISHED session from a spec (program -> session -> blocks -> exercises). Two exercises in one block become a superset. Add a block 'leaderboard' for a Red-Zone score, or a top-level 'instruction' for the session note (Coach Instructions). Returns the draft ids, a read-back, and unit advisories. Review, then workout_publish.",
+		inputSchema: {
+			programId: z.number(),
+			date: z.string().optional(),
+			timelineDay: z.number().optional(),
+			blocks: z.array(blockSpecSchema),
+			instruction: z.string().optional()
+		},
+		annotations: {
+			readOnlyHint: false,
+			destructiveHint: false,
+			openWorldHint: true
+		}
+	}, ({ programId, date, timelineDay, blocks, instruction }) => attempt(async () => {
+		if (date === void 0 && timelineDay === void 0) return errorResult("Provide either date (YYYY-M-D) or timelineDay.");
+		const typed = blocks;
+		const opts = {
+			programId,
+			blocks: typed,
+			publish: false
+		};
+		if (date !== void 0) opts.date = parseWorkoutDate(date);
+		if (timelineDay !== void 0) opts.timelineDay = timelineDay;
+		if (instruction !== void 0) opts.instruction = instruction;
+		const advisories = await collectAdvisories(typed, ctx.index);
+		const built = await buildSession(ctx.client, opts);
+		const readback = opts.date ? await readSession(ctx.client, programId, opts.date, built.pwId) : null;
+		return jsonResult({
+			...built,
+			published: false,
+			advisories,
+			readback,
+			note: "Draft created (unpublished). Review, then call workout_publish to make it athlete-facing."
+		});
+	}));
+	server.registerTool("workout_read", {
+		title: "Read a built session",
+		description: "Read-back a session by programId, date (YYYY-M-D), and programWorkout id.",
+		inputSchema: {
+			programId: z.number(),
+			date: z.string(),
+			pwId: z.number()
+		},
+		annotations: {
+			readOnlyHint: true,
+			openWorldHint: true
+		}
+	}, ({ programId, date, pwId }) => attempt(async () => jsonResult(await readSession(ctx.client, programId, parseWorkoutDate(date), pwId))));
+	server.registerTool("workout_publish", {
+		title: "Publish a session",
+		description: "Publish a built session — ATHLETE-FACING and immediate. Requires confirmation (elicitation, or confirm:true).",
+		inputSchema: {
+			programId: z.number(),
+			date: z.string(),
+			pwId: z.number(),
+			confirm: z.boolean().optional()
+		},
+		annotations: {
+			readOnlyHint: false,
+			destructiveHint: true,
+			openWorldHint: true
+		}
+	}, ({ programId, date, pwId, confirm }, extra) => attempt(async () => {
+		if (!await confirmGate(server, extra.requestId, `Publish session ${pwId} on ${date}? This is athlete-facing and immediate.`, confirm)) return errorResult(NOT_CONFIRMED);
+		await publishSession(ctx.client, pwId);
+		return jsonResult({
+			published: pwId,
+			readback: await readSession(ctx.client, programId, parseWorkoutDate(date), pwId)
+		});
+	}));
+	server.registerTool("session_remove", {
+		title: "Remove a session",
+		description: "Delete a session from the live calendar (also the way to replace a date: remove then build). Hard to undo. Requires confirmation (elicitation, or confirm:true).",
+		inputSchema: {
+			programId: z.number(),
+			pwId: z.number(),
+			confirm: z.boolean().optional()
+		},
+		annotations: {
+			readOnlyHint: false,
+			destructiveHint: true,
+			openWorldHint: true
+		}
+	}, ({ programId, pwId, confirm }, extra) => attempt(async () => {
+		if (!await confirmGate(server, extra.requestId, `Delete session ${pwId}? This removes it from the live calendar and is hard to undo.`, confirm)) return errorResult(NOT_CONFIRMED);
+		await removeSession(ctx.client, programId, pwId);
+		return jsonResult({ removed: pwId });
+	}));
+}
+//#endregion
+//#region src/tools/messaging.ts
+function registerReads(server, ctx) {
+	server.registerTool("messaging_conversations", {
+		title: "List conversations (live)",
+		description: "List chat streams (id, kind, title) live from the API; no setup needed. Use the id to read/draft/send.",
+		inputSchema: {},
+		annotations: READ
+	}, () => attempt(async () => {
+		return jsonResult((await fetchStreams(ctx.client)).map(({ stream, kind }) => ({
+			id: stream.id,
+			kind,
+			title: stream.title ?? "",
+			teamId: stream.teamId,
+			userId: stream.userId
+		})));
+	}));
+	server.registerTool("messaging_read", {
+		title: "Read messages (live)",
+		description: "Recent comments in a stream, live from the API (the stream is fetched whole, then trimmed to `limit`).",
+		inputSchema: {
+			streamId: idParam,
+			limit: z.number().int().positive().max(200).optional()
+		},
+		annotations: READ
+	}, ({ streamId, limit }) => attempt(async () => jsonResult(await readLive(ctx.client, toId(streamId), limit ?? 20))));
+	server.registerTool("message_draft", {
+		title: "Draft a message (preview only)",
+		description: "Preview the exact payload and target WITHOUT sending. Always safe.",
+		inputSchema: commentDraftSchema.shape,
+		annotations: READ
+	}, ({ streamId, text, replyTo }) => attempt(async () => {
+		const id = toId(streamId);
+		return jsonResult({
+			draft: true,
+			note: "NOT sent. This is a preview. Run message_send to deliver it.",
+			would_POST: `/v5/messaging/streams/${id}/comments`,
+			payload: buildCommentPayload(id, text, replyTo === void 0 ? null : toId(replyTo))
+		});
+	}));
+}
+function registerWrites(server, ctx) {
+	server.registerTool("message_send", {
+		title: "Send a message",
+		description: "Send a chat message — ATHLETE-FACING and immediate (no draft state on the server). Requires confirmation (elicitation, or confirm:true). Prefer message_draft first.",
+		inputSchema: {
+			...commentDraftSchema.shape,
+			confirm: z.boolean().optional()
+		},
+		annotations: DESTRUCTIVE
+	}, ({ streamId, text, replyTo, confirm }, extra) => attempt(async () => {
+		const id = toId(streamId);
+		if (!await confirmGate(server, extra.requestId, `Send this message to stream ${id}? It is athlete-facing and immediate.`, confirm)) return errorResult(NOT_CONFIRMED);
+		return jsonResult({
+			sent: true,
+			comment: await sendComment(ctx.client, id, text, replyTo === void 0 ? null : toId(replyTo))
+		});
+	}));
+	server.registerTool("message_delete", {
+		title: "Delete a message",
+		description: "Soft-delete a chat message on the live account. Requires confirmation.",
+		inputSchema: {
+			streamId: idParam,
+			commentId: idParam,
+			confirm: z.boolean().optional()
+		},
+		annotations: DESTRUCTIVE
+	}, ({ streamId, commentId, confirm }, extra) => attempt(async () => {
+		if (!await confirmGate(server, extra.requestId, `Delete comment ${toId(commentId)} from stream ${toId(streamId)}? Acts on the live account.`, confirm)) return errorResult(NOT_CONFIRMED);
+		return jsonResult({
+			deleted: true,
+			response: await deleteComment(ctx.client, toId(streamId), toId(commentId))
+		});
+	}));
+}
+/** Live messaging: list/read conversations, draft a message, and the gated send/delete. */
+function registerMessagingTools(server, ctx) {
+	registerReads(server, ctx);
+	registerWrites(server, ctx);
+}
+//#endregion
+export { DEFAULT_RESULT_BUDGET, DESTRUCTIVE, NOT_CONFIRMED, READ, SYNC, apiCall, attempt, boundedSerialize, confirmGate, errorResult, idParam, jsonResult, registerExerciseTools, registerMessagingTools, registerRawTools, registerReadTools, registerWorkoutTools, resultBudget, toId };

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@trainheroic-unofficial/core",
+  "version": "0.1.0",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/alandotcom/trainheroic-skill.git",
+    "directory": "packages/core"
+  },
+  "description": "Shared MCP tool layer for TrainHeroic, used by the local and Cloudflare servers.",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "import": "./dist/index.mjs"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@cfworker/json-schema": "^4.1.1",
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "zod": "^4.4.3",
+    "@trainheroic-unofficial/dto": "0.1.0",
+    "@trainheroic-unofficial/js": "0.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^26.0.0",
+    "tsdown": "^0.22.3",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.9"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  }
+}