IF Commons GitHub

AnyfsCli surfaces

0004Active

0004-anyfs-cli-surfaces · owner if · domain commons

Requirements

FR-001checkpassing

The program MUST open a store in memory (one for each name for a run), a store of a folder, and a store on a host reached by SSH, and MUST give a place of any other kind the ending E-PLACE-UNAVAILABLE where no opener for it is in the configuration.

Enforced (check): .github: cd commons/anyfs-cli && bun run verify — suite/program.test.ts

Proved by: anyfs-cli/suite/program.test.ts

Written in: anyfs-cli/src/physical/openers.ts

Tests: passed: suite/program.test.ts a host reached by SSH is a store through the safe executor, and a host that does not answe; passed: suite/program.test.ts a store in memory is one for each name, a folder opens, and a kind with no opener is unava

Cited by: AnyFS command line, physical/openers

FR-002checkpassing

The openers of the configuration MUST take the place of the program's own for their kind and add the kinds it lacks, so that anyfs-git, anyfs-sql and a bucket plug in through the configuration alone; and the store on a host MUST speak only through the safe executor of Headless, whose first contact with a host is the verb trust-host.

Enforced (check): .github: cd commons/anyfs-cli && bun run verify — suite/program.test.ts

Proved by: anyfs-cli/suite/program.test.ts

Written in: anyfs-cli/src/physical/openers.ts

Tests: passed: suite/program.test.ts a host reached by SSH is a store through the safe executor, and a host that does not answe; passed: suite/program.test.ts an opener in the configuration brings a kind the program lacks, with no change to the prog

Cited by: AnyFS command line, physical/openers

FR-003checkpassing

The world of the process MUST open each place once for a run, resolve a plain path to the root of its store and the path inside it, read standard input and write standard output as bytes, and keep the state of the program in its own folder.

Enforced (check): .github: cd commons/anyfs-cli && bun run verify — suite/program.test.ts

Proved by: anyfs-cli/suite/program.test.ts

Written in: anyfs-cli/src/physical/os.ts, anyfs-cli/src/physical/world.ts

Tests: passed: suite/program.test.ts the world opens each place once for a run, resolves a plain path to its root, and keeps st

Cited by: AnyFS command line, physical/os, physical/world

FR-004checkpassing

The configuration MUST be found by --config FILE, else the first anyfs.config.ts from the working folder up to the root of the checkout, else the user's; its absence MUST NOT be a problem, and its failure to load or its invalidity MUST be a typed problem with its code.

Enforced (check): .github: cd commons/anyfs-cli && bun run verify — suite/program.test.ts

Proved by: anyfs-cli/suite/program.test.ts

Written in: anyfs-cli/src/physical/config-load.ts

Tests: passed: suite/program.test.ts the configuration is found from the working folder up, its absence is no problem, and a fi

Cited by: AnyFS command line, physical/config-load

FR-005checkpassing

A word MUST be bound to the store it points into by parsing it as a location, opening the store of its place, attenuating the store of a read-only mount so that nothing can change it, and making the POSIX view of the store with the path inside it resolved; a word that is no place MUST end the verb with a usage error and a store that cannot be opened with an environment error.

Enforced (check): .github: cd commons/anyfs-cli && bun run verify — suite/read.test.ts

Proved by: anyfs-cli/suite/read.test.ts

Written in: anyfs-cli/src/physical/bind.ts

Tests: passed: suite/read.test.ts a word that is no place is a usage error, a store that cannot be opened is a problem of th

Cited by: AnyFS command line, physical/bind

FR-006checkpassing

Every verb MUST be declared once, with its words, options, operands and examples, and its action traits MUST come from the table VERBS; two options of a verb MUST NOT share a short letter, and the model of the program MUST pass the conformance rules of Headless.

Enforced (check): .github: cd commons/anyfs-cli && bun run verify — suite/program.test.ts

Proved by: anyfs-cli/suite/program.test.ts

