devendra-skill-package 1.0.2

package/.github/skills/validation-engine-builder/references/platform-flutter.md

@@ -0,0 +1,118 @@
+# Platform File — Flutter
+
+Read `core.md` first. Flutter cannot run any JS library — no Yup, no react-hook-form. This
+platform generates pure Dart, targeting Flutter's own `Form` + `TextFormField.validator`
+mechanism, which needs no package at all.
+
+---
+
+## Dependencies
+
+None. `TextFormField.validator: (value) => ...` is part of the Flutter SDK's `material`/`widgets`
+library — no `pubspec.yaml` addition is required for the baseline pattern documented here.
+`scripts/shared/npm-deps.js` no-ops for this platform (prints an explanatory message).
+
+**If the project already uses `reactive_forms` or `flutter_form_builder`** (check `pubspec.yaml`
+dependencies first), generate against that project's existing pattern instead of the plain
+`TextFormField.validator` approach below — do not introduce a second form-handling approach
+alongside an existing one. The rest of this file assumes neither is present.
+
+## Generated files
+
+`node scripts/apply-to-project.js --platform flutter` writes to `lib/core/validation/`:
+
+| File | Role |
+|---|---|
+| `validation_messages.dart` | `ValidationMessages` class — `static const String` per message key, plus `xxxMsg(...)` interpolation helpers |
+| `validation_regex.dart` | `ValidationRegex` class — `static final RegExp` per regex key |
+| `validators.dart` | One class per schema (`LoginValidators`, `SignupValidators`, ...), each with a `static String? fieldName(String? value)` method per field |
+
+**There is no generated error-display file on this platform.** `TextFormField`'s `validator`
+callback return value is rendered automatically beneath the field by the `Form`/`TextFormField`
+widgets themselves — inventing a separate "ValidationError" widget (as the other 3 platforms need)
+would duplicate what Flutter already does. This is a genuine platform difference, not an omission.
+
+## `TextFormField` wiring per field type
+
+```dart
+final _emailController = TextEditingController();
+
+TextFormField(
+  controller: _emailController,
+  decoration: const InputDecoration(labelText: 'Email'),
+  keyboardType: TextInputType.emailAddress,
+  validator: LoginValidators.email,
+),
+```
+
+| Field type | `keyboardType` | Other props |
+|---|---|---|
+| email | `TextInputType.emailAddress` | — |
+| password / confirmPassword | — | `obscureText: true` |
+| phone | `TextInputType.phone` | — |
+| otp | `TextInputType.number` | consider a max-length formatter (`LengthLimitingTextInputFormatter(6)`) |
+| number fields | `TextInputType.number` | — |
+| everything else | (default `TextInputType.text`) | — |
+
+Always dispose every `TextEditingController` in the widget's `dispose()` override — a controller
+leak is a common, easy-to-miss Flutter bug.
+
+## `call()`, not `execute()` — matches `clean-architecture-generator`'s Flutter convention
+
+If this project's use cases follow the `clean-architecture-generator` skill's Flutter pattern
+(a `call()` method instead of `execute()`), the validators generated here are unrelated — they are
+plain `String? Function(String?)` functions, not use-case classes, so there is no method-naming
+choice to make for them. Do not add a `call()` wrapper to a validator function.
+
+## confirmPassword / cross-field validation
+
+A validator function only receives its own field's value — it cannot see another field's value
+directly. Compare against the other field's live `TextEditingController` instead:
+
+```dart
+final _passwordController = TextEditingController();
+final _confirmPasswordController = TextEditingController();
+
+String? _confirmPasswordValidator(String? value) {
+  if (value == null || value.isEmpty) {
+    return ValidationMessages.requiredMsg('Confirm Password');
+  }
+  if (value != _passwordController.text) {
+    return ValidationMessages.passwordMatch;
+  }
+  return null;
+}
+
+// wiring:
+TextFormField(
+  controller: _confirmPasswordController,
+  obscureText: true,
+  decoration: const InputDecoration(labelText: 'Confirm Password'),
+  validator: _confirmPasswordValidator,
+),
+```
+
+This validator is hand-written (not generated), since it closes over a controller that belongs to
+the specific page — same spirit as the RN/React Yup `.oneOf()` addition and the Angular
+`FormGroup`-level validator, each adapted to what that platform can actually express.
+
+## Reusing the same validation on multiple pages
+
+```dart
+// login_page.dart
+TextFormField(controller: _emailController, validator: LoginValidators.email),
+
+// admin_login_page.dart
+TextFormField(controller: _emailController, validator: LoginValidators.email), // same validator, different page
+```
+
+## Page scaffold generator (optional)
+
+`generate-flutter.js` exports `generateScreen(projectRoot, pageName, schemaKey, pagePath, schemasRaw)`
+— writes a starter `[pageName].dart` (a `StatefulWidget` with a `GlobalKey<FormState>`, one
+`TextEditingController` per field, and a `TextFormField` wired to the matching validator method) for
+every field in the given schema. `pageName` must be snake_case, per Effective Dart's file-naming
+convention (see `clean-architecture-generator`'s Flutter platform file for the same rule applied to
+other artifact types). The generated class name is `pageName` converted to PascalCase, with no
+forced "Page" suffix — pass a name that already reflects it's a page (e.g. `login_page`) so the
+class name reads correctly (`LoginPage`), not doubled (`LoginPagePage`).

