@solana-mobile/dapp-store-cli 0.16.0 → 1.0.0

package/src/publication/__tests__/PublicationProgressReporter.test.ts

@@ -0,0 +1,210 @@
+import { expect, jest, test } from '@jest/globals';
+import { Writable } from 'node:stream';
+
+import { createPublicationProgressReporter } from '../PublicationProgressReporter';
+
+function createTestStream() {
+  const output: string[] = [];
+  const stream = new Writable({
+    write(chunk, _encoding, callback) {
+      output.push(String(chunk));
+      callback();
+    },
+  }) as Writable & NodeJS.WriteStream & { output: string[] };
+
+  stream.isTTY = false;
+  stream.columns = 120;
+  stream.output = output;
+
+  return stream;
+}
+
+test('local file upload progress materially advances the bar', () => {
+  const logSpy = jest.spyOn(console, 'log').mockImplementation(() => {});
+  const stream = createTestStream();
+  try {
+    const reporter = createPublicationProgressReporter({
+      title: 'Publishing version',
+      mode: 'new-version',
+      stream,
+    }) as any;
+
+    reporter.start({
+      metadata: {
+        sourceKind: 'apk-file',
+        fileName: 'app-release.apk',
+      },
+    });
+
+    reporter.logger.debug('Uploading APK to portal storage', {
+      step: 'source.upload',
+      status: 'running',
+      fileName: 'app-release.apk',
+      fileSize: 100,
+      bytesUploaded: 50,
+      bytesTotal: 100,
+      stepProgress: 0.5,
+    });
+
+    const lines = reporter.buildLines();
+
+    expect(reporter.getProgressPercent()).toBeGreaterThan(0.2);
+    expect(lines[1]).toContain('23%');
+    expect(lines).toContain('Upload: 50 B / 100 B (50%)');
+  } finally {
+    logSpy.mockRestore();
+  }
+});
+
+test('ingestion status updates continue advancing overall progress', () => {
+  const logSpy = jest.spyOn(console, 'log').mockImplementation(() => {});
+  const stream = createTestStream();
+  try {
+    const reporter = createPublicationProgressReporter({
+      title: 'Publishing version',
+      mode: 'new-version',
+      stream,
+    }) as any;
+
+    reporter.start({
+      metadata: {
+        sourceKind: 'apk-file',
+        fileName: 'app-release.apk',
+      },
+    });
+
+    reporter.logger.info('APK uploaded to portal storage', {
+      step: 'source.upload',
+      status: 'complete',
+      fileName: 'app-release.apk',
+    });
+
+    reporter.logger.info('Extracting APK metadata', {
+      step: 'ingestion.wait',
+      status: 'running',
+      ingestionStatus: 'processing',
+      ingestionStage: 'ExtractingApk',
+      ingestionDetail: 'Extracting APK metadata',
+      ingestionProgress: 45,
+      stepProgress: 0.7,
+    });
+
+    const lines = reporter.buildLines();
+
+    expect(reporter.getProgressPercent()).toBeGreaterThan(0.55);
+    expect(lines[1]).toContain('57%');
+    expect(lines).toContain('Ingestion: Extracting APK metadata (45%)');
+  } finally {
+    logSpy.mockRestore();
+  }
+});
+
+test('ingestion detail and percentage are rendered while polling', () => {
+  const logSpy = jest.spyOn(console, 'log').mockImplementation(() => {});
+  const stream = createTestStream();
+  try {
+    const reporter = createPublicationProgressReporter({
+      title: 'Publishing version',
+      mode: 'new-version',
+      stream,
+    }) as any;
+
+    reporter.start({
+      metadata: {
+        sourceKind: 'apk-file',
+        fileName: 'app-release.apk',
+      },
+    });
+
+    reporter.logger.info('Extracting APK metadata', {
+      step: 'ingestion.wait',
+      status: 'running',
+      ingestionStatus: 'processing',
+      ingestionProgress: 45,
+      ingestionStage: 'ExtractingApk',
+      ingestionDetail: 'Extracting APK metadata',
+      stepProgress: 0.45,
+    });
+
+    const lines = reporter.buildLines();
+
+    expect(lines).toContain('Ingestion: Extracting APK metadata (45%)');
+  } finally {
+    logSpy.mockRestore();
+  }
+});
+
+test('verbose mode prints detailed identifiers as they arrive', () => {
+  const logSpy = jest.spyOn(console, 'log').mockImplementation(() => {});
+  const stream = createTestStream();
+  try {
+    const reporter = createPublicationProgressReporter({
+      title: 'Publishing version',
+      mode: 'new-version',
+      verbose: true,
+      stream,
+    });
+
+    reporter.start({
+      metadata: {
+        sourceKind: 'apk-file',
+        fileName: 'app-release.apk',
+      },
+    });
+
+    reporter.logger.info('Ingestion session created', {
+      step: 'ingestion.create',
+      status: 'complete',
+      releaseId: 'release-123',
+      ingestionSessionId: 'ingestion-456',
+    });
+
+    reporter.logger.info('Publication session loaded', {
+      step: 'session.load',
+      status: 'complete',
+      publicationSessionId: 'session-789',
+    });
+
+    reporter.logger.info('Release NFT transaction submitted', {
+      step: 'mint.submit',
+      status: 'complete',
+      transactionSignature: 'release-tx-sig',
+    });
+
+    reporter.logger.info('Release collection verified', {
+      step: 'verify.submit',
+      status: 'complete',
+      transactionSignature: 'collection-tx-sig',
+    });
+
+    reporter.logger.info('Attestation payload created', {
+      step: 'attestation.create',
+      status: 'complete',
+      requestUniqueId: 'attest-111',
+    });
+
+    reporter.logger.info('Release submitted to store', {
+      step: 'submit.store',
+      status: 'complete',
+      hubspotTicketId: 'ticket-222',
+    });
+
+    const output = stream.output.join('');
+
+    expect(output).toContain('Verbose: Release ID: release-123');
+    expect(output).toContain('Verbose: Ingestion session ID: ingestion-456');
+    expect(output).toContain('Verbose: Publication session ID: session-789');
+    expect(output).toContain(
+      'Verbose: Release transaction signature: release-tx-sig',
+    );
+    expect(output).toContain(
+      'Verbose: Collection transaction signature: collection-tx-sig',
+    );
+    expect(output).toContain(
+      'Verbose: Attestation request ID: attest-111',
+    );
+    expect(output).toContain('Verbose: Ticket ID: ticket-222');
+  } finally {
+    logSpy.mockRestore();
+  }
+});

