@hraness/wordcell 0.21.2 → 0.22.0

package/src/serve.ts

@@ -0,0 +1,180 @@
+import { realpath, stat } from "node:fs/promises";
+import { join, sep } from "node:path";
+
+const MAX_PATH_BYTES = 8 * 1_024;
+
+const CONTENT_TYPES: Readonly<Record<string, string>> = Object.freeze({
+  ".avif": "image/avif",
+  ".css": "text/css; charset=utf-8",
+  ".gif": "image/gif",
+  ".html": "text/html; charset=utf-8",
+  ".ico": "image/x-icon",
+  ".jpeg": "image/jpeg",
+  ".jpg": "image/jpeg",
+  ".js": "text/javascript; charset=utf-8",
+  ".json": "application/json; charset=utf-8",
+  ".map": "application/json; charset=utf-8",
+  ".mp3": "audio/mpeg",
+  ".mp4": "video/mp4",
+  ".pdf": "application/pdf",
+  ".png": "image/png",
+  ".svg": "image/svg+xml",
+  ".txt": "text/plain; charset=utf-8",
+  ".wasm": "application/wasm",
+  ".wav": "audio/wav",
+  ".webm": "video/webm",
+  ".webp": "image/webp",
+  ".woff": "font/woff",
+  ".woff2": "font/woff2",
+  ".xml": "application/xml; charset=utf-8",
+});
+
+export type ServeSiteOptions = Readonly<{
+  root: string;
+  host?: string;
+  port?: number;
+}>;
+
+export type ServeListener = Readonly<{
+  hostname: string;
+  port: number;
+  stop: () => void;
+}>;
+
+export type ServeListen = (init: Readonly<{
+  hostname: string;
+  port: number;
+  fetch: (request: Request) => Response | Promise<Response>;
+}>) => ServeListener;
+
+export type ServeIo = Readonly<{
+  listen?: ServeListen;
+}>;
+
+export type ServedSite = Readonly<{
+  root: string;
+  host: string;
+  port: number;
+  url: string;
+  close: () => void;
+}>;
+
+function contentType(path: string): string {
+  const extension = path.slice(path.lastIndexOf("."));
+  return CONTENT_TYPES[extension] ?? "application/octet-stream";
+}
+
+async function regularFileUnder(rootReal: string, candidate: string): Promise<string | null> {
+  let resolved: string;
+  try {
+    resolved = await realpath(candidate);
+  } catch {
+    return null;
+  }
+  if (resolved !== rootReal && !resolved.startsWith(`${rootReal}${sep}`)) return null;
+  try {
+    return (await stat(resolved)).isFile() ? resolved : null;
+  } catch {
+    return null;
+  }
+}
+
+async function resolveRequest(rootReal: string, pathname: string): Promise<string | null> {
+  let decoded: string;
+  try {
+    decoded = decodeURIComponent(pathname);
+  } catch {
+    return null;
+  }
+  if (decoded.includes("\0") || decoded.includes("\\")) return null;
+  const segments = decoded.split("/").filter((segment) => segment !== "" && segment !== ".");
+  if (segments.some((segment) => segment === "..")) return null;
+  const relative = segments.join("/");
+  const candidates = [
+    join(rootReal, relative),
+    join(rootReal, relative, "index.html"),
+  ];
+  for (const candidate of candidates) {
+    const file = await regularFileUnder(rootReal, candidate);
+    if (file !== null) return file;
+  }
+  return null;
+}
+
+export async function createServeHandler(
+  root: string,
+): Promise<(request: Request) => Promise<Response>> {
+  const rootReal = await realpath(root);
+  return async (request) => {
+    const method = request.method.toUpperCase();
+    if (method !== "GET" && method !== "HEAD") {
+      return new Response("Method not allowed", { status: 405 });
+    }
+    let pathname: string;
+    try {
+      pathname = new URL(request.url).pathname;
+    } catch {
+      return new Response("Bad request", { status: 400 });
+    }
+    if (pathname.length > MAX_PATH_BYTES) {
+      return new Response("URI too long", { status: 414 });
+    }
+    const head = method === "HEAD";
+    const file = await resolveRequest(rootReal, pathname);
+    if (file !== null) {
+      const body = Bun.file(file);
+      return new Response(head ? null : body, {
+        headers: {
+          "Cache-Control": "no-store",
+          "Content-Length": String(body.size),
+          "Content-Type": contentType(file),
+        },
+      });
+    }
+    const notFound = await regularFileUnder(rootReal, join(rootReal, "404.html"));
+    if (notFound !== null) {
+      const body = Bun.file(notFound);
+      return new Response(head ? null : body, {
+        status: 404,
+        headers: {
+          "Cache-Control": "no-store",
+          "Content-Length": String(body.size),
+          "Content-Type": "text/html; charset=utf-8",
+        },
+      });
+    }
+    return new Response(head ? null : "Not found", {
+      status: 404,
+      headers: { "Cache-Control": "no-store" },
+    });
+  };
+}
+
+export async function serveSite(
+  options: ServeSiteOptions,
+  io: ServeIo = {},
+): Promise<ServedSite> {
+  const host = options.host ?? "127.0.0.1";
+  const port = options.port ?? 8080;
+  if (!Number.isSafeInteger(port) || port < 0 || port > 65_535) {
+    throw new Error("Port must be an integer from 0 through 65535");
+  }
+  const rootReal = await realpath(options.root);
+  if (!(await stat(rootReal)).isDirectory()) {
+    throw new Error(`Site root is not a directory: ${options.root}`);
+  }
+  const listen = io.listen ?? ((init) => Bun.serve(init));
+  const server = listen({
+    hostname: host,
+    port,
+    fetch: await createServeHandler(rootReal),
+  });
+  const boundPort = server.port ?? port;
+  return Object.freeze({
+    root: rootReal,
+    host,
+    port: boundPort,
+    url: `http://${host}:${String(boundPort)}/`,
+    close: () => server.stop(),
+  });
+}

