karajan-code 3.4.1 → 3.5.0

package/src/harden/guidelines-engine.js

@@ -0,0 +1,48 @@
+/**
+ * guidelines-engine — seeds AI-agent guideline files for `kj harden`
+ * (KJC-TSK-0559), absorbing dev-hooks' generate_guidelines without an external
+ * MCP. Writes a kj:managed block into AGENTS.md and CLAUDE.md, preserving any
+ * content the user keeps outside the markers. Idempotent.
+ */
+
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+import { upsertManagedBlock } from "../utils/managed-markers.js";
+import { GUIDELINES_BODY } from "./guidelines-templates.js";
+
+const BLOCK_VERSION = 1;
+const TARGETS = ["AGENTS.md", "CLAUDE.md"];
+const DH_START = "<!-- @manufosela/dev-git-hooks:start -->";
+const DH_END = "<!-- @manufosela/dev-git-hooks:end -->";
+
+/** Remove a legacy dev-hooks managed block, preserving everything else. */
+export function stripDevHooksBlock(source) {
+  const s = source.indexOf(DH_START);
+  if (s === -1) return { content: source, migrated: false };
+  const e = source.indexOf(DH_END, s);
+  if (e === -1) return { content: source, migrated: false };
+  const before = source.slice(0, s).replace(/\n+$/, "");
+  const after = source.slice(e + DH_END.length).replace(/^\n+/, "");
+  const joiner = before && after ? "\n\n" : "";
+  return { content: `${before}${joiner}${after}`, migrated: true };
+}
+
+export function installGuidelines({ projectDir = process.cwd(), dryRun = false } = {}) {
+  const results = [];
+  for (const file of TARGETS) {
+    const target = join(projectDir, file);
+    const raw = existsSync(target) ? readFileSync(target, "utf8") : "";
+    const { content: source, migrated } = stripDevHooksBlock(raw);
+    const { content, action } = upsertManagedBlock({
+      source,
+      blockId: "guidelines",
+      version: BLOCK_VERSION,
+      body: GUIDELINES_BODY,
+      style: "html",
+    });
+    if (!dryRun && (migrated || action !== "unchanged")) writeFileSync(target, content);
+    results.push({ file, action: migrated ? "migrated" : action });
+  }
+  return { dryRun, guidelines: results };
+}

package/src/harden/guidelines-templates.js

@@ -0,0 +1,36 @@
+/**
+ * Distilled AI-agent guidelines for `kj harden` (KJC-TSK-0559).
+ *
+ * A compact, high-signal rule set seeded into AGENTS.md / CLAUDE.md inside a
+ * kj:managed block, so it preserves whatever the user wrote outside it. Kept
+ * deliberately short — these rules enter the agent's context on every run, so
+ * bloat dilutes the signal. Distilled from the dev-toolkit guidelines.
+ */
+
+export const GUIDELINES_BODY = [
+  "# Project guidelines (kj harden)",
+  "",
+  "## Code",
+  "- SOLID, DRY, KISS, YAGNI. `const` by default; arrow callbacks; template literals.",
+  "- ES2025 target: never `var`, `document.write`, `alert`/`confirm`/`prompt`, `escape`/`unescape`, `substr`.",
+  "  Prefer modern APIs (`structuredClone`, `Object.groupBy`, `Array.at`/`findLast`/`toSorted`, optional chaining, `??`).",
+  "- ES modules (`import`/`export`), never `require` in new code. Names in English, descriptive.",
+  "- No silent fallbacks: the system works or fails loudly. Validate and sanitize all input.",
+  "",
+  "## Commits & PRs",
+  "- Conventional Commits (`feat:`/`fix:`/`refactor:`/`docs:`/`test:`/`chore:`). Header <=100 chars, lowercase subject.",
+  '- Never attribute commits or PRs to AI (no `Co-Authored-By`, no "generated by").',
+  "- Atomic PRs: one purpose, small (~150 LOC). Each PR compiles and passes its tests on its own.",
+  "",
+  "## Testing",
+  "- Test-first. Run the tests after each meaningful change. Never skip tests.",
+  "",
+  "## Security",
+  "- Never commit secrets, keys or tokens. Parameterized queries; sanitize output against XSS.",
+  "",
+  "## UI/UX",
+  "- No native `alert`/`confirm`/`prompt` — use the app's modal system. Loading states; accessible; mobile-first.",
+  "",
+  "## Files",
+  "- Edit existing files in place; never overwrite a whole file to make a small change.",
+].join("\n");

