@fractary/codex 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Fractary Engineering
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,280 @@
+# @fractary/codex
+
+Core SDK for Fractary Codex - a centralized knowledge management and distribution platform for organizations.
+
+[![npm version](https://img.shields.io/npm/v/@fractary/codex.svg)](https://www.npmjs.com/package/@fractary/codex)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## Overview
+
+The Codex SDK provides the foundational business logic for the Fractary Codex system, which enables organizations to maintain a single source of truth for documentation, AI tools, and organizational knowledge across all projects.
+
+### Key Features
+
+- **Metadata Parsing**: Extract and validate YAML frontmatter from markdown files
+- **Pattern Matching**: Glob-based pattern matching for intelligent file routing
+- **Smart Routing**: Determine which files should sync to which repositories
+- **Configuration Management**: Multi-source configuration with sensible defaults
+- **Organization-Agnostic**: Works for any organization, not just Fractary
+- **Type-Safe**: Full TypeScript support with strict typing
+- **Well-Tested**: Comprehensive unit test coverage
+
+## Installation
+
+```bash
+npm install @fractary/codex
+```
+
+## Quick Start
+
+```typescript
+import {
+  parseMetadata,
+  shouldSyncToRepo,
+  loadConfig
+} from '@fractary/codex'
+
+// 1. Load configuration
+const config = loadConfig({
+  organizationSlug: 'fractary'
+})
+
+// 2. Parse frontmatter from a markdown file
+const fileContent = await readFile('docs/api-guide.md', 'utf-8')
+const { metadata, content } = parseMetadata(fileContent)
+
+// 3. Determine if file should sync to a target repository
+const shouldSync = shouldSyncToRepo({
+  filePath: 'docs/api-guide.md',
+  fileMetadata: metadata,
+  targetRepo: 'api-gateway',
+  sourceRepo: 'codex.fractary.com',
+  rules: config.rules
+})
+
+console.log(`Sync to api-gateway: ${shouldSync}`)
+```
+
+## Core Concepts
+
+### Metadata Parsing
+
+The SDK parses YAML frontmatter from markdown files to extract sync rules and metadata:
+
+```yaml
+---
+org: fractary
+system: api-gateway
+codex_sync_include: ['api-*', 'core-*']
+codex_sync_exclude: ['*-test', '*-dev']
+visibility: internal
+tags: [api, rest]
+---
+
+# API Documentation
+```
+
+```typescript
+import { parseMetadata } from '@fractary/codex'
+
+const result = parseMetadata(markdown)
+console.log(result.metadata.codex_sync_include) // ['api-*', 'core-*']
+```
+
+### Pattern Matching
+
+Glob patterns determine which repositories receive which files:
+
+```typescript
+import { matchPattern, matchAnyPattern } from '@fractary/codex'
+
+// Single pattern
+matchPattern('api-*', 'api-gateway')  // true
+matchPattern('api-*', 'web-app')      // false
+
+// Multiple patterns
+matchAnyPattern(['api-*', 'core-*'], 'api-gateway')  // true
+matchAnyPattern(['api-*', 'core-*'], 'web-app')      // false
+
+// Special: match all
+matchAnyPattern(['*'], 'anything')  // true
+```
+
+### Sync Routing
+
+Determine which repositories should receive a file based on frontmatter rules:
+
+```typescript
+import { shouldSyncToRepo } from '@fractary/codex'
+
+const shouldSync = shouldSyncToRepo({
+  filePath: 'docs/api-guide.md',
+  fileMetadata: {
+    codex_sync_include: ['api-*', 'core-*'],
+    codex_sync_exclude: ['*-test']
+  },
+  targetRepo: 'api-gateway',
+  sourceRepo: 'codex.fractary.com'
+})
+
+// Returns: true (matches 'api-*' and not excluded)
+```
+
+### Configuration
+
+The SDK supports multi-source configuration:
+
+```typescript
+import { loadConfig, resolveOrganization } from '@fractary/codex'
+
+// Auto-detect organization from repo name
+const org = resolveOrganization({
+  repoName: 'codex.fractary.com'
+})  // Returns: 'fractary'
+
+// Load configuration
+const config = loadConfig({
+  organizationSlug: 'fractary'
+})
+
+console.log(config)
+/*
+{
+  organizationSlug: 'fractary',
+  directories: {
+    source: '.fractary',
+    target: '.fractary',
+    systems: '.fractary/systems'
+  },
+  rules: {
+    preventSelfSync: true,
+    preventCodexSync: true,
+    allowProjectOverrides: true,
+    autoSyncPatterns: []
+  }
+}
+*/
+```
+
+## API Reference
+
+### Metadata Parsing
+
+- `parseMetadata(content, options?)` - Parse YAML frontmatter from markdown
+- `hasFrontmatter(content)` - Check if content has frontmatter
+- `validateMetadata(metadata)` - Validate metadata against schema
+- `extractRawFrontmatter(content)` - Extract raw frontmatter string
+
+### Pattern Matching
+
+- `matchPattern(pattern, value)` - Match a single glob pattern
+- `matchAnyPattern(patterns, value)` - Match against multiple patterns
+- `filterByPatterns(patterns, values)` - Filter array by patterns
+- `evaluatePatterns({ value, include, exclude })` - Evaluate include/exclude rules
+
+### Configuration
+
+- `loadConfig(options)` - Load configuration from all sources
+- `resolveOrganization(options)` - Resolve organization slug
+- `extractOrgFromRepoName(repoName)` - Extract org from repo name pattern
+- `getDefaultConfig(orgSlug)` - Get default configuration
+
+### Routing
+
+- `shouldSyncToRepo(options)` - Determine if file should sync to repo
+- `getTargetRepos(options)` - Get all repos that should receive a file
+
+## Configuration
+
+### Environment Variables
+
+- `ORGANIZATION_SLUG` - Organization identifier
+- `CODEX_ORG_SLUG` - Alternative organization identifier
+- `CODEX_SOURCE_DIR` - Source directory (default: `.{org}`)
+- `CODEX_TARGET_DIR` - Target directory (default: `.{org}`)
+- `CODEX_PREVENT_SELF_SYNC` - Prevent self-sync (default: `true`)
+- `CODEX_ALLOW_PROJECT_OVERRIDES` - Allow project overrides (default: `true`)
+
+### Auto-Sync Patterns
+
+Configure patterns that automatically sync to repositories:
+
+```typescript
+const config = loadConfig({
+  organizationSlug: 'fractary'
+})
+
+config.rules.autoSyncPatterns = [
+  {
+    pattern: '*/docs/schema/*.json',
+    include: ['*'],  // All repos
+    exclude: []
+  },
+  {
+    pattern: '*/security/**/*.md',
+    include: ['*'],
+    exclude: ['*-public']
+  }
+]
+```
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Build
+npm run build
+
+# Test
+npm test
+
+# Test with coverage
+npm run test:coverage
+
+# Type check
+npm run typecheck
+```
+
+## Project Structure
+
+```
+src/
+├── core/
+│   ├── metadata/       # Frontmatter parsing
+│   ├── patterns/       # Pattern matching
+│   ├── routing/        # Sync routing logic
+│   └── config/         # Configuration system
+├── schemas/            # Zod schemas
+├── errors/             # Error classes
+└── index.ts            # Main exports
+
+tests/
+├── unit/               # Unit tests
+└── fixtures/           # Test fixtures
+```
+
+## Specifications
+
+Detailed specifications are available in `/docs/specs/`:
+
+- [SPEC-00001: Core SDK Overview](./docs/specs/SPEC-00001-core-sdk-overview.md)
+- [SPEC-00002: Metadata Parsing](./docs/specs/SPEC-00002-metadata-parsing.md)
+- [SPEC-00003: Pattern Matching](./docs/specs/SPEC-00003-pattern-matching.md)
+- [SPEC-00004: Routing & Distribution](./docs/specs/SPEC-00004-routing-distribution.md)
+- [SPEC-00005: Configuration System](./docs/specs/SPEC-00005-configuration-system.md)
+
+## Related Projects
+
+- **fractary-cli** - Unified CLI for all Fractary tools (coming soon)
+- **forge-bundle-codex-github-core** - GitHub Actions workflows for codex sync
+- **forge-bundle-codex-claude-agents** - Claude Code agents for codex management
+
+## License
+
+MIT © Fractary Engineering
+
+## Contributing
+
+This is part of the Fractary ecosystem. For issues or contributions, please refer to the [main repository](https://github.com/fractary/codex).

package/dist/index.cjs

@@ -0,0 +1,416 @@
+'use strict';
+
+var zod = require('zod');
+var yaml = require('js-yaml');
+var micromatch = require('micromatch');
+
+function _interopDefault (e) { return e && e.__esModule ? e : { default: e }; }
+
+var yaml__default = /*#__PURE__*/_interopDefault(yaml);
+
+// src/errors/CodexError.ts
+var CodexError = class _CodexError extends Error {
+  constructor(message, options) {
+    super(message, options);
+    this.name = "CodexError";
+    Object.setPrototypeOf(this, _CodexError.prototype);
+  }
+};
+
+// src/errors/ConfigurationError.ts
+var ConfigurationError = class _ConfigurationError extends CodexError {
+  constructor(message, options) {
+    super(message, options);
+    this.name = "ConfigurationError";
+    Object.setPrototypeOf(this, _ConfigurationError.prototype);
+  }
+};
+
+// src/errors/ValidationError.ts
+var ValidationError = class _ValidationError extends CodexError {
+  constructor(message, options) {
+    super(message, options);
+    this.name = "ValidationError";
+    Object.setPrototypeOf(this, _ValidationError.prototype);
+  }
+};
+var MetadataSchema = zod.z.object({
+  // Organizational
+  org: zod.z.string().optional(),
+  system: zod.z.string().optional(),
+  // Sync rules
+  codex_sync_include: zod.z.array(zod.z.string()).optional(),
+  codex_sync_exclude: zod.z.array(zod.z.string()).optional(),
+  // Metadata
+  title: zod.z.string().optional(),
+  description: zod.z.string().optional(),
+  visibility: zod.z.enum(["public", "internal", "private"]).optional(),
+  audience: zod.z.array(zod.z.string()).optional(),
+  tags: zod.z.array(zod.z.string()).optional(),
+  // Timestamps
+  created: zod.z.string().optional(),
+  // ISO 8601 date string
+  updated: zod.z.string().optional()
+}).passthrough();
+var AutoSyncPatternSchema = zod.z.object({
+  pattern: zod.z.string(),
+  include: zod.z.array(zod.z.string()),
+  exclude: zod.z.array(zod.z.string()).optional()
+});
+var SyncRulesSchema = zod.z.object({
+  autoSyncPatterns: zod.z.array(AutoSyncPatternSchema).optional(),
+  preventSelfSync: zod.z.boolean().optional(),
+  preventCodexSync: zod.z.boolean().optional(),
+  allowProjectOverrides: zod.z.boolean().optional(),
+  defaultInclude: zod.z.array(zod.z.string()).optional(),
+  defaultExclude: zod.z.array(zod.z.string()).optional()
+});
+var CodexConfigSchema = zod.z.object({
+  organizationSlug: zod.z.string(),
+  directories: zod.z.object({
+    source: zod.z.string().optional(),
+    target: zod.z.string().optional(),
+    systems: zod.z.string().optional()
+  }).optional(),
+  rules: SyncRulesSchema.optional()
+}).strict();
+function parseMetadata(content, options = {}) {
+  const { strict = true, normalize = true } = options;
+  const normalizedContent = normalize ? content.replace(/\r\n/g, "\n") : content;
+  const frontmatterMatch = normalizedContent.match(
+    /^---\n([\s\S]*?)\n---\n([\s\S]*)$/
+  );
+  if (!frontmatterMatch) {
+    return {
+      metadata: {},
+      content: normalizedContent,
+      raw: ""
+    };
+  }
+  const rawFrontmatter = frontmatterMatch[1];
+  const documentContent = frontmatterMatch[2];
+  try {
+    const parsed = yaml__default.default.load(rawFrontmatter);
+    const normalized = normalizeLegacyMetadata(parsed);
+    const metadata = strict ? MetadataSchema.parse(normalized) : MetadataSchema.safeParse(normalized).data || {};
+    return {
+      metadata,
+      content: documentContent,
+      raw: rawFrontmatter
+    };
+  } catch (error) {
+    if (strict) {
+      throw new ValidationError(
+        `Invalid frontmatter: ${error instanceof Error ? error.message : String(error)}`,
+        { cause: error }
+      );
+    }
+    return {
+      metadata: {},
+      content: documentContent,
+      raw: rawFrontmatter
+    };
+  }
+}
+function normalizeLegacyMetadata(parsed) {
+  const normalized = { ...parsed };
+  if (parsed.codex?.includes && !parsed.codex_sync_include) {
+    normalized.codex_sync_include = parsed.codex.includes;
+  }
+  if (parsed.codex?.excludes && !parsed.codex_sync_exclude) {
+    normalized.codex_sync_exclude = parsed.codex.excludes;
+  }
+  return normalized;
+}
+function hasFrontmatter(content) {
+  const normalized = content.replace(/\r\n/g, "\n");
+  return /^---\n[\s\S]*?\n---\n/.test(normalized);
+}
+function validateMetadata(metadata) {
+  const result = MetadataSchema.safeParse(metadata);
+  if (result.success) {
+    return { valid: true };
+  }
+  return {
+    valid: false,
+    errors: result.error.issues.map((issue) => issue.message)
+  };
+}
+function extractRawFrontmatter(content) {
+  const normalized = content.replace(/\r\n/g, "\n");
+  const match = normalized.match(/^---\n([\s\S]*?)\n---\n/);
+  return match && match[1] ? match[1] : null;
+}
+function matchPattern(pattern, value) {
+  if (pattern === value) return true;
+  return micromatch.isMatch(value, pattern);
+}
+function matchAnyPattern(patterns, value) {
+  if (patterns.length === 1 && patterns[0] === "*") {
+    return true;
+  }
+  if (patterns.length === 0) {
+    return false;
+  }
+  return patterns.some((pattern) => matchPattern(pattern, value));
+}
+function filterByPatterns(patterns, values) {
+  return values.filter((value) => matchAnyPattern(patterns, value));
+}
+function evaluatePatterns(options) {
+  const { value, include = [], exclude = [] } = options;
+  if (exclude.length > 0 && matchAnyPattern(exclude, value)) {
+    return false;
+  }
+  if (include.length === 0) {
+    return true;
+  }
+  return matchAnyPattern(include, value);
+}
+
+// src/core/config/organization.ts
+function resolveOrganization(options = {}) {
+  const { orgSlug, repoName, autoDetect = true } = options;
+  if (orgSlug) {
+    return orgSlug;
+  }
+  if (autoDetect && repoName) {
+    const detected = extractOrgFromRepoName(repoName);
+    if (detected) {
+      return detected;
+    }
+  }
+  const envOrg = process.env["ORGANIZATION_SLUG"] || process.env["CODEX_ORG_SLUG"];
+  if (envOrg) {
+    return envOrg;
+  }
+  throw new ConfigurationError(
+    "Organization slug could not be determined. Set ORGANIZATION_SLUG environment variable or pass orgSlug option."
+  );
+}
+function extractOrgFromRepoName(repoName) {
+  const match = repoName.match(/^codex\.([^.]+)\.[^.]+$/);
+  if (match && match[1]) {
+    return match[1];
+  }
+  return null;
+}
+
+// src/core/config/defaults.ts
+function getDefaultDirectories(orgSlug) {
+  return {
+    source: `.${orgSlug}`,
+    target: `.${orgSlug}`,
+    systems: `.${orgSlug}/systems`
+  };
+}
+function getDefaultRules() {
+  return {
+    autoSyncPatterns: [],
+    preventSelfSync: true,
+    preventCodexSync: true,
+    allowProjectOverrides: true,
+    defaultInclude: [],
+    defaultExclude: []
+  };
+}
+function getDefaultConfig(orgSlug) {
+  return {
+    organizationSlug: orgSlug,
+    directories: getDefaultDirectories(orgSlug),
+    rules: getDefaultRules()
+  };
+}
+
+// src/core/config/loader.ts
+function loadConfig(options = {}) {
+  const orgSlug = resolveOrganization({
+    orgSlug: options.organizationSlug,
+    repoName: options.repoName
+  });
+  let config = {
+    organizationSlug: orgSlug,
+    directories: getDefaultDirectories(orgSlug),
+    rules: getDefaultRules()
+  };
+  const envConfig = loadConfigFromEnv(options.env || process.env);
+  config = mergeConfigs(config, envConfig);
+  return CodexConfigSchema.parse(config);
+}
+function loadConfigFromEnv(env) {
+  const config = {};
+  if (env["ORGANIZATION_SLUG"] || env["CODEX_ORG_SLUG"]) {
+    config.organizationSlug = env["ORGANIZATION_SLUG"] || env["CODEX_ORG_SLUG"];
+  }
+  if (env["CODEX_SOURCE_DIR"] || env["CODEX_TARGET_DIR"]) {
+    config.directories = {
+      source: env["CODEX_SOURCE_DIR"],
+      target: env["CODEX_TARGET_DIR"]
+    };
+  }
+  const rules = {};
+  if (env["CODEX_PREVENT_SELF_SYNC"] !== void 0) {
+    rules.preventSelfSync = env["CODEX_PREVENT_SELF_SYNC"] === "true";
+  }
+  if (env["CODEX_PREVENT_CODEX_SYNC"] !== void 0) {
+    rules.preventCodexSync = env["CODEX_PREVENT_CODEX_SYNC"] === "true";
+  }
+  if (env["CODEX_ALLOW_PROJECT_OVERRIDES"] !== void 0) {
+    rules.allowProjectOverrides = env["CODEX_ALLOW_PROJECT_OVERRIDES"] === "true";
+  }
+  if (Object.keys(rules).length > 0) {
+    config.rules = rules;
+  }
+  return config;
+}
+function mergeConfigs(base, override) {
+  return {
+    organizationSlug: override.organizationSlug ?? base.organizationSlug,
+    directories: {
+      ...base.directories,
+      ...override.directories
+    },
+    rules: {
+      ...base.rules,
+      ...override.rules,
+      // Arrays are replaced, not merged
+      autoSyncPatterns: override.rules?.autoSyncPatterns ?? base.rules?.autoSyncPatterns,
+      defaultInclude: override.rules?.defaultInclude ?? base.rules?.defaultInclude,
+      defaultExclude: override.rules?.defaultExclude ?? base.rules?.defaultExclude
+    }
+  };
+}
+
+// src/core/routing/evaluator.ts
+function shouldSyncToRepo(options) {
+  const {
+    filePath,
+    fileMetadata,
+    targetRepo,
+    sourceRepo,
+    rules = getDefaultRules()
+  } = options;
+  const specialRuleResult = evaluateSpecialRules({
+    filePath,
+    targetRepo,
+    sourceRepo,
+    rules
+  });
+  if (specialRuleResult !== null) {
+    return specialRuleResult;
+  }
+  return evaluateFrontmatterRules({
+    metadata: fileMetadata,
+    targetRepo,
+    allowOverrides: rules.allowProjectOverrides ?? true
+  });
+}
+function evaluateSpecialRules(options) {
+  const { filePath, targetRepo, sourceRepo, rules } = options;
+  if (rules.autoSyncPatterns?.length) {
+    const autoSyncResult = evaluateAutoSyncPatterns(
+      filePath,
+      targetRepo,
+      rules.autoSyncPatterns
+    );
+    if (autoSyncResult !== null) {
+      return autoSyncResult;
+    }
+  }
+  if (rules.preventSelfSync) {
+    const selfSyncResult = preventSelfSync(filePath, targetRepo);
+    if (selfSyncResult !== null) {
+      return selfSyncResult;
+    }
+  }
+  if (rules.preventCodexSync) {
+    const codexSyncResult = preventCodexSync(targetRepo, sourceRepo);
+    if (codexSyncResult !== null) {
+      return codexSyncResult;
+    }
+  }
+  return null;
+}
+function evaluateAutoSyncPatterns(filePath, targetRepo, patterns) {
+  for (const autoPattern of patterns) {
+    if (matchPattern(autoPattern.pattern, filePath)) {
+      return evaluatePatterns({
+        value: targetRepo,
+        include: autoPattern.include,
+        ...autoPattern.exclude && { exclude: autoPattern.exclude }
+      });
+    }
+  }
+  return null;
+}
+function preventSelfSync(filePath, targetRepo, _sourceRepo) {
+  const systemMatch = filePath.match(/systems\/([^/]+)\//);
+  if (systemMatch && systemMatch[1]) {
+    const systemName = systemMatch[1];
+    if (systemName === targetRepo) {
+      return false;
+    }
+  }
+  return null;
+}
+function preventCodexSync(targetRepo, sourceRepo) {
+  const isCodexRepo = targetRepo === sourceRepo || targetRepo.startsWith("codex.");
+  if (isCodexRepo) {
+    return false;
+  }
+  return null;
+}
+function evaluateFrontmatterRules(options) {
+  const { metadata, targetRepo, allowOverrides } = options;
+  if (!allowOverrides) {
+    return false;
+  }
+  const include = metadata.codex_sync_include || [];
+  const exclude = metadata.codex_sync_exclude || [];
+  if (include.length === 0) {
+    return false;
+  }
+  return evaluatePatterns({
+    value: targetRepo,
+    include,
+    exclude
+  });
+}
+function getTargetRepos(options) {
+  const { filePath, fileMetadata, sourceRepo, allRepos, rules } = options;
+  return allRepos.filter(
+    (targetRepo) => shouldSyncToRepo({
+      filePath,
+      fileMetadata,
+      targetRepo,
+      sourceRepo,
+      ...rules && { rules }
+    })
+  );
+}
+
+exports.AutoSyncPatternSchema = AutoSyncPatternSchema;
+exports.CodexConfigSchema = CodexConfigSchema;
+exports.CodexError = CodexError;
+exports.ConfigurationError = ConfigurationError;
+exports.MetadataSchema = MetadataSchema;
+exports.SyncRulesSchema = SyncRulesSchema;
+exports.ValidationError = ValidationError;
+exports.evaluatePatterns = evaluatePatterns;
+exports.extractOrgFromRepoName = extractOrgFromRepoName;
+exports.extractRawFrontmatter = extractRawFrontmatter;
+exports.filterByPatterns = filterByPatterns;
+exports.getDefaultConfig = getDefaultConfig;
+exports.getDefaultDirectories = getDefaultDirectories;
+exports.getDefaultRules = getDefaultRules;
+exports.getTargetRepos = getTargetRepos;
+exports.hasFrontmatter = hasFrontmatter;
+exports.loadConfig = loadConfig;
+exports.matchAnyPattern = matchAnyPattern;
+exports.matchPattern = matchPattern;
+exports.parseMetadata = parseMetadata;
+exports.resolveOrganization = resolveOrganization;
+exports.shouldSyncToRepo = shouldSyncToRepo;
+exports.validateMetadata = validateMetadata;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map