@le-space/node 0.1.0

package/README.md

@@ -0,0 +1,5 @@
+# @shared-aleph/node
+
+Node-specific adapters, CLI entrypoints, environment parsing, and GitHub output
+helpers will live here.
+

package/index.d.ts

@@ -0,0 +1,218 @@
+import * as _shared_aleph_shared_types from '@shared-aleph/shared-types';
+import { MessageSigner, InstanceAllocation, PortMapping, RuntimeDiagnostics, CrnRecord, RootfsRequiredPortForward, MessageHasher, RootfsManifest } from '@shared-aleph/shared-types';
+
+declare function requiredEnv(name: string, env?: NodeJS.ProcessEnv): string;
+declare function optionalEnv(name: string, fallback?: string, env?: NodeJS.ProcessEnv): string;
+declare function integerEnv(name: string, fallback: number, env?: NodeJS.ProcessEnv): number;
+declare function booleanEnv(name: string, fallback: boolean, env?: NodeJS.ProcessEnv): boolean;
+declare function jsonEnv<T>(name: string, fallback: string, env?: NodeJS.ProcessEnv): T;
+
+declare function appendGithubOutput(name: string, value: unknown, env?: NodeJS.ProcessEnv): Promise<void>;
+declare function appendGithubSummary(lines: string[], env?: NodeJS.ProcessEnv): Promise<void>;
+declare function actionLog(level: 'notice' | 'warning' | 'error' | string, message: string, options?: {
+    githubActions?: boolean;
+    stderr?: NodeJS.WriteStream;
+}): void;
+
+type WalletLike = {
+    address?: string;
+    getAddress?(): Promise<string>;
+    signMessage(message: string): Promise<string>;
+};
+type WalletCtor = new (privateKey: string) => WalletLike;
+interface PrivateKeyIdentity {
+    address: string;
+    signer: MessageSigner;
+}
+declare function createPrivateKeySigner(privateKey: string, options?: {
+    walletCtor?: WalletCtor;
+}): Promise<MessageSigner>;
+declare function createPrivateKeyIdentity(privateKey: string, options?: {
+    walletCtor?: WalletCtor;
+}): Promise<PrivateKeyIdentity>;
+
+interface DeployMetadataResult {
+    peer_id?: string;
+    probe_multiaddrs?: string[];
+    browser_bootstrap_multiaddrs?: string[];
+    [key: string]: unknown;
+}
+interface DeployConfigurationResult {
+    metadata?: DeployMetadataResult | null;
+    [key: string]: unknown;
+}
+interface DeployOutputResult {
+    sender?: string;
+    itemHash?: string;
+    httpStatus?: number;
+    status?: string;
+    selectedCrn?: {
+        hash?: string;
+        name?: string;
+    } | null;
+    portForwarding?: {
+        aggregateItemHash?: string;
+        aggregateStatus?: string;
+    } | null;
+    runtime?: {
+        allocation?: InstanceAllocation | null;
+        hostIpv4?: string | null;
+        ipv6?: string | null;
+        proxyUrl?: string | null;
+        sshCommand?: string | null;
+        setupHealth?: {
+            ok?: boolean;
+            status?: number;
+            url?: string;
+            error?: string;
+        } | null;
+        mappedPorts?: Record<string, PortMapping>;
+        diagnostics?: RuntimeDiagnostics | null;
+        selectedCrn?: CrnRecord | null;
+    } | null;
+    configuration?: DeployConfigurationResult | null;
+    verification?: {
+        ok?: boolean;
+        [key: string]: unknown;
+    } | null;
+}
+declare function emitDeployOutputs(deployResult: DeployOutputResult, env?: NodeJS.ProcessEnv): Promise<{
+    runtimeJson: string;
+    verificationJson: string;
+}>;
+declare function emitGeocodedCrnOutputs(geocodedCrns: unknown[], env?: NodeJS.ProcessEnv): Promise<void>;
+
+interface DeployPlan {
+    profile: string;
+    privateKey: string;
+    apiHost: string;
+    crnListUrl: string;
+    name: string;
+    sshPublicKey: string;
+    rootfsItemHash: string;
+    rootfsVersion: string;
+    rootfsSizeMiB: number;
+    crnHash: string;
+    preferredCountryCode: string;
+    geoCrnLimit: number;
+    maxCrnAttempts: number;
+    vcpus: number;
+    memoryMiB: number;
+    seconds: number;
+    channel: string;
+    waitAttempts: number;
+    waitDelayMs: number;
+    runtimeAttempts: number;
+    runtimeDelayMs: number;
+    setupAttempts: number;
+    setupDelayMs: number;
+    verifyAttempts: number;
+    verifyDelayMs: number;
+    tcpTimeoutMs: number;
+    httpTimeoutMs: number;
+    metadataAttempts: number;
+    metadataDelayMs: number;
+    metadataTimeoutMs: number;
+    configureTimeoutMs: number;
+    enableCaddyProxy: boolean;
+    autoConfigure: boolean;
+    verifyReachability: boolean;
+    requiredPorts: RootfsRequiredPortForward[];
+    publishPortForwards: boolean;
+}
+declare function parseDeployPlan(env?: NodeJS.ProcessEnv): DeployPlan;
+
+interface DeployExecutorDependencies {
+    fetch?: typeof fetch;
+    sleep?: (ms: number) => Promise<void>;
+    tcpProbe?: (host: string, port: number, timeoutMs?: number) => Promise<{
+        ok: boolean | null;
+        error?: string;
+    }>;
+    signer?: MessageSigner;
+    sender?: string;
+    hasher?: MessageHasher;
+    manifest?: RootfsManifest | null;
+}
+declare function executeDeployPlan(plan: DeployPlan, dependencies?: DeployExecutorDependencies): Promise<DeployOutputResult>;
+
+interface FetchLikeResponse {
+    ok: boolean;
+    status: number;
+    url?: string;
+    json(): Promise<unknown>;
+}
+type FetchLike = (url: string, init?: RequestInit) => Promise<FetchLikeResponse>;
+
+declare function listGeocodedCrns(options: {
+    fetch: FetchLike;
+    url?: string;
+    limit?: number;
+    dnsResolveUrl?: string;
+    countryLookupBaseUrl?: string;
+}): Promise<CrnRecord[]>;
+
+interface JsonFetchLikeResponse {
+    ok: boolean;
+    status: number;
+    json(): Promise<unknown>;
+}
+type JsonFetchLike = (url: string, init?: RequestInit) => Promise<JsonFetchLikeResponse>;
+
+interface RetentionRecord {
+    instance_item_hash: string;
+    rootfs_item_hash: string;
+    site_item_hash: string;
+    rootfs_cid: string;
+    site_url: string;
+    relay_peer_id: string;
+    rootfs_version: string;
+    deployed_at: string;
+    vm_name: string;
+}
+declare function retainSuccessfulDeployments(args: {
+    sender: string;
+    currentRecord: unknown;
+    keepCount: number;
+    signer: MessageSigner;
+    hasher: MessageHasher;
+    fetch: JsonFetchLike;
+    aggregateKey?: string;
+    extraForgetHashes?: string[];
+    reason?: string;
+    channel?: string;
+    apiHost?: string;
+    now?: number;
+}): Promise<{
+    sender: string;
+    aggregateKey: string;
+    keepCount: number;
+    aggregatePublication: {
+        itemHash: string;
+        status: _shared_aleph_shared_types.MessageStatus;
+        response: _shared_aleph_shared_types.AlephBroadcastResponse;
+        httpStatus: number;
+    };
+    retainedRecords: RetentionRecord[];
+    prunedRecords: RetentionRecord[];
+    forgetHashes: string[];
+    forgetResult: {
+        sender: string;
+        itemHash: string;
+        response: _shared_aleph_shared_types.AlephBroadcastResponse;
+        httpStatus: number;
+        status: _shared_aleph_shared_types.MessageStatus;
+    } | null;
+}>;
+
+declare function buildScaffoldDeployResult(env?: NodeJS.ProcessEnv): DeployOutputResult;
+declare function runActionMode(env?: NodeJS.ProcessEnv, hooks?: {
+    stdout?: (text: string) => void;
+    listGeocodedCrns?: typeof listGeocodedCrns;
+    deployExecutor?: typeof executeDeployPlan;
+    retainSuccessfulDeployments?: typeof retainSuccessfulDeployments;
+    createPrivateKeyIdentity?: (privateKey: string) => Promise<PrivateKeyIdentity>;
+}): Promise<void>;
+declare function main(): Promise<void>;
+
+export { type DeployConfigurationResult, type DeployExecutorDependencies, type DeployMetadataResult, type DeployOutputResult, type DeployPlan, type PrivateKeyIdentity, actionLog, appendGithubOutput, appendGithubSummary, booleanEnv, buildScaffoldDeployResult, createPrivateKeyIdentity, createPrivateKeySigner, emitDeployOutputs, emitGeocodedCrnOutputs, executeDeployPlan, integerEnv, jsonEnv, main, optionalEnv, parseDeployPlan, requiredEnv, runActionMode };