package/.github/skills/validation-engine-builder/references/platform-react-native.md

@@ -0,0 +1,170 @@
+# Platform File — React Native
+
+Read `core.md` first (field-type detection, regex/message/schema key tables, golden rules — all
+shared across platforms). This file covers only what's specific to wiring a React Native screen.
+
+---
+
+## Dependencies
+
+| Dependency | Role |
+|---|---|
+| `react-hook-form` | Form state + validation orchestration |
+| `@hookform/resolvers` | Bridges Yup schemas into react-hook-form's `resolver` |
+| `yup` | Schema definition — compiled from `templates/schemas.json` |
+
+Installed automatically by `scripts/install-deps.js` / `scripts/apply-to-project.js`, version-pinned
+by detected React Native version:
+
+| React Native | react-hook-form | @hookform/resolvers | yup |
+|---|---|---|---|
+| 0.80+ / React 19 | ^7.54.0 | ^3.9.0 | ^1.4.0 |
+| 0.73–0.79 | ^7.51.0 | ^3.4.0 | ^1.3.0 |
+| < 0.73 | ^7.43.0 | ^3.1.0 | ^1.0.0 |
+
+## Generated files
+
+`node scripts/apply-to-project.js --platform react-native` writes to `src/validation/`:
+
+| File | Role |
+|---|---|
+| `messages.ts` | `VALIDATION_MESSAGES` const + `msg` interpolation helpers |
+| `regex.ts` | `VALIDATION_REGEX` const |
+| `schemas.ts` | Yup object schemas, one per `templates/schemas.json` key |
+| `useValidatedForm.ts` | Typed react-hook-form wrapper (`mode: 'onBlur'`, `reValidateMode: 'onChange'`) |
+| `ValidationError.tsx` | `<Text>`-based error display component |
+
+The relative import path from a given screen file to `src/validation/` is computed from the real
+project structure by `generate-react-native.js` (`relativeImportPath()`), not hand-counted — if
+wiring a screen manually, compute it the same way (count directory levels from the screen file's
+own folder to `src/validation/`, not from a fixed assumption about screen depth).
+
+## Controller wiring template per field type
+
+Always use `Controller` from `react-hook-form` for every `TextInput` — React Native's `TextInput`
+does not integrate cleanly with `register()`-style uncontrolled refs the way a plain HTML `<input>`
+does (contrast with `platform-react.md`, where `register()` is preferred instead).
+
+### Email
+```tsx
+<Controller control={control} name="email"
+  render={({ field: { onChange, onBlur, value } }) => (
+    <View>
+      <TextInput
+        style={[styles.input, errors.email && styles.inputError]}
+        placeholder="Email"
+        keyboardType="email-address"
+        autoCapitalize="none"
+        onChangeText={onChange}
+        onBlur={onBlur}
+        value={value ?? ''}
+      />
+      <ValidationError message={errors.email?.message} />
+    </View>
+  )}
+/>
+```
+
+### Password
+```tsx
+<Controller control={control} name="password"
+  render={({ field: { onChange, onBlur, value } }) => (
+    <View>
+      <TextInput
+        style={[styles.input, errors.password && styles.inputError]}
+        placeholder="Password"
+        secureTextEntry={true}
+        onChangeText={onChange}
+        onBlur={onBlur}
+        value={value ?? ''}
+      />
+      <ValidationError message={errors.password?.message} />
+    </View>
+  )}
+/>
+```
+
+### Phone
+```tsx
+<Controller control={control} name="phone"
+  render={({ field: { onChange, onBlur, value } }) => (
+    <View>
+      <TextInput
+        style={[styles.input, errors.phone && styles.inputError]}
+        placeholder="Phone Number"
+        keyboardType="phone-pad"
+        onChangeText={onChange}
+        onBlur={onBlur}
+        value={value ?? ''}
+      />
+      <ValidationError message={errors.phone?.message} />
+    </View>
+  )}
+/>
+```
+
+### OTP
+```tsx
+<Controller control={control} name="otp"
+  render={({ field: { onChange, onBlur, value } }) => (
+    <View>
+      <TextInput
+        style={[styles.input, errors.otp && styles.inputError]}
+        placeholder="Enter OTP"
+        keyboardType="number-pad"
+        maxLength={6}
+        onChangeText={onChange}
+        onBlur={onBlur}
+        value={value ?? ''}
+      />
+      <ValidationError message={errors.otp?.message} />
+    </View>
+  )}
+/>
+```
+
+## confirmPassword cross-field validation
+
+This cannot be expressed in `schemas.json`. After regenerating, add directly to `schemas.ts`:
+
+```ts
+// cross-field — added after generation, re-add if regenerated
+confirmPassword: yup.string()
+  .required(msg.required('Confirm Password'))
+  .oneOf([yup.ref('password')], VALIDATION_MESSAGES.passwordMatch),
+```
+
+## Styles to add if not present
+
+```ts
+input: {
+  borderWidth: 1,
+  borderColor: '#D1D5DB',
+  borderRadius: 8,
+  paddingHorizontal: 16,
+  paddingVertical: 12,
+  fontSize: 16,
+  color: '#111827',
+  backgroundColor: '#F9FAFB',
+},
+inputError: {
+  borderColor: '#DC2626',
+},
+```
+
+## Reusing the same validation on multiple screens
+
+```ts
+// LoginScreen.tsx
+const form = useValidatedForm(schemas.login);
+
+// AdminLoginScreen.tsx
+const form = useValidatedForm(schemas.login);  // same schema, different screen
+```
+
+## Screen scaffold generator (optional)
+
+`generate-react-native.js` exports `generateScreen(projectRoot, screenName, schemaKey, screenPath, schemasRaw)`
+— writes a starter `[screenName]/[screenName].tsx` wired with `Controller` for every field in the
+given schema. Useful for a brand-new screen; for an existing screen, wire it by hand following the
+patterns above instead of overwriting the file.

