Core Lightstack CLI foundation (init, up, down commands)

.claude/commands/plan.md

@@ -0,0 +1,36 @@
+---
+description: Execute the implementation planning workflow using the plan template to generate design artifacts.
+---
+
+Given the implementation details provided as an argument, do this:
+
+1. Run `.specify/scripts/powershell/setup-plan.ps1 -Json` from the repo root and parse JSON for FEATURE_SPEC, IMPL_PLAN, SPECS_DIR, BRANCH. All future file paths must be absolute.
+2. Read and analyze the feature specification to understand:
+   - The feature requirements and user stories
+   - Functional and non-functional requirements
+   - Success criteria and acceptance criteria
+   - Any technical constraints or dependencies mentioned
+
+3. Read the constitution at `.specify/memory/constitution.md` to understand constitutional requirements.
+
+4. Execute the implementation plan template:
+   - Load `.specify/templates/plan-template.md` (already copied to IMPL_PLAN path)
+   - Set Input path to FEATURE_SPEC
+   - Run the Execution Flow (main) function steps 1-9
+   - The template is self-contained and executable
+   - Follow error handling and gate checks as specified
+   - Let the template guide artifact generation in $SPECS_DIR:
+     * Phase 0 generates research.md
+     * Phase 1 generates data-model.md, contracts/, quickstart.md
+     * Phase 2 generates tasks.md
+   - Incorporate user-provided details from arguments into Technical Context: $ARGUMENTS
+   - Update Progress Tracking as you complete each phase
+
+5. Verify execution completed:
+   - Check Progress Tracking shows all phases complete
+   - Ensure all required artifacts were generated
+   - Confirm no ERROR states in execution
+
+6. Report results with branch name, file paths, and generated artifacts.
+
+Use absolute paths with the repository root for all file operations to avoid path issues.

.claude/commands/specify.md

@@ -0,0 +1,12 @@
+---
+description: Create or update the feature specification from a natural language feature description.
+---
+
+Given the feature description provided as an argument, do this:
+
+1. Run the script `.specify/scripts/powershell/create-new-feature.ps1 -Json "$ARGUMENTS"` from repo root and parse its JSON output for BRANCH_NAME and SPEC_FILE. All file paths must be absolute.
+2. Load `.specify/templates/spec-template.md` to understand required sections.
+3. Write the specification to SPEC_FILE using the template structure, replacing placeholders with concrete details derived from the feature description (arguments) while preserving section order and headings.
+4. Report completion with branch name, spec file path, and readiness for the next phase.
+
+Note: The script creates and checks out the new branch and initializes the spec file before writing.

.claude/commands/tasks.md

@@ -0,0 +1,58 @@
+---
+description: Generate an actionable, dependency-ordered tasks.md for the feature based on available design artifacts.
+---
+
+Given the context provided as an argument, do this:
+
+1. Run `.specify/scripts/powershell/check-task-prerequisites.ps1 -Json` from repo root and parse FEATURE_DIR and AVAILABLE_DOCS list. All paths must be absolute.
+2. Load and analyze available design documents:
+   - Always read plan.md for tech stack and libraries
+   - IF EXISTS: Read data-model.md for entities
+   - IF EXISTS: Read contracts/ for API endpoints
+   - IF EXISTS: Read research.md for technical decisions
+   - IF EXISTS: Read quickstart.md for test scenarios
+
+   Note: Not all projects have all documents. For example:
+   - CLI tools might not have contracts/
+   - Simple libraries might not need data-model.md
+   - Generate tasks based on what's available
+
+3. Generate tasks following the template:
+   - Use `.specify/templates/tasks-template.md` as the base
+   - Replace example tasks with actual tasks based on:
+     * **Setup tasks**: Project init, dependencies, linting
+     * **Test tasks [P]**: One per contract, one per integration scenario
+     * **Core tasks**: One per entity, service, CLI command, endpoint
+     * **Integration tasks**: DB connections, middleware, logging
+     * **Polish tasks [P]**: Unit tests, performance, docs
+
+4. Task generation rules:
+   - Each contract file → contract test task marked [P]
+   - Each entity in data-model → model creation task marked [P]
+   - Each endpoint → implementation task (not parallel if shared files)
+   - Each user story → integration test marked [P]
+   - Different files = can be parallel [P]
+   - Same file = sequential (no [P])
+
+5. Order tasks by dependencies:
+   - Setup before everything
+   - Tests before implementation (TDD)
+   - Models before services
+   - Services before endpoints
+   - Core before integration
+   - Everything before polish
+
+6. Include parallel execution examples:
+   - Group [P] tasks that can run together
+   - Show actual Task agent commands
+
+7. Create FEATURE_DIR/tasks.md with:
+   - Correct feature name from implementation plan
+   - Numbered tasks (T001, T002, etc.)
+   - Clear file paths for each task
+   - Dependency notes
+   - Parallel execution guidance
+
+Context for task generation: $ARGUMENTS
+
+The tasks.md should be immediately executable - each task must be specific enough that an LLM can complete it without additional context.

.eslintrc.json

@@ -0,0 +1,47 @@
+{
+  "parser": "@typescript-eslint/parser",
+  "extends": [
+    "eslint:recommended",
+    "plugin:@typescript-eslint/recommended",
+    "plugin:@typescript-eslint/recommended-requiring-type-checking",
+    "prettier"
+  ],
+  "plugins": ["@typescript-eslint"],
+  "parserOptions": {
+    "ecmaVersion": 2022,
+    "sourceType": "module",
+    "project": "./tsconfig.json"
+  },
+  "root": true,
+  "env": {
+    "node": true,
+    "es2022": true
+  },
+  "rules": {
+    "@typescript-eslint/explicit-function-return-type": "off",
+    "@typescript-eslint/explicit-module-boundary-types": "off",
+    "@typescript-eslint/no-explicit-any": "error",
+    "@typescript-eslint/no-unused-vars": ["error", { "argsIgnorePattern": "^_" }],
+    "@typescript-eslint/consistent-type-imports": "error",
+    "no-console": ["warn", { "allow": ["warn", "error", "log"] }]
+  },
+  "overrides": [
+    {
+      "files": ["src/cli.ts", "src/commands/**/*"],
+      "rules": {
+        "no-console": "off"
+      }
+    },
+    {
+      "files": ["tests/**/*"],
+      "rules": {
+        "@typescript-eslint/no-explicit-any": "off",
+        "@typescript-eslint/no-unsafe-assignment": "off",
+        "@typescript-eslint/no-unsafe-member-access": "off",
+        "@typescript-eslint/no-unsafe-argument": "off",
+        "no-console": "off"
+      }
+    }
+  ],
+  "ignorePatterns": ["dist", "node_modules", "*.js", "*.cjs", "*.mjs"]
+}

.github/workflows/test.yml

@@ -0,0 +1,48 @@
+name: Test
+
+on:
+  push:
+    branches: [ main, develop ]
+  pull_request:
+    branches: [ main, develop ]
+
+jobs:
+  test:
+    name: Test on ${{ matrix.os }} with Node ${{ matrix.node }}
+    runs-on: ${{ matrix.os }}
+
+    strategy:
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        node: [20, 22]
+      fail-fast: false
+
+    steps:
+    - name: Checkout code
+      uses: actions/checkout@v4
+
+    - name: Setup Node.js
+      uses: actions/setup-node@v4
+      with:
+        node-version: ${{ matrix.node }}
+
+    - name: Setup Bun
+      uses: oven-sh/setup-bun@v1
+      with:
+        bun-version: latest
+
+    - name: Install dependencies
+      run: bun install
+
+    - name: Run lint
+      run: bun run lint
+
+    - name: Run type check
+      run: bun run typecheck
+
+    - name: Build project
+      run: bun run build
+
+    - name: Run unit tests
+      run: bun run vitest run
+

.gitignore

@@ -0,0 +1,50 @@
+# Dependencies
+node_modules/
+.pnp
+.pnp.js
+
+# Build outputs
+dist/
+*.tsbuildinfo
+
+# Testing
+coverage/
+*.lcov
+.nyc_output
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+.DS_Store
+
+# Environment
+.env
+.env.local
+.env.*.local
+
+# Logs
+logs/
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+
+# Bun
+bun.lockb
+
+# Documentation build
+docs/.vitepress/dist/
+docs/.vitepress/cache/
+
+# Temporary files
+*.tmp
+.light/
+.cache/
+
+# OS files
+Thumbs.db
+desktop.ini

.prettierrc.json

@@ -0,0 +1,10 @@
+{
+  "semi": true,
+  "trailingComma": "all",
+  "singleQuote": true,
+  "printWidth": 100,
+  "tabWidth": 2,
+  "useTabs": false,
+  "arrowParens": "always",
+  "endOfLine": "lf"
+}

.specify/memory/constitution.md

@@ -0,0 +1,78 @@
+# Lightstack CLI Constitution
+
+## Core Principles
+
+### I. Don't Reinvent the Wheel (NON-NEGOTIABLE)
+- Use existing, battle-tested tools for complex tasks
+- Traefik/Caddy for reverse proxy and SSL
+- Docker for containerization
+- mkcert for local certificates
+- Established CLI frameworks for argument parsing
+- If a tool does it well, orchestrate it, don't reimplement it
+
+### II. Configuration Over Code
+- Generate configuration files for existing tools
+- Users can understand and modify what we generate
+- No hidden magic or black boxes
+- All generated files are version-controllable
+
+### III. Single Responsibility
+- The CLI orchestrates; it doesn't try to be everything
+- Each command does one thing well
+- Complex operations are compositions of simple ones
+- Leave specialized work to specialized tools
+
+### IV. Fail Fast, Fail Clearly
+- Validate prerequisites before starting operations
+- Error messages must include what went wrong AND how to fix it
+- No silent failures or cryptic errors
+- Exit codes follow standard conventions
+
+### V. Progressive Disclosure
+- Start with smart defaults that work for 80% of cases
+- Allow overrides for power users
+- Hide complexity behind `--advanced` flags
+- Quickstart in <5 minutes, mastery when needed
+
+## Development Principles
+
+### VI. Stand on Shoulders of Giants
+- Use established libraries over custom implementations
+- Follow existing CLI conventions (--help, --version, etc.)
+- Adopt industry standards for config files
+- Learn from successful CLIs (npm, docker, git)
+
+### VII. Idempotent Operations
+- Running a command twice has the same effect as running it once
+- Always check current state before making changes
+- Support --dry-run for destructive operations
+- Make operations resumable after failures
+
+### VIII. Environment Awareness
+- Respect CI environment variables
+- Honor NO_COLOR and other accessibility standards
+- Detect and adapt to platform differences
+- Work offline when possible
+
+## Quality Standards
+
+### IX. Developer Experience First
+- Every error suggests a solution
+- Progress feedback for long operations
+- Verbose mode for debugging
+- Commands are guessable and memorable
+
+### X. Maintainability
+- Code should be obvious, not clever
+- Documentation lives next to code
+- Tests prove the feature works
+- Refactor when complexity grows
+
+## Governance
+
+- Constitution supersedes all implementation decisions
+- Violations must be justified in writing
+- Amendments require clear rationale and migration path
+- Simplicity wins in disputes
+
+**Version**: 1.0.0 | **Ratified**: 2025-09-18 | **Last Amended**: N/A