IF Commons GitHub

Package managers: dialect

0004Active

0004-package-managers-dialect · owner if · domain commons

Requirements

FR-001checkpassing

The dialect MUST declare its guarantees as data: the kind tool, subjects of the classes machine and workstation, a plan that is partial where a check can be made and none where it cannot, idempotence unproven until a suite has run the real manager, and that it cannot destroy; and as a dialect of tools the guarantees and the manager of the data it was made from.

Enforced (check): .github: cd commons/package-managers && bun run verify — suite/dialect.test.ts

Proved by: package-managers/suite/dialect.test.ts

Written in: package-managers/src/physical/dialect.ts

Tests: passed: suite/dialect.test.ts the guarantees are data: the kind tool, a partial plan where a check can be made and none

FR-002checkpassing

render MUST give the plan file of the tools that change something, as generated output, with the commands in it, and MUST refuse with every reason where a command cannot be made; a requirement of another dialect or another manager MUST NOT be in it.

Enforced (check): .github: cd commons/package-managers && bun run verify — suite/dialect.test.ts

Proved by: package-managers/suite/dialect.test.ts

Written in: package-managers/src/physical/dialect.ts

Tests: passed: suite/dialect.test.ts the plan file is rendered with only this dialect's tools, says it is generated, and every

FR-003checkpassing

steps MUST give one step that applies and checks the tools that change through the program of the kit, each naming the digest of what was rendered in the path .archon/<digest>/<dialect>/plan.json, with the status 2 as the status that means something would change; the tools it covers MUST be those of the plan file that change, and a plan that changes nothing, or has none of this dialect's tools, MUST have no step.

Enforced (check): .github: cd commons/package-managers && bun run verify — suite/dialect.test.ts

Proved by: package-managers/suite/dialect.test.ts

Written in: package-managers/src/physical/bin.ts, package-managers/src/physical/dialect.ts

Tests: passed: suite/dialect.test.ts one step runs the program of the kit on the plan file that names the digest, and a plan th

FR-004checkpassing

The runner MUST give a program a limit of time and answer with its exit status and what it printed, or with nothing where it could not be run or did not answer in time, and MUST answer at the limit even where the program has started others that keep its output open.

Enforced (check): .github: cd commons/package-managers && bun run verify — suite/dialect.test.ts

Proved by: package-managers/suite/dialect.test.ts

Written in: package-managers/src/physical/runner.ts

Tests: passed: suite/dialect.test.ts the runner answers with the status and the output, and with nothing for a program that is

FR-005checkpassing

observeRequirements MUST give Archon the desired state itself for a tool installed at the version asked (or any version where none is asked), a state with the version found and installedFrom manager for a tool at another version, and nothing for a tool that is absent, cannot be asked, or whose answer holds no version.

Enforced (check): .github: cd commons/package-managers && bun run verify — suite/dialect.test.ts

Proved by: package-managers/suite/dialect.test.ts

Written in: package-managers/src/physical/dialect.ts

Tests: passed: suite/dialect.test.ts Archon is given the desired state for a tool at the version asked, a differing state for a

FR-006checkpassing

The program that raises the rights MUST come from the options of the dialect and be put before only the commands of a manager that needs rights; where none is given none is put.

Enforced (check): .github: cd commons/package-managers && bun run verify — suite/dialect.test.ts

Proved by: package-managers/suite/dialect.test.ts

Tests: passed: suite/dialect.test.ts the program that raises the rights comes from the options and is put before only the comma

FR-007checkpassing

The program MUST run only the commands of the plan file it is given and refuse a file that is not one; check MUST change nothing and end with 2 where a package is missing or cannot be asked; apply MUST install what is missing and, where the manager can be asked, MUST leave an installed package alone, so that a second apply changes nothing; and a failure MUST name the tool, the step, what it saw and the one action that is next.

Enforced (check): .github: cd commons/package-managers && bun run verify — suite/dialect.test.ts

Proved by: package-managers/suite/dialect.test.ts

Written in: package-managers/src/physical/bin.ts

Tests: passed: suite/dialect.test.ts the program runs only a plan file's commands: check changes nothing and ends with 2, apply

FR-008checkpassing

commandsFromOntology MUST give a source of commands that reads the packaging ontology only through its reader of commands, names the manager as Toolchain does (manager-apt for apt), gives each command with its words joined by single spaces and its environment, rights, non-interactive form and whether it was tried, and gives the ontology's own reason where it states no command; it MUST hold no template of its own.

Enforced (check): .github: cd commons/package-managers && bun run verify — suite/ontology.test.ts

Proved by: package-managers/suite/ontology.test.ts

Written in: package-managers/src/physical/ontology.ts

Tests: passed: suite/ontology.test.ts the commands are the ontology's, a command it does not state is its reason, and the vector

Acceptance scenarios

  1. Given the data of a manager with a known missing status, When the guarantees are read, Then the plan is partial; with no known status it is none, per FR-001.
  2. Given an order with a tool of this manager, a tool of another dialect and a tool by download, When it is rendered, Then only the first is in the plan file, per FR-002.
  3. Given a plan, When the steps are made, Then one step runs the program on the plan file that names the digest, per FR-003.
  4. Given a program that hangs and a program that starts another that keeps its output, When each is run with a limit, Then the answer is nothing at the limit, per FR-004.
  5. Given a manager that says a package is at the version asked, at another version, and not installed, When the requirements are observed, Then the answers are as FR-005 says.
  6. Given a program that raises the rights in the options, When the steps are made for a manager that needs rights and for one that does not, Then it is in front of the first only, per FR-006.
  1. Given a plan file, When check runs with a package missing, installed and unaskable, Then it changes nothing and ends with 2; When apply runs twice, Then the second changes nothing, per FR-007.
  2. Given an install that fails and a check that answers with another status, When the program runs, Then each failure names the tool, the step and the next action, per FR-007.
  1. Given the ontology, When the commands of apt, Homebrew, WinGet and mise are asked, Then each is the ontology's, and a command it does not state is its reason, per FR-008.

Out of scope

  • Proving idempotence on a real manager: the conformance suite of each dialect on a machine that has it.

Edge cases

  • A manager whose check is not known is installed again by apply (managers install what is there as a no-op), and check says it would install, per FR-007.

Assumptions

  • The manager's own command is what installs, and the manager's own verification (signatures of a repository, the hash of a bottle) is what it guarantees; the dialect states it as data and never claims more.

Open questions

  • None.

Key entities

  • Manager spec - the data a dialect is made from.
  • Dialect - the value of the port.

Success criteria

SC-001success criterion

A dialect of a manager is its data and a call.

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

Cited by

apt dialect, Homebrew dialect, mise dialect, WinGet dialect

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