create-paratix 0.10.0 → 0.12.2

package/README.md

@@ -44,8 +44,9 @@ cd my-server
 Run the bootstrap flow:
 
 ```bash
+pnpm apply:first-run:dry
+pnpm apply:first-run
 pnpm apply:dry
-pnpm apply --first-run
 pnpm apply
 ```
 
@@ -75,12 +76,13 @@ The scaffolded project includes:
 The generated project keeps this explicit:
 
 - `paratix apply ... --first-run` stays on port `22`, completes the hardened bootstrap stage, and stops intentionally at the first-run checkpoint
-- later runs use the hardened path, usually on port `2222`, with strict host-key checking again
+- first and later runs use strict host-key checking; pin `expectedHostFingerprint`/`expectedHostPublicKey` or pre-populate `known_hosts` before connecting
+- later runs use the hardened path, usually on port `2222`, with the same strict host-key checking
 
 When you scaffold interactively, the CLI can also:
 
 - select an admin public key from `~/.ssh`
-- pin the current host key from SSH port `22` as `expectedHostFingerprint`
+- scan the current host key from SSH port `22` and pin it as `expectedHostFingerprint` after you verify it out of band
 
 ## Non-Interactive Usage
 

package/dist/index.d.ts

@@ -1,8 +1,3 @@
-type PackageManager = {
-    command: string;
-    name: string;
-};
-
 type InitialUserConfig = {
     kind: "admin";
     user: string;
@@ -10,6 +5,83 @@ type InitialUserConfig = {
     kind: "root";
 };
 
+type PackageManagerCommand = {
+    args: readonly string[];
+    executable: string;
+};
+type PackageManager = {
+    command: PackageManagerCommand;
+    name: string;
+};
+
+type ExitWithMessage = (message: string) => never;
+declare function normalizeInitialUserName(name: string): string;
+declare function isValidInitialUserName(name: string): boolean;
+declare function normalizeHost(value: string): string;
+declare function isValidHost(value: string): boolean;
+declare function isValidExpectedHostFingerprint(value: string): boolean;
+type ParsedCliArguments = {
+    adminPublicKey: string | undefined;
+    adminPublicKeyFile: string | undefined;
+    expectedHostFingerprint: string | undefined;
+    host: string | undefined;
+    initialUser: string | undefined;
+    projectName: string | undefined;
+};
+declare function parseCliArguments$1(argv: string[], exitWithMessage: ExitWithMessage): ParsedCliArguments;
+
+/**
+ * R-0000189: dedicated error type that signals a deterministic CLI exit. A
+ * synchronous `process.exit` call from inside an interactive prompt skips
+ * any in-flight cleanup (raw-mode reset, cursor visibility), which leaves
+ * the operator's terminal unusable. Throwing instead lets `main()` (or any
+ * other top-level driver) run cleanup and assign `process.exitCode` before
+ * the process exits naturally.
+ *
+ * Lives in its own module so low-level helpers (e.g. scaffoldConfig prompts)
+ * can reuse it without forming a circular dependency with cliValidation.
+ */
+declare class CliExitError extends Error {
+    readonly cliMessage: string;
+    readonly exitCode: number;
+    readonly reported: boolean;
+    constructor(message: string, exitCode?: number, options?: {
+        reported?: boolean;
+    });
+}
+
+/**
+ * R-0000189: shared cleanup hook so `main()` can reset interactive terminal
+ * state (cursor visibility, raw mode) after a CliExitError was thrown from
+ * an in-flight prompt. Kept as a small no-op-friendly default so the unit
+ * tests can substitute their own implementation.
+ */
+declare function restoreInteractiveTerminal(): void;
+/**
+ * R-0000189: top-level handler that converts a thrown CliExitError into the
+ * intended exit code while running interactive cleanup. Other thrown errors
+ * are still surfaced as a generic CLI error. CliExitError instances thrown
+ * directly from prompt paths have not necessarily emitted their user-visible
+ * message yet, so this handler prints only unreported CliExitError messages.
+ *
+ * @param error - The error caught from the CLI pipeline.
+ */
+declare function handleCliExit(error: unknown): void;
+declare function parseCliArguments(argv: string[]): ReturnType<typeof parseCliArguments$1>;
+declare function parseInitialUserConfig(value: string): InitialUserConfig;
+declare function validateHost(value: string): string;
+declare function validateExpectedHostFingerprint(value: string): string;
+declare function resolveCliOrPromptHost(host: string | undefined, prompt?: () => Promise<string>): Promise<string>;
+
+declare function deriveParatixDependencyRange(): string;
+
+declare function isDirectExecution(moduleUrl: string, argv1: null | string | undefined): boolean;
+
+type HostFingerprintScanResult = {
+    algorithm: string;
+    fingerprint: string;
+};
+
 type SelectOption<TValue extends string> = {
     description: string;
     label: string;
@@ -18,19 +90,23 @@ type SelectOption<TValue extends string> = {
 type SelectFunction<TValue extends string> = (prompt: string, options: Array<SelectOption<TValue>>) => Promise<TValue>;
 
 type PromptFunction = (question: string) => Promise<string>;
+type InitialUserPromptSession = {
+    ask: PromptFunction;
+    chooseInitialUser: SelectFunction<"admin" | "root">;
+    closePrompt: () => void;
+    closeSelect: () => void;
+};
 declare function promptForHost(prompt?: PromptFunction, closePrompt?: () => void): Promise<string>;
-declare function promptForInitialUserConfig(prompt?: PromptFunction, select?: SelectFunction<"admin" | "root">): Promise<InitialUserConfig>;
+declare function promptForInitialUserConfig(prompt?: PromptFunction, select?: SelectFunction<"admin" | "root">, createSession?: (prompt?: PromptFunction) => InitialUserPromptSession): Promise<InitialUserConfig>;
 declare function promptForAdminPublicKey(select?: SelectFunction<string>, publicKeys?: Array<{
     key: string;
     label: string;
     path: string;
-}>): Promise<string | undefined>;
-declare function promptForHostFingerprint(host: string, select?: SelectFunction<"placeholder" | "scan">, scanner?: (host: string) => Promise<string>): Promise<string | undefined>;
-
-declare function normalizeInitialUserName(name: string): string;
-declare function isValidInitialUserName(name: string): boolean;
-declare function normalizeHost(value: string): string;
-declare function isValidHost(value: string): boolean;
+}>, options?: {
+    allowPlaceholder?: boolean;
+}): Promise<string | undefined>;
+type HostFingerprintSelectValue = "discard" | "pin" | "placeholder" | "scan";
+declare function promptForHostFingerprint(host: string, select?: SelectFunction<HostFingerprintSelectValue>, scanner?: (host: string) => Promise<HostFingerprintScanResult>): Promise<string | undefined>;
 
 type ScaffoldOptions = {
     adminPublicKey?: string;
@@ -42,16 +118,6 @@ type ScaffoldOptions = {
 declare function writeProjectFiles(projectDirectory: string, options?: ScaffoldOptions): void;
 declare function isValidProjectName(name: string): boolean;
 declare function normalizeProjectName(name: string): string;
-declare function parseCliArguments(argv: string[]): {
-    adminPublicKey: string | undefined;
-    adminPublicKeyFile: string | undefined;
-    host: string | undefined;
-    initialUser: string | undefined;
-    projectName: string | undefined;
-};
-declare function parseInitialUserConfig(value: string): InitialUserConfig;
-declare function validateHost(value: string): string;
 declare function scaffoldProject(projectName: string, pm: PackageManager, options?: ScaffoldOptions): boolean;
-declare function isDirectExecution(moduleUrl: string, argv1: null | string | undefined): boolean;
 
-export { type InitialUserConfig, isDirectExecution, isValidHost, isValidInitialUserName, isValidProjectName, normalizeHost, normalizeInitialUserName, normalizeProjectName, parseCliArguments, parseInitialUserConfig, promptForAdminPublicKey, promptForHost, promptForHostFingerprint, promptForInitialUserConfig, scaffoldProject, validateHost, writeProjectFiles };
+export { CliExitError, type InitialUserConfig, type ScaffoldOptions, deriveParatixDependencyRange, handleCliExit, isDirectExecution, isValidExpectedHostFingerprint, isValidHost, isValidInitialUserName, isValidProjectName, normalizeHost, normalizeInitialUserName, normalizeProjectName, parseCliArguments, parseInitialUserConfig, promptForAdminPublicKey, promptForHost, promptForHostFingerprint, promptForInitialUserConfig, resolveCliOrPromptHost, restoreInteractiveTerminal, scaffoldProject, validateExpectedHostFingerprint, validateHost, writeProjectFiles };