@fabrika/installation-init 0.3.1 → 0.3.2

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@fabrika/installation-init",
-	"version": "0.3.1",
+	"version": "0.3.2",
 	"type": "module",
 	"repository": {
 		"type": "git",
@@ -27,7 +27,7 @@
 	},
 	"dependencies": {
 		"zod": "^3.25.76",
-		"@fabrika/app": "^0.3.1",
-		"@fabrika/iam-contract": "^0.3.1"
+		"@fabrika/app": "^0.3.2",
+		"@fabrika/iam-contract": "^0.3.2"
 	}
 }

package/src/checkout.ts

@@ -0,0 +1,45 @@
+import { existsSync, realpathSync } from 'node:fs'
+import { dirname, join, relative, resolve } from 'node:path'
+
+/** `--checkout=<dir>`: where `platform init` keeps the sidecar repository's local checkout. */
+export const CHECKOUT_FLAG = '--checkout'
+
+/** `dir` with every symlink in its existing part resolved, so a link into a repository is seen as inside it. */
+const physicalPath = (dir: string): string => {
+	let existing = dir
+	while (!existsSync(existing)) {
+		const parent = dirname(existing)
+		if (parent === existing) return dir
+		existing = parent
+	}
+	return join(realpathSync(existing), relative(existing, dir))
+}
+
+/** The git work tree that encloses `dir`, not counting `dir` being a checkout itself. */
+const enclosingRepository = (dir: string): string | undefined => {
+	let current = dirname(physicalPath(dir))
+	while (true) {
+		if (existsSync(resolve(current, '.git'))) return current
+		const parent = dirname(current)
+		if (parent === current) return undefined
+		current = parent
+	}
+}
+
+/**
+ * The sidecar checkout directory: `--checkout`, or `defaultName` in the working directory.
+ *
+ * Refused inside another repository, where it would sit as an untracked nested repository that a
+ * blanket `git add` records as a gitlink.
+ */
+export const sidecarCheckoutDir = (explicit: string | undefined, defaultName: string, cwd: string = process.cwd()): string => {
+	const dir = resolve(cwd, explicit ?? defaultName)
+	const repository = enclosingRepository(dir)
+	if (repository !== undefined) {
+		throw new Error(
+			`the sidecar checkout ${dir} would sit inside the git repository at ${repository}. `
+				+ `Pass ${CHECKOUT_FLAG}=<dir> outside it, or run init from a directory that is not in a repository`,
+		)
+	}
+	return dir
+}

package/src/confirmations.ts

@@ -0,0 +1,44 @@
+import { confirm as promptConfirm } from './prompt'
+
+/** The one question `install` and `init` ask. Injected so a flow can be exercised without a TTY. */
+export interface Confirmations {
+	confirm(question: string, defaultYes?: boolean): Promise<boolean>
+}
+
+/**
+ * The one way a confirming command runs with nobody watching it.
+ *
+ * Every confirmation defaults to yes, so a pipe carrying blank lines would answer all of them with
+ * nobody reading what they agree to — which is why saying yes unattended is a FLAG and never an
+ * inference: it makes the choice explicit, and it puts it in the shell history of whoever ran it.
+ */
+export const UNATTENDED_FLAG = '--yes'
+
+/**
+ * How a command's confirmations are answered — and the refusal when nothing can answer them.
+ *
+ * Unattended, each question is still printed with the answer it was given, so the run leaves the same
+ * record of what was agreed to that an interactive one does.
+ */
+export const confirmations = (
+	unattended: boolean,
+	stdin: { readonly isTTY?: boolean },
+	announce: (line: string) => void,
+	whatItDoes: string,
+): Confirmations => {
+	if (unattended) {
+		return {
+			confirm: (question) => {
+				announce(`${question} yes (${UNATTENDED_FLAG})`)
+				return Promise.resolve(true)
+			},
+		}
+	}
+	if (stdin.isTTY !== true) {
+		throw new Error(
+			`stdin is not a terminal, so nobody is here to confirm what this command does — it ${whatItDoes}. `
+				+ `Run it from a terminal, or pass \`${UNATTENDED_FLAG}\` to answer every confirmation yes unattended`,
+		)
+	}
+	return { confirm: (question, defaultYes) => promptConfirm(question, defaultYes) }
+}

