argonuts 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 the Argonuts Core contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,119 @@
-# Temporary Holding Version
+# argonuts
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Your media library from the terminal. `argonuts` keeps a list of your media folders, scans them for
+videos and pictures, and keeps their thumbnails ready. It is the terminal companion of Argonuts Core.
+
+```sh
+npx argonuts@latest library add ~/Movies
+npx argonuts@latest scan
+```
+
+## Install
+
+`argonuts` runs on Node.js 20 or later, which brings the `npx` and `npm` commands with it. If
+`npx --version` already prints a version, skip to step 3.
+
+### Windows (x64 and ARM)
+
+1. Install Node.js. In Command Prompt or PowerShell:
+
+   ```bat
+   winget install --exact --id OpenJS.NodeJS.LTS --source winget
+   ```
+
+   `--source winget` takes Node.js from winget's own catalog and skips the store source (`msstore`),
+   which fails on some networks. Or use the Windows installer from the Node.js website.
+
+2. Close the terminal and open a new one, so it finds the new commands. Check that it worked:
+
+   ```bat
+   node --version
+   npx --version
+   ```
+
+3. Try argonuts, in Command Prompt:
+
+   ```bat
+   npx argonuts@latest --version
+   npx argonuts@latest library add "%USERPROFILE%\Videos"
+   npx argonuts@latest scan
+   ```
+
+   In PowerShell, write the folder as `"$HOME\Videos"`. If PowerShell answers _running scripts is
+   disabled on this system_, type `npx.cmd` instead of `npx` (and `argonuts.cmd` instead of
+   `argonuts`), or use Command Prompt. There is no need to change the execution policy.
+
+### macOS (Apple Silicon and Intel)
+
+1. Install Node.js with Homebrew (`brew install node`), or use the macOS installer from the Node.js
+   website.
+2. Open a new Terminal window and check: `node --version` and `npx --version`.
+3. Try argonuts:
+
+   ```sh
+   npx argonuts@latest --version
+   npx argonuts@latest library add ~/Movies
+   npx argonuts@latest scan
+   ```
+
+### Keep it installed
+
+`npx` downloads argonuts the first time and reuses it afterwards. To type just `argonuts`, install it
+once:
+
+```sh
+npm install --global argonuts
+argonuts scan
+```
+
+Update it later with the same command.
+
+### When something goes wrong
+
+| What you see                                             | What to do                                                                                                                                               |
+| -------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `'npx' is not recognized` or `command not found: npx`    | Node.js isn't installed, or the terminal was opened before it was. Do step 1, then open a new terminal                                                   |
+| winget: `Failed when searching source: msstore`          | The store source isn't reachable from this network (often a certificate error). Add `--source winget`, as in step 1                                      |
+| PowerShell: `running scripts is disabled on this system` | Use `npx.cmd` / `argonuts.cmd`, or Command Prompt                                                                                                        |
+| `argonuts has no build for … yet`                        | Your computer isn't supported yet: Linux comes next                                                                                                      |
+| `@argonuts/cli-… is not installed`                       | npm skipped the part made for your computer. Run the command again; if you set npm to leave out optional packages (`omit=optional`), remove that setting |
+| Windows blocks `argonuts-cli`                            | Version 0.1's programs aren't signed yet. On Windows 11 with Smart App Control turned on, they can't run; signed builds are planned                      |
+
+## Commands
+
+| Command                            | What it does                                                             |
+| ---------------------------------- | ------------------------------------------------------------------------ |
+| `argonuts library`                 | Your library's folders and their last scans                              |
+| `argonuts library add <folder>...` | Add folders to your library                                              |
+| `argonuts library remove <folder>` | Remove a folder; its last scan stays on disk                             |
+| `argonuts scan [<folder>...]`      | Scan every library folder, or the folders named, which join your library |
+| `argonuts scan --cached-only`      | Use earlier thumbnails only and run no ffmpeg                            |
+| `argonuts --version`               | The versions of argonuts and argonuts-cli                                |
+
+Ctrl-C stops a scan; a second Ctrl-C stops it at once. A scan reads your files and never changes
+them.
+
+## Where your library is kept
+
+In the core's data folder, shared with the Argonuts desktop app:
+
+- macOS: `~/Library/Application Support/Argonuts`
+- Windows: `%LOCALAPPDATA%\Argonuts`
+
+Set `ARGONUTS_DATA_DIR` to keep it somewhere else.
+
+## Computers it runs on
+
+macOS on Apple Silicon and Intel, and Windows on x64 and on ARM, with Node.js 20 or later. Linux
+comes next.
+
+On Windows on ARM, argonuts uses the x64 build for now, which Windows 11 runs through its built-in
+x64 emulation. A native ARM build will replace it.
+
+The work is done by `argonuts-cli`, the core's own program, which npm installs with argonuts for your
+computer only, together with the `ffmpeg` and `ffprobe` it uses for thumbnails.
+
+## Licenses
+
+`argonuts` and `argonuts-cli` are MIT licensed. `ffmpeg` and `ffprobe` are FFmpeg, under the GNU
+LGPL 2.1 or later; the platform package that carries them includes its notice and license.

