oaktree-sapling 0.0.1

package/templates/paper/.github/workflows/ci.yml

@@ -0,0 +1,64 @@
+name: Paper CI
+
+# Stage 1 of the always-split preview (design §6a, dec. 13). Builds on every PR + push
+# with NO secrets and a read-only token, so fork PRs get full validation + a build. The
+# preview DEPLOY happens in preview-deploy.yml (workflow_run, base context) because forks
+# never receive secrets. Pages deploy (push to main) rides here behind a job-scoped token.
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read # the untrusted build job never holds pages/id-token ([R13])
+
+concurrency:
+  group: ${{ github.event_name == 'pull_request' && format('ci-{0}', github.head_ref) || 'ci-main' }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+jobs:
+  build: # NO secrets, read-only token — safe for fork PRs
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - uses: ./.github/actions/engine
+        with:
+          args: build
+      # upload-artifact follows symlinks and stores their TARGET content as a regular file.
+      # Author content is untrusted, so a planted symlink (e.g. to .git/config or any
+      # runner-readable file) would ride into the artifact and be served on the public preview.
+      # Strip symlinks so the artifact carries only files the build actually produced.
+      - name: Drop symlinks from the build output
+        run: find _build/html -type l -delete
+      - name: Stash PR number # workflow_run.pull_requests is EMPTY for forks (§6a)
+        if: ${{ github.event_name == 'pull_request' }}
+        run: echo "${{ github.event.pull_request.number }}" > _build/html/.pr-number
+      - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: paper-build
+          path: _build/html
+          if-no-files-found: error
+          include-hidden-files: true
+
+  deploy-pages:
+    if: ${{ github.event_name != 'pull_request' }}
+    needs: build
+    permissions: # deploy perms live HERE, not on the untrusted build job ([R13])
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.d.outputs.page_url }}
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: paper-build
+          path: site
+      - uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9 # v5.0.0
+        with:
+          path: site
+      - id: d
+        uses: actions/deploy-pages@cd2ce8fcbc39b97be8ca5fce6e763baed58fa128 # v5.0.0

package/templates/paper/.github/workflows/prepare.yml

@@ -0,0 +1,34 @@
+name: Prepare Zenodo deposit
+
+# Editor dispatches DOI reservation (design §1d). Reserves/reuses a draft and opens the
+# one-file myst.yml PR writing project.doi/github/date ([R22]) — the CLI opens that PR
+# itself via GH_TOKEN (no peter-evans action; the write is a YAML round-trip, [R3]).
+# `--sandbox` is an explicit human choice here ([R4]); a prod prepare may replace a
+# committed sandbox DOI ([R29]).
+#
+# No `version` input: prepare is version-agnostic — it only reserves the concept DOI. The
+# version is the tag, and it enters the deposit at publish time (publish.yml → `oak release`).
+
+on:
+  workflow_dispatch:
+    inputs:
+      sandbox:
+        description: "Use the Zenodo sandbox (rehearsal) instead of production"
+        type: boolean
+        default: true
+
+permissions:
+  contents: write # commit the DOI PR branch
+  pull-requests: write # open the DOI PR
+
+jobs:
+  prepare:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - uses: ./.github/actions/engine
+        with:
+          args: deposit prepare ${{ inputs.sandbox && '--sandbox' || '' }}
+        env:
+          GH_TOKEN: ${{ github.token }}
+          ZENODO_TOKEN: ${{ inputs.sandbox && secrets.ZENODO_TOKEN_SANDBOX || secrets.ZENODO_TOKEN }}

package/templates/paper/.github/workflows/preview-deploy.yml

