@hasna/skills 0.1.59 → 0.1.61

package/dist/lib/agent-sync.d.ts

@@ -0,0 +1,123 @@
+/**
+ * `skills sync` — the last mile: write skills from this machine's corpus
+ * (~/.hasna/skills/installed/<name>/) into each coding agent's global skills directory,
+ * per-tool adapted, so an agent auto-loads them.
+ *
+ * This is the deliberate reversal of the old "pins, not installs" stub: agent skill
+ * folders used to be left entirely unmanaged and every write path returned success:false.
+ * They are now written — but only the ones this tool owns. Ownership is tracked with a
+ * marker file. An unmarked directory is left alone by default; only one that already has
+ * SKILL.md can be explicitly adopted, while any other unmarked directory is never touched.
+ */
+import { renameSync } from "node:fs";
+/**
+ * The coding agents `skills sync` targets by default. These runtimes load a
+ * `<home>/.<agent>/skills/<name>/SKILL.md` tree (OpenCode is the one path exception).
+ * Gemini is retired; Windsurf/pi are addressable through installSkillForAgent but are
+ * not in the default fan-out.
+ */
+export type SyncAgent = "claude" | "codewith" | "codex" | "opencode" | "cursor";
+export declare const SYNC_AGENTS: readonly SyncAgent[];
+/**
+ * Ownership marker written beside every SKILL.md this tool syncs. Its presence is how a
+ * re-sync tells "a skill I wrote, safe to update" from "a skill the user hand-authored,
+ * do not touch". A hidden sidecar rather than a frontmatter field so the SKILL.md the
+ * agent loads stays exactly the adapted document and nothing else.
+ */
+export declare const SYNC_MARKER_FILE = ".hasna-skills.json";
+export declare const SYNC_MARKER_MANAGED_BY = "@hasna/skills";
+export interface SyncMarker {
+    managedBy: string;
+    skill: string;
+    source: string;
+    syncedAt: string;
+}
+export declare function isSyncAgent(value: string): value is SyncAgent;
+export declare function resolveSyncAgents(arg?: string): SyncAgent[];
+/** The global skills directory for an agent, honouring a test-supplied home. */
+export declare function agentGlobalSkillsDir(agent: SyncAgent, homeDir?: string): string;
+/**
+ * Adapt a SKILL.md for a target agent.
+ *
+ * `user_invocable` is a Claude-only frontmatter field (it controls Claude's slash menu).
+ * The Claude copy carries it; every other agent's copy has it stripped, because the field
+ * is meaningless there and skill-sync policy is that non-Claude copies must not carry
+ * Claude-specific frontmatter. The body is left verbatim: automatically rewriting prose
+ * would corrupt meaning, and corpus/instruction skills are authored tool-neutral.
+ */
+export declare function adaptSkillMdForAgent(skillMd: string, agent: string): string;
+/** A pointer SKILL.md for an executable skill: what it is and how to actually run it. */
+export declare function pointerSkillMd(name: string, description: string): string;
+export type SyncActionKind = "create" | "update" | "skip";
+export interface AgentSyncAction {
+    skill: string;
+    agent: SyncAgent;
+    path: string;
+    action: SyncActionKind;
+    reason?: string;
+}
+export interface SyncSkillsOptions {
+    /** Specific skills to sync. When empty, every corpus skill is synced. */
+    names?: string[];
+    /** Explicit; the default when no names are given is already "all". */
+    all?: boolean;
+    /** Target agents. Defaults to SYNC_AGENTS. */
+    agents?: SyncAgent[];
+    /** Report intended actions without writing anything. */
+    dryRun?: boolean;
+    /** Adopt an unmanaged agent skill only when its directory already contains SKILL.md. */
+    force?: boolean;
+    /** Corpus root override. Tests only. */
+    rootDir?: string;
+    /** Home directory override for agent skill dirs. Tests only. */
+    homeDir?: string;
+}
+export interface SyncSkillsResult {
+    actions: AgentSyncAction[];
+}
+export declare function syncSkillsToAgents(options?: SyncSkillsOptions): SyncSkillsResult;
+export interface WriteManagedAgentSkillParams {
+    skill: string;
+    agent: SyncAgent;
+    skillMd: string;
+    source?: "bundled" | "corpus";
+    resourceDir?: string;
+    homeDir?: string;
+    dryRun?: boolean;
+    force?: boolean;
+}
+/**
+ * Write one skill into one agent's global folder, non-clobbering.
+ *
+ * A directory this tool has written before carries the marker file and is replaced with
+ * an exact mirror. A directory with a SKILL.md but no marker is the user's own skill and
+ * is skipped unless `force` explicitly adopts it. Any other pre-existing unmarked
+ * directory is always left untouched. A fresh directory is created.
+ */
+export declare function writeManagedAgentSkill(params: WriteManagedAgentSkillParams): AgentSyncAction;
+export interface ManagedDirWriteResult {
+    action: SyncActionKind;
+    path: string;
+    reason?: string;
+}
+export interface ManagedDirWriteOptions {
+    skill: string;
+    source?: string;
+    resourceDir?: string;
+    dryRun?: boolean;
+    force?: boolean;
+    /** Test seam for exercising rollback after the original directory has moved. */
+    renameDirectory?: typeof renameSync;
+}
+/**
+ * The primitive both the fan-out sync and the single-skill installer share: replace one
+ * owned skill directory with an exact staged mirror, non-clobbering, and stamp it as ours.
+ * `dir` is the skill's own directory (…/skills/<name>), so callers control scope (global
+ * vs project) by choosing the directory.
+ */
+export declare function writeManagedSkillDir(dir: string, skillMd: string, options: ManagedDirWriteOptions): ManagedDirWriteResult;
+/**
+ * Remove a skill this tool synced from an agent folder. Refuses to delete a directory it
+ * did not write (no marker), so it can never remove a user's hand-authored skill.
+ */
+export declare function removeManagedAgentSkill(skill: string, agent: SyncAgent, homeDir?: string): boolean;