package/.github/skills/validation-engine-builder/references/platform-react.md

@@ -0,0 +1,94 @@
+# Platform File — React (Web)
+
+Read `core.md` first. React web reuses the exact same `react-hook-form` + Yup engine as React
+Native (react-hook-form is a React library, not a React-Native-only one) — the only real
+differences are the DOM elements used and the wiring mechanism for native `<input>` elements.
+
+---
+
+## Dependencies
+
+Identical to React Native — see `platform-react-native.md`'s dependency table. There is no
+separate RN-version gate for web; `scripts/shared/npm-deps.js` applies the same "current" tier
+(`react-hook-form` ^7.54.0, `@hookform/resolvers` ^3.9.0, `yup` ^1.4.0) since there's no RN version
+to detect. Verify against npm if a long time has passed since this skill was last updated.
+
+## Generated files
+
+`node scripts/apply-to-project.js --platform react` writes to `src/validation/` — same 5 files,
+same shape, as React Native (`messages.ts`, `regex.ts`, `schemas.ts`, `useValidatedForm.ts`,
+`ValidationError.tsx`). Only `ValidationError.tsx` differs in content: it renders a plain `<span>`
+with an inline style object instead of RN's `<Text>` + `StyleSheet.create`, so it works with zero
+assumptions about the project's CSS setup. If the project uses CSS Modules, Tailwind, or
+styled-components, adapt `ValidationError`'s styling to match — its contract
+(`{ message?: string }` prop) stays the same either way.
+
+## Wiring native `<input>` — use `register()`, not `Controller`
+
+**This is the one real mechanical difference from React Native.** A plain HTML `<input>` exposes a
+real DOM ref, so react-hook-form's `register()` integrates directly — `Controller` is only needed
+for custom/controlled components that don't expose a compatible ref (which is exactly why React
+Native's `TextInput` needs `Controller` in `platform-react-native.md`). Do not port the `Controller`
+pattern to a native `<input>`; it adds unnecessary boilerplate.
+
+```tsx
+const {
+  register,
+  handleSubmit,
+  formState: { errors },
+} = useValidatedForm(schemas.login);
+
+<input
+  id="email"
+  type="email"
+  autoComplete="email"
+  {...register('email')}
+/>
+<ValidationError message={errors.email?.message} />
+```
+
+If the project's design system uses a custom input component that wraps a ref forwardable
+`<input>` (e.g. `<TextField ref={...} />`), `register()` still works as long as the component
+forwards its ref. Only fall back to `Controller` when the underlying component genuinely does not
+forward a usable ref (e.g. a fully controlled third-party component).
+
+### Per-field `type`/props
+
+| Field type | `type` attribute | Other props |
+|---|---|---|
+| email | `email` | `autoComplete="email"` |
+| password / confirmPassword | `password` | — |
+| phone / otp / numeric | `number` (or `text` with `inputMode="numeric"` if leading zeros matter) | `maxLength={6}` for otp |
+| url / website | `url` | — |
+| everything else | `text` | — |
+
+## confirmPassword cross-field validation
+
+Identical to React Native — see `platform-react-native.md`'s section. Same Yup `.oneOf()` addition
+to `schemas.ts`, since both platforms share the same generated `schemas.ts`.
+
+## Reusing the same validation on multiple pages
+
+```tsx
+// LoginPage.tsx
+const form = useValidatedForm(schemas.login);
+
+// AdminLoginPage.tsx
+const form = useValidatedForm(schemas.login);  // same schema, different page
+```
+
+## Page scaffold generator (optional)
+
+`generate-react.js` exports `generateScreen(projectRoot, pageName, schemaKey, pagePath, schemasRaw)`
+— writes a starter `[pageName]/[pageName].tsx` using `register()` for every field in the given
+schema, inside a plain `<form>`. Useful for a brand-new page; for an existing page, wire it by hand
+following the pattern above instead of overwriting the file.
+
+## Next.js / CRA / Vite notes
+
+The validation layer itself (`src/validation/`) does not depend on the bundler — only the page
+file's own env var access (if any) does. If the target project is Next.js, the page component
+still lives at `src/pages/[PageName]/[PageName].tsx` as generated; a thin Next.js route file
+(`app/[route]/page.tsx` or `pages/[route].tsx`) imports and renders it, matching the same
+"framework routing is a thin shell around a portable presentation component" approach used by
+`clean-architecture-generator`'s React web platform file.

