neuro-canvas-lms 2.13.0 → 2.14.0

package/AGENTS.md

@@ -15,6 +15,12 @@ code (the school comes from Worker vars). It is a community project provided as
   GitHub Actions (`.github/workflows/test.yml`) runs the tests, `npm run format:check` and the
   dry-run build on every push and pull request.
 - Never rename or remove MCP tools (clients store per-tool approvals by name); only add.
+- Versions: every release makes every user's AI announce an update, so release only what users
+  gain from. Patch: fixes. Minor: new tools or parameters, a tool answering differently, install
+  changes. Major: only if users must act (reconnect, change Cloudflare settings, newer Node).
+  Docs, CI and test changes are not released on their own. Bump the version only in the release
+  commit (version.mjs, `npm version x.y.z --no-git-tag-version`, server.json), after testing on a
+  real connector and in a new chat.
 
 Code map:
 - `worker.mjs`: OAuth + MCP entry, /healthz. `config.mjs`: school settings from Worker vars.
@@ -26,7 +32,9 @@ Code map:
 - Files: `file-content.mjs` (text extraction), `file-types.mjs` (file type detection shared by all
   readers), `zip-content.mjs` (server-side ZIP unpacking), `find-files.mjs` (finds files a course
   links to when its Files list is hidden), `external-links.mjs` (Google/Dropbox/GitHub share links →
-  the file itself), `module-file.mjs` + `file-resource.mjs` (original files as MCP resources),
+  the file itself), `link-content.mjs` (text of a file linked in the syllabus, a page, an
+  assignment or an announcement; only links that content really contains), `module-file.mjs` +
+  `file-resource.mjs` (original files as MCP resources),
   `download-link.mjs` (one-time, minutes-long Canvas storage link so coding agents can curl an original
   file to disk).
 - `owner.mjs`: owner binding, allowed OAuth clients. `i18n.mjs` + `pages.mjs`: web pages.
@@ -39,3 +47,8 @@ Code map:
   settings (without a terminal it does not ask). `installer/verify.mjs`: the post-deploy online
   check, also run alone by `npx -y neuro-canvas-lms check`.
 - `version.mjs`: shown on the home page and /healthz, compared with npm by update-check.mjs.
+- `server.json`: the entry in the official MCP Registry (one remote whose host each user fills in).
+  Same version as `version.mjs` and package.json (`version.test.mjs`).
+- Releases: bump those three, push to main, then push a tag `vX.Y.Z`;
+  `.github/workflows/publish.yml` tests, publishes to npm and updates the MCP Registry, with
+  no stored secrets (OIDC trusted publishing).

package/README.md

@@ -2,6 +2,8 @@
 
 **English** · [简体中文](docs/README.zh-CN.md) · [Español](docs/README.es.md) · [日本語](docs/README.ja.md) · [हिन्दी](docs/README.hi.md)
 
