@augment-vir/node 30.0.0

package/dist/docker/containers/run-container.mock.d.ts

@@ -0,0 +1,2 @@
+import { RunDockerContainerParams } from './run-container.js';
+export declare function runMockLongLivingContainer(containerName: string, args?: Partial<RunDockerContainerParams>): Promise<void>;

package/dist/docker/containers/run-container.mock.js

@@ -0,0 +1,14 @@
+import { docker } from '../../augments/docker.js';
+export async function runMockLongLivingContainer(containerName, args = {}) {
+    await docker.container.run({
+        containerName: containerName,
+        detach: true,
+        imageName: 'alpine:3.20.2',
+        dockerFlags: [
+            '-i',
+            '-t',
+        ],
+        command: 'sh',
+        ...args,
+    });
+}

package/dist/docker/containers/try-or-kill-container.d.ts

@@ -0,0 +1,6 @@
+import type { MaybePromise } from '@augment-vir/core';
+/**
+ * Runs a callback (which presumably runs a command within the given `containerName`) and kills the
+ * given `containerName` container if the callback fails.
+ */
+export declare function tryOrKillContainer<T>(containerNameOrId: string, callback: (containerNameOrId: string) => MaybePromise<T>): Promise<Awaited<T>>;

package/dist/docker/containers/try-or-kill-container.js

@@ -0,0 +1,14 @@
+import { killContainer } from './kill-container.js';
+/**
+ * Runs a callback (which presumably runs a command within the given `containerName`) and kills the
+ * given `containerName` container if the callback fails.
+ */
+export async function tryOrKillContainer(containerNameOrId, callback) {
+    try {
+        return await callback(containerNameOrId);
+    }
+    catch (error) {
+        await killContainer(containerNameOrId);
+        throw error;
+    }
+}

package/dist/docker/docker-image.d.ts

@@ -0,0 +1,9 @@
+export declare function updateImage(
+/** @example 'alpine:3.20.2' */
+imageName: string): Promise<void>;
+export declare function isImageInLocalRegistry(
+/** @example 'alpine:3.20.2' */
+imageName: string): Promise<boolean>;
+export declare function removeImageFromLocalRegistry(
+/** @example 'alpine:3.20.2' */
+imageName: string): Promise<void>;

package/dist/docker/docker-image.js

@@ -0,0 +1,36 @@
+import { ensureError } from '@augment-vir/core';
+import { runShellCommand } from '../augments/shell.js';
+export async function updateImage(
+/** @example 'alpine:3.20.2' */
+imageName) {
+    if (await isImageInLocalRegistry(imageName)) {
+        /** If image already exists then we don't need to update it. */
+        return;
+    }
+    await runShellCommand(`docker pull '${imageName}'`, {
+        rejectOnError: true,
+    });
+}
+export async function isImageInLocalRegistry(
+/** @example 'alpine:3.20.2' */
+imageName) {
+    const output = await runShellCommand(`docker inspect '${imageName}'`);
+    return output.exitCode === 0;
+}
+export async function removeImageFromLocalRegistry(
+/** @example 'alpine:3.20.2' */
+imageName) {
+    try {
+        await runShellCommand(`docker image rm '${imageName}'`, { rejectOnError: true });
+    }
+    catch (caught) {
+        const error = ensureError(caught);
+        if (error.message.includes('No such image:')) {
+            /** Ignore the case where the image has already been deleted. */
+            return;
+        }
+        /** An edge case that I don't know how to intentionally trigger. */
+        /* node:coverage ignore next 2 */
+        throw error;
+    }
+}

package/dist/docker/docker-startup.d.ts

@@ -0,0 +1,2 @@
+export declare function isDockerRunning(): Promise<boolean>;
+export declare function startDocker(): Promise<void>;

package/dist/docker/docker-startup.js