package/src/support-profile.ts

@@ -0,0 +1,7 @@
+/** Public presentation data only. Accounts owns current plans and consent. */
+export const supportProfile = {
+  id: "kb",
+  name: "Wordcell",
+  valueProposition: "Support ongoing development of inspectable Markdown memory for coding agents.",
+  updates: false,
+} as const;

package/src/support.ts

@@ -0,0 +1,73 @@
+import { maybeShowSupportInvitation, runSupportCommand, type SupportCommandOptions } from "@hraness/support-foundation/node";
+import { parseArguments } from "./cli-program.js";
+import { parseArguments as parseCaptureArguments } from "./clip/args.js";
+import { parseUrlMetadataArguments } from "./clip/url-metadata-cli.js";
+import { parsePdfArguments } from "./pdf/args.js";
+import { supportProfile } from "./support-profile.js";
+
+/** Called only by the standalone executable. Nested children inherit quiet mode. */
+export function standaloneSupportEnvironment(): Readonly<Record<string, string | undefined>> {
+  const environment = { ...process.env };
+  process.env.HRANESS_SUPPORT_AUDIENCE = "off";
+  return environment;
+}
+
+/** Positive completed-work classification. New command kinds stay quiet by default. */
+export function isUsefulSupportResult(args: readonly string[], environment: Readonly<Record<string, string | undefined>>): boolean {
+  const parsed = parseArguments(args);
+  if (!parsed.ok) return false;
+  const command = parsed.value;
+  switch (command.kind) {
+    case "init":
+    case "refresh":
+    case "graph":
+    case "graph-rebuild":
+    case "graph-query":
+    case "backlinks":
+    case "links":
+    case "catalog":
+    case "context":
+    case "index":
+    case "search":
+    case "history":
+    case "list":
+    case "inbox":
+    case "note-create":
+    case "relation":
+    case "percolate":
+    case "portfolio-search":
+    case "capture-diff":
+      return true;
+    case "capture-bundle":
+      return command.action === "show";
+    case "clip": {
+      const capture = parseCaptureArguments(command.arguments, environment);
+      return capture.ok && (capture.value.command === "capture" || capture.value.command === "inspect") && !capture.value.quiet;
+    }
+    case "pdf": {
+      const pdf = parsePdfArguments(command.arguments, environment);
+      return pdf.ok && pdf.value.command === "capture" && !pdf.value.quiet;
+    }
+    case "url-metadata": {
+      const metadata = parseUrlMetadataArguments(command.arguments, environment);
+      return metadata.ok && metadata.value.kind === "backfill";
+    }
+    default:
+      return false;
+  }
+}
+
+export async function runProductSupportCommand(args: readonly string[], options: SupportCommandOptions = {}): Promise<number> {
+  const result = await runSupportCommand(supportProfile, args, { command: ["wordcell"], gitEmail: false, ...options });
+  if (result.stdout !== "") process.stdout.write(result.stdout);
+  if (result.stderr !== "") process.stderr.write(result.stderr);
+  return result.exitCode;
+}
+
+export async function showProductSupportInvitation(options: SupportCommandOptions = {}): Promise<void> {
+  try {
+    await maybeShowSupportInvitation(supportProfile, { command: ["wordcell"], usefulResult: true, gitEmail: false, ...options });
+  } catch {
+    // Optional support must preserve the completed command's output and exit status.
+  }
+}

