Project Overview

[spelkey-ucd]

Goal

Build an npm package (I will publish when ready) that provides a Lit web component for users to:

1. Summarize cookies for the current site
2. Group cookies using regex rules
3. Delete one cookie or delete an entire group
4. Automatically attempt deletion at host and parent-domain levels

This helps users remove unnecessary cookies (e.g. Google Analytics cookies on shared domains like .ucdavis.edu) that can contribute to request header size issues.

Initially, we can include this on an intranet page.

---

Package Requirements

• Package name: @ucdlib/cork-cookie-manager
• Custom element: <cork-cookie-manager></cork-cookie-manager>
• Must be built using Lit
• Must be installable via npm
• Must export a separate rules module (see below)

---

Incremental Workflow with AI (Required)

Work in small slices:

1. Implement one small feature at a time
2. Open a PR early (even if minimal but working)
3. Request a review from Copilot
4. Review feedback and incorporate what makes sense
5. When done with the whole project, make a PR for me to review. (feel free to ask me to review any of the incremental PRs if you need the guidance)

Do not build the entire feature set before opening a PR.

---

Configuration API

The component must support both configuration methods below.

A) Attribute / property

• group-rules (Array): array of grouping rules
• parent-domain (string, optional): overrides automatic parent-domain detection

---

B) JSON <script> child (Required)

The element must accept configuration via a child:

<cork-cookie-manager>
  <script type="application/json">
    {
      "groupRules": [
        {
          "name": "googleAnalytics",
          "label": "Google Analytics",
          "patterns": ["^_ga", "^_gid", "^_gat", "^_ga_"]
        },
        {
          "name": "other",
          "label": "Other",
          "patterns": [".*"]
        }
      ]
    }
  </script>
</cork-cookie-manager>

Rules:

• Watch for changes to its children using MutationObserver
• If a valid JSON script tag is present, parse and use as config
• If both attribute config and script config are provided, script config wins.
• If config is missing or invalid, fall back to:
  • name: "all"
  • label: "All non-HttpOnly cookies"
  • patterns: [".*"]

---

Cookie Behavior

Cookie summarization

• Read cookies from document.cookie
• Parse into:

{
  name: string,
  value: string,
  valueLength: number
}

• Do not display full cookie values
• Display value length only

---

Grouping Rules

• Cookies are assigned to the first group whose regex matches the cookie name
• name must be unique (internal identifier)
• label is displayed in the UI
• If no valid rules exist, everything goes into “All cookies”

---

Automatic Parent-Domain Delete Attempts (Required)

When deleting a cookie (single or group), the component must automatically attempt deletion for:

1. Host-only (no Domain= attribute)
2. Computed parent domain derived from location.hostname

Parent-domain computation

Default behavior:

• Take the last two hostname labels
• Prefix with a dot

Example:

datalab.ucdavis.edu → .ucdavis.edu

If hostname has fewer than two labels, skip parent-domain attempt.

Override

If the parent-domain attribute/property is provided, use that instead of computing it.

---

Delete Requirements

Delete single cookie

• Button per cookie: “Delete”
• Must attempt expiration with:
  • Path=/
  • Host-only delete
  • Parent-domain delete (computed or overridden)

Delete group

• Button per group: “Delete group”
• Deletes every cookie in the group

After deletion

• Refresh cookie list immediately
• If cookies remain, show warning:

Some cookies could not be removed (domain/path mismatch or HttpOnly).

---

Exported Rules Module

The package must export:

import { rules } from '@ucdlib/cork-cookie-manager';

rules must be an array of objects:

{
  name: string,   // unique identifier
  label: string,  // display name
  patterns: string[]
}

Notes:

• name is used internally for filtering
• label is used in the UI
• Do not assume label is unique

Include at least:

• A Google Analytics rule covering:
  • _ga
  • _gid
  • _gat
  • _ga_*

---

UI Requirements (Keep It Simple)

For each group:

• Show group label
• Show total cookie count and size
• Expand/collapse control
• “Delete group” button

Inside each group:

• Show cookie name
• Show value length
• “Delete” button

No advanced styling required. Keep it clean, readable, and use campus styles.

---

README Requirements

Include:

Installation:

npm install @ucdlib/cork-cookie-manager

Also include:

• Usage examples (attribute config + script tag config)
• Explanation of grouping behavior (first match wins)
• Explanation of automatic parent-domain delete attempts
• HttpOnly disclaimer e.g. This tool only manages cookies accessible via JavaScript. HttpOnly cookies cannot be viewed or removed.
• Example of importing exported rules

---

Suggested Incremental PR Plan

1. Scaffold package and render element
2. Parse document.cookie and display simple list
3. Implement config parsing (attribute + script tag)
4. Add grouping logic
5. Add delete single cookie (host-only + parent domain)
6. Add delete group
7. Add exported rules module
8. Write README and polish

Focus on correctness, clarity, and incremental progress. Try to keep copying code from other projects to an absolute minimum - it's good to go through the motions.

---

Local Development

Add local-dev section. No need for docker or express, http-server will suffice. Make sure when publishing to npm, this section is not included.