@aifabrix/server-setup 0.1.0

package/dist/backup.spec.js

@@ -0,0 +1,199 @@
+/**
+ * Tests for runBackup with mocked SSH (no real connections).
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import extract from 'extract-zip';
+import Database from 'better-sqlite3';
+import { runBackup, runBackupLocal } from './backup.js';
+import { BUILDER_DB, BACKUP_DB, CONFIG_JSON, JSON_FILES } from './config.js';
+const TEST_TMP_BASE = path.join(process.cwd(), 'tmp');
+const mockConn = {};
+const mockExec = jest.fn();
+const mockReadFile = jest.fn();
+const mockClose = jest.fn();
+jest.mock('./ssh.js', () => ({
+    createSSHClient: jest.fn(() => Promise.resolve(mockConn)),
+    readFile: jest.fn((...args) => mockReadFile(...args)),
+    exec: jest.fn((...args) => mockExec(...args)),
+    close: jest.fn((...args) => mockClose(...args)),
+}));
+describe('runBackup', () => {
+    let outDir;
+    beforeEach(() => {
+        jest.clearAllMocks();
+        fs.mkdirSync(TEST_TMP_BASE, { recursive: true });
+        outDir = fs.mkdtempSync(path.join(TEST_TMP_BASE, 'af-backup-out-'));
+    });
+    afterEach(() => {
+        try {
+            fs.rmSync(outDir, { recursive: true, force: true });
+        }
+        catch {
+            // ignore
+        }
+    });
+    it('builds zip from builder.db when present on server', async () => {
+        const dbPath = path.join(outDir, `minimal-${Date.now()}.db`);
+        const db = new Database(dbPath);
+        db.exec("CREATE TABLE users (id TEXT PRIMARY KEY); INSERT INTO users (id) VALUES ('1');");
+        db.close();
+        const sqliteBuf = fs.readFileSync(dbPath);
+        fs.unlinkSync(dbPath);
+        mockExec.mockResolvedValue({ stdout: '1\n', stderr: '', code: 0 });
+        mockReadFile.mockImplementation((_conn, p) => {
+            if (p.includes('builder.db'))
+                return Promise.resolve(sqliteBuf);
+            return Promise.resolve(Buffer.from(''));
+        });
+        const outPath = path.join(outDir, 'backup.zip');
+        const result = await runBackup({
+            target: 'user@host',
+            dataDir: '/data',
+            outputPath: outPath,
+        });
+        expect(result).toBe(path.resolve(outPath));
+        expect(fs.existsSync(result)).toBe(true);
+        expect(mockClose).toHaveBeenCalledWith(mockConn);
+    });
+    it('builds zip from JSON files when builder.db absent', async () => {
+        mockExec.mockResolvedValue({ stdout: '0\n', stderr: '', code: 0 });
+        mockReadFile.mockImplementation((_conn, p) => {
+            if (p.endsWith('users.json'))
+                return Promise.resolve(Buffer.from('{"users":[{"id":"01","name":"A","email":"a@b.com","createdAt":"2025-01-01"}]}'));
+            if (p.endsWith('tokens.json'))
+                return Promise.resolve(Buffer.from('{"pins":[]}'));
+            if (p.endsWith('secrets.json'))
+                return Promise.resolve(Buffer.from('{"secrets":{}}'));
+            if (p.endsWith('ssh-public-keys.json'))
+                return Promise.resolve(Buffer.from('{"byUser":{}}'));
+            return Promise.reject(new Error('ENOENT'));
+        });
+        const outPath = path.join(outDir, 'backup2.zip');
+        const result = await runBackup({
+            target: 'user@host',
+            dataDir: '/data',
+            outputPath: outPath,
+        });
+        expect(result).toBe(path.resolve(outPath));
+        expect(fs.existsSync(result)).toBe(true);
+        expect(mockClose).toHaveBeenCalledWith(mockConn);
+    });
+    it('handles missing key files (catch path)', async () => {
+        mockExec.mockResolvedValue({ stdout: '0\n', stderr: '', code: 0 });
+        mockReadFile
+            .mockResolvedValueOnce(Buffer.from('{"users":[]}'))
+            .mockResolvedValueOnce(Buffer.from('{"pins":[]}'))
+            .mockResolvedValueOnce(Buffer.from('{"secrets":{}}'))
+            .mockResolvedValueOnce(Buffer.from('{"byUser":{}}'))
+            .mockRejectedValue(new Error('ENOENT'));
+        const outPath = path.join(outDir, 'backup3.zip');
+        const result = await runBackup({
+            target: 'user@host',
+            dataDir: '/data',
+            outputPath: outPath,
+        });
+        expect(result).toBe(path.resolve(outPath));
+        expect(fs.existsSync(result)).toBe(true);
+    });
+    it('uses default output path when outputPath not provided', async () => {
+        mockExec.mockResolvedValue({ stdout: '1\n', stderr: '', code: 0 });
+        mockReadFile.mockResolvedValue(Buffer.from(''));
+        const result = await runBackup({ target: 'user@host', dataDir: '/data' });
+        expect(result).toMatch(/\/aifabrix-backup-\d{8}-\d{4}\.zip$/);
+        expect(fs.existsSync(result)).toBe(true);
+        try {
+            fs.unlinkSync(result);
+        }
+        catch {
+            // ignore
+        }
+    });
+    it('uses fallback JSON when readFile fails for each JSON file', async () => {
+        mockExec.mockResolvedValue({ stdout: '0\n', stderr: '', code: 0 });
+        mockReadFile.mockRejectedValue(new Error('ENOENT'));
+        const outPath = path.join(outDir, 'fallback.zip');
+        const result = await runBackup({
+            target: 'user@host',
+            dataDir: '/data',
+            outputPath: outPath,
+        });
+        expect(result).toBe(path.resolve(outPath));
+        expect(fs.existsSync(result)).toBe(true);
+        const tmpExtract = path.join(outDir, 'extract');
+        fs.mkdirSync(tmpExtract, { recursive: true });
+        await extract(result, { dir: tmpExtract });
+        const db = new Database(path.join(tmpExtract, 'backup.db'), { readonly: true });
+        const userCount = db.prepare('SELECT COUNT(*) as n FROM users').get();
+        expect(userCount.n).toBe(0);
+        db.close();
+    });
+});
+describe('runBackupLocal', () => {
+    let dataDir;
+    const TEST_TMP_BASE = path.join(process.cwd(), 'tmp');
+    beforeEach(() => {
+        fs.mkdirSync(TEST_TMP_BASE, { recursive: true });
+        dataDir = fs.mkdtempSync(path.join(TEST_TMP_BASE, 'af-backup-local-'));
+    });
+    afterEach(() => {
+        try {
+            fs.rmSync(dataDir, { recursive: true, force: true });
+        }
+        catch {
+            // ignore
+        }
+    });
+    it('builds zip from local builder.db when present', async () => {
+        const dbPath = path.join(dataDir, BUILDER_DB);
+        const db = new Database(dbPath);
+        db.exec("CREATE TABLE users (id TEXT PRIMARY KEY); INSERT INTO users (id) VALUES ('1');");
+        db.close();
+        const outPath = path.join(dataDir, 'out.zip');
+        const result = await runBackupLocal({ dataDir, outputPath: outPath });
+        expect(result).toBe(path.resolve(outPath));
+        expect(fs.existsSync(result)).toBe(true);
+        const tmpExtract = path.join(dataDir, 'extract');
+        fs.mkdirSync(tmpExtract, { recursive: true });
+        await extract(result, { dir: tmpExtract });
+        const db2 = new Database(path.join(tmpExtract, BACKUP_DB), { readonly: true });
+        const config = JSON.parse(fs.readFileSync(path.join(tmpExtract, CONFIG_JSON), 'utf8'));
+        expect(config.source).toBe('builder.db');
+        const userCount = db2.prepare('SELECT COUNT(*) as n FROM users').get();
+        expect(userCount.n).toBe(1);
+        db2.close();
+    });
+    it('builds zip from JSON files when builder.db absent', async () => {
+        for (const f of JSON_FILES) {
+            if (f === 'users.json')
+                fs.writeFileSync(path.join(dataDir, f), '{"users":[{"id":"02"}]}');
+            else if (f === 'tokens.json')
+                fs.writeFileSync(path.join(dataDir, f), '{"pins":[]}');
+            else if (f === 'secrets.json')
+                fs.writeFileSync(path.join(dataDir, f), '{"secrets":{}}');
+            else if (f === 'ssh-public-keys.json')
+                fs.writeFileSync(path.join(dataDir, f), '{"byUser":{}}');
+        }
+        const outPath = path.join(dataDir, 'out2.zip');
+        const result = await runBackupLocal({ dataDir, outputPath: outPath });
+        expect(fs.existsSync(result)).toBe(true);
+        const tmpExtract = path.join(dataDir, 'extract2');
+        fs.mkdirSync(tmpExtract, { recursive: true });
+        await extract(result, { dir: tmpExtract });
+        const config = JSON.parse(fs.readFileSync(path.join(tmpExtract, CONFIG_JSON), 'utf8'));
+        expect(config.source).toBe('json');
+    });
+    it('includes key files when present in dataDir', async () => {
+        const dbPath = path.join(dataDir, BUILDER_DB);
+        const db = new Database(dbPath);
+        db.exec('CREATE TABLE users (id TEXT PRIMARY KEY);');
+        db.close();
+        fs.writeFileSync(path.join(dataDir, 'ca.crt'), 'cert-content');
+        const outPath = path.join(dataDir, 'out3.zip');
+        const result = await runBackupLocal({ dataDir, outputPath: outPath });
+        const tmpExtract = path.join(dataDir, 'extract3');
+        fs.mkdirSync(tmpExtract, { recursive: true });
+        await extract(result, { dir: tmpExtract });
+        expect(fs.existsSync(path.join(tmpExtract, 'ca.crt'))).toBe(true);
+    });
+});

package/dist/cli.d.ts

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+/**
+ * af-server — Install, backup, and restore AI Fabrix builder-server (config + DB) over SSH.
+ * Usage: af-server <command> [options] [user@host]
+ */
+export {};