@@ -0,0 +1,52 @@
+name: Preview deploy
+
+# Stage 2 of the always-split preview (design §6a, dec. 13, [R16]). Runs in BASE-repo
+# context after Paper CI completes, so it holds the preview secret that fork PRs never
+# get. It ONLY downloads Stage 1's inert artifact and deploys it — it never rebuilds fork
+# content (that would reopen the injection hole through the shim's back door). The engine
+# ref + action code come from the BASE default branch (guaranteed by workflow_run).
+
+on:
+  workflow_run:
+    workflows: ["Paper CI"]
+    types: [completed]
+
+permissions:
+  contents: read
+  actions: read # download the cross-run artifact
+  pull-requests: write # sticky preview comment + new-version reminder ([R16])
+
+concurrency:
+  # head_branch alone collides across forks (two forks PRing from `main` would cancel each
+  # other's previews) — key on head repo too ([R15]).
+  group: preview-${{ github.event.workflow_run.head_repository.full_name }}-${{ github.event.workflow_run.head_branch }}
+  cancel-in-progress: true
+
+jobs:
+  deploy:
+    if: >-
+      ${{ github.event.workflow_run.event == 'pull_request' &&
+          github.event.workflow_run.conclusion == 'success' }}
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 — BASE default branch ⇒ engine ref AND action code from base
+      - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: paper-build
+          path: site
+          run-id: ${{ github.event.workflow_run.id }}
+          github-token: ${{ github.token }}
+      # deploys the inert artifact (deletes .pr-number first — [R26]); if no Cloudflare
+      # secrets are present, `oak deploy-preview` degrades to an artifact-link comment
+      # instead of failing ([R6]). It also posts the new-version reminder here, where it
+      # has pull-requests: write (fork Stage-1 runs never do) — [R16].
+      - uses: ./.github/actions/engine
+        with:
+          args: deploy-preview site
+        env:
+          GH_TOKEN: ${{ github.token }}
+          CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
+          CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
+          # The Paper CI run that holds the paper-build artifact — lets the CLI deep-link the
+          # artifact-degrade comment straight to that run (not the whole Actions tab).
+          PAPER_BUILD_RUN_ID: ${{ github.event.workflow_run.id }}

package/templates/paper/.github/workflows/publish.yml

@@ -0,0 +1,33 @@
+name: Publish Zenodo deposit
+
+# Tag push populates the Zenodo draft (design §1e). `oak release` builds, deposits
+# (env DERIVED from the committed project.doi prefix — kills the awk sniff, [R4]/[R8]),
+# attaches the debug bundle to the tag's GitHub Release ([R24]), and posts the commit
+# comment / failure issue via gh — all behind the version knob. The required-reviewer
+# environment is the human gate before any token-bearing run; the actual public DOI is
+# still minted by a human clicking Publish on Zenodo (design §8). Both tokens are passed;
+# the CLI selects by DOI prefix.
+
+on:
+  push:
+    tags: ["v*"]
+
+permissions:
+  contents: write # attach the Release bundle + commit comment
+  issues: write # open the editor-action issue on failure
+
+jobs:
+  publish:
+    environment: zenodo-publish # required-reviewer gate — provisioned by bootstrap ([R10])
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          fetch-depth: 0 # git archive + PR discovery need history
+      - uses: ./.github/actions/engine
+        with:
+          args: release --tag ${{ github.ref_name }}
+        env:
+          GH_TOKEN: ${{ github.token }}
+          ZENODO_TOKEN: ${{ secrets.ZENODO_TOKEN }}
+          ZENODO_TOKEN_SANDBOX: ${{ secrets.ZENODO_TOKEN_SANDBOX }}

package/templates/paper/.github/workflows/version-bump.yml

@@ -0,0 +1,29 @@
+name: Engine version bump
+
+# Scheduled logic-ref bump (design §6b-left, dec. 17). Floats
+# project.options.oaktree-sapling.version to the latest engine release and opens a one-line
+# PR. The bump is DATA (myst.yml, not CODEOWNERS-gated), so an editor merges it after the
+# preview build shows the result; it touches no secret. Runs `oak upgrade --version-only`,
+# which reads the engine repo from pins.yml, resolves the latest release, writes myst.yml via
+# a YAML round-trip (never sed), and opens the PR. The frequent logic-ref cadence's automated
+# home; the rare frozen-file resync is the manual `oak upgrade --files-only` path.
+
+on:
+  schedule:
+    - cron: "17 4 * * 1" # weekly, Monday 04:17 UTC
+  workflow_dispatch:
+
+permissions:
+  contents: write # commit the bump branch
+  pull-requests: write # open the bump PR
+
+jobs:
+  bump:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - uses: ./.github/actions/engine
+        with:
+          args: upgrade --paper . --version-only --yes
+        env:
+          GH_TOKEN: ${{ github.token }}

package/templates/paper/CODEOWNERS

@@ -0,0 +1,9 @@
+# The frozen shim is the trust boundary (design §6a): action.yml runs engine code at a
+# ref, and pins.yml names the engine + instance repos (code-adjacent). Gate everything
+# under .github/ — including pins.yml and CODEOWNERS itself — behind the editors, so an
+# author PR can float the engine *ref* (data) but cannot redirect a token-bearing run to
+# unreviewed code. copier replaces the owner below at bootstrap. NB a personal-account repo
+# (the interim/lab tier) has no org team, so it names the user directly ([R56]); an org
+# tenant uses a team like @your-org/editors.
+/.github/                @pollomarzo
+/CODEOWNERS              @pollomarzo

package/templates/paper/bib.bib

@@ -0,0 +1,6 @@
+@article{example2026,
+  title = {An Example Reference},
+  author = {Author, Example},
+  journal = {Journal of Examples},
+  year = {2026}
+}