Written in: anyfs-cli/src/physical/verbs/common.ts

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

Cited by: AnyFS command line, physical/verbs/common

FR-007checkpassing

Every verb that works through the POSIX view MUST take --explain, which says how each operation it uses would be carried out on each store it names (native, emulated with a risk, or refused) and does nothing else, and --strict, which ends the verb with E-STRICT where an operation was emulated by a means that can lose or change what was meant.

Enforced (check): .github: cd commons/anyfs-cli && bun run verify — suite/read.test.ts

Proved by: anyfs-cli/suite/read.test.ts

Written in: anyfs-cli/src/physical/verbs/common.ts

Tests: passed: suite/read.test.ts --explain says how the store carries an operation out and does nothing, and --strict stops

Cited by: AnyFS command line, physical/verbs/common

FR-008checkpassing

ls, cat, stat, head, tail, find, du, tree, grep, diff and sha256sum MUST only read; cat, head and tail MUST write the bytes of a file as they are, to the port of standard output, and write none where the output is the one JSON document; a name that is not there MUST end a verb with E-FILESYSTEM and the exit findings.

Enforced (check): .github: cd commons/anyfs-cli && bun run verify — suite/read.test.ts

Proved by: anyfs-cli/suite/read.test.ts

Written in: anyfs-cli/src/physical/verbs/read.ts

Tests: passed: suite/read.test.ts cat writes the bytes of a file as they are, and none where the output is the one JSON docu; passed: suite/read.test.ts grep looks for a literal text within limits, and diff says how two files differ with the e; passed: suite/read.test.ts ls, tree, find, du, stat, head, tail and sha256sum say what is in a store

Cited by: AnyFS command line, physical/verbs/read

FR-009checkpassing

The tool server MUST serve the verbs the held tier sees, ANYFS_TIER=reader MUST show only the verbs that read, and a destructive verb from the tool server MUST be a preview and never an apply, since the channel gives no confirmation.

Enforced (check): .github: cd commons/anyfs-cli && bun run verify — suite/program.test.ts

Proved by: anyfs-cli/suite/program.test.ts

Tests: passed: suite/program.test.ts the tools a tier sees are the verbs of that tier and below, and a destruction is marked as

FR-010checkpassing

A transfer MUST take its rails from the command line and the configuration (include and exclude globs, a maximum of files and bytes, a maximum object size, a refusal of a lossy plan), MUST plan a directory transfer through the bridge, MUST apply only the plan whose hash --plan-hash names, and MUST end with E-PLAN-STALE where the plan made now has another hash.

Enforced (check): .github: cd commons/anyfs-cli && bun run verify — suite/write.test.ts

Proved by: anyfs-cli/suite/write.test.ts

Written in: anyfs-cli/src/physical/verbs/transfer.ts

Tests: passed: suite/write.test.ts a plan that is applied is the plan whose hash was named: a store that changed in between m

FR-011checkpassing

put, mkdir, touch, cp, mv and rm MUST change a store through the view and MUST change nothing under --dry-run; a file copy MUST be one read and one write checked against the digest of the bytes read, a directory copy or a cross-store move MUST be a plan of the bridge, and rm -r MUST list the names it would remove with the hash of that list, which --plan-hash pins.

Enforced (check): .github: cd commons/anyfs-cli && bun run verify — suite/write.test.ts

Proved by: anyfs-cli/suite/write.test.ts

Written in: anyfs-cli/src/physical/verbs/write.ts

Tests: passed: suite/write.test.ts cp copies files by a checked read and write, into a directory, and a directory only with -; passed: suite/write.test.ts mv renames within a store, copies then removes across stores, and a destruction needs its ; passed: suite/write.test.ts put writes standard input or a local file, and --dry-run, mkdir and touch say what they wo; passed: suite/write.test.ts rm lists the names a recursive removal would take with the hash of that list, and removes

Cited by: AnyFS command line, physical/verbs/write

FR-012checkpassing