package/src/vault.ts

@@ -548,20 +548,34 @@ async function snapshot(
       ? {}
       : { maxTotalBytes: options.maxTotalBytes }),
   });
-  const indexRevision = await readIndexRevision(
-    root,
-    indexPath,
-    options.maxNoteBytes ?? MAX_NOTE_UTF8_BYTES,
-  );
-  const currentIndex = indexRevision.content;
-  const indexNote = parseNote(vaultIndexPath, currentIndex);
-  const catalogMode = parsedCatalogMode(
+  const configuredCatalogMode = parsedCatalogMode(
     options.catalogMode,
     "ScanVaultOptions.catalogMode",
-  ) ?? declaredCatalogMode(indexNote) ?? "managed";
+  );
+  let indexRevision: IndexRevision | undefined;
+  try {
+    indexRevision = await readIndexRevision(
+      root,
+      indexPath,
+      options.maxNoteBytes ?? MAX_NOTE_UTF8_BYTES,
+    );
+  } catch (error: unknown) {
+    const absent = error instanceof Error && "code" in error && error.code === "ENOENT";
+    // Ordinary Markdown folders can be queried without creating a front door.
+    // Explicit index contracts and writes still require the real authored file.
+    if (!absent || options.index !== undefined || configuredCatalogMode === "managed"
+      || notes.some((note) => note.path === vaultIndexPath)) throw error;
+    if (writeIndex) {
+      throw new Error("Refresh requires an index.md front door. Add one with kb_catalog: authored to preserve its contents, or catalog markers for a managed catalog. Search and graph commands can read this folder without one.", { cause: error });
+    }
+  }
+  const currentIndex = indexRevision?.content ?? "";
+  const catalogMode = configuredCatalogMode
+    ?? (indexRevision === undefined ? "authored" : declaredCatalogMode(parseNote(vaultIndexPath, currentIndex)) ?? "managed");
   let index: VaultIndexState = "authored";
 
   if (catalogMode === "managed") {
+    if (indexRevision === undefined) throw new Error("A managed catalog requires an existing index file.");
     const expectedIndex = replaceCatalog(
       currentIndex,
       renderCatalog(notes, catalogNoteId),

package/dist/{index-why54q5p.js → index-gm9t95d9.js}

@@ -1,10 +1,10 @@
 // @bun
-import {
-  queryVault
-} from "./index-48pz4jpc.js";
 import {
   navigateLinks
 } from "./index-d13v9ckt.js";
+import {
+  queryVault
+} from "./index-48pz4jpc.js";
 import {
   lookupNote
 } from "./index-ekpwvbra.js";