octo-dev 0.2.2

package/src/manifest/manifest-parser.ts

@@ -0,0 +1,109 @@
+import { parse as parseYaml, YAMLParseError } from 'yaml';
+import { OctoManifestSchema, type OctoManifest } from './manifest-schema.js';
+import { ManifestError } from '../shared/errors.js';
+
+export type ParseSuccess = {
+  ok: true;
+  value: OctoManifest;
+  warnings: string[];
+};
+
+export type ParseFailure = {
+  ok: false;
+  error: ManifestError;
+};
+
+export type ParseResult = ParseSuccess | ParseFailure;
+
+/** Known top-level keys in the manifest schema */
+const KNOWN_TOP_KEYS = new Set(['hooks', 'services', 'packages']);
+const KNOWN_HOOK_KEYS = new Set(['pre-build', 'pre-bump']);
+
+/**
+ * Detects unknown keys at top level and in hooks, returning warnings.
+ */
+function detectUnknownKeys(data: Record<string, unknown>): string[] {
+  const warnings: string[] = [];
+
+  for (const key of Object.keys(data)) {
+    if (!KNOWN_TOP_KEYS.has(key)) {
+      warnings.push(`Unknown key "${key}" at root level`);
+    }
+  }
+
+  if (data.hooks && typeof data.hooks === 'object' && data.hooks !== null) {
+    for (const key of Object.keys(data.hooks as Record<string, unknown>)) {
+      if (!KNOWN_HOOK_KEYS.has(key)) {
+        warnings.push(`Unknown key "${key}" in hooks`);
+      }
+    }
+  }
+
+  return warnings;
+}
+
+/**
+ * Parses YAML content and validates against OctoManifestSchema.
+ * Returns all validation errors in a single message (does not stop at first error).
+ * Emits warnings for unknown keys without blocking the parse.
+ */
+export function parseManifest(content: string, filePath?: string): ParseResult {
+  // Handle empty/whitespace-only content
+  if (!content || content.trim().length === 0) {
+    return {
+      ok: false,
+      error: new ManifestError('Manifest file is empty or contains only whitespace', filePath),
+    };
+  }
+
+  // Parse YAML — catch syntax errors with line/column
+  let data: unknown;
+  try {
+    data = parseYaml(content);
+  } catch (err) {
+    if (err instanceof YAMLParseError) {
+      const pos = err.linePos?.[0];
+      return {
+        ok: false,
+        error: new ManifestError(
+          `YAML syntax error: ${err.message}`,
+          filePath,
+          pos?.line,
+          pos?.col,
+        ),
+      };
+    }
+    return {
+      ok: false,
+      error: new ManifestError(`Unexpected parse error: ${String(err)}`, filePath),
+    };
+  }
+
+  if (data === null || data === undefined || typeof data !== 'object') {
+    return {
+      ok: false,
+      error: new ManifestError('Manifest must be a YAML mapping (object)', filePath),
+    };
+  }
+
+  // Detect unknown keys (warnings, non-blocking)
+  const warnings = detectUnknownKeys(data as Record<string, unknown>);
+
+  // Validate with Zod — collect ALL errors
+  const result = OctoManifestSchema.safeParse(data);
+
+  if (!result.success) {
+    const issues = result.error.issues.map(
+      (issue) => `  - ${issue.path.join('.')}: ${issue.message}`,
+    );
+    return {
+      ok: false,
+      error: new ManifestError(
+        `Manifest validation failed:\n${issues.join('\n')}`,
+        filePath,
+      ),
+    };
+  }
+
+  return { ok: true, value: result.data, warnings };
+}

package/src/manifest/manifest-printer.ts

