feat: namespace-aware install_path + design doc

Sunrisepeak · Sunrisepeak · commit a27885762c4d · 2026-05-11T08:00:40.000+08:00
Extends PR #23 with: 1. Design doc (.agents/docs/2026-05-11-namespace-field-design.md) covering the full namespace scheme: mcpplibs / mcpplibs.capi / compat, with xpkgs directory naming, migration path, and deprecation timeline. 2. package_fetcher.cppm: install_path() now supports namespace-aware directory lookup. Priority order: a. New: <namespace>-x-<shortName> (e.g. "mcpplibs-x-cmdline") b. Old: <defaultIndex>-x-<fullName> (e.g. "mcpp-index-x-mcpplibs.cmdline") c. Old short: <defaultIndex>-x-<name> (e.g. "mcpp-index-x-gtest") d. Fallback scan: any directory matching *-x-<name> This ensures both new installs (namespace-aware xpkgs paths) and pre-0.0.6 cached installs (index-prefixed paths) resolve correctly, enabling a smooth migration with no forced cache invalidation.
diff --git a/.agents/docs/2026-05-11-namespace-field-design.md b/.agents/docs/2026-05-11-namespace-field-design.md
@@ -0,0 +1,149 @@
+# Namespace Field Design — mcpp 0.0.6
+
+> 方案设计文档,指导 namespace 字段的实现和生态迁移。
+
+## 1. 动机
+
+mcpp 生态向 C++23 模块化方向发展。包索引中存在两类库:
+
+- **模块化库**(mcpplibs 生态):原生 `export module`,用 `import` 消费
+- **非模块化库**(compat):传统 C/C++ 库,通过 Form B 描述文件 + `#include` 消费
+
+需要在 namespace 层面区分这两类,让用户一眼看出某个依赖是否是模块化的,
+同时为未来"非模块化库迁移到模块化"提供清晰的升级路径。
+
+## 2. 命名空间划分
+
+| namespace | 含义 | 示例包 |
+|---|---|---|
+| `mcpplibs` | mcpplibs 生态的模块化 C++23 库 | cmdline, tinyhttps, llmapi, xpkg, templates |
+| `mcpplibs.capi` | mcpplibs 的 C API 模块化封装子集 | lua (封装 Lua C API 为 C++23 module) |
+| `compat` | 非模块化的第三方 C/C++ 库(兼容性支持,不鼓励直接使用) | gtest, mbedtls, lua(上游 C 库), ftxui |
+
+### 2.1 默认 namespace
+
+由于 xlings 的 `defaultNamespace = repo.name`(硬编码为索引仓库名 `"mcpp-index"`),
+我们采用**每个包显式指定 namespace** 的方案,不依赖默认值。
+
+### 2.2 用户 mcpp.toml 写法
+
+```toml
+# 模块化库
+[dependencies.mcpplibs]
+cmdline   = "0.0.2"
+tinyhttps = "0.2.2"
+llmapi    = "0.2.5"
+
+# C API 封装
+[dependencies.mcpplibs.capi]
+lua = "0.0.3"
+
+# 非模块化兼容库
+[dependencies.compat]
+gtest   = "1.15.2"
+mbedtls = "3.6.1"
+ftxui   = "6.1.9"
+lua     = "5.4.7"         # 上游 C 库(和 mcpplibs.capi.lua 是不同的包)
+```
+
+### 2.3 迁移路径
+
+当某个 compat 库完成模块化封装后:
+1. 在 mcpplibs 或 mcpplibs.capi 下发布新包
+2. compat 版本标记 deprecated(保留一段时间)
+3. 用户改一行依赖声明即可迁移
+
+## 3. 索引文件布局
+
+### 3.1 描述文件命名
+
+文件名使用 `<namespace>.<name>.lua` 格式:
+
+```
+pkgs/
+  c/compat.gtest.lua              namespace="compat", name="gtest"
+  c/compat.mbedtls.lua            namespace="compat", name="mbedtls"
+  c/compat.lua.lua                namespace="compat", name="lua"
+  c/compat.ftxui.lua              namespace="compat", name="ftxui"
+  m/mcpplibs.cmdline.lua          namespace="mcpplibs", name="cmdline"
+  m/mcpplibs.tinyhttps.lua        namespace="mcpplibs", name="tinyhttps"
+  m/mcpplibs.llmapi.lua           namespace="mcpplibs", name="llmapi"
+  m/mcpplibs.xpkg.lua             namespace="mcpplibs", name="xpkg"
+  m/mcpplibs.templates.lua        namespace="mcpplibs", name="templates"
+  m/mcpplibs.capi.lua.lua         namespace="mcpplibs.capi", name="lua"
+```
+
+### 3.2 描述文件格式
+
+```lua
+package = {
+    spec      = "1",
+    namespace = "compat",          -- 显式 namespace(0.0.6+)
+    name      = "gtest",           -- 短名
+    ...
+}
+```
+
+### 3.3 xpkgs 安装目录
+
+```
+<namespace>-x-<name>/<version>/
+
+compat-x-gtest/1.15.2/
+compat-x-mbedtls/3.6.1/
+compat-x-lua/5.4.7/
+compat-x-ftxui/6.1.9/
+mcpplibs-x-cmdline/0.0.2/
+mcpplibs-x-tinyhttps/0.2.2/
+mcpplibs.capi-x-lua/0.0.3/
+```
+
+## 4. mcpp 实现清单
+
+### 4.1 src/pm/compat.cppm (已完成 PR #23)
+
+- `resolve_package_name(name, ns)` — 显式 ns 优先 > 点号拆分 > 默认
+- `qualified_name(ns, short)` — 重建完整名
+- `xpkg_dir_name(index, ns, short)` — xpkgs 目录名
+
+### 4.2 src/manifest.cppm (已完成 PR #23)
+
+- `Package.namespace_` 字段
+- TOML `[package].namespace` 解析
+- `extract_xpkg_namespace()` — 从 xpkg lua 读 namespace
+
+### 4.3 src/pm/package_fetcher.cppm (待更新)
+
+`install_path()` 查找逻辑需要同时支持:
+- 新路径: `<namespace>-x-<name>`(如 `compat-x-gtest`)
+- 老路径: `<defaultIndex>-x-<qualifiedName>`(如 `mcpp-index-x-gtest`)
+
+### 4.4 src/cli.cppm (已完成 PR #23)
+
+- dep 名称匹配走 compat 模块
+- lua namespace 传播到 manifest
+
+## 5. 向后兼容
+
+### 5.1 compat.cppm 的三条规则
+
+1. 有 `namespace` 字段 → 直接用(新路径)
+2. `name` 带点号 → 按首个点拆分(老路径,deprecated in 1.0.0)
+3. 纯短名 → 走 `install_path` 的 fallback 扫描
+
+### 5.2 install_path 双路查找
+
+```
+查 <xpkgs>/<namespace>-x-<name>/<version>/      ← 新路径
+查 <xpkgs>/<defaultIndex>-x-<qualifiedName>/<version>/  ← 老路径 fallback
+```
+
+先找到哪个用哪个。新安装的包走新路径,老缓存继续能用。
+
+## 6. 弃用时间线
+
+| 版本 | 变化 |
+|---|---|
+| 0.0.6 | namespace 字段支持 + 双路 install_path |
+| 0.1.0 | mcpp-index 全面迁移到显式 namespace |
+| 1.0.0 | 移除 name 嵌点的 compat 拆分逻辑 |
diff --git a/src/pm/package_fetcher.cppm b/src/pm/package_fetcher.cppm
@@ -744,35 +744,71 @@ Fetcher::resolve_xpkg_path(std::string_view target,
 std::optional<std::filesystem::path>
 Fetcher::install_path(std::string_view name, std::string_view version) const
 {
-    // M6.x: install_path now ALWAYS returns the verdir (untouched extract
-    // root). Layout discrimination is done by the caller via the xpkg.lua's
+    // M6.x: install_path returns the verdir (untouched extract root).
+    // Layout discrimination is done by the caller via the xpkg.lua's
     // `mcpp = "<glob path>"` (Form A pointer) or `mcpp = { ... }` (Form B
     // inline) field — no more "find mcpp.toml subdir / unique subdir" magic.
-    // Caller resolves further nested paths via glob.
+    //
+    // 0.0.6+: namespace-aware lookup. xlings stores packages at
+    //     <xpkgs>/<namespace>-x-<shortName>/<version>/
+    // The `name` argument may be either a qualified name
+    // ("mcpplibs.cmdline") or a short name ("cmdline"). We try
+    // multiple candidate prefixes to handle both old and new layouts.
     auto base = cfg_.xlingsHome() / "data" / "xpkgs";
     if (!std::filesystem::exists(base)) return std::nullopt;
 
-    auto try_namespaced = [&](std::string_view prefix) -> std::optional<std::filesystem::path> {
-        auto verdir = base
-                    / std::format("{}-x-{}", prefix, name)
-                    / std::string(version);
+    auto try_dir = [&](std::string_view dirName) -> std::optional<std::filesystem::path> {
+        auto verdir = base / std::string(dirName) / std::string(version);
         return std::filesystem::exists(verdir)
             ? std::optional<std::filesystem::path>{verdir}
             : std::nullopt;
     };
 
-    // 1. Try the configured default index first (fast path).
-    if (auto p = try_namespaced(cfg_.defaultIndex)) return *p;
+    // Split qualified name into (namespace, shortName) for new-style lookup.
+    // "mcpplibs.cmdline" → ("mcpplibs", "cmdline")
+    // "gtest"            → ("", "gtest")
+    std::string ns, shortName;
+    auto dot = name.find('.');
+    if (dot != std::string_view::npos) {
+        ns        = std::string(name.substr(0, dot));
+        shortName = std::string(name.substr(dot + 1));
+    } else {
+        shortName = std::string(name);
+    }
+
+    // Priority order:
+    //   1. New namespace-aware: <ns>-x-<shortName> (e.g. "mcpplibs-x-cmdline")
+    //   2. Old index-prefixed: <defaultIndex>-x-<fullName> (e.g. "mcpp-index-x-mcpplibs.cmdline")
+    //   3. Old index-prefixed short: <defaultIndex>-x-<name> (e.g. "mcpp-index-x-gtest")
+    //   4. Fallback scan: any <*>-x-<name> or <*>-x-<shortName>
+
+    // 1. New namespace-aware path (0.0.6+)
+    if (!ns.empty()) {
+        if (auto p = try_dir(std::format("{}-x-{}", ns, shortName))) return *p;
+    }
 
-    // 2. Fall back: scan every xpkgs/<index>-x-<name> for a match.
+    // 2. Old index-prefixed path (compat with pre-0.0.6 installs)
+    if (auto p = try_dir(std::format("{}-x-{}", cfg_.defaultIndex, name))) return *p;
+
+    // 3. Short name with default index (bare "gtest" → "mcpp-index-x-gtest")
+    if (!shortName.empty() && shortName != name) {
+        if (auto p = try_dir(std::format("{}-x-{}", cfg_.defaultIndex, shortName))) return *p;
+    }
+
+    // 4. Fallback scan: walk xpkgs/ for any directory ending with -x-<name>
+    //    or -x-<shortName>.
     std::error_code ec;
-    std::string suffix = std::format("-x-{}", name);
+    std::string suffix1 = std::format("-x-{}", name);
+    std::string suffix2 = shortName.empty() ? "" : std::format("-x-{}", shortName);
     for (auto& entry : std::filesystem::directory_iterator(base, ec)) {
         if (!entry.is_directory()) continue;
         auto dirname = entry.path().filename().string();
-        if (!dirname.ends_with(suffix)) continue;
-        auto idx = dirname.substr(0, dirname.size() - suffix.size());
-        if (auto p = try_namespaced(idx)) return *p;
+        if (dirname.ends_with(suffix1)) {
+            if (auto p = try_dir(dirname)) return *p;
+        }
+        if (!suffix2.empty() && dirname.ends_with(suffix2)) {
+            if (auto p = try_dir(dirname)) return *p;
+        }
     }
     return std::nullopt;
 }
