@thinkingsage/kanon 0.8.0

package/src/help/metadata.ts

@@ -0,0 +1,445 @@
+export interface UsageExample {
+	comment: string;
+	invocation: string;
+}
+
+export interface OptionGroup {
+	label: string;
+	options: string[];
+}
+
+export interface CommandHelpMeta {
+	examples: UsageExample[];
+	optionGroups?: OptionGroup[];
+	showHarnessList?: boolean;
+}
+
+export const commandMetaRegistry: Record<string, CommandHelpMeta> = {
+	build: {
+		examples: [
+			{ comment: "Build for all harnesses", invocation: "kanon build" },
+			{
+				comment: "Build for Kiro only",
+				invocation: "kanon build --harness kiro",
+			},
+			{
+				comment: "Strict mode — fail on unsupported capabilities",
+				invocation: "kanon build --strict",
+			},
+		],
+		optionGroups: [
+			{
+				label: "Build Options",
+				options: ["--harness", "--strict"],
+			},
+		],
+		showHarnessList: true,
+	},
+	install: {
+		examples: [
+			{
+				comment: "Install a single artifact for Kiro from local dist",
+				invocation: "kanon install my-artifact --harness kiro --source .",
+			},
+			{
+				comment: "Install for all harnesses",
+				invocation: "kanon install my-artifact --all --source .",
+			},
+			{
+				comment: "Install into the global cache (for guild sync)",
+				invocation: "kanon install --global my-artifact --backend github",
+			},
+			{
+				comment: "Install from a GitHub release",
+				invocation: "kanon install my-artifact --from-release v1.0.0",
+			},
+			{
+				comment: "Install from a named backend in kanon.config.yaml",
+				invocation: "kanon install my-artifact --backend internal",
+			},
+			{
+				comment: "Install into a specific workspace project",
+				invocation: "kanon install my-artifact --project frontend",
+			},
+			{
+				comment: "Preview what would be installed",
+				invocation: "kanon install my-artifact --dry-run --source .",
+			},
+		],
+		optionGroups: [
+			{
+				label: "Source Options",
+				options: ["--source", "--from-release", "--backend"],
+			},
+			{
+				label: "Target Options",
+				options: ["--harness", "--all", "--global", "--project"],
+			},
+			{
+				label: "Behavior Options",
+				options: ["--force", "--dry-run"],
+			},
+		],
+		showHarnessList: true,
+	},
+	new: {
+		examples: [
+			{
+				comment: "Scaffold interactively (opens wizard)",
+				invocation: "kanon new my-artifact",
+			},
+			{
+				comment: "Scaffold a power with defaults (skip wizard)",
+				invocation: "kanon new my-power --type power --yes",
+			},
+			{
+				comment: "Scaffold a workflow artifact",
+				invocation: "kanon new deploy-checklist --type workflow",
+			},
+		],
+	},
+	tutorial: {
+		examples: [
+			{
+				comment: "Start the guided walkthrough for first-time authors",
+				invocation: "kanon tutorial",
+			},
+		],
+	},
+	validate: {
+		examples: [
+			{
+				comment: "Validate all artifacts",
+				invocation: "kanon validate",
+			},
+			{
+				comment: "Validate a specific artifact",
+				invocation: "kanon validate knowledge/my-artifact",
+			},
+			{
+				comment:
+					"Run security checks (prompt injection, dangerous hooks, obfuscation)",
+				invocation: "kanon validate --security",
+			},
+		],
+	},
+	catalog: {
+		examples: [
+			{
+				comment: "Show catalog subcommands",
+				invocation: "kanon catalog --help",
+			},
+		],
+	},
+	"catalog generate": {
+		examples: [
+			{
+				comment: "Generate catalog.json from all knowledge sources",
+				invocation: "kanon catalog generate",
+			},
+			{
+				comment: "Regenerate after adding or removing artifacts",
+				invocation: "kanon catalog generate",
+			},
+		],
+	},
+	"catalog browse": {
+		examples: [
+			{
+				comment: "Open the catalog browser in your default browser",
+				invocation: "kanon catalog browse",
+			},
+			{
+				comment: "Browse on a custom port",
+				invocation: "kanon catalog browse --port 8080",
+			},
+		],
+	},
+	"catalog export": {
+		examples: [
+			{
+				comment: "Export a self-contained static site for GitHub Pages",
+				invocation: "kanon catalog export --output dist/web",
+			},
+			{
+				comment: "Export to a custom directory",
+				invocation: "kanon catalog export --output ../site",
+			},
+		],
+	},
+	collection: {
+		examples: [
+			{
+				comment: "Show collection status for all collections",
+				invocation: "kanon collection",
+			},
+		],
+	},
+	"collection new": {
+		examples: [
+			{
+				comment: "Scaffold a new collection interactively",
+				invocation: "kanon collection new",
+			},
+			{
+				comment: "Scaffold with a name pre-filled",
+				invocation: "kanon collection new aws-tools",
+			},
+		],
+	},
+	"collection build": {
+		examples: [
+			{
+				comment: "Build all collection bundles for all harnesses",
+				invocation: "kanon collection build",
+			},
+			{
+				comment: "Build collections for Kiro only",
+				invocation: "kanon collection build --harness kiro",
+			},
+		],
+		showHarnessList: true,
+	},
+	import: {
+		examples: [
+			{
+				comment: "Import a Kiro power into canonical format",
+				invocation: "kanon import path/to/power",
+			},
+			{
+				comment: "Import all artifacts from a directory",
+				invocation: "kanon import path/to/artifacts --all",
+			},
+			{
+				comment: "Import and assign to a collection",
+				invocation: "kanon import path/to/power --collections my-collection",
+			},
+			{
+				comment: "Import accepting derived upstream attribution (no prompt)",
+				invocation: "kanon import path/to/power --attribution-defaults",
+			},
+			{
+				comment: "Import without capturing attribution",
+				invocation: "kanon import path/to/power --no-attribution",
+			},
+			{
+				comment: "Preview what would be imported",
+				invocation: "kanon import path/to/power --dry-run",
+			},
+		],
+		optionGroups: [
+			{
+				label: "Source Options",
+				options: ["--format", "--all"],
+			},
+			{
+				label: "Attribution Options",
+				options: ["--attribution-defaults", "--no-attribution"],
+			},
+			{
+				label: "Behavior Options",
+				options: ["--dry-run", "--collections", "--knowledge-dir"],
+			},
+		],
+	},
+	attribute: {
+		examples: [
+			{
+				comment: "Print a NOTICES report of upstream attribution by license",
+				invocation: "kanon attribute",
+			},
+			{
+				comment: "Write the NOTICES report to a file",
+				invocation: "kanon attribute --output NOTICES",
+			},
+		],
+		optionGroups: [
+			{
+				label: "Output Options",
+				options: ["--output"],
+			},
+		],
+	},
+	"attribute backfill": {
+		examples: [
+			{
+				comment:
+					"Preview the attribution backfill (clean vs manual-review split)",
+				invocation: "kanon attribute backfill --dry-run",
+			},
+			{
+				comment: "Backfill attribution blocks for imported artifacts",
+				invocation: "kanon attribute backfill",
+			},
+		],
+		optionGroups: [
+			{
+				label: "Behavior Options",
+				options: ["--dry-run"],
+			},
+		],
+	},
+	publish: {
+		examples: [
+			{
+				comment: "Publish to the default GitHub backend",
+				invocation: "kanon publish",
+			},
+			{
+				comment: "Publish with an explicit version tag",
+				invocation: "kanon publish --tag v1.2.0",
+			},
+			{
+				comment: "Publish to a named backend from kanon.config.yaml",
+				invocation: "kanon publish --backend internal",
+			},
+			{
+				comment: "Dry run — validate and package without uploading",
+				invocation: "kanon publish --dry-run",
+			},
+			{
+				comment: "Include release notes",
+				invocation: "kanon publish --notes CHANGELOG.md",
+			},
+		],
+		optionGroups: [
+			{ label: "Target Options", options: ["--backend", "--tag"] },
+			{ label: "Behavior Options", options: ["--dry-run", "--notes"] },
+		],
+	},
+	eval: {
+		examples: [
+			{
+				comment: "Run evals for all artifacts and harnesses",
+				invocation: "kanon eval",
+			},
+			{
+				comment: "Run evals for a specific artifact",
+				invocation: "kanon eval my-artifact",
+			},
+			{
+				comment: "Run evals for Cursor with a custom threshold",
+				invocation: "kanon eval --harness cursor --threshold 0.8",
+			},
+			{
+				comment: "Scaffold an eval suite for an artifact",
+				invocation: "kanon eval --init my-artifact",
+			},
+			{
+				comment: "Machine-readable output for CI",
+				invocation: "kanon eval --ci --output results.json",
+			},
+		],
+		optionGroups: [
+			{
+				label: "Execution Options",
+				options: ["--harness", "--provider", "--threshold", "--init"],
+			},
+			{
+				label: "Output Options",
+				options: ["--output", "--ci", "--no-context"],
+			},
+		],
+		showHarnessList: true,
+	},
+	guild: {
+		examples: [
+			{
+				comment: "Typical workflow: add artifact, sync, check status",
+				invocation:
+					"kanon guild init adr && kanon guild sync && kanon guild status",
+			},
+		],
+	},
+	"guild init": {
+		examples: [
+			{
+				comment: "Add an artifact to the manifest",
+				invocation: "kanon guild init my-artifact",
+			},
+			{
+				comment: "Add a collection from a named backend",
+				invocation:
+					"kanon guild init neon-caravan --collection --backend github",
+			},
+			{
+				comment: "Pin a specific version as optional",
+				invocation:
+					"kanon guild init my-artifact --version 0.1.0 --mode optional",
+			},
+		],
+		optionGroups: [
+			{
+				label: "Entry Options",
+				options: ["--collection", "--mode", "--version"],
+			},
+			{
+				label: "Source Options",
+				options: ["--backend"],
+			},
+		],
+	},
+	"guild sync": {
+		examples: [
+			{
+				comment: "Sync manifest artifacts into harness targets",
+				invocation: "kanon guild sync",
+			},
+			{
+				comment: "Check for remote updates before syncing",
+				invocation: "kanon guild sync --auto-update",
+			},
+			{
+				comment: "Sync only Kiro harness files",
+				invocation: "kanon guild sync --harness kiro",
+			},
+			{
+				comment: "Preview what would be synced",
+				invocation: "kanon guild sync --dry-run",
+			},
+		],
+		optionGroups: [
+			{
+				label: "Update Options",
+				options: ["--auto-update", "--throttle"],
+			},
+			{
+				label: "Behavior Options",
+				options: ["--dry-run", "--harness"],
+			},
+		],
+		showHarnessList: true,
+	},
+	"guild status": {
+		examples: [
+			{
+				comment: "Show manifest entries, resolved versions, and sync state",
+				invocation: "kanon guild status",
+			},
+		],
+	},
+	"guild hook install": {
+		examples: [
+			{
+				comment: "Print shell hook snippet for auto-sync on cd",
+				invocation: "kanon guild hook install",
+			},
+			{
+				comment: "Install hook for a specific shell",
+				invocation: "kanon guild hook install --shell zsh",
+			},
+		],
+	},
+	help: {
+		examples: [
+			{
+				comment: "Show help for the build command",
+				invocation: "kanon help build",
+			},
+			{
+				comment: "Show help for a subcommand",
+				invocation: "kanon help guild init",
+			},
+		],
+	},
+};