@@ -0,0 +1,75 @@
+import { parseDocument, stringify, Document, isSeq, isScalar, isMap } from 'yaml';
+import type { OctoManifest } from './manifest-schema.js';
+
+/**
+ * Checks if two values are deeply equal (for simple manifest structures).
+ */
+function deepEqual(a: unknown, b: unknown): boolean {
+  if (a === b) return true;
+  if (a == null || b == null) return false;
+  if (typeof a !== typeof b) return false;
+  if (Array.isArray(a) && Array.isArray(b)) {
+    if (a.length !== b.length) return false;
+    return a.every((v, i) => deepEqual(v, b[i]));
+  }
+  if (typeof a === 'object' && typeof b === 'object') {
+    const keysA = Object.keys(a as object);
+    const keysB = Object.keys(b as object);
+    if (keysA.length !== keysB.length) return false;
+    return keysA.every(k => deepEqual((a as Record<string, unknown>)[k], (b as Record<string, unknown>)[k]));
+  }
+  return false;
+}
+
+/**
+ * Gets the plain JS value from a YAML AST node for comparison.
+ */
+function nodeToPlain(node: unknown): unknown {
+  if (isScalar(node)) return node.value;
+  if (isSeq(node)) return node.items.map(nodeToPlain);
+  if (isMap(node)) {
+    const obj: Record<string, unknown> = {};
+    for (const pair of node.items) {
+      const key = isScalar(pair.key) ? String(pair.key.value) : String(pair.key);
+      obj[key] = nodeToPlain(pair.value);
+    }
+    return obj;
+  }
+  return node;
+}
+
+/**
+ * Serializes an OctoManifest back to YAML.
+ * When originalContent is provided, updates the AST in-place to preserve comments and key order.
+ * When no originalContent is provided, stringifies the object directly.
+ */
+export function printManifest(manifest: OctoManifest, originalContent?: string): string {
+  if (!originalContent) {
+    return stringify(manifest, { lineWidth: 0 });
+  }
+
+  // Parse original into a Document (AST) to preserve comments and ordering
+  const doc = parseDocument(originalContent);
+
+  // Update hooks
+  if (manifest.hooks !== undefined) {
+    const existingHooks = doc.get('hooks', true);
+    if (!deepEqual(nodeToPlain(existingHooks), manifest.hooks)) {
+      doc.set('hooks', manifest.hooks);
+    }
+  } else if (doc.has('hooks')) {
+    doc.delete('hooks');
+  }
+
+  // Only update services/packages if values actually changed
+  for (const key of ['services', 'packages'] as const) {
+    const existingNode = doc.get(key, true);
+    const existingPlain = nodeToPlain(existingNode);
+    if (!deepEqual(existingPlain, manifest[key])) {
+      doc.set(key, manifest[key]);
+    }
+    // If equal, leave the AST node untouched (preserves all comments)
+  }
+
+  return doc.toString({ lineWidth: 0 });
+}

package/src/manifest/manifest-schema.ts

@@ -0,0 +1,34 @@
+import { z } from 'zod';
+
+export const HookDefinitionSchema = z.object({
+  name: z.string(),
+  command: z.string(),
+});
+
+export const ServiceEntrySchema = z.union([
+  z.string(),
+  z.record(z.string(), z.object({
+    path: z.string().optional(),
+  })),
+]);
+
+export const PackageEntrySchema = z.union([
+  z.string(),
+  z.record(z.string(), z.object({
+    path: z.string().optional(),
+  })),
+]);
+
+export const OctoManifestSchema = z.object({
+  hooks: z.object({
+    'pre-build': z.array(HookDefinitionSchema).optional(),
+    'pre-bump': z.array(HookDefinitionSchema).optional(),
+  }).optional(),
+  services: z.array(ServiceEntrySchema),
+  packages: z.array(PackageEntrySchema),
+});
+
+export type OctoManifest = z.infer<typeof OctoManifestSchema>;
+export type HookDefinition = z.infer<typeof HookDefinitionSchema>;
+export type ServiceEntry = z.infer<typeof ServiceEntrySchema>;
+export type PackageEntry = z.infer<typeof PackageEntrySchema>;

package/src/shared/errors.ts

