zernie__vigiles/api-surface/vigiles-spec.api.md

API Report File for "vigiles-spec"

Do not edit this file. It is a report generated by API Extractor.

// @public @deprecated (undocumented)
export const agent: typeof agentSpec & {
    result: typeof result;
    delegate: typeof delegate;
    railway: typeof railway;
    needs: typeof experimental_needs;
    pipeStep: typeof experimental_pipeStep;
    start: typeof experimental_start;
    andThen: typeof experimental_andThen;
    pipe: typeof experimental_pipe;
};

// @public
export interface AgentSpec {
    readonly body?: string | InstructionFragment[];
    readonly color?: string;
    readonly description: string;
    readonly disallowedTools?: readonly string[];
    readonly model?: string;
    readonly name: string;
    readonly output?: OutputContract;
    readonly purity?: AuthoredPurity;
    readonly rules?: Record<string, Rule>;
    readonly sections?: Record<string, string | InstructionFragment[]>;
    // (undocumented)
    readonly _specType: "agent";
    readonly tools?: readonly string[];
}

// @public
export type AgentSpecInput<P extends AuthoredPurity | undefined, V extends ToolVocabulary, Ok extends Shape = Shape, Err extends Shape = Shape> = Omit<AgentSpec, "_specType" | "tools" | "purity" | "output"> & {
    readonly purity?: P;
    readonly tools?: readonly AllowedAt<P, V>[];
    readonly output?: OutputContract<Ok, Err>;
};

// @public
export type AllowedAt<P extends AuthoredPurity | undefined, V extends ToolVocabulary> = P extends "pure" ? V["readOnly"] : P extends "bounded" ? V["bounded"] : string;

// @public
export type AuthoredPurity = "pure" | "bounded" | "dangerously-unrestricted";

// @public
export const BUILTIN_LINTERS: readonly ["eslint", "stylelint", "ruff", "clippy", "pylint", "rubocop", "detekt", "ktlint", "checkstyle", "golangci-lint", "cedar"];

// @public (undocumented)
export type BuiltinLinter = (typeof BUILTIN_LINTERS)[number];

// @public @deprecated (undocumented)
export const claude: typeof instructionFile;

// @public (undocumented)
export interface ClaudeSpec {
    readonly commands?: Record<string, string>;
    readonly keyFiles?: Record<string, string>;
    readonly maxSectionLines?: number;
    readonly maxTokens?: number;
    readonly rules: Record<string, Rule>;
    readonly sections?: Record<string, string | InstructionFragment[]>;
    // (undocumented)
    readonly _specType: "claude";
    readonly target?: InstructionTarget | InstructionTarget[];
}

// @public
export function cmd(command: NoInfer<StrictCmd>): CmdRef;

// @public
export interface CmdRef {
    // (undocumented)
    readonly command: VerifiedCmd;
    // (undocumented)
    readonly _ref: "cmd";
}

// @public (undocumented)
export function defineConfig(config: VigilesV2Config): VigilesV2Config;

// @public
export function dir(path: string): DirRef;

// @public
export interface DirRef {
    // (undocumented)
    readonly path: VerifiedDir;
    // (undocumented)
    readonly _ref: "dir";
}

// @internal
export interface EffectRegion {
    // (undocumented)
    readonly body: InstructionFragment[];
    // (undocumented)
    readonly _ref: "effect";
}

// @public
export function enforce(ref: NoInfer<StrictLinterRule> | VigilesRef, why: string, options?: {
    verify?: boolean;
}): EnforceRule;

// @public
export type EnforcementRef = LinterRule | VigilesRef;

// @public
export interface EnforceRule {
    // (undocumented)
    readonly _kind: "enforce";
    // (undocumented)
    readonly linterRule: LinterRule | VigilesRef;
    readonly verify: boolean;
    // (undocumented)
    readonly why: string;
}

// @public
export const experimental_agent: typeof agentSpec & {
    result: typeof result;
    delegate: typeof delegate;
    railway: typeof railway;
    needs: typeof experimental_needs;
    pipeStep: typeof experimental_pipeStep;
    start: typeof experimental_start;
    andThen: typeof experimental_andThen;
    pipe: typeof experimental_pipe;
};

// @public
export function experimental_effect(strings: TemplateStringsArray, ...values: InstructionFragment[]): EffectRegion;

// @public (undocumented)
export const experimental_skill: typeof skillSpec & {
    input: typeof input;
    step: typeof step;
};

// @public
export function file(path: NoInfer<StrictFile>): FileRef;

// @public
export interface FileRef {
    // (undocumented)
    readonly path: VerifiedPath;
    // (undocumented)
    readonly _ref: "file";
}

// @public
export type Gate = CmdRef | FileRef | RoleGate;

// @public
export function glob(pattern: string): GlobRef;

