@meetless/mla 0.1.4

package/dist/commands/kb_forget.js

@@ -0,0 +1,283 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseKbForgetArgs = parseKbForgetArgs;
+exports.resolveForgetHandle = resolveForgetHandle;
+exports.cascadeRejectForDoc = cascadeRejectForDoc;
+exports.runKbForget = runKbForget;
+const fs = __importStar(require("fs"));
+const os = __importStar(require("os"));
+const path = __importStar(require("path"));
+const config_1 = require("../lib/config");
+const kb_acl_1 = require("../lib/kb_acl");
+const render_1 = require("../lib/render");
+const http_1 = require("../lib/http");
+const relationship_candidate_query_1 = require("../lib/relationship-candidate-query");
+const session_scope_1 = require("../lib/session-scope");
+const kb_add_1 = require("./kb_add");
+const kb_reingest_1 = require("./kb_reingest");
+const VALUE_FLAGS = new Set(["--workspace", "--reason"]);
+const KBDOC_PREFIX = "kbdoc:";
+const NOTE_PREFIX = "note:";
+const FORGET_TIMEOUT_MS = 30_000;
+function parseKbForgetArgs(argv) {
+    const out = {};
+    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 "--reason":
+                    out.reason = v;
+                    break;
+            }
+            i += 1;
+            continue;
+        }
+        if (a.startsWith("--") || a.startsWith("-")) {
+            throw new Error(`Unknown flag: ${a}. Supported flags: ${[...VALUE_FLAGS].sort().join(", ")}`);
+        }
+        if (positional !== null) {
+            throw new Error(`\`mla kb forget\` takes exactly one positional input (got '${positional}' and '${a}')`);
+        }
+        positional = a;
+    }
+    if (positional === null) {
+        throw new Error("`mla kb forget` requires a positional input: kbdoc:<id>, note:<path>, or a bare note path");
+    }
+    return {
+        input: positional,
+        workspace: out.workspace,
+        reason: out.reason,
+    };
+}
+// ---------------------------------------------------------------------------
+// Client-side handle resolution (was the python worker's identity-vs-filesystem
+// candidate logic, minus the disk read forget never does).
+// ---------------------------------------------------------------------------
+function expandHome(p) {
+    if (p === "~")
+        return os.homedir();
+    if (p.startsWith("~/"))
+        return path.join(os.homedir(), p.slice(2));
+    return p;
+}
+// Map the operator's input to the handle the route resolves. A real local file is
+// mapped to its vault-relative path (the SAME mapping `kb add` / `kb reingest`
+// use, so the identity matches); anything else (an opaque kbdoc id, a stored
+// externalObjectId, or a path that is not a local file) is passed through as `ref`
+// for the server to canonicalize and resolve. Throws ReingestPreconditionError
+// (-> exit 2) only when a real local file's vault root cannot be resolved.
+function resolveForgetHandle(input) {
+    const raw = input.trim();
+    if (!raw) {
+        throw new kb_reingest_1.ReingestPreconditionError("`mla kb forget` requires a non-empty input");
+    }
+    // kbdoc:<id>: opaque, never a file. The server does an exact PK load.
+    if (raw.startsWith(KBDOC_PREFIX)) {
+        const id = raw.slice(KBDOC_PREFIX.length).trim();
+        if (!id) {
+            throw new kb_reingest_1.ReingestPreconditionError("kbdoc: prefix requires an id");
+        }
+        return { ref: raw };
+    }
+    // note:<X> or bare <X>. If X is a real local file, the client maps it to its
+    // vault-relative path (filesystem form). Otherwise it is a stored
+    // externalObjectId / identity string; pass it through for the server to resolve.
+    const rawPath = raw.startsWith(NOTE_PREFIX) ? raw.slice(NOTE_PREFIX.length) : raw;
+    const abs = path.resolve(expandHome(rawPath));
+    let isFile = false;
+    try {
+        isFile = fs.existsSync(abs) && fs.statSync(abs).isFile();
+    }
+    catch {
+        isFile = false;
+    }
+    if (isFile) {
+        const vaultRoot = (0, kb_reingest_1.resolveReingestVaultRoot)(path.dirname(abs));
+        const relPath = (0, kb_add_1.vaultRelPath)(vaultRoot, abs);
+        return { relPath };
+    }
+    return { ref: raw };
+}
+function printPreflight(flags, cfg) {
+    const ws = flags.workspace || cfg.workspaceId;
+    const reasonHint = flags.reason ? ` reason=${JSON.stringify(flags.reason)}` : "";
+    console.log(`mla kb forget workspace=${ws} input=${flags.input}${reasonHint}`);
+}
+// Map an HTTP/network failure to the worker's exit semantics: a 404 (unknown
+// doc), 409 (PURGED terminal), or 422 (bad args) is a precondition -> 2; a
+// network error (no status), a 5xx, or the 500 write-time state race is an
+// operational failure -> 1.
+function exitForHttpError(e) {
+    const status = e?.status;
+    if (status === 404 || status === 409 || status === 422)
+        return 2;
+    return 1;
+}
+// Best-effort: after a doc is tombstoned, its PENDING relationship candidates point
+// at a dead artifact and should not linger in the review queue. Keys on the note
+// basename; the route matches either endpoint. A forgotten doc with >200 pending
+// candidates is not realistic, so this reads a single page. Failures are caught and
+// COUNTED (never thrown) so a cascade hiccup cannot mask a successful tombstone,
+// but the caller reports them so the operator knows dangling edges may remain.
+async function cascadeRejectForDoc(canonicalPath, ctx, deps) {
+    const key = (0, session_scope_1.noteKey)(canonicalPath);
+    let page;
+    try {
+        page = await deps.fetchPending((0, relationship_candidate_query_1.buildPendingCandidateQuery)(ctx.workspaceId, key, 200));
+    }
+    catch {
+        return { fetched: 0, rejected: 0, failed: 0, fetchFailed: true };
+    }
+    let rejected = 0;
+    let failed = 0;
+    for (const c of page.items) {
+        try {
+            await deps.submitReject(c.id, {
+                workspaceId: ctx.workspaceId,
+                userId: ctx.actorUserId,
+                note: "[forget-cascade] source document tombstoned",
+            });
+            rejected++;
+        }
+        catch {
+            failed++;
+        }
+    }
+    return { fetched: page.items.length, rejected, failed, fetchFailed: false };
+}
+async function runKbForget(argv) {
+    // Parse flags BEFORE loading config so `--workspace <id>` can override the
+    // marker-resolved workspace (T1.1 folder = workspace) without requiring the
+    // current directory to be activated.
+    let flags;
+    try {
+        flags = parseKbForgetArgs(argv);
+    }
+    catch (e) {
+        console.error(e.message);
+        return 2;
+    }
+    let cfg;
+    try {
+        cfg = (0, config_1.readKbConfig)(flags.workspace);
+    }
+    catch (e) {
+        console.error(e.message);
+        return 2;
+    }
+    // §13.14 owner-only ACL: verify the configured actor is a workspace OWNER
+    // before the tombstone side effect.
+    try {
+        await (0, kb_acl_1.verifyKbActorIsOwner)(cfg);
+    }
+    catch (e) {
+        if (e instanceof kb_acl_1.KbOwnerCheckError) {
+            console.error(e.message);
+            return 2;
+        }
+        throw e;
+    }
+    const workspaceId = flags.workspace || cfg.workspaceId;
+    printPreflight(flags, cfg);
+    // Pick the server-resolvable handle. A real local file maps to its vault-relative
+    // path (vault root resolved client-side); an unresolved vault root for a real
+    // file is a precondition (-> 2).
+    let handle;
+    try {
+        handle = resolveForgetHandle(flags.input);
+    }
+    catch (e) {
+        if (e instanceof kb_reingest_1.ReingestPreconditionError) {
+            console.error(e.message);
+            return 2;
+        }
+        throw e;
+    }
+    const body = {
+        workspaceId,
+        actor: cfg.actorUserId,
+        reason: flags.reason ?? undefined,
+        ...handle,
+    };
+    let receipt;
+    try {
+        const res = await (0, http_1.intelPost)(cfg, "/internal/v1/kb/forget", body, FORGET_TIMEOUT_MS);
+        receipt = res.receipt;
+    }
+    catch (e) {
+        console.error(`kb forget failed: ${e.message}`);
+        return exitForHttpError(e);
+    }
+    if (!receipt) {
+        console.error("kb forget: the route returned no receipt.");
+        return 1;
+    }
+    console.log((0, render_1.renderKbForgetReceipt)(receipt));
+    console.log("");
+    // Cascade: clear PENDING relationship candidates that referenced the now-dead doc.
+    // Only a fresh tombstone needs it; an already_tombstoned doc's candidates were
+    // cleared on the first forget.
+    if (receipt.outcome === "tombstoned") {
+        const cascadeDeps = {
+            fetchPending: (qs) => (0, http_1.get)(cfg, `/internal/v1/relationship-candidates?${qs}`, 12000),
+            submitReject: async (id, rejectBody) => {
+                await (0, http_1.post)(cfg, `/internal/v1/relationship-candidates/${encodeURIComponent(id)}/reject`, rejectBody, 12000);
+            },
+        };
+        const r = await cascadeRejectForDoc(receipt.canonicalPath, { workspaceId: cfg.workspaceId, actorUserId: cfg.actorUserId }, cascadeDeps);
+        if (r.rejected > 0) {
+            console.log(`Also cleared ${r.rejected} orphaned relationship candidate${r.rejected === 1 ? "" : "s"} that referenced this doc.`);
+        }
+        if (r.fetchFailed) {
+            console.error("Warning: could not check for orphaned relationship candidates; some may remain in the review queue.");
+        }
+        else if (r.failed > 0) {
+            console.error(`Warning: ${r.failed} orphaned relationship candidate${r.failed === 1 ? "" : "s"} could not be cleared; clear them with mla kb review <id> --reject.`);
+        }
+    }
+    return 0;
+}

