@anaclumos/taal 1.1.4 → 1.1.7

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/DIAGNOSTIC.md

@@ -0,0 +1,75 @@
+# Trusted Publishing Diagnostic
+
+## Current Error
+
+The v1.1.6 workflow failed with:
+```
+npm notice Access token expired or revoked. Please try logging in again.
+npm error 404 Not Found - PUT https://registry.npmjs.org/@anaclumos%2ftaal - Not found
+```
+
+This means OIDC authentication is NOT working. The issue is likely in the npmjs.com configuration.
+
+## Verification Checklist
+
+### 1. Verify Trusted Publisher Configuration
+
+Go to: https://www.npmjs.com/package/@anaclumos/taal/access
+
+Under "Trusted Publisher", you should see:
+- ✅ **Provider**: GitHub Actions
+- ✅ **Organization or user**: `anaclumos` (EXACTLY - case sensitive)
+- ✅ **Repository**: `taal` (EXACTLY - case sensitive)
+- ✅ **Workflow filename**: `publish.yml` (EXACTLY - must include .yml extension)
+- ✅ **Environment name**: (leave EMPTY unless you use GitHub environments)
+
+**CRITICAL**: All fields are case-sensitive and must match EXACTLY.
+
+### 2. Verify Publishing Access Settings
+
+Still on the same page, under "Publishing Access":
+
+You should have selected: **"Require two-factor authentication and disallow tokens"**
+
+NOT:
+- ❌ "Require two-factor authentication or automation tokens"  
+- ❌ "No restrictions"
+
+### 3. Verify You Saved
+
+Make sure you clicked **"Update Package Settings"** at the bottom of the page.
+
+### 4. Screenshot
+
+Can you take a screenshot of your npmjs.com package settings and show me?
+
+## Common Mistakes
+
+1. **Workflow filename without .yml extension**: Must be `publish.yml` not just `publish`
+2. **Case mismatch**: Repository name must match exactly (`taal` not `Taal` or `TAAL`)
+3. **Organization vs user**: Make sure it's your username `anaclumos`, not an organization
+4. **Didn't save**: Settings won't take effect until you click "Update Package Settings"
+5. **Wrong publishing access setting**: Must select "disallow tokens" to allow OIDC
+
+## Next Steps
+
+1. Double-check ALL settings above
+2. Make sure you clicked "Update Package Settings"
+3. If everything looks correct, try again:
+   ```bash
+   npm version patch
+   git push --follow-tags
+   ```
+
+## Alternative: Use Token (Temporary)
+
+If you want to publish NOW while we debug trusted publishing:
+
+1. Create a Granular Access Token on npmjs.com (Read and write access)
+2. Add it as NPM_TOKEN secret:
+   ```bash
+   gh secret set NPM_TOKEN --body "npm_YOUR_TOKEN_HERE"
+   ```
+3. Re-run workflow
+
+But trusted publishing is better - let's get it working!

package/FIX_2FA_ISSUE.md