package/src/publication/__tests__/fundingPreflight.test.ts

@@ -0,0 +1,78 @@
+import { describe, expect, it, jest } from "@jest/globals";
+import { PublicKey } from "@solana/web3.js";
+
+import {
+  ensurePublicationSignerBalance,
+  MIN_PUBLICATION_SIGNER_BALANCE_LAMPORTS,
+  resolveFundingPreflightRpcUrl,
+} from "../fundingPreflight.js";
+
+describe("resolveFundingPreflightRpcUrl", () => {
+  it("defaults to mainnet when local-dev is not enabled", () => {
+    expect(resolveFundingPreflightRpcUrl({})).toBe(
+      "https://api.mainnet-beta.solana.com"
+    );
+  });
+
+  it("skips the default RPC in local-dev mode", () => {
+    expect(resolveFundingPreflightRpcUrl({ localDev: true })).toBeUndefined();
+  });
+
+  it("honors an explicit RPC URL", () => {
+    expect(
+      resolveFundingPreflightRpcUrl({
+        localDev: true,
+        rpcUrl: "https://rpc.example.com",
+      })
+    ).toBe("https://rpc.example.com");
+  });
+});
+
+describe("ensurePublicationSignerBalance", () => {
+  const publicKey = new PublicKey(new Uint8Array(32).fill(7)).toBase58();
+
+  it("throws before publication when the signer balance is too low", async () => {
+    await expect(
+      ensurePublicationSignerBalance(
+        {
+          publicKey,
+        },
+        () => ({
+          getBalance: jest
+            .fn()
+            .mockResolvedValue(MIN_PUBLICATION_SIGNER_BALANCE_LAMPORTS - 1),
+        })
+      )
+    ).rejects.toThrow("publishing needs at least");
+  });
+
+  it("returns without warning when the signer balance is sufficient", async () => {
+    const result = await ensurePublicationSignerBalance(
+      {
+        publicKey,
+      },
+      () => ({
+        getBalance: jest
+          .fn()
+          .mockResolvedValue(MIN_PUBLICATION_SIGNER_BALANCE_LAMPORTS + 1),
+      })
+    );
+
+    expect(result).toBeUndefined();
+  });
+
+  it("returns a warning when the RPC balance check fails", async () => {
+    const result = await ensurePublicationSignerBalance(
+      {
+        publicKey,
+      },
+      () => ({
+        getBalance: jest.fn().mockRejectedValue(new Error("RPC timeout")),
+      })
+    );
+
+    expect(result).toContain("Continuing without a SOL preflight check");
+    expect(result).toContain("RPC timeout");
+  });
+});
+

