funoteka 0.1.0

package/README.md

@@ -0,0 +1,138 @@
+# funoteka
+
+**The Subsonic server a real collection deserves.**
+
+**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.
+
+- **An image file and its cue sheet become real tracks** — cut exactly where the cue's `INDEX`
+  says, at the frame it names.
+- **A folder is an album.** Three pressings stay three; a box set stays a box set *and* its
+  disc-albums. Tags are metadata, never the identity.
+- **Every format your collection actually has** — FLAC, ALAC, MP3, Ogg Vorbis, Opus — plus
+  **transcoding**, so a client that cannot play one still can.
+- **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`.
+
+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.
+
+## Why the folder wins
+
+Three CD pressings of one album are three different records, and a box set is not one CD. Because
+funoteka keys the album on its **path**, that is exactly what you get:
+
+```
+Cure, The/Pictures Of You [1989 UK CD]/   ← one album
+Cure, The/Pictures Of You [1990 US CD]/   ← another album
+Cure, The/Disintegration (Box, 12 CD)/    ← the box, and each disc inside it
+```
+
+Three albums, a box set of twelve discs. No merging, no guessing, nothing lost.
+
+## What it does
+
+| | |
+|---|---|
+| **Identity** | the absolute folder path — not the tag |
+| **Cue sheets** | image + cue → real tracks; several `.cue` in one folder, `INDEX 00`, `mm:ss:ff`, per-track performer |
+| **Box sets** | a release *and* its disc-albums |
+| **Encodings** | CP1251, UTF-16, ID3v1/v2, Vorbis, MP4 — normalised in the meta layer, files untouched |
+| **Rescan** | incremental by mtime/size; a timer, an optional filesystem watcher, or your own scheduler |
+| **Junk** | releaser debris and fake folders are marked and hidden from the default view — never deleted |
+| **Library** | playlists (server-side and `.m3u`), stars and ratings, play history, play queue, bookmarks, offline download |
+| **Clients** | the Subsonic API + OpenSubsonic extensions; everything else answers with honest, well-formed empty responses — never a 404 |
+| **Management** | an admin API on its own port, and an **MCP server** — an agent can run the whole thing |
+
+## Install
+
+### Docker — the main path
+
+The image carries everything, **ffmpeg included** — the only external binary the server ever wants,
+and only for cue tracks inside an m4a/MP4 container.
+
+```sh
+git clone https://github.com/kzntsv-dev/funoteka && cd funoteka
+cp .env.example .env        # your music folder, a password, an admin token
+docker compose up -d
+docker compose exec funoteka node src/cli.ts scan /music   # fill the library, once
+```
+
+> **On Windows with Git Bash**, prefix that last line with `MSYS_NO_PATHCONV=1`. The shell
+> rewrites `/music` into a Windows path before Docker ever sees it, and the scan then answers
+> honestly about an empty root — `/app/C:/Program Files/Git/music` — which reads like a broken
+> image and is really the shell.
+
+### Or let your agent do it
+
+> **Give `DEPLOY.md` to your agent.** It asks the questions that matter — where the music is, where
+> to keep the database, which ports, TLS or a reverse proxy, a password — and does the rest. Local
+> machine, NAS, VDS: the guide covers all three.
+
+### 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.
+
+```sh
+npm install -g funoteka
+funoteka scan /path/to/music     # build the library
+funoteka serve --daemon          # serve it
+```
+
+## Quick start
+
+1. Start the server. It listens on **4533**.
+2. Install any Subsonic client — Symfonium, Feishin, Substreamer, or whatever you already use.
+3. Point it at `http://your-host:4533`, with the login and password you set.
+4. Browse and play.
+
+You see the disk as it should have looked all along: artists, albums, box sets, and cue tracks that
+are tracks.
+
+## How it works
+
+```
+your folders ─► scanner ─► classifier ─► meta layer (SQLite) ─► Subsonic API ─► any client
+                   │           │                 ▲
+             cue engine   folder identity   admin API · MCP
+```
+
+The scanner **reads**. Everything it learns — what is an album, where a cue track starts, what an
+encoding was — goes into a SQLite database it owns, beside the server. Change your mind about a
+classification and you edit that layer, not your music.
+
+## Compatibility
+
+- **Subsonic 1.16.1** — the standard surface.
+- **OpenSubsonic** — `getArtistInfo2`, genres, `getAlbumList2` by year and genre, embedded cover
+  art, Ogg and ID3 readers, transcoding, and the extension manifest (`getOpenSubsonicExtensions`
+  declares exactly what works — nothing more).
+- What the server does not source from your own files — lyrics, similar artists, top songs, bios —
+  is answered **honestly and empty**, so no client breaks on it.
+
+## What it is not
+
+- **Not a web player.** It is headless: no UI, no dashboard. You drive it with the admin API or MCP,
+  and the music reaches you through the Subsonic client you already like.
+- **Not tag-driven.** It will not merge your pressings, rename your artists to match an online
+  database, or call home. Nothing about your collection leaves the machine.
+- **Not overclaiming.** Where a thing does not exist yet — a published cross-build, say — the docs
+  say so instead of pretending.
+
+## Documentation
+
+- `DEPLOY.md` — install, configure and manage, written to be read by an agent
+- The admin API and the MCP server — `DEPLOY.md` §11
+
+## License
+
+MIT © Victor Kuznetsov. Use it, fork it, ship it.

