agentsmesh 0.5.0 → 0.7.0

package/dist/engine.d.ts

@@ -1,5 +1,5 @@
-import { C as CanonicalFiles } from './canonical-types-gdrUi3bD.js';
-import { G as GenerateResult, V as ValidatedConfig, T as TargetLayoutScope, I as ImportResult } from './target-descriptor-D64xD0C2.js';
+import { V as ValidatedConfig, b as CanonicalFiles } from './schema-B7ZSqkrS.js';
+import { G as GenerateResult, h as TargetLayoutScope, L as LintDiagnostic, d as ImportResult } from './target-descriptor-COp3nil6.js';
 import 'zod';
 
 /**
@@ -31,26 +31,216 @@ interface GenerateContext {
 declare function generate(ctx: GenerateContext): Promise<GenerateResult[]>;
 
 /**
- * Standalone target ID constants.
+ * Typed error taxonomy for agentsmesh programmatic consumers.
  *
- * 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.
+ * 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;
+    });
+}
+
+/**
+ * Diff engine: produces unified diffs between generated content and on-disk files.
  */
-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];
 
+interface DiffEntry {
+    path: string;
+    patch: string;
+}
+interface DiffSummary {
+    new: number;
+    updated: number;
+    unchanged: number;
+    deleted: number;
+}
+interface ComputeDiffResult {
+    diffs: DiffEntry[];
+    summary: DiffSummary;
+}
 /**
- * Public API — generation and import (see package.json "exports"."./engine").
- * Stability: follow semver for these symbols; internal modules are not supported.
+ * 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: {
+declare function importFrom(target: string, 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 LoadProjectContextOptions {
+    /** Defaults to `'project'`. Use `'global'` to load `~/.agentsmesh/`. */
+    readonly scope?: TargetLayoutScope;
+    /** Refresh remote extend cache before loading canonical content. */
+    readonly refreshRemoteCache?: boolean;
+}
+interface ProjectContext {
+    readonly config: ValidatedConfig;
+    readonly canonical: CanonicalFiles;
+    /** Root base used for generated paths: project config dir or user home for global scope. */
+    readonly projectRoot: string;
+    readonly scope: TargetLayoutScope;
+    readonly configDir: string;
+    readonly canonicalDir: string;
+}
+/**
+ * Load the same execution context the CLI uses: scoped config, plugin
+ * descriptors, extends, packs, and local canonical content. The returned object
+ * is directly usable as a `GenerateContext` because it contains
+ * `{ config, canonical, projectRoot, scope }`.
+ */
+declare function loadProjectContext(projectRoot: string, options?: LoadProjectContextOptions): Promise<ProjectContext>;
+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 { type GenerateContext, GenerateResult, ImportResult, generate, importFrom, resolveOutputCollisions };
+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, type LoadProjectContextOptions, LockAcquisitionError, type LockSyncReport, type ProjectContext, RemoteFetchError, TargetLayoutScope, TargetNotFoundError, ValidatedConfig, check, computeDiff, diff, formatDiffSummary, generate, importFrom, lint, loadConfig, loadConfigFromDirectory, loadProjectContext, resolveOutputCollisions };