linke-sdufe 0.1.0

package/src/env.js

@@ -0,0 +1,60 @@
+/**
+ * 运行环境能力注入（宿主适配层）。
+ *
+ * 适配器核心不直接触碰 Node 专有 API；宿主通过 env 提供四件能力：
+ *
+ *   env.fetch(url, { method, headers, body, redirect, timeoutMs, expect })
+ *     → Promise<Response-like>
+ *       Response-like: { status:number, ok:boolean,
+ *                        headers:{ getSetCookie():string[] },
+ *                        text():Promise<string>, arrayBuffer():Promise<ArrayBuffer> }
+ *     expect='buffer' 表示适配器将调用 arrayBuffer()（uni.request 一次只能
+ *     一种 responseType，垫片据此选择；标准 fetch 宿主可忽略 expect）。
+ *     超时由 timeoutMs 表达（毫秒），宿主负责实现（Node 用 AbortSignal.timeout）。
+ *     请求失败（网络层）应 reject——适配器统一转 networkError。
+ *
+ *   env.toBase64(bytes:Uint8Array) → string   验证码图片上行（云端识别入参）
+ *   env.bytesToText(bytes:Uint8Array) → string 前 200 字节嗅探（判定教务返回
+ *     了 HTML 错误页而非图片），宽松实现即可（ASCII 特征判定）
+ *   env.progress(msg:string) → void           进度输出（Node 走 stderr；
+ *     App 端注入 console/log 回调，缺省为 no-op）
+ */
+
+/** Node 宿主默认 env（Node >= 18.14：全局 fetch + getSetCookie）。全惰性，模块顶层零 Node 触碰 */
+export function nodeEnv() {
+  return {
+    async fetch(url, { method, headers, body, redirect, timeoutMs } = {}) {
+      return fetch(url, {
+        method,
+        redirect,
+        headers,
+        body,
+        signal: AbortSignal.timeout(timeoutMs || 20000),
+      })
+    },
+    toBase64(bytes) {
+      return Buffer.from(bytes).toString('base64')
+    },
+    bytesToText(bytes) {
+      return Buffer.from(bytes).toString('utf8')
+    },
+    progress(msg) {
+      process.stderr.write(`[linke] ${msg}\n`)
+    },
+  }
+}
+
+const REQUIRED = ['fetch', 'toBase64', 'bytesToText']
+
+/** 校验宿主 env 缺件（progress 可缺省，其余三件必须） */
+export function validateEnv(env) {
+  if (!env || typeof env !== 'object') {
+    throw new Error('createSdufeAdapter 需要 env 对象（见 linke-sdufe README 环境契约）')
+  }
+  for (const key of REQUIRED) {
+    if (typeof env[key] !== 'function') {
+      throw new Error(`env.${key} 缺失或不是函数（linke-sdufe 环境契约四件之一）`)
+    }
+  }
+  return env
+}

package/src/errors.js

@@ -0,0 +1,64 @@
+/**
+ * 适配器层统一错误分类。exit code 契约同时写进了 linke-cli 的
+ * skill 说明书（skills/linke/SKILL.md），改动这里必须同步改说明书。
+ * linke-cli 的 src/errors.js re-export 本文件并补充 CLI 专属错误
+ * （configMissing）——单一实现，双端同源。
+ */
+export class LinkeError extends Error {
+  /**
+   * @param {string} code 机器可读错误码
+   * @param {string} message 人类可读信息（不得包含密码等凭据）
+   * @param {object} options
+   * @param {number} options.exitCode
+   * @param {string} options.hint 自救提示（给 agent / 用户看）
+   * @param {boolean} options.isLoginExpired 内部标记：教务 session 失效，可重登重试
+   */
+  constructor(code, message, options = {}) {
+    super(message)
+    this.name = 'LinkeError'
+    this.code = code
+    this.exitCode = options.exitCode ?? 1
+    this.hint = options.hint ?? ''
+    this.isLoginExpired = options.isLoginExpired ?? false
+    this.cause = options.cause
+  }
+}
+
+export const EXIT = {
+  OK: 0,
+  GENERAL: 1,
+  CREDENTIAL_INVALID: 2,
+  LOGIN_RETRY_EXHAUSTED: 3,
+  NETWORK: 4,
+  PARSE: 5,
+  NOT_CONFIGURED: 6,
+}
+
+export function credentialInvalid(detail = '') {
+  return new LinkeError('CREDENTIAL_INVALID', `教务账号或密码错误${detail ? `（${detail}）` : ''}`, {
+    exitCode: EXIT.CREDENTIAL_INVALID,
+    hint: '请重新运行: linke config 录入正确凭据',
+  })
+}
+
+export function loginRetryExhausted(attempts) {
+  return new LinkeError('LOGIN_RETRY_EXHAUSTED', `验证码自动识别连续 ${attempts} 次未通过，登录未完成`, {
+    exitCode: EXIT.LOGIN_RETRY_EXHAUSTED,
+    hint: '稍后重试同一命令即可（会自动重登）；若持续失败，可能是云端识别服务或教务系统异常，运行 linke status 检查',
+  })
+}
+
+export function networkError(action, cause) {
+  return new LinkeError('NETWORK', `${action}失败：网络不可达或服务异常`, {
+    exitCode: EXIT.NETWORK,
+    hint: '检查本机网络（教务系统为校内可达的 http://jw.sdufe.edu.cn，云端识别为 https://api.linketeam.com）后重试',
+    cause,
+  })
+}
+
+export function parseError(what) {
+  return new LinkeError('PARSE', `解析${what}失败：教务页面结构可能已变化`, {
+    exitCode: EXIT.PARSE,
+    hint: '这是适配器正则与教务页面脱节，请到 linke-cli 仓库提 issue 注明发生时间',
+  })
+}

package/src/index.js

@@ -0,0 +1,11 @@
+/**
+ * linke-sdufe：山财强智教务适配器共享包。
+ * linke-cli（Node）与 Linke App（uni-app，经 uni.request 垫片）同源引用。
+ */
+export { createSdufeAdapter, COURSE_TYPE_MAP } from './adapter.js'
+export { nodeEnv, validateEnv } from './env.js'
+export { computeEncoded } from './encoding.js'
+export * as parsers from './parsers.js'
+export { stripSpaces, isJwLoginExpired, extractCookieHeader } from './util.js'
+export { LinkeError, EXIT, networkError, credentialInvalid, loginRetryExhausted, parseError } from './errors.js'
+export { getAdapter, registerAdapter, listAdapters, initSdufe } from './registry.js'