@ericdisero/aurora-shared 0.1.0

package/dist/storage/projects.js

@@ -0,0 +1,85 @@
+// Port of aurora/src/main/storage/projects.ts — identical DB rows + folder
+// semantics so the app and the MCP see one library.
+import { join } from 'node:path';
+import { mkdir, rm } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { v4 as uuidv4 } from 'uuid';
+import { getDb } from '../db.js';
+import { getProjectsDirectory } from '../paths.js';
+function rowToProject(row) {
+    return {
+        id: row.id,
+        name: row.name,
+        dirName: row.dir_name || row.id,
+        createdAt: row.created_at,
+        updatedAt: row.updated_at
+    };
+}
+/** Filesystem-safe slug for human-readable project folders. */
+export function slugify(input, max = 60) {
+    const slug = input
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '')
+        .slice(0, max)
+        .replace(/-+$/g, '');
+    return slug || 'project';
+}
+function uniqueDirName(name) {
+    const base = slugify(name);
+    const root = getProjectsDirectory();
+    const taken = (dir) => existsSync(join(root, dir)) ||
+        Boolean(getDb().prepare('SELECT 1 FROM projects WHERE dir_name = ?').get(dir));
+    if (!taken(base))
+        return base;
+    for (let i = 2;; i++) {
+        const candidate = `${base}-${i}`;
+        if (!taken(candidate))
+            return candidate;
+    }
+}
+/** Absolute path to a project's directory. Legacy projects use their uuid dir. */
+export function getProjectDirectory(projectId) {
+    const row = getDb().prepare('SELECT dir_name FROM projects WHERE id = ?').get(projectId);
+    return join(getProjectsDirectory(), row?.dir_name || projectId);
+}
+export function listProjects() {
+    const rows = getDb()
+        .prepare('SELECT id, name, dir_name, created_at, updated_at FROM projects ORDER BY updated_at DESC')
+        .all();
+    return rows.map(rowToProject);
+}
+export function getProject(id) {
+    const row = getDb()
+        .prepare('SELECT id, name, dir_name, created_at, updated_at FROM projects WHERE id = ?')
+        .get(id);
+    return row ? rowToProject(row) : null;
+}
+export async function createProject(name) {
+    const id = uuidv4();
+    const dirName = uniqueDirName(name);
+    await mkdir(join(getProjectsDirectory(), dirName), { recursive: true });
+    const now = Date.now();
+    // source/audio_path are dormant v0 columns (kept for the migration path).
+    getDb()
+        .prepare(`INSERT INTO projects (id, name, source, audio_path, gen_meta, dir_name, created_at, updated_at)
+       VALUES (?, ?, 'imported', '', NULL, ?, ?, ?)`)
+        .run(id, name.trim() || 'Untitled project', dirName, now, now);
+    return getProject(id);
+}
+/** Rename the project (DB name only — the on-disk folder keeps its name). */
+export function renameProject(id, name) {
+    getDb()
+        .prepare('UPDATE projects SET name = ?, updated_at = ? WHERE id = ?')
+        .run(name.trim() || 'Untitled project', Date.now(), id);
+    return getProject(id);
+}
+export function touchProject(id) {
+    getDb().prepare('UPDATE projects SET updated_at = ? WHERE id = ?').run(Date.now(), id);
+}
+export async function deleteProject(id) {
+    const dir = getProjectDirectory(id);
+    getDb().prepare('DELETE FROM projects WHERE id = ?').run(id);
+    await rm(dir, { recursive: true, force: true }).catch(() => { });
+}
+//# sourceMappingURL=projects.js.map

package/dist/storage/references.d.ts

@@ -0,0 +1,10 @@
+import type { ReferenceTrack } from '../types.js';
+export declare function getReferenceDir(id: string): string;
+export declare function listReferences(): ReferenceTrack[];
+export declare function getReference(id: string): ReferenceTrack | null;
+/** Add a reference row (status 'none'). `copy: false` points the row at the
+ *  given path directly (project-scoped reference assets own their file). */
+export declare function addReference(sourcePath: string, opts?: {
+    copy?: boolean;
+}): Promise<ReferenceTrack>;
+export declare function deleteReference(id: string): Promise<void>;

package/dist/storage/references.js

