@eyeauras/opensearch-cli 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 opensearch-cli contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,116 @@
-# Temporary Holding Version
+# opensearch-cli
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A general-purpose command-line client for [OpenSearch](https://opensearch.org/), built on
+[CliFactory](https://github.com/iXab3r/EyeAuras.CliFactory) (`@eyeauras/cli-factory`).
+
+> **M2 Explore data:** profiles, cluster info/health, indices, aliases, data streams, fields and count are available.
+> Further OpenSearch commands are being delivered in [approved milestones](https://github.com/iXab3r/opensearch-cli/issues/7).
+> The package has not been published.
+
+## Development
+
+Use Node 22 or 24 and the pinned npm version. Run `npm ci && npm test` for offline CLI tests,
+`npm run test:package` for an isolated installation check, or
+`dotnet run --project build -- --target Verify` for the complete CI check.
+See [testing](docs/testing.md) and [release preparation](docs/release.md).
+
+## Connect and inspect
+
+```text
+opensearch-cli profile configure dev --url https://cluster.example.com:9200 --auth basic --username operator --password-stdin
+opensearch-cli profile configure prod --url https://search.example.com --auth bearer --token-stdin
+opensearch-cli profile configure local --url http://localhost:9200 --auth none
+opensearch-cli auth status --profile dev
+opensearch-cli cluster info --profile dev
+opensearch-cli cluster health --profile dev --index 'sample-*' --level indices
+opensearch-cli cluster health --profile dev --wait-for-status green --timeout 30s --json
+```
+
+Pass a password or bare bearer token on stdin; credentials stay in the platform secret store.
+Basic passwords preserve whitespace, removing one final line ending. Basic login requires both
+`--username` and `--password-stdin`. Open profiles use no credential.
+Cluster info reports unsupported distributions/versions with a stderr warning and retains their metadata.
+Cluster health reads red state successfully; a wait timeout fails with the observed health on stdout.
+`ReadOnly` is enabled by default. `Update` and `Delete` start disabled.
+
+## List indices
+
+```text
+opensearch-cli indices list
+opensearch-cli indices list 'sample-*' --health yellow
+opensearch-cli indices list --include-hidden --json
+```
+
+Rows are sorted by name and show health, open/close status, primary and replica shard counts,
+document count and total store size. Hidden and system indices are excluded by metadata classification,
+even when named explicitly; `--include-hidden` includes both kinds visible to your profile.
+The default read uses CAT statistics plus a narrow cluster-state metadata projection, compatible
+with OpenSearch 2.x and 3.x. Server permissions must allow `indices:monitor/stats`,
+`indices:monitor/settings/get`, `cluster:monitor/state` and `cluster:monitor/health`.
+No index documents, mappings or unrelated settings are returned.
+
+JSON and RPC return the same array of `{name, health, status, primaries, replicas, docsCount, storeBytes}`.
+Counts are numbers and sizes are numbers in bytes; unavailable statistics and health (for example on a closed
+index) are `null`. Human sizes use binary units. No matches return `[]` successfully.
+
+## Explore definitions and count documents
+
+```text
+opensearch-cli aliases list 'sample-*'
+opensearch-cli data-streams list 'sample-*'
+opensearch-cli indices show sample-a
+opensearch-cli indices show sample-a --section mappings --json
+opensearch-cli fields list 'sample-*' --filter 'user.*'
+opensearch-cli fields list 'sample-*' --type keyword --include-meta --json
+opensearch-cli count 'sample-*'
+opensearch-cli count sample-a --q 'status:500'
+opensearch-cli count sample-a --query-file query.json --fail-on-partial --json
+opensearch-cli count sample-a --query-file -
+```
+
+Alias rows show each target index, the nullable write-index flag and filter/routing presence.
+Data streams show their timestamp field, generation, backing-index count and health. Empty lists
+are successful. Index inspection returns `{name, settings, aliases, mappings}`; settings normalize
+shard counts and creation time, while mapping/alias definitions retain OpenSearch's structure.
+`--section settings|mappings|aliases` returns only that section. A missing index reports
+`index.notFound` and suggests `indices list`. Arbitrary definitions use Core's structured human view.
+
+Fields include object, nested and multi-field dotted paths. Each row retains `types`, `conflict`
+and `indicesByType`; `--type` selects matching fields without hiding their other conflicting types.
+`--filter` matches full paths with `*` and `?`. Reserved metadata fields require `--include-meta`;
+ordinary underscore-prefixed user fields stay visible.
+
+Query files contain the Query DSL **query object**, for example `{"term":{"status":500}}`, rather
+than a full search body. Relative paths resolve from the command's working directory. `-` reads
+fresh CLI stdin; JSON-RPC callers use a file because stdin carries the RPC protocol. Choose either
+`--q` or `--query-file`. Count returns numeric `count`, normalized `_shards` statistics, and
+`partial: {failedShards, totalShards, failures}`. Shard failures warn human callers on stderr;
+`--fail-on-partial` exits with `search.partial` and retains the result on stdout/RPC error result.
+All these commands are ReadOnly and use the selected profile's server permissions.
+Shard failure details retain index, shard, node and type/reason/cause chains. Diagnostic text
+uses Core's credential redaction before the domain result reaches any output or caller.
+
+## Agreed direction
+
+- **Universal product.** The CLI speaks OpenSearch concepts: indices, mappings, Query DSL,
+  search, aggregations, pagination, documents and cluster state. It carries no knowledge of any
+  particular deployment, application, log schema or business process.
+- **Supported versions:** OpenSearch 2.x and 3.x. Amazon OpenSearch Service is tracked separately
+  and is not a commitment.
+- **CliFactory owns the common mechanics:** command declarations, help, human/JSON output,
+  JSON-RPC, profiles, secret storage and permission gates. This repository owns only the
+  OpenSearch API and its semantics.
+- **Standalone process, no IPC.** Calls are cheap and the CLI keeps no state between invocations.
+- **Build and release run on TeamCity**, not GitHub Actions.
+
+Maintainers: follow the [staged release flow](docs/release.md).
+
+## Non-goals
+
+- A UI, an MCP server or a hosted platform.
+- Elasticsearch compatibility.
+- Copying CliFactory sources; the framework is consumed as a package.
+
+## License
+
+[MIT](LICENSE)

package/dist/src/auth.d.ts

@@ -0,0 +1,2 @@
+import { type AuthDefinition } from "@eyeauras/cli-factory";
+export declare function openSearchAuth(): AuthDefinition;

package/dist/src/auth.js

@@ -0,0 +1,86 @@
+import { CliError, diagnosticCause, tokenAuth } from "@eyeauras/cli-factory";
+import { clientFor, OpenSearchClient } from "./client.js";
+// Passwords are arbitrary secrets: preserve whitespace, removing only one terminal line ending.
+async function readPassword(context) {
+    const chunks = [];
+    const abort = () => context.io.input.destroy(new CliError("Password input interrupted.", { code: "interrupted", exitCode: 130 }));
+    context.signal.throwIfAborted();
+    context.signal.addEventListener("abort", abort, { once: true });
+    try {
+        for await (const chunk of context.io.input)
+            chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+        context.signal.throwIfAborted();
+        return Buffer.concat(chunks).toString("utf8").replace(/\r?\n$/, "");
+    }
+    finally {
+        context.signal.removeEventListener("abort", abort);
+    }
+}
+export function openSearchAuth() {
+    const bearer = tokenAuth({
+        validate: context => new OpenSearchClient({ url: String(context.profile.values.url), fetch: context.fetch, signal: context.signal, authorization: "Bearer " + context.token }).identity(),
+    });
+    return {
+        // Every scheme validates the connection at configure/login/status, including open clusters.
+        required: () => true,
+        isReady: async (context) => context.profile.values.auth === "none" || !!await context.secrets.get(context.profile.values.auth === "bearer" ? "token" : "basic"),
+        loginOptions: [
+            { flags: "--username <name>", description: "Set the Basic authentication username" },
+            { flags: "--password-stdin", description: "Read the Basic password from stdin" },
+            ...(bearer.loginOptions ?? []),
+        ],
+        async login(context, options) {
+            if (context.profile.values.auth === "none") {
+                await new OpenSearchClient({ url: String(context.profile.values.url), fetch: context.fetch, signal: context.signal }).info();
+                await context.secrets.delete("basic");
+                await context.secrets.delete("token");
+                return { authenticated: true, identity: { url: context.profile.values.url, reachable: true } };
+            }
+            if (context.profile.values.auth === "bearer") {
+                try {
+                    const status = await bearer.login(context, options);
+                    await context.secrets.delete("basic");
+                    return status;
+                }
+                catch (error) {
+                    const code = error instanceof CliError && error.code === "auth.validationFailed"
+                        ? error.cause?.code : undefined;
+                    if (code?.startsWith("http."))
+                        throw new CliError("OpenSearch rejected the authentication check.", {
+                            code, cause: error, next: [["profile", "configure", context.profile.name, "--url", String(context.profile.values.url), "--auth", "bearer", "--token-stdin"]],
+                        });
+                    throw error;
+                }
+            }
+            if (!options.passwordStdin || !context.stdinAvailable || typeof options.username !== "string" || !options.username || options.username.includes(":"))
+                throw new CliError("Provide --username and --password-stdin for Basic authentication.", { code: "auth.missing", next: [["auth", "login", "--help"]] });
+            const password = await readPassword(context);
+            if (!password)
+                throw new CliError("The Basic password is empty.", { code: "auth.missing", next: [["auth", "login", "--help"]] });
+            const authorization = "Basic " + Buffer.from(`${options.username}:${password}`).toString("base64");
+            const client = new OpenSearchClient({ url: String(context.profile.values.url), fetch: context.fetch, signal: context.signal, authorization });
+            const identity = await client.identity();
+            context.signal.throwIfAborted();
+            try {
+                await context.secrets.set("basic", JSON.stringify({ username: options.username, password }));
+            }
+            catch (cause) {
+                throw new CliError("Could not save Basic credentials in secure storage.", { code: "auth.storeFailed", cause: diagnosticCause(cause, [password, authorization]), next: [["auth", "login", "--help"]] });
+            }
+            await context.secrets.delete("token");
+            return { authenticated: true, identity };
+        },
+        async status(context) {
+            if (context.profile.values.auth === "none")
+                return { authenticated: true, identity: await (await clientFor(context)).identity() };
+            const name = context.profile.values.auth === "bearer" ? "token" : "basic";
+            if (!await context.secrets.get(name))
+                return { authenticated: false };
+            return { authenticated: true, identity: await (await clientFor(context)).identity() };
+        },
+        async logout(context) {
+            await context.secrets.delete("basic");
+            await bearer.logout(context);
+        },
+    };
+}

package/dist/src/bin.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/src/bin.js

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+import { createCli } from "@eyeauras/cli-factory";
+import { createDefinition } from "./cli.js";
+const app = createCli(createDefinition());
+try {
+    process.exitCode = await app.run();
+}
+finally {
+    await app.dispose();
+}

package/dist/src/cli.d.ts

@@ -0,0 +1,2 @@
+import { type CliDefinition } from "@eyeauras/cli-factory";
+export declare function createDefinition(): CliDefinition;

package/dist/src/cli.js

@@ -0,0 +1,137 @@
+import { CliError, command, parseServerUrl, recordView, tableView } from "@eyeauras/cli-factory";
+import { openSearchAuth } from "./auth.js";
+import { clientFor } from "./client.js";
+import { readQuery } from "./query.js";
+import { version } from "./version.js";
+export function createDefinition() {
+    return {
+        name: "opensearch-cli",
+        description: "Explore and manage OpenSearch clusters",
+        version,
+        permissions: { categories: [{ name: "Delete", description: "Delete OpenSearch data", enabledByDefault: false }] },
+        profile: {
+            defaults: { auth: "basic" },
+            fields: [
+                { name: "url", flags: "--url <url>", description: "Set the OpenSearch cluster URL", required: true, normalize: value => parseServerUrl(String(value), "OpenSearch URL must be http(s)://host[:port][/context].").href },
+                { name: "auth", flags: "--auth <scheme>", description: "Choose basic, bearer or none", normalize: value => {
+                        if (!["basic", "bearer", "none"].includes(String(value)))
+                            throw new CliError("Authentication must be basic, bearer or none.", { code: "usage" });
+                        return value;
+                    } },
+            ],
+        },
+        auth: openSearchAuth(),
+        commands: [command("cluster", "Inspect the OpenSearch cluster", [
+                command("info", "Show cluster version and identity", async (_, context) => {
+                    const info = await (await clientFor(context)).info();
+                    if (info.version.distribution !== "opensearch" || !/^[23]\./.test(info.version.number))
+                        context.io.error.write("Warning: unsupported distribution or version; supported versions are OpenSearch 2.x and 3.x.\n");
+                    return info;
+                }, { permission: "ReadOnly", view: recordView({ fields: [
+                            { label: "Cluster", value: value => value.cluster_name },
+                            { label: "UUID", value: value => value.cluster_uuid },
+                            { label: "Distribution", value: value => value.version.distribution },
+                            { label: "Version", value: value => value.version.number },
+                            { label: "Build date", value: value => value.version.build_date },
+                            { label: "Build hash", value: value => value.version.build_hash },
+                            { label: "Lucene", value: value => value.version.lucene_version },
+                        ] }) }),
+                command("health", "Show cluster health and shard allocation", async ({ options }, context) => (await clientFor(context)).health(options), {
+                    permission: "ReadOnly",
+                    options: [
+                        { flags: "--index <pattern>", description: "Select indices or data streams" },
+                        { flags: "--level <level>", description: "Choose cluster, indices or shards" },
+                        { flags: "--wait-for-status <status>", description: "Wait for green, yellow or red" },
+                        { flags: "--timeout <duration>", description: "Set the OpenSearch wait timeout" },
+                    ],
+                    view: recordView({ fields: [
+                            { label: "Cluster", value: value => value.cluster_name },
+                            { label: "Status", value: value => value.status },
+                            { label: "Timed out", value: value => value.timed_out },
+                            { label: "Nodes", value: value => value.number_of_nodes },
+                            { label: "Data nodes", value: value => value.number_of_data_nodes },
+                            { label: "Primary shards", value: value => value.active_primary_shards },
+                            { label: "Active shards", value: value => value.active_shards },
+                            { label: "Relocating", value: value => value.relocating_shards },
+                            { label: "Initializing", value: value => value.initializing_shards },
+                            { label: "Unassigned", value: value => value.unassigned_shards },
+                            { label: "Active %", value: value => value.active_shards_percent_as_number },
+                        ], sections: [{ title: () => "Indices", lines: value => value.indices ? Object.entries(value.indices).map(([name, index]) => `${name}: ${index.status}`) : undefined }] }),
+                }),
+            ]), command("indices", "Explore OpenSearch indices", [
+                command("list [pattern]", "List index health, counts and sizes", async ({ args, options }, context) => (await clientFor(context)).indices({ ...(args.pattern === undefined ? {} : { pattern: String(args.pattern) }), ...options }), {
+                    permission: "ReadOnly",
+                    options: [
+                        { flags: "--health <status>", description: "Select green, yellow or red indices" },
+                        { flags: "--include-hidden", description: "Include hidden and system indices" },
+                    ],
+                    view: tableView({ columns: [
+                            { header: "Name", value: row => row.name },
+                            { header: "Health", value: row => row.health },
+                            { header: "Status", value: row => row.status },
+                            { header: "Primaries", value: row => row.primaries },
+                            { header: "Replicas", value: row => row.replicas },
+                            { header: "Docs", value: row => row.docsCount },
+                            { header: "Store", value: row => row.storeBytes, format: "bytes" },
+                        ], empty: "No indices found." }),
+                }),
+                command("show <index>", "Show index settings, mappings and aliases", async ({ args, options }, context) => (await clientFor(context)).index(args.index, options.section), {
+                    permission: "ReadOnly", options: [{ flags: "--section <section>", description: "Select settings, mappings or aliases", parse: value => {
+                                if (!["settings", "mappings", "aliases"].includes(value))
+                                    throw new CliError("Section must be settings, mappings or aliases.", { code: "usage" });
+                                return value;
+                            } }],
+                }),
+            ]), command("aliases", "Explore index aliases", [
+                command("list [pattern]", "List alias targets and flags", async ({ args }, context) => (await clientFor(context)).aliases(args.pattern === undefined ? undefined : String(args.pattern)), {
+                    permission: "ReadOnly", view: tableView({ columns: [
+                            { header: "Alias", value: row => row.alias }, { header: "Index", value: row => row.index },
+                            { header: "Write", value: row => row.writeIndex }, { header: "Filter", value: row => row.hasFilter },
+                            { header: "Routing", value: row => row.hasRouting },
+                        ], empty: "No aliases found." }),
+                }),
+            ]), command("data-streams", "Explore data streams", [
+                command("list [pattern]", "List data stream metadata", async ({ args }, context) => (await clientFor(context)).dataStreams(args.pattern === undefined ? undefined : String(args.pattern)), {
+                    permission: "ReadOnly", view: tableView({ columns: [
+                            { header: "Name", value: row => row.name }, { header: "Timestamp", value: row => row.timestampField },
+                            { header: "Generation", value: row => row.generation }, { header: "Backing indices", value: row => row.backingIndexCount },
+                            { header: "Health", value: row => row.health },
+                        ], empty: "No data streams found." }),
+                }),
+            ]), command("fields", "Explore index fields", [
+                command("list <pattern>", "List field types and conflicts", async ({ args, options }, context) => (await clientFor(context)).fields(args.pattern, options), {
+                    permission: "ReadOnly", options: [
+                        { flags: "--type <type>", description: "Select fields containing this type" },
+                        { flags: "--filter <glob>", description: "Match field paths with * and ?" },
+                        { flags: "--include-meta", description: "Include reserved metadata fields" },
+                    ], view: tableView({ columns: [
+                            { header: "Field", value: row => row.name }, { header: "Types", value: row => row.types.join(", ") },
+                            { header: "Conflict", value: row => row.conflict },
+                            { header: "Indices by type", value: row => Object.entries(row.indicesByType).map(([type, indices]) => `${type}: ${indices.join(", ")}`).join("; ") },
+                        ], empty: "No fields found." }),
+                }),
+            ]), command("count <index>", "Count matching documents", async ({ args, options }, context) => {
+                if (options.q !== undefined && options.queryFile !== undefined)
+                    throw new CliError("Choose --q or --query-file.", { code: "usage" });
+                const result = await (await clientFor(context)).count(args.index, {
+                    ...(options.q === undefined ? {} : { q: String(options.q) }),
+                    ...(options.queryFile === undefined ? {} : { query: await readQuery(String(options.queryFile), context) }),
+                });
+                if (result.partial.failedShards) {
+                    const reasons = result.partial.failures.slice(0, 3).map(failure => failure.reason?.reason).filter(Boolean).join("; ").replace(/[\r\n\t]+/g, " ");
+                    const details = `${result.partial.failedShards}/${result.partial.totalShards} shards failed.${reasons ? " " + reasons : ""}`;
+                    if (options.failOnPartial)
+                        throw new CliError("The document count is partial.", { code: "search.partial", result, cause: new Error(details) });
+                    context.progress(`Warning: ${details}`);
+                }
+                return result;
+            }, { permission: "ReadOnly", options: [
+                    { flags: "--q <query>", description: "Match a Lucene query string" },
+                    { flags: "--query-file <path>", description: "Read Query DSL from file or -" },
+                    { flags: "--fail-on-partial", description: "Fail when any shard fails" },
+                ], view: recordView({ fields: [
+                        { label: "Count", value: value => value.count },
+                        { label: "Partial", value: value => value.partial.failedShards > 0 },
+                    ] }) })],
+    };
+}

package/dist/src/client.d.ts

@@ -0,0 +1,154 @@
+import { type CommandContext } from "@eyeauras/cli-factory";
+/** Wire metadata returned by the OpenSearch cluster information API. */
+export interface ClusterInfo {
+    name: string;
+    cluster_name: string;
+    cluster_uuid: string;
+    version: {
+        distribution?: string;
+        number: string;
+        build_hash?: string;
+        build_date?: string;
+        lucene_version?: string;
+    };
+}
+/** An observed health state; red health remains a successful read. */
+export interface ClusterHealth {
+    cluster_name: string;
+    status: string;
+    timed_out: boolean;
+    number_of_nodes: number;
+    number_of_data_nodes: number;
+    active_primary_shards: number;
+    active_shards: number;
+    relocating_shards: number;
+    initializing_shards: number;
+    unassigned_shards: number;
+    active_shards_percent_as_number: number;
+    indices?: Record<string, {
+        status: string;
+    }>;
+}
+/** Index statistics normalized from CAT cells; unavailable observations remain null. */
+export interface IndexSummary {
+    name: string;
+    health: string | null;
+    status: string;
+    primaries: number | null;
+    replicas: number | null;
+    docsCount: number | null;
+    /** Total primary and replica store size in bytes, never a human size string. */
+    storeBytes: number | null;
+}
+/** One alias-to-index relationship; routing and filtering expose presence only. */
+export interface AliasSummary {
+    alias: string;
+    index: string;
+    writeIndex: boolean | null;
+    hasFilter: boolean;
+    hasRouting: boolean;
+}
+/** A data stream's observed metadata, without document contents. */
+export interface DataStreamSummary {
+    name: string;
+    timestampField: string;
+    generation: number;
+    backingIndexCount: number;
+    health: string;
+}
+/** Selected index configuration; unavailable server defaults remain null. */
+export interface IndexSettings {
+    primaries: number | null;
+    replicas: number | null;
+    refreshInterval: string | null;
+    createdAt: string | null;
+    uuid: string | null;
+}
+/** Complete mapping and alias definitions belong to OpenSearch, not a CLI-specific schema. */
+export interface IndexInspection {
+    name: string;
+    settings: IndexSettings;
+    aliases: Record<string, unknown>;
+    mappings: Record<string, unknown>;
+}
+export type IndexSection = "settings" | "mappings" | "aliases";
+/** Field types and their concrete indices; a conflict retains every observed type. */
+export interface FieldSummary {
+    name: string;
+    types: string[];
+    conflict: boolean;
+    indicesByType: Record<string, string[]>;
+}
+/** Count observations retain shard evidence so incomplete counts cannot look exact. */
+export interface CountResult {
+    count: number;
+    _shards: {
+        total: number;
+        successful: number;
+        skipped?: number;
+        failed: number;
+        failures?: ShardFailure[];
+    };
+    partial: {
+        failedShards: number;
+        totalShards: number;
+        failures: ShardFailure[];
+    };
+}
+/** Selected shard identity and redacted diagnostics shared by every result/output path. */
+export interface ShardFailure {
+    shard?: number;
+    index?: string;
+    node?: string;
+    reason?: ShardFailureReason;
+}
+/** Supported OpenSearch cause structure; diagnostic strings use Core's redaction policy. */
+export interface ShardFailureReason {
+    type?: string;
+    reason?: string;
+    caused_by?: ShardFailureReason;
+    root_cause?: ShardFailureReason[];
+    suppressed?: ShardFailureReason[];
+}
+/** Invocation-owned transport; paths and status semantics belong to OpenSearch. */
+export declare class OpenSearchClient {
+    private readonly connection;
+    constructor(connection: {
+        url: string;
+        fetch: typeof fetch;
+        signal: AbortSignal;
+        authorization?: string;
+    });
+    private request;
+    info(): Promise<ClusterInfo>;
+    identity(): Promise<{
+        url: string;
+        reachable: true;
+        user?: string;
+        roles?: string[];
+    }>;
+    health(options: {
+        index?: string;
+        level?: string;
+        waitForStatus?: string;
+        timeout?: string;
+    }): Promise<ClusterHealth>;
+    indices(options: {
+        pattern?: string;
+        health?: string;
+        includeHidden?: boolean;
+    }): Promise<IndexSummary[]>;
+    aliases(pattern?: string): Promise<AliasSummary[]>;
+    dataStreams(pattern?: string): Promise<DataStreamSummary[]>;
+    index(index: string, section?: IndexSection): Promise<IndexInspection | IndexSettings | Record<string, unknown>>;
+    fields(pattern: string, options: {
+        type?: string;
+        filter?: string;
+        includeMeta?: boolean;
+    }): Promise<FieldSummary[]>;
+    count(index: string, options: {
+        q?: string;
+        query?: Record<string, unknown>;
+    }): Promise<CountResult>;
+}
+export declare function clientFor(context: CommandContext): Promise<OpenSearchClient>;

package/dist/src/client.js

@@ -0,0 +1,246 @@
+import { CliError, HttpError, diagnosticCause, fetchWithRedirects, readResponseBody } from "@eyeauras/cli-factory";
+function catCount(value) {
+    if (value === null)
+        return null;
+    if (typeof value === "string" && /^\d+$/.test(value) && Number.isSafeInteger(Number(value)))
+        return Number(value);
+    throw new CliError("OpenSearch returned an invalid index count or size.", { code: "opensearch.invalidResponse" });
+}
+function safeShardReason(reason) {
+    const safe = diagnosticCause(Object.assign(new Error(reason.reason ?? ""), { name: reason.type ?? "Error" }));
+    return {
+        ...(reason.type === undefined ? {} : { type: safe.name }),
+        ...(reason.reason === undefined ? {} : { reason: safe.message }),
+        ...(reason.caused_by === undefined ? {} : { caused_by: safeShardReason(reason.caused_by) }),
+        ...(reason.root_cause === undefined ? {} : { root_cause: reason.root_cause.map(safeShardReason) }),
+        ...(reason.suppressed === undefined ? {} : { suppressed: reason.suppressed.map(safeShardReason) }),
+    };
+}
+// Reserved mapper metadata, not a blanket underscore-prefix rule for user fields.
+const metadataFields = new Set(["_id", "_index", "_source", "_routing", "_ignored", "_field_names", "_version", "_seq_no", "_primary_term", "_size", "_doc_count", "_nested_path", "_tombstone", "_parent_join", "_data_stream_timestamp", "_feature"]);
+/** Invocation-owned transport; paths and status semantics belong to OpenSearch. */
+export class OpenSearchClient {
+    connection;
+    constructor(connection) {
+        this.connection = connection;
+    }
+    async request(path, accepted = [], body) {
+        const { url, fetch, signal, authorization } = this.connection;
+        const response = await fetchWithRedirects(fetch, new URL(path, url), {
+            signal, ...(body === undefined ? {} : { method: "POST", body: JSON.stringify(body) }),
+            headers: { accept: "application/json", ...(body === undefined ? {} : { "content-type": "application/json" }), ...(authorization ? { authorization } : {}) },
+        });
+        if (!response.ok && !accepted.includes(response.status)) {
+            await response.body?.cancel();
+            throw new HttpError(response.status, "OpenSearch rejected the request.");
+        }
+        const bytes = await readResponseBody(response, { signal });
+        let value;
+        try {
+            value = JSON.parse(new TextDecoder().decode(bytes));
+        }
+        catch (cause) {
+            throw new CliError("OpenSearch returned an invalid JSON response.", { code: "opensearch.invalidResponse", cause: diagnosticCause(cause, [], "Response JSON could not be decoded.") });
+        }
+        return { status: response.status, value };
+    }
+    async info() {
+        const { value } = await this.request("");
+        if (!value || typeof value.cluster_name !== "string" || typeof value.cluster_uuid !== "string" || typeof value.version?.number !== "string")
+            throw new CliError("OpenSearch returned incomplete cluster metadata.", { code: "opensearch.invalidResponse" });
+        return value;
+    }
+    async identity() {
+        await this.info();
+        const base = { url: this.connection.url, reachable: true };
+        try {
+            const { value } = await this.request("_plugins/_security/authinfo");
+            return {
+                ...base,
+                ...(typeof value?.user_name === "string" ? { user: value.user_name } : {}),
+                ...(Array.isArray(value?.roles) ? { roles: value.roles } : {}),
+            };
+        }
+        catch (error) {
+            if (error instanceof HttpError && [403, 404].includes(error.status))
+                return base;
+            throw error;
+        }
+    }
+    async health(options) {
+        const query = new URLSearchParams();
+        for (const [key, value] of [["level", options.level], ["wait_for_status", options.waitForStatus], ["timeout", options.timeout]])
+            if (value !== undefined)
+                query.set(key, value);
+        const path = "_cluster/health" + (options.index === undefined ? "" : "/" + encodeURIComponent(options.index)) + (query.size ? "?" + query : "");
+        const { status, value } = await this.request(path, [408]);
+        if (!value || typeof value.status !== "string" || typeof value.timed_out !== "boolean")
+            throw new CliError("OpenSearch returned incomplete cluster health.", { code: "opensearch.invalidResponse" });
+        if (value.timed_out)
+            throw new CliError("OpenSearch timed out waiting for cluster health.", { code: "opensearch.healthTimeout", result: value });
+        if (status === 408)
+            throw new HttpError(status, "OpenSearch rejected the health request.");
+        return value;
+    }
+    async indices(options) {
+        const pattern = encodeURIComponent(options.pattern ?? "*");
+        const query = new URLSearchParams({
+            format: "json", bytes: "b", h: "index,health,status,pri,rep,docs.count,store.size",
+            expand_wildcards: options.includeHidden ? "all" : "open,closed", allow_no_indices: "true",
+        });
+        if (options.health !== undefined)
+            query.set("health", options.health);
+        const { value } = await this.request(`_cat/indices/${pattern}?${query}`);
+        if (!Array.isArray(value))
+            throw new CliError("OpenSearch returned an invalid index list.", { code: "opensearch.invalidResponse" });
+        let rows = value.map(row => {
+            if (!row || typeof row.index !== "string" || typeof row.health !== "string" || typeof row.status !== "string")
+                throw new CliError("OpenSearch returned incomplete index metadata.", { code: "opensearch.invalidResponse" });
+            return {
+                name: row.index, health: row.health || null, status: row.status,
+                primaries: catCount(row.pri), replicas: catCount(row.rep), docsCount: catCount(row["docs.count"]), storeBytes: catCount(row["store.size"]),
+            };
+        });
+        if (!options.includeHidden && rows.length) {
+            // CAT has no system classification before 3.9. Metadata also handles explicit hidden names.
+            const classificationQuery = new URLSearchParams({
+                filter_path: "metadata.indices.*.system,metadata.indices.*.settings.index.hidden",
+                expand_wildcards: "all", allow_no_indices: "true",
+            });
+            const { value: classification } = await this.request(`_cluster/state/metadata/${pattern}?${classificationQuery}`);
+            rows = rows.filter(row => {
+                const metadata = classification?.metadata?.indices?.[row.name];
+                if (typeof metadata?.system !== "boolean")
+                    throw new CliError("OpenSearch returned incomplete index classification.", { code: "opensearch.invalidResponse" });
+                return !metadata.system && metadata.settings?.index?.hidden !== "true";
+            });
+        }
+        return rows.sort((a, b) => a.name < b.name ? -1 : a.name > b.name ? 1 : 0);
+    }
+    async aliases(pattern = "*") {
+        const query = new URLSearchParams({ format: "json", h: "alias,index,is_write_index,filter,routing.index,routing.search" });
+        const { value } = await this.request(`_cat/aliases/${encodeURIComponent(pattern)}?${query}`);
+        return value.map(row => ({ alias: row.alias, index: row.index, writeIndex: row.is_write_index === "-" ? null : row.is_write_index === "true",
+            hasFilter: row.filter === "*", hasRouting: row["routing.index"] !== "-" || row["routing.search"] !== "-" }))
+            .sort((a, b) => a.alias.localeCompare(b.alias) || a.index.localeCompare(b.index));
+    }
+    async dataStreams(pattern = "*") {
+        const { status, value } = await this.request(`_data_stream/${encodeURIComponent(pattern)}`, [404]);
+        if (status === 404) {
+            if (value.error?.type === "resource_not_found_exception")
+                return [];
+            throw new HttpError(status, "OpenSearch rejected the data stream request.");
+        }
+        return value.data_streams.map(stream => ({ name: stream.name, timestampField: stream.timestamp_field.name,
+            generation: stream.generation, backingIndexCount: stream.indices.length, health: stream.status.toLowerCase() }))
+            .sort((a, b) => a.name.localeCompare(b.name));
+    }
+    async index(index, section) {
+        const path = encodeURIComponent(index) + (section === "settings" ? "/_settings" : section === "mappings" ? "/_mapping" : "");
+        let value;
+        try {
+            ({ value } = await this.request(path + (section === "mappings" ? "" : "?flat_settings=false&include_defaults=true")));
+        }
+        catch (cause) {
+            if (cause instanceof HttpError && cause.status === 404)
+                throw new CliError("The index was not found.", { code: "index.notFound", cause, next: [["indices", "list"]] });
+            throw cause;
+        }
+        const names = Object.keys(value);
+        if (names.length !== 1)
+            throw new CliError("Select one concrete index.", { code: "usage", next: [["indices", "list"]] });
+        const name = names[0];
+        const item = value[name];
+        if (section === "mappings")
+            return item.mappings ?? {};
+        if (section === "aliases")
+            return item.aliases ?? {};
+        const wire = { ...item.defaults?.index, ...item.settings?.index };
+        const settings = {
+            primaries: catCount(wire.number_of_shards ?? null), replicas: catCount(wire.number_of_replicas ?? null),
+            refreshInterval: wire.refresh_interval ?? null, uuid: wire.uuid ?? null,
+            createdAt: wire.creation_date === undefined ? null : new Date(Number(wire.creation_date)).toISOString(),
+        };
+        return section === "settings" ? settings : { name, settings, aliases: item.aliases ?? {}, mappings: item.mappings ?? {} };
+    }
+    async fields(pattern, options) {
+        const path = encodeURIComponent(pattern);
+        const { value: mappings } = await this.request(`${path}/_mapping?allow_no_indices=true`);
+        const { value: capabilities } = await this.request(`${path}/_field_caps?fields=*&allow_no_indices=true&include_unmapped=true`);
+        const grouped = new Map();
+        const walk = (properties, prefix, index) => {
+            for (const [key, node] of Object.entries(properties)) {
+                const name = prefix + key;
+                const type = node.type ?? "object";
+                const types = grouped.get(name) ?? new Map();
+                const indices = types.get(type) ?? new Set();
+                indices.add(index);
+                types.set(type, indices);
+                grouped.set(name, types);
+                if (node.properties)
+                    walk(node.properties, name + ".", index);
+                if (node.fields)
+                    walk(node.fields, name + ".", index);
+            }
+        };
+        for (const [index, mapping] of Object.entries(mappings))
+            walk(mapping.mappings.properties ?? {}, "", index);
+        const declared = new Set(grouped.keys());
+        for (const [name, caps] of Object.entries(capabilities.fields)) {
+            const mapped = grouped.get(name);
+            const types = Object.keys(caps).filter(type => type !== "unmapped");
+            const allMapped = mapped ? [...new Set([...mapped.values()].flatMap(indices => [...indices]))] : capabilities.indices;
+            const merged = new Map(types.map(type => [type, new Set(caps[type].indices ?? (types.length === 1 ? allMapped : [...mapped?.get(type) ?? []]))]));
+            // Capabilities discover object parents from indexed children; disabled/empty objects need mapping evidence.
+            for (const [type, indices] of mapped ?? [])
+                if (type === "object" || type === "nested") {
+                    const members = merged.get(type) ?? new Set();
+                    for (const index of indices)
+                        members.add(index);
+                    merged.set(type, members);
+                }
+            grouped.set(name, merged);
+        }
+        const filter = options.filter === undefined ? undefined : new RegExp("^" + options.filter.replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/\*/g, ".*").replace(/\?/g, ".") + "$");
+        return [...grouped].sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0)
+            .filter(([name, types]) => (options.includeMeta || declared.has(name) || !metadataFields.has(name)) && (!options.type || types.has(options.type)) && (!filter || filter.test(name)))
+            .map(([name, groups]) => {
+            const types = [...groups.keys()].sort();
+            return { name, types, conflict: types.length > 1, indicesByType: Object.fromEntries(types.map(type => [type, [...groups.get(type)].sort()])) };
+        });
+    }
+    async count(index, options) {
+        if (options.q !== undefined && options.query !== undefined)
+            throw new CliError("Choose --q or --query-file.", { code: "usage" });
+        const query = options.q === undefined ? "" : "?" + new URLSearchParams({ q: options.q });
+        const { value } = await this.request(`${encodeURIComponent(index)}/_count${query}`, [], options.query === undefined ? undefined : { query: options.query });
+        if (!Number.isSafeInteger(value?.count) || value.count < 0 || !Number.isSafeInteger(value._shards?.total) || !Number.isSafeInteger(value._shards?.failed))
+            throw new CliError("OpenSearch returned incomplete count metadata.", { code: "opensearch.invalidResponse" });
+        const failures = (value._shards.failures ?? []).map(failure => ({
+            ...(failure.shard === undefined ? {} : { shard: failure.shard }),
+            ...(failure.index === undefined ? {} : { index: failure.index }),
+            ...(failure.node === undefined ? {} : { node: failure.node }),
+            ...(failure.reason === undefined ? {} : { reason: safeShardReason(failure.reason) }),
+        }));
+        const shards = { total: value._shards.total, successful: value._shards.successful, failed: value._shards.failed,
+            ...(value._shards.skipped === undefined ? {} : { skipped: value._shards.skipped }),
+            ...(value._shards.failures === undefined ? {} : { failures }) };
+        return { count: value.count, _shards: shards, partial: { failedShards: shards.failed, totalShards: shards.total, failures } };
+    }
+}
+export async function clientFor(context) {
+    const scheme = context.profile.values.auth;
+    let authorization;
+    if (scheme !== "none") {
+        const credential = await context.secrets.get(scheme === "bearer" ? "token" : "basic");
+        if (!credential)
+            throw new CliError("Sign in before querying OpenSearch.", { code: "auth.missing", next: [["auth", "login", "--help"]] });
+        if (scheme === "bearer")
+            authorization = "Bearer " + credential;
+        else {
+            const basic = JSON.parse(credential);
+            authorization = "Basic " + Buffer.from(`${basic.username}:${basic.password}`).toString("base64");
+        }
+    }
+    return new OpenSearchClient({ url: String(context.profile.values.url), fetch: context.fetch, signal: context.signal, ...(authorization ? { authorization } : {}) });
+}

package/dist/src/index.d.ts

@@ -0,0 +1 @@
+export { createDefinition } from "./cli.js";

package/dist/src/index.js

@@ -0,0 +1 @@
+export { createDefinition } from "./cli.js";

package/dist/src/query.d.ts

@@ -0,0 +1,3 @@
+import { type CommandContext } from "@eyeauras/cli-factory";
+/** Reads a Query DSL query object; stdin must be fresh and is reserved by RPC sessions. */
+export declare function readQuery(file: string, context: CommandContext): Promise<Record<string, unknown>>;

package/dist/src/query.js

@@ -0,0 +1,33 @@
+import { readFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import { addAbortSignal } from "node:stream";
+import { text } from "node:stream/consumers";
+import { CliError, diagnosticCause, jsonParser } from "@eyeauras/cli-factory";
+/** Reads a Query DSL query object; stdin must be fresh and is reserved by RPC sessions. */
+export async function readQuery(file, context) {
+    let source;
+    try {
+        if (file === "-") {
+            if (context.io.input.readableDidRead)
+                throw new CliError("Use a query file when stdin is already in use.", { code: "usage" });
+            source = await text(addAbortSignal(context.signal, context.io.input));
+        }
+        else
+            source = await readFile(resolve(context.cwd, file), { encoding: "utf8", signal: context.signal });
+    }
+    catch (cause) {
+        if (cause instanceof CliError)
+            throw cause;
+        throw new CliError("Could not read the query input.", { code: "query.readFailed", cause: diagnosticCause(cause) });
+    }
+    let query;
+    try {
+        query = jsonParser("Query input must contain valid JSON.")(source);
+    }
+    catch (cause) {
+        throw new CliError("Could not parse the query input.", { code: "query.invalid", cause });
+    }
+    if (!query || typeof query !== "object" || Array.isArray(query))
+        throw new CliError("Query input must contain a Query DSL query object.", { code: "query.invalid" });
+    return query;
+}

package/dist/src/version.d.ts

@@ -0,0 +1 @@
+export declare const version = "0.1.0";

package/dist/src/version.js

@@ -0,0 +1 @@
+export const version = "0.1.0";

package/package.json

@@ -1,6 +1,52 @@
 {
   "name": "@eyeauras/opensearch-cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Explore and manage OpenSearch clusters",
+  "type": "module",
+  "license": "MIT",
+  "engines": {
+    "node": ">=22"
+  },
+  "packageManager": "npm@11.21.1",
+  "bin": {
+    "opensearch-cli": "./dist/src/bin.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/src/index.d.ts",
+      "import": "./dist/src/index.js"
+    }
+  },
+  "files": [
+    "dist/src",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/iXab3r/opensearch-cli.git"
+  },
+  "homepage": "https://github.com/iXab3r/opensearch-cli#readme",
+  "bugs": {
+    "url": "https://github.com/iXab3r/opensearch-cli/issues"
+  },
+  "scripts": {
+    "build": "tsc --project tsconfig.json",
+    "test": "npm run build && node --test dist/tests/*.test.js",
+    "start": "node dist/src/bin.js",
+    "test:package": "node scripts/test-package.mjs",
+    "test:registry": "node scripts/test-registry.mjs",
+    "proof": "npm run build && node scripts/proof.mjs"
+  },
+  "dependencies": {
+    "@eyeauras/cli-factory": "0.5.3"
+  },
+  "devDependencies": {
+    "typescript": "7.0.2",
+    "@types/node": "24.19.2",
+    "msw": "3.0.3"
+  }
+}