@crafter/cli-tree 0.1.0

package/src/render.ts

@@ -0,0 +1,182 @@
+import { createGrid, writeText } from "./grid";
+import type { Grid } from "./grid";
+import type { CLINode, Flag, Arg, TreeOptions } from "./types";
+
+const BOX = {
+	pipe: "│",
+	tee: "├",
+	corner: "└",
+	dash: "──",
+	space: "  ",
+} as const;
+
+interface RenderState {
+	grid: Grid;
+	row: number;
+	opts: Required<TreeOptions>;
+}
+
+function defaults(opts?: TreeOptions): Required<TreeOptions> {
+	return {
+		color: opts?.color ?? true,
+		indent: opts?.indent ?? 3,
+		showFlags: opts?.showFlags ?? true,
+		showArgs: opts?.showArgs ?? true,
+		showDescriptions: opts?.showDescriptions ?? true,
+		showTypes: opts?.showTypes ?? true,
+		showDefaults: opts?.showDefaults ?? true,
+		maxDepth: opts?.maxDepth ?? Infinity,
+		compact: opts?.compact ?? false,
+	};
+}
+
+function formatFlag(flag: Flag, opts: Required<TreeOptions>): string {
+	let text = `--${flag.name}`;
+	if (flag.short) text = `-${flag.short}, ${text}`;
+
+	if (opts.showTypes && flag.type !== "boolean") {
+		if (flag.type === "enum" && flag.enum) {
+			text += ` <${flag.enum.join("|")}>`;
+		} else {
+			text += ` <${flag.type}>`;
+		}
+	}
+
+	if (flag.type === "boolean") {
+		text += " [boolean]";
+	}
+
+	if (opts.showDefaults && flag.default !== undefined) {
+		text += ` (default: ${JSON.stringify(flag.default)})`;
+	}
+
+	if (flag.required) {
+		text += " *";
+	}
+
+	return text;
+}
+
+function formatArg(arg: Arg): string {
+	const name = arg.variadic ? `${arg.name}...` : arg.name;
+	return arg.required ? `<${name}>` : `[${name}]`;
+}
+
+function drawPrefix(state: RenderState, col: number, pipes: boolean[], isLast: boolean) {
+	const indent = state.opts.indent;
+	for (let i = 0; i < pipes.length; i++) {
+		const x = i * indent;
+		if (pipes[i]) {
+			writeText(state.grid, x, state.row, BOX.pipe, state.opts.color ? "gray" : null);
+		}
+	}
+
+	const x = pipes.length * indent;
+	const connector = isLast ? BOX.corner : BOX.tee;
+	writeText(state.grid, x, state.row, connector + BOX.dash + " ", state.opts.color ? "gray" : null);
+}
+
+function renderNode(
+	state: RenderState,
+	node: CLINode,
+	depth: number,
+	pipes: boolean[],
+	isLast: boolean,
+	isRoot: boolean,
+) {
+	const indent = state.opts.indent;
+
+	if (isRoot) {
+		writeText(state.grid, 0, state.row, node.name, state.opts.color ? "cyan" : null);
+		if (node.description && state.opts.showDescriptions) {
+			const descCol = node.name.length + 1;
+			writeText(state.grid, descCol, state.row, `— ${node.description}`, state.opts.color ? "gray" : null);
+		}
+		state.row++;
+	} else {
+		drawPrefix(state, pipes.length * indent, pipes, isLast);
+		const textStart = pipes.length * indent + 4;
+		writeText(state.grid, textStart, state.row, node.name, state.opts.color ? "green" : null);
+
+		if (node.aliases && node.aliases.length > 0) {
+			const aliasStart = textStart + node.name.length;
+			const aliasText = ` (${node.aliases.join(", ")})`;
+			writeText(state.grid, aliasStart, state.row, aliasText, state.opts.color ? "gray" : null);
+		}
+
+		if (node.description && state.opts.showDescriptions && !state.opts.compact) {
+			const nameLen = node.name.length + (node.aliases ? ` (${node.aliases.join(", ")})`.length : 0);
+			const descCol = textStart + nameLen + 1;
+			writeText(state.grid, descCol, state.row, `— ${node.description}`, state.opts.color ? "gray" : null);
+		}
+		state.row++;
+	}
+
+	if (depth >= state.opts.maxDepth) return;
+
+	const children: { type: "flag" | "arg" | "cmd"; item: Flag | Arg | CLINode }[] = [];
+
+	if (state.opts.showArgs && node.args) {
+		for (const arg of node.args) {
+			children.push({ type: "arg", item: arg });
+		}
+	}
+
+	if (state.opts.showFlags && node.flags) {
+		for (const flag of node.flags) {
+			children.push({ type: "flag", item: flag });
+		}
+	}
+
+	if (node.subcommands) {
+		for (const cmd of node.subcommands) {
+			children.push({ type: "cmd", item: cmd });
+		}
+	}
+
+	for (let i = 0; i < children.length; i++) {
+		const child = children[i]!;
+		const childIsLast = i === children.length - 1;
+		const nextPipes = isRoot ? [] : [...pipes, !isLast];
+
+		if (child.type === "flag") {
+			const flag = child.item as Flag;
+			drawPrefix(state, (nextPipes.length) * indent, nextPipes, childIsLast);
+			const textStart = nextPipes.length * indent + 4;
+			const flagText = formatFlag(flag, state.opts);
+			writeText(state.grid, textStart, state.row, flagText, state.opts.color ? "yellow" : null);
+
+			if (flag.description && state.opts.showDescriptions && !state.opts.compact) {
+				const descCol = textStart + flagText.length + 1;
+				writeText(state.grid, descCol, state.row, `— ${flag.description}`, state.opts.color ? "gray" : null);
+			}
+			state.row++;
+		} else if (child.type === "arg") {
+			const arg = child.item as Arg;
+			drawPrefix(state, (nextPipes.length) * indent, nextPipes, childIsLast);
+			const textStart = nextPipes.length * indent + 4;
+			const argText = formatArg(arg);
+			writeText(state.grid, textStart, state.row, argText, state.opts.color ? "magenta" : null);
+
+			if (arg.description && state.opts.showDescriptions && !state.opts.compact) {
+				const descCol = textStart + argText.length + 1;
+				writeText(state.grid, descCol, state.row, `— ${arg.description}`, state.opts.color ? "gray" : null);
+			}
+			state.row++;
+		} else {
+			const cmd = child.item as CLINode;
+			renderNode(state, cmd, depth + 1, nextPipes, childIsLast, false);
+		}
+	}
+}
+
+export function renderTree(root: CLINode, opts?: TreeOptions): Grid {
+	const resolved = defaults(opts);
+	const width = 120;
+	const grid = createGrid(width);
+	const state: RenderState = { grid, row: 0, opts: resolved };
+
+	renderNode(state, root, 0, [], true, true);
+
+	return grid;
+}

