Initial commit: Grounded Flutter frontend

A to-do app that doesn't believe you — an enforcement layer rather than a
neutral ledger.

Architecture ported from Autoreceptives/Frontend/Receptive: stacked MVVM with
the mandatory 4-file screen pattern, one ParentViewModel owning the loading /
network / error overlays and the handleError decision tree, one AppDataManager
gateway, dio comms carrying the three identity headers, secure storage with
random-suffixed keys, and a single-chokepoint Navigator. Package root and Dart
package name are both Grounded; org is nya.

The enforcement engine, one unit per formula in utils/:

- DebtEngine      w(class) x severity(d) x decay(t), sublinear severity so old
                  misses cannot swamp the score; abandonment 2x with 30-day
                  decay immunity; late complete retains 30%
- StandingEngine  Good -> Warned -> Grounded -> Lockdown, derived not set;
                  Grounded replaces home with the overdue queue
- CapacityEngine  blocks over-scheduling against p50 of historically completed
                  minutes, with a learned per-category estimation multiplier
- IntegrityEngine session integrity, weekly volume, plyometric contact ceiling
                  and enforced recovery gaps
- ExcuseAnalyser  on-device excuse clustering plus the confrontation copy
- GuardrailEngine distress detection and rationed amnesty
- ToneEngine      all enforcement copy, so the tone cap lives in one place

CommitmentEvent is append-only and is the source of truth rather than the
status field, which is what makes honest history and excuse analysis possible.

Goals contain commitments via parentId, and a task can be run from a
full-screen runner that derives elapsed time from wall-clock so screen-off
cannot lose time. Backgrounding pauses the clock and is counted. The runner is
mirrored into an ongoing notification, with alarm-class full-screen intents
reserved for non-negotiables.

Design language, fonts, icon and native splash are in place; Mason bricks are
retargeted to this project and verified end-to-end.

flutter analyze lib/ reports no errors.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Mfu2gQLSFN21YRBcU2NrTt

frontend/bricks/api_endpoint/CHANGELOG.md

@@ -0,0 +1,3 @@
+# 0.1.0+1
+
+- TODO: Describe initial release.

frontend/bricks/api_endpoint/LICENSE

@@ -0,0 +1 @@
+TODO: Add your license here.

frontend/bricks/api_endpoint/README.md

@@ -0,0 +1,83 @@
+## 📄 README.md
+
+### 🚀 API Endpoint Mason Brick
+A smart, synchronized generator that appends API logic across `Comms`, `ConnectComms`, and `AppDataManager` while handling auto-imports and optional formatting.
+
+### 🛠 1. First-Time Setup
+Run these commands to ensure Mason and the Dart hooks are ready to go:
+
+```bash
+# 1. Install Mason CLI (if you haven't)
+dart pub global activate mason_cli
+
+# 2. Initialize Mason in project root
+mason init
+
+# 3. Install Hook dependencies
+cd bricks/api_endpoint/hooks
+dart pub get
+cd ../../../
+
+# 4. Register the brick
+mason get
+```
+
+### 🔃 2. How to Refresh (When logic or prompts change)
+If you update the `brick.yaml` or the `post_gen.dart` hook, Mason might use a cached version. Use this "Hard Refresh" command:
+
+```bash
+rm -rf .mason && mason get
+```
+
+### 🏃 3. Running the Generator
+To add a new endpoint, simply run:
+```bash
+mason make api_endpoint
+```
+
+**Interaction Flow:**
+1. **Endpoint Path:** e.g., `orders/confirm`
+2. **Function Name:** e.g., `confirmOrder`
+3. **Method:** Choose `get` or `post`.
+4. **Request Body:** * **Mandatory for POST**: e.g., `OrderDetails`.
+    * **Optional for GET**: Leave empty or provide a type like `String`.
+5. **Auto-Import**: The brick scans `lib/` for your Body type and adds the `import` statement automatically.
+6. **Format**: Choose `y` to run `dart format` on all 4 modified files.
+
+---
+
+## 🐚 setup_brick.sh
+Create this file in your project root to allow one-click setup or refreshing for your team.
+
+```bash
+#!/bin/bash
+
+# setup_brick.sh
+echo "🧹 Cleaning old Mason cache..."
+rm -rf .mason
+
+echo "📦 Fetching Hook dependencies..."
+if [ -d "bricks/api_endpoint/hooks" ]; then
+    cd bricks/api_endpoint/hooks
+    dart pub get
+    cd ../../../
+else
+    echo "❌ Error: bricks/api_endpoint/hooks directory not found!"
+    exit 1
+fi
+
+echo "🧱 Registering Mason Brick..."
+mason get
+
+echo "✅ Setup Complete! Run 'mason make api_endpoint' to start."
+```
+
+### To use the script:
+1. Create the file: `touch setup_brick.sh`
+2. Give it permission: `chmod +x setup_brick.sh`
+3. Run it: `./setup_brick.sh`
+
+---
+
+### 💡 Pro-Tip: Project Name Detection
+In your `post_gen.dart` hook, ensure you have updated the `package:your_project_name` string to match your real project name from `pubspec.yaml`, otherwise the auto-imports will show a red error in VS Code.

