@biznetgio/neo-app 0.0.0-stage → 0.3.0

package/src/commands/setup.js

@@ -0,0 +1,100 @@
+// `neo-app agent setup` — the one-command onboarding. Detects agents, authenticates
+// (API key), installs the skill, registers the MCP server, optionally links a project,
+// runs health checks, and prints a verification prompt. Idempotent; safe to rerun.
+
+import { resolveConfig } from '../config.js';
+import { getCredential } from '../creds.js';
+import { NeoApi, ApiError } from '../api.js';
+import { detectAgents } from '../agents.js';
+import { installSkill, skillVersion } from '../skill.js';
+import { writeLink, readLink } from '../link.js';
+import { installMcp } from './install-mcp.js';
+import { login } from './login.js';
+import { log, ok, warn, fail, step, c } from '../util.js';
+
+const NODE_MAJOR = Number(process.versions.node.split('.')[0]);
+
+export async function setup(opts = {}) {
+  const cfg = resolveConfig(opts);
+  const dry = !!opts['dry-run'];
+
+  log(c.bold(`NEO App agent setup`) + c.dim(`  (${cfg.env} · ${cfg.baseUrl})`));
+
+  // 1. environment
+  if (NODE_MAJOR < 18) {
+    fail(`Node.js ${process.versions.node} detected; Node 18+ is required`);
+    process.exit(1);
+  }
+  const agents = detectAgents();
+  const present = agents.filter((a) => a.present);
+  step(`platform ${process.platform}/${process.arch}, node ${process.versions.node}`);
+  step(`agents detected: ${present.map((a) => a.name).join(', ') || 'none'}`);
+
+  if (dry) {
+    log(c.yellow('\n[dry-run] no changes will be written. Intended actions:'));
+    step('authenticate with your NEO App API key (stored 0600, not in agent config)');
+    step(`install skill ${skillVersion()} into user agent skill dirs`);
+    for (const a of present) step(`register neo-app MCP in ${a.name} (${a.configPath})`);
+    if (opts.project) step(`link this repo to project ${opts.project} (.neo-app.json)`);
+    step('run health checks + print verification prompt');
+    return;
+  }
+
+  // 2. authenticate — reuse a valid stored credential, else run login.
+  let api;
+  let account;
+  const cred = getCredential(cfg.baseUrl);
+  if (cred?.token && !opts.token) {
+    api = new NeoApi({ baseUrl: cfg.baseUrl, token: cred.token });
+    try {
+      const who = await api.whoami();
+      account = who.user?.email || who.user?.name || 'unknown';
+      ok(`already authenticated as ${account} (${cfg.env})`);
+    } catch {
+      warn('stored credential is invalid — re-authenticating');
+      ({ api, account } = await login(opts));
+    }
+  } else {
+    ({ api, account } = await login(opts));
+  }
+
+  // 3. skill
+  installSkill();
+  ok(`skill ${skillVersion()} installed`);
+
+  // 4. MCP registration
+  const mcpResults = await installMcp(opts);
+  if (!mcpResults.length) warn('no agent MCP configured (no supported agent detected)');
+
+  // 5. project link (optional)
+  let link = readLink();
+  const environment = cfg.env === 'staging' ? 'staging' : 'production';
+  if (opts.project) {
+    try {
+      const proj = (await api.get(`/api/v1/projects/${opts.project}`)).data;
+      const name = proj?.name || proj?.application?.name || opts.project;
+      link = { projectId: opts.project, environment, baseUrl: cfg.baseUrl, env: cfg.env, name };
+      writeLink(link);
+      ok(`project linked: ${name} / ${environment}  ${c.dim('(.neo-app.json)')}`);
+    } catch (e) {
+      const why = e instanceof ApiError && e.status === 404 ? 'not found or no access' : e.message;
+      fail(`could not link project ${opts.project}: ${why}`);
+    }
+  }
+
+  // 6. summary
+  log('');
+  log(c.bold('NEO App agent setup complete.'));
+  log('');
+  log(`CLI:        connected as ${account}`);
+  log(`Project:    ${link?.projectId ? `${link.name || link.projectId} / ${link.environment}` : c.dim('not linked')}`);
+  for (const a of agents) {
+    const r = mcpResults.find((m) => m.agent === a.id);
+    const stateLabel = r?.ok ? 'configured' : a.present ? c.red('failed') : c.dim('not detected');
+    log(`${a.name} MCP:`.padEnd(16) + stateLabel);
+  }
+  log(`Skill:      installed (${skillVersion()})`);
+  log('');
+  log('Restart your coding agent, then ask:');
+  log(c.dim('"Check my NEO App setup: run neo-app status and call neo_whoami."'));
+}

