arkiv-cli 0.0.0-stage → 0.1.0

package/dist/commands/entity.js

@@ -0,0 +1,91 @@
+/**
+ * `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 { explainError, getTiming, blockToUnix, explorerUrl } from "../arkiv.js";
+import { displayValue } from "../values.js";
+import { bold, cyan, dim, formatDate, formatDuration, grey, out, red, table, yellow, } from "../ui.js";
+const KEY_PATTERN = /^0x[0-9a-fA-F]{64}$/;
+export async function runEntity(ctx, rawKey) {
+    const key = rawKey.trim();
+    if (!KEY_PATTERN.test(key)) {
+        out(red(`not an entity key: ${key}`));
+        out(dim("an entity key is 0x followed by 64 hex characters"));
+        process.exitCode = 2;
+        return;
+    }
+    let entity;
+    try {
+        entity = (await ctx.client().getEntity(key));
+    }
+    catch (error) {
+        out(red("could not read that entity"));
+        out(dim(explainError(error)));
+        process.exitCode = 1;
+        return;
+    }
+    const attributes = (entity.$attributes ?? {});
+    let timing = null;
+    try {
+        timing = await getTiming(ctx.client());
+    }
+    catch {
+        /* block timing is a nicety; the entity still prints without it */
+    }
+    if (ctx.json) {
+        const payload = {
+            key: entity.$key,
+            owner: entity.$owner,
+            creator: entity.$creator,
+            createdAt: entity.$createdAt ? Number(entity.$createdAt) : null,
+            updatedAt: entity.$updatedAt ? Number(entity.$updatedAt) : null,
+            expiresAt: entity.$expiresAt ? Number(entity.$expiresAt) : null,
+            flags: entity.$creationFlags,
+            attributes: Object.fromEntries(Object.entries(attributes).map(([name, value]) => [name, { type: value.type, value: value.value }])),
+        };
+        process.stdout.write(`${JSON.stringify(payload, (_k, v) => (typeof v === "bigint" ? v.toString() : v), 2)}\n`);
+        return;
+    }
+    const title = attributes["arkiv.schema"]?.value ?? "entity";
+    out(`${bold(String(title))} ${dim("entity")}`);
+    out(`${grey("key     ")} ${entity.$key}`);
+    if (entity.$owner)
+        out(`${grey("owner   ")} ${entity.$owner}`);
+    if (entity.$creator && entity.$creator !== entity.$owner) {
+        out(`${grey("creator ")} ${entity.$creator}`);
+    }
+    if (timing) {
+        if (entity.$createdAt) {
+            const created = blockToUnix(timing, Number(entity.$createdAt));
+            out(`${grey("created ")} ${formatDate(created)} ${dim(`(block ${Number(entity.$createdAt).toLocaleString("en-US")})`)}`);
+        }
+        if (entity.$updatedAt && entity.$updatedAt !== entity.$createdAt) {
+            out(`${grey("updated ")} ${formatDate(blockToUnix(timing, Number(entity.$updatedAt)))}`);
+        }
+        if (entity.$expiresAt && Number(entity.$expiresAt) > 0) {
+            const expires = blockToUnix(timing, Number(entity.$expiresAt));
+            const remaining = expires - Date.now() / 1000;
+            const tone = remaining < 0 ? red : remaining < 86_400 ? yellow : dim;
+            out(`${grey("expires ")} ${formatDate(expires)} ${tone(`(in ${formatDuration(remaining)})`)}`);
+        }
+        else {
+            out(`${grey("expires ")} ${dim("never (expiry disabled)")}`);
+        }
+    }
+    out();
+    const rows = Object.entries(attributes).map(([name, value]) => [
+        name,
+        cyan(value.type),
+        displayValue(value, 160),
+    ]);
+    if (rows.length === 0) {
+        out(dim("no attributes"));
+    }
+    else {
+        out(table(["ATTRIBUTE", "TYPE", "VALUE"], rows));
+    }
+    const url = explorerUrl(ctx.network, key);
+    if (url)
+        out(`\n${grey("explorer")} ${url}`);
+}

package/dist/commands/init.d.ts

@@ -0,0 +1,13 @@
+/**
+ * `arkiv init` - scaffold a project that runs.
+ *
+ * The generated app is deliberately small: one file that connects, defines a
+ * schema, writes an entity and reads it back. Everything is written with `wx`
+ * so an existing project is never silently overwritten.
+ */
+export interface InitOptions {
+    directory: string;
+    force: boolean;
+    install: boolean;
+}
+export declare function runInit(options: InitOptions): Promise<void>;

package/dist/commands/init.js

