strictcli 0.1.0__tar.gz

strictcli-0.1.0/.claude/settings.json

@@ -0,0 +1,3 @@
+{
+  "hooks": {}
+}

strictcli-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,21 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        # requires-python: >= 3.11
+        python-version: ["3.12", "3.13", "3.14"]
+    steps:
+      - uses: actions/checkout@v6
+      - uses: astral-sh/setup-uv@v7
+      - run: uv python install ${{ matrix.python-version }}
+      - run: uv sync
+      - run: uv run python -c "import strictcli"

strictcli-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,30 @@
+name: Publish
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+  id-token: write
+
+jobs:
+  pypi:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: astral-sh/setup-uv@v7
+      - run: uv build
+      - uses: pypa/gh-action-pypi-publish@release/v1
+
+  npm:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-node@v6
+        with:
+          node-version: 24
+          registry-url: https://registry.npmjs.org
+      - run: npm publish --provenance --access public
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

strictcli-0.1.0/.gitignore

@@ -0,0 +1,15 @@
+node_modules/
+__pycache__/
+*.pyc
+*.log
+.DS_Store
+coverage/
+dist/
+*.egg-info/
+.rlsbl-notes-*.tmp
+.rlsbl/lock
+.credentials.json
+.*-cache.json
+.env
+.env.local
+*.local-only

strictcli-0.1.0/.rlsbl/bases/.claude/settings.json

@@ -0,0 +1,3 @@
+{
+  "hooks": {}
+}

strictcli-0.1.0/.rlsbl/bases/.github/workflows/ci.yml

@@ -0,0 +1,21 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        # requires-python: >= 3.11
+        python-version: ["3.12", "3.13", "3.14"]
+    steps:
+      - uses: actions/checkout@v6
+      - uses: astral-sh/setup-uv@v7
+      - run: uv python install ${{ matrix.python-version }}
+      - run: uv sync
+      - run: uv run python -c "import strictcli"

strictcli-0.1.0/.rlsbl/bases/.github/workflows/publish.yml

@@ -0,0 +1,30 @@
+name: Publish
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+  id-token: write
+
+jobs:
+  pypi:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: astral-sh/setup-uv@v7
+      - run: uv build
+      - uses: pypa/gh-action-pypi-publish@release/v1
+
+  npm:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-node@v6
+        with:
+          node-version: 24
+          registry-url: {{registryUrl}}
+      - run: npm publish --provenance --access public
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

strictcli-0.1.0/.rlsbl/bases/.gitignore

@@ -0,0 +1,15 @@
+node_modules/
+__pycache__/
+*.pyc
+*.log
+.DS_Store
+coverage/
+dist/
+*.egg-info/
+.rlsbl-notes-*.tmp
+.rlsbl/lock
+.credentials.json
+.*-cache.json
+.env
+.env.local
+*.local-only

strictcli-0.1.0/.rlsbl/bases/.rlsbl/hooks/post-release.sh

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+# Post-release hook. Runs after a successful release (non-fatal).
+# Environment: RLSBL_VERSION is set to the released version.
+# Customize this for your project (e.g., local install, deploy, notify).
+
+set -euo pipefail
+
+echo "Post-release: v$RLSBL_VERSION"

strictcli-0.1.0/.rlsbl/bases/.rlsbl/hooks/pre-release.sh

@@ -0,0 +1,31 @@
+#!/usr/bin/env bash
+# Pre-release validation hook.
+# Runs before rlsbl creates a release. Exit non-zero to abort.
+# Detects project type and runs appropriate checks automatically.
+
+set -euo pipefail
+
+echo "Running pre-release checks..."
+
+if [ -f go.mod ]; then
+  echo "  Go: vet + build + test"
+  go vet ./...
+  go build ./...
+  go test ./... -race -short -count=1
+fi
+
+if [ -f pyproject.toml ]; then
+  echo "  Python: pytest"
+  if command -v uv &>/dev/null; then
+    uv run pytest
+  elif command -v pytest &>/dev/null; then
+    pytest
+  fi
+fi
+
+if [ -f package.json ] && node -e "process.exit(require('./package.json').scripts?.test ? 0 : 1)" 2>/dev/null; then
+  echo "  npm: test"
+  npm test
+fi
+
+echo "Pre-release checks passed."

