@lenne.tech/cli 1.9.6 → 1.10.0

package/build/lib/framework-detection.js

@@ -0,0 +1,167 @@
+"use strict";
+/**
+ * Framework-detection helpers for @lenne.tech/nest-server consumer projects.
+ *
+ * lenne.tech API projects can consume the framework in two modes:
+ *
+ *  - **npm mode** (classic): `@lenne.tech/nest-server` is installed as an npm
+ *    dependency. Framework source lives in
+ *    `node_modules/@lenne.tech/nest-server/`. Generated code uses bare
+ *    specifiers (`from '@lenne.tech/nest-server'`).
+ *
+ *  - **vendored mode**: The framework's `core/` directory is copied directly
+ *    into the project at `<api-root>/src/core/` as first-class project code.
+ *    There is **no** `@lenne.tech/nest-server` dependency in `package.json`.
+ *    Generated code uses relative imports (`from '../../../core'`, depth
+ *    varies by file location).
+ *
+ * The detection is driven by the presence of `<api-root>/src/core/VENDOR.md`
+ * (a baseline + patch-log file written by the vendoring pilot).
+ *
+ * This module centralizes the detection logic so that every CLI command which
+ * emits or patches nest-server-aware code can branch consistently.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.detectFrameworkMode = detectFrameworkMode;
+exports.findProjectDir = findProjectDir;
+exports.getFrameworkImportSpecifier = getFrameworkImportSpecifier;
+exports.getFrameworkRootPath = getFrameworkRootPath;
+exports.isVendoredProject = isVendoredProject;
+const node_fs_1 = require("node:fs");
+const path = __importStar(require("node:path"));
+/**
+ * Determines the current framework consumption mode of the given project.
+ *
+ * Returns `'vendor'` if `VENDOR.md` indicates vendored mode. Otherwise
+ * returns `'npm'` (the classic mode where `@lenne.tech/nest-server` is an
+ * npm dependency).
+ */
+function detectFrameworkMode(projectDir) {
+    return isVendoredProject(projectDir) ? 'vendor' : 'npm';
+}
+/**
+ * Walks up from `startDir` looking for the nearest `package.json`, returning
+ * the directory that contains it. Used by commands that are invoked from a
+ * sub-directory of an API project and need to find the project root.
+ *
+ * Returns `undefined` if no `package.json` is found up to the filesystem root.
+ */
+function findProjectDir(startDir) {
+    let current = path.resolve(startDir);
+    const root = path.parse(current).root;
+    while (current !== root) {
+        if ((0, node_fs_1.existsSync)(path.join(current, 'package.json'))) {
+            return current;
+        }
+        current = path.dirname(current);
+    }
+    return undefined;
+}
+/**
+ * Returns the import specifier to use for `from '<framework>'` in generated
+ * source code living at `sourceFilePath`.
+ *
+ * - npm mode:    always `'@lenne.tech/nest-server'` (bare specifier).
+ * - vendor mode: a relative path from `sourceFilePath`'s directory to
+ *                `<projectDir>/src/core`, normalized to forward slashes and
+ *                prefixed with `./` if needed. Example: for
+ *                `projectDir/src/server/modules/foo/foo.service.ts`, returns
+ *                `'../../../core'`.
+ *
+ * `sourceFilePath` is the absolute path of the file that WILL CONTAIN the
+ * import — NOT the file being imported. Depth is calculated from this path.
+ *
+ * @example
+ * // Project at /abs/api, file at src/server/modules/foo/foo.service.ts
+ * getFrameworkImportSpecifier('/abs/api',
+ *   '/abs/api/src/server/modules/foo/foo.service.ts');
+ * // → '../../../core'   (vendor mode)
+ * // → '@lenne.tech/nest-server'  (npm mode)
+ */
+function getFrameworkImportSpecifier(projectDir, sourceFilePath) {
+    if (!isVendoredProject(projectDir)) {
+        return '@lenne.tech/nest-server';
+    }
+    const corePath = path.join(projectDir, 'src', 'core');
+    const fromDir = path.dirname(sourceFilePath);
+    let rel = path.relative(fromDir, corePath);
+    // Normalize to POSIX separators (import specifiers are always forward-slash)
+    rel = rel.split(path.sep).join('/');
+    // Guarantee a relative prefix; sibling or descendant paths otherwise miss `./`
+    if (!rel.startsWith('.')) {
+        rel = `./${rel}`;
+    }
+    return rel;
+}
+/**
+ * Returns the filesystem root of the framework source for the project.
+ *
+ * - npm mode:    `<projectDir>/node_modules/@lenne.tech/nest-server`
+ * - vendor mode: `<projectDir>/src/core`
+ *
+ * Consumers that need to introspect framework source files (e.g. permissions
+ * scanner, CrudService lookup) should use this instead of hard-coding either
+ * path.
+ */
+function getFrameworkRootPath(projectDir) {
+    return isVendoredProject(projectDir)
+        ? path.join(projectDir, 'src', 'core')
+        : path.join(projectDir, 'node_modules', '@lenne.tech', 'nest-server');
+}
+/**
+ * Detects whether the given API project directory runs in vendored mode.
+ *
+ * A project is considered vendored when:
+ *   1. `<projectDir>/src/core/VENDOR.md` exists, AND
+ *   2. The VENDOR.md content references `@lenne.tech/nest-server` (guards
+ *      against coincidental unrelated `VENDOR.md` files).
+ *
+ * @param projectDir Absolute path to the api project (the directory that
+ *                   contains `package.json` and `src/`).
+ */
+function isVendoredProject(projectDir) {
+    const vendorMd = path.join(projectDir, 'src', 'core', 'VENDOR.md');
+    if (!(0, node_fs_1.existsSync)(vendorMd)) {
+        return false;
+    }
+    try {
+        const content = (0, node_fs_1.readFileSync)(vendorMd, 'utf-8');
+        return content.includes('@lenne.tech/nest-server');
+    }
+    catch (_a) {
+        return false;
+    }
+}

