ekwo-os 0.6.0 → 0.8.0

package/README.md

@@ -6,13 +6,17 @@ books: the schema, the chart of accounts, the VAT codes, the first
 administrator, the first company and its first financial year.
 
 ```sh
-npx ekwo-os init
+npx -y ekwo-os@latest init
 ```
 
-The package is `ekwo-os` and the command it installs is `ekwo`: `npx ekwo-os
-<command>` runs it without installing anything, and after
-`npm install -g ekwo-os` every example below that starts with `ekwo ` works as
-written.
+The package is `ekwo-os` and the command it installs is `ekwo`:
+`npx -y ekwo-os@latest <command>` runs it without installing anything, and
+after `npm install -g ekwo-os` every example below that starts with `ekwo `
+works as written. Keep the version in the command: run from inside a clone of
+the Ekwo repository, a bare `npx ekwo-os` finds the workspace package of the
+same name, which links no command, and answers `ekwo: command not found`. With
+`@latest`, `npx` fetches the published CLI wherever it is started; the clone's
+own is `node packages/cli/dist/bin.js`, after `npm run build`.
 
 You need Node 20 or later. That is the whole list. The Supabase CLI is not
 required — this talks to Postgres directly — and Docker is not required
@@ -26,9 +30,11 @@ either.
 2. **Copy two things** from the dashboard:
    - Project Settings → Database → **Connection string** (URI). It contains
      your database password.
-   - Project Settings → API → **`service_role` key**, and the **Project URL**.
-     These are used once, to create the first administrator in your own
-     Supabase Auth, and are never written to disk.
+   - Project Settings → API Keys → the **secret key** (`sb_secret_…`), and the
+     **Project URL**. A project created before the new keys has the legacy
+     **`service_role` key** instead, and it works the same. These are used
+     once, to create the first administrator in your own Supabase Auth, and
+     are never written to disk.
 
    **Take the pooler string, not the direct one, unless you know you have
    IPv6.** The direct host `db.<ref>.supabase.co` resolves to an IPv6 address
@@ -48,7 +54,7 @@ either.
 3. **Run the installer.**
 
    ```sh
-   npx ekwo-os init
+   npx -y ekwo-os@latest init
    ```
 
    It asks for the connection string, the country, the chart of accounts and