package/templates/paper/gitignore

@@ -0,0 +1,8 @@
+# Engine-generated build config ([R71]). `oak build` composes your myst.yml with the
+# engine/edition/brand chain and writes the result here; your myst.yml is never modified.
+# Not auto-deleted: myst's HTML build process.exit(0)s on success, so no cleanup hook can
+# reliably run. Safe to delete by hand at any time.
+myst.oak.yml
+
+# MyST build outputs
+_build/

package/templates/paper/index.md

@@ -0,0 +1,12 @@
+# A Starter Paper
+
++++ {"part": "abstract"}
+
+Replace this with your abstract. The `abstract` part is lifted into the site, the merged
+PDF cover page, and the Zenodo deposit description, so keep it self-contained.
+
++++
+
+## Introduction
+
+Your paper content goes here. Cite your bibliography like this [@example2026].

package/templates/paper/myst.yml

@@ -0,0 +1,37 @@
+version: 1
+
+# Starter paper — stamped by `oak bootstrap`. NEW-MODEL committed paper: NO `extends:`
+# (compose injects the engine/edition/brand chain at build time), and the single engine
+# coordinate rides myst's untyped `options` passthrough. `oak bootstrap` / `oak upgrade`
+# fill `version`/`edition` below.
+#
+# The `authors:`/`keywords:` templates below are COMMENTED OUT: uncomment and fill them with
+# your real metadata. They show exactly the fields the journal's editorial checks expect
+# (authors + ORCID + CRediT roles, keywords, and an `abstract` part in index.md), so you don't
+# have to guess — but they stay inert until you fill them, so nothing fake ships by accident.
+project:
+  # Set a FRESH, UNIQUE id that matches the journal's `id_pattern`. Until you do, the build's
+  # pre-flight rejects this placeholder — that safeguard (not a bug) is why a fresh repo is red.
+  id: CHANGE-ME-template-placeholder
+  title: CHANGE-ME — your paper title
+  # authors:
+  #   - name: Ada Lovelace
+  #     orcid: 0000-0000-0000-0000          # the journal checks for a valid ORCID
+  #     affiliations:
+  #       - Your Institution
+  #     email: you@example.org
+  #     corresponding: true                 # at least one corresponding author
+  #     roles:                              # CRediT taxonomy terms
+  #       - conceptualization
+  #       - writing - original draft
+  # keywords:
+  #   - keyword one
+  #   - keyword two
+  bibliography:
+    - bib.bib
+  options:
+    # The ONE engine knob (design §6). `oak bootstrap` / `oak upgrade` write these; only the
+    # `version` ref floats (a released engine tag — never a branch tip; CI runs releases).
+    oaktree-sapling:
+      version: CHANGE-ME-engine-version
+      edition: CHANGE-ME-edition

package/templates/site/.github/workflows/site.yml

@@ -0,0 +1,73 @@
+name: Journal site
+
+# Builds + deploys the journal site to GitHub Pages. Plain MyST — no engine, no shim, no
+# secrets ([S1]). The editorial PR that adds a registry entry lands in THIS repo, so it is
+# also the deploy trigger: publish → visible, one act, one repo ([S8]).
+#
+# Actions are pinned by full commit SHA at a close-to-latest major ([R75]) — the same SHAs
+# the frozen paper shim uses.
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  build-deploy:
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.d.outputs.page_url }}
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
+        with:
+          node-version: '22'
+      # Resolves where Pages actually serves this repo. `base_path` is `/<repo>` for a project
+      # site and EMPTY for a user/org site or a custom domain — which is exactly MyST's
+      # BASE_URL contract. Without it MyST emits root-absolute asset URLs (`/build/…`) and
+      # every image, stylesheet and script 404s on the subpath this tier deploys to. Asking
+      # GitHub rather than hardcoding `/<repo>` is what keeps the vanity-URL routes working.
+      - id: pages
+        uses: actions/configure-pages@983d7736d9b0ae728b81ab479565c72886d7745b # v5.0.0
+      # Installs BOTH MyST and the gallery plugin's own dependency (js-yaml), which are
+      # pinned together in package.json — the one place this site's versions live.
+      #
+      # The install is not optional: MyST downloads a remote plugin into `_build/cache/`
+      # and imports it FROM THERE, so the plugin's bare imports resolve upward from this
+      # repo's node_modules. A package fetched by `npx` lands outside that resolution path.
+      - run: npm install --no-audit --no-fund
+      # `--strict` is LOAD-BEARING, not hygiene. Without it `myst build` logs errors and
+      # exits 0 (`cli/options.ts:98-102`), and a remote plugin that fails to load degrades
+      # QUIETLY: the page would deploy with `paper-cards` as an unknown directive — no
+      # gallery at all — over a perfectly good previous deploy. Only `--strict` catches that.
+      # `--strict` catches errors raised while BUILDING a page (a bad DOI, a missing image).
+      # It does NOT catch a plugin that never loaded: myst logs "Unknown plugin" and
+      # "unknown directive: paper-cards", then exits 0 — and the gallery-less page deploys
+      # over a perfectly good one. Verified live, not assumed ([R80]). So we also require a
+      # POSITIVE signal: myst prints the plugin's own name when it loads, and that name is
+      # ours, not a myst log format we don't control.
+      - name: Build (and prove the gallery plugin loaded)
+        env:
+          BASE_URL: ${{ steps.pages.outputs.base_path }}
+        run: |
+          set -o pipefail
+          npx myst build --html --strict 2>&1 | tee /tmp/myst-build.log
+          if ! grep -q "Paper Gallery.*loaded" /tmp/myst-build.log; then
+            echo "::error::the gallery plugin did not load — check the pinned plugin URL in myst.yml (a bad tag 404s silently)"
+            exit 1
+          fi
+      - uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9 # v5.0.0
+        with:
+          path: _build/html
+      - id: d
+        uses: actions/deploy-pages@cd2ce8fcbc39b97be8ca5fce6e763baed58fa128 # v5.0.0

