@meetless/mla 0.1.4

package/dist/commands/kb_revision.js

@@ -0,0 +1,179 @@
+"use strict";
+// `mla kb accept <doc-id>` / `mla kb reject <doc-id>` (revision review).
+//
+// A `mla kb reingest` of a doc that has PROMOTED relationship edges does NOT
+// replace the live bytes outright. It parks the new revision at
+// SHADOW_PENDING_REVIEW (the old revision keeps grounding answers) so a human
+// confirms the change before it ships. These two commands are the consumer side
+// of that park:
+//
+//   accept -> POST /internal/v1/kb/documents/<id>/accept
+//             the pending revision becomes current; it starts grounding answers,
+//             the old revision is superseded, KB_REVISION_ACCEPTED is emitted.
+//   reject -> POST /internal/v1/kb/documents/<id>/reject
+//             the pending revision is discarded; the old revision keeps serving,
+//             KB_REVISION_REJECTED is emitted, and the rejected revision's vector
+//             chunks are GC'd best-effort.
+//
+// Both act on a DOCUMENT id; the route resolves the doc's single
+// SHADOW_PENDING_REVIEW revision itself (zero or many is a 409). A `note:` or
+// `kbdocrev:` input is therefore a usage error, not a silent path resolution.
+//
+// Mirrors the kb_retime.ts deps-injection shape: a thin public runner loads the
+// real config (readKbConfig) and wires the real intelPost, while every
+// collaborator is injectable so the unit test drives it offline. Auth + actor:
+// the POST carries Authorization via the shared intel HTTP layer; the actor
+// rides in the BODY as actorUserId (intel stamps only Authorization + X-Trace-ID,
+// never an actor header), so it comes from cfg.actorUserId. For a cli-session
+// caller intel ignores the body actorUserId in favor of the session user.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseKbRevisionArgs = parseKbRevisionArgs;
+exports.runKbAccept = runKbAccept;
+exports.runKbReject = runKbReject;
+const config_1 = require("../lib/config");
+const http_1 = require("../lib/http");
+const VALUE_FLAGS = new Set(["--reason"]);
+const BOOLEAN_FLAGS = new Set(["--json"]);
+const KBDOC_PREFIX = "kbdoc:";
+function usage(action) {
+    return `Usage: mla kb ${action} <kbdoc:<id>|<doc-id>> [--reason <s>] [--json]`;
+}
+// Parse a single positional document id, plus optional --reason / --json. The id
+// may carry the canonical `kbdoc:` prefix (stripped to the raw id for the URL
+// path) or be bare. A `note:` or `kbdocrev:` input is rejected: the route is
+// keyed on a document id and resolves the pending revision itself, so neither a
+// path nor a specific revision id is a valid target. The action only shapes the
+// error text; both verbs share this grammar.
+function parseKbRevisionArgs(argv, action = "accept") {
+    let documentId = null;
+    let reason;
+    let json = false;
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (VALUE_FLAGS.has(a)) {
+            const next = argv[i + 1];
+            if (next === undefined || next.startsWith("-")) {
+                throw new Error(`Missing value for ${a}. ${usage(action)}`);
+            }
+            if (a === "--reason")
+                reason = next;
+            i++;
+        }
+        else if (BOOLEAN_FLAGS.has(a)) {
+            json = true;
+        }
+        else if (a.startsWith("-")) {
+            const supported = [...VALUE_FLAGS, ...BOOLEAN_FLAGS].sort().join(", ");
+            throw new Error(`Unknown flag: ${a}. Supported: ${supported}. ${usage(action)}`);
+        }
+        else if (documentId === null) {
+            documentId = a;
+        }
+        else {
+            throw new Error(`Unexpected argument: ${a}. ${usage(action)}`);
+        }
+    }
+    if (documentId === null) {
+        throw new Error(`mla kb ${action} requires a document id. ${usage(action)}`);
+    }
+    const trimmed = documentId.trim();
+    if (trimmed.startsWith("note:")) {
+        throw new Error(`mla kb ${action} acts on a document id, not a note path. ` +
+            `Run \`mla kb show ${trimmed}\` to find its kbdoc id, then \`mla kb ${action} kbdoc:<id>\`.`);
+    }
+    if (trimmed.startsWith("kbdocrev:")) {
+        throw new Error(`mla kb ${action} acts on a document id, not a revision id. The route resolves ` +
+            `the document's single pending revision itself; pass the kbdoc id instead.`);
+    }
+    const id = trimmed.startsWith(KBDOC_PREFIX) ? trimmed.slice(KBDOC_PREFIX.length).trim() : trimmed;
+    if (!id) {
+        throw new Error(`mla kb ${action} requires a non-empty document id. ${usage(action)}`);
+    }
+    return { documentId: id, reason, json };
+}
+// Surface an intel HTTP failure helpfully, mirroring kb_retime.ts's explainRetimeError.
+function explainReviewError(action, err, intelUrl) {
+    if (err.status === 404) {
+        return `intel returned 404: document not found in this workspace (or this intel does not expose the KB ${action} route).`;
+    }
+    if (err.status === 409) {
+        return (`intel returned 409: the document has no single pending revision to ${action}. ` +
+            `A revision is only reviewable when a reingest parked it at SHADOW_PENDING_REVIEW. ` +
+            `Details: ${err.body ?? err.message}`);
+    }
+    if (err.status === 401 || err.status === 403) {
+        return `intel rejected the request (HTTP ${err.status}). Check controlToken / workspace in cli-config.json.`;
+    }
+    if (err.status === undefined) {
+        return `intel not reachable at ${intelUrl}. Is it running? Try \`mla doctor\`.`;
+    }
+    return err.message;
+}
+// Render the review receipt in plain words. No double-dash range separators
+// (An's AI-smell rule); each line spells out what changed.
+function renderReceipt(r) {
+    const out = [];
+    if (r.action === "accepted") {
+        out.push(`Accepted revision ${r.reviewedRevisionId} on ${r.documentId}.`);
+        out.push(`  current revision: ${r.currentRevisionId} (now grounding answers)`);
+        out.push(`  the prior revision was superseded; its lexical chunks were soft-tombstoned.`);
+        out.push("");
+        out.push("The pending revision is now live. Its vector chunks ground answers; the old revision no longer does.");
+    }
+    else {
+        out.push(`Rejected revision ${r.reviewedRevisionId} on ${r.documentId}.`);
+        out.push(`  current revision: ${r.currentRevisionId} (unchanged; still grounding answers)`);
+        out.push(`  lexical chunks deleted: the rejected revision's chunk_fts rows were removed.`);
+        out.push(`  vector chunks deleted:  ${r.weaviateChunksDeleted}`);
+        out.push("");
+        out.push("The pending revision was discarded. The previously live revision keeps serving unchanged.");
+    }
+    return out.join("\n");
+}
+async function runRevisionReview(action, argv, deps) {
+    let cfg;
+    try {
+        cfg = deps?.cfg ?? (0, config_1.readKbConfig)();
+    }
+    catch (e) {
+        console.error(e.message);
+        return 2;
+    }
+    let parsed;
+    try {
+        parsed = parseKbRevisionArgs(argv, action);
+    }
+    catch (e) {
+        console.error(e.message);
+        return 2;
+    }
+    const post = deps?.http?.intelPost ?? http_1.intelPost;
+    const body = {
+        workspaceId: cfg.workspaceId,
+        actorUserId: cfg.actorUserId,
+    };
+    if (parsed.reason !== undefined)
+        body.reason = parsed.reason;
+    const path = `/internal/v1/kb/documents/${encodeURIComponent(parsed.documentId)}/${action}`;
+    let res;
+    try {
+        res = (await post(cfg, path, body));
+    }
+    catch (e) {
+        const intelUrl = cfg.intelUrl || http_1.DEFAULT_INTEL_URL;
+        console.error(explainReviewError(action, e, intelUrl));
+        return 1;
+    }
+    if (parsed.json) {
+        console.log(JSON.stringify(res, null, 2));
+        return 0;
+    }
+    console.log(renderReceipt(res));
+    return 0;
+}
+async function runKbAccept(argv, deps) {
+    return runRevisionReview("accept", argv, deps);
+}
+async function runKbReject(argv, deps) {
+    return runRevisionReview("reject", argv, deps);
+}

