@biznetgio/neo-app 0.4.2 → 0.4.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@biznetgio/neo-app",
-  "version": "0.4.2",
+  "version": "0.4.6",
   "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,44 @@ 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}`)}`);
-
-  // 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,
+    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 });
-  }
-
-  // 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/deploySource.js

@@ -0,0 +1,108 @@
+// 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, 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';
+}
+
+// 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 }
+// Returns { pending, approvalId } or { appId, url, result }. `log(msg)` is optional.
+export async function deploySource(api, { projectId, src, name, port, build, environment, 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);
+
+  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';
+
+  const existing = (await api.get(`/api/v1/projects/${projectId}/apps`)).data?.applications || [];
+  let app = existing.find((a) => a.name === svc);
+
+  if (!app) {
+    const res = await api.post(`/api/v1/projects/${projectId}/apps`, {
+      name: svc,
+      environment: environment || 'production',
+      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 {
+    log(`service ${svc} exists — redeploying`);
+    if (src.mode === 'image' && app.image !== src.image) await api.put(`/api/v1/apps/${app.id}`, { image: src.image });
+  }
+
+  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…');
+        execFileSync('tar', ['czf', archive, '--exclude=./.git', '--exclude=./node_modules', '-C', src.dir, '.'], { stdio: 'ignore' });
+        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
@@ -98,7 +98,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,78 @@ 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)'),
+      },
+      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',
+      });
+      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).',