@wavehouse/chtypes 0.1.0

package/dist/cli.js

@@ -0,0 +1,303 @@
+#!/usr/bin/env node
+/**
+ * `chtypes` — the one CLI surface every SDK carries (docs/fetch.md §6),
+ * spelled identically in all four:
+ *
+ *   chtypes fetch <line>... [--all] [--platform <os-arch>] [--dest <dir>]
+ *                           [--tag <t> | --url <base>] [--lock <file>] [--frozen]
+ *                           [--force] [--offline]
+ *   chtypes verify [--dest <dir>]        re-hash every installed line against its manifest
+ *   chtypes list   [--dest <dir>]        what is installed, and what the release offers
+ *   chtypes where                        the registry directory fetch would write to
+ *
+ * Exit codes: 0 ok · 1 verification failed · 2 usage · 3 source unreachable ·
+ * 4 not published for this platform/line. Progress goes to stderr; `fetch`
+ * prints the installed directory alone on stdout, so it composes:
+ *
+ *   dir="$(npx @wavehouse/chtypes fetch 25.8)"
+ *
+ * `runCli` is exported so the suite can drive the command in-process; the
+ * file runs `main` only when it is the process's entry point (the `bin`).
+ */
+import { realpathSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { fileURLToPath } from 'node:url';
+import { parseArgs } from 'node:util';
+import { ArtifactUnpublishedError, ChtypesError, FetchError, SourceUnreachableError } from './errors.js';
+import { ensure, ensureAll, listArtifacts, resolvePlatform, verifyInstalled } from './fetch.js';
+import { fetchDestination } from './paths.js';
+/** The §6 exit codes. */
+export const EXIT = {
+    ok: 0,
+    verificationFailed: 1,
+    usage: 2,
+    sourceUnreachable: 3,
+    unpublished: 4,
+};
+const USAGE = `usage: chtypes <command> [options]
+
+  chtypes fetch <line>... [--all] [--platform <os-arch>] [--dest <dir>]
+                          [--tag <t> | --url <base>] [--lock <file>] [--frozen]
+                          [--force] [--offline]
+  chtypes verify [--dest <dir>] [--platform <os-arch>]
+  chtypes list   [--dest <dir>] [--platform <os-arch>] [--tag <t> | --url <base>] [--offline]
+  chtypes where  [--dest <dir>] [--platform <os-arch>]
+
+  <line>      a ClickHouse line (25.8) or an exact patch (25.8.28.1-lts, a hard requirement)
+  --all       every line the release publishes for the platform
+  --platform  <os>-<arch> (linux|darwin)-(arm64|amd64); default: this host
+  --dest      the registry directory; default: CHTYPES_REGISTRY, else the per-user cache
+  --tag       a release tag on the artifacts host (default: the rolling "artifacts")
+  --url       any other base: https://…, file://…, or a directory
+  --lock      record what was installed into this lock file (default with --frozen: chtypes.lock)
+  --frozen    refuse anything the lock file does not pin
+  --force     re-download an installed line
+  --offline   never touch the source: installed-and-verified is fine, anything else fails
+  -q, --quiet no progress on stderr
+  -h, --help  this text;  -V, --version  the package version
+
+exit codes: 0 ok · 1 verification failed · 2 usage · 3 source unreachable · 4 not published
+environment: CHTYPES_ARTIFACTS_URL, CHTYPES_REGISTRY, CHTYPES_TRUSTED_KEYS, CHTYPES_ALLOW_UNSIGNED,
+             CHTYPES_AUTOFETCH, CHTYPES_TARGET, XDG_CACHE_HOME
+`;
+const defaultIo = {
+    stdout: (text) => process.stdout.write(text),
+    stderr: (text) => process.stderr.write(text),
+    tty: process.stderr.isTTY === true,
+};
+/**
+ * Run the command with `argv` (the arguments after the program name) and
+ * return its exit code. Never throws for a user-facing failure: every §7
+ * verdict is printed to stderr and mapped to its exit code.
+ */
+export async function runCli(argv, io = defaultIo) {
+    let parsed;
+    try {
+        parsed = parseArgs({ ...CONFIG, args: [...argv] });
+    }
+    catch (err) {
+        io.stderr(`chtypes: ${err instanceof Error ? err.message : String(err)}\n${USAGE}`);
+        return EXIT.usage;
+    }
+    const { values, positionals } = parsed;
+    if (values.help) {
+        io.stdout(USAGE);
+        return EXIT.ok;
+    }
+    if (values.version) {
+        io.stdout(`${packageVersion()}\n`);
+        return EXIT.ok;
+    }
+    const [command, ...rest] = positionals;
+    if (command === undefined) {
+        io.stderr(USAGE);
+        return EXIT.usage;
+    }
+    try {
+        switch (command) {
+            case 'fetch':
+                return await cmdFetch(rest, values, io);
+            case 'verify':
+                return await cmdVerify(rest, values, io);
+            case 'list':
+                return await cmdList(rest, values, io);
+            case 'where':
+                return cmdWhere(rest, values, io);
+            default:
+                io.stderr(`chtypes: unknown command ${JSON.stringify(command)}\n${USAGE}`);
+                return EXIT.usage;
+        }
+    }
+    catch (err) {
+        return report(err, io);
+    }
+}
+const CONFIG = {
+    allowPositionals: true,
+    strict: true,
+    options: {
+        all: { type: 'boolean' },
+        platform: { type: 'string' },
+        dest: { type: 'string' },
+        tag: { type: 'string' },
+        url: { type: 'string' },
+        lock: { type: 'string' },
+        frozen: { type: 'boolean' },
+        force: { type: 'boolean' },
+        offline: { type: 'boolean' },
+        quiet: { type: 'boolean', short: 'q' },
+        help: { type: 'boolean', short: 'h' },
+        version: { type: 'boolean', short: 'V' },
+    },
+};
+function ensureOptions(values, io) {
+    if (values.url !== undefined && values.tag !== undefined) {
+        throw new ChtypesError('chtypes: --url names a full base; --tag selects a release on the artifacts host — pass one');
+    }
+    const lock = values.lock ?? (values.frozen ? 'chtypes.lock' : undefined);
+    return {
+        dest: values.dest,
+        platform: values.platform,
+        tag: values.tag,
+        url: values.url,
+        lock,
+        frozen: values.frozen ?? false,
+        force: values.force ?? false,
+        offline: values.offline ?? false,
+        onProgress: values.quiet ? undefined : progressPrinter(io),
+    };
+}
+async function cmdFetch(lines, values, io) {
+    const options = ensureOptions(values, io);
+    if (values.all) {
+        if (lines.length > 0) {
+            throw new ChtypesError(`chtypes: --all installs every published line; drop the version argument (${lines.join(', ')})`);
+        }
+        const results = await ensureAll(options);
+        if (results.length === 0)
+            throw new ArtifactUnpublishedError('chtypes: the release publishes nothing for this platform');
+        for (const r of results)
+            io.stdout(`${r.dir}\n`);
+        say(io, `${results.length} line(s) installed into ${results[0].registry}`);
+        return EXIT.ok;
+    }
+    if (lines.length === 0) {
+        io.stderr(`chtypes: a ClickHouse line is required (or --all)\n${USAGE}`);
+        return EXIT.usage;
+    }
+    for (const line of lines) {
+        const r = await ensure(line, options);
+        io.stdout(`${r.dir}\n`);
+    }
+    return EXIT.ok;
+}
+async function cmdVerify(rest, values, io) {
+    if (rest.length > 0)
+        throw new ChtypesError(`chtypes: verify takes no positional arguments (${rest.join(', ')})`);
+    const platform = resolvePlatform(values.platform);
+    const dir = fetchDestination(values.dest, platform);
+    const results = await verifyInstalled(values.dest, platform);
+    if (results.length === 0) {
+        say(io, `nothing installed in ${dir}`);
+        return EXIT.ok;
+    }
+    let bad = 0;
+    for (const r of results) {
+        if (r.ok)
+            io.stdout(`ok   ${r.line.padEnd(6)} ${r.version.padEnd(18)} ${r.library}  sha256 ${r.actual}\n`);
+        else {
+            bad += 1;
+            io.stdout(`BAD  ${r.line.padEnd(6)} ${r.version.padEnd(18)} ${r.library}  ${r.problem}\n`);
+        }
+    }
+    say(io, bad === 0 ? `${results.length} line(s) verified in ${dir}` : `${bad} of ${results.length} line(s) FAILED verification in ${dir}`);
+    return bad === 0 ? EXIT.ok : EXIT.verificationFailed;
+}
+async function cmdList(rest, values, io) {
+    if (rest.length > 0)
+        throw new ChtypesError(`chtypes: list takes no positional arguments (${rest.join(', ')})`);
+    const options = ensureOptions(values, io);
+    const listing = await listArtifacts({ ...options, onProgress: undefined });
+    io.stdout(`installed in ${listing.registry} (${listing.platform}):\n`);
+    if (listing.installed.length === 0)
+        io.stdout('  (nothing)\n');
+    for (const a of listing.installed) {
+        io.stdout(`  ${a.line.padEnd(6)} ${a.version.padEnd(18)} ${a.library}${a.ok ? '' : `  (${a.problem})`}\n`);
+    }
+    if (listing.offered !== null) {
+        const have = new Set(listing.installed.filter((a) => a.ok).map((a) => a.version));
+        io.stdout(`release ${listing.source} offers for ${listing.platform}:\n`);
+        if (listing.offered.length === 0)
+            io.stdout('  (nothing)\n');
+        for (const a of listing.offered) {
+            io.stdout(`  ${a.clickhouse_minor.padEnd(6)} ${a.clickhouse_version.padEnd(18)} ${a.file}  ${a.bytes} bytes${have.has(a.clickhouse_version) ? '  (installed)' : ''}\n`);
+        }
+    }
+    return EXIT.ok;
+}
+function cmdWhere(rest, values, io) {
+    if (rest.length > 0)
+        throw new ChtypesError(`chtypes: where takes no positional arguments (${rest.join(', ')})`);
+    io.stdout(`${fetchDestination(values.dest, resolvePlatform(values.platform))}\n`);
+    return EXIT.ok;
+}
+/** Map an error to its §6 exit code, after printing it. */
+function report(err, io) {
+    if (err instanceof FetchError) {
+        io.stderr(`${err.message} [${err.code}]\n`);
+        if (err instanceof SourceUnreachableError)
+            return EXIT.sourceUnreachable;
+        if (err instanceof ArtifactUnpublishedError)
+            return EXIT.unpublished;
+        return EXIT.verificationFailed;
+    }
+    if (err instanceof ChtypesError) {
+        io.stderr(`${err.message}\n`);
+        return EXIT.usage;
+    }
+    io.stderr(`chtypes: ${err instanceof Error ? (err.stack ?? err.message) : String(err)}\n`);
+    return EXIT.verificationFailed;
+}
+function say(io, message) {
+    io.stderr(io.tty ? `==> ${message}\n` : `==> ${message}\n`);
+}
+/** Status lines as `==> …`; download progress redrawn in place on a terminal, at 10 % steps otherwise. */
+function progressPrinter(io) {
+    let lastStep = -1;
+    let drawing = false;
+    return (event) => {
+        if (event.type === 'status') {
+            if (drawing) {
+                io.stderr('\n');
+                drawing = false;
+            }
+            say(io, event.message);
+            return;
+        }
+        const pct = event.total > 0 ? Math.min(100, Math.floor((event.received * 100) / event.total)) : 0;
+        const mb = (n) => (n / 1e6).toFixed(1);
+        if (io.tty) {
+            io.stderr(`\r    ${event.file}  ${mb(event.received)} / ${mb(event.total)} MB  ${pct}%`);
+            drawing = true;
+            if (event.received >= event.total) {
+                io.stderr('\n');
+                drawing = false;
+            }
+            return;
+        }
+        const step = Math.floor(pct / 10);
+        if (step !== lastStep) {
+            lastStep = step;
+            io.stderr(`    ${event.file}  ${mb(event.received)} / ${mb(event.total)} MB  ${pct}%\n`);
+        }
+    };
+}
+function packageVersion() {
+    try {
+        const pkg = createRequire(import.meta.url)('../package.json');
+        return pkg.version ?? '0.0.0';
+    }
+    catch {
+        return '0.0.0';
+    }
+}
+function invokedDirectly() {
+    const entry = process.argv[1];
+    if (entry === undefined)
+        return false;
+    try {
+        return realpathSync(entry) === realpathSync(fileURLToPath(import.meta.url));
+    }
+    catch {
+        return false;
+    }
+}
+if (invokedDirectly()) {
+    runCli(process.argv.slice(2)).then((code) => {
+        process.exitCode = code;
+    }, (err) => {
+        process.stderr.write(`chtypes: ${err instanceof Error ? (err.stack ?? err.message) : String(err)}\n`);
+        process.exitCode = EXIT.verificationFailed;
+    });
+}
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"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"}

