Seed CLI layer scaffold

CHANGELOG.md

@@ -10,3 +10,4 @@ All notable changes to Base Platform Tools will be documented in this file.
 - Added the Base-managed project manifest and validation contract.
 - Added the tooling boundary documentation.
 - Added the initial GitHub Actions validation workflow.
+- Added the initial CLI layout for future Bash and Python platform tools.

CONTRIBUTING.md

@@ -60,6 +60,39 @@ 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.
 
+## CLI Layout
+
+Use the seeded CLI layout for new tools:
+
+- `bin/` contains thin public launchers only.
+- `cli/bash/commands/<tool>/` contains Bash command implementations.
+- `cli/python/base_platform_tools/<tool>/` contains Python command packages.
+- `base_manifest.yaml` declares commands that Base can run with
+  `basectl run base-platform-tools <command>`.
+
+Do not copy `basectl` or `base-wrapper` into this repository. Base owns those
+entrypoints. Base Platform Tools reuses them through manifest-declared commands
+and thin launchers.
+
+Python launchers should invoke:
+
+```bash
+"$BASE_HOME/bin/base-wrapper" \
+  --project "${BASE_PROJECT:-base-platform-tools}" \
+  base_platform_tools.<tool> "$@"
+```
+
+When a Python launcher needs this repository's package root, prepend
+`$repo_root/cli/python` to `PYTHONPATH` before calling `base-wrapper`.
+
+Bash tools that need the Base runtime may use:
+
+```bash
+#!/usr/bin/env basectl
+```
+
+and should keep their implementation under `cli/bash/commands/<tool>/`.
+
 ## Validation
 
 Run:

README.md

@@ -27,8 +27,9 @@ The boundary is intentional:
 
 ## Current Status
 
-This repository is in its initial scaffold stage. It does not yet contain
-production utility CLIs.
+This repository is in its initial scaffold stage. It has the initial CLI layout
+for future Bash and Python tools, but 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
@@ -61,6 +62,12 @@ Or through Base:
 basectl test base-platform-tools
 ```
 
+List the commands declared by this repository:
+
+```bash
+basectl run base-platform-tools --list
+```
+
 ## What Belongs Here
 
 Good candidates for this repository include:
@@ -92,8 +99,19 @@ Keep these outside Base Platform Tools:
 
 ```text
 .
+├── bin/
+│   └── README.md
 ├── base_manifest.yaml
+├── cli/
+│   ├── README.md
+│   ├── bash/
+│   │   └── README.md
+│   └── python/
+│       ├── README.md
+│       └── base_platform_tools/
+│           └── __init__.py
 ├── docs/
+│   ├── cli-layout.md
 │   └── tooling-boundary.md
 ├── tests/
 │   └── validate.sh
@@ -103,6 +121,8 @@ Keep these outside Base Platform Tools:
 └── 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.
+Future tools should live under the seeded CLI structure, with per-tool
+subdirectories added when the first real tool is migrated or created.
+
+See [CLI Layout](docs/cli-layout.md) for the command structure and launcher
+conventions.

base_manifest.yaml

@@ -7,4 +7,5 @@ test:
   command: tests/validate.sh
 
 commands:
+  cli-check: tests/validate.sh
   validate: tests/validate.sh

bin/README.md

@@ -0,0 +1,35 @@
+# Public Launchers
+
+This directory is reserved for thin public launcher scripts.
+
+Base Platform Tools does not provide its own `basectl` or `base-wrapper`.
+Launchers in this directory should delegate through the Base installation that
+is already managing the workspace.
+
+## Python Launcher Pattern
+
+Use this shape for a Python tool when a public executable is useful:
+
+```bash
+#!/usr/bin/env bash
+
+repo_root="$(cd "$(dirname "$0")/.." && pwd -P)" || exit 1
+
+: "${BASE_HOME:?BASE_HOME is required. Run through basectl run or basectl activate.}"
+
+PYTHONPATH="$repo_root/cli/python${PYTHONPATH:+:$PYTHONPATH}"
+export PYTHONPATH
+
+exec "$BASE_HOME/bin/base-wrapper" \
+  --project "${BASE_PROJECT:-base-platform-tools}" \
+  base_platform_tools.<tool> "$@"
+```
+
+The launcher stays small. The behavior belongs under
+`cli/python/base_platform_tools/<tool>/`.
+
+## Bash Launcher Pattern
+
+Most Bash tools can be exposed directly through `base_manifest.yaml` without a
+public launcher. If a public launcher is useful, keep it small and delegate to
+the implementation under `cli/bash/commands/<tool>/`.

cli/README.md

@@ -0,0 +1,27 @@
+# CLI Layer
+
+This directory contains command implementations for Base Platform Tools.
+
+Base owns `basectl` and `base-wrapper`. This repository owns optional tool
+implementations that Base can orchestrate through `base_manifest.yaml`.
+
+Use this layout:
+
+```text
+cli/
+├── bash/
+│   └── commands/
+│       └── <tool>/
+│           ├── <tool>.sh
+│           ├── README.md
+│           └── tests/
+└── python/
+    └── base_platform_tools/
+        └── <tool>/
+            ├── __init__.py
+            ├── __main__.py
+            ├── engine.py
+            └── tests/
+```
+
+See `docs/cli-layout.md` for launcher and manifest conventions.

cli/bash/README.md

