Bootstrap Base Platform Tools repository

.github/pull_request_template.md

@@ -0,0 +1,19 @@
+## Summary
+
+-
+
+## Issue
+
+Closes #
+
+## Validation
+
+-
+
+## Platform Support
+
+-
+
+## Notes
+
+-

.github/workflows/tests.yml

@@ -0,0 +1,16 @@
+name: Tests
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  validate:
+    name: Repository validation
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Run validation
+        run: tests/validate.sh

.gitignore

@@ -0,0 +1,10 @@
+.DS_Store
+.base/
+.venv/
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.coverage
+dist/
+build/
+*.egg-info/

CHANGELOG.md

@@ -0,0 +1,12 @@
+# Changelog
+
+All notable changes to Base Platform Tools will be documented in this file.
+
+## [Unreleased]
+
+### Added
+
+- Added the initial public repository scaffold for Base Platform Tools.
+- Added the Base-managed project manifest and validation contract.
+- Added the tooling boundary documentation.
+- Added the initial GitHub Actions validation workflow.

CONTRIBUTING.md

@@ -0,0 +1,77 @@
+# Contributing To Base Platform Tools
+
+Base Platform Tools is a developer tooling repository for optional platform,
+SRE, infrastructure, cloud, monitoring, diagnostics, and operational utilities.
+
+Contributions should keep the repository focused on tools that Base can
+orchestrate without expanding Base core.
+
+## Workflow
+
+1. Start from a GitHub issue.
+2. Create a dedicated worktree for each pull request.
+3. Use a branch name in this format:
+
+   ```text
+   <category>/<issue>-<YYYYMMDD>-<slug>
+   ```
+
+   Example:
+
+   ```text
+   enhancement/42-20260606-kube-diagnostics
+   ```
+
+4. Keep each pull request scoped to one issue.
+5. Include validation output in the pull request body.
+6. Link the issue with a closing keyword such as `Closes #42`.
+
+## Pull Request Template
+
+Every pull request should cover:
+
+- Summary
+- Issue
+- Validation
+- Platform Support
+- Notes
+
+For tool changes, include the supported platforms explicitly. If a tool does not
+support a platform, document why.
+
+## Tool Standards
+
+A tool belongs here only when it supports platform engineering, SRE,
+infrastructure, cloud, monitoring, diagnostics, or operational workflows.
+
+Each tool should:
+
+- have a clear operational purpose
+- avoid printing, storing, or logging secrets
+- expose deterministic command behavior suitable for automation
+- keep stdout reserved for command output
+- send diagnostics to stderr
+- provide tests for meaningful behavior
+- document supported platforms
+- fail clearly on unsupported platforms
+- be callable through a manifest-declared Base command when appropriate
+
+Prefer portable implementations when practical, but do not hide platform
+limitations. A useful macOS/Linux/WSL-only tool is acceptable when the limitation
+is explicit.
+
+## Validation
+
+Run:
+
+```bash
+tests/validate.sh
+```
+
+When working from a Base-managed workspace, also run:
+
+```bash
+basectl test base-platform-tools
+```
+
+Use more specific tests once real tool implementations are added.

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ramesh Padmanabhaiah
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -1,2 +1,108 @@
-# base-platform-tools
-Optional platform engineering, SRE, infrastructure, cloud, monitoring, and operational utility tools for Base-managed workspaces.
+# Base Platform Tools
+
+Base Platform Tools is the home for optional platform engineering, SRE,
+infrastructure, cloud, monitoring, diagnostics, and operational utility CLIs
+that can be used inside Base-managed workspaces.
+
+This repository exists so the core Base product can stay focused on workstation
+orchestration while platform-specific tools can evolve independently.
+
+## Relationship To Base
+
+Base owns the workstation control plane:
+
+- project discovery
+- setup, check, doctor, test, run, demo, and activation contracts
+- manifest parsing and validation
+- workspace and repository conventions
+- cross-platform support for macOS, Linux, WSL, and eventually native Windows
+
+Base Platform Tools owns optional utility commands that support platform,
+infrastructure, SRE, cloud, monitoring, and operational workflows.
+
+The boundary is intentional:
+
+> Base orchestrates the workspace. Base Platform Tools provides optional tools
+> that Base can orchestrate.
+
+## Current Status
+
+This repository is in its initial scaffold stage. It does not yet contain
+production utility CLIs.
+
+The existing `caff` and `sort` utilities remain in `codeforester/base` for now.
+They can be migrated here later through separate issues and pull requests once
+this repository baseline is stable.
+
+## Getting Started
+
+Clone this repository next to Base:
+
+```bash
+git clone https://github.com/codeforester/base-platform-tools.git
+```
+
+When Base is installed and the workspace is configured, this project should be
+discoverable through:
+
+```bash
+basectl projects list
+```
+
+Run the repository validation directly:
+
+```bash
+tests/validate.sh
+```
+
+Or through Base:
+
+```bash
+basectl test base-platform-tools
+```
+
+## What Belongs Here
+
+Good candidates for this repository include:
+
+- cloud inventory and reporting tools
+- Kubernetes and container platform diagnostics
+- monitoring and alerting helpers
+- incident-response utilities
+- infrastructure drift checks
+- platform runbook automation
+- operational data collection tools
+
+Each tool should have a clear operational purpose, documented platform support,
+tests, and a manifest-declared command when it is ready for Base orchestration.
+
+## What Does Not Belong Here
+
+This repository should not become a generic script collection.
+
+Keep these outside Base Platform Tools:
+
+- Base core orchestration behavior
+- project-specific application logic
+- one-off personal scripts
+- utilities without tests or a documented operational use case
+- commands that require secret values to be printed, stored, or logged
+
+## Repository Layout
+
+```text
+.
+├── base_manifest.yaml
+├── docs/
+│   └── tooling-boundary.md
+├── tests/
+│   └── validate.sh
+├── CHANGELOG.md
+├── CONTRIBUTING.md
+├── LICENSE
+└── README.md
+```
+
+Future tools should live under a structure that matches their implementation
+language and operational domain. The exact layout should be introduced when the
+first real tool is migrated or added.