@@ -0,0 +1,54 @@
+// Port of aurora/src/main/storage/references.ts (userData/references instead
+// of app.getPath).
+import { join, basename, extname } from 'node:path';
+import { mkdir, copyFile, rm } from 'node:fs/promises';
+import { v4 as uuidv4 } from 'uuid';
+import { getDb } from '../db.js';
+import { getReferencesDir } from '../paths.js';
+function rowToReference(row) {
+    return {
+        id: row.id,
+        name: row.name,
+        audioPath: row.audio_path,
+        cachedCurvePath: row.cached_curve_path,
+        curveStatus: row.curve_status,
+        createdAt: row.created_at
+    };
+}
+export function getReferenceDir(id) {
+    return join(getReferencesDir(), id);
+}
+export function listReferences() {
+    const rows = getDb()
+        .prepare('SELECT * FROM reference_tracks ORDER BY created_at DESC')
+        .all();
+    return rows.map(rowToReference);
+}
+export function getReference(id) {
+    const row = getDb().prepare('SELECT * FROM reference_tracks WHERE id = ?').get(id);
+    return row ? rowToReference(row) : null;
+}
+/** Add a reference row (status 'none'). `copy: false` points the row at the
+ *  given path directly (project-scoped reference assets own their file). */
+export async function addReference(sourcePath, opts = {}) {
+    const id = uuidv4();
+    const dir = getReferenceDir(id);
+    await mkdir(dir, { recursive: true });
+    const ext = extname(sourcePath) || '.wav';
+    let audioPath = sourcePath;
+    if (opts.copy !== false) {
+        audioPath = join(dir, `audio${ext}`);
+        await copyFile(sourcePath, audioPath);
+    }
+    const name = basename(sourcePath, ext) || 'Reference';
+    getDb()
+        .prepare(`INSERT INTO reference_tracks (id, name, audio_path, cached_curve_path, curve_status, created_at)
+       VALUES (?, ?, ?, NULL, 'none', ?)`)
+        .run(id, name, audioPath, Date.now());
+    return getReference(id);
+}
+export async function deleteReference(id) {
+    getDb().prepare('DELETE FROM reference_tracks WHERE id = ?').run(id);
+    await rm(getReferenceDir(id), { recursive: true, force: true }).catch(() => { });
+}
+//# sourceMappingURL=references.js.map

package/dist/storage/stems.d.ts

@@ -0,0 +1,13 @@
+import type { ProjectStem, StemType } from '../types.js';
+/** Stems of one split set (an asset's). */
+export declare function getStems(assetId: string): ProjectStem[];
+/** All split sets in a project. */
+export declare function getProjectStems(projectId: string): ProjectStem[];
+/** Upsert a stem row (one per asset+stem_type — the unique index enforces it). */
+export declare function upsertStem(params: {
+    projectId: string;
+    assetId: string;
+    stemType: StemType;
+    path: string;
+    origin: 'mvsep' | 'synthesized';
+}): ProjectStem;

package/dist/storage/stems.js

@@ -0,0 +1,41 @@
+// Port of aurora/src/main/storage/stems.ts.
+import { v4 as uuidv4 } from 'uuid';
+import { getDb } from '../db.js';
+function rowToStem(row) {
+    return {
+        id: row.id,
+        projectId: row.project_id,
+        assetId: row.asset_id,
+        stemType: row.stem_type,
+        path: row.path,
+        origin: row.origin
+    };
+}
+/** Stems of one split set (an asset's). */
+export function getStems(assetId) {
+    const rows = getDb()
+        .prepare('SELECT * FROM project_stems WHERE asset_id = ? ORDER BY stem_type')
+        .all(assetId);
+    return rows.map(rowToStem);
+}
+/** All split sets in a project. */
+export function getProjectStems(projectId) {
+    const rows = getDb()
+        .prepare('SELECT * FROM project_stems WHERE project_id = ? ORDER BY asset_id, stem_type')
+        .all(projectId);
+    return rows.map(rowToStem);
+}
+/** Upsert a stem row (one per asset+stem_type — the unique index enforces it). */
+export function upsertStem(params) {
+    const db = getDb();
+    const id = uuidv4();
+    db.prepare(`INSERT INTO project_stems (id, project_id, asset_id, stem_type, path, origin)
+     VALUES (?, ?, ?, ?, ?, ?)
+     ON CONFLICT(asset_id, stem_type)
+     DO UPDATE SET path = excluded.path, origin = excluded.origin`).run(id, params.projectId, params.assetId, params.stemType, params.path, params.origin);
+    const row = db
+        .prepare('SELECT * FROM project_stems WHERE asset_id = ? AND stem_type = ?')
+        .get(params.assetId, params.stemType);
+    return rowToStem(row);
+}
+//# sourceMappingURL=stems.js.map

package/dist/types.d.ts

