@biznetgio/neo-app 0.4.70 → 0.4.73

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@biznetgio/neo-app",
-  "version": "0.4.70",
+  "version": "0.4.73",
   "description": "NEO App CLI — one-command agent onboarding, MCP server, and project ops for coding agents (Codex, Claude Code).",
   "type": "module",
   "bin": {

package/src/commands/deploy.js

@@ -35,6 +35,9 @@ function showCost(r) {
     const e = r.estimatedCost;
     const note = (e.assumptions || []).join('; ');
     log(c.bold(`Estimated cost: ${formatCost(e)}`) + (note ? c.dim(` — ${note}`) : ''));
+    // Identify the exact price-book snapshot the quote (and any approval) is pinned to (#170 r18a D1).
+    const ver = e.priceBookVersion || r.priceBookVersion;
+    if (ver) log(c.dim(`  price book: ${ver}`));
   }
 }
 
@@ -95,6 +98,16 @@ export async function deploy(source, opts = {}) {
     log: step,
   };
 
+  // --json: machine-readable + non-interactive. A real deploy still requires --yes; otherwise
+  // deploySource returns the priced gate (requiresConfirmation + estimatedCost + confirmToken)
+  // and deploys nothing. One shape, mirroring the MCP cost schema (#170).
+  if (opts.json) {
+    const r = await deploySource(api, { ...base, log: () => {}, dryRun, confirm: !!opts.yes });
+    process.stdout.write(JSON.stringify(r, null, 2) + '\n');
+    if (r.result && r.result !== 'success' && !r.dryRun && !r.requiresConfirmation && !r.pending) process.exitCode = 1;
+    return r;
+  }
+
   // Cost gate: a real deploy is billable, so it needs explicit approval. `--yes` approves
   // up front (headless/CI); otherwise preview the cost first, then confirm (interactive)
   // or require `--yes` (non-interactive). A spec-bound confirmToken links the approval to

package/src/commands/estimate.js

@@ -0,0 +1,82 @@
+// `neo-app estimate` — a read-only cost quote from the server's authoritative price book
+// (#170 r18a D2). Works WITHOUT a project (org-scoped), unlike `deploy --dry-run` which
+// needs one, so a vibe coder can price a resource before creating anything. Zero-write.
+
+import { resolveConfig } from '../config.js';
+import { getCredential } from '../creds.js';
+import { NeoApi } from '../api.js';
+import { readLink } from '../link.js';
+import { specToResources, formatCost } from '../cost.js';
+import { log, ok, fail, c } from '../util.js';
+
+// buildSpec turns the CLI flags into the flat cost spec specToResources understands.
+function buildSpec(opts) {
+  const spec = {};
+  if (opts.tier) spec.computeTier = opts.tier;
+  if (opts.vcpu) spec.vcpu = Number(opts.vcpu);
+  if (opts.mem) spec.memoryMB = Number(opts.mem);
+  if (opts.storage) spec.storageGB = Number(opts.storage);
+  if (opts.object) spec.objectStorageGB = Number(opts.object);
+  if (opts.replicas) spec.replicas = Number(opts.replicas);
+  if (opts.queue) spec.queue = true;
+  if (opts.cron) spec.cron = true;
+  return spec;
+}
+
+export async function estimate(opts = {}) {
+  const cfg = resolveConfig(opts);
+  const cred = getCredential(cfg.baseUrl);
+  if (!cred?.token) {
+    fail(`not authenticated for ${cfg.baseUrl} — run 'neo-app login'`);
+    process.exit(1);
+  }
+  const api = new NeoApi({ baseUrl: cfg.baseUrl, token: cred.token });
+
+  const spec = buildSpec(opts);
+  const resources = specToResources(spec);
+  if (!resources.length) {
+    fail('nothing to estimate — pass --tier <micro|small|…> (or --vcpu N --mem MB), --storage GB, --object GB, --queue, or --cron');
+    process.exit(2);
+  }
+
+  // Scope: an explicit/linked project (exact org context) else the account's org — the
+  // server authority is the same, so a project-less quote still works.
+  const projectId = opts.project || readLink()?.projectId;
+  let scope;
+  if (projectId) scope = { projectId };
+  else {
+    let orgId = opts.org;
+    if (!orgId) { try { orgId = await api.resolveOrgId(); } catch { orgId = null; } }
+    if (!orgId) { fail('no project or organization — run \'neo-app login\', or pass --project <id> / --org <id>'); process.exit(1); }
+    scope = { orgId };
+  }
+
+  let cost;
+  try {
+    cost = (await api.estimate(scope, { resources })).cost;
+  } catch (e) {
+    fail(`estimate failed: ${e.message || e}`);
+    process.exit(1);
+  }
+
+  // Fail closed when the server can't price a metric (#170: never quote at a guessed rate).
+  if (cost?.pricingUnavailable?.length) {
+    if (opts.json) process.stdout.write(JSON.stringify({ cost }, null, 2) + '\n');
+    fail(`pricing unavailable for: ${cost.pricingUnavailable.join(', ')} — cannot quote`);
+    process.exit(1);
+  }
+
+  if (opts.json) {
+    process.stdout.write(JSON.stringify({ cost }, null, 2) + '\n');
+    return cost;
+  }
+
+  log(c.bold(`Estimated cost: ${formatCost(cost)}`));
+  for (const l of cost.breakdown || []) log(`  · ${l.item}: ${l.monthly} ${cost.currency}/mo (${l.hourly}/h)`);
+  for (const u of cost.upfront || []) log(`  · ${u.item}: ${u.monthly} ${cost.currency} upfront (hourly: n/a)`);
+  for (const v of cost.variable || []) log(c.dim(`  usage: ${v.rate} ${cost.currency}/${v.unit || v.metric}`));
+  if (cost.priceBookVersion) log(c.dim(`  price book: ${cost.priceBookVersion} · billing quantum: ${cost.billingQuantum || 'hour'}`));
+  for (const a of cost.assumptions || []) log(c.dim(`  assumption: ${a}`));
+  ok('estimate complete — nothing was created');
+  return cost;
+}

