pathenger 0.1.0

package/README.md

@@ -0,0 +1,567 @@
+# pathenger
+
+Step-by-step flows for command-line apps. Explicit, branching, testable.
+
+Most prompt libraries hand you widgets and wish you luck with the orchestration. pathenger inverts that: you declare your CLI as a graph of steps, each one of which shows a message, does some work, or asks a question, and the flow engine walks the graph until you tell it to exit. Branches, loops, validation, and async work are all first-class. Your CLI _is_ the flow.
+
+```ts
+import { pathenger } from 'pathenger'
+
+const io = pathenger.create()
+
+io.step.output({
+	id: 'welcome',
+	message: 'Welcome aboard.',
+	duration: 1000,
+	next: 'name'
+})
+
+io.step.input({
+	id: 'name',
+	type: 'text',
+	message: 'What is your name?',
+	validate: (value) => value.length > 1 || 'A little longer, please.',
+	next: 'goodbye'
+})
+
+io.step.output({
+	id: 'goodbye',
+	message: () => `Nice to meet you, ${io.results.name}.`,
+	level: 'success',
+	next: io.exit()
+})
+
+io.start('welcome')
+```
+
+That's a complete program. No `main()`, no prompt-then-if-then-prompt spaghetti. Register steps, point them at each other, start the flow.
+
+## Install
+
+```bash
+pnpm add pathenger
+```
+
+## The mental model
+
+Three ideas, and you know the whole library:
+
+1. **A step either _does_ something or _asks_ something.** Output steps show a message and optionally run a task. Input steps show a message and collect an answer. A step never does both. If you need both then that's two steps. Step by step by step. Explicit progression.
+
+2. **Every step declares `next`.** There is no implicit "then the one below it." `next` is a step id, or a function that returns one, which is how you branch. Because `next` is explicit, it can point _backwards_ and cycles are _legal_, which is how you build menus and REPL-style apps that run until the user quits.
+
+3. **`io` is your app's shared state.** `io.results` holds every step's result, keyed by step id (the engine writes it). `io.store` is yours: a typed grab-bag for anything that spans steps or lives in extracted functions.
+
+## Creating your instance
+
+Create one `io` per app and export it from a module. Every step file and every extracted helper imports it from there. No threading a context argument five levels deep.
+
+```ts
+// source/io.ts
+import { pathenger } from 'pathenger'
+
+type StoreT {
+	isPnpmInstalled?: boolean
+	templates?: Template[]
+}
+
+export const io = pathenger.create<StoreT>()
+```
+
+The generic types `io.store` so every access is checked and autocompleted across your whole codebase. You can also declare your results shape with a second generic — see [TypeScript](#typescript).
+
+Your entry point imports the step files (importing registers them) and starts the flow:
+
+```ts
+// source/index.ts
+import { io } from './io'
+import './steps/welcome'
+import './steps/mainMenu'
+import './steps/createProduct'
+
+io.start('welcome')
+```
+
+## Output steps
+
+An output step shows a message, optionally runs async work while the message is on screen, then moves on.
+
+```ts
+io.step.output({
+	id: 'checkPnpm',
+	message: 'Checking for pnpm.',
+	duration: 1000,
+	task: async () => await hasGlobalPnpm(),
+	next: (result) => (result ? 'cloneTemplate' : 'noPnpmWarning')
+})
+```
+
+Lifecycle: **pre → message → task → post → next**
+
+| Property   | Type                                                     | Required | What it does                                                                                                   |
+| ---------- | -------------------------------------------------------- | -------- | -------------------------------------------------------------------------------------------------------------- |
+| `id`       | `string`                                                 | yes      | Unique step id. Registering a duplicate throws immediately.                                                    |
+| `message`  | `string \| () => string`                                 | yes      | The text shown for this step. Functions run synchronously at render time.                                      |
+| `level`    | `'info' \| 'success' \| 'warning' \| 'error' \| 'debug'` | no       | Styling/color of the message. Defaults to `'info'`.                                                            |
+| `duration` | `number`                                                 | no       | Minimum milliseconds the step stays on screen (see below).                                                     |
+| `pre`      | `() => void \| Promise<void>`                            | no       | Async setup, runs silently _before_ the message renders.                                                       |
+| `task`     | `() => unknown \| Promise<unknown>`                      | no       | Async work, runs _while_ the message is on screen, with a spinner. Its return value becomes the step's result. |
+| `post`     | `(result) => void \| Promise<void>`                      | no       | Side effects after the result is locked in. Cannot block progression.                                          |
+| `next`     | `string \| (result) => string \| ExitToken`              | yes      | Where to go. Receives the step's result.                                                                       |
+
+### `duration`
+
+`duration` is the **minimum time the step stays on screen**. That single rule covers everything:
+
+- Message-only step with `duration: 1000` → the message shows for one second, then the flow advances. Use this to pace output so it reads as deliberate rather than dumped.
+- Step with a `task` → the spinner runs for _at least_ `duration`, and longer if the task is still pending. Fast tasks don't flash; slow tasks aren't cut off.
+
+### `pre` vs `task`
+
+`pre` runs **before** the message renders. It's setup: fetch the data the step needs to display itself. `task` runs **while** the message is on screen. It's the work the message narrates, i.e "Cloning product template…" with a spinner, where the message _is the UX for the work_. If you fold your work into `pre`, the user stares at the previous step while it happens and your message flashes by after the fact. Put display prerequisites in `pre`; put the actual work in `task`.
+
+### The step's result
+
+An output step's result is its task's return value (`undefined` if there's no task). It lands in `io.results[id]` and is passed to `next` and `post`. Tasks that need to record more than one value write to `io.store`. (That is what it is for.)
+
+## Input steps
+
+An input step shows a message and collects an answer.
+
+```ts
+io.step.input({
+	id: 'productId',
+	type: 'text',
+	message: 'What will your product ID be?',
+	tip: 'alpha-numeric with dashes and underscores',
+	placeholder: 'my-new-product',
+	filter: /^[a-zA-Z0-9_-]*$/,
+	validate: async (value) => {
+		const existingIds = await fetcher('/api/getProductIds')
+		return existingIds.includes(value) ? `"${value}" is already taken.` : true
+	},
+	next: 'productName'
+})
+```
+
+Lifecycle: **pre → message → input (filter per keystroke) → validate (on submit) → post → next**
+
+| Property   | Type                                                   | Required | What it does                                                                                                                         |
+| ---------- | ------------------------------------------------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------ |
+| `id`       | `string`                                               | yes      | Unique step id.                                                                                                                      |
+| `type`     | `'text' \| 'select' \| 'multiselect' \| 'confirm'`     | yes      | Which prompt to render.                                                                                                              |
+| `message`  | `string \| () => string`                               | yes      | The question. Functions run synchronously at render time.                                                                            |
+| `tip`      | `string \| () => string`                               | no       | Persistent hint rendered dim beneath the input. Turns red when validation fails.                                                     |
+| `pre`      | `() => void \| Promise<void>`                          | no       | Async setup before the message renders.                                                                                              |
+| `validate` | `(value) => true \| string \| Promise<true \| string>` | no       | Runs on ENTER. Return a string to block progression and show it as the reason, in red. May be async — a spinner shows while it runs. |
+| `post`     | `(result) => void \| Promise<void>`                    | no       | Side effects after the answer is accepted. Cannot block progression — that's `validate`'s job.                                       |
+| `next`     | `string \| (result) => string \| ExitToken`            | yes      | Where to go. Receives the answer.                                                                                                    |
+
+An input step's result is the submitted answer. It lands in `io.results[id]` and is passed to `validate`, `post`, and `next`.
+
+### `type: 'text'`
+
+| Property      | Type                                   | What it does                                                                                                                                                                                                           |
+| ------------- | -------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `value`       | `string \| () => string`               | Initial _editable_ value, prefilled in the input.                                                                                                                                                                      |
+| `placeholder` | `string \| () => string`               | Ghost text shown when the input is empty. Never submitted.                                                                                                                                                             |
+| `filter`      | `RegExp \| (value: string) => boolean` | Runs on **every keystroke**, synchronously. The keystroke is rejected if the candidate value fails. Regexes use **full-match semantics** — `/^[a-z]*$/` and `/[a-z]*/` behave identically; the whole value must match. |
+
+`filter` and `validate` split validation the way it actually needs to be split: `filter` is cheap and sync, so it can run per keystroke and physically keep bad characters out. `validate` runs once on submit, so it's allowed to be async and expensive — hit an API, read the filesystem, take its time behind a spinner. Don't put a network call in a keystroke handler; pathenger won't let you.
+
+```ts
+// Deriving the initial value from an earlier answer
+io.step.input({
+	id: 'productName',
+	type: 'text',
+	message: 'What will your product title be?',
+	value: () => titleCase(io.results.productId),
+	next: 'productRoute'
+})
+```
+
+### `type: 'select'`
+
+| Property  | Type                                                                           | What it does                     |
+| --------- | ------------------------------------------------------------------------------ | -------------------------------- |
+| `options` | `Option[] \| () => Option[]` where `Option = { label: string, value: string }` | The choices. Arrow keys + ENTER. |
+
+The result is the chosen option's `value` — the string itself, not the `{ label, value }` object.
+
+```ts
+io.step.input({
+	id: 'deployment',
+	type: 'select',
+	message: 'Is your product deployed on-prem or in the cloud?',
+	options: [
+		{ label: 'On-Prem', value: 'on-prem' },
+		{ label: 'Cloud', value: 'cloud' }
+	],
+	next: (result) => (result === 'on-prem' ? 'verifyOnPrem' : 'shouldInstall')
+})
+```
+
+### `type: 'multiselect'`
+
+Same `options` shape as `select`; SPACE toggles, ENTER submits. The result is an **array** of the chosen values (empty array if nothing was chosen — use `validate` to require a minimum).
+
+```ts
+io.step.input({
+	id: 'features',
+	type: 'multiselect',
+	message: 'Which features should be scaffolded?',
+	options: featureOptions,
+	validate: (values) => values.length > 0 || 'Pick at least one.',
+	next: 'confirmPlan'
+})
+```
+
+### `type: 'confirm'`
+
+| Property | Type     | What it does                                    |
+| -------- | -------- | ----------------------------------------------- |
+| `yes`    | `string` | Label for the affirmative. Defaults to `'Yes'`. |
+| `no`     | `string` | Label for the negative. Defaults to `'No'`.     |
+
+The result is a `boolean`.
+
+```ts
+io.step.input({
+	id: 'verifyOnPrem',
+	type: 'confirm',
+	message: 'Are you sureeee it is on-prem?',
+	yes: 'Yes, I am sure',
+	no: 'No, not really',
+	next: 'shouldInstall'
+})
+```
+
+## Dynamic properties are sync. Lifecycle hooks are async.
+
+This is the rule that keeps steps predictable, so it gets its own heading.
+
+Any _display_ property — `message`, `tip`, `placeholder`, `value`, `options` — can be a function, and that function runs **synchronously at render time**. It reads from `io.results` and `io.store`; it never fetches. Anything async belongs in a lifecycle hook: `pre`, `task`, `validate`, or `post`.
+
+So "the select options come from an API" looks like this — `pre` fetches, `options` reads:
+
+```ts
+io.step.input({
+	id: 'chooseTemplate',
+	pre: async () => {
+		io.store.templates = await fetcher('/api/templates')
+	},
+	type: 'select',
+	message: 'Which template?',
+	options: () =>
+		io.store.templates.map((template) => ({ label: template.name, value: template.id })),
+	next: 'confirmTemplate'
+})
+```
+
+The render loop never awaits a property, and you always know exactly when your code runs.
+
+## Branching and why explicit `next` is the point
+
+`next` is required on every step (it is literally the feature). Because progression is always explicit:
+
+- **Branches are just functions.** `next: (result) => result ? 'installDeps' : 'skipInstall'`
+- **Cycles are legal.** A `next` can point at any registered step, including one "behind" it. Point every branch's final step back at a menu and you have an app that runs until the user quits:
+
+```ts
+io.step.input({
+	id: 'mainMenu',
+	type: 'select',
+	message: 'What would you like to do?',
+	options: [
+		{ label: 'Create a product', value: 'createProduct' },
+		{ label: 'Delete a product', value: 'deleteProduct' },
+		{ label: 'Quit', value: 'quit' }
+	],
+	next: (result) => (result === 'quit' ? io.exit() : result)
+})
+```
+
+Notice the trick in that last line: option values can _be_ step ids, so the menu routes itself.
+
+## Exiting
+
+`io.exit()` returns an exit token. Use it anywhere a step id is accepted:
+
+```ts
+next: io.exit() // clean exit, status code 0
+next: () => io.exit() // same, from a branch
+next: () => io.exit.error('Could not clone. Check your SSH credentials.') // red message, status code 1
+```
+
+No magic strings. An exit token can't collide with a step id, can't be typo'd into a broken reference, and carries its message as data instead of a parsed prefix.
+
+## `io.results` and `io.store`
+
+**`io.results`** is engine-owned: after a step completes, `io.results[id]` holds its result (the answer for input steps, the task's return value for output steps). Read it anywhere — in later steps' dynamic properties, in `next` functions, in extracted helpers.
+
+**`io.store`** is yours. It's the shared state for everything that isn't a single step's result: flags set by tasks, data fetched in `pre`, accumulations across a loop. Because your app exports one `io` instance, extracted functions just import it — no context parameter threading through five layers of helpers:
+
+```ts
+// source/utilities/cloneTemplate.ts
+import { io } from '../io'
+
+export async function cloneTemplate() {
+	try {
+		await git.clone(templateUrl, io.results.productId)
+		io.store.didCloneSucceed = true
+	} catch {
+		io.store.didCloneSucceed = false
+	}
+}
+```
+
+Rule of thumb: if one step produces it and the flow consumes it, let it be the step's result. If it's shared, shaped, or written from helpers, put it in the store.
+
+## Starting the flow — and what gets validated
+
+```ts
+io.start('welcome')
+```
+
+`io.start` validates the graph **before rendering anything**:
+
+- Every static string `next` must resolve to a registered step. A typo fails at startup with a message naming the step and the missing id — never mid-flow after the user has answered six prompts.
+- The start id must exist.
+- Unreachable steps produce a warning (they're often a sign of a broken reference elsewhere).
+
+Duplicate ids don't even make it that far — `io.step.output` / `io.step.input` throw at registration.
+
+Function `next`s can't be checked statically, so they're checked at runtime: returning an unknown id produces an error that names _which step_ returned _which bad id_, not a stack trace from the engine's guts.
+
+`Ctrl+C` is handled for you: the terminal is restored (no half-drawn prompt), an optional `onCancel` runs, and the process exits cleanly:
+
+```ts
+io.start('welcome', { onCancel: () => console.log('\nNo worries. Nothing was changed.') })
+```
+
+## Preseeded answers
+
+Pass answers up front and their steps resolve without prompting — the step still runs its lifecycle (`pre`, `validate`, `post`, `next`), it just skips the interactive part. This is how a scaffolding CLI grows a `--yes` mode, and how flows run in CI:
+
+```ts
+io.start('welcome', {
+	answers: { productId: 'demo-product', deployment: 'cloud', shouldInstall: false }
+})
+```
+
+Preseeded answers still go through `validate`. If a preseeded answer fails validation, the flow falls back to prompting for that step interactively — or, with `interactive: false`, exits with an error. `interactive: false` also means any _unseeded_ input step is an error: perfect for CI, where a hung prompt is a hung pipeline.
+
+## Testing
+
+Interactive CLIs are notoriously untestable. pathenger flows aren't, because the graph is data. `io.test` runs the flow headless — no TTY, no rendering, durations skipped — and returns what happened:
+
+```ts
+import { io } from '../source/io'
+import '../source/steps'
+
+test('choosing on-prem routes through verification', async () => {
+	const run = await io.test('welcome', {
+		answers: {
+			productId: 'demo-product',
+			productName: 'Demo Product',
+			productRoute: '/demo-product',
+			deployment: 'on-prem',
+			verifyOnPrem: true,
+			shouldInstall: false
+		}
+	})
+
+	expect(run.visited).toContain('verifyOnPrem')
+	expect(run.results.deployment).toBe('on-prem')
+	expect(run.exit.code).toBe(0)
+})
+```
+
+`run.visited` is the ordered list of step ids the flow walked, `run.results` is the final results object, and `run.exit` tells you how it ended. Assert on paths, not pixels.
+
+`pathenger.create()` returns an instance precisely so tests can isolate: your _app_ makes `io` a singleton by exporting it, but a test can always construct a fresh one.
+
+## Handing over the terminal
+
+Sometimes a task needs to run a child process that has its own interactive moment — `git clone` asking for an SSH passphrase, an editor, a pager. Don't fight it; hand over the terminal:
+
+```ts
+io.step.output({
+	id: 'cloneTemplate',
+	message: 'Cloning product template.',
+	task: async () => {
+		return await io.suspend(() =>
+			spawnWithInheritedStdio('git', ['clone', templateUrl, io.results.productId])
+		)
+	},
+	next: (result) =>
+		result.succeeded
+			? 'complete'
+			: io.exit.error('Clone failed. Check your SSH credentials.')
+})
+```
+
+`io.suspend` restores the cursor, leaves raw mode, runs your function with the terminal fully released, then re-enters the flow and redraws. The child process prompts however it wants; pathenger picks up where it left off.
+
+## TypeScript
+
+Declare your store and (optionally) your results shape when you create the instance:
+
+```ts
+interface Store {
+	isPnpmInstalled?: boolean
+	templates?: Template[]
+}
+
+interface Results {
+	productId: string
+	productName: string
+	deployment: 'on-prem' | 'cloud'
+	shouldInstall: boolean
+	features: string[]
+}
+
+export const io = pathenger.create<Store, Results>()
+```
+
+Now `io.store.isPnpmInstalled` is a checked `boolean | undefined`, `io.results.deployment` is `'on-prem' | 'cloud'`, and a typo'd key is a compile error. Declaring your shapes up front is very much in the spirit of the library: explicit beats inferred-and-mysterious.
+
+## A complete example
+
+The product-creation CLI, end to end:
+
+```ts
+import { pathenger } from 'pathenger'
+import { titleCase } from 'change-case'
+import { fetcher, hasGlobalPnpm, cloneTemplate } from './utilities'
+
+interface Store {
+	didCloneSucceed?: boolean
+}
+
+const io = pathenger.create<Store>()
+
+io.step.output({
+	id: 'welcome',
+	message: 'Welcome to the product creator.',
+	duration: 1000,
+	next: 'productId'
+})
+
+io.step.input({
+	id: 'productId',
+	type: 'text',
+	message: 'What will your product ID be?',
+	tip: 'alpha-numeric with dashes and underscores',
+	placeholder: 'my-new-product',
+	filter: /^[a-zA-Z0-9_-]*$/,
+	next: 'productName',
+
+	validate: async (value) => {
+		const existingIds = await fetcher('/api/getProductIds')
+		return existingIds.includes(value) ? `"${value}" is already taken.` : true
+	}
+})
+
+io.step.input({
+	id: 'productName',
+	type: 'text',
+	message: 'What will your product title be?',
+	value: () => titleCase(io.results.productId),
+	next: 'productRoute'
+})
+
+io.step.input({
+	id: 'productRoute',
+	type: 'text',
+	message: 'What route should it live at?',
+	placeholder: () => '/' + io.results.productId,
+	next: 'deployment'
+})
+
+io.step.input({
+	id: 'deployment',
+	type: 'select',
+	message: 'Is your product deployed on-prem or in the cloud?',
+	options: [
+		{ label: 'On-Prem', value: 'on-prem' },
+		{ label: 'Cloud', value: 'cloud' }
+	],
+	next: (result) => (result === 'on-prem' ? 'verifyOnPrem' : 'shouldInstall')
+})
+
+io.step.input({
+	id: 'verifyOnPrem',
+	type: 'confirm',
+	message: 'Are you sureeee it is on-prem?',
+	yes: 'Yes, I am sure',
+	no: 'No, not really',
+	next: 'shouldInstall'
+})
+
+io.step.input({
+	id: 'shouldInstall',
+	type: 'confirm',
+	message: 'Go ahead and install dependencies?',
+	next: (result) => (result ? 'checkPnpm' : 'cloneTemplate')
+})
+
+io.step.output({
+	id: 'checkPnpm',
+	message: 'Checking for pnpm.',
+	duration: 1000,
+	task: async () => await hasGlobalPnpm(),
+	next: (result) => (result ? 'cloneTemplate' : 'noPnpmWarning')
+})
+
+io.step.output({
+	id: 'noPnpmWarning',
+	level: 'warning',
+	message: 'pnpm is not globally installed. Skipping dependency install.',
+	duration: 1000,
+	next: 'cloneTemplate'
+})
+
+io.step.output({
+	id: 'cloneTemplate',
+	message: 'Cloning product template.',
+	task: async () => {
+		await cloneTemplate()
+	},
+	next: () =>
+		io.store.didCloneSucceed
+			? 'complete'
+			: io.exit.error('Failed to clone the template. Check your SSH credentials.')
+})
+
+io.step.output({
+	id: 'complete',
+	level: 'success',
+	message: () =>
+		`Product created. cd ${io.results.productId} && pnpm start to begin development.`,
+	duration: 1250,
+	next: io.exit()
+})
+
+io.start('welcome')
+```
+
+## Why not just use a prompt library?
+
+inquirer, prompts, and @clack/prompts are good at what they do: individual prompt widgets. But the moment your CLI has branches, loops, validation against live data, or async work between questions, the orchestration lands in your lap as a pile of `if`s and `await`s, and it's exactly the part that's hard to read, hard to change, and impossible to test.
+
+pathenger owns the orchestration. The flow is declared, so it can be validated at startup, preseeded for CI, walked headlessly in tests, and read top-to-bottom by the next person. The prompts are the easy part. The graph is the product.
+
+## API summary
+
+|                                        |                                                                                     |
+| -------------------------------------- | ----------------------------------------------------------------------------------- |
+| `pathenger.create<Store, Results>()`   | Create an `io` instance. Export one per app.                                        |
+| `io.step.output(step)`                 | Register an output step. Throws on duplicate id.                                    |
+| `io.step.input(step)`                  | Register an input step. Throws on duplicate id.                                     |
+| `io.start(startId, options?)`          | Validate the graph and run the flow. Options: `answers`, `interactive`, `onCancel`. |
+| `io.test(startId, options?)`           | Run headless. Returns `{ visited, results, exit }`.                                 |
+| `io.results`                           | Every completed step's result, keyed by step id. Engine-owned.                      |
+| `io.store`                             | Your shared state. Typed by the `Store` generic.                                    |
+| `io.exit()` / `io.exit.error(message)` | Exit tokens, usable anywhere a step id is accepted.                                 |
+| `io.suspend(fn)`                       | Release the terminal for a child process, then resume the flow.                     |

package/package.json

@@ -0,0 +1,36 @@
+{
+	"name": "pathenger",
+	"version": "0.1.0",
+	"description": "Step-by-step flows for command-line apps. Explicit, branching, testable.",
+	"type": "module",
+	"main": "./dist/index.js",
+	"types": "./dist/index.d.ts",
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"import": "./dist/index.js"
+		}
+	},
+	"files": [
+		"dist"
+	],
+	"scripts": {
+		"build": "tsc"
+	},
+	"keywords": [
+		"cli",
+		"prompts",
+		"flow",
+		"wizard",
+		"interactive",
+		"state-machine"
+	],
+	"license": "ISC",
+	"dependencies": {
+		"picocolors": "^1.1.1"
+	},
+	"devDependencies": {
+		"@types/node": "^22.0.0",
+		"typescript": "^5.5.0"
+	}
+}