package/dist/lib/api-url.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Single source of truth for resolving the Skills API endpoint.
+ *
+ * Boundary rule (R1): an unconfigured install must never produce a URL on a
+ * vendor-controlled host.
+ *
+ *   - Read paths fail closed: `resolveApiUrl()` returns `undefined` and the
+ *     caller keeps working against the bundled local registry.
+ *   - Auth and write paths fail loudly: `requireApiUrl()` throws an error that
+ *     names the missing configuration.
+ *
+ * There is deliberately no fallback endpoint and no localhost default. An
+ * unconfigured CLI has nothing sane to point a credential-bearing request at,
+ * so it must say so rather than pick a host on the user's behalf.
+ */
+import { type SkillsConfig } from "./config.js";
+export declare const API_URL_ENV_VAR = "SKILLS_API_URL";
+export declare const API_URL_CONFIG_KEY = "apiUrl";
+/** Hint shown wherever a Skills API URL is required but absent. */
+export declare const MISSING_API_URL_HINT: string;
+export declare class MissingApiUrlError extends Error {
+    readonly code = "MISSING_API_URL";
+    constructor(action?: string);
+}
+/**
+ * Resolve the configured Skills API origin, or `undefined` when the install has
+ * not been pointed at an instance. `SKILLS_API_URL` wins over the config file.
+ */
+export declare function resolveApiUrl(config?: SkillsConfig, env?: Record<string, string | undefined>): string | undefined;
+/**
+ * Resolve the configured Skills API origin, or throw naming the missing
+ * configuration. Use this on every auth and write path.
+ */
+export declare function requireApiUrl(action?: string, config?: SkillsConfig, env?: Record<string, string | undefined>): string;

package/dist/lib/auth-store.d.ts