base_manifest.yaml

@@ -0,0 +1,10 @@
+schema_version: 1
+
+project:
+  name: base-platform-tools
+
+test:
+  command: tests/validate.sh
+
+commands:
+  validate: tests/validate.sh

docs/tooling-boundary.md

@@ -0,0 +1,94 @@
+# Tooling Boundary
+
+Base Platform Tools exists to keep optional infrastructure and operations
+utilities separate from Base core.
+
+## Core Principle
+
+Base is the workstation orchestration layer. Base Platform Tools is an optional
+tooling layer that Base can orchestrate.
+
+This means:
+
+- Base should remain small, portable, and cross-platform.
+- Tools should live here when they are useful but not required for Base itself.
+- Projects should declare tool usage through their own Base manifests when the
+  tool is part of that project's workflow.
+
+## Base Owns
+
+Base owns behavior that is required to manage a developer workstation and its
+participating project repositories:
+
+- bootstrap and setup orchestration
+- project discovery
+- project manifests
+- check, doctor, test, run, demo, and activate contracts
+- shell and profile integration
+- repo baseline conventions
+- cross-platform substrate support
+
+## Base Platform Tools Owns
+
+Base Platform Tools owns optional commands in the platform engineering and
+operations space:
+
+- cloud management helpers
+- cloud inventory and reporting tools
+- Kubernetes and container diagnostics
+- monitoring and alerting helpers
+- incident-response commands
+- infrastructure drift checks
+- runbook automation
+- platform diagnostics and reporting
+
+These tools may have different platform support than Base itself.
+
+## Platform Support Policy
+
+Base should aim for macOS, Linux, WSL, and eventually native Windows support.
+
+Tools in this repository may support a narrower set of platforms when they have
+honest reasons to do so. Each tool should document its supported platforms and
+fail clearly when invoked on an unsupported platform.
+
+Recommended support labels:
+
+- `macos`
+- `linux`
+- `wsl`
+- `windows`
+
+Unsupported platforms should include a short reason.
+
+## Migration Policy
+
+Existing simple utilities such as `caff` and `sort` remain in `codeforester/base`
+until this repository baseline is stable.
+
+When a utility moves here:
+
+1. Open a dedicated issue.
+2. Move the implementation and tests.
+3. Add or update documentation.
+4. Add a manifest-declared command when appropriate.
+5. Decide whether Base needs a temporary compatibility note or shim.
+6. Update Base documentation to point to this repository.
+
+Do not migrate tools opportunistically in unrelated changes.
+
+## Admission Checklist
+
+A new tool is a good fit when it answers yes to most of these:
+
+| Question | Expected answer |
+| --- | --- |
+| Does it support platform, infrastructure, SRE, cloud, monitoring, diagnostics, or operations work? | Yes |
+| Is it useful across more than one project? | Yes |
+| Can it be tested locally or with a deterministic fixture? | Yes |
+| Can it avoid printing or storing secrets? | Yes |
+| Can it declare supported platforms clearly? | Yes |
+| Is it outside Base's workstation orchestration responsibility? | Yes |
+
+If the answer is no, the tool probably belongs in a project repository or in
+Base core, depending on the behavior.