package/src/index.ts

@@ -9,6 +9,8 @@ export {
 	type IamAdminClient,
 	type IamAdminConnection,
 } from './admin'
+export { CHECKOUT_FLAG, sidecarCheckoutDir } from './checkout'
+export { type Confirmations, confirmations, UNATTENDED_FLAG } from './confirmations'
 export {
 	configureEnvironment,
 	type EnvironmentConfig,
@@ -19,7 +21,8 @@ export {
 } from './environment'
 export { ghRepoExists, hasGhCli } from './gh'
 export { action, detail, fail, info, ok, step, url, warn } from './log'
-export { confirm, required, retry, secret, secretOrEnv, select, text } from './prompt'
+export { type CommandEnv, describeArgument, readEnv, readFlag, requiredSetting, setting, shellWord } from './options'
+export { confirm } from './prompt'
 export {
 	branchProtectionCommand,
 	DEPLOYMENT_BRANCH_POLICY,

package/src/options.ts

@@ -0,0 +1,35 @@
+// The reading rules every `fabrika platform … --provider=zerops` parser shares: a flag beats the
+// environment variable beside it, a blank value is an absent one, and a flag given twice is refused.
+
+export type CommandEnv = Record<string, string | undefined>
+
+export const readFlag = (argv: readonly string[], name: string): string | undefined => {
+	const prefix = `${name}=`
+	const matches = argv.filter((arg) => arg.startsWith(prefix))
+	if (matches.length > 1) {
+		throw new Error(`${name} was given more than once`)
+	}
+	const value = matches[0]?.slice(prefix.length)
+	return value === undefined || value.trim() === '' ? undefined : value.trim()
+}
+
+export const readEnv = (env: CommandEnv, name: string): string | undefined => {
+	const value = env[name]
+	return value === undefined || value.trim() === '' ? undefined : value.trim()
+}
+
+export const setting = (argv: readonly string[], env: CommandEnv, flag: string, variable: string): string | undefined =>
+	readFlag(argv, flag) ?? readEnv(env, variable)
+
+export const requiredSetting = (value: string | undefined, flag: string, variable: string): string => {
+	if (value === undefined) {
+		throw new Error(`${flag}=<value> or ${variable} is required`)
+	}
+	return value
+}
+
+/** How a refusal names an argument: a flag by its name only, never its value, which may be a pasted credential. */
+export const describeArgument = (arg: string): string => arg.startsWith('-') ? `\`${arg.split('=')[0]}\`` : 'a positional argument'
+
+/** One argument as a POSIX shell reads it back unchanged, for the rerun command a declined step prints. */
+export const shellWord = (arg: string): string => /^[\w@%+=:,./-]+$/.test(arg) ? arg : `'${arg.replaceAll("'", `'\\''`)}'`

package/src/prompt.ts

@@ -1,69 +1,23 @@
 /**
- * Interactive prompts for the fabrika CLI, over `node:readline/promises`.
+ * The one interactive question the fabrika CLI asks: a yes/no confirmation before a step that leaves
+ * the operator's machine. Every other input is a flag or an environment variable, and a run with no
+ * terminal answers confirmations with `--yes` (`confirmations.ts`), so this reads a TTY only.
  *
- * `secret()` is the security-critical one: it reads a value WITHOUT echoing it to the terminal (no
- * keystrokes, no final value), so a token/key pasted at the prompt never lands in scrollback or a
- * screen-share. Every other prompt echoes normally. None of these functions ever log the value they
- * return — the caller routes secrets into a child-process env, never back through `log.ts`.
- *
- * ── Why stdin is read two different ways ──────────────────────────────────────────────────────────
- *
- * A PIPED stdin is read by ONE reader for the whole command. Closing a readline discards whatever it
- * has already buffered, so a fresh interface per question swallows every answer after the first and
- * the command stops on question 2 — which is what made `platform init` undrivable without a PTY.
- *
- * A TTY keeps a fresh interface per question, closed afterwards. A persistent one holds the terminal
- * in raw mode (`-icanon -echo`, measured) between questions, and `init` spawns `git` and `gh` between
- * them — a child inheriting a raw terminal echoes nothing and stair-steps its output.
+ * A fresh interface per question, closed afterwards: a persistent one holds the terminal in raw mode
+ * (`-icanon -echo`, measured) between questions, and init spawns `git` and `gh` between them — a child
+ * inheriting a raw terminal echoes nothing and stair-steps its output.
  */
 
-import { createInterface, type Interface } from 'node:readline/promises'
-import type { Readable, Writable } from 'node:stream'
-import { fail, info } from './log'
-
-/** A free-text prompt. Returns the trimmed answer, or `fallback` when the operator just hits enter. */
-export async function text(question: string, fallback?: string): Promise<string> {
-	const suffix = fallback !== undefined && fallback !== '' ? ` [${fallback}]` : ''
-	const answer = stripTerminalCruft(await ask(`${question}${suffix}: `)).trim()
-	if (answer === '' && fallback !== undefined) {
-		return fallback
-	}
-	return answer
-}
-
-/**
- * A required free-text prompt: re-asks until the operator gives a non-empty answer (or a fallback is
- * supplied and accepted). Used for values the CLI cannot proceed without.
- */
-export async function required(question: string, fallback?: string): Promise<string> {
-	for (;;) {
-		const value = await text(question, fallback)
-		if (value !== '') {
-			return value
-		}
-		console.log('    (a value is required)')
-	}
-}
+import { createInterface } from 'node:readline/promises'
 
-/**
- * A HIDDEN-ECHO prompt for secret values. Keystrokes are not echoed and the final value is not
- * printed — the line is consumed silently. The captured value is run through `stripTerminalCruft` to
- * remove bracketed-paste markers / escape sequences some terminals inject around a paste (which would
- * otherwise corrupt a pasted token), then returned. The value is NEVER logged by this module.
- */
-export async function secret(question: string): Promise<string> {
-	process.stdout.write(`${question}: `)
-	// While reading, intercept the output stream so readline's own echo of the typed characters is
-	// suppressed — only the newline at the end is allowed through, to move the cursor down.
-	const muted = muteOutput()
-	try {
-		const answer = await ask('', question)
-		return stripTerminalCruft(answer)
-	} finally {
-		muted.restore()
-		// readline swallowed the echoed newline while muted; emit one so the next line starts fresh.
-		process.stdout.write('\n')
+/** A yes/no confirmation. Defaults to `defaultYes` on an empty answer. */
+export async function confirm(question: string, defaultYes = false): Promise<boolean> {
+	const hint = defaultYes ? 'Y/n' : 'y/N'
+	const answer = stripTerminalCruft(await ask(`${question} [${hint}]: `)).trim().toLowerCase()
+	if (answer === '') {
+		return defaultYes
 	}
+	return answer === 'y' || answer === 'yes'
 }
 
 /**
@@ -95,207 +49,14 @@ function stripTerminalCruft(value: string): string {
 	)
 }
 
-/**
- * Read a secret from the environment (escape hatch / CI path) OR, failing that, the hidden prompt. If
- * `process.env[envName]` is set, its trimmed value is used and we log ONLY that the env var was the
- * source (never the value) — so an operator can pre-set e.g. `CLOUDFLARE_API_TOKEN=… bunx …` and
- * skip the interactive capture entirely (useful when the hidden prompt misbehaves on a given terminal).
- * Otherwise it falls back to `secret()`. The result is always trimmed.
- */
-export async function secretOrEnv(envName: string, question: string): Promise<string> {
-	const fromEnv = process.env[envName]
-	if (fromEnv !== undefined && fromEnv.trim() !== '') {
-		info(`Using ${envName} from the environment (not prompting).`)
-		return fromEnv.trim()
-	}
-	return (await secret(question)).trim()
-}
-
-/** A yes/no confirmation. Defaults to `defaultYes` on an empty answer. */
-export async function confirm(question: string, defaultYes = false): Promise<boolean> {
-	const hint = defaultYes ? 'Y/n' : 'y/N'
-	const answer = stripTerminalCruft(await ask(`${question} [${hint}]: `)).trim().toLowerCase()
-	if (answer === '') {
-		return defaultYes
-	}
-	return answer === 'y' || answer === 'yes'
-}
-
-/**
- * Run an async action that VALIDATES input (verify a token, resolve a path). On a thrown error, show
- * the message and re-ask — so a typo'd or rejected value re-prompts in place instead of crashing the
- * whole CLI and losing every value already entered. Declining the retry re-throws, so the caller's
- * top-level handler still aborts cleanly. The `action` must itself re-read its inputs (do the
- * `secret()`/`text()` prompt INSIDE it) so a retry actually asks again.
- */
-export async function retry<T>(label: string, action: () => Promise<T>): Promise<T> {
-	for (;;) {
-		try {
-			return await action()
-		} catch (error) {
-			fail(error instanceof Error ? error.message : String(error))
-			if (!(await confirm(`${label} — try again?`, true))) {
-				throw error instanceof Error ? error : new Error(String(error))
-			}
-		}
-	}
-}
-
-/**
- * A single-choice menu. Prints the numbered options and returns the chosen value. Re-asks on an
- * out-of-range answer. With exactly one option it returns it without prompting.
- */
-export async function select<T>(question: string, options: { label: string; value: T }[]): Promise<T> {
-	if (options.length === 0) {
-		throw new Error('select(): no options to choose from')
-	}
-	const only = options[0]
-	if (options.length === 1 && only !== undefined) {
-		return only.value
-	}
-	console.log(question)
-	options.forEach((opt, i) => {
-		console.log(`    ${i + 1}) ${opt.label}`)
-	})
-	for (;;) {
-		const answer = stripTerminalCruft(await ask('    choose [1]: ')).trim()
-		const index = answer === '' ? 0 : Number.parseInt(answer, 10) - 1
-		const chosen = options[index]
-		if (chosen !== undefined) {
-			return chosen.value
-		}
-		console.log(`    (enter a number between 1 and ${options.length})`)
-	}
-}
-
-/** One command's reader over a stdin nobody is typing at. */
-export interface PipedPrompt {
-	/**
-	 * Write `query`, then take the next line — from what is already buffered, or from what arrives.
-	 * `label` names the question in a failure; `secret()` needs it because its own query is empty.
-	 */
-	ask(query: string, label?: string): Promise<string>
-}
-
-/**
- * A reader that OWNS the stream for the whole command, so several answers piped at once survive.
- *
- * The interface stays open, and every line it emits is queued whether or not a question is waiting for
- * it — that queue is the fix. It idles paused between questions so a finished command still exits, and
- * a stream that ends or faults raises instead of hanging forever on a question nothing will answer.
- *
- * Exported for tests, which drive it over an in-memory stream; the CLI has exactly one, over stdin.
- */
-export const pipedPrompt = (input: Readable, output: Writable): PipedPrompt => {
-	const rl = createInterface({ input, output, terminal: false })
-	const buffered: string[] = []
-	let waiting: (() => void) | undefined
-	let delivered: string | undefined
-	let ended = false
-	let failure: Error | undefined
-	const settle = (line: string | undefined): void => {
-		const pending = waiting
-		waiting = undefined
-		delivered = line
-		pending?.()
-	}
-	rl.on('line', (line: string) => {
-		if (waiting === undefined) {
-			buffered.push(line)
-			return
-		}
-		rl.pause()
-		settle(line)
-	})
-	rl.on('close', () => {
-		ended = true
-		settle(undefined)
-	})
-	// A read fault (EIO on a closed pty, a broken pipe) settles the pending question too. Without this
-	// the promise nothing will ever resolve is the whole command's last act. BOTH objects are listened
-	// to: readline re-emits the input's error, and an `error` nobody listens for on the interface is an
-	// uncaught exception rather than a failed prompt.
-	const faulted = (error: Error): void => {
-		if (failure !== undefined) {
-			return
-		}
-		ended = true
-		failure = new Error(`stdin could not be read: ${error.message}`)
-		settle(undefined)
-	}
-	rl.on('error', faulted)
-	input.on('error', faulted)
-	return {
-		ask: async (query: string, label?: string): Promise<string> => {
-			const named = label ?? query
-			const ready = buffered.shift()
-			if (ready !== undefined) {
-				output.write(query)
-				// Nothing echoes an answer that came off a pipe, so close the line here: a scripted run's
-				// transcript reads one question per line, like the terminal one it stands in for.
-				output.write('\n')
-				return ready
-			}
-			if (ended) {
-				throw failure ?? unanswered(named)
-			}
-			if (waiting !== undefined) {
-				// One stream, one queue, one reader: two overlapping questions would race for the same line.
-				throw new Error('pipedPrompt: a question is already waiting')
-			}
-			rl.setPrompt(query)
-			rl.prompt()
-			await new Promise<void>((resolve) => {
-				waiting = resolve
-			})
-			const line = delivered
-			delivered = undefined
-			if (line === undefined) {
-				throw failure ?? unanswered(named)
-			}
-			output.write('\n')
-			return line
-		},
-	}
-}
-
-const unanswered = (label: string): Error => {
-	const prompt = label.trim().replace(/:$/, '')
-	return new Error(
-		`stdin ended before ${prompt === '' ? 'a prompt' : `\`${prompt}\``} was answered — a piped run must supply one line per question`,
-	)
-}
-
-/** The one piped reader this command has. Created on the first question, never closed by hand. */
-let piped: PipedPrompt | undefined
-
-/** Ask one question, on whichever stdin this command was given. `label` names it in a failure. */
-async function ask(query: string, label?: string): Promise<string> {
-	if (process.stdin.isTTY === true) {
-		const rl: Interface = createInterface({ input: process.stdin, output: process.stdout, terminal: true })
-		try {
-			return await rl.question(query)
-		} finally {
-			rl.close()
-		}
+async function ask(query: string): Promise<string> {
+	if (process.stdin.isTTY !== true) {
+		throw new Error('a confirmation needs a terminal; pass --yes to answer every confirmation unattended')
 	}
-	piped ??= pipedPrompt(process.stdin, process.stdout)
-	return piped.ask(query, label)
-}
-
-/**
- * Temporarily replace `process.stdout.write` so nothing readline echoes during a secret read reaches
- * the terminal. Returns a `restore()` that puts the original back. We only mute stdout (where the
- * echo goes); stderr is untouched so a crash still surfaces.
- */
-function muteOutput(): { restore: () => void } {
-	const original = process.stdout.write.bind(process.stdout)
-	// Swallow everything written while muted. Typed characters and the echoed value go nowhere.
-	const muted: typeof process.stdout.write = () => true
-	process.stdout.write = muted
-	return {
-		restore: () => {
-			process.stdout.write = original
-		},
+	const rl = createInterface({ input: process.stdin, output: process.stdout, terminal: true })
+	try {
+		return await rl.question(query)
+	} finally {
+		rl.close()
 	}
 }

package/src/shell.ts

@@ -22,9 +22,7 @@ export interface ShellStep {
  * What a streaming child gets on stdin.
  *
  * A TTY child may INHERIT it — `git` and `gh` prompt on their own, and a terminal is shared by turns.
- * A piped stdin may not: `prompt.ts` gives one reader the whole stream for the command's life, and a
- * child inheriting it between two questions consumes the answers nobody has read yet, so the next
- * prompt dies on a line the child ate. `capture` has always used `'ignore'` for the same reason.
+ * Without a terminal nobody can answer a child's question, so it gets none and fails instead of waiting.
  */
 export const childStdin = (step: ShellStep, isTty: boolean = process.stdin.isTTY === true): Uint8Array | 'inherit' | 'ignore' =>
 	step.stdin !== undefined ? new TextEncoder().encode(step.stdin) : isTty ? 'inherit' : 'ignore'