@fractary/codex 0.12.2 → 0.12.5

package/README.md

@@ -14,93 +14,38 @@ npm install @fractary/codex
 ## Features
 
 - **Universal References**: `codex://` URI scheme for cross-project knowledge references
-- **Multi-Provider Storage**: Local filesystem, GitHub, and HTTP storage backends
-- **Intelligent Caching**: Multi-tier caching (L1 memory, L2 disk, L3 network) with LRU eviction
+- **Multi-Provider Storage**: Local filesystem, GitHub, HTTP, and S3 storage backends
+- **Intelligent Caching**: Multi-tier caching with LRU eviction
 - **File Synchronization**: Bidirectional sync with conflict detection
-- **MCP Integration**: Model Context Protocol server for AI agent integration
-- **Permission System**: Fine-grained access control (none/read/write/admin)
-- **Migration Tools**: Upgrade from v2.x to v3.0 configuration format
-- **Type-Safe**: Full TypeScript support with strict typing
+- **MCP Integration**: Model Context Protocol server for AI agents
+- **Permission System**: Fine-grained access control
+- **Type-Safe**: Full TypeScript support
 
 ## Quick Start
 
 ```typescript
-import {
-  parseReference,
-  resolveReference,
-  CacheManager,
-  StorageManager,
-  createMcpServer
-} from '@fractary/codex'
+import { parseReference, CacheManager, StorageManager } from '@fractary/codex'
 
 // Parse a codex URI
 const ref = parseReference('codex://myorg/docs/api-guide.md')
-console.log(ref.org)      // 'myorg'
-console.log(ref.path)     // 'docs/api-guide.md'
 
-// Create storage and cache managers
+// Create managers
 const storage = StorageManager.create()
 const cache = CacheManager.create({ cacheDir: '.fractary/codex/cache' })
+cache.setStorageManager(storage)
 
 // Fetch content with caching
 const content = await cache.get('codex://myorg/docs/api-guide.md')
 ```
 
