@audiofool/moondog 0.1.0

package/src/memory/reflection-worker.mjs

@@ -0,0 +1,87 @@
+import {
+  createConfiguredMemoryAgentRuntime,
+  MAX_REFLECTION_EPISODES,
+  MEMORY_AGENT_WORKER_VERSION,
+} from "../runtime/pi/memory-agent-runtime.mjs";
+
+function reflectionErrorCode(error) {
+  const message = String(error?.message ?? "");
+  if (/did not submit|exact episode|structured reflection/iu.test(message)) {
+    return "model_output_invalid";
+  }
+  if (/model request failed|provider/iu.test(message)) return "model_failed";
+  return "reflection_failed";
+}
+
+function offlineRuntimeError(reason) {
+  if (reason === "provider_authentication_required") {
+    return new Error(
+      "The Memory Agent requires OpenAI Codex authentication. Run moondog auth login openai-codex first.",
+    );
+  }
+  return new Error(
+    "The Memory Agent model is offline. Choose a model with /model or configure MOONDOG_PROVIDER and MOONDOG_MODEL.",
+  );
+}
+
+export async function runMemoryReflection({
+  application,
+  environment = process.env,
+  trigger = "manual",
+  dryRun = false,
+  runtimeFactory = createConfiguredMemoryAgentRuntime,
+  limit = MAX_REFLECTION_EPISODES,
+} = {}) {
+  if (!application) throw new TypeError("Memory reflection needs an application");
+
+  const pending = application.pendingMemoryReflection({ limit });
+  if (pending.length === 0) {
+    return {
+      state: "no_work",
+      examined_episodes: 0,
+      message: "No unprocessed memory episodes are ready for reflection.",
+    };
+  }
+
+  const runtime = await runtimeFactory(environment);
+  const runtimeStatus = runtime.publicStatus();
+  if (runtimeStatus.state !== "configured") {
+    throw offlineRuntimeError(runtimeStatus.reason);
+  }
+
+  const run = application.beginMemoryReflection({
+    trigger,
+    workerVersion: MEMORY_AGENT_WORKER_VERSION,
+    provider: runtimeStatus.provider,
+    model: runtimeStatus.model,
+    limit,
+    leaseMs: 15 * 60 * 1_000,
+  });
+  if (run.state !== "started") {
+    return {
+      state: run.state,
+      ...(run.active_run ? { active_run: run.active_run } : {}),
+      examined_episodes: 0,
+    };
+  }
+
+  try {
+    const reflected = await runtime.reflect({
+      episodes: run.episodes,
+      activeMemories: run.active_memories,
+    });
+    return application.completeMemoryReflection({
+      runId: run.run_id,
+      leaseToken: run.lease_token,
+      proposals: reflected.proposals,
+      dryRun,
+    });
+  } catch (error) {
+    application.failMemoryReflection(
+      run.run_id,
+      run.lease_token,
+      reflectionErrorCode(error),
+    );
+    throw error;
+  }
+}

package/src/profile/apple-library-import.mjs

@@ -0,0 +1,28 @@
+import { mkdir } from "node:fs/promises";
+import path from "node:path";
+
+import { resolveAppleMusicImportsRoot } from "../core/apple-library-source-status.mjs";
+import { resolveAppleMusicProjectionPath } from "../core/apple-projection-domain-services.mjs";
+import { writeAppleMusicImportBatch, rebuildAppleMusicSqliteProjection } from "../importers/apple-music-library/index.mjs";
+
+export async function persistAppleLibraryImport(bundle, { environment = process.env } = {}) {
+  const outputRoot = resolveAppleMusicImportsRoot(environment);
+  const boundaryRoot = path.dirname(outputRoot);
+  await mkdir(boundaryRoot, { recursive: true, mode: 0o700 });
+  const result = await writeAppleMusicImportBatch(bundle, { outputRoot, boundaryRoot });
+  return {
+    provider: "apple-music-library",
+    already_imported: result.status === "unchanged",
+    library_tracks: result.manifest.counts.track_refs,
+  };
+}
+
+export async function refreshAppleLibraryImport({ environment = process.env } = {}) {
+  const databasePath = resolveAppleMusicProjectionPath(environment);
+  // The existing writer requires its output to be below an existing boundary.
+  const boundaryRoot = path.dirname(path.dirname(databasePath));
+  await mkdir(boundaryRoot, { recursive: true, mode: 0o700 });
+  return rebuildAppleMusicSqliteProjection({
+    importsRoot: resolveAppleMusicImportsRoot(environment), databasePath, boundaryRoot,
+  });
+}

