axiom-coding-agent-setup 1.0.0 → 1.0.1

package/bin/cli.js

@@ -3,8 +3,8 @@
 /**
  * AXIOM Coding Agent Setup CLI
  * 
- * Downloads AGENTS.md and .axiom/ folder files from the GitHub repository
- * into the current project directory.
+ * Downloads AGENTS.md and .agents/ folder (core docs, templates, skills)
+ * from the GitHub repository into the current project directory.
  */
 
 const https = require('https');
@@ -16,10 +16,20 @@ const REPO_NAME = 'axiom-coding-agent-setup';
 const BRANCH = 'main';
 
 const FILES_TO_DOWNLOAD = [
+  // Main instructions
   'AGENTS.md',
-  '.axiom/engineering.md',
-  '.axiom/stack.md',
-  '.axiom/workflow.md'
+  // Core agent documents
+  '.agents/engineering.md',
+  '.agents/stack.md',
+  '.agents/workflow.md',
+  // Templates (project-type conventions)
+  '.agents/templates/ai-engineering-python.md',
+  '.agents/templates/fullstack-ai-nextjs.md',
+  // Skills (domain-specific guides)
+  '.agents/skills/mcp-builder/SKILL.md',
+  '.agents/skills/n8n-patterns/SKILL.md',
+  '.agents/skills/ai-integration/SKILL.md',
+  '.agents/skills/deployment-patterns/SKILL.md'
 ];
 
 const GITHUB_RAW_URL = `https://raw.githubusercontent.com/${REPO_OWNER}/${REPO_NAME}/${BRANCH}`;
