akm-cli 0.10.261008-beta → 0.10.261010-beta

package/dist/commands/ui/api.js

@@ -2,8 +2,8 @@
 // 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/.
 /**
- * The read-only JSON API behind `akm ui`. (The three proposal writes live in
- * `proposal-actions.ts`; nothing in this file writes.) Every handler calls the function the
+ * The read-only JSON API behind `akm ui`. Explicit writes live in
+ * `proposal-actions.ts` and `workspace-actions.ts`; nothing in this file writes. Every handler calls the function the
  * matching CLI command renders (`akmHealth`, `akmMetrics`, `akmSearch`,
  * `akmShowUnified`, the proposal repository, ...), so the UI and the CLI never
  * disagree and there is no second data layer. Documented in
@@ -14,8 +14,11 @@
  * `readOnly` (no usage events, no index build), and git is only queried.
  */
 import fs from "node:fs";
+import path from "node:path";
 import { parsePositiveIntFlag } from "../../cli/parse-args.js";
 import { parseBundleRef } from "../../core/asset/asset-ref.js";
+import { parseMarkdownToc, uniqueHeadingSlugs } from "../../core/asset/markdown.js";
+import { markdownLinkTargets } from "../../core/asset/markdown-link-targets.js";
 import { typeNameFromConceptId } from "../../core/asset/resolve-ref.js";
 import { resolveStashDir } from "../../core/common.js";
 import { getConfigValueSource, loadConfig } from "../../core/config/config.js";
@@ -24,6 +27,7 @@ import { getConfigPath, getDataDir, getDbPath } from "../../core/paths.js";
 import { getStateDbPath, listPendingStateMigrations } from "../../core/state-db.js";
 import { DURATION_UNITS, parseDuration } from "../../core/time.js";
 import { resolveWriteTarget } from "../../core/write-source.js";
+import { findSourceForPath, resolveSourceEntries } from "../../indexer/search/search-source.js";
 import { openDatabase } from "../../storage/database.js";
 import { listRecentImproveRuns } from "../../storage/repositories/improve-runs-repository.js";
 import { closeDatabase, openReadonlyExistingDatabase } from "../../storage/repositories/index-connection.js";
@@ -40,11 +44,12 @@ import { akmMetrics } from "../metrics/metrics-cli.js";
 import { isRetireProposal, proposalWaitingSince } from "../proposal/proposal-types.js";
 import { diffLoadedProposal, resolveProposalIdIn } from "../proposal/repository.js";
 import { validateProposal } from "../proposal/validators/proposals.js";
-import { akmSearch } from "../read/search.js";
+import { akmSearch, normalizeScopeFilters, parseBeliefFilterMode } from "../read/search.js";
 import { akmShowUnified } from "../read/show.js";
 import { assembleInfo } from "../sources/info.js";
 import { akmListSources } from "../sources/installed-stashes.js";
-import { readBundleGitStatus, readRecentCommits } from "./git-read.js";
+import { readDocumentSource } from "./document-source.js";
+import { readBundleGitStatus, readFileRevision, readRecentCommits } from "./git-read.js";
 import { isSecretEnvName, redactForUi } from "./redact.js";
 const DEFAULT_LIST_LIMIT = 50;
 const MAX_LIST_LIMIT = 200;
@@ -236,6 +241,13 @@ async function bundles() {
         source: source.source,
         path: source.path ?? null,
         writable: source.writable,
+        enabled: config.bundles?.[source.name]?.enabled !== false,
+        writableSetting: config.bundles?.[source.name]?.writable,
+        components: source.components.map((component) => ({
+            ...component,
+            configured: !!config.bundles?.[source.name]?.components?.[component.name],
+        })),
+        settingsSource: configSource(["bundles", source.name]),
         version: source.version ?? null,
         exists: source.status.exists,
         itemCount: source.itemCount,
@@ -475,6 +487,8 @@ async function search(query) {
         limit: limitParam(query, 20),
         // `--from <name>` narrows to one configured bundle; absent means every local bundle, as `akm search` does.
         source: bundle ?? "local",
+        belief: parseBeliefFilterMode(query.get("belief") || "current"),
+        filters: normalizeScopeFilters(Object.fromEntries(["user", "agent", "run", "channel"].map((key) => [key, query.get(`scope_${key}`) ?? ""]))),
         readOnly: true,
     });
 }
