@hraness/wordcell 0.25.1 → 0.26.1

package/src/cli-startup.ts

@@ -0,0 +1,76 @@
+import { commandWordCount, resolveCommandId, valueOptions } from "./cli-help.js";
+
+export type StartupCommand =
+  | { readonly kind: "help"; readonly topic?: string }
+  | { readonly kind: "version"; readonly json: boolean }
+  | { readonly kind: "clip"; readonly arguments: readonly string[] }
+  | { readonly kind: "pdf"; readonly arguments: readonly string[] }
+  | { readonly kind: "url-metadata"; readonly arguments: readonly string[] };
+export type StartupParseResult =
+  | { readonly ok: true; readonly value: StartupCommand }
+  | { readonly ok: false; readonly message: string };
+
+function isHelpFlag(argument: string | undefined): boolean {
+  return argument === "--help" || argument === "-h";
+}
+
+/** Help for delegated commands comes from their own parsers. */
+function delegatedHelp(first: string): StartupCommand | undefined {
+  if (first === "clip" || first === "inspect") return { kind: "clip", arguments: ["help"] };
+  if (first === "pdf") return { kind: "pdf", arguments: ["--help"] };
+  if (first === "url-metadata") return { kind: "url-metadata", arguments: ["--help"] };
+  return undefined;
+}
+
+/** `help`, `help advanced`, and `help <command...>`. */
+function parseHelpTopic(words: readonly string[]): StartupParseResult {
+  const topic = words.filter((word) => !isHelpFlag(word) && word !== "--json");
+  if (topic.length === 0) return { ok: true, value: { kind: "help" } };
+  if (topic.length === 1 && topic[0] === "advanced") return { ok: true, value: { kind: "help", topic: "advanced" } };
+  const delegated = delegatedHelp(topic[0] ?? "");
+  if (delegated !== undefined) return { ok: true, value: delegated };
+  const id = resolveCommandId(topic);
+  if (id === undefined) return { ok: false, message: "unknown help topic" };
+  return { ok: true, value: { kind: "help", topic: id } };
+}
+
+/**
+ * `<command> --help` anywhere a person would type it: right after the command
+ * words, or as the last argument when it is not the value of an option.
+ */
+function embeddedHelp(arguments_: readonly string[]): StartupParseResult | undefined {
+  const separator = arguments_.indexOf("--");
+  const end = separator === -1 ? arguments_.length : separator;
+  const index = arguments_.slice(0, end).findIndex(isHelpFlag);
+  if (index <= 0) return undefined;
+  const delegated = delegatedHelp(arguments_[0] ?? "");
+  if (delegated !== undefined) {
+    return index === 1 || index === end - 1 ? { ok: true, value: delegated } : undefined;
+  }
+  const id = resolveCommandId(arguments_.slice(0, index).filter((word) => !word.startsWith("-")));
+  if (id === undefined) return undefined;
+  const words = commandWordCount(id);
+  const previous = arguments_[index - 1] ?? "";
+  // `--help` is never an option value; `-h` could be one, as in `--body -h`.
+  const flag = arguments_[index];
+  const lastArgument = index === end - 1 && (flag === "--help" || !valueOptions(id).has(previous));
+  if (index !== words && !lastArgument) return undefined;
+  return { ok: true, value: { kind: "help", topic: id } };
+}
+
+/** The executable and public parser share the same help/version grammar. */
+export function parseCliStartupCommand(arguments_: readonly string[]): StartupParseResult | undefined {
+  const command = arguments_[0];
+  if (command === undefined) return { ok: true, value: { kind: "help", topic: "start" } };
+  if (command === "help" || isHelpFlag(command)) return parseHelpTopic(arguments_.slice(1));
+  if (command === "--version" || command === "-V" || command === "-v" || command === "version") {
+    return { ok: true, value: { kind: "version", json: arguments_.includes("--json") } };
+  }
+  const help = embeddedHelp(arguments_);
+  if (help !== undefined) return help;
+  if ((command === "clip" || command === "capture" || command === "inspect")
+    && ["--help", "-h", "help"].includes(arguments_[1] ?? "")) {
+    return { ok: true, value: { kind: "clip", arguments: ["help"] } };
+  }
+  return undefined;
+}

