@biznetgio/neo-app 0.4.2 → 0.4.7

package/package.json

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

package/prompt.md

@@ -6,7 +6,7 @@ Keep this in sync with pkg/api/prompt.md (the copy the Go server embeds).
 -->
 # Set this repo up on NEO App
 
-**Version:** 0.4.0 · **Last updated:** 2026-10-12
+**Version:** 0.4.3 · **Last updated:** 2026-10-13
 
 These are the official setup instructions from NEO App (Biznet Gio's managed-app
 platform). If you are an AI coding agent, complete the steps below yourself by running
@@ -23,6 +23,32 @@ several containers running side by side at runtime (a single app container along
 managed databases is fine). If the repo has no server to put behind a URL (a library or
 a CLI tool), say so and stop.
 
+## Before you start: terminal and Node.js
+
+Before running setup, verify that Node.js 18+ and `npx` are available.
+
+- If `npx` is available, run the setup command normally.
+- If the coding environment provides a bundled Node.js runtime, use its bundled package
+  runner instead of installing another copy of Node.js.
+- Otherwise, ask the human before installing Node.js system-wide.
+
+Authentication must run in a visible, interactive terminal. If the agent's normal command
+runner cannot display or accept the API-key prompt, open a dedicated terminal window and
+run the setup command there. On Windows, this may be a separate PowerShell window.
+
+Clearly tell the human:
+
+1. Revoke any token accidentally pasted into chat or a normal shell prompt.
+2. Create a fresh token in *Settings → API tokens*.
+3. Paste it only when the terminal displays:
+   ```
+   Paste your NEO App API key (kap_...):
+   ```
+4. Never paste the token into chat.
+
+Do not run an API token as a PowerShell command, pass it as a command-line argument, or
+write it to a repository file.
+
 ## 1. Install the CLI, skill, and MCP server
 
 One command, every OS and shell (Node 18+). Installs the NEO App skill for your coding

package/src/api.js

@@ -46,6 +46,18 @@ export class NeoApi {
     return { status: res.status, data: payload };
   }
 
+  // postRaw streams raw bytes (e.g. a gzip-tar build context) as the request body.
+  async postRaw(path, body, contentType = 'application/octet-stream') {
+    const headers = { 'Content-Type': contentType };
+    if (this.token) headers.Authorization = `Bearer ${this.token}`;
+    const res = await fetch(this.baseUrl + path, { method: 'POST', headers, body });
+    const payload = await res.json().catch(() => null);
+    if (res.status >= 400) {
+      throw new ApiError(res.status, (payload && payload.error) || res.statusText, payload);
+    }
+    return { status: res.status, data: payload };
+  }
+
   get(path, opts) {
     return this.request('GET', path, opts);
   }

package/src/commands/deploy.js

@@ -1,29 +1,41 @@
-// `neo-app deploy` — create-or-reuse a web service in the linked project and ship it,
-// then poll until the deployment reaches a terminal state (parity with `insta deploy`).
-// Sources: --image <ref> (prebuilt, no build) or --repo <git-url> (server builds it).
+// `neo-app deploy [source]` — deploy a directory (default: cwd), a .zip, a Git repo, or
+// a prebuilt --image. Thin CLI wrapper around ~/deploySource (shared with the MCP tool).
 
-import { basename } from 'node:path';
+import { resolve } from 'node:path';
+import { statSync } from 'node:fs';
 import { resolveConfig } from '../config.js';
 import { getCredential } from '../creds.js';
 import { NeoApi } from '../api.js';
 import { readLink } from '../link.js';
-import { log, ok, fail, step, c } from '../util.js';
+import { deploySource } from '../deploySource.js';
+import { log, ok, fail, warn, step, c } from '../util.js';
 
