@mars-stack/cli 0.2.0 → 1.0.2

package/template/scripts/update-quality-score.ts

@@ -0,0 +1,263 @@
+/**
+ * Scans each feature directory and updates docs/QUALITY_SCORE.md.
+ *
+ * For each feature in src/features/, checks:
+ * - Has server functions (files in server/)
+ * - Has types (*.types.ts, types.ts, or types/)
+ * - Has tests (*.test.ts, *.spec.ts, or __tests__/)
+ * - Has API routes (corresponding routes in src/app/api/)
+ *
+ * Grading:
+ * - A: All present + tests passing (test files exist with assertions)
+ * - B: All four categories present
+ * - C: Partial (2-3 categories)
+ * - D: Scaffold only (1 category)
+ * - F: Missing (0 categories)
+ *
+ * Usage: tsx scripts/update-quality-score.ts
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+
+const ROOT = path.resolve(__dirname, '..');
+const FEATURES_DIR = path.join(ROOT, 'src', 'features');
+const API_DIR = path.join(ROOT, 'src', 'app', 'api');
+const QUALITY_SCORE_PATH = path.join(ROOT, 'docs', 'QUALITY_SCORE.md');
+
+type Grade = 'A' | 'B' | 'C' | 'D' | 'F';
+
+interface FeatureAssessment {
+  name: string;
+  hasServer: boolean;
+  hasTypes: boolean;
+  hasTests: boolean;
+  hasApiRoutes: boolean;
+  grade: Grade;
+  notes: string;
+}
+
+function collectFilesRecursive(dir: string): string[] {
+  const results: string[] = [];
+  if (!fs.existsSync(dir)) return results;
+
+  const entries = fs.readdirSync(dir, { withFileTypes: true });
+  for (const entry of entries) {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      results.push(...collectFilesRecursive(full));
+    } else {
+      results.push(full);
+    }
+  }
+  return results;
+}
+
+function hasServerFunctions(featureDir: string): boolean {
+  const serverDir = path.join(featureDir, 'server');
+  if (!fs.existsSync(serverDir)) return false;
+
+  const files = collectFilesRecursive(serverDir);
+  return files.some((f) => f.endsWith('.ts') || f.endsWith('.tsx'));
+}
+
+function hasTypeDefinitions(featureDir: string): boolean {
+  const files = collectFilesRecursive(featureDir);
+  return files.some((f) => {
+    const basename = path.basename(f);
+    return (
+      basename === 'types.ts' ||
+      basename === 'types.tsx' ||
+      basename.endsWith('.types.ts') ||
+      basename.endsWith('.types.tsx')
+    );
+  });
+}
+
+function hasTestFiles(featureDir: string): boolean {
+  const files = collectFilesRecursive(featureDir);
+  const hasDirectTests = files.some((f) => {
+    const basename = path.basename(f);
+    return basename.endsWith('.test.ts') || basename.endsWith('.spec.ts') ||
+           basename.endsWith('.test.tsx') || basename.endsWith('.spec.tsx');
+  });
+
+  if (hasDirectTests) return true;
+
+  const testDir = path.join(featureDir, '__tests__');
+  if (fs.existsSync(testDir)) {
+    const testFiles = collectFilesRecursive(testDir);
+    return testFiles.some((f) => f.endsWith('.ts') || f.endsWith('.tsx'));
+  }
+
+  return false;
+}
+
+function hasApiRoutes(featureName: string): boolean {
+  const protectedDir = path.join(API_DIR, 'protected', featureName);
+  const publicDir = path.join(API_DIR, featureName);
+
+  function hasRouteFile(dir: string): boolean {
+    if (!fs.existsSync(dir)) return false;
+    const files = collectFilesRecursive(dir);
+    return files.some((f) => path.basename(f) === 'route.ts' || path.basename(f) === 'route.tsx');
+  }
+
+  return hasRouteFile(protectedDir) || hasRouteFile(publicDir);
+}
+
+function testsHaveAssertions(featureDir: string): boolean {
+  const files = collectFilesRecursive(featureDir);
+  const testFiles = files.filter((f) => {
+    const basename = path.basename(f);
+    return basename.endsWith('.test.ts') || basename.endsWith('.spec.ts') ||
+           basename.endsWith('.test.tsx') || basename.endsWith('.spec.tsx');
+  });
+
+  for (const testFile of testFiles) {
+    const content = fs.readFileSync(testFile, 'utf-8');
+    if (content.includes('expect(') || content.includes('assert(') || content.includes('assert.')) {
+      return true;
+    }
+  }
+
+  return false;
+}
+
+function computeGrade(assessment: FeatureAssessment): Grade {
+  const presentCount = [
+    assessment.hasServer,
+    assessment.hasTypes,
+    assessment.hasTests,
+    assessment.hasApiRoutes,
+  ].filter(Boolean).length;
+
+  if (presentCount === 0) return 'F';
+  if (presentCount === 1) return 'D';
+  if (presentCount < 4) return 'C';
+
+  if (assessment.hasTests && testsHaveAssertions(path.join(FEATURES_DIR, assessment.name))) {
+    return 'A';
+  }
+
+  return 'B';
+}
+
+function buildNotes(assessment: FeatureAssessment): string {
+  const present: string[] = [];
+  const missing: string[] = [];
+
+  if (assessment.hasServer) present.push('server'); else missing.push('server');
+  if (assessment.hasTypes) present.push('types'); else missing.push('types');
+  if (assessment.hasTests) present.push('tests'); else missing.push('tests');
+  if (assessment.hasApiRoutes) present.push('api routes'); else missing.push('api routes');
+
+  const parts: string[] = [];
+  if (present.length > 0) parts.push(`Has: ${present.join(', ')}`);
+  if (missing.length > 0) parts.push(`Missing: ${missing.join(', ')}`);
+
+  return parts.join('. ');
+}
+
+function assessFeature(featureName: string): FeatureAssessment {
+  const featureDir = path.join(FEATURES_DIR, featureName);
+
+  const assessment: FeatureAssessment = {
+    name: featureName,
+    hasServer: hasServerFunctions(featureDir),
+    hasTypes: hasTypeDefinitions(featureDir),
+    hasTests: hasTestFiles(featureName),
+    hasApiRoutes: hasApiRoutes(featureName),
+    grade: 'F',
+    notes: '',
+  };
+
+  assessment.grade = computeGrade(assessment);
+  assessment.notes = buildNotes(assessment);
+
+  return assessment;
+}
+
+function generateMarkdownSection(assessments: FeatureAssessment[]): string {
+  const lines: string[] = [
+    '## Feature Quality (Auto-Generated)',
+    '',
+    '> Auto-generated by `yarn update:quality`. Do not edit manually.',
+    '',
+    '| Feature | Grade | Server | Types | Tests | API Routes | Notes |',
+    '|---------|-------|--------|-------|-------|------------|-------|',
+  ];
+
+  for (const a of assessments) {
+    const check = (v: boolean): string => v ? 'Yes' : 'No';
+    lines.push(
+      `| ${a.name} | ${a.grade} | ${check(a.hasServer)} | ${check(a.hasTypes)} | ${check(a.hasTests)} | ${check(a.hasApiRoutes)} | ${a.notes} |`,
+    );
+  }
+
+  lines.push('');
+  return lines.join('\n');
+}
+
+function updateQualityScoreFile(newSection: string): void {
+  const docsDir = path.dirname(QUALITY_SCORE_PATH);
+  if (!fs.existsSync(docsDir)) {
+    fs.mkdirSync(docsDir, { recursive: true });
+  }
+
+  if (!fs.existsSync(QUALITY_SCORE_PATH)) {
+    fs.writeFileSync(QUALITY_SCORE_PATH, `# Quality Score\n\n${newSection}`);
+    return;
+  }
+
+  const content = fs.readFileSync(QUALITY_SCORE_PATH, 'utf-8');
+
+  const sectionStart = content.indexOf('## Feature Quality (Auto-Generated)');
+  if (sectionStart === -1) {
+    fs.writeFileSync(QUALITY_SCORE_PATH, content.trimEnd() + '\n\n' + newSection);
+    return;
+  }
+
+  const nextSectionMatch = content.slice(sectionStart + 1).match(/\n## [^#]/);
+  const sectionEnd = nextSectionMatch
+    ? sectionStart + 1 + nextSectionMatch.index!
+    : content.length;
+
+  const updated = content.slice(0, sectionStart) + newSection + content.slice(sectionEnd);
+  fs.writeFileSync(QUALITY_SCORE_PATH, updated);
+}
+
+function main(): void {
+  console.log('Scanning features and updating quality scores...\n');
+
+  if (!fs.existsSync(FEATURES_DIR)) {
+    console.log('No features directory found at src/features/. Nothing to scan.');
+    process.exit(0);
+  }
+
+  const featureNames = fs
+    .readdirSync(FEATURES_DIR, { withFileTypes: true })
+    .filter((e) => e.isDirectory())
+    .map((e) => e.name)
+    .sort();
+
+  if (featureNames.length === 0) {
+    console.log('No features found in src/features/.');
+    process.exit(0);
+  }
+
+  const assessments = featureNames.map(assessFeature);
+
+  console.log('Feature Assessment Results:\n');
+  for (const a of assessments) {
+    const icon = a.grade === 'A' ? '+' : a.grade === 'F' ? '!' : '-';
+    console.log(`  [${icon}] ${a.name}: ${a.grade} — ${a.notes}`);
+  }
+
+  const newSection = generateMarkdownSection(assessments);
+  updateQualityScoreFile(newSection);
+
+  console.log(`\nUpdated ${path.relative(ROOT, QUALITY_SCORE_PATH)}`);
+}
+
+main();

package/template/src/__tests__/architecture.test.ts

@@ -0,0 +1,114 @@
+/**
+ * Structural tests that validate architecture invariants.
+ * These tests scan the codebase and assert that architectural rules are followed.
+ */
+
+import { describe, it, expect } from 'vitest';
+import * as fs from 'fs';
+import * as path from 'path';
+
+const SRC_DIR = path.resolve(__dirname, '..');
+
+function getAllFiles(dir: string, extensions: string[]): string[] {
+  const results: string[] = [];
+  if (!fs.existsSync(dir)) return results;
+
+  const entries = fs.readdirSync(dir, { withFileTypes: true });
+  for (const entry of entries) {
+    const fullPath = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      if (entry.name === 'node_modules' || entry.name === '.next' || entry.name === 'dist') continue;
+      results.push(...getAllFiles(fullPath, extensions));
+    } else if (extensions.some((ext) => entry.name.endsWith(ext))) {
+      results.push(fullPath);
+    }
+  }
+  return results;
+}
+
+describe('Architecture: Dependency Direction', () => {
+  it('features do not import from other features', () => {
+    const featuresDir = path.join(SRC_DIR, 'features');
+    if (!fs.existsSync(featuresDir)) return;
+
+    const featureDirs = fs
+      .readdirSync(featuresDir, { withFileTypes: true })
+      .filter((d) => d.isDirectory())
+      .map((d) => d.name);
+
+    const violations: string[] = [];
+
+    for (const feature of featureDirs) {
+      const featureDir = path.join(featuresDir, feature);
+      const files = getAllFiles(featureDir, ['.ts', '.tsx']);
+
+      for (const file of files) {
+        const content = fs.readFileSync(file, 'utf-8');
+        const importMatches = content.matchAll(
+          /(?:import|from)\s+['"](?:@\/|\.\.\/.*\/)features\/([^/'"\s]+)/g
+        );
+
+        for (const match of importMatches) {
+          const importedFeature = match[1];
+          if (importedFeature !== feature) {
+            const relPath = path.relative(SRC_DIR, file);
+            violations.push(
+              `${relPath} imports from features/${importedFeature} (cross-feature import)`
+            );
+          }
+        }
+      }
+    }
+
+    expect(violations).toEqual([]);
+  });
+});
+
+describe('Architecture: API Auth Coverage', () => {
+  it('all routes in api/protected/ use auth middleware', () => {
+    const protectedDir = path.join(SRC_DIR, 'app', 'api', 'protected');
+    if (!fs.existsSync(protectedDir)) return;
+
+    const routeFiles = getAllFiles(protectedDir, ['.ts', '.tsx']).filter(
+      (f) => path.basename(f).startsWith('route.')
+    );
+
+    const unprotected: string[] = [];
+
+    for (const file of routeFiles) {
+      const content = fs.readFileSync(file, 'utf-8');
+      const hasAuth =
+        content.includes('withAuth') ||
+        content.includes('withRole') ||
+        content.includes('withOwnership');
+
+      if (!hasAuth) {
+        unprotected.push(path.relative(SRC_DIR, file));
+      }
+    }
+
+    expect(unprotected).toEqual([]);
+  });
+});
+
+describe('Architecture: Server-Only Boundary', () => {
+  it('files in server/ directories import "server-only"', () => {
+    const files = getAllFiles(SRC_DIR, ['.ts', '.tsx']).filter(
+      (f) =>
+        f.includes('/server/') &&
+        !f.includes('.test.') &&
+        !f.includes('node_modules')
+    );
+
+    const missing: string[] = [];
+
+    for (const file of files) {
+      const content = fs.readFileSync(file, 'utf-8');
+      if (!content.includes("import 'server-only'") && !content.includes('import "server-only"')) {
+        missing.push(path.relative(SRC_DIR, file));
+      }
+    }
+
+    expect(missing).toEqual([]);
+  });
+});

package/template/src/app/(auth)/forgotten-password/page.tsx

@@ -0,0 +1,92 @@
+'use client';
+
+import { useCSRF } from '@mars-stack/core/auth/hooks';
+import { formSchemas } from '@mars-stack/core/auth/validation';
+import { useZodForm } from '@mars-stack/ui/hooks';
+import { Button, Input, Text } from '@mars-stack/ui';
+import Link from 'next/link';
+import { routes } from '@/config/routes';
+import { useState } from 'react';
+
+export default function ForgottenPassword() {
+  const { getCSRFHeaders } = useCSRF();
+  const [serverError, setServerError] = useState('');
+  const [success, setSuccess] = useState(false);
+
+  const form = useZodForm({
+    schema: formSchemas.forgotPassword,
+    initialValues: { email: '' },
+    mode: 'onBlur',
+  });
+
+  const handleSubmit = form.handleSubmit(async (values) => {
+    setServerError('');
+    try {
+      const response = await fetch('/api/auth/forgot', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json', ...getCSRFHeaders() },
+        body: JSON.stringify(values),
+      });
+
+      if (!response.ok) {
+        const data = await response.json();
+        setServerError(data.error || 'Failed to send reset email');
+        return;
+      }
+
+      setSuccess(true);
+    } catch {
+      setServerError('Network error. Please try again.');
+    }
+  });
+
+  if (success) {
+    return (
+      <div className="text-center">
+        <Text.H3 as="h2">Check your email</Text.H3>
+        <Text.Paragraph>
+          If an account exists for that email, we&apos;ve sent password reset instructions.
+        </Text.Paragraph>
+        <Link href={routes.signIn} className="mt-6 inline-block text-sm text-text-link hover:text-text-link-hover hover:underline">
+          Back to sign in
+        </Link>
+      </div>
+    );
+  }
+
+  return (
+    <>
+      <div>
+        <Text.H3 as="h2">Reset your password</Text.H3>
+        <Text.Paragraph className="text-sm">
+          Enter your email address and we&apos;ll send you a link to reset your password.
+        </Text.Paragraph>
+      </div>
+
+      <form className="mt-8 space-y-6" onSubmit={handleSubmit}>
+        {serverError && (
+          <div className="rounded-md bg-error-muted p-3 text-sm text-text-error">{serverError}</div>
+        )}
+
+        <Input
+          {...form.getFieldProps('email')}
+          label="Email Address"
+          type="email"
+          placeholder="you@example.com"
+          fullWidth
+          required
+        />
+
+        <Button type="submit" disabled={form.isSubmitting || !form.isValid} fullWidth loading={form.isSubmitting}>
+          {form.isSubmitting ? 'Sending...' : 'Send reset link'}
+        </Button>
+      </form>
+
+      <div className="mt-4 text-center">
+        <Link href={routes.signIn} className="text-sm text-text-link hover:text-text-link-hover hover:underline">
+          Back to sign in
+        </Link>
+      </div>
+    </>
+  );
+}

