learnforge 0.0.0-stage → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,23 @@
+# Changelog
+
+## 0.2.0 (2026-11-10)
+
+Learning features on top of 0.1:
+
+- Review cards with spaced repetition (FSRS); quiz misses become cards on their own.
+- Weak spots: wrong answers saved as the belief behind them; "Quiz my weak spots" aims new questions at them.
+- My take first / Predict first on lenses, with a "where you differ" section.
+- New lens kinds: Trace a run (step-through with variables) and History (from git log).
+- Teach-back, Socratic tutor with a hint ladder, walkthrough with per-block checks, bug hunt.
+- Map (import graph for TS/JS with tsconfig aliases, and Python), learning paths, glossary, margin notes.
+- Today page, fading level and whole-repo heatmap in Progress, command palette (Ctrl/Cmd+K), `?` shortcuts.
+- Lens freshness banner with refresh; markdown export of lenses and quizzes; JSON export of a project.
+- Model replies checked against schemas with one retry; lens, walkthrough and path replies cached.
+- Storage stays bounded: archive expiry, cache size cap, quiz attempt cap, capped histories, crash-file cleanup,
+  removed projects archived then expired; Settings > Storage with usage and "Clean up now".
+- Jobs persist across restarts (capped), with a history in Settings.
+- `--demo` flag: a sample repo with canned answers and temp data.
+
+## 0.1.0
+
+Lenses, quizzes, practice, changes and progress over any folder. Claude Code, Codex and Copilot CLIs, or an API key.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 learnforge contributors
+
+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

