akm-cli 0.8.3 → 0.9.0-beta.1

package/dist/core/text-truncation.js

@@ -105,3 +105,151 @@ export function detectTruncatedDescription(description) {
     }
     return null;
 }
+// ── Post-generation repair pass (issue #556) ─────────────────────────────────
+/**
+ * Minimum length (chars) for a repaired description to be considered usable.
+ * Mirrors the floor in `isValidDescription` (≥20). Kept local so this module
+ * stays dependency-free of the validators (avoids an import cycle).
+ */
+const MIN_REPAIRED_DESCRIPTION_LEN = 20;
+/** Maximum length (chars) for a repaired description. Mirrors `isValidDescription` (≤400). */
+const MAX_REPAIRED_DESCRIPTION_LEN = 400;
+/**
+ * Strip trailing truncation fragments from a candidate clause: repeatedly drop
+ * a hanging-connector word and/or trailing `,` `;` `:` `+` and ellipses until
+ * the clause no longer looks truncated. PURE — no fabrication, only removal.
+ *
+ * Returns the trimmed-to-last-complete-token clause (may be empty if the whole
+ * thing was connectors/punctuation).
+ */
+function stripTrailingTruncationFragment(clause) {
+    let s = clause.trim();
+    // Loop because a tail can stack: "… related to the" → drop "the" → drop "to".
+    for (let guard = 0; guard < 64; guard++) {
+        const before = s;
+        // Drop trailing ellipsis / connector-only punctuation+operators.
+        s = s.replace(/\s*(\.{3,}|…)$/u, "").trim();
+        s = s.replace(/\s*[,;:+]+$/u, "").trim();
+        // Drop a trailing hanging-connector word (and any punctuation glued to it).
+        const m = s.match(/(?:^|\s)([A-Za-z']+)[.!?]*$/u);
+        if (m) {
+            const word = (m[1] ?? "").toLowerCase();
+            if (TRUNCATION_TRAILING_WORDS.has(word)) {
+                // Remove just the final word token (keep preceding text).
+                s = s.slice(0, s.length - m[0].length).trim();
+            }
+        }
+        if (s === before)
+            break;
+    }
+    return s;
+}
+/**
+ * Split prose into sentences on `.`/`!`/`?` boundaries (followed by whitespace
+ * or end). Keeps the terminating punctuation. Deliberately simple — good enough
+ * for the short, single-paragraph descriptions/bodies this repair operates on.
+ */
+function splitSentences(text) {
+    const out = [];
+    for (const match of text.matchAll(/[^.!?]+[.!?]+(?=\s|$)|[^.!?]+$/gu)) {
+        const s = match[0].trim();
+        if (s)
+            out.push(s);
+    }
+    return out;
+}
+/**
+ * True when `candidate` is a self-contained, non-truncated clause of acceptable
+ * length. Used to gate repair outputs without importing the full validator
+ * (which would create a cycle). The full `isValidDescription` still runs
+ * downstream — this is only the truncation/length subset the repair targets.
+ */
+function isUsableClause(candidate) {
+    const c = candidate.trim();
+    if (c.length < MIN_REPAIRED_DESCRIPTION_LEN)
+        return false;
+    if (c.length > MAX_REPAIRED_DESCRIPTION_LEN)
+        return false;
+    if (detectTruncatedDescription(c) !== null)
+        return false;
+    // Must contain at least one word character (not pure punctuation).
+    if (!/[A-Za-z0-9]/.test(c))
+        return false;
+    return true;
+}
+/** Append a period when the clause lacks terminal sentence punctuation. PURE. */
+function ensureTerminalPunctuation(clause) {
+    const c = clause.trim();
+    if (/[.!?]$/.test(c))
+        return c;
+    return `${c}.`;
+}
+/**
+ * Deterministically repair an LLM-generated description that was sliced
+ * mid-sentence (issue #556). The repair NEVER fabricates new claims:
+ *
+ *   1. If the description is not truncated, it is returned **byte-identical**
+ *      (zero behaviour change for already-valid descriptions).
+ *   2. Otherwise:
+ *      a. **trim-to-last-complete-clause** — strip the trailing
+ *         truncation-indicator word(s)/punctuation; if a complete earlier
+ *         sentence survives, use the longest non-truncated prefix.
+ *      b. **swap-in first body sentence** — if (a) yields nothing usable and a
+ *         `body` is provided, use the first clean, complete sentence of the
+ *         body.
+ *      c. **fallback** — if neither produces a usable, non-truncated clause,
+ *         return the original string unchanged so the existing validation
+ *         rejects it exactly as before (no regression, no fabrication).
+ *
+ * @param description The raw description (possibly truncated).
+ * @param body Optional asset body to source a clean completion sentence from.
+ */
+export function repairTruncatedDescription(description, body) {
+    if (typeof description !== "string")
+        return description;
+    // Guarantee: untruncated input passes through byte-identical.
+    if (detectTruncatedDescription(description) === null)
+        return description;
+    const trimmed = description.trim();
+    // (a) trim-to-last-complete-clause.
+    // First, try the whole string with its trailing fragment stripped.
+    const stripped = stripTrailingTruncationFragment(trimmed);
+    if (isUsableClause(stripped)) {
+        return ensureTerminalPunctuation(stripped);
+    }
+    // If the description has multiple sentences, the truncation is in the last
+    // one — fall back to the longest leading run of complete sentences.
+    const sentences = splitSentences(trimmed);
+    if (sentences.length > 1) {
+        for (let take = sentences.length - 1; take >= 1; take--) {
+            const prefix = sentences.slice(0, take).join(" ").trim();
+            const cleaned = stripTrailingTruncationFragment(prefix);
+            if (isUsableClause(cleaned))
+                return ensureTerminalPunctuation(cleaned);
+        }
+    }
+    // (b) swap-in first clean, complete body sentence.
+    if (typeof body === "string" && body.trim().length > 0) {
+        const bodyText = body
+            .replace(/^---\r?\n[\s\S]*?\r?\n---\r?\n?/, "") // drop any frontmatter
+            .replace(/```[\s\S]*?```/g, " ") // drop fenced code
+            .replace(/`[^`]*`/g, " "); // drop inline code spans
+        for (const rawLine of bodyText.split(/\n/)) {
+            const line = rawLine
+                .replace(/\*\*([^*]+)\*\*/g, "$1")
+                .replace(/\*([^*]+)\*/g, "$1")
+                .replace(/^[#*\->_\s]+/, "")
+                .trim();
+            if (!line)
+                continue;
+            if (/^[a-z_]+:\s/i.test(line))
+                continue; // skip yaml-ish leak lines
+            for (const sentence of splitSentences(line)) {
+                if (isUsableClause(sentence))
+                    return ensureTerminalPunctuation(sentence);
+            }
+        }
+    }
+    // (c) fallback: return original unchanged — validation rejects as before.
+    return description;
+}

package/dist/core/time.js

@@ -8,7 +8,7 @@
  * interpret the same set of formats (ISO-8601, epoch ms, plain date strings)
  * consistently without private re-implementations drifting apart.
  */
-import { UsageError } from "./errors";
+import { UsageError } from "./errors.js";
 // ── Since-flag parsing ───────────────────────────────────────────────────────
 /**
  * Parse a user-supplied `--since` value and return an ISO-8601 timestamp

package/dist/core/write-source.js

@@ -2,31 +2,34 @@
 // License, v. 2.0. If a copy of the MPL was not distributed with this
 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
 /**
- * write-source — the only place in the codebase that branches on `source.kind`.
+ * write-source — the command-layer helper that performs asset writes.
  *
- * v1 architecture spec §2.6 / §2.7 / §10 step 5: writing to a source is *not*
- * a SourceProvider interface concern. It's a small command-layer helper that
- * does a plain filesystem write, plus a git-specific commit (and optional
- * push) when the source is backed by a git working tree.
+ * v1 architecture spec §2.6 / §2.7 / §10 step 5 (amended for 0.9.0): writing to
+ * a source is *not* a SourceProvider interface concern. It's a small
+ * command-layer helper that does a plain filesystem write for **every** kind.
  *
- * If a third kind ever needs special write handling, it gets added here. For
- * v1 there are exactly two cases. Adding more parallel scoring systems for
- * different provider kinds is explicitly disallowed by CLAUDE.md.
+ * 0.9.0 amendment (issue #507): the per-asset git commit/push path is retired.
+ * `writeAssetToSource` / `deleteAssetFromSource` no longer branch on `kind` for
+ * commit behaviour — they only ever touch the filesystem. Git-backed targets
+ * are committed in a SINGLE batch at the operation boundary via
+ * {@link commitWriteTargetBoundary} (which delegates to `saveGitStash`). This
+ * stages `.akm/` + sibling assets together as one complete commit instead of
+ * one noisy, incomplete commit per asset.
  *
- * This module is the **single dispatch point** for `kind`-branching write
- * logic. Callers (remember, import, source-add, etc.) MUST go through
- * `writeAssetToSource` / `deleteAssetFromSource` rather than re-inlining the
- * filesystem-write + git-commit dance.
+ * This module is still the **single dispatch point** for write/delete: callers
+ * (remember, import, source-add, etc.) MUST go through `writeAssetToSource` /
+ * `deleteAssetFromSource` rather than re-inlining a filesystem write, and they
+ * fire {@link commitWriteTargetBoundary} once after a batch of mutations to a
+ * writable git target.
  */
-import { spawnSync } from "node:child_process";
 import fs from "node:fs";
 import path from "node:path";
-import { getCachePaths, parseGitRepoUrl } from "../sources/providers/git";
-import { makeAssetRef } from "./asset-ref";
-import { resolveAssetPathFromName, TYPE_DIRS } from "./asset-spec";
-import { isWithin, resolveStashDir } from "./common";
-import { resolveConfiguredSources } from "./config";
-import { ConfigError, UsageError } from "./errors";
+import { getCachePaths, parseGitRepoUrl, saveGitStash } from "../sources/providers/git.js";
+import { makeAssetRef } from "./asset/asset-ref.js";
+import { resolveAssetPathFromName, TYPE_DIRS } from "./asset/asset-spec.js";
+import { isWithin, resolveStashDir } from "./common.js";
+import { resolveConfiguredSources } from "./config/config.js";
+import { ConfigError, UsageError } from "./errors.js";
 /**
  * Source kinds that the loader is allowed to mark `writable: true`. Anything
  * else is rejected at config load (per locked decision 4) — see
@@ -114,41 +117,91 @@ export function assertWritableAllowedForKind(entry) {
  * `ref`. Always:
  *
  *   1. Refuses if `config.writable` is not truthy (per §5.4).
- *   2. Performs a plain filesystem write to `path.join(source.path, …)`.
+ *   2. Rejects unsupported kinds (anything but `filesystem` / `git`).
+ *   3. Performs a plain filesystem write to `path.join(source.path, …)`.
  *
- * For sources of `kind === "git"`, additionally:
- *
- *   3. `git -C <path> add <file>`
- *   4. `git -C <path> commit -m "Update <ref>"`
- *   5. `git -C <path> push` when `config.options.pushOnCommit` is truthy.
- *
- * Any other `kind` reaching this helper is a configuration bug — the loader
- * rejects unsupported writable kinds — so we throw {@link ConfigError}.
+ * No commit runs here — for **every** kind. Git-backed targets are committed in
+ * one batch at the operation boundary via {@link commitWriteTargetBoundary}
+ * (0.9.0 amendment, issue #507). The caller fires that boundary commit once
+ * after a batch of mutations to a writable git target.
  */
 export async function writeAssetToSource(source, config, ref, content) {
     ensureWritable(source, config);
+    assertSupportedKind(source);
     const filePath = resolveAssetFilePath(source, ref);
     fs.mkdirSync(path.dirname(filePath), { recursive: true });
     const normalized = content.endsWith("\n") ? content : `${content}\n`;
     fs.writeFileSync(filePath, normalized, "utf8");
-    await runKindSpecificCommit(source, config, filePath, `Update ${formatRefForMessage(ref)}`);
     return { path: filePath, ref: makeAssetRef(ref.type, ref.name, ref.origin) };
 }
 /**
  * Delete the asset at `ref` from `source`. Symmetric to
- * {@link writeAssetToSource}: same writable check, same git-commit-and-push
- * convenience for `kind === "git"`.
+ * {@link writeAssetToSource}: same writable check, same unsupported-kind guard,
+ * a plain `unlink` with no commit. Git-backed targets are committed once at the
+ * operation boundary via {@link commitWriteTargetBoundary}.
  */
 export async function deleteAssetFromSource(source, config, ref) {
     ensureWritable(source, config);
+    assertSupportedKind(source);
     const filePath = resolveAssetFilePath(source, ref);
     if (!fs.existsSync(filePath)) {
         throw new UsageError(`Asset "${formatRefForMessage(ref)}" not found in source "${source.name}" (expected at ${filePath}).`, "MISSING_REQUIRED_ARGUMENT");
     }
     fs.unlinkSync(filePath);
-    await runKindSpecificCommit(source, config, filePath, `Remove ${formatRefForMessage(ref)}`);
     return { path: filePath, ref: makeAssetRef(ref.type, ref.name, ref.origin) };
 }
+/**
+ * Fire the one-shot batch-at-boundary commit for a resolved write target.
+ *
+ * 0.9.0 (issue #507): replaces the retired per-asset git commit. Callers invoke
+ * this EXACTLY ONCE after a batch of writes/deletes to a resolved write target.
+ * It is a no-op for any non-git target (plain filesystem sources and the
+ * primary stash stay non-committing here — the primary stash is committed by
+ * the existing improve auto-sync boundary).
+ *
+ * For a git target it delegates to `saveGitStash(name, message, writable, …)`,
+ * which stages `.akm/` + sibling assets together (`git add -A`), commits once,
+ * and pushes when the target is writable, has a remote, and `push !== false`.
+ *
+ * The push intent honours a deprecated `options.pushOnCommit` on the source
+ * config (mapped onto the batch push gate) when `push` is not explicitly set.
+ */
+export function commitWriteTargetBoundary(target, message, options) {
+    if (target.source.kind !== "git")
+        return;
+    warnIfPushOnCommit(target.config);
+    // Map the deprecated per-asset `pushOnCommit` intent onto the batch push gate
+    // when the caller did not pass an explicit push toggle. `saveGitStash` still
+    // gates the actual push on writable + remote, so this only ever opts *in*.
+    const push = options?.push ?? (target.config.options?.pushOnCommit === true ? true : undefined);
+    const writable = resolveWritable(target.config);
+    // Commit against the already-resolved repo directory (target.source.path)
+    // rather than re-resolving the stash by name through config. The write helper
+    // resolved this exact path; the boundary commit must operate on the SAME
+    // directory so the staged batch matches what was just written.
+    saveGitStash(undefined, message, writable, {
+        repoDir: target.source.path,
+        ...(push === undefined ? {} : { push }),
+    });
+}
+/**
+ * Emit a one-time deprecation warning the first time a source config carrying
+ * `options.pushOnCommit` is encountered. The field still parses (for old
+ * configs) but its per-asset push-on-commit behaviour is retired; its intent is
+ * now honoured via the batch push gate (writable + remote + push toggle).
+ */
+let pushOnCommitWarned = false;
+function warnIfPushOnCommit(config) {
+    if (config.options?.pushOnCommit === undefined)
+        return;
+    if (pushOnCommitWarned)
+        return;
+    pushOnCommitWarned = true;
+    const label = config.name ? ` on source "${config.name}"` : "";
+    process.stderr.write(`warning: \`options.pushOnCommit\`${label} is deprecated (0.9.0) and no longer commits per asset. ` +
+        "akm now commits writes in a single batch at the operation boundary and pushes when the target is " +
+        "writable with a remote. Remove the option or rely on sync push instead.\n");
+}
 /**
  * Resolve the destination for a write per locked decision 3:
  *
@@ -201,12 +254,10 @@ export function resolveWriteTarget(akmConfig, explicitTarget) {
     //
     // The primary stash stays `kind: "filesystem"` on purpose, even when it is a
     // git repo on disk (recognized elsewhere via isGitBackedStash). Returning
-    // `kind: "git"` here would route every asset write through the per-asset
-    // runGitCommit, which is INCOMPLETE (stages only the single asset file,
-    // leaving .akm/proposals + other state dirty) and NOISY (one commit per
-    // asset, ~25 per improve run). Recognition is decoupled: per-write stays
-    // non-committing, and the primary stash is committed in a single batch at
-    // operation boundaries (e.g. the end-of-run improve auto-sync via saveGitStash).
+    // `kind: "git"` here would fire the boundary commit on every write through
+    // this resolver, double-committing the primary stash which is already
+    // committed in a single batch at operation boundaries (e.g. the end-of-run
+    // improve auto-sync via saveGitStash). Per-write stays non-committing.
     try {
         const stashDir = resolveStashDir({ readOnly: true });
         return {
@@ -241,57 +292,19 @@ function resolveAssetFilePath(source, ref) {
     }
     return assetPath;
 }
-async function runKindSpecificCommit(source, config, filePath, message) {
-    if (source.kind === "filesystem") {
-        return; // No commit step.
-    }
-    if (source.kind === "git") {
-        runGitCommit(source.path, filePath, message);
-        if (config.options?.pushOnCommit) {
-            runGitPush(source.path);
-        }
+/**
+ * Reject any kind reaching the write/delete helpers other than the two
+ * supported writable kinds. The config loader is the first line of defence
+ * (assertWritableAllowedForKind), but we throw here so external callers that
+ * bypass the loader still get a clear error.
+ */
+function assertSupportedKind(source) {
+    if (source.kind === "filesystem" || source.kind === "git")
         return;
-    }
-    // Reject any other kind reaching the helper. The config loader is the
-    // first line of defence (assertWritableAllowedForKind), but we throw here
-    // so external callers that bypass the loader still get a clear error.
     throw new ConfigError(`write-source: unsupported kind "${source.kind}" for source "${source.name}". ` +
         "Writes are only defined for `filesystem` and `git` sources.", "INVALID_CONFIG_FILE", 'Set `kind: "filesystem"` (or `kind: "git"`) on the source, or add a parallel filesystem entry.');
 }
-function runGitCommit(repoDir, filePath, message) {
-    // Stage the specific file rather than `add -A` so unrelated working-tree
-    // changes don't get folded into the asset commit.
-    const relPath = path.relative(repoDir, filePath) || filePath;
-    const addResult = spawnSync("git", ["-C", repoDir, "add", "--", relPath], { encoding: "utf8" });
-    if (addResult.status !== 0) {
-        throw new Error(`git add failed: ${addResult.stderr?.trim() || "unknown error"}`);
-    }
-    // Defense in depth: sanitize the commit subject one more time at the spawn
-    // boundary. Callers should already pass sanitized strings (via
-    // formatRefForMessage / saveGitStash), but this guards against future
-    // refactors that forget. Empty after sanitize falls back to a safe stub.
-    const safeMessage = sanitizeCommitMessage(message) || "akm update";
-    // Provide a fallback identity so fresh CI/test environments without
-    // user.name/user.email configured can always commit.
-    const commitResult = spawnSync("git", ["-C", repoDir, "-c", "user.name=akm", "-c", "user.email=akm@local", "commit", "-m", safeMessage], { encoding: "utf8" });
-    if (commitResult.status !== 0) {
-        // `nothing to commit` is a no-op success — the file may have matched the
-        // existing tree exactly. Surface other errors verbatim.
-        const stderr = commitResult.stderr ?? "";
-        if (/nothing to commit|no changes added/i.test(stderr) ||
-            /nothing to commit|no changes added/i.test(commitResult.stdout ?? "")) {
-            return;
-        }
-        throw new Error(`git commit failed: ${stderr.trim() || "unknown error"}`);
-    }
-}
-function runGitPush(repoDir) {
-    const pushResult = spawnSync("git", ["-C", repoDir, "push"], { encoding: "utf8", timeout: 120_000 });
-    if (pushResult.status !== 0) {
-        throw new Error(`git push failed: ${pushResult.stderr?.trim() || "unknown error"}`);
-    }
-}
-function formatRefForMessage(ref) {
+export function formatRefForMessage(ref) {
     // Sanitize each component independently. `ref.origin` originates from user
     // config and could contain CR/LF that would otherwise be smuggled into the
     // commit subject and forge trailers downstream. `ref.type` and `ref.name`

package/dist/indexer/{db-backup.js → db/db-backup.js}

@@ -4,7 +4,7 @@
 /**
  * MVP data-directory backup for AKM.
  *
- * The DB upgrade path in `src/indexer/db.ts` `handleVersionUpgrade()` is
+ * The DB upgrade path in `src/indexer/db/db.ts` `handleVersionUpgrade()` is
  * intentionally destructive: when `DB_VERSION` bumps and a stored DB is at an
  * older version, ~17 tables are dropped and recreated. Until 0.9.0 ships a
  * full migration framework, this MVP captures a recursive copy of the entire
@@ -27,7 +27,8 @@
  */
 import fs from "node:fs";
 import path from "node:path";
-import { warn } from "../core/warn";
+import { bestEffort } from "../../core/best-effort.js";
+import { warn } from "../../core/warn.js";
 /** Default reason recorded for backups that don't override it. */
 export const DEFAULT_BACKUP_REASON = "version-upgrade";
 /** Reason recorded for backups taken before the embedding-dim drop path. */
@@ -95,12 +96,9 @@ export function measureDataDirSize(dirPath) {
                 stack.push(full);
             }
             else if (entry.isFile()) {
-                try {
+                bestEffort(() => {
                     total += fs.statSync(full).size;
-                }
-                catch {
-                    // File vanished between readdir and stat — ignore.
-                }
+                }, "file vanished between readdir and stat");
             }
         }
     }
@@ -154,7 +152,7 @@ export function listBackups(dataDir) {
         let sizeBytes;
         let reason = DEFAULT_BACKUP_REASON;
         if (fs.existsSync(metaPath)) {
-            try {
+            bestEffort(() => {
                 const raw = fs.readFileSync(metaPath, "utf8");
                 const parsed = JSON.parse(raw);
                 if (typeof parsed.createdAt === "string")
@@ -167,10 +165,7 @@ export function listBackups(dataDir) {
                     sizeBytes = parsed.sizeBytes;
                 if (typeof parsed.reason === "string" && parsed.reason.length > 0)
                     reason = parsed.reason;
-            }
-            catch {
-                // Malformed metadata — fall back to filesystem-derived values.
-            }
+            }, "malformed backup metadata — fall back to filesystem-derived values");
         }
         if (!createdAt) {
             try {
@@ -286,12 +281,7 @@ export function backupDataDir(opts) {
     catch (err) {
         warn("[akm] data dir backup failed — %s; upgrade will proceed without a snapshot", err instanceof Error ? err.message : String(err));
         // Best-effort cleanup of the partial copy so we don't litter the data dir.
-        try {
-            fs.rmSync(finalDest, { recursive: true, force: true });
-        }
-        catch {
-            /* ignore */
-        }
+        bestEffort(() => fs.rmSync(finalDest, { recursive: true, force: true }), "cleanup partial backup copy");
         return null;
     }
     const createdAt = now.toISOString();
@@ -369,12 +359,7 @@ function copyDataDirExcludingBackups(srcRoot, destRoot) {
                 // dir occasionally carries symlinked source roots; following them
                 // could explode the backup size unexpectedly.
                 const target = fs.readlinkSync(srcPath);
-                try {
-                    fs.symlinkSync(target, destPath);
-                }
-                catch {
-                    /* ignore — symlink creation can fail on Windows without admin */
-                }
+                bestEffort(() => fs.symlinkSync(target, destPath), "symlink creation can fail on Windows without admin");
             }
             // Other entry types (block/character/fifo/socket) are silently skipped.
         }