// @public
export interface GlobRef {
    // (undocumented)
    readonly pattern: VerifiedGlob;
    // (undocumented)
    readonly _ref: "glob";
}

// @public
export function guard(options: {
    watch: string | readonly string[];
    run: string;
}, description: string): GuardRule;

// @public
export interface GuardRule {
    // (undocumented)
    readonly description: string;
    // (undocumented)
    readonly _kind: "guard";
    // (undocumented)
    readonly run: string;
    // (undocumented)
    readonly watch: string | readonly string[];
}

// @public
export function guidance(text: string): GuidanceRule;

// @public
export interface GuidanceRule {
    // (undocumented)
    readonly _kind: "guidance";
    // (undocumented)
    readonly text: string;
}

// @internal
export type Handoff<Producer extends Shape, Consumer extends Shape> = Supplies<Producer, Consumer> extends true ? true : {
    readonly __handoff_error: Supplies<Producer, Consumer>;
};

// @public
export function instructionFile(spec: ClaudeSpecInput): ClaudeSpec;

// @public (undocumented)
export type InstructionFragment = string | Ref | EffectRegion;

// @public @deprecated (undocumented)
export const instructions: typeof prose;

// @public
export type InstructionTarget = "CLAUDE.md" | "AGENTS.md" | (string & {});

// @internal
export type KnownAgentName<Target extends string, Names extends string, From extends string = string> = [Target] extends [Names] ? true : {
    readonly __dangling_delegate: Target;
    readonly from: From;
};

// @public
export interface KnownLinterRules {
}

// @public
export interface KnownNpmScripts {
}

// @public
export interface KnownProjectFiles {
}

// @public
export type LinterMode = boolean | "catalog-only";

// @public
export type LinterRule = `${BuiltinLinter}/${string}` | ScopedPlugin;

// @public
export type LintersVerified<T extends ClaudeSpec | SkillSpec = ClaudeSpec> = T & {
    readonly [__stage]: "linters-verified";
};

// @internal
export type NeedsContract<N extends Shape> = N;

// @public
export type OkOf<T> = T extends TypedOutcome<infer Ok, Shape> ? Ok : Shape;

// @public
export interface OpenToolVocabulary extends ToolVocabulary {
    // (undocumented)
    readonly bounded: string;
    // (undocumented)
    readonly readOnly: string;
}

// @public
export interface OutputContract<Ok extends Shape = Shape, Err extends Shape = Shape> {
    // (undocumented)
    readonly err: Err;
    // (undocumented)
    readonly ok: Ok;
    // (undocumented)
    readonly _ref: "output";
}

// @public
export type OutputFieldType = "string" | "number" | "boolean" | "string[]" | readonly [string, ...string[]];

// @public
export type OutputPath<Spec extends `${string}.md.spec.ts`> = Spec extends `${infer Base}.spec.ts` ? Base : never;

// @internal
export interface Pipeline<Ok extends Shape, Err extends Shape> {
    readonly agents: readonly string[];
    readonly err: Err;
    readonly ok: Ok;
    readonly railway: Railway;
    // (undocumented)
    readonly _specType: "pipeline";
}

// @internal
export interface PipeStep<Needs extends Shape, Ok extends Shape, Err extends Shape> {
    // (undocumented)
    readonly agent: TypedAgentSpec<Ok, Err>;
    // (undocumented)
    readonly needs: Needs;
    // (undocumented)
    readonly _step: "typed-delegate";
}

// @public
export function project(role: ProjectRole): RoleGate;

// @public
export type ProjectRole = "test" | "build" | "lint";

// @public
export function prose(strings: TemplateStringsArray, ...values: InstructionFragment[]): InstructionFragment[];

// @public
export interface Railway {
    // (undocumented)
    readonly name: string;
    readonly onError?: RailwayStep;
    readonly recover?: {
        readonly step: RailwayStep;
        readonly max: number;
    };
    // (undocumented)
    readonly _specType: "railway";
    // (undocumented)
    readonly steps: readonly RailwayStep[];
}

// @public
export interface RailwayStep {
    readonly agent: string;
    readonly needs?: Shape;
    // (undocumented)
    readonly _step: "delegate";
    readonly task?: string;
}

// @public
export type RawSpec<T extends ClaudeSpec | SkillSpec = ClaudeSpec> = T & {
    readonly [__stage]: "raw";
};

// @public
export type ReadyToEmit<T extends ClaudeSpec | SkillSpec = ClaudeSpec> = T & {
    readonly [__stage]: "ready";
};

// @public (undocumented)
export type Ref = FileRef | CmdRef | SkillRef | SymbolRef | DirRef | GlobRef;

// @public
export function ref(path: string): SkillRef;

// @public
export type RefsValidated<T extends ClaudeSpec | SkillSpec = ClaudeSpec> = T & {
    readonly [__stage]: "refs-validated";
};

