arkiv-cli 0.0.0-stage → 0.1.0

package/dist/commands/cost.js

@@ -0,0 +1,144 @@
+/**
+ * `arkiv cost` - the pre-flight sizing check.
+ *
+ * Arkiv charges for storage at write time and the exact fee is whatever the
+ * create transaction consumes, so this command does not invent a price. What it
+ * does is the part people get wrong: work out how many bytes and blocks a write
+ * really needs, whether it fits the protocol limits, how many creates that takes,
+ * and what the chain is charging for gas right now.
+ */
+import { statSync, readFileSync } from "node:fs";
+import { explainError } from "../arkiv.js";
+import { BLOCK_SECONDS, MAX_ATTRIBUTES, MAX_BYTES_LENGTH, MAX_ENTITY_BYTES, MAX_LIFETIME, } from "../limits.js";
+import { bold, cyan, dim, formatDuration, green, grey, out, red, table, yellow } from "../ui.js";
+/** Rough per-attribute framing: name, type byte, length prefix, index flag. */
+const ATTRIBUTE_OVERHEAD = 40;
+export function parseLifetime(input, fallbackDays) {
+    if (!input)
+        return fallbackDays;
+    const match = /^(\d+(?:\.\d+)?)([smhdwy])$/.exec(input.trim());
+    if (!match) {
+        throw new Error(`cannot read lifetime "${input}"; use a number with s, m, h, d, w or y (for example 30d)`);
+    }
+    const value = Number(match[1]);
+    const unit = match[2];
+    const days = {
+        s: value / 86_400,
+        m: value / 1_440,
+        h: value / 24,
+        d: value,
+        w: value * 7,
+        y: value * 365,
+    }[unit];
+    return days ?? value;
+}
+export async function runCost(ctx, options) {
+    let payloadBytes = options.bytes;
+    let fileNote = "";
+    if (options.file) {
+        try {
+            const info = statSync(options.file);
+            payloadBytes = info.size;
+            fileNote = options.file;
+            // Read a little of it so an unreadable file fails here rather than mid-write.
+            readFileSync(options.file, { flag: "r" });
+        }
+        catch (error) {
+            out(red(`cannot read ${options.file}: ${error.message}`));
+            process.exitCode = 1;
+            return;
+        }
+    }
+    const attributeBytes = options.attributes * ATTRIBUTE_OVERHEAD + options.attributes * options.averageAttributeBytes;
+    const perCreate = payloadBytes + attributeBytes;
+    const creates = Math.max(1, Math.ceil(perCreate / MAX_ENTITY_BYTES));
+    const largestCreate = Math.min(perCreate, MAX_ENTITY_BYTES);
+    const blocks = Math.round(options.lifetimeDays * 86_400 / BLOCK_SECONDS);
+    const fits = {
+        attributes: options.attributes <= MAX_ATTRIBUTES - 1,
+        bytes: payloadBytes <= MAX_BYTES_LENGTH,
+        lifetime: blocks <= MAX_LIFETIME,
+    };
+    let gasPrice = null;
+    let gasNote = "unavailable";
+    try {
+        gasPrice = await ctx.client().getGasPrice();
+        gasNote = `${(Number(gasPrice) / 1e9).toFixed(4)} gwei`;
+    }
+    catch (error) {
+        gasNote = explainError(error);
+    }
+    if (ctx.json) {
+        process.stdout.write(`${JSON.stringify({
+            file: fileNote || null,
+            payloadBytes,
+            attributeBytes,
+            bytesPerCreate: perCreate,
+            creates,
+            lifetimeDays: options.lifetimeDays,
+            blocks,
+            fits,
+            gasPriceWei: gasPrice ? gasPrice.toString() : null,
+        }, null, 2)}\n`);
+        return;
+    }
+    out(bold("storage plan"));
+    out(table(["ITEM", "VALUE", "LIMIT", "STATUS"], [
+        [
+            "attributes",
+            String(options.attributes),
+            String(MAX_ATTRIBUTES - 1),
+            fits.attributes ? green("fits") : red("over"),
+        ],
+        [
+            "payload",
+            formatBytes(payloadBytes),
+            formatBytes(MAX_BYTES_LENGTH),
+            fits.bytes ? green("fits") : yellow("needs chunking"),
+        ],
+        [
+            "bytes per entity",
+            formatBytes(perCreate),
+            formatBytes(MAX_ENTITY_BYTES),
+            perCreate <= MAX_ENTITY_BYTES ? green("fits") : yellow(`${creates} creates`),
+        ],
+        [
+            "lifetime",
+            `${formatDuration(options.lifetimeDays * 86_400)} (${blocks.toLocaleString("en-US")} blocks)`,
+            `${formatDuration(MAX_LIFETIME * BLOCK_SECONDS)}`,
+            fits.lifetime ? green("fits") : red("over"),
+        ],
+    ]));
+    out();
+    out(`${grey("largest create ")} ${formatBytes(largestCreate)}`);
+    out(`${grey("gas price     ")} ${gasNote} ${dim("(live, mainnet-style read)")}`);
+    out(dim("the fee itself is what the create transaction burns; extension costs depend on remaining lifetime, " +
+        "so measure it with `arkiv create --dry-run` against your own access key"));
+    if (!fits.lifetime) {
+        out();
+        out(yellow(`shrink the lifetime to ${formatDuration(MAX_LIFETIME * BLOCK_SECONDS)} or less, or chain extensions`));
+    }
+    if (!fits.attributes) {
+        out();
+        out(yellow("drop an attribute or move related fields into one bytes payload"));
+    }
+}
+export function formatBytes(bytes) {
+    if (bytes < 1024)
+        return `${bytes} B`;
+    if (bytes < 1024 * 1024)
+        return `${(bytes / 1024).toFixed(1)} KiB`;
+    return `${(bytes / (1024 * 1024)).toFixed(1)} MiB`;
+}
+export function describeLimits() {
+    return table(["LIMIT", "VALUE", "NOTE"], [
+        ["attributes per entity", `${MAX_ATTRIBUTES} (${MAX_ATTRIBUTES - 1} + schema)`, "arkiv.schema counts as one"],
+        ["bytes per entity", formatBytes(MAX_ENTITY_BYTES), "sum of all bytes values"],
+        ["single bytes attribute", formatBytes(MAX_BYTES_LENGTH), "chunk larger payloads"],
+        ["entity lifetime", `${MAX_LIFETIME.toLocaleString("en-US")} blocks`, formatDuration(MAX_LIFETIME * BLOCK_SECONDS)],
+        ["block time", `${BLOCK_SECONDS}s`, "used for expiry maths"],
+    ]);
+}
+export function limitSummary() {
+    return `${cyan(String(MAX_ATTRIBUTES))} attributes, ${cyan(formatBytes(MAX_ENTITY_BYTES))} per entity, ${cyan(String(MAX_LIFETIME))} blocks lifetime`;
+}