@@ -0,0 +1,205 @@
+/**
+ * `arkiv init` - scaffold a project that runs.
+ *
+ * The generated app is deliberately small: one file that connects, defines a
+ * schema, writes an entity and reads it back. Everything is written with `wx`
+ * so an existing project is never silently overwritten.
+ */
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { join, resolve, basename } from "node:path";
+import { bold, dim, green, out, red, yellow } from "../ui.js";
+const PACKAGE_JSON = (name) => JSON.stringify({
+    name,
+    version: "0.1.0",
+    private: true,
+    type: "module",
+    scripts: {
+        dev: "tsx src/main.ts",
+        start: "tsx src/main.ts",
+        typecheck: "tsc --noEmit",
+    },
+    dependencies: {
+        "@arkiv-network/sdk": "^1.0.1",
+        viem: "^2.21.0",
+    },
+    devDependencies: {
+        "@types/node": "^22.10.0",
+        tsx: "^4.19.0",
+        typescript: "^5.6.0",
+    },
+}, null, 2) + "\n";
+const TSCONFIG = `{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "lib": ["ES2022"],
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "skipLibCheck": true,
+    "types": ["node"],
+    "noEmit": true
+  },
+  "include": ["src"]
+}
+`;
+const GITIGNORE = `node_modules/
+.env
+.env.*
+!.env.example
+dist/
+*.log
+`;
+const ENV_EXAMPLE = `# Access key from https://hub.arkiv.network/access-keys
+# The public RPC is rate limited, so a key is not optional for real work.
+ARKIV_ACCESS_KEY=
+
+# A testnet-funded wallet. Generate nothing here: paste the key you already own
+# and fund it from https://hub.arkiv.network/faucet
+ARKIV_PRIVATE_KEY=
+
+# rabdi (testnet) or localhost
+ARKIV_NETWORK=rabdi
+`;
+const MAIN_TS = `/**
+ * A minimal Arkiv app: connect, write one entity, read it back.
+ *
+ * Run it with \`npm run dev\`. Everything is read from .env so no key ever
+ * appears in source.
+ */
+
+import { createPublicClient, createWalletClient, ExpirationTime } from "@arkiv-network/sdk";
+import { http } from "viem";
+import { addr, bytes, defineSchema, str, u64 } from "@arkiv-network/sdk/schema";
+import { rabdi } from "@arkiv-network/sdk/chains";
+import { privateKeyToAccount } from "viem/accounts";
+
+const accessKey = process.env.ARKIV_ACCESS_KEY ?? "";
+const privateKey = process.env.ARKIV_PRIVATE_KEY ?? "";
+
+if (!privateKey) {
+  console.error("ARKIV_PRIVATE_KEY is empty; copy .env.example to .env and fill it in");
+  process.exit(1);
+}
+
+const chain = rabdi({ accessKey });
+const account = privateKeyToAccount(privateKey as \`0x\${string}\`);
+
+const publicClient = createPublicClient({ chain, transport: http() });
+const wallet = createWalletClient({ chain, transport: http(), account });
+
+/**
+ * A schema is the contract for one kind of entity. Keep the name namespaced and
+ * versioned: "notes/v1" not "notes".
+ */
+const Note = defineSchema("notes/v1", {
+  author: addr().indexed(),
+  slug: str().indexed(),
+  title: str(),
+  revision: u64(),
+  body: bytes(),
+});
+
+const slug = \`hello-\${Date.now()}\`;
+
+const { entityKey, txHash, expiresAt } = await wallet.createEntity(
+  Note,
+  {
+    author: addr(account.address),
+    slug,
+    title: "First note",
+    revision: u64(1n),
+    body: new TextEncoder().encode("Written from a terminal."),
+  },
+  { expiration: ExpirationTime.fromDays(7) },
+);
+
+console.log("wrote", entityKey);
+console.log("tx   ", txHash);
+console.log("until", Number(expiresAt));
+
+const page = await publicClient
+  .select({ $key: true, $owner: true, $expiresAt: true, $attributes: true })
+  // the SDK types predicates strictly; the plain string form works at runtime
+  .where(\`slug = str('\${slug}')\` as never)
+  .limit(1)
+  .fetch();
+
+console.log("read back", JSON.stringify(page.entities, (_key, value) => (typeof value === "bigint" ? value.toString() : value), 2));
+`;
+const README = (name) => `# ${name}
+
+An Arkiv app scaffolded with \`arkiv init\`.
+
+## Setup
+
+1. \`npm install\`
+2. Copy \`.env.example\` to \`.env\`.
+3. Put your access key and a faucet-funded testnet private key in \`.env\`.
+4. \`npx arkiv-cli doctor\` checks the key format, the balance and the RPC.
+5. \`npm run dev\` writes one entity and reads it back.
+
+## Where things are
+
+- \`src/main.ts\`: the whole app. A typed schema, one write, one query.
+- \`.env\`: credentials, ignored by git.
+
+## Notes
+
+- Schema names should be namespaced and versioned (\`notes/v1\`), because the
+  network has no registry and a flat name collides with everyone else's.
+- Every attribute value has a size limit; run \`npx arkiv cost\` before writing
+  anything large, and \`npx arkiv limits\` for the full table.
+- Entities expire. \`ExpirationTime.fromDays(7)\` sets the lifetime at write time.
+
+Built By Harish Kotra \\- harishkotra.me
+`;
+export async function runInit(options) {
+    const target = resolve(options.directory);
+    if (existsSync(target)) {
+        if (!options.force) {
+            out(red(`${target} already exists`));
+            out(dim("pass --force to write into it anyway (existing files are still not overwritten)"));
+            process.exitCode = 1;
+            return;
+        }
+    }
+    mkdirSync(target, { recursive: true });
+    mkdirSync(join(target, "src"), { recursive: true });
+    const name = basename(target).replace(/[^a-zA-Z0-9._-]/g, "-") || "arkiv-app";
+    const files = [
+        ["package.json", PACKAGE_JSON(name)],
+        ["tsconfig.json", TSCONFIG],
+        [".gitignore", GITIGNORE],
+        [".env.example", ENV_EXAMPLE],
+        ["src/main.ts", MAIN_TS],
+        ["README.md", README(name)],
+    ];
+    const written = [];
+    const skipped = [];
+    for (const [relative, content] of files) {
+        const path = join(target, relative);
+        if (existsSync(path)) {
+            skipped.push(relative);
+            continue;
+        }
+        writeFileSync(path, content, { flag: "wx", mode: relative.startsWith(".env") ? 0o600 : 0o644 });
+        written.push(relative);
+    }
+    out(bold("scaffolded"));
+    for (const file of written)
+        out(`  ${green("+")} ${file}`);
+    for (const file of skipped)
+        out(`  ${yellow("=")} ${file} ${dim("kept")}`);
+    out();
+    out("next:");
+    out(`  cd ${target}`);
+    out("  npm install");
+    out("  cp .env.example .env   # then fill in the key");
+    out("  npx arkiv-cli doctor");
+    out("  npm run dev");
+    if (skipped.length > 0) {
+        out();
+        out(dim("existing files were left alone; delete them if you want the templates back"));
+    }
+}