@@ -71,7 +77,7 @@ either.
 Everything above in one non-interactive line:
 
 ```sh
-npx ekwo-os init \
+npx -y ekwo-os@latest init \
   --db-url "postgresql://postgres.YOURREF:PASSWORD@aws-1-eu-west-3.pooler.supabase.com:5432/postgres" \
   --supabase-url "https://YOURREF.supabase.co" \
   --service-role-key "$SUPABASE_SERVICE_ROLE_KEY" \
@@ -117,6 +123,52 @@ in `defaults.fiscal_year_default`; one that names none — the United Kingdom's,
 where a company's year ends on the accounting reference date it chose — asks
 for the day.
 
+`ekwo company new` asks the same questions about every other company, and
+refuses the same way.
+
+## Several countries in one installation: `init --no-company`
+
+An installation is not in a country; its companies are. `ekwo init` loads every
+pack of the release whatever `--country` says, so one installation keeps the
+books of companies in as many countries as it holds packs. When there is no
+"first company" to name — a group, a firm, a holding with subsidiaries abroad —
+install without one, then create each company in its own country:
+
+```sh
+npx -y ekwo-os@latest init --no-company \
+  --db-url "$EKWO_DB_URL" --supabase-url "https://YOURREF.supabase.co" \
+  --service-role-key "$SUPABASE_SERVICE_ROLE_KEY" \
+  --org "My Group" --admin-email "you@example.com" --yes
+
+ekwo company new "My Company Belgium" --country BE --chart default --language nl --yes
+ekwo company new "My Company France"  --country FR --language fr --yes
+ekwo company list
+```
+
+`--no-company` runs the migrations, the seeds of every pack, the modules, the
+first administrator, `init_instance()` and `claim_instance_admin()`, and
+nothing else. The instance row records no country. A flag that only describes
+a company — `--country`, `--company`, `--chart`, `--language`, `--currency`,
+`--fiscal-year`, `--fiscal-year-start`, `--vat-period`, `--filing-period`,
+`--iban`, `--bic`, `--bank-name` — is refused with it, exit code 2, before the
+database is touched: it would describe nothing.
+
+**`ekwo company new` is `create_company()`**, the function the `create_company`
+tool of the MCP server calls: the country pack copied in, the first financial
+year opened, the administrator its first owner. It is called as an
+administrator of the installation — `--as-user`, or the only one when there is
+exactly one — so the database judges that person exactly as it judges the tool:
+anybody else is refused, `not_instance_admin`, exit code 3. Before the call,
+the CLI asks what `ekwo init` asks about its first company, from the packs the
+installation holds, and refuses the same way off a terminal: no country without
+`--country`, and `--chart`, `--language` and `--fiscal-year-start` wherever the
+pack offers a choice. `--currency` and `--fiscal-year` override the pack and
+this year.
+
+Without `--no-company`, `ekwo init` does what it always did, and the installation
+takes more companies later the same way. Neither writes a country into
+`ekwo.json`: see below.
+
 ## Where table access comes from
 
 **The schema grants its own rights.** Every table, view and function of Ekwo
@@ -222,7 +274,7 @@ and read by a person.
 | 2 | Applies every reference seed of `supabase/seed/`, in file-name order: `00_currencies.sql`, `00_territories.sql`, `05_framework_generic.sql`, then one `<n>_pack_<cc>.sql` per country pack, in the order of the number each pack declares | The currencies, the territories the tax rules name, the country-less financial statements every chart falls back on, and every country pack of the release — so a company in any of them can be created later without installing anything. They are exactly the seeds `supabase/config.toml` lists (a list `ekwo pack build` writes from `packs/`), so `supabase db push` installs the same set; a test compares both paths row by row. `90_demo_company.sql` is sample data and is never applied here |
 | 3 | Creates the first administrator through the Supabase Auth admin API | See below: a database connection cannot be a signed-in user |
 | 4 | `init_instance()`, `claim_instance_admin()`, the company, `company_members` as owner, `install_country_template()`, the first financial year, and the bank account when an IBAN was given | The six steps of the root README, in the same order, plus the one thing nobody can derive |
-| 5 | Writes `ekwo.json` | Project URL, country, schema version. Nothing else, ever |
+| 5 | Writes `ekwo.json` | The installation: project URL and schema version. Nothing else, ever — no country, since each company carries its own. A file written by 0.6 or earlier also names a country; it is still read, and the key is taken for nothing |
 | 6 | Asks whether to register with Ekwo | The default answer is no, and no is a supported answer forever |
 
 Every step checks before it acts. Running `ekwo init` twice on the same
@@ -250,7 +302,7 @@ instead if the account already exists, and no key is needed.
 
 | Command | What it does |
 |---|---|
-| `ekwo init` | The whole installation, interactive or not: the socle's migrations, the reference seeds, then the modules', as `ekwo migrate` applies them. |
+| `ekwo init` | The whole installation, interactive or not: the socle's migrations, the reference seeds, then the modules', as `ekwo migrate` applies them. `--no-company` stops before the first company: see [several countries](#several-countries-in-one-installation-init---no-company). |
 | `ekwo migrate` | Applies the migrations this release adds, after showing the gap — the socle's, then the modules'. Re-applies the reference seeds, which are idempotent. `--no-modules` leaves the modules alone. |
 | `ekwo status` | Schema version installed against available, pending migrations, the instance, its administrators, the country packs it holds and, per company, the pack version it copied. Exits 1 when something is pending. |
 | `ekwo doctor` | Every object this release defines and every privilege it grants, against what the database holds; row level security on every table, a policy on every protected table, no pending migration, no membership pointing at a deleted user, every company with a bank account, statements that tie to their lines, posted entries that balance. Exits 1 on a problem, 0 on warnings. |
@@ -258,7 +310,7 @@ instead if the account already exists, and no key is needed.
 | `ekwo unregister` | Opt back out. Clears the address and the date on the instance row. |
 | `ekwo demo` | Loads the sample company. Fictional data, explicit request only. |
 | `ekwo module` | What is installed beside the socle, applies a module's migrations and its country seeds, and turns one on or off for a company. |
-| `ekwo company` | One company leaves an installation with its books — `export` writes an archive anybody can read, as a member under row level security — and arrives in another one alive: `import` takes it in whole or not at all. |
+| `ekwo company` | `new` creates a company in its own country, through `create_company()`, and `list` shows the companies held here. One company leaves an installation with its books — `export` writes an archive anybody can read, as a member under row level security — and arrives in another one alive: `import` takes it in whole or not at all. |
 | `ekwo pack` | Compiles a country pack into its seed, and refuses a seed that is no longer the output of its pack. Runs in a checkout of the repository only. |
 | `ekwo login` | Signs in to an instance as yourself and keeps the session, in your own configuration directory. See [acting as a person](#acting-as-a-person-login-use-whoami). |
 | `ekwo logout` | Ends that session, here and on the instance. |
@@ -515,7 +567,7 @@ source, and nothing is posted while an account has no answer:
 ```bash
 ekwo import fec 123456789FEC20251231.txt --dry-run --open-years --save-mapping map.json
 #   read, propose a correspondence, rehearse the import in the database, take it back
