@hraness/wordcell 0.20.0-bootstrap.1

package/dist/index-d13v9ckt.js

@@ -0,0 +1,150 @@
+// @bun
+// src/navigation.ts
+var MAX_NAVIGATION_INDEXED_CONNECTIONS = 1e5;
+var MAX_NAVIGATION_RETURNED_CONNECTIONS = 1e4;
+
+class NavigationBudgetError extends RangeError {
+  kind;
+  limit;
+  constructor(kind, limit, message) {
+    super(message);
+    this.name = "NavigationBudgetError";
+    this.kind = kind;
+    this.limit = limit;
+  }
+}
+function checkedDepth(value) {
+  const depth = value ?? 1;
+  if (!Number.isSafeInteger(depth) || depth < 1 || depth > 10) {
+    throw new RangeError("Link depth must be an integer from 1 through 10.");
+  }
+  return depth;
+}
+function checkedLimit(value) {
+  const limit = value ?? 50;
+  if (!Number.isSafeInteger(limit) || limit < 1 || limit > 1000) {
+    throw new RangeError("Link result limit must be an integer from 1 through 1000.");
+  }
+  return limit;
+}
+function connectionNode(note, connection, distance) {
+  return {
+    id: note.id,
+    path: note.path,
+    title: note.title,
+    distance,
+    inboundContextualCount: connection?.inboundContextualCount ?? 0,
+    outboundContextualCount: connection?.outboundContextualCount ?? 0,
+    inboundRelationCount: connection?.inboundRelationCount ?? 0,
+    outboundRelationCount: connection?.outboundRelationCount ?? 0
+  };
+}
+function edgeKey(edge) {
+  return `${edge.source}\x00${edge.target}\x00${edge.line}`;
+}
+function relationKey(relation) {
+  return `${relation.source}\x00${relation.predicate}\x00${relation.target}`;
+}
+function compareTraversalCandidates(left, right) {
+  return left.source.localeCompare(right.source) || left.target.localeCompare(right.target) || left.kind.localeCompare(right.kind) || (left.kind === "relation" && right.kind === "relation" ? left.relation.predicate.localeCompare(right.relation.predicate) : 0) || left.line - right.line;
+}
+function addCandidate(candidates, path, candidate) {
+  const existing = candidates.get(path) ?? [];
+  existing.push(candidate);
+  candidates.set(path, existing);
+}
+function candidateKey(candidate) {
+  return candidate.kind === "link" ? `link\x00${edgeKey(candidate.edge)}` : `relation\x00${relationKey(candidate.relation)}`;
+}
+function checkedConnections(analysis) {
+  const authoredRelations = analysis.authoredRelations ?? [];
+  const connectionCount = analysis.contextualLinks.length + authoredRelations.length;
+  if (connectionCount > MAX_NAVIGATION_INDEXED_CONNECTIONS) {
+    throw new NavigationBudgetError("connection-work-limit", MAX_NAVIGATION_INDEXED_CONNECTIONS, `Link navigation exceeds the ${MAX_NAVIGATION_INDEXED_CONNECTIONS} ` + "contextual-link and authored-relation observation limit.");
+  }
+  return authoredRelations;
+}
+function returnedConnectionLimit(nodeLimit) {
+  return Math.min(MAX_NAVIGATION_RETURNED_CONNECTIONS, nodeLimit ** 2);
+}
+function navigateLinks(notes, analysis, start, options = {}) {
+  const direction = options.direction ?? "both";
+  const depth = checkedDepth(options.depth);
+  const limit = checkedLimit(options.limit);
+  const authoredRelations = checkedConnections(analysis);
+  const notesByPath = new Map(notes.map((note) => [note.path, note]));
+  const notesById = new Map(notes.map((note) => [note.id, note]));
+  const connectionsById = new Map(analysis.noteConnections.map((connection) => [connection.id, connection]));
+  const inbound = new Map;
+  const outbound = new Map;
+  for (const edge of analysis.contextualLinks) {
+    const candidate = {
+      kind: "link",
+      source: edge.source,
+      target: edge.target,
+      line: edge.line,
+      edge
+    };
+    addCandidate(inbound, edge.target, candidate);
+    addCandidate(outbound, edge.source, candidate);
+  }
+  for (const relation of authoredRelations) {
+    const source = notesById.get(relation.source)?.path;
+    const target = notesById.get(relation.target)?.path;
+    if (source === undefined || target === undefined)
+      continue;
+    const candidate = {
+      kind: "relation",
+      source,
+      target,
+      line: relation.provenance.line,
+      relation
+    };
+    addCandidate(inbound, target, candidate);
+    addCandidate(outbound, source, candidate);
+  }
+  const distanceByPath = new Map([[start.path, 0]]);
+  let frontier = [start.path];
+  let truncated = false;
+  const selectedCandidates = new Map;
+  for (let distance = 0;distance < depth && frontier.length > 0; distance += 1) {
+    const next = new Set;
+    for (const path of frontier.toSorted()) {
+      const candidates = [
+        ...direction === "out" || direction === "both" ? outbound.get(path) ?? [] : [],
+        ...direction === "in" || direction === "both" ? inbound.get(path) ?? [] : []
+      ].toSorted(compareTraversalCandidates);
+      for (const candidate of candidates) {
+        const neighborPath = candidate.source === path ? candidate.target : candidate.source;
+        if (!notesByPath.has(neighborPath))
+          continue;
+        if (distanceByPath.has(neighborPath)) {
+          selectedCandidates.set(candidateKey(candidate), candidate);
+          continue;
+        }
+        if (distanceByPath.size >= limit) {
+          truncated = true;
+          continue;
+        }
+        selectedCandidates.set(candidateKey(candidate), candidate);
+        distanceByPath.set(neighborPath, distance + 1);
+        next.add(neighborPath);
+      }
+    }
+    frontier = [...next];
+  }
+  const nodes = [...distanceByPath].map(([path, distance]) => {
+    const note = notesByPath.get(path);
+    return note === undefined ? null : connectionNode(note, connectionsById.get(note.id), distance);
+  }).filter((node) => node !== null).toSorted((left, right) => left.distance - right.distance || left.path.localeCompare(right.path));
+  const sortedCandidates = [...selectedCandidates.values()].toSorted(compareTraversalCandidates);
+  const connectionLimit = returnedConnectionLimit(limit);
+  if (sortedCandidates.length > connectionLimit)
+    truncated = true;
+  const returnedCandidates = sortedCandidates.slice(0, connectionLimit);
+  const edges = returnedCandidates.filter((candidate) => candidate.kind === "link").map(({ edge }) => edge).toSorted((left, right) => left.source.localeCompare(right.source) || left.target.localeCompare(right.target) || left.line - right.line);
+  const relations = returnedCandidates.filter((candidate) => candidate.kind === "relation").map(({ relation }) => relation).toSorted((left, right) => left.source.localeCompare(right.source) || left.predicate.localeCompare(right.predicate) || left.target.localeCompare(right.target) || left.provenance.line - right.provenance.line);
+  return { note: start.path, direction, depth, limit, truncated, nodes, edges, relations };
+}
+
+export { MAX_NAVIGATION_INDEXED_CONNECTIONS, MAX_NAVIGATION_RETURNED_CONNECTIONS, NavigationBudgetError, navigateLinks };

