calkit-python 0.41.25__tar.gz → 0.42.0__tar.gz

{calkit_python-0.41.25 → calkit_python-0.42.0}/.dockerignore

@@ -1,7 +1,10 @@
 # The hub backend image builds with this directory as its context so it can
 # install the calkit-python workspace member; keep everything it doesn't need
 # out of the context
-.git
+#
+# .git is deliberately NOT excluded: hatch-vcs reads the release tags out of
+# it to version calkit-python and the hub backend at install time. It is
+# bind-mounted into the one RUN that needs it, so it never lands in a layer.
 .venv
 .env
 **/__pycache__

{calkit_python-0.41.25 → calkit_python-0.42.0}/.prettierignore

@@ -7,3 +7,4 @@ calkit
 .pytest_cache
 .ruff_cache
 .venv
+browser-ext/dist

{calkit_python-0.41.25 → calkit_python-0.42.0}/AGENTS.md

@@ -5,6 +5,7 @@
 - The main Python package/CLI lives in `calkit`
 - The JupyterLab extension lives in `src`
 - The VS Code extension lives in `vscode-ext`
+- The Chrome extension lives in `browser-ext`
 
 ## Working
 

{calkit_python-0.41.25 → calkit_python-0.42.0}/CONTRIBUTING.md

@@ -89,6 +89,33 @@ This guide will help you get started.
   to the description.
 - Wait for a review and make necessary changes.
 
+## Releasing the browser extension
+
+Publishing a GitHub release tagged `browser-ext/vX.Y.Z` builds and tests the
+extension, stamps that version into `manifest.json` and `package.json`,
+strips source maps, and attaches a store-ready zip to the release.
+The version comes from the tag because the Chrome Web Store rejects an
+upload whose manifest version isn't higher than the last one, and a version
+kept in sync by hand eventually isn't.
+Uncheck "set as the latest release" for these, since they aren't
+calkit-python releases.
+
+The same workflow uploads to the Chrome Web Store once the
+`CHROME_EXTENSION_ID` repository variable is set, using the
+`CHROME_CLIENT_ID`, `CHROME_CLIENT_SECRET`, and `CHROME_REFRESH_TOKEN`
+secrets (an OAuth client for the Web Store API, authorized for the
+publishing account).
+Until that variable exists the upload step is skipped and the zip on the
+release is uploaded by hand.
+
+`make browser-ext` builds and packages the same zip locally.
+The packaged manifest drops the local development hub's host permission,
+which is why it is built from a staged copy rather than from `dist`, the
+directory loaded unpacked during development.
+The store listing's text lives in `browser-ext/store/listing.md`, and its
+screenshots are generated from `docs/img/browser-ext` by
+`browser-ext/scripts/store-screenshots.py`.
+
 ## 💡 Other ways to contribute
 
 - **Report bugs**: Open an issue with detailed reproduction steps.

{calkit_python-0.41.25 → calkit_python-0.42.0}/Makefile

@@ -79,3 +79,39 @@ test-jlab-ui: ## Run the JupyterLab UI integration tests.
 	@uv run --directory=jupyterlab-ext/ui-tests jlpm install
 	@uv run --directory=jupyterlab-ext/ui-tests jlpm playwright install
 	@uv run --directory=jupyterlab-ext/ui-tests jlpm playwright test -u --reporter=list
+
+.PHONY: browser-ext
+browser-ext: ## Build the browser extension and package it as a ZIP.
+	@echo "🚀 Building the browser extension"
+	@cd browser-ext && npm ci && npm run build
+	@echo "📦 Packaging the browser extension ZIP"
+	@mkdir -p browser-ext/zip
+# Packaged from a staged copy, never from dist: dist is what gets loaded
+# unpacked for development, and the published manifest drops the local
+# hub's host permission, which development needs.
+	@rm -rf browser-ext/zip/stage
+	@mkdir -p browser-ext/zip/stage
+	@cp -R browser-ext/dist/. browser-ext/zip/stage/
+	@cd browser-ext && node scripts/package-manifest.mjs zip/stage/manifest.json
+# Source maps are useful loading unpacked, but only bloat a store upload, so
+# they stay in dist and are excluded from the archive.
+# zip adds to an existing archive rather than replacing it, so a rebuild at
+# the same commit would otherwise keep files the build no longer produces.
+# $$ escapes the shell's expansion from Make's own.
+	@rm -f "browser-ext/zip/calkit-browser-ext.zip"
+	@cd browser-ext/zip/stage && zip -qr \
+		"../calkit-browser-ext.zip" . \
+		-x '.*' '*/.*' '*.map'
+	@rm -rf browser-ext/zip/stage
+
+.PHONY: browser-ext-dev
+browser-ext-dev: ## Rebuild the browser extension on every change.
+	@echo "🚀 Watching the browser extension"
+# Rebuilds on save. Chrome still needs the extension reloaded, since it
+# reads a content script from disk when a page loads. Vite doesn't type
+# check, so run 'cd browser-ext && npm run check' alongside this.
+	@cd browser-ext && npm ci && npm run dev
+
+.PHONY: browser-ext-clean-zips
+browser-ext-clean-zips: ## Delete all built browser extension ZIPs.
+	@rm -rf browser-ext/zip