sync MUST plan first and print the plan with its hash, MUST allow deletes only up to --max-deletes, MUST apply only with --yes (which Headless asks of a destruction) and the plan hash where given, and check MUST change nothing and end with E-DIFFERENT where the two sides differ.

Enforced (check): .github: cd commons/anyfs-cli && bun run verify — suite/bridge.test.ts

Proved by: anyfs-cli/suite/bridge.test.ts

Written in: anyfs-cli/src/physical/verbs/bridge.ts

Tests: passed: suite/bridge.test.ts sync deletes only up to --max-deletes, and check changes nothing and ends with E-DIFFERENT; passed: suite/bridge.test.ts sync plans first with a hash, applies only with the confirmation and the hash, and a secon

Cited by: AnyFS command line, physical/verbs/bridge

FR-013checkpassing

bisync MUST need a recorded base, or --seed for the first run, MUST record the base it ends with in the state folder, and MUST leave a conflict for the person unless a rule settles it; mirror status, mirror sync and mirror promote MUST keep the ledger in the state folder, MUST never touch what the replica changed itself, and MUST refuse to promote a replica that is behind or diverged unless the loss or divergence is accepted.

Enforced (check): .github: cd commons/anyfs-cli && bun run verify — suite/bridge.test.ts

Proved by: anyfs-cli/suite/bridge.test.ts

Written in: anyfs-cli/src/physical/verbs/bridge.ts

Tests: passed: suite/bridge.test.ts a mirror keeps its ledger, never touches what the replica changed itself, and refuses to p; passed: suite/bridge.test.ts bisync needs a base or --seed, records the base, and leaves a conflict for the person unle

Cited by: AnyFS command line, physical/verbs/bridge

FR-014checkpassing

places MUST list the mounts with their places and what each kind of place is (built in, from the configuration, or no store yet), doctor MUST say what is wrong with the setup and the command for each, and both MUST run where there is no configuration.

Enforced (check): .github: cd commons/anyfs-cli && bun run verify — suite/program.test.ts

Proved by: anyfs-cli/suite/program.test.ts

Written in: anyfs-cli/src/physical/verbs/merge.ts, anyfs-cli/src/physical/verbs/setup.ts

Tests: passed: suite/program.test.ts places lists the mounts and the kinds of place where there is no configuration, and doctor

Cited by: AnyFS command line, physical/verbs/merge, physical/verbs/setup

FR-015checkpassing

The program MUST be one Headless tree made in one place from a host, MUST carry the version, the codes it explains and the tiers, and MUST be the same for the command line, the tool server and the description of the REST surface.

Enforced (check): .github: cd commons/anyfs-cli && bun run verify — suite/program.test.ts

Proved by: anyfs-cli/suite/program.test.ts

Written in: anyfs-cli/src/physical/program.ts, anyfs-cli/src/physical/verbs/merge.ts

Tests: passed: suite/program.test.ts the program is one tree with its version, its codes and its tiers, described the same for

Cited by: AnyFS command line, physical/program, physical/verbs/merge

FR-016checkpassing

main MUST run the program with the words after its name and give its exit status; --json MUST give the one envelope of Headless and nothing else on standard output; a variable ANYFS_TIER that is no tier MUST end with the usage status.

Enforced (check): .github: cd commons/anyfs-cli && bun run verify — suite/program.test.ts

Proved by: anyfs-cli/suite/program.test.ts

Written in: anyfs-cli/src/anyfs.ts

Tests: passed: suite/program.test.ts main gives the exit status, the one envelope of --json, and the usage status for a tier th

Cited by: anyfs, AnyFS command line

FR-017checkpassing

merge MUST bring two stores that both merge together, MUST plan first and print the plan with its hash, MUST apply only with --yes and the plan hash where given (a stale hash ends with E-PLAN-STALE), and MUST refuse a store that does not merge.

Enforced (check): .github: cd commons/anyfs-cli && bun run verify — suite/merge.test.ts

Proved by: anyfs-cli/suite/merge.test.ts

