@hasna/skills 0.1.63 → 0.1.66

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,8 +95,13 @@ 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>;
     /**
@@ -34,5 +110,46 @@ export declare class RemoteSkillsClient {
      * 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-routing.d.ts

@@ -0,0 +1,60 @@
+/**
+ * run-routing.ts — where a skill run executes: on this machine, or on the
+ * configured Skills API.
+ *
+ * One resolver serves every run surface (the CLI `skills run` path, the MCP
+ * `run_skill` tool, and the `skills schedule run` surface) so they cannot drift
+ * apart.
+ *
+ * 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`);
+ *   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
+ *      isHostedMetadataPackage in hosted-skill-set.ts).
+ *
+ * Otherwise the run is LOCAL, and local stays the default: an unconfigured
+ * install never sends anything anywhere.
+ *
+ * A server-owned skill never falls back to local execution. Without the origin
+ * or the credential the resolver fails closed with an error naming the exact
+ * setup command, per the product brief: "Premium or server-executed skills
+ * fail closed without API credentials and do not fall back to bundled local
+ * execution."
+ *
+ * Premium-catalog and pricing metadata is server-side and never ships in this
+ * package; the resolver concerns routing only.
+ */
+import type { SkillMeta } from "./registry-types.js";
+export type RunRoutingErrorCode = "REMOTE_REQUIRES_ORIGIN" | "REMOTE_REQUIRES_CREDENTIAL";
+export type RunRouting = {
+    route: "remote";
+    apiKey: string;
+} | {
+    route: "local";
+} | {
+    route: "error";
+    code: RunRoutingErrorCode;
+    error: string;
+};
+/**
+ * Is execution of this skill server-owned per its published contract?
+ * The marker is the skill contract's declaration; absent means local
+ * execution is the contract.
+ */
+export declare function isServerOwnedSkill(skill: Pick<SkillMeta, "serverOwned">): boolean;
+/**
+ * Decide the route for one skill run from injectable inputs, so tests can mock
+ * the origin and the credential without touching the ambient environment.
+ */
+export declare function resolveRunRouting(skill: Pick<SkillMeta, "name" | "serverOwned">, apiKey: string | null | undefined, apiUrl: string | undefined): RunRouting;
+/**
+ * Resolve the route against the ambient configuration and credential store.
+ * The returned `apiKey` on the remote route is the same value the resolver
+ * 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;