package/template/src/app/(auth)/layout.tsx

@@ -0,0 +1,11 @@
+import { Card } from '@mars-stack/ui';
+
+export default function AuthLayout({ children }: Readonly<{ children: React.ReactNode }>) {
+  return (
+    <div className="flex min-h-screen items-start justify-center bg-surface-background px-4 py-8 sm:px-6 lg:px-8">
+      <Card className="w-full max-w-md space-y-8" padding="lg">
+        {children}
+      </Card>
+    </div>
+  );
+}

package/template/src/app/(auth)/register/page.tsx

@@ -0,0 +1,162 @@
+'use client';
+
+import { useAuth } from '@/features/auth/context/AuthContext';
+import { useCSRF, usePasswordStrength } from '@mars-stack/core/auth/hooks';
+import { formSchemas, type SignupFormData } from '@mars-stack/core/auth/validation';
+import { routes } from '@/config/routes';
+import { useZodForm } from '@mars-stack/ui/hooks';
+import { Button, Checkbox, Input, Spinner, Text, PasswordStrengthIndicator } from '@mars-stack/ui';
+import Link from 'next/link';
+import { useRouter } from 'next/navigation';
+import { Suspense, useEffect, useState } from 'react';
+
+function SignUpForm() {
+  const router = useRouter();
+  const { isAuthenticated, isLoading } = useAuth();
+  const { getCSRFHeaders, getCSRFFormData } = useCSRF();
+  const [serverError, setServerError] = useState('');
+
+  useEffect(() => {
+    if (!isLoading && isAuthenticated) router.push(routes.dashboard);
+  }, [isAuthenticated, isLoading, router]);
+
+  const form = useZodForm({
+    schema: formSchemas.signup,
+    initialValues: {
+      name: '',
+      email: '',
+      password: '',
+      confirmPassword: '',
+      termsAccepted: false,
+      marketingOptIn: false,
+    },
+    mode: 'onBlur',
+  });
+
+  const passwordStrength = usePasswordStrength(form.values.password);
+
+  const handleSubmit = form.handleSubmit(async (values: SignupFormData) => {
+    setServerError('');
+    try {
+      const response = await fetch('/api/auth/signup', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json', ...getCSRFHeaders() },
+        body: JSON.stringify({ ...values, ...getCSRFFormData() }),
+      });
+
+      const data = await response.json();
+
+      if (!response.ok) {
+        setServerError(data.error || 'Failed to create account');
+        return;
+      }
+
+      sessionStorage.setItem('verify-email', values.email);
+      router.push('/verify');
+    } catch {
+      setServerError('Network error. Please try again.');
+    }
+  });
+
+  if (isLoading) return <Spinner size="md" />;
+  if (isAuthenticated) return <Text.Paragraph>Redirecting...</Text.Paragraph>;
+
+  return (
+    <>
+      <div>
+        <Text.H3 as="h2">Create your account</Text.H3>
+        <Text.Paragraph className="text-sm">
+          Already have an account?{' '}
+          <Link href={routes.signIn} className="text-text-link hover:text-text-link-hover hover:underline">
+            Sign in
+          </Link>
+        </Text.Paragraph>
+      </div>
+
+      <form className="mt-8 space-y-6" onSubmit={handleSubmit}>
+        {serverError && (
+          <div className="rounded-md bg-error-muted p-3 text-sm text-text-error">{serverError}</div>
+        )}
+
+        <div className="space-y-4">
+          <Input
+            {...form.getFieldProps('name')}
+            label="Full Name"
+            type="text"
+            placeholder="John Doe"
+            fullWidth
+            required
+          />
+          <Input
+            {...form.getFieldProps('email')}
+            label="Email Address"
+            type="email"
+            placeholder="you@example.com"
+            fullWidth
+            required
+          />
+          <Input
+            {...form.getFieldProps('password')}
+            label="Password"
+            type="password"
+            placeholder="Create a strong password"
+            showPasswordToggle
+            fullWidth
+            required
+          />
+          {form.values.password && (
+            <PasswordStrengthIndicator
+              strength={passwordStrength.strength}
+              requirements={passwordStrength.requirements}
+            />
+          )}
+          <Input
+            {...form.getFieldProps('confirmPassword')}
+            label="Confirm Password"
+            type="password"
+            placeholder="Re-enter your password"
+            fullWidth
+            required
+          />
+
+          <div className="space-y-3">
+            <Checkbox
+              checked={form.values.termsAccepted}
+              onChange={(e) => form.setValue('termsAccepted', (e.target as HTMLInputElement).checked)}
+              required
+              label={
+                <span>
+                  I agree to the{' '}
+                  <Link href="/terms" className="text-text-link hover:underline">
+                    Terms of Service
+                  </Link>{' '}
+                  and{' '}
+                  <Link href="/privacy" className="text-text-link hover:underline">
+                    Privacy Policy
+                  </Link>
+                </span>
+              }
+            />
+            <Checkbox
+              checked={form.values.marketingOptIn}
+              onChange={(e) => form.setValue('marketingOptIn', (e.target as HTMLInputElement).checked)}
+              label="I would like to receive product updates and marketing emails"
+            />
+          </div>
+        </div>
+
+        <Button type="submit" disabled={form.isSubmitting || !form.isValid} fullWidth loading={form.isSubmitting}>
+          {form.isSubmitting ? 'Creating account...' : 'Create account'}
+        </Button>
+      </form>
+    </>
+  );
+}
+
+export default function Register() {
+  return (
+    <Suspense fallback={<Spinner size="md" />}>
+      <SignUpForm />
+    </Suspense>
+  );
+}