package/bin/argonuts.js

@@ -0,0 +1,365 @@
+#!/usr/bin/env node
+// src/core.ts
+import { spawn } from "node:child_process";
+import { accessSync, chmodSync, constants, existsSync } from "node:fs";
+import { createRequire } from "node:module";
+import path from "node:path";
+var PLATFORMS = {
+  "darwin-arm64": "macOS on Apple Silicon",
+  "darwin-x64": "macOS on Intel",
+  "win32-x64": "Windows on x64",
+  "win32-arm64": "Windows on ARM"
+};
+
+class CompanionError extends Error {
+  exitCode;
+  constructor(message, exitCode = 1) {
+    super(message);
+    this.exitCode = exitCode;
+  }
+}
+function platformKey() {
+  return `${process.platform}-${process.arch}`;
+}
+function corePath() {
+  const given = process.env.ARGONUTS_CLI;
+  if (given) {
+    if (!existsSync(given))
+      throw new CompanionError(`ARGONUTS_CLI is set to ${given}, which does not exist.`);
+    return given;
+  }
+  const key = platformKey();
+  if (!(key in PLATFORMS)) {
+    throw new CompanionError(`argonuts has no build for ${key} yet. It runs on ${Object.values(PLATFORMS).join(", ")}.`);
+  }
+  const name = `@argonuts/cli-${key}`;
+  let manifest;
+  try {
+    manifest = createRequire(import.meta.url).resolve(`${name}/package.json`);
+  } catch {
+    throw new CompanionError(`${name} is not installed. Reinstall argonuts: npm installs it for this computer.`);
+  }
+  const binary = path.join(path.dirname(manifest), "bin", key.startsWith("win32") ? "argonuts-cli.exe" : "argonuts-cli");
+  if (!existsSync(binary))
+    throw new CompanionError(`${binary} is missing. Reinstall argonuts.`);
+  makeRunnable(binary);
+  return binary;
+}
+function makeRunnable(binary) {
+  if (process.platform === "win32")
+    return;
+  try {
+    accessSync(binary, constants.X_OK);
+  } catch {
+    try {
+      chmodSync(binary, 493);
+    } catch {}
+  }
+}
+function startCore(args) {
+  return spawn(corePath(), args, { windowsHide: true, stdio: ["pipe", "pipe", "pipe"] });
+}
+function captureCore(args) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(corePath(), args, { windowsHide: true, stdio: ["ignore", "pipe", "pipe"] });
+    let stdout = "";
+    let stderr = "";
+    child.stdout.setEncoding("utf8").on("data", (chunk) => stdout += chunk);
+    child.stderr.setEncoding("utf8").on("data", (chunk) => stderr += chunk);
+    child.on("error", reject);
+    child.on("close", (code) => resolve({ code, stdout, stderr }));
+  });
+}
+async function coreJson(args) {
+  const { code, stdout, stderr } = await captureCore(args);
+  if (code !== 0)
+    throw new CompanionError(refusal(stderr) || `argonuts-cli stopped with exit code ${code}.`, code ?? 1);
+  try {
+    return JSON.parse(stdout);
+  } catch {
+    throw new CompanionError(`argonuts-cli answered with something that is not JSON: ${stdout.slice(0, 200)}`);
+  }
+}
+function refusal(stderr) {
+  return stderr.trim().replace(/^Error:\s*/, "");
+}
+
+// src/library.ts
+import path3 from "node:path";
+
+// src/show.ts
+import os from "node:os";
+import path2 from "node:path";
+function count(value) {
+  return Math.trunc(value).toString().replace(/\B(?=(\d{3})+(?!\d))/g, ",");
+}
+function bytes(value) {
+  const units = ["B", "KB", "MB", "GB", "TB", "PB"];
+  let scaled = value;
+  let unit = 0;
+  while (scaled >= 1000 && unit < units.length - 1) {
+    scaled /= 1000;
+    unit += 1;
+  }
+  return unit === 0 ? `${value} B` : `${scaled.toFixed(1)} ${units[unit]}`;
+}
+function plural(value, word) {
+  return value === 1 ? `1 ${word}` : `${count(value)} ${word}s`;
+}
+function when(rfc3339) {
+  const time = new Date(rfc3339);
+  if (Number.isNaN(time.getTime()))
+    return rfc3339;
+  return `${time.toISOString().slice(0, 16).replace("T", " ")} UTC`;
+}
+function shown(folder) {
+  const home = os.homedir();
+  if (!home)
+    return folder;
+  if (folder === home)
+    return "~";
+  if (folder.startsWith(home + path2.sep))
+    return `~${folder.slice(home.length)}`;
+  return folder;
+}
+function fit(line, columns = process.stderr.columns) {
+  if (!columns || line.length < columns)
+    return line;
+  return `${line.slice(0, Math.max(0, columns - 2))}…`;
+}
+
+// src/library.ts
+async function libraryCommand(args) {
+  const [action = "list", ...rest] = args;
+  let library;
+  switch (action) {
+    case "list":
+      if (rest.length > 0)
+        throw new CompanionError("`argonuts library list` takes no folders.", 2);
+      library = await coreJson(["library", "list"]);
+      break;
+    case "add":
+      if (rest.length === 0)
+        throw new CompanionError("Name a folder: argonuts library add <folder>", 2);
+      library = await coreJson(["library", "add", ...rest.map((folder) => path3.resolve(folder))]);
+      break;
+    case "remove":
+      if (rest.length !== 1)
+        throw new CompanionError("Name one folder: argonuts library remove <folder>", 2);
+      library = await coreJson(["library", "remove", path3.resolve(rest[0])]);
+      break;
+    default:
+      throw new CompanionError(`There is no \`argonuts library ${action}\`. Use list, add or remove.`, 2);
+  }
+  printLibrary(library);
+  return 0;
+}
+function printLibrary({ folders }) {
+  if (folders.length === 0) {
+    console.log("Your library has no folders yet. Add one: argonuts library add <folder>");
+    return;
+  }
+  const scans = folders.flatMap((entry) => entry.last_scan ? [entry.last_scan] : []);
+  const files = scans.reduce((sum, scan) => sum + scan.files, 0);
+  const size = scans.reduce((sum, scan) => sum + scan.total_bytes, 0);
+  const width = Math.max(...folders.map((entry) => shown(entry.folder).length));
+  console.log(`Your library: ${plural(folders.length, "folder")} · ${count(files)} files · ${bytes(size)}`);
+  for (const entry of folders) {
+    const scan = entry.last_scan;
+    const state = scan ? `${plural(scan.files, "file")} · ${bytes(scan.total_bytes)} · scanned ${when(scan.scanned_at)}` : "not scanned yet";
+    const connected = entry.present ? "" : " · ⚠ not connected";
+    console.log(`  ${shown(entry.folder).padEnd(width)}  ${state}${connected}`);
+  }
+}
+
+// src/scan.ts
+import { statSync } from "node:fs";
+import path4 from "node:path";
+import { createInterface } from "node:readline";
+var EXIT_CANCELLED = 130;
+async function scanCommand(args) {
+  const named = [];
+  let cachedOnly = false;
+  for (const arg of args) {
+    if (arg === "--cached-only")
+      cachedOnly = true;
+    else if (arg.startsWith("-"))
+      throw new CompanionError(`\`argonuts scan\` has no option ${arg}.`, 2);
+    else
+      named.push(path4.resolve(arg));
+  }
+  const library = await coreJson(named.length > 0 ? ["library", "add", ...named] : ["library", "list"]);
+  const targets = named.length > 0 ? named.map((folder) => ({ folder, present: isFolder(folder) })) : library.folders;
+  if (targets.length === 0) {
+    console.log("Your library has no folders yet. Add one: argonuts library add <folder>");
+    return 1;
+  }
+  let failed = false;
+  for (const { folder, present } of targets) {
+    if (!present) {
+      console.log(`⚠ ${shown(folder)} is not connected; skipped. Its last scan stays.`);
+      continue;
+    }
+    const snapshot = await scanFolder(folder, cachedOnly);
+    printSummary(snapshot);
+    if (snapshot.phase === "cancelled") {
+      console.log("Stopped.");
+      return EXIT_CANCELLED;
+    }
+    failed ||= snapshot.phase === "failed";
+  }
+  console.log();
+  printLibrary(await coreJson(["library", "list"]));
+  return failed ? 1 : 0;
+}
+function isFolder(folder) {
+  try {
+    return statSync(folder).isDirectory();
+  } catch {
+    return false;
+  }
+}
+function scanFolder(folder, cachedOnly) {
+  const label = shown(folder);
+  const redraw = process.stderr.isTTY === true;
+  const draw = (text) => redraw && process.stderr.write(`\r\x1B[2K${fit(`${label} · ${text}`)}`);
+  return new Promise((resolve, reject) => {
+    const child = startCore([
+      "--stop-on-stdin-close",
+      "scan",
+      folder,
+      "--json",
+      ...cachedOnly ? ["--cached-only"] : []
+    ]);
+    let last = null;
+    let finished = false;
+    let interrupts = 0;
+    let stderr = "";
+    const onInterrupt = () => {
+      interrupts += 1;
+      if (interrupts === 1) {
+        child.stdin.write(`cancel
+`);
+        draw("stopping…");
+      } else {
+        child.kill();
+      }
+    };
+    process.on("SIGINT", onInterrupt);
+    child.stdin.on("error", () => {});
+    child.stderr.setEncoding("utf8").on("data", (chunk) => stderr += chunk);
+    createInterface({ input: child.stdout }).on("line", (raw) => {
+      let line;
+      try {
+        line = JSON.parse(raw);
+      } catch {
+        return;
+      }
+      last = line.snapshot;
+      if (line.event === "done")
+        finished = true;
+      else
+        draw(progressLine(line.snapshot));
+    });
+    child.on("error", (error) => {
+      process.off("SIGINT", onInterrupt);
+      reject(error);
+    });
+    child.on("close", (code) => {
+      process.off("SIGINT", onInterrupt);
+      child.stdin.end();
+      if (redraw)
+        process.stderr.write("\r\x1B[2K");
+      if (!last) {
+        reject(new CompanionError(refusal(stderr) || `The scan of ${label} stopped with exit code ${code}.`, code ?? 1));
+        return;
+      }
+      if (!finished)
+        last.phase = interrupts > 0 ? "cancelled" : "failed";
+      resolve(last);
+    });
+  });
+}
+function progressLine(snapshot) {
+  if (snapshot.phase === "discovering")
+    return `Looking for media… ${count(snapshot.discovered_files)} files`;
+  return `Scanning ${count(snapshot.processed_files)}/${count(snapshot.discovered_files)} files · ` + `${count(snapshot.new_files)} new · ${count(snapshot.cached_files)} from cache · ` + `${count(snapshot.failed_files)} failed`;
+}
+function printSummary(snapshot) {
+  const verdict = { finished: "Scanned", cancelled: "Stopped", failed: "Failed" }[snapshot.phase] ?? "Failed";
+  console.log(`${verdict} ${shown(snapshot.root)}`);
+  console.log(`  ${count(snapshot.discovered_files)} files (${count(snapshot.video_files)} videos, ` + `${count(snapshot.image_files)} pictures), ${count(snapshot.new_files)} new, ` + `${count(snapshot.cached_files)} from cache, ${count(snapshot.failed_files)} failed`);
+  console.log(`  ${count(snapshot.thumbnails_generated)} thumbnails made`);
+  if (snapshot.unreadable_dirs > 0)
+    console.log(`  ${count(snapshot.unreadable_dirs)} folders could not be read`);
+  for (const failure of snapshot.failures)
+    console.error(`  ✗ ${failure.relative_path}: ${failure.error}`);
+  if (snapshot.error)
+    console.error(`✗ ${snapshot.error}`);
+}
+
+// src/main.ts
+var VERSION = "0.1.1";
+var HELP = `argonuts ${VERSION}: your media library, from the terminal.
+
+Usage:
+  argonuts library                    Your library's folders and their last scans
+  argonuts library add <folder>...    Add folders to your library
+  argonuts library remove <folder>    Remove a folder; its last scan stays on disk
+  argonuts scan [<folder>...]         Scan every library folder, or the folders named,
+                                      which join your library
+      --cached-only                   Use earlier thumbnails only and run no ffmpeg
+  argonuts --version                  The versions of argonuts and argonuts-cli
+
+Ctrl-C stops a scan; a second Ctrl-C stops it at once.
+Your library is kept in the core's data folder, shared with the desktop app.
+Set ARGONUTS_DATA_DIR to keep it somewhere else.
+`;
+async function main(argv) {
+  const [command, ...rest] = argv;
+  if (rest.includes("--help") || rest.includes("-h")) {
+    process.stdout.write(HELP);
+    return 0;
+  }
+  switch (command) {
+    case undefined:
+    case "help":
+    case "--help":
+    case "-h":
+      process.stdout.write(HELP);
+      return 0;
+    case "version":
+    case "--version":
+    case "-v":
+      return printVersion();
+    case "library":
+      return libraryCommand(rest);
+    case "scan":
+      return scanCommand(rest);
+    default:
+      process.stderr.write(`✗ There is no \`argonuts ${command}\`.
+
+${HELP}`);
+      return 2;
+  }
+}
+async function printVersion() {
+  console.log(`argonuts ${VERSION}`);
+  try {
+    const { code, stdout, stderr } = await captureCore(["--version"]);
+    if (code !== 0)
+      throw new CompanionError(refusal(stderr) || `argonuts-cli stopped with exit code ${code}.`);
+    console.log(stdout.trim());
+    return 0;
+  } catch (error) {
+    console.error(`✗ ${error instanceof Error ? error.message : String(error)}`);
+    return 1;
+  }
+}
+main(process.argv.slice(2)).then((code) => {
+  process.exitCode = code;
+}, (error) => {
+  process.stderr.write(`✗ ${error instanceof Error ? error.message : String(error)}
+`);
+  process.exitCode = error instanceof CompanionError ? error.exitCode : 1;
+});

package/package.json

@@ -1,6 +1,24 @@
 {
   "name": "argonuts",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "Your media library from the terminal: add folders, scan them and keep their thumbnails ready.",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "argonuts": "bin/argonuts.js"
+  },
+  "files": [
+    "bin",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "optionalDependencies": {
+    "@argonuts/cli-darwin-arm64": "0.1.1",
+    "@argonuts/cli-darwin-x64": "0.1.1",
+    "@argonuts/cli-win32-x64": "0.1.1",
+    "@argonuts/cli-win32-arm64": "0.1.1"
+  }
+}