@cosmicdrift/kumiko-framework 0.220.1 → 0.222.0

package/src/scripts/codemod/crypto-shredding-testing-move.ts

@@ -8,47 +8,55 @@
 //
 // Usage: bun scripts/codemod/crypto-shredding-testing-move.ts <targetDir> [--dry-run]
 
-import { resolve } from "node:path";
-import { Glob } from "bun";
-import { Project } from "ts-morph";
+import { type Dirent, readdirSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { Project, type SourceFile } from "ts-morph";
 
 const OLD_SPECIFIER = "@cosmicdrift/kumiko-framework/crypto";
 const NEW_SPECIFIER = "@cosmicdrift/kumiko-framework/testing";
 const MOVED_NAMES = new Set(["resetPiiSubjectKmsForTests", "resetBlindIndexKeyForTests"]);
 
+const EXCLUDE_DIRS = new Set(["node_modules", "dist", "build"]);
+
 function findTargetFiles(rootDir: string): string[] {
-  const glob = new Glob("**/*.{ts,tsx}");
-  const EXCLUDE = ["/node_modules/", "/dist/", "/build/"];
+  // Walk the tree and skip excluded dirs while descending — filtering the
+  // absolute path after a full Glob scan silently no-ops when the repo root
+  // itself contains "/build/" or "/node_modules/" (fw#2289).
   const files: string[] = [];
-  for (const file of glob.scanSync({ cwd: rootDir, dot: false })) {
-    const abs = resolve(rootDir, file);
-    if (EXCLUDE.some((p) => abs.includes(p))) continue;
-    files.push(abs);
-  }
+  const walk = (dir: string): void => {
+    let entries: Dirent[];
+    try {
+      entries = readdirSync(dir, { withFileTypes: true });
+    } catch {
+      // skip: unreadable directory during walk — treat as empty.
+      return;
+    }
+    for (const ent of entries) {
+      if (ent.isDirectory()) {
+        if (EXCLUDE_DIRS.has(ent.name) || ent.name.startsWith(".")) continue;
+        walk(join(dir, ent.name));
+        continue;
+      }
+      if (ent.isFile() && /\.(ts|tsx)$/.test(ent.name)) {
+        files.push(join(dir, ent.name));
+      }
+    }
+  };
+  walk(rootDir);
   return files.sort();
 }
 
-async function main(): Promise<void> {
-  const positional = process.argv.slice(2).filter((a) => !a.startsWith("--"));
-  const dryRun = process.argv.includes("--dry-run");
-  const rootDir = resolve(positional[0] ?? process.cwd());
-
-  const files = findTargetFiles(rootDir);
-  const project = new Project({
-    skipAddingFilesFromTsConfig: true,
-    skipFileDependencyResolution: true,
-  });
-
-  let touchedFiles = 0;
-  let movedNames = 0;
-
-  for (const file of files) {
-    const sourceFile = project.addSourceFileAtPath(file);
-    const oldImport = sourceFile
-      .getImportDeclarations()
-      .find((d) => d.getModuleSpecifierValue() === OLD_SPECIFIER);
-    if (!oldImport) continue;
+/** Move matching value imports from crypto → testing. Returns count of names moved. */
+function migrateFile(sourceFile: SourceFile): number {
+  // Value imports only — a pre-existing `import type { … } from testing`
+  // must not receive runtime helpers (they would be erased).
+  const oldImports = sourceFile
+    .getImportDeclarations()
+    .filter((d) => d.getModuleSpecifierValue() === OLD_SPECIFIER && !d.isTypeOnly());
+  if (oldImports.length === 0) return 0;
 
+  let fileMoved = 0;
+  for (const oldImport of oldImports) {
     const movedHere = oldImport.getNamedImports().filter((spec) => MOVED_NAMES.has(spec.getName()));
     if (movedHere.length === 0) continue;
 
@@ -56,7 +64,7 @@ async function main(): Promise<void> {
 
     const existingNewImport = sourceFile
       .getImportDeclarations()
-      .find((d) => d.getModuleSpecifierValue() === NEW_SPECIFIER);
+      .find((d) => d.getModuleSpecifierValue() === NEW_SPECIFIER && !d.isTypeOnly());
     if (existingNewImport) {
       const already = new Set(existingNewImport.getNamedImports().map((s) => s.getName()));
       for (const name of names) {
@@ -73,8 +81,32 @@ async function main(): Promise<void> {
       !!oldImport.getNamespaceImport();
     if (!remaining) oldImport.remove();
 
+    fileMoved += names.length;
+  }
+  return fileMoved;
+}
+
+async function main(): Promise<void> {
+  const positional = process.argv.slice(2).filter((a) => !a.startsWith("--"));
+  const dryRun = process.argv.includes("--dry-run");
+  const rootDir = resolve(positional[0] ?? process.cwd());
+
+  const files = findTargetFiles(rootDir);
+  const project = new Project({
+    skipAddingFilesFromTsConfig: true,
+    skipFileDependencyResolution: true,
+  });
+
+  let touchedFiles = 0;
+  let movedNames = 0;
+
+  for (const file of files) {
+    const sourceFile = project.addSourceFileAtPath(file);
+    const fileMoved = migrateFile(sourceFile);
+    if (fileMoved === 0) continue;
+
     touchedFiles++;
-    movedNames += names.length;
+    movedNames += fileMoved;
     if (!dryRun) sourceFile.saveSync();
   }
 

package/src/scripts/codemod/pii-personal-migration.ts

@@ -77,7 +77,7 @@ const OVERRIDES_ARG_INDEX_1 = new Set(["createEmbeddedField", "createEmbeddedLis
 
 const FIELD_FACTORY_RE = /^create\w*Field$/;
 
-type ReportEntry = { readonly file: string; readonly line: number; readonly reason: string };
+type ReportEntry = { readonly file: string; readonly line: number; readonly note: string };
 type FindBucket = "exact" | "fuzzy" | "none" | "secret" | "ref" | "personal-false" | "no-find";
 
 const reports: ReportEntry[] = [];
@@ -92,11 +92,11 @@ const counts: Record<FindBucket, number> = {
   "no-find": 0,
 };
 
-function report(node: Node, reason: string): void {
+function report(node: Node, note: string): void {
   reports.push({
     file: node.getSourceFile().getFilePath(),
     line: node.getStartLineNumber(),
-    reason,
+    note,
   });
 }
 
@@ -374,8 +374,8 @@ function processObjectLiteral(obj: ObjectLiteralExpression, factoryName: string)
     newLookupableSites.push({
       file: obj.getSourceFile().getFilePath(),
       line: subject.prop.getStartLineNumber(),
-      // find: "fuzzy" newly adds lookupable (was searchable-only) — needs a _bidx column migration
-      reason: "fuzzy_search_needs_bidx_migration",
+      // Guard keys on property name `reason`; this is console copy, not an error code.
+      note: "needs a `_bidx` column migration",
     });
   }
 
@@ -469,11 +469,11 @@ async function main(): Promise<void> {
   }
   console.log(`\nNewly gains lookupable (needs a _bidx migration): ${newLookupableSites.length}`);
   for (const r of newLookupableSites) {
-    console.log(`  ${relative(rootDir, r.file)}:${r.line} — ${r.reason}`);
+    console.log(`  ${relative(rootDir, r.file)}:${r.line} — ${r.note}`);
   }
   console.log(`\nReported (not transformed): ${reports.length}`);
   for (const r of reports) {
-    console.log(`  ${relative(rootDir, r.file)}:${r.line} — ${r.reason}`);
+    console.log(`  ${relative(rootDir, r.file)}:${r.line} — ${r.note}`);
   }
 }
 

package/src/search/purge-subject.ts

@@ -9,11 +9,12 @@
 //      that still carry the subject key in encrypted columns.
 
 import { quoteIdent, subjectCiphertextLikePattern } from "../crypto/ciphertext-pattern";
+import { isSelfPiiField } from "../crypto/is-self-pii-field";
 import type { SubjectId } from "../crypto/kms-adapter";
 import { collectSearchableSubjectFields } from "../crypto/subject-resolver";
 import type { DbRunner } from "../db/connection";
 import { resolveTableName } from "../db/entity-table-meta";
-import { executeRawQuery } from "../db/queries/raw-sql";
+import { executeRawQueryRead } from "../db/queries/raw-sql";
 import type { FeatureDefinition } from "../engine/types";
 import type { EntityDefinition } from "../engine/types/fields";
 import type { EntityId, TenantId } from "../engine/types/identifiers";
@@ -46,7 +47,7 @@ function ownershipPredicates(
           params.push(subject.userId);
           parts.push(`${quoteIdent(col)} = $${n}`);
         }
-      } else if ("pii" in field && field.pii === true && selfIdN === undefined) {
+      } else if (isSelfPiiField(field) && selfIdN === undefined) {
         selfIdN = nextParam();
         params.push(subject.userId);
         parts.push(`${quoteIdent("id")} = $${selfIdN}`);
@@ -78,7 +79,7 @@ async function collectMatchingRowsForEntity(
   let offset = 0;
   for (;;) {
     const offsetN = params.length + 1;
-    const page = await executeRawQuery<MatchedRow>(
+    const page = await executeRawQueryRead<MatchedRow>(
       db,
       `SELECT id, tenant_id FROM ${quoteIdent(tableName)} WHERE ${whereSql}
         ORDER BY ${quoteIdent("id")} ASC

package/src/search/reindex-entity.ts

@@ -7,7 +7,7 @@
 
 import type { DbRunner } from "../db/connection";
 import { resolveTableName } from "../db/entity-table-meta";
-import { executeRawQuery } from "../db/queries/raw-sql";
+import { executeRawQueryRead } from "../db/queries/raw-sql";
 import type { Registry, TenantId } from "../engine/types";
 import {
   buildSearchDocument,
@@ -112,7 +112,7 @@ export async function reindexEntity(
     // across both types needs a text cast that breaks integer ordering.
     // This is a one-time backfill over existing rows, not a live hot path;
     // switch to keyset if it ever needs to run against a churning table.
-    const rows = await executeRawQuery<Record<string, unknown>>(
+    const rows = await executeRawQueryRead<Record<string, unknown>>(
       db,
       `SELECT * FROM ${quoteIdent(tableName)}
         WHERE ${quoteIdent("tenant_id")} = $1 ${deletedFilter}

package/src/stack/__tests__/request-helper.integration.test.ts

@@ -10,7 +10,7 @@ import { NotFoundError, UnprocessableError, writeFailure } from "../../errors";
 import { setupTestStack, type TestStack } from "../test-stack";
 import { TestUsers } from "../test-users";
 
-let stack: TestStack;
+let stack: TestStack | undefined;
 
 const pingFeature = defineFeature("reqhelp", (r) => {
   r.writeHandler(
@@ -49,12 +49,12 @@ beforeAll(async () => {
 });
 
 afterAll(async () => {
-  await stack.cleanup();
+  await stack?.cleanup();
 });
 
 describe("createRequestHelper via setupTestStack.http", () => {
   test("writeOk posts to /api/write and returns handler data", async () => {
-    const data = await stack.http.writeOk<{ note: string; userId: string }>(
+    const data = await stack!.http.writeOk<{ note: string; userId: string }>(
       "reqhelp:write:echo",
       { note: "hello" },
       TestUsers.admin,
@@ -63,7 +63,7 @@ describe("createRequestHelper via setupTestStack.http", () => {
   });
 
   test("queryOk posts to /api/query and returns handler data", async () => {
-    const data = await stack.http.queryOk<{ id: string; ok: boolean }>(
+    const data = await stack!.http.queryOk<{ id: string; ok: boolean }>(
       "reqhelp:query:lookup",
       { id: "abc" },
       TestUsers.admin,
@@ -72,14 +72,14 @@ describe("createRequestHelper via setupTestStack.http", () => {
   });
 
   test("writeErr returns structured WriteErrorInfo with httpStatus", async () => {
-    const err = await stack.http.writeErr("reqhelp:write:boom", {}, TestUsers.admin);
+    const err = await stack!.http.writeErr("reqhelp:write:boom", {}, TestUsers.admin);
     expect(err.code).toBe("unprocessable");
-    expect(err.httpStatus).toBeGreaterThanOrEqual(400);
+    expect(err.httpStatus).toBe(422);
     expect(err.i18nKey).toBe("errors.unprocessable");
   });
 
   test("queryErr returns structured WriteErrorInfo for not-found", async () => {
-    const err = await stack.http.queryErr(
+    const err = await stack!.http.queryErr(
       "reqhelp:query:lookup",
       { id: "missing" },
       TestUsers.admin,
@@ -89,13 +89,13 @@ describe("createRequestHelper via setupTestStack.http", () => {
   });
 
   test("writeOk throws when the write fails (so suites cannot ignore failures)", async () => {
-    await expect(stack.http.writeOk("reqhelp:write:boom", {}, TestUsers.admin)).rejects.toThrow(
+    await expect(stack!.http.writeOk("reqhelp:write:boom", {}, TestUsers.admin)).rejects.toThrow(
       /reqhelp:write:boom/,
     );
   });
 
   test("batch posts commands and returns per-command results", async () => {
-    const res = await stack.http.batch(
+    const res = await stack!.http.batch(
       [
         { type: "reqhelp:write:echo", payload: { note: "a" } },
         { type: "reqhelp:write:echo", payload: { note: "b" } },
@@ -112,7 +112,7 @@ describe("createRequestHelper via setupTestStack.http", () => {
   });
 
   test("writeWithHeaders forwards extra headers alongside auth", async () => {
-    const res = await stack.http.writeWithHeaders(
+    const res = await stack!.http.writeWithHeaders(
       "reqhelp:write:echo",
       { note: "hdr" },
       TestUsers.admin,
@@ -122,5 +122,19 @@ describe("createRequestHelper via setupTestStack.http", () => {
     const body = (await res.json()) as { isSuccess?: boolean; data?: { note?: string } };
     expect(body.isSuccess).toBe(true);
     expect(body.data?.note).toBe("hdr");
+    expect(res.headers.get("X-Correlation-ID")).toBe("corr-42");
+  });
+
+  test("queryWithHeaders forwards extra headers alongside auth", async () => {
+    const res = await stack!.http.queryWithHeaders(
+      "reqhelp:query:lookup",
+      { id: "abc" },
+      TestUsers.admin,
+      { "X-Correlation-ID": "corr-query" },
+    );
+    expect(res.ok).toBe(true);
+    expect(res.headers.get("X-Correlation-ID")).toBe("corr-query");
+    const body = (await res.json()) as { data?: { id?: string; ok?: boolean } };
+    expect(body.data).toEqual({ id: "abc", ok: true });
   });
 });

package/src/stack/__tests__/request-helper.test.ts

@@ -103,7 +103,7 @@ describe("createRequestHelper", () => {
       ),
     );
     const http = createRequestHelper(app, jwtStub().jwt);
-    expect(http.writeOk("todo.create", {}, user)).rejects.toThrow(
+    await expect(http.writeOk("todo.create", {}, user)).rejects.toThrow(
       'Expected write "todo.create" to succeed but got error: internal_error (DbError: connection lost)',
     );
   });
@@ -119,7 +119,7 @@ describe("createRequestHelper", () => {
 
     const succeeding = appRecording(() => Response.json({ isSuccess: true, data: {} }));
     const http2 = createRequestHelper(succeeding.app, jwtStub().jwt);
-    expect(http2.queryErr("q.type", {}, user)).rejects.toThrow(
+    await expect(http2.queryErr("q.type", {}, user)).rejects.toThrow(
       'Expected query "q.type" to fail but it succeeded',
     );
   });

package/src/testing/file-provider-contract.ts

@@ -90,6 +90,25 @@ export function describeFileProviderContract(
       await expect(it.next()).rejects.toThrow();
     });
 
+    test("list returns only keys under the given prefix", async () => {
+      const group = `contract/list-${crypto.randomUUID()}`;
+      const keyA = `${group}/a.txt`;
+      const keyB = `${group}/b.txt`;
+      const outsideKey = `contract/list-${crypto.randomUUID()}/c.txt`;
+      writtenKeys.push(keyA, keyB, outsideKey);
+      await provider.write(keyA, bytes("a"));
+      await provider.write(keyB, bytes("b"));
+      await provider.write(outsideKey, bytes("c"));
+
+      const listed = await provider.list(`${group}/`);
+      expect(new Set(listed)).toEqual(new Set([keyA, keyB]));
+    });
+
+    test("list on a prefix with no matches returns an empty array", async () => {
+      const listed = await provider.list(`contract/list-missing-${crypto.randomUUID()}/`);
+      expect(listed).toEqual([]);
+    });
+
     test("getSignedUrl, when implemented, returns a URL string", async () => {
       // skip: getSignedUrl is optional on the contract — feature-detected
       if (!provider.getSignedUrl) return;

package/src/ui-types/index.ts

@@ -77,6 +77,7 @@ export type {
   EntityEditScreenDefinition,
   EntityListScreenDefinition,
   FieldCondition,
+  FieldIconKey,
   FieldRenderer,
   FormWidth,
   ListColumnSpec,

package/src/upgrade-cli.ts

@@ -4,6 +4,7 @@ import {
   readdirSync,
   readFileSync,
   realpathSync,
+  statSync,
   writeFileSync,
 } from "node:fs";
 import { isAbsolute, join, relative, resolve } from "node:path";
@@ -170,7 +171,23 @@ export function findFeaturesDirs(cwd: string): string[] {
 // node_modules after a plain npm/bun install (fw#2301).
 export function findCodemodScriptsRoot(repoRoot: string): string | null {
   const local = join(repoRoot, "packages/framework/src");
-  if (existsSync(join(local, CODEMOD_SUBDIR))) return local;
+  if (existsSync(join(local, CODEMOD_SUBDIR))) {
+    // If package.json exists, require it to be kumiko-framework so a generic
+    // monorepo `packages/framework` cannot shadow the installed package.
+    // Missing package.json (test fixtures / incomplete trees) keeps prior behavior.
+    const pkgPath = join(repoRoot, "packages/framework/package.json");
+    if (existsSync(pkgPath)) {
+      try {
+        const pkg = JSON.parse(readFileSync(pkgPath, "utf8")) as { name?: string };
+        if (pkg.name === "@cosmicdrift/kumiko-framework") return local;
+        // wrong name → fall through
+      } catch {
+        // unreadable → fall through
+      }
+    } else {
+      return local;
+    }
+  }
 
   let dir = repoRoot;
   for (let i = 0; i < 10; i++) {
@@ -187,7 +204,10 @@ export function findCodemodScriptsRoot(repoRoot: string): string | null {
 // Resolves a changes.json `codemod` field to an absolute script path,
 // refusing anything that would escape scripts/codemod/ (path traversal,
 // absolute paths, symlinks pointing outward) or that isn't a real .ts file.
-export function resolveCodemodScript(
+// First arg is the consumer repo root (same as findCodemodScriptsRoot) —
+// not the scripts root — so out-of-tree callers keep compiling against the
+// public upgrade-cli subpath without silently resolving to null (fw#2341).
+function resolveCodemodScriptAt(
   codemodScriptsRoot: string,
   codemodField: string | undefined,
 ): string | null {
@@ -213,6 +233,15 @@ export function resolveCodemodScript(
   return resolved;
 }
 
+export function resolveCodemodScript(
+  repoRoot: string,
+  codemodField: string | undefined,
+): string | null {
+  const scriptsRoot = findCodemodScriptsRoot(repoRoot);
+  if (!scriptsRoot) return null;
+  return resolveCodemodScriptAt(scriptsRoot, codemodField);
+}
+
 type CodemodRunResult = { readonly ok: boolean; readonly output: string };
 
 // Array-form argv only — never a shell string. The script itself decides
@@ -242,10 +271,15 @@ type UpgradeMarkerCodemod = {
   readonly codemod: string;
   readonly title: string;
 };
+type UpgradeMarkerManual = {
+  readonly version: string;
+  readonly title: string;
+};
 type UpgradeMarker = {
   readonly version: string;
   readonly appliedAt: string;
   readonly codemods: readonly UpgradeMarkerCodemod[];
+  readonly pendingManual?: readonly UpgradeMarkerManual[];
 };
 
 function writeUpgradeMarker(targetDir: string, marker: UpgradeMarker): void {
@@ -254,24 +288,64 @@ function writeUpgradeMarker(targetDir: string, marker: UpgradeMarker): void {
   writeFileSync(join(dir, "upgrade-state.json"), `${JSON.stringify(marker, null, 2)}\n`, "utf-8");
 }
 
+/** Highest pending version strictly below the earliest open manual breaking
+ *  entry (no codemod). Falls back to highest non-breaking pending when every
+ *  pending version is at/after that manual — never advances onto the manual. */
+/** Highest pending version strictly below the earliest open manual breaking
+ *  entry (no codemod). Falls back to highest non-breaking pending when every
+ *  pending version is at/after that manual. If only manuals remain, returns
+ *  `fallbackInstalled` so the marker stamp moves without claiming manuals done. */
+function markerVersionForPending(
+  pending: readonly ChangelogEntry[],
+  manualEntries: readonly ChangelogEntry[],
+  fallbackInstalled: string,
+): string {
+  const earliestManual = [...manualEntries].sort((a, b) =>
+    compareVersions(a.version, b.version),
+  )[0];
+  const eligible = pending.filter(
+    (e) => earliestManual === undefined || compareVersions(e.version, earliestManual.version) < 0,
+  );
+  const headEligible = eligible[0];
+  if (headEligible !== undefined) {
+    return eligible.reduce(
+      (max, e) => (compareVersions(e.version, max) > 0 ? e.version : max),
+      headEligible.version,
+    );
+  }
+  const nonBreaking = pending.filter((e) => e.type !== "breaking");
+  const headNonBreaking = nonBreaking[0];
+  if (headNonBreaking !== undefined) {
+    return nonBreaking.reduce(
+      (max, e) => (compareVersions(e.version, max) > 0 ? e.version : max),
+      headNonBreaking.version,
+    );
+  }
+  return fallbackInstalled;
+}
+
 // Runs every pending breaking entry's codemod, oldest version first (so a
 // later codemod can assume an earlier one already ran). Stops on the first
 // failure — no partial marker. Writes the marker whenever dryRun is false —
 // even with zero pending entries, so an already-current app still gets a
 // bootstrap marker recording its installed version (fw#2299).
+// kumiko-lint-ignore complexity-budget sequential codemod runner with zero-pending bootstrap marker
 async function applyCodemods(
   out: UpgradeCliOut,
   pending: readonly ChangelogEntry[],
   repoRoot: string,
   targetDir: string,
   dryRun: boolean,
-  currentVersion: string,
+  // Installed version for the zero-pending bootstrap marker — never a
+  // `--from` filter override (that would permanently skip real pending
+  // codemods once the CI guard compares against the fake marker).
+  markerVersion: string,
 ): Promise<number> {
   if (pending.length === 0) {
     out.log("  ✓ Nothing new since your version.");
     if (!dryRun) {
       writeUpgradeMarker(targetDir, {
-        version: currentVersion,
+        version: markerVersion,
         appliedAt: Temporal.Now.instant().toString(),
         codemods: [],
       });
@@ -284,7 +358,7 @@ async function applyCodemods(
   const codemodEntries = breaking
     .filter(hasCodemod)
     .sort((a, b) => compareVersions(a.version, b.version));
-  const manualEntries = breaking.filter((e) => !e.codemod);
+  const manualEntries = breaking.filter((e) => !hasCodemod(e));
 
   for (const e of manualEntries) {
     out.log(`  ⚠ ${e.version} · ${e.title} — no codemod, manual migration required`);
@@ -296,15 +370,28 @@ async function applyCodemods(
         ? "  No automatable codemods among the pending breaking changes."
         : "  ✓ No breaking changes pending.",
     );
+    if (!dryRun) {
+      const markerVer = markerVersionForPending(pending, manualEntries, markerVersion);
+      writeUpgradeMarker(targetDir, {
+        version: markerVer,
+        appliedAt: Temporal.Now.instant().toString(),
+        codemods: [],
+      });
+      out.log(`  ✓ Applied 0 codemod(s). Wrote ${join(targetDir, ".kumiko/upgrade-state.json")}`);
+    }
     return 0;
   }
 
   const codemodScriptsRoot = findCodemodScriptsRoot(repoRoot);
+  if (codemodScriptsRoot === null) {
+    out.err(
+      `  ✗ could not locate @cosmicdrift/kumiko-framework/src/scripts/codemod — is the framework installed? searched from ${repoRoot} upward`,
+    );
+    return 1;
+  }
   const ran: UpgradeMarkerCodemod[] = [];
   for (const e of codemodEntries) {
-    const scriptPath = codemodScriptsRoot
-      ? resolveCodemodScript(codemodScriptsRoot, e.codemod)
-      : null;
+    const scriptPath = resolveCodemodScript(repoRoot, e.codemod);
     if (!scriptPath) {
       out.err(`  ✗ ${e.version} · ${e.title} — invalid codemod path "${e.codemod}"`);
       return 1;
@@ -325,20 +412,20 @@ async function applyCodemods(
     return 0;
   }
 
-  const firstPending = pending[0];
-  if (!firstPending) return 0;
-  const latestVersion = pending.reduce(
-    (max, e) => (compareVersions(e.version, max) > 0 ? e.version : max),
-    firstPending.version,
-  );
+  const latestVersion = markerVersionForPending(pending, manualEntries, markerVersion);
+  const pendingManual = manualEntries.map((e) => ({ version: e.version, title: e.title }));
   writeUpgradeMarker(targetDir, {
     version: latestVersion,
     appliedAt: Temporal.Now.instant().toString(),
     codemods: ran,
+    ...(pendingManual.length > 0 && { pendingManual }),
   });
   out.log(
     `  ✓ Applied ${ran.length} codemod(s). Wrote ${join(targetDir, ".kumiko/upgrade-state.json")}`,
   );
+  if (pendingManual.length > 0) {
+    out.log(`  ⚠ ${pendingManual.length} breaking change(s) still need manual migration.`);
+  }
   return 0;
 }
 
@@ -398,9 +485,19 @@ export async function runUpgradeCli(
   if (getFlag(args, "apply")) {
     const dirFlag = getStringFlag(args, "dir");
     const targetDir = dirFlag ? resolve(dirFlag) : cwd;
+    if (!existsSync(targetDir) || !statSync(targetDir).isDirectory()) {
+      out.err("");
+      out.err(`  --dir path is not a directory: ${targetDir}`);
+      out.err("");
+      return 1;
+    }
+    // Marker must reflect what is actually installed under the target (or
+    // cwd), not a `--from` filter override — otherwise CI stays green forever.
+    const markerVersion =
+      (dirFlag ? readCurrentVersion(targetDir) : null) ?? installedVersion ?? currentVersion;
     const dryRun = getFlag(args, "dry-run");
     out.log("");
-    const code = await applyCodemods(out, pending, repoRoot, targetDir, dryRun, currentVersion);
+    const code = await applyCodemods(out, pending, repoRoot, targetDir, dryRun, markerVersion);
     out.log("");
     return code;
   }