package/src/types.ts

@@ -0,0 +1,62 @@
+export type AnsiColor =
+	| "red"
+	| "green"
+	| "yellow"
+	| "blue"
+	| "magenta"
+	| "cyan"
+	| "white"
+	| "gray";
+
+export const ANSI_COLORS: Record<AnsiColor, string> = {
+	red: "\x1b[31m",
+	green: "\x1b[32m",
+	yellow: "\x1b[33m",
+	blue: "\x1b[34m",
+	magenta: "\x1b[35m",
+	cyan: "\x1b[36m",
+	white: "\x1b[37m",
+	gray: "\x1b[90m",
+};
+
+export const ANSI_RESET = "\x1b[0m";
+export const ANSI_BOLD = "\x1b[1m";
+export const ANSI_DIM = "\x1b[2m";
+
+export interface CLINode {
+	name: string;
+	description?: string;
+	aliases?: string[];
+	subcommands?: CLINode[];
+	flags?: Flag[];
+	args?: Arg[];
+}
+
+export interface Flag {
+	name: string;
+	short?: string;
+	type: "boolean" | "string" | "number" | "enum";
+	enum?: string[];
+	required?: boolean;
+	default?: unknown;
+	description?: string;
+}
+
+export interface Arg {
+	name: string;
+	required?: boolean;
+	variadic?: boolean;
+	description?: string;
+}
+
+export interface TreeOptions {
+	color?: boolean;
+	indent?: number;
+	showFlags?: boolean;
+	showArgs?: boolean;
+	showDescriptions?: boolean;
+	showTypes?: boolean;
+	showDefaults?: boolean;
+	maxDepth?: number;
+	compact?: boolean;
+}

package/workflows/docker-deploy.yml

@@ -0,0 +1,42 @@
+name: deploy
+cli: docker
+description: Build, tag, push, and run a containerized app
+
+nodes:
+  - id: build
+    command: docker build -t myapp .
+    label: Build
+    description: Build the image from Dockerfile
+
+  - id: tag
+    command: docker tag myapp registry.example.com/myapp:latest
+    label: Tag
+    description: Tag the image for registry push
+
+  - id: push
+    command: docker push registry.example.com/myapp:latest
+    label: Push
+    description: Upload to registry
+
+  - id: pull
+    command: docker pull registry.example.com/myapp:latest
+    label: Pull (remote)
+    description: Pull from registry on target host
+
+  - id: run
+    command: docker run -d -p 80:3000 myapp
+    label: Run
+    description: Start the container
+
+  - id: logs
+    command: docker logs -f myapp
+    label: Logs
+    description: Follow container logs
+    optional: true
+
+edges:
+  - build -> tag
+  - tag -> push
+  - push -> pull
+  - pull -> run
+  - run -> logs

package/workflows/docker-parallel.yml

