@hypequery/cli 1.18.1 → 1.18.3

package/dist/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAgCpC,QAAA,MAAM,OAAO,SAAgB,CAAC;AAa9B,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;;EAKpE;AAgQD,OAAO,EAAE,OAAO,EAAE,CAAC"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAgCpC,QAAA,MAAM,OAAO,SAAgB,CAAC;AAa9B,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;;EAKpE;AAmQD,OAAO,EAAE,OAAO,EAAE,CAAC"}

package/dist/cli.js

@@ -143,6 +143,9 @@ program
     .option('--tables <names>', 'Only generate for specific tables (comma-separated)')
     .option('--exclude-tables <names>', 'Exclude specific tables (comma-separated)')
     .option('--tenant-column <column>', 'Set tenantKey to this column on tables that have it (requires a trusted runtime tenant scope)')
+    .option('--force', 'Replace an existing output file when generated contents differ')
+    .option('--check', 'Exit with an error when the output file is missing or out of date')
+    .option('--diff', 'Print generated changes without writing them')
     .action(runCommand(async (options) => {
     await generateDatasetsCommand(options);
 }));

package/dist/commands/generate-datasets.d.ts

@@ -10,6 +10,9 @@ export interface GenerateDatasetsOptions {
     tables?: string;
     excludeTables?: string;
     tenantColumn?: string;
+    force?: boolean;
+    check?: boolean;
+    diff?: boolean;
 }
 export declare function generateDatasetsCommand(options?: GenerateDatasetsOptions): Promise<void>;
 //# sourceMappingURL=generate-datasets.d.ts.map