package/src/harden/harden-engine.js

@@ -0,0 +1,66 @@
+/**
+ * harden-engine — installs kj-managed git hooks idempotently (KJC-TSK-0555).
+ *
+ * Hooks live under `.karajan/hooks/` and are activated via `core.hooksPath`,
+ * so harden never fights husky/simple-git-hooks nor touches `.git/hooks/`.
+ * Each hook is a shebang + a kj:managed block; re-running is a no-op and any
+ * content outside the block is preserved.
+ */
+
+import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+import { upsertManagedBlock } from "../utils/managed-markers.js";
+import { runCommand } from "../utils/process.js";
+import { hookBody, PROFILE_HOOKS, SHEBANG } from "./hook-templates.js";
+
+const BLOCK_VERSION = 1;
+const HOOKS_DIR = join(".karajan", "hooks");
+const HOOK_PREAMBLE = `${SHEBANG}\nset -e\n`;
+
+export function isGitRepo(projectDir) {
+  return existsSync(join(projectDir, ".git"));
+}
+
+/**
+ * Install (or refresh) the profile's hooks under `.karajan/hooks/` and point
+ * `core.hooksPath` there. Idempotent. `dryRun` computes actions without
+ * touching disk or git config. `cmds` supplies stack-aware lint/format/test
+ * commands (npm-script defaults). Returns a per-hook action report.
+ */
+export async function installHooks({
+  projectDir = process.cwd(),
+  profile = "standard",
+  cmds = {},
+  dryRun = false,
+} = {}) {
+  if (!isGitRepo(projectDir)) throw new Error(`Not a git repository: ${projectDir}`);
+  const hooks = PROFILE_HOOKS[profile];
+  if (!hooks) throw new Error(`Unknown harden profile: ${profile}`);
+
+  const absHooksDir = join(projectDir, HOOKS_DIR);
+  const results = [];
+  for (const hook of hooks) {
+    const target = join(absHooksDir, hook);
+    const source = existsSync(target) ? readFileSync(target, "utf8") : HOOK_PREAMBLE;
+    const { content, action } = upsertManagedBlock({
+      source,
+      blockId: `hook:${hook}`,
+      version: BLOCK_VERSION,
+      body: hookBody(hook, cmds),
+      style: "hash",
+    });
+    results.push({ hook, target, action });
+    if (!dryRun && action !== "unchanged") {
+      mkdirSync(absHooksDir, { recursive: true });
+      writeFileSync(target, content);
+      chmodSync(target, 0o755);
+    }
+  }
+
+  if (!dryRun) {
+    await runCommand("git", ["config", "core.hooksPath", HOOKS_DIR], { cwd: projectDir });
+  }
+
+  return { profile, hooksPath: HOOKS_DIR, dryRun, hooks: results };
+}

package/src/harden/hook-commands.js

@@ -0,0 +1,20 @@
+/**
+ * Native lint/format/test commands per language for `kj harden` hooks
+ * (KJC-TSK-0562).
+ *
+ * The installed hooks call the project's OWN toolchain, never npm by default,
+ * so hardening a Go/Python repo never drags Node onto a contributor's machine.
+ * JavaScript/TypeScript is built from package.json scripts by the caller (its
+ * commands depend on what the project defines). Unknown language ⇒ no commands,
+ * leaving only the universal POSIX-shell checks.
+ */
+
+export const COMMANDS_BY_LANGUAGE = {
+  python: { lint: "ruff check .", format: "ruff format --check .", test: "pytest" },
+  go: { lint: "go vet ./...", format: 'test -z "$(gofmt -l .)"', test: "go test ./..." },
+};
+
+/** Native commands for a language, or {} when JS/TS or unknown. */
+export function commandsForLanguage(language) {
+  return COMMANDS_BY_LANGUAGE[language] ?? {};
+}