@@ -0,0 +1,43 @@
+/** Base error for all Octo CLI errors */
+export class OctoError extends Error {
+  constructor(message: string, public readonly exitCode: number = 1) {
+    super(message);
+    this.name = 'OctoError';
+  }
+}
+
+/** Manifest parsing/validation errors */
+export class ManifestError extends OctoError {
+  constructor(
+    message: string,
+    public readonly file?: string,
+    public readonly line?: number,
+    public readonly column?: number,
+  ) {
+    super(message);
+    this.name = 'ManifestError';
+  }
+}
+
+/** Build engine/orchestration errors */
+export class BuildError extends OctoError {
+  constructor(
+    message: string,
+    public readonly service?: string,
+    public readonly output?: string,
+  ) {
+    super(message);
+    this.name = 'BuildError';
+  }
+}
+
+/** Dependency cycle detection errors */
+export class CycleError extends OctoError {
+  constructor(
+    message: string,
+    public readonly cycle: string[],
+  ) {
+    super(message);
+    this.name = 'CycleError';
+  }
+}

package/src/shared/logger.ts

@@ -0,0 +1,14 @@
+/** Formatted output for stdout/stderr with prefixes */
+export const logger = {
+  info(message: string): void {
+    process.stdout.write(`[INFO] ${message}\n`);
+  },
+
+  error(message: string): void {
+    process.stderr.write(`[ERRO] ${message}\n`);
+  },
+
+  warn(message: string): void {
+    process.stderr.write(`[AVISO] ${message}\n`);
+  },
+};

package/src/shared/process-runner.ts

@@ -0,0 +1,47 @@
+import { spawn } from 'node:child_process';
+
+export interface RunOptions {
+  cwd?: string;
+  timeout?: number;
+  env?: Record<string, string>;
+}
+
+export interface RunResult {
+  stdout: string;
+  stderr: string;
+  exitCode: number;
+}
+
+/** Wrapper for child_process.spawn with Promise, timeout, and stdout/stderr capture */
+export function run(command: string, args: string[] = [], options: RunOptions = {}): Promise<RunResult> {
+  const { cwd, timeout = 60_000, env } = options;
+
+  return new Promise((resolve, reject) => {
+    const child = spawn(command, args, {
+      cwd,
+      env: env ? { ...process.env, ...env } : process.env,
+      shell: true,
+    });
+
+    let stdout = '';
+    let stderr = '';
+
+    child.stdout.on('data', (data: Buffer) => { stdout += data.toString(); });
+    child.stderr.on('data', (data: Buffer) => { stderr += data.toString(); });
+
+    const timer = setTimeout(() => {
+      child.kill('SIGTERM');
+      reject(new Error(`Command timed out after ${timeout}ms: ${command} ${args.join(' ')}`));
+    }, timeout);
+
+    child.on('close', (code) => {
+      clearTimeout(timer);
+      resolve({ stdout, stderr, exitCode: code ?? 1 });
+    });
+
+    child.on('error', (err) => {
+      clearTimeout(timer);
+      reject(err);
+    });
+  });
+}

package/src/shared/shutdown.ts

@@ -0,0 +1,36 @@
+/** Graceful shutdown coordination for Octo CLI */
+
+type ShutdownCallback = () => void | Promise<void>;
+
+const callbacks: ShutdownCallback[] = [];
+let shuttingDown = false;
+
+/** Check if shutdown has been requested */
+export function isShuttingDown(): boolean {
+  return shuttingDown;
+}
+
+/** Register a cleanup callback to run on shutdown */
+export function onShutdown(callback: ShutdownCallback): void {
+  callbacks.push(callback);
+}
+
+/** Trigger shutdown — runs all registered callbacks and exits */
+export async function triggerShutdown(signal: string): Promise<void> {
+  if (shuttingDown) return; // prevent double-trigger
+  shuttingDown = true;
+
+  const { logger } = await import('./logger.js');
+  logger.warn(`Shutdown solicitado (${signal}). Cancelando operações em andamento...`);
+
+  for (const cb of callbacks) {
+    try {
+      await cb();
+    } catch {
+      // best-effort cleanup
+    }
+  }
+
+  logger.info('Shutdown completo.');
+  process.exit(130);
+}

package/src/version/changelog-generator.ts

