@hasna/skills 0.2.0 → 0.3.0

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

@@ -120,11 +120,11 @@ export declare class RemoteSkillsClient {
      * instance serves no bundle for this skill (the metadata-only fallback path).
      */
     getBundle(slug: string, version?: string): Promise<Response | null>;
-    /** List the pins the instance holds for this principal. */
     /** Every published version of a slug, newest first (hasna/apps#1630). */
     listSkillVersions(slug: string): Promise<RemoteSkillVersion[]>;
     /** One version's manifest, or null when the slug@version was never published. */
     getSkillVersion(slug: string, version: string): Promise<RemoteSkillVersion | 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
@@ -154,16 +154,26 @@ export declare class RemoteSkillsClient {
         limit?: number;
     }): Promise<UpdatedSincePage>;
 }
-export declare function createRemoteSkillsClient(): RemoteSkillsClient | null;
+/**
+ * The client for the configured instance, or null when this install runs on
+ * this machine (no credential and no authority).
+ *
+ * A configured authority with no credential does NOT return null: the shared
+ * ladder throws, so the caller fails loudly instead of quietly reading the
+ * bundled corpus while authentication is unconfigured.
+ *
+ * ASYNC because the credential ladder is: a vault pointer
+ * (`HASNA_SKILLS_API_KEY_REF`) is completed through the secrets vault before a
+ * client is built, so this never hands `RemoteSkillsClient` an empty key to put
+ * behind `Authorization: Bearer `.
+ */
+export declare function createRemoteSkillsClient(env?: Record<string, string | undefined>): Promise<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).
+ * Identical to createRemoteSkillsClient() now that resolution is the shared
+ * ladder, which reads the Keychain and the credentials file per call and writes
+ * nothing. Kept as a separate name so read-only callers keep reading as
+ * read-only, and so the distinction survives if a write ever creeps back in.
  */
-export declare function createRemoteSkillsClientReadOnly(): RemoteSkillsClient | null;
+export declare function createRemoteSkillsClientReadOnly(env?: Record<string, string | undefined>): Promise<RemoteSkillsClient | null>;

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

@@ -1,11 +1,11 @@
 /**
  * Remote registry client.
  *
- * Local registry behavior remains the default. These helpers are opt-in and
- * read from SKILLS_API_URL or config.apiUrl so services can expose
- * a compatible registry API without hard-coding deployment details upstream.
+ * Local registry behavior remains the default. These helpers are opt-in: the
+ * authority and the credential both come from the shared fleet ladder
+ * (lib/fleet-credentials.ts), so a service can expose a compatible registry API
+ * without this package hard-coding anything about where it is deployed.
  */
