funoteka 0.1.2 → 0.1.4

package/CHANGELOG.md

@@ -9,6 +9,47 @@ The version lives in exactly one place — `package.json`.
 
 _(nothing yet)_
 
+## [0.1.4] — 2026-09-17
+
+### Fixed
+
+- **The scan started from the server starts again.** `src/cli.ts` called
+  `entryPoint('./cli')` and the helper's default base was `import.meta.url`
+  evaluated *inside the helper* — so `./cli` resolved against `src/cli/`, not the
+  caller, and the scan child died with `Cannot find module '.../src/cli/cli.ts'`.
+  That killed every server-side entry to a scan: `POST /scan`, the MCP
+  `funoteka_scan_start` tool, the interval timer and the reader-change trigger.
+  The CLI scan kept working, which is why a broken published build read as a
+  deployment problem. The base is now a **required** argument to `entryPoint`
+  (forgetting it is a `TS2554`, and a path that does not exist throws), both call
+  sites name it, and the seam has tests over the exact pair the call sites use.
+
+## [0.1.3] — 2026-09-17
+
+### Changed
+
+- **The public README, which is a release artefact and ships in this package.**
+  Three things in it are new to a reader: **what it costs**, measured rather than
+  asserted (about 42 MB of RAM idle, 30 MB of SQLite for 3 432 songs, a 421 MB
+  image, and a collection that is only ever read); the **first scan is a step in
+  the quick start** (it was missing, so the documented install produced a server
+  with an empty library); and the **agent pitch opens the file**. The clients named
+  are the ones that have actually connected (`player`: Feishin, Symfonium,
+  Substreamer, Amcfy Music, Castafiore), not a compatibility wish-list.
+- **A checkout now has a working `funoteka`.** `bin` names `dist/cli.js` and a
+  clone had no `dist/` — so `npm install && npm link` produced a binary that
+  failed — until `prepare` was added to build it on install.
+- `DEPLOY.md` gained the two journeys that were guesses: the Windows service
+  wrapper versus the daemon that is in daily use, and the two things a NAS shows
+  that the command does not (the container's uid, and the arm64 half being built
+  under emulation).
+
+### Fixed
+
+- The engine of this patch is unchanged: no server code, no schema. What changed
+  is what a reader is told, and one line of `package.json` that makes the clone
+  behave.
+
 ## [0.1.2] — 2026-09-17
 
 ### Fixed

package/DEPLOY.md

@@ -61,7 +61,7 @@ node -e "console.log(require('crypto').randomBytes(32).toString('base64url'))"
 ## 3. Path A — Docker (main path)
 
 Works the same on a laptop, a NAS and a VDS. There is a **published image** —
-`ghcr.io/kzntsv-dev/funoteka:0.1.2`, `linux/amd64` and `linux/arm64` in one
+`ghcr.io/kzntsv-dev/funoteka:0.1.4`, `linux/amd64` and `linux/arm64` in one
 manifest — and `build: .` still builds on the machine that runs it (that is the
 path where a published image is not wanted or not reachable).
 
@@ -72,16 +72,32 @@ installation (verified by running exactly this against the published image):
 MUSIC=/absolute/path/to/your/music
 docker run -d --name funoteka -p 4533:4533 -p 4534:4534 \
   -e FUNOTEKA_USER=you -e FUNOTEKA_PASSWORD=change-me \
-  -e FUNOTEKA_ADMIN_TOKEN=<the token you generated> \
+  -e FUNOTEKA_ADMIN_TOKEN=PASTE_THE_TOKEN_YOU_GENERATED \
   -e FUNOTEKA_SUPERVISED=1 -e FUNOTEKA_LOG_FILE=/data/funoteka.log \
   -v "$MUSIC":/music:ro -v funoteka-data:/data \
-  --restart unless-stopped ghcr.io/kzntsv-dev/funoteka:0.1.2
+  --restart unless-stopped ghcr.io/kzntsv-dev/funoteka:0.1.4
 ```
 
+(The token above is a placeholder with no angle brackets in it, on purpose: a
+copy-paste that misses the substitution should fail to authenticate loudly rather
+than carry a string that looks like a token.)
+
 `FUNOTEKA_SUPERVISED=1` is what makes `POST /restart` a restart rather than a
 stop, and the restart policy beside it is what supervises the process. The first
 scan is still a command, not a startup side effect — see the end of this section.
 
+Two things that bite on a NAS, and neither is visible from the command above:
+
+- **The container runs as `node`, uid 1000.** A collection on a share that this
+  uid cannot read scans as an empty root — the server says so rather than failing
+  (`nothing here — an empty directory and a mistyped path read alike`), and the
+  fix is on the host: `chown` it, grant the group, or run the container with
+  `--user` set to the owner.
+- **The `arm64` half of the published image is built under emulation** on an
+  `amd64` machine. It runs correctly and it is not as fast as a build made on
+  that box would be — for a small board this is the difference worth measuring,
+  and `build: .` in a checkout on that box is the other path.
+
 From a checkout, the same installation is the compose file:
 
 ```sh
