octo-dev 0.5.5 → 0.7.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.5",
-  "description": "CLI for monorepo build orchestration, semantic versioning, and local infrastructure management",
+  "version": "0.7.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/bump.command.ts

@@ -49,6 +49,7 @@ export async function bumpCommand(pkg: string, type: string, opts: BumpCommandOp
     );
   }
 
+  await ensureRepositories(manifest, rootDir);
   const graph = buildGraphFromManifest(manifest, rootDir);
   const node = graph.getNode(pkg);
 

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.5');
+  .description('Build orchestration, semantic versioning, and local infrastructure management for repository workspaces')
+  .version('0.7.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');
@@ -86,6 +86,14 @@ program
     await addCommand(repoUrl, opts);
   });
 
+program
+  .command('sync')
+  .description('Clone all missing repositories declared in octo.yaml')
+  .action(async () => {
+    const { syncCommand } = await import('./sync.command.js');
+    await syncCommand();
+  });
+
 const config = program
   .command('config')
   .description('Configure octo and git settings');

package/src/cli/init.command.ts

@@ -2,6 +2,7 @@ import { readdir, readFile, access, writeFile } from 'node:fs/promises';
 import { join, relative } from 'node:path';
 import { logger } from '../shared/logger.js';
 import { printManifest } from '../manifest/manifest-printer.js';
+import { ensureRepositories } from '../shared/sync.js';
 import type { OctoManifest } from '../manifest/manifest-schema.js';
 
 const EXCLUDED_DIRS = new Set(['node_modules', 'dist']);
@@ -104,4 +105,7 @@ export async function initCommand(opts: { standalone?: boolean }): Promise<void>
   await writeFile(outputPath, yaml, 'utf-8');
 
   logger.info(`octo.yaml generated with ${services.length} service(s)${packages.length > 0 ? ` and ${packages.length} package(s)` : ''}.`);
+
+  // Sync: clone any missing remote repos declared in the manifest
+  await ensureRepositories(manifest, rootDir);
 }

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/sync.command.ts

@@ -0,0 +1,28 @@
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { parseManifest } from '../manifest/manifest-parser.js';
+import { ensureRepositories } from '../shared/sync.js';
+import { OctoError } from '../shared/errors.js';
+
+/**
+ * octo sync
+ *
+ * Clones all missing repositories declared in octo.yaml.
+ * Repos using org/repo format are cloned from GitHub into ./repo-name.
+ */
+export async function syncCommand(): Promise<void> {
+  const rootDir = process.cwd();
+  const manifestPath = resolve(rootDir, 'octo.yaml');
+
+  let content: string;
+  try {
+    content = readFileSync(manifestPath, 'utf-8');
+  } catch {
+    throw new OctoError('octo.yaml not found. Run `octo init` first.');
+  }
+
+  const parsed = parseManifest(content, manifestPath);
+  if (!parsed.ok) throw parsed.error;
+
+  await ensureRepositories(parsed.value, rootDir);
+}

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/graph/build-graph.ts

@@ -1,6 +1,7 @@
 import { readFileSync, readdirSync, statSync, existsSync } from 'node:fs';
 import { join, resolve } from 'node:path';
 import { DependencyGraph, type GraphNode } from './dependency-graph.js';
