Merge pull request #78 from psadmin-io/staging

Release v0.3.0 — first public release

Author: kbens

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,74 @@
+name: Bug report
+description: Report a defect in psa-cli
+labels: ["bug"]
+body:
+  - type: textarea
+    id: what-happened
+    attributes:
+      label: What happened?
+      description: A clear description of the bug, including the command you ran.
+      placeholder: |
+        I ran `psa dpk apply --summary` and ...
+    validations:
+      required: true
+
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected behavior
+    validations:
+      required: true
+
+  - type: textarea
+    id: reproduce
+    attributes:
+      label: Steps to reproduce
+      placeholder: |
+        1. Run `psa config setup --yes`
+        2. Run `psa ...`
+        3. Observe ...
+    validations:
+      required: true
+
+  - type: input
+    id: psa-version
+    attributes:
+      label: psa-cli version
+      description: Output of `psa --version`
+      placeholder: psa version 0.3.0
+    validations:
+      required: true
+
+  - type: input
+    id: peopletools
+    attributes:
+      label: PeopleTools version
+      placeholder: 8.62.04
+    validations:
+      required: false
+
+  - type: input
+    id: os
+    attributes:
+      label: Operating system
+      placeholder: Oracle Linux 9.3
+    validations:
+      required: false
+
+  - type: input
+    id: python
+    attributes:
+      label: Python version
+      description: Output of `python --version`
+      placeholder: Python 3.11.7
+    validations:
+      required: false
+
+  - type: textarea
+    id: logs
+    attributes:
+      label: Logs / output
+      description: Paste relevant CLI output. Run with `-v` for verbose mode.
+      render: shell
+    validations:
+      required: false

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Security vulnerability
+    url: https://github.com/psadmin-io/psa-cli/blob/main/SECURITY.md
+    about: Please report security issues privately, not via public issues.

.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,35 @@
+name: Feature request
+description: Suggest a new feature or enhancement
+labels: ["enhancement"]
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: What problem are you trying to solve?
+      description: Describe the pain point or workflow this would improve.
+    validations:
+      required: true
+
+  - type: textarea
+    id: proposal
+    attributes:
+      label: Proposed solution
+      description: How could psa-cli address this?
+    validations:
+      required: true
+
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives considered
+      description: Other approaches you've thought about.
+    validations:
+      required: false
+
+  - type: textarea
+    id: context
+    attributes:
+      label: Additional context
+      description: Screenshots, related issues, links, etc.
+    validations:
+      required: false

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,19 @@
+## Summary
+
+<!-- What does this PR change, and why? -->
+
+## Changes
+
+<!-- Bullet list of notable changes -->
+
+## Test plan
+
+<!-- How did you verify this works? -->
+
+- [ ] `pytest` passes
+- [ ] `ruff check .` passes
+- [ ] Manually verified on a PeopleSoft environment (describe below)
+
+## Related issues
+
+<!-- Closes #N, Refs #N -->

.github/workflows/docs.yml

