feat(formulus): support settings deep links

formulus/App.tsx

@@ -29,6 +29,21 @@ import { FormInitData } from './src/webview/FormulusInterfaceDefinition.ts';
 import { FormSpec } from './src/services';
 import { initFormulusI18n, i18n } from './src/i18n';
 import { DirtyExitGate } from './src/diagnostics/DirtyExitGate';
+import type { LinkingOptions } from '@react-navigation/native';
+import type { MainAppStackParamList } from './src/navigation/ProfileNavigationTypes';
+
+const linking: LinkingOptions<MainAppStackParamList> = {
+  prefixes: ['formulus://'],
+  config: {
+    screens: {
+      MainApp: {
+        screens: {
+          Profiles: 'settings',
+        },
+      },
+    },
+  },
+};
 
 /**
  * Inner component that consumes the AppTheme context to build a dynamic
@@ -276,7 +291,7 @@ function AppInner(): React.JSX.Element {
         backgroundColor={themeColors.surface}
       />
       <DirtyExitGate />
-      <NavigationContainer theme={navigationTheme}>
+      <NavigationContainer theme={navigationTheme} linking={linking}>
         <MainAppNavigator />
         {formplayerStack.map((entry, index) => (
           <FormplayerModal

formulus/android/app/src/main/AndroidManifest.xml

@@ -38,6 +38,16 @@
             <action android:name="android.intent.action.MAIN" />
             <category android:name="android.intent.category.LAUNCHER" />
         </intent-filter>
+        <intent-filter>
+            <action android:name="android.intent.action.VIEW" />
+
+            <category android:name="android.intent.category.DEFAULT" />
+            <category android:name="android.intent.category.BROWSABLE" />
+
+            <data
+                android:scheme="formulus"
+                android:host="settings" />
+        </intent-filter>
       </activity>
 
       <service

formulus/ios/Formulus/Info.plist

@@ -10,6 +10,17 @@
 	<string>$(EXECUTABLE_NAME)</string>
 	<key>CFBundleIdentifier</key>
 	<string>$(PRODUCT_BUNDLE_IDENTIFIER)</string>
+	<key>CFBundleURLTypes</key>
+		<array>
+		<dict>
+		<key>CFBundleURLName</key>
+		<string>org.opendataensemble.formulus</string>
+		<key>CFBundleURLSchemes</key>
+		<array>
+		<string>formulus</string>
+		</array>
+		</dict>
+		</array>
 	<key>CFBundleInfoDictionaryVersion</key>
 	<string>6.0</string>
 	<key>CFBundleName</key>

formulus/scripts/generateQR.ts

@@ -59,7 +59,8 @@ function main() {
   try {
     const frmls = parseArgs();
     const encoded = encodeFRMLS(frmls);
-    console.log(encoded);
+    const deepLink = `formulus://settings?payload=${encodeURIComponent(encoded)}`;
+    console.log(deepLink);
   } catch (error) {
     console.error(
       'Error:',

formulus/src/navigation/ProfileNavigationTypes.ts

@@ -6,7 +6,11 @@ import type {
 
 // Keep the profile UI's route extension alongside its navigator.
 export type MainTabParamList = BaseMainTabParamList & {
-  Profiles: undefined;
+  Profiles:
+    | {
+        payload?: string;
+      }
+    | undefined;
 };
 
 export type MainAppStackParamList = Omit<

formulus/src/screens/ProfilesScreen.tsx

@@ -1,4 +1,6 @@
 import React, { useCallback, useEffect, useRef, useState } from 'react';
+import type { BottomTabScreenProps } from '@react-navigation/bottom-tabs';
+import type { MainTabParamList } from '../navigation/ProfileNavigationTypes';
 import {
   ScrollView,
   StyleSheet,
@@ -21,7 +23,10 @@ import { profileRegistry } from '../profiles/ProfileRegistry';
 import { switchProfile, deleteProfile } from '../profiles/ProfileTransitions';
 import { ToastService } from '../services/ToastService';
 import { setCredentialsForProfile } from '../profiles/ProfileKeychain';
-import type { SettingsUpdate } from '../services/QRSettingsService';
+import {
+  QRSettingsService,
+  type SettingsUpdate,
+} from '../services/QRSettingsService';
 import {
   odeSpacing,
   odeTypography,
@@ -41,7 +46,8 @@ type LabelEditor = {
   initialSettings?: SettingsUpdate;
 };
 
-const ProfilesScreen = () => {
+type ProfilesScreenProps = BottomTabScreenProps<MainTabParamList, 'Profiles'>;
+const ProfilesScreen = ({ route, navigation }: ProfilesScreenProps) => {
   const { t } = useTranslation();
   const { themeColors } = useAppTheme();
   const shellStyle = useScreenShellStyle();
@@ -61,6 +67,34 @@ const ProfilesScreen = () => {
     };
   }, []);
 
+  useEffect(() => {
+    const payload = route?.params?.payload;
+    if (!payload) return;
+
+    const processDeepLink = async () => {
+      try {
+        const settings = await QRSettingsService.processQRCode(
+          `formulus://settings?payload=${encodeURIComponent(payload)}`,
+        );
+
+        if (!mountedRef.current) return;
+
+        setDropdownOpen(false);
+        setEditor({ label: '', initialSettings: settings });
+      } catch {
+        if (mountedRef.current) {
+          ToastService.showLong(t('settings.qrInvalid'));
+        }
+      } finally {
+        if (mountedRef.current) {
+          navigation.setParams({ payload: undefined });
+        }
+      }
+    };
+
+    void processDeepLink();
+  }, [navigation, route?.params?.payload, t]);
+
   const runAction = useCallback<RunProfileAction>(
     async (operation, fallbackKey) => {
       if (busyRef.current || !mountedRef.current) return;

formulus/src/services/QRSettingsService.ts

@@ -1,6 +1,23 @@
 import { decodeFRMLS } from '../utils/FRMLSHelpers';
 import { normalizeServerUrl } from './normalizeServerUrl';
 
+const FORMULUS_SETTINGS_URL = 'formulus://settings';
+
+function unwrapQRCode(qrString: string): string {
+  if (qrString.startsWith('FRMLS:')) return qrString;
+
+  const prefix = `${FORMULUS_SETTINGS_URL}?payload=`;
+  if (!qrString.startsWith(prefix)) {
+    throw new Error('Not a Formulus settings link');
+  }
+
+  const encodedPayload = qrString.slice(prefix.length);
+  if (!encodedPayload) {
+    throw new Error('Missing FRMLS payload');
+  }
+
+  return decodeURIComponent(encodedPayload);
+}
 export interface SettingsUpdate {
   serverUrl: string;
   username: string;
@@ -13,7 +30,7 @@ export class QRSettingsService {
    */
   static parseQRCode(qrString: string): SettingsUpdate {
     try {
-      const frmls = decodeFRMLS(qrString);
+      const frmls = decodeFRMLS(unwrapQRCode(qrString));
 
       return {
         serverUrl: frmls.s,

formulus/src/services/__tests__/QRSettingsService.test.ts

@@ -0,0 +1,59 @@
+/// <reference types="jest" />
+
+import { describe, it, expect } from '@jest/globals';
+import { encodeFRMLS } from '../../utils/FRMLSHelpers';
+import { QRSettingsService } from '../QRSettingsService';
+
+describe('QRSettingsService', () => {
+  it('parses a bare FRMLS payload', () => {
+    const qr = encodeFRMLS({
+      v: 1,
+      s: 'https://example.org/',
+      u: 'allen',
+      p: 'secret',
+    });
+
+    const settings = QRSettingsService.parseQRCode(qr);
+
+    expect(settings).toEqual({
+      serverUrl: 'https://example.org/',
+      username: 'allen',
+      password: 'secret',
+    });
+  });
+  it('parses an FRMLS payload wrapped in a Formulus settings deep link', () => {
+    const frmls = encodeFRMLS({
+      v: 1,
+      s: 'https://example.org/',
+      u: 'allen',
+      p: 'secret',
+    });
+    const qr = `formulus://settings?payload=${encodeURIComponent(frmls)}`;
+
+    const settings = QRSettingsService.parseQRCode(qr);
+
+    expect(settings).toEqual({
+      serverUrl: 'https://example.org/',
+      username: 'allen',
+      password: 'secret',
+    });
+  });
+  it('rejects a non-Formulus deep link', () => {
+    const frmls = encodeFRMLS({
+      v: 1,
+      s: 'https://example.org/',
+      u: 'allen',
+      p: 'secret',
+    });
+    const qr = `https://example.org/settings?payload=${encodeURIComponent(frmls)}`;
+
+    expect(() => QRSettingsService.parseQRCode(qr)).toThrow(
+      'Not a Formulus settings link',
+    );
+  });
+  it('rejects a Formulus settings deep link with no payload', () => {
+    expect(() =>
+      QRSettingsService.parseQRCode('formulus://settings?payload='),
+    ).toThrow('Missing FRMLS payload');
+  });
+});

synkronus-cli/internal/cmd/qr.go

@@ -143,6 +143,7 @@ for the Formulus mobile app. The QR encodes server URL, username, and password.`
 			}
 
 			encoded := encodeFRMLS(1, serverURL, username, password)
+			deepLink := "formulus://settings?payload=" + url.QueryEscape(encoded)
 
 			outputFile, err := cmd.Flags().GetString("output")
 			if err != nil {
@@ -154,7 +155,7 @@ for the Formulus mobile app. The QR encodes server URL, username, and password.`
 
 			// Generate QR code with logo using yeqown/go-qrcode
 			logoPath := "qr_logo.png"
-			qrc, err := qrcode.New(encoded)
+			qrc, err := qrcode.New(deepLink)
 			if err != nil {
 				return fmt.Errorf("failed to create QR code: %w", err)
 			}

synkronus-portal/src/utils/frmls.ts

@@ -32,10 +32,11 @@ export function encodeFormulusLoginQr(
   username: string,
   password: string,
 ): string {
-  return encodeFRMLS({
+  const frmls = encodeFRMLS({
     v: 1,
     s: serverUrl,
     u: username,
     p: password,
   });
+  return `formulus://settings?payload=${encodeURIComponent(frmls)}`;
 }