induscode 0.1.0__py3-none-any.whl

induscode/launch/invocation/read.py

@@ -0,0 +1,369 @@
+"""The invocation reader — a generic, table-driven argv parser over
+:data:`~.flags.FLAG_SPECS`.
+
+This is the application's full command-line grammar (the boot layer carries
+only a thin routing parser). It walks a sliced ``argv`` once and folds every
+token into a fully-typed :class:`~induscode.launch.contract.Invocation`:
+recognised flags bind through the declarative flag table, ``@file`` references
+collect for the attachment gatherer, and remaining positionals become the
+prompt and the positional tail.
+
+The grammar is deliberately textbook and entirely data-driven — there is no
+per-flag branch. One index over the table maps every canonical name and alias
+to its row; the loop applies whichever row a token resolves to:
+
+- **``--name=value``** and **``--name value``** both bind a ``string`` /
+  ``number`` / ``list`` flag; an inline ``=value`` wins, otherwise the
+  following token is consumed (unless it is itself a flag, in which case the
+  value is empty).
+- **longest-alias match** resolves the canonical name, so a longer spelling
+  is never shadowed by a shorter prefix (whole tokens match whole index keys).
+- **``--``** terminates option parsing; every subsequent token is positional.
+- **clustered short booleans** (``-pi``) expand to each single-letter switch.
+- **``list`` flags accumulate** across repetition and split a single
+  comma-separated token into elements.
+- **``@file``** tokens are recorded as attachment references rather than
+  positionals.
+
+The parse is total: an unrecognised ``--flag`` is tolerated as a boolean
+switch in the loose ``Invocation.flags`` bag (the extension-flag escape hatch)
+rather than rejected, so nothing is silently dropped. Strong typing of the
+named fields, and mode derivation, happen in one final fold.
+
+Port note: the framework parser engine (``indusagi.shell_app.invocation``)
+raises on unknown flags and has no list-kind / ``@file`` / cluster support, so
+this table-driven reader is ported whole rather than silently adopting the
+engine (analysis 04 risk-5).
+"""
+
+from __future__ import annotations
+
+import math
+from dataclasses import dataclass, field
+from typing import Final, Mapping, Sequence
+
+from ..contract import (
+    FlagValue,
+    Invocation,
+    OutputMode,
+    ThinkingEffort,
+    ToolName,
+    is_thinking_effort,
+    is_tool_name,
+)
+from .flags import FLAG_SPECS, GroupedFlagSpec
+
+__all__ = ["read_file_references", "read_invocation"]
+
+
+def _is_flag_token(token: str) -> bool:
+    """Whether a token is a flag (``-x`` / ``--x``) rather than a positional
+    or the ``-`` stdin convention."""
+    return len(token) > 1 and token.startswith("-")
+
+
+def _is_long_token(token: str) -> bool:
+    """Whether a token is a long flag (``--x``), eligible for inline
+    ``=value`` and the ``--`` terminator."""
+    return token.startswith("--")
+
+
+def _is_short_cluster(token: str) -> bool:
+    """Whether a token is a clustered short switch run (``-pi``), excluding
+    ``-`` and ``--``."""
+    return len(token) > 1 and token[0] == "-" and token[1] != "-"
+
+
+def _flag_key(name: str) -> str:
+    """Strip the leading dashes from a canonical flag name to get its
+    flag-bag key."""
+    return name.lstrip("-")
+
+
+def _build_token_index() -> dict[str, GroupedFlagSpec]:
+    """Build the token index over the table: every canonical name and every
+    alias maps to its owning row. The longest-alias rule falls out of matching
+    whole tokens against whole keys (a longer spelling and a shorter one are
+    distinct keys, never prefixes of one lookup)."""
+    index: dict[str, GroupedFlagSpec] = {}
+    for spec in FLAG_SPECS:
+        index[spec.name] = spec
+        for alias in spec.aliases:
+            index[alias] = spec
+    return index
+
+
+#: The single shared token index; the table is frozen, so one build suffices.
+_TOKEN_INDEX: Final[dict[str, GroupedFlagSpec]] = _build_token_index()
+
+
+def _build_short_boolean_set() -> set[str]:
+    """The set of single-letter aliases that name a boolean flag, for cluster
+    expansion."""
+    letters: set[str] = set()
+    for spec in FLAG_SPECS:
+        if spec.kind != "boolean":
+            continue
+        for alias in spec.aliases:
+            if len(alias) == 2 and alias[0] == "-" and alias[1] != "-":
+                letters.add(alias[1])
+    return letters
+
+
+#: Single-letter boolean switches eligible to appear in a ``-pi`` cluster.
+_SHORT_BOOLEANS: Final[set[str]] = _build_short_boolean_set()
+
+
+def _split_inline(token: str) -> tuple[str, str | None]:
+    """Split a long token into its flag name and optional inline ``=value``."""
+    if _is_long_token(token):
+        eq = token.find("=")
+        if eq != -1:
+            return token[:eq], token[eq + 1 :]
+    return token, None
+
+
+def _split_list(value: str) -> list[str]:
+    """Split a ``list`` flag value into its comma-separated elements, dropping
+    blanks."""
+    return [part.strip() for part in value.split(",") if part.strip()]
+
+
+def _coerce_scalar(kind: str, raw: str) -> FlagValue:
+    """Coerce a raw value token to the runtime type its kind fixes. Numbers
+    parse with JS ``Number`` semantics: the empty string is ``0`` and an
+    unparseable number yields ``NaN``, which the named-field fold below treats
+    as absent."""
+    if kind == "number":
+        if raw.strip() == "":
+            return 0.0
+        try:
+            return float(raw)
+        except ValueError:
+            return math.nan
+    return raw
+
+
+@dataclass(slots=True)
+class _ParseState:
+    """The mutable accumulator threaded through the parse, before the typed
+    fold."""
+
+    # The loose flag bag, keyed by canonical flag name (dashes stripped).
+    flags: dict[str, FlagValue] = field(default_factory=dict)
+    # Positional tokens (after the prompt) and, with `--`, every later token.
+    positionals: list[str] = field(default_factory=list)
+    # `@file` references collected for the attachment gatherer.
+    file_refs: list[str] = field(default_factory=list)
+    # The first positional becomes the prompt; later ones go to positionals.
+    prompt: str | None = None
+
+
+def _push_positional(state: _ParseState, token: str) -> None:
+    """Record a positional token: the first becomes the prompt, the rest
+    accumulate."""
+    if state.prompt is None:
+        state.prompt = token
+    else:
+        state.positionals.append(token)
+
+
+def _accumulate_list(state: _ParseState, key: str, items: list[str]) -> None:
+    """Append elements to a ``list`` flag, preserving prior accumulation."""
+    prior = state.flags.get(key)
+    base = prior if isinstance(prior, list) else []
+    state.flags[key] = [*base, *items]
+
+
+def _apply_flag(
+    spec: GroupedFlagSpec,
+    inline: str | None,
+    argv: Sequence[str],
+    i: int,
+    state: _ParseState,
+) -> int:
+    """Apply one resolved flag row at position ``i``, returning the index of
+    the last token it consumed. A value flag may consume the following token;
+    a boolean consumes only itself."""
+    key = _flag_key(spec.name)
+
+    if spec.kind == "boolean":
+        state.flags[key] = True
+        return i
+
+    # Value-bearing flag: take the inline `=value`, else the next non-flag
+    # token.
+    value = inline
+    consumed = i
+    if value is None and i + 1 < len(argv) and not _is_flag_token(argv[i + 1]):
+        value = argv[i + 1]
+        consumed = i + 1
+    raw = value if value is not None else ""
+
+    if spec.kind == "list":
+        _accumulate_list(state, key, _split_list(raw))
+    else:
+        state.flags[key] = _coerce_scalar(spec.kind, raw)
+    return consumed
+
+
+def _apply_short_cluster(token: str, state: _ParseState) -> bool:
+    """Expand a clustered short-boolean token (``-pi``) into its component
+    switches, setting each in the flag bag. Returns False if any letter is not
+    a known short boolean, so the caller can fall back to treating the token
+    as an unknown flag."""
+    letters = list(token[1:])
+    if not all(letter in _SHORT_BOOLEANS for letter in letters):
+        return False
+    for letter in letters:
+        spec = _TOKEN_INDEX.get(f"-{letter}")
+        if spec is not None:
+            state.flags[_flag_key(spec.name)] = True
+    return True
+
+
+def _read_string(flags: Mapping[str, FlagValue], key: str) -> str | None:
+    """Read a string flag-bag entry, or None when absent / non-string /
+    empty."""
+    value = flags.get(key)
+    return value if isinstance(value, str) and len(value) > 0 else None
+
+
+def _read_list(flags: Mapping[str, FlagValue], key: str) -> list[str] | None:
+    """Read a list flag-bag entry as a string list, or None when absent."""
+    value = flags.get(key)
+    return value if isinstance(value, list) else None
+
+
+def _read_bool(flags: Mapping[str, FlagValue], key: str) -> bool:
+    """Whether a boolean flag-bag entry is set."""
+    return flags.get(key) is True
+
+
+def _derive_mode(flags: Mapping[str, FlagValue]) -> OutputMode:
+    """Derive the resolved :data:`OutputMode`. The headless line protocol
+    (``--json`` / ``--rpc``) wins over a one-shot print, which in turn implies
+    the non-interactive ``json`` result mode unless the interactive switch
+    overrides it; with neither, the mode is the interactive ``text``
+    session."""
+    if _read_bool(flags, "json"):
+        return "rpc"
+    if _read_bool(flags, "print") and not _read_bool(flags, "interactive"):
+        return "json"
+    return "text"
+
+
+def _resolve_thinking(flags: Mapping[str, FlagValue]) -> ThinkingEffort | None:
+    """Resolve the requested reasoning effort, ignoring an unrecognised
+    value."""
+    raw = _read_string(flags, "thinking")
+    if raw is not None and is_thinking_effort(raw):
+        return raw  # type: ignore[return-value]  # narrowed by the guard
+    return None
+
+
+def _resolve_tools(flags: Mapping[str, FlagValue]) -> tuple[ToolName, ...] | None:
+    """Resolve the explicit tool allow-list, keeping only recognised tool
+    names."""
+    raw = _read_list(flags, "tools")
+    if raw is None:
+        return None
+    return tuple(name for name in raw if is_tool_name(name))  # type: ignore[misc]
+
+
+def read_invocation(argv: Sequence[str]) -> Invocation:
+    """Read a sliced ``argv`` into the fully-parsed
+    :class:`~induscode.launch.contract.Invocation`.
+
+    Walks the tokens once via the table index, accumulates into a parse state,
+    then folds that into the strongly-typed result: the loose ``flags`` bag is
+    retained for round-tripping and extension flags, and the named fields are
+    derived from it with per-kind coercion and validation. The ``attachments``
+    field is left unset here — the file references are surfaced for the
+    attachment gatherer to expand separately (:func:`read_file_references`).
+
+    :param argv: the already-sliced argument vector (no interpreter / script
+        path)
+    """
+    state = _ParseState()
+    options_terminated = False
+
+    i = 0
+    while i < len(argv):
+        token = argv[i]
+
+        if options_terminated:
+            _push_positional(state, token)
+            i += 1
+            continue
+
+        if token == "--":
+            options_terminated = True
+            i += 1
+            continue
+
+        if token.startswith("@") and len(token) > 1:
+            state.file_refs.append(token[1:])
+            i += 1
+            continue
+
+        if not _is_flag_token(token):
+            _push_positional(state, token)
+            i += 1
+            continue
+
+        name, inline = _split_inline(token)
+        spec = _TOKEN_INDEX.get(name)
+        if spec is not None:
+            i = _apply_flag(spec, inline, argv, i, state) + 1
+            continue
+
+        # Unrecognised short cluster: expand if every letter is a known
+        # switch.
+        if _is_short_cluster(token) and _apply_short_cluster(token, state):
+            i += 1
+            continue
+
+        # Unknown flag: tolerate as a boolean switch (the extension-flag
+        # hatch); an inline `=value` keeps its value.
+        state.flags[_flag_key(name)] = inline if inline is not None else True
+        i += 1
+
+    flags = state.flags
+    return Invocation(
+        mode=_derive_mode(flags),
+        prompt=state.prompt,
+        flags=flags,
+        positionals=tuple(state.positionals),
+        model=_read_string(flags, "model"),
+        account=_read_string(flags, "account"),
+        cwd=_read_string(flags, "cwd"),
+        system=_read_string(flags, "system"),
+        append_system=_read_string(flags, "append-system"),
+        thinking=_resolve_thinking(flags),
+        tools=_resolve_tools(flags),
+        no_tools=_read_bool(flags, "no-tools"),
+        mcp=tuple(_read_list(flags, "mcp") or []),
+        print=_read_bool(flags, "print"),
+        interactive=_read_bool(flags, "interactive"),
+        help=_read_bool(flags, "help"),
+        version=_read_bool(flags, "version"),
+    )
+
+
+def read_file_references(argv: Sequence[str]) -> list[str]:
+    """The ``@file`` references collected from an argv, exposed for the
+    attachment gatherer. A thin re-walk of the reader so the file references
+    can be obtained without re-deriving the whole parse where only attachments
+    are needed."""
+    refs: list[str] = []
+    options_terminated = False
+    for token in argv:
+        if options_terminated:
+            continue
+        if token == "--":
+            options_terminated = True
+            continue
+        if token.startswith("@") and len(token) > 1:
+            refs.append(token[1:])
+    return refs

