review: one parser for mcpp.toml, and a cmd.exe line cmd.exe accepts

Follow-up to the [hooks] feature. Five things the first shape got wrong, in
descending order of how loudly they fail.

1. Windows: the hook never ran. `run_shell_deadline` built the command line
   with `windows_command_from_argv({"cmd.exe","/d","/s","/c", command})`, which
   quotes every token — so the switches stopped being switches and the command
   arrived carrying a quote pair cmd.exe does not consume:

       '"echo start>>hooks.log' is not recognized as an internal or external
       command

   That is #425 one layer up (`cmd.exe /c` does not use CreateProcess argument
   quoting). A shell command now has its own host-independent shaper,
   `windows_shell_command_line` — bare switches plus the single outer pair /s
   strips — and its own tests in test_windows_command_line.cpp, which compile
   on every platform. The Windows branch is unreachable on the machines this
   is developed on; a unit test is the only thing that can fail there first.

2. `[hooks]` is a section of mcpp.toml, so mcpp.manifest parses it. The
   feature came with a second, independent reader of the same file. It cost a
   redundant parse on every build, and it reported ITS syntax errors in ITS
   vocabulary: any manifest typo, anywhere in the file, came out as
   `error: invalid hook configuration: ...` for every project whether or not
   it used hooks. `Manifest::hooks` now carries the config, unknown keys warn
   (and error under --strict) like every other section, and mcpp.hooks is left
   with the part that is policy rather than grammar.

3. A hook no longer moves mcpp's working directory. The launchers already
   carry a per-child cwd (posix_spawn_file_actions_addchdir_np,
   lpCurrentDirectory); `run_shell_deadline` takes one, and the
   chdir-and-restore dance around the call is gone.

4. The fast-path veto moved into try_fast_build, next to the manifest read
   that answers it — cmd_build no longer loads the manifest a second time to
   ask whether it may call a function that loads it again.