package/dist/commands/create.d.ts

@@ -0,0 +1,27 @@
+/**
+ * `arkiv create` - write one entity from the terminal.
+ *
+ * The SDK only writes through a typed schema, so this command builds one at
+ * runtime from the flags you pass, then refuses anything the schema or the
+ * protocol limits would reject. `--dry-run` prints the exact plan without
+ * signing anything.
+ */
+import type { Context } from "../context.js";
+export type ValueTypeName = "str" | "bytes" | "u64" | "i32" | "u256" | "bool" | "addr" | "key" | "dec";
+export declare const VALUE_TYPES: ValueTypeName[];
+export interface CreateOptions {
+    schema: string;
+    sets: string[];
+    indexed: string[];
+    expires?: string;
+    dryRun: boolean;
+}
+export interface ParsedAttribute {
+    name: string;
+    type: ValueTypeName;
+    raw: string;
+    value: unknown;
+    bytes: number;
+}
+export declare function parseAttribute(input: string): ParsedAttribute;
+export declare function runCreate(ctx: Context, options: CreateOptions): Promise<void>;

package/dist/commands/create.js

@@ -0,0 +1,239 @@
+/**
+ * `arkiv create` - write one entity from the terminal.
+ *
+ * The SDK only writes through a typed schema, so this command builds one at
+ * runtime from the flags you pass, then refuses anything the schema or the
+ * protocol limits would reject. `--dry-run` prints the exact plan without
+ * signing anything.
+ */
+import { readFileSync } from "node:fs";
+import { ExpirationTime } from "@arkiv-network/sdk";
+import { addr, bool as boolValue, bytes as bytesValue, dec, i32, key as keyValue, str, u64, u256, } from "@arkiv-network/sdk";
+import { addr as addrColumn, bool as boolColumn, bytes as bytesColumn, dec as decColumn, defineSchema, i32 as i32Column, key as keyColumn, str as strColumn, u64 as u64Column, u256 as u256Column, } from "@arkiv-network/sdk/schema";
+import { explainError, makeWallet, takeNotice } from "../arkiv.js";
+import { MAX_ATTRIBUTES, MAX_BYTES_LENGTH, MAX_LIFETIME, BLOCK_SECONDS } from "../limits.js";
+import { formatBytes, parseLifetime } from "./cost.js";
+import { bold, cyan, dim, green, grey, out, red, table } from "../ui.js";
+export const VALUE_TYPES = ["str", "bytes", "u64", "i32", "u256", "bool", "addr", "key", "dec"];
+const COLUMNS = {
+    str: strColumn,
+    bytes: bytesColumn,
+    u64: u64Column,
+    i32: i32Column,
+    u256: u256Column,
+    bool: boolColumn,
+    addr: addrColumn,
+    key: keyColumn,
+    dec: decColumn,
+};
+export function parseAttribute(input) {
+    const eq = input.indexOf("=");
+    if (eq < 1)
+        throw new Error(`expected name=type:value, got "${input}"`);
+    const name = input.slice(0, eq).trim();
+    const rest = input.slice(eq + 1);
+    const colon = rest.indexOf(":");
+    if (colon < 1)
+        throw new Error(`missing type for "${name}"; use ${name}=str:hello`);
+    const type = rest.slice(0, colon).trim();
+    const raw = rest.slice(colon + 1);
+    if (!VALUE_TYPES.includes(type)) {
+        throw new Error(`unknown value type "${type}" for ${name}; use one of ${VALUE_TYPES.join(", ")}`);
+    }
+    if (name.length === 0 || Buffer.byteLength(name, "utf8") > 32) {
+        throw new Error(`attribute name "${name}" is empty or over 32 bytes`);
+    }
+    if (name === "arkiv.schema") {
+        throw new Error("arkiv.schema is set by --schema, not by --set");
+    }
+    let value;
+    let bytes;
+    switch (type) {
+        case "str": {
+            const encoded = Buffer.byteLength(raw, "utf8");
+            if (encoded > 128)
+                throw new Error(`${name} is ${encoded} bytes of text; str caps at 128, use bytes:.path`);
+            value = str(raw);
+            bytes = encoded;
+            break;
+        }
+        case "bytes": {
+            const data = readPayload(raw);
+            if (data.byteLength > MAX_BYTES_LENGTH) {
+                throw new Error(`${name} is ${formatBytes(data.byteLength)}; one bytes attribute caps at ${formatBytes(MAX_BYTES_LENGTH)}`);
+            }
+            value = bytesValue(data);
+            bytes = data.byteLength;
+            break;
+        }
+        case "u64":
+            value = u64(BigInt(raw));
+            bytes = 8;
+            break;
+        case "i32":
+            value = i32(Number.parseInt(raw, 10));
+            bytes = 4;
+            break;
+        case "u256":
+            value = u256(BigInt(raw));
+            bytes = 32;
+            break;
+        case "bool":
+            if (!/^(true|false)$/.test(raw))
+                throw new Error(`${name} must be true or false`);
+            value = boolValue(raw === "true");
+            bytes = 1;
+            break;
+        case "addr":
+            if (!/^0x[0-9a-fA-F]{40}$/.test(raw))
+                throw new Error(`${name} is not a 20-byte address: ${raw}`);
+            value = addr(raw);
+            bytes = 20;
+            break;
+        case "key":
+            if (!/^0x[0-9a-fA-F]{64}$/.test(raw))
+                throw new Error(`${name} is not a 32-byte key: ${raw}`);
+            value = keyValue(raw);
+            bytes = 32;
+            break;
+        case "dec":
+            value = dec(raw);
+            bytes = 32;
+            break;
+        default:
+            throw new Error(`unsupported type ${type}`);
+    }
+    return { name, type, raw, value, bytes };
+}
+function readPayload(raw) {
+    const path = raw.startsWith("@") ? raw.slice(1) : raw.startsWith("./") || raw.startsWith("/") ? raw : null;
+    if (path) {
+        try {
+            return new Uint8Array(readFileSync(path));
+        }
+        catch (error) {
+            throw new Error(`cannot read ${path}: ${error.message}`);
+        }
+    }
+    if (/^0x[0-9a-fA-F]*$/.test(raw)) {
+        const hex = raw.slice(2);
+        if (hex.length % 2 !== 0)
+            throw new Error("hex bytes must have an even number of digits");
+        return new Uint8Array(Buffer.from(hex, "hex"));
+    }
+    throw new Error('bytes values take a file path (@./file or ./file) or 0x-prefixed hex');
+}
+export async function runCreate(ctx, options) {
+    if (!/^[A-Za-z0-9][A-Za-z0-9._/-]{0,31}$/.test(options.schema)) {
+        out(red(`schema "${options.schema}" is not a valid name`));
+        out(dim("1 to 32 bytes of letters, digits, dot, slash, dash or underscore, starting with a letter or digit"));
+        process.exitCode = 2;
+        return;
+    }
+    let attributes;
+    try {
+        attributes = options.sets.map(parseAttribute);
+    }
+    catch (error) {
+        out(red(error.message));
+        process.exitCode = 2;
+        return;
+    }
+    const seen = new Set();
+    for (const attribute of attributes) {
+        if (seen.has(attribute.name)) {
+            out(red(`attribute ${attribute.name} is set twice`));
+            process.exitCode = 2;
+            return;
+        }
+        seen.add(attribute.name);
+    }
+    if (attributes.length + 1 > MAX_ATTRIBUTES) {
+        out(red(`${attributes.length} attributes plus arkiv.schema exceeds the limit of ${MAX_ATTRIBUTES}`));
+        out(dim("the schema attribute counts as one of them"));
+        process.exitCode = 2;
+        return;
+    }
+    const indexed = new Set(options.indexed);
+    for (const name of indexed) {
+        if (!seen.has(name)) {
+            out(red(`--index ${name} does not match any --set attribute`));
+            process.exitCode = 2;
+            return;
+        }
+    }
+    let lifetimeDays;
+    try {
+        lifetimeDays = parseLifetime(options.expires, 30);
+    }
+    catch (error) {
+        out(red(error.message));
+        process.exitCode = 2;
+        return;
+    }
+    const blocks = Math.round((lifetimeDays * 86_400) / BLOCK_SECONDS);
+    if (blocks > MAX_LIFETIME) {
+        out(red(`lifetime ${lifetimeDays}d is past the ${MAX_LIFETIME.toLocaleString("en-US")} block maximum`));
+        process.exitCode = 2;
+        return;
+    }
+    const totalBytes = attributes.reduce((sum, attribute) => sum + attribute.bytes, 0);
+    const columns = {};
+    const values = {};
+    for (const attribute of attributes) {
+        const build = COLUMNS[attribute.type];
+        let column = build();
+        if (indexed.has(attribute.name))
+            column = column.isIndexed();
+        columns[attribute.name] = column;
+        values[attribute.name] = attribute.value;
+    }
+    if (ctx.json) {
+        process.stdout.write(`${JSON.stringify({
+            schema: options.schema,
+            attributes: attributes.map((a) => ({ name: a.name, type: a.type, bytes: a.bytes, indexed: indexed.has(a.name) })),
+            totalBytes,
+            lifetimeDays,
+            blocks,
+            dryRun: options.dryRun,
+        }, null, 2)}\n`);
+        if (options.dryRun)
+            return;
+    }
+    else {
+        out(bold("create plan"));
+        out(table(["FIELD", "TYPE", "BYTES", "INDEXED"], attributes.map((a) => [a.name, cyan(a.type), String(a.bytes), indexed.has(a.name) ? green("yes") : grey("no")])));
+        out();
+        out(`${grey("schema   ")} ${options.schema}`);
+        out(`${grey("payload  ")} ${formatBytes(totalBytes)} ${dim(`of ${formatBytes(131072)} per entity`)}`);
+        out(`${grey("lifetime ")} ${lifetimeDays}d ${dim(`(${blocks.toLocaleString("en-US")} blocks)`)}`);
+    }
+    if (options.dryRun) {
+        out(dim("dry run: nothing was signed or sent"));
+        return;
+    }
+    if (!ctx.privateKey) {
+        out(red("no private key found, so this cannot be signed"));
+        out(dim("add ARKIV_PRIVATE_KEY to .env, then run `arkiv doctor`"));
+        process.exitCode = 1;
+        return;
+    }
+    const schema = defineSchema(options.schema, columns);
+    try {
+        const { client, account } = makeWallet({ network: ctx.network, accessKey: ctx.accessKey, rpcUrl: ctx.rpcUrl }, ctx.privateKey);
+        out(dim(`signing as ${account.address}`));
+        const result = await client.createEntity(schema, values, { expiration: ExpirationTime.fromBlocks(blocks) });
+        const notice = takeNotice();
+        if (notice)
+            out(dim(notice));
+        out(green("written"));
+        out(`${grey("key      ")} ${result.entityKey}`);
+        out(`${grey("tx       ")} ${result.txHash}`);
+        out(`${grey("expires  ")} block ${Number(result.expiresAt).toLocaleString("en-US")}`);
+    }
+    catch (error) {
+        out(red("write failed"));
+        out(dim(explainError(error)));
+        process.exitCode = 1;
+    }
+}

