@cogcoin/client 0.5.0

package/dist/cli/mutation-text-format.js

@@ -0,0 +1,171 @@
+import { formatCogAmount } from "../wallet/tx/common.js";
+export function formatRegisterSenderSummary(result) {
+    return `${result.resolved.sender.selector} (${result.resolved.sender.address})`;
+}
+export function formatRegisterEconomicEffect(result) {
+    if (result.resolved.economicEffect.kind === "treasury-payment") {
+        return `send ${result.resolved.economicEffect.amount.toString()} sats to the Cogcoin treasury`;
+    }
+    return `burn ${formatCogAmount(result.resolved.economicEffect.amount)} from the parent-owner identity`;
+}
+export function formatBuyBuyerSummary(result) {
+    if (result.resolvedBuyer === null || result.resolvedBuyer === undefined) {
+        return "unknown";
+    }
+    return `${result.resolvedBuyer.selector} (${result.resolvedBuyer.address})`;
+}
+export function formatBuySellerSummary(result) {
+    if (result.resolvedSeller === null || result.resolvedSeller === undefined) {
+        return "unknown";
+    }
+    return result.resolvedSeller.address ?? `spk:${result.resolvedSeller.scriptPubKeyHex}`;
+}
+export function formatBuySettlementSummary() {
+    return "entirely in COG state; no BTC seller output";
+}
+export function formatDomainMarketSenderSummary(result) {
+    if (result.resolved === null || result.resolved === undefined) {
+        return "unknown";
+    }
+    return `${result.resolved.sender.selector} (${result.resolved.sender.address})`;
+}
+export function formatDomainMarketRecipientSummary(result) {
+    const recipient = result.resolved?.recipient;
+    if (recipient !== null && recipient !== undefined) {
+        return recipient.address ?? `spk:${recipient.scriptPubKeyHex}`;
+    }
+    if (result.recipientScriptPubKeyHex === null || result.recipientScriptPubKeyHex === undefined) {
+        return "unknown";
+    }
+    return `spk:${result.recipientScriptPubKeyHex}`;
+}
+export function formatDomainMarketEconomicEffect(result) {
+    const economicEffect = result.resolved?.economicEffect;
+    if (economicEffect === null || economicEffect === undefined) {
+        return "unknown";
+    }
+    if (economicEffect.kind === "ownership-transfer") {
+        return economicEffect.clearsListing
+            ? "transfer domain ownership and clear any active listing"
+            : "transfer domain ownership";
+    }
+    if (economicEffect.kind === "listing-set") {
+        return `set the listing price to ${economicEffect.listedPriceCogtoshi} cogtoshi in COG state`;
+    }
+    return "clear the active listing in COG state";
+}
+export function formatDomainAdminSenderSummary(result) {
+    if (result.resolved === null || result.resolved === undefined) {
+        return "unknown";
+    }
+    return `${result.resolved.sender.selector} (${result.resolved.sender.address})`;
+}
+export function formatDomainAdminTargetSummary(result) {
+    if (result.resolved?.target !== null && result.resolved?.target !== undefined) {
+        return result.resolved.target.address ?? `spk:${result.resolved.target.scriptPubKeyHex}`;
+    }
+    if (result.recipientScriptPubKeyHex === null) {
+        return "clear";
+    }
+    if (result.recipientScriptPubKeyHex === undefined) {
+        return "none";
+    }
+    return `spk:${result.recipientScriptPubKeyHex}`;
+}
+export function formatDomainAdminEffect(result) {
+    const effect = result.resolved?.effect;
+    if (effect === null || effect === undefined) {
+        return "unknown";
+    }
+    switch (effect.kind) {
+        case "endpoint-set":
+            return `set the endpoint payload to ${effect.byteLength} bytes`;
+        case "endpoint-clear":
+            return "clear the endpoint payload";
+        case "delegate-set":
+            return "set the delegate target";
+        case "delegate-clear":
+            return "clear the delegate target";
+        case "miner-set":
+            return "set the designated miner target";
+        case "miner-clear":
+            return "clear the designated miner target";
+        case "canonicalize-owner":
+            return "canonicalize the current anchored owner";
+    }
+}
+export function formatDomainAdminPayloadSummary(result) {
+    const effect = result.resolved?.effect;
+    if (effect?.kind === "endpoint-set") {
+        return `${effect.byteLength} bytes`;
+    }
+    if (effect?.kind === "endpoint-clear") {
+        return "clear";
+    }
+    if (result.endpointValueHex === null || result.endpointValueHex === undefined) {
+        return "none";
+    }
+    return result.endpointValueHex === "" ? "clear" : `${result.endpointValueHex.length / 2} bytes`;
+}
+export function formatFieldSenderSummary(result) {
+    if (result.resolved === null || result.resolved === undefined) {
+        return "unknown";
+    }
+    return `${result.resolved.sender.selector} (${result.resolved.sender.address})`;
+}
+export function formatFieldPath(result) {
+    return result.resolved?.path ?? "unknown";
+}
+export function formatFieldValueSummary(result) {
+    if (result.resolved?.value !== null && result.resolved?.value !== undefined) {
+        return `format ${result.resolved.value.format}, ${result.resolved.value.byteLength} bytes`;
+    }
+    return "none";
+}
+export function formatFieldEffect(result) {
+    const effect = result.resolved?.effect;
+    if (effect === null || effect === undefined) {
+        return "unknown";
+    }
+    switch (effect.kind) {
+        case "create-empty-field":
+            return `burn ${effect.burnCogtoshi} cogtoshi to create an empty field`;
+        case "create-and-initialize-field":
+            return `burn ${effect.tx1BurnCogtoshi} cogtoshi in Tx1 and ${effect.tx2AdditionalBurnCogtoshi} additional cogtoshi in Tx2`;
+        case "write-field-value":
+            return `burn ${effect.burnCogtoshi} cogtoshi to write the field value`;
+        case "clear-field-value":
+            return "clear the field value with no additional COG burn";
+    }
+}
+export function formatCogSenderSummary(result) {
+    return `${result.resolved.sender.selector} (${result.resolved.sender.address})`;
+}
+export function formatCogClaimPath(result) {
+    return result.resolved.claimPath ?? "unknown";
+}
+export function formatReputationSenderSummary(result) {
+    if (result.resolved === null || result.resolved === undefined) {
+        return "unknown";
+    }
+    return `${result.resolved.sender.selector} (${result.resolved.sender.address})`;
+}
+export function formatReputationReviewSummary(result) {
+    if (result.resolved === null || result.resolved === undefined) {
+        return result.reviewIncluded ? "included" : "none";
+    }
+    if (!result.resolved.review.included || result.resolved.review.byteLength === null) {
+        return "none";
+    }
+    return `included (${result.resolved.review.byteLength} bytes)`;
+}
+export function formatReputationEffect(result) {
+    const effect = result.resolved?.effect;
+    if (effect === null || effect === undefined) {
+        return "unknown";
+    }
+    if (effect.kind === "give-support") {
+        return `burn ${effect.burnCogtoshi} cogtoshi to publish support`;
+    }
+    return `revoke visible support with no refund of the previously burned ${effect.burnCogtoshi} cogtoshi`;
+}

