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

@@ -2120,9 +2120,11 @@ side_effect = true
 | `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,42 @@ 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 your 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 non-positive `timeout_seconds` — is a manifest error.
+
+> **A hook is code, and `mcpp.toml` is part of the repository.** Building a
+> project you have just cloned runs whatever its `[hooks]` say, with your
+> privileges. This is the same trust `build.mcpp` already asks for
+> ([07 — build.mcpp](07-build-mcpp.md)), and it is worth knowing you are
+> extending 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

@@ -1816,8 +1816,9 @@ side_effect = true
 | `enabled` | 布尔 | `true` | 是否启用本表中的全部命令 |
 | `side_effect` | 布尔 | `true` | Hook 失败是否让本次构建失败 |
 
-命令在当前项目根目录中同步执行,使用宿主 Shell(`/bin/sh` 或 `cmd.exe`),标准输入、
-输出和错误沿用普通终端行为。没有配置的事件直接跳过。
+命令通过宿主 Shell(`/bin/sh` 或 `cmd.exe`)同步执行,工作目录是**项目根目录**——
+不是敲 `mcpp build` 的那个目录,所以 Hook 里的相对路径在哪儿发起构建都指同一处。
+标准输入、输出和错误沿用普通终端行为。没有配置的事件直接跳过。
 
 生命周期为:
 
@@ -1827,9 +1828,34 @@ 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` 非正数
+——是 manifest 错误。
+
+> **Hook 是代码,而 `mcpp.toml` 是仓库的一部分。** 构建一个刚克隆下来的项目,会以你的
+> 权限执行它 `[hooks]` 里写的任何东西。这与 `build.mcpp`
+> ([07 — build.mcpp](07-build-mcpp.md))已经要求的信任是同一份,值得知道你正在把它扩大。
 
 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).

modules/platform/src/process.cppm

@@ -112,11 +112,22 @@ int run_exec_deadline(const std::vector<std::string>& argv,
                       std::chrono::milliseconds deadline,
                       bool* timed_out);
 
-// Run one host-shell command with inherited stdio and a real deadline.
-// POSIX uses /bin/sh; Windows uses cmd.exe. This is for user-authored command
-// strings such as project hooks — programmatic launches should keep using the
-// argv-based run_exec_deadline API above.
+// Run one host-shell command with inherited stdio, a working directory and a
+// real deadline. POSIX uses /bin/sh; Windows uses cmd.exe. This is for
+// user-authored command strings such as project hooks — programmatic launches
+// keep using the argv-based run_exec_deadline API above.
+//
+// `cwd` is where the command runs; empty means "inherit ours". It is a
+// PARAMETER rather than something the caller arranges with a chdir: the
+// process-wide working directory is shared state, and the launchers underneath
+// already carry a per-child cwd (posix_spawn_file_actions_addchdir_np /
+// CreateProcess's lpCurrentDirectory).
+//
+// Returns 127 when the shell itself could not be started — the same code a
+// shell uses for a command it cannot find, and never confusable with a
+// command that ran.
 int run_shell_deadline(std::string_view command,
+                       std::string_view cwd,
                        std::chrono::milliseconds deadline,
                        bool* timed_out);
 
@@ -168,6 +179,23 @@ int extract_exit_code(int raw_status);
 std::string windows_command_from_argv(const std::vector<std::string>& argv);
 std::string windows_wrap_for_cmd_c(std::string_view cmd);
 
+// The command line that runs a USER-AUTHORED shell command through cmd.exe.
+//
+// ⚠️ NOT `windows_command_from_argv({"cmd.exe", "/d", "/s", "/c", command})`.
+// That shape is for a program plus its argv, where CreateProcess's parsing is
+// what has to be satisfied. cmd.exe is not parsed that way: its switches must
+// arrive BARE (quoted, they are no longer switches), and the command tail is
+// governed by the /C quote rule above rather than by argv quoting — so an
+// argv-quoted command arrives carrying a pair cmd does not consume. That is
+// #425 one layer up, and it is why this is its own shape:
+//
+//     cmd.exe /d /s /c "<command>"
+//
+// /s makes the rule unconditional (strip exactly the outer pair), so the
+// command reaches cmd verbatim no matter how many quotes it contains; /d skips
+// AutoRun so a user's registry-installed shell hook cannot alter it.
+std::string windows_shell_command_line(std::string_view command);
+
 } // namespace mcpp::platform::process
 
 // ─── Implementation ──────────────────────────────────────────────────────