package/src/cli-update.ts

@@ -0,0 +1,53 @@
+import { runCliUpdate, type CliUpdateOptions } from "@hraness/cli-update";
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { findKbPackageRoot } from "./clip/package-root.js";
+import { parseCliStartupCommand } from "./cli-startup.js";
+import { isEvaluationBuilderHelp } from "./evaluation-builder-cli-args.js";
+
+export type WordcellBin = "wordcell" | "wordcell-evaluation-builder";
+
+export function wordcellUpdateOptions(bin: WordcellBin, entrypoint: string, argv: readonly string[]): CliUpdateOptions {
+  const packageRoot = findKbPackageRoot(dirname(entrypoint));
+  const manifest: unknown = JSON.parse(readFileSync(join(packageRoot, "package.json"), "utf8"));
+  if (manifest === null || typeof manifest !== "object" || !("version" in manifest) || typeof manifest.version !== "string") {
+    throw new Error("Wordcell package version is missing.");
+  }
+  const effectFree = bin === "wordcell" ? parseCliStartupCommand(argv) !== undefined : isEvaluationBuilderHelp(argv);
+  return {
+    packageName: "@hraness/wordcell", version: manifest.version, binName: bin, entrypoint,
+    argv: effectFree && argv[0] === "update" ? ["--help"] : argv,
+    provider: { kind: "github", repository: "hraness/wordcell", tagPrefix: "v", assetName: "hraness-wordcell-{version}.tgz" },
+    ignoreScripts: true,
+    effectFree,
+    suppressAutomatic: bin === "wordcell" && argv[0] === "support",
+    async verifyArtifact(artifact) {
+      const { verifyUpdateArtifact } = await import("./cli-release.js");
+      await verifyUpdateArtifact(artifact);
+    },
+  };
+}
+
+/** Admission precedes imports of vault, capture, support, or evaluation code. */
+export async function runWordcellBin(
+  bin: WordcellBin,
+  entrypoint: string,
+  argv: readonly string[],
+  dependencies: { update?: typeof runCliUpdate; run?: () => Promise<number> } = {},
+): Promise<number> {
+  const update = await (dependencies.update ?? runCliUpdate)(wordcellUpdateOptions(bin, entrypoint, argv));
+  if (update.handled) return update.exitCode;
+  try {
+    if (dependencies.run) return await dependencies.run();
+    if (bin === "wordcell") {
+      const { runStandaloneCli } = await import("./cli.js");
+      return await runStandaloneCli(argv);
+    }
+    const { runKbEvidenceRoutingBuildCli, kbEvidenceRoutingBuildUsage } = await import("./evaluation-builder.js");
+    if (isEvaluationBuilderHelp(argv)) console.log(kbEvidenceRoutingBuildUsage);
+    else await runKbEvidenceRoutingBuildCli(argv);
+    return 0;
+  } finally {
+    await update.release();
+  }
+}

package/src/cli.ts

@@ -3,15 +3,16 @@ import { runExecutable } from "./cli-program.js";
 
 export * from "./cli-program.js";
 