// @public
export interface RoleGate {
    // (undocumented)
    readonly _ref: "role";
    // (undocumented)
    readonly role: ProjectRole;
}

// @public (undocumented)
export type Rule = EnforceRule | GuidanceRule | GuardRule;

// @public
export type Shape = Readonly<Record<string, OutputFieldType>>;

// @public
export interface SkillInput {
    readonly hint: string;
    readonly name: string;
    readonly required?: boolean;
}

// @public
export interface SkillRef {
    // (undocumented)
    readonly path: VerifiedRef;
    // (undocumented)
    readonly _ref: "skill";
}

// @public (undocumented)
export interface SkillSpec {
    readonly argumentHint?: string;
    readonly body?: string | InstructionFragment[];
    readonly context?: "fork";
    readonly description: string;
    readonly disableModelInvocation?: boolean;
    readonly disallowedTools?: readonly string[];
    readonly inputs?: readonly SkillInput[];
    readonly maxInlineCodeLines?: number;
    readonly name: string;
    readonly output?: OutputContract;
    readonly postcondition?: Gate;
    readonly purity?: AuthoredPurity;
    // @deprecated (undocumented)
    readonly result?: Gate;
    // (undocumented)
    readonly _specType: "skill";
    readonly steps?: readonly SkillStep[];
    readonly tools?: readonly string[];
}

// @public
export type SkillSpecInput<P extends AuthoredPurity | undefined, V extends ToolVocabulary> = Omit<SkillSpec, "_specType" | "tools" | "purity"> & {
    readonly purity?: P;
    readonly tools?: readonly AllowedAt<P, V>[];
};

// @public
export interface SkillStep {
    readonly do: string | InstructionFragment[];
    readonly gate?: Gate;
    readonly retry?: number;
}

// @public
export type SpecPath<Output extends `${string}.md`> = `${Output}.spec.ts`;

// @public (undocumented)
export type StrictCmd = [keyof KnownNpmScripts] extends [never] ? string : `npm run ${KnownNpmScripts[keyof KnownNpmScripts] & string}` | `npm ${KnownNpmScripts[keyof KnownNpmScripts] & string}` | (string & {});

// @public
export type StrictFile = [keyof KnownProjectFiles] extends [never] ? string : KnownProjectFiles[keyof KnownProjectFiles] & string;

// @public
export type StrictLinterRule = [keyof KnownLinterRules] extends [never] ? LinterRule : {
    [K in keyof KnownLinterRules]: `${K & string}/${KnownLinterRules[K] & string}`;
}[keyof KnownLinterRules];

// @internal
export type Supplies<Producer extends Shape, Consumer extends Shape> = {
    [K in keyof Consumer]: K extends keyof Producer ? Producer[K] extends Consumer[K] ? true : {
        readonly __mismatch: K;
        readonly expected: Consumer[K];
        readonly got: Producer[K];
    } : {
        readonly __missing: K;
        readonly required: Consumer[K];
    };
}[keyof Consumer];

// @public
export function symbol(file: NoInfer<StrictFile>, name: string): SymbolRef;

// @public
export interface SymbolRef {
    // (undocumented)
    readonly file: VerifiedPath;
    // (undocumented)
    readonly _ref: "symbol";
    // (undocumented)
    readonly symbol: string;
}

// @public
export interface ToolVocabulary {
    readonly bounded: string;
    readonly readOnly: string;
}

// @public
export type TypedAgentSpec<Ok extends Shape, Err extends Shape> = AgentSpec & TypedOutcome<Ok, Err>;

// @public
export interface TypedOutcome<Ok extends Shape, Err extends Shape> {
    // (undocumented)
    readonly [__outcome]: {
        readonly ok: Ok;
        readonly err: Err;
    };
}

// @public (undocumented)
export type VerifiedCmd = string & {
    readonly [__brand]: "VerifiedCmd";
};

// @public (undocumented)
export type VerifiedDir = string & {
    readonly [__brand]: "VerifiedDir";
};

// @public (undocumented)
export type VerifiedGlob = string & {
    readonly [__brand]: "VerifiedGlob";
};

// @public (undocumented)
export type VerifiedPath = string & {
    readonly [__brand]: "VerifiedPath";
};

// @public (undocumented)
export type VerifiedRef = string & {
    readonly [__brand]: "VerifiedRef";
};

// @public
export type VigilesRef = `vigiles/${string}`;

// @public (undocumented)
export interface VigilesV2Config {
    readonly discover?: boolean;
    readonly linters?: Record<string, LinterMode>;
    readonly maxRules?: number;
    readonly maxSectionLines?: number;
    readonly maxTokens?: number;
    readonly specs?: string;
    readonly verifyLinters?: boolean;
}

// (No @packageDocumentation comment for this package)