learn-loops 0.4.1 → 0.4.3

package/README.md

@@ -7,7 +7,7 @@ npm i -g learn-loops
 loops
 ```
 
-Requires Node 20+ and either the `claude` or `codex` CLI installed and logged in. If `loops` isn't found after install, add npm's global bin folder to your `PATH` (`npm prefix -g`, then `<that>/bin`).
+Requires Node 20+ and either the `claude` or `codex` CLI installed and logged in (`npm i -g @anthropic-ai/claude-code` or `npm i -g @openai/codex`). If neither is found, `loops` says so and shows how to install one; if your saved tutor is missing but the other is present, it falls back to that one. If `loops` isn't found after install, add npm's global bin folder to your `PATH` (`npm prefix -g`, then `<that>/bin`).
 
 ## How it teaches
 
@@ -61,4 +61,10 @@ loops profile       edit your learner profile
 ```
 
 Your profile and streak live in `~/.config/loops/`.
-Env: `LOOPS_HOME`, `LOOPS_PROVIDER=claude|codex`, `LOOPS_IMAGES`, `NO_COLOR`.
+### Billing safety
+
+`loops` runs the CLIs under your subscription login and strips `ANTHROPIC_API_KEY`, `OPENAI_API_KEY` and similar variables from their environment, so you aren't billed per token by accident. A CLI signed in with an API key (or Bedrock/Vertex) is refused unless you set `LOOPS_ALLOW_API_BILLING=1`. If your tutor fails (usage limit, outage), `loops` automatically tries the other one.
+
+It **can't** see your account's "extra usage" (Claude) or credits (ChatGPT/Codex) settings, because neither CLI exposes them. If you don't want overage charges, turn those off in your account settings.
+
+Env: `LOOPS_HOME`, `LOOPS_PROVIDER=claude|codex`, `LOOPS_ALLOW_API_BILLING=1`, `LOOPS_IMAGES`, `NO_COLOR`.

package/dist/cli.js

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 import * as p from "@clack/prompts";
 import { listTopics, loadProfile, configDir } from "./store.js";
+import { PROVIDER_HELP, allStatuses, noProviderMessage, setNotifier } from "./llm.js";
 import { isDue } from "./srs.js";
 import { currentStreak, doneToday, loadStats, recordActivity, saveCheckin } from "./stats.js";
 import { banner, bar, must, t } from "./ui.js";
