feat(script): scripts in project.cpp, run with crafter-build run

A project.cpp could describe how a project is built, tested and linted,
but not the chores around it: packaging, installing, publishing. Those
stayed shell lines in a README or in someone's history.

Configuration gains `scripts`, a plain list like `defines`. A Script is
a name and a C++ callback, as a lint rule is; there is no script
language and no config file. The callback gets a ScriptContext (the
project, the project file's directory, the arguments) and returns the
exit status. ctx.Run runs a shell command with the terminal attached
and returns its status. It is only stored when project.cpp loads, which
happens for every verb and for every project that depends on this one.

`crafter-build run <name> [args...]` runs one, a bare `run` lists them.
Only the scripts of the project crafter-build was pointed at are
runnable, never a dependency's.

Everything after the script's name is handed to the script untouched.
The two branches that do this sit ahead of every other branch of the
parse loop, --version and --help included. Below the verbs,
`run package clean` would delete build/, and any other word would land
in the project's args and so in the variant hash, moving the build to
another directory. Options before the name keep their meaning, so
project args go there.

The driver is its own partition, :Script. It refuses a project with no
scripts, a name that is empty or starts with '-' (it could never be
typed), a name declared twice (running either would be a guess) and an
unknown name, each with exit 1 and without running anything. A script
that throws exits 1. A return value outside 0..255 becomes 1: an exit
status is eight bits, and a raw wait status such as 256 would otherwise
wrap to success.

Two helpers in :Platform:

- RunCommandAttached runs a command with inherited stdio. Every helper
  so far captured through popen, which is right for a compile step and
  useless for a command that runs for half an hour or asks a question.
  It reads the wait status through DecodeWaitStatus, which
  RunCommandChecked and RunCommandWithTimeout now share.
- ShellQuote is exported. It existed twice, as ShellQuote in :External
  and ShellQuoteSh in :Test, with the same behaviour; both are gone. A
  script that puts a path into a command needs it too.

Not included: a string shorthand for one-command scripts (a one-line
lambda covers it) and a ctx.Build() helper (Build() is already
exported).

A new partition and new exported symbols: run ./build.sh.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

interfaces/Crafter.Build-Clang.cppm

@@ -356,6 +356,45 @@ export namespace Crafter {
         bool needsAst = false;
     };
 
+    struct Configuration;
+
+    // What a Script's callback is handed when `crafter-build run <name>`
+    // starts it.
+    struct ScriptContext {
+        // The Configuration project.cpp returned. Read the project through
+        // this rather than capturing the local in CrafterBuildProject by
+        // reference: that local is gone by the time a script runs.
+        Configuration& project;
+        // Absolute directory of the project file. Commands run in the
+        // directory crafter-build was started from, like everything else it
+        // does, so a script names its files through this.
+        fs::path projectDir;
+        // Everything the user typed after the script's name, untouched:
+        // crafter-build interprets none of it.
+        std::span<const std::string> args;
+        // Run `command` through sh with the terminal attached — output
+        // appears as it is produced, the command can prompt, Ctrl-C reaches
+        // it — after echoing it as `$ command` (not under -q). Returns its
+        // exit code, 128+signal when it was killed; return that from the
+        // script to make it the exit code of crafter-build. Quote anything
+        // that is not a literal with ShellQuote. Out-of-line like
+        // LintContext's members: the callback runs from project.so.
+        std::int32_t Run(std::string_view command) const;
+    };
+
+    // A project script: a chore that belongs to the project but is not part
+    // of building it (packaging, installing, publishing, serving), run by
+    // name with `crafter-build run <name> [args...]`. `run` returns the
+    // process exit code. It is only stored when project.cpp is loaded, which
+    // happens for every verb and for every project that depends on this one,
+    // so whatever a script needs to probe it probes when it runs. Only the
+    // scripts of the project crafter-build was pointed at can be run, never
+    // a dependency's.
+    struct Script {
+        std::string name;
+        std::function<std::int32_t(ScriptContext&)> run;
+    };
+
     // The host target triple: what the resolved toolchain's clang++ prints
     // for -print-target-triple (see GetToolchain). Used as the default for
     // Configuration::target so projects don't have to hardcode it for the
@@ -446,6 +485,12 @@ export namespace Crafter {
         std::vector<Test> tests;
         // Lint rules for `crafter-build lint`. Populate via AddLintRule.
         std::vector<LintRule> lintRules;
+        // Scripts for `crafter-build run <name>`, a plain list like defines:
+        //   cfg.scripts.push_back({"docs", [](ScriptContext& ctx) {
+        //       return ctx.Run("python3 tools/gen-docs.py");
+        //   }});
+        // Not part of VariantId: a script changes nothing that is compiled.
+        std::vector<Script> scripts;
         void GetInterfacesAndImplementations(std::span<fs::path> interfaces, std::span<fs::path> implementations);
         // Retry the `import X;` names GetInterfacesAndImplementations could not
         // place, against the dependency DAG as it stands now. Sources are

interfaces/Crafter.Build-Platform.cppm

@@ -29,6 +29,18 @@ namespace Crafter {
     // therefore keep the `if (!result.empty())` shape they already had.
     std::string RunBuildCommand(std::string_view command);
     export CommandResult RunCommandWithTimeout(std::string_view command, std::chrono::seconds timeout);
+    // Runs `command` through sh with this process's own stdin, stdout and
+    // stderr, so its output appears as it is produced and it can prompt.
+    // Every helper above captures instead, which suits a compile step and
+    // not a command that runs for half an hour. Returns the exit code, or
+    // 128+signal when the command was killed; a nonzero exit is the caller's
+    // to judge and never throws. While it runs, Ctrl-C goes to the command
+    // and not to crafter-build, which then sees it as exit code 130.
+    // Project scripts reach this through ScriptContext::Run.
+    std::int32_t RunCommandAttached(std::string_view command);
+    // `s` as one single-quoted sh word, safe to splice into a command line
+    // whatever it contains: paths with spaces, arguments a user typed.
+    export std::string ShellQuote(std::string_view s);
     std::string GetBaseCommand(const Configuration& config);
     export Configuration LoadProject(const fs::path& projectFile, std::span<const std::string_view> args);
     // A dependency the project file currently running its CrafterBuildProject

interfaces/Crafter.Build-Script.cppm

@@ -0,0 +1,40 @@
+// SPDX-License-Identifier: LGPL-3.0-only
+// SPDX-FileCopyrightText: Copyright (C) 2026 Catcrafts®
+
+export module Crafter.Build:Script;
+import std;
+import :Clang;
+
+export namespace Crafter {
+    struct RunScriptOptions {
+        // The script to run; read only when `named` is set.
+        std::string name;
+        // A name was given. Kept apart from `name` because an empty string
+        // is a name someone can type (`run ""`): it has to be looked up and
+        // refused, not read as a bare `run`, which lists.
+        bool named = false;
+        // What followed the name on the command line, handed to the script
+        // as ScriptContext::args.
+        std::vector<std::string> args;
+        // Print the script names instead of running one.
+        bool listOnly = false;
+        // Absolute path of the loaded project.cpp; its directory becomes
+        // ScriptContext::projectDir. Empty => fall back to cfg.path.
+        std::filesystem::path projectFile;
+    };
+
+    // Backs `crafter-build run`. Runs the script `opts` names out of
+    // `projectCfg.scripts` and returns what it returned, which the CLI uses
+    // as the process exit code. Without a name, or with listOnly, prints the
+    // names and returns 0.
+    //
+    // Returns 1, with the reason on stderr and without running anything,
+    // when the project defines no scripts, when a script is declared under a
+    // name that could never be typed (empty, or starting with '-') or under
+    // one name twice, and when no script has the requested name. A script
+    // that throws also yields 1, as does one that returns a nonzero value
+    // outside 1..255: an exit status is eight bits, and a value such as 256
+    // (a raw wait status passed along by mistake) would otherwise wrap to
+    // success.
+    std::int32_t RunScript(Configuration& projectCfg, const RunScriptOptions& opts);
+}

interfaces/Crafter.Build.cppm

@@ -10,5 +10,6 @@ export import :Shader;
 export import :External;
 export import :Test;
 export import :Lint;
+export import :Script;
 export import :Progress;
 export import :Asset;