@hasna/skills 0.1.59 → 0.1.61

package/bin/migrate.js

@@ -2,26 +2,74 @@
 // @bun
 
 // src/server/migrate.ts
-import { existsSync, readdirSync, readFileSync } from "fs";
-import { join } from "path";
+import { existsSync as existsSync3, readdirSync as readdirSync3, readFileSync as readFileSync3 } from "fs";
+import { join as join5 } from "path";
+
+// src/lib/retired-settings.ts
+var RETIRED_ENV_SUFFIXES = ["_STORAGE_MODE", "_DEPLOYMENT_MODE", "_CLOUD_MODE"];
+class RetiredSettingError extends Error {
+  code = "RETIRED_SETTING";
+  setting;
+  constructor(setting, message) {
+    super(message);
+    this.name = "RetiredSettingError";
+    this.setting = setting;
+  }
+}
+function isRetiredModeEnvVar(name, app) {
+  const upper = name.toUpperCase();
+  if (!upper.includes(app.toUpperCase()))
+    return false;
+  return RETIRED_ENV_SUFFIXES.some((suffix) => upper.endsWith(suffix));
+}
+function findRetiredModeEnvVars(env, app) {
+  const found = [];
+  for (const [name, value] of Object.entries(env)) {
+    if (value === undefined || value === "")
+      continue;
+    if (isRetiredModeEnvVar(name, app))
+      found.push({ name, value });
+  }
+  return found.sort((a, b) => a.name.localeCompare(b.name));
+}
+function assertNoRetiredModeEnvVars(env, options) {
+  const found = findRetiredModeEnvVars(env, options.app);
+  if (found.length === 0)
+    return;
+  const names = found.map((entry) => entry.name);
+  throw new RetiredSettingError(names[0], `${names.join(", ")} ${names.length === 1 ? "is" : "are"} no longer read. ` + "Deployment modes were removed: where a server keeps its data is decided by the " + `database it is given, not by a declared label. Set ${options.replacement} to a ` + "postgres:// URL to use PostgreSQL, or leave it unset for the on-box SQLite database. " + `Then unset ${names.join(" and ")}. ` + "Refused rather than ignored, because a discarded setting looks exactly like a " + "working one until something needs the data.");
+}
 
 // src/server/config.ts
-var DEFAULT_SELF_HOSTED_API_URL = "https://skills.md";
+var DATABASE_URL_ENV = "HASNA_SKILLS_DATABASE_URL";
+var SKILLS_ENV_NAMESPACE = "SKILLS";
 function resolveServerConfig(env = process.env) {
+  assertNoRetiredModeEnvVars(env, {
+    app: SKILLS_ENV_NAMESPACE,
+    replacement: DATABASE_URL_ENV
+  });
   const nodeEnv = env.NODE_ENV || "development";
+  const host = env.HOST || env.SKILLS_HOST || "0.0.0.0";
+  const port = parsePositiveInt(env.PORT || env.SKILLS_PORT, 8787);
   return {
-    host: env.HOST || env.SKILLS_HOST || "0.0.0.0",
-    port: parsePositiveInt(env.PORT || env.SKILLS_PORT, 8787),
-    databaseUrl: env.HASNA_SKILLS_DATABASE_URL || env.DATABASE_URL || undefined,
+    host,
+    port,
+    databaseUrl: env[DATABASE_URL_ENV] || env.DATABASE_URL || undefined,
     bootstrapApiKey: env.HASNA_SKILLS_BOOTSTRAP_API_KEY || undefined,
     artifactBucket: env.HASNA_SKILLS_S3_BUCKET || env.SKILLS_S3_BUCKET || undefined,
     artifactPrefix: normalizePrefix(env.HASNA_SKILLS_S3_PREFIX || env.SKILLS_S3_PREFIX || "skills/artifacts"),
     inlineWorker: env.HASNA_SKILLS_INLINE_WORKER === "1",
     requestBodyLimitBytes: parsePositiveInt(env.HASNA_SKILLS_REQUEST_BODY_LIMIT_BYTES, 1e6),
-    publicBaseUrl: (env.SKILLS_PUBLIC_BASE_URL || DEFAULT_SELF_HOSTED_API_URL).replace(/\/+$/, ""),
-    nodeEnv
+    skillBundleLimitBytes: parsePositiveInt(env.HASNA_SKILLS_BUNDLE_LIMIT_BYTES, 25000000),
+    publicBaseUrl: (env.SKILLS_PUBLIC_BASE_URL || localOrigin(host, port)).replace(/\/+$/, ""),
+    nodeEnv,
+    allowEphemeralStore: env.HASNA_SKILLS_ALLOW_EPHEMERAL_STORE === "1"
   };
 }