@@ -97,7 +113,7 @@ MUSIC=/absolute/path/to/your/music     # read-only into the container
 DATA=./data                            # everything the server owns
 FUNOTEKA_USER=you
 FUNOTEKA_PASSWORD=change-me
-FUNOTEKA_ADMIN_TOKEN=<the token you generated>
+FUNOTEKA_ADMIN_TOKEN=PASTE_THE_TOKEN_YOU_GENERATED
 ```
 
 Start it:
@@ -214,16 +230,21 @@ admin calls as §3 — add the root with the path **as this machine sees it**
 
 ## 5. Path C — native Windows (service)
 
+**The daemon works on Windows and is in daily use** — it is how the author's own
+server runs (started by a `start.cmd` that carries the `FUNOTEKA_*` variables
+from §3). What has not been run end to end is the *service wrapper* below, and
+its own help says so.
+
 ```powershell
 # elevated PowerShell, from the checkout
 .\deploy\windows\install-service.ps1 -Data 'C:\ProgramData\funoteka'
 ```
 
 The script downloads WinSW (pinned, hash-checked) to wrap `node src/cli.ts
-serve` as a service, writes a config file from the example, and restricts its
-ACL. **Edit that config file before starting the service** — it needs a password
-and an admin token. The script's own help says it has not been run end to end by
-whoever wrote it, and that is worth heeding: the first run is the verification.
+serve` as a service, writes the config file to `<Data>\funoteka.json` and the log
+to `<Data>\funoteka.log`, and restricts the directory's ACL. **Edit that config
+file before starting the service** — it needs a password and an admin token, and
+the service reads them from there rather than from a shell.
 
 ## 6. Verify, then keep it running
 
@@ -350,6 +371,9 @@ so inside a container the script is named instead.
 # a native install, with the bin on PATH (`npm link`, or `npm install -g .`)
 FUNOTEKA_ADMIN_TOKEN=$TOKEN funoteka mcp
 
