@fractary/codex-cli 0.10.13 → 0.10.15

package/README.md

@@ -4,272 +4,54 @@ Command-line interface for Fractary Codex knowledge management system.
 
 ## Installation
 
-### Global Installation
-
 ```bash
 npm install -g @fractary/codex-cli
 ```
 
-### Local Development
-
-```bash
-# From repository root
-npm install
-cd cli
-npm run build
-npm link
-```
-
-## Usage
-
-```bash
-fractary-codex [command] [options]
-```
-
-## Commands
-
-### `init` - Initialize Configuration
-
-Initialize Codex v3.0 with YAML configuration in your project.
-
-```bash
-fractary-codex init [options]
-
-Options:
-  --force    Overwrite existing configuration
-```
+## Quick Start
 
-**Example:**
 ```bash
+# Initialize configuration
 fractary-codex init
-# Creates .fractary/config.yaml and .fractary/codex/cache/
-```
-
-### `fetch` - Fetch Documents
-
-Fetch documents by `codex://` URI reference with intelligent caching.
-
-```bash
-fractary-codex fetch <uri> [options]
-
-Arguments:
-  uri                  Codex URI (e.g., codex://org/project/path/file.md)
-
-Options:
-  --bypass-cache       Fetch directly from storage, bypassing cache
-  --ttl <seconds>      Override default TTL
-  --json               Output as JSON with metadata
-  --output <file>      Write content to file instead of stdout
-```
 
-**Examples:**
-```bash
-# Fetch with caching
+# Fetch a document
 fractary-codex fetch codex://myorg/myproject/README.md
 
-# Bypass cache
-fractary-codex fetch codex://myorg/myproject/README.md --bypass-cache
+# Check cache status
+fractary-codex cache stats
 
-# JSON output with metadata
-fractary-codex fetch codex://myorg/myproject/README.md --json
-
-# Save to file
-fractary-codex fetch codex://myorg/myproject/README.md --output local-README.md
+# Run health check
+fractary-codex health
 ```
 
-### `cache` - Cache Management
-
-Manage the document cache with subcommands for listing, clearing, and viewing statistics.
+## Commands Overview
 
-#### `cache list` - List Cache Information
-
-```bash
-fractary-codex cache list [options]
-
-Options:
-  --json    Output as JSON
-```
+| Command | Description |
+|---------|-------------|
+| `init` | Initialize configuration |
+| `fetch <uri>` | Fetch documents by codex:// URI |
+| `cache list` | List cached documents |
+| `cache clear` | Clear cache entries |
+| `cache stats` | Show cache statistics |
+| `sync project` | Sync single project |
+| `sync org` | Sync entire organization |
+| `types list` | List artifact types |
+| `types add` | Add custom type |
+| `health` | Run diagnostics |
+| `migrate` | Migrate v2.x config to v3.0 |
 
-#### `cache clear` - Clear Cache Entries
+## Documentation
 
-```bash
-fractary-codex cache clear [options]
-
-Options:
-  --all                Clear entire cache
-  --pattern <glob>     Clear entries matching pattern
-  --dry-run            Preview without clearing
-```
-
-**Examples:**
-```bash
-# Clear all cache entries
-fractary-codex cache clear --all
-
-# Clear specific pattern
-fractary-codex cache clear --pattern "myorg/myproject/**"
-
-# Preview clearing
-fractary-codex cache clear --all --dry-run
-```
-
-#### `cache stats` - Cache Statistics
-
-```bash
-fractary-codex cache stats [options]
-
-Options:
-  --json    Output as JSON
-```
-
-### `sync` - Bidirectional Synchronization
-
-Synchronize files with codex repository.
-
-#### `sync project` - Sync Single Project
-
-```bash
-fractary-codex sync project [project-name] [options]
-
-Options:
-  --to-codex           Sync from project to codex (one-way)
-  --from-codex         Sync from codex to project (one-way)
-  --bidirectional      Two-way sync (default)
-  --dry-run            Preview changes without syncing
-  --env <environment>  Environment branch mapping
-```
-
-#### `sync org` - Sync Organization
-
-```bash
-fractary-codex sync org [options]
-
-Options:
-  --to-codex           Sync from projects to codex
-  --from-codex         Sync from codex to projects
-  --bidirectional      Two-way sync (default)
-  --dry-run            Preview changes
-  --exclude <pattern>  Exclude repositories matching pattern
-  --parallel <n>       Number of parallel sync operations (default: 3)
-```
-
-**Routing-Aware Sync (v4.1+):**
-
-When using `--from-codex` direction, the sync command uses **routing-aware file discovery** to find all files across the entire codex that should sync to your project based on `codex_sync_include` frontmatter patterns.
-
-How it works:
-1. Clones the entire codex repository to a temporary directory (`/tmp/fractary-codex-clone/`)
-2. Scans ALL markdown files in the codex recursively
-3. Evaluates `codex_sync_include` patterns in each file's frontmatter
-4. Returns only files that match your project name or pattern
-
-**Example frontmatter in source files:**
-```yaml
----
-codex_sync_include: ['*']                  # Syncs to ALL projects
-codex_sync_include: ['lake-*', 'api-*']    # Syncs to lake-* and api-* projects
-codex_sync_exclude: ['*-test']             # Except *-test projects
----
-```
+**Full documentation**: [docs/cli/](../docs/cli/)
 
