induscode 0.1.0__py3-none-any.whl

induscode/boot/stages.py

@@ -0,0 +1,198 @@
+"""Boot stage pipeline — the ordered list of :class:`~.contract.Stage`
+transforms that turn a bare :class:`~.contract.BootContext` (argv + workspace
++ brand) into a fully-resolved one (parsed invocation, materialised
+directories, applied upgrades, resolved startup resources, selected runner).
+
+Port of TS ``src/boot/stages.ts``. The pipeline is data, not control flow:
+:data:`STAGES` lists each step in order, and :func:`run_stages` folds an
+*immutable* context through them — every stage receives a context and returns
+its successor (built with :func:`dataclasses.replace`, never by mutating). A
+stage may return an awaitable; the fold awaits each in turn so ordering and
+side-effect sequencing are deterministic.
+
+Stage order and intent:
+
+1. ``locate-workspace``  — materialise the resolved workspace on disk
+   (:func:`~induscode.workspace.ensure_dirs`). Pure path computation already
+   happened when the initial context was built; this stage only ``mkdir``\\ s.
+2. ``apply-upgrades``    — fold the idempotent
+   :func:`~.upgrade.apply_upgrades` registry over the workspace (a no-op on
+   an already-current profile).
+3. ``build-invocation``  — parse ``argv`` into the typed invocation.
+4. ``resolve-resources`` — best-effort construct the framework
+   settings/auth/model graph; degrade to a minimal object if a framework
+   piece is unavailable.
+5. ``select-runner``     — no-op transform that exists for symmetry and
+   tracing (the actual dispatch happens in :mod:`~.boot` after the pipeline,
+   so the selected runner can own the exit code).
+"""
+
+from __future__ import annotations
+
+import inspect
+from collections.abc import Mapping, Sequence
+from dataclasses import replace
+from typing import Final
+
+from indusagi.shell_app import Settings
+
+from induscode.conductor import CatalogSource, ModelCatalog
+from induscode.workspace import ensure_dirs
+
+from .contract import BootContext, Stage, StartupResources
+from .invocation import tokenize_invocation
+from .upgrade import apply_upgrades
+
+__all__ = [
+    "STAGES",
+    "build_invocation",
+    "locate_workspace",
+    "resolve_resources",
+    "run_stages",
+    "select_runner_stage",
+    "upgrade_stage",
+]
+
+
+# ---------------------------------------------------------------------------
+# Stages
+# ---------------------------------------------------------------------------
+
+
+def _locate_workspace(ctx: BootContext) -> BootContext:
+    """Materialise the resolved workspace directories on disk. The workspace
+    record was already computed (pure) when the initial context was
+    assembled; this stage only ensures the directory subset exists. Returns
+    the same context — only the filesystem side effects happen here."""
+    ensure_dirs(ctx.workspace)
+    return ctx
+
+
+#: Stage 1 — materialise the workspace directories.
+locate_workspace: Final[Stage] = Stage(name="locate-workspace", apply=_locate_workspace)
+
+
+async def _apply_upgrades(ctx: BootContext) -> BootContext:
+    """Run any pending one-time profile upgrades, idempotently. The driver is
+    non-fatal: a step that fails is reported and retried on a later launch,
+    never aborting boot. The context is returned unchanged (upgrades touch
+    the filesystem, not the context)."""
+    await apply_upgrades(ctx.workspace)
+    return ctx
+
+
+#: Stage 2 — fold the upgrade registry over the workspace.
+#:
+#: Port note: TS exported this stage as ``upgrade``; in Python that name
+#: would shadow the :mod:`induscode.boot.upgrade` subpackage attribute on the
+#: parent package, so it is exported as ``upgrade_stage``.
+upgrade_stage: Final[Stage] = Stage(name="apply-upgrades", apply=_apply_upgrades)
+
+
+def _build_invocation(ctx: BootContext) -> BootContext:
+    """Parse ``argv`` into the typed invocation and thread it onto the
+    context. The initial context carries a pre-parsed invocation (the
+    bootstrapper parses once up front for the meta short-circuits); this
+    stage replaces it with a fresh parse of the same argv."""
+    return replace(ctx, invocation=tokenize_invocation(ctx.argv))
+
+
+#: Stage 3 — re-parse the command line.
+build_invocation: Final[Stage] = Stage(name="build-invocation", apply=_build_invocation)
+
+
+def _load_default_settings() -> Settings | Mapping[str, object]:
+    """Resolve the framework's baseline settings. Prefers the framework's
+    published ``DEFAULT_SETTINGS``; a load failure degrades to an empty
+    mapping without failing boot (the *shape* is what later phases rely on)."""
+    try:
+        from indusagi.shell_app import DEFAULT_SETTINGS
+
+        return DEFAULT_SETTINGS
+    except Exception:
+        return {}
+
+
+def _load_model_catalog() -> ModelCatalog:
+    """Resolve the model catalog: a fresh conductor
+    :class:`~induscode.conductor.ModelCatalog` over the live framework
+    registry (constructed fresh so per-process custom-model loading does not
+    leak across runs); degrades to an empty catalog when the framework
+    registry is unavailable."""
+    try:
+        return ModelCatalog()
+    except Exception:
+        return ModelCatalog(
+            CatalogSource(providers=lambda: [], models=lambda provider: [])
+        )
+
+
+def _build_startup_resources() -> StartupResources:
+    """Construct the :class:`~.contract.StartupResources` graph, preferring
+    framework-owned pieces and falling back to minimal placeholders. The
+    credential graph stays an empty placeholder bag — the concrete vault is
+    consulted directly by the session assembly."""
+    return StartupResources(
+        settings=_load_default_settings(),
+        auth={},
+        models=_load_model_catalog(),
+    )
+
+
+def _resolve_resources(ctx: BootContext) -> BootContext:
+    """Best-effort assembly of the startup resource graph."""
+    return replace(ctx, resources=_build_startup_resources())
+
+
+#: Stage 4 — resolve the settings/auth/model graph (degrade-to-empty).
+resolve_resources: Final[Stage] = Stage(name="resolve-resources", apply=_resolve_resources)
+
+
+def _select_runner(ctx: BootContext) -> BootContext:
+    """Marker / tracing stage for runner selection. The real dispatch is
+    performed by :mod:`~.boot` after the pipeline so the chosen runner can
+    own the process exit code; this stage keeps the ordered pipeline a
+    faithful description of the launch sequence."""
+    return ctx
+
+
+#: Stage 5 — tracing no-op for runner selection.
+select_runner_stage: Final[Stage] = Stage(name="select-runner", apply=_select_runner)
+
+
+# ---------------------------------------------------------------------------
+# The pipeline + fold
+# ---------------------------------------------------------------------------
+
+#: The launch pipeline, in execution order. Folded by :func:`run_stages`.
+STAGES: Final[tuple[Stage, ...]] = (
+    locate_workspace,
+    upgrade_stage,
+    build_invocation,
+    resolve_resources,
+    select_runner_stage,
+)
+
+
+async def run_stages(
+    initial: BootContext,
+    stages: Sequence[Stage] = STAGES,
+) -> BootContext:
+    """Fold an ordered list of :class:`~.contract.Stage` transforms over an
+    immutable :class:`~.contract.BootContext`.
+
+    Each stage receives the current context and returns its successor; the
+    result of one stage is the input to the next. Awaits every stage result
+    so async ordering is deterministic. The input ``initial`` is never
+    mutated — stages produce new contexts via :func:`dataclasses.replace`.
+
+    :param initial: the seed context (argv + workspace + brand + placeholder
+        fields)
+    :param stages: the ordered transforms to apply; defaults to :data:`STAGES`
+    :returns: the fully-resolved context after every stage has run
+    """
+    ctx = initial
+    for stage in stages:
+        result = stage.apply(ctx)
+        ctx = await result if inspect.isawaitable(result) else result
+    return ctx

