arkiv-cli 0.0.0-stage → 0.1.0

package/dist/env.js

@@ -0,0 +1,136 @@
+/**
+ * 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.
+ */
+import { existsSync, readFileSync, statSync, chmodSync } from "node:fs";
+import path from "node:path";
+import { registerSecret } from "./ui.js";
+/** Minimal dotenv parser. No expansion, no shell evaluation, no surprises. */
+export function parseDotenv(text) {
+    const values = {};
+    for (const rawLine of text.split(/\r?\n/)) {
+        const line = rawLine.trim();
+        if (!line || line.startsWith("#"))
+            continue;
+        const eq = line.indexOf("=");
+        if (eq <= 0)
+            continue;
+        let key = line.slice(0, eq).trim();
+        if (key.startsWith("export "))
+            key = key.slice(7).trim();
+        if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(key))
+            continue;
+        let value = line.slice(eq + 1).trim();
+        if ((value.startsWith('"') && value.endsWith('"') && value.length > 1) ||
+            (value.startsWith("'") && value.endsWith("'") && value.length > 1)) {
+            value = value.slice(1, -1);
+        }
+        else {
+            const hash = value.indexOf(" #");
+            if (hash >= 0)
+                value = value.slice(0, hash).trim();
+        }
+        values[key] = value;
+        registerSecret(values[key]);
+    }
+    return values;
+}
+export function readEnvFile(file) {
+    if (!existsSync(file)) {
+        return { path: file, exists: false, values: {}, tooOpen: false, mode: null };
+    }
+    const mode = statSync(file).mode & 0o777;
+    const values = parseDotenv(readFileSync(file, "utf8"));
+    return { path: file, exists: true, values, tooOpen: (mode & 0o077) !== 0, mode };
+}
+/**
+ * Lookup order: a real environment variable wins, then .env in the working
+ * directory. This matches how the SDK and most deployment platforms behave.
+ */
+export function readSecret(name, env) {
+    const fromProcess = process.env[name];
+    const value = (fromProcess && fromProcess.trim()) || env.values[name] || "";
+    registerSecret(value);
+    return value.trim();
+}
+/** Validate a secp256k1 private key without ever echoing it. */
+export function validatePrivateKey(raw) {
+    if (!raw)
+        return { ok: false, reason: "ARKIV_PRIVATE_KEY is not set" };
+    const body = raw.startsWith("0x") ? raw.slice(2) : raw;
+    if (!/^[0-9a-fA-F]{64}$/.test(body)) {
+        return {
+            ok: false,
+            reason: "ARKIV_PRIVATE_KEY must be 64 hexadecimal characters (with or without 0x)",
+        };
+    }
+    if (/^0+$/.test(body))
+        return { ok: false, reason: "ARKIV_PRIVATE_KEY is all zeros" };
+    return { ok: true, normalized: `0x${body}` };
+}
+export function validateAccessKey(raw) {
+    if (!raw)
+        return { ok: false, reason: "ARKIV_ACCESS_KEY is not set" };
+    if (raw.length < 8)
+        return { ok: false, reason: "ARKIV_ACCESS_KEY looks too short" };
+    if (/\s/.test(raw))
+        return { ok: false, reason: "ARKIV_ACCESS_KEY contains whitespace" };
+    if (!/^[\x20-\x7e]+$/.test(raw)) {
+        return { ok: false, reason: "ARKIV_ACCESS_KEY contains non-printable characters" };
+    }
+    return { ok: true };
+}
+/**
+ * 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 function assertSafeRpcUrl(raw) {
+    let url;
+    try {
+        url = new URL(raw);
+    }
+    catch {
+        return { ok: false, reason: "RPC URL is not a valid absolute URL" };
+    }
+    const loopback = ["localhost", "127.0.0.1", "::1", "[::1]"].includes(url.hostname);
+    if (url.protocol === "https:")
+        return { ok: true, url: url.toString() };
+    if (url.protocol === "http:" && loopback)
+        return { ok: true, url: url.toString() };
+    return {
+        ok: false,
+        reason: `refusing to send credentials over ${url.protocol} to ${url.hostname}; use https or a loopback host`,
+    };
+}
+/** True when .env appears to be covered by the repository's .gitignore. */
+export function envIsGitIgnored(dir) {
+    const gitignore = path.join(dir, ".gitignore");
+    if (!existsSync(gitignore))
+        return null;
+    const lines = readFileSync(gitignore, "utf8")
+        .split(/\r?\n/)
+        .map((l) => l.trim())
+        .filter((l) => l && !l.startsWith("#"));
+    return lines.some((pattern) => {
+        const p = pattern.replace(/^!/, "").replace(/^\//, "").replace(/\/$/, "");
+        return (p === ".env" ||
+            p === ".env*" ||
+            p === "*.env" ||
+            p === ".env.*" ||
+            p === "/.env" ||
+            p.endsWith("/.env"));
+    });
+}
+export function tightenPermissions(file) {
+    try {
+        chmodSync(file, 0o600);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Library surface, so the same helpers are usable from a script:
+ *
+ *   import { makeClient, runQuery } from "arkiv-cli";
+ *
+ * The CLI is the product; this module exists so people can script against the
+ * exact same connection and redaction behaviour instead of re-deriving it.
+ */
+export { main } from "./cli.js";
+export { buildContext, type Context, type GlobalFlags } from "./context.js";
+export { makeClient, makeWallet, getTiming, blockToUnix, unixToBlock, explainError, networkNames, NETWORKS, type Timing, type ArkivPublic } from "./arkiv.js";
+export { parseArgs, UsageError, type Parsed, type FlagSpec, type FlagValue } from "./args.js";
+export { readEnvFile, parseDotenv, type EnvFile } from "./env.js";
+export { sanitize, redact, registerSecret, table, formatBytes, formatDuration, formatDate, shortKey, shortAddress } from "./ui.js";
+export { MAX_ATTRIBUTES, MAX_ENTITY_BYTES, MAX_STRING_BYTES, MAX_NAME_BYTES, MAX_LIFETIME, MAX_BYTES_LENGTH, BLOCK_SECONDS } from "./limits.js";
+export { runQuery, type QueryOptions } from "./commands/query.js";
+export { sampleSchemas, lintSchema, type SchemaSummary, type Finding } from "./commands/schema.js";
+export { runDoctor } from "./commands/doctor.js";
+export { runCost, parseLifetime, type CostOptions } from "./commands/cost.js";

package/dist/index.js

@@ -0,0 +1,19 @@
+/**
+ * Library surface, so the same helpers are usable from a script:
+ *
+ *   import { makeClient, runQuery } from "arkiv-cli";
+ *
+ * The CLI is the product; this module exists so people can script against the
+ * exact same connection and redaction behaviour instead of re-deriving it.
+ */
+export { main } from "./cli.js";
+export { buildContext } from "./context.js";
+export { makeClient, makeWallet, getTiming, blockToUnix, unixToBlock, explainError, networkNames, NETWORKS } from "./arkiv.js";
+export { parseArgs, UsageError } from "./args.js";
+export { readEnvFile, parseDotenv } from "./env.js";
+export { sanitize, redact, registerSecret, table, formatBytes, formatDuration, formatDate, shortKey, shortAddress } from "./ui.js";
+export { MAX_ATTRIBUTES, MAX_ENTITY_BYTES, MAX_STRING_BYTES, MAX_NAME_BYTES, MAX_LIFETIME, MAX_BYTES_LENGTH, BLOCK_SECONDS } from "./limits.js";
+export { runQuery } from "./commands/query.js";
+export { sampleSchemas, lintSchema } from "./commands/schema.js";
+export { runDoctor } from "./commands/doctor.js";
+export { runCost, parseLifetime } from "./commands/cost.js";

package/dist/limits.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Protocol limits, taken from the SDK so the CLI cannot drift from the chain.
+ * The fallbacks are the values the SDK itself ships; if a future SDK renames an
+ * export, the CLI still reports the correct documented numbers.
+ */
+export declare const MAX_ATTRIBUTES: number;
+export declare const MAX_ENTITY_BYTES: number;
+export declare const MAX_STRING_BYTES: number;
+export declare const MAX_NAME_BYTES: number;
+export declare const MAX_LIFETIME: number;
+export declare const MAX_BYTES_LENGTH: number;
+export declare const MAX_EXPIRES_AT: number;
+export declare const MAX_LIMIT = 100;
+export declare const BLOCK_SECONDS = 2;
+export interface LimitRow {
+    name: string;
+    value: number;
+    unit: string;
+    note: string;
+}
+export declare const LIMIT_ROWS: LimitRow[];

package/dist/limits.js

@@ -0,0 +1,28 @@
+/**
+ * Protocol limits, taken from the SDK so the CLI cannot drift from the chain.
+ * The fallbacks are the values the SDK itself ships; if a future SDK renames an
+ * export, the CLI still reports the correct documented numbers.
+ */
+import { MAX_ATTRIBUTES as SDK_MAX_ATTRIBUTES, MAX_BYTES_LENGTH as SDK_MAX_BYTES_LENGTH, MAX_ENTITY_BYTES as SDK_MAX_ENTITY_BYTES, MAX_EXPIRES_AT as SDK_MAX_EXPIRES_AT, MAX_LIFETIME as SDK_MAX_LIFETIME, MAX_NAME_BYTES as SDK_MAX_NAME_BYTES, MAX_STRING_BYTES as SDK_MAX_STRING_BYTES, } from "@arkiv-network/sdk";
+function limit(value, fallback) {
+    const n = Number(value);
+    return Number.isFinite(n) && n > 0 ? n : fallback;
+}
+export const MAX_ATTRIBUTES = limit(SDK_MAX_ATTRIBUTES, 32);
+export const MAX_ENTITY_BYTES = limit(SDK_MAX_ENTITY_BYTES, 131072);
+export const MAX_STRING_BYTES = limit(SDK_MAX_STRING_BYTES, 128);
+export const MAX_NAME_BYTES = limit(SDK_MAX_NAME_BYTES, 32);
+export const MAX_LIFETIME = limit(SDK_MAX_LIFETIME, 7_884_000);
+export const MAX_BYTES_LENGTH = limit(SDK_MAX_BYTES_LENGTH, 131072);
+export const MAX_EXPIRES_AT = Number(SDK_MAX_EXPIRES_AT ?? 2n ** 64n - 1n);
+export const MAX_LIMIT = 100;
+export const BLOCK_SECONDS = 2;
+export const LIMIT_ROWS = [
+    { name: "attributes per entity", value: MAX_ATTRIBUTES, unit: "count", note: "including arkiv.schema" },
+    { name: "attribute name", value: MAX_NAME_BYTES, unit: "bytes", note: "UTF-8" },
+    { name: "string attribute", value: MAX_STRING_BYTES, unit: "bytes", note: "longer text goes in bytes" },
+    { name: "bytes attribute", value: MAX_BYTES_LENGTH, unit: "bytes", note: "the binary payload ceiling" },
+    { name: "entity payload", value: MAX_ENTITY_BYTES, unit: "bytes", note: "all attributes together" },
+    { name: "entity lifetime", value: MAX_LIFETIME, unit: "blocks", note: `${MAX_LIFETIME * BLOCK_SECONDS} seconds at ${BLOCK_SECONDS}s blocks` },
+    { name: "query page", value: MAX_LIMIT, unit: "rows", note: "per request" },
+];

package/dist/render.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Shared rendering for entity lists (query and watch).
+ */
+import { type Timing } from "./arkiv.js";
+import { type AttributeValue } from "./values.js";
+export interface Entity {
+    $key: string;
+    $owner?: string;
+    $createdAt?: bigint | number;
+    $expiresAt?: bigint | number;
+    $attributes?: Record<string, AttributeValue>;
+    [key: string]: unknown;
+}
+export declare function attributesOf(entity: Entity): Record<string, AttributeValue>;
+export declare function schemaOf(entity: Entity): string;
+export declare function num(value: bigint | number | undefined): number;
+export declare function expiresIn(entity: Entity, timing: Timing | null, now?: number): number;
+export declare function entityRows(entities: Entity[], timing: Timing | null, options?: {
+    showKey?: boolean;
+    maxAttrs?: number;
+}): string[][];
+export declare function renderEntities(entities: Entity[], timing: Timing | null, options?: {
+    showKey?: boolean;
+    maxAttrs?: number;
+}): string;
+export declare function entityDetail(entity: Entity, timing: Timing | null): string;

package/dist/render.js

@@ -0,0 +1,77 @@
+/**
+ * Shared rendering for entity lists (query and watch).
+ */
+import { blockToUnix } from "./arkiv.js";
+import { displayValue } from "./values.js";
+import { dim, formatDuration, formatDate, shortAddress, shortKey, table, truncate } from "./ui.js";
+export function attributesOf(entity) {
+    const raw = (entity.$attributes ?? {});
+    return raw;
+}
+export function schemaOf(entity) {
+    const attr = attributesOf(entity)["arkiv.schema"];
+    if (attr)
+        return String(attr.value);
+    const direct = entity["arkiv.schema"];
+    return direct ? String(direct.value) : "";
+}
+export function num(value) {
+    if (typeof value === "bigint")
+        return Number(value);
+    return typeof value === "number" ? value : 0;
+}
+export function expiresIn(entity, timing, now = Date.now() / 1000) {
+    const expiresAt = num(entity.$expiresAt);
+    if (!expiresAt)
+        return Number.POSITIVE_INFINITY;
+    if (!timing)
+        return Number.POSITIVE_INFINITY;
+    return blockToUnix(timing, expiresAt) - now;
+}
+export function entityRows(entities, timing, options = {}) {
+    const now = Date.now() / 1000;
+    return entities.map((entity) => {
+        const attrs = attributesOf(entity);
+        const parts = Object.entries(attrs)
+            .filter(([name]) => name !== "arkiv.schema")
+            .slice(0, options.maxAttrs ?? 4)
+            .map(([name, value]) => `${name}=${displayValue(value, 20)}`);
+        const more = Object.keys(attrs).length > (options.maxAttrs ?? 4) + 1 ? " +" : "";
+        return [
+            options.showKey ? entity.$key : shortKey(entity.$key),
+            formatDuration(expiresIn(entity, timing, now)),
+            truncate(schemaOf(entity) || "-", 28),
+            parts.join(" ") + more || dim("-"),
+        ];
+    });
+}
+export function renderEntities(entities, timing, options = {}) {
+    if (entities.length === 0)
+        return dim("no entities matched");
+    return table(["KEY", "EXPIRES", "SCHEMA", "ATTRIBUTES"], entityRows(entities, timing, options), {
+        maxColumnWidth: 64,
+    });
+}
+export function entityDetail(entity, timing) {
+    const attrs = attributesOf(entity);
+    const lines = [];
+    lines.push(`${dim("key")}        ${entity.$key}`);
+    if (entity.$owner)
+        lines.push(`${dim("owner")}      ${entity.$owner} ${dim(`(${shortAddress(entity.$owner)})`)}`);
+    const created = num(entity.$createdAt);
+    const expires = num(entity.$expiresAt);
+    if (created && timing)
+        lines.push(`${dim("created")}    ${formatDate(blockToUnix(timing, created))} ${dim(`block ${created}`)}`);
+    if (expires && timing) {
+        const unix = blockToUnix(timing, expires);
+        lines.push(`${dim("expires")}    ${formatDate(unix)} ${dim(`block ${expires}, in ${formatDuration(unix - Date.now() / 1000)}`)}`);
+    }
+    lines.push("");
+    const width = Math.max(4, ...Object.keys(attrs).map((k) => k.length));
+    for (const [name, value] of Object.entries(attrs)) {
+        lines.push(`${dim(name.padEnd(width))}  ${dim(value.type.padEnd(6))} ${displayValue(value, 120)}`);
+    }
+    if (Object.keys(attrs).length === 0)
+        lines.push(dim("no attributes"));
+    return lines.join("\n");
+}

package/dist/ui.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Terminal output helpers: colour, tables, redaction and sanitisation.
+ *
+ * Two rules live here and apply to every command:
+ *   1. Nothing that looks like a credential ever reaches stdout or stderr.
+ *   2. Nothing read from the chain is printed without stripping control
+ *      sequences first, because attribute values are arbitrary bytes and a
+ *      malicious entity could otherwise rewrite the user's terminal.
+ */
+export declare function setColour(on: boolean): void;
+export declare const bold: (s: string) => string;
+export declare const dim: (s: string) => string;
+export declare const red: (s: string) => string;
+export declare const green: (s: string) => string;
+export declare const yellow: (s: string) => string;
+export declare const blue: (s: string) => string;
+export declare const magenta: (s: string) => string;
+export declare const cyan: (s: string) => string;
+export declare const grey: (s: string) => string;
+/** Register a value that must never appear in output. Empty strings ignored. */
+export declare function registerSecret(value: string | undefined | null): void;
+/** Remove credentials and key-shaped strings from arbitrary text. */
+export declare function redact(input: unknown): string;
+/** Strip ANSI escapes and control characters from untrusted text. */
+export declare function sanitize(input: unknown): string;
+export declare function shortKey(key: string): string;
+export declare function shortAddress(address: string): string;
+export declare function formatBytes(n: number): string;
+export declare function formatDuration(totalSeconds: number): string;
+export declare function formatDate(unixSeconds: number): string;
+export declare function truncate(s: string, max: number): string;
+export interface TableOptions {
+    maxColumnWidth?: number;
+    align?: ("left" | "right")[];
+    /** Rows that should be dimmed, by index. */
+    dim?: number[];
+}
+export declare function table(headers: string[], rows: string[][], options?: TableOptions): string;
+export declare function out(line?: string): void;
+export declare function err(line: string): void;
+export declare function field(label: string, value: string): string;

package/dist/ui.js

@@ -0,0 +1,144 @@
+/**
+ * Terminal output helpers: colour, tables, redaction and sanitisation.
+ *
+ * Two rules live here and apply to every command:
+ *   1. Nothing that looks like a credential ever reaches stdout or stderr.
+ *   2. Nothing read from the chain is printed without stripping control
+ *      sequences first, because attribute values are arbitrary bytes and a
+ *      malicious entity could otherwise rewrite the user's terminal.
+ */
+let colourEnabled = Boolean(process.stdout.isTTY) && !process.env.NO_COLOR;
+export function setColour(on) {
+    colourEnabled = on && !process.env.NO_COLOR;
+}
+const wrap = (open, close = 0) => (s) => colourEnabled ? `\u001b[${open}m${s}\u001b[${close}m` : s;
+export const bold = wrap(1);
+export const dim = wrap(2);
+export const red = wrap(31);
+export const green = wrap(32);
+export const yellow = wrap(33);
+export const blue = wrap(34);
+export const magenta = wrap(35);
+export const cyan = wrap(36);
+export const grey = wrap(90);
+/* ------------------------------------------------------------------ secrets */
+const secrets = new Set();
+/** Register a value that must never appear in output. Empty strings ignored. */
+export function registerSecret(value) {
+    if (!value)
+        return;
+    const v = value.trim();
+    if (v.length >= 6)
+        secrets.add(v);
+}
+const KEY_RE = /\b0x[0-9a-fA-F]{64}\b/g;
+/*
+ * A 64-hex string is only secret when it is presented as one. Entity keys and
+ * other public identifiers are also 64 hex characters, and redacting them would
+ * break the thing the CLI exists to show, so the pattern only fires on lines
+ * that talk about key material.
+ */
+const KEY_CONTEXT_RE = /(private[\s_-]?key|secret|mnemonic|seed phrase|passphrase|api[\s_-]?key|access[\s_-]?key)/i;
+const ASSIGN_RE = /((?:private[_-]?key|access[_-]?key|secret|token|password|passwd|api[_-]?key)\s*[:=]\s*["']?)([^\s"',;]{6,})/gi;
+/** Remove credentials and key-shaped strings from arbitrary text. */
+export function redact(input) {
+    let s = typeof input === "string" ? input : String(input ?? "");
+    for (const secret of secrets) {
+        if (secret)
+            s = s.split(secret).join("[REDACTED]");
+    }
+    s = s
+        .split("\n")
+        .map((line) => (KEY_CONTEXT_RE.test(line) ? line.replace(KEY_RE, "0x[REDACTED]") : line))
+        .join("\n");
+    s = s.replace(ASSIGN_RE, (_m, p1) => `${p1}[REDACTED]`);
+    return s;
+}
+/* ------------------------------------------------------------------ sanitise */
+const CSI_RE = /\u001b\[[0-9;?]*[ -/]*[@-~]/g;
+const CTRL_RE = /[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f\u0080-\u009f]/g;
+/** Strip ANSI escapes and control characters from untrusted text. */
+export function sanitize(input) {
+    const s = typeof input === "string" ? input : String(input ?? "");
+    return s.replace(CSI_RE, "").replace(CTRL_RE, "\u00b7");
+}
+/* ------------------------------------------------------------------ formats */
+export function shortKey(key) {
+    if (!key || key.length < 14)
+        return key;
+    return `${key.slice(0, 8)}\u2026${key.slice(-6)}`;
+}
+export function shortAddress(address) {
+    if (!address || address.length < 12)
+        return address;
+    return `${address.slice(0, 6)}\u2026${address.slice(-4)}`;
+}
+export function formatBytes(n) {
+    if (!Number.isFinite(n) || n < 0)
+        return "?";
+    if (n < 1024)
+        return `${n} B`;
+    if (n < 1024 * 1024)
+        return `${(n / 1024).toFixed(1)} KB`;
+    return `${(n / (1024 * 1024)).toFixed(1)} MB`;
+}
+export function formatDuration(totalSeconds) {
+    const s = Math.round(totalSeconds);
+    if (!Number.isFinite(s))
+        return "?";
+    if (s <= 0)
+        return "expired";
+    const d = Math.floor(s / 86_400);
+    const h = Math.floor((s % 86_400) / 3600);
+    const m = Math.floor((s % 3600) / 60);
+    const sec = s % 60;
+    if (d > 0)
+        return h > 0 ? `${d}d ${h}h` : `${d}d`;
+    if (h > 0)
+        return m > 0 ? `${h}h ${m}m` : `${h}h`;
+    if (m > 0)
+        return `${m}m`;
+    return `${sec}s`;
+}
+export function formatDate(unixSeconds) {
+    if (!Number.isFinite(unixSeconds) || unixSeconds <= 0)
+        return "?";
+    return new Date(unixSeconds * 1000).toISOString().replace(".000Z", "Z");
+}
+export function truncate(s, max) {
+    if (s.length <= max)
+        return s;
+    if (max <= 1)
+        return s.slice(0, max);
+    return `${s.slice(0, max - 1)}\u2026`;
+}
+function width(s) {
+    // Colour codes are not counted; the only codes we emit wrap whole cells.
+    return s.replace(/\u001b\[[0-9;]*m/g, "").length;
+}
+export function table(headers, rows, options = {}) {
+    const max = options.maxColumnWidth ?? 48;
+    const clean = rows.map((r) => headers.map((_, i) => sanitize(r[i] ?? "").replace(/\s+/g, " ").trim()));
+    const cells = clean.map((r) => r.map((c) => truncate(c, max)));
+    const widths = headers.map((h, i) => Math.max(width(h), ...cells.map((r) => width(r[i] ?? "")), 3));
+    const pad = (s, i) => {
+        const gap = " ".repeat(Math.max(0, widths[i] - width(s)));
+        return (options.align?.[i] ?? "left") === "right" ? gap + s : s + gap;
+    };
+    const head = headers.map((h, i) => bold(pad(h, i))).join("  ");
+    const body = cells.map((r, ri) => {
+        const line = r.map((c, i) => pad(c, i)).join("  ");
+        return (options.dim ?? []).includes(ri) ? dim(line) : line;
+    });
+    return [head, ...body].join("\n");
+}
+/* ------------------------------------------------------------------ writing */
+export function out(line = "") {
+    process.stdout.write(`${redact(line)}\n`);
+}
+export function err(line) {
+    process.stderr.write(`${redact(line)}\n`);
+}
+export function field(label, value) {
+    return `${bold(label.padEnd(12))} ${value}`;
+}

package/dist/values.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Reading and writing Arkiv attribute values.
+ *
+ * Values arriving from the chain are untrusted: they can contain control
+ * characters, very long strings, or bytes that are not UTF-8. Everything is
+ * sanitised and truncated before display.
+ */
+export interface AttributeValue {
+    type: string;
+    value: unknown;
+}
+export declare function safeText(input: unknown): string;
+export declare function bytesToText(hex: string): string | null;
+export declare function previewBytes(hex: string, max?: number): string;
+/** Human readable one-line rendering of an attribute. */
+export declare function displayValue(attribute: AttributeValue | undefined, max?: number): string;
+export declare function attributeSize(attribute: AttributeValue | undefined): number;
+/** Total payload size of an entity's attributes, used by doctor and create. */
+export declare function entityFootprint(attributes: Record<string, AttributeValue>): number;
+export type ValueType = "str" | "u64" | "i32" | "u256" | "bool" | "bytes" | "addr" | "key" | "dec";
+export declare const VALUE_TYPES: ValueType[];
+/**
+ * Convert a JSON value from a create file into a typed SDK value. Types are
+ * explicit because the chain does not coerce between them.
+ */
+export declare function typedValue(type: ValueType, raw: unknown): unknown;

package/dist/values.js

@@ -0,0 +1,132 @@
+/**
+ * Reading and writing Arkiv attribute values.
+ *
+ * Values arriving from the chain are untrusted: they can contain control
+ * characters, very long strings, or bytes that are not UTF-8. Everything is
+ * sanitised and truncated before display.
+ */
+import { addr, bool as boolValue, bytes as bytesValue, dec, i32, key as keyValue, str, u64, u256 } from "@arkiv-network/sdk";
+import { sanitize, truncate } from "./ui.js";
+export function safeText(input) {
+    return sanitize(input);
+}
+const PRINTABLE = /^[\x09\x0a\x0d\x20-\x7e\u00a0-\uffff]*$/;
+export function bytesToText(hex) {
+    const body = hex.startsWith("0x") ? hex.slice(2) : hex;
+    if (body.length % 2 !== 0 || body.length === 0)
+        return null;
+    try {
+        const buf = Buffer.from(body, "hex");
+        if (buf.toString("hex") !== body.toLowerCase())
+            return null;
+        const text = buf.toString("utf8");
+        if (text.includes("\ufffd"))
+            return null;
+        if (!PRINTABLE.test(text))
+            return null;
+        return text;
+    }
+    catch {
+        return null;
+    }
+}
+export function previewBytes(hex, max = 48) {
+    const text = bytesToText(hex);
+    const body = hex.startsWith("0x") ? hex.slice(2) : hex;
+    const size = Math.floor(body.length / 2);
+    if (text !== null) {
+        const clean = text.replace(/\s+/g, " ").trim();
+        return `"${truncate(clean, max)}" (${size} B)`;
+    }
+    return `0x${truncate(body, max)} (${size} B)`;
+}
+/** Human readable one-line rendering of an attribute. */
+export function displayValue(attribute, max = 48) {
+    if (!attribute)
+        return "";
+    const { type, value } = attribute;
+    if (value === null || value === undefined)
+        return "";
+    switch (type) {
+        case "bytes":
+            return previewBytes(String(value), max);
+        case "str":
+            return truncate(safeText(value), max);
+        case "bool":
+            return value ? "true" : "false";
+        case "u64":
+        case "i32":
+        case "u256":
+        case "dec":
+        case "addr":
+        case "key":
+            return truncate(String(value), max);
+        default:
+            return truncate(safeText(String(value)), max);
+    }
+}
+export function attributeSize(attribute) {
+    if (!attribute || attribute.value == null)
+        return 0;
+    switch (attribute.type) {
+        case "bytes": {
+            const body = String(attribute.value).replace(/^0x/, "");
+            return Math.floor(body.length / 2);
+        }
+        case "u64":
+            return 8;
+        case "i32":
+            return 4;
+        case "u256":
+            return 32;
+        case "bool":
+            return 1;
+        case "addr":
+            return 20;
+        case "key":
+            return 32;
+        default:
+            return Buffer.byteLength(String(attribute.value), "utf8");
+    }
+}
+/** Total payload size of an entity's attributes, used by doctor and create. */
+export function entityFootprint(attributes) {
+    return Object.entries(attributes).reduce((total, [name, attr]) => total + Buffer.byteLength(name, "utf8") + attributeSize(attr), 0);
+}
+export const VALUE_TYPES = ["str", "u64", "i32", "u256", "bool", "bytes", "addr", "key", "dec"];
+/**
+ * Convert a JSON value from a create file into a typed SDK value. Types are
+ * explicit because the chain does not coerce between them.
+ */
+export function typedValue(type, raw) {
+    switch (type) {
+        case "str":
+            if (typeof raw !== "string")
+                throw new Error("str values must be strings");
+            return str(raw);
+        case "u64":
+            return u64(BigInt(String(raw)));
+        case "i32":
+            return i32(Number(raw));
+        case "u256":
+            return u256(BigInt(String(raw)));
+        case "bool":
+            if (typeof raw !== "boolean")
+                throw new Error("bool values must be true or false");
+            return boolValue(raw);
+        case "bytes": {
+            const hex = String(raw);
+            if (!/^0x([0-9a-fA-F]{2})*$/.test(hex))
+                throw new Error("bytes values must be 0x-prefixed hex");
+            return bytesValue(hex);
+        }
+        case "addr":
+            return addr(String(raw));
+        case "key":
+            return keyValue(String(raw));
+        case "dec":
+            return dec(String(raw));
+        default:
+            throw new Error(`unknown attribute type "${type}"`);
+    }
+}