package/src/commands/status.js

@@ -0,0 +1,39 @@
+// `neo-app status` / `neo-app whoami` — show the connected account, org, environment,
+// and any linked project. Matches what the neo_whoami MCP tool returns.
+
+import { resolveConfig } from '../config.js';
+import { getCredential } from '../creds.js';
+import { NeoApi } from '../api.js';
+import { readLink } from '../link.js';
+import { log, ok, fail, c } from '../util.js';
+
+export async function status(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 });
+  let who;
+  try {
+    who = await api.whoami();
+  } catch (e) {
+    fail(`token invalid for ${cfg.baseUrl}: ${e.message}`);
+    process.exit(1);
+  }
+
+  const account = who.user?.email || who.user?.name || 'unknown';
+  const org = who.orgs?.[0];
+  const link = readLink();
+
+  log(`${c.bold('NEO App')}  ${c.dim(cfg.env + ' · ' + cfg.baseUrl)}`);
+  ok(`account   ${account}${who.user?.isAdmin ? c.dim(' (platform admin)') : ''}`);
+  if (org) ok(`org       ${org.name} ${c.dim('(' + org.role + ')')}`);
+  if (link?.projectId) {
+    ok(`project   ${link.projectId}${link.environment ? ' / ' + link.environment : ''}`);
+  } else {
+    log(`${c.dim('·')} no linked project (run 'neo-app agent setup --project <id>')`);
+  }
+  return { cfg, who, account, org, link };
+}

package/src/commands/uninstall.js

@@ -0,0 +1,34 @@
+// `neo-app agent uninstall` — remove only what NEO App installed: the MCP entry in
+// each agent's config, the skill, and (on confirm) stored credentials + repo link.
+
+import { detectAgents, unregisterMcp } from '../agents.js';
+import { removeSkill } from '../skill.js';
+import { removeStore } from '../creds.js';
+import { removeLink, LINK_FILE } from '../link.js';
+import { log, ok, step, confirm } from '../util.js';
+
+export async function uninstall(opts = {}) {
+  log('NEO App uninstall — removing only NEO App-owned files and config.');
+
+  for (const agent of detectAgents()) {
+    const { removed, bak } = unregisterMcp(agent);
+    if (removed) ok(`${agent.name} MCP removed${bak ? ` (backup: ${bak})` : ''}`);
+    else step(`${agent.name}: no neo-app MCP entry`);
+  }
+
+  const dirs = removeSkill();
+  if (dirs.length) ok(`skill removed (${dirs.length} location(s))`);
+  else step('no skill installed');
+
+  if (removeLink()) ok(`project link removed (${LINK_FILE})`);
+
+  const rmCreds = opts.yes || (await confirm('Also remove stored API credentials?'));
+  if (rmCreds) {
+    if (removeStore()) ok('stored credentials removed');
+    else step('no credentials file');
+  } else {
+    step('kept stored credentials');
+  }
+
+  log("Done. Restart your coding agent so it drops the neo-app MCP server.");
+}

package/src/config.js

