octo-dev 0.9.0 → 0.10.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "octo-dev",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "description": "Build orchestration, semantic versioning, and local infrastructure management for repository workspaces",
   "type": "module",
   "license": "MIT",
@@ -49,16 +49,20 @@
     "@ai-sdk/anthropic": "^3.0.81",
     "commander": "^13.1.0",
     "execa": "^9.6.1",
+    "fs-extra": "^11.3.5",
     "pino": "^10.3.1",
     "pino-pretty": "^13.1.3",
     "semver": "^7.7.2",
+    "treeify": "^1.1.0",
     "tsx": "^4.19.4",
     "yaml": "^2.7.1",
     "zod": "^3.25.67"
   },
   "devDependencies": {
+    "@types/fs-extra": "^11.0.4",
     "@types/node": "^22.15.0",
     "@types/semver": "^7.7.0",
+    "@types/treeify": "^1.0.3",
     "fast-check": "^4.1.1",
     "typescript": "^5.8.3",
     "vitest": "^4.1.8"

package/src/cli/add.command.ts

@@ -1,5 +1,5 @@
-import { existsSync } from 'node:fs';
-import { resolve } from 'node:path';
+import { pathExistsSync, readJsonSync } from 'fs-extra';
+import { resolve, join } from 'node:path';
 import { logger } from '../shared/logger.js';
 import { OctoError } from '../shared/errors.js';
 import { extractRepoName, cloneRepository } from '../shared/git.js';
@@ -10,18 +10,75 @@ export interface AddCommandOptions {
   name?: string;
 }
 
+/**
+ * Reads dependencies from a project's package.json.
+ *
+ * @param projectDir - Absolute path to the project directory.
+ * @returns Combined dependency names from dependencies and devDependencies.
+ */
+function getProjectDeps(projectDir: string): string[] {
+  const pkgPath = join(projectDir, 'package.json');
+  if (!pathExistsSync(pkgPath)) return [];
+  try {
+    const pkg = readJsonSync(pkgPath);
+    return Object.keys({ ...pkg.dependencies, ...pkg.devDependencies });
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Detects dependency relationships between the new project and existing workspace projects.
+ * Reports which existing projects depend on the new one, and which the new one depends on.
+ *
+ * @param newProjectName - The package name of the newly added project.
+ * @param newProjectDir - The directory of the newly cloned project.
+ * @param existingEntries - Names of projects already in the manifest.
+ * @param rootDir - Workspace root directory.
+ */
+function reportDependencies(
+  newProjectName: string,
+  newProjectDir: string,
+  existingEntries: string[],
+  rootDir: string,
+): void {
+  const newDeps = getProjectDeps(newProjectDir);
+  const existingSet = new Set(existingEntries);
+
+  // What does the new project depend on that's already in the workspace?
+  const depsInWorkspace = newDeps.filter((d) => existingSet.has(d));
+  if (depsInWorkspace.length > 0) {
+    logger.info(`  → depends on: ${depsInWorkspace.join(', ')}`);
+  }
+
+  // Which existing projects depend on the new one?
+  const dependents: string[] = [];
+  for (const name of existingEntries) {
+    const dir = resolve(rootDir, extractRepoName(name));
+    if (!pathExistsSync(dir)) continue;
+    const deps = getProjectDeps(dir);
+    if (deps.includes(newProjectName)) {
+      dependents.push(name);
+    }
+  }
+
+  if (dependents.length > 0) {
+    logger.info(`  → depended on by: ${dependents.join(', ')}`);
+  }
+}
+
 /**
  * octo add <repo-url>
  *
  * Clones a repository and registers it in octo.yaml.
- * The directory is resolved automatically from the repo name (or --name override).
+ * After registration, reports dependency relationships with existing workspace projects.
  */
 export async function addCommand(repoUrl: string, opts: AddCommandOptions): Promise<void> {
   const rootDir = process.cwd();
   const dirName = opts.name || extractRepoName(repoUrl);
   const targetDir = resolve(rootDir, dirName);
 
-  if (existsSync(targetDir)) {
+  if (pathExistsSync(targetDir)) {
     throw new OctoError(`Directory already exists: ${dirName}. Use --name to specify another name.`);
   }
 
@@ -33,6 +90,12 @@ export async function addCommand(repoUrl: string, opts: AddCommandOptions): Prom
   const manifestPath = resolve(rootDir, 'octo.yaml');
   const { manifest, originalContent } = loadOrCreateManifest(manifestPath);
 
+  // Collect existing entries before adding
+  const existingEntries = [
+    ...manifest.services.map((e) => typeof e === 'string' ? e : Object.keys(e)[0]),
+    ...(manifest.packages ?? []).map((e) => typeof e === 'string' ? e : Object.keys(e)[0]),
+  ];
+
   const added = addEntry(manifest, projectName, dirName, type);
 
   if (!added) {
@@ -42,4 +105,6 @@ export async function addCommand(repoUrl: string, opts: AddCommandOptions): Prom
 
   saveManifest(manifestPath, manifest, originalContent);
   logger.info(`Project "${projectName}" added as ${type} in octo.yaml.`);
+
+  reportDependencies(projectName, targetDir, existingEntries, rootDir);
 }

package/src/cli/graph.command.ts

@@ -1,11 +1,12 @@
 import { readFileSync } from 'node:fs';
 import { join } from 'node:path';
+import treeify from 'treeify';
 import { parseManifest } from '../manifest/manifest-parser.js';
 import { buildGraphFromManifest } from '../graph/build-graph.js';
 import { OctoError } from '../shared/errors.js';
 
 /**
- * `octo graph` — displays the dependency graph on stdout as an indented adjacency list.
+ * `octo graph` — displays the dependency graph as a tree in the terminal using treeify.
  */
 export async function graphCommand(): Promise<void> {
   const cwd = process.cwd();
@@ -19,22 +20,37 @@ export async function graphCommand(): Promise<void> {
   }
 
   const result = parseManifest(content, manifestPath);
-  if (!result.ok) {
-    throw result.error;
-  }
+  if (!result.ok) throw result.error;
 
   const graph = buildGraphFromManifest(result.value, cwd);
   const sortResult = graph.topologicalSort();
 
-  if (!sortResult.ok) {
-    throw sortResult.error;
-  }
+  if (!sortResult.ok) throw sortResult.error;
+
+  const allNames = sortResult.value;
+  const totalEdges = allNames.reduce((sum, n) => sum + graph.getDependencies(n).length, 0);
 
-  // Print each node followed by its dependencies indented with 2 spaces
-  for (const name of sortResult.value) {
-    process.stdout.write(`${name}\n`);
-    for (const dep of graph.getDependencies(name)) {
-      process.stdout.write(`  ${dep}\n`);
+  // Build treeify-compatible object
+  const tree: Record<string, any> = {};
+
+  for (const name of allNames) {
+    const deps = graph.getDependencies(name);
+    const node = graph.getNode(name);
+    const icon = node?.type === 'service' ? '●' : '○';
+    const label = `${icon} ${name}`;
+
+    if (deps.length === 0) {
+      tree[label] = null;
+    } else {
+      const children: Record<string, null> = {};
+      for (const dep of deps) {
+        children[`→ ${dep}`] = null;
+      }
+      tree[label] = children;
     }
   }
+
+  console.log(`\n  Dependency Graph (${allNames.length} nodes, ${totalEdges} edges)\n`);
+  console.log(treeify.asTree(tree, true, true));
+  console.log('  ● service  ○ package  → depends on\n');
 }

package/src/cli/index.ts

@@ -11,7 +11,7 @@ const program = new Command();
 program
   .name('octo')
   .description('Build orchestration, semantic versioning, and local infrastructure management for repository workspaces')
-  .version('0.9.0');
+  .version('0.10.0');
 
 program
   .command('init')

package/src/graph/build-graph.ts

@@ -1,39 +1,40 @@
-import { readFileSync, readdirSync, statSync, existsSync } from 'node:fs';
+import { pathExistsSync, readdirSync, statSync } from 'fs-extra';
 import { join, resolve } from 'node:path';
 import { DependencyGraph, type GraphNode } from './dependency-graph.js';
 import { isRemoteRepo, extractRepoName } from '../shared/git.js';
+import { NodePackageReader } from '../manifest/adapters/node-package-reader.adapter.js';
+import type { PackageReader } from '../manifest/ports/package-reader.port.js';
 import type { OctoManifest, ServiceEntry, PackageEntry } from '../manifest/manifest-schema.js';
 
-interface PackageJson {
-  name?: string;
-  dependencies?: Record<string, string>;
-  devDependencies?: Record<string, string>;
-}
-
-/** Extract the name and optional path override from a manifest entry */
+/**
+ * Extracts the name and optional path override from a manifest entry.
+ *
+ * @param entry - A service or package entry (string or object with path config).
+ * @returns Resolved name and optional explicit path.
+ */
 function resolveEntry(entry: ServiceEntry | PackageEntry): { name: string; path?: string } {
   if (typeof entry === 'string') return { name: entry };
-  // Object format: { "auth": { path?: "./custom" } }
   const key = Object.keys(entry)[0];
   const config = (entry as Record<string, { path?: string }>)[key];
   return { name: key, path: config?.path };
 }
 
 /**
- * Recursively search for a directory containing a package.json whose `name` matches `targetName`.
- * Searches up to depth 3 from rootDir.
+ * Recursively searches for a directory whose package.json `name` matches targetName.
+ * Skips node_modules, dist, and dot-prefixed directories. Max depth: 3.
+ *
+ * @param rootDir - Starting directory for the search.
+ * @param targetName - The package name to find.
+ * @param reader - PackageReader instance for reading package metadata.
+ * @param maxDepth - Maximum recursion depth.
+ * @returns Absolute path to the matching directory, or undefined.
  */
-function findPackageDir(rootDir: string, targetName: string, maxDepth = 3): string | undefined {
+function findPackageDir(rootDir: string, targetName: string, reader: PackageReader, maxDepth = 3): string | undefined {
   function search(dir: string, depth: number): string | undefined {
     if (depth > maxDepth) return undefined;
 
-    const pkgPath = join(dir, 'package.json');
-    if (existsSync(pkgPath)) {
-      try {
-        const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8')) as PackageJson;
-        if (pkg.name === targetName) return dir;
-      } catch { /* skip invalid json */ }
-    }
+    const pkg = reader.read(dir);
+    if (pkg?.name === targetName) return dir;
 
     let entries: string[];
     try {
@@ -58,26 +59,24 @@ function findPackageDir(rootDir: string, targetName: string, maxDepth = 3): stri
   return search(rootDir, 0);
 }
 
-/** Read a package.json from a directory, returning undefined if not found */
-function readPackageJson(dir: string): PackageJson | undefined {
-  const pkgPath = join(dir, 'package.json');
-  if (!existsSync(pkgPath)) return undefined;
-  try {
-    return JSON.parse(readFileSync(pkgPath, 'utf-8')) as PackageJson;
-  } catch {
-    return undefined;
-  }
-}
-
 /**
- * Build a DependencyGraph from an OctoManifest.
- * Reads each service/package's package.json and adds edges only for internal dependencies.
+ * Builds a DependencyGraph from an OctoManifest.
+ * Resolves project paths, reads package metadata via the PackageReader port,
+ * and adds edges only for dependencies that reference other workspace projects.
+ *
+ * @param manifest - The parsed octo.yaml manifest.
+ * @param rootDir - Workspace root directory.
+ * @param reader - Optional PackageReader implementation (defaults to NodePackageReader).
+ * @returns A populated DependencyGraph with nodes and internal dependency edges.
  */
-export function buildGraphFromManifest(manifest: OctoManifest, rootDir: string): DependencyGraph {
+export function buildGraphFromManifest(
+  manifest: OctoManifest,
+  rootDir: string,
+  reader: PackageReader = new NodePackageReader(),
+): DependencyGraph {
   const graph = new DependencyGraph();
   const resolvedPaths = new Map<string, string>();
 
-  // Collect all declared names (services + packages)
   const allEntries: Array<{ name: string; path?: string; type: 'service' | 'package' }> = [];
 
   for (const entry of manifest.services) {
@@ -89,32 +88,27 @@ export function buildGraphFromManifest(manifest: OctoManifest, rootDir: string):
     allEntries.push({ ...resolved, type: 'package' });
   }
 
-  // Resolve paths and add nodes
   for (const entry of allEntries) {
     let dir: string | undefined;
 
     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);
+      dir = findPackageDir(rootDir, entry.name, reader);
     }
 
-    if (!dir || !existsSync(dir)) continue;
+    if (!dir || !pathExistsSync(dir)) continue;
 
     resolvedPaths.set(entry.name, dir);
-    const node: GraphNode = { name: entry.name, type: entry.type, path: dir };
-    graph.addNode(node);
+    graph.addNode({ name: entry.name, type: entry.type, path: dir });
   }
 
-  // Set of all internal package names for quick lookup
   const internalNames = new Set(resolvedPaths.keys());
 
-  // Add edges based on package.json dependencies
   for (const [name, dir] of resolvedPaths) {
-    const pkg = readPackageJson(dir);
+    const pkg = reader.read(dir);
     if (!pkg) continue;
 
     const allDeps = { ...pkg.dependencies, ...pkg.devDependencies };

package/src/infra/compose-aggregator.ts

@@ -1,4 +1,4 @@
-import { readFileSync, existsSync } from 'node:fs';
+import { readFileSync, pathExistsSync } from 'fs-extra';
 import { join, dirname, relative } from 'node:path';
 import { parse } from 'yaml';
 
@@ -88,7 +88,7 @@ export function createComposeAggregator(): ComposeAggregator {
       const results: DiscoveredCompose[] = [];
       for (const svcPath of servicePaths) {
         const composePath = join(svcPath, 'docker-compose.yml');
-        if (!existsSync(composePath)) continue;
+        if (!pathExistsSync(composePath)) continue;
         const raw = readFileSync(composePath, 'utf-8');
         const content = (parse(raw) ?? {}) as DockerComposeDocument;
         const serviceName = svcPath.split('/').pop() ?? svcPath;

package/src/manifest/adapters/node-package-reader.adapter.ts

@@ -0,0 +1,32 @@
+import { readJsonSync, pathExistsSync } from 'fs-extra';
+import { join } from 'node:path';
+import type { PackageReader, PackageMetadata } from '../ports/package-reader.port.js';
+
+/**
+ * Adapter — reads Node.js package.json files from the filesystem.
+ * Implements the PackageReader port using fs-extra for robust file handling.
+ */
+export class NodePackageReader implements PackageReader {
+  /**
+   * Reads and parses a package.json from the given directory.
+   *
+   * @param dir - Absolute path to the project directory.
+   * @returns Parsed package metadata, or undefined if package.json is missing or invalid.
+   */
+  read(dir: string): PackageMetadata | undefined {
+    const pkgPath = join(dir, 'package.json');
+    if (!pathExistsSync(pkgPath)) return undefined;
+
+    try {
+      const raw = readJsonSync(pkgPath);
+      return {
+        name: raw.name,
+        version: raw.version,
+        dependencies: raw.dependencies ?? {},
+        devDependencies: raw.devDependencies ?? {},
+      };
+    } catch {
+      return undefined;
+    }
+  }
+}

package/src/manifest/manifest-discovery.ts

@@ -1,4 +1,4 @@
-import { readdirSync, readFileSync, statSync, existsSync } from 'node:fs';
+import { readdirSync, readFileSync, statSync, pathExistsSync } from 'fs-extra';
 import { join, relative } from 'node:path';
 import { ManifestError } from '../shared/errors.js';
 import { logger } from '../shared/logger.js';
@@ -29,7 +29,7 @@ function scanForManifests(dir: string, rootDir: string, depth: number): Discover
   const results: DiscoveredManifest[] = [];
   const manifestPath = join(dir, MANIFEST_FILENAME);
 
-  if (existsSync(manifestPath)) {
+  if (pathExistsSync(manifestPath)) {
     const dirName = relative(rootDir, dir) || '.';
     results.push({
       name: dirName === '.' ? 'root' : dirName,
@@ -147,7 +147,7 @@ export function displayDiscoveredProjects(rootDir: string): DiscoveredManifest[]
  * Detects whether a project directory is a service (has Dockerfile) or a package.
  */
 export function detectProjectType(projectDir: string): 'service' | 'package' {
-  return existsSync(join(projectDir, 'Dockerfile')) ? 'service' : 'package';
+  return pathExistsSync(join(projectDir, 'Dockerfile')) ? 'service' : 'package';
 }
 
 /**
@@ -155,7 +155,7 @@ export function detectProjectType(projectDir: string): 'service' | 'package' {
  */
 export function resolveProjectName(projectDir: string, fallbackName: string): string {
   const pkgPath = join(projectDir, 'package.json');
-  if (existsSync(pkgPath)) {
+  if (pathExistsSync(pkgPath)) {
     try {
       const content = readFileSync(pkgPath, 'utf-8');
       const pkg = JSON.parse(content);

package/src/manifest/manifest-mutator.ts

@@ -1,4 +1,4 @@
-import { readFileSync, writeFileSync, existsSync } from 'node:fs';
+import { readFileSync, writeFileSync, pathExistsSync } from 'fs-extra';
 import { parseManifest } from './manifest-parser.js';
 import { printManifest } from './manifest-printer.js';
 import { OctoError } from '../shared/errors.js';
@@ -13,7 +13,7 @@ export interface LoadedManifest {
  * Loads an existing octo.yaml manifest, or returns a minimal empty one.
  */
 export function loadOrCreateManifest(manifestPath: string): LoadedManifest {
-  if (existsSync(manifestPath)) {
+  if (pathExistsSync(manifestPath)) {
     const content = readFileSync(manifestPath, 'utf-8');
     const parsed = parseManifest(content, manifestPath);
     if (parsed.ok) {

package/src/manifest/ports/package-reader.port.ts

@@ -0,0 +1,20 @@
+/**
+ * Port — abstracts reading package metadata from a project directory.
+ * Decouples domain logic from filesystem and specific package manager formats.
+ */
+export interface PackageMetadata {
+  name?: string;
+  version?: string;
+  dependencies: Record<string, string>;
+  devDependencies: Record<string, string>;
+}
+
+export interface PackageReader {
+  /**
+   * Reads package metadata from a project directory.
+   *
+   * @param dir - Absolute path to the project directory.
+   * @returns Package metadata, or undefined if no package manifest exists.
+   */
+  read(dir: string): PackageMetadata | undefined;
+}

package/src/shared/config.ts

@@ -1,4 +1,4 @@
-import { readFileSync, writeFileSync, existsSync } from 'node:fs';
+import { readJsonSync, writeJsonSync, pathExistsSync } from 'fs-extra';
 import { join } from 'node:path';
 import { homedir } from 'node:os';
 
@@ -22,9 +22,9 @@ export interface OctoConfig {
  * @returns The parsed configuration.
  */
 export function loadConfig(): OctoConfig {
-  if (!existsSync(CONFIG_FILE)) return {};
+  if (!pathExistsSync(CONFIG_FILE)) return {};
   try {
-    return JSON.parse(readFileSync(CONFIG_FILE, 'utf-8')) as OctoConfig;
+    return readJsonSync(CONFIG_FILE) as OctoConfig;
   } catch {
     return {};
   }
@@ -39,7 +39,7 @@ export function loadConfig(): OctoConfig {
 export function saveConfig(partial: Partial<OctoConfig>): void {
   const existing = loadConfig();
   const merged = { ...existing, ...partial };
-  writeFileSync(CONFIG_FILE, JSON.stringify(merged, null, 2), 'utf-8');
+  writeJsonSync(CONFIG_FILE, merged, { spaces: 2 });
 }
 
 /**

package/src/shared/sync.ts

@@ -1,4 +1,4 @@
-import { existsSync } from 'node:fs';
+import { pathExistsSync } from 'fs-extra';
 import { resolve } from 'node:path';
 import { logger } from './logger.js';
 import { isRemoteRepo, resolveGitUrl, extractRepoName, cloneRepository } from './git.js';
@@ -20,7 +20,7 @@ export async function ensureRepositories(manifest: OctoManifest, rootDir: string
     if (!isRemoteRepo(name)) return false;
     const repoName = extractRepoName(name);
     const targetDir = resolve(rootDir, explicitPath ?? repoName);
-    return !existsSync(targetDir);
+    return !pathExistsSync(targetDir);
   });
 
   if (pending.length === 0) return 0;