package/dist/discover.d.ts

@@ -0,0 +1,134 @@
+/**
+ * The discovery kit.
+ *
+ * This library NEVER talks to ClickHouse; it ships the queries. At connect
+ * time a caller (a gateway, WaveHouse) runs these three queries against the
+ * deployment's own server with whatever client it already has, feeds the
+ * results to the typed parsers below, and then declares what it learned:
+ *
+ *   profile.version  -> Registry#for / the artifact to load
+ *   profile.settings -> compileDdl({ settings }) (compile-time) and per-call settings
+ *   columns          -> reconstructDdl -> compileDdl
+ *
+ * The pattern, in full (spec/bindings.md §Discovery):
+ *
+ *   1. run QUERY_SERVER_VERSION, QUERY_CHANGED_SETTINGS once per connection
+ *   2. cache the ServerProfile per deployment/tenant
+ *   3. const lib = registry.for(profile.version)
+ *   4. const schema = lib.compileDdl(ddl, { settings: profile.settings, mode: 0 })
+ *   5. per call: pass profile.settings (plus any per-INSERT overrides) to rows()
+ *
+ * Never ask the customer for their settings — ask their server. The queries
+ * return exactly what the server believes, spelled the way the server spells
+ * it, which is what the settings gate (spec/c-abi.md, Settings rule 2)
+ * validates against.
+ *
+ * The parsers read JSONEachRow bytes through this package's own byte-exact
+ * JSON reader, so a numeric field (`position`) is taken from its literal
+ * digits — quoted or bare, ClickHouse's stock HTTP output quotes 64-bit
+ * integers — and never routed through a float.
+ */
+/**
+ * Names the deployment's exact release — the string `Registry#for` resolves
+ * (minor line or exact patch both work). One row: `{"version":"25.8.28.1"}`.
+ */
+export declare const QUERY_SERVER_VERSION = "SELECT version() AS version FORMAT JSONEachRow";
+/**
+ * Lists every query setting the deployment runs at a NON-default value — the
+ * whole declared profile, from the server itself. One row per setting:
+ * `{"name":"flatten_nested","value":"0"}`. `system.settings.value` is already
+ * a String; the map feeds `compileDdl({ settings })` and per-call settings
+ * verbatim.
+ */
+export declare const QUERY_CHANGED_SETTINGS = "SELECT name, value FROM system.settings WHERE changed FORMAT JSONEachRow";
+/**
+ * Describes one existing table, in declaration order, with everything a
+ * column-declaration list needs — INCLUDING `default_kind` and
+ * `default_expression`, without which a reconstructed schema silently loses
+ * its DEFAULT/MATERIALIZED semantics. Uses ClickHouse's own query parameters:
+ * send `param_db` / `param_table` (HTTP) or bind `{db}`/`{table}` (native).
+ */
+export declare const QUERY_TABLE_COLUMNS: string;
+/**
+ * What discovery learns about one deployment: the exact release and the
+ * settings it runs changed from defaults. Cache one per deployment (or per
+ * tenant on bring-your-own-ClickHouse) and declare it.
+ */
+export interface ServerProfile {
+    /** e.g. "25.8.28.1" — feed `Registry#for`. */
+    readonly version: string;
+    /** Changed settings — feed `compileDdl({ settings })` and per-call settings. */
+    readonly settings: Record<string, string>;
+}
+/** One row of `QUERY_TABLE_COLUMNS`. */
+export interface DiscoveredColumn {
+    readonly name: string;
+    readonly type: string;
+    /** "" | "DEFAULT" | "MATERIALIZED" | "ALIAS" | "EPHEMERAL" */
+    readonly defaultKind: string;
+    readonly defaultExpression: string;
+    readonly position: number;
+}
+/**
+ * Read `QUERY_SERVER_VERSION`'s JSONEachRow body.
+ *
+ * @param body - the query result bytes (or text) as the server sent them.
+ * @returns the version string, e.g. `"25.8.28.1"` — feed `Registry#for`.
+ * @throws {ChtypesError} when the body is not exactly one JSONEachRow row with
+ *   a non-empty `version` field.
+ */
+export declare function parseVersionResult(body: Uint8Array | string): string;
+/**
+ * Read `QUERY_CHANGED_SETTINGS`' JSONEachRow body. An empty body is a stock
+ * server: an empty map, not an error.
+ *
+ * @param body - the query result bytes (or text) as the server sent them.
+ * @returns setting name → value, ready for `ServerProfile#settings`,
+ *   `compileDdl({ settings })` and per-call settings.
+ * @throws {ChtypesError} when a row is not JSONEachRow or lacks `name`/`value`.
+ */
+export declare function parseChangedSettingsResult(body: Uint8Array | string): Record<string, string>;
+/**
+ * Read `QUERY_TABLE_COLUMNS`' JSONEachRow body, in the query's ORDER BY
+ * position order. `position` survives both spellings — quoted on stock HTTP
+ * output (`output_format_json_quote_64bit_integers=1`) and bare when a client
+ * unsets that — parsed from its literal digits, never through `JSON.parse`'s
+ * double. A position is small, so it fits a JS number once those digits are
+ * in hand; a malformed one is left 0, as the reference leaves it.
+ *
+ * @param body - the query result bytes (or text) as the server sent them.
+ * @returns one `DiscoveredColumn` per row, in the query's position order —
+ *   feed `reconstructDdl`.
+ * @throws {ChtypesError} when a row is malformed, lacks `name`/`type`, or the
+ *   body holds no rows at all (wrong database/table, or no access).
+ */
+export declare function parseColumnsResult(body: Uint8Array | string): DiscoveredColumn[];
+/**
+ * Turn `QUERY_TABLE_COLUMNS`' rows back into the column-declaration list
+ * `compileDdl` takes. It is a spelling exercise, not a semantic one: types
+ * and expressions are the server's own text, passed through verbatim, and the
+ * library's own compile is the judge of the result.
+ *
+ * Two facts a caller must know, both properties of the server rather than of
+ * this function:
+ *
+ *  - `system.columns` reports the table AS STORED. Under the default
+ *    `flatten_nested=1` a `Nested(a,b)` column appears as its flattened
+ *    `n.a`/`n.b` Array columns and reconstructs to exactly those — which is
+ *    the same table. Under `flatten_nested=0` it appears as one column of
+ *    type `Nested(...)`, which also reconstructs directly. Reconstruction is
+ *    therefore shape-faithful either way, PROVIDED the same `flatten_nested`
+ *    value is declared to `compileDdl({ settings })` that the table was
+ *    created under — which is what the discovered `ServerProfile.settings`
+ *    carries.
+ *  - a MATERIALIZED/ALIAS column reconstructs with its expression; an
+ *    EPHEMERAL column may legitimately have an empty `default_expression`.
+ *
+ * @param cols - the discovered columns, e.g. from `parseColumnsResult`.
+ * @returns the column-declaration list for `Library#compileDdl`.
+ * @throws {ChtypesError} when a column is inconsistent: no name/type, a
+ *   `default_expression` with no kind, a DEFAULT/MATERIALIZED/ALIAS kind with
+ *   no expression, an unknown kind, or no columns at all.
+ */
+export declare function reconstructDdl(cols: readonly DiscoveredColumn[]): string;
+//# sourceMappingURL=discover.d.ts.map

package/dist/discover.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"discover.d.ts","sourceRoot":"","sources":["../src/discover.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAUH;;;GAGG;AACH,eAAO,MAAM,oBAAoB,mDAAmD,CAAC;AAErF;;;;;;GAMG;AACH,eAAO,MAAM,sBAAsB,6EAA6E,CAAC;AAEjH;;;;;;GAMG;AACH,eAAO,MAAM,mBAAmB,QAGQ,CAAC;AAEzC;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC5B,8CAA8C;IAC9C,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,gFAAgF;IAChF,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC3C;AAED,wCAAwC;AACxC,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,8DAA8D;IAC9D,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;IACnC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAsED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,UAAU,GAAG,MAAM,GAAG,MAAM,CAcpE;AAED;;;;;;;;GAQG;AACH,wBAAgB,0BAA0B,CAAC,IAAI,EAAE,UAAU,GAAG,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAc5F;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,UAAU,GAAG,MAAM,GAAG,gBAAgB,EAAE,CA2BhF;AAaD;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,SAAS,gBAAgB,EAAE,GAAG,MAAM,CAmCxE"}