astrowidget 0.1.0__tar.gz

astrowidget-0.1.0/.claude/commands/clean-branches.md

@@ -0,0 +1,52 @@
+Clean up local and remote git branches.
+
+## Arguments
+
+$ARGUMENTS — optional: "all", "stale", "merged", or a specific branch name. If
+omitted, prompt the user.
+
+## Instructions
+
+1. Run these commands in parallel to gather branch information:
+   - `git branch` (local branches)
+   - `git branch -r` (remote branches, exclude HEAD)
+   - `git branch --merged main` (branches merged into main)
+   - `git for-each-ref --sort=-committerdate --format='%(refname:short) %(committerdate:relative) %(upstream:track)' refs/heads/`
+     (local branches with age and tracking status)
+
+2. Categorize each branch (excluding `main` and `feedback-screenshots`):
+
+   | Category            | Definition                                                        |
+   | ------------------- | ----------------------------------------------------------------- |
+   | **Merged**          | Branch is in `git branch --merged main` output                    |
+   | **Stale**           | Last commit is older than 30 days                                 |
+   | **Orphaned remote** | Remote branch exists but no local branch tracks it                |
+   | **Orphaned local**  | Local branch exists but remote is gone (`[gone]` tracking status) |
+   | **Active**          | Has recent commits and is not merged                              |
+
+3. If `$ARGUMENTS` is empty or unclear:
+   - Display a summary table of all branches grouped by category with branch
+     name, last commit age, and local/remote status
+   - Ask the user which categories to clean: merged, stale, orphaned, or all
+   - Wait for the user's response before proceeding
+
+4. If `$ARGUMENTS` specifies a category or "all":
+   - Show the list of branches that will be deleted
+   - Ask for confirmation before proceeding
+
+5. Delete branches:
+   - Local branches: `git branch -d <name>` (safe delete, merged only) or
+     `git branch -D <name>` (if user confirms force delete for unmerged)
+   - Remote branches: `git push origin --delete <name>`
+   - Run `git fetch --prune` after remote deletions
+
+6. Confirm results: show what was deleted and what remains.
+
+## Rules
+
+- NEVER delete `main`, `master`, or `feedback-screenshots` branches
+- NEVER force-delete (`-D`) without explicit user confirmation
+- Always show what will be deleted before doing it
+- If a branch has unmerged commits, warn the user and ask before force-deleting
+- Run `git fetch --prune` at the end to clean up stale remote refs
+- If there are no branches to clean, say so and exit

astrowidget-0.1.0/.claude/commands/commit.md

@@ -0,0 +1,57 @@
+Commit staged and unstaged changes to the current branch.
+
+## Instructions
+
+1. Run `git status` (never use `-uall`) and `git diff --stat` to see all
+   changes.
+2. Run `git log --oneline -5` to see the commit message style for this repo.
+3. Analyze ALL changes (staged + unstaged) and determine:
+   - The conventional commit type: `feat`, `fix`, `refactor`, `docs`, `chore`,
+     `style`, `test`, `perf`, `ci`, `build`
+   - An optional scope in parentheses based on what area changed (e.g.,
+     `marketing`, `platform`, `developer`, `billing`, `db`, `auth`, `worker`,
+     `ui`, `tokens`)
+   - A concise imperative description of WHY, not WHAT
+4. Do NOT commit files that likely contain secrets (`.env`, `.env.local`,
+   credentials, API keys). Warn if any are staged.
+5. Do NOT commit `.DS_Store` files.
+6. Stage relevant untracked files by name (never use `git add -A` or
+   `git add .`).
+7. Create the commit using this format:
+
+```
+git commit -m "$(cat <<'EOF'
+type(scope): short imperative description
+
+Optional body explaining the why, not the what.
+Multi-line is fine for complex changes.
+EOF
+)"
+```
+
+8. Run `git status` after to verify success.
+9. If a pre-commit hook fails, fix the issue and create a NEW commit (never
+   amend).
+
+## Conventional Commit Types
+
+| Type       | When to use                                             |
+| ---------- | ------------------------------------------------------- |
+| `feat`     | New feature or capability                               |
+| `fix`      | Bug fix                                                 |
+| `refactor` | Code change that neither fixes a bug nor adds a feature |
+| `docs`     | Documentation only                                      |
+| `chore`    | Maintenance, deps, config                               |
+| `style`    | Formatting, whitespace (not CSS)                        |
+| `test`     | Adding or updating tests                                |
+| `perf`     | Performance improvement                                 |
+| `ci`       | CI/CD changes                                           |
+| `build`    | Build system or tooling                                 |
+
+## Rules
+
+- Keep the first line under 72 characters
+- Use imperative mood ("add" not "added", "fix" not "fixed")
+- Scope is optional but preferred when changes are localized
+- Never skip hooks (`--no-verify`)
+- Never amend unless explicitly asked

