@hasna/instructions 0.6.1 → 0.7.1

package/dist/chunks/s3-backup-hxe3zpfz.js

@@ -0,0 +1,240 @@
+// @bun
+import {
+  assertSafeInstructionsObjectKey,
+  assertSafeInstructionsObjectVersionId
+} from "./index-mvckkf15.js";
+import {
+  normalizeInstructionsS3Prefix
+} from "./index-8rb7ng2y.js";
+import"./index-bsan4c16.js";
+
+// src/storage/s3-backup.ts
+var INSTRUCTIONS_BACKUP_MANIFEST_SCHEMA = "hasna.instructions.backup-object/v1";
+var encoder = new TextEncoder;
+var decoder = new TextDecoder;
+var SHA256_PATTERN = /^[0-9a-f]{64}$/;
+var CONTROL_CHARACTERS = /[\u0000-\u001f\u007f]/;
+function buildInstructionsBackupKeys(prefix, backupId) {
+  const normalizedPrefix = normalizeInstructionsS3Prefix(prefix);
+  const encodedBackupId = encodeBackupId(backupId);
+  const rootKey = `${normalizedPrefix}backups/${encodedBackupId}`;
+  const keys = {
+    rootKey,
+    payloadKey: `${rootKey}/payload`,
+    manifestKey: `${rootKey}/manifest.json`
+  };
+  assertSafeInstructionsObjectKey(keys.payloadKey);
+  assertSafeInstructionsObjectKey(keys.manifestKey);
+  return keys;
+}
+async function planInstructionsBackupPush(input) {
+  const keys = buildInstructionsBackupKeys(input.prefix, input.backupId);
+  return {
+    operation: "push",
+    dryRun: true,
+    noNetwork: true,
+    backupId: input.backupId,
+    ...keys,
+    sha256: sha256(input.bytes),
+    sizeBytes: input.bytes.byteLength,
+    contentType: normalizeContentType(input.contentType)
+  };
+}
+async function pushInstructionsBackup(input) {
+  const plan = await planInstructionsBackupPush(input);
+  const existingManifestBytes = await input.store.get(plan.manifestKey);
+  if (existingManifestBytes) {
+    const existingManifest2 = parseManifest(existingManifestBytes, plan, input.backupId);
+    assertManifestMatchesPayload(existingManifest2, input.bytes);
+    const existingPayload2 = await input.store.get(existingManifest2.payloadKey);
+    if (!existingPayload2)
+      throw new Error("Instructions backup payload object is missing");
+    assertBytesMatch(existingPayload2, existingManifest2.sha256, existingManifest2.sizeBytes, "backup payload integrity");
+    return {
+      status: "existing",
+      manifest: existingManifest2,
+      ...await resolveCurrentVersions(input.store, existingManifest2)
+    };
+  }
+  const payloadCreate = await createImmutableObject(input.store, plan.payloadKey, input.bytes, plan.contentType);
+  if (payloadCreate.status === "existing") {
+    const existingPayload2 = await input.store.get(plan.payloadKey);
+    if (!existingPayload2)
+      throw new Error("Instructions backup payload object is missing");
+    assertBytesMatch(existingPayload2, plan.sha256, plan.sizeBytes, "existing immutable payload");
+  }
+  const manifest = {
+    schema: INSTRUCTIONS_BACKUP_MANIFEST_SCHEMA,
+    app: "instructions",
+    backupId: input.backupId,
+    payloadKey: plan.payloadKey,
+    manifestKey: plan.manifestKey,
+    sha256: plan.sha256,
+    sizeBytes: plan.sizeBytes,
+    contentType: plan.contentType,
+    createdAt: normalizeCreatedAt(input.createdAt)
+  };
+  const manifestCreate = await createImmutableObject(input.store, plan.manifestKey, serializeManifest(manifest), "application/json");
+  if (manifestCreate.status === "created") {
+    const versions = completeCreatedVersions(payloadCreate, manifestCreate);
+    return { status: "created", manifest, ...versions ? { versions } : {} };
+  }
+  const racedManifestBytes = await input.store.get(plan.manifestKey);
+  if (!racedManifestBytes)
+    throw new Error("Instructions backup manifest object is missing");
+  const existingManifest = parseManifest(racedManifestBytes, plan, input.backupId);
+  assertManifestMatchesPayload(existingManifest, input.bytes);
+  const existingPayload = await input.store.get(existingManifest.payloadKey);
+  if (!existingPayload)
+    throw new Error("Instructions backup payload object is missing");
+  assertBytesMatch(existingPayload, existingManifest.sha256, existingManifest.sizeBytes, "backup payload integrity");
+  return {
+    status: "existing",
+    manifest: existingManifest,
+    ...await resolveCurrentVersions(input.store, existingManifest)
+  };
+}
+async function pullInstructionsBackup(input) {
+  const versions = normalizeReadVersions(input);
+  const keys = buildInstructionsBackupKeys(input.prefix, input.backupId);
+  const manifestBytes = await input.store.get(keys.manifestKey, versions ? { versionId: versions.manifestVersionId } : undefined);
+  if (!manifestBytes)
+    throw new Error("Instructions backup manifest object is missing");
+  const manifest = parseManifest(manifestBytes, keys, input.backupId);
+  const bytes = await input.store.get(manifest.payloadKey, versions ? { versionId: versions.payloadVersionId } : undefined);
+  if (!bytes)
+    throw new Error("Instructions backup payload object is missing");
+  assertBytesMatch(bytes, manifest.sha256, manifest.sizeBytes, "backup payload integrity");
+  if (versions) {
+    const [manifestMetadata, payloadMetadata] = await Promise.all([
+      input.store.head(keys.manifestKey, { versionId: versions.manifestVersionId }),
+      input.store.head(manifest.payloadKey, { versionId: versions.payloadVersionId })
+    ]);
+    if (manifestMetadata?.versionId !== versions.manifestVersionId || payloadMetadata?.versionId !== versions.payloadVersionId) {
+      throw new Error("Instructions backup immutable version authority check failed");
+    }
+    if (payloadMetadata.size !== manifest.sizeBytes) {
+      throw new Error("Instructions backup payload version size check failed");
+    }
+  }
+  return {
+    manifest,
+    bytes,
+    versionPinned: Boolean(versions),
+    ...versions ? { versions } : {}
+  };
+}
+async function verifyInstructionsBackup(input) {
+  const result = await pullInstructionsBackup(input);
+  return {
+    ok: true,
+    backupId: result.manifest.backupId,
+    payloadKey: result.manifest.payloadKey,
+    manifestKey: result.manifest.manifestKey,
+    sha256: result.manifest.sha256,
+    sizeBytes: result.manifest.sizeBytes,
+    versionPinned: result.versionPinned,
+    ...result.versions ? { versions: result.versions } : {}
+  };
+}
+async function createImmutableObject(store, key, bytes, contentType) {
+  if (!store.putIfAbsent) {
+    throw new Error("Instructions object store does not support atomic immutable creation");
+  }
+  return store.putIfAbsent(key, bytes, { contentType });
+}
+function completeCreatedVersions(payload, manifest) {
+  if (!payload.versionId || !manifest.versionId)
+    return;
+  return { payloadVersionId: payload.versionId, manifestVersionId: manifest.versionId };
+}
+async function resolveCurrentVersions(store, manifest) {
+  const [payload, manifestObject] = await Promise.all([
+    store.head(manifest.payloadKey),
+    store.head(manifest.manifestKey)
+  ]);
+  if (!payload?.versionId || !manifestObject?.versionId)
+    return {};
+  return {
+    versions: {
+      payloadVersionId: payload.versionId,
+      manifestVersionId: manifestObject.versionId
+    }
+  };
+}
+function normalizeReadVersions(input) {
+  const payloadVersionId = input.payloadVersionId?.trim();
+  const manifestVersionId = input.manifestVersionId?.trim();
+  if (Boolean(payloadVersionId) !== Boolean(manifestVersionId)) {
+    throw new Error("Instructions backup payload and manifest version ids must be provided together");
+  }
+  if (!payloadVersionId || !manifestVersionId)
+    return;
+  assertSafeInstructionsObjectVersionId(payloadVersionId);
+  assertSafeInstructionsObjectVersionId(manifestVersionId);
+  return { payloadVersionId, manifestVersionId };
+}
+function encodeBackupId(backupId) {
+  const trimmed = backupId.trim();
+  if (!trimmed || trimmed.length > 128 || trimmed === "." || trimmed === ".." || trimmed.includes("\\") || CONTROL_CHARACTERS.test(trimmed)) {
+    throw new Error("Instructions backup id is invalid");
+  }
+  return encodeURIComponent(trimmed);
+}
+function normalizeContentType(value) {
+  const contentType = value?.trim() || "application/octet-stream";
+  if (contentType.length > 255 || CONTROL_CHARACTERS.test(contentType)) {
+    throw new Error("Instructions backup content type is invalid");
+  }
+  return contentType;
+}
+function normalizeCreatedAt(value) {
+  const date = value ?? new Date;
+  if (!Number.isFinite(date.getTime()))
+    throw new Error("Instructions backup creation timestamp is invalid");
+  return date.toISOString();
+}
+function serializeManifest(manifest) {
+  return encoder.encode(`${JSON.stringify(manifest, null, 2)}
+`);
+}
+function parseManifest(bytes, keys, backupId) {
+  let value;
+  try {
+    value = JSON.parse(decoder.decode(bytes));
+  } catch {
+    throw new Error("Instructions backup manifest is not valid JSON");
+  }
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error("Instructions backup manifest is invalid");
+  }
+  const manifest = value;
+  if (manifest.schema !== INSTRUCTIONS_BACKUP_MANIFEST_SCHEMA || manifest.app !== "instructions" || manifest.backupId !== backupId || manifest.payloadKey !== keys.payloadKey || manifest.manifestKey !== keys.manifestKey || typeof manifest.sha256 !== "string" || !SHA256_PATTERN.test(manifest.sha256) || typeof manifest.sizeBytes !== "number" || !Number.isSafeInteger(manifest.sizeBytes) || manifest.sizeBytes < 0 || typeof manifest.contentType !== "string" || !manifest.contentType || typeof manifest.createdAt !== "string" || !Number.isFinite(Date.parse(manifest.createdAt))) {
+    throw new Error("Instructions backup manifest failed validation");
+  }
+  assertSafeInstructionsObjectKey(manifest.payloadKey);
+  assertSafeInstructionsObjectKey(manifest.manifestKey);
+  return manifest;
+}
+function assertManifestMatchesPayload(manifest, bytes) {
+  const digest = sha256(bytes);
+  if (manifest.sha256 !== digest || manifest.sizeBytes !== bytes.byteLength) {
+    throw new Error("Instructions backup is immutable; the existing backup id refers to different bytes");
+  }
+}
+function assertBytesMatch(bytes, expectedSha256, expectedSize, label) {
+  if (bytes.byteLength !== expectedSize || sha256(bytes) !== expectedSha256) {
+    throw new Error(`Instructions ${label} check failed`);
+  }
+}
+function sha256(bytes) {
+  return new Bun.CryptoHasher("sha256").update(bytes).digest("hex");
+}
+export {
+  verifyInstructionsBackup,
+  pushInstructionsBackup,
+  pullInstructionsBackup,
+  planInstructionsBackupPush,
+  buildInstructionsBackupKeys,
+  INSTRUCTIONS_BACKUP_MANIFEST_SCHEMA
+};