package/dist/cli.js

@@ -0,0 +1,170 @@
+#!/usr/bin/env node
+/**
+ * af-server — Install, backup, and restore AI Fabrix builder-server (config + DB) over SSH.
+ * Usage: af-server <command> [options] [user@host]
+ */
+import { Command } from 'commander';
+import { runInstall, runInstallLocal } from './install.js';
+import { runBackup, runBackupLocal } from './backup.js';
+import { runBackupScheduleInstall, runBackupScheduleInstallLocal } from './backup-schedule.js';
+import { runRestore, runRestoreLocal } from './restore.js';
+import { runSshCertRequest, runSshCertInstall, runSshCertInstallLocal } from './ssh-cert.js';
+import { requireUbuntu } from './ubuntu.js';
+const program = new Command();
+program
+    .name('af-server')
+    .description('Install, backup, and restore AI Fabrix builder-server over SSH (config + DB only)')
+    .version('0.1.0');
+program
+    .command('install [user@host]')
+    .description('Run server setup on host or locally (omit target on server). Docker, nginx, SSL, cron.')
+    .option('-d, --data-dir <path>', 'DATA_DIR', '/opt/aifabrix/builder-server/data')
+    .option('--dev-domain <domain>', 'DEV_DOMAIN for nginx', 'dev.aifabrix.dev')
+    .option('--ssl-dir <path>', 'SSL_DIR', '/opt/aifabrix/ssl')
+    .option('--builder-port <port>', 'BUILDER_SERVER_PORT', '3000')
+    .option('-i, --identity <path>', 'SSH private key path')
+    .action(async (target, opts) => {
+    try {
+        if (!target || !target.trim()) {
+            requireUbuntu();
+            runInstallLocal({
+                dataDir: opts.dataDir,
+                devDomain: opts.devDomain,
+                sslDir: opts.sslDir,
+                builderServerPort: opts.builderPort ? parseInt(opts.builderPort, 10) : undefined,
+            });
+        }
+        else {
+            await runInstall({
+                target: target.trim(),
+                privateKeyPath: opts.identity,
+                dataDir: opts.dataDir,
+                devDomain: opts.devDomain,
+                sslDir: opts.sslDir,
+                builderServerPort: opts.builderPort ? parseInt(opts.builderPort, 10) : undefined,
+            });
+        }
+        console.log('Install complete.');
+    }
+    catch (err) {
+        console.error(err instanceof Error ? err.message : err);
+        process.exit(1);
+    }
+});
+program
+    .command('backup [user@host]')
+    .description('On-demand backup, or --schedule to install cron (omit target for local).')
+    .option('-d, --data-dir <path>', 'DATA_DIR', '/opt/aifabrix/builder-server/data')
+    .option('-o, --output <path>', 'Output zip path (on-demand only)')
+    .option('--schedule', 'Install cron backup (daily 02:00, keep last 7)')
+    .option('--backup-dir <path>', 'Backup dir (with --schedule)', '/opt/aifabrix/backups')
+    .option('--keep-days <n>', 'Retention days (with --schedule)', '7')
+    .option('-i, --identity <path>', 'SSH private key path')
+    .action(async (target, opts) => {
+    try {
+        const isLocal = !target || !target.trim();
+        if (opts.schedule) {
+            if (isLocal) {
+                requireUbuntu();
+                runBackupScheduleInstallLocal({
+                    dataDir: opts.dataDir,
+                    backupDir: opts.backupDir,
+                    keepDays: opts.keepDays ? parseInt(opts.keepDays, 10) : 7,
+                });
+            }
+            else {
+                await runBackupScheduleInstall({
+                    target: target.trim(),
+                    privateKeyPath: opts.identity,
+                    dataDir: opts.dataDir,
+                    backupDir: opts.backupDir,
+                    keepDays: opts.keepDays ? parseInt(opts.keepDays, 10) : 7,
+                });
+            }
+            console.log('Cron backup installed. Backups will run daily at 02:00.');
+        }
+        else {
+            if (isLocal) {
+                requireUbuntu();
+                const out = await runBackupLocal({ dataDir: opts.dataDir, outputPath: opts.output });
+                console.log(`Backup saved: ${out}`);
+            }
+            else {
+                const out = await runBackup({
+                    target: target.trim(),
+                    privateKeyPath: opts.identity,
+                    dataDir: opts.dataDir,
+                    outputPath: opts.output,
+                });
+                console.log(`Backup saved: ${out}`);
+            }
+        }
+    }
+    catch (err) {
+        console.error(err instanceof Error ? err.message : err);
+        process.exit(1);
+    }
+});
+program
+    .command('restore <zip-path> [user@host]')
+    .description('Restore backup zip to DATA_DIR (omit user@host for local).')
+    .option('-d, --data-dir <path>', 'DATA_DIR (overrides backup config)')
+    .option('-f, --force', 'Overwrite existing builder.db')
+    .option('-i, --identity <path>', 'SSH private key path')
+    .action(async (zipPath, target, opts) => {
+    try {
+        if (!target || !target.trim()) {
+            requireUbuntu();
+            await runRestoreLocal({ zipPath, dataDir: opts.dataDir, force: opts.force });
+        }
+        else {
+            await runRestore({
+                target: target.trim(),
+                privateKeyPath: opts.identity,
+                zipPath,
+                dataDir: opts.dataDir,
+                force: opts.force,
+            });
+        }
+        console.log('Restore complete. Builder-server container restarted if present.');
+    }
+    catch (err) {
+        console.error(err instanceof Error ? err.message : err);
+        process.exit(1);
+    }
+});
+const sshCert = program.command('ssh-cert').description('Passwordless auth: install = append your SSH public key; request = stub for future SSH CA.');
+sshCert
+    .command('request')
+    .description('Request an SSH certificate for your key (not yet implemented)')
+    .option('--user <id>', 'Builder-server user id if tied to API')
+    .option('-i, --identity <path>', 'SSH private key path')
+    .action(async (opts) => {
+    try {
+        await runSshCertRequest({ privateKeyPath: opts.identity, target: '' });
+    }
+    catch (err) {
+        console.error(err instanceof Error ? err.message : err);
+        process.exit(1);
+    }
+});
+sshCert
+    .command('install [user@host]')
+    .description('Append your local SSH public key to server (or local) authorized_keys for passwordless auth')
+    .option('-i, --identity <path>', 'SSH private key path (its .pub is installed)')
+    .action(async (target, opts) => {
+    try {
+        if (!target || !target.trim()) {
+            requireUbuntu();
+            runSshCertInstallLocal(opts.identity);
+        }
+        else {
+            await runSshCertInstall({ target: target.trim(), privateKeyPath: opts.identity });
+        }
+    }
+    catch (err) {
+        console.error(err instanceof Error ? err.message : err);
+        process.exit(1);
+    }
+});
+program.parse();