-$EDITOR map.json                                   # answer what is null, correct what is wrong
+$EDITOR map.json                                   # answer what is null — read `suggested` — correct what is wrong
 ekwo import fec 123456789FEC20251231.txt --mapping map.json --open-years
 ekwo import trial-balance balance.csv --opening-date 2026-01-01 --dry-run --save-mapping map.json
 ekwo import journal-items items.csv accounts.csv partners.csv --dry-run --save-mapping map.json
@@ -540,23 +592,33 @@ official page and state.
 
 **The correspondence is yours.** Every account of the old chart has to become
 an account of the company's chart, and every old journal a journal of the
-company. The core proposes, from the codes alone — the same code, the same
-digits without the zeros a chart pads with (`411` and `411000`), or the
-account whose digits are the longest beginning of the old code, three at least
-(`401ACME` → `401000`); a tie is no answer — and each proposal says which rule
-found it. `--save-mapping` writes it as JSON:
+company. The codes give a candidate — the same code, the same digits without
+the zeros a chart pads with (`411` and `411000`), or the account whose digits
+are the longest beginning of the old code, three at least (`401ACME` and
+`401000`); a tie is no answer — and what the files say of the old account —
+the type its export gives it, its name, the side of its balance — is held
+against the type of the candidate in the chart, because two charts give the
+same digits to different things. Only the same code, not contradicted, is
+`exact`. Anything else is `suggested`, with its reason, and waits for you; a
+candidate the files contradict is dropped for the one account of the chart of
+the kind they say. `--dry-run` prints the lines to read first, each with its
+reason, and `--save-mapping` writes the correspondence as JSON:
 
 ```json
 {
   "version": 1,
   "source": "fec",
-  "accounts": { "411000": "411000", "401ACME": "401000", "471200": null },
-  "journals": { "VE": "SAL", "AN": "@opening", "BQ1": "MISC" }
+  "accounts": { "411000": "411000", "401ACME": null, "471200": null },
+  "journals": { "VE": "SAL", "AN": "@opening", "BQ1": "MISC" },
+  "suggested": { "401ACME": { "target": "401000", "reason": "the longest beginning of the code the chart has; …" } }
 }
 ```
 
 and `--mapping` gives it back: what it answers wins over the proposal, so the