package/deploy/answers.schema.json

@@ -0,0 +1,151 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://funoteka/deploy/answers.schema.json",
+  "title": "funoteka deployment answers",
+  "description": "The questions DEPLOY.md asks, in a form a program can hold. An agent that has been handed answers instead of asking for them reads this for the shape; an agent that has to ask reads the descriptions, which say why each answer matters and what happens when it is left out. Every property except the music directory and the listener credentials has a default, and the defaults are a working server.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["music", "user", "password"],
+  "properties": {
+    "target": {
+      "description": "Which path of DEPLOY.md to follow. Docker is the main path: one command, and ffmpeg comes inside the image. The native paths are for a machine where Docker is not wanted, and need Node 24 and ffmpeg installed.",
+      "enum": ["docker", "linux-service", "windows-service"],
+      "default": "docker"
+    },
+    "host": {
+      "description": "The machine this is being deployed to, as the person answering would name it. Used in the steps that have to be run there rather than here; nothing in the deployment depends on it.",
+      "type": "string"
+    },
+
+    "music": {
+      "description": "Absolute path to the collection, as the SERVER sees it. For the docker target that is the path inside the container (the compose file mounts the host's directory at /music), and for the native targets it is the path on the machine. It is mounted read-only: nothing in this server ever writes to, moves or renames a file of yours.",
+      "type": "string"
+    },
+    "data": {
+      "description": "Where the server keeps what is its own: the meta layer (a SQLite file), its re-encode cache, its log, its audit file and the config file. This directory is the whole of what a backup takes, apart from the music itself.",
+      "type": "string",
+      "default": "./data"
+    },
+
+    "musicPort": {
+      "description": "The port music clients connect to. 4533 is Subsonic's own, so a client that guesses one guesses right.",
+      "type": "integer",
+      "minimum": 1,
+      "maximum": 65535,
+      "default": 4533
+    },
+    "adminPort": {
+      "description": "The port the admin surface listens on. It is meant to be reachable from outside — that is what it is for — and it is guarded by its own token rather than by not being reachable. One more than the music port, so it is one number to remember.",
+      "type": "integer",
+      "minimum": 1,
+      "maximum": 65535,
+      "default": 4534
+    },
+
+    "user": {
+      "description": "The listener's name. Subsonic clients send it with every request.",
+      "type": "string",
+      "minLength": 1
+    },
+    "password": {
+      "description": "The listener's password. The server REFUSES TO START without a password or an api key: a music library on the open network is not 'it came up', it is a misconfiguration.",
+      "type": "string",
+      "minLength": 1
+    },
+    "apiKey": {
+      "description": "An alternative to the password, for a client that would rather not hold one (OpenSubsonic's apiKeyAuthentication). Either one is enough; both may be set.",
+      "type": "string"
+    },
+    "adminToken": {
+      "description": "The admin surface's whole gate, and the admin surface does not exist without it: with no token the port is not open at all. Generate one with `node -e \"console.log(require('crypto').randomBytes(32).toString('base64url'))\"`. It is a credential: keep it out of the music directory and out of git.",
+      "type": "string"
+    },
+    "adminAllow": {
+      "description": "Who may reach the admin port at all, as comma-separated addresses and CIDR blocks. Empty means every address, which is what the token is then carrying on its own. A second lock, not the gate.",
+      "type": "string",
+      "default": ""
+    },
+    "adminTrustProxy": {
+      "description": "Whether X-Forwarded-For may be believed when deciding adminAllow. False unless a proxy is the only way in: the header is written by the caller, so believing it on a directly reachable port means anyone can claim any address and walk through the allowlist.",
+      "type": "boolean",
+      "default": false
+    },
+    "tls": {
+      "description": "How the admin port is encrypted. 'self' terminates TLS here and needs tlsCert and tlsKey (both or neither; a path that cannot be read stops the server at startup). 'proxy' leaves the port plain and expects a reverse proxy in front of it — not a weaker arrangement, and the one to narrow adminAllow to the proxy's address for. 'none' is for a deployment on a private network.",
+      "enum": ["none", "self", "proxy"],
+      "default": "none"
+    },
+    "tlsCert": {
+      "description": "Path to the certificate, when tls is 'self'.",
+      "type": "string"
+    },
+    "tlsKey": {
+      "description": "Path to its private key, when tls is 'self'.",
+      "type": "string"
+    },
+
+    "supervised": {
+      "description": "Whether something will start this process again after it exits — a restart policy, a systemd unit, a service wrapper. It is what makes POST /restart a restart rather than a stop, and where it is false the route refuses with a 409 instead of taking the music down. The compose file and the unit set it; a bare `serve --daemon` has nobody and should say so.",
+      "type": "boolean",
+      "default": true
+    },
+    "scanInterval": {
+      "description": "Minutes between the scans the server starts by itself. Zero turns the timer off, for a deployment with a cron job of its own.",
+      "type": "integer",
+      "minimum": 0,
+      "default": 360
+    },
+    "scanQuietFrom": {
+      "description": "The first hour (0-23, local) in which a scan may not START. A scan is audible — it reads every file — and these are the hours a house is asleep in. A scan that comes due inside the window waits for the end of it rather than being skipped.",
+      "type": "integer",
+      "minimum": 0,
+      "maximum": 23,
+      "default": 3
+    },
+    "scanQuietTo": {
+      "description": "The hour the quiet window ends. Equal to scanQuietFrom means no quiet hours at all. The window may cross midnight (23 to 6).",
+      "type": "integer",
+      "minimum": 0,
+      "maximum": 23,
+      "default": 6
+    },
+    "scanWatch": {
+      "description": "Watch the roots for changes instead of waiting for the interval. It waits for five seconds of silence first, so a file being copied in is never read halfway. It cannot work on a network share — the server says so in the log and falls back to the interval rather than pretending.",
+      "type": "boolean",
+      "default": false
+    },
+
+    "logFile": {
+      "description": "A file to append this process's own output to, for a deployment whose supervisor collects nothing. Leave it out where Docker, systemd or the service wrapper already collects it.",
+      "type": "string",
+      "default": ""
+    },
+    "ffmpeg": {
+      "description": "The ffmpeg binary, needed only to cut cue tracks out of an .m4a/MP4 image. The Docker image has one; a native install has to provide it. Without it those tracks are refused with a reason and everything else works.",
+      "type": "string",
+      "default": "ffmpeg"
+    }
+  },
+  "examples": [
+    {
+      "target": "docker",
+      "music": "/music",
+      "data": "./data",
+      "user": "you",
+      "password": "change-me",
+      "adminToken": "…32 random bytes…",
+      "supervised": true
+    },
+    {
+      "target": "linux-service",
+      "music": "/srv/music",
+      "data": "/var/lib/funoteka",
+      "user": "you",
+      "password": "change-me",
+      "adminToken": "…32 random bytes…",
+      "adminAllow": "10.0.0.0/8",
+      "tls": "proxy",
+      "adminTrustProxy": true
+    }
+  ]
+}