package/src/cost.js

@@ -26,6 +26,13 @@ export function specToResources(spec = {}) {
   }
   if (spec.storageGB) resources.push({ kind: 'database', name: 'storage', volumeSize: `${spec.storageGB}Gi` });
   if (spec.objectStorageGB) resources.push({ kind: 'bucket', name: 'object', quotaGB: spec.objectStorageGB });
+  // A cron has no fixed cost — it's billed per run. The server returns it as a 0 fixed
+  // line plus the `cron_run` rate in `variable[]`, which is what the gate surfaces (#170).
+  if (spec.cron) resources.push({ kind: 'cron', name: 'cron' });
+  // A queue bills ONLY per message (queue_message) — never compute/storage (JNG #52). It is
+  // its OWN kind, not a database: mapping queue storage to a `database` resource priced it as
+  // DB compute+storage and mislabeled it "database storage" (#170 r18a D5).
+  if (spec.queue) resources.push({ kind: 'queue', name: 'queue' });
   return resources;
 }
 

package/src/index.js

@@ -16,6 +16,7 @@ ${c.bold('Commands')}
   login                    Authenticate with a NEO App API key (kap_...)
   link <project-id>        Link this repo to a project (writes .neo-app.json)
   deploy [path|.zip|git-url]   Deploy a directory (default: cwd), a .zip, a Git repo, or --image <ref>
+  estimate                 Price a resource from the server price book (read-only; no project needed)
                            (or pass the same via --source <path|.zip|git-url>)
   project create [name]    Create a project (defaults to the dir name) and link it
   project list             List projects in your organization (find ids to link)
@@ -35,6 +36,13 @@ ${c.bold('Options')}
   --token <kap_...>        API key (also NEO_APP_TOKEN; prompted if omitted)
   --yes                    Non-interactive (headless/CI); also approves a billable deploy without the cost prompt
   --dry-run               Print intended changes without writing