@@ -0,0 +1,81 @@
+# FIX: 2FA Blocking Trusted Publishing
+
+## The Problem
+
+Your workflow is failing with:
+```
+npm error code EOTP
+npm error This operation requires a one-time password from your authenticator.
+```
+
+This happens because your NPM account requires 2FA for publishing, which blocks OIDC authentication.
+
+## The Solution
+
+You need to **configure your package** to allow trusted publishers to bypass 2FA:
+
+### Step 1: Go to Package Settings
+
+Visit: https://www.npmjs.com/package/@anaclumos/taal/access
+
+### Step 2: Configure Publishing Access
+
+Scroll down to **"Publishing Access"** section.
+
+Select: **"Require two-factor authentication and disallow tokens"**
+
+![Publishing Access Settings](https://docs.npmjs.com/packages-and-modules/securing-your-code/trusted-publisher-security.png)
+
+This option:
+- ✅ **Allows** trusted publishers (OIDC) to publish without OTP
+- ❌ **Blocks** token-based authentication
+- ✅ **Maintains** security through OIDC
+
+### Step 3: Save
+
+Click **"Update Package Settings"** at the bottom.
+
+### Step 4: Test
+
+Re-run the failed workflow:
+```bash
+cd /Users/cho/Developer/taal
+gh run rerun 21076753514
+```
+
+Or create a new version:
+```bash
+npm version patch
+git push --follow-tags
+```
+
+## Why This Works
+
+When you select "Require two-factor authentication and disallow tokens":
+- Traditional token-based publishing is **blocked**
+- Trusted publishing via OIDC is **allowed** (no OTP needed)
+- Security is **enhanced** (OIDC is more secure than tokens + OTP)
+
+## Alternative (Less Secure)
+
+If the above doesn't work, you can temporarily disable 2FA requirement:
+
+1. Go to: https://www.npmjs.com/package/@anaclumos/taal/access
+2. Select: "Require two-factor authentication or automation/integration tokens (recommended)"
+3. Save
+
+**Note**: This is less secure. The first option is better.
+
+## Verification
+
+After configuration, the workflow should:
+1. ✅ Authenticate via OIDC (no OTP needed)
+2. ✅ Generate provenance automatically
+3. ✅ Publish successfully
+
+## Troubleshooting
+
+If it still fails:
+1. Check that trusted publisher is configured correctly (anaclumos/taal/publish.yml)
+2. Verify you saved the "Publishing Access" settings
+3. Check workflow logs: `gh run view --log-failed`

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/TRUSTED_PUBLISHING_SETUP.md

@@ -0,0 +1,87 @@
+# NPM Trusted Publishing Setup
+
+This project uses **NPM Trusted Publishing** with OIDC authentication - no NPM tokens needed!
+
+## What is Trusted Publishing?
+
+Trusted publishing uses OpenID Connect (OIDC) to authenticate GitHub Actions workflows directly with npm, eliminating the need for long-lived access tokens. This is more secure because:
+
+- No secrets to manage or rotate
+- Short-lived, workflow-specific credentials
+- Cannot be extracted or reused
+- Automatic provenance generation
+
+## Setup Instructions
+
+### Step 1: Configure Trusted Publisher on npmjs.com
+
+1. **Go to your package settings**:
+   - Visit: https://www.npmjs.com/package/@anaclumos/taal/access
+   - Or navigate to: npmjs.com → Your package → Settings → Publishing Access
+
+2. **Find "Trusted Publisher" section**
+
+3. **Click "GitHub Actions" button**
+
+4. **Fill in the configuration**:
+   - **Organization or user**: `anaclumos`
+   - **Repository**: `taal`
+   - **Workflow filename**: `publish.yml`
+   - **Environment name**: (leave empty)
+
+5. **Save the configuration**
+
+### Step 2: Verify Workflow Configuration
+
+The workflow is already configured correctly in `.github/workflows/publish.yml`:
+
+```yaml
+permissions:
+  id-token: write  # Required for OIDC
+  contents: read
+
+- run: npm publish --access public  # No NODE_AUTH_TOKEN needed!
+```
+
+### Step 3: Test Publishing
+
+Once you've configured the trusted publisher on npmjs.com:
+
+1. Create a new version tag:
+   ```bash
+   npm version patch
+   git push --follow-tags
+   ```
+
+2. GitHub Actions will automatically:
+   - Run tests and linter
+   - Publish to npm using OIDC
+   - Generate provenance attestations
+
+## Troubleshooting
+
+### "Unable to authenticate" error
+
+- Verify the workflow filename matches exactly: `publish.yml`
+- Check that all fields are correct (case-sensitive)
+- Ensure you're using GitHub-hosted runners (not self-hosted)
+- Confirm `id-token: write` permission is set
+
+### Workflow still failing
+
+- Check that you saved the trusted publisher configuration on npmjs.com
+- Verify the repository and organization names match exactly
+- Review the workflow logs for specific error messages
+
+## Benefits
+
+✅ **No secrets management** - No NPM_TOKEN to rotate or secure  
+✅ **Automatic provenance** - Cryptographic proof of package origin  
+✅ **Enhanced security** - Short-lived, scoped credentials  
+✅ **Simpler workflow** - Less configuration, fewer moving parts  
+
+## Learn More
+
+- [NPM Trusted Publishing Docs](https://docs.npmjs.com/trusted-publishers)
+- [GitHub OIDC Documentation](https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect)
+- [NPM Provenance](https://docs.npmjs.com/generating-provenance-statements)

package/package.json

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

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"
-          }
-        ]
-      }
-    ]
-  }
-}