@wbce/projen-d9 0.0.28 → 0.1.0

package/node_modules/@types/node/repl.d.ts

@@ -1,8 +1,17 @@
-declare module 'repl' {
-    import { Interface, Completer, AsyncCompleter } from 'readline';
-    import { Context } from 'vm';
-    import { InspectOptions } from 'util';
-
+/**
+ * The `node:repl` module provides a Read-Eval-Print-Loop (REPL) implementation
+ * that is available both as a standalone program or includible in other
+ * applications. It can be accessed using:
+ *
+ * ```js
+ * import repl from 'node:repl';
+ * ```
+ * @see [source](https://github.com/nodejs/node/blob/v22.x/lib/repl.js)
+ */
+declare module "repl" {
+    import { AsyncCompleter, Completer, Interface } from "node:readline";
+    import { Context } from "node:vm";
+    import { InspectOptions } from "node:util";
     interface ReplOptions {
         /**
          * The input prompt to display.
@@ -28,45 +37,48 @@ declare module 'repl' {
         terminal?: boolean | undefined;
         /**
          * The function to be used when evaluating each given line of input.
-         * Default: an async wrapper for the JavaScript `eval()` function. An `eval` function can
+         * **Default:** an async wrapper for the JavaScript `eval()` function. An `eval` function can
          * error with `repl.Recoverable` to indicate the input was incomplete and prompt for
-         * additional lines.
-         *
-         * @see https://nodejs.org/dist/latest-v10.x/docs/api/repl.html#repl_default_evaluation
-         * @see https://nodejs.org/dist/latest-v10.x/docs/api/repl.html#repl_custom_evaluation_functions
+         * additional lines. See the [custom evaluation functions](https://nodejs.org/dist/latest-v22.x/docs/api/repl.html#custom-evaluation-functions)
+         * section for more details.
          */
         eval?: REPLEval | undefined;
+        /**
+         * Defines if the repl prints output previews or not.
+         * @default `true` Always `false` in case `terminal` is falsy.
+         */
+        preview?: boolean | undefined;
         /**
          * If `true`, specifies that the default `writer` function should include ANSI color
          * styling to REPL output. If a custom `writer` function is provided then this has no
          * effect.
-         * Default: the REPL instance's `terminal` value.
+         * @default the REPL instance's `terminal` value
          */
         useColors?: boolean | undefined;
         /**
          * If `true`, specifies that the default evaluation function will use the JavaScript
          * `global` as the context as opposed to creating a new separate context for the REPL
          * instance. The node CLI REPL sets this value to `true`.
-         * Default: `false`.
+         * @default false
          */
         useGlobal?: boolean | undefined;
         /**
          * If `true`, specifies that the default writer will not output the return value of a
          * command if it evaluates to `undefined`.
-         * Default: `false`.
+         * @default false
          */
         ignoreUndefined?: boolean | undefined;
         /**
          * The function to invoke to format the output of each command before writing to `output`.
-         * Default: a wrapper for `util.inspect`.
+         * @default a wrapper for `util.inspect`
          *
-         * @see https://nodejs.org/dist/latest-v10.x/docs/api/repl.html#repl_customizing_repl_output
+         * @see https://nodejs.org/dist/latest-v22.x/docs/api/repl.html#repl_customizing_repl_output
          */
         writer?: REPLWriter | undefined;
         /**
          * An optional function used for custom Tab auto completion.
          *
-         * @see https://nodejs.org/dist/latest-v11.x/docs/api/readline.html#readline_use_of_the_completer_function
+         * @see https://nodejs.org/dist/latest-v22.x/docs/api/readline.html#readline_use_of_the_completer_function
          */
         completer?: Completer | AsyncCompleter | undefined;
         /**
@@ -81,22 +93,26 @@ declare module 'repl' {
         /**
          * Stop evaluating the current piece of code when `SIGINT` is received, i.e. `Ctrl+C` is
          * pressed. This cannot be used together with a custom `eval` function.
-         * Default: `false`.
+         * @default false
          */
         breakEvalOnSigint?: boolean | undefined;
     }
-
-    type REPLEval = (this: REPLServer, evalCmd: string, context: Context, file: string, cb: (err: Error | null, result: any) => void) => void;
+    type REPLEval = (
+        this: REPLServer,
+        evalCmd: string,
+        context: Context,
+        file: string,
+        cb: (err: Error | null, result: any) => void,
+    ) => void;
     type REPLWriter = (this: REPLServer, obj: any) => string;
-
     /**
      * This is the default "writer" value, if none is passed in the REPL options,
      * and it can be overridden by custom print functions.
      */
-    const writer: REPLWriter & { options: InspectOptions };
-
+    const writer: REPLWriter & {
+        options: InspectOptions;
+    };
     type REPLCommandAction = (this: REPLServer, text: string) => void;
-
     interface REPLCommand {
         /**
          * Help text to be displayed when `.help` is entered.
@@ -107,22 +123,19 @@ declare module 'repl' {
          */
         action: REPLCommandAction;
     }
-
     /**
-     * Provides a customizable Read-Eval-Print-Loop (REPL).
-     *
-     * Instances of `repl.REPLServer` will accept individual lines of user input, evaluate those
-     * according to a user-defined evaluation function, then output the result. Input and output
-     * may be from `stdin` and `stdout`, respectively, or may be connected to any Node.js `stream`.
+     * Instances of `repl.REPLServer` are created using the {@link start} method
+     * or directly using the JavaScript `new` keyword.
      *
-     * Instances of `repl.REPLServer` support automatic completion of inputs, simplistic Emacs-style
-     * line editing, multi-line inputs, ANSI-styled output, saving and restoring current REPL session
-     * state, error recovery, and customizable evaluation functions.
+     * ```js
+     * import repl from 'node:repl';
      *
-     * Instances of `repl.REPLServer` are created using the `repl.start()` method and _should not_
-     * be created directly using the JavaScript `new` keyword.
+     * const options = { useColors: true };
      *
-     * @see https://nodejs.org/dist/latest-v10.x/docs/api/repl.html#repl_repl
+     * const firstInstance = repl.start(options);
+     * const secondInstance = new repl.REPLServer(options);
+     * ```
+     * @since v0.1.91
      */
     class REPLServer extends Interface {
         /**
@@ -131,11 +144,11 @@ declare module 'repl' {
          */
         readonly context: Context;
         /**
-         * Outdated alias for `input`.
+         * @deprecated since v14.3.0 - Use `input` instead.
          */
         readonly inputStream: NodeJS.ReadableStream;
         /**
-         * Outdated alias for `output`.
+         * @deprecated since v14.3.0 - Use `output` instead.
          */
         readonly outputStream: NodeJS.WritableStream;
         /**
@@ -149,37 +162,37 @@ declare module 'repl' {
         /**
          * The commands registered via `replServer.defineCommand()`.
          */
-        readonly commands: { readonly [name: string]: REPLCommand | undefined };
+        readonly commands: NodeJS.ReadOnlyDict<REPLCommand>;
         /**
          * A value indicating whether the REPL is currently in "editor mode".
          *
-         * @see https://nodejs.org/dist/latest-v10.x/docs/api/repl.html#repl_commands_and_special_keys
+         * @see https://nodejs.org/dist/latest-v22.x/docs/api/repl.html#repl_commands_and_special_keys
          */
         readonly editorMode: boolean;
         /**
          * A value indicating whether the `_` variable has been assigned.
          *
-         * @see https://nodejs.org/dist/latest-v10.x/docs/api/repl.html#repl_assignment_of_the_underscore_variable
+         * @see https://nodejs.org/dist/latest-v22.x/docs/api/repl.html#repl_assignment_of_the_underscore_variable
          */
         readonly underscoreAssigned: boolean;
         /**
          * The last evaluation result from the REPL (assigned to the `_` variable inside of the REPL).
          *
-         * @see https://nodejs.org/dist/latest-v10.x/docs/api/repl.html#repl_assignment_of_the_underscore_variable
+         * @see https://nodejs.org/dist/latest-v22.x/docs/api/repl.html#repl_assignment_of_the_underscore_variable
          */
         readonly last: any;
         /**
          * A value indicating whether the `_error` variable has been assigned.
          *
          * @since v9.8.0
-         * @see https://nodejs.org/dist/latest-v10.x/docs/api/repl.html#repl_assignment_of_the_underscore_variable
+         * @see https://nodejs.org/dist/latest-v22.x/docs/api/repl.html#repl_assignment_of_the_underscore_variable
          */
         readonly underscoreErrAssigned: boolean;
         /**
          * The last error raised inside the REPL (assigned to the `_error` variable inside of the REPL).
          *
          * @since v9.8.0
-         * @see https://nodejs.org/dist/latest-v10.x/docs/api/repl.html#repl_assignment_of_the_underscore_variable
+         * @see https://nodejs.org/dist/latest-v22.x/docs/api/repl.html#repl_assignment_of_the_underscore_variable
          */
         readonly lastError: any;
         /**
@@ -223,7 +236,6 @@ declare module 'repl' {
          *    prefacing every repl statement with `'use strict'`.
          */
         readonly replMode: typeof REPL_MODE_SLOPPY | typeof REPL_MODE_STRICT;
-
         /**
          * NOTE: According to the documentation:
          *
@@ -232,52 +244,79 @@ declare module 'repl' {
          *
          * `REPLServer` cannot be subclassed due to implementation specifics in NodeJS.
          *
-         * @see https://nodejs.org/dist/latest-v10.x/docs/api/repl.html#repl_class_replserver
+         * @see https://nodejs.org/dist/latest-v22.x/docs/api/repl.html#repl_class_replserver
          */
         private constructor();
-
         /**
-         * Used to add new `.`-prefixed commands to the REPL instance. Such commands are invoked
-         * by typing a `.` followed by the `keyword`.
+         * The `replServer.defineCommand()` method is used to add new `.`\-prefixed commands
+         * to the REPL instance. Such commands are invoked by typing a `.` followed by the `keyword`. The `cmd` is either a `Function` or an `Object` with the following
+         * properties:
+         *
+         * The following example shows two new commands added to the REPL instance:
+         *
+         * ```js
+         * import repl from 'node:repl';
+         *
+         * const replServer = repl.start({ prompt: '> ' });
+         * replServer.defineCommand('sayhello', {
+         *   help: 'Say hello',
+         *   action(name) {
+         *     this.clearBufferedCommand();
+         *     console.log(`Hello, ${name}!`);
+         *     this.displayPrompt();
+         *   },
+         * });
+         * replServer.defineCommand('saybye', function saybye() {
+         *   console.log('Goodbye!');
+         *   this.close();
+         * });
+         * ```
          *
+         * The new commands can then be used from within the REPL instance:
+         *
+         * ```console
+         * > .sayhello Node.js User
+         * Hello, Node.js User!
+         * > .saybye
+         * Goodbye!
+         * ```
+         * @since v0.3.0
          * @param keyword The command keyword (_without_ a leading `.` character).
          * @param cmd The function to invoke when the command is processed.
-         *
-         * @see https://nodejs.org/dist/latest-v10.x/docs/api/repl.html#repl_replserver_definecommand_keyword_cmd
          */
         defineCommand(keyword: string, cmd: REPLCommandAction | REPLCommand): void;
         /**
-         * Readies the REPL instance for input from the user, printing the configured `prompt` to a
-         * new line in the `output` and resuming the `input` to accept new input.
+         * The `replServer.displayPrompt()` method readies the REPL instance for input
+         * from the user, printing the configured `prompt` to a new line in the `output` and resuming the `input` to accept new input.
          *
-         * When multi-line input is being entered, an ellipsis is printed rather than the 'prompt'.
+         * When multi-line input is being entered, an ellipsis is printed rather than the
+         * 'prompt'.
          *
-         * This method is primarily intended to be called from within the action function for
-         * commands registered using the `replServer.defineCommand()` method.
+         * When `preserveCursor` is `true`, the cursor placement will not be reset to `0`.
          *
-         * @param preserveCursor When `true`, the cursor placement will not be reset to `0`.
+         * The `replServer.displayPrompt` method is primarily intended to be called from
+         * within the action function for commands registered using the `replServer.defineCommand()` method.
+         * @since v0.1.91
          */
         displayPrompt(preserveCursor?: boolean): void;
         /**
-         * Clears any command that has been buffered but not yet executed.
-         *
-         * This method is primarily intended to be called from within the action function for
-         * commands registered using the `replServer.defineCommand()` method.
-         *
+         * The `replServer.clearBufferedCommand()` method clears any command that has been
+         * buffered but not yet executed. This method is primarily intended to be
+         * called from within the action function for commands registered using the `replServer.defineCommand()` method.
          * @since v9.0.0
          */
         clearBufferedCommand(): void;
-
         /**
          * Initializes a history log file for the REPL instance. When executing the
-         * Node.js binary and using the command line REPL, a history file is initialized
+         * Node.js binary and using the command-line REPL, a history file is initialized
          * by default. However, this is not the case when creating a REPL
          * programmatically. Use this method to initialize a history log file when working
          * with REPL instances programmatically.
-         * @param path The path to the history file
+         * @since v11.10.0
+         * @param historyPath the path to the history file
+         * @param callback called when history writes are ready or upon error
          */
-        setupHistory(path: string, cb: (err: Error | null, repl: this) => void): void;
-
+        setupHistory(path: string, callback: (err: Error | null, repl: this) => void): void;
         /**
          * events.EventEmitter
          * 1. close - inherited from `readline.Interface`
@@ -290,7 +329,6 @@ declare module 'repl' {
          * 8. exit
          * 9. reset
          */
-
         addListener(event: string, listener: (...args: any[]) => void): this;
         addListener(event: "close", listener: () => void): this;
         addListener(event: "line", listener: (input: string) => void): this;
@@ -301,7 +339,6 @@ declare module 'repl' {
         addListener(event: "SIGTSTP", listener: () => void): this;
         addListener(event: "exit", listener: () => void): this;
         addListener(event: "reset", listener: (context: Context) => void): this;
-
         emit(event: string | symbol, ...args: any[]): boolean;
         emit(event: "close"): boolean;
         emit(event: "line", input: string): boolean;
@@ -312,7 +349,6 @@ declare module 'repl' {
         emit(event: "SIGTSTP"): boolean;
         emit(event: "exit"): boolean;
         emit(event: "reset", context: Context): boolean;
-
         on(event: string, listener: (...args: any[]) => void): this;
         on(event: "close", listener: () => void): this;
         on(event: "line", listener: (input: string) => void): this;
@@ -323,7 +359,6 @@ declare module 'repl' {
         on(event: "SIGTSTP", listener: () => void): this;
         on(event: "exit", listener: () => void): this;
         on(event: "reset", listener: (context: Context) => void): this;
-
         once(event: string, listener: (...args: any[]) => void): this;
         once(event: "close", listener: () => void): this;
         once(event: "line", listener: (input: string) => void): this;
@@ -334,7 +369,6 @@ declare module 'repl' {
         once(event: "SIGTSTP", listener: () => void): this;
         once(event: "exit", listener: () => void): this;
         once(event: "reset", listener: (context: Context) => void): this;
-
         prependListener(event: string, listener: (...args: any[]) => void): this;
         prependListener(event: "close", listener: () => void): this;
         prependListener(event: "line", listener: (input: string) => void): this;
@@ -345,7 +379,6 @@ declare module 'repl' {
         prependListener(event: "SIGTSTP", listener: () => void): this;
         prependListener(event: "exit", listener: () => void): this;
         prependListener(event: "reset", listener: (context: Context) => void): this;
-
         prependOnceListener(event: string, listener: (...args: any[]) => void): this;
         prependOnceListener(event: "close", listener: () => void): this;
         prependOnceListener(event: "line", listener: (input: string) => void): this;
@@ -357,34 +390,39 @@ declare module 'repl' {
         prependOnceListener(event: "exit", listener: () => void): this;
         prependOnceListener(event: "reset", listener: (context: Context) => void): this;
     }
-
     /**
      * A flag passed in the REPL options. Evaluates expressions in sloppy mode.
      */
-    const REPL_MODE_SLOPPY: symbol; // TODO: unique symbol
-
+    const REPL_MODE_SLOPPY: unique symbol;
     /**
      * A flag passed in the REPL options. Evaluates expressions in strict mode.
      * This is equivalent to prefacing every repl statement with `'use strict'`.
      */
-    const REPL_MODE_STRICT: symbol; // TODO: unique symbol
-
+    const REPL_MODE_STRICT: unique symbol;
     /**
-     * Creates and starts a `repl.REPLServer` instance.
+     * The `repl.start()` method creates and starts a {@link REPLServer} instance.
      *
-     * @param options The options for the `REPLServer`. If `options` is a string, then it specifies
-     * the input prompt.
+     * If `options` is a string, then it specifies the input prompt:
+     *
+     * ```js
+     * import repl from 'node:repl';
+     *
+     * // a Unix style prompt
+     * repl.start('$ ');
+     * ```
+     * @since v0.1.91
      */
     function start(options?: string | ReplOptions): REPLServer;
-
     /**
      * Indicates a recoverable error that a `REPLServer` can use to support multi-line input.
      *
-     * @see https://nodejs.org/dist/latest-v10.x/docs/api/repl.html#repl_recoverable_errors
+     * @see https://nodejs.org/dist/latest-v22.x/docs/api/repl.html#repl_recoverable_errors
      */
     class Recoverable extends SyntaxError {
         err: Error;
-
         constructor(err: Error);
     }
 }
+declare module "node:repl" {
+    export * from "repl";
+}

package/node_modules/@types/node/sea.d.ts

@@ -0,0 +1,153 @@
+/**
+ * This feature allows the distribution of a Node.js application conveniently to a
+ * system that does not have Node.js installed.
+ *
+ * Node.js supports the creation of [single executable applications](https://github.com/nodejs/single-executable) by allowing
+ * the injection of a blob prepared by Node.js, which can contain a bundled script,
+ * into the `node` binary. During start up, the program checks if anything has been
+ * injected. If the blob is found, it executes the script in the blob. Otherwise
+ * Node.js operates as it normally does.
+ *
+ * The single executable application feature currently only supports running a
+ * single embedded script using the `CommonJS` module system.
+ *
+ * Users can create a single executable application from their bundled script
+ * with the `node` binary itself and any tool which can inject resources into the
+ * binary.
+ *
+ * Here are the steps for creating a single executable application using one such
+ * tool, [postject](https://github.com/nodejs/postject):
+ *
+ * 1. Create a JavaScript file:
+ * ```bash
+ * echo 'console.log(`Hello, ${process.argv[2]}!`);' > hello.js
+ * ```
+ * 2. Create a configuration file building a blob that can be injected into the
+ * single executable application (see `Generating single executable preparation blobs` for details):
+ * ```bash
+ * echo '{ "main": "hello.js", "output": "sea-prep.blob" }' > sea-config.json
+ * ```
+ * 3. Generate the blob to be injected:
+ * ```bash
+ * node --experimental-sea-config sea-config.json
+ * ```
+ * 4. Create a copy of the `node` executable and name it according to your needs:
+ *    * On systems other than Windows:
+ * ```bash
+ * cp $(command -v node) hello
+ * ```
+ *    * On Windows:
+ * ```text
+ * node -e "require('fs').copyFileSync(process.execPath, 'hello.exe')"
+ * ```
+ * The `.exe` extension is necessary.
+ * 5. Remove the signature of the binary (macOS and Windows only):
+ *    * On macOS:
+ * ```bash
+ * codesign --remove-signature hello
+ * ```
+ *    * On Windows (optional):
+ * [signtool](https://learn.microsoft.com/en-us/windows/win32/seccrypto/signtool) can be used from the installed [Windows SDK](https://developer.microsoft.com/en-us/windows/downloads/windows-sdk/).
+ * If this step is
+ * skipped, ignore any signature-related warning from postject.
+ * ```powershell
+ * signtool remove /s hello.exe
+ * ```
+ * 6. Inject the blob into the copied binary by running `postject` with
+ * the following options:
+ *    * `hello` / `hello.exe` \- The name of the copy of the `node` executable
+ *    created in step 4.
+ *    * `NODE_SEA_BLOB` \- The name of the resource / note / section in the binary
+ *    where the contents of the blob will be stored.
+ *    * `sea-prep.blob` \- The name of the blob created in step 1.
+ *    * `--sentinel-fuse NODE_SEA_FUSE_fce680ab2cc467b6e072b8b5df1996b2` \- The [fuse](https://www.electronjs.org/docs/latest/tutorial/fuses) used by the Node.js project to detect if a file has been
+ * injected.
+ *    * `--macho-segment-name NODE_SEA` (only needed on macOS) - The name of the
+ *    segment in the binary where the contents of the blob will be
+ *    stored.
+ * To summarize, here is the required command for each platform:
+ *    * On Linux:
+ *    ```bash
+ *    npx postject hello NODE_SEA_BLOB sea-prep.blob \
+ *        --sentinel-fuse NODE_SEA_FUSE_fce680ab2cc467b6e072b8b5df1996b2
+ *    ```
+ *    * On Windows - PowerShell:
+ *    ```powershell
+ *    npx postject hello.exe NODE_SEA_BLOB sea-prep.blob `
+ *        --sentinel-fuse NODE_SEA_FUSE_fce680ab2cc467b6e072b8b5df1996b2
+ *    ```
+ *    * On Windows - Command Prompt:
+ *    ```text
+ *    npx postject hello.exe NODE_SEA_BLOB sea-prep.blob ^
+ *        --sentinel-fuse NODE_SEA_FUSE_fce680ab2cc467b6e072b8b5df1996b2
+ *    ```
+ *    * On macOS:
+ *    ```bash
+ *    npx postject hello NODE_SEA_BLOB sea-prep.blob \
+ *        --sentinel-fuse NODE_SEA_FUSE_fce680ab2cc467b6e072b8b5df1996b2 \
+ *        --macho-segment-name NODE_SEA
+ *    ```
+ * 7. Sign the binary (macOS and Windows only):
+ *    * On macOS:
+ * ```bash
+ * codesign --sign - hello
+ * ```
+ *    * On Windows (optional):
+ * A certificate needs to be present for this to work. However, the unsigned
+ * binary would still be runnable.
+ * ```powershell
+ * signtool sign /fd SHA256 hello.exe
+ * ```
+ * 8. Run the binary:
+ *    * On systems other than Windows
+ * ```console
+ * $ ./hello world
+ * Hello, world!
+ * ```
+ *    * On Windows
+ * ```console
+ * $ .\hello.exe world
+ * Hello, world!
+ * ```
+ * @since v19.7.0, v18.16.0
+ * @experimental
+ * @see [source](https://github.com/nodejs/node/blob/v22.x/src/node_sea.cc)
+ */
+declare module "node:sea" {
+    type AssetKey = string;
+    /**
+     * @since v20.12.0
+     * @return Whether this script is running inside a single-executable application.
+     */
+    function isSea(): boolean;
+    /**
+     * This method can be used to retrieve the assets configured to be bundled into the
+     * single-executable application at build time.
+     * An error is thrown when no matching asset can be found.
+     * @since v20.12.0
+     */
+    function getAsset(key: AssetKey): ArrayBuffer;
+    function getAsset(key: AssetKey, encoding: string): string;
+    /**
+     * Similar to `sea.getAsset()`, but returns the result in a [`Blob`](https://developer.mozilla.org/en-US/docs/Web/API/Blob).
+     * An error is thrown when no matching asset can be found.
+     * @since v20.12.0
+     */
+    function getAssetAsBlob(key: AssetKey, options?: {
+        type: string;
+    }): Blob;
+    /**
+     * This method can be used to retrieve the assets configured to be bundled into the
+     * single-executable application at build time.
+     * An error is thrown when no matching asset can be found.
+     *
+     * Unlike `sea.getRawAsset()` or `sea.getAssetAsBlob()`, this method does not
+     * return a copy. Instead, it returns the raw asset bundled inside the executable.
+     *
+     * For now, users should avoid writing to the returned array buffer. If the
+     * injected section is not marked as writable or not aligned properly,
+     * writes to the returned array buffer is likely to result in a crash.
+     * @since v20.12.0
+     */
+    function getRawAsset(key: AssetKey): ArrayBuffer;
+}