package/dist/config.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Backup config and paths. Stored in backup zip as config.json.
+ */
+export interface BackupConfig {
+    dataDir: string;
+    sslDir?: string;
+    devDomain?: string;
+    builderServerPort?: number;
+    createdAt: string;
+    source: 'builder.db' | 'json';
+}
+export declare const DATA_DIR_DEFAULT = "/opt/aifabrix/builder-server/data";
+export declare const BUILDER_DB = "builder.db";
+export declare const BACKUP_DB = "backup.db";
+export declare const CONFIG_JSON = "config.json";
+export declare const KEY_FILES: readonly ["ca.crt", "ca.key", "secrets-encryption.key"];
+export declare const JSON_FILES: readonly ["users.json", "tokens.json", "secrets.json", "ssh-public-keys.json"];

package/dist/config.js

@@ -0,0 +1,9 @@
+/**
+ * Backup config and paths. Stored in backup zip as config.json.
+ */
+export const DATA_DIR_DEFAULT = '/opt/aifabrix/builder-server/data';
+export const BUILDER_DB = 'builder.db';
+export const BACKUP_DB = 'backup.db';
+export const CONFIG_JSON = 'config.json';
+export const KEY_FILES = ['ca.crt', 'ca.key', 'secrets-encryption.key'];
+export const JSON_FILES = ['users.json', 'tokens.json', 'secrets.json', 'ssh-public-keys.json'];