package/src/harden/hook-templates.js

@@ -0,0 +1,69 @@
+/**
+ * Hook bodies + profile→hooks mapping for `kj harden` (KJC-TSK-0555, 0562).
+ *
+ * A body is the MANAGED portion only; harden-engine adds the shebang and the
+ * kj:managed markers around it. Pure POSIX sh — the universal checks (commit
+ * format, AI-attribution) need no toolchain, and lint/format/test lines call
+ * the project's NATIVE commands (from `cmds`), only when present. No npm/Node
+ * is imposed on non-JS repos. See docs/specs/quality-harness.md §5.
+ */
+
+const CONVENTIONAL_TYPES = "feat|fix|docs|style|refactor|perf|test|build|ci|chore|revert";
+const AI_ATTRIBUTION = "co-authored-by:.*(claude|gpt|copilot|gemini)|(generated|written) (by|with) .*(claude|gpt|copilot)";
+
+export const SHEBANG = "#!/usr/bin/env sh";
+
+/** Hooks enabled per profile. */
+export const PROFILE_HOOKS = {
+  minimal: ["commit-msg"],
+  standard: ["pre-commit", "commit-msg", "pre-push", "post-merge"],
+  strict: ["pre-commit", "commit-msg", "pre-push", "post-merge"],
+};
+
+/** Build the managed body for a single hook. */
+export function hookBody(hook, cmds = {}) {
+  switch (hook) {
+    case "pre-commit": {
+      const lines = ["# Lint + format the working tree with the project's native tools."];
+      if (cmds.lint) lines.push(`${cmds.lint} || { echo 'kj harden: lint failed'; exit 1; }`);
+      if (cmds.format) lines.push(`${cmds.format} || { echo 'kj harden: format check failed'; exit 1; }`);
+      if (!cmds.lint && !cmds.format) lines.push("# (no lint/format command detected for this stack)");
+      return lines.join("\n");
+    }
+    case "commit-msg":
+      // Pure POSIX — Conventional Commits header, length cap, AI-attribution.
+      return [
+        'msg_file="$1"',
+        'header=$(head -n1 "$msg_file")',
+        `if ! printf '%s' "$header" | grep -qE '^(${CONVENTIONAL_TYPES})(\\([a-z0-9._-]+\\))?!?: .+'; then`,
+        "  echo 'kj harden: commit header must follow Conventional Commits (type: subject)'; exit 1",
+        "fi",
+        'if [ "${#header}" -gt 100 ]; then echo \'kj harden: commit header exceeds 100 chars\'; exit 1; fi',
+        `if grep -qiE '${AI_ATTRIBUTION}' "$msg_file"; then`,
+        "  echo 'kj harden: AI attribution is not allowed in commit messages'; exit 1",
+        "fi",
+      ].join("\n");
+    case "pre-push": {
+      const lines = [
+        "# Identity guard — never push without a configured git identity.",
+        'if [ -z "$(git config user.email)" ] || [ -z "$(git config user.name)" ]; then',
+        "  echo 'kj harden: git user.name/user.email not set — refusing to push'; exit 1",
+        "fi",
+        'echo "kj harden: pushing as $(git config user.name) <$(git config user.email)>"',
+        "# Run the test suite before pushing.",
+      ];
+      if (cmds.test) lines.push(`${cmds.test} || { echo 'kj harden: tests failed'; exit 1; }`);
+      else lines.push("# (no test command detected for this stack)");
+      return lines.join("\n");
+    }
+    case "post-merge":
+      return [
+        "# Refresh the local RAG index so retrieval never serves stale code.",
+        "if command -v kj >/dev/null 2>&1; then",
+        "  kj rag index --since auto >/dev/null 2>&1 || true",
+        "fi",
+      ].join("\n");
+    default:
+      throw new Error(`Unknown hook: ${hook}`);
+  }
+}

package/src/harden/stack-roots.js