strictcli-0.1.0/.rlsbl/bases/CHANGELOG.md

@@ -0,0 +1,5 @@
+# Changelog
+
+## 0.1.0
+
+- Initial release

strictcli-0.1.0/.rlsbl/bases/CLAUDE.md

@@ -0,0 +1,20 @@
+# cli
+
+## Release workflow
+
+This project uses [rlsbl](https://github.com/smm-h/rlsbl) for release orchestration.
+
+- Update CHANGELOG.md with a `## X.Y.Z` entry describing changes
+- Run `rlsbl release [patch|minor|major]` to bump version and create a GitHub Release
+- CI handles publishing automatically via the publish workflow
+- Never publish manually — always use `rlsbl release`
+- Configure Trusted Publishing on pypi.org for automated PyPI releases
+- Use `rlsbl release --dry-run` to preview a release without making changes
+
+## Conventions
+
+- No tokens or secrets in command-line arguments (use env vars or config files)
+- All file writes to shared state should be atomic (write to tmp, then rename)
+- External calls (APIs, CLI tools) must have timeouts and graceful fallbacks
+- Use `npm link` (npm) or `uv pip install -e .` (Python) for local development
+- CI runs smoke tests on every push; manual testing for UI/UX changes

strictcli-0.1.0/.rlsbl/bases/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 smm-h
+
+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.

strictcli-0.1.0/.rlsbl/config.json

@@ -0,0 +1,6 @@
+{
+  "targets": [
+    "pypi",
+    "npm"
+  ]
+}

strictcli-0.1.0/.rlsbl/hashes.json

@@ -0,0 +1,11 @@
+{
+  ".github/workflows/ci.yml": "d71e558f1bfd93b43a783054577698da34c3e45455c6039686e06a7449b2bf1b",
+  ".github/workflows/publish.yml": "5f4ac1bf0bdd4c70041e3d2502efaae28d29eca7575e8ff12fdaad0d3af5b17a",
+  "CHANGELOG.md": "7a6ec46141007c18090a0ff325e2dd68cd51588c4e0b5af7b580365e5eaaca85",
+  ".gitignore": "c89d76c6c43e7f0897b3472a15b7c0103e0be5b3a04c2b44e585fa48bdcda2bb",
+  "LICENSE": "e958892abc1dd5d991fca6d528e695d335f25773d373d2e0be5f4a9507d8f8d5",
+  "CLAUDE.md": "7294b791570185dc31020dadb092b5b79681ba8ee932fe9a3974e27eaae56c4f",
+  ".rlsbl/hooks/pre-release.sh": "9bae4134d0a4c302287766f9a4a2923b6c5706d2cc7078f553fec843b8cd5a06",
+  ".rlsbl/hooks/post-release.sh": "b455f8511e0b2655509ecf5dcb0ab7da5bb7c961f47910ff8e00cab5bd51f833",
+  ".claude/settings.json": "78922a784ee78e9e50587e93628cd3b9d4dfbe49087adc4514e6781cea38cbb9"
+}

strictcli-0.1.0/.rlsbl/hooks/post-release.sh

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+# Post-release hook. Runs after a successful release (non-fatal).
+# Environment: RLSBL_VERSION is set to the released version.
+# Customize this for your project (e.g., local install, deploy, notify).
+
+set -euo pipefail
+
+echo "Post-release: v$RLSBL_VERSION"

strictcli-0.1.0/.rlsbl/hooks/pre-release.sh

@@ -0,0 +1,31 @@
+#!/usr/bin/env bash
+# Pre-release validation hook.
+# Runs before rlsbl creates a release. Exit non-zero to abort.
+# Detects project type and runs appropriate checks automatically.
+
+set -euo pipefail
+
+echo "Running pre-release checks..."
+
+if [ -f go.mod ]; then
+  echo "  Go: vet + build + test"
+  go vet ./...
+  go build ./...
+  go test ./... -race -short -count=1
+fi
+
+if [ -f pyproject.toml ]; then
+  echo "  Python: pytest"
+  if command -v uv &>/dev/null; then
+    uv run pytest
+  elif command -v pytest &>/dev/null; then
+    pytest
+  fi
+fi
+
+if [ -f package.json ] && node -e "process.exit(require('./package.json').scripts?.test ? 0 : 1)" 2>/dev/null; then
+  echo "  npm: test"
+  npm test
+fi
+
+echo "Pre-release checks passed."

strictcli-0.1.0/.rlsbl/version

@@ -0,0 +1 @@
+0.21.2

strictcli-0.1.0/CHANGELOG.md

@@ -0,0 +1,17 @@
+# Changelog
+
+## 0.1.0
+
+- Decorator-based command registration with `@app.command` and `@strictcli.flag`/`@strictcli.arg`
+- npm thin wrapper: `npm install strictcli` installs the Python package via uv/pip
+- Two-level command nesting via `app.group()` with `@group.command`
+- First-class environment variable support with prefix enforcement and `prefixed=False` opt-out
+- Tags: reusable flag bundles applied to commands
+- Plain-text help generation at app, group, and command levels
+- Automatic `--help`/`-h` and `--version`/`-v` handling
+- `--no-X` negation for boolean flags with opt-out
+- Short flag aliases (`-v`, `-t`, etc.)
+- Mandatory help text on all elements (commands, groups, flags, args, env vars)
+- Handler signature validation at registration time
+- `app.run()` full lifecycle and `app.test(argv)` for testing
+- `--` separator to stop flag parsing

strictcli-0.1.0/CLAUDE.md

@@ -0,0 +1,20 @@
+# strictcli
+
+## Release workflow
+
+This project uses [rlsbl](https://github.com/smm-h/rlsbl) for release orchestration.
+
+- Update CHANGELOG.md with a `## X.Y.Z` entry describing changes
+- Run `rlsbl release [patch|minor|major]` to bump version and create a GitHub Release
+- CI handles publishing automatically via the publish workflow
+- Never publish manually — always use `rlsbl release`
+- Configure Trusted Publishing on pypi.org for automated PyPI releases
+- Use `rlsbl release --dry-run` to preview a release without making changes
+
+## Conventions
+
+- No tokens or secrets in command-line arguments (use env vars or config files)
+- All file writes to shared state should be atomic (write to tmp, then rename)
+- External calls (APIs, CLI tools) must have timeouts and graceful fallbacks
+- Use `npm link` (npm) or `uv pip install -e .` (Python) for local development
+- CI runs smoke tests on every push; manual testing for UI/UX changes

strictcli-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 smm-h
+
+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.

strictcli-0.1.0/PKG-INFO

@@ -0,0 +1,318 @@
+Metadata-Version: 2.4
+Name: strictcli
+Version: 0.1.0
+Summary: A strict, zero-dependency CLI framework for Python
+Project-URL: Homepage, https://github.com/smm-h/strictcli
+Project-URL: Repository, https://github.com/smm-h/strictcli
+Author-email: "S. M. Hosseini" <m.hosseini@veliu.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: argparse,cli,command-line,framework,rlsbl,strictcli
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# strictcli
+
+A strict, zero-dependency CLI framework for Python.
+
+strictcli makes you declare everything -- every command, flag, argument, and environment variable must have help text or the framework errors at registration time. Types are `str` and `bool` only; there is no magic type inference. Environment variables are first-class, with prefix enforcement to keep your config namespace clean.
+
+## Installation
+
+```
+uv add strictcli
+```
+
+Or:
+
+```
+pip install strictcli
+```
+
+Requires Python 3.11+.
+
+## Quickstart
+
+```python
+# greet.py
+import strictcli
+
+app = strictcli.App(name="greet", version="0.1.0", help="a friendly greeter")
+
+@app.command("hello", help="say hello", args=[strictcli.Arg(name="name", help="who to greet")])
+@strictcli.flag("loud", short="l", type=bool, help="shout the greeting")
+def hello(name, loud):
+    msg = f"Hello, {name}!"
+    if loud:
+        msg = msg.upper()
+    print(msg)
+
+app.run()
+```
+
+```
+$ python greet.py hello World
+Hello, World!
+
+$ python greet.py hello --loud World
+HELLO, WORLD!
+
+$ python greet.py hello --help
+greet hello -- say hello
+
+Arguments:
+  name    who to greet
+
+Flags:
+  --loud, --no-loud, -l    shout the greeting [default: false]
+```
+
+## Commands and Groups
+
+Register top-level commands with `@app.command`:
+
+```python
+app = strictcli.App(name="myapp", version="1.0.0", help="manage deployments")
+
+@app.command("status", help="show current status")
+def status():
+    print("all systems go")
+```
+
+Create groups for two-level nesting with `app.group`:
+
+```python
+db = app.group("db", help="manage databases")
+
+@db.command("migrate", help="run database migrations")
+@strictcli.flag("dry-run", type=bool, help="preview without applying")
+def migrate(dry_run):
+    if dry_run:
+        print("would run migrations")
+    else:
+        print("running migrations")
+
+@db.command("seed", help="populate with sample data")
+@strictcli.flag("count", type=str, help="number of records", default="100")
+def seed(count):
+    print(f"seeding {count} records")
+```
+
+```
+$ myapp db migrate --dry-run
+would run migrations
+
+$ myapp db seed --count 500
+seeding 500 records
+```
+
+## Flags
+
+Declare flags with the `@strictcli.flag` decorator. Every flag must have `help` text.
+
+### String flags
+
+```python
+@app.command("build", help="build the project")
+@strictcli.flag("output", short="o", type=str, help="output directory", default="dist")
+def build(output):
+    print(f"building to {output}")
+```
+
+String flags accept values via `--output dist` or `--output=dist`. A string flag without a `default` is required.
+
+### Bool flags
+
+```python
+@app.command("deploy", help="deploy the app")
+@strictcli.flag("force", short="f", type=bool, help="skip confirmation")
+def deploy(force):
+    if force:
+        print("deploying without confirmation")
+```
+
+Bool flags default to `False`. Pass `--force` to set `True`, or `--no-force` to explicitly set `False`. The `--no-` negation form is available by default for all bool flags; disable it with `negatable=False`.
+
+### Short aliases
+
+Any flag can have a one-character short alias:
+
+```python
+@strictcli.flag("verbose", short="v", type=bool, help="verbose output")
+```
+
+This allows both `--verbose` and `-v`.
+
+### Required vs optional
+
+- `str` flags with no `default` are required -- the parser errors if missing.
+- `str` flags with a `default` are optional.
+- `bool` flags always default to `False`.
+
+## Arguments
+
+Positional arguments are declared with `strictcli.Arg`. There are two equivalent forms.
+
+Using the `args=` parameter:
+
+```python
+@app.command("copy", help="copy files", args=[
+    strictcli.Arg(name="src", help="source path"),
+    strictcli.Arg(name="dst", help="destination path"),
+])
+def copy(src, dst):
+    print(f"copying {src} to {dst}")
+```
+
+Using the `@strictcli.arg` decorator:
+
+```python
+@app.command("show", help="show a file")
+@strictcli.arg("path", help="file to show")
+def show(path):
+    print(f"showing {path}")
+```
+
+Arguments are matched in order. Use `required=False` for optional arguments. The `--` separator stops flag parsing, so everything after it becomes positional:
+
+```
+$ myapp cmd -- --not-a-flag
+```
+
+## Environment Variables
+
+Flags can be backed by environment variables with the `env` parameter:
+
+```python
+app = strictcli.App(name="myapp", version="1.0.0", help="my app", env_prefix="MYAPP")
+
+@app.command("deploy", help="deploy the app")
+@strictcli.flag("region", type=str, help="cloud region", env="MYAPP_REGION", default="us-east-1")
+def deploy(region):
+    print(f"deploying to {region}")
+```
+
+### Prefix enforcement
+
+When `env_prefix` is set on the App, all env vars must start with that prefix. This is validated at registration time:
+
+```python
+# This raises ValueError: env var 'REGION' must start with 'MYAPP_'
+@strictcli.flag("region", type=str, help="region", env="REGION", default="x")
+```
+
+### External env vars
+
+Use `prefixed=False` for env vars outside your app's namespace:
+
+```python
+@strictcli.flag("token", type=str, help="auth token", env="GITHUB_TOKEN", prefixed=False, default="")
+```
+
+### Priority
+
+Values resolve in this order: CLI argument > environment variable > default. If none of the three provides a value, the parser errors.
+
+### Bool env vars
+
+Bool flags from env vars accept `1`, `true`, `yes` (case-insensitive) for `True` and `0`, `false`, `no` for `False`. Any other value is an error.
+
+## Tags
+
+Tags are reusable bundles of flags that can be applied to multiple commands:
+
+```python
+auth_tag = strictcli.Tag(
+    name="auth",
+    flags=[
+        strictcli.Flag(name="token", type=str, help="auth token", env="MYAPP_TOKEN", default=""),
+        strictcli.Flag(name="insecure", type=bool, help="skip TLS verification"),
+    ],
+)
+
+@app.command("deploy", help="deploy the app", tags=[auth_tag])
+def deploy(token, insecure):
+    print(f"token={'set' if token else 'unset'}, insecure={insecure}")
+
+@app.command("status", help="check status", tags=[auth_tag])
+def status(token, insecure):
+    print(f"checking status")
+```
+
+Both commands now have `--token` and `--insecure` flags. Tag flags appear in help output and are parsed like any other flag.
+
+## Help Output
+
+Help is auto-generated at three levels. Pass `--help` or `-h` at any level, or invoke the app with no arguments.
+
+**App level** (`myapp --help`):
+
+```
+myapp v1.0.0 -- manage deployments
+
+Commands:
+  deploy    deploy the application
+
+Groups:
+  db    manage databases
+
+Use 'myapp <command> --help' for more information.
+```
+
+**Group level** (`myapp db --help`):
+
+```
+myapp db -- manage databases
+
+Commands:
+  migrate    run database migrations
+  seed       populate with sample data
+
+Use 'myapp db <command> --help' for more information.
+```
+
+**Command level** (`myapp deploy --help`):
+
+```
+myapp deploy -- deploy the application
+
+Arguments:
+  target    deployment target
+
+Flags:
+  --region, -r <str>         cloud region [env: MYAPP_REGION] [default: us-east-1]
+  --force, --no-force, -f    skip confirmation prompt [default: false]
+```
+
+Version: `--version` or `-v` prints `myapp 1.0.0`.
+
+## Testing
+
+`app.test(argv)` runs the CLI in-process and returns a `Result` with captured output:
+
+```python
+result = app.test(["deploy", "--force", "production"])
+
+assert result.exit_code == 0
+assert "deploying" in result.stdout
+assert result.stderr == ""
+```
+
+The `Result` dataclass has three fields: `stdout`, `stderr`, and `exit_code`.
+
+## Strict by Design
+
+strictcli is opinionated about strictness:
+
+- **Help is mandatory.** Every command, flag, and argument must have help text. Missing help raises `ValueError` at registration time, not at runtime.
+- **Only str and bool.** No int, float, or list types. Parse them yourself in the handler -- it is one line of code and makes the conversion visible.
+- **Handler signatures are validated.** Every declared flag and arg must have a matching parameter in the handler function, and vice versa. Extra or missing parameters raise `ValueError`.
+- **Env var prefixes are enforced.** If you set `env_prefix="MYAPP"`, every env-backed flag must use that prefix (or explicitly opt out with `prefixed=False`).
+- **No hidden defaults.** Required flags fail loudly. Bool flags default to `False`. Everything else must be declared.
+
+If you want automatic type coercion, subcommand hierarchies deeper than two levels, or rich terminal formatting, consider [argparse](https://docs.python.org/3/library/argparse.html), [click](https://click.palletsprojects.com/), or [typer](https://typer.tiangolo.com/).