@cosmicdrift/kumiko-guards 0.362.0 → 0.364.0

package/src/guard-upgrade-state.ts

@@ -21,6 +21,7 @@
  *   bun guard-upgrade-state.ts
  */
 
+import { createHash } from "node:crypto";
 import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import {
@@ -60,45 +61,69 @@ export function resolveInstalledVersion(json: UpgradeJson): string {
   return json.installedVersion ?? json.currentVersion;
 }
 
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null;
+}
+
 export function isPendingEntry(value: unknown): value is PendingEntry {
-  if (!value || typeof value !== "object") return false;
-  const v = value as Record<string, unknown>;
+  if (!isRecord(value)) return false;
   return (
-    typeof v["version"] === "string" &&
-    typeof v["type"] === "string" &&
-    typeof v["title"] === "string"
+    typeof value["version"] === "string" &&
+    typeof value["type"] === "string" &&
+    typeof value["title"] === "string"
   );
 }
 
 export function isUpgradeJson(value: unknown): value is UpgradeJson {
-  if (!value || typeof value !== "object") return false;
-  const v = value as Record<string, unknown>;
-  const installed = v["installedVersion"];
+  if (!isRecord(value)) return false;
+  const installed = value["installedVersion"];
   return (
-    typeof v["currentVersion"] === "string" &&
+    typeof value["currentVersion"] === "string" &&
     (installed === undefined || installed === null || typeof installed === "string") &&
-    Array.isArray(v["pending"]) &&
-    v["pending"].every(isPendingEntry)
+    Array.isArray(value["pending"]) &&
+    value["pending"].every(isPendingEntry)
   );
 }
 
