@tapcue/extension-sdk 0.1.2 → 0.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tapcue/extension-sdk",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "description": "The Tapcue extension API: types, helpers, and the manifest validator that is the executable spec",
   "license": "MIT",
   "type": "module",

package/src/generic-keywords.ts

@@ -0,0 +1,69 @@
+/**
+ * The words a keyword may not be (spec 028 §1.4).
+ *
+ * A `keywords` entry buys its command a whole-word match in root search. That is the right trade
+ * for `eyedropper` and a disaster for `open`: one extension claiming the ten commonest verbs in
+ * five languages would sit in the candidate pool of nearly every query anybody types, and the only
+ * thing standing between it and the top of the list would be the ranker's opinion of a tie.
+ *
+ * So the blacklist is not a style guide, it is the thing that keeps the keyword field worth
+ * having. It is deliberately short and deliberately multilingual — an author writing a Chinese
+ * extension should hit exactly the same wall as one writing an English one, and a blacklist that
+ * only knew English would read as "generic words are fine as long as they are not in English".
+ *
+ * **What it is not**: a stopword list for the ranker. The ranker sees the user's query and the
+ * candidate's real title; this is only about what an author may *add* to that. A command called
+ * "Open in Browser" keeps that title, and keeps matching `open`, because its title says so.
+ *
+ * Matching is on the normalized keyword (lowercased, whitespace-trimmed), whole-string. `opener`
+ * and `open file` are not on the list: the entry has to *be* the generic word for the failure mode
+ * above to apply.
+ */
+
+/**
+ * One family per row, so a reviewer can see what is being refused and why.
+ *
+ * The families are the ones spec §1.4 names — the verbs and nouns every launcher command shares —
+ * in the languages Tapcue itself ships (`locales/`): English, Simplified Chinese, Japanese,
+ * German, French, Spanish.
+ */
+const GENERIC_KEYWORD_FAMILIES: Readonly<Record<string, readonly string[]>> = Object.freeze({
+  open: ["open", "打开", "开启", "開く", "ひらく", "öffnen", "offnen", "ouvrir", "abrir"],
+  file: ["file", "files", "文件", "檔案", "ファイル", "datei", "dateien", "fichier", "fichiers", "archivo", "archivos"],
+  search: [
+    "search", "find", "查找", "搜索", "搜寻", "検索", "さがす", "suche", "suchen", "finden",
+    "rechercher", "recherche", "chercher", "buscar", "búsqueda", "busqueda",
+  ],
+  new: ["new", "create", "新建", "新增", "创建", "新規", "あたらしい", "neu", "erstellen", "nouveau", "nouvelle", "créer", "creer", "nuevo", "nueva", "crear"],
+  copy: ["copy", "复制", "拷贝", "コピー", "kopieren", "kopie", "copier", "copiar"],
+  paste: ["paste", "粘贴", "貼り付け", "はりつけ", "einfügen", "einfugen", "coller", "pegar"],
+  app: ["app", "apps", "application", "applications", "应用", "程序", "アプリ", "アプリケーション", "anwendung", "programm", "aplicación", "aplicacion", "aplicaciones"],
+  run: ["run", "execute", "start", "运行", "执行", "启动", "実行", "じっこう", "ausführen", "ausfuhren", "starten", "exécuter", "executer", "lancer", "ejecutar", "iniciar"],
+  show: ["show", "view", "display", "显示", "查看", "表示", "ひょうじ", "zeigen", "anzeigen", "afficher", "voir", "mostrar", "ver"],
+  go: ["go", "goto", "前往", "跳转", "移動", "いく", "gehe", "gehen", "aller", "ir"],
+});
+
+/**
+ * Every blacklisted word, flattened. Exported so the Swift mirror can read one list rather than
+ * reconstructing the families, and so a test can assert the two agree.
+ */
+export const GENERIC_KEYWORDS: readonly string[] = Object.freeze(
+  [...new Set(Object.values(GENERIC_KEYWORD_FAMILIES).flat())].sort(),
+);
+
+const GENERIC_KEYWORD_SET: ReadonlySet<string> = new Set(GENERIC_KEYWORDS);
+
+/**
+ * Normalizes the way the check compares: case-folded, whitespace-trimmed, inner runs collapsed.
+ *
+ * Full-width Latin (`ｏｐｅｎ`) folds to ASCII through NFKC, because an author who types a keyword
+ * in a CJK input method should not get a different verdict than one who did not.
+ */
+export function normalizeKeyword(value: string): string {
+  return value.normalize("NFKC").trim().replace(/\s+/g, " ").toLowerCase();
+}
+
+/** Whether this keyword is one of the words §1.4 refuses. */
+export function isGenericKeyword(value: string): boolean {
+  return GENERIC_KEYWORD_SET.has(normalizeKeyword(value));
+}