@@ -189,6 +217,12 @@ std::string windows_wrap_for_cmd_c(std::string_view cmd) {
     return "\"" + std::string(cmd) + "\"";
 }
 
+std::string windows_shell_command_line(std::string_view command) {
+    // One derivation for the outer pair: the same wrap the /c rule above is
+    // written against.
+    return "cmd.exe /d /s /c " + windows_wrap_for_cmd_c(command);
+}
+
 namespace {
 
 // Append a non-interactive stdin redirect to prevent child processes from
@@ -593,12 +627,17 @@ struct BoundedOutcome {
 // `capture == false` runs the child on the caller's stdio: live output, and a
 // real terminal for anything that checks. `run_exec_deadline` needs that; the
 // capturing variants need the pipe.
+// `windowsCommandLine` overrides what the Windows branch launches. Empty (the
+// normal case) means "derive it from argv". A shell command is the one caller
+// that must NOT be derived that way — see windows_shell_command_line — and the
+// POSIX branch is unaffected either way, because it never flattens argv.
 BoundedOutcome dispatch_bounded(
     const std::vector<std::string>& argv,
     const std::vector<std::pair<std::string, std::string>>& extraEnv,
     std::string_view cwd,
     std::chrono::milliseconds deadline,
-    bool capture)
+    bool capture,
+    std::string_view windowsCommandLine = {})
 {
     BoundedOutcome outcome;
 
@@ -625,7 +664,9 @@ BoundedOutcome dispatch_bounded(
         : nullptr;
 
     if constexpr (mcpp::platform::is_windows) {
-        const auto cmd = windows_command_from_argv(argv);
+        const auto cmd = windowsCommandLine.empty()
+                       ? windows_command_from_argv(argv)
+                       : std::string(windowsCommandLine);
         auto r = mcpp::platform::winproc::capture_with_deadline(
             cmd.c_str(), envArg, envCount, cwdArg, ms, sink, &outcome.output);
         outcome.supported = r.supported;
@@ -667,15 +708,25 @@ int run_exec_deadline(const std::vector<std::string>& argv,
 }
 
 int run_shell_deadline(std::string_view command,
+                       std::string_view cwd,
                        std::chrono::milliseconds deadline,
                        bool* timed_out)
 {
-    std::vector<std::string> argv;
-    if constexpr (mcpp::platform::is_windows)
-        argv = {"cmd.exe", "/d", "/s", "/c", std::string(command)};
-    else
-        argv = {"/bin/sh", "-c", std::string(command)};
-    return run_exec_deadline(argv, {}, deadline, timed_out);
+    if (timed_out) *timed_out = false;
+    if (command.empty() || deadline.count() <= 0) return 127;
+
+    // argv is what the POSIX branch launches; the Windows branch takes the
+    // shaped command line instead. Both are built here so neither platform's
+    // spelling can drift into a launcher that does not use it.
+    const std::vector<std::string> argv{"/bin/sh", "-c", std::string(command)};
+    auto r = dispatch_bounded(argv, {}, cwd, deadline, /*capture=*/false,
+                              windows_shell_command_line(command));
+    // No fallback to the unbounded launcher here, unlike run_exec_deadline: a
+    // hook's deadline and its working directory are both part of what the
+    // caller asked for, and the unbounded path can honour neither.
+    if (!r.supported) return 127;
+    if (timed_out) *timed_out = r.timed_out;
+    return r.exit_code;
 }
 
 RunResult capture_exec_deadline(