package/dist/commands/generate-datasets.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"generate-datasets.d.ts","sourceRoot":"","sources":["../../src/commands/generate-datasets.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAUH,MAAM,WAAW,uBAAuB;IACtC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAqBD,wBAAsB,uBAAuB,CAAC,OAAO,GAAE,uBAA4B,iBA8GlF"}
+{"version":3,"file":"generate-datasets.d.ts","sourceRoot":"","sources":["../../src/commands/generate-datasets.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAYH,MAAM,WAAW,uBAAuB;IACtC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AA2BD,wBAAsB,uBAAuB,CAAC,OAAO,GAAE,uBAA4B,iBAqKlF"}

package/dist/commands/generate-datasets.js

@@ -11,6 +11,8 @@ import { getTableCount } from '../utils/detect-database.js';
 import { generateDatasets } from '../generators/dataset-generator.js';
 import { redactConnectionUrl } from '../utils/redact-connection-url.js';
 import { logDatasetGenerationWarnings } from '../utils/dataset-generation-warnings.js';
+import { formatGeneratedFileDiff } from '../utils/generated-file-diff.js';
+import { readGeneratedFile, writeGeneratedFileAtomically } from '../utils/generated-file.js';
 /**
  * Turns the written path into something pasteable into an import statement:
  * strips the `.ts` extension and makes it explicitly relative.
@@ -20,6 +22,11 @@ function toImportSpecifier(relativePath) {
     const normalized = withoutExtension.split(path.sep).join('/');
     return normalized.startsWith('.') ? normalized : `./${normalized}`;
 }
+function refuseOverwrite(relativeOutput) {
+    logger.warn(`Refusing to overwrite existing dataset definitions: ${relativeOutput}`);
+    logger.info('Run again with --diff to inspect changes or --force to replace the file.');
+    process.exitCode = 1;
+}
 function parseTableList(value) {
     const parsed = value
         ?.split(',')
@@ -43,6 +50,11 @@ export async function generateDatasetsCommand(options = {}) {
     }
     const parsedTables = parseTableList(options.tables);
     const excludedTables = parseTableList(options.excludeTables);
+    if (options.force && (options.check || options.diff)) {
+        logger.error('--force cannot be combined with --check or --diff.');
+        process.exitCode = 1;
+        return;
+    }
     logger.newline();
     logger.header('hypequery generate datasets');
     const spinner = ora('Connecting to ClickHouse...').start();
@@ -62,13 +74,59 @@ export async function generateDatasetsCommand(options = {}) {
             // Regeneration replaces the whole file, so a tenant boundary configured at
             // init has to be restated here or it is dropped on every refresh.
             tenantColumn: options.tenantColumn,
+            writeOutput: false,
         });
         const generatedTables = generated?.tables ?? parsedTables ?? [];
         const generatedCount = generatedTables.length || tableCount;
         datasetSpinner.succeed(`Generated dataset definitions for ${generatedCount} ${generatedCount === 1 ? 'table' : 'tables'}`);
-        const relativeOutput = path.relative(process.cwd(), outputPath);
-        logger.success(`Created ${relativeOutput}`);
         logDatasetGenerationWarnings(generated?.warnings);
+        const relativeOutput = path.relative(process.cwd(), outputPath);
+        const currentContents = await readGeneratedFile(outputPath);
+        const contentsMatch = currentContents === generated.contents;
+        if (contentsMatch) {
+            logger.success(options.check || options.diff
+                ? `Dataset definitions are up to date: ${relativeOutput}`
+                : `Unchanged ${relativeOutput}`);
+            if (options.check || options.diff) {
+                return;
+            }
+        }
+        else if (options.diff) {
+            logger.raw(formatGeneratedFileDiff(currentContents ?? '', generated.contents, relativeOutput));
+            logger.error(`Generated dataset definitions differ: ${relativeOutput}`);
+            process.exitCode = 1;
+            return;
+        }
+        else if (options.check) {
+            logger.error(currentContents === undefined
+                ? `Dataset definitions are missing: ${relativeOutput}`
+                : `Generated dataset definitions are out of date: ${relativeOutput}`);
+            process.exitCode = 1;
+            return;
+        }
+        else if (currentContents !== undefined && !options.force) {
+            refuseOverwrite(relativeOutput);
+            return;
+        }
+        else {
+            try {
+                // Without --force this is an exclusive create, so a file written
+                // between the read above and here is refused rather than clobbered.
+                await writeGeneratedFileAtomically(outputPath, generated.contents, {
+                    overwrite: options.force === true,
+                });
+            }
+            catch (error) {
+                if (error.code === 'EEXIST') {
+                    refuseOverwrite(relativeOutput);
+                    return;
+                }
+                throw error;
+            }
+            logger.success(currentContents === undefined
+                ? `Created ${relativeOutput}`
+                : `Updated ${relativeOutput}`);
+        }
         logger.newline();
         logger.header('Next steps:');
         logger.indent('1. Review and customize the generated datasets');

package/dist/generators/dataset-generator.d.ts

@@ -19,6 +19,8 @@ export interface DatasetGeneratorOptions {
      * being silently left unscoped.
      */
     tenantColumn?: string;
+    /** Whether to write the output file. Defaults to true; false renders only. */
+    writeOutput?: boolean;
 }
 export type DatasetGenerationWarning = {
     kind: 'tenant-key-candidate';
@@ -41,5 +43,6 @@ export declare function generateDatasets(options: DatasetGeneratorOptions): Prom
         exportName: string;
     }[];
     warnings: DatasetGenerationWarning[];
+    contents: string;
 }>;
 //# sourceMappingURL=dataset-generator.d.ts.map