induscode/launch/invocation/usage.py

@@ -0,0 +1,110 @@
+"""The usage renderer — generated entirely from :data:`~.flags.FLAG_SPECS`.
+
+:func:`render_usage` produces the ``--help`` banner by walking the same
+declarative flag table the reader parses against. There is no second,
+hand-maintained help string; every option line is synthesised from its row
+(its canonical name, its aliases, its value placeholder, and its one-line
+description), grouped by the editorial :data:`~.flags.FLAG_GROUPS` sections.
+Adding a flag to the table therefore adds it to the help with no further
+edit, and the two can never disagree about what exists.
+
+The renderer is pure and total: it reads only the table and returns a string.
+
+Port note: the synopsis names the Python console script (``pindus``); the TS
+build printed its own bin name there. Everything else is the TS layout
+verbatim (two-space indent, 28-column signature padding, the trailing
+``@file`` / ``--`` arguments note).
+"""
+
+from __future__ import annotations
+
+from typing import Final
+
+from .flags import FLAG_GROUPS, FLAG_SPECS, FlagGroup, GroupedFlagSpec
+
+__all__ = ["render_usage"]
+
+
+#: Two-space indent for option lines within a section.
+_INDENT: Final[str] = "  "
+
+#: Minimum column width the description is padded out to, for alignment.
+_SIGNATURE_COLUMN: Final[int] = 28
+
+
+def _placeholder(spec: GroupedFlagSpec) -> str:
+    """The value placeholder shown after a value-bearing flag in the usage
+    text. Boolean switches take no placeholder; value, number, and list flags
+    each get a shape hint (a list shows the repeatable / comma form)."""
+    match spec.kind:
+        case "boolean":
+            return ""
+        case "number":
+            return " <n>"
+        case "list":
+            return " <a,b>"
+        case _:  # "string" and anything future
+            return " <value>"
+
+
+def _signature(spec: GroupedFlagSpec) -> str:
+    """Render the left "signature" column for a flag: its canonical name, then
+    any aliases in parentheses, then the value placeholder. e.g.
+    ``--print (-p)`` or ``--model (-m) <value>``."""
+    alias_part = f" ({', '.join(spec.aliases)})" if spec.aliases else ""
+    return f"{spec.name}{alias_part}{_placeholder(spec)}"
+
+
+def _option_line(spec: GroupedFlagSpec) -> str:
+    """Render one option line: indented signature, padded, then its
+    description."""
+    sig = _signature(spec)
+    pad = " " * (_SIGNATURE_COLUMN - len(sig)) if len(sig) < _SIGNATURE_COLUMN else "  "
+    return f"{_INDENT}{sig}{pad}{spec.describe}"
+
+
+def _rows_for_group(group: FlagGroup) -> list[GroupedFlagSpec]:
+    """The flag rows filed under one group, in their table declaration
+    order."""
+    return [spec for spec in FLAG_SPECS if spec.group == group]
+
+
+def render_usage() -> str:
+    """Render the full usage banner.
+
+    Emits a synopsis line, then one section per :data:`~.flags.FLAG_GROUPS`
+    entry that has any rows, then a short note on the two positional
+    conventions the reader honours but that are not flags: the ``@file``
+    attachment syntax and the ``--`` option terminator. Every option line is
+    derived from the table; this function holds no per-flag knowledge of its
+    own.
+
+    :returns: the complete multi-line usage string (no trailing newline)
+    """
+    lines: list[str] = []
+
+    lines.append("Usage: pindus [options] [prompt] [@file ...]")
+    lines.append("")
+    lines.append("A terminal-first AI coding agent.")
+
+    for group in FLAG_GROUPS:
+        rows = _rows_for_group(group.id)
+        if not rows:
+            continue
+        lines.append("")
+        lines.append(f"{group.title}:")
+        for spec in rows:
+            lines.append(_option_line(spec))
+
+    lines.append("")
+    lines.append("Arguments:")
+    lines.append(
+        f"{_INDENT}@file".ljust(_SIGNATURE_COLUMN + len(_INDENT))
+        + "Attach a text or image file to the first message."
+    )
+    lines.append(
+        f"{_INDENT}--".ljust(_SIGNATURE_COLUMN + len(_INDENT))
+        + "Stop parsing options; treat every later token as a positional."
+    )
+
+    return "\n".join(lines)