@@ -112,10 +122,12 @@ async function main() {
 
   if (successCount > 0) {
     log('Your project now has AXIOM coding agent instructions:', 'bold');
-    log('  - AGENTS.md         → Main agent instructions', 'cyan');
-    log('  - .axiom/engineering.md → Engineering principles', 'cyan');
-    log('  - .axiom/stack.md       → Tech stack knowledge', 'cyan');
-    log('  - .axiom/workflow.md    → Workflow guidelines\n', 'cyan');
+    log('  - AGENTS.md                          → Main agent instructions', 'cyan');
+    log('  - .agents/engineering.md             → Engineering principles', 'cyan');
+    log('  - .agents/stack.md                   → Tech stack knowledge', 'cyan');
+    log('  - .agents/workflow.md                → Workflow guidelines', 'cyan');
+    log('  - .agents/templates/                 → Project-type conventions', 'cyan');
+    log('  - .agents/skills/                    → Domain-specific skills\n', 'cyan');
   }
 
   process.exit(failCount > 0 ? 1 : 0);

package/docs/npx-cli-setup-guide.md

@@ -0,0 +1,318 @@
+# npx CLI Package Setup Reference
+
+Quick reference for creating and publishing an npx CLI package that downloads files from a GitHub repository.
+
+---
+
+## Overview
+
+This pattern creates a CLI tool that can be run via `npx your-package-name` to download specific files from a GitHub repo into the current project directory.
+
+**Use case**: Distributing coding agent instructions, project templates, config files, etc.
+
+---
+
+## Step-by-Step Setup
+
+### 1. Create Project Structure
+
+```
+your-project/
+├── package.json          # npm package configuration
+├── bin/
+│   └── cli.js           # CLI entry point (Node.js script)
+└── README.md            # Documentation
+```
+
+### 2. Configure package.json
+
+```json
+{
+  "name": "your-package-name",
+  "version": "1.0.0",
+  "description": "Description of what this CLI does",
+  "main": "bin/cli.js",
+  "bin": {
+    "your-package-name": "bin/cli.js",
+    "short-alias": "bin/cli.js"
+  },
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "keywords": ["cli", "setup", "scaffold"],
+  "author": "your-github-username",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/username/repo-name.git"
+  },
+  "engines": {
+    "node": ">=14.0.0"
+  }
+}
+```
+
+**Key fields:**
+- `name`: Must be unique on npm (check availability first)
+- `bin`: Maps command names to the CLI script
+- `repository`: Links to your GitHub repo
+
+### 3. Create the CLI Script (bin/cli.js)
+
+Template for downloading files from GitHub raw content:
+
+```javascript
+#!/usr/bin/env node
+
+const https = require('https');
+const fs = require('fs');
+const path = require('path');
+
+const REPO_OWNER = 'your-github-username';
+const REPO_NAME = 'your-repo-name';
+const BRANCH = 'main';
+
+const FILES_TO_DOWNLOAD = [
+  'file1.md',
+  'folder/file2.md',
+  'folder/file3.md'
+];
+
+const GITHUB_RAW_URL = `https://raw.githubusercontent.com/${REPO_OWNER}/${REPO_NAME}/${BRANCH}`;
+
+function downloadFile(filePath) {
+  return new Promise((resolve, reject) => {
+    const url = `${GITHUB_RAW_URL}/${filePath}`;
+    const localPath = path.join(process.cwd(), filePath);
+    const dir = path.dirname(localPath);
+
+    // Create directory if it doesn't exist
+    if (!fs.existsSync(dir)) {
+      fs.mkdirSync(dir, { recursive: true });
+    }
+
+    const file = fs.createWriteStream(localPath);
+    
+    https.get(url, (response) => {
+      if (response.statusCode === 200) {
+        response.pipe(file);
+        file.on('finish', () => {
+          file.close();
+          resolve(filePath);
+        });
+      } else {
+        file.close();
+        if (fs.existsSync(localPath)) fs.unlinkSync(localPath);
+        reject(new Error(`Failed to download ${filePath}: ${response.statusCode}`));
+      }
+    }).on('error', (err) => {
+      if (fs.existsSync(localPath)) fs.unlinkSync(localPath);
+      reject(err);
+    });
+  });
+}
+
+async function main() {
+  console.log('Starting download...\n');
+  
+  for (const file of FILES_TO_DOWNLOAD) {
+    try {
+      process.stdout.write(`Downloading ${file}... `);
+      await downloadFile(file);
+      console.log('✓');
+    } catch (error) {
+      console.log(`✗ (${error.message})`);
+    }
+  }
+  
+  console.log('\nDone!');
+}
+
+main().catch(console.error);
+```
+
+### 4. Test Locally
+
+Before publishing, test the CLI locally:
+
+```bash
+node bin/cli.js
+```
+
+Or link it locally:
+
+```bash
+npm link
+your-package-name    # Test the command
+npm unlink           # Remove local link when done
+```
+
+### 5. Publish to npm
+
+#### First-time setup:
+
+1. **Create npm account**: https://www.npmjs.com/signup
+
+2. **Login from terminal**:
+   ```bash
+   npm login
+   ```
+
+3. **Publish**:
+   ```bash
+   npm publish
+   ```
+
+#### Check if published successfully:
+
+```bash
+npm view your-package-name
+```
+
+Or visit: `https://www.npmjs.com/package/your-package-name`
+
+---
+
+## Usage After Publishing
+
+Anyone can now use your CLI (no installation required):
+
+```bash
+npx your-package-name
+```
+
+Or install globally:
+
+```bash
+npm install -g your-package-name
+your-package-name    # Run directly
+```
+
+---
+
+## Updating Your Package
+
+### Updating Content Files (the downloaded files)
+
+Since files are downloaded directly from GitHub:
+
+1. Edit files locally
+2. Commit and push:
+   ```bash
+   git add .
+   git commit -m "Update instructions"
+   git push origin main
+   ```
+3. Done! Changes are live immediately (no npm publish needed)
+
+### Updating the CLI Script Itself
+
+If you modify `bin/cli.js` or `package.json`:
+
+1. Update version in `package.json`:
+   ```json
+   "version": "1.0.1"  // Increment version
+   ```
+
+2. Commit and push to GitHub:
+   ```bash
+   git add .
+   git commit -m "Fix download logic"
+   git push origin main
+   ```
+
+3. Republish to npm:
+   ```bash
+   npm publish
+   ```
+
+---
+
+## Version Management
+
+npm follows semantic versioning:
+
+| Version change | When to use |
+|----------------|-------------|
+| `1.0.0` → `1.0.1` | Bug fixes (patch) |
+| `1.0.0` → `1.1.0` | New features (minor) |
+| `1.0.0` → `2.0.0` | Breaking changes (major) |
+
+Update manually in `package.json` before republishing.
+
+---
+
+## Troubleshooting
+
+### 403 Forbidden when publishing
+- Package name might already exist on npm
+- Try a more unique name (e.g., `@username/package-name` for scoped packages)
+
+### 404 when downloading files
+- Check GitHub repo is public
+- Verify `REPO_OWNER` and `REPO_NAME` match your GitHub URL
+- Ensure files exist on the `main` branch
+
+### Command not found after publishing
+- Wait a few minutes for npm registry to propagate
+- Try `npx your-package-name@latest`
+
+### Local changes not reflected
+- Clear npx cache: `npx clear-npx-cache`
+- Or specify version: `npx your-package-name@1.0.1`
+
+---
+
+## Scoped Packages (Optional)
+
+If the package name is taken, use your username as a scope:
+
+```json
+{
+  "name": "@username/package-name"
+}
+```
+
+Publish with:
+```bash
+npm publish --access public
+```
+
+Use with:
+```bash
+npx @username/package-name
+```
+
+---
+
+## Quick Checklist
+
+- [ ] Create `package.json` with `bin` entry
+- [ ] Create `bin/cli.js` with shebang (`#!/usr/bin/env node`)
+- [ ] Set correct `REPO_OWNER`, `REPO_NAME`, and `FILES_TO_DOWNLOAD`
+- [ ] Test locally with `node bin/cli.js`
+- [ ] Create npm account
+- [ ] Run `npm login`
+- [ ] Run `npm publish`
+- [ ] Test with `npx your-package-name`
+
+---
+
+## Example Commands Reference
+
+```bash
+# Setup
+npm login                                    # Login to npm
+npm publish                                  # Publish package
+npm version patch                            # Bump version (1.0.0 → 1.0.1)
+
+# Maintenance  
+npm view your-package-name                   # Check package info
+npm unpublish your-package-name@version      # Remove specific version
+npm deprecate your-package-name@version      # Deprecate version
+
+# Usage
+npx your-package-name                        # Run via npx
+npx your-package-name@latest                 # Force latest version
+npx clear-npx-cache                          # Clear npx cache
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "axiom-coding-agent-setup",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "CLI tool to download AXIOM coding agent setup files into your project",
   "main": "bin/cli.js",
   "bin": {
@@ -26,4 +26,4 @@
   "engines": {
     "node": ">=14.0.0"
   }
-}
+}