induscode/boot/upgrade/__init__.py

@@ -0,0 +1,36 @@
+"""Upgrade subsystem — public barrel (port of TS ``src/boot/upgrade``).
+
+Surfaces the ordered, idempotent profile-upgrade registry and its driver.
+Boot consumers import :func:`apply_upgrades` to run pending one-time
+migrations and the :data:`UPGRADES` registry / :class:`Upgrade` shape for
+inspection and testing. The marker-file bookkeeping is an internal detail of
+the driver and is not re-exported.
+
+Port note: the TS barrel also exported ``projectTranscriptDirName`` (the
+per-cwd transcript-dir encoder step 2 used). The Python steps are documented
+no-ops on the fresh ``~/.pindusagi`` root (see :mod:`.upgrades`), so the
+encoder has no consumer and is not ported.
+"""
+
+from __future__ import annotations
+
+from .apply import UpgradeReport, apply_upgrades
+from .upgrades import (
+    UPGRADES,
+    Upgrade,
+    fold_credentials,
+    relocate_binaries,
+    rename_prompt_dir,
+    reshelve_transcripts,
+)
+
+__all__ = [
+    "UPGRADES",
+    "Upgrade",
+    "UpgradeReport",
+    "apply_upgrades",
+    "fold_credentials",
+    "relocate_binaries",
+    "rename_prompt_dir",
+    "reshelve_transcripts",
+]

