agentsmesh 0.3.1 → 0.6.0

package/dist/engine.d.ts

@@ -0,0 +1,237 @@
+import { b as CanonicalFiles } from './canonical-types-CZwrJoBX.js';
+import { G as GenerateResult, V as ValidatedConfig, f as TargetLayoutScope, L as LintDiagnostic, b as ImportResult } from './target-descriptor-DjHhww11.js';
+import 'zod';
+
+/**
+ * Resolve duplicate generated outputs that target the same path.
+ * Identical content is deduplicated; conflicting content throws.
+ *
+ * @param results - Raw generated outputs collected per target/feature
+ * @returns Deduplicated results preserving first-seen order
+ */
+declare function resolveOutputCollisions(results: GenerateResult[]): GenerateResult[];
+
+/**
+ * Generate orchestrator: produces target-specific files from canonical sources.
+ */
+
+interface GenerateContext {
+    config: ValidatedConfig;
+    canonical: CanonicalFiles;
+    projectRoot: string;
+    scope?: TargetLayoutScope;
+    targetFilter?: string[];
+}
+
+/**
+ * Generate target files from canonical sources.
+ * @param ctx - Config, canonical files, project root, optional target filter
+ * @returns GenerateResult[] with status per file
+ */
+declare function generate(ctx: GenerateContext): Promise<GenerateResult[]>;
+
+/**
+ * Typed error taxonomy for agentsmesh programmatic consumers.
+ *
+ * All public-API errors inherit from AgentsMeshError and carry a stable `code`
+ * property. Consumers can branch on `err instanceof AgentsMeshError && err.code === 'AM_...'`
+ * without relying on error message strings.
+ */
+type AgentsMeshErrorCode = 'AM_CONFIG_NOT_FOUND' | 'AM_CONFIG_INVALID' | 'AM_TARGET_NOT_FOUND' | 'AM_TARGET_UNSUPPORTED' | 'AM_IMPORT_FAILED' | 'AM_GENERATION_FAILED' | 'AM_REMOTE_FETCH_FAILED' | 'AM_LOCK_ACQUISITION_FAILED' | 'AM_LOCK_CONFLICT' | 'AM_FILESYSTEM';
+declare class AgentsMeshError extends Error {
+    readonly code: AgentsMeshErrorCode;
+    constructor(code: AgentsMeshErrorCode, message: string, options?: {
+        cause?: unknown;
+    });
+}
+declare class ConfigNotFoundError extends AgentsMeshError {
+    readonly path: string;
+    constructor(path: string, options?: {
+        cause?: unknown;
+        message?: string;
+    });
+}
+declare class ConfigValidationError extends AgentsMeshError {
+    readonly issues: readonly string[];
+    constructor(path: string, issues: readonly string[], options?: {
+        cause?: unknown;
+    });
+}
+declare class TargetNotFoundError extends AgentsMeshError {
+    readonly target: string;
+    constructor(target: string, options?: {
+        cause?: unknown;
+        supported?: readonly string[];
+    });
+}
+declare class ImportError extends AgentsMeshError {
+    readonly target: string;
+    constructor(target: string, message: string, options?: {
+        cause?: unknown;
+    });
+}
+declare class GenerationError extends AgentsMeshError {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+declare class RemoteFetchError extends AgentsMeshError {
+    readonly source: string;
+    constructor(source: string, message: string, options?: {
+        cause?: unknown;
+    });
+}
+declare class LockAcquisitionError extends AgentsMeshError {
+    readonly lockPath: string;
+    readonly holder: string;
+    constructor(lockPath: string, holder: string, options?: {
+        cause?: unknown;
+    });
+}
+declare class FileSystemError extends AgentsMeshError {
+    readonly path: string;
+    readonly errnoCode?: string;
+    constructor(path: string, message: string, options?: {
+        cause?: unknown;
+        errnoCode?: string;
+    });
+}
+
+/**
+ * Standalone target ID constants.
+ *
+ * Extracted from builtin-targets.ts to break a circular type dependency:
+ * schema.ts → builtin-targets.ts → descriptors → ValidatedConfig → schema.ts
+ *
+ * When adding a new target, add its ID here AND its descriptor to
+ * BUILTIN_TARGETS in builtin-targets.ts. A compile-time assertion
+ * in builtin-targets.ts ensures they stay in sync.
+ */
+declare const TARGET_IDS: readonly ["claude-code", "cursor", "copilot", "continue", "junie", "kiro", "gemini-cli", "cline", "codex-cli", "windsurf", "antigravity", "roo-code"];
+type BuiltinTargetId = (typeof TARGET_IDS)[number];
+
+/**
+ * Diff engine: produces unified diffs between generated content and on-disk files.
+ */
+
+interface DiffEntry {
+    path: string;
+    patch: string;
+}
+interface DiffSummary {
+    new: number;
+    updated: number;
+    unchanged: number;
+    deleted: number;
+}
+interface ComputeDiffResult {
+    diffs: DiffEntry[];
+    summary: DiffSummary;
+}
+/**
+ * Format diff summary for user display.
+ * @param summary - Counts from computeDiff
+ * @returns Human-readable string
+ */
+declare function formatDiffSummary(summary: DiffSummary): string;
+
+/**
+ * Pure lock-vs-current drift detection used by `agentsmesh check` and the
+ * public Programmatic API. The CLI command formats and exits; this helper
+ * returns a structured report.
+ */
+
+interface LockSyncReport {
+    /** True when the canonical state matches the lock file and no extend drifted. */
+    readonly inSync: boolean;
+    /** True when a `.lock` file was found at the canonical directory. */
+    readonly hasLock: boolean;
+    /** Canonical files whose checksum differs from the lock. */
+    readonly modified: readonly string[];
+    /** Canonical files present now but not in the lock. */
+    readonly added: readonly string[];
+    /** Canonical files in the lock but missing now. */
+    readonly removed: readonly string[];
+    /** Extend names whose pinned version/checksum differs from the lock. */
+    readonly extendsModified: readonly string[];
+    /**
+     * Subset of `modified ∪ added ∪ removed` that violates
+     * `collaboration.lock_features`. Empty when no `lock_features` are configured.
+     */
+    readonly lockedViolations: readonly string[];
+}
+interface CheckLockSyncOptions {
+    readonly config: ValidatedConfig;
+    /** Directory containing `agentsmesh.yaml` (used to resolve relative extends). */
+    readonly configDir: string;
+    /** Directory containing `.agentsmesh/.lock` and canonical files. */
+    readonly canonicalDir: string;
+}
+
+declare function importFrom(target: BuiltinTargetId, opts: {
+    root: string;
+    scope?: 'project' | 'global';
+}): Promise<ImportResult[]>;
+/**
+ * Load and validate `agentsmesh.yaml` from a project root, merging
+ * `agentsmesh.local.yaml` if present. Searches upward from `projectRoot` for
+ * the config file (matches CLI behaviour).
+ *
+ * Throws `ConfigNotFoundError` when no config is found, or
+ * `ConfigValidationError` when YAML parses but fails schema validation.
+ */
+declare function loadConfig(projectRoot: string): Promise<{
+    config: ValidatedConfig;
+    configDir: string;
+}>;
+/**
+ * Like {@link loadConfig} but does not search upward — reads
+ * `<configDir>/agentsmesh.yaml` directly. Used by global scope where the
+ * canonical directory is `~/.agentsmesh/`.
+ */
+declare function loadConfigFromDirectory(configDir: string): Promise<{
+    config: ValidatedConfig;
+    configDir: string;
+}>;
+interface LintOptions {
+    readonly config: ValidatedConfig;
+    readonly canonical: CanonicalFiles;
+    /** Directory used for project-file glob matching (typically the project root). */
+    readonly projectRoot: string;
+    /** Optional whitelist of target IDs to lint. Defaults to all enabled. */
+    readonly targetFilter?: readonly string[];
+    /** Defaults to `'project'`. */
+    readonly scope?: TargetLayoutScope;
+}
+interface LintResult {
+    readonly diagnostics: readonly LintDiagnostic[];
+    readonly hasErrors: boolean;
+}
+/**
+ * Run lint across all enabled targets and return diagnostics. Pure: no I/O,
+ * no logging. Equivalent to `agentsmesh lint` minus formatting and exit code.
+ */
+declare function lint(opts: LintOptions): Promise<LintResult>;
+/**
+ * Compute unified diffs from a generate-result set. Use this when you already
+ * have results in hand (e.g. from {@link import('./engine.js').generate})
+ * and want to display drift without re-running generation.
+ */
+declare function computeDiff(results: readonly GenerateResult[]): ComputeDiffResult;
+/**
+ * Run generation and return the unified diff against on-disk content.
+ * Equivalent to `agentsmesh diff` minus formatting. Calls {@link generate}
+ * internally; returns both the raw results and the diff.
+ */
+declare function diff(ctx: GenerateContext): Promise<ComputeDiffResult & {
+    results: readonly GenerateResult[];
+}>;
+/**
+ * Compare the lock file at `canonicalDir/.lock` against the current canonical
+ * state and resolved extends. Equivalent to `agentsmesh check` minus
+ * formatting and exit code. Returns `hasLock: false` and `inSync: false` when
+ * no lock is present.
+ */
+declare function check(opts: CheckLockSyncOptions): Promise<LockSyncReport>;
+
+export { AgentsMeshError, type AgentsMeshErrorCode, CanonicalFiles, type CheckLockSyncOptions, type ComputeDiffResult, ConfigNotFoundError, ConfigValidationError, type DiffEntry, type DiffSummary, FileSystemError, type GenerateContext, GenerateResult, GenerationError, ImportError, ImportResult, LintDiagnostic, type LintOptions, type LintResult, LockAcquisitionError, type LockSyncReport, RemoteFetchError, TargetLayoutScope, TargetNotFoundError, ValidatedConfig, check, computeDiff, diff, formatDiffSummary, generate, importFrom, lint, loadConfig, loadConfigFromDirectory, resolveOutputCollisions };