-second run posts what the first one showed. A journal mapped to `@opening`
+second run posts what the first one showed. A suggestion is confirmed by
+writing its code under `accounts`; `--accept-suggestions` takes all of them
+once you have read them. Nothing is posted while one the books use is only
+suggested. A journal mapped to `@opening`
 becomes the opening entry of its year instead of ordinary entries — the
 *à-nouveaux* of a FEC, typically. A journal whose code is the one the pack
 opens years on is proposed as `@opening` on its own; `*` stands for entries
@@ -580,7 +642,7 @@ dry run reads the file and asks nothing: a statement books nothing anyway.
 What else to know:
 
 - **Refused before the database is asked**, and listed under `refusals` by a
-  dry run: an account or a journal with no answer, books whose reader found
+  dry run: an account or a journal with no answer or only a suggestion, books whose reader found
   something that does not add up (an entry that does not balance, a line of a
   draft entry), a currency the files name that is not the company's.
 - **The numbers** are drawn by the journal each entry goes to; the old number
@@ -592,7 +654,8 @@ What else to know:
   statements, and no box of a VAT return. A period kept elsewhere was declared
   from where it was kept.
 - **The same files twice are refused** (`import_already_done`): `book_imports`
-  keeps the checksum of what each import read.
+  keeps the checksum of what each import read, and the refusal says which
+  files, when, and what that import wrote.
 - **Dates and encodings are said, never guessed**: `--encoding` for a file
   that is not UTF-8, `--date-order` for a report that writes dates in digits.
 - **Reconciliation marks are read and not re-applied yet**: the matching of an
@@ -631,9 +694,23 @@ them as history it has no file for.
 
 ## `ekwo company`
 