@@ -0,0 +1,72 @@
+export interface Project {
+    id: string;
+    name: string;
+    /** Folder name under the projects root. Human-readable slug for new projects;
+     *  legacy projects keep their uuid folder. */
+    dirName: string;
+    createdAt: number;
+    updatedAt: number;
+}
+export type AssetKind = 'generation' | 'cover' | 'import' | 'reference' | 'master';
+export interface ProjectAsset {
+    id: string;
+    projectId: string;
+    kind: AssetKind;
+    name: string;
+    /** Absolute path to the audio file on disk. */
+    path: string;
+    origin?: Record<string, unknown> | null;
+    sourceAssetId?: string | null;
+    refId?: string | null;
+    createdAt: number;
+}
+export declare const STEM_TYPES: readonly ["vocals", "kick", "snare", "toms", "hats", "bass", "ee"];
+export type StemType = (typeof STEM_TYPES)[number];
+export interface ProjectStem {
+    id: string;
+    projectId: string;
+    assetId: string;
+    stemType: StemType;
+    path: string;
+    origin: 'mvsep' | 'synthesized';
+}
+export interface ReferenceTrack {
+    id: string;
+    name: string;
+    audioPath: string;
+    cachedCurvePath: string | null;
+    curveStatus: 'none' | 'analyzing' | 'cached' | 'error';
+    createdAt: number;
+}
+export interface StackLane {
+    id: string;
+    sourceId?: string;
+    name: string;
+    /** Absolute audio path — the truth. */
+    path: string;
+    color?: string;
+    gainDb: number;
+    mute: boolean;
+    solo: boolean;
+    /** Clip start offset from timeline zero, in seconds. */
+    offsetSec: number;
+}
+export interface AppSettings {
+    projectsDirectory: string;
+    outputDirectory: string;
+    defaultGenModel: string;
+    defaultSmoothing: number;
+    defaultBitDepth: 16 | 24 | 32;
+}
+/** A single MVSEP job spec (see aurora docs/build-specs/mvsep-separation-contract.md). */
+export interface MvsepJobSpec {
+    sep_type: string;
+    output_format: string;
+    is_demo: string;
+    add_opt1?: string;
+    add_opt2?: string;
+}
+export interface SeparationResultFile {
+    url: string;
+    filename: string;
+}

package/dist/types.js

@@ -0,0 +1,5 @@
+// Aurora domain types — mirrored from aurora/src/shared/types/index.ts (the
+// locked contract). The MCP works against the SAME DB + project folders as the
+// app, so these shapes must stay in lockstep with the app's schema v1.
+export const STEM_TYPES = ['vocals', 'kick', 'snare', 'toms', 'hats', 'bass', 'ee'];
+//# sourceMappingURL=types.js.map

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@ericdisero/aurora-shared",
+  "version": "0.1.0",
+  "description": "Shared operations layer for the Aurora MCP server and CLI: storage, Suno/MVSEP provider clients, background jobs, and the single tool surface both consume. Most users want @ericdisero/aurora-mcp-server or @ericdisero/aurora-cli instead.",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./operations": "./dist/operations/index.js"
+  },
+  "files": ["dist", "!dist/**/*.map", "skills", "README.md"],
+  "scripts": {
+    "build": "node scripts/embed-skills.mjs && tsc",
+    "typecheck": "node scripts/embed-skills.mjs && tsc --noEmit",
+    "prepublishOnly": "npm run build"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/EricDisero/aurora-mcp.git",
+    "directory": "packages/shared"
+  },
+  "keywords": [
+    "aurora",
+    "mcp",
+    "model-context-protocol",
+    "ai-music",
+    "music-generation",
+    "stem-separation",
+    "suno",
+    "mvsep",
+    "claude"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@ffmpeg-installer/ffmpeg": "^1.1.0",
+    "better-sqlite3": "^11.6.0",
+    "uuid": "^11.0.0",
+    "zod": "^3.23.0"
+  },
+  "devDependencies": {
+    "@types/better-sqlite3": "^7.6.0",
+    "typescript": "^5.7.0"
+  }
+}

package/skills/aurora-cost-discipline.md

