frontier-os-app-builder 1.0.0 → 1.2.0

package/references/verification-rules.md

@@ -4,6 +4,19 @@ Defines what the fos-verifier agent must check after generating or modifying a F
 
 ---
 
+## Verification Tiers
+
+Rules are split into two tiers based on when they apply:
+
+| Tier | Rules | When to Run |
+|------|-------|-------------|
+| **Tier 1 (Design)** | S-01–S-03, T-01–T-05, B-01–B-03, C-02–C-04, M-01–M-03 | After every phase |
+| **Tier 2 (SDK)** | I-01–I-04, C-01, C-05, P-01–P-03 | After SDK Integration phase only |
+
+To determine the current tier: read `sdkPhase` from `.frontier-app/manifest.json`. If the current phase matches `sdkPhase`, run both Tier 1 and Tier 2. Otherwise, run Tier 1 only. If `sdkPhase` is absent from the manifest, run all checks (backward compatibility).
+
+---
+
 ## Structure Checks
 
 These verify the generated file tree matches the standard Frontier OS app layout.
@@ -20,7 +33,7 @@ tsconfig.json
 vercel.json
 vite.config.ts
 src/main.tsx
-src/lib/sdk-context.tsx
+src/lib/frontier-services.tsx
 src/views/Layout.tsx
 src/styles/index.css
 ```
@@ -35,7 +48,7 @@ The `src/` directory must contain at minimum:
 src/
   main.tsx
   lib/
-    sdk-context.tsx
+    frontier-services.tsx
   views/
     Layout.tsx
   styles/
@@ -57,6 +70,8 @@ src/
     components/
 ```
 
+> **Note:** `src/lib/sdk-context.tsx` and `src/lib/sdk-services.tsx` exist only **after** the SDK Integration phase (Tier 2). They are not present during pre-integration phases, so S-02 (a Tier-1 check that runs after every phase) must not require them.
+
 **Pass condition:** All required paths exist. Optional paths should be present when the corresponding feature is used (e.g., `router.tsx` when `react-router-dom` is a dependency).
 
 ### S-03: No extraneous top-level files
@@ -82,6 +97,8 @@ README.md
 
 ## SDK Integration Checks
 
+> **Tier 2 — SDK Integration phase only.** Skip these checks for all other phases.
+
 These verify the app correctly integrates with the Frontier SDK.
 
 ### I-01: isInFrontierApp() call in Layout.tsx
@@ -115,24 +132,26 @@ if (standaloneHtml) {
 }
 ```
 
-### I-03: SdkProvider wrapping children in Layout.tsx
+### I-03: SdkProvider + FrontierServicesProvider wrapping children in Layout.tsx
 
-When inside the Frontier app, the Layout must wrap its children (either `<Outlet />` or a single component) with `<SdkProvider>`.
+When inside the Frontier app, the Layout must wrap its children with `<SdkProvider>` AND bridge the SDK into `<FrontierServicesProvider>`. Feature code consumes `useServices()`, so without `FrontierServicesProvider` the app **crashes at runtime** ("useServices must be used within FrontierServicesProvider").
 
-**Pass condition:** The return statement for the "in Frontier" case contains:
+**Pass condition:** Layout's "in Frontier" return path contains both providers:
 ```tsx
 <SdkProvider>
-  <Outlet />  {/* or a single component */}
+  <SdkServicesBridge>   {/* useSdk() → createSdkServices(sdk) → FrontierServicesProvider */}
+    <Outlet />
+  </SdkServicesBridge>
 </SdkProvider>
 ```
 
 ### I-04: useSdk() hook available and used
 
-`src/lib/sdk-context.tsx` must export `useSdk` and `SdkProvider`. Any view component that accesses the SDK must call `useSdk()`.
+`src/lib/sdk-context.tsx` must export `useSdk` and `SdkProvider`. Only `sdk-services.tsx` and `src/views/Layout.tsx` may consume them; feature code under `src/hooks/`, `src/views/`, and `src/components/` accesses the SDK indirectly through `useServices()` (see M-03), never `useSdk()` directly.
 
 **Pass condition:**
 - `sdk-context.tsx` exports `useSdk` and `SdkProvider`.
-- Every file that accesses SDK methods imports `useSdk` from `../lib/sdk-context` (or appropriate relative path) and calls it within the component body.
+- `useSdk()` / `SdkProvider` are consumed only by `sdk-services.tsx` and `Layout.tsx`; feature code uses `useServices()` from `../lib/frontier-services` (see M-03), not `useSdk`.
 - No direct `new FrontierSDK()` calls outside of `sdk-context.tsx`.
 
 ---
@@ -141,27 +160,23 @@ When inside the Frontier app, the Layout must wrap its children (either `<Outlet
 
 These verify configuration files have the correct content.
 
-### C-01: vercel.json has all 5 CORS origin blocks
+### C-01: vercel.json has CORS + CSP frame-ancestors for the 3 origins
 
-The `vercel.json` file must contain exactly 5 header blocks, one for each allowed origin:
+> **Tier 2 — SDK Integration phase only.**
 
