@hasna/skills 0.1.61 → 0.1.63

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

@@ -1,7 +1,9 @@
 /**
  * `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.
+ * (the migrated owner-layout cache ~/.hasna/skills/skills/<name>/, or the
+ * legacy ~/.hasna/skills/installed/<name>/ when not migrated) 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.
@@ -18,6 +20,14 @@ import { renameSync } from "node:fs";
  */
 export type SyncAgent = "claude" | "codewith" | "codex" | "opencode" | "cursor";
 export declare const SYNC_AGENTS: readonly SyncAgent[];
+/**
+ * Environment variable naming an explicit canonical-corpus source for sync. The CLI
+ * `--source <path>` flag takes precedence; this is the ambient form, and it means the
+ * same thing: the npm package ships no corpus, so a machine that has not pulled from an
+ * instance (or that is not a checkout of the monorepo) must point sync at where the
+ * corpus actually is.
+ */
+export declare const SKILLS_SOURCE_ENV = "SKILLS_SOURCE";
 /**
  * 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,
@@ -69,18 +79,43 @@ export interface SyncSkillsOptions {
     force?: boolean;
     /** Corpus root override. Tests only. */
     rootDir?: string;
+    /**
+     * Explicit canonical-corpus source: a directory of skill folders, or the monorepo
+     * package root (which contains `skills/` and `agent-skills/`). Takes precedence over
+     * $SKILLS_SOURCE, which takes precedence over the installed corpus cache.
+     */
+    sourceDir?: string;
     /** Home directory override for agent skill dirs. Tests only. */
     homeDir?: string;
 }
 export interface SyncSkillsResult {
     actions: AgentSyncAction[];
 }