@@ -528,7 +542,81 @@ async function asset(query) {
     }
     const shown = await akmShowUnified({ ref, readOnly: true });
     const durableRef = shown.path ? durableRefForPath(shown.path) : null;
-    return { redacted: false, durableRef, asset: shown, feedback: feedbackFor(durableRef) };
+    const content = shown.content ?? "";
+    const headings = parseMarkdownToc(content).headings;
+    const slugs = uniqueHeadingSlugs(headings);
+    const links = {};
+    if (shown.path && durableRef) {
+        const owner = parseBundleRef(durableRef).bundle;
+        const db = openReadonlyExistingDatabase(getDbPath());
+        if (db) {
+            try {
+                for (const raw of markdownLinkTargets(content, false)) {
+                    if (/^(?:[a-z][a-z0-9+.-]*:|\/\/|#)/i.test(raw))
+                        continue;
+                    const [file, fragment] = raw.split("#", 2);
+                    if (!file?.toLowerCase().endsWith(".md") || file.startsWith("/"))
+                        continue;
+                    let decoded;
+                    try {
+                        decoded = decodeURIComponent(file);
+                    }
+                    catch {
+                        continue;
+                    }
+                    const id = getEntryIdByFilePath(db, path.resolve(path.dirname(shown.path), decoded));
+                    const target = id === undefined ? undefined : getItemRefById(db, id);
+                    if (target && parseBundleRef(target).bundle === owner)
+                        links[raw] = target + (fragment ? `#${fragment}` : "");
+                }
+            }
+            finally {
+                closeDatabase(db);
+            }
+        }
+    }
+    return {
+        redacted: false,
+        durableRef,
+        bundle: durableRef ? parseBundleRef(durableRef).bundle : null,
+        asset: shown,
+        feedback: feedbackFor(durableRef),
+        feedbackRequireReason: loadConfig().feedback?.requireReason !== false,
+        links,
+        headings: headings.map((heading, i) => ({ ...heading, slug: slugs[i] })),
+    };
+}
+async function assetHistory(query) {
+    const selected = await asset(query);
+    if (selected.redacted || !selected.asset?.path)
+        return { available: false, commits: [] };
+    const source = findSourceForPath(selected.asset.path, resolveSourceEntries(undefined, loadConfig()));
+    if (!source)
+        return { available: false, commits: [] };
+    const file = path.relative(source.path, selected.asset.path).split(path.sep).join("/");
+    if (file.startsWith("../") || path.isAbsolute(file))
+        throw new UsageError("Asset path is outside its bundle.");
+    const commits = await readRecentCommits(source.path, limitParam(query, 30), file);
+    const revision = query.get("revision");
+    if (revision && !commits?.some((commit) => commit.sha === revision))
+        throw new UsageError("Choose a revision from this asset's history.");
+    const diff = revision ? await readFileRevision(source.path, file, revision) : null;
+    const before = capSide(diff?.before ?? null);
+    const after = capSide(diff?.after ?? null);
+    return {
+        available: commits !== null,
+        commits: commits ?? [],
+        ...(diff
+            ? {
+                diff: {
+                    before: before.text,
+                    after: after.text,
+                    unified: diff.unified.slice(0, DIFF_SIDE_MAX_CHARS),
+                    truncated: before.truncated || after.truncated || diff.unified.length > DIFF_SIDE_MAX_CHARS,
+                },
+            }
+            : {}),
+    };
 }
 // ── Routing ──────────────────────────────────────────────────────────────────
 const ROUTES = {
@@ -540,6 +628,8 @@ const ROUTES = {
     "/api/changes": changes,
     "/api/search": search,
     "/api/asset": asset,
+    "/api/asset/history": assetHistory,
+    "/api/asset/source": (query) => readDocumentSource(query.get("ref") ?? ""),
 };
 const PROPOSAL_ROUTE = /^\/api\/proposals\/([^/]+)$/;
 /** What {@link handleApiRequest} returns for a path that is not an API route. */

package/dist/commands/ui/document-source.js

@@ -0,0 +1,51 @@
+// 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/.
+import { createHash } from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { assetPathForName, stashDirFor } from "../../core/asset/asset-placement.js";
+import { parseRefInput } from "../../core/asset/resolve-ref.js";
+import { loadConfig } from "../../core/config/config.js";
+import { UsageError } from "../../core/errors.js";
+import { resolveBundleWriteTarget } from "../../core/mutation-target.js";
+import { assertAkmAssetWrite } from "../../core/write-source.js";
+import { closeDatabase, openReadonlyExistingDatabase } from "../../storage/repositories/index-connection.js";
+import { getEntryIdByFilePath, getItemRefById } from "../../storage/repositories/index-entries-repository.js";
+import { akmShowUnified } from "../read/show.js";
+import { redactUrlsInText } from "./redact.js";
+/** Authoring reads are limited to indexed, writable AKM knowledge/memory files, never arbitrary paths. */
+export async function readDocumentSource(ref) {
+    const parsed = parseRefInput(ref);
+    if (parsed.type !== "knowledge" && parsed.type !== "memory")
+        throw new UsageError("Only knowledge and memory support source editing in this UI.");
+    const shown = await akmShowUnified({ ref, readOnly: true });
+    if (!shown.path)
+        throw new UsageError("The document has no local source file.");
+    const db = openReadonlyExistingDatabase();
+    let canonical;
+    if (db) {
+        try {
+            const id = getEntryIdByFilePath(db, shown.path);
+            canonical = id === undefined ? undefined : (getItemRefById(db, id) ?? undefined);
+        }
+        finally {
+            closeDatabase(db);
+        }
+    }
+    if (!canonical)
+        throw new UsageError("Only indexed documents can be edited.");
+    const identity = parseRefInput(canonical);
+    const target = resolveBundleWriteTarget(loadConfig(), identity.origin);
+    assertAkmAssetWrite(target.source);
+    const expectedPath = assetPathForName(parsed.type, path.join(target.source.path, stashDirFor(parsed.type)), identity.name);
+    if (path.resolve(expectedPath) !== path.resolve(shown.path))
+        throw new UsageError("The indexed source no longer matches the writable document target. Refresh the index before editing.");
+    const raw = fs.readFileSync(shown.path);
+    const content = raw.toString("utf8");
+    if (!Buffer.from(content, "utf8").equals(raw))
+        throw new UsageError("This source is not valid UTF-8; edit it outside the UI.");
+    if (redactUrlsInText(content) !== content)
+        throw new UsageError("This document contains URL credentials hidden by the UI. Edit it outside the UI to preserve those values.");
+    return { ref: canonical, type: parsed.type, content, revision: createHash("sha256").update(raw).digest("hex") };
+}

package/dist/commands/ui/git-read.js

@@ -73,10 +73,17 @@ export function classifyCommitOrigin(subject) {
     return "other";
 }
 /** The `limit` most recent commits of the repository at `repoDir`, newest first; `null` when it is not a git root. */
-export async function readRecentCommits(repoDir, limit) {
+export async function readRecentCommits(repoDir, limit, file) {
     if (!isGitRoot(repoDir))
         return null;
-    const out = await git(repoDir, ["log", "-n", String(limit), "--name-only", "--format=%x1e%H%x1f%cI%x1f%an%x1f%s"]);
+    const out = await git(repoDir, [
+        "log",
+        "-n",
+        String(limit),
+        "--name-only",
+        "--format=%x1e%H%x1f%cI%x1f%an%x1f%s",
+        ...(file ? ["--", file] : []),
+    ]);
     if (out === null)
         return [];
     const commits = [];
@@ -99,3 +106,12 @@ export async function readRecentCommits(repoDir, limit) {
     }
     return commits;
 }
+/** Caller supplies an indexed asset path inside this bundle and a commit ID it took from {@link readRecentCommits}. */
+export async function readFileRevision(repoDir, file, sha) {
+    const after = await git(repoDir, ["show", `${sha}:${file}`]);
+    if (after === null)
+        return null;
+    const before = await git(repoDir, ["show", `${sha}^:${file}`]);
+    const unified = await git(repoDir, ["show", "--no-ext-diff", "--no-textconv", "--format=", sha, "--", file]);
+    return { before, after, unified: unified ?? "" };
+}

package/dist/commands/ui/proposal-actions.js

@@ -2,14 +2,14 @@
 // 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/.
 /**
- * The only writes `akm ui` makes: accept and reject a proposal, and accept
+ * Proposal writes `akm ui` makes: accept and reject a proposal, and accept
  * several at once. Each handler calls the function `akm proposal accept` /
  * `reject` calls, with the arguments the CLI passes, so a UI decision is
  * recorded exactly like a CLI one (same state.db rows, events and commit).
  *
  * The server decides whether a request may reach this module (token header,
  * Origin, content type, body size); see `server.ts`. Everything else in the UI
- * stays read-only and lives in `api.ts`.
+ * is either a read in `api.ts` or an explicit action in `workspace-actions.ts`.
  */
 import { AkmError, TransientError, UsageError } from "../../core/errors.js";
 import { acquireAssetMutationLease } from "../../indexer/index-writer-lock.js";
@@ -56,6 +56,8 @@ export function classifyProposalError(error) {
     const message = error instanceof Error ? error.message : String(error);
     const byMessage = codeForMessage(message);
     if (error instanceof AkmError) {
+        if (error.code === "ASSET_CONTENT_CHANGED")
+            return { status: 409, code: error.code, message };
         if (byMessage === "PROPOSAL_STALE" || byMessage === "PROPOSAL_NOT_PENDING") {
             return { status: 409, code: byMessage, message };
         }
@@ -112,7 +114,7 @@ function batchIds(body) {
  * reject functions would wait up to ten minutes for it, which in a browser is a
  * hung button; the probe turns a held lease into an immediate, retryable 409.
  */
-async function assertWriteLeaseFree(purpose) {
+export async function assertWriteLeaseFree(purpose) {
     const lease = await acquireAssetMutationLease({ mode: "try", purpose });
     if (!lease) {
         throw new TransientError("Another akm process or request is writing to the bundle right now. Try again in a moment.", "ASSET_MUTATION_LEASE_HELD");

package/dist/commands/ui/server.js

@@ -10,7 +10,7 @@
  * `Host` header must be the address the server is bound to, which stops a web
  * page from reaching it through DNS rebinding. Static UI files are served
  * without the token and embed no data. Only GET (and HEAD) is accepted, except
- * for the three proposal writes (accept, reject, accept several): a POST to one
+ * for explicit proposal and workspace actions: a POST to one
  * of those must carry the token in the `X-Akm-Ui-Token` header (never the
  * query string), a JSON content type and an `Origin` that is this server's own,
  * so another web page cannot make the browser send one.
@@ -27,6 +27,7 @@ import chartsJs from "../../assets/ui/charts.js" with { type: "text" };
 import configJs from "../../assets/ui/config.js" with { type: "text" };
 import diffJs from "../../assets/ui/diff.js" with { type: "text" };
 import diffViewJs from "../../assets/ui/diff-view.js" with { type: "text" };
+import editorJs from "../../assets/ui/editor.js" with { type: "text" };
 import indexHtml from "../../assets/ui/index.html" with { type: "text" };
 import libJs from "../../assets/ui/lib.js" with { type: "text" };
 import markdownJs from "../../assets/ui/markdown.js" with { type: "text" };
@@ -40,9 +41,12 @@ import { getDirname } from "../../runtime.js";
 import { handleApiRequest, NO_SUCH_ROUTE } from "./api.js";
 import { classifyProposalError, handleWriteRequest, matchWriteRoute } from "./proposal-actions.js";
 import { scrubUrlCredentials } from "./redact.js";
+import { classifyWorkspaceError, handleWorkspaceAction, matchWorkspaceAction, } from "./workspace-actions.js";
 export const TOKEN_HEADER = "x-akm-ui-token";
 /** Largest request body a write route reads. */
 export const MAX_BODY_BYTES = 64 * 1024;
+/** Largest body of a route that carries a whole Markdown document (`/api/asset/save`, `/api/knowledge/create`). */
+export const MAX_DOCUMENT_BODY_BYTES = 8 * 1024 * 1024;
 const UI_DIR = path.join(getDirname(import.meta.url), "../../assets/ui");
 /**
  * The UI files embedded at build time. Disk stays primary (an edit shows
@@ -62,6 +66,7 @@ export const EMBEDDED_UI = {
     "config.js": configJs,
     "diff-view.js": diffViewJs,
     "diff.js": diffJs,
+    "editor.js": editorJs,
     "lib.js": libJs,
     "markdown.js": markdownJs,
     "overview.js": overviewJs,
@@ -148,11 +153,11 @@ function originAllowed(origin, hostHeader) {
 function isJsonContentType(header) {
     return (header ?? "").split(";")[0]?.trim().toLowerCase() === "application/json";
 }
-/** The request body as text, or `null` when it is larger than {@link MAX_BODY_BYTES}. */
-function readBody(req) {
+/** The request body as text, or `null` when it is larger than `limit` bytes. */
+function readBody(req, limit) {
     return new Promise((resolve, reject) => {
         const declared = Number(req.headers["content-length"]);
-        if (Number.isFinite(declared) && declared > MAX_BODY_BYTES) {
+        if (Number.isFinite(declared) && declared > limit) {
             resolve(null);
             return;
         }
@@ -161,7 +166,7 @@ function readBody(req) {
         let tooLarge = false;
         req.on("data", (chunk) => {
             size += chunk.length;
-            if (size > MAX_BODY_BYTES)
+            if (size > limit)
                 tooLarge = true;
             else
                 chunks.push(chunk);
@@ -237,7 +242,8 @@ export async function startUiServer(options = {}) {
         }
         const url = new URL(req.url ?? "/", "http://akm-ui.invalid");
         const isApi = url.pathname === "/api" || url.pathname.startsWith("/api/");
-        const writeRoute = req.method === "POST" ? matchWriteRoute(url.pathname) : null;
+        const workspace = req.method === "POST" ? matchWorkspaceAction(url.pathname) : null;
+        const writeRoute = req.method === "POST" ? (workspace ? { workspace } : matchWriteRoute(url.pathname)) : null;
         if (writeRoute) {
             await handleWrite(req, res, writeRoute);
             return;
@@ -255,7 +261,7 @@ export async function startUiServer(options = {}) {
             }
         }
         if (!readMethod) {
-            sendError(req, res, 405, "METHOD_NOT_ALLOWED", "Only GET is accepted here. akm ui writes only through POST /api/proposals/:id/accept, /reject and /api/proposals/accept.", {
+            sendError(req, res, 405, "METHOD_NOT_ALLOWED", "Only GET is accepted here. Use an explicit UI action to make changes.", {
                 Allow: "GET, HEAD",
             });
             return;
@@ -271,7 +277,9 @@ export async function startUiServer(options = {}) {
             }
             catch (error) {
                 const code = error instanceof AkmError ? error.code : "INTERNAL_ERROR";
-                sendError(req, res, statusFor(error), code, error instanceof Error ? error.message : String(error));
+                // The editor's source read refuses what a save would refuse, with the same status.
+                const status = url.pathname === "/api/asset/source" ? classifyWorkspaceError(error).status : statusFor(error);
+                sendError(req, res, status, code, error instanceof Error ? error.message : String(error));
             }
             return;
         }
@@ -288,7 +296,7 @@ export async function startUiServer(options = {}) {
         });
         res.end(req.method === "HEAD" ? undefined : asset.body);
     }
-    /** The three proposal writes. Every check runs before the body is read. */
+    /** Explicit write actions. Every check runs before the body is read. */
     async function handleWrite(req, res, route) {
         // The header only: a token in the URL ends up in history and logs, and a link can carry it.
         const given = req.headers[TOKEN_HEADER];
@@ -306,9 +314,11 @@ export async function startUiServer(options = {}) {
             sendError(req, res, 415, "UNSUPPORTED_MEDIA_TYPE", "Writes must be sent as Content-Type: application/json.");
             return;
         }
-        const text = await readBody(req);
+        const document = "workspace" in route && (route.workspace === "document-save" || route.workspace === "knowledge-create");
+        const limit = document ? MAX_DOCUMENT_BODY_BYTES : MAX_BODY_BYTES;
+        const text = await readBody(req, limit);
         if (text === null) {
-            sendError(req, res, 413, "BODY_TOO_LARGE", `The request body is larger than ${MAX_BODY_BYTES} bytes.`, {
+            sendError(req, res, 413, "BODY_TOO_LARGE", `The request body is larger than ${limit} bytes.`, {
                 Connection: "close",
             });
             return;
@@ -322,11 +332,13 @@ export async function startUiServer(options = {}) {
             return;
         }
         try {
-            const data = await handleWriteRequest(route, body);
+            const data = "workspace" in route
+                ? await handleWorkspaceAction(route.workspace, body)
+                : await handleWriteRequest(route, body);
             sendJson(req, res, 200, { ok: true, data: scrubUrlCredentials(data) });
         }
         catch (error) {
-            const { status, code, message } = classifyProposalError(error);
+            const { status, code, message } = "workspace" in route ? classifyWorkspaceError(error) : classifyProposalError(error);
             sendError(req, res, status, code, message);
         }
     }

package/dist/commands/ui/ui-cli.js

@@ -2,7 +2,7 @@
 // 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/.
 /**
- * `akm ui` — a local web UI, read-only apart from accepting and rejecting proposals, over the same data the CLI reports:
+ * `akm ui` — a local web UI over the same data and explicit operations the CLI offers:
  * health and metrics, bundles, config, the proposal queue, recent changes and
  * search. See `docs/reference/ui-api.md` for the API the page reads.
  */
@@ -23,7 +23,7 @@ function parsePort(raw) {
 export const uiCommand = defineJsonCommand({
     meta: {
         name: "ui",
-        description: "Experimental: serve a local web UI (health, bundles, config, proposals, recent changes, search) and open it in your browser. It is read-only except that you can accept and reject proposals in it. The URL carries a per-launch token. Press Ctrl-C to stop.",
+        description: "Experimental: serve a local web UI for browsing, feedback, bundle management, Markdown authoring and proposal decisions. Browsing is read-only; explicit actions use existing AKM operations. The URL carries a per-launch token. Press Ctrl-C to stop.",
     },
     args: {
         port: { type: "string", description: "Port to listen on (default: a random free port)" },
@@ -40,7 +40,7 @@ export const uiCommand = defineJsonCommand({
         const host = args.host?.trim() || "127.0.0.1";
         const server = await startUiServer({ host, port: parsePort(args.port) });
         if (!isLoopbackBind(host)) {
-            warn(`[ui] Listening on ${host}, not just this machine: anyone who can reach it and has the token can read your stash, config and proposals. Keep the URL private.`);
+            warn(`[ui] Listening on ${host}, not just this machine: anyone who can reach it and has the token can read your data and use the UI's write actions. Keep the URL private.`);
         }
         // The URL is the command's output, so it goes to stdout like any other result.
         process.stdout.write(`akm ui: ${server.url}\n`);