@stemtrooper/learningcode 0.4.2 → 0.4.4

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.
@@ -143,6 +171,10 @@ learningcode --mode json           # machine-readable output
 The TLC brand theme and banner ship with the package, so there is nothing to
 configure.
 
+LearningCode suppresses Pi's built-in startup header so the TLC banner appears
+without the Pi logo flashing first. Use `learningcode --verbose` to show Pi's
+startup details and loaded-resource list as well.
+
 ```
   ██╗     ███████╗ █████╗ ██████╗ ███╗   ██╗██╗███╗   ██╗ ██████╗  ██████╗ ██████╗ ██████╗ ███████╗
   ██║     ██╔════╝██╔══██╗██╔══██╗████╗  ██║██║████╗  ██║██╔════╝ ██╔════╝██╔═══██╗██╔══██╗██╔════╝
@@ -167,7 +199,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
@@ -267,4 +301,4 @@ is also MIT. See [LICENSE](LICENSE).
 
 Not affiliated with, endorsed by, or connected to Pi, OpenCode, Anomaly, or any of
 the model providers reachable through this client. "The Learning Curve", TLC and
-Spark are trademarks of The Learning Curve.
+Spark are trademarks of The Learning Curve.

package/bin/learningcode.mjs

@@ -17,6 +17,7 @@ import {
 } from "../lib/config.mjs";
 import { GO_PROVIDER, saveProviderKey } from "../lib/auth.mjs";
 import { ensureSparkProvider, modelsPath, retargetProvider } from "../lib/models.mjs";
+import { ensureQuietStartup } from "../lib/settings.mjs";
 import { ensureThemes, preferredTheme } from "../lib/themes.mjs";
 import { hasToken, looksLikeToken, resolveToken, writeCachedToken } from "../lib/token.mjs";
 
@@ -45,6 +46,7 @@ Everything else is passed straight through to Pi, so the usual flags work:
   learningcode -p "explain main.py"   one-shot, non-interactive
   learningcode --mode json            machine-readable event stream
   learningcode --list-models          every model Pi can reach
+  learningcode --verbose              show Pi's startup header and resource list
 
 Other providers
   Any --model other than tlc-spark/... skips the Spark token and the Spark
@@ -230,6 +232,7 @@ async function main() {
 	}
 	await ensureSparkProvider(dir);
 	await ensureThemes(dir);
+	await ensureQuietStartup(dir);
 
 	// `--login` forces a fresh paste even when a token is already cached.
 	const forced = [];
@@ -369,4 +372,4 @@ main().catch((error) => {
 	// Anything the user can act on gets one line. A stack trace is noise for a
 	// student who mistyped a token; keep it for genuine bugs.
 	fail(error instanceof UserError ? error.message : error?.stack || String(error));
-});
+});

package/lib/settings.mjs

@@ -0,0 +1,42 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { UserError } from "./config.mjs";
+
+/**
+ * Pi renders its built-in header before extension `session_start` handlers run.
+ * Its supported quietStartup setting prevents that header flashing before the
+ * LearningCode banner is installed. Only seed the setting when it is unset, so
+ * an explicit choice in the student's LearningCode settings remains theirs.
+ */
+export async function ensureQuietStartup(agentDir) {
+	const path = join(agentDir, "settings.json");
+	let settings;
+
+	try {
+		const contents = await readFile(path, "utf-8");
+		try {
+			settings = JSON.parse(contents.replace(/^\uFEFF/, ""));
+		} catch (error) {
+			throw new UserError(`Could not parse Pi settings at ${path}: ${error.message}`);
+		}
+	} catch (error) {
+		if (error instanceof UserError) throw error;
+		if (error?.code !== "ENOENT") {
+			throw new UserError(`Could not read Pi settings at ${path}: ${error.message}`);
+		}
+		settings = {};
+	}
+
+	if (!settings || typeof settings !== "object" || Array.isArray(settings)) {
+		throw new UserError(`Pi settings at ${path} must contain a JSON object.`);
+	}
+
+	if (typeof settings.quietStartup === "boolean" || settings.quietStartup === "header") {
+		return false;
+	}
+
+	settings.quietStartup = true;
+	await mkdir(agentDir, { recursive: true });
+	await writeFile(path, `${JSON.stringify(settings, null, 2)}\n`, "utf-8");
+	return true;
+}

package/package.json

@@ -1,11 +1,11 @@
 {
 	"name": "@stemtrooper/learningcode",
-	"version": "0.4.2",
+	"version": "0.4.4",
 	"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",
 	"bin": {
-		"learningcode": "./bin/learningcode.mjs"
+		"learningcode": "bin/learningcode.mjs"
 	},
 	"files": [
 		"assets",