Merge pull request #261 from PaulJPhilp/codex/ep-admin-help-discoverability

ep-admin DX: compact root help, actionable error endings, and next-step nudges

Author: PaulJPhilp

packages/ep-admin/src/__tests__/cli-auth-contract.test.ts

@@ -59,6 +59,7 @@ describe.sequential("CLI auth and DX contract", () => {
 			const typo = runCli(["opz"], env);
 			expect(typo.status).toBe(1);
 			expect(typo.stderr).toContain("Did you mean: ep-admin ops");
+			expect(typo.stderr).toContain("Run: ep-admin --help");
 			expect(typo.stderr).not.toContain("auth has not been initialized");
 		} finally {
 			await rm(tempDir, { recursive: true, force: true });
@@ -71,6 +72,9 @@ describe.sequential("CLI auth and DX contract", () => {
       const help = runCli(["--help"], env);
       expect(help.status).toBe(0);
       expect(help.stdout).toContain("ep-admin");
+      expect(help.stdout).toContain("Top-level commands:");
+      expect(help.stdout).not.toContain("pattern pattern");
+      expect(help.stdout).not.toContain("data data");
 
       const version = runCli(["--version"], env);
       expect(version.status).toBe(0);

packages/ep-admin/src/__tests__/cli-json-contract.test.ts

@@ -111,11 +111,13 @@ describe.sequential("CLI JSON machine contract", () => {
 			expect(dbFailure.status).toBe(1);
 			expect(dbFailure.stdout.trim()).toBe("");
 			expect(dbFailure.stderr.trim().length).toBeGreaterThan(0);
+			expect(dbFailure.stderr).toContain("Run: ep-admin db --help");
 
 			const ingestFailure = runCli(["data", "ingest", "status", "--json"], automationEnv);
 			expect(ingestFailure.status).toBe(1);
 			expect(ingestFailure.stdout.trim()).toBe("");
 			expect(ingestFailure.stderr.trim().length).toBeGreaterThan(0);
+			expect(ingestFailure.stderr).toContain("Run: ep-admin data --help");
 		} finally {
 			await rm(tempDir, { recursive: true, force: true });
 		}

packages/ep-admin/src/index.ts

@@ -198,6 +198,63 @@ const NESTED_COMMANDS: Record<string, readonly string[]> = {
 	release: ["preview", "create"],
 };
 
+const ROOT_HELP_COMMANDS: ReadonlyArray<{
+	readonly name: string;
+	readonly description: string;
+}> = [
+	{ name: "auth", description: "Initialize/login/logout and check admin session state" },
+	{ name: "publish", description: "Validate, test, publish, and generate release artifacts" },
+	{ name: "pattern", description: "Search patterns and generate skill assets" },
+	{ name: "data", description: "Run ingest, Discord, and QA workflows" },
+	{ name: "db", description: "Inspect, test, and migrate database state" },
+	{ name: "dev", description: "Run development utilities and autofix tools" },
+	{ name: "ops", description: "Run health checks and maintenance commands" },
+	{ name: "config", description: "Install rules/skills and manage entities" },
+	{ name: "system", description: "Generate/install shell completions" },
+	{ name: "release", description: "Preview and create tagged releases" },
+];
+
+const renderCompactRootHelp = (): string => {
+	const lines = [
+		`${CLI.RUNNER_NAME} ${CLI.VERSION}`,
+		"",
+		CLI.DESCRIPTION,
+		"",
+		"USAGE",
+		"  ep-admin <command> [subcommand] [options]",
+		"",
+		"Top-level commands:",
+		...ROOT_HELP_COMMANDS.map(
+			(command) => `  ${command.name.padEnd(10)} ${command.description}`
+		),
+		"",
+		"Get detailed help:",
+		"  ep-admin <command> --help",
+		"",
+		"Quick start:",
+		"  ep-admin auth init",
+		"  ep-admin auth login",
+		"  ep-admin ops health-check",
+		"  ep-admin publish pipeline",
+		"",
+		`Docs: ${EP_ADMIN_DOCS_URL}`,
+	];
+	return lines.join("\n");
+};
+
+const isRootHelpRequest = (argv: ReadonlyArray<string>): boolean => {
+	const args = argv.slice(2);
+	if (args.length === 0) return true;
+
+	const hasHelpFlag = args.includes("--help") || args.includes("-h");
+	if (!hasHelpFlag) return false;
+
+	const hasPositional = args.some(
+		(token) => token.length > 0 && !token.startsWith("-")
+	);
+	return !hasPositional;
+};
+
 const normalizeArgsForSuggestion = (argv: ReadonlyArray<string>): string[] =>
 	argv.slice(2).filter((token) => token.length > 0 && !token.startsWith("-"));
 
@@ -280,6 +337,34 @@ const getPreAuthCommandMismatchMessage = (argv: ReadonlyArray<string>): string |
 	return null;
 };
 
+const getContextualHelpCommand = (argv: ReadonlyArray<string>): string => {
+	const args = normalizeArgsForSuggestion(argv);
+	const first = args[0];
+	if (first && ROOT_COMMANDS.includes(first as (typeof ROOT_COMMANDS)[number])) {
+		return `ep-admin ${first} --help`;
+	}
+	return "ep-admin --help";
+};
+
+const appendStandardErrorGuidance = (
+	message: string,
+	argv: ReadonlyArray<string>
+): string => {
+	const trimmed = message.trim();
+	const lines = trimmed.length > 0 ? [trimmed] : [];
+	const hasRunLine = /\bRun:\s*ep-admin\b/i.test(trimmed);
+	const hasDocsLine = /\bDocs:\s*https?:\/\//i.test(trimmed);
+
+	if (!hasRunLine) {
+		lines.push(`Run: ${getContextualHelpCommand(argv)}`);
+	}
+	if (!hasDocsLine) {
+		lines.push(`Docs: ${EP_ADMIN_DOCS_URL}`);
+	}
+
+	return lines.join("\n");
+};
+
 const isAuthExemptArgv = (argv: ReadonlyArray<string>): boolean => {
 	const args = argv.slice(2);
 	if (args.length === 0) return true;
@@ -478,24 +563,26 @@ const extractErrorMessage = (error: unknown, argv: ReadonlyArray<string>): strin
 		}
 	}
 
-	if (typeof resolvedError === "string") return resolvedError;
+	if (typeof resolvedError === "string") {
+		return appendStandardErrorGuidance(resolvedError, argv);
+	}
 
 	if (resolvedError instanceof Error) {
 		const combined = [resolvedError.message, resolvedError.stack].filter(Boolean).join("\n");
 		if (combined.includes("CommandMismatch")) {
 			const suggestion = getCommandSuggestion(argv);
-			return [
+			return appendStandardErrorGuidance(
 				suggestion ? suggestion : "Need command help? Run 'ep-admin --help'.",
-				`Docs: ${EP_ADMIN_DOCS_URL}`,
-			].join("\n");
+				argv
+			);
 		}
 
 		if (resolvedError.message.trim()) {
-			return `${resolvedError.message.trim()}\nDocs: ${EP_ADMIN_DOCS_URL}`;
+			return appendStandardErrorGuidance(resolvedError.message, argv);
 		}
 	}
 
-	return String(resolvedError);
+	return appendStandardErrorGuidance(String(resolvedError), argv);
 };
 
 export const createAdminProgram = (
@@ -506,6 +593,11 @@ export const runCli = (
 	argv: ReadonlyArray<string> = process.argv
 ): Effect.Effect<void, unknown, never> =>
 	Effect.gen(function* () {
+		if (isRootHelpRequest(argv)) {
+			yield* Console.log(renderCompactRootHelp());
+			return;
+		}
+
 		const prepared = normalizeLegacyArgs(argv);
 		for (const warning of prepared.warnings) {
 			yield* Console.error(`⚠ ${warning}`);

packages/ep-admin/src/ingest-commands.ts

@@ -93,6 +93,9 @@ export const ingestProcessCommand = Command.make("process", {
             }
 
             yield* Display.showSuccess(MESSAGES.SUCCESS.PATTERNS_PROCESSED);
+            if (summary.failed === 0) {
+                yield* Display.showInfo("Next: ep-admin data ingest validate");
+            }
         })
     )
 );
@@ -142,6 +145,7 @@ export const ingestProcessOneCommand = Command.make("process-one", {
             yield* Display.showSuccess(
                 `Pattern ${positional.patternFile} processed! ID: ${result.id}`
             );
+            yield* Display.showInfo("Next: ep-admin data ingest validate");
         })
     )
 );
@@ -202,6 +206,9 @@ export const ingestValidateCommand = Command.make("validate", {
             }
 
             yield* Display.showSuccess(MESSAGES.SUCCESS.INGEST_VALIDATION_COMPLETE);
+            if (invalid === 0) {
+                yield* Display.showInfo("Next: ep-admin data ingest test");
+            }
         })
     )
 );
