@mulmoclaude/core 1.7.0 → 1.8.0

package/assets/helps/error-recovery.md

@@ -623,3 +623,49 @@ queue of paths, with one short-delay retry on 429. See the throttled-resolver
 example in `custom-view.md` ("Displaying images"). Do NOT widen the server
 cap, switch to base64-embedding images in the HTML, or treat the 429'd paths
 as bad values.
+
+## An API key in `.env` has no effect — the shell is shadowing it
+
+### Symptoms
+
+- The user says they put a key (`GEMINI_API_KEY`, `OPENAI_API_KEY`, …) in
+  `.env` and restarted, but generation still fails with an auth / 401 /
+  "API key not valid" error from the provider.
+- They may have edited `.env` several times, each time with no change.
+- The bell may show **"Shell env is overriding .env"**, and the server log
+  a `[shadowed-env]` warning naming the keys.
+
+### Cause
+
+An exported shell variable beats the file. `.env` is loaded with
+no-override semantics, so if `~/.zshrc` (or the current shell) still holds
+`export GEMINI_API_KEY=<old value>`, the file's value is read and
+discarded. Editing `.env` cannot fix it, which is why the loop repeats.
+
+An **empty** export shadows just as hard: `export GEMINI_API_KEY=` counts
+as set, so the provider receives an empty key while a perfectly good one
+sits in `.env`.
+
+Two files can be shadowed this way — the directory the user launched from
+(`npx mulmoclaude`) and the server's own working directory (`yarn dev`).
+
+### Fix
+
+Have the user check the shell, not the file. Test whether the variable
+is **set**, not whether it prints something — `export GEMINI_API_KEY=`
+prints nothing and still shadows, which is the case `echo` cannot see:
+
+```bash
+[ -n "${GEMINI_API_KEY+x}" ] && echo "set in the shell — this is what the app uses" \
+                             || echo "not set — the shell is not the problem"
+```
+
+If it reports "set", that shell value is what the app is using, whatever
+`.env` says. Either correct the export, or remove it — from the current
+shell AND from `~/.zshrc` / `~/.bashrc`, or the next terminal brings it
+straight back — so the `.env` value takes effect. Restart the app
+afterwards; the load happens once at boot.
+
+Do NOT tell the user to re-check the spelling in `.env`, add the key
+again, or move it elsewhere; the file is already correct, and it is being
+read. The conflict is the whole problem.

package/dist/artifacts/paths.cjs

