@nanobpm/urban 0.1.0

package/README.md

@@ -0,0 +1,62 @@
+# `@nanobpm/urban`
+
+The `urban` command-line tool: scaffold, validate, generate and run an Urban app
+from your terminal — on **Node or Deno**.
+
+## Install
+
+```bash
+npm i -g @nanobpm/urban      # install the `urban` command
+# or run without installing:
+npx @nanobpm/urban new my-app
+```
+
+Requires Node ≥ 22.6 or Deno. On Node < 23.6 the `urban` command re-executes with
+`--experimental-strip-types` so its TypeScript source runs directly.
+
+Under Deno you can run it without installing:
+
+```bash
+deno run -A npm:@nanobpm/urban run
+```
+
+## Commands
+
+| Command | What it does |
+|---|---|
+| `urban new <name>` | scaffold a new app in a new directory |
+| `urban check` | validate the app's `nano.app.json` manifest |
+| `urban gen` | generate the `nano-generated/` artifacts (migrations, worker I/O, models) |
+| `urban gen --check` | fail if the generated artifacts are out of date (a CI drift gate) |
+| `urban run` | generate, then run the app — starts its workers and serves its surfaces |
+| `urban dev` | run the app (hot-reload is not yet implemented) |
+| `urban deploy` | deploy the app's models to the engine, then exit |
+
+## Options
+
+| Flag | Purpose | Default |
+|---|---|---|
+| `--root <dir>` | app directory | `.` |
+| `--manifest <file>` | manifest filename | `nano.app.json` |
+| `--port <n>` | HTTP port for surfaces and triggers (integer 0–65535) | `$PORT` or `8090` |
+| `-h`, `--help` | show help | |
+| `-v`, `--version` | print the version | |
+
+The engine address comes from `$CAMUNDA_REST_ADDRESS` (default
+`http://localhost:8080/v2`). Set `$CAMUNDA_TRANSPORT` to a non-`rest` value to use
+the `@nanobpm/nano-sdk` transport when it is installed.
+
+## A typical session
+
+```bash
+urban new invoices && cd invoices
+urban gen        # generate nano-generated/
+urban check      # validate the manifest
+urban run        # start workers and serve surfaces
+```
+
+## Related packages
+
+- [`create-urban-app`](../create-urban-app) — the scaffolder behind `urban new`.
+- [`@nanobpm/urban-toolkit`](../urban-toolkit) — the generation behind `urban gen`.
+- [`@nanobpm/urban-runtime`](../urban-runtime) — the runtime behind `urban run`.

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@nanobpm/urban",
+  "version": "0.1.0",
+  "description": "The Urban CLI: scaffold, check, run, dev, and deploy Urban apps (nano.app.json) on Node or Deno. Thin command surface over @nanobpm/urban-runtime (ADR 0052).",
+  "license": "Apache-2.0",
+  "type": "module",
+  "keywords": [
+    "nanobpm",
+    "urban",
+    "urban-cli",
+    "cli",
+    "nano-app",
+    "rad"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/jwulf/nano-ide.git",
+    "directory": "packages/urban-cli"
+  },
+  "engines": {
+    "node": ">=22.6"
+  },
+  "bin": {
+    "urban": "./src/bin.mjs"
+  },
+  "main": "./src/cli.ts",
+  "types": "./src/cli.ts",
+  "exports": {
+    ".": "./src/cli.ts"
+  },
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "scripts": {
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "test": "node --test --experimental-strip-types \"src/**/*.test.ts\""
+  },
+  "dependencies": {
+    "@nanobpm/urban-runtime": "^0.1.0",
+    "@nanobpm/urban-toolkit": "^0.1.0",
+    "create-urban-app": "^0.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.20.1",
+    "typescript": "^5.9.3"
+  }
+}

package/src/bin.mjs

