specsmd 0.0.1

package/flows/aidlc/templates/standards/tech-stack.guide.md

@@ -0,0 +1,280 @@
+# Tech Stack Facilitation Guide
+
+## Purpose
+
+Define the technology choices that will guide code generation, architecture decisions, and ensure consistency across all AI agents working on the project.
+
+---
+
+## Facilitation Approach
+
+You are collaborating with a peer to discover their tech stack preferences. This is a conversation, not a form to fill out.
+
+**Adapt your style:**
+
+- If they mention specific technologies confidently → treat them as experienced, be concise
+- If they seem uncertain → provide more context, examples, and recommendations
+- If they have strong preferences → respect them, ask about tradeoffs they've considered
+
+**Your role:**
+
+- Guide discovery, don't dictate choices
+- Surface tradeoffs they may not have considered
+- Ensure choices are coherent (no conflicting technologies)
+- Capture rationale, not just the choice
+
+---
+
+## Discovery Areas
+
+### 1. Languages
+
+**Goal**: Understand what programming language(s) they'll use.
+
+**Open with context:**
+> "Let's start with languages. This affects everything else - framework options, available libraries, team hiring, and performance characteristics."
+
+**Explore:**
+
+- What languages is the team already comfortable with?
+- Are there languages they want to learn vs. use productively?
+- Is type safety important? (catches bugs early vs. development speed)
+- What's the runtime environment? (Browser, Node.js, Edge functions, Native)
+- Any organizational standards or constraints?
+
+**If they're unsure, guide by use case:**
+
+| Use Case | Recommendation | Why |
+|----------|----------------|-----|
+| Web app (full-stack) | TypeScript | Type safety, React/Next.js ecosystem, great tooling |
+| API service | TypeScript or Go | TS for ecosystem, Go for performance |
+| ML/AI/Data | Python | Libraries (PyTorch, pandas), community |
+| High-performance systems | Go or Rust | Go for simplicity, Rust for safety |
+| Scripts/automation | Python or TypeScript | Readability, quick iteration |
+
+**Common signals to listen for:**
+
+- "We're a React shop" → TypeScript
+- "We do ML/AI" → Python, possibly with TypeScript frontend
+- "Performance is critical" → Go, Rust, or optimized Node.js
+- "Small team, move fast" → TypeScript or Python
+- "Enterprise environment" → Java/Kotlin or TypeScript
+
+**Validate before moving on:**
+> "So we're going with {language}. This means {implication}. Sound right?"
+
+---
+
+### 2. Framework
+
+**Goal**: Understand their application framework choice.
+
+**Context to share:**
+> "Your framework shapes project structure, available patterns, and deployment options. It's one of the hardest things to change later."
+
+**Explore:**
+
+- What type of application? (Web app, API only, CLI, Mobile)
+- Do they need server-side rendering (SSR) or static generation (SSG)?
+- Is this a new project or adding to existing code?
+- Where will it be deployed? (This affects framework choice)
+- Any real-time requirements? (WebSockets, subscriptions)
+
+**Guide by language and use case:**
+
+**TypeScript - Web Applications:**
+
+| Framework | Best For | Tradeoffs |
+|-----------|----------|-----------|
+| Next.js | Full-stack, SSR/SSG, Vercel deployment | Opinionated, tied to React |
+| Remix | Web standards, nested routing, great DX | Smaller ecosystem |
+| Astro | Content-heavy sites, partial hydration | Less suited for highly interactive apps |
+| SvelteKit | Performance, smaller bundle, great DX | Smaller ecosystem than React |
+
+**TypeScript - API Only:**
+
+| Framework | Best For | Tradeoffs |
+|-----------|----------|-----------|
+| Fastify | Performance, low overhead | Less opinionated |
+| NestJS | Enterprise, structured, dependency injection | More boilerplate |
+| Hono | Edge functions, ultra-lightweight | Newer, smaller ecosystem |
+| Express | Simple, huge middleware ecosystem | Older patterns, callback-heavy |
+
+**Python - APIs:**
+
+| Framework | Best For | Tradeoffs |
+|-----------|----------|-----------|
+| FastAPI | Modern async, auto-docs, type hints | Async complexity |
+| Django | Batteries-included, ORM, admin | Heavier, monolithic |
+| Flask | Minimal, flexible | Need to add everything yourself |
+
+**Go - APIs:**
+
+| Framework | Best For | Tradeoffs |
+|-----------|----------|-----------|
+| Gin | Fast, popular, good docs | |
+| Echo | Similar to Gin, slightly different API | |
+| Chi | Lightweight, idiomatic Go | Less batteries included |
+| Standard library | Maximum control | More code to write |
+
+**Questions to surface tradeoffs:**
+
+- "Next.js is great but ties you to React. Is that okay?"
+- "FastAPI requires understanding async Python. Is the team comfortable with that?"
+- "NestJS has more structure but also more boilerplate. Do you prefer convention or flexibility?"
+
+---
+
+### 3. Authentication
+
+**Goal**: Understand authentication needs.
+
+**Optional - some projects don't need auth initially.**
+
+**Explore:**
+
+- Do they need user authentication?
+- What methods? (Email/password, social login, magic links, SSO)
+- Is this B2C (end users) or B2B (enterprise SSO)?
+- Any compliance requirements? (MFA, audit logs)
+
+**Options:**
+
+| Solution | Best For | Tradeoffs |
+|----------|----------|-----------|
+| Supabase Auth | Supabase users, quick setup | Tied to Supabase |
+| NextAuth.js | Next.js apps, flexible | Configuration complexity |
+| Clerk | Quick setup, beautiful UI | Cost at scale |
+| Auth0 | Enterprise, SSO | Cost, complexity |
+| Lucia | Lightweight, self-hosted | More DIY |
+| Custom | Full control | Security responsibility |
+
+**If using Supabase for database:**
+> "Since you're using Supabase for the database, Supabase Auth integrates seamlessly. It handles email/password, social providers, and row-level security. Worth considering unless you have specific needs."
+
+---
+
+### 4. Infrastructure & Deployment
+
+**Goal**: Understand how they'll deploy and operate.
+
+**Explore:**
+
+- Where do they want to deploy? (Cloud provider preference?)
+- Serverless vs. containers vs. VMs?
+- Who manages infrastructure? (Solo dev, dedicated DevOps, managed service)
+- Budget constraints?
+- Any existing infrastructure to integrate with?
+
+**Guide by context:**
+
+| Context | Recommendation | Why |
+|---------|----------------|-----|
+| Solo dev, startup | Vercel, Railway, Render | Minimal ops, fast deployment |
+| Next.js app | Vercel | Optimized for Next.js |
+| Need containers | Fly.io, Railway, Render | Simple container hosting |
+| Enterprise/compliance | AWS, GCP, Azure | Full control, compliance certifications |
+| Cost-sensitive at scale | Fly.io, self-managed k8s | Lower costs, more ops |
+| Already in AWS | AWS ecosystem | Consistency, existing knowledge |
+
+**Serverless vs. Containers:**
+
+- **Serverless** (Vercel, Lambda): Pay-per-use, auto-scaling, cold starts
+- **Containers** (Fly.io, ECS): Predictable performance, more control
+- **VMs** (EC2): Full control, predictable costs at scale
+
+---
+
+### 5. Package Manager
+
+**Goal**: Quick decision on package management.
+
+**For JavaScript/TypeScript:**
+
+| Manager | Best For |
+|---------|----------|
+| pnpm | Monorepos, disk efficiency, speed |
+| npm | Default, widest compatibility |
+| yarn | Existing yarn projects |
+| bun | Experimental, very fast |
+
+**Default recommendation:** pnpm (fast, efficient, great monorepo support)
+
+---
+
+## Completing the Discovery
+
+Once you've explored all relevant areas, summarize:
+
+```markdown
+## Tech Stack Summary
+
+Based on our conversation, here's what I understand:
+
+**Languages**: {choice}
+{brief rationale}
+
+**Framework**: {choice}
+{brief rationale}
+
+**Authentication**: {choice or "TBD"}
+{brief rationale if applicable}
+
+**Infrastructure**: {choice}
+{brief rationale}
+
+**Package Manager**: {choice}
+
+---
+
+Does this capture your tech stack accurately? Any adjustments needed?
+```
+
+---
+
+## Output Generation
+
+After confirmation, create `standards/tech-stack.md`:
+
+```markdown
+# Tech Stack
+
+## Overview
+{1-2 sentence summary of the stack and why it fits the project}
+
+## Languages
+{language(s)}
+
+{Rationale - why this choice, what it enables}
+
+## Framework
+{framework}
+
+{Rationale - why this choice, deployment implications}
+
+## Authentication
+{auth solution or "TBD"}
+
+{Rationale if selected}
+
+## Infrastructure & Deployment
+{infrastructure choice}
+
+{Rationale - deployment strategy, scaling approach}
+
+## Package Manager
+{package manager}
+
+## Decision Relationships
+{Note any important connections between choices}
+```
+
+---
+
+## Notes for Agent
+
+- **Don't ask all questions linearly** - adapt based on what they've already told you
+- **Skip irrelevant decisions** - CLI tools don't need authentication discussion
+- **Capture rationale** - "why" is as important as "what"
+- **Respect existing choices** - if they say "we're using X", don't try to change their mind unless there's a real issue
+- **It's okay to leave things TBD** - not every decision needs to be made upfront