package/src/publication/__tests__/publicationSummary.test.ts

@@ -0,0 +1,30 @@
+import { expect, test } from '@jest/globals';
+
+import { extractPublicationSummaryLines } from '../publicationSummary';
+
+test('summary keeps the completion message and only the compact fields', () => {
+  const lines = extractPublicationSummaryLines({
+    releaseId: 'release-123',
+    publicationSessionId: 'session-123',
+    ingestionSessionId: 'ingestion-123',
+    releaseMintAddress: 'release-mint-abc',
+    collectionMintAddress: 'collection-mint-def',
+    releaseTransactionSignature: 'release-tx',
+    collectionTransactionSignature: 'collection-tx',
+    attestationRequestUniqueId: 'attest-123',
+    hubspotTicketId: 'ticket-123',
+  });
+
+  expect(lines).toEqual([
+    'This app is now in review.',
+    'Release mint address: release-mint-abc',
+    'Collection mint address: collection-mint-def',
+    'Ticket ID: ticket-123',
+  ]);
+});
+
+test('summary still shows the in-review message when no fields are available', () => {
+  expect(extractPublicationSummaryLines(undefined)).toEqual([
+    'This app is now in review.',
+  ]);
+});

package/src/publication/cliValidation.ts

@@ -0,0 +1,264 @@
+import fs from "node:fs";
+import path from "node:path";
+
+export const DEFAULT_LOCAL_PORTAL_URL = "http://localhost:3333";
+export const DEFAULT_PRODUCTION_PORTAL_URL = "https://publish.solanamobile.com";
+export const DEFAULT_API_KEY_ENV = "DAPP_STORE_API_KEY";
+export const UPDATED_PUBLISHING_CLI_DOCS_URL =
+  "https://docs.solanamobile.com/dapp-store/publishing-cli";
+
+export type NewVersionCliOptions = {
+  apkFile?: string;
+  apkUrl?: string;
+  whatsNew?: string;
+  portalUrl?: string;
+  apiKeyEnv?: string;
+  apiKeyStdin?: boolean;
+  keypair?: string;
+  rpcUrl?: string;
+  localDev?: boolean;
+  skipSelfUpdate?: boolean;
+  idempotencyKey?: string;
+  dappId?: string;
+  verbose?: boolean;
+};
+
+export type ResumeCliOptions = {
+  releaseId?: string;
+  sessionId?: string;
+  resumeRelease?: string;
+  resumeSession?: string;
+  portalUrl?: string;
+  apiKeyEnv?: string;
+  apiKeyStdin?: boolean;
+  keypair?: string;
+  rpcUrl?: string;
+  localDev?: boolean;
+  skipSelfUpdate?: boolean;
+  verbose?: boolean;
+};
+
+export type ResolvedPortalTargets = {
+  apiBaseUrl: string;
+};
+
+function normalizeUrl(value: string, label: string): string {
+  try {
+    return new URL(value).toString().replace(/\/$/, "");
+  } catch {
+    throw new Error(`Invalid ${label}: ${value}`);
+  }
+}
+
+function deriveApiBaseUrl(portalUrl: string): string {
+  const normalized = new URL(portalUrl);
+  const basePath = normalized.pathname.replace(/\/$/, "");
+  normalized.pathname = basePath.length === 0 ? "/api" : `${basePath}/api`;
+  return normalized.toString().replace(/\/$/, "");
+}
+
+function isLocalhostUrl(url: string): boolean {
+  try {
+    const parsed = new URL(url);
+    return (
+      parsed.hostname === "localhost" ||
+      parsed.hostname === "127.0.0.1" ||
+      parsed.hostname === "::1" ||
+      parsed.hostname === "[::1]"
+    );
+  } catch {
+    return false;
+  }
+}
+
+export function resolvePortalTargets(input: {
+  portalUrl?: string;
+  localDev?: boolean;
+}): ResolvedPortalTargets {
+  const portalUrl =
+    input.portalUrl ??
+    process.env.DAPP_STORE_PORTAL_URL ??
+    (input.localDev ? DEFAULT_LOCAL_PORTAL_URL : undefined) ??
+    DEFAULT_PRODUCTION_PORTAL_URL;
+
+  const normalizedPortalUrl = normalizeUrl(portalUrl, "portal URL");
+  const normalizedApiBaseUrl = normalizeUrl(
+    deriveApiBaseUrl(normalizedPortalUrl),
+    "portal API base URL"
+  );
+
+  if (input.localDev) {
+    const localTargets = [
+      ["portal URL", normalizedPortalUrl],
+      ["portal API base URL", normalizedApiBaseUrl],
+    ] as const;
+
+    const nonLocalTarget = localTargets.find(
+      ([, value]) => !isLocalhostUrl(value)
+    );
+    if (nonLocalTarget) {
+      throw new Error(
+        `--local-dev only allows localhost portal endpoints. Received ${nonLocalTarget[0]}: ${nonLocalTarget[1]}`
+      );
+    }
+  }
+
+  if (!input.localDev) {
+    const portalTargets = [
+      ["portal URL", normalizedPortalUrl],
+      ["portal API base URL", normalizedApiBaseUrl],
+    ] as const;
+    const insecureTarget = portalTargets.find(([, value]) => {
+      return new URL(value).protocol !== "https:";
+    });
+
+    if (insecureTarget) {
+      throw new Error(
+        `Portal endpoints must use HTTPS unless --local-dev is set. Received ${insecureTarget[0]}: ${insecureTarget[1]}`
+      );
+    }
+  }
+
+  return {
+    apiBaseUrl: normalizedApiBaseUrl,
+  };
+}
+
+export function validateNewVersionArgs(input: NewVersionCliOptions): void {
+  const apkSourceCount = (input.apkFile ? 1 : 0) + (input.apkUrl ? 1 : 0);
+  if (apkSourceCount !== 1) {
+    throw new Error("Specify exactly one of `--apk-file` or `--apk-url`.");
+  }
+
+  if (!input.whatsNew || input.whatsNew.trim().length === 0) {
+    throw new Error("`--whats-new` is required.");
+  }
+
+  if (!input.keypair || input.keypair.trim().length === 0) {
+    throw new Error("`--keypair` is required.");
+  }
+
+  if (input.apkFile) {
+    const apkPath = path.resolve(input.apkFile);
+    if (!fs.existsSync(apkPath)) {
+      throw new Error(`APK file not found: ${apkPath}`);
+    }
+  }
+
+  if (input.apkUrl) {
+    let parsed: URL;
+    try {
+      parsed = new URL(input.apkUrl);
+    } catch {
+      throw new Error("`--apk-url` must be a valid HTTPS URL.");
+    }
+
+    if (parsed.protocol !== "https:") {
+      throw new Error("`--apk-url` must use HTTPS.");
+    }
+  }
+}
+
+export function validateResumeArgs(input: ResumeCliOptions): void {
+  const releaseId = resolveResumeTarget(
+    input.releaseId,
+    input.resumeRelease,
+    "--release-id",
+    "--resume-release"
+  );
+  const sessionId = resolveResumeTarget(
+    input.sessionId,
+    input.resumeSession,
+    "--session-id",
+    "--resume-session"
+  );
+  const resumeTargetCount = (releaseId ? 1 : 0) + (sessionId ? 1 : 0);
+  if (resumeTargetCount !== 1) {
+    throw new Error("Specify exactly one of `--release-id` or `--session-id`.");
+  }
+
+  if (!input.keypair || input.keypair.trim().length === 0) {
+    throw new Error("`--keypair` is required.");
+  }
+}
+
+function resolveResumeTarget(
+  primary?: string,
+  alias?: string,
+  primaryLabel?: string,
+  aliasLabel?: string
+): string | undefined {
+  const trimmedPrimary = primary?.trim();
+  const trimmedAlias = alias?.trim();
+
+  if (trimmedPrimary && trimmedAlias && trimmedPrimary !== trimmedAlias) {
+    throw new Error(
+      `Conflicting values were provided for ${primaryLabel} and ${aliasLabel}.`
+    );
+  }
+
+  return trimmedPrimary ?? trimmedAlias;
+}
+
+export async function resolveApiKey(input: {
+  apiKeyEnv?: string;
+  apiKeyStdin?: boolean;
+}): Promise<string> {
+  const envVarName = input.apiKeyEnv ?? DEFAULT_API_KEY_ENV;
+
+  if (input.apiKeyStdin) {
+    return await readSecretFromStdin();
+  }
+
+  const envValue = process.env[envVarName]?.trim();
+  if (envValue) {
+    return envValue;
+  }
+
+  throw new Error(
+    withUpdatedCliDocs(
+      `Portal API key is required. Set ${envVarName} or pass --api-key-stdin.`
+    )
+  );
+}
+
+export function formatUpdatedCliUsageError(message: string): string {
+  return withUpdatedCliDocs(normalizeCliErrorMessage(message));
+}
+
+async function readSecretFromStdin(): Promise<string> {
+  if (process.stdin.isTTY) {
+    throw new Error(withUpdatedCliDocs("No API key was piped into stdin."));
+  }
+
+  const chunks: Buffer[] = [];
+  for await (const chunk of process.stdin) {
+    chunks.push(Buffer.from(chunk));
+  }
+
+  const value = Buffer.concat(chunks).toString("utf8").trim();
+  if (!value) {
+    throw new Error(withUpdatedCliDocs("No API key was provided on stdin."));
+  }
+
+  return value;
+}
+
+function withUpdatedCliDocs(message: string): string {
+  return [
+    message,
+    "",
+    "The publishing CLI has changed. See the updated usage guide:",
+    UPDATED_PUBLISHING_CLI_DOCS_URL,
+  ].join("\n");
+}
+
+function normalizeCliErrorMessage(message: string): string {
+  const normalized = message.replace(/^error:\s*/i, "").trim();
+  if (normalized.length === 0) {
+    return "Invalid CLI arguments.";
+  }
+
+  const sentence = normalized.endsWith(".") ? normalized : `${normalized}.`;
+  return sentence.charAt(0).toUpperCase() + sentence.slice(1);
+}

