llm-docs-sync 1.0.0 → 1.0.4

package/README.md

@@ -1,4 +1,4 @@
-# @edutherapy/llm-docs-sync
+# llm-docs-sync
 
 A functional, Effect-based documentation sync tool for maintaining up-to-date LLM context in your SvelteKit projects.
 
@@ -9,12 +9,15 @@ A functional, Effect-based documentation sync tool for maintaining up-to-date LL
 - 🔄 **Auto-Sync**: Keeps your LLM documentation context fresh
 - ⚙️ **Configurable**: Customize sources, output directory, and project rules
 - 🎯 **SvelteKit Ready**: Pre-configured for SvelteKit + Effect projects
+- 📝 **Auto-Generated AGENTS.md**: Creates comprehensive agent configuration files
 
 ## Installation
 
-\`\`\`bash
+```bash
+
 bun add -d llm-docs-sync
-\`\`\`
+
+```
 
 ## Usage
 
@@ -22,69 +25,78 @@ bun add -d llm-docs-sync
 
 Add to your package.json scripts:
 
-\`\`\`json
+```json
+
 {
   "scripts": {
     "sync-docs": "llm-docs-sync"
   }
 }
-\`\`\`
+
+```
 
 Run:
-\`\`\`bash
+
+```bash
+
 bun run sync-docs
-\`\`\`
 
-This package is published under:
-- **Brand**: EduTherapy (a brand of Talim Shifa Studio)
-- **GitLab Repository**: https://gitlab.com/EduTherapy/llm-docs-sync
-- **NPM Publisher**: edutherapy (https://www.npmjs.com/~edutherapy)
-- **Company Website**: https://eduth.pro/
-- **Contact**: edutherapystudio@gmail.com
+```
 
 ### Programmatic API
 
-\`\`\`typescript
-import { syncDocs, DEFAULT_SOURCES, type DocSource } from 'llm-docs-sync';
+```typescript
+import { syncDocs, type DocSource } from 'llm-docs-sync';
+import { Effect } from 'effect';
+import { DEFAULT_SOURCES, DEFAULT_PROJECT_RULES } from 'llm-docs-sync/defaults';
 
 // Use defaults
-await syncDocs();
+Effect.runPromise(syncDocs());
 
 // Custom configuration
-await syncDocs({
-  sources: [
-    ...DEFAULT_SOURCES,
-    { name: "Custom Lib", url: "https://example.com/llms.txt" }
-  ],
-  outputDir: "./docs/context",
-  agentsFile: "AI_CONTEXT.md",
-  projectRules: [
-    "Use TypeScript strict mode",
-    "Follow Effect best practices"
-  ]
-});
-\`\`\`
+Effect.runPromise(
+  syncDocs({
+    sources: [
+      ...DEFAULT_SOURCES,
+      { name: "Custom Lib", url: "https://example.com/llms.txt" }
+    ],
+    outputDir: "./docs/context",
+    agentsFile: "AI_CONTEXT.md",
+    projectRules: [
+      "Use TypeScript strict mode",
+      "Follow Effect best practices"
+    ]
+  })
+);
+```
 
 ### Default Sources
 
-- Svelte 5
-- SvelteKit
-- Effect
-- Tailwind v4
-- Lucide
-- Vite
-- Biome
+- Svelte 5: `https://svelte.dev/docs/svelte/llms.txt`
+- SvelteKit: `https://svelte.dev/docs/kit/llms.txt`
+- Effect: `https://effect.website/llms-full.txt`
+- Vite: `https://vite.dev/llms.txt`
+- Skeleton: `https://www.skeleton.dev/llms-svelte.txt`
+- Dexie: `https://dexie.org/llms.txt`
+
+### Default Project Rules
+
+1. **Always use Bun** for adding packages, running scripts, and testing.
+2. **Svelte 5 Runes:** Use `$state`, `$derived`, and `$effect` as defined in local Svelte context.
+3. **Effect TS:** Follow the patterns defined in the Effect full documentation file.
 
 ## Configuration
 