package/dist/index-dfag79p7.js

@@ -0,0 +1,370 @@
+// @bun
+// src/clip/args.ts
+var captureModes = ["auto", "http", "browser", "file"];
+var captureScopes = ["auto", "page", "thread", "comments"];
+var mediaModes = ["none", "images", "all"];
+var evidenceModes = ["none", "source", "screenshot", "all"];
+var cookieSources = ["chrome", "arc", "brave", "chromium", "edge", "firefox", "safari"];
+function captureUrl(options) {
+  if (options.url === null)
+    throw new Error("the current browser target has not resolved its URL yet");
+  return options.url;
+}
+var DEFAULT_USER_AGENT = "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 " + "(KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36";
+var defaults = {
+  timeoutMs: 30000,
+  maxItems: 500,
+  maxDepth: 16,
+  maxHtmlBytes: 25 * 1024 * 1024,
+  maxAssetBytes: 100 * 1024 * 1024,
+  maxTotalAssetBytes: 500 * 1024 * 1024
+};
+var valueOptions = new Set([
+  "--mode",
+  "--scope",
+  "--media",
+  "--evidence",
+  "--html",
+  "--output",
+  "--browser-profile",
+  "--cdp",
+  "--cookie-profile",
+  "--cookies-file",
+  "--user-agent",
+  "--cookie-source",
+  "--timeout-ms",
+  "--max-items",
+  "--max-depth",
+  "--max-html-bytes",
+  "--max-asset-bytes",
+  "--max-total-asset-bytes"
+]);
+function enumValue(value, values, label) {
+  const match = values.find((candidate) => candidate === value);
+  return match === undefined ? { ok: false, message: `${label} must be one of ${values.join(", ")}` } : { ok: true, value: match };
+}
+function positiveInteger(value, label, maximum) {
+  if (!/^\d+$/.test(value))
+    return `${label} must be a positive integer`;
+  const parsed = Number(value);
+  if (!Number.isSafeInteger(parsed) || parsed < 1 || parsed > maximum) {
+    return `${label} must be between 1 and ${maximum}`;
+  }
+  return parsed;
+}
+function byteSize(value, label) {
+  const match = /^(\d+)(b|kb|mb|gb)?$/i.exec(value);
+  if (match === null || match[1] === undefined) {
+    return `${label} must be an integer byte size such as 500000, 25mb, or 1gb`;
+  }
+  const amount = Number(match[1]);
+  const unit = (match[2] ?? "b").toLowerCase();
+  const multiplier = unit === "gb" ? 1024 ** 3 : unit === "mb" ? 1024 ** 2 : unit === "kb" ? 1024 : 1;
+  const parsed = amount * multiplier;
+  if (!Number.isSafeInteger(parsed) || parsed < 1 || parsed > 8 * 1024 ** 3) {
+    return `${label} must be between 1 byte and 8gb`;
+  }
+  return parsed;
+}
+function readOptionValue(args, index, flag) {
+  const value = args[index + 1];
+  return value === undefined || value.startsWith("--") ? { ok: false, message: `${flag} requires a value` } : value;
+}
+function parseUrl(value, label = "URL") {
+  if (value.length > 64 * 1024)
+    return `${label} exceeds the 65536 code-unit safety limit`;
+  try {
+    const url = new URL(value);
+    if (url.protocol !== "http:" && url.protocol !== "https:")
+      return `${label} must use http or https`;
+    if (url.username !== "" || url.password !== "") {
+      return `${label} must not contain embedded credentials; use --cookies-file or a browser session`;
+    }
+    return url;
+  } catch {
+    return `${label} is not a valid URL`;
+  }
+}
+function parseArguments(rawArgs, environment = {}) {
+  if (rawArgs.length === 0 || rawArgs[0] === "help" || rawArgs[0] === "--help" || rawArgs[0] === "-h") {
+    return { ok: true, value: { command: "help" } };
+  }
+  const first = rawArgs[0];
+  if (first === "doctor" || first === "adapters") {
+    const extra = rawArgs.slice(1);
+    if (extra.some((value) => value !== "--json")) {
+      return { ok: false, message: `${first} only accepts --json` };
+    }
+    return { ok: true, value: { command: first, json: extra.includes("--json") } };
+  }
+  let command = "capture";
+  let cursor = 0;
+  if (first === "capture" || first === "inspect") {
+    command = first;
+    cursor += 1;
+  }
+  const positional = [];
+  let mode = "auto";
+  let scope = "auto";
+  let media = command === "inspect" ? "none" : "images";
+  let evidence = "none";
+  let mediaExplicit = false;
+  let evidenceExplicit = false;
+  let htmlFile;
+  let outputBase = environment.KB_CLIP_OUTPUT ?? "kb/articles";
+  let force = false;
+  let stdout = command === "inspect";
+  let stdoutExplicit = false;
+  let json = false;
+  let quiet = false;
+  let browserProfile;
+  let browserLive = false;
+  let cdp;
+  const selectedCookieSources = [];
+  let cookieProfile;
+  let cookiesFile;
+  let timeoutMs = defaults.timeoutMs;
+  let maxItems = defaults.maxItems;
+  let maxDepth = defaults.maxDepth;
+  let maxHtmlBytes = defaults.maxHtmlBytes;
+  let maxAssetBytes = defaults.maxAssetBytes;
+  let maxTotalAssetBytes = defaults.maxTotalAssetBytes;
+  let allowPrivateNetwork = false;
+  let userAgent = environment.KB_CLIP_USER_AGENT ?? DEFAULT_USER_AGENT;
+  for (;cursor < rawArgs.length; cursor += 1) {
+    const argument = rawArgs[cursor];
+    if (argument === undefined)
+      continue;
+    if (!argument.startsWith("--")) {
+      positional.push(argument);
+      continue;
+    }
+    if (argument === "--force")
+      force = true;
+    else if (argument === "--stdout") {
+      stdout = true;
+      stdoutExplicit = true;
+    } else if (argument === "--json")
+      json = true;
+    else if (argument === "--quiet")
+      quiet = true;
+    else if (argument === "--browser-live")
+      browserLive = true;
+    else if (argument === "--allow-private-network")
+      allowPrivateNetwork = true;
+    else {
+      if (!valueOptions.has(argument))
+        return { ok: false, message: `unknown option: ${argument}` };
+      const value = readOptionValue(rawArgs, cursor, argument);
+      if (typeof value !== "string")
+        return value;
+      cursor += 1;
+      if (argument === "--mode") {
+        const parsed = enumValue(value, captureModes, "--mode");
+        if (!parsed.ok)
+          return { ok: false, message: parsed.message };
+        mode = parsed.value;
+      } else if (argument === "--scope") {
+        const parsed = enumValue(value, captureScopes, "--scope");
+        if (!parsed.ok)
+          return { ok: false, message: parsed.message };
+        scope = parsed.value;
+      } else if (argument === "--media") {
+        const parsed = enumValue(value, mediaModes, "--media");
+        if (!parsed.ok)
+          return { ok: false, message: parsed.message };
+        media = parsed.value;
+        mediaExplicit = true;
+      } else if (argument === "--evidence") {
+        const parsed = enumValue(value, evidenceModes, "--evidence");
+        if (!parsed.ok)
+          return { ok: false, message: parsed.message };
+        evidence = parsed.value;
+        evidenceExplicit = true;
+      } else if (argument === "--html")
+        htmlFile = value;
+      else if (argument === "--output")
+        outputBase = value;
+      else if (argument === "--browser-profile")
+        browserProfile = value;
+      else if (argument === "--cdp") {
+        const parsed = positiveInteger(value, "--cdp", 65535);
+        if (typeof parsed === "string") {
+          return { ok: false, message: "--cdp accepts only a local remote-debugging port between 1 and 65535" };
+        }
+        cdp = String(parsed);
+      } else if (argument === "--cookie-profile")
+        cookieProfile = value;
+      else if (argument === "--cookies-file")
+        cookiesFile = value;
+      else if (argument === "--user-agent")
+        userAgent = value;
+      else if (argument === "--cookie-source") {
+        const parsed = enumValue(value, cookieSources, "--cookie-source");
+        if (!parsed.ok)
+          return { ok: false, message: parsed.message };
+        selectedCookieSources.push(parsed.value);
+      } else if (argument === "--timeout-ms") {
+        const parsed = positiveInteger(value, argument, 10 * 60000);
+        if (typeof parsed === "string")
+          return { ok: false, message: parsed };
+        timeoutMs = parsed;
+      } else if (argument === "--max-items") {
+        const parsed = positiveInteger(value, argument, 1e4);
+        if (typeof parsed === "string")
+          return { ok: false, message: parsed };
+        maxItems = parsed;
+      } else if (argument === "--max-depth") {
+        const parsed = positiveInteger(value, argument, 64);
+        if (typeof parsed === "string")
+          return { ok: false, message: parsed };
+        maxDepth = parsed;
+      } else if (argument === "--max-html-bytes") {
+        const parsed = byteSize(value, argument);
+        if (typeof parsed === "string")
+          return { ok: false, message: parsed };
+        maxHtmlBytes = parsed;
+      } else if (argument === "--max-asset-bytes") {
+        const parsed = byteSize(value, argument);
+        if (typeof parsed === "string")
+          return { ok: false, message: parsed };
+        maxAssetBytes = parsed;
+      } else if (argument === "--max-total-asset-bytes") {
+        const parsed = byteSize(value, argument);
+        if (typeof parsed === "string")
+          return { ok: false, message: parsed };
+        maxTotalAssetBytes = parsed;
+      }
+    }
+  }
+  if (positional.length === 0)
+    return { ok: false, message: `${command} requires a URL or current` };
+  if (positional.length > 2)
+    return { ok: false, message: `${command} accepts one URL/current target and one optional slug` };
+  const currentTab = positional[0] === "current";
+  const parsedUrl = currentTab ? null : parseUrl(positional[0] ?? "");
+  if (typeof parsedUrl === "string")
+    return { ok: false, message: parsedUrl };
+  if (mode === "file" && htmlFile === undefined)
+    return { ok: false, message: "--mode file requires --html <path|->" };
+  if (htmlFile !== undefined && mode !== "auto" && mode !== "file") {
+    return { ok: false, message: "--html can only be used with --mode auto or --mode file" };
+  }
+  if (browserLive && browserProfile !== undefined) {
+    return { ok: false, message: "--browser-live and --browser-profile are mutually exclusive" };
+  }
+  if (cdp !== undefined && (browserLive || browserProfile !== undefined)) {
+    return { ok: false, message: "--cdp cannot be combined with --browser-live or --browser-profile" };
+  }
+  if (currentTab && browserProfile !== undefined) {
+    return { ok: false, message: "the current target attaches with --browser-live or --cdp; it cannot use --browser-profile" };
+  }
+  if (currentTab && !browserLive && cdp === undefined) {
+    return { ok: false, message: "the current target requires --browser-live or --cdp <loopback-port>" };
+  }
+  const hasBrowserSelection = browserLive || cdp !== undefined || browserProfile !== undefined;
+  if (hasBrowserSelection && (mode === "http" || mode === "file" || htmlFile !== undefined)) {
+    return { ok: false, message: "browser selection requires --mode auto or --mode browser and cannot be combined with --html" };
+  }
+  if ((evidence === "screenshot" || evidence === "all") && (mode === "http" || mode === "file" || htmlFile !== undefined)) {
+    return { ok: false, message: "screenshot evidence requires --mode auto or --mode browser" };
+  }
+  if (selectedCookieSources.length > 1) {
+    return { ok: false, message: "select at most one --cookie-source so profile and media behavior stay unambiguous" };
+  }
+  if (selectedCookieSources.length > 0 && cookiesFile !== undefined) {
+    return { ok: false, message: "--cookie-source and --cookies-file are mutually exclusive authentication sources" };
+  }
+  if (cookieProfile !== undefined && selectedCookieSources.length === 0) {
+    return { ok: false, message: "--cookie-profile requires at least one --cookie-source" };
+  }
+  if (maxTotalAssetBytes < maxAssetBytes) {
+    return { ok: false, message: "--max-total-asset-bytes cannot be smaller than --max-asset-bytes" };
+  }
+  if (stdoutExplicit && json)
+    return { ok: false, message: "--stdout and --json cannot be combined" };
+  if (stdout && force)
+    return { ok: false, message: "--stdout and --force cannot be combined" };
+  if (command === "inspect" && media !== "none") {
+    return { ok: false, message: "inspect does not persist media; use capture or pass --media none" };
+  }
+  if (command === "inspect" && evidence !== "none") {
+    return { ok: false, message: "inspect does not persist evidence; use capture or pass --evidence none" };
+  }
+  if (stdout && mediaExplicit && media !== "none") {
+    return { ok: false, message: "--stdout does not persist media; use capture without --stdout or pass --media none" };
+  }
+  if (stdout && evidenceExplicit && evidence !== "none") {
+    return { ok: false, message: "--stdout does not persist evidence; use capture without --stdout or pass --evidence none" };
+  }
+  return {
+    ok: true,
+    value: {
+      command,
+      url: parsedUrl,
+      currentTab,
+      slug: positional[1],
+      mode: htmlFile === undefined ? currentTab ? "browser" : mode : "file",
+      scope,
+      media: stdout ? "none" : media,
+      evidence: stdout ? "none" : evidence,
+      htmlFile,
+      outputBase,
+      force,
+      stdout,
+      json,
+      quiet,
+      browserProfile,
+      browserLive,
+      cdp,
+      cookieSources: selectedCookieSources,
+      cookieProfile,
+      cookiesFile,
+      timeoutMs,
+      maxItems,
+      maxDepth,
+      maxHtmlBytes,
+      maxAssetBytes,
+      maxTotalAssetBytes,
+      allowPrivateNetwork,
+      userAgent
+    }
+  };
+}
+var usage = `Usage:
+  wordcell clip <url> [slug] [options]
+  wordcell clip current [slug] --browser-live [options]
+  wordcell clip current [slug] --cdp <loopback-port> [options]
+  wordcell clip capture <url> [slug] [options]
+  wordcell clip inspect <url> [options]
+  wordcell doctor [--json]
+  wordcell adapters [--json]
+
+Capture options:
+  --mode auto|http|browser|file     Acquisition strategy (default: auto)
+  --scope auto|page|thread|comments Content scope (default: platform-aware)
+  --html <path|->                  Parse saved/rendered HTML; - reads stdin
+  --browser-profile <name|path>    Use a signed-in or persistent Chrome profile
+  --browser-live                   Attach to a live Chrome session
+  --cdp <loopback-port>            Attach to a local CDP-capable browser
+  --cookie-source <browser>        chrome|arc|brave|chromium|edge|firefox|safari
+  --cookie-profile <name|path>     Browser profile; Safari expects a Cookies.binarycookies path
+  --cookies-file <path>            Cookie-Editor JSON/base64, Netscape, Cookie header, or cURL input
+  --media none|images|all          Localize images or all supported media
+  --evidence none|source|screenshot|all
+  --output <directory>             Output base (default: kb/articles)
+  --stdout                         Print Markdown without writing a clip
+  --json                           Print a machine-readable result summary
+  --force                          Atomically replace an existing clip
+  --timeout-ms <n>                 Per-request/process/extraction timeout
+  --max-items <n>                  Bound comments/thread items (default: 500)
+  --max-depth <n>                  Bound nested replies (default: 16)
+  --max-html-bytes <size>          HTML cap (default: 25mb)
+  --max-asset-bytes <size>         Per-asset cap (default: 100mb)
+  --max-total-asset-bytes <size>   Total asset cap (default: 500mb)
+  --allow-private-network          Permit private targets in every network lane
+  --user-agent <value>             Override the browser-like user agent
+  --quiet                          Suppress progress output
+`;
+
+export { captureModes, captureScopes, mediaModes, evidenceModes, cookieSources, captureUrl, parseArguments, usage };