+# or without installing anything: the published package, the same command
+FUNOTEKA_ADMIN_TOKEN=$TOKEN npx -y funoteka mcp
+
 # the container — the token arrives through .env, so it need not be repeated
 docker compose exec -T funoteka node src/cli.ts mcp
 ```
@@ -393,3 +417,26 @@ own status is in `GET /scan/history`.
 with them), then whether the song exists (`/rest/search3`), then the log with
 `FUNOTEKA_LOG_REQUESTS=1`, which prints one line per request with the method and
 the query — masked, because a client spells its password there.
+
+## 13. Why the published package is built, and the repository is not
+
+The repository runs its own TypeScript: `node src/cli.ts` is the program, `npm
+test` is the suite, and there is no build step to run before either of them.
+
+**The npm package cannot do that**, and the reason is a rule rather than a
+preference: Node refuses to strip types from any file under `node_modules`
+(`ERR_UNSUPPORTED_NODE_MODULES_TYPE_STRIPPING`), and no flag lifts it — checked on
+v24.19.0 with the default, both `--experimental-strip-types` and
+`--experimental-transform-types`, and the two together. A `bin` that named a `.ts`
+file would install a package that cannot start.
+
+So `npm run build` compiles `src` into `dist` for the package only
+(`tsconfig.build.json`, `deploy/build.mjs`), copying the schema migrations
+beside the code that reads them, and `bin` names `dist/cli.js`. Two consequences
+worth knowing:
+
+- **A fresh checkout has no `dist/`** and therefore no `funoteka` bin until the
+  build runs. `npm install` in a checkout now runs it (`prepare`), so
+  `npm link` from a clone works; `git clone` without an install does not.
+- **The image still copies `src/`** and runs `node src/cli.ts serve` — the
+  container is a checkout, and it never needs the build.

package/README.md

@@ -2,6 +2,13 @@
 
 **The Subsonic server a real collection deserves.**
 
+> ## Give `DEPLOY.md` to your agent.
+> Installing a music server means answering fiddly questions — where the music lives, which ports,
+> TLS or a reverse proxy, where the database goes, who may log in. Hand them to an agent: it reads
+> `DEPLOY.md`, asks you only what matters, installs funoteka (**Docker or native** — your machine,
+> your NAS, or a VDS), configures it, and then **keeps running it** — rescanning the library,
+> filtering junk, managing roots — over the **admin API and MCP**.
+
 **A folder is an album** — not a guess, not a heuristic: the rule. funoteka keys every record on
 its folder path, so three pressings of the same album stay three albums, a box stays a box and its
 discs, and an image file with a cue sheet becomes real, playable tracks. Nothing merged, nothing lost.
@@ -15,8 +22,12 @@ discs, and an image file with a cue sheet becomes real, playable tracks. Nothing
 - **Your files are never modified.** Classification, cue boundaries, encodings, dedup — all of it
   lives in a meta layer beside the server. Point it at your disk; your disk stays as it is.
 - **No LLM, no Discogs, no Last.fm, no external service.** The core reads what is in your files and
-  folders. Enrichment is possible later, and it is optional.
-- **An agent installs, configures and runs it.** Hand your agent `DEPLOY.md`.
+  folders, and what it writes stays on your disk: the meta layer, the log, and an audit file beside
+  the database that records what was changed through the admin surface. Enrichment is possible
+  later, and it is optional.
+- **Any client you already like just works.** Symfonium, Feishin, Substreamer, Amcfy Music and
+  Castafiore have all reported themselves to this server, and none of them needed anything special;
+  the API is the point, the client is yours.
 
 A complete **Subsonic / OpenSubsonic** surface, filled from your own files wherever it can be and
 answered honestly and empty wherever it cannot — so the client you already like just works.
@@ -50,6 +61,18 @@ Three albums, a box set of twelve discs. No merging, no guessing, nothing lost.
 
 ## Install
 
+### What it costs
+
+Measured on the machine this was built on, and worth knowing before you point it at 200 GB of FLAC:
+
+| | |
+|---|---|
+| **Idle** | about **42 MB** of RAM, no measurable CPU — the container, with an empty library |
+| **The meta layer** | **30 MB** of SQLite for 3 432 songs and 472 albums (the author's own library); it grows with the catalogue, not with the audio |
+| **The re-encode cache** | grows with what you ask for: 300 MB after a year of cue segments from m4a/MP4 images, and it is inside the one directory you mount |
+| **The collection** | read-only, never written to, never copied anywhere. The server reads the bytes it serves and does not keep the library in memory |
+| **The image** | 421 MB, ffmpeg included |
+
 ### Docker — the main path
 
 The image carries everything, **ffmpeg included** — the only external binary the server ever wants,
@@ -76,11 +99,10 @@ docker compose exec funoteka node src/cli.ts scan /music   # fill the library, o
 ### Native, without Docker
 
 Needs **Node 24+**. There are **no runtime dependencies** — Node carries SQLite and FTS5, and the
-repository runs its own TypeScript, with no build step at all. The published *package* is the one
-place that cannot hold: Node refuses to strip types from anything under `node_modules`
-(`ERR_UNSUPPORTED_NODE_MODULES_TYPE_STRIPPING`, and no flag lifts it), so what npm gets is the same
-sources compiled once at release (`npm run build`) — a build that exists for the package and not for
-the repository. `ffmpeg` on the PATH is needed only for cue tracks inside an m4a/MP4 container.
+repository runs its own TypeScript with no build step at all. (The published *package* is the one
+place that cannot hold, because Node refuses to strip types from anything under `node_modules`; what
+npm gets is the same sources compiled once at release. Why, and what that changes — `DEPLOY.md` §13.)
+`ffmpeg` on the PATH is needed only for cue tracks inside an m4a/MP4 container.
 
 ```sh
 npm install -g funoteka
@@ -132,6 +154,9 @@ classification and you edit that layer, not your music.
 
 - `DEPLOY.md` — install, configure and manage, written to be read by an agent
 - The admin API and the MCP server — `DEPLOY.md` §11