package/templates/site/gitignore

@@ -0,0 +1,5 @@
+# MyST build outputs
+_build/
+
+# Installed by the site workflow so the gallery plugin's `js-yaml` import resolves.
+node_modules/

package/templates/site/myst.yml

@@ -0,0 +1,32 @@
+version: 1
+
+# The JOURNAL SITE — the page a reader lands on ([S1]/[S8]). It is a plain MyST project
+# living in this instance-config repo: `myst build --html`, no engine, no `oak`. This file
+# and `plugins/gallery.mjs` are the only bytes the engine owns here; everything else in the
+# site scaffold is yours to rewrite. `oak upgrade` does not touch it.
+#
+# THREE PINS live in this repo, all stamped once at bootstrap and all bumped by hand:
+#   1. the gallery plugin URL below (the engine tag),
+#   2. `site.template` below (the theme release this engine version pins),
+#   3. `mystmd` in package.json — beside `js-yaml`, which the gallery plugin imports.
+#      Both live there so this site has ONE dependency list; the workflow just installs it.
+
+extends:
+  # Your journal's brand, right here in this repo. A LOCAL path: no network, no cache
+  # staleness, and a single-entry chain has no siblings to race ([R72]).
+  - ./brand/brand.yml
+
+project:
+  title: CHANGE-ME Journal
+  plugins:
+    # The `paper-cards` directive, pinned to the engine tag this repo was bootstrapped with.
+    # Bump the tag to take engine updates. It must be remote because it is CODE — a `.mjs`
+    # body cannot be stamped into YAML, and vendoring a copy is exactly the copy-rot the
+    # engine exists to kill.
+    - STAMPED-AT-BOOTSTRAP
+  toc:
+    - file: pages/index.md
+
+site:
+  # The myst-theme fork release this engine version pins (design §7).
+  template: STAMPED-AT-BOOTSTRAP

package/templates/site/package.json

@@ -0,0 +1,9 @@
+{
+  "name": "journal-site",
+  "private": true,
+  "description": "The journal site's build toolchain and plugin dependencies. MyST is pinned HERE, not in the workflow, so this file is the one place site versions live.",
+  "dependencies": {
+    "js-yaml": "^4.1.0",
+    "mystmd": "{{myst_version}}"
+  }
+}

package/templates/site/pages/index.md

@@ -0,0 +1,25 @@
+# {{journal_name}}
+
+Welcome. Rewrite this paragraph: say what the journal publishes, who it is for, and how to
+submit. This page is yours — the engine stamps it once and never touches it again.
+
+## Papers
+
+:::{paper-cards}
+:::
+
+<!--
+The `paper-cards` directive above lists EVERY paper in `registry/papers.yml`, in file order.
+That is the right shape for a journal with one edition.
+
+When you grow a second edition, split this into per-edition pages: add
+`pages/editions/<edition>.md` with its own title and blurb, filter it with
+
+    :::{paper-cards}
+    :edition: <edition>
+    :::
+
+and add the file to `toc:` in myst.yml. The edition's display title and blurb live in that
+page, deliberately: `editions/<edition>.yml` is a MyST config layer, so a non-MyST key there
+is silently ignored and misattributed to a paper's generated config ([R79]).
+-->

package/templates/typst/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 Rowan Cockett
+
+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.