Metadata-Version: 2.4
Name: estrellio-repo-layout-tools
Version: 0.1.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: test
Requires-Dist: pytest>=8; extra == "test"
Dynamic: license-file

# repo_layout_tools

## Python 包发布准备

首版 `0.1.0` 正在准备，本次尚未上传 PyPI。要求 Python 3.10+，无第三方运行依赖。
在本仓根目录可以先安装：

```console
python -m pip install .
```

正式发布后可使用 `python -m pip install estrellio-repo-layout-tools==0.1.0`。

wheel 提供 `repo_path`、`host_path`、`json_config` 的现有 Python 接口；
首版不新增安装后的命令行入口，也不会安装 `scripts/` 中的 Shell/PowerShell 启动器。

路径推导仍约定目标模块位于项目的 `src/` 或 `sim/` 下。pip 安装后调用初始化
接口时应显式传入目标路径；省略目标的宿主仓自动发现依赖 vendored/submodule 布局。
部分生成的 runner 仍调用 `libs/py_env_tools/scripts/py_env.sh` 或 `.ps1`，
仅用 pip 安装两个库不能替代该布局。通过配置解析到解释器的 runner 则直接调用解释器。

详见 [使用说明](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)。
