kibi-cli 0.19.0 → 2.0.0

package/dist/commands/gc.js

@@ -1,84 +1,153 @@
-/*
- Kibi — repo-local, per-branch, queryable long-term memory for software projects
- Copyright (C) 2026 Piotr Franczyk
-
- This program is free software: you can redistribute it and/or modify
- it under the terms of the GNU Affero General Public License as published by
- the Free Software Foundation, either version 3 of the License, or
- (at your option) any later version.
-
- This program is distributed in the hope that it will be useful,
- but WITHOUT ANY WARRANTY; without even the implied warranty of
- MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
- GNU Affero General Public License for more details.
-
- You should have received a copy of the GNU Affero General Public License
- along with this program.  If not, see <https://www.gnu.org/licenses/>.
-*/
-import { execSync } from "node:child_process";
+import { spawnSync } from "node:child_process";
 import * as fs from "node:fs";
 import * as path from "node:path";
-export async function gcCommand(options) {
-    // If force is true, perform deletion. Otherwise default to dry run.
-    const dryRun = options?.force ? false : (options?.dryRun ?? true);
-    try {
-        const kbRoot = path.resolve(process.cwd(), ".kb/branches");
-        if (!fs.existsSync(kbRoot)) {
-            console.error("No branch KBs found (.kb/branches does not exist)");
-            process.exitCode = 1;
-            return;
+import { branchStoreKey, branchStoresRoot, readBranchStoreManifest, } from "../utils/branch-store-locator.js";
+const DEFAULT_RETENTION_DAYS = 30;
+function localBranches(workspaceRoot) {
+    const result = spawnSync("git", ["branch", "--format=%(refname:short)"], {
+        encoding: "utf8",
+        cwd: workspaceRoot,
+        stdio: ["pipe", "pipe", "pipe"],
+    });
+    if (result.status !== 0) {
+        throw new Error(result.stderr?.trim() || "unable to list local Git branches");
+    }
+    const output = result.stdout ?? "";
+    const live = new Set(output
+        .split("\n")
+        .map((branch) => branch.trim())
+        .filter(Boolean));
+    // A branch checked out in another worktree is live even when it is not the
+    // current worktree's symbolic HEAD. Remote-only refs are deliberately not
+    // included: they have no local authored checkout to protect.
+    const worktrees = spawnSync("git", ["worktree", "list", "--porcelain"], {
+        encoding: "utf8",
+        cwd: workspaceRoot,
+        stdio: ["pipe", "pipe", "pipe"],
+    });
+    if (worktrees.status === 0) {
+        for (const line of (worktrees.stdout ?? "").split("\n")) {
+            const match = line.match(/^branch refs\/heads\/(.+)$/);
+            if (match?.[1])
+                live.add(match[1]);
         }
-        let gitBranches;
-        try {
-            execSync("git rev-parse --git-dir", {
-                encoding: "utf-8",
-                cwd: process.cwd(),
-                stdio: ["pipe", "pipe", "pipe"],
-                env: process.env,
-            });
-            const output = execSync("git branch --format='%(refname:short)'", {
-                encoding: "utf-8",
-                cwd: process.cwd(),
-                stdio: ["pipe", "pipe", "pipe"],
-                env: process.env,
-            });
-            gitBranches = new Set(output
-                .trim()
-                .split("\n")
-                .map((b) => b.trim().replace(/^'|'$/g, ""))
-                .filter((b) => b));
+    }
+    return live;
+}
+function quarantineRoot(workspaceRoot) {
+    return path.join(workspaceRoot, ".kb", "quarantine", "branches");
+}
+function quarantineBranch(workspaceRoot, sourcePath, branch) {
+    const target = path.join(quarantineRoot(workspaceRoot), branchStoreKey(branch), new Date().toISOString().replaceAll(":", "-"));
+    fs.mkdirSync(path.dirname(target), { recursive: true });
+    fs.renameSync(sourcePath, target);
+    fs.writeFileSync(path.join(target, "quarantine.json"), `${JSON.stringify({
+        version: 1,
+        branch,
+        key: branchStoreKey(branch),
+        quarantinedAt: new Date().toISOString(),
+        sourcePath: path.relative(workspaceRoot, sourcePath),
+    }, null, 2)}\n`, { mode: 0o600 });
+    return target;
+}
+function purgeQuarantine(workspaceRoot, retentionDays) {
+    const root = quarantineRoot(workspaceRoot);
+    if (!fs.existsSync(root))
+        return 0;
+    const cutoff = Date.now() - retentionDays * 24 * 60 * 60 * 1000;
+    let purged = 0;
+    for (const key of fs.readdirSync(root, { withFileTypes: true })) {
+        if (!key.isDirectory())
+            continue;
+        const keyPath = path.join(root, key.name);
+        for (const entry of fs.readdirSync(keyPath, { withFileTypes: true })) {
+            if (!entry.isDirectory())
+                continue;
+            const candidate = path.join(keyPath, entry.name);
+            const metadataPath = path.join(candidate, "quarantine.json");
+            let quarantinedAt = fs.statSync(candidate).mtimeMs;
+            try {
+                const metadata = JSON.parse(fs.readFileSync(metadataPath, "utf8"));
+                if (metadata.quarantinedAt) {
+                    const parsed = Date.parse(metadata.quarantinedAt);
+                    if (Number.isFinite(parsed))
+                        quarantinedAt = parsed;
+                }
+            }
+            catch {
+                // A missing or malformed journal falls back to the directory mtime.
+            }
+            if (retentionDays > 0 && quarantinedAt > cutoff)
+                continue;
+            fs.rmSync(candidate, { recursive: true, force: true });
+            purged += 1;
+        }
+        if (fs.readdirSync(keyPath).length === 0) {
+            fs.rmSync(keyPath, { recursive: true, force: true });
         }
-        catch (error) {
-            const message = error instanceof Error ? error.message : String(error);
-            console.error(`Not in a git repository or git command failed: ${message}`);
-            process.exitCode = 1;
+    }
+    return purged;
+}
+export async function gcCommand(options = {}) {
+    const workspaceRoot = process.cwd();
+    const retentionDays = Number.isFinite(options.retentionDays) && (options.retentionDays ?? 0) >= 0
+        ? Math.floor(options.retentionDays)
+        : DEFAULT_RETENTION_DAYS;
+    const branchesRoot = branchStoresRoot(workspaceRoot);
+    try {
+        if (!fs.existsSync(branchesRoot)) {
+            console.log("No branch KBs found (.kb/branches does not exist)");
+            process.exitCode = 0;
             return;
         }
-        const kbBranches = fs
-            .readdirSync(kbRoot, { withFileTypes: true })
-            .filter((d) => d.isDirectory())
-            .map((d) => d.name);
-        // Branches are protected if they exist in git - no default branch concept
-        const staleBranches = kbBranches.filter((kb) => !gitBranches.has(kb));
-        // Perform deletion when dryRun is false (force requested)
-        const performDelete = !dryRun;
-        let deletedCount = 0;
-        if (performDelete && staleBranches.length > 0) {
-            for (const branch of staleBranches) {
-                const branchPath = path.join(kbRoot, branch);
-                fs.rmSync(branchPath, { recursive: true, force: true });
-                deletedCount++;
+        const live = localBranches(workspaceRoot);
+        const candidates = [];
+        const visit = (dir, relativeBranch) => {
+            const entries = fs.readdirSync(dir, { withFileTypes: true });
+            for (const entry of entries) {
+                const candidatePath = path.join(dir, entry.name);
+                if (!entry.isDirectory())
+                    continue;
+                const manifest = readBranchStoreManifest(candidatePath);
+                if (manifest !== null) {
+                    candidates.push({
+                        branch: manifest.branch,
+                        path: candidatePath,
+                        legacy: false,
+                    });
+                    continue;
+                }
+                const next = relativeBranch
+                    ? `${relativeBranch}/${entry.name}`
+                    : entry.name;
+                if (fs.existsSync(path.join(candidatePath, "kb.rdf")) ||
+                    fs.existsSync(path.join(candidatePath, "storage.json"))) {
+                    candidates.push({ branch: next, path: candidatePath, legacy: true });
+                }
+                else {
+                    visit(candidatePath, next);
+                }
+            }
+        };
+        visit(branchesRoot, "");
+        const stale = candidates.filter(({ branch }) => !live.has(branch));
+        if (!options.force && !options.purge) {
+            console.log(`Found ${stale.length} stale branch KB(s) (dry run - not quarantined)`);
+            for (const candidate of stale) {
+                console.log(`  - ${candidate.branch}: ${candidate.path}`);
             }
+            process.exitCode = 0;
+            return;
         }
-        if (dryRun) {
-            console.log(`Found ${staleBranches.length} stale branch KB(s) (dry run - not deleted)`);
-            if (staleBranches.length > 0) {
-                for (const b of staleBranches)
-                    console.log(`  - ${b}`);
+        if (options.force && !options.purge) {
+            for (const candidate of stale) {
+                const destination = quarantineBranch(workspaceRoot, candidate.path, candidate.branch);
+                console.log(`Quarantined ${candidate.branch}: ${destination}`);
             }
         }
-        else {
-            console.log(`Deleted ${deletedCount} stale branch KB(s)`);
+        if (options.purge) {
+            const purged = purgeQuarantine(workspaceRoot, retentionDays);
+            console.log(`Purged ${purged} quarantined branch store(s) older than ${retentionDays} day(s)`);
         }
         process.exitCode = 0;
     }

package/dist/commands/github-init.d.ts

@@ -0,0 +1,57 @@
+export declare const GITHUB_REPORT_WORKFLOW_RELPATH = ".github/workflows/kibi-report.yml";
+export declare const GITHUB_BADGE_WORKFLOW_RELPATH = ".github/workflows/kibi-badge.yml";
+export declare const GITHUB_PAGES_NAMESPACE = "kibi-report";
+export declare const KIBI_BADGE_ALT = "Kibi requirement health";
+export declare const KIBI_METRIC_DOCS_URL = "https://github.com/Looted/kibi/blob/develop/docs/github-integration.md#what-the-badge-means";
+export declare const PLACEHOLDER_OWNER = "OWNER";
+export declare const PLACEHOLDER_REPO = "REPOSITORY";
+export type GitHubRepo = Readonly<{
+    owner: string;
+    repo: string;
+}>;
+export type GitRemote = Readonly<{
+    name: string;
+    url: string;
+}>;
+export type GitHubPagesUrls = Readonly<{
+    siteUrl: string;
+    badgeUrl: string;
+}>;
+export type GitHubWorkflowKind = "report" | "badge";
+export type WorkflowWriteStatus = "created" | "unchanged" | "conflict";
+export type ReadmeWriteStatus = "updated" | "unchanged" | "printed" | "skipped-unknown-repo";
+export type GitIgnoreWriteStatus = "updated" | "unchanged";
+export type GitHubScaffoldOptions = Readonly<{
+    cwd: string;
+    badgeOnly: boolean;
+}>;
+export type GitHubInitDeps = Readonly<{
+    listRemotes?: (cwd: string) => GitRemote[];
+    log?: (message: string) => void;
+    error?: (message: string) => void;
+}>;
+export type GitHubScaffoldResult = Readonly<{
+    exitCode: number;
+    workflow: WorkflowWriteStatus;
+    readme: ReadmeWriteStatus;
+    gitignore: GitIgnoreWriteStatus;
+    repo: GitHubRepo | undefined;
+}>;
+export declare function githubTemplateDir(): string;
+export declare function githubWorkflowTemplateFileName(kind: GitHubWorkflowKind): string;
+export declare function loadGitHubWorkflowTemplate(kind: GitHubWorkflowKind): string;
+export declare function parseGitHubRemote(url: string): GitHubRepo | undefined;
+export declare function githubPagesUrls(repo: GitHubRepo): GitHubPagesUrls;
+export declare function formatKibiBadgeMarkdown(badgeUrl: string, linkUrl: string): string;
+export declare function placeholderPagesUrls(): GitHubPagesUrls;
+export declare function placeholderBadgeMarkdown(badgeOnly: boolean): string;
+export declare function hasKibiBadge(content: string): boolean;
+export declare function detectReadmePath(cwd: string): string | undefined;
+export declare function insertKibiBadge(content: string, badgeMarkdown: string): string;
+export declare function listGitRemotes(cwd: string): GitRemote[];
+export declare function resolveGitHubRepo(remotes: readonly GitRemote[]): GitHubRepo | undefined;
+export declare function writeGitHubWorkflow(cwd: string, kind: GitHubWorkflowKind, template: string): WorkflowWriteStatus;
+export declare function ensureKibiReportGitIgnore(cwd: string): GitIgnoreWriteStatus;
+export declare function scaffoldGitHubIntegration(options: GitHubScaffoldOptions, deps?: GitHubInitDeps): GitHubScaffoldResult;
+export declare function skipBlankLines(lines: readonly string[], start: number): number;
+//# sourceMappingURL=github-init.d.ts.map

package/dist/commands/github-init.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"github-init.d.ts","sourceRoot":"","sources":["../../src/commands/github-init.ts"],"names":[],"mappings":"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"}

package/dist/commands/github-init.js

@@ -0,0 +1,314 @@
+/*
+ Kibi — repo-local, per-branch, queryable long-term memory for software projects
+ Copyright (C) 2026 Piotr Franczyk
+
+ This program is free software: you can redistribute it and/or modify
+ it under the terms of the GNU Affero General Public License as published by
+ the Free Software Foundation, either version 3 of the License, or
+ (at your option) any later version.
+
+ This program is distributed in the hope that it will be useful,
+ but WITHOUT ANY WARRANTY; without even the implied warranty of
+ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ GNU Affero General Public License for more details.
+
+ You should have received a copy of the GNU Affero General Public License
+ along with this program.  If not, see <https://www.gnu.org/licenses/>.
+*/
+import { execFileSync } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+export const GITHUB_REPORT_WORKFLOW_RELPATH = ".github/workflows/kibi-report.yml";
+export const GITHUB_BADGE_WORKFLOW_RELPATH = ".github/workflows/kibi-badge.yml";
+export const GITHUB_PAGES_NAMESPACE = "kibi-report";
+export const KIBI_BADGE_ALT = "Kibi requirement health";
+export const KIBI_METRIC_DOCS_URL = "https://github.com/Looted/kibi/blob/develop/docs/github-integration.md#what-the-badge-means";
+export const PLACEHOLDER_OWNER = "OWNER";
+export const PLACEHOLDER_REPO = "REPOSITORY";
+const README_CANDIDATES = ["README.md", "readme.md", "Readme.md"];
+const BADGE_OR_IMAGE_LINE = /^\s*(?:\[!\[[^\]]*\]\([^)]+\)\]\([^)]+\)|!\[[^\]]*\]\([^)]+\))\s*$/;
+// implements REQ-kibi-github-report-integration
+export function githubTemplateDir() {
+    return path.resolve(__dirname, "..", "..", "templates", "github");
+}
+export function githubWorkflowTemplateFileName(kind) {
+    return kind === "badge" ? "kibi-badge.yml" : "kibi-report.yml";
+}
+export function loadGitHubWorkflowTemplate(kind) {
+    const templatePath = path.join(githubTemplateDir(), githubWorkflowTemplateFileName(kind));
+    if (!existsSync(templatePath)) {
+        throw new Error(`Kibi GitHub workflow template missing: ${templatePath}`);
+    }
+    return readFileSync(templatePath, "utf8");
+}
+export function parseGitHubRemote(url) {
+    const trimmed = url.trim();
+    if (trimmed.length === 0) {
+        return undefined;
+    }
+    const patterns = [
+        /^https?:\/\/(?:[^/@]+@)?(?:www\.)?github\.com\/([^/]+)\/([^/]+?)(?:\.git)?\/?$/i,
+        /^git@github\.com:([^/]+)\/([^/]+?)(?:\.git)?\/?$/i,
+        /^ssh:\/\/(?:git@)?github\.com(?::\d+)?\/([^/]+)\/([^/]+?)(?:\.git)?\/?$/i,
+        /^git:\/\/github\.com\/([^/]+)\/([^/]+?)(?:\.git)?\/?$/i,
+    ];
+    for (const pattern of patterns) {
+        const match = trimmed.match(pattern);
+        const owner = match?.[1];
+        const repoRaw = match?.[2];
+        if (!owner || !repoRaw) {
+            continue;
+        }
+        if (owner.includes(":") || repoRaw.includes(" ")) {
+            return undefined;
+        }
+        const repo = repoRaw.replace(/\.git$/i, "");
+        if (owner.length === 0 || repo.length === 0) {
+            return undefined;
+        }
+        return { owner, repo };
+    }
+    return undefined;
+}
+export function githubPagesUrls(repo) {
+    const owner = repo.owner.toLowerCase();
+    const name = repo.repo.toLowerCase();
+    const isUserSite = name === `${owner}.github.io`;
+    const origin = isUserSite
+        ? `https://${owner}.github.io/`
+        : `https://${owner}.github.io/${name}/`;
+    const siteUrl = `${origin}${GITHUB_PAGES_NAMESPACE}/`;
+    const badgeUrl = `${siteUrl}badge.svg`;
+    return { siteUrl, badgeUrl };
+}
+export function formatKibiBadgeMarkdown(badgeUrl, linkUrl) {
+    return `[![${KIBI_BADGE_ALT}](${badgeUrl})](${linkUrl})`;
+}
+export function placeholderPagesUrls() {
+    return {
+        siteUrl: `https://${PLACEHOLDER_OWNER}.github.io/${PLACEHOLDER_REPO}/${GITHUB_PAGES_NAMESPACE}/`,
+        badgeUrl: `https://${PLACEHOLDER_OWNER}.github.io/${PLACEHOLDER_REPO}/${GITHUB_PAGES_NAMESPACE}/badge.svg`,
+    };
+}
+export function placeholderBadgeMarkdown(badgeOnly) {
+    const urls = placeholderPagesUrls();
+    return formatKibiBadgeMarkdown(urls.badgeUrl, badgeOnly ? KIBI_METRIC_DOCS_URL : urls.siteUrl);
+}
+export function hasKibiBadge(content) {
+    return /\[!\[Kibi requirement health\]/i.test(content);
+}
+export function detectReadmePath(cwd) {
+    for (const name of README_CANDIDATES) {
+        const candidate = path.join(cwd, name);
+        if (existsSync(candidate)) {
+            return candidate;
+        }
+    }
+    return undefined;
+}
+export function insertKibiBadge(content, badgeMarkdown) {
+    const newline = content.includes("\r\n") ? "\r\n" : "\n";
+    const lines = content.split(/\r?\n/);
+    let h1Index = -1;
+    for (let index = 0; index < lines.length; index += 1) {
+        if (/^#\s+\S/.test(lines[index] ?? "")) {
+            h1Index = index;
+            break;
+        }
+    }
+    const clusterEnd = findBadgeClusterEnd(lines, h1Index >= 0 ? h1Index + 1 : 0);
+    if (h1Index >= 0) {
+        const insertAt = clusterEnd > h1Index + 1 ? clusterEnd : h1Index + 1;
+        return insertLine(lines, insertAt, badgeMarkdown, newline);
+    }
+    if (clusterEnd > 0) {
+        return insertLine(lines, clusterEnd, badgeMarkdown, newline);
+    }
+    if (content.length === 0) {
+        return `${badgeMarkdown}${newline}`;
+    }
+    return `${badgeMarkdown}${newline}${newline}${content}`;
+}
+export function listGitRemotes(cwd) {
+    try {
+        const output = execFileSync("git", ["-C", cwd, "remote", "-v"], {
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+        const remotes = [];
+        for (const line of output.split("\n")) {
+            const match = line.match(/^(\S+)\s+(\S+)\s+\(fetch\)$/);
+            if (match?.[1] && match[2]) {
+                remotes.push({ name: match[1], url: match[2] });
+            }
+        }
+        return remotes;
+    }
+    catch {
+        return [];
+    }
+}
+export function resolveGitHubRepo(remotes) {
+    const parsed = remotes
+        .map((remote) => ({ remote, repo: parseGitHubRemote(remote.url) }))
+        .filter((entry) => entry.repo !== undefined);
+    const origin = parsed.find((entry) => entry.remote.name === "origin");
+    return origin?.repo ?? parsed[0]?.repo;
+}
+export function writeGitHubWorkflow(cwd, kind, template) {
+    const relativePath = kind === "badge"
+        ? GITHUB_BADGE_WORKFLOW_RELPATH
+        : GITHUB_REPORT_WORKFLOW_RELPATH;
+    const dest = path.join(cwd, relativePath);
+    const normalizedTemplate = normalizeNewlines(template);
+    if (existsSync(dest)) {
+        const existing = normalizeNewlines(readFileSync(dest, "utf8"));
+        return existing === normalizedTemplate ? "unchanged" : "conflict";
+    }
+    mkdirSync(path.dirname(dest), { recursive: true });
+    writeFileSync(dest, normalizedTemplate);
+    return "created";
+}
+export function ensureKibiReportGitIgnore(cwd) {
+    const gitignorePath = path.join(cwd, ".gitignore");
+    const current = existsSync(gitignorePath)
+        ? readFileSync(gitignorePath, "utf8")
+        : "";
+    if (/(?:^|\n)kibi-report\/(?:\n|$)/.test(current)) {
+        return "unchanged";
+    }
+    const next = current
+        ? `${current.replace(/\s*$/, "")}\nkibi-report/\n`
+        : "kibi-report/\n";
+    writeFileSync(gitignorePath, next);
+    return "updated";
+}
+// implements REQ-kibi-github-report-integration
+export function scaffoldGitHubIntegration(options, deps = {}) {
+    const log = deps.log ?? ((message) => console.log(message));
+    const error = deps.error ?? ((message) => console.error(message));
+    const listRemotes = deps.listRemotes ?? listGitRemotes;
+    const kind = options.badgeOnly ? "badge" : "report";
+    const workflowPath = kind === "badge"
+        ? GITHUB_BADGE_WORKFLOW_RELPATH
+        : GITHUB_REPORT_WORKFLOW_RELPATH;
+    const siblingPath = kind === "badge"
+        ? GITHUB_REPORT_WORKFLOW_RELPATH
+        : GITHUB_BADGE_WORKFLOW_RELPATH;
+    const template = loadGitHubWorkflowTemplate(kind);
+    const workflow = writeGitHubWorkflow(options.cwd, kind, template);
+    const gitignore = ensureKibiReportGitIgnore(options.cwd);
+    const repo = resolveGitHubRepo(listRemotes(options.cwd));
+    if (existsSync(path.join(options.cwd, siblingPath))) {
+        error(`Warning: ${siblingPath} already exists. GitHub Pages can host one site; keep a single Kibi workflow.`);
+    }
+    if (workflow === "created") {
+        log(`✓ Added ${workflowPath}`);
+    }
+    else if (workflow === "unchanged") {
+        log(`✓ ${workflowPath} already configured`);
+    }
+    else {
+        error(`Warning: ${workflowPath} already exists and differs from the Kibi template.`);
+        error(`Left the existing file in place. Compare it with https://github.com/Looted/kibi/blob/develop/docs/examples/github/${githubWorkflowTemplateFileName(kind)}.`);
+    }
+    if (gitignore === "updated") {
+        log("✓ Added kibi-report/ to .gitignore");
+    }
+    const readme = updateReadmeBadge(options, repo, log, error);
+    log("");
+    log("Manual step required:");
+    log("GitHub → Settings → Pages → Source → GitHub Actions");
+    return {
+        exitCode: 0,
+        workflow,
+        readme,
+        gitignore,
+        repo,
+    };
+}
+function updateReadmeBadge(options, repo, log, error) {
+    const markdown = repo
+        ? formatKibiBadgeMarkdown(githubPagesUrls(repo).badgeUrl, options.badgeOnly
+            ? KIBI_METRIC_DOCS_URL
+            : githubPagesUrls(repo).siteUrl)
+        : placeholderBadgeMarkdown(options.badgeOnly);
+    const readmePath = detectReadmePath(options.cwd);
+    if (!repo) {
+        error("Warning: Could not determine a github.com owner/repository from git remotes.");
+        error("Did not invent a badge URL. Add this Markdown after replacing OWNER/REPOSITORY:");
+        log(markdown);
+        if (!readmePath) {
+            return "printed";
+        }
+        return "skipped-unknown-repo";
+    }
+    if (!readmePath) {
+        log("No README found. Add this badge Markdown manually:");
+        log(markdown);
+        return "printed";
+    }
+    const existing = readFileSync(readmePath, "utf8");
+    if (hasKibiBadge(existing)) {
+        log("✓ README already contains the Kibi requirement-health badge");
+        return "unchanged";
+    }
+    writeFileSync(readmePath, insertKibiBadge(existing, markdown));
+    log(`✓ Added Kibi requirement-health badge to ${path.basename(readmePath)}`);
+    return "updated";
+}
+function normalizeNewlines(value) {
+    const unix = value.replace(/\r\n/g, "\n");
+    return unix.endsWith("\n") ? unix : `${unix}\n`;
+}
+export function skipBlankLines(lines, start) {
+    let peek = start;
+    while (peek < lines.length && (lines[peek] ?? "").trim() === "") {
+        peek += 1;
+    }
+    return peek;
+}
+function findBadgeClusterEnd(lines, start) {
+    let index = start;
+    while (index < lines.length && (lines[index] ?? "").trim() === "") {
+        index += 1;
+    }
+    if (index >= lines.length || !BADGE_OR_IMAGE_LINE.test(lines[index] ?? "")) {
+        return start;
+    }
+    while (index < lines.length) {
+        const line = lines[index] ?? "";
+        if (BADGE_OR_IMAGE_LINE.test(line)) {
+            index += 1;
+            continue;
+        }
+        if (line.trim() === "") {
+            const peek = skipBlankLines(lines, index + 1);
+            if (peek < lines.length && BADGE_OR_IMAGE_LINE.test(lines[peek] ?? "")) {
+                index = peek;
+                continue;
+            }
+            break;
+        }
+        break;
+    }
+    return index;
+}
+function insertLine(lines, index, badgeMarkdown, newline) {
+    const before = lines.slice(0, index);
+    const after = lines.slice(index);
+    const prefixBlank = before.length === 0 || (before[before.length - 1] ?? "").trim() === ""
+        ? []
+        : [""];
+    const suffixBlank = after.length === 0 || (after[0] ?? "").trim() === "" ? [] : [""];
+    return [
+        ...before,
+        ...prefixBlank,
+        badgeMarkdown,
+        ...suffixBlank,
+        ...after,
+    ].join(newline);
+}

package/dist/commands/init-helpers.d.ts

@@ -1,6 +1,6 @@
 export declare function getCurrentBranch(cwd?: string): Promise<string>;
 export declare function createKbDirectoryStructure(kbDir: string, currentBranch: string): void;
-export declare function createConfigFile(kbDir: string): void;
+export declare function createManifestFile(kbDir: string): void;
 export declare function updateGitIgnore(cwd: string): void;
 export declare function ensureSymbolsManifestFile(cwd: string): void;
 export declare function copySchemaFiles(kbDir: string, schemaSourceDir: string): Promise<void>;

package/dist/commands/init-helpers.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"init-helpers.d.ts","sourceRoot":"","sources":["../../src/commands/init-helpers.ts"],"names":[],"mappings":"AAoGA,wBAAsB,gBAAgB,CACpC,GAAG,GAAE,MAAsB,GAC1B,OAAO,CAAC,MAAM,CAAC,CASjB;AAED,wBAAgB,0BAA0B,CACxC,KAAK,EAAE,MAAM,EACb,aAAa,EAAE,MAAM,GACpB,IAAI,CAQN;AAED,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAMpD;AAED,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAqBjD;AAGD,wBAAgB,yBAAyB,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAW3D;AAED,wBAAsB,eAAe,CACnC,KAAK,EAAE,MAAM,EACb,eAAe,EAAE,MAAM,GACtB,OAAO,CAAC,IAAI,CAAC,CAYf;AASD,wBAAgB,WAAW,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAkCnE;AAED,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAiBpD"}
+{"version":3,"file":"init-helpers.d.ts","sourceRoot":"","sources":["../../src/commands/init-helpers.ts"],"names":[],"mappings":"AAkIA,wBAAsB,gBAAgB,CACpC,GAAG,GAAE,MAAsB,GAC1B,OAAO,CAAC,MAAM,CAAC,CASjB;AAED,wBAAgB,0BAA0B,CACxC,KAAK,EAAE,MAAM,EACb,aAAa,EAAE,MAAM,GACpB,IAAI,CAUN;AAED,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAGtD;AAED,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CA6BjD;AAiDD,wBAAgB,yBAAyB,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAU3D;AAED,wBAAsB,eAAe,CACnC,KAAK,EAAE,MAAM,EACb,eAAe,EAAE,MAAM,GACtB,OAAO,CAAC,IAAI,CAAC,CAYf;AASD,wBAAgB,WAAW,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAkCnE;AAED,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAiBpD"}