@@ -57,10 +57,53 @@ function toWorkspaceArtifactPath(relPath) {
 function hasUnsafePathSegment(value) {
 	return value.split("/").some((seg) => seg === "" || seg === "." || seg === "..");
 }
+var WINDOWS_DRIVE_RE = /^[a-zA-Z]:[\\/]/;
+/** True when `value` names a location that does not depend on a base directory.
+*  Exported so a URL builder and a path resolver cannot disagree about which
+*  values are rooted. */
+function isAbsoluteFilePathValue(value) {
+	return value.startsWith("/") || value.startsWith("\\") || WINDOWS_DRIVE_RE.test(value);
+}
+/**
+* Classify a caller-supplied path to a file the host may read and overwrite.
+*
+* Accepts one of `extensions` (compared case-insensitively) and rejects NUL
+* bytes and any `.` / `..` / empty segment — a relative path must be canonical
+* so it can be joined onto a root, and an absolute one must not climb, so
+* neither form can be re-pointed by traversal after the host has vetted it.
+* Returns `"absolute"` / `"relative"` so the host knows whether to resolve
+* against its workspace root, or `null` when the value is unusable.
+*
+* This is a LEXICAL check only. Existence, file-vs-directory, symlink
+* containment and any host policy about which roots are reachable stay with
+* the host, which is the only layer that can consult the filesystem.
+*/
+function classifyFilePath(value, extensions) {
+	if (!value || value.includes("\0")) return null;
+	const lower = value.toLowerCase();
+	if (!extensions.some((ext) => lower.endsWith(ext))) return null;
+	const absolute = isAbsoluteFilePathValue(value);
+	const segments = value.split(/[/\\]/);
+	const body = absolute ? segments.slice(segments.findIndex((segment) => segment.length > 0)) : segments;
+	if (body.length === 0) return null;
+	if (body.some((segment) => segment === "" || segment === "." || segment === "..")) return null;
+	return absolute ? "absolute" : "relative";
+}
+/** True when any `/` or `\`-separated segment starts with a dot. The file
+*  servers that hand these pages to a browser refuse dotfile segments (the
+*  artifact mounts' `dotfiles: "deny"` policy), so a `path` argument bearing
+*  one can be accepted by a tool and then never render — the gate and the
+*  server have to agree on this, hence one definition. */
+function hasDotfileSegment(value) {
+	return value.split(/[/\\]/).some((segment) => segment.startsWith("."));
+}
 //#endregion
 exports.ARTIFACTS_ROOT = ARTIFACTS_ROOT;
 exports.buildArtifactRelPath = buildArtifactRelPath;
+exports.classifyFilePath = classifyFilePath;
+exports.hasDotfileSegment = hasDotfileSegment;
 exports.hasUnsafePathSegment = hasUnsafePathSegment;
+exports.isAbsoluteFilePathValue = isAbsoluteFilePathValue;
 exports.slugifyArtifact = slugifyArtifact;
 exports.toWorkspaceArtifactPath = toWorkspaceArtifactPath;
 exports.yearMonthUtc = yearMonthUtc;

package/dist/artifacts/paths.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"paths.cjs","names":[],"sources":["../../src/artifacts/paths.ts"],"sourcesContent":["// Shared artifact-path builders for the presentation plugins (chart / html /\n// mulmoscript). Browser-safe by design: no node:path / no node:crypto, so it\n// bundles into both the server core and the browser (`./vue`) plugin entries.\n//\n// These are POSIX artifact *wire paths* — stored in JSON and used as the\n// generic `files.artifacts` FileOps keys — so they must ALWAYS join with `/`\n// regardless of host OS. `path.join` would emit `\\` on Windows and corrupt\n// them; `path.posix.join` would drag in node:path and break the browser\n// bundle. So already-sanitised segments are joined with `/` directly (same\n// choice the plugins made before this module existed).\n\nconst MAX_SLUG_LEN = 120;\n\n/** The workspace directory every artifact lives under (`<workspace>/artifacts`). */\nexport const ARTIFACTS_ROOT = \"artifacts\";\n\n/**\n * Lowercase-ASCII slug for a throwaway, timestamped artifact filename. Empty,\n * whitespace-only, and non-ASCII-only titles fall back to `fallback`. Capped at\n * 120 chars so a long LLM title can't blow the filesystem's NAME_MAX.\n *\n * Leading/trailing hyphens are stripped with a linear scan rather than a regex\n * like `/^-+|-+$/` — CodeQL flags the trailing-anchor form as polynomial\n * backtracking on the attacker-influenced (LLM-provided) title. Strip → cap →\n * strip so a cut at the 120-char boundary can't re-expose a trailing hyphen.\n */\nexport function slugifyArtifact(title: string | undefined, fallback: string): string {\n  if (!title) return fallback;\n  const collapsed = title.toLowerCase().replace(/[^a-z0-9]+/g, \"-\");\n  let start = 0;\n  let end = collapsed.length;\n  while (start < end && collapsed[start] === \"-\") start += 1;\n  while (end > start && collapsed[end - 1] === \"-\") end -= 1;\n  if (end - start > MAX_SLUG_LEN) end = start + MAX_SLUG_LEN;\n  while (end > start && collapsed[end - 1] === \"-\") end -= 1;\n  return collapsed.slice(start, end) || fallback;\n}\n\n/** UTC `YYYY/MM` partition (matches the host's #764 artifact sharding). UTC —\n *  not local — so a workspace synced across timezones stays in one bucket. */\nexport function yearMonthUtc(now: Date = new Date()): string {\n  const year = now.getUTCFullYear();\n  const month = String(now.getUTCMonth() + 1).padStart(2, \"0\");\n  return `${year}/${month}`;\n}\n\nexport interface ArtifactRelPathParams {\n  /** Artifact-kind directory under the artifacts root (e.g. `charts`, `html`, `stories`). */\n  dir: string;\n  /** Human title the slug is derived from; empty/non-ASCII falls back to `fallback`. */\n  title: string | undefined;\n  /** File extension INCLUDING the leading dot (e.g. `.html`, `.chart.json`). */\n  ext: string;\n  /** Slug used when `title` yields nothing (e.g. `chart`, `page`, `story`). */\n  fallback: string;\n  now?: Date;\n  /** Include the `YYYY/MM` partition segment. Default true; stories opt out. */\n  partitioned?: boolean;\n}\n\n/**\n * FileOps-relative artifact path: `<dir>[/YYYY/MM]/<slug>-<epochMs><ext>`. The\n * `<epochMs>` suffix keeps freshly-built filenames collision-free without a\n * random component. This is what `files.artifacts.write` takes; prefix it with\n * `toWorkspaceArtifactPath` for the workspace-relative form shown to the LLM.\n */\nexport function buildArtifactRelPath(params: ArtifactRelPathParams): string {\n  const { dir, title, ext, fallback, now = new Date(), partitioned = true } = params;\n  const fileName = `${slugifyArtifact(title, fallback)}-${now.getTime()}${ext}`;\n  const segments = partitioned ? [dir, yearMonthUtc(now), fileName] : [dir, fileName];\n  return segments.join(\"/\");\n}\n\n/** Prefix a FileOps-relative artifact path with the workspace `artifacts/` root. */\nexport function toWorkspaceArtifactPath(relPath: string): string {\n  return `${ARTIFACTS_ROOT}/${relPath}`;\n}\n\n/**\n * True when any `/`-segment of `value` is empty (`//`, leading/trailing slash),\n * `.`, or `..`. The lexical traversal / non-canonical guard every artifact path\n * check shares — equivalent to `path.posix.normalize(v) === v && !v.includes(\"..\")`\n * — so a workspace-escape judgement can't drift between plugins.\n */\nexport function hasUnsafePathSegment(value: string): boolean {\n  return value.split(\"/\").some((seg) => seg === \"\" || seg === \".\" || seg === \"..\");\n}\n"],"mappings":";;AAWA,IAAM,eAAe;;AAGrB,IAAa,iBAAiB;;;;;;;;;;;AAY9B,SAAgB,gBAAgB,OAA2B,UAA0B;CACnF,IAAI,CAAC,OAAO,OAAO;CACnB,MAAM,YAAY,MAAM,YAAY,CAAC,CAAC,QAAQ,eAAe,GAAG;CAChE,IAAI,QAAQ;CACZ,IAAI,MAAM,UAAU;CACpB,OAAO,QAAQ,OAAO,UAAU,WAAW,KAAK,SAAS;CACzD,OAAO,MAAM,SAAS,UAAU,MAAM,OAAO,KAAK,OAAO;CACzD,IAAI,MAAM,QAAQ,cAAc,MAAM,QAAQ;CAC9C,OAAO,MAAM,SAAS,UAAU,MAAM,OAAO,KAAK,OAAO;CACzD,OAAO,UAAU,MAAM,OAAO,GAAG,KAAK;AACxC;;;AAIA,SAAgB,aAAa,sBAAY,IAAI,KAAK,GAAW;CAG3D,OAAO,GAFM,IAAI,eAEP,EAAK,GADD,OAAO,IAAI,YAAY,IAAI,CAAC,CAAC,CAAC,SAAS,GAAG,GACtC;AACpB;;;;;;;AAsBA,SAAgB,qBAAqB,QAAuC;CAC1E,MAAM,EAAE,KAAK,OAAO,KAAK,UAAU,sBAAM,IAAI,KAAK,GAAG,cAAc,SAAS;CAC5E,MAAM,WAAW,GAAG,gBAAgB,OAAO,QAAQ,EAAE,GAAG,IAAI,QAAQ,IAAI;CAExE,QADiB,cAAc;EAAC;EAAK,aAAa,GAAG;EAAG;CAAQ,IAAI,CAAC,KAAK,QAAQ,EAAA,CAClE,KAAK,GAAG;AAC1B;;AAGA,SAAgB,wBAAwB,SAAyB;CAC/D,OAAO,GAAG,eAAe,GAAG;AAC9B;;;;;;;AAQA,SAAgB,qBAAqB,OAAwB;CAC3D,OAAO,MAAM,MAAM,GAAG,CAAC,CAAC,MAAM,QAAQ,QAAQ,MAAM,QAAQ,OAAO,QAAQ,IAAI;AACjF"}
+{"version":3,"file":"paths.cjs","names":[],"sources":["../../src/artifacts/paths.ts"],"sourcesContent":["// Shared artifact-path builders for the presentation plugins (chart / html /\n// mulmoscript). Browser-safe by design: no node:path / no node:crypto, so it\n// bundles into both the server core and the browser (`./vue`) plugin entries.\n//\n// These are POSIX artifact *wire paths* — stored in JSON and used as the\n// generic `files.artifacts` FileOps keys — so they must ALWAYS join with `/`\n// regardless of host OS. `path.join` would emit `\\` on Windows and corrupt\n// them; `path.posix.join` would drag in node:path and break the browser\n// bundle. So already-sanitised segments are joined with `/` directly (same\n// choice the plugins made before this module existed).\n\nconst MAX_SLUG_LEN = 120;\n\n/** The workspace directory every artifact lives under (`<workspace>/artifacts`). */\nexport const ARTIFACTS_ROOT = \"artifacts\";\n\n/**\n * Lowercase-ASCII slug for a throwaway, timestamped artifact filename. Empty,\n * whitespace-only, and non-ASCII-only titles fall back to `fallback`. Capped at\n * 120 chars so a long LLM title can't blow the filesystem's NAME_MAX.\n *\n * Leading/trailing hyphens are stripped with a linear scan rather than a regex\n * like `/^-+|-+$/` — CodeQL flags the trailing-anchor form as polynomial\n * backtracking on the attacker-influenced (LLM-provided) title. Strip → cap →\n * strip so a cut at the 120-char boundary can't re-expose a trailing hyphen.\n */\nexport function slugifyArtifact(title: string | undefined, fallback: string): string {\n  if (!title) return fallback;\n  const collapsed = title.toLowerCase().replace(/[^a-z0-9]+/g, \"-\");\n  let start = 0;\n  let end = collapsed.length;\n  while (start < end && collapsed[start] === \"-\") start += 1;\n  while (end > start && collapsed[end - 1] === \"-\") end -= 1;\n  if (end - start > MAX_SLUG_LEN) end = start + MAX_SLUG_LEN;\n  while (end > start && collapsed[end - 1] === \"-\") end -= 1;\n  return collapsed.slice(start, end) || fallback;\n}\n\n/** UTC `YYYY/MM` partition (matches the host's #764 artifact sharding). UTC —\n *  not local — so a workspace synced across timezones stays in one bucket. */\nexport function yearMonthUtc(now: Date = new Date()): string {\n  const year = now.getUTCFullYear();\n  const month = String(now.getUTCMonth() + 1).padStart(2, \"0\");\n  return `${year}/${month}`;\n}\n\nexport interface ArtifactRelPathParams {\n  /** Artifact-kind directory under the artifacts root (e.g. `charts`, `html`, `stories`). */\n  dir: string;\n  /** Human title the slug is derived from; empty/non-ASCII falls back to `fallback`. */\n  title: string | undefined;\n  /** File extension INCLUDING the leading dot (e.g. `.html`, `.chart.json`). */\n  ext: string;\n  /** Slug used when `title` yields nothing (e.g. `chart`, `page`, `story`). */\n  fallback: string;\n  now?: Date;\n  /** Include the `YYYY/MM` partition segment. Default true; stories opt out. */\n  partitioned?: boolean;\n}\n\n/**\n * FileOps-relative artifact path: `<dir>[/YYYY/MM]/<slug>-<epochMs><ext>`. The\n * `<epochMs>` suffix keeps freshly-built filenames collision-free without a\n * random component. This is what `files.artifacts.write` takes; prefix it with\n * `toWorkspaceArtifactPath` for the workspace-relative form shown to the LLM.\n */\nexport function buildArtifactRelPath(params: ArtifactRelPathParams): string {\n  const { dir, title, ext, fallback, now = new Date(), partitioned = true } = params;\n  const fileName = `${slugifyArtifact(title, fallback)}-${now.getTime()}${ext}`;\n  const segments = partitioned ? [dir, yearMonthUtc(now), fileName] : [dir, fileName];\n  return segments.join(\"/\");\n}\n\n/** Prefix a FileOps-relative artifact path with the workspace `artifacts/` root. */\nexport function toWorkspaceArtifactPath(relPath: string): string {\n  return `${ARTIFACTS_ROOT}/${relPath}`;\n}\n\n/**\n * True when any `/`-segment of `value` is empty (`//`, leading/trailing slash),\n * `.`, or `..`. The lexical traversal / non-canonical guard every artifact path\n * check shares — equivalent to `path.posix.normalize(v) === v && !v.includes(\"..\")`\n * — so a workspace-escape judgement can't drift between plugins.\n */\nexport function hasUnsafePathSegment(value: string): boolean {\n  return value.split(\"/\").some((seg) => seg === \"\" || seg === \".\" || seg === \"..\");\n}\n\n// ── Presentable document paths (presentDocument / presentHtml `path`) ──\n//\n// The two present* tools accept a path to an EXISTING file to display and\n// edit in place. That file is no longer necessarily an artifact the agent\n// wrote: it can be any document in the workspace (MulmoTerminal's workspace\n// IS the git project the user is working in) or, when the host allows it, an\n// absolute path elsewhere on disk.\n//\n// Which of those a value is decides how the host resolves it, so the\n// judgement lives here rather than in each plugin — the plugins may not\n// import one another, and a predicate two of them spell differently is how\n// \"the write site accepts what the refresh site rejects\" bugs start.\n\n/** How a caller-supplied file path must be resolved. `null` = not a usable path. */\nexport type FilePathKind = \"absolute\" | \"relative\";\n\n// `/x`, `C:\\x` / `C:/x`, `\\\\server\\share` (UNC), and the Windows root-relative\n// `\\dir\\x` — which node's `path.resolve` on Windows sends to the drive root, so\n// treating it as relative would mean the classification and the resolution\n// disagreed about where the file is. Windows spellings are recognised on every\n// platform: the value is produced by an LLM or a remote host, not by the local\n// `path` module.\nconst WINDOWS_DRIVE_RE = /^[a-zA-Z]:[\\\\/]/;\n\n/** True when `value` names a location that does not depend on a base directory.\n *  Exported so a URL builder and a path resolver cannot disagree about which\n *  values are rooted. */\nexport function isAbsoluteFilePathValue(value: string): boolean {\n  // One leading backslash covers both the UNC `\\\\server\\share` and the Windows\n  // root-relative `\\dir\\x`.\n  return value.startsWith(\"/\") || value.startsWith(\"\\\\\") || WINDOWS_DRIVE_RE.test(value);\n}\n\n/**\n * Classify a caller-supplied path to a file the host may read and overwrite.\n *\n * Accepts one of `extensions` (compared case-insensitively) and rejects NUL\n * bytes and any `.` / `..` / empty segment — a relative path must be canonical\n * so it can be joined onto a root, and an absolute one must not climb, so\n * neither form can be re-pointed by traversal after the host has vetted it.\n * Returns `\"absolute\"` / `\"relative\"` so the host knows whether to resolve\n * against its workspace root, or `null` when the value is unusable.\n *\n * This is a LEXICAL check only. Existence, file-vs-directory, symlink\n * containment and any host policy about which roots are reachable stay with\n * the host, which is the only layer that can consult the filesystem.\n */\nexport function classifyFilePath(value: string, extensions: readonly string[]): FilePathKind | null {\n  if (!value || value.includes(\"\\0\")) return null;\n  const lower = value.toLowerCase();\n  if (!extensions.some((ext) => lower.endsWith(ext))) return null;\n  const absolute = isAbsoluteFilePathValue(value);\n  // Split on both separators: `..` must be refused however the value spells it.\n  const segments = value.split(/[/\\\\]/);\n  // A leading `/` (or drive / UNC prefix) makes the first segment empty by\n  // construction — skip those, then require every remaining segment to be a\n  // real name.\n  const body = absolute ? segments.slice(segments.findIndex((segment) => segment.length > 0)) : segments;\n  if (body.length === 0) return null;\n  if (body.some((segment) => segment === \"\" || segment === \".\" || segment === \"..\")) return null;\n  return absolute ? \"absolute\" : \"relative\";\n}\n\n/** True when any `/` or `\\`-separated segment starts with a dot. The file\n *  servers that hand these pages to a browser refuse dotfile segments (the\n *  artifact mounts' `dotfiles: \"deny\"` policy), so a `path` argument bearing\n *  one can be accepted by a tool and then never render — the gate and the\n *  server have to agree on this, hence one definition. */\nexport function hasDotfileSegment(value: string): boolean {\n  return value.split(/[/\\\\]/).some((segment) => segment.startsWith(\".\"));\n}\n"],"mappings":";;AAWA,IAAM,eAAe;;AAGrB,IAAa,iBAAiB;;;;;;;;;;;AAY9B,SAAgB,gBAAgB,OAA2B,UAA0B;CACnF,IAAI,CAAC,OAAO,OAAO;CACnB,MAAM,YAAY,MAAM,YAAY,CAAC,CAAC,QAAQ,eAAe,GAAG;CAChE,IAAI,QAAQ;CACZ,IAAI,MAAM,UAAU;CACpB,OAAO,QAAQ,OAAO,UAAU,WAAW,KAAK,SAAS;CACzD,OAAO,MAAM,SAAS,UAAU,MAAM,OAAO,KAAK,OAAO;CACzD,IAAI,MAAM,QAAQ,cAAc,MAAM,QAAQ;CAC9C,OAAO,MAAM,SAAS,UAAU,MAAM,OAAO,KAAK,OAAO;CACzD,OAAO,UAAU,MAAM,OAAO,GAAG,KAAK;AACxC;;;AAIA,SAAgB,aAAa,sBAAY,IAAI,KAAK,GAAW;CAG3D,OAAO,GAFM,IAAI,eAEP,EAAK,GADD,OAAO,IAAI,YAAY,IAAI,CAAC,CAAC,CAAC,SAAS,GAAG,GACtC;AACpB;;;;;;;AAsBA,SAAgB,qBAAqB,QAAuC;CAC1E,MAAM,EAAE,KAAK,OAAO,KAAK,UAAU,sBAAM,IAAI,KAAK,GAAG,cAAc,SAAS;CAC5E,MAAM,WAAW,GAAG,gBAAgB,OAAO,QAAQ,EAAE,GAAG,IAAI,QAAQ,IAAI;CAExE,QADiB,cAAc;EAAC;EAAK,aAAa,GAAG;EAAG;CAAQ,IAAI,CAAC,KAAK,QAAQ,EAAA,CAClE,KAAK,GAAG;AAC1B;;AAGA,SAAgB,wBAAwB,SAAyB;CAC/D,OAAO,GAAG,eAAe,GAAG;AAC9B;;;;;;;AAQA,SAAgB,qBAAqB,OAAwB;CAC3D,OAAO,MAAM,MAAM,GAAG,CAAC,CAAC,MAAM,QAAQ,QAAQ,MAAM,QAAQ,OAAO,QAAQ,IAAI;AACjF;AAwBA,IAAM,mBAAmB;;;;AAKzB,SAAgB,wBAAwB,OAAwB;CAG9D,OAAO,MAAM,WAAW,GAAG,KAAK,MAAM,WAAW,IAAI,KAAK,iBAAiB,KAAK,KAAK;AACvF;;;;;;;;;;;;;;;AAgBA,SAAgB,iBAAiB,OAAe,YAAoD;CAClG,IAAI,CAAC,SAAS,MAAM,SAAS,IAAI,GAAG,OAAO;CAC3C,MAAM,QAAQ,MAAM,YAAY;CAChC,IAAI,CAAC,WAAW,MAAM,QAAQ,MAAM,SAAS,GAAG,CAAC,GAAG,OAAO;CAC3D,MAAM,WAAW,wBAAwB,KAAK;CAE9C,MAAM,WAAW,MAAM,MAAM,OAAO;CAIpC,MAAM,OAAO,WAAW,SAAS,MAAM,SAAS,WAAW,YAAY,QAAQ,SAAS,CAAC,CAAC,IAAI;CAC9F,IAAI,KAAK,WAAW,GAAG,OAAO;CAC9B,IAAI,KAAK,MAAM,YAAY,YAAY,MAAM,YAAY,OAAO,YAAY,IAAI,GAAG,OAAO;CAC1F,OAAO,WAAW,aAAa;AACjC;;;;;;AAOA,SAAgB,kBAAkB,OAAwB;CACxD,OAAO,MAAM,MAAM,OAAO,CAAC,CAAC,MAAM,YAAY,QAAQ,WAAW,GAAG,CAAC;AACvE"}

