@imjp/writenex-astro 0.1.0

package/dist/discovery/index.d.ts

@@ -0,0 +1,310 @@
+import { C as CollectionConfig, b as CollectionSchema } from '../config-BmEdBDo_.js';
+import { D as DiscoveredCollection } from '../content-BWR52vD-.js';
+
+/**
+ * @fileoverview Collection discovery for Astro content collections
+ *
+ * This module provides functions to auto-discover content collections
+ * from an Astro project's src/content directory.
+ *
+ * ## Discovery Process:
+ * 1. Scan src/content/ for subdirectories
+ * 2. Each subdirectory is treated as a collection
+ * 3. Count content files in each collection
+ * 4. Detect file patterns from existing files
+ * 5. Auto-detect frontmatter schema from sample files
+ *
+ * @module @writenex/astro/discovery/collections
+ */
+
+/**
+ * Discover all content collections in a project
+ *
+ * Scans the src/content directory for subdirectories and treats
+ * each as a content collection.
+ *
+ * @param projectRoot - Absolute path to the project root
+ * @param contentDir - Relative path to content directory (default: src/content)
+ * @returns Array of discovered collections
+ *
+ * @example
+ * ```typescript
+ * const collections = await discoverCollections('/path/to/project');
+ * // Returns: [
+ * //   { name: 'blog', path: 'src/content/blog', count: 10, ... },
+ * //   { name: 'docs', path: 'src/content/docs', count: 5, ... },
+ * // ]
+ * ```
+ */
+declare function discoverCollections(projectRoot: string, contentDir?: string): Promise<DiscoveredCollection[]>;
+/**
+ * Merge discovered collections with configured collections
+ *
+ * Configured collections take precedence over discovered ones.
+ * This allows users to override auto-discovered settings.
+ *
+ * @param discovered - Auto-discovered collections
+ * @param configured - User-configured collections
+ * @returns Merged collection list
+ */
+declare function mergeCollections(discovered: DiscoveredCollection[], configured: CollectionConfig[]): DiscoveredCollection[];
+/**
+ * Get a single collection by name
+ *
+ * @param projectRoot - Absolute path to the project root
+ * @param collectionName - Name of the collection
+ * @param contentDir - Relative path to content directory
+ * @returns The collection if found, undefined otherwise
+ */
+declare function getCollection(projectRoot: string, collectionName: string, contentDir?: string): Promise<DiscoveredCollection | undefined>;
+/**
+ * Check if a collection exists
+ *
+ * @param projectRoot - Absolute path to the project root
+ * @param collectionName - Name of the collection
+ * @param contentDir - Relative path to content directory
+ * @returns True if the collection exists
+ */
+declare function collectionExists(projectRoot: string, collectionName: string, contentDir?: string): Promise<boolean>;
+
+/**
+ * @fileoverview File pattern detection for content collections
+ *
+ * This module provides functions to detect and work with file naming patterns
+ * in Astro content collections.
+ *
+ * ## Supported Patterns:
+ * - `{slug}.md` - Simple slug-based naming
+ * - `{date}-{slug}.md` - Date-prefixed naming (2024-01-15-my-post.md)
+ * - `{year}/{slug}.md` - Year folder structure
+ * - `{year}/{month}/{slug}.md` - Year/month folder structure
+ * - `{year}/{month}/{day}/{slug}.md` - Full date folder structure
+ * - `{slug}/index.md` - Folder-based with index file
+ * - `{category}/{slug}.md` - Category folder structure
+ * - `{category}/{slug}/index.md` - Category with folder-based content
+ * - `{lang}/{slug}.md` - Language-prefixed content (i18n)
+ * - `{lang}/{slug}/index.md` - Language with folder-based content
+ *
+ * ## Custom Patterns:
+ * Developers can configure custom patterns in their collection config.
+ * Custom tokens are resolved from frontmatter data or use default values.
+ *
+ * ## Detection Process:
+ * 1. Scan collection directory for all content files
+ * 2. Analyze file paths and names for common patterns
+ * 3. Score each pattern based on match frequency
+ * 4. Return the best matching pattern
+ *
+ * @module @writenex/astro/discovery/patterns
+ */
+/**
+ * Result of pattern detection
+ */
+interface PatternDetectionResult {
+    /** The detected pattern template */
+    pattern: string;
+    /** Confidence score (0-1) */
+    confidence: number;
+    /** Number of files that matched this pattern */
+    matchCount: number;
+    /** Total files analyzed */
+    totalFiles: number;
+    /** Sample matches for debugging */
+    samples: Array<{
+        filePath: string;
+        extracted: Record<string, string>;
+    }>;
+}
+/**
+ * Detect the file naming pattern used in a collection
+ *
+ * Analyzes all content files in the collection directory and determines
+ * the most likely pattern based on file names and structure.
+ *
+ * @param collectionPath - Absolute path to the collection directory
+ * @returns Pattern detection result with confidence score
+ *
+ * @example
+ * ```typescript
+ * const result = await detectFilePattern('/project/src/content/blog');
+ * console.log(result.pattern); // "{date}-{slug}.md"
+ * console.log(result.confidence); // 0.95
+ * ```
+ */
+declare function detectFilePattern(collectionPath: string): Promise<PatternDetectionResult>;
+/**
+ * Generate a file path from a pattern and tokens
+ *
+ * @param pattern - Pattern template (e.g., "{date}-{slug}.md")
+ * @param tokens - Token values to substitute
+ * @returns Generated file path
+ *
+ * @example
+ * ```typescript
+ * const path = generatePathFromPattern(
+ *   "{date}-{slug}.md",
+ *   { date: "2024-01-15", slug: "my-post" }
+ * );
+ * // Returns: "2024-01-15-my-post.md"
+ * ```
+ */
+declare function generatePathFromPattern(pattern: string, tokens: Record<string, string>): string;
+/**
+ * Parse a pattern template to extract token names
+ *
+ * @param pattern - Pattern template
+ * @returns Array of token names
+ *
+ * @example
+ * ```typescript
+ * const tokens = parsePatternTokens("{year}/{month}/{slug}.md");
+ * // Returns: ["year", "month", "slug"]
+ * ```
+ */
+declare function parsePatternTokens(pattern: string): string[];
+/**
+ * Validate that a pattern has all required tokens
+ *
+ * @param pattern - Pattern template
+ * @param requiredTokens - Required token names
+ * @returns True if all required tokens are present
+ */
+declare function validatePattern(pattern: string, requiredTokens?: string[]): boolean;
+/**
+ * Get the default extension for a pattern
+ *
+ * @param pattern - Pattern template
+ * @returns The file extension (.md or .mdx)
+ */
+declare function getPatternExtension(pattern: string): string;
+/**
+ * Options for resolving pattern tokens
+ */
+interface ResolveTokensOptions {
+    /** The content slug */
+    slug: string;
+    /** Frontmatter data for resolving dynamic tokens */
+    frontmatter?: Record<string, unknown>;
+    /** Custom token values (override automatic resolution) */
+    customTokens?: Record<string, string>;
+}
+/**
+ * Resolve all tokens in a pattern to their values
+ *
+ * Token resolution priority:
+ * 1. Custom tokens (explicitly provided)
+ * 2. Known token resolvers (date, year, month, etc.)
+ * 3. Frontmatter values (for custom tokens)
+ * 4. Empty string (fallback)
+ *
+ * @param pattern - Pattern template with tokens
+ * @param options - Resolution options
+ * @returns Record of token names to resolved values
+ *
+ * @example
+ * ```typescript
+ * const tokens = resolvePatternTokens("{year}/{month}/{slug}.md", {
+ *   slug: "my-post",
+ *   frontmatter: { pubDate: new Date("2024-06-15") }
+ * });
+ * // Returns: { year: "2024", month: "06", slug: "my-post" }
+ * ```
+ */
+declare function resolvePatternTokens(pattern: string, options: ResolveTokensOptions): Record<string, string>;
+/**
+ * Check if a pattern is valid for content creation
+ *
+ * A pattern is valid if:
+ * - It contains the {slug} token (required)
+ * - It ends with .md or .mdx
+ * - All tokens can be resolved
+ *
+ * @param pattern - Pattern template to validate
+ * @returns Validation result with error message if invalid
+ */
+declare function isValidPattern(pattern: string): {
+    valid: boolean;
+    error?: string;
+};
+/**
+ * Get list of all supported token names
+ *
+ * @returns Array of supported token names
+ */
+declare function getSupportedTokens(): string[];
+
+/**
+ * @fileoverview Schema auto-detection for content collections
+ *
+ * This module analyzes frontmatter from sample content files to automatically
+ * infer the schema (field types, required status, enums, etc.).
+ *
+ * ## Detection Process:
+ * 1. Read sample files from the collection (up to 20)
+ * 2. Parse frontmatter from each file
+ * 3. Analyze field patterns across all samples
+ * 4. Infer field types and constraints
+ * 5. Generate schema definition
+ *
+ * ## Detected Types:
+ * - string: Plain text values
+ * - number: Numeric values
+ * - boolean: True/false values
+ * - date: ISO date strings or Date objects
+ * - array: Arrays (with item type detection)
+ * - image: Paths ending with image extensions
+ *
+ * @module @writenex/astro/discovery/schema
+ */
+
+/**
+ * Result of schema detection
+ */
+interface SchemaDetectionResult {
+    /** The detected schema */
+    schema: CollectionSchema;
+    /** Number of files analyzed */
+    samplesAnalyzed: number;
+    /** Confidence score (0-1) based on sample consistency */
+    confidence: number;
+    /** Fields that had inconsistent types across samples */
+    warnings: string[];
+}
+/**
+ * Analyze frontmatter from content items to detect schema
+ *
+ * @param collectionPath - Absolute path to the collection directory
+ * @returns Schema detection result
+ *
+ * @example
+ * ```typescript
+ * const result = await detectSchema('/project/src/content/blog');
+ * console.log(result.schema);
+ * // {
+ * //   title: { type: 'string', required: true },
+ * //   pubDate: { type: 'date', required: true },
+ * //   draft: { type: 'boolean', required: false, default: false },
+ * //   tags: { type: 'array', required: false, items: 'string' },
+ * // }
+ * ```
+ */
+declare function detectSchema(collectionPath: string): Promise<SchemaDetectionResult>;
+/**
+ * Merge detected schema with user-provided schema
+ *
+ * User schema takes precedence over detected schema.
+ *
+ * @param detected - Auto-detected schema
+ * @param userSchema - User-provided schema overrides
+ * @returns Merged schema
+ */
+declare function mergeSchema(detected: CollectionSchema, userSchema?: CollectionSchema): CollectionSchema;
+/**
+ * Convert schema to a human-readable description
+ *
+ * @param schema - The schema to describe
+ * @returns Human-readable description
+ */
+declare function describeSchema(schema: CollectionSchema): string;
+
+export { type PatternDetectionResult, type ResolveTokensOptions, type SchemaDetectionResult, collectionExists, describeSchema, detectFilePattern, detectSchema, discoverCollections, generatePathFromPattern, getCollection, getPatternExtension, getSupportedTokens, isValidPattern, mergeCollections, mergeSchema, parsePatternTokens, resolvePatternTokens, validatePattern };