-A firm keeps several companies in one installation, and each of them belongs to
-somebody. These two commands are how one of them leaves, and arrives somewhere
-else.
+A firm keeps several companies in one installation, each in its own country,
+and each of them belongs to somebody. `new` creates one and `list` shows them —
+see [several countries](#several-countries-in-one-installation-init---no-company):
+
+```sh
+ekwo company new "My Company Belgium" --country BE --chart default --language fr
+ekwo company new "My Company France" --country FR --language fr
+ekwo company list                                     # name, country, currency, language, chart, pack, members
+```
+
+`company new --json` answers the company (`id`, `country`, `currency`,
+`language`, `chart`, `packVersion`), its first financial year and its owner;
+`company list --json` answers `companies`, one per company. Both shapes are
+under `$defs/data` of the output schema, and the exit codes are the ones every
+command has: 2 for a missing answer, 3 when the database refuses.
+
+The two commands below are how a company leaves, and arrives somewhere else.
 
 ```sh
 ekwo company export "My Company" --out ./my-company   # manifest.json + data/<schema>.<table>.jsonl
@@ -810,7 +887,7 @@ Every command takes the connection flags:
 | `--db-password <pw>` | Database password. Prompted, masked, when omitted. |
 | `--db-region <region>` | With `--project-ref`, the session pooler in that region. Both generation prefixes are tried and the one that answers is kept. |
 | `--supabase-url <url>` | `https://<ref>.supabase.co`. Needed only to create a user. |
-| `--service-role-key <key>` | Needed only to create a user. |
+| `--service-role-key <key>` | Needed only to create a user. Either form Supabase issues: a secret key, `sb_secret_…`, sent on the `apikey` header alone because it is not a JWT, or the legacy `service_role` JWT, sent on `apikey` and as a Bearer as before. |
 | `--yes`, `-y` | Never ask a question. Everything must come from flags or the environment. |
 
 `--project-ref` with `--db-password` and `--db-region` builds the session
@@ -845,6 +922,12 @@ dashboard under Connect → Session pooler, is the form that is never derived.
 | `--register` | Register without being asked. `--register-email` sets the address. |
 | `--registry-url <url>` | Where the registration is announced. |
 | `--no-modules` | Leave the modules out. By default `init` installs them, as `ekwo migrate` does — empty schemas until a company enables one. |
+| `--no-company` | Install without a company: schema, every pack, the modules, the first administrator, and no country on the instance row. The flags that only describe a company are refused with it. Then `ekwo company new`, once per company. |
+
+`ekwo company new <name>` takes `--country`, `--chart`, `--language`,
+`--currency`, `--fiscal-year` and `--fiscal-year-start` as `init` does, and
+`--as-user <uuid>`: the administrator of the installation it is created as,
+who becomes its owner — the only one, when there is exactly one.
 
 Every command takes `--json`; see [what a command answers](#what-a-command-answers---json-and-the-exit-codes).
 `ekwo migrate` takes `--skip-seeds`.

package/dist/assets/expected-objects.json

@@ -1,6 +1,6 @@
 {
-  "schemaVersion": "0.6.0",
-  "migration": "20260922091348",
+  "schemaVersion": "0.8.0",
+  "migration": "20260923093000",
   "socle": {
     "schema": "public",
     "tables": [
@@ -3743,6 +3743,10 @@
         "name": "amount_text_format",
         "arguments": "p_rounding money_rounding"
       },
+      {
+        "name": "api_key_company",
+        "arguments": ""
+      },
       {
         "name": "assert_may_close_year",
         "arguments": ""
@@ -3931,6 +3935,10 @@
         "name": "declaration_period_start",
         "arguments": "p_period declaration_period, p_day date"
       },
+      {
+        "name": "default_statement_code",
+        "arguments": "p_company_id uuid, p_kind text, p_at date"
+      },
       {
         "name": "disable_module",
         "arguments": "p_company_id uuid, p_code text"
@@ -3999,6 +4007,10 @@
         "name": "ec_sales_list",
         "arguments": "p_company_id uuid, p_from date, p_to date, p_report_code text"
       },
+      {
+        "name": "ekwo_pre_request",
+        "arguments": ""
+      },
       {
         "name": "ekwo_schema_version",
         "arguments": ""
@@ -4095,6 +4107,10 @@
         "name": "financial_statement",
         "arguments": "p_company_id uuid, p_statement_code text, p_from date, p_to date"
       },
+      {
+        "name": "financial_statement_of_kind",
+        "arguments": "p_company_id uuid, p_kind text, p_from date, p_to date"
+      },
       {
         "name": "fiscal_year_at",
         "arguments": "p_company_id uuid, p_date date"
@@ -4151,6 +4167,10 @@
         "name": "install_country_template",
         "arguments": "p_company_id uuid, p_country character, p_language character, p_chart_code text"
       },
+      {
+        "name": "installed_schema_version",
+        "arguments": ""
+      },
       {
         "name": "instance_has_no_admin",
         "arguments": ""
@@ -4183,6 +4203,10 @@
         "name": "is_instance_admin",
         "arguments": ""
       },
+      {
+        "name": "is_known_caller",
+        "arguments": ""
+      },
       {
         "name": "label_for",
         "arguments": "p_name text, p_i18n jsonb, p_languages text[]"
@@ -4315,6 +4339,10 @@
         "name": "prepare_filing",
         "arguments": "p_company_id uuid, p_from date, p_to date, p_report_code text"
       },
+      {
+        "name": "present_api_key",
+        "arguments": "p_secret text"
+      },
       {
         "name": "purge_audit_log",
         "arguments": "p_before date"
@@ -6817,6 +6845,19 @@
             "execute"
           ]
         },
+        {
+          "name": "api_key_company",
+          "arguments": "",
+          "anon": [
+            "execute"
+          ],
+          "authenticated": [
+            "execute"
+          ],
+          "service_role": [
+            "execute"
+          ]
+        },
         {
           "name": "assert_may_close_year",
           "arguments": "",
@@ -7281,6 +7322,17 @@
             "execute"
           ]
         },
+        {
+          "name": "default_statement_code",
+          "arguments": "p_company_id uuid, p_kind text, p_at date",
+          "anon": [],
+          "authenticated": [
+            "execute"
+          ],
+          "service_role": [
+            "execute"
+          ]
+        },
         {
           "name": "disable_module",
           "arguments": "p_company_id uuid, p_code text",
@@ -7441,6 +7493,19 @@
             "execute"
           ]
         },
+        {
+          "name": "ekwo_pre_request",
+          "arguments": "",
+          "anon": [
+            "execute"
+          ],
+          "authenticated": [
+            "execute"
+          ],
+          "service_role": [
+            "execute"
+          ]
+        },
         {
           "name": "ekwo_schema_version",
           "arguments": "",
@@ -7684,6 +7749,17 @@
             "execute"
           ]
         },