package/src/profile/history-import.mjs

@@ -0,0 +1,163 @@
+import { lstat } from "node:fs/promises";
+import { homedir } from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { readSpotifyHistoryArchive } from "../integrations/spotify/history-archive.mjs";
+import { readListenBrainzHistoryFile } from "../integrations/listenbrainz/history-file.mjs";
+import { projectSpotifyRecentActivity } from "../integrations/spotify/recent-activity.mjs";
+import { buildAppleMusicLibraryImport } from "../importers/apple-music-library/index.mjs";
+import { readYouTubeMusicTakeout } from "../integrations/youtube-music/takeout.mjs";
+import { readPublicPlaylist } from "../integrations/public-playlists.mjs";
+
+export function prepareSpotifyRecentImport({ page, subjectId, capturedAt = new Date().toISOString() }) {
+  const bundle = projectSpotifyRecentActivity({ page, subjectId, capturedAt });
+  const dates = bundle.listening_events.map((event) => event.occurred_at).sort();
+  return {
+    provider: "spotify-recent",
+    bundle,
+    preview: {
+      sourceLabel: "Spotify recent listening",
+      listeningEvents: bundle.listening_events.length,
+      tracks: bundle.track_refs.length,
+      earliestListeningAt: dates[0],
+      latestListeningAt: dates.at(-1),
+      eventsWithPlayedMs: 0,
+      scopeNote: "Your latest plays, up to 50. Spotify doesn't say how long you listened here. A history ZIP can add the older ones later.",
+    },
+  };
+}
+
+function fail(code, message) {
+  const error = new Error(message);
+  error.code = code;
+  throw error;
+}
+
+function literalPath(input) {
+  if (typeof input !== "string" || !input.trim()) {
+    fail("history_import_path_required", "Paste one music export file path or a QQ Music / NetEase playlist share link.");
+  }
+  let value = input.trim();
+  if (/[\u0000-\u001f\u007f]/u.test(value)) {
+    fail("history_import_path_invalid", "Paste one file path on a single line.");
+  }
+  const quote = ["'", '"'].includes(value[0]) ? value[0] : null;
+  if (quote) {
+    if (value.at(-1) !== quote) {
+      fail("history_import_path_invalid", "The quoted path is incomplete. Paste the complete file path.");
+    }
+    value = value.slice(1, -1);
+  }
+  let decoded = "";
+  for (let index = 0; index < value.length; index += 1) {
+    const character = value[index];
+    if (quote && character === quote) {
+      fail("history_import_path_invalid", "Paste one complete file path, not several quoted arguments.");
+    }
+    if (character === "\\" && quote !== "'") {
+      const next = value[index + 1];
+      const allowed = quote === '"' ? /["\\$`]/u : /[ \t()\[\]{}!&;'"\\#$~`]/u;
+      if (!next || !allowed.test(next)) {
+        fail("history_import_path_invalid", "The path has an unsupported escape. Paste the plain path, including its spaces.");
+      }
+      decoded += next;
+      index += 1;
+    } else {
+      decoded += character;
+    }
+  }
+  if (!decoded) fail("history_import_path_required", "Paste a file path between the quotes.");
+  if (/^file:/iu.test(decoded)) {
+    try {
+      const url = new URL(decoded);
+      if (url.hostname && url.hostname !== "localhost") throw new Error();
+      if (url.search || url.hash || url.username || url.password || url.port) throw new Error();
+      decoded = fileURLToPath(url);
+    } catch {
+      fail("history_import_path_invalid", "Use a local file:// URL with no remote host, query, or fragment, or paste the file path.");
+    }
+  } else if (/^[a-z][a-z0-9+.-]*:\/\//iu.test(decoded)) {
+    fail("history_import_path_invalid", "Choose a downloaded local file. Remote URLs are not imported.");
+  }
+  if (decoded === "~" || decoded.startsWith("~/")) decoded = path.join(homedir(), decoded.slice(1));
+  else if (decoded.startsWith("~")) fail("history_import_path_invalid", "Use ~/ for your home folder, or paste the full file path.");
+  return path.resolve(decoded);
+}
+
+export async function prepareHistoryImport({ filePath, subjectId, provider: selectedProvider, capturedAt = new Date().toISOString(), fetchImpl } = {}) {
+  if (/https?:\/\//iu.test(filePath ?? "") && !String(filePath).startsWith("file:")) {
+    return readPublicPlaylist({ input: filePath, subjectId, capturedAt, provider: selectedProvider, fetchImpl });
+  }
+  const resolvedPath = literalPath(filePath);
+  let file;
+  try {
+    file = await lstat(resolvedPath);
+  } catch (error) {
+    if (error.code === "ENOENT" || error.code === "ENOTDIR") {
+      fail("history_import_file_missing", `File not found: ${resolvedPath}. Paste the path to the downloaded file.`);
+    }
+    fail("history_import_file_unreadable", `Could not read ${resolvedPath}. Check that the file is accessible.`);
+  }
+  if (file.isDirectory()) {
+    fail("history_import_directory", "This is a folder. Choose the downloaded music export file inside it, or the original ZIP.");
+  }
+  if (!file.isFile()) fail("history_import_file_invalid", "Choose a regular music export file.");
+  const extension = path.extname(resolvedPath).toLowerCase();
+  if (selectedProvider === "youtube_music" || extension === ".csv" || /^(?:watch-history|takeout)[-.]/iu.test(path.basename(resolvedPath))) {
+    if (![".csv", ".json", ".zip"].includes(extension)) fail("history_import_format_unsupported", "Choose your Takeout ZIP, music-library-songs.csv or watch-history.json. For history, select JSON in Takeout instead of HTML.");
+    return readYouTubeMusicTakeout({ filePath: resolvedPath, subjectId, capturedAt });
+  }
+  if (extension === ".xml") {
+    const bundle = await buildAppleMusicLibraryImport(resolvedPath, { subjectId });
+    return {
+      provider: "apple-music-library",
+      bundle,
+      preview: {
+        kind: "library",
+        sourceLabel: "Apple Music library",
+        fileName: path.basename(resolvedPath),
+        tracks: bundle.trackRefs.length,
+        capturedAt: bundle.manifest.source.captured_at,
+        scopeNote: "Your library with loves, ratings, play counts and when you last played each song. It doesn't list every play.",
+      },
+    };
+  }
+  if (![".zip", ".json"].includes(extension)) {
+    fail("history_import_format_unsupported", "This format is not supported. Choose a Spotify history ZIP, Apple Music library XML, YouTube Music Takeout ZIP/CSV/JSON or saved ListenBrainz JSON.");
+  }
+  const provider = extension === ".zip" ? "spotify" : "listenbrainz";
+  let bundle;
+  try {
+    bundle = provider === "spotify"
+      ? await readSpotifyHistoryArchive({ archivePath: resolvedPath, subjectId, capturedAt })
+      : await readListenBrainzHistoryFile({ filePath: resolvedPath, subjectId, capturedAt });
+  } catch (error) {
+    if (provider === "listenbrainz" && error.code === "listenbrainz_history_invalid") {
+      error.message += " If this is a Spotify export, choose the original ZIP instead of an extracted JSON file.";
+    }
+    throw error;
+  }
+  const extended = bundle.import_batch.data_scope === "lifetime_extended_streaming_history";
+  return {
+    provider,
+    bundle,
+    preview: {
+      sourceLabel: provider === "listenbrainz" ? "ListenBrainz history" : extended ? "Spotify Extended Streaming History" : "Spotify Account Data",
+      fileName: path.basename(resolvedPath),
+      sourceFormat: bundle.import_batch.source_format,
+      dataScope: bundle.import_batch.data_scope,
+      listeningEvents: bundle.listening_events.length,
+      tracks: bundle.track_refs.length,
+      earliestListeningAt: bundle.import_batch.earliest_occurred_at,
+      latestListeningAt: bundle.import_batch.latest_occurred_at,
+      eventsWithPlayedMs: bundle.listening_events.filter((event) => Number.isSafeInteger(event.played_ms)).length,
+      profileEvidence: bundle.profile_evidence?.length ?? 0,
+      scopeNote: provider === "listenbrainz"
+        ? "Your saved listens. Some don't say how long you listened, so they count as plays without minutes."
+        : extended
+          ? "Every play in this file, with how long you listened and how each song started and ended."
+          : "Your plays from the past year, plus your library and playlists. For older plays and listening time, use Extended streaming history.",
+    },
+  };
+}

package/src/profile/listener-corrections.mjs

@@ -0,0 +1,217 @@
+import { randomUUID } from "node:crypto";
+
+import { isUuid, uuidV5 } from "../core/uuid-v5.mjs";
+
+export const LISTENER_CORRECTION_SCHEMA_VERSION = 1;
+export const LISTENER_CORRECTION_ENTITY_NAMESPACE =
+  "6bcb265e-ce6d-5ab9-8471-7d6b40c95ba6";
+export const LISTENER_CORRECTION_ENTITY_TYPES = Object.freeze([
+  "artist",
+  "track",
+]);
+export const LISTENER_CORRECTION_STANCES = Object.freeze([
+  "like",
+  "avoid",
+]);
+
+function cleanText(value, label, maximum = 512) {
+  if (typeof value !== "string") throw new TypeError(`${label} is required`);
+  const cleaned = value
+    .replace(/[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f-\u009f]/gu, "")
+    .replace(/[\u202a-\u202e\u2066-\u2069]/gu, "")
+    .replace(/\s+/gu, " ")
+    .trim();
+  if (!cleaned || Array.from(cleaned).length > maximum) {
+    throw new TypeError(`${label} is invalid`);
+  }
+  return cleaned;
+}
+
+function optionalNote(value) {
+  if (value === undefined || value === null) return null;
+  return cleanText(value, "Listener correction note", 2_000);
+}
+
+function timestamp(value, label) {
+  const milliseconds = Date.parse(value);
+  if (typeof value !== "string" || !Number.isFinite(milliseconds)) {
+    throw new TypeError(`${label} is invalid`);
+  }
+  return new Date(milliseconds).toISOString();
+}
+
+function normalizedIdentity(value) {
+  return value.normalize("NFKC").toLocaleLowerCase("und");
+}
+
+function correctionTarget({ entityType, label, artistCredit }) {
+  if (!LISTENER_CORRECTION_ENTITY_TYPES.includes(entityType)) {
+    throw new TypeError(
+      `Listener correction entity type must be one of: ${LISTENER_CORRECTION_ENTITY_TYPES.join(", ")}`,
+    );
+  }
+  const cleanedLabel = cleanText(label, "Listener correction label");
+  const cleanedArtist = entityType === "track"
+    ? cleanText(artistCredit, "Listener correction track artist")
+    : null;
+  const identity = [
+    entityType,
+    normalizedIdentity(cleanedLabel),
+    ...(cleanedArtist ? [normalizedIdentity(cleanedArtist)] : []),
+  ].join("\0");
+  const entityId = uuidV5(identity, LISTENER_CORRECTION_ENTITY_NAMESPACE);
+  return {
+    target: {
+      entity_type: entityType,
+      entity_id: entityId,
+      entity_revision: 1,
+      label: cleanedLabel,
+    },
+    targetKey: `${entityType}:${entityId}`,
+    artistCredit: cleanedArtist,
+  };
+}
+
+function eventId(value, label) {
+  const id = value ?? randomUUID();
+  if (!isUuid(id)) throw new TypeError(`${label} is invalid`);
+  return id.toLowerCase();
+}
+
+export function createListenerCorrection({
+  subjectId,
+  entityType,
+  label,
+  artistCredit,
+  stance,
+  note,
+  occurredAt,
+  recordedAt = occurredAt,
+  supersedesCorrectionId,
+  correctionId,
+} = {}) {
+  if (!isUuid(subjectId)) {
+    throw new TypeError("Listener correction subject is invalid");
+  }
+  if (!LISTENER_CORRECTION_STANCES.includes(stance)) {
+    throw new TypeError(
+      `Listener correction stance must be one of: ${LISTENER_CORRECTION_STANCES.join(", ")}`,
+    );
+  }
+  const occurred = timestamp(occurredAt, "Listener correction occurrence time");
+  const recorded = timestamp(recordedAt, "Listener correction recording time");
+  if (occurred > recorded) {
+    throw new TypeError("Listener correction cannot be recorded before it occurred");
+  }
+  const correctionTargetValue = correctionTarget({
+    entityType,
+    label,
+    artistCredit,
+  });
+  const supersedes = supersedesCorrectionId === undefined
+    ? null
+    : eventId(supersedesCorrectionId, "Superseded listener correction ID");
+  const cleanedNote = optionalNote(note);
+  const id = eventId(correctionId, "Listener correction ID");
+  if (supersedes === id) {
+    throw new TypeError("A listener correction cannot supersede itself");
+  }
+  const record = {
+    schema_version: LISTENER_CORRECTION_SCHEMA_VERSION,
+    taste_event_id: id,
+    subject_id: subjectId.toLowerCase(),
+    operation: "assert",
+    occurred_at: occurred,
+    recorded_at: recorded,
+    target: correctionTargetValue.target,
+    signal_type: stance === "like" ? "preference" : "avoidance",
+    polarity: stance === "like" ? "positive" : "negative",
+    strength: 1,
+    explicitness: "explicit",
+    provenance: {
+      source_kind: "user_input",
+      captured_at: recorded,
+    },
+    extensions: {
+      "moondog.correction_scope": "label_scoped",
+      ...(correctionTargetValue.artistCredit
+        ? { "moondog.artist_credit": correctionTargetValue.artistCredit }
+        : {}),
+    },
+    ...(cleanedNote ? { note: cleanedNote } : {}),
+    ...(supersedes ? { supersedes_taste_event_id: supersedes } : {}),
+  };
+  return {
+    record,
+    targetKey: correctionTargetValue.targetKey,
+    stance,
+  };
+}
+
+export function createListenerCorrectionRetraction({
+  subjectId,
+  retractsCorrectionId,
+  occurredAt,
+  recordedAt = occurredAt,
+  correctionId,
+} = {}) {
+  if (!isUuid(subjectId)) {
+    throw new TypeError("Listener correction subject is invalid");
+  }
+  const occurred = timestamp(
+    occurredAt,
+    "Listener correction retraction occurrence time",
+  );
+  const recorded = timestamp(
+    recordedAt,
+    "Listener correction retraction recording time",
+  );
+  if (occurred > recorded) {
+    throw new TypeError(
+      "Listener correction retraction cannot be recorded before it occurred",
+    );
+  }
+  const id = eventId(correctionId, "Listener correction retraction ID");
+  const retracts = eventId(
+    retractsCorrectionId,
+    "Retracted listener correction ID",
+  );
+  if (id === retracts) {
+    throw new TypeError("A listener correction cannot retract itself");
+  }
+  return {
+    schema_version: LISTENER_CORRECTION_SCHEMA_VERSION,
+    taste_event_id: id,
+    subject_id: subjectId.toLowerCase(),
+    operation: "retract",
+    occurred_at: occurred,
+    recorded_at: recorded,
+    retracts_taste_event_id: retracts,
+    provenance: {
+      source_kind: "user_input",
+      captured_at: recorded,
+    },
+  };
+}
+
+export function listenerCorrectionTargetKey(record) {
+  if (
+    !record ||
+    record.operation !== "assert" ||
+    !LISTENER_CORRECTION_ENTITY_TYPES.includes(record.target?.entity_type) ||
+    typeof record.target?.label !== "string"
+  ) {
+    throw new TypeError("Listener correction target is invalid");
+  }
+  if (!isUuid(record.target.entity_id)) {
+    throw new TypeError("Listener correction target ID is invalid");
+  }
+  const artistCredit = record.extensions?.["moondog.artist_credit"];
+  if (record.target.entity_type === "track") {
+    cleanText(
+      artistCredit,
+      "Listener correction track artist",
+    );
+  }
+  return `${record.target.entity_type}:${record.target.entity_id.toLowerCase()}`;
+}