Reduce bridge artifact drift across the app-builder workflow

Fulora's app-facing bridge story had split across generator output,
templates, samples, and CLI workflows. This change moves the
common path toward generated service facades, makes bridge
artifact generation explicit and complete, and teaches `dev`
and `package` to validate manifest-based consistency before
developers fall into stale-contract failures.

The CLI now emits and consumes a bridge artifact manifest,
exposes `--preflight-only` for fast checks, and uses more
stable build invocation defaults for nested CLI-driven bridge
builds in tests and real workflows.

Constraint: Must preserve the existing bridge transport/runtime substrate while improving app-builder DX
Constraint: Must keep legacy service exports available during the transition to `services.*`-style facades
Rejected: Auto-fix missing/stale artifacts inside `dev`/`package` | user explicitly requested manifest/hash consistency rather than implicit mutation
Rejected: Keep timestamp-only freshness checks | too noisy and not authoritative enough for build/TFM drift
Confidence: medium
Scope-risk: moderate
Reversibility: clean
Directive: Keep bridge artifact consistency logic centralized; do not re-spread manifest/hash checks across commands without a shared helper
Directive: If manifest schema changes, update both CLI generation and MSBuild target emission in lockstep
Tested: `dotnet test tests/Agibuild.Fulora.UnitTests/Agibuild.Fulora.UnitTests.csproj -v minimal` (2177 passed)
Tested: Template/sample web builds for React, Vue, Showcase Todo, and AI Chat during implementation
Not-tested: End-to-end desktop runtime behavior after `dev`/`package` preflight warnings on a freshly scaffolded app

Author: Hongwei-MB

README.md

@@ -136,9 +136,9 @@ webView.Bridge.Expose<IGreeterService>(new GreeterService());
 Call from JavaScript:
 
 ```javascript
-const msg = await window.agWebView.rpc.invoke("GreeterService.greet", {
-    name: "World"
-});
+import { services } from "./bridge/client";
+
+const msg = await services.greeter.greet({ name: "World" });
 ```
 
 Call JavaScript from C#:

docs/articles/bridge-guide.md

@@ -45,7 +45,9 @@ webView.Bridge.Expose<ICalculatorService>(new CalculatorService());
 ### 2) Call from JavaScript
 
 ```javascript
-const sum = await window.agWebView.rpc.invoke("Calculator.add", { a: 3, b: 4 });
+import { services } from "./bridge/client";
+
+const sum = await services.calculator.add({ a: 3, b: 4 });
 ```
 
 ### 3) Call JavaScript service from C# (`[JsImport]`)

docs/articles/getting-started.md

@@ -153,7 +153,9 @@ WebView.Bridge.Expose<IGreeterService>(new GreeterServiceImpl());
 Call it from JavaScript — the bridge client is auto-generated:
 
 ```javascript
-const result = await GreeterService.greet("World");
+import { services } from "./bridge/client";
+
+const result = await services.greeter.greet({ name: "World" });
 // → "Hello, World!"
 ```
 

docs/cli.md

@@ -33,23 +33,28 @@ Start the Vite dev server and Avalonia desktop app together. Run from the soluti
 ```bash
 fulora dev
 fulora dev --web ./MyApp.Web.Vite.React --desktop ./MyApp.Desktop/MyApp.Desktop.csproj
+fulora dev --preflight-only
 ```
 
 | Option | Description |
 |---|---|
 | `--web` | Web project directory (auto-detected) |
 | `--desktop` | Desktop `.csproj` path (auto-detected) |
 | `--npm-script` | npm script name (default: `dev`) |
+| `--preflight-only` | Run bridge/dev preflight checks and exit without starting the dev processes |
 
 Press **Ctrl+C** to stop both processes.
 
+Use `--preflight-only` when you want to validate bridge artifact consistency and project wiring without launching Vite or the desktop host.
+
 ### `fulora package`
 
 Package your app for distribution. The recommended first path is to start with a named profile.
 
 ```bash
 fulora package --project ./src/MyApp.Desktop/MyApp.Desktop.csproj --profile desktop-public
 fulora package --project ./src/MyApp.Desktop/MyApp.Desktop.csproj --profile mac-notarized
+fulora package --project ./src/MyApp.Desktop/MyApp.Desktop.csproj --profile desktop-public --preflight-only
 ```
 
 Available profiles today:
@@ -69,16 +74,30 @@ Available profiles today:
 | `--sign-params`, `-n` | Raw signing parameters passed to `vpk` |
 | `--notarize` | Enable macOS notarization |
 | `--channel`, `-c` | Release channel |
+| `--preflight-only` | Run packaging and bridge consistency preflight checks, then exit without publishing or packing |
 
 If `vpk` is not installed, `fulora package` falls back to copying the `dotnet publish` output into the output directory.
 
