@nspot/geo-engine 0.1.0 → 0.2.0

package/README.md

@@ -55,7 +55,17 @@ import { installPack } from "@nspot/geo-engine";
 await installPack(pool, "https://example.com/packs/romania-1.0.0.json");
 ```
 
-`installPack` also accepts a file path or an already-parsed pack object.
+`installPack` also accepts a file path, an already-parsed pack object, or a bare npm
+package name, resolved like `require()` to `<package>/pack.json`:
+
+```ts
+await installPack(pool, "@nspot/geo-pack-romania");
+```
+
+so hosts can `npm i @nspot/geo-pack-romania` and install it without knowing a URL or file
+path. Pass `{ resolveFrom }` to resolve the package name from a directory other than
+`process.cwd()`. A pack package must expose `pack.json`; if its `package.json` declares
+an `exports` map, that map must include `"./pack.json"`.
 
 **4. Filter your own query by region.**
 
@@ -114,7 +124,7 @@ usage: geo-engine <command> [options]
   register --name N --table [S.]T --id C (--geometry G | --lng X --lat Y)
   unregister --name N
   rebuild [--source N]                    recompute memberships (one source or all)
-  pack install <url|file>
+  pack install <url|file|package>
   pack list
   pack uninstall <slug>
 
@@ -136,7 +146,7 @@ database, and `cause` when it wraps something else (a zod `ZodError`, a fetch fa
 | `invalid_input`  | Postgres rejected a value (`22023`) — e.g. a malformed geometry or invalid enum value |
 | `invalid_input`  | `idType` is not a plain SQL type name (`inRegions` / `notInRegions`), raised before any SQL is built |
 | `invalid_input`  | `filter.regions` is empty in `inRegions` / `ids`, raised before the database is touched |
-| `invalid_input`  | `installPack` could not download, read or JSON-parse the pack (`cause` is the underlying error) |
+| `invalid_input`  | `installPack` could not download, read, resolve or JSON-parse the pack (`cause` is the underlying error) |
 | `invalid_input`  | the pack document failed validation — `Invalid pack document: <path>: <issue>; …`, `cause` is the `ZodError` |
 | `invalid_input`  | `migrate` found a database whose schema is newer than the one this package ships   |
 | `unknown_source` | the request named a source that isn't registered                                  |
@@ -175,16 +185,64 @@ executable by PUBLIC).
 project against a scratch database; run it before every release.
 
 To cut a release: bump `version` in `packages/sdk-node/package.json`, run
-`pnpm sdk:rehearsal` and confirm it passes, commit the version bump, tag the commit
-`sdk-node-v<version>` (e.g. `sdk-node-v0.1.0`), and push the tag. Pushing a tag matching
-`sdk-node-v*` runs `.github/workflows/publish-sdk.yml`, which checks the tag against
-`package.json`'s version, builds the package, runs the full SDK test suite against a
-PostGIS service container, and publishes to npm with provenance.
-
-One-time setup, before the first release: create the `@nspot` organisation on npm,
-generate an automation token scoped to it, and add that token as the repository secret
-`NPM_TOKEN`. Without the secret the workflow is not inert: pushing a matching tag still
-runs it, and it goes all the way through the checks, build and tests before failing at
-the publish step. Add the secret before pushing the first tag.
+`pnpm sdk:rehearsal` and confirm it passes, and open a pull request with the bump. There is
+no release tag to push by hand — when the pull request merges and CI passes on `main`,
+`.github/workflows/publish-sdk.yml` publishes it to npm, tags the commit
+`sdk-node-v<version>` and creates a GitHub release for it.
+
+That workflow publishes *every* publishable package in the repository whose version is not
+on npm yet, not only the SDK. `node scripts/publishable.mjs --all` lists every publishable
+package (one JSON line each — `name`, `version`, `dir`, `tag`, `published`), and the job
+walks that list in order:
+
+- a package whose version is **not** on npm is published (`npm publish --access public`);
+- every package that is on npm — published just now or long since — then has its tag
+  (`sdk-node-v<version>` for the SDK, `pack-<slug>-v<version>` for a region pack) and its
+  GitHub release created if they are missing, and left alone if they are not.
+
+A merge that bumps nothing publishes nothing; the job still runs, finds everything in
+order, and exits green.
+
+What "idempotent" means here is worth being precise about, because a re-run does more than
+skip work. Re-running the job **repairs** a half-finished release: a package that published
+successfully but whose tag push or release creation failed gets its tag and release on the
+next run, instead of being skipped forever because it is now on npm. And one package
+failing no longer stops the rest — a failure is recorded and the loop continues to the next
+package, with the job failing at the end and naming everything that went wrong. So it is
+always safe, and often useful, to re-run by hand from the Actions tab
+(`workflow_dispatch`).
+
+A manual run publishes **the current `main`**, not the commit of an older run: it checks
+out `main`'s head, and the job refuses to run on any other branch. There is no way to
+re-publish a past commit from the Actions tab; to release again, merge another bump.
+
+Only one publish runs at a time (`concurrency: publish`, never cancelled mid-flight). Two
+merges landing within a minute can therefore drop the middle run — a queued run is
+superseded by a newer one. That is harmless: the gate is "is this version on npm", not "did
+this commit run", so a version bump superseded before it published simply publishes on the
+next merge.
+
+The workflow publishes through npm Trusted Publishing (OpenID Connect), so there is no token
+and no repository secret. npm binds a trusted publisher to a workflow **filename**, which is
+why the file is still called `publish-sdk.yml` now that it publishes the packs too.
+
+Publishing does *not* pass `--provenance`: npm only accepts provenance attestations from a
+public source repository, and this repository is private, so asking for one fails the
+publish outright. Trusted publishing itself is unaffected. If the repository is ever made
+public, trusted publishing generates provenance on its own — no flag needed.
+
+The first version of a *new* package cannot be published by CI, because a trusted publisher
+can only be configured on a package that already exists. For each new package, once:
+
+1. Publish the first version from your machine: in the package directory run `npm login` and
+   `npm publish --access public` (for the SDK, npm runs `prepack`, which syncs the SQL and
+   builds; it asks for a one-time 2FA code).
+2. On npmjs.com open the package, Settings, Trusted Publisher, GitHub Actions: organisation
+   `NSpot-Games`, repository `geo-engine`, workflow filename `publish-sdk.yml`, environment
+   empty.
+
+Until both are done for a package, the publish job runs and fails at `npm publish` for it.
+`@nspot/geo-engine` is past that point: 0.1.0 was published by hand on 2026-09-16 and its
+trusted publisher is configured, so every later version comes from a merge to `main`.
 
 A Python SDK does not exist yet.

package/dist/cli.js

@@ -9,7 +9,7 @@ const USAGE = `usage: geo-engine <command> [options]
   register --name N --table [S.]T --id C (--geometry G | --lng X --lat Y)
   unregister --name N
   rebuild [--source N]                    recompute memberships (one source or all)
