zensical-updates 0.1.0__tar.gz

zensical_updates-0.1.0/.gitignore

@@ -0,0 +1,42 @@
+# Python
+__pycache__/
+*.pyc
+*.pyo
+*.egg-info/
+dist/
+build/
+*.egg
+
+# uv
+.venv/
+
+# Testing & coverage
+.pytest_cache/
+.coverage
+.coverage.*
+coverage.xml
+test-results.xml
+htmlcov/
+pytest.log
+*.sarif
+
+# All CI / build reports go here
+.reports/
+
+# Docs site build output (zensical)
+/site/
+
+# Environment
+.env
+.env.local
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Editors
+*.swp
+*.swo
+*~
+.idea/
+.vscode/

zensical_updates-0.1.0/CHANGELOG.md

@@ -0,0 +1,30 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/),
+and this project adheres to [Semantic Versioning](https://semver.org/).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-06-17
+
+### Added
+
+- Initial project scaffold.
+- Post discovery and the content model: YAML front-matter parsing (block-list
+  aware), post loading (slug from file stem, date coercion, taxonomies,
+  excerpt), newest-first discovery, and grouping by category, tag, and year.
+- Markdown emitters for the index listing, archive landing and per-year pages,
+  and tag/category pages and their indexes. Output is zensical-safe: every link
+  is a site-absolute directory URL and there are no bare reference brackets.
+- A `build`/`clean` CLI and a `zensical.toml` config loader (the
+  `[project.extra.zensical_updates]` table). `build` discovers source posts,
+  copies them into `docs/<base>/`, and writes the generated pages; `clean`
+  removes that output. An invalid post (e.g. missing date) fails the build.
+- An end-to-end integration test: generate a fixture site, run
+  `zensical build --clean --strict`, and assert every generated post,
+  taxonomy, and archive link resolves to a rendered page. This guards the two
+  silent failures (wrong post URLs and front-matter link reads).
+- Documentation: README and a usage guide covering how to write posts,
+  configure the generator, and run the build.

zensical_updates-0.1.0/LICENSE.md

@@ -0,0 +1,121 @@
+# CC0 1.0 Universal
+
+Creative Commons Legal Code
+
+    CREATIVE COMMONS CORPORATION IS NOT A LAW FIRM AND DOES NOT PROVIDE
+    LEGAL SERVICES. DISTRIBUTION OF THIS DOCUMENT DOES NOT CREATE AN
+    ATTORNEY-CLIENT RELATIONSHIP. CREATIVE COMMONS PROVIDES THIS
+    INFORMATION ON AN "AS-IS" BASIS. CREATIVE COMMONS MAKES NO WARRANTIES
+    REGARDING THE USE OF THIS DOCUMENT OR THE INFORMATION OR WORKS
+    PROVIDED HEREUNDER, AND DISCLAIMS LIABILITY FOR DAMAGES RESULTING FROM
+    THE USE OF THIS DOCUMENT OR THE INFORMATION OR WORKS PROVIDED
+    HEREUNDER.
+
+## Statement of Purpose
+
+The laws of most jurisdictions throughout the world automatically confer
+exclusive Copyright and Related Rights (defined below) upon the creator
+and subsequent owner(s) (each and all, an "owner") of an original work of
+authorship and/or a database (each, a "Work").
+
+Certain owners wish to permanently relinquish those rights to a Work for
+the purpose of contributing to a commons of creative, cultural and
+scientific works ("Commons") that the public can reliably and without fear
+of later claims of infringement build upon, modify, incorporate in other
+works, reuse and redistribute as freely as possible in any form whatsoever
+and for any purposes, including without limitation commercial purposes.
+These owners may contribute to the Commons to promote the ideal of a free
+culture and the further production of creative, cultural and scientific
+works, or to gain reputation or greater distribution for their Work in
+part through the use and efforts of others.
+
+For these and/or other purposes and motivations, and without any
+expectation of additional consideration or compensation, the person
+associating CC0 with a Work (the "Affirmer"), to the extent that he or she
+is an owner of Copyright and Related Rights in the Work, voluntarily
+elects to apply CC0 to the Work and publicly distribute the Work under its
+terms, with knowledge of his or her Copyright and Related Rights in the
+Work and the meaning and intended legal effect of CC0 on those rights.
+
+1. Copyright and Related Rights. A Work made available under CC0 may be
+protected by copyright and related or neighboring rights ("Copyright and
+Related Rights"). Copyright and Related Rights include, but are not
+limited to, the following:
+
+  i. the right to reproduce, adapt, distribute, perform, display,
+     communicate, and translate a Work;
+ ii. moral rights retained by the original author(s) and/or performer(s);
+iii. publicity and privacy rights pertaining to a person's image or
+     likeness depicted in a Work;
+ iv. rights protecting against unfair competition in regards to a Work,
+     subject to the limitations in paragraph 4(a), below;
+  v. rights protecting the extraction, dissemination, use and reuse of data
+     in a Work;
+ vi. database rights (such as those arising under Directive 96/9/EC of the
+     European Parliament and of the Council of 11 March 1996 on the legal
+     protection of databases, and under any national implementation
+     thereof, including any amended or successor version of such
+     directive); and
+vii. other similar, equivalent or corresponding rights throughout the
+     world based on applicable law or treaty, and any national
+     implementations thereof.
+
+2. Waiver. To the greatest extent permitted by, but not in contravention
+of, applicable law, Affirmer hereby overtly, fully, permanently,
+irrevocably and unconditionally waives, abandons, and surrenders all of
+Affirmer's Copyright and Related Rights and associated claims and causes
+of action, whether now known or unknown (including existing as well as
+future claims and causes of action), in the Work (i) in all territories
+worldwide, (ii) for the maximum duration provided by applicable law or
+treaty (including future time extensions), (iii) in any current or future
+medium and for any number of copies, and (iv) for any purpose whatsoever,
+including without limitation commercial, advertising or promotional
+purposes (the "Waiver"). Affirmer makes the Waiver for the benefit of each
+member of the public at large and to the detriment of Affirmer's heirs and
+successors, fully intending that such Waiver shall not be subject to
+revocation, rescission, cancellation, termination, or any other legal or
+equitable action to disrupt the quiet enjoyment of the Work by the public
+as contemplated by Affirmer's express Statement of Purpose.
+
+3. Public License Fallback. Should any part of the Waiver for any reason
+be judged legally invalid or ineffective under applicable law, then the
+Waiver shall be preserved to the maximum extent permitted taking into
+account Affirmer's express Statement of Purpose. In addition, to the
+extent the Waiver is so judged Affirmer hereby grants to each affected
+person a royalty-free, non transferable, non sublicensable, non exclusive,
+irrevocable and unconditional license to exercise Affirmer's Copyright and
+Related Rights in the Work (i) in all territories worldwide, (ii) for the
+maximum duration provided by applicable law or treaty (including future
+time extensions), (iii) in any current or future medium and for any number
+of copies, and (iv) for any purpose whatsoever, including without
+limitation commercial, advertising or promotional purposes (the
+"License"). The License shall be deemed effective as of the date CC0 was
+applied by Affirmer to the Work. Should any part of the License for any
+reason be judged legally invalid or ineffective under applicable law, such
+partial invalidity or ineffectiveness shall not invalidate the remainder
+of the License, and in such case Affirmer hereby affirms that he or she
+will not (i) exercise any of his or her remaining Copyright and Related
+Rights in the Work or (ii) assert any associated claims and causes of
+action with respect to the Work, in either case contrary to Affirmer's
+express Statement of Purpose.
+
+4. Limitations and Disclaimers.
+
+ a. No trademark or patent rights held by Affirmer are waived, abandoned,
+    surrendered, licensed or otherwise affected by this document.
+ b. Affirmer offers the Work as-is and makes no representations or
+    warranties of any kind concerning the Work, express, implied,
+    statutory or otherwise, including without limitation warranties of
+    title, merchantability, fitness for a particular purpose, non
+    infringement, or the absence of latent or other defects, accuracy, or
+    the present or absence of errors, whether or not discoverable, all to
+    the greatest extent permissible under applicable law.
+ c. Affirmer disclaims responsibility for clearing rights of other persons
+    that may apply to the Work or any use thereof, including without
+    limitation any person's Copyright and Related Rights in the Work.
+    Further, Affirmer disclaims responsibility for obtaining any necessary
+    consents, permissions or other rights required for any use of the
+    Work.
+ d. Affirmer understands and acknowledges that Creative Commons is not a
+    party to this document and has no duty or obligation with respect to
+    this CC0 or use of the Work.

zensical_updates-0.1.0/PKG-INFO

@@ -0,0 +1,118 @@
+Metadata-Version: 2.4
+Name: zensical-updates
+Version: 0.1.0
+Summary: Generate a dated Updates (blog) section for zensical sites as plain Markdown
+Project-URL: Homepage, https://github.com/IvanAnishchuk/zensical-updates
+Project-URL: Repository, https://github.com/IvanAnishchuk/zensical-updates
+Project-URL: Documentation, https://IvanAnishchuk.github.io/zensical-updates/
+Project-URL: Issues, https://github.com/IvanAnishchuk/zensical-updates/issues
+Project-URL: Changelog, https://github.com/IvanAnishchuk/zensical-updates/blob/main/CHANGELOG.md
+Project-URL: Security, https://github.com/IvanAnishchuk/zensical-updates/blob/main/SECURITY.md
+Author-email: Ivan Anishchuk <ivan@ivananishchuk.net>
+License-Expression: CC0-1.0
+License-File: LICENSE.md
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: pyyaml>=6.0.3
+Requires-Dist: rich>=13.0
+Requires-Dist: typer>=0.15
+Description-Content-Type: text/markdown
+
+# zensical-updates
+
+Generate a dated "Updates" (blog) section for [zensical](https://zensical.org)
+sites as plain Markdown. zensical ships no blog plugin, so this CLI runs as a
+pre-build step. It reads your post files and writes an index listing, per-year
+archives, and tag and category pages that zensical then builds.
+
+## How it works
+
+Writers keep posts in a source directory (default `updates/`), one Markdown file
+per post. Each post carries a `date` and optional `categories`/`tags` in
+block-list front matter:
+
+```markdown
+---
+date: 2026-06-11
+categories:
+  - weekly-update
+tags:
+  - epf
+---
+
+# Hello world
+
+The first paragraph becomes the listing excerpt.
+```
+
+`zensical-updates build` copies each post to `docs/<base>/<slug>.md` and writes
+the generated section around it (the index, `archive/`, `tags/`, `categories/`).
+A post at `docs/updates/hello.md` renders at `/updates/hello/`, and every
+generated link points there. Run it before zensical:
+
+```bash
+zensical-updates build              # writes docs/updates/
+zensical build --clean --strict
+```
+
+The generated `docs/<base>/` tree is build output. Gitignore it. The source tree
+stays under version control, and the generator never edits it.
+
+## Install
+
+Not on PyPI yet. Pin from git:
+
+```bash
+uv add "zensical-updates @ git+https://github.com/IvanAnishchuk/zensical-updates"
+```
+
+## Configure
+
+Settings live in `zensical.toml` under `[project.extra.zensical_updates]`, a
+namespace zensical ignores:
+
+```toml
+[project.extra.zensical_updates]
+base = "updates"        # section dir under docs/ and the URL base
+source = "updates"      # where your post files live, outside docs/
+emit_tags = true
+emit_categories = true
+emit_archive = true
+```
+
+Every key is optional. The defaults above apply when the table is absent.
+
+## CLI
+
+```bash
+zensical-updates build    # generate the section into docs/<base>/
+zensical-updates clean    # remove the generated output
+zensical-updates --help
+```
+
+## Development
+
+```bash
+git clone https://github.com/IvanAnishchuk/zensical-updates.git
+cd zensical-updates
+uv sync
+
+uv run pytest                       # tests + coverage (includes the zensical build)
+uv run ruff check src/ tests/
+uv run ruff format --check src/ tests/
+uv run mypy
+uv run pre-commit run --all-files
+```
+
+## License
+
+CC0-1.0. This is an original implementation inspired by the concept of
+`knu2xs/zensical-blog`, written from this project's own analysis of how zensical
+behaves.

zensical_updates-0.1.0/README.md

@@ -0,0 +1,91 @@
+# zensical-updates
+
+Generate a dated "Updates" (blog) section for [zensical](https://zensical.org)
+sites as plain Markdown. zensical ships no blog plugin, so this CLI runs as a
+pre-build step. It reads your post files and writes an index listing, per-year
+archives, and tag and category pages that zensical then builds.
+
+## How it works
+
+Writers keep posts in a source directory (default `updates/`), one Markdown file
+per post. Each post carries a `date` and optional `categories`/`tags` in
+block-list front matter:
+
+```markdown
+---
+date: 2026-06-11
+categories:
+  - weekly-update
+tags:
+  - epf
+---
+
+# Hello world
+
+The first paragraph becomes the listing excerpt.
+```
+
+`zensical-updates build` copies each post to `docs/<base>/<slug>.md` and writes
+the generated section around it (the index, `archive/`, `tags/`, `categories/`).
+A post at `docs/updates/hello.md` renders at `/updates/hello/`, and every
+generated link points there. Run it before zensical:
+
+```bash
+zensical-updates build              # writes docs/updates/
+zensical build --clean --strict
+```
+
+The generated `docs/<base>/` tree is build output. Gitignore it. The source tree
+stays under version control, and the generator never edits it.
+
+## Install
+
+Not on PyPI yet. Pin from git:
+
+```bash
+uv add "zensical-updates @ git+https://github.com/IvanAnishchuk/zensical-updates"
+```
+
+## Configure
+
+Settings live in `zensical.toml` under `[project.extra.zensical_updates]`, a
+namespace zensical ignores:
+
+```toml
+[project.extra.zensical_updates]
+base = "updates"        # section dir under docs/ and the URL base
+source = "updates"      # where your post files live, outside docs/
+emit_tags = true
+emit_categories = true
+emit_archive = true
+```
+
+Every key is optional. The defaults above apply when the table is absent.
+
+## CLI
+
+```bash
+zensical-updates build    # generate the section into docs/<base>/
+zensical-updates clean    # remove the generated output
+zensical-updates --help
+```
+
+## Development
+
+```bash
+git clone https://github.com/IvanAnishchuk/zensical-updates.git
+cd zensical-updates
+uv sync
+
+uv run pytest                       # tests + coverage (includes the zensical build)
+uv run ruff check src/ tests/
+uv run ruff format --check src/ tests/
+uv run mypy
+uv run pre-commit run --all-files
+```
+
+## License
+
+CC0-1.0. This is an original implementation inspired by the concept of
+`knu2xs/zensical-blog`, written from this project's own analysis of how zensical
+behaves.

zensical_updates-0.1.0/SECURITY.md

@@ -0,0 +1,61 @@
+# Security Policy
+
+## Supported Versions
+
+Only the latest release receives security fixes.
+
+| Version | Supported |
+|---------|-----------|
+| latest  | yes       |
+| older   | no        |
+
+## Reporting a Vulnerability
+
+**Please do not file public GitHub issues for security vulnerabilities.**
+
+Report privately via one of the following channels:
+
+1. **GitHub Private Vulnerability Reporting**
+   Use the "Report a vulnerability" button on the
+   [Security tab](https://github.com/IvanAnishchuk/zensical-updates/security/advisories/new).
+
+2. **Email**
+   Send to `ivan@ivananishchuk.net`.
+
+Please include:
+
+- A description of the issue and its impact
+- Steps to reproduce (proof-of-concept if possible)
+- Affected versions
+- Your name and affiliation (optional, for credit)
+
+## Response SLA
+
+- **Triage**: within 7 days of report
+- **Fix + advisory**: within 90 days for high/critical issues
+
+## Verifying Releases
+
+All releases are:
+
+- Built by GitHub Actions from a tagged commit
+- Published to PyPI via **trusted publishing (OIDC)**
+- **Signed with sigstore** (keyless signing)
+- Accompanied by a **CycloneDX SBOM**
+
+```sh
+# Verify sigstore signature (replace vX.Y.Z with the release tag)
+uv tool run sigstore verify identity \
+    --cert-identity 'https://github.com/IvanAnishchuk/zensical-updates/.github/workflows/release.yml@refs/tags/vX.Y.Z' \
+    --cert-oidc-issuer 'https://token.actions.githubusercontent.com' \
+    --bundle zensical-updates-*.whl.sigstore.json \
+    zensical-updates-*.whl
+
+# Verify GitHub attestation
+gh attestation verify zensical-updates-*.whl --owner IvanAnishchuk
+```
+
+## Safe Harbor
+
+We support responsible security research. Good-faith efforts to discover
+and report vulnerabilities will not be met with legal action.

zensical_updates-0.1.0/docs/api.md

@@ -0,0 +1,6 @@
+# API Reference
+
+The public API of `zensical_updates`, generated from the source
+docstrings. Only names exported in `__all__` are shown.
+
+::: zensical_updates

zensical_updates-0.1.0/docs/changelog.md

@@ -0,0 +1 @@
+--8<-- "CHANGELOG.md"

zensical_updates-0.1.0/docs/cli.md

@@ -0,0 +1,10 @@
+# CLI Reference
+
+`zensical-updates` ships a small maintenance CLI for inspecting
+the installed library. The importable API is the product; this is a convenience
+for introspection and maintenance tasks.
+
+::: mkdocs-typer2
+    :module: zensical_updates.cli
+    :command: app
+    :name: zensical-updates

zensical_updates-0.1.0/docs/index.md

@@ -0,0 +1,27 @@
+# zensical-updates
+
+Generate a dated "Updates" (blog) section for zensical sites as plain Markdown.
+zensical has no blog plugin, so this CLI runs as a pre-build step that writes an
+index listing, per-year archives, and tag and category pages.
+
+## Install
+
+Not on PyPI yet. Pin from git:
+
+```bash
+uv add "zensical-updates @ git+https://github.com/IvanAnishchuk/zensical-updates"
+```
+
+## Quickstart
+
+```bash
+zensical-updates build              # writes docs/<base>/
+zensical build --clean --strict
+```
+
+## Documentation
+
+- [Usage](usage.md) — write posts, configure, and run the build.
+- [CLI](cli.md) — the `build`/`clean` commands.
+- [API Reference](api.md) — generated from docstrings.
+- [Changelog](changelog.md) — version history.

zensical_updates-0.1.0/docs/usage.md

@@ -0,0 +1,72 @@
+# Usage
+
+## Write posts
+
+Put one Markdown file per post in your source directory (default `updates/`, set
+by the `source` config key). The file stem becomes the slug and the URL segment,
+so name files for the URL you want: `updates/hello-world.md` renders at
+`/updates/hello-world/`.
+
+Each post needs a `date` in front matter. Use block-style lists for `categories`
+and `tags`; a flow list like `[weekly-update]` breaks zensical's strict build,
+which reads it as an unresolved reference link.
+
+```markdown
+---
+date: 2026-06-11
+categories:
+  - weekly-update
+tags:
+  - epf
+---
+
+# Hello world
+
+The first paragraph becomes the listing excerpt. Mark a cut point with
+`<!-- more -->` to control where the excerpt ends.
+```
+
+An optional `updates/index.md` holds the section intro. Its body is placed above
+the generated listing on the landing page.
+
+## Configure
+
+Settings live in `zensical.toml` under `[project.extra.zensical_updates]`:
+
+```toml
+[project.extra.zensical_updates]
+base = "updates"        # section dir under docs/ and the URL base
+source = "updates"      # where your post files live, outside docs/
+intro = "index.md"      # the intro file within source/
+excerpt_marker = "<!-- more -->"
+emit_tags = true
+emit_categories = true
+emit_archive = true
+```
+
+## Build
+
+```bash
+zensical-updates build              # generate docs/<base>/
+zensical build --clean --strict     # build the site
+```
+
+The generated `docs/<base>/` tree is build output. Add it to `.gitignore`. Run
+`zensical-updates clean` to remove it. An invalid post (for example one with no
+`date`) fails the build with a message naming the file.
+
+## Library
+
+The same operations are available as functions:
+
+```python
+from pathlib import Path
+
+from zensical_updates import Config, build_site, clean_site
+
+result = build_site(Config(), Path("."))
+print(result.post_urls)
+```
+
+The supported surface is whatever `zensical_updates.__all__` lists. See the
+[API Reference](api.md).