@nanobpm/nano-workforce 0.26.0

package/scripts/check-agent-prompts.ts

@@ -0,0 +1,143 @@
+// check-agent-prompts — deploy-safety gate for the model-authored `{{template}}` agent prompts.
+//
+// Since #31 (v0.11.0) each agent's prompt is authored in the BPMN as a deploy-time template
+// header, e.g. `<zeebe:header key="io.nanobpm.agentTask.task.prompt" value="{{review-round}}" />`.
+// `@nanobpm/urban` substitutes `{{token}}` with `prompts/<token>.md` (nano.app.json
+// `models.templates`) at deploy time; the harness (`c8ctl nano work`) does NO substitution and
+// relays whatever header ships. So a token that resolves to a missing/blank template — or a blank
+// agent-prompt header — runs the agent effectively prompt-less. For `senior:pr-review` that makes
+// it improvise as a "reviewer" and escalate with no question (Magikcraft/nano-bpm #597/#599).
+//
+// urban's deploy only *warns* on an unresolved placeholder and ships the resource with the raw
+// token in place — and this project does not tolerate warnings. This guard runs urban's OWN
+// substitution (`applyTemplates`, the single source of truth for token scanning/escaping) exactly
+// as deploy does and turns any surviving placeholder into a hard failure, plus flags a blank
+// template or a blank agent-prompt header (which substitute to an empty prompt without being
+// "unresolved"). Importing from `@nanobpm/urban/runtime` also asserts the installed urban is new
+// enough to substitute at all (the capability was added in the 0.22 / nano-ide #106 release).
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { basename, join } from "node:path";
+import { applyTemplates } from "@nanobpm/urban/runtime";
+
+// The reserved header carrying an agent's base prompt. A blank value here means the agent gets no
+// instructions — the exact failure mode we guard against.
+const AGENT_PROMPT_HEADER = "io.nanobpm.agentTask.task.prompt";
+
+interface AppManifest {
+  models?: { processes?: string[]; decisions?: string[]; forms?: string[]; templates?: string[] };
+}
+
+// Mirror urban deploy's `contentTypeFor`: only the escapable model types are substituted.
+function contentTypeFor(path: string): string {
+  if (path.endsWith(".bpmn") || path.endsWith(".dmn")) return "text/xml";
+  if (path.endsWith(".form")) return "application/json";
+  return "application/octet-stream";
+}
+
+// Minimal `dir/*.ext` glob — the only shape nano.app.json uses. Unknown patterns throw loudly
+// rather than silently matching nothing.
+function expandGlob(root: string, pattern: string): string[] {
+  const m = /^(.*)\/\*\.([A-Za-z0-9]+)$/.exec(pattern);
+  if (!m) throw new Error(`check-agent-prompts: unsupported glob pattern "${pattern}"`);
+  const [, dir, ext] = m;
+  const abs = join(root, dir);
+  if (!existsSync(abs)) return [];
+  return readdirSync(abs)
+    .filter((f) => f.endsWith(`.${ext}`))
+    .sort()
+    .map((f) => join(dir, f));
+}
+
+// The `name -> content` template map urban substitutes from (array source: name = file stem).
+function templateMap(root: string, patterns: string[]): Record<string, string> {
+  const map: Record<string, string> = {};
+  for (const pattern of patterns) {
+    for (const rel of expandGlob(root, pattern)) {
+      const stem = basename(rel).replace(/\.[^.]+$/, "");
+      map[stem] = readFileSync(join(root, rel), "utf8");
+    }
+  }
+  return map;
+}
+
+// Blank reserved agent-prompt headers in a BPMN source — the one blank case urban's `unresolved`
+// signal can't see (an empty value carries no `{{token}}` to be unresolved).
+function hasBlankAgentPromptHeader(bpmn: string): boolean {
+  const re = /<zeebe:header\s+key="([^"]*)"\s+value="([^"]*)"\s*\/?>/g;
+  let m: RegExpExecArray | null;
+  while ((m = re.exec(bpmn)) !== null) {
+    if (m[1] === AGENT_PROMPT_HEADER && m[2].trim() === "") return true;
+  }
+  return false;
+}
+
+export interface CheckResult {
+  ok: boolean;
+  errors: string[];
+  /** template names successfully substituted into a model — surfaced for the CLI summary line. */
+  resolved: string[];
+}
+
+export function checkAgentPrompts(root: string): CheckResult {
+  const errors: string[] = [];
+  const resolved = new Set<string>();
+
+  const manifestPath = join(root, "nano.app.json");
+  if (!existsSync(manifestPath)) {
+    return { ok: false, errors: [`nano.app.json not found under ${root}`], resolved: [] };
+  }
+  const manifest = JSON.parse(readFileSync(manifestPath, "utf8")) as AppManifest;
+  const models = manifest.models ?? {};
+  const templates = templateMap(root, models.templates ?? []);
+
+  // A declared-but-blank template substitutes to an empty prompt without being "unresolved" —
+  // catch it up front (urban would silently produce a blank prompt).
+  for (const [name, body] of Object.entries(templates)) {
+    if (body.trim() === "") errors.push(`template {{${name}}} is empty — it would substitute to a blank prompt`);
+  }
+
+  const modelFiles = [
+    ...(models.processes ?? []),
+    ...(models.decisions ?? []),
+    ...(models.forms ?? []),
+  ].flatMap((p) => expandGlob(root, p));
+  if (modelFiles.length === 0) {
+    errors.push(`no model files matched ${JSON.stringify(models.processes ?? [])}`);
+  }
+
+  for (const rel of modelFiles) {
+    const contentType = contentTypeFor(rel);
+    if (contentType === "application/octet-stream") continue; // urban does not substitute these
+    const content = readFileSync(join(root, rel), "utf8");
+
+    // Run urban's canonical substitution — the same call deploy makes — and fail on any token it
+    // leaves unresolved (deploy only warns, which we don't tolerate).
+    const applied = applyTemplates(content, contentType, templates);
+    for (const name of applied.unresolved) {
+      errors.push(
+        `${rel}: unresolved template {{${name}}} — no such template is declared in models.templates`,
+      );
+    }
+    for (const name of Object.keys(templates)) {
+      if (content.includes(`{{${name}}}`)) resolved.add(name);
+    }
+
+    if (hasBlankAgentPromptHeader(content)) {
+      errors.push(`${rel}: a reserved "${AGENT_PROMPT_HEADER}" header is empty (agent would run prompt-less)`);
+    }
+  }
+
+  return { ok: errors.length === 0, errors, resolved: [...resolved].sort() };
+}
+
+// CLI: check the repo rooted at cwd. Exit non-zero (fail CI) on any problem.
+if (import.meta.main) {
+  const root = process.cwd();
+  const { ok, errors, resolved } = checkAgentPrompts(root);
+  if (!ok) {
+    console.error(`✖ agent prompt check failed (${errors.length} problem(s)):`);
+    for (const e of errors) console.error(`  - ${e}`);
+    process.exit(1);
+  }
+  console.log(`✔ agent prompt templates resolve (${resolved.length}: ${resolved.join(", ")})`);
+}

package/scripts/layout-bpmn.ts

@@ -0,0 +1,99 @@
+// npm run layout <file.bpmn ...> (or `deno task layout <file.bpmn ...>`) — (re)generate the
+// bpmndi:BPMNDiagram for one or more BPMN models using the urban toolkit's `layoutBpmn`
+// (bpmn-auto-layout). The semantic model stays authoritative: author the process elements
+// (tasks, gateways, flows, zeebe extensions) and run this to derive an auto-laid-out diagram,
+// rather than hand-editing DI. Works on DI-less or already-laid-out input; only the diagram is
+// (re)written — the semantic model round-trips 1:1. Re-run whenever the flow changes.
+//
+// `--check` (npm run layout:check) regenerates the DI in memory and fails with a non-zero exit
+// if any committed diagram is stale, WITHOUT rewriting files — the CI freshness gate that stops
+// a BPMN flow change from merging with an un-regenerated diagram.
+import { layoutBpmn } from "@nanobpm/urban";
+
+// Host-agnostic file I/O: Deno inside a compiled binary, else node:fs under Node — mirrors
+// app/plan.ts's readAsset seam so this runs the same under `npm run` and `deno task`.
+const g = globalThis as {
+  Deno?: {
+    args: string[];
+    readDir(p: string): AsyncIterable<{ name: string; isFile: boolean }>;
+    readTextFile(p: string): Promise<string>;
+    writeTextFile(p: string, s: string): Promise<void>;
+  };
+};
+
+async function readText(path: string): Promise<string> {
+  return g.Deno?.readTextFile
+    ? await g.Deno.readTextFile(path)
+    : await (await import("node:fs/promises")).readFile(path, "utf8");
+}
+async function writeText(path: string, text: string): Promise<void> {
+  if (g.Deno?.writeTextFile) return await g.Deno.writeTextFile(path, text);
+  await (await import("node:fs/promises")).writeFile(path, text, "utf8");
+}
+async function defaultProcessFiles(): Promise<string[]> {
+  const dir = "resources/processes";
+  if (g.Deno?.readDir) {
+    const files: string[] = [];
+    for await (const e of g.Deno.readDir(dir)) if (e.isFile && e.name.endsWith(".bpmn")) files.push(`${dir}/${e.name}`);
+    return files.sort();
+  }
+  const fs = await import("node:fs/promises");
+  return (await fs.readdir(dir, { withFileTypes: true }))
+    .filter((e) => e.isFile() && e.name.endsWith(".bpmn"))
+    .map((e) => `${dir}/${e.name}`)
+    .sort();
+}
+
+// Count the shapes/edges the layout produced, so the run reports what it drew (matches the
+// "N shapes + M edges" accounting used when merge-loop's DI was first generated, #18).
+const countDi = (xml: string) => ({
+  shapes: (xml.match(/<bpmndi:BPMNShape\b/g) ?? []).length,
+  edges: (xml.match(/<bpmndi:BPMNEdge\b/g) ?? []).length,
+});
+
+function exit(code: number): never {
+  if (g.Deno) return (globalThis as { Deno?: { exit(c: number): never } }).Deno!.exit(code);
+  process.exit(code);
+}
+
+async function main() {
+  const argv = g.Deno?.args ?? process.argv.slice(2);
+  // `--check` mode: regenerate the DI in memory and fail (non-zero) if it differs from what's
+  // committed, WITHOUT rewriting any file. This is the CI freshness gate — it catches a BPMN
+  // flow change whose author forgot to re-run `npm run layout`, so a stale diagram can't merge.
+  const check = argv.includes("--check");
+  const files = (() => {
+    const named = argv.filter((a) => a !== "--check");
+    return named.length ? named : undefined;
+  })() ?? await defaultProcessFiles();
+  if (files.length === 0) {
+    console.error("usage: layout-bpmn [--check] [file.bpmn ...] (default: resources/processes/*.bpmn)");
+    exit(2);
+  }
+  const stale: string[] = [];
+  for (const file of files) {
+    const current = await readText(file);
+    const laid = await layoutBpmn(current);
+    const { shapes, edges } = countDi(laid);
+    if (check) {
+      if (laid !== current) {
+        stale.push(file);
+        console.error(`[layout:check] ${file}: DI is STALE — re-run \`npm run layout ${file}\` and commit`);
+      } else {
+        console.log(`[layout:check] ${file}: DI fresh (${shapes} shapes + ${edges} edges)`);
+      }
+      continue;
+    }
+    await writeText(file, laid);
+    console.log(`[layout] ${file}: ${shapes} shapes + ${edges} edges`);
+  }
+  if (check && stale.length) {
+    console.error(
+      `\n${stale.length} BPMN model(s) have stale diagram interchange. The semantic model is ` +
+        `authoritative; regenerate the DI with \`npm run layout\` and commit the result.`,
+    );
+    exit(1);
+  }
+}
+
+await main();

package/scripts/purge-db.ts

@@ -0,0 +1,57 @@
+// npm run purge (or `deno task purge`) — wipe the app's sqlite datasource so `npm start`
+// comes up against a fresh schema (the runtime re-applies db/migrations on boot). Deletes the
+// sqlite file and its WAL/SHM sidecars for the `app` source declared in nano.app.json.
+import { rmSync } from "node:fs";
+
+const url = process.env.NANO_APP_DB_URL ?? "file:./app.db";
+
+/** Percent-decode a path, turning `decodeURIComponent`'s opaque `URIError`
+ *  (malformed escape, or a literal `%` in a filename) into a clear message. */
+function decodePath(p: string, url: string): string {
+  try {
+    return decodeURIComponent(p);
+  } catch (e) {
+    throw new Error(`purge could not decode the path in datasource URL: ${url}`, {
+      cause: e,
+    });
+  }
+}
+
+/** Resolve a `file:` datasource URL to a filesystem path. Handles both the opaque
+ *  form (`file:./app.db`, `file:/abs/app.db`) and the authority form
+ *  (`file:///abs/app.db`), and refuses non-`file:` schemes. */
+function fileUrlToPath(u: string): string {
+  if (!u.startsWith("file:")) {
+    throw new Error(`purge only supports file: datasource URLs, got: ${u}`);
+  }
+  // Authority form (`file://host/path` or `file:///path`) parses cleanly as a URL.
+  if (u.startsWith("file://")) {
+    const parsed = new URL(u);
+    if (parsed.hostname && parsed.hostname !== "localhost") {
+      throw new Error(
+        `purge does not support remote file hosts, got host "${parsed.hostname}" in: ${u}`,
+      );
+    }
+    const p = decodePath(parsed.pathname, u);
+    // Windows drive fixup: `/C:/x` -> `C:/x`.
+    return /^\/[A-Za-z]:/.test(p) ? p.slice(1) : p;
+  }
+  // Opaque form: everything after the scheme is the (possibly relative) path.
+  // Decode percent-escapes too (mirroring the authority branch above), so an
+  // encoded path like `file:./my%20app.db` resolves to `./my app.db`.
+  const p = decodePath(u.slice("file:".length), u);
+  // Windows single-slash absolute form (`file:/C:/x`): strip the leading slash.
+  return /^\/[A-Za-z]:/.test(p) ? p.slice(1) : p;
+}
+
+const path = fileUrlToPath(url);
+
+for (const suffix of ["", "-wal", "-shm"]) {
+  try {
+    rmSync(path + suffix);
+    console.log(`removed ${path}${suffix}`);
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code !== "ENOENT") throw err;
+  }
+}
+console.log("app db purged");