-\`\`\`typescript
+```typescript
+
 type SyncConfig = {
-  sources?: DocSource[];           // Documentation sources to sync
+  sources?: DocSource[];           // Documentation sources to sync (default: DEFAULT_SOURCES)
   outputDir?: string;              // Output directory (default: ./.opencode/context)
   agentsFile?: string;             // AGENTS.md file path (default: AGENTS.md)
-  projectRules?: string[];         // Custom project rules
+  projectRules?: string[];         // Custom project rules (default: DEFAULT_PROJECT_RULES)
 };
-\`\`\`
+
+```
 
 ## Example Workflow
 
@@ -93,14 +105,117 @@ type SyncConfig = {
 3. Run before starting development or in CI/CD
 4. Your AGENTS.md and context files stay updated
 
-\`\`\`json
+```json
+
 {
   "scripts": {
     "predev": "bun run sync-docs",
     "dev": "vite dev"
   }
 }
-\`\`\`
+
+```
+
+## Generated AGENTS.md Format
+
+The tool generates an `AGENTS.md` file with the following structure. If the file already exists, the new content is appended with a separator (`\n\n---\n\n`):
+
+```markdown
+# OpenCode Agent Configuration
+**Primary Runtime:** Bun (System-wide)
+**Context Strategy:** Local Documentation First
+
+## 📚 Local Documentation References
+The following files contain the latest API specifications and standards.
+Always consult these before attempting to write code for these libraries:
+
+- **Svelte 5**: Refer to "./.opencode/context/svelte-5.md"
+- **SvelteKit**: Refer to "./.opencode/context/sveltekit.md"
+- **Effect**: Refer to "./.opencode/context/effect.md"
+- **Vite**: Refer to "./.opencode/context/vite.md"
+- **Skeleton**: Refer to "./.opencode/context/skeleton.md"
+- **Dexie**: Refer to "./.opencode/context/dexie.md"
+
+## 🛠 Project Rules
+1. **Always use Bun** for adding packages, running scripts, and testing.
+2. **Svelte 5 Runes:** Use `$state`, `$derived`, and `$effect` as defined in local Svelte context.
+3. **Effect TS:** Follow the patterns defined in the Effect full documentation file.
+```
+
+## API Reference
+
+### Functions
+
+#### `syncDocs(config?: Partial<SyncConfig>): Effect.Effect<void, never>`
+
+Main sync function that fetches documentation from all sources and generates AGENTS.md.
+
+#### `runCLI(): void`
+
+Runs the sync process from command line.
+
+#### `toFileName(name: string): string`
+
+Converts a source name to a filename (lowercase, spaces to hyphens).
+
+#### `createManifest(results: readonly SyncResult[]): readonly string[]`
+
+Creates manifest entries for successful sync results.
+
+### Types
+
+#### `DocSource`
+
+```typescript
+
+interface DocSource {
+  readonly name: string;
+  readonly url: string;
+}
+
+```
+
+#### `SyncResult`
+
+```typescript
+
+interface SyncResult {
+  readonly name: string;
+  readonly filePath: string;
+  readonly status: "success" | "failed";
+}
+
+```
+
+#### `SyncConfig`
+
+```typescript
+
+interface SyncConfig {
+  readonly sources: readonly DocSource[];
+  readonly outputDir: string;
+  readonly agentsFile?: string;
+  readonly projectRules?: readonly string[];
+}
+
+```
+
+## Testing
+
+```bash
+
+bun test
+
+```
+
+## Publishing
+
+This package is published under:
+- **Brand**: EduTherapy (a brand of Talim Shifa Studio)
+- **NPM Package**: [llm-docs-sync](https://www.npmjs.com/package/llm-docs-sync)
+- **NPM Publisher**: [edutherapy](https://www.npmjs.com/~edutherapy)
+- **Company Website**: https://eduth.pro/
+- **Contact**: edutherapystudio@gmail.com
 
 ## License