package/dist/config.spec.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Unit tests for backup config constants and types.
+ */
+export {};

package/dist/config.spec.js

@@ -0,0 +1,41 @@
+/**
+ * Unit tests for backup config constants and types.
+ */
+import { DATA_DIR_DEFAULT, BUILDER_DB, BACKUP_DB, CONFIG_JSON, KEY_FILES, JSON_FILES, } from './config.js';
+describe('config', () => {
+    describe('DATA_DIR_DEFAULT', () => {
+        it('is the expected builder-server data path', () => {
+            expect(DATA_DIR_DEFAULT).toBe('/opt/aifabrix/builder-server/data');
+        });
+    });
+    describe('BUILDER_DB', () => {
+        it('is builder.db', () => {
+            expect(BUILDER_DB).toBe('builder.db');
+        });
+    });
+    describe('BACKUP_DB', () => {
+        it('is backup.db', () => {
+            expect(BACKUP_DB).toBe('backup.db');
+        });
+    });
+    describe('CONFIG_JSON', () => {
+        it('is config.json', () => {
+            expect(CONFIG_JSON).toBe('config.json');
+        });
+    });
+    describe('KEY_FILES', () => {
+        it('includes ca.crt, ca.key, secrets-encryption.key', () => {
+            expect(KEY_FILES).toEqual(['ca.crt', 'ca.key', 'secrets-encryption.key']);
+        });
+    });
+    describe('JSON_FILES', () => {
+        it('includes users, tokens, secrets, ssh-public-keys', () => {
+            expect(JSON_FILES).toEqual([
+                'users.json',
+                'tokens.json',
+                'secrets.json',
+                'ssh-public-keys.json',
+            ]);
+        });
+    });
+});

