@stigmer/plugin-package 3.15.3-dev.20260916211208

package/src/dialects/manifest.ts

@@ -0,0 +1,237 @@
+/**
+ * The intermediate every dialect reader reduces its manifest to, and the
+ * field-reading helpers they share.
+ *
+ * A `DialectManifest` says what one manifest CONTRIBUTES: identity fields,
+ * declared component paths, MCP configuration sources, a variables block,
+ * and the fields it carries that Stigmer records as ignored. It does not
+ * decide anything across manifests: precedence, name conflicts and default
+ * locations are `detect.ts`'s, and turning declarations into skills,
+ * servers and variables is `normalise/`'s. Keeping the readers to "what
+ * does this file say" is what lets a plugin carry a root manifest and a
+ * vendor manifest at once and have both read.
+ *
+ * Unknown fields WARN in every dialect (the open format says report and
+ * ignore; Cursor's own validator would reject them, but a warning serves
+ * the author and the install still works). A known field of the wrong type
+ * is fatal (`manifest-field-type`), the open format's rule for any
+ * violation other than an unknown field.
+ */
+
+import { fields, isJsonObject, type JsonObject, optionalString, optionalStringArray, stringOrStringArray } from "../documents.js";
+import { resolveDeclaredPath } from "../files.js";
+import type { Findings } from "../messages.js";
+import type { IgnoredComponent, IgnoredComponentKind, PluginAuthor, PluginDialect } from "../types.js";
+
+export interface PluginIdentity {
+  readonly name?: string;
+  readonly version?: string;
+  readonly description?: string;
+  readonly author?: PluginAuthor;
+  readonly homepage?: string;
+  readonly repository?: string;
+  readonly license?: string;
+  readonly keywords?: readonly string[];
+}
+
+/** A component path a manifest declared, normalised, with where it was declared. */
+export interface DeclaredPath {
+  /** Plugin-relative, no leading `./`, no trailing slash; the root is `""`. */
+  readonly path: string;
+  /** The manifest that declared it, for messages. */
+  readonly manifest: string;
+}
+
+/** Where MCP server entries come from: a configuration file, or an object inline in a manifest. */
+export type McpConfigSource =
+  | { readonly kind: "file"; readonly path: string; readonly dialect: PluginDialect; readonly manifest: string }
+  | { readonly kind: "inline"; readonly manifest: string; readonly servers: unknown; readonly dialect: PluginDialect };
+
+/** A variables block, raw, tagged with the dialect whose shape it takes. */
+export type VariablesDeclaration =
+  | { readonly dialect: "cursor"; readonly value: unknown; readonly manifest: string }
+  | { readonly dialect: "claude"; readonly value: unknown; readonly manifest: string };
+
+export interface DialectManifest {
+  readonly dialect: PluginDialect;
+  readonly path: string;
+  readonly identity: PluginIdentity;
+  /** Declared skill paths; the default `skills/` is scanned regardless. */
+  readonly skillPaths: readonly DeclaredPath[];
+  /** Declared agent paths; `undefined` leaves the default `agents/` scan in force. */
+  readonly agentPaths?: readonly DeclaredPath[];
+  readonly mcpConfigs: readonly McpConfigSource[];
+  readonly variables?: VariablesDeclaration;
+  readonly ignored: readonly IgnoredComponent[];
+}
+
+/** Warn once per field the dialect does not define. */
+export function warnUnknownFields(object: JsonObject, known: ReadonlySet<string>, path: string, findings: Findings): void {
+  for (const [name] of fields(object)) {
+    if (!known.has(name)) findings.warn("manifest-field-unknown", { path, subject: name });
+  }
+}
+
+/**
+ * The identity fields every dialect shares. `author` is an object in every
+ * dialect (Cursor's schema has no `url`; the extra key is a warning there,
+ * reported by the caller's known-field set for `author`).
+ */
+export function readIdentity(object: JsonObject, path: string, findings: Findings): PluginIdentity {
+  const identity: { -readonly [K in keyof PluginIdentity]: PluginIdentity[K] } = {};
+  const name = optionalString(object, "name", path, findings);
+  if (name !== undefined) identity.name = name;
+  const version = optionalString(object, "version", path, findings);
+  if (version !== undefined) identity.version = version;
+  const description = optionalString(object, "description", path, findings);
+  if (description !== undefined) identity.description = description;
+  const homepage = optionalString(object, "homepage", path, findings);
+  if (homepage !== undefined) identity.homepage = homepage;
+  const repository = optionalString(object, "repository", path, findings);
+  if (repository !== undefined) identity.repository = repository;
+  const license = optionalString(object, "license", path, findings);
+  if (license !== undefined) identity.license = license;
+  const keywords = optionalStringArray(object, "keywords", path, findings);
+  if (keywords !== undefined) identity.keywords = keywords;
+  const author = readAuthor(object, path, findings);
+  if (author !== undefined) identity.author = author;
+  return identity;
+}
+
+function readAuthor(object: JsonObject, path: string, findings: Findings): PluginAuthor | undefined {
+  const value = object["author"];
+  if (value === undefined) return undefined;
+  if (!isJsonObject(value)) {
+    findings.error("manifest-field-type", { path, subject: "author", detail: "an object" });
+    return undefined;
+  }
+  const author: { -readonly [K in keyof PluginAuthor]: PluginAuthor[K] } = {};
+  const name = optionalString(value, "name", path, findings);
+  if (name !== undefined) author.name = name;
+  const email = optionalString(value, "email", path, findings);
+  if (email !== undefined) author.email = email;
+  const url = optionalString(value, "url", path, findings);
+  if (url !== undefined) author.url = url;
+  return author;
+}
+
+/**
+ * A path field (`skills`, `agents`, ...) as declared paths. A value that is
+ * not a path (wrong prefix, escape, glob) is reported and dropped; the
+ * rest are kept, so one bad entry does not hide the others.
+ */
+export function readDeclaredPaths(
+  object: JsonObject,
+  field: string,
+  path: string,
+  findings: Findings,
+): readonly DeclaredPath[] | undefined {
+  const values = stringOrStringArray(object, field, path, findings);
+  if (values === undefined) return undefined;
+  const declared: DeclaredPath[] = [];
+  for (const value of values) {
+    const resolved = resolveDeclaredPath(value);
+    if (!resolved.ok) {
+      findings.error(resolved.kind, { path, subject: value });
+      continue;
+    }
+    declared.push({ path: resolved.path, manifest: path });
+  }
+  return declared;
+}
+
+/**
+ * A vendor `mcpServers` field: a path, an inline `mcpServers` object, or an
+ * array of either. Each becomes one source under the dialect's rules.
+ */
+export function readMcpSources(
+  object: JsonObject,
+  field: string,
+  path: string,
+  dialect: PluginDialect,
+  findings: Findings,
+): readonly McpConfigSource[] {
+  const value = object[field];
+  if (value === undefined) return [];
+  const items = Array.isArray(value) ? value : [value];
+  const sources: McpConfigSource[] = [];
+  for (const item of items) {
+    if (typeof item === "string") {
+      const resolved = resolveDeclaredPath(item);
+      if (!resolved.ok) {
+        findings.error(resolved.kind, { path, subject: item });
+        continue;
+      }
+      sources.push({ kind: "file", path: resolved.path, dialect, manifest: path });
+    } else if (isJsonObject(item)) {
+      sources.push({ kind: "inline", manifest: path, servers: item, dialect });
+    } else {
+      findings.error("manifest-field-type", { path, subject: field, detail: "a path, an object, or an array of either" });
+    }
+  }
+  return sources;
+}
+
+/**
+ * Manifest fields Stigmer reads past, recorded as ignored components at
+ * `<manifest>#<field>` when present. Shared across dialects; each names the
+ * fields it knows through `known` so the same field is never also an
+ * unknown-field warning.
+ */
+export const IGNORED_FIELD_KINDS: Readonly<Record<string, IgnoredComponentKind>> = {
+  hooks: "hooks",
+  rules: "rules",
+  commands: "commands",
+  workflows: "workflows",
+  outputStyles: "output-styles",
+  lspServers: "lsp-servers",
+  channels: "channels",
+  dependencies: "dependencies",
+  defaultEnabled: "default-enabled",
+  minClientVersions: "min-client-versions",
+  logo: "logo",
+  apps: "apps",
+};
+
+export function ignoredFieldComponents(object: JsonObject, path: string): IgnoredComponent[] {
+  const ignored: IgnoredComponent[] = [];
+  for (const [name, value] of fields(object)) {
+    const kind = IGNORED_FIELD_KINDS[name];
+    if (kind !== undefined) ignored.push({ kind, path: `${path}#${name}` });
+    if (name === "experimental" && isJsonObject(value)) {
+      for (const [sub] of fields(value)) {
+        const subKind = EXPERIMENTAL_KINDS[sub];
+        if (subKind !== undefined) ignored.push({ kind: subKind, path: `${path}#experimental.${sub}` });
+      }
+    }
+  }
+  return ignored;
+}
+
+const EXPERIMENTAL_KINDS: Readonly<Record<string, IgnoredComponentKind>> = {
+  themes: "themes",
+  monitors: "monitors",
+  evals: "evals",
+};
+
+/**
+ * `extensions` in a root manifest: every namespace with content is an
+ * ignored component (a client ignores namespaces it does not implement
+ * without validating them); an empty object, including Stigmer's own
+ * reserved `ai.stigmer`, is silent. A non-object `extensions` is the open
+ * format's one non-fatal type violation: reported and ignored.
+ */
+export function extensionComponents(object: JsonObject, path: string, findings: Findings): IgnoredComponent[] {
+  const value = object["extensions"];
+  if (value === undefined) return [];
+  if (!isJsonObject(value)) {
+    findings.warn("manifest-extensions-invalid", { path });
+    return [];
+  }
+  const ignored: IgnoredComponent[] = [];
+  for (const [namespace, content] of fields(value)) {
+    if (isJsonObject(content) && fields(content).length === 0) continue;
+    ignored.push({ kind: "extension", path: `${path}#extensions.${namespace}` });
+  }
+  return ignored;
+}