@@ -0,0 +1,40 @@
+import { waitUntil } from '@augment-vir/assert';
+import { currentOperatingSystem, OperatingSystem } from '../augments/os/operating-system.js';
+import { runShellCommand } from '../augments/shell.js';
+export async function isDockerRunning() {
+    const output = await runShellCommand('docker info');
+    return output.exitCode === 0;
+}
+const startDockerCommands = {
+    /**
+     * Officially supported for the following distros:
+     *
+     * - [Ubuntu](https://docs.docker.com/desktop/install/ubuntu/#launch-docker-desktop)
+     * - [Debian](https://docs.docker.com/desktop/install/debian/#launch-docker-desktop)
+     * - [Fedora](https://docs.docker.com/desktop/install/fedora/#launch-docker-desktop)
+     * - [Arch](https://docs.docker.com/desktop/install/archlinux/#launch-docker-desktop)
+     */
+    [OperatingSystem.Linux]: 'systemctl --user start docker-desktop',
+    [OperatingSystem.Mac]: 'open -a Docker',
+    [OperatingSystem.Windows]: String.raw `/c/Program\ Files/Docker/Docker/Docker\ Desktop.exe`,
+};
+export async function startDocker() {
+    const command = startDockerCommands[currentOperatingSystem];
+    /** We */
+    /* node:coverage disable */
+    if (await isDockerRunning()) {
+        /** Docker is already running. Nothing to do. */
+        return;
+    }
+    await waitUntil.isTrue(async () => {
+        await runShellCommand(command, { rejectOnError: true });
+        return isDockerRunning();
+    }, {
+        interval: {
+            seconds: 1,
+        },
+        timeout: {
+            minutes: 1,
+        },
+    }, 'Failed to start Docker.');
+}

package/dist/file-paths.mock.d.ts

@@ -0,0 +1,17 @@
+export declare const monoRepoDirPath: string;
+export declare const notCommittedDirPath: string;
+export declare const nodePackageDir: string;
+export declare const testFilesDir: string;
+export declare const longRunningFilePath: string;
+export declare const longRunningFileWithStderr: string;
+export declare const workspaceQueryDir: string;
+export declare const workspaceQueryPackageJsonPath: string;
+export declare const tempWorkspaceQueryFile: string;
+export declare const recursiveFileReadDir: string;
+export declare const invalidPackageDirPath: string;
+export declare const testPrismaSchemaPath: string;
+export declare const testPrismaSchema2Path: string;
+export declare const testInvalidPrismaSchemaPath: string;
+export declare const testSqliteDbPath: string;
+export declare const generatedPrismaClientDirPath: string;
+export declare const testPrismaMigrationsDirPath: string;

package/dist/file-paths.mock.js

@@ -0,0 +1,19 @@
+import { dirname, join } from 'node:path';
+export const monoRepoDirPath = dirname(dirname(dirname(import.meta.dirname)));
+export const notCommittedDirPath = join(monoRepoDirPath, '.not-committed');
+export const nodePackageDir = dirname(import.meta.dirname);
+export const testFilesDir = join(nodePackageDir, 'test-files');
+const longRunningFileDir = join(testFilesDir, 'long-running-test-file');
+export const longRunningFilePath = join(longRunningFileDir, 'long-running-file.ts');
+export const longRunningFileWithStderr = join(longRunningFileDir, 'long-running-file-with-stderr.ts');
+export const workspaceQueryDir = join(testFilesDir, 'workspace-query');
+export const workspaceQueryPackageJsonPath = join(workspaceQueryDir, 'package.json');
+export const tempWorkspaceQueryFile = join(workspaceQueryDir, 'temp-workspace-query-output.ts');
+export const recursiveFileReadDir = join(testFilesDir, 'recursive-reading');
+export const invalidPackageDirPath = join(testFilesDir, 'invalid-package');
+export const testPrismaSchemaPath = join(testFilesDir, 'schema.prisma');
+export const testPrismaSchema2Path = join(testFilesDir, 'schema2.prisma');
+export const testInvalidPrismaSchemaPath = join(testFilesDir, 'invalid-schema.prisma');
+export const testSqliteDbPath = join(notCommittedDirPath, 'dev.db');
+export const generatedPrismaClientDirPath = join(nodePackageDir, 'node_modules', '.prisma');
+export const testPrismaMigrationsDirPath = join(testFilesDir, 'migrations');

package/dist/index.d.ts