@@ -0,0 +1,74 @@
+/**
+ * detectStackRoots — find every language root in a (possibly monorepo) tree
+ * for `kj harden` (KJC-TSK-0561).
+ *
+ * Walks the project up to a shallow depth and returns the shallowest
+ * directory where each language appears, e.g. a fullstack repo yields
+ * `[{dir:"frontend",language:"javascript"},{dir:"backend",language:"python"}]`
+ * so lint/format config is seeded on each side. Universal config (handled by
+ * the caller) stays at the project root. Noise dirs are never descended.
+ */
+
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { join, relative } from "node:path";
+
+const IGNORE_DIRS = new Set([
+  "node_modules",
+  "dist",
+  "build",
+  "coverage",
+  "vendor",
+  "target",
+  "__pycache__",
+  "venv",
+]);
+const DEFAULT_MAX_DEPTH = 2;
+
+/** Identify the language of a single directory by its manifest files. */
+export function languageAt(dir) {
+  if (existsSync(join(dir, "package.json"))) {
+    if (existsSync(join(dir, "tsconfig.json"))) return "typescript";
+    try {
+      const pkg = JSON.parse(readFileSync(join(dir, "package.json"), "utf8"));
+      const deps = { ...pkg.dependencies, ...pkg.devDependencies };
+      if (deps.typescript || deps["ts-node"]) return "typescript";
+    } catch {
+      /* unreadable package.json → treat as plain JS */
+    }
+    return "javascript";
+  }
+  if (["pyproject.toml", "requirements.txt", "setup.py"].some((f) => existsSync(join(dir, f)))) return "python";
+  if (existsSync(join(dir, "go.mod"))) return "go";
+  return null;
+}
+
+export function detectStackRoots(projectDir, { maxDepth = DEFAULT_MAX_DEPTH } = {}) {
+  const found = [];
+  function walk(dir, depth) {
+    const language = languageAt(dir);
+    if (language) found.push({ dir: relative(projectDir, dir) || ".", language, depth });
+    if (depth >= maxDepth) return;
+    let entries;
+    try {
+      entries = readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const e of entries) {
+      if (e.isDirectory() && !e.name.startsWith(".") && !IGNORE_DIRS.has(e.name)) {
+        walk(join(dir, e.name), depth + 1);
+      }
+    }
+  }
+  walk(projectDir, 0);
+
+  // Keep only the shallowest directory per language.
+  const byLanguage = new Map();
+  for (const f of found) {
+    const cur = byLanguage.get(f.language);
+    if (!cur || f.depth < cur.depth) byLanguage.set(f.language, f);
+  }
+  return [...byLanguage.values()]
+    .map(({ dir, language }) => ({ dir, language }))
+    .sort((a, b) => a.dir.localeCompare(b.dir));
+}

package/src/harden/workflow-engine.js

@@ -0,0 +1,64 @@
+/**
+ * workflow-engine — seeds CI quality workflows for `kj harden` (KJC-TSK-0557).
+ *
+ * Seed-if-absent into `.github/workflows/`: a workflow the user already wrote
+ * (no kj:managed marker) is left untouched and reported "skipped". kj-managed
+ * workflows refresh in place. Markers ride in YAML `#` comments.
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+import { upsertManagedBlock } from "../utils/managed-markers.js";
+import { extraWorkflowsFor, qualityWorkflowFor, WORKFLOWS } from "./workflow-templates.js";
+
+const BLOCK_VERSION = 1;
+const WORKFLOWS_DIR = join(".github", "workflows");
+
+/** A package.json that ships code (not private, has bin or main) ⇒ publishable. */
+export function isPublishableNpm(projectDir) {
+  const pkgPath = join(projectDir, "package.json");
+  if (!existsSync(pkgPath)) return false;
+  try {
+    const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
+    return pkg.private !== true && Boolean(pkg.bin || pkg.main);
+  } catch {
+    return false;
+  }
+}
+
+export function installWorkflows({
+  projectDir = process.cwd(),
+  language = null,
+  profile = "standard",
+  dryRun = false,
+} = {}) {
+  const dir = join(projectDir, WORKFLOWS_DIR);
+  const quality = qualityWorkflowFor(language);
+  const extras = extraWorkflowsFor({ profile, publishable: isPublishableNpm(projectDir) });
+  const all = [...WORKFLOWS, ...(quality ? [quality] : []), ...extras];
+  const results = [];
+  for (const wf of all) {
+    const target = join(dir, wf.file);
+    const label = join(WORKFLOWS_DIR, wf.file);
+    const exists = existsSync(target);
+    const source = exists ? readFileSync(target, "utf8") : "";
+    if (exists && !source.includes(`kj:managed:${wf.blockId}`)) {
+      results.push({ file: label, action: "skipped" });
+      continue;
+    }
+    const { content, action } = upsertManagedBlock({
+      source,
+      blockId: wf.blockId,
+      version: BLOCK_VERSION,
+      body: wf.body,
+      style: "hash",
+    });
+    if (!dryRun && action !== "unchanged") {
+      mkdirSync(dir, { recursive: true });
+      writeFileSync(target, content);
+    }
+    results.push({ file: label, action });
+  }
+  return { dryRun, workflows: results };
+}

