NeoHaskell

The Layout library is a beginner-friendly wrapper around prettyprinter used for constructing and rendering formatted text. It uses a Blueprint abstraction to represent a layout plan that is only rendered to Text when explicitly requested.

Core Mental Model

1. Construct: Use functions like text, stack, or joinWords to build a Blueprint.
2. Annotate (Optional): Attach metadata to parts of the layout using withAnnotation.
3. Render: Convert the Blueprint into Text using render, renderWithWidth, or renderWith (for custom RenderOptions).

Quick Start

import Layout (Blueprint)
import Layout qualified

-- Simplest possible use:
greeting :: Text
greeting =
  [Layout.text "Hello,", Layout.text "world!"]
    |> Layout.joinWords
    |> Layout.render
-- => "Hello, world!"

-- Stacking lines with custom width:
twoLines :: Text
twoLines =
  [Layout.text "line one", Layout.text "line two"]
    |> Layout.stack
    |> Layout.renderWithWidth 40
-- => "line one\nline two"

The Layout Library is a beginner-friendly wrapper around the prettyprinter engine, designed to provide structured text layout and automatic line-breaking for Jess. Unlike basic Text primitives, this library allows you to build composable 'layout plans' (blueprints) that can be rendered in a single pass with consistent formatting.

Key features include:

• Automatic Line-Breaking: Sensible defaults (e.g., 80 columns) with smart layout decisions.
• Separation of Concerns: You build layout structures in pure code and only render them to text at the 'edge' of your application.
• Beginner-Friendly API: Uses plain English verbs and nouns instead of complex operators or low-level prettyprinter internals.

Common use cases include generating formatted source code for the transpiler, formatting parser diagnostics (with caret pointers and aligned columns), and creating structured CLI output like build summaries and progress tables.

Codemap regeneration is a maintainer-triggered process used to update documentation artifacts (like codemap/MAP.md and signatures) on a contributor's Pull Request.

To ensure security, the process is split into two distinct phases:

1. Generation (Untrusted): A job runs in a restricted environment with contents: read permissions and no access to secrets. It executes ./dev codemap and produces an artifact containing only allowlisted files and a manifest.
2. Publication (Trusted): A separate job, gated by a GitHub Environment requiring maintainer approval, uses a dedicated token (CODEMAP_PUBLISH_TOKEN) to push the updated files back to the contributor's branch. This job runs no contributor-provided code and treats the PR branch as data only.

Key Security Constraints:

• The process only works for PRs where "Allow edits by maintainers" is enabled.
• It only supports user-owned forks (organization-owned forks are rejected).
• It will never create a fallback PR; it either updates the existing branch or fails loudly.

# The generation phase runs this command to produce the codemap
./dev codemap

NeoHaskell allows you to define specific authentication and authorization policies for individual commands, rather than applying a global authentication requirement to all endpoints. This follows the same pattern used for Queries.

Mental Model

• Whitelist by default: If you do not define a canAccess function for a command, it defaults to authenticatedAccess, meaning it requires a valid JWT.
• Colocation: The canAccess declaration should be placed in the same module as your command's decide logic.
• Error Types: Access control failures return a CommandAuthError, which uses the following constructors:
  • Unauthenticated: No valid token provided.
  • Forbidden: Token is valid, but the user is not allowed to perform this action.
  • InsufficientPermissions [Text]: The user lacks one or more required permissions (the list contains the missing permission names).

Available Permission Helpers

You can use these helpers to define your canAccess logic:

• publicAccess: Allows anyone (including anonymous users) to execute the command.
• authenticatedAccess: Requires a valid JWT.
• requirePermission <permission_name>: Requires a specific permission.
• requireAnyPermission [<permission_names>]: Requires at least one of the listed permissions.
• requireAllPermissions [<permission_names>]: Requires all of the listed permissions.

-- Example: A public command for feedback
canAccess = publicAccess

decide :: FeedbackData -> CommandResult
decide data = ...

-- Example: An admin-only command
canAccess = requirePermission "admin:delete"

decide :: AccountId -> CommandResult
decide id = ...

NeoHaskell manages per-stream subscriptions (using PostgreSQL LISTEN) by tying the lifetime of a database connection to a SubscriptionId.

When a stream is subscribed to, a connection is allocated. When the subscription is removed (via unsubscribe or system teardown), the connection is automatically released through a single cleanup path in removeSubscription. This prevents connection leaks during high-churn subscribe/unsubscribe cycles.

Key Lifecycle Behaviors:

• Single Funnel: All removal routes (explicit unsubscription or system close-time teardown) go through removeSubscription to ensure a single release path.
• Best-Effort Cleanup: If a connection fails to release, the error is logged as a warn, but the unsubscription proceeds. This prevents cleanup failures from blocking the unsubscription process.
• Idempotent Removal: Calling removeSubscription multiple times for the same ID is safe; the first call executes the cleanup, and subsequent calls find no remaining cleanup task and return unit without error.