-if (import.meta.main) {
+export async function runStandaloneCli(args: readonly string[] = process.argv.slice(2)): Promise<number> {
   const { standaloneSupportEnvironment, isUsefulSupportResult, runProductSupportCommand, showProductSupportInvitation } = await import("./support.js");
   const env = standaloneSupportEnvironment();
-  const args = process.argv.slice(2);
   if (args[0] === "support") {
-    process.exitCode = await runProductSupportCommand(args.slice(1), { env });
+    return await runProductSupportCommand(args.slice(1), { env });
   } else {
     const exitCode = await runExecutable(args);
-    process.exitCode = exitCode;
     if (exitCode === 0 && isUsefulSupportResult(args, env)) await showProductSupportInvitation({ env });
+    return exitCode;
   }
 }
+
+if (import.meta.main) process.exitCode = await runStandaloneCli();

package/src/evaluation-builder-bin.ts

@@ -0,0 +1,5 @@
+#!/usr/bin/env bun
+import { fileURLToPath } from "node:url";
+import { runWordcellBin } from "./cli-update.js";
+
+if (import.meta.main) process.exitCode = await runWordcellBin("wordcell-evaluation-builder", fileURLToPath(import.meta.url), process.argv.slice(2));

package/src/evaluation-builder-cli-args.ts

@@ -0,0 +1,30 @@
+export const kbEvidenceRoutingBuildUsage =
+  "Usage: wordcell-evaluation-builder <--anchor-seal|--build> --config <checked-config.json> --artifact-root <artifact-B>\n"
+  + "       wordcell-evaluation-builder update [check|status|enable|disable] [--json]";
+
+export function parseKbEvidenceRoutingBuildCliArguments(arguments_: readonly string[]): {
+  readonly mode: "anchor-seal" | "build";
+  readonly configPath: string;
+  readonly artifactRoot: string;
+} {
+  const mode = arguments_[0];
+  const configPath = arguments_[2];
+  const artifactRoot = arguments_[4];
+  if (
+    arguments_.length !== 5
+    || (mode !== "--anchor-seal" && mode !== "--build")
+    || arguments_[1] !== "--config"
+    || arguments_[3] !== "--artifact-root"
+    || configPath === undefined
+    || configPath.trim() === ""
+    || artifactRoot === undefined
+    || artifactRoot.trim() === ""
+  ) {
+    throw new Error(kbEvidenceRoutingBuildUsage);
+  }
+  return Object.freeze({ mode: mode.slice(2) as "anchor-seal" | "build", configPath, artifactRoot });
+}
+
+export function isEvaluationBuilderHelp(arguments_: readonly string[]): boolean {
+  return arguments_.length === 1 && (arguments_[0] === "--help" || arguments_[0] === "-h");
+}

package/src/evaluation-builder.ts

@@ -1,4 +1,6 @@
 #!/usr/bin/env bun
+import { isEvaluationBuilderHelp, kbEvidenceRoutingBuildUsage, parseKbEvidenceRoutingBuildCliArguments } from "./evaluation-builder-cli-args.js";
+export { kbEvidenceRoutingBuildUsage, parseKbEvidenceRoutingBuildCliArguments } from "./evaluation-builder-cli-args.js";
 
 import { createHash, randomBytes } from "node:crypto";
 import { constants as fsConstants } from "node:fs";
@@ -2459,32 +2461,6 @@ export async function buildKbEvidenceRoutingEvaluation(
   };
 }
 
