base-cli 0.1.0__py3-none-any.whl

base_cli-0.1.0.dist-info/METADATA

@@ -0,0 +1,543 @@
+Metadata-Version: 2.2
+Name: base-cli
+Version: 0.1.0
+Summary: A small, consistent Python CLI framework for Base and Base-supported projects
+Author: Base Foundry
+License: Apache-2.0
+Project-URL: Homepage, https://github.com/basefoundry/base-cli
+Project-URL: Repository, https://github.com/basefoundry/base-cli
+Project-URL: Issues, https://github.com/basefoundry/base-cli/issues
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: click>=8.1
+Requires-Dist: PyYAML>=6.0
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: pytest>=8.0; extra == "dev"
+
+# `base-cli`
+
+`base-cli` is the PyPI distribution; import it in Python as `base_cli`.
+
+Install it with:
+
+```bash
+python -m pip install base-cli
+```
+
+Release builds, TestPyPI rehearsals, and protected PyPI publication are
+documented in [`docs/releasing.md`](docs/releasing.md). The package exposes
+`base_cli.__version__`, which matches the distribution version.
+
+The package is distributed under the Apache License 2.0. Base itself remains
+licensed separately under AGPL-3.0-or-later.
+
+`base_cli` is Base's small Python framework for writing command-line tools that
+feel consistent across Base and Base-supported projects.
+
+It is intentionally thin. Click still owns argument parsing and command
+execution, while `base_cli` adds the Base-specific behavior every project CLI
+should get by default:
+
+- standard command options such as `--debug`, `--quiet`, `--environment`,
+  `--config`, `--keep-temp`, and `--log-file`
+- structured logging to stderr and, by default, to a persistent per-run log file
+- Base project discovery through `base_manifest.yaml`
+- config loading with predictable precedence
+- per-run temp directories, persistent cache directories, and cleanup hooks
+- sensitive argument redaction in debug invocation logs
+- a command context object shared by command code and helper functions
+- test helpers built on Click's `CliRunner`
+
+## Design Goals
+
+Base CLI tools should be easy to write, but not magical. A command should be
+explicitly registered, receive an explicit `Context`, and use standard Python
+functions instead of import-time side effects.
+
+The package follows these rules:
+
+- **Decorator-driven setup**: commands opt in by creating an `App` and
+  decorating a function.
+- **Logs go to stderr**: user-facing program output can stay on stdout, while
+  logs remain redirectable and skippable.
+- **Every run has a context**: logs, paths, config, environment, manifest, and
+  cleanup are available through one object.
+- **No import-time filesystem writes**: state directories are created only when
+  a command runs.
+- **Base-aware, Click-compatible**: command authors keep using familiar Click
+  concepts such as options and arguments.
+
+## Public API
+
+The supported facade is `import base_cli`. It exports the command lifecycle
+(`App`, `Context`, `run_app`, decorators, and logging helpers), command filters,
+the structured command protocol helpers, and the user configuration types used
+by `Context.user_config`. The corresponding modules are also available as
+`base_cli.command_filters`, `base_cli.command_protocol`, and
+`base_cli.history`.
+
+Low-level implementation helpers are intentionally not included in the
+module `__all__` surfaces. Downstream code should use the documented facade or
+the explicitly supported symbols from those modules.
+
+## Minimal Command
+
+```python
+from __future__ import annotations
+
+import base_cli
+
+
+app = base_cli.App(name="hello", version="0.1.0")
+
+
+@app.command()
+@base_cli.option("--name", required=True)
+def main(ctx: base_cli.Context, name: str) -> None:
+    ctx.log.info("starting hello")
+    print(f"hello {name}")
+
+
+if __name__ == "__main__":
+    raise SystemExit(base_cli.run_app(app))
+```
+
+Running this command directly as a Python package automatically adds the
+standard Base options:
+
+```bash
+hello --name Ada
+hello --debug --name Ada
+hello --quiet --name Ada
+hello --environment prod --name Ada
+hello --keep-temp --name Ada
+hello --log-file /tmp/hello.log --name Ada
+```
+
+Long options with values use space-separated syntax. `base_cli.run_app()` rejects
+equals-form values such as `--name=Ada` before Click parses arguments.
+These are direct package options. Public `basectl` launchers expose `-v` for
+command-level debug logs and command-specific flags from
+`basectl <command> --help`; they do not expose `--debug`, `--quiet`,
+`--log-file`, `--config`, or `--environment` as public `basectl` options.
+The wrapper-level `basectl --keep-temp <command>` option preserves the
+complete temporary tree for that run.
+
+## Command Registration
+
+Use `App` when you want a named command:
+
+```python
+app = base_cli.App(name="base-projects", version="0.1.0")
+```
+
+Register the command function explicitly:
+
+```python
+@app.command()
+def main(ctx: base_cli.Context) -> None:
+    ...
+```
+
+The command function always receives `ctx` as its first argument. User-defined
+options and arguments are passed after the Base standard options have been
+removed from Click's keyword arguments.
+
+For small scripts, the module-level decorators are available:
+
+```python
+@base_cli.command()
+def main(ctx: base_cli.Context) -> None:
+    ...
+```
+
+In Base itself, prefer an explicit `App` so command names and versions are
+obvious at the top of the module.
+
+Use `@app.subcommand()` when one CLI needs multiple verbs while keeping Base's
+standard context, logging, redaction, and cleanup lifecycle for each invocation:
+
+```python
+app = base_cli.App(
+    name="workspace-tools",
+    version="0.1.0",
+    help="Inspect and sync workspace projects.",
+)
+
+
+@app.subcommand()
+@base_cli.argument("project")
+def status(ctx: base_cli.Context, project: str) -> None:
+    ctx.log.info("checking %s", project)
+
+
+@app.subcommand("sync")
+@base_cli.option("--dry-run", is_flag=True)
+def sync_project(ctx: base_cli.Context, dry_run: bool) -> None:
+    if ctx.dry_run:
+        ctx.log.info("previewing sync")
+```
+
+Subcommands use the same `base_cli.option()` and `base_cli.argument()` metadata
+as single commands. `App(help=...)` appears in the command group's `--help`
+output. For subcommand apps, prefer standard Base options before the subcommand
+name, for example `workspace-tools --debug status demo`. The post-subcommand
+form, such as `workspace-tools status --debug demo`, remains accepted for
+compatibility. Use either `@app.command()` for a single-command CLI or
+`@app.subcommand()` for a command group; do not mix the two registration styles
+on one `App`.
+
+## Options And Arguments
+
+`base_cli.option` and `base_cli.argument` mirror Click's decorators:
+
+```python
+@app.command()
+@base_cli.argument("project")
+@base_cli.option("--workspace", type=str)
+def main(ctx: base_cli.Context, project: str, workspace: str | None) -> None:
+    ...
+```
+
+Use `sensitive=True` for options whose values should not appear in invocation
+logs:
+
+```python
+@base_cli.option("--token", sensitive=True, required=True)
+def main(ctx: base_cli.Context, token: str) -> None:
+    ...
+```
+
+Both `--token secret` and an externally supplied `--token=secret` token are
+redacted in debug logs, even though Base command invocation rejects equals-form
+option values before Click parses them.
+
+Use `dry_run=True` when a nonstandard option should drive `ctx.dry_run` and
+Base's default durable-write suppression:
+
+```python
+@base_cli.option("--preview", is_flag=True, dry_run=True)
+def main(ctx: base_cli.Context, preview: bool) -> None:
+    if ctx.dry_run:
+        ctx.log.info("previewing changes")
+```
+
+The conventional `dry_run` parameter is recognized automatically, so commands
+using `@base_cli.option("--dry-run", is_flag=True)` do not need the marker.
+Only one option on a command may be marked `dry_run=True`; duplicate dry-run
+markers fail during command registration so authors do not accidentally ship an
+option that is ignored by `ctx.dry_run`.
+
+## Standard Options
+
+Every `base_cli.App` command gets these options:
+
+- `--debug`: enable DEBUG logging on the user-facing stderr stream.
+- `--quiet`, `-q`: suppress INFO logs on the user-facing stderr stream.
+- `--environment <name>`: set `ctx.environment` for the run.
+- `--config <path>`: merge an additional YAML config file.
+- `--keep-temp`: preserve the run's temp directory after command completion.
+- `--log-file <path>`: write the persistent log to a specific file.
+- `--version`: shown when the `App` was created with a version.
+
+The command receives only its own application-specific options. Standard options
+are consumed before the command function is called.
+
+## Exit Codes
+
+Use `base_cli.ExitCode` when command code or tests need to name Base's standard
+command result meanings:
+
+- `ExitCode.SUCCESS` (`0`): the command completed successfully.
+- `ExitCode.FAILURE` (`1`): the command was valid, but an operational problem
+  prevented successful completion.
+- `ExitCode.USAGE_ERROR` (`2`): the command could not proceed because user
+  input, configuration, or environment setup was invalid or incomplete.
+
+Existing commands can keep returning integers. New code should prefer the named
+constants when it makes intent clearer:
+
+```python
+if ctx.project_root is None:
+    ctx.log.error("run this command from a Base project")
+    return base_cli.ExitCode.USAGE_ERROR
+```
+
+## Context
+
+`Context` is the object command code should pass around instead of rediscovering
+Base paths or global settings.
+
+Important fields include:
+
+- `ctx.cli_name`: normalized CLI name used for state paths and logger names.
+- `ctx.run_id`: timestamp plus short random suffix for this invocation.
+- `ctx.base_home`: resolved `BASE_HOME`, when available.
+- `ctx.project_root`: directory containing the nearest `base_manifest.yaml`.
+- `ctx.workspace_root`: configured workspace root from `~/.base.d/config.yaml`.
+- `ctx.manifest_path`: nearest discovered Base manifest.
+- `ctx.history_scope`: compatibility scope marker; delegated children are not
+  written as separate history events.
+- `ctx.history_parent_run_id`: shared parent `basectl` invocation ID, when delegated.
+- `ctx.runtime_owner`: `base` or `project`.
+- `ctx.owner_root`: owner namespace root under the Base cache root.
+- `ctx.run_root`: this invocation's run bundle.
+- `ctx.state_dir`: owner root (compatibility alias).
+- `ctx.log_dir`: run-bundle log directory.
+- `ctx.cache_dir`: persistent component cache directory.
+- `ctx.temp_dir`: per-run temp directory inside the bundle.
+- `ctx.log_file`: the run's shared `logs/primary.log`, or `None` when persistent
+  logging is disabled.
+- `ctx.config`: merged configuration dictionary.
+- `ctx.user_config`: typed user configuration from `~/.base.d/config.yaml`.
+- `ctx.environment`: active environment, defaulting to `dev`.
+- `ctx.debug`: whether debug logging is enabled for the stderr stream.
+- `ctx.quiet`: whether INFO logs are suppressed on the stderr stream.
+- `ctx.dry_run`: whether the command is running in a no-durable-write mode.
+- `ctx.keep_temp`: whether `ctx.temp_dir` should survive cleanup.
+- `ctx.log`: standard Python logger configured by Base.
+
+Helpers can retrieve the active context without threading it through every call:
+
+```python
+from base_cli import get_current_context
+
+
+def helper() -> None:
+    ctx = get_current_context()
+    ctx.log.debug("helper is running")
+```
+
+`get_current_context()` is valid only while a `base_cli.App` command is running.
+
+## Logging
+
+`base_cli` configures two handlers:
+
+- a user-facing stderr handler at INFO by default, DEBUG with `--debug`, or
+  WARNING with `--quiet` / `-q`
+- a persistent file handler that records DEBUG logs when persistent logging is
+  enabled
+
+`--quiet` suppresses INFO output on the user-facing stream but still shows
+warnings and errors. `--debug` and `--quiet` cannot be used together. Persistent
+log files still receive DEBUG-level detail, including INFO messages suppressed
+from stderr. When `basectl --color` is used on a terminal, the user-facing
+Python logs use the same level colors as Bash logs; persistent log files remain
+plain text. `NO_COLOR` disables colors.
+
+Advanced tests and CI wrappers can call `base_cli.configure_logger(...,
+stream=..., formatter=...)` to capture user-facing logs or apply a custom
+formatter without replacing Base's logger setup. Leave those arguments as
+`None` to keep the default stderr stream and `BaseCliFormatter`. Base CLI log
+timestamps use the host's local timezone and include its numeric offset by
+default. When the wrapper sets `LOG_UTC=1` (for example via
+`basectl --utc-wrapper`), they use UTC and include an explicit `UTC` marker.
+
+This setting affects log presentation only. Run metadata, history records, and
+run IDs retain their canonical UTC representation.
+
+Commands that inspect runtime artifacts can use `base_cli.App(log_to_file=False)`
+to keep the standard context, `--debug`, and `--quiet` behavior without creating
+default `logs/`, `cache/`, or `tmp/<run-id>/` directories. `base_logs` uses this
+mode so `basectl logs` does not appear in its own output; `base_history` does
+the same for `basectl history`. An explicit `--log-file <path>` still enables
+file logging for that invocation.
+
+Commands running with `ctx.dry_run` also skip default `logs/`, `cache/`, and
+`tmp/<run-id>/` creation. Passing `--log-file <path>` still writes to that
+explicit file so tests and diagnostics can inspect dry-run logs when needed.
+
+For Python-backed commands with persistent logs, `base_cli.App` also writes a
+best-effort final history record to `<base-cache-root>/base/history/runs.jsonl`.
+History records contain redacted command metadata, timing, exit status, project
+context when known, and a pointer to the raw log file. History writes are local
+only and do not fail the user command when the index cannot be updated.
+
+High-frequency tools can set `base_cli.App(max_log_files=<count>)` to keep at
+most that many default persistent log files across the owner's run bundles.
+Retention runs during startup after the current run's default log file is
+resolved, and the current run's log file is never pruned. The policy is skipped
+for `ctx.dry_run`,
+`log_to_file=False`, and explicit `--log-file` paths so no-durable-write modes
+and caller-selected log locations stay under caller control. Use this as a
+small guardrail for busy local tools; `basectl clean` remains the broader
+maintenance command for caches, logs, and retained temp files.
+
+Logs use the same general shape as Base Bash logs:
+
+```text
+2026-05-26 12:34:56 INFO    path/to/file.py:42 message
+```
+
+Use either `ctx.log` directly:
+
+```python
+ctx.log.info("processed %s items", count)
+```
+
+or the convenience functions:
+
+```python
+base_cli.log_debug("cache_dir=%s", ctx.cache_dir)
+base_cli.log_info("done")
+base_cli.log_warning("using fallback")
+base_cli.log_error("failed")
+```
+
+Program output should still use stdout when another command might consume it.
+Logs should stay on stderr so users can redirect or ignore logs without losing
+the real command output.
+
+## Config Precedence
+
+Configuration is loaded from YAML files and environment variables in this order:
+
+1. user config: `~/.base.d/config.yaml`
+2. project config: `<project>/.base/config.yaml`
+3. explicit config from `--config`
+4. environment variables
+5. direct command-line standard options
+
+Environment variables currently recognized by the config layer:
+
+- `BASE_CLI_ENVIRONMENT`
+- `BASE_CLI_LOG_LEVEL`
+- `BASE_CLI_KEEP_TEMP`
+
+`LOG_DEBUG=1` or `LOG_DEBUG=true` is also accepted as an internal compatibility
+fallback for wrapper/debug paths when `BASE_CLI_LOG_LEVEL` is unset. Prefer
+`BASE_CLI_LOG_LEVEL=debug` for user-facing Python CLI debug logging.
+
+Command-line standard options are applied after config is loaded. For example,
+`--environment prod` overrides `environment: dev` from config.
+
+`ctx.config` exposes the merged raw configuration after user, project,
+explicit, and environment layers are applied. `ctx.user_config` exposes only the
+typed machine-local user config, including `workspace.root`,
+`workspace.manifest`, and IDE
+preferences, so command code does not need to re-read `~/.base.d/config.yaml`
+for those structured values.
+
+The user config file is machine-local by default. Base owns the semantics of
+`~/.base.d/config.yaml`, while users own backup and sync choices such as iCloud,
+chezmoi, dotfiles repositories, Time Machine, or manual copy. See
+`docs/local-config.md` for the product-level boundary.
+
+## Project Discovery
+
+When a command runs, `base_cli` walks upward from the current working directory
+looking for `base_manifest.yaml`.
+
+If found:
+
+- `ctx.manifest_path` points to the manifest
+- `ctx.project_root` points to the manifest's parent directory
+
+If no manifest is found, both fields are `None`. Commands that require a Base
+project should validate this explicitly and return a clear usage error or
+actionable message.
+
+## Runtime Directories
+
+Runtime state is rooted at `~/Library/Caches/base` on macOS and `~/.cache/base`
+elsewhere. `BASE_CACHE_DIR` overrides the root. See
+[`docs/cache-ownership-and-layout.md`](../../../docs/cache-ownership-and-layout.md)
+for the owner-aware layout. Base control-plane commands use `base/`; a
+Base-compliant project's own commands use `projects/<project>/<checkout-id>/`.
+Each invocation is a run bundle containing private (`0600`) `run.json`,
+`logs/`, and `tmp/`,
+while persistent component caches live in the owner's `cache/components/`.
+`basectl clean --older-than <age>` removes old bundles and component caches;
+`--keep-last <count>` retains the newest completed bundles per owner.
+
+Use `ctx.on_cleanup()` for cleanup work that should happen even when helper code
+does not own the main command wrapper:
+
+```python
+def close_connection() -> None:
+    connection.close()
+
+
+ctx.on_cleanup(close_connection)
+```
+
+Cleanup hooks run before temp directory removal. Hook failures are logged as
+warnings and do not prevent later hooks from running.
+
+## Testing
+
+Use `base_cli.testing.invoke` for unit tests:
+
+```python
+from pathlib import Path
+
+from base_cli.testing import invoke
+
+
+def test_command(tmp_path: Path) -> None:
+    project = tmp_path / "project"
+    project.mkdir()
+
+    result = invoke(
+        app,
+        ["--name", "Ada"],
+        home=tmp_path,
+        cwd=project,
+        manifest={"project": {"name": "demo"}, "artifacts": []},
+    )
+
+    assert result.exit_code == 0
+    assert "hello Ada" in result.stdout
+```
+
+The helper wraps Click's `CliRunner`, sets `HOME` when requested, supplies
+`cwd` to Base's context discovery without mutating process-global cwd, and keeps
+stderr separate on Click versions that support it. Use `cwd` for commands whose
+behavior depends on project discovery, including tests that intentionally run
+outside a Base project. Pass
+`manifest={...}` with `cwd` to write a temporary `base_manifest.yaml` before
+the command runs.
+
+When `home` is supplied, `invoke()` also defaults `BASE_CACHE_DIR` to
+`<home>/.cache/base` so helper-based tests do not inherit a developer's real
+cache root. Pass `env={"BASE_CACHE_DIR": str(path)}` when a test needs an
+explicit cache location.
+
+## When To Use `base_cli`
+
+Use `base_cli` for Python commands that are part of Base or a Base-supported
+project and need standard Base behavior.
+
+Base public command engines under `cli/python/base_*/engine.py` should
+instantiate `base_cli.App` so standard options, logging, redaction, runtime
+state, and local command history stay consistent. If a future public Python
+engine intentionally bypasses this lifecycle, document the reason in code and
+in this guide, then add it as an explicit lifecycle-audit exemption. Shell-only
+helpers that avoid Python startup, such as `basectl config path`, do not create
+Python logs or history records; once a `basectl` path enters a Python command
+package, it should participate in `base_cli.App`.
+
+It is a good fit for:
+
+- project discovery commands
+- setup and artifact management commands
+- developer workflow commands
+- CLIs that need predictable logs, temp directories, and config precedence
+
+It is not meant to replace Click, Typer, argparse, or rich terminal UI
+frameworks. It is the Base layer around command lifecycle, context, logging,
+configuration, and state.

