@salesforce/afv-skills 1.45.0 → 1.47.0

package/skills/education-cloud-academic-calendar-generate/references/date-validation.md

@@ -0,0 +1,222 @@
+# Academic Calendar Date Validation Rules
+
+## Basic Date Range Validation
+
+### Rule: Term End After Start
+
+**Requirement**: Every term's end date must be strictly after its start date.
+
+**Check**: `END_DATE > START_DATE`
+
+**Example Valid**:
+- Start: 2025-08-18
+- End: 2025-12-12
+- Valid (117 days)
+
+**Example Invalid**:
+- Start: 2025-08-18
+- End: 2025-08-15
+- Invalid (end before start)
+
+**Error Message**: "Term end date must be after start date"
+
+---
+
+### Rule: Academic Year Covers All Terms
+
+**Requirement**: The Academic Year start date must be <= the earliest term start, and the Academic Year end date must be >= the latest term end.
+
+**Check**: 
+- `YEAR_START <= min(TERM_START_DATES)`
+- `YEAR_END >= max(TERM_END_DATES)`
+
+**Example Valid**:
+- Academic Year: 2025-08-18 to 2026-08-14
+- Fall 2025: 2025-08-18 to 2025-12-12
+- Spring 2026: 2026-01-12 to 2026-05-15
+- Summer 2026: 2026-05-26 to 2026-08-14
+- Valid (year spans all terms)
+
+**Example Invalid**:
+- Academic Year: 2025-08-18 to 2026-05-31
+- Summer 2026: 2026-05-26 to 2026-08-14
+- Invalid (Summer extends beyond year end)
+
+**Error Message**: "Academic Year must span all child terms"
+
+---
+
+## Registration and Deadline Validation
+
+### Rule: Registration Opens Before Term Starts
+
+**Requirement**: Registration open date must be before term start date.
+
+**Check**: `REGISTRATION_OPEN < TERM_START`
+
+**Typical Lead Time**: 3-4 months for Fall, 2-3 months for Spring, 1-2 months for Summer
+
+**Example Valid**:
+- Registration Opens: 2025-04-01
+- Term Starts: 2025-08-18
+- Valid (4.5 months lead time)
+
+**Example Invalid**:
+- Registration Opens: 2025-08-20
+- Term Starts: 2025-08-18
+- Invalid (opens after term starts)
+
+**Error Message**: "Registration window must open before term start date"
+
+---
+
+### Rule: Add/Drop Deadline After or Equal to Session Start
+
+**Requirement**: AcademicTerm has NO add/drop field — add/drop deadlines live on AcademicSession only (see `SKILL.md` Gotchas). A deadline must be on or after its session's start date, and before its session's end date.
+
+**Check**: `SESSION_START <= ADD_DROP_DEADLINE < SESSION_END`
+
+**Typical Timing**: 1-2 weeks after session start
+
+**Example Valid**:
+- Session Start: 2025-08-18
+- Add/Drop Deadline: 2025-09-05
+- Session End: 2025-12-12
+- Valid (18 days after start, well before end)
+
+**Example Invalid**:
+- Session Start: 2025-08-18
+- Add/Drop Deadline: 2025-08-10
+- Invalid (deadline before session starts)
+
+**No natural session exists**: If the user gives a per-term add/drop deadline but no session subdivisions, ask the user how to represent it (e.g. propose a single session per term to carry the deadline) — never write the date onto AcademicTerm and never silently drop it.
+
+**Error Message**: "Add/drop deadline must be on or after session start date"
+
+---
+
+## Session Overlap Validation
+
+### Rule: Overlapping Sessions Within Same Term Are Allowed
+
+**Requirement**: Sessions within the same parent term CAN have overlapping date ranges. This is a common pattern for Summer sessions.
+
+**Check**: Flag overlaps for user confirmation, but do not block creation.
+
+**Example Valid (Intentional Overlap)**:
+- Summer 2026 Term: 2026-05-26 to 2026-08-14
+  - Summer Session 1: 2026-05-26 to 2026-07-03 (6 weeks)
+  - Summer Session 2: 2026-06-26 to 2026-08-14 (7 weeks)
+  - Overlap: 2026-06-26 to 2026-07-03 (1 week overlap is intentional)
+
+**User Confirmation Prompt**:
+> "Summer Session 1 and Summer Session 2 overlap from [START] to [END]. This is common for summer sessions where students can take courses in both. Is this overlap intentional?"
+
+**Example Invalid (Likely Error)**:
+- Fall 2025 Term: 2025-08-18 to 2025-12-12
+  - Fall Session 1: 2025-08-18 to 2025-10-15
+  - Fall Session 2: 2025-08-20 to 2025-12-12
+  - Suspicious: Fall terms rarely have overlapping sessions — confirm with user
+
+---
+
+### Rule: Sessions Must Be Contained Within Parent Term
+
+**Requirement**: Every session's start and end dates must fall within its parent term's date range.
+
+**Check**:
+- `SESSION_START >= TERM_START`
+- `SESSION_END <= TERM_END`
+
+**Example Valid**:
+- Summer 2026 Term: 2026-05-26 to 2026-08-14
+- Summer Session 1: 2026-05-26 to 2026-07-03
+- Valid (session fully contained within term)
+
+**Example Invalid**:
+- Summer 2026 Term: 2026-05-26 to 2026-08-14
+- Summer Session 1: 2026-05-15 to 2026-07-03
+- Invalid (session starts before term)
+
+**Error Message**: "Session dates must fall within parent term date range"
+
+---
+
+## Duplicate Detection
+
+### Rule: No Duplicate Term Names for Same Academic Year
+
+**Requirement**: Within a single Academic Year, term names must be unique.
+
+**Check**: `AcademicTerm.Name` is not unique-constrained — a duplicate name will NOT error on insert. List-scan for existing terms with matching names via SOQL `/query` (routable via headless-360) before creating: `GET /services/data/<ver>/query` with `queryParams: {"q": "SELECT Id, Name, StartDate, EndDate FROM AcademicTerm WHERE Name = 'Fall 2025'"}` — pass the SOQL via `queryParams`, not inlined as `?q=` in the URL (inlining 404s); otherwise reuse Ids captured earlier in the same session. If the read fails, stop and ask the user before creating — do not risk a silent duplicate.
+
+**Example Valid**:
+- Academic Year 2025-2026
+  - Fall 2025
+  - Spring 2026
+  - Summer 2026
+- Valid (all unique names)
+
+**Example Invalid (Duplicate Name)**:
+- Academic Year 2025-2026
+  - Fall 2025 (existing, created on 2025-03-15)
+  - Fall 2025 (new, attempting to create on 2025-07-20)
+- Duplicate (same name, same year)
+
+**Resolution**:
+1. If dates match existing record: Skip creation, report "Fall 2025 already exists with same dates"
+2. If dates differ: Ask user whether to update existing or skip
+
+---
+
+### Rule: Duplicate with Different Dates Requires User Confirmation
+
+**Requirement**: If a term with the same name exists but has different dates, stop and ask user how to proceed.
+
+**Example Conflict**:
+- **Existing**: Fall 2025 (2025-08-25 to 2025-12-19)
+- **New**: Fall 2025 (2025-08-18 to 2025-12-12)
+
+**User Prompt**:
+> "A Fall 2025 term already exists with dates 2025-08-25 to 2025-12-19. Your new data has dates 2025-08-18 to 2025-12-12. Would you like to:
+> 1. Update the existing term with new dates
+> 2. Skip creating Fall 2025
+> 3. Cancel and review the existing term first"
+
+---
+
+## Date Format Validation
+
+### Rule: Date Strings Must Be in ISO 8601 Format
+
+**Requirement**: All dates parsed from user input or documents must be converted to YYYY-MM-DD format before inserting.
+
+**Valid Formats**:
+- `2025-08-18`
+- `08/18/2025` → Convert to `2025-08-18`
+- `August 18, 2025` → Convert to `2025-08-18`
+
+**Invalid Formats**:
+- `8/18/25` → Ambiguous (is it 2025 or 1925?)
+- `18-08-2025` → Day-first format (common in Europe, ambiguous)
+
+**Resolution**: If date format is ambiguous, ask user to clarify which format convention they're using.
+
+---
+
+## Validation Workflow
+
+### Step-by-Step Validation Process
+
+1. **Parse all dates from input** → Convert to YYYY-MM-DD format
+2. **Validate basic ranges** → Check end > start for all terms and sessions
+3. **Validate Academic Year coverage** → Check year spans all terms
+4. **Validate registration windows** → Check open date < term start
+5. **Validate add/drop deadlines** → Check start <= deadline < end
+6. **Check for overlapping sessions** → Flag for user confirmation (but allow)
+7. **Check for duplicate terms** → Query existing, ask user if conflict found
+8. **Validate session containment** → Check sessions within parent term bounds
+
+**If any validation fails**: Stop, report specific error with field values, and ask user to provide corrected dates.
+
+**If all validations pass**: Proceed to record creation.

