repoactive 0.4.0.dev1__tar.gz → 0.4.2__tar.gz

{repoactive-0.4.0.dev1 → repoactive-0.4.2}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: repoactive
-Version: 0.4.0.dev1
+Version: 0.4.2
 Summary: Script-driven code changes with automated merge requests
 License-Expression: GPL-3.0-or-later
 License-File: LICENSE
@@ -68,10 +68,12 @@ request (MR) throughout; on GitHub, read that as pull request (PR).
   - [Example](#example)
   - [`[platform.<name>]`](#platformname)
   - [Config file locations](#config-file-locations)
+  - [Reading configuration from a revset](#reading-configuration-from-a-revset)
   - [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)
 - [Run control](#run-control)
+  - [Running a command ad-hoc](#running-a-command-ad-hoc)
   - [Selecting jobs with tags](#selecting-jobs-with-tags)
   - [Disabling jobs](#disabling-jobs)
   - [Running a job on a schedule](#running-a-job-on-a-schedule)
@@ -274,6 +276,10 @@ plus the `Repoactive-Job` trailer that
 Repoactive-Job: uv-lock-upgrade
 ```
 
+Output above 32 KiB is truncated: the start and the end are kept and the
+middle is replaced by a line naming how many characters went. A command that
+_fails_ is still reported in full on the terminal.
+
 ### Keeping the local clone current
 
 `repoactive` works entirely from the **local** repository view and never
@@ -313,11 +319,11 @@ repoactive --version
 Every command that works against a repository accepts `--repo`/`-r` and
 `--debug`/`-d`. The commands that read configuration - `run`,
 `validate-config`, `info jobs`, and `info tags` - also accept the same
-`--config`/`-c` and `--set`/`-s` options, described in the
-[`repoactive run`](#repoactive-run) table below. `recent-commits` works from
-the repository alone and reads no configuration;
-[`dump-schema`](#repoactive-dump-schema) touches no repository at all and
-takes only `--output`.
+`--config`/`-c`, `--config-revset`, and `--set`/`-s` options, described in
+the [`repoactive run`](#repoactive-run) table below. `--ad-hoc` is specific
+to `run`. `recent-commits` works from the repository alone and reads no
+configuration; [`dump-schema`](#repoactive-dump-schema) touches no
+repository at all and takes only `--output`.
 
 All commands exit with these status codes:
 
@@ -352,6 +358,12 @@ repoactive run --mode push
 # Push branches and create or update merge requests
 repoactive run --mode publish
 
+# Use the configuration as it stands on trunk, whatever is checked out
+repoactive run --config-revset 'trunk()'
+
+# Run a one-off command without configuring a job for it
+repoactive run --ad-hoc 'just flake-update-diff'
+
 # Enable debug logging
 repoactive run --debug
 ```
@@ -359,10 +371,13 @@ repoactive run --debug
 | Option                          | Short | Description                                                                                                                  |
 | ------------------------------- | ----- | ---------------------------------------------------------------------------------------------------------------------------- |
 | `--config PATH`                 | `-c`  | Config file or directory of `*.toml` files; repeat to merge. Default: `.repoactive.d/` and `.repoactive.toml` under `--repo` |
+| `--config-revset REVSET`        |       | Read configuration from the merged tree of `REVSET` instead of from the working copy. Cannot be combined with `--config`     |
 | `--set NAME=VALUE`              | `-s`  | Override a config value (repeatable); `NAME` is a dotted TOML key, `VALUE` a TOML expression. Wins over `--config`           |
 | `--repo PATH`                   | `-r`  | jj repository path (default: `.`)                                                                                            |
 | `--mode [local\|push\|publish]` | `-m`  | How far to publish: `local` (default) applies only locally, `push` also pushes branches, `publish` also creates/updates MRs  |
 | `--tag TAG`                     | `-t`  | Run jobs carrying any of these tags (repeatable). With no tags/jobs the default run targets the `enabled` tag                |
+| `--ad-hoc COMMAND`              |       | Run `COMMAND` as a one-off job, no configuration needed. See [Running a command ad-hoc](#running-a-command-ad-hoc)           |
+| `--ad-hoc-name NAME`            |       | Name the `--ad-hoc` job (and thus its branch). Default: a name derived from the command                                      |
 | `--debug`                       | `-d`  | Enable debug logging                                                                                                         |
 
 ### `repoactive recent-commits`
@@ -689,8 +704,8 @@ underscores.
 - **`commit_title_prefix`** (default: inherited) - Override the commit title
   prefix for this job only.
 - **`output_in_commit`** (default: `true`) - Append the job's command and
-  its captured output to the commit message. Set to `false` to keep the
-  commit message clean.
+  its captured output to the commit message (truncated in the middle above
+  32 KiB). Set to `false` to keep the commit message clean.
 
 **Run control:**
 
@@ -831,6 +846,45 @@ 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`.
 
+### Reading configuration from a revset
+
+By default, the command reads the configuration from the working copy. The
+working copy can contain an incomplete change or an unsuitable revision.
+`--config-revset` creates a temporary jj workspace. The command runs
+`jj new REVSET` in this workspace to merge the revisions. It then discovers
+`.repoactive.d/` and `.repoactive.toml` in the temporary workspace instead
+of under `--repo`.
+
+```bash
+# Always run the configuration that is on trunk, whatever is checked out
+repoactive run --config-revset 'trunk()'
+
+# Preview the configuration a branch would produce once it lands
+repoactive info jobs --config-revset 'trunk() | my-feature-branch'
+```
+
+A revset that selects several revisions produces a merged tree. This
+behavior makes the second example possible. The following rules apply:
+
+- `--config-revset` cannot be combined with `--config`; the combination is
+  rejected. `--set`/`-s` still applies and still wins.
+- Merging the revset's revisions can cause conflicts. `repoactive` warns and
+  names the conflicted files. The command then continues. If a configuration
+  file contains conflict markers, the command cannot parse the file and
+  reports an invalid-configuration error.
+- The option needs jj and a colocated jj repository, even for the read-only
+  commands. A plain git repository is converted with
+  `jj git init --colocate` first - the same conversion a bare
+  `repoactive run` performs, with the same undo hint.
+- Only the _configuration_ comes from the revset. Jobs still run on commits
+  that use `trunk()` or their `base_branch` as the base. The local
+  repository is still the source of truth. Therefore, you must still fetch
+  the clone (see
+  [Keeping the local clone current](#keeping-the-local-clone-current)).
+
+See [ADR 0021](docs/adr/0021-read-config-from-a-revset.md) for the
+reasoning.
+
 ### Variables passed to job commands
 
 `repoactive` injects a few `RA_`-prefixed environment variables into every
@@ -929,6 +983,12 @@ 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.
 
+With [`--config-revset`](#reading-configuration-from-a-revset), the value
+points to the temporary workspace that contains the configuration. The
+workspace exists for the complete run. A command can read files from it. The
+command deletes the workspace when it exits. Files written to the workspace
+do not remain after the command exits.
+
 ### Passing secrets to commands with `secret_env`
 
 A job command inherits `repoactive`'s environment, so a secret exported
@@ -1030,6 +1090,61 @@ The sections below cover the run-control options from the
 [configuration reference](#jobname) in detail: which jobs a run selects, how
 to schedule and throttle them, and how to generate jobs dynamically.
 
+### Running a command ad-hoc
+
+`--ad-hoc COMMAND` runs a single command without writing a job for it. The
+repository needs no `repoactive` configuration at all:
+
+```bash
+repoactive run --ad-hoc 'just flake-update-diff'
+```
+
+`repoactive` builds one job from the command and runs it exactly as if it
+had been configured and named on the command line: the command runs in a
+temporary workspace, its result is committed on the job's own branch, and
+the commit carries the usual `Repoactive-Job` trailer. `--mode push` and
+`--mode publish` work as they do for a configured job.
+
+The job's name (and with it, its branch) is derived from the command: every
+run of characters a job name may not contain becomes a single dash, so
+`just flake-update-diff` produces the branch
+`repoactive/just-flake-update-diff`. The name is deterministic, so running
+the same ad-hoc command again updates that branch instead of opening a
+second one. Pass `--ad-hoc-name` for a name of your own:
+
+```bash
+repoactive run --ad-hoc "sed -i 's/2025/2026/' LICENSE" --ad-hoc-name copyright-year
+```
+
+The commit subject names the command it ran, `Run 'just flake-update-diff'`,
+and carries no `commit_title_prefix`; the merge request title keeps the
+usual `[repoactive] ` prefix.
+
+The remaining rules:
+
+- Configuration is still read when it exists. `[job-defaults]` and
+  `[platform.<name>]` apply to the ad-hoc job, and the configured jobs stay
+  loaded.
+- The ad-hoc job is selected the way a job named on the command line is, so
+  the run is the union of it, any jobs named as arguments, and any `--tag`
+  selection (see [Selecting jobs with tags](#selecting-jobs-with-tags)). On
+  its own, `--ad-hoc` therefore runs that one job and nothing else; combine
+  it with `--tag weekly` and the weekly jobs run too.
+- `--set`/`-s` still wins over everything, so a single field can be tuned in
+  place: `--ad-hoc 'cargo update' -s 'job.cargo-update.timeout = "10m"'`.
+- The name must be free. If a configured job already uses it, `repoactive`
+  says so and stops; `--ad-hoc-name` resolves the clash.
+- The command belongs to no config file, so it gets no
+  [`RA_CONFIG_SOURCE_DIR`](#variables-passed-to-job-commands), just like a
+  command defined through `--set`.
+- Like a job named on the command line, the ad-hoc job runs immediately and
+  ignores any cooldown.
+
+`--ad-hoc` is meant for one-off work and for trying a command out. A command
+worth running repeatedly is worth a [`[job.<name>]`](#jobname) block: a
+readable name, a proper title, tags, and a cooldown. See
+[ADR 0022](docs/adr/0022-ad-hoc-commands.md) for the reasoning.
+
 ### Selecting jobs with tags
 
 Which jobs a `repoactive run` touches is decided by **tags**. Every job has

{repoactive-0.4.0.dev1 → repoactive-0.4.2}/README.md

@@ -40,10 +40,12 @@ request (MR) throughout; on GitHub, read that as pull request (PR).
   - [Example](#example)
   - [`[platform.<name>]`](#platformname)
   - [Config file locations](#config-file-locations)
+  - [Reading configuration from a revset](#reading-configuration-from-a-revset)
   - [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)
 - [Run control](#run-control)
+  - [Running a command ad-hoc](#running-a-command-ad-hoc)
   - [Selecting jobs with tags](#selecting-jobs-with-tags)
   - [Disabling jobs](#disabling-jobs)
   - [Running a job on a schedule](#running-a-job-on-a-schedule)
@@ -246,6 +248,10 @@ plus the `Repoactive-Job` trailer that
 Repoactive-Job: uv-lock-upgrade
 ```
 
+Output above 32 KiB is truncated: the start and the end are kept and the
+middle is replaced by a line naming how many characters went. A command that
+_fails_ is still reported in full on the terminal.
+
 ### Keeping the local clone current
 
 `repoactive` works entirely from the **local** repository view and never
@@ -285,11 +291,11 @@ repoactive --version
 Every command that works against a repository accepts `--repo`/`-r` and
 `--debug`/`-d`. The commands that read configuration - `run`,
 `validate-config`, `info jobs`, and `info tags` - also accept the same
-`--config`/`-c` and `--set`/`-s` options, described in the
-[`repoactive run`](#repoactive-run) table below. `recent-commits` works from
-the repository alone and reads no configuration;
-[`dump-schema`](#repoactive-dump-schema) touches no repository at all and
-takes only `--output`.
+`--config`/`-c`, `--config-revset`, and `--set`/`-s` options, described in
+the [`repoactive run`](#repoactive-run) table below. `--ad-hoc` is specific
+to `run`. `recent-commits` works from the repository alone and reads no
+configuration; [`dump-schema`](#repoactive-dump-schema) touches no
+repository at all and takes only `--output`.
 
 All commands exit with these status codes:
 
@@ -324,6 +330,12 @@ repoactive run --mode push
 # Push branches and create or update merge requests
 repoactive run --mode publish
 
+# Use the configuration as it stands on trunk, whatever is checked out
+repoactive run --config-revset 'trunk()'
+
+# Run a one-off command without configuring a job for it
+repoactive run --ad-hoc 'just flake-update-diff'
+
 # Enable debug logging
 repoactive run --debug
 ```
@@ -331,10 +343,13 @@ repoactive run --debug
 | Option                          | Short | Description                                                                                                                  |
 | ------------------------------- | ----- | ---------------------------------------------------------------------------------------------------------------------------- |
 | `--config PATH`                 | `-c`  | Config file or directory of `*.toml` files; repeat to merge. Default: `.repoactive.d/` and `.repoactive.toml` under `--repo` |
+| `--config-revset REVSET`        |       | Read configuration from the merged tree of `REVSET` instead of from the working copy. Cannot be combined with `--config`     |
 | `--set NAME=VALUE`              | `-s`  | Override a config value (repeatable); `NAME` is a dotted TOML key, `VALUE` a TOML expression. Wins over `--config`           |
 | `--repo PATH`                   | `-r`  | jj repository path (default: `.`)                                                                                            |
 | `--mode [local\|push\|publish]` | `-m`  | How far to publish: `local` (default) applies only locally, `push` also pushes branches, `publish` also creates/updates MRs  |
 | `--tag TAG`                     | `-t`  | Run jobs carrying any of these tags (repeatable). With no tags/jobs the default run targets the `enabled` tag                |
+| `--ad-hoc COMMAND`              |       | Run `COMMAND` as a one-off job, no configuration needed. See [Running a command ad-hoc](#running-a-command-ad-hoc)           |
+| `--ad-hoc-name NAME`            |       | Name the `--ad-hoc` job (and thus its branch). Default: a name derived from the command                                      |
 | `--debug`                       | `-d`  | Enable debug logging                                                                                                         |
 
 ### `repoactive recent-commits`
@@ -661,8 +676,8 @@ underscores.
 - **`commit_title_prefix`** (default: inherited) - Override the commit title
   prefix for this job only.
 - **`output_in_commit`** (default: `true`) - Append the job's command and
-  its captured output to the commit message. Set to `false` to keep the
-  commit message clean.
+  its captured output to the commit message (truncated in the middle above
+  32 KiB). Set to `false` to keep the commit message clean.
 
 **Run control:**
 
@@ -803,6 +818,45 @@ 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`.
 
+### Reading configuration from a revset
+
+By default, the command reads the configuration from the working copy. The
+working copy can contain an incomplete change or an unsuitable revision.
+`--config-revset` creates a temporary jj workspace. The command runs
+`jj new REVSET` in this workspace to merge the revisions. It then discovers
+`.repoactive.d/` and `.repoactive.toml` in the temporary workspace instead
+of under `--repo`.
+
+```bash
+# Always run the configuration that is on trunk, whatever is checked out
+repoactive run --config-revset 'trunk()'
+
+# Preview the configuration a branch would produce once it lands
+repoactive info jobs --config-revset 'trunk() | my-feature-branch'
+```
+
+A revset that selects several revisions produces a merged tree. This
+behavior makes the second example possible. The following rules apply:
+
+- `--config-revset` cannot be combined with `--config`; the combination is
+  rejected. `--set`/`-s` still applies and still wins.
+- Merging the revset's revisions can cause conflicts. `repoactive` warns and
+  names the conflicted files. The command then continues. If a configuration
+  file contains conflict markers, the command cannot parse the file and
+  reports an invalid-configuration error.
+- The option needs jj and a colocated jj repository, even for the read-only
+  commands. A plain git repository is converted with
+  `jj git init --colocate` first - the same conversion a bare
+  `repoactive run` performs, with the same undo hint.
+- Only the _configuration_ comes from the revset. Jobs still run on commits
+  that use `trunk()` or their `base_branch` as the base. The local
+  repository is still the source of truth. Therefore, you must still fetch
+  the clone (see
+  [Keeping the local clone current](#keeping-the-local-clone-current)).
+
+See [ADR 0021](docs/adr/0021-read-config-from-a-revset.md) for the
+reasoning.
+
 ### Variables passed to job commands
 
 `repoactive` injects a few `RA_`-prefixed environment variables into every
@@ -901,6 +955,12 @@ 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.
 
+With [`--config-revset`](#reading-configuration-from-a-revset), the value
+points to the temporary workspace that contains the configuration. The
+workspace exists for the complete run. A command can read files from it. The
+command deletes the workspace when it exits. Files written to the workspace
+do not remain after the command exits.
+
 ### Passing secrets to commands with `secret_env`
 
 A job command inherits `repoactive`'s environment, so a secret exported
@@ -1002,6 +1062,61 @@ The sections below cover the run-control options from the
 [configuration reference](#jobname) in detail: which jobs a run selects, how
 to schedule and throttle them, and how to generate jobs dynamically.
 
+### Running a command ad-hoc
+
+`--ad-hoc COMMAND` runs a single command without writing a job for it. The
+repository needs no `repoactive` configuration at all:
+
+```bash
+repoactive run --ad-hoc 'just flake-update-diff'
+```
+
+`repoactive` builds one job from the command and runs it exactly as if it
+had been configured and named on the command line: the command runs in a
+temporary workspace, its result is committed on the job's own branch, and
+the commit carries the usual `Repoactive-Job` trailer. `--mode push` and
+`--mode publish` work as they do for a configured job.
+
+The job's name (and with it, its branch) is derived from the command: every
+run of characters a job name may not contain becomes a single dash, so
+`just flake-update-diff` produces the branch
+`repoactive/just-flake-update-diff`. The name is deterministic, so running
+the same ad-hoc command again updates that branch instead of opening a
+second one. Pass `--ad-hoc-name` for a name of your own:
+
+```bash
+repoactive run --ad-hoc "sed -i 's/2025/2026/' LICENSE" --ad-hoc-name copyright-year
+```
+
+The commit subject names the command it ran, `Run 'just flake-update-diff'`,
+and carries no `commit_title_prefix`; the merge request title keeps the
+usual `[repoactive] ` prefix.
+
+The remaining rules:
+
+- Configuration is still read when it exists. `[job-defaults]` and
+  `[platform.<name>]` apply to the ad-hoc job, and the configured jobs stay
+  loaded.
+- The ad-hoc job is selected the way a job named on the command line is, so
+  the run is the union of it, any jobs named as arguments, and any `--tag`
+  selection (see [Selecting jobs with tags](#selecting-jobs-with-tags)). On
+  its own, `--ad-hoc` therefore runs that one job and nothing else; combine
+  it with `--tag weekly` and the weekly jobs run too.
+- `--set`/`-s` still wins over everything, so a single field can be tuned in
+  place: `--ad-hoc 'cargo update' -s 'job.cargo-update.timeout = "10m"'`.
+- The name must be free. If a configured job already uses it, `repoactive`
+  says so and stops; `--ad-hoc-name` resolves the clash.
+- The command belongs to no config file, so it gets no
+  [`RA_CONFIG_SOURCE_DIR`](#variables-passed-to-job-commands), just like a
+  command defined through `--set`.
+- Like a job named on the command line, the ad-hoc job runs immediately and
+  ignores any cooldown.
+
+`--ad-hoc` is meant for one-off work and for trying a command out. A command
+worth running repeatedly is worth a [`[job.<name>]`](#jobname) block: a
+readable name, a proper title, tags, and a cooldown. See
+[ADR 0022](docs/adr/0022-ad-hoc-commands.md) for the reasoning.
+
 ### Selecting jobs with tags
 
 Which jobs a `repoactive run` touches is decided by **tags**. Every job has

{repoactive-0.4.0.dev1 → repoactive-0.4.2}/pyproject.toml

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

{repoactive-0.4.0.dev1 → repoactive-0.4.2}/src/repoactive/cli.py

@@ -1,7 +1,9 @@
 """Command-line interface for repoactive."""
 
+import contextlib
 import json
 import logging
+from collections.abc import Generator
 from datetime import UTC, datetime
 from enum import StrEnum
 from importlib.metadata import version
@@ -12,9 +14,12 @@ import typer
 from rich.logging import RichHandler
 
 from repoactive.config import (
+    AdHocJob,
+    AdHocNameCollisionError,
     Config,
     ConfigError,
     ConfigNotFoundError,
+    EmptyAdHocCommandError,
     Job,
     MissingSecretError,
     default_config_paths,
@@ -77,6 +82,30 @@ _SetOption = Annotated[
         "VALUE is a TOML expression. Repeatable; wins over --config.",
     ),
 ]
+_ConfigRevsetOption = Annotated[
+    str | None,
+    typer.Option(
+        "--config-revset",
+        help="Read configuration from the merged tree of this revset instead of from the "
+        "working copy. Cannot be combined with --config.",
+    ),
+]
+_AdHocOption = Annotated[
+    str | None,
+    typer.Option(
+        "--ad-hoc",
+        help="Run this shell command as a one-off job, without configuring it. The job is "
+        "added to any configuration found and selected like a job named on the command line.",
+    ),
+]
+_AdHocNameOption = Annotated[
+    str | None,
+    typer.Option(
+        "--ad-hoc-name",
+        help="Name for the --ad-hoc job, which also names its branch. "
+        "Default: derived from the command.",
+    ),
+]
 _RepoOption = Annotated[Path, typer.Option("--repo", "-r", help="Path to the jj repository.")]
 _DebugOption = Annotated[bool, typer.Option("--debug", "-d", help="Enable debug logging.")]
 
@@ -113,20 +142,40 @@ class MergeStatus(StrEnum):
     unmerged = "unmerged"
 
 
-def _resolve_config(config_paths: list[Path] | None, repo: Path) -> list[Path]:
-    """Use the given config paths, or discover defaults inside repo."""
-    return config_paths or default_config_paths(repo)
+def _resolve_config(
+    config_paths: list[Path] | None, repo: Path, *, required: bool = True
+) -> list[Path]:
+    """Use the given config paths, or discover defaults inside repo.
+
+    With required=False a missing default config yields no paths instead of an
+    error: --ad-hoc brings its own job and needs no configuration.
+    """
+    if config_paths:
+        return config_paths
+    try:
+        return default_config_paths(repo)
+    except ConfigNotFoundError:
+        if required:
+            raise
+        return []
 
 
 def _load_config_or_exit(
-    config_paths: list[Path] | None, repo: Path, overrides: list[str] | None = None
+    config_paths: list[Path] | None,
+    repo: Path,
+    overrides: list[str] | None = None,
+    ad_hoc: AdHocJob | None = None,
 ) -> Config:
     """Load the config, or print a clean error and exit non-zero."""
     try:
-        return load_config(_resolve_config(config_paths, repo), overrides=overrides or None)
+        paths = _resolve_config(config_paths, repo, required=ad_hoc is None)
+        return load_config(paths, overrides=overrides or None, ad_hoc=ad_hoc)
     except ConfigNotFoundError as e:
         _error(str(e))
         raise typer.Exit(code=1) from e
+    except (EmptyAdHocCommandError, AdHocNameCollisionError) as e:
+        _error(str(e))
+        raise typer.Exit(code=1) from e
     except ConfigError as e:
         _error(f"invalid config {e}")
         raise typer.Exit(code=1) from e
@@ -137,6 +186,11 @@ def _error(message: str) -> None:
     typer.secho(f"Error: {message}", err=True, fg=typer.colors.RED, bold=True)
 
 
+def _warn(message: str) -> None:
+    """Print message to stderr as a bold yellow Warning: line."""
+    typer.secho(f"Warning: {message}", err=True, fg=typer.colors.YELLOW, bold=True)
+
+
 def _check_jj() -> None:
     """Exit with a clear error unless the jj executable is on PATH."""
     try:
@@ -177,6 +231,45 @@ def _ensure_colocated_repo(repo: Path) -> None:
         raise typer.Exit(code=1) from e
 
 
+@contextlib.contextmanager
+def _config_root(
+    repo: Path, config_paths: list[Path] | None, config_revset: str | None
+) -> Generator[Path]:
+    """Yield the directory to discover configuration in.
+
+    The context lifetime keeps configuration-relative paths valid as required by
+    ADR 0021.
+    """
+    if config_revset is None:
+        yield repo
+        return
+    if config_paths:
+        _error("--config-revset cannot be combined with --config")
+        raise typer.Exit(code=1)
+    _check_jj()
+    # Create a colocated jj repository before the workspace. See ADR 0021.
+    _ensure_colocated_repo(repo)
+    with contextlib.ExitStack() as stack:
+        try:
+            workspace = stack.enter_context(JJ(repo).revset_workspace(config_revset))
+            _warn_about_conflicts(workspace, config_revset)
+        except JJError as e:
+            # Report an invalid revset without a traceback.
+            _error(str(e))
+            raise typer.Exit(code=1) from e
+        yield workspace.cwd
+
+
+def _warn_about_conflicts(workspace: JJ, config_revset: str) -> None:
+    """Warn about conflicted files, but continue to read the configuration."""
+    if not workspace.has_conflict("@"):
+        return
+    paths = workspace.conflicted_paths()
+    _warn(f"merging revset {config_revset!r} produced file conflicts:")
+    for path in paths:
+        typer.echo(f"  {path}", err=True)
+
+
 def _version_callback(value: bool) -> None:
     if value:
         typer.echo(version("repoactive"))
@@ -202,9 +295,20 @@ def callback(
         raise typer.Exit(code=1) from e
 
 
+def _ad_hoc_job(command: str | None, name: str | None) -> AdHocJob | None:
+    """Build the AdHocJob for --ad-hoc, or exit when only --ad-hoc-name was given."""
+    if command is None:
+        if name is not None:
+            _error("--ad-hoc-name requires --ad-hoc")
+            raise typer.Exit(code=1)
+        return None
+    return AdHocJob(command=command, name=name)
+
+
 @app.command()
 def run(  # noqa: PLR0913, PLR0917
     config_paths: _ConfigOption = None,
+    config_revset: _ConfigRevsetOption = None,
     repo: _RepoOption = _DEFAULT_REPO,
     mode: Annotated[
         RunMode,
@@ -217,6 +321,8 @@ def run(  # noqa: PLR0913, PLR0917
     ] = RunMode.local,
     overrides: _SetOption = None,
     debug: _DebugOption = False,
+    ad_hoc_command: _AdHocOption = None,
+    ad_hoc_name: _AdHocNameOption = None,
     tags: Annotated[
         list[str] | None,
         typer.Option(
@@ -233,35 +339,42 @@ def run(  # noqa: PLR0913, PLR0917
     """Apply jobs locally; pass --mode push or --mode publish to publish."""
     _setup_logging(debug)
     _check_jj()
-    cfg = _load_config_or_exit(config_paths, repo, overrides)
-    _ensure_colocated_repo(repo)
-    try:
-        platform = get_platform(cfg, repo) if mode is RunMode.publish else None
-        summary = run_all(
-            config=cfg,
-            repo_path=repo,
-            platform=platform,
-            requested_names=frozenset(jobs or []),
-            requested_tags=frozenset(tags or []),
-            mode=mode,
-        )
-    except RunLockHeldError as e:
-        _error(str(e))
-        raise typer.Exit(code=LOCK_HELD_EXIT_CODE) from e
-    except (
-        UnknownJobsError,
-        UnknownTagsError,
-        JJError,
-        MissingSecretError,
-        NoPlatformConfiguredError,
-        PlatformTokenNotSetError,
-        PlatformError,
-    ) as e:
-        # Anticipated failures (a mistyped job name or tag, a job granting an
-        # unset secret, no matching platform, an unset or rejected token, a
-        # failing jj/git invocation) get a clean error line, not a traceback.
-        _error(str(e))
-        raise typer.Exit(code=1) from e
+    ad_hoc = _ad_hoc_job(ad_hoc_command, ad_hoc_name)
+    # An ad-hoc job is requested by name, so it runs at once like any job named
+    # on the command line, alongside whatever else was requested.
+    requested_names = frozenset(jobs or []) | ({ad_hoc.job_name} if ad_hoc else frozenset())
+    # The config workspace is held for the whole run, so a job command can still
+    # reach the files RA_CONFIG_SOURCE_DIR points at (ADR 0021).
+    with _config_root(repo, config_paths, config_revset) as config_root:
+        cfg = _load_config_or_exit(config_paths, config_root, overrides, ad_hoc)
+        _ensure_colocated_repo(repo)
+        try:
+            platform = get_platform(cfg, repo) if mode is RunMode.publish else None
+            summary = run_all(
+                config=cfg,
+                repo_path=repo,
+                platform=platform,
+                requested_names=requested_names,
+                requested_tags=frozenset(tags or []),
+                mode=mode,
+            )
+        except RunLockHeldError as e:
+            _error(str(e))
+            raise typer.Exit(code=LOCK_HELD_EXIT_CODE) from e
+        except (
+            UnknownJobsError,
+            UnknownTagsError,
+            JJError,
+            MissingSecretError,
+            NoPlatformConfiguredError,
+            PlatformTokenNotSetError,
+            PlatformError,
+        ) as e:
+            # Anticipated failures (a mistyped job name or tag, a job granting an
+            # unset secret, no matching platform, an unset or rejected token, a
+            # failing jj/git invocation) get a clean error line, not a traceback.
+            _error(str(e))
+            raise typer.Exit(code=1) from e
     if not summary.ok:
         raise typer.Exit(code=1)
 
@@ -269,6 +382,7 @@ def run(  # noqa: PLR0913, PLR0917
 @app.command("validate-config")
 def validate_config(
     config_paths: _ConfigOption = None,
+    config_revset: _ConfigRevsetOption = None,
     repo: _RepoOption = _DEFAULT_REPO,
     overrides: _SetOption = None,
     debug: _DebugOption = False,
@@ -280,25 +394,32 @@ def validate_config(
     code 1 on failure.
     """
     _setup_logging(debug)
-    try:
-        paths = _resolve_config(config_paths, repo)
-        files = expand_config_paths(paths)
-        typer.echo("Configuration files:")
-        for file in files:
-            typer.echo(f"  {file}")
-        cfg = load_config(paths, overrides=overrides or None)
-    except ConfigNotFoundError as e:
-        _error(str(e))
-        raise typer.Exit(code=1) from e
-    except ConfigError as e:
-        _error(f"invalid config {e}")
-        raise typer.Exit(code=1) from e
+    with _config_root(repo, config_paths, config_revset) as config_root:
+        try:
+            paths = _resolve_config(config_paths, config_root)
+            files = expand_config_paths(paths)
+            if config_revset is not None:
+                # Say where the listed paths come from; they are inside a
+                # temporary workspace that is gone by the time this returns.
+                typer.echo(f"Configuration files from revset {config_revset!r}:")
+            else:
+                typer.echo("Configuration files:")
+            for file in files:
+                typer.echo(f"  {file}")
+            cfg = load_config(paths, overrides=overrides or None)
+        except ConfigNotFoundError as e:
+            _error(str(e))
+            raise typer.Exit(code=1) from e
+        except ConfigError as e:
+            _error(f"invalid config {e}")
+            raise typer.Exit(code=1) from e
     typer.echo(f"Config OK: {len(cfg.jobs)} job(s) defined.")
 
 
 @info_app.command("jobs")
 def info_jobs(
     config_paths: _ConfigOption = None,
+    config_revset: _ConfigRevsetOption = None,
     repo: _RepoOption = _DEFAULT_REPO,
     overrides: _SetOption = None,
     debug: _DebugOption = False,
@@ -310,13 +431,15 @@ def info_jobs(
     also shows the job's title and effective tags in aligned columns.
     """
     _setup_logging(debug)
-    cfg = _load_config_or_exit(config_paths, repo, overrides)
+    with _config_root(repo, config_paths, config_revset) as config_root:
+        cfg = _load_config_or_exit(config_paths, config_root, overrides)
     print_job_table(format_job_forest(topological_sort(cfg.jobs)))
 
 
 @info_app.command("tags")
 def info_tags(
     config_paths: _ConfigOption = None,
+    config_revset: _ConfigRevsetOption = None,
     repo: _RepoOption = _DEFAULT_REPO,
     overrides: _SetOption = None,
     debug: _DebugOption = False,
@@ -331,7 +454,8 @@ def info_tags(
     Each line also shows the job's title and effective tags in aligned columns.
     """
     _setup_logging(debug)
-    cfg = _load_config_or_exit(config_paths, repo, overrides)
+    with _config_root(repo, config_paths, config_revset) as config_root:
+        cfg = _load_config_or_exit(config_paths, config_root, overrides)
     jobs_by_tag: dict[str, list[Job]] = {}
     # Sort all jobs at once: a per-tag sort would break on dependencies whose
     # tags differ from the dependent's.

{repoactive-0.4.0.dev1 → repoactive-0.4.2}/src/repoactive/command.py

@@ -17,6 +17,11 @@ from repoactive.settings import load_settings
 
 logger = logging.getLogger(__name__)
 
+# How much of a command's output is kept for the commit message and the MR
+# description. Beyond this the middle is dropped (see truncate_middle and
+# docs/adr/0023-cap-captured-command-output.md).
+MAX_OUTPUT_CHARS = 32 * 1024
+
 
 @dataclass
 class CommandResult:
@@ -24,6 +29,35 @@ class CommandResult:
     elapsed: float
 
 
+def truncate_middle(text: str, limit: int) -> str:
+    """Drop the middle of text so the result fits in limit characters.
+
+    Keeps 30% of the remaining budget from the start and 70% from the end, with
+    a marker in between naming how much went: the first lines say what ran, the
+    last lines say how it ended, so the middle is the expendable part. Both
+    slices are cut back to a line boundary unless that would empty them, which
+    happens when the output is one enormous line.
+    """
+    if len(text) <= limit:
+        return text
+    # Size the marker with the widest omitted count it can ever carry, so the
+    # real marker is no longer than the one budgeted for and the result stays
+    # within limit.
+    budget = max(limit - len(_omitted_marker(len(text))), 0)
+    head_len = budget * 30 // 100
+    head, tail = text[:head_len], text[len(text) - (budget - head_len) :]
+    if "\n" in head:
+        head = head[: head.rindex("\n")]
+    if "\n" in tail:
+        tail = tail[tail.index("\n") + 1 :]
+    return head + _omitted_marker(len(text) - len(head) - len(tail)) + tail
+
+
+def _omitted_marker(omitted: int) -> str:
+    """Render the line that stands in for the characters truncate_middle dropped."""
+    return f"\n[... {omitted} characters omitted ...]\n"
+
+
 class CommandError(RuntimeError):
     """A job command exited non-zero.
 
@@ -161,11 +195,16 @@ def run_command(job: Job, cwd: Path, *, env: dict[str, str]) -> CommandResult:
             + (f":\n{detail}" if detail else ""),
             elapsed=elapsed,
         )
-    command_result = CommandResult(output=detail, elapsed=elapsed)
+    # Only the success path is capped: a failure is reported in full above, where
+    # the complete output is what makes it diagnosable.
+    command_result = CommandResult(
+        output=truncate_middle(detail, MAX_OUTPUT_CHARS), elapsed=elapsed
+    )
     logger.debug(
-        "[%s] command finished in %.3fs, %d bytes output",
+        "[%s] command finished in %.3fs, %d bytes output (%d captured)",
         job.name,
         command_result.elapsed,
+        len(detail),
         len(command_result.output),
     )
     return command_result

{repoactive-0.4.0.dev1 → repoactive-0.4.2}/src/repoactive/config.py

@@ -40,6 +40,13 @@ 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_-]+$")
+# Job name for an --ad-hoc command built entirely of characters a name may not
+# contain, and the longest name derived from a command (branch_prefix is added
+# on top of it).
+AD_HOC_NAME_FALLBACK = "ad-hoc"
+_AD_HOC_LABEL = "--ad-hoc"
+_AD_HOC_SLUG_RE = re.compile(r"[^A-Za-z0-9_]+")
+_AD_HOC_NAME_MAX_LEN = 50
 # 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_]*$")
@@ -287,6 +294,23 @@ class BranchNameIsBaseBranchError(ValueError):
         )
 
 
+class EmptyAdHocCommandError(ValueError):
+    """Raised when --ad-hoc is given a blank command."""
+
+    def __init__(self) -> None:
+        super().__init__("--ad-hoc needs a command to run")
+
+
+class AdHocNameCollisionError(ValueError):
+    """Raised when the ad-hoc job name is already taken by a configured job."""
+
+    def __init__(self, name: str) -> None:
+        super().__init__(
+            f"ad-hoc job {name!r} collides with a configured job of the same name; "
+            "pass --ad-hoc-name to run it under a different name"
+        )
+
+
 class ConfigError(Exception):
     """Wraps a parse or validation error with the config source it came from."""
 
@@ -894,9 +918,14 @@ 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.
+    # sources without a file (built-in defaults, --set overrides, --ad-hoc).
+    # Exposed to a command as RA_CONFIG_SOURCE_DIR for the job whose command
+    # this source sets.
     source_dir: Path | None = None
+    # Whether the jobs this source defines must not exist yet. Set for the
+    # --ad-hoc source, whose job would otherwise silently take over a
+    # same-named configured job's tags, labels, depends_on and cooldown.
+    reject_existing_jobs: bool = False
 
 
 def _built_in_defaults() -> list[_ConfigSource]:
@@ -931,6 +960,69 @@ def _parse_override(text: str) -> _ConfigSource:
         raise ConfigError(label, e) from e
 
 
+def ad_hoc_job_name(command: str) -> str:
+    """Derive a job name from an --ad-hoc command.
+
+    Every run of characters a job name may not contain, dashes included,
+    collapses into a single dash, so the same command always yields the same
+    name and thus reuses its branch across runs. Falls back to a fixed name for
+    a command that has no usable character at all.
+    """
+    slug = _AD_HOC_SLUG_RE.sub("-", command.strip()).strip("-")
+    return slug[:_AD_HOC_NAME_MAX_LEN].strip("-") or AD_HOC_NAME_FALLBACK
+
+
+def _ad_hoc_title(command: str) -> str:
+    """Commit subject for an ad-hoc command, marking a multi-line command as cut off.
+
+    Quotes the command, switching to double quotes only when that avoids
+    nesting a quote inside itself.
+    """
+    lines = command.strip().splitlines()
+    text = f"{lines[0].strip()} ..." if len(lines) > 1 else lines[0].strip()
+    quote = '"' if "'" in text and '"' not in text else "'"
+    return f"Run {quote}{text}{quote}"
+
+
+@dataclass(frozen=True)
+class AdHocJob:
+    """The job repoactive builds from --ad-hoc instead of from configuration."""
+
+    command: str
+    # Name from --ad-hoc-name; None derives one from the command.
+    name: str | None = None
+
+    @property
+    def job_name(self) -> str:
+        # Only an absent name derives one; a given name is passed through even
+        # when it is empty, so it fails job-name validation instead of being
+        # silently replaced by the derived one.
+        return ad_hoc_job_name(self.command) if self.name is None else self.name
+
+
+def _ad_hoc_source(ad_hoc: AdHocJob) -> _ConfigSource:
+    """Build the config source holding the ad-hoc job.
+
+    The table is built directly rather than through TOML, so the command needs
+    no quoting. It carries no source_dir: like a --set-defined command, an
+    ad-hoc command belongs to no config file and gets no RA_CONFIG_SOURCE_DIR.
+    """
+    if not ad_hoc.command.strip():
+        raise EmptyAdHocCommandError
+    # The title already names the command, so a prefix would only repeat that
+    # the run was not a human's; the MR title keeps its prefix.
+    body = {
+        "command": ad_hoc.command,
+        "title": _ad_hoc_title(ad_hoc.command),
+        "commit_title_prefix": "",
+    }
+    return _ConfigSource(
+        _AD_HOC_LABEL,
+        {"job": {ad_hoc.job_name: body}},
+        reject_existing_jobs=True,
+    )
+
+
 def _read_toml_file(path: Path) -> _ConfigSource:
     try:
         return _ConfigSource(
@@ -940,16 +1032,41 @@ def _read_toml_file(path: Path) -> _ConfigSource:
         raise ConfigError(str(path), e) from e
 
 
-def load_config(paths: list[Path], overrides: list[str] | None = None) -> Config:
+def load_config(
+    paths: list[Path],
+    overrides: list[str] | None = None,
+    ad_hoc: AdHocJob | None = None,
+) -> Config:
+    """Merge the built-in defaults, the given config paths, an ad-hoc job, and --set overrides.
+
+    The ad-hoc job is layered on top of the files, so it picks up job-defaults
+    and platforms from them, and below the overrides, so --set stays the last
+    word on every field.
+    """
     return _merge_config(
         itertools.chain(
             _built_in_defaults(),
             (_read_toml_file(path) for path in expand_config_paths(paths)),
+            () if ad_hoc is None else (_ad_hoc_source(ad_hoc),),
             (_parse_override(text) for text in overrides or []),
         )
     )
 
 
+def _reject_existing_jobs(source: _ConfigSource, shape: ConfigShape, merged: dict) -> None:
+    """Reject a source that redefines a job an earlier source already defined.
+
+    Only the --ad-hoc source asks for this; every other source merges into an
+    existing job by design. The error escapes _merge_config unwrapped: the
+    collision is with the command line, not with the config being invalid.
+    """
+    if not source.reject_existing_jobs:
+        return
+    for name in shape.job:
+        if name in merged.get("job", {}):
+            raise AdHocNameCollisionError(name)
+
+
 def _merge_config(sources: Iterable[_ConfigSource]) -> Config:
     merged = {}
     # Directory of the config source that last set each job's command, keyed by
@@ -962,6 +1079,10 @@ def _merge_config(sources: Iterable[_ConfigSource]) -> Config:
             # 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)
+        except ValidationError as e:
+            raise ConfigError(source.label, e) from e
+        _reject_existing_jobs(source, shape, merged)
+        try:
             for name, body in shape.job.items():
                 if "command" in body:
                     command_source_dir[name] = source.source_dir

{repoactive-0.4.0.dev1 → repoactive-0.4.2}/src/repoactive/jj.py

@@ -3,16 +3,19 @@
 import contextlib
 import enum
 import logging
+import re
 import shutil
 import subprocess
 import tempfile
 import time
+import uuid
 from collections.abc import Callable, Collection, Generator
 from dataclasses import dataclass
 from datetime import UTC, datetime
 from pathlib import Path
 
 from repoactive.constants import JOB_TRAILER_KEY
+from repoactive.lock import config_workspace_is_free, config_workspace_lock
 
 logger = logging.getLogger(__name__)
 
@@ -27,6 +30,9 @@ class Colocation(enum.Enum):
 # be recognised and reclaimed by name (see JJ.forget_stale_workspaces).
 WORKSPACE_PREFIX = "repoactive-tmp-"
 
+# Prefix for temporary configuration workspaces. See ADR 0021.
+CONFIG_WORKSPACE_PREFIX = "repoactive-config-"
+
 # The all-zeros commit_id jj reports for the virtual root commit, which has no
 # git counterpart.
 GIT_ROOT_COMMIT_ID = "0" * 40
@@ -48,6 +54,14 @@ def workspace_name(job_name: str) -> str:
     return f"{WORKSPACE_PREFIX}{job_name}"
 
 
+def config_workspace_name() -> str:
+    """Build a unique name for a configuration workspace.
+
+    The random suffix prevents name conflicts between concurrent commands.
+    """
+    return f"{CONFIG_WORKSPACE_PREFIX}{uuid.uuid4().hex}"
+
+
 def revset_heads(revs: list[str]) -> str:
     """Build a revset selecting the heads of revs.
 
@@ -211,11 +225,13 @@ class JJ:
         *,
         global_args: tuple[str, ...] = (),
         cwd: Path | None = None,
+        stdin: str | None = None,
     ) -> str:
         """Run program with args, raising CommandFailedError on a non-zero exit.
 
         global_args are inserted between the program and args but kept out
-        of logs and error messages, which show only the caller's args.
+        of logs and error messages, which show only the caller's args. stdin,
+        when given, is fed to the process instead of an empty pipe.
         """
         run_cwd = cwd or self.cwd
         logger.debug("%s %s (cwd=%s)", program, " ".join(args), run_cwd)
@@ -224,6 +240,7 @@ class JJ:
             result = subprocess.run(
                 [program, *global_args, *args],
                 cwd=run_cwd,
+                input=stdin,
                 capture_output=True,
                 text=True,
                 check=True,
@@ -246,8 +263,8 @@ class JJ:
         )
         return result.stdout
 
-    def _run(self, *args: str) -> str:
-        return self._exec("jj", args, global_args=("--no-pager", "--color=never"))
+    def _run(self, *args: str, stdin: str | None = None) -> str:
+        return self._exec("jj", args, global_args=("--no-pager", "--color=never"), stdin=stdin)
 
     def op_id(self) -> str:
         """Return the current operation id.
@@ -385,10 +402,6 @@ class JJ:
     def abandon(self) -> None:
         self._run("abandon", "@")
 
-    def abandon_revision(self, revision: str) -> None:
-        """Abandon a specific revision (not the working copy)."""
-        self._run("abandon", revision)
-
     def same_content(self, rev1: str, rev2: str) -> bool:
         """Return True if rev1 and rev2 have identical tree contents."""
         return not self._run("diff", "--git", "--from", rev1, "--to", rev2).strip()
@@ -416,10 +429,6 @@ class JJ:
         onto_args = [arg for parent in onto for arg in ("--onto", parent)]
         self._run("rebase", "-s", revision, *onto_args)
 
-    def describe_revision(self, revision: str, message: str) -> None:
-        """Set the commit message of a specific revision without touching @."""
-        self._run("describe", "-r", revision, "--message", message)
-
     def get_description(self, revision: str) -> str:
         """Return the commit message of a specific revision."""
         return self._run("log", "--no-graph", "-r", revision, "-T", "description")
@@ -428,7 +437,13 @@ class JJ:
         return self._run("log", "--no-graph", "-r", "@", "-T", "self.diff().stat(50)").strip()
 
     def describe(self, message: str) -> None:
-        self._run("describe", "--message", message)
+        """Set the working copy's description.
+
+        The message goes in on stdin, not as --message: a job that embeds its
+        command output in the commit can exceed the 128 KiB Linux puts on a
+        single argv entry, which fails the exec with "argument list too long".
+        """
+        self._run("describe", "--stdin", stdin=message)
 
     def change_id(self, revision: str = "@") -> str:
         """Return the short change id of revision (the working copy by default)."""
@@ -505,6 +520,15 @@ class JJ:
         output = self._run("log", "--no-graph", "-r", revset, "-T", 'commit_id ++ "\\n"')
         return [line for line in output.splitlines() if line]
 
+    def conflicted_paths(self, revision: str = "@") -> list[str]:
+        """Return conflicted paths in revision.
+
+        Call this only when has_conflict is true because jj reports an empty
+        list as an error.
+        """
+        output = self._run("resolve", "--list", "--revision", revision)
+        return [re.split(r"\s{2,}", line, maxsplit=1)[0] for line in output.splitlines() if line]
+
     def has_conflict(self, revset: str) -> bool:
         """Return True if any commit in revset contains a materialized conflict.
 
@@ -647,7 +671,8 @@ class JJ:
         A run killed before its `finally` could call workspace_forget leaves its
         temporary workspace (named with WORKSPACE_PREFIX) registered in jj. Because
         the prefix is fixed, every such workspace can be recognised and dropped here,
-        even for jobs that have since been renamed or removed.
+        even for jobs that have since been renamed or removed. Only the run lock
+        makes that safe, so config workspaces stay out of scope by prefix.
         """
         stale = sorted(n for n in self.workspace_names() if n.startswith(WORKSPACE_PREFIX))
         logger.debug("stale workspaces to forget: %s", stale)
@@ -690,6 +715,42 @@ class JJ:
     def workspace_forget(self, name: str) -> None:
         self._run("workspace", "forget", name)
 
+    @contextlib.contextmanager
+    def revset_workspace(self, revset: str) -> Generator["JJ"]:
+        """Yield a temporary workspace containing the merged tree of revset.
+
+        Conflicts remain materialised for caller inspection as required by ADR
+        0021.
+        """
+        self.forget_stale_config_workspaces()
+        name = config_workspace_name()
+        # The lock is taken before the workspace is registered, so a command
+        # reclaiming abandoned workspaces never sees this one unlocked.
+        with (
+            config_workspace_lock(self.cwd, name),
+            self.temp_workspace(name, Colocation.PLAIN) as workspace,
+        ):
+            workspace.new(revset)
+            yield workspace
+
+    def forget_stale_config_workspaces(self) -> None:
+        """Forget configuration workspaces that have no held advisory lock.
+
+        The advisory lock identifies workspaces that live commands use. See
+        ADR 0021.
+        """
+        abandoned = sorted(
+            name
+            for name in self.workspace_names()
+            if name.startswith(CONFIG_WORKSPACE_PREFIX)
+            and config_workspace_is_free(self.cwd, name)
+        )
+        logger.debug("abandoned config workspaces to forget: %s", abandoned)
+        for name in abandoned:
+            # Another command may be reclaiming the same workspace right now.
+            with contextlib.suppress(JJError):
+                self.workspace_forget(name)
+
     @contextlib.contextmanager
     def temp_workspace(
         self, name: str, colocation: Colocation = Colocation.COLOCATED

{repoactive-0.4.0.dev1 → repoactive-0.4.2}/src/repoactive/lock.py

@@ -72,6 +72,58 @@ def _write_holder(fd: int) -> None:
     os.write(fd, info.encode("utf-8"))
 
 
+def _config_workspace_lock_path(repo_path: Path, name: str) -> Path:
+    # Keyed by workspace name, not by the workspace directory: a reclaiming
+    # command knows the name from jj workspace list, and the directory of an
+    # abandoned workspace may be gone.
+    return repo_path.resolve() / ".jj" / f"{name}.lock"
+
+
+@contextlib.contextmanager
+def config_workspace_lock(repo_path: Path, name: str) -> Generator[None]:
+    """Hold the advisory lock for a configuration workspace.
+
+    The kernel releases the lock when the process ends. This behavior identifies
+    abandoned workspaces without the use of process identifiers. See ADR 0021.
+    """
+    path = _config_workspace_lock_path(repo_path, name)
+    fd = os.open(path, os.O_CREAT | os.O_RDWR, 0o644)
+    try:
+        fcntl.flock(fd, fcntl.LOCK_EX | fcntl.LOCK_NB)
+        _write_holder(fd)
+        try:
+            yield
+        finally:
+            fcntl.flock(fd, fcntl.LOCK_UN)
+    finally:
+        os.close(fd)
+        path.unlink(missing_ok=True)
+
+
+def config_workspace_is_free(repo_path: Path, name: str) -> bool:
+    """Report whether no live command holds the config workspace name.
+
+    A missing lock file counts as free: the command that made the workspace is
+    gone and removed its lock, or never had one. Callers use this only to
+    decide that a registered workspace can be forgotten, so the worst a wrong
+    'free' can do is forget a workspace nobody is using.
+    """
+    path = _config_workspace_lock_path(repo_path, name)
+    try:
+        fd = os.open(path, os.O_RDWR)
+    except OSError:
+        return True
+    try:
+        try:
+            fcntl.flock(fd, fcntl.LOCK_EX | fcntl.LOCK_NB)
+        except OSError:
+            return False
+        fcntl.flock(fd, fcntl.LOCK_UN)
+        return True
+    finally:
+        os.close(fd)
+
+
 @contextlib.contextmanager
 def run_lock(repo_path: Path) -> Generator[None]:
     """Hold an exclusive per-repository run lock for the duration of the block.