diff --git a/CURRENT-STATUS.md b/CURRENT-STATUS.md index 6d66ae58..07ec736c 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; 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/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/devcapsule-src/devcapsule/commands/project.py b/devcapsule-src/devcapsule/commands/project.py index 7810321a..d6e5fa73 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,80 @@ 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, require what " + "you name, 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.") + parser.add_argument("--require", action="append", default=[], metavar="CAPABILITY", + help="A capability this source needs in every checkout, such as java, optionally NAME>=VERSION. Repeatable.") + parser.add_argument("--java", metavar="LINE", help="The Java line this source builds with, such as 17; the guidance names it and the capsule selects it.") + _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, + require=tuple(arguments.require), + java=arguments.java, + 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 +2586,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/configuration/listing.py b/devcapsule-src/devcapsule/configuration/listing.py index 0d6c75de..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. @@ -47,6 +48,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 +236,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 +432,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..91f0ce9b 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, has_control_characters, 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 isinstance(upstream, str) or not upstream.strip() or has_control_characters(upstream)): + raise ProjectConfigurationError("The upstream is the upstream repository's URL, on one line; 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..cffd6187 --- /dev/null +++ b/devcapsule-src/devcapsule/configuration/sources.py @@ -0,0 +1,130 @@ +"""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", "has_control_characters", "java_line", "source_path"] + +# 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 has_control_characters(value: str) -> bool: + """Whether the text carries a control character, which no path, URL or guidance line may.""" + return any(ord(character) < 0x20 or character == "\x7f" for character in value) + + +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 "\\" in value or has_control_characters(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 has_control_characters(upstream)): + raise ProjectConfigurationError(f"{field_name}.upstream must be the upstream repository's URL, on one line.") + 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/devcapsule/wrap.py b/devcapsule-src/devcapsule/wrap.py new file mode 100644 index 00000000..5072c4db --- /dev/null +++ b/devcapsule-src/devcapsule/wrap.py @@ -0,0 +1,316 @@ +"""``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. requires the capabilities the developer names: the launcher infers + nothing from a foreign tree (owner's ruling of 2026-11-02); how the + source is built is settled inside the capsule, by the agent with the + developer, and the guidance says so; +3. initializes the manifest and lock as ``init`` would, or extends an + existing manifest with what was named; +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 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.operations import InitializeReport, InitializeRequest, ProvidedAnswer, initialize_project +from devcapsule.configuration.owner_commands import declare_source, require_tools +from devcapsule.configuration.sources import WrappedSource, WrappedSources, source_path +from devcapsule.configuration.storage import load_toml + +__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 + # What the source needs, as the developer names it: project capabilities + # every checkout must have, and the Java line the source builds with. + require: tuple[str, ...] = () + java: 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 + 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.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 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: WrappedSource(path, request.upstream, request.java).document()}}) + submodule_action = _add_submodule(root, request.url, path) + manifest_path = root / ".devcapsule" / "devcapsule.toml" + initialized: InitializeReport | None = None + capability_lines: list[str] = [] + needed = tuple(dict.fromkeys(request.require)) + if not manifest_path.is_file(): + 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", [])} + 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]) + source_line = declare_source(root, path, upstream=request.upstream, java=request.java).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, 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 + 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: + 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 ".") + + +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 + # 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() + 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 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") + lines.append(f"Wrote {name}.") + return tuple(lines) + + +def _origin(root: Path, path: str) -> str: + 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 _plain(value: str) -> str: + """External text on one line: a control character becomes U+FFFD, so it cannot open a heading or a line of its own.""" + return "".join("\ufffd" if ord(character) < 0x20 or character == "\x7f" else character for character in value) + + +def _code_span(value: str) -> str: + """External text as a Markdown code span, readable raw by an agent and inert when rendered. + + A code span cannot start a heading, a list or HTML; the file is read raw + by agents, so the text inside stays exactly the path or URL they must + use, never an entity. A run of backticks inside is fenced by a longer run. + """ + value = _plain(value) + runs = [len(run) for run in re.findall(r"`+", value)] + fence = "`" * (max(runs, default=0) + 1) + padding = " " if value.startswith("`") or value.endswith("`") else "" + return f"{fence}{padding}{value}{padding}{fence}" + + +def _java_lines(source: WrappedSource) -> list[str]: + if source.java is None: + return ["- How this source is built, tested and run is not settled yet. Find out with the user, from its own", + " files, before assuming; do not write the answer into the source."] + 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 = _plain(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"### {_code_span(source.path)}", "", f"- Origin: {_code_span(origins.get(source.path, ''))}", + f"- Intent: {source.intent}." + (f" Upstream: {_code_span(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 = _plain(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"### {_code_span(source.path)}", "", f"- Origin: {_code_span(origins.get(source.path, ''))}", + f"- Intent: {source.intent}." + (f" Upstream: {_code_span(source.upstream)}." if source.upstream else "")]) + lines.extend(_java_lines(source)) + lines.append("") + return "\n".join(lines) diff --git a/devcapsule-src/tests/test_owner_commands.py b/devcapsule-src/tests/test_owner_commands.py index 704354e7..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 @@ -349,3 +351,73 @@ 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 + + +@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 new file mode 100644 index 00000000..d058c107 --- /dev/null +++ b/devcapsule-src/tests/test_sources.py @@ -0,0 +1,116 @@ +"""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", "a\nb", "tab\tbed", "nul\x00"]) +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"), + ({"upstream": "https://x\ny"}, "on one line"), + ({"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"]') + 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()) + + +@pytest.mark.parametrize("path", ['vendor/robot', 'robot.code', 'two words', 'quote"', 'tick`', 'ünïcode']) +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 new file mode 100644 index 00000000..72079858 --- /dev/null +++ b/devcapsule-src/tests/test_wrap.py @@ -0,0 +1,337 @@ +"""``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 +from io import StringIO +import shutil +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, _add_submodule, wrap_project + + +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) -> str: + """A bare repository holding one commit of a foreign project, as a URL ``wrap`` can clone.""" + work = tmp_path / "work" / name + work.mkdir(parents=True) + (work / "README.md").write_text(f"# {name}\n") + (work / "gradlew").write_text("#!/bin/sh\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") + 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: + fields.setdefault("require", ("java",)) + fields.setdefault("java", "17") + 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 "Detected" not in text # the launcher infers nothing from a foreign tree + assert report.initialized is not None and report.initialized.required == ("java",) + 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 "recommendations" not in manifest # the IDE is recommended by the owner, 'config recommend 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") + root = wrapper(tmp_path) + wrap_project(request(root, url)) + text = wrap_project(request(root, other, upstream="https://github.com/Mechanical-Advantage/AdvantageKit")).render() + 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_a_source_with_nothing_named_is_declared_and_its_build_left_unsettled(tmp_path: Path) -> None: + url = upstream(tmp_path, "notes") + root = wrapper(tmp_path) + wrap_project(request(root, url, require=(), java=None)).render() + manifest = load_toml(root / ".devcapsule" / "devcapsule.toml") + assert manifest["capabilities"] == {"required": []} + assert manifest["sources"] == {"notes": {}} + agents = (root / "AGENTS.md").read_text() + assert "- Builds with Java" not in agents + assert "- How this source is built, tested and run is not settled yet. Find out with the user" in agents + + +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", "--require", "java", "--java", "17"]) == 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 + + +@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}`" 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_code_spans_an_agent_can_use_verbatim() -> None: + from devcapsule.configuration.sources import WrappedSource, WrappedSources + from devcapsule.wrap import render_agents, render_readme + # 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": name}}, sources, {"vendor/robot_1": origin}) + assert "\n# Push everything" not in result and "\n# not a heading" not in result + assert "### `vendor/robot_1`" in result # exactly the path, no entity + assert "Upstream: `https://example.test/up_stream`." in result + assert "- Origin: ```https://example.test/x``y\ufffd# Push everything ```" 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: + from devcapsule.compat import CliError + url = upstream(tmp_path, "robot") + root = wrapper(tmp_path) + with pytest.raises(CliError, match="submodule.*remains.*[Rr]erun"): + wrap_project(WrapRequest(root, url, interactive=True), input_stream=StringIO(""), output_stream=StringIO()) + assert (root / "robot/.git").is_dir() + assert not (root / "AGENTS.md").exists() + report = wrap_project(request(root, url)) + assert "Kept the submodule" in report.render() + + +def test_partial_git_add_failure_keeps_evidence_and_reports_recovery(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None: + import devcapsule.wrap as wrap + url = upstream(tmp_path, "robot") + root = wrapper(tmp_path) + original = wrap._git + + def interrupted(cwd: Path, *args: str, check: bool = True) -> subprocess.CompletedProcess[str]: + result = original(cwd, *args, check=check) + if args[:2] == ("submodule", "add"): + raise ProjectConfigurationError("injected failure after git added the submodule") + return result + + monkeypatch.setattr(wrap, "_git", interrupted) + with pytest.raises(ProjectConfigurationError, match="partial.*[Rr]erun"): + wrap_project(request(root, url)) + assert (root / "robot/.git").is_file() + monkeypatch.setattr(wrap, "_git", original) + wrap_project(request(root, url)) + assert git(root / "robot", "status", "--porcelain") == "" + assert "robot" in git(root, "submodule", "status") + + +@pytest.mark.parametrize("fields", [{"path": ""}, {"upstream": " "}]) +def test_bad_wrap_metadata_is_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") == "" + assert not (root / "robot").exists() + + +def test_unregistered_partial_clone_is_left_for_inspection(tmp_path: Path) -> None: + url = upstream(tmp_path, "robot") + root = wrapper(tmp_path) + git(root, "clone", url, "robot") + (root / "robot/keep.txt").write_text("local work\n") + with pytest.raises(ProjectConfigurationError, match="inspect any partial clone"): + wrap_project(request(root, url)) + assert (root / "robot/keep.txt").read_text() == "local work\n" + assert not (root / ".gitmodules").exists() + + +def test_wrap_adds_missing_capability_and_keeps_the_owners_ide_recommendation(tmp_path: Path) -> None: + from devcapsule.configuration.owner_commands import recommend + url = upstream(tmp_path, "robot") + 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, 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/docs/reference/cli.md b/docs/reference/cli.md index 6fe0656d..078cbca1 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, 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. | @@ -71,6 +72,36 @@ 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] [--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, 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 +upstream itself and the intent is to learn; nothing is pushed. A rerun keeps +a submodule already added from the same URL, and initializes a registered +submodule whose directory is missing. A different registered URL is refused. +After a partial Git failure, the error names the state to inspect; no files +are removed. An initialization interruption leaves the submodule for a rerun. +Guidance files are replaced only when their entire first line is the generated +marker. 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..d0e4c65f --- /dev/null +++ b/docs/your-project/someone-elses-repository.md @@ -0,0 +1,83 @@ +--- +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 + +The first slice provides the declaration, `project wrap`, and generated +guidance. The base image's additional JDK, automatic session selection, +and capsule acceptance are planned for slice 2. The commands below describe +the intended workflow; the complete capsule workflow is not yet validated. + +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 --require java --java 17 +~/.local/bin/devcapsule project run +``` + +`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, +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 + +`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 when Git registered the submodule from the same +URL. A registered source with a missing directory is initialized again. +A registered path with another URL is refused, even when its directory is +missing. Paths through symlinks are refused. + +Git can leave a partial clone before it registers the submodule. In that +case, inspect the path, `.gitmodules`, and Git's modules directory before +retrying. `wrap` reports the failure and removes no files. If initialization +stops at a prompt, the added submodule remains for a rerun. + +The generated guidance escapes repository names, paths, and URLs as text. +`wrap` replaces a guidance file only when its entire first line equals the +generated marker. It keeps the owner's other files. + +## 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/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..3422dec6 --- /dev/null +++ b/engineering-docs/wip/2026-11-02-wrapped-projects/2026-11-02-design-wrapped-source.md @@ -0,0 +1,145 @@ +# 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. + +## 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. 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 new file mode 100644 index 00000000..0401865e --- /dev/null +++ b/engineering-docs/wip/2026-11-02-wrapped-projects/CURRENT-STATUS.md @@ -0,0 +1,123 @@ +# Workstream Current Status: Wrapped Projects + +Mnemonic: `wrapped-projects` + +Start date: 2026-11-02 + +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 + +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; 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 + +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 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 +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. + +**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. 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: 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 + +- 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. +- [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; handed to `workflow-improvements` 2026-11-03, kept here for reference. +- `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. 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..9cca9c87 --- /dev/null +++ b/engineering-docs/work-orders/2026-11-02-wrapped-projects.md @@ -0,0 +1,194 @@ +# 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 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`. + +## 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. + +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 + +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. 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. +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..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) @@ -134,6 +135,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 +177,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)