@hasna/skills 0.1.60 → 0.1.62

package/dist/lib/registry-merge.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Merging the several registries a `skills` install can see into one list.
+ *
+ * Before this, `--remote` REPLACED the local registry: `skills list --remote` showed the
+ * instance's skills and nothing else, so the bundled corpus and anything the operator had
+ * written locally vanished from the listing the moment they pointed the CLI at their own
+ * server. Since the whole point of publishing is that a machine sees bundled, local, and
+ * published skills together, the lists are merged and collisions are resolved by an
+ * explicit rule rather than by which list happened to be concatenated last.
+ *
+ * PRECEDENCE, most local wins:
+ *
+ *     custom  >  extension  >  private  >  private-hosted  >  remote  >  upstream  >  official
+ *
+ * The rule is "whichever copy this machine would actually use, wins the listing". A skill
+ * present in ~/.hasna/skills/installed is the one `skills run` executes, so a listing that
+ * described the server's copy instead would be describing something that is not going to
+ * run. `remote` beats `official` for the mirror-image reason: an organization that
+ * published a skill under a bundled name did so to override the bundled one on their
+ * instance, and silently preferring the bundled copy would make publishing an override
+ * impossible.
+ *
+ * Ties inside one source are resolved last-wins, so a caller can order its own inputs.
+ */
+import type { SkillMeta, SkillSource } from "./registry-types.js";
+/** Higher wins. Every SkillSource has an entry; adding a source without one is a type error. */
+export declare const SKILL_SOURCE_PRECEDENCE: Record<SkillSource, number>;
+/**
+ * An entry with no `source` at all is treated as `official`.
+ *
+ * Deliberately the *lowest* rank rather than the highest. Untagged entries come from
+ * older payloads and hand-built fixtures, and an unknown provenance losing a collision
+ * fails towards the bundled corpus - the copy that is known to exist - instead of letting
+ * an unlabelled remote entry silently displace a local skill.
+ */
+export declare function skillSourceRank(skill: Pick<SkillMeta, "source">): number;
+export interface MergedSkillCollision {
+    name: string;
+    /** The source that won. */
+    winner: SkillSource;
+    /** Every source that lost, in the order they were supplied. */
+    shadowed: SkillSource[];
+}
+export interface MergeSkillRegistriesResult {
+    skills: SkillMeta[];
+    collisions: MergedSkillCollision[];
+}
+/**
+ * Merge registries by name, keeping the highest-precedence entry for each.
+ *
+ * Groups are supplied in whatever order the caller likes: the result does not depend on
+ * it except for ties within a single source, which resolve last-wins. Output is sorted by
+ * name so two callers merging the same inputs print the same list.
+ */
+export declare function mergeSkillRegistries(...groups: Array<SkillMeta[] | undefined | null>): MergeSkillRegistriesResult;
+/** The merged list on its own, for callers that do not care which entries collided. */
+export declare function mergeSkillRegistryLists(...groups: Array<SkillMeta[] | undefined | null>): SkillMeta[];

package/dist/lib/registry-types.d.ts

@@ -18,22 +18,9 @@ export interface SkillMeta {
      * agents. Missing kind defaults to "executable" during migration.
      */
     kind?: SkillKind;
-    pricing?: SkillPricingMetadata;
     availability?: SkillAvailabilityMetadata;
     source?: SkillSource;
 }
