Private/Contract.ps1
|
# Versioned language-neutral v1 contract. Avoid requiring JSON Schema/NPM at runtime. function Assert-AppShellKeys { param($Object,[string[]]$Required,[string[]]$Allowed,[string]$Where) if ($Object -isnot [System.Collections.IDictionary]) { throw "$Where must be object" } foreach ($key in $Required) { if (-not $Object.Contains($key)) { throw "$Where missing $key" } } foreach ($key in $Object.Keys) { if ($Allowed -cnotcontains $key) { throw "$Where unknown field: $key" } } } function Assert-AppShellText { param($Value,[string]$Name,[int]$Length,[bool]$Nonempty=$false) if ($Value -isnot [string] -or $Value.Length -gt $Length -or ($Nonempty -and -not $Value.Trim())) { throw "$Name must be string (maximum $Length)" } } function Assert-AppShellSlug { param([string]$Value) if ($Value.Length -gt 64 -or $Value -cnotmatch '^[a-z][a-z0-9_-]*$') { throw "Invalid extension-local ID: $Value" } } function Assert-AppShellJsonSize { param($Value,[int]$Maximum,[string]$Kind) $json = $Value | ConvertTo-Json -Depth 50 -Compress if ([Text.Encoding]::UTF8.GetByteCount($json) -gt $Maximum) { throw "$Kind exceeds $Maximum bytes" } } function Assert-AppShellManifest { param($Manifest,[string]$ExpectedId,[string]$ExpectedVersion) $m = ConvertTo-AppShellTable $Manifest Assert-AppShellKeys $m @('api_version','id','title','version','pages') @('api_version','id','title','version','description','platforms','pages','commands') 'manifest' if (($m.api_version -isnot [int] -and $m.api_version -isnot [long]) -or $m.api_version -ne 1) { throw 'Unsupported manifest api_version' } Test-AppShellId ([string]$m.id) if ($m.id -cne $ExpectedId) { throw 'Manifest ID mismatches module metadata' } if ($m.version -cne $ExpectedVersion) { throw 'Manifest version mismatches module manifest' } Assert-AppShellText $m.title 'title' 120 $true Assert-AppShellText $m.version 'version' 100 $true if ($m.ContainsKey('description')) { Assert-AppShellText $m.description 'description' 2000 } if ($m.ContainsKey('platforms')) { if (@($m.platforms).Count -lt 1 -or @($m.platforms).Count -gt 2) { throw 'Invalid platforms count' } $target = if ($env:OS -eq 'Windows_NT') { 'windows' } else { 'linux' } if (@($m.platforms) -cnotcontains $target) { throw "Unsupported platform: $target" } } if (@($m.pages).Count -lt 1 -or @($m.pages).Count -gt 100) { throw 'pages length must be 1..100' } $ids = @{} foreach ($p in $m.pages) { Assert-AppShellKeys $p @('id','title') @('id','title','description','order') 'page' Assert-AppShellSlug $p.id if ($ids.ContainsKey($p.id)) { throw 'Duplicate page ID' } $ids[$p.id] = $true Assert-AppShellText $p.title 'page.title' 120 $true if ($p.ContainsKey('description')) { Assert-AppShellText $p.description 'page.description' 500 } if ($p.ContainsKey('order') -and (($p.order -isnot [int] -and $p.order -isnot [long]) -or $p.order -lt 0 -or $p.order -gt 9999)) { throw 'Invalid page.order' } } if (-not $m.ContainsKey('commands')) { $m.commands = @() } if (@($m.commands).Count -gt 100) { throw 'Too many commands' } $ids = @{} foreach ($c in @($m.commands)) { Assert-AppShellKeys $c @('id','title','risk') @('id','title','risk','confirmation') 'command' Assert-AppShellSlug $c.id if ($ids.ContainsKey($c.id)) { throw 'Duplicate command ID' } $ids[$c.id] = $true Assert-AppShellText $c.title 'command.title' 120 $true if (@('read','write','destructive') -cnotcontains $c.risk) { throw 'Invalid command risk' } if ($c.risk -ne 'read' -and -not $c.confirmation) { throw 'Write/destructive command requires confirmation' } if ($c.ContainsKey('confirmation')) { Assert-AppShellText $c.confirmation 'confirmation' 500 $true } } Assert-AppShellJsonSize $m 131072 'manifest' return ,$m } function Assert-AppShellView { param($View,$Manifest) $v = ConvertTo-AppShellTable $View Assert-AppShellKeys $v @('title','blocks') @('title','blocks') 'view' Assert-AppShellText $v.title 'view.title' 120 $true if (@($v.blocks).Count -gt 300) { throw 'Too many blocks' } $declared = @{} foreach ($c in @($Manifest.commands)) { $declared[$c.id] = $true } $fields = @{} $count = [ref]0 foreach ($block in @($v.blocks)) { Assert-AppShellBlock $block $declared $fields $count 0 } Assert-AppShellJsonSize $v 1048576 'view' return ,$v } function Assert-AppShellBlock { param($Block,$Commands,$Fields,[ref]$Count,[int]$Depth) if ($Depth -gt 10) { throw 'View nesting too deep' } if ($Block -isnot [System.Collections.IDictionary]) { throw 'Block must be object' } $Count.Value++ if ($Count.Value -gt 300) { throw 'View node count exceeded' } $kind = $Block.kind switch ($kind) { { $_ -in @('text','caption','code','badge','heading','notice') } { $allowed = @('kind','text') if ($kind -eq 'heading') { $allowed += 'level' } if ($kind -eq 'notice') { $allowed += 'tone' } Assert-AppShellKeys $Block @('kind','text') $allowed 'text block' $limit = if ($kind -eq 'heading') { 300 } elseif ($kind -eq 'notice') { 5000 } else { 10000 } Assert-AppShellText $Block.text 'block.text' $limit if ($kind -eq 'heading' -and $Block.ContainsKey('level') -and (($Block.level -isnot [int] -and $Block.level -isnot [long]) -or $Block.level -lt 1 -or $Block.level -gt 4)) { throw 'Invalid heading level' } if ($kind -eq 'notice' -and $Block.ContainsKey('tone') -and @('info','success','warning','danger') -cnotcontains $Block.tone) { throw 'Invalid notice tone' } break } divider { Assert-AppShellKeys $Block @('kind') @('kind') 'divider'; break } { $_ -in @('row','column','card') } { Assert-AppShellKeys $Block @('kind','children') @('kind','children') 'container' if (@($Block.children).Count -gt 300) { throw 'Too many children' } foreach ($child in @($Block.children)) { Assert-AppShellBlock $child $Commands $Fields $Count ($Depth+1) } break } { $_ -in @('input','textarea','checkbox','select') } { $keys = switch ($kind) { input { @('kind','name','label','value','placeholder','password') } textarea { @('kind','name','label','value') } checkbox { @('kind','name','label','checked') } select { @('kind','name','label','value','options') } } $required = @('kind','name','label') if ($kind -eq 'select') { $required += 'options' } Assert-AppShellKeys $Block $required $keys 'form field' Assert-AppShellSlug $Block.name if ($Fields.ContainsKey($Block.name)) { throw 'Duplicate form field name' } $Fields[$Block.name] = $true if ($Fields.Count -gt 80) { throw 'Too many fields' } Assert-AppShellText $Block.label 'field.label' 200 if ($kind -ne 'checkbox' -and $Block.ContainsKey('value')) { Assert-AppShellText $Block.value 'field.value' 10000 } if ($kind -eq 'checkbox' -and $Block.ContainsKey('checked') -and $Block.checked -isnot [bool]) { throw 'checked must be boolean' } if ($kind -eq 'input') { if ($Block.ContainsKey('placeholder')) { Assert-AppShellText $Block.placeholder 'placeholder' 200 } if ($Block.ContainsKey('password') -and $Block.password -isnot [bool]) { throw 'password must be boolean' } } if ($kind -eq 'select') { if (@($Block.options).Count -gt 100) { throw 'Too many options' } $values = @{} foreach ($opt in @($Block.options)) { Assert-AppShellKeys $opt @('value','label') @('value','label') 'select option' Assert-AppShellText $opt.value 'option.value' 200 Assert-AppShellText $opt.label 'option.label' 200 if ($values.ContainsKey($opt.value)) { throw 'Duplicate select option' } $values[$opt.value] = $true } if ($Block.value -and -not $values.ContainsKey($Block.value)) { throw 'Selected option does not exist' } } break } button { Assert-AppShellKeys $Block @('kind','text','command') @('kind','text','command','params') 'button' Assert-AppShellSlug $Block.command Assert-AppShellText $Block.text 'button.text' 200 if (-not $Commands.ContainsKey($Block.command)) { throw 'Button references undeclared command' } if ($Block.ContainsKey('params') -and $Block.params -isnot [System.Collections.IDictionary]) { throw 'Button params must be object' } break } table { Assert-AppShellKeys $Block @('kind','columns','rows') @('kind','columns','rows') 'table' if (@($Block.columns).Count -gt 24 -or @($Block.rows).Count -gt 200) { throw 'Table exceeds bounds' } $keys = @{} foreach ($col in @($Block.columns)) { Assert-AppShellKeys $col @('key','title') @('key','title') 'column' Assert-AppShellSlug $col.key Assert-AppShellText $col.title 'column.title' 120 if ($keys.ContainsKey($col.key)) { throw 'Duplicate column' } $keys[$col.key]=$true } foreach ($row in @($Block.rows)) { if ($row -isnot [System.Collections.IDictionary]) { throw 'Table row must be object' } foreach ($cell in $row.Values) { if ($null -ne $cell -and $cell -isnot [string] -and $cell -isnot [ValueType]) { throw 'Table cells must be scalar' } } } break } default { throw "Unsupported view block: $kind" } } } function Assert-AppShellResult { param($Value) $r = ConvertTo-AppShellTable $Value Assert-AppShellKeys $r @() @('message','refresh') 'action result' if ($r.ContainsKey('message')) { Assert-AppShellText $r.message 'message' 500 } if ($r.ContainsKey('refresh') -and $r.refresh -isnot [bool]) { throw 'refresh must be boolean' } return ,$r } |