zentao-api 0.6.6 → 0.6.8

package/dist/modules/override.d.ts

@@ -20,6 +20,7 @@
  * ```ts
  * defineModuleActions('bug', {
  *   name: 'assignTo',
+ *   minVersion: ['22.0', 'biz13.0', 'max8.0', 'ipd5.0'],
  *   display: '指派 Bug',
  *   type: 'action',
  *   method: 'put',
@@ -44,6 +45,7 @@
  *   actions: [
  *     {
  *       name: 'list',
+ *       minVersion: ['22.0', 'biz13.0', 'max8.0', 'ipd5.0'],
  *       type: 'list',
  *       method: 'get',
  *       path: '/customs',

package/dist/modules/override.js

@@ -24,6 +24,7 @@ import { isRecord } from '../utils/index.js';
  * ```ts
  * defineModuleActions('bug', {
  *   name: 'assignTo',
+ *   minVersion: ['22.0', 'biz13.0', 'max8.0', 'ipd5.0'],
  *   display: '指派 Bug',
  *   type: 'action',
  *   method: 'put',
@@ -48,6 +49,7 @@ import { isRecord } from '../utils/index.js';
  *   actions: [
  *     {
  *       name: 'list',
+ *       minVersion: ['22.0', 'biz13.0', 'max8.0', 'ipd5.0'],
  *       type: 'list',
  *       method: 'get',
  *       path: '/customs',
@@ -178,6 +180,7 @@ export function applyBuiltinOverrides() {
     // 定义获取需求层级操作
     defineModuleActions('story', {
         name: 'getGrades',
+        minVersion: ['22.5', 'biz13.5', 'max8.5', 'ipd5.5'],
         display: '获取需求层级选项',
         type: 'list',
         method: 'get',

package/dist/modules/query.d.ts

@@ -1,14 +1,15 @@
-import type { ModuleAction, ModuleActionParam, ModuleActionParamRole, ModuleDefinition } from '../types/index.js';
+import type { ModuleAction, ModuleActionParam, ModuleActionParamRole, ModuleDefinition, ModuleQueryOptions } from '../types/index.js';
 /**
  * 获取模块定义。
  *
- * 模块名匹配大小写不敏感。返回值是注册表内部的已深冻结引用（O(1) 查询、零拷贝），
+ * 模块名匹配大小写不敏感。未传版本时返回注册表内部的已深冻结引用（O(1) 查询、零拷贝），
  * 任何写入尝试在严格模式下会抛 `TypeError`；如需修改请使用 {@link defineModules}。
  *
  * @param moduleName - 模块名。
- * @returns 已注册的模块定义；模块未注册时返回 `undefined`。
+ * @param options - 可选版本过滤；不传时保留完整注册表引用，传入时返回冻结的过滤视图。
+ * @returns 已注册的模块定义；模块未注册或过滤后没有动作时返回 `undefined`。
  */
-export declare function getModule(moduleName: string): ModuleDefinition | undefined;
+export declare function getModule(moduleName: string, options?: ModuleQueryOptions): ModuleDefinition | undefined;
 /**
  * 获取指定模块下的某个动作。
  *
@@ -20,9 +21,10 @@ export declare function getModule(moduleName: string): ModuleDefinition | undefi
  *
  * @param moduleName - 模块名（大小写不敏感）。
  * @param actionName - 动作名（大小写不敏感）；支持 `ls` 作为 `list` 的别名。
+ * @param options - 可选版本过滤。
  * @returns 匹配到的动作定义；模块未注册或动作不存在时返回 `undefined`。
  */
-export declare function getModuleAction(moduleName: string, actionName: string): ModuleAction | undefined;
+export declare function getModuleAction(moduleName: string, actionName: string, options?: ModuleQueryOptions): ModuleAction | undefined;
 /**
  * 获取指定模块下的某个动作的参数。
  *
@@ -30,9 +32,10 @@ export declare function getModuleAction(moduleName: string, actionName: string):
  * @param actionName - 动作名（大小写不敏感）；支持 `ls` 作为 `list` 的别名。
  * @param options - 选项。
  * @param options.roles - 角色，可选 `path`、`query`、`body`。
+ * @param options.version - 可选禅道版本；不支持该动作时返回空数组，不做参数级版本过滤。
  * @returns 动作参数。
  */
-export declare function getModuleActionParams(moduleName: string, actionName: string, options?: {
+export declare function getModuleActionParams(moduleName: string, actionName: string, options?: ModuleQueryOptions & {
     roles?: ModuleActionParamRole[];
 }): ModuleActionParam[];
 /**
@@ -41,15 +44,17 @@ export declare function getModuleActionParams(moduleName: string, actionName: st
  * 顺序与模块写入注册表的顺序一致；包括内置模块和通过 {@link defineModules} 追加的用户模块。
  *
  * @returns 模块名数组（保留原始大小写）。
+ * @param options - 可选版本过滤，仅保留含有支持动作的模块。
  */
-export declare function getModuleNames(): string[];
+export declare function getModuleNames(options?: ModuleQueryOptions): string[];
 /**
  * 判断模块名是否已注册。
  *
  * @param moduleName - 模块名；匹配大小写不敏感。
+ * @param options - 可选版本过滤。
  * @returns 已注册返回 `true`，否则 `false`。
  */
-export declare function isModuleName(moduleName: string): boolean;
+export declare function isModuleName(moduleName: string, options?: ModuleQueryOptions): boolean;
 /**
  * 获取对象属性。
  *

package/dist/modules/query.js

@@ -1,16 +1,23 @@
+import { parseZentaoVersion, supportsZentaoVersion } from '../misc/zentao-version.js';
 import { objectProps } from './object-props.js';
 import { getModuleMapState, getModulesState } from './registry-store.js';
 /**
  * 获取模块定义。
  *
- * 模块名匹配大小写不敏感。返回值是注册表内部的已深冻结引用（O(1) 查询、零拷贝），
+ * 模块名匹配大小写不敏感。未传版本时返回注册表内部的已深冻结引用（O(1) 查询、零拷贝），
  * 任何写入尝试在严格模式下会抛 `TypeError`；如需修改请使用 {@link defineModules}。
  *
  * @param moduleName - 模块名。
- * @returns 已注册的模块定义；模块未注册时返回 `undefined`。
+ * @param options - 可选版本过滤；不传时保留完整注册表引用，传入时返回冻结的过滤视图。
+ * @returns 已注册的模块定义；模块未注册或过滤后没有动作时返回 `undefined`。
  */
-export function getModule(moduleName) {
-    return getModuleMapState().get(moduleName.toLowerCase());
+export function getModule(moduleName, options = {}) {
+    const version = options.version === undefined ? undefined : parseZentaoVersion(options.version);
+    const module = getModuleMapState().get(moduleName.toLowerCase());
+    if (!version || !module)
+        return module;
+    const actions = module.actions.filter(action => supportsZentaoVersion(version, action.minVersion));
+    return actions.length ? Object.freeze({ ...module, actions: Object.freeze(actions) }) : undefined;
 }
 /**
  * 获取指定模块下的某个动作。
@@ -23,10 +30,11 @@ export function getModule(moduleName) {
  *
  * @param moduleName - 模块名（大小写不敏感）。
  * @param actionName - 动作名（大小写不敏感）；支持 `ls` 作为 `list` 的别名。
+ * @param options - 可选版本过滤。
  * @returns 匹配到的动作定义；模块未注册或动作不存在时返回 `undefined`。
  */
-export function getModuleAction(moduleName, actionName) {
-    const module = getModule(moduleName);
+export function getModuleAction(moduleName, actionName, options) {
+    const module = getModule(moduleName, options);
     if (!module)
         return undefined;
     const normalized = actionName === 'ls' ? 'list' : actionName;
@@ -39,12 +47,13 @@ export function getModuleAction(moduleName, actionName) {
  * @param actionName - 动作名（大小写不敏感）；支持 `ls` 作为 `list` 的别名。
  * @param options - 选项。
  * @param options.roles - 角色，可选 `path`、`query`、`body`。
+ * @param options.version - 可选禅道版本；不支持该动作时返回空数组，不做参数级版本过滤。
  * @returns 动作参数。
  */
 export function getModuleActionParams(moduleName, actionName, options) {
     const { roles } = options ?? {};
     const params = [];
-    const action = getModuleAction(moduleName, actionName);
+    const action = getModuleAction(moduleName, actionName, options);
     if (!action) {
         return [];
     }
@@ -98,18 +107,23 @@ export function getModuleActionParams(moduleName, actionName, options) {
  * 顺序与模块写入注册表的顺序一致；包括内置模块和通过 {@link defineModules} 追加的用户模块。
  *
  * @returns 模块名数组（保留原始大小写）。
+ * @param options - 可选版本过滤，仅保留含有支持动作的模块。
  */
-export function getModuleNames() {
-    return getModulesState().map((module) => module.name);
+export function getModuleNames(options = {}) {
+    const version = options.version === undefined ? undefined : parseZentaoVersion(options.version);
+    return getModulesState()
+        .filter(module => !version || module.actions.some(action => supportsZentaoVersion(version, action.minVersion)))
+        .map(module => module.name);
 }
 /**
  * 判断模块名是否已注册。
  *
  * @param moduleName - 模块名；匹配大小写不敏感。
+ * @param options - 可选版本过滤。
  * @returns 已注册返回 `true`，否则 `false`。
  */
-export function isModuleName(moduleName) {
-    return getModuleMapState().has(moduleName.toLowerCase());
+export function isModuleName(moduleName, options) {
+    return getModule(moduleName, options) !== undefined;
 }
 /**
  * 获取对象属性。

package/dist/modules/registry-store.js

@@ -1,4 +1,5 @@
 import { ZentaoError } from '../misc/errors.js';
+import { validateMinVersion } from '../misc/zentao-version.js';
 import { isRecord } from '../utils/object.js';
 import { BUILTIN_MODULES } from './generated.js';
 // 动作类型到 HTTP 方法 / 结果形态的默认推导表：当动作未显式声明 method / resultType 时按 type 补齐。
@@ -99,6 +100,7 @@ export function normalizeAction(action) {
     return action;
 }
 export function freezeAction(action) {
+    validateAction(action);
     return deepFreeze(normalizeAction(action));
 }
 export function freezeModule(module) {
@@ -146,6 +148,7 @@ export function validateAction(action) {
     if (!action || typeof action.name !== 'string' || typeof action.path !== 'string') {
         throw new ZentaoError('E_INVALID_ACTION_DEFINITION');
     }
+    validateMinVersion(action.minVersion);
     // method / resultType 可省略（由 normalizeAction 按 type 推导），但显式给出时必须是字符串。
     if (action.method !== undefined && typeof action.method !== 'string') {
         throw new ZentaoError('E_INVALID_ACTION_DEFINITION');
@@ -153,6 +156,9 @@ export function validateAction(action) {
     if (action.resultType !== undefined && typeof action.resultType !== 'string') {
         throw new ZentaoError('E_INVALID_ACTION_DEFINITION');
     }
+    if (action.request !== undefined && typeof action.request !== 'function') {
+        throw new ZentaoError('E_INVALID_ACTION_DEFINITION');
+    }
 }
 /** 当前运行时注册表中的模块数组（define 侧原地修改，query 侧只读）。 */
 export function getModulesState() {

package/dist/profiles/file-lock.d.ts

@@ -0,0 +1,6 @@
+/**
+ * 在同一主机的本地文件系统上保护 profile 的 read-modify-write。
+ * 仅回收已确认退出的本机进程；不以锁的年龄判断进程是否仍在写入。
+ * @internal
+ */
+export declare function withProfileFileLock<T>(file: string, operation: () => Promise<T>, timeoutMs?: number): Promise<T>;

package/dist/profiles/file-lock.js

@@ -0,0 +1,127 @@
+import { ZentaoError } from '../misc/errors.js';
+// 间接导入，避免浏览器打包器解析 Node 内置模块。
+function importNodeModule(specifier) {
+    return import(specifier);
+}
+/**
+ * 在同一主机的本地文件系统上保护 profile 的 read-modify-write。
+ * 仅回收已确认退出的本机进程；不以锁的年龄判断进程是否仍在写入。
+ * @internal
+ */
+export async function withProfileFileLock(file, operation, timeoutMs = 5000) {
+    const [fs, path, os, crypto] = await Promise.all([
+        importNodeModule('node:fs/promises'),
+        importNodeModule('node:path'),
+        importNodeModule('node:os'),
+        importNodeModule('node:crypto'),
+    ]);
+    await fs.mkdir(path.dirname(file), { recursive: true, mode: 0o700 });
+    const directory = await fs.realpath(path.dirname(file));
+    const lock = path.join(directory, `${path.basename(file)}.lock`);
+    const ownerName = `${process.pid}-${crypto.randomUUID()}.json`;
+    const candidate = `${lock}.${ownerName}`;
+    const hostname = os.hostname();
+    async function removeOwner(name) {
+        try {
+            await fs.unlink(path.join(lock, name));
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                return;
+            throw error;
+        }
+        try {
+            // 迟到的释放者/回收者不能删除后继持有者的非空目录。
+            await fs.rmdir(lock);
+        }
+        catch (error) {
+            if (!['ENOENT', 'ENOTEMPTY', 'EEXIST'].includes(error.code ?? ''))
+                throw error;
+        }
+    }
+    async function reclaimDeadOwner() {
+        try {
+            const entries = await fs.readdir(lock, { withFileTypes: true });
+            if (entries.length !== 1 || !entries[0].isFile())
+                return;
+            const name = entries[0].name;
+            if (!/^[1-9]\d*-[\da-f]{8}-(?:[\da-f]{4}-){3}[\da-f]{12}\.json$/.test(name))
+                return;
+            let owner;
+            try {
+                owner = JSON.parse(await fs.readFile(path.join(lock, name), 'utf8'));
+            }
+            catch (error) {
+                if (error instanceof SyntaxError)
+                    return;
+                throw error;
+            }
+            if (!owner || typeof owner.pid !== 'number' || !Number.isSafeInteger(owner.pid)
+                || owner.pid <= 0 || !name.startsWith(`${owner.pid}-`) || owner.hostname !== hostname)
+                return;
+            try {
+                process.kill(owner.pid, 0);
+            }
+            catch (error) {
+                if (error.code === 'ESRCH')
+                    await removeOwner(name);
+                // EPERM 或未知错误都不能证明进程已退出。
+            }
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+        }
+    }
+    await fs.mkdir(candidate, { mode: 0o700 });
+    let acquired = false;
+    try {
+        await fs.writeFile(path.join(candidate, ownerName), JSON.stringify({ pid: process.pid, hostname }), {
+            flag: 'wx', mode: 0o600,
+        });
+        const started = performance.now();
+        while (performance.now() - started < timeoutMs) {
+            try {
+                // 先准备非空目录再原子 rename，不留下“已有锁但尚无 owner”的窗口。
+                await fs.rename(candidate, lock);
+                acquired = true;
+                break;
+            }
+            catch (error) {
+                const code = error.code;
+                if (code === 'EPERM') {
+                    // Windows 对已有目录可能返回 EPERM；没有目标目录时保留真实权限错误。
+                    const existing = await fs.stat(lock).catch(statError => {
+                        if (statError.code === 'ENOENT')
+                            return undefined;
+                        throw statError;
+                    });
+                    if (!existing?.isDirectory())
+                        throw error;
+                }
+                else if (code !== 'EEXIST' && code !== 'ENOTEMPTY') {
+                    throw error;
+                }
+                await reclaimDeadOwner();
+                const remaining = timeoutMs - (performance.now() - started);
+                if (remaining > 0) {
+                    await new Promise(resolve => setTimeout(resolve, Math.min(remaining, 25 + Math.random() * 25)));
+                }
+            }
+        }
+        if (!acquired) {
+            throw new ZentaoError('E_PROFILE_STORAGE_UNAVAILABLE', undefined, new Error('Timed out waiting for the profile file lock.'));
+        }
+        try {
+            return await operation();
+        }
+        finally {
+            await removeOwner(ownerName);
+        }
+    }
+    finally {
+        // 此候选目录只属于本次调用；固定锁目录绝不能递归删除。
+        if (!acquired)
+            await fs.rm(candidate, { recursive: true, force: true });
+    }
+}

package/dist/profiles/index.d.ts

@@ -1,4 +1,4 @@
-import type { ZentaoProfile, ZentaoProfileRecord } from '../types/index.js';
+import type { ServerConfig, ZentaoProfile, ZentaoProfileRecord } from '../types/index.js';
 /**
  * 浏览器环境下用于在 `localStorage` 中保存 profile 数据的 key。
  *
@@ -23,7 +23,7 @@ export declare function getProfileKey(profile: Pick<ZentaoProfile, 'account' | '
  * 读取过程不会写回存储；存储中无法解析的条目会被静默忽略，不会影响其余 profile。
  *
  * @returns 当前存储中的所有 profile（带 `key` 字段），文件不存在时返回空数组。
- * @throws {ZentaoError} `E_PROFILE_STORAGE_INVALID`（存储内容不是合法 JSON）或
+ * @throws {ZentaoError} `E_PROFILE_STORAGE_INVALID`（存储内容不是合法 JSON 或根结构不合法）或
  *   `E_PROFILE_STORAGE_UNAVAILABLE`（运行时无法访问存储）。
  */
 export declare function getAllProfiles(): Promise<ZentaoProfileRecord[]>;
@@ -35,13 +35,16 @@ export declare function getAllProfiles(): Promise<ZentaoProfileRecord[]>;
  * @throws {ZentaoError} `E_PROFILE_STORAGE_INVALID` / `E_PROFILE_STORAGE_UNAVAILABLE`。
  */
 export declare function getProfile(profileKey?: string): Promise<ZentaoProfileRecord | undefined>;
+/** 只读恢复与账号切换共用相同的 key 解析和错误语义。 @internal */
+export declare function getProfileOrThrow(profileKey?: string): Promise<ZentaoProfileRecord>;
 /**
  * 添加或覆盖一个本地 profile，并把它设置为当前使用的 profile。
  *
  * 行为细节：
  * - 同 key（`account@server`）已存在时会**整体覆盖**而非合并字段。
  * - 写入时会自动补齐 `loginTime` 与 `lastUsedTime`（若调用方未提供则使用当前 ISO 时间）。
- * - 操作通过进程内串行锁保护 read-modify-write，避免并发调用导致的 lost update；跨进程并发不在保证范围。
+ * - Node.js 通过文件锁保护同主机本地文件系统的 read-modify-write；浏览器在支持 Web Locks 时保护同源上下文，其他环境仅保证实例内串行。
+ * - 跨进程或上下文等待锁超过约 5 秒时抛出存储不可用错误，不修改 profile 数据。
  * - 实际写入使用临时文件 + `rename` 的原子方式，并将文件与目录权限收紧到 `0600`/`0700`（Node.js 下）。
  *
  * @param profile - 要写入的 profile，必须至少包含 `server`、`account`、`token`。
@@ -50,10 +53,14 @@ export declare function getProfile(profileKey?: string): Promise<ZentaoProfileRe
  *   `E_INVALID_BASE_URL`、`E_PROFILE_STORAGE_INVALID`、`E_PROFILE_STORAGE_UNAVAILABLE`。
  */
 export declare function addProfile(profile: ZentaoProfile): Promise<ZentaoProfileRecord>;
+/** 登录只更新会话字段和显式偏好，保留同账号的应用数据。 @internal */
+export declare function saveLoginProfile(profile: ZentaoProfile): Promise<ZentaoProfileRecord>;
+/** 只刷新已有 profile 的服务器配置，不切换当前账号或重建已删除的记录。 @internal */
+export declare function updateProfileServerConfig(profileKey: string, serverConfig: ServerConfig, fetchedAt: string): Promise<void>;
 /**
  * 删除指定 profile。
  *
- * 若被删除的是当前 profile，会回退为列表中最近一次写入的 profile；若已无任何 profile，
+ * 若被删除的是当前 profile，会回退为最近添加且仍保留的 profile；覆盖或切换已有记录不改变添加顺序。若已无任何 profile，
  * 当前 profile 会被清空。操作同样通过进程内串行锁保护。
  *
  * @param profileKey - 要删除的 profile key。