package/dist/artifacts/paths.d.ts

@@ -43,3 +43,30 @@ export declare function toWorkspaceArtifactPath(relPath: string): string;
  * — so a workspace-escape judgement can't drift between plugins.
  */
 export declare function hasUnsafePathSegment(value: string): boolean;
+/** How a caller-supplied file path must be resolved. `null` = not a usable path. */
+export type FilePathKind = "absolute" | "relative";
+/** True when `value` names a location that does not depend on a base directory.
+ *  Exported so a URL builder and a path resolver cannot disagree about which
+ *  values are rooted. */
+export declare function isAbsoluteFilePathValue(value: string): boolean;
+/**
+ * Classify a caller-supplied path to a file the host may read and overwrite.
+ *
+ * Accepts one of `extensions` (compared case-insensitively) and rejects NUL
+ * bytes and any `.` / `..` / empty segment — a relative path must be canonical
+ * so it can be joined onto a root, and an absolute one must not climb, so
+ * neither form can be re-pointed by traversal after the host has vetted it.
+ * Returns `"absolute"` / `"relative"` so the host knows whether to resolve
+ * against its workspace root, or `null` when the value is unusable.
+ *
+ * This is a LEXICAL check only. Existence, file-vs-directory, symlink
+ * containment and any host policy about which roots are reachable stay with
+ * the host, which is the only layer that can consult the filesystem.
+ */
+export declare function classifyFilePath(value: string, extensions: readonly string[]): FilePathKind | null;
+/** True when any `/` or `\`-separated segment starts with a dot. The file
+ *  servers that hand these pages to a browser refuse dotfile segments (the
+ *  artifact mounts' `dotfiles: "deny"` policy), so a `path` argument bearing
+ *  one can be accepted by a tool and then never render — the gate and the
+ *  server have to agree on this, hence one definition. */
+export declare function hasDotfileSegment(value: string): boolean;

package/dist/artifacts/paths.js