{calkit_python-0.41.25 → calkit_python-0.42.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: calkit-python
-Version: 0.41.25
+Version: 0.42.0
 Summary: Reproducibility simplified.
 Project-URL: Homepage, https://calkit.org
 Project-URL: Issues, https://github.com/calkit/calkit/issues

calkit_python-0.42.0/browser-ext/.gitignore

@@ -0,0 +1,6 @@
+node_modules/
+dist/
+zip/
+*.zip
+# Generated from docs/img/browser-ext by scripts/store-screenshots.py
+store/screenshots/

calkit_python-0.42.0/browser-ext/README.md

@@ -0,0 +1,200 @@
+# Calkit browser extension
+
+A Chrome extension (Manifest V3) for working with Calkit projects from the
+sites where the work actually happens: GitHub, Overleaf, and journal and
+preprint pages.
+
+## What it does
+
+### Overleaf
+
+On an Overleaf project page, a panel shows the Calkit project that syncs with
+it and, most importantly, **which figures are out of date on Overleaf**:
+
+- Figures whose content differs from the copy in the Calkit project are
+  listed first, so it's obvious when the paper is showing an old plot.
+- A figure produced by a pipeline stage that is itself stale is flagged, so
+  you know to run the pipeline before syncing rather than syncing a stale
+  figure into the paper.
+- Overleaf edits that haven't come back into the project yet are counted.
+- **Sync now** runs the same bidirectional sync as `calkit overleaf sync`.
+
+If the Overleaf project isn't linked yet, the panel can search your projects
+and either check an existing link or import the Overleaf project into one as a
+new publication.
+
+**Attach to new project** covers the case where the code, data, and figures
+already live in a GitHub repo. Turn on "Exists on GitHub", type the repo name,
+and pick the folder the document should occupy inside the project. That
+creates the Calkit project around the existing repo and imports the Overleaf
+document into it in one go, after which the document is a pipeline stage whose
+figures can be checked for staleness and synced. The Calkit GitHub app has to
+be installed for the repo.
+
+Finding the linked project doesn't require having synced before: the hub reads
+each project's `calkit.yaml` through the GitHub API, active project first,
+indexing what it finds so later lookups are a single query.
+
+### GitHub
+
+A **Calkit** button in the corner of a repository page says whether the repo is
+a Calkit project before you click it. It reads the repo's `calkit.yaml` first,
+since that file names the hub the project belongs to, so a project on another
+instance is recognised rather than looking like it isn't one; a private repo,
+which won't serve that file anonymously, falls back to asking your hub.
+
+On a **pull request**, the panel compares DVC-tracked outputs between the
+branch and its base, so a regenerated figure can be looked at next to the one
+it replaces. GitHub's own diff can only show the `.dvc` pointer changing,
+which says an output changed but nothing about how.
+
+From there you can open the project on its hub, or connect a repo that isn't a
+project yet. For a connected project the extension **adds its DVC-tracked
+files to GitHub's own file listing**, badged as DVC, since GitHub can only show
+the `.dvc` pointer files. Clicking one opens it: image preview or download,
+straight from the project's DVC storage.
+
+### References
+
+On a journal, publisher, or preprint page, the extension reads the page's
+citation metadata (Highwire Press and Dublin Core tags, the same ones Zotero
+relies on) and tells you whether that reference is already in a collection in
+one of your projects. From there you can:
+
+- Import it into any `.bib` collection in a project.
+- Read and edit the notes attached to it, which are stored in the BibTeX
+  `comment` field, and pushed to Zotero for collections linked to it.
+
+The project checked is the **active project**, which the panel names in a
+dropdown at the top: changing it there switches the active project outright,
+so what was checked and what an import lands in can't drift apart, and the
+next paper starts where this one left off.
+
+One project rather than a list is deliberate: it suits a thesis-scale
+monorepo, and it's also what keeps the lookup fast, since each project has to
+be read on the server to search its collections.
+
+The content script runs on the major preprint servers and publishers (arXiv,
+bioRxiv, PLOS, Springer, Wiley, Elsevier, Nature, Science, MDPI, Cambridge
+Core, AIP, ACS, RSC, IOP, ASME, AIAA, Oxford, and others). Publishers that
+spread journals across subdomains are matched with a wildcard host, so
+`agupubs.onlinelibrary.wiley.com` and `collections.plos.org` are covered by
+the same entry as their parents.
+
+That list can't ever be complete, and every host on it is a permission the
+user has to grant, so it stays limited to sites worth injecting into. The
+popup does the same detection on **any** page through `activeTab`, which is
+the general answer for everything else.
+
+## Installing during development
+
+```sh
+npm install
+npm run build
+```
+
+Then, in Chrome, open `chrome://extensions`, turn on **Developer mode**, click
+**Load unpacked**, and select the `dist` directory.
+
+## Signing in
+
+The extension uses the hub's device authorization flow, the same one
+`calkit hub login` uses. Click **Sign in** in the popup, approve the request in
+the tab that opens, and the extension stores a short-lived access token plus a
+refresh token in `chrome.storage.local`, scoped to the hub it came from.
+
+Nothing else ever sees the token: every API call runs in the service worker,
+which the content scripts drive through a fixed set of named operations rather
+than a general "fetch this URL" proxy.
+
+## Image previews and object storage
+
+Panels live in the host page's DOM, so the page's content security policy
+decides what they can load, and sites like GitHub don't allow images from
+object storage. Previews are therefore fetched in the service worker and
+handed to the panel as data URLs, which every page allows.
+
+That fetch needs the storage host in `host_permissions`. The manifest lists
+Google Cloud Storage and S3, which covers the hosted instances. A hub using
+some other storage, e.g. MinIO, needs its host added; without it the preview
+is dropped and the download link still works.
+
+## Settings
+
+The options page holds two settings.
+
+**Hub** selects between calkit.io, the staging instance, a local development
+instance, and a self-hosted one. Changing it applies immediately, and the
+page then shows whether you're signed in to the newly selected hub, since
+credentials are stored per hub and switching generally means signing in
+again.
+
+A hub serves its API from the `api` subdomain of the host serving its web
+app, so a self-hosted hub is configured with its URL alone:
+`https://calkit.example.edu` implies `https://api.calkit.example.edu`. Chrome
+prompts for access to that host when the hub is applied. This matches
+`calkit.hub.api_url_from_hub_url` in the Python package; see the
+[self-hosting docs](../docs/hub/self-hosting.md).
+
+**Active project** is the project being worked on, remembered per hub.
+Reference lookups check its collections, and importing a reference defaults to
+it. It can also be switched from the popup.
+
+Project pickers list only projects you can **write** to
+(`GET /projects?min_access_level=write`), since every action they offer
+writes. The GitHub panel is the exception: it resolves a repo at read
+access, because browsing the DVC artifacts behind a public project you
+don't own is the point of it.
+
+## Layout
+
+```
+public/manifest.json   Extension manifest
+popup.html             Toolbar popup page, built to dist/popup.html
+options.html           Options page, built to dist/options.html
+src/background/        Service worker: auth, API calls, message routing
+src/content/           One content script per site (github, overleaf,
+                       references)
+src/core/              Hub config, storage, API client, page detection, UI
+src/popup/             Popup script and shared page styles
+src/options/           Options script
+```
+
+Both pages are built to the root of `dist` rather than to a path under
+`src/`, so they load from `chrome-extension://<id>/options.html`. Content
+blockers match on request paths and some of their filter lists catch generic
+source-tree paths, which is enough to break an extension page with
+`ERR_BLOCKED_BY_CLIENT`.
+
+## Development
+
+```sh
+npm run check    # Type-check
+npm test         # Unit tests for URL and citation-metadata parsing
+npm run format   # Prettier
+npm run build    # Type-check, then build into dist/
+npm run dev      # Rebuild into dist/ as sources change
+```
+
+`dist` is a directory Chrome has loaded, not just build output, so anything
+that empties it is doing so underneath a running extension. The type check
+therefore happens before `dist` is cleared, and `npm run build` shouldn't be
+run while `npm run dev` is watching: both own the same directory, and a
+service worker that goes missing mid-build stays failed until the extension
+is reloaded.
+
+Content scripts are bundled one at a time as IIFEs (see
+`scripts/build-content.mjs`), because Chrome runs them as classic scripts,
+which can't be ES modules or be code-split.
+
+## Backend requirements
+
+The Overleaf and reference features need hub API endpoints added alongside
+this extension:
+
+- `GET /overleaf-links` resolves an Overleaf project ID to the Calkit projects
+  that sync with it.
+- `GET /projects/{owner}/{project}/overleaf-syncs/status` reports what a sync
+  would do without doing it.
+- `GET /projects?github_repo=owner/repo` looks a project up by its GitHub repo.
+- `GET /user/references/search` finds a reference across named projects.

calkit_python-0.42.0/browser-ext/options.html

@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <title>Calkit options</title>
+    <link rel="stylesheet" href="./src/popup/popup.css" />
+  </head>
+  <body class="options">
+    <div id="app"></div>
+    <script type="module" src="./src/options/options.ts"></script>
+  </body>
+</html>