cmdscope 0.1.0__tar.gz

cmdscope-0.1.0/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,58 @@
+name: Bug report
+description: Report a problem with CmdScope
+labels: [bug]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for reporting a bug. CmdScope never uploads data, so everything below
+        stays in this issue.
+  - type: input
+    id: version
+    attributes:
+      label: CmdScope version
+      description: Output of `cmdscope --version`
+      placeholder: cmdscope 0.1.0
+    validations:
+      required: true
+  - type: input
+    id: os
+    attributes:
+      label: Operating system
+      placeholder: Windows 11 / Ubuntu 24.04 / macOS 15
+    validations:
+      required: true
+  - type: input
+    id: python
+    attributes:
+      label: Python version
+      placeholder: 3.13.1
+    validations:
+      required: true
+  - type: textarea
+    id: command
+    attributes:
+      label: What did you run?
+      description: The exact CmdScope command, with secrets removed.
+      placeholder: cmdscope run -- npm install
+    validations:
+      required: true
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected behaviour
+    validations:
+      required: true
+  - type: textarea
+    id: observed
+    attributes:
+      label: Observed behaviour
+      description: Include the report output if it is safe to share.
+    validations:
+      required: true
+  - type: textarea
+    id: doctor
+    attributes:
+      label: Output of `cmdscope doctor`
+      description: This contains no personal data and helps a lot.
+      render: shell