@@ -0,0 +1,23 @@
+#!/usr/bin/env node
+// Bootstrap for the `urban` CLI. The CLI is shipped as TypeScript source (one source of
+// truth, no build step). Node strips types natively, but versions < 23.6 need the
+// `--experimental-strip-types` flag, so we re-exec node with it when required.
+
+import { spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+
+const cli = join(dirname(fileURLToPath(import.meta.url)), "cli.ts");
+const [maj, min] = process.versions.node.split(".").map(Number);
+const needsFlag = maj < 23 || (maj === 23 && min < 6);
+
+const args = needsFlag
+  ? ["--disable-warning=ExperimentalWarning", "--experimental-strip-types", cli, ...process.argv.slice(2)]
+  : [cli, ...process.argv.slice(2)];
+
+const r = spawnSync(process.execPath, args, { stdio: "inherit" });
+if (r.error) {
+  console.error(String(r.error.message ?? r.error));
+  process.exit(1);
+}
+process.exit(r.status ?? 1);

package/src/cli.ts

@@ -0,0 +1,215 @@
+// The `urban` CLI — a thin command surface over @nanobpm/urban-runtime.
+//
+//   urban new <name>     scaffold a new app (delegates to create-urban-app)
+//   urban check          load + validate the manifest, report issues
+//   urban run            materialize + serve the app (deploy, data, workers, surfaces, triggers)
+//   urban dev            like run (hot-reload is not yet implemented; documented below)
+//   urban deploy         deploy models only, then exit
+//
+// Global flags: --root <dir> (default "."), --manifest <file> (default nano.app.json),
+//               --port <n>, -h/--help, -v/--version.
+
+import {
+  collectManifestIssues,
+  loadManifest,
+  runFromEnv,
+  selectHost,
+} from "@nanobpm/urban-runtime";
+import { scaffold, slugify } from "create-urban-app";
+import { createNodeGenIO, runGen } from "@nanobpm/urban-toolkit";
+import { pathToFileURL } from "node:url";
+
+const VERSION = "0.1.0";
+
+interface Flags {
+  root: string;
+  manifest: string;
+  port?: number;
+  check: boolean;
+  help: boolean;
+  version: boolean;
+  _: string[];
+}
+
+function parse(argv: string[]): Flags {
+  const f: Flags = { root: ".", manifest: "nano.app.json", check: false, help: false, version: false, _: [] };
+  const need = (i: number, flag: string): string => {
+    const v = argv[i];
+    if (v === undefined || v.startsWith("-")) throw new Error(`flag ${flag} requires a value`);
+    return v;
+  };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "-h" || a === "--help") f.help = true;
+    else if (a === "-v" || a === "--version") f.version = true;
+    else if (a === "--check") f.check = true;
+    else if (a === "--root") f.root = need(++i, a);
+    else if (a === "--manifest") f.manifest = need(++i, a);
+    else if (a === "--port") {
+      const raw = need(++i, a);
+      const n = Number(raw);
+      if (!Number.isInteger(n) || n < 0 || n > 65535) {
+        throw new Error(`flag --port requires an integer in 0..65535 (got "${raw}")`);
+      }
+      f.port = n;
+    } else if (a.startsWith("-")) throw new Error(`unknown flag: ${a}`);
+    else f._.push(a);
+  }
+  return f;
+}
+
+const USAGE = `urban — build and run Urban apps (nano.app.json)
+
+Usage:
+  urban new <name> [--root <path>]    scaffold a new Urban app
+  urban check                       validate the manifest
+  urban gen [--check]               derive artifacts (migrations, worker-io, models)
+  urban run                         materialize + serve the app
+  urban dev                         run (hot-reload not yet implemented)
+  urban deploy                      deploy models only, then exit
+
+Global flags:
+  --root <dir>        app root (default ".")
+  --manifest <file>   manifest filename (default "nano.app.json")
+  --port <n>          HTTP port for surfaces/triggers (default $PORT or 8090)
+  -h, --help          show this help
+  -v, --version       print version
+
+Engine address: $CAMUNDA_REST_ADDRESS (default http://localhost:8080/v2).
+`;
+
+async function cmdCheck(f: Flags): Promise<number> {
+  // The host is anchored at f.root, so manifest paths are already root-relative —
+  // pass the bare manifest filename (prefixing root again would double it).
+  const host = selectHost({ cwd: f.root });
+  const manifest = await loadManifest(host, f.manifest);
+  const issues = collectManifestIssues(manifest);
+  if (issues.length === 0) {
+    console.log(`✔ ${manifest.name ?? manifest.id} — manifest is valid`);
+    return 0;
+  }
+  console.error(`✖ ${issues.length} issue(s) in ${f.manifest}:`);
+  for (const it of issues) console.error(`  • ${it.path}: ${it.message}`);
+  return 1;
+}
+
+async function cmdGen(f: Flags): Promise<number> {
+  const io = createNodeGenIO();
+  const res = await runGen({ root: f.root, io, manifestFile: f.manifest, check: f.check });
+  if (f.check) {
+    if (res.drift.length === 0) {
+      console.log(`✔ generated artifacts are up to date (${res.artifacts.length} checked)`);
+      return 0;
+    }
+    console.error(`✖ ${res.drift.length} generated artifact(s) are out of date — run \`urban gen\`:`);
+    for (const p of res.drift) console.error(`  • ${p}`);
+    return 1;
+  }
+  console.log(`✔ generated ${res.artifacts.length} artifact(s):`);
+  for (const a of res.artifacts) console.log(`  • ${a.path}`);
+  return 0;
+}
+
+async function cmdRun(f: Flags, mount?: Record<string, boolean>): Promise<number> {
+  const app = await runFromEnv({
+    root: f.root,
+    manifestPath: f.manifest,
+    port: f.port,
+    mount,
+  });
+  const info = app.inspect();
+  console.log(`▲ ${info.name} — surfaces on :${info.httpPort ?? "n/a"} (Ctrl-C to stop)`);
+  return -1; // keep the process alive; signal handlers stop it
+}
+
+async function cmdDeploy(f: Flags): Promise<number> {
+  const app = await runFromEnv({
+    root: f.root,
+    manifestPath: f.manifest,
+    mount: { deploy: true, data: false, workers: false, surfaces: false, triggers: false, security: false },
+    handleSignals: false,
+  });
+  console.log(`✔ deployed models for ${app.manifest.name ?? app.manifest.id}`);
+  await app.stop();
+  return 0;
+}
+
+async function cmdNew(f: Flags): Promise<number> {
+  const name = f._[1];
+  if (!name) {
+    console.error("usage: urban new <name> [--root <path>]");
+    return 1;
+  }
+  const dir = f.root !== "." ? f.root : `./${slugify(name)}`;
+  const res = await scaffold({ name, dir });
+  console.log(`✔ scaffolded "${res.id}" in ${res.dir} (${res.files.length} files)`);
+  console.log(`  cd ${res.dir} && (npm install && npm start) || deno task start`);
+  return 0;
+}
+
+export async function main(argv: string[]): Promise<number> {
+  let f: Flags;
+  try {
+    f = parse(argv);
+  } catch (err) {
+    console.error(String((err as Error).message));
+    return 1;
+  }
+  if (f.version) {
+    console.log(VERSION);
+    return 0;
+  }
+  const cmd = f._[0];
+  if (f.help || !cmd) {
+    console.log(USAGE);
+    return cmd ? 0 : f.help ? 0 : 1;
+  }
+  switch (cmd) {
+    case "new":
+    case "scaffold":
+      return cmdNew(f);
+    case "check":
+      return cmdCheck(f);
+    case "gen":
+      return cmdGen(f);
+    case "run":
+      return cmdRun(f);
+    case "dev":
+      console.log("urban dev: hot-reload is not yet implemented; running once.");
+      return cmdRun(f);
+    case "deploy":
+      return cmdDeploy(f);
+    default:
+      console.error(`unknown command: ${cmd}\n`);
+      console.log(USAGE);
+      return 1;
+  }
+}
+
+const g = globalThis as {
+  process?: { argv: string[]; exit(code: number): void };
+  Deno?: { args?: string[]; exit?: (code: number) => void };
+};
+const meta = import.meta as unknown as { main?: boolean; url: string };
+const argv1 = g.process?.argv?.[1];
+const nodeMain = argv1 ? meta.url === pathToFileURL(argv1).href : false;
+if (meta.main === true || nodeMain) {
+  // Node passes args via process.argv (slice off exec+script); Deno (run directly)
+  // exposes them on Deno.args. Prefer whichever actually carries args.
+  const fromNode = g.process?.argv?.slice(2);
+  const fromDeno = g.Deno?.args;
+  const argv = (fromNode && fromNode.length ? fromNode : fromDeno) ?? fromNode ?? [];
+  const exit = (code: number) => {
+    if (g.process?.exit) g.process.exit(code);
+    else if (g.Deno?.exit) g.Deno.exit(code);
+  };
+  main(argv).then(
+    (code) => {
+      if (code >= 0) exit(code);
+    },
+    (err) => {
+      console.error(String((err as Error)?.message ?? err));
+      exit(1);
+    },
+  );
+}