修改 meta.json 规则, 涉及version 、group 字段.

This commit is contained in:
cheney 2026-06-17 10:03:51 +08:00
parent fc81584878
commit 364efbc1c1
8 changed files with 599 additions and 136 deletions

View File

@ -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`
---

2
kit/doc/开发规范.md Normal file
View File

@ -0,0 +1,2 @@
- 每次需求修改都要同时更新文档、代码、测试代码。
- 每条测试用例都要有一个唯一编号。例如 1-1、2-20 等。

View File

@ -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`

View File

@ -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 [];
}
}

View File

@ -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);
}

View File

@ -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}`);
};

View File

@ -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", () => {});
});
}

View File

@ -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);
});
});