@@ -0,0 +1,30 @@
+# Bash Tools
+
+Bash tools belong under:
+
+```text
+cli/bash/commands/<tool>/<tool>.sh
+```
+
+When a Bash tool needs the Base runtime, use:
+
+```bash
+#!/usr/bin/env basectl
+
+main() {
+    ...
+}
+
+main "$@"
+```
+
+Expose runnable Bash tools through `base_manifest.yaml`:
+
+```yaml
+commands:
+  example: cli/bash/commands/example/example.sh
+```
+
+Keep Bash tools focused on shell-native orchestration. Move structured parsing,
+state modeling, and non-trivial data transformations into Python unless shell is
+clearly the better substrate.

cli/python/README.md

@@ -0,0 +1,37 @@
+# Python Tools
+
+Python tools belong under the `base_platform_tools` package:
+
+```text
+cli/python/base_platform_tools/<tool>/
+  __init__.py
+  __main__.py
+  engine.py
+  tests/
+```
+
+Use package execution as the public Python contract:
+
+```bash
+base_platform_tools.<tool>
+```
+
+Thin launchers should set this repository's Python source root and then invoke
+Base's wrapper:
+
+```bash
+PYTHONPATH="$repo_root/cli/python${PYTHONPATH:+:$PYTHONPATH}"
+export PYTHONPATH
+
+exec "$BASE_HOME/bin/base-wrapper" \
+  --project "${BASE_PROJECT:-base-platform-tools}" \
+  base_platform_tools.<tool> "$@"
+```
+
+The wrapper selects the `base-platform-tools` project virtual environment from
+`~/.base.d/base-platform-tools/.venv` unless Base overrides
+`BASE_PROJECT_VENV_DIR` for tests or project execution.
+
+Python modules should keep import-time behavior cheap and side-effect free.
+Command packages should expose a `main(argv) -> int` function and raise
+`SystemExit(main())` from `__main__.py`.

cli/python/base_platform_tools/__init__.py

@@ -0,0 +1 @@
+"""Python package namespace for Base Platform Tools command implementations."""

docs/cli-layout.md

@@ -0,0 +1,139 @@
+# CLI Layout
+
+Base Platform Tools provides optional tool implementations for Base-managed
+workspaces. It reuses Base for orchestration and Python environment selection.
+
+Do not copy `basectl` or `base-wrapper` into this repository.
+
+## Ownership
+
+| Concern | Owner |
+| --- | --- |
+| Workspace orchestration | Base |
+| `basectl` control plane | Base |
+| `base-wrapper` Python execution wrapper | Base |
+| Optional platform tools | Base Platform Tools |
+| Tool command declarations | `base_manifest.yaml` in this repository |
+
+## Directory Structure
+
+```text
+bin/
+  <tool>                         # optional thin launchers
+
+cli/
+  bash/
+    commands/
+      <tool>/
+        <tool>.sh
+        README.md
+        tests/
+
+  python/
+    base_platform_tools/
+      <tool>/
+        __init__.py
+        __main__.py
+        engine.py
+        tests/
+```
+
+Create only the directories that a real tool needs. The top-level scaffold
+exists to make the expected shape clear before production tools are added.
+
+## Manifest Commands
+
+Expose tools through `base_manifest.yaml` so Base can list and run them:
+
+```yaml
+commands:
+  example-bash: cli/bash/commands/example-bash/example-bash.sh
+  example-python: bin/example-python
+```
+
+Run them with:
+
+```bash
+basectl run base-platform-tools example-bash
+basectl run base-platform-tools example-python
+```
+
+Use `--` to pass tool-specific arguments:
+
+```bash
+basectl run base-platform-tools example-python -- --format json
+```
+
+## Bash Tools
+
+Bash tools that need the Base runtime should use:
+
+```bash
+#!/usr/bin/env basectl
+
+main() {
+    ...
+}
+
+main "$@"
+```
+
+The command implementation should live under:
+
+```text
+cli/bash/commands/<tool>/<tool>.sh
+```
+
+Prefer Bash for shell-native orchestration and small wrappers. Prefer Python
+for structured parsing, data modeling, provider clients, reporting, and logic
+that needs focused unit tests.
+
+## Python Tools
+
+Python tools should run as packages under `base_platform_tools`:
+
+```text
+cli/python/base_platform_tools/<tool>/
+  __init__.py
+  __main__.py
+  engine.py
+```
+
+Use this launcher shape when a Python tool needs a public executable:
+
+```bash
+#!/usr/bin/env bash
+
+repo_root="$(cd "$(dirname "$0")/.." && pwd -P)" || exit 1
+
+: "${BASE_HOME:?BASE_HOME is required. Run through basectl run or basectl activate.}"
+
+PYTHONPATH="$repo_root/cli/python${PYTHONPATH:+:$PYTHONPATH}"
+export PYTHONPATH
+
+exec "$BASE_HOME/bin/base-wrapper" \
+  --project "${BASE_PROJECT:-base-platform-tools}" \
+  base_platform_tools.<tool> "$@"
+```
+
+This does two things:
+
+1. Adds this repository's `cli/python` directory to `PYTHONPATH`.
+2. Delegates interpreter selection to Base's `base-wrapper`, using the
+   `base-platform-tools` project virtual environment.
+
+Base's wrapper adds Base's own Python libraries. The launcher adds this
+repository's Python package root.
+
+## Tests
+
+Each tool should have focused tests near the implementation:
+
+```text
+cli/bash/commands/<tool>/tests/
+cli/python/base_platform_tools/<tool>/tests/
+```
+
+Wire the useful test command into `base_manifest.yaml` when the tool is ready.
+The repository-level `tests/validate.sh` should stay a lightweight contract
+check for the whole repo.