induscode/boot/upgrade/apply.py

@@ -0,0 +1,125 @@
+"""Upgrade driver — folds the ordered :data:`~.upgrades.UPGRADES` registry
+over a :class:`~induscode.workspace.Workspace`, exactly once per step.
+
+Port of TS ``src/boot/upgrade/apply.ts``. The driver is the only place that
+knows about the *marker file*: a small JSON record under the profile
+directory listing the ids of upgrades that have already run
+(``.upgrade-state.json`` with the ``{"appliedIds": [...]}`` shape — kept
+byte-compatible with the TS app since this app owns the file). Each registry
+step is skipped if its id is present in the marker; otherwise it is applied
+and, on success, its id is appended and the marker is persisted. A step that
+raises is *not* recorded (so it is retried next launch) and is reported as a
+warning rather than aborting the remaining steps — one bad migration must
+never wedge startup.
+
+The result is purely informational: :attr:`UpgradeReport.applied` lists ids
+run *this* invocation (empty on an already-current profile), and
+:attr:`UpgradeReport.warnings` carries human-readable notes for any step that
+failed. Callers typically log both and continue.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Final
+
+from induscode.workspace import Workspace
+
+from .upgrades import UPGRADES
+
+__all__ = [
+    "UpgradeReport",
+    "apply_upgrades",
+]
+
+#: Basename of the marker file recording which upgrade ids have been applied.
+_MARKER_FILENAME: Final[str] = ".upgrade-state.json"
+
+
+@dataclass(frozen=True, slots=True)
+class UpgradeReport:
+    """The outcome of an :func:`apply_upgrades` pass.
+
+    - ``applied``  — ids of upgrades that ran successfully *this* invocation,
+      in apply order. Empty when the profile was already current.
+    - ``warnings`` — one entry per step that raised, naming the step and its
+      error. Non-fatal: applying continues past a failed step.
+    """
+
+    #: Ids successfully applied during this call, in order.
+    applied: list[str]
+    #: Human-readable notes for steps that failed (non-fatal).
+    warnings: list[str]
+
+
+def _marker_path(ws: Workspace) -> Path:
+    """Absolute path of the marker file inside the profile directory."""
+    return Path(ws.profile_dir) / _MARKER_FILENAME
+
+
+def _read_applied_ids(ws: Workspace) -> set[str]:
+    """Read the set of already-applied ids from the marker file. A missing,
+    unreadable, or malformed marker is treated as "nothing applied yet" so a
+    corrupted marker degrades to re-attempting (idempotent) steps rather than
+    crashing."""
+    try:
+        parsed = json.loads(_marker_path(ws).read_text(encoding="utf-8"))
+        ids = parsed.get("appliedIds") if isinstance(parsed, dict) else None
+        if not isinstance(ids, list):
+            return set()
+        return {item for item in ids if isinstance(item, str)}
+    except Exception:
+        return set()
+
+
+def _write_applied_ids(ws: Workspace, applied_ids: set[str]) -> None:
+    """Persist the marker file with the given applied ids, creating parents
+    if needed. Order is the registry order for the ids present, so the file
+    reads as the apply history."""
+    ordered = [step.id for step in UPGRADES if step.id in applied_ids]
+    # Carry through any ids the registry no longer knows (forward compat).
+    ordered.extend(sorted(applied_ids - set(ordered)))
+    state = {"appliedIds": ordered}
+    path = _marker_path(ws)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(f"{json.dumps(state, indent=2)}\n", encoding="utf-8")
+
+
+def _describe_error(error: BaseException) -> str:
+    """Render a raised value as a single-line message for a warning."""
+    text = str(error)
+    return text if text else type(error).__name__
+
+
+async def apply_upgrades(ws: Workspace) -> UpgradeReport:
+    """Apply every not-yet-applied upgrade in :data:`UPGRADES`, in registry
+    order, recording each success in the marker file so it never runs again.
+
+    Steps already named in the marker are skipped. A step that raises is
+    recorded as a warning, left unmarked (so it is retried on a later
+    launch), and does not block the remaining steps. The marker is rewritten
+    after each success, so a crash mid-pass still preserves the progress made
+    so far.
+
+    :param ws: the resolved, absolute on-disk layout to upgrade
+    :returns: the ids applied this pass and any non-fatal warnings
+    """
+    already_applied = _read_applied_ids(ws)
+    applied: list[str] = []
+    warnings: list[str] = []
+
+    for upgrade in UPGRADES:
+        if upgrade.id in already_applied:
+            continue
+        try:
+            await upgrade.apply(ws)
+            already_applied.add(upgrade.id)
+            applied.append(upgrade.id)
+            # Persist after each success so partial progress survives a crash.
+            _write_applied_ids(ws, already_applied)
+        except Exception as error:  # noqa: BLE001 — reported, never fatal
+            warnings.append(f'upgrade "{upgrade.id}" failed: {_describe_error(error)}')
+
+    return UpgradeReport(applied=applied, warnings=warnings)

induscode/boot/upgrade/upgrades.py

@@ -0,0 +1,136 @@
+"""Upgrade registry — the ordered, idempotent catalog of one-time profile
+migrations.
+
+Port of TS ``src/boot/upgrade/upgrades.ts``, under the port plan's locked
+migration decision: the Python build's profile root (``~/.pindusagi``)
+**starts empty** — no TS-era legacy layout (``oauth.json`` + embedded
+``apiKeys``, loose ``*.jsonl`` transcripts, a ``tools/`` binary dir, a
+``commands/`` template dir) can ever exist under it. The migration
+*mechanism* is therefore kept fully exercisable (registry → marker-file
+driver → idempotence pinned by the boot tests), while the four TS steps are
+registered as **documented no-ops**:
+
+- their :attr:`Upgrade.id` strings are preserved **verbatim** so the ids stay
+  reserved — a future step can never accidentally reuse one with different
+  semantics, and a marker file written by this build remains meaningful;
+- their bodies perform no filesystem work (each detects "nothing legacy can
+  exist here" by construction and returns).
+
+Idempotence contract (every step must honor it, no-op or not):
+
+- Detect "already done" cheaply and return early without side effects.
+- Treat a *missing* source (the thing being migrated from) as success.
+- Never destroy data.
+
+Append new (real) steps to the end of :data:`UPGRADES` — never reorder or
+rename existing ids, as that would re-run already-applied migrations.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass
+
+from induscode.workspace import Workspace
+
+__all__ = [
+    "UPGRADES",
+    "Upgrade",
+    "fold_credentials",
+    "relocate_binaries",
+    "rename_prompt_dir",
+    "reshelve_transcripts",
+]
+
+
+# ---------------------------------------------------------------------------
+# The Upgrade shape
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True, slots=True)
+class Upgrade:
+    """One ordered, idempotent profile-layout upgrade.
+
+    An upgrade is pure data plus one async effect. The registry order is the
+    apply order; :attr:`id` is the durable key recorded in the marker file
+    once :attr:`apply` completes, so it must be stable across releases
+    (renaming an id re-runs the step). :attr:`apply` must be safe to invoke
+    against a profile in any state — fresh, partially-migrated, or
+    fully-migrated.
+    """
+
+    #: Durable identifier recorded once this step has run. Never rename.
+    id: str
+    #: One-line human summary for logs and verbose output.
+    describe: str
+    #: Perform the upgrade against the resolved workspace (idempotent).
+    apply: Callable[[Workspace], Awaitable[None]]
+
+
+# ---------------------------------------------------------------------------
+# The four TS migrations, registered as documented no-ops
+# ---------------------------------------------------------------------------
+
+
+async def _noop(ws: Workspace) -> None:
+    """The shared no-op body: the legacy source this step migrated from
+    belongs to the TS-era ``~/.indusagi/agent`` layout and cannot exist under
+    the fresh ``~/.pindusagi`` root, so there is nothing to detect and
+    nothing to move. (Idempotent by construction.)"""
+    del ws
+
+
+#: TS step 1 — folded a legacy split credential layout (a standalone
+#: ``oauth.json`` plus an ``apiKeys`` block embedded in ``settings.json``)
+#: into the single consolidated 0600 ``auth.json``. No-op here: the Python
+#: profile root never carried the split layout; the disk vault
+#: (:mod:`induscode.boot.auth_vault`) writes the consolidated shape from day
+#: one.
+fold_credentials = Upgrade(
+    id="fold-credentials-into-secure-auth-file",
+    describe="Consolidate legacy oauth.json + settings.apiKeys into a 0600 auth.json (no-op on the fresh root)",
+    apply=_noop,
+)
+
+#: TS step 2 — relocated loose ``*.jsonl`` transcripts written directly under
+#: the profile root into the per-cwd ``sessions/`` tree. No-op here: the
+#: conductor's filesystem backend has always written ``.ndjson`` transcripts
+#: under the cwd-scoped sessions directory.
+reshelve_transcripts = Upgrade(
+    id="reshelve-loose-transcripts-into-sessions-dir",
+    describe="Move loose session .jsonl files under the profile root into sessions/<cwd>/ (no-op on the fresh root)",
+    apply=_noop,
+)
+
+#: TS step 3 — moved the managed ``fd`` / ``rg`` helper binaries from the
+#: legacy ``tools/`` directory into ``bin/``. No-op here: the Python layout
+#: provisions helpers under ``bin/`` directly (``tools_dir`` == ``bin_dir``).
+relocate_binaries = Upgrade(
+    id="relocate-managed-helper-binaries-to-bin",
+    describe="Move managed fd/rg helper binaries from the legacy tools/ dir into bin/ (no-op on the fresh root)",
+    apply=_noop,
+)
+
+#: TS step 4 — renamed the legacy ``commands/`` template directory to
+#: ``prompts/``. No-op here: the Python layout creates ``prompts/`` directly.
+rename_prompt_dir = Upgrade(
+    id="rename-legacy-commands-dir-to-prompts",
+    describe="Rename the legacy commands/ template directory to prompts/ (no-op on the fresh root)",
+    apply=_noop,
+)
+
+
+# ---------------------------------------------------------------------------
+# The ordered registry
+# ---------------------------------------------------------------------------
+
+#: The ordered list of upgrades. Apply order is array order; ids are the
+#: durable marker keys. Append new steps to the end — never reorder or rename
+#: existing ids.
+UPGRADES: tuple[Upgrade, ...] = (
+    fold_credentials,
+    reshelve_transcripts,
+    relocate_binaries,
+    rename_prompt_dir,
+)