package/src/index.ts

@@ -6,6 +6,7 @@ export * from "./capabilities.js";
 export * from "./types.js";
 export * from "./define-extension.js";
 export * from "./manifest.js";
+export * from "./generic-keywords.js";
 export * from "./permission-units.js";
 export * from "./view.js";
 export * from "./reactive.js";

package/src/manifest.ts

@@ -13,6 +13,7 @@ import {
   CONTRIBUTION_MATCH_FIELDS,
   isContributableScopeType,
 } from "./types.js";
+import { isGenericKeyword } from "./generic-keywords.js";
 import type { ContributableScopeType } from "./types.js";
 import {
   BOOLEAN_PERMISSION_GROUPS,
@@ -77,7 +78,21 @@ export interface ExtensionManifest {
    * Absent or empty for almost every extension. The forms above simply become undeclarable.
    */
   integratesWith?: string[];
-  commands: ManifestCommand[];
+  /**
+   * Required for every package type but `skill`, which has none: a skill is markdown, and its
+   * surface is `documents` (spec 028 §1.3).
+   */
+  commands?: ManifestCommand[];
+  /**
+   * **The markdown a `skill` package carries** (spec 028 §1.3) — and the only thing it carries.
+   *
+   * A skill has no commands and no code. What it offers is documents that get handed to an
+   * assistant surface as context, so the manifest names them the way it names commands: declared,
+   * readable without unpacking anything, and localizable. The *bodies* stay in the package —
+   * the catalog index publishes only these titles, because a title is what a row shows and a body
+   * is something you get after you install it.
+   */
+  documents?: ManifestDocument[];
   /**
    * **Rows this extension adds to scopes it does not own** (architecture §11.3) — the third
    * right over a scope, next to owning one and producing an item that enters one.
@@ -142,6 +157,18 @@ export interface ExtensionManifest {
   optionalPermissions?: ManifestPermissions;
 }
 
+/** One markdown document inside a `skill` package. */
+export interface ManifestDocument {
+  /**
+   * Package-relative path to a `.md` file that is actually in the archive. Relative, no traversal,
+   * and `.md` — the same three rules an `asset:` reference lives by, for the same reason: this
+   * string is resolved against a directory on the user's disk.
+   */
+  path: string;
+  /** What the document is called. Localizable (`@key`), and the only part the index publishes. */
+  title: string;
+}
+
 /**
  * One contribution: a native scope, which of its subjects, and the rows to add there.
  *
@@ -565,6 +592,16 @@ export interface ManifestPermissions {
 export interface ManifestProblem {
   path: string;
   message: string;
+  /**
+   * A stable rule id, for the problems the Swift mirror is measured against by name rather than
+   * by message (`@tapcue/extension-cli`'s `Problem.rule`, spec 028 §1.4).
+   *
+   * Absent on most problems, and that is not an oversight: the CLI reports an unnamed manifest
+   * problem as the generic `manifest.field`, which is all a corpus needs for a rule whose fixture
+   * nobody writes. A rule gets a name here when a fixture in `fixtures/malicious.ts` names it,
+   * because that name is the whole contract between the two implementations.
+   */
+  rule?: string;
 }
 
 /** Same grammar the shell resolves at runtime; see `scene.ts`. */
@@ -623,6 +660,9 @@ const COMMAND_ID_PATTERN = /^[a-z0-9]+(-[a-z0-9]+)*$/;
 const SEMVER_PATTERN = /^\d+\.\d+\.\d+(-[0-9A-Za-z.-]+)?$/;
 const HOST_PATTERN = /^[a-z0-9]([a-z0-9-]*[a-z0-9])?(\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)+$/;
 
+/** How every check below says no. `rule` is set only where a fixture names one; see `ManifestProblem`. */
+type Fail = (path: string, message: string, rule?: string) => void;
+
 /**
  * Validates a parsed manifest without executing any package code. Returns every
  * problem it finds rather than throwing on the first, so an author sees the full
@@ -630,7 +670,8 @@ const HOST_PATTERN = /^[a-z0-9]([a-z0-9-]*[a-z0-9])?(\.[a-z0-9]([a-z0-9-]*[a-z0-
  */
 export function validateManifest(value: unknown): ManifestProblem[] {
   const problems: ManifestProblem[] = [];
-  const fail = (path: string, message: string) => problems.push({ path, message });
+  const fail: Fail = (path, message, rule) =>
+    problems.push(rule === undefined ? { path, message } : { path, message, rule });
 
   if (typeof value !== "object" || value === null || Array.isArray(value)) {
     return [{ path: "", message: "manifest must be a JSON object" }];
@@ -676,9 +717,17 @@ export function validateManifest(value: unknown): ManifestProblem[] {
   }
 
   const commands = m.commands;
-  if (!Array.isArray(commands) || commands.length === 0) {
+  // A skill is markdown: it has no commands, and §1.3 says so in as many words. Demanding one
+  // would make the whole package type undeclarable, so the requirement is per type — and
+  // `documents` takes its place, checked in `validateDocuments`.
+  if (m.type === "skill") {
+    if (commands !== undefined) {
+      fail("commands", "a skill package has no commands — its surface is documents");
+    }
+  } else if (!Array.isArray(commands) || commands.length === 0) {
     fail("commands", "must declare at least one command");
-  } else {
+  }
+  if (Array.isArray(commands)) {
     const seen = new Set<string>();
     commands.forEach((raw, index) => {
       const path = `commands[${index}]`;
@@ -715,6 +764,7 @@ export function validateManifest(value: unknown): ManifestProblem[] {
         fail(`${path}.activation.runsAtRoot`, "only a remote command can run at root");
       }
       validateInput(c.input as CommandInput | undefined, `${path}.input`, fail);
+      validateKeywords(c.keywords, `${path}.keywords`, fail);
       const surface = c.surface as CommandSurface | undefined;
       if (surface !== undefined) {
         if (surface.layout !== undefined && surface.layout !== "list" && surface.layout !== "grid") {
@@ -759,6 +809,7 @@ export function validateManifest(value: unknown): ManifestProblem[] {
     });
   }
 
+  validateDocuments(m, fail);
   const integrates = validateIntegratesWith(m, fail);
   validateContributes(m, integrates, fail);
   validateProvides(m, fail);
@@ -901,9 +952,258 @@ export function effectiveGrants(
 
 type PermissionRecord = Record<string, any>;
 
+/** At most this many `keywords` on one command — see `validateKeywords`. */
+export const MAX_COMMAND_KEYWORDS = 10;
+/** The longest one keyword may be. */
+export const MAX_KEYWORD_LENGTH = 32;
+
+/**
+ * `keywords` — how many, how long, and which words are not keywords at all (spec 028 §1.4).
+ *
+ * A keyword is a claim on the user's typing: it puts this command in the candidate pool for a
+ * query that never mentions it by name. Three limits keep that claim proportionate.
+ *
+ * **Count** and **length** are about the index, which now holds every published extension rather
+ * than the handful someone installed: a hundred keywords per command is a way to be in every pool,
+ * and it costs the author nothing to write.
+ *
+ * **The blacklist** is about the pool itself (`generic-keywords.ts`). `open` belongs to every
+ * command there has ever been, so a command that claims it is not saying what it does — it is
+ * saying "consider me always", and the only thing left deciding is a tie-break.
+ */
+function validateKeywords(value: unknown, path: string, fail: Fail): void {
+  if (value === undefined) return;
+  if (!Array.isArray(value)) {
+    fail(path, "must be an array of keywords");
+    return;
+  }
+  if (value.length > MAX_COMMAND_KEYWORDS) {
+    fail(
+      path,
+      `at most ${MAX_COMMAND_KEYWORDS} keywords — past that a command is not describing itself, it is claiming the query field`,
+      "manifest.keywords-count",
+    );
+  }
+  value.forEach((keyword, index) => {
+    const where = `${path}[${index}]`;
+    if (typeof keyword !== "string" || keyword.trim() === "") {
+      fail(where, "must be a non-empty string");
+      return;
+    }
+    if (keyword.length > MAX_KEYWORD_LENGTH) {
+      fail(where, `at most ${MAX_KEYWORD_LENGTH} characters`, "manifest.keywords-length");
+    }
+    if (isGenericKeyword(keyword)) {
+      fail(
+        where,
+        `"${keyword}" is a word nearly every command shares — a keyword has to narrow the pool, not join it`,
+        "manifest.keywords-generic",
+      );
+    }
+  });
+}
+
 /** The longest `pattern` a command may declare — see `CommandInput.pattern`. */
 const MAX_INPUT_PATTERN_LENGTH = 200;
 
+/**
+ * Constructs a `pattern` may not use, because it runs in the launcher's process (spec 028 §1.4).
+ *
+ * The three refused families are the ones that turn a regular expression into a computation:
+ * **nested quantifiers** (`(a+)+`) are the classic exponential blow-up, **backreferences** make the
+ * language non-regular and the engine a backtracker, and **lookaround** re-runs a subpattern at
+ * every position. None of the three is needed to describe an issue key or a tracking number, which
+ * is what this field is for.
+ *
+ * **This check is deliberately syntactic, and it is not a ReDoS oracle.** It reads the pattern as
+ * text — tracking escapes, character classes, and group nesting — and refuses the shapes above. It
+ * does *not* find every pattern that can backtrack badly: `(a|a)+` and `(a|ab)*` are quadratic or
+ * worse and pass this, as does any blow-up that needs alternation to see. What closes that gap is
+ * elsewhere and is not a parser: the host caps the pattern's length (200), caps the length of the
+ * text it is run against, and runs it off the keystroke path. This function removes the shapes an
+ * attacker would reach for first; the caps are what make the rest uninteresting.
+ */
+export function unsafePatternProblem(pattern: string): string | undefined {
+  /** Whether each still-open group has a quantifier anywhere inside it. */
+  const open: { quantified: boolean }[] = [];
+  const markQuantified = () => {
+    for (const group of open) group.quantified = true;
+  };
+
+  let inClass = false;
+  for (let i = 0; i < pattern.length; i += 1) {
+    const char = pattern[i]!;
+    if (char === "\\") {
+      const next = pattern[i + 1];
+      if (!inClass && next !== undefined && /[1-9]/.test(next)) {
+        return "must not use a backreference — it makes the match a backtracking search";
+      }
+      if (!inClass && next === "k" && pattern[i + 2] === "<") {
+        return "must not use a backreference — it makes the match a backtracking search";
+      }
+      i += 1; // the escaped character is never punctuation
+      continue;
+    }
+    if (inClass) {
+      if (char === "]") inClass = false;
+      continue;
+    }
+    if (char === "[") {
+      inClass = true;
+      continue;
+    }
+    if (char === "(") {
+      if (pattern.startsWith("(?=", i) || pattern.startsWith("(?!", i)) {
+        return "must not use lookahead — it re-runs a subpattern at every position";
+      }
+      if (pattern.startsWith("(?<=", i) || pattern.startsWith("(?<!", i)) {
+        return "must not use lookbehind — it re-runs a subpattern at every position";
+      }
+      open.push({ quantified: false });
+      continue;
+    }
+    if (char === ")") {
+      const group = open.pop();
+      const quantifier = quantifierAt(pattern, i + 1);
+      if (quantifier === undefined) continue;
+      if (group?.quantified && quantifier.repeats) {
+        return "must not nest quantifiers, e.g. (a+)+ — that is the shape that backtracks exponentially";
+      }
+      markQuantified();
+      i = quantifier.end - 1;
+      continue;
+    }
+    const quantifier = quantifierAt(pattern, i);
+    if (quantifier !== undefined) {
+      markQuantified();
+      i = quantifier.end - 1;
+    }
+  }
+  return undefined;
+}
+
+/**
+ * The quantifier starting at `index`, if there is one.
+ *
+ * `repeats` is what separates the dangerous outer quantifier from the harmless one: `(a+)?` may
+ * match its group at most once, so nothing inside it can be re-tried against a different split.
+ * `*`, `+`, `{n,}` and `{n,m}` with m ≥ 2 all can.
+ */
+function quantifierAt(
+  pattern: string,
+  index: number,
+): { end: number; repeats: boolean } | undefined {
+  const char = pattern[index];
+  if (char === "*" || char === "+") return { end: index + 1, repeats: true };
+  if (char === "?") return { end: index + 1, repeats: false };
+  if (char !== "{") return undefined;
+  const close = pattern.indexOf("}", index);
+  if (close < 0) return undefined; // a literal brace, which JavaScript tolerates
+  const body = pattern.slice(index + 1, close);
+  const match = /^(\d+)(,(\d*))?$/.exec(body);
+  if (!match) return undefined;
+  const min = Number(match[1]);
+  const max = match[2] === undefined ? min : match[3] === "" ? Infinity : Number(match[3]);
+  return { end: close + 1, repeats: max >= 2 };
+}
+
+/** The longest a `contributes[].when.host` value may be — see `hostPatternProblem`. */
+export const MAX_CONTRIBUTION_HOST_LENGTH = 64;
+
+/**
+ * A `when.host` value: a host name, lowercase, optionally prefixed `*.` for its subdomains
+ * (spec 028 §1.4).
+ *
+ * Every rule here is about the same thing — a host predicate is a *disclosure*, and the install
+ * sheet reads it out. `*.github.com` says "the rows appear on GitHub", which somebody can decide
+ * about. `*.com` says nothing at all while matching most of the web, so a wildcard needs a label
+ * of its own below the suffix. Uppercase is refused rather than folded so that the string in the
+ * manifest and the string on the sheet are the same string.
+ */
+export function hostPatternProblem(value: string): string | undefined {
+  if (value.length > MAX_CONTRIBUTION_HOST_LENGTH) {
+    return `at most ${MAX_CONTRIBUTION_HOST_LENGTH} characters`;
+  }
+  const wildcard = value.startsWith("*.");
+  const host = wildcard ? value.slice(2) : value;
+  if (!/^[a-z0-9.-]+$/.test(host)) {
+    return 'must be a lowercase host name — letters, digits, dots and hyphens, with an optional leading "*."';
+  }
+  const labels = host.split(".");
+  for (const label of labels) {
+    if (label === "") return "has an empty label — no leading, trailing or doubled dots";
+    if (label.startsWith("-") || label.endsWith("-")) return `label "${label}" may not start or end with a hyphen`;
+  }
+  if (labels.length < 2) {
+    // The known limit: this refuses `*.com`, not `*.co.uk`. Telling those apart needs the public
+    // suffix list, which is a megabyte that expires — and the second door here is a human reading
+    // a pull request, who can see a wildcard on a registry suffix for what it is.
+    return wildcard
+      ? `"${value}" is every site under a top-level domain — name the site, e.g. *.github.com`
+      : "must be a full host name, e.g. github.com";
+  }
+  return undefined;
+}
+
+/**
+ * Whether a `when.host` value admits a subject's host.
+ *
+ * Whole-string and case-insensitive, like every other match field, with one addition: a leading
+ * `*.` matches any *subdomain* and not the domain itself. `*.github.com` matches
+ * `gist.github.com` and not `github.com` — a contribution that wants both writes both, because
+ * the two are different claims and guessing which one an author meant is how a predicate quietly
+ * widens.
+ */
+export function hostMatches(pattern: string, host: string): boolean {
+  const left = pattern.toLowerCase();
+  const right = host.toLowerCase();
+  if (!left.startsWith("*.")) return left === right;
+  const suffix = left.slice(1); // ".github.com"
+  return right.length > suffix.length && right.endsWith(suffix);
+}
+
+/**
+ * `documents` — the markdown a `skill` package carries, and nothing else may (spec 028 §1.3).
+ *
+ * The path rules are `asset:`'s: relative, no traversal, and here also `.md`, because these paths
+ * are joined onto a directory in the user's store and then read. The title is checked for being
+ * present rather than for being resolvable — a `@key` is resolved against the package's catalogs,
+ * which is a question only the archive can answer (`manifest-check.ts`).
+ */
+function validateDocuments(m: Record<string, unknown>, fail: Fail): void {
+  const documents = m.documents;
+  if (m.type !== "skill") {
+    if (documents !== undefined) {
+      fail("documents", 'only a "skill" package carries documents');
+    }
+    return;
+  }
+  if (!Array.isArray(documents) || documents.length === 0) {
+    fail("documents", "a skill package must declare at least one markdown document");
+    return;
+  }
+  const seen = new Set<string>();
+  documents.forEach((raw, index) => {
+    const path = `documents[${index}]`;
+    const document = raw as Record<string, unknown>;
+    const file = document?.path;
+    if (typeof file !== "string" || file.trim() === "") {
+      fail(`${path}.path`, "must name a markdown file inside the package");
+    } else if (file.startsWith("/") || file.includes("\\") || file.split("/").includes("..")) {
+      fail(`${path}.path`, "must be package-relative and must not traverse");
+    } else if (!file.toLowerCase().endsWith(".md")) {
+      fail(`${path}.path`, "must be a .md file — a skill is markdown");
+    } else if (seen.has(file)) {
+      fail(`${path}.path`, `duplicate document "${file}"`);
+    } else {
+      seen.add(file);
+    }
+    if (typeof document?.title !== "string" || document.title.trim() === "") {
+      fail(`${path}.title`, "must say what the document is, for the row and the review sheet");
+    }
+  });
+}
+
 /**
  * Validates a command's `input` block at install time, where a bad one costs nothing.
  *
@@ -916,7 +1216,7 @@ const MAX_INPUT_PATTERN_LENGTH = 200;
 function validateInput(
   input: CommandInput | undefined,
   path: string,
-  fail: (path: string, message: string) => void,
+  fail: Fail,
 ): void {
   if (input === undefined) return;
   if (typeof input !== "object" || input === null) {
@@ -941,6 +1241,8 @@ function validateInput(
     } else {
       try {
         new RegExp(input.pattern);
+        const unsafe = unsafePatternProblem(input.pattern);
+        if (unsafe) fail(`${path}.pattern`, unsafe, "manifest.pattern-unsafe");
       } catch {
         fail(`${path}.pattern`, "is not a valid regular expression");
       }
@@ -1083,7 +1385,10 @@ export function manifestCatalogKeys(manifest: ExtensionManifest): string[] {
   };
   take(manifest.name);
   take(manifest.description);
-  for (const command of manifest.commands) {
+  for (const document of manifest.documents ?? []) {
+    take(document.title);
+  }
+  for (const command of manifest.commands ?? []) {
     take(command.title);
     take(command.description);
     for (const argument of command.arguments ?? []) {
@@ -1175,7 +1480,7 @@ export function scopeTypePrefix(extensionId: string): string {
  */
 function validateProvides(
   m: Record<string, unknown>,
-  fail: (path: string, message: string) => void,
+  fail: Fail,
 ): void {
   const declaresWorkspaceRoots = (block: unknown): boolean =>
     (block as ManifestPermissions | undefined)?.workspace?.roots === true;
@@ -1224,7 +1529,7 @@ function validateProvides(
 function validateContributes(
   m: Record<string, unknown>,
   integrates: string[],
-  fail: (path: string, message: string) => void,
+  fail: Fail,
 ): void {
   const contributes = m.contributes;
   if (contributes === undefined) return;
@@ -1297,6 +1602,10 @@ function validateContributes(
             `"${value}" is not in integratesWith — declare the apps this extension works with there`,
           );
         }
+        if (field === "host") {
+          const problem = hostPatternProblem(value);
+          if (problem) fail(`${fieldPath}[${valueIndex}]`, problem, "manifest.host-invalid");
+        }
       });
     }
   });
@@ -1316,7 +1625,7 @@ const MAX_SUGGESTION_RULES_LENGTH = 8_000;
  */
 function validateSuggestionRules(
   value: unknown,
-  fail: (path: string, message: string) => void,
+  fail: Fail,
 ): void {
   if (value === undefined) return;
   let text: string;
@@ -1342,7 +1651,7 @@ function validateSuggestionRules(
 /** `integratesWith` — bundle identifiers, unique, and the anchor every other reach resolves against. */
 function validateIntegratesWith(
   m: Record<string, unknown>,
-  fail: (path: string, message: string) => void,
+  fail: Fail,
 ): string[] {
   const raw = m.integratesWith;
   if (raw === undefined) return [];
@@ -1382,7 +1691,7 @@ function validateRootPath(
   root: FileRoot,
   value: unknown,
   path: string,
-  fail: (path: string, message: string) => void,
+  fail: Fail,
 ): void {
   if (ROOT_PATH_SHAPES[root] === "dot-segment") {
     if (typeof value !== "string" || value.trim() === "") {
@@ -1416,7 +1725,7 @@ function validateRootPath(
 function validateReadOnlySql(
   value: unknown,
   path: string,
-  fail: (path: string, message: string) => void,
+  fail: Fail,
 ): void {
   if (typeof value !== "string" || value.trim() === "") {
     fail(path, "must be a SELECT statement");
@@ -1442,7 +1751,7 @@ function validateReach(
   permissions: ManifestPermissions | undefined,
   block: string,
   integrates: string[],
-  fail: (path: string, message: string) => void,
+  fail: Fail,
 ): void {
   if (!permissions) return;
 
@@ -1559,7 +1868,7 @@ function validateReach(
 }
 
 /** A subpath inside a host-chosen root: no wildcards, no climbing, no absolute form. */
-function validateSubpath(value: string, path: string, fail: (path: string, message: string) => void): void {
+function validateSubpath(value: string, path: string, fail: Fail): void {
   if (value.trim() === "") {
     fail(path, "must be a non-empty subpath");
   } else if (value.startsWith("/") || value.startsWith("~")) {

package/src/testing/test-host.ts

@@ -78,6 +78,7 @@ import {
   type ManifestPermissions,
   coerceSetting,
   effectiveGrants,
+  hostMatches,
   iconProblem,
   namespacedItemId,
   permissionUnits,
@@ -122,6 +123,7 @@ const NATIVE_SUBJECT_FIELDS: Readonly<Record<ContributableScopeType, readonly st
     application: ["bundleId", "name"],
     file: ["path", "name", "extension", "isDirectory"],
     "file.folder": ["path", "name", "extension", "isDirectory"],
+    url: ["url", "host"],
   });
 
 export interface HostLimits {
@@ -1368,7 +1370,7 @@ export function createTestHost(options: TestHostOptions): TestHost {
   }
 
   function commandOf(commandId: string): ManifestCommand {
-    const command = manifest.commands.find((c) => c.id === commandId);
+    const command = (manifest.commands ?? []).find((c) => c.id === commandId);
     if (!command) throw new Error(`command "${commandId}" is not declared in the manifest`);
     return command;
   }
@@ -1701,6 +1703,12 @@ export function createTestHost(options: TestHostOptions): TestHost {
       if (!matchable.includes(field)) return false;
       const actual = subject[field];
       if (typeof actual !== "string") return false;
+      // `host` is the one field with a wildcard form, and `hostMatches` is the only place it is
+      // read — the shell and this fake must agree that `*.github.com` is not `github.com`.
+      if (field === "host") {
+        if (!values.some((value) => hostMatches(value, actual))) return false;
+        continue;
+      }
       const lowered = actual.toLowerCase();
       if (!values.some((value) => value.toLowerCase() === lowered)) return false;
     }
@@ -1913,7 +1921,7 @@ export function createTestHost(options: TestHostOptions): TestHost {
       // The command whose query produced this item — not `commands[0]`. An action
       // inside the scope is still routed to (extension, command, item, action), and
       // an extension with two commands would otherwise be told the wrong one.
-      const commandId = itemOrigin.get(item.id) ?? manifest.commands[0].id;
+      const commandId = itemOrigin.get(item.id) ?? manifest.commands?.[0]?.id ?? "";
       // Entering a scope tears down whatever surface the previous one had up. The isolate does
       // not own the surface, the shell does, and leaving one scope ends it — so the bridge from
       // a stale surface is gone before the next scope's actions can reach for it.

package/src/types.ts

@@ -59,6 +59,7 @@ export interface NativeSubjects {
   application: ApplicationSubject;
   file: FileSubject;
   "file.folder": FileSubject;
+  url: UrlSubject;
 }
 
 /** An installed application, as the `application` scope names it. */
@@ -79,6 +80,23 @@ export interface FileSubject {
   isDirectory: boolean;
 }
 
+/**
+ * A web address, as the `url` scope names it — a link the user is standing on, or the page the
+ * frontmost browser is showing.
+ *
+ * Two fields and no page content. `host` is separate from `url` because it is the only thing a
+ * contribution may *match* on (`CONTRIBUTION_MATCH_FIELDS`), and deriving it from the address on
+ * both sides of the boundary would be two parsers disagreeing about punycode and ports. The title,
+ * the description and the rest of the page are not here: reading them is a fetch, and a subject is
+ * something the host already knows.
+ */
+export interface UrlSubject {
+  /** The full address, normalized: scheme and host lowercased, no fragment. */
+  url: string;
+  /** The lowercased host, no port and no userinfo. `""` for an address that has none. */
+  host: string;
+}
+
 /**
  * **The native scopes an extension may contribute rows *into*** (architecture §11.3).
  *
@@ -93,7 +111,7 @@ export interface FileSubject {
  * **list of rows** there is something to add to. `color` has a subject and no list — it is a
  * value Tapcue formats, not a place — so it is not here.
  */
-export const CONTRIBUTABLE_SCOPE_TYPES = ["application", "file", "file.folder"] as const;
+export const CONTRIBUTABLE_SCOPE_TYPES = ["application", "file", "file.folder", "url"] as const;
 export type ContributableScopeType = (typeof CONTRIBUTABLE_SCOPE_TYPES)[number];
 
 /**
@@ -103,6 +121,11 @@ export type ContributableScopeType = (typeof CONTRIBUTABLE_SCOPE_TYPES)[number];
  * is a glob problem, and a predicate that could say "anything under /Users" would hand an
  * extension every file you ever open a scope on. What a contribution may name is a *kind* of
  * subject (this app, this file extension), never a location.
+ *
+ * `url` names `host` for the same reason and nothing else: the address itself is a location, and a
+ * predicate over it would be the glob problem again. The one concession is the `*.` prefix
+ * (`hostMatches`), because "this site" and "this site's subdomains" are genuinely different asks
+ * and neither is expressible as the other.
  */
 export const CONTRIBUTION_MATCH_FIELDS: Readonly<
   Record<ContributableScopeType, readonly string[]>
@@ -110,6 +133,7 @@ export const CONTRIBUTION_MATCH_FIELDS: Readonly<
   application: ["bundleId", "name"],
   file: ["extension", "name"],
   "file.folder": ["name"],
+  url: ["host"],
 });
 
 export function isContributableScopeType(type: string): type is ContributableScopeType {