@nspot/geo-engine 0.2.0 → 0.3.0

package/README.md

@@ -67,6 +67,15 @@ path. Pass `{ resolveFrom }` to resolve the package name from a directory other
 `process.cwd()`. A pack package must expose `pack.json`; if its `package.json` declares
 an `exports` map, that map must include `"./pack.json"`.
 
+A pack may build on another: a region's `parent` is a slug, found first among the same
+pack's regions and then among any other installed pack's (never among your local regions).
+Links are remade after every install, so packs can be installed in any order, and
+reinstalling a parent pack restores the links its uninstall cut. `exportPack(pool, slug,
+version, { owner, slugPrefix })` exports every region, or only one owner's (`"local"` for
+the regions no pack owns, or a pack's slug) and/or those under a slug prefix; a scoped
+export names only the countries it needs, with no outline, so installing it never
+overwrites one. Both need schema 7 (`@nspot/geo-engine` 0.3.0).
+
 **4. Filter your own query by region.**
 
 ```ts
@@ -178,71 +187,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, 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/packs.d.ts

@@ -8,7 +8,25 @@ export interface InstallPackOptions {
     /** 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>;
+export interface ExportPackOptions {
+    /**
+     * Whose regions to export: `"local"` for the regions no pack owns, or an installed pack's
+     * slug for that pack's regions. Omitted, every region is exported.
+     */
+    owner?: string;
+    /** Export only regions whose slug starts with this. */
+    slugPrefix?: string;
+}
+/**
+ * The database's regions as one pack document, named `slug`@`version`.
+ *
+ * Unscoped, it holds every region and every country with its outline. Scoped (`owner` or
+ * `slugPrefix`), it holds the chosen regions and only the countries they and their parents
+ * sit in, with no outline, so installing it never overwrites one. A region's `parent` is its
+ * parent's slug wherever that parent lives; a pack region whose parent is in another pack
+ * gets linked to it when both are installed (schema 7).
+ */
+export declare function exportPack(db: Queryable, slug: string, version: string, opts?: ExportPackOptions): Promise<Pack>;
 /**
  * Install a pack into the database.
  *

package/dist/packs.js

@@ -6,8 +6,22 @@ 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]);
+/**
+ * The database's regions as one pack document, named `slug`@`version`.
+ *
+ * Unscoped, it holds every region and every country with its outline. Scoped (`owner` or
+ * `slugPrefix`), it holds the chosen regions and only the countries they and their parents
+ * sit in, with no outline, so installing it never overwrites one. A region's `parent` is its
+ * parent's slug wherever that parent lives; a pack region whose parent is in another pack
+ * gets linked to it when both are installed (schema 7).
+ */
+export async function exportPack(db, slug, version, opts = {}) {
+    const rows = await run(db, "SELECT geo.export_pack($1, $2, $3, $4) AS pack", [
+        slug,
+        version,
+        opts.owner ?? null,
+        opts.slugPrefix ?? null,
+    ]);
     return rows[0].pack;
 }
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nspot/geo-engine",
-  "version": "0.2.0",
+  "version": "0.3.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",
@@ -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": {

package/sql/007_pack_scope.sql

@@ -0,0 +1,199 @@
+-- ============================================================================
+-- 007 — packs that build on other packs
+--
+-- A pack may name a parent that lives in another pack (a commune pack whose
+-- communes sit in the Romania pack's județ). Every pack region keeps the parent
+-- its pack declared, and the link is made to whichever pack region carries that
+-- slug: the pack's own first (a slug is unique per country, so there is only
+-- one), else another pack's. A local region is never adopted, since a pack
+-- cannot know about it. Links are remade after every install, so the order in
+-- which packs are installed does not matter, and reinstalling a parent pack
+-- restores the links its uninstall cut (ON DELETE SET NULL).
+--
+-- export_pack gains a scope: the regions of one owner (a pack slug, or 'local'
+-- for regions no pack owns) and/or a slug prefix. A scoped pack names only the
+-- countries it needs, with no outline, so installing it never overwrites the
+-- outline another pack or the host set.
+-- ============================================================================
+
+ALTER TABLE geo.regions
+  ADD COLUMN declared_parent         text,
+  ADD COLUMN declared_parent_country text;
+
+COMMENT ON COLUMN geo.regions.declared_parent IS
+  'For a pack region: the parent slug its pack declared, resolved by geo.link_pack_parents()';
+COMMENT ON COLUMN geo.regions.declared_parent_country IS
+  'For a pack region: the country code of its declared parent';
+
+-- Link every pack region to its declared parent among pack regions. Returns how
+-- many links changed.
+CREATE OR REPLACE FUNCTION geo.link_pack_parents() RETURNS int
+LANGUAGE plpgsql AS $$
+DECLARE
+  n int;
+BEGIN
+  UPDATE geo.regions r
+  SET parent_id = par.id
+  FROM geo.countries pc
+  JOIN geo.regions par ON par.country_id = pc.id AND par.pack_id IS NOT NULL
+  WHERE r.pack_id IS NOT NULL
+    AND r.declared_parent IS NOT NULL
+    AND pc.code = r.declared_parent_country
+    AND par.slug = r.declared_parent
+    AND par.id <> r.id
+    AND r.parent_id IS DISTINCT FROM par.id;
+  GET DIAGNOSTICS n = ROW_COUNT;
+  RETURN n;
+END $$;
+
+DROP FUNCTION geo.export_pack(text, text);
+CREATE OR REPLACE FUNCTION geo.export_pack(
+  p_slug        text,
+  p_version     text,
+  p_owner       text DEFAULT NULL,
+  p_slug_prefix text DEFAULT NULL
+) RETURNS jsonb
+LANGUAGE plpgsql STABLE AS $$
+DECLARE
+  owner_id int;
+  scoped   boolean := p_owner IS NOT NULL OR p_slug_prefix IS NOT NULL;
+BEGIN
+  IF p_owner IS NOT NULL AND p_owner <> 'local' THEN
+    SELECT id INTO owner_id FROM geo.packs WHERE slug = p_owner;
+    IF owner_id IS NULL THEN
+      RAISE EXCEPTION 'Unknown pack "%"', p_owner USING ERRCODE = 'invalid_parameter_value';
+    END IF;
+  END IF;
+
+  RETURN (
+    WITH sel AS (
+      SELECT r.*
+      FROM geo.regions r
+      WHERE (p_owner IS NULL
+             OR (p_owner = 'local' AND r.pack_id IS NULL)
+             OR r.pack_id = owner_id)
+        AND (p_slug_prefix IS NULL OR starts_with(r.slug, p_slug_prefix))
+    ),
+    feats AS (
+      SELECT c.code AS country, r.slug, jsonb_build_object(
+        'type', 'Feature',
+        'geometry', ST_AsGeoJSON(r.geom, 6)::jsonb,
+        'properties', jsonb_build_object(
+          'country', c.code, 'slug', r.slug, 'name', r.name, 'type', r.type, 'level', r.level,
+          'parent', coalesce(p.slug, r.declared_parent),
+          'parent_country', CASE WHEN p.id IS NOT NULL THEN pc.code ELSE r.declared_parent_country END,
+          'code', r.code, 'tags', to_jsonb(r.tags), 'properties', r.properties)) AS feature,
+        coalesce(pc.code, r.declared_parent_country) AS parent_country
+      FROM sel r
+      JOIN geo.countries c ON c.id = r.country_id
+      LEFT JOIN geo.regions p ON p.id = r.parent_id
+      LEFT JOIN geo.countries pc ON pc.id = p.country_id
+    ),
+    needed AS (
+      SELECT country AS code FROM feats
+      UNION
+      SELECT parent_country FROM feats WHERE parent_country IS NOT NULL
+    )
+    SELECT jsonb_build_object(
+      'pack', jsonb_build_object(
+        'slug', p_slug, 'version', p_version, 'schema_version', geo.schema_version(),
+        'published_at', to_char(now() AT TIME ZONE 'UTC', 'YYYY-MM-DD"T"HH24:MI:SS"Z"')),
+      'countries', coalesce((
+        SELECT jsonb_agg(jsonb_build_object(
+          'code', c.code, 'name', c.name,
+          'geometry', CASE WHEN scoped OR c.geom IS NULL THEN NULL ELSE ST_AsGeoJSON(c.geom, 6)::jsonb END
+        ) ORDER BY c.code)
+        FROM geo.countries c
+        WHERE NOT scoped OR c.code IN (SELECT code FROM needed)), '[]'::jsonb),
+      'regions', jsonb_build_object(
+        'type', 'FeatureCollection',
+        'features', coalesce((SELECT jsonb_agg(feature ORDER BY country, slug) FROM feats), '[]'::jsonb)))
+  );
+END $$;
+
+-- install_pack as in 005, except that it records each region's declared parent
+-- and links parents across packs.
+CREATE OR REPLACE FUNCTION geo.install_pack(p_pack jsonb) RETURNS jsonb
+LANGUAGE plpgsql AS $$
+DECLARE
+  hdr         jsonb := p_pack->'pack';
+  feats       jsonb := coalesce(p_pack->'regions'->'features', '[]'::jsonb);
+  pid         int;
+  f           jsonb;
+  n_countries int := 0;
+  n_regions   int := 0;
+  n_members   bigint;
+  code        text;
+BEGIN
+  IF hdr IS NULL OR coalesce(hdr->>'slug', '') = '' OR coalesce(hdr->>'version', '') = '' THEN
+    RAISE EXCEPTION 'Pack header must have slug and version' USING ERRCODE = 'invalid_parameter_value';
+  END IF;
+  IF coalesce((hdr->>'schema_version')::int, 0) > geo.schema_version() THEN
+    RAISE EXCEPTION 'Pack "%" needs schema version % but this database has %',
+      hdr->>'slug', hdr->>'schema_version', geo.schema_version()
+      USING ERRCODE = 'invalid_parameter_value';
+  END IF;
+
+  INSERT INTO geo.packs (slug, version, schema_version)
+  VALUES (hdr->>'slug', hdr->>'version', coalesce((hdr->>'schema_version')::int, geo.schema_version()))
+  ON CONFLICT (slug) DO UPDATE
+    SET version = EXCLUDED.version, schema_version = EXCLUDED.schema_version, installed_at = now()
+  RETURNING id INTO pid;
+
+  PERFORM set_config('geo.skip_membership_triggers', 'on', true);
+
+  FOR f IN SELECT * FROM jsonb_array_elements(coalesce(p_pack->'countries', '[]'::jsonb)) LOOP
+    PERFORM geo.upsert_country(f->>'code', f->>'name',
+      CASE WHEN jsonb_typeof(f->'geometry') = 'object' THEN f->'geometry' END);
+    n_countries := n_countries + 1;
+  END LOOP;
+
+  FOR f IN SELECT * FROM jsonb_array_elements(feats) LOOP
+    PERFORM geo.upsert_region(
+      f->'properties'->>'country',
+      f->'properties'->>'slug',
+      f->'properties'->>'name',
+      (f->'properties'->>'type')::geo.region_type,
+      (f->'properties'->>'level')::int,
+      NULL,
+      f->'properties'->>'code',
+      ARRAY(SELECT jsonb_array_elements_text(coalesce(f->'properties'->'tags', '[]'::jsonb))),
+      coalesce(f->'properties'->'properties', '{}'::jsonb),
+      f->'geometry',
+      true,
+      pid);
+    n_regions := n_regions + 1;
+  END LOOP;
+
+  -- regions that left the pack
+  DELETE FROM geo.regions r
+  USING geo.countries c
+  WHERE r.pack_id = pid AND c.id = r.country_id
+    AND NOT EXISTS (
+      SELECT 1 FROM jsonb_array_elements(feats) ff
+      WHERE upper(ff->'properties'->>'country') = c.code AND ff->'properties'->>'slug' = r.slug);
+
+  -- the parent each region declares (a slug, in its parent_country or its own)
+  UPDATE geo.regions r
+  SET declared_parent = nullif(ff->'properties'->>'parent', ''),
+      declared_parent_country = CASE WHEN nullif(ff->'properties'->>'parent', '') IS NULL THEN NULL
+        ELSE upper(coalesce(ff->'properties'->>'parent_country', ff->'properties'->>'country')) END
+  FROM jsonb_array_elements(feats) ff
+  JOIN geo.countries c ON c.code = upper(ff->'properties'->>'country')
+  WHERE r.pack_id = pid AND r.country_id = c.id AND r.slug = ff->'properties'->>'slug';
+
+  -- parents among pack regions, this pack's and every other's
+  PERFORM geo.link_pack_parents();
+
+  FOR code IN SELECT c.code FROM geo.countries c WHERE c.geom IS NULL LOOP
+    PERFORM geo.derive_country_geom(code);
+  END LOOP;
+
+  n_members := geo.rebuild_all_memberships();
+  PERFORM set_config('geo.skip_membership_triggers', 'off', true);
+  RETURN jsonb_build_object(
+    'pack', hdr->>'slug', 'version', hdr->>'version',
+    'countries', n_countries, 'regions', n_regions, 'memberships', n_members);
+END $$;
+
+SELECT geo.pin_search_path();