package/scripts/upgrade-from-pack.ts

@@ -0,0 +1,334 @@
+// npm run upgrade (or `deno task upgrade`) — refresh THIS app's source from a newer
+// published pack of @nanobpm/nano-workforce, WITHOUT touching your data.
+//
+// Why this exists: a Console project stamped from the example pack is a one-time
+// COPY (a snapshot/fork) — there is no built-in "update from template". This
+// script performs the Option-A "keep the database" upgrade: it fetches a newer
+// pack (via `npm pack`), then overlays its files onto the current directory while
+// PRESERVING the sqlite datasource (`app.db` + WAL/SHM sidecars), generated SDK
+// (`nano-generated/`), and local VCS/deps (`.git/`, `node_modules/`). Because the
+// app's migrations in `db/migrations` are additive and re-applied on boot, your
+// existing data survives and any new migrations top it up on the next `npm start`.
+//
+// SAFETY: dry-run by default. It prints the plan (files it would create/overwrite,
+// and anything preserved or newly-orphaned) and writes NOTHING until you pass
+// `--apply`. It never deletes files. If you modified the app, review the plan —
+// an overlay overwrites your edits to any file the new version also ships.
+//
+// Usage:
+//   npm run upgrade                         # dry-run against @latest
+//   npm run upgrade -- --apply              # perform the @latest overlay
+//   npm run upgrade -- --version 0.7.0 --apply
+//   npm run upgrade -- --from ./pkg --apply # overlay a local dir/tarball (offline)
+//
+// Flags:
+//   --apply             write changes (default: dry-run preview)
+//   --version <v>       npm dist-tag or version to fetch (default: "latest")
+//   --package <name>    package to fetch (default: "@nanobpm/nano-workforce")
+//   --from <path>       use a local extracted dir OR a .tgz tarball as the source
+//                       (skips `npm pack`; --version/--package are ignored)
+//   --force             overlay even if the cwd doesn't look like this app
+//   -h, --help          show this help
+import {
+  cpSync,
+  existsSync,
+  mkdirSync,
+  mkdtempSync,
+  readdirSync,
+  readFileSync,
+  rmSync,
+  statSync,
+} from "node:fs";
+import { execFileSync } from "node:child_process";
+import { tmpdir } from "node:os";
+import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+
+interface Args {
+  apply: boolean;
+  version: string;
+  pkg: string;
+  from: string | null;
+  force: boolean;
+}
+
+function parseArgs(argv: string[]): Args {
+  const a: Args = {
+    apply: false,
+    version: "latest",
+    pkg: "@nanobpm/nano-workforce",
+    from: null,
+    force: false,
+  };
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    switch (arg) {
+      case "--apply":
+        a.apply = true;
+        break;
+      case "--force":
+        a.force = true;
+        break;
+      case "--version":
+        a.version = req(argv, ++i, arg);
+        break;
+      case "--package":
+        a.pkg = req(argv, ++i, arg);
+        break;
+      case "--from":
+        a.from = req(argv, ++i, arg);
+        break;
+      case "-h":
+      case "--help":
+        printHelp();
+        process.exit(0);
+        break;
+      default:
+        throw new Error(`unknown argument: ${arg} (try --help)`);
+    }
+  }
+  return a;
+}
+
+function req(argv: string[], i: number, flag: string): string {
+  const v = argv[i];
+  if (v === undefined || v.startsWith("--")) {
+    throw new Error(`${flag} requires a value`);
+  }
+  return v;
+}
+
+function printHelp(): void {
+  console.log(
+    readFileSync(new URL(import.meta.url), "utf8")
+      .split("\n")
+      .filter((l) => l.startsWith("// "))
+      .map((l) => l.slice(3))
+      .join("\n"),
+  );
+}
+
+/** Resolve a `file:` datasource URL to a filesystem path (mirrors purge-db.ts so
+ *  the DB we preserve is exactly the one the runtime opens). Non-`file:` schemes
+ *  (e.g. libsql/turso) have no local file to protect, so they return null. */
+function datasourcePath(url: string): string | null {
+  if (!url.startsWith("file:")) return null;
+  const decode = (p: string): string => {
+    try {
+      return decodeURIComponent(p);
+    } catch (e) {
+      throw new Error(`could not decode datasource path in URL: ${url}`, { cause: e });
+    }
+  };
+  if (url.startsWith("file://")) {
+    const parsed = new URL(url);
+    if (parsed.hostname && parsed.hostname !== "localhost") {
+      throw new Error(`remote file host unsupported in datasource URL: ${url}`);
+    }
+    const p = decode(parsed.pathname);
+    return /^\/[A-Za-z]:/.test(p) ? p.slice(1) : p;
+  }
+  const p = decode(url.slice("file:".length));
+  return /^\/[A-Za-z]:/.test(p) ? p.slice(1) : p;
+}
+
+/** Recursively list files (not directories) under `root`, as paths relative to it.
+ *  `skipTop` names top-level directories to skip entirely (e.g. node_modules, .git)
+ *  so we never walk large machine-local trees. */
+function listFiles(root: string, skipTop: Set<string> = new Set()): string[] {
+  const out: string[] = [];
+  const walk = (dir: string): void => {
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+      if (dir === root && entry.isDirectory() && skipTop.has(entry.name)) continue;
+      const abs = join(dir, entry.name);
+      if (entry.isDirectory()) walk(abs);
+      else if (entry.isFile()) out.push(relative(root, abs));
+    }
+  };
+  walk(root);
+  return out;
+}
+
+/** True when `rel` is inside one of the preserved top-level directories, or is a
+ *  preserved DB file/sidecar. */
+function isPreserved(rel: string, preservedDirs: Set<string>, preservedFiles: Set<string>): boolean {
+  if (preservedFiles.has(rel)) return true;
+  const top = rel.split(sep)[0];
+  return preservedDirs.has(top);
+}
+
+/** Fetch the package with `npm pack` into a temp dir and extract it, returning the
+ *  path to the extracted `package/` directory. */
+function fetchPack(pkg: string, version: string, tmp: string): string {
+  const spec = `${pkg}@${version}`;
+  console.log(`• fetching ${spec} via npm pack …`);
+  const out = execFileSync("npm", ["pack", spec, "--pack-destination", tmp, "--silent"], {
+    encoding: "utf8",
+  }).trim();
+  // `npm pack --silent` prints the tarball filename (last line, to be safe).
+  const tgz = out.split("\n").filter(Boolean).pop();
+  if (!tgz) throw new Error(`npm pack produced no tarball for ${spec}`);
+  return extractTarball(join(tmp, tgz), tmp);
+}
+
+/** Extract a .tgz into `tmp` and return the `package/` dir npm tarballs wrap. */
+function extractTarball(tgz: string, tmp: string): string {
+  if (!existsSync(tgz)) throw new Error(`tarball not found: ${tgz}`);
+  // Validate the archive listing BEFORE extracting: an untrusted `.tgz` may carry
+  // absolute paths or `../` segments that would let `tar` write outside `tmp`.
+  // Fail fast on any unsafe entry instead of trusting `tar` to sandbox itself.
+  const listing = runTar(["-tzf", tgz], tgz);
+  for (const raw of listing.split("\n")) {
+    const entry = raw.trim();
+    if (!entry) continue;
+    if (isAbsolute(entry) || /^[A-Za-z]:[\\/]/.test(entry)) {
+      throw new Error(`refusing to extract tarball with absolute path entry: ${entry} (${tgz})`);
+    }
+    const parts = entry.split(/[\\/]/);
+    if (parts.includes("..")) {
+      throw new Error(`refusing to extract tarball with '..' path segment: ${entry} (${tgz})`);
+    }
+  }
+  runTar(["-xzf", tgz, "-C", tmp], tgz);
+  const pkgDir = join(tmp, "package");
+  if (!existsSync(pkgDir)) throw new Error(`extracted tarball has no package/ dir: ${tgz}`);
+  return pkgDir;
+}
+
+/** Run `tar` with a clearer error when it is missing or fails. */
+function runTar(tarArgs: string[], tgz: string): string {
+  try {
+    return execFileSync("tar", tarArgs, { encoding: "utf8" });
+  } catch (e) {
+    if ((e as NodeJS.ErrnoException).code === "ENOENT") {
+      throw new Error(`'tar' not found on PATH — install it to extract ${tgz}`, { cause: e });
+    }
+    throw new Error(`tar failed on ${tgz}: ${(e as Error).message}`, { cause: e });
+  }
+}
+
+/** Resolve the source dir from --from (a dir or a .tgz) or from npm. */
+function resolveSource(args: Args, tmp: string): string {
+  if (args.from) {
+    const p = resolve(args.from);
+    if (!existsSync(p)) throw new Error(`--from path does not exist: ${p}`);
+    if (statSync(p).isDirectory()) {
+      // Accept either the app dir itself or an npm-style `package/` wrapper.
+      const wrapped = join(p, "package");
+      return existsSync(join(wrapped, "nano.app.json")) ? wrapped : p;
+    }
+    return extractTarball(p, tmp);
+  }
+  return fetchPack(args.pkg, args.version, tmp);
+}
+
+function packageVersion(dir: string): string {
+  try {
+    return JSON.parse(readFileSync(join(dir, "package.json"), "utf8")).version ?? "?";
+  } catch {
+    return "?";
+  }
+}
+
+function main(): void {
+  const args = parseArgs(process.argv.slice(2));
+  const cwd = process.cwd();
+
+  if (!existsSync(join(cwd, "nano.app.json")) && !args.force) {
+    throw new Error(
+      "current directory has no nano.app.json — run this from the app/project root " +
+        "(or pass --force if you're sure)",
+    );
+  }
+
+  // Preserve the live datasource (+ WAL/SHM sidecars) and machine-local dirs.
+  const dbUrl = process.env.NANO_APP_DB_URL ?? "file:./app.db";
+  const dbPath = datasourcePath(dbUrl);
+  const preservedFiles = new Set<string>();
+  if (dbPath) {
+    for (const suffix of ["", "-wal", "-shm"]) {
+      const rel = relative(cwd, resolve(cwd, dbPath + suffix));
+      // Only protect DB files that live inside the project: a relative path with
+      // no leading `..` and not absolute. On Windows `path.relative()` returns an
+      // absolute path (e.g. `C:\…`) when cwd and the DB are on different drives —
+      // that is out-of-tree, so an overlay never touches it.
+      if (!rel.startsWith("..") && !isAbsolute(rel)) preservedFiles.add(rel);
+    }
+  }
+  const preservedDirs = new Set(["nano-generated", ".nano", ".git", "node_modules"]);
+
+  const tmp = mkdtempSync(join(tmpdir(), "upr-upgrade-"));
+  try {
+    const src = resolveSource(args, tmp);
+    const srcVersion = packageVersion(src);
+    const curVersion = packageVersion(cwd);
+    // Describe the source accurately: with --from we overlay a local path and never
+    // consult npm, so naming args.pkg (the npm default) would be misleading.
+    const srcLabel = args.from ? `${args.from} (local)` : args.pkg;
+    console.log(`• source ${srcLabel} @ ${srcVersion}  →  current @ ${curVersion}\n`);
+
+    const srcFiles = listFiles(src);
+    const created: string[] = [];
+    const overwritten: string[] = [];
+    const skipped: string[] = [];
+    for (const rel of srcFiles) {
+      if (isPreserved(rel, preservedDirs, preservedFiles)) {
+        skipped.push(rel);
+        continue;
+      }
+      (existsSync(join(cwd, rel)) ? overwritten : created).push(rel);
+    }
+
+    // Files present locally but not shipped by the new version (informational —
+    // never deleted; may be your data, or something the new version dropped).
+    const srcSet = new Set(srcFiles);
+    const orphans = listFiles(cwd, preservedDirs)
+      .filter((rel) => !isPreserved(rel, preservedDirs, preservedFiles))
+      .filter((rel) => !srcSet.has(rel));
+
+    report("create", created);
+    report("overwrite", overwritten);
+    if (skipped.length) console.log(`  preserved (not overlaid): ${skipped.length} file(s)`);
+    if (preservedFiles.size) {
+      console.log(`  keeping database: ${[...preservedFiles].join(", ")}`);
+    }
+    report("orphan (kept, review)", orphans);
+
+    if (!args.apply) {
+      console.log(
+        `\nDRY RUN — nothing written. Re-run with --apply to overlay ` +
+          `${created.length + overwritten.length} file(s).`,
+      );
+      return;
+    }
+
+    for (const rel of [...created, ...overwritten]) {
+      const dest = join(cwd, rel);
+      mkdirSync(dirname(dest), { recursive: true });
+      cpSync(join(src, rel), dest, { recursive: false });
+    }
+    // Guard against a script that overwrote itself mid-run on some platforms: the
+    // copy is byte-for-byte, so this is just a friendly confirmation.
+    console.log(
+      `\n✔ overlaid ${created.length + overwritten.length} file(s) → now @ ${srcVersion}.\n` +
+        `Next: reinstall deps if package.json changed, then restart the app —\n` +
+        `the runtime re-applies db/migrations on boot, preserving your data.`,
+    );
+  } finally {
+    rmSync(tmp, { recursive: true, force: true });
+  }
+}
+
+function report(label: string, files: string[]): void {
+  if (!files.length) return;
+  console.log(`  ${label}: ${files.length} file(s)`);
+  const show = files.slice(0, 20);
+  for (const f of show) console.log(`    ${f}`);
+  if (files.length > show.length) console.log(`    … and ${files.length - show.length} more`);
+}
+
+try {
+  main();
+} catch (err) {
+  console.error(`upgrade failed: ${(err as Error).message}`);
+  process.exit(1);
+}

