Metadata-Version: 2.4
Name: mawflow-seed-kit
Version: 2.17.2
Summary: Canonical MAWflow Seed contract, compiler, reconciler, and project template
License-Expression: MIT
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: PyYAML>=6.0
Provides-Extra: test
Requires-Dist: pytest>=8; extra == "test"
Requires-Dist: jsonschema>=4.18; extra == "test"

# mawflow-seed-kit

`mawflow-seed-kit` 是 Seed Contract v2 的唯一可执行分发包。v2.8.0 增加通用 Agent 入口、专用适配、独立就绪检查和任务上下文导出；保留 v2.7.0 增加的脚本用途合同和可选择的 `npm run dev`：真实命令仍属于组件，当前设备只启动所选服务，未选应用不探测、不阻塞；本机选择和运行记录进入 Git 已忽略的 `.local`。v2.6 的多部署目标与 v2.5 的多子项目、共享代码源、新设备 hydrate 保持兼容。

主仓 CLI 和 Host Program 必须固定消费同一版本；项目仓库通过 `.maw/seed.lock` 记录版本、BOM 和契约指纹。

本包提供 Python API 与只读诊断命令，面向用户的组件操作由 `mawflow component ...` 暴露：

```bash
mawflow-seed-kit catalog
mawflow-seed-kit doctor /path/to/project
mawflow-seed-kit doctor credentials /path/to/project --fail-on-plaintext
```

项目创建应通过 `mawflow project init`，已有项目迁移应通过 `mawflow project adopt/upgrade` 或本地工作台执行；不要直接复制包内模板覆盖现有仓库。

迁移应用会生成仅保存在指定私有备份目录的哈希清单。需要回退时，调用 `rollback_migration(...)` 并提供迁移结果中的 `plan_key` 与精确确认串；回退前会校验当前文件仍等于迁移候选，避免覆盖迁移后的并发修改。

## 2.9.0 候选：纯项目命令

`mawflow_seed_kit.commands.cli` 与 `mawflow_seed_kit.testing` 是项目文件能力的唯一实现；主仓轻量 CLI 与 Host 共用。普通命令离线可用。升级执行须由官方入口提供在线账号授权；直接使用此模块不会默认授权升级。`project upgrade --template` 处理 package 来源模板，`--rollback` 恢复已保存的事务，Contract 迁移使用既有显式选项。

本版本是未发布候选；首发操作说明随主仓 `code/npm-cli/README.md` 维护。源码仓 Git 漂移仍沿用原有受控流程，不能用 package 升级覆盖项目。

## 开发验证依赖

安装测试可选依赖后使用 pytest 收集完整套件，避免 unittest discover 漏掉函数式回归：

```bash
python3 -m pip install -e 'packages/mawflow-seed-kit[test]'
python3 -m pytest -q tests
```

测试依赖不加入 Kit 运行时依赖；项目资源预算仍按现有串行验证入口执行。

### 模板升级元数据一致性（2.17.2）

官方 `mawflow project upgrade --template` 在预览中同时列出Seed锁与来源文件的版本和实际模板树摘要变更，确认串绑定这些字节。`seed.lock.source`与`template_source.distribution`中的version、template_version、template_tree_sha256取本次已校验模板；索引、来源身份、自定义字段和项目事实保留。两个文件沿既有事务和恢复日志写入，中断后按原回滚入口恢复，不手工改锁消除差异。

同版本也检查旧升级遗留的元数据；使用当前已安装模板即可离线修复，无需下载同版本基线。全部一致后返回up_to_date，不新建恢复事务。模板摘要反映分发模板原文，不能用派生项目替换占位符、定制后的整仓目录摘要代替。工具环境升级由控制侧负责；这不是WorkBuddy CLI接入。