package/skills/education-cloud-academic-calendar-generate/references/foundation_prerequisites.md

@@ -0,0 +1,40 @@
+# Foundation Prerequisites (Step 0)
+
+Run before Step 1 on every standalone invocation. Shared across the EDU skill family (also required by `education-cloud-multi-campus-configure`). Do not create any Academic Year/Term/Session record until every check below passes.
+
+All checks use the org REST transport resolved in Execution Transport — no `sf`/`sfdx`/`curl`.
+
+## 1. Org edition
+
+`GET /services/data/<ver>/query` with `queryParams: {"q": "SELECT OrganizationType FROM Organization"}`.
+
+Education Cloud requires Enterprise, Performance, Unlimited, or Developer edition. If the org is a different edition (e.g. Group, Professional), STOP — this is not fixable via API. Tell the user the org edition doesn't support Education Cloud.
+
+## 2. Lightning Experience enabled
+
+No dedicated read API for this. Infer it from other calls in this checklist succeeding normally. If a call unexpectedly errors in a way consistent with Classic-mode restrictions, tell the user to enable Lightning Experience manually (Setup → Lightning Experience → turn it on) and re-run this checklist.
+
+## 3. Education Cloud license provisioned
+
+`GET /services/data/<ver>/query` with `queryParams: {"q": "SELECT Id, Name FROM PermissionSet WHERE Name LIKE '%EducationCloud%'"}`.
+
+- One or more rows → license is provisioned, continue to check 4.
+- Zero rows → cross-check before concluding it's absent: `GET /services/data/<ver>/sobjects/BusinessProfile/describe`. If the describe succeeds and `createable:true`, the license is present despite the empty query (permission set naming varies by org) — continue to check 4.
+- Still zero rows AND describe fails/`createable:false` → genuinely absent. STOP — this is not fixable via API. Tell the user Education Cloud needs to be provisioned on this org (Setup → licenses).
+
+## 4. Running user has EDU access
+
+Resolve the running user's Id first — `GET /services/oauth2/userinfo` and read `user_id`/`sub`, or ask for their username if that endpoint isn't reachable through the resolved transport. Then:
+
+`GET /services/data/<ver>/query` with `queryParams: {"q": "SELECT Id FROM PermissionSetAssignment WHERE AssigneeId = '<resolved running user Id>' AND PermissionSet.Name LIKE '%EducationCloud%'"}`.
+
+- One or more rows → continue to check 5.
+- Zero rows → tell the user the running user needs an Education Cloud permission set assigned (Setup → Users → Permission Set Assignments), wait for confirmation, then re-run this query before proceeding.
+
+## 5. Education Cloud Foundation enabled
+
+`GET /headless/invoke/platform/education-cloud-settings` → read `educationCloudEnabled`.
+
+- `true` → all checks pass, proceed to Step 1.
+- `false` → this flips the org into Education Cloud mode and is **IRREVERSIBLE**. Warn the user explicitly and ask for confirmation before enabling. On confirmation: `PATCH /headless/invoke/platform/education-cloud-settings/enable-education-cloud`, then cold-verify with a fresh `GET /headless/invoke/platform/education-cloud-settings` (a `success:true` on the PATCH is not proof — re-read `educationCloudEnabled`). If the API path fails, fall back to the manual path: Setup → "Set Up Education Cloud" → toggle → Save, wait for the user to confirm, then re-verify with the same GET.
+- If the user declines to enable it, STOP — do not proceed to Step 1.