+  --json                   Machine-readable output incl. the normalized cost (deploy, estimate)
+  --tier <key>             estimate: compute tier (micro|small|medium|large|xlarge)
+  --vcpu <n> --mem <MB>    estimate: custom compute (instead of --tier)
+  --storage <GB>           estimate: database/persistent storage
+  --object <GB>            estimate: object-storage quota (billed monthly-upfront)
+  --queue / --cron         estimate: a queue (per-message) / cron (per-run) resource
+  --replicas <n>           estimate: replica count
   -v, --version           Print version
   -h, --help              Show this help`;
 
@@ -63,6 +71,15 @@ const options = {
   prod: { type: 'boolean' },
   yes: { type: 'boolean' },
   'dry-run': { type: 'boolean' },
+  json: { type: 'boolean' },
+  tier: { type: 'string' },
+  vcpu: { type: 'string' },
+  mem: { type: 'string' },
+  storage: { type: 'string' },
+  object: { type: 'string' },
+  replicas: { type: 'string' },
+  queue: { type: 'boolean' },
+  cron: { type: 'boolean' },
   version: { type: 'boolean', short: 'v' },
   help: { type: 'boolean', short: 'h' },
 };
@@ -85,7 +102,7 @@ export async function main(argv = process.argv.slice(2)) {
   // Root help, and `--help` on a KNOWN command, print usage. An UNKNOWN command must
   // still error (nonzero exit) even with `--help`, so a bad command isn't silently
   // accepted (JNG #97). Per-subcommand help is tracked in #89.
-  const KNOWN_COMMANDS = new Set(['agent', 'setup', 'config', 'login', 'deploy', 'link', 'project', 'status', 'whoami', 'mcp', 'version', 'help']);
+  const KNOWN_COMMANDS = new Set(['agent', 'setup', 'config', 'login', 'deploy', 'estimate', 'link', 'project', 'status', 'whoami', 'mcp', 'version', 'help']);
   if (positionals.length === 0 || (opts.help && KNOWN_COMMANDS.has(cmd))) return void console.log(HELP);
 
   try {
@@ -96,6 +113,7 @@ export async function main(argv = process.argv.slice(2)) {
     if (cmd === 'config' && sub === 'install-mcp') return void (await (await import('./commands/install-mcp.js')).installMcp(opts));
     if (cmd === 'login') return void (await (await import('./commands/login.js')).login(opts));
     if (cmd === 'deploy') return void (await (await import('./commands/deploy.js')).deploy(sub, opts));
+    if (cmd === 'estimate') return void (await (await import('./commands/estimate.js')).estimate(opts));
     if (cmd === 'link') return void (await (await import('./commands/link.js')).link(sub, opts));
     if (cmd === 'project' && sub === 'link') return void (await (await import('./commands/link.js')).link(positionals[2], opts));
     if (cmd === 'project' && sub === 'create') return void (await (await import('./commands/link.js')).createProject(positionals[2], opts));

package/src/mcp/tools.js

@@ -153,26 +153,33 @@ function validateBucketArgs(args) {
 // args.confirm===true it returns the live-priced cost and creates NOTHING — the
 // agent shows the user, then re-calls with confirm:true. plan/apply remains the
 // server-immutable costed path; this is the lighter client-side gate (handoff 3.3).
-async function confirmCost(api, args, spec) {
+async function confirmCost(api, args, spec, currentSpec) {
   if (args.confirm === true) return null;
   let orgId = null;
   try { orgId = await api.resolveOrgId(args.orgId); } catch { orgId = null; }
   // The server's /estimate is the sole price authority (#170) — the CLI no longer prices
   // locally. Prefer the project scope (exact org context); fall back to org scope for a
-  // project-less quote. Best-effort: a failed estimate must never fail the gate.
-  let cost = null;
+  // project-less quote. When a CURRENT spec is given (a change flow), ask the server for
+  // the delta too (current → proposed → increase). Best-effort: a failed estimate must
+  // never fail the gate.
+  let cost = null, delta = null;
   const resources = specToResources(spec);
+  const current = currentSpec ? specToResources(currentSpec) : null;
   if (resources.length && (args.projectId || orgId)) {
-    try { cost = (await api.estimate(args.projectId ? { projectId: args.projectId } : { orgId }, { resources })).cost; }
-    catch { cost = null; }
+    try {
+      const body = current && current.length ? { resources, current } : { resources };
+      const r = await api.estimate(args.projectId ? { projectId: args.projectId } : { orgId }, body);
+      cost = r.cost; delta = r.delta || null;
+    } catch { cost = null; }
   }
   return {
     requiresConfirmation: true,
     cost,
+    delta, // current → proposed → increase, when a current spec was given (#170 change delta)
     priceBookVersion: cost?.priceBookVersion, // pins the quote to a price-book snapshot (#170)
     acting: await actingOf(api, { orgId, projectId: args.projectId }), // whose/where — JNG #131
     priceBook: cost?.priceBook || (orgId ? `org:${orgId}` : 'global-defaults'),
-    message: 'Billable resource — show the user this cost (and the acting account/org), then re-call with confirm:true to create. For an immutable, server-pinned quote use neo_plan_stack → neo_apply_stack.',
+    message: 'Billable change — show the user BOTH the hourly and monthly cost (and the increase delta, plus any per-use variable rates), then re-call with confirm:true to apply. For an immutable, server-pinned quote use neo_plan_stack → neo_apply_stack.',
   };
 }
 
@@ -203,7 +210,7 @@ async function billableGate(api, { projectId, kind, name, confirmationId, confir
   // from failing an otherwise-fine create (same spirit as the api-layer idempotent retry).
   let mint;
   for (let attempt = 1; ; attempt++) {
-    try { mint = (await api.post('/api/v1/confirmations', { action: 'billable_create', projectId, kind, name, environment, estimatedCost: costNote, priceBookVersion: cost?.priceBookVersion })).data; break; }
+    try { mint = (await api.post('/api/v1/confirmations', { action: 'billable_create', projectId, kind, name, environment, estimatedCost: costNote, priceBookVersion: cost?.priceBookVersion, cost })).data; break; }
     catch (e) {
       if (attempt < 3 && (e?.status >= 500 || e?.status === 0)) { await new Promise((r) => setTimeout(r, 300 * attempt)); continue; }
       throw e;
@@ -499,21 +506,26 @@ export const TOOLS = [
         // effective compute — the one being set, else the service's CURRENT compute. Without
         // the current compute, an autoscale-only change estimated to IDR 0 (#123).
         const replicas = args.replicas ?? args.autoscaleMax ?? args.autoscaleMin;
+        // Read the service's CURRENT compute/storage once — for the empty-tier default (#123)
+        // AND the change delta (current → proposed → increase).
+        let svc = {};
+        try { const d = (await api.get(`/api/v1/apps/${appId}`)).data; svc = (d && d.application) || d || {}; } catch { /* best-effort */ }
+        // A bundled service with no explicit tier bills at the default "micro" (store.DefaultTierKey);
+        // using the empty cpuLimit as-is priced the gate at IDR 0 (#123).
+        const svcSpec = (svc.billingMode === 'unbundled' && (svc.cpuLimit || svc.memoryLimit))
+          ? { vcpu: cpuToVcpu(svc.cpuLimit), memoryMB: memToMB(svc.memoryLimit) }
+          : { computeTier: svc.cpuLimit || 'micro' };
         let spec;
         if (computeTier) spec = { computeTier, replicas };
         else if (args.cpuLimit || args.memoryLimit) spec = { vcpu: cpuToVcpu(args.cpuLimit), memoryMB: memToMB(args.memoryLimit), replicas };
-        else {
-          let svc = {};
-          try { const d = (await api.get(`/api/v1/apps/${appId}`)).data; svc = (d && d.application) || d || {}; } catch { /* best-effort */ }
-          // A bundled service with no explicit tier bills at the default "micro" (store.DefaultTierKey);
-          // using the empty cpuLimit as-is priced the gate at IDR 0 (#123).
-          spec = (svc.billingMode === 'unbundled' && (svc.cpuLimit || svc.memoryLimit))
-            ? { vcpu: cpuToVcpu(svc.cpuLimit), memoryMB: memToMB(svc.memoryLimit), replicas }
-            : { computeTier: svc.cpuLimit || 'micro', replicas };
+        else spec = { ...svcSpec, replicas };
+        const currentSpec = { ...svcSpec, replicas: svc.replicas ?? svc.scaleMin };
+        if (args.volumeSize !== undefined) { // persistent-volume price in the gate (JNG #129)
+          spec = { ...spec, storageGB: gbFromSize(args.volumeSize) };
+          if (svc.volumeSize) currentSpec.storageGB = gbFromSize(svc.volumeSize);
         }
-        if (args.volumeSize !== undefined) spec = { ...spec, storageGB: gbFromSize(args.volumeSize) }; // persistent-volume price in the gate (JNG #129)
-        const gate = await confirmCost(api, args, spec);
-        if (gate) return { ...gate, change: 'update service compute/scaling/volume', message: 'This changes cost — re-call with confirm:true to apply.' };
+        const gate = await confirmCost(api, args, spec, currentSpec);
+        if (gate) return { ...gate, change: 'update service compute/scaling/volume', message: 'This changes cost — show BOTH the hourly and monthly cost and the increase, then re-call with confirm:true to apply.' };
       }
       const { status, data } = await api.put(`/api/v1/apps/${appId}`, body);
       const out = redactSecrets(result(status, data));
@@ -864,15 +876,16 @@ export const TOOLS = [
     },
     async call(api, args) {
       if (args.confirm !== true) {
-        let computeTier;
+        let computeTier, currentReplicas;
         try {
           const apps = (await api.get(`/api/v1/projects/${args.projectId}/apps`)).data;
           const list = Array.isArray(apps) ? apps : (apps.applications || []);
           const svc = list.find((a) => a.name === args.service || a.id === args.service);
-          computeTier = svc && (svc.cpuLimit || svc.computeTier);
+          if (svc) { computeTier = svc.cpuLimit || svc.computeTier; currentReplicas = svc.replicas ?? svc.scaleMin; }
         } catch { /* best effort — gate regardless */ }
-        const gate = await confirmCost(api, args, { computeTier, replicas: args.replicas });
-        if (gate) return { ...gate, change: `scale "${args.service}" to ${args.replicas} replica(s)`, message: 'Scaling changes cost — show the user and re-call with confirm:true to apply.' };
+        // Price the delta against the current replica count so the user sees current → proposed → increase.
+        const gate = await confirmCost(api, args, { computeTier, replicas: args.replicas }, { computeTier, replicas: currentReplicas });
+        if (gate) return { ...gate, change: `scale "${args.service}" to ${args.replicas} replica(s)`, message: 'Scaling changes cost — show the user BOTH time bases and the increase, then re-call with confirm:true to apply.' };
       }
       const { status, data } = await api.post(
         `/api/v1/projects/${args.projectId}/services/${args.service}/scale`,
@@ -1184,8 +1197,12 @@ export const TOOLS = [
     async call(api, args) {
       const costChanging = args.volumeSize || args.replicas !== undefined;
       if (costChanging && args.confirm !== true) {
-        const gate = await confirmCost(api, args, { storageGB: gbFromSize(args.volumeSize), replicas: args.replicas });
-        if (gate) return { ...gate, change: 'resize database (storage/replicas)', message: 'Resizing changes cost — re-call with confirm:true to apply.' };
+        // Read current storage for the change delta (current → proposed → increase).
+        let cur = {};
+        try { const d = (await api.get(`/api/v1/databases/${args.databaseId}`)).data; cur = (d && d.database) || d || {}; } catch { /* best-effort */ }
+        const currentSpec = { storageGB: cur.volumeSize ? gbFromSize(cur.volumeSize) : undefined, replicas: cur.replicas };
+        const gate = await confirmCost(api, args, { storageGB: gbFromSize(args.volumeSize), replicas: args.replicas }, currentSpec);
+        if (gate) return { ...gate, change: 'resize database (storage/replicas)', message: 'Resizing changes cost — show BOTH time bases and the increase, then re-call with confirm:true to apply.' };
       }
       const body = {};
       if (args.volumeSize) body.volumeSize = args.volumeSize;
@@ -1304,7 +1321,7 @@ export const TOOLS = [
     },
     async call(api, args) {
       const environment = requireEnv(args.environment, args.allowCrossEnvironment); // explicit, else the session pin (JNG #136)
-      const gate = await billableGate(api, { projectId: args.projectId, kind: 'queue', name: args.name, confirmationId: args.confirmationId, confirm: args.confirm, environment }, { storageGB: gbFromSize(args.volumeSize) });
+      const gate = await billableGate(api, { projectId: args.projectId, kind: 'queue', name: args.name, confirmationId: args.confirmationId, confirm: args.confirm, environment }, { queue: true }); // queue bills per-message only (JNG #52) — 0 fixed + queue_message rate
       if (gate.requiresConfirmation) return { environment, ...gate };
       const { projectId, confirm, confirmationId, orgId, ...body } = args;
       body.environment = environment; // send the resolved env so the pin actually targets it
@@ -1359,8 +1376,10 @@ export const TOOLS = [
     async call(api, args) {
       const costChanging = args.volumeSize || args.planClass;
       if (costChanging && args.confirm !== true) {
-        const gate = await confirmCost(api, args, { storageGB: gbFromSize(args.volumeSize) });
-        if (gate) return { ...gate, change: 'update queue (storage/plan)', message: 'This changes cost — re-call with confirm:true to apply.' };
+        // A queue has no fixed cost — it bills per message (queue_message, JNG #52), so a
+        // storage/plan change doesn't move the fixed bill. The gate surfaces the per-message rate.
+        const gate = await confirmCost(api, args, { queue: true });
+        if (gate) return { ...gate, change: 'update queue (storage/plan)', message: 'Queue bills per message — no fixed-cost change; the queue_message rate is shown. Re-call with confirm:true to apply.' };
       }
       const { queueId, confirm, orgId, ...body } = args;
       const { status, data } = await api.put(`/api/v1/queues/${queueId}`, body);
@@ -1444,7 +1463,7 @@ export const TOOLS = [
     },
     async call(api, args) {
       const environment = requireEnv(args.environment, args.allowCrossEnvironment); // explicit, else the session pin (JNG #136)
-      const gate = await billableGate(api, { projectId: args.projectId, kind: 'cron', name: args.name, confirmationId: args.confirmationId, confirm: args.confirm }, {}); // cron cost is variable (per-run) — gate surfaces the rate
+      const gate = await billableGate(api, { projectId: args.projectId, kind: 'cron', name: args.name, confirmationId: args.confirmationId, confirm: args.confirm }, { cron: true }); // cron has no fixed cost — the contract surfaces the per-run `cron_run` rate in cost.variable
       if (gate.requiresConfirmation) return { environment, ...gate };
       // Merge contentType into headers for convenience (unless already set).
       if (args.contentType) {
@@ -2027,7 +2046,11 @@ export const TOOLS = [
     },
     async call(api, args) {
       const { status, data } = await api.post(`/api/v1/databases/${args.databaseId}/public-access`, { allowlistCidrs: args.allowlistCidrs || [] });
-      return redactSecrets(result(status, data));
+      const out = redactSecrets(result(status, data));
+      // Public access adds no fixed monthly charge, but egress through the gateway is metered
+      // per GB (usage-based). Surface that so enabling it isn't a silent billing change (#170).
+      if (out && typeof out === 'object') out.billingNote = 'No fixed monthly cost is added. Data transfer (egress) through the public TLS gateway is metered per GB — see the usage-based rates via neo_estimate (cost.variable).';
+      return out;
     },
   },
   {
@@ -2054,7 +2077,9 @@ export const TOOLS = [
     },
     async call(api, args) {
       const { status, data } = await api.post(`/api/v1/queues/${args.queueId}/public-access`, { allowlistCidrs: args.allowlistCidrs || [] });
-      return redactSecrets(result(status, data));
+      const out = redactSecrets(result(status, data));
+      if (out && typeof out === 'object') out.billingNote = 'No fixed monthly cost is added. Data transfer (egress) through the public TLS gateway is metered per GB — see the usage-based rates via neo_estimate (cost.variable).';
+      return out;
     },
   },
   {