Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions CURRENT-STATUS.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
1 change: 1 addition & 0 deletions REQUIREMENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down
93 changes: 76 additions & 17 deletions devcapsule-src/devcapsule/commands/project.py
Original file line number Diff line number Diff line change
Expand Up @@ -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"),
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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,
Expand Down
13 changes: 13 additions & 0 deletions devcapsule-src/devcapsule/configuration/listing.py
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down Expand Up @@ -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,
Expand Down Expand Up @@ -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))
Expand Down Expand Up @@ -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]:
Expand Down
10 changes: 5 additions & 5 deletions devcapsule-src/devcapsule/configuration/manifest_document.py
Original file line number Diff line number Diff line change
Expand Up @@ -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_]*$")
Expand Down
18 changes: 15 additions & 3 deletions devcapsule-src/devcapsule/configuration/manifest_schemas.py
Original file line number Diff line number Diff line change
Expand Up @@ -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"]
Expand All @@ -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})
Expand Down Expand Up @@ -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")
Expand Down Expand Up @@ -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`
Expand All @@ -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)
Expand All @@ -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:
Expand All @@ -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 {},
Expand All @@ -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})
Expand All @@ -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:
Expand Down
Loading
Loading