@hasna/skills 0.1.62 → 0.1.64

package/dist/server/types.d.ts

@@ -0,0 +1,337 @@
+import type { OwnedBytes } from "../lib/skill-bundle.js";
+export declare const SERVER_RUN_STATUSES: readonly ["queued", "waiting_for_approval", "running", "succeeded", "failed", "cancel_requested", "cancelled", "retrying", "expired", "refunded"];
+export type ServerRunStatus = (typeof SERVER_RUN_STATUSES)[number];
+/**
+ * A fenced transition was refused because the run's lease_generation moved on.
+ *
+ * The worker that throws this is writing against a run it no longer owns: a
+ * newer claim took it, or a cancellation fenced it. The run is not missing -
+ * that is the null return - it has simply left the writer behind.
+ */
+export declare class StaleLeaseGenerationError extends Error {
+    readonly runId: string;
+    readonly expectedGeneration: number;
+    readonly currentGeneration: number;
+    readonly status: ServerRunStatus;
+    constructor(runId: string, expectedGeneration: number, currentGeneration: number, status: ServerRunStatus);
+}
+/**
+ * A publish or update was refused because it would silently overwrite a newer revision.
+ *
+ * The optimistic-concurrency guard (todos d061fcda): a write to an existing, live row
+ * must carry If-Match naming the current revision_id (the ETag the server issued). A
+ * missing guard, or one naming a different revision, is refused with this error instead
+ * of being applied. `currentRevisionId` is null when the row is absent or tombstoned —
+ * those are the two cases where the guard does not apply — and carries the live
+ * revision otherwise, so the caller can name what the writer was racing against.
+ */
+export declare class SkillRevisionConflictError extends Error {
+    readonly slug: string;
+    readonly expectedRevisionId: string | null | undefined;
+    readonly currentRevisionId: string | null;
+    constructor(slug: string, expectedRevisionId: string | null | undefined, currentRevisionId: string | null);
+}
+export interface ApiPrincipal {
+    apiKeyId: string;
+    orgId: string;
+    orgSlug: string;
+    orgName: string;
+    userId: string;
+    email: string;
+    role: string;
+    scopes: string[];
+}
+export interface ServerRunRecord {
+    id: string;
+    orgId: string;
+    userId: string;
+    skill: string;
+    requestedSlug: string;
+    status: ServerRunStatus;
+    input: Record<string, unknown>;
+    args: string[];
+    idempotencyKey?: string;
+    correlationId: string;
+    costCents: number;
+    /**
+     * The cancellation fence. Bumped by every claim and by every cancellation; a
+     * worker that transitions a run while carrying an older generation is writing
+     * against a run it no longer owns and is rejected (see transitionRun).
+     */
+    leaseGeneration: number;
+    outputType?: string;
+    outputPreview?: string;
+    errorCode?: string;
+    errorMessage?: string;
+    createdAt: string;
+    startedAt?: string;
+    completedAt?: string;
+}
+export interface ServerRunLog {
+    runId: string;
+    sequence: number;
+    level: "debug" | "info" | "warn" | "error";
+    message: string;
+    createdAt: string;
+}
+export interface ServerArtifact {
+    id: string;
+    runId: string;
+    orgId: string;
+    fileName: string;
+    relativePath: string;
+    contentType: string;
+    byteSize: number;
+    sha256: string;
+    storageKind: "db" | "s3";
+    storageKey?: string;
+    bodyText?: string;
+    /**
+     * Output visibility. Runs' outputs are PRIVATE by default: the value is set at
+     * write time from the governance default and persisted, never inferred at read
+     * time. "public" is the explicit opt-in for artifacts the tenant intends to
+     * share; it is not a default on any path.
+     */
+    visibility: "private" | "public";
+    /**
+     * Finite retention, set at write time as createdAt + configured TTL. Absent
+     * only when the writing path opted out explicitly; the expiry sweep deletes
+     * artifacts whose expiresAt is in the past and records a deletion receipt.
+     */
+    expiresAt?: string;
+    createdAt: string;
+}
+/** Where bytes actually live. Same vocabulary as ServerArtifact, same meaning. */
+export type BlobStorageKind = "db" | "s3";
+/**
+ * A skill published to this instance by one organization.
+ *
+ * Distinct from `SkillMeta` (src/lib/registry-types.ts), which describes a skill the CLI
+ * knows about from any source. This is the row: it always belongs to an org, and it
+ * always carries the provenance of who put it there.
+ */
+export interface ServerSkillRecord {
+    orgId: string;
+    slug: string;
+    displayName: string;
+    description: string;
+    category: string;
+    tags: string[];
+    source: string;
+    kind: "executable" | "instruction";
+    version?: string;
+    /** The agent-facing document, served verbatim by GET /skills/:slug/skill.md. */
+    skillMd?: string;
+    /** Digest of the stored bundle. Absent for a metadata-only publish. */
+    bundleSha256?: string;
+    bundleByteSize?: number;
+    publishedByUserId?: string;
+    createdAt: string;
+    updatedAt: string;
+    /**
+     * Immutable content-addressed revision identity (sha-256 over the published content,
+     * computed in server/revision.ts). Same content -> same id; any content change mints
+     * a new one. This is the ETag every read issues and every guarded write must match.
+     */
+    revisionId: string;
+    /**
+     * Monotonic per-slug write counter. Every publish and every metadata update bumps it,
+     * even when the content hash is unchanged, so "how many writes happened to this slug"
+     * is a number, not a digest comparison.
+     */
+    revisionNumber: number;
+    /**
+     * Present when the slug was deleted within the tombstone window (todos d061fcda).
+     * Reads must answer 410 with the marker so a client's pull can reconcile; the row and
+     * its bundle are purged once tombstonePurgeAfter passes. A re-publish clears both
+     * fields and revives the slug as a fresh revision.
+     */
+    tombstonedAt?: string;
+    tombstonePurgeAfter?: string;
+}
+/**
+ * Bundle bytes, addressed by their own digest.
+ *
+ * `bytes` is present only when the bundle is stored in the database (`storageKind: "db"`).
+ * For S3 the row is a pointer and SkillBundleStorage.read() fetches the object - the same
+ * split ServerArtifact makes between `bodyText` and `storageKey`, except that a bundle is
+ * a gzipped tar and so cannot be a string at any layer.
+ */
+/**
+ * A skill the principal pinned on the hosted instance.
+ *
+ * The cloud-side twin of the local `.skills/project.json` pin: metadata-only,
+ * never content. `principal` is the api_keys.id of the API key that pinned
+ * (ApiPrincipal.apiKeyId) - a pin is a fact about a specific principal's
+ * selection, and two API keys in one org each have their own pin set.
+ */
+export interface ServerPin {
+    orgId: string;
+    principal: string;
+    slug: string;
+    pinnedAt: string;
+    metadata: Record<string, unknown>;
+}
+export interface ServerSkillBundle {
+    orgId: string;
+    sha256: string;
+    byteSize: number;
+    contentType: string;
+    storageKind: BlobStorageKind;
+    storageKey?: string;
+    bytes?: OwnedBytes;
+    createdAt: string;
+}
+export interface PublishSkillInput {
+    principal: ApiPrincipal;
+    slug: string;
+    displayName: string;
+    description: string;
+    category: string;
+    tags: string[];
+    source: string;
+    kind: ServerSkillRecord["kind"];
+    version?: string;
+    skillMd?: string;
+    /** Omitted for a metadata-only publish or update. */
+    bundle?: Omit<ServerSkillBundle, "orgId" | "createdAt">;
+    /**
+     * Optimistic-concurrency guard (todos d061fcda): the revision_id (ETag) the writer
+     * read. A publish against an existing, LIVE row requires the guard to name that row's
+     * current revision_id; missing or mismatched is a SkillRevisionConflictError, never a
+     * silent overwrite. The guard is not required for a first publish (no row exists) or
+     * against a tombstoned row (nothing live to overwrite - the publish revives the slug
+     * as a fresh revision).
+     */
+    expectedRevisionId?: string;
+}
+/** Metadata-only patch. Never touches the bundle; republish to change bytes. */
+export type UpdateSkillPatch = Partial<Pick<ServerSkillRecord, "displayName" | "description" | "category" | "tags" | "version" | "kind" | "skillMd">>;
+export interface CreateRunInput {
+    principal: ApiPrincipal;
+    slug: string;
+    input: Record<string, unknown>;
+    args: string[];
+    idempotencyKey?: string;
+}
+export interface ClaimRunInput {
+    workerId: string;
+}
+/**
+ * Fields a fenced transition may write, plus the lease_generation the fence
+ * itself bumps on cancellation. Everything updateRun can write plus the
+ * generation counter; the worker never patches the generation, the cancel
+ * service does.
+ */
+export type RunTransitionPatch = Partial<Pick<ServerRunRecord, "status" | "outputType" | "outputPreview" | "errorCode" | "errorMessage" | "startedAt" | "completedAt" | "leaseGeneration">>;
+/**
+ * What a store is, in the only two dimensions the server needs at boot: which backend
+ * it is (for logs and diagnostics) and whether it survives a restart.
+ *
+ * `durable` exists because the server used to boot onto an in-process Map, report
+ * `ok: true` at /health, and lose every run on restart with no warning at any point. A
+ * store that knows it is non-durable can now say so, and startSkillsServer() refuses it
+ * unless the operator explicitly opted in.
+ */
+export interface StoreBackendInfo {
+    /**
+     * The three bundled backends are named for autocomplete; the open `string` arm is
+     * deliberate. This interface is a published seam, and a third-party store must be able
+     * to declare what it is - "mysql", "dynamodb" - without either a type error or having
+     * to misreport itself as one of ours. A closed union would make the seam implementable
+     * only by us, which is the test R3 sets for it.
+     */
+    kind: "postgres" | "sqlite" | "memory" | (string & {});
+    /** False when the data does not survive process exit. */
+    durable: boolean;
+    /** Credential-free description, safe to put in logs and error messages. */
+    label: string;
+}
+export interface SkillsProductStore {
+    /**
+     * Optional so a third-party store implementing this seam keeps compiling. An
+     * undeclared backend is treated as durable: we can refuse what a store tells us is
+     * ephemeral, and cannot infer it about somebody else's implementation. The hazard
+     * actually being closed is our own default, which is now SQLite on disk.
+     */
+    readonly backend?: StoreBackendInfo;
+    /** Release connections and file handles. Optional; not every backend holds any. */
+    close?(): Promise<void>;
+    /**
+     * Prove the backend is actually reachable, throwing if it is not.
+     *
+     * Called once at startup. Bun's SQL client connects lazily, so without this a
+     * Postgres URL pointing at a dead host produced a server that started happily and
+     * then 500ed on the first request.
+     */
+    verifyConnectivity?(): Promise<void>;
+    authenticateApiKeyHash(hash: string): Promise<ApiPrincipal | null>;
+    ensureBootstrapApiKey?(token: string, principal?: Partial<ApiPrincipal>): Promise<void>;
+    createRun(input: CreateRunInput): Promise<ServerRunRecord>;
+    listRuns(principal: ApiPrincipal, limit: number): Promise<ServerRunRecord[]>;
+    getRun(principal: ApiPrincipal, runId: string): Promise<ServerRunRecord | null>;
+    claimNextRun(input: ClaimRunInput): Promise<ServerRunRecord | null>;
+    updateRun(runId: string, patch: Partial<Pick<ServerRunRecord, "status" | "outputType" | "outputPreview" | "errorCode" | "errorMessage" | "startedAt" | "completedAt">>): Promise<ServerRunRecord | null>;
+    /**
+     * Generation-fenced transition, the cancellation gate.
+     *
+     * Optional so a third-party store implementing this seam keeps compiling; the
+     * cancel service requires it and refuses to run without it (FENCING_UNSUPPORTED)
+     * rather than cancelling unfenced. When present it is the ONLY transition the
+     * worker paths use: the UPDATE re-asserts `lease_generation = <expected>` and
+     * reports zero rows when the generation moved on (a newer claim, or a
+     * cancellation), so a late write from a stale worker never lands.
+     *
+     * Returns null when the run does not exist; throws StaleLeaseGenerationError
+     * when the generation no longer matches. The distinction matters: "nothing
+     * there" and "you lost the fence" are different facts.
+     */
+    transitionRun?(runId: string, patch: RunTransitionPatch, expectedGeneration: number): Promise<ServerRunRecord | null>;
+    appendLog(runId: string, orgId: string, level: ServerRunLog["level"], message: string): Promise<ServerRunLog>;
+    listLogs(principal: ApiPrincipal, runId: string): Promise<ServerRunLog[]>;
+    addArtifact(artifact: Omit<ServerArtifact, "createdAt">): Promise<ServerArtifact>;
+    listArtifacts(principal: ApiPrincipal, runId: string): Promise<ServerArtifact[]>;
+    getArtifact(principal: ApiPrincipal, runId: string, artifactId: string): Promise<ServerArtifact | null>;
+    publishSkill(input: PublishSkillInput): Promise<ServerSkillRecord>;
+    listSkills(principal: ApiPrincipal): Promise<ServerSkillRecord[]>;
+    getSkill(principal: ApiPrincipal, slug: string): Promise<ServerSkillRecord | null>;
+    /**
+     * Metadata-only patch, guarded by the same optimistic concurrency as publish: the
+     * row's current revision_id must match `expectedRevisionId` or
+     * SkillRevisionConflictError is thrown (409), never a silent overwrite. The revision
+     * advances on every successful update (new content sha, number + 1). Returns null
+     * when the org has no skill by that slug, or when the row is tombstoned.
+     */
+    updateSkill(principal: ApiPrincipal, slug: string, patch: UpdateSkillPatch, expectedRevisionId?: string): Promise<ServerSkillRecord | null>;
+    /**
+     * Tombstone a skill instead of hard-deleting it (todos d061fcda): the row is stamped
+     * tombstoned_at + tombstone_purge_after (now + tombstoneWindowMs) and kept, so reads
+     * can answer 410 with the marker and a pulling client can reconcile, and the bundle
+     * survives until the purge. Returns the tombstoned record, or null when the org has
+     * no row by that slug. A second delete of an already-tombstoned slug returns the
+     * existing tombstone (idempotent; the window is not extended).
+     */
+    deleteSkill(principal: ApiPrincipal, slug: string, tombstoneWindowMs: number): Promise<ServerSkillRecord | null>;
+    /**
+     * Drop every tombstoned row whose window has expired, collecting the bundles nothing
+     * (live or tombstoned) references. Called on the read paths and by listSkills so the
+     * purge is lazy but does not wait for a slug to be read. Returns the purged records so
+     * the caller can discard their stored objects (S3).
+     */
+    purgeExpiredTombstones(principal: ApiPrincipal): Promise<ServerSkillRecord[]>;
+    getSkillBundle(principal: ApiPrincipal, sha256: string): Promise<ServerSkillBundle | null>;
+    pinSkill(principal: ApiPrincipal, slug: string, metadata?: Record<string, unknown>): Promise<ServerPin>;
+    /** False when this principal has no pin by that slug. */
+    unpinSkill(principal: ApiPrincipal, slug: string): Promise<boolean>;
+    listPins(principal: ApiPrincipal): Promise<ServerPin[]>;
+    listTags(principal: ApiPrincipal): Promise<string[]>;
+    listSkillsByTag(principal: ApiPrincipal, tag: string): Promise<ServerSkillRecord[]>;
+    listPinsByTag(principal: ApiPrincipal, tag: string): Promise<ServerPin[]>;
+    /**
+     * The slugs of the org's live (non-tombstoned) published skills. The tag
+     * routes use this to resolve merged-view precedence: a bundled skill whose
+     * slug a published row occupies must not resurface under a tag filter or in
+     * the tag list. A single-column scan of the (org_id, slug) primary key.
+     */
+    listPublishedSlugs(principal: ApiPrincipal): Promise<string[]>;
+}