cmdscope-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,60 @@
+name: release
+
+on:
+  push:
+    tags: ["v*"]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: build distributions
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+      - name: Install build tools
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install build twine
+      - name: Build
+        run: python -m build
+      - name: Verify metadata
+        run: twine check dist/*
+      - name: Install wheel in a clean environment
+        run: |
+          python -m venv .venv-wheel
+          .venv-wheel/bin/python -m pip install dist/*.whl
+          .venv-wheel/bin/cmdscope --version
+      - uses: actions/upload-artifact@v4
+        with:
+          name: distributions
+          path: dist/
+
+  publish:
+    name: publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/cmdscope
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: distributions
+          path: dist
+      - name: Publish to PyPI with an API token
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          # The token is a PyPI API token with scope "Entire project" for cmdscope,
+          # stored as the repository secret PYPI_API_TOKEN.
+          # Repository settings -> Secrets and variables -> Actions -> New secret.
+          # Name it exactly PYPI_API_TOKEN and paste the "pypi-..." token as the value.
+          password: ${{ secrets.PYPI_API_TOKEN }}

cmdscope-0.1.0/.github/workflows/tests.yml

@@ -0,0 +1,92 @@
+name: tests
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: tests-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  lint:
+    name: lint and type check
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install -e ".[dev]"
+      - name: Ruff lint
+        run: ruff check src tests
+      - name: Ruff format
+        run: ruff format --check src tests
+      - name: Mypy
+        run: mypy src/cmdscope
+
+  test:
+    name: test ${{ matrix.os }} / python ${{ matrix.python }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest, macos-latest]
+        python: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python }}
+          cache: pip
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install -e ".[dev]"
+      - name: Run tests
+        run: pytest --cov=cmdscope --cov-report=term-missing
+      - name: Upload coverage
+        if: matrix.os == 'ubuntu-latest' && matrix.python == '3.12'
+        uses: actions/upload-artifact@v4
+        with:
+          name: coverage-${{ matrix.python }}
+          path: .coverage
+          if-no-files-found: ignore
+
+  build:
+    name: build and install
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+      - name: Install build tools
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install build twine
+      - name: Build distributions
+        run: python -m build
+      - name: Check metadata
+        run: twine check dist/*
+      - name: Install wheel in a clean environment
+        run: |
+          python -m venv .venv-wheel
+          .venv-wheel/bin/python -m pip install dist/*.whl
+          .venv-wheel/bin/cmdscope --version
+          .venv-wheel/bin/cmdscope doctor --json > doctor.json
+      - name: Upload distributions
+        uses: actions/upload-artifact@v4
+        with:
+          name: distributions
+          path: dist/

cmdscope-0.1.0/CHANGELOG.md

@@ -0,0 +1,47 @@
+# Changelog
+
+All notable changes to this project are documented in this file. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the project adheres to
+[Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+Nothing yet.
+
+## [0.1.0] - 2026-11-08
+
+Initial public release.
+
+### Added
+
+- `cmdscope run` — run a command inside an observation session and print a report.
+- Filesystem collector: baseline snapshot, native OS events (Windows, Linux, macOS),
+  polling fallback, and final reconciliation. Reports created, modified, and deleted
+  entries with metadata only.
+- Process collector: psutil-based discovery of the root process and its descendants,
+  with redacted command lines and explicit "still running" reporting.
+- Network collector: TCP/UDP endpoint sampling attributed to the processes of the
+  session, with no payload inspection and no DNS lookups.
+- Local SQLite session storage with schema versioning, cascading deletes, event limits,
+  and optional pruning of old sessions.
+- `cmdscope sessions`, `cmdscope show`, `cmdscope report` (terminal, JSON, HTML), and
+  `cmdscope compare`.
+- `cmdscope doctor` for read-only capability diagnostics and `cmdscope config` for
+  inspecting or initializing the TOML configuration.
+- Privacy layer that redacts sensitive flags, environment variables, URL credentials, and
+  authorization headers before anything is stored.
+- TOML configuration with per-collector settings, watch roots, ignore patterns, storage
+  limits, and report options.
+- Documentation: README, architecture guide, collector guide, configuration reference,
+  privacy model, contribution guide with the engineering rules.
+
+### Known limitations
+
+- Observation is limited to the configured watch roots; CmdScope is not a syscall tracer.
+- Processes and sockets are sampled and very short-lived ones can be missed.
+- Runtime environment mutations are not observable.
+- Windows is the only platform validated manually in this release; Linux and macOS are
+  exercised by CI.
+
+[Unreleased]: https://github.com/SouzaF19/cmdscope/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/SouzaF19/cmdscope/releases/tag/v0.1.0

cmdscope-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,97 @@
+# Contributing to CmdScope
+
+Thanks for considering a contribution. CmdScope is young, so there is room to shape the
+design — but the project has non-negotiable rules about honesty, privacy, and safety.
+
+Read the "Ground rules" and "Architecture invariants" sections of this guide first: they
+contain the engineering rules for this repository and are enforced in review.
+
+## Development setup
+
+```console
+$ git clone https://github.com/SouzaF19/cmdscope.git
+$ cd cmdscope
+$ python -m venv .venv
+$ .venv\Scripts\activate          # Windows
+$ source .venv/bin/activate       # Linux/macOS
+$ python -m pip install -e ".[dev]"
+```
+
+## Quality gates
+
+Run all of them before opening a pull request:
+
+```console
+$ ruff check src tests
+$ ruff format --check src tests
+$ mypy src/cmdscope
+$ pytest
+$ pytest --cov=cmdscope --cov-report=term-missing
+```
+
+CI runs the same checks on Windows, Ubuntu, and macOS for Python 3.11, 3.12, and 3.13.
+
+## Ground rules
+
+- **No fabricated events.** Every reported value must come from an observation. When a
+  collector cannot observe something, say so.
+- **No file contents, no telemetry, no uploads.**
+- **Never elevate privileges** and never install privileged components.
+- **Never hide failures.** A degraded collector must be visible in the report.
+- **Tests must run.** Do not skip tests to make a pipeline green.
+- **Keep the dependency list small.** A new dependency needs a justification in the pull
+  request description.
+
+## Adding a collector
+
+See [docs/collectors.md](docs/collectors.md#writing-a-new-collector). In short: implement
+the `Collector` protocol, emit typed events, report an honest status, document the blind
+spots, and add tests.
+
+## Pull requests
+
+1. Create a focused branch: `feature/short-description`.
+2. Keep the change small enough to review. Separate refactors from behaviour changes.
+3. Update `CHANGELOG.md` under "Unreleased" for user-visible changes.
+4. Update the README and `docs/` when behaviour or limitations change.
+5. Describe in the pull request what you validated and on which platform.
+
+## Commit messages
+
+Use short, imperative summaries, for example:
+
+```text
+Add network collector status for access-denied environments
+```
+
+## Reporting bugs
+
+Open an issue with:
+
+- the CmdScope version (`cmdscope --version`), Python version, and operating system;
+- the exact command you ran and the expected versus observed behaviour;
+- the output of `cmdscope doctor` (it contains no personal data);
+- a minimal reproduction if possible.
+
+Never paste secrets into an issue — CmdScope redacts its own reports, but your shell
+history might not.
+
+## License
+
+Contributions are accepted under the MIT license.
+
+## Releasing (maintainers)
+
+1. Merge the release PR and confirm that CI is green on `main`.
+2. Update `CHANGELOG.md` (move "Unreleased" entries into a dated version section).
+3. Bump `version` in `pyproject.toml`.
+4. Tag and push: `git tag v0.1.0 && git push origin v0.1.0`.
+5. The `release` workflow builds the wheel and sdist, checks them, smoke-installs the
+   wheel, and publishes both to PyPI.
+
+Publishing uses the PyPI API token stored as the repository secret `PYPI_API_TOKEN`
+(`Repository settings → Secrets and variables → Actions`). Rotate the token after every
+release. To switch to trusted publishing instead, remove the `password:` input and add
+`id-token: write` to the publish job permissions after configuring the publisher on
+PyPI. Publishing is never triggered from a pull request.
+

cmdscope-0.1.0/LICENSE

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

cmdscope-0.1.0/MANIFEST.in

@@ -0,0 +1,11 @@
+include LICENSE
+include README.md
+include CHANGELOG.md
+include CONTRIBUTING.md
+include SECURITY.md
+recursive-include docs *.md
+recursive-include examples *.py *.md
+recursive-include tests *.py
+recursive-include .github *.yml *.yaml *.md
+global-exclude __pycache__
+global-exclude *.py[cod]