@hasna/skills 0.1.62 → 0.1.64

package/dist/lib/pull.d.ts

@@ -1,5 +1,16 @@
 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";
+/** Header carrying the immutable revision identity of the served row (todos d061fcda). */
+export declare const BUNDLE_REVISION_ID_HEADER = "X-Skill-Revision-Id";
+/** Header carrying the per-slug write counter of the served row. */
+export declare const BUNDLE_REVISION_NUMBER_HEADER = "X-Skill-Revision-Number";
+/** 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 +20,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 +37,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,8 +46,32 @@ 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;
+    /**
+     * The revision id (todos d061fcda) this pull installed, when the instance reported one.
+     * Recorded in the marker so a later pull can detect that the remote moved on.
+     */
+    revisionId?: string;
+    /** True when the instance answered 410: the slug was deleted and pull reconciled. */
+    tombstoned?: boolean;
+    /** With `tombstoned`: true when a local corpus entry existed and was removed. */
+    removed?: boolean;
+    /**
+     * With `tombstoned`: true when the local corpus entry was NOT pull-managed (no pull
+     * marker), so it was left in place — a remote 410 never deletes a user-created skill.
+     */
+    leftInPlace?: boolean;
+    /**
+     * True when the instance no longer serves a published revision under this slug (its
+     * tombstone window expired) but the local copy is a revision-marked published install.
+     * Reported instead of silently swapping in a bundled skill of the same name.
+     */
+    purged?: boolean;
     error?: string;
 }
 export interface PullSkillsResult {
@@ -38,4 +81,58 @@ 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;
+    /** The server-declared revision id, when the header was present and well-formed. */
+    revisionId?: string;
+    /** The server-declared per-slug write counter, when the header was present. */
+    revisionNumber?: number;
+}
 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;
+    revisionId?: 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;
+    revisionId?: string;
+    source?: "pull" | "sync";
+}): void;

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

