From 364efbc1c135af88963bedb2e9080e349d831b12 Mon Sep 17 00:00:00 2001 From: cheney Date: Wed, 17 Jun 2026 10:03:51 +0800 Subject: [PATCH] =?UTF-8?q?=E4=BF=AE=E6=94=B9=20meta.json=20=E8=A7=84?= =?UTF-8?q?=E5=88=99,=20=E6=B6=89=E5=8F=8Aversion=20=E3=80=81group=20?= =?UTF-8?q?=E5=AD=97=E6=AE=B5.?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- kit/doc/kit remote 仓库格式设计.md | 41 ++--- kit/doc/开发规范.md | 2 + kit/doc/远程模块管理命令.md | 15 ++ kit/src/remote/index.js | 91 +++++----- kit/src/remote/install.js | 9 +- kit/src/remote/publish.js | 82 ++++++--- kit/test/remote_manu_test.js | 260 +++++++++++++++++++++++++++++ kit/test/remote_test.js | 235 +++++++++++++++++++++----- 8 files changed, 599 insertions(+), 136 deletions(-) create mode 100644 kit/doc/开发规范.md create mode 100644 kit/test/remote_manu_test.js diff --git a/kit/doc/kit remote 仓库格式设计.md b/kit/doc/kit remote 仓库格式设计.md index d964b1b..fc58b5e 100644 --- a/kit/doc/kit remote 仓库格式设计.md +++ b/kit/doc/kit remote 仓库格式设计.md @@ -1,4 +1,4 @@ -- 基于 webdav 协议访问。包括**远程仓库存储方案**（基于 WebDAV 协议）与**本地客户端存储方案**。 +- 基于 webdav 协议访问。包括**远程仓库存储方案**（基于 WebDAV 协议）与**本地客户端存储方案**。 - 支持存储多种操作系统（Linux、Windows）、多种架构（X86、aarch64） - 支持记录官网地址，方便定期从官网拉取新版本存储。 @@ -20,21 +20,23 @@ ``` /repo/ # WebDAV 服务暴露的根路径 - └─ {project-id}/ # 项目目录（唯一标识） - ├─ metadata.json # 项目级元数据文件 - └─ {semver}/ # 版本目录（如 1.2.3 或 v1.2.3） - ├─ version.json # 版本级元数据文件（推荐） - ├─ any/any/ # 平台无关文件目录（保留字） - │ └─ ... # 单文件或压缩包 - ├─ {os}/ # 操作系统（如 linux, windows, darwin） - │ └─ {arch}/ # 架构（如 x86_64, aarch64） - │ └─ ... # 具体二进制文件或压缩包 - └─ ... + └─ {group}/ # 分组目录，默认 /modules；空值等同 / + └─ {project-id}/ # 项目目录（唯一标识），实际路径为 group/id + ├─ metadata.json # 项目级元数据文件 + └─ {version}/ # 版本目录（如 1.0、1.1、2.0） + ├─ version.json # 版本级元数据文件（推荐） + ├─ any/any/ # 平台无关文件目录（保留字） + │ └─ ... # 单文件或压缩包 + ├─ {os}/ # 操作系统（如 linux, windows, darwin） + │ └─ {arch}/ # 架构（如 x86_64, aarch64） + │ └─ ... # 具体二进制文件或压缩包 + └─ ... ``` #### 2.1 命名规则 -- `project-id`：小写字母、数字、连字符（-），长度 ≤ 64。 -- `semver`：符合 [Semantic Versioning 2.0]( 的版本号，推荐不含 `v` 前缀。 +- `project-id`：来自项目 `meta.json` 中的唯一 `id`，小写字母、数字、连字符（-），长度 ≤ 64。 +- `group`：来自项目 `meta.json`，默认 `/modules`；空字符串等同 `/`；支持 `/docker`、`/tmpls`、`/docker/net` 等子路径。 +- `version`：来自项目 `meta.json` 的 `version`；若为空，发布时根据远程 `metadata.json.version` 尾数 +1，远程不存在时初始为 `1.0`。 - `os` 与 `arch` 使用标准化名称（见下表），`any` 为保留字，表示任意平台。 | 操作系统 | 标准名称 | 架构 | 标准名称 | @@ -58,12 +60,11 @@ **字段说明**： | 字段名 | 类型 | 必选 | 说明 | -| ------------------ | ----------------- | --- | ----------------- | | `project_id` | string | 是 | 项目唯一标识，与目录名相同 | +| `group` | string | 否 | 仓库分组路径，默认 `/modules`，空值等同 `/` | | `official_url` | string | 是 | 项目官网地址（用于定期拉取新版本） | | `description` | string | 否 | 项目简述 | -| `latest_version` | string | 是 | 仓库中已存储的最新版本号 | -| `versions` | array of strings | 是 | 仓库中已存储的所有版本号列表 | +| `version` | string | 是 | 当前远程最新版本号；不再使用 `versions` 数组 | | `last_fetch_check` | string (ISO 8601) | 否 | 上次检查官网更新的时间戳 | | `fetch_rules` | array of objects | 否 | 自动拉取时的匹配规则（见 3.3） | | `extra` | object | 否 | 扩展字段 | @@ -72,10 +73,10 @@ ```json { "project_id": "myapp", + "group": "/modules", "official_url": "", "description": "An example tool", - "latest_version": "1.2.1", - "versions": ["1.0.0", "1.2.0", "1.2.1"], + "version": "1.2", "last_fetch_check": "2026-06-15T12:00:00Z", "fetch_rules": [...], "extra": { "license": "Apache-2.0" } @@ -207,9 +208,9 @@ 2. 访问 `official_url`，获取所有可用版本列表及最新版本。 3. 对比已存储版本，找出缺失的新版本。 4. 对于每个新版本，根据 `fetch_rules`（或内置逻辑）匹配下载 URL，下载对应的二进制/压缩包。 -5. 按 `os` / `arch` / `any` 规则存放到 `{project-id}/{version}/{os}/{arch}/` 下。 +5. 按 `os` / `arch` / `any` 规则存放到 `{group}/{project-id}/{version}/{os}/{arch}/` 下。 6. 计算文件哈希，生成或更新该版本的 `version.json`。 -7. 更新项目级 `metadata.json`（`versions`、`latest_version`、`last_fetch_check`）。 +7. 更新项目级 `metadata.json`（`version`、`group`、`last_fetch_check`），不再写入 `versions`。 --- diff --git a/kit/doc/开发规范.md b/kit/doc/开发规范.md new file mode 100644 index 0000000..a7e280f --- /dev/null +++ b/kit/doc/开发规范.md @@ -0,0 +1,2 @@ +- 每次需求修改都要同时更新文档、代码、测试代码。 +- 每条测试用例都要有一个唯一编号。例如 1-1、2-20 等。 \ No newline at end of file diff --git a/kit/doc/远程模块管理命令.md b/kit/doc/远程模块管理命令.md index e7b755b..e5acfd8 100644 --- a/kit/doc/远程模块管理命令.md +++ b/kit/doc/远程模块管理命令.md @@ -25,3 +25,18 @@ rollback myapp # 删除模块 remove myapp ``` + +## 发布规则 + +项目 `meta.json` 支持 `group` 字段： + +- 默认值为 `/modules`。 +- 空字符串等同于 `/`。 +- 可配置为 `/docker`、`/tmpls` 等一级路径，也可配置为 `/docker/net` 等子路径。 +- 远程仓库整体上传路径为 `group/id`，其中 `id` 是项目唯一标识。 + +项目 `meta.json` 只使用 `version` 字段，不再使用 `versions`： + +- `version` 有值时，按该版本上传；上传前检查远程 `group/id/version` 是否存在，已存在则报错。 +- `version` 为空时，先读取远程 `group/id/metadata.json` 中的 `version`，将尾数 +1 后上传。 +- 远程没有版本信息时，初始版本号为 `1.0`。 diff --git a/kit/src/remote/index.js b/kit/src/remote/index.js index c081668..3c89082 100644 --- a/kit/src/remote/index.js +++ b/kit/src/remote/index.js @@ -12,7 +12,15 @@ function normalizeRemotePath(value) { if (!value || value === "/") { return "/"; } - return path.posix.normalize("/" + String(value).replace(/\\/g, "/")).replace(/\/+$|^$/g, "") || "/"; + return path.posix.normalize("/" + String(value).replace(/\\/g, "/")).replace(/\/+$/g, "") || "/"; +} + +function normalizeGroup(group) { + return normalizeRemotePath(group == null ? "/modules" : group); +} + +function joinRemote(...items) { + return normalizeRemotePath(items.filter((item) => item !== undefined && item !== null && item !== "").join("/")); } function normalizeOs(value) { @@ -136,7 +144,8 @@ module.exports = class Remote { } async list(projectId) { - const state = this.getInstallState(projectId); + const parsed = this.parseProjectVersion(projectId); + const state = this.getInstallState(parsed.projectId); for (const version of state.installed_versions) { const current = version === state.current_version ? "*" : " "; $logger.info(`${current} ${version}${current === "*" ? " (current)" : ""}`); @@ -150,14 +159,15 @@ module.exports = class Remote { } async rollback(projectId) { - const state = this.getInstallState(projectId); + const parsed = this.parseProjectVersion(projectId); + const state = this.getInstallState(parsed.projectId); const history = [...state.history].reverse(); const current = state.current_version; const previous = history.find((item) => item.version && item.version !== current && state.installed_versions.includes(item.version)); if (!previous) { - throw new Error(`没有可回滚版本 ${projectId}`); + throw new Error(`没有可回滚版本 ${parsed.projectId}`); } - return this.activate(projectId, previous.version, "rollback"); + return this.activate(parsed.projectId, previous.version, "rollback"); } async remove(projectVersion) { @@ -183,10 +193,15 @@ module.exports = class Remote { parseProjectVersion(value) { const text = String(value || "kit"); const index = text.lastIndexOf("@"); - if (index <= 0) { - return { projectId: text, version: undefined }; + const target = index <= 0 ? text : text.substring(0, index); + const version = index <= 0 ? undefined : text.substring(index + 1); + if (target.startsWith("/")) { + const normalized = normalizeRemotePath(target); + const projectId = path.posix.basename(normalized); + const group = normalizeGroup(path.posix.dirname(normalized)); + return { projectId, version, group }; } - return { projectId: text.substring(0, index), version: text.substring(index + 1) }; + return { projectId: target, version, group: "/modules" }; } getLocalModuleRoot(projectId) { @@ -255,6 +270,10 @@ module.exports = class Remote { ]; } + getRemoteProjectRoot(projectId, group = "/modules") { + return joinRemote(normalizeGroup(group), projectId); + } + async ensureDir(remotePath) { const target = normalizeRemotePath(remotePath); if (target === "/") { @@ -299,51 +318,29 @@ module.exports = class Remote { return this.ensureDir(folder); } - async wGetModuleInfo(projectId) { - return this.getProjectMetadata(projectId); + async wGetModuleInfo(projectId, group = "/modules") { + return this.getProjectMetadata(projectId, group); } - async getProjectMetadata(projectId) { - const metadata = await this.getJson(`/${projectId}/metadata.json`, undefined); + async getProjectMetadata(projectId, group = "/modules") { + const metadata = await this.getJson(joinRemote(this.getRemoteProjectRoot(projectId, group), "metadata.json"), undefined); + if (metadata) { + metadata.group = normalizeGroup(metadata.group == null ? group : metadata.group); + return metadata; + } + throw new Error(`远程模块不存在 ${normalizeGroup(group)}/${projectId}`); + } + + async getVersionMetadata(projectId, version, group = "/modules") { + const metadata = await this.getJson(joinRemote(this.getRemoteProjectRoot(projectId, group), version, "version.json"), undefined); if (metadata) { return metadata; } - - const legacy = await this.getJson(`/modules/${projectId}/meta.json`, undefined); - if (legacy) { - return { - project_id: legacy.id || projectId, - description: legacy.desc || legacy.name || "", - latest_version: legacy.latest && legacy.latest.version, - versions: (legacy.versions || []).map((item) => item.version || item), - extra: legacy - }; - } - throw new Error(`远程模块不存在 ${projectId}`); + throw new Error(`远程版本不存在 ${normalizeGroup(group)}/${projectId}@${version}`); } - async getVersionMetadata(projectId, version) { - const metadata = await this.getJson(`/${projectId}/${version}/version.json`, undefined); - if (metadata) { - return metadata; - } - - const project = await this.getProjectMetadata(projectId); - const legacyVersion = project.extra && project.extra.versions && project.extra.versions.find((item) => (item.version || item) === version); - if (legacyVersion && legacyVersion.dist) { - return { - version, - artifacts: legacyVersion.dist.map((dist) => ({ - path: `${normalizeOs(dist.os)}/${normalizeArch(dist.platform)}/${dist.filename}`, - type: "executable" - })) - }; - } - throw new Error(`远程版本不存在 ${projectId}@${version}`); - } - - async downloadArtifact(projectId, version, artifact, versionDir) { - const remotePath = `/${projectId}/${version}/${artifact.path}`; + async downloadArtifact(projectId, version, artifact, versionDir, group = "/modules") { + const remotePath = joinRemote(this.getRemoteProjectRoot(projectId, group), version, artifact.path); const localPath = path.resolve(versionDir, artifact.path); await this.wDownload(remotePath, localPath); return localPath; @@ -362,5 +359,3 @@ module.exports = class Remote { return []; } } - - diff --git a/kit/src/remote/install.js b/kit/src/remote/install.js index c8b0b07..a653d89 100644 --- a/kit/src/remote/install.js +++ b/kit/src/remote/install.js @@ -50,13 +50,14 @@ function unpackArtifact(artifact, localPath, versionDir) { module.exports = async function install(remote, id) { const parsed = remote.parseProjectVersion(id || "kit"); const projectId = parsed.projectId; - const project = await remote.getProjectMetadata(projectId); - const version = parsed.version || project.latest_version; + const group = parsed.group || "/modules"; + const project = await remote.getProjectMetadata(projectId, group); + const version = parsed.version || project.version; if (!version) { throw new Error(`远程模块没有可安装版本 ${projectId}`); } - const versionMeta = await remote.getVersionMetadata(projectId, version); + const versionMeta = await remote.getVersionMetadata(projectId, version, project.group || group); const artifacts = remote.getMatchingArtifacts(versionMeta); if (artifacts.length < 1) { throw new Error(`没有匹配当前平台的文件 ${projectId}@${version}`); @@ -67,7 +68,7 @@ module.exports = async function install(remote, id) { fs.mkdirSync(versionDir, { recursive: true }); for (const artifact of artifacts) { - const localPath = await remote.downloadArtifact(projectId, version, artifact, versionDir); + const localPath = await remote.downloadArtifact(projectId, version, artifact, versionDir, project.group || group); verifyChecksum(localPath, artifact.checksum || (versionMeta.checksums && versionMeta.checksums[artifact.path])); unpackArtifact(artifact, localPath, versionDir); } diff --git a/kit/src/remote/publish.js b/kit/src/remote/publish.js index fb4f947..46a5a14 100644 --- a/kit/src/remote/publish.js +++ b/kit/src/remote/publish.js @@ -7,6 +7,21 @@ function now() { return new Date().toISOString(); } +function normalizeRemotePath(value) { + if (!value || value === "/") { + return "/"; + } + return path.posix.normalize("/" + String(value).replace(/\\/g, "/")).replace(/\/+$/g, "") || "/"; +} + +function normalizeGroup(group) { + return normalizeRemotePath(group == null ? "/modules" : group); +} + +function joinRemote(...items) { + return normalizeRemotePath(items.filter((item) => item !== undefined && item !== null && item !== "").join("/")); +} + function normalizeOs(value) { const name = String(value || "any").toLowerCase(); if (["windows_nt", "win32", "windows"].includes(name)) { @@ -70,16 +85,6 @@ function archiveFormat(filePath) { return undefined; } -function buildVersion(localMeta) { - if (localMeta.release_version) { - return localMeta.release_version; - } - if (localMeta.version) { - return localMeta.version; - } - return new Date().toISOString().replace(/[-:TZ.]/g, "").slice(0, 14); -} - function readLocalMeta(localFile) { const base = localFile ? path.resolve(localFile) : process.cwd(); const metaFile = fs.statSync(base).isDirectory() ? path.resolve(base, "meta.json") : path.resolve(process.cwd(), "meta.json"); @@ -93,7 +98,8 @@ function readLocalMeta(localFile) { return { id: path.basename(localFile, path.extname(localFile)).toLowerCase(), - version: buildVersion({}), + group: "/modules", + version: "", desc: "", dist: [{ path: localFile, os: "any", platform: "any", filename: path.basename(localFile) }] }; @@ -123,6 +129,34 @@ function buildArtifacts(localMeta) { }); } +function bumpTailVersion(version) { + const text = String(version || "").trim(); + if (!text) { + return "1.0"; + } + const match = text.match(/^(.*?)(\d+)$/); + if (!match) { + return `${text}.1`; + } + return `${match[1]}${Number(match[2]) + 1}`; +} + +async function resolveVersion(remote, projectRoot, localMeta) { + const explicitVersion = String(localMeta.version || "").trim(); + if (explicitVersion) { + if (await remote.client.exists(joinRemote(projectRoot, explicitVersion))) { + throw new Error(`远程版本已存在 ${projectRoot}@${explicitVersion}`); + } + return explicitVersion; + } + + const metadata = await remote.getJson(joinRemote(projectRoot, "metadata.json"), undefined); + if (metadata && metadata.version) { + return bumpTailVersion(metadata.version); + } + return "1.0"; +} + module.exports = async function publish(remote, localFile, remotePath) { if (remotePath) { const target = path.posix.resolve("/", remotePath.replace(/\\/g, "/")); @@ -137,9 +171,11 @@ module.exports = async function publish(remote, localFile, remotePath) { throw new Error("meta.json 缺少 project_id/id/name"); } - const version = buildVersion(localMeta); + const group = normalizeGroup(localMeta.group); + const projectRoot = remote.getRemoteProjectRoot ? remote.getRemoteProjectRoot(projectId, group) : joinRemote(group, projectId); + const version = await resolveVersion(remote, projectRoot, localMeta); const artifacts = buildArtifacts(localMeta); - await remote.ensureDir(`/${projectId}/${version}`); + await remote.ensureDir(joinRemote(projectRoot, version)); const versionMeta = { version, @@ -150,27 +186,29 @@ module.exports = async function publish(remote, localFile, remotePath) { }; for (const artifact of artifacts) { - await remote.wUpload(artifact.localPath, `/${projectId}/${version}/${artifact.path}`); + await remote.wUpload(artifact.localPath, joinRemote(projectRoot, version, artifact.path)); } - await remote.putJson(`/${projectId}/${version}/version.json`, versionMeta); + await remote.putJson(joinRemote(projectRoot, version, "version.json"), versionMeta); - const metadata = await remote.getJson(`/${projectId}/metadata.json`, { + const metadata = await remote.getJson(joinRemote(projectRoot, "metadata.json"), { project_id: projectId, + group, official_url: localMeta.official_url || localMeta.vcs || "", description: localMeta.description || localMeta.desc || "", - latest_version: version, - versions: [], + version, fetch_rules: localMeta.fetch_rules || [], extra: {} }); metadata.project_id = projectId; + metadata.group = group; metadata.official_url = metadata.official_url || localMeta.official_url || localMeta.vcs || ""; metadata.description = localMeta.description || localMeta.desc || metadata.description || ""; - metadata.latest_version = version; - metadata.versions = Array.from(new Set([...(metadata.versions || []), version])); + metadata.version = version; + delete metadata.versions; + delete metadata.latest_version; metadata.extra = Object.assign({}, metadata.extra || {}, localMeta.extra || {}); - await remote.putJson(`/${projectId}/metadata.json`, metadata); - $logger.info(`文件上传成功 ${projectId}@${version}`); + await remote.putJson(joinRemote(projectRoot, "metadata.json"), metadata); + $logger.info(`文件上传成功 ${group}/${projectId}@${version}`); }; diff --git a/kit/test/remote_manu_test.js b/kit/test/remote_manu_test.js new file mode 100644 index 0000000..28992d3 --- /dev/null +++ b/kit/test/remote_manu_test.js @@ -0,0 +1,260 @@ +import { afterEach, beforeEach, describe, expect, test } from "bun:test"; +import fs from "fs"; +import os from "os"; +import path from "path"; + +const RUN_MANUAL = process.env.KIT_REMOTE_MANU_TEST === "1"; +const manualDescribe = RUN_MANUAL ? describe : describe.skip; +const manualTest = RUN_MANUAL ? test : test.skip; + +let Remote; +if (RUN_MANUAL) { + require("../src/init"); + Remote = require("../src/remote"); +} + +async function createRemote() { + const remote = new Remote(); + await remote.init(); + return remote; +} + +function writeFixtureProject(tempDir, version, content, options = {}) { + const projectId = options.id || "myapp"; + const group = options.group === undefined ? "/modules" : options.group; + const projectDir = path.resolve(tempDir, `fixture-${projectId}-${version || "auto"}-${Math.random().toString(16).slice(2)}`); + fs.mkdirSync(projectDir, { recursive: true }); + + const filePath = path.resolve(projectDir, "myapp.txt"); + fs.writeFileSync(filePath, content, "utf-8"); + + fs.writeFileSync(path.resolve(projectDir, "meta.json"), JSON.stringify({ + id: projectId, + group, + version, + desc: "test app", + official_url: "https://example.test/myapp", + dist: [ + { + path: filePath, + os: "any", + platform: "any", + filename: "myapp.txt", + type: "data" + } + ] + }, null, 4), "utf-8"); + + return projectDir; +} + +function normalizeRemotePath(value) { + if (!value || value === "/") { + return "/"; + } + return path.posix.normalize("/" + String(value).replace(/\\/g, "/")).replace(/\/+$/g, "") || "/"; +} + +function remoteProjectPath(group, projectId) { + const normalizedGroup = group === undefined ? "/modules" : normalizeRemotePath(group); + return normalizeRemotePath(path.posix.join(normalizedGroup, projectId)); +} + +async function deleteRemotePath(remote, remotePath) { + try { + if (remote.client && remote.client.deleteFile && await remote.client.exists(remotePath)) { + await remote.client.deleteFile(remotePath); + } + } catch (e) { + console.warn(`cleanup remote failed ${remotePath}: ${e.message}`); + } +} + +let tempDir; +let localStore; +let remote; +let runId; +let counter; +let projectIds; +let remoteRoots; + +beforeEach(async () => { + if (!RUN_MANUAL) { + return; + } + tempDir = fs.mkdtempSync(path.resolve(os.tmpdir(), "kit-remote-manu-test-")); + localStore = $sConfig.getLocalStorePath(); + remote = await createRemote(); + runId = `${Date.now()}-${Math.random().toString(16).slice(2)}`; + counter = 0; + projectIds = []; + remoteRoots = []; +}); + +afterEach(async () => { + if (!RUN_MANUAL) { + return; + } + for (const remoteRoot of remoteRoots.reverse()) { + await deleteRemotePath(remote, remoteRoot); + } + for (const projectId of projectIds) { + fs.rmSync(path.resolve(localStore, "modules", projectId), { recursive: true, force: true }); + } + fs.rmSync(tempDir, { recursive: true, force: true }); +}); + +function nextProjectId() { + const projectId = `myapp-${runId}-${++counter}`.toLowerCase(); + projectIds.push(projectId); + return projectId; +} + +function trackRemote(group, projectId) { + const root = remoteProjectPath(group, projectId); + remoteRoots.push(root); + return root; +} + +manualDescribe("remote module public API manual webdav", () => { + manualTest("exposes documented public methods", async () => { + expect(typeof remote.check).toBe("function"); + expect(typeof remote.publish).toBe("function"); + expect(typeof remote.install).toBe("function"); + expect(typeof remote.list).toBe("function"); + expect(typeof remote.use).toBe("function"); + expect(typeof remote.rollback).toBe("function"); + expect(typeof remote.remove).toBe("function"); + }); + + manualTest("check validates an available webdav client", async () => { + expect(await remote.check()).toBe(true); + }); + + manualTest("publish stores files under default group /modules/id", async () => { + const projectId = nextProjectId(); + trackRemote("/modules", projectId); + const projectDir = writeFixtureProject(tempDir, "1.0", "hello v1", { id: projectId }); + + await remote.publish(projectDir); + + const metadata = JSON.parse(await remote.client.getFileContents(`/modules/${projectId}/metadata.json`, { format: "text" })); + const version = JSON.parse(await remote.client.getFileContents(`/modules/${projectId}/1.0/version.json`, { format: "text" })); + const artifact = await remote.client.getFileContents(`/modules/${projectId}/1.0/any/any/myapp.txt`, { format: "text" }); + + expect(metadata.project_id).toBe(projectId); + expect(metadata.group).toBe("/modules"); + expect(metadata.version).toBe("1.0"); + expect(metadata.versions).toBeUndefined(); + expect(metadata.latest_version).toBeUndefined(); + expect(version.artifacts[0].path).toBe("any/any/myapp.txt"); + expect(artifact).toBe("hello v1"); + }, 30000); + + manualTest("publish supports custom nested group", async () => { + const projectId = nextProjectId(); + const group = `/kit-manual-test/${runId}/docker/net`; + trackRemote(group, projectId); + await remote.publish(writeFixtureProject(tempDir, "2.0", "docker net", { id: projectId, group })); + + const metadata = JSON.parse(await remote.client.getFileContents(`${group}/${projectId}/metadata.json`, { format: "text" })); + const artifact = await remote.client.getFileContents(`${group}/${projectId}/2.0/any/any/myapp.txt`, { format: "text" }); + + expect(metadata.group).toBe(group); + expect(metadata.version).toBe("2.0"); + expect(artifact).toBe("docker net"); + }, 30000); + + manualTest("empty group stores project at repository root", async () => { + const projectId = nextProjectId(); + trackRemote("", projectId); + await remote.publish(writeFixtureProject(tempDir, "1.0", "root group", { id: projectId, group: "" })); + + const metadata = JSON.parse(await remote.client.getFileContents(`/${projectId}/metadata.json`, { format: "text" })); + expect(metadata.group).toBe("/"); + expect(await remote.client.getFileContents(`/${projectId}/1.0/any/any/myapp.txt`, { format: "text" })).toBe("root group"); + }, 30000); + + manualTest("explicit version fails when remote version already exists", async () => { + const projectId = nextProjectId(); + trackRemote("/modules", projectId); + await remote.publish(writeFixtureProject(tempDir, "1.0", "hello v1", { id: projectId })); + + await expect(remote.publish(writeFixtureProject(tempDir, "1.0", "hello again", { id: projectId }))).rejects.toThrow("远程版本已存在"); + }, 30000); + + manualTest("blank version increments remote version tail or starts at 1.0", async () => { + const projectId = nextProjectId(); + trackRemote("/modules", projectId); + + await remote.publish(writeFixtureProject(tempDir, "", "first auto", { id: projectId })); + let metadata = JSON.parse(await remote.client.getFileContents(`/modules/${projectId}/metadata.json`, { format: "text" })); + expect(metadata.version).toBe("1.0"); + + await remote.publish(writeFixtureProject(tempDir, "", "second auto", { id: projectId })); + metadata = JSON.parse(await remote.client.getFileContents(`/modules/${projectId}/metadata.json`, { format: "text" })); + expect(metadata.version).toBe("1.1"); + expect(await remote.client.getFileContents(`/modules/${projectId}/1.1/any/any/myapp.txt`, { format: "text" })).toBe("second auto"); + }, 30000); + + manualTest("install downloads latest version from default group", async () => { + const projectId = nextProjectId(); + trackRemote("/modules", projectId); + await remote.publish(writeFixtureProject(tempDir, "1.0", "hello v1", { id: projectId })); + + const installed = await remote.install(projectId); + + const moduleRoot = path.resolve(localStore, "modules", projectId); + const installJson = JSON.parse(fs.readFileSync(path.resolve(moduleRoot, ".meta", "install.json"), "utf-8")); + const installedFile = fs.readFileSync(path.resolve(moduleRoot, "versions", "1.0", "any", "any", "myapp.txt"), "utf-8"); + + expect(installed).toBe("1.0"); + expect(installedFile).toBe("hello v1"); + expect(installJson.current_version).toBe("1.0"); + expect(installJson.installed_versions).toContain("1.0"); + expect(fs.existsSync(path.resolve(moduleRoot, "current"))).toBe(true); + }, 30000); + + manualTest("install can target a custom group path", async () => { + const projectId = nextProjectId(); + const group = `/kit-manual-test/${runId}/docker/net`; + trackRemote(group, projectId); + await remote.publish(writeFixtureProject(tempDir, "1.0", "docker install", { id: projectId, group })); + + const installed = await remote.install(`${group}/${projectId}`); + const installedFile = fs.readFileSync(path.resolve(localStore, "modules", projectId, "versions", "1.0", "any", "any", "myapp.txt"), "utf-8"); + + expect(installed).toBe("1.0"); + expect(installedFile).toBe("docker install"); + }, 30000); + + manualTest("list use rollback and remove manage installed versions", async () => { + const projectId = nextProjectId(); + trackRemote("/modules", projectId); + await remote.publish(writeFixtureProject(tempDir, "1.0", "hello v1", { id: projectId })); + await remote.install(projectId); + await remote.publish(writeFixtureProject(tempDir, "2.0", "hello v2", { id: projectId })); + await remote.install(projectId); + + expect(await remote.list(projectId)).toEqual(["1.0", "2.0"]); + + await remote.rollback(projectId); + let installJson = JSON.parse(fs.readFileSync(path.resolve(localStore, "modules", projectId, ".meta", "install.json"), "utf-8")); + expect(installJson.current_version).toBe("1.0"); + + await remote.use(`${projectId}@2.0`); + installJson = JSON.parse(fs.readFileSync(path.resolve(localStore, "modules", projectId, ".meta", "install.json"), "utf-8")); + expect(installJson.current_version).toBe("2.0"); + + await remote.remove(`${projectId}@1.0`); + installJson = JSON.parse(fs.readFileSync(path.resolve(localStore, "modules", projectId, ".meta", "install.json"), "utf-8")); + expect(installJson.installed_versions).toEqual(["2.0"]); + expect(fs.existsSync(path.resolve(localStore, "modules", projectId, "versions", "1.0"))).toBe(false); + }, 30000); +}); + +if (!RUN_MANUAL) { + describe("remote manual webdav tests", () => { + test.skip("set KIT_REMOTE_MANU_TEST=1 and run bun test test/remote_manu_test.js", () => {}); + }); +} diff --git a/kit/test/remote_test.js b/kit/test/remote_test.js index d8de17d..2a3e1f5 100644 --- a/kit/test/remote_test.js +++ b/kit/test/remote_test.js @@ -2,17 +2,101 @@ import fs from "fs"; import os from "os"; import path from "path"; +import { Readable, Writable } from "stream"; +import Remote from "../src/remote"; -require("../src/init") -async function createRemote() { - const Remote = require("../src/remote") - const remote = new Remote(); - await remote.init() - return remote +class MemoryWebdavClient { + constructor() { + this.files = new Map(); + this.dirs = new Set(["/"]); + } + + normalize(remotePath) { + const normalized = path.posix.normalize("/" + String(remotePath || "").replace(/\\/g, "/")); + return normalized === "/" ? "/" : normalized.replace(/\/$/, ""); + } + + async exists(remotePath) { + const key = this.normalize(remotePath); + return this.dirs.has(key) || this.files.has(key); + } + + async createDirectory(remotePath) { + const key = this.normalize(remotePath); + const parts = key.split("/").filter(Boolean); + let current = ""; + for (const part of parts) { + current += "/" + part; + this.dirs.add(current); + } + } + + async getDirectoryContents(remotePath) { + const dir = this.normalize(remotePath); + const prefix = dir === "/" ? "/" : dir + "/"; + const names = new Map(); + for (const item of [...this.dirs, ...this.files.keys()]) { + if (item === dir || !item.startsWith(prefix)) { + continue; + } + const rest = item.slice(prefix.length); + const name = rest.split("/")[0]; + names.set(name, prefix + name); + } + return [...names].map(([basename, filename]) => ({ basename, filename, type: this.dirs.has(this.normalize(filename)) ? "directory" : "file" })); + } + + async putFileContents(remotePath, content) { + const key = this.normalize(remotePath); + await this.createDirectory(path.posix.dirname(key)); + this.files.set(key, Buffer.isBuffer(content) ? content : Buffer.from(String(content))); + } + + async getFileContents(remotePath, options = {}) { + const key = this.normalize(remotePath); + if (!this.files.has(key)) { + throw new Error(`missing ${key}`); + } + const data = this.files.get(key); + return options.format === "text" ? data.toString("utf-8") : data; + } + + createWriteStream(remotePath) { + const key = this.normalize(remotePath); + const chunks = []; + const stream = new Writable({ + write(chunk, encoding, callback) { + chunks.push(Buffer.from(chunk)); + callback(); + } + }); + stream.on("finish", () => { + this.createDirectory(path.posix.dirname(key)); + this.files.set(key, Buffer.concat(chunks)); + }); + return stream; + } + + createReadStream(remotePath) { + const key = this.normalize(remotePath); + if (!this.files.has(key)) { + throw new Error(`missing ${key}`); + } + return Readable.from(this.files.get(key)); + } + + async stat(remotePath) { + const key = this.normalize(remotePath); + const data = this.files.get(key); + if (!data) { + throw new Error(`missing ${key}`); + } + return { size: data.length }; + } } -function writeFixtureProject(tempDir, version, content) { - const projectDir = path.resolve(tempDir, `fixture-${version}`); +function writeFixtureProject(tempDir, version, content, group = "/modules") { + const projectDir = path.resolve(tempDir, `fixture-${version || "auto"}-${Math.random().toString(16).slice(2)}`); fs.mkdirSync(projectDir, { recursive: true }); const filePath = path.resolve(projectDir, "myapp.txt"); @@ -20,6 +104,7 @@ function writeFixtureProject(tempDir, version, content) { fs.writeFileSync(path.resolve(projectDir, "meta.json"), JSON.stringify({ id: "myapp", + group, version, desc: "test app", official_url: "https://example.test/myapp", @@ -37,21 +122,35 @@ function writeFixtureProject(tempDir, version, content) { return projectDir; } +function createRemote() { + const remote = new Remote(); + remote.client = new MemoryWebdavClient(); + return remote; +} + let tempDir; let localStore; +let oldLogger; +let oldConfig; beforeEach(() => { - tempDir = fs.mkdtempSync(path.resolve(os.tmpdir(), "kit-remote-test")); - localStore = $sConfig.getLocalStorePath(); + tempDir = fs.mkdtempSync(path.resolve(os.tmpdir(), "kit-remote-test-")); + localStore = path.resolve(tempDir, "local-store"); + oldLogger = globalThis.$logger; + oldConfig = globalThis.$sConfig; + globalThis.$logger = { info() {}, warn() {}, error() {}, debug() {} }; + globalThis.$sConfig = { getLocalStorePath: () => localStore }; }); afterEach(() => { + globalThis.$logger = oldLogger; + globalThis.$sConfig = oldConfig; fs.rmSync(tempDir, { recursive: true, force: true }); }); describe("remote module public API", () => { - test("1-1 exposes documented public methods", async() => { - const remote = await createRemote(); + test("exposes documented public methods", () => { + const remote = createRemote(); expect(typeof remote.check).toBe("function"); expect(typeof remote.publish).toBe("function"); expect(typeof remote.install).toBe("function"); @@ -61,67 +160,119 @@ describe("remote module public API", () => { expect(typeof remote.remove).toBe("function"); }); - test("1-2 check validates an available webdav client", async () => { - const remote = await createRemote(); + test("check validates an available webdav client", async () => { + const remote = createRemote(); expect(await remote.check()).toBe(true); }); - test("1-3 publish stores metadata and version artifacts in webdav layout", async () => { - const remote = await createRemote(); - const projectDir = writeFixtureProject(tempDir, "1.0.0", "hello v1"); + test("publish stores files under default group /modules/id", async () => { + const remote = createRemote(); + const projectDir = writeFixtureProject(tempDir, "1.0", "hello v1"); await remote.publish(projectDir); - const metadata = JSON.parse(await remote.client.getFileContents("/myapp/metadata.json", { format: "text" })); - const version = JSON.parse(await remote.client.getFileContents("/myapp/1.0.0/version.json", { format: "text" })); - const artifact = await remote.client.getFileContents("/myapp/1.0.0/any/any/myapp.txt", { format: "text" }); + const metadata = JSON.parse(await remote.client.getFileContents("/modules/myapp/metadata.json", { format: "text" })); + const version = JSON.parse(await remote.client.getFileContents("/modules/myapp/1.0/version.json", { format: "text" })); + const artifact = await remote.client.getFileContents("/modules/myapp/1.0/any/any/myapp.txt", { format: "text" }); expect(metadata.project_id).toBe("myapp"); - expect(metadata.latest_version).toBe("1.0.0"); - expect(metadata.versions).toContain("1.0.0"); + expect(metadata.group).toBe("/modules"); + expect(metadata.version).toBe("1.0"); + expect(metadata.versions).toBeUndefined(); + expect(metadata.latest_version).toBeUndefined(); expect(version.artifacts[0].path).toBe("any/any/myapp.txt"); expect(artifact).toBe("hello v1"); - }, 30000); + }); - test("install downloads latest matching artifact and records local state", async () => { - const remote = await createRemote(); - const projectDir = writeFixtureProject(tempDir, "1.0.0", "hello v1"); - await remote.publish(projectDir); + test("publish supports custom nested group", async () => { + const remote = createRemote(); + await remote.publish(writeFixtureProject(tempDir, "2.0", "docker net", "/docker/net")); + + const metadata = JSON.parse(await remote.client.getFileContents("/docker/net/myapp/metadata.json", { format: "text" })); + const artifact = await remote.client.getFileContents("/docker/net/myapp/2.0/any/any/myapp.txt", { format: "text" }); + + expect(metadata.group).toBe("/docker/net"); + expect(metadata.version).toBe("2.0"); + expect(artifact).toBe("docker net"); + }); + + test("empty group stores project at repository root", async () => { + const remote = createRemote(); + await remote.publish(writeFixtureProject(tempDir, "1.0", "root group", "")); + + const metadata = JSON.parse(await remote.client.getFileContents("/myapp/metadata.json", { format: "text" })); + expect(metadata.group).toBe("/"); + expect(await remote.client.getFileContents("/myapp/1.0/any/any/myapp.txt", { format: "text" })).toBe("root group"); + }); + + test("explicit version fails when remote version already exists", async () => { + const remote = createRemote(); + await remote.publish(writeFixtureProject(tempDir, "1.0", "hello v1")); + + await expect(remote.publish(writeFixtureProject(tempDir, "1.0", "hello again"))).rejects.toThrow("远程版本已存在"); + }); + + test("blank version increments remote version tail or starts at 1.0", async () => { + const remote = createRemote(); + + await remote.publish(writeFixtureProject(tempDir, "", "first auto")); + let metadata = JSON.parse(await remote.client.getFileContents("/modules/myapp/metadata.json", { format: "text" })); + expect(metadata.version).toBe("1.0"); + + await remote.publish(writeFixtureProject(tempDir, "", "second auto")); + metadata = JSON.parse(await remote.client.getFileContents("/modules/myapp/metadata.json", { format: "text" })); + expect(metadata.version).toBe("1.1"); + expect(await remote.client.getFileContents("/modules/myapp/1.1/any/any/myapp.txt", { format: "text" })).toBe("second auto"); + }); + + test("install downloads latest version from default group", async () => { + const remote = createRemote(); + await remote.publish(writeFixtureProject(tempDir, "1.0", "hello v1")); const installed = await remote.install("myapp"); const moduleRoot = path.resolve(localStore, "modules", "myapp"); const installJson = JSON.parse(fs.readFileSync(path.resolve(moduleRoot, ".meta", "install.json"), "utf-8")); - const installedFile = fs.readFileSync(path.resolve(moduleRoot, "versions", "1.0.0", "any", "any", "myapp.txt"), "utf-8"); + const installedFile = fs.readFileSync(path.resolve(moduleRoot, "versions", "1.0", "any", "any", "myapp.txt"), "utf-8"); - expect(installed).toBe("1.0.0"); + expect(installed).toBe("1.0"); expect(installedFile).toBe("hello v1"); - expect(installJson.current_version).toBe("1.0.0"); - expect(installJson.installed_versions).toContain("1.0.0"); + expect(installJson.current_version).toBe("1.0"); + expect(installJson.installed_versions).toContain("1.0"); expect(fs.existsSync(path.resolve(moduleRoot, "current"))).toBe(true); }); + test("install can target a custom group path", async () => { + const remote = createRemote(); + await remote.publish(writeFixtureProject(tempDir, "1.0", "docker install", "/docker/net")); + + const installed = await remote.install("/docker/net/myapp"); + const installedFile = fs.readFileSync(path.resolve(localStore, "modules", "myapp", "versions", "1.0", "any", "any", "myapp.txt"), "utf-8"); + + expect(installed).toBe("1.0"); + expect(installedFile).toBe("docker install"); + }); + test("list use rollback and remove manage installed versions", async () => { - const remote = await createRemote(); - await remote.publish(writeFixtureProject(tempDir, "1.0.0", "hello v1")); + const remote = createRemote(); + await remote.publish(writeFixtureProject(tempDir, "1.0", "hello v1")); await remote.install("myapp"); - await remote.publish(writeFixtureProject(tempDir, "2.0.0", "hello v2")); + await remote.publish(writeFixtureProject(tempDir, "2.0", "hello v2")); await remote.install("myapp"); - expect(await remote.list("myapp")).toEqual(["1.0.0", "2.0.0"]); + expect(await remote.list("myapp")).toEqual(["1.0", "2.0"]); await remote.rollback("myapp"); let installJson = JSON.parse(fs.readFileSync(path.resolve(localStore, "modules", "myapp", ".meta", "install.json"), "utf-8")); - expect(installJson.current_version).toBe("1.0.0"); + expect(installJson.current_version).toBe("1.0"); - await remote.use("myapp@2.0.0"); + await remote.use("myapp@2.0"); installJson = JSON.parse(fs.readFileSync(path.resolve(localStore, "modules", "myapp", ".meta", "install.json"), "utf-8")); - expect(installJson.current_version).toBe("2.0.0"); + expect(installJson.current_version).toBe("2.0"); - await remote.remove("myapp@1.0.0"); + await remote.remove("myapp@1.0"); installJson = JSON.parse(fs.readFileSync(path.resolve(localStore, "modules", "myapp", ".meta", "install.json"), "utf-8")); - expect(installJson.installed_versions).toEqual(["2.0.0"]); - expect(fs.existsSync(path.resolve(localStore, "modules", "myapp", "versions", "1.0.0"))).toBe(false); + expect(installJson.installed_versions).toEqual(["2.0"]); + expect(fs.existsSync(path.resolve(localStore, "modules", "myapp", "versions", "1.0"))).toBe(false); }); }); -