astrowidget-0.1.0/.claude/commands/create-issue.md

@@ -0,0 +1,62 @@
+Create a GitHub issue for tracking work.
+
+## Arguments
+
+$ARGUMENTS — a description of the issue to create
+
+## Instructions
+
+1. Based on `$ARGUMENTS`, determine:
+   - **Type**: `feat`, `fix`, `refactor`, `docs`, `chore`, `perf`, `ci`,
+     `build`, `test`
+   - **Scope**: the area of the codebase affected (e.g., `marketing`,
+     `platform`, `developer`, `billing`, `db`, `auth`, `worker`, `ui`, `tokens`,
+     `infra`)
+   - **Title**: conventional commit format:
+     `type(scope): short imperative description`
+
+2. Draft a structured issue body with relevant sections:
+
+```bash
+gh issue create --title "type(scope): description" --body "$(cat <<'EOF'
+## Summary
+
+<1-2 sentences describing the problem or feature>
+
+## Requirements
+
+<bulleted list of specific requirements or acceptance criteria>
+- [ ] Requirement 1
+- [ ] Requirement 2
+
+## Context
+
+<any relevant context, links, or background — omit if not needed>
+
+## Implementation Notes
+
+<optional technical direction or constraints — omit if not needed>
+EOF
+)"
+```
+
+3. Return the issue URL and number to the user.
+
+## Title Convention
+
+| Type              | Example                                                             |
+| ----------------- | ------------------------------------------------------------------- |
+| `feat(marketing)` | `feat(marketing): add testimonial carousel to landing page`         |
+| `fix(auth)`       | `fix(auth): resolve PKCE exchange failure on second localhost port` |
+| `refactor(db)`    | `refactor(db): normalize ingredient tables to reduce duplication`   |
+| `docs(guides)`    | `docs(guides): add Stripe webhook deployment checklist`             |
+| `chore(deps)`     | `chore(deps): upgrade React to 19.3`                                |
+
+## Rules
+
+- Title must use conventional commit format: `type(scope): description`
+- Keep title under 70 characters
+- Use imperative mood ("add" not "adds", "fix" not "fixes")
+- Requirements section should have checkboxes for trackable items
+- Omit sections that aren't relevant (don't pad with empty sections)
+- If `$ARGUMENTS` is vague, ask clarifying questions before creating

astrowidget-0.1.0/.claude/commands/create-pr.md