+/**
+ * Resolve where sync reads the canonical corpus from.
+ *
+ * The package ships no bundled corpus. Precedence is explicit-over-ambient:
+ *   1. `options.sourceDir`   - an explicit source: a corpus dir, or a package root
+ *                              containing `skills/` and/or `agent-skills/`
+ *   2. `$SKILLS_SOURCE`      - the ambient spelling of the same thing
+ *   3. the installed cache   - `getPortableSkillsRoot()` (what `skills pull` writes),
+ *      resolved through `resolveCorpusRoot` so a migrated owner layout
+ *      (~/.hasna/skills/skills/) is read in preference to `installed/`.
+ *
+ * A missing explicit source is an error, not a fallback to "nothing": the whole point
+ * of zero-corpus is that sync must not silently sync an empty corpus because the
+ * package directory changed shape.
+ */
+export declare function resolveSyncCorpus(options?: SyncSkillsOptions): {
+    roots: string[];
+    source: "source" | "corpus";
+};
 export declare function syncSkillsToAgents(options?: SyncSkillsOptions): SyncSkillsResult;
 export interface WriteManagedAgentSkillParams {
     skill: string;
     agent: SyncAgent;
     skillMd: string;
-    source?: "bundled" | "corpus";
+    source?: "source" | "corpus";
     resourceDir?: string;
     homeDir?: string;
     dryRun?: boolean;

package/dist/lib/home-adoption.d.ts

@@ -0,0 +1,91 @@
+import { type SyncAgent, type SyncMarker } from "./agent-sync.js";
+import type { PortableSkillOptions } from "./portable-skills.js";
+export declare const CONFLICTS_LEDGER_FILE = "conflicts.json";
+export declare const ROLLBACK_DIRNAME = "rollback";
+export interface HomeSkillEntry {
+    agent: SyncAgent;
+    skill: string;
+    /** The agent home skills directory (e.g. ~/.claude/skills). */
+    home: string;
+    /** The skill's own directory under the agent home. */
+    path: string;
+    hash: string;
+    /** SKILL.md mtime (ISO). */
+    mtime: string;
+}
+export interface HomeConflict extends HomeSkillEntry {
+    canonicalHash: string;
+}
+export interface UnknownHomeSkill extends HomeSkillEntry {
+}
+export interface AdoptionScan {
+    /** Unmarked home dirs whose SKILL.md hash matches the canonical corpus entry. */
+    adoptable: HomeSkillEntry[];
+    /** Unmarked home dirs whose content differs from canonical; never touched. */
+    conflicts: HomeConflict[];
+    /** Unmarked home dirs with no canonical corpus entry; reported and skipped. */
+    unknown: UnknownHomeSkill[];
+    /** Already-marked dirs, counted only. */
+    managed: number;
+}
+export interface AdoptionOptions extends PortableSkillOptions {
+    agents?: SyncAgent[];
+    /** Write markers and the conflicts ledger. Without it, scan only. */
+    apply?: boolean;
+}
+export interface AdoptionResult extends AdoptionScan {
+    applied: boolean;
+    /** Rollback record path, when markers were written. */
+    rollbackFile?: string;
+}
+export interface RollbackMarker {
+    agent: SyncAgent;
+    skill: string;
+    path: string;
+    hash: string;
+    marker: SyncMarker;
+}
+export interface RollbackRecord {
+    version: 1;
+    mode: "adopt" | "prune";
+    timestamp: string;
+    entries: RollbackMarker[];
+}
+export interface PruneCandidate extends RollbackMarker {
+    /** The agent home skills directory. */
+    home: string;
+}
+export interface PruneResult {
+    candidates: PruneCandidate[];
+    pruned: number;
+    dryRun: boolean;
+    rollbackFile?: string;
+}
+/**
+ * Canonical corpus index: skill name -> canonical SKILL.md hash. A skill is
+ * canonical when the corpus cache holds a directory with a SKILL.md.
+ */
+export declare function indexCanonicalCorpus(corpusRoot: string): Map<string, string>;
+/**
+ * Census of unmarked home skill dirs against the canonical corpus. Read-only.
+ */
+export declare function scanUnmarkedHomes(options?: AdoptionOptions): AdoptionScan;
+/**
+ * Write one rollback record listing every marker written (mode "adopt") or
+ * every directory removed (mode "prune"), so both operations are reversible
+ * from a single machine-readable file.
+ */
+export declare function writeRollbackRecord(mode: "adopt" | "prune", entries: RollbackMarker[], appDir?: string): string;
+/**
+ * Adopt unmarked home skills whose content exactly matches the canonical
+ * corpus. Without `apply` this is a pure scan; with `apply` it writes one
+ * marker per exact match, appends diverging dirs to the conflicts ledger, and
+ * records every written marker in a rollback file. Never deletes anything.
+ */
+export declare function adoptUnmarkedHomes(options?: AdoptionOptions): AdoptionResult;
+/**
+ * List (or, with `apply`, remove) marked home skill dirs that have no canonical
+ * corpus entry. Never touches an unmarked directory. Removals are recorded in
+ * the rollback store before they happen.
+ */
+export declare function pruneStrayHomes(options?: AdoptionOptions): PruneResult;

package/dist/lib/home-census.d.ts

@@ -0,0 +1,22 @@
+import { type SyncAgent } from "./agent-sync.js";
+import { type AdoptionOptions } from "./home-adoption.js";
+export type DriftKind = "missing-from-home" | "stray-in-home" | "diverged";
+export interface DriftEntry {
+    agent: SyncAgent;
+    skill: string;
+    kind: DriftKind;
+    path: string;
+    homeHash?: string;
+    canonicalHash?: string;
+}
+export interface DriftCensus {
+    entries: DriftEntry[];
+    /** Homes that exist and were checked. */
+    homesChecked: number;
+    /** Unmarked home skill dirs (adoption candidates, not drift). */
+    unmarked: number;
+    /** Marked home skill dirs. */
+    managed: number;
+    clean: boolean;
+}
+export declare function censusHomeDrift(options?: AdoptionOptions): DriftCensus;

package/dist/lib/home-migration.d.ts

@@ -0,0 +1,61 @@
+import { type PortableSkillOptions } from "./portable-skills.js";
+/** The canonical corpus cache subfolder of the app folder. */
+export declare const SKILLS_CACHE_DIRNAME = "skills";
+export declare const LOGS_DIRNAME = "logs";
+export declare const OUTPUTS_DIRNAME = "outputs";
+/** Marker file inside skills/ proving a migration ran; also its record. */
+export declare const LAYOUT_MIGRATION_RECORD = ".layout-migration.json";
+export declare const LEGACY_CUSTOM_DIRNAME = "custom";
+export interface LayoutMigrationRecord {
+    version: 1;
+    /** ISO timestamp of the migration. */
+    migratedAt: string;
+    /** The entries moved: "installed" for the old corpus dir, then each legacy flat dir name. */
+    moved: string[];
+    note: string;
+}
+export declare function layoutMigrationRecordPath(appDir: string): string;
+/** True once the owner layout has been migrated (the record is the authority). */
+export declare function isOwnerLayoutMigrated(appDir: string): boolean;
+/**
+ * Resolve the corpus the sync/fan-out reads from.
+ *
+ * Precedence:
+ *   1. options.rootDir — named outright, no suffix (unchanged contract)
+ *   2. migrated owner layout — <app folder>/skills when a migration record exists
+ *   3. the pre-migration corpus — getPortableSkillsRoot() (installed/, with the
+ *      legacy auto-copy migration)
+ *
+ * The migration record is required: a skills/ directory someone created by hand
+ * is not the corpus and never will be treated as one.
+ */
+export declare function resolveCorpusRoot(options?: PortableSkillOptions): string;
+export type LayoutMigrationStatus = "already-migrated" | "refused" | "migrated" | "nothing-to-do";
+export interface LayoutMigrationResult {
+    status: LayoutMigrationStatus;
+    /** Why a run refused; absent otherwise. */
+    reason?: string;
+    /** The source entries moved (or that a dry-run would move). */
+    moved: string[];
+    /** Directories created by the run. */
+    created: string[];
+    /** The record written, when a run actually migrated. */
+    record?: LayoutMigrationRecord;
+}
+export interface LayoutMigrationOptions {
+    dryRun?: boolean;
+    /** App-folder override for tests. */
+    homeDir?: string;
+}
+/**
+ * Migrate the owner layout, idempotently.
+ *
+ * - already-migrated: the record exists; nothing happens.
+ * - refused: skills/ exists with content and no record, or a legacy dir would
+ *   collide with an existing skills/<name>; nothing happens.
+ * - migrated: installed/ (when present) and every legacy flat dir moved into
+ *   skills/; logs/ and outputs/ created; the record written.
+ * - nothing-to-do: no installed/ and no legacy dirs; logs/ and outputs/ are
+ *   still created (lazily) unless the run is a dry-run.
+ */
+export declare function migrateOwnerLayout(options?: LayoutMigrationOptions): LayoutMigrationResult;

package/dist/lib/portable-skills-files.d.ts

@@ -1,5 +1,13 @@
 import type { SkillKind } from "./registry-types.js";
-import { type PortableSkillManifest } from "./portable-skills-types.js";
+import { type PortableSkillManifest, type PortableSkillProvenance, type PortableSkillRuntimeContract } from "./portable-skills-types.js";
+/**
+ * Default runtime contract (hasna.skill.v1). `bun` is the Hasna default
+ * runtime; the sandbox is read-only by default, execution is time-capped at
+ * 900s and does not assume network egress.
+ */
+export declare function defaultRuntimeContract(entrypoint?: string): PortableSkillRuntimeContract;
+/** Provenance defaults; content_hash is filled at write time over the bundle. */
+export declare function defaultProvenance(sourceCommit?: string): PortableSkillProvenance;
 export declare function normalizePortableSkillName(name: string): string;
 export declare function readPortableSkillManifest(skillPath: string, fallbackName?: string): PortableSkillManifest;
 export declare function parseSkillKind(value: string | undefined): SkillKind | undefined;
@@ -11,6 +19,16 @@ export declare function createPortableManifest(name: string, options: {
     description: string;
 }): PortableSkillManifest;
 export declare function writePortableSkillTemplate(skillPath: string, manifest: PortableSkillManifest): void;
+/**
+ * Write skill.json with the canonical content_hash computed over the current
+ * bundle. Preserves unknown keys already present in an existing skill.json
+ * (merge, never replace) and recomputes the hash whenever content changed.
+ *
+ * The manifest is written hashless FIRST so the canonical bundle covers
+ * skill.json itself; canonicalization strips content_hash, so adding the hash
+ * afterwards does not change the digest.
+ */
+export declare function writeSkillJsonWithHash(skillPath: string, manifest: PortableSkillManifest): PortableSkillManifest;
 export declare function ensurePortableSkillFiles(skillPath: string, manifest: PortableSkillManifest): PortableSkillManifest;
 /**
  * Instruction (prose) skills are consumed by agent renderers/MCP docs, not run
@@ -21,5 +39,7 @@ export declare function ensurePortableSkillFiles(skillPath: string, manifest: Po
 export declare function ensureInstructionSkillFiles(skillPath: string, manifest: PortableSkillManifest): PortableSkillManifest;
 export declare function copySkillDirectory(source: string, destination: string): void;
 export declare function renderSkillJson(manifest: PortableSkillManifest): string;
+/** The skill.json object for a manifest, with contract defaults applied. */
+export declare function renderSkillJsonObject(manifest: PortableSkillManifest): Record<string, unknown>;
 export declare function hasPackageDependencies(pkgPath: string): boolean;
 export declare function displayName(name: string): string;

package/dist/lib/portable-skills-types.d.ts

@@ -2,6 +2,50 @@ import type { SkillKind } from "./registry-types.js";
 export declare const PORTABLE_SKILL_STANDARD = "hasna.skill.v1";
 export declare const PORTABLE_SKILL_SCHEMA = "https://hasna.dev/schemas/skill.v1.json";
 export declare const PORTABLE_SKILL_DEFAULT_VERSION = "0.1.0";
+/** Allowed execution runtimes in the hasna.skill.v1 runtime contract. */
+export declare const SKILL_RUNTIMES: readonly ["bun", "node", "python3"];
+export type SkillRuntimeName = (typeof SKILL_RUNTIMES)[number];
+/** Allowed sandbox modes in the hasna.skill.v1 runtime contract. */
+export declare const SKILL_SANDBOX_MODES: readonly ["readonly-fs", "workspace-write", "full"];
+export type SkillSandboxMode = (typeof SKILL_SANDBOX_MODES)[number];
+/**
+ * Allowlisted system binaries a skill may declare. The allowlist lives here
+ * and in schemas/skill.schema.json; the parity test keeps them in agreement.
+ */
+export declare const SKILL_SYSTEM_DEPS_ALLOWLIST: readonly ["ffmpeg", "ffprobe", "imagemagick", "convert", "curl", "wget", "git", "gh", "jq", "python3", "pip3", "node", "bun", "npm", "rsync", "pdftotext", "tesseract", "7z", "unzip", "zip"];
+export type SkillSystemDep = (typeof SKILL_SYSTEM_DEPS_ALLOWLIST)[number];
+/**
+ * Runtime contract (hasna.skill.v1): how the skill executes and what it may
+ * touch. `env` carries secret REFERENCE names, never values.
+ */
+export interface PortableSkillRuntimeContract {
+    runtime: SkillRuntimeName;
+    /** Optional runtime version constraint, e.g. "22" or ">=3.12". */
+    version?: string;
+    /** Relative entrypoint; defaults to commands[0].entry. */
+    entrypoint?: string;
+    /** Max execution seconds, 1..900, default 900. */
+    timeout?: number;
+    /** Whether execution requires network egress, default false. */
+    needs_network?: boolean;
+    /** Secret reference names (uppercase identifiers), never values. */
+    env?: string[];
+    /** Filesystem access granted to execution, default readonly-fs. */
+    sandbox?: SkillSandboxMode;
+    /** Allowlisted system binaries required at execution time. */
+    system_deps?: SkillSystemDep[];
+    /** Glob patterns of artifacts the skill may produce. */
+    artifacts?: string[];
+}
+/** Provenance and integrity fields. content_hash is self-referencing. */
+export interface PortableSkillProvenance {
+    /** Git SHA of the source revision, or "unknown" for local scaffolds. */
+    source_commit?: string;
+    /** Canonical SHA-256 of the normalized bundle (see skill-hash.ts). */
+    content_hash?: string;
+    /** Pointer to changelog / release notes (relative path or URL). */
+    changelog?: string;
+}
 /**
  * Artifact class of a portable skill.
  * - `executable`: a runnable skill folder (package.json + bin + src entry).
@@ -35,6 +79,8 @@ export interface PortableSkillManifest {
     kind?: SkillKind;
     inputs: PortableSkillInput[];
     commands: PortableSkillCommand[];
+    runtime?: PortableSkillRuntimeContract;
+    provenance?: PortableSkillProvenance;
 }
 export interface PortableSkillSummary {
     name: string;

package/dist/lib/pull.d.ts

@@ -1,5 +1,12 @@
 import { type PortableSkillOptions } from "./portable-skills.js";
+import { type SkillBundleEntry } from "./skill-bundle.js";
 import type { SkillKind } from "./registry-types.js";
+/** Header carrying the canonical content digest of the served bundle. */
+export declare const BUNDLE_DIGEST_HEADER = "X-Skill-Bundle-Sha256";
+/** Header carrying the HMAC signature of the served bundle, when the server can sign. */
+export declare const BUNDLE_SIGNATURE_HEADER = "X-Skill-Bundle-Signature";
+/** Marker file written inside each corpus skill directory recording pull provenance. */
+export declare const PULL_MARKER_FILE = ".hasna-skills.json";
 /**
  * The slice of RemoteSkillsClient that `pullSkills` needs. Narrowed to an interface so a
  * test can inject a fake and the real HTTP client (which satisfies it structurally) is
@@ -9,6 +16,12 @@ export interface SkillPullClient {
     listSkills(): Promise<unknown[]>;
     getSkill(slug: string): Promise<unknown>;
     getSkillMd(slug: string): Promise<string | null>;
+    /**
+     * The skill's bundle, headers intact, or null when the instance serves none.
+     * `Response` is the natural transport type here: verification reads the
+     * X-Skill-Bundle-Sha256 / X-Skill-Bundle-Signature headers off it.
+     */
+    getBundle(slug: string): Promise<Response | null>;
 }
 export interface PullSkillsOptions extends PortableSkillOptions {
     /** Explicit skill names to pull. Ignored when `all` is set. */
@@ -20,6 +33,8 @@ export interface PullSkillsOptions extends PortableSkillOptions {
      * `null` models "no credential available" so the null-handling path stays testable.
      */
     client?: SkillPullClient | null;
+    /** HMAC signing key for bundle signature verification. Defaults to $SKILLS_SIGNING_KEY. */
+    signingKey?: string;
 }
 export interface PulledSkillResult {
     name: string;
@@ -27,6 +42,10 @@ export interface PulledSkillResult {
     path?: string;
     kind?: SkillKind;
     version?: string;
+    /** Canonical content hash of the installed bundle, when one was verified. */
+    contentHash?: string;
+    /** Source commit recorded on the bundle, when the instance reported one. */
+    sourceCommit?: string;
     /** True when the pull created the corpus entry, false when it updated an existing one. */
     created?: boolean;
     error?: string;
@@ -38,4 +57,51 @@ export declare class PullSkillError extends Error {
     readonly detail?: string[] | undefined;
     constructor(message: string, detail?: string[] | undefined);
 }
+export interface VerifiedBundle {
+    /** The received bundle bytes, owned by this process. */
+    bytes: Uint8Array;
+    /** Canonical sha256 of `bytes`. */
+    contentHash: string;
+    /** The server-declared digest, when the header was present. */
+    serverHash?: string;
+    /** The server-declared signature, when the header was present. */
+    signature?: string;
+}
 export declare function pullSkills(options?: PullSkillsOptions): Promise<PullSkillsResult>;
+/**
+ * The verification core, synchronous over already-buffered bytes: the digest header
+ * (when present) must equal the canonical sha256 of the received bytes, and the
+ * signature header (when present) must verify against the signing key when one is
+ * available — otherwise it is recorded with a warning, because a pull cannot check a
+ * signature it has no key for.
+ */
+export declare function verifyBundleResponseBytes(buffer: ArrayBuffer, response: Response, verify?: {
+    signingKey?: string;
+}): VerifiedBundle;
+/**
+ * Atomically replace the corpus entry for a verified bundle: stage every entry in a
+ * sibling directory, then rename into place (the existing entry is moved aside first
+ * and removed only after the staged tree is in position). A failure at any point leaves
+ * either the old entry or nothing — never a partial skill.
+ */
+export declare function installBundleAtomically(name: string, entries: SkillBundleEntry[], options?: PortableSkillOptions, marker?: {
+    version?: string;
+    contentHash?: string;
+    sourceCommit?: string;
+    signature?: string;
+}): {
+    path: string;
+    created: boolean;
+};
+/**
+ * Record what a pull installed. Version/hash/source-commit are the provenance a later
+ * `skills sync --check` or drift census needs; the signature is recorded when one was
+ * present so an audit can tell "verified" from "declared".
+ */
+export declare function writePullMarker(dir: string, record: {
+    skill: string;
+    version?: string;
+    contentHash?: string;
+    sourceCommit?: string;
+    signature?: string;
+}): void;

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

@@ -28,5 +28,11 @@ export declare class RemoteSkillsClient {
     publishSkill(manifest: Record<string, unknown>, bundle?: Uint8Array): Promise<Response>;
     deleteSkill(slug: string): Promise<Response>;
     downloadSkillBundle(slug: string): Promise<Response>;
+    /**
+     * Bundle fetch for the verified-pull path. Returns the raw Response so the caller can
+     * read the X-Skill-Bundle-Sha256 / X-Skill-Bundle-Signature headers, or null when the
+     * instance serves no bundle for this skill (the metadata-only fallback path).
+     */
+    getBundle(slug: string): Promise<Response | null>;
 }
 export declare function createRemoteSkillsClient(): RemoteSkillsClient | null;

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

@@ -19,6 +19,10 @@ export interface SkillRunRecord {
     args: string[];
     startedAt: string;
     completedAt?: string;
+    /** Exit code of the skill child process, when one was observed. */
+    exitCode?: number;
+    /** Wall time between startedAt and completedAt, in milliseconds. */
+    durationMs?: number;
     remote: boolean;
     remoteRunId?: string;
     costCents?: number;
@@ -51,6 +55,7 @@ export declare function completeSkillRun(context: SkillRunContext, patch: {
     error?: string;
     remoteRunId?: string;
     costCents?: number;
+    exitCode?: number;
 }): SkillRunRecord;
 export declare function updateSkillRun(context: SkillRunContext, patch: Partial<SkillRunRecord>): SkillRunRecord;
 export declare function writeRunLogs(context: SkillRunContext, stdout?: string, stderr?: string): void;

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

@@ -0,0 +1,54 @@
+import { type PackedSkillBundle } from "./skill-bundle.js";
+/** Environment variable holding the HMAC signing key. Never logged, never printed. */
+export declare const SKILLS_SIGNING_KEY_ENV = "SKILLS_SIGNING_KEY";
+/** Environment variable naming the source commit the bundle was built from. */
+export declare const SKILLS_SOURCE_COMMIT_ENV = "SKILLS_SOURCE_COMMIT";
+/** Prefix of the signature string. The remainder is lowercase hex. */
+export declare const SIGNATURE_PREFIX = "hmac-sha256:";
+export interface SkillBundleManifest {
+    name: string;
+    version: string;
+    source_commit: string;
+    /** Canonical sha256 of the bundle bytes (the skill's content address). */
+    content_hash: string;
+    /** `hmac-sha256:<hex>` over the bundle bytes. Omitted when no key is available. */
+    signature?: string;
+    published_at: string;
+}
+export interface BuildSkillBundleOptions {
+    name: string;
+    /** The skill directory to pack. */
+    dir: string;
+    version: string;
+    /** Source commit the skill came from. `unknown` when the provenance is unavailable. */
+    sourceCommit: string;
+    /** Signing key. Defaults to reading process.env[SKILLS_SIGNING_KEY_ENV]. */
+    signingKey?: string;
+    /** Explicit published_at. Defaults to now. Tests only. */
+    publishedAt?: string;
+}
+export interface BuiltSkillBundle {
+    bundle: PackedSkillBundle;
+    manifest: SkillBundleManifest;
+}
+/**
+ * Resolve the signing key from the environment. Returns null when unset, and the
+ * caller decides how to behave (omit the signature, warn, or refuse) — this function
+ * never touches stdout, so nothing about the key can leak through it.
+ */
+export declare function resolveSigningKey(env?: Record<string, string | undefined>): string | null;
+/** Sign canonical bundle bytes with an HMAC key. Returns `hmac-sha256:<hex>`. */
+export declare function signBundleBytes(bytes: Uint8Array, key: string): string;
+/**
+ * Verify a signature string against bundle bytes and a key. Returns true only for a
+ * well-formed `hmac-sha256:<hex>` signature computed over exactly these bytes.
+ * timingSafeEqual keeps the comparison from leaking a byte-at-a-time signal; the
+ * length check is a format check (a hex digest is a fixed length), not a leak.
+ */
+export declare function verifyBundleSignature(bytes: Uint8Array, signature: string, key: string): boolean;
+/**
+ * Pack a skill directory and build its signed manifest in one call — the unit the CI
+ * bundle script, push, and pull all share, so a bundle built by CI and one pushed by
+ * a machine agree on the canonical content_hash by construction.
+ */
+export declare function buildSkillBundle(options: BuildSkillBundleOptions): BuiltSkillBundle;

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

@@ -0,0 +1,35 @@
+import { type PortableSkillManifest } from "./portable-skills-types.js";
+import type { SkillValidationMessage } from "./skill-validation.js";
+/**
+ * Field-level validator implementing the hasna.skill.v1 JSON Schema
+ * (schemas/skill.schema.json). Checks the portable manifest against the
+ * contract and verifies the self-referencing content_hash when a skill
+ * folder is available. Returns exact field errors with `contract.*` codes.
+ *
+ * The parity test (skill-contract.test.ts) asserts this validator and the
+ * schema file agree on required fields, runtime/sandbox enums, and the
+ * system-deps allowlist, so the two cannot drift apart silently.
+ */
+export declare const SEMVER_PATTERN = "^(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*)(?:-((?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\\.(?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\\+([0-9a-zA-Z-]+(?:\\.[0-9a-zA-Z-]+)*))?$";
+export declare const CONTENT_HASH_PATTERN = "^[a-f0-9]{64}$";
+export declare const ENV_REFERENCE_PATTERN = "^[A-Z0-9_]+$";
+export declare const MAX_RUNTIME_TIMEOUT_SECONDS = 900;
+export declare const DEFAULT_RUNTIME_TIMEOUT_SECONDS = 900;
+export interface PortableContractOptions {
+    /**
+     * Whether the manifest is the full portable contract (a skill.json exists).
+     * When true, the runtime contract and content_hash are required; a manifest
+     * present without its integrity field is not portable. SKILL.md-only legacy
+     * skills stay under the relaxed rule.
+     */
+    strict?: boolean;
+    /** Skill folder for content_hash verification. */
+    skillPath?: string;
+}
+/**
+ * Validate the portable manifest against the hasna.skill.v1 contract.
+ * Returns issues only; callers combine with existing directory validation.
+ */
+export declare function validatePortableManifestContract(manifest: PortableSkillManifest | undefined, options?: PortableContractOptions): SkillValidationMessage[];
+/** Read a skill.json from disk and parse it, tolerating absence. */
+export declare function readRawSkillJson(skillPath: string): Record<string, unknown> | undefined;

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

@@ -0,0 +1,77 @@
+import type { PortableSkillManifest } from "./portable-skills-types.js";
+/**
+ * Canonical content hashing for the hasna.skill.v1 portable bundle.
+ *
+ * The hash covers the normalized skill bundle: skill.json (blank-canonicalized —
+ * its own `content_hash` field removed, keys sorted, line endings normalized)
+ * plus SKILL.md and every file under src/, scripts/, assets/, and references/,
+ * plus AGENTS.md, package.json, and tsconfig.json. Entries are sorted by
+ * relative path and hash-stable across platforms (posix separators, LF
+ * endings, sorted keys), so two checkouts of the same skill produce the same
+ * hash regardless of OS or editor.
+ *
+ * Excluded, mirroring the port/copy rules: node_modules, .git, dist, build,
+ * .turbo, dot-entries, and symlinks (symlinks are validation errors anyway).
+ */
+export declare const CONTENT_HASH_ALGORITHM = "sha256";
+export declare const CONTENT_HASH_HEX_LENGTH = 64;
+/** Normalize CRLF/CR to LF for hash stability across platforms. */
+export declare function normalizeLineEndings(content: string): string;
+/**
+ * Blank-canonicalize a skill.json manifest for hashing: parse it, drop the
+ * self-referencing `content_hash` field, and re-serialize with sorted keys so
+ * key order and the hash's own presence never change the digest.
+ */
+export declare function canonicalizeManifest(raw: string): string;
+export interface BundleFile {
+    /** Posix relative path from the skill root, e.g. `scripts/setup.sh`. */
+    rel: string;
+    /** Normalized text content for text files; raw buffer for binary files. */
+    content: Uint8Array;
+}
+/**
+ * Collect the normalized bundle files for a skill folder, sorted by relative
+ * path. Only the documented coverage set is included.
+ */
+export declare function collectBundleFiles(skillPath: string): BundleFile[];
+/**
+ * Compute the canonical content hash of a skill folder. Stable across
+ * platforms: sorted posix paths, LF line endings, canonicalized manifest.
+ */
+export declare function computeContentHash(skillPath: string): string;
+export interface ContentHashVerification {
+    /** Whether the skill declares a content_hash at all. */
+    declared: boolean;
+    /** Whether the declared hash is present, well-formed, and matches the bundle. */
+    valid: boolean;
+    /** The declared value, if any. */
+    declaredHash?: string;
+    /** The recomputed hash over the current bundle. */
+    computedHash?: string;
+}
+/**
+ * Verify a skill folder's declared content_hash against the recomputed
+ * canonical hash of the current bundle. A missing declaration or a mismatch
+ * fails; a malformed declaration fails.
+ */
+export declare function verifyContentHash(skillPath: string, manifest?: PortableSkillManifest): ContentHashVerification;
+/** Path sanity helper used by the contract validator: the skill folder exists. */
+export declare function skillFolderExists(skillPath: string): boolean;
+/**
+ * Canonical SKILL.md document hash for home-vs-corpus comparison.
+ *
+ * The bundle-wide hash above covers a whole skill folder; agent home
+ * directories carry only a SKILL.md, so the home comparison hashes exactly
+ * that one document. The normalization is the canonical one: LF line endings
+ * (LF-invariant, so the same document hashes identically across platforms),
+ * with the single agent-adaptation delta removed — `user_invocable` frontmatter
+ * lines, which `sync` injects for Claude and strips for every other agent.
+ * Two copies that differ only in those two ways hash identically, so an
+ * unmarked home copy that matches the canonical SKILL.md modulo adaptation is
+ * recognised as an exact match.
+ */
+export declare function canonicalAgentSkillMarkdown(content: string): string;
+/** Canonical hash of a SKILL.md document (modulo LF endings and user_invocable). */
+export declare function hashSkillMarkdown(content: string): string;
+/** Canonical hash of the SKILL.md at `path`. */
+export declare function hashSkillMarkdownFile(path: string): string;