@@ -0,0 +1,16 @@
+export * from './augments/console/question.js';
+export * from './augments/docker.js';
+export * from './augments/download.js';
+export * from './augments/fs/json.js';
+export * from './augments/fs/read-dir.js';
+export * from './augments/fs/read-file.js';
+export * from './augments/fs/symlink.js';
+export * from './augments/fs/write.js';
+export * from './augments/npm/query-workspace.js';
+export * from './augments/npm/read-package-json.js';
+export * from './augments/os/operating-system.js';
+export * from './augments/path/ancestor.js';
+export * from './augments/path/os-path.js';
+export * from './augments/path/root.js';
+export * from './augments/prisma.js';
+export * from './augments/shell.js';

package/dist/index.js

@@ -0,0 +1,16 @@
+export * from './augments/console/question.js';
+export * from './augments/docker.js';
+export * from './augments/download.js';
+export * from './augments/fs/json.js';
+export * from './augments/fs/read-dir.js';
+export * from './augments/fs/read-file.js';
+export * from './augments/fs/symlink.js';
+export * from './augments/fs/write.js';
+export * from './augments/npm/query-workspace.js';
+export * from './augments/npm/read-package-json.js';
+export * from './augments/os/operating-system.js';
+export * from './augments/path/ancestor.js';
+export * from './augments/path/os-path.js';
+export * from './augments/path/root.js';
+export * from './augments/prisma.js';
+export * from './augments/shell.js';

package/dist/prisma/prisma-client.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Runs Prisma generators included in the given Prisma schema (which usually includes the Prisma JS
+ * client). This will work even if the database doesn't exist yet.
+ */
+export declare function generatePrismaClient(schemaFilePath: string, env?: Record<string, string>): Promise<void>;
+export declare function isGeneratedPrismaClientCurrent({ jsClientOutputDir, schemaFilePath, }: {
+    schemaFilePath: string;
+    jsClientOutputDir: string;
+}): Promise<boolean>;

package/dist/prisma/prisma-client.js

@@ -0,0 +1,28 @@
+import { collapseWhiteSpace } from '@augment-vir/common';
+import { existsSync } from 'node:fs';
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { runPrismaCommand } from './run-prisma-command.js';
+/**
+ * Runs Prisma generators included in the given Prisma schema (which usually includes the Prisma JS
+ * client). This will work even if the database doesn't exist yet.
+ */
+export async function generatePrismaClient(schemaFilePath, env = {}) {
+    await runPrismaCommand({ command: 'generate' }, schemaFilePath, env);
+}
+async function areSchemasEqual(originalSchema, generatedClientSchema) {
+    if (!existsSync(originalSchema)) {
+        throw new Error(`Schema file does not exist: '${originalSchema}'`);
+    }
+    else if (!existsSync(generatedClientSchema)) {
+        return false;
+    }
+    const originalSchemaContents = String(await readFile(originalSchema));
+    const generatedClientSchemaContents = String(await readFile(generatedClientSchema));
+    return (collapseWhiteSpace(originalSchemaContents, { keepNewLines: true }) ===
+        collapseWhiteSpace(generatedClientSchemaContents, { keepNewLines: true }));
+}
+export async function isGeneratedPrismaClientCurrent({ jsClientOutputDir, schemaFilePath, }) {
+    const clientSchemaFilePath = join(jsClientOutputDir, 'schema.prisma');
+    return areSchemasEqual(schemaFilePath, clientSchemaFilePath);
+}

package/dist/prisma/prisma-database.d.ts

@@ -0,0 +1,3 @@
+export declare function getPrismaDiff(schemaFilePath: string, env?: Record<string, string>): Promise<string>;
+export declare function doesPrismaDiffExist(schemaFilePath: string, env?: Record<string, string>): Promise<boolean>;
+export declare function resetDevPrismaDatabase(schemaFilePath: string, env?: Record<string, string>): Promise<void>;

package/dist/prisma/prisma-database.js

