diff --git a/README.md b/README.md index 807b78d3..3d345c96 100644 --- a/README.md +++ b/README.md @@ -37,6 +37,21 @@ Common first-run and product questions are answered in [FAQ.md](FAQ.md). Contributions should follow [CONTRIBUTING.md](CONTRIBUTING.md). Release notes are tracked in [CHANGELOG.md](CHANGELOG.md). +## Source Control And Forge Support + +Base assumes Git. Mercurial, Perforce, Subversion, and other non-Git SCMs are +out of scope. + +Base is GitHub-primary rather than forge-independent. GitHub is the only +first-class forge automation target today for repository creation, +configuration, Issues, pull requests, Projects, Actions intake, and release +publishing. A GitLab, Bitbucket, internal Git, or local Git repository can +still use Base's local project loop once it is checked out locally and declares +`base_manifest.yaml`. + +See [Source Control And Forge Support](docs/source-control-and-forge-support.md) +for the command-by-command compatibility contract and non-GitHub Git workflow. + ## Start Here ### Choose An Install Path @@ -491,11 +506,14 @@ repositories are errors, missing optional repositories are warnings, and Base-managed projects outside the manifest stay visible as warnings. Use `basectl workspace clone --manifest `, or configure -`workspace.manifest`, to materialize the missing required repositories from that -manifest. The command keeps existing repositories visible, delegates each -repository operation to `basectl repo clone`, and supports `--dry-run` for a -no-write preview. Optional repositories are reported but skipped unless -`--include-optional` is supplied. +`workspace.manifest`, to materialize the missing required GitHub repositories +from that manifest. The command keeps existing repositories visible, delegates +each repository operation to `basectl repo clone`, and supports `--dry-run` for +a no-write preview. Optional repositories are reported but skipped unless +`--include-optional` is supplied. Workspace manifests may list non-GitHub Git +URLs for reporting, but automatic materialization through `workspace clone` is +GitHub-only today; clone GitLab, Bitbucket, internal Git, or local repositories +with ordinary Git first, then let Base discover the local checkout. Use `basectl workspace init ` for first-run bootstrap from a workspace configuration repository. The source can be a local path, GitHub URL, @@ -555,6 +573,10 @@ Without `--path`, `repo clone` writes to `/`, and URL without touching the filesystem. Existing matching checkouts are treated as already satisfied; conflicting destinations fail with guidance. +`repo clone` and `repo configure` are GitHub automation surfaces. For +non-GitHub Git repositories, use the forge's normal Git clone path and then use +Base's local project loop from the resulting checkout. + Check and repair the repo baseline with: ```bash diff --git a/docs/README.md b/docs/README.md index c92a08dc..adb97ece 100644 --- a/docs/README.md +++ b/docs/README.md @@ -55,6 +55,9 @@ reference. The filename should answer "what is this about?" manifest contract, command tables, and file locations. - [Architecture](architecture.md) describes Base's product direction, command model, environment model, manifest shape, and repository conventions. +- [Source Control And Forge Support](source-control-and-forge-support.md) + defines Base's Git-only, GitHub-primary support contract and the expected + behavior for non-GitHub Git repositories. - [First-Mile Bootstrap](bootstrap.md) documents `bootstrap.sh`, install mode selection, handoff commands, and contributor setup. - [Clean macOS Install Validation](macos-install-validation.md) defines the diff --git a/docs/architecture.md b/docs/architecture.md index ec2a1658..481d1828 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -8,11 +8,14 @@ multiple projects through a single CLI interface. The current implementation sup contract is macOS. Linux is a future design target, while Windows support is not in scope. -The governing philosophy: **solve your own problem elegantly first**. Base is built for -a specific workflow — multiple peer GitHub repositories under a shared parent directory, -each declaring their dependencies through a simple manifest, all managed through a -unified interface. If it works well for its author, it will work well for others with -similar constraints. +The governing philosophy: **solve your own problem elegantly first**. Base is +built for a specific workflow: multiple peer Git repositories under a shared +parent directory, each declaring their dependencies through a simple manifest, +all managed through a unified interface. GitHub is the first-class forge +automation target today. Non-GitHub Git repositories can still use Base's local +project loop after they exist locally, but GitHub workflow automation remains +GitHub-specific. The exact contract lives in +[Source Control And Forge Support](source-control-and-forge-support.md). --- @@ -57,8 +60,8 @@ need Base's orchestration model. ## Repository Structure -Base is a public GitHub repository. All projects managed by Base are also GitHub -repositories, checked out as peers under a shared parent directory: +Base is a public GitHub repository. The primary dogfood workspace is a set of +GitHub repositories checked out as peers under a shared parent directory: ``` ~/work/ ← shared workspace root @@ -68,8 +71,10 @@ repositories, checked out as peers under a shared parent directory: banyanlabs/ ← peer project with base_manifest.yaml ``` -Base discovers peer repositories by scanning the workspace root for repositories -that contain `base_manifest.yaml`. +Base discovers peer repositories by scanning the workspace root for Git +repositories that contain `base_manifest.yaml`. The local project loop does not +require the remote to be hosted on GitHub. Repository creation, configuration, +issue, pull-request, Project, and release automation do require GitHub today. --- diff --git a/docs/command-reference.md b/docs/command-reference.md index 90c5abeb..18c03214 100644 --- a/docs/command-reference.md +++ b/docs/command-reference.md @@ -13,6 +13,19 @@ syntax. `--config`, `--environment`, and `--keep-temp` are private to Python package execution and are rejected by `basectl`. +## Source Control And Forge Boundary + +Base assumes Git as the source-control system. Non-Git SCMs such as Mercurial, +Perforce, and Subversion are out of scope. + +Base is GitHub-primary today. Local project commands work for non-GitHub Git +repositories once they are checked out locally and declare `base_manifest.yaml`. +Repository creation, cloning, configuration, issue, pull-request, Project, and +release automation are GitHub-specific unless a command explicitly says +otherwise. See +[Source Control And Forge Support](source-control-and-forge-support.md) for the +full compatibility contract. + ## Install And Bootstrap | Command | What it does | Important flags | @@ -67,13 +80,17 @@ inspect the resolved command contract first. | `basectl workspace status` | Show read-only workspace project status and latest recorded project check dates. Uses `workspace.manifest` from user config unless `--manifest` is supplied. | `--workspace `, `--manifest `, `--format ` | | `basectl workspace check` | Run read-only checks across workspace projects. Uses `workspace.manifest` from user config unless `--manifest` is supplied. | `--workspace `, `--manifest `, `--format ` | | `basectl workspace doctor` | Run read-only diagnostics across workspace projects. Uses `workspace.manifest` from user config unless `--manifest` is supplied. | `--workspace `, `--manifest `, `--format ` | -| `basectl workspace clone` | Clone or validate expected repositories from a workspace manifest. Uses `workspace.manifest` from user config unless `--manifest` is supplied. | `--workspace `, `--manifest `, `--include-optional`, `--dry-run` | +| `basectl workspace clone` | Clone or validate expected repositories from a workspace manifest. Missing-repository materialization is GitHub-only today because this path delegates to `repo clone`. Uses `workspace.manifest` from user config unless `--manifest` is supplied. | `--workspace `, `--manifest `, `--include-optional`, `--dry-run` | | `basectl workspace pull` | Explicitly fetch and validate a canonical workspace manifest source before updating the local workspace manifest. Uses `workspace.manifest_source` and `workspace.manifest` from user config unless flags are supplied. | `--source `, `--manifest `, `--dry-run` | | `basectl workspace init ` | Initialize a workspace from a workspace configuration repository, update local workspace config, and optionally materialize member repositories. | `--owner `, `--path `, `--workspace `, `--manifest `, `--include-optional`, `--dry-run` | | `basectl workspace configure` | Apply the existing `repo configure` repair path across discovered Base-managed workspace repositories or an explicit workspace manifest. Skips missing, non-Base-managed, or non-GitHub repos and continues after per-repo failures. | `--workspace `, `--manifest `, `--dry-run` | ## Repository And GitHub Workflow +This section is intentionally GitHub-specific except for local baseline +inspection. Use ordinary Git to clone non-GitHub repositories, then use the +daily project loop commands from the local checkout. + | Command | What it does | Important flags | |---|---|---| | `basectl repo init ` | Create a Base-managed repository baseline, including `.github/base-project.yml`, and optionally create/configure the GitHub repo. | `--path `, `--repo `, `--description `, `--copyright-holder `, `--public`, `--private`, `--pr`, `--project `, `--project-owner <login>`, `--project-schema <schema>`, `--copy-project-fields-from <title>`, `--initiative-option <name>`, `--no-configure`, `--no-project`, `--no-protect-default-branch`, `--dry-run` | diff --git a/docs/source-control-and-forge-support.md b/docs/source-control-and-forge-support.md new file mode 100644 index 00000000..a2b02fc0 --- /dev/null +++ b/docs/source-control-and-forge-support.md @@ -0,0 +1,115 @@ +# Source Control And Forge Support + +Base is Git-based and GitHub-primary. + +This page is the canonical contract for what that means. It separates the local +Base project loop, which is mostly forge-neutral once a Git checkout exists, +from the repository workflow automation that intentionally targets GitHub +today. + +## Support Contract + +Base assumes Git as the underlying source-control system. + +Supported source-control baseline: + +- Git repositories checked out on the local machine. +- Direct-child repository layouts under a shared workspace root. +- Project metadata declared through `base_manifest.yaml`. +- Git remotes hosted by GitHub, GitLab, Bitbucket, an internal Git server, or a + local filesystem remote when the command only needs ordinary Git behavior. + +Out of scope: + +- Mercurial. +- Perforce. +- Subversion. +- Fossil. +- Other non-Git SCMs. + +GitHub is the only first-class forge automation target today. Base can automate +GitHub repository creation and configuration, GitHub Issues, pull requests, +Projects, Actions-based intake, and GitHub Releases. It does not currently +provide equivalent automation for GitLab, Bitbucket, Azure DevOps, or other Git +forges. + +## Command Compatibility + +| Command area | Non-GitHub Git behavior | +|---|---| +| Local project loop: `projects list`, `setup`, `check`, `doctor`, `activate`, `run`, `test`, `build`, `demo`, `export-context` | Supported once the repository exists locally and has `base_manifest.yaml`. These commands use local files, project manifests, and ordinary process execution. | +| Git update: `update [project]` | Supported for ordinary Git checkouts when the repo is on its default branch and the worktree is clean enough for Base's update guardrails. | +| Remote diagnostics: `check [project]`, `doctor [project]` | Supported. Non-GitHub remotes are reported as non-GitHub providers and do not require GitHub CLI authentication. Optional network checks use Git reachability rather than forge APIs. | +| Workspace reports: `workspace status`, `workspace check`, `workspace doctor` | Supported. Workspace manifests can list GitLab, Bitbucket, internal Git, or local repository URLs as metadata for reporting. | +| Workspace manifest refresh: `workspace pull` | Supported for local paths, `file://` URLs, and raw `https://` manifest files. It updates the manifest file only; it does not clone or mutate project repositories. | +| Repository materialization: `repo clone`, `workspace clone`, `workspace init` when cloning repositories | GitHub-only today. These paths delegate to GitHub repository specs and should fail clearly when asked to materialize unsupported non-GitHub repositories. | +| Repository baseline: `repo init`, `repo check` | Local baseline files can be created and checked without GitHub, but the standard Base baseline is GitHub-flavored: `.github` workflows, pull request template, and Project intake files are part of that contract. | +| Repository automation: `repo configure`, `workspace configure` | GitHub-specific. `workspace configure` skips non-GitHub repositories, while `repo configure` requires an explicit or inferable GitHub repository. | +| GitHub workflow: `gh ...` | GitHub-specific by name and behavior. | +| Release publishing: `release publish` | GitHub Release publishing today. Release readiness commands also expect the manifest's current GitHub release metadata. | +| Documentation shortcut: `docs` | Opens the GitHub-hosted Base documentation entry point. | + +## Non-GitHub Git Workspaces + +A GitLab, Bitbucket, internal Git, or local Git repository can still use Base's +local control-plane loop: + +1. Clone the repository with the normal Git tooling for that forge. +2. Place the checkout under `workspace.root`, or pass `--workspace <path>` when + inspecting a different root. +3. Add a valid `base_manifest.yaml`. +4. Use `basectl projects list`, `basectl setup <project>`, + `basectl check <project>`, `basectl doctor <project>`, + `basectl test <project>`, `basectl run <project> <command>`, and related + local project commands. + +Workspace manifests may include non-GitHub Git URLs so reports can describe +the expected repository set. Today, those URLs are metadata for read-only +workspace reporting unless the materialization command explicitly documents +support for that URL shape. If a missing GitLab or Bitbucket repository needs +to be cloned, clone it manually with Git, then let Base discover and diagnose +the local checkout. + +Avoid these commands unless GitHub is intentionally part of the repository +workflow: + +- `basectl repo clone` +- `basectl repo configure` +- `basectl workspace clone` +- `basectl workspace init` when it must clone repositories +- `basectl workspace configure` +- `basectl gh ...` +- `basectl release publish` + +## Future Forge Support + +GitLab and Bitbucket are viable future support targets, but they should not be +added speculatively. The current product strategy is to prove the GitHub-first +model through real adoption before Base grows provider adapters. + +If adoption proves the need, the right direction is a narrow forge-provider +boundary rather than scattered conditional logic. Likely adapter seams include: + +- remote provider detection +- repository clone and creation +- issue and merge-request or pull-request workflows +- project or board metadata +- release publishing +- CI or workflow intake + +Each provider should be added because a real workspace needs it, not because +Base wants to present itself as generally forge-independent. + +## Clean Failure Expectations + +GitHub-specific commands should not make a non-GitHub Git repository look +broken. They should either: + +- skip that repository with an explicit non-GitHub explanation, +- fail with a direct "GitHub-only today" message, or +- point the user to the manual Git workflow when Base can still operate on the + resulting local checkout. + +The user should be able to distinguish "this repository is unhealthy" from +"this command is a GitHub automation surface and this repository uses another +forge." diff --git a/docs/superpowers/plans/2026-07-01-forge-support-boundaries.md b/docs/superpowers/plans/2026-07-01-forge-support-boundaries.md new file mode 100644 index 00000000..6734e9d0 --- /dev/null +++ b/docs/superpowers/plans/2026-07-01-forge-support-boundaries.md @@ -0,0 +1,103 @@ +# Forge Support Boundaries Implementation Plan + +> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. + +**Goal:** Document Base's Git-only and GitHub-primary support contract so non-GitHub Git users get predictable guidance instead of implicit assumptions. + +**Architecture:** Add one canonical support-boundary page and link existing command and workspace docs to it. Keep this PR documentation-focused; defer provider adapters or new GitLab/Bitbucket behavior until GitHub-first adoption proves the need. + +**Tech Stack:** Markdown, existing docs map, existing Base validation commands. + +--- + +### Task 1: Add The Canonical Support Contract + +**Files:** +- Create: `docs/source-control-and-forge-support.md` +- Modify: `docs/README.md` +- Modify: `docs/architecture.md` + +- [ ] **Step 1: Create the support-boundary page** + +Add `docs/source-control-and-forge-support.md` with these sections: + +```markdown +# Source Control And Forge Support + +## Support Contract + +## Command Compatibility + +## Non-GitHub Git Workspaces + +## Future Forge Support + +## Clean Failure Expectations +``` + +The page must state that Git is required, non-Git SCMs are out of scope, GitHub is first-class today, and GitLab/Bitbucket support is deferred until adoption proves the need. + +- [ ] **Step 2: Link the page from the docs map** + +Add a Core Documents or Feature And Boundary Documents bullet in `docs/README.md` pointing to the new page. + +- [ ] **Step 3: Update architecture wording** + +Modify `docs/architecture.md` so the overview keeps the GitHub-primary product loop but points readers to the support-boundary page for exact non-GitHub behavior. + +### Task 2: Correct Command And Workspace Documentation + +**Files:** +- Modify: `README.md` +- Modify: `docs/command-reference.md` +- Modify: `docs/workspace-manifest.md` + +- [ ] **Step 1: Add the product-front-door summary** + +Add a short README section explaining that Base is Git-based, GitHub-primary, and still useful for local non-GitHub Git projects through the local command loop. + +- [ ] **Step 2: Clarify command-reference categories** + +Add a short compatibility note near the command tables in `docs/command-reference.md`, and make GitHub-only commands explicit where the table could otherwise imply forge independence. + +- [ ] **Step 3: Fix workspace manifest clone wording** + +Adjust `docs/workspace-manifest.md` so `repos[].url` remains generic metadata for reporting, while current `basectl workspace clone` support is documented as GitHub-only when materializing missing repositories. + +### Task 3: Validate And Publish + +**Files:** +- Validate all touched docs and existing tests. + +- [ ] **Step 1: Run focused docs validation** + +Run: + +```bash +env -u BASE_HOME PYTHONPATH=lib/python:cli/python \ + "$HOME/.base.d/base/.venv/bin/python" -m pytest \ + tests/test_base_cli_docs.py tests/test_contract_hardening.py -q +``` + +Expected: all selected tests pass. + +- [ ] **Step 2: Run full Base validation** + +Run: + +```bash +env -u BASE_HOME BASE_BASH_LIBS_DIR=/Users/rameshhp/work/base-bash-libs/lib/bash BASE_CACHE_DIR=/private/tmp/base-1344-final ./bin/base-test +``` + +Expected: Python suite and Bats/source suite pass. + +- [ ] **Step 3: Commit and open the PR** + +Commit with: + +```bash +git add README.md docs/README.md docs/architecture.md docs/command-reference.md docs/source-control-and-forge-support.md docs/workspace-manifest.md docs/superpowers/plans/2026-07-01-forge-support-boundaries.md +git commit -m "Document forge support boundaries" +``` + +Push `documentation/1344-20260701-forge-support-boundaries` and open a PR linked to issue `#1344`. diff --git a/docs/workspace-manifest.md b/docs/workspace-manifest.md index 4cf118fc..d2e0ffa3 100644 --- a/docs/workspace-manifest.md +++ b/docs/workspace-manifest.md @@ -69,11 +69,14 @@ missing required and optional repositories, and discovered Base-managed projects outside the manifest. `basectl workspace clone --manifest <path>` uses the expected repository list -as an explicit clone plan. It clones missing required repositories by default, -reports missing optional repositories without cloning them, and includes -optional repositories only with `--include-optional`. Existing repositories are -checked through `basectl repo clone` so matching checkouts are treated as -already satisfied and conflicts stay visible. +as an explicit clone plan. It clones missing required GitHub repositories by +default, reports missing optional repositories without cloning them, and +includes optional repositories only with `--include-optional`. The current +materialization path delegates to `basectl repo clone`, so GitLab, Bitbucket, +internal Git, and local repository URLs are accepted as manifest metadata for +read-only reports but are not automatically cloned by this command today. Clone +non-GitHub repositories with ordinary Git first, then let Base discover the +local checkout. ## Design Goal @@ -88,8 +91,8 @@ It should let Base answer: - which expected repositories are missing - which discovered repositories are outside the expected set - which repositories are required versus optional -- what clone URL and default branch should be shown or used by explicit clone - commands +- what clone URL and default branch should be shown in reports, and what + GitHub clone target should be used by explicit clone commands Each repository still owns its own `base_manifest.yaml`. The workspace manifest must not duplicate project setup, test, run, activation, demo, or health @@ -129,12 +132,18 @@ guidance. `repos[].name` is the local directory name under the workspace root and the stable identifier used in reports. -`repos[].url` is optional v1 metadata for a Git clone URL. The -`basectl workspace clone` command supports HTTPS, SSH, Git protocol, -SCP-style SSH, `file://`, and absolute local path repository sources. It -otherwise falls back to `repos[].name` when no URL is provided. Cleartext -`http://` repository URLs are rejected by default. Base does not parse -credentials or manage authentication. +`repos[].url` is optional v1 metadata for a Git clone URL. Manifest validation +accepts HTTPS, SSH, Git protocol, SCP-style SSH, `file://`, and absolute local +path repository sources so workspace reports can describe GitHub, GitLab, +Bitbucket, internal Git, and local repositories. Cleartext `http://` +repository URLs are rejected by default. Base does not parse credentials or +manage authentication. + +The current `basectl workspace clone` implementation only materializes GitHub +repositories because it delegates to `basectl repo clone`. Non-GitHub URLs +remain useful metadata for status, check, and doctor output, but users should +clone those repositories with ordinary Git until Base grows provider-specific +clone support. `repos[].default_branch` is advisory metadata for reports and future clone validation. It should default to the remote's default branch when omitted, but @@ -194,8 +203,9 @@ they are not workspace manifest source URLs. ## Trust And Authentication -Base should delegate repository authentication to Git, SSH, and the GitHub CLI. -It should not store, read, print, or manage credentials. +Base should delegate repository authentication to Git and SSH. GitHub-specific +commands also delegate to the GitHub CLI. Base should not store, read, print, +or manage credentials. Remote workspace manifest sources should use HTTPS. Cleartext HTTP is rejected by default because a workspace manifest controls expected repositories and @@ -204,7 +214,7 @@ needed, it should use an explicit opt-in rather than making HTTP ordinary configuration. Workspace manifest validation may check that clone URLs are syntactically -present. Network reachability, SSH key readiness, and GitHub authentication +present. Network reachability, SSH key readiness, and forge authentication belong in explicit check or doctor behavior, not in passive parsing. ## Existing Repositories