package/deploy/build.mjs

@@ -0,0 +1,88 @@
+#!/usr/bin/env node
+/**
+ * The build, for the npm package and for nothing else.
+ *
+ *   node deploy/build.mjs
+ *
+ * **The repository runs its own TypeScript and needs no build.** `node
+ * src/cli.ts` is the program, `npm test` is the suite, and TypeScript is a
+ * dev-time tool — that is a property of this project worth keeping, and this
+ * script does not take it away.
+ *
+ * The *package* is the one place it cannot hold. Node refuses to strip types
+ * from any file under `node_modules` (`ERR_UNSUPPORTED_NODE_MODULES_TYPE_STRIPPING`),
+ * and there is no flag that lifts it — checked on v24.19.0: the default, both
+ * `--experimental-strip-types` and `--experimental-transform-types`, and the two
+ * together all refuse. So a package whose `bin` names a `.ts` file installs and
+ * then cannot start, which is what `npx -y funoteka mcp` would have done. The
+ * published artifact therefore carries what `tsc` emits, and this is how it is
+ * made.
+ *
+ * Two steps, because `tsc` emits TypeScript and the program also reads files
+ * that are not: the schema migrations live beside the code that applies them
+ * (`src/db/migrations`, found through `import.meta.dirname`). Every such file is
+ * copied to the same place under `dist` — every one, not the migrations
+ * specifically, so that a `.json` added tomorrow travels without anyone
+ * remembering to extend this script — and then the copy is *checked* rather than
+ * assumed. A build that compiled the code and left an asset behind would produce
+ * a package that starts and then fails somewhere deeper, which is the kind of
+ * failure that reads as a bug in the program.
+ *
+ * Exit code 0 on a complete build, 1 otherwise.
+ */
+
+import { cpSync, existsSync, mkdirSync, readdirSync, rmSync, statSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import { dirname, join, relative } from 'node:path';
+
+/** Every file under `src` that is not TypeScript, as a path relative to `src`. */
+function assets(dir = 'src') {
+  const found = [];
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    const from = join(dir, entry.name);
+    if (entry.isDirectory()) {
+      found.push(...assets(from));
+      continue;
+    }
+    if (entry.name.endsWith('.ts')) continue;
+    found.push(relative('src', from));
+  }
+  return found.sort();
+}
+
+const tsc = join('node_modules', 'typescript', 'bin', 'tsc');
+if (!existsSync(tsc)) {
+  console.error('no TypeScript in node_modules — run `npm ci` first');
+  process.exit(1);
+}
+
+rmSync('dist', { recursive: true, force: true });
+
+const compiled = spawnSync(process.execPath, [tsc, '-p', 'tsconfig.build.json'], { stdio: 'inherit' });
+if (compiled.status !== 0) {
+  console.error(`tsc exited with ${compiled.status}`);
+  process.exit(1);
+}
+
+const carried = assets();
+for (const one of carried) {
+  const to = join('dist', one);
+  mkdirSync(dirname(to), { recursive: true });
+  cpSync(join('src', one), to);
+}
+
+const entry = join('dist', 'cli.js');
+const entrySize = existsSync(entry) ? statSync(entry).size : 0;
+const missing = carried.filter((one) => !existsSync(join('dist', one)));
+const schema = carried.filter((one) => one.endsWith('.sql'));
+
+console.log(`dist/cli.js ${entrySize} bytes, ${carried.length - missing.length}/${carried.length} asset(s) beside it`);
+if (entrySize === 0 || missing.length > 0) {
+  for (const one of missing) console.error(`  not in dist: ${one}`);
+  console.error('the build is not complete: the entry point or a file the program reads is missing');
+  process.exit(1);
+}
+if (schema.length === 0) {
+  console.error('no schema migrations under src — a package without them could not open a database');
+  process.exit(1);
+}