package/dist/install.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Install command: upload setup script + nginx template and run via SSH with sudo, or locally (no target).
+ */
+import { type SSHConnectionOptions } from './ssh.js';
+export interface InstallOptions extends SSHConnectionOptions {
+    dataDir?: string;
+    devDomain?: string;
+    sslDir?: string;
+    builderServerPort?: number;
+}
+export interface InstallLocalOptions {
+    dataDir?: string;
+    devDomain?: string;
+    sslDir?: string;
+    builderServerPort?: number;
+}
+export declare function runInstall(options: InstallOptions): Promise<void>;
+/** Run setup script locally (no SSH). Call requireUbuntu() before this. */
+export declare function runInstallLocal(options?: InstallLocalOptions): void;

package/dist/install.js

@@ -0,0 +1,74 @@
+/**
+ * Install command: upload setup script + nginx template and run via SSH with sudo, or locally (no target).
+ */
+import * as path from 'path';
+import * as fs from 'fs';
+import { execSync } from 'child_process';
+import { fileURLToPath } from 'url';
+import { createSSHClient, exec, writeFile, close, } from './ssh.js';
+const scriptDir = path.dirname(fileURLToPath(import.meta.url));
+const ASSETS_DIR = path.resolve(scriptDir, '..', 'assets');
+function getSetupScript() {
+    const p = path.join(ASSETS_DIR, 'setup-dev-server-no-node.sh');
+    return fs.readFileSync(p, 'utf8');
+}
+function getNginxTemplate() {
+    const p = path.join(ASSETS_DIR, 'builder', 'builder-server', 'nginx-builder-server.conf.template');
+    return fs.readFileSync(p, 'utf8');
+}
+export async function runInstall(options) {
+    const dataDir = options.dataDir ?? '/opt/aifabrix/builder-server/data';
+    const devDomain = options.devDomain ?? 'dev.aifabrix.dev';
+    const sslDir = options.sslDir ?? '/opt/aifabrix/ssl';
+    const builderServerPort = options.builderServerPort ?? 3000;
+    const conn = await createSSHClient(options);
+    try {
+        const tmpDir = `/tmp/aifabrix-setup-${Date.now()}`;
+        await exec(conn, `mkdir -p ${tmpDir}/builder/builder-server`);
+        await exec(conn, `chmod 755 ${tmpDir}`);
+        const setupScript = getSetupScript();
+        const nginxTemplate = getNginxTemplate();
+        await writeFile(conn, `${tmpDir}/setup.sh`, setupScript);
+        await writeFile(conn, `${tmpDir}/builder/builder-server/nginx-builder-server.conf.template`, nginxTemplate);
+        await exec(conn, `chmod +x ${tmpDir}/setup.sh`);
+        const env = [
+            `REPO_ROOT=${tmpDir}`,
+            `DATA_DIR=${dataDir}`,
+            `DEV_DOMAIN=${devDomain}`,
+            `SSL_DIR=${sslDir}`,
+            `BUILDER_SERVER_PORT=${builderServerPort}`,
+        ].join(' ');
+        const cmd = `sudo ${env} ${tmpDir}/setup.sh`;
+        const result = await exec(conn, cmd);
+        if (result.stderr)
+            process.stderr.write(result.stderr);
+        if (result.stdout)
+            process.stdout.write(result.stdout);
+        if (result.code !== 0) {
+            throw new Error(`Install script exited with code ${result.code}`);
+        }
+        await exec(conn, `rm -rf ${tmpDir}`);
+    }
+    finally {
+        close(conn);
+    }
+}
+/** Run setup script locally (no SSH). Call requireUbuntu() before this. */
+export function runInstallLocal(options = {}) {
+    const dataDir = options.dataDir ?? '/opt/aifabrix/builder-server/data';
+    const devDomain = options.devDomain ?? 'dev.aifabrix.dev';
+    const sslDir = options.sslDir ?? '/opt/aifabrix/ssl';
+    const builderServerPort = options.builderServerPort ?? 3000;
+    const tmpDir = `/tmp/aifabrix-setup-${Date.now()}`;
+    const builderSubdir = path.join(tmpDir, 'builder', 'builder-server');
+    fs.mkdirSync(builderSubdir, { recursive: true });
+    try {
+        fs.writeFileSync(path.join(tmpDir, 'setup.sh'), getSetupScript(), { mode: 0o755 });
+        fs.writeFileSync(path.join(builderSubdir, 'nginx-builder-server.conf.template'), getNginxTemplate());
+        const env = `REPO_ROOT=${tmpDir} DATA_DIR=${dataDir} DEV_DOMAIN=${devDomain} SSL_DIR=${sslDir} BUILDER_SERVER_PORT=${builderServerPort}`;
+        execSync(`sudo ${env} ${tmpDir}/setup.sh`, { stdio: 'inherit' });
+    }
+    finally {
+        fs.rmSync(tmpDir, { recursive: true, force: true });
+    }
+}