+- Something broken, or missing: [an issue](https://github.com/kzntsv-dev/funoteka/issues) — say
+  what you did, what you expected and what the server said; the log and `GET /issues` usually
+  already contain the answer, and the troubleshooting table in `DEPLOY.md` has the rest
 
 ## License
 

package/dist/api/envelope.js

@@ -30,7 +30,7 @@ export const API_VERSION = '1.16.1';
  * module every route depends on.
  */
 export const SERVER_TYPE = 'funoteka';
-export const SERVER_VERSION = '0.1.2';
+export const SERVER_VERSION = '0.1.4';
 /**
  * The fields every answer carries, whatever the answer is.
  *

package/dist/cli/daemon.js

@@ -101,8 +101,10 @@ export async function start(dbPath, argv, timeoutMs = 15_000) {
     const log = openSync(logPath(dbPath), 'a');
     const child = spawn(process.execPath, 
     // The entry point as *this* build spells it — `.ts` beside the sources, `.js`
-    // in the compiled build the npm package ships (see `cli/entry.ts`).
-    [entryPoint('../cli'), 'serve', ...argv], {
+    // in the compiled build the npm package ships (see `cli/entry.ts`). The base
+    // is this module's own URL, because the relative name is counted from the
+    // file that spawns (`issue:91`).
+    [entryPoint('../cli', import.meta.url), 'serve', ...argv], {
         detached: true,
         // Nothing on stdin: a daemon that could read a terminal would be waiting
         // on a prompt nobody is there to answer.

package/dist/cli/entry.js

@@ -13,13 +13,34 @@ import { fileURLToPath } from 'node:url';
  *
  * Asking the filesystem instead of inferring the answer from the caller's own
  * extension makes it checkable rather than assumed: the emitted file is preferred
- * because a tree that has one is a built tree, the source is the fallback, and
- * neither existing names the source — so the failure reads as "the build did not
- * run" rather than as a `.js` that was never going to be there.
+ * because a tree that has one is a built tree, the source is the fallback.
+ *
+ * ## The base is the caller's, and it is a parameter rather than a default
+ *
+ * `from` has **no default on purpose.** It had one — `import.meta.url`, which
+ * reads as "here" and is evaluated *in this file*: so a caller writing
+ * `entryPoint('./cli')` from `src/cli.ts` was asking for a sibling of
+ * `src/cli/entry.ts`, and got `src/cli/cli.ts`, which does not exist. The server
+ * answered `202` to `POST /scan`, the child died on `MODULE_NOT_FOUND`, and the
+ * only trace was in the child's stderr — `issue:91`, and it reached a released
+ * image because nothing in the suite ran the command the scanner builds. A
+ * required parameter turns that from a silent wrong path into a compile error at
+ * the next call site, which is the version of this that cannot happen again.
+ *
+ * ## And a path that is not there is a throw, not a guess
+ *
+ * The first version returned the `.ts` spelling whether or not it existed, so a
+ * wrong base travelled out of here as a plausible-looking string and failed
+ * somewhere else entirely. Now the search either finds a file or says so.
  */
-export function entryPoint(relative, from = import.meta.url) {
+export function entryPoint(relative, from) {
     const emitted = fileURLToPath(new URL(`${relative}.js`, from));
     if (existsSync(emitted))
         return emitted;
-    return fileURLToPath(new URL(`${relative}.ts`, from));
+    const source = fileURLToPath(new URL(`${relative}.ts`, from));
+    if (existsSync(source))
+        return source;
+    throw new Error(`no entry point beside ${fileURLToPath(from)}: neither ${emitted} nor ${source} exists. ` +
+        `A relative name is resolved against the base the caller passes, so a base that is not ` +
+        `the calling module's own URL looks in the wrong directory.`);
 }

package/dist/cli.js

@@ -494,7 +494,10 @@ function listen(db, config, admin, scan, stopLog) {
             args: [
                 // The entry point as *this* build spells it — `.ts` beside the sources,
                 // `.js` in the compiled build the npm package ships (see `cli/entry.ts`).
-                entryPoint('./cli'),
+                // `import.meta.url` is this module's, and it has to be passed: the name is
+                // relative to the file that *spawns*, not to the helper that resolves it
+                // (`issue:91`).
+                entryPoint('./cli', import.meta.url),
                 'scan',
                 ...listRoots(db).map((one) => one.path),
                 '--db',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "funoteka",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "Subsonic-compatible server: smart music library — scanner-classifier, cue splitting, meta layer, virtual tree",
   "license": "MIT",
   "type": "module",
@@ -41,6 +41,7 @@
   "scripts": {
     "build": "node deploy/build.mjs",
     "prepublishOnly": "npm run build",
+    "prepare": "node deploy/build.mjs",
     "scan": "node src/cli.ts scan",
     "serve": "node src/cli.ts serve",
     "smoke": "node deploy/smoke.mjs",