@hasna/instructions 0.6.1 → 0.7.1

package/dist/chunks/index-n3fjspr0.js

@@ -0,0 +1,119 @@
+// @bun
+// src/types/index.ts
+var CONFIG_AGENTS = [
+  "claude",
+  "codex",
+  "opencode",
+  "cursor",
+  "codewith",
+  "aicopilot",
+  "antigravity",
+  "qwen",
+  "grok",
+  "copilot",
+  "devin",
+  "windsurf-legacy",
+  "cline",
+  "zsh",
+  "git",
+  "npm",
+  "global"
+];
+var PROFILE_CONFIG_BINDING_SCHEMA = "hasna.instructions.profile-config-binding/v1";
+var INSTRUCTION_ACTIVATION_MODES = ["always", "glob", "model", "manual"];
+var INSTRUCTION_FALLBACKS = ["fail", "flatten", "promote-always", "omit"];
+var PROFILE_ASSET_BINDING_SCHEMA = "hasna.instructions.profile-asset-binding/v1";
+var ASSET_KINDS = ["skill", "workflow", "plugin", "extension", "hook", "custom-agent"];
+var ASSET_DESTINATION_STRATEGIES = ["emit-file", "install-local", "install-marketplace", "unsupported"];
+var ASSET_SCOPES = ["global", "project", "session"];
+var ASSET_UNINSTALL_POLICIES = ["remove-managed", "retain"];
+var ASSET_ROLLBACK_POLICIES = ["snapshot", "installer-receipt", "none"];
+var INSTRUCTIONS_DOMAIN_ARCHIVE_SCHEMA = "hasna.instructions.domain-archive/v2";
+
+class ConfigNotFoundError extends Error {
+  constructor(id) {
+    super(`Config not found: ${id}`);
+    this.name = "ConfigNotFoundError";
+  }
+}
+
+class ProfileNotFoundError extends Error {
+  constructor(id) {
+    super(`Profile not found: ${id}`);
+    this.name = "ProfileNotFoundError";
+  }
+}
+
+class ConfigApplyError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "ConfigApplyError";
+  }
+}
+
+class TemplateRenderError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "TemplateRenderError";
+  }
+}
+
+// src/lib/template.ts
+var VAR_PATTERN = /\{\{([A-Z0-9_]+)(?::([^}]*))?\}\}/g;
+function parseTemplateVars(content) {
+  const names = new Set;
+  let match;
+  VAR_PATTERN.lastIndex = 0;
+  while ((match = VAR_PATTERN.exec(content)) !== null) {
+    names.add(match[1]);
+  }
+  return Array.from(names);
+}
+function extractTemplateVars(content) {
+  const vars = new Map;
+  let match;
+  VAR_PATTERN.lastIndex = 0;
+  while ((match = VAR_PATTERN.exec(content)) !== null) {
+    const name = match[1];
+    const description = match[2] ?? null;
+    if (!vars.has(name)) {
+      vars.set(name, { name, description, required: true });
+    }
+  }
+  return Array.from(vars.values());
+}
+function renderTemplate(content, vars) {
+  const missing = [];
+  VAR_PATTERN.lastIndex = 0;
+  let match;
+  while ((match = VAR_PATTERN.exec(content)) !== null) {
+    const name = match[1];
+    if (!(name in vars))
+      missing.push(name);
+  }
+  if (missing.length > 0) {
+    throw new TemplateRenderError(`Missing required template variables: ${missing.join(", ")}`);
+  }
+  VAR_PATTERN.lastIndex = 0;
+  return content.replace(VAR_PATTERN, (_match, name) => vars[name] ?? "");
+}
+function renderTemplatePreview(content, vars) {
+  const unresolved = new Set;
+  VAR_PATTERN.lastIndex = 0;
+  const rendered = content.replace(VAR_PATTERN, (match, name) => {
+    if (name in vars)
+      return vars[name] ?? "";
+    unresolved.add(name);
+    return match;
+  });
+  return {
+    content: rendered,
+    unresolved: [...unresolved].sort()
+  };
+}
+function isTemplate(content) {
+  VAR_PATTERN.lastIndex = 0;
+  return VAR_PATTERN.test(content);
+}
+
+export { CONFIG_AGENTS, PROFILE_CONFIG_BINDING_SCHEMA, INSTRUCTION_ACTIVATION_MODES, INSTRUCTION_FALLBACKS, PROFILE_ASSET_BINDING_SCHEMA, ASSET_KINDS, ASSET_DESTINATION_STRATEGIES, ASSET_SCOPES, ASSET_UNINSTALL_POLICIES, ASSET_ROLLBACK_POLICIES, INSTRUCTIONS_DOMAIN_ARCHIVE_SCHEMA, ConfigNotFoundError, ProfileNotFoundError, ConfigApplyError, parseTemplateVars, extractTemplateVars, renderTemplate, renderTemplatePreview, isTemplate };

