@axiomatic-labs/cli 1.0.0

package/bin/cli.js

@@ -0,0 +1,39 @@
+#!/usr/bin/env node
+
+const command = process.argv[2];
+
+switch (command) {
+  case 'init':
+    require('../lib/init.js')();
+    break;
+  case 'update':
+    require('../lib/update.js')();
+    break;
+  case 'version':
+    require('../lib/version.js')();
+    break;
+  case '--version':
+  case '-v':
+    console.log(`@axiomatic-labs/cli v${require('../package.json').version}`);
+    break;
+  case '--help':
+  case '-h':
+  case undefined:
+    console.log(`
+  axiomatic - Install and update Axiomatic project templates
+
+  Usage:
+    axiomatic init      Download and install the latest template files
+    axiomatic update    Update template files to the latest version
+    axiomatic version   Show local and latest version info
+
+  Options:
+    --version, -v       Show CLI version
+    --help, -h          Show this help message
+`);
+    break;
+  default:
+    console.error(`Unknown command: ${command}`);
+    console.error('Run "axiomatic --help" for usage.');
+    process.exit(1);
+}

package/lib/auth.js

@@ -0,0 +1,32 @@
+const { execSync } = require('child_process');
+
+function getGitHubToken() {
+  // Try gh CLI first
+  try {
+    const token = execSync('gh auth token', { encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'] }).trim();
+    if (token) return token;
+  } catch {}
+
+  // Fall back to GITHUB_TOKEN env var
+  if (process.env.GITHUB_TOKEN) {
+    return process.env.GITHUB_TOKEN;
+  }
+
+  return null;
+}
+
+function requireAuth() {
+  const token = getGitHubToken();
+  if (!token) {
+    console.error('GitHub authentication required.\n');
+    console.error('Option 1: Install the GitHub CLI and authenticate:');
+    console.error('  brew install gh && gh auth login\n');
+    console.error('Option 2: Set a GitHub Personal Access Token:');
+    console.error('  export GITHUB_TOKEN=ghp_your_token_here\n');
+    console.error('The token needs read access to axiomatic-labs/axiomatic-cli releases.');
+    process.exit(1);
+  }
+  return token;
+}
+
+module.exports = { getGitHubToken, requireAuth };

package/lib/download.js

@@ -0,0 +1,99 @@
+const https = require('https');
+const { execSync } = require('child_process');
+
+const OWNER = 'axiomatic-labs';
+const REPO = 'axiomatic-cli';
+
+function githubApi(path, token) {
+  return new Promise((resolve, reject) => {
+    const options = {
+      hostname: 'api.github.com',
+      path,
+      headers: {
+        'User-Agent': '@axiomatic-labs/cli',
+        'Authorization': `Bearer ${token}`,
+        'Accept': 'application/vnd.github+json',
+      },
+    };
+
+    https.get(options, (res) => {
+      // Follow redirects
+      if (res.statusCode >= 300 && res.statusCode < 400 && res.headers.location) {
+        return fetchUrl(res.headers.location).then(resolve).catch(reject);
+      }
+
+      if (res.statusCode !== 200) {
+        let body = '';
+        res.on('data', (d) => body += d);
+        res.on('end', () => reject(new Error(`GitHub API ${res.statusCode}: ${body}`)));
+        return;
+      }
+
+      const chunks = [];
+      res.on('data', (d) => chunks.push(d));
+      res.on('end', () => {
+        try {
+          resolve(JSON.parse(Buffer.concat(chunks).toString()));
+        } catch (e) {
+          reject(e);
+        }
+      });
+    }).on('error', reject);
+  });
+}
+
+function fetchUrl(url) {
+  return new Promise((resolve, reject) => {
+    const mod = url.startsWith('https') ? https : require('http');
+    mod.get(url, { headers: { 'User-Agent': '@axiomatic-labs/cli' } }, (res) => {
+      if (res.statusCode >= 300 && res.statusCode < 400 && res.headers.location) {
+        return fetchUrl(res.headers.location).then(resolve).catch(reject);
+      }
+      if (res.statusCode !== 200) {
+        return reject(new Error(`HTTP ${res.statusCode} fetching ${url}`));
+      }
+      const chunks = [];
+      res.on('data', (d) => chunks.push(d));
+      res.on('end', () => resolve(Buffer.concat(chunks)));
+    }).on('error', reject);
+  });
+}
+
+async function getLatestRelease(token) {
+  return githubApi(`/repos/${OWNER}/${REPO}/releases/latest`, token);
+}
+
+async function downloadReleaseAsset(asset, token) {
+  // Use the GitHub API URL with Accept header for binary
+  return new Promise((resolve, reject) => {
+    const options = {
+      hostname: 'api.github.com',
+      path: `/repos/${OWNER}/${REPO}/releases/assets/${asset.id}`,
+      headers: {
+        'User-Agent': '@axiomatic-labs/cli',
+        'Authorization': `Bearer ${token}`,
+        'Accept': 'application/octet-stream',
+      },
+    };
+
+    https.get(options, (res) => {
+      // GitHub redirects to a CDN URL for the actual binary
+      if (res.statusCode >= 300 && res.statusCode < 400 && res.headers.location) {
+        return fetchUrl(res.headers.location).then(resolve).catch(reject);
+      }
+
+      if (res.statusCode !== 200) {
+        let body = '';
+        res.on('data', (d) => body += d);
+        res.on('end', () => reject(new Error(`Asset download failed ${res.statusCode}: ${body}`)));
+        return;
+      }
+
+      const chunks = [];
+      res.on('data', (d) => chunks.push(d));
+      res.on('end', () => resolve(Buffer.concat(chunks)));
+    }).on('error', reject);
+  });
+}
+
+module.exports = { getLatestRelease, downloadReleaseAsset, OWNER, REPO };

package/lib/init.js

@@ -0,0 +1,55 @@
+const fs = require('fs');
+const path = require('path');
+const { execSync } = require('child_process');
+const { requireAuth } = require('./auth.js');
+const { getLatestRelease, downloadReleaseAsset } = require('./download.js');
+const { writeLocalVersion } = require('./version.js');
+
+async function run() {
+  // Check if already initialized
+  const versionFile = path.join(process.cwd(), '.claude', '.axiomatic-version');
+  if (fs.existsSync(versionFile)) {
+    const current = fs.readFileSync(versionFile, 'utf-8').trim();
+    console.error(`Already initialized at ${current}. Use "axiomatic update" instead.`);
+    process.exit(1);
+  }
+
+  console.log('Authenticating with GitHub...');
+  const token = requireAuth();
+
+  console.log('Fetching latest release...');
+  const release = await getLatestRelease(token);
+  const version = release.tag_name;
+
+  // Find the ZIP asset
+  const asset = release.assets.find((a) => a.name.endsWith('.zip'));
+  if (!asset) {
+    console.error('No ZIP asset found in the latest release.');
+    process.exit(1);
+  }
+
+  console.log(`Downloading ${asset.name} (${version})...`);
+  const zipBuffer = await downloadReleaseAsset(asset, token);
+
+  // Write ZIP to temp file and extract
+  const tmpZip = path.join(require('os').tmpdir(), `axiomatic-${Date.now()}.zip`);
+  fs.writeFileSync(tmpZip, zipBuffer);
+
+  try {
+    console.log('Extracting template files...');
+    execSync(`unzip -o "${tmpZip}" -d "${process.cwd()}"`, { stdio: 'pipe' });
+  } finally {
+    fs.unlinkSync(tmpZip);
+  }
+
+  // Ensure .claude/tmp exists
+  fs.mkdirSync(path.join(process.cwd(), '.claude', 'tmp'), { recursive: true });
+
+  // Write version file
+  writeLocalVersion(version);
+
+  console.log(`\nAxiomatic ${version} installed.`);
+  console.log('Run: claude, then /build');
+}
+
+module.exports = run;

package/lib/manifest.js

@@ -0,0 +1,69 @@
+// Canonical list of template files — mirrors build-zip.sh.
+// Only these files are managed by init/update. Everything else is user-generated.
+
+const TEMPLATE_SKILLS = [
+  'build',
+  'review',
+  'setup',
+  'brand-strategy',
+  'competitive-analysis',
+  'content-strategy',
+  'design-specification',
+  'information-architecture',
+  'logo-design',
+  'ux-wireframes',
+  'visual-design-direction',
+];
+
+const TEMPLATE_AGENTS = [
+  'brand-strategy.md',
+  'competitive-analysis.md',
+  'content-strategy.md',
+  'cro-layout.md',
+  'design-mockup.md',
+  'design-specification.md',
+  'generate-skill.md',
+  'information-architecture.md',
+  'logo-design.md',
+  'ux-wireframes.md',
+  'visual-design-direction.md',
+];
+
+// Build the full list of relative paths that belong to the template
+function getTemplatePaths() {
+  const paths = [
+    'CLAUDE.md',
+    '.claude/settings.json',
+    '.claude/docs/quality-gate-protocol.md',
+  ];
+
+  for (const skill of TEMPLATE_SKILLS) {
+    paths.push(`.claude/skills/${skill}/SKILL.md`);
+  }
+
+  for (const agent of TEMPLATE_AGENTS) {
+    paths.push(`.claude/agents/${agent}`);
+  }
+
+  // Hooks — all .js files are template-managed
+  // (matched dynamically during extraction since we don't know filenames ahead of time)
+
+  return paths;
+}
+
+// Check if a path from the ZIP is a template file
+function isTemplatePath(relativePath) {
+  // Exact match for known files
+  const known = getTemplatePaths();
+  if (known.includes(relativePath)) return true;
+
+  // All hooks/*.js files are template-managed
+  if (relativePath.startsWith('.claude/hooks/') && relativePath.endsWith('.js')) return true;
+
+  // .axiomatic-version is also managed
+  if (relativePath === '.claude/.axiomatic-version') return true;
+
+  return false;
+}
+
+module.exports = { TEMPLATE_SKILLS, TEMPLATE_AGENTS, getTemplatePaths, isTemplatePath };

package/lib/update.js

@@ -0,0 +1,87 @@
+const fs = require('fs');
+const path = require('path');
+const { execSync } = require('child_process');
+const { requireAuth } = require('./auth.js');
+const { getLatestRelease, downloadReleaseAsset } = require('./download.js');
+const { readLocalVersion, writeLocalVersion } = require('./version.js');
+const { isTemplatePath } = require('./manifest.js');
+
+async function run() {
+  const current = readLocalVersion();
+  if (!current) {
+    console.error('Not initialized. Run "axiomatic init" first.');
+    process.exit(1);
+  }
+
+  console.log('Authenticating with GitHub...');
+  const token = requireAuth();
+
+  console.log('Fetching latest release...');
+  const release = await getLatestRelease(token);
+  const latest = release.tag_name;
+
+  if (current === latest) {
+    console.log(`Already up to date (${current}).`);
+    return;
+  }
+
+  console.log(`Updating ${current} -> ${latest}`);
+
+  // Find the ZIP asset
+  const asset = release.assets.find((a) => a.name.endsWith('.zip'));
+  if (!asset) {
+    console.error('No ZIP asset found in the latest release.');
+    process.exit(1);
+  }
+
+  console.log(`Downloading ${asset.name}...`);
+  const zipBuffer = await downloadReleaseAsset(asset, token);
+
+  // Write ZIP to temp file
+  const tmpZip = path.join(require('os').tmpdir(), `axiomatic-${Date.now()}.zip`);
+  const tmpDir = path.join(require('os').tmpdir(), `axiomatic-extract-${Date.now()}`);
+  fs.writeFileSync(tmpZip, zipBuffer);
+
+  try {
+    // Extract to temp directory first
+    fs.mkdirSync(tmpDir, { recursive: true });
+    execSync(`unzip -o "${tmpZip}" -d "${tmpDir}"`, { stdio: 'pipe' });
+
+    // Copy only template files
+    const updated = [];
+    copyTemplateFiles(tmpDir, process.cwd(), '', updated);
+
+    // Write version file
+    writeLocalVersion(latest);
+
+    console.log(`\nUpdated ${current} -> ${latest}`);
+    if (updated.length > 0) {
+      console.log(`\nUpdated files:`);
+      for (const f of updated) {
+        console.log(`  ${f}`);
+      }
+    }
+    console.log('\nRestart CLI to apply agent changes.');
+  } finally {
+    fs.unlinkSync(tmpZip);
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  }
+}
+
+function copyTemplateFiles(srcDir, destDir, prefix, updated) {
+  const entries = fs.readdirSync(path.join(srcDir, prefix), { withFileTypes: true });
+  for (const entry of entries) {
+    const relative = prefix ? `${prefix}/${entry.name}` : entry.name;
+    if (entry.isDirectory()) {
+      copyTemplateFiles(srcDir, destDir, relative, updated);
+    } else if (isTemplatePath(relative)) {
+      const src = path.join(srcDir, relative);
+      const dest = path.join(destDir, relative);
+      fs.mkdirSync(path.dirname(dest), { recursive: true });
+      fs.copyFileSync(src, dest);
+      updated.push(relative);
+    }
+  }
+}
+
+module.exports = run;

package/lib/version.js

@@ -0,0 +1,57 @@
+const fs = require('fs');
+const path = require('path');
+const { getGitHubToken } = require('./auth.js');
+const { getLatestRelease } = require('./download.js');
+
+const VERSION_FILE = path.join(process.cwd(), '.claude', '.axiomatic-version');
+
+function readLocalVersion() {
+  try {
+    return fs.readFileSync(VERSION_FILE, 'utf-8').trim();
+  } catch {
+    return null;
+  }
+}
+
+function writeLocalVersion(version) {
+  const dir = path.dirname(VERSION_FILE);
+  fs.mkdirSync(dir, { recursive: true });
+  fs.writeFileSync(VERSION_FILE, version + '\n');
+}
+
+async function run() {
+  const cliVersion = require('../package.json').version;
+  const local = readLocalVersion();
+
+  console.log(`CLI:   v${cliVersion}`);
+
+  if (local) {
+    console.log(`Local: ${local}`);
+  } else {
+    console.log('Local: not installed (run "axiomatic init" first)');
+  }
+
+  const token = getGitHubToken();
+  if (!token) {
+    console.log('Latest: (authenticate with GitHub to check)');
+    return;
+  }
+
+  try {
+    const release = await getLatestRelease(token);
+    const latest = release.tag_name;
+    console.log(`Latest: ${latest}`);
+
+    if (local && local === latest) {
+      console.log('\nUp to date.');
+    } else if (local) {
+      console.log('\nUpdate available. Run: axiomatic update');
+    }
+  } catch (err) {
+    console.error(`\nCould not fetch latest release: ${err.message}`);
+  }
+}
+
+module.exports = run;
+module.exports.readLocalVersion = readLocalVersion;
+module.exports.writeLocalVersion = writeLocalVersion;

package/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "@axiomatic-labs/cli",
+  "version": "1.0.0",
+  "description": "CLI for installing and updating Axiomatic project templates",
+  "bin": {
+    "axiomatic": "./bin/cli.js"
+  },
+  "files": [
+    "bin/",
+    "lib/"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/axiomatic-labs/axiomatic-cli.git"
+  },
+  "license": "UNLICENSED",
+  "private": false
+}