@fluentcommerce/ai-skills 0.1.0 → 0.3.0

package/content/dev/skills/fluent-mystique-builder/components/fc.workflow.provider.md

@@ -0,0 +1,77 @@
+---
+alias: "fc.workflow.provider"
+aliases:
+  - fc.workflow.provider
+category: layout
+module: Core
+---
+
+# fc.workflow.provider
+
+Data provider that fetches all workflows across all retailers and passes them as data context to its first descendant.
+
+## When to Use
+- Build a workflow management or listing page that needs access to all workflows in the account
+- Provide workflow data context to downstream components like `fc.list` or `fc.card.attribute`
+- Create a workflow explorer or configuration page
+
+## Key Props
+
+This component has no props. It fetches workflow data automatically on mount.
+
+## Data Binding
+Fetches workflows via the Fluent REST API (`/api/v4.1/workflow`) for each retailer the user has access to. The workflow data includes:
+- `name` -- workflow name
+- `version` -- workflow version string
+- `entityType` -- target entity type (e.g. ORDER, FULFILMENT)
+- `entitySubtype` -- entity subtype (e.g. HD, CC)
+- `description` -- workflow description
+- `createdBy` -- creator username
+- `createdOn` -- creation timestamp
+- `retailer` -- retailer ID
+- `versionComment` -- optional version comment
+
+The fetched workflows are passed to the first descendant via `dataOverride`.
+
+## Descendants
+Yes -- renders its first descendant (`index={0}`) with the workflow data injected as `dataOverride`. Shows a loading spinner while data is being fetched. Displays an error message if the fetch fails.
+
+## Composition Patterns
+- `fc.page` > `fc.workflow.provider` > `fc.list` for a workflow listing page
+- `fc.page` > `fc.workflow.provider` > `fc.tabs.card` > workflow category tabs
+
+## Gotchas
+- Only the first descendant (`index={0}`) receives the data -- additional descendants are ignored.
+- Fetches workflows for ALL retailers the user has access to, not just the active retailer. This can be slow on accounts with many retailers.
+- Uses `@tanstack/react-query` for caching -- subsequent renders may use cached data.
+- The REST API call uses `latest=true&count=100` -- only the latest version of each workflow is returned, up to 100 per retailer.
+- Shows a loading spinner during fetch and an error message on failure -- no descendant is rendered until data is available.
+- Registered with category `content` in the component registry.
+
+## Manifest Example
+```json
+{
+  "component": "fc.workflow.provider",
+  "descendants": [
+    {
+      "component": "fc.list",
+      "props": {
+        "attributes": [
+          { "label": "Name", "value": "{{name}}" },
+          { "label": "Entity Type", "value": "{{entityType}}" },
+          { "label": "Subtype", "value": "{{entitySubtype}}" },
+          { "label": "Version", "value": "{{version}}" },
+          { "label": "Retailer", "value": "{{retailer}}" }
+        ],
+        "defaultPageSize": 25
+      }
+    }
+  ]
+}
+```
+
+## AI Parse Notes
+- **Primary intent:** Declarative Mystique component definition for manifests.
+- **Selection signals:** Match by `alias`, category, and required `Key Props`.
+- **Assembly hints:** Combine with compatible parent/child components listed in `Composition Patterns`.
+- **Safety checks:** Validate required props and data bindings before manifest generation.

package/content/dev/skills/fluent-mystique-builder/validate-docs.ps1