package/dist/commands/query.d.ts

@@ -0,0 +1,24 @@
+/**
+ * `arkiv query` - paginated reads with a readable default table.
+ */
+import type { Context } from "../context.js";
+import { explainError } from "../arkiv.js";
+import { type ValueType } from "../values.js";
+import { cyan } from "../ui.js";
+export declare const MAX_LIMIT = 100;
+export interface QueryOptions {
+    expression: string;
+    schema?: string;
+    limit: number;
+    offset: number;
+    countOnly?: boolean;
+    showKey?: boolean;
+    sort?: string;
+    sortType?: ValueType;
+    descending?: boolean;
+    select?: string[];
+}
+export declare function buildExpression(options: QueryOptions): string;
+export declare function runQuery(ctx: Context, options: QueryOptions): Promise<void>;
+export declare function stringifyEntity(entity: unknown): string;
+export { explainError, cyan };

package/dist/commands/query.js

@@ -0,0 +1,111 @@
+/**
+ * `arkiv query` - paginated reads with a readable default table.
+ */
+import { asc, desc } from "@arkiv-network/sdk/query";
+import { explainError, getTiming } from "../arkiv.js";
+import { renderEntities, num } from "../render.js";
+import { VALUE_TYPES } from "../values.js";
+import { UsageError } from "../args.js";
+import { bold, cyan, dim, out, yellow } from "../ui.js";
+export const MAX_LIMIT = 100;
+export function buildExpression(options) {
+    const parts = [];
+    const raw = options.expression.trim();
+    if (raw)
+        parts.push(`(${raw})`);
+    if (options.schema) {
+        if (!/^[A-Za-z0-9._/-]{1,64}$/.test(options.schema)) {
+            throw new UsageError("--schema contains characters that are not allowed in a schema name");
+        }
+        parts.push(`arkiv.schema = str('${options.schema}')`);
+    }
+    if (parts.length === 0) {
+        throw new UsageError('give a filter expression, for example: arkiv query "arkiv.schema = str(\'my-app-v1.post\')"');
+    }
+    const expression = parts.join(" AND ");
+    if (expression.length > 2000)
+        throw new UsageError("expression is too long (2000 character limit)");
+    return expression;
+}
+export async function runQuery(ctx, options) {
+    const expression = buildExpression(options);
+    if (!Number.isInteger(options.limit) || options.limit < 1 || options.limit > MAX_LIMIT) {
+        throw new UsageError(`--limit must be between 1 and ${MAX_LIMIT}`);
+    }
+    if (!Number.isInteger(options.offset) || options.offset < 0) {
+        throw new UsageError("--offset must be zero or more");
+    }
+    const client = ctx.client();
+    let builder = client.select();
+    if (options.select?.length) {
+        const selection = {};
+        for (const field of options.select)
+            selection[field] = true;
+        builder = client.select(selection);
+    }
+    builder = builder.where(expression).limit(options.limit);
+    if (options.offset > 0)
+        builder = builder.offset(options.offset);
+    if (options.sort) {
+        const type = options.sort.startsWith("$")
+            ? undefined
+            : (options.sortType ?? "str");
+        if (type && !VALUE_TYPES.includes(type))
+            throw new UsageError(`unknown --sort-type ${type}`);
+        const key = type
+            ? asc(options.sort, type)
+            : asc(options.sort);
+        const descendingKey = type
+            ? desc(options.sort, type)
+            : desc(options.sort);
+        builder = builder.orderBy(options.descending ? descendingKey : key);
+    }
+    const page = await builder.withCount().fetch();
+    const count = page.count === undefined ? undefined : Number(page.count);
+    const entities = page.entities;
+    if (options.countOnly) {
+        if (ctx.json) {
+            process.stdout.write(`${JSON.stringify({ count, block: String(page.blockNumber) })}\n`);
+        }
+        else {
+            out(`${bold(String(count ?? "?"))} ${dim("matching entities")}`);
+        }
+        return;
+    }
+    if (ctx.json) {
+        const payload = {
+            count,
+            block: String(page.blockNumber),
+            expression,
+            entities: entities.map((entity) => JSON.parse(stringifyEntity(entity))),
+        };
+        process.stdout.write(`${JSON.stringify(payload, null, 2)}\n`);
+        return;
+    }
+    let timing = null;
+    try {
+        timing = await getTiming(client);
+    }
+    catch {
+        /* expiry falls back to block numbers */
+    }
+    out(dim(`expression: ${expression}`));
+    out(renderEntities(entities, timing, { showKey: options.showKey }));
+    const shown = entities.length;
+    const from = options.offset + 1;
+    const to = options.offset + shown;
+    out();
+    out(dim(count === undefined
+        ? `${shown} shown`
+        : `${from}-${to} of ${count} ${shown === 0 ? "" : "shown in page"}`.replace("  ", " ")) +
+        dim(`  (read at block ${num(page.blockNumber).toLocaleString("en-US")})`));
+    if (count !== undefined && to < count) {
+        out(dim(`next page: --offset ${to}`));
+    }
+    if (shown === 0)
+        out(yellow("nothing matched - check the schema name with `arkiv schema`"));
+}
+export function stringifyEntity(entity) {
+    return JSON.stringify(entity, (_key, value) => (typeof value === "bigint" ? value.toString() : value), 2);
+}
+export { explainError, cyan };