package/dist/chunks/s3-config-hhght91k.js

@@ -0,0 +1,14 @@
+// @bun
+import {
+  INSTRUCTIONS_S3_ALIAS_ENV,
+  INSTRUCTIONS_S3_ENV,
+  loadInstructionsS3Config,
+  normalizeInstructionsS3Prefix
+} from "./index-8rb7ng2y.js";
+import"./index-bsan4c16.js";
+export {
+  normalizeInstructionsS3Prefix,
+  loadInstructionsS3Config,
+  INSTRUCTIONS_S3_ENV,
+  INSTRUCTIONS_S3_ALIAS_ENV
+};

package/dist/chunks/s3-object-store-n0s82swt.js

@@ -0,0 +1,14 @@
+// @bun
+import {
+  assertSafeInstructionsObjectKey,
+  assertSafeInstructionsObjectVersionId,
+  createInstructionsS3ObjectStore,
+  memoryInstructionsObjectStore
+} from "./index-mvckkf15.js";
+import"./index-bsan4c16.js";
+export {
+  memoryInstructionsObjectStore,
+  createInstructionsS3ObjectStore,
+  assertSafeInstructionsObjectVersionId,
+  assertSafeInstructionsObjectKey
+};

package/dist/chunks/{sync-vy1yjvs6.js → sync-q5hvwq6e.js}