@@ -0,0 +1,56 @@
+Create a pull request for the current branch.
+
+## Instructions
+
+1. Run these commands in parallel to understand the current state:
+   - `git status` (never use `-uall`)
+   - `git diff --stat` (check for uncommitted changes)
+   - `git branch --show-current` (current branch)
+   - `git log --oneline main..HEAD` (all commits being PR'd)
+   - `git diff main...HEAD --stat` (full diff summary against main)
+
+2. If there are uncommitted changes, ask whether to commit first.
+
+3. If the branch hasn't been pushed, push with `git push -u origin <branch>`.
+
+4. Analyze ALL commits in the branch (not just the latest) to draft:
+   - **Title**: Use conventional commit format: `type(scope): short description`
+     (under 70 chars)
+   - **Body**: Structured summary with test plan
+
+5. Create the PR:
+
+```bash
+gh pr create --title "type(scope): description" --body "$(cat <<'EOF'
+## Summary
+<1-3 bullet points covering what changed and why>
+
+## Changes
+<bulleted list of specific changes, grouped by area if needed>
+
+## Test plan
+- [ ] <specific testable checklist items>
+EOF
+)"
+```
+
+6. If there's a related issue, add `Closes #N` in the body.
+7. Return the PR URL to the user.
+
+## Title Convention
+
+Use the same conventional commit types as /commit:
+
+- `feat(scope):` for new features
+- `fix(scope):` for bug fixes
+- `refactor(scope):` for restructuring
+- `docs(scope):` for documentation
+- `chore(scope):` for maintenance
+
+## Rules
+
+- Keep title under 70 characters
+- Always include a test plan with specific checkboxes
+- Never create a PR from `main` to `main`
+- If the branch name contains a hint (e.g., `feat/`, `fix/`), use that as the
+  commit type

astrowidget-0.1.0/.claude/commands/docs.md

@@ -0,0 +1,107 @@
+Write comprehensive documentation for recent work in this session.
+
+Arguments: $ARGUMENTS (optional — topic, section, or "all" to regenerate
+broadly)
+
+## Instructions
+
+1. **Gather context** — Run these in parallel to understand what changed:
+   - `git log --oneline -20` (recent commits)
+   - `git diff main...HEAD --stat` (if on a feature branch)
+   - `git log --oneline --since="8 hours ago"` (today's work)
+   - Review any open plans in `docs/plans/`
+   - Read `docs/index.md` and `mkdocs.yml` for existing structure
+
+2. **Determine scope** — Based on the argument and recent changes, decide which
+   docs need writing or updating:
+   - If argument is a specific topic (e.g., "queues", "auth", "notifications"),
+     focus there
+   - If argument is a section (e.g., "architecture", "database", "guides"),
+     update that section
+   - If argument is "all" or empty, document everything from the current session
+   - Always check existing docs first — update rather than duplicate
+
+3. **Write documentation** covering these categories as relevant:
+
+   ### Technical Details
+   - What was built, changed, or fixed
+   - API contracts, database schema changes, new RPC functions
+   - Configuration changes, environment variables, dependencies added
+   - Code patterns introduced or modified
+
+   ### Technical Architecture
+   - System design and component relationships
+   - Data flow diagrams (use Mermaid syntax)
+   - Integration points between services (workers, platform, database)
+   - Infrastructure decisions (Cloudflare, Neon, WorkOS, Stripe, etc.)
+
+   ### Session Learnings
+   - Decisions made and their rationale (ADR-style: Decision / Why / Result)
+   - Technical issues encountered and how they were resolved
+   - Trade-offs considered and which path was chosen
+   - Gotchas, edge cases, or surprising behavior discovered
+   - Things that didn't work and why
+
+4. **Place documentation correctly:**
+   - New architecture docs → `docs/architecture/`
+   - Database changes → `docs/database/`
+   - Frontend changes → `docs/frontend/`
+   - How-to content → `docs/guides/`
+   - Implementation plans → `docs/plans/` (named `YYYY-MM-DD-topic.md`)
+   - Session learnings → `docs/guides/architecture-decisions.md` (append new
+     entries at top of relevant section)
+   - Script documentation → `docs/scripts/`
+
+5. **Update mkdocs.yml nav** — If you created a new file, add it to the `nav:`
+   section in `mkdocs.yml` under the correct heading. Match existing indentation
+   and naming style.
+
+6. **Update docs/index.md** — If the new doc is significant, add a link in the
+   Documentation section of `docs/index.md` with a one-line description.
+
+7. **Verify** — Run `pixi run docs-build` to confirm MkDocs builds without
+   errors.
+
+8. **Report** — Show the user:
+   - Files created or updated (with paths)
+   - New nav entries added
+   - Build status (pass/fail)
+
+## Documentation Style
+
+- Use MkDocs Material features: admonitions (`!!! note`, `!!! warning`,
+  `!!! tip`), tabs, Mermaid diagrams, code blocks with language tags
+- Start every doc with a level-1 heading and a 1-2 sentence summary
+- Use tables for structured data (configs, env vars, field mappings)
+- Keep headings hierarchical (h1 → h2 → h3, never skip levels)
+- Use imperative voice for guides ("Run the migration", not "You should run the
+  migration")
+- Architecture decisions follow the pattern:
+
+```markdown
+### YYYY-MM-DD: Decision Title (Status)
+
+- **Decision:** What was decided
+- **Why:** The reasoning and constraints
+- **Result:** What was implemented and any notable outcomes
+```
+
+## Mermaid Diagram Conventions
+
+- Use `graph TD` for top-down architecture diagrams
+- Use `sequenceDiagram` for request/response flows
+- Use `erDiagram` for database relationships
+- Keep diagrams focused — split complex systems into multiple diagrams
+- Label edges with the protocol or mechanism (e.g., `-->|JWT|`, `-->|REST|`,
+  `-->|Queue|`)
+
+## Rules
+
+- Never delete existing documentation — update or extend it
+- Always read existing docs before writing to avoid duplication
+- Every new doc must appear in `mkdocs.yml` nav
+- Date-stamp architecture decisions and plans
+- Use relative links between docs (e.g., `../guides/getting-started.md`)
+- Build must pass before considering the task done
+- If `pixi run docs-build` fails, fix the issue (usually a nav mismatch or
+  broken link)

astrowidget-0.1.0/.claude/commands/merge-pr.md

@@ -0,0 +1,51 @@
+Merge a pull request and clean up branches.
+
+## Arguments
+
+$ARGUMENTS — PR number or URL (optional, defaults to current branch's PR)
+
+## Instructions
+
+1. Determine the PR:
+   - If `$ARGUMENTS` is provided, use it as the PR number or URL
+   - If not, find the PR for the current branch:
+     `gh pr view --json number,title,state,headRefName`
+
+2. Check PR status:
+   - `gh pr view <number> --json state,mergeable,mergeStateStatus,statusCheckRollup,title,headRefName`
+   - If checks are failing, warn the user and ask whether to proceed
+   - If there are merge conflicts, tell the user and stop
+
+3. Check for local uncommitted changes:
+   - `git status`
+   - If there are unstaged changes, stash them before proceeding: `git stash`
+
+4. Merge the PR:
+
+   ```bash
+   gh pr merge <number> --squash --delete-branch
+   ```
+
+   Use `--squash` by default (consistent with this repo's history).
+
+5. Clean up locally:
+   - Switch to main if not already: `git checkout main`
+   - Pull the merged changes: `git pull origin main`
+   - Prune stale remote refs: `git fetch --prune`
+   - Delete the local branch if it still exists: `git branch -d <branch-name>`
+   - If changes were stashed, restore them: `git stash pop`
+
+6. Verify cleanup:
+   - `git branch -a | grep <branch-name>` to confirm branch is gone everywhere
+
+7. Confirm: "PR #N merged into main. Branch `<name>` deleted locally and
+   remotely."
+
+## Rules
+
+- Default merge strategy is `--squash` (produces clean linear history)
+- If user asks for a merge commit, use `--merge` instead
+- If user asks for rebase, use `--rebase` instead
+- NEVER force-delete branches (`-D`), use `-d` which is safe
+- Always restore stashed changes after merge
+- If the merge fails, do NOT retry destructively — report the error

astrowidget-0.1.0/.claude/commands/push.md

@@ -0,0 +1,25 @@
+Push the current branch to the remote repository.
+
+## Instructions
+
+1. Run `git status` to check:
+   - Current branch name
+   - Whether there are uncommitted changes (warn the user if so)
+   - Whether the branch tracks a remote
+2. Run `git log --oneline origin/$(git branch --show-current)..HEAD 2>/dev/null`
+   to see unpushed commits. If the remote branch doesn't exist yet, show all
+   commits since diverging from `main`.
+3. Show the user what will be pushed (branch name + commit list).
+4. Push:
+   - If the branch has no upstream yet: `git push -u origin <branch-name>`
+   - If it already tracks a remote: `git push`
+5. Confirm success.
+
+## Rules
+
+- NEVER force push (`--force`, `-f`) unless the user explicitly asks
+- NEVER force push to `main` or `master` — warn the user and refuse
+- If there are uncommitted changes, ask whether to commit first (using /commit
+  conventions) or push what's already committed
+- If push is rejected due to remote changes, suggest `git pull --rebase` and ask
+  before proceeding

astrowidget-0.1.0/.claude/commands/release.md

@@ -0,0 +1,132 @@
+Create a versioned release that triggers PyPI publishing via trusted publisher.
+
+## Arguments
+
+$ARGUMENTS — version bump type: `patch`, `minor`, or `major` (optional, defaults
+to analyzing changes)
+
+## Instructions
+
+1. Determine the version bump:
+   - If `$ARGUMENTS` specifies `patch`, `minor`, or `major`, use that
+   - If not specified, analyze commits since the last tag to determine:
+     - `major`: breaking changes (commits with `!` or `BREAKING CHANGE`)
+     - `minor`: new features (`feat:` commits)
+     - `patch`: fixes, refactors, docs, chores only
+
+2. Get the current version:
+   - Check `git tag --sort=-v:refname | head -1` for the latest tag
+   - If no tags exist, start at `v0.1.0`
+   - Also check `pyproject.toml` `version` field
+
+3. Calculate the new version following semver.
+
+4. Verify readiness:
+   - `git status` — must be on `main` with no uncommitted changes
+   - `git pull origin main` — must be up to date
+   - Warn and stop if not on `main` or if there are uncommitted changes
+
+5. Update the version in `pyproject.toml`:
+   - Change `version = "X.Y.Z"` to the new version
+   - Also update `__version__` in `src/astrowidget/__init__.py`
+
+6. Ensure the JS bundle is current:
+   - Copy `js/inline_widget.js` to `src/astrowidget/static/widget.js`
+   - Verify `src/astrowidget/static/widget.js` exists
+
+7. Run tests to verify everything works:
+   ```bash
+   pixi run test-py
+   ```
+   Stop if tests fail.
+
+8. Verify the package builds:
+   ```bash
+   pip install build && python -m build
+   ```
+   Check that `dist/astrowidget-X.Y.Z-py3-none-any.whl` contains
+   `astrowidget/static/widget.js`.
+
+9. Commit the version bump:
+    ```bash
+    git add pyproject.toml src/astrowidget/__init__.py src/astrowidget/static/widget.js
+    git commit -m "chore(release): prepare vX.Y.Z"
+    ```
+
+10. Create the git tag:
+    ```bash
+    git tag -a vX.Y.Z -m "vX.Y.Z"
+    ```
+
+11. Ask for confirmation before pushing.
+
+12. Push the commit and tag:
+    ```bash
+    git push origin main --follow-tags
+    ```
+
+13. Create a GitHub release (triggers the publish workflow):
+    ```bash
+    gh release create vX.Y.Z --title "vX.Y.Z" \
+      --generate-notes \
+      --latest
+    ```
+
+    This uses `.github/release.yml` to auto-generate categorized release notes:
+    - PRs labeled `breaking` appear under **Breaking Changes**
+    - PRs labeled `enhancement` appear under **New Features**
+    - PRs labeled `bug` appear under **Bug Fixes**
+    - PRs labeled `documentation` appear under **Documentation**
+    - All other PRs appear under **Other Changes**
+    - Commits from `dependabot` and `pre-commit-ci` are excluded
+
+    The `.github/workflows/publish.yml` workflow will then automatically:
+    - Build the JS bundle and Python package
+    - Publish to PyPI via trusted publisher (OIDC)
+
+14. Confirm: "Released vX.Y.Z — <release URL>"
+    - Remind user to check the GitHub Actions run for PyPI publish status
+
+## Prerequisites
+
+Before the first release, the following must be configured:
+
+1. **PyPI**: Add a pending trusted publisher at
+   [pypi.org/manage/account/publishing](https://pypi.org/manage/account/publishing/)
+   with owner=`uw-ssec`, repo=`astrowidget`, workflow=`publish.yml`,
+   environment=`pypi`
+
+2. **GitHub**: Create a `pypi` environment in the repo settings
+   (Settings → Environments → New environment → name it `pypi`)
+
+## Version Guidelines
+
+| Bump            | When                               | Example              |
+| --------------- | ---------------------------------- | -------------------- |
+| `patch` (0.1.X) | Bug fixes, docs, chores, refactors | `v0.1.1` → `v0.1.2` |
+| `minor` (0.X.0) | New features, non-breaking changes | `v0.1.2` → `v0.2.0` |
+| `major` (X.0.0) | Breaking changes, major rewrites   | `v0.2.0` → `v1.0.0` |
+
+## Release Note Labels
+
+For the auto-generated release notes to categorize PRs correctly, apply these
+labels to PRs before merging:
+
+| Label | Release Notes Section |
+|---|---|
+| `breaking` | Breaking Changes |
+| `enhancement` | New Features |
+| `bug` | Bug Fixes |
+| `documentation` | Documentation |
+| `ignore-for-release` | Excluded from notes |
+
+PRs without these labels appear under **Other Changes**.
+
+## Rules
+
+- Must be on `main` branch with no uncommitted changes
+- All tests must pass before releasing
+- Never create a release from a feature branch
+- Tag format is always `vX.Y.Z` (with `v` prefix)
+- The wheel must include `astrowidget/static/widget.js`
+- Ask for confirmation before pushing the tag and creating the release

astrowidget-0.1.0/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,90 @@
+name: Bug Report
+description: Report a bug in astrowidget
+labels: ["bug"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for taking the time to report a bug. Please fill out the sections below
+        so we can reproduce and fix the issue.
+
+  - type: textarea
+    id: description
+    attributes:
+      label: Description
+      description: A clear and concise description of the bug.
+    validations:
+      required: true
+
+  - type: textarea
+    id: reproduce
+    attributes:
+      label: Steps to Reproduce
+      description: Minimal steps or code to reproduce the behavior.
+      placeholder: |
+        1. Load data with `open_dataset("...")`
+        2. Call `widget.set_dataset(ds)`
+        3. Click on the sphere
+        4. See error in browser console
+    validations:
+      required: true
+
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected Behavior
+      description: What you expected to happen.
+    validations:
+      required: true
+
+  - type: textarea
+    id: actual
+    attributes:
+      label: Actual Behavior
+      description: What actually happened. Include error messages or screenshots if applicable.
+    validations:
+      required: true
+
+  - type: input
+    id: python-version
+    attributes:
+      label: Python Version
+      placeholder: "3.12.0"
+    validations:
+      required: true
+
+  - type: dropdown
+    id: environment
+    attributes:
+      label: Jupyter Environment
+      options:
+        - JupyterLab
+        - Jupyter Notebook (classic)
+        - VS Code
+        - Other
+    validations:
+      required: true
+
+  - type: input
+    id: browser
+    attributes:
+      label: Browser
+      placeholder: "Chrome 124, Firefox 126, Safari 17"
+    validations:
+      required: true
+
+  - type: input
+    id: os
+    attributes:
+      label: Operating System
+      placeholder: "macOS 15, Ubuntu 24.04, Windows 11"
+    validations:
+      required: false
+
+  - type: textarea
+    id: additional
+    attributes:
+      label: Additional Context
+      description: Any other context -- sample data, console logs, screenshots, etc.
+    validations:
+      required: false

astrowidget-0.1.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,8 @@
+blank_issues_enabled: true
+contact_links:
+  - name: SSEC Contributing Guidelines
+    url: https://github.com/uw-ssec/.github/blob/main/CONTRIBUTING.md
+    about: Organization-wide contribution guidelines and AI-usage policy
+  - name: Documentation
+    url: https://uw-ssec.github.io/astrowidget
+    about: Check the docs before filing -- your question may already be answered