Skip to content

Wrapped projects, slice 1: the sources declaration and project wrap (PR1) - #333

Merged
ccozianu merged 16 commits into
mainfrom
ws-wrapped-projects/wrap
Nov 3, 2026
Merged

ccozianu merged 16 commits into
mainfrom
ws-wrapped-projects/wrap

Conversation

@ccozianu

@ccozianu ccozianu commented Nov 2, 2026 •

Copy link
Copy Markdown
Owner

Slice 1 of the wrapped-projects work order, by the Claude Code + Fable 5.1 pair, reviewed by the Codex + gpt-6-astra pair as PR1.1 (#334, merged). Design: the wrapped-source design note, ruled by the owner on 2026-11-02, amended the same day: the launcher infers nothing from a foreign tree (amendment 6).

What changed

digraph wrap {
  rankdir=LR; node [shape=box];
  cmd [label="project wrap URL\n--require CAP --java LINE\n(commands/project.py)"];
  op [label="wrap_project\n(wrap.py)"];
  git [label="git submodule add\n+ embedded .git"];
  init [label="initialize_project\nor require_tools"];
  decl [label="declare_source\n(owner_commands.py)"];
  man [label="[sources.\"path\"]\n(sources.py, manifest_schemas.py)", shape=folder];
  guide [label="AGENTS.md\nREADME.md", shape=note];
  show [label="config show\n(listing.py)"];
  cmd -> op; op -> git; op -> init; op -> decl -> man; op -> guide; man -> show;
}
  • The declaration. Schema 2 gains [sources."<path>"], one entry per submodule path, with upstream (present when the origin is the developer's fork) and java (the Java line the source builds with). configuration/sources.py validates and renders it; ManifestV2 reads it as its own table, the writer renders it after [capabilities], a schema-1 file refuses the word, and a launcher without the field carries it as an extension. declare_source edits the table alone and leaves the lock bytes untouched. config show lists one source row per entry.
  • The command. devcapsule project wrap URL [--path NAME] [--upstream URL] [--require CAPABILITY]... [--java LINE] plus init's owner options, shared through _add_owner_options. It adds the submodule, finds registrations by path (a section name is not a path), initializes a registered submodule whose directory is missing, moves the Git directory the submodule names into <path>/.git and unsets core.worktree by editing the file, so the capsule's bind mount sees a whole repository. It requires what the developer names, initializes the manifest and lock as init would or extends an existing manifest, declares the source, and writes AGENTS.md and README.md from the manifest: paths, origins and upstreams as code spans an agent can use verbatim; a source without a Java line described as unsettled, to be found out with the user. Files whose whole first line is the wrap marker are regenerated; others are kept and named. A rerun keeps a submodule already added from the same URL; failures name the state left behind and remove nothing.
  • Documentation. docs/your-project/someone-elses-repository.md, the wrap row and section in the CLI reference, R-CONFIG-001's new section on the optional table, R-WRAP-001, and both indexes.

Judgments for the owner

  1. The origin URL is not repeated in the manifest; .gitmodules holds it. The manifest holds what DevCapsule adds.
  2. upstream present means "fork, change it"; absent means "upstream, learn". One key carries the fork rule.
  3. wrap infers nothing: --require and --java are the developer's statements. The java key is an early form of the build's environment and is expected to fold into the project-capabilities design that follows.
  4. wrap writes nothing inside the submodule, does not install the project workflow, and does not recommend an IDE; config recommend ide does.
  5. Guidance files are regenerated on every wrap when they carry the marker as their whole first line; the owner's own files are left alone and named.
  6. Inputs are validated before any Git write; a partial clone is never removed.

Validation

See the comments: the first gate at 9af1fd1 and the final gate at 0a131d6. Both show 18 pre-existing failures specific to this capsule, none caused or fixed by the slice; typecheck passes; 270 focused tests pass. Preparation evidence from inside the 0.3.0 capsule: RobotCode2025Public fails under Temurin 25 at Gradle's script parser and builds under Temurin 17 with JAVA_HOME and PATH alone (BUILD SUCCESSFUL in 10m 55s, 25 tasks).

🤖 Generated with Claude Code

ccozianu and others added 10 commits November 2, 2026 23:16
A wrapper repository holds the DevCapsule configuration and a foreign
repository as a submodule, so a developer works on someone else's code in a
capsule with three commands. The work order records the owner's rulings of
2026-11-02: an ordinary project, several JDKs in the base, the fork rule, the
FRC learning project as the showcase, Codex as the review partner. The
registration lists the workstream in the root status and the index.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
The manifest gains a [sources] root table keyed by submodule path, with an
upstream key for the fork rule and a java key for the JDK line; the base
carries Temurin 17 beside 25 under stable names; the instruction reaches the
agent first and the capsule environment second; the IDE opens the wrapper
root so the agent reads the wrapper's guidance; wrap detects GradleRIO and
plain Gradle for the showcase and embeds the submodule's Git directory.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Schema 2 gains the [sources."<path>"] table: one entry per submodule path
with an upstream key, present when the origin is the developer's fork, and a
java key naming the Java line the source builds with. The reader validates
it, the writer renders it after capabilities, a schema-1 file refuses the
word, and a launcher without the field carries it as an extension.
declare_source edits the table alone, leaving the lock bytes untouched;
config show lists one row per source. Evidence: tests/test_sources.py and
the owner-command tests.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
wrap adds the repository as a submodule with its Git directory moved into
the tree the capsule mounts, reads what the source needs (a Gradle wrapper,
with or without GradleRIO, as data with its sources), initializes the
manifest and lock as init would or extends an existing manifest, declares
the source, and writes the wrapper's AGENTS.md and README.md from the
manifest, regenerated on every wrap and kept when they are the owner's. A
rerun keeps a submodule already added from the same URL. init and wrap share
the owner options. Evidence: tests/test_wrap.py over local bare
repositories and tests/test_wrap_detection.py.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Someone else's repository explains the three commands, what wrap reads off
the code, learning versus changing, several repositories and what wrap does
not do; the CLI reference gains the wrap row and section; R-CONFIG-001 names
the sources table as an optional table; R-WRAP-001 states the requirement;
the indexes list both.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Fix submodule path lookup, missing-directory recovery, metadata validation, failure reports, guidance escaping, and literal Gradle detection. Add manifest round-trip and listing coverage. Correct the user documentation.

Evidence: the initial regression run found 19 failures on PR1. After the fixes, 146 focused cases passed. The build gate passed mypy over 271 files and is running the full suite.

Co-authored-by: GPT-6 Astra Codex <noreply@openai.com>
@ccozianu

ccozianu commented Nov 3, 2026

Copy link
Copy Markdown
Owner Author

Validation of PR1 at 9af1fd1, in the dogfood capsule (Claude Code + Fable 5.1).

  • nox -s typecheck: success, 271 files.
  • nox -s tests: 2678 passed, 18 failed, 41 deselected, 1 xfailed, 1 xpassed, in 25m 53s. The 18 fail identically with this slice's code and tests stashed, so they are the capsule's, not the PR's:
    • 12 consent and trust tests (test_trust.py, test_capability_commands_v2.py, test_capability_minimums.py, test_console_channel.py, test_environment_realization.py, test_project_init.py, test_base_contract.py): inside a capsule settings_source falls back to the launcher's mounted settings at /etc/devcapsule/home/settings.toml when the test's private home has none, so the owner's trust answers leak into tests that expect a consent question.
    • 3 in test_repository_manifest_compatibility.py: they read this checkout's own manifest and lock, which carry the owner's uncommitted 0.3.0 migration (schema 2, no need, no interactive-surface).
    • 1 in test_home.py (test_replaced_scope_word_is_absent[tests]): a .venv inside the fastapi-webapp sample submodule in this checkout.
  • The new tests, 100 in test_sources.py, test_wrap_detection.py, test_wrap.py and test_owner_commands.py, pass.
  • CI on main at 31d44fa is green; the PR's own CI run is the clean-environment evidence.

Pending the owner's direction of 2026-11-02 in chat: the Gradle detection is to be removed from wrap (explicit --require and --java instead); that change lands on this branch after the PR1.1 review merges.

ccozianu and others added 4 commits November 3, 2026 02:25
Codex + gpt-6-astra review of the sources declaration and project wrap, accepted without a round. Inputs are validated before Git writes; submodules are found by path, missing registered directories are initialized, and the embedding asks the submodule for its Git directory; failures name the state left behind; the guidance marker is the exact first line and external text is escaped; detection ignores comments and strings; tests and pages updated.
The owner's ruling of 2026-11-02: the launcher infers nothing from a
foreign tree. Detecting Gradle special-cased the showcase into the product
and baked in facts about another tool. wrap now requires the capabilities
the developer names and declares the Java line the developer gives; a source
with no line is described to the agent as unsettled, to be found out with
the user. The guidance renders paths, origins and upstreams as code spans,
readable raw by an agent, in place of HTML entities; paths and upstreams
refuse control characters. Evidence: tests/test_wrap.py and
tests/test_sources.py; wrap_detection.py and its tests are deleted.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
@ccozianu

ccozianu commented Nov 3, 2026

Copy link
Copy Markdown
Owner Author

Gate on the final branch at 0a131d6 (after PR1.1 merged and the detection removed), in the dogfood capsule (Claude Code + Fable 5.1).

  • nox -s typecheck: success.
  • nox -s tests: 2711 passed, 18 failed, 41 deselected, 1 xfailed, 1 xpassed; total coverage 88%. The 18 are the same set as the first run, none new, none gone: the capsule's mounted launcher settings (12 consent and trust tests), this checkout's uncommitted manifest migration (3), and a venv inside the fastapi sample submodule (1); all fail with the slice stashed.
  • Focused: test_sources.py, test_wrap.py, test_owner_commands.py, test_project_commands.py, test_listing.py, test_cli.py: 270 passed.
  • The showcase wrapper produced by the final wrap is at ccozianu/devcapsule-sample-frc-learning on main (58d9219).

PR1 is handed to the owner. The design note for what follows, project capabilities settled and unsettled, is on the branch at engineering-docs/wip/2026-11-02-wrapped-projects/2026-11-03-design-project-capabilities.md and waits for the ruling.

ccozianu and others added 2 commits November 3, 2026 00:32
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
@ccozianu
ccozianu merged commit b3f10b7 into main Nov 3, 2026
5 checks passed
@ccozianu
ccozianu deleted the ws-wrapped-projects/wrap branch November 3, 2026 00:51
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant