octo-dev 0.2.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 congeant
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,270 @@
+<p align="center">
+  <img src="https://img.shields.io/badge/node-%3E%3D25-brightgreen" alt="Node.js >= 25" />
+  <img src="https://img.shields.io/badge/typescript-5.8-blue" alt="TypeScript" />
+  <img src="https://img.shields.io/badge/license-MIT-green" alt="License" />
+  <img src="https://img.shields.io/badge/pnpm-11-orange" alt="pnpm" />
+</p>
+
+<h1 align="center">🐙 Octo</h1>
+
+<p align="center">
+  <strong>Build orchestration, semantic versioning, and local infrastructure management for monorepos.</strong>
+</p>
+
+<p align="center">
+  <code>octo build</code> · <code>octo bump</code> · <code>octo up</code> · <code>octo down</code> · <code>octo status</code>
+</p>
+
+---
+
+## Why Octo?
+
+Managing a monorepo with multiple microservices and shared packages means dealing with:
+
+- **Manual build ordering** — services depend on shared packages that must be built first
+- **Version drift** — bumping a shared SDK requires updating every consumer by hand
+- **Infrastructure sprawl** — each service has its own `docker-compose.yml` with overlapping containers
+
+Octo solves all three with a single CLI that understands your dependency graph.
+
+---
+
+## Quick Start
+
+```bash
+# Install globally
+pnpm add -g octo-monorepo
+
+# Initialize in your monorepo
+octo init
+
+# Build everything in dependency order
+octo build
+
+# Bump a shared package and propagate
+octo bump @myorg/shared-lib minor --install
+
+# Spin up all infrastructure
+octo up
+```
+
+---
+
+## Requirements
+
+| Tool | Version |
+|------|---------|
+| Node.js | >= 25 |
+| Docker | Latest |
+| Git | >= 2.x |
+| pnpm | >= 11 |
+
+---
+
+## Commands
+
+### `octo init`
+
+Scans the monorepo, discovers services (directories with `Dockerfile`) and packages, and generates `octo.yaml`.
+
+```bash
+octo init                # Recursive scan, generates root manifest
+octo init --standalone   # Current directory only
+```
+
+---
+
+### `octo graph`
+
+Displays the dependency graph as an indented adjacency list.
+
+```bash
+$ octo graph
+
+api-gateway
+  @myorg/shared-lib
+  @myorg/config
+user-service
+  @myorg/shared-lib
+@myorg/shared-lib
+@myorg/config
+```
+
+---
+
+### `octo build`
+
+Orchestrates Docker builds respecting topological order with maximum parallelism.
+
+```bash
+octo build                # Build all services
+octo build api-gateway    # Build api-gateway + modified dependencies
+octo build --affected     # Build only changed services since last build
+```
+
+**Features:**
+- Parallel execution limited by available CPUs
+- Failure propagation — if a dependency fails, dependents are cancelled
+- Independent services continue building
+- Real-time progress reporting (updated every 1s)
+- Affected detection via file mtime comparison
+
+---
+
+### `octo bump`
+
+Increments a package version following [Semantic Versioning 2.0.0](https://semver.org/).
+
+```bash
+octo bump @myorg/shared-lib           # patch (default)
+octo bump @myorg/shared-lib minor     # minor
+octo bump @myorg/shared-lib major     # major
+octo bump @myorg/shared-lib --install # also runs pnpm install in consumers
+```
+
+**Pipeline:**
+
+```
+pre-bump hooks → version increment → build verification → changelog → git commit → propagation
+```
+
+**Safety guarantees:**
+- Uncommitted changes trigger interactive confirmation
+- Build failure triggers automatic rollback (byte-for-byte)
+- Incompatible version ranges are skipped with conflict report
+
+---
+
+### `octo up`
+
+Merges all `docker-compose.yml` files and starts infrastructure containers.
+
+```bash
+octo up              # All infrastructure
+octo up user-service # Only user-service's dependencies
+```
+
+**Features:**
+- Smart merge via local LLM (Phi-4/Ollama) for deduplication
+- Deterministic fallback when LLM is unavailable
+- Healthcheck polling (60s timeout per container)
+- Automatic log tail on healthcheck failure
+
+---
+
+### `octo down`
+
+Stops and removes infrastructure containers.
+
+```bash
+octo down              # Stop containers, preserve volumes
+octo down --volumes    # Also remove persistent volumes
+```
+
+---
+
+### `octo status`
+
+Displays container state in tabular format.
+
+```bash
+$ octo status
+
+NAME                           IMAGE                               STATE        PORT
+my-postgres                    postgres:16                         running      5432:5432
+my-redis                       redis:7-alpine                      running      6379:6379
+my-nats                        nats:2.10                           running      4222:4222
+```
+
+---
+
+## Configuration
+
+### `octo.yaml`
+
+```yaml
+# Pre-validation hooks (run before build/bump)
+hooks:
+  pre-build:
+    - name: lint
+      command: pnpm run lint
+    - name: type-check
+      command: pnpm run type-check
+  pre-bump:
+    - name: lint
+      command: pnpm run lint
+
+# Services — directories with Dockerfile
+services:
+  - api-gateway
+  - user-service
+  - billing-service
+
+# Shared packages — libraries consumed by services
+packages:
+  - "@myorg/shared-lib"
+  - "@myorg/config"
+```
+
+### Path Resolution
+
+By default, Octo resolves paths automatically by searching for a directory whose `package.json` `name` field matches the entry. To override:
+
+```yaml
+services:
+  - api-gateway:
+      path: ./custom/gateway-dir
+```
+
+### Dependency Detection
+
+Dependencies are resolved automatically from `package.json` fields (`dependencies` + `devDependencies`). Only internal packages (those declared in the manifest) create graph edges. External npm packages are ignored.
+
+---
+
+## Operating Modes
+
+| Mode | Trigger | Behavior |
+|------|---------|----------|
+| **Standalone** | Single `octo.yaml` in CWD | Operates on local manifest only |
+| **Aggregated** | Multiple `octo.yaml` in subdirectories | Discovers all manifests, builds unified dependency graph with cross-project resolution |
+
+In aggregated mode, if a root `octo.yaml` exists alongside sub-manifests, the root takes priority.
+
+---
+
+## Graceful Shutdown
+
+Octo handles `SIGINT` (Ctrl+C) and `SIGTERM` gracefully:
+
+1. Cancels builds in progress
+2. Reports partial state (completed / in-progress / pending)
+3. Exits with code 130
+
+---
+
+## Error Handling
+
+All errors follow a consistent format:
+
+```
+[ERRO] <category>: <descriptive message>
+  → <additional context (path, line, column)>
+  → <suggested fix when applicable>
+```
+
+| Category | Behavior | Exit Code |
+|----------|----------|-----------|
+| Configuration error | Reports all problems at once | 1 |
+| Dependency cycle | Reports cycle path `A -> B -> ... -> A` | 1 |
+| Hook failure | Aborts operation, shows hook output | 1 |
+| Build failure | Cancels dependents, continues independents | 1 |
+| Version rollback | Automatic on build failure post-bump | 1 |
+| Infrastructure timeout | Shows last 20 log lines | 1 |
+| Unknown YAML keys | Warning on stderr, continues | 0 |
+
+---
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "octo-dev",
+  "version": "0.2.2",
+  "description": "CLI for monorepo build orchestration, semantic versioning, and local infrastructure management",
+  "type": "module",
+  "license": "MIT",
+  "author": "congeant",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/congeant/octo.git"
+  },
+  "homepage": "https://github.com/congeant/octo#readme",
+  "bugs": {
+    "url": "https://github.com/congeant/octo/issues"
+  },
+  "keywords": [
+    "cli",
+    "monorepo",
+    "build",
+    "orchestration",
+    "docker",
+    "semver",
+    "versioning",
+    "infrastructure",
+    "dependency-graph",
+    "topological-sort"
+  ],
+  "bin": {
+    "octo": "./src/cli/index.ts"
+  },
+  "files": [
+    "src/",
+    "scripts/",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "dev": "tsx src/cli/index.ts",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "eslint src/",
+    "type-check": "tsc --noEmit"
+  },
+  "dependencies": {
+    "commander": "^13.1.0",
+    "ollama": "^0.5.16",
+    "semver": "^7.7.2",
+    "tsx": "^4.19.4",
+    "yaml": "^2.7.1",
+    "zod": "^3.25.67"
+  },
+  "devDependencies": {
+    "@types/node": "^22.15.0",
+    "@types/semver": "^7.7.0",
+    "fast-check": "^4.1.1",
+    "typescript": "^5.8.3",
+    "vitest": "^3.2.4"
+  },
+  "engines": {
+    "node": ">=25.0.0"
+  }
+}

