repoactive 0.2.8.dev2__tar.gz → 0.3.1.dev1__tar.gz

{repoactive-0.2.8.dev2 → repoactive-0.3.1.dev1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: repoactive
-Version: 0.2.8.dev2
+Version: 0.3.1.dev1
 Summary: Script-driven code changes with automated merge requests
 License-Expression: GPL-3.0-or-later
 License-File: LICENSE
@@ -55,6 +55,8 @@ and (with `--mode publish`) the full MR lifecycle.
   - [Example](#example)
   - [`[platform.<name>]`](#platformname)
   - [Config file locations](#config-file-locations)
+  - [Variables passed to job commands](#variables-passed-to-job-commands)
+  - [Passing secrets to commands with `secret_env`](#passing-secrets-to-commands-with-secret_env)
   - [Overriding values on the command line](#overriding-values-on-the-command-line)
 - [Selecting jobs with tags](#selecting-jobs-with-tags)
   - [Keeping unmerged branches current](#keeping-unmerged-branches-current)
@@ -467,13 +469,17 @@ block.
 **Branch and commit options:**
 
 - **`branch_prefix`** (default: `"repoactive/"`) - Prefix prepended to the
-  job name to form the branch name.
+  job name to form the branch name. Set to `""` to use the job name alone.
+  With an empty prefix the branch name is exactly the job name, so make sure
+  no job is named after your base branch (e.g. a job named `main`) - the two
+  branches would otherwise collide.
 - **`mr_title_prefix`** (default: `"[repoactive] "`) - Prefix prepended to
   every MR/PR title. Set to `""` to disable.
 - **`commit_title_prefix`** (default: `"[repoactive] "`) - Prefix prepended
   to every commit title. Set to `""` to disable.
 - **`base_branch`** (default: repo default) - Target branch for all jobs
-  that do not set their own.
+  that do not set their own. May also be a jj revset expression such as
+  `trunk()`, `root()`, or a user-defined revset alias.
 
 **Run control:**
 
@@ -484,6 +490,18 @@ block.
 - **`timeout`** (default: `"2m"`) - Maximum runtime for a job's command.
   Same format as `cooldown_period`. See
   [Limiting job runtime with `timeout`](#limiting-job-runtime-with-timeout).
+- **`shell`** (default: `/bin/sh`) - Interpreter used to run job commands. A
+  bare name is resolved on `PATH` (e.g. `"bash"`); an absolute path also
+  works. The command runs as `<shell> -c <command>`. Arguments are not
+  allowed - the value must be a single binary.
+
+**Secrets:**
+
+- **`secret_env`** (default: `[]`) - Names of environment variables to mark
+  as secrets config-wide. Each marked name is stripped from every job
+  command's environment, but a job still reads one only by listing it in its
+  own `secret_env`; `job-defaults` marks names, it does not grant them. See
+  [Passing secrets to commands with `secret_env`](#passing-secrets-to-commands-with-secret_env).
 
 ### `[job.<name>]`
 
@@ -518,7 +536,8 @@ underscores.
 **Branch and commit options:**
 
 - **`base_branch`** (default: inherited) - Target branch for this job's
-  MR/PR.
+  MR/PR. May also be a jj revset expression such as `trunk()`, `root()`, or
+  a user-defined revset alias.
 - **`branch_prefix`** (default: inherited) - Override the branch-name prefix
   for this job only.
 - **`mr_title_prefix`** (default: inherited) - Override the MR/PR title
@@ -553,9 +572,20 @@ underscores.
 - **`timeout`** (default: inherited) - Maximum runtime for this job's
   command. Set to `"0s"` to disable the timeout entirely. See
   [Limiting job runtime with `timeout`](#limiting-job-runtime-with-timeout).
+- **`shell`** (default: inherited) - Interpreter used to run this job's
+  command, overriding `job-defaults.shell`. See
+  [`job-defaults.shell`](#job-defaults).
 - **`emits_jobs`** (default: `false`) - Generator job: the command writes
-  `*.toml` job fragments into `$REPOACTIVE_JOBS_DIR` instead of producing a
-  diff. See [Generating jobs dynamically](#generating-jobs-dynamically).
+  `*.toml` job fragments into `$RA_JOBS_DIR` instead of producing a diff.
+  See [Generating jobs dynamically](#generating-jobs-dynamically).
+
+**Secrets:**
+
+- **`secret_env`** (default: `[]`) - Names of environment variables holding
+  secrets this job's command may read. A marked name is stripped from every
+  command's environment; only a job that lists it here has it injected back
+  for its own command. See
+  [Passing secrets to commands with `secret_env`](#passing-secrets-to-commands-with-secret_env).
 
 ### Stacking MRs
 
@@ -658,6 +688,165 @@ directory of `*.toml` files, and may be repeated to merge several sources;
 later sources win. Explicit paths are resolved relative to the current
 directory, not `--repo`.
 
+### Variables passed to job commands
+
+`repoactive` injects a few `RA_`-prefixed environment variables into every
+job command's environment. These are distinct from the `REPOACTIVE_`
+variables [above](#environment-variables), which configure `repoactive`
+itself.
+
+| Variable               | Value                                                                                  | Set when                                                                            |
+| ---------------------- | -------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
+| `RA_JOB_NAME`          | The name of the job the command belongs to.                                            | Always.                                                                             |
+| `RA_WORKSPACE_DIR`     | The temporary jj workspace created for the job (also the command's working directory). | Always.                                                                             |
+| `RA_JOB_BRANCH`        | The bookmark/branch repoactive uses for the job's output.                              | Always.                                                                             |
+| `RA_JOB_BASE_BRANCH`   | The branch the job's MR targets (`base_branch`, or `trunk()` by default).              | Always.                                                                             |
+| `RA_CONFIG_SOURCE_DIR` | The directory of the config file that defined the command.                             | The command came from a config file (not a `--set` override or a built-in default). |
+| `RA_JOBS_DIR`          | The directory a generator writes its `*.toml` job fragments into.                      | The command is a [generator](#generating-jobs-dynamically) (`emits_jobs`).          |
+
+#### `RA_JOB_NAME`
+
+`RA_JOB_NAME` holds the name of the job the command belongs to. A command
+shared by several jobs (for instance one set in `[job-defaults]` or emitted
+by a generator) can read it to tell which job is running:
+
+```toml
+[job.lint]
+command = "./run-check.sh $RA_JOB_NAME"
+title = "run the shared check script for this job"
+```
+
+#### `RA_WORKSPACE_DIR`
+
+A job's command runs in a temporary jj workspace, which is also its working
+directory. `RA_WORKSPACE_DIR` names that directory explicitly, so a command
+that changes directory can still find its way back:
+
+```toml
+[job.build]
+command = "cd subdir && make && cp result $RA_WORKSPACE_DIR/subdir/"
+title = "build in a subdirectory"
+```
+
+#### `RA_JOB_BRANCH`
+
+`RA_JOB_BRANCH` holds the bookmark (git branch) repoactive uses for the
+job's output, e.g. `repoactive/uv-lock-upgrade`. The command runs on a fresh
+commit while that bookmark still points at the **previous** run's commit, so
+a command can inspect what it produced last time - for example to build on
+it or diff against it:
+
+```toml
+[job.notes]
+command = "jj diff --from $RA_JOB_BRANCH --to @ > /tmp/delta || true; ./make-notes.sh"
+title = "regenerate release notes from what changed since last run"
+```
+
+The bookmark may not exist yet: a job's first run, a run that produced no
+diff, and a generator all leave it unset on the remote, so a command that
+reads it should tolerate a missing ref.
+
+#### `RA_JOB_BASE_BRANCH`
+
+`RA_JOB_BASE_BRANCH` holds the branch the job's merge request targets - its
+`base_branch`, or `trunk()` when that is unset. A command can use it to look
+at only what changed relative to the target, for instance to lint or
+reformat just the affected files:
+
+```toml
+[job.format]
+command = "treefmt $(git diff --name-only $RA_JOB_BASE_BRANCH)"
+title = "format files changed since the base branch"
+```
+
+This is the branch you _configured_ as the base. When a job stacks on
+another via `depends_on`, its commit actually sits on top of that other
+job's output, so `RA_JOB_BASE_BRANCH` names the ultimate target of the
+stack, not the immediate parent.
+
+#### `RA_CONFIG_SOURCE_DIR`
+
+Because the command runs in that throwaway workspace rather than in the
+directory its config lives in, a relative path cannot reach a helper file
+kept beside the config. `RA_CONFIG_SOURCE_DIR` bridges that: it holds the
+directory of the config file that defined the job's command:
+
+- a job defined in `.repoactive.toml` gets the directory holding it (the
+  repo directory, by default);
+- a job defined in `.repoactive.d/foo.toml` gets the `.repoactive.d`
+  directory.
+
+```toml
+[job.fixup]
+command = "$RA_CONFIG_SOURCE_DIR/fixup.sh"
+title = "run the fixup script kept beside the config"
+```
+
+The value is the config file's real location on disk, so it is the same
+whether the file was discovered automatically or named with `-c`. A command
+whose value came from a `--set` override has no config file, so
+`RA_CONFIG_SOURCE_DIR` is unset for it.
+
+### Passing secrets to commands with `secret_env`
+
+A job command inherits `repoactive`'s environment, so a secret exported
+before the run (an LLM key, a registry token) reaches it. Left unmanaged
+that secret reaches **every** job, whether it needs it or not. `secret_env`
+scopes secrets to the jobs that ask for them.
+
+The field separates two things:
+
+- **Marking** - naming a variable in _any_ `secret_env` (a job's or
+  `[job-defaults]`') marks it a secret and **removes it from every job
+  command's environment**.
+- **Granting** - a job reads a marked secret back only by listing it in
+  **its own** `secret_env`. `[job-defaults].secret_env` marks names but
+  grants to no job.
+
+So a secret is present only in the jobs that name it, never ambient:
+
+```toml
+[job-defaults]
+secret_env = ["OPENAI_API_KEY"]
+
+[job.rewrite-docs]
+command = "./llm-rewrite.sh"
+title = "docs: rewrite with the LLM"
+secret_env = ["OPENAI_API_KEY"]
+
+[job.format]
+command = "treefmt"
+title = "format the tree"
+```
+
+Here `OPENAI_API_KEY` is marked in `[job-defaults]`, so `format` (which does
+not grant it) runs without it in its environment; only `rewrite-docs`, which
+lists it in its own `secret_env`, can read it.
+
+A job that grants a secret which is **unset** in `repoactive`'s environment
+fails at its start with a clear error, rather than letting the command fail
+obscurely later. Secret **values** must never be written in config - a
+`.repoactive.toml` is checked into the repo; `secret_env` names variables,
+your environment (or your CI's secret store) supplies the values. The `RA_`
+and `REPOACTIVE_` prefixes are reserved and rejected.
+
+A [generated job](#generating-jobs-dynamically) may only grant a secret that
+the static config already marks; an emitted `secret_env` naming a variable
+no static job or `[job-defaults]` marked is rejected. Mark such a secret up
+front in `[job-defaults].secret_env` (or on the generator), and the emitted
+jobs grant it.
+
+A platform's `token_env` is normally stripped from every command
+([the platform token](#platformname) is kept out of jobs). A job that
+genuinely needs it can opt back in by naming that variable in its own
+`secret_env`; only that job then receives it.
+
+> **Note:** `secret_env` scopes _which jobs_ can read a secret. It does not
+> yet redact secret values from a command's captured output, so a command
+> that echoes a secret it was granted can still write it into the commit
+> message. Avoid printing granted secrets. See
+> [ADR 0017](docs/adr/0017-secret-env-redaction.md).
+
 ### Overriding values on the command line
 
 `--set NAME=VALUE`/`-s` tweaks individual config values without editing a
@@ -831,12 +1020,12 @@ changed anything in the current run, the job is skipped.
 
 ```toml
 [job.prek-autoupdate]
-command = "./scripts/prek.sh autoupdate"
+command = "uvx prek autoupdate"
 title = "ci: update pre-commit hooks"
 tags = ["weekly"]
 
 [job.prek-run-all]
-command = "sh -c './scripts/prek.sh run -a; true'"
+command = "sh -c 'uvx prek run -a; true'"
 title = "ci: apply pre-commit fixes"
 depends_on = ["prek-autoupdate"]
 run_only_if_changed = ["prek-autoupdate"]
@@ -962,8 +1151,8 @@ job per package in a monorepo, one per entry in a manifest - and you don't
 want to hand-maintain them. A **generator** is an ordinary `[job.<name>]`
 with `emits_jobs = true`. Instead of producing a diff, its command writes
 one or more `*.toml` job fragments into the directory named by the
-`REPOACTIVE_JOBS_DIR` environment variable, and the jobs it emits run in the
-same invocation.
+`RA_JOBS_DIR` environment variable, and the jobs it emits run in the same
+invocation.
 
 ```toml
 [job.per-package]
@@ -978,7 +1167,7 @@ cooldown_period = "7d"
 The command writes fragments using the normal `[job.<name>]` syntax, e.g.
 
 ```toml
-# $REPOACTIVE_JOBS_DIR/pkg-a.toml
+# $RA_JOBS_DIR/pkg-a.toml
 [job.upgrade-pkg-a]
 command = "uv lock --upgrade --package pkg-a"
 title = "build: upgrade pkg-a"

{repoactive-0.2.8.dev2 → repoactive-0.3.1.dev1}/README.md

@@ -28,6 +28,8 @@ and (with `--mode publish`) the full MR lifecycle.
   - [Example](#example)
   - [`[platform.<name>]`](#platformname)
   - [Config file locations](#config-file-locations)
+  - [Variables passed to job commands](#variables-passed-to-job-commands)
+  - [Passing secrets to commands with `secret_env`](#passing-secrets-to-commands-with-secret_env)
   - [Overriding values on the command line](#overriding-values-on-the-command-line)
 - [Selecting jobs with tags](#selecting-jobs-with-tags)
   - [Keeping unmerged branches current](#keeping-unmerged-branches-current)
@@ -440,13 +442,17 @@ block.
 **Branch and commit options:**
 
 - **`branch_prefix`** (default: `"repoactive/"`) - Prefix prepended to the
-  job name to form the branch name.
+  job name to form the branch name. Set to `""` to use the job name alone.
+  With an empty prefix the branch name is exactly the job name, so make sure
+  no job is named after your base branch (e.g. a job named `main`) - the two
+  branches would otherwise collide.
 - **`mr_title_prefix`** (default: `"[repoactive] "`) - Prefix prepended to
   every MR/PR title. Set to `""` to disable.
 - **`commit_title_prefix`** (default: `"[repoactive] "`) - Prefix prepended
   to every commit title. Set to `""` to disable.
 - **`base_branch`** (default: repo default) - Target branch for all jobs
-  that do not set their own.
+  that do not set their own. May also be a jj revset expression such as
+  `trunk()`, `root()`, or a user-defined revset alias.
 
 **Run control:**
 
@@ -457,6 +463,18 @@ block.
 - **`timeout`** (default: `"2m"`) - Maximum runtime for a job's command.
   Same format as `cooldown_period`. See
   [Limiting job runtime with `timeout`](#limiting-job-runtime-with-timeout).
+- **`shell`** (default: `/bin/sh`) - Interpreter used to run job commands. A
+  bare name is resolved on `PATH` (e.g. `"bash"`); an absolute path also
+  works. The command runs as `<shell> -c <command>`. Arguments are not
+  allowed - the value must be a single binary.
+
+**Secrets:**
+
+- **`secret_env`** (default: `[]`) - Names of environment variables to mark
+  as secrets config-wide. Each marked name is stripped from every job
+  command's environment, but a job still reads one only by listing it in its
+  own `secret_env`; `job-defaults` marks names, it does not grant them. See
+  [Passing secrets to commands with `secret_env`](#passing-secrets-to-commands-with-secret_env).
 
 ### `[job.<name>]`
 
@@ -491,7 +509,8 @@ underscores.
 **Branch and commit options:**
 
 - **`base_branch`** (default: inherited) - Target branch for this job's
-  MR/PR.
+  MR/PR. May also be a jj revset expression such as `trunk()`, `root()`, or
+  a user-defined revset alias.
 - **`branch_prefix`** (default: inherited) - Override the branch-name prefix
   for this job only.
 - **`mr_title_prefix`** (default: inherited) - Override the MR/PR title
@@ -526,9 +545,20 @@ underscores.
 - **`timeout`** (default: inherited) - Maximum runtime for this job's
   command. Set to `"0s"` to disable the timeout entirely. See
   [Limiting job runtime with `timeout`](#limiting-job-runtime-with-timeout).
+- **`shell`** (default: inherited) - Interpreter used to run this job's
+  command, overriding `job-defaults.shell`. See
+  [`job-defaults.shell`](#job-defaults).
 - **`emits_jobs`** (default: `false`) - Generator job: the command writes
-  `*.toml` job fragments into `$REPOACTIVE_JOBS_DIR` instead of producing a
-  diff. See [Generating jobs dynamically](#generating-jobs-dynamically).
+  `*.toml` job fragments into `$RA_JOBS_DIR` instead of producing a diff.
+  See [Generating jobs dynamically](#generating-jobs-dynamically).
+
+**Secrets:**
+
+- **`secret_env`** (default: `[]`) - Names of environment variables holding
+  secrets this job's command may read. A marked name is stripped from every
+  command's environment; only a job that lists it here has it injected back
+  for its own command. See
+  [Passing secrets to commands with `secret_env`](#passing-secrets-to-commands-with-secret_env).
 
 ### Stacking MRs
 
@@ -631,6 +661,165 @@ directory of `*.toml` files, and may be repeated to merge several sources;
 later sources win. Explicit paths are resolved relative to the current
 directory, not `--repo`.
 
+### Variables passed to job commands
+
+`repoactive` injects a few `RA_`-prefixed environment variables into every
+job command's environment. These are distinct from the `REPOACTIVE_`
+variables [above](#environment-variables), which configure `repoactive`
+itself.
+
+| Variable               | Value                                                                                  | Set when                                                                            |
+| ---------------------- | -------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
+| `RA_JOB_NAME`          | The name of the job the command belongs to.                                            | Always.                                                                             |
+| `RA_WORKSPACE_DIR`     | The temporary jj workspace created for the job (also the command's working directory). | Always.                                                                             |
+| `RA_JOB_BRANCH`        | The bookmark/branch repoactive uses for the job's output.                              | Always.                                                                             |
+| `RA_JOB_BASE_BRANCH`   | The branch the job's MR targets (`base_branch`, or `trunk()` by default).              | Always.                                                                             |
+| `RA_CONFIG_SOURCE_DIR` | The directory of the config file that defined the command.                             | The command came from a config file (not a `--set` override or a built-in default). |
+| `RA_JOBS_DIR`          | The directory a generator writes its `*.toml` job fragments into.                      | The command is a [generator](#generating-jobs-dynamically) (`emits_jobs`).          |
+
+#### `RA_JOB_NAME`
+
+`RA_JOB_NAME` holds the name of the job the command belongs to. A command
+shared by several jobs (for instance one set in `[job-defaults]` or emitted
+by a generator) can read it to tell which job is running:
+
+```toml
+[job.lint]
+command = "./run-check.sh $RA_JOB_NAME"
+title = "run the shared check script for this job"
+```
+
+#### `RA_WORKSPACE_DIR`
+
+A job's command runs in a temporary jj workspace, which is also its working
+directory. `RA_WORKSPACE_DIR` names that directory explicitly, so a command
+that changes directory can still find its way back:
+
+```toml
+[job.build]
+command = "cd subdir && make && cp result $RA_WORKSPACE_DIR/subdir/"
+title = "build in a subdirectory"
+```
+
+#### `RA_JOB_BRANCH`
+
+`RA_JOB_BRANCH` holds the bookmark (git branch) repoactive uses for the
+job's output, e.g. `repoactive/uv-lock-upgrade`. The command runs on a fresh
+commit while that bookmark still points at the **previous** run's commit, so
+a command can inspect what it produced last time - for example to build on
+it or diff against it:
+
+```toml
+[job.notes]
+command = "jj diff --from $RA_JOB_BRANCH --to @ > /tmp/delta || true; ./make-notes.sh"
+title = "regenerate release notes from what changed since last run"
+```
+
+The bookmark may not exist yet: a job's first run, a run that produced no
+diff, and a generator all leave it unset on the remote, so a command that
+reads it should tolerate a missing ref.
+
+#### `RA_JOB_BASE_BRANCH`
+
+`RA_JOB_BASE_BRANCH` holds the branch the job's merge request targets - its
+`base_branch`, or `trunk()` when that is unset. A command can use it to look
+at only what changed relative to the target, for instance to lint or
+reformat just the affected files:
+
+```toml
+[job.format]
+command = "treefmt $(git diff --name-only $RA_JOB_BASE_BRANCH)"
+title = "format files changed since the base branch"
+```
+
+This is the branch you _configured_ as the base. When a job stacks on
+another via `depends_on`, its commit actually sits on top of that other
+job's output, so `RA_JOB_BASE_BRANCH` names the ultimate target of the
+stack, not the immediate parent.
+
+#### `RA_CONFIG_SOURCE_DIR`
+
+Because the command runs in that throwaway workspace rather than in the
+directory its config lives in, a relative path cannot reach a helper file
+kept beside the config. `RA_CONFIG_SOURCE_DIR` bridges that: it holds the
+directory of the config file that defined the job's command:
+
+- a job defined in `.repoactive.toml` gets the directory holding it (the
+  repo directory, by default);
+- a job defined in `.repoactive.d/foo.toml` gets the `.repoactive.d`
+  directory.
+
+```toml
+[job.fixup]
+command = "$RA_CONFIG_SOURCE_DIR/fixup.sh"
+title = "run the fixup script kept beside the config"
+```
+
+The value is the config file's real location on disk, so it is the same
+whether the file was discovered automatically or named with `-c`. A command
+whose value came from a `--set` override has no config file, so
+`RA_CONFIG_SOURCE_DIR` is unset for it.
+
+### Passing secrets to commands with `secret_env`
+
+A job command inherits `repoactive`'s environment, so a secret exported
+before the run (an LLM key, a registry token) reaches it. Left unmanaged
+that secret reaches **every** job, whether it needs it or not. `secret_env`
+scopes secrets to the jobs that ask for them.
+
+The field separates two things:
+
+- **Marking** - naming a variable in _any_ `secret_env` (a job's or
+  `[job-defaults]`') marks it a secret and **removes it from every job
+  command's environment**.
+- **Granting** - a job reads a marked secret back only by listing it in
+  **its own** `secret_env`. `[job-defaults].secret_env` marks names but
+  grants to no job.
+
+So a secret is present only in the jobs that name it, never ambient:
+
+```toml
+[job-defaults]
+secret_env = ["OPENAI_API_KEY"]
+
+[job.rewrite-docs]
+command = "./llm-rewrite.sh"
+title = "docs: rewrite with the LLM"
+secret_env = ["OPENAI_API_KEY"]
+
+[job.format]
+command = "treefmt"
+title = "format the tree"
+```
+
+Here `OPENAI_API_KEY` is marked in `[job-defaults]`, so `format` (which does
+not grant it) runs without it in its environment; only `rewrite-docs`, which
+lists it in its own `secret_env`, can read it.
+
+A job that grants a secret which is **unset** in `repoactive`'s environment
+fails at its start with a clear error, rather than letting the command fail
+obscurely later. Secret **values** must never be written in config - a
+`.repoactive.toml` is checked into the repo; `secret_env` names variables,
+your environment (or your CI's secret store) supplies the values. The `RA_`
+and `REPOACTIVE_` prefixes are reserved and rejected.
+
+A [generated job](#generating-jobs-dynamically) may only grant a secret that
+the static config already marks; an emitted `secret_env` naming a variable
+no static job or `[job-defaults]` marked is rejected. Mark such a secret up
+front in `[job-defaults].secret_env` (or on the generator), and the emitted
+jobs grant it.
+
+A platform's `token_env` is normally stripped from every command
+([the platform token](#platformname) is kept out of jobs). A job that
+genuinely needs it can opt back in by naming that variable in its own
+`secret_env`; only that job then receives it.
+
+> **Note:** `secret_env` scopes _which jobs_ can read a secret. It does not
+> yet redact secret values from a command's captured output, so a command
+> that echoes a secret it was granted can still write it into the commit
+> message. Avoid printing granted secrets. See
+> [ADR 0017](docs/adr/0017-secret-env-redaction.md).
+
 ### Overriding values on the command line
 
 `--set NAME=VALUE`/`-s` tweaks individual config values without editing a
@@ -804,12 +993,12 @@ changed anything in the current run, the job is skipped.
 
 ```toml
 [job.prek-autoupdate]
-command = "./scripts/prek.sh autoupdate"
+command = "uvx prek autoupdate"
 title = "ci: update pre-commit hooks"
 tags = ["weekly"]
 
 [job.prek-run-all]
-command = "sh -c './scripts/prek.sh run -a; true'"
+command = "sh -c 'uvx prek run -a; true'"
 title = "ci: apply pre-commit fixes"
 depends_on = ["prek-autoupdate"]
 run_only_if_changed = ["prek-autoupdate"]
@@ -935,8 +1124,8 @@ job per package in a monorepo, one per entry in a manifest - and you don't
 want to hand-maintain them. A **generator** is an ordinary `[job.<name>]`
 with `emits_jobs = true`. Instead of producing a diff, its command writes
 one or more `*.toml` job fragments into the directory named by the
-`REPOACTIVE_JOBS_DIR` environment variable, and the jobs it emits run in the
-same invocation.
+`RA_JOBS_DIR` environment variable, and the jobs it emits run in the same
+invocation.
 
 ```toml
 [job.per-package]
@@ -951,7 +1140,7 @@ cooldown_period = "7d"
 The command writes fragments using the normal `[job.<name>]` syntax, e.g.
 
 ```toml
-# $REPOACTIVE_JOBS_DIR/pkg-a.toml
+# $RA_JOBS_DIR/pkg-a.toml
 [job.upgrade-pkg-a]
 command = "uv lock --upgrade --package pkg-a"
 title = "build: upgrade pkg-a"

{repoactive-0.2.8.dev2 → repoactive-0.3.1.dev1}/pyproject.toml

@@ -10,7 +10,7 @@ only-include = ["src"]
 
 [project]
 name = "repoactive"
-version = "0.2.8.dev2"
+version = "0.3.1.dev1"
 description = "Script-driven code changes with automated merge requests"
 readme = "README.md"
 requires-python = ">=3.11"

repoactive-0.3.1.dev1/src/repoactive/boxquote.py

@@ -0,0 +1,51 @@
+"""Render and strip boxquote.el-style boxes used to embed command output in messages."""
+
+import re
+
+# A boxquote block: a ``,----`` opening line through its closing ``` `---- ``` line.
+# DOTALL lets ``.*?`` span the body lines; MULTILINE anchors both delimiters to a
+# line of their own. Non-greedy so each block stops at its own closing line.
+_BOXQUOTE_BLOCK = re.compile(r"^,----.*?^`----[ \t]*$", re.MULTILINE | re.DOTALL)
+
+
+def boxquote(msg: str, title: str = "") -> str:
+    """Render ``msg`` inside a boxquote.el-style box.
+
+    The box opens with ``,----[ title ]`` (or just ``,----`` when ``title`` is
+    empty), each line of ``msg`` is prefixed with ``| ``, and the box closes
+    with ``` `---- ```.
+
+    A multi-line ``title`` (e.g. a multi-line job command) is bracketed across
+    several lines instead of jammed onto the opening line: the first title line
+    follows ``,----[ ``, the remaining lines are ``|``-prefixed and indented to
+    align under that first line, the closing ``]`` trails the last of them, and
+    a blank ``|`` line then separates the bracketed title from ``msg``. A
+    trailing newline on ``title`` is dropped so it does not produce an empty
+    final title line.
+    """
+    body = "\n".join(f"| {line}" for line in msg.splitlines())
+    title = title.rstrip("\n")
+    if "\n" not in title:
+        top = f",----[ {title} ]" if title else ",----"
+        return f"{top}\n{body}\n`----"
+    open_bracket = ",----[ "
+    # Indent continuation lines so the title text aligns under the first line;
+    # the "|" replaces the leading "," so the bar still runs down the left edge.
+    indent = "|" + " " * (len(open_bracket) - 1)
+    head, *rest = title.split("\n")
+    header_lines = [f"{open_bracket}{head}", *(f"{indent}{line}" for line in rest[:-1])]
+    header_lines.append(f"{indent}{rest[-1]} ]")
+    header = "\n".join(header_lines)
+    return f"{header}\n|\n{body}\n`----"
+
+
+def strip_boxquotes(text: str) -> str:
+    """Remove every boxquote block (see :func:`boxquote`) from ``text``.
+
+    A block runs from a ``,----`` opening line to its closing ``` `---- ``` line;
+    the surrounding text is kept. Blank lines exposed by a removed block are
+    collapsed so paragraphs stay separated by a single blank line, and leading
+    and trailing blank lines are trimmed.
+    """
+    without = _BOXQUOTE_BLOCK.sub("", text)
+    return re.sub(r"\n{3,}", "\n\n", without).strip("\n")

{repoactive-0.2.8.dev2 → repoactive-0.3.1.dev1}/src/repoactive/config.py

@@ -33,7 +33,12 @@ logger = logging.getLogger(__name__)
 _DURATION_RE = re.compile(r"^(\d+)([smhdw])$")
 _JOB_NAME_RE = re.compile(r"^[A-Za-z0-9_-]+$")
 _TAG_RE = re.compile(r"^[A-Za-z0-9_-]+$")
-_BRANCH_PREFIX_RE = re.compile(r"^(?!/)(?!.*//)[a-zA-Z0-9_\-/]+$")
+# Environment-variable name grammar for secret_env entries. The RA_ and
+# REPOACTIVE_ prefixes are repoactive's own (ADR 0016) and are rejected.
+_ENV_NAME_RE = re.compile(r"^[A-Za-z_][A-Za-z0-9_]*$")
+_RESERVED_ENV_PREFIXES = ("RA_", "REPOACTIVE_")
+# An empty prefix is allowed (branch name == job name); hence * not +.
+_BRANCH_PREFIX_RE = re.compile(r"^(?!/)(?!.*//)[a-zA-Z0-9_\-/]*$")
 _DURATION_UNITS = {"s": "seconds", "m": "minutes", "h": "hours", "d": "days", "w": "weeks"}
 
 # Reserved tags driving job selection. A plain job carries DEFAULT_TAG, which is
@@ -63,6 +68,17 @@ class InvalidBranchPrefixError(ValueError):
         )
 
 
+class InvalidShellError(ValueError):
+    """Raised when a shell value is not a single interpreter binary."""
+
+    def __init__(self, value: str) -> None:
+        super().__init__(
+            f"invalid shell {value!r}: must be a single interpreter binary "
+            "(a name resolved on PATH like 'bash', or an absolute path); "
+            "arguments are not allowed"
+        )
+
+
 class InvalidJobNameError(ValueError):
     """Raised when a job name contains disallowed characters."""
 
@@ -79,6 +95,27 @@ class InvalidTagError(ValueError):
         super().__init__(f"invalid tag {tag!r}: only letters, digits, '-', and '_' are allowed")
 
 
+class InvalidSecretEnvNameError(ValueError):
+    """Raised when a secret_env entry is not a valid environment-variable name."""
+
+    def __init__(self, name: str) -> None:
+        super().__init__(
+            f"invalid secret_env name {name!r}: must be a valid environment-variable name "
+            "(letters, digits, and '_', not starting with a digit)"
+        )
+
+
+class ReservedSecretEnvNameError(ValueError):
+    """Raised when a secret_env entry uses a prefix reserved for repoactive."""
+
+    def __init__(self, name: str) -> None:
+        super().__init__(
+            f"invalid secret_env name {name!r}: the "
+            f"{' and '.join(_RESERVED_ENV_PREFIXES)} prefixes are reserved for repoactive "
+            "(see docs/adr/0016-injected-env-var-prefix.md)"
+        )
+
+
 class NewlineInTitleError(ValueError):
     """Raised when a title or prefix field contains a newline character."""
 
@@ -157,6 +194,20 @@ class GeneratedByInBodyError(ValueError):
         )
 
 
+class ConfigSourceDirInBodyError(ValueError):
+    """Raised when a [job.<name>] table sets a 'config_source_dir' field.
+
+    'config_source_dir' is set by repoactive to the directory of the config
+    source that defined the job's command; it is not a user-facing config field.
+    """
+
+    def __init__(self, name: str) -> None:
+        super().__init__(
+            f"job {name!r} must not set 'config_source_dir'; "
+            "that field is set by repoactive to the job's config directory"
+        )
+
+
 class DuplicatePlatformHostError(ValueError):
     """Raised when two platforms resolve to the same host.
 
@@ -235,6 +286,16 @@ def _validate_duration(value: str) -> str:
     return value
 
 
+def _validate_shell(value: str) -> str:
+    # The value maps to subprocess' executable= (run as `<shell> -c <command>`),
+    # so it must be a single binary, not an argv with flags. Reject empty and any
+    # whitespace so a "full argv" like "bash -e" fails at config load instead of
+    # silently looking up a binary literally named "bash -e".
+    if not value or any(c.isspace() for c in value):
+        raise InvalidShellError(value)
+    return value
+
+
 def _validate_single_line(value: str, info: ValidationInfo) -> str:
     if "\n" in value:
         assert info.field_name is not None
@@ -242,8 +303,19 @@ def _validate_single_line(value: str, info: ValidationInfo) -> str:
     return value
 
 
+def _validate_secret_env(value: list[str]) -> list[str]:
+    for name in value:
+        if not _ENV_NAME_RE.match(name):
+            raise InvalidSecretEnvNameError(name)
+        if name.startswith(_RESERVED_ENV_PREFIXES):
+            raise ReservedSecretEnvNameError(name)
+    return value
+
+
 _BranchPrefix = Annotated[str, AfterValidator(_validate_branch_prefix)]
 _Duration = Annotated[str, AfterValidator(_validate_duration)]
+_Shell = Annotated[str, AfterValidator(_validate_shell)]
+_SecretEnv = Annotated[list[str], AfterValidator(_validate_secret_env)]
 # Titles and title prefixes end up in commit subjects and MR titles, which are
 # single-line by nature.
 _SingleLine = Annotated[str, AfterValidator(_validate_single_line)]
@@ -265,6 +337,16 @@ class JobDefaults(BaseModel):
     timeout: _Duration | None = "2m"
     auto_merge: bool = False
     required_approvals: int | None = Field(default=None, ge=0)
+    # Interpreter for job commands, passed to subprocess as executable= and run as
+    # `<shell> -c <command>`. None means /bin/sh (the shell=True default). May be a
+    # bare name resolved on PATH (e.g. "bash") or an absolute path.
+    shell: _Shell | None = None
+    # Names of environment variables to mark as secrets config-wide: each is
+    # stripped from every job command's environment, but a job still reads one
+    # only by listing it in its own secret_env. Marks names, never grants them;
+    # deliberately not inherited into jobs like the defaulted fields above. See
+    # docs/adr/0017-secret-env-redaction.md.
+    secret_env: _SecretEnv = Field(default_factory=list)
 
 
 # Fields Job.resolve fills in from JobDefaults when the job does not set them
@@ -278,6 +360,7 @@ _DEFAULTED_FIELDS = (
     "timeout",
     "auto_merge",
     "required_approvals",
+    "shell",
 )
 
 
@@ -286,6 +369,12 @@ class Job(BaseModel):
 
     name: str
     command: str
+    # Names of environment variables holding secrets this job's command may read.
+    # A name listed in any secret_env (here, another job's, or job-defaults') is
+    # stripped from every command's base environment; only a job that lists a name
+    # here has that variable injected back for its own command. See
+    # docs/adr/0017-secret-env-redaction.md.
+    secret_env: _SecretEnv = Field(default_factory=list)
     title: _SingleLine
     description: str | None = None
     base_branch: str | None = None
@@ -303,13 +392,18 @@ class Job(BaseModel):
     output_in_commit: bool = True
     # When true, the command does not produce a diff to commit; instead it writes
     # one or more *.toml job fragments into the directory named by the
-    # REPOACTIVE_JOBS_DIR environment variable, and those jobs are run in the same
+    # RA_JOBS_DIR environment variable, and those jobs are run in the same
     # invocation. See docs/adr/0004-job-generators.md.
     emits_jobs: bool = False
     # Set by repoactive (never written in config) on jobs produced by a generator:
     # the generator's name, recorded as a second Repoactive-Job trailer so the
     # generator gets a meaningful cooldown over the whole fan-out.
     generated_by: str | None = None
+    # Set by repoactive (never written in config): the absolute directory of the
+    # config source that defined this job's command, exported to the command as
+    # RA_CONFIG_SOURCE_DIR so it can reach files kept beside its config. None when
+    # the command came from a --set override or the built-in defaults.
+    config_source_dir: str | None = None
 
     # the following fields will be resolved from the defaults
     branch_prefix: _BranchPrefix | None = None
@@ -320,6 +414,7 @@ class Job(BaseModel):
     timeout: _Duration | None = None
     auto_merge: bool | None = None
     required_approvals: int | None = Field(default=None, ge=0)
+    shell: _Shell | None = None
 
     @field_validator("name")
     @classmethod
@@ -432,6 +527,8 @@ class Config(BaseModel):
                 raise JobNameInBodyError(name)
             if "generated_by" in body:
                 raise GeneratedByInBodyError(name)
+            if "config_source_dir" in body:
+                raise ConfigSourceDirInBodyError(name)
             jobs.append({**body, "name": name})
         return jobs
 
@@ -517,8 +614,18 @@ class Config(BaseModel):
         return {job.branch_name() for job in self._resolved_jobs()}
 
     def base_branches(self) -> set[str]:
-        """All branches a job uses as base_branch."""
-        return {job.base_branch for job in self._resolved_jobs() if job.base_branch}
+        """Bookmark names a job uses as base_branch.
+
+        These are the branches to track with ``jj bookmark track``. Values that
+        look like a revset function call (``trunk()``, ``root()``, or a
+        user-defined revset alias) are excluded: they are valid base branches but
+        not bookmarks, so tracking them would fail.
+        """
+        return {
+            job.base_branch
+            for job in self._resolved_jobs()
+            if job.base_branch and "()" not in job.base_branch
+        }
 
     def token_env_names(self) -> set[str]:
         """Names of the env vars holding platform API tokens.
@@ -529,6 +636,19 @@ class Config(BaseModel):
         """
         return {p.token_env for p in self.platforms}
 
+    def marked_secret_names(self) -> set[str]:
+        """Names marked as managed secrets: every secret_env in the merged config.
+
+        The union of ``job-defaults`` and every job's ``secret_env``. A marked
+        name is stripped from every job command's base environment; a job reads
+        it back only by listing it in its own ``secret_env`` (see
+        runner._run_command and docs/adr/0017-secret-env-redaction.md).
+        """
+        names = set(self.job_defaults.secret_env)
+        for job in self.jobs:
+            names.update(job.secret_env)
+        return names
+
 
 class ConfigShape(BaseModel):
     """Structural shape of a raw config source, validated before merging.
@@ -657,6 +777,10 @@ class _ConfigSource:
 
     label: str
     data: dict
+    # Absolute directory of the file this source was read from, or None for
+    # sources without a file (built-in defaults, --set overrides). Exposed to a
+    # command as RA_CONFIG_SOURCE_DIR for the job whose command this source sets.
+    source_dir: Path | None = None
 
 
 def _built_in_defaults() -> list[_ConfigSource]:
@@ -693,7 +817,9 @@ def _parse_override(text: str) -> _ConfigSource:
 
 def _read_toml_file(path: Path) -> _ConfigSource:
     try:
-        return _ConfigSource(str(path), tomllib.loads(path.read_text()))
+        return _ConfigSource(
+            str(path), tomllib.loads(path.read_text()), source_dir=path.resolve().parent
+        )
     except (OSError, tomllib.TOMLDecodeError) as e:
         raise ConfigError(str(path), e) from e
 
@@ -710,12 +836,19 @@ def load_config(paths: list[Path], overrides: list[str] | None = None) -> Config
 
 def _merge_config(sources: Iterable[_ConfigSource]) -> Config:
     merged = {}
+    # Directory of the config source that last set each job's command, keyed by
+    # job name. Exported to the command as RA_CONFIG_SOURCE_DIR (see
+    # Job.config_source_dir). None when that source has no file (--set, built-in).
+    command_source_dir: dict[str, Path | None] = {}
     for source in sources:
         data = source.data
         try:
             # Reject odd shapes (e.g. job.foo = "hello") up front; the merge
             # helpers assume tables of tables and would fail cryptically.
             shape = ConfigShape.model_validate(data)
+            for name, body in shape.job.items():
+                if "command" in body:
+                    command_source_dir[name] = source.source_dir
             jobs = merge_jobs(base=merged.get("job", {}), override=shape.job)
             platforms = merge_platforms(
                 base=merged.get("platform", {}),
@@ -732,5 +865,18 @@ def _merge_config(sources: Iterable[_ConfigSource]) -> Config:
         except (ValueError, ValidationError) as e:
             raise ConfigError(source.label, e) from e
     config = Config.model_validate(merged)
+    # Stamp each job with the directory of the source that defined its command.
+    # Done after validation (not injected into the raw table) so it bypasses the
+    # ConfigSourceDirInBodyError guard, which only rejects user-written values.
+    config = config.model_copy(
+        update={
+            "jobs": [
+                job.model_copy(update={"config_source_dir": str(command_source_dir[job.name])})
+                if command_source_dir.get(job.name) is not None
+                else job
+                for job in config.jobs
+            ]
+        }
+    )
     logger.debug("loaded config: %s", config.model_dump_json(indent=2))
     return config

{repoactive-0.2.8.dev2 → repoactive-0.3.1.dev1}/src/repoactive/runner.py

@@ -49,7 +49,37 @@ logger = logging.getLogger(__name__)
 
 # Environment variable naming the directory a generator (``emits_jobs``) command
 # writes its ``*.toml`` job fragments into. See docs/adr/0004-job-generators.md.
-REPOACTIVE_JOBS_DIR_ENV = "REPOACTIVE_JOBS_DIR"
+RA_JOBS_DIR_ENV = "RA_JOBS_DIR"
+
+# Environment variable exposing to a job command the directory of the config
+# source that defined the command (Job.config_source_dir), so the command can
+# reach files kept beside its config. See docs/adr/0016-injected-env-var-prefix.md.
+RA_CONFIG_SOURCE_DIR_ENV = "RA_CONFIG_SOURCE_DIR"
+
+# Environment variable exposing to a job command the throwaway jj workspace
+# repoactive created for it. This is always the command's working directory, but
+# naming it explicitly lets a command that changes directory find its way back.
+RA_WORKSPACE_DIR_ENV = "RA_WORKSPACE_DIR"
+
+# Environment variable exposing to a job command the bookmark/branch repoactive
+# uses for the job's output (Job.branch_name). The command runs on a fresh commit
+# while this bookmark still points at the previous run's commit, so the command
+# can inspect what it produced last time (e.g. `git diff $RA_JOB_BRANCH`). The
+# bookmark may not exist yet: a first run, a run that produced no diff, or a
+# generator never creates it.
+RA_JOB_BRANCH_ENV = "RA_JOB_BRANCH"
+
+# Environment variable exposing to a job command the name of the job it belongs
+# to (Job.name), so a command shared by several jobs can tell which one is
+# running (e.g. to label its output).
+RA_JOB_NAME_ENV = "RA_JOB_NAME"
+
+# Environment variable exposing to a job command the branch the job's MR targets
+# (Job.base_branch, or "trunk()" by default), so a command can diff against its
+# target (e.g. `git diff $RA_JOB_BASE_BRANCH`). This is the *configured* base; for a
+# stacked job (depends_on) the immediate parent commit is another job's output,
+# not this value.
+RA_JOB_BASE_BRANCH_ENV = "RA_JOB_BASE_BRANCH"
 
 # Fields an emitted job inherits from its generator when the emitted entry does
 # not set them itself (``tags`` and ``depends_on`` are handled separately because
@@ -100,6 +130,18 @@ class CommandError(RuntimeError):
         self.elapsed = elapsed
 
 
+class MissingSecretError(RuntimeError):
+    """A job granted a secret_env variable that is unset in repoactive's environment.
+
+    Raised before the command runs so the failure is legible (ADR 0017) instead
+    of surfacing as an obscure command error later.
+    """
+
+    def __init__(self, name: str) -> None:
+        super().__init__(f"requires secret {name}, not set")
+        self.name = name
+
+
 class GeneratedJobError(ValueError):
     """Raised when a generator emits an invalid job set.
 
@@ -206,10 +248,12 @@ class RunContext:
     plan: UpdatePlan = field(default_factory=UpdatePlan)
 
     @property
-    def secret_env_names(self) -> frozenset[str]:
-        # Token vars stripped from every job command's environment so a command
-        # cannot read the credential repoactive uses to push/create MRs.
-        return frozenset(self.config.token_env_names())
+    def stripped_env_names(self) -> frozenset[str]:
+        # Names removed from every job command's base environment: the platform
+        # tokens (ADR 0006) plus every marked secret (ADR 0017). A job reads a
+        # marked secret back only by granting it in its own secret_env; see
+        # _resolve_granted_secrets.
+        return frozenset(self.config.token_env_names() | self.config.marked_secret_names())
 
 
 def _compute_parents(job: Job, results: dict[str, JobResult]) -> list[str]:
@@ -238,22 +282,63 @@ def _kill_process_group(proc: subprocess.Popen[str]) -> None:
 
 
 def _command_env(
-    *, extra_env: dict[str, str] | None, secret_env_names: frozenset[str]
+    *,
+    extra_env: dict[str, str] | None,
+    stripped_env_names: frozenset[str],
+    granted_secret_env: dict[str, str] | None = None,
 ) -> dict[str, str]:
     """Build the environment a job command runs in.
 
     Starts from the inherited environment (so the command still sees PATH etc.),
-    drops the platform token variables (``secret_env_names``) so a command cannot read
-    the credential repoactive uses to push/create MRs, then layers on ``extra_env``
-    (e.g. REPOACTIVE_JOBS_DIR for a generator). See
-    docs/adr/0006-job-commands-are-trusted.md.
+    drops ``stripped_env_names`` (the platform tokens of ADR 0006 plus every
+    marked secret of ADR 0017), injects back only the secrets this job granted
+    (``granted_secret_env``), then layers on ``extra_env`` (the RA_* variables,
+    e.g. RA_JOBS_DIR for a generator) last so repoactive's own variables win.
     """
-    env = {k: v for k, v in os.environ.items() if k not in secret_env_names}
+    env = {k: v for k, v in os.environ.items() if k not in stripped_env_names}
+    if granted_secret_env:
+        env.update(granted_secret_env)
     if extra_env:
         env.update(extra_env)
     return env
 
 
+def _resolve_granted_secrets(job: Job) -> dict[str, str]:
+    """Values for the secrets ``job`` grants, read from repoactive's own environment.
+
+    Only the names in the job's own ``secret_env`` are granted; ``job-defaults``
+    marks names but grants to no job (ADR 0017). Raises MissingSecretError on the
+    first granted name that is unset, so a misconfigured job fails legibly before
+    its command runs rather than deep inside it.
+    """
+    granted: dict[str, str] = {}
+    for name in job.secret_env:
+        try:
+            granted[name] = os.environ[name]
+        except KeyError:
+            raise MissingSecretError(name) from None
+    return granted
+
+
+def _job_extra_env(job: Job, extra: dict[str, str] | None = None) -> dict[str, str]:
+    """Extra environment for ``job``'s command: its name, branches, config dir, ``extra``.
+
+    Always adds RA_JOB_NAME (the job's name), RA_JOB_BRANCH (the bookmark
+    repoactive uses for the job's output), and RA_JOB_BASE_BRANCH (the branch the
+    job's MR targets). Adds RA_CONFIG_SOURCE_DIR when the job has a
+    ``config_source_dir`` (the directory of the config source that defined its
+    command), on top of any caller-supplied entries (e.g. RA_JOBS_DIR for a
+    generator).
+    """
+    env = dict(extra or {})
+    env[RA_JOB_NAME_ENV] = job.name
+    env[RA_JOB_BRANCH_ENV] = job.branch_name()
+    env[RA_JOB_BASE_BRANCH_ENV] = job.base_branch or "trunk()"
+    if job.config_source_dir is not None:
+        env[RA_CONFIG_SOURCE_DIR_ENV] = job.config_source_dir
+    return env
+
+
 @contextlib.contextmanager
 def _watchdog(proc: subprocess.Popen[str], timeout: float | None) -> Generator[threading.Event]:
     """Kill ``proc``'s process group if it outlives ``timeout`` seconds.
@@ -298,6 +383,9 @@ def _spawn(job: Job, cwd: Path, env: dict[str, str]) -> Generator[subprocess.Pop
     proc = subprocess.Popen(
         job.command,
         shell=True,
+        # None keeps subprocess' shell=True default of /bin/sh; a configured shell
+        # runs the command as `<shell> -c <command>` (see Job.shell).
+        executable=job.shell,
         cwd=cwd,
         stdout=subprocess.PIPE,
         stderr=subprocess.STDOUT,
@@ -323,11 +411,19 @@ def _run_command(
     job: Job,
     cwd: Path,
     *,
-    secret_env_names: frozenset[str] = frozenset(),
+    stripped_env_names: frozenset[str] = frozenset(),
     extra_env: dict[str, str] | None = None,
 ) -> CommandResult:
     start = time.monotonic()
-    env = _command_env(extra_env=extra_env, secret_env_names=secret_env_names)
+    # Fail before the command runs if a granted secret is unset (ADR 0017).
+    granted_secret_env = _resolve_granted_secrets(job)
+    # The workspace is always cwd, but expose it explicitly so a command that
+    # cd's elsewhere can still find the workspace repoactive prepared for it.
+    env = _command_env(
+        extra_env={**(extra_env or {}), RA_WORKSPACE_DIR_ENV: str(cwd)},
+        stripped_env_names=stripped_env_names,
+        granted_secret_env=granted_secret_env,
+    )
 
     # Stream the merged stdout/stderr line by line: keep the full output (needed
     # for the commit message and the success result) while feeding a live tail of
@@ -498,7 +594,12 @@ def run_job(
         repo.git_sync_head()
         logger.debug("[%s] running command: %s", job.name, job.command)
         try:
-            command_result = _run_command(job, repo.cwd, secret_env_names=ctx.secret_env_names)
+            command_result = _run_command(
+                job,
+                repo.cwd,
+                stripped_env_names=ctx.stripped_env_names,
+                extra_env=_job_extra_env(job),
+            )
         except CommandError:
             # The command timed out or failed; discard only the fresh commit.
             # The old bookmark is completely unaffected.
@@ -544,16 +645,23 @@ def _load_job_specs(jobs_dir: Path) -> dict[str, dict]:
     return specs
 
 
-def _build_generated_job(
-    *, generator: Job, name: str, spec: dict, run_names: set[str], all_config_names: set[str]
+def _build_generated_job(  # noqa: PLR0913
+    *,
+    generator: Job,
+    name: str,
+    spec: dict,
+    run_names: set[str],
+    all_config_names: set[str],
+    marked_secret_names: frozenset[str],
 ) -> Job:
     """Build one emitted ``Job`` from its raw spec, applying inheritance.
 
     ``name`` is the spec's table key. The job inherits the (resolved) generator's
     tags, ``depends_on`` and the ``_INHERITED_FIELDS`` unless the spec overrides
     them, and records the generator in ``generated_by``. Raises GeneratedJobError
-    on a name colliding with an existing job, a nested generator, or a job that
-    fails validation.
+    on a name colliding with an existing job, a nested generator, a job that
+    fails validation, or a ``secret_env`` naming a secret the static config did
+    not already mark (``marked_secret_names``).
     """
     if name in run_names or name in all_config_names:
         raise GeneratedJobError(
@@ -571,14 +679,36 @@ def _build_generated_job(
     for f in _INHERITED_FIELDS:
         merged.setdefault(f, getattr(generator, f))
     merged["generated_by"] = generator.name
+    # The generator's fragments live in a throwaway temp dir, so an emitted job's
+    # meaningful config location is the generator's own config source.
+    merged["config_source_dir"] = generator.config_source_dir
     try:
-        return Job.model_validate(merged)
+        job = Job.model_validate(merged)
     except ValidationError as e:
         raise GeneratedJobError(generator.name, f"emitted job {name!r} is invalid: {e}") from e
+    # A generated job may only grant secrets the static config already marked. The
+    # env strip set is derived from the static config (RunContext.stripped_env_names),
+    # so a secret first introduced by an emitted job would not be stripped from the
+    # other jobs' environments; requiring it be marked up front (e.g. in
+    # [job-defaults].secret_env or on the generator) keeps a secret out of every job
+    # that did not grant it. See docs/adr/0017-secret-env-redaction.md.
+    unmarked = sorted(set(job.secret_env) - marked_secret_names)
+    if unmarked:
+        raise GeneratedJobError(
+            generator.name,
+            f"emitted job {name!r} grants secret(s) not marked in the static config: "
+            f"{unmarked}; add them to [job-defaults].secret_env or the generator's secret_env",
+        )
+    return job
 
 
 def _build_generated_jobs(
-    *, generator: Job, specs: dict[str, dict], run_names: set[str], all_config_names: set[str]
+    *,
+    generator: Job,
+    specs: dict[str, dict],
+    run_names: set[str],
+    all_config_names: set[str],
+    marked_secret_names: frozenset[str] = frozenset(),
 ) -> list[Job]:
     """Turn a generator's raw specs into validated ``Job`` objects.
 
@@ -595,6 +725,7 @@ def _build_generated_jobs(
             spec=spec,
             run_names=run_names,
             all_config_names=all_config_names,
+            marked_secret_names=marked_secret_names,
         )
         for name, spec in specs.items()
     ]
@@ -785,7 +916,7 @@ def _run_generator_job(
     """Run a generator and return its emitted jobs (resolved ``job`` required).
 
     The command runs in a fresh workspace on top of ``parents`` with
-    ``REPOACTIVE_JOBS_DIR`` pointing at an empty directory; it writes ``*.toml``
+    ``RA_JOBS_DIR`` pointing at an empty directory; it writes ``*.toml``
     fragments there which are parsed once it exits. The generator itself produces
     no diff: any working-copy change it leaves is discarded (ADR 0004), and a
     no-op ``JobResult`` is recorded so its emitted jobs (which depend on it)
@@ -807,8 +938,8 @@ def _run_generator_job(
             _run_command(
                 job,
                 repo.cwd,
-                secret_env_names=ctx.secret_env_names,
-                extra_env={REPOACTIVE_JOBS_DIR_ENV: str(jobs_dir)},
+                stripped_env_names=ctx.stripped_env_names,
+                extra_env=_job_extra_env(job, {RA_JOBS_DIR_ENV: str(jobs_dir)}),
             )
             specs = _load_job_specs(jobs_dir)
         finally:
@@ -821,6 +952,7 @@ def _run_generator_job(
         specs=specs,
         run_names={j.name for j in ctx.selection.jobs},
         all_config_names={j.name for j in ctx.config.jobs},
+        marked_secret_names=frozenset(ctx.config.marked_secret_names()),
     )
 
     names = ", ".join(j.name for j in emitted) if emitted else "none"

repoactive-0.2.8.dev2/src/repoactive/boxquote.py

@@ -1,32 +0,0 @@
-"""Render and strip boxquote.el-style boxes used to embed command output in messages."""
-
-import re
-
-# A boxquote block: a ``,----`` opening line through its closing ``` `---- ``` line.
-# DOTALL lets ``.*?`` span the body lines; MULTILINE anchors both delimiters to a
-# line of their own. Non-greedy so each block stops at its own closing line.
-_BOXQUOTE_BLOCK = re.compile(r"^,----.*?^`----[ \t]*$", re.MULTILINE | re.DOTALL)
-
-
-def boxquote(msg: str, title: str = "") -> str:
-    """Render ``msg`` inside a boxquote.el-style box.
-
-    The first line is ``,----[ title ]`` (or just ``,----`` when ``title`` is
-    empty), each line of ``msg`` is prefixed with ``| ``, and the box closes
-    with ``` `---- ```.
-    """
-    top = f",----[ {title} ]" if title else ",----"
-    body = "\n".join(f"| {line}" for line in msg.splitlines())
-    return f"{top}\n{body}\n`----"
-
-
-def strip_boxquotes(text: str) -> str:
-    """Remove every boxquote block (see :func:`boxquote`) from ``text``.
-
-    A block runs from a ``,----`` opening line to its closing ``` `---- ``` line;
-    the surrounding text is kept. Blank lines exposed by a removed block are
-    collapsed so paragraphs stay separated by a single blank line, and leading
-    and trailing blank lines are trimmed.
-    """
-    without = _BOXQUOTE_BLOCK.sub("", text)
-    return re.sub(r"\n{3,}", "\n\n", without).strip("\n")