pingthings 0.1.0

package/src/cli/play.js

@@ -0,0 +1,127 @@
+import { readConfig, VALID_EVENTS } from '../config.js';
+import { getPackSounds, getEventSounds, pickRandom, resolvePack } from '../packs.js';
+import { playSound } from '../player.js';
+import { basename } from 'node:path';
+
+function parseArgs(args) {
+  const result = { sound: null, event: null };
+
+  for (let i = 0; i < args.length; i++) {
+    if ((args[i] === '--event' || args[i] === '-e') && args[i + 1]) {
+      result.event = args[i + 1];
+      i++;
+    } else if (args[i] === '--help' || args[i] === '-h') {
+      showHelp();
+      process.exit(0);
+    } else if (!args[i].startsWith('-')) {
+      result.sound = args[i];
+    }
+  }
+
+  return result;
+}
+
+function showHelp() {
+  console.log(`
+Usage: pingthings play [sound] [options]
+
+Play a sound from the active pack.
+
+Arguments:
+  sound              Play a specific sound by name (partial match)
+
+Options:
+  --event, -e <type> Play a sound mapped to an event type
+  --help, -h         Show this help message
+
+Event types:
+  done               Task/step finished, awaiting next instruction
+  permission         Needs user approval to continue
+  complete           Whole project or major milestone finished
+  error              Something went wrong
+  blocked            Can't proceed, user action needed
+
+Modes (set via "pingthings config mode <mode>"):
+  random             Play any random sound from the pack (default)
+  specific           Always play the same configured sound
+  informational      Use event mappings — requires --event flag
+
+Examples:
+  pingthings play                     Random sound
+  pingthings play READY               Play sound matching "READY"
+  pingthings play --event done        Play a "done" sound
+  pingthings play -e error            Play an "error" sound
+`);
+}
+
+export default function play(args) {
+  const config = readConfig();
+  const packName = config.activePack;
+  const pack = resolvePack(packName);
+
+  if (!pack) {
+    console.error(`Pack not found: ${packName}`);
+    console.error('Run "pingthings list" to see available packs.');
+    process.exit(1);
+  }
+
+  const parsed = parseArgs(args);
+
+  // Validate event if provided
+  if (parsed.event && !VALID_EVENTS.includes(parsed.event)) {
+    console.error(`Unknown event type: ${parsed.event}`);
+    console.error(`Valid events: ${VALID_EVENTS.join(', ')}`);
+    process.exit(1);
+  }
+
+  let soundFile;
+
+  // If --event flag is provided, use event mapping
+  if (parsed.event) {
+    const eventSounds = getEventSounds(packName, parsed.event);
+    if (eventSounds.length === 0) {
+      // Fall back to random if pack has no mapping for this event
+      const allSounds = getPackSounds(packName);
+      soundFile = pickRandom(allSounds);
+    } else {
+      soundFile = pickRandom(eventSounds);
+    }
+  }
+  // If a specific sound name is provided, find it
+  else if (parsed.sound) {
+    const sounds = getPackSounds(packName);
+    const query = parsed.sound.toLowerCase();
+    soundFile = sounds.find(s => basename(s).toLowerCase().includes(query));
+    if (!soundFile) {
+      console.error(`Sound "${parsed.sound}" not found in pack "${packName}".`);
+      process.exit(1);
+    }
+  }
+  // Informational mode: requires --event (show help if missing)
+  else if (config.mode === 'informational') {
+    console.error('Informational mode requires an event type.');
+    console.error('Usage: pingthings play --event <done|permission|complete|error|blocked>');
+    console.error('Or switch mode: pingthings config mode random');
+    process.exit(1);
+  }
+  // Specific mode: always play the configured sound
+  else if (config.mode === 'specific' && config.specificSound) {
+    const sounds = getPackSounds(packName);
+    const query = config.specificSound.toLowerCase();
+    soundFile = sounds.find(s => basename(s).toLowerCase().includes(query));
+    if (!soundFile) {
+      soundFile = pickRandom(sounds);
+    }
+  }
+  // Random mode (default)
+  else {
+    const sounds = getPackSounds(packName);
+    if (sounds.length === 0) {
+      console.error(`No sounds found in pack: ${packName}`);
+      process.exit(1);
+    }
+    soundFile = pickRandom(sounds);
+  }
+
+  playSound(soundFile);
+}