+[![npm](https://img.shields.io/npm/v/neuro-canvas-lms?label=npm&color=c9a462)](https://www.npmjs.com/package/neuro-canvas-lms) [![tests](https://github.com/BloodyReginaa/Neuro-CanvasLMS/actions/workflows/test.yml/badge.svg)](https://github.com/BloodyReginaa/Neuro-CanvasLMS/actions/workflows/test.yml) [![license: MIT](https://img.shields.io/badge/license-MIT-blue)](https://github.com/BloodyReginaa/Neuro-CanvasLMS/blob/main/LICENSE)
+
 ![Neuro-CanvasLMS answering "What's due this week?" in Claude](https://raw.githubusercontent.com/BloodyReginaa/Neuro-CanvasLMS/main/docs/images/banner.png)
 
 **Wire your Canvas LMS straight into Claude and ChatGPT.** Your courses, deadlines, grades and lecture files become part of what your AI knows, in any chat and on any device. It is a read-only remote MCP server that one command deploys to your own free Cloudflare account. Works at any Canvas school that lets students create access tokens ([30-second check](#can-you-use-it)).
@@ -21,9 +23,9 @@ Local Canvas tools only work while your own computer runs them. Hosted services
 
 ## What you get
 
-- **64 read-only tools:** courses, modules, pages, files, assignments, submissions, grades and feedback, rubrics, announcements, discussions, inbox, calendar, to-dos, groups, quiz history and profile settings.
+- **65 read-only tools:** courses, modules, pages, files, assignments, submissions, grades and feedback, rubrics, announcements, discussions, inbox, calendar, to-dos, groups, quiz history and profile settings.
 - **Real file reading:** text from PDF, Word, PowerPoint and Excel, about 90 kinds of code and text files, and Jupyter notebooks (cells and outputs); ZIP archives unpacked on the server (listing plus every code/text file); scanned or handwritten PDFs are recognised and their original pages handed to the AI to look at.
-- **Linked files too:** course files that a module links on Google Docs/Slides/Sheets, Google Drive, Dropbox (files and folders) and GitHub (files and repositories) are read as text, as long as they are shared publicly ("Anyone with the link").
+- **Linked files too:** course files that a module, the syllabus, a page, an assignment or an announcement links on Google Docs/Slides/Sheets, Google Drive, Dropbox (files and folders) and GitHub (files and repositories) are read as text, as long as they are shared publicly ("Anyone with the link").
 - **Finds files the course hides:** many courses hide their Files list from students. The connector searches the front page, syllabus, modules, assignments, announcements and the pages they link to, so the AI can still find "the Lecture 12 slides" by name.
 - **Starter code onto your computer:** in Claude Code, Codex and other coding agents, ask "set up PA2 from Canvas". The agent gets a one-time download link that expires in minutes, saves the assignment's starter files in your folder and unpacks them.
 - **Read-only by design:** only fixed `GET` requests. It never submits work, sends messages, starts quizzes or changes anything in Canvas.

package/canvas-transport.mjs

@@ -135,9 +135,12 @@ export async function parseCanvasResponse(bytes) {
 }
 // A JSON answer is Canvas itself speaking; HTML (or a 406) means something in front of Canvas
 // rejected the request, which is when the socket path is worth trying.
+// A rate limit (429, or Canvas's own 403 carrying X-Rate-Limit-Remaining) is Canvas speaking too:
+// asking again at once over the socket would only add to the count.
 export function shouldFallBack(response) {
   if (response.status === 406) return true;
-  if (response.status < 400) return false;
+  if (response.status < 400 || response.status === 429) return false;
+  if (response.headers.has('x-rate-limit-remaining')) return false;
   return !(response.headers.get('content-type') ?? '').toLowerCase().includes('json');
 }
 

package/canvas.mjs

@@ -219,7 +219,19 @@ export async function callCanvas(name, args, token, fetcher = fetch, opts = {})
   }
   if (name === 'canvas_file_content') return readFileContent(r.data, args, fetcher);
   if (args.raw) return r;
-  const out = slim(name, r, { timeZone: opts.timeZone });
+  // Compact grade rows name each assignment's group and come with the weights and drop rules:
+  // one more request, and the rows still come back without them if it fails.
+  let groups;
+  if (name === 'canvas_course_submissions' && !args.full)
+    groups = await canvasGet(
+      endpoint('canvas_assignment_groups', { course_id: args.course_id }),
+      token,
+      fetcher,
+    ).then(
+      g => (Array.isArray(g.data) ? g.data : undefined),
+      () => undefined,
+    );
+  const out = slim(name, r, { timeZone: opts.timeZone, full: args.full === true, groups });
   if (name === 'canvas_calendar_events' && Array.isArray(out.data) && out.data.length === 0) {
     const where = args.context_codes ? 'these calendars' : 'your personal calendar';
     const what =
@@ -246,6 +258,36 @@ export function unreachable(e) {
 
 // One GET to the Canvas API: fixed headers, no redirects, Canvas errors turned into safe messages
 // (never the upstream body). `e.status` is set when Canvas refused this item (not a token problem).
+// Canvas throttles API use per token: it answers "403 Forbidden (Rate Limit Exceeded)" (its own
+// answers carry X-Rate-Limit-Remaining), and a proxy in front may answer 429. That is not "this
+// course hides its files" (no find_files hint, no retry over the socket): the AI is told to wait.
+// The error has no `status`, so nothing treats it as a hidden resource.
+async function rateLimit(r) {
+  if (r.status !== 429 && r.status !== 403) return null;
+  let limited = r.status === 429;
+  if (!limited) {
+    const remaining = r.headers.get('x-rate-limit-remaining');
+    if (remaining !== null && Number(remaining) <= 0) limited = true;
+    else if (!(r.headers.get('content-type') ?? '').includes('json'))
+      try {
+        limited = /rate limit/i.test((await r.clone().text()).slice(0, 2000));
+      } catch {}
+  }
+  if (!limited) return null;
+  await r.body?.cancel().catch(() => {});
+  const seconds = Number(r.headers.get('retry-after'));
+  const wait =
+    Number.isFinite(seconds) && seconds > 0
+      ? `${Math.min(Math.ceil(seconds), 3600)} seconds`
+      : 'about a minute';
+  return Object.assign(
+    new Error(
+      `Canvas rate limit reached (HTTP ${r.status}): too many Canvas requests in a short time. Wait ${wait} before the next Canvas call and do not retry in a loop. The token and the connection are fine; this is not a permission problem.`,
+    ),
+    { rateLimited: true },
+  );
+}
+
 export async function canvasGet(u, token, fetcher = fetch) {
   let r;
   try {
@@ -262,6 +304,8 @@ export async function canvasGet(u, token, fetcher = fetch) {
   } catch (e) {
     throw unreachable(e);
   }
+  const limited = await rateLimit(r);
+  if (limited) throw limited;
   if (
     r.status === 406 ||
     (r.status >= 500 && !(r.headers.get('content-type') ?? '').includes('json'))

package/download-link.mjs

@@ -160,12 +160,20 @@ export function newDownloadId() {
     .replace(/=+$/, '');
 }
 
+// Cloudflare KV failed (briefly unavailable, or the free plan's 1000 writes a day are used up).
+export const STORAGE_DOWN =
+  "Connector storage (Cloudflare KV) is unavailable right now, so no download link could be made. It is often the free plan's daily KV limit, which resets at 00:00 UTC. Meanwhile use canvas_file_original or canvas_file_content; the Canvas connection itself is fine.";
+
 // Store the Canvas address for 5 minutes and return the Worker link that leads to it.
 export async function issueDownload(kv, origin, target, now = Date.now) {
   const id = newDownloadId();
-  await kv.put('dl:' + id, JSON.stringify({ target, exp: now() + DOWNLOAD_TTL * 1000 }), {
-    expirationTtl: DOWNLOAD_TTL,
-  });
+  try {
+    await kv.put('dl:' + id, JSON.stringify({ target, exp: now() + DOWNLOAD_TTL * 1000 }), {
+      expirationTtl: DOWNLOAD_TTL,
+    });
+  } catch {
+    throw new Error(STORAGE_DOWN);
+  }
   return `${origin}/dl/${id}`;
 }
 
@@ -188,11 +196,22 @@ export async function redeemDownload(request, kv, id, now = Date.now) {
       { status: 403, headers: plain },
     );
   const key = 'dl:' + id;
+  let stored;
+  try {
+    stored = await kv.get(key);
+  } catch {
+    // not "expired": the link may be fine, the storage is not
+    return new Response(
+      "The connector's storage (Cloudflare KV) is unavailable right now. Try again in a minute; if it keeps failing, the free plan's daily limit may be used up (it resets at 00:00 UTC).\n",
+      { status: 503, headers: plain },
+    );
+  }
   let entry = null;
   try {
-    entry = JSON.parse((await kv.get(key)) ?? 'null');
+    entry = JSON.parse(stored ?? 'null');
   } catch {}
-  if (entry) await kv.delete(key);
+  // Used up before it is used: a failed delete does not stop this download (it still expires).
+  if (entry) await kv.delete(key).catch(() => {});
   // KV expiry can lag a little: the stored deadline is checked too.
   if (!entry?.target || !(now() < entry.exp))
     return new Response(

package/find-files.mjs

@@ -89,7 +89,7 @@ const FILE_HOSTS =
   /(^|\.)(dropbox\.com|drive\.google\.com|docs\.google\.com|onedrive\.live\.com|1drv\.ms|sharepoint\.com|box\.com|github\.com)$/i;
 const FILE_EXT =
   /\.(pdf|zip|pptx?|docx?|xlsx?|csv|txt|md|ipynb|py|java|c|cpp|h|js|tar|gz|tgz|7z|rar)$/i;
-function externalFileLink(raw) {
+export function externalFileLink(raw) {
   let u;
   try {
     u = new URL(raw);
@@ -183,15 +183,17 @@ export async function findFiles(args, token, fetcher) {
   // A source being hidden or not enabled (401/403/404) is normal. A source that failed (timeout,
   // network, rate limit, Canvas error) was not searched: the result is then incomplete, and if
   // nothing could be searched at all the error is passed on instead of an empty "complete" list.
-  // An expired token or an HTML error page (Canvas down, a firewall) stops everything.
+  // An expired token, a rate limit or an HTML error page (Canvas down, a firewall) stops everything.
   const failures = [];
   const hidden = e => [401, 403, 404].includes(e.status);
+  const stops = e =>
+    e.rateLimited || /authorization expired|HTML error page/.test(e?.message ?? '');
   const attempt = async (source, run) => {
     try {
       const n = await run();
       searched[source] = n === undefined ? 'ok' : `ok (${n})`;
     } catch (e) {
-      if (/authorization expired|HTML error page/.test(e.message ?? '')) throw e;
+      if (stops(e)) throw e;
       if (hidden(e)) searched[source] = `not available (HTTP ${e.status})`;
       else {
         failures.push(e);
@@ -248,9 +250,30 @@ export async function findFiles(args, token, fetcher) {
     if (e.found_in.length < MAX_PLACES && !e.found_in.some(p => JSON.stringify(p) === key))
       e.found_in.push(where);
   };
+  // Where a link was written, as canvas_link_content takes it (link-content.mjs).
+  const linkSource = where =>
+    where.type === 'syllabus'
+      ? { source: 'syllabus' }
+      : where.type === 'page'
+        ? where.page_url
+          ? { source: 'page', source_id: where.page_url }
+          : { source: 'front_page' }
+        : where.type === 'assignment' && Number.isSafeInteger(where.assignment_id)
+          ? { source: 'assignment', source_id: String(where.assignment_id) }
+          : where.type === 'announcement' && Number.isSafeInteger(where.topic_id)
+            ? { source: 'discussion', source_id: String(where.topic_id) }
+            : null;
   const addExternal = (x, where) => {
-    if (external.length < MAX_EXTERNAL && !external.some(y => y.url === x.url))
-      external.push({ ...x, found_in: where });
+    if (external.length < MAX_EXTERNAL && !external.some(y => y.url === x.url)) {
+      const from = linkSource(where);
+      external.push({
+        ...x,
+        found_in: where,
+        ...(from
+          ? { read_with: { tool: 'canvas_link_content', course_id: c, ...from, url: x.url } }
+          : {}),
+      });
+    }
   };
   const addHtml = (html, where) => {
     const r = scanHtml(html, c);
@@ -365,7 +388,7 @@ export async function findFiles(args, token, fetcher) {
             page_url: r.data?.url ?? slug,
           });
         } catch (e) {
-          if (/authorization expired|HTML error page/.test(e.message ?? '')) throw e;
+          if (stops(e)) throw e;
           if (hidden(e)) pagesUnavailable++;
           else {
             failures.push(e);
@@ -438,6 +461,6 @@ export async function findFiles(args, token, fetcher) {
         }
       : {}),
     how_to_read:
-      'Read a file_id with canvas_file_content (text from PDF/Office/code, ZIP listing and contents) or canvas_file_original (original bytes, e.g. scanned PDFs). An external link with read_with (a module item): call canvas_module_file_content with those IDs for its text (Google Docs/Slides/Sheets/Drive, Dropbox, GitHub), or canvas_module_file for the original file. Other external links cannot be read by this connector: give the user the link.',
+      'Read a file_id with canvas_file_content (text from PDF/Office/code, ZIP listing and contents) or canvas_file_original (original bytes, e.g. scanned PDFs). An external link with read_with: call the tool it names with those arguments for its text (Google Docs/Slides/Sheets/Drive, Dropbox, GitHub, direct file links); for a module item canvas_module_file gives the original file. Other external links cannot be read by this connector: give the user the link.',
   };
 }

package/i18n.mjs

@@ -51,6 +51,9 @@ const S = {
     down_title: 'Canvas is not answering right now',
     down_hint:
       'Your token is probably fine: Canvas is slow, down for maintenance, or could not be reached. Wait a few minutes, then go back and try again.',
+    busy_title: 'Something went wrong on your connector',
+    busy_body:
+      "Usually its Cloudflare storage is briefly unavailable, or the free plan's daily storage limit is used up (it resets at 00:00 UTC). Your token and your connection are not affected. Try again later.",
     footer: 'Open source · read-only · runs on your own Cloudflare account',
     version_label: 'Version',
     not_configured: 'Not configured yet. Run the installer.',
@@ -101,6 +104,9 @@ const S = {
     expired_body: '这个页面打开太久了，或者在另一个标签页里又打开过一次。请返回，重新粘贴令牌。',
     down_title: 'Canvas 暂时没有响应',
     down_hint: '令牌多半没有问题：Canvas 现在很慢、正在维护，或者连不上。等几分钟后返回重试。',
+    busy_title: '你的连接器出了点问题',
+    busy_body:
+      '通常是它的 Cloudflare 存储暂时不可用，或者免费版当天的存储额度用完了（每天 UTC 0 点重置）。你的令牌和已有的连接都不受影响，请稍后再试。',
     footer: '开源 · 只读 · 运行在你自己的 Cloudflare 账号上',
     version_label: '版本',
     not_configured: '还没配置，请运行安装向导。',
@@ -155,6 +161,9 @@ const S = {
     down_title: 'Canvas no responde ahora mismo',
     down_hint:
       'Seguramente tu token está bien: Canvas va lento, está en mantenimiento o no se pudo contactar. Espera unos minutos, luego vuelve e inténtalo de nuevo.',
+    busy_title: 'Algo salió mal en tu conector',
+    busy_body:
+      'Normalmente su almacenamiento de Cloudflare no está disponible por un momento, o se agotó el límite diario del plan gratuito (se reinicia a las 00:00 UTC). Tu token y tu conexión no se ven afectados. Inténtalo más tarde.',
     footer: 'Código abierto · solo lectura · en tu propia cuenta de Cloudflare',
     version_label: 'Versión',
     not_configured: 'Aún no configurado. Ejecuta el instalador.',
@@ -211,6 +220,9 @@ const S = {
     down_title: 'Canvas が今は応答していません',
     down_hint:
       'トークンはおそらく問題ありません。Canvas が遅いか、メンテナンス中か、接続できませんでした。数分待ってから、戻ってもう一度お試しください。',
+    busy_title: 'コネクタで問題が発生しました',
+    busy_body:
+      '多くの場合、Cloudflare のストレージが一時的に使えないか、無料プランの 1 日あたりのストレージ上限に達しています（UTC 0:00 にリセット）。トークンと接続には影響ありません。しばらくしてからもう一度お試しください。',
     footer: 'オープンソース · 読み取り専用 · あなたの Cloudflare アカウントで動作',
     version_label: 'バージョン',
     not_configured: '未設定です。インストーラーを実行してください。',
@@ -266,6 +278,9 @@ const S = {
     down_title: 'Canvas अभी जवाब नहीं दे रहा',
     down_hint:
       'आपका टोकन शायद ठीक है: Canvas धीमा है, रखरखाव में है, या उससे संपर्क नहीं हो सका। कुछ मिनट रुकें, फिर वापस जाकर दोबारा कोशिश करें।',
+    busy_title: 'आपके कनेक्टर में कुछ गड़बड़ हुई',
+    busy_body:
+      'आम तौर पर इसका Cloudflare स्टोरेज कुछ देर के लिए उपलब्ध नहीं होता, या फ़्री प्लान की रोज़ की स्टोरेज सीमा खत्म हो गई है (यह 00:00 UTC पर रीसेट होती है)। आपका टोकन और कनेक्शन प्रभावित नहीं हैं। बाद में फिर से कोशिश करें।',
     footer: 'ओपन सोर्स · केवल पढ़ना · आपके अपने Cloudflare खाते पर चलता है',
     version_label: 'संस्करण',
     not_configured: 'अभी कॉन्फ़िगर नहीं है। इंस्टॉलर चलाएँ।',

package/installer/cli.mjs

@@ -6,7 +6,8 @@
 // Running it again updates the connector to the code you are running and keeps its storage, so
 // existing Claude/ChatGPT connections keep working.
 // Language: your system language if supported (en, zh, es, ja, hi), else English; --lang to choose.
-// Automation/tests: --name, --canvas-host, --school, --account-id, --yes; env NCLMS_HOME, NCLMS_LANG.
+// Automation/tests: --name, --canvas-host, --school, --account-id, --yes; env NCLMS_HOME, NCLMS_LANG
+// (tests only: NCLMS_WRANGLER, a stand-in for wrangler's bin script).
 // Exit codes: 0 done, 1 failed, 2 deployed but not confirmed online yet (run `check` later).
 import { spawnSync } from 'node:child_process';
 import { createRequire } from 'node:module';
@@ -40,12 +41,16 @@ import { ensureSubdomain } from './subdomain.mjs';
 
 const ROOT = path.resolve(fileURLToPath(new URL('..', import.meta.url)));
 // wrangler's package "exports" hide bin/; find the package root from its main entry instead.
-const WRANGLER = (() => {
-  let dir = path.dirname(createRequire(import.meta.url).resolve('wrangler'));
-  while (path.basename(dir) !== 'wrangler' || !fs.existsSync(path.join(dir, 'package.json')))
-    dir = path.dirname(dir);
-  return path.join(dir, 'bin', 'wrangler.js');
-})();
+const WRANGLER =
+  process.env.NCLMS_WRANGLER ||
+  (() => {
+    let dir = path.dirname(createRequire(import.meta.url).resolve('wrangler'));
+    while (path.basename(dir) !== 'wrangler' || !fs.existsSync(path.join(dir, 'package.json'))) {
+      if (path.dirname(dir) === dir) throw new Error('wrangler is not installed');
+      dir = path.dirname(dir);
+    }
+    return path.join(dir, 'bin', 'wrangler.js');
+  })();
 const HOME = process.env.NCLMS_HOME || path.join(os.homedir(), '.neuro-canvas-lms');
 const args = parseArgs(process.argv.slice(2));
 function systemLanguages() {
@@ -67,7 +72,9 @@ const fail = detail => {
 };
 
 let accountEnv = {};
-function wrangler(argv, { cwd, inherit, timeout } = {}) {
+// Every wrangler step has a time limit (a hung network must not hang the installer); only the
+// interactive login waits as long as the user needs.
+function wrangler(argv, { cwd, inherit, timeout = inherit ? undefined : 2 * 60 * 1000 } = {}) {
   const r = spawnSync(process.execPath, [WRANGLER, ...argv], {
     cwd,
     encoding: 'utf8',
@@ -75,7 +82,37 @@ function wrangler(argv, { cwd, inherit, timeout } = {}) {
     timeout,
     env: { ...process.env, WRANGLER_SEND_METRICS: 'false', ...accountEnv },
   });
-  return { ok: r.status === 0, out: `${r.stdout ?? ''}${r.stderr ?? ''}`, stdout: r.stdout ?? '' };
+  let out = `${r.stdout ?? ''}${r.stderr ?? ''}`;
+  if (r.error?.code === 'ETIMEDOUT') out += '\n' + msg(lang, 'timed_out', { s: timeout / 1000 });
+  return { ok: r.status === 0, out, stdout: r.stdout ?? '' };
+}
+// JSON that wrangler printed on stdout (warnings and banners go to stderr, or come before it).
+function stdoutJson(r, open) {
+  try {
+    return JSON.parse(r.stdout.slice(r.stdout.indexOf(open)));
+  } catch {
+    return null;
+  }
+}
+
+// The local install record. A damaged file is moved aside (and said so) instead of failing every
+// run with the same JSON error; it is written to a temporary file first, then renamed, so an
+// interrupted write cannot damage it.
+function readState(statePath) {
+  if (!fs.existsSync(statePath)) return {};
+  try {
+    const state = JSON.parse(fs.readFileSync(statePath, 'utf8'));
+    if (state && typeof state === 'object' && !Array.isArray(state)) return state;
+  } catch {}
+  const moved = `${statePath}.damaged-${Date.now()}`;
+  fs.renameSync(statePath, moved);
+  say('state_broken', { moved });
+  return {};
+}
+function writeState(statePath, state) {
+  const tmp = `${statePath}.tmp`;
+  fs.writeFileSync(tmp, JSON.stringify(state, null, 2));
+  fs.renameSync(tmp, statePath);
 }
 // A failed wrangler step: an unverified Cloudflare email gets its own clear message.
 const failStep = (what, out) =>
@@ -140,12 +177,13 @@ async function ensureLogin(saved) {
     }
     if (!who.ok) fail(msg(lang, 'login_failed'));
   }
-  const info = JSON.parse(who.out.slice(who.out.indexOf('{')));
+  const info = stdoutJson(who, '{');
+  if (!info) failStep('wrangler whoami', who.out);
   ok('logged_in', { email: info.email ?? '' });
   const accounts = info.accounts ?? [];
   if (args.accountId) return args.accountId;
   if (saved && accounts.some(a => a.id === saved)) return saved;
-  if (!accounts.length) fail('no Cloudflare account found');
+  if (!accounts.length) fail(msg(lang, 'no_account'));
   if (accounts.length === 1) return accounts[0].id;
   // Run by an agent (no terminal) or with --yes: never pick an account silently.
   if (args.yes || !process.stdin.isTTY)
@@ -174,13 +212,17 @@ async function checkCanvas(host) {
   try {
     const r = await fetch(`https://${host}/api/v1/users/self`, {
       redirect: 'manual',
+      signal: AbortSignal.timeout(20 * 1000),
       headers: { 'User-Agent': 'Neuro-CanvasLMS-installer', Accept: 'application/json' },
     });
     const ct = (r.headers.get('content-type') ?? '').split(';')[0];
     if (r.status === 401 && ct.includes('json')) return { ok: true };
     return { ok: false, detail: `HTTP ${r.status}${ct ? ', ' + ct : ''}` };
   } catch (e) {
-    return { ok: false, detail: e.cause?.code ?? e.message };
+    return {
+      ok: false,
+      detail: e.name === 'TimeoutError' ? 'timeout' : (e.cause?.code ?? e.message),
+    };
   }
 }
 async function askCanvasHost(previous, { quiet = false } = {}) {
@@ -205,19 +247,15 @@ async function askCanvasHost(previous, { quiet = false } = {}) {
   fail(msg(lang, 'cancelled'));
 }
 
-// null = the list could not be read (never treat that as "no storage").
+// { list } or, when the list could not be read, { detail } (never treat that as "no storage").
 function listNamespaces() {
   const r = wrangler(['kv', 'namespace', 'list']);
-  if (!r.ok) return null;
-  try {
-    return JSON.parse(r.out.slice(r.out.indexOf('[')));
-  } catch {
-    return null;
-  }
+  const list = r.ok ? stdoutJson(r, '[') : null;
+  return Array.isArray(list) ? { list } : { detail: lastLines(r.out) || 'no answer' };
 }
 function ensureKv(name, state) {
-  const namespaces = listNamespaces();
-  if (!namespaces) fail('could not list storage');
+  const { list: namespaces, detail } = listNamespaces();
+  if (!namespaces) failStep(msg(lang, 'step_kv_list'), detail);
   const existing =
     namespaces.find(n => n.id === state.kvId) ?? namespaces.find(n => n.title === `${name}-oauth`);
   if (existing) {
@@ -227,7 +265,7 @@ function ensureKv(name, state) {
   say('kv');
   const r = wrangler(['kv', 'namespace', 'create', `${name}-oauth`]);
   const id = r.out.match(/"id":\s*"([a-f0-9]{32})"/)?.[1];
-  if (!id) failStep('could not create storage', r.out);
+  if (!id) failStep(msg(lang, 'step_kv_create'), r.out);
   return id;
 }
 
@@ -250,11 +288,11 @@ async function install() {
   const [major] = process.versions.node.split('.').map(Number);
   if (major < 22) fail(msg(lang, 'node_old', { need: 22, have: process.versions.node }));
   const name = args.name ?? DEFAULT_NAME;
-  if (!validWorkerName(name)) fail('invalid --name');
+  if (!validWorkerName(name)) fail(msg(lang, 'invalid_name'));
   const dir = path.join(HOME, name);
   fs.mkdirSync(dir, { recursive: true });
   const statePath = path.join(dir, 'state.json');
-  const state = fs.existsSync(statePath) ? JSON.parse(fs.readFileSync(statePath, 'utf8')) : {};
+  const state = readState(statePath);
   const plan = updateChoices(state, args);
   if (plan.updating) {
     const from = await runningVersion(state.url);
@@ -270,10 +308,7 @@ async function install() {
   const school = plan.school;
   const kvId = ensureKv(name, state);
   const save = extra =>
-    fs.writeFileSync(
-      statePath,
-      JSON.stringify({ ...state, name, accountId, kvId, host, school, ...extra }, null, 2),
-    );
+    writeState(statePath, { ...state, name, accountId, kvId, host, school, ...extra });
   save({});
 
   say('deploy', { version: VERSION });
@@ -281,7 +316,9 @@ async function install() {
   const main = path.relative(dir, path.join(ROOT, 'worker.mjs'));
   const config = connectorConfig({ name, accountId, kvId, main, template, host, school });
   fs.writeFileSync(path.join(dir, 'wrangler.jsonc'), JSON.stringify(config, null, 2));
-  let r = wrangler(['deploy', '-c', 'wrangler.jsonc'], { cwd: dir });
+  const deploy = () =>
+    wrangler(['deploy', '-c', 'wrangler.jsonc'], { cwd: dir, timeout: 5 * 60 * 1000 });
+  let r = deploy();
   // New Cloudflare account: the user picks a workers.dev subdomain in the dashboard, then we retry.
   for (let i = 0; !r.ok && needsSubdomain(r.out) && i < 3; i++) {
     const link = subdomainLink(accountId);
@@ -289,11 +326,11 @@ async function install() {
     say('subdomain_needed', { link });
     openUrl(link);
     await ask(msg(lang, 'subdomain_wait'));
-    r = wrangler(['deploy', '-c', 'wrangler.jsonc'], { cwd: dir });
+    r = deploy();
   }
-  if (!r.ok) failStep('deploy failed', r.out);
+  if (!r.ok) failStep(msg(lang, 'step_deploy'), r.out);
   const url = parseWorkerUrl(r.out) ?? state.url;
-  if (!url) fail('could not read the connector URL: ' + lastLines(r.out));
+  if (!url) fail(`${msg(lang, 'step_url')}: ${lastLines(r.out)}`);
   ok('deploy_ok', { url });
   save({ url, version: VERSION });
 
@@ -357,9 +394,9 @@ function nextSteps(url, host, { tokenAsked = false } = {}) {
 async function check() {
   console.log(`\n  ${msg(lang, 'title')}\n`);
   const name = args.name ?? DEFAULT_NAME;
-  if (!validWorkerName(name)) fail('invalid --name');
+  if (!validWorkerName(name)) fail(msg(lang, 'invalid_name'));
   const statePath = path.join(HOME, name, 'state.json');
-  const state = fs.existsSync(statePath) ? JSON.parse(fs.readFileSync(statePath, 'utf8')) : {};
+  const state = readState(statePath);
   if (!state.url) {
     console.error('  ✗ ' + msg(lang, 'check_none', { name }));
     process.exitCode = 1;
@@ -379,7 +416,7 @@ async function uninstall() {
   const name = args.name ?? DEFAULT_NAME;
   const dir = path.join(HOME, name);
   const statePath = path.join(dir, 'state.json');
-  const state = fs.existsSync(statePath) ? JSON.parse(fs.readFileSync(statePath, 'utf8')) : {};
+  const state = readState(statePath);
   // The account the connector was installed in. In any other account "Worker does not exist"
   // would look like success while the Worker and its storage (with the token grants) stay online.
   const accountId = await ensureLogin(state.accountId);
@@ -393,8 +430,15 @@ async function uninstall() {
   if (!worker.ok && !/\b10090\b|does not exist/i.test(worker.out))
     fail(msg(lang, 'un_failed', { what: `Worker "${name}"`, detail: lastLines(worker.out) }));
   const before = listNamespaces();
-  if (!before) fail(msg(lang, 'un_failed', { what: 'storage', detail: 'could not list storage' }));
-  const kv = before.find(n => n.id === state.kvId) ?? before.find(n => n.title === `${name}-oauth`);
+  if (!before.list)
+    fail(
+      msg(lang, 'un_failed', {
+        what: msg(lang, 'step_kv_list'),
+        detail: before.detail,
+      }),
+    );
+  const kv =
+    before.list.find(n => n.id === state.kvId) ?? before.find(n => n.title === `${name}-oauth`);
   if (kv) {
     const r = wrangler([
       'kv',
@@ -404,11 +448,12 @@ async function uninstall() {
       kv.id,
       '--skip-confirmation',
     ]);
+    const what = msg(lang, 'storage_label', { title: kv.title });
     if (!r.ok && !/\b10013\b|not found/i.test(r.out))
-      fail(msg(lang, 'un_failed', { what: `storage "${kv.title}"`, detail: lastLines(r.out) }));
+      fail(msg(lang, 'un_failed', { what, detail: lastLines(r.out) }));
     const after = listNamespaces();
-    if (!after || after.some(n => n.id === kv.id))
-      fail(msg(lang, 'un_failed', { what: `storage "${kv.title}"`, detail: 'still listed' }));
+    if (!after.list || after.list.some(n => n.id === kv.id))
+      fail(msg(lang, 'un_failed', { what, detail: after.detail ?? msg(lang, 'still_listed') }));
   }
   fs.rmSync(dir, { recursive: true, force: true });
   ok('un_done');