package/dist/server/worker.d.ts

@@ -0,0 +1,4 @@
+#!/usr/bin/env bun
+import { ArtifactStorage } from "../sdk/storage.js";
+import type { SkillsProductStore } from "../sdk/storage.js";
+export declare function runWorkerOnce(store: SkillsProductStore, workerId?: string, storage?: ArtifactStorage): Promise<boolean>;

package/dist/storage.js

@@ -1,5 +1,35 @@
 // @bun
+var __create = Object.create;
+var __getProtoOf = Object.getPrototypeOf;
 var __defProp = Object.defineProperty;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+function __accessProp(key) {
+  return this[key];
+}
+var __toESMCache_node;
+var __toESMCache_esm;
+var __toESM = (mod, isNodeMode, target) => {
+  var canCache = mod != null && typeof mod === "object";
+  if (canCache) {
+    var cache = isNodeMode ? __toESMCache_node ??= new WeakMap : __toESMCache_esm ??= new WeakMap;
+    var cached = cache.get(mod);
+    if (cached)
+      return cached;
+  }
+  target = mod != null ? __create(__getProtoOf(mod)) : {};
+  const to = isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target;
+  for (let key of __getOwnPropNames(mod))
+    if (!__hasOwnProp.call(to, key))
+      __defProp(to, key, {
+        get: __accessProp.bind(mod, key),
+        enumerable: true
+      });
+  if (canCache)
+    cache.set(mod, to);
+  return to;
+};
+var __commonJS = (cb, mod) => () => (mod || cb((mod = { exports: {} }).exports, mod), mod.exports);
 var __returnValue = (v) => v;
 function __exportSetter(name, newValue) {
   this[name] = __returnValue.bind(null, newValue);
@@ -13,6 +43,8 @@ var __export = (target, all) => {
       set: __exportSetter.bind(all, name)
     });
 };
