Skip to content

feat: add type annotations to core and tasks modules#3

Closed
Tokenized2027 wants to merge 10 commits intoleonprou:mainfrom
Tokenized2027:feat/type-annotations
Closed

feat: add type annotations to core and tasks modules#3
Tokenized2027 wants to merge 10 commits intoleonprou:mainfrom
Tokenized2027:feat/type-annotations

Conversation

@Tokenized2027
Copy link
Copy Markdown
Contributor

What

Type annotations added to the two foundational modules (core.py and tasks.py) plus a py.typed PEP 561 marker file.

core.py — 29 public functions annotated, including:

  • Vault discovery: find_root, vault_path, tasks_dir_path
  • Frontmatter parsing: parse_frontmatter, parse_multiline_value, parse_inline_list, parse_frontmatter_list, parse_frontmatter_for_json, extract_body, strip_wikilink
  • Text utilities: slugify, title_from_description, shlex_join
  • Output helpers: info, err, warn, header, step, detail, success, failure, hint, remaining_line, format_duration, tips_block, summary_block
  • Module state setters: set_quiet, set_run_start

tasks.py — 13 public functions annotated, including:

  • discover_tasks, resolve_task, group_tasks_for_display, format_table
  • validate_transition, allowed_from
  • update_frontmatter, next_task_id, create_task_file
  • All four command handlers: cmd_list, cmd_show, cmd_create, cmd_status

Why

  • IDE autocompletion and inline documentation for callers of these modules
  • Type checkers (mypy, pyright) can now catch misuse at the call sites
  • Makes the public API self-documenting — resolve_task returning tuple[str | None, str | None, int] is immediately clear to a reader

Scope and approach

  • from __future__ import annotations at the top of each file — clean Python 3.9+ compatible syntax with no runtime cost
  • from typing import Any, Optional only where needed (union types use X | Y syntax via the future import)
  • Only function signatures annotated — zero logic changes, zero new dependencies, zero docstrings added or modified
  • Private helpers (_check_dir, _git_toplevel, _use_color, etc.) intentionally left unannotated
  • py.typed empty marker file signals to PEP 561-aware type checkers that this package supports typing

Tests

All existing tests continue to pass. The annotation-only changes introduce no behavioural differences.

leonprou and others added 10 commits March 19, 2026 21:56
Spec the .openstation-only convention: drop dual-path prefix, define vault_path helper, migration checklist for all modules
Research shared artifacts across worktrees; recommended runtime resolution in find_root()

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Remove prefix parameter, add vault_path() helper, simplify find_root() to return single root path with .openstation/ hardcoded
… from all signatures

Drop the dual-path vault detection (root-level source repo vs .openstation/).
All vault files now live under .openstation/ with a single code path.

- Remove `prefix` parameter from remaining run.py functions (cmd_run,
  cmd_agents_list, cmd_agents_show, _find_agent_artifact, _agent_not_found)
- Replace all `if prefix:` path branching with core.vault_path()
- Remove source-guard check from init.py (agents/ + install.sh detection)
- Update all 7 test files: vault fixtures use .openstation/ + git init,
  remove source-repo test cases, fix hardcoded path references
- Remove stale .specify/ and content artifacts

All 416 tests pass.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
The zipapp used importlib.metadata which has no package metadata,
so --version always showed "dev". Now generates _version.py at
build time and falls back to importlib.metadata for pip installs.
Also bumps install.sh OPENSTATION_VERSION to v0.11.0.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
The 0173 convention moved commands/, skills/, docs/, templates/,
and agents/ under .openstation/ in the source repo, but init.py
still referenced the old root-level paths — breaking `os init`.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Replace hardcoded INIT_DOCS, INIT_SKILLS, and INIT_DEFAULT_AGENTS
with _discover_docs(), _discover_skills(), and _discover_templates()
so new files are picked up automatically without editing init.py.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
- Add from __future__ import annotations to core.py and tasks.py
- Add typing imports (Any, Optional) where needed
- Annotate all public function signatures in core.py (29 functions)
- Annotate all public function signatures in tasks.py (13 functions)
- Add py.typed PEP 561 marker so type checkers recognise the package
- No logic changes, no new dependencies, no docstring additions

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
@Tokenized2027 Tokenized2027 closed this by deleting the head repository Apr 7, 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.

2 participants