learn-loops 0.4.2 → 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/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/package.json

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