@@ -0,0 +1,22 @@
+import { runPrismaCommand } from './run-prisma-command.js';
+export async function getPrismaDiff(schemaFilePath, env = {}) {
+    const command = [
+        'migrate',
+        'diff',
+        `--from-schema-datamodel='${schemaFilePath}'`,
+        `--to-schema-datasource='${schemaFilePath}'`,
+    ].join(' ');
+    const results = await runPrismaCommand({ command }, undefined, env);
+    if (results.stdout.trim() === 'No difference detected.') {
+        return '';
+    }
+    else {
+        return results.stdout.trim();
+    }
+}
+export async function doesPrismaDiffExist(schemaFilePath, env = {}) {
+    return !!(await getPrismaDiff(schemaFilePath, env));
+}
+export async function resetDevPrismaDatabase(schemaFilePath, env = {}) {
+    await runPrismaCommand({ command: 'migrate reset --force' }, schemaFilePath, env);
+}

package/dist/prisma/prisma-database.mock.d.ts

@@ -0,0 +1 @@
+export declare function clearTestDatabaseOutputs(): Promise<void>;

package/dist/prisma/prisma-database.mock.js

@@ -0,0 +1,7 @@
+import { rm } from 'node:fs/promises';
+import { generatedPrismaClientDirPath, notCommittedDirPath, testPrismaMigrationsDirPath, } from '../file-paths.mock.js';
+export async function clearTestDatabaseOutputs() {
+    await rm(generatedPrismaClientDirPath, { force: true, recursive: true });
+    await rm(notCommittedDirPath, { force: true, recursive: true });
+    await rm(testPrismaMigrationsDirPath, { force: true, recursive: true });
+}

package/dist/prisma/prisma-errors.d.ts

@@ -0,0 +1,12 @@
+export declare class PrismaSchemaError extends Error {
+    readonly name = "PrismaSchemaError";
+    constructor(message: string);
+}
+export declare class PrismaMigrationNeededError extends Error {
+    readonly name = "PrismaMigrationNeededError";
+    constructor(schemaFilePath: string);
+}
+export declare class PrismaResetNeededError extends Error {
+    readonly name = "PrismaResetNeededError";
+    constructor(schemaFilePath: string);
+}

package/dist/prisma/prisma-errors.js

@@ -0,0 +1,18 @@
+export class PrismaSchemaError extends Error {
+    name = 'PrismaSchemaError';
+    constructor(message) {
+        super(message);
+    }
+}
+export class PrismaMigrationNeededError extends Error {
+    name = 'PrismaMigrationNeededError';
+    constructor(schemaFilePath) {
+        super(`A new Prisma migration is needed for '${schemaFilePath}'`);
+    }
+}
+export class PrismaResetNeededError extends Error {
+    name = 'PrismaResetNeededError';
+    constructor(schemaFilePath) {
+        super(`A database reset is needed for '${schemaFilePath}'`);
+    }
+}

package/dist/prisma/prisma-migrations.d.ts

@@ -0,0 +1,17 @@
+export type PrismaMigrationStatus = {
+    totalMigrations: number;
+    unappliedMigrations: string[];
+};
+export declare function applyPrismaMigrationsToProd(schemaFilePath: string, env?: Record<string, string>): Promise<void>;
+/**
+ * @throws `PrismaMigrationNeededError` when a new migration is required so the user needs to input
+ *   a name.
+ * @throws `PrismaResetNeededError` when there's a migration mismatch with the database and it needs
+ *   to be reset.
+ */
+export declare function applyPrismaMigrationsToDev(schemaFilePath: string, env?: Record<string, string>): Promise<void>;
+export declare function getMigrationStatus(schemaFilePath: string, env?: Record<string, string>): Promise<PrismaMigrationStatus>;
+export declare function createPrismaMigration({ migrationName, createOnly, }: {
+    migrationName: string;
+    createOnly?: boolean | undefined;
+}, schemaFilePath: string, env?: Record<string, string>): Promise<void>;

package/dist/prisma/prisma-migrations.js