+The command now emits **preflight notes** before packaging when the selected profile implies extra setup. Examples:
+
+- `desktop-public` without `vpk` → warns that Fulora will copy publish output instead of producing installer/update packages
+- `mac-notarized` without `vpk` → warns that the fallback output will not be notarized
+- `mac-notarized` on a non-macOS host → warns that notarization usually needs a macOS host
+
+Use `--preflight-only` when you want those checks without triggering `dotnet publish` or `vpk`.
+
 ## Advanced Workflows
 
 Use these commands after the main path is already working.
 
 ### `fulora generate types`
 
-Build the Bridge project and extract generated TypeScript declarations.
+Build the Bridge project and extract the generated bridge artifacts:
+
+- `bridge.d.ts`
+- `bridge.client.ts`
+- `bridge.mock.ts`
+- `bridge.manifest.json`
 
 ```bash
 fulora generate types
@@ -88,7 +107,9 @@ fulora gen types --project ./MyApp.Bridge/MyApp.Bridge.csproj --output ./MyApp.W
 | Option | Description |
 |---|---|
 | `--project`, `-p` | Bridge `.csproj` path (auto-detected) |
-| `--output`, `-o` | Output directory for generated `.d.ts` files (auto-detected) |
+| `--output`, `-o` | Output directory for generated bridge artifacts (auto-detected; prefers `src/bridge/generated` when present) |
+
+The generated `bridge.manifest.json` records the bridge project identity, artifact directory, build configuration, target framework, bridge assembly hash, and artifact hashes so `fulora dev` and `fulora package` can detect missing or stale generated outputs without relying only on timestamps.
 
 ### `fulora add service <name>`
 

docs/shipping-your-app.md

@@ -18,6 +18,10 @@ fulora package --project ./src/MyApp.Desktop/MyApp.Desktop.csproj \
   --profile desktop-public \
   --version 1.0.0 \
   --output ./Releases
+
+fulora package --project ./src/MyApp.Desktop/MyApp.Desktop.csproj \
+  --profile desktop-public \
+  --preflight-only
 ```
 
 Profiles are the productized shipping path in Fulora. They bundle the recommended defaults for a release scenario so you do not need to remember low-level flags every time.
@@ -30,6 +34,8 @@ Current built-in profiles:
 
 You can still override profile defaults with explicit flags. For example, `--runtime linux-x64` or `--channel preview` wins over the profile setting.
 
+If you want to verify packaging prerequisites without running publish/pack yet, use `--preflight-only`.
+
 ### 2. Package command options
 
 | Option | Description | Default |
