help simplified

.structify/history.json

@@ -10,6 +10,22 @@
     "summary": "Generated Graph"
   },
   {
+    "id": "3f6df786-8828-4725-9aa7-0a279ca9d856",
+    "timestamp": "2026-08-03T11:42:54.024Z",
+    "version": "1.0.1",
+    "operation": "deps",
+    "status": "success",
+    "duration": 94.2069,
+    "filesChanged": [],
+    "summary": "Dependency Audit"
+  },
+  {
+    "id": "0898d986-a491-4d87-a774-0ed0b2622f74",
+    "timestamp": "2026-08-03T11:43:04.650Z",
+    "version": "1.0.1",
+    "operation": "graph",
+    "status": "success",
+    "duration": 150.2621,
     "id": "411f1106-292d-4a47-a796-a158c4c39e7c",
     "timestamp": "2026-07-10T06:49:45.458Z",
     "version": "1.0.1",

apps/cli/src/commands/index.ts

@@ -438,13 +438,14 @@ export function registerCommands(program: Command): void {
 
   program
     .command('upgrade')
-    .description('Preview or apply safe Structify project upgrades')
+    .description('Preview or apply safe Structify project upgrades or CLI updates')
     .option('-d, --dry-run', 'Preview upgrade plan without writing files')
     .option('-y, --yes', 'Apply safe metadata/package upgrades without confirmation')
+    .option('--cli', 'Check for updates to the structify-tool CLI package')
     .option('--path <path>', 'Project path to upgrade')
     .addHelpText(
       'after',
-      '\nExamples:\n  $ structify upgrade --dry-run\n  $ structify upgrade --json',
+      '\nExamples:\n  $ structify upgrade --dry-run\n  $ structify upgrade --cli\n  $ structify upgrade --json',
     )
     .action(async (options, commandInstance) => {
       const globalOpts = program.opts();

apps/cli/src/commands/upgrade.ts

@@ -5,18 +5,51 @@ import { StructifyCLIError } from '../utils/error.js';
 import { getElapsedMs } from '../utils/middleware.js';
 import { createUpgradePlan, executePatchPlan, appendHistoryEntry } from '@structify/core';
 
+import { checkCliVersionUpdate } from '../utils/version.js';
+
 export interface UpgradeOptions {
   dryRun?: boolean;
   yes?: boolean;
+  cli?: boolean;
   path?: string;
 }
 
 export async function handleUpgrade(options: UpgradeOptions, context: CLIContext): Promise<void> {
   const output = new CLIOutput(context);
+  const elapsed = getElapsedMs(context.startTime);
+
+  if (options.cli) {
+    const updateCheck = await checkCliVersionUpdate(context.packageVersion);
+    if (context.json) {
+      output.json({
+        success: true,
+        command: 'upgrade --cli',
+        timestamp: new Date().toISOString(),
+        durationMs: elapsed,
+        data: updateCheck,
+      });
+      return;
+    }
+
+    output.heading('Structify CLI Package Update Status');
+    output.info(`Current Version: v${updateCheck.currentVersion}`);
+    output.info(`Latest Version on npm: v${updateCheck.latestVersion}`);
+    output.info('');
+    if (updateCheck.updateAvailable) {
+      output.warn(
+        `An update is available! (v${updateCheck.currentVersion} → v${updateCheck.latestVersion})`,
+      );
+      output.info(`To upgrade, run: ${updateCheck.updateCommand}`);
+    } else {
+      output.success('Structify CLI is up to date!');
+    }
+    output.showFooter('upgrade');
+    return;
+  }
+
   output.heading('Structify Project Upgrade');
   const projectPath = path.resolve(context.cwd, options.path ?? '.');
   const upgrade = createUpgradePlan(projectPath);
-  const elapsed = getElapsedMs(context.startTime);
 
   if (context.json) {
     if (!options.dryRun && options.yes && !upgrade.reviewRequired) {

apps/cli/src/commands/validate.ts

@@ -53,10 +53,31 @@ export async function handleValidate(options: ValidateOptions, context: CLIConte
       throw new StructifyCLIError('VALIDATION_ERROR', `Failed to parse config file JSON: ${msg}`);
     }
   } else {
-    throw new StructifyCLIError(
-      'USAGE_ERROR',
-      'Please specify a configuration path using "--config <path>" or use "--example" to check the built-in demo configuration.',
-    );
+    // Auto-discover structify.config.json or structify.json in cwd
+    const defaultConfigPath = path.join(context.cwd, 'structify.config.json');
+    const altConfigPath = path.join(context.cwd, 'structify.json');
+    let targetPath: string | null = null;
+
+    if (fs.existsSync(defaultConfigPath)) {
+      targetPath = defaultConfigPath;
+    } else if (fs.existsSync(altConfigPath)) {
+      targetPath = altConfigPath;
+    }
+
+    if (targetPath) {
+      output.info(`Auto-detected config file: ${path.basename(targetPath)}`);
+      try {
+        configToValidate = JSON.parse(fs.readFileSync(targetPath, 'utf8'));
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        throw new StructifyCLIError('VALIDATION_ERROR', `Failed to parse config file JSON: ${msg}`);
+      }
+    } else {
+      throw new StructifyCLIError(
+        'USAGE_ERROR',
+        'No structify.config.json or structify.json found in current directory. Specify a path using "--config <path>" or use "--example" to check the demo config.',
+      );
+    }
   }
 
   const result = validateStack(configToValidate as ProjectConfig);

apps/cli/src/context.ts

@@ -40,9 +40,9 @@ export function createCLIContext(
 ): CLIContext {
   const argList = args || [];
   const manualNoColor = argList.includes('--no-color');
-  const manualVerbose = argList.includes('--verbose');
-  const manualDebug = argList.includes('--debug');
-  const manualJson = argList.includes('--json');
+  const manualVerbose = argList.includes('--no-verbose') ? false : argList.includes('--verbose');
+  const manualDebug = argList.includes('--no-debug') ? false : argList.includes('--debug');
+  const manualJson = argList.includes('--no-json') ? false : argList.includes('--json');
 
   let manualCwd: string | undefined;
   const cwdIdx = argList.indexOf('--cwd');
@@ -51,9 +51,9 @@ export function createCLIContext(
   }
 
   const targetCwd = options.cwd
-    ? path.resolve(options.cwd)
+    ? path.resolve(process.cwd(), options.cwd)
     : manualCwd
-      ? path.resolve(manualCwd)
+      ? path.resolve(process.cwd(), manualCwd)
       : process.cwd();
 
   let detectedPackageManager: 'npm' | 'none' = 'none';
@@ -65,6 +65,10 @@ export function createCLIContext(
     // Fail silently
   }
 
+  const debugVal = options.debug !== undefined ? options.debug : manualDebug;
+  const verboseVal = options.verbose !== undefined ? options.verbose : manualVerbose;
+  const jsonVal = options.json !== undefined ? options.json : manualJson;
+
   return {
     packageName: 'structify-tool',
     packageVersion: getCliVersion(),
@@ -75,9 +79,9 @@ export function createCLIContext(
     nodeVersion: process.version,
     platform: os.platform(),
     arch: os.arch(),
-    debug: !!options.debug || manualDebug,
-    verbose: !!options.verbose || manualVerbose,
-    json: !!options.json || manualJson,
+    debug: debugVal,
+    verbose: verboseVal,
+    json: jsonVal,
     noColor: !!options.noColor || manualNoColor || process.env.NO_COLOR === 'true',
     isCI: process.env.CI === 'true',
     isTTY: process.stdout.isTTY ?? false,

apps/cli/src/index.spec.ts

@@ -120,7 +120,7 @@ describe('CLI Shell Unit Tests', () => {
     it('should not hardcode the Commander version output', () => {
       const source = fs.readFileSync(path.resolve(__dirname, 'index.ts'), 'utf8');
 
-      expect(source).toContain('.version(getCliVersion())');
+      expect(source).toContain('.version(getCliVersion()');
       expect(source).not.toContain(".version('1.0.0')");
       expect(source).not.toContain('.version("1.0.0")');
     });