akm-cli 0.9.0-beta.9 → 0.9.0-rc.0

package/dist/core/structured.js

@@ -0,0 +1,69 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// 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/.
+/**
+ * `runStructured<T>()` — transport-free structured-output core (P0.5 seam).
+ *
+ * akm has two structured-output paths that share no code: the LLM HTTP path
+ * (`llm/structured-call.ts` + `responseSchema`) and the agent JSON path
+ * (`agent/spawn.ts` `parseOutput: "json"` — embedded-JSON scan, no schema,
+ * no retry). This module is the ONE validation-driven retry loop both are
+ * meant to converge on: the workflow engine's schema units compose it with a
+ * dispatch adapter per runner (llm = `chatCompletion` + `responseSchema`;
+ * agent/sdk = `runAgent`/`runOpencodeSdk` + prompt-injected schema;
+ * native-schema CLIs pass the schema through and still validate).
+ *
+ * Layering: this file lives in `core/` — NOT `llm/` — because the agent path
+ * must be able to reach it and `agent/ ⇏ llm/` is an enforced invariant
+ * (`tests/architecture/agent-no-llm-sdk-guard.test.ts`). The transport is
+ * always injected; this module never performs IO of its own.
+ *
+ * Retry semantics: only parse/validation misses are retried (with corrective
+ * feedback appended to the re-dispatch). Transport errors PROPAGATE — the
+ * transports own their own retry discipline (`chatCompletion` has a bounded
+ * jittered retry; `runAgent` has timeout/abort semantics).
+ */
+import { parseEmbeddedJsonResponse } from "./parse.js";
+function defaultFeedback(failure) {
+    if (failure.reason === "parse_error") {
+        return "Your previous response contained no parseable JSON. Respond with ONLY a JSON value that matches the requested schema — no prose, no code fences.";
+    }
+    return `Your previous JSON response failed validation:\n- ${failure.errors.join("\n- ")}\nRespond again with ONLY a corrected JSON value.`;
+}
+/**
+ * Run the dispatch→parse→validate loop, re-dispatching with corrective
+ * feedback on parse/validation misses, up to `maxAttempts` total attempts.
+ * Never throws for structure problems (returns a typed failure); transport
+ * throws propagate untouched.
+ */
+export async function runStructured(options) {
+    const parse = options.parse ?? ((raw) => parseEmbeddedJsonResponse(raw));
+    const buildFeedback = options.buildFeedback ?? defaultFeedback;
+    const maxAttempts = Math.max(1, options.maxAttempts ?? 2);
+    let feedback;
+    let lastFailure;
+    for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+        const raw = await options.dispatch(feedback);
+        const candidate = parse(raw);
+        if (candidate === undefined) {
+            lastFailure = {
+                ok: false,
+                reason: "parse_error",
+                errors: ["no JSON structure found in response"],
+                attempts: attempt,
+                raw,
+            };
+            feedback = buildFeedback({ reason: "parse_error", errors: lastFailure.errors, raw });
+            continue;
+        }
+        const verdict = options.validate(candidate);
+        if (verdict.ok) {
+            return { ok: true, value: verdict.value, attempts: attempt };
+        }
+        lastFailure = { ok: false, reason: "validation_error", errors: verdict.errors, attempts: attempt, raw };
+        feedback = buildFeedback({ reason: "validation_error", errors: verdict.errors, raw });
+    }
+    // maxAttempts >= 1 guarantees at least one loop iteration set lastFailure
+    // (a success would have returned), so the non-null assertion is safe.
+    return lastFailure;
+}

package/dist/core/time.js

@@ -9,6 +9,59 @@
  * consistently without private re-implementations drifting apart.
  */
 import { UsageError } from "./errors.js";
+// ── Duration-shorthand parsing ───────────────────────────────────────────────
+const MINUTE_MS = 60 * 1000;
+const HOUR_MS = 60 * 60 * 1000;
+const DAY_MS = 24 * 60 * 60 * 1000;
+/** A month is approximated as 30 days — this shorthand is not calendar-exact. */
+const MONTH_MS = 30 * DAY_MS;
+/**
+ * Canonical duration-shorthand unit map shared by every `--since` / `--expires`
+ * / `--window-compare` consumer.
+ *
+ * The grammar is intentionally uniform across the whole CLI:
+ *   - `m` = MINUTES, `M` = MONTHS (30-day approximation)
+ *   - `h`/`H` = hours, `d`/`D` = days
+ *
+ * Matching is CASE-SENSITIVE (see {@link parseDuration}), which is what lets
+ * `m` and `M` mean different things. Historically `akm health --since` and
+ * `remember --expires` read a case-insensitive `m` as MONTHS while
+ * `consolidate` / `--window-compare` read it as MINUTES; that split is now
+ * resolved in favour of the conventional `m`=minutes, with `M` reserved for
+ * months. Upper-case `H`/`D` aliases are retained so specs that previously
+ * relied on the old case-insensitive parsers (e.g. `"7D"`) keep working.
+ */
+export const DURATION_UNITS = {
+    m: MINUTE_MS,
+    M: MONTH_MS,
+    h: HOUR_MS,
+    H: HOUR_MS,
+    d: DAY_MS,
+    D: DAY_MS,
+};
+/**
+ * Parse a compact duration shorthand (e.g. `"30d"`, `"12h"`, `"5m"`, `"3M"`)
+ * into a number of milliseconds using an explicit `units` map (default
+ * {@link DURATION_UNITS}), or return `null` when the input does not match
+ * `<digits><letter>` or the unit is not in the map.
+ *
+ * Matching is CASE-SENSITIVE against the map keys, so `m` (minutes) and `M`
+ * (months) are distinct — do NOT lower-case the spec before calling, or the
+ * two collapse. Amount is parsed with base-10 `parseInt`; `null` is returned
+ * rather than throwing so each caller keeps its own error/fallback policy.
+ */
+export function parseDuration(spec, units = DURATION_UNITS) {
+    const match = spec.trim().match(/^(\d+)([a-zA-Z])$/);
+    if (!match)
+        return null;
+    const amount = Number.parseInt(match[1] ?? "", 10);
+    if (!Number.isFinite(amount))
+        return null;
+    const multiplier = units[match[2] ?? ""];
+    if (multiplier === undefined)
+        return null;
+    return amount * multiplier;
+}
 // ── Since-flag parsing ───────────────────────────────────────────────────────
 /**
  * Parse a user-supplied `--since` value and return an ISO-8601 timestamp

package/dist/core/warn.js

@@ -17,6 +17,11 @@ import path from "node:path";
 let quiet = false;
 let verbose = false;
 let logFilePath;
+let sinkOverride;
+/** TEST-ONLY. Swap the output sink; pass undefined to restore real output. */
+export function _setWarnSinkForTests(fake) {
+    sinkOverride = fake;
+}
 export function setQuiet(value) {
     quiet = value;
 }
