41e80b6c0c
All checks were successful
Trigger Cloudarix Deploy / call-webhook (push) Successful in 2s
✨ New Features - Advanced data table with TanStack Table v8 + Server Actions - Server-side pagination (10/25/50/100 rows per page) - Multi-column sorting with visual indicators - Column management (show/hide, resize) persisted to localStorage - URL state synchronization for shareable filtered views - Sticky header with compact/comfortable density modes 📦 Components Added - PolicyTableV2.tsx - Main table with TanStack integration - PolicyTableColumns.tsx - 7 column definitions with sorting - PolicyTablePagination.tsx - Pagination controls - PolicyTableToolbar.tsx - Density toggle + column visibility menu - ColumnVisibilityMenu.tsx - Show/hide columns dropdown 🔧 Hooks Added - usePolicyTable.ts - TanStack Table initialization - useURLState.ts - URL query param sync with nuqs - useTablePreferences.ts - localStorage persistence 🎨 Server Actions Updated - getPolicySettingsV2 - Pagination + sorting + filtering + Zod validation - exportPolicySettingsCSV - Server-side CSV generation (max 5000 rows) 📚 Documentation Added - Intune Migration Guide (1400+ lines) - Reverse engineering strategy - Intune Reference Version tracking - Tasks completed: 22/62 (Phase 1-3) ✅ Zero TypeScript compilation errors ✅ All MVP success criteria met (pagination, sorting, column management) ✅ Ready for Phase 4-7 (filtering, export, detail view, polish) Refs: specs/004-policy-explorer-v2/tasks.md
97 lines
8.1 KiB
Markdown
97 lines
8.1 KiB
Markdown
# Feature Specification: Technical Standard - Intune Reverse Engineering Strategy
|
|
|
|
**Feature Branch**: `006-intune-reverse-engineering-guide`
|
|
**Created**: 2025-12-09
|
|
**Status**: Draft
|
|
**Input**: User description: "Technical Standard - Intune Reverse Engineering Strategy"
|
|
|
|
## User Scenarios & Testing *(mandatory)*
|
|
|
|
### User Story 1 - Developer Implements New Intune Feature (Priority: P1)
|
|
|
|
A backend developer receives a request to add support for a new Intune resource type (e.g., "App Protection Policies"). They need a clear process to ensure the implementation matches Microsoft's actual Graph API behavior and includes all necessary parameters, filters, and data transformations.
|
|
|
|
**Why this priority**: This is the core workflow that enables all future Intune feature additions. Without this guideline, developers will make inconsistent API calls, miss critical parameters, and create technical debt.
|
|
|
|
**Independent Test**: Can be fully tested by having a developer follow the guide to implement one new resource type (e.g., Compliance Policies) and verify that the TypeScript implementation matches the PowerShell reference behavior exactly (same endpoints, same filters, same data shape).
|
|
|
|
**Acceptance Scenarios**:
|
|
|
|
1. **Given** a feature request for "Windows Update Rings", **When** developer follows the guide to analyze `IntuneManagement/Modules/WindowsUpdateRings.psm1`, **Then** they identify the exact Graph endpoint (`/deviceManagement/windowsUpdateForBusinessConfigurations`), required filters (`$filter=`), and property cleanup logic before writing any TypeScript code.
|
|
|
|
2. **Given** a new Settings Catalog policy type needs to be synced, **When** developer references the PowerShell code for Settings Catalog, **Then** they discover the `$expand=settings` parameter is required (not documented in Graph API docs) and implement it in TypeScript.
|
|
|
|
3. **Given** an AI agent is tasked with implementing a new sync job, **When** the agent reads this guide, **Then** it knows to search for the corresponding `.psm1` file first, extract API patterns, and document any undocumented behaviors before generating TypeScript code.
|
|
|
|
---
|
|
|
|
### User Story 2 - Developer Troubleshoots API Discrepancy (Priority: P2)
|
|
|
|
A developer notices that the TypeScript implementation returns different data than the PowerShell tool for the same Intune resource. They need a systematic way to identify what's missing in the TypeScript implementation.
|
|
|
|
**Why this priority**: This handles maintenance and bug fixes for existing features. It's less critical than the initial implementation process but essential for long-term reliability.
|
|
|
|
**Independent Test**: Can be tested by intentionally creating a "broken" implementation (missing an `$expand` parameter), then using the guide to trace back to the PowerShell reference and identify the fix.
|
|
|
|
**Acceptance Scenarios**:
|
|
|
|
1. **Given** TypeScript sync returns incomplete data for Configuration Policies, **When** developer compares against the PowerShell reference module, **Then** they discover a missing `$expand=assignments` parameter and add it to the TypeScript implementation.
|
|
|
|
2. **Given** a sync job fails with "400 Bad Request", **When** developer checks the PowerShell reference for that resource type, **Then** they find undocumented query parameter requirements (e.g., API version must be `beta` not `v1.0`).
|
|
|
|
---
|
|
|
|
### User Story 3 - Onboarding New Team Member (Priority: P3)
|
|
|
|
A new developer joins the project and needs to understand why the codebase uses specific Graph API patterns that seem to differ from official Microsoft documentation.
|
|
|
|
**Why this priority**: Good documentation reduces onboarding time and prevents future developers from "fixing" intentional design decisions that match the PowerShell reference.
|
|
|
|
**Independent Test**: A new developer can read the guide and understand the rationale for existing implementation choices without needing to ask the original author.
|
|
|
|
**Acceptance Scenarios**:
|
|
|
|
1. **Given** a new developer sees code that deletes certain properties before saving (e.g., `delete policy.createdDateTime`), **When** they read the migration guide, **Then** they understand this matches the PowerShell cleanup logic and shouldn't be "refactored away".
|
|
|
|
2. **Given** a developer wonders why some endpoints use beta API, **When** they consult the guide, **Then** they learn to check the PowerShell reference first before attempting to "upgrade" to v1.0.
|
|
|
|
---
|
|
|
|
### Edge Cases
|
|
|
|
- What happens when the PowerShell reference module is updated with breaking changes? (Guide should include a versioning strategy: document which PowerShell commit/version was used as reference)
|
|
- How does the system handle Intune features that exist in PowerShell but are deprecated by Microsoft? (Mark as "reference only, do not implement new features")
|
|
- What if a new Intune feature has no PowerShell equivalent yet? (Define a fallback process: use official Graph docs + extensive testing, document assumptions)
|
|
- How do we handle undocumented PowerShell behaviors that seem like bugs? (Document them explicitly with `[POWERSHELL QUIRK]` markers and decide case-by-case whether to replicate)
|
|
|
|
## Requirements *(mandatory)*
|
|
|
|
### Functional Requirements
|
|
|
|
- **FR-001**: Documentation MUST include a step-by-step process for analyzing PowerShell reference code before implementing TypeScript equivalents
|
|
- **FR-002**: Guide MUST specify the location of the PowerShell reference source (`IntuneManagement-master/` directory in the repo)
|
|
- **FR-003**: Process MUST define which data points to extract from PowerShell code: exact API endpoints, query parameters (`$filter`, `$expand`, `$select`), API version (beta vs v1.0), property cleanup/transformation logic
|
|
- **FR-004**: Guide MUST provide concrete examples mapping PowerShell patterns to TypeScript implementations (e.g., how PowerShell's `Invoke-MSGraphRequest` translates to `graphClient.api().get()`)
|
|
- **FR-005**: Documentation MUST include a troubleshooting section for when TypeScript behavior doesn't match PowerShell reference
|
|
- **FR-006**: Guide MUST define a fallback process for Intune features that have no PowerShell reference (use official docs + extensive testing)
|
|
- **FR-007**: Process MUST include versioning strategy: document which PowerShell commit/version is used as reference for each implemented feature
|
|
- **FR-008**: Guide MUST distinguish between "must replicate" behaviors (intentional API patterns) and "document but don't replicate" behaviors (PowerShell-specific quirks)
|
|
|
|
### Key Entities
|
|
|
|
- **PowerShell Reference Module**: A `.psm1` file in `IntuneManagement-master/Modules/` that implements sync logic for a specific Intune resource type (e.g., `ConfigurationPolicies.psm1`, `Applications.psm1`)
|
|
- **API Endpoint Pattern**: The exact Microsoft Graph URL path, API version, and query parameters required to fetch an Intune resource
|
|
- **Data Transformation Rule**: Logic that modifies API response data before storage (e.g., property deletion, type conversions, flattening nested structures)
|
|
- **Implementation Mapping**: The relationship between a PowerShell function (e.g., `Get-IntuneConfigurationPolicies`) and its TypeScript equivalent (e.g., `worker/jobs/syncConfigurationPolicies.ts`)
|
|
|
|
## Success Criteria *(mandatory)*
|
|
|
|
### Measurable Outcomes
|
|
|
|
- **SC-001**: A developer can implement a new Intune resource type sync job in under 2 hours by following the guide (compared to 8+ hours of trial-and-error without it)
|
|
- **SC-002**: 95% of newly implemented sync jobs match PowerShell reference behavior on first attempt (verified by comparing API calls and returned data)
|
|
- **SC-003**: Zero "undocumented Graph API behavior" surprises after implementation (all quirks are discovered during PowerShell analysis phase)
|
|
- **SC-004**: New team members can understand existing API implementation choices within 30 minutes of reading the guide (verified by onboarding feedback)
|
|
- **SC-005**: Code review time for new Intune features reduced by 50% (reviewers can verify against PowerShell reference instead of testing manually)
|
|
- **SC-006**: Technical debt reduced: zero instances of "why is this endpoint using beta API?" questions after guide adoption (rationale is documented in the guide or feature spec)
|