-import { type SkillsConfig } from "./config.js";
 import type { SkillMeta } from "./registry.js";
 export interface RemoteRegistryOptions {
     apiUrl?: string;
@@ -14,7 +14,25 @@ export interface RemoteRegistryOptions {
     authToken?: string | null;
     fetchImpl?: (input: string | URL | Request, init?: RequestInit) => Promise<Response>;
 }
-export declare function getConfiguredApiUrl(config?: SkillsConfig, env?: Record<string, string | undefined>): string | undefined;
+export declare function getConfiguredApiUrl(env?: Record<string, string | undefined>): string | undefined;
+/**
+ * Compose one Skills API request URL from an authority and an endpoint.
+ *
+ * The Skills server serves its API under `/api/v1`, so a bare authority gets
+ * `/api/v1` appended — the SAME composition `RemoteSkillsClient` performs
+ * (`${origin}/api/v1/...`). The two sites must agree: they are handed the same
+ * origin by the same resolver.
+ *
+ * A trailing `/skills` is only stripped when the API prefix precedes it
+ * (`.../api/skills`, `.../api/v1/skills`), i.e. when an operator pasted the
+ * full collection base that this package's own error messages print. A BARE
+ * trailing `/skills` is NOT a collection: the default fleet authority is
+ * `https://api.hasna.com/skills`, where `/skills` is the gateway's per-app PATH
+ * PREFIX. Treating that as "the base already names the collection" collapsed
+ * every remote read onto the gateway app root — which answers 404 — so a
+ * correctly credentialled install on the default authority could not run
+ * `skills list` at all, on the plain merge path as well as `--remote`.
+ */
 export declare function buildSkillsApiUrl(apiUrl: string, endpoint?: string): string;
 export declare function parseRemoteRegistryPayload(payload: unknown): SkillMeta[];
 export declare function parseRemoteSkillPayload(payload: unknown): SkillMeta;
@@ -27,12 +45,14 @@ export declare function loadRemoteRegistry(options?: RemoteRegistryOptions): Pro
  * 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
+ *   - Nothing configured (no credential, no authority) -> the local list is
+ *     returned unchanged and no request is attempted. An install running on
+ *     this machine must stay byte-identical to the pre-merge output.
+ *   - An authority configured with NO credential -> this throws, from the
+ *     shared ladder. It used to return the local half silently, which is the
+ *     false green the 2026-09-04 ruling removes: an operator who pointed this
+ *     CLI at an instance and lost the key was shown a healthy local listing.
+ *   - Credential (+ authority, else the fleet gateway) -> 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"`.

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

@@ -8,9 +8,11 @@
  *
  * A skill run is REMOTE only when all three hold:
  *
- *   1. an origin is configured (config `apiUrl` or `$SKILLS_API_URL`);
- *   2. a credential is present (`$SKILLS_API_KEY` / `$SKILL_API_KEY` or the
- *      auth store written by `skills auth login`);
+ *   1. a credential resolves on the fleet ladder (an argument, an env pointer,
+ *      the macOS Keychain, `~/.hasna/skills/config/credentials`, or
+ *      `$HASNA_SKILLS_API_KEY`) — see lib/fleet-credentials.ts;
+ *   2. an authority follows from it (`$HASNA_SKILLS_API_URL`, the Keychain
+ *      `api-url` item, the credentials file, else the fleet gateway);
  *   3. the skill carries the server-owned marker from its published contract
  *      (`skills.runtime: "hosted"` or `skills.source: "remote" |
  *      "private-hosted"` in the skill's `package.json` — see
@@ -57,4 +59,4 @@ export declare function resolveRunRouting(skill: Pick<SkillMeta, "name" | "serve
  * validated, so the caller never re-reads (and cannot diverge from) the
  * credential the decision was made with.
  */
-export declare function resolveConfiguredRunRouting(skill: Pick<SkillMeta, "name" | "serverOwned">): RunRouting;
+export declare function resolveConfiguredRunRouting(skill: Pick<SkillMeta, "name" | "serverOwned">, env?: Record<string, string | undefined>): Promise<RunRouting>;

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

@@ -29,10 +29,41 @@ export declare const APPROVED_CODE_HOSTS: readonly {
     domain: string;
     reason: string;
 }[];
+/**
+ * The public fleet gateway's host.
+ *
+ * Every Hasna CLI reaches its service through one gateway origin, path-prefixed
+ * by app, and since the credential-ladder ruling of 2026-09-04 (hasna/apps#1720,
+ * #1668) that address is the DEFAULT authority in the shared @hasna/contracts
+ * client — so the string ships inside the bundle, on a domain this policy calls
+ * vendor-controlled. It is listed in VENDOR_HOST_URL_EXCEPTIONS below.
+ *
+ * R1 IS NOT WEAKENED BY THIS, because R1 was never about the hostname. It says
+ * an UNCONFIGURED install must not produce a URL, and that still holds exactly:
+ * the shared resolver composes the gateway only AFTER a credential has resolved
+ * (an argument, an env pointer, the macOS Keychain, the credentials file, or
+ * the API-key variable). With no credential there is no URL — which is what
+ * `unconfigured-client-boundary.test.ts` asserts, against the resolvers rather
+ * than against a hostname, so that test needed no weakening either.
+ *
+ * The exception is scoped to exact strings on this one host. Every other
+ * endpoint on a vendor domain still fails, including other paths on this one.
+ *
+ * Typed as `string` rather than left to inference on purpose: a literal type
+ * would print the host into the emitted `.d.ts`, which ships, and the packed
+ * vendor-domain scan reads shipped bytes without caring that they are types.
+ */
+export declare const FLEET_GATEWAY_HOST: string;
 /**
  * Exact URLs that may appear despite being on a vendor domain. Matched on the
  * full URL, never on the domain, so a real endpoint on the same domain still
  * fails. Keep minimal and justified.
+ *
+ * An entry whose path is empty is allowed ONLY for {@link FLEET_GATEWAY_HOST}:
+ * the shared client holds the gateway ORIGIN as a constant and appends the app
+ * slug at runtime, so the origin and its one-slash folded form are the literals
+ * that actually appear in the bundles. Every other vendor host must name an
+ * exact endpoint, so a bare vendor origin can never be excepted.
  */
 export declare const VENDOR_HOST_URL_EXCEPTIONS: readonly {
     url: string;

package/dist/sdk/index.d.ts

@@ -9,7 +9,13 @@
  * implementation with the interface as the contract; nothing here duplicates
  * business logic. The SaaS control plane imports this package directly and
  * never spawns the server binaries.
+ *
+ * The client credential seam is re-exported too, so an SDK consumer resolves the
+ * Skills authority and credential exactly the way the CLI and the MCP server do
+ * — the shared @hasna/contracts ladder — instead of reading an environment
+ * variable of its own. See lib/fleet-credentials.ts.
  */
+export { MissingSkillsFleetError, SkillsFleetCredentialError, SKILLS_API_KEY_ENV, SKILLS_API_URL_ENV, SKILLS_APP, configuredSkillsApiUrl, noticeLocalSkillsMode, normalizeSkillsApiOrigin, requireSkillsApiOrigin, requireSkillsFleet, resolveSkillsApiOrigin, resolveSkillsFleet, skillsCredentialFilePath, skillsCredentialFiles, skillsCredentialOrReason, type HostedSkillsFleet, type LocalSkillsFleet, type SkillsFleet, type SkillsFleetErrorCode, type SkillsFleetOptions, } from "../lib/fleet-credentials.js";
 export * from "./server.js";
 export * from "./registry.js";
 export * from "./runs.js";