@@ -0,0 +1,260 @@
+[CmdletBinding()]
+param(
+    [switch]$Json
+)
+
+Set-StrictMode -Version Latest
+$ErrorActionPreference = "Stop"
+
+function Clean-Alias {
+    param(
+        [Parameter(Mandatory = $false)]
+        [string]$Value
+    )
+
+    if ([string]::IsNullOrWhiteSpace($Value)) {
+        return ""
+    }
+
+    $alias = ($Value -replace [char]7, "").Trim()
+    $match = [regex]::Match($alias, 'fc\.[A-Za-z0-9_.-]+')
+    if ($match.Success) {
+        return $match.Value
+    }
+    return ""
+}
+
+function Get-UniqueAliases {
+    param(
+        [string[]]$Items
+    )
+
+    if ($null -eq $Items -or $Items.Count -eq 0) {
+        return @()
+    }
+
+    $set = New-Object 'System.Collections.Generic.HashSet[string]'
+    foreach ($item in $Items) {
+        if (-not [string]::IsNullOrWhiteSpace($item)) {
+            [void]$set.Add($item)
+        }
+    }
+    $output = New-Object string[] $set.Count
+    $set.CopyTo($output)
+    return $output
+}
+
+function Get-DocsAliases {
+    param(
+        [Parameter(Mandatory = $true)]
+        [string]$ComponentsDir
+    )
+
+    $docs = Get-ChildItem -Path $ComponentsDir -File -Filter "*.md" | Where-Object { $_.Name -ne "INDEX.md" }
+    $bell = [char]7
+
+    $aliases = @()
+    $docsWithAiParseNotes = 0
+    $docsWithBellChar = 0
+    $docsWithAliasFrontmatter = 0
+
+    foreach ($doc in $docs) {
+        $content = Get-Content -Path $doc.FullName -Raw
+
+        if ($content -match '(?m)^##\s+AI Parse Notes\b') {
+            $docsWithAiParseNotes++
+        }
+
+        if ($content.Contains($bell)) {
+            $docsWithBellChar++
+        }
+
+        $frontmatter = [regex]::Match($content, '(?ms)^---\r?\n(.*?)\r?\n---')
+        if ($frontmatter.Success) {
+            $aliasMatch = [regex]::Match($frontmatter.Groups[1].Value, '(?m)^\s*alias\s*:\s*(.+?)\s*$')
+            if ($aliasMatch.Success) {
+                $docsWithAliasFrontmatter++
+                $alias = Clean-Alias -Value $aliasMatch.Groups[1].Value
+                if ($alias -like "fc.*") {
+                    $aliases += $alias
+                }
+            }
+        }
+    }
+
+    return [pscustomobject]@{
+        Docs                      = $docs
+        Aliases                   = @(Get-UniqueAliases -Items $aliases)
+        DocsWithAiParseNotes      = $docsWithAiParseNotes
+        DocsWithBellChar          = $docsWithBellChar
+        DocsWithAliasFrontmatter  = $docsWithAliasFrontmatter
+    }
+}
+
+function Get-RegistryAliases {
+    param(
+        [Parameter(Mandatory = $true)]
+        [string]$RegistryFile
+    )
+
+    $content = Get-Content -Path $RegistryFile -Raw
+    $sectionStart = [regex]::Match($content, '(?m)^##\s+Component Alias Registry\s*$')
+    if (-not $sectionStart.Success) {
+        return @()
+    }
+
+    $rest = $content.Substring($sectionStart.Index + $sectionStart.Length)
+    $nextSection = [regex]::Match($rest, '(?m)^##\s+')
+    if ($nextSection.Success) {
+        $rest = $rest.Substring(0, $nextSection.Index)
+    }
+
+    $aliases = @()
+    $lines = $rest -split "\r?\n"
+    foreach ($line in $lines) {
+        if (-not $line.Trim().StartsWith("|")) { continue }
+        if ($line -notmatch "fc\.") { continue }
+
+        $cells = $line -split "\|"
+        if ($cells.Length -lt 2) { continue }
+        $firstCell = $cells[1].Trim()
+        $aliasMatch = [regex]::Match($firstCell, 'fc\.[A-Za-z0-9_.-]+')
+        if ($aliasMatch.Success) {
+            $aliases += $aliasMatch.Value
+        }
+    }
+
+    if ($aliases.Count -eq 0) {
+        return @()
+    }
+    return @(Get-UniqueAliases -Items $aliases)
+}
+
+function Get-IndexAliases {
+    param(
+        [Parameter(Mandatory = $true)]
+        [string]$IndexFile
+    )
+
+    if (-not (Test-Path -Path $IndexFile)) {
+        return @()
+    }
+
+    $lines = Get-Content -Path $IndexFile
+    $aliases = @()
+    foreach ($line in $lines) {
+        if (-not $line.Trim().StartsWith("|")) { continue }
+        if ($line -notmatch "fc\.") { continue }
+        $cells = $line -split "\|"
+        if ($cells.Length -lt 2) { continue }
+        $aliasMatch = [regex]::Match($cells[1], 'fc\.[A-Za-z0-9_.-]+')
+        if ($aliasMatch.Success) {
+            $aliases += $aliasMatch.Value
+        }
+    }
+
+    if ($aliases.Count -eq 0) {
+        return @()
+    }
+    return @(Get-UniqueAliases -Items $aliases)
+}
+
+$scriptDir = Split-Path -Path $MyInvocation.MyCommand.Path -Parent
+$componentsDir = Join-Path -Path $scriptDir -ChildPath "components"
+$indexFile = Join-Path -Path $componentsDir -ChildPath "INDEX.md"
+$registryFile = [System.IO.Path]::GetFullPath((Join-Path -Path $scriptDir -ChildPath "..\fluent-mystique-validate\SKILL.md"))
+
+if (-not (Test-Path -Path $componentsDir)) {
+    throw "Components directory not found: $componentsDir"
+}
+if (-not (Test-Path -Path $registryFile)) {
+    throw "Registry file not found: $registryFile"
+}
+if (-not (Test-Path -Path $indexFile)) {
+    throw "Index file not found: $indexFile"
+}
+
+$docsData = Get-DocsAliases -ComponentsDir $componentsDir
+$registryAliases = @(Get-RegistryAliases -RegistryFile $registryFile)
+$indexAliases = @(Get-IndexAliases -IndexFile $indexFile)
+
+$registryOnly = @($registryAliases | Where-Object { $_ -notin $docsData.Aliases } | Sort-Object)
+$docsOnly = @($docsData.Aliases | Where-Object { $_ -notin $registryAliases } | Sort-Object)
+$indexOnly = @($indexAliases | Where-Object { $_ -notin $docsData.Aliases } | Sort-Object)
+$docsMissingInIndex = @($docsData.Aliases | Where-Object { $_ -notin $indexAliases } | Sort-Object)
+
+$summary = [pscustomobject]@{
+    componentDocs              = $docsData.Docs.Count
+    docsWithAiParseNotes       = $docsData.DocsWithAiParseNotes
+    docsWithBellChar           = $docsData.DocsWithBellChar
+    docsWithAliasFrontmatter   = $docsData.DocsWithAliasFrontmatter
+    indexRows                  = $indexAliases.Count
+    registryAliases            = $registryAliases.Count
+    documentedAliases          = $docsData.Aliases.Count
+    missingInDocsCount         = $registryOnly.Count
+    extraInDocsCount           = $docsOnly.Count
+    indexOnlyCount             = $indexOnly.Count
+    docsMissingInIndexCount    = $docsMissingInIndex.Count
+}
+
+$report = [pscustomobject]@{
+    summary            = $summary
+    missingInDocs      = $registryOnly
+    extraInDocs        = $docsOnly
+    indexOnly          = $indexOnly
+    docsMissingInIndex = $docsMissingInIndex
+}
+
+if ($Json) {
+    $report | ConvertTo-Json -Depth 5
+} else {
+    Write-Host "Mystique Docs Validation"
+    Write-Host "========================"
+    Write-Host ("componentDocs            : {0}" -f $summary.componentDocs)
+    Write-Host ("docsWithAiParseNotes     : {0}" -f $summary.docsWithAiParseNotes)
+    Write-Host ("docsWithBellChar         : {0}" -f $summary.docsWithBellChar)
+    Write-Host ("docsWithAliasFrontmatter : {0}" -f $summary.docsWithAliasFrontmatter)
+    Write-Host ("indexRows                : {0}" -f $summary.indexRows)
+    Write-Host ("registryAliases          : {0}" -f $summary.registryAliases)
+    Write-Host ("documentedAliases        : {0}" -f $summary.documentedAliases)
+    Write-Host ("missingInDocsCount       : {0}" -f $summary.missingInDocsCount)
+    Write-Host ("extraInDocsCount         : {0}" -f $summary.extraInDocsCount)
+    Write-Host ("indexOnlyCount           : {0}" -f $summary.indexOnlyCount)
+    Write-Host ("docsMissingInIndexCount  : {0}" -f $summary.docsMissingInIndexCount)
+
+    if ($registryOnly.Count -gt 0) {
+        Write-Host ""
+        Write-Host "Missing in docs:"
+        $registryOnly | ForEach-Object { Write-Host (" - {0}" -f $_) }
+    }
+    if ($docsOnly.Count -gt 0) {
+        Write-Host ""
+        Write-Host "Extra in docs (not in registry):"
+        $docsOnly | ForEach-Object { Write-Host (" - {0}" -f $_) }
+    }
+    if ($indexOnly.Count -gt 0) {
+        Write-Host ""
+        Write-Host "Index-only aliases:"
+        $indexOnly | ForEach-Object { Write-Host (" - {0}" -f $_) }
+    }
+    if ($docsMissingInIndex.Count -gt 0) {
+        Write-Host ""
+        Write-Host "Docs missing from index:"
+        $docsMissingInIndex | ForEach-Object { Write-Host (" - {0}" -f $_) }
+    }
+}
+
+$failed = $false
+if ($summary.componentDocs -ne $summary.docsWithAiParseNotes) { $failed = $true }
+if ($summary.docsWithBellChar -gt 0) { $failed = $true }
+if ($summary.componentDocs -ne $summary.docsWithAliasFrontmatter) { $failed = $true }
+if ($summary.missingInDocsCount -gt 0) { $failed = $true }
+if ($summary.extraInDocsCount -gt 0) { $failed = $true }
+if ($summary.indexOnlyCount -gt 0) { $failed = $true }
+if ($summary.docsMissingInIndexCount -gt 0) { $failed = $true }
+
+if ($failed) {
+    exit 1
+}
+
+exit 0