-**Trade-offs:**
-- **Efficient for discovery**: Finds all relevant files across hundreds of projects
-- **Inefficient for execution**: Clones entire codex repository (uses shallow clone for speed)
-- **Best practice**: Use `codex://` URI references + cache purging for most workflows; use sync occasionally when needed
-
-**Recommended workflow:**
-```bash
-# Primary: Reference files via codex:// URIs (no sync needed)
-fractary-codex fetch codex://org/project/path/file.md
-
-# When you need latest versions: Purge cache
-fractary-codex cache clear --pattern "codex://org/project/*"
-
-# Then MCP will re-fetch fresh content automatically
-```
-
-### `types` - Type Registry Management
-
-Manage custom artifact types for classification and caching.
-
-#### `types list` - List All Types
-
-```bash
-fractary-codex types list [options]
-
-Options:
-  --custom-only    Show only custom types
-  --builtin-only   Show only built-in types
-  --json           Output as JSON
-```
-
-#### `types show` - Show Type Details
-
-```bash
-fractary-codex types show <type-name> [options]
-
-Options:
-  --json    Output as JSON
-```
-
-#### `types add` - Add Custom Type
-
-```bash
-fractary-codex types add <type-name> [options]
-
-Options:
-  --pattern <glob>        File pattern (required)
-  --ttl <duration>        Cache TTL (default: 24h)
-  --description <text>    Type description
-```
-
-**Example:**
-```bash
-fractary-codex types add api-schema --pattern "**/*.openapi.{yaml,json}" --ttl 48h --description "OpenAPI schemas"
-```
-
-#### `types remove` - Remove Custom Type
-
-```bash
-fractary-codex types remove <type-name> [options]
-
-Options:
-  --json    Output as JSON
-```
-
-### `health` - Diagnostics
-
-Run comprehensive diagnostics on codex setup.
-
-```bash
-fractary-codex health [options]
-
-Options:
-  --json    Output as JSON for CI/CD integration
-```
-
-**Checks:**
-- Configuration validity
-- SDK client initialization
-- Cache health and statistics
-- Storage provider availability
-- Type registry status
-
-### `migrate` - Configuration Migration
-
-Migrate legacy v2.x JSON configuration to v3.0 YAML format.
-
-```bash
-fractary-codex migrate [options]
-
-Options:
-  --dry-run    Preview migration without writing
-  --json       Output as JSON
-```
+- [Commands Reference](../docs/cli/#commands-reference)
+- [Integration Patterns](../docs/cli/#integration-patterns)
+- [Troubleshooting](../docs/cli/#troubleshooting)
+- [Configuration Guide](../docs/configuration.md)
 
 ## Configuration
 
-Codex uses `.fractary/config.yaml` for configuration:
+Uses `.fractary/config.yaml`:
 
 ```yaml
 organization: myorg
@@ -277,95 +59,39 @@ cacheDir: .fractary/codex/cache
 
 storage:
   - type: github
-    owner: myorg
-    repo: codex-core
-    ref: main
     token: ${GITHUB_TOKEN}
-    priority: 50
-
-  - type: local
-    path: ./codex-local
-    priority: 10
-
-types:
-  custom:
-    api-schema:
-      description: OpenAPI API schemas
-      patterns:
-        - "**/*.openapi.yaml"
-        - "**/*.openapi.json"
-      defaultTtl: 172800  # 48 hours
-
-permissions:
-  default: read
-  rules:
-    - pattern: "sensitive/**"
-      permission: admin
-      users: ["admin-user"]
-
-sync:
-  bidirectional: true
-  conflictResolution: latest
-  exclude:
-    - "node_modules/**"
-    - ".git/**"
-
-mcp:
-  enabled: true
-  port: 3000
 ```
 
 ## Environment Variables
 
-- `GITHUB_TOKEN` - GitHub personal access token for private repositories
-- `CODEX_CACHE_DIR` - Override default cache directory
-- `CODEX_ORG` - Override organization slug
+| Variable | Description |
+|----------|-------------|
+| `GITHUB_TOKEN` | GitHub access token |
+| `CODEX_CACHE_DIR` | Override cache directory |
+| `CODEX_ORG` | Override organization |
 
 ## Development
 
-### Build
-
 ```bash
+# Build
 npm run build
-```
-
-### Test
 
-```bash
+# Test
 npm test
-```
 
-### Type Check
-
-```bash
+# Type check
 npm run typecheck
-```
-
-### Link for Local Testing
 
-```bash
+# Link for local testing
 npm link
-fractary-codex --help
 ```
 
-## Architecture
-
-The CLI is built on top of the `@fractary/codex` SDK and uses:
-
-- **Commander.js** for command-line parsing
-- **Chalk** for colored output
-- **js-yaml** for YAML configuration
-- **Dynamic imports** for fast cold-start performance
-
-All commands use lazy-loading to avoid SDK initialization overhead for simple operations like `--help`.
-
 ## License
 
 MIT
 
-## Links
+## See Also
 
-- [GitHub Repository](https://github.com/fractary/codex)
-- [Documentation](https://github.com/fractary/codex/tree/main/docs)
-- [SDK Package](https://github.com/fractary/codex/tree/main/sdk/js)
-- [Issue Tracker](https://github.com/fractary/codex/issues)
+- [SDK Package](../sdk/js/) - Core JavaScript SDK
+- [MCP Server](../mcp/server/) - AI agent integration
+- [Documentation](../docs/) - Full documentation

package/dist/cli.cjs

@@ -823,7 +823,7 @@ function getDefaultUnifiedConfig(organization, project, codexRepo) {
   const sanitizedProject = sanitizeForS3BucketName(project);
   return {
     file: {
-      schema_version: "2.0",
+      schema_version: codex.CONFIG_SCHEMA_VERSION,
       sources: {
         specs: {
           type: "s3",
@@ -860,11 +860,16 @@ function getDefaultUnifiedConfig(organization, project, codexRepo) {
       }
     },
     codex: {
-      schema_version: "2.0",
+      schema_version: codex.CONFIG_SCHEMA_VERSION,
       organization,
       project,
       codex_repo: codexRepo,
-      dependencies: {}
+      remotes: {
+        // The codex repository - uses same token as git operations
+        [`${organization}/${codexRepo}`]: {
+          token: "${GITHUB_TOKEN}"
+        }
+      }
     }
   };
 }
@@ -895,7 +900,7 @@ function mergeUnifiedConfigs(existing, updates) {
   const merged = {};
   if (updates.file || existing.file) {
     merged.file = {
-      schema_version: updates.file?.schema_version || existing.file?.schema_version || "2.0",
+      schema_version: updates.file?.schema_version || existing.file?.schema_version || codex.CONFIG_SCHEMA_VERSION,
       sources: {
         ...existing.file?.sources || {},
         ...updates.file?.sources || {}
@@ -904,13 +909,13 @@ function mergeUnifiedConfigs(existing, updates) {
   }
   if (updates.codex || existing.codex) {
     merged.codex = {
-      schema_version: updates.codex?.schema_version || existing.codex?.schema_version || "2.0",
+      schema_version: updates.codex?.schema_version || existing.codex?.schema_version || codex.CONFIG_SCHEMA_VERSION,
       organization: updates.codex?.organization || existing.codex?.organization || "default",
       project: updates.codex?.project || existing.codex?.project || "default",
       codex_repo: updates.codex?.codex_repo || existing.codex?.codex_repo || "",
-      dependencies: {
-        ...existing.codex?.dependencies || {},
-        ...updates.codex?.dependencies || {}
+      remotes: {
+        ...existing.codex?.remotes || {},
+        ...updates.codex?.remotes || {}
       }
     };
   }
@@ -1124,9 +1129,64 @@ async function fileExists(filePath) {
     return false;
   }
 }
+async function installMcpServer(projectRoot, configPath = ".fractary/config.yaml", options = {}) {
+  const mcpJsonPath = path4__namespace.join(projectRoot, ".mcp.json");
+  const { backup = true } = options;
+  let existingConfig = { mcpServers: {} };
+  let backupPath;
+  let migrated = false;
+  if (await fileExists(mcpJsonPath)) {
+    try {
+      const content = await fs__namespace.readFile(mcpJsonPath, "utf-8");
+      existingConfig = JSON.parse(content);
+      if (backup) {
+        const timestamp = (/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "").slice(0, 18);
+        const suffix = Math.random().toString(36).substring(2, 6);
+        backupPath = `${mcpJsonPath}.backup.${timestamp}-${suffix}`;
+        await fs__namespace.writeFile(backupPath, content);
+      }
+    } catch {
+      console.log(chalk7__default.default.yellow("\u26A0 Warning: .mcp.json contains invalid JSON, starting fresh"));
+      existingConfig = { mcpServers: {} };
+    }
+  }
+  if (!existingConfig.mcpServers) {
+    existingConfig.mcpServers = {};
+  }
+  const existing = existingConfig.mcpServers["fractary-codex"];
+  if (existing) {
+    const existingCommand = existing.command;
+    const existingArgs = existing.args || [];
+    if (existingCommand === "npx" && existingArgs.includes("@fractary/codex-mcp")) {
+      return {
+        installed: false,
+        migrated: false,
+        alreadyInstalled: true,
+        backupPath
+      };
+    }
+    if (existingCommand === "node" || existingArgs.includes("@fractary/codex")) {
+      migrated = true;
+    }
+  }
+  existingConfig.mcpServers["fractary-codex"] = {
+    command: "npx",
+    args: ["-y", "@fractary/codex-mcp", "--config", configPath]
+  };
+  await fs__namespace.writeFile(
+    mcpJsonPath,
+    JSON.stringify(existingConfig, null, 2) + "\n"
+  );
+  return {
+    installed: true,
+    migrated,
+    alreadyInstalled: false,
+    backupPath
+  };
+}
 function initCommand() {
   const cmd = new commander.Command("init");
-  cmd.description("Initialize unified Fractary configuration (.fractary/config.yaml)").option("--org <slug>", 'Organization slug (e.g., "fractary")').option("--project <name>", "Project name (default: derived from directory)").option("--codex-repo <name>", 'Codex repository name (e.g., "codex.fractary.com")').option("--force", "Overwrite existing configuration").action(async (options) => {
+  cmd.description("Initialize unified Fractary configuration (.fractary/config.yaml)").option("--org <slug>", 'Organization slug (e.g., "fractary")').option("--project <name>", "Project name (default: derived from directory)").option("--codex-repo <name>", 'Codex repository name (e.g., "codex.fractary.com")').option("--force", "Overwrite existing configuration").option("--no-mcp", "Skip MCP server installation").action(async (options) => {
     try {
       console.log(chalk7__default.default.blue("Initializing unified Fractary configuration...\n"));
       let org = options.org;
@@ -1238,6 +1298,20 @@ function initCommand() {
       } else if (result.merged) {
         console.log(chalk7__default.default.green("\u2713"), chalk7__default.default.dim(".fractary/config.yaml (merged with existing)"));
       }
+      if (options.mcp !== false) {
+        console.log("\nConfiguring MCP server...");
+        const mcpResult = await installMcpServer(process.cwd(), ".fractary/config.yaml");
+        if (mcpResult.alreadyInstalled) {
+          console.log(chalk7__default.default.green("\u2713"), chalk7__default.default.dim(".mcp.json (already configured)"));
+        } else if (mcpResult.migrated) {
+          console.log(chalk7__default.default.green("\u2713"), chalk7__default.default.dim(".mcp.json (migrated from old format)"));
+          if (mcpResult.backupPath) {
+            console.log(chalk7__default.default.dim(`  Backup: ${path4__namespace.basename(mcpResult.backupPath)}`));
+          }
+        } else if (mcpResult.installed) {
+          console.log(chalk7__default.default.green("\u2713"), chalk7__default.default.dim(".mcp.json (created)"));
+        }
+      }
       console.log(chalk7__default.default.green("\n\u2713 Unified configuration initialized successfully!\n"));
       console.log(chalk7__default.default.bold("Configuration:"));
       console.log(chalk7__default.default.dim(`  Organization: ${org}`));
@@ -1249,18 +1323,19 @@ function initCommand() {
       console.log(chalk7__default.default.dim("  - logs: .fractary/logs/ \u2192 S3"));
       console.log(chalk7__default.default.bold("\nCodex plugin:"));
       console.log(chalk7__default.default.dim("  - Cache: .fractary/codex/cache/"));
-      console.log(chalk7__default.default.dim("  - Dependencies: (none configured)"));
+      console.log(chalk7__default.default.dim("  - MCP Server: @fractary/codex-mcp (via npx)"));
+      console.log(chalk7__default.default.dim("  - Remotes: codex repo configured"));
       console.log(chalk7__default.default.bold("\nGit Authentication:"));
       console.log(chalk7__default.default.dim("  Codex sync uses your existing git credentials."));
       console.log(chalk7__default.default.dim("  Ensure you have access to the codex repository:"));
       console.log(chalk7__default.default.dim(`    gh repo view ${org}/${codexRepo}`));
       console.log(chalk7__default.default.dim("  Or set GITHUB_TOKEN environment variable."));
       console.log(chalk7__default.default.bold("\nNext steps:"));
-      console.log(chalk7__default.default.dim("  1. Verify codex repository access: gh repo view " + org + "/" + codexRepo));
-      console.log(chalk7__default.default.dim("  2. Configure AWS credentials for S3 access (if using file plugin)"));
-      console.log(chalk7__default.default.dim("  3. Edit .fractary/config.yaml to add external project dependencies"));
-      console.log(chalk7__default.default.dim("  4. Access current project files: codex://specs/SPEC-001.md"));
-      console.log(chalk7__default.default.dim("  5. Access external projects: codex://org/project/docs/README.md"));
+      console.log(chalk7__default.default.dim("  1. Restart Claude Code to load the MCP server"));
+      console.log(chalk7__default.default.dim("  2. Verify codex repository access: gh repo view " + org + "/" + codexRepo));
+      console.log(chalk7__default.default.dim("  3. Configure AWS credentials for S3 access (if using file plugin)"));
+      console.log(chalk7__default.default.dim("  4. Edit .fractary/config.yaml to add external project remotes"));
+      console.log(chalk7__default.default.dim("  5. Reference docs via codex:// URIs (auto-fetched by MCP)"));
     } catch (error) {
       console.error(chalk7__default.default.red("Error:"), error.message);
       process.exit(1);
@@ -1723,7 +1798,7 @@ function formatDuration(ms) {
 }
 function syncCommand() {
   const cmd = new commander.Command("sync");
-  cmd.description("Sync single project with codex repository").argument("[name]", "Project name (auto-detected if not provided)").option("--env <env>", "Target environment (dev/test/staging/prod)", "prod").option("--dry-run", "Show what would sync without executing").option("--direction <dir>", "Sync direction (to-codex/from-codex/bidirectional)", "bidirectional").option("--include <pattern>", "Include files matching pattern (can be used multiple times)", (val, prev) => prev.concat([val]), []).option("--exclude <pattern>", "Exclude files matching pattern (can be used multiple times)", (val, prev) => prev.concat([val]), []).option("--force", "Force sync without checking timestamps").option("--json", "Output as JSON").action(async (name, options) => {
+  cmd.description("Sync single project with codex repository").argument("[name]", "Project name (auto-detected if not provided)").option("--env <env>", "Target environment (dev/test/staging/prod)", "prod").option("--dry-run", "Show what would sync without executing").option("--direction <dir>", "Sync direction (to-codex/from-codex/bidirectional)", "bidirectional").option("--include <pattern>", "Include files matching pattern (can be used multiple times)", (val, prev) => prev.concat([val]), []).option("--exclude <pattern>", "Exclude files matching pattern (can be used multiple times)", (val, prev) => prev.concat([val]), []).option("--force", "Force sync without checking timestamps").option("--json", "Output as JSON").option("--work-id <id>", "GitHub issue number or URL to scope sync to").action(async (name, options) => {
     try {
       const configPath = path4__namespace.join(process.cwd(), ".fractary", "config.yaml");
       let config;
@@ -1907,8 +1982,11 @@ function syncCommand() {
           console.log(JSON.stringify({
             project: projectName,
             organization: config.organization,
+            workId: options.workId || null,
             files: [],
-            synced: 0
+            synced: 0,
+            status: "success",
+            message: "No files to sync"
           }, null, 2));
         } else {
           console.log(chalk7__default.default.yellow("No files to sync."));
@@ -1923,6 +2001,7 @@ function syncCommand() {
           branch: targetBranch,
           direction,
           dryRun: options.dryRun || false,
+          workId: options.workId || null,
           plan: {
             totalFiles: plan.totalFiles,
             totalBytes: plan.totalBytes,
@@ -1937,12 +2016,24 @@ function syncCommand() {
           }))
         };
         if (options.dryRun) {
-          console.log(JSON.stringify(output, null, 2));
+          console.log(JSON.stringify({
+            ...output,
+            status: "success"
+          }, null, 2));
           return;
         }
         const result2 = await syncManager.executePlan(plan, syncOptions);
+        let status;
+        if (!result2.success && result2.synced === 0) {
+          status = "failure";
+        } else if (!result2.success || result2.failed > 0 || plan.conflicts.length > 0) {
+          status = "warning";
+        } else {
+          status = "success";
+        }
         console.log(JSON.stringify({
           ...output,
+          status,
           result: {
             success: result2.success,
             synced: result2.synced,