pstq 0.1.0__tar.gz

pstq-0.1.0/.devcontainer/Dockerfile

@@ -0,0 +1,49 @@
+FROM python:3.13-slim AS pypff-builder
+
+# Build a wheel from the immutable libpff Python source distribution.
+ARG LIBPFF_VERSION=20231205
+ARG LIBPFF_SHA256=06c218be51321b16dc3b835185ee1cd2fa5c2a1ca856e0390c1d6e4ddf329250
+
+# Install the native build dependencies in the builder only.
+RUN apt-get update \
+    && apt-get install -y --no-install-recommends \
+        build-essential \
+        ca-certificates \
+        curl \
+        zlib1g-dev \
+    && rm -rf /var/lib/apt/lists/*
+
+RUN curl --fail --location --silent --show-error \
+        --output /tmp/libpff-python.tar.gz \
+        "https://files.pythonhosted.org/packages/0b/a3/826777491832478f5e1555a16bc9de794ef0264eac53d213340dddae5bd4/libpff-python-${LIBPFF_VERSION}.tar.gz" \
+    && printf '%s  %s\n' "$LIBPFF_SHA256" /tmp/libpff-python.tar.gz \
+        | sha256sum --check \
+    && python -m pip wheel --no-cache-dir --no-deps \
+        --wheel-dir /opt/pypff-wheel /tmp/libpff-python.tar.gz
+
+FROM python:3.13-slim
+
+COPY --from=pypff-builder /opt/pypff-wheel /tmp/pypff-wheel
+
+RUN python -m pip install --no-cache-dir /tmp/pypff-wheel/*.whl \
+    && python -c "import pypff" \
+    && rm -rf /tmp/pypff-wheel
+
+# Install git and other dependencies.
+RUN apt-get update \
+    && apt-get install -y --no-install-recommends bash ca-certificates curl git \
+    && rm -rf /var/lib/apt/lists/*
+
+# Install uv
+RUN pip install uv
+
+
+# Install Backlog.md
+RUN apt-get update \
+    && apt-get install -y --no-install-recommends nodejs npm \
+    && npm install -g backlog.md \
+    && rm -rf /var/lib/apt/lists/*
+
+
+# Install OpenCode CLI
+RUN curl -fsSL https://opencode.ai/install | bash

pstq-0.1.0/.devcontainer/devcontainer.json

@@ -0,0 +1,24 @@
+{
+	"name": "Python 3.13",
+	"build": {
+		"dockerfile": "Dockerfile"
+	},
+	"customizations": {
+		"vscode": {
+			"extensions": [
+				"ms-python.python",
+				"ms-python.vscode-pylance",
+				"charliermarsh.ruff",
+				"sst-dev.opencode"
+			]
+		}
+	},
+	"remoteEnv": {
+		"OPENCODE_ENABLE_EXA": "true"
+	},
+    "mounts": [
+        "source=${localEnv:HOME}/.config/opencode,target=/root/.config/opencode,type=bind,consistency=cached",
+        "source=${localEnv:HOME}/.local/share/opencode,target=/root/.local/share/opencode,type=bind,consistency=cached"
+    ],
+"postCreateCommand": "if [ -f .backlog-config.yml ]; then git init && backlog init --defaults --backlog-dir backlog --config-location folder --task-prefix task --zero-padded-ids 3 --check-branches false --include-remote false --branch-days 30 --bypass-git-hooks true --web-port 6420 --auto-open-browser false --integration-mode cli --agent-instructions agents && mv .backlog-config.yml backlog/config.yml; fi && uv venv --clear --system-site-packages && uv sync --group dev && uv run python -c 'import pypff'"
+}

pstq-0.1.0/.editorconfig

@@ -0,0 +1,19 @@
+# http://editorconfig.org
+
+root = true
+
+[*]
+indent_style = space
+indent_size = 4
+trim_trailing_whitespace = true
+insert_final_newline = true
+charset = utf-8
+end_of_line = lf
+
+[*.bat]
+indent_style = tab
+end_of_line = crlf
+
+[LICENSE]
+insert_final_newline = false
+

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

@@ -0,0 +1,36 @@
+name: CI
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    branches:
+      - main
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ci-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  quality:
+    name: Quality checks
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
+        with:
+          python-version: "3.13"
+          enable-cache: true
+
+      - name: Run quality checks
+        run: uv run tox

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

@@ -0,0 +1,166 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*"
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: Existing vX.Y.Z tag to release
+        required: true
+        type: string
+      skip_pypi:
+        description: Skip PyPI only when this version is already published
+        required: true
+        default: false
+        type: boolean
+
+permissions:
+  contents: read
+
+concurrency:
+  group: release-${{ github.event_name == 'workflow_dispatch' && inputs.tag || github.ref_name }}
+  cancel-in-progress: false
+
+jobs:
+  build:
+    name: Validate and build release artifacts
+    runs-on: ubuntu-latest
+    outputs:
+      tag: ${{ steps.release.outputs.tag }}
+    steps:
+      - name: Check out release tag
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          ref: ${{ github.event_name == 'workflow_dispatch' && inputs.tag || github.ref }}
+          fetch-depth: 0
+          persist-credentials: false
+
+      - name: Validate release version
+        id: release
+        env:
+          RELEASE_TAG: ${{ github.event_name == 'workflow_dispatch' && inputs.tag || github.ref_name }}
+        run: |
+          set -euo pipefail
+          [[ "$RELEASE_TAG" =~ ^v[0-9]+\.[0-9]+\.[0-9]+$ ]] || {
+            echo "Release tag must match vX.Y.Z: $RELEASE_TAG" >&2
+            exit 1
+          }
+          git rev-parse --verify "refs/tags/$RELEASE_TAG" >/dev/null
+          python - "$RELEASE_TAG" <<'PY'
+          import ast
+          import re
+          import sys
+          import tomllib
+
+          tag = sys.argv[1]
+          with open("pyproject.toml", "rb") as pyproject:
+              version = tomllib.load(pyproject)["project"]["version"]
+          module = ast.parse(open("pstq/__init__.py", encoding="utf-8").read())
+          module_version = next(
+              (
+                  ast.literal_eval(node.value)
+                  for node in module.body
+                  if isinstance(node, ast.Assign)
+                  and any(
+                      isinstance(target, ast.Name) and target.id == "__version__"
+                      for target in node.targets
+                  )
+              ),
+              None,
+          )
+          changelog = open("CHANGELOG.md", encoding="utf-8").read()
+
+          if tag != f"v{version}":
+              raise SystemExit(
+                  f"Release tag {tag!r} does not match package version {version!r}."
+              )
+          if module_version != version:
+              raise SystemExit(
+                  "pstq.__version__ does not match the package version "
+                  f"{version!r}."
+              )
+          if not re.search(rf"^## {re.escape(version)}(?: |$)", changelog, re.MULTILINE):
+              raise SystemExit(f"CHANGELOG.md has no heading for version {version!r}.")
+          PY
+          echo "tag=$RELEASE_TAG" >> "$GITHUB_OUTPUT"
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
+        with:
+          python-version: "3.13"
+
+      - name: Install locked development dependencies
+        run: uv sync --group dev --locked
+
+      - name: Run quality checks
+        run: uv run tox
+
+      - name: Build distributions
+        run: uv build --out-dir dist --clear
+
+      - name: Validate distribution metadata
+        run: uv tool run twine check dist/*
+
+      - name: Smoke test the built wheel
+        run: |
+          uv venv --python 3.13 .release-venv
+          uv pip install --python .release-venv/bin/python dist/*.whl
+          .release-venv/bin/python - <<'PY'
+          import importlib.metadata
+          import pstq
+
+          assert importlib.metadata.version("pstq") == pstq.__version__
+          PY
+          .release-venv/bin/pstq --help >/dev/null
+
+      - name: Upload release distributions
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: release-distributions
+          path: dist/
+          if-no-files-found: error
+
+  publish-pypi:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/pstq
+    permissions:
+      id-token: write
+    steps:
+      - name: Download release distributions
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: release-distributions
+          path: dist/
+
+      - name: Publish package distributions to PyPI
+        if: ${{ !inputs.skip_pypi }}
+        uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # v1.14.2
+        with:
+          packages-dir: dist/
+
+  create-github-release:
+    name: Create GitHub Release
+    needs:
+      - build
+      - publish-pypi
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - name: Download release distributions
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: release-distributions
+          path: dist/
+
+      - name: Create GitHub Release
+        env:
+          GH_TOKEN: ${{ github.token }}
+          RELEASE_TAG: ${{ needs.build.outputs.tag }}
+        run: gh release create "$RELEASE_TAG" dist/* --verify-tag --generate-notes

pstq-0.1.0/.gitignore

@@ -0,0 +1,106 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+env/
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+.hypothesis/
+.pytest_cache/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# PyBuilder
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# pyenv
+#.python-version
+
+# celery beat schedule file
+celerybeat-schedule
+
+# SageMath parsed files
+*.sage.py
+
+# dotenv
+.env
+
+# virtualenv
+.venv
+venv/
+ENV/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mypy
+.mypy_cache/
+alabaster
+
+.vscode/
+.idea/
+.claude/
+
+# temporary files
+temp/
+test.json
+test_config.yaml

pstq-0.1.0/.opencode/skills/pstq/SKILL.md

@@ -0,0 +1,27 @@
+---
+name: pstq
+description: Use when searching, retrieving, threading, or extracting content from an Outlook PST with pstq.
+---
+
+# PST Query
+
+Use `pstq` rather than parsing the PST or SQLite database directly. The PST is
+read-only and authoritative; the SQLite index is a disposable local cache.
+
+Before issuing an unfamiliar command, read its canonical documentation:
+
+```console
+pstq --help
+pstq <command> --help
+```
+
+Use `--json` for programmatic work. On success it writes deterministic JSON to
+stdout. On failure it writes a JSON error envelope to stderr and returns a
+non-zero exit code. Do not infer JSON fields, ID formats, limits, cache access,
+or synchronization behavior from this skill; command-level `--help` defines
+the current contract.
+
+The normal retrieval sequence is `status`, `folders` when needed, bounded
+`search`, then `show` for selected message IDs. Use `thread`, `attachments`,
+and `attachment` only after reading their help. Never modify the configured
+PST or assume it is safe to access while Outlook is writing it.

pstq-0.1.0/AGENTS.md

@@ -0,0 +1,193 @@
+## Backlog.md workflow
+
+Backlog.md is the authoritative record of active and completed development work.
+
+Tasks are living work records. Their initial descriptions and acceptance criteria may be incomplete and may evolve during implementation as the human and agent investigate the problem.
+
+### General rules
+
+1. Before beginning substantial work, identify the relevant Backlog task and read it in full.
+2. Do not treat the initial task specification as immutable.
+3. Keep the task synchronized with the current shared understanding throughout the development session.
+4. Do not require the human to operate the Backlog CLI. Perform all necessary Backlog operations yourself.
+5. Use Backlog.md tasks, comments, plans, notes, and final summaries.
+6. Do not use Backlog.md decisions. Record durable architectural decisions as ADRs under `docs/adr/`.
+7. Only the human may accept a task as complete.
+
+### Comments
+
+Use task comments as a concise chronological record of material human-agent discussion.
+
+Add comments on behalf of both participants when the conversation produces information that would be useful in a future session, including:
+
+* clarification of ambiguous requirements;
+* answers to implementation questions;
+* requested changes in behavior or scope;
+* alternatives considered and rejected;
+* explicit human approvals or objections;
+* reasons for changing the implementation direction;
+* unresolved questions that affect further work.
+
+When recording comments:
+
+* Attribute each comment clearly as `Human` or `Agent`.
+* A comment attributed to `Human` must faithfully summarize something the human explicitly said or confirmed.
+* Do not invent, extrapolate, or strengthen the human's position.
+* Preserve important qualifications and uncertainty.
+* Prefer concise summaries over verbatim transcripts.
+* Do not record routine conversation, acknowledgements, minor corrections, or raw chat history.
+* Group closely related discussion into one comment when appropriate.
+* Record comments during the session when a material clarification occurs, rather than trying to reconstruct the entire conversation at the end.
+
+Example:
+
+> **Agent:** The existing importer permits identical entries from different source files. Should duplicate detection apply globally or only within one import?
+
+> **Human:** Duplicate detection should apply only within one import process. Identical entries from separate imports are allowed.
+
+Comments provide the historical trail, but they are not the canonical specification.
+
+### Updating the canonical task
+
+After a question is settled, update the relevant canonical part of the task:
+
+* update the description when the intended behavior or scope changes;
+* update acceptance criteria when testable requirements are clarified;
+* update the implementation plan when the technical approach changes;
+* update dependencies when newly discovered work blocks the task.
+
+A future agent should be able to understand the current requirements without reconstructing them from comments.
+
+Preserve the original intent where useful, but make the current description and acceptance criteria accurately represent the latest agreed behavior.
+
+When requirements remain uncertain, state the uncertainty explicitly rather than silently selecting an interpretation.
+
+### Notes
+
+Use task notes as durable working memory for implementation-related knowledge discovered during the task.
+
+Appropriate notes include:
+
+* relevant existing code and where it is located;
+* observed current behavior;
+* investigation results;
+* technical constraints;
+* external API or library behavior relevant to the task;
+* failed approaches and why they failed;
+* commands useful for reproducing or verifying behavior;
+* migration or compatibility concerns;
+* assumptions that still require verification;
+* risks and known limitations;
+* useful context for continuing the task in another agent session.
+
+Notes should contain distilled conclusions and evidence, not private reasoning or an exhaustive activity log.
+
+Good note:
+
+> Duplicate detection cannot use a database unique constraint because users may approve otherwise identical rows. Implement it in `ImportValidationService`, scoped by `ImportProcess.id`.
+
+Bad note:
+
+> I opened several files, thought about using a constraint, changed my mind, and then considered a service.
+
+Keep notes current:
+
+* correct notes that are proven wrong;
+* remove or clearly mark obsolete information;
+* preserve failed approaches only when knowing about them prevents repeated work;
+* distinguish confirmed facts from assumptions.
+
+### ADRs
+
+Do not create or use Backlog.md decision records.
+
+Create an ADR under `docs/adr/` when a decision:
+
+* affects multiple tasks or components;
+* defines a long-lived architectural rule;
+* changes an important data model, interface, dependency, or deployment approach;
+* involves meaningful alternatives and trade-offs;
+* is likely to matter after the current task is completed.
+
+Use the next available ADR number and the repository's ADR template.
+
+A task should link to relevant ADRs, for example:
+
+> Architectural context: `docs/adr/0012-store-monetary-values-as-integers.md`
+
+Task-specific choices that have no wider architectural significance should remain in the task comments, notes, or implementation plan.
+
+### Scope discovered during implementation
+
+Do not silently expand a task.
+
+When additional work is discovered:
+
+* incorporate it into the active task only when it is small, necessary to satisfy the agreed acceptance criteria, and does not materially broaden the scope;
+* otherwise create a separate Backlog task;
+* link the new task from the active task;
+* state whether it blocks the active task or is follow-up work.
+
+### Session checkpoints
+
+Update the Backlog task at natural checkpoints:
+
+1. after initial investigation;
+2. after a material requirement clarification;
+3. after a significant change in implementation approach;
+4. before ending a session with unfinished work;
+5. before requesting human review.
+
+Before ending an unfinished session, ensure that another agent can continue from the task without requiring access to the previous chat.
+
+At minimum, record:
+
+* the current state of implementation;
+* settled requirements;
+* remaining open questions;
+* relevant findings;
+* the next concrete action;
+* commands or tests needed to continue.
+
+### Completion
+
+Before moving a task to human review:
+
+1. Re-read the complete task.
+2. Ensure the description and acceptance criteria reflect the final agreed scope.
+3. Ensure all material session decisions are represented in the canonical task, comments, notes, or an ADR.
+4. Update acceptance-criteria checkboxes based on verified behavior.
+5. Add a final summary containing:
+
+   * what changed;
+   * important implementation choices;
+   * tests and checks performed;
+   * known limitations;
+   * follow-up tasks;
+   * ADRs created or referenced.
+6. Move the task to the review state, not directly to accepted or complete.
+7. Leave final acceptance to the human.
+
+<!-- BACKLOG.MD GUIDELINES START -->
+<!-- backlog.md-instructions-version: 1.50.1 -->
+<CRITICAL_INSTRUCTION>
+
+## Backlog.md Workflow
+
+This project uses Backlog.md for task and project management.
+
+**For every user request in this project, run `backlog instructions overview` before answering or taking action.**
+
+Use the overview to decide whether to search, read, create, or update Backlog tasks.
+
+Before task lifecycle actions, read the matching detailed guide:
+- `backlog instructions task-creation` before creating or splitting tasks
+- `backlog instructions task-execution` before planning, changing status or assignee, adding a plan or implementation notes, or implementing task work
+- `backlog instructions task-finalization` before checking acceptance criteria, writing final summaries, or moving tasks to terminal statuses
+
+Use `backlog <command> --help` before running unfamiliar commands. Help shows options, fields, and examples.
+
+Do not edit Backlog task, draft, document, decision, or milestone markdown files directly. Use the `backlog` CLI so metadata, relationships, and history stay consistent.
+
+</CRITICAL_INSTRUCTION>
+<!-- BACKLOG.MD GUIDELINES END -->

pstq-0.1.0/CHANGELOG.md

@@ -0,0 +1,5 @@
+# History
+
+## 0.1.0 (2026-08-31)
+
+* First release on PyPI.

pstq-0.1.0/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026, Josef Nevrly
+
+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.
+