ai-dot 0.1.0-alpha.1

package/dist/index.d.ts

@@ -0,0 +1,476 @@
+/**
+ * A specialized AI assistant with isolated context, custom instructions,
+ * and optional tool/model restrictions.
+ *
+ * Claude Code: .claude/agents/*.md
+ * Cursor:      .cursor/agents/*.md
+ * Codex:       [agents.<name>] config sections
+ */
+interface Agent {
+    /** Identifier used for delegation. */
+    name: string;
+    /** When/why the primary agent should delegate to this subagent. */
+    description: string;
+    /** Model override (e.g. "claude-sonnet-4-6"). */
+    model?: string;
+    /** When true, restrict to read-only file access. */
+    readonly?: boolean;
+    /** System prompt / behavioral guidance (markdown). */
+    instructions: string;
+    /** Allowed tool names. Undefined means all tools allowed. */
+    tools?: string[];
+    /** Agent mode (OpenCode). */
+    mode?: "primary" | "subagent" | "all";
+    /** Sampling temperature (OpenCode). */
+    temperature?: number;
+    /** Top-p sampling (OpenCode). */
+    topP?: number;
+    /** Max steps per invocation (OpenCode). */
+    steps?: number;
+    /** Display color in TUI (OpenCode). */
+    color?: string;
+    /** Hidden from agent picker (OpenCode). */
+    hidden?: boolean;
+    /** Disabled agent (OpenCode). */
+    disabled?: boolean;
+}
+
+/**
+ * The 4-tier scope hierarchy shared by Claude Code, Cursor, and Codex.
+ * Precedence: enterprise > project > user > local (highest to lowest).
+ */
+declare const Scope: {
+    readonly Enterprise: "enterprise";
+    readonly Project: "project";
+    readonly User: "user";
+    readonly Local: "local";
+};
+type Scope = (typeof Scope)[keyof typeof Scope];
+/** All scopes ordered from highest to lowest precedence. */
+declare const SCOPE_PRECEDENCE: readonly Scope[];
+/** Returns true if `a` has higher precedence (lower index) than `b`. */
+declare function scopeOutranks(a: Scope, b: Scope): boolean;
+
+/**
+ * A persistent, text-based instruction that shapes agent behavior.
+ *
+ * Abstracts what Claude Code calls "CLAUDE.md / rules",
+ * Cursor calls "rules", and Codex calls "AGENTS.md / instructions".
+ */
+interface Directive {
+    /** Markdown content of the directive. */
+    content: string;
+    /** Scope at which this directive is defined. */
+    scope: Scope;
+    /** Optional glob patterns — activates only for matching file paths. */
+    appliesTo?: string[];
+    /** When true, always include in context (vs. intelligent selection). */
+    alwaysApply: boolean;
+    /** Optional human-readable description (used for intelligent selection). */
+    description?: string;
+}
+
+/** Lifecycle events that can trigger a hook. */
+declare const HookEvent: {
+    readonly PreToolUse: "preToolUse";
+    readonly PostToolUse: "postToolUse";
+    readonly PreFileEdit: "preFileEdit";
+    readonly PostFileEdit: "postFileEdit";
+    readonly SessionStart: "sessionStart";
+    readonly SessionEnd: "sessionEnd";
+    readonly UserPromptSubmitted: "userPromptSubmitted";
+    readonly AgentStop: "agentStop";
+    readonly SubagentStop: "subagentStop";
+    readonly ErrorOccurred: "errorOccurred";
+};
+type HookEvent = (typeof HookEvent)[keyof typeof HookEvent];
+/**
+ * An event handler that fires at specific points in the agent lifecycle.
+ * Supported by Claude Code and Cursor; not supported by Codex.
+ */
+interface Hook {
+    /** Lifecycle event this hook responds to. */
+    event: HookEvent;
+    /** Filter condition (glob pattern or tool name) for when this hook fires. */
+    matcher?: string;
+    /** Shell command or prompt to execute. */
+    handler: string;
+    /** Scope at which this hook is defined. */
+    scope: Scope;
+}
+
+/**
+ * A file/directory exclusion rule — the agent should not access or index matching paths.
+ *
+ * Claude Code: Deny rules on Read()/Edit()
+ * Cursor:      .cursorignore, .cursorindexingignore
+ * Codex:       Protected paths + shell_environment_policy
+ */
+interface IgnorePattern {
+    /** Gitignore-style glob pattern. */
+    pattern: string;
+    /** Scope at which this ignore rule is defined. */
+    scope: Exclude<Scope, "enterprise" | "local">;
+}
+
+/** The three possible access control decisions. */
+declare const Decision: {
+    readonly Allow: "allow";
+    readonly Deny: "deny";
+    readonly Ask: "ask";
+};
+type Decision = (typeof Decision)[keyof typeof Decision];
+/**
+ * An access control rule governing what tools and actions the agent can take.
+ *
+ * Claude Code: allow/deny/ask rules per tool (Bash(pattern), Read(pattern), etc.)
+ * Cursor:      allow/deny per tool type (Shell(cmd), Read(glob), Write(glob))
+ * Codex:       approval_policy + sandbox_mode + command rules
+ */
+interface Permission {
+    /** Which tool this applies to (e.g. "Bash", "Read", "Write"). */
+    tool: string;
+    /** Glob/prefix pattern for matching arguments. */
+    pattern?: string;
+    /** Access control decision. */
+    decision: Decision;
+    /** Scope at which this permission is defined. */
+    scope: Scope;
+}
+
+/**
+ * A key-value configuration entry for tool behavior, model selection, and feature flags.
+ *
+ * Claude Code: .claude/settings.json
+ * Cursor:      .cursor/cli.json
+ * Codex:       .codex/config.toml
+ */
+interface Setting {
+    /** Setting name. */
+    key: string;
+    /** Setting value (type varies by key). */
+    value: unknown;
+    /** Scope at which this setting is defined. */
+    scope: Scope;
+}
+
+/**
+ * A portable, reusable package of domain-specific knowledge and optional scripts.
+ *
+ * Structure: SKILL.md + optional scripts/, references/, assets/.
+ * Invocation: explicit (/skill-name) or automatic (agent decides).
+ * All three tools (Claude Code, Cursor, Codex) converge on this format.
+ */
+interface Skill {
+    /** Identifier used for explicit invocation (e.g. /skill-name). */
+    name: string;
+    /** What this skill does and when to use it. */
+    description: string;
+    /** The SKILL.md body (markdown). */
+    content: string;
+    /** When true, only allow explicit /skill-name invocation. */
+    disableAutoInvocation: boolean;
+}
+
+/** MCP transport type. */
+declare const Transport: {
+    readonly Stdio: "stdio";
+    readonly Http: "http";
+    readonly Sse: "sse";
+};
+type Transport = (typeof Transport)[keyof typeof Transport];
+/**
+ * An external tool/data provider connected via Model Context Protocol (MCP).
+ * Universal across Claude Code, Cursor, and Codex.
+ */
+interface ToolServer {
+    /** Identifier. */
+    name: string;
+    /** Connection type. */
+    transport: Transport;
+    /** Shell command (stdio) or endpoint URL (http/sse). */
+    command?: string;
+    url?: string;
+    /** Command arguments (stdio transport). */
+    args?: string[];
+    /** Environment variables passed to the server. */
+    env?: Record<string, string>;
+    /** If set, only these tools are exposed from the server. */
+    enabledTools?: string[];
+    /** If set, these tools are hidden from the server. */
+    disabledTools?: string[];
+    /** Scope at which this server is configured. */
+    scope: Scope;
+}
+
+/** Aggregated project configuration loaded from `.ai/`. */
+interface ProjectConfig {
+    directives: Directive[];
+    skills: Skill[];
+    agents: Agent[];
+    toolServers: ToolServer[];
+    hooks: Hook[];
+    permissions: Permission[];
+    settings: Setting[];
+    ignorePatterns: IgnorePattern[];
+}
+/** A validation error with location context. */
+interface ConfigError {
+    file: string;
+    line?: number;
+    message: string;
+}
+/** Result of config validation. */
+interface ValidationResult {
+    valid: boolean;
+    errors: ConfigError[];
+}
+/** The scope at which config was loaded. */
+type ConfigScope = "user" | "project";
+/** Create an empty ProjectConfig. */
+declare function emptyConfig(): ProjectConfig;
+/**
+ * Merge two configs: base (user) + override (project).
+ * Project-level entities are appended after user-level ones.
+ * For settings with the same key, project overrides user.
+ */
+declare function mergeConfigs(base: ProjectConfig, override: ProjectConfig): ProjectConfig;
+/** Validate a ProjectConfig and return errors. */
+declare function validateConfig(config: ProjectConfig): ValidationResult;
+
+/** Validate config and warn about unsupported features per target. */
+declare function runCheck(projectDir: string, scope?: ConfigScope): Promise<void>;
+
+/** Source tool that originally created a config file. */
+type SourceTool = "claude" | "cursor" | "codex" | "opencode";
+/** Kind of config entity the file maps to. */
+type DetectedKind = "directives" | "mcp" | "permissions" | "hooks" | "settings" | "agents" | "skills" | "ignore";
+/** A detected raw config file in the project. */
+interface DetectedFile {
+    path: string;
+    relativePath: string;
+    source: SourceTool;
+    kind: DetectedKind;
+    label: string;
+}
+/** Scan a project directory for existing raw config files from AI tools. */
+declare function scanForConfigs(projectDir: string): Promise<DetectedFile[]>;
+
+/** Options for the import command. */
+interface ImportCommandOptions {
+    source?: SourceTool;
+}
+/** Import existing AI tool configs into .ai/ format. */
+declare function runImportCommand(projectDir: string, options?: ImportCommandOptions): Promise<void>;
+
+/** Target AI tool for config generation. */
+declare const TargetTool: {
+    readonly Claude: "claude";
+    readonly Cursor: "cursor";
+    readonly Codex: "codex";
+    readonly OpenCode: "opencode";
+    readonly Copilot: "copilot";
+    readonly Antigravity: "antigravity";
+};
+type TargetTool = (typeof TargetTool)[keyof typeof TargetTool];
+/** All supported target tools. */
+declare const ALL_TARGETS: readonly TargetTool[];
+/** A file written by an emitter. */
+interface EmittedFile {
+    /** Relative path from the project root. */
+    path: string;
+    /** File content. */
+    content: string;
+}
+/** Result of an emit operation. */
+interface EmitResult {
+    /** Files that were written (or would be written in dry-run). */
+    files: EmittedFile[];
+    /** Warnings about lossy mappings or unsupported features. */
+    warnings: string[];
+}
+/** Interface that all emitters implement. */
+interface Emitter {
+    /** Emit config files for a specific target tool. */
+    emit(config: ProjectConfig, target: TargetTool): EmitResult;
+}
+
+/** Available template names. */
+type TemplateName = "blank" | "minimal" | "web" | "python" | "monorepo";
+/** Template metadata for display. */
+interface TemplateInfo {
+    name: TemplateName;
+    label: string;
+    description: string;
+    factory: () => ProjectConfig;
+}
+/** All available templates. */
+declare const TEMPLATES: readonly TemplateInfo[];
+/** Get a template by name. Throws if not found. */
+declare function getTemplate(name: TemplateName): ProjectConfig;
+/** All valid template names. */
+declare const TEMPLATE_NAMES: readonly TemplateName[];
+
+/** Options for the init command. */
+interface InitOptions {
+    template?: TemplateName;
+    targets?: TargetTool[];
+    skipImport?: boolean;
+    autoSync?: boolean;
+}
+/** Scaffold a new `.ai/` directory with guided setup or flags. */
+declare function runInit(projectDir: string, options?: InitOptions): Promise<void>;
+
+/** Show the status of generated files vs what's on disk. */
+declare function runStatus(projectDir: string): Promise<void>;
+
+interface SyncOptions {
+    targets: TargetTool[];
+    dryRun: boolean;
+    scope: ConfigScope;
+    force: boolean;
+    yes?: boolean;
+}
+/** Load config, run emitters, write files. */
+declare function runSync(projectDir: string, options: SyncOptions): Promise<void>;
+
+/** Result of loading a project config from `.ai/`. */
+interface LoadResult {
+    config: ProjectConfig;
+    errors: ConfigError[];
+}
+/** Load a full ProjectConfig from an `.ai/` directory. */
+declare function loadProjectConfig(aiDir: string, scope?: ConfigScope): Promise<LoadResult>;
+/**
+ * Load merged config: user-level ~/.ai/ as base, project .ai/ overrides.
+ * Returns the combined config with correct scopes on each entity.
+ */
+declare function loadMergedConfig(projectDir: string): Promise<LoadResult>;
+
+/** Parsed result of a markdown file with YAML frontmatter. */
+interface ParsedMarkdown {
+    /** Frontmatter key-value pairs. */
+    frontmatter: Record<string, unknown>;
+    /** Markdown body after frontmatter. */
+    body: string;
+}
+/**
+ * Parse a markdown string with optional YAML frontmatter.
+ *
+ * Frontmatter is delimited by `---` at the start of the file.
+ * Uses a simple parser to avoid pulling in a full YAML library for frontmatter
+ * (the main config.yaml uses the `yaml` package).
+ */
+declare function parseMarkdownWithFrontmatter(raw: string): ParsedMarkdown;
+/** Load and parse a markdown file with frontmatter from disk. */
+declare function loadMarkdownFile(filePath: string): Promise<ParsedMarkdown>;
+
+/**
+ * Scan `.ai/skills/` for skill directories.
+ * Each skill is a directory containing a SKILL.md file.
+ */
+declare function loadSkills(skillsDir: string): Promise<Skill[]>;
+
+/** Create a Directive with sensible defaults. */
+declare function createDirective(overrides: Partial<Directive> & Pick<Directive, "content" | "scope">): Directive;
+/** Create a Skill with sensible defaults. */
+declare function createSkill(overrides: Partial<Skill> & Pick<Skill, "name" | "content">): Skill;
+/** Create an Agent with sensible defaults. */
+declare function createAgent(overrides: Partial<Agent> & Pick<Agent, "name" | "instructions">): Agent;
+/** Create a ToolServer with sensible defaults. */
+declare function createToolServer(overrides: Partial<ToolServer> & Pick<ToolServer, "name" | "transport" | "scope">): ToolServer;
+/** Create a Hook with sensible defaults. */
+declare function createHook(overrides: Partial<Hook> & Pick<Hook, "event" | "handler" | "scope">): Hook;
+/** Create a Permission with sensible defaults. */
+declare function createPermission(overrides: Partial<Permission> & Pick<Permission, "tool" | "decision" | "scope">): Permission;
+/** Create a Setting. */
+declare function createSetting(overrides: Partial<Setting> & Pick<Setting, "key" | "value" | "scope">): Setting;
+/** Create an IgnorePattern. */
+declare function createIgnorePattern(overrides: Partial<IgnorePattern> & Pick<IgnorePattern, "pattern" | "scope">): IgnorePattern;
+
+declare function isDirective(v: unknown): v is Directive;
+declare function isSkill(v: unknown): v is Skill;
+declare function isAgent(v: unknown): v is Agent;
+declare function isToolServer(v: unknown): v is ToolServer;
+declare function isHook(v: unknown): v is Hook;
+declare function isPermission(v: unknown): v is Permission;
+declare function isSetting(v: unknown): v is Setting;
+declare function isIgnorePattern(v: unknown): v is IgnorePattern;
+
+/** Emits agent definition files. */
+declare const agentsEmitter: Emitter;
+
+/** Emits directive files — biggest format divergence across tools. */
+declare const directivesEmitter: Emitter;
+
+/** Emits hooks and ignore pattern configuration files. */
+declare const hooksEmitter: Emitter;
+
+/** Emits MCP server configuration files. */
+declare const mcpEmitter: Emitter;
+
+/** Emits permissions and settings configuration files. */
+declare const permissionsEmitter: Emitter;
+
+/** Emits skill files for all target tools. Near-identical format across all 3. */
+declare const skillsEmitter: Emitter;
+
+/** Parse Claude Code config files into a partial ProjectConfig. */
+declare function parseClaude(projectDir: string, files: DetectedFile[]): Promise<Partial<ProjectConfig>>;
+
+/** Parse Codex config files into a partial ProjectConfig. */
+declare function parseCodex(_projectDir: string, files: DetectedFile[]): Promise<Partial<ProjectConfig>>;
+
+/** Parse Cursor config files into a partial ProjectConfig. */
+declare function parseCursor(_projectDir: string, files: DetectedFile[]): Promise<Partial<ProjectConfig>>;
+
+/** Parse OpenCode config files into a partial ProjectConfig. */
+declare function parseOpenCode(projectDir: string, files: DetectedFile[]): Promise<Partial<ProjectConfig>>;
+
+/** Options for running an import. */
+interface ImportOptions {
+    interactive: boolean;
+    sourceFilter?: SourceTool;
+    /** In interactive mode, this function selects which files to import. */
+    selectFiles?: (detected: DetectedFile[]) => Promise<DetectedFile[]>;
+}
+/** Result of an import operation. */
+interface ImportResult {
+    detected: DetectedFile[];
+    imported: DetectedFile[];
+    config: ProjectConfig;
+    filesWritten: string[];
+}
+/** Run the import pipeline: scan → select → parse → merge → write. */
+declare function runImport(projectDir: string, options: ImportOptions): Promise<ImportResult>;
+
+/** Serialize a ProjectConfig back to an `.ai/` directory. Returns paths of written files. */
+declare function writeProjectConfig(aiDir: string, config: ProjectConfig): Promise<string[]>;
+
+/** Persisted state of last sync operation. */
+interface SyncState {
+    /** Timestamp of last sync. */
+    lastSync: string;
+    /** Map of relative file path → content hash. */
+    files: Record<string, string>;
+}
+/** Compute a content hash for a string. */
+declare function contentHash(content: string): string;
+/** Load the sync state from .ai/.state.json. */
+declare function loadState(projectDir: string): Promise<SyncState | null>;
+/** Save the sync state to .ai/.state.json. */
+declare function saveState(projectDir: string, files: EmittedFile[]): Promise<void>;
+/** Status of a generated file compared to what's on disk. */
+type FileStatus = "new" | "up-to-date" | "modified" | "conflict" | "orphaned";
+/** Result of comparing a file. */
+interface FileStatusEntry {
+    path: string;
+    status: FileStatus;
+}
+/**
+ * Compare generated files against on-disk state and last-known state.
+ * Returns status for each file plus any orphaned files from previous sync.
+ */
+declare function diffFiles(projectDir: string, generated: EmittedFile[], state: SyncState | null): Promise<FileStatusEntry[]>;
+
+export { ALL_TARGETS, type Agent, type ConfigError, type ConfigScope, Decision, type DetectedFile, type DetectedKind, type Directive, type EmitResult, type EmittedFile, type Emitter, type FileStatus, type FileStatusEntry, type Hook, HookEvent, type IgnorePattern, type ImportCommandOptions, type ImportOptions, type ImportResult, type InitOptions, type LoadResult, type ParsedMarkdown, type Permission, type ProjectConfig, SCOPE_PRECEDENCE, Scope, type Setting, type Skill, type SourceTool, type SyncOptions, type SyncState, TEMPLATES, TEMPLATE_NAMES, TargetTool, type TemplateInfo, type TemplateName, type ToolServer, Transport, type ValidationResult, agentsEmitter, contentHash, createAgent, createDirective, createHook, createIgnorePattern, createPermission, createSetting, createSkill, createToolServer, diffFiles, directivesEmitter, emptyConfig, getTemplate, hooksEmitter, isAgent, isDirective, isHook, isIgnorePattern, isPermission, isSetting, isSkill, isToolServer, loadMarkdownFile, loadMergedConfig, loadProjectConfig, loadSkills, loadState, mcpEmitter, mergeConfigs, parseClaude, parseCodex, parseCursor, parseMarkdownWithFrontmatter, parseOpenCode, permissionsEmitter, runCheck, runImport, runImportCommand, runInit, runStatus, runSync, saveState, scanForConfigs, scopeOutranks, skillsEmitter, validateConfig, writeProjectConfig };