-1. `https://os.frontiertower.io`
-2. `https://alpha.os.frontiertower.io`
-3. `https://beta.os.frontiertower.io`
-4. `https://sandbox.os.frontiertower.io`
-5. `http://localhost:5173`
-
-Each block must include:
-- `Access-Control-Allow-Origin` matching the origin
+The `vercel.json` file uses a single unconditional header block containing:
+- `Access-Control-Allow-Origin: https://os.frontiertower.io` (the production origin)
 - `Access-Control-Allow-Methods: GET, OPTIONS`
 - `Access-Control-Allow-Headers: Content-Type`
+- `Content-Security-Policy` with `frame-ancestors` listing all 3 live origins (`https://os.frontiertower.io`, `https://sandbox.os.frontiertower.io`, `http://localhost:5173`) — this governs iframe embedding
+- security headers: `X-Content-Type-Options`, `Referrer-Policy`, `Permissions-Policy`
 
 It must also include the SPA rewrite:
 ```json
 { "source": "/(.*)", "destination": "/index.html" }
 ```
 
-**Pass condition:** All 5 origin blocks are present with correct headers. The rewrite rule exists.
+**Pass condition:** All 3 origins appear in the `frame-ancestors` directive, the CORS and security headers are present, and the rewrite rule exists.
 
 ### C-02: tsconfig.json has strict mode and vitest types
 
@@ -203,12 +218,12 @@ The `test` script may be omitted if the app has no tests and vitest is not in de
 
 **Pass condition:** All listed scripts are present with exact command values. If vitest is in devDependencies, the `test` script must be present.
 
-### C-05: package.json has required dependencies
+### C-05a: package.json has required dependencies (Tier 1)
 
 The following must be in `dependencies`:
-- `@frontiertower/frontier-sdk`
 - `react`
 - `react-dom`
+- `react-router-dom` (when the app uses routing)
 
 The following must be in `devDependencies`:
 - `@tailwindcss/postcss`
@@ -219,23 +234,32 @@ The following must be in `devDependencies`:
 - `tailwindcss`
 - `typescript`
 - `vite`
+- `vitest`
 
-When the app uses routing, `react-router-dom` must be in `dependencies`.
-
-When the app has tests, the following must be in `devDependencies`:
+When the app has tests, the following must also be in `devDependencies`:
 - `@testing-library/jest-dom`
 - `@testing-library/react`
 - `@testing-library/user-event`
 - `@vitest/coverage-v8`
 - `jsdom`
-- `vitest`
 
 **Pass condition:** All listed packages are present in the correct section.
 
+### C-05b: package.json has SDK dependency (Tier 2)
+
+> **Tier 2 — SDK Integration phase only.**
+
+The following must be in `dependencies`:
+- `@frontiertower/frontier-sdk`
+
+**Pass condition:** `@frontiertower/frontier-sdk` is present in `dependencies`.
+
 ---
 
 ## Permission Checks
 
+> **Tier 2 — SDK Integration phase only.** Permission checks only apply after the SDK is wired in.
+
 These verify that declared permissions match actual SDK usage.
 
 ### P-01: Manifest permissions match SDK method calls
@@ -263,6 +287,7 @@ Method-to-permission mapping follows the pattern:
 - `sdk.getOffices().<method>()` --> `offices:<method>`
 - `sdk.getThirdParty().<method>()` --> `thirdParty:<method>`
 - `sdk.getChain().<method>()` --> `chain:<method>`
+- `sdk.getNavigation().<method>()` --> `navigation:<method>`
 
 **Pass condition:** No SDK method is called without the corresponding permission being declared.
 
@@ -375,30 +400,66 @@ The `@layer base` block must include:
 
 ---
 
+## Mock Layer Checks
+
+> **Tier 1 — Run after every phase** (except Phase 1 scaffold-only verification).
+
+### M-01: frontier-services.tsx exports useServices
+
+`src/lib/frontier-services.tsx` must exist and export a `useServices` function.
+
+**Pass condition:** `grep -q "export.*useServices" src/lib/frontier-services.tsx`
+
+**Severity:** Error
+
+### M-02: createMockServices exported
+
+`src/lib/frontier-services.tsx` must export `createMockServices`.
+
+**Pass condition:** `grep -q "export.*createMockServices" src/lib/frontier-services.tsx`
+
+**Severity:** Error
+
+### M-03: No direct SDK imports in feature code
+
+Source files under `src/hooks/`, `src/views/`, and `src/components/` must NOT import from `@frontiertower/frontier-sdk` or `../lib/sdk-context`. Feature code should use `useServices()` from `../lib/frontier-services`.
+
+**Pass condition:** No matches for `from.*@frontiertower/frontier-sdk` or `from.*sdk-context` in `src/hooks/`, `src/views/`, `src/components/` (excluding `src/lib/`).
+
+**Severity:** Error — indicates feature code bypassing the services abstraction
+
+**Note:** This check does NOT apply during the SDK Integration phase, where `sdk-context.tsx` and `sdk-services.tsx` legitimately import from the SDK.
+
+---
+
 ## Summary Checklist
 
