arkiv-cli 0.0.0-stage → 0.1.0

package/dist/commands/schema.js

@@ -0,0 +1,397 @@
+/**
+ * `arkiv schema` - discover what is actually on the network, and lint the
+ * naming/structure mistakes that make a schema hard to find six months later.
+ *
+ * Discovery works by sampling: the query language has no "list schemas" call,
+ * so the CLI pages through entities that carry an arkiv.schema attribute,
+ * ordered by key so pages are stable while others write.
+ */
+import { asc } from "@arkiv-network/sdk/query";
+import { schemaOf } from "../render.js";
+import { getTiming } from "../arkiv.js";
+import { attributeSize, entityFootprint } from "../values.js";
+import { MAX_ATTRIBUTES, MAX_ENTITY_BYTES, MAX_STRING_BYTES } from "../limits.js";
+import { bold, cyan, dim, field, formatDate, formatDuration, green, grey, out, red, table, yellow, } from "../ui.js";
+import { blockToUnix } from "../arkiv.js";
+export async function sampleSchemas(ctx, options) {
+    const client = ctx.client();
+    const schemas = new Map();
+    const pageSize = 100;
+    const target = Math.max(pageSize, Math.min(options.sample, 1000));
+    let scanned = 0;
+    let block = 0;
+    for (let offset = 0; offset < target; offset += pageSize) {
+        const page = await client
+            .select({
+            $key: true,
+            $owner: true,
+            $expiresAt: true,
+            $attributeSchema: true,
+            $attributes: true,
+        })
+            .where("EXISTS(arkiv.schema)")
+            .orderBy(asc("$key"))
+            .limit(pageSize)
+            .offset(offset)
+            .fetch();
+        block = Number(page.blockNumber);
+        const entities = page.entities;
+        for (const entity of entities) {
+            scanned += 1;
+            const name = schemaOf(entity);
+            if (!name)
+                continue;
+            absorbEntity(schemas, entity);
+        }
+        if (entities.length < pageSize)
+            break;
+    }
+    return { schemas, scanned, block };
+}
+/**
+ * Records one entity into the schema map.
+ *
+ * Shared by the broad sample and the targeted lookup, so a schema's shape is
+ * computed the same way whether it was found by scanning or by asking for it.
+ */
+function absorbEntity(schemas, entity) {
+    const name = schemaOf(entity);
+    if (!name)
+        return;
+    let summary = schemas.get(name);
+    if (!summary) {
+        summary = {
+            name,
+            entities: 0,
+            owners: [],
+            fields: new Map(),
+            typeConflicts: new Set(),
+            earliestExpiry: Number.POSITIVE_INFINITY,
+        };
+        schemas.set(name, summary);
+    }
+    summary.entities += 1;
+    if (entity.$owner && !summary.owners.includes(entity.$owner)) {
+        if (summary.owners.length < 8)
+            summary.owners.push(entity.$owner);
+    }
+    const expiry = Number(entity.$expiresAt ?? 0);
+    if (expiry > 0 && expiry < summary.earliestExpiry)
+        summary.earliestExpiry = expiry;
+    const declared = (entity.$attributeSchema ?? {});
+    const attributes = (entity.$attributes ?? {});
+    const footprint = entityFootprint(attributes);
+    for (const [field, meta] of Object.entries(declared)) {
+        const existing = summary.fields.get(field);
+        if (!existing) {
+            summary.fields.set(field, {
+                type: meta.type,
+                indexed: Boolean(meta.indexed),
+                maxStringBytes: 0,
+                maxEntityBytes: footprint,
+            });
+        }
+        else if (existing.type !== meta.type) {
+            summary.typeConflicts.add(field);
+        }
+        const value = attributes[field];
+        const size = attributeSize(value);
+        const current = summary.fields.get(field);
+        current.maxEntityBytes = Math.max(current.maxEntityBytes, footprint);
+        if (meta.type === "str")
+            current.maxStringBytes = Math.max(current.maxStringBytes, size);
+    }
+}
+export function lintSchema(summary) {
+    const findings = [];
+    const name = summary.name;
+    const bytes = Buffer.byteLength(name, "utf8");
+    if (bytes > 32) {
+        findings.push({
+            severity: "error",
+            rule: "name-length",
+            message: `name is ${bytes} bytes; the limit is 32`,
+        });
+    }
+    if (!/^[A-Za-z0-9][A-Za-z0-9._/-]*$/.test(name)) {
+        findings.push({
+            severity: "warn",
+            rule: "name-charset",
+            message: "name has characters outside letters, digits, dot, slash, dash, underscore",
+        });
+    }
+    if (!/[./]/.test(name)) {
+        findings.push({
+            severity: "warn",
+            rule: "namespace",
+            message: "flat name: no namespace, so it collides with anyone else's schema",
+        });
+    }
+    if (!/v\d+(\b|\/|\.|$)/.test(name)) {
+        findings.push({
+            severity: "warn",
+            rule: "versioning",
+            message: "no version segment; add /v1 so a format change can coexist",
+        });
+    }
+    if (summary.typeConflicts.size > 0) {
+        findings.push({
+            severity: "error",
+            rule: "type-drift",
+            message: `same attribute written with different types: ${[...summary.typeConflicts].join(", ")}`,
+        });
+    }
+    if (summary.fields.size > MAX_ATTRIBUTES) {
+        findings.push({
+            severity: "error",
+            rule: "attribute-count",
+            message: `${summary.fields.size} attributes; the limit is ${MAX_ATTRIBUTES}`,
+        });
+    }
+    for (const [field, info] of summary.fields) {
+        if (info.type === "str" && info.maxStringBytes > MAX_STRING_BYTES) {
+            findings.push({
+                severity: "error",
+                rule: "string-length",
+                message: `${field} holds ${info.maxStringBytes} bytes of text; the limit is ${MAX_STRING_BYTES}`,
+            });
+        }
+        if (info.maxEntityBytes > MAX_ENTITY_BYTES) {
+            findings.push({
+                severity: "error",
+                rule: "entity-size",
+                message: `a sampled entity is ${info.maxEntityBytes} bytes; the limit is ${MAX_ENTITY_BYTES}`,
+            });
+        }
+    }
+    if (summary.owners.length > 1) {
+        findings.push({
+            severity: "info",
+            rule: "shared-owner",
+            message: `${summary.owners.length}+ different signers write this schema`,
+        });
+    }
+    return findings;
+}
+export function worst(findings) {
+    if (findings.some((f) => f.severity === "error"))
+        return "error";
+    if (findings.some((f) => f.severity === "warn"))
+        return "warn";
+    if (findings.length)
+        return "info";
+    return null;
+}
+/* ------------------------------------------------------------------ listing */
+export async function runSchemaList(ctx, options) {
+    const { schemas, scanned, block } = await sampleSchemas(ctx, options);
+    const ordered = [...schemas.values()].sort((a, b) => b.entities - a.entities);
+    if (ctx.json) {
+        const payload = {
+            scanned,
+            block,
+            note: "counts are from a sample, not a registry",
+            schemas: ordered.map((s) => ({
+                name: s.name,
+                entities: s.entities,
+                signers: s.owners.length,
+                fields: [...s.fields.entries()].map(([field, info]) => ({
+                    name: field,
+                    type: info.type,
+                    indexed: info.indexed,
+                })),
+                findings: lintSchema(s),
+            })),
+        };
+        process.stdout.write(`${JSON.stringify(payload, null, 2)}\n`);
+        return;
+    }
+    const rows = ordered.map((s) => {
+        const findings = lintSchema(s);
+        const level = worst(findings);
+        const note = level === "error"
+            ? red(`${findings.filter((f) => f.severity === "error").length} error(s)`)
+            : level === "warn"
+                ? yellow(`${findings.length} warning(s)`)
+                : level === "info"
+                    ? grey("note")
+                    : green("clean");
+        return [
+            s.name,
+            String(s.owners.length),
+            String(s.entities),
+            String(s.fields.size),
+            note,
+        ];
+    });
+    out(dim(`sampled ${scanned} entities at block ${block.toLocaleString("en-US")}`));
+    out(table(["SCHEMA", "SIGNERS", "ENTITIES", "FIELDS", "LINT"], rows));
+    out();
+    out(dim("counts are sample-based; run `arkiv schema <name>` for the fields and findings behind a row"));
+}
+/* ------------------------------------------------------------------ detail */
+/**
+ * Reads one schema directly.
+ *
+ * `schema` listings come from a broad sample, which can miss a schema that sits
+ * deep in the keyspace. Asking for an explicit schema should not depend on a
+ * lucky sample, so this queries the schema itself.
+ */
+export async function collectSchema(ctx, name, limit = 200) {
+    const client = ctx.client();
+    const schemas = new Map();
+    const pageSize = 100;
+    const literal = name.replace(/\\/g, "\\\\").replace(/'/g, "\\'");
+    for (let offset = 0; offset < limit; offset += pageSize) {
+        const page = await client
+            .select({
+            $key: true,
+            $owner: true,
+            $expiresAt: true,
+            $attributeSchema: true,
+            $attributes: true,
+        })
+            .where(`arkiv.schema = str('${literal}')`)
+            .orderBy(asc("$key"))
+            .limit(pageSize)
+            .offset(offset)
+            .fetch();
+        const entities = page.entities;
+        for (const entity of entities)
+            absorbEntity(schemas, entity);
+        if (entities.length < pageSize)
+            break;
+    }
+    return schemas.get(name) ?? null;
+}
+export async function runSchemaDetail(ctx, name) {
+    const summary = await collectSchema(ctx, name);
+    if (!summary) {
+        out(red(`no entities found for schema "${name}" in the sample`));
+        out(dim("try `arkiv schema` to list what is actually on this network"));
+        process.exitCode = 1;
+        return;
+    }
+    const findings = lintSchema(summary);
+    let timing = null;
+    try {
+        timing = await getTiming(ctx.client());
+    }
+    catch {
+        /* optional */
+    }
+    if (ctx.json) {
+        process.stdout.write(`${JSON.stringify({
+            name: summary.name,
+            entities: summary.entities,
+            signers: summary.owners,
+            earliestExpiry: summary.earliestExpiry,
+            fields: [...summary.fields.entries()].map(([field, info]) => ({
+                name: field,
+                type: info.type,
+                indexed: info.indexed,
+                maxStringBytes: info.maxStringBytes,
+            })),
+            findings,
+        }, null, 2)}\n`);
+        return;
+    }
+    out(`${bold(summary.name)}`);
+    out(field("entities", String(summary.entities)));
+    out(field("signers", `${summary.owners.length}`));
+    if (timing && summary.earliestExpiry !== Number.POSITIVE_INFINITY) {
+        out(field("expires", `${formatDate(blockToUnix(timing, summary.earliestExpiry))} ${dim(`(worst case, in ${formatDuration(blockToUnix(timing, summary.earliestExpiry) - Date.now() / 1000)})`)}`));
+    }
+    out();
+    const fields = [...summary.fields.entries()].map(([field, info]) => [
+        field,
+        info.type,
+        info.indexed ? "indexed" : "-",
+        info.type === "str" ? `${info.maxStringBytes} B` : "",
+    ]);
+    out(table(["FIELD", "TYPE", "QUERYABLE", "MAX VALUE"], fields));
+    out();
+    if (findings.length === 0) {
+        out(green("no naming or structure findings"));
+    }
+    else {
+        const mark = { error: red("ERROR"), warn: yellow("WARN "), info: cyan("INFO ") };
+        for (const finding of findings) {
+            out(`${mark[finding.severity]} ${bold(finding.rule)}  ${finding.message}`);
+        }
+    }
+}
+/* ------------------------------------------------------------------ atlas */
+export function renderAtlas(schemas, meta) {
+    const ordered = [...schemas.values()].sort((a, b) => b.entities - a.entities);
+    const cards = ordered
+        .map((s) => {
+        const findings = lintSchema(s);
+        const level = worst(findings);
+        const badge = level === "error" ? "bad-error" : level === "warn" ? "bad-warn" : level === "info" ? "bad-info" : "bad-ok";
+        const label = level === "error" ? "needs fixing" : level === "warn" ? "review" : level === "info" ? "note" : "clean";
+        const fields = [...s.fields.entries()]
+            .map(([field, info]) => `<li><code>${escapeHtml(field)}</code><span class="type">${escapeHtml(info.type)}</span>${info.indexed ? '<span class="idx">indexed</span>' : ""}</li>`)
+            .join("");
+        const notes = findings
+            .map((f) => `<li class="f ${f.severity}">${escapeHtml(f.message)}</li>`)
+            .join("");
+        return `<article class="card">
+  <header><h2>${escapeHtml(s.name)}</h2><span class="badge ${badge}">${label}</span></header>
+  <p class="meta">${s.entities} entities &middot; ${s.owners.length} signer(s) &middot; ${s.fields.size} fields</p>
+  <ul class="fields">${fields}</ul>
+  ${notes ? `<ul class="findings">${notes}</ul>` : ""}
+</article>`;
+    })
+        .join("\n");
+    return `<!doctype html>
+<html lang="en"><head><meta charset="utf-8">
+<meta name="viewport" content="width=device-width,initial-scale=1">
+<title>Schema Atlas - ${escapeHtml(meta.network)}</title>
+<style>
+  :root { color-scheme: dark; --bg:#0b0d10; --panel:#14181d; --line:#252b33; --text:#e8eaed; --muted:#8b939e; --accent:#7fd1b9; --warn:#e5b95c; --error:#e2705f; --info:#7aa8e0; }
+  * { box-sizing:border-box; }
+  body { margin:0; background:var(--bg); color:var(--text); font:15px/1.5 ui-sans-serif,system-ui,-apple-system,Segoe UI,Roboto,sans-serif; }
+  main { max-width:1120px; margin:0 auto; padding:48px 24px 80px; }
+  h1 { font-size:34px; margin:0 0 6px; letter-spacing:-.02em; }
+  .sub { color:var(--muted); margin:0 0 32px; }
+  .grid { display:grid; grid-template-columns:repeat(auto-fill,minmax(320px,1fr)); gap:16px; }
+  .card { background:var(--panel); border:1px solid var(--line); border-radius:14px; padding:18px; }
+  .card header { display:flex; justify-content:space-between; align-items:flex-start; gap:12px; }
+  h2 { font-size:16px; margin:0; word-break:break-word; font-family:ui-monospace,SFMono-Regular,Menlo,monospace; }
+  .badge { font-size:11px; text-transform:uppercase; letter-spacing:.08em; padding:3px 8px; border-radius:999px; white-space:nowrap; }
+  .bad-ok { background:rgba(127,209,185,.14); color:var(--accent); }
+  .bad-warn { background:rgba(229,185,92,.14); color:var(--warn); }
+  .bad-error { background:rgba(226,112,95,.16); color:var(--error); }
+  .bad-info { background:rgba(122,168,224,.14); color:var(--info); }
+  .meta { color:var(--muted); font-size:13px; margin:8px 0 12px; }
+  ul { list-style:none; margin:0; padding:0; }
+  .fields li { display:flex; gap:8px; align-items:baseline; padding:4px 0; border-bottom:1px dashed var(--line); font-size:13px; }
+  .fields li:last-child { border-bottom:0; }
+  code { font-family:ui-monospace,SFMono-Regular,Menlo,monospace; font-size:13px; }
+  .type { color:var(--muted); }
+  .idx { font-size:10px; color:var(--accent); border:1px solid rgba(127,209,185,.4); border-radius:4px; padding:0 4px; }
+  .findings { margin-top:12px; border-top:1px solid var(--line); padding-top:10px; }
+  .f { font-size:12px; color:var(--muted); padding-left:14px; position:relative; }
+  .f::before { content:"-"; position:absolute; left:0; }
+  .f.error { color:var(--error); }
+  .f.warn { color:var(--warn); }
+  footer { color:var(--muted); font-size:12px; margin-top:40px; }
+</style></head>
+<body><main>
+<h1>Schema Atlas</h1>
+<p class="sub">${escapeHtml(meta.network)} &middot; ${ordered.length} schemas in a sample of ${meta.scanned} entities &middot; block ${meta.block.toLocaleString("en-US")}</p>
+<p class="sub">Generated by <code>arkiv schema --atlas</code>. Counts describe a sample, not a registry.</p>
+<div class="grid">
+${cards}
+</div>
+<footer>Built By Harish Kotra &middot; harishkotra.me</footer>
+</main></body></html>`;
+}
+function escapeHtml(input) {
+    return input
+        .replace(/&/g, "&amp;")
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;")
+        .replace(/"/g, "&quot;");
+}

package/dist/commands/watch.d.ts

@@ -0,0 +1,16 @@
+/**
+ * `arkiv watch` - poll a query and print entities as they appear.
+ *
+ * The query language exposes $createdAt only as a projection, so there is no
+ * block cursor to resume from. Instead the CLI keeps a bounded, deterministically
+ * ordered window (ordered by key) and diffs it each tick. If the window fills up
+ * the CLI says so, because a full window means new entities could land outside it.
+ */
+import type { Context } from "../context.js";
+export interface WatchOptions {
+    expression: string;
+    limit: number;
+    intervalSeconds: number;
+    once: boolean;
+}
+export declare function runWatch(ctx: Context, options: WatchOptions): Promise<void>;

package/dist/commands/watch.js

@@ -0,0 +1,124 @@
+/**
+ * `arkiv watch` - poll a query and print entities as they appear.
+ *
+ * The query language exposes $createdAt only as a projection, so there is no
+ * block cursor to resume from. Instead the CLI keeps a bounded, deterministically
+ * ordered window (ordered by key) and diffs it each tick. If the window fills up
+ * the CLI says so, because a full window means new entities could land outside it.
+ */
+import { asc } from "@arkiv-network/sdk/query";
+import { renderEntities, schemaOf } from "../render.js";
+import { explainError, getTiming, blockToUnix } from "../arkiv.js";
+import { displayValue } from "../values.js";
+import { cyan, dim, green, grey, out, red, sanitize, yellow } from "../ui.js";
+async function snapshot(ctx, expression, limit) {
+    const client = ctx.client();
+    const collected = [];
+    const pageSize = 100;
+    for (let offset = 0; offset < limit; offset += pageSize) {
+        const take = Math.min(pageSize, limit - offset);
+        const page = await client
+            .select({
+            $key: true,
+            $owner: true,
+            $expiresAt: true,
+            $attributeSchema: true,
+            $attributes: true,
+        })
+            .where(expression)
+            .orderBy(asc("$key"))
+            .limit(take)
+            .offset(offset)
+            .fetch();
+        const entities = page.entities;
+        collected.push(...entities);
+        if (entities.length < take)
+            break;
+    }
+    return collected;
+}
+function summarise(entity) {
+    const attributes = (entity.$attributes ?? {});
+    const schema = schemaOf(entity) ?? "untyped";
+    const parts = Object.entries(attributes)
+        .filter(([name]) => name !== "arkiv.schema")
+        .slice(0, 3)
+        .map(([name, value]) => `${grey(name)}=${sanitize(displayValue(value, 48))}`);
+    return `${cyan(schema)} ${dim(entity.$key.slice(0, 12))}… ${parts.join(" ")}`;
+}
+export async function runWatch(ctx, options) {
+    const limit = Math.max(1, Math.min(options.limit, 1000));
+    const interval = Math.max(1, options.intervalSeconds) * 1000;
+    let previous = new Map();
+    let timing = null;
+    try {
+        timing = await getTiming(ctx.client());
+    }
+    catch {
+        /* timestamps degrade to block numbers, which is still useful */
+    }
+    const stamp = (entity) => {
+        if (timing && entity.$createdAt) {
+            return formatClock(blockToUnix(timing, Number(entity.$createdAt)));
+        }
+        return entity.$createdAt ? `block ${Number(entity.$createdAt)}` : "now";
+    };
+    const first = await snapshot(ctx, options.expression, limit);
+    for (const entity of first)
+        previous.set(entity.$key, entity);
+    if (options.once) {
+        out(renderEntities(first, timing, {}));
+        out(dim(`${first.length} matching ${first.length === 1 ? "entity" : "entities"} at ${new Date().toISOString()}`));
+        return;
+    }
+    out(dim(`${first.length} existing matching ${first.length === 1 ? "entity" : "entities"}; ` +
+        `watching every ${interval / 1000}s (ctrl-c to stop)`));
+    if (first.length >= limit) {
+        out(yellow(`the window is full at ${limit} rows, so new entities outside the key window can be missed; raise --limit`));
+    }
+    let stopping = false;
+    const stop = () => {
+        stopping = true;
+        out(dim("\nstopped"));
+    };
+    process.once("SIGINT", stop);
+    process.once("SIGTERM", stop);
+    while (!stopping) {
+        await sleep(interval);
+        if (stopping)
+            break;
+        let current;
+        try {
+            current = await snapshot(ctx, options.expression, limit);
+        }
+        catch (error) {
+            out(red(`poll failed: ${explainError(error)}`));
+            continue;
+        }
+        const next = new Map(current.map((entity) => [entity.$key, entity]));
+        let changes = 0;
+        for (const [key, entity] of next) {
+            if (previous.has(key))
+                continue;
+            changes += 1;
+            out(`${green("+")} ${grey(stamp(entity))} ${summarise(entity)}`);
+        }
+        for (const [key, entity] of previous) {
+            if (next.has(key))
+                continue;
+            changes += 1;
+            out(`${red("-")} ${grey(stamp(entity))} ${summarise(entity)}`);
+        }
+        previous = next;
+        if (ctx.verbose && changes === 0) {
+            out(dim(`no changes at ${new Date().toISOString()}`));
+        }
+    }
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function formatClock(unix) {
+    const date = new Date(unix * 1000);
+    return `${String(date.getHours()).padStart(2, "0")}:${String(date.getMinutes()).padStart(2, "0")}:${String(date.getSeconds()).padStart(2, "0")}`;
+}

package/dist/context.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Shared command context: one environment, one client, no globals.
+ */
+import { type EnvFile } from "./env.js";
+import { type ArkivPublic } from "./arkiv.js";
+export interface GlobalFlags {
+    json: boolean;
+    colour: boolean;
+    network?: string;
+    rpc?: string;
+    env?: string;
+    verbose: boolean;
+}
+export interface Context {
+    cwd: string;
+    envFile: EnvFile;
+    accessKey: string;
+    privateKey: string;
+    network: string;
+    rpcUrl?: string;
+    json: boolean;
+    verbose: boolean;
+    client: () => ArkivPublic;
+}
+export declare function buildContext(flags: GlobalFlags, cwd?: string): Context;

package/dist/context.js

@@ -0,0 +1,31 @@
+/**
+ * Shared command context: one environment, one client, no globals.
+ */
+import path from "node:path";
+import { readEnvFile, readSecret } from "./env.js";
+import { makeClient } from "./arkiv.js";
+export function buildContext(flags, cwd = process.cwd()) {
+    const envPath = flags.env ? path.resolve(cwd, flags.env) : path.join(cwd, ".env");
+    const envFile = readEnvFile(envPath);
+    const accessKey = readSecret("ARKIV_ACCESS_KEY", envFile);
+    /* ARKIV_PRIVATE_KEY is the documented name; PRIVATE_KEY is kept as an alias */
+    const privateKey = readSecret("ARKIV_PRIVATE_KEY", envFile) ?? readSecret("PRIVATE_KEY", envFile);
+    const network = flags.network ?? process.env.ARKIV_NETWORK ?? "rabdi";
+    const rpcUrl = flags.rpc ?? process.env.ARKIV_RPC_URL ?? undefined;
+    let cached = null;
+    return {
+        cwd,
+        envFile,
+        accessKey,
+        privateKey,
+        network,
+        rpcUrl,
+        json: Boolean(flags.json),
+        verbose: Boolean(flags.verbose),
+        client: () => {
+            if (!cached)
+                cached = makeClient({ network, accessKey, rpcUrl });
+            return cached;
+        },
+    };
+}

package/dist/env.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Environment handling for the CLI.
+ *
+ * The rule this module enforces: credentials are read, validated and passed to
+ * the SDK, but never returned to a caller that prints them. Values are
+ * registered with the redactor as soon as they are read.
+ */
+export interface EnvFile {
+    path: string;
+    exists: boolean;
+    values: Record<string, string>;
+    /** True when group or world bits are set on the file. */
+    tooOpen: boolean;
+    mode: number | null;
+}
+/** Minimal dotenv parser. No expansion, no shell evaluation, no surprises. */
+export declare function parseDotenv(text: string): Record<string, string>;
+export declare function readEnvFile(file: string): EnvFile;
+/**
+ * Lookup order: a real environment variable wins, then .env in the working
+ * directory. This matches how the SDK and most deployment platforms behave.
+ */
+export declare function readSecret(name: string, env: EnvFile): string;
+export type KeyCheck = {
+    ok: true;
+    normalized: `0x${string}`;
+} | {
+    ok: false;
+    reason: string;
+};
+/** Validate a secp256k1 private key without ever echoing it. */
+export declare function validatePrivateKey(raw: string): KeyCheck;
+export declare function validateAccessKey(raw: string): {
+    ok: boolean;
+    reason?: string;
+};
+/**
+ * Credentials travel in a request header. Sending them over plain http to a
+ * remote host would leak them to anyone on the path, so only https (or a
+ * loopback address) is accepted.
+ */
+export declare function assertSafeRpcUrl(raw: string): {
+    ok: true;
+    url: string;
+} | {
+    ok: false;
+    reason: string;
+};
+/** True when .env appears to be covered by the repository's .gitignore. */
+export declare function envIsGitIgnored(dir: string): boolean | null;
+export declare function tightenPermissions(file: string): boolean;