@withpica/mcp-server/dist/tools/version-guard.d.ts

MCP Server for withPICA — enables AI assistants to interact with your withPICA music catalog

/**
 * ADR-280 advisory version-as-work guard — pure logic for the MCP layer.
 *
 * This file is an in-package adaptation of two modules from the main app:
 *   lib/services/works/version-detection.ts  (detector)
 *   lib/services/works/version-detection-lookup.ts  (warning builder)
 *
 * WHY a local copy: the mcp-server tsconfig has rootDir="./src", so it
 * cannot import from ../../../lib/services. The functions are pure (no I/O,
 * no side effects), making a local copy safe. Keep in sync with the lib
 * originals when either changes.
 *
 * Doctrine (ADR-280, remix line amended by ADR-324): instrumental/acoustic/
 * live/edit variants are RECORDINGS under the parent work. A remix is kind
 * "remix": by default also a recording under the parent (version_type
 * "remix"), unless it adds writers — then it is a modified version, its own
 * work linked to the parent with original_work_id.
 */
export interface VersionGuardWork {
    id: string;
    title: string;
    iswc: string | null;
    artistId: string | null;
}
type VersionKind = "recording" | "remix";
interface VersionGuardMatch {
    parentWork: {
        id: string;
        title: string;
        iswc: string | null;
    };
    suffix: string;
    marker: string;
    suggestedVersionType: string;
    kind: VersionKind;
}
export interface VersionWarning {
    warning: string;
    suggestion: string;
    next_tool: string;
    next_args?: Record<string, unknown>;
    /** Remix only (ADR-324): the path when the remix added writers. */
    if_new_writers?: {
        suggestion: string;
        next_tool: string;
        next_args: Record<string, unknown>;
    };
}
export interface ParsedVersionTitle {
    stem: string;
    /** Canonical token for the matched suffix rule (e.g. "instrumental"). */
    suffix: string;
    /** The raw version marker as written ("MrClottey Remix"). */
    marker: string;
    /** recordings.version_type to suggest. */
    suggestedVersionType: string;
    kind: VersionKind;
}
/**
 * Parse a candidate title and return the stem + version metadata, or null if
 * the title does not match any known version suffix. Pure function, no I/O.
 * Used by the MCP create-guard to search by stem instead of list-and-scan,
 * avoiding the /admin/works?limit=100 cap on large catalogs (ADR-280 fix).
 */
export declare function parseVersionTitle(title: string): ParsedVersionTitle | null;
/**
 * Detect whether a candidate work title is a version-suffix of an existing
 * work by the same artist. Returns the match or null.
 *
 * Same-artist scoping is best-effort: when either side lacks an artistId,
 * title match alone is sufficient (advisory guard, never blocks a create).
 */
export declare function detectVersionOfExistingWork(candidate: {
    title: string;
    artistId: string | null;
}, existingWorks: VersionGuardWork[]): VersionGuardMatch | null;
/**
 * Format advisory response fields for a detected version match.
 * Always returns a value; never throws.
 */
export declare function buildVersionWarning(match: VersionGuardMatch, candidateWorkId?: string): VersionWarning;
export {};
//# sourceMappingURL=version-guard.d.ts.map