package/src/publication/fundingPreflight.ts

@@ -0,0 +1,123 @@
+import {
+  Connection,
+  LAMPORTS_PER_SOL,
+  PublicKey,
+  type Commitment,
+} from "@solana/web3.js";
+
+const BALANCE_CHECK_COMMITMENT: Commitment = "confirmed";
+const DEFAULT_MAINNET_RPC_URL = "https://api.mainnet-beta.solana.com";
+
+// Release NFT minting currently needs roughly ~0.015 SOL in rent plus fees.
+// Keep a small buffer so the CLI fails before uploading the APK.
+export const MIN_PUBLICATION_SIGNER_BALANCE_LAMPORTS = 16_000_000;
+
+type FundingPreflightInput = {
+  localDev?: boolean;
+  publicKey: string;
+  rpcUrl?: string;
+};
+
+type BalanceClient = {
+  getBalance(publicKey: PublicKey): Promise<number>;
+};
+
+type BalanceClientFactory = (rpcUrl: string) => BalanceClient;
+
+function createBalanceClient(rpcUrl: string): BalanceClient {
+  const connection = new Connection(rpcUrl, BALANCE_CHECK_COMMITMENT);
+  return {
+    async getBalance(publicKey: PublicKey) {
+      return await connection.getBalance(publicKey, BALANCE_CHECK_COMMITMENT);
+    },
+  };
+}
+
+function trimOptional(value?: string): string | undefined {
+  const trimmed = value?.trim();
+  return trimmed ? trimmed : undefined;
+}
+
+export function resolveFundingPreflightRpcUrl(input: {
+  localDev?: boolean;
+  rpcUrl?: string;
+}): string | undefined {
+  const explicitRpcUrl = trimOptional(input.rpcUrl);
+  if (explicitRpcUrl) {
+    return explicitRpcUrl;
+  }
+
+  if (input.localDev) {
+    return undefined;
+  }
+
+  return DEFAULT_MAINNET_RPC_URL;
+}
+
+function formatSolAmount(lamports: number): string {
+  return (lamports / LAMPORTS_PER_SOL).toFixed(6);
+}
+
+function buildInsufficientBalanceMessage(input: {
+  balanceLamports: number;
+  publicKey: string;
+  requiredLamports: number;
+}): string {
+  return `Signer ${input.publicKey} has ${formatSolAmount(
+    input.balanceLamports
+  )} SOL, but publishing needs at least ${formatSolAmount(
+    input.requiredLamports
+  )} SOL available before it starts.`;
+}
+
+function buildRpcWarningMessage(rpcUrl: string, error: unknown): string {
+  const detail = error instanceof Error ? error.message : String(error);
+  return [
+    `Unable to confirm the signer balance via ${rpcUrl}.`,
+    `Continuing without a SOL preflight check: ${detail}.`,
+  ].join(" ");
+}
+
+export async function ensurePublicationSignerBalance(
+  input: FundingPreflightInput,
+  clientFactory: BalanceClientFactory = createBalanceClient
+): Promise<string | undefined> {
+  const rpcUrl = resolveFundingPreflightRpcUrl(input);
+  if (!rpcUrl) {
+    return undefined;
+  }
+
+  let publicKey: PublicKey;
+  try {
+    publicKey = new PublicKey(input.publicKey);
+  } catch (error) {
+    const detail = error instanceof Error ? error.message : String(error);
+    throw new Error(
+      `Invalid signer public key for balance preflight: ${input.publicKey}. ${detail}`
+    );
+  }
+
+  try {
+    const balanceLamports = await clientFactory(rpcUrl).getBalance(publicKey);
+    if (balanceLamports < MIN_PUBLICATION_SIGNER_BALANCE_LAMPORTS) {
+      throw new Error(
+        buildInsufficientBalanceMessage({
+          balanceLamports,
+          publicKey: input.publicKey,
+          requiredLamports: MIN_PUBLICATION_SIGNER_BALANCE_LAMPORTS,
+        })
+      );
+    }
+
+    return undefined;
+  } catch (error) {
+    if (
+      error instanceof Error &&
+      error.message.includes("publishing needs at least")
+    ) {
+      throw error;
+    }
+
+    return buildRpcWarningMessage(rpcUrl, error);
+  }
+}