@@ -0,0 +1,31 @@
+---
+name: aurora-cost-discipline
+description: Credit and spend discipline for every paid Aurora operation (Suno generation/cover/sounds/WAV, MVSEP splits). Fires before any aurora_generate, aurora_cover, aurora_sounds, aurora_split, or aurora_fetch_wav call.
+---
+
+# Aurora Cost Discipline
+
+Two metered providers sit behind Aurora's cloud ops. Spend is real money. The rules:
+
+## Always
+
+1. **`aurora_get_credits` BEFORE the first paid call of a session** — and after a batch, to log actual spend.
+2. **Never re-split.** `aurora_split` burns real MVSEP credits; the op refuses when 7 stems already exist — don't work around it. Check `aurora_list_assets` first.
+3. **Batch authorization, not per-call nagging.** When the user approves a multi-generation plan ("make me 4 braams and a riser"), that approval covers the enumerated batch — don't re-confirm each call. NEW spend beyond the approved batch needs a fresh ask.
+
+## Known costs (sunoapi.org credits, measured 2026-06-10)
+
+| Op | Cost |
+|---|---|
+| `aurora_sounds` | ~2.5 credits (~$0.0125) — the cheap verification + layer tool |
+| `aurora_cover` | ~12 credits + ~0.4 per WAV fetch |
+| `aurora_fetch_wav` | ~0.4 credits per conversion |
+| `aurora_generate` | not yet measured — check credits before/after and report the delta |
+| `aurora_split` | MVSEP credits, priced by audio duration (separate balance) |
+| `aurora_get_credits`, all local ffmpeg/stack/project ops | FREE |
+
+## Cheap-first ladder
+
+- Verifying a pipeline or experimenting? `aurora_sounds` first (2.5 credits), full `aurora_generate` only when the user wants a track.
+- Audition MP3s before paying for WAV upgrades; `aurora_fetch_wav` only the keepers.
+- Local ops (`aurora_pitch_shift`, `aurora_convert`, stack everything) cost nothing — prefer them over regenerating.

package/skills/aurora-music-production.md

@@ -0,0 +1,43 @@
+---
+name: aurora-music-production
+description: End-to-end Aurora workflow — create a project, generate or cover tracks, manufacture sounds, split into 7 stems, layer in the stack, export aligned WAVs for the DAW. Use when driving Aurora (the AI audio workbench) for any music production task.
+---
+
+# Aurora Music Production Workflow
+
+Aurora is the desktop layer between AI music generation and a real DAW: generate AI music, split anything into stems, keep it all organized. Files on disk ARE the product — everything you create lands in a real project folder the user can open, play, and drag into their DAW.
+
+## Session start
+
+1. `aurora_get_workspace_state` — projects list, key status, folder locations. Once per session.
+2. `aurora_get_credits` — Suno credits + MVSEP minutes. ALWAYS before paid calls (see aurora-cost-discipline).
+
+## The verbs
+
+- **Generate** (`aurora_generate`) — full track from a prompt. 2 variations land as assets. 1-3 min.
+- **Cover** (`aurora_cover`) — style-transform an existing asset or file: same musical content, new style. `audioWeight` is the dial: 0 = new style dominates, 1 = stay close to the source.
+- **Sounds** (`aurora_sounds`) — samples, one-shots, loops with key/tempo lock. Fast (~20-30s), cheap (~2.5 credits). The layer-manufacturing tool: braams, booms, transitions, textures.
+- **Split** (`aurora_split`) — ANY asset → 7 stems (vocals, kick, snare, toms, hats, bass, everything-else). REAL MVSEP credits; never re-split (the op refuses if 7 stems exist).
+- **Stack** (`aurora_stack_*`) — layer assets/stems on lanes with offsets and gain, then `aurora_stack_export` for a sample-aligned multi-WAV bundle (drop at time zero in any DAW).
+
+## Long-op discipline
+
+Generation and splits take minutes. Prefer `background: true` + `aurora_get_job_status` polling every 10-20s:
+
+- Status responses include `streamUrls` while a generation is still cooking — give the user the link, they can LISTEN ~30-45s in, minutes before files land.
+- Split stems land PROGRESSIVELY: vocals/kick/snare/toms/hats/bass appear as each MVSEP job finishes; everything-else (ee) lands last.
+- Jobs survive restarts — `aurora_list_jobs` recovers anything in flight.
+
+## Files + organization
+
+- Project folder: `generations/ covers/ imports/ references/ stems/<asset>/ masters/ stack-export/ stack.json`.
+- MP3 lands first; `aurora_fetch_wav` upgrades a generation/cover to provider WAV (~0.4 credits).
+- `aurora_pitch_shift` and `aurora_convert` are FREE local ffmpeg ops.
+- Mastering (analyze → mix → export) lives in the Aurora app window — point the user there once stems exist; it is not agent-drivable yet.
+
+## Suno prompting quick rules
+
+- Custom mode = set `style` AND `title` together; then `prompt` carries the LYRICS.
+- Non-custom mode: `prompt` is a track description.
+- `negativeTags` is ONE comma-separated string ("Heavy Metal, Upbeat Drums").
+- Sounds prompts: concrete and physical ("huge cinematic braam, dark low brass, trailer hit"), max 500 chars, lock `soundKey`/`tempo` when the track they'll sit in is known.