@@ -52,6 +58,14 @@ You can still override profile defaults with explicit flags. For example, `--run
 
 If `vpk` is not installed, `fulora package` falls back to copying the `dotnet publish` output into the output directory.
 
+Fulora now prints **preflight notes** before packaging when the chosen profile implies extra setup. Typical examples:
+
+- `desktop-public` without `vpk`: you will get copied publish output, not installer/update packages
+- `mac-notarized` without `vpk`: the fallback output will not be notarized
+- `mac-notarized` on a non-macOS host: you may need to finish signing/notarization on macOS
+
+`fulora package` also checks the bridge artifact manifest (`bridge.manifest.json`) when it can locate a sibling Bridge project. That lets it warn about missing or stale generated bridge files before packaging continues.
+
 ## Raw Signing And Notarization Flags
 
 Most teams should stay on the profile-based path. Use the raw flags below when you need to tune signing behavior for a specific environment.

samples/avalonia-ai-chat/AvaloniAiChat.Web/src/bridge/client.ts

@@ -1,8 +1,43 @@
-import { createBridgeProfile } from '@agibuild/bridge/profile';
+import {
+  createBridgeClient,
+  type BridgeReadyOptions,
+  withErrorNormalization,
+  withLogging,
+} from '@agibuild/bridge';
+import { aiChatService, windowShellBridgeService } from './generated/bridge.client';
 
-export const bridgeProfile = createBridgeProfile({
-  enableLogging: import.meta.env.DEV,
-  logging: { maxParamLength: 200 },
-});
+export type {
+  AiModelState,
+  DroppedFileResult,
+  TransparencyLevel,
+  WindowShellState,
+  WindowShellSettings,
+} from './generated/bridge.d';
 
-export const bridge = bridgeProfile.bridge;
+const bridgeClient = createBridgeClient();
+
+if (import.meta.env.DEV) {
+  bridgeClient.use(withLogging({ maxParamLength: 200 }));
+}
+
+bridgeClient.use(withErrorNormalization());
+
+export const bridge = bridgeClient;
+
+export const bridgeProfile = {
+  bridge,
+  ready(options?: BridgeReadyOptions) {
+    return bridge.ready(options);
+  },
+};
+
+export function createFuloraClient() {
+  return {
+    aiChat: aiChatService,
+    windowShellBridge: windowShellBridgeService,
+  } as const;
+}
+
+export const services = createFuloraClient();
+
+export { aiChatService, windowShellBridgeService };

samples/avalonia-ai-chat/AvaloniAiChat.Web/src/bridge/services.ts

@@ -1,9 +1,9 @@
-export { aiChatService, windowShellBridgeService } from './generated/bridge.client';
+export { aiChatService, createFuloraClient, services, windowShellBridgeService } from './client';
 
 export type {
   AiModelState,
   DroppedFileResult,
   TransparencyLevel,
   WindowShellState,
   WindowShellSettings,
-} from './generated/bridge.d';
+} from './client';

samples/avalonia-react/AvaloniReact.Web/src/bridge/client.ts

@@ -3,11 +3,65 @@
  * Configures cross-cutting concerns (logging, error normalization) before any service calls.
  */
 
-import { createBridgeProfile } from '@agibuild/bridge/profile';
+import {
+  createBridgeClient,
+  type BridgeReadyOptions,
+  withErrorNormalization,
+  withLogging,
+} from '@agibuild/bridge';
+import {
+  appShellService,
+  chatService,
+  fileService,
+  settingsService,
+  systemInfoService,
+} from './generated/bridge.client';
 
-export const bridgeProfile = createBridgeProfile({
-  enableLogging: import.meta.env.DEV,
-  logging: { maxParamLength: 100 },
-});
+export type {
+  AppInfo,
+  AppSettings,
+  ChatMessage,
+  ChatRequest,
+  ChatResponse,
+  FileEntry,
+  PageDefinition,
+  RuntimeMetrics,
+  SystemInfo,
+} from './generated/bridge.d';
 
-export const bridge = bridgeProfile.bridge;
+const bridgeClient = createBridgeClient();
+
+if (import.meta.env.DEV) {
+  bridgeClient.use(withLogging({ maxParamLength: 100 }));
+}
+
+bridgeClient.use(withErrorNormalization());
+
+export const bridge = bridgeClient;
+
+export const bridgeProfile = {
+  bridge,
+  ready(options?: BridgeReadyOptions) {
+    return bridge.ready(options);
+  },
+};
+
+export function createFuloraClient() {
+  return {
+    appShell: appShellService,
+    chat: chatService,
+    file: fileService,
+    settings: settingsService,
+    systemInfo: systemInfoService,
+  } as const;
+}
+
+export const services = createFuloraClient();
+
+export {
+  appShellService,
+  chatService,
+  fileService,
+  settingsService,
+  systemInfoService,
+};

samples/avalonia-react/AvaloniReact.Web/src/bridge/services.ts

@@ -4,12 +4,14 @@
  */
 
 export {
+  createFuloraClient,
+  services,
   appShellService,
   systemInfoService,
   chatService,
   fileService,
   settingsService,
-} from './generated/bridge.client';
+} from './client';
 
 export type {
   AppInfo,
@@ -21,4 +23,4 @@ export type {
   PageDefinition,
   RuntimeMetrics,
   SystemInfo,
-} from './generated/bridge.d';
+} from './client';

samples/avalonia-vue/AvaloniVue.Web/src/bridge/client.js

@@ -1,8 +1,47 @@
-import { createBridgeProfile } from '@agibuild/bridge/profile';
+import { BridgeReadyTimeoutError, createBridgeClient, withErrorNormalization, withLogging, } from '@agibuild/bridge';
+import { appShellService, chatService, fileService, settingsService, systemInfoService, } from './generated/bridge.client';
 import { installBridgeMock } from './generated/bridge.mock';
-export const bridgeProfile = createBridgeProfile({
-    enableLogging: import.meta.env.DEV,
-    logging: { maxParamLength: 200 },
-    installMock: installBridgeMock,
-});
-export const bridge = bridgeProfile.bridge;
+const bridgeClient = createBridgeClient();
+if (import.meta.env.DEV) {
+    bridgeClient.use(withLogging({ maxParamLength: 200 }));
+}
+bridgeClient.use(withErrorNormalization());
+let mockInstalled = false;
+function installMockOnce() {
+    if (mockInstalled) {
+        return;
+    }
+    installBridgeMock();
+    mockInstalled = true;
+}
+export const bridge = bridgeClient;
+export const bridgeProfile = {
+    bridge,
+    get isMockMode() {
+        return mockInstalled;
+    },
+    async ready(options) {
+        try {
+            await bridge.ready(options);
+        }
+        catch (err) {
+            if (!mockInstalled && err instanceof BridgeReadyTimeoutError) {
+                installMockOnce();
+                await bridge.ready(options);
+                return;
+            }
+            throw err;
+        }
+    },
+};
+export function createFuloraClient() {
+    return {
+        appShell: appShellService,
+        chat: chatService,
+        file: fileService,
+        settings: settingsService,
+        systemInfo: systemInfoService,
+    };
+}
+export const services = createFuloraClient();
+export { appShellService, chatService, fileService, settingsService, systemInfoService, };