agentsmesh 0.3.1 → 0.6.0

package/dist/target-descriptor-DjHhww11.d.ts

@@ -0,0 +1,364 @@
+import { b as CanonicalFiles, c as CanonicalRule } from './canonical-types-CZwrJoBX.js';
+import { z } from 'zod';
+
+/** Result of generating files for a target */
+interface GenerateResult {
+    /** Target tool ID */
+    target: string;
+    /** File path (relative to project root) */
+    path: string;
+    /** File content (what would be written) */
+    content: string;
+    /** Current on-disk content, set when status is updated or unchanged */
+    currentContent?: string;
+    /** What happened: created, updated, unchanged, skipped */
+    status: 'created' | 'updated' | 'unchanged' | 'skipped';
+    /** If skipped, why */
+    skipReason?: string;
+}
+/** Result of importing from a tool */
+interface ImportResult {
+    /** Source tool */
+    fromTool: string;
+    /** Source file path */
+    fromPath: string;
+    /** Destination canonical path */
+    toPath: string;
+    /** What was imported */
+    feature: string;
+}
+/** Lint diagnostic */
+interface LintDiagnostic {
+    level: 'error' | 'warning';
+    file: string;
+    target: string;
+    message: string;
+}
+/** Feature support level per target */
+type SupportLevel = 'native' | 'embedded' | 'partial' | 'none';
+
+/** Zod schema for agentsmesh.yaml config validation */
+declare const configSchema: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    targets: z.ZodDefault<z.ZodArray<z.ZodEnum<{
+        "claude-code": "claude-code";
+        cursor: "cursor";
+        copilot: "copilot";
+        continue: "continue";
+        junie: "junie";
+        kiro: "kiro";
+        "gemini-cli": "gemini-cli";
+        cline: "cline";
+        "codex-cli": "codex-cli";
+        windsurf: "windsurf";
+        antigravity: "antigravity";
+        "roo-code": "roo-code";
+    }>>>;
+    features: z.ZodDefault<z.ZodArray<z.ZodEnum<{
+        rules: "rules";
+        commands: "commands";
+        agents: "agents";
+        skills: "skills";
+        mcp: "mcp";
+        hooks: "hooks";
+        ignore: "ignore";
+        permissions: "permissions";
+    }>>>;
+    extends: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        source: z.ZodString;
+        version: z.ZodOptional<z.ZodString>;
+        target: z.ZodOptional<z.ZodEnum<{
+            "claude-code": "claude-code";
+            cursor: "cursor";
+            copilot: "copilot";
+            continue: "continue";
+            junie: "junie";
+            kiro: "kiro";
+            "gemini-cli": "gemini-cli";
+            cline: "cline";
+            "codex-cli": "codex-cli";
+            windsurf: "windsurf";
+            antigravity: "antigravity";
+            "roo-code": "roo-code";
+        }>>;
+        features: z.ZodArray<z.ZodEnum<{
+            rules: "rules";
+            commands: "commands";
+            agents: "agents";
+            skills: "skills";
+            mcp: "mcp";
+            hooks: "hooks";
+            ignore: "ignore";
+            permissions: "permissions";
+        }>>;
+        path: z.ZodOptional<z.ZodString>;
+        pick: z.ZodOptional<z.ZodObject<{
+            skills: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            commands: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            rules: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            agents: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        }, z.core.$strict>>;
+    }, z.core.$strip>>>;
+    overrides: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+    collaboration: z.ZodDefault<z.ZodObject<{
+        strategy: z.ZodDefault<z.ZodEnum<{
+            merge: "merge";
+            lock: "lock";
+            "last-wins": "last-wins";
+        }>>;
+        lock_features: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>>;
+    conversions: z.ZodOptional<z.ZodObject<{
+        commands_to_skills: z.ZodOptional<z.ZodObject<{
+            'codex-cli': z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodObject<{
+                project: z.ZodOptional<z.ZodBoolean>;
+                global: z.ZodOptional<z.ZodBoolean>;
+            }, z.core.$strict>]>>;
+        }, z.core.$loose>>;
+        agents_to_skills: z.ZodOptional<z.ZodObject<{
+            'gemini-cli': z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodObject<{
+                project: z.ZodOptional<z.ZodBoolean>;
+                global: z.ZodOptional<z.ZodBoolean>;
+            }, z.core.$strict>]>>;
+            cline: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodObject<{
+                project: z.ZodOptional<z.ZodBoolean>;
+                global: z.ZodOptional<z.ZodBoolean>;
+            }, z.core.$strict>]>>;
+            'codex-cli': z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodObject<{
+                project: z.ZodOptional<z.ZodBoolean>;
+                global: z.ZodOptional<z.ZodBoolean>;
+            }, z.core.$strict>]>>;
+            windsurf: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodObject<{
+                project: z.ZodOptional<z.ZodBoolean>;
+                global: z.ZodOptional<z.ZodBoolean>;
+            }, z.core.$strict>]>>;
+        }, z.core.$loose>>;
+    }, z.core.$strict>>;
+    plugins: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        source: z.ZodString;
+        version: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>>;
+    pluginTargets: z.ZodDefault<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+type ValidatedConfig = z.infer<typeof configSchema>;
+
+/** Serialization / projection variant for a canonical feature (see architecture review §3.3). */
+type FeatureFlavor = 'standard' | 'workflows' | 'settings-embedded' | 'projected-skills' | 'gh-actions-lite' | string;
+/** Normalized capability entry: support level plus optional serialization flavor. */
+interface TargetCapabilityValue {
+    readonly level: SupportLevel;
+    readonly flavor?: FeatureFlavor;
+}
+/** Descriptor may still use legacy string levels until fully migrated — normalize on read. */
+type TargetCapabilityInput = SupportLevel | TargetCapabilityValue;
+
+/**
+ * Capabilities of a target tool — each feature has a level and optional serialization flavor.
+ * String levels are accepted for authoring; `getTargetCapabilities` normalizes to objects.
+ */
+type TargetCapabilities = Record<'rules' | 'additionalRules' | 'commands' | 'agents' | 'skills' | 'mcp' | 'hooks' | 'ignore' | 'permissions', TargetCapabilityInput>;
+/** Optional context passed to feature generators (flavor-aware targets). */
+interface GenerateFeatureContext {
+    readonly capability: TargetCapabilityValue;
+    readonly scope: TargetLayoutScope;
+}
+type FeatureGeneratorOutput = {
+    path: string;
+    content: string;
+};
+type FeatureGeneratorFn = (canonical: CanonicalFiles, ctx?: GenerateFeatureContext) => FeatureGeneratorOutput[];
+/**
+ * Per-feature generator contract matching engine.ts dispatch tables.
+ * Each generator takes CanonicalFiles and returns file outputs.
+ * Only generateRules and importFrom are required; all others are optional
+ * because not every target supports every feature.
+ */
+interface TargetGenerators {
+    name: string;
+    primaryRootInstructionPath?: string;
+    generateRules: FeatureGeneratorFn;
+    generateCommands?: FeatureGeneratorFn;
+    generateAgents?: FeatureGeneratorFn;
+    generateSkills?: FeatureGeneratorFn;
+    generateMcp?: FeatureGeneratorFn;
+    generatePermissions?: FeatureGeneratorFn;
+    generateHooks?: FeatureGeneratorFn;
+    generateIgnore?: FeatureGeneratorFn;
+    importFrom(projectRoot: string, options?: {
+        scope?: TargetLayoutScope;
+    }): Promise<ImportResult[]>;
+    lint?(files: CanonicalFiles): LintDiagnostic[];
+}
+
+/**
+ * Self-describing target descriptor interface.
+ *
+ * A new target exports one TargetDescriptor from its index.ts.
+ * The catalog imports it and adds it to BUILTIN_TARGETS — that
+ * is the only central registration step.
+ *
+ * Designed for future plugin support: plugins will export a
+ * TargetDescriptor that gets registered at runtime.
+ */
+
+/** Declared output families for reference rewriting and decoration (architecture P1-3). */
+interface TargetOutputFamily {
+    readonly id: string;
+    readonly kind: 'primary' | 'mirror' | 'additional';
+    /** Match generated paths under this prefix (e.g. Copilot `.github/instructions/`). */
+    readonly pathPrefix?: string;
+    /** Explicit paths for additional root mirrors (Cursor, Gemini compat). */
+    readonly explicitPaths?: readonly string[];
+}
+/**
+ * Path resolvers for the output reference map.
+ * Each method returns a relative output path, or null to skip.
+ *
+ * Shared pre-checks (root rule handling, target filtering) remain
+ * centralized in map-targets.ts — descriptors only handle the
+ * target-specific path logic after those guards pass.
+ */
+interface TargetPathResolvers {
+    /** Output path for a non-root, non-filtered rule. */
+    rulePath(slug: string, rule: CanonicalRule): string;
+    /** Output path for a command. Null suppresses generation. */
+    commandPath(name: string, config: ValidatedConfig): string | null;
+    /** Output path for an agent. Null suppresses generation. */
+    agentPath(name: string, config: ValidatedConfig): string | null;
+}
+interface TargetManagedOutputs {
+    dirs: readonly string[];
+    files: readonly string[];
+}
+interface TargetLayout {
+    /** Primary root instruction artifact for this scope, if any. */
+    readonly rootInstructionPath?: string;
+    /**
+     * Extra generated paths that should receive the same AgentsMesh root appendix as
+     * `rootInstructionPath` (for example Cursor `AGENTS.md` / `.cursor/AGENTS.md`, Gemini `AGENTS.md`).
+     * @deprecated Prefer `outputFamilies` with `kind: 'additional'`.
+     */
+    readonly additionalRootDecorationPaths?: readonly string[];
+    /** Output families for rewrite cache keys and root decoration (see `layout-outputs.ts`). */
+    readonly outputFamilies?: readonly TargetOutputFamily[];
+    /** Optional renderer for scope-specific primary root instruction content. */
+    readonly renderPrimaryRootInstruction?: (canonical: CanonicalFiles) => string;
+    /** Target-native skills directory for this scope, if any. */
+    readonly skillDir?: string;
+    /** Files/directories agentsmesh fully manages for stale cleanup. */
+    readonly managedOutputs?: TargetManagedOutputs;
+    /** Optional path rewriter for scope-specific generated outputs. Return null to skip emission. */
+    readonly rewriteGeneratedPath?: (path: string) => string | null;
+    /**
+     * Optional mirror hook. Called after rewriteGeneratedPath resolves the primary path.
+     * Returns an additional path to emit the same content to, or null to skip mirroring.
+     */
+    readonly mirrorGlobalPath?: (path: string, activeTargets: readonly string[]) => string | readonly string[] | null;
+    /** Path resolvers for this scope. */
+    readonly paths: TargetPathResolvers;
+}
+type TargetLayoutScope = 'project' | 'global';
+/** Scope extras hook (e.g. Claude Code global output-styles). */
+type ScopeExtrasFn = (canonical: CanonicalFiles, projectRoot: string, scope: TargetLayoutScope, enabledFeatures: ReadonlySet<string>) => Promise<GenerateResult[]>;
+/** Single block for global-mode support (replaces scattered global* fields). */
+interface GlobalTargetSupport {
+    readonly capabilities: TargetCapabilities;
+    readonly detectionPaths: readonly string[];
+    readonly layout: TargetLayout;
+    readonly scopeExtras?: ScopeExtrasFn;
+}
+/** Import-path builder: populates refs with (target path -> canonical path) mappings. */
+type ImportPathBuilder = (refs: Map<string, string>, projectRoot: string, scope?: TargetLayoutScope) => Promise<void>;
+/** Rule linter function signature. */
+type RuleLinter = (canonical: CanonicalFiles, projectRoot: string, projectFiles: string[], options?: {
+    scope?: TargetLayoutScope;
+}) => LintDiagnostic[];
+/** Feature-specific lint hook signature. */
+type FeatureLinter = (canonical: CanonicalFiles, options?: unknown) => LintDiagnostic[];
+/** Optional per-feature lint hooks for target-specific validation. */
+interface TargetLintHooks {
+    readonly commands?: FeatureLinter;
+    readonly mcp?: FeatureLinter;
+    readonly permissions?: FeatureLinter;
+    readonly hooks?: FeatureLinter;
+    readonly ignore?: FeatureLinter;
+    readonly settings?: FeatureLinter;
+}
+/**
+ * Full self-describing target descriptor.
+ * Bundles everything needed to generate, import, lint, and detect a target.
+ */
+interface TargetDescriptor {
+    /** Unique target identifier, e.g. 'claude-code' */
+    readonly id: string;
+    /** Feature generators (rules, commands, agents, etc.) */
+    readonly generators: TargetGenerators;
+    /** Feature support levels */
+    readonly capabilities: TargetCapabilities;
+    /** Consolidated global-mode metadata (preferred over bare `global*` fields). */
+    readonly globalSupport?: GlobalTargetSupport;
+    /** Optional global-scope feature support levels when they differ from project mode */
+    readonly globalCapabilities?: TargetCapabilities;
+    /** Message shown when import finds nothing for this target */
+    readonly emptyImportMessage: string;
+    /** Optional linter for canonical files */
+    readonly lintRules: RuleLinter | null;
+    /** Optional per-feature lint hooks */
+    readonly lint?: TargetLintHooks;
+    /** Project-scope target layout metadata */
+    readonly project: TargetLayout;
+    /** Optional global-scope layout (use `globalSupport.layout` when `globalSupport` is set). */
+    readonly global?: TargetLayout;
+    /**
+     * Declares which embedded-capability features support user-configured conversion.
+     * When the corresponding conversion is disabled in config, the feature generator is skipped.
+     */
+    readonly supportsConversion?: {
+        readonly commands?: true;
+        readonly agents?: true;
+    };
+    /**
+     * Optional hook for generating scope-specific extras beyond the standard feature loop.
+     * Prefer `globalSupport.scopeExtras` for global-only extras.
+     */
+    readonly generateScopeExtras?: ScopeExtrasFn;
+    /** @deprecated Use project.skillDir */
+    readonly skillDir?: string;
+    /** @deprecated Use project.paths */
+    readonly paths?: TargetPathResolvers;
+    /** Import reference map builder */
+    readonly buildImportPaths: ImportPathBuilder;
+    /** Filesystem paths used to detect this target during `init` */
+    readonly detectionPaths: readonly string[];
+    /** Optional filesystem paths used to detect this target in global scope during `init --global` */
+    readonly globalDetectionPaths?: readonly string[];
+    /**
+     * Declares which shared artifact paths this target owns or consumes.
+     * Used by the reference rewriter to select the correct artifact map for shared outputs.
+     * Example: codex-cli owns '.agents/skills/', copilot consumes it in global mode.
+     */
+    readonly sharedArtifacts?: {
+        readonly [pathPrefix: string]: 'owner' | 'consumer';
+    };
+    /**
+     * Optional native settings sidecar (e.g. Gemini `.gemini/settings.json` when embedded features are on).
+     */
+    readonly emitScopedSettings?: (canonical: CanonicalFiles, scope: TargetLayoutScope) => readonly {
+        readonly path: string;
+        readonly content: string;
+    }[];
+    /**
+     * Async post-pass for hook generator outputs (e.g. Copilot hook script assets under `.github/hooks/`).
+     */
+    readonly postProcessHookOutputs?: (projectRoot: string, canonical: CanonicalFiles, outputs: readonly {
+        readonly path: string;
+        readonly content: string;
+    }[]) => Promise<readonly {
+        readonly path: string;
+        readonly content: string;
+    }[]>;
+}
+
+export type { FeatureLinter as F, GenerateResult as G, ImportPathBuilder as I, LintDiagnostic as L, RuleLinter as R, ScopeExtrasFn as S, TargetCapabilities as T, ValidatedConfig as V, GlobalTargetSupport as a, ImportResult as b, TargetDescriptor as c, TargetGenerators as d, TargetLayout as e, TargetLayoutScope as f, TargetLintHooks as g, TargetManagedOutputs as h, TargetOutputFamily as i, TargetPathResolvers as j };

package/dist/targets.d.ts

@@ -0,0 +1,18 @@
+import { c as TargetDescriptor } from './target-descriptor-DjHhww11.js';
+export { F as FeatureLinter, a as GlobalTargetSupport, I as ImportPathBuilder, R as RuleLinter, S as ScopeExtrasFn, T as TargetCapabilities, d as TargetGenerators, e as TargetLayout, f as TargetLayoutScope, g as TargetLintHooks, h as TargetManagedOutputs, i as TargetOutputFamily, j as TargetPathResolvers } from './target-descriptor-DjHhww11.js';
+import './canonical-types-CZwrJoBX.js';
+import 'zod';
+
+/** Register a full target descriptor (for plugins). */
+declare function registerTargetDescriptor(descriptor: TargetDescriptor): void;
+/** Look up a full descriptor by target ID. */
+declare function getDescriptor(name: string): TargetDescriptor | undefined;
+declare function getAllDescriptors(): TargetDescriptor[];
+
+/**
+ * Public API — built-in target catalog and plugin registration (package.json "exports"."./targets").
+ */
+
+declare function getTargetCatalog(): readonly TargetDescriptor[];
+
+export { TargetDescriptor, getAllDescriptors, getDescriptor, getTargetCatalog, registerTargetDescriptor };