package/dist/commands/schema.d.ts

@@ -0,0 +1,55 @@
+/**
+ * `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 type { Context } from "../context.js";
+export interface FieldInfo {
+    type: string;
+    indexed: boolean;
+    /** Distinct string lengths seen, used by the overflow lint. */
+    maxStringBytes: number;
+    maxEntityBytes: number;
+}
+export interface SchemaSummary {
+    name: string;
+    entities: number;
+    owners: string[];
+    fields: Map<string, FieldInfo>;
+    typeConflicts: Set<string>;
+    earliestExpiry: number;
+}
+export interface SampleOptions {
+    sample: number;
+}
+export declare function sampleSchemas(ctx: Context, options: SampleOptions): Promise<{
+    schemas: Map<string, SchemaSummary>;
+    scanned: number;
+    block: number;
+}>;
+export type Severity = "error" | "warn" | "info";
+export interface Finding {
+    severity: Severity;
+    rule: string;
+    message: string;
+}
+export declare function lintSchema(summary: SchemaSummary): Finding[];
+export declare function worst(findings: Finding[]): Severity | null;
+export declare function runSchemaList(ctx: Context, options: SampleOptions): Promise<void>;
+/**
+ * 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 declare function collectSchema(ctx: Context, name: string, limit?: number): Promise<SchemaSummary | null>;
+export declare function runSchemaDetail(ctx: Context, name: string): Promise<void>;
+export declare function renderAtlas(schemas: Map<string, SchemaSummary>, meta: {
+    scanned: number;
+    block: number;
+    network: string;
+}): string;