-  pack install <url|file>
+  pack install <url|file|package>
   pack list
   pack uninstall <slug>
 
@@ -92,7 +92,7 @@ async function run() {
         else if (command === "pack") {
             const sub = positionals[1];
             if (sub === "install") {
-                const source = positionals[2] ?? usageError("usage: geo-engine pack install <url|file>");
+                const source = positionals[2] ?? usageError("usage: geo-engine pack install <url|file|package>");
                 const r = await installPack(pool, source);
                 console.log(`installed ${r.pack}@${r.version}: ${r.regions} regions, ${r.countries} countries, ${r.memberships} memberships`);
             }

package/dist/packs.d.ts

@@ -5,9 +5,24 @@ export interface InstallPackOptions {
     fetch?: typeof fetch;
     /** Abort an http(s) pack download after this many milliseconds; defaults to 30000. */
     timeoutMs?: number;
+    /** Directory to resolve a bare package name from; defaults to process.cwd(). */
+    resolveFrom?: string;
 }
 export declare function exportPack(db: Queryable, slug: string, version: string): Promise<Pack>;
-/** Install a pack given as a parsed document, a file path, or an http(s) URL. */
+/**
+ * Install a pack into the database.
+ *
+ * `source` is a parsed pack document, or a string in one of three forms:
+ *
+ * - **an npm package name** — `"@nspot/geo-pack-romania"`, or an unscoped `"geo-pack-x"` —
+ *   resolved to that package's `pack.json` the way `require()` would, starting from
+ *   `opts.resolveFrom` (default: the current working directory). This is how first-party
+ *   packs are distributed: `npm i @nspot/geo-pack-romania`, then pass the name.
+ * - **a file path** — `"./packs/romania/pack.json"`, relative to the current working
+ *   directory, or absolute. An existing file always wins: a path that happens to look like
+ *   a package name is read as a file when the file is there.
+ * - **an `http(s)` URL**, downloaded with a timeout (`opts.timeoutMs`, default 30s).
+ */
 export declare function installPack(db: Queryable, source: Pack | string, opts?: InstallPackOptions): Promise<InstallPackResult>;
 /** Removes the pack's regions and the pack row; returns how many regions were removed. */
 export declare function uninstallPack(db: Queryable, slug: string): Promise<number>;

package/dist/packs.js

@@ -1,12 +1,29 @@
+import { statSync } from "node:fs";
 import { readFile } from "node:fs/promises";
+import { createRequire } from "node:module";
+import path from "node:path";
 import { GeoEngineError, run } from "./errors.js";
 import { packSchema } from "./types.js";
 const DEFAULT_TIMEOUT_MS = 30_000;
+const PACKAGE_NAME_RE = /^(@[a-z0-9-~][a-z0-9-._~]*\/)?[a-z0-9-~][a-z0-9-._~]*$/;
 export async function exportPack(db, slug, version) {
     const rows = await run(db, "SELECT geo.export_pack($1, $2) AS pack", [slug, version]);
     return rows[0].pack;
 }
-/** Install a pack given as a parsed document, a file path, or an http(s) URL. */
+/**
+ * Install a pack into the database.
+ *
+ * `source` is a parsed pack document, or a string in one of three forms:
+ *
+ * - **an npm package name** — `"@nspot/geo-pack-romania"`, or an unscoped `"geo-pack-x"` —
+ *   resolved to that package's `pack.json` the way `require()` would, starting from
+ *   `opts.resolveFrom` (default: the current working directory). This is how first-party
+ *   packs are distributed: `npm i @nspot/geo-pack-romania`, then pass the name.
+ * - **a file path** — `"./packs/romania/pack.json"`, relative to the current working
+ *   directory, or absolute. An existing file always wins: a path that happens to look like
+ *   a package name is read as a file when the file is there.
+ * - **an `http(s)` URL**, downloaded with a timeout (`opts.timeoutMs`, default 30s).
+ */
 export async function installPack(db, source, opts = {}) {
     const raw = typeof source === "string" ? await loadPack(source, opts) : source;
     const doc = parsePack(raw);
@@ -43,21 +60,55 @@ async function loadPack(source, opts) {
             throw new GeoEngineError("invalid_input", `Pack at ${source} is not valid JSON: ${messageOf(cause)}`, { cause });
         }
     }
+    let file = source;
+    if (!isFile(source) && PACKAGE_NAME_RE.test(source)) {
+        try {
+            // path.resolve, not path.join: resolveFrom may be relative, and createRequire only
+            // accepts an absolute path or a file URL.
+            const req = createRequire(path.resolve(opts.resolveFrom ?? process.cwd(), "noop.js"));
+            file = req.resolve(`${source}/pack.json`);
+        }
+        catch (cause) {
+            // "pack.json" is a syntactically valid package name, so a source ending in .json that
+            // got this far was probably meant as a file path that is simply not there. Say so,
+            // rather than leaving the caller with a resolver error about a package they never had.
+            const alsoNotAFile = /\.json$/i.test(source)
+                ? ` (and no file named ${path.resolve(source)} exists either)`
+                : "";
+            throw new GeoEngineError("invalid_input", `Failed to resolve pack package ${source}${alsoNotAFile}: ${messageOf(cause)}`, { cause });
+        }
+    }
     let text;
     try {
-        text = await readFile(source, "utf8");
+        text = await readFile(file, "utf8");
     }
     catch (cause) {
-        throw new GeoEngineError("invalid_input", `Failed to read pack file ${source}: ${messageOf(cause)}`, { cause });
+        throw new GeoEngineError("invalid_input", `Failed to read pack file ${file}: ${messageOf(cause)}`, { cause });
     }
     try {
         return JSON.parse(text);
     }
     catch (cause) {
-        throw new GeoEngineError("invalid_input", `Pack file ${source} is not valid JSON: ${messageOf(cause)}`, { cause });
+        throw new GeoEngineError("invalid_input", `Pack file ${file} is not valid JSON: ${messageOf(cause)}`, { cause });
     }
 }
 const messageOf = (err) => (err instanceof Error ? err.message : String(err));
+/**
+ * Does this path point at an existing file?
+ *
+ * `throwIfNoEntry: false` only covers ENOENT; a path component that is not a directory
+ * (ENOTDIR), an unreadable parent (EACCES) or a symlink loop (ELOOP) still throw. None of
+ * those is a file, and none of them should stop us trying the package-name interpretation,
+ * so every throw means "no".
+ */
+function isFile(p) {
+    try {
+        return statSync(p, { throwIfNoEntry: false })?.isFile() ?? false;
+    }
+    catch {
+        return false;
+    }
+}
 /** Removes the pack's regions and the pack row; returns how many regions were removed. */
 export async function uninstallPack(db, slug) {
     const rows = await run(db, "SELECT geo.uninstall_pack($1) AS n", [slug]);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nspot/geo-engine",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Region membership for your own PostGIS tables: install the geo schema, register tables, install region packs, query by region.",
   "license": "MIT",
   "type": "module",