@sctg/openclaw-coach 0.1.0 → 2.0.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/README.md +296 -66
- package/assets/fonts/Inter_400Regular.ttf +0 -0
- package/assets/fonts/Inter_600SemiBold.ttf +0 -0
- package/assets/fonts/LICENSE.txt +93 -0
- package/assets/logo.png +0 -0
- package/assets/logo.svg +62 -0
- package/dist/charts/build.d.ts +71 -0
- package/dist/charts/build.js +276 -0
- package/dist/charts/labels.d.ts +38 -0
- package/dist/charts/labels.js +73 -0
- package/dist/charts/render.d.ts +10 -0
- package/dist/charts/render.js +26 -0
- package/dist/charts/svg.d.ts +47 -0
- package/dist/charts/svg.js +92 -0
- package/dist/config.d.ts +25 -0
- package/dist/config.js +38 -0
- package/dist/dates.d.ts +22 -0
- package/dist/dates.js +71 -0
- package/dist/garmin/gc.d.ts +25 -0
- package/dist/garmin/gc.js +81 -0
- package/dist/garmin/normalize.d.ts +20 -0
- package/dist/garmin/normalize.js +132 -0
- package/dist/index.js +188 -163
- package/dist/profile.d.ts +4 -0
- package/dist/profile.js +43 -0
- package/dist/science/associations.d.ts +56 -0
- package/dist/science/associations.js +102 -0
- package/dist/science/healthspan.d.ts +25 -0
- package/dist/science/healthspan.js +89 -0
- package/dist/science/hrv.d.ts +61 -0
- package/dist/science/hrv.js +119 -0
- package/dist/science/load.d.ts +107 -0
- package/dist/science/load.js +228 -0
- package/dist/science/performance.d.ts +93 -0
- package/dist/science/performance.js +191 -0
- package/dist/science/readiness.d.ts +47 -0
- package/dist/science/readiness.js +97 -0
- package/dist/science/recovery.d.ts +74 -0
- package/dist/science/recovery.js +173 -0
- package/dist/science/sleep.d.ts +79 -0
- package/dist/science/sleep.js +165 -0
- package/dist/science/stats.d.ts +50 -0
- package/dist/science/stats.js +201 -0
- package/dist/science/strength.d.ts +47 -0
- package/dist/science/strength.js +120 -0
- package/dist/store.d.ts +36 -0
- package/dist/store.js +78 -0
- package/dist/sync.d.ts +36 -0
- package/dist/sync.js +145 -0
- package/dist/tools.d.ts +427 -0
- package/dist/tools.js +721 -0
- package/dist/types.d.ts +143 -0
- package/dist/types.js +2 -0
- package/docs/SCIENCE.md +717 -0
- package/examples/ATHLETE-fr.md +72 -0
- package/examples/ATHLETE.md +74 -0
- package/examples/PLAN-fr.md +55 -0
- package/examples/PLAN.md +55 -0
- package/openclaw.plugin.json +152 -5
- package/package.json +14 -3
- package/skills/coach/SKILL.md +283 -208
package/dist/store.d.ts
ADDED
|
@@ -0,0 +1,36 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Local store: day records, activities and the journal, as JSON files in the
|
|
3
|
+
* plugin's data directory (owner-only permissions, atomic writes).
|
|
4
|
+
*
|
|
5
|
+
* The store exists because baselines need 60-180 days of history and Garmin
|
|
6
|
+
* cannot be queried for that on every call. It holds nightly aggregates only:
|
|
7
|
+
* no intraday series, no GPS tracks, no credentials.
|
|
8
|
+
*/
|
|
9
|
+
import type { Activity, DayRecord, JournalEntry } from "./types.ts";
|
|
10
|
+
export type StoreData = {
|
|
11
|
+
schemaVersion: 1;
|
|
12
|
+
days: Record<string, DayRecord>;
|
|
13
|
+
/** When each day was last fetched, and whether with per-day detail. */
|
|
14
|
+
fetched: Record<string, {
|
|
15
|
+
at: string;
|
|
16
|
+
detail: boolean;
|
|
17
|
+
}>;
|
|
18
|
+
activities: Record<string, Activity>;
|
|
19
|
+
activitiesSyncedAt: string | null;
|
|
20
|
+
/** First day covered by the stored activity list. */
|
|
21
|
+
activitiesFrom: string | null;
|
|
22
|
+
journal: Record<string, JournalEntry>;
|
|
23
|
+
lthr: {
|
|
24
|
+
value: number;
|
|
25
|
+
at: string;
|
|
26
|
+
} | null;
|
|
27
|
+
};
|
|
28
|
+
export declare function emptyStore(): StoreData;
|
|
29
|
+
export declare function loadStore(dataDir: string): Promise<StoreData>;
|
|
30
|
+
export declare function saveStore(dataDir: string, store: StoreData): Promise<void>;
|
|
31
|
+
/** Drops everything older than the retention period. The journal follows the same rule. */
|
|
32
|
+
export declare function prune(store: StoreData, today: string, retentionDays: number): void;
|
|
33
|
+
/** Day records from `start` to `end`; a missing day is an empty record, so series stay aligned. */
|
|
34
|
+
export declare function daysBetweenDates(store: StoreData, dates: readonly string[]): DayRecord[];
|
|
35
|
+
export declare function emptyDay(date: string): DayRecord;
|
|
36
|
+
export declare function activitiesFrom(store: StoreData, start: string, end: string): Activity[];
|
package/dist/store.js
ADDED
|
@@ -0,0 +1,78 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Local store: day records, activities and the journal, as JSON files in the
|
|
3
|
+
* plugin's data directory (owner-only permissions, atomic writes).
|
|
4
|
+
*
|
|
5
|
+
* The store exists because baselines need 60-180 days of history and Garmin
|
|
6
|
+
* cannot be queried for that on every call. It holds nightly aggregates only:
|
|
7
|
+
* no intraday series, no GPS tracks, no credentials.
|
|
8
|
+
*/
|
|
9
|
+
import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
|
|
10
|
+
import path from "node:path";
|
|
11
|
+
import { addDays } from "./dates.js";
|
|
12
|
+
export function emptyStore() {
|
|
13
|
+
return { schemaVersion: 1, days: {}, fetched: {}, activities: {}, activitiesSyncedAt: null, activitiesFrom: null, journal: {}, lthr: null };
|
|
14
|
+
}
|
|
15
|
+
const FILE = "coach-store.json";
|
|
16
|
+
export async function loadStore(dataDir) {
|
|
17
|
+
try {
|
|
18
|
+
const parsed = JSON.parse(await readFile(path.join(dataDir, FILE), "utf8"));
|
|
19
|
+
if (parsed?.schemaVersion !== 1)
|
|
20
|
+
return emptyStore();
|
|
21
|
+
return { ...emptyStore(), ...parsed };
|
|
22
|
+
}
|
|
23
|
+
catch (error) {
|
|
24
|
+
if (error.code === "ENOENT")
|
|
25
|
+
return emptyStore();
|
|
26
|
+
// A corrupt file must not be silently replaced by an empty store on the next save.
|
|
27
|
+
throw new Error(`Coach store at ${path.join(dataDir, FILE)} is unreadable: ${error.message}`);
|
|
28
|
+
}
|
|
29
|
+
}
|
|
30
|
+
export async function saveStore(dataDir, store) {
|
|
31
|
+
await mkdir(dataDir, { recursive: true, mode: 0o700 });
|
|
32
|
+
const target = path.join(dataDir, FILE);
|
|
33
|
+
const temporary = `${target}.${process.pid}.tmp`;
|
|
34
|
+
await writeFile(temporary, JSON.stringify(store), { mode: 0o600 });
|
|
35
|
+
await rename(temporary, target);
|
|
36
|
+
}
|
|
37
|
+
/** Drops everything older than the retention period. The journal follows the same rule. */
|
|
38
|
+
export function prune(store, today, retentionDays) {
|
|
39
|
+
const cutoff = addDays(today, -retentionDays);
|
|
40
|
+
for (const date of Object.keys(store.days))
|
|
41
|
+
if (date < cutoff)
|
|
42
|
+
delete store.days[date];
|
|
43
|
+
for (const date of Object.keys(store.fetched))
|
|
44
|
+
if (date < cutoff)
|
|
45
|
+
delete store.fetched[date];
|
|
46
|
+
for (const date of Object.keys(store.journal))
|
|
47
|
+
if (date < cutoff)
|
|
48
|
+
delete store.journal[date];
|
|
49
|
+
for (const [id, activity] of Object.entries(store.activities))
|
|
50
|
+
if (activity.date < cutoff)
|
|
51
|
+
delete store.activities[id];
|
|
52
|
+
}
|
|
53
|
+
/** Day records from `start` to `end`; a missing day is an empty record, so series stay aligned. */
|
|
54
|
+
export function daysBetweenDates(store, dates) {
|
|
55
|
+
return dates.map((date) => store.days[date] ?? emptyDay(date));
|
|
56
|
+
}
|
|
57
|
+
export function emptyDay(date) {
|
|
58
|
+
return {
|
|
59
|
+
date,
|
|
60
|
+
sleep: null,
|
|
61
|
+
hrv: null,
|
|
62
|
+
restingHr: null,
|
|
63
|
+
respiration: null,
|
|
64
|
+
spo2: null,
|
|
65
|
+
skinTempDeviationC: null,
|
|
66
|
+
stress: null,
|
|
67
|
+
bodyBattery: null,
|
|
68
|
+
activity: null,
|
|
69
|
+
heartRate: null,
|
|
70
|
+
sources: [],
|
|
71
|
+
errors: {},
|
|
72
|
+
};
|
|
73
|
+
}
|
|
74
|
+
export function activitiesFrom(store, start, end) {
|
|
75
|
+
return Object.values(store.activities)
|
|
76
|
+
.filter((activity) => activity.date >= start && activity.date <= end)
|
|
77
|
+
.sort((a, b) => (a.startLocal ?? a.date).localeCompare(b.startLocal ?? b.date));
|
|
78
|
+
}
|
package/dist/sync.d.ts
ADDED
|
@@ -0,0 +1,36 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Keeps the local store in step with Garmin Connect.
|
|
3
|
+
*
|
|
4
|
+
* - History: missing days are fetched through `gc daily` range requests
|
|
5
|
+
* (28 days per call, about 3 Garmin requests each).
|
|
6
|
+
* - Recent days: the last two days are refetched with per-day detail, because
|
|
7
|
+
* today's record fills in during the day and last night's sleep appears only
|
|
8
|
+
* after the watch has synced.
|
|
9
|
+
* - Activities: one list request for the missing span.
|
|
10
|
+
* A failing signal never blocks the others; errors are returned to the caller.
|
|
11
|
+
*/
|
|
12
|
+
import type { CoachConfig } from "./config.ts";
|
|
13
|
+
import type { GcRunner } from "./garmin/gc.ts";
|
|
14
|
+
import { type StoreData } from "./store.ts";
|
|
15
|
+
export type SyncReport = {
|
|
16
|
+
fetchedDays: number;
|
|
17
|
+
fetchedActivities: number;
|
|
18
|
+
/** Stable error codes by step, e.g. { daily: "auth" }. */
|
|
19
|
+
errors: Record<string, string>;
|
|
20
|
+
skipped: boolean;
|
|
21
|
+
};
|
|
22
|
+
export declare function syncStore(store: StoreData, gc: GcRunner, config: CoachConfig, today: string, now?: Date): Promise<SyncReport>;
|
|
23
|
+
/** How much usable history the store holds, for the data-status tool and the briefing. */
|
|
24
|
+
export declare function coverage(store: StoreData, today: string, historyDays: number): {
|
|
25
|
+
windowDays: number;
|
|
26
|
+
daysWithHrv: number;
|
|
27
|
+
daysWithSleep: number;
|
|
28
|
+
daysWithRestingHr: number;
|
|
29
|
+
daysWithRespiration: number;
|
|
30
|
+
daysWithSpo2: number;
|
|
31
|
+
daysWithSkinTemp: number;
|
|
32
|
+
activities: number;
|
|
33
|
+
activitiesFrom: string | null;
|
|
34
|
+
lastSync: string | null;
|
|
35
|
+
journalEntries: number;
|
|
36
|
+
};
|
package/dist/sync.js
ADDED
|
@@ -0,0 +1,145 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Keeps the local store in step with Garmin Connect.
|
|
3
|
+
*
|
|
4
|
+
* - History: missing days are fetched through `gc daily` range requests
|
|
5
|
+
* (28 days per call, about 3 Garmin requests each).
|
|
6
|
+
* - Recent days: the last two days are refetched with per-day detail, because
|
|
7
|
+
* today's record fills in during the day and last night's sleep appears only
|
|
8
|
+
* after the watch has synced.
|
|
9
|
+
* - Activities: one list request for the missing span.
|
|
10
|
+
* A failing signal never blocks the others; errors are returned to the caller.
|
|
11
|
+
*/
|
|
12
|
+
import { addDays, dateRange, daysBetween } from "./dates.js";
|
|
13
|
+
import { hasSignal, lthrFromPayload, normalizeActivities, parseDailyExport } from "./garmin/normalize.js";
|
|
14
|
+
import { prune } from "./store.js";
|
|
15
|
+
const RANGE_CHUNK_DAYS = 28;
|
|
16
|
+
const DETAIL_DAYS = 2;
|
|
17
|
+
/** `gc daily --detail` accepts at most 14 days. */
|
|
18
|
+
const DETAIL_CHUNK_DAYS = 14;
|
|
19
|
+
const RANGE_TIMEOUT_MS = 90_000;
|
|
20
|
+
/** A stored day is final once it was fetched at least this long after it ended. */
|
|
21
|
+
const FINAL_AFTER_DAYS = 2;
|
|
22
|
+
const LTHR_REFRESH_DAYS = 7;
|
|
23
|
+
function chunks(dates, size) {
|
|
24
|
+
const out = [];
|
|
25
|
+
let start = 0;
|
|
26
|
+
while (start < dates.length) {
|
|
27
|
+
let end = start;
|
|
28
|
+
// A chunk is a run of consecutive dates, at most `size` long.
|
|
29
|
+
while (end + 1 < dates.length && end - start + 1 < size && addDays(dates[end], 1) === dates[end + 1])
|
|
30
|
+
end += 1;
|
|
31
|
+
out.push([dates[start], dates[end]]);
|
|
32
|
+
start = end + 1;
|
|
33
|
+
}
|
|
34
|
+
return out;
|
|
35
|
+
}
|
|
36
|
+
function needsFetch(store, date, today, now, cacheMinutes) {
|
|
37
|
+
const fetched = store.fetched[date];
|
|
38
|
+
if (!fetched)
|
|
39
|
+
return true;
|
|
40
|
+
const age = daysBetween(date, today);
|
|
41
|
+
if (age < DETAIL_DAYS)
|
|
42
|
+
return (now.getTime() - Date.parse(fetched.at)) / 60_000 >= cacheMinutes;
|
|
43
|
+
// Older days are refetched once after they are complete, then never again.
|
|
44
|
+
return daysBetween(date, fetched.at.slice(0, 10)) < FINAL_AFTER_DAYS && age >= FINAL_AFTER_DAYS;
|
|
45
|
+
}
|
|
46
|
+
export async function syncStore(store, gc, config, today, now = new Date()) {
|
|
47
|
+
const report = { fetchedDays: 0, fetchedActivities: 0, errors: {}, skipped: false };
|
|
48
|
+
const stamp = now.toISOString();
|
|
49
|
+
const historyStart = addDays(today, -(config.historyDays - 1));
|
|
50
|
+
const recentStart = addDays(today, -(DETAIL_DAYS - 1));
|
|
51
|
+
const stale = dateRange(historyStart, today).filter((date) => needsFetch(store, date, today, now, config.cacheMinutes));
|
|
52
|
+
const older = stale.filter((date) => date < recentStart);
|
|
53
|
+
const recent = stale.filter((date) => date >= recentStart);
|
|
54
|
+
const apply = (payload, detail, step) => {
|
|
55
|
+
const parsed = parseDailyExport(payload);
|
|
56
|
+
if (!parsed) {
|
|
57
|
+
report.errors[step] = "parse_error";
|
|
58
|
+
return;
|
|
59
|
+
}
|
|
60
|
+
for (const [signal, code] of Object.entries(parsed.errors))
|
|
61
|
+
report.errors[`${step}.${signal}`] = code;
|
|
62
|
+
for (const day of parsed.days) {
|
|
63
|
+
const previous = store.days[day.date];
|
|
64
|
+
// A range fetch must not erase the detail fields of an earlier per-day fetch.
|
|
65
|
+
if (!detail && previous && store.fetched[day.date]?.detail && hasSignal(previous)) {
|
|
66
|
+
store.fetched[day.date] = { at: stamp, detail: true };
|
|
67
|
+
continue;
|
|
68
|
+
}
|
|
69
|
+
if (hasSignal(day) || !previous)
|
|
70
|
+
store.days[day.date] = day;
|
|
71
|
+
store.fetched[day.date] = { at: stamp, detail };
|
|
72
|
+
report.fetchedDays += 1;
|
|
73
|
+
}
|
|
74
|
+
};
|
|
75
|
+
const fatal = (code) => code === "auth" || code === "not_configured" || code === "unsupported";
|
|
76
|
+
// A day first fetched while it was still running holds partial daily totals:
|
|
77
|
+
// it is refetched with detail once it is over. Other old days use range requests.
|
|
78
|
+
const incomplete = older.filter((date) => store.fetched[date]?.detail);
|
|
79
|
+
const missing = older.filter((date) => !store.fetched[date]?.detail);
|
|
80
|
+
const requests = [
|
|
81
|
+
...chunks(missing, RANGE_CHUNK_DAYS).map(([start, end]) => ({ start, end, detail: false, step: "daily" })),
|
|
82
|
+
...chunks(incomplete, DETAIL_CHUNK_DAYS).map(([start, end]) => ({ start, end, detail: true, step: "daily" })),
|
|
83
|
+
...(recent.length ? [{ start: recent[0], end: recent[recent.length - 1], detail: true, step: "recent" }] : []),
|
|
84
|
+
];
|
|
85
|
+
for (const request of requests) {
|
|
86
|
+
const result = await gc(["daily", "--start", request.start, "--end", request.end, request.detail ? "--detail" : "--no-detail"], {
|
|
87
|
+
timeoutMs: RANGE_TIMEOUT_MS,
|
|
88
|
+
});
|
|
89
|
+
if (result.ok) {
|
|
90
|
+
apply(result.data, request.detail, request.step);
|
|
91
|
+
continue;
|
|
92
|
+
}
|
|
93
|
+
report.errors[request.step] = result.code;
|
|
94
|
+
// Without a session or a compatible CLI, every further call would fail the same way.
|
|
95
|
+
if (fatal(result.code))
|
|
96
|
+
return report;
|
|
97
|
+
}
|
|
98
|
+
const loadStart = addDays(today, -(config.loadHistoryDays - 1));
|
|
99
|
+
const activitiesFresh = store.activitiesSyncedAt !== null && (now.getTime() - Date.parse(store.activitiesSyncedAt)) / 60_000 < config.cacheMinutes;
|
|
100
|
+
if (!activitiesFresh) {
|
|
101
|
+
// Refetch the last week too: activities are edited, and a late sync adds old ones.
|
|
102
|
+
const covered = store.activitiesFrom !== null && store.activitiesFrom <= loadStart && store.activitiesSyncedAt !== null;
|
|
103
|
+
const from = covered ? addDays(store.activitiesSyncedAt.slice(0, 10), -7) : loadStart;
|
|
104
|
+
const result = await gc(["activities", "--start", from < loadStart ? loadStart : from, "--end", today], { timeoutMs: RANGE_TIMEOUT_MS });
|
|
105
|
+
if (result.ok) {
|
|
106
|
+
const list = normalizeActivities(result.data);
|
|
107
|
+
for (const activity of list)
|
|
108
|
+
store.activities[activity.id] = activity;
|
|
109
|
+
store.activitiesSyncedAt = stamp;
|
|
110
|
+
if (!covered)
|
|
111
|
+
store.activitiesFrom = loadStart;
|
|
112
|
+
report.fetchedActivities = list.length;
|
|
113
|
+
}
|
|
114
|
+
else {
|
|
115
|
+
report.errors.activities = result.code;
|
|
116
|
+
}
|
|
117
|
+
}
|
|
118
|
+
if (config.lthr === null && (store.lthr === null || daysBetween(store.lthr.at.slice(0, 10), today) >= LTHR_REFRESH_DAYS)) {
|
|
119
|
+
const result = await gc(["metrics", "lactate-threshold"]);
|
|
120
|
+
const value = result.ok ? lthrFromPayload(result.data) : null;
|
|
121
|
+
if (value !== null)
|
|
122
|
+
store.lthr = { value, at: stamp };
|
|
123
|
+
}
|
|
124
|
+
report.skipped = !stale.length && activitiesFresh;
|
|
125
|
+
prune(store, today, config.retentionDays);
|
|
126
|
+
return report;
|
|
127
|
+
}
|
|
128
|
+
/** How much usable history the store holds, for the data-status tool and the briefing. */
|
|
129
|
+
export function coverage(store, today, historyDays) {
|
|
130
|
+
const dates = dateRange(addDays(today, -(historyDays - 1)), today);
|
|
131
|
+
const count = (test) => dates.filter(test).length;
|
|
132
|
+
return {
|
|
133
|
+
windowDays: dates.length,
|
|
134
|
+
daysWithHrv: count((date) => store.days[date]?.hrv?.lastNightAvgMs != null),
|
|
135
|
+
daysWithSleep: count((date) => store.days[date]?.sleep?.durationS != null),
|
|
136
|
+
daysWithRestingHr: count((date) => store.days[date]?.restingHr != null),
|
|
137
|
+
daysWithRespiration: count((date) => store.days[date]?.respiration?.sleepAvg != null),
|
|
138
|
+
daysWithSpo2: count((date) => store.days[date]?.spo2?.sleepAvg != null),
|
|
139
|
+
daysWithSkinTemp: count((date) => store.days[date]?.skinTempDeviationC != null),
|
|
140
|
+
activities: Object.keys(store.activities).length,
|
|
141
|
+
activitiesFrom: store.activitiesFrom,
|
|
142
|
+
lastSync: store.activitiesSyncedAt,
|
|
143
|
+
journalEntries: Object.keys(store.journal).length,
|
|
144
|
+
};
|
|
145
|
+
}
|