package/skills/education-cloud-academic-calendar-generate/scripts/validate_calendar_dates.py

@@ -0,0 +1,143 @@
+#!/usr/bin/env python3
+"""Deterministic date validation for Academic Year / Term / Session records.
+
+Reads calendar data as JSON on stdin, shape:
+{
+  "academicYear": {"startDate": "YYYY-MM-DD", "endDate": "YYYY-MM-DD"},
+  "terms": [
+    {"name": "Fall 2025", "startDate": "...", "endDate": "...", "registrationOpenDate": "..."}
+  ],
+  "sessions": [
+    {"name": "Summer Session 1", "termName": "Summer 2026",
+     "classStartDate": "...", "classEndDate": "...", "addDropDeadline": "..."}
+  ]
+}
+
+Writes JSON to stdout:
+{
+  "valid": bool,
+  "errors": [{"field": str, "message": str}],
+  "warnings": [{"field": str, "message": str}],
+  "computedRegistrationCloseDates": {"<termName>": "YYYY-MM-DD"}
+}
+
+Exit code 0 if no errors (warnings, e.g. intentional session overlaps, do not fail the run), 1 otherwise.
+"""
+
+import json
+import sys
+from datetime import date, timedelta
+
+
+def parse_date(value):
+    return date.fromisoformat(value)
+
+
+def safe_parse(value, field, errors):
+    """Parse an ISO date, routing missing/malformed values into `errors` instead of raising."""
+    if value is None:
+        errors.append({"field": field, "message": "Required date value is missing"})
+        return None
+    try:
+        return parse_date(value)
+    except (TypeError, ValueError):
+        errors.append({"field": field, "message": f"Invalid date value: {value!r}"})
+        return None
+
+
+def validate(data):
+    errors = []
+    warnings = []
+    computed_close_dates = {}
+
+    year = data.get("academicYear", {})
+    terms = data.get("terms", [])
+    sessions = data.get("sessions", [])
+
+    year_start = safe_parse(year.get("startDate"), "academicYear.startDate", errors)
+    year_end = safe_parse(year.get("endDate"), "academicYear.endDate", errors)
+
+    term_bounds = {}
+
+    for term in terms:
+        name = term.get("name", "<unnamed term>")
+        start = safe_parse(term.get("startDate"), f"terms[{name}].startDate", errors)
+        end = safe_parse(term.get("endDate"), f"terms[{name}].endDate", errors)
+        if start is None or end is None:
+            continue
+        term_bounds[name] = (start, end)
+
+        if end <= start:
+            errors.append({"field": f"terms[{name}].endDate", "message": "Term end date must be after start date"})
+
+        if year_start and start < year_start:
+            errors.append({"field": f"terms[{name}].startDate", "message": "Term starts before Academic Year start date"})
+        if year_end and end > year_end:
+            errors.append({"field": f"terms[{name}].endDate", "message": "Term ends after Academic Year end date"})
+
+        reg_open = term.get("registrationOpenDate")
+        if reg_open:
+            reg_open_date = safe_parse(reg_open, f"terms[{name}].registrationOpenDate", errors)
+            if reg_open_date is not None and reg_open_date >= start:
+                errors.append({"field": f"terms[{name}].registrationOpenDate", "message": "Registration window must open before term start date"})
+
+        computed_close_dates[name] = (start - timedelta(days=1)).isoformat()
+
+    sessions_by_term = {}
+    for session in sessions:
+        name = session.get("name", "<unnamed session>")
+        term_name = session.get("termName")
+        start = safe_parse(session.get("classStartDate"), f"sessions[{name}].classStartDate", errors)
+        end = safe_parse(session.get("classEndDate"), f"sessions[{name}].classEndDate", errors)
+        if start is None or end is None:
+            continue
+
+        if end <= start:
+            errors.append({"field": f"sessions[{name}].classEndDate", "message": "Session end date must be after start date"})
+
+        bounds = term_bounds.get(term_name)
+        if bounds is None:
+            errors.append({"field": f"sessions[{name}].termName", "message": f"No term named '{term_name}' found for this session"})
+        else:
+            term_start, term_end = bounds
+            if start < term_start or end > term_end:
+                errors.append({"field": f"sessions[{name}]", "message": "Session dates must fall within parent term date range"})
+
+        deadline = session.get("addDropDeadline")
+        if deadline:
+            deadline_date = safe_parse(deadline, f"sessions[{name}].addDropDeadline", errors)
+            if deadline_date is not None:
+                if deadline_date < start or deadline_date >= end:
+                    errors.append({"field": f"sessions[{name}].addDropDeadline", "message": "Add/drop deadline must be on or after session start and before session end"})
+
+        sessions_by_term.setdefault(term_name, []).append((name, start, end))
+
+    for term_name, entries in sessions_by_term.items():
+        for i in range(len(entries)):
+            for j in range(i + 1, len(entries)):
+                name_a, start_a, end_a = entries[i]
+                name_b, start_b, end_b = entries[j]
+                if start_a <= end_b and start_b <= end_a:
+                    warnings.append({
+                        "field": f"sessions[{name_a},{name_b}]",
+                        "message": f"'{name_a}' and '{name_b}' overlap within term '{term_name}' — confirm with user whether intentional",
+                    })
+
+    return {
+        "valid": len(errors) == 0,
+        "errors": errors,
+        "warnings": warnings,
+        "computedRegistrationCloseDates": computed_close_dates,
+    }
+
+
+def main():
+    data = json.load(sys.stdin)
+    result = validate(data)
+    json.dump(result, sys.stdout, indent=2)
+    sys.stdout.write("\n")
+    sys.exit(0 if result["valid"] else 1)
+
+
+if __name__ == "__main__":
+    main()