5. Coverage the claims did not have: workspace members (each member's own
   hooks, in that member's root, root manifest silent), preparation failing
   fires nothing, an unknown key warns and the known ones still run, and the
   e2e compares hook logs by CONTENT — cmd.exe writes CRLF, so the previous
   `$'start\nfinished'` comparison could not have passed on Windows even with
   the command line fixed. Plus seven manifest tests for the grammar.

Docs (en + zh) state what was implicit: which commands run hooks and which
deliberately do not, what a virtual workspace root does, that an active hook
opts the project out of the fast path, that preparation failure is silent, and
that a `[hooks]` table is executable content in a repository you may have just
cloned.

Author: speak-agent

docs/05-mcpp-toml.md

@@ -2116,13 +2116,15 @@ side_effect = true
 | `build_start` | string | — | Runs after project preparation, immediately before the build |
 | `build_failed` | string | — | Runs when the build exits unsuccessfully |
 | `build_finished` | string | — | Runs when the build exits successfully |
-| `timeout_seconds` | positive integer | `10` | Maximum time for each command |
+| `timeout_seconds` | integer, 1–86400 | `10` | Maximum time for each command |
 | `enabled` | bool | `true` | Enables all commands in this table |
 | `side_effect` | bool | `true` | Whether a hook failure makes the overall build fail |
 
-Commands run synchronously in the current project's root directory through the
-host shell (`/bin/sh` or `cmd.exe`). Standard input/output/error keep their
-ordinary terminal behaviour. Missing event commands are skipped.
+Commands run synchronously through the host shell (`/bin/sh` or `cmd.exe`),
+with the **project root** as their working directory — not the directory
+`mcpp build` was typed in, so a relative path in a hook means the same thing
+wherever the build was started. Standard input/output/error keep their ordinary
+terminal behaviour. Missing event commands are skipped.
 
 The lifecycle is:
 
@@ -2132,11 +2134,43 @@ build_start
     └─ build fails    → build_failed
 ```
 
-`build_failed` and `build_finished` are mutually exclusive. A hook command
-that cannot start, returns non-zero, or exceeds its timeout is a hook failure.
-With `side_effect = false`, mcpp reports a warning and preserves the build's
-result; with `true`, it returns failure. A hook's own failure does not trigger
-another hook.
+`build_failed` and `build_finished` are mutually exclusive, and both are
+reachable only after `build_start` has run. A project that cannot be *prepared*
+— an invalid manifest, an unresolvable dependency, no usable toolchain — fires
+nothing: it has not started building, and its hook program may be exactly what
+preparation would have installed.
+
+A hook command that cannot start, returns non-zero, or exceeds its timeout is a
+hook failure. With `side_effect = false`, mcpp reports a warning and preserves
+the build's result; with `true`, it returns failure — but a build that failed on
+its own keeps its own exit code, so `mcpp build` never reports a compile error
+as a notifier problem. A hook's own failure does not trigger another hook.
+
+Scope, precisely:
+
+- Only `mcpp build` runs hooks. `mcpp run`, `mcpp test` and
+  `mcpp build --configure-only` build too, and deliberately do not.
+- Hooks belong to the **package being built**. In a workspace fan-out that is
+  each member in turn — its own `[hooks]`, around its own build, in its own
+  root. A *virtual* workspace root (`[workspace]` with no `[package]`) builds
+  nothing, so a `[hooks]` table there never fires.
+- A dependency's `[hooks]` is never run. Only the root project's — installing a
+  package cannot make its author's shell command part of the consuming
+  project's build.
+- Declaring an active hook opts the project out of the no-op fast path, because
+  `build_start` is specified to run after preparation. Expect `mcpp build` on an
+  already-current hooked project to cost a preparation pass rather than
+  milliseconds.
+
+An unrecognised key in `[hooks]` is a warning (an error under `--strict`), so a
+manifest written for a newer mcpp still loads. An unrecognised *value* — a
+non-string command, a `timeout_seconds` outside 1–86400 — is a manifest error.
+
+> **A hook is code, and `mcpp.toml` is part of the repository.** Building a
+> freshly cloned project runs whatever its `[hooks]` say, with the privileges
+> of whoever invoked `mcpp build`. This is the same trust `build.mcpp` already
+> asks for ([07 — build.mcpp](07-build-mcpp.md)); `[hooks]` widens its reach
+> rather than introducing it.
 
 Hook programs can be installed as ordinary xlings dependencies. For example,
 an audio notifier can keep its sound files inside its own executable rather

docs/zh/05-mcpp-toml.md

@@ -1812,12 +1812,13 @@ side_effect = true
 | `build_start` | 字符串 | — | 项目准备完成、正式构建开始前执行 |
 | `build_failed` | 字符串 | — | 构建以失败状态结束时执行 |
 | `build_finished` | 字符串 | — | 构建成功结束时执行 |
-| `timeout_seconds` | 正整数 | `10` | 每条命令的最长执行时间 |
+| `timeout_seconds` | 整数,1–86400 | `10` | 每条命令的最长执行时间 |
 | `enabled` | 布尔 | `true` | 是否启用本表中的全部命令 |
 | `side_effect` | 布尔 | `true` | Hook 失败是否让本次构建失败 |
 
-命令在当前项目根目录中同步执行,使用宿主 Shell(`/bin/sh` 或 `cmd.exe`),标准输入、
-输出和错误沿用普通终端行为。没有配置的事件直接跳过。
+命令通过宿主 Shell(`/bin/sh` 或 `cmd.exe`)同步执行,工作目录是**项目根目录**——
+不是敲 `mcpp build` 的那个目录,所以 Hook 里的相对路径在哪儿发起构建都指同一处。
+标准输入、输出和错误沿用普通终端行为。没有配置的事件直接跳过。
 
 生命周期为:
 
@@ -1827,9 +1828,35 @@ build_start
     └─ 构建失败 → build_failed
 ```
 
-`build_failed` 与 `build_finished` 互斥。命令无法启动、返回非零或超过时限均视为
-Hook 失败。`side_effect = false` 时 mcpp 报 warning 并保留原构建结果;设为 `true`
-时返回失败。Hook 自身失败不会再触发另一个 Hook。
+`build_failed` 与 `build_finished` 互斥,而且两者都只在 `build_start` 已经执行之后
+才可达。项目**准备**阶段就失败的情况——manifest 非法、依赖无法解析、没有可用工具链
+——一个 Hook 都不触发:此时构建尚未开始,而 Hook 程序本身可能正是准备阶段要装的东西。
+
+命令无法启动、返回非零或超过时限均视为 Hook 失败。`side_effect = false` 时 mcpp 报
+warning 并保留原构建结果;设为 `true` 时返回失败——但构建自身失败时保留它自己的退出码,
+所以 `mcpp build` 不会把一次编译错误报成通知程序的问题。Hook 自身失败不会再触发另一个
+Hook。
+
+作用范围:
+
+- 只有 `mcpp build` 执行 Hook。`mcpp run`、`mcpp test` 和
+  `mcpp build --configure-only` 同样会构建,但有意不执行。
+- Hook 属于**被构建的那个包**。workspace 展开时就是逐个成员:各自的 `[hooks]`、
+  各自的构建、各自的根目录。**虚拟** workspace 根(只有 `[workspace]` 没有
+  `[package]`)不构建任何东西,写在那里的 `[hooks]` 永不触发。
+- 依赖的 `[hooks]` 永不执行,只有根项目的会——装一个包不会把包作者的 Shell 命令
+  变成消费方构建的一部分。
+- 声明了生效的 Hook 就等于让项目放弃空转快路径,因为 `build_start` 规定在准备阶段之后
+  执行。对已经是最新状态的带 Hook 项目,`mcpp build` 的代价是一次准备,而不是毫秒级。
+
+`[hooks]` 里不认识的**键**是 warning(`--strict` 下为错误),所以为更新版 mcpp 写的
+manifest 在这一版仍能加载;不认识的**值**——命令不是字符串、`timeout_seconds` 不在
+1–86400 之间——是 manifest 错误。
+
+> **Hook 是代码,而 `mcpp.toml` 是仓库的一部分。** 构建一个刚克隆下来的项目,会以
+> 执行 `mcpp build` 的那个账户的权限,运行它 `[hooks]` 里写的任何东西。这与
+> `build.mcpp`([07 — build.mcpp](07-build-mcpp.md))已经要求的信任是同一份;
+> `[hooks]` 扩大的是它的范围,而不是引入了一份新的信任。
 
 Hook 程序可以作为普通 xlings 依赖安装。例如,音频通知程序可以把音频内置进自己的
 可执行文件,无需让 mcpp 处理媒体资源:

modules/manifest/src/toml.cppm

@@ -1520,6 +1520,81 @@ std::expected<Manifest, ManifestError> parse_string(std::string_view content,
         }
     }
 
