@nspot/geo-engine 0.1.0 → 0.2.1

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                                  |
@@ -168,23 +178,3 @@ writing rows or editing regions at that moment. Registering a source is as power
 writing a trigger by hand — only let database administrators call `registerSource` /
 `unregisterSource` (the underlying `geo.register_source` / `geo.unregister_source` are not
 executable by PUBLIC).
-
-## Releasing
-
-`pnpm sdk:rehearsal` (from the repo root) packs the SDK and installs it into a throwaway
-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.
-
-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.1",
   "description": "Region membership for your own PostGIS tables: install the geo schema, register tables, install region packs, query by region.",
   "license": "MIT",
   "type": "module",
@@ -11,7 +11,7 @@
     ".": { "types": "./dist/index.d.ts", "import": "./dist/index.js" },
     "./types": { "types": "./dist/types.d.ts", "import": "./dist/types.js" }
   },
-  "bin": { "geo-engine": "./dist/cli.js" },
+  "bin": { "geo-engine": "dist/cli.js" },
   "files": ["dist", "sql", "README.md", "LICENSE"],
   "engines": { "node": ">=20" },
   "repository": {