Tests: passed: suite/merge.test.ts merge plans first with a hash, refuses a stale hash, and a store that does not merge

FR-018checkpassing

sync-medium MUST exchange a store that merges with a shared place under the identity given by --replica, MUST keep its cursor in the state folder, MUST change nothing under --dry-run, and MUST end with E-FILES-ASIDE where delta files were refused.

Enforced (check): .github: cd commons/anyfs-cli && bun run verify — suite/merge.test.ts

Proved by: anyfs-cli/suite/merge.test.ts

Tests: passed: suite/merge.test.ts sync-medium needs a replica identity, plans under --dry-run and exchanges with the shared

Acceptance scenarios

  1. Given a place of the kind s3 and no opener, When it is opened, Then the ending is E-PLACE-UNAVAILABLE, per FR-001.
  2. Given an opener for the kind git in the configuration, When a git place is opened, Then the opener's store is the result, per FR-002.
  3. Given the same place opened twice, When the stores are compared, Then they are the same store, per FR-003.
  4. Given a folder with no configuration and one with a broken one, When the program runs in each, Then the first works on plain paths and the second ends with E-CONFIG-LOAD, per FR-004.
  5. Given a read-only mount, When a verb tries to remove a file in it, Then the ending is EROFS, per FR-005.
  6. Given the program, When its model is described, Then the conformance finds nothing, per FR-006.
  7. Given a mkdir in a store of objects, When --strict is given, Then the ending is E-STRICT, and with --explain nothing is made, per FR-007.
  8. Given a file of every byte value, When it is cat, Then the bytes written are the bytes of the file, per FR-008.
  9. Given the tier reader, When the tools are described, Then only the verbs that read are there, per FR-009.
  10. Given a plan hash that is not the plan's, When the transfer is applied, Then nothing is written and the ending is E-PLAN-STALE, per FR-010.
  11. Given a directory, When it is removed with its hash after the names changed, Then nothing is removed and the ending is E-PLAN-STALE, per FR-011.
  12. Given two directories that differ, When they are synced with --dry-run and then with --yes and the hash, Then the second makes them equal, per FR-012.
  13. Given a replica that changed on its own, When the mirror is synced, Then the changed path is left and the ending is E-REPLICA-DIVERGED, per FR-013.
  14. Given no configuration, When places runs, Then it says there are no mounts and lists the kinds, per FR-014.
  15. Given the program, When its model is described, Then it has the verbs and the three surfaces agree, per FR-015.
  16. Given --json, When ls runs, Then standard output is one JSON document, per FR-016.
  17. Given two stores that merge, When merge runs with --dry-run and then with a stale hash, Then the first prints a plan hash and the second ends with E-PLAN-STALE, per FR-017.
  18. Given a store that merges and a shared folder, When sync-medium runs, Then delta files appear under the folder, per FR-018.

Out of scope

  • The backends that plug in through the configuration: their own libraries.
  • A mount of the stores as a file system (a WebDAV or NFS server, or FUSE): their own libraries.

Edge cases

  • A destruction asked through the tool server: it is a preview and never an apply, per FR-009.
  • A store that changed between the plan and the apply: the ending is E-PLAN-STALE and nothing is written, per FR-010.
  • A host key not yet trusted: the store does not open and trust-host is the way, per FR-002.
  • A configuration file that does not load: the verbs that need no mount still run, per FR-004.

Assumptions

  • The libraries anyfs, anyfs-bridge, anyfs-posix, anyfs-ssh and Headless are on the branch that holds this library.

Open questions

  • None.

Key entities

  • AnyfsCli - the library.

Success criteria

SC-001success criterion

bun run verify in this folder passes.

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

anyfs, AnyFS command line, physical/bind, physical/config-load, physical/openers, physical/os, physical/program, physical/verbs/bridge, physical/verbs/common, physical/verbs/merge, physical/verbs/read, physical/verbs/setup, physical/verbs/write, physical/world

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