@@ -0,0 +1,32 @@
+name: Docs
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - docs/**
+      - mkdocs.yml
+      - .github/workflows/docs.yml
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install MkDocs Material
+        run: pip install mkdocs-material
+
+      - name: Deploy to GitHub Pages
+        run: mkdocs gh-deploy --force

.github/workflows/test.yml

@@ -0,0 +1,38 @@
+name: Test
+
+on:
+  push:
+    branches: [main, staging]
+  pull_request:
+    branches: [main, staging]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.9", "3.10", "3.11", "3.12"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+        with:
+          enable-cache: true
+
+      - name: Install dependencies
+        run: uv sync --extra dev
+
+      - name: Lint with ruff
+        run: uv run ruff check .
+        continue-on-error: true
+
+      - name: Run tests
+        run: uv run pytest -v

.gitignore

@@ -41,3 +41,6 @@ htmlcov/
 # Distribution
 *.tar.gz
 *.whl
+
+# MkDocs build output
+site/

CHANGELOG.md

@@ -0,0 +1,85 @@
+# Changelog
+
+All notable changes to psa-cli are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.3.0] — 2026-05-12
+
+**First public release.** psa-cli is now open source under the MIT license. This release collapses the un-tagged 0.2.1 through 0.2.5 development work into the first public cut.
+
+> :warning: **Pre-1.0 / beta.** Not yet recommended for production. The CLI surface, config schema, and command behavior may change before 1.0.
+
+### Highlights
+
+- **Domain lifecycle** — `psa domain list / status / start / stop / restart / bounce / compare` with Rich-rendered output, JSON mode, quiet/verbose flags, and `--force` confirmation skips.
+- **DPK workflow** — end-to-end PeopleSoft DPK provisioning: `psa dpk stage → setup → init → sync → apply → cleanup`, including a 3-tier Hiera layout, `dpk module install` for custom Puppet modules, `dpk facts` for site facts, and `dpk lookup` for hiera key resolution.
+- **`psa dpk apply --summary`** — filtered, readable Puppet apply output with surfaced errors, exit-code mapping, and ANSI handling.
+- **Discovery** — `psa discover` finds local PeopleSoft domains and can report results to a configured API.
+- **Configuration** — `psa config setup` (interactive + `--yes` non-interactive), `psa config show`, `psa config set` for individual keys, with auto-detection of `PS_*` and `DPK_*` paths.
+- **Resilient file operations** — `SudoFileOps` abstraction transparently cascades to `sudo` when the runtime user lacks write permission, with timeout-driven diagnostics for missing passwordless sudo.
+
+### Added since v0.2.0
+
+#### Domain
+- `psa domain compare` replaces `psa domain drift`; archive picker, archive age display, raw-config diff that handles `%PS_SERVDIR%` vars
+- Global `-q/--quiet` / `-v/--verbose` flags; Rich spinners
+- `--force/-f` flag (renamed from `--yes/-y`) on destructive operations
+- `psa domain status --json` with full process detail
+- Web tier renamed `pia` → `web`; status/start/stop route through `psadmin -w` for PT 8.62
+- Graceful already-stopped / already-purged handling
+
+#### DPK
+- `psa dpk` command group consolidates DPK provisioning
+- `psa dpk module install <org/repo>` with `--branch`, `--dry-run`, `--as <name>`
+- `psa dpk facts` (writes to `/etc/`, not the DPK install tree)
+- `psa dpk init` auto-creates config, generates `hiera.yaml` (eyaml backend), 3-tier hiera layout
+- `psa dpk lookup` for hiera key resolution
+- `psa dpk apply --summary` mode + puppet error surfacing + stderr scanning + Rich bypass for raw streams
+- `psa dpk apply` auto-sudo to root unless already root or `runtime_user`
+- `psa dpk sync` with `SudoFileOps` permission fallback
+- `psa dpk status --json` + manifest parsing
+- `psa dpk cleanup --domains-only` for scoped domain+service teardown
+- `psa dpk stage --version` and `--dry-run` fix
+- Split `DPK_BASE` vs `DPK_HOME` with `--dpk-cust-home` flag
+- EL 9+ ncurses prereq: per-lib symlink fallback
+- OL8/RHEL8+ libnsl in DPK prereq checks
+- DPK repo commands: `init`, `status`, `list`
+
+#### Config
+- `psa config set` for individual config keys (`ps_cfg_home`, `ps_base`, `ps_home`, etc.)
+- `psa config show` groups DPK paths, uppercases path labels
+- `DPK_CUST_HOME` foundation (renamed from `PSA_CUST`)
+- `psa ops setup` moved out of `config` group (hidden by default)
+
+#### Quality / internal
+- Minimum Python bumped to 3.9
+- `SudoFileOps` centralized file operations
+- Resilient domain discovery (skips permission errors, scopes by type)
+- Test fixes: verbosity reset, tmadmin process-table parsing, "Started" prcs pattern
+- Demo-lab regression fixes: status parser, PIA paths, empty errors, PS path auto-detect
+
+### Removed
+
+- `psa cache` and `psa secrets` (stub commands that were never wired into the CLI)
+- `psa domain drift` (replaced by `psa domain compare`)
+- `psa ops register` (folded into `psa ops setup`)
+- `start/stopPIA.sh` shim (now routes through `psadmin -w`)
+- `io_base` config key
+
+### Known limitations
+
+- **Encrypted password leak in JSON** — `psa domain --json` includes raw config content that contains encrypted password fields (`ConnectPswd`, `OprPswd`, etc). Values are encrypted, not cleartext, but should not appear in piped output. Tracked as issue #23, fix planned for 0.4.
+- **`psa ops` is hidden** — depends on the private psadmin.io ops API; not intended for general public use in this release.
+- **`psa kit` is gated** — requires `enable_psa_kit: true` in config and SSH access to the private `psadmin-io/psa-kit` repository.
+- Tested against **PeopleTools 8.62**; older versions may work but are unverified.
+- No PyPI release yet — install from the GitHub release wheel or from source.
+
+### Compatibility
+
+- Python 3.9, 3.10, 3.11, 3.12
+- Linux (Oracle Linux 8/9, RHEL 8/9 covered; other distros likely fine)
+- PeopleTools 8.62
+
+[0.3.0]: https://github.com/psadmin-io/psa-cli/releases/tag/v0.3.0

LICENSE

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