package/src/dialects/open.ts

@@ -0,0 +1,48 @@
+/**
+ * The Agent Plugins 1.0.0 root manifest (`plugin.json`).
+ *
+ * The open format's manifest is closed and versioned: `$schema` is required
+ * and must be the canonical 1.0.0 identifier, the ten permitted fields are
+ * fixed, an unknown field is reported and ignored, and any other violation
+ * is fatal. Components live at fixed locations only (`skills/`, `mcp.json`),
+ * so this manifest declares no paths and no inline servers; `mcp.json` is
+ * read under the open format's rules by `detect.ts` when it exists.
+ * Client-specific data belongs under `extensions`, which Stigmer records as
+ * ignored per namespace (its own `ai.stigmer` namespace is reserved and
+ * empty today).
+ */
+
+import { describeValue, type JsonObject } from "../documents.js";
+import { AGENT_PLUGINS_MANIFEST_SCHEMA, type Findings } from "../messages.js";
+import { type DialectManifest, extensionComponents, readIdentity, warnUnknownFields } from "./manifest.js";
+
+const KNOWN_FIELDS: ReadonlySet<string> = new Set([
+  "$schema",
+  "name",
+  "version",
+  "description",
+  "author",
+  "homepage",
+  "repository",
+  "license",
+  "keywords",
+  "extensions",
+]);
+
+export function readOpenManifest(object: JsonObject, path: string, findings: Findings): DialectManifest {
+  const schema = object["$schema"];
+  if (schema === undefined) {
+    findings.error("manifest-schema-missing", { path });
+  } else if (schema !== AGENT_PLUGINS_MANIFEST_SCHEMA) {
+    findings.error("manifest-schema-unsupported", { path, detail: describeValue(schema) });
+  }
+  warnUnknownFields(object, KNOWN_FIELDS, path, findings);
+  return {
+    dialect: "agent-plugins",
+    path,
+    identity: readIdentity(object, path, findings),
+    skillPaths: [],
+    mcpConfigs: [],
+    ignored: extensionComponents(object, path, findings),
+  };
+}