+var __esm = (fn, res) => () => (fn && (res = fn(fn = 0)), res);
+var __require = import.meta.require;
 
 // src/lib/native-storage.ts
 import { createHash, createHmac } from "crypto";
@@ -130,6 +162,11 @@ function normalizeConfigValue(key, value) {
 }
 var DATA_DIR_ENV = "HASNA_SKILLS_DIR";
 var INSTALLED_SKILLS_DIRNAME = "installed";
+var SKILLS_CACHE_DIRNAME = "skills";
+var LAYOUT_MIGRATION_RECORD = ".layout-migration.json";
+function isOwnerLayoutMigrated(appDir) {
+  return existsSync(join(appDir, SKILLS_CACHE_DIRNAME, LAYOUT_MIGRATION_RECORD));
+}
 function getDataDir() {
   const override = process.env[DATA_DIR_ENV];
   if (override) {
@@ -466,7 +503,7 @@ function getSkillsNativeStorageStatus(options = {}) {
   const s3BucketEnv = readStorageEnv(env, "s3Bucket");
   const targetDir = options.targetDir ?? process.cwd();
   return {
-    package: "open-skills",
+    package: "skills",
     tables: [...SKILLS_STORAGE_TABLES],
     env: {
       databaseUrl: SKILLS_NATIVE_STORAGE_ENV.databaseUrl,
@@ -638,7 +675,7 @@ function createSkillsSnapshotSyncRecord(snapshot, options = {}) {
     kind: "local-snapshot",
     id: options.id ?? "project-state",
     updatedAt: snapshot.exportedAt,
-    source: options.source ?? "open-skills",
+    source: options.source ?? "skills",
     payload: snapshot
   };
 }