@@ -0,0 +1,105 @@
+import { check } from '@augment-vir/assert';
+import { log, safeMatch, toEnsuredNumber } from '@augment-vir/common';
+import terminate from 'terminate';
+import { runShellCommand } from '../augments/shell.js';
+import { PrismaMigrationNeededError, PrismaResetNeededError } from './prisma-errors.js';
+import { runPrismaCommand, verifyOutput } from './run-prisma-command.js';
+export async function applyPrismaMigrationsToProd(schemaFilePath, env = {}) {
+    await runPrismaCommand({ command: 'migrate deploy' }, schemaFilePath, env);
+}
+var DbChangeRequired;
+(function (DbChangeRequired) {
+    DbChangeRequired["MigrationNeeded"] = "migration-needed";
+    DbChangeRequired["ResetNeeded"] = "reset-needed";
+})(DbChangeRequired || (DbChangeRequired = {}));
+/**
+ * @throws `PrismaMigrationNeededError` when a new migration is required so the user needs to input
+ *   a name.
+ * @throws `PrismaResetNeededError` when there's a migration mismatch with the database and it needs
+ *   to be reset.
+ */
+export async function applyPrismaMigrationsToDev(schemaFilePath, env = {}) {
+    const command = [
+        'prisma',
+        'migrate',
+        'dev',
+        `--schema='${schemaFilePath}'`,
+    ].join(' ');
+    log.faint(`> ${command}`);
+    let dbRequirement = undefined;
+    const result = await runShellCommand(command, {
+        env: {
+            ...process.env,
+            ...env,
+        },
+        stdoutCallback(stdout, childProcess) {
+            if (stdout.includes('Enter a name for the new migration')) {
+                if (childProcess.pid) {
+                    terminate(childProcess.pid);
+                }
+                dbRequirement = DbChangeRequired.MigrationNeeded;
+            }
+        },
+        stderrCallback(stderr, childProcess) {
+            if (stderr.includes('Prisma Migrate has detected that the environment is non-interactive, which is not supported')) {
+                if (childProcess.pid) {
+                    terminate(childProcess.pid);
+                }
+                dbRequirement = DbChangeRequired.ResetNeeded;
+            }
+        },
+    });
+    if (dbRequirement === DbChangeRequired.MigrationNeeded) {
+        throw new PrismaMigrationNeededError(schemaFilePath);
+    }
+    else if (dbRequirement === DbChangeRequired.ResetNeeded) {
+        throw new PrismaResetNeededError(schemaFilePath);
+    }
+    verifyOutput(schemaFilePath, result, false);
+}
+export async function getMigrationStatus(schemaFilePath, env = {}) {
+    const output = await runPrismaCommand({
+        command: 'migrate status',
+        ignoreExitCode: true,
+    }, schemaFilePath, env);
+    const listedMigrations = {
+        totalMigrations: 0,
+        unappliedMigrations: [],
+    };
+    let foundNotAppliedMigrations = false;
+    output.stdout.split('\n').some((rawLine) => {
+        const line = rawLine.trim();
+        if (foundNotAppliedMigrations) {
+            if (line) {
+                listedMigrations.unappliedMigrations.push(line);
+            }
+            else {
+                /** We're done parsing. */
+                return true;
+            }
+        }
+        else if (line.endsWith('not yet been applied:')) {
+            foundNotAppliedMigrations = true;
+        }
+        else {
+            const [, countMatch,] = safeMatch(line, /^([\d,]+) migrations? found in/);
+            if (countMatch) {
+                listedMigrations.totalMigrations = toEnsuredNumber(countMatch);
+            }
+        }
+        /** Still need to keep parsing. */
+        return false;
+    });
+    return listedMigrations;
+}
+export async function createPrismaMigration({ migrationName, createOnly = false, }, schemaFilePath, env = {}) {
+    const command = [
+        'migrate',
+        'dev',
+        `--name='${migrationName}'`,
+        createOnly ? '--create-only' : '',
+    ]
+        .filter(check.isTruthy)
+        .join(' ');
+    await runPrismaCommand({ command }, schemaFilePath, env);
+}

package/dist/prisma/run-prisma-command.d.ts

@@ -0,0 +1,8 @@
+import { type ShellOutput } from '../augments/shell.js';
+export declare function runPrismaCommand({ command, ignoreExitCode, }: {
+    command: string;
+    ignoreExitCode?: boolean | undefined;
+}, 
+/** Set to `undefined` to omit the `--schema` flag. */
+schemaFilePath: string | undefined, env?: Record<string, string> | undefined): Promise<Readonly<ShellOutput>>;
+export declare function verifyOutput(schemaFilePath: string, shellOutput: Readonly<ShellOutput>, ignoreExitCode: boolean): Readonly<ShellOutput>;