@@ -0,0 +1,50 @@
+// Environment + endpoint resolution.
+//
+// Portals:
+//   staging    → https://portal.neoapp.biznetgio.dev
+//   production → https://portal.app.neoapp.id
+// NODE_ENV=development points at staging. Everything is overridable with NEO_APP_URL /
+// NEO_APP_ENV or a --staging / --prod / --url flag so the same CLI works against a
+// custom or local control-plane.
+
+const ENDPOINTS = {
+  staging: {
+    url: 'https://portal.neoapp.biznetgio.dev',
+    mcpUrl: 'https://portal.neoapp.biznetgio.dev/api/v1/mcp', // hosted HTTP MCP (Phase 2)
+  },
+  production: {
+    url: 'https://portal.app.neoapp.id',
+    mcpUrl: 'https://portal.app.neoapp.id/api/v1/mcp',
+  },
+};
+
+// resolveEnv decides staging vs production from (in order): explicit --staging/--prod,
+// --env/NEO_APP_ENV, then NODE_ENV=development => staging, else production.
+export function resolveEnv(opts = {}) {
+  if (opts.staging) return 'staging';
+  if (opts.prod) return 'production';
+  const flag = (opts.env || '').toLowerCase();
+  if (flag === 'staging' || flag === 'dev' || flag === 'development') return 'staging';
+  if (flag === 'production' || flag === 'prod') return 'production';
+  const envVar = (process.env.NEO_APP_ENV || '').toLowerCase();
+  if (envVar === 'staging' || envVar === 'dev') return 'staging';
+  if (envVar === 'production' || envVar === 'prod') return 'production';
+  if ((process.env.NODE_ENV || '').toLowerCase() === 'development') return 'staging';
+  return 'production';
+}
+
+// resolveConfig returns { env, baseUrl, mcpUrl }. An explicit URL (flag or
+// NEO_APP_URL) wins over the env-derived default but keeps the env label for
+// credential scoping and messaging.
+export function resolveConfig(opts = {}) {
+  const env = resolveEnv(opts);
+  const base = ENDPOINTS[env];
+  const override = (opts.url || process.env.NEO_APP_URL || '').trim().replace(/\/+$/, '');
+  return {
+    env,
+    baseUrl: override || base.url,
+    mcpUrl: base.mcpUrl,
+  };
+}
+
+export { ENDPOINTS };

package/src/creds.js

@@ -0,0 +1,94 @@
+// Credential storage for the NEO App CLI.
+//
+// API keys (kap_ personal tokens) are kept OUT of any agent/MCP config file. They
+// live in a user-only (0600) JSON store, keyed by control-plane base URL so staging
+// and production tokens never clash. NEO_APP_TOKEN (env) always overrides the store,
+// which is how headless/CI runs authenticate without writing anything to disk.
+//
+// ponytail: file-0600 store only. OS keychain (macOS `security`, Linux libsecret) is
+// the hardening upgrade — add a backend here if plaintext-at-rest becomes a concern.
+
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { mkdirSync, readFileSync, writeFileSync, chmodSync, existsSync, rmSync, statSync } from 'node:fs';
+
+function storeDir() {
+  const base = process.env.XDG_CONFIG_HOME || join(homedir(), '.config');
+  return join(base, 'neo-app');
+}
+
+function storePath() {
+  return join(storeDir(), 'credentials.json');
+}
+
+function readStore() {
+  try {
+    return JSON.parse(readFileSync(storePath(), 'utf8'));
+  } catch {
+    return {};
+  }
+}
+
+function writeStore(store) {
+  const dir = storeDir();
+  mkdirSync(dir, { recursive: true });
+  const path = storePath();
+  writeFileSync(path, JSON.stringify(store, null, 2), { mode: 0o600 });
+  try {
+    chmodSync(path, 0o600); // enforce even if the file pre-existed with looser perms
+  } catch {
+    /* best effort */
+  }
+}
+
+// getCredential returns { token, account, env, source } for a base URL, or null.
+// NEO_APP_TOKEN wins so CI can authenticate without a stored file.
+export function getCredential(baseUrl) {
+  if (process.env.NEO_APP_TOKEN) {
+    return { token: process.env.NEO_APP_TOKEN, account: null, env: null, source: 'env' };
+  }
+  const entry = readStore()[baseUrl];
+  if (entry && entry.token) return { ...entry, source: 'file' };
+  return null;
+}
+
+export function setCredential(baseUrl, { token, account, env }) {
+  const store = readStore();
+  store[baseUrl] = { token, account: account || null, env: env || null, savedAt: new Date().toISOString() };
+  writeStore(store);
+}
+
+export function deleteCredential(baseUrl) {
+  const store = readStore();
+  if (store[baseUrl]) {
+    delete store[baseUrl];
+    writeStore(store);
+    return true;
+  }
+  return false;
+}
+
+// storeInfo reports where creds live and whether the file is user-only (for doctor).
+export function storeInfo() {
+  const path = storePath();
+  const info = { path, exists: existsSync(path), secure: null };
+  if (info.exists) {
+    try {
+      const mode = statSync(path).mode & 0o777;
+      info.secure = mode === 0o600;
+      info.mode = mode.toString(8);
+    } catch {
+      /* ignore */
+    }
+  }
+  return info;
+}
+
+export function removeStore() {
+  try {
+    rmSync(storePath());
+    return true;
+  } catch {
+    return false;
+  }
+}

