oaktree-sapling 0.0.1

package/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, Neuromatch, Inc.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

package/README.md

@@ -0,0 +1,66 @@
+# oaktree-sapling
+
+A journal engine for small publications built on [MyST](https://mystmd.org), GitHub and Zenodo.
+
+One repo holds the journal: its settings, branding, editions and the list of published papers.
+Each paper gets a repo of its own, with CI that builds a website and a PDF, runs the journal's checks on every pull request, publishes a preview, and deposits the final version to Zenodo for a DOI. `oak` is the command line tool that sets those repos up and does the work inside them.
+
+Papers refer to the engine by a single version coordinate, so a journal upgrades by changing one line rather than by copying workflow files around.
+
+## Status
+
+Pre-1.0 and in active development. Every command is implemented and the CI is being tested end to end against real GitHub, Cloudflare and Zenodo, but interfaces may still change between 0.x versions and the documentation is incomplete. Its original design served Neuromatch Impact Scholars Program 2025, but is being heavily revised to become suitable to more tenants.
+
+## Install
+
+```
+npm install -g oaktree-sapling
+oak
+```
+
+`oak` with no arguments prints the full usage.
+
+## Commands
+
+Setting up repos:
+
+- `oak bootstrap journal` — create the journal repo (settings, branding, paper list)
+- `oak bootstrap paper` — create a paper repo pointing at a journal
+- `oak upgrade` — move a paper repo to a newer engine version, as a pull request
+
+Working on a paper:
+
+- `oak validate` — run the journal's checks over a manuscript
+- `oak build` — build the paper's website and PDF into `_build/`
+- `oak start` — preview it in a browser with the journal's settings applied
+
+The rest (`check-post`, `deploy-preview`, `deposit`, `release`, `notify`, `conformance`) are run by the generated workflows and are rarely typed by hand.
+
+## Known limitations of the npm package
+
+The engine is normally run from a checked-out release tag, which carries two things the npm package does not:
+
+- **No PDF export.** A pinned `typst` binary ships with each release tag; the package has none, so `oak build` produces a PDF only if `typst` is already on your `PATH`.
+- **`oak deposit` does not work.** It archives the engine with `git archive` to record what built the paper, which needs a git checkout rather than an installed package.
+
+Both are being worked on. Until then, CI uses release tags.
+
+## Editorial checks
+
+`oak validate` runs two kinds of check. The engine's own invariants are built in. The editorial checks a journal selects — authors exist, have ORCIDs, have valid CRediT roles, abstract exists, keywords defined — come from the MIT-licensed [`@curvenote/check-implementations`](https://www.npmjs.com/package/@curvenote/check-implementations) and [`@curvenote/check-definitions`](https://www.npmjs.com/package/@curvenote/check-definitions). The engine supplies the runner and the GitHub Check Run reporter.
+
+## Development
+
+```
+npm install
+npm test
+npm run typecheck
+```
+
+`NOTES.md` has the module map and the build internals. `RELEASING.md` explains how releases are cut and why the built bundle is committed at the tag.
+
+## License
+
+BSD 3-Clause, copyright Neuromatch, Inc. See `LICENSE`.
+
+One subtree is not covered by it: `templates/typst/` is the [LaPreprint](https://github.com/curvenote/lapreprint) typst template, MIT-licensed and copyright Rowan Cockett. It keeps its own `LICENSE` alongside it, which ships with the package and with every release tag.

package/ci/run.sh

@@ -0,0 +1,64 @@
+#!/usr/bin/env bash
+# The ONLY bash in the engine (design §12). The composite action has already checked out
+# the engine at the pinned ref into ./.engine and set INSTANCE_REPO from pins.yml. This
+# does the CI-specific *materialization* §1b assigns it — typst on PATH, instance-config
+# cloned, BASE_URL by event — then dispatches to dist/cli.cjs, where all LOGIC lives.
+# (Resolves the §12 "5 lines" aspiration toward §1b: setup here, logic in the bundle.)
+set -euo pipefail
+
+here="$(cd "$(dirname "$0")" && pwd)"
+engine="$(cd "$here/.." && pwd)"
+verb="${1:-}"
+
+# A runnable engine ⟺ a release ([R57]): dist/cli.cjs is committed ONLY onto release-tag
+# leaves, never a branch tip. If it's absent the pinned ref is a branch (or a bad tag) —
+# fail loud with the fix, not a raw "Cannot find module". This guard IS the enforcement of
+# "CI runs released tags only"; nothing else rejects a branch pin.
+if [ ! -f "$engine/dist/cli.cjs" ]; then
+  echo "::error::engine ref carries no dist/cli.cjs — pin a released tag, not a branch tip (a runnable engine ⟺ a release, [R57]; see RELEASING.md)"
+  exit 1
+fi
+
+# typst — prefer a binary shipped with the engine tag ([R34]); else rely on PATH.
+if [ -x "$engine/bin/typst" ]; then export PATH="$engine/bin:$PATH"; fi
+
+extra=()
+
+# build + release run a real myst build → pick BASE_URL. deploy-preview only reads the
+# journal.yml preview: fields ([R27]), so it needs the instance but never a base_url.
+if [ "$verb" = "build" ] || [ "$verb" = "release" ]; then
+  # BASE_URL: '' for PR previews (served at the Cloudflare root), '/<repo>' for Pages/prod.
+  if [ "${GITHUB_EVENT_NAME:-}" = "pull_request" ]; then
+    base_url=""
+  else
+    base_url="/${GITHUB_REPOSITORY##*/}"
+  fi
+  extra+=(--base-url "$base_url")
+fi
+
+# instance-config: public, depth-1, default branch (dec. 16/19). '.' = co-located
+# (repo=journal, deferred) — leave to the CLI's root resolution. build/release need it for
+# the extends chain; deploy-preview needs it for the preview: knobs ([R27]/[R69]); validate
+# needs it for journal.yml `checks:` + the registry (id-uniqueness).
+if [ "$verb" = "build" ] || [ "$verb" = "release" ] || [ "$verb" = "deploy-preview" ] || [ "$verb" = "validate" ]; then
+  if [ -n "${INSTANCE_REPO:-}" ] && [ "${INSTANCE_REPO}" != "." ]; then
+    inst_dir="$(mktemp -d)"
+    git clone --depth 1 "https://github.com/${INSTANCE_REPO}.git" "$inst_dir"
+    extra+=(--instance "$inst_dir")
+  fi
+fi
+
+echo "::group::engine context"
+echo "engine dir : $engine"
+echo "verb       : $verb"
+echo "instance   : ${INSTANCE_REPO:-<co-located>}"
+echo "extra args : ${extra[*]:-<none>}"
+# Secret PRESENCE only — never the value (design §1a: echo what we resolved; aids a
+# tenant's first broken run, and lets the [R18] step-env-propagation spike be observed
+# on prepare/publish/preview-deploy without leaking anything). `:+present` is set -u safe.
+echo "GH_TOKEN     : ${GH_TOKEN:+present}"
+echo "ZENODO_TOKEN : ${ZENODO_TOKEN:+present}"
+echo "CLOUDFLARE   : ${CLOUDFLARE_API_TOKEN:+present}"
+echo "::endgroup::"
+
+exec node "$engine/dist/cli.cjs" "$@" "${extra[@]}"