package/src/documents.ts

@@ -0,0 +1,145 @@
+/**
+ * Reading one document through its cap, and the JSON shape checks every
+ * dialect reader repeats.
+ *
+ * `readText` is the only place the library calls `PluginFiles.read`: the
+ * declared size is checked against the document class's cap first, the
+ * returned length second, and an over-cap document becomes a
+ * `document-too-large` finding instead of a read. The JSON helpers turn a
+ * parse failure into a finding of the caller's kind and leave the value
+ * `unknown`, so each reader narrows fields with the `expect*` helpers and
+ * reports a wrong type with the field's name rather than trusting a cast.
+ */
+
+import { decodeUtf8, PLUGIN_DOCUMENT_LIMITS, type PluginDocumentClass, type PluginFileIndex } from "./files.js";
+import type { Findings } from "./messages.js";
+import type { PluginErrorKind } from "./outcome.js";
+
+/** The document's text, or `undefined` after a `document-too-large` finding. */
+export function readText(
+  index: PluginFileIndex,
+  path: string,
+  cls: PluginDocumentClass,
+  findings: Findings,
+): string | undefined {
+  const bytes = readBytes(index, path, cls, findings);
+  return bytes === undefined ? undefined : decodeUtf8(bytes);
+}
+
+/** The document's bytes, or `undefined` after a `document-too-large` finding. */
+export function readBytes(
+  index: PluginFileIndex,
+  path: string,
+  cls: PluginDocumentClass,
+  findings: Findings,
+): Uint8Array | undefined {
+  const limit = PLUGIN_DOCUMENT_LIMITS[cls];
+  const entry = index.entry(path);
+  if (entry === undefined) {
+    throw new Error(`plugin file '${path}' is not listed`);
+  }
+  if (entry.size > limit) {
+    findings.error("document-too-large", { path, subject: String(entry.size), detail: String(limit) });
+    return undefined;
+  }
+  const bytes = index.files.read(path);
+  if (bytes.length > limit) {
+    findings.error("document-too-large", { path, subject: String(bytes.length), detail: String(limit) });
+    return undefined;
+  }
+  return bytes;
+}
+
+/** A parsed JSON object (non-null, non-array), or `undefined` after a finding of `kind`. */
+export function parseJsonObject(
+  text: string,
+  path: string,
+  kind: Extract<PluginErrorKind, "manifest-unreadable" | "mcp-config-unreadable">,
+  findings: Findings,
+): JsonObject | undefined {
+  let value: unknown;
+  try {
+    value = JSON.parse(text);
+  } catch (error) {
+    findings.error(kind, { path, detail: error instanceof Error ? error.message : String(error) });
+    return undefined;
+  }
+  if (!isJsonObject(value)) {
+    findings.error(kind, { path, detail: "the document is not a JSON object" });
+    return undefined;
+  }
+  return value;
+}
+
+export type JsonObject = Readonly<Record<string, unknown>>;
+
+export function isJsonObject(value: unknown): value is JsonObject {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+export function isStringArray(value: unknown): value is readonly string[] {
+  return Array.isArray(value) && value.every((item) => typeof item === "string");
+}
+
+export function isStringRecord(value: unknown): value is Readonly<Record<string, string>> {
+  return isJsonObject(value) && Object.values(value).every((item) => typeof item === "string");
+}
+
+/** A JSON value as a sentence can quote it: a string as itself, anything else serialised. */
+export function describeValue(value: unknown): string {
+  return typeof value === "string" ? value : JSON.stringify(value);
+}
+
+/**
+ * The fields of `object`, in the document's own order. `Object.entries`
+ * reads own enumerable properties only, so a `__proto__` key in the JSON is
+ * just another entry here and never reaches a prototype.
+ */
+export function fields(object: JsonObject): readonly (readonly [string, unknown])[] {
+  return Object.entries(object);
+}
+
+/** A string field or `undefined`; a present non-string reports `manifest-field-type`. */
+export function optionalString(object: JsonObject, field: string, path: string, findings: Findings): string | undefined {
+  const value = object[field];
+  if (value === undefined) return undefined;
+  if (typeof value !== "string") {
+    findings.error("manifest-field-type", { path, subject: field, detail: "a string" });
+    return undefined;
+  }
+  return value;
+}
+
+/** A string-array field or `undefined`; a present non-array-of-strings reports `manifest-field-type`. */
+export function optionalStringArray(
+  object: JsonObject,
+  field: string,
+  path: string,
+  findings: Findings,
+): readonly string[] | undefined {
+  const value = object[field];
+  if (value === undefined) return undefined;
+  if (!isStringArray(value)) {
+    findings.error("manifest-field-type", { path, subject: field, detail: "an array of strings" });
+    return undefined;
+  }
+  return value;
+}
+
+/**
+ * A field that may be one string or an array of strings (the vendor
+ * dialects' path fields), normalised to an array; `undefined` when absent.
+ */
+export function stringOrStringArray(
+  object: JsonObject,
+  field: string,
+  path: string,
+  findings: Findings,
+): readonly string[] | undefined {
+  const value = object[field];
+  if (value === undefined) return undefined;
+  if (typeof value === "string") return [value];
+  if (isStringArray(value)) return value;
+  findings.error("manifest-field-type", { path, subject: field, detail: "a string or an array of strings" });
+  return undefined;
+}

package/src/files.ts

@@ -0,0 +1,213 @@
+/**
+ * The reader the library is pure over, and the path discipline every path in
+ * a package obeys.
+ *
+ * `PluginFiles` is a sorted list of SIZED entries plus `read`. The size is
+ * declared up front so the library can refuse an over-cap document before a
+ * byte is read: an archive reader may hold a deflated entry whose declared
+ * size is the only defence against inflating a bomb, and a cap checked after
+ * `read` would be no defence at all. The reader's contract is that `read`
+ * never returns more than `size` bytes (a directory reader uses the file's
+ * stat size; an archive reader passes the central directory's declared size
+ * as its inflate limit). The library checks both sides anyway: the declared
+ * size before reading, the returned length after, refusing either as
+ * `document-too-large`. Nothing here touches the filesystem or any `node:*`
+ * module; the CLI's directory walker and the server's archive reader each
+ * implement this interface at their edge.
+ *
+ * Containment is lexical here and physical in each reader. A listed path
+ * that is absolute, contains `..` or a backslash, or has an empty segment is
+ * refused by the library; a reader never follows a symlink, and an archive
+ * has none. A path DECLARED in a manifest must begin with `./` (or be `.`),
+ * the open format's rule for every plugin-relative path.
+ */
+
+import type { PluginErrorKind } from "./outcome.js";
+
+export interface PluginFileEntry {
+  /** Plugin-relative POSIX path, no leading `./`, files only. */
+  readonly path: string;
+  /** The entry's declared size in bytes; `read` returns at most this many. */
+  readonly size: number;
+}
+
+export interface PluginFiles {
+  /** Sorted by path (code-point order), files only, every path contained. */
+  readonly entries: readonly PluginFileEntry[];
+  /** The bytes of one listed path. */
+  read(path: string): Uint8Array;
+}
+
+/**
+ * Per-document byte caps, checked from declared sizes. A plugin's documents
+ * are small by nature; the caps exist so no reader can be made to inflate
+ * a large entry through the library, not to bound legitimate content.
+ */
+export const PLUGIN_DOCUMENT_LIMITS = {
+  /** A manifest (`plugin.json` in any dialect). Real manifests are a few KB. */
+  manifest: 256 * 1024,
+  /** An MCP configuration file. */
+  mcpConfig: 256 * 1024,
+  /**
+   * A `SKILL.md`. The server's skill push gate inflates a `SKILL.md` alone
+   * under the same 1 MB cap, so a skill this library accepts is one the push
+   * gate accepts.
+   */
+  skillMd: 1024 * 1024,
+  /** A sub-agent file (`agents/*.md`): a prompt, so the `SKILL.md` cap. */
+  subAgent: 1024 * 1024,
+  /** A document under `ai.stigmer/`: a resource YAML. */
+  overlay: 1024 * 1024,
+} as const;
+
+export type PluginDocumentClass = keyof typeof PLUGIN_DOCUMENT_LIMITS;
+
+const encoder = new TextEncoder();
+// `fatal: false` keeps the decoder from throwing on a malformed sequence: a
+// document with bad UTF-8 reaches the JSON or YAML parser, which refuses it
+// with its own sentence, rather than crashing the read.
+const decoder = new TextDecoder("utf-8", { fatal: false });
+
+/** An in-memory `PluginFiles` over path -> content; the testing builders' product. */
+export function inMemoryPluginFiles(files: ReadonlyMap<string, Uint8Array | string>): PluginFiles {
+  const bytes = new Map<string, Uint8Array>();
+  for (const [path, content] of files) {
+    bytes.set(path, typeof content === "string" ? encoder.encode(content) : content);
+  }
+  const entries = [...bytes.entries()]
+    .map(([path, content]) => ({ path, size: content.length }))
+    .sort((a, b) => comparePaths(a.path, b.path));
+  return {
+    entries,
+    read(path) {
+      const content = bytes.get(path);
+      if (content === undefined) {
+        throw new Error(`plugin file '${path}' is not listed`);
+      }
+      return content;
+    },
+  };
+}
+
+/** Code-point order, the order `entries` is sorted in. */
+export function comparePaths(a: string, b: string): number {
+  return a < b ? -1 : a > b ? 1 : 0;
+}
+
+/** UTF-8 text with a leading byte-order mark removed (a manifest saved with a BOM was a known load failure elsewhere). */
+export function decodeUtf8(bytes: Uint8Array): string {
+  const text = decoder.decode(bytes);
+  return text.charCodeAt(0) === 0xfeff ? text.slice(1) : text;
+}
+
+/**
+ * Lexical containment of a LISTED path: relative, forward slashes only, no
+ * `.` or `..` segments, no empty segments. Readers produce such paths; the
+ * library refuses a reader that did not.
+ */
+export function isContainedPath(path: string): boolean {
+  if (path === "" || path.startsWith("/") || path.includes("\\")) return false;
+  return path.split("/").every((segment) => segment !== "" && segment !== "." && segment !== "..");
+}
+
+export type DeclaredPathOutcome =
+  | { readonly ok: true; readonly path: string }
+  | { readonly ok: false; readonly kind: Extract<PluginErrorKind, "path-not-relative" | "path-escapes-root" | "path-glob-unsupported"> };
+
+const GLOB_CHARACTERS = /[*?[\]{}]/;
+
+/**
+ * Normalise a path DECLARED in a manifest (`"./skills/"`, `"."`,
+ * `"./agents/reviewer.md"`) to a plugin-relative path with no leading `./`
+ * and no trailing slash; the plugin root itself is the empty string. The
+ * open format requires the `./` prefix; the vendor dialects document the
+ * same rule; a glob is refused because no plugin in the wild uses one and
+ * expanding globs is a second path language the library would then have
+ * to own.
+ */
+export function resolveDeclaredPath(value: string): DeclaredPathOutcome {
+  if (GLOB_CHARACTERS.test(value)) return { ok: false, kind: "path-glob-unsupported" };
+  if (value === "." || value === "./") return { ok: true, path: "" };
+  if (!value.startsWith("./")) return { ok: false, kind: "path-not-relative" };
+  const trimmed = value.slice(2).replace(/\/+$/, "");
+  if (trimmed === "") return { ok: true, path: "" };
+  if (!isContainedPath(trimmed)) return { ok: false, kind: "path-escapes-root" };
+  return { ok: true, path: trimmed };
+}
+
+/** `dir + "/" + name`, or `name` at the plugin root. */
+export function joinPath(dir: string, name: string): string {
+  return dir === "" ? name : `${dir}/${name}`;
+}
+
+/** The last segment of a plugin-relative path. */
+export function basename(path: string): string {
+  const slash = path.lastIndexOf("/");
+  return slash === -1 ? path : path.slice(slash + 1);
+}
+
+/** The path without its last segment; the empty string at the root. */
+export function dirname(path: string): string {
+  const slash = path.lastIndexOf("/");
+  return slash === -1 ? "" : path.slice(0, slash);
+}
+
+/**
+ * Indexed access over a `PluginFiles`: membership, the files under a
+ * directory, a directory's immediate children. Built once per read; every
+ * lookup is a map or a prefix walk over the sorted entries.
+ */
+export class PluginFileIndex {
+  private readonly byPath: ReadonlyMap<string, PluginFileEntry>;
+
+  constructor(readonly files: PluginFiles) {
+    this.byPath = new Map(files.entries.map((entry) => [entry.path, entry]));
+  }
+
+  has(path: string): boolean {
+    return this.byPath.has(path);
+  }
+
+  entry(path: string): PluginFileEntry | undefined {
+    return this.byPath.get(path);
+  }
+
+  /** Every file under `dir` (recursively), in entry order; every file at the root when `dir` is empty. */
+  filesUnder(dir: string): readonly string[] {
+    if (dir === "") return this.files.entries.map((entry) => entry.path);
+    const prefix = `${dir}/`;
+    return this.files.entries.filter((entry) => entry.path.startsWith(prefix)).map((entry) => entry.path);
+  }
+
+  /** True when at least one file lives under `dir`. */
+  isDirectory(dir: string): boolean {
+    if (dir === "") return this.files.entries.length > 0;
+    const prefix = `${dir}/`;
+    return this.files.entries.some((entry) => entry.path.startsWith(prefix));
+  }
+
+  /** The immediate child directory names under `dir`, sorted, deduplicated. */
+  childDirectories(dir: string): readonly string[] {
+    const prefix = dir === "" ? "" : `${dir}/`;
+    const names = new Set<string>();
+    for (const entry of this.files.entries) {
+      if (!entry.path.startsWith(prefix)) continue;
+      const rest = entry.path.slice(prefix.length);
+      const slash = rest.indexOf("/");
+      if (slash !== -1) names.add(rest.slice(0, slash));
+    }
+    return [...names].sort(comparePaths);
+  }
+
+  /** The immediate child FILE names under `dir`, sorted. */
+  childFiles(dir: string): readonly string[] {
+    const prefix = dir === "" ? "" : `${dir}/`;
+    const names: string[] = [];
+    for (const entry of this.files.entries) {
+      if (!entry.path.startsWith(prefix)) continue;
+      const rest = entry.path.slice(prefix.length);
+      if (!rest.includes("/")) names.push(rest);
+    }
+    return names.sort(comparePaths);
+  }
+}