@anaclumos/taal 1.1.4 → 1.1.8

package/.github/workflows/publish.yml

@@ -7,7 +7,7 @@ on:
 
 permissions:
   contents: read
-  id-token: write # Required for NPM provenance
+  id-token: write # Required for NPM trusted publishing (OIDC)
 
 jobs:
   publish:
@@ -33,10 +33,14 @@ jobs:
       - name: Setup Node.js for NPM publishing
         uses: actions/setup-node@v4
         with:
-          node-version: '20'
+          node-version: '22'
           registry-url: 'https://registry.npmjs.org'
 
-      - name: Publish to NPM with provenance
-        run: npm publish --provenance --access public
-        env:
-          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+      - name: Update npm to latest (required for trusted publishing)
+        run: npm install -g npm@latest
+
+      - name: Verify npm version
+        run: npm --version
+
+      - name: Publish to NPM with trusted publishing
+        run: npm publish --access public

package/AGENTS.md

@@ -1,123 +1,237 @@
-# Ultracite Code Standards
-
-This project uses **Ultracite**, a zero-config preset that enforces strict code quality standards through automated formatting and linting.
-
-## Quick Reference
-
-- **Format code**: `bun x ultracite fix`
-- **Check for issues**: `bun x ultracite check`
-- **Diagnose setup**: `bun x ultracite doctor`
-
-Biome (the underlying engine) provides robust linting and formatting. Most issues are automatically fixable.
-
+# TAAL Agent Instructions
+
+This file provides instructions for AI agents working with TAAL configurations.
+
+## About TAAL
+
+TAAL (Tooling & Agent Abstraction Layer) syncs MCP server configs and Agent Skills across AI coding assistants.
+
+- **Repository**: https://github.com/anaclumos/taal
+- **Package**: `@anaclumos/taal`
+- **Config Location**: `~/.taal/config.yaml`
+- **Skills Location**: `~/.taal/skills/`
+
+## How to Use TAAL
+
+### Installation
+
+```bash
+npm install -g @anaclumos/taal
+```
+
+### Core Commands
+
+| Command | Purpose | Example |
+|---------|---------|---------|
+| `taal init` | Initialize TAAL configuration | `taal init` |
+| `taal collect` | Import configs from installed providers | `taal collect` |
+| `taal validate` | Validate configuration | `taal validate` |
+| `taal diff` | Preview changes before sync | `taal diff` |
+| `taal sync` | Sync configs to all providers | `taal sync` |
+| `taal list` | List configured servers and skills | `taal list` |
+| `taal providers` | Show all supported providers | `taal providers` |
+
+### Typical Workflow
+
+1. **First-time setup:**
+   ```bash
+   taal init          # Creates ~/.taal/config.yaml
+   taal collect       # Imports existing MCP configs
+   taal validate      # Checks configuration
+   taal sync          # Syncs to all providers
+   ```
+
+2. **Adding a new MCP server:**
+   ```bash
+   # Edit ~/.taal/config.yaml to add server
+   taal validate      # Verify configuration
+   taal diff          # Preview changes
+   taal sync          # Apply changes
+   ```
+
+3. **Adding a new skill:**
+   ```bash
+   # Create skill in ~/.taal/skills/my-skill/SKILL.md
+   taal list          # Verify skill is discovered
+   taal sync          # Sync to providers
+   ```
+
+### Configuration Structure
+
+**File**: `~/.taal/config.yaml`
+
+```yaml
+version: "1"
+
+mcp:
+  # stdio server example
+  filesystem:
+    command: npx
+    args: ["-y", "@modelcontextprotocol/server-filesystem", "/path"]
+    env:
+      LOG_LEVEL: "info"
+  
+  # HTTP server example
+  context7:
+    url: https://mcp.context7.com/mcp
+    headers:
+      CONTEXT7_API_KEY: "${CONTEXT7_API_KEY}"
+
+skills:
+  paths:
+    - ~/.taal/skills
+    - ~/projects/custom-skills
+
+providers:
+  enabled:
+    - claude-desktop
+    - claude-code
+    - cursor
+    - zed
+```
+
+### Supported Providers
+
+- **Claude Desktop** - stdio only, skills: `~/.claude/skills/`
+- **Claude Code** - stdio + HTTP, skills: `~/.claude/skills/`
+- **Cursor** - stdio only
+- **Continue.dev** - stdio + HTTP (SSE)
+- **Zed** - stdio + HTTP
+- **OpenCode** - stdio + HTTP, skills: `~/.config/opencode/skill/`
+- **Codex** - stdio + HTTP, skills: `~/.codex/skills/`
+- **Windsurf** - stdio + HTTP
+- **Antigravity** - stdio only
+
+### Environment Variables
+
+Use `${VAR_NAME}` syntax in config:
+
+```yaml
+mcp:
+  my-server:
+    url: https://api.example.com
+    headers:
+      API_KEY: "${MY_API_KEY}"
+```
+
+TAAL will substitute variables at sync time and warn if undefined.
+
+### Skills Structure
+
+Create skills in `~/.taal/skills/`:
+
+```
+~/.taal/skills/
+└── my-skill/
+    ├── SKILL.md          # Required: YAML frontmatter + instructions
+    ├── scripts/          # Optional: Helper scripts
+    └── references/       # Optional: Reference materials
+```
+
+**SKILL.md format:**
+
+```markdown
+---
+name: My Skill
+description: What this skill does
+version: 1.0.0
 ---
 
-## Core Principles
+# My Skill
 
-Write code that is **accessible, performant, type-safe, and maintainable**. Focus on clarity and explicit intent over brevity.
+Instructions for the AI agent...
+```
 