package/lib/InstallerFactory.js

@@ -0,0 +1,36 @@
+const ClaudeInstaller = require('./installers/ClaudeInstaller');
+const CursorInstaller = require('./installers/CursorInstaller');
+const CopilotInstaller = require('./installers/CopilotInstaller');
+const AntigravityInstaller = require('./installers/AntigravityInstaller');
+const WindsurfInstaller = require('./installers/WindsurfInstaller');
+const ClineInstaller = require('./installers/ClineInstaller');
+const RooInstaller = require('./installers/RooInstaller');
+const KiroInstaller = require('./installers/KiroInstaller');
+const GeminiInstaller = require('./installers/GeminiInstaller');
+const CodexInstaller = require('./installers/CodexInstaller');
+const OpenCodeInstaller = require('./installers/OpenCodeInstaller');
+
+class InstallerFactory {
+    static getInstallers() {
+        return [
+            new ClaudeInstaller(),
+            new CursorInstaller(),
+            new CopilotInstaller(),
+            new AntigravityInstaller(),
+            new WindsurfInstaller(),
+            new ClineInstaller(),
+            new RooInstaller(),
+            new KiroInstaller(),
+            new GeminiInstaller(),
+            new CodexInstaller(),
+            new OpenCodeInstaller()
+        ];
+    }
+
+    static getInstaller(key) {
+        const installers = this.getInstallers();
+        return installers.find(i => i.key === key);
+    }
+}
+
+module.exports = InstallerFactory;

