@biznetgio/neo-app 0.4.6 → 0.4.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@biznetgio/neo-app",
-  "version": "0.4.6",
+  "version": "0.4.8",
   "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

@@ -68,6 +68,9 @@ export async function deploy(source, opts = {}) {
   const environment = cfg.env === 'staging' ? 'staging' : 'production';
   log(`${c.bold('Deploying')} ${c.dim(`[${src.mode}] → ${cfg.env} · project ${projectId}`)}`);
 
+  const dryRun = !!opts['dry-run'];
+  if (dryRun) log(c.dim('dry-run — no changes will be made'));
+
   const r = await deploySource(api, {
     projectId,
     src,
@@ -75,10 +78,15 @@ export async function deploy(source, opts = {}) {
     port: opts.port,
     build: opts.build,
     environment,
+    dryRun,
     timeout: Number(opts.timeout) || 300,
     log: step,
   });
 
+  if (r.dryRun) {
+    ok(`dry-run complete — ${r.plan.length} step(s) planned, nothing written`);
+    return r;
+  }
   if (r.pending) {
     ok(`submitted — pending approval (${r.approvalId}). An owner/admin must approve.`);
     return;

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

@@ -3,7 +3,7 @@
 // .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 { existsSync, readFileSync, readdirSync, writeFileSync, rmSync } from 'node:fs';
 import { execFileSync } from 'node:child_process';
 import { tmpdir } from 'node:os';
 
@@ -17,44 +17,201 @@ 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, timeout = 300, log = () => {} }) {
+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 || [];
-  let app = existing.find((a) => a.name === svc);
+  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) {
-    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}`);
+    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 {
-    log(`service ${svc} exists — redeploying`);
-    if (src.mode === 'image' && app.image !== src.image) await api.put(`/api/v1/apps/${app.id}`, { image: src.image });
+    // 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') {
@@ -69,7 +226,17 @@ export async function deploySource(api, { projectId, src, name, port, build, env
         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' });
+        // 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';
       }

package/src/index.js

@@ -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));

package/src/mcp/tools.js

@@ -226,6 +226,7 @@ export const TOOLS = [
         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'],
     },
@@ -246,7 +247,9 @@ export const TOOLS = [
         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 };
     },