@teamix-evo/registry 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,505 @@
+import { z } from 'zod';
+
+/**
+ * Update strategy for a resource.
+ * - frozen: CLI will not modify after first install
+ * - regenerable: Entire file is rewritten on update
+ * - managed: Only managed regions are rewritten, rest is preserved
+ */
+declare const UpdateStrategySchema: z.ZodEnum<["frozen", "regenerable", "managed"]>;
+/**
+ * Resource type discriminator.
+ */
+declare const ResourceTypeSchema: z.ZodEnum<["doc", "tokens", "ai-rules", "config"]>;
+/**
+ * A single resource entry within a variant manifest.
+ */
+declare const ResourceSchema: z.ZodObject<{
+    /** Unique identifier for the resource within the manifest */
+    id: z.ZodString;
+    /** Resource type */
+    type: z.ZodEnum<["doc", "tokens", "ai-rules", "config"]>;
+    /** Source path (relative to variant root), typically a template */
+    source: z.ZodString;
+    /** Target path (relative to project root) where the resource is installed */
+    target: z.ZodString;
+    /** How the resource is updated */
+    updateStrategy: z.ZodEnum<["frozen", "regenerable", "managed"]>;
+    /** Whether the source is a Handlebars template */
+    template: z.ZodOptional<z.ZodBoolean>;
+    /** IDs of managed regions (only relevant when updateStrategy is "managed") */
+    managedRegions: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    /** Whether to recursively process directory contents */
+    recursive: z.ZodOptional<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    id: string;
+    type: "doc" | "tokens" | "ai-rules" | "config";
+    source: string;
+    target: string;
+    updateStrategy: "frozen" | "regenerable" | "managed";
+    template?: boolean | undefined;
+    managedRegions?: string[] | undefined;
+    recursive?: boolean | undefined;
+}, {
+    id: string;
+    type: "doc" | "tokens" | "ai-rules" | "config";
+    source: string;
+    target: string;
+    updateStrategy: "frozen" | "regenerable" | "managed";
+    template?: boolean | undefined;
+    managedRegions?: string[] | undefined;
+    recursive?: boolean | undefined;
+}>;
+/**
+ * Variant manifest schema — describes a variant package and its resources.
+ */
+declare const VariantManifestSchema: z.ZodObject<{
+    $schema: z.ZodOptional<z.ZodString>;
+    schemaVersion: z.ZodLiteral<1>;
+    /** Package name (e.g. "design") */
+    package: z.ZodString;
+    /** Variant identifier (e.g. "opentrek") */
+    variant: z.ZodString;
+    /** Human-readable name */
+    displayName: z.ZodString;
+    /** Description of the variant */
+    description: z.ZodString;
+    /** Semver version string */
+    version: z.ZodString;
+    /** Engine compatibility */
+    engines: z.ZodObject<{
+        "teamix-evo": z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        "teamix-evo": string;
+    }, {
+        "teamix-evo": string;
+    }>;
+    /** Supported IDE identifiers */
+    ide: z.ZodArray<z.ZodString, "many">;
+    /** List of resources provided by this variant */
+    resources: z.ZodArray<z.ZodObject<{
+        /** Unique identifier for the resource within the manifest */
+        id: z.ZodString;
+        /** Resource type */
+        type: z.ZodEnum<["doc", "tokens", "ai-rules", "config"]>;
+        /** Source path (relative to variant root), typically a template */
+        source: z.ZodString;
+        /** Target path (relative to project root) where the resource is installed */
+        target: z.ZodString;
+        /** How the resource is updated */
+        updateStrategy: z.ZodEnum<["frozen", "regenerable", "managed"]>;
+        /** Whether the source is a Handlebars template */
+        template: z.ZodOptional<z.ZodBoolean>;
+        /** IDs of managed regions (only relevant when updateStrategy is "managed") */
+        managedRegions: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        /** Whether to recursively process directory contents */
+        recursive: z.ZodOptional<z.ZodBoolean>;
+    }, "strip", z.ZodTypeAny, {
+        id: string;
+        type: "doc" | "tokens" | "ai-rules" | "config";
+        source: string;
+        target: string;
+        updateStrategy: "frozen" | "regenerable" | "managed";
+        template?: boolean | undefined;
+        managedRegions?: string[] | undefined;
+        recursive?: boolean | undefined;
+    }, {
+        id: string;
+        type: "doc" | "tokens" | "ai-rules" | "config";
+        source: string;
+        target: string;
+        updateStrategy: "frozen" | "regenerable" | "managed";
+        template?: boolean | undefined;
+        managedRegions?: string[] | undefined;
+        recursive?: boolean | undefined;
+    }>, "many">;
+}, "strip", z.ZodTypeAny, {
+    schemaVersion: 1;
+    package: string;
+    variant: string;
+    displayName: string;
+    description: string;
+    version: string;
+    engines: {
+        "teamix-evo": string;
+    };
+    ide: string[];
+    resources: {
+        id: string;
+        type: "doc" | "tokens" | "ai-rules" | "config";
+        source: string;
+        target: string;
+        updateStrategy: "frozen" | "regenerable" | "managed";
+        template?: boolean | undefined;
+        managedRegions?: string[] | undefined;
+        recursive?: boolean | undefined;
+    }[];
+    $schema?: string | undefined;
+}, {
+    schemaVersion: 1;
+    package: string;
+    variant: string;
+    displayName: string;
+    description: string;
+    version: string;
+    engines: {
+        "teamix-evo": string;
+    };
+    ide: string[];
+    resources: {
+        id: string;
+        type: "doc" | "tokens" | "ai-rules" | "config";
+        source: string;
+        target: string;
+        updateStrategy: "frozen" | "regenerable" | "managed";
+        template?: boolean | undefined;
+        managedRegions?: string[] | undefined;
+        recursive?: boolean | undefined;
+    }[];
+    $schema?: string | undefined;
+}>;
+
+/**
+ * Package entry within a project config.
+ */
+declare const PackageEntrySchema: z.ZodObject<{
+    /** Variant identifier (e.g. "opentrek") */
+    variant: z.ZodString;
+    /** Semver version string */
+    version: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    variant: string;
+    version: string;
+}, {
+    variant: string;
+    version: string;
+}>;
+/**
+ * Project configuration schema — teamix-evo config.json at project root.
+ */
+declare const ProjectConfigSchema: z.ZodObject<{
+    $schema: z.ZodOptional<z.ZodString>;
+    schemaVersion: z.ZodLiteral<1>;
+    /** IDE identifier */
+    ide: z.ZodString;
+    /** Installed packages keyed by package name */
+    packages: z.ZodRecord<z.ZodString, z.ZodObject<{
+        /** Variant identifier (e.g. "opentrek") */
+        variant: z.ZodString;
+        /** Semver version string */
+        version: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        variant: string;
+        version: string;
+    }, {
+        variant: string;
+        version: string;
+    }>>;
+}, "strip", z.ZodTypeAny, {
+    schemaVersion: 1;
+    ide: string;
+    packages: Record<string, {
+        variant: string;
+        version: string;
+    }>;
+    $schema?: string | undefined;
+}, {
+    schemaVersion: 1;
+    ide: string;
+    packages: Record<string, {
+        variant: string;
+        version: string;
+    }>;
+    $schema?: string | undefined;
+}>;
+
+/**
+ * An installed resource entry — tracks individual resource installation state.
+ */
+declare const InstalledResourceSchema: z.ZodObject<{
+    /** Resource identifier matching the variant manifest */
+    id: z.ZodString;
+    /** Target path where the resource was installed */
+    target: z.ZodString;
+    /** Content hash for change detection (e.g. "sha256:...") */
+    hash: z.ZodString;
+    /** Update strategy that was applied */
+    strategy: z.ZodEnum<["frozen", "regenerable", "managed"]>;
+}, "strip", z.ZodTypeAny, {
+    id: string;
+    target: string;
+    hash: string;
+    strategy: "frozen" | "regenerable" | "managed";
+}, {
+    id: string;
+    target: string;
+    hash: string;
+    strategy: "frozen" | "regenerable" | "managed";
+}>;
+/**
+ * An installed package entry — tracks a single package installation.
+ */
+declare const InstalledPackageSchema: z.ZodObject<{
+    /** Full package name (e.g. "@teamix-evo/design") */
+    package: z.ZodString;
+    /** Variant identifier */
+    variant: z.ZodString;
+    /** Installed version */
+    version: z.ZodString;
+    /** ISO 8601 timestamp of installation */
+    installedAt: z.ZodString;
+    /** List of installed resources */
+    resources: z.ZodArray<z.ZodObject<{
+        /** Resource identifier matching the variant manifest */
+        id: z.ZodString;
+        /** Target path where the resource was installed */
+        target: z.ZodString;
+        /** Content hash for change detection (e.g. "sha256:...") */
+        hash: z.ZodString;
+        /** Update strategy that was applied */
+        strategy: z.ZodEnum<["frozen", "regenerable", "managed"]>;
+    }, "strip", z.ZodTypeAny, {
+        id: string;
+        target: string;
+        hash: string;
+        strategy: "frozen" | "regenerable" | "managed";
+    }, {
+        id: string;
+        target: string;
+        hash: string;
+        strategy: "frozen" | "regenerable" | "managed";
+    }>, "many">;
+}, "strip", z.ZodTypeAny, {
+    package: string;
+    variant: string;
+    version: string;
+    resources: {
+        id: string;
+        target: string;
+        hash: string;
+        strategy: "frozen" | "regenerable" | "managed";
+    }[];
+    installedAt: string;
+}, {
+    package: string;
+    variant: string;
+    version: string;
+    resources: {
+        id: string;
+        target: string;
+        hash: string;
+        strategy: "frozen" | "regenerable" | "managed";
+    }[];
+    installedAt: string;
+}>;
+/**
+ * Installed manifest schema — tracks all installed packages in a project.
+ * Stored at `.teamix-evo/manifest.json`.
+ */
+declare const InstalledManifestSchema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<1>;
+    /** List of installed packages */
+    installed: z.ZodArray<z.ZodObject<{
+        /** Full package name (e.g. "@teamix-evo/design") */
+        package: z.ZodString;
+        /** Variant identifier */
+        variant: z.ZodString;
+        /** Installed version */
+        version: z.ZodString;
+        /** ISO 8601 timestamp of installation */
+        installedAt: z.ZodString;
+        /** List of installed resources */
+        resources: z.ZodArray<z.ZodObject<{
+            /** Resource identifier matching the variant manifest */
+            id: z.ZodString;
+            /** Target path where the resource was installed */
+            target: z.ZodString;
+            /** Content hash for change detection (e.g. "sha256:...") */
+            hash: z.ZodString;
+            /** Update strategy that was applied */
+            strategy: z.ZodEnum<["frozen", "regenerable", "managed"]>;
+        }, "strip", z.ZodTypeAny, {
+            id: string;
+            target: string;
+            hash: string;
+            strategy: "frozen" | "regenerable" | "managed";
+        }, {
+            id: string;
+            target: string;
+            hash: string;
+            strategy: "frozen" | "regenerable" | "managed";
+        }>, "many">;
+    }, "strip", z.ZodTypeAny, {
+        package: string;
+        variant: string;
+        version: string;
+        resources: {
+            id: string;
+            target: string;
+            hash: string;
+            strategy: "frozen" | "regenerable" | "managed";
+        }[];
+        installedAt: string;
+    }, {
+        package: string;
+        variant: string;
+        version: string;
+        resources: {
+            id: string;
+            target: string;
+            hash: string;
+            strategy: "frozen" | "regenerable" | "managed";
+        }[];
+        installedAt: string;
+    }>, "many">;
+}, "strip", z.ZodTypeAny, {
+    schemaVersion: 1;
+    installed: {
+        package: string;
+        variant: string;
+        version: string;
+        resources: {
+            id: string;
+            target: string;
+            hash: string;
+            strategy: "frozen" | "regenerable" | "managed";
+        }[];
+        installedAt: string;
+    }[];
+}, {
+    schemaVersion: 1;
+    installed: {
+        package: string;
+        variant: string;
+        version: string;
+        resources: {
+            id: string;
+            target: string;
+            hash: string;
+            strategy: "frozen" | "regenerable" | "managed";
+        }[];
+        installedAt: string;
+    }[];
+}>;
+
+/** Resource update strategy */
+type UpdateStrategy = z.infer<typeof UpdateStrategySchema>;
+/** Resource type discriminator */
+type ResourceType = z.infer<typeof ResourceTypeSchema>;
+/** A single resource entry within a variant manifest */
+type Resource = z.infer<typeof ResourceSchema>;
+/** Variant manifest describing a package variant and its resources */
+type VariantManifest = z.infer<typeof VariantManifestSchema>;
+/** A package entry in the project config */
+type PackageEntry = z.infer<typeof PackageEntrySchema>;
+/** Project configuration (config.json) */
+type ProjectConfig = z.infer<typeof ProjectConfigSchema>;
+/** An installed resource tracking entry */
+type InstalledResource = z.infer<typeof InstalledResourceSchema>;
+/** An installed package tracking entry */
+type InstalledPackage = z.infer<typeof InstalledPackageSchema>;
+/** Installed manifest tracking all packages in a project */
+type InstalledManifest = z.infer<typeof InstalledManifestSchema>;
+/** Managed region parsed from document content */
+interface ManagedRegion {
+    /** Region identifier */
+    id: string;
+    /** The full start marker string */
+    startMarker: string;
+    /** The full end marker string */
+    endMarker: string;
+    /** Content between start and end markers */
+    content: string;
+}
+/** Generic result type for validation operations */
+type Result<T> = {
+    success: true;
+    data: T;
+} | {
+    success: false;
+    error: string;
+};
+
+/**
+ * Load and validate a variant manifest from a package directory.
+ *
+ * Reads `manifest.json` from the given directory, parses it as JSON,
+ * and validates it against the VariantManifest schema.
+ *
+ * @param packageDir - Absolute or relative path to the variant package directory
+ * @returns The validated VariantManifest
+ * @throws Error if the file cannot be read or the manifest is invalid
+ */
+declare function loadVariantManifest(packageDir: string): Promise<VariantManifest>;
+
+/**
+ * Validate unknown data against the VariantManifest schema.
+ * Returns a discriminated Result with either the parsed data or a friendly error message.
+ */
+declare function validateManifest(data: unknown): Result<VariantManifest>;
+/**
+ * Validate unknown data against the ProjectConfig schema.
+ */
+declare function validateConfig(data: unknown): Result<ProjectConfig>;
+/**
+ * Validate unknown data against the InstalledManifest schema.
+ */
+declare function validateInstalled(data: unknown): Result<InstalledManifest>;
+
+/**
+ * Parse all managed regions from document content.
+ *
+ * @param content - The full document content
+ * @returns Array of parsed ManagedRegion objects
+ * @throws Error if there are unmatched start/end markers
+ */
+declare function parseManagedRegions(content: string): ManagedRegion[];
+/**
+ * Replace the content of a specific managed region by id.
+ * Content outside managed regions is preserved.
+ *
+ * @param content - The full document content
+ * @param id - The region id to replace
+ * @param newContent - The new content for the region
+ * @returns The updated document content
+ * @throws Error if the region id is not found
+ */
+declare function replaceManagedRegion(content: string, id: string, newContent: string): string;
+/**
+ * Check whether a managed region with the given id exists in the content.
+ *
+ * @param content - The full document content
+ * @param id - The region id to check
+ * @returns true if the region exists
+ */
+declare function hasManagedRegion(content: string, id: string): boolean;
+
+/**
+ * Determine whether a resource should be updated based on its strategy
+ * and whether it already exists.
+ *
+ * @param strategy - The update strategy for the resource
+ * @param resourceExists - Whether the resource file already exists
+ * @returns true if the resource should be updated/created
+ */
+declare function shouldUpdate(strategy: UpdateStrategy, resourceExists: boolean): boolean;
+/** Possible actions returned by getUpdateAction */
+type UpdateAction = "skip" | "overwrite" | "managed-update";
+interface UpdateActionOptions {
+    /** Whether the resource file already exists */
+    exists: boolean;
+    /** Hash of the new content to be written */
+    hash?: string;
+    /** Hash of the currently installed content */
+    currentHash?: string;
+}
+/**
+ * Determine the specific update action to take for a resource.
+ *
+ * @param strategy - The update strategy for the resource
+ * @param options - Context about the resource's current state
+ * @returns The action to perform
+ */
+declare function getUpdateAction(strategy: UpdateStrategy, options: UpdateActionOptions): UpdateAction;
+
+export { type InstalledManifest, InstalledManifestSchema, type InstalledPackage, InstalledPackageSchema, type InstalledResource, InstalledResourceSchema, type ManagedRegion, type PackageEntry, PackageEntrySchema, type ProjectConfig, ProjectConfigSchema, type Resource, ResourceSchema, type ResourceType, ResourceTypeSchema, type Result, type UpdateAction, type UpdateActionOptions, type UpdateStrategy, UpdateStrategySchema, type VariantManifest, VariantManifestSchema, getUpdateAction, hasManagedRegion, loadVariantManifest, parseManagedRegions, replaceManagedRegion, shouldUpdate, validateConfig, validateInstalled, validateManifest };