baller-maester 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,546 @@
+import { z } from 'zod';
+
+declare const StateSchema: z.ZodEnum<["draft", "canon"]>;
+type State = z.infer<typeof StateSchema>;
+
+declare const AuthRefSchema: z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
+    type: z.ZodLiteral<"none">;
+}, "strict", z.ZodTypeAny, {
+    type: "none";
+}, {
+    type: "none";
+}>, z.ZodObject<{
+    type: z.ZodLiteral<"token">;
+    envVar: z.ZodString;
+}, "strict", z.ZodTypeAny, {
+    type: "token";
+    envVar: string;
+}, {
+    type: "token";
+    envVar: string;
+}>]>;
+declare const SourceSchema: z.ZodObject<{
+    name: z.ZodString;
+    url: z.ZodEffects<z.ZodString, string, string>;
+    ref: z.ZodOptional<z.ZodString>;
+    includes: z.ZodOptional<z.ZodArray<z.ZodUnion<[z.ZodEffects<z.ZodString, string, string>, z.ZodObject<{
+        path: z.ZodEffects<z.ZodString, string, string>;
+        state: z.ZodOptional<z.ZodEnum<["draft", "canon"]>>;
+    }, "strict", z.ZodTypeAny, {
+        path: string;
+        state?: "draft" | "canon" | undefined;
+    }, {
+        path: string;
+        state?: "draft" | "canon" | undefined;
+    }>]>, "many">>;
+    auth: z.ZodOptional<z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
+        type: z.ZodLiteral<"none">;
+    }, "strict", z.ZodTypeAny, {
+        type: "none";
+    }, {
+        type: "none";
+    }>, z.ZodObject<{
+        type: z.ZodLiteral<"token">;
+        envVar: z.ZodString;
+    }, "strict", z.ZodTypeAny, {
+        type: "token";
+        envVar: string;
+    }, {
+        type: "token";
+        envVar: string;
+    }>]>>;
+    destination: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
+    description: z.ZodOptional<z.ZodString>;
+    tags: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+}, "strict", z.ZodTypeAny, {
+    name: string;
+    url: string;
+    includes?: (string | {
+        path: string;
+        state?: "draft" | "canon" | undefined;
+    })[] | undefined;
+    ref?: string | undefined;
+    auth?: {
+        type: "none";
+    } | {
+        type: "token";
+        envVar: string;
+    } | undefined;
+    destination?: string | undefined;
+    description?: string | undefined;
+    tags?: string[] | undefined;
+}, {
+    name: string;
+    url: string;
+    includes?: (string | {
+        path: string;
+        state?: "draft" | "canon" | undefined;
+    })[] | undefined;
+    ref?: string | undefined;
+    auth?: {
+        type: "none";
+    } | {
+        type: "token";
+        envVar: string;
+    } | undefined;
+    destination?: string | undefined;
+    description?: string | undefined;
+    tags?: string[] | undefined;
+}>;
+declare const CitadelConfigSchema: z.ZodEffects<z.ZodObject<{
+    schemaVersion: z.ZodLiteral<1>;
+    baseDir: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
+    sources: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        url: z.ZodEffects<z.ZodString, string, string>;
+        ref: z.ZodOptional<z.ZodString>;
+        includes: z.ZodOptional<z.ZodArray<z.ZodUnion<[z.ZodEffects<z.ZodString, string, string>, z.ZodObject<{
+            path: z.ZodEffects<z.ZodString, string, string>;
+            state: z.ZodOptional<z.ZodEnum<["draft", "canon"]>>;
+        }, "strict", z.ZodTypeAny, {
+            path: string;
+            state?: "draft" | "canon" | undefined;
+        }, {
+            path: string;
+            state?: "draft" | "canon" | undefined;
+        }>]>, "many">>;
+        auth: z.ZodOptional<z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
+            type: z.ZodLiteral<"none">;
+        }, "strict", z.ZodTypeAny, {
+            type: "none";
+        }, {
+            type: "none";
+        }>, z.ZodObject<{
+            type: z.ZodLiteral<"token">;
+            envVar: z.ZodString;
+        }, "strict", z.ZodTypeAny, {
+            type: "token";
+            envVar: string;
+        }, {
+            type: "token";
+            envVar: string;
+        }>]>>;
+        destination: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
+        description: z.ZodOptional<z.ZodString>;
+        tags: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    }, "strict", z.ZodTypeAny, {
+        name: string;
+        url: string;
+        includes?: (string | {
+            path: string;
+            state?: "draft" | "canon" | undefined;
+        })[] | undefined;
+        ref?: string | undefined;
+        auth?: {
+            type: "none";
+        } | {
+            type: "token";
+            envVar: string;
+        } | undefined;
+        destination?: string | undefined;
+        description?: string | undefined;
+        tags?: string[] | undefined;
+    }, {
+        name: string;
+        url: string;
+        includes?: (string | {
+            path: string;
+            state?: "draft" | "canon" | undefined;
+        })[] | undefined;
+        ref?: string | undefined;
+        auth?: {
+            type: "none";
+        } | {
+            type: "token";
+            envVar: string;
+        } | undefined;
+        destination?: string | undefined;
+        description?: string | undefined;
+        tags?: string[] | undefined;
+    }>, "many">>>;
+}, "strict", z.ZodTypeAny, {
+    sources: {
+        name: string;
+        url: string;
+        includes?: (string | {
+            path: string;
+            state?: "draft" | "canon" | undefined;
+        })[] | undefined;
+        ref?: string | undefined;
+        auth?: {
+            type: "none";
+        } | {
+            type: "token";
+            envVar: string;
+        } | undefined;
+        destination?: string | undefined;
+        description?: string | undefined;
+        tags?: string[] | undefined;
+    }[];
+    schemaVersion: 1;
+    baseDir?: string | undefined;
+}, {
+    schemaVersion: 1;
+    sources?: {
+        name: string;
+        url: string;
+        includes?: (string | {
+            path: string;
+            state?: "draft" | "canon" | undefined;
+        })[] | undefined;
+        ref?: string | undefined;
+        auth?: {
+            type: "none";
+        } | {
+            type: "token";
+            envVar: string;
+        } | undefined;
+        destination?: string | undefined;
+        description?: string | undefined;
+        tags?: string[] | undefined;
+    }[] | undefined;
+    baseDir?: string | undefined;
+}>, {
+    sources: {
+        name: string;
+        url: string;
+        includes?: (string | {
+            path: string;
+            state?: "draft" | "canon" | undefined;
+        })[] | undefined;
+        ref?: string | undefined;
+        auth?: {
+            type: "none";
+        } | {
+            type: "token";
+            envVar: string;
+        } | undefined;
+        destination?: string | undefined;
+        description?: string | undefined;
+        tags?: string[] | undefined;
+    }[];
+    schemaVersion: 1;
+    baseDir?: string | undefined;
+}, {
+    schemaVersion: 1;
+    sources?: {
+        name: string;
+        url: string;
+        includes?: (string | {
+            path: string;
+            state?: "draft" | "canon" | undefined;
+        })[] | undefined;
+        ref?: string | undefined;
+        auth?: {
+            type: "none";
+        } | {
+            type: "token";
+            envVar: string;
+        } | undefined;
+        destination?: string | undefined;
+        description?: string | undefined;
+        tags?: string[] | undefined;
+    }[] | undefined;
+    baseDir?: string | undefined;
+}>;
+type AuthRef = z.infer<typeof AuthRefSchema>;
+type Source = z.infer<typeof SourceSchema>;
+type CitadelConfig = z.infer<typeof CitadelConfigSchema>;
+
+declare const PublishedDocumentSchema: z.ZodObject<{
+    path: z.ZodEffects<z.ZodString, string, string>;
+    description: z.ZodOptional<z.ZodString>;
+    category: z.ZodOptional<z.ZodString>;
+    tags: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    state: z.ZodOptional<z.ZodEnum<["draft", "canon"]>>;
+}, "strict", z.ZodTypeAny, {
+    path: string;
+    state?: "draft" | "canon" | undefined;
+    description?: string | undefined;
+    tags?: string[] | undefined;
+    category?: string | undefined;
+}, {
+    path: string;
+    state?: "draft" | "canon" | undefined;
+    description?: string | undefined;
+    tags?: string[] | undefined;
+    category?: string | undefined;
+}>;
+declare const MaesterConfigSchema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<1>;
+    documents: z.ZodEffects<z.ZodArray<z.ZodObject<{
+        path: z.ZodEffects<z.ZodString, string, string>;
+        description: z.ZodOptional<z.ZodString>;
+        category: z.ZodOptional<z.ZodString>;
+        tags: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        state: z.ZodOptional<z.ZodEnum<["draft", "canon"]>>;
+    }, "strict", z.ZodTypeAny, {
+        path: string;
+        state?: "draft" | "canon" | undefined;
+        description?: string | undefined;
+        tags?: string[] | undefined;
+        category?: string | undefined;
+    }, {
+        path: string;
+        state?: "draft" | "canon" | undefined;
+        description?: string | undefined;
+        tags?: string[] | undefined;
+        category?: string | undefined;
+    }>, "many">, {
+        path: string;
+        state?: "draft" | "canon" | undefined;
+        description?: string | undefined;
+        tags?: string[] | undefined;
+        category?: string | undefined;
+    }[], {
+        path: string;
+        state?: "draft" | "canon" | undefined;
+        description?: string | undefined;
+        tags?: string[] | undefined;
+        category?: string | undefined;
+    }[]>;
+}, "strict", z.ZodTypeAny, {
+    schemaVersion: 1;
+    documents: {
+        path: string;
+        state?: "draft" | "canon" | undefined;
+        description?: string | undefined;
+        tags?: string[] | undefined;
+        category?: string | undefined;
+    }[];
+}, {
+    schemaVersion: 1;
+    documents: {
+        path: string;
+        state?: "draft" | "canon" | undefined;
+        description?: string | undefined;
+        tags?: string[] | undefined;
+        category?: string | undefined;
+    }[];
+}>;
+type PublishedDocument = z.infer<typeof PublishedDocumentSchema>;
+type MaesterConfig = z.infer<typeof MaesterConfigSchema>;
+
+declare function loadCitadelConfig(repoRoot: string): Promise<CitadelConfig>;
+declare function loadMaesterConfig(repoRoot: string): Promise<MaesterConfig>;
+
+type FetchWarning = {
+    type: "no-matches";
+    name: string;
+    includes: readonly string[];
+};
+
+type SourceOfTruth = "inline" | "rule" | "default";
+type StateBreakdown = {
+    canon: number;
+    draft: number;
+    untagged: number;
+};
+type BadInlineStateWarning = {
+    type: "bad-inline-state";
+    file: string;
+    raw: string;
+};
+type DisagreementWarning = {
+    type: "disagreement";
+    file: string;
+    inline: State;
+    rule: State;
+};
+type StateWarning = BadInlineStateWarning | DisagreementWarning;
+type StateApplyDetail = {
+    file: string;
+    state: State | "untagged";
+    sourceOfTruth: SourceOfTruth | "untagged";
+};
+
+type SyncStatus = "added" | "updated" | "unchanged" | "failed";
+type SyncOutcome = {
+    name: string;
+    status: SyncStatus;
+    destination: string;
+    ref: string | undefined;
+    commitSha?: string;
+    warnings: FetchWarning[];
+    stateBreakdown?: StateBreakdown;
+    stateWarnings?: StateWarning[];
+    stateDetails?: StateApplyDetail[];
+    error?: string;
+};
+type SyncResult = {
+    outcomes: SyncOutcome[];
+    failed: number;
+};
+type SyncOptions = {
+    repoRoot: string;
+    scope?: readonly string[];
+    concurrency?: number;
+    env?: NodeJS.ProcessEnv;
+    baseDir?: string;
+    onProgress?: (event: ProgressEvent) => void;
+};
+type ProgressEvent = {
+    type: "start";
+    name: string;
+} | {
+    type: "fetched";
+    name: string;
+    commitSha: string;
+} | {
+    type: "staged";
+    name: string;
+    status: SyncStatus;
+} | {
+    type: "warning";
+    name: string;
+    warning: FetchWarning;
+} | {
+    type: "failed";
+    name: string;
+    error: string;
+};
+declare function runSync(config: CitadelConfig, options: SyncOptions): Promise<SyncResult>;
+
+type StatusVerdict = "up-to-date" | "behind" | "failed";
+type BehindReason = "never-synced" | "remote-ref-advanced" | "manifest-changed";
+type StatusOutcome = {
+    name: string;
+    verdict: "up-to-date";
+    commitSha: string;
+} | {
+    name: string;
+    verdict: "behind";
+    reasons: readonly BehindReason[];
+    commitSha?: string;
+    resolvedSha?: string;
+} | {
+    name: string;
+    verdict: "failed";
+    error: string;
+};
+type StatusCounts = {
+    upToDate: number;
+    behind: number;
+    failed: number;
+};
+type StatusResult = {
+    outcomes: StatusOutcome[];
+    counts: StatusCounts;
+};
+type StatusOptions = {
+    repoRoot: string;
+    scope?: readonly string[];
+    concurrency?: number;
+    env?: NodeJS.ProcessEnv;
+    baseDir?: string;
+};
+declare function runStatus(config: CitadelConfig, options: StatusOptions): Promise<StatusResult>;
+
+type SkillTargetId = "claude-code" | "codex" | "cursor" | "agents-md";
+type SkillAction = "installed" | "upgraded" | "unchanged" | "failed";
+type SkillInstallOutcome = {
+    id: SkillTargetId;
+    label: string;
+    artifactPaths: readonly string[];
+    action: SkillAction;
+    installedVersion?: string;
+    error?: string;
+};
+type SkillInstallResult = {
+    outcomes: SkillInstallOutcome[];
+    counts: {
+        installed: number;
+        upgraded: number;
+        unchanged: number;
+        failed: number;
+    };
+};
+type SkillStatusOutcomeState = "up-to-date" | "outdated" | "not-installed";
+type SkillStatusOutcome = {
+    id: SkillTargetId;
+    label: string;
+    artifactPaths: readonly string[];
+    state: SkillStatusOutcomeState;
+    installedVersion?: string;
+    currentVersion: string;
+};
+type SkillStatusResult = {
+    outcomes: SkillStatusOutcome[];
+    counts: {
+        upToDate: number;
+        outdated: number;
+        notInstalled: number;
+    };
+};
+type SkillWriteInput = {
+    repoRoot: string;
+    skillVersion: string;
+    citadelBaseDir: string;
+};
+type SkillWriteOutcome = {
+    action: SkillAction;
+    installedVersion?: string;
+    error?: string;
+};
+type SkillTarget = {
+    readonly id: SkillTargetId;
+    readonly label: string;
+    /** Repo-relative paths this target writes. */
+    readonly artifactPaths: readonly string[];
+    /** Writers backing different ids may share an implementation (codex + agents-md). */
+    readonly writerKey: string;
+    write(input: SkillWriteInput): Promise<SkillWriteOutcome>;
+    /** Read the installed version marker from disk, if any. */
+    readInstalledVersion(repoRoot: string): Promise<string | undefined>;
+};
+
+declare function listSkillTargets(): readonly SkillTarget[];
+
+type RunSkillInstallOpts = {
+    targets: readonly SkillTargetId[];
+    mode: "install" | "add-target";
+    citadelBaseDir: string;
+};
+declare function runSkillInstall(repoRoot: string, opts: RunSkillInstallOpts): Promise<SkillInstallResult>;
+type RunSkillUpgradeOpts = {
+    check?: boolean;
+    citadelBaseDir: string;
+};
+declare function runSkillUpgrade(repoRoot: string, opts: RunSkillUpgradeOpts): Promise<SkillInstallResult>;
+declare function runSkillStatus(repoRoot: string): Promise<SkillStatusResult>;
+
+declare const SKILL_VERSION: string;
+
+declare class MaesterError extends Error {
+    readonly code: string;
+    readonly cause?: unknown;
+    constructor(code: string, message: string, options?: {
+        cause?: unknown;
+    });
+}
+declare class ConfigError extends MaesterError {
+    readonly filePath: string | undefined;
+    readonly line?: number;
+    readonly column?: number;
+    constructor(message: string, detail?: {
+        filePath?: string;
+        line?: number;
+        column?: number;
+        cause?: unknown;
+    });
+}
+declare class AuthError extends MaesterError {
+    readonly envVar: string;
+    constructor(envVar: string, message?: string);
+}
+declare class RefNotFoundError extends MaesterError {
+    readonly ref: string;
+    readonly url: string;
+    constructor(ref: string, url: string, cause?: unknown);
+}
+declare class DestinationBlockedError extends MaesterError {
+    readonly destination: string;
+    constructor(destination: string, message: string);
+}
+
+export { AuthError, type AuthRef, type BehindReason, type CitadelConfig, ConfigError, DestinationBlockedError, type MaesterConfig, MaesterError, type ProgressEvent, type PublishedDocument, RefNotFoundError, SKILL_VERSION, type SkillAction, type SkillInstallOutcome, type SkillInstallResult, type SkillStatusOutcome, type SkillStatusResult, type SkillTarget, type SkillTargetId, type Source, type StatusCounts, type StatusOptions, type StatusOutcome, type StatusResult, type StatusVerdict, type SyncOptions, type SyncOutcome, type SyncResult, type SyncStatus, listSkillTargets, loadCitadelConfig, loadMaesterConfig, runSkillInstall, runSkillStatus, runSkillUpgrade, runStatus, runSync };