package/dist/commands/kb_show.js

@@ -0,0 +1,385 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseKbShowArgs = parseKbShowArgs;
+exports.runKbShow = runKbShow;
+const config_1 = require("../lib/config");
+const workspace_1 = require("../lib/workspace");
+const http_1 = require("../lib/http");
+const open_url_1 = require("../lib/open-url");
+const artifact_id_1 = require("../lib/artifact_id");
+const temporal_1 = require("../lib/temporal");
+const render_1 = require("../lib/render");
+const VALUE_FLAGS = new Set(["--workspace", "--posture", "--as-of"]);
+const BOOLEAN_FLAGS = new Set([
+    "--include-tombstoned",
+    "--json",
+    "--all",
+    "--audit-all",
+    "--open",
+]);
+const REVISION_LIMIT_DEFAULT = 20;
+const REVISION_LIMIT_ALL = 200;
+const AUDIT_LIMIT_DEFAULT = 10;
+const AUDIT_LIMIT_ALL = 500;
+function parseKbShowArgs(argv) {
+    const out = {
+        posture: "both",
+        includeTombstoned: false,
+        json: false,
+        all: false,
+        auditAll: false,
+        open: false,
+    };
+    let positional = null;
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (VALUE_FLAGS.has(a)) {
+            const v = argv[i + 1];
+            if (v === undefined) {
+                throw new Error(`Missing value for ${a}`);
+            }
+            if (v.startsWith("--") || v.startsWith("-")) {
+                throw new Error(`Missing value for ${a} (got the next flag ${v} instead)`);
+            }
+            switch (a) {
+                case "--workspace":
+                    out.workspace = v;
+                    break;
+                case "--posture":
+                    if (v !== "both" && v !== "LIVE" && v !== "SHADOW") {
+                        throw new Error(`--posture must be 'both', 'LIVE', or 'SHADOW' (got '${v}')`);
+                    }
+                    out.posture = v;
+                    break;
+                case "--as-of":
+                    // parseAsOf throws on a malformed date so a typo never silently
+                    // answers as-of "now"; runKbShow maps the throw to exit 2.
+                    out.asOf = (0, temporal_1.parseAsOf)(v);
+                    break;
+            }
+            i += 1;
+            continue;
+        }
+        if (BOOLEAN_FLAGS.has(a)) {
+            if (a === "--include-tombstoned")
+                out.includeTombstoned = true;
+            else if (a === "--json")
+                out.json = true;
+            else if (a === "--all")
+                out.all = true;
+            else if (a === "--audit-all")
+                out.auditAll = true;
+            else if (a === "--open")
+                out.open = true;
+            continue;
+        }
+        if (a.startsWith("--") || a.startsWith("-")) {
+            throw new Error(`Unknown flag: ${a}. Supported flags: ${[...VALUE_FLAGS, ...BOOLEAN_FLAGS].sort().join(", ")}`);
+        }
+        if (positional !== null) {
+            throw new Error(`\`mla kb show\` takes exactly one positional <input> (got '${positional}' and '${a}')`);
+        }
+        positional = a;
+    }
+    if (positional === null) {
+        throw new Error("`mla kb show` requires a positional <input> (kbdoc:<id> or a note path)");
+    }
+    return {
+        input: positional,
+        workspace: out.workspace,
+        posture: out.posture,
+        includeTombstoned: !!out.includeTombstoned,
+        json: !!out.json,
+        all: !!out.all,
+        auditAll: !!out.auditAll,
+        open: !!out.open,
+        asOf: out.asOf,
+    };
+}
+function explainIntelError(err, intelUrl) {
+    if (err.status === 404) {
+        return err.body && err.body.includes("KB_DOCUMENT_PATH_NOT_FOUND")
+            ? `No KbDocument matches that path in the requested workspace. Try \`mla kb dump\` to list ingested sources.`
+            : err.body && err.body.includes("KB_DOCUMENT_NOT_FOUND")
+                ? `No KbDocument matches that id in the requested workspace.`
+                : `intel returned 404. ${err.body.slice(0, 200)}`;
+    }
+    if (err.status === 401 || err.status === 403) {
+        return `intel rejected the token (HTTP ${err.status}). Check controlToken in cli-config.json.`;
+    }
+    if (err.status === undefined) {
+        return `intel not reachable at ${intelUrl}. Is it running? Try \`mla doctor\`.`;
+    }
+    return err.message;
+}
+function toShowRevision(r) {
+    return {
+        id: r.revisionId,
+        status: r.status,
+        ingestRunId: r.ingestRunId,
+        postureAtIngest: r.postureAtIngest,
+        normalizedBodyHash: r.normalizedBodyHash,
+        frontmatterHash: r.frontmatterHash,
+        fullDocumentHash: r.fullDocumentHash,
+        chunkCount: r.chunkCount,
+        createdAt: r.createdAt,
+        failureCode: r.status === "FAILED" ? r.failureCode : null,
+        failureReason: r.status === "FAILED" ? r.failureReason : null,
+        failedAt: r.status === "FAILED" ? r.failedAt : null,
+        provenanceOverride: r.provenanceOverride,
+        overrideReason: r.overrideReason,
+    };
+}
+function toShowChunk(c) {
+    return {
+        id: c.chunkUuid,
+        ordinal: c.chunkIndex,
+        bytes: c.contentLength,
+        preview: c.preview,
+        revisionId: c.revisionId,
+    };
+}
+function postureOf(endpoint) {
+    // Intel doesn't carry per-edge posture on candidates/promoted edges in this
+    // response shape; use the counterpart's tombstone state as a proxy hint so
+    // the renderer still has SOMETHING to print. Both posture filters operate
+    // post-render via fmtEdgeLine. The wire string is opaque to the renderer.
+    return endpoint.counterpartTombstoneState === "ACTIVE" ||
+        endpoint.counterpartTombstoneState === null
+        ? "LIVE"
+        : "SHADOW";
+}
+function pickCounterpartEndpoint(fromEndpoint, toEndpoint) {
+    // The "self" side is whichever endpoint has isThisDoc=true. The counterpart
+    // is the other one. Direction is from-this-doc -> counterpart for outgoing,
+    // counterpart -> this-doc for incoming.
+    if (fromEndpoint.isThisDoc) {
+        return { endpoint: toEndpoint, direction: "outgoing" };
+    }
+    return { endpoint: fromEndpoint, direction: "incoming" };
+}
+function toCandidateRow(c) {
+    const pick = pickCounterpartEndpoint(c.fromEndpoint, c.toEndpoint);
+    return {
+        id: c.candidateId,
+        kind: "candidate",
+        direction: pick.direction,
+        predicate: c.relationType,
+        status: c.status,
+        posture: postureOf(pick.endpoint),
+        counterpart: {
+            documentId: pick.endpoint.counterpartKbDocumentId || pick.endpoint.endpointId,
+            canonicalPath: null,
+            tombstoneState: pick.endpoint.counterpartTombstoneState,
+            tombstonedAt: pick.endpoint.counterpartTombstonedAt,
+        },
+    };
+}
+function toPromotedRow(e) {
+    const pick = pickCounterpartEndpoint(e.fromEndpoint, e.toEndpoint);
+    return {
+        id: e.edgeId,
+        kind: "promoted",
+        direction: pick.direction,
+        predicate: e.relationType,
+        status: e.isRetrievable ? "ACTIVE" : "RETIRED",
+        posture: postureOf(pick.endpoint),
+        counterpart: {
+            documentId: pick.endpoint.counterpartKbDocumentId || pick.endpoint.endpointId,
+            canonicalPath: null,
+            tombstoneState: pick.endpoint.counterpartTombstoneState,
+            tombstonedAt: pick.endpoint.counterpartTombstonedAt,
+        },
+        // Task 5.2: carry the VALID-time window + clock trust onto the row so the
+        // renderer shows when the relation was true and how trustworthy that clock
+        // is. UNKNOWN is the honest fallback for a legacy edge with no source.
+        validity: {
+            validAt: e.validAt ?? null,
+            invalidAt: e.invalidAt ?? null,
+            validTimeSource: e.validTimeSource ?? "UNKNOWN",
+            sourceObservedAt: e.sourceObservedAt ?? null,
+        },
+    };
+}
+function toAuditEntry(a) {
+    return {
+        id: a.auditEventId,
+        eventType: a.eventType,
+        occurredAt: a.occurredAt,
+        actorId: a.actorUserId,
+        subjectId: a.artifactId,
+        payloadDigest: null,
+    };
+}
+function filterEdgesByPosture(rows, posture, includeTombstoned) {
+    return rows.filter((r) => {
+        const cpState = r.counterpart.tombstoneState;
+        const cpIsTombstoned = cpState !== null && cpState !== "ACTIVE";
+        if (cpIsTombstoned && !includeTombstoned)
+            return false;
+        if (posture === "both")
+            return true;
+        return r.posture === posture;
+    });
+}
+function buildShowView(resp, flags) {
+    const candidates = filterEdgesByPosture(resp.candidates.map(toCandidateRow), flags.posture, flags.includeTombstoned);
+    const promoted = filterEdgesByPosture(resp.promotedEdges.map(toPromotedRow), flags.posture, flags.includeTombstoned);
+    const totalChunks = resp.chunks.active.length +
+        resp.chunks.pendingReview.length +
+        resp.chunks.superseded.length;
+    const activePreview = resp.chunks.active.slice(0, 5).map(toShowChunk);
+    const pendingPreview = resp.chunks.pendingReview
+        .slice(0, 5)
+        .map(toShowChunk);
+    const revisionLimit = flags.all ? REVISION_LIMIT_ALL : REVISION_LIMIT_DEFAULT;
+    const auditLimit = flags.auditAll ? AUDIT_LIMIT_ALL : AUDIT_LIMIT_DEFAULT;
+    return {
+        workspaceId: resp.workspaceId,
+        document: {
+            id: resp.identity.documentId,
+            canonicalPath: resp.identity.canonicalPath,
+            pathAliases: resp.identity.pathAliases || [],
+            parentUuid: resp.identity.parentUuid,
+            provenance: resp.identity.provenance,
+            currentPosture: resp.identity.currentPosture,
+            effectivePosture: resp.identity.effectivePosture,
+            tombstoneState: resp.identity.tombstoneState,
+            tombstonedAt: resp.identity.tombstonedAt,
+            tombstoneReason: resp.identity.tombstoneReason,
+            tombstoneActorId: resp.identity.tombstoneActorId,
+            deletedAt: resp.identity.deletedAt,
+            deletedBy: resp.identity.deletedBy,
+            redactedPathHash: null,
+            createdAt: resp.identity.createdAt,
+            updatedAt: resp.identity.updatedAt,
+        },
+        currentRevision: resp.currentRevision
+            ? toShowRevision(resp.currentRevision)
+            : null,
+        revisionHistory: resp.revisions.map(toShowRevision),
+        revisionHistoryTruncated: resp.revisions.length >= revisionLimit,
+        chunks: {
+            totalCount: totalChunks,
+            totalBytes: resp.chunks.totalContentBytes,
+            preview: activePreview,
+            pendingReviewPreview: pendingPreview,
+        },
+        candidates,
+        promoted,
+        audit: resp.auditTrail.map(toAuditEntry),
+        auditTruncated: resp.auditTrail.length >= auditLimit,
+        includeTombstoned: flags.includeTombstoned,
+        extraction: resp.extraction ?? null,
+    };
+}
+async function resolveToDocumentId(cfg, workspaceId, input, intelUrl) {
+    if (input.kind === "kbdoc") {
+        return input.id;
+    }
+    if (input.kind === "kbdocrev") {
+        throw new Error("`mla kb show` does not accept kbdocrev:<id>. Pass the parent kbdoc:<id> or the note path; revision details are rendered inside the document view.");
+    }
+    const qs = new URLSearchParams({
+        workspaceId,
+        path: input.path,
+    }).toString();
+    try {
+        const r = await (0, http_1.intelGet)(cfg, `/internal/v1/kb/documents/resolve?${qs}`, 10000);
+        return r.documentId;
+    }
+    catch (e) {
+        const err = e;
+        throw new Error(explainIntelError(err, intelUrl));
+    }
+}
+async function runKbShow(argv) {
+    let cfg;
+    try {
+        cfg = (0, config_1.readConfig)();
+    }
+    catch (e) {
+        console.error(e.message);
+        return 2;
+    }
+    let flags;
+    try {
+        flags = parseKbShowArgs(argv);
+    }
+    catch (e) {
+        console.error(e.message);
+        return 2;
+    }
+    let input;
+    try {
+        input = (0, artifact_id_1.parseArtifactInput)(flags.input);
+    }
+    catch (e) {
+        const msg = e instanceof artifact_id_1.ArtifactInputError ? e.message : e.message;
+        console.error(msg);
+        return 2;
+    }
+    // Folder = workspace (T1.1): the workspace comes from the nearest marker;
+    // `--workspace <id>` overrides it (admin cross-workspace inspection) and
+    // short-circuits marker resolution so an unbound directory does not block it.
+    let workspaceId;
+    try {
+        workspaceId = flags.workspace || (0, workspace_1.resolveWorkspaceId)();
+    }
+    catch (e) {
+        console.error(e.message);
+        return 2;
+    }
+    const intelUrl = cfg.intelUrl || http_1.DEFAULT_INTEL_URL;
+    let documentId;
+    try {
+        documentId = await resolveToDocumentId(cfg, workspaceId, input, intelUrl);
+    }
+    catch (e) {
+        console.error(e.message);
+        return 1;
+    }
+    const revisionLimit = flags.all ? REVISION_LIMIT_ALL : REVISION_LIMIT_DEFAULT;
+    const auditLimit = flags.auditAll ? AUDIT_LIMIT_ALL : AUDIT_LIMIT_DEFAULT;
+    const qsParams = new URLSearchParams({
+        workspaceId,
+        revisionLimit: String(revisionLimit),
+        auditLimit: String(auditLimit),
+    });
+    if (flags.asOf) {
+        // Point-in-time view: the detail endpoint runs the trusted-source as-of
+        // filter so edges not yet valid at this instant (or from an untrusted clock)
+        // are excluded. The banner goes to stderr so it never pollutes --json stdout.
+        qsParams.set("asOf", flags.asOf);
+        console.error(`Point-in-time view as of ${flags.asOf} (relations not yet valid at that instant, or from an untrusted clock, are excluded).`);
+    }
+    const qs = qsParams.toString();
+    let detail;
+    try {
+        detail = await (0, http_1.intelGet)(cfg, `/internal/v1/kb/documents/${encodeURIComponent(documentId)}/detail?${qs}`, 15000);
+    }
+    catch (e) {
+        console.error(explainIntelError(e, intelUrl));
+        return 1;
+    }
+    const view = buildShowView(detail, flags);
+    // B4a: always surface the Console review URL. The renderer stays pure, so the
+    // command layer resolves it via getConsoleUrl(cfg) and stamps it on the view.
+    view.consoleUrl = `${(0, config_1.getConsoleUrl)(cfg)}/relationships`;
+    if (flags.json) {
+        console.log(JSON.stringify(view, null, 2));
+    }
+    else {
+        console.log((0, render_1.renderKbShow)(view));
+    }
+    // B4b: `--open` is opt-in (never auto-open; the URL is always printed above). The
+    // status note goes to stderr so it never pollutes `--json` stdout.
+    if (flags.open && view.consoleUrl) {
+        const res = (0, open_url_1.openUrl)(view.consoleUrl);
+        if (res.ok)
+            console.error(`opened ${view.consoleUrl} in your browser`);
+        else
+            console.error(`could not open a browser (${res.error}); the URL is above`);
+    }
+    return 0;
+}