neuro-canvas-lms 2.10.0 → 2.11.0

package/AGENTS.md

@@ -30,6 +30,7 @@ Code map:
 - `owner.mjs`: owner binding, allowed OAuth clients. `i18n.mjs` + `pages.mjs`: web pages.
 - `update-check.mjs`: once a day reads the newest version number from npm; when it is newer the AI
   tells the user how to update. Also the `canvas_connector_version` tool.
-- `installer/`: the setup wizard (re-running it asks once, y/n, then updates with the saved
-  settings; without a terminal it does not ask). `version.mjs`: shown on
-  the home page and /healthz, compared with npm by update-check.mjs.
+- `installer/`: the setup wizard. Re-running it asks once (y/n), then updates with the saved
+  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.

package/installer/cli.mjs

@@ -1,11 +1,13 @@
 // Neuro-CanvasLMS installer. Deploys THIS copy of the code to your own Cloudflare account.
 //   npx -y neuro-canvas-lms             install, or update an existing install
 //   npx -y neuro-canvas-lms uninstall   remove it
+//   npx -y neuro-canvas-lms check       only check an installed connector (deploys nothing)
 //   (from a clone: npm run setup / npm run setup -- uninstall)
 // 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.
+// 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';
 import fs from 'node:fs';
@@ -32,6 +34,7 @@ import {
   subdomainLink,
 } from './lib.mjs';
 import { msg } from './messages.mjs';
+import { verifyDeployment } from './verify.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.
@@ -227,27 +230,6 @@ async function runningVersion(url) {
   }
 }
 