@@ -1,3 +1,143 @@
-# Temporary Holding Version
+# learnforge
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Understand any codebase, and prove to yourself that you do.
+
+AI makes code faster to write and easier to not understand. learnforge turns the model around: instead of
+writing code for you, it helps you build the model of the code in your own head.
+
+```bash
+npx learnforge ./my-repo
+npx learnforge --demo        # a sample repo and canned answers: see every page in a minute, no model needed
+```
+
+| | |
+|---|---|
+| ![Open a folder](assets/screenshots/projects.png) | ![A lens over real code](assets/screenshots/lens.png) |
+| ![The import graph](assets/screenshots/map.png) | ![Progress per file](assets/screenshots/progress.png) |
+
+## What it does
+
+It is built on what makes learning stick: recall beats re-reading, spacing beats cramming, and
+producing an answer before you see one beats reading the answer.
+
+**Read, with a question**
+
+| | |
+|---|---|
+| **Lenses** | See code through one question: *Explain*, *Data flow*, *State over time*, *Failure modes*, *Contracts*, *Concepts*, *The change*, *Trace a run* (a debugger without running: line by line with the variables), *History* (why it is like this, from git), or your own. Tick **My take first** to write your own guess before the lens; it opens with where you differ. On a diff, that becomes **Predict first**. A lens shows a banner when its code changes, with one-click refresh. |
+| **Walkthrough** | The file in reading order (not file order), one block at a time, with a check question on each block before the next. |
+| **Tutor** | A Socratic chat over the files. It answers with a question or a hint first and gives a bit more each turn; ask it to just tell you any time. Opens from any missed quiz question too. |
+| **Map** | The import graph (TS/JS with tsconfig aliases, Python), sized by how many files import each one: where to start. |
+| **Paths** | An ordered tour of the repo, 6-12 stops, each with the activity that fits. Stops tick off as you do them. |
+
+**Prove it**
+
+| | |
+|---|---|
+| **Quizzes** | Free-text questions about behaviour and reasons, not names. Mark each answer *sure* or *guess*. Graded with feedback that names the line and a good answer to compare with. |
+| **Teach-back** | Explain the code in your own words. Graded 1-5: what you got right, what you missed, what is wrong. |
+| **Practice** | The key logic is cut out of a copy of your file (4 levels). Write it back, with hints, then "check my work". |
+| **Bug hunt** | Realistic bugs are planted in a copy of the file. Click the lines you suspect and say why; see found, missed and false alarms. |
+| **Changes** | Two git refs, or HEAD vs your working tree. Read the diff, then predict, lens or quiz the change itself. |
+
+**Keep it**
+
+| | |
+|---|---|
+| **Review cards** | Spaced repetition (FSRS). Quiz misses become cards on their own; lens concepts and code lines can become cards in one click. |
+| **Weak spots** | Wrong answers are saved as the belief behind them ("you think X, but Y"). *Quiz my weak spots* asks new questions aimed at exactly those; a right answer clears one. |
+| **Today** | Each project opens on what to do now: due cards, weak spots, files that need a refresh, the next stop on your path, and one suggested 10-minute activity. |
+| **Progress** | Per file: *seen*, *understood* (a check passed on the code as it is now), *fading* (no recall for a few weeks), *stale* (the code changed since). Table, or a heatmap of the whole repo. |
+| **Library** | Everything made, searchable, plus a glossary built from every lens and your margin notes. Export a lens or quiz as markdown, or a whole project as JSON. |
+
+`Ctrl/Cmd+K` jumps to any page, file or project, or starts an activity. `?` lists all shortcuts.
+
+Context is what you pick: tick files in the tree, or add extra folders (docs, notes, design files) to a
+project as context. The model reads only what you give it.
+
+## Model access
+
+learnforge makes one model call per lens, quiz, grade, practice, tutor turn and so on (about 15 s to 2 min).
+Replies are checked against a schema (one retry with the problems listed), and lens, walkthrough and path
+replies are cached: the same lens on an unchanged file is free the second time.
+It drives a coding CLI you already use, with that CLI's own login, so **learnforge never asks for or
+stores a key**. Pick one in Settings; *Auto* takes the first one it finds, in this order:
+
+| Provider | How learnforge runs it | Login |
+|---|---|---|
+| **Claude Code** (default) | `claude -p`, read-only tools (`Read`, `Grep`, `Glob`) | your Claude Code login |
+| **OpenAI Codex** | `codex exec -`, `--sandbox read-only` | `codex login` |
+| **GitHub Copilot** | `copilot -p -s`, only the `read` tool (shell and write denied) | your Copilot login, or `COPILOT_GITHUB_TOKEN` / `GH_TOKEN` |
+| **Anthropic API** | Messages API; the picked files go in the prompt | `ANTHROPIC_API_KEY` in the environment |
+
+Each CLI runs with the project folder as its working directory. Model per provider is optional
+(empty = the CLI's default). `LEARNFORGE_AGENT=fake` gives canned answers, to try the UI without a model.
+
+## Your files are safe
+
+- learnforge never writes to your folders. Practice works on a copy.
+- Everything it makes lives in `~/.learnforge` (change with `LEARNFORGE_HOME`), as plain JSON files, one
+  per item. Files, not SQLite: the data is small, you can read and back it up, and there is no native
+  module to build.
+
+```
+~/.learnforge/
+  settings.json  projects.json  jobs.json  prune.json
+  projects/<id>/<lenses|quizzes|practice|cards|misconceptions|teachbacks|threads|walks|hunts|paths|notes>/<id>.json
+  projects/<id>/archive/...        "Archive" moves items here
+  archive/projects/<id>/           a project you removed from the list
+  cache/<hash>.json                saved model replies
+```
+
+**It does not keep growing.** Every part that could grow has a limit (Settings > Storage shows the
+sizes and has *Clean up now*):
+
+| What | Limit (setting) |
+|---|---|
+| Archived items and removed projects | deleted after 30 days (`storage.archiveDays`; reopen a removed folder in time and its history comes back) |
+| Model reply cache | 50 MB, least recently used goes first (`storage.cacheMB`) |
+| Graded attempts per quiz | newest 20, the best one always kept (`storage.maxAttempts`) |
+| Card review history, tutor messages, job history | 50 per card, 200 per chat, 100 jobs |
+| Temp files left by a crash | removed after an hour |
+
+Cleanup runs at start-up and every 6 hours, and only ever inside the learnforge folder.
+
+- The server binds to `127.0.0.1` only. There is no login: it is a local, one-person tool.
+
+## CLI
+
+```
+learnforge [folder] [--port 4711] [--host 127.0.0.1] [--no-open] [--demo]
+```
+
+## Develop
+
+```bash
+npm install
+npm run dev          # API on :4711 (tsx watch) + Vite on :5173 with hot reload
+npm test             # core and API tests (vitest, fake model, temp git repos)
+npm run typecheck
+npm run build        # dist/web (Vite) + dist/cli.js (tsup)
+
+# Browser smoke test over every page (needs a Chromium; set CHROME or have one in ~/.cache/ms-playwright)
+LEARNFORGE_HOME=$(mktemp -d) LEARNFORGE_AGENT=fake node dist/cli.js . --port 4799 --no-open &
+node test/ui-smoke.mjs [--dark] [--shots DIR]
+```
+
+Layout:
+
+```
+src/cli.ts              CLI: serves the API and the built web app
+src/server/app.ts       Hono routes under /api
+src/core/               no HTTP here: workspace (files, git), graph (imports), store, storage (limits, cache),
+                        prompts, schemas, services (model work), insights (cards, progress, today), jobs, agent adapters
+demo/sample/            the small repo --demo opens
+web/src/                React + Vite + Tailwind: pages/, components/, lib/
+```
+
+Stack: TypeScript everywhere. Hono on Node 20+, zod, ts-fsrs. React 18, React Router, TanStack Query,
+Tailwind, Shiki (code), CodeMirror (practice editor), Mermaid (diagrams), d3-force (map).
+
+## License
+
+MIT

package/demo/sample/README.md

@@ -0,0 +1,8 @@
+# tiny-queue
+
+A small in-memory job queue with retries, used as the learnforge demo project.
+
+- `src/queue.ts`: the queue (add, take, ack, fail with retry and backoff)
+- `src/backoff.ts`: how long to wait before a retry
+- `src/worker.ts`: runs jobs from the queue with a concurrency limit
+- `src/index.ts`: wires it together

package/demo/sample/src/backoff.ts

@@ -0,0 +1,6 @@
+/** Wait before retry `attempt` (1-based): doubles each time, capped, with jitter so retries spread out. */
+export function backoffMs(attempt: number, baseMs = 200, capMs = 10_000, random = Math.random): number {
+  const exp = Math.min(capMs, baseMs * 2 ** (attempt - 1));
+  // Full jitter: anywhere between half and all of the delay.
+  return Math.round(exp / 2 + random() * (exp / 2));
+}

package/demo/sample/src/index.ts

@@ -0,0 +1,12 @@
+import { Queue } from "./queue.js";
+import { drain } from "./worker.js";
+
+const queue = new Queue<string>(3);
+for (const url of ["a", "b", "flaky", "c"]) queue.add(url);
+
+let flakyTries = 0;
+await drain(queue, async (url) => {
+  if (url === "flaky" && ++flakyTries < 3) throw new Error("try again");
+  console.log("done", url);
+});
+console.log("dead letters:", queue.dead.length);

package/demo/sample/src/queue.ts

@@ -0,0 +1,58 @@
+import { backoffMs } from "./backoff.js";
+
+export interface Job<T> {
+  id: number;
+  payload: T;
+  attempts: number;
+  /** Not before this time (ms since epoch). */
+  runAt: number;
+}
+
+/**
+ * In-memory queue. take() hands out the oldest ready job and keeps it "in flight" until
+ * ack() or fail(). fail() puts it back with a backoff, or drops it after maxAttempts.
+ */
+export class Queue<T> {
+  private ready: Job<T>[] = [];
+  private inFlight = new Map<number, Job<T>>();
+  private nextId = 1;
+  readonly dead: Job<T>[] = [];
+
+  constructor(private readonly maxAttempts = 3, private readonly now = () => Date.now()) {}
+
+  add(payload: T): number {
+    const job = { id: this.nextId++, payload, attempts: 0, runAt: this.now() };
+    this.ready.push(job);
+    return job.id;
+  }
+
+  take(): Job<T> | undefined {
+    const t = this.now();
+    const i = this.ready.findIndex((j) => j.runAt <= t);
+    if (i < 0) return undefined;
+    const [job] = this.ready.splice(i, 1);
+    job.attempts++;
+    this.inFlight.set(job.id, job);
+    return job;
+  }
+
+  ack(id: number): void {
+    this.inFlight.delete(id);
+  }
+
+  fail(id: number): void {
+    const job = this.inFlight.get(id);
+    if (!job) return;
+    this.inFlight.delete(id);
+    if (job.attempts >= this.maxAttempts) {
+      this.dead.push(job);
+      return;
+    }
+    job.runAt = this.now() + backoffMs(job.attempts);
+    this.ready.push(job);
+  }
+
+  get size(): number {
+    return this.ready.length + this.inFlight.size;
+  }
+}

package/demo/sample/src/worker.ts

@@ -0,0 +1,20 @@
+import type { Queue } from "./queue.js";
+
+/** Pull jobs and run them, at most `concurrency` at a time, until the queue is empty. */
+export async function drain<T>(queue: Queue<T>, handle: (payload: T) => Promise<void>, concurrency = 2): Promise<void> {
+  const running = new Set<Promise<void>>();
+  while (queue.size > 0) {
+    const job = running.size < concurrency ? queue.take() : undefined;
+    if (!job) {
+      // Nothing ready (or no free slot): wait for a running job, or a short tick for backoff.
+      await (running.size ? Promise.race(running) : new Promise((r) => setTimeout(r, 50)));
+      continue;
+    }
+    const p = handle(job.payload)
+      .then(() => queue.ack(job.id))
+      .catch(() => queue.fail(job.id))
+      .finally(() => running.delete(p));
+    running.add(p);
+  }
+  await Promise.all(running);
+}