ReviewOS

also looking at this

loghqorg/loghq

Deploy: uniform auth session model (main → production)

#7
Merged glennmichael123 wants to merge main into production
282 files +3028 -64856
docs/bootcamp/cli.mddeleted+0-743
Changes to docs/bootcamp/cli.md
@@ -1,743 +0,0 @@
1# Build a CLI
2
3This tutorial will guide you through building command-line interfaces (CLIs) with Stacks. You will learn how to create commands, handle options and arguments, display prompts, and format output.
4
5## Overview
6
7Stacks makes it easy to create powerful CLIs:
8
9- **Automatic Registration** - Commands are auto-discovered
10- **Type-Safe** - Full TypeScript support with excellent IDE integration
11- **Rich Output** - Colorful output, tables, progress bars, and more
12- **Interactive Prompts** - Confirmations, selections, and text input
13- **Distributable** - Ship as a binary or npm package
14
15## Configuration
16
17Configure your CLI in `config/cli.ts`:
18
19```typescript
20// config/cli.ts
21import type { BinaryConfig } from '@stacksjs/types'
22
23export default {
24 name: 'My Custom CLI',
25 command: 'my-cli', // enables `my-cli <command> <options>`
26 description: 'A powerful CLI tool for my project',
27 deploy: true, // deploys CLI setup endpoint
28} satisfies BinaryConfig
29```
30
31## Creating Commands
32
33Commands live in the `app/Commands/` directory and are automatically registered.
34
35### Generate a Command
36
37```bash
38buddy make:command SendEmails
39```
40
41### Basic Command Structure
42
43```typescript
44// app/Commands/SendEmails.ts
45import type { CLI } from '@stacksjs/types'
46import process from 'node:process'
47import { log } from '@stacksjs/cli'
48import { ExitCode } from '@stacksjs/types'
49
50export default function (cli: CLI) {
51 cli
52 .command('send-emails', 'Send pending emails to users')
53 .action(() => {
54 log.info('Sending emails...')
55
56 // Your logic here
57
58 log.success('Emails sent successfully!')
59 process.exit(ExitCode.Success)
60 })
61
62 return cli
63}
64```
65
66### Using the Command
67
68```bash
69# Using Buddy
70buddy send-emails
71
72# Using your custom CLI (after deployment)
73my-cli send-emails
74```
75
76## Options and Arguments
77
78### Adding Options
79
80Options are flags that modify command behavior:
81
82```typescript
83// app/Commands/Greet.ts
84import type { CLI } from '@stacksjs/types'
85import process from 'node:process'
86import { log } from '@stacksjs/cli'
87import { ExitCode } from '@stacksjs/types'
88
89interface GreetOptions {
90 name: string
91 uppercase: boolean
92 times: number
93}
94
95export default function (cli: CLI) {
96 cli
97 .command('greet', 'Greet someone')
98 .option('--name, -n <name>', 'Name to greet', { default: 'World' })
99 .option('--uppercase, -u', 'Output in uppercase', { default: false })
100 .option('--times, -t <count>', 'Number of times to greet', { default: 1 })
101 .action((options: GreetOptions) => {
102 let message = `Hello, ${options.name}!`
103
104 if (options.uppercase) {
105 message = message.toUpperCase()
106 }
107
108 for (let i = 0; i < options.times; i++) {
109 log.info(message)
110 }
111
112 process.exit(ExitCode.Success)
113 })
114
115 return cli
116}
117```
118
119Usage:
120
121```bash
122buddy greet # Hello, World!
123buddy greet --name Alice # Hello, Alice!
124buddy greet -n Alice -u # HELLO, ALICE!
125buddy greet --name Bob --times 3 # Prints 3 times
126```
127
128### Adding Arguments
129
130Arguments are positional values:
131
132```typescript
133// app/Commands/Copy.ts
134import type { CLI } from '@stacksjs/types'
135import process from 'node:process'
136import { log } from '@stacksjs/cli'
137import { ExitCode } from '@stacksjs/types'
138
139export default function (cli: CLI) {
140 cli
141 .command('copy <source> <destination>', 'Copy files from source to destination')
142 .option('--recursive, -r', 'Copy recursively', { default: false })
143 .option('--force, -f', 'Overwrite existing files', { default: false })
144 .action((source: string, destination: string, options) => {
145 log.info(`Copying from ${source} to ${destination}`)
146
147 if (options.recursive) {
148 log.info('Copying recursively...')
149 }
150
151 if (options.force) {
152 log.info('Overwriting existing files...')
153 }
154
155 // Perform copy operation
156
157 log.success('Copy completed!')
158 process.exit(ExitCode.Success)
159 })
160
161 return cli
162}
163```
164
165Usage:
166
167```bash
168buddy copy ./src ./dist
169buddy copy ./src ./dist --recursive --force
170buddy copy ./src ./dist -rf
171```
172
173### Optional Arguments
174
175Use square brackets for optional arguments:
176
177```typescript
178cli
179 .command('deploy [environment]', 'Deploy to an environment')
180 .action((environment: string = 'production') => {
181 log.info(`Deploying to ${environment}...`)
182 })
183```
184
185### Variadic Arguments
186
187Accept multiple values:
188
189```typescript
190cli
191 .command('install <packages...>', 'Install packages')
192 .action((packages: string[]) => {
193 packages.forEach(pkg => {
194 log.info(`Installing ${pkg}...`)
195 })
196 })
197```
198
199Usage:
200
201```bash
202buddy install lodash axios vue
203```
204
205## Interactive Prompts
206
207Stacks provides interactive prompts for user input.
208
209### Confirmation Prompt
210
211```typescript
212import { confirm } from '@stacksjs/cli'
213
214const shouldContinue = await confirm('Are you sure you want to continue?')
215
216if (shouldContinue) {
217 log.info('Continuing...')
218} else {
219 log.info('Cancelled.')
220 process.exit(ExitCode.Success)
221}
222```
223
224### Text Input
225
226```typescript
227import { prompt } from '@stacksjs/cli'
228
229const name = await prompt('What is your name?')
230const email = await prompt('What is your email?', {
231 default: 'user@example.com',
232})
233
234log.info(`Hello, ${name} (${email})!`)
235```
236
237### Password Input
238
239```typescript
240import { password } from '@stacksjs/cli'
241
242const secret = await password('Enter your password:')
243```
244
245### Selection List
246
247```typescript
248import { select } from '@stacksjs/cli'
249
250const choice = await select('Choose an environment:', [
251 'development',
252 'staging',
253 'production',
254])
255
256log.info(`Selected: ${choice}`)
257```
258
259### Multi-Select
260
261```typescript
262import { multiselect } from '@stacksjs/cli'
263
264const features = await multiselect('Select features to enable:', [
265 { name: 'TypeScript', value: 'typescript', checked: true },
266 { name: 'ESLint', value: 'eslint', checked: true },
267 { name: 'Testing', value: 'testing' },
268 { name: 'Docker', value: 'docker' },
269])
270
271log.info(`Selected features: ${features.join(', ')}`)
272```
273
274### Complete Interactive Example
275
276```typescript
277// app/Commands/Init.ts
278import type { CLI } from '@stacksjs/types'
279import process from 'node:process'
280import { confirm, log, multiselect, prompt, select } from '@stacksjs/cli'
281import { ExitCode } from '@stacksjs/types'
282
283export default function (cli: CLI) {
284 cli
285 .command('init', 'Initialize a new project')
286 .action(async () => {
287 log.info('Welcome to the project initializer!')
288 console.log('')
289
290 // Get project name
291 const projectName = await prompt('Project name:', {
292 default: 'my-project',
293 })
294
295 // Choose template
296 const template = await select('Choose a template:', [
297 'minimal',
298 'with-auth',
299 'full-stack',
300 'api-only',
301 ])
302
303 // Select features
304 const features = await multiselect('Select additional features:', [
305 { name: 'Database (SQLite)', value: 'database', checked: true },
306 { name: 'Authentication', value: 'auth' },
307 { name: 'Testing', value: 'testing', checked: true },
308 { name: 'Docker', value: 'docker' },
309 { name: 'CI/CD', value: 'cicd' },
310 ])
311
312 // Confirm
313 console.log('')
314 log.info('Configuration:')
315 log.info(` Project: ${projectName}`)
316 log.info(` Template: ${template}`)
317 log.info(` Features: ${features.join(', ') || 'none'}`)
318 console.log('')
319
320 const confirmed = await confirm('Create project with these settings?')
321
322 if (!confirmed) {
323 log.warning('Project creation cancelled.')
324 process.exit(ExitCode.Success)
325 }
326
327 // Create project
328 log.info('Creating project...')
329 // ... project creation logic
330
331 log.success(`Project "${projectName}" created successfully!`)
332 console.log('')
333 log.info('Next steps:')
334 log.info(` cd ${projectName}`)
335 log.info(' bun install')
336 log.info(' buddy dev')
337
338 process.exit(ExitCode.Success)
339 })
340
341 return cli
342}
343```
344
345## Output Formatting
346
347### Log Levels
348
349```typescript
350import { log } from '@stacksjs/cli'
351
352log.info('Information message') // Blue text
353log.success('Success message') // Green text
354log.warning('Warning message') // Yellow text
355log.error('Error message') // Red text
356log.debug('Debug message') // Gray text (only in verbose mode)
357```
358
359### Tables
360
361```typescript
362import { table } from '@stacksjs/cli'
363
364const users = [
365 { id: 1, name: 'Alice', email: 'alice@example.com', role: 'Admin' },
366 { id: 2, name: 'Bob', email: 'bob@example.com', role: 'User' },
367 { id: 3, name: 'Charlie', email: 'charlie@example.com', role: 'User' },
368]
369
370table(users, {
371 columns: ['id', 'name', 'email', 'role'],
372 headers: ['ID', 'Name', 'Email', 'Role'],
373})
374```
375
376Output:
377
378```
379┌────┬─────────┬─────────────────────────┬───────┐
380│ ID │ Name │ Email │ Role │
381├────┼─────────┼─────────────────────────┼───────┤
382│ 1 │ Alice │ alice@example.com │ Admin │
383│ 2 │ Bob │ bob@example.com │ User │
384│ 3 │ Charlie │ charlie@example.com │ User │
385└────┴─────────┴─────────────────────────┴───────┘
386```
387
388### Progress Bars
389
390```typescript
391import { progress } from '@stacksjs/cli'
392
393const bar = progress('Processing files', { total: 100 })
394
395for (let i = 0; i <= 100; i++) {
396 await sleep(50) // Simulate work
397 bar.update(i)
398}
399
400bar.stop('Processing complete!')
401```
402
403### Spinners
404
405```typescript
406import { spinner } from '@stacksjs/cli'
407
408const spin = spinner('Loading data...')
409spin.start()
410
411// Simulate async work
412await fetchData()
413
414spin.stop('Data loaded!')
415// Or on error:
416// spin.fail('Failed to load data')
417```
418
419### Colored Output
420
421```typescript
422import { colors } from '@stacksjs/cli'
423
424console.log(colors.blue('Blue text'))
425console.log(colors.red('Red text'))
426console.log(colors.green('Green text'))
427console.log(colors.yellow('Yellow text'))
428console.log(colors.bold('Bold text'))
429console.log(colors.dim('Dimmed text'))
430console.log(colors.underline('Underlined text'))
431
432// Combine styles
433console.log(colors.bold(colors.red('Bold red text')))
434```
435
436### Boxes
437
438```typescript
439import { box } from '@stacksjs/cli'
440
441box('Important Message', {
442 title: 'Notice',
443 padding: 1,
444 borderStyle: 'round',
445 borderColor: 'yellow',
446})
447```
448
449Output:
450
451```
452╭──────────────────────────────╮
453│ │
454│ Notice │
455│ │
456│ Important Message │
457│ │
458╰──────────────────────────────╯
459```
460
461## Command Aliases
462
463Create shorthand aliases for commands:
464
465```typescript
466cli
467 .command('database:migrate', 'Run database migrations')
468 .alias('migrate')
469 .alias('db:m')
470 .action(() => {
471 // Migration logic
472 })
473```
474
475Usage:
476
477```bash
478buddy database:migrate
479buddy migrate
480buddy db:m
481```
482
483## Sub-Commands
484
485Organize related commands with namespaces:
486
487```typescript
488// app/Commands/Database.ts
489export default function (cli: CLI) {
490 // Main namespace command
491 cli
492 .command('database', 'Database management commands')
493 .action(() => {
494 log.info('Available commands:')
495 log.info(' database:migrate - Run migrations')
496 log.info(' database:seed - Seed database')
497 log.info(' database:reset - Reset database')
498 })
499
500 // Sub-commands
501 cli
502 .command('database:migrate', 'Run database migrations')
503 .option('--fresh', 'Drop all tables first')
504 .action((options) => {
505 if (options.fresh) {
506 log.warning('Dropping all tables...')
507 }
508 log.info('Running migrations...')
509 })
510
511 cli
512 .command('database:seed', 'Seed the database')
513 .option('--class <name>', 'Specific seeder to run')
514 .action((options) => {
515 log.info('Seeding database...')
516 })
517
518 cli
519 .command('database:reset', 'Reset the database')
520 .action(async () => {
521 const confirmed = await confirm('This will delete all data. Continue?')
522 if (confirmed) {
523 log.info('Resetting database...')
524 }
525 })
526
527 // Handle unknown sub-commands
528 cli.on('database:*', () => {
529 log.error('Unknown database command')
530 log.info('Run `buddy database` for available commands')
531 process.exit(1)
532 })
533
534 return cli
535}
536```
537
538## Error Handling
539
540Handle errors gracefully:
541
542```typescript
543import { ExitCode } from '@stacksjs/types'
544
545export default function (cli: CLI) {
546 cli
547 .command('risky-operation', 'Perform a risky operation')
548 .action(async () => {
549 try {
550 log.info('Starting operation...')
551
552 const result = await riskyFunction()
553
554 if (!result.success) {
555 log.error(`Operation failed: ${result.error}`)
556 process.exit(ExitCode.FatalError)
557 }
558
559 log.success('Operation completed!')
560 process.exit(ExitCode.Success)
561 }
562 catch (error) {
563 log.error('An unexpected error occurred:')
564 console.error(error)
565 process.exit(ExitCode.FatalError)
566 }
567 })
568
569 return cli
570}
571```
572
573## Complete Example: Deployment CLI
574
575```typescript
576// app/Commands/Deploy.ts
577import type { CLI } from '@stacksjs/types'
578import process from 'node:process'
579import {
580 box,
581 colors,
582 confirm,
583 log,
584 progress,
585 select,
586 spinner,
587 table,
588} from '@stacksjs/cli'
589import { ExitCode } from '@stacksjs/types'
590
591interface DeployOptions {
592 environment: string
593 force: boolean
594 skipTests: boolean
595}
596
597export default function (cli: CLI) {
598 cli
599 .command('deploy [environment]', 'Deploy the application')
600 .option('--force, -f', 'Force deployment without confirmation', { default: false })
601 .option('--skip-tests', 'Skip running tests before deployment', { default: false })
602 .action(async (environment: string | undefined, options: DeployOptions) => {
603 // Select environment if not provided
604 const env = environment || await select('Select deployment environment:', [
605 'development',
606 'staging',
607 'production',
608 ])
609
610 // Show deployment info
611 box(`Deploying to ${colors.bold(env)}`, {
612 title: 'Deployment',
613 borderColor: env === 'production' ? 'red' : 'blue',
614 })
615
616 console.log('')
617
618 // Confirm for production
619 if (env === 'production' && !options.force) {
620 const confirmed = await confirm(
621 colors.yellow('You are deploying to PRODUCTION. Are you sure?')
622 )
623
624 if (!confirmed) {
625 log.warning('Deployment cancelled.')
626 process.exit(ExitCode.Success)
627 }
628 }
629
630 // Run tests
631 if (!options.skipTests) {
632 const testSpinner = spinner('Running tests...')
633 testSpinner.start()
634
635 try {
636 await runTests()
637 testSpinner.stop('Tests passed!')
638 }
639 catch (error) {
640 testSpinner.fail('Tests failed!')
641 log.error('Fix failing tests before deployment.')
642 process.exit(ExitCode.FatalError)
643 }
644 }
645
646 // Build
647 const buildSpinner = spinner('Building application...')
648 buildSpinner.start()
649
650 try {
651 await buildApplication()
652 buildSpinner.stop('Build complete!')
653 }
654 catch (error) {
655 buildSpinner.fail('Build failed!')
656 process.exit(ExitCode.FatalError)
657 }
658
659 // Deploy
660 log.info('Deploying...')
661 const bar = progress('Uploading files', { total: 100 })
662
663 for (let i = 0; i <= 100; i += 10) {
664 await sleep(200) // Simulate upload
665 bar.update(i)
666 }
667
668 bar.stop('Upload complete!')
669
670 // Show deployment summary
671 console.log('')
672 log.success('Deployment successful!')
673 console.log('')
674
675 table([
676 { key: 'Environment', value: env },
677 { key: 'Version', value: '1.2.3' },
678 { key: 'URL', value: `https://${env}.example.com` },
679 { key: 'Deployed at', value: new Date().toISOString() },
680 ], {
681 columns: ['key', 'value'],
682 headers: ['Property', 'Value'],
683 })
684
685 process.exit(ExitCode.Success)
686 })
687
688 return cli
689}
690
691// Helper functions
692async function runTests() {
693 await sleep(2000)
694}
695
696async function buildApplication() {
697 await sleep(1500)
698}
699
700function sleep(ms: number) {
701 return new Promise(resolve => setTimeout(resolve, ms))
702}
703```
704
705## Distributing Your CLI
706
707### As npm Package
708
709Your CLI can be distributed as an npm package:
710
711```json
712// package.json
713{
714 "name": "my-cli",
715 "version": "1.0.0",
716 "bin": {
717 "my-cli": "./dist/cli.js"
718 }
719}
720```
721
722### As Binary
723
724Build a standalone binary:
725
726```bash
727buddy build:cli
728```
729
730This creates platform-specific binaries in the `dist/` directory.
731
732## Next Steps
733
734Now that you know how to build CLIs, continue to:
735
736- [Build a Desktop App](/bootcamp/desktop) - Package your app as a desktop application
737- [Testing How-To](/bootcamp/how-to/testing) - Test your CLI commands
738- [Deployment How-To](/bootcamp/how-to/deploy) - Distribute your CLI
739
740## Related Documentation
741
742- [Commands Guide](/basics/commands)
743- [CLI Package](/packages/cli)