package/dist/prisma/run-prisma-command.js

@@ -0,0 +1,48 @@
+import { log } from '@augment-vir/common';
+import { runShellCommand } from '../augments/shell.js';
+import { PrismaSchemaError } from './prisma-errors.js';
+const prismaCommandsThatSupportNoHints = [
+    'generate',
+];
+export async function runPrismaCommand({ command, ignoreExitCode = false, }, 
+/** Set to `undefined` to omit the `--schema` flag. */
+schemaFilePath, env = {}) {
+    const schemaFileArgs = schemaFilePath
+        ? [
+            '--schema',
+            schemaFilePath,
+        ]
+        : [];
+    /** Disable Prisma's in-CLI ads. */
+    const noHintsArg = prismaCommandsThatSupportNoHints.some((commandName) => command.startsWith(commandName))
+        ? '--no-hints'
+        : '';
+    const fullCommand = [
+        'prisma',
+        command,
+        ...schemaFileArgs,
+        noHintsArg,
+    ].join(' ');
+    log.faint(`> ${fullCommand}`);
+    const result = await runShellCommand(fullCommand, {
+        env: {
+            ...process.env,
+            ...env,
+        },
+    });
+    return verifyOutput(schemaFilePath || '', result, ignoreExitCode);
+}
+export function verifyOutput(schemaFilePath, shellOutput, ignoreExitCode) {
+    if (shellOutput.stderr.includes('Validation Error Count')) {
+        throw new PrismaSchemaError(`Invalid schema file at '${schemaFilePath}':\n\n${shellOutput.stderr}`);
+    }
+    else if (shellOutput.stderr.includes('does not exist at')) {
+        throw new PrismaSchemaError(`Database does not exist: ${shellOutput.stderr}`);
+    }
+    else if (shellOutput.exitCode === 0 || ignoreExitCode) {
+        return shellOutput;
+    }
+    else {
+        throw new Error(shellOutput.stdout + shellOutput.stderr);
+    }
+}

package/package.json

@@ -0,0 +1,58 @@
+{
+    "name": "@augment-vir/node",
+    "version": "30.0.0",
+    "homepage": "https://github.com/electrovir/augment-vir",
+    "bugs": {
+        "url": "https://github.com/electrovir/augment-vir/issues"
+    },
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/electrovir/augment-vir.git"
+    },
+    "license": "(MIT or CC0 1.0)",
+    "author": {
+        "name": "electrovir",
+        "url": "https://github.com/electrovir"
+    },
+    "type": "module",
+    "main": "dist/index.js",
+    "module": "dist/index.js",
+    "types": "dist/index.d.ts",
+    "scripts": {
+        "compile": "virmator compile",
+        "docs": "virmator docs",
+        "test": "virmator --no-deps test node --test-concurrency 1",
+        "test:coverage": "virmator test node coverage --test-concurrency 1",
+        "test:docs": "virmator docs check",
+        "test:update": "npm test"
+    },
+    "dependencies": {
+        "@augment-vir/assert": "^30.0.0",
+        "@augment-vir/common": "^30.0.0",
+        "@date-vir/duration": "^6.0.0",
+        "ansi-styles": "^6.2.1",
+        "terminate": "^2.8.0",
+        "type-fest": "^4.25.0",
+        "typed-event-target": "^3.4.0"
+    },
+    "devDependencies": {
+        "@augment-vir/test": "^30.0.0",
+        "@prisma/client": "^5.19.0",
+        "@types/node": "^22.5.0",
+        "@web/dev-server-esbuild": "^1.0.2",
+        "@web/test-runner": "^0.18.3",
+        "@web/test-runner-commands": "^0.9.0",
+        "@web/test-runner-playwright": "^0.11.0",
+        "@web/test-runner-visual-regression": "^0.9.0",
+        "c8": "^10.1.2",
+        "concurrently": "^8.2.2",
+        "istanbul-smart-text-reporter": "^1.1.4",
+        "prisma": "^5.19.0"
+    },
+    "engines": {
+        "node": ">=22"
+    },
+    "publishConfig": {
+        "access": "public"
+    }
+}