package/.github/skills/validation-engine-builder/scripts/apply-to-project.js

@@ -0,0 +1,80 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * apply-to-project.js
+ * Detects the target project's platform, installs compatible dependencies
+ * (React Native / React only — Angular and Flutter need none), and
+ * regenerates the platform's validation output files from the skill's
+ * shared templates.
+ *
+ * The AI handles screen/page/component analysis and wiring — this script
+ * handles only platform detection, dependency management, and file generation.
+ *
+ * Usage:
+ *   node .github/skills/validation-engine-builder/scripts/apply-to-project.js
+ *   node .github/skills/validation-engine-builder/scripts/apply-to-project.js --projectPath MyApp
+ *   node .github/skills/validation-engine-builder/scripts/apply-to-project.js --platform angular
+ *   node .github/skills/validation-engine-builder/scripts/apply-to-project.js --skipInstall
+ */
+
+const path = require('path');
+
+const { detectPlatform } = require('./shared/detect-platform.js');
+const { ensureDeps }     = require('./shared/npm-deps.js');
+
+const GENERATORS = {
+  'react-native': './generate-react-native.js',
+  'react':        './generate-react.js',
+  'angular':      './generate-angular.js',
+  'flutter':      './generate-flutter.js',
+};
+
+function parseArgs(argv) {
+  const parsed = {};
+  for (let i = 0; i < argv.length; i++) {
+    const token = argv[i];
+    if (!token.startsWith('--')) continue;
+    const key  = token.slice(2);
+    const next = argv[i + 1];
+    if (!next || next.startsWith('--')) { parsed[key] = true; continue; }
+    parsed[key] = next;
+    i++;
+  }
+  return parsed;
+}
+
+function main() {
+  const args        = parseArgs(process.argv.slice(2));
+  const projectRoot = args.projectPath ? path.resolve(args.projectPath) : process.cwd();
+
+  if (args.screenName || args.schema) {
+    console.log('  Note: --screenName and --schema are no longer supported.');
+    console.log('  Screen/page/component wiring is done by the AI agent, not this script.\n');
+  }
+
+  const platform = args.platform || detectPlatform(projectRoot);
+
+  if (!platform || !GENERATORS[platform]) {
+    console.error('\nERROR: Could not determine the target platform.');
+    console.error('  Detected neither pubspec.yaml (Flutter), angular.json (Angular), nor a');
+    console.error('  react-native/react dependency in package.json.');
+    console.error('  Re-run with --platform <react-native|react|angular|flutter> once the');
+    console.error('  platform has been confirmed with the user.');
+    process.exit(1);
+  }
+
+  console.log('\nValidation Engine — generating validation output');
+  console.log(`  Project  : ${projectRoot}`);
+  console.log(`  Platform : ${platform}${args.platform ? ' (explicit override)' : ' (detected)'}\n`);
+
+  ensureDeps(projectRoot, platform, { skipInstall: !!args.skipInstall });
+
+  const { generate } = require(GENERATORS[platform]);
+  generate(projectRoot);
+
+  console.log('\nDone. Edit templates/messages.json, templates/regex.json, or templates/schemas.json');
+  console.log('and re-run this script to regenerate — never edit the generated output directly.\n');
+}
+
+main();