package/dist/commands/doctor.d.ts

@@ -0,0 +1,23 @@
+/**
+ * `arkiv doctor` - the first thing a new developer should run.
+ *
+ * Every check answers one question: will a write to Rabdi work from this
+ * machine, right now? Failures carry the exact command or URL that fixes them.
+ */
+import type { Context } from "../context.js";
+type Status = "ok" | "warn" | "fail";
+interface Check {
+    id: string;
+    status: Status;
+    detail: string;
+    fix?: string;
+}
+export interface DoctorOptions {
+    fixPerms?: boolean;
+}
+export declare function runDoctor(ctx: Context, options?: DoctorOptions): Promise<{
+    checks: Check[];
+    ok: boolean;
+}>;
+export declare function printDoctor(checks: Check[], json: boolean): void;
+export {};

package/dist/commands/doctor.js

@@ -0,0 +1,190 @@
+/**
+ * `arkiv doctor` - the first thing a new developer should run.
+ *
+ * Every check answers one question: will a write to Rabdi work from this
+ * machine, right now? Failures carry the exact command or URL that fixes them.
+ */
+import { privateKeyToAccount } from "viem/accounts";
+import { resolveChain, explainError, getTiming } from "../arkiv.js";
+import { envIsGitIgnored, tightenPermissions, validateAccessKey, validatePrivateKey } from "../env.js";
+import { bold, cyan, dim, green, grey, out, red, yellow } from "../ui.js";
+const MIN_NODE = [22, 10];
+const MARK = {
+    ok: green("OK  "),
+    warn: yellow("WARN"),
+    fail: red("FAIL"),
+};
+function nodeCheck() {
+    const [major, minor] = process.versions.node.split(".").map(Number);
+    const ok = major > MIN_NODE[0] || (major === MIN_NODE[0] && minor >= MIN_NODE[1]);
+    return {
+        id: "node",
+        status: ok ? "ok" : "fail",
+        detail: `v${process.versions.node} ${ok ? "" : `(need >= ${MIN_NODE.join(".")})`}`.trim(),
+        fix: ok ? undefined : "Install a current Node.js LTS from https://nodejs.org",
+    };
+}
+export async function runDoctor(ctx, options = {}) {
+    const checks = [nodeCheck()];
+    /* ---------------------------------------------------------------- env file */
+    if (!ctx.envFile.exists) {
+        checks.push({
+            id: "env",
+            status: "warn",
+            detail: `no .env at ${ctx.envFile.path}`,
+            fix: "Run `arkiv init` or create .env with ARKIV_ACCESS_KEY and ARKIV_PRIVATE_KEY",
+        });
+    }
+    else {
+        const mode = (ctx.envFile.mode ?? 0).toString(8).padStart(3, "0");
+        if (ctx.envFile.tooOpen) {
+            const fixed = options.fixPerms ? tightenPermissions(ctx.envFile.path) : false;
+            checks.push({
+                id: "env",
+                status: fixed ? "ok" : "warn",
+                detail: fixed ? `.env tightened to 600` : `.env is readable by other users (mode ${mode})`,
+                fix: fixed ? undefined : "chmod 600 .env  (or re-run with --fix-perms)",
+            });
+        }
+        else {
+            checks.push({ id: "env", status: "ok", detail: `.env mode ${mode}` });
+        }
+    }
+    /* ---------------------------------------------------------------- access key */
+    const access = validateAccessKey(ctx.accessKey);
+    checks.push({
+        id: "access-key",
+        status: access.ok ? "ok" : "warn",
+        detail: access.ok
+            ? "ARKIV_ACCESS_KEY set"
+            : "not set - queries go to the shared, rate-limited endpoint",
+        fix: access.ok ? undefined : "Get a free key at https://hub.arkiv.network/access-keys",
+    });
+    /* ---------------------------------------------------------------- signer */
+    let address = null;
+    const key = validatePrivateKey(ctx.privateKey);
+    if (!ctx.privateKey) {
+        checks.push({
+            id: "signer",
+            status: "warn",
+            detail: "ARKIV_PRIVATE_KEY not set (read-only: query/schema/watch still work)",
+            fix: "Add ARKIV_PRIVATE_KEY to .env, then fund it from https://hub.arkiv.network/faucet",
+        });
+    }
+    else if (!key.ok) {
+        checks.push({ id: "signer", status: "fail", detail: key.reason });
+    }
+    else {
+        try {
+            address = privateKeyToAccount(key.normalized).address;
+            checks.push({ id: "signer", status: "ok", detail: address });
+        }
+        catch {
+            checks.push({ id: "signer", status: "fail", detail: "ARKIV_PRIVATE_KEY is not a valid secp256k1 key" });
+        }
+    }
+    /* ---------------------------------------------------------------- transport */
+    let timing = null;
+    let chainId = 0;
+    try {
+        const chain = resolveChain({ network: ctx.network, accessKey: ctx.accessKey, rpcUrl: ctx.rpcUrl });
+        chainId = chain.id;
+        const started = Date.now();
+        const client = ctx.client();
+        const remoteId = await client.getChainId();
+        const latency = Date.now() - started;
+        if (remoteId !== chain.id) {
+            checks.push({
+                id: "rpc",
+                status: "fail",
+                detail: `endpoint is chain ${remoteId}, expected ${chain.id} (${ctx.network})`,
+                fix: "Check --rpc / ARKIV_RPC_URL, or drop the override to use the default endpoint",
+            });
+        }
+        else {
+            checks.push({
+                id: "rpc",
+                status: "ok",
+                detail: `${chain.rpcUrls.default.http[0]} (${latency} ms)`,
+            });
+        }
+        timing = await getTiming(client);
+        if (!timing)
+            throw new Error("the node returned no block timing");
+        checks.push({
+            id: "chain",
+            status: "ok",
+            detail: `${ctx.network} id ${chainId}, block ${timing.currentBlock.toLocaleString("en-US")}, ${timing.blockDuration}s blocks`,
+        });
+        const skew = Math.abs(Date.now() / 1000 - timing.currentBlockTime);
+        checks.push({
+            id: "clock",
+            status: skew < 120 ? "ok" : "warn",
+            detail: skew < 120
+                ? `local clock within ${skew.toFixed(0)}s of chain time`
+                : `local clock differs from chain by ${(skew / 60).toFixed(1)} min`,
+            fix: skew < 120 ? undefined : "Enable automatic time sync on this machine",
+        });
+        if (address) {
+            const balance = await client.getBalance({ address });
+            const glm = Number(balance) / 1e18;
+            checks.push({
+                id: "balance",
+                status: glm <= 0 ? "fail" : glm < 0.05 ? "warn" : "ok",
+                detail: `${glm.toFixed(4)} tGLM ${symbol(ctx)}`,
+                fix: glm <= 0.05 ? "Top up at https://hub.arkiv.network/faucet" : undefined,
+            });
+        }
+        const qStart = Date.now();
+        const probe = await client
+            .select({ $key: true })
+            .where("EXISTS(arkiv.schema)")
+            .limit(1)
+            .fetch();
+        checks.push({
+            id: "query",
+            status: "ok",
+            detail: `smoke query ok in ${Date.now() - qStart} ms (${probe.entities.length} row)`,
+        });
+    }
+    catch (error) {
+        checks.push({ id: "rpc", status: "fail", detail: explainError(error) });
+    }
+    /* ---------------------------------------------------------------- hygiene */
+    const ignored = envIsGitIgnored(ctx.cwd);
+    checks.push({
+        id: "gitignore",
+        status: ignored === false ? "fail" : ignored ? "ok" : "warn",
+        detail: ignored === true
+            ? ".env is covered by .gitignore"
+            : ignored === false
+                ? ".env is NOT ignored by git - a commit here leaks your key"
+                : "no .gitignore in this directory",
+        fix: ignored === true ? undefined : "Add `.env` to .gitignore",
+    });
+    return {
+        checks,
+        ok: !checks.some((c) => c.status === "fail"),
+    };
+}
+function symbol(ctx) {
+    const chain = resolveChain({ network: ctx.network, accessKey: ctx.accessKey, rpcUrl: ctx.rpcUrl });
+    return chain.nativeCurrency?.symbol ?? "tGLM";
+}
+export function printDoctor(checks, json) {
+    if (json) {
+        process.stdout.write(`${JSON.stringify({ ok: !checks.some((c) => c.status === "fail"), checks }, null, 2)}\n`);
+        return;
+    }
+    const width = Math.max(...checks.map((c) => c.id.length));
+    for (const check of checks) {
+        out(`${MARK[check.status]}  ${bold(check.id.padEnd(width))}  ${check.detail}`);
+        if (check.fix)
+            out(`      ${dim(" ".repeat(width))}  ${grey("-> " + check.fix)}`);
+    }
+    const fail = checks.filter((c) => c.status === "fail").length;
+    const warn = checks.filter((c) => c.status === "warn").length;
+    const ok = checks.filter((c) => c.status === "ok").length;
+    out();
+    out(`${green(`${ok} ok`)}${warn ? `, ${yellow(`${warn} warn`)}` : ""}${fail ? `, ${red(`${fail} fail`)}` : ""}  ${dim(`${cyan("rabdi")} - https://hub.arkiv.network for keys and faucet`)}`);
+}

package/dist/commands/entity.d.ts

@@ -0,0 +1,7 @@
+/**
+ * `arkiv entity <key>` - read one entity and print everything the node returns.
+ * Attribute values are untrusted bytes, so every string goes through sanitize()
+ * before it reaches the terminal.
+ */
+import type { Context } from "../context.js";
+export declare function runEntity(ctx: Context, rawKey: string): Promise<void>;