package/src/harden/workflow-templates.js

@@ -0,0 +1,152 @@
+/**
+ * CI workflow templates for `kj harden` (KJC-TSK-0557).
+ *
+ * Generic, language-agnostic GitHub Actions that `kj harden` seeds into a
+ * target repo's `.github/workflows/`. Bodies are plain strings (NOT template
+ * literals) so the `${{ … }}` GitHub expressions survive verbatim.
+ */
+
+// Blocks AI self-attribution in PR commit messages. Pure bash + grep, no Node.
+// Pins github.base_ref to an env var (never interpolated into the run block).
+export const NO_AI_ATTRIBUTION_WORKFLOW = [
+  "name: Block AI attribution",
+  "on:",
+  "  pull_request:",
+  "    branches: [main]",
+  "permissions:",
+  "  contents: read",
+  "jobs:",
+  "  scan:",
+  "    runs-on: ubuntu-latest",
+  "    steps:",
+  "      - uses: actions/checkout@v4",
+  "        with:",
+  "          fetch-depth: 0",
+  "      - name: Scan commit messages for AI attribution",
+  "        env:",
+  "          BASE_REF: ${{ github.base_ref }}",
+  "        run: |",
+  '          msgs=$(git log --format=%B "origin/${BASE_REF}...HEAD" || true)',
+  "          pat='co-authored-by:.*(claude|anthropic|openai|chatgpt|gpt-[0-9]|copilot|gemini|cursor|windsurf|codeium|deepseek)'",
+  "          pat=\"$pat|(generated|written|authored|assisted|powered) (by|with|using) .*(claude|anthropic|openai|copilot|gemini)\"",
+  '          if printf "%s" "$msgs" | grep -qiE "$pat"; then',
+  '            echo "::error::AI attribution detected in commit messages"; exit 1',
+  "          fi",
+  '          echo "AI attribution scan: clean"',
+].join("\n");
+
+/** Universal workflows (every stack). style:hash ⇒ marker in YAML comments. */
+export const WORKFLOWS = [
+  { file: "kj-no-ai-attribution.yml", blockId: "wf-no-ai", body: NO_AI_ATTRIBUTION_WORKFLOW },
+];
+
+const header = (steps) =>
+  [
+    "name: Quality",
+    "on:",
+    "  pull_request:",
+    "    branches: [main]",
+    "jobs:",
+    "  quality:",
+    "    runs-on: ubuntu-latest",
+    "    steps:",
+    "      - uses: actions/checkout@v4",
+    ...steps,
+  ].join("\n");
+
+const QUALITY_BY_LANGUAGE = {
+  javascript: header([
+    "      - uses: actions/setup-node@v4",
+    "        with:",
+    "          node-version: 22",
+    "      - run: npm ci",
+    "      - run: npm run -s lint --if-present",
+    "      - run: npm test",
+  ]),
+  python: header([
+    "      - uses: actions/setup-python@v5",
+    "        with:",
+    "          python-version: '3.12'",
+    "      - run: pip install ruff pytest",
+    "      - run: ruff check .",
+    "      - run: pytest",
+  ]),
+  go: header([
+    "      - uses: actions/setup-go@v5",
+    "        with:",
+    "          go-version: stable",
+    "      - run: go vet ./...",
+    "      - run: go test ./...",
+  ]),
+};
+QUALITY_BY_LANGUAGE.typescript = QUALITY_BY_LANGUAGE.javascript;
+
+/** Stack-aware Quality workflow entry, or null for an unknown language. */
+export function qualityWorkflowFor(language) {
+  const body = QUALITY_BY_LANGUAGE[language];
+  return body ? { file: "kj-quality.yml", blockId: "wf-quality", body } : null;
+}
+
+// Caps the net LOC delta of a PR (strict profile only — it is opinionated).
+export const SHRINK_BUDGET_WORKFLOW = [
+  "name: Shrink budget",
+  "on:",
+  "  pull_request:",
+  "    branches: [main]",
+  "permissions:",
+  "  contents: read",
+  "jobs:",
+  "  budget:",
+  "    runs-on: ubuntu-latest",
+  '    env: { LOC_LIMIT: "200" }',
+  "    steps:",
+  "      - uses: actions/checkout@v4",
+  "        with:",
+  "          fetch-depth: 0",
+  "      - name: Net LOC delta within budget",
+  "        env:",
+  "          BASE_REF: ${{ github.base_ref }}",
+  "        run: |",
+  "          d=$(git diff --numstat \"origin/${BASE_REF}...HEAD\" -- . ':!**/*.md' ':!*.lock' ':!package-lock.json' || true)",
+  '          a=$(printf "%s\\n" "$d" | awk \'$1!="-"{s+=$1}END{print s+0}\')',
+  '          r=$(printf "%s\\n" "$d" | awk \'$2!="-"{s+=$2}END{print s+0}\')',
+  '          net=$((a - r)); echo "net=$net (limit=$LOC_LIMIT)"',
+  '          if [ "$net" -gt "$LOC_LIMIT" ]; then echo "::error::PR adds $net net lines (limit $LOC_LIMIT)"; exit 1; fi',
+].join("\n");
+
+// Packs the tarball and installs it clean — only for publishable npm packages.
+export const PACK_SMOKE_WORKFLOW = [
+  "name: Pack smoke",
+  "on:",
+  "  pull_request:",
+  "    branches: [main]",
+  "permissions:",
+  "  contents: read",
+  "jobs:",
+  "  pack-smoke:",
+  "    runs-on: ubuntu-latest",
+  "    steps:",
+  "      - uses: actions/checkout@v4",
+  "      - uses: actions/setup-node@v4",
+  "        with:",
+  "          node-version: 22",
+  "      - run: npm ci",
+  "      - name: Pack and install the tarball clean",
+  "        run: |",
+  "          tgz=$(npm pack --silent)",
+  "          dir=$(mktemp -d)",
+  '          npm install --prefix "$dir" "$PWD/$tgz" --no-audit --no-fund',
+  '          echo "Tarball installs clean: $tgz"',
+].join("\n");
+
+/** Conditional workflows: shrink-budget on strict, pack-smoke when publishable. */
+export function extraWorkflowsFor({ profile = "standard", publishable = false } = {}) {
+  const extras = [];
+  if (profile === "strict") {
+    extras.push({ file: "kj-shrink-budget.yml", blockId: "wf-shrink", body: SHRINK_BUDGET_WORKFLOW });
+  }
+  if (publishable) {
+    extras.push({ file: "kj-pack-smoke.yml", blockId: "wf-pack-smoke", body: PACK_SMOKE_WORKFLOW });
+  }
+  return extras;
+}