package/dist/commands/kb_move.js

@@ -0,0 +1,45 @@
+"use strict";
+// `mla kb move` is a BLOCKED capability in the governed (slice-A) model.
+//
+// A governed document's identity IS its source tuple (sourceSystem,
+// sourceTenantId, externalObjectId). For a note, externalObjectId is derived
+// from its path, so re-pathing a note produces a DIFFERENT governed document,
+// not a rename of the existing one. The legacy worker faked a rename by
+// rewriting a row's canonical_path and array-appending the old path to
+// path_aliases while preserving parent_uuid; the slice-A reshape dropped that
+// table shape and every method it leaned on (move_document,
+// resolve_by_canonical_path, path_aliases, parent_uuid, current_posture).
+//
+// Slice A ships no redirect / alias primitive that would let a new path inherit
+// the old document's stable id, revisions, human review verdicts, and audit
+// trail. Until that primitive lands, a true identity-preserving move is not
+// expressible, so this command refuses fast (no config load, no owner check, no
+// subprocess) rather than silently forking a document's history.
+//
+// Workaround (history does NOT follow the content):
+//   1. mla kb add <new-path>   - ingest the content under its new identity
+//   2. mla kb forget <old>     - tombstone the old document
+//
+// Exit code 2 = unsupported / refused, consistent with the other curation
+// commands' usage-error code.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MOVE_BLOCKED_MESSAGE = void 0;
+exports.runKbMove = runKbMove;
+exports.MOVE_BLOCKED_MESSAGE = [
+    "`mla kb move` is blocked in the governed model.",
+    "",
+    "A document's identity is its source tuple (sourceSystem, sourceTenantId,",
+    "externalObjectId). For a note, externalObjectId is derived from its path, so",
+    "re-pathing it is a different governed document, not a rename. Slice A ships no",
+    "redirect / alias primitive that would carry the old document's id, revisions,",
+    "review verdicts, and audit trail to the new path, so a true move is not yet",
+    "expressible.",
+    "",
+    "Workaround (history does NOT follow the content):",
+    "  1. mla kb add <new-path>   - ingest the content under its new identity",
+    "  2. mla kb forget <old>     - tombstone the old document",
+].join("\n");
+async function runKbMove(_argv) {
+    console.error(exports.MOVE_BLOCKED_MESSAGE);
+    return 2;
+}