induscode/briefing/__init__.py

@@ -0,0 +1,115 @@
+"""Briefing subsystem — public barrel.
+
+Re-exports the FROZEN prompt contract: the declarative system-prompt pipeline
+(:class:`BriefingSection` over a :class:`BriefingContext`, composed by
+:func:`compose_briefing`), the single-pass ``$arg`` macro model
+(:class:`Macro`, :class:`MacroScope`, :data:`MacroToken`), and the
+Agent-Skills capability cards (:class:`SkillCard` parsed from a ``SKILL.md``).
+
+Port note: the TS barrel additionally re-exported the table-driven SGR
+machine, the HTML-transcript color layer (``ExportTheme`` / ``ThemeBridge`` /
+``LuminanceLut``), and the publish surface from ``briefing/contract``. In the
+Python build those types belong to ``induscode.transcript_export`` (ported
+separately); this barrel carries only the briefing-owned vocabulary plus the
+shared :class:`BriefingFault`. Consumers import the briefing surface from
+``induscode.briefing`` rather than reaching into individual modules.
+"""
+
+from .compose import BRIEFING_SECTIONS, compose_briefing
+from .contract import (
+    SKILL_DESCRIPTION_LIMIT,
+    SKILL_NAME_LIMIT,
+    AgentState,
+    AgentTool,
+    AllToken,
+    Briefing,
+    BriefingContext,
+    BriefingFault,
+    BriefingFaultKind,
+    BriefingInputs,
+    BriefingSection,
+    ContextDoc,
+    ImageContent,
+    LiteralToken,
+    Macro,
+    MacroOrigin,
+    MacroScope,
+    MacroToken,
+    MacroTokenKind,
+    PositionalToken,
+    SkillCard,
+    SkillDiagnostic,
+    SkillFrontmatter,
+    SkillLoad,
+    SkillOutcomeKind,
+    SliceToken,
+    SubagentBrief,
+    TextContent,
+    briefing_fault,
+)
+from .macros import (
+    FrontmatterSplit,
+    apply_macros,
+    build_macro_scope,
+    expand_invocation,
+    load_macros,
+    read_macro_file,
+    resolve_tokens,
+    scan_macro_body,
+    set_legacy_macro_reporter,
+    split_frontmatter,
+)
+from .skills import (
+    SkillRoot,
+    gather_skill_cards,
+    load_skill_cards,
+    model_invocable_cards,
+)
+
+__all__ = [
+    "AgentState",
+    "AgentTool",
+    "AllToken",
+    "BRIEFING_SECTIONS",
+    "Briefing",
+    "BriefingContext",
+    "BriefingFault",
+    "BriefingFaultKind",
+    "BriefingInputs",
+    "BriefingSection",
+    "ContextDoc",
+    "FrontmatterSplit",
+    "ImageContent",
+    "LiteralToken",
+    "Macro",
+    "MacroOrigin",
+    "MacroScope",
+    "MacroToken",
+    "MacroTokenKind",
+    "PositionalToken",
+    "SKILL_DESCRIPTION_LIMIT",
+    "SKILL_NAME_LIMIT",
+    "SkillCard",
+    "SkillDiagnostic",
+    "SkillFrontmatter",
+    "SkillLoad",
+    "SkillOutcomeKind",
+    "SkillRoot",
+    "SliceToken",
+    "SubagentBrief",
+    "TextContent",
+    "apply_macros",
+    "briefing_fault",
+    "build_macro_scope",
+    "compose_briefing",
+    "expand_invocation",
+    "gather_skill_cards",
+    "load_macros",
+    "load_skill_cards",
+    "model_invocable_cards",
+    "read_macro_file",
+    "resolve_tokens",
+    "scan_macro_body",
+    "set_legacy_macro_reporter",
+    "split_frontmatter",
+]