package/dist/index-e4fagfjz.js

@@ -0,0 +1,44 @@
+// @bun
+import {
+  defineWorkflow
+} from "./index-h170byqw.js";
+
+// src/workflows/explain-change.ts
+var explainChangeWorkflow = defineWorkflow({
+  id: "explain-change",
+  nodes: [
+    {
+      id: "rationale",
+      resource: "qmd",
+      run: ({ input, kb }) => kb.search({
+        query: input.query,
+        history: false,
+        ...input.resultLimit === undefined ? {} : { limit: input.resultLimit }
+      })
+    },
+    {
+      id: "evolution",
+      resource: "git",
+      run: ({ input, kb }) => kb.searchHistory({
+        query: input.historyQuery ?? input.query,
+        ...input.historyLimit === undefined ? {} : { limit: input.historyLimit }
+      })
+    },
+    {
+      id: "neighborhood",
+      run: ({ input, kb }) => input.note === undefined ? null : kb.links(input.note, { direction: "both", depth: 1, limit: 20 })
+    },
+    {
+      id: "assemble",
+      needs: ["rationale", "evolution", "neighborhood"],
+      run: ({ result }) => ({
+        rationale: result("rationale"),
+        evolution: result("evolution"),
+        neighborhood: result("neighborhood")
+      })
+    }
+  ],
+  output: "assemble"
+});
+
+export { explainChangeWorkflow };