package/build/templates/nest-server-module/inputs/template-create.input.ts.ejs

@@ -1,4 +1,4 @@
-import { Restricted, RoleEnum, UnifiedField } from '@lenne.tech/nest-server';
+import { Restricted, RoleEnum, UnifiedField } from '<%= props.frameworkImport %>';
 import { InputType } from '@nestjs/graphql';
 import { <%= props.namePascal %>Input } from './<%= props.nameKebab %>.input';<%- props.imports %>
 

package/build/templates/nest-server-module/inputs/template.input.ts.ejs

@@ -1,4 +1,4 @@
-import { CoreInput, Restricted, RoleEnum, UnifiedField } from '@lenne.tech/nest-server';
+import { CoreInput, Restricted, RoleEnum, UnifiedField } from '<%= props.frameworkImport %>';
 import { InputType } from '@nestjs/graphql';<%- props.imports %>
 
 /**

package/build/templates/nest-server-module/outputs/template-fac-result.output.ts.ejs

@@ -1,4 +1,4 @@
-import { UnifiedField } from '@lenne.tech/nest-server';
+import { UnifiedField } from '<%= props.frameworkImport %>';
 <% if (props.isGql) { %>
     import { ObjectType } from '@nestjs/graphql';
 <% } %>

package/build/templates/nest-server-module/template.controller.ts.ejs

@@ -1,4 +1,4 @@
-import { ApiCommonErrorResponses, FilterArgs, RoleEnum, Roles } from '@lenne.tech/nest-server';
+import { ApiCommonErrorResponses, FilterArgs, RoleEnum, Roles } from '<%= props.frameworkImport %>';
 import { Body, Controller, Delete, Get, Param, Post, Put } from '@nestjs/common';
 import { ApiOkResponse } from '@nestjs/swagger';
 

package/build/templates/nest-server-module/template.model.ts.ejs

@@ -1,4 +1,4 @@
-import { Restricted, RoleEnum, equalIds<% if (props.mappings.includes('mapClasses')) { %>, mapClasses<% } %>, UnifiedField} from '@lenne.tech/nest-server';
+import { Restricted, RoleEnum, equalIds<% if (props.mappings.includes('mapClasses')) { %>, mapClasses<% } %>, UnifiedField} from '<%= props.frameworkImport %>';
 <% if (props.isGql) { %>
 import { ObjectType } from '@nestjs/graphql';
 <% } %>

package/build/templates/nest-server-module/template.module.ts.ejs

@@ -1,4 +1,4 @@
-import { ConfigService } from '@lenne.tech/nest-server';
+import { ConfigService } from '<%= props.frameworkImport %>';
 import { Module, forwardRef } from '@nestjs/common';
 import { MongooseModule } from '@nestjs/mongoose';
 <% if ((props.controller === 'GraphQL') || (props.controller === 'Both')) { -%>

package/build/templates/nest-server-module/template.resolver.ts.ejs

@@ -1,4 +1,4 @@
-import { FilterArgs, GraphQLServiceOptions, RoleEnum, Roles, ServiceOptions } from '@lenne.tech/nest-server';
+import { FilterArgs, GraphQLServiceOptions, RoleEnum, Roles, ServiceOptions } from '<%= props.frameworkImport %>';
 import { Inject } from '@nestjs/common';
 import { Args, Mutation, Query, Resolver, Subscription } from '@nestjs/graphql';
 import { PubSub } from 'graphql-subscriptions';

package/build/templates/nest-server-module/template.service.ts.ejs

@@ -1,4 +1,4 @@
-import { ConfigService, CrudService, ServiceOptions, assignPlain } from '@lenne.tech/nest-server';
+import { ConfigService, CrudService, ServiceOptions, assignPlain } from '<%= props.frameworkImport %>';
 import { Inject, Injectable, NotFoundException } from '@nestjs/common';
 import { InjectModel } from '@nestjs/mongoose';
 <% if (props.isGql) { %>import { PubSub } from 'graphql-subscriptions';

package/build/templates/nest-server-object/template-create.input.ts.ejs

@@ -1,4 +1,4 @@
-import { Restricted, RoleEnum, UnifiedField } from '@lenne.tech/nest-server';
+import { Restricted, RoleEnum, UnifiedField } from '<%= props.frameworkImport %>';
 import { InputType } from '@nestjs/graphql';
 import { <%= props.namePascal %>Input } from './<%= props.nameKebab %>.input';<%- props.imports %>
 

package/build/templates/nest-server-object/template.input.ts.ejs

@@ -1,4 +1,4 @@
-import { CoreInput, Restricted, RoleEnum, UnifiedField } from '@lenne.tech/nest-server';
+import { CoreInput, Restricted, RoleEnum, UnifiedField } from '<%= props.frameworkImport %>';
 import { InputType } from '@nestjs/graphql';<%- props.imports %>
 
 /**

package/build/templates/nest-server-object/template.object.ts.ejs

@@ -1,4 +1,4 @@
-import { CoreModel, Restricted, RoleEnum<% if (props.mappings.includes('mapClasses')) { %>, mapClasses<% } %>, UnifiedField } from '@lenne.tech/nest-server';
+import { CoreModel, Restricted, RoleEnum<% if (props.mappings.includes('mapClasses')) { %>, mapClasses<% } %>, UnifiedField } from '<%= props.frameworkImport %>';
 import { ObjectType } from '@nestjs/graphql';
 import { Schema as MongooseSchema, SchemaFactory } from '@nestjs/mongoose';
 import { Document } from 'mongoose';<%- props.imports %>

package/build/templates/nest-server-tests/tests.e2e-spec.ts.ejs

@@ -1,4 +1,4 @@
-import { RoleEnum, TestGraphQLType, TestHelper } from '@lenne.tech/nest-server';
+import { RoleEnum, TestGraphQLType, TestHelper } from '<%= props.frameworkImport %>';
 import { Test, TestingModule } from '@nestjs/testing';
 import { PubSub } from 'graphql-subscriptions';
 import envConfig from '../src/config.env';

package/build/templates/vendor-scripts/check-vendor-freshness.mjs

@@ -0,0 +1,131 @@
+#!/usr/bin/env node
+// Check whether the vendored @lenne.tech/nest-server core is up-to-date with the
+// latest upstream release. Non-blocking: prints a warning when outdated, but always
+// exits 0 so that `check` / `check:fix` pipelines continue.
+//
+// Reads:
+//   projects/api/src/core/VENDOR.md  →  baseline version (e.g. "11.24.1")
+//
+// Fetches:
+//   https://registry.npmjs.org/@lenne.tech/nest-server/latest  →  latest published version
+//
+// Outputs:
+//   - Up-to-date   → stdout: "✓ vendored nest-server core is up-to-date (vX.Y.Z)"
+//   - Outdated     → stderr: "⚠ vendored nest-server core is X.Y.Z, latest is A.B.C"
+//   - Offline/err  → stderr: warn + exit 0 (never fail)
+
+import { readFileSync, existsSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+import https from 'node:https';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const VENDOR_MD = join(__dirname, '..', '..', 'src', 'core', 'VENDOR.md');
+
+// ANSI color codes (no external deps)
+const C = {
+  reset: '\x1b[0m',
+  yellow: '\x1b[33m',
+  green: '\x1b[32m',
+  dim: '\x1b[2m',
+};
+
+function warnAndExit(msg) {
+  process.stderr.write(`${C.yellow}⚠ ${msg}${C.reset}\n`);
+  process.exit(0);
+}
+
+function ok(msg) {
+  process.stdout.write(`${C.green}✓ ${msg}${C.reset}\n`);
+  process.exit(0);
+}
+
+// 1. Locate VENDOR.md
+if (!existsSync(VENDOR_MD)) {
+  warnAndExit(
+    `vendor-freshness: VENDOR.md not found at ${VENDOR_MD}. ` +
+      `Is this project vendored? Skipping check.`,
+  );
+}
+
+// 2. Parse baseline version from VENDOR.md
+let baselineVersion;
+try {
+  const content = readFileSync(VENDOR_MD, 'utf-8');
+  // Match: "**Baseline-Version:** 11.24.1" or "Baseline-Version: 11.24.1"
+  const match = content.match(/Baseline-Version[:*\s]+([\d.]+[\w.-]*)/);
+  if (!match) {
+    warnAndExit(`vendor-freshness: could not parse Baseline-Version from ${VENDOR_MD}`);
+  }
+  baselineVersion = match[1];
+} catch (err) {
+  warnAndExit(`vendor-freshness: failed to read ${VENDOR_MD}: ${err.message}`);
+}
+
+// 3. Fetch latest from npm registry (offline-tolerant)
+function fetchLatest() {
+  return new Promise((resolve) => {
+    const req = https.get(
+      'https://registry.npmjs.org/@lenne.tech/nest-server/latest',
+      { timeout: 5000 },
+      (res) => {
+        if (res.statusCode !== 200) {
+          resolve(null);
+          return;
+        }
+        let body = '';
+        res.on('data', (chunk) => (body += chunk));
+        res.on('end', () => {
+          try {
+            const json = JSON.parse(body);
+            resolve(json.version || null);
+          } catch {
+            resolve(null);
+          }
+        });
+      },
+    );
+    req.on('error', () => resolve(null));
+    req.on('timeout', () => {
+      req.destroy();
+      resolve(null);
+    });
+  });
+}
+
+const latestVersion = await fetchLatest();
+
+if (!latestVersion) {
+  warnAndExit(
+    `vendor-freshness: could not reach npm registry. ` +
+      `Current baseline: ${baselineVersion}. Check skipped.`,
+  );
+}
+
+// 4. semver compare (simple lexical sort works for X.Y.Z)
+function parseSemver(v) {
+  const parts = v.split('.').map((p) => parseInt(p, 10));
+  return [parts[0] || 0, parts[1] || 0, parts[2] || 0];
+}
+
+const [bMaj, bMin, bPatch] = parseSemver(baselineVersion);
+const [lMaj, lMin, lPatch] = parseSemver(latestVersion);
+
+const baselineNum = bMaj * 1e6 + bMin * 1e3 + bPatch;
+const latestNum = lMaj * 1e6 + lMin * 1e3 + lPatch;
+
+if (baselineNum === latestNum) {
+  ok(`vendored nest-server core is up-to-date (v${baselineVersion})`);
+} else if (baselineNum < latestNum) {
+  const msg =
+    `vendored nest-server core is v${baselineVersion}, ` +
+    `latest upstream is v${latestVersion}\n` +
+    `${C.dim}  Run /lt-dev:backend:update-nest-server-core to sync${C.reset}`;
+  warnAndExit(msg);
+} else {
+  // baseline > latest: weird but not fatal
+  warnAndExit(
+    `vendored nest-server core is v${baselineVersion} (ahead of npm latest v${latestVersion}). ` +
+      `Possibly tracking an unreleased branch.`,
+  );
+}

package/build/templates/vendor-scripts/propose-upstream-pr.ts

@@ -0,0 +1,269 @@
+/**
+ * Diff-generator for the `lt-dev:nest-server-core-contributor` agent.
+ *
+ * Analyzes local git commits that touched projects/api/src/core/ since the
+ * vendoring baseline, emits per-commit patch files and a human-readable
+ * candidate list. Filters out cosmetic commits (format, style, lint:fix).
+ * Does NOT cherry-pick or open any PR — that's the contributor agent's job.
+ *
+ * Usage:
+ *   pnpm run vendor:propose-upstream
+ *   (or: ts-node scripts/vendor/propose-upstream-pr.ts [--since <sha>])
+ *
+ * Output directory: scripts/vendor/upstream-candidates/<timestamp>/
+ *   - local-commits.json: structured metadata for every commit
+ *   - local-diffs/<commit-sha>.patch: per-commit patch file
+ *   - summary.md: human-readable candidate list
+ */
+
+import { execSync } from 'node:child_process';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+const PROJECT_ROOT = join(__dirname, '..', '..');
+const VENDOR_DIR = join(PROJECT_ROOT, 'src', 'core');
+const VENDOR_MD = join(VENDOR_DIR, 'VENDOR.md');
+const OUTPUT_BASE = join(PROJECT_ROOT, 'scripts', 'vendor', 'upstream-candidates');
+
+const MONOREPO_ROOT = join(PROJECT_ROOT, '..', '..');
+
+function die(msg: string): never {
+  process.stderr.write(`ERROR: ${msg}\n`);
+  process.exit(1);
+}
+
+function sh(cmd: string, opts: { cwd?: string; allowFailure?: boolean } = {}): string {
+  try {
+    return execSync(cmd, {
+      cwd: opts.cwd ?? MONOREPO_ROOT,
+      encoding: 'utf-8',
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+  } catch (err: unknown) {
+    if (opts.allowFailure) {
+      const e = err as { stdout?: string };
+      return e.stdout ?? '';
+    }
+    throw err;
+  }
+}
+
+// Cosmetic message patterns (case-insensitive)
+const COSMETIC_PATTERNS = [
+  /^chore.*format/i,
+  /^style:/i,
+  /^chore.*oxfmt/i,
+  /^chore.*prettier/i,
+  /^chore.*lint:fix/i,
+  /^chore.*linting/i,
+  /^chore.*apply project formatting/i,
+  /^chore.*re-?format/i,
+];
+
+interface CommitInfo {
+  sha: string;
+  shortSha: string;
+  subject: string;
+  author: string;
+  date: string;
+  files: string[];
+  isCosmetic: boolean;
+  cosmeticReason: string | null;
+}
+
+// 1. Parse arguments
+const args = process.argv.slice(2);
+let sinceRef: string | null = null;
+
+for (let i = 0; i < args.length; i++) {
+  if (args[i] === '--since' && i + 1 < args.length) {
+    sinceRef = args[++i];
+  }
+}
+
+// 2. Verify vendored state
+if (!existsSync(VENDOR_MD)) {
+  die(`VENDOR.md not found at ${VENDOR_MD}. Not a vendored project.`);
+}
+
+const vendorContent = readFileSync(VENDOR_MD, 'utf-8');
+const baselineVersionMatch = vendorContent.match(/Baseline-Version[:*\s]+([\d.]+[\w.-]*)/);
+const baselineVersion = baselineVersionMatch?.[1] ?? 'unknown';
+
+// 3. Determine starting point for git log
+if (!sinceRef) {
+  // Find the commit that added VENDOR.md — that's the vendoring commit
+  sinceRef = sh(
+    `git log --diff-filter=A --format="%H" -- projects/api/src/core/VENDOR.md | tail -1`,
+  ).trim();
+  if (!sinceRef) {
+    die(
+      'Could not find the commit that added VENDOR.md. Pass --since <sha> manually.',
+    );
+  }
+}
+
+// 4. Collect all commits since that ref that touched src/core/
+const gitLog = sh(
+  `git log --format="%H%x09%s%x09%an%x09%aI" ${sinceRef}..HEAD -- projects/api/src/core/`,
+).trim();
+
+if (!gitLog) {
+  process.stdout.write(
+    `No local commits found since ${sinceRef.substring(0, 8)} touching src/core/. Nothing to propose.\n`,
+  );
+  process.exit(0);
+}
+
+const commits: CommitInfo[] = gitLog
+  .split('\n')
+  .filter((line) => line.trim())
+  .map((line) => {
+    const [sha, subject, author, date] = line.split('\t');
+    const filesOutput = sh(
+      `git show --pretty="" --name-only ${sha} -- projects/api/src/core/`,
+    ).trim();
+    const files = filesOutput ? filesOutput.split('\n') : [];
+
+    // Cosmetic check by message pattern
+    let isCosmetic = false;
+    let cosmeticReason: string | null = null;
+    for (const pat of COSMETIC_PATTERNS) {
+      if (pat.test(subject)) {
+        isCosmetic = true;
+        cosmeticReason = `commit-message matches ${pat.source}`;
+        break;
+      }
+    }
+
+    // Additional cosmetic check: if diff has only whitespace/formatting changes
+    if (!isCosmetic) {
+      const diff = sh(`git show --format="" ${sha} -- projects/api/src/core/`);
+      // Normalize: drop all whitespace, quote style, trailing commas
+      const normalized = diff
+        .split('\n')
+        .filter((l) => l.startsWith('+') || l.startsWith('-'))
+        .filter((l) => !l.startsWith('+++') && !l.startsWith('---'))
+        .map((l) => l.slice(1).replace(/\s+/g, '').replace(/['"`]/g, '').replace(/,$/, ''))
+        .filter((l) => l.length > 0);
+
+      // Count +/- with the same normalized content — if they cancel out, it's cosmetic
+      const plus = normalized.filter((_, i) => diff.split('\n').filter((l) => l.startsWith('+') && !l.startsWith('+++'))[i]);
+      // Simpler heuristic: if normalized plus == normalized minus, it's cosmetic
+      const plusLines = diff.split('\n').filter((l) => l.startsWith('+') && !l.startsWith('+++')).map((l) => l.slice(1).replace(/\s+/g, ''));
+      const minusLines = diff.split('\n').filter((l) => l.startsWith('-') && !l.startsWith('---')).map((l) => l.slice(1).replace(/\s+/g, ''));
+      const plusSet = new Set(plusLines);
+      const minusSet = new Set(minusLines);
+      const plusOnlyCount = [...plusSet].filter((l) => !minusSet.has(l) && l.length > 0).length;
+      const minusOnlyCount = [...minusSet].filter((l) => !plusSet.has(l) && l.length > 0).length;
+      if (plusOnlyCount === 0 && minusOnlyCount === 0 && plusLines.length > 0) {
+        isCosmetic = true;
+        cosmeticReason = 'normalized diff is empty (whitespace/quotes only)';
+      }
+    }
+
+    return {
+      sha,
+      shortSha: sha.substring(0, 8),
+      subject,
+      author,
+      date,
+      files,
+      isCosmetic,
+      cosmeticReason,
+    };
+  });
+
+// 5. Write output
+const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
+const outputDir = join(OUTPUT_BASE, timestamp);
+const diffsDir = join(outputDir, 'local-diffs');
+mkdirSync(diffsDir, { recursive: true });
+
+// Save JSON
+writeFileSync(
+  join(outputDir, 'local-commits.json'),
+  JSON.stringify(
+    {
+      baselineVersion,
+      sinceRef,
+      generated: new Date().toISOString(),
+      total: commits.length,
+      cosmetic: commits.filter((c) => c.isCosmetic).length,
+      substantial: commits.filter((c) => !c.isCosmetic).length,
+      commits,
+    },
+    null,
+    2,
+  ),
+);
+
+// Save per-commit patch files (only substantial ones)
+for (const commit of commits.filter((c) => !c.isCosmetic)) {
+  const patch = sh(`git show ${commit.sha} -- projects/api/src/core/`);
+  writeFileSync(join(diffsDir, `${commit.shortSha}.patch`), patch);
+}
+
+// Save summary
+const substantialCommits = commits.filter((c) => !c.isCosmetic);
+const cosmeticCommits = commits.filter((c) => c.isCosmetic);
+
+const summary = `# Upstream-PR Candidates
+
+**Baseline version:** ${baselineVersion}
+**Since commit:** ${sinceRef.substring(0, 8)}
+**Generated:** ${new Date().toISOString()}
+
+## Statistics
+
+- Total commits touching \`src/core/\`: ${commits.length}
+- Filtered as cosmetic: ${cosmeticCommits.length}
+- **Substantial (candidate pool):** ${substantialCommits.length}
+
+## Substantial Commits (need manual categorization by the contributor agent)
+
+${
+  substantialCommits.length === 0
+    ? '_No substantial local changes. Nothing to contribute._'
+    : substantialCommits
+        .map(
+          (c) =>
+            `### \`${c.shortSha}\` — ${c.subject}\n\n` +
+            `- **Author:** ${c.author}\n` +
+            `- **Date:** ${c.date}\n` +
+            `- **Files:** ${c.files.length}\n` +
+            c.files.map((f) => `  - ${f}`).join('\n') +
+            `\n- **Patch:** \`local-diffs/${c.shortSha}.patch\`\n`,
+        )
+        .join('\n')
+}
+
+## Filtered Cosmetic Commits
+
+${
+  cosmeticCommits.length === 0
+    ? '_(none)_'
+    : cosmeticCommits
+        .map((c) => `- \`${c.shortSha}\` — ${c.subject} _(${c.cosmeticReason})_`)
+        .join('\n')
+}
+
+## Next Steps
+
+Run the contributor agent:
+\`\`\`
+/lt-dev:backend:contribute-nest-server-core
+\`\`\`
+
+It will:
+1. Categorize each substantial commit (upstream-candidate / project-specific / unclear)
+2. Check upstream HEAD for duplicates
+3. Prepare candidate branches in a local upstream clone with reverse flatten-fix
+4. Generate PR-body drafts for human review
+5. Present a final list with \`gh pr create\` commands ready to run
+`;
+
+writeFileSync(join(outputDir, 'summary.md'), summary);
+
+process.stdout.write(`\nDone. Review:\n`);
+process.stdout.write(`  cat ${outputDir}/summary.md\n`);