[brettheap]

Lane: openreposhape-4 (openRepoShape-4)

Claim: #433 (comment)

What changed and why

Under --local-remote-dir the clone URL of a new repository is the bare repository's own path. scaffold-project.py renders it as CLONE_URL and ASSEMBLY_CLONE_URL into the READMEs of the assembly root and of each leg, and family.py init renders the holder's into the holder's README, all through write_lf, which encodes strictly. A directory whose name is not UTF-8 reaches sys.argv as a string with a lone surrogate, so on main (re-measured at 8f453d0e, LANG unset):

• the scaffold exited 1 with UnicodeEncodeError in write_lf after Atlas.git, Atlas-spec.git and Atlas-code.git existed and the work directory held Atlas-spec;
• family.py init exited 1 the same way after Contoso.git existed and the family folder was made;
• --dry-run exited 0 for both and said nothing;
• a line break, a control character or a bidi override in the path was written into the README raw.

adopt-project.py asks the question before any leg exists (#255, _refuse_an_unwritable_clone_url). Both tools now ask it of the same value with the same unwritable_reason, and refuse in adopt's words, before any remote or folder exists and under --dry-run alike:

• scaffold-project.py: scaffold-unwritable-value, the code scaffold-project.py writes --elected-by, --reference and --name between literal double quotes with no escaping and asks none of them whether a file can hold it, so a line break leaves a project.yaml its own validators refuse, a backslash is recorded as another character (CORP\nick as CORP, a line feed, ick), and a byte that is not UTF-8 dies in write_lf after the legs are pushed #282 gave the free-text values. _repository_urls moves up to just after the name-length check and _refuse_an_unwritable_clone_url asks the assembly root's URL there, so the refusal comes before _declaration runs gh api and before a work directory or remote exists. Only the assembly root's URL is asked: it is the one a file holds, and the legs' sit beside it in the same directory, so what makes one unwritable makes all three so.
• scripts/family.py: family-unwritable-value, a new code of the same family, asked right after _holder_remote.

The sentence, scaffold: under --local-remote-dir the assembly root's clone URL is the bare repository's own path, '<url>', which the scaffold writes into the README.md of the assembly root and of each leg, and it holds a byte that is not UTF-8. The family's: ... the holder's clone URL is the bare repository's own path, '<url>', which initwrites into the holder'sREADME.md, and .... The Remediation: says nothing was created and --dry-run refuses the same, to pass a --local-remote-dir whose path is one line of UTF-8 text with no control character (renamed or made anew), or to run against GitHub, where the clone URL is https://github.com/<org>/<name>.git, and why each kind of byte cannot be written.

The issue offered reusing _refuse_unwritable_values with the URL among its fields. I did not: its remediation tells a person to retype a value, and a directory is renamed or replaced, not retyped. The code, the question and the sentence's skeleton are the same.

Tests

tests/test_clone_url_bytes.py, 30 tests, on the #282 file's harness (scaffold and no_process imported from tests/test_scaffold_free_text_values.py) and tests/test_family_init_values.py's (FAMILY, family_module):

• the issue's <dir>/caf<e9>, plus a line feed, an escape and a U+202E in the directory's name, each tool, real run and --dry-run, exit 2, nothing on stdout, the whole of stderr compared, the remote directory still empty and the work directory or family folder absent; the scaffold under a guard that fails if any process starts, init under one that allows only git check-ref-format (scaffold-project.py holds --tracking-branch only to checked_value's alphabet, so a name git refuses as a branch (~, a..b, x.lock, a trailing /) passes --dry-run and, against GitHub, dies at the first git init -b after gh repo create has made all three repositories #283's question, asked first);
• a relative --local-remote-dir rehearsal run from the bad directory (the URL asked is the resolved one);
• the issue's two commands as child processes: no traceback, exit 2, nothing made;
• controls: a UTF-8 café directory still plans and still scaffolds / creates the holder, the README holding the URL as written.

Where the disk cannot hold the name (macOS, Windows) the test skips with a reason; none skipped here. New file alone: 30 passed. Targeted run on the committed bytes, 76 files (every test_scaffold_*, test_family*, test_setup_*, and each file naming the scaffold, family.py or setup-project.py three or more times, plus test_repo_hygiene.py, test_cli_reference.py, test_agents_md_codes.py): 4620 passed, 31 skipped (template-quoting, Windows-only and PowerShell skips), exit 0, 48 min. After main moved to 4cf5fb07, which touches none of the three files, the new file and its two harness files on a scratch merge with main: 249 passed, 19 skipped.

Mutants, each run on the new file alone:

mutant	result
M1 delete the scaffold's call	killed, 12 failed
M2 delete init's call	killed, 12 failed
M3 scaffold asks only on the real run	killed, 6 failed (every dry-run case)
M4 both functions ask only for a byte that is not UTF-8	killed, 12 failed (line feed, escape, bidi)
M5 both ask the flag as typed, not the resolved URL	killed, 24 failed (the relative cases fail on the exit code, the others on the sentence)

Fix round 1 (ac404626, after review R433 found SonarCloud's gate in ERROR, from the test file only; no behaviour changed):

• tests/test_clone_url_bytes.py:71: the bidi-override row held a RAW U+202E in the file (S6389, new-code security rating C), against the file's own promise that every invisible character in it is an escape. It is now "\u202eevil".encode("utf-8"), the same bytes. A scan of the file for any control, format, line-separator, private-use or unassigned character finds none; the only non-ASCII characters left are the visible é of the issue's own <dir>/café control.
• tests/test_clone_url_bytes.py:149: assert path.is_dir() and os.listdir(path) == [] is two assertions (S9073).
• scripts/family.py:1140: the comment above CLONE_URL_REMEDIATION now says it is what a family-unwritable-value for the holder's clone URL is told to do, as the scaffold's twin already does, because bump-leg.py, scaffold-project.py and family.py: git status --porcelain and git config user.name are read as bytes, so a file name that is not UTF-8 is bump-leg-root-dirty or the DIRTY warning and a user.name that is not UTF-8 is refused family-unwritable-value naming --created-by, where each ended in a UnicodeDecodeError traceback (#423, #426) #641 gives the same code a second remediation (a creator read from git config user.name). Comment only.
• The round's run, on the committed bytes: tests/test_clone_url_bytes.py, tests/test_scaffold_free_text_values.py, tests/test_family_init_values.py, tests/test_family_dry_run.py, tests/test_family_init_landing.py, tests/test_repo_hygiene.py, tests/test_cli_reference.py and tests/test_agents_md_codes.py: 453 passed, 19 skipped (16 and 3 template-quoting skips in test_family_init_values.py), exit 0, 1:29. The new file still collects 30 tests.

Main merge (541f3aec, after #641 landed as 42f64111): tests/test_clone_url_bytes.py, tests/test_non_utf8_git_reads.py (#641's), tests/test_family_refuse_up_front.py (#626's), tests/test_scaffold_free_text_values.py, tests/test_family_init_values.py, tests/test_family_dry_run.py, tests/test_family_init_landing.py, tests/test_repo_hygiene.py, tests/test_cli_reference.py and tests/test_agents_md_codes.py, on the committed merge, GIT_ALLOW_PROTOCOL unset: 589 passed, 19 skipped (the same 16 and 3 template-quoting skips in test_family_init_values.py), exit 0, 2:58.

What it cannot tell

• Only a local URL is asked. Against GitHub the URL is ASCII by construction.
• --work-dir, --into and --source holding a non-UTF-8 byte are not in the issue and not touched. family.py add --local-remote-dir <bad> runs to exit 0 (git writes the URL into .gitmodules); that URL's readers are adopt-project.py: _elector and _remote_repository read git config user.name and the origin URL through git_out, which decodes strictly, so a name or URL that is not UTF-8 ends plan (and, for the URL, check and execute) in a UnicodeDecodeError traceback, exit 1, naming neither the git setting nor the flag that avoids it #292's and scripts/shape_advisory.py repository_names and shape-doctor.py origin_url and origin_name read git remote get-url origin through git_out and catch Refusal and OSError only, so an origin URL that is not UTF-8 makes read answer not-answered (a single repository loses the Triad advisory, a leg clone its pointer to the assembly root) and ends shape-doctor.py --root in a UnicodeDecodeError traceback, exit 1, where an ASCII origin gives NOT A SHAPE ROOT, exit 2 #385's.
• docs/release-notes/v1.0.0.md:452 still lists scaffold-project.py and family.py init with --local-remote-dir under a directory whose name is not UTF-8 put that path into the clone URL they render into the new repositories' files, and write_lf (strict UTF-8) raises a UnicodeEncodeError traceback, exit 1, after the bare remotes exist (--dry-run exits 0), where adopt refuses an unwritable clone URL before any leg exists #433 as a v1.0.0 limit. It is history for that release and is left as it is.

Shared files

scaffold-project.py and scripts/family.py, and the new test file tests/test_clone_url_bytes.py; the diff against main is those three files and no others. No --help text, so docs/cli.md is unchanged, and no README or handbook sentence became false. No pinned shape copy is touched.

Main is merged in. Head 541f3aec, a --no-ff merge of main 42f64111 (which holds #641, #626, #633, #642 and #590, among others, since this branch's base 8f453d0e) into fix round 1 ac404626. Exactly one hunk conflicted, in scripts/family.py: the comment above the one shared from shape_materialize import unwritable_reason line, which #433 and #641 each gave its own comment. scaffold-project.py auto-merged. The hunk, markers included, is resolved to these five lines (reviewer R423 tested them byte for byte), as committed:

# Whether a value `init` writes into the holder is one line of text a file
# can hold: the creator read from `git config user.name` (#426), and the
# holder's clone URL under `--local-remote-dir` (#255, #433). It is the
# question the scaffold and `adopt-project.py` ask of theirs.
from shape_materialize import unwritable_reason  # noqa: E402

py_compile passes on scripts/family.py, which holds both CREATOR_UNWRITABLE_REMEDIATION (#426) and CLONE_URL_REMEDIATION (#433), one unwritable_reason import and no duplicate definition.

git merge-tree --write-tree of this head 541f3aec, each head read with ls-remote just before:

against	head	exit	tree
main	42f64111592d	0	3611c189c62e (= this head's own tree: main is already in it)
#643 fix/421-push-branch-refspec	1fe37647d930	0	8d90f0ba0caf
#622 fix/609-dry-run-parity	227bc3b01c08	0	ef44f058f3f1
#621 fix/602-free-plan-hint-root	10dda171dd77	0	38e99bd5767f

#626 and #641 are in main now, so they are not listed.

Closes #433

🤖 Generated with Claude Code

Summary by Sourcery

Refuse unwritable local clone URLs before creating repositories or project folders in scaffold and family initialization.

Bug Fixes:

• Reject scaffold and family initialization when a local clone URL cannot be safely represented in README text, preventing partial repository or folder creation and UnicodeEncodeError failures.

Enhancements:

• Apply the same upfront validation to real and dry-run flows, with actionable refusal messages for invalid encoding, control, and bidirectional characters while preserving valid UTF-8 paths.

Tests:

• Add coverage for invalid and valid local remote directory names, relative paths, dry runs, subprocess behavior, side-effect prevention, and refusal-message parity.

[sourcery-ai]

Reviewer's Guide

The PR prevents scaffold-project.py and family.py init from creating partial repositories or folders when a local clone URL cannot be safely represented in README text, by validating the resolved URL up front and applying equivalent behavior during --dry-run; extensive tests cover invalid bytes, unsafe controls, path resolution, exact diagnostics, side-effect absence, and valid UTF-8 paths.

Sequence diagram for preflight validation of local clone URLs

sequenceDiagram
    participant CLI
    participant Resolver
    participant Validator
    participant Creator

    alt scaffold-project.py
        CLI->>Resolver: _repository_urls(args, names)
        Resolver-->>CLI: urls[assembly]
        CLI->>Validator: _refuse_an_unwritable_clone_url(local, urls[assembly])
        alt URL is unwritable
            Validator-->>CLI: Refusal scaffold-unwritable-value
            CLI-->>CLI: Exit 2, no remote or work directory
        else URL is writable
            Validator-->>CLI: Continue
            CLI->>Creator: _declaration(...)
            Creator-->>CLI: Create scaffold resources
        end
    else family.py init
        CLI->>Resolver: _holder_remote(args, family)
        Resolver-->>CLI: local, repository, url
        CLI->>Validator: _refuse_an_unwritable_clone_url(local, url)
        alt URL is unwritable
            Validator-->>CLI: Refusal family-unwritable-value
            CLI-->>CLI: Exit 2, no remote or family folder
        else URL is writable
            Validator-->>CLI: Continue
            CLI->>Creator: materialize_family_root(...)
            Creator-->>CLI: Create family resources
        end
    end

Loading

File-Level Changes

Change	Details	Files
Add early validation for local clone URLs before any remote, work directory, or family folder is created.	Resolve repository URLs earlier in scaffold setup and validate the assembly URL before GitHub or filesystem side effects. Validate the family holder URL immediately after deriving it during init. Reuse the shared unwritable-reason classification while preserving tool-specific refusal codes and remediation text. Leave GitHub URLs unaffected because they are ASCII by construction.	scaffold-project.py scripts/family.py
Add comprehensive coverage for invalid local path bytes and control characters, including dry-run behavior and side-effect prevention.	Test non-UTF-8 bytes, line feeds, escape controls, and bidi controls for scaffold and family init. Verify real and dry-run invocations return refusal code 2 with exact stderr and no stdout. Cover resolved relative paths, child-process execution without tracebacks, and guards against premature process starts. Confirm UTF-8 paths, including accented names, continue to plan and create successfully.	tests/test_clone_url_bytes.py

Assessment against linked issues

Issue	Objective	Addressed	Explanation
#433	Refuse scaffold runs whose local clone URL cannot safely be written into the generated READMEs, before creating any work directory or remote, including during --dry-run.	✅
#433	Refuse family init runs whose local holder clone URL cannot safely be written into its README, before creating the family folder or remote, including during --dry-run.	✅

Possibly linked issues

• scaffold-project.py and family.py init with --local-remote-dir under a directory whose name is not UTF-8 put that path into the clone URL they render into the new repositories' files, and write_lf (strict UTF-8) raises a UnicodeEncodeError traceback, exit 1, after the bare remotes exist (--dry-run exits 0), where adopt refuses an unwritable clone URL before any leg exists #433: The PR directly fixes the issue by checking local clone URLs before creation in scaffold and family init, including dry-runs.

---

Tips and commands

Interacting with Sourcery

• Trigger a new review: Comment @sourcery-ai review on the pull request.
• Continue discussions: Reply directly to Sourcery's review comments.
• Generate a GitHub issue from a review comment: Ask Sourcery to create an
  issue from a review comment by replying to it. You can also reply to a
  review comment with @sourcery-ai issue to create an issue from it.
• Generate a pull request title: Write @sourcery-ai anywhere in the pull
  request title to generate a title at any time. You can also comment
  @sourcery-ai title on the pull request to (re-)generate the title at any time.
• Generate a pull request summary: Write @sourcery-ai summary anywhere in
  the pull request body to generate a PR summary at any time exactly where you
  want it. You can also comment @sourcery-ai summary on the pull request to
  (re-)generate the summary at any time.
• Generate reviewer's guide: Comment @sourcery-ai guide on the pull
  request to (re-)generate the reviewer's guide at any time.
• Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
  pull request to resolve all Sourcery comments. Useful if you've already
  addressed all the comments and don't want to see them anymore.
• Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
  request to dismiss all existing Sourcery reviews. Especially useful if you
  want to start fresh with a new review - don't forget to comment
  @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

• Enable or disable review features such as the Sourcery-generated pull request
  summary, the reviewer's guide, and others.
• Change the review language.
• Add, remove or edit custom review instructions.
• Adjust other review settings.

Getting Help

• Contact our support team for questions or feedback.
• Visit our documentation for detailed guides and information.
• Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[sourcery-ai]

Sorry @brettheap, you've used your own review budget of 250,000 diff characters for the last 7 days.

You can request another review in 10 hours and 19 minutes by commenting @sourcery-ai review. Upgrade to get a review now.