-export const kbEvidenceRoutingBuildUsage =
-  "Usage: wordcell-evaluation-builder <--anchor-seal|--build> --config <checked-config.json> --artifact-root <artifact-B>";
-
-export function parseKbEvidenceRoutingBuildCliArguments(arguments_: readonly string[]): {
-  readonly mode: "anchor-seal" | "build";
-  readonly configPath: string;
-  readonly artifactRoot: string;
-} {
-  const mode = arguments_[0];
-  const configPath = arguments_[2];
-  const artifactRoot = arguments_[4];
-  if (
-    arguments_.length !== 5
-    || (mode !== "--anchor-seal" && mode !== "--build")
-    || arguments_[1] !== "--config"
-    || arguments_[3] !== "--artifact-root"
-    || configPath === undefined
-    || configPath.trim() === ""
-    || artifactRoot === undefined
-    || artifactRoot.trim() === ""
-  ) {
-    throw new Error(kbEvidenceRoutingBuildUsage);
-  }
-  return Object.freeze({ mode: mode.slice(2) as "anchor-seal" | "build", configPath, artifactRoot });
-}
-
 export async function runKbEvidenceRoutingBuildCli(
   arguments_: readonly string[],
   dependencies: Pick<KbEvidenceRoutingEvaluationBuildDependencies, "runGit"> = {},
@@ -2518,7 +2494,7 @@ export async function runKbEvidenceRoutingBuildCli(
 
 if (import.meta.main) {
   const arguments_ = process.argv.slice(2);
-  if (arguments_.length === 1 && (arguments_[0] === "--help" || arguments_[0] === "-h")) {
+  if (isEvaluationBuilderHelp(arguments_)) {
     console.log(kbEvidenceRoutingBuildUsage);
   } else {
     await runKbEvidenceRoutingBuildCli(arguments_);

package/src/import-supermemory.ts

@@ -828,7 +828,9 @@ export function occupancyKey(value: string): string {
 
 /** Validate `--prefix` as a vault-relative directory note-ID prefix. */
 export function normalizePrefix(prefix: string): string {
-  const trimmed = prefix.replace(/\/+$/u, "");
+  let end = prefix.length;
+  while (end > 0 && prefix.charCodeAt(end - 1) === 47) end -= 1;
+  const trimmed = prefix.slice(0, end);
   let canonical: string | undefined;
   try {
     canonical = canonicalNoteId(trimmed);

package/dist/{index-hxyjer3x.js → index-hacpnaew.js}

@@ -1,13 +1,13 @@
 // @bun
+import {
+  sanitizeArtifactUrl
+} from "./index-mxxxytys.js";
 import {
   assertSafeNetworkUrl,
   decodeBytes,
   isPrivateHostname,
   safeFetch
 } from "./index-e5fbsywq.js";
-import {
-  sanitizeArtifactUrl
-} from "./index-mxxxytys.js";
 
 // src/clip/url-intelligence.ts
 var MAX_METADATA_SEARCH_RESULTS = 20;

package/dist/{index-qfqjfxaa.js → index-m9p2a4mj.js}

@@ -11,16 +11,16 @@ import {
   terminalOutput,
   yamlString
 } from "./index-cd75vky9.js";
+import {
+  redactSensitiveText,
+  sanitizeArtifactUrl
+} from "./index-mxxxytys.js";
 import {
   safeFetch
 } from "./index-e5fbsywq.js";
 import {
   BoundedByteBuffer
 } from "./index-gh719d91.js";
-import {
-  redactSensitiveText,
-  sanitizeArtifactUrl
-} from "./index-mxxxytys.js";
 import {
   sanitizeTerminalLine,
   sanitizeTerminalText

package/dist/{index-xwxy71ew.js → index-ncwzmsge.js}

@@ -8,6 +8,9 @@ import {
   readCookieFile,
   renderCookieHeader
 } from "./index-2gv8y733.js";
+import {
+  sanitizeArtifactUrl
+} from "./index-mxxxytys.js";
 import {
   startNetworkProxy
 } from "./index-w2zc0vwa.js";
@@ -16,15 +19,12 @@ import {
   decodeBytes,
   safeFetch
 } from "./index-e5fbsywq.js";
-import {
-  captureUrl
-} from "./index-byz4kzww.js";
 import {
   readBoundedByteStream
 } from "./index-gh719d91.js";
 import {
-  sanitizeArtifactUrl
-} from "./index-mxxxytys.js";
+  captureUrl
+} from "./index-byz4kzww.js";
 import {
   findKbPackageRoot,
   resolvePackageDirectory

package/dist/{index-e26mdwxz.js → index-wqx1x32f.js}

@@ -1,7 +1,4 @@
 // @bun
-import {
-  percolateVault
-} from "./index-bdwcjvr4.js";
 import {
   createGraphSnapshot,
   openGraphAuthority
@@ -10,6 +7,9 @@ import {
   GraphAuthorityError,
   validateGraphPercolationOptions
 } from "./index-pgtm2nhf.js";
+import {
+  percolateVault
+} from "./index-bdwcjvr4.js";
 import {
   analyzeVault,
   lookupNote,