@@ -21,7 +22,7 @@ const HELP = `${t.bold("loops")} — learn anything with Claude Code or Codex as
   loops profile         edit how you like to learn
   loops --help          this help
 
-Env: LOOPS_HOME (config dir), LOOPS_PROVIDER=claude|codex, NO_COLOR`;
+Env: LOOPS_HOME (config dir), LOOPS_PROVIDER=claude|codex, LOOPS_ALLOW_API_BILLING=1 (allow pay-per-token logins), NO_COLOR`;
 const dueCount = (topics) => topics.reduce((n, tp) => n + tp.state.cards.filter((c) => isDue(c)).length, 0);
 function progressOf(tp) {
     const areas = tp.state.map?.areas ?? [];
@@ -231,11 +232,27 @@ async function main() {
         process.exit(1);
     }
     banner();
+    setNotifier((m) => p.log.warn(m));
+    const statuses = await allStatuses();
+    const usable = statuses.filter((x) => x.usable);
+    if (!usable.length) {
+        const installed = statuses.filter((x) => x.installed);
+        p.log.error(t.bad(installed.length ? `No usable tutor:\n${installed.map((x) => `  - ${x.reason}`).join("\n")}` : noProviderMessage()));
+        process.exit(1);
+    }
+    for (const x of statuses)
+        if (x.installed && !x.usable)
+            p.log.warn(x.reason);
     let profile = await loadProfile();
     if (!profile)
         profile = await onboard();
     if (process.env.LOOPS_PROVIDER === "claude" || process.env.LOOPS_PROVIDER === "codex")
         profile.provider = process.env.LOOPS_PROVIDER;
+    if (!usable.some((x) => x.name === profile.provider)) {
+        const fallback = usable[0].name;
+        p.log.warn(`Using ${PROVIDER_HELP[fallback].label} for this session instead of ${PROVIDER_HELP[profile.provider].label}.`);
+        profile.provider = fallback;
+    }
     if (!cmd)
         return menu(profile);
     if (["new", "continue", "review", "quiz", "mistakes", "streak", "topics", "profile", "map"].includes(cmd))

package/dist/diagram.js

@@ -1,5 +1,10 @@
 import { renderMermaidASCII } from "beautiful-mermaid";
 const color = !!process.stdout.isTTY && !process.env.NO_COLOR;
+// beautiful-mermaid hardcodes near-black label text, unreadable on dark terminals. Render labels in a
+// sentinel colour and swap it for the terminal's default foreground; lines use a mid-grey legible on both.
+const SENTINEL = "\x1b[38;5;201m";
+const GREY = "#8a8a8a";
+const theme = { fg: "#ff00ff", border: GREY, line: GREY, arrow: GREY, corner: GREY, junction: GREY };
 const widest = (s) => Math.max(...s.split("\n").map((l) => l.replace(/\x1b\[[0-9;]*m/g, "").length));
 /** mindmap isn't supported by beautiful-mermaid, so draw it as an indented tree. */
 function mindmapTree(src) {
@@ -34,7 +39,8 @@ export function renderDiagram(src, cols = process.stdout.columns ?? 100) {
         return mindmapTree(text);
     const attempt = (s) => {
         try {
-            return renderMermaidASCII(s, { colorMode: color ? "ansi256" : "none", paddingY: 2, paddingX: 4 });
+            const out = renderMermaidASCII(s, { colorMode: color ? "ansi256" : "none", paddingY: 2, paddingX: 4, theme });
+            return color ? out.split(SENTINEL).join("\x1b[39m") : out;
         }
         catch {
             return null;

package/dist/flows/onboard.js

@@ -1,25 +1,28 @@
 import * as p from "@clack/prompts";
-import { execFileSync } from "node:child_process";
 import { homedir } from "node:os";
 import { join } from "node:path";
+import { PROVIDER_HELP, hasBinary as has, installedProviders } from "../llm.js";
 import { saveProfile } from "../store.js";
 import { must, t } from "../ui.js";
-const has = (bin) => {
-    try {
-        execFileSync("which", [bin], { stdio: "ignore" });
-        return true;
-    }
-    catch {
-        return false;
-    }
-};
 export async function onboard(existing) {
     p.intro(t.bold(t.accent(existing ? " Edit your learner profile " : " Let's set up how YOU learn ")));
-    if (!existing)
+    if (!existing) {
         p.note("Answer a few questions so every lesson, quiz and diagram fits you.\nYou can change any of this later with `loops profile`.", "Welcome");
+        const found = ["claude", "codex"].map((n) => `${has(n) ? t.ok("✓") : t.dim("✗")} ${PROVIDER_HELP[n].label}`).join("   ");
+        p.note([
+            `loops has no AI of its own. It looks for Claude Code or Codex on your computer and uses it as your tutor:  ${found}`,
+            "",
+            "To avoid surprise charges:",
+            "  • It only uses your subscription login. API-key / pay-per-token logins are refused,",
+            "    and API-key environment variables are hidden from the tutor.",
+            "  • If one tutor fails (e.g. usage limit), it switches to the other.",
+            "  • It can't see your account's \"extra usage\" / credits setting. Turn that off in your",
+            "    Claude or ChatGPT account settings if you don't want to pay beyond your plan.",
+        ].join("\n"), "Your tutor & billing");
+    }
     const d = existing;
     const name = must(await p.text({ message: "What should I call you?", initialValue: d?.name, validate: (v) => (v?.trim() ? undefined : "Required") }));
-    const installed = ["claude", "codex"].filter(has);
+    const installed = installedProviders();
     const provider = must(await p.select({
         message: "Which AI tutor should power your lessons?",
         initialValue: d?.provider ?? installed[0] ?? "claude",

package/dist/llm.js

@@ -1,16 +1,59 @@
 import { spawn } from "node:child_process";
+import { accessSync, constants } from "node:fs";
 import { mkdtemp, readFile, rm } from "node:fs/promises";
 import { tmpdir } from "node:os";
-import { join } from "node:path";
+import { delimiter, join } from "node:path";
 export const TUTOR_SYSTEM = [
     "You are an exceptional tutor grounded in learning science: you activate prior knowledge,",
     "teach in small chunks, use concrete examples and diagrams, test retrieval rather than recognition,",
     "and correct misconceptions precisely. You never pad. You are accurate: if unsure, say so.",
     "You output exactly what is asked for, in the requested format, with no preamble.",
 ].join(" ");
-function run(cmd, args, input, timeoutMs) {
+export const PROVIDER_HELP = {
+    claude: { label: "Claude Code", install: "npm install -g @anthropic-ai/claude-code", login: "claude" },
+    codex: { label: "Codex CLI", install: "npm install -g @openai/codex", login: "codex login" },
+};
+/** True if `bin` is an executable file in some PATH directory (honours PATHEXT on Windows). */
+export function hasBinary(bin, env = process.env) {
+    const exts = process.platform === "win32" ? ["", ...(env.PATHEXT ?? ".EXE;.CMD;.BAT").split(";")] : [""];
+    for (const dir of (env.PATH ?? "").split(delimiter).filter(Boolean)) {
+        for (const ext of exts) {
+            try {
+                accessSync(join(dir, bin + ext), constants.X_OK);
+                return true;
+            }
+            catch { }
+        }
+    }
+    return false;
+}
+export const installedProviders = () => ["claude", "codex"].filter((n) => hasBinary(n));
+export function noProviderMessage() {
+    return [
+        "loops needs Claude Code or Codex installed to act as your tutor, and found neither on your PATH.",
+        "",
+        "Install one, sign in, then run loops again:",
+        ...Object.keys(PROVIDER_HELP).map((n) => `  ${PROVIDER_HELP[n].label}: ${PROVIDER_HELP[n].install}  (then: ${PROVIDER_HELP[n].login})`),
+        "",
+        "Already installed in a non-standard place? Add its folder to your PATH.",
+        "Sign in with a subscription account: loops refuses API-key / pay-per-token logins unless LOOPS_ALLOW_API_BILLING=1.",
+    ].join("\n");
+}
+/** Credentials that make a CLI bill per token instead of using the user's subscription login. */
+const METERED_ENV = ["ANTHROPIC_API_KEY", "ANTHROPIC_AUTH_TOKEN", "CLAUDE_CODE_USE_BEDROCK", "CLAUDE_CODE_USE_VERTEX", "CLAUDE_CODE_USE_FOUNDRY", "OPENAI_API_KEY", "CODEX_API_KEY"];
+export const allowMetered = (env = process.env) => env.LOOPS_ALLOW_API_BILLING === "1";
+/** The environment child CLIs run in: pay-per-token credentials are removed unless the user opted in. */
+export function childEnv(env = process.env) {
+    if (allowMetered(env))
+        return { ...env };
+    const out = { ...env };
+    for (const k of METERED_ENV)
+        delete out[k];
+    return out;
+}
+function run(cmd, args, input, timeoutMs, includeStderr = false) {
     return new Promise((resolve, reject) => {
-        const child = spawn(cmd, args, { cwd: tmpdir(), stdio: ["pipe", "pipe", "pipe"] });
+        const child = spawn(cmd, args, { cwd: tmpdir(), env: childEnv(), stdio: ["pipe", "pipe", "pipe"] });
         let out = "";
         let err = "";
         const timer = setTimeout(() => {
@@ -21,19 +64,20 @@ function run(cmd, args, input, timeoutMs) {
         child.stderr.on("data", (d) => (err += d));
         child.on("error", (e) => {
             clearTimeout(timer);
-            reject(new Error(`Could not run "${cmd}" — is it installed and on your PATH? (${e.message})`));
+            const help = PROVIDER_HELP[cmd];
+            reject(new Error(`Could not run "${cmd}" — is it installed and on your PATH?${help ? ` Install: ${help.install}` : ""} (${e.message})`));
         });
         child.on("close", (code) => {
             clearTimeout(timer);
             if (code === 0)
-                resolve(out);
+                resolve(includeStderr ? out + err : out);
             else
                 reject(new Error(`${cmd} exited with ${code}: ${err.trim().split("\n").slice(-4).join("\n")}`));
         });
         child.stdin.end(input);
     });
 }
-export async function complete(provider, prompt, timeoutMs = 240_000) {
+async function completeWith(provider, prompt, timeoutMs) {
     if (provider === "claude") {
         return run("claude", ["-p", "--tools", "", "--no-session-persistence", "--output-format", "text", "--system-prompt", TUTOR_SYSTEM], prompt, timeoutMs);
     }
@@ -47,6 +91,87 @@ export async function complete(provider, prompt, timeoutMs = 240_000) {
         await rm(dir, { recursive: true, force: true });
     }
 }
+/** Classify `claude auth status` JSON. Anything that isn't a first-party subscription login bills per token. */
+export function classifyClaude(raw) {
+    let j;
+    try {
+        j = JSON.parse(raw);
+    }
+    catch {
+        return "unknown";
+    }
+    if (j.loggedIn === false)
+        return "logged-out";
+    const method = String(j.authMethod ?? "");
+    if ((j.apiProvider && j.apiProvider !== "firstParty") || /api.?key|console/i.test(method))
+        return "metered";
+    return /claude\.ai|oauth|subscription/i.test(method) ? "subscription" : "unknown";
+}
+/** Classify `codex login status` output. */
+export function classifyCodex(text) {
+    if (/not logged in/i.test(text))
+        return "logged-out";
+    if (/api key/i.test(text))
+        return "metered";
+    return /chatgpt/i.test(text) ? "subscription" : "unknown";
+}
+async function probe(name) {
+    const label = PROVIDER_HELP[name].label;
+    const bad = (billing, reason) => ({ name, installed: hasBinary(name), billing, usable: false, reason });
+    if (!hasBinary(name))
+        return bad("unknown", `${label} isn't installed (${PROVIDER_HELP[name].install})`);
+    let billing;
+    try {
+        billing = name === "claude" ? classifyClaude(await run("claude", ["auth", "status"], "", 20_000)) : classifyCodex(await run("codex", ["login", "status"], "", 20_000, true));
+    }
+    catch {
+        billing = "logged-out";
+    }
+    if (billing === "logged-out")
+        return bad(billing, `${label} isn't signed in (run: ${PROVIDER_HELP[name].login})`);
+    if (billing === "metered" && !allowMetered()) {
+        return bad(billing, `${label} is signed in with an API key / pay-per-token account, which would charge you per request. Sign in with your subscription instead, or set LOOPS_ALLOW_API_BILLING=1 to allow it`);
+    }
+    return { name, installed: true, billing, usable: true, reason: "" };
+}
+const statusCache = new Map();
+export const providerStatus = (name) => {
+    if (!statusCache.has(name))
+        statusCache.set(name, probe(name));
+    return statusCache.get(name);
+};
+export const allStatuses = () => Promise.all(["claude", "codex"].map(providerStatus));
+let notify = (m) => console.error(m);
+export const setNotifier = (fn) => (notify = fn);
+let sticky;
+/**
+ * Run the prompt on the preferred tutor; if it can't be used or fails (usage limit, outage, signed out), fall back
+ * to the other one — but never to a CLI that would bill per token. Once a fallback works it's kept for the session.
+ */
+export async function complete(preferred, prompt, timeoutMs = 240_000) {
+    const first = sticky ?? preferred;
+    const order = [first, first === "claude" ? "codex" : "claude"];
+    const problems = [];
+    for (const name of order) {
+        const st = await providerStatus(name);
+        if (!st.usable) {
+            problems.push(st.reason);
+            continue;
+        }
+        if (name !== first)
+            notify(`${PROVIDER_HELP[order[0]].label} didn't work, so I'm trying ${PROVIDER_HELP[name].label} instead.`);
+        try {
+            const out = await completeWith(name, prompt, timeoutMs);
+            if (name !== preferred)
+                sticky = name;
+            return out;
+        }
+        catch (e) {
+            problems.push(`${PROVIDER_HELP[name].label}: ${e.message}`);
+        }
+    }
+    throw new Error(problems.join("\n"));
+}
 /**
  * Models often forget to double LaTeX backslashes inside JSON strings. `\theta` would silently parse as a
  * tab + "heta", `\nabla` as newline + "abla", `\frac` as form feed + "rac". Double the backslash of any

package/dist/prompts.js

@@ -20,6 +20,12 @@ const STEM_RULES = `Math and science content:
 - Physical or geometric setups (free-body diagrams, circuits, ray/optics diagrams, fields, waves, geometry) go in a fenced svg block holding one complete <svg viewBox='0 0 640 360'>. Use SINGLE quotes for every attribute, include a <title>, dark strokes on a transparent background, labelled parts via <text>, arrowheads via <marker>, and no scripts, images or external references. Keep it uncluttered and physically correct.
 - Graphs of functions (waveforms, potentials, distributions, trade-off curves) go in a fenced plot block holding JSON: {"title":"...","xlabel":"...","ylabel":"...","xmin":0,"xmax":10,"series":[{"label":"...","expr":"exp(-0.3*x)*cos(3*x)"}]}. The expr is a mathjs expression in x (use *, ^, sin, cos, exp, sqrt, pi), never LaTeX.
 - Use mermaid only for processes, hierarchies and state/flow structure. Add equations or figures only where they genuinely clarify; never decorate.`;
+const QUESTION_RULES = `Question precision (every question you write, including multiple-choice checks, flashcard fronts, predictions and follow-ups):
+- Each question must have exactly one defensible reading. Name the specific thing being asked about; never use bare "it", "this" or "the system" without a clear referent, and never lean on context the learner cannot see.
+- State any assumptions, conditions or scope the answer depends on inside the question itself (e.g. "assuming a single thread", "in the ideal case").
+- Ask for one thing at a time, and say what form the answer takes (which, why, how many, what happens next).
+- For multiple-choice: exactly one option is correct, the others are clearly wrong on a strict reading, and no option is a matter of opinion or "it depends". Avoid "all/none of the above" and vague words like "usually", "best" or "better" unless the question defines the criterion.
+- Open-ended questions may have many good answers, but the task must still be unambiguous about what to address.`;
 const diagramRule = (p) => p.diagrams === "lots" ? "Include 1-2 mermaid diagrams." : p.diagrams === "some" ? "Include one mermaid diagram if it genuinely helps." : "Only include a diagram if essential.";
 export function mapPrompt(p, topic, prior) {
     return `${learnerBlurb(p)}
@@ -47,6 +53,7 @@ Concepts to touch: ${area.concepts.map((c) => c.name).join(", ")}.
 Rules: max ~250 words in markdown. ${p.order === "examples-first" ? "Open with a concrete example, then name the idea." : p.order === "theory-first" ? "State the core principle first, then illustrate." : "Open with where it fits in the whole field, then the idea, then an example."}
 Use the learner's preferred styles (${p.styles.join(", ") || "any"}). ${diagramRule(p)} ${MERMAID_RULES}
 ${STEM_RULES}
+${QUESTION_RULES}
 Exactly 2 multiple-choice checks (4 options each, "answer" is the 0-based index, plausible distractors based on real misconceptions; vary the position of the right answer). 2-3 flashcards.
 Return ONLY JSON of this shape:
 ${lessonShape}`;
@@ -64,6 +71,7 @@ Already covered in this area: ${doneTitles.join("; ") || "nothing yet"}. Build o
 Rules: 400-650 words of markdown with ## subheadings. ${p.order === "examples-first" ? "Start from a worked example, then abstract." : p.order === "theory-first" ? "Start from first principles, then apply." : "Start from the big picture, zoom in, then work an example."}
 Include a worked example, one common misconception to avoid, and ${p.diagrams === "minimal" ? "at least one" : "1-2"} figure(s) (mermaid, svg or plot as fits the subject) showing the real mechanism/structure (not decoration). ${MERMAID_RULES}
 ${STEM_RULES}
+${QUESTION_RULES}
 Challenge level: ${p.challenge}. Exactly ${p.challenge === "tough" ? 4 : 3} multiple-choice checks that test understanding/application, not trivia (4 options, "answer" is 0-based). 3-4 flashcards phrased as recall questions.
 ${p.socratic ? "The learner prefers a SOCRATIC style: the markdown is the consolidation shown AFTER they work through your leading questions, so it should name and tie together the ideas those questions lead to." : ""}
 Also include the "prediction" (a situation where a wrong intuition is likely, so they learn from guessing wrong), the "deeper" trade-off question${p.socratic ? ", and exactly 3 \"socratic\" questions" : ""}.
@@ -102,13 +110,14 @@ export const PERSONAS = [
 export function personaPrompt(p, persona, title, keyPoints, answer) {
     return `Role-play ${persona.label} (${persona.voice}) who just heard the learner explain "${title}". Their explanation: """${answer}"""
 A complete explanation would cover: ${keyPoints.join("; ")}.
-React in character in 1-2 sentences (say honestly what confused you or what clicked), then ask ONE follow-up question aimed at the biggest gap or shaky claim in what they said. Stay in character; never reveal the answer.
+React in character in 1-2 sentences (say honestly what confused you or what clicked), then ask ONE follow-up question aimed at the biggest gap or shaky claim in what they said. Stay in character; never reveal the answer. The question must still be unambiguous: one specific thing asked, with any needed context stated.
 Return ONLY JSON: {"reaction":"...","question":"..."}`;
 }
 export function diagnoseQuestionsPrompt(p, title, missed, explanation) {
     return `${learnerBlurb(p)}
 The learner struggled with "${title}". They missed: ${missed.map((m) => `"${m}"`).join("; ") || "none (their own-words explanation was weak)"}. ${explanation ? `Feedback on their explanation: ${explanation}` : ""}
 Write exactly 2 short diagnostic questions (not quiz questions) that reveal WHAT mental model they hold, e.g. "what do you picture happens when ...?". Do not teach yet.
+${QUESTION_RULES}
 Return ONLY JSON: {"questions":["...","..."]}`;
 }
 export function diagnoseResultPrompt(p, title, qa, missed) {
@@ -117,6 +126,7 @@ Lesson "${title}". Missed questions: ${missed.join("; ") || "n/a"}.
 Diagnostic Q&A:
 ${qa.map((x) => `Q: ${x.q}\nA: ${x.a || "(no answer)"}`).join("\n")}
 Identify the single most likely misconception or gap, re-teach exactly that with a NEW angle (max 150 words, markdown, optional tiny mermaid), and write one fresh multiple-choice check that would fail if the misconception persists (4 options, "answer" 0-based index).
+${QUESTION_RULES}
 Return ONLY JSON: {"misconception":"one sentence","reteach":"markdown","retest":{"q":"...","options":["","","",""],"answer":0,"explain":"..."}}`;
 }
 export const LENSES = [
@@ -131,6 +141,7 @@ export function deeperPrompt(p, s, title, lens, earlier) {
     return `${learnerBlurb(p)} ${useBlurb(s)}
 Topic "${s.title}", lesson "${title}". Pose ONE open-ended "think deeper" question through the lens "${lens.label}": ${lens.ask}
 Make it concrete (a specific situation, not abstract). Do not repeat earlier questions: ${earlier.join(" | ") || "none"}.
+${QUESTION_RULES}
 Return ONLY JSON: {"question":"...","considerations":["4-5 things a thoughtful answer would raise"]}`;
 }
 export function critiquePrompt(p, title, question, considerations, answer) {
@@ -145,5 +156,6 @@ export function challengePrompt(p, s, area, covered) {
     return `${learnerBlurb(p)} ${useBlurb(s)}
 The learner just finished a deep dive into "${area.title}" (topic "${s.title}"), covering: ${covered.join("; ")}.
 Write ONE realistic application challenge: a specific scenario with constraints and a decision to make, where there is no single right answer and the learner must weigh trade-offs and anticipate what could go wrong. Make it ${p.challenge === "tough" ? "hard and ambiguous" : p.challenge === "gentle" ? "approachable" : "moderately demanding"}.
+${QUESTION_RULES}
 Return ONLY JSON: {"scenario":"3-5 sentences","task":"what they must decide or design, and justify","considerations":["5-6 things a strong answer weighs"]}`;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "learn-loops",
-  "version": "0.4.1",
+  "version": "0.4.3",
   "description": "A learning CLI that uses Claude Code / Codex as your tutor",
   "type": "module",
   "bin": {