package/src/cli/preview.js

@@ -0,0 +1,30 @@
+import { getPackSounds, pickRandom, resolvePack } from '../packs.js';
+import { playSound } from '../player.js';
+import { basename } from 'node:path';
+
+export default function preview(args) {
+  const packName = args[0];
+
+  if (!packName) {
+    console.error('Usage: pingthings preview <pack>');
+    console.error('Run "pingthings list" to see available packs.');
+    process.exit(1);
+  }
+
+  const pack = resolvePack(packName);
+  if (!pack) {
+    console.error(`Pack not found: ${packName}`);
+    console.error('Run "pingthings list" to see available packs.');
+    process.exit(1);
+  }
+
+  const sounds = getPackSounds(packName);
+  if (sounds.length === 0) {
+    console.error(`No sounds found in pack: ${packName}`);
+    process.exit(1);
+  }
+
+  const sound = pickRandom(sounds);
+  console.log(`Playing: ${basename(sound)} from "${packName}"`);
+  playSound(sound);
+}

package/src/cli/use.js

@@ -0,0 +1,25 @@
+import { readConfig, writeConfig } from '../config.js';
+import { resolvePack } from '../packs.js';
+
+export default function use(args) {
+  const packName = args[0];
+
+  if (!packName) {
+    console.error('Usage: pingthings use <pack>');
+    console.error('Run "pingthings list" to see available packs.');
+    process.exit(1);
+  }
+
+  const pack = resolvePack(packName);
+  if (!pack) {
+    console.error(`Pack not found: ${packName}`);
+    console.error('Run "pingthings list" to see available packs.');
+    process.exit(1);
+  }
+
+  const config = readConfig();
+  config.activePack = packName;
+  writeConfig(config);
+
+  console.log(`Active pack set to: ${packName}`);
+}

package/src/config.js

@@ -0,0 +1,48 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync, renameSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+
+const DEFAULTS = {
+  activePack: '7kaa-soldiers',
+  mode: 'random',
+  specificSound: null,
+};
+
+export function getConfigDir() {
+  const base = process.env.XDG_CONFIG_HOME || join(homedir(), '.config');
+  const dir = join(base, 'pingthings');
+  mkdirSync(dir, { recursive: true });
+  return dir;
+}
+
+export function getConfigPath() {
+  return join(getConfigDir(), 'config.json');
+}
+
+export function readConfig() {
+  const configPath = getConfigPath();
+  if (!existsSync(configPath)) {
+    return { ...DEFAULTS };
+  }
+  try {
+    const raw = readFileSync(configPath, 'utf8');
+    return { ...DEFAULTS, ...JSON.parse(raw) };
+  } catch {
+    return { ...DEFAULTS };
+  }
+}
+
+export function writeConfig(config) {
+  const configPath = getConfigPath();
+  const tmpPath = configPath + '.tmp';
+  writeFileSync(tmpPath, JSON.stringify(config, null, 2) + '\n', 'utf8');
+  renameSync(tmpPath, configPath);
+}
+
+export function getDefaults() {
+  return { ...DEFAULTS };
+}
+
+export const VALID_MODES = ['random', 'specific', 'informational'];
+
+export const VALID_EVENTS = ['done', 'permission', 'complete', 'error', 'blocked'];

package/src/packs.js

