IF Commons GitHub

Repoctl surfaces

0006Active

0006-repoctl-surfaces · owner if · domain commons

Requirements

FR-001checkpassing

Every verb MUST be declared once as a Headless command with its options, operands and at least one example, its summary and the traits of its action coming from the table of Governance, and the model of the program MUST have no problem under Headless' conformance (every action has a reach policy, the words of no two verbs clash).

Enforced (check): .github: cd commons/repoctl && bun run verify — suite/surfaces.test.ts: every verb has examples and the model has no problem

Proved by: repoctl/suite/surfaces.test.ts

Written in: repoctl/src/physical/define.ts, repoctl/src/physical/program.ts

Tests: passed: suite/surfaces.test.ts every verb has examples and its facts from the table, and the model of the program has no

Cited by: Repoctl, physical/define, physical/program

FR-002checkpassing

The program MUST be described by Headless' describe (the layered model of its actions, verbs, options, operands, problem codes, command-line commands, tools of the tool server and routes of the REST projection), so that the documentation lists every verb per tier with its examples and every problem code with its explanation.

Enforced (check): .github: cd commons/repoctl && bun run verify — suite/surfaces.test.ts: describe gives the elements of every verb, code and tool

Proved by: repoctl/suite/surfaces.test.ts

Tests: passed: suite/surfaces.test.ts the program is described: its verbs, options, tools and codes are elements of the model

FR-003checkpassing

repoctl mcp MUST serve, as the tools of a tool server on standard input and output, the verbs that the held tier sees, that come through the mcp channel and that are not for a person alone, each with the schema of its options and operands; a tool that the held tier does not see MUST be refused with the reason, and a destruction MUST be served only as a preview, never confirmed by the caller.

Enforced (check): .github: cd commons/repoctl && bun run verify — suite/surfaces.test.ts: the tools of each tier are the verbs of that tier, a hidden tool is refused with its reason and a destruction is only a preview

Proved by: repoctl/suite/surfaces.test.ts

Tests: passed: suite/surfaces.test.ts a tool the tier does not see is refused with the reason, a destruction is only a preview, ; passed: suite/surfaces.test.ts the tools a tier sees are the verbs of that tier and below that come through the tool serv; passed: suite/surfaces.test.ts a real tool server on standard input and output serves the tools of the held tier and answ

FR-004checkpassing

The reach policy of each action MUST be: the verbs that only read are read-only and safe to repeat; sync is safe to repeat and can preview and check; release publish is a destruction that previews and is confirmed by a person, and the option that types its confirmation MUST be one that only a person may give, so that no tool of the tool server can give it.

Enforced (check): .github: cd commons/repoctl && bun run verify — suite/surfaces.test.ts: the reach of each action, and the confirmation is for a person alone

Proved by: repoctl/suite/surfaces.test.ts

Tests: passed: suite/surfaces.test.ts a tool the tier does not see is refused with the reason, a destruction is only a preview, ; passed: suite/surfaces.test.ts the reach of each action: reports are read-only and safe to repeat, sync previews and chec

Cited by: Repoctl, physical/define

FR-005checkpassing

The tier the program holds MUST be a fact of the host: the variable the configuration names (REPOCTL_TIER by default; 0009-repoctl-config FR-006) (public, contributor or releaser), contributor where it says nothing; a word that is no tier MUST end the run with the status 2; and a caller of a lower tier MUST NOT see, be offered or run a verb of a higher one.

Enforced (check): .github: cd commons/repoctl && bun run verify — suite/surfaces.test.ts: the tier is the host's, an unknown word ends with 2 and a verb of a higher tier is not there

Proved by: repoctl/suite/surfaces.test.ts

Tests: passed: suite/surfaces.test.ts the tools a tier sees are the verbs of that tier and below that come through the tool serv; passed: suite/surfaces.test.ts the tier is the host's: an unknown word ends with 2, and a verb of a higher tier is not th

Cited by: Repoctl, physical/program

FR-006checkpassing

The root package.json MUST have the script repoctl (which links the libraries, then runs the program) and the bin repoctl, the package MUST have the launcher bin/repoctl.mjs that runs the program on Bun and on Node 26, and the package MUST be packed with the command as one bundled file.

Enforced (check): .github: cd commons/repoctl && bun run verify — suite/surfaces.test.ts: the root package has the script and the bin, and the launcher is there

Proved by: repoctl/suite/surfaces.test.ts

Written in: repoctl/bin/main.ts, repoctl/src/repoctl.ts, repoctl/tools/pack.ts

Tests: passed: suite/surfaces.test.ts the root package has the script and the bin, and the launcher and the bundle's entry are t

Acceptance scenarios

  1. Given the program, When the model's conformance is checked, Then there is no problem, per FR-001.
  2. Given the program, When it is described, Then every verb, option, code and tool is an element of the model, per FR-002.
  3. Given the tier public, When the tools are listed, Then only the verbs that read are there, per FR-003.
  4. Given the tier releaser, When release_publish is called with no preview, Then it is refused as needing a confirmation, per FR-003 and FR-004.
  5. Given contributor, When repoctl release publish is typed, Then the verb is not there and the sentence says the tier it is for, per FR-005.
  6. Given REPOCTL_TIER=admin, When the program runs, Then it ends with 2, per FR-005.
  7. Given the root package, When it is read, Then the script and the bin are there, per FR-006.

Out of scope

  • The REST server: its projection is described, and a host serves it.
  • Remote targets: the program runs on the checkout it is in.

Edge cases

  • A tool server asked for a tool that does not exist: invalid params, per FR-003.
  • REPOCTL_READ_ONLY=1: the key may only read, so a verb that changes something is refused through the tool server, per FR-003.
  • --confirm given through a tool: refused as for a person alone, per FR-004.

Assumptions

  • The libraries of commons that Repoctl calls (libraries, the tools of commons) are on the branch that holds it, and git, bun and node are installed.

Open questions

  • None.

Key entities

  • Tool - a verb as a tool of the tool server.
  • Held tier - the tier a host fixes for a caller.

Success criteria

SC-001success criterion

The tools a tier sees are exactly the verbs of that tier and below.

SC-002success criterion

No tool can publish.

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

Repoctl, physical/define, physical/mod, physical/program, repoctl

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