prompt-diary 0.1.0__tar.gz

prompt_diary-0.1.0/PKG-INFO

@@ -0,0 +1,121 @@
+Metadata-Version: 2.3
+Name: prompt-diary
+Version: 0.1.0
+Summary: Review user prompts for evidence-backed improvement in AI coding collaboration.
+Requires-Dist: jinja2>=3.1
+Requires-Dist: mcp>=1.2
+Requires-Dist: msgspec>=0.21.1
+Requires-Dist: notion-client>=2.0
+Requires-Dist: openai-codex>=0.1.0b2
+Requires-Dist: platformdirs>=4.0
+Requires-Dist: rich>=13
+Requires-Dist: typer>=0.25.1
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# Prompt Diary
+
+Language: English | [简体中文](README.zh-CN.md)
+
+[![CI](https://github.com/OptimalCNC/prompt-diary/actions/workflows/ci.yml/badge.svg)](https://github.com/OptimalCNC/prompt-diary/actions/workflows/ci.yml)
+[![Publish](https://github.com/OptimalCNC/prompt-diary/actions/workflows/publish.yml/badge.svg)](https://github.com/OptimalCNC/prompt-diary/actions/workflows/publish.yml)
+[![PyPI](https://img.shields.io/pypi/v/prompt-diary.svg)](https://pypi.org/project/prompt-diary/)
+![Coverage budget](https://img.shields.io/badge/coverage%20budget-100%25-brightgreen.svg)
+
+Prompt Diary prepares bounded workspaces from local assistant session history and generates evidenced prompt diary reports that help users review and improve how they collaborate with AI coding agents.
+
+The tool targets Python 3.10 and newer. The package exposes `report` and `prompt-diary`
+console commands after installation.
+
+## Usage
+
+Install Prompt Diary from PyPI as an isolated uv tool:
+
+```bash
+uv tool install prompt-diary
+```
+
+Then run:
+
+```bash
+report --help
+prompt-diary --help
+report prepare --date 2026-05-12 --timezone Asia/Shanghai
+report generate --date 2026-05-12 --timezone Asia/Shanghai
+report render notion --date 2026-05-12 --timezone Asia/Shanghai
+```
+
+Generation is an artifact-first pipeline with standalone phase commands:
+
+```bash
+report generate evidence --date 2026-05-12 --timezone Asia/Shanghai --project-key <project> --session-ref S0001
+report generate project --date 2026-05-12 --timezone Asia/Shanghai --project-key <project>
+report generate daily --date 2026-05-12 --timezone Asia/Shanghai
+```
+
+Once Notion is configured, `report render notion` can publish an already-generated report as a new
+row in the Notion database. It resolves the existing workspace, requires `daily-report.json`,
+regenerates the deterministic `report.notion.json` payload beside `report.md`, and publishes that
+payload. `report generate` delegates to the same render path after a successful pipeline: by default
+it publishes when Notion is configured; pass `--no-notion` to skip publishing, or `--notion` to
+require it (which errors if Notion is not configured). Configure the Notion integration token and
+target database id once with `prompt-diary config init` (see [Configuration](#configuration));
+credentials never pass on the command line. Each run appends a new dated row; re-publishing never
+edits or deletes existing rows.
+
+Generation drives a three-phase, artifact-first pipeline — evidence extraction, then project
+synthesis, then daily report synthesis — through the Codex CLI, producing `daily-report.json`, the
+rendered `report.md`, and `report.notion.json`. It requires the `codex` CLI to be installed and
+authenticated; the subcommands above run each phase standalone against an already-prepared workspace.
+
+Prepared workspaces and generated reports are written under a per-user data directory by default
+(`~/.local/share/prompt-diary/` on Linux; the platform equivalent on macOS and Windows), organized
+by date as `<reports-root>/work/<YYYY-MM-DD>/`. Override the location with `--reports-root <path>` on
+`prepare`, `generate`, and `render notion`, `PROMPT_DIARY_HOME`, or the stored config (see
+[Configuration](#configuration)); precedence is `--reports-root` over `PROMPT_DIARY_HOME` over the
+stored config over the default data directory. (Earlier versions wrote to `./.reports` in the current directory — pass
+`--reports-root .reports` to keep using an existing local directory.)
+
+Both `prepare` and `generate` show a live progress dashboard when running on a TTY and write
+append-only log lines when output is piped, redirected, or running in CI. Pass `--quiet` to either
+command to suppress the live output and print only the final summary.
+
+## Configuration
+
+Run `prompt-diary config init` once to set up credentials and settings interactively. It prompts for
+the Notion integration token, an optional data folder, the Notion database id, and an optional
+reporter name (a free-form label, like `git config user.name`, written into the `汇报人` column at
+publish time). Each credential is validated live against the Notion API and saved the moment it
+passes — the token check reports the
+authenticated integration and workspace, and the database check reports the connected database's name
+— so an interrupted run keeps whatever was already verified. Everything is written to a single config
+file with `0600` permissions. The token is read only from that file or the environment — never passed
+on the command line, and never printed (`config show` masks it).
+
+```bash
+prompt-diary config init   # interactive setup; validates the token and database live
+prompt-diary config show   # print the configuration (token masked) and the file location
+prompt-diary config path   # print the config file location
+```
+
+The config file lives under the per-user config directory (`~/.config/prompt-diary/config.json` on
+Linux; the platform equivalent on macOS and Windows), overridable with `PROMPT_DIARY_CONFIG`. Each
+setting is resolved from the first source that provides it: a CLI flag (where one exists), then the
+environment, then the stored config, then a built-in default (where one exists). So `NOTION_API_KEY`
+/ `NOTION_PAGE_ID` and `--reports-root` / `PROMPT_DIARY_HOME` still override the stored config (useful
+in CI). Once Notion is configured — including via those environment variables — a bare `report
+generate` publishes by default; pass `--no-notion` in CI or any pipeline that should not publish.
+
+## Development
+
+This project uses [`uv`](https://docs.astral.sh/uv/) for Python version, environment,
+dependency, build, and release workflows.
+
+Read [`docs/src/product.md`](docs/src/product.md) before designing new features, changing report
+content, or modifying the generation pipeline. It defines the tool's purposes and principles that
+downstream design must satisfy.
+
+For environment setup, build commands, type checking, testing, coverage, linting, and pre-submit
+checks, including the optional Ubuntu 24.04 devcontainer, see the
+[Development Guide](docs/src/dev/guide.md). For codebase architecture and API design, see
+[Architecture](docs/src/dev/architecture.md).

prompt_diary-0.1.0/README.md

@@ -0,0 +1,106 @@
+# Prompt Diary
+
+Language: English | [简体中文](README.zh-CN.md)
+
+[![CI](https://github.com/OptimalCNC/prompt-diary/actions/workflows/ci.yml/badge.svg)](https://github.com/OptimalCNC/prompt-diary/actions/workflows/ci.yml)
+[![Publish](https://github.com/OptimalCNC/prompt-diary/actions/workflows/publish.yml/badge.svg)](https://github.com/OptimalCNC/prompt-diary/actions/workflows/publish.yml)
+[![PyPI](https://img.shields.io/pypi/v/prompt-diary.svg)](https://pypi.org/project/prompt-diary/)
+![Coverage budget](https://img.shields.io/badge/coverage%20budget-100%25-brightgreen.svg)
+
+Prompt Diary prepares bounded workspaces from local assistant session history and generates evidenced prompt diary reports that help users review and improve how they collaborate with AI coding agents.
+
+The tool targets Python 3.10 and newer. The package exposes `report` and `prompt-diary`
+console commands after installation.
+
+## Usage
+
+Install Prompt Diary from PyPI as an isolated uv tool:
+
+```bash
+uv tool install prompt-diary
+```
+
+Then run:
+
+```bash
+report --help
+prompt-diary --help
+report prepare --date 2026-05-12 --timezone Asia/Shanghai
+report generate --date 2026-05-12 --timezone Asia/Shanghai
+report render notion --date 2026-05-12 --timezone Asia/Shanghai
+```
+
+Generation is an artifact-first pipeline with standalone phase commands:
+
+```bash
+report generate evidence --date 2026-05-12 --timezone Asia/Shanghai --project-key <project> --session-ref S0001
+report generate project --date 2026-05-12 --timezone Asia/Shanghai --project-key <project>
+report generate daily --date 2026-05-12 --timezone Asia/Shanghai
+```
+
+Once Notion is configured, `report render notion` can publish an already-generated report as a new
+row in the Notion database. It resolves the existing workspace, requires `daily-report.json`,
+regenerates the deterministic `report.notion.json` payload beside `report.md`, and publishes that
+payload. `report generate` delegates to the same render path after a successful pipeline: by default
+it publishes when Notion is configured; pass `--no-notion` to skip publishing, or `--notion` to
+require it (which errors if Notion is not configured). Configure the Notion integration token and
+target database id once with `prompt-diary config init` (see [Configuration](#configuration));
+credentials never pass on the command line. Each run appends a new dated row; re-publishing never
+edits or deletes existing rows.
+
+Generation drives a three-phase, artifact-first pipeline — evidence extraction, then project
+synthesis, then daily report synthesis — through the Codex CLI, producing `daily-report.json`, the
+rendered `report.md`, and `report.notion.json`. It requires the `codex` CLI to be installed and
+authenticated; the subcommands above run each phase standalone against an already-prepared workspace.
+
+Prepared workspaces and generated reports are written under a per-user data directory by default
+(`~/.local/share/prompt-diary/` on Linux; the platform equivalent on macOS and Windows), organized
+by date as `<reports-root>/work/<YYYY-MM-DD>/`. Override the location with `--reports-root <path>` on
+`prepare`, `generate`, and `render notion`, `PROMPT_DIARY_HOME`, or the stored config (see
+[Configuration](#configuration)); precedence is `--reports-root` over `PROMPT_DIARY_HOME` over the
+stored config over the default data directory. (Earlier versions wrote to `./.reports` in the current directory — pass
+`--reports-root .reports` to keep using an existing local directory.)
+
+Both `prepare` and `generate` show a live progress dashboard when running on a TTY and write
+append-only log lines when output is piped, redirected, or running in CI. Pass `--quiet` to either
+command to suppress the live output and print only the final summary.
+
+## Configuration
+
+Run `prompt-diary config init` once to set up credentials and settings interactively. It prompts for
+the Notion integration token, an optional data folder, the Notion database id, and an optional
+reporter name (a free-form label, like `git config user.name`, written into the `汇报人` column at
+publish time). Each credential is validated live against the Notion API and saved the moment it
+passes — the token check reports the
+authenticated integration and workspace, and the database check reports the connected database's name
+— so an interrupted run keeps whatever was already verified. Everything is written to a single config
+file with `0600` permissions. The token is read only from that file or the environment — never passed
+on the command line, and never printed (`config show` masks it).
+
+```bash
+prompt-diary config init   # interactive setup; validates the token and database live
+prompt-diary config show   # print the configuration (token masked) and the file location
+prompt-diary config path   # print the config file location
+```
+
+The config file lives under the per-user config directory (`~/.config/prompt-diary/config.json` on
+Linux; the platform equivalent on macOS and Windows), overridable with `PROMPT_DIARY_CONFIG`. Each
+setting is resolved from the first source that provides it: a CLI flag (where one exists), then the
+environment, then the stored config, then a built-in default (where one exists). So `NOTION_API_KEY`
+/ `NOTION_PAGE_ID` and `--reports-root` / `PROMPT_DIARY_HOME` still override the stored config (useful
+in CI). Once Notion is configured — including via those environment variables — a bare `report
+generate` publishes by default; pass `--no-notion` in CI or any pipeline that should not publish.
+
+## Development
+
+This project uses [`uv`](https://docs.astral.sh/uv/) for Python version, environment,
+dependency, build, and release workflows.
+
+Read [`docs/src/product.md`](docs/src/product.md) before designing new features, changing report
+content, or modifying the generation pipeline. It defines the tool's purposes and principles that
+downstream design must satisfy.
+
+For environment setup, build commands, type checking, testing, coverage, linting, and pre-submit
+checks, including the optional Ubuntu 24.04 devcontainer, see the
+[Development Guide](docs/src/dev/guide.md). For codebase architecture and API design, see
+[Architecture](docs/src/dev/architecture.md).

prompt_diary-0.1.0/pyproject.toml

@@ -0,0 +1,172 @@
+[project]
+name = "prompt-diary"
+version = "0.1.0"
+description = "Review user prompts for evidence-backed improvement in AI coding collaboration."
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = [
+    "jinja2>=3.1",
+    "mcp>=1.2",
+    "msgspec>=0.21.1",
+    "notion-client>=2.0",
+    "openai-codex>=0.1.0b2",
+    "platformdirs>=4.0",
+    "rich>=13",
+    "typer>=0.25.1",
+]
+
+[project.scripts]
+prompt-diary = "prompt_diary.cli:main"
+report = "prompt_diary.cli:main"
+
+[build-system]
+requires = ["uv_build>=0.11.6,<0.12"]
+build-backend = "uv_build"
+
+[tool.basedpyright]
+include = ["src", "tests"]
+pythonVersion = "3.10"
+typeCheckingMode = "strict"
+reportMissingTypeStubs = false
+venv = ".venv"
+venvPath = "."
+
+[tool.pytest.ini_options]
+minversion = "9.0"
+testpaths = ["tests"]
+addopts = [
+    "--strict-config",
+    "--strict-markers",
+]
+markers = [
+    "codex_mcp: opt-in Codex MCP integration contract tests",
+]
+
+[tool.coverage.run]
+source = ["prompt_diary"]
+omit = [
+    "src/prompt_diary/integrations/codex_runner.py",
+    "src/prompt_diary/progress/console.py",
+    # The real Notion SDK adapter is exercised by the live publish path, not the unit suite (the
+    # publisher logic is fully tested against a fake), like codex_runner.py above.
+    "src/prompt_diary/generate/daily_synthesis/notion_client_adapter.py",
+]
+
+[tool.coverage.report]
+fail_under = 100
+show_missing = true
+exclude_also = [
+    # Unreachable defensive fallback: the loop always finds the trigger's own
+    # non-scaffolding record before exhausting all lines.
+    "return next_trigger_line - 1",
+]
+
+[tool.uv]
+dependency-metadata = [
+    # openai-codex 0.1.0b2 pins openai-codex-cli-bin==0.132.0, but that runtime
+    # release has no manylinux wheel. Prompt Diary passes an explicit local codex
+    # binary to CodexConfig, so the SDK package itself is the needed dependency.
+    { name = "openai-codex", version = "0.1.0b2", requires-dist = ["pydantic>=2.12"], requires-python = ">=3.10" },
+]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+src = ["src", "tests"]
+extend-exclude = ["export_codex_user_history.py"]
+
+[tool.ruff.lint]
+select = [
+    # pycodestyle
+    "E",
+    "W",
+    # Pyflakes
+    "F",
+    # isort
+    "I",
+    # pyupgrade
+    "UP",
+    # flake8-bugbear
+    "B",
+    # flake8-builtins
+    "A",
+    # flake8-unused-arguments
+    "ARG",
+    # flake8-blind-except
+    "BLE",
+    # flake8-comprehensions
+    "C4",
+    # mccabe
+    "C90",
+    # flake8-datetimez
+    "DTZ",
+    # eradicate
+    "ERA",
+    # flake8-boolean-trap
+    "FBT",
+    # flake8-logging
+    "LOG",
+    # flake8-logging-format
+    "G",
+    # flake8-no-pep420
+    "INP",
+    # pep8-naming
+    "N",
+    # Perflint
+    "PERF",
+    # flake8-pie
+    "PIE",
+    # Pylint convention, error, and warning rules.
+    "PLC",
+    "PLE",
+    "PLW",
+    # flake8-pytest-style
+    "PT",
+    # flake8-use-pathlib
+    "PTH",
+    # flake8-return
+    "RET",
+    # flake8-raise
+    "RSE",
+    # flake8-bandit
+    "S",
+    # flake8-simplify
+    "SIM",
+    # flake8-type-checking
+    "TC",
+    # flake8-tidy-imports
+    "TID",
+    # tryceratops
+    "TRY",
+    # flake8-2020
+    "YTT",
+    # Ruff-specific rules
+    "RUF",
+]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**" = [
+    # Allow pytest assertions in tests.
+    "S101",
+    # Test fixtures use fake/sentinel credentials, not real secrets.
+    "S105",
+]
+
+[tool.ruff.lint.isort]
+known-first-party = ["prompt_diary"]
+
+[tool.ruff.lint.mccabe]
+max-complexity = 10
+
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"
+line-ending = "lf"
+
+[dependency-groups]
+dev = [
+    "basedpyright>=1.39.4",
+    "coverage[toml]>=7.14.0",
+    "pytest>=9.0.3",
+    "ruff>=0.15.12",
+]

prompt_diary-0.1.0/src/prompt_diary/__init__.py

@@ -0,0 +1,5 @@
+"""Prompt Diary package."""
+
+__all__ = ["__version__"]
+
+__version__ = "0.1.0"

prompt_diary-0.1.0/src/prompt_diary/agent.py

@@ -0,0 +1,78 @@
+"""Neutral agent execution contract shared by generation phases and runner adapters."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Protocol
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping
+    from pathlib import Path
+    from types import TracebackType
+
+
+@dataclass(frozen=True)
+class AgentConfig:
+    """Per-conversation agent configuration."""
+
+    working_directory: Path
+    model: str | None = None
+    model_provider: str | None = None
+    reasoning_effort: str | None = None
+    approval_mode: str | None = None
+    sandbox: str | None = None
+    base_instructions: str | None = None
+    developer_instructions: str | None = None
+    personality: str | None = None
+
+
+@dataclass(frozen=True)
+class AgentTurnEvent:
+    """Structured event summary emitted while running one agent turn."""
+
+    kind: str
+    summary: str
+    metadata: Mapping[str, object]
+
+
+@dataclass(frozen=True)
+class AgentTurnResult:
+    """Result from one agent turn."""
+
+    assistant_text: str
+    events: tuple[AgentTurnEvent, ...]
+
+
+class AgentRunner(Protocol):
+    """One agent conversation. Turns run sequentially on a single instance."""
+
+    async def turn(
+        self,
+        prompt: str,
+        *,
+        timeout_seconds: float = 600.0,
+        output_schema: Mapping[str, object] | None = None,
+    ) -> AgentTurnResult:
+        """Run one prompt turn and return its structured result."""
+        ...
+
+
+class AgentSessionFactory(Protocol):
+    """Owns one shared backend and mints a fresh agent conversation per call."""
+
+    async def __aenter__(self) -> AgentSessionFactory:
+        """Start the shared backend."""
+        ...
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> bool | None:
+        """Stop the shared backend."""
+        ...
+
+    async def runner(self, config: AgentConfig) -> AgentRunner:
+        """Return a fresh agent conversation bound to the shared backend."""
+        ...

prompt_diary-0.1.0/src/prompt_diary/cli.py

@@ -0,0 +1,42 @@
+"""Typer command-line entrypoint for Prompt Diary."""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+import typer
+
+from prompt_diary import __version__
+from prompt_diary.cmds import config, generate, mcp, prepare, prompts, render
+
+app = typer.Typer(
+    add_completion=False,
+    help="Prepare and generate evidence-backed prompt diary reports.",
+    invoke_without_command=True,
+    no_args_is_help=True,
+)
+
+VersionOption = Annotated[
+    bool,
+    typer.Option("--version", help="Show the version and exit.", is_eager=True),
+]
+
+
+@app.callback()
+def app_callback(*, version: VersionOption = False) -> None:
+    """Prompt Diary command group."""
+    if version:
+        typer.echo(__version__)
+        raise typer.Exit
+
+
+prepare.register(app)
+generate.register(app)
+config.register(app)
+prompts.register(app)
+render.register(app)
+mcp.register(app)
+
+
+def main() -> None:
+    app()

prompt_diary-0.1.0/src/prompt_diary/cmds/__init__.py

@@ -0,0 +1 @@
+"""Typer command modules for Prompt Diary."""

prompt_diary-0.1.0/src/prompt_diary/cmds/common.py

@@ -0,0 +1,53 @@
+"""Shared CLI helpers."""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+from typing import TYPE_CHECKING, Annotated, NoReturn
+
+import typer
+
+from prompt_diary.progress.console import build_reporter
+from prompt_diary.progress.reporter import select_reporter_mode
+
+if TYPE_CHECKING:
+    from collections.abc import Iterable
+
+    from prompt_diary.errors import PromptDiaryError
+    from prompt_diary.progress.reporter import ProgressReporter
+
+DateOption = Annotated[str | None, typer.Option(help="Target local date in YYYY-MM-DD format.")]
+TodayOption = Annotated[bool, typer.Option(help="Target the current local day.")]
+TimezoneOption = Annotated[
+    str | None,
+    typer.Option(help="IANA timezone name, e.g. Asia/Shanghai."),
+]
+QuietOption = Annotated[bool, typer.Option(help="Suppress progress; print only the final summary.")]
+ReportsRootOption = Annotated[
+    Path | None,
+    typer.Option(
+        help=(
+            "Directory for report workspaces. Defaults to the per-user data directory "
+            "(override with $PROMPT_DIARY_HOME)."
+        ),
+    ),
+]
+
+
+def build_cli_reporter(*, quiet: bool) -> ProgressReporter:
+    """Build the progress reporter for a CLI invocation."""
+    mode = select_reporter_mode(quiet=quiet, isatty=sys.stderr.isatty())
+    return build_reporter(mode)
+
+
+def echo_messages(messages: Iterable[str]) -> None:
+    """Print workflow messages."""
+    for message in messages:
+        typer.echo(message)
+
+
+def exit_with_error(exc: PromptDiaryError) -> NoReturn:
+    """Print an actionable error and exit with the workflow error code."""
+    typer.echo(f"Error: {exc}", err=True)
+    raise typer.Exit(2) from exc