UN-4270 [FEAT] v1 scaffold, strict TypeScript and import boundary

.github/workflows/ci-frontend-lint.yaml

@@ -50,7 +50,7 @@ jobs:
         uses: actions/checkout@v6
 
       - name: Setup Biome
-        uses: biomejs/setup-biome@v2
+        uses: biomejs/setup-biome@4c91541eaada48f67d7dbd7833600ce162b68f51 # v2.7.1
         with:
           version: "2.3.13"
 
@@ -121,6 +121,31 @@ jobs:
         working-directory: frontend
         run: bun run typecheck
 
+      # src/v1 is excluded from the step above and checked under its own
+      # stricter tsconfig, after scripts/check-v1.mjs checks file types,
+      # placement, symlinks and the folder taxonomy.
+      - name: Run v1 typecheck
+        working-directory: frontend
+        run: bun run typecheck:v1
+
+      # Biome on src/v1, then scripts/check-v1.mjs: the folder import
+      # contract, v0 reaching v1 only through `@v1`, PropTypes and `ant-`.
+      - name: Run v1 lint
+        working-directory: frontend
+        run: bun run lint:v1
+
+      # The guardrail fixtures run under `node --test` (Node 22 APIs).
+      - name: Setup Node
+        uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
+        with:
+          node-version: "22"
+
+      # v1 unit tests, then the fixtures proving each guard above fails and
+      # passes when it should.
+      - name: Run v1 tests
+        working-directory: frontend
+        run: bun run test:v1
+
   # ci-test.yaml runs the same suite as the rig's `frontend` group, but its
   # tiers skip frontend-only PRs; this job is what gates those.
   vitest:

.gitignore

@@ -41,8 +41,12 @@ eggs/
 lib/
 lib64/
 # The Python `lib/` rule above also matches the frontend's shadcn/ui helper
-# directory (`@/lib/utils` per components.json). Keep that tracked.
+# directory (`@/lib/utils` per components.json), the v1 `lib/` folder and the
+# v1 guardrail fixtures. Keep those tracked, or their files are silently left
+# out of commits.
 !frontend/src/lib/
+!frontend/src/v1/**/lib/
+!frontend/test-fixtures/**/lib/
 parts/
 sdist/
 var/