package/skills/aurora-split-and-stems.md

@@ -0,0 +1,33 @@
+---
+name: aurora-split-and-stems
+description: How Aurora's 7-stem split works (3 MVSEP jobs + phase cancellation), what the stems are, progressive landing, cost rules, and where stems live on disk. Use when calling aurora_split or working with split stems.
+---
+
+# Aurora Split & Stems
+
+## The 7 stems
+
+`vocals, kick, snare, toms, hats, bass, ee` (everything-else). Only 5 come from MVSEP; **hats** and **ee** are synthesized locally by phase cancellation (hats = drums − kick − snare − toms; ee = original − vocals − drums − bass). This is why ee always lands LAST.
+
+## How a split runs
+
+3 parallel MVSEP jobs (vocals model, drum separation, bass model) on one standardized 44.1kHz float32 WAV. Stems land **progressively** as each job finishes:
+
+- vocals job → `vocals`
+- drums job → `kick`, `snare`, `toms`, `hats`
+- bass job → `bass`
+- all three done → `ee`
+
+With `background: true`, `aurora_get_job_status` shows the per-job landing state — the user can start auditioning early stems while the rest cook. Typical total: 3-5 minutes (longer if the MVSEP queue is busy — free-tier keys run 1 concurrent job, so the 3 jobs may serialize).
+
+## Cost rules
+
+- REAL MVSEP credits, priced by audio duration. Check `aurora_get_credits` (mvsepPremiumMinutes) first.
+- **Never re-split**: the op returns existing stems instead of spending again when a full set exists.
+- Any asset kind splits: generations, covers, imports, AND references (split-a-reference is a first-class loop for studying an arrangement).
+
+## On disk
+
+Stems live at `<project>/stems/<asset-slug>-<id6>/*.wav` — 32-bit float, sample-aligned by construction. They are DAW-ready files: stack them (`aurora_stack_add_lane` with `stemType`), pitch them (`aurora_pitch_shift`), rip MIDI from them (`aurora_rip_midi`), or point the user at the folder.
+
+Mastering against a reference (analyze → mix → export) happens in the Aurora app window from any split set — not agent-drivable yet.

package/skills/aurora-suno-prompting.md

@@ -0,0 +1,35 @@
+---
+name: aurora-suno-prompting
+description: Prompting guide for Aurora's Suno-backed generation ops — generate (full tracks), cover (style transforms, the audioWeight dial), and sounds (samples/one-shots/loops with key+tempo lock). Use when writing prompts for aurora_generate, aurora_cover, or aurora_sounds.
+---
+
+# Suno Prompting for Aurora
+
+## aurora_generate — full tracks
+
+Two modes, switched by whether you set `style`/`title`:
+
+- **Description mode** (no style/title): `prompt` describes the track — genre, mood, instrumentation, tempo feel, structure. One coherent paragraph beats keyword soup.
+- **Custom mode** (`style` AND `title` set): `prompt` carries the LYRICS; `style` carries the genre/production language. The provider requires BOTH style and title together.
+
+Controls: `instrumental: true` for no vocals; `vocalGender` male/female; `negativeTags` as ONE comma-separated string of styles to avoid ("Heavy Metal, Upbeat Drums").
+
+## aurora_cover — style transforms
+
+The source's musical content (melody, structure) is kept; the style is replaced.
+
+- `audioWeight` is the single most important dial: **0 = the new style dominates, 1 = stay close to the source.** 0.5-0.7 is the useful middle for "same song, new genre".
+- Custom mode rules are the same: `style` + `title` together, prompt describes the transformation target.
+- Source cap: 8 minutes. Project asset (`sourceAssetId`) or external file (`sourcePath`).
+
+## aurora_sounds — samples, one-shots, loops
+
+The layer-manufacturing tool. Prompts are short (max 500 chars), physical, and concrete:
+
+- Name the sound type: braam, boom, riser, downer, whoosh, impact, drone, texture, loop.
+- Describe the material: "dark low brass", "metallic scrape", "sub-heavy 808", "airy granular pad".
+- Context helps: "trailer hit", "transition", "intro swell".
+- Lock `soundKey` (e.g. "Cm", "F#") and `tempo` (BPM) when the destination track is known — this is the point of the tool.
+- `loop: true` for loopable textures/grooves.
+
+Each call returns 2 variations — audition both before generating more.