-## Core Modules
-
-### References
-
-```typescript
-import { parseReference, buildUri, validateUri } from '@fractary/codex'
-
-const ref = parseReference('codex://fractary/codex/docs/api.md')
-const uri = buildUri('fractary', 'codex', 'docs/api.md')
-const isValid = validateUri('codex://org/project/path.md')
-```
-
-### Storage
-
-```typescript
-import { StorageManager } from '@fractary/codex'
-
-const storage = StorageManager.create({
-  providers: [
-    { type: 'local', basePath: './knowledge' },
-    { type: 'github', token: process.env.GITHUB_TOKEN },
-    { type: 'http', baseUrl: 'https://codex.example.com' }
-  ]
-})
-
-const result = await storage.fetch('codex://org/project/file.md')
-```
-
-### Cache
-
-```typescript
-import { createCacheManager } from '@fractary/codex'
-
-const cache = createCacheManager({
-  cacheDir: '.fractary/codex/cache',
-  maxMemorySize: 50 * 1024 * 1024,
-  defaultTtl: 3600
-})
-
-const entry = await cache.get('codex://org/project/file.md')
-```
-
-### MCP Server
-
-```typescript
-import { createMcpServer } from '@fractary/codex'
+## Documentation
 
-const server = createMcpServer({
-  name: 'codex',
-  version: '1.0.0',
-  cacheDir: '.fractary/codex/cache'
-})
+**Full documentation**: [docs/sdk/js/](../../docs/sdk/js/)
 
-await server.start()
-```
+- [API Reference](../../docs/sdk/js/#api-reference)
+- [Authentication](../../docs/sdk/js/#authentication)
+- [Troubleshooting](../../docs/sdk/js/#troubleshooting)
+- [Configuration Guide](../../docs/configuration.md)
 
 ## Development
 
@@ -114,125 +59,35 @@ npm run build
 # Run tests
 npm test
 
-# Run tests in watch mode
-npm run test:watch
-
 # Type check
 npm run typecheck
 
 # Lint
 npm run lint
-
-# Format code
-npm run format
 ```
 
-## Publishing to npm
-
-### Prerequisites
-
-1. **npm Account**: Create an account on [npmjs.com](https://www.npmjs.com)
-2. **npm Login**: Run `npm login` to authenticate
-3. **Organization Access**: Ensure you have publish access to `@fractary` scope
-
-### Manual Publishing
+## Publishing
 
 ```bash
 # Build and test
-npm run build
-npm test
-
-# Check what will be published
-npm pack --dry-run
-
-# Publish to npm (the prepublishOnly script runs build & test automatically)
-npm publish
-
-# For first publish or after scope changes
-npm publish --access public
-```
-
-### Automated Publishing (CI/CD)
-
-For automated publishing via GitHub Actions:
-
-1. **npm Token**: Generate an Automation token on npmjs.com
-2. **GitHub Secret**: Add `NPM_TOKEN` to repository secrets
-3. **Workflow**: Create `.github/workflows/npm-publish.yml`:
-
-```yaml
-name: Publish to npm
-on:
-  release:
-    types: [published]
-
-jobs:
-  publish:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
-        with:
-          node-version: '20'
-          registry-url: 'https://registry.npmjs.org'
-      - run: npm ci
-      - run: npm run build
-      - run: npm test
-      - run: npm publish --access public
-        env:
-          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
-```
-
-### Version Management
+npm run build && npm test
 
-```bash
-# Bump patch version (0.1.2 -> 0.1.3)
-npm version patch
-
-# Bump minor version (0.1.2 -> 0.2.0)
-npm version minor
-
-# Bump major version (0.1.2 -> 1.0.0)
-npm version major
-
-# This automatically:
-# - Updates package.json version
-# - Creates a git commit
-# - Creates a git tag
-```
-
-To publish a new version:
-
-```bash
-# 1. Ensure all changes are committed
-# 2. Bump version
+# Bump version
 npm version patch  # or minor/major
 
-# 3. Push with tags
+# Push with tags
 git push && git push --tags
 
-# 4. Publish to npm
+# Publish
 npm publish
 ```
 
-Follow [Semantic Versioning](https://semver.org/):
-- **MAJOR**: Breaking API changes
-- **MINOR**: New features, backward compatible
-- **PATCH**: Bug fixes, backward compatible
-
 ## License
 
 MIT - see [LICENSE](LICENSE)
 
-## Documentation
-
-- [CLI Integration Guide](../../docs/guides/cli-integration.md) - How to integrate into CLI applications
-- [API Reference](../../docs/guides/api-reference.md) - Complete API documentation
-- [Configuration Guide](../../docs/guides/configuration.md) - Configuration reference
-- [Troubleshooting](../../docs/guides/troubleshooting.md) - Common issues and solutions
-- [Examples](../../docs/examples/) - Real-world usage patterns
-
 ## See Also
 
-- [Python SDK](../python/) - `fractary-codex` on PyPI
-- [Technical Specifications](../../docs/specs/) - Detailed specs
+- [Python SDK](../py/) - `fractary-codex` on PyPI
+- [CLI](../../cli/) - Command-line interface
+- [MCP Server](../../mcp/server/) - AI agent integration

package/dist/index.cjs

@@ -923,12 +923,24 @@ var DirectionalSyncConfigSchema = zod.z.object({
   /** Patterns to exclude (optional) */
   exclude: zod.z.array(zod.z.string()).optional()
 });
+var FromCodexSyncConfigSchema = DirectionalSyncConfigSchema.refine(
+  (config) => {
+    const includeValid = config.include.every(
+      (pattern) => pattern.startsWith("codex://")
+    );
+    const excludeValid = !config.exclude || config.exclude.every((pattern) => pattern.startsWith("codex://"));
+    return includeValid && excludeValid;
+  },
+  {
+    message: 'from_codex patterns must use codex:// URI format (e.g., "codex://{org}/{codex_repo}/docs/**"). Plain paths like "docs/**" are not valid for from_codex.'
+  }
+);
 var DirectionalSyncSchema = zod.z.object({
   // New format (v0.7.0+) - Recommended
-  // Patterns for files to push from this project to codex
+  // Patterns for files to push from this project to codex (plain paths)
   to_codex: DirectionalSyncConfigSchema.optional(),
-  // Patterns for files to pull from codex to this project
-  from_codex: DirectionalSyncConfigSchema.optional(),
+  // Patterns for files to pull from codex to this project (codex:// URIs required)
+  from_codex: FromCodexSyncConfigSchema.optional(),
   // Global exclude patterns (applied to both directions)
   exclude: zod.z.array(zod.z.string()).optional(),
   // Legacy format (deprecated, backward compatible)
@@ -956,25 +968,9 @@ var AuthConfigSchema = zod.z.object({
   /** GitHub authentication configuration */
   github: GitHubAuthConfigSchema.optional()
 });
-var SourceConfigSchema = zod.z.object({
-  /** Source type */
-  type: zod.z.enum(["github", "s3", "http", "local"]),
-  /** Environment variable containing the authentication token */
-  token_env: zod.z.string().optional(),
-  /** Direct token value (not recommended, use token_env instead) */
-  token: zod.z.string().optional(),
-  /** Branch to fetch from (for GitHub sources) */
-  branch: zod.z.string().optional(),
-  /** Base URL (for HTTP sources) */
-  base_url: zod.z.string().optional(),
-  /** Bucket name (for S3 sources) */
-  bucket: zod.z.string().optional(),
-  /** Prefix/path within bucket (for S3 sources) */
-  prefix: zod.z.string().optional()
-});
-var DependencyConfigSchema = zod.z.object({
-  /** Sources within this dependency */
-  sources: zod.z.record(SourceConfigSchema)
+var RemoteConfigSchema = zod.z.object({
+  /** Authentication token - can be direct value or ${ENV_VAR} reference */
+  token: zod.z.string().optional()
 });
 var CodexConfigSchema = zod.z.object({
   organizationSlug: zod.z.string(),
@@ -992,8 +988,9 @@ var CodexConfigSchema = zod.z.object({
   archive: ArchiveConfigSchema.optional(),
   // Authentication configuration
   auth: AuthConfigSchema.optional(),
-  // Dependencies configuration (external projects)
-  dependencies: zod.z.record(DependencyConfigSchema).optional()
+  // Remote repositories configuration (external projects)
+  // Keys are org/project identifiers, values configure authentication
+  remotes: zod.z.record(RemoteConfigSchema).optional()
 }).strict();
 var FileSourceSchema = zod.z.object({
   type: zod.z.enum(["s3", "r2", "gcs", "local"]),
@@ -1238,6 +1235,99 @@ function mergeConfigs(base, override) {
   };
 }
 
+// src/core/config/sync-presets.ts
+var CONFIG_SCHEMA_VERSION = "2.0";
+var SYNC_PATTERN_PRESETS = {
+  standard: {
+    name: "standard",
+    description: "Standard configuration with docs, README, and CLAUDE.md",
+    config: {
+      to_codex: {
+        include: ["docs/**", "README.md", "CLAUDE.md"],
+        exclude: ["*.tmp"]
+      },
+      from_codex: {
+        include: ["codex://{org}/{codex_repo}/docs/**"]
+      }
+    }
+  },
+  minimal: {
+    name: "minimal",
+    description: "Minimal configuration with just docs and README",
+    config: {
+      to_codex: {
+        include: ["docs/**", "README.md"]
+      },
+      from_codex: {
+        include: ["codex://{org}/{codex_repo}/docs/**"]
+      }
+    }
+  }
+};
+var DEFAULT_GLOBAL_EXCLUDES = [
+  "**/.git/**",
+  "**/node_modules/**",
+  "**/.env",
+  "**/.env.*",
+  "**/*.log",
+  "**/dist/**",
+  "**/build/**",
+  "**/.DS_Store",
+  "**/credentials.json",
+  "**/*secret*",
+  "**/*password*"
+];
+function getSyncPreset(name) {
+  return SYNC_PATTERN_PRESETS[name];
+}
+function getSyncPresetNames() {
+  return Object.keys(SYNC_PATTERN_PRESETS);
+}
+function substitutePatternPlaceholders(patterns, org, codexRepo) {
+  if (!org || typeof org !== "string" || org.trim() === "") {
+    throw new ValidationError("org must be a non-empty string");
+  }
+  if (!codexRepo || typeof codexRepo !== "string" || codexRepo.trim() === "") {
+    throw new ValidationError("codexRepo must be a non-empty string");
+  }
+  return patterns.map(
+    (pattern) => pattern.replace(/\{org\}/g, org).replace(/\{codex_repo\}/g, codexRepo)
+  );
+}
+function generateSyncConfigFromPreset(presetName, org, codexRepo, options) {
+  const preset = getSyncPreset(presetName);
+  if (!preset) {
+    return void 0;
+  }
+  let toCodexExclude;
+  if (options?.includeGlobalExcludes) {
+    toCodexExclude = [
+      ...preset.config.to_codex.exclude || [],
+      ...DEFAULT_GLOBAL_EXCLUDES
+    ];
+  } else if (preset.config.to_codex.exclude) {
+    toCodexExclude = [...preset.config.to_codex.exclude];
+  }
+  return {
+    to_codex: {
+      include: [...preset.config.to_codex.include],
+      exclude: toCodexExclude
+    },
+    from_codex: {
+      include: substitutePatternPlaceholders(
+        preset.config.from_codex.include,
+        org,
+        codexRepo
+      ),
+      exclude: preset.config.from_codex.exclude ? substitutePatternPlaceholders(
+        preset.config.from_codex.exclude,
+        org,
+        codexRepo
+      ) : void 0
+    }
+  };
+}
+
 // src/core/routing/evaluator.ts
 init_matcher();
 function shouldSyncToRepo(options) {
@@ -2382,30 +2472,31 @@ var StorageManager = class {
     }
     this.priority = config.priority || (config.filePlugin && config.s3Archive ? ["file-plugin", "local", "s3-archive", "github", "http"] : config.filePlugin ? ["file-plugin", "local", "github", "http"] : config.s3Archive ? ["local", "s3-archive", "github", "http"] : ["local", "github", "http"]);
   }
+  /**
+   * Resolve a token value, expanding ${VAR} references to environment variables
+   */
+  resolveTokenValue(token) {
+    const envVarMatch = token.match(/^\$\{([^}]+)\}$/);
+    if (envVarMatch && envVarMatch[1]) {
+      const envVarName = envVarMatch[1];
+      return process.env[envVarName];
+    }
+    return token;
+  }
   /**
    * Resolve authentication token for a reference
    *
-   * Looks up dependency-specific authentication or falls back to default
+   * Looks up remote-specific authentication or falls back to default
    */
   resolveToken(reference) {
     if (!this.codexConfig) {
       return void 0;
     }
-    const dependencyKey = `${reference.org}/${reference.project}`;
-    if (this.codexConfig.dependencies?.[dependencyKey]) {
-      const dependency = this.codexConfig.dependencies[dependencyKey];
-      for (const [, sourceConfig] of Object.entries(dependency.sources)) {
-        if (sourceConfig.type === "github") {
-          if (sourceConfig.token_env) {
-            const token = process.env[sourceConfig.token_env];
-            if (token) {
-              return token;
-            }
-          }
-          if (sourceConfig.token) {
-            return sourceConfig.token;
-          }
-        }
+    const remoteKey = `${reference.org}/${reference.project}`;
+    if (this.codexConfig.remotes?.[remoteKey]?.token) {
+      const token = this.resolveTokenValue(this.codexConfig.remotes[remoteKey].token);
+      if (token) {
+        return token;
       }
     }
     const defaultTokenEnv = this.codexConfig.auth?.github?.default_token_env || "GITHUB_TOKEN";
@@ -2464,7 +2555,7 @@ var StorageManager = class {
    * Fetch content for a reference
    *
    * Tries providers in priority order until one succeeds.
-   * Automatically resolves authentication based on dependency configuration.
+   * Automatically resolves authentication based on remote configuration.
    */
   async fetch(reference, options) {
     const resolvedOptions = this.resolveFetchOptions(reference, options);
@@ -2496,7 +2587,7 @@ var StorageManager = class {
    * Check if content exists for a reference
    *
    * Returns true if any provider reports the content exists.
-   * Automatically resolves authentication based on dependency configuration.
+   * Automatically resolves authentication based on remote configuration.
    */
   async exists(reference, options) {
     const resolvedOptions = this.resolveFetchOptions(reference, options);
@@ -5142,6 +5233,7 @@ function isValidSize(value) {
 exports.AutoSyncPatternSchema = AutoSyncPatternSchema;
 exports.BUILT_IN_TYPES = BUILT_IN_TYPES;
 exports.CODEX_URI_PREFIX = CODEX_URI_PREFIX;
+exports.CONFIG_SCHEMA_VERSION = CONFIG_SCHEMA_VERSION;
 exports.CacheManager = CacheManager;
 exports.CachePersistence = CachePersistence;
 exports.CodexConfigSchema = CodexConfigSchema;
@@ -5151,6 +5243,7 @@ exports.ConfigurationError = ConfigurationError;
 exports.CustomTypeSchema = CustomTypeSchema;
 exports.DEFAULT_CACHE_DIR = DEFAULT_CACHE_DIR;
 exports.DEFAULT_FETCH_OPTIONS = DEFAULT_FETCH_OPTIONS;
+exports.DEFAULT_GLOBAL_EXCLUDES = DEFAULT_GLOBAL_EXCLUDES;
 exports.DEFAULT_MIGRATION_OPTIONS = DEFAULT_MIGRATION_OPTIONS;
 exports.DEFAULT_PERMISSION_CONFIG = DEFAULT_PERMISSION_CONFIG;
 exports.DEFAULT_SYNC_CONFIG = DEFAULT_SYNC_CONFIG;
@@ -5166,6 +5259,7 @@ exports.MetadataSchema = MetadataSchema;
 exports.PERMISSION_LEVEL_ORDER = PERMISSION_LEVEL_ORDER;
 exports.PermissionDeniedError = PermissionDeniedError;
 exports.PermissionManager = PermissionManager;
+exports.SYNC_PATTERN_PRESETS = SYNC_PATTERN_PRESETS;
 exports.StorageManager = StorageManager;
 exports.SyncManager = SyncManager;
 exports.SyncRulesSchema = SyncRulesSchema;
@@ -5221,6 +5315,7 @@ exports.formatPlanSummary = formatPlanSummary;
 exports.formatSeconds = formatSeconds;
 exports.generateMigrationReport = generateMigrationReport;
 exports.generateReferenceMigrationSummary = generateReferenceMigrationSummary;
+exports.generateSyncConfigFromPreset = generateSyncConfigFromPreset;
 exports.getBuiltInType = getBuiltInType;
 exports.getBuiltInTypeNames = getBuiltInTypeNames;
 exports.getCacheEntryAge = getCacheEntryAge;
@@ -5240,6 +5335,8 @@ exports.getMigrationRequirements = getMigrationRequirements;
 exports.getPlanStats = getPlanStats;
 exports.getRelativeCachePath = getRelativeCachePath;
 exports.getRemainingTtl = getRemainingTtl;
+exports.getSyncPreset = getSyncPreset;
+exports.getSyncPresetNames = getSyncPresetNames;
 exports.getTargetRepos = getTargetRepos;
 exports.hasContentChanged = hasContentChanged;
 exports.hasEnvVars = hasEnvVars;
@@ -5291,6 +5388,7 @@ exports.setDefaultCacheManager = setDefaultCacheManager;
 exports.setDefaultPermissionManager = setDefaultPermissionManager;
 exports.setDefaultStorageManager = setDefaultStorageManager;
 exports.shouldSyncToRepo = shouldSyncToRepo;
+exports.substitutePatternPlaceholders = substitutePatternPlaceholders;
 exports.summarizeEvaluations = summarizeEvaluations;
 exports.touchCacheEntry = touchCacheEntry;
 exports.validateCustomTypes = validateCustomTypes;