package/lib/cli-utils.js

@@ -0,0 +1,372 @@
+/**
+ * CLI Utilities for specsmd
+ */
+
+const chalk = require('chalk');
+const figlet = require('figlet');
+const gradient = require('gradient-string');
+const path = require('path');
+
+// Lazy load oh-my-logo (ESM module) via dynamic import
+let ohMyLogo = null;
+const getOhMyLogo = async () => {
+  if (!ohMyLogo) {
+    ohMyLogo = await import('oh-my-logo');
+  }
+  return ohMyLogo;
+};
+
+const { THEME_COLORS } = require('./constants');
+
+// Theme Colors (Terracotta/Orange inspired by Claude Code)
+const THEME = THEME_COLORS;
+
+// Create gradient for logo
+const logoGradient = gradient([THEME.primary, THEME.secondary]);
+
+// Theme chalk instances
+const theme = {
+  primary: chalk.hex(THEME.primary),
+  secondary: chalk.hex(THEME.secondary),
+  success: chalk.hex(THEME.success),
+  error: chalk.hex(THEME.error),
+  warning: chalk.hex(THEME.warning),
+  info: chalk.hex(THEME.info),
+  dim: chalk.hex(THEME.dim)
+};
+
+// Box drawing characters (Unicode)
+const BOX = {
+  topLeft: '╭',
+  topRight: '╮',
+  bottomLeft: '╰',
+  bottomRight: '╯',
+  horizontal: '─',
+  vertical: '│',
+  heavyHorizontal: '═',
+  heavyVertical: '║',
+  heavyTopLeft: '╔',
+  heavyTopRight: '╗',
+  heavyBottomLeft: '╚',
+  heavyBottomRight: '╝'
+};
+
+/**
+ * CLIUtils -
+ */
+const CLIUtils = {
+  /**
+   * Get package version
+   */
+  getVersion() {
+    try {
+      const packageJson = require(path.join(__dirname, '..', 'package.json'));
+      return packageJson.version || 'Unknown';
+    } catch {
+      return 'Unknown';
+    }
+  },
+
+  /**
+   * Get terminal width (capped at 80)
+   */
+  getWidth() {
+    return Math.min(process.stdout.columns || 80, 80);
+  },
+
+  /**
+   * Display the specs.md logo with gradient ASCII art (lowercase with shadow)
+   * Uses oh-my-logo for beautiful gradient rendering
+   * @param {boolean} clearScreen - Whether to clear screen first
+   */
+  async displayLogo(clearScreen = true) {
+    if (clearScreen) {
+      console.clear();
+    }
+
+    const version = this.getVersion();
+
+    console.log('');
+
+    try {
+      // Use oh-my-logo with custom orange palette and Standard font (lowercase)
+      const { render } = await getOhMyLogo();
+      const logo = await render('specs.md', {
+        palette: [THEME.primary, THEME.secondary, '#ffb380'],
+        font: 'Standard',
+        direction: 'horizontal'
+      });
+
+      console.log(logo);
+    } catch (err) {
+      // Fallback to figlet + gradient-string if oh-my-logo fails
+      const figletArt = figlet.textSync('specs.md', {
+        font: 'Standard',
+        horizontalLayout: 'default'
+      });
+      console.log(logoGradient(figletArt));
+    }
+
+    // Tagline with version
+    console.log(theme.primary(' AI-native development orchestration') + theme.primary.bold(` v${version}`) + '\n');
+  },
+
+  /**
+   * Display the specsmd logo synchronously using figlet (fallback)
+   * @param {boolean} clearScreen - Whether to clear screen first
+   */
+  displayLogoSync(clearScreen = true) {
+    if (clearScreen) {
+      console.clear();
+    }
+
+    const version = this.getVersion();
+
+    // Generate ASCII art with figlet
+    const figletArt = figlet.textSync('specs.md', {
+      font: 'Big',
+      horizontalLayout: 'default'
+    });
+
+    console.log('');
+    console.log(logoGradient(figletArt));
+
+    // Tagline with version
+    console.log(theme.primary(' AI-native development orchestration') + theme.primary.bold(` v${version}`) + '\n');
+  },
+
+  /**
+   * Display the logo using figlet (alternative style)
+   * @param {boolean} clearScreen - Whether to clear screen first
+   */
+  displayFigletLogo(clearScreen = true) {
+    if (clearScreen) {
+      console.clear();
+    }
+
+    const version = this.getVersion();
+    const art = figlet.textSync('specs.md', {
+      font: 'Big',
+      horizontalLayout: 'full'
+    });
+
+    console.log(logoGradient(art));
+    console.log(theme.dim(' AI-native development orchestration') + theme.primary.bold(` v${version}`) + '\n');
+  },
+
+  /**
+   * Display a section header with separator lines
+   * @param {string} title - Section title
+   * @param {string} subtitle - Optional subtitle
+   */
+  displaySection(title, subtitle = null) {
+    const width = this.getWidth();
+    const line = BOX.heavyHorizontal.repeat(width);
+
+    console.log('\n' + theme.primary(line));
+    console.log(theme.primary.bold(` ${title}`));
+    if (subtitle) {
+      console.log(theme.dim(` ${subtitle}`));
+    }
+    console.log(theme.primary(line) + '\n');
+  },
+
+  /**
+   * Display a header (lighter than section)
+   * @param {string} title - Header title
+   * @param {string} icon - Optional icon prefix
+   */
+  displayHeader(title, icon = '') {
+    const prefix = icon ? `${icon}  ` : '';
+    console.log('\n' + theme.primary.bold(`${prefix}${title}`));
+    console.log(theme.dim(BOX.horizontal.repeat(title.length + prefix.length)) + '\n');
+  },
+
+  /**
+   * Display a boxed message
+   * @param {string} content - Box content
+   * @param {object} options - Box options
+   */
+  displayBox(content, options = {}) {
+    const {
+      title = null,
+      borderColor = 'primary',
+      padding = 1,
+      width = null
+    } = options;
+
+    const boxWidth = width || Math.min(this.getWidth() - 4, 76);
+    const innerWidth = boxWidth - 2;
+    const colorFn = theme[borderColor] || theme.primary;
+
+    // Top border
+    let topBorder;
+    if (title) {
+      const titleStr = ` ${title} `;
+      const remainingWidth = boxWidth - titleStr.length - 2;
+      const leftPad = Math.floor(remainingWidth / 2);
+      const rightPad = remainingWidth - leftPad;
+      topBorder = colorFn(BOX.topLeft + BOX.horizontal.repeat(leftPad) + titleStr + BOX.horizontal.repeat(rightPad) + BOX.topRight);
+    } else {
+      topBorder = colorFn(BOX.topLeft + BOX.horizontal.repeat(boxWidth - 2) + BOX.topRight);
+    }
+    console.log(topBorder);
+
+    // Padding top
+    for (let i = 0; i < padding; i++) {
+      console.log(colorFn(BOX.vertical) + ' '.repeat(innerWidth) + colorFn(BOX.vertical));
+    }
+
+    // Content lines
+    const lines = content.split('\n');
+    for (const line of lines) {
+      const stripped = line.replace(/\u001b\[[0-9;]*m/g, ''); // Strip ANSI codes for length calculation
+      const paddedLine = line + ' '.repeat(Math.max(0, innerWidth - stripped.length));
+      console.log(colorFn(BOX.vertical) + paddedLine.slice(0, innerWidth) + colorFn(BOX.vertical));
+    }
+
+    // Padding bottom
+    for (let i = 0; i < padding; i++) {
+      console.log(colorFn(BOX.vertical) + ' '.repeat(innerWidth) + colorFn(BOX.vertical));
+    }
+
+    // Bottom border
+    console.log(colorFn(BOX.bottomLeft + BOX.horizontal.repeat(boxWidth - 2) + BOX.bottomRight));
+  },
+
+  /**
+   * Display a success message in a green box
+   * @param {string} message - Success message
+   * @param {string} title - Optional title
+   */
+  displaySuccess(message, title = 'Success') {
+    console.log('');
+    this.displayBox(theme.success(message), {
+      title,
+      borderColor: 'success',
+      padding: 0
+    });
+  },
+
+  /**
+   * Display an error message in a red box
+   * @param {string} message - Error message
+   * @param {string} title - Optional title
+   */
+  displayError(message, title = 'Error') {
+    console.log('');
+    this.displayBox(theme.error(message), {
+      title,
+      borderColor: 'error',
+      padding: 0
+    });
+  },
+
+  /**
+   * Display a warning message in an amber box
+   * @param {string} message - Warning message
+   * @param {string} title - Optional title
+   */
+  displayWarning(message, title = 'Warning') {
+    console.log('');
+    this.displayBox(theme.warning(message), {
+      title,
+      borderColor: 'warning',
+      padding: 0
+    });
+  },
+
+  /**
+   * Display an info message in a blue box
+   * @param {string} message - Info message
+   * @param {string} title - Optional title
+   */
+  displayInfo(message, title = 'Info') {
+    console.log('');
+    this.displayBox(theme.info(message), {
+      title,
+      borderColor: 'info',
+      padding: 0
+    });
+  },
+
+  /**
+   * Display current step progress
+   * @param {number} current - Current step
+   * @param {number} total - Total steps
+   * @param {string} description - Step description
+   */
+  displayStep(current, total, description) {
+    const progress = theme.primary.bold(`[${current}/${total}]`);
+    console.log(`${progress} ${description}`);
+  },
+
+  /**
+   * Display a completion message
+   * @param {string} message - Completion message
+   */
+  displayComplete(message) {
+    this.displaySuccess(message, 'Complete');
+  },
+
+  /**
+   * Display a simple status line
+   * @param {string} icon - Status icon
+   * @param {string} message - Status message
+   * @param {string} color - Color name
+   */
+  displayStatus(icon, message, color = 'primary') {
+    const colorFn = theme[color] || theme.primary;
+    console.log(`${colorFn(icon)} ${message}`);
+  },
+
+  /**
+   * Display a list of items
+   * @param {string[]} items - List items
+   * @param {string} bullet - Bullet character
+   */
+  displayList(items, bullet = '  -') {
+    for (const item of items) {
+      console.log(theme.dim(bullet) + ' ' + item);
+    }
+  },
+
+  /**
+   * Display next steps
+   * @param {string[]} steps - Array of step descriptions
+   */
+  displayNextSteps(steps) {
+    console.log(theme.dim('\nNext steps:'));
+    steps.forEach((step, index) => {
+      console.log(theme.dim(`  ${index + 1}. ${step}`));
+    });
+    console.log('');
+  },
+
+  /**
+   * Display a separator line
+   * @param {string} style - 'light' or 'heavy'
+   */
+  displaySeparator(style = 'light') {
+    const width = this.getWidth();
+    const char = style === 'heavy' ? BOX.heavyHorizontal : BOX.horizontal;
+    console.log(theme.dim(char.repeat(width)));
+  },
+
+  /**
+   * Theme colors for external use
+   */
+  theme,
+
+  /**
+   * Logo gradient for external use
+   */
+  logoGradient,
+
+  /**
+   * Box characters for external use
+   */
+  BOX
+};
+
+module.exports = CLIUtils;