@nanobpm/urban 0.38.0 → 0.39.0

package/dist/cli.js

@@ -162,6 +162,12 @@ async function cmdGen(f) {
     console.log(`✔ generated ${res.artifacts.length} artifact(s):`);
     for (const a of res.artifacts)
         console.log(`  • ${a.path}`);
+    // Stale generated files removed from nano-generated/ (renamed/removed artifacts from a prior gen).
+    if (res.swept.length > 0) {
+        console.log(`✔ removed ${res.swept.length} stale generated file(s):`);
+        for (const p of res.swept)
+            console.log(`  - ${p}`);
+    }
     // Write-once handler stubs scaffolded as part of generation (workers from the model, operation
     // delegates from the OpenAPI spec). Existing, human-owned stubs are kept verbatim.
     const created = [

package/dist/toolkit/artifact.d.ts

@@ -15,6 +15,17 @@ export interface Deriver<I> {
 /** Where all derived output lands — the console's `nano-generated/` dir, so the toolkit is a
  * drop-in for the IDE's own codegen (ADR 0053). One drift domain, gitignored, never committed. */
 export declare const GENERATED_DIR = "nano-generated";
+/**
+ * Files that live in `GENERATED_DIR` but are NOT produced by `urban gen`. These are materialized by
+ * a different writer — the runtime SDK shims and the `urban data` / console-host dataops path, which
+ * derives the typed wrappers from the *live* DB (something `urban gen` can't do without a running
+ * datasource). `urban gen`'s stale-file sweep must own only what it emits, so it protects these by
+ * name: it never deletes them even though it didn't (re)write them this run. Basenames, relative to
+ * `GENERATED_DIR`. Keep in sync with the emitters' filename constants (DOMAIN_BINDINGS,
+ * WORKER_BINDINGS_TS, MESSAGE_BINDINGS_TS, DOMAIN_MODEL_JSON) + the `./data-sdk.ts`/`./worker-sdk.ts`
+ * shim imports the generated wrappers reference.
+ */
+export declare const RUNTIME_MATERIALIZED_ARTIFACTS: readonly string[];
 /** Stable ordering so artifact lists compare deterministically. */
 export declare function sortArtifacts(a: DerivedArtifact[]): DerivedArtifact[];
 /** True when `p` is an absolute path — POSIX root (`/`), a drive-letter root (`C:\` or `C:/`), or a

package/dist/toolkit/artifact.js

@@ -5,6 +5,24 @@
 /** Where all derived output lands — the console's `nano-generated/` dir, so the toolkit is a
  * drop-in for the IDE's own codegen (ADR 0053). One drift domain, gitignored, never committed. */
 export const GENERATED_DIR = "nano-generated";
+/**
+ * Files that live in `GENERATED_DIR` but are NOT produced by `urban gen`. These are materialized by
+ * a different writer — the runtime SDK shims and the `urban data` / console-host dataops path, which
+ * derives the typed wrappers from the *live* DB (something `urban gen` can't do without a running
+ * datasource). `urban gen`'s stale-file sweep must own only what it emits, so it protects these by
+ * name: it never deletes them even though it didn't (re)write them this run. Basenames, relative to
+ * `GENERATED_DIR`. Keep in sync with the emitters' filename constants (DOMAIN_BINDINGS,
+ * WORKER_BINDINGS_TS, MESSAGE_BINDINGS_TS, DOMAIN_MODEL_JSON) + the `./data-sdk.ts`/`./worker-sdk.ts`
+ * shim imports the generated wrappers reference.
+ */
+export const RUNTIME_MATERIALIZED_ARTIFACTS = [
+    "domain.ts",
+    "workers.ts",
+    "messages.ts",
+    "domain.json",
+    "data-sdk.ts",
+    "worker-sdk.ts",
+];
 /** Stable ordering so artifact lists compare deterministically. */
 export function sortArtifacts(a) {
     return [...a].sort((x, y) => (x.path < y.path ? -1 : x.path > y.path ? 1 : 0));

package/dist/toolkit/gen.d.ts

@@ -36,6 +36,8 @@ export interface GenResult {
     artifacts: DerivedArtifact[];
     /** Paths that differ from disk (only populated by `check`). */
     drift: string[];
+    /** App-relative paths of stale files removed from `nano-generated/` (only populated in write mode). */
+    swept: string[];
     /** True if any code-first workflow failed to import/derive. */
     incomplete: boolean;
     /** Per-file model-derivation errors (empty on success). */

package/dist/toolkit/gen.js

@@ -2,7 +2,7 @@
 // models, runs the pure derivers, and either writes the artifacts to disk (`urban gen`) or
 // compares them against what's on disk and reports drift (`urban gen --check`). The derivers stay
 // pure; all IO is confined here behind a tiny FS port so the same code runs on Node and Deno.
-import { isAbsolutePath, sortArtifacts } from "./artifact.js";
+import { GENERATED_DIR, isAbsolutePath, RUNTIME_MATERIALIZED_ARTIFACTS, sortArtifacts } from "./artifact.js";
 import { deriveMigrations } from "./derivers/migrations.js";
 import { deriveDomain } from "./derivers/domain.js";
 import { deriveWorkerBindings } from "./derivers/worker-io.js";
@@ -138,7 +138,29 @@ export async function runGen(opts) {
                 await io.remove(join(root, rel));
         }
     }
-    return { artifacts, drift, incomplete: derived.incomplete, modelErrors: derived.errors };
+    // Stale-artifact sweep of `nano-generated/` (clean break, nano-bpm#: gen owns its output dir).
+    // The dir is gitignored and fully codegen-owned, so any file this run did not (re)write is stale
+    // from a prior gen — a renamed or removed artifact (e.g. an old `data_sdk.ts`) whose orphan the
+    // app might still import. Remove it. The one exception is the runtime-materialized set: the SDK
+    // shims + the `urban data`/console dataops wrappers gen does NOT emit but the app needs at runtime
+    // (RUNTIME_MATERIALIZED_ARTIFACTS). Protect those by name. Write mode only; skipped when io.remove
+    // is absent (the sweep is best-effort, mirroring the `.bpmn` sweep above). NOT on `modelsOnly`
+    // (`urban derive`): that path derives only models, so `artifacts` carries no `nano-generated/*` and
+    // sweeping would wrongly wipe the type-contract outputs a prior `urban gen` wrote.
+    const swept = [];
+    if (!opts.check && !opts.modelsOnly && !derived.incomplete && io.remove) {
+        const keep = new Set(artifacts.map((a) => a.path).filter((p) => p.startsWith(`${GENERATED_DIR}/`)));
+        for (const name of RUNTIME_MATERIALIZED_ARTIFACTS)
+            keep.add(`${GENERATED_DIR}/${name}`);
+        for (const name of await io.listDir(join(root, GENERATED_DIR))) {
+            const rel = `${GENERATED_DIR}/${name}`;
+            if (keep.has(rel))
+                continue;
+            await io.remove(join(root, rel));
+            swept.push(rel);
+        }
+    }
+    return { artifacts, drift, swept: swept.sort(), incomplete: derived.incomplete, modelErrors: derived.errors };
 }
 export { dirOf, join as joinPath };
 /** Derive code-first models in-memory (no writes) — backs `urban derive --stdout`, the

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@nanobpm/urban",
-	"version": "0.38.0",
+	"version": "0.39.0",
 	"description": "Urban: build and run code-first apps on Nano — runtime, derivation toolkit, and CLI in one. Author durable processes with @nanobpm/workflow (defineFlow), a typed datasource, forms, triggers and surfaces from a nano.app.json manifest, on Node or Deno.",
 	"license": "Apache-2.0",
 	"type": "module",

package/src/cli.ts

@@ -171,6 +171,12 @@ async function cmdGen(f: Flags): Promise<number> {
   console.log(`✔ generated ${res.artifacts.length} artifact(s):`);
   for (const a of res.artifacts) console.log(`  • ${a.path}`);
 
+  // Stale generated files removed from nano-generated/ (renamed/removed artifacts from a prior gen).
+  if (res.swept.length > 0) {
+    console.log(`✔ removed ${res.swept.length} stale generated file(s):`);
+    for (const p of res.swept) console.log(`  - ${p}`);
+  }
+
   // Write-once handler stubs scaffolded as part of generation (workers from the model, operation
   // delegates from the OpenAPI spec). Existing, human-owned stubs are kept verbatim.
   const created = [

package/src/toolkit/artifact.ts

@@ -23,6 +23,25 @@ export interface Deriver<I> {
  * drop-in for the IDE's own codegen (ADR 0053). One drift domain, gitignored, never committed. */
 export const GENERATED_DIR = "nano-generated";
 
+/**
+ * Files that live in `GENERATED_DIR` but are NOT produced by `urban gen`. These are materialized by
+ * a different writer — the runtime SDK shims and the `urban data` / console-host dataops path, which
+ * derives the typed wrappers from the *live* DB (something `urban gen` can't do without a running
+ * datasource). `urban gen`'s stale-file sweep must own only what it emits, so it protects these by
+ * name: it never deletes them even though it didn't (re)write them this run. Basenames, relative to
+ * `GENERATED_DIR`. Keep in sync with the emitters' filename constants (DOMAIN_BINDINGS,
+ * WORKER_BINDINGS_TS, MESSAGE_BINDINGS_TS, DOMAIN_MODEL_JSON) + the `./data-sdk.ts`/`./worker-sdk.ts`
+ * shim imports the generated wrappers reference.
+ */
+export const RUNTIME_MATERIALIZED_ARTIFACTS: readonly string[] = [
+  "domain.ts",
+  "workers.ts",
+  "messages.ts",
+  "domain.json",
+  "data-sdk.ts",
+  "worker-sdk.ts",
+];
+
 /** Stable ordering so artifact lists compare deterministically. */
 export function sortArtifacts(a: DerivedArtifact[]): DerivedArtifact[] {
   return [...a].sort((x, y) => (x.path < y.path ? -1 : x.path > y.path ? 1 : 0));

package/src/toolkit/gen.test.ts

@@ -103,6 +103,59 @@ test("collectArtifacts touches no writes", async () => {
   assert.equal(Object.keys(io.files).length, before);
 });
 
+test("runGen sweeps stale files from nano-generated/ (write mode)", async () => {
+  const io = memIO(fixture());
+  // A stale artifact left by a prior gen (e.g. a renamed `data_sdk.ts` orphan) that this run does
+  // not re-emit. It must be removed so the app can't import a dead generated module.
+  io.files["/app/nano-generated/data_sdk.ts"] = "// stale, renamed away";
+  io.files["/app/nano-generated/old-worker-io.d.ts"] = "// stale";
+  const res = await runGen({ root: "/app", io });
+  assert.deepEqual(res.swept, [
+    "nano-generated/data_sdk.ts",
+    "nano-generated/old-worker-io.d.ts",
+  ]);
+  assert.ok(!("/app/nano-generated/data_sdk.ts" in io.files), "stale file removed");
+  assert.ok(!("/app/nano-generated/old-worker-io.d.ts" in io.files), "stale file removed");
+  // Current artifacts survive.
+  assert.ok("/app/nano-generated/worker-io.d.ts" in io.files, "fresh artifact kept");
+});
+
+test("runGen never sweeps runtime-materialized wrappers gen does not emit", async () => {
+  const io = memIO(fixture());
+  // The SDK shims + `urban data`/console dataops wrappers live in nano-generated/ but are not
+  // produced by `urban gen`; the app needs them at runtime, so the sweep must protect them.
+  for (const name of ["domain.ts", "workers.ts", "messages.ts", "domain.json", "data-sdk.ts", "worker-sdk.ts"]) {
+    io.files[`/app/nano-generated/${name}`] = `// runtime-materialized ${name}`;
+  }
+  const res = await runGen({ root: "/app", io });
+  assert.deepEqual(res.swept, [], "no runtime-materialized file swept");
+  for (const name of ["domain.ts", "workers.ts", "messages.ts", "domain.json", "data-sdk.ts", "worker-sdk.ts"]) {
+    assert.ok(`/app/nano-generated/${name}` in io.files, `${name} preserved`);
+  }
+});
+
+test("gen --check never sweeps (read-only)", async () => {
+  const io = memIO(fixture());
+  await runGen({ root: "/app", io });
+  io.files["/app/nano-generated/stale.ts"] = "// stale";
+  const res = await runGen({ root: "/app", io, check: true });
+  assert.deepEqual(res.swept, []);
+  assert.ok("/app/nano-generated/stale.ts" in io.files, "check mode leaves stale files untouched");
+});
+
+test("modelsOnly (urban derive) never sweeps nano-generated type-contract outputs", async () => {
+  const io = memIO(fixture());
+  // A prior `urban gen` wrote the type-contract outputs.
+  await runGen({ root: "/app", io });
+  assert.ok("/app/nano-generated/worker-io.d.ts" in io.files, "precondition: gen wrote outputs");
+  // `urban derive` (modelsOnly) derives only models — its artifacts carry no nano-generated/*, so
+  // the sweep must be a no-op here; otherwise it would wipe the type contracts above.
+  const res = await runGen({ root: "/app", io, modelsOnly: true });
+  assert.deepEqual(res.swept, []);
+  assert.ok("/app/nano-generated/worker-io.d.ts" in io.files, "derive preserved the type contracts");
+  assert.ok("/app/nano-generated/app.schema.sql" in io.files, "derive preserved the migrations");
+});
+
 // --- code-first model derivation (urban gen / urban derive) ---
 
 const GreetIn = envelope("GreetIn", { who: "string" });

package/src/toolkit/gen.ts

@@ -4,7 +4,7 @@
 // pure; all IO is confined here behind a tiny FS port so the same code runs on Node and Deno.
 
 import type { DerivedArtifact } from "./artifact.ts";
-import { isAbsolutePath, sortArtifacts } from "./artifact.ts";
+import { GENERATED_DIR, isAbsolutePath, RUNTIME_MATERIALIZED_ARTIFACTS, sortArtifacts } from "./artifact.ts";
 import { deriveMigrations, type ToolkitManifest } from "./derivers/migrations.ts";
 import { deriveDomain } from "./derivers/domain.ts";
 import { deriveWorkerBindings, type ModelSource } from "./derivers/worker-io.ts";
@@ -51,6 +51,8 @@ export interface GenResult {
   artifacts: DerivedArtifact[];
   /** Paths that differ from disk (only populated by `check`). */
   drift: string[];
+  /** App-relative paths of stale files removed from `nano-generated/` (only populated in write mode). */
+  swept: string[];
   /** True if any code-first workflow failed to import/derive. */
   incomplete: boolean;
   /** Per-file model-derivation errors (empty on success). */
@@ -199,7 +201,30 @@ export async function runGen(opts: GenOptions & { check?: boolean }): Promise<Ge
     }
   }
 
-  return { artifacts, drift, incomplete: derived.incomplete, modelErrors: derived.errors };
+  // Stale-artifact sweep of `nano-generated/` (clean break, nano-bpm#: gen owns its output dir).
+  // The dir is gitignored and fully codegen-owned, so any file this run did not (re)write is stale
+  // from a prior gen — a renamed or removed artifact (e.g. an old `data_sdk.ts`) whose orphan the
+  // app might still import. Remove it. The one exception is the runtime-materialized set: the SDK
+  // shims + the `urban data`/console dataops wrappers gen does NOT emit but the app needs at runtime
+  // (RUNTIME_MATERIALIZED_ARTIFACTS). Protect those by name. Write mode only; skipped when io.remove
+  // is absent (the sweep is best-effort, mirroring the `.bpmn` sweep above). NOT on `modelsOnly`
+  // (`urban derive`): that path derives only models, so `artifacts` carries no `nano-generated/*` and
+  // sweeping would wrongly wipe the type-contract outputs a prior `urban gen` wrote.
+  const swept: string[] = [];
+  if (!opts.check && !opts.modelsOnly && !derived.incomplete && io.remove) {
+    const keep = new Set(
+      artifacts.map((a) => a.path).filter((p) => p.startsWith(`${GENERATED_DIR}/`)),
+    );
+    for (const name of RUNTIME_MATERIALIZED_ARTIFACTS) keep.add(`${GENERATED_DIR}/${name}`);
+    for (const name of await io.listDir(join(root, GENERATED_DIR))) {
+      const rel = `${GENERATED_DIR}/${name}`;
+      if (keep.has(rel)) continue;
+      await io.remove(join(root, rel));
+      swept.push(rel);
+    }
+  }
+
+  return { artifacts, drift, swept: swept.sort(), incomplete: derived.incomplete, modelErrors: derived.errors };
 }
 
 export { dirOf, join as joinPath };