package/dist/cli/mutation-text-write.d.ts

@@ -0,0 +1,13 @@
+import type { WritableLike } from "./types.js";
+export interface MutationTextField {
+    label: string;
+    value: string;
+    when?: boolean;
+}
+export declare function writeMutationTextResult(stream: WritableLike, options: {
+    heading: string;
+    fields: MutationTextField[];
+    reusedExisting?: boolean;
+    reusedMessage?: string;
+    trailerLines?: string[];
+}): void;

package/dist/cli/mutation-text-write.js

@@ -0,0 +1,16 @@
+import { writeLine } from "./io.js";
+export function writeMutationTextResult(stream, options) {
+    writeLine(stream, options.heading);
+    for (const field of options.fields) {
+        if (field.when === false) {
+            continue;
+        }
+        writeLine(stream, `${field.label}: ${field.value}`);
+    }
+    if (options.reusedExisting === true && options.reusedMessage !== undefined) {
+        writeLine(stream, options.reusedMessage);
+    }
+    for (const line of options.trailerLines ?? []) {
+        writeLine(stream, line);
+    }
+}

package/dist/cli/output.d.ts

@@ -0,0 +1,185 @@
+import type { CommandName, OutputMode, ParsedCliArgs, WritableLike } from "./types.js";
+export interface JsonAvailabilityEntry {
+    available: boolean;
+    stale: boolean;
+    reason: string | null;
+    state?: string | null;
+    source?: string | null;
+    operatorValidationState?: string | null;
+    cooldownActive?: boolean | null;
+    publishState?: string | null;
+    replicaStatus?: string | null;
+    serviceApiVersion?: string | null;
+    binaryVersion?: string | null;
+    buildId?: string | null;
+    serviceInstanceId?: string | null;
+    processId?: number | null;
+    walletRootId?: string | null;
+    chain?: string | null;
+    dataDir?: string | null;
+    runtimeRoot?: string | null;
+    startedAtUnixMs?: number | null;
+    updatedAtUnixMs?: number | null;
+    schemaVersion?: string | null;
+    daemonInstanceId?: string | null;
+    snapshotSeq?: string | null;
+    heartbeatAtUnixMs?: number | null;
+    openedAtUnixMs?: number | null;
+    activeSnapshotCount?: number | null;
+    backlogBlocks?: number | null;
+    reorgDepth?: number | null;
+    lastError?: string | null;
+    appliedTipHeight?: number | null;
+    appliedTipHash?: string | null;
+    coreBestHeight?: number | null;
+    coreBestHash?: string | null;
+}
+export interface JsonPage {
+    limit: number | null;
+    returned: number;
+    truncated: boolean;
+    moreAvailable: boolean | null;
+    totalKnown: number | null;
+}
+export interface StableJsonEnvelopeBase {
+    schema: string;
+    command: string;
+    generatedAtUnixMs: number;
+    warnings: string[];
+    explanations: string[];
+    nextSteps: string[];
+}
+export interface StableJsonSuccessEnvelope<T> extends StableJsonEnvelopeBase {
+    ok: true;
+    data: T;
+}
+export interface StableJsonErrorEnvelope extends StableJsonEnvelopeBase {
+    ok: false;
+    error: {
+        code: string;
+        message: string;
+        details: Record<string, unknown>;
+    };
+}
+export interface MutationJsonEnvelopeBase {
+    schema: string;
+    ok: boolean;
+    command: string;
+    generatedAtUnixMs: number;
+    outcome: string;
+    warnings: string[];
+    explanations: string[];
+    nextSteps: string[];
+}
+export interface MutationJsonSuccessEnvelope<T> extends MutationJsonEnvelopeBase {
+    ok: true;
+    data: T;
+}
+export interface MutationJsonErrorEnvelope extends MutationJsonEnvelopeBase {
+    ok: false;
+    error: {
+        code: string;
+        message: string;
+        details: Record<string, unknown>;
+    };
+}
+export interface PreviewJsonEnvelopeBase {
+    schema: string;
+    ok: boolean;
+    command: string;
+    generatedAtUnixMs: number;
+    outcome: string;
+    warnings: string[];
+    explanations: string[];
+    nextSteps: string[];
+}
+export interface PreviewJsonSuccessEnvelope<T> extends PreviewJsonEnvelopeBase {
+    ok: true;
+    data: T;
+}
+export interface PreviewJsonErrorEnvelope extends PreviewJsonEnvelopeBase {
+    ok: false;
+    error: {
+        code: string;
+        message: string;
+        details: Record<string, unknown>;
+    };
+}
+export declare function writeJsonValue(stream: WritableLike, value: unknown): void;
+export declare function isStructuredOutputMode(mode: OutputMode): boolean;
+export declare function createSuccessEnvelope<T>(schema: string, command: string, data: T, options?: {
+    warnings?: string[];
+    explanations?: string[];
+    nextSteps?: string[];
+    generatedAtUnixMs?: number;
+}): StableJsonSuccessEnvelope<T>;
+export declare function createErrorEnvelope(schema: string, command: string, errorCode: string, message: string, options?: {
+    warnings?: string[];
+    explanations?: string[];
+    nextSteps?: string[];
+    details?: Record<string, unknown>;
+    generatedAtUnixMs?: number;
+}): StableJsonErrorEnvelope;
+export declare function createPreviewSuccessEnvelope<T>(schema: string, command: string, outcome: string, data: T, options?: {
+    warnings?: string[];
+    explanations?: string[];
+    nextSteps?: string[];
+    generatedAtUnixMs?: number;
+}): PreviewJsonSuccessEnvelope<T>;
+export declare function createMutationSuccessEnvelope<T>(schema: string, command: string, outcome: string, data: T, options?: {
+    warnings?: string[];
+    explanations?: string[];
+    nextSteps?: string[];
+    generatedAtUnixMs?: number;
+}): MutationJsonSuccessEnvelope<T>;
+export declare function createPreviewErrorEnvelope(schema: string, command: string, errorCode: string, message: string, options?: {
+    outcome?: string;
+    warnings?: string[];
+    explanations?: string[];
+    nextSteps?: string[];
+    details?: Record<string, unknown>;
+    generatedAtUnixMs?: number;
+}): PreviewJsonErrorEnvelope;
+export declare function createMutationErrorEnvelope(schema: string, command: string, errorCode: string, message: string, options?: {
+    outcome?: string;
+    warnings?: string[];
+    explanations?: string[];
+    nextSteps?: string[];
+    details?: Record<string, unknown>;
+    generatedAtUnixMs?: number;
+}): MutationJsonErrorEnvelope;
+export declare function normalizeListPage<T>(items: readonly T[], options: {
+    limit: number | null;
+    all: boolean;
+    defaultLimit: number;
+}): {
+    items: T[];
+    page: JsonPage;
+};
+export declare function createTruncationNote(page: JsonPage): string | null;
+export declare function classifyCliError(error: unknown): {
+    exitCode: number;
+    errorCode: string;
+    message: string;
+};
+export declare function formatCliTextError(error: unknown): string[] | null;
+export declare function createCliErrorPresentation(errorCode: string, fallbackMessage: string): {
+    what: string;
+    why: string | null;
+    next: string | null;
+} | null;
+export declare function describeCanonicalCommand(parsed: ParsedCliArgs): string;
+export declare function inferOutputMode(argv: readonly string[]): OutputMode;
+export declare function resolveStableJsonSchema(parsed: ParsedCliArgs): string | null;
+export declare function resolveStableMutationJsonSchema(parsed: ParsedCliArgs): string | null;
+export declare function resolveStableMiningControlJsonSchema(parsed: ParsedCliArgs): string | null;
+export declare function resolvePreviewJsonSchema(parsed: ParsedCliArgs): string | null;
+export declare function isJsonOutputSupportedCommand(command: CommandName | null): boolean;
+export declare function isPreviewJsonOutputSupportedCommand(command: CommandName | null): boolean;
+export declare function createCommandJsonErrorEnvelope(parsed: ParsedCliArgs, error: unknown): StableJsonErrorEnvelope | MutationJsonErrorEnvelope | PreviewJsonErrorEnvelope;
+export declare function writeHandledCliError(options: {
+    parsed: ParsedCliArgs;
+    stdout: WritableLike;
+    stderr: WritableLike;
+    error: unknown;
+}): number;