package/dist/discovery/index.js

@@ -0,0 +1,38 @@
+import {
+  collectionExists,
+  describeSchema,
+  detectSchema,
+  discoverCollections,
+  getCollection,
+  mergeCollections,
+  mergeSchema
+} from "../chunk-CYLDJ3HZ.js";
+import {
+  detectFilePattern,
+  generatePathFromPattern,
+  getPatternExtension,
+  getSupportedTokens,
+  isValidPattern,
+  parsePatternTokens,
+  resolvePatternTokens,
+  validatePattern
+} from "../chunk-AAOQHQPU.js";
+import "../chunk-CRPZUUDU.js";
+export {
+  collectionExists,
+  describeSchema,
+  detectFilePattern,
+  detectSchema,
+  discoverCollections,
+  generatePathFromPattern,
+  getCollection,
+  getPatternExtension,
+  getSupportedTokens,
+  isValidPattern,
+  mergeCollections,
+  mergeSchema,
+  parsePatternTokens,
+  resolvePatternTokens,
+  validatePattern
+};
+//# sourceMappingURL=index.js.map

package/dist/discovery/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/errors-C0iYiDTv.d.ts

@@ -0,0 +1,107 @@
+/**
+ * @fileoverview Custom error classes for @writenex/astro
+ *
+ * This module provides categorized error types for better error handling,
+ * debugging, and user-facing error messages across the integration.
+ *
+ * ## Error Categories:
+ * - Configuration errors (invalid config, missing files)
+ * - Filesystem errors (read/write failures, permissions)
+ * - Content errors (parsing, validation, not found)
+ * - API errors (request handling, validation)
+ * - Version history errors (manifest, storage)
+ *
+ * @module @writenex/astro/core/errors
+ */
+/**
+ * Error codes for categorization and i18n support
+ */
+declare enum WritenexErrorCode {
+    CONFIG_NOT_FOUND = "CONFIG_NOT_FOUND",
+    CONFIG_INVALID = "CONFIG_INVALID",
+    CONFIG_PARSE_ERROR = "CONFIG_PARSE_ERROR",
+    FS_READ_ERROR = "FS_READ_ERROR",
+    FS_WRITE_ERROR = "FS_WRITE_ERROR",
+    FS_DELETE_ERROR = "FS_DELETE_ERROR",
+    FS_PERMISSION_DENIED = "FS_PERMISSION_DENIED",
+    FS_PATH_NOT_FOUND = "FS_PATH_NOT_FOUND",
+    FS_PATH_TRAVERSAL = "FS_PATH_TRAVERSAL",
+    CONTENT_NOT_FOUND = "CONTENT_NOT_FOUND",
+    CONTENT_PARSE_ERROR = "CONTENT_PARSE_ERROR",
+    CONTENT_VALIDATION_ERROR = "CONTENT_VALIDATION_ERROR",
+    CONTENT_ALREADY_EXISTS = "CONTENT_ALREADY_EXISTS",
+    CONTENT_INVALID_SLUG = "CONTENT_INVALID_SLUG",
+    CONTENT_CONFLICT = "CONTENT_CONFLICT",
+    COLLECTION_NOT_FOUND = "COLLECTION_NOT_FOUND",
+    COLLECTION_EMPTY = "COLLECTION_EMPTY",
+    COLLECTION_DISCOVERY_ERROR = "COLLECTION_DISCOVERY_ERROR",
+    API_BAD_REQUEST = "API_BAD_REQUEST",
+    API_METHOD_NOT_ALLOWED = "API_METHOD_NOT_ALLOWED",
+    API_INTERNAL_ERROR = "API_INTERNAL_ERROR",
+    API_TIMEOUT = "API_TIMEOUT",
+    IMAGE_INVALID_TYPE = "IMAGE_INVALID_TYPE",
+    IMAGE_TOO_LARGE = "IMAGE_TOO_LARGE",
+    IMAGE_UPLOAD_ERROR = "IMAGE_UPLOAD_ERROR",
+    IMAGE_NOT_FOUND = "IMAGE_NOT_FOUND",
+    VERSION_NOT_FOUND = "VERSION_NOT_FOUND",
+    VERSION_MANIFEST_CORRUPT = "VERSION_MANIFEST_CORRUPT",
+    VERSION_LOCK_TIMEOUT = "VERSION_LOCK_TIMEOUT",
+    VERSION_SAVE_ERROR = "VERSION_SAVE_ERROR",
+    VERSION_RESTORE_ERROR = "VERSION_RESTORE_ERROR",
+    PATTERN_INVALID = "PATTERN_INVALID",
+    PATTERN_MISSING_TOKEN = "PATTERN_MISSING_TOKEN",
+    UNKNOWN_ERROR = "UNKNOWN_ERROR"
+}
+/**
+ * Base error class for all Writenex errors
+ *
+ * Provides structured error information including error code,
+ * HTTP status, and optional context data for debugging.
+ */
+declare class WritenexError extends Error {
+    /** Error code for categorization */
+    readonly code: WritenexErrorCode;
+    /** HTTP status code for API responses */
+    readonly httpStatus: number;
+    /** Additional context data for debugging */
+    readonly context?: Record<string, unknown>;
+    /** Original error if this wraps another error */
+    readonly cause?: Error;
+    constructor(code: WritenexErrorCode, message: string, options?: {
+        context?: Record<string, unknown>;
+        cause?: Error;
+    });
+    /**
+     * Convert error to JSON for API responses
+     */
+    toJSON(): Record<string, unknown>;
+    /**
+     * Create a user-friendly error message
+     */
+    toUserMessage(): string;
+}
+/**
+ * Error thrown when content was modified externally (conflict detection)
+ *
+ * This error includes both the server version and the client's expected mtime
+ * to help resolve the conflict.
+ */
+declare class ContentConflictError extends WritenexError {
+    /** Current content on disk */
+    readonly serverContent: string;
+    /** Server's current mtime */
+    readonly serverMtime: number;
+    /** Client's expected mtime */
+    readonly clientMtime: number;
+    constructor(collection: string, contentId: string, serverContent: string, serverMtime: number, clientMtime: number);
+    /**
+     * Override toJSON to include conflict-specific data
+     */
+    toJSON(): Record<string, unknown>;
+}
+/**
+ * Check if an error is a WritenexError
+ */
+declare function isWritenexError(error: unknown): error is WritenexError;
+
+export { ContentConflictError as C, WritenexError as W, WritenexErrorCode as a, isWritenexError as i };