octo-dev 0.5.4 → 0.6.0

package/README.md

@@ -8,7 +8,7 @@
 <h1 align="center">🐙 Octo</h1>
 
 <p align="center">
-  <strong>Build orchestration, semantic versioning, and local infrastructure management for monorepos.</strong>
+  <strong>Build orchestration, semantic versioning, and local infrastructure management for repository workspaces.</strong>
 </p>
 
 <p align="center">
@@ -19,7 +19,7 @@
 
 ## Why Octo?
 
-Managing a monorepo with multiple microservices and shared packages means dealing with:
+Managing a workspace with multiple repositories, 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
@@ -33,9 +33,9 @@ Octo solves all three with a single CLI that understands your dependency graph.
 
 ```bash
 # Install globally
-pnpm add -g octo-monorepo
+npm install -g octo-dev
 
-# Initialize in your monorepo
+# Initialize in your workspace
 octo init
 
 # Build everything in dependency order
@@ -65,7 +65,7 @@ octo up
 
 ### `octo init`
 
-Scans the monorepo, discovers services (directories with `Dockerfile`) and packages, and generates `octo.yaml`.
+Scans the workspace, discovers services (directories with `Dockerfile`) and packages, and generates `octo.yaml`.
 
 ```bash
 octo init                # Recursive scan, generates root manifest

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "octo-dev",
-  "version": "0.5.4",
-  "description": "CLI for monorepo build orchestration, semantic versioning, and local infrastructure management",
+  "version": "0.6.0",
+  "description": "Build orchestration, semantic versioning, and local infrastructure management for repository workspaces",
   "type": "module",
   "license": "MIT",
   "author": "congeant",
