@odeva/cli 0.0.6 → 0.0.8

package/dist/commands/app/dev.js

@@ -9,11 +9,15 @@ import { loadCredentials } from "../../lib/credentials.js";
 import { adminUrl } from "../../lib/paths.js";
 import {
   cleanupSubscriptions,
+  ensureDevAppInstalled,
   preflightChecks,
   registeredWebhookEnv,
   registerWebhookSubscriptions,
   spawnDevServer,
+  syncDevAppUrls,
   watchedDevInputPaths,
+  waitForLocalDevServer,
+  waitForDevServerReachable,
   writeDevEnvFile
 } from "../../lib/dev-runner.js";
 import { CliError } from "../../lib/errors.js";
@@ -53,11 +57,19 @@ class AppDev extends Command {
         return;
       }
       const api = new OdevaApi();
-      const tunnelSpinner = p.spinner();
-      tunnelSpinner.start("Starting Cloudflare tunnel");
-      const tunnel = await startQuickTunnel(port);
-      tunnelSpinner.stop(`Tunnel ready at ${ui.code(tunnel.url)}`);
       let registered = [];
+      let server = spawnDevServer({
+        cwd: loaded.root,
+        config: loaded.config,
+        env: {
+          ...appEnv,
+          PORT: String(port)
+        }
+      });
+      await this.verifyLocalDevServer(port, server, api, registered);
+      this.log(ui.dim("Starting Cloudflare tunnel..."));
+      const tunnel = await startQuickTunnel(port);
+      this.log(ui.ok(`Tunnel ready at ${ui.code(tunnel.url)}`));
       registered = await this.registerDevWebhooks(api, loaded, tunnel.url);
       this.log("");
       this.log(`${ui.bold("Tunnel:")}     ${tunnel.url}`);
@@ -66,19 +78,12 @@ class AppDev extends Command {
         this.log(`  ${ui.dim("\u2192")} ${reg.config.topic.padEnd(28)} ${reg.fullUrl}`);
       }
       this.log("");
-      this.printInstallHint(loaded, tunnel.url);
+      await this.verifyDevServerReachable(tunnel, port, server, api, registered);
+      const syncedUrls = await this.syncDevAppUrls(api, loaded, tunnel.url);
+      this.printDevAppInfo(syncedUrls);
+      await this.ensureDevAppInstalled(api, loaded, tunnel, port, server, registered);
       this.log(ui.dim("Press Ctrl-C to stop. Subscriptions will be cleaned up on exit."));
       this.log("");
-      let server = spawnDevServer({
-        cwd: loaded.root,
-        config: loaded.config,
-        env: {
-          ...appEnv,
-          PORT: String(port),
-          ODEVA_TUNNEL_URL: tunnel.url,
-          ...registeredWebhookEnv(registered)
-        }
-      });
       let shuttingDown = false;
       let restartingServer = false;
       let serverExited = () => {
@@ -120,6 +125,8 @@ class AppDev extends Command {
           });
           server = nextServer;
           watchServerExit(server);
+          await this.verifyDevServerReachable(tunnel, port, server, api, registered);
+          await this.syncDevAppUrls(api, nextLoaded, tunnel.url);
           this.log(ui.ok("Reloaded app dev config."));
         }).catch((err) => {
           restartingServer = false;
@@ -145,26 +152,36 @@ class AppDev extends Command {
       await Promise.allSettled([tunnel.stop(), cleanupSubscriptions(api, registered)]);
     });
   }