@@ -0,0 +1,130 @@
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { join, extname, basename } from 'node:path';
+import { dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { getConfigDir } from './config.js';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const BUILT_IN_PACKS_DIR = join(__dirname, '..', 'packs');
+const AUDIO_EXTENSIONS = new Set(['.wav', '.mp3', '.ogg', '.flac']);
+
+function getUserPacksDir() {
+  return join(getConfigDir(), 'packs');
+}
+
+function readManifest(packDir) {
+  const manifestPath = join(packDir, 'manifest.json');
+  if (!existsSync(manifestPath)) return null;
+  try {
+    return JSON.parse(readFileSync(manifestPath, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+function discoverSounds(packDir) {
+  const soundsDir = join(packDir, 'sounds');
+  const searchDir = existsSync(soundsDir) ? soundsDir : packDir;
+
+  try {
+    return readdirSync(searchDir)
+      .filter(f => AUDIO_EXTENSIONS.has(extname(f).toLowerCase()))
+      .map(f => join(searchDir, f))
+      .sort();
+  } catch {
+    return [];
+  }
+}
+
+function scanDirectory(dir, isBuiltIn) {
+  if (!existsSync(dir)) return [];
+
+  return readdirSync(dir, { withFileTypes: true })
+    .filter(d => d.isDirectory())
+    .map(d => {
+      const packDir = join(dir, d.name);
+      const manifest = readManifest(packDir);
+      const sounds = discoverSounds(packDir);
+
+      return {
+        name: manifest?.name || d.name,
+        description: manifest?.description || '',
+        license: manifest?.license || 'Unknown',
+        credits: manifest?.credits || '',
+        location: packDir,
+        soundCount: sounds.length,
+        isBuiltIn,
+      };
+    })
+    .filter(p => p.soundCount > 0);
+}
+
+export function listPacks() {
+  const builtIn = scanDirectory(BUILT_IN_PACKS_DIR, true);
+  const user = scanDirectory(getUserPacksDir(), false);
+
+  // User packs override built-in packs with the same name
+  const names = new Set(user.map(p => p.name));
+  const merged = [...user, ...builtIn.filter(p => !names.has(p.name))];
+
+  return merged.sort((a, b) => a.name.localeCompare(b.name));
+}
+
+export function resolvePack(name) {
+  // Check user packs first (override built-in)
+  const userDir = join(getUserPacksDir(), name);
+  if (existsSync(userDir)) {
+    const manifest = readManifest(userDir);
+    return { name, dir: userDir, manifest };
+  }
+
+  // Check built-in packs
+  const builtInDir = join(BUILT_IN_PACKS_DIR, name);
+  if (existsSync(builtInDir)) {
+    const manifest = readManifest(builtInDir);
+    return { name, dir: builtInDir, manifest };
+  }
+
+  return null;
+}
+
+export function getPackSounds(name) {
+  const pack = resolvePack(name);
+  if (!pack) return [];
+
+  // Use manifest sounds list if available
+  if (pack.manifest?.sounds?.length) {
+    return pack.manifest.sounds
+      .map(s => join(pack.dir, s))
+      .filter(f => existsSync(f));
+  }
+
+  return discoverSounds(pack.dir);
+}
+
+export function getEventSounds(name, event) {
+  const pack = resolvePack(name);
+  if (!pack) return [];
+
+  const eventSounds = pack.manifest?.events?.[event];
+  if (!eventSounds?.length) return [];
+
+  return eventSounds
+    .map(s => join(pack.dir, s))
+    .filter(f => existsSync(f));
+}
+
+export function getPackEvents(name) {
+  const pack = resolvePack(name);
+  if (!pack) return [];
+
+  const events = pack.manifest?.events;
+  if (!events) return [];
+
+  return Object.keys(events);
+}
+
+export function pickRandom(sounds) {
+  if (sounds.length === 0) return null;
+  return sounds[Math.floor(Math.random() * sounds.length)];
+}

package/src/player.js

@@ -0,0 +1,39 @@
+import { spawn } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { platform } from 'node:os';
+
+function getPlayerCommand() {
+  switch (platform()) {
+    case 'darwin':
+      return 'afplay';
+    case 'linux': {
+      // Prefer PulseAudio/PipeWire, fall back to ALSA
+      try {
+        const result = spawn('which', ['paplay'], { stdio: 'pipe' });
+        return 'paplay';
+      } catch {
+        return 'aplay';
+      }
+    }
+    default:
+      return null;
+  }
+}
+
+export function playSound(filePath) {
+  if (!existsSync(filePath)) {
+    throw new Error(`Sound file not found: ${filePath}`);
+  }
+
+  const cmd = getPlayerCommand();
+  if (!cmd) {
+    throw new Error(`Unsupported platform: ${platform()}. Supported: macOS, Linux.`);
+  }
+
+  const child = spawn(cmd, [filePath], {
+    detached: true,
+    stdio: 'ignore',
+  });
+
+  child.unref();
+}