induscode 0.1.0__py3-none-any.whl

induscode/console/slash_commands/builtins.py

@@ -0,0 +1,254 @@
+"""The built-in slash catalog — the single ordered source of truth.
+
+Port of TS ``src/console/slash/builtins.ts``. The catalog is assembled from
+three static topic groups, each its own module in this package: transcript /
+session control, the workbench pickers, and the integration bridges. On top
+of those it splices in the *dynamic* rows — one ``/skill:<name>`` per
+discovered Agent-Skills capability card and one ``/<template-name>`` per
+discovered prompt-template macro — produced by
+:func:`~induscode.console.slash_commands.dynamic.build_dynamic_commands`.
+
+There is no command ``if``-ladder anywhere: adding a static command is
+appending a row to one of the groups, and the dynamic rows are discovered
+from the standard skill/macro roots (returning nothing, never an error, when
+those roots are absent). The registry index, the completion matcher, and the
+family grouping are all *derived* from the assembled catalog (see
+:mod:`induscode.console_slash.registry`).
+
+Listing order is intentional: transcript controls first (the verbs a new
+user meets), then the workbench pickers, then the integration bridges, and
+finally the discovered skills and templates.
+
+Port deltas, locked by the plan (cross-cutting rule 4 / analysis 03 §6.5):
+
+- **Assembly is the explicit** :func:`build_catalog` ``(cwd, home)``
+  function — the TS module ran discovery at import time; import-time fs
+  scans are banned here, and the explicit roots make the discovery testable
+  against a temp tree.
+- **The defaults are lazy.** ``SLASH_COMMANDS`` and
+  ``DEFAULT_SLASH_REGISTRY`` remain importable for parity, but they are
+  minted on first attribute access via module ``__getattr__`` (and cached so
+  the TS identity pins — ``DEFAULT_SLASH_REGISTRY.commands is
+  SLASH_COMMANDS`` — keep holding). :func:`reset_default_registry` drops the
+  cache for tests.
+- **Per-console bridge state**: the integrations group is minted against an
+  :class:`~induscode.console.slash_commands.integrations.IntegrationsRuntime`
+  holder per :func:`build_catalog` call, replacing the TS module globals.
+- Building the default registry also installs it as the ``/help`` catalog
+  provider (the late-bound provider that replaced the TS dynamic-import
+  cycle-breaker — see :mod:`.workbench`), so ``/help`` lists the dynamic
+  rows exactly as the TS ``SLASH_COMMANDS`` listing did.
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from typing import Final
+
+from induscode.briefing import Macro, MacroOrigin, SkillRoot, gather_skill_cards, load_macros
+from induscode.console_slash import SlashCommand, SlashRegistry, build_registry
+
+from .dynamic import DynamicCommandSources, build_dynamic_commands
+from .integrations import IntegrationsRuntime, build_integration_commands
+from .transcript import transcript_commands
+from .workbench import set_help_registry_provider, workbench_commands
+
+__all__ = [
+    "DEFAULT_SLASH_REGISTRY",
+    "DynamicRoots",
+    "MacroRoot",
+    "PROJECT_DIR",
+    "SLASH_COMMANDS",
+    "build_catalog",
+    "build_default_registry",
+    "discover_dynamic_sources",
+    "dynamic_roots",
+    "reset_default_registry",
+]
+
+
+# ---------------------------------------------------------------------------
+# Dynamic discovery
+# ---------------------------------------------------------------------------
+
+#: The per-project settings directory dynamic roots are resolved under.
+PROJECT_DIR: Final = ".indusagi"
+
+
+@dataclass(frozen=True, slots=True)
+class MacroRoot:
+    """One prompt-template root to scan, with its origin tag and the label
+    woven into derived descriptions."""
+
+    dir: str
+    origin: MacroOrigin
+    label: str
+
+
+@dataclass(frozen=True, slots=True)
+class DynamicRoots:
+    """The skill and macro roots to scan, in precedence order."""
+
+    skills: tuple[SkillRoot, ...]
+    macros: tuple[MacroRoot, ...]
+
+
+def dynamic_roots(cwd: str, home: str) -> DynamicRoots:
+    """The skill and macro roots to scan, in precedence order (project
+    before user so a project-local card or template shadows a user-global
+    one of the same name). Every root is optional; a missing directory
+    simply yields nothing.
+
+    :param cwd:  the workspace directory (project roots resolve under it)
+    :param home: the user's home directory (user roots resolve under it)
+    """
+    return DynamicRoots(
+        skills=(
+            SkillRoot(dir=os.path.join(cwd, PROJECT_DIR, "skills"), origin="project"),
+            SkillRoot(dir=os.path.join(home, PROJECT_DIR, "skills"), origin="user"),
+        ),
+        macros=(
+            MacroRoot(
+                dir=os.path.join(cwd, PROJECT_DIR, "commands"),
+                origin="project",
+                label="project",
+            ),
+            MacroRoot(
+                dir=os.path.join(home, PROJECT_DIR, "commands"),
+                origin="user",
+                label="user",
+            ),
+        ),
+    )
+
+
+def discover_dynamic_sources(cwd: str, home: str) -> DynamicCommandSources:
+    """Discover the skill cards and prompt-template macros available on disk.
+
+    Never throws: the underlying loaders treat a missing or unreadable root
+    as an empty result, so this returns whatever was found and an empty set
+    otherwise. Templates are deduped by name across roots (first root wins —
+    project shadows user).
+
+    :param cwd:  the workspace directory
+    :param home: the user's home directory
+    """
+    roots = dynamic_roots(cwd, home)
+
+    try:
+        skills = tuple(gather_skill_cards(roots.skills).cards)
+    except Exception:
+        skills = ()
+
+    templates: list[Macro] = []
+    claimed: set[str] = set()
+    for root in roots.macros:
+        try:
+            loaded = load_macros(root.dir, origin=root.origin, label=root.label)
+        except Exception:
+            loaded = []
+        for macro in loaded:
+            if macro.name in claimed:
+                continue
+            claimed.add(macro.name)
+            templates.append(macro)
+
+    return DynamicCommandSources(skills=skills, templates=tuple(templates))
+
+
+# ---------------------------------------------------------------------------
+# The catalog
+# ---------------------------------------------------------------------------
+
+
+def build_catalog(
+    cwd: str,
+    home: str,
+    *,
+    integrations: IntegrationsRuntime | None = None,
+) -> tuple[SlashCommand, ...]:
+    """Assemble the full command catalog — every row in listing order.
+
+    The static command groups come first (transcript → workbench →
+    integrations), then the dynamic rows discovered under ``cwd``/``home``.
+    Every token (name + aliases) the static catalog already claims is
+    reserved: a discovered skill or template whose token would collide with
+    one of them is dropped, so splicing the dynamic rows can never make
+    ``build_registry`` raise on a duplicate.
+
+    Consumers fold the result into a
+    :class:`~induscode.console_slash.SlashRegistry` via ``build_registry``;
+    the index by name/alias, the family grouping, and the completion matcher
+    are all derived from this one tuple.
+
+    :param cwd:          the workspace directory dynamic roots resolve under
+    :param home:         the user's home directory for user-global roots
+    :param integrations: the per-console bridge-state holder; fresh when
+        omitted
+    """
+    static_commands: tuple[SlashCommand, ...] = (
+        *transcript_commands,
+        *workbench_commands,
+        *build_integration_commands(integrations),
+    )
+
+    reserved_tokens: set[str] = set()
+    for command in static_commands:
+        reserved_tokens.add(command.name.lower())
+        for alias in command.aliases:
+            reserved_tokens.add(alias.lower())
+
+    dynamic_commands = tuple(
+        command
+        for command in build_dynamic_commands(discover_dynamic_sources(cwd, home))
+        if command.name.lower() not in reserved_tokens
+    )
+
+    return (*static_commands, *dynamic_commands)
+
+
+# ---------------------------------------------------------------------------
+# The lazy defaults (TS `SLASH_COMMANDS` / `DEFAULT_SLASH_REGISTRY`)
+# ---------------------------------------------------------------------------
+
+_catalog_cache: tuple[SlashCommand, ...] | None = None
+_registry_cache: SlashRegistry | None = None
+
+
+def build_default_registry() -> SlashRegistry:
+    """The process-default registry, assembled once from the real cwd/home
+    roots and cached (the Python rendering of the TS module-level
+    ``DEFAULT_SLASH_REGISTRY``).
+
+    First build also installs the assembled catalog as the ``/help``
+    provider so the palette lists the dynamic rows too.
+    """
+    global _catalog_cache, _registry_cache
+    if _registry_cache is None:
+        if _catalog_cache is None:
+            _catalog_cache = build_catalog(os.getcwd(), os.path.expanduser("~"))
+        registry = build_registry(_catalog_cache)
+        set_help_registry_provider(lambda: registry.commands)
+        _registry_cache = registry
+    return _registry_cache
+
+
+def reset_default_registry() -> None:
+    """Drop the cached default catalog/registry and the ``/help`` provider
+    (tests; a fresh access re-discovers against the then-current cwd)."""
+    global _catalog_cache, _registry_cache
+    _catalog_cache = None
+    _registry_cache = None
+    set_help_registry_provider(None)
+
+
+def __getattr__(name: str) -> object:
+    """Lazy module attributes: the TS import-time catalog constants, minted
+    on first access (no import-time fs scans — plan cross-cutting rule 4)."""
+    if name == "SLASH_COMMANDS":
+        build_default_registry()
+        return _catalog_cache
+    if name == "DEFAULT_SLASH_REGISTRY":
+        return build_default_registry()
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

induscode/console/slash_commands/dynamic.py

@@ -0,0 +1,217 @@
+"""Dynamic slash commands — capability cards and prompt templates as registry
+rows.
+
+Port of TS ``src/console/slash/commands/dynamic.ts``. The static catalog
+(``.builtins``) is hand-maintained, but two command families are *discovered*
+rather than written by hand: the Agent-Skills capability cards
+(:class:`~induscode.briefing.SkillCard` rows loaded from ``SKILL.md`` files)
+and the user/project prompt templates (:class:`~induscode.briefing.Macro`
+rows loaded from ``*.md`` macro files). This module turns whatever was
+discovered into ordinary :class:`~induscode.console_slash.SlashCommand` rows
+so they sit in the same registry as the built-ins, complete the same way,
+and resolve through the same dispatcher.
+
+Two row shapes are produced:
+
+- ``/skill:<name>`` — invoking it submits an Agent-Skills *invocation block*
+  (``<skill name="…" location="…">body</skill>``) as a normal turn, which is
+  exactly what the agent loop recognises to load and run that skill. The
+  trailing argument string becomes the skill body, so ``/skill:commit tidy
+  the diff`` runs the ``commit`` card against "tidy the diff".
+- ``/<template-name>`` — invoking it expands the macro body against the
+  trailing arguments (the single-pass ``$arg`` model from the briefing
+  layer) and submits the result as a normal turn.
+
+Both return a :class:`~induscode.console_slash.Prompt` outcome so the
+dispatcher hands the produced text to the conductor as a turn; neither
+reaches into a backend the console does not own. When nothing was
+discovered, :func:`build_dynamic_commands` returns an empty list, so
+splicing it into the catalog is always safe.
+
+Port delta (locked): per the uniform calling convention every generated
+``run`` is ``async def``; the TS optional-fields source bag becomes the
+frozen :class:`DynamicCommandSources` dataclass with empty-tuple defaults.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from typing import Final
+
+from induscode.briefing import Macro, SkillCard, apply_macros
+from induscode.console_slash import Prompt, SlashCommand, SlashContext, SlashOutcome
+
+__all__ = [
+    "DynamicCommandSources",
+    "build_dynamic_commands",
+    "clamp_summary",
+    "skill_invocation_block",
+]
+
+
+# ---------------------------------------------------------------------------
+# Sources
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True, slots=True)
+class DynamicCommandSources:
+    """The discovered material a dynamic catalog is built from.
+
+    Both fields default to empty: a caller that only loaded skills passes
+    ``DynamicCommandSources(skills=…)``, one that only loaded templates
+    passes ``DynamicCommandSources(templates=…)``, and a caller with neither
+    passes nothing and gets back ``[]``.
+    """
+
+    # Capability cards discovered from `SKILL.md` files.
+    skills: tuple[SkillCard, ...] = ()
+    # Prompt templates discovered from `*.md` macro files.
+    templates: tuple[Macro, ...] = ()
+
+
+#: The namespace prefix every skill command answers to.
+SKILL_PREFIX: Final = "skill:"
+
+#: Trim a one-line summary down to a length the completion window can show.
+SUMMARY_BUDGET: Final = 88
+
+#: Whitespace-run collapser for the one-line summary.
+_WHITESPACE_RUNS: Final = re.compile(r"\s+")
+
+
+def clamp_summary(text: str) -> str:
+    """Cap a description to :data:`SUMMARY_BUDGET`, suffixing an ellipsis
+    when cut."""
+    one_line = _WHITESPACE_RUNS.sub(" ", text).strip()
+    if len(one_line) <= SUMMARY_BUDGET:
+        return one_line
+    return one_line[: SUMMARY_BUDGET - 1].rstrip() + "…"
+
+
+# ---------------------------------------------------------------------------
+# Skill-invocation block
+# ---------------------------------------------------------------------------
+
+
+def _escape_attr(value: str) -> str:
+    """Escape the XML attribute-significant characters for the opener tag."""
+    return (
+        value.replace("&", "&amp;")
+        .replace("<", "&lt;")
+        .replace(">", "&gt;")
+        .replace('"', "&quot;")
+    )
+
+
+def skill_invocation_block(card: SkillCard, body: str) -> str:
+    """Render the Agent-Skills invocation block for a card and an optional
+    body.
+
+    The opener carries the card ``name`` and its on-disk ``location`` so the
+    agent loop can locate and read the full instructions; the body (the
+    user's trailing argument) sits between the opener and ``</skill>``. A
+    bare invocation produces a block with an empty body — the skill still
+    runs, just without a task message.
+
+    :param card: the capability card to invoke
+    :param body: the trailing user message the skill should act on (may be
+        empty)
+    """
+    opener = (
+        f'<skill name="{_escape_attr(card.name)}" '
+        f'location="{_escape_attr(card.location)}">'
+    )
+    return f"{opener}\n{body}\n</skill>"
+
+
+def _skill_command(card: SkillCard) -> SlashCommand:
+    """Build the ``/skill:<name>`` row for one capability card.
+
+    Its ``run`` mints the invocation block against the trailing argument
+    string and returns it as a ``prompt`` outcome, so the dispatcher submits
+    it as a turn.
+
+    :param card: the capability card to expose
+    """
+
+    async def run(ctx: SlashContext) -> SlashOutcome:
+        body = ctx.args.strip()
+        return Prompt(text=skill_invocation_block(card, body))
+
+    return SlashCommand(
+        name=f"{SKILL_PREFIX}{card.name}",
+        summary=clamp_summary(card.description),
+        run=run,
+        family="skill",
+        takes_args=True,
+    )
+
+
+# ---------------------------------------------------------------------------
+# Prompt templates
+# ---------------------------------------------------------------------------
+
+
+def _template_command(macro: Macro) -> SlashCommand:
+    """Build the ``/<template-name>`` row for one prompt-template macro.
+
+    Its ``run`` expands the macro body against the trailing argument string
+    via the single-pass ``$arg`` resolver and returns the expansion as a
+    ``prompt`` outcome.
+
+    :param macro: the prompt template to expose
+    """
+
+    async def run(ctx: SlashContext) -> SlashOutcome:
+        return Prompt(text=apply_macros(macro.body, ctx.args))
+
+    return SlashCommand(
+        name=macro.name,
+        summary=clamp_summary(macro.description),
+        run=run,
+        family="template",
+        takes_args=True,
+    )
+
+
+# ---------------------------------------------------------------------------
+# Assembly
+# ---------------------------------------------------------------------------
+
+
+def build_dynamic_commands(
+    sources: DynamicCommandSources | None = None,
+) -> list[SlashCommand]:
+    """Project discovered skills and templates into command rows.
+
+    Skill rows are listed first (namespaced under ``skill:``), then the
+    template rows. A name claimed by an earlier row — including any of the
+    static built-ins a caller will concatenate these ahead of — is the
+    registry's problem to reject at assembly time; this function only
+    suppresses *self*-collisions so a template whose name duplicates another
+    template (first wins) cannot crash the build. When no sources are
+    supplied the result is an empty list, never an error.
+
+    :param sources: the discovered skills and templates
+    :returns: the dynamic command rows, skills first then templates
+    """
+    resolved = sources if sources is not None else DynamicCommandSources()
+    rows: list[SlashCommand] = []
+    claimed: set[str] = set()
+
+    for card in resolved.skills:
+        command = _skill_command(card)
+        if command.name in claimed:
+            continue
+        claimed.add(command.name)
+        rows.append(command)
+
+    for macro in resolved.templates:
+        if macro.name in claimed:
+            continue
+        claimed.add(macro.name)
+        rows.append(_template_command(macro))
+
+    return rows