-| ID   | Category      | Rule                                                | Severity |
-| ---- | ------------- | --------------------------------------------------- | -------- |
-| S-01 | Structure     | Required files exist                                | Error    |
-| S-02 | Structure     | Directory structure matches pattern                 | Error    |
-| S-03 | Structure     | No extraneous top-level files                       | Warning  |
-| I-01 | SDK           | isInFrontierApp() call in Layout.tsx                | Error    |
-| I-02 | SDK           | createStandaloneHTML() fallback in Layout.tsx        | Error    |
-| I-03 | SDK           | SdkProvider wrapping children in Layout.tsx          | Error    |
-| I-04 | SDK           | useSdk() hook available and used                    | Error    |
-| C-01 | Configuration | vercel.json has all 5 CORS origin blocks            | Error    |
-| C-02 | Configuration | tsconfig.json has strict mode and vitest types      | Error    |
-| C-03 | Configuration | postcss.config.js imports @tailwindcss/postcss      | Error    |
-| C-04 | Configuration | package.json has correct scripts                    | Error    |
-| C-05 | Configuration | package.json has required dependencies              | Error    |
-| P-01 | Permissions   | Manifest permissions match SDK method calls         | Error    |
-| P-02 | Permissions   | No SDK methods called without permission            | Error    |
-| P-03 | Permissions   | No unnecessary permissions declared                 | Warning  |
-| B-01 | Build         | tsc --noEmit passes                                 | Error    |
-| B-02 | Build         | vite build succeeds                                 | Error    |
-| B-03 | Build         | vitest run passes (if tests exist)                  | Error    |
-| T-01 | Theme         | Dark theme CSS variables defined in index.css       | Error    |
-| T-02 | Theme         | body class="dark" in index.html                     | Error    |
-| T-03 | Theme         | Plus Jakarta Sans font loaded                       | Error    |
-| T-04 | Theme         | @import "tailwindcss" in index.css                  | Error    |
-| T-05 | Theme         | Base layer styles present                           | Error    |
+| ID    | Category      | Rule                                                | Tier   | Severity |
+| ----- | ------------- | --------------------------------------------------- | ------ | -------- |
+| S-01  | Structure     | Required files exist                                | Tier 1 | Error    |
+| S-02  | Structure     | Directory structure matches pattern                 | Tier 1 | Error    |
+| S-03  | Structure     | No extraneous top-level files                       | Tier 1 | Warning  |
+| I-01  | SDK           | isInFrontierApp() call in Layout.tsx                | Tier 2 | Error    |
+| I-02  | SDK           | createStandaloneHTML() fallback in Layout.tsx        | Tier 2 | Error    |
+| I-03  | SDK           | SdkProvider wrapping children in Layout.tsx          | Tier 2 | Error    |
+| I-04  | SDK           | useSdk() hook available and used                    | Tier 2 | Error    |
+| C-01  | Configuration | vercel.json: CORS + CSP frame-ancestors (3 origins) | Tier 2 | Error    |
+| C-02  | Configuration | tsconfig.json has strict mode and vitest types      | Tier 1 | Error    |
+| C-03  | Configuration | postcss.config.js imports @tailwindcss/postcss      | Tier 1 | Error    |
+| C-04  | Configuration | package.json has correct scripts                    | Tier 1 | Error    |
+| C-05a | Configuration | package.json has required dependencies              | Tier 1 | Error    |
+| C-05b | Configuration | package.json has SDK dependency                     | Tier 2 | Error    |
+| M-01  | Mock Layer    | frontier-services.tsx exports useServices            | Tier 1 | Error    |
+| M-02  | Mock Layer    | createMockServices exported                         | Tier 1 | Error    |
+| M-03  | Mock Layer    | No direct SDK imports in feature code               | Tier 1 | Error    |
+| P-01  | Permissions   | Manifest permissions match SDK method calls         | Tier 2 | Error    |
+| P-02  | Permissions   | No SDK methods called without permission            | Tier 2 | Error    |
+| P-03  | Permissions   | No unnecessary permissions declared                 | Tier 2 | Warning  |
+| B-01  | Build         | tsc --noEmit passes                                 | Tier 1 | Error    |
+| B-02  | Build         | vite build succeeds                                 | Tier 1 | Error    |
+| B-03  | Build         | vitest run passes (if tests exist)                  | Tier 1 | Error    |
+| T-01  | Theme         | Dark theme CSS variables defined in index.css       | Tier 1 | Error    |
+| T-02  | Theme         | body class="dark" in index.html                     | Tier 1 | Error    |
+| T-03  | Theme         | Plus Jakarta Sans font loaded                       | Tier 1 | Error    |
+| T-04  | Theme         | @import "tailwindcss" in index.css                  | Tier 1 | Error    |
+| T-05  | Theme         | Base layer styles present                           | Tier 1 | Error    |