-### Type Safety & Explicitness
+## Coding Standards
 
-- Use explicit types for function parameters and return values when they enhance clarity
-- Prefer `unknown` over `any` when the type is genuinely unknown
-- Use const assertions (`as const`) for immutable values and literal types
-- Leverage TypeScript's type narrowing instead of type assertions
-- Use meaningful variable names instead of magic numbers - extract constants with descriptive names
+When working on TAAL codebase or related projects, fetch and follow the latest coding standards:
 
-### Modern JavaScript/TypeScript
+```
+https://raw.githubusercontent.com/anaclumos/taal/master/AGENTS.md
+```
 
-- Use arrow functions for callbacks and short functions
-- Prefer `for...of` loops over `.forEach()` and indexed `for` loops
-- Use optional chaining (`?.`) and nullish coalescing (`??`) for safer property access
-- Prefer template literals over string concatenation
-- Use destructuring for object and array assignments
-- Use `const` by default, `let` only when reassignment is needed, never `var`
+Use WebFetch or similar tools to retrieve the latest guidelines before making code changes.
 
-### Async & Promises
+### Development Workflow
 
-- Always `await` promises in async functions - don't forget to use the return value
-- Use `async/await` syntax instead of promise chains for better readability
-- Handle errors appropriately in async code with try-catch blocks
-- Don't use async functions as Promise executors
+1. Fetch the latest AGENTS.md from the URL above
+2. Review the coding standards and principles
+3. Apply them to your work on TAAL configurations and related code
+4. Ensure all changes comply with Ultracite code quality standards
 
-### React & JSX
+## Common Tasks for Agents
 
-- Use function components over class components
-- Call hooks at the top level only, never conditionally
-- Specify all dependencies in hook dependency arrays correctly
-- Use the `key` prop for elements in iterables (prefer unique IDs over array indices)
-- Nest children between opening and closing tags instead of passing as props
-- Don't define components inside other components
-- Use semantic HTML and ARIA attributes for accessibility:
-  - Provide meaningful alt text for images
-  - Use proper heading hierarchy
-  - Add labels for form inputs
-  - Include keyboard event handlers alongside mouse events
-  - Use semantic elements (`<button>`, `<nav>`, etc.) instead of divs with roles
+### Task: Add a new MCP server
 