@@ -0,0 +1,36 @@
+name: parallel-deploy
+cli: docker
+description: Build once, push to multiple registries in parallel
+
+nodes:
+  - id: build
+    command: docker build -t app .
+    label: Build
+
+  - id: tag-prod
+    command: docker tag app prod.registry/app
+    label: Tag prod
+
+  - id: tag-staging
+    command: docker tag app staging.registry/app
+    label: Tag staging
+
+  - id: push-prod
+    command: docker push prod.registry/app
+    label: Push prod
+
+  - id: push-staging
+    command: docker push staging.registry/app
+    label: Push staging
+
+  - id: notify
+    command: docker system info
+    label: Notify
+
+edges:
+  - build -> tag-prod
+  - build -> tag-staging
+  - tag-prod -> push-prod
+  - tag-staging -> push-staging
+  - push-prod -> notify
+  - push-staging -> notify

package/workflows/gh-issue-to-pr.yml

@@ -0,0 +1,48 @@
+name: issue-to-pr
+cli: gh
+description: Full flow from issue triage to merged PR
+
+nodes:
+  - id: view-issue
+    command: gh issue view 123
+    label: View issue
+    description: Read the issue details
+
+  - id: assign
+    command: gh issue edit 123 --add-assignee @me
+    label: Assign
+    description: Assign the issue to yourself
+
+  - id: checkout
+    command: gh issue develop 123 --checkout
+    label: Branch
+    description: Create and checkout a development branch
+
+  - id: pr-create
+    command: gh pr create --fill
+    label: Open PR
+    description: Create a pull request
+
+  - id: review
+    command: gh pr review --approve
+    label: Review
+    description: Request review from teammates
+    optional: true
+
+  - id: pr-merge
+    command: gh pr merge --squash
+    label: Merge
+    description: Merge when approved
+
+  - id: close
+    command: gh issue close 123
+    label: Close issue
+    description: Close the linked issue
+
+edges:
+  - view-issue -> assign
+  - assign -> checkout
+  - checkout -> pr-create
+  - pr-create -> review
+  - review -> pr-merge
+  - pr-merge -> close

package/workflows/git-pr-flow.yml

@@ -0,0 +1,36 @@
+name: pr-flow
+cli: git
+description: Typical flow for creating a pull request from a feature branch
+
+nodes:
+  - id: checkout
+    command: git checkout -b feature/my-feature
+    label: Create branch
+    description: Create and switch to a new feature branch
+
+  - id: add
+    command: git add .
+    label: Stage changes
+    description: Stage all modified files
+
+  - id: commit
+    command: git commit -m "message"
+    label: Commit
+    description: Record changes with a meaningful message
+
+  - id: push
+    command: git push -u origin feature/my-feature
+    label: Push
+    description: Push branch to remote and set upstream
+
+  - id: pr
+    command: gh pr create
+    label: Open PR
+    description: Open a pull request via gh CLI
+    optional: true
+
+edges:
+  - checkout -> add
+  - add -> commit
+  - commit -> push
+  - push -> pr

package/workflows/kubectl-rollout.yml

@@ -0,0 +1,37 @@
+name: rollout
+cli: kubectl
+description: Apply a new deployment and monitor the rollout
+
+nodes:
+  - id: apply
+    command: kubectl apply -f deployment.yaml
+    label: Apply
+    description: Apply the new deployment manifest
+
+  - id: status
+    command: kubectl rollout status deployment/myapp
+    label: Status
+    description: Watch the rollout until complete
+
+  - id: logs
+    command: kubectl logs -l app=myapp --tail=100
+    label: Logs
+    description: Check recent logs from the new pods
+
+  - id: verify
+    command: kubectl get pods -l app=myapp
+    label: Verify
+    description: Confirm pods are running
+
+  - id: undo
+    command: kubectl rollout undo deployment/myapp
+    label: Undo
+    description: Roll back if something went wrong
+    optional: true
+
+edges:
+  - apply -> status
+  - status -> logs
+  - status -> verify
+  - logs -> undo
+  - verify -> undo

package/workflows/npm-publish.yml

@@ -0,0 +1,42 @@
+name: publish
+cli: npm
+description: Test, build, version, and publish a package
+
+nodes:
+  - id: install
+    command: npm install
+    label: Install
+    description: Install dependencies
+
+  - id: test
+    command: npm test
+    label: Test
+    description: Run the test suite
+
+  - id: build
+    command: npm run build
+    label: Build
+    description: Build for distribution
+
+  - id: version
+    command: npm version patch
+    label: Version bump
+    description: Increment version
+
+  - id: publish
+    command: npm publish
+    label: Publish
+    description: Publish to the npm registry
+
+  - id: tag
+    command: npm dist-tag add mypkg@1.0.0 latest
+    label: Dist-tag
+    description: Update dist-tag
+    optional: true
+
+edges:
+  - install -> test
+  - test -> build
+  - build -> version
+  - version -> publish
+  - publish -> tag