@@ -635,6 +639,10 @@ workers/pluggable_worker/*
 # FE Plugins
 frontend/src/plugins/*
 frontend/public/llm-whisperer/
+# v1 cloud plugins are copied in at build time; only the placeholder manifest
+# is public.
+frontend/src/v1/plugins/*
+!frontend/src/v1/plugins/manifest.ts
 
 
 # TODO: Ensure its made generic to abstract subfolder and file names

.pre-commit-config.yaml

@@ -22,9 +22,9 @@ repos:
       - id: check-docstring-first
       - id: check-ast
       - id: check-json
-        # Both files are JSONC — their tooling (VS Code, tsc) allows comments,
+        # These files are JSONC — their tooling (VS Code, tsc) allows comments,
         # but this hook parses with strict `json.loads`, which does not.
-        exclude: "(\\.vscode/launch\\.json|frontend/tsconfig\\.json)$"
+        exclude: "(\\.vscode/launch\\.json|frontend/(src/v1/)?tsconfig\\.json)$"
       - id: check-executables-have-shebangs
       - id: check-shebang-scripts-are-executable
       - id: check-toml

frontend/biome.json

@@ -129,5 +129,97 @@
   "assist": {
     "enabled": true,
     "actions": { "source": { "organizeImports": "on" } }
-  }
+  },
+  "overrides": [
+    {
+      "includes": ["src/v1/**"],
+      "linter": {
+        "rules": {
+          "style": {
+            "noRestrictedImports": {
+              "level": "error",
+              "options": {
+                "paths": {
+                  "prop-types": "v1 is typed with TypeScript; PropTypes are not used under src/v1.",
+                  "antd": "antd is not used under src/v1."
+                },
+                "patterns": [
+                  {
+                    "group": [
+                      "../**",
+                      "..",
+                      "./../**",
+                      "/**",
+                      "@/**",
+                      "src/**"
+                    ],
+                    "message": "v1 imports nothing outside src/v1, and never with '../'. Use './' within a folder and '@v1/...' across folders."
+                  },
+                  {
+                    "group": ["@ant-design/**", "antd/**"],
+                    "message": "antd is not used under src/v1."
+                  },
+                  {
+                    "group": ["prop-types/**"],
+                    "message": "v1 is typed with TypeScript; PropTypes are not used under src/v1."
+                  },
+                  {
+                    "group": [
+                      "**/*.css",
+                      "**/*.less",
+                      "**/*.sass",
+                      "**/*.scss",
+                      "**/*.styl",
+                      "**/*.stylus",
+                      "**/*.pcss",
+                      "**/*.postcss",
+                      "**/*.sss",
+                      "!@v1/styles/**"
+                    ],
+                    "message": "No component .css under src/v1; style with tokens and Tailwind. Global v1 styles live in @v1/styles/."
+                  }
+                ]
+              }
+            }
+          },
+          "suspicious": {
+            "noExplicitAny": "error"
+          }
+        }
+      }
+    },
+    {
+      "includes": ["src/**", "!src/v1/**"],
+      "linter": {
+        "rules": {
+          "style": {
+            "noRestrictedImports": {
+              "level": "error",
+              "options": {
+                "patterns": [
+                  {
+                    "group": [
+                      "@v1/**",
+                      "@/v1",
+                      "@/v1/**",
+                      "src/v1",
+                      "src/v1/**",
+                      "/src/v1",
+                      "/src/v1/**",
+                      "./v1",
+                      "./v1/**",
+                      "../**/v1",
+                      "../**/v1/**",
+                      "!@v1"
+                    ],
+                    "message": "v0 may import only the v1 public entry, as '@v1'."
+                  }
+                ]
+              }
+            }
+          }
+        }
+      }
+    }
+  ]
 }

frontend/jsconfig.json

@@ -2,9 +2,11 @@
   "compilerOptions": {
     "baseUrl": ".",
     "paths": {
-      "@/*": ["./src/*"]
+      "@/*": ["./src/*"],
+      "@v1": ["./src/v1/index.ts"],
+      "@v1/*": ["./src/v1/*"]
     }
   },
   "include": ["src/**/*"],
-  "exclude": ["node_modules", "build"]
+  "exclude": ["node_modules", "build", "src/v1"]
 }

frontend/package.json

@@ -77,7 +77,10 @@
     "check:fix": "biome check --write src/",
     "lint:all": "biome check --write src/",
     "lint:changed": "(git diff --name-only --diff-filter=ACMR; git ls-files --others --exclude-standard) | grep -E '\\.[jt]sx?$' | sed 's|^frontend/||' | sort -u | xargs -r biome check --write",
-    "typecheck": "tsc --noEmit"
+    "typecheck": "tsc --noEmit",
+    "typecheck:v1": "node scripts/check-v1.mjs --files && tsc -p src/v1/tsconfig.json",
+    "lint:v1": "biome lint src/v1/ && node scripts/check-v1.mjs --code",
+    "test:v1": "vitest run --dir src/v1 --passWithNoTests && node --test test-fixtures/v1-boundary/boundary.fixtures.mjs"
   },
   "browserslist": {
     "production": [
@@ -92,6 +95,7 @@
     ]
   },
   "devDependencies": {
+    "@babel/parser": "^7.28.6",
     "@biomejs/biome": "^2.3.13",
     "@tailwindcss/postcss": "^4",
     "@tailwindcss/typography": "^0.5.20",
@@ -106,6 +110,8 @@
     "autoprefixer": "^10.5.4",
     "baseline-browser-mapping": "^2.9.19",
     "happy-dom": "^20.10.2",
+    "postcss": "^8.5.23",
+    "postcss-value-parser": "^4.2.0",
     "tailwindcss": "^4",
     "typescript": "^7.0.2",
     "vite": "^7.3.5",