-function sanitizeName(s) {
-  return (
-    String(s)
-      .toLowerCase()
-      .replace(/[^a-z0-9-]+/g, '-')
-      .replace(/^-+|-+$/g, '')
-      .slice(0, 60) || 'app'
-  );
+function isGitUrl(s) {
+  if (!s) return false;
+  return /^(https?:\/\/|git@|ssh:\/\/)/.test(s) && (/\.git(#|$)/.test(s) || /(github\.com|gitlab\.|bitbucket\.)/.test(s));
 }
-
-function pending(res) {
-  return res.status === 202 && res.data && res.data.status === 'pending_approval';
+function isZip(s) {
+  try {
+    return !!s && /\.zip$/i.test(s) && statSync(s).isFile();
+  } catch {
+    return false;
+  }
+}
+function isDir(s) {
+  try {
+    return !!s && statSync(s).isDirectory();
+  } catch {
+    return false;
+  }
 }
 
-export async function deploy(opts = {}) {
+export async function deploy(source, opts = {}) {
+  // Forgive the common mix-up: --url is the CONTROL-PLANE override, not the Git repo.
+  if (!source && !opts.repo && !opts.image && isGitUrl(opts.url)) {
+    warn('`--url` is the control-plane URL, not the Git repo — using it as the repo. Next time: `neo-app deploy <git-url>` or `--repo <url>`.');
+    opts = { ...opts, repo: opts.url, url: undefined };
+  }
+
   const cfg = resolveConfig(opts);
   const cred = getCredential(cfg.baseUrl);
   if (!cred?.token) {
@@ -38,81 +50,52 @@ export async function deploy(opts = {}) {
     process.exit(1);
   }
 
-  const image = opts.image;
-  const repo = opts.repo;
-  if (!image && !repo) {
-    fail('specify a source: --image <ref> or --repo <git-url>');
+  // Resolve the source: --image > --repo > positional (git url | .zip | directory) > cwd.
+  let src;
+  if (opts.image) src = { mode: 'image', image: opts.image };
+  else if (opts.repo) src = { mode: 'git', repo: opts.repo, branch: opts.branch };
+  else if (source && isGitUrl(source)) src = { mode: 'git', repo: source, branch: opts.branch };
+  else if (source && isZip(source)) src = { mode: 'zip', zipFile: resolve(source) };
+  else if (source && isDir(source)) src = { mode: 'dir', dir: resolve(source) };
+  else if (source) {
+    fail(`'${source}' is not a Git URL, a .zip file, or an existing directory (use --image for a prebuilt image)`);
     process.exit(2);
+  } else {
+    src = { mode: 'dir', dir: process.cwd() };
+    step(`no source given — deploying the current directory (${src.dir})`);
   }
 
-  const name = sanitizeName(
-    opts.name || (image ? image.split('/').pop().split(':')[0] : basename(repo, '.git'))
-  );
   const environment = cfg.env === 'staging' ? 'staging' : 'production';
+  log(`${c.bold('Deploying')} ${c.dim(`[${src.mode}] → ${cfg.env} · project ${projectId}`)}`);
 
-  log(`${c.bold('Deploying')} ${name} ${c.dim(`→ ${cfg.env} · project ${projectId}`)}`);
+  const dryRun = !!opts['dry-run'];
+  if (dryRun) log(c.dim('dry-run — no changes will be made'));
 
-  // Create-or-reuse the service by name.
-  const existing = (await api.get(`/api/v1/projects/${projectId}/apps`)).data?.applications || [];
-  let app = existing.find((a) => a.name === name);
+  const r = await deploySource(api, {
+    projectId,
+    src,
+    name: opts.name,
+    port: opts.port,
+    build: opts.build,
+    environment,
+    dryRun,
+    timeout: Number(opts.timeout) || 300,
+    log: step,
+  });
 
-  if (!app) {
-    const res = await api.post(`/api/v1/projects/${projectId}/apps`, {
-      name,
-      environment,
-      serviceType: 'web',
-      buildType: image ? 'image' : opts.build || 'railpack',
-      image: image || undefined,
-      repoUrl: repo || undefined,
-      branch: opts.branch || undefined,
-      port: opts.port ? Number(opts.port) : undefined,
-      tls: true,
-    });
-    if (pending(res)) {
-      ok(`create submitted — pending approval (${res.data.approvalId}). An owner/admin must approve, then re-run.`);
-      return;
-    }
-    app = res.data?.application || res.data;
-    ok(`created service ${name}`);
-  } else {
-    step(`service ${name} exists — redeploying`);
-    if (image && app.image !== image) await api.put(`/api/v1/apps/${app.id}`, { image });
+  if (r.dryRun) {
+    ok(`dry-run complete — ${r.plan.length} step(s) planned, nothing written`);
+    return r;
   }
-
-  // Ship it.
-  const dep = await api.post(`/api/v1/apps/${app.id}/deploy`);
-  if (pending(dep)) {
-    ok(`deploy submitted — pending approval (${dep.data.approvalId}).`);
+  if (r.pending) {
+    ok(`submitted — pending approval (${r.approvalId}). An owner/admin must approve.`);
     return;
   }
-  const deployId = dep.data?.id;
-  step(`deployment ${deployId} started`);
-
-  const result = await pollDeployment(api, deployId, Number(opts.timeout) || 300);
-
-  const view = (await api.get(`/api/v1/apps/${app.id}`)).data?.application || {};
-  const url = view.domain ? `https://${view.domain}` : '';
-  if (result === 'success') {
-    ok(`deployed ${name}${url ? ' → ' + c.bold(url) : ''}`);
+  if (r.result === 'success') {
+    ok(`deployed${r.url ? ' → ' + c.bold(r.url) : ''}`);
   } else {
-    fail(`deployment ${result}${deployId ? ` (neo-app logs via 'neo_get_logs' or the portal)` : ''}`);
+    fail(`deployment ${r.result} — check logs in the portal or via the neo_get_logs MCP tool`);
     process.exitCode = 1;
   }
-  return { appId: app.id, url, result };
-}
-
-async function pollDeployment(api, id, timeoutSec) {
-  if (!id) return 'unknown';
-  const deadline = Date.now() + timeoutSec * 1000;
-  let last = '';
-  while (Date.now() < deadline) {
-    const d = (await api.get(`/api/v1/deployments/${id}`)).data || {};
-    if (d.status && d.status !== last) {
-      step(`  ${d.status}`);
-      last = d.status;
-    }
-    if (d.status === 'success' || d.status === 'failed') return d.status;
-    await new Promise((r) => setTimeout(r, 4000));
-  }
-  return 'timeout';
+  return r;
 }

package/src/commands/doctor.js

@@ -74,8 +74,9 @@ export async function doctor(opts = {}) {
   const info = storeInfo();
   if (cred?.source === 'env') ok('credentials from NEO_APP_TOKEN (env)');
   else if (!info.exists) warn('no credential file');
-  else if (info.secure) ok(`credentials file user-only (${info.path})`);
-  else bad(`credentials file is not 0600 (${info.mode}) — run 'chmod 600 ${info.path}'`);
+  else if (info.secure === true) ok(`credentials file access-restricted (${info.path})`);
+  else if (info.secure === false) bad(`credentials file is world-accessible${info.mode ? ` (mode ${info.mode})` : ''} — run '${info.remediation}'`);
+  else warn(`could not verify credentials file permissions (${info.path})`);
 
   // Required executables
   onPath('npx') ? ok('npx available') : warn("npx not found — needed for the npx install path");

package/src/creds.js

@@ -11,6 +11,7 @@
 import { homedir } from 'node:os';
 import { join } from 'node:path';
 import { mkdirSync, readFileSync, writeFileSync, chmodSync, existsSync, rmSync, statSync } from 'node:fs';
+import { execFileSync } from 'node:child_process';
 
 function storeDir() {
   const base = process.env.XDG_CONFIG_HOME || join(homedir(), '.config');
@@ -69,17 +70,31 @@ export function deleteCredential(baseUrl) {
 }
 
 // storeInfo reports where creds live and whether the file is user-only (for doctor).
+// Security is judged per-platform (JNG #98): POSIX mode bits on Linux/macOS, the NTFS
+// ACL on Windows — where stat.mode is meaningless (it reports 0o666 even for a locked
+// file), so `chmod 600` is never used as the proof. `remediation` is the platform's
+// own fix command. On any error `secure` stays null (unknown) rather than falsely
+// flagged. No credential value is read or returned.
 export function storeInfo() {
   const path = storePath();
-  const info = { path, exists: existsSync(path), secure: null };
-  if (info.exists) {
-    try {
+  const info = { path, platform: process.platform, exists: existsSync(path), secure: null };
+  if (!info.exists) return info;
+  try {
+    if (process.platform === 'win32') {
+      // Secure when the ACL grants no access to broad principals (Everyone / Users /
+      // Authenticated Users). icacls prints one grant per line as `principal:(perms)`.
+      const acl = execFileSync('icacls', [path], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] });
+      const broad = /(^|\\|\s)(Everyone|Users|Authenticated Users|Tout le monde)\s*:/im.test(acl);
+      info.secure = !broad;
+      info.remediation = `icacls "${path}" /inheritance:r /grant:r "%USERNAME%":F`;
+    } else {
       const mode = statSync(path).mode & 0o777;
       info.secure = mode === 0o600;
       info.mode = mode.toString(8);
-    } catch {
-      /* ignore */
+      info.remediation = `chmod 600 "${path}"`;
     }
+  } catch {
+    /* secure stays null (couldn't determine) */
   }
   return info;
 }

package/src/deploySource.js

@@ -0,0 +1,275 @@
+// Shared deploy core used by the `deploy` CLI command and the neo_deploy_folder MCP
+// tool: create-or-reuse a web service, upload a local build context (dir → gzip-tar,
+// .zip → as-is) when relevant, trigger the deploy, and poll to a terminal state.
+
+import { basename, join } from 'node:path';
+import { existsSync, readFileSync, readdirSync, writeFileSync, rmSync } from 'node:fs';
+import { execFileSync } from 'node:child_process';
+import { tmpdir } from 'node:os';
+
+export function sanitizeName(s) {
+  return (
+    String(s).toLowerCase().replace(/[^a-z0-9-]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 60) || 'app'
+  );
+}
+
+function pending(res) {
+  return res.status === 202 && res.data && res.data.status === 'pending_approval';
+}
+
+// --- source safety (JNG #95) --------------------------------------------------
+// Files that must never be uploaded in a build context, whatever the ignore files
+// say. `.env.example`/`.sample`/`.template` are shareable templates, not secrets.
+function isSecretPath(rel) {
+  const base = rel.replace(/^\.\//, '').split('/').pop();
+  if (base === '.env' || /^\.env\.(?!example$|sample$|template$)[^/]*$/i.test(base)) return true;
+  if (/\.(pem|key|p12|pfx|keystore|jks)$/i.test(base)) return true;
+  if (/^id_(rsa|dsa|ecdsa|ed25519)$/.test(base)) return true;
+  return false;
+}
+
+// Exclude patterns: always skip .git/node_modules, then honor .gitignore and
+// .neoappignore (comments, blanks and negations are skipped — a conservative packer).
+function collectExcludes(dir) {
+  const excludes = new Set(['.git', 'node_modules']);
+  for (const f of ['.gitignore', '.neoappignore']) {
+    const p = join(dir, f);
+    if (!existsSync(p)) continue;
+    for (let line of readFileSync(p, 'utf8').split(/\r?\n/)) {
+      line = line.trim();
+      if (!line || line.startsWith('#') || line.startsWith('!')) continue;
+      excludes.add(line.replace(/^\/+/, '').replace(/\/+$/, ''));
+    }
+  }
+  return excludes;
+}
+
+// A relative path is excluded if a pattern matches its basename, the whole path, any
+// path segment (a directory like node_modules), or a simple `*.ext` glob — a small,
+// gitignore-ish matcher good enough for the ignore files we support.
+function matchesExclude(rel, excludes) {
+  const parts = rel.split('/');
+  const base = parts[parts.length - 1];
+  for (const pat of excludes) {
+    if (pat === base || pat === rel || parts.includes(pat)) return true;
+    if (pat.startsWith('*.') && base.endsWith(pat.slice(1))) return true;
+  }
+  return false;
+}
+
+// Build the explicit list of files to pack (relative to dir), honoring the ignore
+// files and never including secrets. We tar this exact list (tar -T) instead of
+// relying on `tar --exclude`, whose glob semantics differ across tar implementations
+// (GNU vs bsd vs busybox) and silently let ignored/secret files through (JNG #95).
+function collectIncludedFiles(dir) {
+  const excludes = collectExcludes(dir);
+  const out = [];
+  const walk = (d, rel) => {
+    let entries;
+    try { entries = readdirSync(d, { withFileTypes: true }); } catch { return; }
+    for (const e of entries) {
+      const r = rel ? `${rel}/${e.name}` : e.name;
+      if (matchesExclude(r, excludes) || isSecretPath(r)) continue;
+      if (e.isDirectory()) walk(join(d, e.name), r);
+      else out.push(r);
+    }
+  };
+  walk(dir, '');
+  return out;
+}
+
+// Secret files found under dir (for the heads-up log and the .zip check).
+function findSecretFiles(dir) {
+  const out = [];
+  const walk = (d, rel) => {
+    let entries;
+    try { entries = readdirSync(d, { withFileTypes: true }); } catch { return; }
+    for (const e of entries) {
+      if (e.name === '.git' || e.name === 'node_modules') continue;
+      const r = rel ? `${rel}/${e.name}` : e.name;
+      if (e.isDirectory()) walk(join(d, e.name), r);
+      else if (isSecretPath(r)) out.push(r);
+    }
+  };
+  walk(dir, '');
+  return out;
+}
+
+// Read a .zip's entry names from its central directory (no unzip binary needed) so we
+// can audit a prebuilt archive for secret files before uploading it (JNG #95).
+function zipEntryNames(buf) {
+  const names = [];
+  let eocd = -1;
+  for (let i = buf.length - 22; i >= Math.max(0, buf.length - 22 - 0xffff); i--) {
+    if (buf.readUInt32LE(i) === 0x06054b50) { eocd = i; break; }
+  }
+  if (eocd < 0) return null; // not a parseable zip — caller decides how strict to be
+  let off = buf.readUInt32LE(eocd + 16);
+  const count = buf.readUInt16LE(eocd + 10);
+  for (let i = 0; i < count && off + 46 <= buf.length; i++) {
+    if (buf.readUInt32LE(off) !== 0x02014b50) break;
+    const nameLen = buf.readUInt16LE(off + 28);
+    const extraLen = buf.readUInt16LE(off + 30);
+    const commentLen = buf.readUInt16LE(off + 32);
+    names.push(buf.toString('utf8', off + 46, off + 46 + nameLen));
+    off += 46 + nameLen + extraLen + commentLen;
+  }
+  return names;
+}
+
+// deploySource ships a resolved source to a project. `src` is one of:
+//   { mode:'image', image }           { mode:'git', repo, branch? }
+//   { mode:'dir', dir }               { mode:'zip', zipFile }
+// With `dryRun`, it performs NO create/update/upload/deploy — only the GETs needed to
+// build a plan — and returns { dryRun:true, plan } (JNG #93).
+// Returns { pending, approvalId } or { appId, url, result }. `log(msg)` is optional.
+export async function deploySource(api, { projectId, src, name, port, build, environment, dryRun = false, timeout = 300, log = () => {} }) {
+  const defaultName =
+    src.mode === 'image' ? src.image.split('/').pop().split(':')[0]
+    : src.mode === 'git' ? basename(src.repo, '.git')
+    : src.mode === 'zip' ? basename(src.zipFile, '.zip')
+    : basename(src.dir);
+  const svc = sanitizeName(name || defaultName);
+  const targetEnv = environment || 'production';
+
+  let buildType = 'railpack';
+  if (src.mode === 'image') buildType = 'image';
+  else if (build) buildType = build;
+  else if (src.mode === 'dir' && existsSync(join(src.dir, 'Dockerfile'))) buildType = 'dockerfile';
+
+  // Select an existing service by name AND environment — a Staging deploy must never
+  // reuse/mutate a Production service of the same name, or vice versa (JNG #94). The
+  // result is order-independent (filter, not first-match).
+  const existing = (await api.get(`/api/v1/projects/${projectId}/apps`)).data?.applications || [];
+  const sameName = existing.filter((a) => a.name === svc);
+  let app = sameName.find((a) => (a.environment || 'production') === targetEnv) || null;
+  if (!app && sameName.length) {
+    const envs = [...new Set(sameName.map((a) => a.environment || 'production'))].sort().join(', ');
+    throw new Error(
+      `a service named "${svc}" already exists in ${envs}, not in ${targetEnv} — ` +
+      `choose a different --name or target that environment`,
+    );
+  }
+
+  // Source-safety preflight — BEFORE any mutation (and in dry-run too, it's read-only)
+  // so an unsafe source aborts before a service is even created (JNG #95). Secrets are
+  // named, never their contents.
+  let dirSecrets = [];
+  if (src.mode === 'dir') {
+    dirSecrets = findSecretFiles(src.dir);
+    if (dirSecrets.length) log(`excluding secret file(s) from the build context: ${dirSecrets.join(', ')}`);
+  } else if (src.mode === 'zip') {
+    const names = zipEntryNames(readFileSync(src.zipFile));
+    const zipSecrets = (names || []).filter(isSecretPath);
+    if (zipSecrets.length) {
+      throw new Error(
+        `refusing to upload ${basename(src.zipFile)}: it contains secret file(s) ${zipSecrets.join(', ')} — ` +
+        `remove them from the archive before deploying`,
+      );
+    }
+  }
+
+  const plan = [];
+  if (!app) {
+    plan.push(`create web service "${svc}" (${buildType}) in ${targetEnv}`);
+    if (!dryRun) {
+      const res = await api.post(`/api/v1/projects/${projectId}/apps`, {
+        name: svc,
+        environment: targetEnv,
+        serviceType: 'web',
+        buildType,
+        image: src.image || undefined,
+        repoUrl: src.repo || undefined,
+        branch: src.branch || undefined,
+        port: port ? Number(port) : undefined,
+        tls: true,
+      });
+      if (pending(res)) return { pending: true, approvalId: res.data.approvalId };
+      app = res.data?.application || res.data;
+      log(`created service ${svc}`);
+    }
+  } else {
+    // Existing service: apply requested source changes (image/repo/branch/build) BEFORE
+    // deploying, so a redeploy never silently ships the old source config (JNG #96).
+    const patch = {};
+    if (src.mode === 'image' && src.image && app.image !== src.image) patch.image = src.image;
+    if (src.mode === 'git') {
+      if (src.repo && app.repoUrl !== src.repo) patch.repoUrl = src.repo;
+      if (src.branch && app.branch !== src.branch) patch.branch = src.branch;
+    }
+    if (buildType && app.buildType && app.buildType !== buildType) patch.buildType = buildType;
+    if (Object.keys(patch).length) {
+      plan.push(`update "${svc}": ${Object.keys(patch).join(', ')}`);
+      if (!dryRun) { await api.put(`/api/v1/apps/${app.id}`, patch); log(`updated source config (${Object.keys(patch).join(', ')})`); }
+    } else {
+      log(`service ${svc} exists — redeploying`);
+    }
+  }
+
+  if (src.mode === 'dir' || src.mode === 'zip') plan.push(`upload build context (${src.mode})`);
+  plan.push(`deploy "${svc}"`);
+
+  if (dryRun) {
+    for (const p of plan) log(`[dry-run] would ${p}`);
+    return { dryRun: true, plan, service: svc, environment: targetEnv };
+  }
+
+  if (src.mode === 'dir' || src.mode === 'zip') {
+    let archive = src.zipFile;
+    let packed = false;
+    try {
+      let buf, ctype;
+      if (src.mode === 'zip') {
+        buf = readFileSync(src.zipFile);
+        ctype = 'application/zip';
+      } else {
+        archive = join(tmpdir(), `neo-deploy-${app.id}-${Date.now()}.tgz`);
+        packed = true;
+        log('packing the directory…');
+        // Pack exactly the allowed files (ignore-respecting, secret-free) via a list,
+        // so no ignored/secret file can slip through a tar --exclude quirk (JNG #95).
+        const files = collectIncludedFiles(src.dir);
+        if (!files.length) throw new Error('nothing to deploy — the folder is empty after applying ignore rules');
+        const listFile = join(tmpdir(), `neo-files-${app.id}-${Date.now()}.txt`);
+        writeFileSync(listFile, files.join('\n') + '\n');
+        try {
+          execFileSync('tar', ['czf', archive, '-C', src.dir, '-T', listFile], { stdio: 'ignore' });
+        } finally {
+          rmSync(listFile, { force: true });
+        }
+        buf = readFileSync(archive);
+        ctype = 'application/gzip';
+      }
+      log(`uploading build context (${(buf.length / 1024 / 1024).toFixed(1)} MiB)…`);
+      await api.postRaw(`/api/v1/apps/${app.id}/source`, buf, ctype);
+    } finally {
+      if (packed) rmSync(archive, { force: true });
+    }
+  }
+
+  const dep = await api.post(`/api/v1/apps/${app.id}/deploy`);
+  if (pending(dep)) return { pending: true, approvalId: dep.data.approvalId };
+  const deployId = dep.data?.id;
+  log(`deployment ${deployId} started`);
+
+  const result = await pollDeployment(api, deployId, timeout, log);
+  const view = (await api.get(`/api/v1/apps/${app.id}`)).data?.application || {};
+  const url = view.domain ? `https://${view.domain}` : '';
+  return { appId: app.id, url, result };
+}
+
+async function pollDeployment(api, id, timeoutSec, log) {
+  if (!id) return 'unknown';
+  const deadline = Date.now() + timeoutSec * 1000;
+  let last = '';
+  while (Date.now() < deadline) {
+    const d = (await api.get(`/api/v1/deployments/${id}`)).data || {};
+    if (d.status && d.status !== last) {
+      log(`  ${d.status}`);
+      last = d.status;
+    }
+    if (d.status === 'success' || d.status === 'failed') return d.status;
+    await new Promise((r) => setTimeout(r, 4000));
+  }
+  return 'timeout';
+}

package/src/index.js

@@ -27,7 +27,7 @@ ${c.bold('Commands')}
   config install-mcp       Register the neo-app MCP server with detected agents
   login                    Authenticate with a NEO App API key (kap_...)
   link <project-id>        Link this repo to a project (writes .neo-app.json)
-  deploy                   Deploy a web service: --image <ref> or --repo <git-url>
+  deploy [path|.zip|git-url]   Deploy a directory (default: cwd), a .zip, a Git repo, or --image <ref>
   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)
   status | whoami          Show connected account, org, environment, linked project
@@ -85,12 +85,16 @@ export async function main(argv = process.argv.slice(2)) {
   const { values: opts, positionals } = parsed;
   if (opts.dev) opts.staging = true;
 
-  if (opts.version && positionals.length === 0) return void console.log(version());
-  if (opts.help || positionals.length === 0) return void console.log(HELP);
-
   const cmd = positionals[0];
   const sub = positionals[1];
 
+  if (opts.version && positionals.length === 0) return void console.log(version());
+  // 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']);
+  if (positionals.length === 0 || (opts.help && KNOWN_COMMANDS.has(cmd))) return void console.log(HELP);
+
   try {
     // `agent setup` and `setup agent` both work (parity with InstaCloud's `setup agent`).
     if ((cmd === 'agent' && sub === 'setup') || (cmd === 'setup' && sub === 'agent')) return void (await (await import('./commands/setup.js')).setup(opts));
@@ -98,7 +102,7 @@ export async function main(argv = process.argv.slice(2)) {
     if ((cmd === 'agent' && sub === 'uninstall') || (cmd === 'uninstall')) return void (await (await import('./commands/uninstall.js')).uninstall(opts));
     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(opts));
+    if (cmd === 'deploy') return void (await (await import('./commands/deploy.js')).deploy(sub, 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

@@ -2,6 +2,10 @@
 // map). Read-only vs mutating is annotated; mutating tools surface the server's
 // 202 pending_approval result verbatim instead of treating it as success/failure.
 
+import { resolve } from 'node:path';
+import { statSync } from 'node:fs';
+import { deploySource } from '../deploySource.js';
+
 const str = (description) => ({ type: 'string', description });
 const int = (description) => ({ type: 'integer', description });
 
@@ -175,6 +179,81 @@ export const TOOLS = [
       return (await api.get(`/api/v1/orgs/${orgId}/approvals`)).data;
     },
   },
+  {
+    name: 'neo_get_credit',
+    description: "Check the organization's prepaid credit balance and status (JNG #72).",
+    mutating: false,
+    schema: { type: 'object', properties: { orgId: str('Organization id (optional)') } },
+    async call(api, args) {
+      const orgId = await api.resolveOrgId(args.orgId);
+      return (await api.get(`/api/v1/orgs/${orgId}/credit`)).data;
+    },
+  },
+  {
+    name: 'neo_list_templates',
+    description: 'List deployable templates (e.g. wordpress, n8n, redis).',
+    mutating: false,
+    schema: { type: 'object', properties: {} },
+    async call(api) {
+      return (await api.get('/api/v1/templates')).data;
+    },
+  },
+  {
+    name: 'neo_deploy_template',
+    description: 'Deploy a template (e.g. wordpress, n8n) into a project. May return pending_approval.',
+    mutating: true,
+    schema: {
+      type: 'object',
+      properties: { projectId: str('Project id'), name: str('Template name'), domain: str('Custom domain (some templates need it)') },
+      required: ['projectId', 'name'],
+    },
+    async call(api, args) {
+      const body = args.domain ? { domain: args.domain } : {};
+      const { status, data } = await api.post(`/api/v1/projects/${args.projectId}/templates/${args.name}`, body);
+      return result(status, data);
+    },
+  },
+  {
+    name: 'neo_deploy_folder',
+    description:
+      'Deploy a local folder or .zip as a web service in a project (built server-side). The path is on the machine running this MCP server. Pick the environment with `environment` (JNG #72).',
+    mutating: true,
+    schema: {
+      type: 'object',
+      properties: {
+        projectId: str('Project id'),
+        path: str('Local folder or .zip path'),
+        name: str('Service name (optional)'),
+        port: int('Container port (optional)'),
+        environment: str('production or staging (optional, default production)'),
+        dryRun: { type: 'boolean', description: 'Preview the plan without creating/uploading/deploying anything (JNG #93)' },
+      },
+      required: ['projectId', 'path'],
+    },
+    async call(api, args) {
+      const p = resolve(args.path);
+      let src;
+      try {
+        const st = statSync(p);
+        if (st.isDirectory()) src = { mode: 'dir', dir: p };
+        else if (/\.zip$/i.test(p) && st.isFile()) src = { mode: 'zip', zipFile: p };
+        else throw new Error('not a folder or .zip');
+      } catch (e) {
+        throw new Error(`invalid path '${args.path}': ${e.message}`);
+      }
+      const r = await deploySource(api, {
+        projectId: args.projectId,
+        src,
+        name: args.name,
+        port: args.port,
+        environment: args.environment || 'production',
+        dryRun: !!args.dryRun,
+      });
+      if (r.dryRun) return { status: 'dry_run', plan: r.plan, service: r.service, environment: r.environment };
+      if (r.pending) return { status: 'pending_approval', approvalId: r.approvalId };
+      return { status: r.result, url: r.url || undefined, appId: r.appId };
+    },
+  },
   {
     name: 'neo_get_approval',
     description: 'Get one approval request by id (filtered from the org approval list).',