@@ -1,13 +1,29 @@
+/**
+ * Stored credentials for a Skills API instance.
+ *
+ * `apiKey` is the only credential. The identity fields are display metadata
+ * echoed back from the instance's `whoami`, so they are optional: an instance
+ * that does not return them leaves them unset. They are never invented locally
+ * — a placeholder written here is indistinguishable from a value the server
+ * actually returned once it is read back out of `auth.json`.
+ */
 export interface AuthConfig {
     apiKey: string;
-    email: string;
-    orgId: string;
-    orgSlug: string;
-    userId: string;
+    email?: string;
+    orgId?: string;
+    orgSlug?: string;
+    userId?: string;
 }
 export declare function getAuthConfig(): AuthConfig | null;
 export declare function saveAuthConfig(config: AuthConfig): void;
 export declare function clearAuthConfig(): void;
 export declare function getApiKey(): string | null;
 export declare function normalizeSkillsApiOrigin(apiUrl: string): string;
-export declare function getApiUrl(): string;
+/**
+ * Origin every credential-bearing request is sent to.
+ *
+ * Throws `MissingApiUrlError` when the install has not been pointed at an
+ * instance. There is no fallback endpoint: an unconfigured CLI must not decide
+ * on the user's behalf where their email address, login code, or API key goes.
+ */
+export declare function getApiUrl(action?: string): string;

package/dist/lib/blog-article.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Input validation for the `blog-article` skill.
+ *
+ * This is ordinary run-option validation — topic, tone, length, SEO flag, and
+ * article count — surfaced at the CLI/MCP layer so a bad invocation fails with a
+ * clear message before the skill runs. It carries no pricing or billing concern.
+ */
+export declare const ARTICLE_GENERATION_SLUG = "blog-article";
+export declare const ARTICLE_MAX_COUNT = 12;
+export declare const ARTICLE_COUNT_ERROR = "Count must be an integer between 1 and 12.";
+declare const ARTICLE_TONES: readonly ["professional", "casual", "technical", "friendly"];
+declare const ARTICLE_LENGTHS: readonly ["short", "medium", "long"];
+export type ArticleTone = typeof ARTICLE_TONES[number];
+export type ArticleLength = typeof ARTICLE_LENGTHS[number];
+export interface BlogArticleRunOptions {
+    topic?: string;
+    audience?: string;
+    tone: ArticleTone;
+    length: ArticleLength;
+    seo: boolean;
+    outline?: string;
+    count: number;
+}
+export type BlogArticleValidationResult = {
+    ok: true;
+    options: BlogArticleRunOptions;
+    input: Record<string, unknown>;
+    errors: [];
+} | {
+    ok: false;
+    input: Record<string, unknown>;
+    errors: string[];
+};
+export declare function validateBlogArticleRunOptions(input?: unknown, args?: string[], validation?: {
+    requireTopic?: boolean;
+}): BlogArticleValidationResult;
+export {};

package/dist/lib/config.d.ts

@@ -8,17 +8,59 @@
  *
  * Values from the project config override global config.
  */
+/**
+ * There is no deployment "mode" key.
+ *
+ * Skills has one deployment story: you run it. Whether this CLI talks to a
+ * server is not a product variant, it is one fact — whether an API origin is
+ * configured (apiUrl here, or $SKILLS_API_URL). Nothing else may be derived
+ * from a declared label, because a label can disagree with the configuration
+ * it claims to describe.
+ *
+ * One caveat, true at the time of writing and tracked separately: getApiUrl()
+ * in auth-store.ts still falls back to a built-in origin when neither is set,
+ * so "no origin configured" is not yet the same as "sends nothing anywhere" on
+ * the auth path. Removing that fallback belongs to the no-vendor-defaults work,
+ * not here; remote-registry.ts already fails closed and is the model.
+ *
+ * Configs written by older versions may still carry a "mode" key on disk. That is
+ * refused rather than ignored - see lib/retired-settings.ts for why silence is
+ * the worse of the two failures - and `skills config unset mode` removes it.
+ */
 export interface SkillsConfig {
-    mode?: "local" | "self-hosted";
     defaultAgent?: "claude" | "codex" | "gemini" | "pi" | "opencode" | "all";
     defaultScope?: "global" | "project";
     format?: "compact" | "json" | "csv";
     apiUrl?: string;
+    extensionsDir?: string;
 }
 export type ConfigScope = "global" | "project";
