Skip to content

Commit 092a796

Browse files
ma2zama2za
committed
Prepare Python Substack for cloud development
1 parent d3b5957 commit 092a796

8 files changed

Lines changed: 385 additions & 243 deletions

File tree

‎.gitattributes‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
scripts/*.sh text eol=lf

‎.gitignore‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -103,7 +103,10 @@ celerybeat.pid
103103

104104
# Environments
105105
.env
106+
.env.*
107+
!.env.example
106108
.venv
109+
.tools/
107110
env/
108111
venv/
109112
ENV/

‎AGENTS.md‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,20 @@
33
This file is the public source of guidance for any coding agent working in
44
this repository. Read it before inspecting, changing, or running the project.
55

6+
For a clean Linux checkout, follow `CODEX_CLOUD.md` and run:
7+
8+
```bash
9+
bash scripts/codex-cloud-setup.sh
10+
export PATH="$PWD/.tools/poetry/bin:$PATH"
11+
poetry run pytest -q -m "not live" --strict-markers
12+
```
13+
14+
Keep live-test opt-ins unset for ordinary development. Live Substack operations
15+
require authorization and must never publish test content.
16+
17+
Keep the repository public. Never change repository visibility unless the user
18+
explicitly requests that change for this repository.
19+
620
Private local maintainer guidance and optional workflows may live under
721
`.agents/`. Read the relevant files when they are available:
822

‎CHANGELOG.md‎

Lines changed: 252 additions & 243 deletions
Large diffs are not rendered by default.

‎CODEX_CLOUD.md‎

Lines changed: 94 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,94 @@
1+
# Cloud development handover
2+
3+
Repository: <https://github.com/ma2za/python-substack>, branch `main`.
4+
The repository remains public. Package version: `0.10.0`.
5+
6+
## Environment setup
7+
8+
Use Python 3.10 or newer; Python 3.12 is recommended for the cloud environment.
9+
The CI matrix covers Python 3.10 through 3.14. Git and Bash are required.
10+
11+
Run this from the checkout as the cloud environment's install script:
12+
13+
```bash
14+
bash scripts/codex-cloud-setup.sh
15+
```
16+
17+
The script installs Poetry 2.3.2 in `.tools/poetry`, installs the locked project
18+
dependencies and all extras in `.venv`, and installs the pre-commit hook. It
19+
requires package-registry access. It can be rerun on an existing checkout.
20+
No credentials or external services are required for development setup.
21+
22+
In each new shell, make the isolated Poetry executable available:
23+
24+
```bash
25+
export PATH="$PWD/.tools/poetry/bin:$PATH"
26+
```
27+
28+
The setup is checked into Git; no workstation virtual environment, editor
29+
configuration, or shared parent-directory `.env` is needed.
30+
31+
## Validation
32+
33+
```bash
34+
poetry run pytest -q -m "not live" --strict-markers
35+
poetry run pytest -q --strict-markers
36+
poetry run pre-commit run --all-files
37+
poetry check
38+
poetry build
39+
poetry run python -m twine check dist/*
40+
```
41+
42+
Keep `RUN_SUBSTACK_E2E` and `RUN_SUBSTACK_CLI_E2E` unset for ordinary development.
43+
The first test command excludes live tests; the second verifies they skip with
44+
live opt-ins unset. Live tests create and delete real Substack drafts and need
45+
explicit authorization for the operation. Follow [CONTRIBUTING.md](CONTRIBUTING.md)
46+
and [docs/releasing.md](docs/releasing.md) before any live or release work.
47+
48+
## Authentication
49+
50+
Offline tests and package validation need no Substack credentials. For an
51+
authorized live task, configure fresh values in the cloud environment:
52+
53+
- `PUBLICATION_URL`: the publication selected for the task.
54+
- `COOKIES_STRING`: a cookie string, or `COOKIES_PATH`: a cookie file supplied
55+
within that environment.
56+
- Alternatively, `EMAIL` and `PASSWORD` for password authentication.
57+
58+
Use the environment's protected configuration or personal vault for credentials.
59+
The program must be able to read authentication values directly. See
60+
[official cloud environment documentation](https://learn.chatgpt.com/docs/environments/cloud-environments)
61+
and [docs/authentication.md](docs/authentication.md).
62+
63+
Never put real values in source files, example configuration, workflow output,
64+
or documentation. GitHub Actions secrets do not automatically configure Codex
65+
Cloud authentication. A local cookie file path cannot carry over to a new cloud
66+
environment.
67+
68+
## Continuing work
69+
70+
Read [AGENTS.md](AGENTS.md), [CHANGELOG.md](CHANGELOG.md), and the relevant tests
71+
before making changes. Preserve the current package version during ordinary
72+
development and keep `poetry.lock` unchanged unless dependencies change.
73+
74+
This handover does not publish a package, create a release, or operate on a
75+
Substack publication. Package publication remains governed by
76+
[docs/releasing.md](docs/releasing.md) and the existing tag-gated Trusted
77+
Publishing workflow.
78+
79+
## Validation checkpoint
80+
81+
Validated on 2026-10-12 in a clean Python 3.12 Linux container with no Substack
82+
credentials:
83+
84+
- Cloud setup passed twice with the dependency lock file unchanged.
85+
- Offline suite: 267 passed, 8 live tests deselected.
86+
- Normal suite with opt-ins unset: 267 passed, 8 live tests skipped.
87+
- Strict collection: 275 tests collected.
88+
- All five repository hooks, Bash syntax, and ShellCheck passed.
89+
- Poetry validation, wheel/sdist build, and Twine checks passed.
90+
- Fresh base wheel, MCP wheel, and sdist installs passed their smoke checks.
91+
- Project, tooling, and fresh package environments passed `pip check`.
92+
93+
No live tests, Substack writes, package publication, or release creation were
94+
performed for this checkpoint.

‎CONTRIBUTING.md‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,16 @@
22

33
## Setup
44

5+
For a clean Linux or Codex Cloud checkout, install the pinned Poetry tool and
6+
locked development dependencies:
7+
8+
```bash
9+
bash scripts/codex-cloud-setup.sh
10+
export PATH="$PWD/.tools/poetry/bin:$PATH"
11+
```
12+
13+
See [CODEX_CLOUD.md](CODEX_CLOUD.md) for cloud configuration and handover context.
14+
515
Fork and clone the repository, then install the package and all optional
616
dependencies:
717

‎README.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -252,6 +252,7 @@ See [MCP server](docs/mcp.md) for the tool list and safety notes.
252252
- [YAML drafts](docs/yaml.md)
253253
- [MCP server](docs/mcp.md)
254254
- [Agent workflow](docs/agents.md)
255+
- [Cloud development](CODEX_CLOUD.md)
255256
- [Safety and publishing behavior](docs/safety.md)
256257
- [Troubleshooting](docs/troubleshooting.md)
257258
- [Compatibility policy](docs/compatibility.md)

‎scripts/codex-cloud-setup.sh‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
#!/bin/bash
2+
set -euo pipefail
3+
4+
cd "$(dirname "${BASH_SOURCE[0]}")/.."
5+
python3 -c 'import sys; assert (3, 10) <= sys.version_info < (4, 0), "Python 3.10 or newer is required"'
6+
python3 -m venv .tools/poetry
7+
.tools/poetry/bin/python -m pip install poetry==2.3.2
8+
export POETRY_VIRTUALENVS_IN_PROJECT=true
9+
.tools/poetry/bin/python -m poetry install --with dev --all-extras
10+
.tools/poetry/bin/python -m poetry run pre-commit install

0 commit comments

Comments
 (0)