package/deploy/check-publishable.mjs

@@ -0,0 +1,246 @@
+#!/usr/bin/env node
+/**
+ * The publishability gate: what must not be in a copy that leaves this machine.
+ *
+ *   node deploy/check-publishable.mjs [dir] [--shapes-only]   # default: the current directory
+ *
+ * **Run it on the curated copy, not on the development tree.** The development
+ * tree keeps its meta deliberately — `.mappa/`, `AGENTS.md`, `.pi/` are tracked
+ * there, and the private host lives in `.mappa/config.yaml` on purpose. A gate
+ * run against the tree is red every day, and a gate that is red every day is a
+ * gate nobody reads. The copy is the artefact; the copy is what is checked.
+ *
+ * Two questions, and both are about the copy:
+ *
+ *   1. **private VALUES — zero hits.** By value, not by name: `.mappa` in a
+ *      `.gitignore` line is not a leak and must not be reported as one, while a
+ *      hostname, a machine name or the collection's own path is a leak wherever
+ *      it appears.
+ *   2. **meta files in the tree — none**, at any depth, not only at the top.
+ *
+ * **Which values, and why the list is split in two.** Shapes are named here and
+ * are safe to publish: a Windows drive letter, a workstation prefix, the name of
+ * a registry product. The *identifiers* of this estate — the private git host,
+ * its registry, the leading characters of an administrative token, the operator,
+ * the LAN the live server sits on, the NAS marker — are **not** in this file:
+ * this file travels to the public repository, and a gate that publishes what it
+ * forbids is worse than no gate. They arrive by environment instead:
+ *
+ *   FUNOTEKA_PRIVATE_VALUES='git.example.site,some-handle'  node deploy/check-publishable.mjs .
+ *
+ * CI supplies them from a repository secret, so the public workflow carries the
+ * check and not the values.
+ *
+ * **The identifiers are required, not optional.** Without them the gate knows
+ * three shapes and nothing else, and a green verdict would mean far less than it
+ * looks like it means — so it exits 2 and says so. `--shapes-only` is the
+ * explicit way to ask for the reduced check, and it is a way to say "I know this
+ * is weaker", not a default.
+ *
+ * **One file is exempt from the shape scan and not from the rest:** this one,
+ * wherever a copy of this repository keeps it (`deploy/check-publishable.mjs`)
+ * and whichever copy is the one running. It names the shapes it forbids, so it
+ * matches itself, and a gate that reports itself as a leak is a gate that gets
+ * switched off. The exemption is by that path and by this file's own resolved
+ * path, so it holds whoever runs it and from wherever — and it covers the built-in
+ * shapes only: anything arriving through `FUNOTEKA_PRIVATE_VALUES` is checked here
+ * too, which is what keeps this file honest about the only values that would
+ * matter if they appeared in it.
+ *
+ * Exit code: 0 clean, 1 findings, 2 misused (bad directory, or identifiers
+ * missing without `--shapes-only`). A gate that cannot fail would be a report,
+ * and a green report is not a check.
+ */
+
+import { readFileSync, readdirSync, realpathSync, statSync } from 'node:fs';
+import { basename, join, relative, resolve, sep } from 'node:path';
+
+const argv = process.argv.slice(2);
+const shapesOnly = argv.includes('--shapes-only');
+const target = resolve(argv.find((argument) => !argument.startsWith('--')) ?? '.');
+
+try {
+  if (!statSync(target).isDirectory()) throw new Error('not a directory');
+} catch (error) {
+  console.error(`cannot read ${target}: ${error.message}`);
+  process.exit(2);
+}
+
+/**
+ * Shapes: generic markers, safe to name in public, and each one a leak wherever
+ * it appears.
+ *
+ * **A private IPv4 range is deliberately NOT one of them.** `10.0.0.0/8` is
+ * what every page about an address allowlist says, including this project's own
+ * documentation and its tests — a rule against private ranges flags the
+ * documentation for documenting the feature, and 57 such lines is how a gate
+ * gets switched off. `music/` is absent for the same reason: `/music` is the
+ * container's mount point and is public by design.
+ *
+ * So what stays here is what is generic, and what names *this* estate goes to
+ * `FUNOTEKA_PRIVATE_VALUES` — including the LAN the live server sits on, which
+ * is an identifier of this estate and not a shape.
+ */
+const SHAPES = [
+  { pattern: /\bZ:\\/, why: 'the collection drive' },
+  { pattern: /DESKTOP-/, why: 'a workstation name' },
+  { pattern: /verdaccio/, why: 'a private registry' },
+];
+
+/**
+ * Identifiers of this estate, supplied from outside (see the header). Each is
+ * matched literally after escaping, **unanchored and case-sensitive**: an
+ * unanchored substring is the strict reading — a value inside a longer word is
+ * still the value — and the price of that strictness is that the values must be
+ * specific. A one- or two-character value would match half the tree, so short
+ * ones are reported as a warning rather than quietly trusted.
+ */
+const supplied = (() => {
+  const raw = process.env.FUNOTEKA_PRIVATE_VALUES ?? '';
+  return raw
+    .split(',')
+    .map((value) => value.trim())
+    .filter((value) => value !== '')
+    .map((value) => ({ pattern: new RegExp(value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')), why: 'supplied as private' }));
+})();
+
+if (supplied.length === 0 && !shapesOnly) {
+  console.error('the estate identifiers were not supplied — set FUNOTEKA_PRIVATE_VALUES, or pass --shapes-only');
+  console.error('  (--shapes-only checks three generic shapes and no hostname, handle or token, and says so in its verdict)');
+  process.exit(2);
+}
+for (const { pattern } of supplied) {
+  const value = pattern.source.replace(/\\(.)/g, '$1');
+  if (value.length < 4) console.warn(`  warning: supplied value ${JSON.stringify(value)} is very short — expect false positives`);
+}
+
+/**
+ * Meta that belongs to the development tree, by name or by directory anywhere in
+ * the tree. `README.ru.md` is here because the public README is English and the
+ * Russian one is a development note that is not in the allowlist. `.env` and
+ * `funoteka.json` are not meta, they are somebody's machine — a copy made from a
+ * working checkout would otherwise carry credentials or a port — so the report
+ * heading says "meta and machine-local files" rather than calling them meta.
+ */
+const META_FILES = ['AGENTS.md', 'CLAUDE.md', '.mappa-manifest.json', 'README.ru.md', '.env', 'funoteka.json'];
+const META_DIRS = ['.mappa', '.pi', '.wiki', '.tasks'];
+
+/** A file this large is read in one piece; past the cap it is named, not read. */
+const MAX_BYTES = 16 * 1024 * 1024;
+
+const selfPath = realpathSync(import.meta.filename);
+const selfRelative = 'deploy/check-publishable.mjs';
+
+const rules = [
+  ...SHAPES.map(({ pattern, why }) => ({ pattern, why, selfExempt: true })),
+  ...supplied.map(({ pattern, why }) => ({ pattern, why, selfExempt: false })),
+];
+const hits = rules.map(() => []);
+const skipped = { large: 0, other: 0 };
+const meta = new Set();
+
+function* walk(dir) {
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    const path = join(dir, entry.name);
+    if (entry.isDirectory()) {
+      yield path;
+      if (entry.name === '.git' || entry.name === 'node_modules' || META_DIRS.includes(entry.name)) continue;
+      yield* walk(path);
+    } else if (entry.isFile()) {
+      yield path;
+    }
+  }
+}
+
+/**
+ * Both readings of a file, because a private value does not care how the bytes
+ * were encoded: UTF-8 lossy (which is what a PNG's text chunk or a PDF reads as)
+ * and, when there are NUL bytes, UTF-16 as well — a `.env`-shaped file saved by
+ * a Windows editor is UTF-16 and would otherwise be skipped as "binary".
+ */
+function textsOf(path) {
+  const bytes = readFileSync(path);
+  const texts = [bytes.toString('utf8')];
+  if (bytes.includes(0)) texts.push(bytes.toString('utf16le'));
+  return texts;
+}
+
+const targetPrefix = target.endsWith(sep) ? target : target + sep;
+let files = 0;
+
+try {
+  for (const path of walk(target)) {
+    const relativePath = relative(target, path).split(sep).join('/');
+    const parts = relativePath.split('/');
+    const metaDir = parts.findIndex((part) => META_DIRS.includes(part));
+    if (metaDir >= 0) meta.add(parts.slice(0, metaDir + 1).join('/'));
+    else if (META_FILES.includes(basename(relativePath))) meta.add(relativePath);
+
+    if (metaDir >= 0 || !statSync(path).isFile()) continue;
+
+    const stats = statSync(path);
+    if (stats.size > MAX_BYTES) {
+      skipped.large += 1;
+      continue;
+    }
+    if (realpathSync(path) === selfPath || relativePath === selfRelative) {
+      // Scanned only for the supplied identifiers; see the header.
+      const text = readFileSync(path, 'utf8');
+      text.split('\n').forEach((line, index) => {
+        rules.forEach((rule, position) => {
+          if (rule.selfExempt) return;
+          const match = rule.pattern.exec(line);
+          if (match) hits[position].push(`${relativePath}:${index + 1}: ${line.slice(Math.max(0, match.index - 40), match.index + 60)}`);
+        });
+      });
+      files += 1;
+      continue;
+    }
+
+    files += 1;
+    for (const text of textsOf(path)) {
+      text.split('\n').forEach((line, index) => {
+        rules.forEach((rule, position) => {
+          const match = rule.pattern.exec(line);
+          if (match) hits[position].push(`${relativePath}:${index + 1}: ${line.slice(Math.max(0, match.index - 40), match.index + 60)}`);
+        });
+      });
+    }
+  }
+} catch (error) {
+  console.error(`the walk stopped: ${error.message}`);
+  process.exit(2);
+}
+
+const shown = relative(process.cwd(), target) || basename(target);
+console.log(`funoteka publishability gate — ${shown === '' ? basename(target) : shown}`);
+console.log(`  ${files} text file(s) read`);
+if (skipped.large > 0) console.log(`  ${skipped.large} file(s) skipped: larger than ${MAX_BYTES} bytes`);
+console.log(
+  supplied.length === 0
+    ? '  identifiers: SHAPES ONLY — requested with --shapes-only, not a full check'
+    : `  identifiers: ${supplied.length} supplied via FUNOTEKA_PRIVATE_VALUES`,
+);
+console.log();
+
+let findings = 0;
+console.log('private values (by value, not by meta name):');
+for (const [position, rule] of rules.entries()) {
+  const found = hits[position];
+  if (found.length === 0) continue;
+  findings += 1;
+  console.log(`  ✗ ${rule.pattern} — ${rule.why}: ${found.length} line(s)`);
+  for (const line of found.slice(0, 5)) console.log(`      ${line}`);
+  if (found.length > 5) console.log(`      … and ${found.length - 5} more`);
+}
+if (findings === 0) console.log('  ✓ zero hits');
+
+console.log('\nmeta and machine-local files in the tree:');
+if (meta.size === 0) console.log('  ✓ none');
+else {
+  findings += meta.size;
+  for (const name of [...meta].sort()) console.log(`  ✗ ${name}`);
+}
+
+console.log(`\nverdict: ${findings === 0 ? 'publishable' : `NOT publishable — ${findings} finding(s)`}`);
+process.exit(findings === 0 ? 0 : 1);