Repository navigation
feat(adr): create from flags writes an accepted decision's files - #950
austinborn wants to merge 3 commits into
Conversation
backlineint
left a comment
There was a problem hiding this comment.
1. Files are written under the current directory, not the repository root (cloud.rs, run_create)
On the flags path root is dir.to_path_buf(). origin_remote_url runs git remote get-url from that directory, which succeeds from any subdirectory of the checkout. Running create from src/ therefore writes src/docs/adr/… and src/.actual/rules/…. The sync writes at the repository root, so once its PR merges there are two copies of the rule: the stray subdirectory one and the root one. The hooks search ancestors, so both would be enforced. Suggested fix: resolve the git toplevel (git rev-parse --show-toplevel) for the pair. Alternatively, refuse with a files_problem when dir isn't the toplevel.
2. The local save check runs after the server has accepted the decision (cloud.rs, saved_pair)
The decision is saved first, and only then does check_document run. If the local check refuses a decision the server accepted, for example a policy over two lines, the user has an accepted decision in Actual AI that isn't enforced locally. create_from_flags_writes_no_file_the_save_check_refuses pins this behavior. Suggested fix: for accepted saves, run check_document before the request and either fail early or warn. If the gap is deliberate, docs/ADR_COMMANDS.md should say that a server-valid decision can still end up without local files.
benw5483
left a comment
There was a problem hiding this comment.
P2: from a subdirectory, the pair lands outside the paths the sync manages, and outlives the decision
Changed code: cloud.rs:313, cloud.rs:460
Evidence: For a create from flags, root is the current directory (None => dir.to_path_buf()), and write_pair joins docs/adr/ and .actual/rules/ onto it. The repository check doesn't catch a subdirectory: pick_repo reads git remote get-url origin, which git answers from anywhere inside the checkout, and the --repo check at line 445 does the same. A test run from src/ of a checkout of actual-software/actual-cli saved an accepted decision and wrote src/docs/adr/33333333-…-use-postgres-for-storage.md and src/.actual/rules/cross-cutting-use-postgres-storage-3333.md. load_rule_set on the checkout root then read 0 rule documents, and on src/ it read 1.
The sync manages only the root-level paths: MANAGED_ROOTS is .actual/rules and docs/adr (ruleFile.ts:135-137).
Impact: The PR's central promise, that the sync's pull request rewrites these same two files, holds only at the checkout root. From a subdirectory (common in a monorepo, and in an agent shell that has cd'd somewhere), the person gets:
- a rule that root-level checks don't read until the sync PR merges, though the output says it was written;
- a second pair at the root once the sync PR merges;
- a subdirectory copy that the sync never updates or deletes. A check run from that subdirectory keeps enforcing it after the decision is edited, unpublished or archived.
Fix: For the flags path, write under the checkout's top level rather than the current directory. impl_check::checkout_root (impl_check.rs:599) already resolves it for hooks started in a subdirectory. The other option is to refuse with a files_problem when the current directory isn't the top level. Either way, ADR_COMMANDS.md item 6 ("They go into the directory the command runs in") and the CHANGELOG line need to match. A test that runs run_create from a subdirectory would pin it.
P3: a person who doesn't commit the pair can't pull the sync's merge
Changed code: cloud.rs:704, docs/ADR_COMMANDS.md:102
Evidence: The pair is written as untracked files, and the output says "Actual AI opens a pull request that writes its rule files", then lists the two paths. Nothing says to commit them. When the sync PR merges and the person runs git pull, git refuses to overwrite untracked files at the incoming paths, even when the bytes are identical. With git 2.50.1, an identical untracked .actual/rules/x.md stopped the pull with "The following untracked working tree files would be overwritten by merge … Aborting".
Impact: Every accepted create from a terminal leaves this in place by default. The way out is easy once someone reads git's message, which is to delete the two files and pull again. create --file's renamed pair has the same shape today. This PR makes it the normal path for flags.
Fix: One line in the output and in item 6: commit the two files with the change they govern, or delete them before pulling once the sync PR merges.
f349428 to
7e11087
Compare
|
@backlineint thanks for the review. Both points are fixed in 7e11087. 1. Files under the current directory. I took your first suggestion. The pair now goes at the top of the checkout ( 2. The local save check ran after the save. I took the fail-early fix. An accepted save from flags now runs the local save check before anything is sent, and a decision it refuses exits 1 with the check's reasons, the same check and wording @benw5483's review added one more point, which bdc162c covers:
|
|
@benw5483 thanks. Both points are fixed. P2, the pair under a subdirectory. Fixed in 7e11087, together with @backlineint's first point. The pair goes at the top of the checkout from any directory inside it, and P3, pulling the sync's merge over untracked files. Fixed in bdc162c as you suggested. After the two
|
…om flags `actual adr create --title … --policy …` saved the decision and wrote nothing locally. An accepted save now writes its decision doc into docs/adr/ and its rule file into .actual/rules/, laid out as `adr new` writes them and named for the new decision's id as Actual AI's sync names them, so plan-check and impl-check enforce it at once and the sync's pull request rewrites those same files. A draft gets no files, because the sync deletes a merged file named for a decision that doesn't govern. With --repo, the files are written only when the directory's origin remote names that repository. An existing file is never replaced. Any reason the pair wasn't written shows as a note, or as files_problem in --json, and the command still succeeds, since the decision is saved. City: city · Agent: local-core__builder-ci-wisp-z8zi1o
…efore the save From a subdirectory, an accepted `adr create` from flags wrote its pair under that directory, so once the sync's pull request merged, its copy at the repository root would sit beside a stray one that the hooks enforce too. The pair now goes at the top of the checkout (`git rev-parse --show-toplevel`), and a directory with no working tree, such as `.git`, gets a files_problem. The local save check ran only after Actual AI had saved the decision, so a refusal there left an accepted decision with no local files. It now runs before anything is sent, and an accepted save it refuses exits 1 with its reasons, as `adr new` does. City: city · Agent: local-core__builder-ci-wisp-nphse1
… the sync The pair is written untracked, and git won't merge the sync pull request over untracked files at the same paths, even identical ones, so `git pull` aborts. create's output and docs/ADR_COMMANDS.md item 6 now say to commit both files with the change they govern, or delete them before pulling once that pull request merges. City: city · Agent: local-core__builder-ci-wisp-nphse1
bdc162c to
786627f
Compare
|
Rebased onto The commits cited in the replies above are now:
On 786627f,
|
Summary
actual adr create --title … --policy …saves a decision to Actual AI but writes nothing to the repository, so a decision accepted from a terminal isn't enforced locally until Actual AI's sync pull request merges. Now an accepted save also writes its decision doc intodocs/adr/and its rule file into.actual/rules/, laid out asadr newwrites them and named for the decision's id as the sync names them, soplan-checkandimpl-checkenforce it at once and the sync later rewrites the same files.create --fileis unchanged..git, gets none.--repo, the files are written only when the checkout's origin remote names that repository.files_problemin--json).adr newruns. A refusal exits 1 with the check's reasons before anything is sent.The risk is confined to the flags path of
create.--jsongains three optional keys:decision_file,rule_fileandfiles_problem.Verification: none, no web app or SQL change (a CLI change)
The tests in the plan below cover the change.
Test plan, sample output and the overlap with #943 and #951
Test plan
cargo test --lib -- cli::commands::adr adr::: 189 passed. An accepted save writes both files with the decision's id andacceptedin each header, after a draft save in the same checkout wrote none, and a second save onto those files leaves them untouched. From a subdirectory the pair goes to the top of the checkout and the output says to commit it or delete it before pulling, and from inside.gitthe save says it found no working tree.--repowrites only into a checkout of that repository, says so in a checkout of another one, and names the error when the connected repositories can't be read. An accepted save that the local check refuses (a policy over two lines) sends nothing and returns the check's reason.checkout_topfinds the top from a subdirectory and returns nothing inside.gitor outside a repository.cargo llvm-cov --lib -- cli::commands::adr adr:::cli/commands/adr/cloud.rs2154/2154,cli/commands/adr/mod.rs373/373 andcli/commands/adr/local.rs739/739 lines.cargo fmt --check,cargo clippy -- -D warningsandcargo check --no-default-features --lib --bins: clean.cargo test --workspace --features integrationrun is left to CI.Sample output (from the tests)
In a checkout of another repository:
Overlap with #943 and #951
#943 (
adr discoverandcreate --all) and #951, stacked on it, editcloud.rsandmod.rstoo. This change leavesCreateOutcome,RenameOutcomeand the two test helpers #943 touches as they are, since the flags path reports through its ownFlagsOutcome. Trial merges with #943's head (47639f3) and #951's (5828301) are clean.