frontend/bricks/api_endpoint/brick.yaml

@@ -0,0 +1,25 @@
+name: api_endpoint
+description: Generates Comms and AppDataManager logic for a new endpoint.
+
+version: 0.1.0+1
+
+environment:
+  mason: ^0.1.1
+
+
+vars:
+  path_url:
+    type: string
+    prompt: "🌐 What is the API path? (e.g., auth/login)"
+  function_name:
+    type: string
+    prompt: "🖋️ What is the function name? (e.g., signIn)"
+  request_type:
+    type: string
+    default: get
+    prompt: "🔃 Is this a 'get' or a 'post'?"
+  request_body:
+    type: string
+    default: ""
+    prompt: "📦 Request Body type? (Mandatory for POST, Optional for GET)"
+

frontend/bricks/api_endpoint/hooks/post_gen.dart

@@ -0,0 +1,146 @@
+import 'dart:io';
+import 'package:mason/mason.dart';
+import 'package:yaml/yaml.dart';
+
+void run(HookContext context) async {
+  final logger = context.logger;
+
+  final String pathUrl = context.vars['path_url'] ?? '';
+  final String functionName = context.vars['function_name'] ?? '';
+  final String requestType = (context.vars['request_type'] as String).toLowerCase();
+  final String requestBody = context.vars['request_body'] as String;
+
+  if (requestType == 'post' && requestBody.isEmpty) {
+    logger.err('❌ Error: POST requests require a Request Body type.');
+    return;
+  }
+
+  final cName = functionName.camelCase;
+  final bool hasData = requestBody.isNotEmpty;
+  final String paramType = hasData ? requestBody : 'dynamic';
+
+  // Auto-Detect Project Name
+  String projectName = 'your_project';
+  final pubspecFile = File('pubspec.yaml');
+  if (pubspecFile.existsSync()) {
+    final doc = loadYaml(pubspecFile.readAsStringSync());
+    projectName = doc['name'] ?? projectName;
+  }
+
+  final progress = logger.progress('🚀 Injecting logic...');
+
+  final filesToUpdate = [
+    'lib/Grounded/comms/CommsDirections.dart',
+    'lib/Grounded/comms/Comms.dart',
+    'lib/Grounded/comms/ConnectComms.dart',
+    'lib/Grounded/informatics/AppDataManager.dart'
+  ];
+
+  // Find Import Path and Filename
+  String? importLine;
+  String? importFileName;
+  if (hasData && !['String','int','double','bool'].contains(requestBody)) {
+    final result = await _findClassData(requestBody, projectName);
+    importLine = result?['line'];
+    importFileName = result?['fileName'];
+  }
+
+  final String sharedParams = hasData ? '$paramType request' : '';
+  final String callParams = hasData ? 'request' : '';
+
+  // 1. CommsDirections
+  await _inject(filesToUpdate[0], "String ${cName}Path = '$pathUrl';", logger,
+      isClass: false, duplicateCheck: "${cName}Path");
+
+  // 2. comms.dart
+  final String dioData = requestType == 'post' ? 'data: request' : 'options: Options(headers: dio.options.headers)';
+  final String commsMethod = '''
+  @override
+  Future<Response> $cName($sharedParams) async {
+    Pair navigation = await getRequestHeaders(${cName}Path, "");
+    dio.options.headers = navigation.value;
+    return await dio.$requestType(
+      navigation.key, 
+      $dioData
+    );
+  }''';
+  await _inject(filesToUpdate[1], commsMethod, logger,
+      importLine: importLine, importFileName: importFileName, duplicateCheck: "Future<Response> $cName");
+
+  // 3. ConnectComms.dart
+  await _inject(filesToUpdate[2], "  Future<Response> $cName($sharedParams);", logger,
+      importLine: importLine, importFileName: importFileName, duplicateCheck: "Future<Response> $cName");
+
+  // 4. AppDataManager.dart
+  final String dataManagerMethod = '''
+  @override
+  Future<Response> $cName($sharedParams) async {
+    return await connectComms.$cName($callParams);
+  }''';
+  await _inject(filesToUpdate[3], dataManagerMethod, logger,
+      importLine: importLine, importFileName: importFileName, duplicateCheck: "Future<Response> $cName");
+
+  progress.complete('✨ Injection & Deduplication complete.');
+
+  final shouldFormat = logger.confirm('🎨 Run "dart format" on updated files?', defaultValue: false);
+  if (shouldFormat) {
+    for (final path in filesToUpdate) {
+      await Process.run('dart', ['format', path]);
+    }
+    logger.success('✅ Files formatted.');
+  }
+}
+
+/// Returns both the full import line and just the filename (e.g. user_request.dart)
+Future<Map<String, String>?> _findClassData(String className, String projectName) async {
+  final directory = Directory('lib');
+  if (!directory.existsSync()) return null;
+  final List<FileSystemEntity> files = directory.listSync(recursive: true);
+  for (var file in files) {
+    if (file is File && file.path.endsWith('.dart')) {
+      final content = await file.readAsString();
+      if (content.contains('class $className') || content.contains('enum $className')) {
+        final fileName = file.path.split('/').last;
+        final packagePath = file.path.replaceFirst('lib/Grounded/', '');
+        return {
+          'line': "import 'package:$projectName/$packagePath';",
+          'fileName': fileName,
+        };
+      }
+    }
+  }
+  return null;
+}
+
+Future<void> _inject(String path, String content, Logger logger,
+    {bool isClass = true, String? importLine, String? importFileName, String? duplicateCheck}) async {
+  final file = File(path);
+  if (!await file.exists()) return;
+  String fileContent = await file.readAsString();
+
+  // 1. Prevent Duplicate Method/Variable
+  if (duplicateCheck != null && fileContent.contains(duplicateCheck)) {
+    return; // Silently skip methods that exist
+  }
+
+  // 2. Smart Import Check: Look for the filename inside any import statement
+  if (importLine != null && importFileName != null) {
+    // Regex matches: import 'any/path/filename.dart'; or "any/path/filename.dart";
+    final importRegex = RegExp("import ['\"].*?$importFileName['\"];");
+    if (!importRegex.hasMatch(fileContent)) {
+      fileContent = "$importLine\n$fileContent";
+    }
+  }
+
+  if (isClass) {
+    final lastBrace = fileContent.lastIndexOf('}');
+    if (lastBrace != -1) {
+      fileContent = fileContent.substring(0, lastBrace).trimRight() + '\n\n$content\n' + fileContent.substring(lastBrace);
+    } else {
+      fileContent += '\n\n$content';
+    }
+  } else {
+    fileContent = fileContent.trimRight() + '\n\n$content\n';
+  }
+  await file.writeAsString(fileContent);
+}

frontend/bricks/api_endpoint/hooks/pubspec.yaml

@@ -0,0 +1,10 @@
+name: api_endpoint_hooks
+description: Hooks for the api_endpoint brick.
+publish_to: none
+
+environment:
+  sdk: ">=2.12.0 <4.0.0"
+
+dependencies:
+  mason: ^0.1.0-dev.51 # Or the latest version
+  yaml: ^3.1.2

frontend/bricks/api_endpoint/setup_brick.sh

@@ -0,0 +1,20 @@
+#!/bin/bash
+
+# setup_brick.sh
+echo "🧹 Cleaning old Mason cache (Hard Refresh)..."
+rm -rf .mason
+
+echo "📦 Fetching Hook dependencies (Yaml/Mason)..."
+if [ -d "bricks/api_endpoint/hooks" ]; then
+    cd bricks/api_endpoint/hooks
+    dart pub get
+    cd ../../../
+else
+    echo "❌ Error: Hooks directory not found!"
+    exit 1
+fi
+
+echo "🧱 Getting latest Brick definition..."
+mason get
+
+echo "✅ Ready! Run 'mason make api_endpoint'"