Adding comprehensive debug logging.

adrianwebb · adrianwebb · commit e6d8fd165bcc · 2025-12-11T16:44:01.000-05:00
diff --git a/src/commands/build.ts b/src/commands/build.ts
@@ -3,6 +3,7 @@ import { BaseCommand } from '../core/BaseCommand';
 import fs from 'fs-extra';
 import path from 'path';
 import { runCommand } from '../utils/shell.js';
+import { logger } from '../utils/logger.js';
 
 export default class BuildCommand extends BaseCommand {
     static paths = [['build']];
@@ -23,9 +24,12 @@ export default class BuildCommand extends BaseCommand {
         const contentDir = path.resolve(srcDir, 'content');
         const publicDir = path.resolve(this.projectRoot, 'public');
 
+        logger.debug('Build paths resolved:', { siteDir, srcDir, coreDir, modulesDir, contentDir, publicDir });
+
         this.info('Building for production...');
 
         // 1. Clean _site
+        logger.debug(`Cleaning site directory: ${siteDir}`);
         await fs.remove(siteDir);
         await fs.ensureDir(siteDir);
 
@@ -63,6 +67,7 @@ export default class BuildCommand extends BaseCommand {
         // 6. Run Astro using local binary from project root
         // This avoids relying on global npx or PATH issues in tests
         const astroBin = path.join(this.projectRoot, 'node_modules', '.bin', 'astro');
+        logger.debug(`Using astro binary at: ${astroBin}`);
 
         try {
             await runCommand(`${astroBin} build`, siteDir);
diff --git a/src/commands/clean.ts b/src/commands/clean.ts
@@ -2,6 +2,7 @@
 import { BaseCommand } from '../core/BaseCommand';
 import fs from 'fs-extra';
 import path from 'path';
+import { logger } from '../utils/logger.js';
 
 export default class CleanCommand extends BaseCommand {
     static paths = [['clean']];
@@ -17,6 +18,7 @@ export default class CleanCommand extends BaseCommand {
 
         for (const target of targets) {
             const targetPath = path.resolve(process.cwd(), target);
+            logger.debug(`Checking clean target: ${targetPath}`);
             if (await fs.pathExists(targetPath)) {
                 await fs.remove(targetPath);
                 // BaseCommand doesn't expose logger property, use helpers or import
diff --git a/src/commands/dev.ts b/src/commands/dev.ts
@@ -4,6 +4,7 @@ import fs from 'fs-extra';
 import path from 'path';
 import { spawn } from 'child_process';
 import process from 'node:process';
+import { logger } from '../utils/logger.js';
 
 export default class DevCommand extends BaseCommand {
     static paths = [['dev']];
@@ -23,6 +24,7 @@ export default class DevCommand extends BaseCommand {
 
         try {
             const { prepareEnvironment } = await import('../utils/environment.js');
+            logger.debug(`Preparing environment at: ${this.projectRoot}`);
             await prepareEnvironment(this.projectRoot);
         } catch (error: any) {
             this.error(error);
@@ -32,6 +34,7 @@ export default class DevCommand extends BaseCommand {
         this.success('Environment ready. Starting Astro...');
 
         const astroBin = path.join(this.projectRoot, 'node_modules', '.bin', 'astro');
+        logger.debug(`Spawning astro dev from: ${astroBin} in ${siteDir}`);
 
         const child = spawn(astroBin, ['dev'], {
             cwd: siteDir,
diff --git a/src/commands/init.ts b/src/commands/init.ts
@@ -4,6 +4,7 @@ import * as git from '../utils/git.js';
 import { runCommand } from '../utils/shell.js';
 import fs from 'node:fs';
 import path from 'node:path';
+import { logger } from '../utils/logger.js';
 
 export default class InitCommand extends BaseCommand {
     static description = 'Initialize a new Astrical project';
@@ -30,8 +31,11 @@ export default class InitCommand extends BaseCommand {
         // Handle gh@ syntax
         if (repoUrl.startsWith('gh@')) {
             repoUrl = `https://github.com/${repoUrl.substring(3)}.git`;
+            logger.debug(`Resolved gh@ shorthad to: ${repoUrl}`);
         }
 
+        logger.debug('Init options:', { directory, targetPath, repoUrl });
+
         this.info(`Initializing project in: ${targetPath}`);
         this.info(`Using starter repository: ${repoUrl}`);
 
diff --git a/src/commands/module/add.ts b/src/commands/module/add.ts
@@ -3,6 +3,7 @@ import { BaseCommand } from '../../core/BaseCommand';
 import fs from 'fs-extra';
 import path from 'path';
 import { runCommand } from '../../utils/shell.js';
+import { logger } from '../../utils/logger.js';
 
 export default class ModuleAddCommand extends BaseCommand {
     static paths = [['module', 'add']];
@@ -18,7 +19,7 @@ export default class ModuleAddCommand extends BaseCommand {
     };
 
     async run(options: any) {
-        console.log('DEBUG: ModuleAdd Options:', JSON.stringify(options, null, 2));
+        logger.debug('ModuleAdd Options:', options);
         let { url, name } = options;
 
         if (!this.projectRoot) {
@@ -54,10 +55,15 @@ export default class ModuleAddCommand extends BaseCommand {
 
         this.info(`Adding submodule ${name} from ${url}...`);
 
-        console.log('DEBUG: projectRoot', this.projectRoot);
-        console.log('DEBUG: targetDir', targetDir);
-        console.log('DEBUG: relativeTargetDir', relativeTargetDir);
-        console.log('DEBUG: Executing git submodule add', url, relativeTargetDir);
+        this.info(`Adding submodule ${name} from ${url}...`);
+
+        logger.debug('Module Add Context:', {
+            projectRoot: this.projectRoot,
+            targetDir,
+            relativeTargetDir,
+            url
+        });
+        logger.debug('Executing git submodule add...');
 
         try {
             await runCommand(`git submodule add ${url} ${relativeTargetDir}`, this.projectRoot);
diff --git a/src/commands/module/list.ts b/src/commands/module/list.ts
@@ -2,6 +2,7 @@
 import { BaseCommand } from '../../core/BaseCommand';
 import fs from 'fs-extra';
 import path from 'path';
+import { logger } from '../../utils/logger.js';
 
 export default class ModuleListCommand extends BaseCommand {
     static paths = [['module', 'list']];
@@ -16,6 +17,7 @@ export default class ModuleListCommand extends BaseCommand {
         }
 
         const modulesDir = path.resolve(this.projectRoot, 'src', 'modules');
+        logger.debug(`Scanning for modules in: ${modulesDir}`);
 
         if (!(await fs.pathExists(modulesDir))) {
             this.info('No modules installed (src/modules directory missing).');
diff --git a/src/commands/module/remove.ts b/src/commands/module/remove.ts
@@ -3,6 +3,7 @@ import { BaseCommand } from '../../core/BaseCommand';
 import fs from 'fs-extra';
 import path from 'path';
 import { runCommand } from '../../utils/shell.js';
+import { logger } from '../../utils/logger.js';
 
 export default class ModuleRemoveCommand extends BaseCommand {
     static paths = [['module', 'remove']];
@@ -25,6 +26,8 @@ export default class ModuleRemoveCommand extends BaseCommand {
         const relativePath = `src/modules/${name}`;
         const fullPath = path.resolve(this.projectRoot, relativePath);
 
+        logger.debug('Removing module at:', fullPath);
+
         if (!(await fs.pathExists(fullPath))) {
             this.error(`Module ${name} not found at ${relativePath}.`);
             return;
diff --git a/src/commands/module/update.ts b/src/commands/module/update.ts
@@ -3,6 +3,7 @@ import { BaseCommand } from '../../core/BaseCommand';
 import fs from 'fs-extra';
 import path from 'path';
 import { runCommand } from '../../utils/shell.js';
+import { logger } from '../../utils/logger.js';
 
 export default class ModuleUpdateCommand extends BaseCommand {
     static paths = [['module', 'update']];
@@ -23,6 +24,7 @@ export default class ModuleUpdateCommand extends BaseCommand {
         }
 
         this.info(name ? `Updating module ${name}...` : 'Updating all modules...');
+        logger.debug('Update context:', { name, projectRoot: this.projectRoot });
 
         try {
             if (name) {
diff --git a/src/commands/preview.ts b/src/commands/preview.ts
@@ -4,6 +4,7 @@ import fs from 'fs-extra';
 import path from 'path';
 import { spawn } from 'child_process';
 import process from 'node:process';
+import { logger } from '../utils/logger.js';
 
 export default class PreviewCommand extends BaseCommand {
     static paths = [['preview']];
@@ -20,6 +21,8 @@ export default class PreviewCommand extends BaseCommand {
         const siteDir = path.resolve(this.projectRoot, '_site');
         const distDir = path.join(siteDir, 'dist');
 
+        logger.debug('Preview paths:', { siteDir, distDir });
+
         if (!(await fs.pathExists(distDir))) {
             this.error("Please run 'astrical build' first.");
             return;
@@ -28,6 +31,7 @@ export default class PreviewCommand extends BaseCommand {
         this.info('Starting preview server...');
 
         const astroBin = path.join(this.projectRoot, 'node_modules', '.bin', 'astro');
+        logger.debug(`Spawning astro preview from: ${astroBin} in ${siteDir}`);
 
         const child = spawn(astroBin, ['preview'], {
             cwd: siteDir,
diff --git a/src/commands/run.ts b/src/commands/run.ts
@@ -5,6 +5,7 @@ import path from 'path';
 import { spawn } from 'child_process';
 import process from 'node:process';
 import { prepareEnvironment } from '../utils/environment.js';
+import { logger } from '../utils/logger.js';
 
 export default class RunCommand extends BaseCommand {
     static paths = [['run']];
@@ -37,6 +38,8 @@ export default class RunCommand extends BaseCommand {
         await prepareEnvironment(this.projectRoot!);
         const siteDir = path.resolve(this.projectRoot!, '_site');
 
+        logger.debug('Run command context:', { script, args: scriptArgs, siteDir });
+
         // Initialize command to default npm run
         let finalCmd = 'npm';
         let finalArgs = ['run', script, '--', ...scriptArgs];
@@ -45,6 +48,7 @@ export default class RunCommand extends BaseCommand {
         if (script.includes(':')) {
             const [moduleName, scriptName] = script.split(':');
             const modulePath = path.resolve(this.projectRoot!, 'src', 'modules', moduleName);
+            logger.debug(`Resolving module script: ${moduleName}:${scriptName} at ${modulePath}`);
 
             // Check if module exists
             const modulePkgJsonPath = path.join(modulePath, 'package.json');
@@ -74,6 +78,8 @@ export default class RunCommand extends BaseCommand {
             }
         }
 
+        logger.debug(`Executing final command: ${finalCmd} ${finalArgs.join(' ')} `);
+
         const child = spawn(finalCmd, finalArgs, {
             cwd: siteDir,
             stdio: 'inherit',
diff --git a/src/core/CLI.ts b/src/core/CLI.ts
@@ -6,6 +6,7 @@ import fs from 'node:fs';
 import { fileURLToPath } from 'node:url';
 import pc from 'picocolors';
 import pkg from '../../package.json';
+import { logger, setDebugMode } from '../utils/logger.js';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 
@@ -31,6 +32,12 @@ export class CLI {
         // Strategy: Try both relative locations (sibling 'commands' folder)
         // because tsup might put index.js at root of dist, and commands in dist/commands
 
+        // Check for debug flag early
+        if (process.argv.includes('--debug')) {
+            setDebugMode(true);
+            logger.debug('Debug mode enabled via --debug flag');
+        }
+
         const possibleDirs = [
             path.resolve(__dirname, 'commands'),
             path.resolve(__dirname, '../commands'),
@@ -47,7 +54,7 @@ export class CLI {
 
         // Fallback or error
         if (!commandsDir) {
-            // logger.debug("No commands directory found.");
+            logger.debug("No commands directory found.");
         }
 
         this.loadedCommands = await this.loader.load(commandsDir);
diff --git a/src/core/CommandLoader.ts b/src/core/CommandLoader.ts
@@ -1,6 +1,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { BaseCommand } from './BaseCommand.js';
+import { logger } from '../utils/logger.js';
 
 export interface LoadedCommand {
     command: string; // "module add"
@@ -18,7 +19,9 @@ export class CommandLoader {
     }
 
     async load(commandsDir: string): Promise<LoadedCommand[]> {
+        logger.debug(`Loading commands from: ${commandsDir}`);
         if (!fs.existsSync(commandsDir)) {
+            logger.debug(`Commands directory not found: ${commandsDir}`);
             return [];
         }
 
@@ -39,6 +42,7 @@ export class CommandLoader {
                 // Ignore index files or non-command files if needed, but for now scan all.
                 // Assuming "index.ts" might be the command for the directory path itself if we supported that,
                 // but let's stick to "create.ts" -> "create"
+                logger.debug(`Found potential command file: ${fullPath}`);
 
                 const name = path.basename(file, path.extname(file));
                 const commandParts = [...prefix];
@@ -56,6 +60,7 @@ export class CommandLoader {
 
                     if (CommandClass) { // Loose check for now to debug
                         const commandName = commandParts.join(' ');
+                        logger.debug(`Registered command: ${commandName}`);
                         this.commands.push({
                             command: commandName,
                             path: fullPath,
@@ -64,7 +69,7 @@ export class CommandLoader {
                         });
                     }
                 } catch (e) {
-                    console.error(`Failed to load command at ${fullPath}`, e);
+                    logger.error(`Failed to load command at ${fullPath}`, e);
                 }
             }
         }
diff --git a/src/index.ts b/src/index.ts
@@ -1,7 +1,9 @@
 #!/usr/bin/env node
 import { CLI } from './core/CLI.js';
 
-console.log('DEBUG: CLI ENTRY POINT HIT', process.argv);
+import { logger } from './utils/logger.js';
+
+logger.debug('CLI ENTRY POINT HIT', process.argv);
 
 const app = new CLI();
 app.start();
diff --git a/src/utils/config.ts b/src/utils/config.ts
@@ -2,6 +2,7 @@ import { lilconfig, type Loader } from 'lilconfig';
 import fs from 'node:fs';
 import path from 'node:path';
 import YAML from 'yaml';
+import { logger } from './logger.js';
 
 export const loadYaml: Loader = (filepath, content) => {
     return YAML.parse(content);
@@ -21,6 +22,7 @@ export async function findProjectRoot(startDir: string): Promise<string | null>
 
     const result = await explorer.search(startDir);
     if (result) {
+        logger.debug(`Project root found at: ${path.dirname(result.filepath)}`);
         return path.dirname(result.filepath);
     }
 
@@ -37,5 +39,6 @@ export async function loadConfig(rootDir: string): Promise<any> {
         }
     });
     const result = await explorer.search(rootDir);
+    logger.debug(result ? `Loaded config from ${result.filepath}` : `No config found in ${rootDir}`);
     return result ? result.config : {};
 }
diff --git a/src/utils/environment.ts b/src/utils/environment.ts
@@ -1,7 +1,7 @@
 
 import fs from 'fs-extra';
 import path from 'path';
-import { logger } from './logger';
+import { logger } from './logger.js';
 
 export async function prepareEnvironment(projectRoot: string) {
     const siteDir = path.resolve(projectRoot, '_site');
@@ -11,6 +11,8 @@ export async function prepareEnvironment(projectRoot: string) {
     const contentDir = path.resolve(srcDir, 'content');
     const publicDir = path.resolve(projectRoot, 'public');
 
+    logger.debug('Preparing environment paths:', { siteDir, srcDir });
+
     // 1. Ensure _site exists
     await fs.ensureDir(siteDir);
 
diff --git a/src/utils/git.ts b/src/utils/git.ts
@@ -1,11 +1,14 @@
 import { runCommand } from './shell.js';
+import { logger } from './logger.js';
 
 export async function clone(url: string, destination: string, recursive = false): Promise<void> {
     const cmd = `git clone ${recursive ? '--recursive ' : ''}${url} .`;
+    logger.debug(`Git clone: ${url} to ${destination}`);
     await runCommand(cmd, destination);
 }
 
 export async function updateSubmodules(cwd: string): Promise<void> {
+    logger.debug(`Updating submodules in ${cwd}`);
     await runCommand('git submodule foreach --recursive "git checkout main && git pull origin main"', cwd);
 }
 
diff --git a/src/utils/logger.ts b/src/utils/logger.ts
@@ -1,7 +1,12 @@
-import { consola } from 'consola';
+import { consola, LogLevels } from 'consola';
 
 export const logger = consola.create({
     defaults: {
         tag: 'astrical',
     },
+    level: LogLevels.info, // Default to info
 });
+
+export function setDebugMode(enabled: boolean) {
+    logger.level = enabled ? LogLevels.debug : LogLevels.info;
+}
diff --git a/src/utils/shell.ts b/src/utils/shell.ts
@@ -6,6 +6,7 @@ const execAsync = promisify(exec);
 
 export async function runCommand(command: string, cwd?: string): Promise<void> {
     try {
+        logger.debug(`Executing command: ${command} in ${cwd || process.cwd()}`);
         const { stdout } = await execAsync(command, { cwd });
         if (stdout) {
             console.log(stdout);
diff --git a/test/unit/core/CLI.test.ts b/test/unit/core/CLI.test.ts
diff --git a/test/unit/core/CommandLoader.test.ts b/test/unit/core/CommandLoader.test.ts
diff --git a/test/unit/utils/logger.test.ts b/test/unit/utils/logger.test.ts