-async function healthCheck(url) {
-  let detail = 'no answer';
-  for (let i = 0; i < 20; i++) {
-    if (i) await new Promise(r => setTimeout(r, 3000));
-    try {
-      const h = await fetch(`${url}/healthz`, { headers: { 'Cache-Control': 'no-cache' } });
-      const j = h.ok ? await h.json() : null;
-      if (!j?.ok) detail = `/healthz HTTP ${h.status}`;
-      else if (j.version !== VERSION) detail = `still ${j.version}`;
-      else {
-        const mcp = await fetch(`${url}/mcp`, { method: 'POST', body: '{}' });
-        if (mcp.status === 401) return { ok: true, connected: j.connected === true };
-        detail = `/mcp HTTP ${mcp.status}`;
-      }
-    } catch (e) {
-      detail = e.message;
-    }
-  }
-  return { ok: false, detail };
-}
-
 async function install() {
   console.log(`\n  ${msg(lang, 'title')}\n`);
   const [major] = process.versions.node.split('.').map(Number);
@@ -302,8 +284,8 @@ async function install() {
   save({ url, version: VERSION });
 
   say('check');
-  const check = await healthCheck(url);
-  if (!check.ok) fail(msg(lang, 'check_bad', { detail: check.detail }));
+  const check = await verifyDeployment(url, VERSION, { onWarmup: () => say('cert_wait') });
+  if (!check.ok) return notConfirmed(name, url, check.detail);
   ok('check_ok', { version: VERSION });
 
   // Already connected: an update needs nothing from the user, so don't send them to make a token,
@@ -316,6 +298,22 @@ async function install() {
     console.log('');
     return;
   }
+  nextSteps(url, host);
+}
+
+// The deploy worked but the address did not answer correctly in time (usually a brand-new
+// workers.dev address still getting its certificate). Not a failure: say where it is and how to
+// check again without deploying. Exit code 2 tells scripts and agents exactly that.
+function notConfirmed(name, url, detail) {
+  const cmd = 'npx -y neuro-canvas-lms check' + (name === DEFAULT_NAME ? '' : ` --name ${name}`);
+  console.log('');
+  say('check_pending', { url, detail, cmd });
+  console.log('');
+  process.exitCode = 2;
+}
+
+// What the user does next, once the connector is online and not yet connected to an AI app.
+function nextSteps(url, host) {
   copy(`${url}/mcp`);
   console.log(`\n  ${msg(lang, 'done')}`);
   say('done_1', { canvas: `https://${host}` });
@@ -330,6 +328,28 @@ async function install() {
   if (!args.yes) openUrl(`https://${host}/profile/settings`);
 }
 
+// Only check an installed connector (after "not confirmed online yet"): nothing is deployed.
+async function check() {
+  console.log(`\n  ${msg(lang, 'title')}\n`);
+  const name = args.name ?? DEFAULT_NAME;
+  if (!validWorkerName(name)) fail('invalid --name');
+  const statePath = path.join(HOME, name, 'state.json');
+  const state = fs.existsSync(statePath) ? JSON.parse(fs.readFileSync(statePath, 'utf8')) : {};
+  if (!state.url) {
+    console.error('  ✗ ' + msg(lang, 'check_none', { name }));
+    process.exitCode = 1;
+    return;
+  }
+  say('check_only', { url: state.url });
+  const result = await verifyDeployment(state.url, state.version, {
+    onWarmup: () => say('cert_wait'),
+  });
+  if (!result.ok) return notConfirmed(name, state.url, result.detail);
+  ok('check_ok', { version: result.version });
+  if (result.connected) return ok('check_connected');
+  nextSteps(state.url, state.host);
+}
+
 async function uninstall() {
   const name = args.name ?? DEFAULT_NAME;
   const dir = path.join(HOME, name);
@@ -369,11 +389,11 @@ const help = async () =>
     fs
       .readFileSync(fileURLToPath(import.meta.url), 'utf8')
       .split('\n')
-      .slice(0, 8)
+      .slice(0, 10)
       .join('\n'),
   );
-({ install, uninstall, help })[args.command]().then(
-  () => process.exit(0),
+({ install, uninstall, help, check })[args.command]().then(
+  () => process.exit(process.exitCode ?? 0),
   e => {
     console.error('\n  ✗ ' + msg(lang, 'failed', { detail: e?.message ?? e }) + '\n');
     process.exit(1);

package/installer/lib.mjs

@@ -68,7 +68,7 @@ export function parseArgs(argv) {
   const out = { command: 'install' };
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i];
-    if (a === 'install' || a === 'uninstall' || a === 'help') out.command = a;
+    if (['install', 'uninstall', 'help', 'check'].includes(a)) out.command = a;
     else if (a === '--yes' || a === '-y') out.yes = true;
     else if (a.startsWith('--')) {
       const [k, v] = a.includes('=') ? a.slice(2).split(/=(.*)/s) : [a.slice(2), argv[++i]];
@@ -108,3 +108,12 @@ export const isYes = answer => /^(?:y|yes)$/i.test(String(answer ?? '').trim());
 export const needsSubdomain = out => /register a workers\.dev subdomain/i.test(out ?? '');
 export const subdomainLink = accountId =>
   `https://dash.cloudflare.com/${encodeURIComponent(accountId)}/workers/onboarding`;
+
+// A new workers.dev address answers only once its DNS and HTTPS certificate are ready, which can
+// take minutes on a brand-new subdomain. These errors mean "not ready yet", not "broken".
+export const isWarmingUp = detail =>
+  /SSL|TLS|CERT|UNABLE_TO_VERIFY|SELF_SIGNED|EPROTO|handshake|ENOTFOUND|EAI_AGAIN|ECONNRESET|ECONNREFUSED|certificate/i.test(
+    detail ?? '',
+  );
+export const CHECK_WAIT = 60 * 1000; // a normal deploy answers within a minute
+export const WARMUP_WAIT = 5 * 60 * 1000; // a new address may need a few minutes for its certificate

package/installer/messages.mjs

@@ -23,7 +23,6 @@ const M = {
     deploy_ok: 'Connector is live: {url}',
     check: 'Step 4/4 · Checking the connector…',
     check_ok: 'Everything works (version {version}).',
-    check_bad: 'The connector did not pass its check: {detail}',
     done: 'Done! Last step, in your AI:',
     done_1:
       '1. Create a Canvas access token: {canvas}/profile/settings → "+ New Access Token" (copy it; Canvas shows it once).',
@@ -47,6 +46,14 @@ const M = {
     un_done:
       'Removed. Also delete the Canvas token (Canvas → Account → Settings) and the connector in your AI app.',
     cancelled: 'Cancelled.',
+    check_pending:
+      'Deployed to {url}, but it could not be confirmed online yet ({detail}). A new address can take a few more minutes the first time. Nothing needs to be deployed again: in a few minutes, check it with\n    {cmd}',
+    check_none:
+      'No install named "{name}" was found (installed under another name? add --name <name>). Install it first with npx -y neuro-canvas-lms.',
+    check_only: 'Checking the connector at {url}…',
+    check_connected: 'It is connected to your AI apps and ready to use.',
+    cert_wait:
+      'The new workers.dev address is still getting its HTTPS certificate. The first time this can take a few minutes; waiting…',
     pick_account_flag:
       'This Cloudflare login has several accounts. Run the same command again with one of these added:\n{list}',
     canvas_flag:
@@ -87,7 +94,6 @@ const M = {
     deploy_ok: '连接器已上线：{url}',
     check: '第 4/4 步 · 检查连接器…',
     check_ok: '一切正常（版本 {version}）。',
-    check_bad: '连接器没通过检查：{detail}',
     done: '装好了！最后一步，在你的 AI 里：',
     done_1:
       '1. 生成 Canvas 访问令牌：{canvas}/profile/settings →「+ 新建访问许可证」（立刻复制，Canvas 只显示一次）。',
@@ -105,6 +111,13 @@ const M = {
     un_failed: '没能删除{what}：{detail}\n  本地安装记录已保留，再运行一次同一条命令即可重试。',
     un_done: '已删除。另外请删掉 Canvas 令牌（Canvas → 账户 → 设置）和 AI 应用里的连接器。',
     cancelled: '已取消。',
+    check_pending:
+      '已部署到 {url}，但还没能确认它已上线（{detail}）。新地址第一次可能还要几分钟。不需要重新部署：过几分钟用这条命令只做检查：\n    {cmd}',
+    check_none:
+      '没找到名为「{name}」的安装（装的时候用了别的名字？加上 --name <名字>）。请先用 npx -y neuro-canvas-lms 安装。',
+    check_only: '检查连接器 {url}…',
+    check_connected: '已经连接到你的 AI 应用，可以直接用。',
+    cert_wait: '新的 workers.dev 地址还在申请 HTTPS 证书，第一次可能要几分钟，正在等待…',
     pick_account_flag:
       '这个 Cloudflare 登录下有多个账号。请在同一条命令后加上其中一个，再运行一次：\n{list}',
     canvas_flag:
@@ -147,7 +160,6 @@ const M = {
     deploy_ok: 'El conector está activo: {url}',
     check: 'Paso 4/4 · Comprobando el conector…',
     check_ok: 'Todo funciona (versión {version}).',
-    check_bad: 'El conector no pasó la comprobación: {detail}',
     done: '¡Listo! Último paso, en tu IA:',
     done_1:
       '1. Crea un token de acceso de Canvas: {canvas}/profile/settings → "+ Nuevo token de acceso" (cópialo; Canvas lo muestra una sola vez).',
@@ -172,6 +184,14 @@ const M = {
     un_done:
       'Eliminado. Borra también el token de Canvas (Canvas → Cuenta → Configuración) y el conector en tu app de IA.',
     cancelled: 'Cancelado.',
+    check_pending:
+      'Desplegado en {url}, pero aún no se pudo confirmar que está en línea ({detail}). Una dirección nueva puede tardar unos minutos más la primera vez. No hace falta volver a desplegar: dentro de unos minutos, compruébalo con\n    {cmd}',
+    check_none:
+      'No se encontró ninguna instalación llamada "{name}" (¿la instalaste con otro nombre? añade --name <nombre>). Instálala primero con npx -y neuro-canvas-lms.',
+    check_only: 'Comprobando el conector en {url}…',
+    check_connected: 'Está conectado a tus apps de IA y listo para usar.',
+    cert_wait:
+      'La nueva dirección workers.dev todavía está obteniendo su certificado HTTPS. La primera vez puede tardar unos minutos; esperando…',
     pick_account_flag:
       'Este inicio de sesión de Cloudflare tiene varias cuentas. Ejecuta el mismo comando otra vez añadiendo una de estas:\n{list}',
     canvas_flag:
@@ -215,7 +235,6 @@ const M = {
     deploy_ok: 'コネクタが公開されました：{url}',
     check: 'ステップ 4/4 · コネクタを確認しています…',
     check_ok: 'すべて正常です（バージョン {version}）。',
-    check_bad: 'コネクタが確認に失敗しました：{detail}',
     done: '完了！最後のステップ（AI 側）：',
     done_1:
       '1. Canvas アクセストークンを作成：{canvas}/profile/settings →「+ 新しいアクセストークン」（すぐコピー。表示は一度きりです）。',
@@ -239,6 +258,14 @@ const M = {
     un_done:
       '削除しました。Canvas トークン（Canvas → アカウント → 設定）と AI アプリのコネクタも削除してください。',
     cancelled: 'キャンセルしました。',
+    check_pending:
+      '{url} へのデプロイは完了しましたが、まだオンラインであることを確認できていません（{detail}）。新しいアドレスは初回にさらに数分かかることがあります。再デプロイは不要です。数分後に次のコマンドで確認だけ行ってください：\n    {cmd}',
+    check_none:
+      '「{name}」という名前のインストールが見つかりません（別の名前でインストールした場合は --name <名前> を付けてください）。先に npx -y neuro-canvas-lms でインストールしてください。',
+    check_only: '{url} のコネクタを確認しています…',
+    check_connected: 'AI アプリに接続済みで、すぐに使えます。',
+    cert_wait:
+      '新しい workers.dev アドレスの HTTPS 証明書を準備しています。初回は数分かかることがあります。待機しています…',
     pick_account_flag:
       'この Cloudflare ログインには複数のアカウントがあります。同じコマンドに次のどれかを付けて、もう一度実行してください：\n{list}',
     canvas_flag:
@@ -282,7 +309,6 @@ const M = {
     deploy_ok: 'कनेक्टर चालू है: {url}',
     check: 'चरण 4/4 · कनेक्टर की जाँच हो रही है…',
     check_ok: 'सब कुछ ठीक है (संस्करण {version})।',
-    check_bad: 'कनेक्टर जाँच में विफल रहा: {detail}',
     done: 'हो गया! आख़िरी कदम, अपने AI में:',
     done_1:
       '1. Canvas एक्सेस टोकन बनाएँ: {canvas}/profile/settings → "+ New Access Token" (तुरंत कॉपी करें; Canvas इसे केवल एक बार दिखाता है)।',
@@ -306,6 +332,14 @@ const M = {
     un_done:
       'हटा दिया गया। Canvas टोकन (Canvas → Account → Settings) और अपने AI ऐप में कनेक्टर भी हटाएँ।',
     cancelled: 'रद्द किया गया।',
+    check_pending:
+      '{url} पर डिप्लॉय हो गया, लेकिन अभी पुष्टि नहीं हो पाई कि यह ऑनलाइन है ({detail})। नए पते को पहली बार कुछ और मिनट लग सकते हैं। दोबारा डिप्लॉय करने की ज़रूरत नहीं: कुछ मिनट बाद इस कमांड से सिर्फ़ जाँच करें:\n    {cmd}',
+    check_none:
+      '"{name}" नाम का कोई इंस्टॉल नहीं मिला (किसी और नाम से इंस्टॉल किया था? --name <नाम> जोड़ें)। पहले npx -y neuro-canvas-lms से इंस्टॉल करें।',
+    check_only: '{url} पर कनेक्टर की जाँच हो रही है…',
+    check_connected: 'यह आपके AI ऐप से जुड़ा है और इस्तेमाल के लिए तैयार है।',
+    cert_wait:
+      'नए workers.dev पते का HTTPS प्रमाणपत्र अभी तैयार हो रहा है। पहली बार इसमें कुछ मिनट लग सकते हैं; प्रतीक्षा हो रही है…',
     pick_account_flag:
       'इस Cloudflare लॉगिन में कई खाते हैं। वही कमांड इनमें से एक जोड़कर फिर से चलाएँ:\n{list}',
     canvas_flag:

package/installer/verify.mjs

@@ -0,0 +1,61 @@
+// Is a freshly deployed connector online and running the expected version?
+// Ready means: /healthz answers ok with that version AND /mcp refuses an unauthenticated request
+// with 401 (the OAuth layer is in front). Each request has its own timeout and the whole check a
+// deadline, so it always ends. A new workers.dev address can take minutes for its DNS and HTTPS
+// certificate: for those "not ready yet" errors the deadline is longer. Everything that touches
+// the network or the clock can be replaced, so the behaviour is tested (verify.test.mjs).
+import { isWarmingUp, CHECK_WAIT, WARMUP_WAIT } from './lib.mjs';
+
+// fetch reports only "fetch failed"; the cause names the real problem (a TLS alert, DNS, …).
+export function errorDetail(e) {
+  if (e?.name === 'TimeoutError' || e?.cause?.name === 'TimeoutError') return 'no answer (timeout)';
+  return String(e?.cause?.code ?? e?.cause?.message ?? e?.message ?? e);
+}
+
+export async function verifyDeployment(
+  url,
+  version,
+  {
+    fetcher = fetch,
+    sleep = ms => new Promise(r => setTimeout(r, ms)),
+    now = Date.now,
+    requestTimeout = 10 * 1000,
+    interval = 3 * 1000,
+    normalWait = CHECK_WAIT,
+    warmupWait = WARMUP_WAIT,
+    onWarmup = () => {},
+  } = {},
+) {
+  let detail = 'no answer';
+  let told = false;
+  const start = now();
+  for (let i = 0; now() - start < (isWarmingUp(detail) ? warmupWait : normalWait); i++) {
+    if (i) await sleep(interval);
+    try {
+      const h = await fetcher(`${url}/healthz`, {
+        headers: { 'Cache-Control': 'no-cache' },
+        signal: AbortSignal.timeout(requestTimeout),
+      });
+      const j = h.ok ? await h.json() : null;
+      if (!j?.ok) detail = `/healthz HTTP ${h.status}`;
+      else if (version && j.version !== version) detail = `still version ${j.version}`;
+      else {
+        const mcp = await fetcher(`${url}/mcp`, {
+          method: 'POST',
+          body: '{}',
+          signal: AbortSignal.timeout(requestTimeout),
+        });
+        if (mcp.status === 401)
+          return { ok: true, version: j.version, connected: j.connected === true };
+        detail = `/mcp HTTP ${mcp.status} (expected 401)`;
+      }
+    } catch (e) {
+      detail = errorDetail(e);
+      if (isWarmingUp(detail) && !told) {
+        told = true;
+        onWarmup(detail);
+      }
+    }
+  }
+  return { ok: false, detail };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "neuro-canvas-lms",
-  "version": "2.10.0",
+  "version": "2.11.0",
   "description": "Neuro-CanvasLMS: read-only connector that lets Claude or ChatGPT read any Canvas LMS (remote MCP server on your own Cloudflare account)",
   "keywords": [
     "canvas",
@@ -20,7 +20,7 @@
   },
   "repository": {
     "type": "git",
-    "url": "https://github.com/BloodyReginaa/Neuro-CanvasLMS.git"
+    "url": "git+https://github.com/BloodyReginaa/Neuro-CanvasLMS.git"
   },
   "license": "MIT",
   "author": "BloodyReginaa",

package/version.mjs

@@ -1,3 +1,3 @@
 // The connector's version, shown on its home page and at /healthz (the installer checks that the
 // deployed version answers). Bump it together with package.json when something changes.
-export const VERSION = '2.10.0';
+export const VERSION = '2.11.0';