-### Error Handling & Debugging
+```bash
+# 1. Edit config
+vim ~/.taal/config.yaml
 
-- Remove `console.log`, `debugger`, and `alert` statements from production code
-- Throw `Error` objects with descriptive messages, not strings or other values
-- Use `try-catch` blocks meaningfully - don't catch errors just to rethrow them
-- Prefer early returns over nested conditionals for error cases
+# 2. Add server configuration
+# mcp:
+#   new-server:
+#     command: npx
+#     args: ["-y", "package-name"]
 
-### Code Organization
+# 3. Validate
+taal validate
 
-- Keep functions focused and under reasonable cognitive complexity limits
-- Extract complex conditions into well-named boolean variables
-- Use early returns to reduce nesting
-- Prefer simple conditionals over nested ternary operators
-- Group related code together and separate concerns
+# 4. Preview changes
+taal diff
 
-### Security
+# 5. Sync
+taal sync
+```
 
-- Add `rel="noopener"` when using `target="_blank"` on links
-- Avoid `dangerouslySetInnerHTML` unless absolutely necessary
-- Don't use `eval()` or assign directly to `document.cookie`
-- Validate and sanitize user input
+### Task: Create a new skill
 
-### Performance
+```bash
+# 1. Create skill directory
+mkdir -p ~/.taal/skills/my-skill
 
-- Avoid spread syntax in accumulators within loops
-- Use top-level regex literals instead of creating them in loops
-- Prefer specific imports over namespace imports
-- Avoid barrel files (index files that re-export everything)
-- Use proper image components (e.g., Next.js `<Image>`) over `<img>` tags
+# 2. Create SKILL.md
+cat > ~/.taal/skills/my-skill/SKILL.md << 'EOF'
+---
+name: My Skill
+description: Skill description
+version: 1.0.0
+---
 
-### Framework-Specific Guidance
+# My Skill
 
-**Next.js:**
-- Use Next.js `<Image>` component for images
-- Use `next/head` or App Router metadata API for head elements
-- Use Server Components for async data fetching instead of async Client Components
+Instructions for AI agents...
+EOF
 
-**React 19+:**
-- Use ref as a prop instead of `React.forwardRef`
+# 3. Verify discovery
+taal list
 
-**Solid/Svelte/Vue/Qwik:**
-- Use `class` and `for` attributes (not `className` or `htmlFor`)
+# 4. Sync to providers
+taal sync
+```
 
----
+### Task: Troubleshoot configuration
 
-## Testing
+```bash
+# Check validation errors
+taal validate
 
-- Write assertions inside `it()` or `test()` blocks
-- Avoid done callbacks in async tests - use async/await instead
-- Don't use `.only` or `.skip` in committed code
-- Keep test suites reasonably flat - avoid excessive `describe` nesting
+# Check which providers are installed
+taal providers
 
-## When Biome Can't Help
+# Preview what would change
+taal diff
 
-Biome's linter will catch most issues automatically. Focus your attention on:
+# Check current configuration
+cat ~/.taal/config.yaml
 
-1. **Business logic correctness** - Biome can't validate your algorithms
-2. **Meaningful naming** - Use descriptive names for functions, variables, and types
-3. **Architecture decisions** - Component structure, data flow, and API design
-4. **Edge cases** - Handle boundary conditions and error states
-5. **User experience** - Accessibility, performance, and usability considerations
-6. **Documentation** - Add comments for complex logic, but prefer self-documenting code
+# Check backups if something went wrong
+ls -la ~/.taal/backups/
+```
 
----
+## Important Notes
 
-Most formatting and common issues are automatically fixed by Biome. Run `bun x ultracite fix` before committing to ensure compliance.
+- **Backups**: TAAL automatically creates backups before every sync in `~/.taal/backups/`
+- **Environment Variables**: Undefined variables trigger warnings but don't block sync
+- **Provider Detection**: TAAL auto-detects installed providers by checking config directories
+- **Skills Validation**: Invalid skills are skipped with warnings during sync
+- **Mutual Exclusivity**: MCP servers must have either `command` (stdio) OR `url` (HTTP), not both