-  printInstallHint(loaded, tunnelUrl) {
+  printDevAppInfo(syncedUrls) {
     const creds = loadCredentials();
     const apps = adminUrl(creds?.apiUrl);
     this.log(`${ui.bold("Install:")}    ${apps}/settings/apps  ${ui.dim('(find your draft app under "Your apps")')}`);
     if (creds?.organizationSlug) {
       this.log(`  ${ui.dim("org:")}      ${creds.organizationSlug}`);
     }
-    const installUrl = loaded.config.install_url?.trim();
-    const expected = `${tunnelUrl}/install`;
-    if (!installUrl) {
-      this.log(ui.warn(
-        `install_url in odeva.app.toml is empty \u2014 installs won't redirect back. Set it to ${expected} and re-run \`odeva app config link\` (or use a stable URL once you deploy).`
-      ));
-    } else if (!installUrl.startsWith(tunnelUrl) && !/localhost|127\.0\.0\.1/.test(installUrl)) {
-      this.log(ui.warn(
-        `install_url is ${installUrl} \u2014 installs from your org will redirect there, not to this tunnel. Update odeva.app.toml + \`odeva app config link\` if you want installs to hit the dev tunnel.`
-      ));
+    this.log(`  ${ui.dim("install:")}  ${syncedUrls.installUrl}`);
+    if (syncedUrls.adminEntryUrl) {
+      this.log(`  ${ui.dim("admin:")}    ${syncedUrls.adminEntryUrl}`);
     }
+    this.log(ui.dim("  dev URLs are synced to this tunnel for the current app record."));
     this.log("");
   }
+  async syncDevAppUrls(api, loaded, tunnelUrl) {
+    const spinner = p.spinner();
+    spinner.start("Syncing dev app URLs");
+    try {
+      const synced = await syncDevAppUrls({
+        api,
+        config: loaded.config,
+        tunnelUrl
+      });
+      spinner.stop(`Synced app URLs for ${ui.code(synced.app.slug)}`);
+      return synced;
+    } catch (err) {
+      spinner.stop(ui.err("Dev app URL sync failed"));
+      throw err instanceof CliError ? err : new CliError(`Dev app URL sync failed: ${err.message}`);
+    }
+  }
   async registerDevWebhooks(api, loaded, tunnelUrl) {
     const subscriptions = loaded.config.webhooks?.subscriptions ?? [];
     if (subscriptions.length === 0) {
@@ -186,6 +203,65 @@ class AppDev extends Command {
       throw err instanceof CliError ? err : new CliError(`Webhook registration failed: ${err.message}`);
     }
   }
+  async ensureDevAppInstalled(api, loaded, tunnel, port, server, registered) {
+    const spinner = p.spinner();
+    spinner.start("Ensuring app is installed in this organization");
+    try {
+      const installed = await ensureDevAppInstalled({
+        api,
+        config: loaded.config,
+        tunnelUrl: tunnel.url,
+        localPort: port
+      });
+      if (installed.alreadyInstalled) {
+        spinner.stop(`App ${ui.code(installed.app.slug)} is already installed`);
+      } else if (installed.callbackUrl) {
+        spinner.stop(`Installed app ${ui.code(installed.app.slug)} via ${ui.code(installed.callbackUrl)}`);
+      } else {
+        spinner.stop(`Installed app ${ui.code(installed.app.slug)}`);
+      }
+    } catch (err) {
+      spinner.stop(ui.err("App installation failed"));
+      await Promise.allSettled([
+        server.stop(),
+        tunnel.stop(),
+        cleanupSubscriptions(api, registered)
+      ]);
+      throw err;
+    }
+  }
+  async verifyLocalDevServer(port, server, api, registered) {
+    this.log(ui.dim("Waiting for local dev server..."));
+    try {
+      const result = await waitForLocalDevServer({ localPort: port });
+      this.log(ui.ok(`Local dev server ready via ${ui.code(result.path)} (HTTP ${result.status})`));
+    } catch (err) {
+      this.log(ui.err("Local dev server failed to start"));
+      await Promise.allSettled([
+        server.stop(),
+        cleanupSubscriptions(api, registered)
+      ]);
+      throw err;
+    }
+  }
+  async verifyDevServerReachable(tunnel, port, server, api, registered) {
+    this.log(ui.dim("Verifying dev server and tunnel... (trycloudflare can take up to 60s to propagate)"));
+    try {
+      const result = await waitForDevServerReachable({
+        localPort: port,
+        tunnelUrl: tunnel.url
+      });
+      this.log(ui.ok(`Tunnel verified via ${ui.code(result.path)} (HTTP ${result.tunnelStatus})`));
+    } catch (err) {
+      this.log(ui.err("Dev server tunnel check failed"));
+      await Promise.allSettled([
+        server.stop(),
+        tunnel.stop(),
+        cleanupSubscriptions(api, registered)
+      ]);
+      throw err;
+    }
+  }
   watchDevInputs(appConfigPath, onChange) {
     const paths = watchedDevInputPaths(appConfigPath);
     let timer;

package/dist/commands/app/init.js

@@ -9,7 +9,6 @@ import { withErrorHandling } from "../../lib/run.js";
 import { isValidSlug, slugify } from "../../lib/slug.js";
 import { listTemplates, renderTemplate } from "../../lib/templates.js";
 import { ui } from "../../lib/ui.js";
-import { detectShell, isCompletionInstalled } from "../autocomplete.js";
 const DEFAULT_TEMPLATE = "hono-bun";
 class AppInit extends Command {
   static description = "Scaffold a new Odeva app";
@@ -69,23 +68,17 @@ class AppInit extends Command {
         }
       });
       spinner.stop(`Wrote ${filesWritten} file${filesWritten === 1 ? "" : "s"} from template '${template}'.`);
-      const outroLines = [
-        ui.ok(`Created ${ui.bold(displayName)}`),
-        "",
-        "  Next steps:",
-        `    ${ui.code(`cd ${basename(directory)}`)}`,
-        `    ${ui.code("bun install")}`,
-        `    ${ui.code("odeva app config link")}    ${ui.dim("# register on Odeva")}`,
-        `    ${ui.code("odeva app dev")}             ${ui.dim("# start local dev with a tunnel")}`
-      ];
-      const shell = detectShell();
-      if (shell && !isCompletionInstalled(shell, "odeva")) {
-        outroLines.push(
+      p.outro(
+        [
+          ui.ok(`Created ${ui.bold(displayName)}`),
           "",
-          `  ${ui.dim("Tip:")} ${ui.code("odeva autocomplete --install")} ${ui.dim("to enable tab-completion.")}`
-        );
-      }
-      p.outro(outroLines.join("\n"));
+          "  Next steps:",
+          `    ${ui.code(`cd ${basename(directory)}`)}`,
+          `    ${ui.code("bun install")}`,
+          `    ${ui.code("odeva app config link")}    ${ui.dim("# register on Odeva")}`,
+          `    ${ui.code("odeva app dev")}             ${ui.dim("# start local dev with a tunnel")}`
+        ].join("\n")
+      );
     });
   }
   async resolveDirectory(nameArg, skipPrompts) {

package/dist/commands/autocomplete.js

@@ -1,90 +1,36 @@
-import { Args, Command, Flags } from "@oclif/core";
-import { existsSync, mkdirSync, writeFileSync } from "node:fs";
-import { homedir } from "node:os";
-import { basename, dirname, join } from "node:path";
+import { Args, Command } from "@oclif/core";
 import { CliError } from "../lib/errors.js";
 import { withErrorHandling } from "../lib/run.js";
-import { ui } from "../lib/ui.js";
 const SUPPORTED_SHELLS = ["fish", "zsh"];
 class Autocomplete extends Command {
-  static description = "Print or install a shell completion script for the odeva CLI";
+  static description = "Print a shell completion script for the odeva CLI";
   static examples = [
-    "$ odeva autocomplete --install                                  # detect shell and install",
-    "$ odeva autocomplete fish --install                             # explicit shell",
-    "$ odeva autocomplete fish > ~/.config/fish/completions/odeva.fish"
+    "$ odeva autocomplete fish > ~/.config/fish/completions/odeva.fish",
+    "$ odeva autocomplete zsh > ~/.odeva/_odeva  # then source it from .zshrc"
   ];
   static args = {
     shell: Args.string({
-      description: "Target shell (auto-detected from $SHELL when omitted with --install)",
+      description: "Target shell",
       options: [...SUPPORTED_SHELLS],
-      required: false
-    })
-  };
-  static flags = {
-    install: Flags.boolean({
-      description: "Write the completion script to the conventional path for the shell",
-      default: false
+      required: true
     })
   };
   async run() {
-    const { args, flags } = await this.parse(Autocomplete);
+    const { args } = await this.parse(Autocomplete);
     await withErrorHandling(this, async () => {
-      const bin = this.config.bin;
-      const shell = args.shell ?? (flags.install ? detectShell() : void 0);
-      if (!shell) {
-        if (flags.install) {
-          throw new CliError("Couldn't detect shell from $SHELL.", {
-            hint: `Pass it explicitly: \`${bin} autocomplete <${SUPPORTED_SHELLS.join("|")}> --install\`.`
-          });
-        }
-        throw new CliError("A shell is required.", {
-          hint: `Usage: \`${bin} autocomplete <${SUPPORTED_SHELLS.join("|")}>\`. Add --install to write the script to the conventional path.`
+      const shell = args.shell;
+      if (!SUPPORTED_SHELLS.includes(shell)) {
+        throw new CliError(`Unsupported shell '${shell}'.`, {
+          hint: `Supported: ${SUPPORTED_SHELLS.join(", ")}.`
         });
       }
+      const bin = this.config.bin;
       const tree = buildCommandTree(this.config.commands, bin);
       const script = shell === "fish" ? renderFish(bin, tree) : renderZsh(bin, tree);
-      if (!flags.install) {
-        process.stdout.write(script);
-        return;
-      }
-      const target = completionInstallPath(shell, bin);
-      mkdirSync(dirname(target), { recursive: true });
-      writeFileSync(target, script, { mode: 420 });
-      this.log(ui.ok(`Wrote ${shell} completion to ${ui.code(target)}`));
-      if (shell === "fish") {
-        this.log(ui.dim("  Open a new fish shell \u2014 completions auto-load from this path."));
-      } else {
-        const fpathDir = dirname(target);
-        this.log("");
-        this.log("  Add this to your ~/.zshrc (if you haven't already):");
-        this.log("");
-        this.log(ui.code(`    fpath=(${fpathDir} $fpath)`));
-        this.log(ui.code(`    autoload -U compinit && compinit`));
-        this.log("");
-        this.log(ui.dim("  Then open a new zsh shell."));
-      }
+      process.stdout.write(script);
     });
   }
 }
-function detectShell(env = process.env) {
-  const shell = env["SHELL"];
-  if (!shell) return null;
-  const name = basename(shell);
-  if (name === "fish" || name === "zsh") return name;
-  return null;
-}
-function completionInstallPath(shell, bin, env = process.env) {
-  const home = env["HOME"] || homedir();
-  if (shell === "fish") {
-    const config = env["XDG_CONFIG_HOME"] || join(home, ".config");
-    return join(config, "fish", "completions", `${bin}.fish`);
-  }
-  const data = env["XDG_DATA_HOME"] || join(home, ".local", "share");
-  return join(data, bin, "completions", `_${bin}`);
-}
-function isCompletionInstalled(shell, bin, env = process.env) {
-  return existsSync(completionInstallPath(shell, bin, env));
-}
 function buildCommandTree(commands, binName) {
   const root = { name: "", description: "", children: /* @__PURE__ */ new Map() };
   for (const cmd of commands) {
@@ -206,10 +152,7 @@ _${bin} "$@"
 }
 export {
   buildCommandTree,
-  completionInstallPath,
   Autocomplete as default,
-  detectShell,
-  isCompletionInstalled,
   renderFish,
   renderZsh
 };

package/dist/commands/webhook/trigger.js

@@ -61,7 +61,9 @@ class WebhookTrigger extends Command {
             hint: flags.url || configSubscription ? "Run `odeva app dev` to generate one, or pass --secret <value>, or use --no-sign for unsigned testing." : `Add a '${event}' subscription to odeva.app.toml, let \`odeva app dev\` reload, then try again.`
           });
         }
-        headers["x-odeva-signature"] = signPayload(body, secret);
+        const timestamp = Math.floor(Date.now() / 1e3).toString();
+        headers["x-odeva-timestamp"] = timestamp;
+        headers["x-odeva-signature"] = signPayload(body, secret, timestamp);
       }
       this.log(`${ui.bold("POST")} ${url}`);
       this.log(`  ${ui.dim("event:")}     ${event}`);

package/dist/lib/api.js

@@ -139,6 +139,20 @@ class OdevaApi {
     `);
     return data.developerApps.find((a) => a.clientId === clientId) ?? null;
   }
+  async installApp(appId, grantedScopes) {
+    const data = await this.request(
+      `mutation OdevaCliInstallApp($appId: ID!, $grantedScopes: [String!]) {
+        installApp(appId: $appId, grantedScopes: $grantedScopes) {
+          appInstallation { id status grantedScopes }
+          installCode
+          installUrl
+          errors
+        }
+      }`,
+      { appId, grantedScopes }
+    );
+    return data.installApp;
+  }
   async submitDeveloperApp(id) {
     const data = await this.request(
       `mutation OdevaCliSubmitDeveloperApp($id: ID!) {

package/dist/lib/cloudflared.js

@@ -2,6 +2,7 @@ import { spawn } from "node:child_process";
 import { spawnSync } from "node:child_process";
 import { CliError } from "./errors.js";
 const TRYCLOUDFLARE_RE = /https:\/\/[a-z0-9-]+\.trycloudflare\.com/i;
+const REGISTERED_CONNECTION_RE = /Registered tunnel connection/i;
 function isCloudflaredInstalled() {
   const result = spawnSync("cloudflared", ["--version"], { stdio: "ignore" });
   return result.status === 0;
@@ -15,32 +16,28 @@ function startQuickTunnel(localPort, options = {}) {
   return new Promise((resolve, reject) => {
     const proc = spawn(
       "cloudflared",
-      ["tunnel", "--no-autoupdate", "--url", `http://localhost:${localPort}`],
+      ["tunnel", "--no-autoupdate", "--url", `http://127.0.0.1:${localPort}`],
       { stdio: ["ignore", "pipe", "pipe"] }
     );
     let resolved = false;
+    let url = null;
+    let registered = false;
     const timeoutMs = options.timeoutMs ?? 3e4;
     const timer = setTimeout(() => {
       if (resolved) return;
       cleanup();
       reject(
         new CliError(`cloudflared did not produce a tunnel URL within ${timeoutMs / 1e3}s.`, {
-          hint: "Check your network connection or run `cloudflared tunnel --url http://localhost:" + localPort + "` manually."
+          hint: "Check your network connection or run `cloudflared tunnel --url http://127.0.0.1:" + localPort + "` manually."
         })
       );
     }, timeoutMs);
     const onData = (chunk) => {
       const text = chunk.toString("utf8");
       const match = TRYCLOUDFLARE_RE.exec(text);
-      if (match && !resolved) {
-        resolved = true;
-        clearTimeout(timer);
-        resolve({
-          url: match[0],
-          process: proc,
-          stop: () => stopProcess(proc)
-        });
-      }
+      if (match) url = match[0];
+      if (REGISTERED_CONNECTION_RE.test(text)) registered = true;
+      maybeResolve();
     };
     proc.stdout?.on("data", onData);
     proc.stderr?.on("data", onData);
@@ -60,16 +57,32 @@ function startQuickTunnel(localPort, options = {}) {
       } catch {
       }
     }
+    function maybeResolve() {
+      if (!url || !registered || resolved) return;
+      resolved = true;
+      clearTimeout(timer);
+      resolve({
+        url,
+        process: proc,
+        stop: () => stopProcess(proc)
+      });
+    }
   });
 }
 function stopProcess(proc) {
   return new Promise((resolve) => {
     if (proc.exitCode !== null) return resolve();
-    proc.once("exit", () => resolve());
+    let resolved = false;
+    const finish = () => {
+      if (resolved) return;
+      resolved = true;
+      resolve();
+    };
+    proc.once("exit", finish);
     try {
       proc.kill("SIGTERM");
     } catch {
-      resolve();
+      finish();
       return;
     }
     setTimeout(() => {
@@ -80,14 +93,19 @@ function stopProcess(proc) {
         }
       }
     }, 2e3);
+    setTimeout(finish, 5e3);
   });
 }
 function parseTunnelUrl(text) {
   const match = TRYCLOUDFLARE_RE.exec(text);
   return match ? match[0] : null;
 }
+function tunnelConnectionRegistered(text) {
+  return REGISTERED_CONNECTION_RE.test(text);
+}
 export {
   isCloudflaredInstalled,
   parseTunnelUrl,
-  startQuickTunnel
+  startQuickTunnel,
+  tunnelConnectionRegistered
 };

package/dist/lib/dev-runner.js

@@ -2,6 +2,7 @@ import { spawn } from "node:child_process";
 import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { APP_ENV_FILE } from "./app-env.js";
+import { CliError } from "./errors.js";
 async function registerWebhookSubscriptions(api, appName, tunnelUrl, subscriptions) {
   const created = [];
   for (const sub of subscriptions) {
@@ -23,6 +24,57 @@ async function cleanupSubscriptions(api, registered) {
     }
   }
 }
+async function syncDevAppUrls(opts) {
+  const app = await findLinkedApp(opts.api, opts.config.client_id);
+  const installUrl = devAppTunnelUrl({
+    tunnelUrl: opts.tunnelUrl,
+    configuredUrl: opts.config.install_url,
+    defaultPath: "/install"
+  });
+  const adminEntryUrl = opts.config.admin ? devAppTunnelUrl({
+    tunnelUrl: opts.tunnelUrl,
+    configuredUrl: opts.config.admin.entry_url,
+    defaultPath: "/admin"
+  }) : null;
+  const { app: updated } = await opts.api.upsertDeveloperApp({
+    id: app.id,
+    name: opts.config.name,
+    slug: opts.config.slug,
+    description: opts.config.description,
+    homepageUrl: opts.config.homepage_url,
+    installUrl,
+    privacyUrl: opts.config.privacy_url,
+    requestedScopes: opts.config.access_scopes?.scopes,
+    ...opts.config.admin && adminEntryUrl ? {
+      adminEmbed: {
+        entryUrl: adminEntryUrl,
+        sidebar: opts.config.admin.sidebar
+      }
+    } : {}
+  });
+  return { app: updated, installUrl, adminEntryUrl };
+}
+async function ensureDevAppInstalled(opts) {
+  const app = await findLinkedApp(opts.api, opts.config.client_id);
+  const result = await opts.api.installApp(app.id, opts.config.access_scopes?.scopes ?? app.requestedScopes);
+  if (isAlreadyInstalled(result)) {
+    return { app, result, callbackUrl: null, alreadyInstalled: true };
+  }
+  if (result.errors.length > 0) {
+    throw new CliError(`Could not install app: ${result.errors.join(", ")}`);
+  }
+  if (!result.installCode) {
+    return { app, result, callbackUrl: null, alreadyInstalled: false };
+  }
+  const callbackUrl = devInstallCallbackUrl({
+    tunnelUrl: opts.tunnelUrl,
+    installUrl: result.installUrl ?? opts.config.install_url,
+    installCode: result.installCode
+  });
+  await waitForDevInstallRoute({ localPort: opts.localPort, callbackUrl });
+  await completeInstallCallback(callbackUrl);
+  return { app, result, callbackUrl, alreadyInstalled: false };
+}
 function spawnDevServer(opts) {
   const command = opts.config.build?.dev ?? "bun run dev";
   const proc = spawn(command, {
@@ -44,6 +96,75 @@ function spawnDevServer(opts) {
     })
   };
 }
+async function waitForDevServerReachable(opts) {
+  const fetchImpl = opts.fetchImpl ?? fetch;
+  const deadline = Date.now() + (opts.timeoutMs ?? 6e4);
+  const requestTimeoutMs = opts.requestTimeoutMs ?? 2500;
+  const mismatchGraceMs = opts.mismatchGraceMs ?? 45e3;
+  const probe = await waitForLocalProbe(opts.localPort, deadline, requestTimeoutMs, fetchImpl);
+  const tunnelUrl = new URL(opts.tunnelUrl);
+  tunnelUrl.pathname = probe.path;
+  tunnelUrl.search = "";
+  let lastError = "not ready";
+  let mismatchSince = null;
+  while (Date.now() < deadline) {
+    try {
+      const response = await fetchWithTimeout(fetchImpl, tunnelUrl, requestTimeoutMs);
+      if (response.status === probe.status) {
+        return {
+          path: probe.path,
+          localStatus: probe.status,
+          tunnelStatus: response.status
+        };
+      }
+      lastError = `HTTP ${response.status}`;
+      mismatchSince ??= Date.now();
+      if (Date.now() - mismatchSince >= mismatchGraceMs) break;
+    } catch (err) {
+      lastError = err instanceof Error ? err.message : String(err);
+      mismatchSince = null;
+    }
+    await delay(500);
+  }
+  throw new CliError(`Cloudflare tunnel did not reach the local dev server at ${tunnelUrl.toString()}.`, {
+    hint: `Local ${probe.path} returned HTTP ${probe.status}, but the tunnel returned ${lastError}. Restart \`odeva app dev\` if the quick tunnel URL expired.`
+  });
+}
+async function waitForLocalDevServer(opts) {
+  const fetchImpl = opts.fetchImpl ?? fetch;
+  const deadline = Date.now() + (opts.timeoutMs ?? 3e4);
+  const requestTimeoutMs = opts.requestTimeoutMs ?? 1500;
+  return waitForLocalProbe(opts.localPort, deadline, requestTimeoutMs, fetchImpl);
+}
+function devInstallCallbackUrl(opts) {
+  const url = new URL(devAppTunnelUrl({
+    tunnelUrl: opts.tunnelUrl,
+    configuredUrl: opts.installUrl,
+    defaultPath: "/install",
+    configField: "install_url"
+  }));
+  url.searchParams.set("install_code", opts.installCode);
+  return url.toString();
+}
+function devAppTunnelUrl(opts) {
+  const url = new URL(opts.tunnelUrl);
+  if (opts.configuredUrl) {
+    let configured;
+    try {
+      configured = new URL(opts.configuredUrl);
+    } catch {
+      throw new CliError(`Invalid ${opts.configField ?? "URL"}: ${opts.configuredUrl}`, {
+        hint: "Fix odeva.app.toml or run `odeva app config link` with a valid URL."
+      });
+    }
+    url.pathname = configured.pathname;
+    url.search = configured.search;
+  } else {
+    url.pathname = opts.defaultPath;
+    url.search = "";
+  }
+  return url.toString();
+}
 function writeDevEnvFile(cwd, registered) {
   if (registered.length === 0) return null;
   const path = join(cwd, ".env.odeva.local");
@@ -82,14 +203,113 @@ function joinUrl(base, path) {
   const trimmedPath = path.startsWith("/") ? path : `/${path}`;
   return `${trimmedBase}${trimmedPath}`;
 }
+function isAlreadyInstalled(result) {
+  return result.errors.some((error) => /already installed/i.test(error));
+}
+async function findLinkedApp(api, clientId) {
+  if (!clientId) {
+    throw new CliError("App has not been registered yet.", {
+      hint: "Run `odeva app config link` first."
+    });
+  }
+  const app = await api.findAppByClientId(clientId);
+  if (!app) {
+    throw new CliError(`No app with client_id ${clientId} is owned by your active organization.`, {
+      hint: "If you registered against a different org, run `odeva auth select-org`."
+    });
+  }
+  return app;
+}
+async function waitForDevInstallRoute(opts) {
+  const deadline = Date.now() + (opts.timeoutMs ?? 15e3);
+  const callback = new URL(opts.callbackUrl);
+  const localUrl = new URL(`http://127.0.0.1:${opts.localPort}`);
+  localUrl.pathname = callback.pathname;
+  let lastError = "not ready";
+  while (Date.now() < deadline) {
+    try {
+      const response = await fetch(localUrl);
+      if (response.status < 500) return;
+      lastError = `HTTP ${response.status}`;
+    } catch (err) {
+      lastError = err instanceof Error ? err.message : String(err);
+    }
+    await delay(250);
+  }
+  throw new CliError(`Dev server did not become ready at ${localUrl.toString()}.`, {
+    hint: `Last probe failed with: ${lastError}`
+  });
+}
+async function waitForLocalProbe(localPort, deadline, requestTimeoutMs, fetchImpl) {
+  const candidates = [
+    { path: "/healthz", accepts: (status) => status < 400 },
+    { path: "/", accepts: (status) => status < 500 }
+  ];
+  let lastError = "not ready";
+  while (Date.now() < deadline) {
+    for (const candidate of candidates) {
+      const url = new URL(`http://127.0.0.1:${localPort}`);
+      url.pathname = candidate.path;
+      try {
+        const response = await fetchWithTimeout(fetchImpl, url, requestTimeoutMs);
+        if (candidate.accepts(response.status)) return { path: candidate.path, status: response.status };
+        lastError = `${candidate.path} returned HTTP ${response.status}`;
+      } catch (err) {
+        lastError = err instanceof Error ? err.message : String(err);
+      }
+    }
+    await delay(250);
+  }
+  throw new CliError(`Dev server did not become reachable at http://127.0.0.1:${localPort}.`, {
+    hint: `Last probe failed with: ${lastError}`
+  });
+}
+async function fetchWithTimeout(fetchImpl, url, timeoutMs) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    return await fetchImpl(url, { signal: controller.signal });
+  } finally {
+    clearTimeout(timer);
+  }
+}
+async function completeInstallCallback(callbackUrl) {
+  let response;
+  try {
+    response = await fetch(callbackUrl);
+  } catch (err) {
+    throw new CliError(`Could not reach app install callback at ${callbackUrl}.`, {
+      hint: err instanceof Error ? err.message : String(err)
+    });
+  }
+  if (response.ok) return;
+  let body = "";
+  try {
+    body = (await response.text()).trim().slice(0, 300);
+  } catch {
+    body = "";
+  }
+  throw new CliError(`App install callback failed with HTTP ${response.status}.`, {
+    hint: body || callbackUrl
+  });
+}
+function delay(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
 function stopProcess(proc) {
   return new Promise((resolve) => {
     if (proc.exitCode !== null) return resolve();
-    proc.once("exit", () => resolve());
+    let resolved = false;
+    const finish = () => {
+      if (resolved) return;
+      resolved = true;
+      resolve();
+    };
+    proc.once("exit", finish);
     try {
       killDevProcess(proc, "SIGTERM");
     } catch {
-      resolve();
+      finish();
       return;
     }
     setTimeout(() => {
@@ -100,6 +320,7 @@ function stopProcess(proc) {
         }
       }
     }, 2e3);
+    setTimeout(finish, 5e3);
   });
 }
 function killDevProcess(proc, signal) {
@@ -134,11 +355,17 @@ function readEnvFile(path) {
 }
 export {
   cleanupSubscriptions,
+  devAppTunnelUrl,
+  devInstallCallbackUrl,
+  ensureDevAppInstalled,
   preflightChecks,
   readEnvFile,
   registerWebhookSubscriptions,
   registeredWebhookEnv,
   spawnDevServer,
+  syncDevAppUrls,
+  waitForDevServerReachable,
+  waitForLocalDevServer,
   watchedDevInputPaths,
   webhookSecretEnvKey,
   webhookSecretForEvent,

package/dist/lib/webhook-fixtures.js

@@ -20,6 +20,16 @@ const FIXTURES = {
     },
     changes: ["checkIn", "checkOut"]
   },
+  "reservation.confirmed": {
+    reservation: {
+      id: "res_test_abc123",
+      reservationNumber: "R-2026-0001",
+      status: "confirmed",
+      checkIn: "2026-07-01",
+      checkOut: "2026-07-05",
+      total: { amount: "480.00", currency: "EUR" }
+    }
+  },
   "reservation.cancelled": {
     reservation: {
       id: "res_test_abc123",
@@ -47,8 +57,9 @@ function buildFixture(event, overrides) {
     data
   };
 }
-function signPayload(rawBody, secret) {
-  return createHmac("sha256", secret).update(rawBody).digest("hex");
+function signPayload(rawBody, secret, timestamp) {
+  const digest = createHmac("sha256", secret).update(`${timestamp}.${rawBody}`).digest("hex");
+  return `sha256=${digest}`;
 }
 function listFixtureEvents() {
   return Object.keys(FIXTURES);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@odeva/cli",
-  "version": "0.0.6",
+  "version": "0.0.8",
   "description": "Build apps on the Odeva booking platform — scaffold, develop, deploy.",
   "license": "MIT",
   "type": "module",

package/templates/hono-bun/README.md.tmpl

@@ -13,14 +13,15 @@ odeva app dev            # local server + tunnel + webhook delivery
 In another terminal:
 
 ```sh
-odeva webhook trigger reservation.created
+odeva webhook trigger reservation.confirmed
+odeva webhook trigger payment.succeeded
 ```
 
 ## Project layout
 
 - `odeva.app.toml` — app config (name, slug, webhooks, scopes)
 - `src/index.ts` — Hono server with a webhook handler stub
-- `src/webhook.ts` — HMAC signature verification
+- `src/webhook.ts` — timestamped `sha256=` HMAC signature verification
 - `src/admin.ts` — iframe session-token verification
 
 ## Embed in the merchant admin

package/templates/hono-bun/odeva.app.toml.tmpl

@@ -21,8 +21,12 @@ api_version = "2026-01"
 # tunnel URL. List supported events with: `odeva webhook list --available`.
 #
 # [[webhooks.subscriptions]]
-# topic = "reservation.created"
-# uri = "/webhooks/reservation.created"
+# topic = "reservation.confirmed"
+# uri = "/webhooks/reservation.confirmed"
+#
+# [[webhooks.subscriptions]]
+# topic = "payment.succeeded"
+# uri = "/webhooks/payment.succeeded"
 
 # Uncomment to embed this app inside the merchant admin sidebar.
 # The merchant admin will iframe `entry_url?session_token=<short-lived JWT>`

package/templates/hono-bun/src/index.ts

@@ -57,19 +57,20 @@ app.post("/webhooks/:topic", async (c) => {
   const topic = c.req.param("topic");
   const rawBody = await c.req.text();
   const signature = c.req.header("x-odeva-signature");
+  const timestamp = c.req.header("x-odeva-timestamp");
   const secret =
     process.env[`ODEVA_WEBHOOK_SECRET__${topic.toUpperCase().replace(/[^A-Z0-9]+/g, "_")}`] ??
     process.env.ODEVA_WEBHOOK_SECRET;
 
-  if (secret && !verifyWebhook(rawBody, signature, secret)) {
+  if (secret && !verifyWebhook(rawBody, signature, secret, timestamp)) {
     return c.json({ error: "invalid signature" }, 401);
   }
 
   const payload = JSON.parse(rawBody) as Record<string, unknown>;
   logger.info(`[webhook] ${topic}`, payload);
 
-  // TODO: handle the event.
-  // Tip: run `odeva webhook trigger <topic>` to fire a sample payload at this handler.
+  // Route work by topic here. Tip: run `odeva webhook trigger <topic>` to fire
+  // a signed sample payload at this handler.
 
   return c.json({ received: true });
 });

package/templates/hono-bun/src/install.ts

@@ -27,7 +27,7 @@ const EXCHANGE_MUTATION = `
 `;
 
 interface ExchangeResponse {
-  data: {
+  data?: {
     exchangeAppInstallCode: {
       appInstallation: {
         id: string;
@@ -37,10 +37,14 @@ interface ExchangeResponse {
       rawKey: string | null;
       errors: string[];
     } | null;
-  };
+  } | null;
   errors?: Array<{ message: string }>;
 }
 
+function isExchangeResponse(value: unknown): value is ExchangeResponse {
+  return typeof value === "object" && value !== null;
+}
+
 export function makeInstallHandler(store: InstallationStore) {
   return async (c: Context): Promise<Response> => {
     const installCode = c.req.query("install_code");
@@ -68,13 +72,23 @@ export function makeInstallHandler(store: InstallationStore) {
       }),
     });
 
-    const body = (await response.json()) as ExchangeResponse;
+    let body: ExchangeResponse;
+    try {
+      const parsed: unknown = await response.json();
+      if (!isExchangeResponse(parsed)) {
+        return c.text(`Install failed: Odeva returned an unexpected response (${response.status}).`, 502);
+      }
+      body = parsed;
+    } catch {
+      return c.text(`Install failed: Could not parse Odeva response (${response.status}).`, 502);
+    }
+
     const topErrors = body.errors?.map((e) => e.message) ?? [];
     const payload = body.data?.exchangeAppInstallCode ?? null;
     const userErrors = payload?.errors ?? [];
 
     if (topErrors.length > 0 || userErrors.length > 0 || !payload?.rawKey || !payload.appInstallation) {
-      const msg = [...topErrors, ...userErrors].join("; ") || "Exchange failed";
+      const msg = [...topErrors, ...userErrors].join("; ") || `Exchange failed (${response.status})`;
       return c.text(`Install failed: ${msg}`, 400);
     }
 

package/templates/hono-bun/src/webhook.ts

@@ -3,12 +3,19 @@ import { createHmac, timingSafeEqual } from "node:crypto";
 /**
  * Verify a webhook signature from the Odeva platform.
  *
- * The CLI's `odeva webhook trigger` and the platform itself both sign payloads
- * with HMAC-SHA256(secret, rawBody), hex-encoded, sent as `x-odeva-signature`.
+ * Webhooks are signed as HMAC-SHA256(secret, `${timestamp}.${rawBody}`),
+ * hex-encoded and sent as `x-odeva-signature: sha256=<digest>`.
  */
-export function verifyWebhook(rawBody: string, signature: string | undefined, secret: string): boolean {
+export function verifyWebhook(
+  rawBody: string,
+  signature: string | undefined,
+  secret: string,
+  timestamp: string | undefined,
+): boolean {
   if (!signature) return false;
-  const expected = createHmac("sha256", secret).update(rawBody).digest("hex");
+  if (!timestamp) return false;
+  const digest = createHmac("sha256", secret).update(`${timestamp}.${rawBody}`).digest("hex");
+  const expected = `sha256=${digest}`;
   const a = Buffer.from(expected, "utf8");
   const b = Buffer.from(signature, "utf8");
   if (a.length !== b.length) return false;