+        {
+          "name": "financial_statement_of_kind",
+          "arguments": "p_company_id uuid, p_kind text, p_from date, p_to date",
+          "anon": [],
+          "authenticated": [
+            "execute"
+          ],
+          "service_role": [
+            "execute"
+          ]
+        },
         {
           "name": "fiscal_year_at",
           "arguments": "p_company_id uuid, p_date date",
@@ -7834,6 +7910,19 @@
             "execute"
           ]
         },
+        {
+          "name": "installed_schema_version",
+          "arguments": "",
+          "anon": [
+            "execute"
+          ],
+          "authenticated": [
+            "execute"
+          ],
+          "service_role": [
+            "execute"
+          ]
+        },
         {
           "name": "instance_has_no_admin",
           "arguments": "",
@@ -7932,6 +8021,19 @@
             "execute"
           ]
         },
+        {
+          "name": "is_known_caller",
+          "arguments": "",
+          "anon": [
+            "execute"
+          ],
+          "authenticated": [
+            "execute"
+          ],
+          "service_role": [
+            "execute"
+          ]
+        },
         {
           "name": "label_for",
           "arguments": "p_name text, p_i18n jsonb, p_languages text[]",
@@ -8294,6 +8396,19 @@
             "execute"
           ]
         },
+        {
+          "name": "present_api_key",
+          "arguments": "p_secret text",
+          "anon": [
+            "execute"
+          ],
+          "authenticated": [
+            "execute"
+          ],
+          "service_role": [
+            "execute"
+          ]
+        },
         {
           "name": "purge_audit_log",
           "arguments": "p_before date",

package/dist/assets/migrations/20260922115309_an_installation_without_a_country.sql

@@ -0,0 +1,24 @@
+-- Ekwo OS — an installation is not in a country; its companies are.
+--
+-- `instance.country` was `not null` because the installation used to be set up
+-- *for* one country: `ekwo init` created the first company in the same run and
+-- wrote its country on the instance row. It never meant more than that. The
+-- seeds of every pack are loaded whatever it says, `create_company()` takes a
+-- country per company, and nothing in the schema reads the column — a firm
+-- keeping the books of companies in two countries has had one installation
+-- for both since the first release.
+--
+-- `ekwo init --no-company` installs the schema, the packs and the first
+-- administrator and creates no company, so there is no country to write down,
+-- and inventing one would be a default nobody chose. The column becomes
+-- nullable. The format check stays: a country, when there is one, is still two
+-- capital letters, and a null passes a check by definition.
+--
+-- `init_instance()` is unchanged: `upper(null)` is null, and the row now takes
+-- it. An installation set up with a company keeps the country of that company,
+-- as before.
+
+alter table instance alter column country drop not null;
+
+comment on column instance.country is
+  'The country of the first company, when `ekwo init` created one with the installation. Null for an installation set up without a company. Informative: every company carries its own country, and nothing reads this one to decide anything.';