-export interface SkillPricingMetadata {
-    tier?: "free" | "premium" | string;
-    billingUnit?: string;
-    costCents?: number;
-    formattedCost: string;
-    formattedUnitCost?: string;
-    unitCount?: number;
-    estimated?: boolean;
-    quoteDependsOnInput?: boolean;
-    quoteRequired?: boolean;
-    description?: string;
-}
 export interface SkillAvailabilityMetadata {
     status: "available" | "unavailable";
     code?: string;
@@ -42,5 +29,5 @@ export interface SkillAvailabilityMetadata {
 }
 export declare const CATEGORIES: readonly ["Development Tools", "Business & Marketing", "Productivity & Organization", "Project Management", "Content Generation", "Finance & Compliance", "Data & Analysis", "Media Processing", "Design & Branding", "Web & Browser", "Research & Writing", "Science & Academic", "Education & Learning", "Communication", "Health & Wellness", "Travel & Lifestyle", "Event Management"];
 export type Category = (typeof CATEGORIES)[number];
-export declare const BASIC_SKILL_NAMES: readonly ["image", "video", "audio", "music", "transcript", "audio-extract", "read-image", "read-pdf", "pdf-read", "pdf-to-markdown", "doc-read", "pdf-generate", "doc-generate", "read-csv", "read-excel", "excel", "convert"];
+export declare const BASIC_SKILL_NAMES: readonly ["blog-article", "ad-creative-pack", "email-sequence", "seo-content-pack", "social-content-calendar", "pitch-deck", "proposal-pack", "market-research-report"];
 export type SkillRegistryProfile = "basic" | "all";

package/dist/lib/registry.d.ts

@@ -6,11 +6,14 @@ import { BASIC_SKILL_NAMES, CATEGORIES, type Category, type SkillMeta, type Skil
 export { BASIC_SKILL_NAMES, CATEGORIES, SKILLS };
 export type { Category, SkillMeta, SkillRegistryProfile };
 export declare function isBasicSkillName(name: string): boolean;
+export declare function findExtensionSkillPath(name: string): string | null;
 /**
- * Load the full registry: official skills merged with global custom skills
- * from ~/.hasna/skills/<name>/ and the legacy ~/.hasna/skills/custom/<name>/ path.
+ * Load the full registry: official skills merged with a configured private
+ * extension checkout and global custom skills from ~/.hasna/skills/installed/<name>/
+ * (plus the legacy ~/.hasna/skills/custom/<name>/ migration safety net).
  *
- * Custom skills with the same name as official skills take precedence.
+ * Custom skills take precedence over extensions, which take precedence over
+ * official skills. Extension skills are read in place and never copied into installed/.
  * Results are cached for 5 seconds.
  */
 export declare function loadRegistry(cwd?: string): SkillMeta[];

package/dist/lib/remote-client.d.ts

@@ -7,12 +7,26 @@ export declare class RemoteSkillsClient {
     listSkills(): Promise<any[]>;
     getSkillMd(slug: string): Promise<string | null>;
     getSkill(slug: string): Promise<any | null>;
-    quoteSkill(slug: string, input?: Record<string, unknown>, args?: string[]): Promise<any>;
     submitRun(slug: string, input?: Record<string, unknown>, args?: string[]): Promise<RemoteSkillRunContract>;
     getRun(runId: string): Promise<RemoteSkillRunContract | null>;
     getRunLogs(runId: string): Promise<any[]>;
     listRuns(limit?: number): Promise<any[]>;
     getRunArtifacts(runId: string): Promise<any[]>;
     downloadRunArtifact(runId: string, artifactId: string): Promise<Response>;
+    /**
+     * Publish a skill to the configured instance.
+     *
+     * Sent as multipart rather than as JSON with a base64 field. A base64 body would inflate
+     * the bundle by a third and would have to pass through the server's JSON reader, whose
+     * 1 MB cap exists to keep JSON bodies sane; multipart keeps the tarball on its own path
+     * with its own, larger limit.
+     *
+     * Note the deliberate absence of `request()`: that helper pins
+     * `Content-Type: application/json`, and a multipart body whose Content-Type does not
+     * carry the generated boundary is unparseable at the other end.
+     */
+    publishSkill(manifest: Record<string, unknown>, bundle?: Uint8Array): Promise<Response>;
+    deleteSkill(slug: string): Promise<Response>;
+    downloadSkillBundle(slug: string): Promise<Response>;
 }
 export declare function createRemoteSkillsClient(): RemoteSkillsClient | null;

package/dist/lib/remote-registry.d.ts

@@ -2,7 +2,7 @@
  * Remote registry client.
  *
  * Local registry behavior remains the default. These helpers are opt-in and
- * read from SKILLS_API_URL or config.apiUrl so self-hosted services can expose
+ * read from SKILLS_API_URL or config.apiUrl so services can expose
  * a compatible registry API without hard-coding deployment details upstream.
  */
 import { type SkillsConfig } from "./config.js";

package/dist/lib/remote-run-contract.d.ts

@@ -1,4 +1,3 @@
-import type { PublicSkillPricing } from "./pricing";
 export declare const REMOTE_SKILL_RUN_CONTRACT_VERSION: 1;
 export interface RemoteSkillRunContract {
     contractVersion: typeof REMOTE_SKILL_RUN_CONTRACT_VERSION;
@@ -8,9 +7,6 @@ export interface RemoteSkillRunContract {
     status?: string;
     exitCode?: number;
     correlationId?: string;
-    costCents?: number;
-    cost?: string;
-    pricing?: PublicSkillPricing;
     createdAt?: string;
     startedAt?: string;
     completedAt?: string;
@@ -19,11 +15,8 @@ export interface RemoteSkillRunContract {
     outputPreview?: unknown;
     errorCode?: string;
     errorMessage?: string;
-    creditsUsed?: number;
     error?: string;
     code?: string;
     details?: unknown;
-    balance?: string;
-    balanceCents?: number;
 }
 export declare function normalizeRemoteSkillRunContract(payload: unknown, fallbackSkill?: string): RemoteSkillRunContract;

package/dist/lib/retired-settings.d.ts

@@ -0,0 +1,100 @@
+/**
+ * Settings that used to select a deployment mode, and the refusal they now produce.
+ *
+ * Skills once declared a three-way deployment axis as a label: running on this
+ * machine, running against a server somebody operates, running against a
+ * vendor-operated one. That axis is gone. Two facts replaced it, and both are read
+ * from the configuration itself rather than from a declaration about it:
+ *
+ *   - a server keeps its data in SQLite or in PostgreSQL, decided by the database
+ *     string it is given (see server/database-url.ts);
+ *   - a client either has an API origin configured or it does not (see
+ *     lib/api-url.ts).
+ *
+ * Deleting the label was not sufficient on its own, and this module is the half
+ * that was left. A retired setting which is merely *unread* is the worse of the
+ * two failures: an operator who exports a storage-mode variable gets a process on
+ * the default SQLite database with no indication that the thing they configured
+ * was discarded, and silence there is indistinguishable from success. That is how
+ * a deployment ends up writing to a file nobody is backing up. So a retired
+ * setting is refused, and the refusal names what replaced it.
+ *
+ * MATCHED BY SHAPE, NOT BY A LIST OF NAMES. The retired axis was spelled several
+ * ways at once across the estate - two prefixes, and both `storage` and
+ * `deployment` as the middle word - so enumerating the spellings we happen to
+ * remember would let the next one through silently, which is the failure being
+ * fixed. A suffix match catches every prefix variant, including ones this repo
+ * never used itself.
+ *
+ * Two discriminations keep that shape from doing damage:
+ *
+ *   - The suffixes are narrow. `*_MODE` alone would swallow live, unrelated
+ *     settings - SKILLS_TEST_MODE gates self-update in the suite, and SQLite's
+ *     journal mode is a mode - so only the three that named the removed
+ *     deployment axis appear below. Anything else called mode is a different axis
+ *     and none of this module's business.
+ *   - The match is scoped to this application's variables. Sibling Hasna apps are
+ *     mid-removal on the same axis and their variables are present in the same
+ *     shell; refusing to start because a *different* app still exports one would
+ *     turn this fix into an outage. The caller supplies the token that identifies
+ *     its own namespace.
+ */
+/**
+ * Configuration-file keys that named the removed deployment axis, and the key
+ * that replaces each one.
+ *
+ * A key is retired whatever its value: the fault is asking for a deployment label
+ * at all, not asking for a particular one. Listing values instead would accept
+ * `mode: "onprem"` while rejecting `mode: "cloud"`, which teaches the reader that
+ * the concept survived and only some spellings of it are wrong.
+ */
+export declare const RETIRED_CONFIG_KEYS: Readonly<Record<string, string>>;
+/** Thrown when configuration names a setting the deployment-mode removal deleted. */
+export declare class RetiredSettingError extends Error {
+    readonly code = "RETIRED_SETTING";
+    /** The retired setting, spelled as the operator wrote it. */
+    readonly setting: string;
+    constructor(setting: string, message: string);
+}
+/**
+ * Whether an environment variable names the removed deployment axis for `app`.
+ *
+ * @param app token identifying the calling application's variable namespace, so
+ * a sibling app's not-yet-removed variable is left alone.
+ */
+export declare function isRetiredModeEnvVar(name: string, app: string): boolean;
+/**
+ * Every retired deployment-axis variable for `app` that is actually set.
+ *
+ * An empty string counts as unset. `export FOO="$BAR"` with BAR unset is what
+ * collapses to that, and refusing it would fail a deployment over a value nobody
+ * chose.
+ */
+export declare function findRetiredModeEnvVars(env: Record<string, string | undefined>, app: string): {
+    name: string;
+    value: string;
+}[];
+/**
+ * Refuse if the environment names the removed deployment axis.
+ *
+ * `replacement` is supplied by the caller rather than hardcoded here so the name
+ * stays owned by the module that reads it, and so this module needs no imports
+ * and can be called from anywhere without an import cycle.
+ *
+ * @throws RetiredSettingError naming the retired variables, their replacement,
+ * and the fix.
+ */
+export declare function assertNoRetiredModeEnvVars(env: Record<string, string | undefined>, options: {
+    app: string;
+    replacement: string;
+}): void;
+/**
+ * Refuse if a configuration object carries a retired deployment-axis key.
+ *
+ * @param source where the object came from - a file path, or the command that
+ * supplied it - so the message points at the thing the operator has to change
+ * rather than at "your configuration".
+ *
+ * @throws RetiredSettingError naming the retired key, its replacement, and the fix.
+ */
+export declare function assertNoRetiredConfigKeys(config: Record<string, unknown>, source: string): void;

package/dist/lib/run-state.d.ts

@@ -57,4 +57,18 @@ export declare function writeRunLogs(context: SkillRunContext, stdout?: string,
 export declare function appendRunEvent(context: SkillRunContext, event: string, data?: Record<string, unknown>): void;
 export declare function listSkillRuns(targetDir?: string, limit?: number): SkillRunRecord[];
 export declare function findSkillRun(runId: string, targetDir?: string): SkillRunRecord | null;
+/**
+ * Environment handed to a skill child process so it writes into the project's
+ * `.skills` tree instead of its own installation directory.
+ *
+ * Skills are spawned with `cwd` set to the installed skill package, so every
+ * cwd-relative fallback (`process.env.SKILLS_EXPORTS_DIR || "."`,
+ * `process.env.SKILLS_OUTPUT_DIR || join(process.cwd(), ".skills")`) resolves
+ * inside node_modules unless these are set. The catalog reads three names:
+ * SKILLS_OUTPUT_DIR (the `.skills` root, from which skills derive
+ * `exports/<skill>` and `logs/<skill>`), plus SKILLS_EXPORTS_DIR and
+ * SKILLS_LOGS_DIR (already-resolved directories). SKILLS_EXPORT_DIR is kept
+ * for back-compat with anything reading the singular CLI-side name.
+ */
+export declare function skillRunEnv(context: SkillRunContext): Record<string, string>;
 export declare function getRunExportDir(runId: string, skill: string, targetDir?: string): string;

package/dist/lib/skill-aliases.d.ts

@@ -1,17 +1,5 @@
 export declare const SKILL_ALIASES: {
-    readonly transcribe: "transcript";
-    readonly "speech-to-text": "transcript";
-    readonly "generate-pdf": "pdf-generate";
-    readonly "create-pdf": "pdf-generate";
-    readonly "generate-doc": "doc-generate";
-    readonly "generate-document": "doc-generate";
-    readonly "read-document": "doc-read";
-    readonly "document-read": "doc-read";
-    readonly "pdf-reader": "read-pdf";
-    readonly "generate-image": "image";
-    readonly "image-generator": "image";
     readonly "create-blog-article": "blog-article";
-    readonly "skill-diff": "diff-viewer";
 };
 export type SkillAlias = keyof typeof SKILL_ALIASES;
 export declare function normalizeSkillSlug(name: string): string;

package/dist/lib/skill-bundle.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Bytes backed by an ArrayBuffer this process owns.
+ *
+ * Spelled out rather than left as a bare `Uint8Array` because Node's readFileSync and
+ * Bun's gzipSync return views over pooled or shared buffers, and passing one of those to
+ * `new Response(...)` or letting it outlive the call is how a view ends up describing
+ * bytes that belong to something else.
+ */
+export type OwnedBytes = Uint8Array<ArrayBuffer>;
+/** Copy any byte view into a buffer of its own. */
+export declare function ownBytes(view: Uint8Array | ArrayBuffer): OwnedBytes;
+export interface SkillBundleEntry {
+    path: string;
+    bytes: OwnedBytes;
+    mode: number;
+}
+export interface PackedSkillBundle {
+    /** The gzipped tar. This is what is uploaded and what the digest is taken over. */
+    bytes: OwnedBytes;
+    /** Lowercase hex sha-256 of `bytes`. The skill's content address. */
+    sha256: string;
+    fileCount: number;
+    /** Total uncompressed size of the packed files, for a size limit that means something. */
+    unpackedByteSize: number;
+    /** Relative paths included, sorted. Surfaced so `push --dry-run` can show them. */
+    paths: string[];
+}
+export interface PackSkillBundleOptions {
+    /** Reject before compressing when the sources exceed this. 0 disables the check. */
+    maxUnpackedBytes?: number;
+}
+export declare function sha256Hex(bytes: Uint8Array): string;
+/** Collect the files a bundle would contain, in archive order. */
+export declare function collectSkillBundleEntries(dir: string): SkillBundleEntry[];
+export declare function packSkillBundle(dir: string, options?: PackSkillBundleOptions): PackedSkillBundle;
+/** Inverse of packSkillBundle. Used by the round-trip tests and by any future `pull`. */
+export declare function unpackSkillBundle(bundle: Uint8Array): SkillBundleEntry[];

package/dist/lib/vendor-host-code-scan.d.ts

@@ -0,0 +1,66 @@
+import { type ScanSource } from "./vendor-host-url.js";
+export declare const CODE_FILE_PATTERN: RegExp;
+export declare function isCodeFile(file: string): boolean;
+/**
+ * Where a URL literal sits. Used only for REPORTING — the pass/fail decision is
+ * position-independent on purpose, so a syntactic form nobody enumerated here
+ * still cannot hide a URL.
+ */
+export type UrlLiteralPosition = "parameter default" | "object property" | "class field" | "variable initializer" | "fallback operand" | "ternary branch" | "call argument" | "return value" | "literal";
+/**
+ * A vendor domain written into a string literal, whether or not it forms a URL.
+ *
+ * The URL-shaped checks are value-dependent: they have to reconstruct what the
+ * program will produce, and every reconstruction is a finite set of cases that
+ * an attacker can step outside of (`.concat`, `.slice`, `.replace`, a `const`
+ * referenced by name, a JSON blob parsed at runtime). This check is
+ * value-INDEPENDENT: the vendor's own domain has to appear somewhere in the
+ * bytes for the program to reach the vendor, so looking for the domain as a
+ * token catches every assembly trick at once.
+ *
+ * It is a denylist, so it says nothing about a vendor domain nobody has listed —
+ * that case is what the URL allowlist is for. The two are deliberately different
+ * shapes because they fail in different directions.
+ */
+export type CodeFindingKind = 
+/** Host resolves to a domain we operate. */
+"vendor-host"
+/** Host resolves to a domain that is not on APPROVED_CODE_HOSTS. */
+ | "unapproved-host"
+/** The TLD is supplied by code, so no host can be certified. */
+ | "undeterminable-host"
+/** The file could not be parsed, so its contents were never inspected. */
+ | "unparsable"
+/** The bytes could not be decoded as text, so they were never inspected. */
+ | "undecodable"
+/** A vendor domain appears in a string literal, in any form. */
+ | "vendor-domain-token";
+export interface CodeUrlFinding {
+    file: string;
+    line: number;
+    kind: CodeFindingKind;
+    /** True only for `kind === "vendor-host"`. */
+    vendor: boolean;
+    url?: string;
+    host?: string;
+    domain?: string;
+    position?: UrlLiteralPosition;
+    detail?: string;
+}
+/**
+ * Every absolute URL a source file can statically produce, found by folding
+ * string expressions and walking the AST — never by matching a syntactic shape.
+ *
+ * Failure to read the file is itself reported. A scanner that returns "clean"
+ * for a file it could not parse is worse than no scanner, because it converts an
+ * unknown into a certification. One stray byte used to do exactly that.
+ */
+export declare function findCodeUrlLiterals(file: string, content: string): CodeUrlFinding[];
+/**
+ * STRONG check over packed executable code.
+ *
+ * Every finding is a refusal to certify, not only a bad host: an unreadable or
+ * unparsable code file is reported, because silence about a file nobody read is
+ * indistinguishable from silence about a clean file.
+ */
+export declare function findDisallowedCodeUrls(sources: Iterable<ScanSource>): CodeUrlFinding[];

package/dist/lib/vendor-host-folding.d.ts

@@ -0,0 +1,40 @@
+import ts from "typescript";
+import { type Sentinels } from "./vendor-host-url.js";
+type FoldSegment = {
+    text: string;
+} | {
+    hole: ts.Node;
+};
+export interface Folded {
+    segments: FoldSegment[];
+    /** Sub-expressions that were not constant, so the walker can still scan them. */
+    holes: ts.Node[];
+}
+/**
+ * Module-local constant bindings, so `const H = "vendor.invalid"` used by name is
+ * resolved rather than treated as an opaque runtime value.
+ *
+ * Without this, moving the host one `const` away from the URL was enough to turn
+ * a hard-coded endpoint into an "undeterminable host", which the annotation
+ * carve-outs then waved through. Scope is deliberately shallow — a single
+ * assignment to a `const` with a constant initialiser — because anything cleverer
+ * would need a type checker, and the guard should be honest about being a
+ * syntactic tool.
+ */
+type ConstantBindings = Map<string, string | Map<string, string>>;
+export declare function collectConstantBindings(source: ts.SourceFile): ConstantBindings;
+export declare function fold(node: ts.Node, out: Folded, bindings: ConstantBindings): void;
+/** Is this node the outermost part of a string-building expression? */
+export declare function isFoldRoot(node: ts.Node): boolean;
+/**
+ * Render a folded expression two ways, because both are values the program can
+ * produce and each hides a different attack:
+ *
+ *   - holes as sentinels: keeps `https://s3.${region}.amazonaws.com` readable as
+ *     the amazonaws.com host it is, and makes `"https://" + host` visible as a
+ *     scheme with an undeterminable authority;
+ *   - holes as empty strings: catches a host split by an interpolation that
+ *     contributes nothing, e.g. `` `https://ski${""}lls.md` ``.
+ */
+export declare function renderFolded(folded: Folded, sentinels: Sentinels): string[];
+export {};

package/dist/lib/vendor-host-guard.d.ts

@@ -0,0 +1,47 @@
+/**
+ * vendor-host-guard.ts — machinery for the R1 boundary checks.
+ *
+ * R1: unconfigured OSS never produces a URL on a vendor-controlled host.
+ *
+ * WHAT THIS FILE CHECKS, PRECISELY — read this before trusting its silence.
+ *
+ * There are two checks with deliberately different strengths, and the
+ * difference is the whole design:
+ *
+ *   1. `findDisallowedCodeUrls` — the STRONG check, over executable code.
+ *      Every absolute http(s) URL that appears in a *string literal* in a
+ *      packed `.ts`/`.js`-family file must be on `APPROVED_CODE_HOSTS`.
+ *      It is an allowlist and it is position-independent: URLs are found by
+ *      walking the TypeScript AST for string literals, so it does not matter
+ *      whether the literal sits in a variable initializer, an object property,
+ *      a function or constructor parameter default, a class field, a ternary
+ *      branch, a `||`/`??` fallback, or a bare call argument. A host nobody has
+ *      approved fails — including a vendor domain nobody has thought of yet.
+ *
+ *      An earlier version of this guard matched two hand-written syntactic
+ *      shapes with regexes. It missed constructor parameter defaults and object
+ *      properties, which is exactly how the rule gets broken in practice. The
+ *      AST walk exists because a regex cannot honestly express "a URL literal
+ *      is reachable as a default, in any position".
+ *
+ *   2. `findVendorHostReferences` — the WEAK check, over everything else
+ *      (Markdown, JSON, plain text). It is a denylist keyed on
+ *      `VENDOR_CONTROLLED_DOMAINS`, so it catches a *known* vendor domain in
+ *      prose and does NOT catch an unknown one. That limit is real and stated
+ *      here rather than glossed. It is acceptable only because prose cannot
+ *      make a request; code can, and code is covered by check 1.
+ *
+ * Both run over the PACKED FILE LIST rather than `src/`: the `files` negation
+ * globs in package.json mean the repository and the published package are
+ * different sets of bytes, and only the published set is what a user installs.
+ *
+ * `typescript` is a devDependency. That is fine: this module is imported only
+ * by the test suite and by `scripts/release-guard.ts`, both of which run with
+ * devDependencies installed (`prepack` already shells out to `tsc`). Nothing in
+ * the published runtime graph imports it.
+ */
+export * from "./vendor-host-policy.js";
+export * from "./vendor-host-url.js";
+export * from "./vendor-host-folding.js";
+export * from "./vendor-host-code-scan.js";
+export * from "./vendor-host-package.js";

package/dist/lib/vendor-host-package.d.ts

@@ -0,0 +1,42 @@
+import type { CodeUrlFinding } from "./vendor-host-code-scan.js";
+import type { ScanSource, VendorHostFinding } from "./vendor-host-url.js";
+export interface PackedFs {
+    existsSync: (path: string) => boolean;
+    statSync: (path: string) => {
+        isFile: () => boolean;
+    };
+    readFileSync: (path: string) => Buffer;
+}
+/**
+ * Read every file in the published package as a scan source.
+ *
+ * Driven by the packer's own file list rather than by walking `src/`: the `files`
+ * negation globs mean the repository and the published tarball are different
+ * sets of bytes, and the tarball is what a user installs.
+ *
+ * Bytes that will not decode are recorded as `undecodable` rather than skipped.
+ * Skipping is how a single NUL byte makes a whole file invisible to a scanner.
+ */
+export declare function readPackedSources(packedFiles: readonly string[], root: string, fs: PackedFs, joinPath: (...parts: string[]) => string): ScanSource[];
+export interface EntryPointCoverage {
+    path: string;
+    packed: boolean;
+    read: boolean;
+    certified: boolean;
+}
+/** Every path a consumer can `require`/`import`/execute, from package.json. */
+export declare function declaredEntryPoints(manifest: unknown): string[];
+/**
+ * Anti-vacuity, per entry point.
+ *
+ * A global "we scanned more than N files" is satisfiable by files that have
+ * nothing to do with the code under test: on an unbuilt tree the skill corpus
+ * alone cleared the old threshold while `bin/`, `dist/` and everything they are
+ * built from went unscanned. Coverage has to be asserted against the specific
+ * artifacts a consumer runs.
+ */
+export declare function checkEntryPointCoverage(manifest: unknown, packedFiles: readonly string[], scanned: ReadonlyMap<string, {
+    certified: boolean;
+}>): EntryPointCoverage[];
+export declare function uncoveredEntryPoints(coverage: readonly EntryPointCoverage[]): EntryPointCoverage[];
+export declare function formatFindings(findings: ReadonlyArray<VendorHostFinding | CodeUrlFinding>): string;

package/dist/lib/vendor-host-policy.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Registrable domains the vendor controls. A URL on one of these fails both
+ * checks. Adding a new vendor domain to the codebase without adding it here
+ * does NOT make it invisible: check 1 is an allowlist, so an unlisted domain
+ * fails as "unapproved" even if nobody has classified it as ours.
+ */
+export declare const VENDOR_CONTROLLED_DOMAINS: readonly string[];
+/**
+ * POLICY — third-party endpoint defaults vs vendor endpoint defaults.
+ *
+ * R1 bans defaulting to hosts *we operate*. It does not ban a bring-your-own-key
+ * skill from naming the public API of the provider whose key the user supplies:
+ * `api.openai.com` in a skill pointed at the user's own OpenAI account is the
+ * provider's published address, not a service we run, and there is no other
+ * value it could sensibly take. That is legitimate under R2's "third-party
+ * provider the user configures directly (BYO key — documented, never proxied)".
+ *
+ * So the distinction is explicit rather than accidental:
+ *
+ *   - a default endpoint on a host WE operate            → forbidden, always;
+ *   - a default endpoint on an approved third-party host → allowed;
+ *   - a default endpoint on any other host               → forbidden until
+ *     reviewed and listed here with a reason.
+ *
+ * Every entry is a registrable domain plus its justification. This list doubles
+ * as the inventory of every host the published code is able to name.
+ */
+export declare const APPROVED_CODE_HOSTS: readonly {
+    domain: string;
+    reason: string;
+}[];
+/**
+ * Exact URLs that may appear despite being on a vendor domain. Matched on the
+ * full URL, never on the domain, so a real endpoint on the same domain still
+ * fails. Keep minimal and justified.
+ */
+export declare const VENDOR_HOST_URL_EXCEPTIONS: readonly {
+    url: string;
+    reason: string;
+}[];
+/** Reduce a hostname to its registrable domain (approximate eTLD+1). */
+export declare function registrableDomain(host: string): string;
+export declare function isLoopbackHost(host: string): boolean;
+export declare function isVendorControlledHost(host: string): boolean;
+export declare function isApprovedCodeHost(host: string): boolean;
+/**
+ * Packed files allowed to contain a host whose TLD is supplied by `{…}` template
+ * syntax (`https://s3.{partitionResult#dnsSuffix}`). These are bundles of the
+ * AWS SDK, whose endpoint-rule engine substitutes the DNS suffix per partition.
+ *
+ * File-scoped on purpose: the carve-out used to be package-wide, which meant any
+ * file could park a partial authority next to a runtime value and be exempted.
+ * A host completed from a *code* expression is never exempt, in any file.
+ */
+export declare const TEMPLATE_HOST_FILES: readonly {
+    file: string;
+    reason: string;
+}[];
+export declare function allowsTemplateHost(file: string): boolean;
+/**
+ * Sites that build a host out of a computed value.
+ *
+ * Building a host from configuration is exactly what R1 asks for, so these are
+ * not defects — but they are also the shape an endpoint default hides in, so
+ * each one is acknowledged here rather than exempted by a blanket rule. Matched
+ * on file AND exact URL fragment, never on file alone, and never on line number
+ * so that rebuilding a bundle does not churn the list. A new dynamic-host site
+ * fails until someone reads it and adds it.
+ */
+export declare const DYNAMIC_HOST_SITES: readonly {
+    file: string;
+    path: string;
+    expr: string;
+    reason: string;
+}[];
+/**
+ * Path component of a URL, used as the annotation key. Deliberately not the full
+ * URL: a dynamic-host URL renders as a bare scheme, and storing that literal
+ * would both read as noise and trip the repo's own insecure-HTTP scanner.
+ */
+export declare function urlPath(url: string): string;
+/**
+ * Is this specific site annotated?
+ *
+ * Matched on file AND url path AND a substring of the host-producing EXPRESSION.
+ * The expression is what makes the annotation site-scoped: keying on
+ * (file, path) alone degenerated to keying on the file, because every
+ * computed host with no path renders to the same bare scheme — so one annotated
+ * site silently pre-approved every future one in the same file.
+ */
+export declare function isAnnotatedDynamicHost(file: string, url: string, expressionText: string): boolean;
+/**
+ * The policy module must name the vendor domains it declares. Exclude only this
+ * file from the value-independent token check; URL-shaped checks still apply.
+ */
+export declare const VENDOR_DOMAIN_DECLARATION_FILE = "src/lib/vendor-host-policy.ts";