@@ -0,0 +1,114 @@
+import { type PortableSkillOptions } from "./portable-skills.js";
+import { RemoteSkillsClient } from "./remote-client.js";
+export type ReconcileConflictPolicy = "local" | "remote" | "skip";
+/**
+ * The default policy, named exactly as the plan specifies: when the digests are identical
+ * the local state wins by construction (nothing to resolve); every other divergence is
+ * skipped and reported unless --conflict says otherwise.
+ */
+export declare const DEFAULT_CONFLICT_POLICY: "local-wins-on-identical-digest-else-skip-and-report";
+export declare const CONFLICT_POLICIES: readonly ReconcileConflictPolicy[];
+/** Corpus-root cursor recording the last sync run. */
+export declare const SYNC_CURSOR_FILE = ".sync-cursor.json";
+export declare const SYNC_CURSOR_SCHEMA_VERSION: 1;
+export interface ReconcileRegistryOptions extends PortableSkillOptions {
+    /** Push local-only, changed-locally, and conflicts won by local. */
+    push?: boolean;
+    /** Pull remote-only, changed-remotely, and conflicts won by remote. */
+    pull?: boolean;
+    /** Both directions (the default when neither --push nor --pull is given). */
+    all?: boolean;
+    /** Plan and report without writing anything. */
+    dryRun?: boolean;
+    /** Conflict resolution policy. */
+    conflict?: ReconcileConflictPolicy;
+    /** Client override. `undefined` resolves one from configuration; `null` models "no credential". */
+    client?: RemoteSkillsClient | null;
+    /** HMAC signing key for bundle signature verification. Defaults to $SKILLS_SIGNING_KEY. */
+    signingKey?: string;
+}
+export type ReconcileSkillState = "local-only" | "remote-only" | "changed-locally" | "changed-remotely" | "conflict" | "in-sync";
+export type ReconcileAction = "push" | "pull" | "skip" | "none";
+export interface ReconcileSkillEntry {
+    slug: string;
+    state: ReconcileSkillState;
+    action: ReconcileAction;
+    localVersion?: string;
+    remoteVersion?: string;
+    localSha256?: string;
+    remoteSha256?: string;
+    /** Why the entry was classified or skipped this way. */
+    reason?: string;
+    /** Present only for executed (non-dry-run) actions. */
+    result?: {
+        ok: boolean;
+        detail?: string;
+    };
+}
+export interface ReconcileSummary {
+    /** Skills found in the local corpus. */
+    local: number;
+    /** Skills the registry serves (published plus bundled). */
+    remote: number;
+    inSync: number;
+    pushed: number;
+    pulled: number;
+    /** Divergences the conflict policy had to resolve (or decline to resolve). */
+    conflicts: number;
+    /** Divergences skipped under the policy. */
+    skipped: number;
+    errors: number;
+}
+export interface ReconcileCursor {
+    schemaVersion: typeof SYNC_CURSOR_SCHEMA_VERSION;
+    managedBy: string;
+    lastSyncedAt: string;
+    runCount: number;
+    summary: ReconcileSummary;
+}
+export interface ReconcileRegistryResult {
+    corpusRoot: string;
+    /** True when a real run would first migrate the legacy corpus layout into place. */
+    migrationPending: boolean;
+    direction: "push" | "pull" | "all";
+    dryRun: boolean;
+    conflictPolicy: ReconcileConflictPolicy;
+    /** The full declared policy label; identical to conflictPolicy for local/remote. */
+    conflictPolicyDescription: string;
+    summary: ReconcileSummary;
+    skills: ReconcileSkillEntry[];
+    /** Present only when the run was real and completed without errors. */
+    cursor?: Pick<ReconcileCursor, "lastSyncedAt" | "runCount">;
+}
+export declare class ReconcileRegistryError extends Error {
+    readonly detail?: string[] | undefined;
+    constructor(message: string, detail?: string[] | undefined);
+}
+/**
+ * Re-check the local side of one pull candidate, immediately before the pull batch.
+ *
+ * Packs FIRST, then samples existence: a directory that appeared between the plan and
+ * the pack is provably on disk when the sample runs. Sampling before the pack let a
+ * concurrent editor's partial tree read as "still absent" — the pack then threw on it
+ * while the stale sample stayed false, so localMoved was false and the pull replaced
+ * the newly created directory (review P1). The ops seam exists so a test can pin that
+ * ordering deterministically: pack throws on the partial tree, the post-pack sample
+ * sees it, and the candidate counts as moved.
+ *
+ * Returns true when the local side moved since the plan: a digest different from the
+ * planned one, or a directory present where the plan saw none (a concurrent editor).
+ */
+export declare function recheckLocalSide(plannedLocal: string | undefined, localDir: string, ops?: {
+    pack: (dir: string) => string;
+    exists: (dir: string) => boolean;
+}): boolean;
+/**
+ * Run one sync pass.
+ *
+ * The plan (classification + per-skill action) is computed in full before anything is
+ * executed, and a dry run stops at the plan: no publish, no pull, no marker, no cursor —
+ * proven by readback in the tests. Every executed mutation re-checks both sides first
+ * (see the module header); a side that moved since the plan skips that skill and reports
+ * it rather than overwriting state the plan did not see.
+ */
+export declare function reconcileRegistry(options?: ReconcileRegistryOptions): Promise<ReconcileRegistryResult>;

package/dist/lib/registry.d.ts

@@ -9,12 +9,15 @@ export declare function isBasicSkillName(name: string): boolean;
 export declare function findExtensionSkillPath(name: string): string | null;
 /**
  * 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).
+ * extension checkout and global custom skills from the canonical local corpus
+ * — <app folder>/installed/<name>/ before the owner-layout migration, <app
+ * folder>/skills/<name>/ after it (resolveCorpusRoot(), the one resolution
+ * every discovery path shares) — plus the legacy ~/.hasna/skills/custom/<name>/
+ * migration safety net.
  *
  * 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.
+ * official skills. Extension skills are read in place and never copied into the
+ * corpus. Results are cached for 5 seconds.
  */
 export declare function loadRegistry(cwd?: string): SkillMeta[];
 export declare function loadBasicRegistry(cwd?: string): SkillMeta[];

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

@@ -1,12 +1,83 @@
 import { type RemoteSkillRunContract } from "./remote-run-contract.js";
