From 4217250ec6744a1c3614ad01419ec19c90fa0a6d Mon Sep 17 00:00:00 2001 From: Costin Cozianu Date: Mon, 2 Nov 2026 23:16:14 +0000 Subject: [PATCH 01/15] Open the wrapped-projects workstream with its work order 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 --- CURRENT-STATUS.md | 1 + .../CURRENT-STATUS.md | 60 ++++++ .../intake-dispositions.md | 4 + .../intake/README.md | 9 + .../2026-11-02-wrapped-projects.md | 176 ++++++++++++++++++ index.md | 2 + 6 files changed, 252 insertions(+) create mode 100644 engineering-docs/wip/2026-11-02-wrapped-projects/CURRENT-STATUS.md create mode 100644 engineering-docs/wip/2026-11-02-wrapped-projects/intake-dispositions.md create mode 100644 engineering-docs/wip/2026-11-02-wrapped-projects/intake/README.md create mode 100644 engineering-docs/work-orders/2026-11-02-wrapped-projects.md diff --git a/CURRENT-STATUS.md b/CURRENT-STATUS.md index 6d66ae58..efaf7ba5 100644 --- a/CURRENT-STATUS.md +++ b/CURRENT-STATUS.md @@ -19,6 +19,7 @@ coordination branch. Detailed state belongs in each linked status file. | `user-docs` | 2026-09-12 | Deliver V1 adopter documentation from first useful session through resuming work | paused 2026-09-28; 0.2.15 documentation merged in PR #151 and on docs-0.2.15; improvement list awaits the owner's decision | `ws-user-docs/first-session` | [workstream status](engineering-docs/wip/2026-09-12-user-docs/CURRENT-STATUS.md) | | `website` | 2026-09-16 | Deliver the website autonomy experiment: repository-owned landing/docs/blog content, independently developable website submodule, local preview and publishing mechanism | paused 2026-09-30; producer migration merged in PR #152 and the versioned documentation live; W04-C, W09-C, W11-C retained | `ws-website/contract-v1` | [workstream status](engineering-docs/wip/2026-09-16-website/CURRENT-STATUS.md) | | `capsule-webconsole` | 2026-10-09 | Serve a token-gated web console from every capsule: configuration, versions, info, live resources, later records and workflow state | active; work order accepted 2026-10-09; the first iteration, deliverables 1 and 2, is three stacked pull requests, #184, #186 and the runtime-and-base slice, each reviewed by the Codex pair; the owner merges | `ws-capsule-webconsole/first-slice` | [workstream status](engineering-docs/wip/2026-10-09-capsule-webconsole/CURRENT-STATUS.md) | +| `wrapped-projects` | 2026-11-02 | Wrap a foreign repository as a submodule of a small wrapper project and work on it in a capsule with three commands; FRC learning project first | active; opened 2026-11-02 at the owner's direction; design and JDK experiment in progress | `ws-wrapped-projects/wrap` | [workstream status](engineering-docs/wip/2026-11-02-wrapped-projects/CURRENT-STATUS.md) | | `website` | 2026-09-16 | Deliver the website autonomy experiment: repository-owned landing/docs/blog content, independently developable website submodule, local preview and publishing mechanism | paused 2026-09-20 at owner request to switch to maintenance; experiment accepted, A−; blog integrated and published; content/parent-integration follow-ups remain | `ws-website/initial-cut`; renamed from `website/initial-cut`; preparation and backlog-handoff exceptions in status | [workstream status](engineering-docs/wip/2026-09-16-website/CURRENT-STATUS.md) | Paused and blocked workstreams remain open until they conclude successfully or diff --git a/engineering-docs/wip/2026-11-02-wrapped-projects/CURRENT-STATUS.md b/engineering-docs/wip/2026-11-02-wrapped-projects/CURRENT-STATUS.md new file mode 100644 index 00000000..207603e3 --- /dev/null +++ b/engineering-docs/wip/2026-11-02-wrapped-projects/CURRENT-STATUS.md @@ -0,0 +1,60 @@ +# Workstream Current Status: Wrapped Projects + +Mnemonic: `wrapped-projects` + +Start date: 2026-11-02 + +State: active; opened 2026-11-02 at the owner's direction; design and the JDK experiment in progress + +Definition read: WORKFLOW.md@635ed43f2fde, WORKFLOW-LOCAL.md@fb8d8f100502 + +Branch association: `ws-wrapped-projects/wrap`, forked from `origin/main` at 31d44fa473a8 + +Integration target: `main` + +Delivery method: pull request, merge commit, under the Pair Review Loop with Codex as the review partner + +Requirements: R-CONFIG-001, R-SCOPE-001; a new requirement for the wrapped-project shape is a deliverable + +Work order: [wrapped projects](../../work-orders/2026-11-02-wrapped-projects.md), issued 2026-11-02 by the owner and accepted as this workstream's goal + +## Goal And Scope + +Let a developer wrap a foreign repository, one that is not theirs and carries no DevCapsule +configuration, in a small wrapper repository of their own, as a submodule, and work on it in a +capsule with three commands. The showcase is an FRC learning project around Mechanical-Advantage's +public robot code. The work order holds the owner's rulings; this file holds the state. + +## Current State + +**2026-11-02, opened.** The owner described the feature and ruled on its shape in conversation. +The work order records the rulings. Preparation evidence from inside the 0.3.0 capsule: + +- A shallow clone of RobotCode2025Public, Gradle 8.11 through its wrapper, under the capsule's + Temurin 25.0.4+7: `BUILD FAILED`, `Unsupported class file major version 69` during the + build script's semantic analysis, before any Java compiled. Exit 1 after 2m 5s, most of it + the Gradle download. +- The same build under a Temurin 17 downloaded into the session scratch: in progress when + this file was written; the result is recorded below when it lands. + +## Next Resumable Task + +1. Record the Temurin 17 build result here. +2. Write `2026-11-02-design-wrapped-source.md`: the manifest shape, the JDK selection + mechanism, the IDE opening rule, the detection rules for the showcase. Stop there for the + owner's reading in the IDE; this is the first stopping point of the work order. +3. After the ruling: slice 1, the declaration and `project wrap`, as PR1 with its Codex review. + +## Open Threads + +- The release target is the owner's to fix at the first stopping point. +- `project-management` has four items waiting in its mailbox from 2026-10-31; this session + left them untaken because the owner directed it to open this workstream instead. +- The owner's checkout carries an uncommitted 0.3.0 migration of the dogfood manifest and lock + (schema 2) and an IDE module file change; they are not this workstream's and travel + uncommitted. + +## Document Index + +- [the work order](../../work-orders/2026-11-02-wrapped-projects.md): read first. +- `intake/` and `intake-dispositions.md`: the queue and its log; empty at opening. diff --git a/engineering-docs/wip/2026-11-02-wrapped-projects/intake-dispositions.md b/engineering-docs/wip/2026-11-02-wrapped-projects/intake-dispositions.md new file mode 100644 index 00000000..cde58ff9 --- /dev/null +++ b/engineering-docs/wip/2026-11-02-wrapped-projects/intake-dispositions.md @@ -0,0 +1,4 @@ +# Intake Decisions: `wrapped-projects` + +Record each removed intake item, its decision, reasoning, and resulting +status file requirement or task here. diff --git a/engineering-docs/wip/2026-11-02-wrapped-projects/intake/README.md b/engineering-docs/wip/2026-11-02-wrapped-projects/intake/README.md new file mode 100644 index 00000000..ae256b20 --- /dev/null +++ b/engineering-docs/wip/2026-11-02-wrapped-projects/intake/README.md @@ -0,0 +1,9 @@ +# Intake: `wrapped-projects` + +Work other workstreams have delivered to `wrapped-projects` and that it has not +yet decided. Senders add one file per item, named +`YYYY-MM-DD--.md`, and deliver it by mail on the +coordination branch, never through `main` or by editing this directory. Each +item is acknowledged into the status file or forwarded as `WORKFLOW.md` +permits, and every decision is recorded in `intake-dispositions.md` before the +item is removed. diff --git a/engineering-docs/work-orders/2026-11-02-wrapped-projects.md b/engineering-docs/work-orders/2026-11-02-wrapped-projects.md new file mode 100644 index 00000000..c0d339f9 --- /dev/null +++ b/engineering-docs/work-orders/2026-11-02-wrapped-projects.md @@ -0,0 +1,176 @@ +# Work Order: Wrapped Projects + +Origin: product-owner direction, 2026-11-02, after a conversation at an AI expo with a +high-school FIRST Robotics team whose Java robot code is private on GitHub. +Status: accepted the same day by the `wrapped-projects` workstream, which this order opens. +Coordination owner: `project-management`. Implementation owner: `wrapped-projects`. +Release target: the next minor after 0.3.0, to be fixed by the owner at the first stopping point. +Requirements: R-CONFIG-001 (the manifest) and R-SCOPE-001 (what is shared with the capsule); +a new requirement for the wrapped-project shape is a deliverable of this order. + +## Outcome + +A developer can give DevCapsule a repository that is not theirs and does not carry a DevCapsule +configuration, and work on it inside a capsule: browse it in the IDE, build it, run its tests, +debug it, and let a coding agent do the same. Nothing is imposed on the foreign repository. The +DevCapsule configuration lives in a small wrapper repository of the developer's own, and the +foreign code is a Git submodule of that wrapper. + +The three commands the developer types, in an empty directory: + +```bash +git init +devcapsule project wrap https://github.com/Mechanical-Advantage/RobotCode2025Public +devcapsule project run +``` + +`wrap` adds the repository as a submodule, looks at what it finds there, writes the manifest +and the lock, and writes the guidance an agent needs. `run` opens the capsule with the IDE on +the foreign code. `wrap` is repeatable: a wrapper may hold several foreign repositories. +The developer never writes TOML. + +The showcase, and the first acceptance target, is an FRC learning project: a wrapper around +FRC team 6328 Mechanical-Advantage's public robot code, Java built with Gradle and WPILib's +GradleRIO plugin, MIT licensed. A team that keeps its own code private can use that wrapper to +learn from the best team's code in an afternoon instead of following installation instructions. + +The second audience is anyone who wants to read, build or debug an open-source project whose +development setup is a chore, and the maintainer who receives a message saying: instead of an +afternoon of setup, `devcapsule project run`. + +## Decisions already taken + +The owner ruled these on 2026-11-02. + +1. **A wrapper is an ordinary project.** There is no new project kind. The manifest of a wrapper + is a schema-2 manifest that additionally names its wrapped sources. The owner's standing rule + applies: an unjustified concept is deleted outright, never replaced by a smaller one. +2. **Several JDKs live in the base image.** Temurin 25 stays the default under `/opt/java/current` + and on `PATH`. The base additionally carries a Temurin 17 under `/opt/java/jdk-17...`. A wrapped + source names the JDK line it builds with, and that selection reaches the IDE, the terminal and + the agent: either `JAVA_HOME` and `PATH` set for the whole capsule when every wrapped source + agrees, or set just in time by the instruction the agent reads when it works in that source. + The owner's view: current agents follow such an instruction reliably, so the instruction is + an acceptable first delivery and the global setting is the refinement. +3. **The foreign repository is never edited through the wrapper's upstream pointer.** When the + developer intends to change the code, the submodule points at a fork they control; when they + only learn, it may point at the upstream. `wrap` takes the URL it is given and records which + case this is. Pull requests go to the fork, never unsolicited to the upstream. +4. **One concrete use case first.** The FRC wrapper is the acceptance target. The general case is + designed so that it works, but nothing is built that the showcase does not exercise. +5. **The pair.** Claude (Fable 5.1) designs and implements; Codex is the review partner under the + Pair Review Loop as the local workflow file applies it. + +## Deliverables + +### The wrapped-source declaration + +The manifest names each wrapped source: its path in the wrapper, its origin URL, whether that +origin is an upstream or the developer's fork, and the toolchain it builds with, the JDK line +for a Java source. Older launchers must still read a wrapper's manifest; schema 2 tolerates +unknown root tables, and the declaration must stay within that tolerance or come with a schema +change the owner has ruled on. The exact table and keys are the workstream's to choose and to +record in R-CONFIG-001. + +Done means a manifest with the declaration round-trips through every command that rewrites the +manifest without losing it, and `project config show` reports it. + +### `project wrap` + +`devcapsule project wrap URL [--path NAME] [--fork]` in a Git repository: + +1. Adds the repository as a submodule at the path, the repository's name by default, with the + embedded Git directory the capsule needs, so the submodule works from inside the capsule on + the first run. +2. Detects what the source needs from what is in it. For the showcase: a Gradle wrapper and + GradleRIO mean Java; the GradleRIO version decides the JDK line. Unknown contents produce a + manifest the developer can complete with the ordinary `project config` commands, and say so. +3. Writes or extends the manifest and lock as `init` would: the required capabilities, the + recommended IDE, the wrapped-source declaration. A second `wrap` adds a source to an existing + manifest and reconciles the capabilities. +4. Writes the wrapper's `AGENTS.md` and `README.md` when absent: what this wrapper is, which + directories are foreign and under whose control, how to build, test and run each, which JDK + each uses and how to select it, and where changes go. The files are portable, in the owner's + words agent-neutral; nothing is written for one agent product. +5. Does not install the project workflow. `project bootstrap` stays available for a wrapper + whose owner wants it. + +Done means the three commands above, in an empty directory on a machine with DevCapsule +installed, produce a wrapper whose next `run` opens the capsule; and the wrapper repository +contains only `.devcapsule/`, `.gitmodules`, the submodule, `AGENTS.md` and `README.md`. + +### The capsule's behaviour on a wrapper + +1. The IDE opens on the foreign code. With one wrapped source, IntelliJ opens that source as + the project so the Gradle import happens. With several, the behaviour is the workstream's + choice, backed by evidence from a real launch, and recorded. +2. The JDK selection reaches the build. Inside the capsule, the source's Gradle wrapper builds + with the declared JDK whether the developer types the command in the IDE terminal or an agent + runs it from the instruction. +3. The base image carries the JDK lines the catalog lists, Temurin 17 and 25 at delivery, under + `/opt/java/`, with 25 current. Adding a line is a catalog change, not a design change. + +Done means the acceptance evidence below. + +### Documentation and records + +A page under `docs/your-project/`, *Someone else's repository*, with the three commands, what +`wrap` writes, the fork rule and the JDK rule; the CLI reference updated; a requirement for the +wrapped-project shape under `engineering-docs/requirements/product/`; R-CONFIG-001 extended for +the declaration; the release notes entry. Nothing is advertised before it runs. + +## Acceptance evidence + +On the built executable, from an empty directory, with the showcase repository: + +1. The three commands run without prompts beyond those `init` and `run` already ask. +2. Inside the capsule, `./gradlew build -x spotlessCheck` in the wrapped source succeeds with + the declared JDK, from the IDE terminal and from an agent told only to build the project. +3. IntelliJ opens with the robot code imported as a Gradle project and navigable. +4. The wrapper repository holds nothing but the files named above; the foreign repository's + working tree is clean after the launch. +5. A second `wrap` of another Mechanical-Advantage Java repository into the same wrapper + leaves the first intact and both buildable. +6. A launcher older than this feature reads the wrapper's manifest and runs the capsule, + without the JDK selection. +7. The repository gate from WORKFLOW-LOCAL.md passes; the base image rebuild is recorded with + its evidence. + +Preparation evidence, 2026-11-02, inside the 0.3.0 capsule, on a shallow clone of +RobotCode2025Public at its current default branch: Gradle 8.11 under Temurin 25.0.4+7 fails +before compiling anything, with `Unsupported class file major version 69` in the build script's +semantic analysis. The same build under a Temurin 17 is the second experiment; its result is +recorded in the workstream's status file. + +## Execution decisions and stopping points + +The workstream owns the manifest representation, the detection rules, code placement and test +design. It records a short design note before implementing, with the manifest shape, the JDK +selection mechanism and the IDE opening rule, and the owner reads it in the IDE on the +workstream's branch. + +Stopping points where the owner is consulted: + +1. After the design note and the Temurin 17 experiment, before implementation: the manifest + shape and the release target. +2. Before the base image change: a base rebuild is costly and publishes a new reference; the + owner says when. +3. Any need to change the manifest schema, the capability requirement syntax (today only + `NAME>=VERSION`), or what is shared with the capsule. +4. Simulation of the robot code, which needs native libraries and a display, is out of scope + until the owner names it. + +## Evidence and starting points + +Mainline evidence was read at `origin/main` 31d44fa473a86f608110caa53ee38c6aef40a717, the merge of the 0.3.0 final acceptance. +The capsule this was written in runs the shipped DevCapsule 0.3.0, source revision +475427da033633ff5ee0e44e09face700630bf36, with Temurin 25.0.4+7 as the only JDK. + +Relevant source: `devcapsule-src/devcapsule/commands/project.py` (the `init` command and the +`config` group), `configuration/operations.py` (`initialize_project`), +`configuration/manifest_schemas.py` (schema 2 tolerates unknown root tables), +`configuration/capabilities.py` (the requirement form), `images/tooling.py` and `images/base.py` +(the Temurin component), `components/intellij.py`. The user page +`docs/your-project/existing-repository.md` is where the new page sits beside. +The sample-projects workstream's submodule practice and the memory of embedded Git directories +in submodules are the known traps. diff --git a/index.md b/index.md index da730545..d52fa3aa 100644 --- a/index.md +++ b/index.md @@ -134,6 +134,7 @@ status file; internal WIP/archive documents use the local index in that status. ## Work Orders +- [Wrapped projects: a foreign repository as a submodule, three commands](engineering-docs/work-orders/2026-11-02-wrapped-projects.md) - [0.3.0 user documentation CLI alignment, full stub authoring, and prose review — maintenance, 0.3.0](engineering-docs/work-orders/2026-10-30-user-docs-0-3-0-cli-alignment.md) - [CI path gating and advisory diff coverage — maintenance, 0.3.0](engineering-docs/work-orders/2026-10-30-ci-path-gating-and-diff-coverage.md) - [Structural guardrails for the repository with ast-grep](engineering-docs/work-orders/2026-10-29-ast-grep-guardrails.md) @@ -175,6 +176,7 @@ status file; internal WIP/archive documents use the local index in that status. - [Component upgrades current status](engineering-docs/wip/2026-09-21-component-upgrades/CURRENT-STATUS.md) - [Maintenance current status](engineering-docs/wip/2026-09-18-maintenance/CURRENT-STATUS.md) - [Capsule web console current status](engineering-docs/wip/2026-10-09-capsule-webconsole/CURRENT-STATUS.md) +- [Wrapped projects current status](engineering-docs/wip/2026-11-02-wrapped-projects/CURRENT-STATUS.md) - [Sample demo projects current status](engineering-docs/wip/2026-08-14-sample-projects/CURRENT-STATUS.md) - [Contained display current status](engineering-docs/wip/2026-08-19-contained-display/CURRENT-STATUS.md) From 812d44ed9a00ad26172d6a38cd01826d5869aabe Mon Sep 17 00:00:00 2001 From: Costin Cozianu Date: Mon, 2 Nov 2026 23:18:56 +0000 Subject: [PATCH 02/15] Design the wrapped source for the owner's ruling 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 --- .../2026-11-02-design-wrapped-source.md | 136 ++++++++++++++++++ .../CURRENT-STATUS.md | 3 +- 2 files changed, 138 insertions(+), 1 deletion(-) create mode 100644 engineering-docs/wip/2026-11-02-wrapped-projects/2026-11-02-design-wrapped-source.md diff --git a/engineering-docs/wip/2026-11-02-wrapped-projects/2026-11-02-design-wrapped-source.md b/engineering-docs/wip/2026-11-02-wrapped-projects/2026-11-02-design-wrapped-source.md new file mode 100644 index 00000000..e030f6f7 --- /dev/null +++ b/engineering-docs/wip/2026-11-02-wrapped-projects/2026-11-02-design-wrapped-source.md @@ -0,0 +1,136 @@ +# Design: the wrapped source + +Date: 2026-11-02. Status: for the owner's ruling at the first stopping point of +[the work order](../../work-orders/2026-11-02-wrapped-projects.md). Each section +ends with the recommendation and, where one exists, the alternative in a line. + +## 1. What the manifest says + +Schema 2 names seven root tables and tolerates any other as an extension that its +writer carries along (`configuration/manifest_schemas.py`). The declaration is one +new root table, `[sources]`, one entry per wrapped source, keyed by the source's +path in the wrapper: + +```toml +[sources."RobotCode2025Public"] +java = "17" +``` + +```toml +[sources."RobotCode2026Public"] +upstream = "https://github.com/Mechanical-Advantage/RobotCode2026Public" +java = "17" +``` + +- The key is the submodule path. The origin URL is not repeated: `.gitmodules` holds + it and Git keeps it true. The manifest holds only what DevCapsule adds. +- `upstream`, when present, says the submodule's origin is the developer's fork of + that upstream, so changes and pull requests go to the origin and the upstream is + read-only. Absent, the origin is the upstream itself and the intent is to learn: + no changes are pushed anywhere. This is the work order's fork rule, as one key. +- A toolchain key is named after the capability it refines: `java = "17"` says this + source builds with the Java 17 line. The project-level requirement stays the + capability, `capabilities.required = ["java"]`; the per-source key says which line, + since the requirement syntax knows only `NAME>=VERSION` and a 25 would satisfy `>=17` + while GradleRIO rejects it. Other capabilities get the same form later, `python = + "3.11"`, when a source needs them; nothing is built for them now. +- A launcher older than this feature reads the table as an extension and ignores it: + the capsule runs, without the JDK selection. Slice 1 proves the round trip through + every manifest-writing command. + +Recommendation: `[sources.""]` with `upstream` and `java`. Alternative: put the +selection under `[capabilities]` as a new key; rejected because the selection is per +source, not per project, and a wrapper with two sources on different lines is real. + +## 2. How the JDK reaches the build + +The base image installs Temurin 17 beside Temurin 25, each under its versioned +directory, with two stable names the manifest and the instructions can rely on across +base updates: + +```text +/opt/java/current -> /opt/java/jdk-25.0.4+7 unchanged, on PATH +/opt/java/25 -> /opt/java/jdk-25.0.4+7 +/opt/java/17 -> /opt/java/jdk-17.0.x+y +``` + +Two deliveries, in the order the owner ruled: + +1. **The instruction.** `wrap` writes into the wrapper's `AGENTS.md`, per source, the + exact line: `export JAVA_HOME=/opt/java/17; export PATH="$JAVA_HOME/bin:$PATH"`, + to run before any build, test or run in that source. The `README.md` carries the + same line for the human at the IDE terminal. This works on the first base that + carries the JDK, with no runtime change. +2. **The capsule environment.** When every wrapped source names the same line, the + runtime plan carries `JAVA_HOME` and the `PATH` prefix for the whole session, so + the IDE terminal, Gradle's daemon and IntelliJ's JDK detection see 17 without + anyone typing the line. When sources disagree, the capsule stays on `current` and + the instruction governs. The plan's environment is an existing contract + (`container_runtime/contract.py`); the addition is one more source of entries. + +What is not done: no `gradle.properties`, `.sdkmanrc` or `.java-version` is written +into the foreign tree. The foreign tree stays clean; that is the point. + +Recommendation: both, instruction in slice 1, environment in slice 2 with the base. +Alternative: only the environment; rejected because two sources on different lines +would have no answer. + +## 3. What the IDE opens, and where the agent starts + +The IDE opens the wrapper root, as it does for every project, and the agent starts +there. The reason is the agent: Claude Code and Codex read `AGENTS.md` from the +working directory up to the Git root, and the submodule is its own Git root. An IDE +that opened the submodule would start the agent inside it, blind to the wrapper's +guidance, and the only fix would be a file inside the foreign tree. + +For IntelliJ to import the Gradle project automatically from the wrapper root, `wrap` +writes a minimal `.idea/gradle.xml` in the wrapper that links each Gradle source, and +names the project JDK from the declared line. These files are the wrapper's, not the +foreign tree's, and they are the same files IntelliJ writes itself after a manual +"link Gradle project". Whether the link file is needed at all, or a one-time click is +acceptable, is decided by the slice 2 launch and recorded. + +Recommendation: open the wrapper root; link Gradle through the wrapper's own IDE +files. Alternative: open the single source directly when there is one; rejected for +the agent reason above. + +## 4. What `wrap` detects, for the showcase + +In the submodule just added, in this order, first match wins: + +| Found | Declared | +|---|---| +| `gradlew` and a `build.gradle` or `build.gradle.kts` naming `edu.wpi.first.GradleRIO` | `java` required, `java-ide` recommended; `java = "17"` for GradleRIO 2025 and 2026 | +| `gradlew` without GradleRIO | `java` required, `java-ide` recommended; the line from the Gradle version in `gradle/wrapper/gradle-wrapper.properties`: Gradle 8.x gets `17`, Gradle 9.x gets `25` | +| anything else | nothing declared; `wrap` says so and names `project config require` | + +The GradleRIO rule is a fact about WPILib: its 2025 and 2026 releases ship and require +JDK 17. The Gradle rule is a fact about Gradle's Java compatibility table. Both are +data in one small module with the source of each fact beside it, so a new WPILib year +is a one-line change. Maven, Node and Python detection are not built now; the work +order names one use case. + +## 5. The submodule, done right the first time + +`wrap` runs `git submodule add `, then moves `.git/modules/` into +`/.git` and unsets `core.worktree`, so the submodule's Git directory is inside +the tree the capsule mounts. This is the known trap from the dogfood checkout; `wrap` +removes it for every adopter. The `README.md` it writes tells a cloner of the wrapper +to run `git submodule update --init`, which produces the same embedded layout on a +fresh clone. + +## 6. Slices + +1. **The declaration and `wrap`.** `[sources]` read and written and reported by + `project config show`; `project wrap URL [--path NAME] [--upstream URL]`; the + `AGENTS.md` and `README.md` it writes; the detection module; the user page draft; + R-CONFIG-001 extended; unit and built-CLI tests. No base change. Validation: the + gate, plus the three commands run against the showcase repository on the host side + up to the manifest and lock. +2. **The base and the capsule.** Temurin 17 in the base with the stable names; the + environment entries in the runtime plan; the IntelliJ link; the acceptance run of + the work order inside a capsule. Starts after the owner's go at the second stopping + point. + +Each slice is one pull request with its Codex review, as the local Pair Review Loop +says. diff --git a/engineering-docs/wip/2026-11-02-wrapped-projects/CURRENT-STATUS.md b/engineering-docs/wip/2026-11-02-wrapped-projects/CURRENT-STATUS.md index 207603e3..7e7913ab 100644 --- a/engineering-docs/wip/2026-11-02-wrapped-projects/CURRENT-STATUS.md +++ b/engineering-docs/wip/2026-11-02-wrapped-projects/CURRENT-STATUS.md @@ -6,7 +6,7 @@ Start date: 2026-11-02 State: active; opened 2026-11-02 at the owner's direction; design and the JDK experiment in progress -Definition read: WORKFLOW.md@635ed43f2fde, WORKFLOW-LOCAL.md@fb8d8f100502 +Definition read: WORKFLOW.md@d2ccbbe43dfa, WORKFLOW-LOCAL.md@65501b3407db Branch association: `ws-wrapped-projects/wrap`, forked from `origin/main` at 31d44fa473a8 @@ -57,4 +57,5 @@ The work order records the rulings. Preparation evidence from inside the 0.3.0 c ## Document Index - [the work order](../../work-orders/2026-11-02-wrapped-projects.md): read first. +- [the wrapped-source design](2026-11-02-design-wrapped-source.md): the manifest shape, the JDK mechanism, the IDE rule, the detection rules; open for the first stopping point. - `intake/` and `intake-dispositions.md`: the queue and its log; empty at opening. From 2f7aff3915b320598488cb15990013a97728c3f2 Mon Sep 17 00:00:00 2001 From: Costin Cozianu Date: Mon, 2 Nov 2026 23:21:37 +0000 Subject: [PATCH 03/15] Record the showcase wrapper's repository Co-Authored-By: Claude Fable 5.1 --- .../wip/2026-11-02-wrapped-projects/CURRENT-STATUS.md | 4 ++++ engineering-docs/work-orders/2026-11-02-wrapped-projects.md | 6 ++++++ 2 files changed, 10 insertions(+) diff --git a/engineering-docs/wip/2026-11-02-wrapped-projects/CURRENT-STATUS.md b/engineering-docs/wip/2026-11-02-wrapped-projects/CURRENT-STATUS.md index 7e7913ab..301c86f3 100644 --- a/engineering-docs/wip/2026-11-02-wrapped-projects/CURRENT-STATUS.md +++ b/engineering-docs/wip/2026-11-02-wrapped-projects/CURRENT-STATUS.md @@ -37,6 +37,10 @@ The work order records the rulings. Preparation evidence from inside the 0.3.0 c - The same build under a Temurin 17 downloaded into the session scratch: in progress when this file was written; the result is recorded below when it lands. +**2026-11-02, the sample repository.** The owner created +`git@github.com:ccozianu/devcapsule-sample-frc-learning.git` for the showcase wrapper. The +wrapper the three commands produce is pushed there; the work order records it. + ## Next Resumable Task 1. Record the Temurin 17 build result here. diff --git a/engineering-docs/work-orders/2026-11-02-wrapped-projects.md b/engineering-docs/work-orders/2026-11-02-wrapped-projects.md index c0d339f9..a685f8c7 100644 --- a/engineering-docs/work-orders/2026-11-02-wrapped-projects.md +++ b/engineering-docs/work-orders/2026-11-02-wrapped-projects.md @@ -34,6 +34,12 @@ FRC team 6328 Mechanical-Advantage's public robot code, Java built with Gradle a GradleRIO plugin, MIT licensed. A team that keeps its own code private can use that wrapper to learn from the best team's code in an afternoon instead of following installation instructions. +The showcase wrapper has its own repository, created by the owner on 2026-11-02: +`git@github.com:ccozianu/devcapsule-sample-frc-learning.git`. The wrapper produced by the +three commands is pushed there, and at delivery it joins the other sample projects as a +submodule under `devcapsule-src/tests/resources/sample_projects/`, following the pattern of +the `sample-projects` workstream; taken as decided, flagged here for the owner. + The second audience is anyone who wants to read, build or debug an open-source project whose development setup is a chore, and the maintainer who receives a message saying: instead of an afternoon of setup, `devcapsule project run`. From 152c266c06f09032e6f17c687aacce72da46239a Mon Sep 17 00:00:00 2001 From: Costin Cozianu Date: Mon, 2 Nov 2026 23:28:32 +0000 Subject: [PATCH 04/15] Note that the Gradle cache persists with the capsule home Co-Authored-By: Claude Fable 5.1 --- .../2026-11-02-design-wrapped-source.md | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/engineering-docs/wip/2026-11-02-wrapped-projects/2026-11-02-design-wrapped-source.md b/engineering-docs/wip/2026-11-02-wrapped-projects/2026-11-02-design-wrapped-source.md index e030f6f7..3422dec6 100644 --- a/engineering-docs/wip/2026-11-02-wrapped-projects/2026-11-02-design-wrapped-source.md +++ b/engineering-docs/wip/2026-11-02-wrapped-projects/2026-11-02-design-wrapped-source.md @@ -134,3 +134,12 @@ fresh clone. Each slice is one pull request with its Codex review, as the local Pair Review Loop says. + +## 7. The downloaded internet stays downloaded + +One build of the showcase pulls Gradle itself and a few hundred megabytes of +dependencies into `~/.gradle`. The capsule's home is already a persistent mount per +checkout (`persistence.py`), so the cache survives sessions with no new mechanism, and +the second launch builds offline-fast. The cost is paid once per wrapper checkout, not +once per session. Nothing to build here; the acceptance run records the second-launch +build time beside the first to prove it. From 8246852bb57e08938790685ef50361244d15cc85 Mon Sep 17 00:00:00 2001 From: Costin Cozianu Date: Mon, 2 Nov 2026 23:29:05 +0000 Subject: [PATCH 05/15] Record the Temurin 17 build of the robot code Co-Authored-By: Claude Fable 5.1 --- CURRENT-STATUS.md | 2 +- .../CURRENT-STATUS.md | 16 +++++++++++----- 2 files changed, 12 insertions(+), 6 deletions(-) diff --git a/CURRENT-STATUS.md b/CURRENT-STATUS.md index efaf7ba5..6ed34938 100644 --- a/CURRENT-STATUS.md +++ b/CURRENT-STATUS.md @@ -19,7 +19,7 @@ coordination branch. Detailed state belongs in each linked status file. | `user-docs` | 2026-09-12 | Deliver V1 adopter documentation from first useful session through resuming work | paused 2026-09-28; 0.2.15 documentation merged in PR #151 and on docs-0.2.15; improvement list awaits the owner's decision | `ws-user-docs/first-session` | [workstream status](engineering-docs/wip/2026-09-12-user-docs/CURRENT-STATUS.md) | | `website` | 2026-09-16 | Deliver the website autonomy experiment: repository-owned landing/docs/blog content, independently developable website submodule, local preview and publishing mechanism | paused 2026-09-30; producer migration merged in PR #152 and the versioned documentation live; W04-C, W09-C, W11-C retained | `ws-website/contract-v1` | [workstream status](engineering-docs/wip/2026-09-16-website/CURRENT-STATUS.md) | | `capsule-webconsole` | 2026-10-09 | Serve a token-gated web console from every capsule: configuration, versions, info, live resources, later records and workflow state | active; work order accepted 2026-10-09; the first iteration, deliverables 1 and 2, is three stacked pull requests, #184, #186 and the runtime-and-base slice, each reviewed by the Codex pair; the owner merges | `ws-capsule-webconsole/first-slice` | [workstream status](engineering-docs/wip/2026-10-09-capsule-webconsole/CURRENT-STATUS.md) | -| `wrapped-projects` | 2026-11-02 | Wrap a foreign repository as a submodule of a small wrapper project and work on it in a capsule with three commands; FRC learning project first | active; opened 2026-11-02 at the owner's direction; design and JDK experiment in progress | `ws-wrapped-projects/wrap` | [workstream status](engineering-docs/wip/2026-11-02-wrapped-projects/CURRENT-STATUS.md) | +| `wrapped-projects` | 2026-11-02 | Wrap a foreign repository as a submodule of a small wrapper project and work on it in a capsule with three commands; FRC learning project first | active; opened 2026-11-02; design note and JDK experiment done; the owner's first ruling pending | `ws-wrapped-projects/wrap` | [workstream status](engineering-docs/wip/2026-11-02-wrapped-projects/CURRENT-STATUS.md) | | `website` | 2026-09-16 | Deliver the website autonomy experiment: repository-owned landing/docs/blog content, independently developable website submodule, local preview and publishing mechanism | paused 2026-09-20 at owner request to switch to maintenance; experiment accepted, A−; blog integrated and published; content/parent-integration follow-ups remain | `ws-website/initial-cut`; renamed from `website/initial-cut`; preparation and backlog-handoff exceptions in status | [workstream status](engineering-docs/wip/2026-09-16-website/CURRENT-STATUS.md) | Paused and blocked workstreams remain open until they conclude successfully or diff --git a/engineering-docs/wip/2026-11-02-wrapped-projects/CURRENT-STATUS.md b/engineering-docs/wip/2026-11-02-wrapped-projects/CURRENT-STATUS.md index 301c86f3..4b70f55b 100644 --- a/engineering-docs/wip/2026-11-02-wrapped-projects/CURRENT-STATUS.md +++ b/engineering-docs/wip/2026-11-02-wrapped-projects/CURRENT-STATUS.md @@ -4,7 +4,7 @@ Mnemonic: `wrapped-projects` Start date: 2026-11-02 -State: active; opened 2026-11-02 at the owner's direction; design and the JDK experiment in progress +State: active; opened 2026-11-02; design note and JDK experiment done; waiting for the owner's ruling at the first stopping point Definition read: WORKFLOW.md@d2ccbbe43dfa, WORKFLOW-LOCAL.md@65501b3407db @@ -34,8 +34,14 @@ The work order records the rulings. Preparation evidence from inside the 0.3.0 c Temurin 25.0.4+7: `BUILD FAILED`, `Unsupported class file major version 69` during the build script's semantic analysis, before any Java compiled. Exit 1 after 2m 5s, most of it the Gradle download. -- The same build under a Temurin 17 downloaded into the session scratch: in progress when - this file was written; the result is recorded below when it lands. +- The same build under Temurin 17.0.21+9, downloaded into the session scratch and selected + with `JAVA_HOME` and `PATH` only: `BUILD SUCCESSFUL in 10m 55s`, 25 tasks executed, + `compileJava`, `test` and `check` among them, exit 0. The foreign tree was clean afterwards + even though the project's own build runs `spotlessApply` before compiling. The Gradle cache + under the capsule home grew to 1.4 GB; the design's section 7 is why that is paid once. + Both runs were made in this capsule's shell, not in a child capsule: no base with a second + JDK exists yet, and the question needed one build each. Conclusion: the JDK line is the + whole difference, and `JAVA_HOME` plus `PATH` is a sufficient selection mechanism. **2026-11-02, the sample repository.** The owner created `git@github.com:ccozianu/devcapsule-sample-frc-learning.git` for the showcase wrapper. The @@ -43,8 +49,8 @@ wrapper the three commands produce is pushed there; the work order records it. ## Next Resumable Task -1. Record the Temurin 17 build result here. -2. Write `2026-11-02-design-wrapped-source.md`: the manifest shape, the JDK selection +1. Done: the Temurin 17 result is above. +2. Done: wrote `2026-11-02-design-wrapped-source.md`: the manifest shape, the JDK selection mechanism, the IDE opening rule, the detection rules for the showcase. Stop there for the owner's reading in the IDE; this is the first stopping point of the work order. 3. After the ruling: slice 1, the declaration and `project wrap`, as PR1 with its Codex review. From 92086c4661026b66929cec8b18eeede70f9045a1 Mon Sep 17 00:00:00 2001 From: Costin Cozianu Date: Mon, 2 Nov 2026 23:51:28 +0000 Subject: [PATCH 06/15] Declare wrapped sources in the manifest Schema 2 gains the [sources.""] 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 --- .../devcapsule/configuration/listing.py | 12 ++ .../configuration/manifest_document.py | 10 +- .../configuration/manifest_schemas.py | 18 ++- .../configuration/owner_commands.py | 39 ++++++ .../devcapsule/configuration/sources.py | 125 ++++++++++++++++++ devcapsule-src/tests/test_owner_commands.py | 35 +++++ devcapsule-src/tests/test_sources.py | 102 ++++++++++++++ 7 files changed, 333 insertions(+), 8 deletions(-) create mode 100644 devcapsule-src/devcapsule/configuration/sources.py create mode 100644 devcapsule-src/tests/test_sources.py diff --git a/devcapsule-src/devcapsule/configuration/listing.py b/devcapsule-src/devcapsule/configuration/listing.py index 0d6c75de..39a3af0c 100644 --- a/devcapsule-src/devcapsule/configuration/listing.py +++ b/devcapsule-src/devcapsule/configuration/listing.py @@ -47,6 +47,7 @@ from .file_formats import ProjectConfigurationError, render_toml_scalar, table from .launcher_values import launcher_value_source from .manifest_document import EnvironmentPolicy, Recommendations +from .sources import WrappedSources from .trust import HomeTrust, channels_for from .values import ( LAUNCHER_VALUE_NAMES, @@ -234,6 +235,7 @@ def assess_checkout( rows.extend(_access_rows(manifest, composed_lock if access_lock is None else access_lock, checkout, project, base_display, home, home_path)) rows.extend(_environment_rows(manifest, saved_environment or {}, project)) + rows.extend(_source_rows(manifest)) has_surface = bool(table(composed_lock, "components").get("interactive-surface")) if has_surface: rows.extend(_binding_rows(composed_lock, checkout, project)) @@ -429,6 +431,16 @@ def _access_rows( return rows +def _source_rows(manifest: Mapping[str, Any]) -> list[ListingRow]: + """One row per wrapped source: its Java line, and whether it is the upstream to learn from or a fork to change.""" + rows: list[ListingRow] = [] + for source in WrappedSources.read(manifest).entries: + effective = f"java {source.java}" if source.java is not None else "no toolchain declared" + origin = f"project: fork of {source.upstream}" if source.upstream else "project: upstream, read-only" + rows.append(ListingRow("source", source.path, effective, origin)) + return rows + + def _environment_rows( manifest: Mapping[str, Any], saved: Mapping[str, str | None], project: Path | None, ) -> list[ListingRow]: diff --git a/devcapsule-src/devcapsule/configuration/manifest_document.py b/devcapsule-src/devcapsule/configuration/manifest_document.py index f2e52582..e93a1506 100644 --- a/devcapsule-src/devcapsule/configuration/manifest_document.py +++ b/devcapsule-src/devcapsule/configuration/manifest_document.py @@ -48,11 +48,11 @@ CURRENT_MANIFEST_SCHEMA_VERSION = 2 # Tables in the order an owner reads them: who the project is, what it needs, -# what it asks of the developer, what it recommends, the host access it asks -# for with its reasons, the declared values, the workflow choice. Tables this -# writer does not know precede workflow in sorted order, so a newer owner's -# field is never dropped by an older launcher's edit. -MANIFEST_TABLE_ORDER = ("project", "capabilities", "environment", "recommendations", "host", "configuration", "workflow") +# what it wraps, what it asks of the developer, what it recommends, the host +# access it asks for with its reasons, the declared values, the workflow +# choice. Tables this writer does not know precede workflow in sorted order, +# so a newer owner's field is never dropped by an older launcher's edit. +MANIFEST_TABLE_ORDER = ("project", "capabilities", "sources", "environment", "recommendations", "host", "configuration", "workflow") # An environment variable name as POSIX shells and Docker accept it. ENVIRONMENT_NAME_PATTERN = re.compile(r"^[A-Za-z_][A-Za-z0-9_]*$") diff --git a/devcapsule-src/devcapsule/configuration/manifest_schemas.py b/devcapsule-src/devcapsule/configuration/manifest_schemas.py index fd0f4e47..971f5d62 100644 --- a/devcapsule-src/devcapsule/configuration/manifest_schemas.py +++ b/devcapsule-src/devcapsule/configuration/manifest_schemas.py @@ -46,6 +46,7 @@ from .capabilities import RETIRED_CAPABILITY_FIELD, CapabilityPolicy, names, requirement, resolution_recommendations from .file_formats import ConfigurationFileKind, ProjectConfigurationError, table, validate_file_format from .manifest_document import EnvironmentPolicy, Recommendations, capability_reasons +from .sources import WrappedSources from .values import configuration_value_declarations __all__ = ["ManifestV1", "ManifestV2", "NeedForm", "RequiredForm", "read_manifest", "upgrade"] @@ -54,7 +55,7 @@ # The root keys each schema names; every other root key is an extension. _V1_ROOT = frozenset({VERSION_KEY, "project", "capabilities", "host", "configuration", "workflow", "workflow-type"}) -_V2_ROOT = frozenset({VERSION_KEY, "project", "capabilities", "environment", "recommendations", "host", "configuration", "workflow"}) +_V2_ROOT = frozenset({VERSION_KEY, "project", "capabilities", "sources", "environment", "recommendations", "host", "configuration", "workflow"}) # The keys each schema names under [capabilities]; every other key is an extension. _V1_CAPABILITIES = frozenset({"need", "required", "optional", "resolution", RETIRED_CAPABILITY_FIELD}) _V2_CAPABILITIES = frozenset({"required", "optional", "reasons", "resolution", RETIRED_CAPABILITY_FIELD}) @@ -167,7 +168,7 @@ def read(cls, document: Mapping[str, Any], source: object) -> ManifestV1: validate_file_format(document, ConfigurationFileKind.manifest, source) if document[VERSION_KEY] != cls.version: raise ProjectConfigurationError(f"{source} is not a schema-{cls.version} manifest; it says {document[VERSION_KEY]!r}.") - for word in ("environment", "recommendations"): + for word in ("sources", "environment", "recommendations"): if word in document: raise _refuse(source, f"[{word}]", belongs_to=2, says=1) capabilities = table(document, "capabilities") @@ -237,7 +238,9 @@ class ManifestV2: Required entries allow ``NAME>=VERSION``; optional entries allow only names. :attr:`policy` is their value. ``reasons`` is ``[capabilities.reasons]``, ``resolution`` - the owner's provider choices. ``environment`` is the ``[environment]`` + the owner's provider choices. ``sources`` is the ``[sources]`` table as + written, the wrapped sources of a wrapper project; :attr:`wrapped_sources` + is its value. ``environment`` is the ``[environment]`` table as written, since an entry may carry a newer owner's field beside its reason; :attr:`environment_policy` is its value. ``recommendation_fields`` keeps the original spelling and all reasons; :attr:`recommendations` @@ -252,6 +255,7 @@ class ManifestV2: optional: tuple[str, ...] = () reasons: dict[str, str] = field(default_factory=dict) resolution: dict[str, str] = field(default_factory=dict) + sources: dict[str, Any] = field(default_factory=dict) environment: dict[str, Any] = field(default_factory=dict) recommendation_fields: dict[str, Any] = field(default_factory=dict) host: dict[str, Any] = field(default_factory=dict) @@ -276,6 +280,7 @@ def read(cls, document: Mapping[str, Any], source: object) -> ManifestV2: CapabilityPolicy.read(document) try: reasons = capability_reasons(document) + WrappedSources.read(document) EnvironmentPolicy.read(document) Recommendations.read(document) except ProjectConfigurationError as exc: @@ -288,6 +293,7 @@ def read(cls, document: Mapping[str, Any], source: object) -> ManifestV2: optional=optional, reasons=reasons, resolution=resolution_recommendations(document), + sources=_optional_table(document, "sources", source) or {}, environment=_optional_table(document, "environment", source) or {}, recommendation_fields=_optional_table(document, "recommendations", source) or {}, host=_optional_table(document, "host", source) or {}, @@ -307,6 +313,10 @@ def policy(self) -> CapabilityPolicy: def environment_policy(self) -> EnvironmentPolicy: return EnvironmentPolicy.read({"environment": self.environment}) + @property + def wrapped_sources(self) -> WrappedSources: + return WrappedSources.read({"sources": self.sources}) + @property def recommendations(self) -> Recommendations: return Recommendations.read({"recommendations": self.recommendation_fields}) @@ -323,6 +333,8 @@ def document(self) -> dict[str, Any]: capabilities.update(deepcopy(self.capability_extensions)) capabilities.update(deepcopy(self.retired)) result: dict[str, Any] = {VERSION_KEY: self.version, "project": deepcopy(self.project), "capabilities": capabilities} + if self.sources or ("sources",) in self._present: + result["sources"] = deepcopy(self.sources) if self.environment or ("environment",) in self._present: result["environment"] = deepcopy(self.environment) if self.recommendation_fields or ("recommendations",) in self._present: diff --git a/devcapsule-src/devcapsule/configuration/owner_commands.py b/devcapsule-src/devcapsule/configuration/owner_commands.py index d8e5a85c..41911fb3 100644 --- a/devcapsule-src/devcapsule/configuration/owner_commands.py +++ b/devcapsule-src/devcapsule/configuration/owner_commands.py @@ -36,10 +36,12 @@ capability_table, environment_name, ) +from .sources import WrappedSource, WrappedSources, java_line, source_path from .storage import discover_project, load_toml, require_settled from .values import normalize_memory_size __all__ = [ + "declare_source", "edit_capabilities", "drop_environment", "drop_tools", @@ -392,3 +394,40 @@ def _validate(manifest: dict[str, Any]) -> None: ManifestV2.read(manifest, Path("manifest")) from .authorization import authorization_declarations authorization_declarations(manifest, {}) + + +def declare_source(start: Path, path: str, *, upstream: str | None = None, java: str | None = None, + preview: bool = False) -> str: + """Declare, or redeclare, one wrapped source under ``[sources.""]``; the manifest alone changes. + + ``path`` is the submodule's path in the wrapper. ``upstream`` is the + upstream's URL when the submodule's origin is the developer's fork, else + ``None``. ``java`` is the Java line the source builds with, or ``None`` + when the source does not build with Java. A second declaration of the + same path replaces its known keys and keeps any key this launcher does + not know. The lock is untouched: a source adds no capability by itself; + ``require_tools`` does that, and ``project wrap`` calls both. + """ + root, manifest, _lock, _matrix = _project(start, check_resolutions=False) + path = source_path(path, field_name="source path") + if upstream is not None and (not upstream.strip() or "\x00" in upstream): + raise ProjectConfigurationError("The upstream is the upstream repository's URL; it cannot be blank.") + if java is not None: + java = java_line(java, field_name="java line") + previous = deepcopy(manifest.get("sources", {})) + declared = WrappedSources.read(manifest) + entries = [source for source in declared.entries if source.path != path] + entries.append(WrappedSource(path, upstream, java)) + candidate = WrappedSources(tuple(sorted(entries, key=lambda source: source.path))) + candidate_manifest = deepcopy(manifest) + candidate_manifest["sources"] = candidate.document(previous=previous) + WrappedSources.read(candidate_manifest) + check_documents(candidate_manifest, _lock, check_resolutions=False) + if not preview: + promote(root, candidate_manifest) + verb = "Redeclared" if declared.get(path) is not None else "Declared" + lines = ["Preview; nothing written." if preview else f"{verb} source {path}; the manifest is updated."] + lines.append(f" {path}: " + ("learn from it; the origin is the upstream and nothing is pushed" if upstream is None + else f"change it in your fork of {upstream}; pull requests go to the fork") + + (f"; builds with Java {java}" if java is not None else "")) + return "\n".join(lines) diff --git a/devcapsule-src/devcapsule/configuration/sources.py b/devcapsule-src/devcapsule/configuration/sources.py new file mode 100644 index 00000000..378653e4 --- /dev/null +++ b/devcapsule-src/devcapsule/configuration/sources.py @@ -0,0 +1,125 @@ +"""The wrapped sources a project declares: foreign repositories it holds as submodules. + +A wrapper project (the wrapped-projects work order of 2026-11-02) keeps the +DevCapsule configuration in a small repository of the developer's own and +the foreign code as Git submodules of it. The manifest names each wrapped +source under ``[sources.""]``, keyed by the submodule's path, and holds +only what DevCapsule adds: the origin URL stays in ``.gitmodules``, where Git +keeps it true. + +* ``upstream``, when present, says the submodule's origin is the developer's + fork of that upstream: changes and pull requests go to the origin, the + upstream is read-only. Absent, the origin is the upstream itself and the + intent is to learn; nothing is pushed anywhere. +* ``java`` names the Java line the source builds with, ``"17"``: the + project-level requirement stays the capability, and this key says which + line, because a requirement knows only ``NAME>=VERSION`` and a 25 would + satisfy ``>=17`` while the source's build rejects it. + +This module is pure: it validates and renders the table. Whether a line is +installed in the capsule is the runtime's question, asked at launch. A +launcher older than this field reads the table as an extension and carries +it, which is what R-CONFIG-001 asks of a new declaration. +""" + +from __future__ import annotations + +from dataclasses import dataclass +import posixpath +import re +from typing import Any, Mapping + +from .file_formats import ProjectConfigurationError, table + +__all__ = ["WrappedSource", "WrappedSources", "source_path", "java_line"] + +# The keys this launcher knows in a source entry; others are tolerated and +# carried, so a newer owner's field does not make the manifest unreadable. +SOURCE_KEYS = frozenset({"upstream", "java"}) + +# A Java line is the feature release number, as the vendors name a JDK. +JAVA_LINE_PATTERN = re.compile(r"^[1-9][0-9]*$") + + +def source_path(value: object, *, field_name: str) -> str: + """Validate a submodule path as the manifest keys it: relative, inside the wrapper, in POSIX form.""" + if not isinstance(value, str) or not value or "\x00" in value or "\\" in value: + raise ProjectConfigurationError(f"{field_name}: a source path is a relative POSIX path such as RobotCode2025Public; found {value!r}.") + if value.startswith("/") or value != posixpath.normpath(value) or value == "." or value.split("/")[0] == "..": + raise ProjectConfigurationError(f"{field_name}: a source path stays inside the wrapper and carries no '.' or '..' segments; found {value!r}.") + return value + + +def java_line(value: object, *, field_name: str) -> str: + """Validate a Java line as a feature release number such as ``"17"``.""" + if not isinstance(value, str) or JAVA_LINE_PATTERN.fullmatch(value) is None: + raise ProjectConfigurationError(f"{field_name}: a Java line is the feature release number as a string, such as \"17\"; found {value!r}.") + return value + + +@dataclass(frozen=True) +class WrappedSource: + """One wrapped source as declared: its path, its upstream when the origin is a fork, its Java line.""" + + path: str + upstream: str | None = None + java: str | None = None + + @property + def intent(self) -> str: + """What the developer means to do with the source, in the words the guidance uses.""" + return "change it in your fork; pull requests go to the fork's origin, never to the upstream" if self.upstream else "learn from it; it is read-only, nothing is pushed" + + def document(self) -> dict[str, Any]: + result: dict[str, Any] = {} + if self.upstream is not None: + result["upstream"] = self.upstream + if self.java is not None: + result["java"] = self.java + return result + + +@dataclass(frozen=True) +class WrappedSources: + """The ``[sources]`` table, validated, sorted by path.""" + + entries: tuple[WrappedSource, ...] = () + + @classmethod + def read(cls, manifest: Mapping[str, Any]) -> WrappedSources: + """Read ``[sources.""]`` entries; unknown keys inside an entry are tolerated.""" + sources = table(manifest, "sources") + entries: list[WrappedSource] = [] + for key, entry in sources.items(): + field_name = f"sources.{key}" + path = source_path(key, field_name=field_name) + if not isinstance(entry, dict): + raise ProjectConfigurationError(f"{field_name} must be a table with optional 'upstream' and 'java' keys.") + upstream = entry.get("upstream") + if upstream is not None and (not isinstance(upstream, str) or not upstream.strip() or "\x00" in upstream): + raise ProjectConfigurationError(f"{field_name}.upstream must be the upstream repository's URL.") + java = entry.get("java") + if java is not None: + java = java_line(java, field_name=f"{field_name}.java") + entries.append(WrappedSource(path, upstream, java)) + return cls(tuple(sorted(entries, key=lambda source: source.path))) + + @property + def paths(self) -> tuple[str, ...]: + return tuple(source.path for source in self.entries) + + def get(self, path: str) -> WrappedSource | None: + return next((source for source in self.entries if source.path == path), None) + + def java_lines(self) -> tuple[str, ...]: + """The distinct Java lines the sources name, in order; one line means the capsule can select it for everyone.""" + return tuple(dict.fromkeys(source.java for source in self.entries if source.java is not None)) + + def document(self, *, previous: Mapping[str, Any] | None = None) -> dict[str, Any]: + """The ``[sources]`` table; unknown keys of ``previous`` entries survive an edit.""" + result: dict[str, Any] = {} + for source in self.entries: + carried = previous.get(source.path, {}) if previous else {} + extra = {key: value for key, value in carried.items() if key not in SOURCE_KEYS} if isinstance(carried, dict) else {} + result[source.path] = {**source.document(), **extra} + return result diff --git a/devcapsule-src/tests/test_owner_commands.py b/devcapsule-src/tests/test_owner_commands.py index 704354e7..ed1995d9 100644 --- a/devcapsule-src/tests/test_owner_commands.py +++ b/devcapsule-src/tests/test_owner_commands.py @@ -349,3 +349,38 @@ def test_owner_help_discloses_schema_two_compatibility(capsys, command) -> None: assert cli.main(["project", *command, "--help"]) == 0 help_text = " ".join(capsys.readouterr().out.split()) assert "rc3 and older launchers cannot read" in help_text + + +def test_declare_source_writes_the_table_and_leaves_the_lock_bytes_alone(project: Path, capsys) -> None: + lock_before = paths(project)[1].read_bytes() + assert cli.main(["project", "--path", str(project), "config", "show"]) == 0 + capsys.readouterr() + text = owner_commands.declare_source(project, "RobotCode2025Public", java="17") + assert text.splitlines()[0] == "Declared source RobotCode2025Public; the manifest is updated." + assert "learn from it" in text and "Java 17" in text + manifest = load_toml(paths(project)[0]) + assert manifest["sources"] == {"RobotCode2025Public": {"java": "17"}} + assert paths(project)[1].read_bytes() == lock_before + assert cli.main(["project", "--path", str(project), "config", "show"]) == 0 + assert "source RobotCode2025Public java 17" in capsys.readouterr().out.replace(" ", " ") + + +def test_declare_source_again_replaces_known_keys_and_keeps_unknown_ones(project: Path) -> None: + owner_commands.declare_source(project, "robot", upstream="https://example.test/up", java="17") + manifest_path = paths(project)[0] + manifest_path.write_text(manifest_path.read_text().replace('java = "17"', 'java = "17"\nfuture = "kept"')) + text = owner_commands.declare_source(project, "robot", java="21") + assert text.splitlines()[0] == "Redeclared source robot; the manifest is updated." + assert load_toml(manifest_path)["sources"] == {"robot": {"java": "21", "future": "kept"}} + + +def test_declare_source_preview_and_refusals_write_nothing(project: Path) -> None: + before = manifest_text(project) + assert owner_commands.declare_source(project, "robot", java="17", preview=True).startswith("Preview; nothing written.") + with pytest.raises(ProjectConfigurationError, match="source path"): + owner_commands.declare_source(project, "../robot") + with pytest.raises(ProjectConfigurationError, match="Java line"): + owner_commands.declare_source(project, "robot", java="17.0") + with pytest.raises(ProjectConfigurationError, match="upstream"): + owner_commands.declare_source(project, "robot", upstream=" ") + assert manifest_text(project) == before diff --git a/devcapsule-src/tests/test_sources.py b/devcapsule-src/tests/test_sources.py new file mode 100644 index 00000000..7b73d053 --- /dev/null +++ b/devcapsule-src/tests/test_sources.py @@ -0,0 +1,102 @@ +"""The wrapped sources a manifest declares: the ``[sources]`` table, its validation, its round trip (work order of 2026-11-02).""" + +from __future__ import annotations + +import tomllib + +import pytest + +from devcapsule.configuration.file_formats import ProjectConfigurationError +from devcapsule.configuration.manifest_document import render_manifest +from devcapsule.configuration.manifest_schemas import ManifestV2, read_manifest +from devcapsule.configuration.sources import WrappedSource, WrappedSources, java_line, source_path + +PROJECT = {"name": "FRC learning", "slug": "frc-learning", "creator": "mailto:owner@example.test", "mount": "/workspace/frc-learning"} + + +def manifest(**sources: object) -> dict: + return {"devcapsule-schema-version": 2, "project": dict(PROJECT), "capabilities": {"required": ["java"]}, "sources": sources} + + +def test_sources_are_read_sorted_with_their_keys_and_intent() -> None: + sources = WrappedSources.read(manifest(Second={"upstream": "https://example.test/up", "java": "21"}, RobotCode2025Public={"java": "17"})) + assert sources.paths == ("RobotCode2025Public", "Second") + first, second = sources.entries + assert first == WrappedSource("RobotCode2025Public", None, "17") + assert first.intent.startswith("learn from it") + assert second == WrappedSource("Second", "https://example.test/up", "21") + assert second.intent.startswith("change it in your fork") + assert sources.java_lines() == ("17", "21") + assert sources.get("Second") is second and sources.get("Other") is None + + +def test_an_entry_without_a_java_line_names_no_toolchain() -> None: + sources = WrappedSources.read(manifest(docs={})) + assert sources.entries == (WrappedSource("docs"),) + assert sources.java_lines() == () + assert sources.document() == {"docs": {}} + + +@pytest.mark.parametrize("path", ["", "/abs", "../out", "a/../b", ".", "a//b", "a/", "back\\slash"]) +def test_source_paths_stay_inside_the_wrapper_in_posix_form(path: str) -> None: + with pytest.raises(ProjectConfigurationError, match="source path"): + source_path(path, field_name="source path") + + +def test_nested_paths_are_allowed() -> None: + assert source_path("vendor/robot", field_name="p") == "vendor/robot" + + +@pytest.mark.parametrize("value", ["", "0", "17.0", 17, "jdk-17", "017"]) +def test_a_java_line_is_a_feature_release_number_as_a_string(value: object) -> None: + with pytest.raises(ProjectConfigurationError, match="Java line"): + java_line(value, field_name="sources.x.java") + + +@pytest.mark.parametrize("entry, message", [ + ("17", "must be a table"), + ({"upstream": ""}, "upstream"), + ({"upstream": 3}, "upstream"), + ({"java": 17}, "Java line"), +]) +def test_malformed_entries_are_refused_by_name(entry: object, message: str) -> None: + with pytest.raises(ProjectConfigurationError, match=message): + WrappedSources.read(manifest(robot=entry)) + + +def test_unknown_keys_inside_an_entry_are_tolerated_and_carried_by_the_document() -> None: + document = manifest(robot={"java": "17", "future": {"keep": True}}) + sources = WrappedSources.read(document) + assert sources.entries == (WrappedSource("robot", None, "17"),) + assert sources.document(previous=document["sources"]) == {"robot": {"java": "17", "future": {"keep": True}}} + assert sources.document() == {"robot": {"java": "17"}} + + +def test_schema_two_reads_sources_as_its_own_table_and_renders_it_after_capabilities() -> None: + document = manifest(**{"vendor/robot": {"java": "17"}}) + value = read_manifest(document, "manifest") + assert isinstance(value, ManifestV2) + assert value.sources == {"vendor/robot": {"java": "17"}} + assert value.extensions == {} + assert value.wrapped_sources.entries == (WrappedSource("vendor/robot", None, "17"),) + text = render_manifest(value.document()) + assert text.index("[capabilities]") < text.index('[sources."vendor/robot"]') < text.index("[recommendations]") if "[recommendations]" in text else True + assert 'java = "17"' in text + assert read_manifest(tomllib.loads(text), "rendered") == value + + +def test_schema_two_refuses_a_bad_source_naming_the_file() -> None: + with pytest.raises(ProjectConfigurationError, match=r"manifest: sources\.robot\.java"): + read_manifest(manifest(robot={"java": "seventeen"}), "manifest") + + +def test_schema_one_refuses_the_schema_two_word() -> None: + document = {"devcapsule-schema-version": 1, "project": dict(PROJECT), "capabilities": {"need": ["java"]}, "sources": {"robot": {}}} + with pytest.raises(ProjectConfigurationError, match=r"\[sources\], a schema-2 word"): + read_manifest(document, "manifest") + + +def test_an_explicitly_empty_sources_table_survives_the_round_trip() -> None: + value = read_manifest(manifest(), "manifest") + assert value.document()["sources"] == {} + assert "[sources]" in render_manifest(value.document()) From 97ef942144132ce1adadfb668e0ee571bce4eabf Mon Sep 17 00:00:00 2001 From: Costin Cozianu Date: Mon, 2 Nov 2026 23:51:28 +0000 Subject: [PATCH 07/15] Add project wrap: a foreign repository as a declared submodule 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 --- devcapsule-src/devcapsule/commands/project.py | 88 ++++-- devcapsule-src/devcapsule/wrap.py | 269 ++++++++++++++++++ devcapsule-src/devcapsule/wrap_detection.py | 80 ++++++ devcapsule-src/tests/test_wrap.py | 183 ++++++++++++ devcapsule-src/tests/test_wrap_detection.py | 59 ++++ 5 files changed, 662 insertions(+), 17 deletions(-) create mode 100644 devcapsule-src/devcapsule/wrap.py create mode 100644 devcapsule-src/devcapsule/wrap_detection.py create mode 100644 devcapsule-src/tests/test_wrap.py create mode 100644 devcapsule-src/tests/test_wrap_detection.py diff --git a/devcapsule-src/devcapsule/commands/project.py b/devcapsule-src/devcapsule/commands/project.py index 7810321a..eb7cf97b 100644 --- a/devcapsule-src/devcapsule/commands/project.py +++ b/devcapsule-src/devcapsule/commands/project.py @@ -309,29 +309,13 @@ def configure(cls, parser: argparse.ArgumentParser) -> None: "--offer", action="append", default=[], metavar="CAPABILITY", help="A capability the project offers and a developer may leave out, such as browser-automation. Repeatable.", ) - parser.add_argument("--ide", metavar="IDE", help="Your IDE for this checkout: python-ide, frontend-ide, vscode-ide, java-ide, eclipse-ide or dotnet-ide; component names such as pycharm or vscode also work.") - parser.add_argument("--with", dest="capabilities", action="append", default=[], metavar="CAPABILITY", - help="Add a capability for your checkout. Repeatable.") + _add_owner_options(parser) _retired_option(parser, "--agent", "devcapsule project init --with CAPABILITY") - parser.add_argument("--name", dest="project_name", help="Project display name.") - parser.add_argument("--slug", help="Project identity slug.") - parser.add_argument("--creator", help="Project creator URL or email address.") - parser.add_argument("--project-mount", help="In-container project mount path.") parser.add_argument( "--regenerate", action="store_true", help="Rewrite the derived platform lock from the current embedded matrix; migrate a schema-1 manifest to schema 2, keeping its leading comment block.", ) - parser.add_argument( - "--unverified", - action="store_true", - dest="allow_unverified", - help=( - "If no fully verified combination satisfies the requirements, resolve past " - "the matrix with a gentle warning; the generated lock names every " - "unverified combination." - ), - ) for flag, replacement in (("--need", "init --require CAPABILITY; config ide IDE or config add CAPABILITY"), ("--required", "init --require CAPABILITY"), ("--optional", "init --offer CAPABILITY"), @@ -373,6 +357,75 @@ def run(cls, arguments: argparse.Namespace, context: object | None) -> int: return 0 +def _add_owner_options(parser: argparse.ArgumentParser) -> None: + """The options ``init`` and ``wrap`` share: the owner's own checkout, the project's identity, the matrix escape.""" + parser.add_argument("--ide", metavar="IDE", help="Your IDE for this checkout: python-ide, frontend-ide, vscode-ide, java-ide, eclipse-ide or dotnet-ide; component names such as pycharm or vscode also work.") + parser.add_argument("--with", dest="capabilities", action="append", default=[], metavar="CAPABILITY", + help="Add a capability for your checkout. Repeatable.") + parser.add_argument("--name", dest="project_name", help="Project display name.") + parser.add_argument("--slug", help="Project identity slug.") + parser.add_argument("--creator", help="Project creator URL or email address.") + parser.add_argument("--project-mount", help="In-container project mount path.") + parser.add_argument( + "--unverified", + action="store_true", + dest="allow_unverified", + help=( + "If no fully verified combination satisfies the requirements, resolve past " + "the matrix with a gentle warning; the generated lock names every " + "unverified combination." + ), + ) + + +class ProjectWrapCommand(Command): + name = "wrap" + capsule_access: ClassVar[CapsuleAccess] = CapsuleAccess.CREATES_HERE + help = ( + "Wrap a foreign repository: add it as a submodule with its Git directory embedded, read what it " + "needs, initialize or extend the manifest and lock, declare it under [sources], and write the " + "wrapper's AGENTS.md and README.md. Repeatable for several repositories. Writes schema 2." + ) + + @classmethod + def configure(cls, parser: argparse.ArgumentParser) -> None: + parser.add_argument("url", metavar="URL", help="The repository to wrap: your fork when you mean to change it, the upstream when you mean to learn.") + parser.add_argument("--path", metavar="NAME", help="The submodule's directory in the wrapper; default: the repository's name.") + parser.add_argument("--upstream", metavar="URL", help="The upstream URL when URL is your fork of it; pull requests then go to the fork, never to the upstream.") + _add_owner_options(parser) + add_carrier_options(parser) + + @classmethod + def run(cls, arguments: argparse.Namespace, context: object | None) -> int: + from devcapsule.wrap import WrapRequest, wrap_project + from devcapsule.platforms import Platform + from devcapsule.resolution_matrix import MATRICES + matrix = MATRICES[Platform.current()] + ide = matrix.canonical_name(arguments.ide) if arguments.ide is not None and arguments.ide.strip().lower() != "none" else None + answers = tuple( + ProvidedAnswer(family=answer.family, name=answer.name, value=answer.value, justification=answer.justification) + for answer in carrier_answers(arguments) + ) + report = wrap_project( + WrapRequest( + directory=_project_context(context).target_path(), + url=arguments.url, + path=arguments.path, + upstream=arguments.upstream, + ide=ide, + agents=tuple(arguments.capabilities), + project_name=arguments.project_name, + slug=arguments.slug, + creator=arguments.creator, + project_mount=arguments.project_mount, + answers=answers, + allow_unverified=arguments.allow_unverified, + ) + ) + print(report.render()) + return 0 + + def _init_selection(arguments: argparse.Namespace) -> tuple[tuple[str, ...], tuple[str, ...], str | None, tuple[str, ...]]: """Keep shared declarations separate from the checkout's selections.""" from devcapsule.platforms import Platform @@ -2528,6 +2581,7 @@ def subcommands(cls) -> Mapping[str, type[Command] | type[Group]]: ProjectDiagnoseCommand.name: ProjectDiagnoseCommand, ProjectListCommand.name: ProjectListCommand, ProjectInitCommand.name: ProjectInitCommand, + ProjectWrapCommand.name: ProjectWrapCommand, CheckoutGroup.name: CheckoutGroup, ConfigGroup.name: ConfigGroup, VersionsGroup.name: VersionsGroup, diff --git a/devcapsule-src/devcapsule/wrap.py b/devcapsule-src/devcapsule/wrap.py new file mode 100644 index 00000000..b7e9b146 --- /dev/null +++ b/devcapsule-src/devcapsule/wrap.py @@ -0,0 +1,269 @@ +"""``project wrap``: a foreign repository as a submodule of a wrapper project, declared and explained. + +The wrapped-projects work order of 2026-11-02: a developer gives DevCapsule +a repository that is not theirs and carries no DevCapsule configuration, and +works on it in a capsule without imposing anything on it. The configuration +lives in a small wrapper repository of their own; the foreign code is a Git +submodule of it. ``wrap`` does, in order: + +1. adds the submodule, with its Git directory embedded in the tree the + capsule mounts, so it works inside the capsule on the first run; +2. reads what the source needs (:mod:`wrap_detection`); +3. initializes the manifest and lock as ``init`` would, or extends an + existing manifest with what the source requires; +4. declares the source under ``[sources.""]``; +5. writes the wrapper's ``AGENTS.md`` and ``README.md``, regenerated from the + manifest on every wrap, so an agent and a human each know what is foreign, + under whose control, how to build it and which Java to use. + +A rerun after an interruption finishes what was left: a submodule already +added at the path from the same URL is kept, not refused. +""" + +from __future__ import annotations + +from dataclasses import dataclass +from pathlib import Path +import shutil +import subprocess +from typing import Any, Mapping, TextIO + +from devcapsule.configuration.file_formats import ProjectConfigurationError +from devcapsule.configuration.manifest import current_manifest +from devcapsule.configuration.manifest_document import Recommendations +from devcapsule.configuration.operations import InitializeReport, InitializeRequest, ProvidedAnswer, initialize_project +from devcapsule.configuration.owner_commands import declare_source, recommend, require_tools +from devcapsule.configuration.sources import WrappedSource, WrappedSources, source_path +from devcapsule.configuration.storage import load_toml +from devcapsule.wrap_detection import Detection, detect + +__all__ = ["WrapRequest", "WrapReport", "wrap_project", "GUIDANCE_MARKER", "render_agents", "render_readme"] + +# The first line of every file wrap writes: the one it may rewrite. +GUIDANCE_MARKER = "" + +# Where the capsule's base image keeps each Java line, by the stable name the +# runtime guarantees across base updates (design of 2026-11-02, section 2). +JAVA_HOME_ROOT = "/opt/java" + + +@dataclass(frozen=True) +class WrapRequest: + """Everything ``devcapsule project wrap`` collected from its command line.""" + + directory: Path + url: str + path: str | None = None + upstream: str | None = None + # The owner's own checkout, as for init: never in the manifest. + ide: str | None = None + agents: tuple[str, ...] = () + project_name: str | None = None + slug: str | None = None + creator: str | None = None + project_mount: str | None = None + answers: tuple[ProvidedAnswer, ...] = () + allow_unverified: bool = False + interactive: bool | None = None + + +@dataclass(frozen=True) +class WrapReport: + """What one wrap did, in the order it did it.""" + + path: str + submodule_action: str + detection: Detection | None + initialized: InitializeReport | None + capability_lines: tuple[str, ...] + source_line: str + guidance: tuple[str, ...] + next_steps: tuple[str, ...] + + def render(self) -> str: + lines = [self.submodule_action] + if self.detection is None: + lines.append(f"Detected nothing in {self.path} that these rules know; declare what it needs with " + "'devcapsule project config require CAPABILITY'.") + else: + lines.append(f"Detected in {self.path}: " + "; ".join(self.detection.evidence)) + if self.initialized is not None: + lines.append(self.initialized.render()) + lines.extend(self.capability_lines) + lines.append(self.source_line) + lines.extend(self.guidance) + lines.append("Next: " + " ".join(self.next_steps)) + return "\n".join(lines) + + +def wrap_project(request: WrapRequest, *, input_stream: TextIO | None = None, output_stream: TextIO | None = None) -> WrapReport: + """Wrap one repository into the project at ``request.directory``; see the module docstring for the steps.""" + root = request.directory.expanduser().resolve() + _require_repository_root(root) + path = source_path(request.path or _repository_name(request.url), field_name="--path") + submodule_action = _add_submodule(root, request.url, path) + detection = detect(root / path) + manifest_path = root / ".devcapsule" / "devcapsule.toml" + initialized: InitializeReport | None = None + capability_lines: list[str] = [] + needed = detection.capabilities if detection is not None else () + if not manifest_path.is_file(): + initialized = initialize_project( + InitializeRequest(directory=root, require=needed, ide=request.ide, agents=request.agents, + project_name=request.project_name, slug=request.slug, creator=request.creator, + project_mount=request.project_mount, answers=request.answers, + allow_unverified=request.allow_unverified, interactive=request.interactive), + input_stream=input_stream, output_stream=output_stream, + ) + else: + manifest = current_manifest(load_toml(manifest_path), manifest_path).document() + declared = {name.partition(">=")[0] for name in manifest["capabilities"].get("required", [])} + missing = tuple(name for name in needed if name not in declared) + if missing: + capability_lines.append(require_tools(root, missing, allow_unverified=request.allow_unverified).splitlines()[0]) + manifest = current_manifest(load_toml(manifest_path), manifest_path).document() + if detection is not None and detection.ide is not None and Recommendations.read(manifest).ide is None: + capability_lines.append(recommend(root, "ide", detection.ide).splitlines()[0]) + source_line = declare_source(root, path, upstream=request.upstream, + java=detection.java if detection is not None else None).splitlines()[0] + manifest = current_manifest(load_toml(manifest_path), manifest_path).document() + guidance = _write_guidance(root, manifest) + next_steps = ("Review the changes, commit them (the submodule, .gitmodules, .devcapsule/, AGENTS.md, README.md),", + "then 'devcapsule project run' opens the capsule.") + return WrapReport(path, submodule_action, detection, initialized, tuple(capability_lines), source_line, guidance, next_steps) + + +def _require_repository_root(root: Path) -> None: + completed = _git(root, "rev-parse", "--show-toplevel", check=False) + if completed.returncode != 0: + raise ProjectConfigurationError(f"{root} is not a Git repository; 'git init' there first, then wrap.") + top = Path(completed.stdout.strip()).resolve() + if top != root: + raise ProjectConfigurationError(f"Wrap at the repository's top level, {top}, where the manifest lives; {root} is inside it.") + + +def _repository_name(url: str) -> str: + """The last path segment of a Git URL without ``.git``: ``RobotCode2025Public`` from its GitHub URL.""" + trimmed = url.rstrip("/") + name = trimmed.rsplit("/", 1)[-1].rsplit(":", 1)[-1] + name = name[:-4] if name.endswith(".git") else name + if not name: + raise ProjectConfigurationError(f"Cannot name a directory after {url!r}; give --path NAME.") + return name + + +def _add_submodule(root: Path, url: str, path: str) -> str: + """Add the submodule unless the same one already stands at ``path``; embed its Git directory either way.""" + target = root / path + registered = _git(root, "config", "-f", ".gitmodules", f"submodule.{path}.url", check=False) + if target.exists(): + if registered.returncode == 0 and registered.stdout.strip() == url: + action = f"Kept the submodule {path}, already added from {url}" + else: + raise ProjectConfigurationError(f"{target} exists and is not a submodule added from {url}; give another --path.") + else: + _git(root, "submodule", "add", "--", url, path) + action = f"Added the submodule {path} from {url}" + return action + ("; its Git directory is embedded in the tree." if _embed_git_directory(root, path) else ".") + + +def _embed_git_directory(root: Path, path: str) -> bool: + """Move ``.git/modules/`` into ``/.git`` so the capsule, which mounts the project tree alone, sees it. + + ``git submodule add`` leaves the submodule's Git directory under the + superproject's ``.git`` and a one-line gitfile in the submodule; a bind + mount of the project tree then carries a dangling pointer. Returns + whether a move happened. + """ + gitfile = root / path / ".git" + if gitfile.is_dir(): + return False + git_dir = Path(_git(root, "rev-parse", "--path-format=absolute", "--git-dir").stdout.strip()) + module = git_dir / "modules" / path + if not module.is_dir(): + raise ProjectConfigurationError(f"The submodule's Git directory is neither at {gitfile} nor at {module}; cannot embed it.") + gitfile.unlink() + shutil.move(str(module), str(gitfile)) + # Edit the file, not the repository: ``core.worktree`` still points at the + # old location relative to the old Git directory, and discovery through + # it would fail before the command ran. + _git(root, "config", "--file", str(gitfile / "config"), "--unset", "core.worktree") + return True + + +def _git(cwd: Path, *args: str, check: bool = True) -> subprocess.CompletedProcess[str]: + completed = subprocess.run(["git", "-C", str(cwd), *args], capture_output=True, text=True) + if check and completed.returncode != 0: + raise ProjectConfigurationError(f"git {' '.join(args)} failed: {completed.stderr.strip() or completed.stdout.strip()}") + return completed + + +def _write_guidance(root: Path, manifest: Mapping[str, Any]) -> tuple[str, ...]: + """Write AGENTS.md and README.md from the manifest; a file without the marker is the owner's and is left alone.""" + sources = WrappedSources.read(manifest) + origins = {source.path: _origin(root, source.path) for source in sources.entries} + lines: list[str] = [] + for name, text in (("AGENTS.md", render_agents(manifest, sources, origins)), ("README.md", render_readme(manifest, sources, origins))): + target = root / name + if target.is_file() and not target.read_text(encoding="utf-8").startswith(GUIDANCE_MARKER): + lines.append(f"Kept your {name}; it does not carry the wrap marker. Add the wrapped sources to it yourself.") + continue + target.write_text(text, encoding="utf-8") + lines.append(f"Wrote {name}.") + return tuple(lines) + + +def _origin(root: Path, path: str) -> str: + completed = _git(root, "config", "-f", ".gitmodules", f"submodule.{path}.url", check=False) + return completed.stdout.strip() if completed.returncode == 0 else "(not in .gitmodules)" + + +def _java_lines(source: WrappedSource) -> list[str]: + if source.java is None: + return [] + home = f"{JAVA_HOME_ROOT}/{source.java}" + return [f"- Builds with Java {source.java}. Before any build, test or run in this directory, select it:", + "", " ```bash", f' export JAVA_HOME={home}; export PATH="$JAVA_HOME/bin:$PATH"', " ```"] + + +def render_agents(manifest: Mapping[str, Any], sources: WrappedSources, origins: Mapping[str, str]) -> str: + """The wrapper's AGENTS.md: agent-neutral, regenerated from the manifest.""" + name = manifest["project"]["name"] + lines = [GUIDANCE_MARKER, f"# Agent Instructions: {name}", "", + "This repository is a DevCapsule wrapper. It holds the DevCapsule configuration under", + "`.devcapsule/` and foreign repositories as Git submodules. The code to work on lives in", + "the submodules; the wrapper only sets up the environment around them.", "", + "## Wrapped sources", ""] + for source in sources.entries: + lines.extend([f"### `{source.path}`", "", f"- Origin: {origins.get(source.path, '')}", + f"- Intent: {source.intent}." + (f" Upstream: {source.upstream}." if source.upstream else "")]) + lines.extend(_java_lines(source)) + lines.append("") + lines.extend(["## Rules", "", + "1. Never push to, or open a pull request against, a source whose intent is to learn.", + " A fork's origin takes the changes; its upstream never does, unless its maintainers ask.", + "2. Write nothing inside a wrapped source that is not the change you were asked for: no", + " DevCapsule files, no IDE files, no notes. The wrapper holds the configuration.", + "3. Build, test and run each source with its own tool, from its own directory, with the Java", + " line named above selected first.", + "4. Changes to the wrapper itself (the manifest, these files) are ordinary commits here.", + "5. A fresh clone of this wrapper needs `git submodule update --init` before anything else.", ""]) + return "\n".join(lines) + + +def render_readme(manifest: Mapping[str, Any], sources: WrappedSources, origins: Mapping[str, str]) -> str: + """The wrapper's README.md for a person: what this is and how to start.""" + name = manifest["project"]["name"] + lines = [GUIDANCE_MARKER, f"# {name}", "", + "A DevCapsule wrapper: the development environment for the repositories below, which", + "are not this repository's own code and carry no DevCapsule configuration of their own.", "", + "## Start", "", "```bash", "git clone --recurse-submodules ", + "devcapsule project run", "```", "", + "An existing clone without the submodules: `git submodule update --init`.", "", + "## Wrapped sources", ""] + for source in sources.entries: + lines.extend([f"### `{source.path}`", "", f"- Origin: {origins.get(source.path, '')}", + f"- Intent: {source.intent}." + (f" Upstream: {source.upstream}." if source.upstream else "")]) + lines.extend(_java_lines(source)) + lines.append("") + return "\n".join(lines) diff --git a/devcapsule-src/devcapsule/wrap_detection.py b/devcapsule-src/devcapsule/wrap_detection.py new file mode 100644 index 00000000..c23f1b2c --- /dev/null +++ b/devcapsule-src/devcapsule/wrap_detection.py @@ -0,0 +1,80 @@ +"""What ``project wrap`` reads off a freshly added source to declare its needs. + +The rules are facts about build tools, each with its source beside it, kept +as data so a new WPILib year or Gradle line is a one-line change. Only what +the showcase of the wrapped-projects work order exercises is here: a Gradle +wrapper, with or without WPILib's GradleRIO plugin. Anything else is +reported as undetected, and the developer completes the manifest with the +ordinary ``project config`` commands. + +This module reads files and nothing else: no Git, no network, no writes. +""" + +from __future__ import annotations + +from dataclasses import dataclass +from pathlib import Path +import re + +__all__ = ["Detection", "detect"] + +# WPILib ships and requires one JDK per season: 2025 and 2026 both ship +# JDK 17 (WPILib release notes; GradleRIO's toolchain check refuses others). +# The key is the GradleRIO plugin's year, the first component of its version. +GRADLERIO_JAVA_LINES: dict[str, str] = {"2025": "17", "2026": "17"} + +# Gradle's Java compatibility table (docs.gradle.org/current/userguide/compatibility.html): +# every 8.x and 9.0 run on JDK 17; 9.1 is the first to run on JDK 25. +# A plain Gradle project gets the oldest line its wrapper runs on, which is +# the line most likely to match what the project's authors use. +GRADLE_JAVA_LINES: tuple[tuple[tuple[int, int], str], ...] = (((9, 1), "25"), ((8, 0), "17")) + +_GRADLERIO_PATTERN = re.compile(r'edu\.wpi\.first\.GradleRIO["\')]*\s*version\s*\(?\s*["\'](\d{4})') +_DISTRIBUTION_PATTERN = re.compile(r"gradle-(\d+)\.(\d+)") + + +@dataclass(frozen=True) +class Detection: + """What a source needs, as read off its files. + + ``capabilities`` are the project capabilities every checkout must have; + ``ide`` is the IDE to recommend; ``java`` is the Java line, or ``None`` + when the rules cannot name one; ``evidence`` says what was read. + """ + + capabilities: tuple[str, ...] + ide: str | None + java: str | None + evidence: tuple[str, ...] + + +def detect(source: Path) -> Detection | None: + """Detect the showcase's shapes; ``None`` when none of the rules apply.""" + build_script = next((source / name for name in ("build.gradle", "build.gradle.kts") if (source / name).is_file()), None) + if not (source / "gradlew").is_file() or build_script is None: + return None + evidence = [f"Gradle wrapper and {build_script.name}"] + match = _GRADLERIO_PATTERN.search(build_script.read_text(encoding="utf-8", errors="replace")) + if match is not None: + year = match.group(1) + java = GRADLERIO_JAVA_LINES.get(year) + evidence.append(f"GradleRIO {year}" + (f": WPILib {year} builds with Java {java}" if java else f": no Java line known for WPILib {year}")) + return Detection(("java",), "java-ide", java, tuple(evidence)) + gradle = _gradle_java_line(source) + evidence.append(f"Gradle {gradle[0]}: runs on Java {gradle[1]}" if gradle is not None else "the Gradle version is not in gradle-wrapper.properties") + return Detection(("java",), "java-ide", gradle[1] if gradle is not None else None, tuple(evidence)) + + +def _gradle_java_line(source: Path) -> tuple[str, str] | None: + """The wrapper's Gradle version and the Java line it runs on, from ``gradle-wrapper.properties``.""" + properties = source / "gradle" / "wrapper" / "gradle-wrapper.properties" + if not properties.is_file(): + return None + match = _DISTRIBUTION_PATTERN.search(properties.read_text(encoding="utf-8", errors="replace")) + if match is None: + return None + version = (int(match.group(1)), int(match.group(2))) + for minimum, line in GRADLE_JAVA_LINES: + if version >= minimum: + return f"{version[0]}.{version[1]}", line + return None diff --git a/devcapsule-src/tests/test_wrap.py b/devcapsule-src/tests/test_wrap.py new file mode 100644 index 00000000..34b4198c --- /dev/null +++ b/devcapsule-src/tests/test_wrap.py @@ -0,0 +1,183 @@ +"""``project wrap``: a foreign repository as a submodule, declared, explained, repeatable (work order of 2026-11-02).""" + +from __future__ import annotations + +from pathlib import Path +import subprocess + +import pytest + +from devcapsule import cli +from devcapsule.configuration.file_formats import ProjectConfigurationError +from devcapsule.configuration.storage import load_toml +from devcapsule.wrap import GUIDANCE_MARKER, WrapRequest, wrap_project +from tests.test_wrap_detection import gradle_project + +GRADLERIO = 'plugins {\n id "java"\n id "edu.wpi.first.GradleRIO" version "2025.3.2"\n}\n' + + +def git(cwd: Path, *args: str) -> str: + return subprocess.run(["git", "-C", str(cwd), *args], capture_output=True, text=True, check=True).stdout.strip() + + +@pytest.fixture(autouse=True) +def local_git(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None: + """Isolated homes, and Git allowed to clone from a local path, which it refuses by default since 2.38.1.""" + monkeypatch.setenv("HOME", str(tmp_path / "home")) + monkeypatch.setenv("XDG_CONFIG_HOME", str(tmp_path / "config")) + monkeypatch.setenv("XDG_DATA_HOME", str(tmp_path / "data")) + monkeypatch.setenv("GIT_CONFIG_COUNT", "1") + monkeypatch.setenv("GIT_CONFIG_KEY_0", "protocol.file.allow") + monkeypatch.setenv("GIT_CONFIG_VALUE_0", "always") + + +def upstream(tmp_path: Path, name: str, *, script: str = GRADLERIO) -> str: + """A bare repository holding one commit of a Gradle project, as a URL ``wrap`` can clone.""" + work = gradle_project(tmp_path / "work" / name, script=script) + git(work, "init", "--quiet") + git(work, "-c", "user.name=t", "-c", "user.email=t@example.invalid", "add", "-A") + git(work, "-c", "user.name=t", "-c", "user.email=t@example.invalid", "commit", "--quiet", "-m", "seed") + bare = tmp_path / "remote" / f"{name}.git" + git(tmp_path, "clone", "--quiet", "--bare", str(work), str(bare)) + return str(bare) + + +def wrapper(tmp_path: Path) -> Path: + root = tmp_path / "frc-learning" + root.mkdir() + git(root, "init", "--quiet") + return root + + +def request(root: Path, url: str, **fields) -> WrapRequest: + return WrapRequest(directory=root, url=url, creator="https://github.com/example", interactive=False, **fields) + + +def test_a_first_wrap_builds_the_whole_wrapper(tmp_path: Path) -> None: + url = upstream(tmp_path, "RobotCode2025Public") + root = wrapper(tmp_path) + report = wrap_project(request(root, url)) + text = report.render() + assert text.startswith(f"Added the submodule RobotCode2025Public from {url}; its Git directory is embedded in the tree.") + assert "GradleRIO 2025: WPILib 2025 builds with Java 17" in text + assert report.initialized is not None and report.initialized.required == ("java",) + assert "Recommended ide = java-ide" in text + assert "Declared source RobotCode2025Public; the manifest is updated." in text + assert "Wrote AGENTS.md." in text and "Wrote README.md." in text + manifest = load_toml(root / ".devcapsule" / "devcapsule.toml") + assert manifest["capabilities"] == {"required": ["java"]} + assert manifest["sources"] == {"RobotCode2025Public": {"java": "17"}} + assert manifest["recommendations"] == {"ide": "java-ide"} + assert (root / ".devcapsule" / "devcapsule.linux-amd64.lock").is_file() + # The submodule is registered, staged, and its Git directory lives in the tree the capsule mounts. + assert git(root, "config", "-f", ".gitmodules", "submodule.RobotCode2025Public.url") == url + assert (root / "RobotCode2025Public" / ".git").is_dir() + assert not (root / ".git" / "modules" / "RobotCode2025Public").exists() + assert "worktree" not in (root / "RobotCode2025Public" / ".git" / "config").read_text() + assert git(root / "RobotCode2025Public", "status", "--porcelain") == "" + assert git(root, "status", "--porcelain") == "A .gitmodules\nA RobotCode2025Public\n?? .devcapsule/\n?? AGENTS.md\n?? README.md" + agents = (root / "AGENTS.md").read_text() + assert agents.startswith(GUIDANCE_MARKER + "\n") + assert "### `RobotCode2025Public`" in agents and f"- Origin: {url}" in agents + assert "- Intent: learn from it; it is read-only, nothing is pushed." in agents + assert 'export JAVA_HOME=/opt/java/17; export PATH="$JAVA_HOME/bin:$PATH"' in agents + readme = (root / "README.md").read_text() + assert readme.startswith(GUIDANCE_MARKER + "\n# frc-learning\n") and "git submodule update --init" in readme + + +def test_a_second_wrap_extends_the_manifest_and_regenerates_the_guidance(tmp_path: Path) -> None: + url = upstream(tmp_path, "RobotCode2025Public") + other = upstream(tmp_path, "AdvantageKit", script='plugins { id "java" }\n') + root = wrapper(tmp_path) + wrap_project(request(root, url)) + text = wrap_project(request(root, other, upstream="https://github.com/Mechanical-Advantage/AdvantageKit")).render() + assert "Gradle 8.11: runs on Java 17" in text + assert "Declared source AdvantageKit; the manifest is updated." in text + assert "Requires:" not in text # nothing re-initialized; java was already required + manifest = load_toml(root / ".devcapsule" / "devcapsule.toml") + assert manifest["sources"] == {"AdvantageKit": {"upstream": "https://github.com/Mechanical-Advantage/AdvantageKit", "java": "17"}, + "RobotCode2025Public": {"java": "17"}} + agents = (root / "AGENTS.md").read_text() + assert agents.index("### `AdvantageKit`") < agents.index("### `RobotCode2025Public`") + assert ("- Intent: change it in your fork; pull requests go to the fork's origin, never to the upstream. " + "Upstream: https://github.com/Mechanical-Advantage/AdvantageKit.") in agents + + +def test_a_rerun_keeps_the_submodule_and_redeclares(tmp_path: Path) -> None: + url = upstream(tmp_path, "RobotCode2025Public") + root = wrapper(tmp_path) + wrap_project(request(root, url)) + text = wrap_project(request(root, url)).render() + assert text.startswith(f"Kept the submodule RobotCode2025Public, already added from {url}.") + assert "Redeclared source RobotCode2025Public" in text + assert git(root, "status", "--porcelain").count("RobotCode2025Public") == 1 + + +def test_an_undetected_source_declares_nothing_but_itself(tmp_path: Path) -> None: + work = tmp_path / "work" / "notes" + work.mkdir(parents=True) + (work / "README.md").write_text("notes\n") + git(work, "init", "--quiet") + git(work, "-c", "user.name=t", "-c", "user.email=t@example.invalid", "add", "-A") + git(work, "-c", "user.name=t", "-c", "user.email=t@example.invalid", "commit", "--quiet", "-m", "seed") + root = wrapper(tmp_path) + text = wrap_project(request(root, str(work), path="notes")).render() + assert "Detected nothing in notes that these rules know; declare what it needs with 'devcapsule project config require CAPABILITY'." in text + manifest = load_toml(root / ".devcapsule" / "devcapsule.toml") + assert manifest["capabilities"] == {"required": []} + assert manifest["sources"] == {"notes": {}} + assert "recommendations" not in manifest + assert "- Builds with Java" not in (root / "AGENTS.md").read_text() + + +def test_the_owners_own_guidance_is_kept_and_named(tmp_path: Path) -> None: + url = upstream(tmp_path, "RobotCode2025Public") + root = wrapper(tmp_path) + (root / "AGENTS.md").write_text("# Mine\n") + text = wrap_project(request(root, url)).render() + assert "Kept your AGENTS.md; it does not carry the wrap marker. Add the wrapped sources to it yourself." in text + assert (root / "AGENTS.md").read_text() == "# Mine\n" + assert (root / "README.md").read_text().startswith(GUIDANCE_MARKER) + + +def test_refusals_name_the_remedy_before_anything_changes(tmp_path: Path) -> None: + url = upstream(tmp_path, "RobotCode2025Public") + plain = tmp_path / "plain" + plain.mkdir() + with pytest.raises(ProjectConfigurationError, match="not a Git repository; 'git init' there first"): + wrap_project(request(plain, url)) + root = wrapper(tmp_path) + nested = root / "inside" + nested.mkdir() + with pytest.raises(ProjectConfigurationError, match="Wrap at the repository's top level"): + wrap_project(request(nested, url)) + (root / "RobotCode2025Public").mkdir() + with pytest.raises(ProjectConfigurationError, match="exists and is not a submodule added from"): + wrap_project(request(root, url)) + with pytest.raises(ProjectConfigurationError, match="--path"): + wrap_project(request(root, url, path="../escape")) + assert not (root / ".devcapsule").exists() and not (root / ".gitmodules").exists() + + +@pytest.mark.parametrize("url, name", [ + ("https://github.com/Mechanical-Advantage/RobotCode2025Public", "RobotCode2025Public"), + ("https://github.com/Mechanical-Advantage/RobotCode2025Public.git", "RobotCode2025Public"), + ("git@github.com:ccozianu/devcapsule-sample-frc-learning.git", "devcapsule-sample-frc-learning"), + ("/tmp/remote/robot.git/", "robot"), +]) +def test_the_submodule_is_named_after_the_repository(url: str, name: str) -> None: + from devcapsule.wrap import _repository_name + assert _repository_name(url) == name + + +def test_the_command_line_reaches_the_operation(tmp_path: Path, capsys) -> None: + url = upstream(tmp_path, "RobotCode2025Public") + root = wrapper(tmp_path) + assert cli.main(["project", "--path", str(root), "wrap", url, "--creator", "https://github.com/example", "--ide", "none", + "--upstream", "https://github.com/Mechanical-Advantage/RobotCode2025Public"]) == 0 + out = capsys.readouterr().out + assert "Declared source RobotCode2025Public; the manifest is updated." in out + assert out.rstrip().endswith("then 'devcapsule project run' opens the capsule.") + assert load_toml(root / ".devcapsule" / "devcapsule.toml")["sources"]["RobotCode2025Public"]["upstream"] == "https://github.com/Mechanical-Advantage/RobotCode2025Public" + assert cli.main(["project", "--path", str(root), "config", "show"]) == 0 + assert "source RobotCode2025Public java 17" in capsys.readouterr().out diff --git a/devcapsule-src/tests/test_wrap_detection.py b/devcapsule-src/tests/test_wrap_detection.py new file mode 100644 index 00000000..2c97f1f8 --- /dev/null +++ b/devcapsule-src/tests/test_wrap_detection.py @@ -0,0 +1,59 @@ +"""What ``project wrap`` reads off a source: the showcase's Gradle shapes, as data with their sources.""" + +from __future__ import annotations + +from pathlib import Path + +import pytest + +from devcapsule.wrap_detection import Detection, detect + + +def gradle_project(root: Path, *, script: str = 'plugins {\n id "java"\n}\n', distribution: str | None = "8.11", kts: bool = False) -> Path: + root.mkdir(parents=True, exist_ok=True) + (root / "gradlew").write_text("#!/bin/sh\n") + (root / ("build.gradle.kts" if kts else "build.gradle")).write_text(script) + if distribution is not None: + (root / "gradle" / "wrapper").mkdir(parents=True) + (root / "gradle" / "wrapper" / "gradle-wrapper.properties").write_text( + f"distributionUrl=https\\://services.gradle.org/distributions/gradle-{distribution}-bin.zip\n") + return root + + +@pytest.mark.parametrize("year, line", [("2025", "17"), ("2026", "17")]) +def test_gradlerio_names_the_java_line_of_its_wpilib_year(tmp_path: Path, year: str, line: str) -> None: + source = gradle_project(tmp_path / "robot", script=f'plugins {{\n id "edu.wpi.first.GradleRIO" version "{year}.3.2"\n}}\n') + assert detect(source) == Detection(("java",), "java-ide", line, + ("Gradle wrapper and build.gradle", f"GradleRIO {year}: WPILib {year} builds with Java {line}")) + + +def test_gradlerio_in_a_kotlin_script_is_read_too(tmp_path: Path) -> None: + source = gradle_project(tmp_path / "robot", script='plugins {\n id("edu.wpi.first.GradleRIO") version "2026.1.1"\n}\n', kts=True) + detection = detect(source) + assert detection is not None and detection.java == "17" and detection.evidence[0] == "Gradle wrapper and build.gradle.kts" + + +def test_an_unknown_wpilib_year_requires_java_but_names_no_line(tmp_path: Path) -> None: + source = gradle_project(tmp_path / "robot", script='plugins { id "edu.wpi.first.GradleRIO" version "2031.1.1" }\n') + assert detect(source) == Detection(("java",), "java-ide", None, + ("Gradle wrapper and build.gradle", "GradleRIO 2031: no Java line known for WPILib 2031")) + + +@pytest.mark.parametrize("distribution, line", [("8.11", "17"), ("8.0", "17"), ("9.0", "17"), ("9.1", "25"), ("10.2", "25")]) +def test_plain_gradle_gets_the_oldest_line_its_wrapper_runs_on(tmp_path: Path, distribution: str, line: str) -> None: + source = gradle_project(tmp_path / "lib", distribution=distribution) + assert detect(source) == Detection(("java",), "java-ide", line, + ("Gradle wrapper and build.gradle", f"Gradle {distribution}: runs on Java {line}")) + + +def test_a_gradle_wrapper_without_a_readable_version_names_no_line(tmp_path: Path) -> None: + source = gradle_project(tmp_path / "lib", distribution=None) + assert detect(source) == Detection(("java",), "java-ide", None, + ("Gradle wrapper and build.gradle", "the Gradle version is not in gradle-wrapper.properties")) + + +def test_anything_else_is_undetected(tmp_path: Path) -> None: + (tmp_path / "pyproject.toml").write_text("[project]\nname = 'x'\n") + assert detect(tmp_path) is None + (tmp_path / "gradlew").write_text("") # a wrapper without a build script says nothing + assert detect(tmp_path) is None From 9af1fd12285a71010da97eeb019ca3d7e083ce7a Mon Sep 17 00:00:00 2001 From: Costin Cozianu Date: Mon, 2 Nov 2026 23:51:28 +0000 Subject: [PATCH 08/15] Document wrapped projects: the user page, the CLI reference, R-WRAP-001 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 --- REQUIREMENTS.md | 1 + docs/reference/cli.md | 25 +++++++ docs/your-project/existing-repository.md | 3 + docs/your-project/someone-elses-repository.md | 66 +++++++++++++++++++ ...1-conservative-writers-tolerant-readers.md | 12 ++++ .../product/r-wrap-001-wrapped-projects.md | 57 ++++++++++++++++ index.md | 3 +- 7 files changed, 166 insertions(+), 1 deletion(-) create mode 100644 docs/your-project/someone-elses-repository.md create mode 100644 engineering-docs/requirements/product/r-wrap-001-wrapped-projects.md diff --git a/REQUIREMENTS.md b/REQUIREMENTS.md index bff33be9..4c3ded67 100644 --- a/REQUIREMENTS.md +++ b/REQUIREMENTS.md @@ -86,6 +86,7 @@ Current release/stabilization reality: ### Developer Experience And Persistence - `R-CONFIG-001` — [Conservative Configuration Writers And Tolerant Readers](engineering-docs/requirements/product/r-config-001-conservative-writers-tolerant-readers.md) — accepted for 0.3 planning; mandatory/optional needs, command-owned writes and graceful degradation; one explicit per-launch exception for a required IDE (D-0016, 2026-10-28). +- `R-WRAP-001` — [Wrapped Projects](engineering-docs/requirements/product/r-wrap-001-wrapped-projects.md) — accepted 2026-11-02 with the wrapped-projects work order; a foreign repository as a submodule of a wrapper project, `project wrap`, a clean foreign tree, the toolchain reaching the build. - `R-CONSOLE-001` — [Every Capsule Serves A Web Console](engineering-docs/requirements/product/r-console-001-capsule-web-console.md) — proposed and accepted 2026-10-09 by `capsule-webconsole` in its first integration; token-gated loopback console in the base image showing configuration, versions, info and live resources. - `R-UPGRADE-001` — [Local Component Upgrades And Recoverable Version Sets](engineering-docs/requirements/product/r-upgrade-001-component-version-sets.md) diff --git a/docs/reference/cli.md b/docs/reference/cli.md index 6fe0656d..8cb8c455 100644 --- a/docs/reference/cli.md +++ b/docs/reference/cli.md @@ -39,6 +39,7 @@ home instead and disables this fallback to launcher settings. | Command | Intent | |---|---| | `init` | Create the project manifest and platform lock, record your checkout's IDE and capabilities, and resolve when an IDE is chosen. | +| `wrap` | Add a foreign repository as a submodule, read what it needs, create or extend the manifest and lock, declare it as a wrapped source, and write the wrapper's `AGENTS.md` and `README.md`. | | `run` | Derive the launch plan from the project, this home, and this checkout, ask any open questions, and start the capsule. | | `config` | Inspect what the next launch uses, change checkout choices or the shared project contract, and validate without launching. | | `info` | Show selected software, container environment, and persistent storage paths without changing state. | @@ -71,6 +72,30 @@ IDE is selected, `init` can ask for base or vendor consent; non-interactive scripts can pass `--authorize NAME VALUE`. `--set`, `--bind`, and `--authorize` also accept one optional justification argument after the value. +### `wrap` + +```text +devcapsule project wrap URL [--path NAME] [--upstream URL] [--ide IDE] [--with CAPABILITY]... + [--name NAME] [--slug SLUG] [--creator CREATOR] [--project-mount PATH] + [--unverified] [--set NAME VALUE]... [--authorize NAME VALUE]... [--bind NAME VALUE]... +``` + +Run it at the top level of a Git repository, the wrapper. `wrap` adds `URL` +as a submodule at `--path` (default: the repository's name) with its Git +directory embedded in the tree, reads what the source needs, and declares it +under `[sources."NAME"]` in `.devcapsule/devcapsule.toml`. Without a manifest +it initializes one as `init` would, with the detected requirements; with one +it adds what is missing. A Gradle wrapper means `java` is required and +`java-ide` recommended; WPILib's GradleRIO names the Java line its season +builds with, `java = "17"`. It then writes `AGENTS.md` and `README.md` from +the manifest, regenerated on every wrap and left alone when they are yours. + +`--upstream` says `URL` is your fork of that upstream: changes and pull +requests go to the fork, never to the upstream. Without it the origin is the +upstream itself and the intent is to learn; nothing is pushed. A rerun keeps +a submodule already added from the same URL. The owner options are `init`'s. +See [Someone else's repository](../your-project/someone-elses-repository.md). + ### `run` ```text diff --git a/docs/your-project/existing-repository.md b/docs/your-project/existing-repository.md index 44858c77..fabbbcb2 100644 --- a/docs/your-project/existing-repository.md +++ b/docs/your-project/existing-repository.md @@ -90,5 +90,8 @@ authorizations, channel trust, private environment variables, agent sign-ins, and IDE state stay in your local DevCapsule home outside the repository; see [Project versus personal](../configuration/project-versus-personal.md). +A repository that is not yours to configure is wrapped instead; see +[Someone else's repository](someone-elses-repository.md). + **Next: [choose a coding agent](../working-with-ai/choose-an-agent.md) or [declare project needs](declare-needs.md).** diff --git a/docs/your-project/someone-elses-repository.md b/docs/your-project/someone-elses-repository.md new file mode 100644 index 00000000..27db99e6 --- /dev/null +++ b/docs/your-project/someone-elses-repository.md @@ -0,0 +1,66 @@ +--- +description: Work on a repository that is not yours, and carries no DevCapsule configuration, by wrapping it as a submodule of a small project of your own. +weight: 3 +updated: 2026-11-02 +--- +# Someone else's repository + +A project you want to read, build or debug is not yours to configure: an +open-source project with an afternoon of setup instructions, or a robotics +team's public code you want to learn from. Do not send them a pull request +with a DevCapsule configuration. Wrap the repository instead: a small +repository of your own holds the configuration, and theirs is a Git submodule +of it. Nothing is written into their tree. + +```bash +mkdir frc-learning && cd frc-learning && git init +~/.local/bin/devcapsule project wrap https://github.com/Mechanical-Advantage/RobotCode2025Public +~/.local/bin/devcapsule project run +``` + +`wrap` adds the submodule, reads what the code needs, writes the manifest and +the lock, and writes an `AGENTS.md` and a `README.md` that say what is foreign, +how to build it and which Java to use. `run` opens the capsule with the IDE on +the wrapper; the code is in the submodule. Commit what `wrap` produced; anyone +who clones the wrapper with its submodules starts with `devcapsule project run`. + +## What `wrap` reads off the code + +| Found in the repository | Declared | +|---|---| +| A Gradle wrapper with WPILib's GradleRIO plugin | `java` required, `java-ide` recommended, the Java line of that WPILib season: 17 for 2025 and 2026 | +| A Gradle wrapper without it | `java` required, `java-ide` recommended, the oldest Java line that Gradle version runs on | +| Anything else | Nothing; `wrap` says so and names `project config require` | + +The Java line matters because a build such as GradleRIO's refuses any other +JDK. The capsule's base carries more than one; the `AGENTS.md` names the line +to select before building in that directory, and the capsule selects it for +the whole session when every wrapped source agrees. + +## Learning or changing + +`wrap URL` with the upstream's URL means you intend to learn: the submodule +is read-only in intent, and nothing is pushed. `wrap URL --upstream UPSTREAM` +means `URL` is your fork of `UPSTREAM`: your changes and pull requests go to +the fork, and the upstream is never written to unless its maintainers ask. +The `AGENTS.md` carries the same rule for the agent. + +## Several repositories + +Run `wrap` once per repository. The second run extends the manifest and +regenerates the two files. `--path NAME` picks the directory when the +repository's name will not do. A run interrupted by a network failure is +finished by running it again: a submodule already added from the same URL is +kept. + +## What `wrap` does not do + +It does not install the project workflow; `project bootstrap` remains +available. It does not run the foreign project's build, tests or setup; those +run inside the capsule, from the submodule's directory, with its own tools. +It does not add the project's dependencies to the lock; the Gradle cache +lives in the capsule's persistent home, so the first build's downloads are +paid once per checkout. + +**Next: [choose a coding agent](../working-with-ai/choose-an-agent.md) or +[declare project needs](declare-needs.md).** diff --git a/engineering-docs/requirements/product/r-config-001-conservative-writers-tolerant-readers.md b/engineering-docs/requirements/product/r-config-001-conservative-writers-tolerant-readers.md index 7ab4206d..3b67b184 100644 --- a/engineering-docs/requirements/product/r-config-001-conservative-writers-tolerant-readers.md +++ b/engineering-docs/requirements/product/r-config-001-conservative-writers-tolerant-readers.md @@ -57,6 +57,18 @@ silently reduce the project's mandatory needs. A more capable collaborator can still use the enhancement from the same shared project. Tolerant reading does not authorize ignoring constraints needed for integrity or host-access boundaries. +### Wrapped sources are an optional table + +A wrapper project declares the foreign repositories it holds as submodules +under `[sources.""]`, one entry per submodule path, with `upstream` +(the upstream URL when the origin is the developer's fork) and a toolchain +key named after the capability it refines (`java = "17"`, the Java line the +source builds with). The declaration adds no capability by itself; the +capability stays in `[capabilities]`. A launcher without this field reads the +table as an unknown root table, carries it through its own writes, and runs +the capsule without the toolchain selection; a launcher with it validates the +entries and reports them. See R-WRAP-001. + ### One explicit launch exception: the required IDE Owner decision, 2026-10-28, [D-0016](../../decisions/product/d-0016-explicit-launch-departure-from-a-required-ide.md): diff --git a/engineering-docs/requirements/product/r-wrap-001-wrapped-projects.md b/engineering-docs/requirements/product/r-wrap-001-wrapped-projects.md new file mode 100644 index 00000000..df1558ef --- /dev/null +++ b/engineering-docs/requirements/product/r-wrap-001-wrapped-projects.md @@ -0,0 +1,57 @@ +--- +id: R-WRAP-001 +title: Wrapped Projects +type: requirement +kind: concrete-requirement +status: accepted +priority: wanted +source_of_truth: repo +verification: [tests, manual] +external_refs: [] +--- + +# R-WRAP-001: Wrapped Projects + +## Statement + +Owner direction, 2026-11-02, from the wrapped-projects work order. A +developer can work in a capsule on a repository that is not theirs and +carries no DevCapsule configuration, without imposing anything on it: the +configuration lives in a small wrapper repository of their own, and the +foreign repository is a Git submodule of it. + +### The wrapper is an ordinary project + +There is no new project kind. The wrapper's manifest is a schema-2 manifest +that additionally names its wrapped sources under `[sources.""]` +(R-CONFIG-001). Every command that works on a project works on a wrapper. + +### One command wraps a repository + +`devcapsule project wrap URL` adds the repository as a submodule with its Git +directory embedded in the tree the capsule mounts, reads what the source +needs, initializes or extends the manifest and lock, declares the source, and +writes the wrapper's `AGENTS.md` and `README.md` from the manifest. The +developer writes no TOML. The command is repeatable for several repositories +and finishes what an interrupted run left. + +### The foreign tree stays clean + +Nothing is written inside a wrapped source: no DevCapsule files, no IDE +files, no toolchain selection files. The guidance names the toolchain to +select; the capsule selects it. The intent recorded for each source, learning +from the upstream or changing a fork, governs where changes and pull requests +go; the upstream is never written to unless its maintainers ask. + +### The toolchain reaches the build + +A wrapped source names the Java line it builds with. The capsule's base +carries the lines the catalog lists; the selection reaches the agent through +the wrapper's guidance first and the capsule's session environment second. + +## Verification + +Unit tests over the declaration, the detection rules and the wrap operation +with local repositories; the acceptance evidence of the work order on the +showcase, an FRC learning wrapper around Mechanical-Advantage's public robot +code, inside a capsule whose base carries Java 17. diff --git a/index.md b/index.md index d52fa3aa..5698399e 100644 --- a/index.md +++ b/index.md @@ -22,7 +22,7 @@ status file; internal WIP/archive documents use the local index in that status. - [This project's local workflow: the reasons, for humans](WORKFLOW-LOCAL-humane.md) - [Product documentation](docs/README.md), versioned per release under the content–website contract; pages marked *coming soon* are planned stubs - Getting started: [Install](docs/getting-started/install.md), [Your first session](docs/getting-started/first-session.md), [Stop and come back](docs/getting-started/stop-and-come-back.md) - - Your project: [An existing repository](docs/your-project/existing-repository.md), [A new project](docs/your-project/new-project.md), [What a project declares](docs/your-project/declare-needs.md) (coming soon), [Services and ports](docs/your-project/services-and-ports.md) (coming soon) + - Your project: [An existing repository](docs/your-project/existing-repository.md), [A new project](docs/your-project/new-project.md), [Someone else's repository](docs/your-project/someone-elses-repository.md), [What a project declares](docs/your-project/declare-needs.md) (coming soon), [Services and ports](docs/your-project/services-and-ports.md) (coming soon) - Working with AI: [Choose an agent](docs/working-with-ai/choose-an-agent.md), [Sign in and defaults](docs/working-with-ai/sign-in-and-defaults.md), [Instructions for agents](docs/working-with-ai/instructions-for-agents.md), [Hosted and local models](docs/working-with-ai/hosted-and-local-models.md) (coming soon), [Review and change agents](docs/working-with-ai/review-and-change-agents.md) (coming soon) - Everyday development: [Clipboard, keys and browser](docs/everyday-development/clipboard-and-browser.md); coming soon: [IDEs and terminals](docs/everyday-development/ides-and-terminals.md), [Git](docs/everyday-development/git.md), [Run, debug, test](docs/everyday-development/run-debug-test.md), [Previews and ports](docs/everyday-development/previews-and-ports.md) - [Configuration](docs/configuration/index.md) @@ -75,6 +75,7 @@ status file; internal WIP/archive documents use the local index in that status. ## Root Requirement Records - [Conservative configuration writers and tolerant readers](engineering-docs/requirements/product/r-config-001-conservative-writers-tolerant-readers.md) — R-CONFIG-001, accepted 0.3 direction. +- [R-WRAP-001 Wrapped projects](engineering-docs/requirements/product/r-wrap-001-wrapped-projects.md) - [R-CONSOLE-001 Every capsule serves a web console](engineering-docs/requirements/product/r-console-001-capsule-web-console.md) - [R-UPGRADE-001 Local Component Upgrades And Recoverable Version Sets](engineering-docs/requirements/product/r-upgrade-001-component-version-sets.md) - [R-UPGRADE-002 Component Status Operational Reliability](engineering-docs/requirements/product/r-upgrade-002-status-operational-reliability.md) From 48e3e4b1b5e612be89f60c6c5d06151d52295d5b Mon Sep 17 00:00:00 2001 From: Costin Cozianu Date: Mon, 2 Nov 2026 23:53:36 +0000 Subject: [PATCH 09/15] Record slice 1 as PR1 and brief the Codex review Co-Authored-By: Claude Fable 5.1 --- CURRENT-STATUS.md | 2 +- .../CURRENT-STATUS.md | 49 ++++++- .../evidence/2026-11-02-pr1-brief-codex.md | 121 ++++++++++++++++++ 3 files changed, 164 insertions(+), 8 deletions(-) create mode 100644 engineering-docs/wip/2026-11-02-wrapped-projects/evidence/2026-11-02-pr1-brief-codex.md diff --git a/CURRENT-STATUS.md b/CURRENT-STATUS.md index 6ed34938..d6b7f9da 100644 --- a/CURRENT-STATUS.md +++ b/CURRENT-STATUS.md @@ -19,7 +19,7 @@ coordination branch. Detailed state belongs in each linked status file. | `user-docs` | 2026-09-12 | Deliver V1 adopter documentation from first useful session through resuming work | paused 2026-09-28; 0.2.15 documentation merged in PR #151 and on docs-0.2.15; improvement list awaits the owner's decision | `ws-user-docs/first-session` | [workstream status](engineering-docs/wip/2026-09-12-user-docs/CURRENT-STATUS.md) | | `website` | 2026-09-16 | Deliver the website autonomy experiment: repository-owned landing/docs/blog content, independently developable website submodule, local preview and publishing mechanism | paused 2026-09-30; producer migration merged in PR #152 and the versioned documentation live; W04-C, W09-C, W11-C retained | `ws-website/contract-v1` | [workstream status](engineering-docs/wip/2026-09-16-website/CURRENT-STATUS.md) | | `capsule-webconsole` | 2026-10-09 | Serve a token-gated web console from every capsule: configuration, versions, info, live resources, later records and workflow state | active; work order accepted 2026-10-09; the first iteration, deliverables 1 and 2, is three stacked pull requests, #184, #186 and the runtime-and-base slice, each reviewed by the Codex pair; the owner merges | `ws-capsule-webconsole/first-slice` | [workstream status](engineering-docs/wip/2026-10-09-capsule-webconsole/CURRENT-STATUS.md) | -| `wrapped-projects` | 2026-11-02 | Wrap a foreign repository as a submodule of a small wrapper project and work on it in a capsule with three commands; FRC learning project first | active; opened 2026-11-02; design note and JDK experiment done; the owner's first ruling pending | `ws-wrapped-projects/wrap` | [workstream status](engineering-docs/wip/2026-11-02-wrapped-projects/CURRENT-STATUS.md) | +| `wrapped-projects` | 2026-11-02 | Wrap a foreign repository as a submodule of a small wrapper project and work on it in a capsule with three commands; FRC learning project first | active; slice 1 delivered as PR1 (#333) 2026-11-02; Codex review in progress | `ws-wrapped-projects/wrap` | [workstream status](engineering-docs/wip/2026-11-02-wrapped-projects/CURRENT-STATUS.md) | | `website` | 2026-09-16 | Deliver the website autonomy experiment: repository-owned landing/docs/blog content, independently developable website submodule, local preview and publishing mechanism | paused 2026-09-20 at owner request to switch to maintenance; experiment accepted, A−; blog integrated and published; content/parent-integration follow-ups remain | `ws-website/initial-cut`; renamed from `website/initial-cut`; preparation and backlog-handoff exceptions in status | [workstream status](engineering-docs/wip/2026-09-16-website/CURRENT-STATUS.md) | Paused and blocked workstreams remain open until they conclude successfully or diff --git a/engineering-docs/wip/2026-11-02-wrapped-projects/CURRENT-STATUS.md b/engineering-docs/wip/2026-11-02-wrapped-projects/CURRENT-STATUS.md index 4b70f55b..b088243d 100644 --- a/engineering-docs/wip/2026-11-02-wrapped-projects/CURRENT-STATUS.md +++ b/engineering-docs/wip/2026-11-02-wrapped-projects/CURRENT-STATUS.md @@ -4,7 +4,7 @@ Mnemonic: `wrapped-projects` Start date: 2026-11-02 -State: active; opened 2026-11-02; design note and JDK experiment done; waiting for the owner's ruling at the first stopping point +State: active; slice 1 delivered as PR1 (#333) on 2026-11-02; its Codex review (PR1.1) in progress Definition read: WORKFLOW.md@d2ccbbe43dfa, WORKFLOW-LOCAL.md@65501b3407db @@ -47,13 +47,47 @@ The work order records the rulings. Preparation evidence from inside the 0.3.0 c `git@github.com:ccozianu/devcapsule-sample-frc-learning.git` for the showcase wrapper. The wrapper the three commands produce is pushed there; the work order records it. +**2026-11-02, the owner's ruling and slice 1.** The owner read the design and said to run +with it in this capsule; the recommendations of the design note are taken as decided, and +the release target is the next minor after 0.3.0 until the owner names it. Slice 1 is +PR1, [#333](https://github.com/ccozianu/devcapsule/pull/333), against `main`: the +`[sources]` declaration, `declare_source`, `project wrap` with its detection and guidance +files, the `config show` rows, the user page, the CLI reference, R-WRAP-001 and the +R-CONFIG-001 section. The Codex + gpt-6-astra pair reviews it as PR1.1 from +`ws-wrapped-projects/wrap-review` in `~/worktrees/wrapped-projects-review`; the brief is +[evidence/2026-11-02-pr1-brief-codex.md](evidence/2026-11-02-pr1-brief-codex.md). + +### Slice 1, judgments + +1. The manifest holds only what DevCapsule adds to a source: `upstream` and `java`. The + origin URL stays in `.gitmodules`. +2. `upstream` present means a fork to change; absent means the upstream to learn from. +3. The toolchain key is per source and named after the capability (`java = "17"`). +4. `wrap` writes nothing inside the submodule and does not install the workflow. +5. Guidance files with the wrap marker are regenerated on every wrap; the owner's own are + kept and named in the report. +6. The IDE recommendation is added only when the manifest recommends none. +7. Detection covers the showcase only: Gradle, with or without GradleRIO. +8. The submodule's Git directory is embedded by moving `.git/modules/` and editing + `core.worktree` out of the file, not through repository discovery, which fails on the + moved directory. + +Validation of PR1 in this capsule: `nox -s typecheck` passes over 271 files; the new +tests, 100 in `test_sources.py`, `test_wrap_detection.py`, `test_wrap.py` and +`test_owner_commands.py`, pass; the full `nox -s tests` run is recorded on the PR when it +completes. Three pre-existing failures in `test_capability_commands_v2.py` +(`test_resolution_grants_no_consent_and_no_partial_save`) fail in this capsule with the +slice stashed as well as applied; disclosed on the PR, not fixed here. + ## Next Resumable Task -1. Done: the Temurin 17 result is above. -2. Done: wrote `2026-11-02-design-wrapped-source.md`: the manifest shape, the JDK selection - mechanism, the IDE opening rule, the detection rules for the showcase. Stop there for the - owner's reading in the IDE; this is the first stopping point of the work order. -3. After the ruling: slice 1, the declaration and `project wrap`, as PR1 with its Codex review. +1. Run the Codex review of PR1 (#333): read PR1.1's diff, post the assessment, merge or push + back, at most three rounds; then the full gate on PR1's branch, the counts on the PR, and + hand PR1 to the owner. +2. Push the showcase wrapper, produced by the three commands against + RobotCode2025Public, to `git@github.com:ccozianu/devcapsule-sample-frc-learning.git`. +3. Slice 2, after the owner's go at the second stopping point: Temurin 17 in the base under + the stable names, the session environment, the IntelliJ link, the acceptance run. ## Open Threads @@ -67,5 +101,6 @@ wrapper the three commands produce is pushed there; the work order records it. ## Document Index - [the work order](../../work-orders/2026-11-02-wrapped-projects.md): read first. -- [the wrapped-source design](2026-11-02-design-wrapped-source.md): the manifest shape, the JDK mechanism, the IDE rule, the detection rules; open for the first stopping point. +- [the wrapped-source design](2026-11-02-design-wrapped-source.md): the manifest shape, the JDK mechanism, the IDE rule, the detection rules; ruled 2026-11-02. +- [evidence/2026-11-02-pr1-brief-codex.md](evidence/2026-11-02-pr1-brief-codex.md): the review brief of PR1; open when reading PR1.1. - `intake/` and `intake-dispositions.md`: the queue and its log; empty at opening. diff --git a/engineering-docs/wip/2026-11-02-wrapped-projects/evidence/2026-11-02-pr1-brief-codex.md b/engineering-docs/wip/2026-11-02-wrapped-projects/evidence/2026-11-02-pr1-brief-codex.md new file mode 100644 index 00000000..d69e1cdd --- /dev/null +++ b/engineering-docs/wip/2026-11-02-wrapped-projects/evidence/2026-11-02-pr1-brief-codex.md @@ -0,0 +1,121 @@ +# Review brief for the Codex + gpt-6-astra pair: PR1.1 on the sources declaration and project wrap + +The Claude Code + Fable 5.1 pair opened PR1, #333, "Wrapped projects, slice 1: the sources +declaration and project wrap (PR1)", branch `ws-wrapped-projects/wrap`, base `main`. It is +the first slice of the wrapped-projects workstream; no earlier review of this series exists. +Your job is one improvement pull request against that branch. + +## Your checkout + +You are in the git worktree at `/home/devcapsule/worktrees/wrapped-projects-review`, on the +branch `ws-wrapped-projects/wrap-review`, branched from `ws-wrapped-projects/wrap`. Work only +there. Do not touch the main checkout at `/workspace/301e4208ef81-ChatGPT_Codex`. + +Read first, in this order: `AGENTS.md`, `WORKFLOW.md`, `WORKFLOW-LOCAL.md`, +`engineering-docs/work-orders/2026-11-02-wrapped-projects.md`, +`engineering-docs/wip/2026-11-02-wrapped-projects/CURRENT-STATUS.md` (the section +*Slice 1, judgments*), `engineering-docs/wip/2026-11-02-wrapped-projects/2026-11-02-design-wrapped-source.md`, +then the module docstrings of `devcapsule-src/devcapsule/configuration/sources.py` and +`devcapsule-src/devcapsule/wrap.py`, which are the contract. + +## GitHub CLI + +In every shell you run, first execute: + + . /opt/xtras/miniconda3/etc/profile.d/conda.sh && conda activate gh + +Then `gh` is logged in to github.com as the owner's account against `ccozianu/devcapsule`. +Do not edit `.bashrc` or any shell profile. + +## Validation environment + +Your worktree's `devcapsule-src/.venv` exists. Run unit tests and mypy from `devcapsule-src` +with `PYTEST_ADDOPTS="--basetemp=/opt/devcapsule-gate/pytest-codex -p no:cacheprovider"`. +This PR touches, under `devcapsule-src/devcapsule/`: `configuration/sources.py` (new), +`configuration/manifest_schemas.py`, `configuration/manifest_document.py`, +`configuration/owner_commands.py`, `configuration/listing.py`, `wrap.py` (new), +`wrap_detection.py` (new), `commands/project.py`; under `devcapsule-src/tests/`: +`test_sources.py` (new), `test_wrap.py` (new), `test_wrap_detection.py` (new), +`test_owner_commands.py`; and documentation under `docs/`, `engineering-docs/requirements/`, +`REQUIREMENTS.md`, `index.md`. The gate type-checks `tests/` too. Run `nox -s build` before +your final push and report its result. + +Three tests in `tests/test_capability_commands_v2.py`, +`test_resolution_grants_no_consent_and_no_partial_save[project|checkout|run]`, fail in this +capsule with the PR's changes stashed as well as with them applied; they are not this PR's. +Report them as pre-existing if you see them; do not fix them here. + +Do not build images, start capsules, or run the console smoke; the implementor runs the +acceptance inside a capsule in slice 2, and the evidence lands in the workstream's +status file. + +## The task + +Review the diff of PR 333 against its base: + + gh pr diff 333 + +Read first inside the diff: the docstring of `sources.py` (what the table means), the +docstring of `wrap.py` (the five steps and the rerun rule), then `wrap_detection.py` (facts as +data), then the command in `commands/project.py`. + +Improve it on your branch, focused on exactly three things, in this order: + +1. Correctness of the new and modified lines. Ask: + - Does `source_path` refuse every path that escapes the wrapper or is not in normal POSIX + form, and admit nested paths? Can a key reach the writer unquoted when it must be quoted? + - Does `ManifestV2.document()` round-trip an explicitly empty `[sources]` and a table with + unknown keys inside an entry? Does a schema-1 file with `[sources]` get refused by name? + - Does `declare_source` leave the lock bytes untouched, keep unknown keys of an existing + entry, and refuse before writing on every malformed input? + - In `wrap.py`: is the repository-root check right for a worktree or a symlinked path? Is + the existing-path rule right when `.gitmodules` names the path with a different URL, or + when the path is a registered submodule whose directory is missing? After + `_embed_git_directory`, is the submodule usable (`git status` inside it, `git submodule + status` from the wrapper)? What happens when `git submodule add` fails halfway? Is the + report honest when `initialize_project` is interactive and the user aborts? + - In `wrap_detection.py`: can a `build.gradle` that mentions GradleRIO in a comment or a + string mislead the rule? Is the Gradle version parsed from `distributionUrl` only? + - In `listing.py`: do the new rows break the JSON document or the pending logic? + - Guidance files: can a wrapped source's origin or path inject Markdown that misleads an + agent? Is the marker check exact? +2. Clarity of the new and modified lines. The standard is "obviously no deficiencies". +3. Test coverage of the new and modified lines. Add tests where a branch is not exercised. + Every test must fail if the line it covers is broken. Do not pad. + +Stay inside the PR's scope: the `[sources]` declaration, `declare_source`, `project wrap`, +its detection and guidance, the `config show` rows and the documentation of these. Do not +change `initialize_project`, the lock generation, the capsule runtime or the base image. Do +not widen the manifest contract; if you believe the table's shape is wrong, say why in the PR +body and keep your change minimal. + +## What you must not do + +- Do not edit `CURRENT-STATUS.md` files, `intake-dispositions.md`, the `evidence/` directory, + or run `devcapsule workflow publish`. +- Do not commit the `website` submodule pointer, the `devcapsule-sample-trading-research` + submodule pointer, `.idea/` files, `*.egg-info`, `.nox/`, `dist/` or `__pycache__`. +- Do not merge anything. Do not push to `main` or to any branch other than your review branch. +- Do not rebase or force-push. Do not build images or run capsules. + +## Deliverable + +1. Commits on `ws-wrapped-projects/wrap-review`, each message naming the component and the + evidence, ending with your `Co-Authored-By:` line: + `Co-authored-by: GPT-6 Astra Codex `. +2. Push the branch and open one pull request with + `gh pr create --base ws-wrapped-projects/wrap --head ws-wrapped-projects/wrap-review`. + Title: "Correctness, clarity and coverage review of #333 (PR1.1)". The body lists each + finding as: what was wrong or unclear, where, what you changed, how the test proves it. + Separate "changed" from "considered and left alone, because". List the proposals you did + not implement. State the gate result with counts and what was skipped. If you find nothing + to change, say so in the PR body and open the PR with the added tests only, or, if there + are none, say that in your final report instead of opening an empty PR. +3. Print the PR URL as the last line of your output, or "NO PR" if you opened none. + +Write the PR body and your report at about 80% ASD-STE100: one fact per sentence, about +twenty words, active voice. Every claim about behavior must be backed by a test or a command +you ran. + +If you cannot proceed, because of a blocker like network or credentials, stop and say exactly +what blocked you. Do not work around a blocker. From 0bedfcb74f85467468dd6feacc4ff7ed4954439c Mon Sep 17 00:00:00 2001 From: Costin Cozianu Date: Tue, 3 Nov 2026 00:07:53 +0000 Subject: [PATCH 10/15] wrap and sources: fix recovery and parsing with regression evidence 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 --- .../devcapsule/configuration/listing.py | 1 + .../configuration/owner_commands.py | 2 +- devcapsule-src/devcapsule/wrap.py | 93 ++++++++--- devcapsule-src/devcapsule/wrap_detection.py | 58 +++++-- devcapsule-src/tests/test_owner_commands.py | 37 +++++ devcapsule-src/tests/test_sources.py | 15 +- devcapsule-src/tests/test_wrap.py | 152 +++++++++++++++++- devcapsule-src/tests/test_wrap_detection.py | 39 ++++- docs/reference/cli.md | 7 +- docs/your-project/someone-elses-repository.md | 34 +++- 10 files changed, 388 insertions(+), 50 deletions(-) diff --git a/devcapsule-src/devcapsule/configuration/listing.py b/devcapsule-src/devcapsule/configuration/listing.py index 39a3af0c..df7bd6dc 100644 --- a/devcapsule-src/devcapsule/configuration/listing.py +++ b/devcapsule-src/devcapsule/configuration/listing.py @@ -15,6 +15,7 @@ - ``access``: host access and the base and vendor consents, from the authorization review; - ``env``: the environment the project asks for and the checkout saved; +- ``source``: a wrapped source's declared toolchain and fork or learning intent; - ``value``, ``binding``, ``secret``: the project's declared values and the selected components' state slots and secret inputs. diff --git a/devcapsule-src/devcapsule/configuration/owner_commands.py b/devcapsule-src/devcapsule/configuration/owner_commands.py index 41911fb3..ddda78d0 100644 --- a/devcapsule-src/devcapsule/configuration/owner_commands.py +++ b/devcapsule-src/devcapsule/configuration/owner_commands.py @@ -410,7 +410,7 @@ def declare_source(start: Path, path: str, *, upstream: str | None = None, java: """ root, manifest, _lock, _matrix = _project(start, check_resolutions=False) path = source_path(path, field_name="source path") - if upstream is not None and (not upstream.strip() or "\x00" in upstream): + if upstream is not None and (not isinstance(upstream, str) or not upstream.strip() or "\x00" in upstream): raise ProjectConfigurationError("The upstream is the upstream repository's URL; it cannot be blank.") if java is not None: java = java_line(java, field_name="java line") diff --git a/devcapsule-src/devcapsule/wrap.py b/devcapsule-src/devcapsule/wrap.py index b7e9b146..17acaa8a 100644 --- a/devcapsule-src/devcapsule/wrap.py +++ b/devcapsule-src/devcapsule/wrap.py @@ -23,11 +23,14 @@ from __future__ import annotations from dataclasses import dataclass +import html from pathlib import Path +import re import shutil import subprocess from typing import Any, Mapping, TextIO +from devcapsule.compat import CliError from devcapsule.configuration.file_formats import ProjectConfigurationError from devcapsule.configuration.manifest import current_manifest from devcapsule.configuration.manifest_document import Recommendations @@ -100,7 +103,9 @@ def wrap_project(request: WrapRequest, *, input_stream: TextIO | None = None, ou """Wrap one repository into the project at ``request.directory``; see the module docstring for the steps.""" root = request.directory.expanduser().resolve() _require_repository_root(root) - path = source_path(request.path or _repository_name(request.url), field_name="--path") + path = source_path(request.path if request.path is not None else _repository_name(request.url), field_name="--path") + # Validate source metadata before Git or initialization writes anything. + WrappedSources.read({"sources": {path: {"upstream": request.upstream} if request.upstream is not None else {}}}) submodule_action = _add_submodule(root, request.url, path) detection = detect(root / path) manifest_path = root / ".devcapsule" / "devcapsule.toml" @@ -108,13 +113,19 @@ def wrap_project(request: WrapRequest, *, input_stream: TextIO | None = None, ou capability_lines: list[str] = [] needed = detection.capabilities if detection is not None else () if not manifest_path.is_file(): - initialized = initialize_project( - InitializeRequest(directory=root, require=needed, ide=request.ide, agents=request.agents, - project_name=request.project_name, slug=request.slug, creator=request.creator, - project_mount=request.project_mount, answers=request.answers, - allow_unverified=request.allow_unverified, interactive=request.interactive), - input_stream=input_stream, output_stream=output_stream, - ) + try: + initialized = initialize_project( + InitializeRequest(directory=root, require=needed, ide=request.ide, agents=request.agents, + project_name=request.project_name, slug=request.slug, creator=request.creator, + project_mount=request.project_mount, answers=request.answers, + allow_unverified=request.allow_unverified, interactive=request.interactive), + input_stream=input_stream, output_stream=output_stream, + ) + except (CliError, KeyboardInterrupt) as exc: + raise ProjectConfigurationError( + f"Initialization did not finish: {exc or 'interrupted'}. The submodule {path} remains. " + "Rerun wrap with the missing answers; if configuration files already exist, complete 'project init' first." + ) from exc else: manifest = current_manifest(load_toml(manifest_path), manifest_path).document() declared = {name.partition(">=")[0] for name in manifest["capabilities"].get("required", [])} @@ -155,14 +166,25 @@ def _repository_name(url: str) -> str: def _add_submodule(root: Path, url: str, path: str) -> str: """Add the submodule unless the same one already stands at ``path``; embed its Git directory either way.""" target = root / path - registered = _git(root, "config", "-f", ".gitmodules", f"submodule.{path}.url", check=False) - if target.exists(): - if registered.returncode == 0 and registered.stdout.strip() == url: - action = f"Kept the submodule {path}, already added from {url}" - else: - raise ProjectConfigurationError(f"{target} exists and is not a submodule added from {url}; give another --path.") + if any(part.is_symlink() for part in (target, *target.parents) if part != root and root in part.parents): + raise ProjectConfigurationError(f"{target} passes through a symlink; give a path inside the wrapper without symlinks.") + registered = _registered_url(root, path) + if registered is not None: + if registered != url: + raise ProjectConfigurationError(f"{path} is registered with a different URL ({registered}); give another --path.") + if not (target / ".git").exists(): + _git(root, "submodule", "update", "--init", "--", path) + action = f"Kept the submodule {path}, already added from {url}" + elif target.exists(): + raise ProjectConfigurationError(f"{target} exists and is not a submodule added from {url}; inspect any partial clone, then give another --path.") else: - _git(root, "submodule", "add", "--", url, path) + try: + _git(root, "submodule", "add", "--", url, path) + except ProjectConfigurationError as exc: + raise ProjectConfigurationError( + f"{exc}. Git may have left a partial submodule at {path}; no files were removed. " + "Rerun wrap if the submodule was registered; otherwise inspect the path, .gitmodules and Git's modules directory before retrying." + ) from exc action = f"Added the submodule {path} from {url}" return action + ("; its Git directory is embedded in the tree." if _embed_git_directory(root, path) else ".") @@ -178,8 +200,9 @@ def _embed_git_directory(root: Path, path: str) -> bool: gitfile = root / path / ".git" if gitfile.is_dir(): return False - git_dir = Path(_git(root, "rev-parse", "--path-format=absolute", "--git-dir").stdout.strip()) - module = git_dir / "modules" / path + # Ask the submodule: its registered name can differ from its path, and + # a linked wrapper worktree has its own Git directory. + module = Path(_git(root / path, "rev-parse", "--absolute-git-dir").stdout.strip()) if not module.is_dir(): raise ProjectConfigurationError(f"The submodule's Git directory is neither at {gitfile} nor at {module}; cannot embed it.") gitfile.unlink() @@ -205,7 +228,7 @@ def _write_guidance(root: Path, manifest: Mapping[str, Any]) -> tuple[str, ...]: lines: list[str] = [] for name, text in (("AGENTS.md", render_agents(manifest, sources, origins)), ("README.md", render_readme(manifest, sources, origins))): target = root / name - if target.is_file() and not target.read_text(encoding="utf-8").startswith(GUIDANCE_MARKER): + if target.is_file() and target.read_text(encoding="utf-8").splitlines()[:1] != [GUIDANCE_MARKER]: lines.append(f"Kept your {name}; it does not carry the wrap marker. Add the wrapped sources to it yourself.") continue target.write_text(text, encoding="utf-8") @@ -214,8 +237,26 @@ def _write_guidance(root: Path, manifest: Mapping[str, Any]) -> tuple[str, ...]: def _origin(root: Path, path: str) -> str: - completed = _git(root, "config", "-f", ".gitmodules", f"submodule.{path}.url", check=False) - return completed.stdout.strip() if completed.returncode == 0 else "(not in .gitmodules)" + return _registered_url(root, path) or "(not in .gitmodules)" + + +def _registered_url(root: Path, path: str) -> str | None: + """Find a submodule by its path, which need not equal its Git section name.""" + completed = _git(root, "config", "--null", "-f", ".gitmodules", "--get-regexp", r"^submodule\..*\.path$", check=False) + for record in completed.stdout.split("\x00"): + key, separator, value = record.partition("\n") + if separator and value == path: + url = _git(root, "config", "--null", "-f", ".gitmodules", key[:-4] + "url", check=False) + # A registered path without a URL must not become a new add. + return url.stdout.removesuffix("\x00") if url.returncode == 0 else "" + return None + + +def _markdown_data(value: str) -> str: + """Keep external text on one line and prevent Markdown or HTML structure.""" + value = value.replace("\\", "\\\\").replace("\n", r"\n").replace("\r", r"\r").replace("\t", r"\t") + value = html.escape(value, quote=True) + return re.sub(r"[`*_[\]{}()#!|]", lambda match: f"&#{ord(match.group())};", value) def _java_lines(source: WrappedSource) -> list[str]: @@ -228,15 +269,15 @@ def _java_lines(source: WrappedSource) -> list[str]: def render_agents(manifest: Mapping[str, Any], sources: WrappedSources, origins: Mapping[str, str]) -> str: """The wrapper's AGENTS.md: agent-neutral, regenerated from the manifest.""" - name = manifest["project"]["name"] + name = _markdown_data(manifest["project"]["name"]) lines = [GUIDANCE_MARKER, f"# Agent Instructions: {name}", "", "This repository is a DevCapsule wrapper. It holds the DevCapsule configuration under", "`.devcapsule/` and foreign repositories as Git submodules. The code to work on lives in", "the submodules; the wrapper only sets up the environment around them.", "", "## Wrapped sources", ""] for source in sources.entries: - lines.extend([f"### `{source.path}`", "", f"- Origin: {origins.get(source.path, '')}", - f"- Intent: {source.intent}." + (f" Upstream: {source.upstream}." if source.upstream else "")]) + lines.extend([f"### {_markdown_data(source.path)}", "", f"- Origin: {_markdown_data(origins.get(source.path, ''))}", + f"- Intent: {source.intent}." + (f" Upstream: {_markdown_data(source.upstream)}." if source.upstream else "")]) lines.extend(_java_lines(source)) lines.append("") lines.extend(["## Rules", "", @@ -253,7 +294,7 @@ def render_agents(manifest: Mapping[str, Any], sources: WrappedSources, origins: def render_readme(manifest: Mapping[str, Any], sources: WrappedSources, origins: Mapping[str, str]) -> str: """The wrapper's README.md for a person: what this is and how to start.""" - name = manifest["project"]["name"] + name = _markdown_data(manifest["project"]["name"]) lines = [GUIDANCE_MARKER, f"# {name}", "", "A DevCapsule wrapper: the development environment for the repositories below, which", "are not this repository's own code and carry no DevCapsule configuration of their own.", "", @@ -262,8 +303,8 @@ def render_readme(manifest: Mapping[str, Any], sources: WrappedSources, origins: "An existing clone without the submodules: `git submodule update --init`.", "", "## Wrapped sources", ""] for source in sources.entries: - lines.extend([f"### `{source.path}`", "", f"- Origin: {origins.get(source.path, '')}", - f"- Intent: {source.intent}." + (f" Upstream: {source.upstream}." if source.upstream else "")]) + lines.extend([f"### {_markdown_data(source.path)}", "", f"- Origin: {_markdown_data(origins.get(source.path, ''))}", + f"- Intent: {source.intent}." + (f" Upstream: {_markdown_data(source.upstream)}." if source.upstream else "")]) lines.extend(_java_lines(source)) lines.append("") return "\n".join(lines) diff --git a/devcapsule-src/devcapsule/wrap_detection.py b/devcapsule-src/devcapsule/wrap_detection.py index c23f1b2c..9de05cad 100644 --- a/devcapsule-src/devcapsule/wrap_detection.py +++ b/devcapsule-src/devcapsule/wrap_detection.py @@ -25,12 +25,25 @@ # Gradle's Java compatibility table (docs.gradle.org/current/userguide/compatibility.html): # every 8.x and 9.0 run on JDK 17; 9.1 is the first to run on JDK 25. -# A plain Gradle project gets the oldest line its wrapper runs on, which is -# the line most likely to match what the project's authors use. +# Select 17 for 8.x and 9.0, and the capsule's default 25 from 9.1 onward. +# This is a wrapper selection rule, not Gradle's minimum Java requirement. GRADLE_JAVA_LINES: tuple[tuple[tuple[int, int], str], ...] = (((9, 1), "25"), ((8, 0), "17")) -_GRADLERIO_PATTERN = re.compile(r'edu\.wpi\.first\.GradleRIO["\')]*\s*version\s*\(?\s*["\'](\d{4})') -_DISTRIBUTION_PATTERN = re.compile(r"gradle-(\d+)\.(\d+)") +# Keep strings as whole tokens. A plugin example inside a string must never +# become an executable declaration. Comments are discarded below. +_SCRIPT_TOKEN = re.compile( + "|".join(( + r"//[^\n]*", r"/\*.*?\*/", # comments + r"\$/.*?/\$", r"/(?:\\.|[^/\\])*/", # Groovy slashy strings + r'""".*?"""', r"'''.*?'''", # multiline strings + r'"(?:\\.|[^"\\])*"', r"'(?:\\.|[^'\\])*'", + r"[A-Za-z_$][\w$]*", r"[^\s]", + )), + re.DOTALL, +) +_PLUGIN_YEAR = re.compile(r'''(["'])(\d{4})(?:\.[^"']*)?\1''') +_DISTRIBUTION_PROPERTY = re.compile(r"^[ \t]*distributionUrl[ \t]*(?:[=:][ \t]*|[ \t]+)([^\r\n]*)", re.MULTILINE) +_DISTRIBUTION_PATTERN = re.compile(r"/gradle-(\d+)\.(\d+)(?:[.\w-]*)-(?:bin|all)\.zip(?:[?#].*)?$") @dataclass(frozen=True) @@ -54,14 +67,13 @@ def detect(source: Path) -> Detection | None: if not (source / "gradlew").is_file() or build_script is None: return None evidence = [f"Gradle wrapper and {build_script.name}"] - match = _GRADLERIO_PATTERN.search(build_script.read_text(encoding="utf-8", errors="replace")) - if match is not None: - year = match.group(1) + year = _gradlerio_year(build_script.read_text(encoding="utf-8", errors="replace")) + if year is not None: java = GRADLERIO_JAVA_LINES.get(year) evidence.append(f"GradleRIO {year}" + (f": WPILib {year} builds with Java {java}" if java else f": no Java line known for WPILib {year}")) return Detection(("java",), "java-ide", java, tuple(evidence)) gradle = _gradle_java_line(source) - evidence.append(f"Gradle {gradle[0]}: runs on Java {gradle[1]}" if gradle is not None else "the Gradle version is not in gradle-wrapper.properties") + evidence.append(f"Gradle {gradle[0]}: runs on Java {gradle[1]}" if gradle is not None else "no supported Gradle version found in distributionUrl in gradle-wrapper.properties") return Detection(("java",), "java-ide", gradle[1] if gradle is not None else None, tuple(evidence)) @@ -70,7 +82,8 @@ def _gradle_java_line(source: Path) -> tuple[str, str] | None: properties = source / "gradle" / "wrapper" / "gradle-wrapper.properties" if not properties.is_file(): return None - match = _DISTRIBUTION_PATTERN.search(properties.read_text(encoding="utf-8", errors="replace")) + declarations = _DISTRIBUTION_PROPERTY.findall(properties.read_text(encoding="utf-8", errors="replace")) + match = _DISTRIBUTION_PATTERN.search(declarations[-1].strip()) if declarations else None if match is None: return None version = (int(match.group(1)), int(match.group(2))) @@ -78,3 +91,30 @@ def _gradle_java_line(source: Path) -> tuple[str, str] | None: if version >= minimum: return f"{version[0]}.{version[1]}", line return None + + +def _gradlerio_year(script: str) -> str | None: + """Read a literal ``id ... version ...`` declaration, without evaluating Gradle.""" + tokens = [match.group() for match in _SCRIPT_TOKEN.finditer(script) + if not match.group().startswith(("//", "/*"))] + for index, token in enumerate(tokens): + if token != "id": + continue + rest = tokens[index + 1:] + if rest[:1] == ["("]: + if len(rest) < 3 or rest[2] != ")": + continue + plugin, rest = rest[1], rest[3:] + elif rest: + plugin, rest = rest[0], rest[1:] + else: + continue + if plugin not in ('"edu.wpi.first.GradleRIO"', "'edu.wpi.first.GradleRIO'") or rest[:1] != ["version"]: + continue + rest = rest[1:] + if rest[:1] == ["("]: + rest = rest[1:] + match = _PLUGIN_YEAR.fullmatch(rest[0]) if rest else None + if match is not None: + return match.group(2) + return None diff --git a/devcapsule-src/tests/test_owner_commands.py b/devcapsule-src/tests/test_owner_commands.py index ed1995d9..6291b2c2 100644 --- a/devcapsule-src/tests/test_owner_commands.py +++ b/devcapsule-src/tests/test_owner_commands.py @@ -3,7 +3,9 @@ from __future__ import annotations from pathlib import Path +import json import tomllib +from typing import Any import pytest @@ -384,3 +386,38 @@ def test_declare_source_preview_and_refusals_write_nothing(project: Path) -> Non with pytest.raises(ProjectConfigurationError, match="upstream"): owner_commands.declare_source(project, "robot", upstream=" ") assert manifest_text(project) == before + + +@pytest.mark.parametrize("fields", [ + {"path": ""}, {"path": "../escape"}, {"path": 3}, + {"upstream": 3}, {"upstream": "bad\x00url"}, {"upstream": " "}, + {"java": 17}, {"java": "0"}, {"java": "17\n"}, +]) +def test_declare_source_refuses_malformed_inputs_without_touching_files(project: Path, fields: dict[str, Any]) -> None: + manifest_path, lock_path, _ = paths(project) + before = manifest_path.read_bytes(), lock_path.read_bytes() + with pytest.raises(ProjectConfigurationError): + owner_commands.declare_source(project, **{"path": "vendor/robot", **fields}) + assert (manifest_path.read_bytes(), lock_path.read_bytes()) == before + + +def test_sources_survive_other_owner_edits_and_do_not_change_pending_decisions(project: Path, capsys) -> None: + assert cli.main(["project", "--path", str(project), "config", "show", "--json"]) == 0 + baseline = json.loads(capsys.readouterr().out) + owner_commands.declare_source(project, 'vendor/robot.code', upstream="https://example.test/up", java="17") + owner_commands.declare_source(project, "notes") + manifest_path, lock_path, _ = paths(project) + manifest_path.write_text(manifest_path.read_text().replace('java = "17"', 'java = "17"\nfuture = { extra = true }')) + sources = load_toml(manifest_path)["sources"] + owner_commands.recommend(project, "memory", "4g") + assert load_toml(manifest_path)["sources"] == sources + lock = lock_path.read_bytes() + owner_commands.declare_source(project, "notes", preview=True) + assert lock_path.read_bytes() == lock + assert cli.main(["project", "--path", str(project), "config", "show", "--json"]) == 0 + document = json.loads(capsys.readouterr().out) + assert document["pending"] == baseline["pending"] + assert [row for row in document["rows"] if row["kind"] == "source"] == [ + {"kind": "source", "name": "notes", "effective": "no toolchain declared", "source": "project: upstream, read-only", "pending": "", "command": ""}, + {"kind": "source", "name": "vendor/robot.code", "effective": "java 17", "source": "project: fork of https://example.test/up", "pending": "", "command": ""}, + ] diff --git a/devcapsule-src/tests/test_sources.py b/devcapsule-src/tests/test_sources.py index 7b73d053..70cc1d16 100644 --- a/devcapsule-src/tests/test_sources.py +++ b/devcapsule-src/tests/test_sources.py @@ -80,7 +80,7 @@ def test_schema_two_reads_sources_as_its_own_table_and_renders_it_after_capabili assert value.extensions == {} assert value.wrapped_sources.entries == (WrappedSource("vendor/robot", None, "17"),) text = render_manifest(value.document()) - assert text.index("[capabilities]") < text.index('[sources."vendor/robot"]') < text.index("[recommendations]") if "[recommendations]" in text else True + assert text.index("[capabilities]") < text.index('[sources."vendor/robot"]') assert 'java = "17"' in text assert read_manifest(tomllib.loads(text), "rendered") == value @@ -100,3 +100,16 @@ def test_an_explicitly_empty_sources_table_survives_the_round_trip() -> None: value = read_manifest(manifest(), "manifest") assert value.document()["sources"] == {} assert "[sources]" in render_manifest(value.document()) + + +@pytest.mark.parametrize("path", ['vendor/robot', 'robot.code', 'two words', 'quote"', 'tick`', 'line\nbreak', 'robot\x7f']) +def test_source_keys_and_unknown_fields_round_trip_through_the_manifest(path: str) -> None: + document = manifest(**{path: {"java": "17", "future": {"key.with.dots": True}}}) + value = ManifestV2.read(document, "manifest") + assert tomllib.loads(render_manifest(value.document())) == document + + +@pytest.mark.parametrize("path", [None, 17, "a/./b", "a/..", "./a", "//a", "a\x00b"]) +def test_additional_non_normal_source_paths_are_refused(path: object) -> None: + with pytest.raises(ProjectConfigurationError, match="source path"): + source_path(path, field_name="source path") diff --git a/devcapsule-src/tests/test_wrap.py b/devcapsule-src/tests/test_wrap.py index 34b4198c..66a4ff5d 100644 --- a/devcapsule-src/tests/test_wrap.py +++ b/devcapsule-src/tests/test_wrap.py @@ -3,6 +3,8 @@ from __future__ import annotations from pathlib import Path +from io import StringIO +import shutil import subprocess import pytest @@ -10,7 +12,7 @@ from devcapsule import cli from devcapsule.configuration.file_formats import ProjectConfigurationError from devcapsule.configuration.storage import load_toml -from devcapsule.wrap import GUIDANCE_MARKER, WrapRequest, wrap_project +from devcapsule.wrap import GUIDANCE_MARKER, WrapRequest, _add_submodule, wrap_project from tests.test_wrap_detection import gradle_project GRADLERIO = 'plugins {\n id "java"\n id "edu.wpi.first.GradleRIO" version "2025.3.2"\n}\n' @@ -78,7 +80,7 @@ def test_a_first_wrap_builds_the_whole_wrapper(tmp_path: Path) -> None: assert git(root, "status", "--porcelain") == "A .gitmodules\nA RobotCode2025Public\n?? .devcapsule/\n?? AGENTS.md\n?? README.md" agents = (root / "AGENTS.md").read_text() assert agents.startswith(GUIDANCE_MARKER + "\n") - assert "### `RobotCode2025Public`" in agents and f"- Origin: {url}" in agents + assert "### RobotCode2025Public" in agents and f"- Origin: {url.replace('_', '_')}" in agents assert "- Intent: learn from it; it is read-only, nothing is pushed." in agents assert 'export JAVA_HOME=/opt/java/17; export PATH="$JAVA_HOME/bin:$PATH"' in agents readme = (root / "README.md").read_text() @@ -98,7 +100,7 @@ def test_a_second_wrap_extends_the_manifest_and_regenerates_the_guidance(tmp_pat assert manifest["sources"] == {"AdvantageKit": {"upstream": "https://github.com/Mechanical-Advantage/AdvantageKit", "java": "17"}, "RobotCode2025Public": {"java": "17"}} agents = (root / "AGENTS.md").read_text() - assert agents.index("### `AdvantageKit`") < agents.index("### `RobotCode2025Public`") + assert agents.index("### AdvantageKit") < agents.index("### RobotCode2025Public") assert ("- Intent: change it in your fork; pull requests go to the fork's origin, never to the upstream. " "Upstream: https://github.com/Mechanical-Advantage/AdvantageKit.") in agents @@ -181,3 +183,147 @@ def test_the_command_line_reaches_the_operation(tmp_path: Path, capsys) -> None: assert load_toml(root / ".devcapsule" / "devcapsule.toml")["sources"]["RobotCode2025Public"]["upstream"] == "https://github.com/Mechanical-Advantage/RobotCode2025Public" assert cli.main(["project", "--path", str(root), "config", "show"]) == 0 assert "source RobotCode2025Public java 17" in capsys.readouterr().out + + +@pytest.mark.parametrize("missing", [False, True]) +def test_registered_path_with_another_url_is_refused_without_changes(tmp_path: Path, missing: bool) -> None: + url = upstream(tmp_path, "robot") + root = wrapper(tmp_path) + git(root, "submodule", "add", "--name", "custom-name", url, "vendor/robot") + if missing: + shutil.rmtree(root / "vendor/robot") + before = (root / ".gitmodules").read_bytes() + with pytest.raises(ProjectConfigurationError, match="registered.*different URL"): + _add_submodule(root, url + "-other", "vendor/robot") + assert (root / ".gitmodules").read_bytes() == before + assert (root / "vendor/robot").exists() is not missing + + +@pytest.mark.parametrize("missing", [False, True]) +def test_registered_submodule_uses_its_path_not_its_name(tmp_path: Path, missing: bool) -> None: + url = upstream(tmp_path, "robot") + root = wrapper(tmp_path) + git(root, "submodule", "add", "--name", "custom-name", url, "vendor/robot") + if missing: + shutil.rmtree(root / "vendor/robot") + wrap_project(request(root, url, path="vendor/robot")) + assert (root / "vendor/robot/.git").is_dir() + assert git(root / "vendor/robot", "status", "--porcelain") == "" + assert "vendor/robot" in git(root, "submodule", "status") + assert f"- Origin: {url.replace('_', '_')}" in (root / "AGENTS.md").read_text() + + +def test_wrap_at_a_symlink_to_a_linked_worktree(tmp_path: Path) -> None: + url = upstream(tmp_path, "robot") + root = wrapper(tmp_path) + git(root, "-c", "user.name=t", "-c", "user.email=t@example.invalid", "commit", "--allow-empty", "-m", "seed") + worktree = tmp_path / "linked" + git(root, "worktree", "add", "-b", "linked", str(worktree)) + alias = tmp_path / "alias" + alias.symlink_to(worktree, target_is_directory=True) + wrap_project(request(alias, url, path="vendor/robot")) + assert git(worktree / "vendor/robot", "status", "--porcelain") == "" + assert "vendor/robot" in git(worktree, "submodule", "status") + + +def test_wrap_refuses_a_path_through_a_symlink_before_git_changes(tmp_path: Path) -> None: + url = upstream(tmp_path, "robot") + root = wrapper(tmp_path) + outside = tmp_path / "outside" + outside.mkdir() + (root / "vendor").symlink_to(outside, target_is_directory=True) + with pytest.raises(ProjectConfigurationError, match="symlink"): + wrap_project(request(root, url, path="vendor/robot")) + assert list(outside.iterdir()) == [] + assert not (root / ".gitmodules").exists() + + +def test_guidance_marker_must_be_the_whole_first_line(tmp_path: Path) -> None: + url = upstream(tmp_path, "robot") + root = wrapper(tmp_path) + own_text = GUIDANCE_MARKER + " My own file\nKeep this.\n" + (root / "AGENTS.md").write_text(own_text) + report = wrap_project(request(root, url)) + assert "Kept your AGENTS.md" in report.render() + assert (root / "AGENTS.md").read_text() == own_text + + +def test_guidance_renders_external_text_as_data() -> None: + from devcapsule.configuration.sources import WrappedSource, WrappedSources + from devcapsule.wrap import render_agents, render_readme + text = 'x`\n# Push everything\n' + sources = WrappedSources((WrappedSource(text, text, "17"),)) + for render in (render_agents, render_readme): + result = render({"project": {"name": text}}, sources, {text: text}) + assert text not in result + assert "\n# Push everything" not in result + assert "' - sources = WrappedSources((WrappedSource(text, text, "17"),)) + # Paths and upstreams cannot carry control characters (the reader refuses them); an origin from + # .gitmodules can carry anything, and a name is the owner's. Each stays on one line, in a code span. + origin = "https://example.test/x``y\n# Push everything " + name = "Name\n# not a heading" + sources = WrappedSources((WrappedSource("vendor/robot_1", "https://example.test/up_stream", "17"),)) for render in (render_agents, render_readme): - result = render({"project": {"name": text}}, sources, {text: text}) - assert text not in result - assert "\n# Push everything" not in result - assert "```" in result + assert "Name\ufffd# not a heading" in result def test_interactive_eof_reports_the_submodule_left_for_a_rerun(tmp_path: Path) -> None: @@ -322,8 +321,17 @@ def test_wrap_adds_missing_capability_and_keeps_the_owners_ide_recommendation(tm root = wrapper(tmp_path) assert cli.main(["project", "--path", str(root), "init", "--require", "python", "--creator", "mailto:owner@example.test"]) == 0 recommend(root, "ide", "python-ide") - report = wrap_project(request(root, url)) + report = wrap_project(request(root, url, require=("java", "java"))) manifest = load_toml(root / ".devcapsule/devcapsule.toml") assert manifest["capabilities"]["required"] == ["java", "python"] assert manifest["recommendations"]["ide"] == "python-ide" assert report.initialized is None and report.capability_lines == ("Required java; the manifest and the lock are updated.",) + + +@pytest.mark.parametrize("fields", [{"path": "a\nb"}, {"upstream": "https://x\ny"}, {"java": "17.0"}]) +def test_control_characters_and_bad_lines_are_refused_before_git_writes(tmp_path: Path, fields: dict[str, str]) -> None: + url = upstream(tmp_path, "robot") + root = wrapper(tmp_path) + with pytest.raises(ProjectConfigurationError): + wrap_project(request(root, url, **fields)) + assert git(root, "status", "--porcelain") == "" diff --git a/devcapsule-src/tests/test_wrap_detection.py b/devcapsule-src/tests/test_wrap_detection.py deleted file mode 100644 index 76b33cf9..00000000 --- a/devcapsule-src/tests/test_wrap_detection.py +++ /dev/null @@ -1,94 +0,0 @@ -"""What ``project wrap`` reads off a source: the showcase's Gradle shapes, as data with their sources.""" - -from __future__ import annotations - -from pathlib import Path - -import pytest - -from devcapsule.wrap_detection import Detection, detect - - -def gradle_project(root: Path, *, script: str = 'plugins {\n id "java"\n}\n', distribution: str | None = "8.11", kts: bool = False) -> Path: - root.mkdir(parents=True, exist_ok=True) - (root / "gradlew").write_text("#!/bin/sh\n") - (root / ("build.gradle.kts" if kts else "build.gradle")).write_text(script) - if distribution is not None: - (root / "gradle" / "wrapper").mkdir(parents=True) - (root / "gradle" / "wrapper" / "gradle-wrapper.properties").write_text( - f"distributionUrl=https\\://services.gradle.org/distributions/gradle-{distribution}-bin.zip\n") - return root - - -@pytest.mark.parametrize("year, line", [("2025", "17"), ("2026", "17")]) -def test_gradlerio_names_the_java_line_of_its_wpilib_year(tmp_path: Path, year: str, line: str) -> None: - source = gradle_project(tmp_path / "robot", script=f'plugins {{\n id "edu.wpi.first.GradleRIO" version "{year}.3.2"\n}}\n') - assert detect(source) == Detection(("java",), "java-ide", line, - ("Gradle wrapper and build.gradle", f"GradleRIO {year}: WPILib {year} builds with Java {line}")) - - -def test_gradlerio_in_a_kotlin_script_is_read_too(tmp_path: Path) -> None: - source = gradle_project(tmp_path / "robot", script='plugins {\n id("edu.wpi.first.GradleRIO") version "2026.1.1"\n}\n', kts=True) - detection = detect(source) - assert detection is not None and detection.java == "17" and detection.evidence[0] == "Gradle wrapper and build.gradle.kts" - - -def test_an_unknown_wpilib_year_requires_java_but_names_no_line(tmp_path: Path) -> None: - source = gradle_project(tmp_path / "robot", script='plugins { id "edu.wpi.first.GradleRIO" version "2031.1.1" }\n') - assert detect(source) == Detection(("java",), "java-ide", None, - ("Gradle wrapper and build.gradle", "GradleRIO 2031: no Java line known for WPILib 2031")) - - -@pytest.mark.parametrize("distribution, line", [("8.11", "17"), ("8.0", "17"), ("9.0", "17"), ("9.1", "25"), ("10.2", "25")]) -def test_plain_gradle_gets_the_declared_selection_for_its_wrapper(tmp_path: Path, distribution: str, line: str) -> None: - source = gradle_project(tmp_path / "lib", distribution=distribution) - assert detect(source) == Detection(("java",), "java-ide", line, - ("Gradle wrapper and build.gradle", f"Gradle {distribution}: runs on Java {line}")) - - -def test_a_gradle_wrapper_without_a_readable_version_names_no_line(tmp_path: Path) -> None: - source = gradle_project(tmp_path / "lib", distribution=None) - assert detect(source) == Detection(("java",), "java-ide", None, - ("Gradle wrapper and build.gradle", "no supported Gradle version found in distributionUrl in gradle-wrapper.properties")) - - -def test_anything_else_is_undetected(tmp_path: Path) -> None: - (tmp_path / "pyproject.toml").write_text("[project]\nname = 'x'\n") - assert detect(tmp_path) is None - (tmp_path / "gradlew").write_text("") # a wrapper without a build script says nothing - assert detect(tmp_path) is None - - -@pytest.mark.parametrize("script", [ - '// id "edu.wpi.first.GradleRIO" version "2025.3.2"', - '/* id "edu.wpi.first.GradleRIO" version "2025.3.2" */', - '''def example = 'id "edu.wpi.first.GradleRIO" version "2025.3.2"' ''', - '''def example = """id "edu.wpi.first.GradleRIO" version "2025.3.2"""" ''', - '''def example = /id "edu.wpi.first.GradleRIO" version "2025.3.2"/ ''', - '''def example = $/id "edu.wpi.first.GradleRIO" version "2025.3.2"/$ ''', -]) -def test_gradlerio_mentions_are_not_plugin_declarations(tmp_path: Path, script: str) -> None: - source = gradle_project(tmp_path / "lib", script=script, distribution="9.1") - result = detect(source) - assert result is not None and result.java == "25" - assert result.evidence[-1] == "Gradle 9.1: runs on Java 25" - - -def test_comments_between_plugin_tokens_do_not_hide_the_declaration(tmp_path: Path) -> None: - source = gradle_project(tmp_path / "lib", script='plugins { id /* plugin */ ("edu.wpi.first.GradleRIO") version /* year */ "2026.1.1" }', distribution="9.1") - result = detect(source) - assert result is not None and result.java == "17" - - -@pytest.mark.parametrize("properties, line", [ - ('# distributionUrl=https://example/gradle-8.11-bin.zip\ndistributionUrl=https://example/gradle-9.1-bin.zip\n', "25"), - ('other=https://example/gradle-8.11-bin.zip\ndistributionUrl=https://example/gradle-9.1-bin.zip\n', "25"), - ('other=https://example/gradle-8.11-bin.zip\n', None), - ('distributionUrl=https://example/gradle-7.6-bin.zip\n', None), - ('distributionUrl=https://example/unknown.zip\n', None), -]) -def test_gradle_version_comes_only_from_distribution_url(tmp_path: Path, properties: str, line: str | None) -> None: - source = gradle_project(tmp_path / "lib") - (source / "gradle/wrapper/gradle-wrapper.properties").write_text(properties) - result = detect(source) - assert result is not None and result.java == line diff --git a/docs/reference/cli.md b/docs/reference/cli.md index 2a024d67..078cbca1 100644 --- a/docs/reference/cli.md +++ b/docs/reference/cli.md @@ -39,7 +39,7 @@ home instead and disables this fallback to launcher settings. | Command | Intent | |---|---| | `init` | Create the project manifest and platform lock, record your checkout's IDE and capabilities, and resolve when an IDE is chosen. | -| `wrap` | Add a foreign repository as a submodule, read what it needs, create or extend the manifest and lock, declare it as a wrapped source, and write the wrapper's `AGENTS.md` and `README.md`. | +| `wrap` | Add a foreign repository as a submodule, require what you name, create or extend the manifest and lock, declare it as a wrapped source, and write the wrapper's `AGENTS.md` and `README.md`. | | `run` | Derive the launch plan from the project, this home, and this checkout, ask any open questions, and start the capsule. | | `config` | Inspect what the next launch uses, change checkout choices or the shared project contract, and validate without launching. | | `info` | Show selected software, container environment, and persistent storage paths without changing state. | @@ -75,20 +75,21 @@ also accept one optional justification argument after the value. ### `wrap` ```text -devcapsule project wrap URL [--path NAME] [--upstream URL] [--ide IDE] [--with CAPABILITY]... +devcapsule project wrap URL [--path NAME] [--upstream URL] [--require CAPABILITY]... [--java LINE] + [--ide IDE] [--with CAPABILITY]... [--name NAME] [--slug SLUG] [--creator CREATOR] [--project-mount PATH] [--unverified] [--set NAME VALUE]... [--authorize NAME VALUE]... [--bind NAME VALUE]... ``` Run it at the top level of a Git repository, the wrapper. `wrap` adds `URL` as a submodule at `--path` (default: the repository's name) with its Git -directory embedded in the tree, reads what the source needs, and declares it -under `[sources."NAME"]` in `.devcapsule/devcapsule.toml`. Without a manifest -it initializes one as `init` would, with the detected requirements; with one -it adds what is missing. A Gradle wrapper means `java` is required and -`java-ide` recommended; WPILib's GradleRIO names the Java line its season -builds with, `java = "17"`. It then writes `AGENTS.md` and `README.md` from -the manifest, regenerated on every wrap and left alone when they are yours. +directory embedded in the tree, requires the capabilities you name, and +declares the source under `[sources."NAME"]` in `.devcapsule/devcapsule.toml` +with the Java line you give, `java = "17"`. Without a manifest it initializes +one as `init` would; with one it adds what is missing. It infers nothing from +the source. It then writes `AGENTS.md` and `README.md` from the manifest, +regenerated on every wrap and left alone when they are yours; a source +without a Java line is described as unsettled, to be found out with the user. `--upstream` says `URL` is your fork of that upstream: changes and pull requests go to the fork, never to the upstream. Without it the origin is the diff --git a/docs/your-project/someone-elses-repository.md b/docs/your-project/someone-elses-repository.md index 5bcc0d54..d0e4c65f 100644 --- a/docs/your-project/someone-elses-repository.md +++ b/docs/your-project/someone-elses-repository.md @@ -19,32 +19,29 @@ of it. Nothing is written into their tree. ```bash mkdir frc-learning && cd frc-learning && git init -~/.local/bin/devcapsule project wrap https://github.com/Mechanical-Advantage/RobotCode2025Public +~/.local/bin/devcapsule project wrap https://github.com/Mechanical-Advantage/RobotCode2025Public --require java --java 17 ~/.local/bin/devcapsule project run ``` -`wrap` adds the submodule, reads what the code needs, writes the manifest and +`wrap` adds the submodule, requires what you name, writes the manifest and the lock, and writes an `AGENTS.md` and a `README.md` that say what is foreign, -how to build it and which Java to use. `run` opens the capsule with the IDE on -the wrapper; the code is in the submodule. Commit what `wrap` produced; anyone -who clones the wrapper must initialize its submodules before running it. - -## What `wrap` reads off the code - -| Found in the repository | Declared | -|---|---| -| A Gradle wrapper with WPILib's GradleRIO plugin | `java` required, `java-ide` recommended, the Java line of that WPILib season: 17 for 2025 and 2026 | -| A Gradle wrapper without it | `java` required, `java-ide` recommended; Java 17 for Gradle 8.x and 9.0, Java 25 from 9.1 onward | -| Anything else | Nothing; `wrap` says so and names `project config require` | - -The Java line matters because a build such as GradleRIO's refuses any other -JDK. The generated `AGENTS.md` names the line to select before building in -that directory. The matching JDK must exist under `/opt/java/`. -Slice 2 supplies the additional JDK and session-wide selection. - -Detection reads literal GradleRIO plugin declarations. It ignores comments -and string examples. Plain Gradle detection reads only `distributionUrl` in -`gradle/wrapper/gradle-wrapper.properties`. It does not execute build scripts. +under whose control, and which Java to use. `run` opens the capsule with the +IDE on the wrapper; the code is in the submodule. Commit what `wrap` produced; +anyone who clones the wrapper must initialize its submodules before running it. + +## What you tell `wrap` + +The launcher infers nothing from a foreign tree. You name what every +checkout must have, `--require java`, as you would with `init`, and the Java +line the source builds with, `--java 17`. The line matters because a build +such as WPILib's refuses any other JDK; the generated `AGENTS.md` names it, +and the matching JDK must exist under `/opt/java/`. The additional JDK +in the base and the session-wide selection are planned for the next slice. + +Name nothing and the source is still wrapped, with its build unsettled: the +`AGENTS.md` tells the agent to find out with you, from the source's own +files, before assuming. The IDE is recommended separately, +`devcapsule project config recommend ide java-ide`, as for any project. ## Learning or changing From 0a131d699fd4989d0941a34df8b1e1e2569aef44 Mon Sep 17 00:00:00 2001 From: Costin Cozianu Date: Tue, 3 Nov 2026 00:30:08 +0000 Subject: [PATCH 12/15] Record PR1.1 and the owner's amendments 6 and 7 of the work order Co-Authored-By: Claude Fable 5.1 --- CURRENT-STATUS.md | 2 +- .../CURRENT-STATUS.md | 32 +++++++++++++------ .../2026-11-02-wrapped-projects.md | 18 +++++++++-- 3 files changed, 39 insertions(+), 13 deletions(-) diff --git a/CURRENT-STATUS.md b/CURRENT-STATUS.md index d6b7f9da..a3aea31d 100644 --- a/CURRENT-STATUS.md +++ b/CURRENT-STATUS.md @@ -19,7 +19,7 @@ coordination branch. Detailed state belongs in each linked status file. | `user-docs` | 2026-09-12 | Deliver V1 adopter documentation from first useful session through resuming work | paused 2026-09-28; 0.2.15 documentation merged in PR #151 and on docs-0.2.15; improvement list awaits the owner's decision | `ws-user-docs/first-session` | [workstream status](engineering-docs/wip/2026-09-12-user-docs/CURRENT-STATUS.md) | | `website` | 2026-09-16 | Deliver the website autonomy experiment: repository-owned landing/docs/blog content, independently developable website submodule, local preview and publishing mechanism | paused 2026-09-30; producer migration merged in PR #152 and the versioned documentation live; W04-C, W09-C, W11-C retained | `ws-website/contract-v1` | [workstream status](engineering-docs/wip/2026-09-16-website/CURRENT-STATUS.md) | | `capsule-webconsole` | 2026-10-09 | Serve a token-gated web console from every capsule: configuration, versions, info, live resources, later records and workflow state | active; work order accepted 2026-10-09; the first iteration, deliverables 1 and 2, is three stacked pull requests, #184, #186 and the runtime-and-base slice, each reviewed by the Codex pair; the owner merges | `ws-capsule-webconsole/first-slice` | [workstream status](engineering-docs/wip/2026-10-09-capsule-webconsole/CURRENT-STATUS.md) | -| `wrapped-projects` | 2026-11-02 | Wrap a foreign repository as a submodule of a small wrapper project and work on it in a capsule with three commands; FRC learning project first | active; slice 1 delivered as PR1 (#333) 2026-11-02; Codex review in progress | `ws-wrapped-projects/wrap` | [workstream status](engineering-docs/wip/2026-11-02-wrapped-projects/CURRENT-STATUS.md) | +| `wrapped-projects` | 2026-11-02 | Wrap a foreign repository as a submodule of a small wrapper project and work on it in a capsule with three commands; FRC learning project first | active; PR1 (#333) reviewed and its PR1.1 merged 2026-11-02; the project-capabilities design note is next | `ws-wrapped-projects/wrap` | [workstream status](engineering-docs/wip/2026-11-02-wrapped-projects/CURRENT-STATUS.md) | | `website` | 2026-09-16 | Deliver the website autonomy experiment: repository-owned landing/docs/blog content, independently developable website submodule, local preview and publishing mechanism | paused 2026-09-20 at owner request to switch to maintenance; experiment accepted, A−; blog integrated and published; content/parent-integration follow-ups remain | `ws-website/initial-cut`; renamed from `website/initial-cut`; preparation and backlog-handoff exceptions in status | [workstream status](engineering-docs/wip/2026-09-16-website/CURRENT-STATUS.md) | Paused and blocked workstreams remain open until they conclude successfully or diff --git a/engineering-docs/wip/2026-11-02-wrapped-projects/CURRENT-STATUS.md b/engineering-docs/wip/2026-11-02-wrapped-projects/CURRENT-STATUS.md index b088243d..b414de5b 100644 --- a/engineering-docs/wip/2026-11-02-wrapped-projects/CURRENT-STATUS.md +++ b/engineering-docs/wip/2026-11-02-wrapped-projects/CURRENT-STATUS.md @@ -4,7 +4,7 @@ Mnemonic: `wrapped-projects` Start date: 2026-11-02 -State: active; slice 1 delivered as PR1 (#333) on 2026-11-02; its Codex review (PR1.1) in progress +State: active; PR1 (#333) reviewed, PR1.1 (#334) merged, detection removed at the owner's direction; gate running; the project-capabilities design note is next Definition read: WORKFLOW.md@d2ccbbe43dfa, WORKFLOW-LOCAL.md@65501b3407db @@ -12,7 +12,7 @@ Branch association: `ws-wrapped-projects/wrap`, forked from `origin/main` at 31d Integration target: `main` -Delivery method: pull request, merge commit, under the Pair Review Loop with Codex as the review partner +Delivery method: pull request, merge commit, under the Pair Review Loop with Codex as the review partner; PR1.1 (#334) merged 2026-11-02 Requirements: R-CONFIG-001, R-SCOPE-001; a new requirement for the wrapped-project shape is a deliverable @@ -79,15 +79,29 @@ completes. Three pre-existing failures in `test_capability_commands_v2.py` (`test_resolution_grants_no_consent_and_no_partial_save`) fail in this capsule with the slice stashed as well as applied; disclosed on the PR, not fixed here. +**2026-11-02 late, PR1.1 and the owner's two rulings.** The Codex + gpt-6-astra pair's review, +[#334](https://github.com/ccozianu/devcapsule/pull/334), was accepted without a round and merged +at 5a18a5c9: inputs validated before Git writes, submodules found by path (a section name is not +a path), missing registered directories initialized, the embedding asking the submodule for its +own Git directory, recovery messages, the exact first-line marker. Its entity escaping of the +guidance was replaced afterwards by code spans, since agents read the file raw. Then the owner, +in chat, ruled twice: the launcher infers nothing from a foreign tree, so the Gradle detection +is deleted and `wrap` takes `--require` and `--java` (work order amendment 6); and the next +design is higher-level project capabilities, browse, build, test, debug and manage, each settled +or unsettled, with the unsettled ones surfaced by the status as the standing task of the agent +with the user (amendment 7). The four questions put to the owner for that note: one word or two +for the two kinds of capability; whether `browse` is the project's or the IDE's; whether `manage` +is these records or the workflow definition; whether the proving run's evidence is kept. + ## Next Resumable Task -1. Run the Codex review of PR1 (#333): read PR1.1's diff, post the assessment, merge or push - back, at most three rounds; then the full gate on PR1's branch, the counts on the PR, and - hand PR1 to the owner. -2. Push the showcase wrapper, produced by the three commands against - RobotCode2025Public, to `git@github.com:ccozianu/devcapsule-sample-frc-learning.git`. -3. Slice 2, after the owner's go at the second stopping point: Temurin 17 in the base under - the stable names, the session environment, the IntelliJ link, the acceptance run. +1. Record the full gate's counts on PR1 (#333) after the detection removal and hand it to the + owner. The showcase wrapper at `git@github.com:ccozianu/devcapsule-sample-frc-learning.git` + is regenerated with the final `wrap` and pushed. +2. Write `2026-11-03-design-project-capabilities.md` from amendment 7 and the owner's four + answers; stop there for the owner's reading. No further slice before it is ruled. +3. Slice 2, after the ruling and the owner's go at the second stopping point: Temurin 17 in + the base under the stable names, the session environment, the acceptance run. ## Open Threads diff --git a/engineering-docs/work-orders/2026-11-02-wrapped-projects.md b/engineering-docs/work-orders/2026-11-02-wrapped-projects.md index a685f8c7..9cca9c87 100644 --- a/engineering-docs/work-orders/2026-11-02-wrapped-projects.md +++ b/engineering-docs/work-orders/2026-11-02-wrapped-projects.md @@ -67,6 +67,19 @@ The owner ruled these on 2026-11-02. 5. **The pair.** Claude (Fable 5.1) designs and implements; Codex is the review partner under the Pair Review Loop as the local workflow file applies it. +Amended by the owner on 2026-11-02, in chat, after reading slice 1: + +6. **The launcher infers nothing from a foreign tree.** Detecting Gradle, or any build tool, special-cases + one ecosystem into the product and bakes in facts about someone else's tool that rot. `wrap` + takes what the developer names, `--require CAPABILITY` and `--java LINE`, and declares that. Item 2 + of the `project wrap` deliverable and the showcase's detection table are superseded; the showcase + command is `wrap --require java --java 17`. +7. **Higher-level project capabilities are the next design.** A project, wrapped or not, can be made + to do things: browse, build, test, debug, manage its development. Each is settled or unsettled; an + unsettled one is not an error but a standing task the status surfaces ("we can browse the code + but cannot build yet") and the agent takes up with the user. The `java` line of a source is an + early form of the build's environment. A design note on this precedes any further slice. + ## Deliverables ### The wrapped-source declaration @@ -88,9 +101,8 @@ manifest without losing it, and `project config show` reports it. 1. Adds the repository as a submodule at the path, the repository's name by default, with the embedded Git directory the capsule needs, so the submodule works from inside the capsule on the first run. -2. Detects what the source needs from what is in it. For the showcase: a Gradle wrapper and - GradleRIO mean Java; the GradleRIO version decides the JDK line. Unknown contents produce a - manifest the developer can complete with the ordinary `project config` commands, and say so. +2. Superseded by amendment 6: requires the capabilities the developer names and declares the Java + line the developer gives; infers nothing from the source. 3. Writes or extends the manifest and lock as `init` would: the required capabilities, the recommended IDE, the wrapped-source declaration. A second `wrap` adds a source to an existing manifest and reconciles the capabilities. From 136732e15d911bffb0f057a3bf87ad40aa8f6dc3 Mon Sep 17 00:00:00 2001 From: Costin Cozianu Date: Tue, 3 Nov 2026 00:31:58 +0000 Subject: [PATCH 13/15] Design project capabilities: operations, settled and unsettled Co-Authored-By: Claude Fable 5.1 --- .../2026-11-03-design-project-capabilities.md | 175 ++++++++++++++++++ .../CURRENT-STATUS.md | 5 +- 2 files changed, 178 insertions(+), 2 deletions(-) create mode 100644 engineering-docs/wip/2026-11-02-wrapped-projects/2026-11-03-design-project-capabilities.md diff --git a/engineering-docs/wip/2026-11-02-wrapped-projects/2026-11-03-design-project-capabilities.md b/engineering-docs/wip/2026-11-02-wrapped-projects/2026-11-03-design-project-capabilities.md new file mode 100644 index 00000000..9f7da3f4 --- /dev/null +++ b/engineering-docs/wip/2026-11-02-wrapped-projects/2026-11-03-design-project-capabilities.md @@ -0,0 +1,175 @@ +# Design: project capabilities, settled and unsettled + +Date: 2026-11-03. Status: for the owner's ruling; it answers amendment 7 of +[the work order](../../work-orders/2026-11-02-wrapped-projects.md) and the +Socratic exchange of 2026-11-02. Each section ends with the recommendation +and, where one exists, the alternative in a line. The four questions put to +the owner are answered here as recommendations, marked **Q1** to **Q4**. + +## 1. The floor and the ceiling + +At the minimum DevCapsule is a reproducible room: a base image, components, +possibly none, the source tree mounted, a persistent home, explicit host +boundaries, and something running inside, IntelliJ or vim or a shell. The +minimum promises the room and nothing about what happens in it. Nothing +below may make the vim case need one more declaration. + +At the maximum DevCapsule is a complete description of how work happens in a +project, such that a newcomer, human or agent, is productive on the first run +without asking anyone. Between the two lie layers, each optional: + +1. what is installed: components, versions, the lock; done; +2. how the project is operated: build, test, debug, browse, manage; this note; +3. how humans and agents work here: the workflow definition, records, + decisions, the console hand-off; partly built; +4. how capsules relate: wrappers, samples, the recursive dogfood; begun. + +## 2. Two kinds of capability, one word or two (Q1) + +A capability today names a tool the capsule must have: `java`, `node`, +`codex-agent`. What amendment 7 names is something the project can be made +to do, with the recipe and the environment it needs. The two relate: the +second needs the first and names it. + +Recommendation: keep the owner's word in prose, *a higher-level capability*, +and give it its own table and verb so no command is ambiguous: `[operations]` +in the manifest, `project operation` on the command line. A developer who +types `config require build` must get a clear refusal, not a tool named +`build`. Alternative: `[capabilities.project]` under the tools; rejected +because `capabilities.required` already means tools and the two would be +read together by every older launcher. + +## 3. The minimal set + +The owner's list, in the owner's order, and nothing added: + +| Operation | Settled means | +|---|---| +| `browse` | the code opens navigably in the IDE; for Gradle, the import happened; for vim, nothing to settle | +| `build` | the software builds, in the broad sense that covers packaging an interpreted project | +| `test` | the tests run, or the project says it has none, by choice | +| `debug` | a process, or a test, starts under the debugger | +| `manage` | how development is managed: branches, pull requests, validation | + +Every operation is either settled or unsettled. Unsettled is not an error. A +project may start with `browse` alone, an old project without today's +tooling, and the status says so: *we can browse the code but cannot build +yet*. That sentence is the agent's standing task, taken up with the user. + +## 4. The record + +One table per operation, per project, or per wrapped source when the project +wraps several: + +```toml +[operations.build] +command = "./gradlew build -x spotlessCheck" +directory = "." +environment = { JAVA_HOME = "/opt/java/17", PATH = "/opt/java/17/bin:$PATH" } +needs = ["java"] +settled = 2026-11-02 +proved-at = "3ea1eb0" + +[sources."RobotCode2025Public".operations.test] +command = "./gradlew test" +needs = ["java"] +settled = 2026-11-02 +proved-at = "3ea1eb0" +``` + +- `command`, `directory` (relative to the source, `.` by default) and + `environment` are the recipe. `needs` names the tool capabilities, which + must be required or offered by the project; the launcher refuses a recipe + whose needs the project does not declare. +- `settled` is the date the human accepted it, after a run that proved it; + `proved-at` is the source's revision at that run. An entry without + `settled` does not exist: a proposal lives in the dialogue, never in the + manifest, so the manifest never carries a guess (the lesson of the deleted + detection). +- **Q4**: keep the date and the revision, not the log. The run is + reproducible by the recipe itself; a log would rot and bloat the manifest. +- The `java` key on a source, invented in slice 1, becomes the build's + `environment` and is removed from `[sources]` before any release ships it. +- Unknown keys inside an entry are carried, as everywhere in schema 2. + +Recommendation: this shape. Alternative: one table of named commands without +state; rejected because the state is the whole point. + +## 5. What the status surfaces + +- `project info` and `config show` list every operation of every source with + `settled ` or `unsettled`, and one line of summary: *browse settled, + build unsettled, test unsettled*. +- The generated `AGENTS.md` carries a section *Unsettled* naming each one + and the standing instruction: find out with the user, from the source's + own files and the owner's notes, propose with evidence, settle only through + the command, write nothing into the source. +- The console shows the same list; a settlement is a decision it can hand + off. + +## 6. The commands + +```text +devcapsule project operation list [--source NAME] +devcapsule project operation settle NAME [--source NAME] --command CMD [--directory DIR] [--env VAR=VALUE]... [--needs CAPABILITY]... [--proved-at REVISION] +devcapsule project operation forget NAME [--source NAME] +devcapsule project operation run NAME [--source NAME] +``` + +`settle` writes the record through the one manifest writer after the +human's acceptance; the agent runs it when the human says yes, or the human +runs it. `run` executes the recipe inside the capsule with its environment, +so the human and the agent use one command and the proof is reproducible. +`run` is the only operation command the capsule runtime needs; the others +are owner commands. + +## 7. The discovery dialogue, the wrap workflow + +The first session of a wrapper, as the guidance directs it: + +1. The agent reads `AGENTS.md`: the sources, the unsettled operations, the + owner's notes. +2. For `build` first, it reads the source's own files, tries the build in a + scratch of the capsule, and brings the human the recipe with the run's + result, as a decision hand-off when the console is there, in chat + otherwise. +3. The human accepts, corrects or defers. Acceptance is the `settle` command. +4. Then `test`, `debug`, `browse`, `manage`, in whatever order the human + wants, or not at all. Deferred stays unsettled and visible. + +The owner's notes are the *extra instructions outside the source tree* of the +amendment: a section of the generated `AGENTS.md` between two markers that +regeneration preserves, so a human can write "the simulation needs a +display; skip it" once and every agent reads it. Alternative: a separate +notes file; rejected because the agent reads one file first and the notes +belong beside the rules. + +## 8. Browse and manage (Q2, Q3) + +**Q2**: `browse` belongs to the project. The project says what to import +(`[sources."X".operations.browse] gradle = "."`); the IDE component consumes +it, IntelliJ by linking the Gradle project, vim by ignoring it. Nothing is +written into the foreign tree. + +**Q3**: `manage` is the workflow definition where there is one, the +`[workflow]` table, and otherwise the project's own stated conventions: a +settled `manage` names the branch model, where pull requests go (the fork +rule of `[sources]` is part of it) and the validation command. For a learning +wrapper it is settled as *learn only; no branches, no pull requests*, which +is a legitimate answer, not an absence. + +## 9. Slices + +1. **The record and the commands.** `[operations]` read, written, listed; + `operation settle`, `forget`, `list`, `run`; the status surfaces; the + guidance's *Unsettled* section and the owner's notes; the `java` key + folded into `build`'s environment. No base change. +2. **The dialogue.** The console's decision hand-off for a settlement; the + first-session instruction in the guidance proven on the showcase inside a + capsule. +3. **The base and browse.** Temurin 17 under the stable names, the session + environment from the settled operations, the IntelliJ link; the former + slice 2, unchanged in substance. + +Each slice is one pull request with its Codex review. Slice 1 starts after +this note is ruled. diff --git a/engineering-docs/wip/2026-11-02-wrapped-projects/CURRENT-STATUS.md b/engineering-docs/wip/2026-11-02-wrapped-projects/CURRENT-STATUS.md index b414de5b..f7b75fc8 100644 --- a/engineering-docs/wip/2026-11-02-wrapped-projects/CURRENT-STATUS.md +++ b/engineering-docs/wip/2026-11-02-wrapped-projects/CURRENT-STATUS.md @@ -98,8 +98,8 @@ is these records or the workflow definition; whether the proving run's evidence 1. Record the full gate's counts on PR1 (#333) after the detection removal and hand it to the owner. The showcase wrapper at `git@github.com:ccozianu/devcapsule-sample-frc-learning.git` is regenerated with the final `wrap` and pushed. -2. Write `2026-11-03-design-project-capabilities.md` from amendment 7 and the owner's four - answers; stop there for the owner's reading. No further slice before it is ruled. +2. Done: `2026-11-03-design-project-capabilities.md` is written with the four questions answered + as recommendations; it waits for the owner's ruling. No further slice before it is ruled. 3. Slice 2, after the ruling and the owner's go at the second stopping point: Temurin 17 in the base under the stable names, the session environment, the acceptance run. @@ -117,4 +117,5 @@ is these records or the workflow definition; whether the proving run's evidence - [the work order](../../work-orders/2026-11-02-wrapped-projects.md): read first. - [the wrapped-source design](2026-11-02-design-wrapped-source.md): the manifest shape, the JDK mechanism, the IDE rule, the detection rules; ruled 2026-11-02. - [evidence/2026-11-02-pr1-brief-codex.md](evidence/2026-11-02-pr1-brief-codex.md): the review brief of PR1; open when reading PR1.1. +- [the project-capabilities design](2026-11-03-design-project-capabilities.md): operations, settled and unsettled, the record, the commands, the discovery dialogue; open for the owner's ruling. - `intake/` and `intake-dispositions.md`: the queue and its log; empty at opening. From da24fb1f8a26f5eee0189702a9d318a353aca624 Mon Sep 17 00:00:00 2001 From: Costin Cozianu Date: Tue, 3 Nov 2026 00:32:50 +0000 Subject: [PATCH 14/15] Hand PR1 to the owner with the final gate recorded Co-Authored-By: Claude Fable 5.1 --- CURRENT-STATUS.md | 2 +- .../wip/2026-11-02-wrapped-projects/CURRENT-STATUS.md | 8 ++++---- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/CURRENT-STATUS.md b/CURRENT-STATUS.md index a3aea31d..140053c7 100644 --- a/CURRENT-STATUS.md +++ b/CURRENT-STATUS.md @@ -19,7 +19,7 @@ coordination branch. Detailed state belongs in each linked status file. | `user-docs` | 2026-09-12 | Deliver V1 adopter documentation from first useful session through resuming work | paused 2026-09-28; 0.2.15 documentation merged in PR #151 and on docs-0.2.15; improvement list awaits the owner's decision | `ws-user-docs/first-session` | [workstream status](engineering-docs/wip/2026-09-12-user-docs/CURRENT-STATUS.md) | | `website` | 2026-09-16 | Deliver the website autonomy experiment: repository-owned landing/docs/blog content, independently developable website submodule, local preview and publishing mechanism | paused 2026-09-30; producer migration merged in PR #152 and the versioned documentation live; W04-C, W09-C, W11-C retained | `ws-website/contract-v1` | [workstream status](engineering-docs/wip/2026-09-16-website/CURRENT-STATUS.md) | | `capsule-webconsole` | 2026-10-09 | Serve a token-gated web console from every capsule: configuration, versions, info, live resources, later records and workflow state | active; work order accepted 2026-10-09; the first iteration, deliverables 1 and 2, is three stacked pull requests, #184, #186 and the runtime-and-base slice, each reviewed by the Codex pair; the owner merges | `ws-capsule-webconsole/first-slice` | [workstream status](engineering-docs/wip/2026-10-09-capsule-webconsole/CURRENT-STATUS.md) | -| `wrapped-projects` | 2026-11-02 | Wrap a foreign repository as a submodule of a small wrapper project and work on it in a capsule with three commands; FRC learning project first | active; PR1 (#333) reviewed and its PR1.1 merged 2026-11-02; the project-capabilities design note is next | `ws-wrapped-projects/wrap` | [workstream status](engineering-docs/wip/2026-11-02-wrapped-projects/CURRENT-STATUS.md) | +| `wrapped-projects` | 2026-11-02 | Wrap a foreign repository as a submodule of a small wrapper project and work on it in a capsule with three commands; FRC learning project first | active; PR1 (#333) complete and handed to the owner 2026-11-03; the project-capabilities design note awaits the owner's ruling | `ws-wrapped-projects/wrap` | [workstream status](engineering-docs/wip/2026-11-02-wrapped-projects/CURRENT-STATUS.md) | | `website` | 2026-09-16 | Deliver the website autonomy experiment: repository-owned landing/docs/blog content, independently developable website submodule, local preview and publishing mechanism | paused 2026-09-20 at owner request to switch to maintenance; experiment accepted, A−; blog integrated and published; content/parent-integration follow-ups remain | `ws-website/initial-cut`; renamed from `website/initial-cut`; preparation and backlog-handoff exceptions in status | [workstream status](engineering-docs/wip/2026-09-16-website/CURRENT-STATUS.md) | Paused and blocked workstreams remain open until they conclude successfully or diff --git a/engineering-docs/wip/2026-11-02-wrapped-projects/CURRENT-STATUS.md b/engineering-docs/wip/2026-11-02-wrapped-projects/CURRENT-STATUS.md index f7b75fc8..afb2c931 100644 --- a/engineering-docs/wip/2026-11-02-wrapped-projects/CURRENT-STATUS.md +++ b/engineering-docs/wip/2026-11-02-wrapped-projects/CURRENT-STATUS.md @@ -4,7 +4,7 @@ Mnemonic: `wrapped-projects` Start date: 2026-11-02 -State: active; PR1 (#333) reviewed, PR1.1 (#334) merged, detection removed at the owner's direction; gate running; the project-capabilities design note is next +State: active; PR1 (#333) complete at 0a131d69 and handed to the owner; the project-capabilities design note waits for the owner's ruling Definition read: WORKFLOW.md@d2ccbbe43dfa, WORKFLOW-LOCAL.md@65501b3407db @@ -95,9 +95,9 @@ is these records or the workflow definition; whether the proving run's evidence ## Next Resumable Task -1. Record the full gate's counts on PR1 (#333) after the detection removal and hand it to the - owner. The showcase wrapper at `git@github.com:ccozianu/devcapsule-sample-frc-learning.git` - is regenerated with the final `wrap` and pushed. +1. Done: the final gate on PR1 (#333) at 0a131d69, 2711 passed and the same 18 capsule-specific + failures as before, is on the PR; PR1 is the owner's to merge. The showcase wrapper is + regenerated with the final `wrap` and pushed (58d9219). 2. Done: `2026-11-03-design-project-capabilities.md` is written with the four questions answered as recommendations; it waits for the owner's ruling. No further slice before it is ruled. 3. Slice 2, after the ruling and the owner's go at the second stopping point: Temurin 17 in From 3f2986f0130295477aef5ed075dd4fe7d22b96ef Mon Sep 17 00:00:00 2001 From: Costin Cozianu Date: Tue, 3 Nov 2026 00:37:49 +0000 Subject: [PATCH 15/15] Hand the project-capabilities design to workflow-improvements Co-Authored-By: Claude Fable 5.1 --- CURRENT-STATUS.md | 2 +- .../2026-11-02-wrapped-projects/CURRENT-STATUS.md | 14 ++++++++------ 2 files changed, 9 insertions(+), 7 deletions(-) diff --git a/CURRENT-STATUS.md b/CURRENT-STATUS.md index 140053c7..07ec736c 100644 --- a/CURRENT-STATUS.md +++ b/CURRENT-STATUS.md @@ -19,7 +19,7 @@ coordination branch. Detailed state belongs in each linked status file. | `user-docs` | 2026-09-12 | Deliver V1 adopter documentation from first useful session through resuming work | paused 2026-09-28; 0.2.15 documentation merged in PR #151 and on docs-0.2.15; improvement list awaits the owner's decision | `ws-user-docs/first-session` | [workstream status](engineering-docs/wip/2026-09-12-user-docs/CURRENT-STATUS.md) | | `website` | 2026-09-16 | Deliver the website autonomy experiment: repository-owned landing/docs/blog content, independently developable website submodule, local preview and publishing mechanism | paused 2026-09-30; producer migration merged in PR #152 and the versioned documentation live; W04-C, W09-C, W11-C retained | `ws-website/contract-v1` | [workstream status](engineering-docs/wip/2026-09-16-website/CURRENT-STATUS.md) | | `capsule-webconsole` | 2026-10-09 | Serve a token-gated web console from every capsule: configuration, versions, info, live resources, later records and workflow state | active; work order accepted 2026-10-09; the first iteration, deliverables 1 and 2, is three stacked pull requests, #184, #186 and the runtime-and-base slice, each reviewed by the Codex pair; the owner merges | `ws-capsule-webconsole/first-slice` | [workstream status](engineering-docs/wip/2026-10-09-capsule-webconsole/CURRENT-STATUS.md) | -| `wrapped-projects` | 2026-11-02 | Wrap a foreign repository as a submodule of a small wrapper project and work on it in a capsule with three commands; FRC learning project first | active; PR1 (#333) complete and handed to the owner 2026-11-03; the project-capabilities design note awaits the owner's ruling | `ws-wrapped-projects/wrap` | [workstream status](engineering-docs/wip/2026-11-02-wrapped-projects/CURRENT-STATUS.md) | +| `wrapped-projects` | 2026-11-02 | Wrap a foreign repository as a submodule of a small wrapper project and work on it in a capsule with three commands; FRC learning project first | active; PR1 (#333) accepted by the owner 2026-11-03, awaiting merge; the project-capabilities design handed to workflow-improvements | `ws-wrapped-projects/wrap` | [workstream status](engineering-docs/wip/2026-11-02-wrapped-projects/CURRENT-STATUS.md) | | `website` | 2026-09-16 | Deliver the website autonomy experiment: repository-owned landing/docs/blog content, independently developable website submodule, local preview and publishing mechanism | paused 2026-09-20 at owner request to switch to maintenance; experiment accepted, A−; blog integrated and published; content/parent-integration follow-ups remain | `ws-website/initial-cut`; renamed from `website/initial-cut`; preparation and backlog-handoff exceptions in status | [workstream status](engineering-docs/wip/2026-09-16-website/CURRENT-STATUS.md) | Paused and blocked workstreams remain open until they conclude successfully or diff --git a/engineering-docs/wip/2026-11-02-wrapped-projects/CURRENT-STATUS.md b/engineering-docs/wip/2026-11-02-wrapped-projects/CURRENT-STATUS.md index afb2c931..0401865e 100644 --- a/engineering-docs/wip/2026-11-02-wrapped-projects/CURRENT-STATUS.md +++ b/engineering-docs/wip/2026-11-02-wrapped-projects/CURRENT-STATUS.md @@ -4,7 +4,7 @@ Mnemonic: `wrapped-projects` Start date: 2026-11-02 -State: active; PR1 (#333) complete at 0a131d69 and handed to the owner; the project-capabilities design note waits for the owner's ruling +State: active; PR1 (#333) complete and accepted by the owner 2026-11-03, awaiting merge; the project-capabilities design is handed to workflow-improvements by mail Definition read: WORKFLOW.md@d2ccbbe43dfa, WORKFLOW-LOCAL.md@65501b3407db @@ -98,10 +98,12 @@ is these records or the workflow definition; whether the proving run's evidence 1. Done: the final gate on PR1 (#333) at 0a131d69, 2711 passed and the same 18 capsule-specific failures as before, is on the PR; PR1 is the owner's to merge. The showcase wrapper is regenerated with the final `wrap` and pushed (58d9219). -2. Done: `2026-11-03-design-project-capabilities.md` is written with the four questions answered - as recommendations; it waits for the owner's ruling. No further slice before it is ruled. -3. Slice 2, after the ruling and the owner's go at the second stopping point: Temurin 17 in - the base under the stable names, the session environment, the acceptance run. +2. Done: the owner accepted PR1 as it stands on 2026-11-03 and ruled that the project-capabilities + design is an AI-workflow issue; it went to `workflow-improvements` by mail the same day + (`2026-11-03-wrapped-projects-project-capabilities.md`). No operations slice here until the + definition speaks and a work order comes back. +3. Slice 2, at the owner's go at the second stopping point: Temurin 17 in the base under the + stable names, the session environment from the settled facts, the acceptance run. ## Open Threads @@ -117,5 +119,5 @@ is these records or the workflow definition; whether the proving run's evidence - [the work order](../../work-orders/2026-11-02-wrapped-projects.md): read first. - [the wrapped-source design](2026-11-02-design-wrapped-source.md): the manifest shape, the JDK mechanism, the IDE rule, the detection rules; ruled 2026-11-02. - [evidence/2026-11-02-pr1-brief-codex.md](evidence/2026-11-02-pr1-brief-codex.md): the review brief of PR1; open when reading PR1.1. -- [the project-capabilities design](2026-11-03-design-project-capabilities.md): operations, settled and unsettled, the record, the commands, the discovery dialogue; open for the owner's ruling. +- [the project-capabilities design](2026-11-03-design-project-capabilities.md): operations, settled and unsettled, the record, the commands, the discovery dialogue; handed to `workflow-improvements` 2026-11-03, kept here for reference. - `intake/` and `intake-dispositions.md`: the queue and its log; empty at opening.