yappr 0.1.0

package/dist/src/cli/env.d.ts

@@ -0,0 +1,4 @@
+export declare function isUnset(value: string | undefined): boolean;
+export declare function setEnvVarInContent(content: string, key: string, value: string): string;
+export declare function removeEnvVarInContent(content: string, key: string): string;
+export declare function setEnvVar(envPath: string, key: string, value: string): Promise<void>;

package/dist/src/cli/env.js

@@ -0,0 +1,50 @@
+// .env read/write helpers for the deploy flow: prompt-collected values and
+// deploy-generated state (instance id, one-time SSH password) are persisted here
+// so a failed run can resume without losing anything unrecoverable.
+import { readFile, writeFile } from "node:fs/promises";
+// A value that should be treated as "not set" — empty or an .env.example placeholder.
+export function isUnset(value) {
+    return !value || /^(bk_|0x)?\.\.\.$/.test(value) || value === "...";
+}
+// Quote a value so dotenv reads it back verbatim: unquoted values are trimmed and
+// truncated at an inline " #" — fatal for generated secrets like the one-time SSH
+// password, which can't be re-fetched. Plain values stay unquoted.
+function quoteEnvValue(value) {
+    if (!/[#'"\s]/.test(value))
+        return value;
+    if (!value.includes("'"))
+        return `'${value}'`;
+    if (!value.includes('"'))
+        return `"${value}"`;
+    return value; // contains both quote kinds — leave as-is rather than corrupt it
+}
+export function setEnvVarInContent(content, key, value) {
+    const line = `${key}=${quoteEnvValue(value)}`;
+    // The replacements below MUST use a function: a plain replacement string would
+    // have its `$`-sequences ($&, $', $1, …) expanded by String.replace, silently
+    // mangling any value (passwords!) that contains them.
+    // Existing uncommented assignment — overwrite in place.
+    const active = new RegExp(`^${key}=.*$`, "m");
+    if (active.test(content))
+        return content.replace(active, () => line);
+    // Commented placeholder (e.g. "# KEY=" or "#KEY=...") — uncomment in place
+    // so the file stays clean instead of growing a duplicate at the bottom.
+    const commented = new RegExp(`^#\\s*${key}=.*$`, "m");
+    if (commented.test(content))
+        return content.replace(commented, () => line);
+    if (!content)
+        return `${line}\n`;
+    return content.endsWith("\n") ? `${content}${line}\n` : `${content}\n${line}\n`;
+}
+// Drop every assignment of `key` — used to keep credentials the server has no use
+// for (its own root password) out of the uploaded .env.
+export function removeEnvVarInContent(content, key) {
+    return content.replace(new RegExp(`^${key}=.*\\n?`, "gm"), "");
+}
+// Persist `key=value` into the .env file AND the live process.env, so later steps
+// in the same run see it without re-reading the file.
+export async function setEnvVar(envPath, key, value) {
+    const content = await readFile(envPath, "utf8").catch(() => "");
+    await writeFile(envPath, setEnvVarInContent(content, key, value));
+    process.env[key] = value;
+}

package/dist/src/cli/host-key.d.ts

@@ -0,0 +1,4 @@
+export declare function hostKeyConfig(host: string): {
+    hostHash: "sha256";
+    hostVerifier: (hash: string) => boolean;
+};

package/dist/src/cli/host-key.js

@@ -0,0 +1,50 @@
+// Trust-on-first-use SSH host-key pinning for the CLI's node-ssh connections
+// (deploy / status / ssh). ssh2 accepts ANY host key by default, and the target
+// IP comes from a third-party compute API — without pinning, a reassigned or
+// spoofed IP would silently receive the root password (and then the full .env).
+// The first connection records the host's key fingerprint in .yappr-known-hosts
+// (next to .env; one "host fingerprint" line per host); later connections refuse
+// a changed key instead of proceeding.
+import { readFileSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+const KNOWN_HOSTS_PATH = resolve(process.cwd(), ".yappr-known-hosts");
+function loadKnownHosts() {
+    const map = new Map();
+    try {
+        for (const line of readFileSync(KNOWN_HOSTS_PATH, "utf8").split("\n")) {
+            const [host, fp] = line.trim().split(/\s+/);
+            if (host && fp)
+                map.set(host, fp);
+        }
+    }
+    catch { /* no file yet */ }
+    return map;
+}
+function saveKnownHosts(map) {
+    const body = [...map].map(([h, fp]) => `${h} ${fp}`).join("\n") + "\n";
+    try {
+        writeFileSync(KNOWN_HOSTS_PATH, body, { mode: 0o600 });
+    }
+    catch { /* best-effort */ }
+}
+// ssh2 connect-config fragment — spread into every `ssh.connect({...})`. With
+// `hostHash` set, the verifier receives the host key's sha256 hash as a string.
+export function hostKeyConfig(host) {
+    return {
+        hostHash: "sha256",
+        hostVerifier: (hash) => {
+            const known = loadKnownHosts();
+            const pinned = known.get(host);
+            if (!pinned) {
+                known.set(host, hash);
+                saveKnownHosts(known);
+                return true;
+            }
+            if (pinned === hash)
+                return true;
+            console.error(`\n  SSH host key for ${host} changed (pinned ${pinned}, got ${hash}).`);
+            console.error(`  If the instance was reprovisioned, remove the ${host} line from ${KNOWN_HOSTS_PATH} and retry.`);
+            return false;
+        },
+    };
+}

package/dist/src/cli/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/src/cli/index.js

@@ -0,0 +1,71 @@
+#!/usr/bin/env node
+// The `yappr` command. A thin dispatcher; each subcommand lazy-imports its module so
+// `init` (used before deps/config exist) never loads the engine.
+function help() {
+    console.log(`yappr — self-funding X reply agent
+
+Usage: yappr <command> [args]
+
+  init [dir]        Scaffold a project (config/ + .env.example) into dir (default: .)
+  start             Run the agent — loads ./config and ./.env
+  update            Update the engine + sync new skills/hooks/context into ./config
+  deploy            Provision + deploy to an x402 compute instance
+  status [id]       Live dashboard for the deployed instance
+  ssh [id]          Open an interactive shell on the deployed instance
+  help              Show this help
+`);
+}
+// Hand control to a subcommand module's run(), making its process.argv look like a
+// direct invocation (drop the subcommand token) so its own argv parsing still works.
+async function delegate(path) {
+    process.argv.splice(2, 1);
+    const mod = (await import(path));
+    await mod.run();
+}
+const cmd = process.argv[2];
+try {
+    switch (cmd) {
+        case "init": {
+            const { runInit } = await import("./init.js");
+            await runInit(process.argv[3]);
+            break;
+        }
+        case "start":
+            // Booting the agent is a side effect of importing its entry module.
+            await import("../yappr.js");
+            break;
+        case "update":
+            await delegate("./update.js");
+            break;
+        case "deploy":
+            await delegate("./deploy.js");
+            break;
+        case "status":
+            await delegate("./status.js");
+            break;
+        case "ssh":
+            await delegate("./ssh.js");
+            break;
+        case undefined:
+        case "help":
+        case "--help":
+        case "-h":
+            help();
+            break;
+        default:
+            console.error(`yappr: unknown command "${cmd}"\n`);
+            help();
+            process.exit(1);
+    }
+}
+catch (err) {
+    // Ctrl-C inside an inquirer prompt rejects with ExitPromptError — that's the
+    // user quitting, not a failure: exit quietly instead of dumping a stack trace.
+    if (err?.name === "ExitPromptError") {
+        console.log("\n  Aborted.");
+        process.exit(0);
+    }
+    console.error(`\n  ✗  ${err?.message ?? err}`);
+    process.exit(1);
+}
+export {};

package/dist/src/cli/init.d.ts

@@ -0,0 +1 @@
+export declare function runInit(targetArg?: string): Promise<void>;

package/dist/src/cli/init.js

@@ -0,0 +1,51 @@
+import { cp, mkdir, access } from "node:fs/promises";
+import { basename, dirname, resolve, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { manifestForDir, saveManifest } from "./config-sync.js";
+// The installed package ships a starter config/ + .env.example (see package.json
+// "files"); init copies them into the user's project so they have something useful
+// to edit. Package root is three levels up from dist/src/cli/init.js (and from
+// src/cli/init.ts in the repo).
+const here = dirname(fileURLToPath(import.meta.url));
+const PKG_ROOT = resolve(here, "..", "..", "..");
+async function exists(p) {
+    try {
+        await access(p);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+// Scaffold a new project. Never clobbers existing files — config is the user's once
+// it's there, so re-running init is safe.
+export async function runInit(targetArg = ".") {
+    const target = resolve(process.cwd(), targetArg);
+    await mkdir(target, { recursive: true });
+    const destConfig = join(target, "config");
+    if (await exists(destConfig)) {
+        console.log("• config/ already exists — left untouched");
+    }
+    else {
+        // Skip hidden files (e.g. a stray .DS_Store) so the scaffold stays clean.
+        await cp(join(PKG_ROOT, "config"), destConfig, {
+            recursive: true,
+            filter: (src) => !basename(src).startsWith("."),
+        });
+        // Record what we scaffolded so `yappr update` can later tell which files the user
+        // edited from those still pristine, and fast-forward only the untouched ones.
+        await saveManifest(destConfig, await manifestForDir(destConfig));
+        console.log("• scaffolded config/ — starter skills, hooks and context (edit or delete freely)");
+    }
+    const destEnv = join(target, ".env");
+    const examplePath = join(PKG_ROOT, ".env.example");
+    if (await exists(destEnv)) {
+        console.log("• .env already exists — left untouched");
+    }
+    else if (await exists(examplePath)) {
+        await cp(examplePath, destEnv);
+        console.log("• created .env from .env.example — fill in your keys");
+    }
+    const where = targetArg === "." ? "" : `cd ${targetArg} && `;
+    console.log(`\nDone. Next:\n  ${where}# edit .env, then run the agent\n  npx yappr start\n`);
+}

package/dist/src/cli/ssh.d.ts

@@ -0,0 +1,2 @@
+import "dotenv/config";
+export declare function run(): Promise<void>;

package/dist/src/cli/ssh.js

@@ -0,0 +1,141 @@
+// Manual SSH into the deployed yappr compute instance (the `yappr ssh` command).
+//
+//   yappr ssh                 # uses COMPUTE_INSTANCE_ID from .env
+//   yappr ssh <instanceId>    # override the instance id
+//
+// Resolves the instance IP and one-time root password from the compute API
+// (wallet-signature auth via the Bankr key), then opens an interactive shell
+// using the password automatically — no prompt. Uses the ssh2 client bundled
+// with node-ssh, so there's no dependency on `sshpass`.
+import "dotenv/config";
+import { spawn } from "node:child_process";
+import { resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import ora from "ora";
+import { NodeSSH } from "node-ssh";
+import { resolveEvmAddress, fetchComputeInstance, fetchOneTimePassword, computeInstanceIp, computeInstancePassword, } from "../compute.js";
+import { hostKeyConfig } from "./host-key.js";
+// Open a fully interactive PTY shell over the established connection, wiring it
+// to the local terminal (raw mode, resize forwarding). Resolves with the remote
+// shell's exit code.
+async function interactiveShell(ssh) {
+    const conn = ssh.connection;
+    if (!conn)
+        throw new Error("SSH connection not established");
+    return new Promise((resolve, reject) => {
+        conn.shell({ term: process.env.TERM || "xterm-256color" }, (err, stream) => {
+            if (err)
+                return reject(err);
+            const stdin = process.stdin;
+            const wasRaw = !!stdin.isRaw;
+            if (stdin.isTTY)
+                stdin.setRawMode(true);
+            stdin.resume();
+            stdin.pipe(stream);
+            stream.pipe(process.stdout);
+            stream.stderr.pipe(process.stderr);
+            const syncWindow = () => stream.setWindow(process.stdout.rows ?? 24, process.stdout.columns ?? 80, 0, 0);
+            process.stdout.on("resize", syncWindow);
+            syncWindow();
+            let exitCode = 0;
+            stream.on("exit", (code) => { exitCode = code ?? 0; });
+            stream.on("close", () => {
+                process.stdout.off("resize", syncWindow);
+                stdin.unpipe(stream);
+                if (stdin.isTTY)
+                    stdin.setRawMode(wasRaw);
+                stdin.pause();
+                resolve(exitCode);
+            });
+            stream.on("error", reject);
+        });
+    });
+}
+// Connect with a password via the bundled ssh2 client and run an interactive
+// shell. Returns the remote shell's exit code.
+async function connectAndShell(ip, pw) {
+    const ssh = new NodeSSH();
+    await ssh.connect({ host: ip, username: "root", password: pw, tryKeyboard: true, ...hostKeyConfig(ip) });
+    const code = await interactiveShell(ssh);
+    ssh.dispose();
+    return code;
+}
+async function main() {
+    const instanceIdArg = process.argv[2];
+    // Fast path: if the deploy already cached the IP (COMPUTE_HOST) and password
+    // (COMPUTE_SSH_PASSWORD), connect directly with ZERO Bankr/compute API calls.
+    // Only when using the default instance (no explicit id override), since the
+    // cached IP belongs to COMPUTE_INSTANCE_ID. Any connection failure (e.g. the
+    // instance was reprovisioned and the cached IP is stale) falls through to the
+    // full resolve-from-API path below.
+    const cachedIp = process.env.COMPUTE_HOST;
+    const cachedPw = process.env.COMPUTE_SSH_PASSWORD;
+    if (!instanceIdArg && cachedIp && cachedPw) {
+        try {
+            console.log(`Using cached credentials. Connecting to root@${cachedIp}…\n`);
+            const code = await connectAndShell(cachedIp, cachedPw);
+            process.exit(code);
+        }
+        catch (err) {
+            console.warn(`Cached connection failed (${err instanceof Error ? err.message : String(err)}); resolving from the compute API…\n`);
+        }
+    }
+    // Slow path: resolve the IP + one-time password from the compute API (this is
+    // what requires the Bankr key + wallet signatures).
+    const apiKey = process.env.BANKR_API_KEY;
+    if (!apiKey)
+        throw new Error("BANKR_API_KEY not set in .env");
+    const instanceId = instanceIdArg || process.env.COMPUTE_INSTANCE_ID;
+    if (!instanceId)
+        throw new Error("No instance id — pass one as an argument or set COMPUTE_INSTANCE_ID in .env");
+    const spinner = ora("Resolving instance credentials…").start();
+    let ip;
+    let pw;
+    try {
+        const address = await resolveEvmAddress(apiKey);
+        const instance = await fetchComputeInstance(apiKey, address, instanceId);
+        ip = computeInstanceIp(instance);
+        if (!ip)
+            throw new Error(`Instance has no IP yet (status: ${instance?.status ?? instance?.order?.status ?? "unknown"})`);
+        // The one-time password can only be fetched ONCE per instance. The deploy
+        // saves it to .env after fetching, so prefer that before hitting the API.
+        pw = computeInstancePassword(instance) || process.env.COMPUTE_SSH_PASSWORD || undefined;
+        if (!pw)
+            pw = await fetchOneTimePassword(apiKey, address, instanceId);
+        spinner.succeed("Credentials resolved");
+    }
+    catch (err) {
+        spinner.fail();
+        throw err;
+    }
+    console.log(`\nInstance: ${instanceId}`);
+    console.log(`IP:       ${ip}`);
+    // With a password we can log in directly via the ssh2 client (no prompt).
+    if (pw) {
+        console.log(`Connecting to root@${ip}…\n`);
+        const code = await connectAndShell(ip, pw);
+        process.exit(code);
+    }
+    // No password available — fall back to the system ssh client (will prompt / use keys).
+    console.warn("Password unavailable — falling back to system ssh (key auth or prompt).\n");
+    const child = spawn("ssh", ["-o", "StrictHostKeyChecking=accept-new", `root@${ip}`], { stdio: "inherit" });
+    child.on("exit", (code) => process.exit(code ?? 0));
+}
+export async function run() {
+    await main();
+}
+// Direct invocation (`tsx src/cli/ssh.ts`) — the bin calls run() instead.
+const isMain = (() => {
+    try {
+        return fileURLToPath(import.meta.url) === resolve(process.argv[1] ?? "");
+    }
+    catch {
+        return false;
+    }
+})();
+if (isMain) {
+    run().catch((err) => {
+        console.error("Error:", err instanceof Error ? err.message : String(err));
+        process.exit(1);
+    });
+}

package/dist/src/cli/status.d.ts

@@ -0,0 +1,7 @@
+import "dotenv/config";
+export declare function runStatus(target: {
+    ip: string;
+    password?: string;
+    handle?: string;
+}): Promise<void>;
+export declare function run(): Promise<void>;