package/src/index.js

@@ -0,0 +1,105 @@
+// CLI entrypoint: parse args and dispatch. Keep this thin — logic lives in commands/.
+
+import { parseArgs } from 'node:util';
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+import { c, fail } from './util.js';
+
+function version() {
+  try {
+    const p = join(dirname(fileURLToPath(import.meta.url)), '..', 'package.json');
+    return JSON.parse(readFileSync(p, 'utf8')).version;
+  } catch {
+    return 'dev';
+  }
+}
+
+const HELP = `${c.bold('neo-app')} — NEO App CLI for coding agents
+
+${c.bold('Usage')}
+  npx -y @biznetgio/neo-app@latest <command> [options]
+
+${c.bold('Commands')}
+  agent setup              Install skill, register MCP, authenticate, link project
+  agent doctor             Diagnose CLI, auth, API, agent MCP wiring, skill, perms
+  agent uninstall          Remove NEO App MCP entries, skill, (optionally) credentials
+  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)
+  project list             List projects in your organization (find ids to link)
+  status | whoami          Show connected account, org, environment, linked project
+  mcp                      Run the local stdio MCP server (used by agents)
+
+${c.bold('Options')}
+  --project <id>           Link this repo to a project (agent setup)
+  --agent <codex|claude-code>   Target one agent (config install-mcp)
+  --staging | --prod       Target staging (portal.neoapp.biznetgio.dev) or production (portal.app.neoapp.id)
+  --url <url>              Override the control-plane URL (also NEO_APP_URL)
+  --token <kap_...>        API key (also NEO_APP_TOKEN; prompted if omitted)
+  --yes                    Non-interactive (headless/CI)
+  --dry-run               Print intended changes without writing
+  -v, --version           Print version
+  -h, --help              Show this help
+
+${c.bold('Environment')}
+  Production is the default. Set NODE_ENV=development (or pass --staging) for staging.
+  NEO_APP_URL / NEO_APP_TOKEN override the target and credential.`;
+
+const options = {
+  project: { type: 'string' },
+  agent: { type: 'string' },
+  org: { type: 'string' },
+  env: { type: 'string' },
+  url: { type: 'string' },
+  token: { type: 'string' },
+  staging: { type: 'boolean' },
+  dev: { type: 'boolean' },
+  prod: { type: 'boolean' },
+  yes: { type: 'boolean' },
+  'dry-run': { type: 'boolean' },
+  version: { type: 'boolean', short: 'v' },
+  help: { type: 'boolean', short: 'h' },
+};
+
+export async function main(argv = process.argv.slice(2)) {
+  let parsed;
+  try {
+    parsed = parseArgs({ args: argv, options, allowPositionals: true });
+  } catch (e) {
+    fail(e.message);
+    process.exit(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];
+
+  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));
+    if ((cmd === 'agent' && sub === 'doctor') || (cmd === 'doctor')) return void (await (await import('./commands/doctor.js')).doctor(opts));
+    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 === '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 === 'list' || sub === 'ls')) return void (await (await import('./commands/link.js')).listProjects(opts));
+    if (cmd === 'status' || cmd === 'whoami') return void (await (await import('./commands/status.js')).status(opts));
+    if (cmd === 'mcp') return void (await (await import('./mcp/server.js')).runMcpServer());
+    if (cmd === 'version') return void console.log(version());
+    if (cmd === 'help') return void console.log(HELP);
+
+    fail(`unknown command: ${[cmd, sub].filter(Boolean).join(' ')}`);
+    console.log(`Run ${c.bold('neo-app --help')} for usage.`);
+    process.exit(2);
+  } catch (e) {
+    fail(e.message || String(e));
+    if (process.env.NEO_APP_DEBUG) console.error(e);
+    process.exit(1);
+  }
+}