package/scripts/install.sh

@@ -0,0 +1,117 @@
+#!/usr/bin/env bash
+# Octo CLI — Installer
+# Usage: curl -fsSL https://raw.githubusercontent.com/congeant/octo/main/scripts/install.sh | sh
+
+set -euo pipefail
+
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[0;33m'
+NC='\033[0m'
+
+info()  { printf "${GREEN}[INFO]${NC} %s\n" "$1"; }
+warn()  { printf "${YELLOW}[AVISO]${NC} %s\n" "$1"; }
+error() { printf "${RED}[ERRO]${NC} %s\n" "$1"; }
+
+missing=()
+
+# Check Node.js >= 25
+check_node() {
+  if ! command -v node &>/dev/null; then
+    missing+=("node")
+    error "Node.js não encontrado"
+    echo "  → Instale via: https://nodejs.org/ ou use nvm:"
+    echo "    curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash"
+    echo "    nvm install 25"
+    return
+  fi
+
+  local version
+  version=$(node --version | sed 's/^v//')
+  local major
+  major=$(echo "$version" | cut -d. -f1)
+
+  if [ "$major" -lt 25 ]; then
+    missing+=("node")
+    error "Node.js >= 25 necessário (encontrado: v${version})"
+    echo "  → Atualize via nvm: nvm install 25"
+  else
+    info "Node.js v${version} ✓"
+  fi
+}
+
+# Check Docker
+check_docker() {
+  if ! command -v docker &>/dev/null; then
+    missing+=("docker")
+    error "Docker não encontrado"
+    echo "  → Instale via: https://docs.docker.com/get-docker/"
+  else
+    local version
+    version=$(docker --version | grep -oE '[0-9]+\.[0-9]+\.[0-9]+' | head -1)
+    info "Docker v${version} ✓"
+  fi
+}
+
+# Check Git
+check_git() {
+  if ! command -v git &>/dev/null; then
+    missing+=("git")
+    error "Git não encontrado"
+    echo "  → Instale via: https://git-scm.com/downloads"
+  else
+    local version
+    version=$(git --version | grep -oE '[0-9]+\.[0-9]+\.[0-9]+' | head -1)
+    info "Git v${version} ✓"
+  fi
+}
+
+# Check pnpm
+check_pnpm() {
+  if ! command -v pnpm &>/dev/null; then
+    missing+=("pnpm")
+    error "pnpm não encontrado"
+    echo "  → Instale via: corepack enable && corepack prepare pnpm@latest --activate"
+    echo "    ou: npm install -g pnpm"
+  else
+    local version
+    version=$(pnpm --version)
+    info "pnpm v${version} ✓"
+  fi
+}
+
+main() {
+  echo ""
+  echo "╔══════════════════════════════════════╗"
+  echo "║       Octo CLI — Installer          ║"
+  echo "╚══════════════════════════════════════╝"
+  echo ""
+
+  info "Verificando pré-requisitos..."
+  echo ""
+
+  check_node
+  check_docker
+  check_git
+  check_pnpm
+
+  echo ""
+
+  if [ ${#missing[@]} -gt 0 ]; then
+    error "Pré-requisitos faltantes: ${missing[*]}"
+    echo ""
+    echo "Instale os itens acima e execute novamente."
+    exit 1
+  fi
+
+  info "Todos os pré-requisitos atendidos."
+  info "Instalando @spectre/octo globalmente..."
+  echo ""
+
+  pnpm add -g @spectre/octo
+
+  echo ""
+  info "Instalação concluída. Verifique com: octo --version"
+}
+
+main

package/src/build/adapters/docker-build-engine.adapter.ts

@@ -0,0 +1,39 @@
+import { run } from '../../shared/process-runner.js';
+import type { BuildEngine, BuildTarget, BuildEngineResult } from '../ports/build-engine.port.js';
+
+/** Adapter — Docker build engine via CLI */
+export class DockerBuildEngine implements BuildEngine {
+  name = 'docker';
+
+  async build(target: BuildTarget): Promise<BuildEngineResult> {
+    const context = target.context ?? target.path;
+    const start = Date.now();
+
+    const result = await run('docker', ['build', '-f', target.buildFile, context], {
+      cwd: target.path,
+    });
+
+    const durationMs = Date.now() - start;
+    const output = (result.stdout + result.stderr).trim();
+
+    return {
+      success: result.exitCode === 0,
+      output,
+      durationMs,
+    };
+  }
+
+  async isAvailable(): Promise<boolean> {
+    try {
+      const result = await run('docker', ['--version'], { timeout: 5_000 });
+      return result.exitCode === 0;
+    } catch {
+      return false;
+    }
+  }
+
+  detect(buildFile: string): boolean {
+    const name = buildFile.split('/').pop() ?? buildFile;
+    return name === 'Dockerfile' || name.startsWith('Dockerfile.');
+  }
+}

package/src/build/affected-detector.ts

@@ -0,0 +1,126 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import type { DependencyGraph } from '../graph/dependency-graph.js';
+
+const CACHE_FILE = '.octo-cache.json';
+
+interface CacheData {
+  builds: Record<string, number>;
+}
+
+export interface AffectedDetector {
+  detect(graph: DependencyGraph, rootDir: string): Promise<string[]>;
+  recordBuild(names: string[], rootDir: string): Promise<void>;
+}
+
+async function readCache(rootDir: string): Promise<CacheData | null> {
+  try {
+    const content = await fs.readFile(path.join(rootDir, CACHE_FILE), 'utf-8');
+    return JSON.parse(content) as CacheData;
+  } catch {
+    return null;
+  }
+}
+
+async function writeCache(rootDir: string, data: CacheData): Promise<void> {
+  await fs.writeFile(path.join(rootDir, CACHE_FILE), JSON.stringify(data, null, 2));
+}
+
+/** Get the latest mtime of any file in a directory (recursive, skipping node_modules/dist) */
+async function getLatestMtime(dir: string): Promise<number> {
+  let latest = 0;
+
+  let entries: string[];
+  try {
+    entries = await fs.readdir(dir);
+  } catch {
+    return 0;
+  }
+
+  for (const name of entries) {
+    if (name === 'node_modules' || name === 'dist' || name.startsWith('.')) {
+      continue;
+    }
+
+    const fullPath = path.join(dir, name);
+    const stat = await fs.stat(fullPath);
+
+    if (stat.isDirectory()) {
+      const sub = await getLatestMtime(fullPath);
+      if (sub > latest) latest = sub;
+    } else {
+      if (stat.mtimeMs > latest) latest = stat.mtimeMs;
+    }
+  }
+
+  return latest;
+}
+
+/** Calculate transitive closure of dependents for a set of modified nodes */
+function getTransitiveDependents(modified: Set<string>, graph: DependencyGraph): Set<string> {
+  const affected = new Set<string>(modified);
+  const queue = [...modified];
+
+  while (queue.length > 0) {
+    const current = queue.shift()!;
+    for (const dep of graph.getDependents(current)) {
+      if (!affected.has(dep)) {
+        affected.add(dep);
+        queue.push(dep);
+      }
+    }
+  }
+
+  return affected;
+}
+
+export function createAffectedDetector(): AffectedDetector {
+  return {
+    async detect(graph, rootDir) {
+      const cache = await readCache(rootDir);
+      const allNames = graph.getNodeNames();
+
+      // No previous build → all affected
+      if (!cache || Object.keys(cache.builds).length === 0) {
+        return allNames;
+      }
+
+      // Find directly modified nodes
+      const modified = new Set<string>();
+
+      for (const name of allNames) {
+        const node = graph.getNode(name);
+        if (!node) continue;
+
+        const lastBuild = cache.builds[name];
+        if (lastBuild === undefined) {
+          // Never built → affected
+          modified.add(name);
+          continue;
+        }
+
+        const latestMtime = await getLatestMtime(node.path);
+        if (latestMtime > lastBuild) {
+          modified.add(name);
+        }
+      }
+
+      if (modified.size === 0) return [];
+
+      // Transitive closure
+      const affected = getTransitiveDependents(modified, graph);
+      return [...affected];
+    },
+
+    async recordBuild(names, rootDir) {
+      const cache = await readCache(rootDir) ?? { builds: {} };
+      const now = Date.now();
+
+      for (const name of names) {
+        cache.builds[name] = now;
+      }
+
+      await writeCache(rootDir, cache);
+    },
+  };
+}