Skip to content

πŸ“ docs: specify typed Unix CLI platform contracts - #24

Draft
zrr1999 wants to merge 17 commits into
mainfrom
codex/mltt-platform-spec
Draft

zrr1999 wants to merge 17 commits into
mainfrom
codex/mltt-platform-spec

Conversation

@zrr1999

@zrr1999 zrr1999 commented Nov 14, 2026 •

Copy link
Copy Markdown
Member

Summary

  • Specify the Unix MLTT CLI platform: complete argv input, declaration-ordered command routing, typed parameter binding, help, output, terminal prompts, and exit status. Each root, child, or reused subtree consumes its own name token without backtracking.
  • Define OptionalPositional[T] and OptionalNamed[T] with required Some aliases Positional[T] and Named[T]. Public impl declarations relate their branches and roots to Option[T], subject to ownership, coverage, completeness, and path coherence.
  • Keep paths in the standard library. The platform and application share os.Path from Spore Spec's spec/stdlib/os.sp; path parameters validate text and then use os.Path.from_text. The platform does not own a second path type.
  • Provide prompt(label, default) and TextInput in the platform. Only a submitted empty line selects the default; EOF, cancellation, missing terminals, and I/O failures remain explicit. The application owns menu meaning and retry policy.
  • Describe the companion bootstrap's init/run/status contracts: omitted directories use cwd directly, init/run still require their confirmations, and run performs one recoverable execution-verification cycle.

Validation

  • prek run --files spec/README.md spec/operations.sp spec/platform.sp and git diff --check passed.
  • The current local Spore Spec grammar accepted both platform files, the external os module, the companion system.sp, 88 comment examples, and the README Spore block. No grammar changes were needed.
  • Static boundary review checked unique path ownership, UTF-8 encoding, absence of platform-to-application type dependencies, cwd defaults, and prompt/default/EOF/error branches.
  • The companion reader snapshot was synchronized to the source bytes; its five source-reading tests passed. These external checks do not establish runtime behavior.

Notes

This is a specification PR. Five primitive holes and five integration obligations remain pending, including generated bindings, module/ABI assembly, type/effect checks, and real process behavior. Syntax recognition does not establish execution or semantic verification of subtype relations.

Standard os is independent of this platform and the application. Its byte-based Path, Directory.open, and I/O result contract are maintained outside this PR in Spore Spec. The reviewed local os source SHA-256 is 8890ff6b352d49ac6ee70b12177ca31140958da61e612f6877c18d78d3c9b036; this is not a released standard-library provider, and package/import assembly remains pending.

The CLI entry remains List[Str] and currently rejects non-UTF-8 Unix argv without replacement. This restriction does not constrain os.Path or filesystem results to Unicode. Named options require a separate value token; -- escapes subsequent positional values. Short options, valueless flags, --name=value, parameter defaults, and nested role/Option shapes remain outside this slice.

The companion local bootstrap specification is outside this PR and is pinned to 701faff68222fbac0a45ce1a5fd04f60bb2a7402. Its handlers receive OptionalPositional[os.Path], choose os.Path.current when omitted, call standard os.Directory.open, and map library errors into application Problem values. Existing runtime, host, manifest, and CI configuration are unchanged.

@zrr1999 zrr1999 changed the title πŸ“ docs: specify minimal MLTT CLI platform πŸ“ docs: specify MLTT CLI platform and command trees Nov 14, 2026
@zrr1999 zrr1999 changed the title πŸ“ docs: specify MLTT CLI platform and command trees πŸ“ docs: specify MLTT CLI platform and unified commands Nov 14, 2026
@zrr1999 zrr1999 changed the title πŸ“ docs: specify MLTT CLI platform and unified commands πŸ“ docs: specify Command.run and optional CLI paths Nov 15, 2026
@zrr1999 zrr1999 changed the title πŸ“ docs: specify Command.run and optional CLI paths πŸ“ docs: specify typed CLI parameters and command dispatch Nov 15, 2026
@zrr1999 zrr1999 changed the title πŸ“ docs: specify typed CLI parameters and command dispatch πŸ“ docs: specify typed Unix CLI platform contracts Nov 15, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant