kordexa 0.0.0-stage → 0.4.2

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.
Files changed (64) hide show
  1. package/.claude/commands/eduorchestrate-card.md +5 -0
  2. package/.claude/commands/eduorchestrate-log.md +6 -0
  3. package/.claude/commands/eduorchestrate-next.md +5 -0
  4. package/.claude/commands/eduorchestrate-research.md +6 -0
  5. package/.claude/commands/eduorchestrate-send.md +5 -0
  6. package/.claude/commands/eduorchestrate-status.md +5 -0
  7. package/.claude/commands/eduorchestrate-weekly.md +6 -0
  8. package/.claude/commands/kordexa-card.md +5 -0
  9. package/.claude/commands/kordexa-log.md +6 -0
  10. package/.claude/commands/kordexa-next.md +5 -0
  11. package/.claude/commands/kordexa-research.md +6 -0
  12. package/.claude/commands/kordexa-send.md +5 -0
  13. package/.claude/commands/kordexa-status.md +5 -0
  14. package/.claude/commands/kordexa-weekly.md +6 -0
  15. package/.claude/skills/eduorchestrate/SKILL.md +24 -0
  16. package/.claude/skills/kordexa/SKILL.md +24 -0
  17. package/.eduorchestrate/adapters/antigravity/manifest.json +31 -0
  18. package/.eduorchestrate/adapters/codex/AGENTS.md +23 -0
  19. package/.eduorchestrate/adapters/generic/EDUORCHESTRATE.md +19 -0
  20. package/.eduorchestrate/adapters/hermas/manifest.json +31 -0
  21. package/.eduorchestrate/adapters/openclaw/SKILL.md +24 -0
  22. package/.eduorchestrate/mcp/manifest.json +19 -0
  23. package/.eduorchestrate/mcp/server.js +47 -0
  24. package/.kordexa/adapters/antigravity/manifest.json +31 -0
  25. package/.kordexa/adapters/codex/AGENTS.md +23 -0
  26. package/.kordexa/adapters/generic/KORDEXA.md +19 -0
  27. package/.kordexa/adapters/hermas/manifest.json +31 -0
  28. package/.kordexa/adapters/openclaw/SKILL.md +24 -0
  29. package/.kordexa/mcp/manifest.json +19 -0
  30. package/.kordexa/mcp/server.js +47 -0
  31. package/AGENTS.md +25 -0
  32. package/GEMINI.md +7 -0
  33. package/LICENSE +22 -0
  34. package/README.md +311 -2
  35. package/agents/eduorchestrate-agent.yaml +18 -0
  36. package/agents/kordexa-agent.yaml +18 -0
  37. package/bin/kordexa.js +8 -0
  38. package/package.json +38 -4
  39. package/skills/eduorchestrate/SKILL.md +115 -0
  40. package/skills/eduorchestrate/agents/openai.yaml +4 -0
  41. package/skills/eduorchestrate/assets/default-terminal-card.svg +1 -0
  42. package/skills/eduorchestrate/references/agent-contracts.md +107 -0
  43. package/skills/eduorchestrate/references/learning-system.md +119 -0
  44. package/skills/kordexa/SKILL.md +115 -0
  45. package/skills/kordexa/agents/openai.yaml +4 -0
  46. package/skills/kordexa/assets/default-terminal-card.svg +1 -0
  47. package/skills/kordexa/references/agent-contracts.md +107 -0
  48. package/skills/kordexa/references/learning-system.md +119 -0
  49. package/src/adapters.js +203 -0
  50. package/src/card-components.js +103 -0
  51. package/src/cli.js +505 -0
  52. package/src/config.js +118 -0
  53. package/src/courses.js +150 -0
  54. package/src/email.js +173 -0
  55. package/src/harness.js +130 -0
  56. package/src/planner.js +423 -0
  57. package/src/progress.js +93 -0
  58. package/src/progression-card.js +137 -0
  59. package/src/prompts.js +77 -0
  60. package/src/research.js +288 -0
  61. package/src/workflow.js +161 -0
  62. package/tests/node/eduorchestrate.test.js +558 -0
  63. package/tests/node/launch-ready.test.js +101 -0
  64. package/tests/node/safe-setup.test.js +313 -0
package/src/planner.js ADDED
@@ -0,0 +1,423 @@
1
+ import { inferRoleKey } from "./research.js";
2
+
3
+ const ROLE_BLUEPRINTS = {
4
+ "agentic-ai": {
5
+ label: "Agentic AI and LLM Engineer",
6
+ capstone: "agentic RAG assistant with evaluation and deployment notes",
7
+ topics: [
8
+ ["Role intro and tool setup", ["Hugging Face", "GitHub", "Google Colab"], "Create accounts, open a Colab notebook, and clone or fork one starter repo."],
9
+ ["Python notebook fluency", ["Python", "Colab", "notebooks"], "Run a notebook that loads data, prints results, and saves notes."],
10
+ ["LLM basics", ["tokens", "context windows", "inference"], "Write a short explanation of how prompts become model outputs."],
11
+ ["Prompt engineering", ["system prompts", "examples", "constraints"], "Build three prompt variants and compare outputs."],
12
+ ["Embeddings", ["vectors", "semantic search", "similarity"], "Create a tiny embedding search demo."],
13
+ ["RAG architecture", ["retrieval", "chunking", "grounding"], "Sketch and implement a minimal RAG pipeline."],
14
+ ["Vector stores", ["FAISS", "Chroma", "metadata"], "Index a small document set and retrieve relevant chunks."],
15
+ ["Hugging Face models", ["transformers", "datasets", "model cards"], "Load a small model or dataset and document constraints."],
16
+ ["Fine-tuning concepts", ["LoRA", "QLoRA", "PEFT"], "Read a fine-tuning tutorial and list hardware limits."],
17
+ ["Colab fine-tuning setup", ["GPU runtime", "datasets", "checkpoints"], "Prepare a dry-run notebook for fine-tuning."],
18
+ ["Evaluation basics", ["golden sets", "metrics", "rubrics"], "Create five test questions and expected traits."],
19
+ ["LLM app backend", ["API", "streaming", "timeouts"], "Create a simple endpoint or script wrapper."],
20
+ ["Agent tools", ["tool calling", "function schema", "state"], "Define two tools and test their input/output contracts."],
21
+ ["Agent planning", ["tasks", "handoffs", "memory"], "Build a simple planner-executor loop."],
22
+ ["Multi-agent workflow", ["researcher", "builder", "evaluator"], "Split one task across three agent roles."],
23
+ ["Safety and guardrails", ["validation", "refusal", "scope"], "Add input checks and output constraints."],
24
+ ["GitHub portfolio hygiene", ["README", "issues", "commits"], "Polish one repo with setup steps and screenshots."],
25
+ ["Deployment basics", ["env vars", "secrets", "hosting"], "Deploy or document a runnable local service."],
26
+ ["Observability", ["logs", "traces", "costs"], "Add structured logs to one agent run."],
27
+ ["RAG improvement", ["reranking", "citations", "chunk tests"], "Improve retrieval quality and show before/after evidence."],
28
+ ["Model comparison", ["latency", "quality", "price"], "Compare two model choices with a small rubric."],
29
+ ["Data preparation", ["cleaning", "splits", "licenses"], "Prepare a tiny dataset and document license concerns."],
30
+ ["Fine-tuning practice", ["training loop", "adapter", "eval"], "Run or dry-run a small adapter training notebook."],
31
+ ["Agent evaluation", ["task success", "regression set", "manual review"], "Create a regression checklist for agent behavior."],
32
+ ["Capstone planning", ["problem", "users", "scope"], "Choose a capstone agent and define the smallest useful version."],
33
+ ["Capstone build day 1", ["architecture", "tools", "data"], "Implement the first end-to-end path."],
34
+ ["Capstone build day 2", ["polish", "errors", "tests"], "Add error handling and tests."],
35
+ ["Capstone evaluation", ["demo", "rubric", "limits"], "Run a demo and document failures."],
36
+ ["Interview story", ["tradeoffs", "metrics", "ownership"], "Write a STAR-style explanation of the capstone."],
37
+ ["Portfolio release", ["README", "demo", "next steps"], "Publish final notes and define the next 30 days."]
38
+ ]
39
+ },
40
+ "full-stack": {
41
+ label: "Full-Stack Developer",
42
+ capstone: "authenticated full-stack dashboard deployed with tests",
43
+ topics: [
44
+ ["Role map and dev setup", ["GitHub", "Node.js", "editor"], "Create a repo, install Node.js, and run a starter web app."],
45
+ ["HTML structure", ["semantic HTML", "forms", "accessibility"], "Build a semantic profile page."],
46
+ ["CSS layout", ["flexbox", "grid", "responsive"], "Make the profile responsive across mobile and desktop."],
47
+ ["JavaScript basics", ["DOM", "events", "state"], "Add interactive filtering or toggles."],
48
+ ["TypeScript basics", ["types", "interfaces", "compiler"], "Convert one script to TypeScript-style typed thinking."],
49
+ ["React components", ["props", "state", "composition"], "Build reusable UI components."],
50
+ ["Routing and pages", ["routes", "navigation", "loading"], "Create a two-page app."],
51
+ ["API design", ["REST", "status codes", "JSON"], "Design and mock a simple API."],
52
+ ["Backend server", ["Node", "handlers", "middleware"], "Create a minimal backend endpoint."],
53
+ ["Database basics", ["tables", "queries", "schema"], "Model one useful table and seed sample rows."],
54
+ ["Auth concepts", ["sessions", "JWT", "permissions"], "Sketch an auth flow and protect one route."],
55
+ ["Form validation", ["client validation", "server validation", "errors"], "Build a robust form with errors."],
56
+ ["Testing basics", ["unit", "integration", "fixtures"], "Write tests for one utility and one API path."],
57
+ ["Deployment", ["env vars", "hosting", "builds"], "Deploy or document deployment for the app."],
58
+ ["Observability", ["logs", "errors", "metrics"], "Add useful logs and error boundaries."],
59
+ ["Performance", ["bundle", "caching", "lazy loading"], "Measure and improve one bottleneck."],
60
+ ["Security basics", ["XSS", "CSRF", "secrets"], "Review the app against common web risks."],
61
+ ["Accessibility pass", ["keyboard", "labels", "contrast"], "Fix three accessibility issues."],
62
+ ["API integration", ["fetch", "loading state", "retry"], "Connect frontend to backend data."],
63
+ ["State management", ["local state", "server state", "cache"], "Clean up app state flow."],
64
+ ["Feature planning", ["user story", "scope", "acceptance"], "Plan the capstone feature."],
65
+ ["Capstone backend", ["schema", "API", "validation"], "Implement the backend for the capstone."],
66
+ ["Capstone frontend", ["components", "forms", "states"], "Implement the frontend for the capstone."],
67
+ ["Capstone testing", ["unit", "integration", "manual QA"], "Add regression coverage."],
68
+ ["Capstone deployment", ["hosting", "env", "domain"], "Deploy or create a reproducible deployment guide."],
69
+ ["Code review", ["readability", "duplication", "errors"], "Refactor one rough section."],
70
+ ["Portfolio README", ["setup", "screenshots", "demo"], "Write a recruiter-friendly README."],
71
+ ["Interview practice", ["architecture", "tradeoffs", "debugging"], "Explain the app architecture aloud."],
72
+ ["Mock task", ["bug fix", "feature request", "deadline"], "Complete a timed practical task."],
73
+ ["Release and next plan", ["release notes", "next steps", "gaps"], "Publish release notes and next 30-day plan."]
74
+ ]
75
+ },
76
+ "cybersecurity": {
77
+ label: "Cybersecurity Analyst",
78
+ capstone: "home SOC investigation report with detections and response notes",
79
+ topics: [
80
+ ["Role map and lab setup", ["Linux", "networking", "GitHub"], "Create a lab notes repo and install basic analysis tools."],
81
+ ["Networking basics", ["IP", "DNS", "HTTP"], "Trace a simple request and document each hop."],
82
+ ["Linux command line", ["files", "processes", "permissions"], "Collect system facts using CLI commands."],
83
+ ["Security fundamentals", ["CIA triad", "risk", "controls"], "Map one common attack to controls."],
84
+ ["Threat modeling", ["assets", "threats", "mitigations"], "Threat-model a login form."],
85
+ ["Logs basics", ["events", "fields", "timestamps"], "Parse a sample log file."],
86
+ ["SIEM thinking", ["queries", "alerts", "triage"], "Write three detection-style queries in plain language."],
87
+ ["MITRE ATT&CK", ["tactics", "techniques", "procedures"], "Map one incident scenario to ATT&CK."],
88
+ ["Phishing triage", ["headers", "URLs", "attachments"], "Write a phishing investigation checklist."],
89
+ ["Endpoint basics", ["processes", "persistence", "artifacts"], "Document suspicious endpoint indicators."],
90
+ ["Vulnerability basics", ["CVEs", "CVSS", "patching"], "Summarize one recent advisory."],
91
+ ["Web security", ["XSS", "SQLi", "auth"], "Test a deliberately vulnerable sample safely."],
92
+ ["Incident response", ["identify", "contain", "eradicate"], "Draft a response playbook."],
93
+ ["Detection engineering", ["signal", "noise", "false positives"], "Improve one noisy alert rule."],
94
+ ["Cloud basics", ["IAM", "logs", "storage"], "Review a mock cloud permissions issue."],
95
+ ["Security automation", ["Python", "parsing", "reporting"], "Write a small log summarizer."],
96
+ ["Evidence handling", ["timeline", "notes", "chain"], "Build an incident timeline."],
97
+ ["SOC communication", ["severity", "impact", "next action"], "Write a concise escalation note."],
98
+ ["Malware basics", ["hashes", "sandbox", "IOCs"], "Create a safe malware-analysis glossary."],
99
+ ["Blue-team project plan", ["data", "detections", "report"], "Plan the capstone investigation."],
100
+ ["Capstone data collection", ["logs", "events", "sources"], "Collect or create sample log data."],
101
+ ["Capstone detection", ["query", "alert", "triage"], "Implement one detection workflow."],
102
+ ["Capstone analysis", ["timeline", "IOCs", "scope"], "Analyze the sample incident."],
103
+ ["Capstone report", ["summary", "evidence", "recommendations"], "Write the first report draft."],
104
+ ["Capstone improvement", ["false positives", "coverage", "limits"], "Improve detection quality."],
105
+ ["Portfolio polish", ["README", "screenshots", "safe data"], "Publish sanitized project evidence."],
106
+ ["Interview scenarios", ["triage", "escalation", "tradeoffs"], "Practice three SOC interview prompts."],
107
+ ["Current threats", ["advisories", "patches", "impact"], "Summarize one current CISA advisory."],
108
+ ["Mock shift", ["alerts", "notes", "handoff"], "Complete a timed triage simulation."],
109
+ ["Release and next plan", ["gaps", "certs", "labs"], "Define the next 30-day security path."]
110
+ ]
111
+ },
112
+ "data-science": {
113
+ label: "Data Scientist",
114
+ capstone: "end-to-end analysis notebook with model, metrics, and stakeholder summary",
115
+ topics: [
116
+ ["Role map and notebook setup", ["Python", "Jupyter", "GitHub"], "Create a notebook repo and run a starter analysis."],
117
+ ["Python data basics", ["lists", "dicts", "functions"], "Write utilities for simple data transformations."],
118
+ ["pandas basics", ["DataFrame", "filtering", "groupby"], "Analyze a small CSV."],
119
+ ["Data cleaning", ["missing values", "types", "outliers"], "Clean a messy sample dataset."],
120
+ ["Visualization basics", ["charts", "labels", "story"], "Create three useful charts."],
121
+ ["Statistics basics", ["mean", "variance", "distribution"], "Explain one dataset statistically."],
122
+ ["SQL basics", ["select", "join", "aggregate"], "Answer five questions with SQL."],
123
+ ["Feature engineering", ["encoding", "scaling", "leakage"], "Create features and document risks."],
124
+ ["Train/test split", ["validation", "leakage", "baseline"], "Create a baseline model."],
125
+ ["Regression", ["loss", "features", "residuals"], "Train and evaluate a regression model."],
126
+ ["Classification", ["precision", "recall", "confusion matrix"], "Train and evaluate a classifier."],
127
+ ["Model evaluation", ["metrics", "tradeoffs", "thresholds"], "Compare two models."],
128
+ ["Notebook hygiene", ["sections", "reproducibility", "outputs"], "Refactor a notebook for readability."],
129
+ ["Experiment tracking", ["parameters", "results", "notes"], "Create a simple experiment log."],
130
+ ["Communication", ["summary", "audience", "decision"], "Write a stakeholder summary."],
131
+ ["Ethics and bias", ["sampling", "fairness", "limits"], "Document dataset limitations."],
132
+ ["Deployment thinking", ["batch", "API", "monitoring"], "Sketch how the model would be used."],
133
+ ["Portfolio project plan", ["question", "data", "metric"], "Plan the capstone analysis."],
134
+ ["Capstone data collection", ["source", "license", "schema"], "Choose and document a dataset."],
135
+ ["Capstone cleaning", ["quality", "types", "missing"], "Clean the capstone dataset."],
136
+ ["Capstone EDA", ["patterns", "segments", "charts"], "Create the first analysis story."],
137
+ ["Capstone modeling", ["baseline", "metric", "validation"], "Train a baseline model."],
138
+ ["Capstone improvement", ["features", "tuning", "comparison"], "Improve and compare the model."],
139
+ ["Capstone explanation", ["importance", "limits", "risks"], "Explain model behavior and limits."],
140
+ ["Capstone report", ["executive summary", "charts", "recommendations"], "Write the report draft."],
141
+ ["Portfolio README", ["setup", "dataset", "results"], "Create a professional project README."],
142
+ ["Interview practice", ["case study", "metrics", "tradeoffs"], "Answer three data-science interview prompts."],
143
+ ["Current tools", ["libraries", "MLOps", "LLMs"], "Research one current data tooling update."],
144
+ ["Mock task", ["analysis", "timebox", "recommendation"], "Complete a timed mini analysis."],
145
+ ["Release and next plan", ["gaps", "projects", "interviews"], "Define the next 30-day data path."]
146
+ ]
147
+ }
148
+ };
149
+
150
+ export function generate30DayPlan(profile) {
151
+ const role = profile.targetRole || "Agentic AI and LLM Engineer";
152
+ const roleKey = inferRoleKey(role);
153
+ const blueprint = ROLE_BLUEPRINTS[roleKey] || ROLE_BLUEPRINTS["agentic-ai"];
154
+ const requestedDays = Math.max(30, Number.parseInt(profile.planDays, 10) || 30);
155
+ const primarySkill = profile.focusSkill || blueprint.topics[0][0];
156
+ const topics = prioritizeTopics(blueprint.topics, primarySkill, requestedDays, role);
157
+ return {
158
+ generatedAt: new Date().toISOString(),
159
+ command: "/kordexa",
160
+ learner: profile,
161
+ roleKey,
162
+ requestedDays,
163
+ primarySkill,
164
+ currentLearning: profile.currentLearning || "not specified",
165
+ capstone: blueprint.capstone,
166
+ phases: createPhases(requestedDays),
167
+ days: topics.slice(0, requestedDays).map(([title, concepts, task], index) => buildDay(index + 1, role, title, concepts, task, blueprint, primarySkill)),
168
+ nextSkillRecommendation: recommendNextSkill(roleKey, primarySkill, blueprint, requestedDays)
169
+ };
170
+ }
171
+
172
+ function buildDay(day, role, title, concepts, task, blueprint, primarySkill) {
173
+ const query = encodeURIComponent(`${role} ${title} tutorial`);
174
+ const codeQuery = encodeURIComponent(`${role} ${title} sample code GitHub`);
175
+ const docsQuery = encodeURIComponent(`${role} ${concepts.join(" ")} official docs`);
176
+ const difficulty = day <= 7 ? "foundation" : day <= 15 ? "applied" : day <= 24 ? "portfolio" : day <= 30 ? "release" : "next-skill-ramp";
177
+ const currentYear = new Date().getFullYear();
178
+ const trendQuery = encodeURIComponent(`${role} ${title} ${primarySkill} trending tools ${currentYear}`);
179
+ return {
180
+ day,
181
+ title,
182
+ difficulty,
183
+ goal: `Move toward ${role} by completing one focused artifact for ${title}.`,
184
+ primarySkill,
185
+ concepts,
186
+ setupOrBuildTask: task,
187
+ timeBox: {
188
+ learnMinutes: day <= 7 ? 35 : 25,
189
+ buildMinutes: day <= 7 ? 45 : 70,
190
+ reviewMinutes: 15
191
+ },
192
+ references: [
193
+ { type: "docs-search", title: "Official docs search", url: `https://www.google.com/search?q=${docsQuery}` },
194
+ { type: "trend-search", title: "Trending knowledge search", url: `https://www.google.com/search?q=${trendQuery}` },
195
+ { type: "video-search", title: "YouTube tutorial search", url: `https://www.youtube.com/results?search_query=${query}` },
196
+ { type: "code-search", title: "GitHub sample code search", url: `https://github.com/search?q=${codeQuery}&type=repositories` }
197
+ ],
198
+ proof: "Save notes, code, screenshot, log, or demo output that proves today's task was attempted.",
199
+ portfolioArtifact: day >= 16 ? `Improve the ${blueprint.capstone}.` : "Add one small note or commit that can feed the capstone later.",
200
+ reviewQuestions: [
201
+ "What did I build or prove today?",
202
+ "What is the most important blocker?",
203
+ "What should tomorrow preserve or change?"
204
+ ],
205
+ stretch: day % 3 === 0 ? "Explain today's work in 5 bullet points as if answering an interview question." : "Skip stretch work unless the base proof is complete.",
206
+ nextDayBridge: "Write one blocker and one question to carry into tomorrow."
207
+ };
208
+ }
209
+
210
+ function prioritizeTopics(topics, primarySkill, requestedDays, role) {
211
+ const lowered = primarySkill.toLowerCase();
212
+ const setup = topics[0];
213
+ const body = topics.slice(1);
214
+ const matching = body.filter(([title, concepts]) => `${title} ${concepts.join(" ")}`.toLowerCase().includes(lowered));
215
+ const remaining = body.filter((topic) => !matching.includes(topic));
216
+ const focusIntro = [`Primary skill focus: ${primarySkill}`, [primarySkill, "current trends", "practical proof"], `Build a first visible artifact for ${primarySkill} in the ${role} role.`];
217
+ const ordered = [setup, ...(matching.length ? matching : [focusIntro]), ...remaining];
218
+ const expanded = [...ordered];
219
+ while (expanded.length < requestedDays) {
220
+ const index = expanded.length + 1;
221
+ expanded.push([
222
+ `Next-skill adaptation day ${index}`,
223
+ [primarySkill, "trend adaptation", "portfolio evidence"],
224
+ `Review current trends for ${primarySkill}, upgrade the capstone, and log evidence for what changed.`
225
+ ]);
226
+ }
227
+ return expanded;
228
+ }
229
+
230
+ function createPhases(days) {
231
+ return [
232
+ { days: `1-${Math.min(7, days)}`, name: "Setup and first-skill foundations" },
233
+ { days: `8-${Math.min(15, days)}`, name: "Applied practice and trend adaptation" },
234
+ { days: `16-${Math.min(24, days)}`, name: "Portfolio build" },
235
+ { days: `25-${Math.min(30, days)}`, name: "Release and interview proof" },
236
+ ...(days > 30 ? [{ days: `31-${days}`, name: "Next-skill ramp and trend refresh" }] : [])
237
+ ].filter((phase) => !phase.days.includes("8-7") && !phase.days.includes("16-15") && !phase.days.includes("25-24"));
238
+ }
239
+
240
+ function recommendNextSkill(roleKey, primarySkill, blueprint, requestedDays) {
241
+ const flattened = blueprint.topics.flatMap(([, concepts]) => concepts);
242
+ const next = flattened.find((concept) => concept.toLowerCase() !== primarySkill.toLowerCase()) || "capstone deployment and interview proof";
243
+ const roleSpecific = {
244
+ "agentic-ai": "LLM evaluation and production agent observability",
245
+ "full-stack": "backend reliability, auth, and deployment automation",
246
+ cybersecurity: "detection engineering and incident reporting",
247
+ "data-science": "model evaluation, communication, and deployment thinking"
248
+ };
249
+ return {
250
+ afterDay: requestedDays,
251
+ currentFocus: primarySkill,
252
+ recommendedNextSkill: roleSpecific[roleKey] || next,
253
+ reason: `After at least ${requestedDays} days on ${primarySkill}, move to a skill that improves portfolio depth, current-market relevance, and interview proof.`
254
+ };
255
+ }
256
+
257
+ export function renderDailyEmail(config, plan, dayNumber, { progressReview = null, researchDigest = null, progressionCard = null, coursePack = null } = {}) {
258
+ const day = plan.days.find((entry) => entry.day === dayNumber) || plan.days[0];
259
+ const references = day.references.map((ref) => `- ${ref.title}: ${ref.url}`).join("\n");
260
+ const timeBox = `Learn ${day.timeBox.learnMinutes}m, build ${day.timeBox.buildMinutes}m, review ${day.timeBox.reviewMinutes}m`;
261
+ const research = researchDigest
262
+ ? ["", "Fresh research digest:", `Topic: ${researchDigest.topic}`, ...researchDigest.sources.slice(0, 5).map((source) => `- ${source.title}: ${source.url}`)]
263
+ : [];
264
+ const topLinkLines = [];
265
+ if (researchDigest?.topVideo?.url) {
266
+ if (researchDigest.topVideo.resolved && researchDigest.topVideo.title) topLinkLines.push(`Watch (video): ${researchDigest.topVideo.title}`);
267
+ topLinkLines.push(`Watch (video): ${researchDigest.topVideo.url}`);
268
+ }
269
+ if (researchDigest?.topRepo?.url) {
270
+ if (researchDigest.topRepo.resolved && researchDigest.topRepo.title) topLinkLines.push(`Build from (repo): ${researchDigest.topRepo.title}`);
271
+ topLinkLines.push(`Build from (repo): ${researchDigest.topRepo.url}`);
272
+ }
273
+ if (researchDigest?.topDoc?.url) topLinkLines.push(`Read (docs): ${researchDigest.topDoc.url}`);
274
+ const topLinks = topLinkLines.length ? ["", "Today's links (open these first):", ...topLinkLines] : [];
275
+ const progress = progressReview
276
+ ? ["", "Progress signal:", `Momentum: ${progressReview.momentum}`, `Next action: ${progressReview.nextAction}`, `Risk: ${progressReview.risk}`]
277
+ : [];
278
+ const card = progressionCard
279
+ ? ["", "Skill learning progression card:", progressionCard.markdown]
280
+ : [];
281
+ const courses = coursePack
282
+ ? [
283
+ "",
284
+ "Role-specific learning sources:",
285
+ ...coursePack.recommendedSources.slice(0, 2).map((source) => `- ${source.title}: ${source.url}`),
286
+ "Newsletters/update feeds:",
287
+ ...coursePack.newsletters.slice(0, 2).map((source) => `- ${source.title}: ${source.url}`),
288
+ "Full source pack: data/learning-sources.md"
289
+ ]
290
+ : [];
291
+ const text = [
292
+ `Hi ${config.learner.name},`,
293
+ "",
294
+ `Today is Day ${day.day} for your ${config.learner.targetRole} path.`,
295
+ `Current learning: ${config.learner.currentLearning || "not specified"}`,
296
+ `Primary skill focus: ${day.primarySkill}`,
297
+ "",
298
+ `Goal: ${day.goal}`,
299
+ `Difficulty: ${day.difficulty}`,
300
+ `Timebox: ${timeBox}`,
301
+ `Concepts: ${day.concepts.join(", ")}`,
302
+ `Build task: ${day.setupOrBuildTask}`,
303
+ `Portfolio link: ${day.portfolioArtifact}`,
304
+ ...topLinks,
305
+ "",
306
+ "References to research:",
307
+ references,
308
+ ...research,
309
+ "",
310
+ `Proof: ${day.proof}`,
311
+ `Stretch: ${day.stretch}`,
312
+ "Review questions:",
313
+ ...day.reviewQuestions.map((question) => `- ${question}`),
314
+ ...progress,
315
+ ...courses,
316
+ ...card,
317
+ "",
318
+ `Bridge: ${day.nextDayBridge}`,
319
+ "",
320
+ "Use /kordexa in your agent to adjust the plan or review progress."
321
+ ].join("\n");
322
+ const html = renderDailyEmailHtml({ config, day, timeBox, researchDigest, progressReview, progressionCard, coursePack });
323
+ return {
324
+ to: config.learner.email,
325
+ subject: `Kordexa Day ${day.day}: ${day.title}`,
326
+ text,
327
+ html
328
+ };
329
+ }
330
+
331
+ function escapeHtml(value) {
332
+ return String(value)
333
+ .replace(/&/g, "&amp;")
334
+ .replace(/</g, "&lt;")
335
+ .replace(/>/g, "&gt;")
336
+ .replace(/"/g, "&quot;");
337
+ }
338
+
339
+ function renderDailyEmailHtml({ config, day, timeBox, researchDigest, progressReview, progressionCard, coursePack }) {
340
+ const orange = "#e97926";
341
+ const muted = "#9c9188";
342
+ const ink = "#2a2520";
343
+
344
+ const mono = "ui-monospace,Menlo,Consolas,monospace";
345
+
346
+ // Each top link shows the resolved TITLE plus its actual, visible URL.
347
+ const linkCard = (label, title, url, watch) => `<div style="margin:0 0 10px;padding:12px 14px;border:1px solid #e2d8cf;border-radius:10px;background:#fbf6ef;">
348
+ <div style="font-size:11px;color:${muted};text-transform:uppercase;letter-spacing:.06em;margin-bottom:5px;">${escapeHtml(label)}</div>
349
+ <a href="${escapeHtml(url)}" style="color:#0a0a0a;font-weight:600;font-size:15px;line-height:1.3;text-decoration:none;">${escapeHtml(title)}</a>
350
+ ${watch ? `<a href="${escapeHtml(url)}" style="display:inline-block;margin:8px 8px 2px 0;padding:7px 12px;background:${orange};color:#ffffff;border-radius:7px;font-size:13px;font-weight:600;text-decoration:none;">Watch ▶</a>` : ""}
351
+ <div style="margin-top:5px;"><a href="${escapeHtml(url)}" style="color:${orange};font-family:${mono};font-size:12px;word-break:break-all;text-decoration:underline;">${escapeHtml(url)}</a></div>
352
+ </div>`;
353
+
354
+ const topCards = [];
355
+ if (researchDigest?.topVideo?.url) topCards.push(linkCard("Watch — top video for today", researchDigest.topVideo.title || "Top video", researchDigest.topVideo.url, true));
356
+ if (researchDigest?.topRepo?.url) topCards.push(linkCard("Build from — top repo", researchDigest.topRepo.title || "Top repo", researchDigest.topRepo.url, false));
357
+ if (researchDigest?.topDoc?.url) topCards.push(linkCard("Read — official docs", researchDigest.topDoc.title || "Docs", researchDigest.topDoc.url, false));
358
+ const topBlock = topCards.length ? `<div style="margin:4px 0 18px;">${topCards.join("")}</div>` : "";
359
+
360
+ const link = (label, url) => `<a href="${escapeHtml(url)}" style="color:${orange};text-decoration:none;">${escapeHtml(label)}</a>`;
361
+ const listItems = (items) => items.map((line) => `<li style="margin:4px 0;">${line}</li>`).join("");
362
+
363
+ // "More to skim" also shows each title above its visible URL.
364
+ const moreItem = (title, url) => `<li style="margin:8px 0;list-style:none;"><a href="${escapeHtml(url)}" style="color:#0a0a0a;font-weight:600;text-decoration:none;">${escapeHtml(title)}</a><br><a href="${escapeHtml(url)}" style="color:${orange};font-family:${mono};font-size:12px;word-break:break-all;text-decoration:none;">${escapeHtml(url)}</a></li>`;
365
+ const moreVideos = (researchDigest?.videos || []).slice(1, 3).map((video) => moreItem(video.title || video.url, video.url));
366
+ const moreRepos = (researchDigest?.repos || []).slice(1, 3).map((repo) => moreItem(`${repo.title}${repo.stars != null ? ` (★${repo.stars})` : ""}`, repo.url));
367
+ const moreLinks = [...moreVideos, ...moreRepos];
368
+ const moreBlock = moreLinks.length
369
+ ? `<p style="margin:16px 0 4px;font-weight:600;font-size:14px;">More to skim</p><ul style="margin:0 0 8px;padding:0;font-size:14px;color:${ink};">${moreLinks.join("")}</ul>`
370
+ : "";
371
+
372
+ const refs = day.references.map((ref) => link(ref.title, ref.url));
373
+ const refsBlock = `<p style="margin:16px 0 4px;font-weight:600;font-size:14px;">Research entry points</p><ul style="margin:0 0 8px;padding-left:18px;font-size:14px;color:${ink};">${listItems(refs)}</ul>`;
374
+
375
+ const facts = [
376
+ ["Difficulty", day.difficulty],
377
+ ["Timebox", timeBox],
378
+ ["Concepts", day.concepts.join(", ")],
379
+ ["Build task", day.setupOrBuildTask],
380
+ ["Portfolio", day.portfolioArtifact]
381
+ ]
382
+ .map(([k, v]) => `<tr><td style="padding:4px 12px 4px 0;color:${muted};font-size:13px;vertical-align:top;white-space:nowrap;">${k}</td><td style="padding:4px 0;font-size:14px;color:${ink};">${escapeHtml(v)}</td></tr>`)
383
+ .join("");
384
+
385
+ const progressBlock = progressReview
386
+ ? `<p style="margin:16px 0 4px;font-weight:600;font-size:14px;">Progress signal</p><p style="margin:0;font-size:14px;color:${ink};">Momentum: <b>${escapeHtml(progressReview.momentum)}</b> · Next: ${escapeHtml(progressReview.nextAction)}</p>`
387
+ : "";
388
+
389
+ const coursesBlock = coursePack
390
+ ? `<p style="margin:16px 0 4px;font-weight:600;font-size:14px;">Official learning sources</p><ul style="margin:0 0 8px;padding-left:18px;font-size:14px;color:${ink};">${listItems(coursePack.recommendedSources.slice(0, 2).map((s) => link(s.title, s.url)))}</ul>`
391
+ : "";
392
+
393
+ const cardBlock = progressionCard
394
+ ? `<p style="margin:16px 0 4px;font-weight:600;font-size:14px;">Progression card</p><pre style="margin:0;padding:14px;background:#0d1117;color:#c9d1d9;border-radius:10px;font-family:ui-monospace,Menlo,Consolas,monospace;font-size:12px;line-height:1.5;overflow:auto;white-space:pre-wrap;">${escapeHtml(progressionCard.terminalLines ? progressionCard.terminalLines.join("\n") : progressionCard.markdown)}</pre>`
395
+ : "";
396
+
397
+ const questions = `<p style="margin:16px 0 4px;font-weight:600;font-size:14px;">Review questions</p><ul style="margin:0;padding-left:18px;font-size:14px;color:${ink};">${listItems(day.reviewQuestions.map(escapeHtml))}</ul>`;
398
+
399
+ return `<!doctype html>
400
+ <html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"></head>
401
+ <body style="margin:0;background:#f4f1ec;font-family:-apple-system,BlinkMacSystemFont,'Segoe UI',Roboto,Helvetica,Arial,sans-serif;color:${ink};">
402
+ <div style="max-width:640px;margin:0 auto;padding:24px 16px;">
403
+ <div style="background:#ffffff;border:1px solid #e2d8cf;border-radius:14px;overflow:hidden;">
404
+ <div style="background:#0d1117;padding:14px 22px;color:#c9d1d9;font-family:ui-monospace,Menlo,Consolas,monospace;font-size:13px;">&gt;_ kordexa — day ${day.day}</div>
405
+ <div style="padding:22px;">
406
+ <p style="margin:0 0 4px;color:${muted};font-size:13px;">Hi ${escapeHtml(config.learner.name)} — Day ${day.day} of your ${escapeHtml(config.learner.targetRole)} path.</p>
407
+ <h1 style="margin:6px 0 8px;font-size:22px;line-height:1.2;color:#0a0a0a;">${escapeHtml(day.title)}</h1>
408
+ <p style="margin:0 0 16px;color:#5e554d;font-size:15px;">${escapeHtml(day.goal)}</p>
409
+ ${topBlock}
410
+ <table style="border-collapse:collapse;margin:4px 0 4px;">${facts}</table>
411
+ ${moreBlock}
412
+ ${refsBlock}
413
+ ${progressBlock}
414
+ ${coursesBlock}
415
+ ${cardBlock}
416
+ ${questions}
417
+ <p style="margin:18px 0 0;font-size:14px;color:#5e554d;">Bridge: ${escapeHtml(day.nextDayBridge)}</p>
418
+ </div>
419
+ </div>
420
+ <p style="text-align:center;color:${muted};font-size:12px;margin:14px 0 0;">Use <b>/kordexa</b> in your agent to adjust the plan or review progress.</p>
421
+ </div>
422
+ </body></html>`;
423
+ }
@@ -0,0 +1,93 @@
1
+ import path from "node:path";
2
+ import { readJson, resolveDataDir, writeJson } from "./config.js";
3
+
4
+ export function appendProgress(config, entry) {
5
+ const dataDir = resolveDataDir(config);
6
+ const logPath = path.join(dataDir, "progress-log.json");
7
+ const existing = readJson(logPath, []);
8
+ const normalized = {
9
+ loggedAt: new Date().toISOString(),
10
+ day: Number.parseInt(entry.day, 10) || inferNextDay(existing),
11
+ completed: entry.completed || "No completion note provided.",
12
+ evidence: entry.evidence || "No evidence provided.",
13
+ minutes: Number.parseInt(entry.minutes, 10) || 0,
14
+ confidence: Number.parseInt(entry.confidence, 10) || 3,
15
+ blocker: entry.blocker || ""
16
+ };
17
+ existing.push(normalized);
18
+ writeJson(logPath, existing);
19
+ return normalized;
20
+ }
21
+
22
+ export function reviewProgress(config, plan) {
23
+ const entries = readJson(path.join(resolveDataDir(config), "progress-log.json"), []);
24
+ const completedDays = new Set(entries.map((entry) => entry.day));
25
+ const latest = entries.at(-1) || null;
26
+ const totalDays = plan.days.length || 30;
27
+ const nextDay = Math.min(totalDays, firstUnfinishedDay(completedDays));
28
+ const activeDay = plan.days.find((day) => day.day === nextDay) || plan.days.at(-1);
29
+ const blockers = entries.filter((entry) => entry.blocker).map((entry) => entry.blocker);
30
+ return {
31
+ generatedAt: new Date().toISOString(),
32
+ completedEntries: entries.length,
33
+ completedDays: completedDays.size,
34
+ latestEvidence: latest?.evidence || "",
35
+ activeDay: activeDay?.day || 1,
36
+ nextAction: activeDay ? activeDay.setupOrBuildTask : "Regenerate the plan and continue with one artifact.",
37
+ nextSkillRecommendation: completedDays.size >= totalDays ? plan.nextSkillRecommendation : null,
38
+ risk: blockers.length ? `Resolve blocker: ${blockers.at(-1)}` : "No active blocker logged.",
39
+ momentum: momentum(entries)
40
+ };
41
+ }
42
+
43
+ export function createWeeklySummary(config, plan, week = 1) {
44
+ const entries = readJson(path.join(resolveDataDir(config), "progress-log.json"), []);
45
+ const start = (week - 1) * 7 + 1;
46
+ const end = Math.min(plan.days.length || 30, start + 6);
47
+ const weekEntries = entries.filter((entry) => entry.day >= start && entry.day <= end);
48
+ const plannedDays = plan.days.filter((day) => day.day >= start && day.day <= end);
49
+ return {
50
+ generatedAt: new Date().toISOString(),
51
+ week,
52
+ range: `${start}-${end}`,
53
+ planned: plannedDays.map((day) => ({ day: day.day, title: day.title })),
54
+ completed: weekEntries.map((entry) => ({ day: entry.day, completed: entry.completed, evidence: entry.evidence })),
55
+ summary: weekEntries.length
56
+ ? `Completed ${weekEntries.length}/${plannedDays.length} logged days. Keep the next week focused on visible artifacts.`
57
+ : "No progress logged for this week. Restart with the first unfinished day and produce one proof artifact.",
58
+ nextWeekFocus: plan.days.find((day) => day.day === end + 1)?.title || plan.nextSkillRecommendation?.recommendedNextSkill || "Review and portfolio polish"
59
+ };
60
+ }
61
+
62
+ export function planStatus(config, plan) {
63
+ const review = reviewProgress(config, plan);
64
+ return {
65
+ learner: config.learner.name,
66
+ targetRole: config.learner.targetRole,
67
+ emailTime: `${config.schedule.dailyEmailTime} ${config.schedule.timezone}`,
68
+ daysPlanned: plan.days.length,
69
+ primarySkill: plan.primarySkill,
70
+ currentLearning: config.learner.currentLearning,
71
+ ...review
72
+ };
73
+ }
74
+
75
+ function inferNextDay(entries) {
76
+ return firstUnfinishedDay(new Set(entries.map((entry) => entry.day)));
77
+ }
78
+
79
+ function firstUnfinishedDay(completedDays) {
80
+ let day = 1;
81
+ while (completedDays.has(day)) day += 1;
82
+ return day;
83
+ }
84
+
85
+ function momentum(entries) {
86
+ const recent = entries.slice(-3);
87
+ if (!recent.length) return "not-started";
88
+ const avgConfidence = recent.reduce((sum, entry) => sum + entry.confidence, 0) / recent.length;
89
+ if (recent.some((entry) => entry.blocker)) return "blocked";
90
+ if (avgConfidence >= 4) return "strong";
91
+ if (avgConfidence >= 3) return "steady";
92
+ return "needs-support";
93
+ }