repoactive 0.2.8.dev2__tar.gz → 0.3.0__tar.gz

{repoactive-0.2.8.dev2 → repoactive-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: repoactive
-Version: 0.2.8.dev2
+Version: 0.3.0
 Summary: Script-driven code changes with automated merge requests
 License-Expression: GPL-3.0-or-later
 License-File: LICENSE
@@ -55,6 +55,7 @@ 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)
   - [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 +468,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 +489,10 @@ 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.
 
 ### `[job.<name>]`
 
@@ -518,7 +527,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 +563,12 @@ 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).
 
 ### Stacking MRs
 
@@ -658,6 +671,105 @@ 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.
+
 ### Overriding values on the command line
 
 `--set NAME=VALUE`/`-s` tweaks individual config values without editing a
@@ -831,12 +943,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 +1074,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 +1090,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.0}/README.md

@@ -28,6 +28,7 @@ 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)
   - [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 +441,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 +462,10 @@ 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.
 
 ### `[job.<name>]`
 
@@ -491,7 +500,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 +536,12 @@ 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).
 
 ### Stacking MRs
 
@@ -631,6 +644,105 @@ 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.
+
 ### Overriding values on the command line
 
 `--set NAME=VALUE`/`-s` tweaks individual config values without editing a
@@ -804,12 +916,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 +1047,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 +1063,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.0}/pyproject.toml

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

repoactive-0.3.0/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.0}/src/repoactive/config.py

@@ -33,7 +33,8 @@ 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_\-/]+$")
+# 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 +64,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."""
 
@@ -157,6 +169,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 +261,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
@@ -244,6 +280,7 @@ def _validate_single_line(value: str, info: ValidationInfo) -> str:
 
 _BranchPrefix = Annotated[str, AfterValidator(_validate_branch_prefix)]
 _Duration = Annotated[str, AfterValidator(_validate_duration)]
+_Shell = Annotated[str, AfterValidator(_validate_shell)]
 # 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 +302,10 @@ 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
 
 
 # Fields Job.resolve fills in from JobDefaults when the job does not set them
@@ -278,6 +319,7 @@ _DEFAULTED_FIELDS = (
     "timeout",
     "auto_merge",
     "required_approvals",
+    "shell",
 )
 
 
@@ -303,13 +345,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 +367,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 +480,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 +567,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.
@@ -657,6 +717,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 +757,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 +776,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 +805,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.0}/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
@@ -245,7 +275,7 @@ def _command_env(
     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
+    (e.g. RA_JOBS_DIR for a generator). See
     docs/adr/0006-job-commands-are-trusted.md.
     """
     env = {k: v for k, v in os.environ.items() if k not in secret_env_names}
@@ -254,6 +284,25 @@ def _command_env(
     return env
 
 
+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 +347,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,
@@ -327,7 +379,12 @@ def _run_command(
     extra_env: dict[str, str] | None = None,
 ) -> CommandResult:
     start = time.monotonic()
-    env = _command_env(extra_env=extra_env, secret_env_names=secret_env_names)
+    # 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)},
+        secret_env_names=secret_env_names,
+    )
 
     # 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 +555,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,
+                secret_env_names=ctx.secret_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.
@@ -571,6 +633,9 @@ 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)
     except ValidationError as e:
@@ -785,7 +850,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)
@@ -808,7 +873,7 @@ def _run_generator_job(
                 job,
                 repo.cwd,
                 secret_env_names=ctx.secret_env_names,
-                extra_env={REPOACTIVE_JOBS_DIR_ENV: str(jobs_dir)},
+                extra_env=_job_extra_env(job, {RA_JOBS_DIR_ENV: str(jobs_dir)}),
             )
             specs = _load_job_specs(jobs_dir)
         finally:

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")