ekwo-os 0.5.0 → 0.7.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. |
@@ -271,6 +323,7 @@ instead if the account already exists, and no key is needed.
 | `ekwo reverse <entry>` | Undoes a posted entry keyed by hand, through `reverse_entry()`: its mirror, posted and matched against it. By id or by number; `--date` as for `cancel`. |
 | `ekwo payment record` | Money in or out, booked and matched. With `--doc`, against that document. |
 | `ekwo match <transaction> <document>` | A bank statement line pays a document, through `settle_from_statement()`. |
+| `ekwo import <source> <file>…` | Books kept elsewhere — `trial-balance`, `fec`, `journal-items`, `journal-report` — whole or not at all, through `import_books()`, with a correspondence of accounts and journals you save and give back; or a bank statement — `camt.053`, `coda`, `cfonb120` — as pending lines. `--dry-run` rehearses. See [taking over books](#taking-over-books-ekwo-import). |
 | `ekwo doc list` / `show` | What exists, and with `--unpaid` what is posted and still owed. See [keeping books](#keeping-books). |
 
 There is no `eject`, because there is nothing to eject from. The schema is in
@@ -506,6 +559,111 @@ Two values are supplied when nobody gives them, and said when they are:
 `--type` is `sale_invoice`, and `--date` is today on the machine running the
 command. Whether that date may be booked on is the database's decision.
 
+## Taking over books: `ekwo import`
+
+To try Ekwo on your own books, bring them. One command, one reader per
+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 — 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
+ekwo import journal-report report.csv chart.csv --date-order dmy --dry-run --save-mapping map.json
+ekwo import camt.053 statement.xml                 # or coda, cfonb120: pending lines for `ekwo match`
+```
+
+| Source | What it reads |
+|---|---|
+| `trial-balance` | A trial balance as CSV — `account`, `debit`, `credit`, or one signed `balance` — which becomes the opening entry of the year `--opening-date` starts |
+| `fec` | A *fichier des écritures comptables*: the eighteen columns of the arrêté of 29 July 2013, tab or bar separated |
+| `journal-items` | The lines of every entry exported as CSV from the list view of an ERP whose ledger is a table of lines, with the chart of accounts and the partners exported beside it |
+| `journal-report` | A journal report or a general ledger detail, saved as CSV from a cloud service's spreadsheet export, with its Journal ID and Account Code columns, and the chart and the contacts beside it |
+| `camt.053`, `coda`, `cfonb120` | A bank statement: its lines, pending, ready for `ekwo match` |
+
+Each reader is a brick of [`packages/formats/`](../formats/README.md), named
+after the file; its README says which columns it reads and which official
+pages the format was read from. The exports of other ledgers can also be named
+by the software they come from: `ekwo import --help` lists those names, and
+[`docs/compatibility.md`](../../docs/compatibility.md) gives each one's export,
+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 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": 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 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
+the source gives no journal.
+
+**Whole or not at all.** `import_books()` is one call and one transaction: the
+fiscal years it needs (with `--open-years`, as years of the same length and
+first day as the company's own; without, an entry outside every year is
+refused by name), the parties the lines name — found by their code or their
+name, or created as customers or suppliers according to where their lines are
+booked — every entry as a draft then posted by `post_entry()`, and the opening
+through `opening_balance()`. One refusal — a locked period, an account the
+chart does not have, a capability you do not hold — and nothing stays, not
+even the years or the parties.
+
+**`--dry-run` is the real thing, taken back.** The database runs the whole
+import and rolls it back, so the numbers shown are the ones the entries would
+take now and a refusal is the one the import would give. For a bank statement a
+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 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
+  is kept as the entry's reference. `--keep-numbers` posts each under its old
+  number instead, where the country allows a number chosen by hand or you hold
+  `entries.import`.
+- **No tax.** An imported line carries an account and an amount, not the tax
+  that produced it: the history feeds the ledger, the trial balance and the
+  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, 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
+  imported receivable against its payment is done in Ekwo, with `reconcile`.
+
+The MCP server offers the same as `import_books`, and `import_bank_statement`
+for a statement. [`docs/import.md`](../../docs/import.md) is the long form.
+
 ## `ekwo module`
 
 A module is a Postgres schema beside the socle — `assets` for fixed assets,
@@ -536,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
@@ -715,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
@@ -750,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.5.0",
-  "migration": "20260922072635",
+  "schemaVersion": "0.7.0",
+  "migration": "20260922124012",
   "socle": {
     "schema": "public",
     "tables": [
@@ -599,6 +599,59 @@
           }
         ]
       },
+      {
+        "name": "book_imports",
+        "columns": [
+          {
+            "name": "checksum",
+            "type": "text"
+          },
+          {
+            "name": "company_id",
+            "type": "uuid"
+          },
+          {
+            "name": "created_at",
+            "type": "timestamp with time zone"
+          },
+          {
+            "name": "created_by",
+            "type": "uuid"
+          },
+          {
+            "name": "entry_count",
+            "type": "integer"
+          },
+          {
+            "name": "file_names",
+            "type": "text[]"
+          },
+          {
+            "name": "first_number",
+            "type": "text"
+          },
+          {
+            "name": "id",
+            "type": "uuid"
+          },
+          {
+            "name": "last_number",
+            "type": "text"
+          },
+          {
+            "name": "line_count",
+            "type": "integer"
+          },
+          {
+            "name": "opening_number",
+            "type": "text"
+          },
+          {
+            "name": "source",
+            "type": "text"
+          }
+        ]
+      },
       {
         "name": "capabilities",
         "columns": [
@@ -4078,10 +4131,18 @@
         "name": "import_bank_statement",
         "arguments": "p_company_id uuid, p_file jsonb, p_source jsonb, p_bank_account_id uuid"
       },
+      {
+        "name": "import_books",
+        "arguments": "p_company_id uuid, p_books jsonb, p_dry_run boolean, p_open_years boolean, p_allow_result_accounts boolean"
+      },
       {
         "name": "import_company",
         "arguments": "p_archive jsonb, p_owner_user_id uuid"
       },
+      {
+        "name": "import_fiscal_year_for",
+        "arguments": "p_company_id uuid, p_date date"
+      },
       {
         "name": "init_instance",
         "arguments": "p_organization_name text, p_country character, p_edition instance_edition"
@@ -4569,6 +4630,16 @@
         "name": "bank_transactions_write",
         "command": "all"
       },
+      {
+        "table": "book_imports",
+        "name": "book_imports_insert",
+        "command": "insert"
+      },
+      {
+        "table": "book_imports",
+        "name": "book_imports_select",
+        "command": "select"
+      },
       {
         "table": "capabilities",
         "name": "capabilities_select",
@@ -5959,6 +6030,18 @@
             "update"
           ]
         },
+        {
+          "name": "book_imports",
+          "anon": [],
+          "authenticated": [
+            "insert",
+            "select"
+          ],
+          "service_role": [
+            "insert",
+            "select"
+          ]
+        },
         {
           "name": "capabilities",
           "anon": [],
@@ -7696,6 +7779,17 @@
             "execute"
           ]
         },
+        {
+          "name": "import_books",
+          "arguments": "p_company_id uuid, p_books jsonb, p_dry_run boolean, p_open_years boolean, p_allow_result_accounts boolean",
+          "anon": [],
+          "authenticated": [
+            "execute"
+          ],
+          "service_role": [
+            "execute"
+          ]
+        },
         {
           "name": "import_company",
           "arguments": "p_archive jsonb, p_owner_user_id uuid",
@@ -7707,6 +7801,17 @@
             "execute"
           ]
         },
+        {
+          "name": "import_fiscal_year_for",
+          "arguments": "p_company_id uuid, p_date date",
+          "anon": [],
+          "authenticated": [
+            "execute"
+          ],
+          "service_role": [
+            "execute"
+          ]
+        },
         {
           "name": "init_instance",
           "arguments": "p_organization_name text, p_country character, p_edition instance_edition",