@@ -15,7 +15,7 @@
   },
   "keywords": [
     "cli",
-    "monorepo",
+    "workspace",
     "build",
     "orchestration",
     "docker",

package/src/build/build-orchestrator.ts

@@ -4,13 +4,12 @@ import { onShutdown } from '../shared/shutdown.js';
 import { runHooks } from '../hooks/hook-runner.js';
 import type { HookContext } from '../hooks/hook-runner.js';
 import type { DependencyGraph } from '../graph/dependency-graph.js';
-import type { BuildEngine, BuildEngineRegistry, BuildTarget } from './ports/build-engine.port.js';
+import type { BuildEngineRegistry, BuildTarget } from './ports/build-engine.port.js';
 import type { OctoManifest } from '../manifest/manifest-schema.js';
 import {
   createBuildScheduler,
   type BuildResult,
   type BuildProgress,
-  type BuildStatus,
 } from './build-scheduler.js';
 
 export interface BuildOptions {

package/src/build/build-scheduler.ts

@@ -161,11 +161,6 @@ export function createBuildScheduler(): BuildScheduler {
         clearInterval(progressInterval);
       }
 
-      const success = [...results.values()].every(
-        (r) => r.status === 'success' || r.status === 'cancelled',
-      ) && [...results.values()].some((r) => r.status === 'success');
-
-      // Overall success: no failures
       const hasFailure = [...results.values()].some((r) => r.status === 'failure');
 
       return { success: !hasFailure, results };

package/src/cli/down.command.ts

@@ -25,7 +25,7 @@ export async function downCommand(opts: { volumes?: boolean }): Promise<void> {
     .map((name) => graph.getNode(name)?.path)
     .filter((p): p is string => !!p);
 
-  const manager = createInfraManager(servicePaths);
+  const manager = createInfraManager(servicePaths, rootDir);
   const result = await manager.down({ volumes: opts.volumes });
 
   if (!result.success) {

package/src/cli/index.ts

@@ -10,12 +10,12 @@ const program = new Command();
 
 program
   .name('octo')
-  .description('Monorepo build orchestration, versioning, and infrastructure CLI')
-  .version('0.5.4');
+  .description('Build orchestration, semantic versioning, and local infrastructure management for repository workspaces')
+  .version('0.6.0');
 
 program
   .command('init')
-  .description('Scan the monorepo and generate octo.yaml')
+  .description('Scan the workspace and generate octo.yaml')
   .option('--standalone', 'Generate manifest for the current project only')
   .action(async (opts) => {
     const { initCommand } = await import('./init.command.js');
@@ -32,7 +32,7 @@ program
 
 program
   .command('build [service]')
-  .description('Build monorepo services')
+  .description('Build workspace services')
   .option('--affected', 'Build only affected services')
   .action(async (service, opts) => {
     const { buildCommand } = await import('./build.command.js');

package/src/cli/status.command.ts

@@ -25,16 +25,16 @@ export async function statusCommand(): Promise<void> {
     .map((name) => graph.getNode(name)?.path)
     .filter((p): p is string => !!p);
 
-  const manager = createInfraManager(servicePaths);
+  const manager = createInfraManager(servicePaths, rootDir);
   const containers = await manager.status();
 
   if (containers.length === 0) {
-    logger.info('Nenhum container em execução.');
+    logger.info('No containers running.');
     return;
   }
 
   // Print table header
-  const header = `${'NOME'.padEnd(30)} ${'IMAGEM'.padEnd(35)} ${'ESTADO'.padEnd(12)} PORTA`;
+  const header = `${'NAME'.padEnd(30)} ${'IMAGE'.padEnd(35)} ${'STATE'.padEnd(12)} PORT`;
   console.log(header);
   console.log('-'.repeat(header.length));
 

package/src/cli/up.command.ts

@@ -41,7 +41,7 @@ export async function upCommand(service?: string): Promise<void> {
     .map((name) => graph.getNode(name)?.path)
     .filter((p): p is string => !!p);
 
-  const manager = createInfraManager(servicePaths);
+  const manager = createInfraManager(servicePaths, rootDir);
   const result = await manager.up(targetServices);
 
   if (!result.success) {

package/src/infra/infra-manager.ts

@@ -1,12 +1,11 @@
-import { writeFile } from 'node:fs/promises';
+import { readFile, writeFile } from 'node:fs/promises';
+import { createHash } from 'node:crypto';
 import { join } from 'node:path';
-import { tmpdir } from 'node:os';
 import { stringify } from 'yaml';
 import { run } from '../shared/process-runner.js';
 import { logger } from '../shared/logger.js';
-import { OctoError } from '../shared/errors.js';
 import { createComposeSmartMerger } from './compose-smart-merger.js';
-import { createComposeAggregator, type MergedCompose } from './compose-aggregator.js';
+import { createComposeAggregator, type DiscoveredCompose, type MergedCompose } from './compose-aggregator.js';
 
 export type ContainerState = 'running' | 'stopped' | 'unhealthy';
 
@@ -30,126 +29,261 @@ export interface InfraManager {
 
 const HEALTHCHECK_TIMEOUT_MS = 60_000;
 const HEALTHCHECK_POLL_MS = 2_000;
+const CHECKSUM_FILE = '.octo-compose-checksum';
 
-/** Write merged compose to a temp file and return its path */
-async function writeTempCompose(merged: MergedCompose): Promise<string> {
-  const tempPath = join(tmpdir(), `octo-compose-${Date.now()}.yml`);
+// --- Checksum ---
+
+/**
+ * Computes a SHA-256 checksum from the combined content of all discovered compose files.
+ * Files are sorted by path to ensure deterministic output regardless of discovery order.
+ *
+ * @param discovered - Array of discovered compose file entries with path and content.
+ * @returns Hex-encoded SHA-256 hash string.
+ */
+async function computeChecksum(discovered: DiscoveredCompose[]): Promise<string> {
+  const hash = createHash('sha256');
+  for (const entry of discovered.sort((a, b) => a.path.localeCompare(b.path))) {
+    const content = await readFile(entry.path, 'utf-8');
+    hash.update(content);
+  }
+  return hash.digest('hex');
+}
+
+/**
+ * Reads the previously stored checksum from disk.
+ *
+ * @param rootDir - Workspace root directory containing the checksum file.
+ * @returns The stored checksum string, or null if the file does not exist.
+ */
+async function readStoredChecksum(rootDir: string): Promise<string | null> {
+  try {
+    return (await readFile(join(rootDir, CHECKSUM_FILE), 'utf-8')).trim();
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Persists the current checksum to disk for future comparison.
+ *
+ * @param rootDir - Workspace root directory where the checksum file is stored.
+ * @param checksum - The SHA-256 hex string to persist.
+ */
+async function writeChecksum(rootDir: string, checksum: string): Promise<void> {
+  await writeFile(join(rootDir, CHECKSUM_FILE), checksum, 'utf-8');
+}
+
+// --- Compose output ---
+
+/**
+ * Serializes a merged compose object to YAML and writes it to `docker-compose.yml` in the project root.
+ *
+ * @param merged - The unified compose structure (services, networks, volumes).
+ * @param rootDir - Workspace root directory where the file is written.
+ * @returns Absolute path to the written `docker-compose.yml`.
+ */
+async function writeMergedCompose(merged: MergedCompose, rootDir: string): Promise<string> {
+  const outputPath = join(rootDir, 'docker-compose.yml');
   const content = stringify(merged);
-  await writeFile(tempPath, content, 'utf-8');
-  return tempPath;
+  await writeFile(outputPath, content, 'utf-8');
+  logger.info(`Merged compose written to ${outputPath}`);
+  return outputPath;
 }
 
-/** Poll healthcheck for a container, returns true if healthy within timeout */
+// --- Healthcheck ---
+
+/**
+ * Polls a container's health status via `docker inspect` until healthy, unhealthy, or timeout.
+ * Containers without a healthcheck defined are considered healthy immediately.
+ *
+ * @param containerName - Full Docker container name (e.g. "project-db-1").
+ * @returns `true` if container is healthy or has no healthcheck; `false` if unhealthy or timed out.
+ */
 async function waitForHealthcheck(containerName: string): Promise<boolean> {
   const start = Date.now();
   while (Date.now() - start < HEALTHCHECK_TIMEOUT_MS) {
     const result = await run('docker', [
       'inspect', '--format', '{{if .State.Health}}{{.State.Health.Status}}{{else}}none{{end}}', containerName,
     ]);
+    if (result.exitCode !== 0) return true;
     const status = result.stdout.trim();
+    if (status.includes('unhealthy')) return false;
     if (status === 'healthy' || status === 'none') return true;
-    if (status === 'unhealthy') return false;
     await new Promise((r) => setTimeout(r, HEALTHCHECK_POLL_MS));
   }
   return false;
 }
 
-/** Show last 20 lines of container log */
+/**
+ * Outputs the last 20 log lines of a container to stderr for debugging failed healthchecks.
+ *
+ * @param containerName - Full Docker container name to retrieve logs from.
+ */
 async function showContainerLogs(containerName: string): Promise<void> {
   const result = await run('docker', ['logs', '--tail', '20', containerName]);
   const output = result.stdout || result.stderr;
-  if (output) logger.error(`Last 20 lines of log (${containerName}):\n${output}`);
+  if (output) logger.error(`Container "${containerName}" recent logs:\n${output}`);
+}
+
+// --- Resolve compose path ---
+
+/**
+ * Determines which compose file to use for docker operations.
+ *
+ * - Single compose file: returns its path directly (no merge needed).
+ * - Multiple compose files: compares SHA-256 checksum against stored value.
+ *   If checksums match and the merged file exists, reuses it (cache hit).
+ *   If checksums differ or merged file is missing, triggers a re-merge.
+ *
+ * @param discovered - Array of discovered compose files from service directories.
+ * @param rootDir - Workspace root where merged output and checksum are stored.
+ * @param smartMerger - Smart merger instance for deduplication and LLM-assisted merge.
+ * @returns Absolute path to the compose file to use with `docker compose -f`.
+ */
+async function resolveComposePath(
+  discovered: DiscoveredCompose[],
+  rootDir: string,
+  smartMerger: ReturnType<typeof createComposeSmartMerger>,
+): Promise<string> {
+  if (discovered.length === 1) {
+    return discovered[0].path;
+  }
+
+  const currentChecksum = await computeChecksum(discovered);
+  const storedChecksum = await readStoredChecksum(rootDir);
+  const mergedPath = join(rootDir, 'docker-compose.yml');
+
+  if (currentChecksum === storedChecksum) {
+    try {
+      await readFile(mergedPath, 'utf-8');
+      logger.info('Compose files unchanged — using cached docker-compose.yml');
+      return mergedPath;
+    } catch {
+      // Merged file missing despite matching checksum — re-merge below
+    }
+  }
+
+  logger.info(`Found ${discovered.length} compose files with changes — merging into unified docker-compose.yml`);
+  const merged = await smartMerger.deduplicate(discovered);
+  const outputPath = await writeMergedCompose(merged, rootDir);
+  await writeChecksum(rootDir, currentChecksum);
+  return outputPath;
 }
 
-export function createInfraManager(servicePaths: string[]): InfraManager {
+// --- Manager ---
+
+/**
+ * Creates an infrastructure manager that handles docker compose operations for the workspace.
+ *
+ * @param servicePaths - Array of absolute paths to service directories (each may contain a docker-compose.yml).
+ * @param rootDir - Workspace root directory for merged compose output and checksum storage.
+ * @returns An InfraManager instance with `up`, `down`, and `status` methods.
+ */
+export function createInfraManager(servicePaths: string[], rootDir: string): InfraManager {
   const aggregator = createComposeAggregator();
   const smartMerger = createComposeSmartMerger();
-  let composePath: string | undefined;
 
   return {
+    /**
+     * Starts containers defined in the workspace's compose file(s).
+     * Discovers compose files, resolves/merges if needed, runs `docker compose up -d`,
+     * and waits for all container healthchecks to pass.
+     *
+     * @param services - Optional list of service names to filter. If empty, starts all.
+     * @returns Result indicating success/failure with a descriptive message.
+     */
     async up(services?: string[]): Promise<InfraResult> {
-      const paths = services && services.length > 0
+      const paths = services?.length
         ? servicePaths.filter((p) => services.some((s) => p.endsWith(s)))
         : servicePaths;
 
       const discovered = aggregator.discover(paths);
       if (discovered.length === 0) {
-        return { success: true, message: 'Nenhum docker-compose.yml encontrado.' };
+        return { success: true, message: 'No docker-compose.yml found in any service directory.' };
       }
 
-      logger.info(`Discovered ${discovered.length} compose file(s). Merging...`);
-      const merged = await smartMerger.deduplicate(discovered);
-      composePath = await writeTempCompose(merged);
+      const composePath = await resolveComposePath(discovered, rootDir, smartMerger);
 
-      logger.info('Starting containers...');
+      logger.info('Starting containers with docker compose...');
       const result = await run('docker', ['compose', '-f', composePath, 'up', '-d']);
       if (result.exitCode !== 0) {
-        return { success: false, message: `docker compose up falhou: ${result.stderr}` };
+        return {
+          success: false,
+          message: `Failed to start containers. docker compose exited with code ${result.exitCode}:\n${result.stderr.trim()}`,
+        };
       }
 
-      // Wait for healthchecks
-      const serviceNames = Object.keys(merged.services);
-      for (const svc of serviceNames) {
-        const healthy = await waitForHealthcheck(svc);
+      const psResult = await run('docker', ['compose', '-f', composePath, 'ps', '--format', '{{.Name}}']);
+      const containerNames = psResult.stdout.trim().split('\n').filter(Boolean);
+
+      for (const container of containerNames) {
+        const healthy = await waitForHealthcheck(container);
         if (!healthy) {
-          logger.error(`Healthcheck timeout for container "${svc}".`);
-          await showContainerLogs(svc);
-          // Stop dependents but don't tear down everything
-          return { success: false, message: `Healthcheck timeout: ${svc}` };
+          logger.error(`Container "${container}" failed healthcheck after ${HEALTHCHECK_TIMEOUT_MS / 1000}s.`);
+          await showContainerLogs(container);
+          return { success: false, message: `Healthcheck failed for "${container}". Check logs above for details.` };
         }
       }
 
-      return { success: true, message: `${serviceNames.length} container(s) iniciado(s).` };
+      return { success: true, message: `All ${containerNames.length} container(s) are up and healthy.` };
     },
 
+    /**
+     * Stops all containers managed by the workspace's compose file.
+     * Optionally removes associated volumes.
+     *
+     * @param options - `{ volumes: true }` to also remove Docker volumes on teardown.
+     * @returns Result indicating success/failure with a descriptive message.
+     */
     async down(options: { volumes?: boolean }): Promise<InfraResult> {
-      // Discover and merge to get the compose file path
-      if (!composePath) {
-        const discovered = aggregator.discover(servicePaths);
-        if (discovered.length === 0) {
-          return { success: true, message: 'Nenhum container para parar.' };
-        }
-        const merged = await smartMerger.deduplicate(discovered);
-        composePath = await writeTempCompose(merged);
+      const discovered = aggregator.discover(servicePaths);
+      if (discovered.length === 0) {
+        return { success: true, message: 'No compose files found — nothing to stop.' };
       }
 
+      const composePath = await resolveComposePath(discovered, rootDir, smartMerger);
       const args = ['compose', '-f', composePath, 'down'];
       if (options.volumes) args.push('--volumes');
 
       const result = await run('docker', args);
       if (result.exitCode !== 0) {
-        return { success: false, message: `docker compose down falhou: ${result.stderr}` };
+        return {
+          success: false,
+          message: `Failed to stop containers. docker compose exited with code ${result.exitCode}:\n${result.stderr.trim()}`,
+        };
       }
 
-      return { success: true, message: 'Containers parados.' };
+      return { success: true, message: options.volumes ? 'All containers stopped and volumes removed.' : 'All containers stopped.' };
     },
 
+    /**
+     * Retrieves the current status of all containers managed by the workspace's compose file.
+     * Parses `docker compose ps --format json` output into structured ContainerStatus objects.
+     *
+     * @returns Array of container statuses. Empty array if no compose files exist or command fails.
+     */
     async status(): Promise<ContainerStatus[]> {
-      if (!composePath) {
-        const discovered = aggregator.discover(servicePaths);
-        if (discovered.length === 0) return [];
-        const merged = await smartMerger.deduplicate(discovered);
-        composePath = await writeTempCompose(merged);
-      }
+      const discovered = aggregator.discover(servicePaths);
+      if (discovered.length === 0) return [];
 
+      const composePath = await resolveComposePath(discovered, rootDir, smartMerger);
       const result = await run('docker', ['compose', '-f', composePath, 'ps', '--format', 'json']);
       if (result.exitCode !== 0 || !result.stdout.trim()) return [];
 
       const containers: ContainerStatus[] = [];
-      // docker compose ps --format json outputs one JSON object per line
       for (const line of result.stdout.trim().split('\n')) {
         try {
           const entry = JSON.parse(line);
           const state: ContainerState =
-            entry.Health === 'unhealthy' ? 'unhealthy' :
-            entry.State === 'running' ? 'running' : 'stopped';
+            entry.State !== 'running' ? 'stopped' :
+            entry.Health === 'unhealthy' ? 'unhealthy' : 'running';
           containers.push({
             name: entry.Name ?? entry.Service ?? '',
             image: entry.Image ?? '',
             state,
             port: entry.Publishers?.map((p: any) => `${p.PublishedPort}:${p.TargetPort}`).join(', ') ?? '',
           });
-        } catch { /* skip malformed lines */ }
+        } catch { /* skip malformed JSON lines */ }
       }
       return containers;
     },

package/src/manifest/manifest-discovery.ts

@@ -133,7 +133,7 @@ export function displayDiscoveredProjects(rootDir: string): DiscoveredManifest[]
   const mode = resolveMode(rootDir);
 
   if (mode === 'aggregated') {
-    logger.info(`Modo agregado: ${manifests.length} projetos descobertos`);
+    logger.info(`Aggregated mode: ${manifests.length} projects discovered`);
     for (const m of manifests) {
       logger.info(`  → ${m.name} (${relative(rootDir, m.path)})`);
     }

package/src/version/version-propagator.ts

@@ -95,7 +95,7 @@ export class VersionPropagator {
           previousVersion: currentRange,
           newVersion,
           skipped: true,
-          reason: `Range ${currentRange} incompatível com ${newVersion}`,
+          reason: `Range ${currentRange} incompatible with ${newVersion}`,
         });
         return false;
       }