base_cli-0.1.0.dist-info/RECORD

@@ -0,0 +1,22 @@
+base_cli/__init__.py,sha256=QJY2CEfaVDF50rNdCzB2LjO5o9O8j46JhJGjmV6SSEI,2465
+base_cli/_runtime.py,sha256=VhxeIfl8GMIEOIBvu2k7ZIm4XG4TdMm00xCLwDHuJBc,2677
+base_cli/app.py,sha256=0gELgIMJsX7Px5nIRd_kophLUEy2IwTl31cTU4io2P0,20363
+base_cli/command_filters.py,sha256=BnOfEThw5LvEp06lv2PZXLHFWDposGy1qeOA9tqvKBo,1285
+base_cli/command_protocol.py,sha256=GG7bggxoDqF9VA2rfK8uShhIFI2vdg2Ii7gk5ZVp7-w,9929
+base_cli/config.py,sha256=fTz_QH_s_R-DWOv_NksoJln2EoeyN7fsd-cq-R50VlM,9525
+base_cli/context.py,sha256=Mb_xiemnUiZXTCaczaFkN-0MFzPCPTLC-th4_N565NM,3561
+base_cli/exit_codes.py,sha256=eVHoCtFbZJ10KfbOSIQfHl8HZGiWFYyFdg58EblArIU,159
+base_cli/history.py,sha256=_7FKNZZ9I0sRCDtpxsG1igVw_-ryZZzGcvDcoZc66gw,13513
+base_cli/ide_schema.py,sha256=jJH2ZVbBASinXWhedHrQ8P-eF_XNXeso1oJJ9kXKZKI,2192
+base_cli/inspection.py,sha256=I1LMvspXelTdqEXuFlf9-62OHJ5qYU_aPPiK82JV-j8,1191
+base_cli/logging.py,sha256=kwICbRyXwqzlaWMvNd5T03vpvSvzbO2Q56Fq3m1lSVs,5728
+base_cli/output.py,sha256=bJPrrbfUzdbvSjxG51RW0yG1reifkG63ISFoC9a4Eow,6838
+base_cli/paths.py,sha256=nZm6OMQdSgRVS0i33cAmyu1TW-x9ywT12plmgKg24kA,3978
+base_cli/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+base_cli/redaction.py,sha256=qoASJ6KccGTABA0Ao7hYAGMUDJJuqhFgtQ9T7Hyztz0,1591
+base_cli/testing.py,sha256=NmV6PYYa34iqQLlvfVzu5ZIEp4oXoGBmoC3vcf2u0fw,1923
+base_cli-0.1.0.dist-info/LICENSE,sha256=ZzMAmMf8LNaj3S2uxM7wg7fenYafjBwfHeTeOyBTikY,10328
+base_cli-0.1.0.dist-info/METADATA,sha256=LMqiWfR9GLsafhLzgymcndKInzmiCtXWgaRnFaDtUDw,20714
+base_cli-0.1.0.dist-info/WHEEL,sha256=beeZ86-EfXScwlR_HKu4SllMC9wUEj_8Z_4FJ3egI2w,91
+base_cli-0.1.0.dist-info/top_level.txt,sha256=IvAvZRcOvOpPR7McHaJ9xdAgOjoQgkddkQMnR5vs-O8,9
+base_cli-0.1.0.dist-info/RECORD,,

base_cli-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (76.1.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

base_cli-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+base_cli