@hasna/skills 0.1.43 → 0.1.45

package/dist/storage.js

@@ -0,0 +1,854 @@
+// @bun
+var __defProp = Object.defineProperty;
+var __returnValue = (v) => v;
+function __exportSetter(name, newValue) {
+  this[name] = __returnValue.bind(null, newValue);
+}
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, {
+      get: all[name],
+      enumerable: true,
+      configurable: true,
+      set: __exportSetter.bind(all, name)
+    });
+};
+
+// src/lib/native-storage.ts
+import { createHash, createHmac } from "crypto";
+import {
+  existsSync as existsSync3,
+  mkdirSync as mkdirSync3,
+  readFileSync as readFileSync3,
+  readdirSync,
+  statSync,
+  writeFileSync as writeFileSync3
+} from "fs";
+import { dirname as dirname2, join as join3, normalize, relative, sep } from "path";
+
+// src/lib/config.ts
+import { existsSync, readFileSync, writeFileSync, mkdirSync, copyFileSync } from "fs";
+import { join, dirname } from "path";
+import { homedir } from "os";
+var ENUM_KEYS = {
+  defaultAgent: ["claude", "codex", "gemini", "pi", "opencode", "all"],
+  defaultScope: ["global", "project"],
+  format: ["compact", "json", "csv"]
+};
+var STRING_KEYS = ["apiUrl"];
+var MODE_VALUES = ["local", "hosted"];
+var MODE_ALIASES = {
+  local: "local",
+  offline: "local",
+  hosted: "hosted",
+  remote: "hosted",
+  "skills.md": "hosted",
+  skillsmd: "hosted"
+};
+function validKeys() {
+  return ["mode", ...Object.keys(ENUM_KEYS), ...STRING_KEYS];
+}
+function allowedValues(key) {
+  if (key === "mode")
+    return MODE_VALUES;
+  return ENUM_KEYS[key];
+}
+function normalizeConfigValue(key, value) {
+  if (typeof value !== "string")
+    return;
+  if (key === "mode")
+    return MODE_ALIASES[value.trim().toLowerCase()];
+  const allowed = allowedValues(key);
+  if (allowed)
+    return allowed.includes(value) ? value : undefined;
+  if (key === "apiUrl") {
+    try {
+      const url = new URL(value);
+      if (url.protocol !== "http:" && url.protocol !== "https:")
+        return;
+      return value.replace(/\/+$/, "");
+    } catch {
+      return;
+    }
+  }
+  return;
+}
+function getDataDir() {
+  const home = process.env["HOME"] || process.env["USERPROFILE"] || homedir();
+  const newDir = join(home, ".hasna", "skills");
+  const oldConfigFile = join(home, ".skillsrc");
+  if (existsSync(oldConfigFile) && !existsSync(join(newDir, "config.json"))) {
+    mkdirSync(newDir, { recursive: true });
+    try {
+      copyFileSync(oldConfigFile, join(newDir, "config.json"));
+    } catch {}
+  }
+  mkdirSync(newDir, { recursive: true });
+  return newDir;
+}
+function getConfigPath(scope) {
+  if (scope === "global") {
+    return join(getDataDir(), "config.json");
+  }
+  return join(process.cwd(), "skills.config.json");
+}
+function readConfigFile(path) {
+  if (!existsSync(path))
+    return {};
+  try {
+    const raw = readFileSync(path, "utf-8");
+    const parsed = JSON.parse(raw);
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed))
+      return {};
+    const config = {};
+    for (const key of validKeys()) {
+      const value = normalizeConfigValue(key, parsed[key]);
+      if (value !== undefined)
+        config[key] = value;
+    }
+    return config;
+  } catch {
+    return {};
+  }
+}
+function loadConfig() {
+  const globalConfig = readConfigFile(getConfigPath("global"));
+  const projectConfig = readConfigFile(getConfigPath("project"));
+  return { ...globalConfig, ...projectConfig };
+}
+function saveConfig(key, value, scope = "project") {
+  if (!validKeys().includes(key)) {
+    throw new Error(`Unknown config key: ${key}. Valid keys: ${validKeys().join(", ")}`);
+  }
+  const normalized = normalizeConfigValue(key, value);
+  if (normalized === undefined) {
+    const allowed = allowedValues(key);
+    throw new Error(allowed ? `Invalid value '${value}' for ${key}. Allowed: ${allowed.join(", ")}` : `Invalid value '${value}' for ${key}. Expected an http(s) URL`);
+  }
+  const filePath = getConfigPath(scope);
+  let existing = {};
+  if (existsSync(filePath)) {
+    try {
+      existing = JSON.parse(readFileSync(filePath, "utf-8"));
+      if (typeof existing !== "object" || existing === null || Array.isArray(existing)) {
+        existing = {};
+      }
+    } catch {
+      existing = {};
+    }
+  } else {
+    const dir = dirname(filePath);
+    if (!existsSync(dir)) {
+      mkdirSync(dir, { recursive: true });
+    }
+  }
+  existing[key] = normalized;
+  writeFileSync(filePath, JSON.stringify(existing, null, 2) + `
+`);
+}
+
+// src/lib/project-state.ts
+import { existsSync as existsSync2, mkdirSync as mkdirSync2, readFileSync as readFileSync2, writeFileSync as writeFileSync2 } from "fs";
+import { join as join2 } from "path";
+
+// src/lib/utils.ts
+function normalizeSkillName(name) {
+  return name;
+}
+
+// src/lib/project-state.ts
+var SKILLS_PROJECT_DIR = ".skills";
+var PROJECT_CONFIG_FILE = "project.json";
+var DEFAULT_EXPORT_DIR = ".skills/exports";
+function getProjectStateDir(targetDir = process.cwd()) {
+  return join2(targetDir, SKILLS_PROJECT_DIR);
+}
+function getProjectConfigPath(targetDir = process.cwd()) {
+  return join2(getProjectStateDir(targetDir), PROJECT_CONFIG_FILE);
+}
+function loadProjectConfig(targetDir = process.cwd()) {
+  const path = getProjectConfigPath(targetDir);
+  if (!existsSync2(path))
+    return null;
+  try {
+    return normalizeProjectConfig(JSON.parse(readFileSync2(path, "utf-8")));
+  } catch {
+    return null;
+  }
+}
+function ensureProjectConfig(targetDir = process.cwd()) {
+  const existing = loadProjectConfig(targetDir);
+  if (existing)
+    return existing;
+  const now = new Date().toISOString();
+  return {
+    version: 1,
+    defaultExportDir: DEFAULT_EXPORT_DIR,
+    pinnedSkills: [],
+    pins: {},
+    createdAt: now,
+    updatedAt: now
+  };
+}
+function saveProjectConfig(config, targetDir = process.cwd()) {
+  const dir = getProjectStateDir(targetDir);
+  mkdirSync2(dir, { recursive: true });
+  const normalized = normalizeProjectConfig({ ...config, updatedAt: new Date().toISOString() });
+  writeFileSync2(getProjectConfigPath(targetDir), JSON.stringify(normalized, null, 2) + `
+`);
+}
+function pinProjectSkill(name, details = {}, targetDir = process.cwd()) {
+  const skillName = normalizeSkillName(name);
+  const config = ensureProjectConfig(targetDir);
+  const alreadyPinned = config.pinnedSkills.includes(skillName);
+  if (!alreadyPinned)
+    config.pinnedSkills.push(skillName);
+  config.pinnedSkills = [...new Set(config.pinnedSkills)].sort();
+  config.pins[skillName] = config.pins[skillName] ?? {
+    name: skillName,
+    pinnedAt: new Date().toISOString(),
+    version: details.version ?? "unknown",
+    source: details.source ?? "official"
+  };
+  config.pins[skillName] = {
+    ...config.pins[skillName],
+    version: details.version ?? config.pins[skillName].version ?? "unknown",
+    source: details.source ?? config.pins[skillName].source ?? "official"
+  };
+  saveProjectConfig(config, targetDir);
+  return { pinned: !alreadyPinned, config };
+}
+function unpinProjectSkill(name, targetDir = process.cwd()) {
+  const skillName = normalizeSkillName(name);
+  const config = loadProjectConfig(targetDir);
+  if (!config)
+    return { unpinned: false, config: null };
+  const before = config.pinnedSkills.length;
+  config.pinnedSkills = config.pinnedSkills.filter((skill) => skill !== skillName);
+  delete config.pins[skillName];
+  if (config.disabledSkills) {
+    config.disabledSkills = config.disabledSkills.filter((skill) => skill !== skillName);
+  }
+  const unpinned = config.pinnedSkills.length !== before;
+  if (unpinned)
+    saveProjectConfig(config, targetDir);
+  return { unpinned, config };
+}
+function listPinnedSkills(targetDir = process.cwd()) {
+  return loadProjectConfig(targetDir)?.pinnedSkills ?? [];
+}
+function setSkillDisabled(name, disabled, targetDir = process.cwd()) {
+  const skillName = normalizeSkillName(name);
+  const config = loadProjectConfig(targetDir);
+  if (!config?.pinnedSkills.includes(skillName))
+    return false;
+  const disabledSet = new Set(config.disabledSkills ?? []);
+  const changed = disabled ? !disabledSet.has(skillName) : disabledSet.has(skillName);
+  if (disabled)
+    disabledSet.add(skillName);
+  else
+    disabledSet.delete(skillName);
+  config.disabledSkills = [...disabledSet].sort();
+  if (changed)
+    saveProjectConfig(config, targetDir);
+  return changed;
+}
+function getDisabledProjectSkills(targetDir = process.cwd()) {
+  return loadProjectConfig(targetDir)?.disabledSkills ?? [];
+}
+function normalizeProjectConfig(raw) {
+  const now = new Date().toISOString();
+  const pinnedSkills = Array.isArray(raw.pinnedSkills) ? [...new Set(raw.pinnedSkills.map((name) => normalizeSkillName(String(name))))].sort() : [];
+  const pins = {};
+  const rawPins = raw.pins && typeof raw.pins === "object" ? raw.pins : {};
+  for (const name of pinnedSkills) {
+    const pin = rawPins[name];
+    pins[name] = {
+      name,
+      pinnedAt: typeof pin?.pinnedAt === "string" ? pin.pinnedAt : now,
+      version: typeof pin?.version === "string" ? pin.version : "unknown",
+      source: isPinSource(pin?.source) ? pin.source : "official"
+    };
+  }
+  return {
+    version: 1,
+    defaultExportDir: typeof raw.defaultExportDir === "string" ? raw.defaultExportDir : DEFAULT_EXPORT_DIR,
+    pinnedSkills,
+    pins,
+    disabledSkills: Array.isArray(raw.disabledSkills) ? [...new Set(raw.disabledSkills.map((name) => normalizeSkillName(String(name))))].sort() : [],
+    createdAt: typeof raw.createdAt === "string" ? raw.createdAt : now,
+    updatedAt: typeof raw.updatedAt === "string" ? raw.updatedAt : now
+  };
+}
+function isPinSource(value) {
+  return value === "official" || value === "custom" || value === "remote" || value === "local";
+}
+
+// src/lib/native-storage.ts
+var SKILLS_STORAGE_TABLES = [
+  "skills_sync_records",
+  "skills_sync_cursors"
+];
+var STORAGE_TABLES = SKILLS_STORAGE_TABLES;
+var SKILLS_NATIVE_STORAGE_ENV = {
+  mode: "HASNA_SKILLS_STORAGE_MODE",
+  databaseUrl: "HASNA_SKILLS_DATABASE_URL",
+  databaseSsl: "HASNA_SKILLS_DATABASE_SSL",
+  databaseSchema: "HASNA_SKILLS_DATABASE_SCHEMA",
+  s3Bucket: "HASNA_SKILLS_S3_BUCKET",
+  s3Prefix: "HASNA_SKILLS_S3_PREFIX",
+  awsRegion: "HASNA_SKILLS_AWS_REGION",
+  s3Endpoint: "HASNA_SKILLS_S3_ENDPOINT",
+  s3ForcePathStyle: "HASNA_SKILLS_S3_FORCE_PATH_STYLE",
+  s3AccessKeyId: "HASNA_SKILLS_S3_ACCESS_KEY_ID",
+  s3SecretAccessKey: "HASNA_SKILLS_S3_SECRET_ACCESS_KEY",
+  s3SessionToken: "HASNA_SKILLS_S3_SESSION_TOKEN",
+  syncBatchSize: "HASNA_SKILLS_SYNC_BATCH_SIZE",
+  dryRun: "HASNA_SKILLS_SYNC_DRY_RUN"
+};
+var SKILLS_NATIVE_STORAGE_FALLBACK_ENV = {
+  mode: "SKILLS_STORAGE_MODE",
+  databaseUrl: "SKILLS_DATABASE_URL",
+  databaseSsl: "SKILLS_DATABASE_SSL",
+  databaseSchema: "SKILLS_DATABASE_SCHEMA",
+  s3Bucket: "SKILLS_S3_BUCKET",
+  s3Prefix: "SKILLS_S3_PREFIX",
+  awsRegion: "SKILLS_AWS_REGION",
+  s3Endpoint: "SKILLS_S3_ENDPOINT",
+  s3ForcePathStyle: "SKILLS_S3_FORCE_PATH_STYLE",
+  s3AccessKeyId: "SKILLS_S3_ACCESS_KEY_ID",
+  s3SecretAccessKey: "SKILLS_S3_SECRET_ACCESS_KEY",
+  s3SessionToken: "SKILLS_S3_SESSION_TOKEN",
+  syncBatchSize: "SKILLS_SYNC_BATCH_SIZE",
+  dryRun: "SKILLS_SYNC_DRY_RUN"
+};
+var SKILLS_STORAGE_ENV = SKILLS_NATIVE_STORAGE_ENV;
+var SKILLS_STORAGE_FALLBACK_ENV = SKILLS_NATIVE_STORAGE_FALLBACK_ENV;
+function resolveSkillsNativeStorageConfig(env = process.env) {
+  const mode = getSkillsStorageMode(env);
+  return {
+    mode,
+    databaseUrl: getSkillsStorageDatabaseUrl(env),
+    databaseSsl: parseBoolean(readStorageEnv(env, "databaseSsl").value),
+    databaseSchema: readStorageEnv(env, "databaseSchema").value,
+    s3Bucket: readStorageEnv(env, "s3Bucket").value,
+    s3Prefix: readStorageEnv(env, "s3Prefix").value,
+    awsRegion: readStorageEnv(env, "awsRegion").value ?? "us-east-1",
+    s3Endpoint: readStorageEnv(env, "s3Endpoint").value,
+    s3ForcePathStyle: parseBoolean(readStorageEnv(env, "s3ForcePathStyle").value) ?? false,
+    syncBatchSize: parsePositiveInteger(readStorageEnv(env, "syncBatchSize").value) ?? 500,
+    dryRun: parseBoolean(readStorageEnv(env, "dryRun").value) ?? true
+  };
+}
+function resolveStorageConfig(env = process.env) {
+  return resolveSkillsNativeStorageConfig(env);
+}
+function getSkillsStorageMode(env = process.env) {
+  return parseMode(readStorageEnv(env, "mode").value);
+}
+function getStorageMode(env = process.env) {
+  return getSkillsStorageMode(env);
+}
+function getSkillsStorageDatabaseEnv(env = process.env) {
+  return readStorageEnv(env, "databaseUrl").name;
+}
+function getStorageDatabaseEnv(env = process.env) {
+  return getSkillsStorageDatabaseEnv(env);
+}
+function getSkillsStorageDatabaseUrl(env = process.env) {
+  return readStorageEnv(env, "databaseUrl").value;
+}
+function getStorageDatabaseUrl(env = process.env) {
+  return getSkillsStorageDatabaseUrl(env);
+}
+function getSkillsNativeStorageStatus(options = {}) {
+  const env = options.env ?? process.env;
+  const config = resolveSkillsNativeStorageConfig(env);
+  const modeEnv = readStorageEnv(env, "mode");
+  const databaseEnv = readStorageEnv(env, "databaseUrl");
+  const s3BucketEnv = readStorageEnv(env, "s3Bucket");
+  const targetDir = options.targetDir ?? process.cwd();
+  return {
+    package: "open-skills",
+    mode: config.mode,
+    tables: [...SKILLS_STORAGE_TABLES],
+    env: {
+      mode: SKILLS_NATIVE_STORAGE_ENV.mode,
+      databaseUrl: SKILLS_NATIVE_STORAGE_ENV.databaseUrl,
+      s3Bucket: SKILLS_NATIVE_STORAGE_ENV.s3Bucket
+    },
+    local: {
+      dataDir: getDataDir(),
+      projectStateDir: getProjectStateDir(targetDir),
+      feedbackDbPath: join3(getDataDir(), "skills.db")
+    },
+    remote: {
+      databaseConfigured: Boolean(config.databaseUrl),
+      s3Configured: Boolean(config.s3Bucket),
+      databaseEnv: SKILLS_NATIVE_STORAGE_ENV.databaseUrl,
+      s3BucketEnv: SKILLS_NATIVE_STORAGE_ENV.s3Bucket,
+      activeModeEnv: modeEnv.name,
+      activeDatabaseEnv: databaseEnv.name,
+      activeS3BucketEnv: s3BucketEnv.name,
+      region: config.awsRegion ?? "us-east-1",
+      dryRun: config.dryRun
+    }
+  };
+}
+function getSkillsStorageStatus(options = {}) {
+  return getSkillsNativeStorageStatus(options);
+}
+function getStorageStatus(options = {}) {
+  return getSkillsNativeStorageStatus(options);
+}
+function exportSkillsLocalSnapshot(targetDir = process.cwd(), options = {}) {
+  const projectStateDir = getProjectStateDir(targetDir);
+  const files = [];
+  if (existsSync3(projectStateDir)) {
+    for (const filePath of walkFiles(projectStateDir)) {
+      const bytes = readFileSync3(filePath);
+      const relativePath = toPosix(relative(targetDir, filePath));
+      files.push({
+        path: relativePath,
+        sizeBytes: bytes.byteLength,
+        sha256: createHash("sha256").update(bytes).digest("hex"),
+        ...options.includeFileContents ? { contentBase64: Buffer.from(bytes).toString("base64") } : {}
+      });
+    }
+  }
+  return {
+    schemaVersion: 1,
+    exportedAt: new Date().toISOString(),
+    files: files.sort((a, b) => a.path.localeCompare(b.path))
+  };
+}
+function importSkillsLocalSnapshot(snapshot, targetDir = process.cwd(), options = {}) {
+  let written = 0;
+  let skipped = 0;
+  for (const file of snapshot.files) {
+    if (!file.contentBase64) {
+      skipped += 1;
+      continue;
+    }
+    const absolutePath = resolveSnapshotPath(targetDir, file.path);
+    if (existsSync3(absolutePath) && !options.overwrite) {
+      skipped += 1;
+      continue;
+    }
+    const bytes = Buffer.from(file.contentBase64, "base64");
+    const hash = createHash("sha256").update(bytes).digest("hex");
+    if (hash !== file.sha256) {
+      throw new Error(`Snapshot file checksum mismatch: ${file.path}`);
+    }
+    mkdirSync3(dirname2(absolutePath), { recursive: true });
+    writeFileSync3(absolutePath, bytes);
+    written += 1;
+  }
+  return { written, skipped };
+}
+var skillsPostgresSyncSchemaSql = `
+CREATE TABLE IF NOT EXISTS skills_sync_records (
+  scope TEXT NOT NULL,
+  kind TEXT NOT NULL,
+  id TEXT NOT NULL,
+  updated_at TIMESTAMPTZ NOT NULL,
+  deleted_at TIMESTAMPTZ,
+  source TEXT,
+  payload JSONB NOT NULL,
+  PRIMARY KEY (scope, kind, id)
+);
+
+CREATE INDEX IF NOT EXISTS skills_sync_records_updated_at_idx
+  ON skills_sync_records (updated_at);
+
+CREATE TABLE IF NOT EXISTS skills_sync_cursors (
+  scope TEXT NOT NULL,
+  cursor_name TEXT NOT NULL,
+  value TEXT NOT NULL,
+  updated_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+  PRIMARY KEY (scope, cursor_name)
+);
+`.trim();
+
+class SkillsPostgresSyncStore {
+  client;
+  constructor(client) {
+    this.client = client;
+  }
+  async ensureSchema() {
+    await this.client.query(skillsPostgresSyncSchemaSql);
+  }
+  async upsertRecords(records) {
+    let count = 0;
+    for (const record of records) {
+      await this.client.query([
+        "INSERT INTO skills_sync_records",
+        "(scope, kind, id, updated_at, deleted_at, source, payload)",
+        "VALUES ($1, $2, $3, $4, $5, $6, $7::jsonb)",
+        "ON CONFLICT (scope, kind, id) DO UPDATE SET",
+        "updated_at = EXCLUDED.updated_at,",
+        "deleted_at = EXCLUDED.deleted_at,",
+        "source = EXCLUDED.source,",
+        "payload = EXCLUDED.payload"
+      ].join(" "), [
+        record.scope,
+        record.kind,
+        record.id,
+        record.updatedAt,
+        record.deletedAt ?? null,
+        record.source ?? null,
+        JSON.stringify(record.payload)
+      ]);
+      count += 1;
+    }
+    return count;
+  }
+  async pullUpdatedSince(params) {
+    const limit = params.limit ?? 500;
+    const result = await this.client.query([
+      "SELECT scope, kind, id, updated_at, deleted_at, source, payload",
+      "FROM skills_sync_records",
+      "WHERE scope = $1 AND updated_at > $2",
+      "ORDER BY updated_at ASC",
+      "LIMIT $3"
+    ].join(" "), [params.scope, params.since ?? "1970-01-01T00:00:00.000Z", limit]);
+    return result.rows.map((row) => ({
+      scope: row.scope,
+      kind: row.kind,
+      id: row.id,
+      updatedAt: toIsoString(row.updated_at),
+      deletedAt: row.deleted_at ? toIsoString(row.deleted_at) : null,
+      source: row.source,
+      payload: typeof row.payload === "string" ? JSON.parse(row.payload) : row.payload
+    }));
+  }
+  async getCursor(scope, cursorName) {
+    const result = await this.client.query("SELECT value FROM skills_sync_cursors WHERE scope = $1 AND cursor_name = $2", [scope, cursorName]);
+    return result.rows[0]?.value ?? null;
+  }
+  async setCursor(scope, cursorName, value) {
+    await this.client.query([
+      "INSERT INTO skills_sync_cursors (scope, cursor_name, value, updated_at)",
+      "VALUES ($1, $2, $3, now())",
+      "ON CONFLICT (scope, cursor_name) DO UPDATE SET",
+      "value = EXCLUDED.value, updated_at = EXCLUDED.updated_at"
+    ].join(" "), [scope, cursorName, value]);
+  }
+}
+function createSkillsPostgresSyncStore(client) {
+  return new SkillsPostgresSyncStore(client);
+}
+function createSkillsSnapshotSyncRecord(snapshot, options = {}) {
+  return {
+    scope: options.scope ?? "default",
+    kind: "local-snapshot",
+    id: options.id ?? "project-state",
+    updatedAt: snapshot.exportedAt,
+    source: options.source ?? "open-skills",
+    payload: snapshot
+  };
+}
+
+class SkillsS3ObjectStore {
+  options;
+  fetchImpl;
+  region;
+  prefix;
+  constructor(options) {
+    this.options = options;
+    this.fetchImpl = options.fetch ?? ((input, init) => fetch(input, init));
+    this.region = options.region ?? "us-east-1";
+    this.prefix = normalizeS3Prefix(options.prefix);
+  }
+  objectKey(path) {
+    const cleaned = toPosix(path).replace(/^\.?\//, "").replace(/^\/+/, "");
+    return [this.prefix, cleaned].filter(Boolean).join("/");
+  }
+  objectUrl(key) {
+    return buildSkillsS3ObjectUrl({
+      bucket: this.options.bucket,
+      key,
+      region: this.region,
+      endpoint: this.options.endpoint,
+      forcePathStyle: this.options.forcePathStyle
+    });
+  }
+  async putObject(params) {
+    const key = this.objectKey(params.key);
+    const body = typeof params.body === "string" ? new TextEncoder().encode(params.body) : params.body;
+    const url = this.objectUrl(key);
+    const headers = {
+      "content-type": params.contentType ?? "application/octet-stream",
+      "x-amz-content-sha256": sha256Hex(body)
+    };
+    const signed = signSkillsAwsV4Request({
+      method: "PUT",
+      url,
+      region: this.region,
+      service: "s3",
+      headers,
+      body,
+      credentials: this.options.credentials
+    });
+    const response = await this.fetchImpl(url, {
+      method: "PUT",
+      headers: signed.headers,
+      body: toArrayBuffer(body)
+    });
+    if (!response.ok) {
+      throw new Error(`S3 put failed for ${key}: ${response.status} ${response.statusText}`.trim());
+    }
+    return {
+      key,
+      url,
+      etag: response.headers.get("etag"),
+      sizeBytes: body.byteLength
+    };
+  }
+  async getObject(key) {
+    const objectKey = this.objectKey(key);
+    const url = this.objectUrl(objectKey);
+    const signed = signSkillsAwsV4Request({
+      method: "GET",
+      url,
+      region: this.region,
+      service: "s3",
+      headers: { "x-amz-content-sha256": sha256Hex(new Uint8Array) },
+      credentials: this.options.credentials
+    });
+    const response = await this.fetchImpl(url, {
+      method: "GET",
+      headers: signed.headers
+    });
+    if (!response.ok) {
+      throw new Error(`S3 get failed for ${objectKey}: ${response.status} ${response.statusText}`.trim());
+    }
+    return new Uint8Array(await response.arrayBuffer());
+  }
+}
+function createSkillsS3ObjectStore(options) {
+  return new SkillsS3ObjectStore(options);
+}
+function planSkillsS3SnapshotUpload(snapshot, options = {}) {
+  const prefix = normalizeS3Prefix(options.prefix);
+  return snapshot.files.map((file) => ({
+    path: file.path,
+    key: [prefix, file.path.replace(/^\.?\//, "")].filter(Boolean).join("/"),
+    sizeBytes: file.sizeBytes,
+    sha256: file.sha256
+  }));
+}
+async function uploadSkillsSnapshotFilesToS3(snapshot, store) {
+  const uploaded = [];
+  for (const file of snapshot.files) {
+    if (!file.contentBase64)
+      continue;
+    uploaded.push(await store.putObject({
+      key: file.path,
+      body: Buffer.from(file.contentBase64, "base64"),
+      contentType: contentTypeForPath(file.path)
+    }));
+  }
+  return uploaded;
+}
+function signSkillsAwsV4Request(options) {
+  const now = options.now ?? new Date;
+  const amzDate = toAmzDate(now);
+  const dateStamp = amzDate.slice(0, 8);
+  const url = new URL(options.url);
+  const bodyBytes = typeof options.body === "string" ? new TextEncoder().encode(options.body) : options.body ?? new Uint8Array;
+  const payloadHash = sha256Hex(bodyBytes);
+  const headers = normalizeHeaders({
+    ...options.headers ?? {},
+    host: url.host,
+    "x-amz-date": amzDate,
+    "x-amz-content-sha256": options.headers?.["x-amz-content-sha256"] ?? payloadHash,
+    ...options.credentials.sessionToken ? { "x-amz-security-token": options.credentials.sessionToken } : {}
+  });
+  const signedHeaderNames = Object.keys(headers).sort();
+  const canonicalHeaders = signedHeaderNames.map((name) => `${name}:${headers[name]}
+`).join("");
+  const canonicalQuery = canonicalizeQuery(url.searchParams);
+  const canonicalRequest = [
+    options.method.toUpperCase(),
+    encodeUriPath(url.pathname),
+    canonicalQuery,
+    canonicalHeaders,
+    signedHeaderNames.join(";"),
+    headers["x-amz-content-sha256"]
+  ].join(`
+`);
+  const credentialScope = `${dateStamp}/${options.region}/${options.service}/aws4_request`;
+  const stringToSign = [
+    "AWS4-HMAC-SHA256",
+    amzDate,
+    credentialScope,
+    sha256Hex(canonicalRequest)
+  ].join(`
+`);
+  const signingKey = getAwsSigningKey(options.credentials.secretAccessKey, dateStamp, options.region, options.service);
+  const signature = createHmac("sha256", signingKey).update(stringToSign).digest("hex");
+  headers.authorization = [
+    `AWS4-HMAC-SHA256 Credential=${options.credentials.accessKeyId}/${credentialScope}`,
+    `SignedHeaders=${signedHeaderNames.join(";")}`,
+    `Signature=${signature}`
+  ].join(", ");
+  return { headers, canonicalRequest, stringToSign };
+}
+function buildSkillsS3ObjectUrl(params) {
+  const region = params.region ?? "us-east-1";
+  const key = params.key.split("/").map(encodeURIComponent).join("/");
+  if (params.endpoint) {
+    const endpoint = params.endpoint.replace(/\/+$/, "");
+    return params.forcePathStyle ? `${endpoint}/${encodeURIComponent(params.bucket)}/${key}` : `${endpoint}/${key}`;
+  }
+  return params.forcePathStyle ? `https://s3.${region}.amazonaws.com/${encodeURIComponent(params.bucket)}/${key}` : `https://${params.bucket}.s3.${region}.amazonaws.com/${key}`;
+}
+function parseMode(value) {
+  const normalized = value?.trim().toLowerCase();
+  if (normalized === "remote" || normalized === "hybrid")
+    return normalized;
+  return "local";
+}
+function readStorageEnv(env, key) {
+  const primaryName = SKILLS_NATIVE_STORAGE_ENV[key];
+  const primaryValue = cleanOptional(env[primaryName]);
+  if (primaryValue !== undefined)
+    return { name: primaryName, value: primaryValue };
+  const fallbackName = SKILLS_NATIVE_STORAGE_FALLBACK_ENV[key];
+  const fallbackValue = cleanOptional(env[fallbackName]);
+  if (fallbackValue !== undefined)
+    return { name: fallbackName, value: fallbackValue };
+  return { name: primaryName };
+}
+function cleanOptional(value) {
+  const cleaned = value?.trim();
+  return cleaned ? cleaned : undefined;
+}
+function parseBoolean(value) {
+  if (value === undefined)
+    return;
+  const normalized = value.trim().toLowerCase();
+  if (["1", "true", "yes", "on"].includes(normalized))
+    return true;
+  if (["0", "false", "no", "off"].includes(normalized))
+    return false;
+  return;
+}
+function parsePositiveInteger(value) {
+  if (!value)
+    return;
+  const parsed = Number.parseInt(value, 10);
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : undefined;
+}
+function walkFiles(dir) {
+  const files = [];
+  for (const entry of readdirSync(dir)) {
+    const full = join3(dir, entry);
+    const stats = statSync(full);
+    if (stats.isDirectory())
+      files.push(...walkFiles(full));
+    else
+      files.push(full);
+  }
+  return files;
+}
+function resolveSnapshotPath(targetDir, snapshotPath) {
+  const normalizedPath = normalize(snapshotPath);
+  if (normalizedPath.startsWith("..") || normalizedPath.includes(`${sep}..${sep}`) || normalizedPath.startsWith(sep)) {
+    throw new Error(`Unsafe snapshot path: ${snapshotPath}`);
+  }
+  if (!toPosix(normalizedPath).startsWith(".skills/")) {
+    throw new Error(`Snapshot path must stay inside .skills: ${snapshotPath}`);
+  }
+  return join3(targetDir, normalizedPath);
+}
+function normalizeS3Prefix(prefix) {
+  return (prefix ?? "").trim().replace(/^\/+|\/+$/g, "");
+}
+function toPosix(path) {
+  return path.split(/[\\/]+/).join("/");
+}
+function toIsoString(value) {
+  const date = new Date(value);
+  return Number.isNaN(date.getTime()) ? value : date.toISOString();
+}
+function sha256Hex(value) {
+  return createHash("sha256").update(value).digest("hex");
+}
+function normalizeHeaders(headers) {
+  const result = {};
+  for (const [key, value] of Object.entries(headers)) {
+    result[key.toLowerCase()] = String(value).trim().replace(/\s+/g, " ");
+  }
+  return result;
+}
+function canonicalizeQuery(params) {
+  return [...params.entries()].sort(([aKey, aValue], [bKey, bValue]) => aKey.localeCompare(bKey) || aValue.localeCompare(bValue)).map(([key, value]) => `${encodeURIComponent(key)}=${encodeURIComponent(value)}`).join("&");
+}
+function encodeUriPath(pathname) {
+  return pathname.split("/").map((segment) => encodeURIComponent(decodeURIComponent(segment)).replace(/[!'()*]/g, (char) => `%${char.charCodeAt(0).toString(16).toUpperCase()}`)).join("/");
+}
+function toAmzDate(date) {
+  return date.toISOString().replace(/[:-]|\.\d{3}/g, "");
+}
+function getAwsSigningKey(secret, dateStamp, region, service) {
+  const kDate = createHmac("sha256", `AWS4${secret}`).update(dateStamp).digest();
+  const kRegion = createHmac("sha256", kDate).update(region).digest();
+  const kService = createHmac("sha256", kRegion).update(service).digest();
+  return createHmac("sha256", kService).update("aws4_request").digest();
+}
+function contentTypeForPath(path) {
+  const lower = path.toLowerCase();
+  if (lower.endsWith(".json"))
+    return "application/json";
+  if (lower.endsWith(".log") || lower.endsWith(".txt") || lower.endsWith(".ndjson"))
+    return "text/plain";
+  if (lower.endsWith(".md"))
+    return "text/markdown";
+  if (lower.endsWith(".png"))
+    return "image/png";
+  if (lower.endsWith(".jpg") || lower.endsWith(".jpeg"))
+    return "image/jpeg";
+  if (lower.endsWith(".webp"))
+    return "image/webp";
+  if (lower.endsWith(".pdf"))
+    return "application/pdf";
+  return "application/octet-stream";
+}
+function toArrayBuffer(bytes) {
+  const buffer = new ArrayBuffer(bytes.byteLength);
+  new Uint8Array(buffer).set(bytes);
+  return buffer;
+}
+export {
+  uploadSkillsSnapshotFilesToS3,
+  skillsPostgresSyncSchemaSql,
+  signSkillsAwsV4Request,
+  resolveStorageConfig,
+  resolveSkillsNativeStorageConfig,
+  planSkillsS3SnapshotUpload,
+  importSkillsLocalSnapshot,
+  getStorageStatus,
+  getStorageMode,
+  getStorageDatabaseUrl,
+  getStorageDatabaseEnv,
+  getSkillsStorageStatus,
+  getSkillsStorageMode,
+  getSkillsStorageDatabaseUrl,
+  getSkillsStorageDatabaseEnv,
+  getSkillsNativeStorageStatus,
+  exportSkillsLocalSnapshot,
+  createSkillsSnapshotSyncRecord,
+  createSkillsS3ObjectStore,
+  createSkillsPostgresSyncStore,
+  buildSkillsS3ObjectUrl,
+  SkillsS3ObjectStore,
+  SkillsPostgresSyncStore,
+  STORAGE_TABLES,
+  SKILLS_STORAGE_TABLES,
+  SKILLS_STORAGE_FALLBACK_ENV,
+  SKILLS_STORAGE_ENV,
+  SKILLS_NATIVE_STORAGE_FALLBACK_ENV,
+  SKILLS_NATIVE_STORAGE_ENV
+};