reflection-check 0.0.2 → 0.0.3

package/dist/core/report-schema.d.ts

@@ -27,8 +27,8 @@ export declare const ReportStatusSchema: z.ZodEnum<{
     "pass-with-review": "pass-with-review";
 }>;
 export declare const ArtifactTypeSchema: z.ZodEnum<{
-    report: "report";
     screenshot: "screenshot";
+    report: "report";
     image: "image";
     "visual-diff": "visual-diff";
     trace: "trace";
@@ -37,8 +37,8 @@ export declare const ArtifactTypeSchema: z.ZodEnum<{
     metadata: "metadata";
 }>;
 export declare const ArtifactRoleSchema: z.ZodEnum<{
-    trace: "trace";
     expected: "expected";
+    trace: "trace";
     evidence: "evidence";
     actual: "actual";
     diff: "diff";
@@ -46,8 +46,8 @@ export declare const ArtifactRoleSchema: z.ZodEnum<{
 }>;
 export declare const ArtifactRefSchema: z.ZodObject<{
     type: z.ZodEnum<{
-        report: "report";
         screenshot: "screenshot";
+        report: "report";
         image: "image";
         "visual-diff": "visual-diff";
         trace: "trace";
@@ -56,8 +56,8 @@ export declare const ArtifactRefSchema: z.ZodObject<{
         metadata: "metadata";
     }>;
     role: z.ZodOptional<z.ZodEnum<{
-        trace: "trace";
         expected: "expected";
+        trace: "trace";
         evidence: "evidence";
         actual: "actual";
         diff: "diff";
@@ -93,8 +93,8 @@ export declare const CheckResultSchema: z.ZodObject<{
     details: z.ZodOptional<z.ZodString>;
     artifacts: z.ZodArray<z.ZodObject<{
         type: z.ZodEnum<{
-            report: "report";
             screenshot: "screenshot";
+            report: "report";
             image: "image";
             "visual-diff": "visual-diff";
             trace: "trace";
@@ -103,8 +103,8 @@ export declare const CheckResultSchema: z.ZodObject<{
             metadata: "metadata";
         }>;
         role: z.ZodOptional<z.ZodEnum<{
-            trace: "trace";
             expected: "expected";
+            trace: "trace";
             evidence: "evidence";
             actual: "actual";
             diff: "diff";
@@ -183,8 +183,8 @@ export declare const ReflectionReportSchema: z.ZodObject<{
         details: z.ZodOptional<z.ZodString>;
         artifacts: z.ZodArray<z.ZodObject<{
             type: z.ZodEnum<{
-                report: "report";
                 screenshot: "screenshot";
+                report: "report";
                 image: "image";
                 "visual-diff": "visual-diff";
                 trace: "trace";
@@ -193,8 +193,8 @@ export declare const ReflectionReportSchema: z.ZodObject<{
                 metadata: "metadata";
             }>;
             role: z.ZodOptional<z.ZodEnum<{
-                trace: "trace";
                 expected: "expected";
+                trace: "trace";
                 evidence: "evidence";
                 actual: "actual";
                 diff: "diff";
@@ -209,8 +209,8 @@ export declare const ReflectionReportSchema: z.ZodObject<{
     }, z.core.$strip>>;
     artifacts: z.ZodArray<z.ZodObject<{
         type: z.ZodEnum<{
-            report: "report";
             screenshot: "screenshot";
+            report: "report";
             image: "image";
             "visual-diff": "visual-diff";
             trace: "trace";
@@ -219,8 +219,8 @@ export declare const ReflectionReportSchema: z.ZodObject<{
             metadata: "metadata";
         }>;
         role: z.ZodOptional<z.ZodEnum<{
-            trace: "trace";
             expected: "expected";
+            trace: "trace";
             evidence: "evidence";
             actual: "actual";
             diff: "diff";
@@ -247,6 +247,7 @@ export type SuggestedNextStep = z.output<typeof SuggestedNextStepSchema>;
 export declare function summarizeChecks(checks: CheckResult[]): ReportSummary;
 export declare function deriveReportStatus(checks: CheckResult[]): ReportStatus;
 export declare function deriveExitCode(status: ReportStatus): ExitCode;
+export declare function deriveSuggestedNextSteps(checks: CheckResult[]): SuggestedNextStep[];
 export declare function validateReport(report: unknown): ReflectionReport;
 export declare function createReport(input: {
     runId: string;

package/dist/core/report-schema.js

@@ -83,6 +83,45 @@ export function deriveExitCode(status) {
     }
     return ExitCode.Success;
 }
+export function deriveSuggestedNextSteps(checks) {
+    const blockingFailures = checks.filter((check) => check.severity === 'blocking' && (check.status === 'fail' || check.status === 'error'));
+    if (blockingFailures.length > 0) {
+        return [
+            {
+                kind: 'fix',
+                summary: `Fix blocking checks before updating baselines: ${formatCheckList(blockingFailures)}.`
+            }
+        ];
+    }
+    const missingBaselines = checks.filter((check) => check.suite === 'visual' && check.severity === 'review' && check.metadata.classification === 'missing-baseline');
+    if (missingBaselines.length > 0) {
+        return [
+            {
+                kind: 'baseline',
+                summary: 'Review actual screenshots for missing baselines, then run `reflection update --dry-run --case <caseId> --from-run latest` for intentional first baselines.'
+            }
+        ];
+    }
+    const visualReviewItems = checks.filter((check) => check.suite === 'visual' && check.severity === 'review' && (check.status === 'warn' || check.status === 'fail'));
+    if (visualReviewItems.length > 0) {
+        return [
+            {
+                kind: 'review',
+                summary: 'Inspect review-only visual artifacts, then run `reflection update --dry-run --case <caseId> --from-run latest` for intentional route visual changes.'
+            }
+        ];
+    }
+    const reviewItems = checks.filter((check) => check.severity === 'review' && (check.status === 'warn' || check.status === 'fail'));
+    if (reviewItems.length > 0) {
+        return [
+            {
+                kind: 'review',
+                summary: `Inspect review-only checks: ${formatCheckList(reviewItems)}.`
+            }
+        ];
+    }
+    return [{ kind: 'pass', summary: 'No action required; expand route or visual coverage when useful.' }];
+}
 export function validateReport(report) {
     const parsed = ReflectionReportSchema.safeParse(report);
     if (!parsed.success) {
@@ -106,7 +145,14 @@ export function createReport(input) {
         summary: summarizeChecks(input.checks),
         checks: input.checks,
         artifacts: input.artifacts ?? [],
-        suggestedNextSteps: input.suggestedNextSteps ?? []
+        suggestedNextSteps: input.suggestedNextSteps ?? deriveSuggestedNextSteps(input.checks)
     });
 }
+function formatCheckList(checks) {
+    const ids = checks.map((check) => check.id);
+    if (ids.length <= 3) {
+        return ids.join(', ');
+    }
+    return `${ids.slice(0, 3).join(', ')} and ${ids.length - 3} more`;
+}
 //# sourceMappingURL=report-schema.js.map

package/dist/core/report-schema.js.map

@@ -1 +1 @@
-{"version":3,"file":"report-schema.js","sourceRoot":"","sources":["../../src/core/report-schema.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"report-schema.js","sourceRoot":"","sources":["../../src/core/report-schema.ts"],"names":[],"mappings":"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"}

package/docs/agent-workflows.md

@@ -7,21 +7,29 @@ Reflection is meant to give agents an evidence gate for rendered UI work. Agents
 Before claiming frontend work is complete:
 
 ```bash
-reflection doctor
+reflection doctor --config reflection.config.ts
 reflection run --config reflection.config.ts --mode smoke
 reflection review --json
 ```
 
-`reflection doctor` is currently a lightweight setup check. Treat `reflection run --config ...` as the command that exercises project contracts.
+`reflection doctor --config` validates config loading/schema, summarizes enabled contracts and server settings, checks local runtime readiness, and remains read-only.
 
 If the project uses a non-default config path or report root, pass it explicitly:
 
 ```bash
-reflection doctor
+reflection doctor --config path/to/reflection.config.ts
 reflection run --config path/to/reflection.config.ts --mode smoke --report-dir .reflection
 reflection review --report-dir .reflection --json
 ```
 
+For first-time setup discovery, agents may run the read-only preview:
+
+```bash
+reflection init --dry-run --preset vite-react
+```
+
+The init command currently previews proposed config and scripts only. Do not assume it wrote files, and do not run any future write mode without explicit human approval.
+
 ## How to interpret review JSON
 
 Treat the review summary as the handoff contract:
@@ -100,7 +108,7 @@ Use Reflection as the UI evidence gate before claiming frontend work is complete
 Run:
 
 ```bash
-reflection doctor
+reflection doctor --config reflection.config.ts
 reflection run --config reflection.config.ts --mode smoke
 reflection review --json
 ```
@@ -121,7 +129,7 @@ Full protocol: `docs/validation-process.md`.
 CI should run Reflection and upload artifacts, but never update baselines:
 
 ```bash
-reflection doctor
+reflection doctor --config reflection.config.ts
 reflection run --ci --config reflection.config.ts --mode smoke
 reflection review --report-dir artifacts/reflection --json
 ```

package/docs/browser-contract.md

@@ -30,12 +30,22 @@ browser: {
     reuseExisting: true,
     timeoutMs: 60_000
   },
+  setup: {
+    localStorage: {
+      'reflection:test-mode': 'enabled'
+    }
+  },
   maskSelectors: ['[data-reflection-mask]'],
   routes: [
     {
       id: 'login',
       path: '/login',
       viewports: ['desktop', 'mobile'],
+      setup: {
+        sessionStorage: {
+          'reflection:login-state': 'ready'
+        }
+      },
       expects: [
         { role: 'heading', name: 'Login' },
         { label: 'Email' },
@@ -51,6 +61,27 @@ browser: {
 }
 ```
 
+## Route setup for authenticated fixtures
+
+Use `setup.localStorage` and `setup.sessionStorage` to seed non-secret test state before Reflection navigates to a route:
+
+```ts
+routes: [
+  {
+    id: 'authenticated-home',
+    path: '/',
+    setup: {
+      localStorage: {
+        'reflection:test-user': 'fixture-user'
+      }
+    },
+    expects: [{ text: 'Welcome fixture-user' }]
+  }
+]
+```
+
+Browser-level setup applies to every route, and route-level setup extends or overrides it. Reflection records only setup key names in metadata so reports show that setup ran without logging values. Keep real credentials and production session values out of committed config; prefer test-mode auth or mock fixture tokens.
+
 ## Expectations
 
 | Expectation | Use for |

package/docs/ci.md

@@ -4,8 +4,18 @@ Reflection is designed to be safe in CI: runs create evidence artifacts, but the
 
 ## Recommended command
 
+Install Reflection in the consuming repository:
+
+```bash
+pnpm add -D reflection-check
+```
+
+Then run the CI evidence loop:
+
 ```bash
+reflection doctor --config reflection.config.ts
 reflection run --ci --config reflection.config.ts --mode smoke
+reflection review --report-dir artifacts/reflection --json
 ```
 
 When `--ci` is enabled and `--report-dir` is not provided, Reflection writes artifacts to:
@@ -41,4 +51,4 @@ artifacts/reflection/runs/latest
 
 ## GitHub Actions example
 
-See `.github/workflows/reflection.yml` for a repo-owned example that installs dependencies, builds Reflection, runs `reflection run --ci`, and uploads `artifacts/reflection` for review.
+See `.github/workflows/reflection.yml` for a repo-owned example that installs dependencies, builds Reflection, runs `reflection run --ci`, reviews `artifacts/reflection`, and uploads the report root for inspection.

package/docs/configuration.md

@@ -59,6 +59,11 @@ browser: {
     reuseExisting: true,
     timeoutMs: 60_000
   },
+  setup: {
+    localStorage: {
+      'reflection:test-mode': 'enabled'
+    }
+  },
   maskSelectors: ['[data-reflection-mask]'],
   routes: [
     {
@@ -66,6 +71,11 @@ browser: {
       name: 'Home route',
       path: '/',
       viewports: ['desktop', 'mobile'],
+      setup: {
+        sessionStorage: {
+          'reflection:route-state': 'ready'
+        }
+      },
       expects: [
         { role: 'heading', name: 'Home' },
         { noHorizontalOverflow: true },
@@ -96,10 +106,26 @@ Browser fields:
 | `blocking` | Defaults to `true`; route assertion failures are blocking unless configured otherwise by current runner behavior. |
 | `baseUrl` | Absolute URL used to visit route paths. |
 | `server` | Optional managed server. If omitted, Reflection assumes `baseUrl` is already reachable. |
+| `setup` | Optional browser-level storage setup applied before route navigation. Values are not written to report metadata. |
 | `maskSelectors` | Selectors masked in browser screenshots. |
 | `routes` | Route assertions executed in `smoke` and `full` modes. |
 | `visualSmoke` | Route screenshot baseline comparisons driven from successful browser screenshots. |
 
+Route setup fields:
+
+```ts
+setup: {
+  localStorage: {
+    'reflection:test-user': 'fixture-user'
+  },
+  sessionStorage: {
+    'reflection:test-session': 'fixture-session'
+  }
+}
+```
+
+Browser-level setup applies to every route. Route-level setup extends or overrides browser-level keys for that route. Reflection records only storage key names in metadata, never storage values. Use this for non-secret test-mode state, mock auth, or local fixture tokens. Do not commit real credentials or production session values in config.
+
 Supported browser expectations:
 
 ```ts

package/docs/getting-started.md

@@ -20,6 +20,14 @@ pnpm exec reflection doctor
 
 The package install exposes both `reflection` and `reflection-check` binaries. The docs use `reflection` as the primary command.
 
+You can preview the setup Reflection would suggest without writing files:
+
+```bash
+pnpm exec reflection init --dry-run --preset vite-react
+```
+
+`init --dry-run` prints proposed install commands, config, and script guidance. It is read-only; creating or updating files still happens manually.
+
 For local tarball testing before a registry publish, create and install a packed artifact instead.
 
 From the Reflection repository:
@@ -84,18 +92,24 @@ reflection run --config reflection.config.ts --mode smoke
 reflection review --latest
 ```
 
+Pass the config to `doctor` when you want a read-only preflight of the consuming repository setup:
+
+```bash
+reflection doctor --config reflection.config.ts
+```
+
 During Reflection development, use the built CLI:
 
 ```bash
 pnpm build
-node dist/cli.js doctor
+node dist/cli.js doctor --config examples/basic-react/reflection.config.ts
 node dist/cli.js run --config examples/basic-react/reflection.config.ts --mode smoke
 node dist/cli.js review --latest
 ```
 
 `reflection run` writes reports and artifacts under `.reflection/runs/<run-id>/` by default.
 
-`reflection doctor` is currently a lightweight setup check. The configured project contract is exercised by `reflection run --config reflection.config.ts ...`.
+`reflection doctor --config` validates that the config can be loaded, summarizes enabled contracts and server settings, checks local runtime readiness, and does not start servers or mutate baselines. Use `--check-server` when you explicitly want it to probe the configured server `readyUrl` without starting the server.
 
 Important files:
 
@@ -147,7 +161,7 @@ Use Reflection as the UI evidence gate before claiming frontend work is complete
 Run:
 
 ```bash
-reflection doctor
+reflection doctor --config reflection.config.ts
 reflection run --config reflection.config.ts --mode smoke
 reflection review --json
 ```