@@ -96,6 +101,10 @@ function appendToLogFile(level, args) {
  * Use for progress counters and status lines (replaces console.error used for progress).
  */
 export function info(...args) {
+    if (sinkOverride) {
+        sinkOverride("info", args);
+        return;
+    }
     appendToLogFile("INFO", args);
     if (!quiet) {
         console.warn(...args);
@@ -107,6 +116,10 @@ export function info(...args) {
  * Drop-in replacement for console.warn() across the codebase.
  */
 export function warn(...args) {
+    if (sinkOverride) {
+        sinkOverride("warn", args);
+        return;
+    }
     appendToLogFile("WARN", args);
     if (!quiet) {
         console.warn(...args);
@@ -118,6 +131,10 @@ export function warn(...args) {
  * Drop-in replacement for console.error() used for diagnostic failures.
  */
 export function error(...args) {
+    if (sinkOverride) {
+        sinkOverride("error", args);
+        return;
+    }
     appendToLogFile("ERROR", args);
     if (!quiet) {
         console.error(...args);
@@ -129,6 +146,10 @@ export function error(...args) {
  * default verbosity (e.g. registry-content workflow validation errors).
  */
 export function warnVerbose(...args) {
+    if (sinkOverride) {
+        sinkOverride("warnVerbose", args);
+        return;
+    }
     if (isVerbose()) {
         warn(...args);
     }

package/dist/core/write-source.js

@@ -30,6 +30,7 @@ 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";
+import { warn } from "./warn.js";
 /**
  * Source kinds that the loader is allowed to mark `writable: true`. Anything
  * else is rejected at config load (per locked decision 4) — see
@@ -80,6 +81,34 @@ export function sanitizeCommitMessage(input) {
     }
     return out;
 }
+// ── Portability advisory (review 13, D1) ────────────────────────────────────
+/**
+ * Matches an absolute host **home** path — `/home/<user>` or `/Users/<user>` —
+ * requiring at least one user segment after the prefix. A bare `/home/` or
+ * `/Users/` (no user segment) does NOT match. The user segment stops at the
+ * first path separator, whitespace, or common delimiter so we capture just the
+ * `/home/<user>` prefix rather than the whole path.
+ *
+ * Deliberately conservative: it does not exempt fenced code blocks, so content
+ * that legitimately *documents* a system path (e.g. a tutorial) can produce a
+ * false positive. That is accepted — the advisory is non-fatal and correctness
+ * (never missing a real leak) is preferred over cleverness here.
+ */
+const ABSOLUTE_HOME_PATH_RE = /\/(?:home|Users)\/[^\s/"'`)\]}<>|:;,]+/g;
+/**
+ * Return the distinct `/home/<user>` / `/Users/<user>` prefixes embedded in
+ * `content`, in first-seen order. Empty when the content is portable.
+ *
+ * Used by {@link writeAssetToSource} to emit a write-time advisory: absolute
+ * host home paths make the stash non-portable and leak the local username.
+ */
+export function findAbsoluteHomePaths(content) {
+    const seen = new Set();
+    for (const match of content.matchAll(ABSOLUTE_HOME_PATH_RE)) {
+        seen.add(match[0]);
+    }
+    return [...seen];
+}
 // ── Public helpers ──────────────────────────────────────────────────────────
 /**
  * Resolve the effective `writable` flag for a source config entry, applying
@@ -132,6 +161,14 @@ export async function writeAssetToSource(source, config, ref, content) {
     fs.mkdirSync(path.dirname(filePath), { recursive: true });
     const normalized = content.endsWith("\n") ? content : `${content}\n`;
     fs.writeFileSync(filePath, normalized, "utf8");
+    // Non-fatal portability advisory (review 13, D1): flag absolute host home
+    // paths in the written content. These make the stash non-portable and leak
+    // the local username. We warn AFTER the write so the advisory never blocks it.
+    const hostPaths = findAbsoluteHomePaths(normalized);
+    if (hostPaths.length > 0) {
+        warn(`warning: asset "${formatRefForMessage(ref)}" embeds absolute host path(s): ${hostPaths.join(", ")}. ` +
+            "These make the stash non-portable and leak the local username — prefer $HOME or ~ relative references.");
+    }
     return { path: filePath, ref: makeAssetRef(ref.type, ref.name, ref.origin) };
 }
 /**