@@ -12,11 +12,11 @@ import {
   syncProject,
   syncToDir,
   syncToDisk
-} from "./index-9p9gn7gh.js";
-import"./index-axhwg61p.js";
-import"./index-v7dkb384.js";
+} from "./index-jg8ptcwh.js";
+import"./index-ypcef3a2.js";
+import"./index-aj66f6xr.js";
 import"./index-35z65jsa.js";
-import"./index-pkscjnj5.js";
+import"./index-3djthcm6.js";
 import"./index-nnwp92tk.js";
 export {
   syncToDisk,

package/dist/chunks/{sync-m46fc257.js → sync-xtkbm5br.js}

@@ -12,10 +12,11 @@ import {
   syncProject,
   syncToDir,
   syncToDisk
-} from "./index-85n5wnd8.js";
-import"./index-e9epbsvs.js";
-import"./index-1hpwskwd.js";
-import"./index-pkscjnj5.js";
+} from "./index-pdpg8a44.js";
+import"./index-r7nfef2g.js";
+import"./index-6jncnnw7.js";
+import"./index-n3fjspr0.js";
+import"./index-fpeyzn3n.js";
 import"./index-bsan4c16.js";
 export {
   syncToDisk,

package/dist/chunks/{template-02wjvv05.js → template-fsfxpe4p.js}

@@ -5,7 +5,7 @@ import {
   parseTemplateVars,
   renderTemplate,
   renderTemplatePreview
-} from "./index-pkscjnj5.js";
+} from "./index-3djthcm6.js";
 import"./index-nnwp92tk.js";
 export {
   renderTemplatePreview,

package/dist/chunks/{template-ke972qqe.js → template-wgnzdn7h.js}

@@ -5,7 +5,7 @@ import {
   parseTemplateVars,
   renderTemplate,
   renderTemplatePreview
-} from "./index-pkscjnj5.js";
+} from "./index-n3fjspr0.js";
 import"./index-bsan4c16.js";
 export {
   renderTemplatePreview,