package/src/link.js

@@ -0,0 +1,34 @@
+// Repository <-> NEO App project link, stored as an untracked `.neo-app.json` at the
+// working directory root. Holds only non-secret routing (project id + environment).
+
+import { join } from 'node:path';
+import { readFileSync, writeFileSync, existsSync, rmSync } from 'node:fs';
+
+const LINK_FILE = '.neo-app.json';
+
+function linkPath() {
+  return join(process.cwd(), LINK_FILE);
+}
+
+export function readLink() {
+  try {
+    return JSON.parse(readFileSync(linkPath(), 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+export function writeLink(link) {
+  writeFileSync(linkPath(), JSON.stringify(link, null, 2) + '\n');
+  return linkPath();
+}
+
+export function removeLink() {
+  if (existsSync(linkPath())) {
+    rmSync(linkPath());
+    return true;
+  }
+  return false;
+}
+
+export { LINK_FILE };

package/src/mcp/server.js

@@ -0,0 +1,56 @@
+// NEO App local stdio MCP server (`neo-app mcp`). Reuses the authenticated CLI
+// credential for the configured control-plane — the token is NEVER passed in agent
+// config, it is read here from the credential store (or NEO_APP_TOKEN). All logging
+// goes to stderr; stdout is the JSON-RPC channel.
+
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { ListToolsRequestSchema, CallToolRequestSchema } from '@modelcontextprotocol/sdk/types.js';
+import { resolveConfig } from '../config.js';
+import { getCredential } from '../creds.js';
+import { NeoApi } from '../api.js';
+import { TOOLS } from './tools.js';
+
+export async function runMcpServer() {
+  const cfg = resolveConfig({});
+  const cred = getCredential(cfg.baseUrl);
+  const api = new NeoApi({ baseUrl: cfg.baseUrl, token: cred?.token });
+  if (!cred?.token) {
+    console.error(`[neo-app mcp] no credential for ${cfg.baseUrl} — run 'neo-app login' or set NEO_APP_TOKEN`);
+  }
+
+  const server = new Server({ name: 'neo-app', version: '0.3.0' }, { capabilities: { tools: {} } });
+
+  server.setRequestHandler(ListToolsRequestSchema, async () => ({
+    tools: TOOLS.map((t) => ({
+      name: t.name,
+      description: t.description,
+      inputSchema: t.schema,
+      annotations: { readOnlyHint: !t.mutating, destructiveHint: false },
+    })),
+  }));
+
+  server.setRequestHandler(CallToolRequestSchema, async (req) => {
+    const tool = TOOLS.find((t) => t.name === req.params.name);
+    if (!tool) {
+      return { content: [{ type: 'text', text: `unknown tool: ${req.params.name}` }], isError: true };
+    }
+    if (!api.token) {
+      return {
+        content: [{ type: 'text', text: 'Not authenticated. Run `neo-app login` or set NEO_APP_TOKEN.' }],
+        isError: true,
+      };
+    }
+    try {
+      const out = await tool.call(api, req.params.arguments || {});
+      const text = typeof out === 'string' ? out : JSON.stringify(out, null, 2);
+      return { content: [{ type: 'text', text }] };
+    } catch (e) {
+      const suffix = e.status ? ` (HTTP ${e.status})` : '';
+      return { content: [{ type: 'text', text: `Error: ${e.message}${suffix}` }], isError: true };
+    }
+  });
+
+  await server.connect(new StdioServerTransport());
+  console.error(`[neo-app mcp] ready: ${cfg.env} ${cfg.baseUrl}`);
+}