@@ -56,7 +56,47 @@ function toWorkspaceArtifactPath(relPath) {
 function hasUnsafePathSegment(value) {
 	return value.split("/").some((seg) => seg === "" || seg === "." || seg === "..");
 }
+var WINDOWS_DRIVE_RE = /^[a-zA-Z]:[\\/]/;
+/** True when `value` names a location that does not depend on a base directory.
+*  Exported so a URL builder and a path resolver cannot disagree about which
+*  values are rooted. */
+function isAbsoluteFilePathValue(value) {
+	return value.startsWith("/") || value.startsWith("\\") || WINDOWS_DRIVE_RE.test(value);
+}
+/**
+* Classify a caller-supplied path to a file the host may read and overwrite.
+*
+* Accepts one of `extensions` (compared case-insensitively) and rejects NUL
+* bytes and any `.` / `..` / empty segment — a relative path must be canonical
+* so it can be joined onto a root, and an absolute one must not climb, so
+* neither form can be re-pointed by traversal after the host has vetted it.
+* Returns `"absolute"` / `"relative"` so the host knows whether to resolve
+* against its workspace root, or `null` when the value is unusable.
+*
+* This is a LEXICAL check only. Existence, file-vs-directory, symlink
+* containment and any host policy about which roots are reachable stay with
+* the host, which is the only layer that can consult the filesystem.
+*/
+function classifyFilePath(value, extensions) {
+	if (!value || value.includes("\0")) return null;
+	const lower = value.toLowerCase();
+	if (!extensions.some((ext) => lower.endsWith(ext))) return null;
+	const absolute = isAbsoluteFilePathValue(value);
+	const segments = value.split(/[/\\]/);
+	const body = absolute ? segments.slice(segments.findIndex((segment) => segment.length > 0)) : segments;
+	if (body.length === 0) return null;
+	if (body.some((segment) => segment === "" || segment === "." || segment === "..")) return null;
+	return absolute ? "absolute" : "relative";
+}
+/** True when any `/` or `\`-separated segment starts with a dot. The file
+*  servers that hand these pages to a browser refuse dotfile segments (the
+*  artifact mounts' `dotfiles: "deny"` policy), so a `path` argument bearing
+*  one can be accepted by a tool and then never render — the gate and the
+*  server have to agree on this, hence one definition. */
+function hasDotfileSegment(value) {
+	return value.split(/[/\\]/).some((segment) => segment.startsWith("."));
+}
 //#endregion
-export { ARTIFACTS_ROOT, buildArtifactRelPath, hasUnsafePathSegment, slugifyArtifact, toWorkspaceArtifactPath, yearMonthUtc };
+export { ARTIFACTS_ROOT, buildArtifactRelPath, classifyFilePath, hasDotfileSegment, hasUnsafePathSegment, isAbsoluteFilePathValue, slugifyArtifact, toWorkspaceArtifactPath, yearMonthUtc };
 
 //# sourceMappingURL=paths.js.map

package/dist/artifacts/paths.js.map

@@ -1 +1 @@
-{"version":3,"file":"paths.js","names":[],"sources":["../../src/artifacts/paths.ts"],"sourcesContent":["// Shared artifact-path builders for the presentation plugins (chart / html /\n// mulmoscript). Browser-safe by design: no node:path / no node:crypto, so it\n// bundles into both the server core and the browser (`./vue`) plugin entries.\n//\n// These are POSIX artifact *wire paths* — stored in JSON and used as the\n// generic `files.artifacts` FileOps keys — so they must ALWAYS join with `/`\n// regardless of host OS. `path.join` would emit `\\` on Windows and corrupt\n// them; `path.posix.join` would drag in node:path and break the browser\n// bundle. So already-sanitised segments are joined with `/` directly (same\n// choice the plugins made before this module existed).\n\nconst MAX_SLUG_LEN = 120;\n\n/** The workspace directory every artifact lives under (`<workspace>/artifacts`). */\nexport const ARTIFACTS_ROOT = \"artifacts\";\n\n/**\n * Lowercase-ASCII slug for a throwaway, timestamped artifact filename. Empty,\n * whitespace-only, and non-ASCII-only titles fall back to `fallback`. Capped at\n * 120 chars so a long LLM title can't blow the filesystem's NAME_MAX.\n *\n * Leading/trailing hyphens are stripped with a linear scan rather than a regex\n * like `/^-+|-+$/` — CodeQL flags the trailing-anchor form as polynomial\n * backtracking on the attacker-influenced (LLM-provided) title. Strip → cap →\n * strip so a cut at the 120-char boundary can't re-expose a trailing hyphen.\n */\nexport function slugifyArtifact(title: string | undefined, fallback: string): string {\n  if (!title) return fallback;\n  const collapsed = title.toLowerCase().replace(/[^a-z0-9]+/g, \"-\");\n  let start = 0;\n  let end = collapsed.length;\n  while (start < end && collapsed[start] === \"-\") start += 1;\n  while (end > start && collapsed[end - 1] === \"-\") end -= 1;\n  if (end - start > MAX_SLUG_LEN) end = start + MAX_SLUG_LEN;\n  while (end > start && collapsed[end - 1] === \"-\") end -= 1;\n  return collapsed.slice(start, end) || fallback;\n}\n\n/** UTC `YYYY/MM` partition (matches the host's #764 artifact sharding). UTC —\n *  not local — so a workspace synced across timezones stays in one bucket. */\nexport function yearMonthUtc(now: Date = new Date()): string {\n  const year = now.getUTCFullYear();\n  const month = String(now.getUTCMonth() + 1).padStart(2, \"0\");\n  return `${year}/${month}`;\n}\n\nexport interface ArtifactRelPathParams {\n  /** Artifact-kind directory under the artifacts root (e.g. `charts`, `html`, `stories`). */\n  dir: string;\n  /** Human title the slug is derived from; empty/non-ASCII falls back to `fallback`. */\n  title: string | undefined;\n  /** File extension INCLUDING the leading dot (e.g. `.html`, `.chart.json`). */\n  ext: string;\n  /** Slug used when `title` yields nothing (e.g. `chart`, `page`, `story`). */\n  fallback: string;\n  now?: Date;\n  /** Include the `YYYY/MM` partition segment. Default true; stories opt out. */\n  partitioned?: boolean;\n}\n\n/**\n * FileOps-relative artifact path: `<dir>[/YYYY/MM]/<slug>-<epochMs><ext>`. The\n * `<epochMs>` suffix keeps freshly-built filenames collision-free without a\n * random component. This is what `files.artifacts.write` takes; prefix it with\n * `toWorkspaceArtifactPath` for the workspace-relative form shown to the LLM.\n */\nexport function buildArtifactRelPath(params: ArtifactRelPathParams): string {\n  const { dir, title, ext, fallback, now = new Date(), partitioned = true } = params;\n  const fileName = `${slugifyArtifact(title, fallback)}-${now.getTime()}${ext}`;\n  const segments = partitioned ? [dir, yearMonthUtc(now), fileName] : [dir, fileName];\n  return segments.join(\"/\");\n}\n\n/** Prefix a FileOps-relative artifact path with the workspace `artifacts/` root. */\nexport function toWorkspaceArtifactPath(relPath: string): string {\n  return `${ARTIFACTS_ROOT}/${relPath}`;\n}\n\n/**\n * True when any `/`-segment of `value` is empty (`//`, leading/trailing slash),\n * `.`, or `..`. The lexical traversal / non-canonical guard every artifact path\n * check shares — equivalent to `path.posix.normalize(v) === v && !v.includes(\"..\")`\n * — so a workspace-escape judgement can't drift between plugins.\n */\nexport function hasUnsafePathSegment(value: string): boolean {\n  return value.split(\"/\").some((seg) => seg === \"\" || seg === \".\" || seg === \"..\");\n}\n"],"mappings":";AAWA,IAAM,eAAe;;AAGrB,IAAa,iBAAiB;;;;;;;;;;;AAY9B,SAAgB,gBAAgB,OAA2B,UAA0B;CACnF,IAAI,CAAC,OAAO,OAAO;CACnB,MAAM,YAAY,MAAM,YAAY,CAAC,CAAC,QAAQ,eAAe,GAAG;CAChE,IAAI,QAAQ;CACZ,IAAI,MAAM,UAAU;CACpB,OAAO,QAAQ,OAAO,UAAU,WAAW,KAAK,SAAS;CACzD,OAAO,MAAM,SAAS,UAAU,MAAM,OAAO,KAAK,OAAO;CACzD,IAAI,MAAM,QAAQ,cAAc,MAAM,QAAQ;CAC9C,OAAO,MAAM,SAAS,UAAU,MAAM,OAAO,KAAK,OAAO;CACzD,OAAO,UAAU,MAAM,OAAO,GAAG,KAAK;AACxC;;;AAIA,SAAgB,aAAa,sBAAY,IAAI,KAAK,GAAW;CAG3D,OAAO,GAFM,IAAI,eAEP,EAAK,GADD,OAAO,IAAI,YAAY,IAAI,CAAC,CAAC,CAAC,SAAS,GAAG,GACtC;AACpB;;;;;;;AAsBA,SAAgB,qBAAqB,QAAuC;CAC1E,MAAM,EAAE,KAAK,OAAO,KAAK,UAAU,sBAAM,IAAI,KAAK,GAAG,cAAc,SAAS;CAC5E,MAAM,WAAW,GAAG,gBAAgB,OAAO,QAAQ,EAAE,GAAG,IAAI,QAAQ,IAAI;CAExE,QADiB,cAAc;EAAC;EAAK,aAAa,GAAG;EAAG;CAAQ,IAAI,CAAC,KAAK,QAAQ,EAAA,CAClE,KAAK,GAAG;AAC1B;;AAGA,SAAgB,wBAAwB,SAAyB;CAC/D,OAAO,GAAG,eAAe,GAAG;AAC9B;;;;;;;AAQA,SAAgB,qBAAqB,OAAwB;CAC3D,OAAO,MAAM,MAAM,GAAG,CAAC,CAAC,MAAM,QAAQ,QAAQ,MAAM,QAAQ,OAAO,QAAQ,IAAI;AACjF"}
+{"version":3,"file":"paths.js","names":[],"sources":["../../src/artifacts/paths.ts"],"sourcesContent":["// Shared artifact-path builders for the presentation plugins (chart / html /\n// mulmoscript). Browser-safe by design: no node:path / no node:crypto, so it\n// bundles into both the server core and the browser (`./vue`) plugin entries.\n//\n// These are POSIX artifact *wire paths* — stored in JSON and used as the\n// generic `files.artifacts` FileOps keys — so they must ALWAYS join with `/`\n// regardless of host OS. `path.join` would emit `\\` on Windows and corrupt\n// them; `path.posix.join` would drag in node:path and break the browser\n// bundle. So already-sanitised segments are joined with `/` directly (same\n// choice the plugins made before this module existed).\n\nconst MAX_SLUG_LEN = 120;\n\n/** The workspace directory every artifact lives under (`<workspace>/artifacts`). */\nexport const ARTIFACTS_ROOT = \"artifacts\";\n\n/**\n * Lowercase-ASCII slug for a throwaway, timestamped artifact filename. Empty,\n * whitespace-only, and non-ASCII-only titles fall back to `fallback`. Capped at\n * 120 chars so a long LLM title can't blow the filesystem's NAME_MAX.\n *\n * Leading/trailing hyphens are stripped with a linear scan rather than a regex\n * like `/^-+|-+$/` — CodeQL flags the trailing-anchor form as polynomial\n * backtracking on the attacker-influenced (LLM-provided) title. Strip → cap →\n * strip so a cut at the 120-char boundary can't re-expose a trailing hyphen.\n */\nexport function slugifyArtifact(title: string | undefined, fallback: string): string {\n  if (!title) return fallback;\n  const collapsed = title.toLowerCase().replace(/[^a-z0-9]+/g, \"-\");\n  let start = 0;\n  let end = collapsed.length;\n  while (start < end && collapsed[start] === \"-\") start += 1;\n  while (end > start && collapsed[end - 1] === \"-\") end -= 1;\n  if (end - start > MAX_SLUG_LEN) end = start + MAX_SLUG_LEN;\n  while (end > start && collapsed[end - 1] === \"-\") end -= 1;\n  return collapsed.slice(start, end) || fallback;\n}\n\n/** UTC `YYYY/MM` partition (matches the host's #764 artifact sharding). UTC —\n *  not local — so a workspace synced across timezones stays in one bucket. */\nexport function yearMonthUtc(now: Date = new Date()): string {\n  const year = now.getUTCFullYear();\n  const month = String(now.getUTCMonth() + 1).padStart(2, \"0\");\n  return `${year}/${month}`;\n}\n\nexport interface ArtifactRelPathParams {\n  /** Artifact-kind directory under the artifacts root (e.g. `charts`, `html`, `stories`). */\n  dir: string;\n  /** Human title the slug is derived from; empty/non-ASCII falls back to `fallback`. */\n  title: string | undefined;\n  /** File extension INCLUDING the leading dot (e.g. `.html`, `.chart.json`). */\n  ext: string;\n  /** Slug used when `title` yields nothing (e.g. `chart`, `page`, `story`). */\n  fallback: string;\n  now?: Date;\n  /** Include the `YYYY/MM` partition segment. Default true; stories opt out. */\n  partitioned?: boolean;\n}\n\n/**\n * FileOps-relative artifact path: `<dir>[/YYYY/MM]/<slug>-<epochMs><ext>`. The\n * `<epochMs>` suffix keeps freshly-built filenames collision-free without a\n * random component. This is what `files.artifacts.write` takes; prefix it with\n * `toWorkspaceArtifactPath` for the workspace-relative form shown to the LLM.\n */\nexport function buildArtifactRelPath(params: ArtifactRelPathParams): string {\n  const { dir, title, ext, fallback, now = new Date(), partitioned = true } = params;\n  const fileName = `${slugifyArtifact(title, fallback)}-${now.getTime()}${ext}`;\n  const segments = partitioned ? [dir, yearMonthUtc(now), fileName] : [dir, fileName];\n  return segments.join(\"/\");\n}\n\n/** Prefix a FileOps-relative artifact path with the workspace `artifacts/` root. */\nexport function toWorkspaceArtifactPath(relPath: string): string {\n  return `${ARTIFACTS_ROOT}/${relPath}`;\n}\n\n/**\n * True when any `/`-segment of `value` is empty (`//`, leading/trailing slash),\n * `.`, or `..`. The lexical traversal / non-canonical guard every artifact path\n * check shares — equivalent to `path.posix.normalize(v) === v && !v.includes(\"..\")`\n * — so a workspace-escape judgement can't drift between plugins.\n */\nexport function hasUnsafePathSegment(value: string): boolean {\n  return value.split(\"/\").some((seg) => seg === \"\" || seg === \".\" || seg === \"..\");\n}\n\n// ── Presentable document paths (presentDocument / presentHtml `path`) ──\n//\n// The two present* tools accept a path to an EXISTING file to display and\n// edit in place. That file is no longer necessarily an artifact the agent\n// wrote: it can be any document in the workspace (MulmoTerminal's workspace\n// IS the git project the user is working in) or, when the host allows it, an\n// absolute path elsewhere on disk.\n//\n// Which of those a value is decides how the host resolves it, so the\n// judgement lives here rather than in each plugin — the plugins may not\n// import one another, and a predicate two of them spell differently is how\n// \"the write site accepts what the refresh site rejects\" bugs start.\n\n/** How a caller-supplied file path must be resolved. `null` = not a usable path. */\nexport type FilePathKind = \"absolute\" | \"relative\";\n\n// `/x`, `C:\\x` / `C:/x`, `\\\\server\\share` (UNC), and the Windows root-relative\n// `\\dir\\x` — which node's `path.resolve` on Windows sends to the drive root, so\n// treating it as relative would mean the classification and the resolution\n// disagreed about where the file is. Windows spellings are recognised on every\n// platform: the value is produced by an LLM or a remote host, not by the local\n// `path` module.\nconst WINDOWS_DRIVE_RE = /^[a-zA-Z]:[\\\\/]/;\n\n/** True when `value` names a location that does not depend on a base directory.\n *  Exported so a URL builder and a path resolver cannot disagree about which\n *  values are rooted. */\nexport function isAbsoluteFilePathValue(value: string): boolean {\n  // One leading backslash covers both the UNC `\\\\server\\share` and the Windows\n  // root-relative `\\dir\\x`.\n  return value.startsWith(\"/\") || value.startsWith(\"\\\\\") || WINDOWS_DRIVE_RE.test(value);\n}\n\n/**\n * Classify a caller-supplied path to a file the host may read and overwrite.\n *\n * Accepts one of `extensions` (compared case-insensitively) and rejects NUL\n * bytes and any `.` / `..` / empty segment — a relative path must be canonical\n * so it can be joined onto a root, and an absolute one must not climb, so\n * neither form can be re-pointed by traversal after the host has vetted it.\n * Returns `\"absolute\"` / `\"relative\"` so the host knows whether to resolve\n * against its workspace root, or `null` when the value is unusable.\n *\n * This is a LEXICAL check only. Existence, file-vs-directory, symlink\n * containment and any host policy about which roots are reachable stay with\n * the host, which is the only layer that can consult the filesystem.\n */\nexport function classifyFilePath(value: string, extensions: readonly string[]): FilePathKind | null {\n  if (!value || value.includes(\"\\0\")) return null;\n  const lower = value.toLowerCase();\n  if (!extensions.some((ext) => lower.endsWith(ext))) return null;\n  const absolute = isAbsoluteFilePathValue(value);\n  // Split on both separators: `..` must be refused however the value spells it.\n  const segments = value.split(/[/\\\\]/);\n  // A leading `/` (or drive / UNC prefix) makes the first segment empty by\n  // construction — skip those, then require every remaining segment to be a\n  // real name.\n  const body = absolute ? segments.slice(segments.findIndex((segment) => segment.length > 0)) : segments;\n  if (body.length === 0) return null;\n  if (body.some((segment) => segment === \"\" || segment === \".\" || segment === \"..\")) return null;\n  return absolute ? \"absolute\" : \"relative\";\n}\n\n/** True when any `/` or `\\`-separated segment starts with a dot. The file\n *  servers that hand these pages to a browser refuse dotfile segments (the\n *  artifact mounts' `dotfiles: \"deny\"` policy), so a `path` argument bearing\n *  one can be accepted by a tool and then never render — the gate and the\n *  server have to agree on this, hence one definition. */\nexport function hasDotfileSegment(value: string): boolean {\n  return value.split(/[/\\\\]/).some((segment) => segment.startsWith(\".\"));\n}\n"],"mappings":";AAWA,IAAM,eAAe;;AAGrB,IAAa,iBAAiB;;;;;;;;;;;AAY9B,SAAgB,gBAAgB,OAA2B,UAA0B;CACnF,IAAI,CAAC,OAAO,OAAO;CACnB,MAAM,YAAY,MAAM,YAAY,CAAC,CAAC,QAAQ,eAAe,GAAG;CAChE,IAAI,QAAQ;CACZ,IAAI,MAAM,UAAU;CACpB,OAAO,QAAQ,OAAO,UAAU,WAAW,KAAK,SAAS;CACzD,OAAO,MAAM,SAAS,UAAU,MAAM,OAAO,KAAK,OAAO;CACzD,IAAI,MAAM,QAAQ,cAAc,MAAM,QAAQ;CAC9C,OAAO,MAAM,SAAS,UAAU,MAAM,OAAO,KAAK,OAAO;CACzD,OAAO,UAAU,MAAM,OAAO,GAAG,KAAK;AACxC;;;AAIA,SAAgB,aAAa,sBAAY,IAAI,KAAK,GAAW;CAG3D,OAAO,GAFM,IAAI,eAEP,EAAK,GADD,OAAO,IAAI,YAAY,IAAI,CAAC,CAAC,CAAC,SAAS,GAAG,GACtC;AACpB;;;;;;;AAsBA,SAAgB,qBAAqB,QAAuC;CAC1E,MAAM,EAAE,KAAK,OAAO,KAAK,UAAU,sBAAM,IAAI,KAAK,GAAG,cAAc,SAAS;CAC5E,MAAM,WAAW,GAAG,gBAAgB,OAAO,QAAQ,EAAE,GAAG,IAAI,QAAQ,IAAI;CAExE,QADiB,cAAc;EAAC;EAAK,aAAa,GAAG;EAAG;CAAQ,IAAI,CAAC,KAAK,QAAQ,EAAA,CAClE,KAAK,GAAG;AAC1B;;AAGA,SAAgB,wBAAwB,SAAyB;CAC/D,OAAO,GAAG,eAAe,GAAG;AAC9B;;;;;;;AAQA,SAAgB,qBAAqB,OAAwB;CAC3D,OAAO,MAAM,MAAM,GAAG,CAAC,CAAC,MAAM,QAAQ,QAAQ,MAAM,QAAQ,OAAO,QAAQ,IAAI;AACjF;AAwBA,IAAM,mBAAmB;;;;AAKzB,SAAgB,wBAAwB,OAAwB;CAG9D,OAAO,MAAM,WAAW,GAAG,KAAK,MAAM,WAAW,IAAI,KAAK,iBAAiB,KAAK,KAAK;AACvF;;;;;;;;;;;;;;;AAgBA,SAAgB,iBAAiB,OAAe,YAAoD;CAClG,IAAI,CAAC,SAAS,MAAM,SAAS,IAAI,GAAG,OAAO;CAC3C,MAAM,QAAQ,MAAM,YAAY;CAChC,IAAI,CAAC,WAAW,MAAM,QAAQ,MAAM,SAAS,GAAG,CAAC,GAAG,OAAO;CAC3D,MAAM,WAAW,wBAAwB,KAAK;CAE9C,MAAM,WAAW,MAAM,MAAM,OAAO;CAIpC,MAAM,OAAO,WAAW,SAAS,MAAM,SAAS,WAAW,YAAY,QAAQ,SAAS,CAAC,CAAC,IAAI;CAC9F,IAAI,KAAK,WAAW,GAAG,OAAO;CAC9B,IAAI,KAAK,MAAM,YAAY,YAAY,MAAM,YAAY,OAAO,YAAY,IAAI,GAAG,OAAO;CAC1F,OAAO,WAAW,aAAa;AACjC;;;;;;AAOA,SAAgB,kBAAkB,OAAwB;CACxD,OAAO,MAAM,MAAM,OAAO,CAAC,CAAC,MAAM,YAAY,QAAQ,WAAW,GAAG,CAAC;AACvE"}

package/dist/files/byPath.d.ts

@@ -0,0 +1,32 @@
+export declare const MARKDOWN_EXTENSIONS: readonly [".md"];
+export declare const HTML_EXTENSIONS: readonly [".html", ".htm"];
+/** Minimal structural echo of gui-chat-protocol's `FileOps`. Declared here
+ *  rather than imported so core keeps no dependency on the protocol package;
+ *  a host assigns the result straight to a `FileOps`-typed capability. */
+export interface ByPathFileOps {
+    read: (rel: string) => Promise<string>;
+    readBytes: (rel: string) => Promise<Uint8Array>;
+    write: (rel: string, content: string | Uint8Array) => Promise<void>;
+    readDir: (rel: string) => Promise<string[]>;
+    stat: (rel: string) => Promise<{
+        mtimeMs: number;
+        size: number;
+    }>;
+    exists: (rel: string) => Promise<boolean>;
+    unlink: (rel: string) => Promise<void>;
+}
+/** Absolute on-disk path for a caller-supplied path with one of `extensions`,
+ *  or null when the value is not usable on this platform. */
+export declare function resolveByPath(root: string, value: string, extensions: readonly string[]): string | null;
+/** True when the path names an existing regular file. */
+export declare function existsAsFile(root: string, value: string, extensions: readonly string[]): Promise<boolean>;
+export interface ByPathOptions {
+    /** The root relative values resolve against, read PER CALL — hosts inject the
+     *  workspace after these ops are already bound into plugin closures. */
+    rootFor: () => string;
+    extensions: readonly string[];
+}
+/** FileOps over caller-supplied paths — what a host injects as `files.byPath`
+ *  for plugins whose `path` argument may leave their artifact directory. Every
+ *  method takes the same value the tool call carried, not a scope-relative one. */
+export declare function createByPathFileOps(options: ByPathOptions): ByPathFileOps;

package/dist/files/htmlFileRequest.d.ts

@@ -0,0 +1,4 @@
+/** Absolute path for a `/htmlfile/<scope>/<segments…>` request, or null when
+ *  the URL is malformed, uses an unknown scope, or touches a `.` / `..` /
+ *  dotfile segment. `workspaceRoot` should already be a realpath. */
+export declare function resolveHtmlFileRequestPath(workspaceRoot: string, reqPath: string): string | null;

package/dist/files/index.cjs

@@ -1,10 +1,12 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 const require_rolldown_runtime = require("../rolldown-runtime-D6vf50IK.cjs");
+const require_artifacts_paths = require("../artifacts/paths.cjs");
 const require_atomic = require("../atomic-C_7YpMiM.cjs");
 const require_relPath = require("../relPath-CgGi4-Nv.cjs");
 let node_fs = require("node:fs");
 let node_path = require("node:path");
 node_path = require_rolldown_runtime.__toESM(node_path, 1);
+let node_fs_promises = require("node:fs/promises");
 //#region src/files/json.ts
 var JSON_INDENT = 2;
 /** Atomic JSON write (2-space indent) — serialize then write through the atomic
@@ -39,8 +41,114 @@ function realpathOrNull(absPath) {
 	}
 }
 //#endregion
+//#region src/files/byPath.ts
+var MARKDOWN_EXTENSIONS = [".md"];
+var HTML_EXTENSIONS = [".html", ".htm"];
+/** Absolute on-disk path for a caller-supplied path with one of `extensions`,
+*  or null when the value is not usable on this platform. */
+function resolveByPath(root, value, extensions) {
+	const kind = require_artifacts_paths.classifyFilePath(value, extensions);
+	if (kind === null) return null;
+	if (kind === "relative") return node_path.default.resolve(root, value);
+	return node_path.default.isAbsolute(value) ? node_path.default.resolve(value) : null;
+}
+/** True when the path names an existing regular file. */
+async function existsAsFile(root, value, extensions) {
+	const absPath = resolveByPath(root, value, extensions);
+	return absPath === null ? false : await regularFileTarget(absPath) !== null;
+}
+function resolveOrThrow({ rootFor, extensions }, value) {
+	const absPath = resolveByPath(rootFor(), value, extensions);
+	if (absPath === null) throw new Error(`invalid path: ${value}`);
+	return absPath;
+}
+/** The canonical REGULAR FILE a path names, or null when it is missing, is a
+*  directory, or is anything else (a FIFO would block a read forever).
+*  Resolved through `realpath` so a symlink is judged — and later written — by
+*  what it points at: `writeFileAtomic` renames a temp file into place, which
+*  through a link would replace the link itself and leave the real document
+*  untouched. */
+async function regularFileTarget(absPath) {
+	try {
+		const target = await (0, node_fs_promises.realpath)(absPath);
+		return (await (0, node_fs_promises.stat)(target)).isFile() ? target : null;
+	} catch {
+		return null;
+	}
+}
+/** The file to read or overwrite. Throws rather than creating: neither tool
+*  ever writes to a path that does not already hold a document. */
+async function existingFileFor(options, rel) {
+	const target = await regularFileTarget(resolveOrThrow(options, rel));
+	if (target === null) throw new Error(`no file exists at ${rel}`);
+	return target;
+}
+/** Browsing and deleting are NOT part of this capability: it exists so a view
+*  can read and re-save the ONE document the tool call named, not to enumerate
+*  a directory it was never pointed at or remove a file. */
+function unsupported(operation) {
+	return () => Promise.reject(/* @__PURE__ */ new Error(`byPath FileOps does not support ${operation}`));
+}
+/** FileOps over caller-supplied paths — what a host injects as `files.byPath`
+*  for plugins whose `path` argument may leave their artifact directory. Every
+*  method takes the same value the tool call carried, not a scope-relative one. */
+function createByPathFileOps(options) {
+	return {
+		read: async (rel) => (0, node_fs_promises.readFile)(await existingFileFor(options, rel), "utf-8"),
+		readBytes: async (rel) => {
+			const buf = await (0, node_fs_promises.readFile)(await existingFileFor(options, rel));
+			return new Uint8Array(buf.buffer, buf.byteOffset, buf.byteLength);
+		},
+		write: async (rel, content) => require_atomic.writeFileAtomic(await existingFileFor(options, rel), content),
+		readDir: unsupported("readDir"),
+		stat: async (rel) => {
+			const { mtimeMs, size } = await (0, node_fs_promises.stat)(resolveOrThrow(options, rel));
+			return {
+				mtimeMs,
+				size
+			};
+		},
+		exists: (rel) => existsAsFile(options.rootFor(), rel, options.extensions),
+		unlink: unsupported("unlink")
+	};
+}
+//#endregion
+//#region src/files/htmlFileRequest.ts
+var HTML_FILE_SCOPE_WORKSPACE = "ws";
+var HTML_FILE_SCOPE_ABSOLUTE = "abs";
+var WINDOWS_DRIVE_ONLY_RE = /^[a-zA-Z]:$/;
+function decodeSegments(reqPath) {
+	let decoded;
+	try {
+		decoded = reqPath.replace(/^\//, "").split("/").map((segment) => decodeURIComponent(segment));
+	} catch {
+		return null;
+	}
+	return decoded.some((segment) => segment.includes("/") || segment.includes("\\")) ? null : decoded;
+}
+/** Absolute path for a `/htmlfile/<scope>/<segments…>` request, or null when
+*  the URL is malformed, uses an unknown scope, or touches a `.` / `..` /
+*  dotfile segment. `workspaceRoot` should already be a realpath. */
+function resolveHtmlFileRequestPath(workspaceRoot, reqPath) {
+	const decoded = decodeSegments(reqPath);
+	if (decoded === null || decoded.length < 2) return null;
+	const [scope, ...rest] = decoded;
+	if (scope !== HTML_FILE_SCOPE_WORKSPACE && scope !== HTML_FILE_SCOPE_ABSOLUTE) return null;
+	if (rest.length === 0) return null;
+	if (rest.some((segment) => segment === "" || segment === "." || segment === ".." || segment.startsWith(".") || segment.includes("\0"))) return null;
+	if (scope === HTML_FILE_SCOPE_WORKSPACE) return node_path.default.resolve(workspaceRoot, ...rest);
+	const candidate = WINDOWS_DRIVE_ONLY_RE.test(rest[0]) ? rest.join("/") : `/${rest.join("/")}`;
+	return node_path.default.isAbsolute(candidate) ? node_path.default.resolve(candidate) : null;
+}
+//#endregion
+exports.HTML_EXTENSIONS = HTML_EXTENSIONS;
+exports.MARKDOWN_EXTENSIONS = MARKDOWN_EXTENSIONS;
+exports.createByPathFileOps = createByPathFileOps;
+exports.existsAsFile = existsAsFile;
 exports.isEnoent = isEnoent;
 exports.joinPosixRelPath = require_relPath.joinPosixRelPath;
+exports.resolveByPath = resolveByPath;
+exports.resolveHtmlFileRequestPath = resolveHtmlFileRequestPath;
 exports.resolveWithinRoot = resolveWithinRoot;
 exports.toPosixRelPath = require_relPath.toPosixRelPath;
 exports.writeFileAtomic = require_atomic.writeFileAtomic;

package/dist/files/index.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"index.cjs","names":[],"sources":["../../src/files/json.ts","../../src/files/safe.ts"],"sourcesContent":["import { writeFileAtomic, type WriteAtomicOptions } from \"./atomic.js\";\n\nconst JSON_INDENT = 2;\n\n/** Atomic JSON write (2-space indent) — serialize then write through the atomic\n *  tmp-file + rename seam so a reader never sees a half-written document. */\nexport async function writeJsonAtomic(filePath: string, data: unknown, opts: WriteAtomicOptions = {}): Promise<void> {\n  await writeFileAtomic(filePath, JSON.stringify(data, null, JSON_INDENT), opts);\n}\n","import { realpathSync } from \"node:fs\";\nimport path from \"node:path\";\n\n/** True for a `not found` filesystem error (ENOENT) — lets callers treat a\n *  missing file as an empty/default result instead of a thrown error. */\nexport function isEnoent(err: unknown): boolean {\n  return typeof err === \"object\" && err !== null && \"code\" in err && err.code === \"ENOENT\";\n}\n\n/** Realpath-based read-time containment: resolve `relPath` against the root's\n *  realpath and require the target's realpath to stay inside it. Returns null\n *  on ENOENT or traversal (symlink escapes included). `rootReal` MUST already\n *  be a realpath. The one implementation for host and plugins (#2461) — this\n *  security-critical primitive must not drift per consumer. */\nexport function resolveWithinRoot(rootReal: string, relPath: string): string | null {\n  const normalized = path.normalize(relPath || \"\");\n  const resolved = path.resolve(rootReal, normalized);\n  const resolvedReal = realpathOrNull(resolved);\n  if (resolvedReal === null) return null;\n  if (resolvedReal !== rootReal && !resolvedReal.startsWith(rootReal + path.sep)) {\n    return null;\n  }\n  return resolvedReal;\n}\n\nfunction realpathOrNull(absPath: string): string | null {\n  try {\n    return realpathSync(absPath);\n  } catch {\n    return null;\n  }\n}\n"],"mappings":";;;;;;;;AAEA,IAAM,cAAc;;;AAIpB,eAAsB,gBAAgB,UAAkB,MAAe,OAA2B,CAAC,GAAkB;CACnH,MAAM,eAAA,gBAAgB,UAAU,KAAK,UAAU,MAAM,MAAM,WAAW,GAAG,IAAI;AAC/E;;;;;ACHA,SAAgB,SAAS,KAAuB;CAC9C,OAAO,OAAO,QAAQ,YAAY,QAAQ,QAAQ,UAAU,OAAO,IAAI,SAAS;AAClF;;;;;;AAOA,SAAgB,kBAAkB,UAAkB,SAAgC;CAClF,MAAM,aAAa,UAAA,QAAK,UAAU,WAAW,EAAE;CAE/C,MAAM,eAAe,eADJ,UAAA,QAAK,QAAQ,UAAU,UACJ,CAAQ;CAC5C,IAAI,iBAAiB,MAAM,OAAO;CAClC,IAAI,iBAAiB,YAAY,CAAC,aAAa,WAAW,WAAW,UAAA,QAAK,GAAG,GAC3E,OAAO;CAET,OAAO;AACT;AAEA,SAAS,eAAe,SAAgC;CACtD,IAAI;EACF,QAAA,GAAA,QAAA,aAAA,CAAoB,OAAO;CAC7B,QAAQ;EACN,OAAO;CACT;AACF"}
+{"version":3,"file":"index.cjs","names":[],"sources":["../../src/files/json.ts","../../src/files/safe.ts","../../src/files/byPath.ts","../../src/files/htmlFileRequest.ts"],"sourcesContent":["import { writeFileAtomic, type WriteAtomicOptions } from \"./atomic.js\";\n\nconst JSON_INDENT = 2;\n\n/** Atomic JSON write (2-space indent) — serialize then write through the atomic\n *  tmp-file + rename seam so a reader never sees a half-written document. */\nexport async function writeJsonAtomic(filePath: string, data: unknown, opts: WriteAtomicOptions = {}): Promise<void> {\n  await writeFileAtomic(filePath, JSON.stringify(data, null, JSON_INDENT), opts);\n}\n","import { realpathSync } from \"node:fs\";\nimport path from \"node:path\";\n\n/** True for a `not found` filesystem error (ENOENT) — lets callers treat a\n *  missing file as an empty/default result instead of a thrown error. */\nexport function isEnoent(err: unknown): boolean {\n  return typeof err === \"object\" && err !== null && \"code\" in err && err.code === \"ENOENT\";\n}\n\n/** Realpath-based read-time containment: resolve `relPath` against the root's\n *  realpath and require the target's realpath to stay inside it. Returns null\n *  on ENOENT or traversal (symlink escapes included). `rootReal` MUST already\n *  be a realpath. The one implementation for host and plugins (#2461) — this\n *  security-critical primitive must not drift per consumer. */\nexport function resolveWithinRoot(rootReal: string, relPath: string): string | null {\n  const normalized = path.normalize(relPath || \"\");\n  const resolved = path.resolve(rootReal, normalized);\n  const resolvedReal = realpathOrNull(resolved);\n  if (resolvedReal === null) return null;\n  if (resolvedReal !== rootReal && !resolvedReal.startsWith(rootReal + path.sep)) {\n    return null;\n  }\n  return resolvedReal;\n}\n\nfunction realpathOrNull(absPath: string): string | null {\n  try {\n    return realpathSync(absPath);\n  } catch {\n    return null;\n  }\n}\n","// Read / overwrite files the TOOL CALL named, rather than files the app minted.\n// `presentDocument(path)` / `presentHtml(path)` open a document that already\n// exists — a repo's `README.md`, `docs/report.html`, an absolute path — and the\n// user's edits in the view overwrite it in place.\n//\n// Shared by both hosts (MulmoClaude's `server/utils/files/by-path.ts` and\n// MulmoTerminal's backend bind their own workspace root to it), because the\n// judgement of what a `path` argument may reach is exactly the thing that must\n// not drift between them: a host that accepts what the other refuses turns one\n// tool call into two different behaviours.\n//\n// The rules:\n//   - `classifyFilePath` (also what the plugins' `path` gate calls) decides the\n//     shape: right extension, no NUL, no `.` / `..` / empty segment. That\n//     lexical guard is what stops a vetted path from being re-pointed later.\n//   - relative paths resolve against the injected root; absolute paths are taken\n//     as given. There is deliberately NO containment check — opening a file\n//     outside the workspace is the documented purpose of the `path` form. The\n//     agent can already read and write those files directly; what is new is that\n//     the view can too.\n//   - a value that is absolute only under ANOTHER platform's rules is refused:\n//     `classifyFilePath` recognises `C:\\proj\\x.md` everywhere (the value may\n//     come from a remote host), but on POSIX `path.resolve(\"C:/proj/x.md\")`\n//     lands under the process cwd — a file nobody named.\n//   - reads and writes require a REGULAR FILE, judged through `realpath` so a\n//     symlink is assessed by what it points at and a directory named `x.md`\n//     cannot masquerade as a document.\n//   - `write` overwrites only. Neither tool creates a file at a caller-supplied\n//     path, so a write to a path that does not exist means the view is stale or\n//     the path was wrong — refusing keeps a typo from scattering files.\n//   - `readDir` and `unlink` are refused outright: this capability exists to\n//     read and re-save ONE named document, not to browse or delete.\n\nimport { readFile, realpath, stat as fsStat } from \"node:fs/promises\";\nimport path from \"node:path\";\nimport { classifyFilePath } from \"../artifacts/paths.js\";\nimport { writeFileAtomic } from \"./atomic.js\";\n\nexport const MARKDOWN_EXTENSIONS = [\".md\"] as const;\nexport const HTML_EXTENSIONS = [\".html\", \".htm\"] as const;\n\n/** Minimal structural echo of gui-chat-protocol's `FileOps`. Declared here\n *  rather than imported so core keeps no dependency on the protocol package;\n *  a host assigns the result straight to a `FileOps`-typed capability. */\nexport interface ByPathFileOps {\n  read: (rel: string) => Promise<string>;\n  readBytes: (rel: string) => Promise<Uint8Array>;\n  write: (rel: string, content: string | Uint8Array) => Promise<void>;\n  readDir: (rel: string) => Promise<string[]>;\n  stat: (rel: string) => Promise<{ mtimeMs: number; size: number }>;\n  exists: (rel: string) => Promise<boolean>;\n  unlink: (rel: string) => Promise<void>;\n}\n\n/** Absolute on-disk path for a caller-supplied path with one of `extensions`,\n *  or null when the value is not usable on this platform. */\nexport function resolveByPath(root: string, value: string, extensions: readonly string[]): string | null {\n  const kind = classifyFilePath(value, extensions);\n  if (kind === null) return null;\n  if (kind === \"relative\") return path.resolve(root, value);\n  return path.isAbsolute(value) ? path.resolve(value) : null;\n}\n\n/** True when the path names an existing regular file. */\nexport async function existsAsFile(root: string, value: string, extensions: readonly string[]): Promise<boolean> {\n  const absPath = resolveByPath(root, value, extensions);\n  return absPath === null ? false : (await regularFileTarget(absPath)) !== null;\n}\n\nexport interface ByPathOptions {\n  /** The root relative values resolve against, read PER CALL — hosts inject the\n   *  workspace after these ops are already bound into plugin closures. */\n  rootFor: () => string;\n  extensions: readonly string[];\n}\n\nfunction resolveOrThrow({ rootFor, extensions }: ByPathOptions, value: string): string {\n  const absPath = resolveByPath(rootFor(), value, extensions);\n  if (absPath === null) throw new Error(`invalid path: ${value}`);\n  return absPath;\n}\n\n/** The canonical REGULAR FILE a path names, or null when it is missing, is a\n *  directory, or is anything else (a FIFO would block a read forever).\n *  Resolved through `realpath` so a symlink is judged — and later written — by\n *  what it points at: `writeFileAtomic` renames a temp file into place, which\n *  through a link would replace the link itself and leave the real document\n *  untouched. */\nasync function regularFileTarget(absPath: string): Promise<string | null> {\n  try {\n    const target = await realpath(absPath);\n    return (await fsStat(target)).isFile() ? target : null;\n  } catch {\n    return null;\n  }\n}\n\n/** The file to read or overwrite. Throws rather than creating: neither tool\n *  ever writes to a path that does not already hold a document. */\nasync function existingFileFor(options: ByPathOptions, rel: string): Promise<string> {\n  const target = await regularFileTarget(resolveOrThrow(options, rel));\n  if (target === null) throw new Error(`no file exists at ${rel}`);\n  return target;\n}\n\n/** Browsing and deleting are NOT part of this capability: it exists so a view\n *  can read and re-save the ONE document the tool call named, not to enumerate\n *  a directory it was never pointed at or remove a file. */\nfunction unsupported(operation: string): () => Promise<never> {\n  return () => Promise.reject(new Error(`byPath FileOps does not support ${operation}`));\n}\n\n/** FileOps over caller-supplied paths — what a host injects as `files.byPath`\n *  for plugins whose `path` argument may leave their artifact directory. Every\n *  method takes the same value the tool call carried, not a scope-relative one. */\nexport function createByPathFileOps(options: ByPathOptions): ByPathFileOps {\n  return {\n    read: async (rel) => readFile(await existingFileFor(options, rel), \"utf-8\"),\n    readBytes: async (rel) => {\n      const buf = await readFile(await existingFileFor(options, rel));\n      return new Uint8Array(buf.buffer, buf.byteOffset, buf.byteLength);\n    },\n    write: async (rel, content) => writeFileAtomic(await existingFileFor(options, rel), content),\n    readDir: unsupported(\"readDir\"),\n    stat: async (rel) => {\n      const { mtimeMs, size } = await fsStat(resolveOrThrow(options, rel));\n      return { mtimeMs, size };\n    },\n    exists: (rel) => existsAsFile(options.rootFor(), rel, options.extensions),\n    unlink: unsupported(\"unlink\"),\n  };\n}\n","// Server half of the `/htmlfile` scheme (client half: `src/config/htmlFileUrl.ts`).\n// Turns a request path into the absolute file to serve, or null.\n//\n// Shared by both hosts so the URL the View asks for and the file a host resolves\n// cannot drift apart.\n//\n// This mount is deliberately NOT contained to a root: presentHtml's `path` form\n// may name any HTML page on disk, and serving it is the point. What still holds:\n//\n//   - only `ws` (workspace-relative) and `abs` (absolute) scopes exist; anything\n//     else 404s, so a bare `/htmlfile/etc/passwd` is not a path at all.\n//   - no `.` / `..` / empty segment survives, so a vetted URL cannot be\n//     re-pointed by traversal, and no dotfile segment is reachable (same policy\n//     as `resolveArtifactRequestPath`, which the artifact mounts share).\n//   - extension allowlist, realpath and regular-file checks stay with the host's\n//     mount, which is also where the CSP header and rate limit are applied.\n//\n// The trust boundary is whatever the host applies to its `/artifacts/html`\n// mount — in MulmoClaude, the loopback-only listener plus `requireSameOrigin`\n// (bearer auth does not apply outside `/api`, and an iframe `src` request cannot\n// carry an Authorization header anyway).\n\nimport path from \"node:path\";\n// The scope constants are re-declared rather than imported: core must not\n// depend on a plugin (dependencies flow the other way). `html-plugin`'s\n// `htmlFileUrl` builds the URLs these parse, and the round-trip test in the host\n// is what keeps the two halves honest.\nconst HTML_FILE_SCOPE_WORKSPACE = \"ws\";\nconst HTML_FILE_SCOPE_ABSOLUTE = \"abs\";\n\nconst WINDOWS_DRIVE_ONLY_RE = /^[a-zA-Z]:$/;\n\nfunction decodeSegments(reqPath: string): string[] | null {\n  let decoded: string[];\n  try {\n    decoded = reqPath\n      .replace(/^\\//, \"\")\n      .split(\"/\")\n      .map((segment) => decodeURIComponent(segment));\n  } catch {\n    // Malformed escape (`%ZZ`) — fail closed rather than bubbling a URIError.\n    return null;\n  }\n  // Segmentation happens on the ENCODED path, so a `%2F` (or `%5C`) becomes a\n  // separator only after this decode — `a%2F..%2F..%2Ftmp%2Fx.html` would arrive\n  // as one segment that the `..` check below never sees, and then split apart\n  // inside `path.resolve`. A decoded segment that still contains a separator is\n  // never legitimate here, so refuse it.\n  return decoded.some((segment) => segment.includes(\"/\") || segment.includes(\"\\\\\")) ? null : decoded;\n}\n\n/** Absolute path for a `/htmlfile/<scope>/<segments…>` request, or null when\n *  the URL is malformed, uses an unknown scope, or touches a `.` / `..` /\n *  dotfile segment. `workspaceRoot` should already be a realpath. */\nexport function resolveHtmlFileRequestPath(workspaceRoot: string, reqPath: string): string | null {\n  const decoded = decodeSegments(reqPath);\n  if (decoded === null || decoded.length < 2) return null;\n  const [scope, ...rest] = decoded;\n  if (scope !== HTML_FILE_SCOPE_WORKSPACE && scope !== HTML_FILE_SCOPE_ABSOLUTE) return null;\n  if (rest.length === 0) return null;\n  if (rest.some((segment) => segment === \"\" || segment === \".\" || segment === \"..\" || segment.startsWith(\".\") || segment.includes(\"\\0\"))) {\n    return null;\n  }\n  if (scope === HTML_FILE_SCOPE_WORKSPACE) return path.resolve(workspaceRoot, ...rest);\n  // `abs/C:/proj/page.html` — the drive letter arrives as its own segment, so\n  // rejoin it before resolving; everything else is rooted at `/`.\n  const candidate = WINDOWS_DRIVE_ONLY_RE.test(rest[0]) ? rest.join(\"/\") : `/${rest.join(\"/\")}`;\n  // Only THIS platform's `path` can say whether that is really absolute: on\n  // POSIX, `path.resolve(\"C:/proj/page.html\")` would land under the process cwd\n  // rather than at any drive, silently serving the wrong file. Refuse instead.\n  return path.isAbsolute(candidate) ? path.resolve(candidate) : null;\n}\n"],"mappings":";;;;;;;;;;AAEA,IAAM,cAAc;;;AAIpB,eAAsB,gBAAgB,UAAkB,MAAe,OAA2B,CAAC,GAAkB;CACnH,MAAM,eAAA,gBAAgB,UAAU,KAAK,UAAU,MAAM,MAAM,WAAW,GAAG,IAAI;AAC/E;;;;;ACHA,SAAgB,SAAS,KAAuB;CAC9C,OAAO,OAAO,QAAQ,YAAY,QAAQ,QAAQ,UAAU,OAAO,IAAI,SAAS;AAClF;;;;;;AAOA,SAAgB,kBAAkB,UAAkB,SAAgC;CAClF,MAAM,aAAa,UAAA,QAAK,UAAU,WAAW,EAAE;CAE/C,MAAM,eAAe,eADJ,UAAA,QAAK,QAAQ,UAAU,UACJ,CAAQ;CAC5C,IAAI,iBAAiB,MAAM,OAAO;CAClC,IAAI,iBAAiB,YAAY,CAAC,aAAa,WAAW,WAAW,UAAA,QAAK,GAAG,GAC3E,OAAO;CAET,OAAO;AACT;AAEA,SAAS,eAAe,SAAgC;CACtD,IAAI;EACF,QAAA,GAAA,QAAA,aAAA,CAAoB,OAAO;CAC7B,QAAQ;EACN,OAAO;CACT;AACF;;;ACOA,IAAa,sBAAsB,CAAC,KAAK;AACzC,IAAa,kBAAkB,CAAC,SAAS,MAAM;;;AAiB/C,SAAgB,cAAc,MAAc,OAAe,YAA8C;CACvG,MAAM,OAAO,wBAAA,iBAAiB,OAAO,UAAU;CAC/C,IAAI,SAAS,MAAM,OAAO;CAC1B,IAAI,SAAS,YAAY,OAAO,UAAA,QAAK,QAAQ,MAAM,KAAK;CACxD,OAAO,UAAA,QAAK,WAAW,KAAK,IAAI,UAAA,QAAK,QAAQ,KAAK,IAAI;AACxD;;AAGA,eAAsB,aAAa,MAAc,OAAe,YAAiD;CAC/G,MAAM,UAAU,cAAc,MAAM,OAAO,UAAU;CACrD,OAAO,YAAY,OAAO,QAAS,MAAM,kBAAkB,OAAO,MAAO;AAC3E;AASA,SAAS,eAAe,EAAE,SAAS,cAA6B,OAAuB;CACrF,MAAM,UAAU,cAAc,QAAQ,GAAG,OAAO,UAAU;CAC1D,IAAI,YAAY,MAAM,MAAM,IAAI,MAAM,iBAAiB,OAAO;CAC9D,OAAO;AACT;;;;;;;AAQA,eAAe,kBAAkB,SAAyC;CACxE,IAAI;EACF,MAAM,SAAS,OAAA,GAAA,iBAAA,SAAA,CAAe,OAAO;EACrC,QAAQ,OAAA,GAAA,iBAAA,KAAA,CAAa,MAAM,EAAA,CAAG,OAAO,IAAI,SAAS;CACpD,QAAQ;EACN,OAAO;CACT;AACF;;;AAIA,eAAe,gBAAgB,SAAwB,KAA8B;CACnF,MAAM,SAAS,MAAM,kBAAkB,eAAe,SAAS,GAAG,CAAC;CACnE,IAAI,WAAW,MAAM,MAAM,IAAI,MAAM,qBAAqB,KAAK;CAC/D,OAAO;AACT;;;;AAKA,SAAS,YAAY,WAAyC;CAC5D,aAAa,QAAQ,uBAAO,IAAI,MAAM,mCAAmC,WAAW,CAAC;AACvF;;;;AAKA,SAAgB,oBAAoB,SAAuC;CACzE,OAAO;EACL,MAAM,OAAO,SAAA,GAAA,iBAAA,SAAA,CAAiB,MAAM,gBAAgB,SAAS,GAAG,GAAG,OAAO;EAC1E,WAAW,OAAO,QAAQ;GACxB,MAAM,MAAM,OAAA,GAAA,iBAAA,SAAA,CAAe,MAAM,gBAAgB,SAAS,GAAG,CAAC;GAC9D,OAAO,IAAI,WAAW,IAAI,QAAQ,IAAI,YAAY,IAAI,UAAU;EAClE;EACA,OAAO,OAAO,KAAK,YAAY,eAAA,gBAAgB,MAAM,gBAAgB,SAAS,GAAG,GAAG,OAAO;EAC3F,SAAS,YAAY,SAAS;EAC9B,MAAM,OAAO,QAAQ;GACnB,MAAM,EAAE,SAAS,SAAS,OAAA,GAAA,iBAAA,KAAA,CAAa,eAAe,SAAS,GAAG,CAAC;GACnE,OAAO;IAAE;IAAS;GAAK;EACzB;EACA,SAAS,QAAQ,aAAa,QAAQ,QAAQ,GAAG,KAAK,QAAQ,UAAU;EACxE,QAAQ,YAAY,QAAQ;CAC9B;AACF;;;ACxGA,IAAM,4BAA4B;AAClC,IAAM,2BAA2B;AAEjC,IAAM,wBAAwB;AAE9B,SAAS,eAAe,SAAkC;CACxD,IAAI;CACJ,IAAI;EACF,UAAU,QACP,QAAQ,OAAO,EAAE,CAAC,CAClB,MAAM,GAAG,CAAC,CACV,KAAK,YAAY,mBAAmB,OAAO,CAAC;CACjD,QAAQ;EAEN,OAAO;CACT;CAMA,OAAO,QAAQ,MAAM,YAAY,QAAQ,SAAS,GAAG,KAAK,QAAQ,SAAS,IAAI,CAAC,IAAI,OAAO;AAC7F;;;;AAKA,SAAgB,2BAA2B,eAAuB,SAAgC;CAChG,MAAM,UAAU,eAAe,OAAO;CACtC,IAAI,YAAY,QAAQ,QAAQ,SAAS,GAAG,OAAO;CACnD,MAAM,CAAC,OAAO,GAAG,QAAQ;CACzB,IAAI,UAAU,6BAA6B,UAAU,0BAA0B,OAAO;CACtF,IAAI,KAAK,WAAW,GAAG,OAAO;CAC9B,IAAI,KAAK,MAAM,YAAY,YAAY,MAAM,YAAY,OAAO,YAAY,QAAQ,QAAQ,WAAW,GAAG,KAAK,QAAQ,SAAS,IAAI,CAAC,GACnI,OAAO;CAET,IAAI,UAAU,2BAA2B,OAAO,UAAA,QAAK,QAAQ,eAAe,GAAG,IAAI;CAGnF,MAAM,YAAY,sBAAsB,KAAK,KAAK,EAAE,IAAI,KAAK,KAAK,GAAG,IAAI,IAAI,KAAK,KAAK,GAAG;CAI1F,OAAO,UAAA,QAAK,WAAW,SAAS,IAAI,UAAA,QAAK,QAAQ,SAAS,IAAI;AAChE"}

package/dist/files/index.d.ts

@@ -2,3 +2,5 @@ export { writeFileAtomic, writeFileAtomicSync, type WriteAtomicOptions } from '.
 export { writeJsonAtomic } from './json.js';
 export { isEnoent, resolveWithinRoot } from './safe.js';
 export { toPosixRelPath, joinPosixRelPath } from './relPath.js';
+export { resolveByPath, existsAsFile, createByPathFileOps, MARKDOWN_EXTENSIONS, HTML_EXTENSIONS, type ByPathFileOps, type ByPathOptions } from './byPath.js';
+export { resolveHtmlFileRequestPath } from './htmlFileRequest.js';

package/dist/files/index.js

@@ -1,7 +1,9 @@
+import { classifyFilePath } from "../artifacts/paths.js";
 import { n as writeFileAtomicSync, t as writeFileAtomic } from "../atomic-DPpdrJzO.js";
 import { n as toPosixRelPath, t as joinPosixRelPath } from "../relPath-DW8MC8VO.js";
 import { realpathSync } from "node:fs";
 import path from "node:path";
+import { readFile, realpath, stat } from "node:fs/promises";
 //#region src/files/json.ts
 var JSON_INDENT = 2;
 /** Atomic JSON write (2-space indent) — serialize then write through the atomic
@@ -36,6 +38,106 @@ function realpathOrNull(absPath) {
 	}
 }
 //#endregion
-export { isEnoent, joinPosixRelPath, resolveWithinRoot, toPosixRelPath, writeFileAtomic, writeFileAtomicSync, writeJsonAtomic };
+//#region src/files/byPath.ts
+var MARKDOWN_EXTENSIONS = [".md"];
+var HTML_EXTENSIONS = [".html", ".htm"];
+/** Absolute on-disk path for a caller-supplied path with one of `extensions`,
+*  or null when the value is not usable on this platform. */
+function resolveByPath(root, value, extensions) {
+	const kind = classifyFilePath(value, extensions);
+	if (kind === null) return null;
+	if (kind === "relative") return path.resolve(root, value);
+	return path.isAbsolute(value) ? path.resolve(value) : null;
+}
+/** True when the path names an existing regular file. */
+async function existsAsFile(root, value, extensions) {
+	const absPath = resolveByPath(root, value, extensions);
+	return absPath === null ? false : await regularFileTarget(absPath) !== null;
+}
+function resolveOrThrow({ rootFor, extensions }, value) {
+	const absPath = resolveByPath(rootFor(), value, extensions);
+	if (absPath === null) throw new Error(`invalid path: ${value}`);
+	return absPath;
+}
+/** The canonical REGULAR FILE a path names, or null when it is missing, is a
+*  directory, or is anything else (a FIFO would block a read forever).
+*  Resolved through `realpath` so a symlink is judged — and later written — by
+*  what it points at: `writeFileAtomic` renames a temp file into place, which
+*  through a link would replace the link itself and leave the real document
+*  untouched. */
+async function regularFileTarget(absPath) {
+	try {
+		const target = await realpath(absPath);
+		return (await stat(target)).isFile() ? target : null;
+	} catch {
+		return null;
+	}
+}
+/** The file to read or overwrite. Throws rather than creating: neither tool
+*  ever writes to a path that does not already hold a document. */
+async function existingFileFor(options, rel) {
+	const target = await regularFileTarget(resolveOrThrow(options, rel));
+	if (target === null) throw new Error(`no file exists at ${rel}`);
+	return target;
+}
+/** Browsing and deleting are NOT part of this capability: it exists so a view
+*  can read and re-save the ONE document the tool call named, not to enumerate
+*  a directory it was never pointed at or remove a file. */
+function unsupported(operation) {
+	return () => Promise.reject(/* @__PURE__ */ new Error(`byPath FileOps does not support ${operation}`));
+}
+/** FileOps over caller-supplied paths — what a host injects as `files.byPath`
+*  for plugins whose `path` argument may leave their artifact directory. Every
+*  method takes the same value the tool call carried, not a scope-relative one. */
+function createByPathFileOps(options) {
+	return {
+		read: async (rel) => readFile(await existingFileFor(options, rel), "utf-8"),
+		readBytes: async (rel) => {
+			const buf = await readFile(await existingFileFor(options, rel));
+			return new Uint8Array(buf.buffer, buf.byteOffset, buf.byteLength);
+		},
+		write: async (rel, content) => writeFileAtomic(await existingFileFor(options, rel), content),
+		readDir: unsupported("readDir"),
+		stat: async (rel) => {
+			const { mtimeMs, size } = await stat(resolveOrThrow(options, rel));
+			return {
+				mtimeMs,
+				size
+			};
+		},
+		exists: (rel) => existsAsFile(options.rootFor(), rel, options.extensions),
+		unlink: unsupported("unlink")
+	};
+}
+//#endregion
+//#region src/files/htmlFileRequest.ts
+var HTML_FILE_SCOPE_WORKSPACE = "ws";
+var HTML_FILE_SCOPE_ABSOLUTE = "abs";
+var WINDOWS_DRIVE_ONLY_RE = /^[a-zA-Z]:$/;
+function decodeSegments(reqPath) {
+	let decoded;
+	try {
+		decoded = reqPath.replace(/^\//, "").split("/").map((segment) => decodeURIComponent(segment));
+	} catch {
+		return null;
+	}
+	return decoded.some((segment) => segment.includes("/") || segment.includes("\\")) ? null : decoded;
+}
+/** Absolute path for a `/htmlfile/<scope>/<segments…>` request, or null when
+*  the URL is malformed, uses an unknown scope, or touches a `.` / `..` /
+*  dotfile segment. `workspaceRoot` should already be a realpath. */
+function resolveHtmlFileRequestPath(workspaceRoot, reqPath) {
+	const decoded = decodeSegments(reqPath);
+	if (decoded === null || decoded.length < 2) return null;
+	const [scope, ...rest] = decoded;
+	if (scope !== HTML_FILE_SCOPE_WORKSPACE && scope !== HTML_FILE_SCOPE_ABSOLUTE) return null;
+	if (rest.length === 0) return null;
+	if (rest.some((segment) => segment === "" || segment === "." || segment === ".." || segment.startsWith(".") || segment.includes("\0"))) return null;
+	if (scope === HTML_FILE_SCOPE_WORKSPACE) return path.resolve(workspaceRoot, ...rest);
+	const candidate = WINDOWS_DRIVE_ONLY_RE.test(rest[0]) ? rest.join("/") : `/${rest.join("/")}`;
+	return path.isAbsolute(candidate) ? path.resolve(candidate) : null;
+}
+//#endregion
+export { HTML_EXTENSIONS, MARKDOWN_EXTENSIONS, createByPathFileOps, existsAsFile, isEnoent, joinPosixRelPath, resolveByPath, resolveHtmlFileRequestPath, resolveWithinRoot, toPosixRelPath, writeFileAtomic, writeFileAtomicSync, writeJsonAtomic };
 
 //# sourceMappingURL=index.js.map