Codap Resources

codap-resources

Manage assets in the s3://codap-resources/ S3 bucket using the AWS CLI.

The bucket is served via CloudFront at codap-resources.concord.org.

When Invoked

Display this to the user:

codap-resources — Deploy and manage assets in the codap-resources S3 bucket (served at codap-resources.concord.org).

This skill helps with copying files, syncing plugin builds, and invalidating the CloudFront cache for the CODAP resource bucket.

Requirements:

• AWS CLI installed (aws --version)
• Authenticated with credentials that have write access to the codap-resources bucket and permission to create CloudFront invalidations

What do you want to do?

Then ask the user what they want to do, or proceed with the task if it was already specified.

Bucket Structure

Common Commands

Copy a single file

aws s3 cp <local-file> s3://codap-resources/<folder>/<filename> --acl public-read

For notifications/ assets, always add no-cache:

aws s3 cp <local-file> s3://codap-resources/notifications/<filename> \
  --acl public-read \
  --cache-control "no-cache, no-store, must-revalidate"

Sync a folder (plugins, examples, etc.)

Always use --size-only — timestamps never match between local files and S3, so without this flag every file will appear changed. Always dry-run first so the user can review what will change before anything is uploaded:

# 1. Dry run — show what would change
aws s3 sync <local-folder> s3://codap-resources/<folder>/<name>/ \
  --acl public-read --size-only --dryrun

# 2. After user confirms, run for real
aws s3 sync <local-folder> s3://codap-resources/<folder>/<name>/ \
  --acl public-read --size-only

Add --delete to remove S3 files that no longer exist locally. Omit it to preserve old files.

CloudFront Invalidation

After updating cached assets (plugins, documents, boundaries), invalidate the CloudFront cache so changes are served immediately. Not needed for notifications/ since those use no-cache headers.

There are three distributions, and the one you invalidate depends on how the asset is consumed:

⚠️ Production V3 does NOT load assets from codap-resources.concord.org. It loads them from a relative /codap-resources/... path (see kCodapResourcesUrl in v3/src/constants.ts, which resolves to "/codap-resources" when not in local dev). That path is served by the app distributions — E7WVRGISCR2VR (codap3) and E26XOJN7T3CJO (codap / codap2to3) — each with its own edge cache. Invalidating only E1RS9TZVZBEEEC leaves production users on stale files. Anything production V3 loads (plugins, example-document guides, boundaries) needs the app distributions invalidated too.