+/**
+ * A server that predates this client's pin/tag/incremental-sync routes answered
+ * 404/405 for them. The caller must never mistake that for "no pins" or "empty
+ * listing" — a silently-empty sync would look like success and drop nothing on
+ * the next push. This error is how the version-skew surfaces fail-closed.
+ */
+export declare class RemoteRouteUnsupportedError extends Error {
+    readonly path: string;
+    readonly status: number;
+    readonly instance: string;
+    constructor(path: string, status: number, instance: string);
+}
+/** Any other non-ok response on the new-route methods, with the status attached. */
+export declare class RemoteRequestError extends Error {
+    readonly path: string;
+    readonly status: number;
+    constructor(path: string, status: number, statusText: string);
+}
+/**
+ * A remote pin on a skill, matching the hosted-pins wire shape
+ * (`{ slug, pinnedAt, metadata }`). `pinnedAt`/`metadata` are server-reported
+ * and may be absent.
+ */
+export interface RemotePin {
+    slug: string;
+    pinnedAt?: string;
+    metadata?: Record<string, unknown>;
+}
+/** The minimal per-skill row the pin/tag/updated-since routes serve. */
+export interface RemoteSkillSummary {
+    slug: string;
+    name?: string;
+    version?: string;
+    updatedAt?: string;
+}
+/**
+ * One page of an incremental listing. `nextCursor` is an opaque continuation
+ * token; null (or an absent field) means the listing is complete.
+ */
+export interface UpdatedSincePage {
+    skills: RemoteSkillSummary[];
+    nextCursor: string | null;
+}
 export declare class RemoteSkillsClient {
     private apiUrl;
     private apiKey;
     constructor(apiKey: string, apiUrl?: string);
     private request;
+    /**
+     * Fail-closed version-skew guard for the pin/tag/updated-since routes.
+     *
+     * A server that predates these routes answers 404 (unmatched path) or 405
+     * (unmatched method). Both are surfaced as `RemoteRouteUnsupportedError` —
+     * never as an empty listing, which would read as "no pins / no changes" and
+     * silently desynchronize the caller. Every other non-ok response becomes a
+     * `RemoteRequestError` carrying the status.
+     *
+     * `domainNotFoundCodes` is the one deliberate exception: a route the server
+     * DOES have can 404 for a domain reason (the hosted-pins DELETE answers
+     * `{ code: "PIN_NOT_FOUND" }` when no pin exists). A 404 whose JSON body
+     * carries one of those codes is returned to the caller (status intact) so it
+     * can apply domain semantics instead of misreporting version skew. Every
+     * other 404 — including the dispatcher's `{ code: "NOT_FOUND" }` on a route
+     * the server lacks — still throws `RemoteRouteUnsupportedError`.
+     */
+    private requestNewRoute;
     listSkills(): Promise<any[]>;
     getSkillMd(slug: string): Promise<string | null>;
     getSkill(slug: string): Promise<any | null>;
+    /**
+     * Raw GET for one skill, with the HTTP status surfaced. Used by the reconcile
+     * re-check (registry-reconcile.ts) so it can distinguish "no such skill" (404) from
+     * "the registry failed to answer" (any other non-success status) instead of treating
+     * both as absent.
+     */
+    getSkillStatus(slug: string): Promise<{
+        status: number;
+        body: unknown;
+    }>;
     submitRun(slug: string, input?: Record<string, unknown>, args?: string[]): Promise<RemoteSkillRunContract>;
     getRun(runId: string): Promise<RemoteSkillRunContract | null>;
     getRunLogs(runId: string): Promise<any[]>;
@@ -24,9 +95,61 @@ export declare class RemoteSkillsClient {
      * 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.
+     *
+     * Optimistic concurrency (todos d061fcda): pass the revision id this client last read
+     * for the slug (from getSkill().revisionId) as `ifMatch`. The instance refuses a
+     * publish against a live slug that does not name its current revision with 409 — this
+     * is how a push never silently overwrites a newer remote revision.
      */
-    publishSkill(manifest: Record<string, unknown>, bundle?: Uint8Array): Promise<Response>;
+    publishSkill(manifest: Record<string, unknown>, bundle?: Uint8Array, ifMatch?: string): 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>;
+    /** List the pins the instance holds for this principal. */
+    listPins(): Promise<RemotePin[]>;
+    /**
+     * Pin a skill on the instance (upsert — pinning again refreshes it). The
+     * wire contract matches the hosted-pins routes: a PUT with an optional
+     * `{ metadata }` body, answered with the stored pin (`slug`, `pinnedAt`,
+     * `metadata`).
+     */
+    pin(slug: string, metadata?: Record<string, unknown>): Promise<RemotePin>;
+    /**
+     * Unpin a skill on the instance. Resolves true when a pin existed and was
+     * deleted; false when the instance has no pin for this slug (its 404
+     * carries `code: "PIN_NOT_FOUND"` — a domain answer, not version skew). A
+     * bare 404 (route not deployed) still throws `RemoteRouteUnsupportedError`.
+     */
+    unpin(slug: string): Promise<boolean>;
+    /** List the tag names the instance serves. */
+    listTags(): Promise<string[]>;
+    /** List the skills carrying a tag on the instance. */
+    skillsByTag(tag: string): Promise<RemoteSkillSummary[]>;
+    /**
+     * Cursor-based incremental listing of skills updated after `since` (ISO 8601).
+     * Each page carries an opaque `nextCursor`; null means the listing is complete.
+     * This is the feed T9's sync reconciliation verb consumes.
+     */
+    listUpdatedSince(since: string, options?: {
+        cursor?: string;
+        limit?: number;
+    }): Promise<UpdatedSincePage>;
 }
 export declare function createRemoteSkillsClient(): RemoteSkillsClient | null;
+/**
+ * Write-free client resolution for read-only paths (e.g. `sync --dry-run`).
+ *
+ * createRemoteSkillsClient() resolves the stored credential through
+ * getAuthFilePath() and the stored origin through loadConfig() — both route
+ * through getDataDir(), which WRITES (mkdirs the app dir, merges legacy ~/.skills
+ * content, copies the legacy config). A dry run must resolve the same client a
+ * real run would without performing any of that: the credential and the origin
+ * are read from the same files at the same computed paths, and the MissingApiUrl
+ * failure mode is preserved (a key with no origin still fails loudly).
+ */
+export declare function createRemoteSkillsClientReadOnly(): RemoteSkillsClient | null;

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

@@ -19,4 +19,30 @@ export declare function buildSkillsApiUrl(apiUrl: string, endpoint?: string): st
 export declare function parseRemoteRegistryPayload(payload: unknown): SkillMeta[];
 export declare function parseRemoteSkillPayload(payload: unknown): SkillMeta;
 export declare function loadRemoteRegistry(options?: RemoteRegistryOptions): Promise<SkillMeta[]>;
+/**
+ * Merge the authenticated remote registry into a local listing, whenever the
+ * install is pointed at a hosted instance.
+ *
+ * This is the fail-closed (R1) default-read merge: a client configured with an
+ * origin sees the folder UNION cloud in the plain `list`/`search` path, while
+ * every other install keeps today's exact local behavior.
+ *
+ *   - No origin configured  -> the local list is returned unchanged and no
+ *     request is attempted. An unconfigured install must stay byte-identical
+ *     to the pre-merge output.
+ *   - Origin configured but no credential -> the local list is returned
+ *     unchanged and nothing throws. Auth-missing must never crash a read.
+ *   - Origin + credential -> the remote registry is fetched and merged under
+ *     the precedence in registry-merge.ts (custom > extension > private >
+ *     private-hosted > remote > upstream > official), remote rows tagged
+ *     `source: "remote"`.
+ *   - A configured, authenticated read that FAILS (auth rejection, HTTP
+ *     error, network failure) throws a clear error rather than silently
+ *     returning the local half — a silent partial listing would report
+ *     success for a union the caller asked to include.
+ *
+ * The explicit `--remote` path stays on loadRemoteRegistry(): an explicit
+ * request has always been fatal on failure, and that contract is unchanged.
+ */
+export declare function mergeRemoteRegistry(local: SkillMeta[], options?: RemoteRegistryOptions): Promise<SkillMeta[]>;
 export declare function loadRemoteSkill(name: string, options?: RemoteRegistryOptions): Promise<SkillMeta>;

package/dist/lib/revision.d.ts

@@ -0,0 +1,29 @@
+/** The row's content-addressed revision identity: a lowercase hex sha-256. */
+export declare const REVISION_ID_PATTERN: RegExp;
+export interface RevisionContent {
+    slug: string;
+    displayName: string;
+    description: string;
+    category: string;
+    tags: string[];
+    source: string;
+    kind: "executable" | "instruction";
+    version?: string;
+    skillMd?: string;
+    bundleSha256?: string;
+    bundleByteSize?: number;
+}
+export declare function revisionIdOf(content: RevisionContent): string;
+export declare function revisionIdOfRecord(record: RevisionContent): string;
+/**
+ * The legacy-row marker the 0004 migration leaves behind.
+ *
+ * Migration 0004 adds revision_id with DEFAULT '', so rows written before the migration
+ * carry an empty id. An empty id would make the If-Match guard vacuous for those rows:
+ * two clients that both read '' would both "match" and both land, silently overwriting
+ * each other. The stores replace the marker with a real content sha on first open
+ * (idempotent: new code always writes a full id, so the marker never reappears).
+ */
+export declare const LEGACY_REVISION_ID = "";
+/** True when a revision id is the empty legacy marker (needs backfill). */
+export declare function isLegacyRevisionId(value: string): boolean;

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;