gacama 1.0.1

package/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2025 2Bubs2Go
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
+AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
+OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -0,0 +1,21 @@
+# Gacama - Bub's Game Capture Manager
+Automatically organizes game captures by watching a specified directory for new files, saving metadata to a JSON file, and moving the files to folders based on game titles. It can retrieve the current game title from a text file, a REST API, or a provided function.
+
+Gacama can be run without any explicit configuration, but locations can be customized environment variables:
+
+- `GACAMA_DROPS`: Directory to watch for new capture files (default: `./drops`)
+- `GACAMA_SCREENSHOTS`: Path to the JSON file where metadata will be stored (default: `./screenshots`)
+- `GACAMA_GAME_SOURCE`: Path to retrieve the current game title, either a file path or URL that begins with "http" - this will be ignored if Gacama is provided an external function to use for this (default: `[drops]/game.txt`)
+
+## Development Details
+Basic node.js project. Heavy use of the `fs` module for file system operations, and `chokidar` for watching the drops directory. Claude Code was used for some initial scaffolding and implementation, but most code was written by hand. All code was reviewed and edited by a human.
+
+###  Testing
+Uses native test runner. `npm test` will run unit tests, `npm run test:e2e` will run end-to-end tests.
+
+### Development Practices
+
+- Test-Driven Development (TDD) is followed, meaning that tests are written before implementation code.
+- Simplicity is prioritized in implementations, with a focus on meeting requirements without unnecessary complexity.
+- Code is reviewed and edited by a human to ensure quality and correctness, especially for critical sections of the codebase.
+- Care is taken to ensure low-dependency on external libraries, with a preference for native Node.js modules where possible.

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "gacama",
+  "version": "1.0.1",
+  "description": "Bub's Game Capture Manager",
+  "type": "module",
+  "files": ["src/", "gamaca.js"],
+  "main": "gamaca.js",
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "scripts": {
+    "test": "node --test --experimental-test-module-mocks  'test/**/!(endtoend).test.js'",
+    "test:e2e": "node --test --experimental-test-module-mocks  'test/**/endtoend.test.js'"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+ssh://git@gitlab.com/2Bubs2Go/gacama.git"
+  },
+  "keywords": [
+    "screenshots",
+    "gaming",
+    "game-screenshots",
+    "screenshot-manager",
+    "file-organizer",
+    "image-organizer",
+    "file-watcher",
+    "steam",
+    "game-capture"
+  ],
+  "author": "2Bubs2Go",
+  "license": "ISC",
+  "bugs": {
+    "url": "https://gitlab.com/2Bubs2Go/gacama/issues"
+  },
+  "homepage": "https://gitlab.com/2Bubs2Go/gacama#readme",
+  "dependencies": {
+    "chokidar": "^5.0.0"
+  }
+}

package/src/game.js

@@ -0,0 +1,27 @@
+import { readFile } from 'fs/promises';
+import { getGameNameLocation } from './paths.js';
+import { getNameObject } from '../gacama.js';
+
+export async function getGameName() {
+  const location = getGameNameLocation();
+  
+  let game;
+  if(location.startsWith('http')) {
+    try {
+      const response = await fetch(location);
+      if(response.ok) {
+        game = await response.text();
+      } else {
+        throw new Error(`Failed to fetch game name from ${location}. Status returned: ${response.status}`);
+      }
+    } catch (error) {
+      throw new Error(`Failed to connect to ${location}: ${error.message}`);
+    }
+  } else {
+    game = await readFile(location, 'utf-8');
+  }
+
+  if(!game) return;
+
+  return getNameObject(game);
+}

package/src/paths.js

@@ -0,0 +1,15 @@
+import { resolve } from "node:path";
+
+export const getScreenshotsDirectory = () => 
+  resolve(process.env.GACAMA_SCREENSHOTS || 'screenshots');
+
+export const getDropsDirectory = () =>
+  resolve(process.env.GACAMA_DROPS || 'drops');
+
+export const getGameNameLocation = () => {
+  const location = process.env.GACAMA_GAME_SOURCE || 'game.txt';
+
+  if(location.startsWith('http')) return location;
+
+  return resolve(getDropsDirectory(), location);
+}

package/src/screenshots.js

@@ -0,0 +1,63 @@
+import { mkdir, readFile, writeFile, rename } from "node:fs/promises";
+import { resolve } from "node:path";
+import { getGameName } from "./game.js";
+import { getScreenshotsDirectory } from "./paths.js";
+
+export class ScreenshotManager {
+  constructor(gameNameFn = getGameName) {
+    this.screenshots = {};
+    this.shotsDir = getScreenshotsDirectory();
+    this.jsonPath = resolve('./', this.shotsDir, 'screenshots.json');
+    this.getGameName = gameNameFn;
+  }
+
+  async initialize() {
+    try {
+      this.screenshots = await readFile(this.jsonPath, 'utf-8');
+    } catch {
+      console.log(`Screenshots JSON not found, creating file "${this.jsonPath}".`);
+      await this.save();
+    }
+
+    if(this.screenshots.length) {
+      this.screenshots = JSON.parse(this.screenshots);
+    }
+
+    this.gameCache = await this.getGameName();
+  }
+
+  async save() {
+    await writeFile(this.jsonPath, JSON.stringify(this.screenshots));
+  }
+
+  getLastId() {
+    if(!this.screenshots[this.gameCache.name]) return 0;
+
+    return this.screenshots[this.gameCache.name]
+      .reduce((max, shot) => shot.id > max ? shot.id : max, 0);
+  }
+
+  async addToJSON(id, path) {
+    if(!this.screenshots[this.gameCache.name]) {
+      this.screenshots[this.gameCache.name] = [];
+    }
+
+    this.screenshots[this.gameCache.name].push({
+      id, path, taken: new Date()
+    });
+
+    await this.save();
+  }
+
+  async add(file) {
+    this.gameCache = await this.getGameName();
+
+    const id = this.getLastId() + 1,
+          ext = file.split('.').pop(),
+          newPath = resolve(this.shotsDir, this.gameCache.folder, `${this.gameCache.file}.${id}.${ext}`);
+
+    await mkdir(resolve(this.shotsDir, this.gameCache.folder), { recursive: true });
+    await rename(file, newPath);
+    await this.addToJSON(id, newPath);
+  }
+}