@odeva/cli 0.0.9 → 0.0.11

package/dist/commands/app/config/link.js

@@ -1,14 +1,20 @@
 import { Command, Flags } from "@oclif/core";
 import * as p from "@clack/prompts";
 import { OdevaApi } from "../../../lib/api.js";
-import { loadAppConfig, saveAppConfig, ADMIN_ICONS } from "../../../lib/config.js";
+import { loadAppConfig, resolveAppConfigUrl, saveAppConfig, ADMIN_ICONS } from "../../../lib/config.js";
 import { saveAppEnv } from "../../../lib/app-env.js";
 import { loadCredentials } from "../../../lib/credentials.js";
 import { withErrorHandling } from "../../../lib/run.js";
 import { ui } from "../../../lib/ui.js";
 import { ApiError, CliError } from "../../../lib/errors.js";
 import { isValidSlug } from "../../../lib/slug.js";
-function buildAdminEmbedInput(admin, configPath) {
+function buildAdminEmbedInput(config, configPath) {
+  const admin = config.admin;
+  if (!admin) {
+    throw new CliError("Cannot build admin embed input without an [admin] section.", {
+      hint: `Edit ${configPath}`
+    });
+  }
   const validIcons = ADMIN_ICONS;
   if (!validIcons.includes(admin.sidebar.icon)) {
     const iconList = ADMIN_ICONS.join(", ");
@@ -17,8 +23,20 @@ function buildAdminEmbedInput(admin, configPath) {
       { hint: `Edit ${configPath}` }
     );
   }
+  const entryUrl = resolveAppConfigUrl({
+    config,
+    configuredUrl: admin.entry_url,
+    defaultPath: "/admin",
+    fieldName: "admin.entry_url",
+    configPath
+  });
+  if (!entryUrl) {
+    throw new CliError(`Invalid odeva.app.toml: missing 'admin.entry_url'.`, {
+      hint: `Set 'tunnel_url' or add 'admin.entry_url' in ${configPath}.`
+    });
+  }
   return {
-    entryUrl: admin.entry_url,
+    entryUrl,
     sidebar: {
       label: admin.sidebar.label,
       icon: admin.sidebar.icon
@@ -38,16 +56,25 @@ class AppConfigLink extends Command {
     const { flags } = await this.parse(AppConfigLink);
     await withErrorHandling(this, async () => {
       const loaded = loadAppConfig();
-      const adminInput = loaded.config.admin ? buildAdminEmbedInput(loaded.config.admin, loaded.path) : void 0;
+      const adminInput = loaded.config.admin ? buildAdminEmbedInput(loaded.config, loaded.path) : void 0;
+      const installUrl = resolveAppConfigUrl({
+        config: loaded.config,
+        configuredUrl: loaded.config.install_url,
+        defaultPath: "/install",
+        fieldName: "install_url",
+        configPath: loaded.path
+      });
       p.intro(ui.brand("odeva app config link"));
       p.note(
         [
           `${ui.dim("name:")}        ${loaded.config.name}`,
           `${ui.dim("slug:")}        ${loaded.config.slug}`,
           `${ui.dim("client_id:")}   ${loaded.config.client_id ?? ui.dim("(new)")}`,
+          `${ui.dim("tunnel_url:")}  ${loaded.config.tunnel_url ?? ui.dim("(none)")}`,
           `${ui.dim("homepage:")}    ${loaded.config.homepage_url ?? ui.dim("(none)")}`,
+          `${ui.dim("install:")}     ${installUrl ?? ui.dim("(none)")}`,
           `${ui.dim("scopes:")}      ${(loaded.config.access_scopes?.scopes ?? []).join(", ") || ui.dim("(none)")}`,
-          ...loaded.config.admin ? [`${ui.dim("admin:")}       ${loaded.config.admin.sidebar.label} (${loaded.config.admin.entry_url})`] : []
+          ...loaded.config.admin ? [`${ui.dim("admin:")}       ${loaded.config.admin.sidebar.label} (${adminInput?.entryUrl})`] : []
         ].join("\n"),
         "Will register this app"
       );
@@ -65,7 +92,7 @@ class AppConfigLink extends Command {
         if (match) existingId = match.id;
       }
       spinner.message(existingId ? "Updating app on Odeva" : "Creating app on Odeva");
-      const { app, rawClientSecret } = await upsertWithSlugRetry(api, spinner, loaded, existingId, adminInput);
+      const { app, rawClientSecret } = await upsertWithSlugRetry(api, spinner, loaded, existingId, installUrl, adminInput);
       spinner.stop(`${existingId ? "Updated" : "Registered"} app ${ui.code(app.slug)} (client_id ${ui.code(app.clientId)})`);
       loaded.config.client_id = app.clientId;
       saveAppConfig(loaded);
@@ -102,7 +129,7 @@ class AppConfigLink extends Command {
   }
 }
 const SLUG_TAKEN_RE = /slug.*(?:already been taken|taken|in use|exists)/i;
-async function upsertWithSlugRetry(api, spinner, loaded, existingId, adminInput) {
+async function upsertWithSlugRetry(api, spinner, loaded, existingId, installUrl, adminInput) {
   for (; ; ) {
     try {
       return await api.upsertDeveloperApp({
@@ -111,7 +138,7 @@ async function upsertWithSlugRetry(api, spinner, loaded, existingId, adminInput)
         slug: loaded.config.slug,
         description: loaded.config.description,
         homepageUrl: loaded.config.homepage_url,
-        installUrl: loaded.config.install_url,
+        installUrl,
         privacyUrl: loaded.config.privacy_url,
         requestedScopes: loaded.config.access_scopes?.scopes,
         ...adminInput ? { adminEmbed: adminInput } : {}

package/dist/commands/app/dev.js

@@ -13,6 +13,7 @@ import {
   preflightChecks,
   registeredWebhookEnv,
   registerWebhookSubscriptions,
+  saveDevTunnelUrl,
   spawnDevServer,
   syncDevAppUrls,
   watchedDevInputPaths,
@@ -68,6 +69,9 @@ class AppDev extends Command {
       });
       await this.verifyLocalDevServer(port, server, api, registered);
       const tunnel = await this.startReachableTunnel(port, server);
+      if (saveDevTunnelUrl(loaded, tunnel.url)) {
+        this.log(ui.ok(`Wrote tunnel_url to ${ui.code(loaded.path)}`));
+      }
       registered = await this.registerDevWebhooks(api, loaded, tunnel.url);
       this.log("");
       this.log(`${ui.bold("Tunnel:")}     ${tunnel.url}`);
@@ -103,6 +107,9 @@ class AppDev extends Command {
           if (nextPort !== port) {
             this.log(ui.warn(`Port changed to ${nextPort}; restart \`odeva app dev\` to recreate the tunnel.`));
           }
+          if (saveDevTunnelUrl(nextLoaded, tunnel.url)) {
+            this.log(ui.ok(`Wrote tunnel_url to ${ui.code(nextLoaded.path)}`));
+          }
           const nextRegistered = await this.registerDevWebhooks(api, nextLoaded, tunnel.url);
           await cleanupSubscriptions(api, registered);
           registered = nextRegistered;

package/dist/commands/webhook/trigger.js

@@ -1,13 +1,13 @@
 import { Args, Command, Flags } from "@oclif/core";
 import { readFileSync } from "node:fs";
-import { resolve } from "node:path";
+import { join, resolve } from "node:path";
+import { APP_DEV_ENV_FILE, readEnvFile } from "../../lib/app-env.js";
 import { loadAppConfig, findAppConfigPath } from "../../lib/config.js";
 import { buildFixture, signPayload } from "../../lib/webhook-fixtures.js";
 import { CliError } from "../../lib/errors.js";
 import { withErrorHandling } from "../../lib/run.js";
-import { readEnvFile, webhookSecretForEvent } from "../../lib/dev-runner.js";
+import { webhookSecretForEvent } from "../../lib/dev-runner.js";
 import { ui } from "../../lib/ui.js";
-import { join } from "node:path";
 class WebhookTrigger extends Command {
   static description = "Fire a sample webhook payload at a local handler (uses the secret from .env.odeva.local if present)";
   static examples = [
@@ -107,7 +107,7 @@ class WebhookTrigger extends Command {
   secretFromEnvFile(event) {
     const cfgPath = findAppConfigPath();
     if (!cfgPath) return void 0;
-    const envPath = join(resolve(cfgPath, ".."), ".env.odeva.local");
+    const envPath = join(resolve(cfgPath, ".."), APP_DEV_ENV_FILE);
     const env = readEnvFile(envPath);
     return webhookSecretForEvent(event, env);
   }

package/dist/lib/app-env.js

@@ -1,8 +1,17 @@
 import { existsSync, readFileSync, writeFileSync, chmodSync } from "node:fs";
 import { dirname, join } from "node:path";
 const APP_ENV_FILE = ".odeva.env";
+const APP_ENV_LOCAL_FILE = ".odeva.env.local";
+const APP_DEV_ENV_FILE = ".env.odeva.local";
 function loadAppEnv(appConfigPath) {
-  const envPath = join(dirname(appConfigPath), APP_ENV_FILE);
+  const dir = dirname(appConfigPath);
+  return {
+    ...readEnvFile(join(dir, APP_DEV_ENV_FILE)),
+    ...readEnvFile(join(dir, APP_ENV_FILE)),
+    ...readEnvFile(join(dir, APP_ENV_LOCAL_FILE))
+  };
+}
+function readEnvFile(envPath) {
   if (!existsSync(envPath)) return {};
   const raw = readFileSync(envPath, "utf8");
   const result = {};
@@ -19,7 +28,7 @@ function loadAppEnv(appConfigPath) {
 }
 function saveAppEnv(appConfigPath, values) {
   const envPath = join(dirname(appConfigPath), APP_ENV_FILE);
-  const merged = { ...loadAppEnv(appConfigPath), ...values };
+  const merged = { ...readEnvFile(envPath), ...values };
   const body = [
     "# Auto-managed by `odeva` \u2014 do not commit. Add `.odeva.env` to .gitignore.",
     ...Object.entries(merged).map(([k, v]) => `${k}=${v}`),
@@ -33,7 +42,10 @@ function saveAppEnv(appConfigPath, values) {
   return envPath;
 }
 export {
+  APP_DEV_ENV_FILE,
   APP_ENV_FILE,
+  APP_ENV_LOCAL_FILE,
   loadAppEnv,
+  readEnvFile,
   saveAppEnv
 };

package/dist/lib/config.js

@@ -14,6 +14,20 @@ const ADMIN_ICONS = [
   "bar-chart",
   "wallet"
 ];
+function resolveAppConfigUrl(opts) {
+  const configured = opts.configuredUrl?.trim();
+  if (configured) {
+    if (isAbsoluteHttpUrl(configured)) return new URL(configured).toString();
+    if (configured.startsWith("/")) {
+      return appUrlFromTunnel(opts.config.tunnel_url, configured, opts.fieldName, opts.configPath);
+    }
+    throw new CliError(`Invalid '${opts.fieldName}' in ${APP_CONFIG_FILE}: must be an absolute URL or path starting with '/'.`, {
+      hint: `Edit ${opts.configPath}`
+    });
+  }
+  if (!opts.config.tunnel_url) return void 0;
+  return appUrlFromTunnel(opts.config.tunnel_url, opts.defaultPath, "tunnel_url", opts.configPath);
+}
 function findAppConfigPath(startDir = process.cwd()) {
   let dir = resolve(startDir);
   while (true) {
@@ -70,27 +84,68 @@ function validateConfig(config, path) {
       };
     });
   }
+  if (config.tunnel_url !== void 0) {
+    validateTunnelUrl(config.tunnel_url, path);
+  }
+  if (config.install_url !== void 0 && config.install_url !== "") {
+    validateResolvableUrl(config.install_url, "install_url", config.tunnel_url, path);
+  }
   if (config.admin !== void 0) {
-    validateAdminSection(config.admin, path);
+    validateAdminSection(config.admin, config.tunnel_url, path);
+  }
+}
+function validateTunnelUrl(value, path) {
+  if (typeof value !== "string" || !value) {
+    throw new CliError(`Invalid ${APP_CONFIG_FILE}: 'tunnel_url' must be a non-empty string.`, {
+      hint: `Edit ${path}`
+    });
+  }
+  if (!isAbsoluteHttpUrl(value)) {
+    throw new CliError(`Invalid 'tunnel_url' in ${APP_CONFIG_FILE}: must start with https:// or http://.`, {
+      hint: `Edit ${path}`
+    });
+  }
+}
+function validateResolvableUrl(value, fieldName, tunnelUrl, path) {
+  if (typeof value !== "string" || !value) {
+    throw new CliError(`Invalid ${APP_CONFIG_FILE}: '${fieldName}' must be a non-empty string.`, {
+      hint: `Edit ${path}`
+    });
+  }
+  if (isAbsoluteHttpUrl(value)) {
+    if (fieldName === "admin.entry_url" && !value.startsWith("https://")) {
+      throw new CliError(
+        `Invalid 'admin.entry_url' in ${APP_CONFIG_FILE}: must start with https://.`,
+        { hint: `Edit ${path}` }
+      );
+    }
+    return;
   }
+  if (value.startsWith("/") && tunnelUrl) return;
+  throw new CliError(
+    `Invalid '${fieldName}' in ${APP_CONFIG_FILE}: must be an absolute URL or a path with 'tunnel_url' set.`,
+    { hint: `Edit ${path}` }
+  );
 }
-function validateAdminSection(admin, path) {
+function validateAdminSection(admin, tunnelUrl, path) {
   if (typeof admin !== "object" || admin === null || Array.isArray(admin)) {
     throw new CliError(`Invalid ${APP_CONFIG_FILE}: 'admin' must be a table.`, {
       hint: `Edit ${path}`
     });
   }
   const a = admin;
-  if (typeof a["entry_url"] !== "string" || !a["entry_url"]) {
+  if (a["entry_url"] === void 0) {
+    if (!tunnelUrl) {
+      throw new CliError(`Invalid ${APP_CONFIG_FILE}: missing 'admin.entry_url'.`, {
+        hint: `Set 'tunnel_url' or add 'admin.entry_url' in ${path}.`
+      });
+    }
+  } else if (a["entry_url"] === "") {
     throw new CliError(`Invalid ${APP_CONFIG_FILE}: missing 'admin.entry_url'.`, {
       hint: `Edit ${path}`
     });
-  }
-  if (!a["entry_url"].startsWith("https://")) {
-    throw new CliError(
-      `Invalid 'admin.entry_url' in ${APP_CONFIG_FILE}: must start with https://.`,
-      { hint: `Edit ${path}` }
-    );
+  } else {
+    validateResolvableUrl(a["entry_url"], "admin.entry_url", tunnelUrl, path);
   }
   const sidebar = a["sidebar"];
   if (typeof sidebar !== "object" || sidebar === null || Array.isArray(sidebar)) {
@@ -122,10 +177,30 @@ function validateAdminSection(admin, path) {
     );
   }
 }
+function appUrlFromTunnel(tunnelUrl, pathValue, fieldName, configPath) {
+  if (!tunnelUrl) {
+    throw new CliError(`Cannot resolve '${fieldName}' without 'tunnel_url'.`, {
+      hint: `Set tunnel_url in ${configPath}.`
+    });
+  }
+  const url = new URL(tunnelUrl);
+  url.pathname = pathValue;
+  url.search = "";
+  return url.toString();
+}
+function isAbsoluteHttpUrl(value) {
+  try {
+    const url = new URL(value);
+    return url.protocol === "http:" || url.protocol === "https:";
+  } catch {
+    return false;
+  }
+}
 export {
   ADMIN_ICONS,
   findAppConfigPath,
   loadAppConfig,
+  resolveAppConfigUrl,
   saveAppConfig,
   writeAppConfigAt
 };

package/dist/lib/dev-runner.js

@@ -1,7 +1,8 @@
 import { spawn } from "node:child_process";
-import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { existsSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
-import { APP_ENV_FILE } from "./app-env.js";
+import { saveAppConfig } from "./config.js";
+import { APP_DEV_ENV_FILE, APP_ENV_FILE, APP_ENV_LOCAL_FILE, readEnvFile } from "./app-env.js";
 import { CliError } from "./errors.js";
 async function registerWebhookSubscriptions(api, appName, tunnelUrl, subscriptions) {
   const created = [];
@@ -148,13 +149,19 @@ function devInstallCallbackUrl(opts) {
 }
 function devAppTunnelUrl(opts) {
   const url = new URL(opts.tunnelUrl);
-  if (opts.configuredUrl) {
+  const configuredUrl = opts.configuredUrl?.trim();
+  if (configuredUrl) {
+    if (configuredUrl.startsWith("/")) {
+      url.pathname = configuredUrl;
+      url.search = "";
+      return url.toString();
+    }
     let configured;
     try {
-      configured = new URL(opts.configuredUrl);
+      configured = new URL(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."
+      throw new CliError(`Invalid ${opts.configField ?? "URL"}: ${configuredUrl}`, {
+        hint: "Use an absolute URL, a path starting with '/', or omit it so `tunnel_url` can infer it."
       });
     }
     url.pathname = configured.pathname;
@@ -165,9 +172,16 @@ function devAppTunnelUrl(opts) {
   }
   return url.toString();
 }
+function saveDevTunnelUrl(loaded, tunnelUrl) {
+  if (loaded.config.tunnel_url === tunnelUrl) return false;
+  loaded.config.tunnel_url = tunnelUrl;
+  saveAppConfig(loaded);
+  return true;
+}
 function writeDevEnvFile(cwd, registered) {
   if (registered.length === 0) return null;
-  const path = join(cwd, ".env.odeva.local");
+  const path = join(cwd, APP_DEV_ENV_FILE);
+  const preserved = Object.entries(readEnvFile(path)).filter(([key]) => !key.startsWith("ODEVA_WEBHOOK_SECRET"));
   const lines = [
     "# Auto-generated by `odeva app dev`. Do not commit.",
     "# Reload your dev server to pick up these values."
@@ -178,6 +192,13 @@ function writeDevEnvFile(cwd, registered) {
     lines.push(`# ${reg.config.topic} \u2192 ${reg.fullUrl}`);
     lines.push(`ODEVA_WEBHOOK_SECRET__${webhookSecretEnvKey(reg.config.topic)}=${reg.secret}`);
   }
+  if (preserved.length > 0) {
+    lines.push("");
+    lines.push("# Preserved local values.");
+    for (const [key, value] of preserved) {
+      lines.push(`${key}=${value}`);
+    }
+  }
   writeFileSync(path, lines.join("\n") + "\n", { mode: 384 });
   return path;
 }
@@ -196,7 +217,11 @@ function webhookSecretForEvent(event, env) {
   return env[`ODEVA_WEBHOOK_SECRET__${webhookSecretEnvKey(event)}`] ?? env["ODEVA_WEBHOOK_SECRET"];
 }
 function watchedDevInputPaths(appConfigPath) {
-  return [appConfigPath, join(dirname(appConfigPath), APP_ENV_FILE)];
+  return [
+    appConfigPath,
+    join(dirname(appConfigPath), APP_ENV_FILE),
+    join(dirname(appConfigPath), APP_ENV_LOCAL_FILE)
+  ];
 }
 function joinUrl(base, path) {
   const trimmedBase = base.replace(/\/$/, "");
@@ -341,27 +366,15 @@ function preflightChecks(cwd) {
   }
   return { warnings };
 }
-function readEnvFile(path) {
-  if (!existsSync(path)) return {};
-  const out = {};
-  for (const line of readFileSync(path, "utf8").split("\n")) {
-    const trimmed = line.trim();
-    if (!trimmed || trimmed.startsWith("#")) continue;
-    const eq = trimmed.indexOf("=");
-    if (eq === -1) continue;
-    out[trimmed.slice(0, eq)] = trimmed.slice(eq + 1);
-  }
-  return out;
-}
 export {
   cleanupSubscriptions,
   devAppTunnelUrl,
   devInstallCallbackUrl,
   ensureDevAppInstalled,
   preflightChecks,
-  readEnvFile,
   registerWebhookSubscriptions,
   registeredWebhookEnv,
+  saveDevTunnelUrl,
   spawnDevServer,
   syncDevAppUrls,
   waitForDevServerReachable,

package/package.json

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

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

@@ -30,10 +30,13 @@ This template ships a `/admin` route that verifies Odeva session tokens against
 the platform's JWKS. To surface your app inside the merchant admin sidebar:
 
 1. Uncomment the `[admin]` block at the bottom of `odeva.app.toml` and set
-   `entry_url` to a publicly reachable URL (your `odeva app dev` tunnel works).
+   `entry_url = "/admin"` or omit it to use the default `/admin` path.
 2. Run `odeva app config link` to push the embed config to Odeva.
 3. Reinstall the app on a test org; the sidebar entry appears.
 
+`odeva app dev` writes the active public tunnel to `tunnel_url`; the CLI
+resolves relative app URLs such as `/install` and `/admin` against it.
+
 `/admin` reads `?session_token=<jwt>` from the iframe URL, verifies it via
 `jose` + the JWKS at `${ODEVA_API_URL}/.well-known/odeva/apps/jwks.json`,
 and renders `Hello, org <org_id>`. See `src/admin.ts` for the verification

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

@@ -2,10 +2,11 @@ name = "{{name}}"
 slug = "{{slug}}"
 description = "An Odeva app."
 
-# Where Odeva redirects users when they install this app on their org.
-# Must be a publicly reachable URL once you submit for marketplace review.
-# During development you can leave it blank or point it at your `odeva app dev` tunnel.
-install_url = ""
+# `odeva app dev` keeps this set to the active public tunnel.
+# `install_url` and `[admin].entry_url` can be omitted or written as paths;
+# the CLI resolves them against tunnel_url when syncing the app record.
+tunnel_url = ""
+install_url = "/install"
 
 [build]
 dev = "bun run dev"
@@ -35,7 +36,7 @@ api_version = "2026-01"
 # Icons: puzzle, box, plug, bot, sparkles, wrench, database, bar-chart, wallet.
 #
 # [admin]
-# entry_url = "https://<your-app-dev-url>/admin"
+# entry_url = "/admin"
 #
 # [admin.sidebar]
 # label = "{{name}}"