@theaiplatform/miniapp-sdk 0.3.3 → 0.4.0

package/dist/bin/tap-miniapp-test.js

@@ -0,0 +1,1293 @@
+#!/usr/bin/env node
+import * as __rspack_external_node_fs_promises_3b710708 from "node:fs/promises";
+import * as __rspack_external_ajv_dist_2020_js_e85899db from "ajv/dist/2020.js";
+import * as __rspack_external_node_crypto_2e7c4b46 from "node:crypto";
+import * as __rspack_external_node_path_806ed179 from "node:path";
+import * as __rspack_external_zod from "zod";
+import { registerTapManifestAjvFormats } from "../internal/json-schema.js";
+const SDK_PACKAGE = '@theaiplatform/miniapp-sdk';
+const TEST_DESCRIPTOR_SCHEMA_ID = 'https://the-ai-platform.dev/schemas/tap.test.schema.json';
+const TARGET_ORDER = [
+    'desktop',
+    'mobile',
+    'quickjs',
+    'worker',
+    'node',
+    'workflow-host'
+];
+const MAX_JSON_BYTES = 8388608;
+const MAX_SCANNED_TEST_FILES = 10000;
+const V1_DENIED_ACTIONS = Object.freeze({
+    default: [],
+    'all-denied': [
+        '*'
+    ],
+    'read-only': [
+        'do:*'
+    ],
+    'http-denied': [
+        'network.request'
+    ]
+});
+const jsonValueSchema = __rspack_external_zod.z.lazy(()=>__rspack_external_zod.z.union([
+        __rspack_external_zod.z["null"](),
+        __rspack_external_zod.z.boolean(),
+        __rspack_external_zod.z.number().finite(),
+        __rspack_external_zod.z.string(),
+        __rspack_external_zod.z.array(jsonValueSchema),
+        __rspack_external_zod.z.record(__rspack_external_zod.z.string(), jsonValueSchema)
+    ]));
+const v1DescriptorSchema = __rspack_external_zod.z.object({
+    schemaVersion: __rspack_external_zod.z.literal(1),
+    packageId: __rspack_external_zod.z.string().trim().min(1).max(512),
+    runner: __rspack_external_zod.z.literal('rstest'),
+    configPath: __rspack_external_zod.z.string().trim().min(1).max(512),
+    testRoots: __rspack_external_zod.z.array(__rspack_external_zod.z.string().trim().min(1).max(512)).min(1).max(64),
+    defaultMode: __rspack_external_zod.z["enum"]([
+        'surface',
+        'live-tap'
+    ]),
+    surfaces: __rspack_external_zod.z.array(__rspack_external_zod.z.string().trim().min(1).max(256)).min(1).max(64),
+    permissionScenarios: __rspack_external_zod.z.array(__rspack_external_zod.z.string().trim().min(1).max(256)).min(1).max(64)
+}).strict();
+function compareCodePoints(left, right) {
+    return left < right ? -1 : left > right ? 1 : 0;
+}
+function isJsonObject(value) {
+    return null !== value && 'object' == typeof value && !Array.isArray(value);
+}
+function requireObject(value, label) {
+    if (void 0 === value || !isJsonObject(value)) throw new Error(`${label} must be an object.`);
+    return value;
+}
+function requireString(value, label) {
+    if ('string' != typeof value || 0 === value.length) throw new Error(`${label} must be a non-empty string.`);
+    return value;
+}
+function optionalStringArray(value, label) {
+    if (void 0 === value) return [];
+    if (!Array.isArray(value) || value.some((entry)=>'string' != typeof entry)) throw new Error(`${label} must be an array of strings.`);
+    return value.map((entry)=>requireString(entry, label));
+}
+function requireArray(value, label) {
+    if (!Array.isArray(value)) throw new Error(`${label} must be an array.`);
+    return value;
+}
+function normalizeRelativePath(value, label) {
+    const normalized = value.trim();
+    if (0 === normalized.length || normalized.length > 512 || normalized.includes('\0') || normalized.includes('\\') || normalized.startsWith('/') || /^[a-zA-Z]:/u.test(normalized) || normalized.split('/').some((segment)=>'..' === segment)) throw new Error(`${label} must be a confined slash-relative path.`);
+    return normalized.replace(/^\.\//u, '');
+}
+function projectPath(root, relativePath) {
+    const relative = normalizeRelativePath(relativePath, 'Project path');
+    const absolute = __rspack_external_node_path_806ed179["default"].resolve(root, relative);
+    if (absolute !== root && !absolute.startsWith(`${__rspack_external_node_path_806ed179["default"].resolve(root)}${__rspack_external_node_path_806ed179["default"].sep}`)) throw new Error(`Project path escapes the source root: ${relative}`);
+    return absolute;
+}
+function parseJson(source, label) {
+    if (Buffer.byteLength(source, 'utf8') > MAX_JSON_BYTES) throw new Error(`${label} exceeds ${MAX_JSON_BYTES} bytes.`);
+    let parsed;
+    try {
+        parsed = JSON.parse(source);
+    } catch (error) {
+        throw new Error(`${label} is not valid JSON: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    const result = jsonValueSchema.safeParse(parsed);
+    if (!result.success) throw new Error(`${label} must contain strict finite JSON.`);
+    return result.data;
+}
+function schemaValidator(schema, label) {
+    if (!isJsonObject(schema) && 'boolean' != typeof schema) throw new Error(`${label} must be a JSON Schema object or boolean.`);
+    const ajv = registerTapManifestAjvFormats(new __rspack_external_ajv_dist_2020_js_e85899db["default"]({
+        allErrors: true,
+        strict: true
+    }));
+    return ajv.compile(schema);
+}
+function formatSchemaErrors(errors) {
+    return (errors ?? []).slice(0, 16).map((error)=>{
+        const location = error.instancePath || '/';
+        if ('additionalProperties' === error.keyword) return `${location} has unsupported property "${String(error.params.additionalProperty)}"`;
+        if ('required' === error.keyword) return `${location} is missing "${String(error.params.missingProperty)}"`;
+        return `${location} ${error.message ?? 'is invalid'}`;
+    }).join('; ');
+}
+function assertSchema(value, schema, label) {
+    const validate = schemaValidator(schema, `${label} schema`);
+    if (!validate(value)) throw new Error(`${label} is invalid: ${formatSchemaErrors(validate.errors)}`);
+}
+async function canonicalRoot(root) {
+    const resolved = await (0, __rspack_external_node_fs_promises_3b710708.realpath)(__rspack_external_node_path_806ed179["default"].resolve(root));
+    const stats = await (0, __rspack_external_node_fs_promises_3b710708.lstat)(resolved);
+    if (!stats.isDirectory()) throw new Error(`Project root is not a directory: ${root}`);
+    return resolved;
+}
+async function readProjectFile(root, relativePath) {
+    const normalized = normalizeRelativePath(relativePath, 'Project file');
+    const absolutePath = projectPath(root, normalized);
+    const resolved = await (0, __rspack_external_node_fs_promises_3b710708.realpath)(absolutePath).catch(()=>void 0);
+    if (!resolved) throw new Error(`Required project file is missing: ${normalized}`);
+    if (resolved !== root && !resolved.startsWith(`${root}${__rspack_external_node_path_806ed179["default"].sep}`)) throw new Error(`Project file resolves outside the source root: ${normalized}`);
+    const stats = await (0, __rspack_external_node_fs_promises_3b710708.lstat)(absolutePath);
+    if (!stats.isFile() || stats.isSymbolicLink()) throw new Error(`Project file must be a regular non-symlink: ${normalized}`);
+    return {
+        absolutePath,
+        source: await (0, __rspack_external_node_fs_promises_3b710708.readFile)(absolutePath, 'utf8')
+    };
+}
+async function readJsonProjectFile(root, relativePath) {
+    const file = await readProjectFile(root, relativePath);
+    return {
+        path: normalizeRelativePath(relativePath, 'Project JSON file'),
+        source: file.source,
+        value: parseJson(file.source, relativePath)
+    };
+}
+function manifestInventory(value) {
+    const manifest = requireObject(value, 'Manifest');
+    const packageRecord = requireObject(manifest.package, 'manifest.package');
+    const compatibility = requireObject(manifest.compatibility, 'manifest.compatibility');
+    const targetRecord = requireObject(manifest.targets, 'manifest.targets');
+    const targets = TARGET_ORDER.filter((target)=>Object.hasOwn(targetRecord, target));
+    const targetSet = new Set(targets);
+    const contributions = requireArray(manifest.contributions, 'manifest.contributions');
+    const permissionActions = new Map();
+    for (const entry of contributions){
+        const contribution = requireObject(entry, 'manifest contribution');
+        if ('permission.catalog' !== contribution.kind) continue;
+        const options = requireObject(contribution.options, 'permission.catalog options');
+        for (const actionValue of requireArray(options.actions, 'permission.catalog options.actions')){
+            const action = requireObject(actionValue, 'permission action');
+            const id = requireString(action.id, 'permission action id');
+            if (permissionActions.has(id)) throw new Error(`Manifest declares duplicate permission action ${id}.`);
+            permissionActions.set(id, {
+                autonomyCeiling: requireString(action.autonomyCeiling, `permission action ${id} autonomyCeiling`),
+                consent: requireString(action.consent, `permission action ${id} consent`),
+                risk: requireString(action.risk, `permission action ${id} risk`)
+            });
+        }
+    }
+    const surfaces = contributions.filter((entry)=>{
+        const contribution = requireObject(entry, 'manifest contribution');
+        return 'ui.surface' === contribution.kind;
+    }).map((entry)=>{
+        const contribution = requireObject(entry, 'UI surface contribution');
+        const id = requireString(contribution.id, 'UI surface id');
+        const contributionTargetRecord = requireObject(contribution.targets, `UI surface ${id} targets`);
+        const contributionTargets = TARGET_ORDER.filter((target)=>Object.hasOwn(contributionTargetRecord, target));
+        if (0 === contributionTargets.length) throw new Error(`UI surface ${id} has no target bindings.`);
+        for (const target of contributionTargets)if (!targetSet.has(target)) throw new Error(`UI surface ${id} references undeclared manifest target ${target}.`);
+        const authorization = void 0 === contribution.authorization ? {} : requireObject(contribution.authorization, `UI surface ${id} authorization`);
+        const requiredOrigins = new Set();
+        const effects = [
+            ...new Set(requireArray(authorization.effects ?? [], `UI surface ${id} authorization.effects`).flatMap((effectValue)=>{
+                const effect = requireObject(effectValue, `UI surface ${id} effect`);
+                const kind = requireString(effect.kind, `UI surface ${id} effect kind`);
+                const resources = [
+                    ...new Set(optionalStringArray(effect.resources, `UI surface ${id} effect resources`))
+                ];
+                if ('external-network' === kind || 'host-http' === kind || 'network' === kind || 'embedded-frame' === kind) for (const resource of resources)try {
+                    const url = new URL(resource);
+                    if ('http:' === url.protocol || 'https:' === url.protocol) requiredOrigins.add(url.origin);
+                } catch  {}
+                return 0 === resources.length ? [
+                    `effect:${kind}:*`
+                ] : resources.map((resource)=>`effect:${kind}:${resource}`);
+            }))
+        ];
+        const authorizationActions = [
+            ...new Set(optionalStringArray(authorization.allOf, `UI surface ${id} authorization.allOf`))
+        ];
+        const highRiskActions = authorizationActions.filter((actionId)=>{
+            const action = permissionActions.get(actionId);
+            if (!action) throw new Error(`UI surface ${id} references undeclared permission action ${actionId}.`);
+            return 'write' === action.risk || 'consequential' === action.risk || 'do' === action.autonomyCeiling && 'none' !== action.consent;
+        });
+        return {
+            id,
+            targets: contributionTargets,
+            authorizationActions,
+            authorizationEffects: effects,
+            highRiskCapabilities: [
+                ...new Set([
+                    ...highRiskActions.map((actionId)=>`action:${actionId}`),
+                    ...effects
+                ])
+            ].sort(compareCodePoints),
+            requiredOrigins: [
+                ...requiredOrigins
+            ].sort(compareCodePoints)
+        };
+    }).sort((left, right)=>compareCodePoints(left.id, right.id));
+    if (0 === surfaces.length) throw new Error('Manifest declares no ui.surface contributions.');
+    const surfaceIds = new Set();
+    for (const surface of surfaces){
+        if (surfaceIds.has(surface.id)) throw new Error(`Manifest declares duplicate UI surface ${surface.id}.`);
+        surfaceIds.add(surface.id);
+    }
+    return {
+        packageId: requireString(packageRecord.packageId, 'manifest.package.packageId'),
+        sdkVersion: requireString(compatibility.tapSdk, 'manifest.compatibility.tapSdk'),
+        targets,
+        surfaces
+    };
+}
+async function loadTapToolingSchemas(manifestSchemaPath, testDescriptorSchemaPath) {
+    const [manifestSource, descriptorSource] = await Promise.all([
+        (0, __rspack_external_node_fs_promises_3b710708.readFile)(manifestSchemaPath, 'utf8'),
+        (0, __rspack_external_node_fs_promises_3b710708.readFile)(testDescriptorSchemaPath, 'utf8')
+    ]);
+    return Object.freeze({
+        manifest: parseJson(manifestSource, 'TAP package manifest schema'),
+        testDescriptor: parseJson(descriptorSource, "TAP test descriptor schema")
+    });
+}
+async function inspectTapManifest(options, schemas) {
+    const root = await canonicalRoot(options.root);
+    const document = await readJsonProjectFile(root, options.manifestPath ?? 'manifest.tap.json');
+    assertSchema(document.value, schemas.manifest, document.path);
+    return manifestInventory(document.value);
+}
+function parseTapSdkPackageVersion(source) {
+    const value = requireObject(parseJson(source, 'SDK package.json'), 'SDK package.json');
+    if (value.name !== SDK_PACKAGE) throw new Error(`Executing package must be ${SDK_PACKAGE}.`);
+    return requireString(value.version, 'SDK package.json version');
+}
+function defaultEnvironment() {
+    return {
+        viewport: {
+            width: 1280,
+            height: 720
+        },
+        locale: 'en-US',
+        timezone: 'UTC',
+        theme: 'light',
+        reducedMotion: true,
+        seed: 1,
+        fixedNow: '2026-01-01T00:00:00Z'
+    };
+}
+function defaultArtifacts() {
+    return {
+        trace: 'failure-only',
+        screenshots: 'failure-only'
+    };
+}
+function profileId(surface, target) {
+    const value = `${surface}-${target}`.toLowerCase().replace(/[^a-z0-9._-]+/gu, '-').replace(/^-+|-+$/gu, '');
+    const digest = __rspack_external_node_crypto_2e7c4b46["default"].createHash('sha256').update(`${surface}\0${target}`).digest('hex').slice(0, 24);
+    if (0 === value.length) return digest;
+    return `${value.slice(0, 103)}-${digest}`;
+}
+function scaffoldDescriptor(inventory) {
+    const profiles = {};
+    const matrix = [];
+    for (const surface of inventory.surfaces)for (const target of surface.targets){
+        const id = profileId(surface.id, target);
+        if (Object.hasOwn(profiles, id)) throw new Error(`Derived duplicate profile id ${id}.`);
+        profiles[id] = {
+            surface: surface.id,
+            target,
+            mode: 'surface',
+            permissionScenario: 'default',
+            deniedActions: [],
+            fixtureFiles: [
+                'tests/fixtures/default.seed.json'
+            ],
+            httpRouteFiles: [
+                'tests/fixtures/default.http-routes.json'
+            ],
+            requiredOrigins: [
+                ...surface.requiredOrigins
+            ],
+            requiredEffects: [
+                ...surface.authorizationEffects
+            ],
+            credentialSlots: [],
+            environment: defaultEnvironment(),
+            artifacts: defaultArtifacts()
+        };
+        matrix.push({
+            id,
+            profile: id,
+            capabilities: [
+                ...surface.authorizationActions.map((actionId)=>`action:${actionId}`),
+                ...surface.authorizationEffects
+            ].sort(compareCodePoints)
+        });
+    }
+    return {
+        $schema: TEST_DESCRIPTOR_SCHEMA_ID,
+        schemaVersion: 2,
+        packageId: inventory.packageId,
+        configPath: 'rstest.tap.config.ts',
+        testMatch: [
+            'tests/e2e/**'
+        ],
+        profiles,
+        matrix,
+        waivers: []
+    };
+}
+function deniedActionsForV1Scenario(scenario) {
+    if ('default' === scenario) return [
+        ...V1_DENIED_ACTIONS.default
+    ];
+    if ('all-denied' === scenario) return [
+        ...V1_DENIED_ACTIONS['all-denied']
+    ];
+    if ('read-only' === scenario) return [
+        ...V1_DENIED_ACTIONS['read-only']
+    ];
+    if ('http-denied' === scenario) return [
+        ...V1_DENIED_ACTIONS['http-denied']
+    ];
+    if (scenario.startsWith('deny:') && scenario.length > 5) return [
+        scenario.slice(5)
+    ];
+    return [];
+}
+function expandMigratedDescriptor(v1Value, inventory) {
+    const parsed = v1DescriptorSchema.parse(v1Value);
+    if (parsed.packageId !== inventory.packageId) throw new Error('tap.test.json packageId does not match manifest.package.packageId.');
+    const surfaces = new Map(inventory.surfaces.map((surface)=>[
+            surface.id,
+            surface
+        ]));
+    const profiles = {};
+    const matrix = [];
+    let sequence = 1;
+    for (const surfaceId of parsed.surfaces){
+        const surface = surfaces.get(surfaceId);
+        if (!surface) throw new Error(`v1 tap.test.json surface ${surfaceId} is not declared by the manifest.`);
+        for (const target of surface.targets)for (const permissionScenario of parsed.permissionScenarios){
+            const suffix = String(sequence).padStart(3, '0');
+            const profile = `v1-profile-${suffix}`;
+            profiles[profile] = {
+                surface: surfaceId,
+                target,
+                mode: 'surface' === parsed.defaultMode ? 'surface' : 'live',
+                permissionScenario,
+                deniedActions: deniedActionsForV1Scenario(permissionScenario),
+                fixtureFiles: [],
+                httpRouteFiles: [],
+                requiredOrigins: [
+                    ...surface.requiredOrigins
+                ],
+                requiredEffects: [
+                    ...surface.authorizationEffects
+                ],
+                credentialSlots: [],
+                environment: defaultEnvironment(),
+                artifacts: defaultArtifacts()
+            };
+            matrix.push({
+                id: `v1-matrix-${suffix}`,
+                profile,
+                capabilities: [
+                    ...surface.authorizationActions.map((actionId)=>`action:${actionId}`),
+                    ...surface.authorizationEffects
+                ].sort(compareCodePoints)
+            });
+            sequence += 1;
+        }
+    }
+    return {
+        $schema: TEST_DESCRIPTOR_SCHEMA_ID,
+        schemaVersion: 2,
+        packageId: parsed.packageId,
+        configPath: parsed.configPath,
+        testMatch: parsed.testRoots.map((root)=>{
+            const confined = normalizeRelativePath(root, 'v1 testRoot');
+            return confined.endsWith('/**') ? confined : `${confined}/**`;
+        }),
+        profiles,
+        matrix,
+        waivers: []
+    };
+}
+function descriptorProfiles(descriptor) {
+    return requireObject(descriptor.profiles, 'tap.test.json profiles');
+}
+function descriptorTestMatch(descriptor, label = 'tap.test.json testMatch') {
+    return optionalStringArray(descriptor.testMatch, label);
+}
+function matrixRows(value) {
+    const descriptor = requireObject(value, 'tap.test.json');
+    const profiles = descriptorProfiles(descriptor);
+    const rootTestMatch = descriptorTestMatch(descriptor);
+    return requireArray(descriptor.matrix, 'tap.test.json matrix').map((entryValue)=>{
+        const entry = requireObject(entryValue, 'tap.test.json matrix entry');
+        const id = requireString(entry.id, 'matrix id');
+        const profileName = requireString(entry.profile, `matrix ${id} profile`);
+        const profile = requireObject(profiles[profileName], `matrix ${id} profile ${profileName}`);
+        const testMatch = optionalStringArray(entry.testMatch, `matrix ${id} testMatch`);
+        return {
+            id,
+            profile: profileName,
+            surface: requireString(profile.surface, `profile ${profileName} surface`),
+            target: requireString(profile.target, `profile ${profileName} target`),
+            mode: requireString(profile.mode, `profile ${profileName} mode`),
+            permissionScenario: requireString(profile.permissionScenario, `profile ${profileName} permissionScenario`),
+            deniedActions: optionalStringArray(profile.deniedActions, `profile ${profileName} deniedActions`),
+            capabilities: optionalStringArray(entry.capabilities, `matrix ${id} capabilities`),
+            testMatch: testMatch.length > 0 ? testMatch : rootTestMatch
+        };
+    });
+}
+async function inspectTapMatrix(options, schemas) {
+    const root = await canonicalRoot(options.root);
+    const descriptorPath = options.descriptorPath ?? 'tap.test.json';
+    const document = await readJsonProjectFile(root, descriptorPath);
+    const object = requireObject(document.value, descriptorPath);
+    const descriptor = 1 === object.schemaVersion ? expandMigratedDescriptor(document.value, await inspectTapManifest({
+        ...options,
+        root
+    }, schemas)) : object;
+    assertSchema(descriptor, schemas.testDescriptor, descriptorPath);
+    return Object.freeze({
+        descriptor,
+        rows: matrixRows(descriptor)
+    });
+}
+function jsonFile(value) {
+    return `${JSON.stringify(value, null, 2)}\n`;
+}
+function configFile() {
+    return `import { defineTapRstestConfig } from '${SDK_PACKAGE}/testing/rstest-config';\n\nexport default defineTapRstestConfig();\n`;
+}
+function testRootFromPattern(pattern) {
+    const confined = normalizeRelativePath(pattern, 'testMatch');
+    const globIndex = confined.search(/[*?[{]/u);
+    const prefix = (-1 === globIndex ? confined : confined.slice(0, globIndex)).replace(/\/+$/u, '');
+    if (0 === prefix.length) throw new Error(`testMatch must have a confined directory prefix: ${pattern}`);
+    const extension = __rspack_external_node_path_806ed179["default"].posix.extname(prefix);
+    return extension.length > 0 ? __rspack_external_node_path_806ed179["default"].posix.dirname(prefix) : prefix;
+}
+function tapTsconfig(configPath, testRoots) {
+    return jsonFile({
+        extends: './tsconfig.json',
+        compilerOptions: {
+            incremental: true,
+            noEmit: true,
+            tsBuildInfoFile: '.turbo/typecheck.tap.tsbuildinfo'
+        },
+        include: [
+            ...testRoots.flatMap((root)=>[
+                    `${root}/**/*.ts`,
+                    `${root}/**/*.tsx`
+                ]),
+            configPath
+        ],
+        exclude: [
+            'node_modules',
+            'dist',
+            'build',
+            '.tap-build',
+            '.tap-legacy'
+        ]
+    });
+}
+function smokeTest(packageId, sdkVersion, rows) {
+    const cells = [
+        ...new Set(rows.map((row)=>`${row.surface}\0${row.target}`))
+    ].sort(compareCodePoints);
+    const profileIds = [
+        ...new Set(rows.map((row)=>row.profile))
+    ].sort(compareCodePoints);
+    const matrixEntryIds = [
+        ...new Set(rows.map((row)=>row.id))
+    ].sort(compareCodePoints);
+    return `import { expect, test } from '${SDK_PACKAGE}/testing/rstest';\n\nconst PACKAGE_ID = ${JSON.stringify(packageId)};\nconst SDK_VERSION = ${JSON.stringify(sdkVersion)};\nconst SURFACE_TARGET_CELLS = new Set(${JSON.stringify(cells)});\nconst PROFILE_IDS = new Set(${JSON.stringify(profileIds)});\nconst MATRIX_ENTRY_IDS = new Set(${JSON.stringify(matrixEntryIds)});\nconst SHA256 = /^[a-f0-9]{64}$/u;\nconst SEMVER = /^\\d+\\.\\d+\\.\\d+(?:-[0-9A-Za-z.-]+)?(?:\\+[0-9A-Za-z.-]+)?$/u;\n\ntest('mounts the exact declared TAP cell with reproducible provenance', async ({ surface, tap }) => {\n  expect(tap.packageId).toBe(PACKAGE_ID);\n  expect(SURFACE_TARGET_CELLS.has(\`\${tap.surfaceId}\\0\${tap.target}\`)).toBe(true);\n  expect(PROFILE_IDS.has(tap.profileId)).toBe(true);\n  expect(MATRIX_ENTRY_IDS.has(tap.matrixEntryId)).toBe(true);\n  expect(tap.seed).toBe(tap.environment.seed);\n  expect(tap.adapterVersion).toBe(SDK_VERSION);\n  expect(tap.hostVersion).toMatch(SEMVER);\n  expect(tap.hostContractVersion).toMatch(/^\\d+$/u);\n  expect(tap.runnerName).toBe('rstest');\n  expect(tap.runnerVersion).toMatch(SEMVER);\n  expect(tap.sourceDigest).toMatch(SHA256);\n  expect(tap.testBundleDigest).toMatch(SHA256);\n  expect(tap.descriptorDigest).toMatch(SHA256);\n  expect(tap.policyDigest).toMatch(SHA256);\n  if (tap.mode === 'surface') expect(tap.fixtureDigest).toMatch(SHA256);\n  else expect(tap.fixtureDigest).toBeUndefined();\n\n  await tap.control.remountSurface();\n  await expect(surface.locator('body')).toBeVisible();\n});\n`;
+}
+function collectProfileFiles(descriptor, key) {
+    const values = new Set();
+    for (const [profileName, profileValue] of Object.entries(descriptorProfiles(descriptor))){
+        const profile = requireObject(profileValue, `profile ${profileName}`);
+        for (const file of optionalStringArray(profile[key], `profile ${profileName} ${key}`))values.add(normalizeRelativePath(file, `profile ${profileName} ${key}`));
+    }
+    return [
+        ...values
+    ].sort(compareCodePoints);
+}
+function scaffoldFiles(descriptor, descriptorPath, sdkVersion) {
+    const configPath = normalizeRelativePath(requireString(descriptor.configPath, 'tap.test.json configPath'), 'tap.test.json configPath');
+    const rows = matrixRows(descriptor);
+    const rootTestMatch = descriptorTestMatch(descriptor);
+    const testMatch = rootTestMatch.length > 0 ? rootTestMatch : [
+        ...new Set(rows.flatMap((row)=>row.testMatch))
+    ].sort(compareCodePoints);
+    if (0 === testMatch.length) throw new Error('tap.test.json must declare an effective root or matrix testMatch for scaffolding.');
+    const testRoots = [
+        ...new Set(testMatch.map(testRootFromPattern))
+    ].sort(compareCodePoints);
+    const files = [
+        {
+            relativePath: descriptorPath,
+            content: jsonFile(descriptor)
+        },
+        {
+            relativePath: configPath,
+            content: configFile()
+        },
+        {
+            relativePath: 'tsconfig.tap-test.json',
+            content: tapTsconfig(configPath, testRoots)
+        },
+        {
+            relativePath: `${testRoots[0]}/tap-surface.smoke.test.ts`,
+            content: smokeTest(requireString(descriptor.packageId, 'tap.test.json packageId'), sdkVersion, rows)
+        },
+        ...collectProfileFiles(descriptor, 'fixtureFiles').map((relativePath)=>({
+                relativePath,
+                content: '{}\n'
+            })),
+        ...collectProfileFiles(descriptor, 'httpRouteFiles').map((relativePath)=>({
+                relativePath,
+                content: '[]\n'
+            }))
+    ];
+    const unique = new Map();
+    for (const file of files){
+        const relativePath = normalizeRelativePath(file.relativePath, 'Scaffold file');
+        const existing = unique.get(relativePath);
+        if (existing && existing.content !== file.content) throw new Error(`Scaffold planned conflicting content for ${relativePath}.`);
+        unique.set(relativePath, {
+            ...file,
+            relativePath
+        });
+    }
+    return [
+        ...unique.values()
+    ].sort((left, right)=>compareCodePoints(left.relativePath, right.relativePath));
+}
+async function pathKind(root, relativePath) {
+    const absolute = projectPath(root, relativePath);
+    const stats = await (0, __rspack_external_node_fs_promises_3b710708.lstat)(absolute).catch((error)=>{
+        if (null !== error && 'object' == typeof error && 'code' in error && 'ENOENT' === error.code) return;
+        throw error;
+    });
+    if (!stats) return 'missing';
+    if (!stats.isFile() || stats.isSymbolicLink()) throw new Error(`Scaffold destination must be a regular file or absent: ${relativePath}`);
+    const resolved = await (0, __rspack_external_node_fs_promises_3b710708.realpath)(absolute);
+    if (resolved !== root && !resolved.startsWith(`${root}${__rspack_external_node_path_806ed179["default"].sep}`)) throw new Error(`Scaffold destination escapes the source root: ${relativePath}`);
+    return 'regular';
+}
+async function ensureSafeDirectory(root, directory) {
+    const relative = __rspack_external_node_path_806ed179["default"].relative(root, directory);
+    if ('' === relative) return;
+    let current = root;
+    for (const segment of relative.split(__rspack_external_node_path_806ed179["default"].sep)){
+        current = __rspack_external_node_path_806ed179["default"].join(current, segment);
+        const stats = await (0, __rspack_external_node_fs_promises_3b710708.lstat)(current).catch((error)=>{
+            if (null !== error && 'object' == typeof error && 'code' in error && 'ENOENT' === error.code) return;
+            throw error;
+        });
+        if (!stats) {
+            await (0, __rspack_external_node_fs_promises_3b710708.mkdir)(current);
+            continue;
+        }
+        if (!stats.isDirectory() || stats.isSymbolicLink()) throw new Error(`Scaffold directory is not a regular directory: ${current}`);
+    }
+}
+async function atomicCreateFiles(root, files) {
+    const staged = [];
+    const created = [];
+    try {
+        for (const file of files){
+            const destination = projectPath(root, file.relativePath);
+            await ensureSafeDirectory(root, __rspack_external_node_path_806ed179["default"].dirname(destination));
+            const temporary = `${destination}.tap-scaffold-${__rspack_external_node_crypto_2e7c4b46["default"].randomUUID()}.tmp`;
+            const handle = await (0, __rspack_external_node_fs_promises_3b710708.open)(temporary, 'wx', 384);
+            try {
+                await handle.writeFile(file.content, 'utf8');
+                await handle.sync();
+            } finally{
+                await handle.close();
+            }
+            staged.push({
+                destination,
+                temporary
+            });
+        }
+        for (const file of staged){
+            await (0, __rspack_external_node_fs_promises_3b710708.link)(file.temporary, file.destination);
+            created.push(file.destination);
+            await (0, __rspack_external_node_fs_promises_3b710708.chmod)(file.destination, 420);
+        }
+    } catch (error) {
+        await Promise.all(created.map((destination)=>(0, __rspack_external_node_fs_promises_3b710708.unlink)(destination)));
+        throw error;
+    } finally{
+        await Promise.all(staged.map((file)=>(0, __rspack_external_node_fs_promises_3b710708.rm)(file.temporary, {
+                force: true
+            })));
+    }
+}
+async function optionalDescriptor(root, relativePath) {
+    if (await pathKind(root, relativePath) === 'missing') return;
+    return readJsonProjectFile(root, relativePath);
+}
+async function scaffoldTapTests(options, schemas) {
+    const root = await canonicalRoot(options.root);
+    const inventory = await inspectTapManifest({
+        ...options,
+        root
+    }, schemas);
+    const descriptorPath = normalizeRelativePath(options.descriptorPath ?? 'tap.test.json', "Descriptor path");
+    const existing = await optionalDescriptor(root, descriptorPath);
+    let descriptor;
+    if (existing) {
+        const object = requireObject(existing.value, existing.path);
+        if (1 === object.schemaVersion) throw new Error(`${descriptorPath} uses schemaVersion 1; run "tap-miniapp-test migrate" first.`);
+        assertSchema(existing.value, schemas.testDescriptor, existing.path);
+        descriptor = object;
+    } else {
+        descriptor = scaffoldDescriptor(inventory);
+        assertSchema(descriptor, schemas.testDescriptor, descriptorPath);
+    }
+    if (descriptor.packageId !== inventory.packageId) throw new Error(`${descriptorPath} packageId does not match manifest.package.packageId.`);
+    const plan = scaffoldFiles(descriptor, descriptorPath, inventory.sdkVersion);
+    const missing = [];
+    const statuses = [];
+    for (const file of plan){
+        const kind = await pathKind(root, file.relativePath);
+        if ('missing' === kind) {
+            missing.push(file);
+            statuses.push({
+                path: file.relativePath,
+                status: options.check ? 'missing' : 'created'
+            });
+        } else statuses.push({
+            path: file.relativePath,
+            status: 'preserved'
+        });
+    }
+    if (!options.check && missing.length > 0) await atomicCreateFiles(root, missing);
+    return {
+        schemaVersion: 1,
+        command: 'scaffold',
+        ok: !options.check || 0 === missing.length,
+        check: options.check ?? false,
+        packageId: inventory.packageId,
+        root,
+        files: statuses
+    };
+}
+function valuesOutsideAllowlist(values, allowlist) {
+    const allowed = new Set(allowlist);
+    return [
+        ...new Set(values)
+    ].filter((entry)=>!allowed.has(entry)).sort(compareCodePoints);
+}
+function authorizationAllowsCapability(allowed, capability) {
+    if (allowed.has(capability)) return true;
+    const effect = /^effect:([a-z0-9][a-z0-9._-]*):\S+$/u.exec(capability);
+    return null !== effect && allowed.has(`effect:${effect[1]}:*`);
+}
+function valuesOutsideAuthorizationAllowlist(values, allowlist) {
+    const allowed = new Set(allowlist);
+    return [
+        ...new Set(values)
+    ].filter((entry)=>!authorizationAllowsCapability(allowed, entry)).sort(compareCodePoints);
+}
+function cellKey(surface, target) {
+    return `${surface}\0${target}`;
+}
+function capabilityIsWaived(descriptor, capability, now) {
+    return requireArray(descriptor.waivers ?? [], 'tap.test.json waivers').some((waiverValue)=>{
+        const waiver = requireObject(waiverValue, 'tap.test.json waiver');
+        if (waiver.capability !== capability) return false;
+        if (void 0 === waiver.expiresAt) return false;
+        const expiresAt = requireString(waiver.expiresAt, 'waiver expiresAt');
+        const expiration = Date.parse(expiresAt);
+        return Number.isFinite(expiration) && expiration > now.getTime();
+    });
+}
+function rowDeniesCapability(row, capability) {
+    if (row.deniedActions.includes('*')) return true;
+    if (capability.startsWith('action:')) {
+        const action = capability.slice(7);
+        return row.deniedActions.includes(action);
+    }
+    if (!capability.startsWith('effect:')) return false;
+    const effectKind = capability.split(':', 3)[1] ?? '';
+    if ('credentials' === effectKind) return row.deniedActions.includes('credentials.use');
+    return [
+        'external-network',
+        'host-http',
+        'network'
+    ].includes(effectKind) && ('http-denied' === row.permissionScenario || row.deniedActions.includes('network.request'));
+}
+function globToRegExp(pattern) {
+    const confined = normalizeRelativePath(pattern, 'testMatch');
+    let source = '^';
+    for(let index = 0; index < confined.length; index += 1){
+        const character = confined[index];
+        if ('*' === character) {
+            if ('*' === confined[index + 1]) {
+                index += 1;
+                if ('/' === confined[index + 1]) {
+                    index += 1;
+                    source += '(?:.*/)?';
+                } else source += '.*';
+            } else source += '[^/]*';
+            continue;
+        }
+        if ('?' === character) {
+            source += '[^/]';
+            continue;
+        }
+        if ('[' === character) {
+            const closing = confined.indexOf(']', index + 1);
+            if (-1 === closing) throw new Error(`testMatch has an unterminated character class: ${pattern}`);
+            const body = confined.slice(index + 1, closing);
+            if (0 === body.length || body.includes('/') || body.includes('\\') || body.includes('[')) throw new Error(`testMatch has an unsafe character class: ${pattern}`);
+            const negated = body.startsWith('!') ? `^${body.slice(1)}` : body;
+            source += `[${negated.replaceAll('^', '\\^')}]`;
+            index = closing;
+            continue;
+        }
+        if ('{' === character) {
+            const closing = confined.indexOf('}', index + 1);
+            if (-1 === closing) throw new Error(`testMatch has an unterminated alternation: ${pattern}`);
+            const alternatives = confined.slice(index + 1, closing).split(',');
+            if (alternatives.length < 2 || alternatives.some((entry)=>0 === entry.length || !/^[a-zA-Z0-9._-]+$/u.test(entry))) throw new Error(`testMatch has an unsafe alternation: ${pattern}`);
+            source += `(?:${alternatives.join('|')})`;
+            index = closing;
+            continue;
+        }
+        source += /[\\^$+.()|{}]/u.test(character) ? `\\${character}` : character;
+    }
+    source += '$';
+    return new RegExp(source, 'u');
+}
+async function collectTestFiles(root) {
+    const files = [];
+    const excludedDirectories = new Set([
+        '.git',
+        '.tap-build',
+        '.tap-legacy',
+        '.turbo',
+        'build',
+        'dist',
+        'node_modules'
+    ]);
+    const visit = async (directory)=>{
+        const entries = await (0, __rspack_external_node_fs_promises_3b710708.readdir)(directory, {
+            withFileTypes: true
+        });
+        entries.sort((left, right)=>compareCodePoints(left.name, right.name));
+        for (const entry of entries){
+            if (entry.isSymbolicLink()) continue;
+            const absolute = __rspack_external_node_path_806ed179["default"].join(directory, entry.name);
+            if (entry.isDirectory()) {
+                if (!excludedDirectories.has(entry.name)) await visit(absolute);
+                continue;
+            }
+            if (entry.isFile()) {
+                if (/\.(?:test|spec)\.[cm]?[jt]sx?$/u.test(entry.name)) {
+                    files.push(__rspack_external_node_path_806ed179["default"].relative(root, absolute).split(__rspack_external_node_path_806ed179["default"].sep).join('/'));
+                    if (files.length > MAX_SCANNED_TEST_FILES) throw new Error(`Test discovery exceeds ${MAX_SCANNED_TEST_FILES} files.`);
+                }
+            }
+        }
+    };
+    await visit(root);
+    return files;
+}
+function hasSurfaceApplicabilityBranch(source) {
+    return /if\s*\([^)]*\btap\.surfaceId\b[^)]*\)/su.test(source) || /switch\s*\(\s*tap\.surfaceId\s*\)/su.test(source) || /\btap\.surfaceId\b[^\n?]{0,160}\?/u.test(source) || /\breturn\b[^\n;]{0,160}\btap\.surfaceId\b/u.test(source);
+}
+function dependencyVersions(packageJson, dependency) {
+    const versions = [];
+    for (const field of [
+        'dependencies',
+        'devDependencies',
+        'optionalDependencies',
+        'peerDependencies'
+    ]){
+        const dependencies = packageJson[field];
+        if (void 0 === dependencies) continue;
+        const record = requireObject(dependencies, `package.json ${field}`);
+        const version = record[dependency];
+        if (void 0 !== version) versions.push({
+            field,
+            version: requireString(version, `package.json ${field}.${dependency}`)
+        });
+    }
+    return versions;
+}
+function diagnostic(diagnostics, code, message, relativePath, severity = 'error') {
+    diagnostics.push({
+        code,
+        severity,
+        message,
+        ...relativePath ? {
+            path: relativePath
+        } : {}
+    });
+}
+async function validateDescriptorFiles(root, descriptor, diagnostics) {
+    const configPath = normalizeRelativePath(requireString(descriptor.configPath, 'tap.test.json configPath'), 'tap.test.json configPath');
+    for (const required of [
+        configPath,
+        'tsconfig.tap-test.json'
+    ])try {
+        const file = await readProjectFile(root, required);
+        if (required === configPath && (!/\bdefineTapRstestConfig\b/u.test(file.source) || !/['"]@theaiplatform\/miniapp-sdk\/testing\/rstest-config['"]/u.test(file.source))) diagnostic(diagnostics, 'config.deterministic-helper-required', `Rstest TAP config must import and use defineTapRstestConfig from ${SDK_PACKAGE}/testing/rstest-config so Test Lab owns isolation, concurrency, retries, environment, and the default timeout.`, required);
+    } catch (error) {
+        diagnostic(diagnostics, 'file.missing-or-unsafe', error instanceof Error ? error.message : String(error), required);
+    }
+    for (const file of collectProfileFiles(descriptor, 'fixtureFiles'))try {
+        const document = await readJsonProjectFile(root, file);
+        if (!isJsonObject(document.value)) throw new Error(`${file} must contain a fixture seed JSON object.`);
+    } catch (error) {
+        diagnostic(diagnostics, 'fixture.invalid', error instanceof Error ? error.message : String(error), file);
+    }
+    for (const file of collectProfileFiles(descriptor, 'httpRouteFiles'))try {
+        const document = await readJsonProjectFile(root, file);
+        if (!Array.isArray(document.value)) throw new Error(`${file} must contain an HTTP route JSON array.`);
+    } catch (error) {
+        diagnostic(diagnostics, 'http-routes.invalid', error instanceof Error ? error.message : String(error), file);
+    }
+}
+async function validateMatrixTestApplicability(root, rows, diagnostics) {
+    const testFiles = await collectTestFiles(root);
+    const matchers = new Map();
+    const matches = (pattern, file)=>{
+        let matcher = matchers.get(pattern);
+        if (!matcher) {
+            matcher = globToRegExp(pattern);
+            matchers.set(pattern, matcher);
+        }
+        return matcher.test(file);
+    };
+    for (const row of rows){
+        if (0 === row.testMatch.length) {
+            diagnostic(diagnostics, 'matrix.test-match-missing', `Matrix ${row.id} has no effective testMatch.`, 'tap.test.json');
+            continue;
+        }
+        if (!testFiles.some((file)=>row.testMatch.some((glob)=>matches(glob, file)))) diagnostic(diagnostics, 'matrix.test-match-empty', `Matrix ${row.id} testMatch selects no test files.`, 'tap.test.json');
+    }
+    for (const file of testFiles){
+        const applicableRows = rows.filter((row)=>row.testMatch.some((glob)=>matches(glob, file)));
+        const surfaces = new Set(applicableRows.map((row)=>row.surface));
+        if (surfaces.size < 2) continue;
+        const source = await (0, __rspack_external_node_fs_promises_3b710708.readFile)(projectPath(root, file), 'utf8');
+        if (hasSurfaceApplicabilityBranch(source)) diagnostic(diagnostics, 'test.surface-branch', `${file} branches or returns on tap.surfaceId while matching ${surfaces.size} surfaces. Split the cases into surface-specific files and express applicability with matrix.testMatch.`, file);
+    }
+}
+function validateMatrixCoverage(inventory, descriptor, rows, diagnostics, now) {
+    for (const waiverValue of requireArray(descriptor.waivers ?? [], 'tap.test.json waivers')){
+        const waiver = requireObject(waiverValue, 'tap.test.json waiver');
+        if (void 0 === waiver.expiresAt) diagnostic(diagnostics, 'waiver.expiry-required', `Waiver for ${requireString(waiver.capability, 'waiver capability')} must declare a future expiresAt. Open-ended waivers never satisfy denied/error coverage.`, 'tap.test.json');
+    }
+    const surfaces = new Map(inventory.surfaces.map((surface)=>[
+            surface.id,
+            surface
+        ]));
+    const cells = new Map();
+    for (const surface of inventory.surfaces)for (const target of surface.targets)cells.set(cellKey(surface.id, target), surface);
+    for (const row of rows){
+        const surface = surfaces.get(row.surface);
+        if (!surface || !surface.targets.includes(row.target)) {
+            diagnostic(diagnostics, 'matrix.unknown-cell', `Matrix ${row.id} selects undeclared surface×target ${row.surface}×${row.target}.`, 'tap.test.json');
+            continue;
+        }
+        const declaredCapabilities = new Set([
+            ...surface.authorizationActions.map((action)=>`action:${action}`),
+            ...surface.authorizationEffects
+        ]);
+        const undeclaredCapabilities = row.capabilities.filter((capability)=>!authorizationAllowsCapability(declaredCapabilities, capability));
+        if (undeclaredCapabilities.length > 0) diagnostic(diagnostics, 'matrix.capability-not-authorized', `Matrix ${row.id} names capabilities absent from ${row.surface} authorization: ${JSON.stringify(undeclaredCapabilities)}.`, 'tap.test.json');
+    }
+    for (const [key, surface] of cells){
+        const separator = key.indexOf('\0');
+        const surfaceId = key.slice(0, separator);
+        const target = key.slice(separator + 1);
+        const applicable = rows.filter((row)=>row.surface === surfaceId && row.target === target);
+        const positive = applicable.filter((row)=>0 === row.deniedActions.length);
+        if (1 !== positive.length) diagnostic(diagnostics, 'matrix.positive-cell-count', `Surface×target ${surfaceId}×${target} must have exactly one positive matrix entry; found ${positive.length}.`, 'tap.test.json');
+        const declaredCapabilities = [
+            ...surface.authorizationActions.map((action)=>`action:${action}`),
+            ...surface.authorizationEffects
+        ];
+        for (const capability of declaredCapabilities){
+            const named = positive.some((row)=>row.capabilities.includes(capability));
+            if (!named) diagnostic(diagnostics, 'coverage.capability-unnamed', `The positive matrix entry for ${surfaceId}×${target} must name declared capability ${capability}. Matrix capabilities are descriptor requirements and cannot rely on ambient manifest authority.`, 'tap.test.json');
+        }
+        for (const capability of surface.highRiskCapabilities){
+            const denied = applicable.some((row)=>row.capabilities.includes(capability) && rowDeniesCapability(row, capability));
+            if (!denied && !capabilityIsWaived(descriptor, capability, now)) {
+                const guidance = capability.startsWith('action:') ? `Add a denied/error row with capabilities ["${capability}"] and deniedActions ["${capability.slice(7)}"].` : /^effect:(?:external-network|host-http|network):/u.test(capability) ? `Add an HTTP-denied error row with capabilities ["${capability}"], permissionScenario "http-denied", and deniedActions ["network.request"].` : /^effect:credentials:/u.test(capability) ? `Add a credential-denied error row with capabilities ["${capability}"], permissionScenario "deny:credentials.use", and deniedActions ["credentials.use"].` : `Add an all-denied error row with capabilities ["${capability}"] and deniedActions ["*"], or use an explicit waiver when no action can express this host-effect denial.`;
+                diagnostic(diagnostics, 'coverage.denied-case-missing', `Missing real denied/error coverage for ${capability} on ${surfaceId}×${target}. ${guidance}`, 'tap.test.json');
+            }
+        }
+    }
+    const profiles = descriptorProfiles(descriptor);
+    for (const [profileName, profileValue] of Object.entries(profiles)){
+        const profile = requireObject(profileValue, `profile ${profileName}`);
+        const surfaceId = requireString(profile.surface, `profile ${profileName} surface`);
+        const surface = surfaces.get(surfaceId);
+        if (!surface) continue;
+        const requiredEffects = optionalStringArray(profile.requiredEffects, `profile ${profileName} requiredEffects`);
+        const unknownEffects = valuesOutsideAuthorizationAllowlist(requiredEffects, surface.authorizationEffects);
+        if (unknownEffects.length > 0) diagnostic(diagnostics, 'profile.required-effects-drift', `Profile ${profileName} requires effects absent from ${surfaceId} authorization.effects: ${JSON.stringify(unknownEffects)}.`, 'tap.test.json');
+        const requiredOrigins = optionalStringArray(profile.requiredOrigins, `profile ${profileName} requiredOrigins`);
+        const unknownOrigins = valuesOutsideAllowlist(requiredOrigins, surface.requiredOrigins);
+        if (unknownOrigins.length > 0) diagnostic(diagnostics, 'profile.required-origins-drift', `Profile ${profileName} requires origins absent from ${surfaceId} authorization.effects: ${JSON.stringify(unknownOrigins)}.`, 'tap.test.json');
+    }
+}
+async function doctorTapTests(options, schemas, sdkVersion, now = new Date()) {
+    const root = await canonicalRoot(options.root);
+    const diagnostics = [];
+    let inventory;
+    let descriptor;
+    try {
+        inventory = await inspectTapManifest({
+            ...options,
+            root
+        }, schemas);
+    } catch (error) {
+        diagnostic(diagnostics, 'manifest.invalid', error instanceof Error ? error.message : String(error), options.manifestPath ?? 'manifest.tap.json');
+    }
+    try {
+        const descriptorPath = options.descriptorPath ?? 'tap.test.json';
+        const document = await readJsonProjectFile(root, descriptorPath);
+        const object = requireObject(document.value, descriptorPath);
+        if (1 === object.schemaVersion) throw new Error(`${descriptorPath} uses schemaVersion 1; run "tap-miniapp-test migrate".`);
+        assertSchema(document.value, schemas.testDescriptor, descriptorPath);
+        descriptor = object;
+    } catch (error) {
+        diagnostic(diagnostics, "descriptor.invalid", error instanceof Error ? error.message : String(error), options.descriptorPath ?? 'tap.test.json');
+    }
+    try {
+        const packageDocument = await readJsonProjectFile(root, 'package.json');
+        const packageJson = requireObject(packageDocument.value, 'package.json');
+        const versions = dependencyVersions(packageJson, SDK_PACKAGE);
+        if (1 !== versions.length || versions[0]?.version !== sdkVersion) diagnostic(diagnostics, 'sdk.version-not-exact', `package.json must declare exactly one ${SDK_PACKAGE} dependency pinned to ${sdkVersion}; found ${0 === versions.length ? 'none' : versions.map((entry)=>`${entry.field}:${entry.version}`).join(', ')}.`, 'package.json');
+    } catch (error) {
+        diagnostic(diagnostics, 'package-json.invalid', error instanceof Error ? error.message : String(error), 'package.json');
+    }
+    if (inventory && inventory.sdkVersion !== sdkVersion) diagnostic(diagnostics, 'manifest.sdk-version-not-exact', `manifest.compatibility.tapSdk must equal the executing SDK version ${sdkVersion}; found ${inventory.sdkVersion}. Ranges and tags are not accepted.`, options.manifestPath ?? 'manifest.tap.json');
+    if (inventory && descriptor) {
+        if (descriptor.packageId !== inventory.packageId) diagnostic(diagnostics, "descriptor.package-id-mismatch", `tap.test.json packageId must equal ${inventory.packageId}.`, options.descriptorPath ?? 'tap.test.json');
+        let rows = [];
+        try {
+            rows = matrixRows(descriptor);
+            validateMatrixCoverage(inventory, descriptor, rows, diagnostics, now);
+            await validateDescriptorFiles(root, descriptor, diagnostics);
+            await validateMatrixTestApplicability(root, rows, diagnostics);
+        } catch (error) {
+            diagnostic(diagnostics, "descriptor.semantic-error", error instanceof Error ? error.message : String(error), options.descriptorPath ?? 'tap.test.json');
+        }
+    }
+    diagnostics.sort((left, right)=>{
+        const byCode = compareCodePoints(left.code, right.code);
+        return 0 !== byCode ? byCode : compareCodePoints(left.path ?? '', right.path ?? '');
+    });
+    return {
+        schemaVersion: 1,
+        command: 'doctor',
+        ok: diagnostics.every((entry)=>'error' !== entry.severity),
+        ...inventory ? {
+            packageId: inventory.packageId
+        } : {},
+        sdkVersion,
+        root,
+        diagnostics
+    };
+}
+async function atomicReplaceFile(destination, content) {
+    const temporary = `${destination}.tap-migrate-${__rspack_external_node_crypto_2e7c4b46["default"].randomUUID()}.tmp`;
+    const handle = await (0, __rspack_external_node_fs_promises_3b710708.open)(temporary, 'wx', 384);
+    try {
+        await handle.writeFile(content, 'utf8');
+        await handle.sync();
+    } finally{
+        await handle.close();
+    }
+    try {
+        await (0, __rspack_external_node_fs_promises_3b710708.chmod)(temporary, 420);
+        await (0, __rspack_external_node_fs_promises_3b710708.rename)(temporary, destination);
+    } finally{
+        await (0, __rspack_external_node_fs_promises_3b710708.rm)(temporary, {
+            force: true
+        });
+    }
+}
+async function migrateTapTests(options, schemas) {
+    const root = await canonicalRoot(options.root);
+    const descriptorPath = normalizeRelativePath(options.descriptorPath ?? 'tap.test.json', "Descriptor path");
+    const source = await readJsonProjectFile(root, descriptorPath);
+    const object = requireObject(source.value, descriptorPath);
+    if (2 === object.schemaVersion) {
+        assertSchema(source.value, schemas.testDescriptor, descriptorPath);
+        return {
+            schemaVersion: 1,
+            command: 'migrate',
+            ok: true,
+            changed: false,
+            dryRun: options.dryRun ?? false,
+            descriptorPath,
+            descriptor: object
+        };
+    }
+    const inventory = await inspectTapManifest({
+        ...options,
+        root
+    }, schemas);
+    const descriptor = expandMigratedDescriptor(source.value, inventory);
+    assertSchema(descriptor, schemas.testDescriptor, descriptorPath);
+    const backupPath = descriptorPath.replace(/\.json$/u, '.v1.json');
+    if (backupPath === descriptorPath) throw new Error("Descriptor path must end in .json for migration backup.");
+    const backupKind = await pathKind(root, backupPath);
+    if ('regular' === backupKind) {
+        const backup = await readProjectFile(root, backupPath);
+        if (backup.source !== source.source) throw new Error(`Migration backup ${backupPath} already exists with different content.`);
+    }
+    if (!options.dryRun) {
+        let createdBackup = false;
+        try {
+            if ('missing' === backupKind) {
+                await atomicCreateFiles(root, [
+                    {
+                        relativePath: backupPath,
+                        content: source.source
+                    }
+                ]);
+                createdBackup = true;
+            }
+            await atomicReplaceFile(projectPath(root, descriptorPath), jsonFile(descriptor));
+        } catch (error) {
+            if (createdBackup) await (0, __rspack_external_node_fs_promises_3b710708.unlink)(projectPath(root, backupPath));
+            throw error;
+        }
+    }
+    return {
+        schemaVersion: 1,
+        command: 'migrate',
+        ok: true,
+        changed: true,
+        dryRun: options.dryRun ?? false,
+        descriptorPath,
+        backupPath,
+        descriptor
+    };
+}
+const COMMANDS = [
+    'doctor',
+    'list',
+    'matrix',
+    'scaffold',
+    'migrate'
+];
+const HELP = `The AI Platform miniapp test tooling
+
+Usage:
+  tap-miniapp-test doctor [options]
+  tap-miniapp-test list [options]
+  tap-miniapp-test matrix [options]
+  tap-miniapp-test scaffold [--check] [options]
+  tap-miniapp-test migrate [--dry-run] [options]
+
+Options:
+  --root <path>         Miniapp project root (default: current directory)
+  --manifest <path>     Package manifest (default: manifest.tap.json)
+  --descriptor <path>   Test descriptor (default: tap.test.json)
+  --json                Emit one machine-readable JSON document
+  --check               Check scaffold completeness without writing
+  --dry-run             Print migration output without writing
+  --help                Show this help
+`;
+function isCommand(value) {
+    return COMMANDS.some((command)=>command === value);
+}
+function optionValue(args, index, option) {
+    const value = args[index + 1];
+    if (!value || value.startsWith('--')) throw new Error(`${option} requires a value.`);
+    return value;
+}
+function parseArgs(args) {
+    if (0 === args.length || args.includes('--help') || args.includes('-h')) return 'help';
+    const command = args[0];
+    if (!command || !isCommand(command)) throw new Error(`Unknown command ${JSON.stringify(command ?? '')}. Expected ${COMMANDS.join(', ')}.`);
+    let root = process.cwd();
+    let manifestPath;
+    let descriptorPath;
+    let check = false;
+    let dryRun = false;
+    let json = false;
+    for(let index = 1; index < args.length; index += 1){
+        const argument = args[index];
+        if ('--json' === argument) {
+            json = true;
+            continue;
+        }
+        if ('--check' === argument) {
+            check = true;
+            continue;
+        }
+        if ('--dry-run' === argument) {
+            dryRun = true;
+            continue;
+        }
+        if ('--root' === argument) {
+            root = optionValue(args, index, argument);
+            index += 1;
+            continue;
+        }
+        if ('--manifest' === argument) {
+            manifestPath = optionValue(args, index, argument);
+            index += 1;
+            continue;
+        }
+        if ("--descriptor" === argument) {
+            descriptorPath = optionValue(args, index, argument);
+            index += 1;
+            continue;
+        }
+        throw new Error(`Unknown option ${JSON.stringify(argument)}.`);
+    }
+    if (check && 'scaffold' !== command) throw new Error('--check is supported only by scaffold.');
+    if (dryRun && 'migrate' !== command) throw new Error('--dry-run is supported only by migrate.');
+    return {
+        command,
+        root,
+        ...manifestPath ? {
+            manifestPath
+        } : {},
+        ...descriptorPath ? {
+            descriptorPath
+        } : {},
+        check,
+        dryRun,
+        json
+    };
+}
+function projectOptions(options) {
+    return {
+        root: options.root,
+        ...options.manifestPath ? {
+            manifestPath: options.manifestPath
+        } : {},
+        ...options.descriptorPath ? {
+            descriptorPath: options.descriptorPath
+        } : {}
+    };
+}
+function printJson(value) {
+    process.stdout.write(`${JSON.stringify(value, null, 2)}\n`);
+}
+function printInventory(inventory) {
+    process.stdout.write([
+        `${inventory.packageId} (SDK ${inventory.sdkVersion})`,
+        `Targets: ${inventory.targets.join(', ')}`,
+        ...inventory.surfaces.map((surface)=>`- ${surface.id}: ${surface.targets.join(', ')}`),
+        ''
+    ].join('\n'));
+}
+function printRows(rows) {
+    process.stdout.write([
+        'ID\tPROFILE\tSURFACE\tTARGET\tMODE\tPERMISSION',
+        ...rows.map((row)=>[
+                row.id,
+                row.profile,
+                row.surface,
+                row.target,
+                row.mode,
+                row.permissionScenario
+            ].join('\t')),
+        ''
+    ].join('\n'));
+}
+function printDoctor(result) {
+    process.stdout.write(result.ok ? `Miniapp test project is ready for ${result.sdkVersion}.\n` : [
+        `Miniapp test project has ${result.diagnostics.length} issue(s):`,
+        ...result.diagnostics.map((entry)=>`- [${entry.code}]${entry.path ? ` ${entry.path}:` : ''} ${entry.message}`),
+        ''
+    ].join('\n'));
+}
+function printScaffold(result) {
+    process.stdout.write([
+        `${result.check ? 'Checked' : 'Scaffolded'} ${result.packageId}:`,
+        ...result.files.map((file)=>`- ${file.status}: ${file.path}`),
+        ''
+    ].join('\n'));
+}
+function printMigration(result) {
+    if (!result.changed) return void process.stdout.write(`${result.descriptorPath} already uses schemaVersion 2.\n`);
+    process.stdout.write(result.dryRun ? `${JSON.stringify(result.descriptor, null, 2)}\n` : `Migrated ${result.descriptorPath} to schemaVersion 2; preserved v1 at ${result.backupPath}.\n`);
+}
+async function run(options) {
+    const [schemas, sdkVersion] = await Promise.all([
+        loadTapToolingSchemas(new URL('../../config-schema.json', import.meta.url), new URL('../testing/tap.test.schema.json', import.meta.url)),
+        (0, __rspack_external_node_fs_promises_3b710708.readFile)(new URL('../../package.json', import.meta.url), 'utf8').then(parseTapSdkPackageVersion)
+    ]);
+    const project = projectOptions(options);
+    if ('doctor' === options.command) {
+        const result = await doctorTapTests(project, schemas, sdkVersion);
+        options.json ? printJson(result) : printDoctor(result);
+        return result.ok;
+    }
+    if ('list' === options.command) {
+        const inventory = await inspectTapManifest(project, schemas);
+        const result = {
+            schemaVersion: 1,
+            command: 'list',
+            ok: true,
+            ...inventory
+        };
+        options.json ? printJson(result) : printInventory(inventory);
+        return true;
+    }
+    if ('matrix' === options.command) {
+        const result = await inspectTapMatrix(project, schemas);
+        const output = {
+            schemaVersion: 1,
+            command: 'matrix',
+            ok: true,
+            rows: result.rows
+        };
+        options.json ? printJson(output) : printRows(result.rows);
+        return true;
+    }
+    if ('scaffold' === options.command) {
+        const result = await scaffoldTapTests({
+            ...project,
+            check: options.check
+        }, schemas);
+        options.json ? printJson(result) : printScaffold(result);
+        return result.ok;
+    }
+    const result = await migrateTapTests({
+        ...project,
+        dryRun: options.dryRun
+    }, schemas);
+    options.json ? printJson(result) : printMigration(result);
+    return result.ok;
+}
+async function main() {
+    let parsed;
+    try {
+        parsed = parseArgs(process.argv.slice(2));
+        if ('help' === parsed) return void process.stdout.write(HELP);
+        if (!await run(parsed)) process.exitCode = 1;
+    } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        const json = process.argv.includes('--json');
+        if (json) printJson({
+            schemaVersion: 1,
+            command: process.argv[2] ?? null,
+            ok: false,
+            error: {
+                code: 'TAP_MINIAPP_TEST_TOOLING_ERROR',
+                message
+            }
+        });
+        else process.stderr.write(`tap-miniapp-test: ${message}\n`);
+        process.exitCode = 1;
+    }
+}
+main();