package/dist/generators/dataset-generator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dataset-generator.d.ts","sourceRoot":"","sources":["../../src/generators/dataset-generator.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,KAAK,EAAE,8BAA8B,EAAE,MAAM,qBAAqB,CAAC;AAG1E,MAAM,WAAW,uBAAuB;IACtC,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IACzB,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IACzB,MAAM,CAAC,EAAE,8BAA8B,CAAC;IACxC;;;;;;;OAOG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,MAAM,wBAAwB,GAChC;IACE,IAAI,EAAE,sBAAsB,CAAC;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;CACjB,GACD;IACE,IAAI,EAAE,uBAAuB,CAAC;IAC9B,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;CACjB,CAAC;AAkSN;;GAEG;AACH,wBAAsB,gBAAgB,CAAC,OAAO,EAAE,uBAAuB;;;;;;;GAsEtE"}
+{"version":3,"file":"dataset-generator.d.ts","sourceRoot":"","sources":["../../src/generators/dataset-generator.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,KAAK,EAAE,8BAA8B,EAAE,MAAM,qBAAqB,CAAC;AAG1E,MAAM,WAAW,uBAAuB;IACtC,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IACzB,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IACzB,MAAM,CAAC,EAAE,8BAA8B,CAAC;IACxC;;;;;;;OAOG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,8EAA8E;IAC9E,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB;AAED,MAAM,MAAM,wBAAwB,GAChC;IACE,IAAI,EAAE,sBAAsB,CAAC;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;CACjB,GACD;IACE,IAAI,EAAE,uBAAuB,CAAC;IAC9B,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;CACjB,CAAC;AAkSN;;GAEG;AACH,wBAAsB,gBAAgB,CAAC,OAAO,EAAE,uBAAuB;;;;;;;;GAyEtE"}

package/dist/generators/dataset-generator.js

@@ -277,11 +277,13 @@ ${tables.map((table) => `  ${table.name}: ${tableToPascalCase(table.name)}Datase
 };
 `;
     const output = header + datasetDefinitions.join('\n') + footer;
-    // Ensure output directory exists
-    const outputDir = path.dirname(path.resolve(options.outputPath));
-    await fs.mkdir(outputDir, { recursive: true });
-    // Write the file
-    await fs.writeFile(path.resolve(options.outputPath), output);
+    if (options.writeOutput !== false) {
+        // Ensure output directory exists
+        const outputDir = path.dirname(path.resolve(options.outputPath));
+        await fs.mkdir(outputDir, { recursive: true });
+        // Write the file
+        await fs.writeFile(path.resolve(options.outputPath), output);
+    }
     // Returned so the CLI can report what it actually generated, and print an
     // example that matches the file rather than a hardcoded placeholder.
     return {
@@ -291,5 +293,6 @@ ${tables.map((table) => `  ${table.name}: ${tableToPascalCase(table.name)}Datase
             exportName: `${tableToPascalCase(table.name)}Dataset`,
         })),
         warnings,
+        contents: output,
     };
 }

package/dist/utils/generated-file-diff.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Formats one unified hunk spanning the changed region, with nearby context.
+ * Generated files are replaced as a unit, so a compact single hunk is easier
+ * to review than treating every regenerated line as an unrelated edit.
+ */
+export declare function formatGeneratedFileDiff(currentContents: string, generatedContents: string, displayPath: string): string;
+//# sourceMappingURL=generated-file-diff.d.ts.map

package/dist/utils/generated-file-diff.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"generated-file-diff.d.ts","sourceRoot":"","sources":["../../src/utils/generated-file-diff.ts"],"names":[],"mappings":"AAQA;;;;GAIG;AACH,wBAAgB,uBAAuB,CACrC,eAAe,EAAE,MAAM,EACvB,iBAAiB,EAAE,MAAM,EACzB,WAAW,EAAE,MAAM,GAClB,MAAM,CA+CR"}

package/dist/utils/generated-file-diff.js

@@ -0,0 +1,52 @@
+function splitLines(contents) {
+    if (contents.length === 0) {
+        return [];
+    }
+    // Keep a trailing empty line so newline-only changes remain visible.
+    return contents.split('\n');
+}
+/**
+ * Formats one unified hunk spanning the changed region, with nearby context.
+ * Generated files are replaced as a unit, so a compact single hunk is easier
+ * to review than treating every regenerated line as an unrelated edit.
+ */
+export function formatGeneratedFileDiff(currentContents, generatedContents, displayPath) {
+    if (currentContents === generatedContents) {
+        return '';
+    }
+    const currentLines = splitLines(currentContents);
+    const generatedLines = splitLines(generatedContents);
+    let sharedPrefix = 0;
+    while (sharedPrefix < currentLines.length
+        && sharedPrefix < generatedLines.length
+        && currentLines[sharedPrefix] === generatedLines[sharedPrefix]) {
+        sharedPrefix += 1;
+    }
+    let sharedSuffix = 0;
+    while (sharedSuffix < currentLines.length - sharedPrefix
+        && sharedSuffix < generatedLines.length - sharedPrefix
+        && currentLines[currentLines.length - sharedSuffix - 1]
+            === generatedLines[generatedLines.length - sharedSuffix - 1]) {
+        sharedSuffix += 1;
+    }
+    const contextLines = 3;
+    const currentStart = Math.max(0, sharedPrefix - contextLines);
+    const generatedStart = Math.max(0, sharedPrefix - contextLines);
+    const currentChangedEnd = currentLines.length - sharedSuffix;
+    const generatedChangedEnd = generatedLines.length - sharedSuffix;
+    const currentEnd = Math.min(currentLines.length, currentChangedEnd + contextLines);
+    const generatedEnd = Math.min(generatedLines.length, generatedChangedEnd + contextLines);
+    const prefixContext = currentLines.slice(currentStart, sharedPrefix);
+    const suffixContext = currentLines.slice(currentChangedEnd, currentEnd);
+    const removedLines = currentLines.slice(sharedPrefix, currentChangedEnd);
+    const addedLines = generatedLines.slice(sharedPrefix, generatedChangedEnd);
+    return [
+        `--- ${displayPath}`,
+        `+++ ${displayPath} (generated)`,
+        `@@ -${currentStart + 1},${currentEnd - currentStart} +${generatedStart + 1},${generatedEnd - generatedStart} @@`,
+        ...prefixContext.map((line) => ` ${line}`),
+        ...removedLines.map((line) => `-${line}`),
+        ...addedLines.map((line) => `+${line}`),
+        ...suffixContext.map((line) => ` ${line}`),
+    ].join('\n');
+}

package/dist/utils/generated-file.d.ts

@@ -0,0 +1,22 @@
+export interface WriteGeneratedFileOptions {
+    /**
+     * Whether an existing destination may be replaced.
+     *
+     * Defaults to `false`, which makes the write an exclusive create: the
+     * existence check and the write are a single filesystem operation, so a file
+     * that appeared since the caller last looked raises
+     * {@link GeneratedFileExistsError} instead of being silently clobbered.
+     */
+    overwrite?: boolean;
+}
+/**
+ * Thrown when a non-overwriting write finds the destination already present.
+ */
+export declare class GeneratedFileExistsError extends Error {
+    readonly filePath: string;
+    readonly code = "EEXIST";
+    constructor(filePath: string);
+}
+export declare function readGeneratedFile(filePath: string): Promise<string | undefined>;
+export declare function writeGeneratedFileAtomically(filePath: string, contents: string, options?: WriteGeneratedFileOptions): Promise<void>;
+//# sourceMappingURL=generated-file.d.ts.map

package/dist/utils/generated-file.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"generated-file.d.ts","sourceRoot":"","sources":["../../src/utils/generated-file.ts"],"names":[],"mappings":"AAIA,MAAM,WAAW,yBAAyB;IACxC;;;;;;;OAOG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED;;GAEG;AACH,qBAAa,wBAAyB,SAAQ,KAAK;IAGrC,QAAQ,CAAC,QAAQ,EAAE,MAAM;IAFrC,QAAQ,CAAC,IAAI,YAAY;gBAEJ,QAAQ,EAAE,MAAM;CAItC;AAED,wBAAsB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CASrF;AAgCD,wBAAsB,4BAA4B,CAChD,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE,yBAA8B,GACtC,OAAO,CAAC,IAAI,CAAC,CA4Df"}

package/dist/utils/generated-file.js

@@ -0,0 +1,100 @@
+import { randomUUID } from 'node:crypto';
+import { chmod, mkdir, readFile, rename, stat, unlink, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+/**
+ * Thrown when a non-overwriting write finds the destination already present.
+ */
+export class GeneratedFileExistsError extends Error {
+    filePath;
+    code = 'EEXIST';
+    constructor(filePath) {
+        super(`Refusing to overwrite existing file: ${filePath}`);
+        this.filePath = filePath;
+        this.name = 'GeneratedFileExistsError';
+    }
+}
+export async function readGeneratedFile(filePath) {
+    try {
+        return await readFile(filePath, 'utf8');
+    }
+    catch (error) {
+        if (error.code === 'ENOENT') {
+            return undefined;
+        }
+        throw error;
+    }
+}
+/**
+ * Tightest of the permission bits observed on a destination, ignoring the
+ * observations where it did not exist.
+ *
+ * A `chmod` that lands between two observations must not be undone by the
+ * earlier snapshot, and the safe direction is always the more restrictive one:
+ * the replacement is never more permissive than anything the destination was
+ * seen to be.
+ */
+function mostRestrictiveMode(...modes) {
+    const observed = modes.filter((mode) => mode !== undefined);
+    return observed.length > 0 ? observed.reduce((tightest, mode) => tightest & mode) : undefined;
+}
+/**
+ * Permission bits of an existing file, or undefined when it does not exist.
+ */
+async function readExistingMode(filePath) {
+    try {
+        const stats = await stat(filePath);
+        return stats.mode & 0o777;
+    }
+    catch (error) {
+        if (error.code === 'ENOENT') {
+            return undefined;
+        }
+        throw error;
+    }
+}
+export async function writeGeneratedFileAtomically(filePath, contents, options = {}) {
+    const resolvedPath = path.resolve(filePath);
+    const outputDirectory = path.dirname(resolvedPath);
+    await mkdir(outputDirectory, { recursive: true });
+    if (!options.overwrite) {
+        try {
+            // O_EXCL: the destination is created only if it is still absent, so a
+            // concurrent create between the caller's check and this write is never
+            // lost.
+            await writeFile(resolvedPath, contents, { flag: 'wx' });
+            return;
+        }
+        catch (error) {
+            if (error.code === 'EEXIST') {
+                throw new GeneratedFileExistsError(resolvedPath);
+            }
+            throw error;
+        }
+    }
+    const temporaryPath = path.join(outputDirectory, `.${path.basename(resolvedPath)}.${process.pid}.${randomUUID()}.tmp`);
+    // Read the destination's mode first: the temporary file must never be created
+    // more permissively than the file it replaces, or its contents are briefly
+    // exposed to other local users in a shared directory.
+    const existingMode = await readExistingMode(resolvedPath);
+    try {
+        await writeFile(temporaryPath, contents, existingMode !== undefined ? { mode: existingMode } : {});
+        // The destination can be chmod'ed — or created — while the contents above
+        // are being written. Renaming with only the pre-write snapshot would undo
+        // that, replacing a file just tightened to 0600 with a 0644 one, so the
+        // tighter of the two observations wins.
+        const destinationMode = mostRestrictiveMode(existingMode, await readExistingMode(resolvedPath));
+        // open() also applies the umask, and rename() swaps in a new inode, so the
+        // destination's exact mode has to be restored explicitly or a customized
+        // mode is silently reset. A chmod landing after this read still races the
+        // rename — rename() cannot be made conditional on the destination's mode —
+        // but the window is now two syscalls rather than the whole write.
+        if (destinationMode !== undefined) {
+            await chmod(temporaryPath, destinationMode);
+        }
+        await rename(temporaryPath, resolvedPath);
+    }
+    catch (error) {
+        await unlink(temporaryPath).catch(() => undefined);
+        throw error;
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hypequery/cli",
-  "version": "1.18.1",
+  "version": "1.18.3",
   "description": "CLI for scaffolding type-safe ClickHouse analytics, semantic datasets, React manifests, and deployments",
   "keywords": [
     "clickhouse",
@@ -30,8 +30,8 @@
     "open": "^10.0.0",
     "ora": "^8.0.1",
     "prompts": "^2.4.2",
-    "@hypequery/protocol": "0.11.0",
-    "@hypequery/deployment": "0.7.3"
+    "@hypequery/protocol": "0.11.1",
+    "@hypequery/deployment": "0.7.4"
   },
   "optionalDependencies": {
     "@napi-rs/keyring": "1.3.0"
@@ -45,7 +45,7 @@
     "@vitest/coverage-v8": "^3.2.6",
     "typescript": "^5.7.3",
     "vitest": "^3.2.6",
-    "@hypequery/serve": "0.16.1"
+    "@hypequery/serve": "0.16.2"
   },
   "repository": {
     "type": "git",