package/README.md

@@ -226,9 +226,15 @@ TAAL supports 9 AI coding assistants:
 
 ### Provider-Specific Notes
 
-**Claude Desktop & Claude Code**
+**Claude Desktop**
 - Only supports stdio servers (no HTTP)
-- Shared skills directory: `~/.claude/skills/`
+- Skills directory: `~/.claude/skills/`
+
+**Claude Code**
+- Supports both stdio and HTTP servers (SSE deprecated)
+- Uses `type: "http" | "stdio"` format in config
+- Skills directory: `~/.claude/skills/`
+- Can import servers from Claude Desktop via `claude mcp add-from-claude-desktop`
 
 **Cursor**
 - Only supports stdio servers

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@anaclumos/taal",
-  "version": "1.1.4",
+  "version": "1.1.8",
   "description": "CLI tool to sync MCP server configs and Agent Skills across AI coding assistants",
   "type": "module",
   "bin": {

package/src/commands/diff.ts

@@ -2,6 +2,20 @@ import { homedir } from "node:os";
 import { loadTaalConfig } from "../config/loader.js";
 import { initializeProviders, registry } from "../providers/index.js";
 
+function sortObjectKeys(obj: unknown): unknown {
+  if (obj === null || typeof obj !== "object") {
+    return obj;
+  }
+  if (Array.isArray(obj)) {
+    return obj.map(sortObjectKeys);
+  }
+  const sorted: Record<string, unknown> = {};
+  for (const key of Object.keys(obj).sort()) {
+    sorted[key] = sortObjectKeys((obj as Record<string, unknown>)[key]);
+  }
+  return sorted;
+}
+
 export interface DiffChange {
   type: "add" | "remove" | "modify";
   serverName: string;
@@ -73,9 +87,13 @@ export async function diff(
 
         for (const key of taalKeys) {
           if (currentKeys.has(key)) {
-            const currentValue = JSON.stringify(currentServers[key]);
+            const currentValue = JSON.stringify(
+              sortObjectKeys(currentServers[key])
+            );
             const newValue = JSON.stringify(
-              (transformedServers as Record<string, unknown>)[key]
+              sortObjectKeys(
+                (transformedServers as Record<string, unknown>)[key]
+              )
             );
 
             if (currentValue !== newValue) {

package/src/providers/claude-code.ts

@@ -1,5 +1,6 @@
 import { join } from "node:path";
-import { BaseProvider, createStdioTransformer } from "./base.js";
+import type { McpServer } from "../config/schema.js";
+import { BaseProvider } from "./base.js";
 
 export class ClaudeCodeProvider extends BaseProvider {
   name = "claude-code";
@@ -8,5 +9,32 @@ export class ClaudeCodeProvider extends BaseProvider {
   mcpKey = "mcpServers";
   skillsPath = (home: string) => join(home, ".claude", "skills");
 
-  transformMcpServers = createStdioTransformer("Claude Code");
+  transformMcpServers(
+    servers: Record<string, McpServer>
+  ): Record<string, unknown> {
+    const transformed: Record<string, unknown> = {};
+
+    for (const [name, server] of Object.entries(servers)) {
+      if (server.url) {
+        // HTTP server - Claude Code supports HTTP transport
+        transformed[name] = {
+          type: "http",
+          url: server.url,
+          ...(server.headers && { headers: server.headers }),
+        };
+      } else if (server.command) {
+        // stdio server - Claude Code supports stdio transport
+        transformed[name] = {
+          type: "stdio",
+          command: server.command,
+          ...(server.args && { args: server.args }),
+          ...(server.env && { env: server.env }),
+        };
+      } else {
+        console.warn(`Skipping server "${name}" - missing command or url`);
+      }
+    }
+
+    return transformed;
+  }
 }

package/.claude/settings.json

@@ -1,15 +0,0 @@
-{
-  "hooks": {
-    "PostToolUse": [
-      {
-        "matcher": "Write|Edit",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "bun x ultracite fix"
-          }
-        ]
-      }
-    ]
-  }
-}