@@ -0,0 +1,112 @@
+import { readFile, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { Ollama } from 'ollama';
+import { run } from '../shared/process-runner.js';
+import { logger } from '../shared/logger.js';
+
+const HEADER = '# Changelog\n';
+
+export class ChangelogGenerator {
+  private ollama = new Ollama();
+
+  async generate(packageDir: string, newVersion: string): Promise<string> {
+    const changelogPath = join(packageDir, 'CHANGELOG.md');
+    const commits = await this.getCommitsSinceLastTag(packageDir);
+    const entry = await this.buildEntry(newVersion, commits);
+
+    const existing = await this.readChangelog(changelogPath);
+    const updated = this.prependEntry(existing, entry);
+    await writeFile(changelogPath, updated, 'utf-8');
+
+    return entry;
+  }
+
+  private async getCommitsSinceLastTag(cwd: string): Promise<string[]> {
+    const tagResult = await run('git', ['describe', '--tags', '--abbrev=0'], { cwd });
+    const lastTag = tagResult.exitCode === 0 ? tagResult.stdout.trim() : '';
+
+    const logArgs = lastTag
+      ? ['log', `${lastTag}..HEAD`, '--oneline', '--', '.']
+      : ['log', '--oneline', '--', '.'];
+
+    const logResult = await run('git', logArgs, { cwd });
+    if (logResult.exitCode !== 0 || !logResult.stdout.trim()) return [];
+
+    return logResult.stdout
+      .trim()
+      .split('\n')
+      .map((line) => line.replace(/^[a-f0-9]+\s+/, ''));
+  }
+
+  private async buildEntry(version: string, commits: string[]): Promise<string> {
+    const date = new Date().toISOString().slice(0, 10);
+
+    if (commits.length === 0) {
+      return [`## [${version}] - ${date}`, '', '### Changed', '', '- Version bump', ''].join('\n');
+    }
+
+    // Try LLM-generated changelog
+    const llmEntry = await this.generateWithLLM(version, date, commits);
+    if (llmEntry) return llmEntry;
+
+    // Fallback: plain commit list
+    const lines = [`## [${version}] - ${date}`, '', '### Changed', ''];
+    for (const msg of commits) {
+      lines.push(`- ${msg}`);
+    }
+    lines.push('');
+    return lines.join('\n');
+  }
+
+  private async generateWithLLM(version: string, date: string, commits: string[]): Promise<string | null> {
+    try {
+      const models = await this.ollama.list();
+      const hasModel = models.models.some((m) => m.name.startsWith('phi4'));
+      if (!hasModel) return null;
+
+      const commitList = commits.map((c) => `- ${c}`).join('\n');
+      const prompt = `You are a changelog writer. Given these git commits, generate a concise, well-organized changelog entry in Keep a Changelog format.
+
+Group changes into appropriate sections: Added, Changed, Fixed, Removed (only include sections that apply).
+Rewrite commit messages into clear, user-facing descriptions. Merge related commits into single entries when appropriate.
+
+Commits:
+${commitList}
+
+Output ONLY the markdown sections (### Added, ### Changed, etc.) with bullet points. No header, no version line.`;
+
+      const response = await this.ollama.generate({ model: 'phi4', prompt, stream: false });
+      const sections = response.response.trim();
+
+      if (!sections || sections.length < 10) return null;
+
+      return [`## [${version}] - ${date}`, '', sections, ''].join('\n');
+    } catch {
+      return null;
+    }
+  }
+
+  private async readChangelog(path: string): Promise<string> {
+    try {
+      return await readFile(path, 'utf-8');
+    } catch {
+      return '';
+    }
+  }
+
+  private prependEntry(existing: string, entry: string): string {
+    if (!existing) return HEADER + '\n' + entry;
+
+    const headerIndex = existing.indexOf('# Changelog');
+    if (headerIndex !== -1) {
+      const afterHeader = existing.indexOf('\n', headerIndex);
+      if (afterHeader !== -1) {
+        const before = existing.slice(0, afterHeader + 1);
+        const after = existing.slice(afterHeader + 1);
+        return before + '\n' + entry + after;
+      }
+    }
+
+    return HEADER + '\n' + entry + existing;
+  }
+}

package/src/version/version-bumper.ts

@@ -0,0 +1,116 @@
+import { createInterface } from 'node:readline';
+import { readFile, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import semver from 'semver';
+import { run } from '../shared/process-runner.js';
+import { logger } from '../shared/logger.js';
+import { OctoError } from '../shared/errors.js';
+
+export type BumpType = 'patch' | 'minor' | 'major';
+
+export interface BumpOptions {
+  push?: boolean;
+  tag?: boolean;
+  auto?: boolean;
+}
+
+export interface BumpResult {
+  package: string;
+  previousVersion: string;
+  newVersion: string;
+  propagated: PropagationEntry[];
+}
+
+export interface PropagationEntry {
+  project: string;
+  previousVersion: string;
+  newVersion: string;
+  skipped?: boolean;
+  reason?: string;
+}
+
+function confirm(message: string): Promise<boolean> {
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  return new Promise((resolve) => {
+    rl.question(message, (answer) => {
+      rl.close();
+      resolve(answer.trim().toLowerCase() === 'y');
+    });
+  });
+}
+
+export class VersionBumper {
+  async bump(packageDir: string, packageName: string, type: BumpType = 'patch', options: BumpOptions = {}): Promise<BumpResult> {
+    const pkgJsonPath = join(packageDir, 'package.json');
+    const originalContent = await readFile(pkgJsonPath, 'utf-8');
+    const pkg = JSON.parse(originalContent);
+    const previousVersion: string = pkg.version;
+
+    if (!semver.valid(previousVersion)) {
+      throw new OctoError(`Invalid version in package.json: ${previousVersion}`);
+    }
+
+    const newVersion = semver.inc(previousVersion, type);
+    if (!newVersion) {
+      throw new OctoError(`Failed to increment version ${previousVersion} with type ${type}`);
+    }
+
+    // Check uncommitted changes (skip in auto mode)
+    if (!options.auto) {
+      const status = await run('git', ['status', '--porcelain'], { cwd: packageDir });
+      if (status.stdout.trim().length > 0) {
+        logger.warn(`Uncommitted changes detected in ${packageName}:`);
+        logger.info(status.stdout.trim());
+        const accepted = await confirm('Continue with bump? (y/n) ');
+        if (!accepted) {
+          throw new OctoError('Bump aborted by user');
+        }
+      }
+    }
+
+    // Write new version
+    pkg.version = newVersion;
+    await writeFile(pkgJsonPath, JSON.stringify(pkg, null, 2) + '\n', 'utf-8');
+    logger.info(`${packageName}: ${previousVersion} → ${newVersion}`);
+
+    // Run build
+    const buildResult = await run('pnpm', ['run', 'build'], { cwd: packageDir });
+    if (buildResult.exitCode !== 0) {
+      await writeFile(pkgJsonPath, originalContent, 'utf-8');
+      logger.error(`Build failed for ${packageName}. Rollback applied.`);
+      logger.error(buildResult.stderr || buildResult.stdout);
+      throw new OctoError(`Build failed after bump of ${packageName}`);
+    }
+
+    // Commit
+    const commitMsg = `chore(${packageName}): bump version to ${newVersion}`;
+    await run('git', ['add', pkgJsonPath], { cwd: packageDir });
+    await run('git', ['commit', '-m', commitMsg], { cwd: packageDir });
+    logger.info(`Commit: ${commitMsg}`);
+
+    // Tag (if --tag or --auto)
+    if (options.tag || options.auto) {
+      const tagName = `${packageName}@${newVersion}`;
+      await run('git', ['tag', '-a', tagName, '-m', `Release ${tagName}`], { cwd: packageDir });
+      logger.info(`Tag created: ${tagName}`);
+    }
+
+    // Push (if --push or --auto)
+    if (options.push || options.auto) {
+      const pushResult = await run('git', ['push', '--follow-tags'], { cwd: packageDir });
+      if (pushResult.exitCode !== 0) {
+        logger.error(`Push failed: ${pushResult.stderr}`);
+      } else {
+        logger.info('Pushed to remote with tags.');
+      }
+    }
+
+    return { package: packageName, previousVersion, newVersion, propagated: [] };
+  }
+
+  async rollback(packageDir: string, originalContent: string): Promise<void> {
+    const pkgJsonPath = join(packageDir, 'package.json');
+    await writeFile(pkgJsonPath, originalContent, 'utf-8');
+    logger.info('Rollback of package.json complete.');
+  }
+}