@ankhorage/doctor 0.5.0 → 0.6.0

package/dist/readme-usage.js

@@ -20,8 +20,13 @@ import { runCli } from './cli/standalone.js';
  *
  * - strict `public-package` validation for extracted public package repos
  * - light recognized `integration-monorepo` validation for `ankhorage4`
+ * - canonical app-manifest authentication validation for JSON file targets
  * - non-mutating `fix` plans for deterministic mechanical changes only
  *
+ * Manifest validation accepts `infra.auth.flow` as the only auth-flow location, rejects
+ * `settings.authFlow` with a manual-migration diagnostic, and permits authentication without
+ * an authorization block.
+ *
  * Still deferred:
  *
  * - GitHub checks
@@ -31,7 +36,7 @@ import { runCli } from './cli/standalone.js';
  *
  * Path handling:
  *
- * - pass `[path]`, or
+ * - pass a repo/package directory or app-manifest JSON file as `[path]`, or
  * - omit it to inspect the current working directory
  *
  * @usage

package/dist/readme-usage.js.map

@@ -1 +1 @@
-{"version":3,"file":"readme-usage.js","sourceRoot":"","sources":["../src/readme-usage.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAE7C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,MAAM,MAAM,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC","sourcesContent":["import { runCli } from './cli/standalone.js';\n\n/***\n * Provider and CLI surface\n *\n * `@ankhorage/doctor` is the repo/package compliance provider for Ankhorage.\n *\n * The same shared command implementation backs both:\n *\n * - `ankh doctor ...`\n * - `bunx @ankhorage/doctor ...`\n *\n * Current command surface:\n *\n * - `validate`\n * - `fix`\n * - `repo`\n * - `package`\n *\n * `doctor#2` adds a profile-based policy engine:\n *\n * - strict `public-package` validation for extracted public package repos\n * - light recognized `integration-monorepo` validation for `ankhorage4`\n * - non-mutating `fix` plans for deterministic mechanical changes only\n *\n * Still deferred:\n *\n * - GitHub checks\n * - CI checks\n * - on-disk `fix --apply`\n * - deeper cross-repo policy enforcement\n *\n * Path handling:\n *\n * - pass `[path]`, or\n * - omit it to inspect the current working directory\n *\n * @usage\n */\nawait runCli(['--help']);\n"]}
+{"version":3,"file":"readme-usage.js","sourceRoot":"","sources":["../src/readme-usage.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAE7C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH,MAAM,MAAM,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC","sourcesContent":["import { runCli } from './cli/standalone.js';\n\n/***\n * Provider and CLI surface\n *\n * `@ankhorage/doctor` is the repo/package compliance provider for Ankhorage.\n *\n * The same shared command implementation backs both:\n *\n * - `ankh doctor ...`\n * - `bunx @ankhorage/doctor ...`\n *\n * Current command surface:\n *\n * - `validate`\n * - `fix`\n * - `repo`\n * - `package`\n *\n * `doctor#2` adds a profile-based policy engine:\n *\n * - strict `public-package` validation for extracted public package repos\n * - light recognized `integration-monorepo` validation for `ankhorage4`\n * - canonical app-manifest authentication validation for JSON file targets\n * - non-mutating `fix` plans for deterministic mechanical changes only\n *\n * Manifest validation accepts `infra.auth.flow` as the only auth-flow location, rejects\n * `settings.authFlow` with a manual-migration diagnostic, and permits authentication without\n * an authorization block.\n *\n * Still deferred:\n *\n * - GitHub checks\n * - CI checks\n * - on-disk `fix --apply`\n * - deeper cross-repo policy enforcement\n *\n * Path handling:\n *\n * - pass a repo/package directory or app-manifest JSON file as `[path]`, or\n * - omit it to inspect the current working directory\n *\n * @usage\n */\nawait runCli(['--help']);\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ankhorage/doctor",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Executable Ankh provider and standalone CLI for lightweight repo and package compliance diagnostics.",
   "license": "MIT",
   "publishConfig": {
@@ -74,7 +74,7 @@
     "version-packages": "changeset version"
   },
   "dependencies": {
-    "@ankhorage/contracts": "^1.19.0"
+    "@ankhorage/contracts": "^2.0.0"
   },
   "devDependencies": {
     "@ankhorage/ankh": "^0.4.0",

package/src/analysis.ts

@@ -4,7 +4,7 @@ import { pathToFileURL } from 'node:url';
 
 import type { DoctorDiagnostic, DoctorPolicyProfile, DoctorRuleId } from './diagnostics.js';
 
-export type DoctorTargetCheck = 'package' | 'repo';
+export type DoctorTargetCheck = 'manifest' | 'package' | 'repo';
 export type DoctorTargetMode = 'fix' | 'package' | 'repo' | 'validate';
 export type DoctorPlannedChangeKind =
   'create-directory' | 'create-file' | 'update-json' | 'update-text';

package/src/cliLayoutAnalysis.ts

@@ -7,6 +7,7 @@ import {
   type DoctorAnalysisResult,
 } from './analysis.js';
 import type { DoctorDiagnostic, DoctorPolicyProfile } from './diagnostics.js';
+import { analyzeAppManifestTarget } from './manifestAnalysis.js';
 
 const LEGACY_ROOT_CLI_SOURCE = path.join('src', 'cli.ts');
 const CANONICAL_CLI_INDEX_SOURCE = path.join('src', 'cli', 'index.ts');
@@ -62,6 +63,11 @@ interface DependencyEntry {
 export async function analyzeDoctorTargetWithCliLayout(
   request: DoctorAnalysisRequest,
 ): Promise<DoctorAnalysisResult> {
+  const manifestResult = await analyzeAppManifestTarget(request);
+  if (manifestResult !== null) {
+    return manifestResult;
+  }
+
   const result = await analyzeDoctorTarget(request);
   if (!result.hasPackageJson) {
     return result;

package/src/commands.ts

@@ -1,7 +1,7 @@
 import type { AnkhCapabilityId, AnkhCommandDescriptor } from '@ankhorage/contracts/cli';
 
 import type { DoctorAnalysisResult, DoctorPlannedChange, DoctorTargetMode } from './analysis.js';
-import { analyzeDoctorTarget } from './analysis.js';
+import { analyzeDoctorTargetWithCliLayout } from './cliLayoutAnalysis.js';
 import type { DoctorCommandContext, DoctorCommandRunResult } from './commandContext.js';
 import {
   countErrorDiagnostics,
@@ -38,7 +38,7 @@ export interface DoctorCommandInvocation {
 }
 
 export interface DoctorCommandServices {
-  readonly analyzeTarget: typeof analyzeDoctorTarget;
+  readonly analyzeTarget: typeof analyzeDoctorTargetWithCliLayout;
 }
 
 export interface RunDoctorCommandOptions {
@@ -64,7 +64,8 @@ export const DOCTOR_COMMANDS = [
     path: ['validate'],
     capability: COMMAND_CAPABILITIES.validate,
     mode: 'validate',
-    summary: 'Auto-detect the applicable doctor policy profile and validate a local path.',
+    summary:
+      'Validate a repo, package, or app-manifest JSON path with the applicable Doctor profile.',
     run: runValidateCommand,
   },
   {
@@ -147,7 +148,7 @@ export function renderRootHelp(version: string): string {
     commandLines,
     '',
     'Path resolution:',
-    '  Pass [path], or omit it to validate the current working directory.',
+    '  Pass a repo/package directory or app-manifest JSON file, or omit [path] to inspect the current directory.',
     '',
   ].join('\n');
 }
@@ -165,7 +166,7 @@ function renderCommandHelp(command: DoctorCommandDefinition): string {
     `  ankh ${DOCTOR_COMMAND_CATEGORY} ${command.path.join(' ')} [path]`,
     '',
     'Path resolution:',
-    '  Pass [path], or omit it to validate the current working directory.',
+    '  Pass a repo/package directory or app-manifest JSON file, or omit [path] to inspect the current directory.',
     '',
   ].join('\n');
 }
@@ -174,7 +175,7 @@ function createDoctorCommandServices(
   overrides: Partial<DoctorCommandServices> = {},
 ): DoctorCommandServices {
   return {
-    analyzeTarget: overrides.analyzeTarget ?? analyzeDoctorTarget,
+    analyzeTarget: overrides.analyzeTarget ?? analyzeDoctorTargetWithCliLayout,
   };
 }
 

package/src/diagnostics.ts

@@ -2,6 +2,7 @@ export type DoctorDiagnosticCode =
   | 'field-invalid'
   | 'field-missing'
   | 'invalid-ankh-metadata'
+  | 'invalid-app-manifest-json'
   | 'invalid-package-json'
   | 'missing-dependency'
   | 'missing-path'
@@ -13,11 +14,27 @@ export type DoctorDiagnosticCode =
   | 'unsupported-target';
 
 export type DoctorDiagnosticSeverity = 'error' | 'warning';
-export type DoctorPolicyProfile = 'integration-monorepo' | 'public-package' | 'unknown';
+export type DoctorPolicyProfile =
+  'app-manifest' | 'integration-monorepo' | 'public-package' | 'unknown';
 export type DoctorRuleId =
   | 'integration.package.ankh.disallowed'
   | 'integration.package.private.required'
   | 'integration.package.workspaces.required'
+  | 'manifest.auth.authorization.engine.valid'
+  | 'manifest.auth.authorization.kind.valid'
+  | 'manifest.auth.authorization.valid-shape'
+  | 'manifest.auth.flow.post-sign-in.distinct'
+  | 'manifest.auth.flow.route.required'
+  | 'manifest.auth.flow.route.unique'
+  | 'manifest.auth.flow.route.valid'
+  | 'manifest.auth.flow.unauthorized-route.valid'
+  | 'manifest.auth.flow.valid-shape'
+  | 'manifest.auth.valid-shape'
+  | 'manifest.infra.valid-shape'
+  | 'manifest.json.readable'
+  | 'manifest.json.valid'
+  | 'manifest.root.valid-shape'
+  | 'manifest.settings.auth-flow.removed'
   | 'package.ankh.capabilities.match-provider'
   | 'package.ankh.present.valid-shape'
   | 'package.ankh.provider-path.required'

package/src/index.ts

@@ -23,6 +23,11 @@ export type {
   DoctorPolicyProfile,
   DoctorRuleId,
 } from './diagnostics.js';
+export {
+  analyzeAppManifest,
+  analyzeAppManifestFile,
+  analyzeAppManifestTarget,
+} from './manifestAnalysis.js';
 export {
   DOCTOR_CAPABILITIES,
   DOCTOR_COMMAND_CATEGORY,

package/src/manifestAnalysis.ts

@@ -0,0 +1,458 @@
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+
+import { AUTHZ_ENGINES, AUTHZ_KINDS } from '@ankhorage/contracts';
+import { type AuthFlowConfig, resolveAuthFlow } from '@ankhorage/contracts/auth';
+
+import type {
+  DoctorAnalysisRequest,
+  DoctorAnalysisResult,
+  DoctorFixPlan,
+  DoctorPlannedChange,
+} from './analysis.js';
+import type {
+  DoctorDiagnostic,
+  DoctorDiagnosticCode,
+  DoctorPolicyProfile,
+  DoctorRuleId,
+} from './diagnostics.js';
+
+const MANIFEST_PROFILE = 'app-manifest' satisfies DoctorPolicyProfile;
+const AUTH_ACTION_ROUTE_KEYS = [
+  'signInRoute',
+  'signUpRoute',
+  'signOutRoute',
+  'forgotPasswordRoute',
+  'otpRoute',
+] as const satisfies readonly (keyof AuthFlowConfig)[];
+const OPTIONAL_ROUTE_KEYS = [
+  'signUpRoute',
+  'signOutRoute',
+  'forgotPasswordRoute',
+  'otpRoute',
+  'unauthorizedRoute',
+] as const satisfies readonly (keyof AuthFlowConfig)[];
+
+type AuthActionRouteKey = (typeof AUTH_ACTION_ROUTE_KEYS)[number];
+type OptionalRouteKey = (typeof OPTIONAL_ROUTE_KEYS)[number];
+
+export async function analyzeAppManifestTarget(
+  request: DoctorAnalysisRequest,
+): Promise<DoctorAnalysisResult | null> {
+  const targetPath = path.resolve(request.cwd, request.inputPath ?? '.');
+  const stats = await statOrNull(targetPath);
+
+  if (
+    stats === null ||
+    !stats.isFile() ||
+    path.extname(targetPath).toLowerCase() !== '.json' ||
+    (request.mode !== 'validate' && request.mode !== 'fix')
+  ) {
+    return null;
+  }
+
+  const diagnostics = await analyzeAppManifestFile(targetPath);
+  const plannedChanges: DoctorPlannedChange[] = [];
+  const fixPlan: DoctorFixPlan | null =
+    request.mode === 'fix'
+      ? {
+          changes: plannedChanges,
+          diagnostics,
+          profile: MANIFEST_PROFILE,
+          targetPath,
+        }
+      : null;
+
+  return {
+    appliedChecks: ['manifest'],
+    diagnostics,
+    fixPlan,
+    hasPackageJson: false,
+    plannedChanges,
+    profile: MANIFEST_PROFILE,
+    repoMarkers: [],
+    targetPath,
+  };
+}
+
+export async function analyzeAppManifestFile(filePath: string): Promise<DoctorDiagnostic[]> {
+  let source: string;
+
+  try {
+    source = await fs.readFile(filePath, 'utf8');
+  } catch (error) {
+    return [
+      createManifestDiagnostic({
+        code: 'invalid-app-manifest-json',
+        message: `Could not read app manifest JSON: ${toErrorMessage(error)}`,
+        path: filePath,
+        ruleId: 'manifest.json.readable',
+      }),
+    ];
+  }
+
+  let manifest: unknown;
+
+  try {
+    manifest = JSON.parse(source) as unknown;
+  } catch (error) {
+    return [
+      createManifestDiagnostic({
+        code: 'invalid-app-manifest-json',
+        message: `App manifest must contain valid JSON: ${toErrorMessage(error)}`,
+        path: filePath,
+        ruleId: 'manifest.json.valid',
+      }),
+    ];
+  }
+
+  return analyzeAppManifest(manifest, filePath);
+}
+
+export function analyzeAppManifest(
+  manifest: unknown,
+  manifestPath = 'manifest.json',
+): DoctorDiagnostic[] {
+  if (!isRecord(manifest)) {
+    return [
+      createManifestDiagnostic({
+        code: 'field-invalid',
+        message: 'App manifest root must be a JSON object.',
+        path: manifestPath,
+        ruleId: 'manifest.root.valid-shape',
+      }),
+    ];
+  }
+
+  const diagnostics: DoctorDiagnostic[] = [];
+  const { settings } = manifest;
+
+  if (isRecord(settings) && hasOwn(settings, 'authFlow')) {
+    diagnostics.push(
+      createManifestDiagnostic({
+        code: 'field-invalid',
+        message:
+          'settings.authFlow was removed. Move this configuration manually to infra.auth.flow; Doctor will not migrate it automatically.',
+        path: manifestPath,
+        ruleId: 'manifest.settings.auth-flow.removed',
+      }),
+    );
+  }
+
+  const { infra } = manifest;
+  if (infra === undefined) {
+    return diagnostics;
+  }
+
+  if (!isRecord(infra)) {
+    diagnostics.push(
+      createManifestDiagnostic({
+        code: 'field-invalid',
+        message: 'manifest.infra must be a JSON object when present.',
+        path: manifestPath,
+        ruleId: 'manifest.infra.valid-shape',
+      }),
+    );
+    return diagnostics;
+  }
+
+  const { auth } = infra;
+  if (auth === undefined) {
+    return diagnostics;
+  }
+
+  if (!isRecord(auth)) {
+    diagnostics.push(
+      createManifestDiagnostic({
+        code: 'field-invalid',
+        message: 'manifest.infra.auth must be a JSON object when present.',
+        path: manifestPath,
+        ruleId: 'manifest.auth.valid-shape',
+      }),
+    );
+    return diagnostics;
+  }
+
+  const flow = parseAuthFlow(auth.flow, manifestPath, diagnostics);
+  if (flow !== null) {
+    validateAuthFlowRelationships(flow, manifestPath, diagnostics);
+  }
+
+  validateAuthorization(auth.authorization, manifestPath, diagnostics);
+
+  return diagnostics;
+}
+
+function parseAuthFlow(
+  value: unknown,
+  manifestPath: string,
+  diagnostics: DoctorDiagnostic[],
+): AuthFlowConfig | null {
+  if (value === undefined) {
+    return resolveAuthFlow();
+  }
+
+  if (!isRecord(value)) {
+    diagnostics.push(
+      createManifestDiagnostic({
+        code: 'field-invalid',
+        message: 'manifest.infra.auth.flow must be a JSON object when present.',
+        path: manifestPath,
+        ruleId: 'manifest.auth.flow.valid-shape',
+      }),
+    );
+    return null;
+  }
+
+  const signInRoute = readRequiredRoute(value, 'signInRoute', manifestPath, diagnostics);
+  const postSignInRoute = readRequiredRoute(value, 'postSignInRoute', manifestPath, diagnostics);
+  const optionalRoutes = readOptionalRoutes(value, manifestPath, diagnostics);
+
+  if (signInRoute === null || postSignInRoute === null || optionalRoutes === null) {
+    return null;
+  }
+
+  return resolveAuthFlow({
+    signInRoute,
+    postSignInRoute,
+    ...optionalRoutes,
+  });
+}
+
+function readRequiredRoute(
+  flow: Record<string, unknown>,
+  key: 'postSignInRoute' | 'signInRoute',
+  manifestPath: string,
+  diagnostics: DoctorDiagnostic[],
+): string | null {
+  const value = flow[key];
+
+  if (typeof value !== 'string' || value.trim() === '') {
+    diagnostics.push(
+      createManifestDiagnostic({
+        code: value === undefined ? 'field-missing' : 'field-invalid',
+        message: `manifest.infra.auth.flow.${key} must be a non-empty string.`,
+        path: manifestPath,
+        ruleId: 'manifest.auth.flow.route.required',
+      }),
+    );
+    return null;
+  }
+
+  return value;
+}
+
+function readOptionalRoutes(
+  flow: Record<string, unknown>,
+  manifestPath: string,
+  diagnostics: DoctorDiagnostic[],
+): Pick<AuthFlowConfig, OptionalRouteKey> | null {
+  const routes: Partial<Pick<AuthFlowConfig, OptionalRouteKey>> = {};
+  let valid = true;
+
+  for (const key of OPTIONAL_ROUTE_KEYS) {
+    const value = flow[key];
+    if (value === undefined) {
+      continue;
+    }
+
+    if (typeof value !== 'string' || value.trim() === '') {
+      valid = false;
+      diagnostics.push(
+        createManifestDiagnostic({
+          code: 'field-invalid',
+          message: `manifest.infra.auth.flow.${key} must be a non-empty string when present.`,
+          path: manifestPath,
+          ruleId: 'manifest.auth.flow.route.valid',
+        }),
+      );
+      continue;
+    }
+
+    routes[key] = value;
+  }
+
+  return valid ? routes : null;
+}
+
+function validateAuthFlowRelationships(
+  flow: AuthFlowConfig,
+  manifestPath: string,
+  diagnostics: DoctorDiagnostic[],
+): void {
+  const actionRoutes = AUTH_ACTION_ROUTE_KEYS.flatMap((key) => {
+    const value = flow[key];
+    return typeof value === 'string' ? [{ key, route: normalizeRoute(value) }] : [];
+  });
+  const routesByName = new Map<string, AuthActionRouteKey[]>();
+
+  for (const entry of actionRoutes) {
+    const keys = routesByName.get(entry.route) ?? [];
+    keys.push(entry.key);
+    routesByName.set(entry.route, keys);
+  }
+
+  for (const [route, keys] of routesByName) {
+    if (keys.length < 2) {
+      continue;
+    }
+
+    diagnostics.push(
+      createManifestDiagnostic({
+        code: 'field-invalid',
+        message: `Auth action routes must be unique; ${keys.join(', ')} all resolve to "${route}".`,
+        path: manifestPath,
+        ruleId: 'manifest.auth.flow.route.unique',
+      }),
+    );
+  }
+
+  const postSignInRoute = normalizeRoute(flow.postSignInRoute);
+  const collidingAction = actionRoutes.find((entry) => entry.route === postSignInRoute);
+  if (collidingAction !== undefined) {
+    diagnostics.push(
+      createManifestDiagnostic({
+        code: 'field-invalid',
+        message: `postSignInRoute must resolve outside the auth action routes; it collides with ${collidingAction.key}.`,
+        path: manifestPath,
+        ruleId: 'manifest.auth.flow.post-sign-in.distinct',
+      }),
+    );
+  }
+
+  if (flow.unauthorizedRoute === undefined) {
+    return;
+  }
+
+  const unauthorizedRoute = normalizeRoute(flow.unauthorizedRoute);
+  const signInRoute = normalizeRoute(flow.signInRoute);
+
+  if (unauthorizedRoute === postSignInRoute) {
+    diagnostics.push(
+      createManifestDiagnostic({
+        code: 'field-invalid',
+        message: 'unauthorizedRoute must not resolve to postSignInRoute.',
+        path: manifestPath,
+        ruleId: 'manifest.auth.flow.unauthorized-route.valid',
+      }),
+    );
+  }
+
+  if (unauthorizedRoute === signInRoute) {
+    return;
+  }
+
+  const collidingActionRoute = actionRoutes.find(
+    (entry) => entry.key !== 'signInRoute' && entry.route === unauthorizedRoute,
+  );
+  if (collidingActionRoute !== undefined) {
+    diagnostics.push(
+      createManifestDiagnostic({
+        code: 'field-invalid',
+        message: `unauthorizedRoute may alias signInRoute, but it must not collide with ${collidingActionRoute.key}.`,
+        path: manifestPath,
+        ruleId: 'manifest.auth.flow.unauthorized-route.valid',
+      }),
+    );
+  }
+}
+
+function validateAuthorization(
+  value: unknown,
+  manifestPath: string,
+  diagnostics: DoctorDiagnostic[],
+): void {
+  if (value === undefined) {
+    return;
+  }
+
+  if (!isRecord(value)) {
+    diagnostics.push(
+      createManifestDiagnostic({
+        code: 'field-invalid',
+        message:
+          'manifest.infra.auth.authorization must be a JSON object when explicitly configured.',
+        path: manifestPath,
+        ruleId: 'manifest.auth.authorization.valid-shape',
+      }),
+    );
+    return;
+  }
+
+  validateAuthorizationField({
+    allowed: AUTHZ_KINDS,
+    diagnostics,
+    fieldName: 'kind',
+    manifestPath,
+    value: value.kind,
+    ruleId: 'manifest.auth.authorization.kind.valid',
+  });
+  validateAuthorizationField({
+    allowed: AUTHZ_ENGINES,
+    diagnostics,
+    fieldName: 'engine',
+    manifestPath,
+    value: value.engine,
+    ruleId: 'manifest.auth.authorization.engine.valid',
+  });
+}
+
+function validateAuthorizationField(request: {
+  readonly allowed: readonly string[];
+  readonly diagnostics: DoctorDiagnostic[];
+  readonly fieldName: 'engine' | 'kind';
+  readonly manifestPath: string;
+  readonly ruleId: DoctorRuleId;
+  readonly value: unknown;
+}): void {
+  if (typeof request.value === 'string' && request.allowed.includes(request.value)) {
+    return;
+  }
+
+  request.diagnostics.push(
+    createManifestDiagnostic({
+      code: request.value === undefined ? 'field-missing' : 'field-invalid',
+      message: `Explicit authorization.${request.fieldName} must be one of: ${request.allowed.join(', ')}.`,
+      path: request.manifestPath,
+      ruleId: request.ruleId,
+    }),
+  );
+}
+
+function createManifestDiagnostic(request: {
+  readonly code: DoctorDiagnosticCode;
+  readonly message: string;
+  readonly path: string;
+  readonly ruleId: DoctorRuleId;
+}): DoctorDiagnostic {
+  return {
+    ...request,
+    profile: MANIFEST_PROFILE,
+    severity: 'error',
+  };
+}
+
+function normalizeRoute(route: string): string {
+  const normalized = route.trim().replace(/^\/+/, '').replace(/\/+$/, '');
+  return normalized === '' ? 'index' : normalized;
+}
+
+function hasOwn(record: Record<string, unknown>, key: string): boolean {
+  return Object.prototype.hasOwnProperty.call(record, key);
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+async function statOrNull(filePath: string) {
+  try {
+    return await fs.stat(filePath);
+  } catch {
+    return null;
+  }
+}
+
+function toErrorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}

package/src/readme-usage.ts

@@ -21,8 +21,13 @@ import { runCli } from './cli/standalone.js';
  *
  * - strict `public-package` validation for extracted public package repos
  * - light recognized `integration-monorepo` validation for `ankhorage4`
+ * - canonical app-manifest authentication validation for JSON file targets
  * - non-mutating `fix` plans for deterministic mechanical changes only
  *
+ * Manifest validation accepts `infra.auth.flow` as the only auth-flow location, rejects
+ * `settings.authFlow` with a manual-migration diagnostic, and permits authentication without
+ * an authorization block.
+ *
  * Still deferred:
  *
  * - GitHub checks
@@ -32,7 +37,7 @@ import { runCli } from './cli/standalone.js';
  *
  * Path handling:
  *
- * - pass `[path]`, or
+ * - pass a repo/package directory or app-manifest JSON file as `[path]`, or
  * - omit it to inspect the current working directory
  *
  * @usage