+function localOrigin(host, port) {
+  const hostname = host === "0.0.0.0" || host === "::" ? "localhost" : host;
+  return `http://${hostname.includes(":") ? `[${hostname}]` : hostname}:${port}`;
+}
 function parsePositiveInt(value, fallback) {
   const parsed = Number.parseInt(value ?? "", 10);
   return Number.isFinite(parsed) && parsed > 0 ? parsed : fallback;
@@ -30,40 +78,914 @@ function normalizePrefix(value) {
   return value.replace(/^\/+|\/+$/g, "") || "skills/artifacts";
 }
 
-// src/server/migrate.ts
-async function runMigrations(databaseUrl, migrationsDir = join(process.cwd(), "migrations")) {
-  if (!existsSync(migrationsDir))
-    throw new Error(`migrations directory not found: ${migrationsDir}`);
-  const bunWithSql = Bun;
-  const sql = new bunWithSql.SQL(databaseUrl, { max: 1 });
-  await sql.unsafe("CREATE TABLE IF NOT EXISTS schema_migrations (version text PRIMARY KEY, applied_at timestamptz NOT NULL DEFAULT now())");
-  const appliedRows = await sql`SELECT version FROM schema_migrations`;
-  const applied = new Set(appliedRows.map((row) => row.version));
-  const appliedNow = [];
-  for (const file of readdirSync(migrationsDir).filter((name) => name.endsWith(".sql")).sort()) {
-    const version = file.replace(/\.sql$/, "");
-    if (applied.has(version))
-      continue;
-    const sqlText = readFileSync(join(migrationsDir, file), "utf8");
-    await sql.unsafe("BEGIN");
+// src/server/database-url.ts
+import { isAbsolute, join as join2 } from "path";
+import { fileURLToPath } from "url";
+
+// src/lib/config.ts
+import { existsSync, readFileSync, writeFileSync, mkdirSync, copyFileSync, readdirSync, statSync } from "fs";
+import { join, dirname } from "path";
+import { homedir } from "os";
+function mergeDirectoryContents(sourceDir, targetDir) {
+  if (!existsSync(sourceDir))
+    return;
+  mkdirSync(targetDir, { recursive: true });
+  for (const entry of readdirSync(sourceDir)) {
+    const sourcePath = join(sourceDir, entry);
+    const targetPath = join(targetDir, entry);
     try {
-      await sql.unsafe(sqlText);
-      await sql`INSERT INTO schema_migrations (version) VALUES (${version})`;
-      await sql.unsafe("COMMIT");
-      appliedNow.push(version);
+      const sourceStat = statSync(sourcePath);
+      if (sourceStat.isDirectory()) {
+        mergeDirectoryContents(sourcePath, targetPath);
+        continue;
+      }
+      if (!existsSync(targetPath))
+        copyFileSync(sourcePath, targetPath);
+    } catch {}
+  }
+}
+var DATA_DIR_ENV = "HASNA_SKILLS_DIR";
+function getDataDir() {
+  const override = process.env[DATA_DIR_ENV];
+  if (override) {
+    try {
+      mkdirSync(override, { recursive: true });
+    } catch {}
+    return override;
+  }
+  const home = process.env["HOME"] || process.env["USERPROFILE"] || homedir();
+  const newDir = join(home, ".hasna", "skills");
+  const oldDir = join(home, ".skills");
+  const oldConfigFile = join(home, ".skillsrc");
+  mkdirSync(newDir, { recursive: true });
+  try {
+    mergeDirectoryContents(oldDir, newDir);
+  } catch {}
+  if (existsSync(oldConfigFile) && !existsSync(join(newDir, "config.json"))) {
+    try {
+      copyFileSync(oldConfigFile, join(newDir, "config.json"));
+    } catch {}
+  }
+  return newDir;
+}
+
+// src/server/database-url.ts
+var DEFAULT_SQLITE_FILENAME = "server.db";
+var SQLITE_MEMORY_PATH = ":memory:";
+var POSTGRES_SCHEMES = new Set(["postgres", "postgresql"]);
+var SQLITE_SCHEMES = new Set(["sqlite", "sqlite3", "file"]);
+var MEMORY_SCHEMES = new Set(["memory"]);
+var SQLITE_EXTENSIONS = [".db", ".sqlite", ".sqlite3", ".db3"];
+function defaultSqlitePath() {
+  return join2(getDataDir(), DEFAULT_SQLITE_FILENAME);
+}
+function resolveDatabaseTarget(raw) {
+  const value = raw?.trim();
+  if (!value) {
+    const path = defaultSqlitePath();
+    return { kind: "sqlite", path, durable: true, label: `sqlite (${path})` };
+  }
+  if (value === SQLITE_MEMORY_PATH) {
+    return { kind: "sqlite", path: SQLITE_MEMORY_PATH, durable: false, label: "sqlite (in-memory)" };
+  }
+  const schemeMatch = value.match(/^([a-z][a-z0-9+.-]+):/i);
+  const scheme = schemeMatch?.[1]?.toLowerCase();
+  if (scheme && POSTGRES_SCHEMES.has(scheme)) {
+    return { kind: "postgres", url: value, durable: true, label: "postgres" };
+  }
+  if (scheme && MEMORY_SCHEMES.has(scheme)) {
+    return { kind: "memory", durable: false, label: "memory (non-durable)" };
+  }
+  if (scheme && SQLITE_SCHEMES.has(scheme)) {
+    const path = sqlitePathFromUrl(value, scheme);
+    return path === SQLITE_MEMORY_PATH ? { kind: "sqlite", path, durable: false, label: "sqlite (in-memory)" } : { kind: "sqlite", path, durable: true, label: `sqlite (${path})` };
+  }
+  if (scheme) {
+    throw new Error(`unsupported database scheme "${scheme}:". Supported: postgres://, postgresql://, sqlite:, file:, ` + `an absolute or relative path to a .db/.sqlite file, ":memory:", or "memory:" (non-durable, tests only). ` + `Leave the setting empty to use the default SQLite database at ${defaultSqlitePath()}.`);
+  }
+  if (looksLikeSqlitePath(value)) {
+    const path = isAbsolute(value) ? value : join2(process.cwd(), value);
+    return { kind: "sqlite", path, durable: true, label: `sqlite (${path})` };
+  }
+  throw new Error(`could not resolve a database backend from "${value}". Use postgres://\u2026, sqlite:\u2026, an absolute or ` + `relative path ending in ${SQLITE_EXTENSIONS.join("/")}, ":memory:", or leave it empty for the ` + `default SQLite database at ${defaultSqlitePath()}.`);
+}
+function sqlitePathFromUrl(value, scheme) {
+  const rest = value.slice(scheme.length + 1).replace(/[?#].*$/, "");
+  if (rest.startsWith(SQLITE_MEMORY_PATH))
+    return SQLITE_MEMORY_PATH;
+  if (rest === "" || rest === "//") {
+    throw new Error(`"${value}" names no database file. Give a path (${scheme}:///var/lib/skills/server.db), ` + `or ":memory:" if a non-durable database is genuinely what you want. ` + "An empty path here usually means an unset variable in a templated URL.");
+  }
+  if (rest.startsWith("//")) {
+    if (!rest.startsWith("///")) {
+      const authority = rest.slice(2).split("/")[0];
+      throw new Error(`"${value}" has a host ("${authority}") where a path was expected. Remote SQLite files are not a thing; ` + `for an absolute path use ${scheme}:///${rest.slice(2)}, and for a relative one use ${scheme}:${rest.slice(2)}.`);
+    }
+    if (scheme === "file") {
+      try {
+        return fileURLToPath(new URL(value));
+      } catch {}
+    }
+    return rest.slice(2).replace(/^\/\/+/, "/");
+  }
+  return isAbsolute(rest) ? rest : join2(process.cwd(), rest);
+}
+function looksLikeSqlitePath(value) {
+  if (value.includes("/"))
+    return true;
+  return SQLITE_EXTENSIONS.some((extension) => value.toLowerCase().endsWith(extension));
+}
+
+// src/server/migrations-dir.ts
+import { existsSync as existsSync2 } from "fs";
+import { dirname as dirname2, join as join3 } from "path";
+var MIGRATION_DIALECTS = ["postgres", "sqlite"];
+var MAX_WALK_UP = 6;
+function findMigrationsRoot(startDirs = defaultStartDirs()) {
+  for (const start of startDirs) {
+    let dir = start;
+    for (let level = 0;level < MAX_WALK_UP; level += 1) {
+      const candidate = join3(dir, "migrations");
+      if (MIGRATION_DIALECTS.some((dialect) => existsSync2(join3(candidate, dialect))))
+        return candidate;
+      const parent = dirname2(dir);
+      if (parent === dir)
+        break;
+      dir = parent;
+    }
+  }
+  return null;
+}
+function resolveMigrationsDir(dialect, root = findMigrationsRoot()) {
+  if (!root) {
+    throw new Error(`could not locate the migrations directory for dialect "${dialect}". ` + `Expected a migrations/${dialect}/ folder alongside the package root.`);
+  }
+  const dir = join3(root, dialect);
+  if (!existsSync2(dir)) {
+    throw new Error(`migrations directory not found: ${dir}`);
+  }
+  return dir;
+}
+function defaultStartDirs() {
+  const dirs = [import.meta.dir];
+  const cwd = process.cwd();
+  if (cwd && cwd !== import.meta.dir)
+    dirs.push(cwd);
+  return dirs;
+}
+
+// src/server/sqlite-store.ts
+import { Database } from "bun:sqlite";
+import { randomUUID as randomUUID2 } from "crypto";
+import { mkdirSync as mkdirSync2, readFileSync as readFileSync2, readdirSync as readdirSync2 } from "fs";
+import { dirname as dirname3, join as join4 } from "path";
+
+// src/server/auth.ts
+import { createHash } from "crypto";
+function hashApiKey(token) {
+  return createHash("sha256").update(token).digest("hex");
+}
+function publicPrincipal(partial = {}) {
+  return {
+    apiKeyId: partial.apiKeyId || "key_dev",
+    orgId: partial.orgId || "org_dev",
+    orgSlug: partial.orgSlug || "dev",
+    orgName: partial.orgName || "Development",
+    userId: partial.userId || "user_dev",
+    email: partial.email || "dev@example.com",
+    role: partial.role || "owner",
+    scopes: partial.scopes || ["skills:read", "runs:write"]
+  };
+}
+
+// src/server/rows.ts
+import { randomUUID } from "crypto";
+
+// src/lib/skill-bundle.ts
+var ANY_SEGMENT_EXCLUDES = new Set([
+  ".git",
+  ".ds_store",
+  ".system",
+  "node_modules",
+  ".aws",
+  ".ssh",
+  ".gnupg",
+  ".docker"
+]);
+var ROOT_EXCLUDES = new Set(["dist", "build", ".turbo"]);
+var CREDENTIAL_FILENAMES = new Set([
+  ".npmrc",
+  ".pypirc",
+  ".netrc",
+  ".envrc",
+  ".pgpass",
+  ".git-credentials",
+  "credentials",
+  "id_rsa",
+  "id_dsa",
+  "id_ecdsa",
+  "id_ed25519"
+]);
+var ENV_TEMPLATE_NAMES = new Set([".env.example", ".env.sample", ".env.template", ".env.dist"]);
+var NON_DOTENV_EXTENSIONS = new Set([
+  "ts",
+  "tsx",
+  "mts",
+  "cts",
+  "js",
+  "jsx",
+  "mjs",
+  "cjs",
+  "json",
+  "jsonc",
+  "json5",
+  "py",
+  "rb",
+  "go",
+  "rs",
+  "java",
+  "kt",
+  "kts",
+  "swift",
+  "c",
+  "h",
+  "cc",
+  "cpp",
+  "hpp",
+  "cs",
+  "php",
+  "sh",
+  "bash",
+  "zsh",
+  "fish",
+  "ps1",
+  "bat",
+  "cmd",
+  "lua",
+  "pl",
+  "pm",
+  "r",
+  "jl",
+  "dart",
+  "ex",
+  "exs",
+  "scala",
+  "clj",
+  "cljs",
+  "groovy",
+  "gradle",
+  "vb",
+  "fs",
+  "yaml",
+  "yml",
+  "toml",
+  "ini",
+  "xml",
+  "csv",
+  "tsv",
+  "html",
+  "htm",
+  "css",
+  "scss",
+  "sass",
+  "less",
+  "md",
+  "mdx",
+  "txt",
+  "rst",
+  "adoc",
+  "sql",
+  "graphql",
+  "gql",
+  "proto",
+  "d",
+  "png",
+  "jpg",
+  "jpeg",
+  "gif",
+  "svg",
+  "webp",
+  "ico",
+  "bmp",
+  "pdf",
+  "woff",
+  "woff2",
+  "ttf",
+  "otf",
+  "eot",
+  "mp3",
+  "mp4",
+  "wav",
+  "webm",
+  "zip",
+  "gz",
+  "tar",
+  "wasm"
+]);
+function ownBytes(view) {
+  const source = view instanceof ArrayBuffer ? new Uint8Array(view) : view;
+  const out = new Uint8Array(new ArrayBuffer(source.byteLength));
+  out.set(source);
+  return out;
+}
+
+// src/server/rows.ts
+function nowIso() {
+  return new Date().toISOString();
+}
+function normalizeLimit(limit) {
+  return Number.isFinite(limit) ? Math.max(0, Math.trunc(limit)) : 0;
+}
+function runId() {
+  return `run_${Date.now().toString(36)}_${randomUUID().slice(0, 8)}`;
+}
+function rowToRun(row) {
+  return {
+    id: String(row.id),
+    orgId: String(row.org_id),
+    userId: String(row.user_id),
+    skill: String(row.skill_slug),
+    requestedSlug: String(row.requested_slug),
+    status: String(row.status),
+    input: parseJsonObject(row.input_json),
+    args: parseJsonArray(row.args_json),
+    ...typeof row.idempotency_key === "string" ? { idempotencyKey: row.idempotency_key } : {},
+    correlationId: String(row.correlation_id),
+    costCents: Number(row.cost_cents ?? 0),
+    ...typeof row.output_type === "string" ? { outputType: row.output_type } : {},
+    ...typeof row.output_preview === "string" ? { outputPreview: row.output_preview } : {},
+    ...typeof row.error_code === "string" ? { errorCode: row.error_code } : {},
+    ...typeof row.error_message === "string" ? { errorMessage: row.error_message } : {},
+    createdAt: dateString(row.created_at),
+    ...row.started_at ? { startedAt: dateString(row.started_at) } : {},
+    ...row.completed_at ? { completedAt: dateString(row.completed_at) } : {}
+  };
+}
+function rowToLog(row) {
+  return {
+    runId: String(row.run_id),
+    sequence: Number(row.sequence),
+    level: String(row.level),
+    message: String(row.message),
+    createdAt: dateString(row.created_at)
+  };
+}
+function rowToArtifact(row) {
+  return {
+    id: String(row.id),
+    runId: String(row.run_id),
+    orgId: String(row.org_id),
+    fileName: String(row.file_name),
+    relativePath: String(row.relative_path),
+    contentType: String(row.content_type),
+    byteSize: Number(row.byte_size),
+    sha256: String(row.sha256),
+    storageKind: String(row.storage_kind),
+    ...typeof row.storage_key === "string" ? { storageKey: row.storage_key } : {},
+    ...typeof row.body_text === "string" ? { bodyText: row.body_text } : {},
+    createdAt: dateString(row.created_at)
+  };
+}
+function rowToSkill(row) {
+  return {
+    orgId: String(row.org_id),
+    slug: String(row.slug),
+    displayName: String(row.display_name),
+    description: String(row.description ?? ""),
+    category: String(row.category),
+    tags: parseJsonArray(row.tags_json),
+    source: String(row.source),
+    kind: String(row.kind) === "instruction" ? "instruction" : "executable",
+    ...typeof row.version === "string" ? { version: row.version } : {},
+    ...typeof row.skill_md === "string" ? { skillMd: row.skill_md } : {},
+    ...typeof row.bundle_sha256 === "string" ? { bundleSha256: row.bundle_sha256 } : {},
+    ...row.bundle_byte_size === null || row.bundle_byte_size === undefined ? {} : { bundleByteSize: Number(row.bundle_byte_size) },
+    ...typeof row.published_by_user_id === "string" ? { publishedByUserId: row.published_by_user_id } : {},
+    createdAt: dateString(row.created_at),
+    updatedAt: dateString(row.updated_at)
+  };
+}
+function rowToSkillBundle(row) {
+  return {
+    orgId: String(row.org_id),
+    sha256: String(row.sha256),
+    byteSize: Number(row.byte_size),
+    contentType: String(row.content_type),
+    storageKind: String(row.storage_kind),
+    ...typeof row.storage_key === "string" ? { storageKey: row.storage_key } : {},
+    ...toBytes(row.body_blob) ? { bytes: toBytes(row.body_blob) } : {},
+    createdAt: dateString(row.created_at)
+  };
+}
+function toBytes(value) {
+  if (value == null)
+    return null;
+  if (value instanceof Uint8Array)
+    return ownBytes(value);
+  if (value instanceof ArrayBuffer)
+    return ownBytes(value);
+  return null;
+}
+function parseJsonObject(value) {
+  if (value && typeof value === "object" && !Array.isArray(value))
+    return value;
+  if (typeof value === "string") {
+    try {
+      const parsed = JSON.parse(value);
+      return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : {};
+    } catch {}
+  }
+  return {};
+}
+function parseJsonArray(value) {
+  const parsed = typeof value === "string" ? safeParse(value) : value;
+  return Array.isArray(parsed) ? parsed.map(String) : [];
+}
+function safeParse(value) {
+  try {
+    return JSON.parse(value);
+  } catch {
+    return;
+  }
+}
+function dateString(value) {
+  if (value instanceof Date)
+    return value.toISOString();
+  return String(value);
+}
+
+// src/server/sqlite-store.ts
+var CLAIM_ATTEMPTS = 8;
+var CLAIMABLE_STATUSES = ["queued", "retrying"];
+var LAST_USED_RESOLUTION_MS = 60000;
+
+class SqliteSkillsStore {
+  backend;
+  db;
+  closed = false;
+  constructor(path = SQLITE_MEMORY_PATH, options = {}) {
+    const inMemory = path === SQLITE_MEMORY_PATH;
+    if (!inMemory)
+      mkdirSync2(dirname3(path), { recursive: true });
+    this.db = openDatabase(path);
+    this.db.exec(`PRAGMA busy_timeout = ${Math.max(0, options.busyTimeoutMs ?? 5000)}`);
+    if (!inMemory)
+      enableWalMode(this.db);
+    this.db.exec("PRAGMA foreign_keys = ON");
+    this.db.exec("PRAGMA synchronous = NORMAL");
+    if (options.migrate !== false) {
+      applySqliteMigrations(this.db, options.migrationsDir);
+    }
+    this.backend = {
+      kind: "sqlite",
+      durable: !inMemory,
+      label: inMemory ? "sqlite (in-memory)" : `sqlite (${path})`
+    };
+  }
+  get database() {
+    return this.db;
+  }
+  async close() {
+    if (this.closed)
+      return;
+    this.closed = true;
+    this.db.close(false);
+  }
+  async ensureBootstrapApiKey(token, principal) {
+    const resolved = publicPrincipal(principal);
+    this.db.transaction(() => {
+      this.db.run(`INSERT INTO organizations (id, slug, name) VALUES (?, ?, ?)
+         ON CONFLICT (id) DO UPDATE SET slug = excluded.slug, name = excluded.name`, [resolved.orgId, resolved.orgSlug, resolved.orgName]);
+      this.db.run(`INSERT INTO users (id, email, name) VALUES (?, ?, ?)
+         ON CONFLICT (id) DO UPDATE SET email = excluded.email`, [resolved.userId, resolved.email, resolved.email]);
+      this.db.run(`INSERT INTO organization_members (org_id, user_id, role) VALUES (?, ?, ?)
+         ON CONFLICT (org_id, user_id) DO UPDATE SET role = excluded.role`, [resolved.orgId, resolved.userId, resolved.role]);
+      this.db.run(`INSERT INTO api_keys (id, org_id, user_id, name, key_hash, scopes_json)
+         VALUES (?, ?, ?, ?, ?, ?)
+         ON CONFLICT (key_hash) DO NOTHING`, [resolved.apiKeyId, resolved.orgId, resolved.userId, "bootstrap", hashApiKey(token), JSON.stringify(resolved.scopes)]);
+    })();
+  }
+  async authenticateApiKeyHash(hash) {
+    const row = this.get(`SELECT k.id AS api_key_id, k.scopes_json, k.last_used_at, o.id AS org_id, o.slug AS org_slug, o.name AS org_name,
+              u.id AS user_id, u.email, m.role
+       FROM api_keys k
+       JOIN organizations o ON o.id = k.org_id
+       JOIN users u ON u.id = k.user_id
+       LEFT JOIN organization_members m ON m.org_id = k.org_id AND m.user_id = k.user_id
+       WHERE k.key_hash = ? AND k.revoked_at IS NULL
+       LIMIT 1`, [hash]);
+    if (!row)
+      return null;
+    const lastUsed = typeof row.last_used_at === "string" ? Date.parse(row.last_used_at) : Number.NaN;
+    if (!Number.isFinite(lastUsed) || Date.now() - lastUsed >= LAST_USED_RESOLUTION_MS) {
+      this.db.run("UPDATE api_keys SET last_used_at = ? WHERE id = ?", [nowIso(), String(row.api_key_id)]);
+    }
+    return {
+      apiKeyId: String(row.api_key_id),
+      orgId: String(row.org_id),
+      orgSlug: String(row.org_slug),
+      orgName: String(row.org_name),
+      userId: String(row.user_id),
+      email: String(row.email),
+      role: typeof row.role === "string" ? row.role : "member",
+      scopes: parseScopes(row.scopes_json)
+    };
+  }
+  async createRun(input) {
+    if (input.idempotencyKey) {
+      const existing = this.get("SELECT * FROM skills_runs WHERE org_id = ? AND idempotency_key = ? LIMIT 1", [input.principal.orgId, input.idempotencyKey]);
+      if (existing)
+        return rowToRun(existing);
+    }
+    const row = this.get(`INSERT INTO skills_runs (id, org_id, user_id, skill_slug, requested_slug, status, input_json, args_json, idempotency_key, correlation_id, created_at)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+       RETURNING *`, [
+      runId(),
+      input.principal.orgId,
+      input.principal.userId,
+      input.slug,
+      input.slug,
+      "queued",
+      JSON.stringify(input.input),
+      JSON.stringify(input.args),
+      input.idempotencyKey ?? null,
+      randomUUID2(),
+      nowIso()
+    ]);
+    return rowToRun(row);
+  }
+  async listRuns(principal, limit) {
+    return this.all("SELECT * FROM skills_runs WHERE org_id = ? ORDER BY created_at DESC, rowid DESC LIMIT ?", [principal.orgId, normalizeLimit(limit)]).map(rowToRun);
+  }
+  async getRun(principal, id) {
+    const row = this.get("SELECT * FROM skills_runs WHERE id = ? AND org_id = ? LIMIT 1", [id, principal.orgId]);
+    return row ? rowToRun(row) : null;
+  }
+  async claimNextRun(input) {
+    const lost = new Set;
+    for (let attempt = 0;attempt < CLAIM_ATTEMPTS; attempt += 1) {
+      const claimed = this.claimOnce(input.workerId, lost);
+      if (claimed === "empty")
+        return null;
+      if (claimed)
+        return claimed;
+    }
+    return null;
+  }
+  claimOnce(workerId, lost) {
+    this.db.exec("BEGIN IMMEDIATE");
+    try {
+      const excluded = [...lost];
+      const candidate = this.get(`SELECT id FROM skills_runs
+         WHERE status IN (${CLAIMABLE_STATUSES.map(() => "?").join(", ")})
+           ${excluded.length ? `AND id NOT IN (${excluded.map(() => "?").join(", ")})` : ""}
+         ORDER BY created_at ASC, rowid ASC
+         LIMIT 1`, [...CLAIMABLE_STATUSES, ...excluded]);
+      if (!candidate) {
+        this.db.exec("COMMIT");
+        return "empty";
+      }
+      const id = String(candidate.id);
+      const now = nowIso();
+      const result = this.db.run(`UPDATE skills_runs
+         SET status = 'running', started_at = COALESCE(started_at, ?), locked_by = ?, locked_at = ?
+         WHERE id = ? AND status IN (${CLAIMABLE_STATUSES.map(() => "?").join(", ")})`, [now, workerId, now, id, ...CLAIMABLE_STATUSES]);
+      if (result.changes !== 1) {
+        this.db.exec("ROLLBACK");
+        lost.add(id);
+        return null;
+      }
+      const row = this.get("SELECT * FROM skills_runs WHERE id = ? LIMIT 1", [id]);
+      if (!row) {
+        this.db.exec("ROLLBACK");
+        throw new Error(`claimed run ${id} vanished within its own transaction; refusing to report a lost claim as an empty queue`);
+      }
+      this.db.exec("COMMIT");
+      return rowToRun(row);
     } catch (error) {
-      await sql.unsafe("ROLLBACK");
+      this.rollbackQuietly();
       throw error;
     }
   }
+  async updateRun(id, patch) {
+    const current = this.get("SELECT * FROM skills_runs WHERE id = ? LIMIT 1", [id]);
+    if (!current)
+      return null;
+    const run = { ...rowToRun(current), ...patch };
+    const row = this.get(`UPDATE skills_runs
+       SET status = ?, output_type = ?, output_preview = ?, error_code = ?, error_message = ?, started_at = ?, completed_at = ?
+       WHERE id = ?
+       RETURNING *`, [
+      run.status,
+      run.outputType ?? null,
+      run.outputPreview ?? null,
+      run.errorCode ?? null,
+      run.errorMessage ?? null,
+      run.startedAt ?? null,
+      run.completedAt ?? null,
+      id
+    ]);
+    return row ? rowToRun(row) : null;
+  }
+  async appendLog(id, orgId, level, message) {
+    const row = this.get(`INSERT INTO skills_run_logs (run_id, org_id, sequence, level, message, created_at)
+       VALUES (?, ?, (SELECT COALESCE(MAX(sequence), 0) + 1 FROM skills_run_logs WHERE run_id = ?), ?, ?, ?)
+       RETURNING *`, [id, orgId, id, level, message, nowIso()]);
+    return rowToLog(row);
+  }
+  async listLogs(principal, id) {
+    return this.all(`SELECT l.* FROM skills_run_logs l
+       JOIN skills_runs r ON r.id = l.run_id AND r.org_id = ?
+       WHERE l.run_id = ?
+       ORDER BY l.sequence ASC`, [principal.orgId, id]).map(rowToLog);
+  }
+  async addArtifact(artifact) {
+    const row = this.get(`INSERT INTO skills_artifacts (id, run_id, org_id, file_name, relative_path, content_type, byte_size, sha256, storage_kind, storage_key, body_text, created_at)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+       RETURNING *`, [
+      artifact.id,
+      artifact.runId,
+      artifact.orgId,
+      artifact.fileName,
+      artifact.relativePath,
+      artifact.contentType,
+      artifact.byteSize,
+      artifact.sha256,
+      artifact.storageKind,
+      artifact.storageKey ?? null,
+      artifact.bodyText ?? null,
+      nowIso()
+    ]);
+    return rowToArtifact(row);
+  }
+  async listArtifacts(principal, id) {
+    return this.all(`SELECT a.* FROM skills_artifacts a
+       JOIN skills_runs r ON r.id = a.run_id AND r.org_id = ?
+       WHERE a.run_id = ?
+       ORDER BY a.created_at ASC, a.rowid ASC`, [principal.orgId, id]).map(rowToArtifact);
+  }
+  async getArtifact(principal, id, artifact) {
+    const row = this.get(`SELECT a.* FROM skills_artifacts a
+       JOIN skills_runs r ON r.id = a.run_id AND r.org_id = ?
+       WHERE a.run_id = ? AND a.id = ?
+       LIMIT 1`, [principal.orgId, id, artifact]);
+    return row ? rowToArtifact(row) : null;
+  }
+  async publishSkill(input) {
+    const orgId = input.principal.orgId;
+    const now = nowIso();
+    return this.db.transaction(() => {
+      const previous = this.get("SELECT bundle_sha256 FROM skills_registry WHERE org_id = ? AND slug = ?", [orgId, input.slug]);
+      const previousSha = typeof previous?.bundle_sha256 === "string" ? previous.bundle_sha256 : null;
+      if (input.bundle) {
+        this.db.run(`INSERT INTO skills_bundles (org_id, sha256, byte_size, content_type, storage_kind, storage_key, body_blob, created_at)
+           VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+           ON CONFLICT (org_id, sha256) DO UPDATE SET
+             byte_size = excluded.byte_size,
+             content_type = excluded.content_type,
+             storage_kind = excluded.storage_kind,
+             storage_key = excluded.storage_key,
+             body_blob = excluded.body_blob`, [
+          orgId,
+          input.bundle.sha256,
+          input.bundle.byteSize,
+          input.bundle.contentType,
+          input.bundle.storageKind,
+          input.bundle.storageKey ?? null,
+          input.bundle.bytes ?? null,
+          now
+        ]);
+      }
+      const row = this.get(`INSERT INTO skills_registry (org_id, slug, display_name, description, category, tags_json, source, kind, version, skill_md,
+                                      bundle_sha256, bundle_byte_size, published_by_user_id, created_at, updated_at)
+         VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+         ON CONFLICT (org_id, slug) DO UPDATE SET
+           display_name = excluded.display_name,
+           description = excluded.description,
+           category = excluded.category,
+           tags_json = excluded.tags_json,
+           source = excluded.source,
+           kind = excluded.kind,
+           version = excluded.version,
+           skill_md = excluded.skill_md,
+           -- COALESCE, not a straight assignment. A publish that carries no bundle is a
+           -- metadata update, not an instruction to discard the stored one: the plain
+           -- assignment nulled bundle_sha256 and then handed the old digest to orphan
+           -- collection, so re-publishing metadata over an existing skill deleted its
+           -- tarball and left every client with a 404.
+           bundle_sha256 = COALESCE(excluded.bundle_sha256, skills_registry.bundle_sha256),
+           bundle_byte_size = COALESCE(excluded.bundle_byte_size, skills_registry.bundle_byte_size),
+           published_by_user_id = excluded.published_by_user_id,
+           updated_at = excluded.updated_at
+         RETURNING *`, [
+        orgId,
+        input.slug,
+        input.displayName,
+        input.description,
+        input.category,
+        JSON.stringify(input.tags),
+        input.source,
+        input.kind,
+        input.version ?? null,
+        input.skillMd ?? null,
+        input.bundle?.sha256 ?? null,
+        input.bundle?.byteSize ?? null,
+        input.principal.userId,
+        now,
+        now
+      ]);
+      if (previousSha && input.bundle && previousSha !== input.bundle.sha256)
+        this.collectOrphanBundle(orgId, previousSha);
+      return rowToSkill(row);
+    })();
+  }
+  async listSkills(principal) {
+    return this.all("SELECT * FROM skills_registry WHERE org_id = ? ORDER BY slug ASC", [principal.orgId]).map(rowToSkill);
+  }
+  async getSkill(principal, slug) {
+    const row = this.get("SELECT * FROM skills_registry WHERE org_id = ? AND slug = ? LIMIT 1", [principal.orgId, slug]);
+    return row ? rowToSkill(row) : null;
+  }
+  async updateSkill(principal, slug, patch) {
+    const current = await this.getSkill(principal, slug);
+    if (!current)
+      return null;
+    const next = { ...current, ...patch };
+    const row = this.get(`UPDATE skills_registry
+       SET display_name = ?, description = ?, category = ?, tags_json = ?, kind = ?, version = ?, skill_md = ?, updated_at = ?
+       WHERE org_id = ? AND slug = ?
+       RETURNING *`, [
+      next.displayName,
+      next.description,
+      next.category,
+      JSON.stringify(next.tags),
+      next.kind,
+      next.version ?? null,
+      next.skillMd ?? null,
+      nowIso(),
+      principal.orgId,
+      slug
+    ]);
+    return row ? rowToSkill(row) : null;
+  }
+  async deleteSkill(principal, slug) {
+    return this.db.transaction(() => {
+      const existing = this.get("SELECT bundle_sha256 FROM skills_registry WHERE org_id = ? AND slug = ?", [principal.orgId, slug]);
+      if (!existing)
+        return false;
+      this.db.run("DELETE FROM skills_registry WHERE org_id = ? AND slug = ?", [principal.orgId, slug]);
+      if (typeof existing.bundle_sha256 === "string")
+        this.collectOrphanBundle(principal.orgId, existing.bundle_sha256);
+      return true;
+    })();
+  }
+  async getSkillBundle(principal, sha256) {
+    const row = this.get("SELECT * FROM skills_bundles WHERE org_id = ? AND sha256 = ? LIMIT 1", [principal.orgId, sha256]);
+    return row ? rowToSkillBundle(row) : null;
+  }
+  collectOrphanBundle(orgId, sha256) {
+    const referenced = this.get("SELECT 1 AS present FROM skills_registry WHERE org_id = ? AND bundle_sha256 = ? LIMIT 1", [orgId, sha256]);
+    if (referenced)
+      return;
+    this.db.run("DELETE FROM skills_bundles WHERE org_id = ? AND sha256 = ?", [orgId, sha256]);
+  }
+  get(sql, params) {
+    return this.db.query(sql).get(...params) ?? null;
+  }
+  all(sql, params) {
+    return this.db.query(sql).all(...params);
+  }
+  rollbackQuietly() {
+    try {
+      this.db.exec("ROLLBACK");
+    } catch {}
+  }
+}
+function applySqliteMigrations(db, migrationsDir = resolveMigrationsDir("sqlite")) {
+  db.exec(`CREATE TABLE IF NOT EXISTS schema_migrations (
+       version text PRIMARY KEY,
+       applied_at text NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now'))
+     )`);
+  const files = readdirSync2(migrationsDir).filter((name) => name.endsWith(".sql")).sort();
+  if (files.length === 0) {
+    throw new Error(`no .sql migrations found in ${migrationsDir}`);
+  }
+  const appliedNow = [];
+  for (const file of files) {
+    const version = file.replace(/\.sql$/, "");
+    const text = readFileSync2(join4(migrationsDir, file), "utf8");
+    const apply = db.transaction(() => {
+      const already = db.query("SELECT 1 AS present FROM schema_migrations WHERE version = ? LIMIT 1").get(version);
+      if (already)
+        return false;
+      db.exec(text);
+      db.run("INSERT INTO schema_migrations (version) VALUES (?)", [version]);
+      return true;
+    });
+    if (apply.immediate())
+      appliedNow.push(version);
+  }
   return appliedNow;
 }
+function enableWalMode(db, attempts = 50, pauseMs = 10) {
+  for (let attempt = 0;attempt < attempts; attempt += 1) {
+    if (journalMode(db) === "wal")
+      return true;
+    try {
+      if (String(db.query("PRAGMA journal_mode = WAL").get()?.journal_mode).toLowerCase() === "wal") {
+        return true;
+      }
+    } catch {}
+    Bun.sleepSync(pauseMs);
+  }
+  return false;
+}
+function journalMode(db) {
+  try {
+    return String(db.query("PRAGMA journal_mode").get()?.journal_mode ?? "").toLowerCase();
+  } catch {
+    return "";
+  }
+}
+function openDatabase(path) {
+  try {
+    return new Database(path, { create: true, readwrite: true });
+  } catch (error) {
+    const reason = error instanceof Error ? error.message : String(error);
+    throw new Error(`cannot open the skills database at ${path}: ${reason}. ` + "Check that the directory exists and is writable. Set HASNA_SKILLS_DATABASE_URL to choose a " + "different path or a postgres:// URL, or HASNA_SKILLS_DIR to relocate the whole data directory.", { cause: error });
+  }
+}
+function parseScopes(value) {
+  if (Array.isArray(value))
+    return value.map(String);
+  if (typeof value !== "string")
+    return [];
+  try {
+    const parsed = JSON.parse(value);
+    return Array.isArray(parsed) ? parsed.map(String) : [];
+  } catch {
+    return [];
+  }
+}
+
+// src/server/migrate.ts
+async function runMigrations(databaseUrl, migrationsDir) {
+  const target = resolveDatabaseTarget(databaseUrl);
+  if (!target.durable) {
+    throw new Error(`refusing to migrate ${target.label}: it does not outlive this process, so migrating it accomplishes nothing. ` + "Configure a sqlite file path or a postgres:// URL.");
+  }
+  if (target.kind === "sqlite") {
+    const store = new SqliteSkillsStore(target.path, { migrate: false, ...migrationsDir ? { migrationsDir } : {} });
+    try {
+      const applied = applySqliteMigrations(store.database, migrationsDir ?? resolveMigrationsDir("sqlite"));
+      return { backend: "sqlite", applied };
+    } finally {
+      await store.close();
+    }
+  }
+  return { backend: "postgres", applied: await runPostgresMigrations(target.url, migrationsDir ?? resolveMigrationsDir("postgres")) };
+}
+async function runPostgresMigrations(databaseUrl, migrationsDir) {
+  if (!existsSync3(migrationsDir))
+    throw new Error(`migrations directory not found: ${migrationsDir}`);
+  const bunWithSql = Bun;
+  const sql = new bunWithSql.SQL(databaseUrl, { max: 1 });
+  try {
+    await sql.unsafe("CREATE TABLE IF NOT EXISTS schema_migrations (version text PRIMARY KEY, applied_at timestamptz NOT NULL DEFAULT now())");
+    const appliedRows = await sql`SELECT version FROM schema_migrations`;
+    const applied = new Set(appliedRows.map((row) => row.version));
+    const appliedNow = [];
+    const files = readdirSync3(migrationsDir).filter((name) => name.endsWith(".sql")).sort();
+    if (files.length === 0)
+      throw new Error(`no .sql migrations found in ${migrationsDir}`);
+    for (const file of files) {
+      const version = file.replace(/\.sql$/, "");
+      if (applied.has(version))
+        continue;
+      const sqlText = readFileSync3(join5(migrationsDir, file), "utf8");
+      await sql.unsafe("BEGIN");
+      try {
+        await sql.unsafe(sqlText);
+        await sql`INSERT INTO schema_migrations (version) VALUES (${version})`;
+        await sql.unsafe("COMMIT");
+        appliedNow.push(version);
+      } catch (error) {
+        await sql.unsafe("ROLLBACK");
+        throw error;
+      }
+    }
+    return appliedNow;
+  } finally {
+    await sql.close?.();
+  }
+}
 if (import.meta.main) {
   const config = resolveServerConfig();
-  if (!config.databaseUrl)
-    throw new Error("HASNA_SKILLS_DATABASE_URL or DATABASE_URL is required for migrations");
-  const applied = await runMigrations(config.databaseUrl);
-  console.log(JSON.stringify({ applied, count: applied.length }, null, 2));
+  if (!config.databaseUrl) {
+    throw new Error("HASNA_SKILLS_DATABASE_URL or DATABASE_URL is required for migrations. " + "SQLite databases migrate themselves when the server opens them, so there is nothing to do here " + "unless you are naming a target explicitly.");
+  }
+  const result = await runMigrations(config.databaseUrl);
+  console.log(JSON.stringify({ ...result, count: result.applied.length }, null, 2));
 }
 export {
   runMigrations