@stemtrooper/learningcode 0.4.1 → 0.4.3

package/README.md

@@ -63,6 +63,34 @@ npm install -g @stemtrooper/learningcode
 learningcode --version
 ```
 
+`node --version` must report **22.19.0 or newer**. If it is older — and
+Ubuntu's own `apt` package is usually Node 18 — install a current one first:
+
+```bash
+curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash
+source ~/.bashrc
+nvm install 24
+nvm alias default 24
+```
+
+**If the install fails with a permissions error**, npm's global directory belongs
+to root. Move it somewhere you own, then install again:
+
+```bash
+mkdir -p ~/.npm-global
+npm config set prefix ~/.npm-global
+export PATH="$HOME/.npm-global/bin:$PATH"
+echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.bashrc
+
+npm install -g @stemtrooper/learningcode
+```
+
+The last line is what makes `learningcode` visible in future terminals; without
+it you will think the install failed.
+
+**Do not use `sudo npm install -g`.** It appears to work, then writes
+root-owned files that break your next upgrade with a confusing error.
+
 ### Termux (Android)
 
 No root and no `proot-distro` needed.
@@ -167,7 +195,9 @@ A footer shows your remaining quota whenever you are connected to Spark:
 ## Troubleshooting
 
 **`Node 22.19.0 or newer is required`**
-Upgrade Node, then reinstall: `npm i -g @stemtrooper/learningcode`.
+Upgrade Node, then reinstall: `npm i -g @stemtrooper/learningcode`. On Linux this
+is usually the first thing to check, because Ubuntu ships Node 18 — see
+[macOS / Linux](#macos--linux).
 
 **`No Spark API token configured`**
 You do not have a token yet, or it is not cached. Run `learningcode --login` to

package/bin/learningcode.mjs

@@ -288,6 +288,9 @@ async function main() {
 					"it may not be a Spark token.\n",
 			);
 		}
+		// Keep Pi's stored credential and the environment in step. See the note
+		// beside saveProviderKey below.
+		await saveProviderKey(dir, PROVIDER_ID, token);
 		if (resolved.shouldCache) await writeCachedToken(dir, token);
 	} else if (explicitToken) {
 		process.stderr.write(
@@ -320,11 +323,12 @@ async function main() {
 
 	const childEnv = { ...process.env };
 
-	// Pi reads provider credentials from auth.json before the environment, and
-	// auth.json is keyed per provider. Storing the key under opencode-go alone
-	// authenticates Go while leaving Zen credential-less, so its 111 pay-per-use
-	// models never register. Zen and Go otherwise share OPENCODE_API_KEY, so
-	// leaving the env var in place would expose both.
+	// Pi prefers a stored credential in auth.json over the `$SPARK_API_KEY` the
+	// provider config names, so leaving the token only in the environment lets the
+	// two drift apart: Pi authenticates with whatever auth.json holds while the
+	// /quota and /seats commands read the environment, and a stale entry then shows
+	// up as a 401 on those two but not on completions. Writing the token to
+	// auth.json as well makes every path use the same value whichever Pi prefers.
 	const goKey = process.env.LEARNINGCODE_GO_KEY || process.env.OPENCODE_API_KEY;
 	if (goKey && process.env.LEARNINGCODE_ALLOW_ZEN !== "1") {
 		await saveProviderKey(dir, GO_PROVIDER, goKey);

package/lib/token.mjs

@@ -101,7 +101,10 @@ export async function resolveToken(agentDir, explicit) {
 	if (fromEnv) return { token: fromEnv.trim(), source: "environment" };
 
 	const cached = await readCachedToken(agentDir);
-	if (cached) return { token: cached, source: "cached" };
+	// A cached value that is not a Spark token is worse than no cache: it would be
+	// sent to Spark, rejected, and reported as a 401 that looks like a revoked
+	// token. Fall through and ask instead.
+	if (cached && isSparkToken(cached)) return { token: cached, source: "cached" };
 
 	const entered = await promptSecret(
 		"Paste your Spark API token (Bench > Issue / rotate token): ",
@@ -111,9 +114,23 @@ export async function resolveToken(agentDir, explicit) {
 }
 
 export function looksLikeToken(token) {
-	return token.startsWith(TOKEN_PREFIX);
+	return isSparkToken(token);
 }
 
+/**
+ * Whether a value could be a Spark token at all. Spark mints them as
+ * `spark_live_<secret>`, so anything else in the cache slot came from somewhere
+ * else and must not be sent to Spark.
+ *
+ * The length of the secret is deliberately not checked: Spark chooses it, and
+ * tightening this to today's value would start rejecting valid tokens the day
+ * that changes. Requiring something after the prefix is the safe minimum.
+ */
+export const isSparkToken = (token) =>
+	typeof token === "string" &&
+	token.startsWith(TOKEN_PREFIX) &&
+	token.length > TOKEN_PREFIX.length;
+
 /** True when a token can be found without asking the student anything. */
 export async function hasToken(agentDir, explicit) {
 	if (explicit) return true;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@stemtrooper/learningcode",
-	"version": "0.4.1",
+	"version": "0.4.3",
 	"description": "TLC Spark coding agent for students: Pi wired to the Spark OpenAI-compatible endpoint with per-student tokens, quota and seat-queue awareness.",
 	"type": "module",
 	"license": "MIT",