agent-scenario-loop 0.1.0

package/dist/runner/validate-project.d.ts

@@ -0,0 +1,273 @@
+#!/usr/bin/env node
+type CliArgs = {
+    config?: string | boolean;
+    out?: string | boolean;
+    platform?: string | boolean;
+    root?: string | boolean;
+    [key: string]: string | boolean | undefined;
+};
+type ProjectValidationPlan = {
+    healthStatus: string;
+    platform: string;
+    runId: string;
+    scenarioId: string;
+    scenarioPath: string;
+};
+type ProjectValidationAppHelper = {
+    missingExports: string[];
+    path: string;
+    status: 'present' | 'missing' | 'incomplete';
+};
+type ProjectValidationConfig = {
+    customDrivers: string[];
+    externalTargetDrivers: string[];
+    invalidFields: string[];
+    missingFields: string[];
+    missingSupportedDrivers: string[];
+    packageSupportedDrivers: string[];
+    path: string;
+    status: 'present' | 'missing' | 'incomplete';
+    supportedDrivers: string[];
+};
+type ProjectValidationScripts = {
+    invalidScripts: string[];
+    invalidPackageJsonScripts: string[];
+    missingPaths: string[];
+    missingPackageJsonScripts: string[];
+    mismatchedPackageJsonScripts: string[];
+    missingScripts: string[];
+    packageJsonPath: string;
+    packageJsonStatus: 'present' | 'missing' | 'incomplete';
+    path: string;
+    scriptNames: string[];
+    status: 'present' | 'missing' | 'incomplete';
+    unknownCommands: string[];
+};
+type ProjectValidationGitignore = {
+    configArtifactPatterns: string[];
+    missingConfigArtifactPatterns: string[];
+    missingPatterns: string[];
+    path: string;
+    requiredPatterns: string[];
+    snippetPath: string;
+    status: 'present' | 'missing' | 'incomplete';
+};
+type ProjectValidationNextAction = {
+    code: string;
+    message: string;
+    severity: 'error' | 'warning';
+    target: string;
+};
+type ProjectValidationResult = {
+    appHelper: ProjectValidationAppHelper;
+    config: ProjectValidationConfig;
+    configPath: string;
+    errors: string[];
+    gitignore: ProjectValidationGitignore;
+    nextActions: ProjectValidationNextAction[];
+    platform: string;
+    plans: ProjectValidationPlan[];
+    providerPaths: string[];
+    rootDir: string;
+    runnerPath: string;
+    scripts: ProjectValidationScripts;
+    scenarioCandidateDirectories: string[];
+    scenarioPaths: string[];
+    status: 'passed' | 'failed';
+    warnings: string[];
+};
+/**
+ * Prints CLI usage.
+ *
+ * @param {{write: (message: string) => unknown}} [output]
+ * @returns {void}
+ */
+declare function usage(output?: {
+    write: (message: string) => unknown;
+}): void;
+/**
+ * Parses the small flag set for the project validator.
+ *
+ * @param {string[]} argv
+ * @returns {CliArgs}
+ */
+declare function parseArgs(argv: string[]): CliArgs;
+/**
+ * Resolves scenario directories from project config plus the scaffold default.
+ *
+ * @param {{configPath: string, requestedPlatform: string, rootDir: string}} options
+ * @returns {string[]}
+ */
+declare function resolveScenarioDirectories({ configPath, requestedPlatform, rootDir, }: {
+    configPath: string;
+    requestedPlatform: string;
+    rootDir: string;
+}): string[];
+/**
+ * Lists scenario JSON files from resolved scenario directories.
+ *
+ * @param {string[]} scenarioCandidateDirectories
+ * @returns {string[]}
+ */
+declare function listScenarioFilesFromDirectories(scenarioCandidateDirectories: string[]): string[];
+/**
+ * Lists scenario JSON files from configured scenario directories.
+ *
+ * @param {{configPath: string, requestedPlatform: string, rootDir: string}} options
+ * @returns {string[]}
+ */
+declare function listScenarioFiles({ configPath, requestedPlatform, rootDir, }: {
+    configPath: string;
+    requestedPlatform: string;
+    rootDir: string;
+}): string[];
+/**
+ * Resolves platforms that should be validated for one scenario.
+ *
+ * @param {{requestedPlatform: string, scenario: Record<string, unknown>}} options
+ * @returns {string[]}
+ */
+declare function resolvePlatforms({ requestedPlatform, scenario, }: {
+    requestedPlatform: string;
+    scenario: Record<string, unknown>;
+}): string[];
+/**
+ * Builds a stable run id for one project-validation plan check.
+ *
+ * @param {{platform: string, scenarioId: string}} options
+ * @returns {string}
+ */
+declare function buildValidationRunId({ platform, scenarioId, }: {
+    platform: string;
+    scenarioId: string;
+}): string;
+/**
+ * Validates that the generated app helper is present and still exposes the expected integration API.
+ *
+ * @param {string} rootDir
+ * @returns {ProjectValidationAppHelper}
+ */
+declare function validateAppHelper(rootDir: string): ProjectValidationAppHelper;
+/**
+ * Finds known placeholder values in the initialized project config.
+ *
+ * @param {Record<string, unknown>} config
+ * @returns {string[]}
+ */
+declare function validateConfigPlaceholders(config: Record<string, unknown>): string[];
+/**
+ * Validates required project config fields for live profile execution.
+ *
+ * @param {{configPath: string, requestedPlatform: string}} options
+ * @returns {ProjectValidationConfig}
+ */
+declare function validateProjectConfig({ configPath, requestedPlatform, }: {
+    configPath: string;
+    requestedPlatform: string;
+}): ProjectValidationConfig;
+/**
+ * Validates that runtime proof artifacts are ignored by the consuming app.
+ *
+ * @param {string} rootDir
+ * @param {string} [configPath]
+ * @returns {ProjectValidationGitignore}
+ */
+declare function validateGitignore(rootDir: string, configPath?: string): ProjectValidationGitignore;
+/**
+ * Validates one generated package-script snippet against its expected lifecycle shape.
+ *
+ * @param {{command: string, scriptName: string}} options
+ * @returns {string | null}
+ */
+declare function validatePackageScriptShape({ command, scriptName, }: {
+    command: string;
+    scriptName: string;
+}): string | null;
+/**
+ * Validates the generated package-script snippets against installed CLI bins and project-local inputs.
+ *
+ * @param {{packageRoot?: string, rootDir: string}} options
+ * @returns {ProjectValidationScripts}
+ */
+declare function validatePackageScripts({ packageRoot, rootDir, }: {
+    packageRoot?: string;
+    rootDir: string;
+}): ProjectValidationScripts;
+/**
+ * Validates that generated snippets were intentionally merged into app package scripts.
+ *
+ * The generated snippet file owns canonical command shape. This check only
+ * proves the app exposes runnable script names so teams do not leave the
+ * snippets stranded under `asl/`.
+ *
+ * Direct installed-bin scripts are also compared against the generated
+ * snippets, catching stale merges while allowing source-tree wrappers.
+ *
+ * @param {{expectedScripts?: Record<string, unknown>, packageJsonPath: string}} options
+ * @returns {{invalidPackageJsonScripts: string[], missingPackageJsonScripts: string[], mismatchedPackageJsonScripts: string[], packageJsonStatus: 'present' | 'missing' | 'incomplete'}}
+ */
+declare function validatePackageJsonScripts({ expectedScripts, packageJsonPath, }: {
+    expectedScripts?: Record<string, unknown>;
+    packageJsonPath: string;
+}): {
+    invalidPackageJsonScripts: string[];
+    missingPackageJsonScripts: string[];
+    mismatchedPackageJsonScripts: string[];
+    packageJsonStatus: 'present' | 'missing' | 'incomplete';
+};
+/**
+ * Validates project-local script files referenced by evidence-provider commands.
+ *
+ * @param {{providerPaths: string[]}} options
+ * @returns {string[]}
+ */
+declare function validateProviderCommandReferences({ providerPaths, }: {
+    providerPaths: string[];
+}): string[];
+/**
+ * Builds stable agent-readable next actions from project validation facts.
+ *
+ * @param {{appHelper: ProjectValidationAppHelper, config: ProjectValidationConfig, configPath: string, gitignore: ProjectValidationGitignore, plans: ProjectValidationPlan[], providerCommandMissingPaths: string[], requestedPlatform: string, rootDir: string, runnerPath: string, scenarioPaths: string[], scripts: ProjectValidationScripts, warnings: string[]}} options
+ * @returns {ProjectValidationNextAction[]}
+ */
+declare function buildNextActions({ appHelper, config, configPath, gitignore, plans, providerCommandMissingPaths, requestedPlatform, rootDir, runnerPath, scenarioPaths, scripts, warnings, }: {
+    appHelper: ProjectValidationAppHelper;
+    config: ProjectValidationConfig;
+    configPath: string;
+    gitignore: ProjectValidationGitignore;
+    plans: ProjectValidationPlan[];
+    providerCommandMissingPaths: string[];
+    requestedPlatform: string;
+    rootDir: string;
+    runnerPath: string;
+    scenarioPaths: string[];
+    scripts: ProjectValidationScripts;
+    warnings: string[];
+}): ProjectValidationNextAction[];
+/**
+ * Validates a generated or hand-authored Agent Scenario Loop project.
+ *
+ * @param {{rootDir?: string, configPath?: string, platform?: string}} [options]
+ * @returns {Promise<ProjectValidationResult>}
+ */
+declare function validateProject(options?: {
+    configPath?: string;
+    packageRoot?: string;
+    rootDir?: string;
+    platform?: string;
+}): Promise<ProjectValidationResult>;
+/**
+ * Formats project validation output for humans and agents.
+ *
+ * @param {ProjectValidationResult} result
+ * @returns {string}
+ */
+declare function formatResult(result: ProjectValidationResult): string;
+/**
+ * Runs the project validation CLI.
+ *
+ * @returns {Promise<void>}
+ */
+declare function main(): Promise<void>;
+export { buildValidationRunId, formatResult, listScenarioFiles, listScenarioFilesFromDirectories, main, parseArgs, resolveScenarioDirectories, resolvePlatforms, usage, buildNextActions, validateConfigPlaceholders, validateProjectConfig, validateGitignore, validatePackageJsonScripts, validateProject, validateAppHelper, validatePackageScriptShape, validatePackageScripts, validateProviderCommandReferences, };
+export type { CliArgs, ProjectValidationAppHelper, ProjectValidationConfig, ProjectValidationGitignore, ProjectValidationNextAction, ProjectValidationPlan, ProjectValidationResult, ProjectValidationScripts, };