package/src/utils/managed-markers.js

@@ -0,0 +1,93 @@
+/**
+ * Managed-markers — idempotent file-block scaffolding for `kj harden`
+ * (KJC-TSK-0555, design in docs/specs/quality-harness.md §4).
+ *
+ * harden owns ONLY the content between a pair of markers; everything else in
+ * the file is preserved verbatim. Re-running with the same input is a no-op.
+ * Generalises the `KJC-TSK-0455` marker already used by the post-merge hook
+ * installer, and honours the project rule "never overwrite existing files".
+ *
+ * Block shape (comment syntax varies by file type):
+ *   # >>> kj:managed:<id> v<N> >>> (do not edit: regenerated by kj harden)
+ *   …managed body…
+ *   # <<< kj:managed:<id> <<<
+ */
+
+const DEFAULT_NOTE = "do not edit: regenerated by kj harden";
+
+/** Wrap marker payload text in the comment syntax for a given style. */
+const COMMENT = {
+  hash: (text) => `# ${text}`,
+  slash: (text) => `// ${text}`,
+  html: (text) => `<!-- ${text} -->`,
+};
+
+/** Pick a comment style from a file path. Defaults to hash (shell/yaml/conf). */
+export function commentStyleFor(filePath = "") {
+  if (/\.(md|markdown|mdx)$/i.test(filePath)) return "html";
+  if (/\.(m?[jt]sx?|c[jt]s)$/i.test(filePath)) return "slash";
+  return "hash";
+}
+
+const openPayload = (blockId, version) => `>>> kj:managed:${blockId} v${version} >>>`;
+const closePayload = (blockId) => `<<< kj:managed:${blockId} <<<`;
+
+/** Render the full managed block (open marker + body + close marker). */
+export function buildManagedBlock({ blockId, version, body, style = "hash", note = DEFAULT_NOTE }) {
+  const comment = COMMENT[style] ?? COMMENT.hash;
+  const open = comment(`${openPayload(blockId, version)} (${note})`);
+  const close = comment(closePayload(blockId));
+  return `${open}\n${body}\n${close}`;
+}
+
+/**
+ * Locate a managed block by id in `source`, regardless of comment style or
+ * version. Returns line indices and the detected version, or { found:false }.
+ */
+export function findManagedBlock(source = "", blockId) {
+  const lines = source.split("\n");
+  const openTag = `>>> kj:managed:${blockId} v`;
+  const closeTag = `<<< kj:managed:${blockId} <<<`;
+  let startLine = -1;
+  let version = null;
+  for (let i = 0; i < lines.length; i += 1) {
+    const at = lines[i].indexOf(openTag);
+    if (at === -1) continue;
+    const rest = lines[i].slice(at + openTag.length);
+    const end = rest.indexOf(" >>>");
+    const digits = end === -1 ? "" : rest.slice(0, end);
+    if (/^\d+$/.test(digits)) {
+      startLine = i;
+      version = Number(digits);
+      break;
+    }
+  }
+  if (startLine === -1) return { found: false };
+  for (let i = startLine + 1; i < lines.length; i += 1) {
+    if (lines[i].includes(closeTag)) return { found: true, startLine, endLine: i, version };
+  }
+  return { found: false, malformed: true, startLine };
+}
+
+/**
+ * Insert or update the managed block for `blockId` in `source`, preserving all
+ * content outside the markers. Idempotent: identical input → action "unchanged".
+ *
+ * @returns {{content: string, action: "inserted"|"updated"|"unchanged", previousVersion: number|null}}
+ */
+export function upsertManagedBlock({ source = "", blockId, version, body, style = "hash", note }) {
+  const block = buildManagedBlock({ blockId, version, body, style, note });
+  const existing = findManagedBlock(source, blockId);
+
+  if (!existing.found) {
+    const base = source === "" ? "" : source.replace(/\n*$/, "\n");
+    return { content: `${base}${block}\n`, action: "inserted", previousVersion: null };
+  }
+
+  const lines = source.split("\n");
+  const before = lines.slice(0, existing.startLine);
+  const after = lines.slice(existing.endLine + 1);
+  const content = [...before, ...block.split("\n"), ...after].join("\n");
+  if (content === source) return { content, action: "unchanged", previousVersion: existing.version };
+  return { content, action: "updated", previousVersion: existing.version };
+}

package/node_modules/@sec-ant/readable-stream/LICENSE

@@ -1,21 +0,0 @@
-MIT License
-
-Copyright (c) 2022 Ze-Zheng Wu
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.