+/**
+ * Environment variable that relocates the skills data directory.
+ *
+ * Exported so that every reader agrees on the name: previously the literal was
+ * duplicated in portable-skills.ts and honoured there but *not* in getDataDir(),
+ * which is what made the override only half work (see getDataDir below).
+ */
+export declare const DATA_DIR_ENV = "HASNA_SKILLS_DIR";
+/**
+ * Subfolder of the data directory holding the installed skill corpus.
+ *
+ * ~/.hasna/skills is the skills *app* folder, matching every sibling Hasna app:
+ * mementos keeps agents/ beside config.json and mementos.db, accounts keeps
+ * profiles/ beside accounts.json, knowledge keeps artifacts/ and cache/ beside
+ * auth.json. Each puts app data at the app root and content in a named subfolder.
+ *
+ * Skills used to be the exception, writing one folder per skill straight into the
+ * app root next to config.json and skills.db. That is the only reason a denylist
+ * of "entries that look like skills but aren't" ever had to exist; no sibling app
+ * needs one. With the corpus under installed/, a skill may be named `config` or
+ * `custom` without colliding with anything.
+ */
+export declare const INSTALLED_SKILLS_DIRNAME = "installed";
 /**
  * Get the data directory for skills global config/data.
- * New default: ~/.hasna/skills/
+ * Default: ~/.hasna/skills/, overridable with $HASNA_SKILLS_DIR.
  * Auto-migrates from ~/.skills/ and ~/.skillsrc without deleting legacy data.
  */
 export declare function getDataDir(): string;
@@ -34,3 +76,15 @@ export declare function loadConfig(): SkillsConfig;
  * Save a single config key-value pair to the specified scope
  */
 export declare function saveConfig(key: string, value: string, scope?: ConfigScope): void;
+/**
+ * Remove a single config key from the specified scope.
+ *
+ * This is the counterpart that makes "no deployment mode" workable. Running on
+ * this machine is the absence of a configured apiUrl, so there has to be a way
+ * to get back to that state; previously the only way to express the intent was
+ * to set mode=local, and that key is gone.
+ *
+ * Returns whether the key was actually present, so callers can distinguish
+ * "removed" from "there was nothing to remove" instead of guessing.
+ */
+export declare function unsetConfig(key: string, scope?: ConfigScope): boolean;

package/dist/lib/content-scan.d.ts

@@ -2,17 +2,32 @@
  * content-scan.ts — scans skill BODIES (not just package.json/README) for content
  * that must never ship in the public @hasna/skills package.
  *
- * Three finding categories:
+ * Five finding categories:
  *   - secret-value:     credential-shaped values (API keys, tokens, private keys)
- *   - pii-contact:      personal contact PII (E.164 phone numbers)
+ *   - pii-contact:      personal contact PII (E.164 phone numbers, consumer-provider
+ *                       email addresses)
+ *   - pii-personal:     personal data ABOUT an identified individual — a real human
+ *                       name paired with employment/HR/leave/health status, or a
+ *                       government identifier carrying a real-looking value
  *   - private-context:  internal/operational context that leaks the private fleet
  *                       (fleet hostnames, home-directory paths with a real user,
  *                       internal CLI invocations, internal infra/product names)
+ *   - committed-output: operational tool output committed into the package — a
+ *                       run artifact (timestamped filename, data file under an
+ *                       exports/ directory) rather than an authored fixture
  *