package/src/help/renderer.ts

@@ -0,0 +1,265 @@
+import { Chalk } from "chalk";
+import type { CommandHelpMeta } from "./metadata";
+
+/** Chalk instance that always emits ANSI codes regardless of terminal detection. */
+const colorChalk = new Chalk({ level: 3 });
+/** Chalk instance that never emits ANSI codes. */
+const plainChalk = new Chalk({ level: 0 });
+
+export interface RenderOptions {
+	useColor: boolean;
+}
+
+export const SUPPORTED_HARNESSES = [
+	"kiro",
+	"claude-code",
+	"codex",
+	"copilot",
+	"cursor",
+	"windsurf",
+	"cline",
+	"qdeveloper",
+] as const;
+
+/**
+ * Render the root help screen.
+ *
+ * Sections (in order):
+ *   1. Description
+ *   2. Usage line
+ *   3. Commands table (aligned columns)
+ *   4. Global Options
+ *   5. Getting Started tip
+ */
+export interface RootCommand {
+	name: string;
+	description: string;
+	subcommands?: { name: string; description: string }[];
+}
+
+export function renderRootHelp(
+	commands: RootCommand[],
+	opts: RenderOptions,
+): string {
+	const pad = "  ";
+	const lines: string[] = [];
+
+	// --- helpers for optional chalk styling ---
+	const c = opts.useColor ? colorChalk : plainChalk;
+	const bold = (s: string) => c.bold(s);
+	const cyan = (s: string) => c.cyan(s);
+	const yellow = (s: string) => c.yellow(s);
+	const dim = (s: string) => c.dim(s);
+
+	// 1. Description
+	lines.push(
+		`${pad}${bold("Kanon")} ${dim("—")} write knowledge once, compile to every harness`,
+	);
+	lines.push("");
+
+	// 2. Usage
+	lines.push(`${pad}${yellow("Usage:")} kanon <command> [options]`);
+	lines.push("");
+
+	// 3. Commands table — structured with optional subcommand groups
+	// Column width accounts for top-level names and indented subcommand names
+	const allNames = [
+		...commands.map((cmd) => cmd.name),
+		...commands.flatMap(
+			(cmd) => cmd.subcommands?.map((s) => `  ${s.name}`) ?? [],
+		),
+	];
+	const nameColWidth = Math.max(...allNames.map((n) => n.length)) + 2;
+
+	lines.push(`${pad}${yellow("Commands:")}`);
+	for (const cmd of commands) {
+		const paddedName = cmd.name.padEnd(nameColWidth);
+		if (cmd.subcommands && cmd.subcommands.length > 0) {
+			// Parent command: show name + description, then indented subcommands
+			lines.push(`${pad}${pad}${cyan(paddedName)}${cmd.description}`);
+			for (const sub of cmd.subcommands) {
+				const paddedSub = `  ${sub.name}`.padEnd(nameColWidth);
+				lines.push(`${pad}${pad}${dim(paddedSub)}${sub.description}`);
+			}
+		} else {
+			lines.push(`${pad}${pad}${cyan(paddedName)}${cmd.description}`);
+		}
+	}
+	lines.push("");
+
+	// 4. Global Options
+	const globalOptions = [
+		{ flags: "-V, --version", description: "Output version information" },
+		{ flags: "-h, --help", description: "Show help" },
+		{ flags: "--no-color", description: "Disable color output" },
+	];
+
+	const flagColWidth =
+		Math.max(...globalOptions.map((o) => o.flags.length)) + 2;
+
+	lines.push(`${pad}${yellow("Global Options:")}`);
+	for (const opt of globalOptions) {
+		const paddedFlags = opt.flags.padEnd(flagColWidth);
+		lines.push(`${pad}${pad}${cyan(paddedFlags)}${opt.description}`);
+	}
+	lines.push("");
+
+	// 5. Getting Started tip
+	lines.push(`${pad}${yellow("Getting Started:")}`);
+	lines.push(
+		`${pad}${pad}Run ${cyan("kanon new <name>")} to create your first knowledge artifact.`,
+	);
+	lines.push("");
+
+	return lines.join("\n");
+}
+
+/**
+ * Render help for a single command.
+ *
+ * Sections (in order):
+ *   1. Description
+ *   2. Usage line
+ *   3. Options (grouped or flat)
+ *   4. Examples (if metadata provides them)
+ */
+export function renderCommandHelp(
+	_commandName: string,
+	description: string,
+	usage: string,
+	options: { flags: string; description: string }[],
+	meta: CommandHelpMeta | undefined,
+	opts: RenderOptions,
+	subcommands?: { name: string; description: string }[],
+): string {
+	const pad = "  ";
+	const lines: string[] = [];
+
+	// --- helpers for optional chalk styling ---
+	const c = opts.useColor ? colorChalk : plainChalk;
+	const cyan = (s: string) => c.cyan(s);
+	const yellow = (s: string) => c.yellow(s);
+	const dim = (s: string) => c.dim(s);
+
+	// Possibly augment --harness option description with harness names
+	const augmentedOptions = options.map((opt) => {
+		if (meta?.showHarnessList && opt.flags.includes("--harness")) {
+			const harnessList = SUPPORTED_HARNESSES.join(", ");
+			return {
+				flags: opt.flags,
+				description: `${opt.description} (${harnessList})`,
+			};
+		}
+		return opt;
+	});
+
+	// 1. Description
+	lines.push(`${pad}${description}`);
+	lines.push("");
+
+	// 2. Usage
+	lines.push(`${pad}${yellow("Usage:")} ${usage}`);
+	lines.push("");
+
+	// 2b. Subcommands (for parent commands like catalog, collection)
+	if (subcommands && subcommands.length > 0) {
+		const nameColWidth = Math.max(...subcommands.map((s) => s.name.length)) + 2;
+		lines.push(`${pad}${yellow("Commands:")}`);
+		for (const sub of subcommands) {
+			lines.push(
+				`${pad}${pad}${cyan(sub.name.padEnd(nameColWidth))}${sub.description}`,
+			);
+		}
+		lines.push("");
+	}
+
+	// 3. Options — grouped or flat
+	const flagColWidth =
+		Math.max(...augmentedOptions.map((o) => o.flags.length), 0) + 2;
+
+	if (meta?.optionGroups && meta.optionGroups.length > 0) {
+		// Build a set of flags that belong to a group
+		const groupedFlags = new Set<string>();
+		for (const group of meta.optionGroups) {
+			for (const flag of group.options) {
+				groupedFlags.add(flag);
+			}
+		}
+
+		// Render each group
+		for (const group of meta.optionGroups) {
+			lines.push(`${pad}${yellow(`${group.label}:`)}`);
+			for (const flag of group.options) {
+				const opt = augmentedOptions.find((o) => o.flags.includes(flag));
+				if (opt) {
+					const paddedFlags = opt.flags.padEnd(flagColWidth);
+					lines.push(`${pad}${pad}${cyan(paddedFlags)}${opt.description}`);
+				}
+			}
+			lines.push("");
+		}
+
+		// Render ungrouped options (if any)
+		const ungrouped = augmentedOptions.filter(
+			(o) => !Array.from(groupedFlags).some((f) => o.flags.includes(f)),
+		);
+		if (ungrouped.length > 0) {
+			lines.push(`${pad}${yellow("Options:")}`);
+			for (const opt of ungrouped) {
+				const paddedFlags = opt.flags.padEnd(flagColWidth);
+				lines.push(`${pad}${pad}${cyan(paddedFlags)}${opt.description}`);
+			}
+			lines.push("");
+		}
+	} else {
+		// Flat list
+		lines.push(`${pad}${yellow("Options:")}`);
+		for (const opt of augmentedOptions) {
+			const paddedFlags = opt.flags.padEnd(flagColWidth);
+			lines.push(`${pad}${pad}${cyan(paddedFlags)}${opt.description}`);
+		}
+		lines.push("");
+	}
+
+	// 4. Examples
+	if (meta?.examples && meta.examples.length > 0) {
+		lines.push(`${pad}${yellow("Examples:")}`);
+		for (const example of meta.examples) {
+			lines.push(`${pad}${pad}${dim(`# ${example.comment}`)}`);
+			lines.push(`${pad}${pad}${cyan(`$ ${example.invocation}`)}`);
+			lines.push("");
+		}
+	}
+
+	return lines.join("\n");
+}
+
+/**
+ * Render version information block.
+ *
+ * Output:
+ *   kanon v<version>
+ *   bun v<bunVersion>
+ *   platform <os>-<arch>
+ */
+export function renderVersion(version: string, opts: RenderOptions): string {
+	const pad = "  ";
+	const lines: string[] = [];
+
+	// --- helpers for optional chalk styling ---
+	const c = opts.useColor ? colorChalk : plainChalk;
+	const cyan = (s: string) => c.cyan(s);
+	const dim = (s: string) => c.dim(s);
+
+	// Bun version — gracefully degrade if not running in Bun
+	const bunVersion = typeof Bun !== "undefined" ? Bun.version : "unknown";
+
+	const platform = `${process.platform}-${process.arch}`;
+
+	lines.push(`${pad}${cyan("kanon")} ${dim(`v${version}`)}`);
+	lines.push(`${pad}${cyan("bun")} ${dim(`v${bunVersion}`)}`);
+	lines.push(`${pad}${cyan("platform")} ${dim(platform)}`);
+	lines.push("");
+
+	return lines.join("\n");
+}