+import { isRemoteRepo, extractRepoName } from '../shared/git.js';
 import type { OctoManifest, ServiceEntry, PackageEntry } from '../manifest/manifest-schema.js';
 
 interface PackageJson {
@@ -94,11 +95,14 @@ export function buildGraphFromManifest(manifest: OctoManifest, rootDir: string):
 
     if (entry.path) {
       dir = resolve(rootDir, entry.path);
+    } else if (isRemoteRepo(entry.name)) {
+      // org/repo format — directory is the repo name
+      dir = resolve(rootDir, extractRepoName(entry.name));
     } else {
       dir = findPackageDir(rootDir, entry.name);
     }
 
-    if (!dir) continue;
+    if (!dir || !existsSync(dir)) continue;
 
     resolvedPaths.set(entry.name, dir);
     const node: GraphNode = { name: entry.name, type: entry.type, path: dir };

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/shared/git-auth.ts

@@ -0,0 +1,37 @@
+import { ask } from './prompt.js';
+
+let cachedToken: string | undefined;
+
+/**
+ * Acquires a GitHub Personal Access Token for git HTTPS operations.
+ * Prompts the user once and caches in memory for the process lifetime.
+ * The token is never persisted to disk.
+ *
+ * @returns The PAT string, or undefined if the user provides empty input (skip).
+ */
+export async function acquireGitToken(): Promise<string | undefined> {
+  if (cachedToken) return cachedToken;
+  const input = await ask('GitHub token (PAT): ');
+  cachedToken = input || undefined;
+  return cachedToken;
+}
+
+/**
+ * Embeds a token into an HTTPS git URL for credential-less cloning.
+ * Produces format: https://<token>@github.com/org/repo.git
+ *
+ * @param baseUrl - The base HTTPS clone URL (e.g. "https://github.com/org/repo.git").
+ * @param token - The GitHub PAT to embed.
+ * @returns The URL with credentials embedded in the authority segment.
+ */
+export function embedTokenInUrl(baseUrl: string, token: string): string {
+  return baseUrl.replace('https://', `https://${token}@`);
+}
+
+/**
+ * Clears the cached token from process memory.
+ * Should be called after sync completes as defense-in-depth.
+ */
+export function clearCachedToken(): void {
+  cachedToken = undefined;
+}

package/src/shared/git.ts

@@ -4,11 +4,15 @@ import { logger } from './logger.js';
 import { OctoError } from './errors.js';
 
 /**
- * Extracts the repository name from a git URL.
- * Supports HTTPS and SSH formats:
+ * Extracts the repository name from a git URL or org/repo shorthand.
+ * Supports HTTPS, SSH, and GitHub shorthand formats:
  *   https://github.com/user/repo.git → repo
  *   git@github.com:user/repo.git    → repo
- *   https://github.com/user/repo    → repo
+ *   user/repo                        → repo
+ *
+ * @param url - Git URL or org/repo shorthand.
+ * @returns The repository name (last segment without .git suffix).
+ * @throws OctoError if the name cannot be extracted.
  */
 export function extractRepoName(url: string): string {
   const cleaned = url.replace(/\.git$/, '').replace(/\/$/, '');
@@ -20,19 +24,43 @@ export function extractRepoName(url: string): string {
   return name;
 }
 
+/**
+ * Checks if a manifest entry name is a git remote reference (org/repo format).
+ *
+ * @param name - The entry name from octo.yaml.
+ * @returns true if the name matches org/repo pattern (contains exactly one slash, no @ prefix).
+ */
+export function isRemoteRepo(name: string): boolean {
+  return /^[^@/]+\/[^/]+$/.test(name);
+}
+
+/**
+ * Converts an org/repo shorthand to a full GitHub HTTPS URL.
+ *
+ * @param shorthand - The org/repo string (e.g. "vguerato/spectre-tasks").
+ * @returns Full clone URL (e.g. "https://github.com/vguerato/spectre-tasks.git").
+ */
+export function resolveGitUrl(shorthand: string): string {
+  return `https://github.com/${shorthand}.git`;
+}
+
 /**
  * Clones a git repository into the target directory.
+ * Uses interactive stdio when no auth is embedded in the URL.
+ *
+ * @param url - Full git URL to clone (may contain embedded token).
+ * @param targetDir - Absolute path where the repo will be cloned.
+ * @throws OctoError if clone exits with non-zero code.
  */
 export async function cloneRepository(url: string, targetDir: string): Promise<void> {
-  logger.info(`Cloning ${url}...`);
+  // Log without exposing token
+  const safeUrl = url.replace(/\/\/[^@]+@/, '//***@');
+  logger.info(`Cloning ${safeUrl}...`);
 
-  const result = await run('git', ['clone', url, targetDir], {
-    timeout: 120_000,
-    interactive: true,
-  });
+  const result = await run('git', ['clone', url, targetDir], { timeout: 120_000 });
 
   if (result.exitCode !== 0) {
-    throw new OctoError('Failed to clone repository.');
+    throw new OctoError(`Failed to clone repository: ${result.stderr.trim() || 'unknown error'}`);
   }
 
   logger.info(`Repository cloned to ./${basename(targetDir)}`);

package/src/shared/prompt.ts

@@ -1,8 +1,27 @@
 import { createInterface } from 'node:readline';
 
+/**
+ * Prompts the user with a question and returns their text input.
+ *
+ * @param message - The prompt message displayed to the user.
+ * @returns The trimmed user input string.
+ */
+export function ask(message: string): Promise<string> {
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  return new Promise((resolve) => {
+    rl.question(message, (answer) => {
+      rl.close();
+      resolve(answer.trim());
+    });
+  });
+}
+
 /**
  * Prompts the user with a yes/no question via stdin.
- * Accepts 'y', 'Y', 's', 'S' as affirmative.
+ * Accepts 'y', 'Y', 's', 'S' as affirmative responses.
+ *
+ * @param message - The yes/no question to display.
+ * @returns `true` if the user confirmed, `false` otherwise.
  */
 export function confirm(message: string): Promise<boolean> {
   const rl = createInterface({ input: process.stdin, output: process.stdout });

package/src/shared/sync.ts

@@ -0,0 +1,81 @@
+import { existsSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { logger } from './logger.js';
+import { isRemoteRepo, resolveGitUrl, extractRepoName, cloneRepository } from './git.js';
+import { acquireGitToken, embedTokenInUrl, clearCachedToken } from './git-auth.js';
+import type { OctoManifest, ServiceEntry, PackageEntry } from '../manifest/manifest-schema.js';
+
+/**
+ * Ensures all repositories declared in the manifest are present locally.
+ * Prompts for a GitHub token once, embeds it in clone URLs (in-memory only).
+ * Token is cleared from memory after all clones complete.
+ *
+ * @param manifest - The parsed octo.yaml manifest.
+ * @param rootDir - Workspace root directory where repos are cloned.
+ * @returns Number of repositories that were cloned.
+ */
+export async function ensureRepositories(manifest: OctoManifest, rootDir: string): Promise<number> {
+  const entries = collectEntries(manifest);
+  const pending = entries.filter(({ name, path: explicitPath }) => {
+    if (!isRemoteRepo(name)) return false;
+    const repoName = extractRepoName(name);
+    const targetDir = resolve(rootDir, explicitPath ?? repoName);
+    return !existsSync(targetDir);
+  });
+
+  if (pending.length === 0) return 0;
+
+  logger.info(`${pending.length} repository(ies) to clone.`);
+
+  const token = await acquireGitToken();
+
+  try {
+    let cloned = 0;
+    for (const { name, path: explicitPath } of pending) {
+      const repoName = extractRepoName(name);
+      const targetDir = resolve(rootDir, explicitPath ?? repoName);
+      const baseUrl = resolveGitUrl(name);
+      const url = token ? embedTokenInUrl(baseUrl, token) : baseUrl;
+      await cloneRepository(url, targetDir);
+      cloned++;
+    }
+
+    logger.info(`Synced ${cloned} repository(ies).`);
+    return cloned;
+  } finally {
+    clearCachedToken();
+  }
+}
+
+/**
+ * Extracts all entry names and optional path overrides from the manifest.
+ *
+ * @param manifest - The parsed octo.yaml manifest.
+ * @returns Array of entries with name and optional explicit path.
+ */
+function collectEntries(manifest: OctoManifest): Array<{ name: string; path?: string }> {
+  const results: Array<{ name: string; path?: string }> = [];
+
+  for (const entry of manifest.services) {
+    results.push(resolveEntry(entry));
+  }
+  for (const entry of manifest.packages ?? []) {
+    results.push(resolveEntry(entry));
+  }
+
+  return results;
+}
+
+/**
+ * Resolves the name and optional path from a manifest entry.
+ * String entries return name only. Object entries extract key + path config.
+ *
+ * @param entry - A service or package entry from octo.yaml.
+ * @returns Object with resolved name and optional path override.
+ */
+function resolveEntry(entry: ServiceEntry | PackageEntry): { name: string; path?: string } {
+  if (typeof entry === 'string') return { name: entry };
+  const key = Object.keys(entry)[0];
+  const config = (entry as Record<string, { path?: string }>)[key];
+  return { name: key, path: config?.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;
       }