- * All output is REDACTED: secret values are never emitted, phone numbers are masked
- * to their country code, and only the rule id + a safe redacted marker are reported.
+ * The first four categories are matched against file CONTENT (see {@link scanText}).
+ * `committed-output` is matched against the package-relative PATH instead (see
+ * {@link scanPaths}), because what makes an artifact wrong is where it came from,
+ * not what is inside it — a scraped catalog and a hand-written fixture can be
+ * byte-identical in shape.
+ *
+ * All output is REDACTED: secret values are never emitted, phone numbers, emails and
+ * personal names are masked, and only the rule id + a safe redacted marker are
+ * reported. Findings are surfaced in (potentially public) CI logs, so a rule must
+ * never echo the personal data it just found.
  */
-export type ScanCategory = "secret-value" | "pii-contact" | "private-context";
+export type ScanCategory = "secret-value" | "pii-contact" | "pii-personal" | "private-context" | "committed-output";
 export interface ScanRule {
     category: ScanCategory;
     /** Stable, human-readable rule id (safe to print — never a secret value). */
@@ -21,6 +36,13 @@ export interface ScanRule {
     pattern: RegExp;
     /** Optional predicate to drop known-safe example matches (e.g. 555 phone numbers). */
     isExample?: (match: string) => boolean;
+    /**
+     * Match against the whole text rather than line by line. Needed for record
+     * shapes whose fields sit on DIFFERENT lines — a YAML export writes the
+     * person on one line and the status on the next, and a per-line regex can
+     * never see that pairing.
+     */
+    multiline?: boolean;
 }
 export interface ScanFinding {
     file: string;
@@ -32,11 +54,33 @@ export interface ScanFinding {
     redacted: string;
 }
 export declare const SCAN_RULES: ScanRule[];
+/** A rule matched against a package-relative path rather than file content. */
+export interface ScanPathRule {
+    category: ScanCategory;
+    id: string;
+    description: string;
+    pattern: RegExp;
+    /** Optional predicate to drop known-safe paths (e.g. source trees). */
+    isExample?: (path: string) => boolean;
+}
+/**
+ * Scan package-relative PATHS for committed tool output. Unlike the content
+ * scanners this reads nothing from disk — the path itself is the evidence. The
+ * reported marker is the path verbatim: it is not sensitive, and the maintainer
+ * needs it in order to delete the file.
+ */
+export declare function scanPaths(paths: string[]): ScanFinding[];
 /**
  * Produce a redacted marker for a matched value. Secret values are NEVER emitted;
- * phone numbers are reduced to their leading country context; private-context
- * matches (hostnames, paths, CLI names — not credentials) are shown verbatim so a
- * maintainer can locate and remove them.
+ * PII (phone numbers, emails, personal names and identifiers) keeps only a short
+ * two-character locating prefix; private-context matches (hostnames, paths, CLI
+ * names — not credentials) are shown verbatim so a maintainer can locate and
+ * remove them.
+ *
+ * Personal data must be masked here as well as elsewhere: findings are printed
+ * into (potentially public) CI logs, so reporting a leaked name in full would
+ * republish the very data the rule exists to catch. The rule id plus file:line is
+ * enough for a maintainer to find it in the working tree.
  */
 export declare function redactMatch(category: ScanCategory, ruleId: string, match: string): string;
 /**
@@ -44,7 +88,16 @@ export declare function redactMatch(category: ScanCategory, ruleId: string, matc
  * reporting; it is never read from disk here.
  */
 export declare function scanText(text: string, file?: string): ScanFinding[];
-/** Read a file and scan its contents. Binary files are skipped and yield no findings. */
+/**
+ * Read a file and scan its contents.
+ *
+ * This used to skip any file whose first 8000 bytes contained a NUL, which made
+ * a NUL byte a silent opt-out from secret and PII scanning: the identical
+ * credential-shaped literal was caught without a NUL and passed with one. Only
+ * genuinely compiled/compressed content is skipped now, decided by magic number
+ * rather than by the presence of a byte, and NULs are stripped during decoding
+ * so they cannot be used to break a pattern apart either.
+ */
 export declare function scanFile(path: string, reportedName?: string): ScanFinding[];
 /**
  * Scan a list of files. `nameFor` maps an absolute path to the name reported in

package/dist/lib/discovery.d.ts

@@ -1,24 +1,24 @@
 import type { SkillMeta } from "./registry-types.js";
-import { type PublicSkillPricing } from "./pricing.js";
 export interface CompactSkillDiscovery {
     name: string;
     category: string;
     description: string;
-    pricing: PublicSkillPricing;
 }
 export type PublicSkillDiscovery<T extends SkillMeta = SkillMeta> = Omit<T, "description" | "tags"> & {
     description: string;
     tags: string[];
-    pricing: PublicSkillPricing;
 };
 export declare function getCompactSkillDiscovery(skill: SkillMeta): CompactSkillDiscovery;
 export declare function getPublicSkillDiscovery<T extends SkillMeta>(skill: T): PublicSkillDiscovery<T>;
-export declare function publicDiscoveryPriceLabel(skill: {
-    name: string;
-    pricing?: PublicSkillPricing;
-}): string;
 export declare function publicDiscoveryTags(tags: string[]): string[];
 export declare function sanitizePublicDiscoveryText(text: string): string;
-export declare function publicDiscoveryEnvVars(skillName: string, envVars: string[]): string[];
-export declare function publicDiscoveryDependencies(skillName: string, dependencies: Record<string, string>): Record<string, string>;
-export declare function publicDiscoveryDocumentation(skill: SkillMeta, documentation: string | null): string | null;
+/**
+ * Every skill now runs from bundled source or is instruction prose, so the
+ * environment it declares IS the environment a caller must provide. A BYO-key
+ * skill's variable is the single most important thing to surface, not to redact.
+ */
+export declare function publicDiscoveryEnvVars(_skillName: string, envVars: string[]): string[];
+/** Dependencies are installed locally now, so the real list is the useful one. */
+export declare function publicDiscoveryDependencies(_skillName: string, dependencies: Record<string, string>): Record<string, string>;
+/** The skill's own docs are the truth; there is no hosted runtime to describe. */
+export declare function publicDiscoveryDocumentation(_skill: SkillMeta, documentation: string | null): string | null;

package/dist/lib/doc-derived-counts.d.ts

@@ -0,0 +1,56 @@
+/**
+ * doc-derived-counts.ts — the one place that re-derives the counts our docs assert.
+ *
+ * WHY THIS IS A MODULE AND NOT INLINE IN ONE TEST
+ *
+ * CLAUDE.md rotted once (it claimed 202 skills against a real 229) and grew the
+ * guard in `claude-md.test.ts`. README.md then rotted the SAME number in the same
+ * direction and nobody noticed for weeks, because the guard was scoped to a single
+ * hard-coded path: `202+` sat in README while the guarded table two files away read
+ * 85. One document was fixed and its neighbour was left asserting the old figure.
+ *
+ * A guard that covers one of the two places a number is written is not a guard on
+ * the number; it is a guard on a file. So the derivation and the table parser live
+ * here, and every document that asserts these counts is checked by the same code.
+ * Adding a third document is a two-line test, which is the point — the cheap path
+ * has to be the correct one or the next document will hand-copy the numbers again.
+ */
+/**
+ * The heading every guarded table sits under. Fixed rather than per-document so a
+ * document cannot opt out of the guard by renaming its own section.
+ */
+export declare const TABLE_HEADING = "### Derived counts";
+/**
+ * Parse the `### Derived counts` table in `docPath` into {label -> value}.
+ *
+ * Scoped to the section rather than the whole file so an unrelated markdown table
+ * elsewhere in the document cannot inject rows. Throws rather than returning empty
+ * when the section is missing: an empty map would make every assertion pass or fail
+ * for the wrong reason.
+ *
+ * The three tolerances below are not incidental — each one is a way this guard
+ * could have failed for a reason that has nothing to do with doc drift, and a doc
+ * test that cries wolf is a doc test that gets deleted:
+ *
+ *   - Up to three leading spaces before `|`. GFM permits them, so an editor that
+ *     indents the table would otherwise yield zero rows and a diff that looks like
+ *     catastrophic drift.
+ *   - A delimiter row of ANY dash count, with or without alignment colons. `|-|-|-|`
+ *     is legal GFM; an earlier `-{2,}` test let it through as a data row named "-".
+ *   - The header is dropped BY POSITION (first row), not by matching the literal
+ *     "Count". Renaming that cell to "Metric" must not break the guard.
+ */
+export declare function readDocumentedCounts(docPath: string): Record<string, string>;
+export declare function deriveCounts(): Promise<Record<string, string>>;
+/**
+ * Narrow the derived set to the rows a given document actually publishes.
+ *
+ * README and CLAUDE.md have different audiences and deliberately carry different
+ * subsets — forcing every document to restate all seven rows would mean every skill
+ * PR edits every document, which is the tax that gets a guard deleted.
+ *
+ * Throws on a key the derivation does not produce. Without that, a typo in a
+ * document's expected-key list would silently shrink the comparison to the rows that
+ * happened to match, and the guard would pass while checking less than it claims.
+ */
+export declare function selectCounts(derived: Record<string, string>, keys: readonly string[]): Record<string, string>;

package/dist/lib/feedback.d.ts

@@ -11,5 +11,12 @@ export interface FeedbackResult {
     category: FeedbackCategory;
     path: string;
 }
+/**
+ * Resolved via getDataDir() rather than homedir() so that it agrees with the
+ * path `skills storage` advertises (native-storage.ts builds `feedbackDbPath`
+ * from getDataDir()). While this read the home directly, setting
+ * $HASNA_SKILLS_DIR made the reported path and the written path diverge - the
+ * CLI would name a database it was not using.
+ */
 export declare function getFeedbackDbPath(): string;
 export declare function saveFeedback(input: FeedbackInput): FeedbackResult;

package/dist/lib/file-bytes.d.ts

@@ -0,0 +1,43 @@
+/**
+ * file-bytes.ts — turning bytes into text that a content guard can actually scan.
+ *
+ * Every guard in this repo that reads files used to decide "is this text?" with
+ * some form of `buffer.includes(0)` and skip the file when the answer was no.
+ * That is not a heuristic, it is an opt-out: appending or prepending one NUL
+ * byte removed a file from the scan entirely, silently, and the guard still
+ * exited 0. It was live in three places at once — the R4 infrastructure scan,
+ * `content-scan.ts`'s secret/PII scanner, and `release-guard.ts`'s own marker
+ * scan, which is the actual publish gate.
+ *
+ * The rule here is: decode everything, skip almost nothing, and let the caller
+ * treat a skip as a finding.
+ */
+/**
+ * Whether the bytes are a compiled/compressed binary.
+ *
+ * Decided by CONTENT, never by filename. A filename-based version of this check
+ * was itself a bypass: a plain-text file named `leak.gz` was skipped without
+ * ever being opened. An extension is attacker-chosen; the leading bytes are not.
+ *
+ * Note what this deliberately does NOT do: it does not treat "contains a NUL"
+ * as binary. Plenty of legitimate text files contain NUL — fixtures, test
+ * corpora, anything storing a NUL-separated key — and treating that byte as a
+ * skip signal is exactly the hole being closed.
+ */
+export declare function looksBinary(buffer: Buffer): boolean;
+/**
+ * Decode file bytes to scannable text.
+ *
+ *  - UTF-16 (BOM-marked, or detected from the alternating-NUL pattern of
+ *    BOM-less ASCII) is decoded properly, so an identifier stored as UTF-16 is
+ *    ordinary text by the time any rule sees it.
+ *  - NUL bytes are stripped AFTER decoding, which defeats NUL-interleaved
+ *    payloads (`1\0"2\0"3456789012`) and, as a bonus, renders BOM-less UTF-16
+ *    ASCII readable even when the heuristic misses it.
+ *  - Line structure is preserved: NUL is not a newline, so reported line
+ *    numbers stay correct.
+ *
+ * Stripping NULs cannot cause a false negative — no rule in this repo matches a
+ * NUL — and it removes the single byte that most reliably blinded these guards.
+ */
+export declare function decodeForScanning(buffer: Buffer): string;

package/dist/lib/hosted-skill-set.d.ts

@@ -0,0 +1,69 @@
+/**
+ * hosted-skill-set.ts — the single authoritative derivation of the
+ * "hosted metadata skill" set.
+ *
+ * A hosted metadata skill ships its `package.json` and docs but NOT its `src/`.
+ * That set is expressed in three places that can silently drift apart:
+ *
+ *   1. Each skill's own `package.json` -> `skills.runtime` / `skills.source`.
+ *   2. The negated `!skills/{...}/src` glob(s) in the root `package.json` `files`.
+  *
+ * (1) is AUTHORITATIVE. It lives next to the thing it describes, so it cannot be
+ * forgotten when a directory is added, removed, or converted. (2) and (3) are
+ * projections of it and are guarded against drift in `hosted-skill-set.test.ts`.
+ *
+ * Two accessors, deliberately different:
+ *
+ * THIS REPO now has ZERO hosted skills: every catalog entry ships bundled source
+ * or is instruction prose. The guard-facing `requireHostedMetadataSlugs`
+ * accessor, and the five guards derived from it, were retired in the change that
+ * emptied the set — which is precisely what its own emptiness error demanded.
+ * `catalog-runnable.test.ts` now asserts the set stays empty, so re-introducing
+ * a hosted skill fails loudly rather than silently.
+ *
+ * The parsing helpers below remain: `release-guard.ts` still applies them to
+ * ARBITRARY packages, where a non-empty hosted set is a legitimate answer, and
+ * `release-guard.integration.test.ts` exercises them against synthetic fixtures.
+ */
+/** Shape of the only part of a skill `package.json` this module reads. */
+export interface HostedSkillPackageMarkers {
+    skills?: {
+        runtime?: unknown;
+        source?: unknown;
+    };
+}
+/**
+ * The authoritative predicate: does this parsed skill `package.json` declare
+ * itself as hosted metadata (implementation lives off-repo)?
+ */
+export declare function isHostedMetadataPackage(pkg: unknown): boolean;
+/** Read a skill directory's `package.json` and apply the authoritative predicate. */
+export declare function isHostedMetadataSkillDir(skillDir: string): boolean;
+/**
+ * Enumerate the hosted metadata slugs under a `skills/` root, sorted.
+ * Returns `[]` for this repo, and may legitimately be non-empty for another.
+ */
+export declare function listHostedMetadataSlugs(skillsRoot: string): string[];
+export declare const HOSTED_METADATA_SET_EMPTY_ERROR: string;
+/**
+ * Extract the set of slugs whose `src/` the root `files` array genuinely
+ * excludes from the published package, sorted and de-duplicated.
+ *
+ * Only negations that survive to the end of the array count: a later entry that
+ * re-includes `skills/` discards every exclusion before it, exactly as npm
+ * resolves them.
+ */
+export declare function parseHostedSourceExclusionSlugs(files: readonly string[]): string[];
+/**
+ * Render the canonical `files` exclusion entry for a slug set, so a drift
+ * failure can print the exact line to paste. Emits the bare form for a single
+ * slug because the one-element brace form is inert under `npm pack`.
+ */
+export declare function buildHostedSourceExclusionGlob(slugs: readonly string[]): string;
+/** Paths in a packed file list that would ship a hosted skill's implementation source. */
+export declare function findHostedSourcePacklistLeaks(packedPaths: readonly string[], hostedSlugs: Iterable<string>): string[];
+/** Symmetric difference between two slug sets, for readable drift failures. */
+export declare function diffSlugSets(expected: readonly string[], actual: readonly string[]): {
+    missing: string[];
+    unexpected: string[];
+};