Skip to content

AI_CURATOR_RECIPE.md

Latest commit

 

History

History
163 lines (135 loc) · 7.71 KB

AI_CURATOR_RECIPE.md

File metadata and controls

163 lines (135 loc) · 7.71 KB
version 0.3
project odsview-cli-python
baseline_commit main
curated_by arturo

AI Curator Recipe (odsview-cli-python)

This file customizes the baseline Software Curatorship recipe for this repository. Sections not explicitly customized here inherit their meaning from docs/curation/AI_CURATOR_RECIPE_BASELINE_v0.3.md.

1) Intent & Scope

  • Keep runtime minimal; favor clarity and determinism.
  • All user-visible behavior is test-backed and explained via ADRs.
  • Provenance is transparent (README “Attribution & Curation”, ADR-0010, AUTHORS).
  • This project provides a read-only terminal viewer for .ods files aiming to work well over SSH and in constrained environments (e.g. Termux).

2) Product Contract (plain language)

Describe the externally visible behavior of the CLI. This section reflects the currently implemented behavior plus near-term intent from docs/curation/BLUEPRINT.md, ADR-0003, and ADR-0004.

Aspect Description
Inputs CLI invocation odsview [FILE] [options]; FILE is optional in the skeleton and required when using --list-sheets
Outputs/streams stdout → help/usage text; sheet names (one per line) when using --list-sheets; range-based table view output for odsview FILE.ods [--sheet NAME] [--range A1:E10]; stderr → diagnostics and error messages on failure
Exit codes 0 on success (e.g. --help, no arguments, --list-sheets FILE, or successful table view); 2 for CLI usage errors (e.g. --list-sheets without FILE, malformed --range); 1 for runtime/IO/loader errors when operating on a file
Determinism Given the same CLI arguments, environment, and locale, help, --list-sheets, and range-based table output are deterministic over the curated fixtures; future ADRs may tighten locale/format guarantees.

As of this milestone, the CLI is read-only and provides two user-visible data operations:

  • --list-sheets FILE.ods, which prints sheet names.
  • A minimal range-based table view for cell contents as specified in ADR-0004 and exercised by tests/test_cli.py using curated .ods fixtures.

3) Curation Principles

  • AI drafts; human curator approves and is accountable.
  • Non-trivial changes: add/update tests and ADRs.
  • Prefer stdlib/zero-deps unless ADR justifies otherwise.
  • Maintain transparency of reasoning and provenance.

4) Repository Map

  • docs/curation/ — baseline, prompts, blueprint, and curation log.
  • scripts/ — guardrails (recipe validation, ADR checks, fast tests, etc.).
  • .github/workflows/ci.yml — CI pipeline (lint, type-check, tests, recipe validation).
  • .pre-commit-config.yaml — local guardrails.
  • Future source and test layout (TBD, likely src/odsview and tests/).

5) ADR Policy

  • ADRs live under docs/adr/.
  • Each ADR contains Context · Decision · Consequences.
  • Status flow: Proposed → Accepted → Superseded.
  • docs/adr/README.md serves as an index; CI should fail if stale.

6) Testing Strategy

  • Cover CLI contracts (inputs, outputs, exit codes, invariants).
  • At least one edge case per new behavior (e.g. empty sheet, large sheet, invalid file).
  • Keep deterministic and fast; network-free.
  • Provide a fast subset via scripts/fast_tests.sh.

7) Automation — Self-Verifying

Stage Tools Purpose
Local (pre-commit) Ruff, mypy, ADR guards, print-guard, fast tests Prevent regressions early
CI Lint → Type → Tests → ADR checks → Recipe validation Guarantee reproducibility

Curator docs under docs/curation/ are validated via scripts/validate_recipe.py but excluded from general lint/type checks.

8) Definition of Done

  • Lint/types/tests/build all green.
  • Tests cover new/changed behavior.
  • Docs/ADRs updated as needed.
  • Provenance intact (licenses and curation docs preserved).
  • Packaging/version sanity verified.

9) AI Assistant Operating Procedure

  1. Read repository tree and curator’s current goal.
  2. Expand the goal into a small checklist of concrete steps.
  3. Propose minimal, focused diffs instead of large rewrites.
  4. Propose explicit shell commands using this repo’s scripts and tooling (e.g. pre-commit run --all-files, bash scripts/fast_tests.sh, python scripts/validate_recipe.py …) and let the human curator run them in the terminal.
  5. Iterate until checks are green or clearly mark any deferrals.
  6. Summarize changes (Done/Deferred) and reference ADRs where applicable.
  7. Keep attribution; never remove license/provenance.

10) Releases & Versioning

  • Use Semantic Versioning once the CLI is public.
  • Define a single source of truth for the version (e.g. __version__ in the package module or pyproject.toml).
  • Tag releases as vX.Y.Z; require green CI for tags.
  • Maintain lightweight release notes and/or changelog when appropriate.

11) Maintenance Rhythm

  • Periodically run pre-commit run --all-files.
  • Review README and BLUEPRINT.md for accuracy versus implemented behavior.
  • Perform ADR housekeeping (index, statuses, superseded links).
  • Review automation scripts and CI for drift.

Deferred with Rationale

  • Detailed CLI option and exit code matrix — will be specified in Appendix A once the first CLI implementation is in place.
  • Determinism guarantees for locale/encoding — to be documented alongside the first end-to-end tests.

Appendix A — Project-Specific Contracts

Current implemented behavior

  • CLI entrypoint: odsview console script (via pyproject.toml).
  • Inputs:
    • No arguments → prints help to stdout, exits with code 0.
    • --help → prints help to stdout, exits with code 0.
    • FILE argument without --list-sheets → renders a default preview window of the first sheet, equivalent to range A1:H10, and exits with code 0.
    • --list-sheets FILE → lists sheet names (one per line) to stdout and exits with code 0 on success.
    • FILE plus --sheet NAME and/or --range A1:E10 → renders a range-based table view as specified in ADR-0004 and exits with code 0 on success. -- Outputs:
    • Help/usage text.
    • Sheet names (one per line) when requested via --list-sheets.
    • Range-based table output for odsview FILE.ods and --sheet/--range combinations.
  • Invariants (even at this stage):
    • Never mutates any input file.
    • Avoids interactive prompts by default.

Current implemented internals (used by CLI and tests)

  • Container layer: odsview.container.open_ods_container(path) validates that the given path exists and is an .ods-compatible ZIP container and exposes access to content.xml.
  • Workbook layer: odsview.workbook.load_workbook(path) uses odfpy to load the document model from content.xml and returns a Workbook abstraction.
  • Sheet enumeration: Workbook.sheets provides an ordered list of sheets (names only). This is exercised both by tests and by the --list-sheets CLI behavior using the fixture tests/fixtures/simple.ods.

Planned behavior (not yet implemented, subject to future ADRs)

  • Smarter defaults (e.g. terminal-size-aware windows) and truncation rules for very wide or long sheets.
  • Additional display options (e.g. toggling gridlines, alignment controls) while preserving the simple range-based contract.

Planned contracts become authoritative only once backed by tests and, where appropriate, ADRs.