@@ -256,6 +263,7 @@ export const ingestTestCommand = Command.make("test", {
 
             if (failed === 0) {
                 yield* Display.showSuccess(MESSAGES.SUCCESS.INGEST_TESTS_PASSED);
+                yield* Display.showInfo("Next: ep-admin data ingest pipeline");
             } else {
                 for (const r of tested.filter((r) => r.valid && !r.testPassed)) {
                     yield* Display.showError(`  - ${r.pattern.id}: test failed`);
@@ -408,6 +416,9 @@ export const ingestPipelineCommand = Command.make("pipeline", {
             }
 
             yield* Display.showSuccess(MESSAGES.SUCCESS.INGEST_PIPELINE_COMPLETED);
+            if (report.failed === 0) {
+                yield* Display.showInfo("Next: ep-admin publish validate");
+            }
         })
     )
 );

packages/ep-admin/src/publish-commands.ts

@@ -131,6 +131,7 @@ export const publishValidateCommand = Command.make("validate", {
             }
 
             yield* Display.showSuccess(MESSAGES.SUCCESS.PATTERNS_VALIDATED);
+            yield* Display.showInfo("Next: ep-admin publish test");
         })
     )
 );
@@ -183,6 +184,7 @@ export const publishTestCommand = Command.make("test", {
             }
 
             yield* Display.showSuccess(MESSAGES.SUCCESS.ALL_EXAMPLES_PASSED);
+            yield* Display.showInfo("Next: ep-admin publish run");
         })
     )
 );
@@ -241,6 +243,7 @@ export const publishRunCommand = Command.make("run", {
             }
 
             yield* Display.showSuccess(MESSAGES.SUCCESS.PATTERNS_PUBLISHED);
+            yield* Display.showInfo("Next: ep-admin publish generate --readme");
         })
     )
 );
@@ -300,6 +303,7 @@ export const publishGenerateCommand = Command.make("generate", {
             }
 
             yield* Display.showSuccess(MESSAGES.SUCCESS.DOCUMENTATION_GENERATED);
+            yield* Display.showInfo("Next: ep-admin release preview");
         })
     )
 );
@@ -355,6 +359,7 @@ export const publishLintCommand = Command.make("lint", {
             }
 
             yield* Display.showSuccess(MESSAGES.SUCCESS.LINTING_COMPLETE);
+            yield* Display.showInfo("Next: ep-admin publish pipeline");
         })
     )
 );
@@ -418,6 +423,7 @@ export const publishPipelineCommand = Command.make("pipeline", {
             yield* Display.showInfo(`Duration: ${result.duration}ms`);
 
             yield* Display.showSuccess(MESSAGES.SUCCESS.PIPELINE_COMPLETED);
+            yield* Display.showInfo("Next: ep-admin release preview");
         })
     )
 );