-export function isPendingManualStep(value: unknown): value is PendingManualStep {
-  if (!value || typeof value !== "object") return false;
-  const v = value as Record<string, unknown>;
-  return (
-    typeof v["id"] === "string" &&
-    v["id"].length > 0 &&
-    typeof v["version"] === "string" &&
-    typeof v["title"] === "string"
-  );
+// Same id scheme as manualEntryId in @cosmicdrift/kumiko-framework/upgrade-cli. Duplicated because
+// this package must stay installable without the framework; a test pins both to the same value.
+const MANUAL_ID_HASH_LENGTH = 8;
+
+export function manualEntryId(version: string, title: string): string {
+  const hash = createHash("sha256").update(title).digest("hex").slice(0, MANUAL_ID_HASH_LENGTH);
+  return `${version}:${hash}`;
 }
 
-function readPendingManual(parsed: unknown): readonly PendingManualStep[] {
-  const raw =
-    parsed && typeof parsed === "object"
-      ? (parsed as Record<string, unknown>)["pendingManual"]
-      : undefined;
-  return Array.isArray(raw) ? raw.filter(isPendingManualStep) : [];
+/** Markers written before entries carried an `id` get the id the CLI derives for them. */
+export function parsePendingManualStep(value: unknown): PendingManualStep | null {
+  if (!isRecord(value)) return null;
+  const { id, version, title } = value;
+  if (typeof version !== "string" || typeof title !== "string") return null;
+  return {
+    id: typeof id === "string" && id.length > 0 ? id : manualEntryId(version, title),
+    version,
+    title,
+  };
+}
+
+function readPendingManual(
+  parsed: unknown,
+): { readonly steps: readonly PendingManualStep[] } | { readonly error: string } {
+  const raw = isRecord(parsed) ? parsed["pendingManual"] : undefined;
+  if (raw === undefined) return { steps: [] };
+  if (!Array.isArray(raw))
+    return { error: `${MARKER_REL} has a "pendingManual" that is not an array` };
+  const steps: PendingManualStep[] = [];
+  for (const [index, entry] of raw.entries()) {
+    const step = parsePendingManualStep(entry);
+    if (step === null) {
+      return {
+        error: `${MARKER_REL} has a malformed pendingManual entry at index ${index} (needs string "version" and "title")`,
+      };
+    }
+    steps.push(step);
+  }
+  return { steps };
 }
 
 export function readMarker(root: string): UpgradeMarker | { error: string } {
@@ -114,16 +139,15 @@ export function readMarker(root: string): UpgradeMarker | { error: string } {
   } catch {
     return { error: `${MARKER_REL} is not valid JSON — broken marker file` };
   }
-  const version =
-    parsed && typeof parsed === "object"
-      ? (parsed as Record<string, unknown>)["version"]
-      : undefined;
+  const version = isRecord(parsed) ? parsed["version"] : undefined;
   if (typeof version !== "string" || !SEMVER_RE.test(version)) {
     return {
       error: `${MARKER_REL} is missing a valid "version" field (expected semver x.y.z[-pre][+build]) — broken marker file`,
     };
   }
-  return { version, pendingManual: readPendingManual(parsed) };
+  const pendingManual = readPendingManual(parsed);
+  if ("error" in pendingManual) return pendingManual;
+  return { version, pendingManual: pendingManual.steps };
 }
 
 /** Pending changelog entries turned into guard violations — pure, testable without a subprocess. */

package/src/index.ts

@@ -1,3 +1,4 @@
+export { AGENT_DOCS_DIR, renderAgentDocs, writeAgentDocs } from "./_lib/agent-docs";
 export { gitEnv } from "./_lib/git-env";
 export {
   type AstGuard,

package/src/pre-push.sh

@@ -18,6 +18,9 @@
 #      sub-repo's own package.json `test` script — refuses the push if that
 #      script is missing.
 #
+# Before the checks below, the hook runs a gitleaks scan of origin/main..HEAD
+# when the binary is installed.
+#
 # Extension point: a tracked, executable scripts/pre-push-extra.sh runs
 # before the main check in every branch above, with KUMIKO_PUSH_REPO_ROOT
 # and KUMIKO_PUSH_PARENT_DIR available inline (never exported).
@@ -118,6 +121,22 @@ if [ -f "$REPO_ROOT/.kumiko/upgrade-state.json" ]; then
   fi
 fi
 
+# Secret scan: runs before check-wt.sh/bun check so a leaked credential is
+# caught in seconds, not after the long checks. A missing binary or a missing
+# origin/main only warns, so a machine without gitleaks is not locked out.
+# No --config: gitleaks reads a .gitleaks.toml in the repo root itself.
+if ! command -v gitleaks >/dev/null 2>&1; then
+  echo "[pre-push] gitleaks not installed — secret scan skipped. Install: brew install gitleaks" >&2
+elif ! git -C "$REPO_ROOT" rev-parse --verify --quiet origin/main >/dev/null 2>&1; then
+  echo "[pre-push] origin/main not found — secret scan skipped" >&2
+else
+  echo "[pre-push] gitleaks git origin/main..HEAD"
+  if ! (cd "$REPO_ROOT" && gitleaks git --no-banner --redact --log-opts="origin/main..HEAD" .); then
+    echo "[pre-push] gitleaks found secrets — refusing push" >&2
+    exit 1
+  fi
+fi
+
 # infra#559/#569: from a worktree, `--git-common-dir` resolves to the main
 # checkout's .git, so the branch below would scope `bun check` to the
 # canonical sibling path instead of this worktree — checking the wrong

package/src/run-repo-checks.ts

@@ -7,6 +7,7 @@ import { check as realProviderIsolation } from "./check-real-provider-isolation"
 import { check as runtimeIsolation } from "./check-runtime-isolation";
 import { check as secretLiterals } from "./check-secret-literals";
 import { check as singleRuntimeInstance } from "./check-single-runtime-instance";
+import { check as agentDocsDrift } from "./guard-agent-docs-drift";
 import { check as featureIntegrationTests } from "./guard-feature-integration-tests";
 import { check as noDirectProcessEnv } from "./guard-no-direct-process-env";
 import { check as primitivesDiscipline } from "./guard-primitives-discipline";
@@ -29,6 +30,7 @@ export const REPO_CHECKS = [
   upgradeState,
   realProviderIsolation,
   singleRuntimeInstance,
+  agentDocsDrift,
 ];
 
 export const REPO_CHECK_FLAGS: readonly string[] = ["--write-baseline"];