🛑 On the app distributions, invalidate the STRIPPED path (/<folder>/*), NOT /codap-resources/<folder>/*. The /codap-resources/* behavior has a viewer-request CloudFront function (StripCodapResourcesPrefix) that rewrites the URI /codap-resources/... → /... before the cache key is computed. Objects are therefore cached under the stripped key (e.g. /plugins/onboarding/strings.json). An invalidation for /codap-resources/plugins/onboarding/* matches nothing — it reports Completed while purging zero objects, and stale content keeps being served. Always invalidate the post-rewrite path: /plugins/onboarding/*.

# codap-resources.concord.org (direct bucket access — no prefix function)
aws cloudfront create-invalidation --distribution-id E1RS9TZVZBEEEC \
  --paths "/<folder>/*"

# production app hosts (what V3 users actually hit) — use the STRIPPED path, repeat for both
aws cloudfront create-invalidation --distribution-id E7WVRGISCR2VR \
  --paths "/<folder>/*"
aws cloudfront create-invalidation --distribution-id E26XOJN7T3CJO \
  --paths "/<folder>/*"

To confirm an invalidation actually took effect (not just Completed), re-request the asset and check the response: x-cache: Miss from cloudfront on the first hit plus the expected last-modified/content means the edge refetched. A Hit with stale last-modified after a Completed invalidation is the tell-tale sign you invalidated the wrong (pre-rewrite) path.

List contents of a folder

aws s3 ls s3://codap-resources/<folder>/

When to Use No-Cache

Use --cache-control "no-cache, no-store, must-revalidate" for any asset that:

• May be updated frequently
• Must take effect immediately after changes (e.g., banners, feature flags, notifications)

Immutable, content-hashed files (webpack chunks with a hash in the filename) can use default caching — their name changes when the content changes.

But mutable, unversioned plugin entry files — index.html, and any top-level same-named-across-deploys files like onboarding.js, strings.json, init_*.js, task_descriptions*.js — should be uploaded with --cache-control "no-cache" so browsers revalidate via ETag and pick up changes immediately instead of waiting out CloudFront's (and the browser's heuristic) default TTL:

aws s3 cp onboarding.js s3://codap-resources/plugins/onboarding/onboarding.js \
  --acl public-read --cache-control "no-cache"

no-cache does NOT mean "don't cache" — it means "cache, but revalidate before reusing." It does not force a full download on every load:

• First load: the browser downloads the file and stores it along with its ETag (the content fingerprint S3 returns).
• Later loads: the browser sends a conditional request (If-None-Match: <etag>). If the file is unchanged, the server returns 304 Not Modified with an empty body and the browser reuses its cached copy — a tiny header-only round-trip, no payload. Only when the content actually changed does the server return 200 with the new body.

So the cost is one lightweight revalidation per load (a 304 when nothing changed), and the benefit is that a deploy is picked up on the next load. Contrast:

• no-store — never cache; full download every time (heavier than needed here).
• max-age=N / immutable — no revalidation round-trip at all; correct only for content-hashed files (the chunk's filename changes when its content does).
• (no Cache-Control) — browsers fall back to heuristic freshness (~10% of age since Last-Modified); a year-old Last-Modified ⇒ ~weeks of staleness. This is the bug to avoid.

Without no-cache, different entry files age out of cache at different times and a deploy can leave users on a half-updated plugin — e.g. a new onboarding.js that references string keys a stale strings.json doesn't have yet, so lookups return raw keys like ~onboarding1.mammals.table.title instead of the translated text.

Deploying Plugins and Example Documents

CODAP V3 loads these assets from S3 (s3://codap-resources/) rather than bundling them in the build. There are two ways assets get there:

• Direct-to-S3 (current, preferred) — copy a plugin's files straight from its source repo to S3. This is the normal path going forward.
• Syncing from a V2 build (historical / bulk) — described further below, kept for context and for the occasional bulk re-sync of many plugins at once.

Before the release of V3, certain static/built-in plugins were deployed as part of the V2 build on codap-server.concord.org, then manually copied to S3 for compatibility with V3. With the release of V3 we are no longer performing regular V2 builds, so the direct-to-S3 path below is required for routine plugin updates.

Direct-to-S3 deploy (no V2 build)

Use this for a targeted update to a single plugin from its source repo (sibling repos under codap-build/, e.g. codap-data-interactives).

Many static plugins are served as raw source with no build step — e.g. Simmer at eepsmedia/plugins/simmer/, whose index.html loads src/*.js directly via script tags. For these the source folder is the deployable artifact: copy the changed file(s) straight to S3, no build required.

1. Identify the S3 location. Plugins live under s3://codap-resources/plugins/<path>/, mirroring the build's layout. The path can be nested — e.g. eepsmedia plugins are at s3://codap-resources/plugins/eepsmedia/plugins/<name>/. Confirm with aws s3 ls, and diff the deployed file against your local copy first so you know exactly what will change.

2. Copy the changed file(s). For mutable entry files (index.html, top-level *.js / strings.json) add --cache-control "no-cache" (see When to Use No-Cache):

   aws s3 cp eepsmedia/plugins/simmer/index.html \
     s3://codap-resources/plugins/eepsmedia/plugins/simmer/index.html \
     --acl public-read --cache-control "no-cache"

   For a whole-folder update use aws s3 sync ... --size-only (see Sync a folder); for webpack-built plugins remember to cp index.html explicitly afterward (hashed chunks).

3. Invalidate CloudFront on all three distributions at the STRIPPED path — see CloudFront Invalidation:

   aws cloudfront create-invalidation --distribution-id E1RS9TZVZBEEEC \
     --paths "/plugins/eepsmedia/plugins/simmer/*"
   aws cloudfront create-invalidation --distribution-id E7WVRGISCR2VR \
     --paths "/plugins/eepsmedia/plugins/simmer/*"
   aws cloudfront create-invalidation --distribution-id E26XOJN7T3CJO \
     --paths "/plugins/eepsmedia/plugins/simmer/*"

4. Verify the edge refetched (required — a Completed status alone proves nothing):

   for host in codap.concord.org codap3.concord.org; do
     echo "--- $host ---"
     curl -sI "https://$host/codap-resources/plugins/eepsmedia/plugins/simmer/index.html" \
       | grep -iE "x-cache|last-modified"
   done

   Expect x-cache: Miss from cloudfront plus the new last-modified on the first request after the invalidation.