package/dist/local-pubkey.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Resolve local SSH public key for install (default paths or from -i private key path).
+ * Never log or return private key material.
+ */
+/** Options for testing (inject homedir). */
+export interface ResolveLocalPublicKeyOptions {
+    homedir?: string;
+}
+/**
+ * Resolve public key content: first try identityPath.pub if given, then ~/.ssh/id_ed25519.pub, then id_rsa.pub.
+ * Returns single trimmed line. Throws with actionable message if none found.
+ */
+export declare function resolveLocalPublicKey(identityPath?: string, options?: ResolveLocalPublicKeyOptions): string;

package/dist/local-pubkey.js

@@ -0,0 +1,35 @@
+/**
+ * Resolve local SSH public key for install (default paths or from -i private key path).
+ * Never log or return private key material.
+ */
+import * as os from 'os';
+import * as path from 'path';
+import * as fs from 'fs';
+const DEFAULT_PUB_PATHS = ['id_ed25519.pub', 'id_rsa.pub'];
+const NO_KEY_MESSAGE = 'No default SSH public key found. Create one with: ssh-keygen -t ed25519 -f ~/.ssh/id_ed25519';
+/**
+ * Resolve public key content: first try identityPath.pub if given, then ~/.ssh/id_ed25519.pub, then id_rsa.pub.
+ * Returns single trimmed line. Throws with actionable message if none found.
+ */
+export function resolveLocalPublicKey(identityPath, options) {
+    const home = options?.homedir ?? os.homedir();
+    const sshDir = path.join(home, '.ssh');
+    if (identityPath) {
+        const resolved = path.resolve(identityPath);
+        const pubPath = resolved.endsWith('.pub') ? resolved : `${resolved}.pub`;
+        if (fs.existsSync(pubPath)) {
+            const content = fs.readFileSync(pubPath, 'utf8').trim().split(/\r?\n/)[0];
+            if (content)
+                return content;
+        }
+    }
+    for (const name of DEFAULT_PUB_PATHS) {
+        const full = path.join(sshDir, name);
+        if (fs.existsSync(full)) {
+            const content = fs.readFileSync(full, 'utf8').trim().split(/\r?\n/)[0];
+            if (content)
+                return content;
+        }
+    }
+    throw new Error(NO_KEY_MESSAGE);
+}

package/dist/local-pubkey.spec.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Tests for local SSH public key resolution (using temp dir via homedir option).
+ */
+export {};

package/dist/local-pubkey.spec.js

@@ -0,0 +1,64 @@
+/**
+ * Tests for local SSH public key resolution (using temp dir via homedir option).
+ */
+import * as path from 'path';
+import * as fs from 'fs';
+import { resolveLocalPublicKey } from './local-pubkey.js';
+const TEST_TMP = path.join(process.cwd(), 'tmp', 'local-pubkey');
+describe('local-pubkey', () => {
+    let fakeHome;
+    beforeEach(() => {
+        fs.mkdirSync(TEST_TMP, { recursive: true });
+        fakeHome = fs.mkdtempSync(path.join(TEST_TMP, 'home-'));
+    });
+    afterEach(() => {
+        try {
+            fs.rmSync(TEST_TMP, { recursive: true, force: true });
+        }
+        catch {
+            // ignore
+        }
+    });
+    it('throws with actionable message when no default key exists', () => {
+        expect(() => resolveLocalPublicKey(undefined, { homedir: fakeHome })).toThrow(/No default SSH public key found/);
+        expect(() => resolveLocalPublicKey(undefined, { homedir: fakeHome })).toThrow(/ssh-keygen/);
+    });
+    it('returns content of ~/.ssh/id_ed25519.pub when it exists', () => {
+        const sshDir = path.join(fakeHome, '.ssh');
+        fs.mkdirSync(sshDir, { recursive: true });
+        const content = 'ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAI user@host';
+        fs.writeFileSync(path.join(sshDir, 'id_ed25519.pub'), content);
+        expect(resolveLocalPublicKey(undefined, { homedir: fakeHome })).toBe(content);
+    });
+    it('returns content of ~/.ssh/id_rsa.pub when id_ed25519.pub absent', () => {
+        const sshDir = path.join(fakeHome, '.ssh');
+        fs.mkdirSync(sshDir, { recursive: true });
+        const content = 'ssh-rsa AAAAB3 user@host';
+        fs.writeFileSync(path.join(sshDir, 'id_rsa.pub'), content);
+        expect(resolveLocalPublicKey(undefined, { homedir: fakeHome })).toBe(content);
+    });
+    it('prefers id_ed25519.pub over id_rsa.pub', () => {
+        const sshDir = path.join(fakeHome, '.ssh');
+        fs.mkdirSync(sshDir, { recursive: true });
+        fs.writeFileSync(path.join(sshDir, 'id_rsa.pub'), 'ssh-rsa old');
+        fs.writeFileSync(path.join(sshDir, 'id_ed25519.pub'), 'ssh-ed25519 preferred');
+        expect(resolveLocalPublicKey(undefined, { homedir: fakeHome })).toBe('ssh-ed25519 preferred');
+    });
+    it('returns content of identityPath.pub when -i path given', () => {
+        const customPub = path.join(fakeHome, 'mykey.pub');
+        const content = 'ssh-ed25519 AAAAC3 user@pc';
+        fs.writeFileSync(customPub, content);
+        expect(resolveLocalPublicKey(path.join(fakeHome, 'mykey'), { homedir: fakeHome })).toBe(content);
+    });
+    it('uses identityPath as-is when it already ends with .pub', () => {
+        const customPub = path.join(fakeHome, 'key.pub');
+        fs.writeFileSync(customPub, 'ssh-ed25519 from-pub');
+        expect(resolveLocalPublicKey(customPub, { homedir: fakeHome })).toBe('ssh-ed25519 from-pub');
+    });
+    it('returns first line only when file has multiple lines', () => {
+        const sshDir = path.join(fakeHome, '.ssh');
+        fs.mkdirSync(sshDir, { recursive: true });
+        fs.writeFileSync(path.join(sshDir, 'id_ed25519.pub'), 'line1\nline2\n');
+        expect(resolveLocalPublicKey(undefined, { homedir: fakeHome })).toBe('line1');
+    });
+});