@lark-project/cli/lib/utils/validate-runtime-urls.d.ts

飞书项目插件开发工具

/**
 * Runtime URL placeholder validator.
 *
 * Runtime URLs (those that the product actually requests at runtime) must be
 * real. Placeholder/example values will cause silent failures in production
 * (blank columns, broken buttons, missed events).
 *
 * This validator is deliberately static and conservative: it matches known
 * placeholder patterns but does not verify reachability. It catches the
 * common AI fabrication modes (example.com, your-server, localhost,
 * placeholder, reserved TLDs, etc.) without network side effects.
 *
 * Two severities (see `kind`):
 *   - 'invalid'     — missing / empty / not http(s):// — a structural defect.
 *                     Callers hard-block (exit 1): the config cannot be used.
 *   - 'placeholder' — looks fabricated (example.com / your-server / localhost /
 *                     <PLACEHOLDER:…> …). Callers DO NOT block — they only warn
 *                     and push as-is. This matches the documented two-step flow
 *                     (fill a placeholder at Stage Config, swap the real public
 *                     URL in later / in the developer console). The notice
 *                     discharges the duty to inform; replacing is the user's job.
 *
 * Full field taxonomy and rationale see:
 *   jy-skill/skills/meego-shared/references/url-policy.md
 *   jy-skill/skills/meego-point-config/references/apply.md (A0.5)
 */
export interface Violation {
    path: string;
    value: string;
    reason: string;
    /** 'invalid' → structural defect (block); 'placeholder' → fabricated value (notice only). */
    kind: 'invalid' | 'placeholder';
}
export declare function validateRuntimeUrls(config: Record<string, any> | null | undefined): {
    violations: Violation[];
};
/**
 * Split violations by severity so callers can block on structural defects
 * while only warning on fabricated-looking placeholders.
 */
export declare function splitViolations(violations: Violation[]): {
    invalid: Violation[];
    placeholders: Violation[];
};
/**
 * Hard-error formatting for 'invalid' violations (missing / empty / not http(s)).
 * Callers print this and exit 1 — the config is structurally unusable.
 */
export declare function formatViolations(violations: Violation[]): string;
/**
 * Non-blocking notice for 'placeholder' violations (fabricated-looking URLs).
 * Callers print this and CONTINUE — the placeholder is pushed as-is. The notice
 * exists to discharge the duty to inform: the user must swap in the real URL,
 * not the CLI to refuse. See the two-step flow in the module header.
 */
export declare function formatPlaceholderNotice(violations: Violation[]): string;