Metadata-Version: 2.4
Name: estrellio-repo-layout-tools
Version: 0.2.0
Summary: AutoScripts repository layout helpers and runner path generation
Author: shade
License-Expression: MIT
Project-URL: Homepage, https://github.com/jiangnanqw12/repo_layout_tools
Project-URL: Repository, https://github.com/jiangnanqw12/repo_layout_tools
Project-URL: Issues, https://github.com/jiangnanqw12/repo_layout_tools/issues
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: py-env
Requires-Dist: estrellio-py-env-tools<0.3,>=0.2.0; extra == "py-env"
Provides-Extra: test
Requires-Dist: pytest>=8; extra == "test"
Dynamic: license-file

# repo_layout_tools

## Python 包安装

版本 0.2.0 提供独立 Python 包和 runner 生成命令，要求 Python 3.10+。

```console
python -m pip install "estrellio-repo-layout-tools[py-env]==0.2.0"
repo-layout-tool generate-runners src --target-platform linux --config config/py_env.json --project-dir .
```

也可通过 `python -m repo_layout_tools` 调用。配置模式使用可选的
`estrellio-py-env-tools` 依赖；显式 `--python-executable` 模式仅需本包。
新命令生成的 runner 直接调用解释器，不需要 `libs/` 目录。
旧 Python 接口和源码启动器保留兼容，但其默认 legacy 模式仍可能依赖子模块。

详见 [使用说明](docs/usage.md)、[测试说明](docs/testing.md)和
[发布说明](docs/publishing.md)。

`repo_layout_tools` 提供 AutoScripts 风格仓库的路径推导工具，包括：

- 根据 `src/.../*.py` 或 `sim/.../*.py` 模块路径推导仓库根目录
- 生成配置、日志、输出、文档和 runner 脚本路径
- 初始化 `_runner.ps1` / `_runner.sh` 包装脚本和必要目录，并跳过 `__init__.py`
- 提供跨 Windows / WSL 的 host path 归一化 helper

规范导入方式：

```python
from repo_layout_tools import host_path
from repo_layout_tools import repo_path
```

例如：

```python
host_path.normalize_host_path(r"D:\Users\shade\Downloads")
host_path.normalize_host_path("/mnt/d/Users/shade/Downloads")
```

源码仓库的 CLI 入口仍在子模块内：

- `scripts/repo_path.py`
- `scripts/repo_path.sh`
- `scripts/repo_path.ps1`

常用调用方式：

```bash
bash libs/repo_layout_tools/scripts/repo_path.sh src
```

默认初始化只生成 runner 和必要目录，不再创建 `*_local.txt`。如需创建默认 Local text 配置文件，请显式调用 `repo_path.init_config_file(...)`。

如果宿主仓想直接暴露仓库级稳定入口，可以复制安装到 `scripts/`：

```bash
bash libs/repo_layout_tools/scripts/install_minimal_repo.sh --repo-root . --force
```

这会写入：

- `scripts/repo_path.py`
- `scripts/repo_path.sh`
- `scripts/repo_path.ps1`

更细的说明见：

- `docs/usage.md`
- `docs/testing.md`

## 作为 submodule 使用时的常见操作

当这个仓库以 `libs/repo_layout_tools` 的形式被父仓引用时，需要区分两种状态：

- 父仓当前锁定的 submodule 提交
- 这个子仓自己远端分支上的最新提交

在父仓根目录下，常见操作如下：

```bash
# 查看父仓记录的 submodule 状态，以及当前指针差异
git submodule status
git diff --submodule=log -- libs/repo_layout_tools

# 把子仓切回父仓当前锁定的提交
git submodule update --init --recursive

# 把子仓切到它自己 origin/main 的最新提交
git -C libs/repo_layout_tools checkout main
git -C libs/repo_layout_tools pull --ff-only

# 把新的 submodule 指针提交回父仓
git add libs/repo_layout_tools
git commit -m "Update repo_layout_tools submodule"
```

`git submodule update --init --recursive` 不是“拉取子仓远端最新代码”，而是“检出父仓当前记录的那个提交”。执行后子仓经常会处于 detached `HEAD` 状态，这属于正常现象。

## 仓库布局约定

假设源文件是：

```text
<repo>/src/git_ops/para_notes/para_update_projects.py
```

则默认派生路径为：

- 配置文件路径：`<repo>/src/git_ops/para_notes/para_update_projects_local.txt`
- 日志文件：`<repo>/logs/git_ops/para_notes/para_update_projects.log`
- 输出文件：`<repo>/output/git_ops/para_notes/para_update_projects.txt`
- 文档文件：`<repo>/docs/git_ops/para_notes/para_update_projects.md`
- PowerShell runner：`<repo>/src/git_ops/para_notes/para_update_projects_runner.ps1`
- Bash runner：`<repo>/src/git_ops/para_notes/para_update_projects_runner.sh`

runner 统一使用 `_runner` 后缀，而不是直接复用 Python 文件名。

这些是路径推导结果；CLI 初始化不会默认创建 `*_local.txt`。

通过显式解释器解析回调生成不依赖子模块的 runner，参见[独立 runner 示例](docs/standalone-runners.md)。