+    // [hooks] — project build lifecycle commands (#496). Parsed HERE rather
+    // than by the module that runs them, for the reason Appendix A of
+    // docs/05-mcpp-toml.md states: mcpp.toml has one grammar and one parser.
+    // A second reader of the same file would report ITS syntax errors in its
+    // own vocabulary — a typo in [package] arriving as "invalid hook
+    // configuration" — and would sit outside the warning/--strict policy every
+    // other section is subject to.
+    if (auto* hooksValue = doc->get("hooks");
+        hooksValue && !hooksValue->is_table()) {
+        return std::unexpected(error(origin,
+            "[hooks] must be a table of lifecycle commands"));
+    }
+    if (auto* ht = doc->get_table("hooks")) {
+        // Values are the author's own and visible in front of them: a wrong
+        // type is an error, not a silent default. An unrecognised KEY is a
+        // warning (--strict makes it an error), same split as [build] — so a
+        // manifest written for a later mcpp still loads on this one.
+        auto read_command = [&](std::string_view key, std::string& out)
+            -> std::optional<ManifestError> {
+            auto it = ht->find(key);
+            if (it == ht->end()) return std::nullopt;
+            if (!it->second.is_string() || it->second.as_string().empty())
+                return error(origin, std::format(
+                    "[hooks].{} must be a non-empty command string", key));
+            out = it->second.as_string();
+            return std::nullopt;
+        };
+        for (auto [key, out] : std::initializer_list<
+                 std::pair<std::string_view, std::string*>>{
+                 {"build_start",    &m.hooks.buildStart},
+                 {"build_failed",   &m.hooks.buildFailed},
+                 {"build_finished", &m.hooks.buildFinished}}) {
+            if (auto e = read_command(key, *out)) return std::unexpected(*e);
+        }
+
+        if (auto it = ht->find("timeout_seconds"); it != ht->end()) {
+            // Bounded above as well as below: the value becomes a
+            // std::chrono::seconds deadline, and "a timeout so large it is not
+            // one" is a mistake worth naming rather than honouring.
+            constexpr std::int64_t kMaxTimeout = 24 * 60 * 60;
+            if (!it->second.is_int() || it->second.as_int() <= 0
+                || it->second.as_int() > kMaxTimeout)
+                return std::unexpected(error(origin, std::format(
+                    "[hooks].timeout_seconds must be a positive integer "
+                    "(seconds, at most {})", kMaxTimeout)));
+            m.hooks.timeoutSeconds = static_cast<int>(it->second.as_int());
+        }
+
+        for (auto [key, out] : std::initializer_list<
+                 std::pair<std::string_view, bool*>>{
+                 {"enabled",     &m.hooks.enabled},
+                 {"side_effect", &m.hooks.sideEffect}}) {
+            auto it = ht->find(key);
+            if (it == ht->end()) continue;
+            if (!it->second.is_bool())
+                return std::unexpected(error(origin, std::format(
+                    "[hooks].{} must be a boolean", key)));
+            *out = it->second.as_bool();
+        }
+
+        static constexpr std::string_view kKnownHookKeys[] = {
+            "build_start", "build_failed", "build_finished",
+            "timeout_seconds", "enabled", "side_effect",
+        };
+        for (auto& [k, _] : *ht) {
+            bool known = false;
+            for (auto kk : kKnownHookKeys) if (k == kk) { known = true; break; }
+            if (!known)
+                m.schemaWarnings.push_back(std::format(
+                    "[hooks] has unsupported key '{}' (ignored). Keys: "
+                    "build_start, build_failed, build_finished, "
+                    "timeout_seconds, enabled, side_effect.", k));
+        }
+    }
+
     // [lib] — library root convention (cargo-style).
     if (auto v = doc->get_string("lib.path")) {
         m.lib.path = *v;

modules/manifest/src/types.cppm

@@ -919,6 +919,37 @@ struct WorkspaceConfig {
     bool                                                present = false;
 };
 
+// `[hooks]` — project build lifecycle commands (#496).
+//
+// The commands are host-shell strings written by the project author, run by
+// `mcpp build` around the build it performs. See docs/05-mcpp-toml.md §2.16.
+//
+// ⚠️ ONLY THE ROOT PROJECT'S HOOKS ARE EVER RUN. Every manifest mcpp parses
+// carries this field, including a DEPENDENCY's — and `mcpp build` reaches the
+// invoker (mcpp.hooks) with the root project's manifest alone. A dependency
+// that declares hooks is inert by construction, which is the only reason
+// `mcpp add` of a third-party package does not become "run their shell
+// command on my next build". Anything that adds a second call site inherits
+// that responsibility.
+struct Hooks {
+    std::string buildStart;
+    std::string buildFailed;
+    std::string buildFinished;
+    int         timeoutSeconds = 10;   // per command
+    bool        enabled        = true; // whole table
+    // Whether a hook failure fails the build. False downgrades it to a
+    // warning and preserves whatever the build itself returned.
+    bool        sideEffect     = true;
+
+    // "This project has work for `mcpp build` to do." Distinct from `enabled`:
+    // a table that only sets policy keys declares no command, and must leave
+    // the build path it would otherwise divert (the fast path) untouched.
+    bool active() const {
+        return enabled && !(buildStart.empty() && buildFailed.empty()
+                            && buildFinished.empty());
+    }
+};
+
 // [profile.<name>] — bundled build settings (opt level, debug, lto, strip).
 struct Profile {
     std::string optLevel = "2";
@@ -985,6 +1016,7 @@ struct Manifest {
     Resources                   resources;          // [resources] (mcpp#365)
     RuntimeConfig               runtimeConfig;
     XlingsConfig                xlings;             // [xlings] build environment (L-1)
+    Hooks                       hooks;              // [hooks] lifecycle commands (#496)
     std::vector<ConditionalConfig> conditionalConfigs;  // [target.'cfg(...)'.build], deferred
     std::map<std::string, Profile> profiles;   // [profile.<name>]
     // [features] — feature name → implied features ("default" = default set).