IF Commons GitHub

project cli

0051Active

0051-project-cli · owner if · domain data

Requirements

FR-001checkpassing

sql MUST write the DDL of the models for a dialect, with the triggers of the invariants unless left out.

Enforced (check): .github: cd commons/data && bun run verify — suite/arcactl-project.test.ts: sql writes the DDL of the models for a dialect, which PostgreSQL, SQLite and DuckDB each run, with the triggers of the invariants unless they are left out, and for a module of a project's own

Proved by: data/suite/arcactl-project.test.ts

Written in: data/sql/cli/project.ts

Tests: passed: suite/arcactl-project.test.ts sql writes the DDL of the models for a dialect, which PostgreSQL, SQLite and DuckDB each r

FR-002checkpassing

It MUST work for a module of a project's own.

Enforced (check): .github: cd commons/data && bun run verify — suite/arcactl-project.test.ts: sql writes the DDL of the models for a dialect, which PostgreSQL, SQLite and DuckDB each run, with the triggers of the invariants unless they are left out, and for a module of a project's own

Proved by: data/suite/arcactl-project.test.ts

Written in: data/sql/cli/project.ts

Tests: passed: suite/arcactl-project.test.ts sql writes the DDL of the models for a dialect, which PostgreSQL, SQLite and DuckDB each r

FR-003checkpassing

lint MUST hold models and operations to governance's rules: errors fail, warnings fail only when strict.

Enforced (check): .github: cd commons/data && bun run verify — suite/arcactl-project.test.ts: lint holds the models and the operations to governance's rules: errors fail it, warnings do not unless it is strict, and a module of a project's own is held to them too

Proved by: data/suite/arcactl-project.test.ts

Written in: data/sql/cli/project.ts

Tests: passed: suite/arcactl-project.test.ts lint holds the models and the operations to governance's rules: errors fail it, warnings d

FR-004checkpassing

generate MUST write what a generator makes and list MUST say what there is. A generator MUST be named by its id or by the short name the usage gives (the id without sql.generate.; mermaid and d2 for erd-mermaid and erd-d2).

Enforced (check): .github: cd commons/data && bun run verify — suite/arcactl-access.test.ts: a generator is named by its id or by the short name the usage gives, for a module of the project's own; suite/arcactl-project.test.ts: generate writes what a generator makes for the models, names the generators where it is not given one, and list says what there is

Proved by: data/suite/arcactl-access.test.ts, data/suite/arcactl-project.test.ts

Written in: data/sql/cli/project.ts

Tests: passed: suite/arcactl-access.test.ts a generator is named by its id or by the short name the usage gives, for a module of the p; passed: suite/arcactl-project.test.ts generate writes what a generator makes for the models, names the generators where it is no

FR-005checkpassing

A command that is wrong MUST be refused with exit code 2 before anything is made.

Enforced (check): .github: cd commons/data && bun run verify — suite/arcactl-project.test.ts: a command that is wrong is refused with exit code 2 before anything is made: no project, both kinds of project, a model that is not one, a dialect that is not one, a module that is not a project, a thing to list that is not one

Proved by: data/suite/arcactl-project.test.ts

Written in: data/sql/cli/project.ts

Tests: passed: suite/arcactl-project.test.ts a command that is wrong is refused with exit code 2 before anything is made: no project, b

FR-006checkpassing

sql MUST write row security where its flags ask for it, for PostgreSQL only: --access (the grants of security.access and the policies of security.scope), --protect ROLE (the protected layer of 0014-sql-protected-access: the tables in --schema, a view of each in api, owned by that role), --seal (the scope is sealed; its key is ARCA_SEAL_KEY, at least 16 characters, and its unlock secret ARCA_UNLOCK_SECRET, from the environment or the files <NAME>_FILE name, never an argument), --reach exact|set, --wildcard (with --reach set) and --prefix; --protect and --seal imply --access. It MUST refuse, with exit code 2, a seal with no key or a short one, --reach, --wildcard or --prefix without access, --wildcard without --reach set, a role that is not a lower-case name, and a dialect other than PostgreSQL; without these flags it writes what it always wrote. The statements of a seal hold the key, which the database must hold, so they are for a pipe into psql and not for a file.

Enforced (check): .github: cd commons/data && bun run verify — suite/arcactl-access.test.ts: sql writes the grants and policies, the protected layer, the reach and the seal that its flags ask for, and refuses a seal with no key, a key given as an argument, a reach with no access, and a dialect that has no row security

Proved by: data/suite/arcactl-access.test.ts

Written in: data/sql/cli/project.ts

Tests: passed: suite/arcactl-access.test.ts sql writes the grants and policies, the protected layer, the reach and the seal that its f

Out of scope

  • A command for a model that is not of the arca family.

Edge cases

  • A dialect without the feature, an empty list, or a name that needs quoting: each is an error value or is quoted, never a silent omission, per FR-001.

Assumptions

  • The engines of the tests are SQLite, DuckDB and PGlite (PostgreSQL), in process.

Open questions

  • None.

Key entities

  • Command - sql, lint, generate or list of arcactl, run on the models of a project.

Success criteria

SC-001success criterion

Each requirement above is proved by a test that runs on real engines, and bun run verify is green.

Review & acceptance checklist

  • [x] Every requirement is testable (MUST / MUST NOT), not aspirational
  • [x] No company fact is asserted here
  • [x] Every open item is marked, not silently decided

Titles, headings, exports, tables, columns and requirements. Esc closes.