package/dist/chunks/{index-85n5wnd8.js → index-pdpg8a44.js}

@@ -1,10 +1,11 @@
 // @bun
 import {
   applyConfigsWithReport,
+  compactPathForConfigHome,
   expandPath,
   getConfigHome,
   normalizeTargetPath
-} from "./index-e9epbsvs.js";
+} from "./index-r7nfef2g.js";
 import {
   applyTransform,
   detectMachineContext,
@@ -15,7 +16,7 @@ import {
   resolveConfigStore,
   retiredOrUnsupportedAgentReason,
   templateizeMachineContent
-} from "./index-1hpwskwd.js";
+} from "./index-6jncnnw7.js";
 
 // src/lib/sync.ts
 import { existsSync as existsSync2, readdirSync as readdirSync2, readFileSync as readFileSync2 } from "fs";
@@ -24,7 +25,6 @@ import { basename, extname, join as join2 } from "path";
 // src/lib/sync-dir.ts
 import { existsSync, readdirSync, readFileSync, statSync } from "fs";
 import { join, relative } from "path";
-import { homedir } from "os";
 var SKIP = [".db", ".db-shm", ".db-wal", ".log", ".lock", ".DS_Store", "node_modules", ".git"];
 function shouldSkip(p) {
   return SKIP.some((s) => p.includes(s));
@@ -36,7 +36,6 @@ async function syncFromDir(dir, opts = {}) {
     return { added: 0, updated: 0, unchanged: 0, skipped: [`Not found: ${absDir}`] };
   const files = opts.recursive !== false ? walkDir(absDir) : readdirSync(absDir).map((f) => join(absDir, f)).filter((f) => statSync(f).isFile());
   const result = { added: 0, updated: 0, unchanged: 0, skipped: [] };
-  const home = homedir();
   const allConfigs = await store.listConfigs();
   for (const file of files) {
     if (shouldSkip(file)) {
@@ -49,7 +48,7 @@ async function syncFromDir(dir, opts = {}) {
         result.skipped.push(file + " (too large)");
         continue;
       }
-      const targetPath = file.replace(home, "~");
+      const targetPath = compactPathForConfigHome(file);
       const redacted = redactContent(content, redactFormatForTarget(targetPath, detectFormat(file)));
       const existing = allConfigs.find((c) => c.target_path === targetPath);
       if (!existing) {
@@ -71,9 +70,8 @@ async function syncFromDir(dir, opts = {}) {
 }
 async function syncToDir(dir, opts = {}) {
   const store = opts.store ?? resolveConfigStore();
-  const home = homedir();
   const absDir = expandPath(dir);
-  const normalized = dir.startsWith("~/") ? dir : absDir.replace(home, "~");
+  const normalized = dir.startsWith("~/") ? dir : compactPathForConfigHome(absDir);
   const configs = (await store.listConfigs()).filter((c) => c.target_path && (c.target_path.startsWith(normalized) || c.target_path.startsWith(absDir)));
   const result = { added: 0, updated: 0, unchanged: 0, skipped: [] };
   for (const config of configs) {

package/dist/chunks/{index-e9epbsvs.js → index-r7nfef2g.js}

@@ -18,15 +18,15 @@ import {
   resolveProfileVariables,
   scanSecrets,
   stampCursorGlobalAuthorityMarker
-} from "./index-1hpwskwd.js";
+} from "./index-6jncnnw7.js";
 import {
   ConfigApplyError,
   parseTemplateVars
-} from "./index-pkscjnj5.js";
+} from "./index-n3fjspr0.js";
 
 // src/lib/apply.ts
 import { existsSync as existsSync2, mkdirSync, readFileSync as readFileSync2, realpathSync, writeFileSync } from "fs";
-import { basename, dirname as dirname2, join as join2, resolve } from "path";
+import { basename, dirname as dirname2, isAbsolute, join as join2, relative as relative2, resolve, sep as sep2 } from "path";
 import { homedir } from "os";
 
 // src/lib/session-render-ownership.ts
@@ -110,6 +110,17 @@ function expandPath(p) {
   }
   return resolve(p);
 }
+function compactPathForConfigHome(p) {
+  const absolute = resolve(p);
+  const configHome = resolve(getConfigHome());
+  const conventionalHome = resolve(process.env["HOME"] || homedir());
+  if (configHome !== conventionalHome)
+    return absolute;
+  const rel = relative2(configHome, absolute);
+  if (!rel || rel === ".." || rel.startsWith(`..${sep2}`) || isAbsolute(rel))
+    return absolute;
+  return `~/${rel}`;
+}
 function normalizeTargetPath(p) {
   const expanded = expandPath(p);
   try {
@@ -518,4 +529,4 @@ function sessionRendererOwnsCanonicalTarget(normalized, opts) {
   return sessionRenderOwnsPath(normalized);
 }
 
-export { getConfigHome, expandPath, normalizeTargetPath, applyConfig, applyConfigs, applyConfigsWithReport, previewConfigs };
+export { getConfigHome, expandPath, compactPathForConfigHome, normalizeTargetPath, applyConfig, applyConfigs, applyConfigsWithReport, previewConfigs };

package/dist/chunks/{index-axhwg61p.js → index-ypcef3a2.js}

@@ -15,7 +15,7 @@ import {
   resolveConfigStore,
   resolveProfileVariables,
   stampCursorGlobalAuthorityMarker
-} from "./index-v7dkb384.js";
+} from "./index-aj66f6xr.js";
 import {
   isSecretVarName,
   redactFormatForTarget,
@@ -24,11 +24,11 @@ import {
 import {
   ConfigApplyError,
   parseTemplateVars
-} from "./index-pkscjnj5.js";
+} from "./index-3djthcm6.js";
 
 // src/lib/apply.ts
 import { existsSync as existsSync2, mkdirSync, readFileSync as readFileSync2, realpathSync, writeFileSync } from "fs";
-import { basename, dirname as dirname2, join as join2, resolve } from "path";
+import { basename, dirname as dirname2, isAbsolute, join as join2, relative as relative2, resolve, sep as sep2 } from "path";
 import { homedir } from "os";
 
 // src/lib/session-render-ownership.ts
@@ -112,6 +112,17 @@ function expandPath(p) {
   }
   return resolve(p);
 }
+function compactPathForConfigHome(p) {
+  const absolute = resolve(p);
+  const configHome = resolve(getConfigHome());
+  const conventionalHome = resolve(process.env["HOME"] || homedir());
+  if (configHome !== conventionalHome)
+    return absolute;
+  const rel = relative2(configHome, absolute);
+  if (!rel || rel === ".." || rel.startsWith(`..${sep2}`) || isAbsolute(rel))
+    return absolute;
+  return `~/${rel}`;
+}
 function normalizeTargetPath(p) {
   const expanded = expandPath(p);
   try {
@@ -520,4 +531,4 @@ function sessionRendererOwnsCanonicalTarget(normalized, opts) {
   return sessionRenderOwnsPath(normalized);
 }
 
-export { getConfigHome, expandPath, normalizeTargetPath, applyConfig, applyConfigs, applyConfigsWithReport, previewConfigs };
+export { getConfigHome, expandPath, compactPathForConfigHome, normalizeTargetPath, applyConfig, applyConfigs, applyConfigsWithReport, previewConfigs };

package/dist/chunks/legacy-store-migration-z2m5yzyk.js

@@ -0,0 +1,322 @@
+// @bun
+import"./index-bsan4c16.js";
+
+// src/lib/legacy-store-migration.ts
+import { Database } from "bun:sqlite";
+import { chmodSync, constants, copyFileSync, existsSync, mkdirSync, statSync } from "fs";
+import { createHash } from "crypto";
+import { dirname, join, resolve } from "path";
+import { homedir } from "os";
+
+class LegacyStoreMigrationError extends Error {
+  code;
+  constructor(code, message) {
+    super(message);
+    this.name = "LegacyStoreMigrationError";
+    this.code = code;
+  }
+}
+function emptyCounts() {
+  return { configs: 0, snapshots: 0, profiles: 0, profileConfigs: 0, machines: 0 };
+}
+function legacyInstructionsStorePaths(home = process.env.HOME || homedir()) {
+  return {
+    sourcePath: join(home, ".hasna", "configs", "configs.db"),
+    destinationPath: join(home, ".hasna", "instructions", "instructions.db")
+  };
+}
+function tableExists(db, table) {
+  return db.query("SELECT 1 AS present FROM sqlite_master WHERE type = 'table' AND name = ?").get(table)?.present === 1;
+}
+function columns(db, table) {
+  if (!tableExists(db, table))
+    return new Set;
+  return new Set(db.query(`PRAGMA table_info(${table})`).all().map((row) => row.name));
+}
+function rows(db, table) {
+  if (!tableExists(db, table))
+    return [];
+  return db.query(`SELECT * FROM ${table} ORDER BY rowid`).all();
+}
+function value(row, name, fallback) {
+  return Object.prototype.hasOwnProperty.call(row, name) && row[name] !== undefined ? row[name] : fallback;
+}
+function normalizeJson(valueToNormalize, fallback) {
+  if (typeof valueToNormalize !== "string")
+    return fallback;
+  try {
+    JSON.parse(valueToNormalize);
+    return valueToNormalize;
+  } catch {
+    return fallback;
+  }
+}
+function compatibleConfig(row) {
+  return {
+    id: value(row, "id", ""),
+    name: value(row, "name", ""),
+    slug: value(row, "slug", ""),
+    kind: value(row, "kind", "file"),
+    category: value(row, "category", "rules"),
+    agent: value(row, "agent", "global"),
+    target_path: value(row, "target_path", null),
+    outputs: normalizeJson(value(row, "outputs", "[]"), "[]"),
+    format: value(row, "format", "text"),
+    content: value(row, "content", ""),
+    description: value(row, "description", null),
+    tags: normalizeJson(value(row, "tags", "[]"), "[]"),
+    is_template: value(row, "is_template", 0),
+    version: value(row, "version", 1),
+    created_at: value(row, "created_at", "1970-01-01T00:00:00.000Z"),
+    updated_at: value(row, "updated_at", value(row, "created_at", "1970-01-01T00:00:00.000Z")),
+    synced_at: value(row, "synced_at", null)
+  };
+}
+function compatibleProfile(row) {
+  return {
+    id: value(row, "id", ""),
+    name: value(row, "name", ""),
+    slug: value(row, "slug", ""),
+    description: value(row, "description", null),
+    selectors: normalizeJson(value(row, "selectors", "{}"), "{}"),
+    variables: normalizeJson(value(row, "variables", "{}"), "{}"),
+    created_at: value(row, "created_at", "1970-01-01T00:00:00.000Z"),
+    updated_at: value(row, "updated_at", value(row, "created_at", "1970-01-01T00:00:00.000Z"))
+  };
+}
+function compatibleMachine(row) {
+  return {
+    id: value(row, "id", ""),
+    hostname: value(row, "hostname", ""),
+    os: value(row, "os", null),
+    arch: value(row, "arch", null),
+    last_applied_at: value(row, "last_applied_at", null),
+    created_at: value(row, "created_at", "1970-01-01T00:00:00.000Z")
+  };
+}
+function stableSnapshotId(config) {
+  const digest = createHash("sha256").update(String(config.id)).update("\x00").update(String(config.version)).update("\x00").update(String(config.content)).digest("hex").slice(0, 32);
+  return `legacy-current-${digest}`;
+}
+function countDestinationRows(db) {
+  return ["configs", "config_snapshots", "profiles", "profile_configs", "machines"].reduce((total, table) => {
+    if (!tableExists(db, table))
+      return total;
+    return total + (db.query(`SELECT COUNT(*) AS count FROM ${table}`).get()?.count ?? 0);
+  }, 0);
+}
+function requireCurrentSchema(db) {
+  const required = {
+    configs: ["id", "slug", "kind", "outputs", "content", "version"],
+    config_snapshots: ["id", "config_id", "content", "version"],
+    profiles: ["id", "slug", "selectors", "variables"],
+    profile_configs: ["profile_id", "config_id", "binding"],
+    machines: ["id", "hostname", "arch"]
+  };
+  for (const [table, names] of Object.entries(required)) {
+    const actual = columns(db, table);
+    if (names.some((name) => !actual.has(name))) {
+      throw new LegacyStoreMigrationError("DESTINATION_SCHEMA_INCOMPATIBLE", `instructions legacy migration: destination is not a current Instructions SQLite database (incompatible ${table} table)`);
+    }
+  }
+}
+function sameConfig(a, b) {
+  const keys = ["id", "name", "slug", "kind", "category", "agent", "target_path", "outputs", "format", "content", "description", "tags", "is_template", "version", "created_at", "updated_at", "synced_at"];
+  return keys.every((key) => String(a[key] ?? "") === String(b[key] ?? ""));
+}
+function buildPlan(source, destination, mergePolicy) {
+  const sourceCounts = emptyCounts();
+  const migrated = emptyCounts();
+  const skipped = emptyCounts();
+  const planned = [];
+  let conflicts = 0;
+  let snapshotsCreated = 0;
+  const sourceConfigs = rows(source, "configs").map(compatibleConfig);
+  const sourceSnapshots = rows(source, "config_snapshots");
+  const sourceProfiles = rows(source, "profiles").map(compatibleProfile);
+  const sourceProfileConfigs = rows(source, "profile_configs");
+  const sourceMachines = rows(source, "machines").map(compatibleMachine);
+  sourceCounts.configs = sourceConfigs.length;
+  sourceCounts.snapshots = sourceSnapshots.length;
+  sourceCounts.profiles = sourceProfiles.length;
+  sourceCounts.profileConfigs = sourceProfileConfigs.length;
+  sourceCounts.machines = sourceMachines.length;
+  const acceptedConfigIds = new Set;
+  for (const config of sourceConfigs) {
+    const id = String(config.id);
+    const existing = destination.query("SELECT * FROM configs WHERE id = ? OR slug = ? LIMIT 1").get(id, String(config.slug));
+    if (existing) {
+      skipped.configs++;
+      if (!sameConfig(existing, config))
+        conflicts++;
+      if (mergePolicy === "preserve-destination" && String(existing.id) === id && sameConfig(existing, config)) {
+        acceptedConfigIds.add(id);
+      }
+      continue;
+    }
+    acceptedConfigIds.add(id);
+    planned.push({ table: "configs", values: config });
+    migrated.configs++;
+  }
+  const snapshotIdentity = new Set;
+  for (const snapshot of sourceSnapshots) {
+    const configId = String(value(snapshot, "config_id", ""));
+    if (!acceptedConfigIds.has(configId)) {
+      skipped.snapshots++;
+      continue;
+    }
+    const normalized = {
+      id: value(snapshot, "id", ""),
+      config_id: configId,
+      content: value(snapshot, "content", ""),
+      version: value(snapshot, "version", 1),
+      created_at: value(snapshot, "created_at", "1970-01-01T00:00:00.000Z")
+    };
+    const identity = `${configId}\x00${normalized.version}\x00${normalized.content}`;
+    snapshotIdentity.add(identity);
+    const existing = destination.query("SELECT id FROM config_snapshots WHERE id = ?").get(String(normalized.id));
+    if (existing)
+      skipped.snapshots++;
+    else {
+      planned.push({ table: "snapshots", values: normalized });
+      migrated.snapshots++;
+    }
+  }
+  for (const config of sourceConfigs) {
+    const configId = String(config.id);
+    if (!acceptedConfigIds.has(configId))
+      continue;
+    const identity = `${configId}\x00${config.version}\x00${config.content}`;
+    const destinationHas = destination.query("SELECT 1 AS present FROM config_snapshots WHERE config_id = ? AND version = ? AND content = ? LIMIT 1").get(configId, Number(config.version), String(config.content));
+    if (!snapshotIdentity.has(identity) && !destinationHas) {
+      planned.push({ table: "snapshots", values: {
+        id: stableSnapshotId(config),
+        config_id: configId,
+        content: config.content,
+        version: config.version,
+        created_at: config.updated_at
+      } });
+      migrated.snapshots++;
+      snapshotsCreated++;
+    }
+  }
+  const acceptedProfileIds = new Set;
+  for (const profile of sourceProfiles) {
+    const existing = destination.query("SELECT id FROM profiles WHERE id = ? OR slug = ? LIMIT 1").get(String(profile.id), String(profile.slug));
+    if (existing) {
+      skipped.profiles++;
+      if (String(existing.id) !== String(profile.id))
+        conflicts++;
+    } else {
+      acceptedProfileIds.add(String(profile.id));
+      planned.push({ table: "profiles", values: profile });
+      migrated.profiles++;
+    }
+  }
+  for (const link of sourceProfileConfigs) {
+    const profileId = String(value(link, "profile_id", ""));
+    const configId = String(value(link, "config_id", ""));
+    if (!acceptedProfileIds.has(profileId) || !acceptedConfigIds.has(configId)) {
+      skipped.profileConfigs++;
+      continue;
+    }
+    planned.push({ table: "profileConfigs", values: {
+      profile_id: profileId,
+      config_id: configId,
+      sort_order: value(link, "sort_order", 0),
+      binding: normalizeJson(value(link, "binding", '{"schema":"hasna.instructions.profile-config-binding/v1","activation":{"mode":"always"},"required":true,"fallback":"fail"}'), "{}")
+    } });
+    migrated.profileConfigs++;
+  }
+  for (const machine of sourceMachines) {
+    const existing = destination.query("SELECT id FROM machines WHERE id = ? OR hostname = ? LIMIT 1").get(String(machine.id), String(machine.hostname));
+    if (existing) {
+      skipped.machines++;
+      if (String(existing.id) !== String(machine.id))
+        conflicts++;
+    } else {
+      planned.push({ table: "machines", values: machine });
+      migrated.machines++;
+    }
+  }
+  return { source: sourceCounts, migrated, skipped, conflicts, snapshotsCreated, rows: planned };
+}
+function insertRow(db, row) {
+  const table = row.table === "snapshots" ? "config_snapshots" : row.table === "profileConfigs" ? "profile_configs" : row.table;
+  const names = Object.keys(row.values);
+  const placeholders = names.map(() => "?").join(", ");
+  db.run(`INSERT INTO ${table} (${names.join(", ")}) VALUES (${placeholders})`, names.map((name) => row.values[name]));
+}
+function migrateLegacyInstructionsStore(options) {
+  if (!options.operatorConfirmed) {
+    throw new LegacyStoreMigrationError("LOCAL_OPERATOR_CONFIRMATION_REQUIRED", "instructions legacy migration requires explicit local operator confirmation");
+  }
+  const defaults = legacyInstructionsStorePaths();
+  const sourcePath = resolve(options.sourcePath ?? defaults.sourcePath);
+  const destinationPath = resolve(options.destinationPath ?? defaults.destinationPath);
+  const dryRun = options.dryRun ?? true;
+  if (sourcePath === destinationPath) {
+    throw new LegacyStoreMigrationError("SOURCE_DESTINATION_SAME", "instructions legacy migration source and destination must differ");
+  }
+  if (!existsSync(sourcePath) || !statSync(sourcePath).isFile()) {
+    throw new LegacyStoreMigrationError("SOURCE_NOT_FOUND", "instructions legacy migration source database was not found");
+  }
+  if (!existsSync(destinationPath) || !statSync(destinationPath).isFile()) {
+    throw new LegacyStoreMigrationError("DESTINATION_NOT_FOUND", "instructions legacy migration destination must be an initialized current Instructions SQLite database");
+  }
+  const source = new Database(sourcePath, { readonly: true, strict: true });
+  const destination = new Database(destinationPath, { strict: true });
+  let backupPath = null;
+  try {
+    source.run("PRAGMA query_only = ON");
+    destination.run("PRAGMA foreign_keys = ON");
+    requireCurrentSchema(destination);
+    const destinationRows = countDestinationRows(destination);
+    if (destinationRows > 0 && options.mergePolicy === undefined) {
+      throw new LegacyStoreMigrationError("DESTINATION_NOT_EMPTY", "instructions legacy migration refuses a non-empty destination without an explicit merge policy");
+    }
+    const plan = buildPlan(source, destination, options.mergePolicy);
+    if (!dryRun) {
+      backupPath = resolve(options.backupPath ?? `${destinationPath}.before-legacy-migration.bak`);
+      if (backupPath === sourcePath || backupPath === destinationPath) {
+        throw new LegacyStoreMigrationError("INVALID_BACKUP_PATH", "instructions legacy migration backup path must be separate");
+      }
+      if (existsSync(backupPath)) {
+        throw new LegacyStoreMigrationError("BACKUP_ALREADY_EXISTS", "instructions legacy migration refuses to overwrite an existing destination backup");
+      }
+      mkdirSync(dirname(backupPath), { recursive: true, mode: 448 });
+      destination.run("PRAGMA wal_checkpoint(FULL)");
+      copyFileSync(destinationPath, backupPath, constants.COPYFILE_EXCL);
+      chmodSync(backupPath, 384);
+      const apply = destination.transaction(() => {
+        for (const row of plan.rows)
+          insertRow(destination, row);
+      });
+      apply();
+    }
+    return {
+      dryRun,
+      source: plan.source,
+      migrated: plan.migrated,
+      skipped: plan.skipped,
+      conflicts: plan.conflicts,
+      snapshotsCreated: plan.snapshotsCreated,
+      backupCreated: !dryRun,
+      sourcePath,
+      destinationPath,
+      backupPath
+    };
+  } catch (error) {
+    if (error instanceof LegacyStoreMigrationError)
+      throw error;
+    throw new LegacyStoreMigrationError("MIGRATION_FAILED", `instructions legacy migration failed safely: ${error instanceof Error ? error.name : "unknown error"}`);
+  } finally {
+    source.close();
+    destination.close();
+  }
+}
+export {
+  migrateLegacyInstructionsStore,
+  legacyInstructionsStorePaths,
+  LegacyStoreMigrationError
+};