package/tsconfig.json

@@ -0,0 +1,51 @@
+{
+  "compilerOptions": {
+    "target": "esnext",
+    "module": "nodenext",
+    "moduleResolution": "nodenext",
+    "allowImportingTsExtensions": true,
+    "noEmit": true,
+    "strict": true,
+    "skipLibCheck": true,
+    "lib": [
+      "esnext",
+      "dom"
+    ],
+    "paths": {
+      "@nanobpm/worker": [
+        "./nano-generated/workers.ts"
+      ],
+      "@nanobpm/messages": [
+        "./nano-generated/messages.ts"
+      ],
+      "@nanobpm/meta": [
+        "./nano-generated/meta.ts"
+      ],
+      "@nanobpm/llm": [
+        "./nano-generated/llm-worker.ts"
+      ],
+      "@nanobpm/data": [
+        "./nano-generated/data-sdk.ts"
+      ],
+      "@nanobpm/domain": [
+        "./nano-generated/domain.ts"
+      ],
+      "@lib/*": [
+        "./lib/*"
+      ]
+    }
+  },
+  "include": [
+    "main.ts",
+    "workers/**/*.ts",
+    "lib/**/*.ts",
+    "src/**/*.ts",
+    "scripts/**/*.ts",
+    "actions/**/*.ts"
+  ],
+  "exclude": [
+    "node_modules",
+    "dist",
+    "**/*.test.ts"
+  ]
+}