Application Entrypoints

architecture.application-entrypoints documents the repository policy that classifies application entrypoints and enforces the dsh launcher as the approved path for application startup.

Purpose and Scope

This page covers the behavior verified by applicationEntrypointViolations: package-level bin declarations, executable source files, application launcher scripts and wrappers, and root demo scripts. Its central rule is that applications must be launched through apps/cli/src/bin.ts and, where applicable, an explicit dsh profile or an explicitly classified in-process demo.

The available source material is a test specification for the verifier. It demonstrates the accepted repository inventory and the rejection messages for invalid layouts and launch commands. The verifier implementation, its package registration, the CLI implementation, configuration defaults, and any runtime behavior beyond these checks are not present in the supplied source grounding; implementation details not found in source are therefore not inferred here.

Overview

The entrypoint policy prevents application packages from becoming independent executables. Instead, application startup is centralized behind the dsh launcher and its application profiles. The tests establish four related constraints:

• A package-level bin field is forbidden for an application package because it bypasses the launcher.
• Executable source files must be classified as application, build, or test sources.
• Application launcher scripts and wrappers must invoke apps/cli/src/bin.ts, rather than launching a package entry directly or serving through another command without the launcher.
• Root demo scripts need an explicit dsh or in-process classification before they are accepted.

The policy applies broadly enough to catch executable files in package sources, application workspaces, the CLI workspace, the repository root, and private Python application carriers. This indicates that privacy or language/runtime packaging does not exempt a workspace from the repository-level launcher rule.

Architecture

The source-grounded architecture is a validation boundary rather than a runtime component graph:

• applicationEntrypointViolations scans a repository fixture or repository root.
• The repository layout and package metadata provide the inputs being classified.
• apps/cli/src/bin.ts is the required launcher target for application launcher scripts and wrappers.
• dsh profiles provide the approved application selection mechanism.
• The verifier returns an array of human-readable violation strings; an empty array represents an accepted inventory.

The supplied material does not include the verifier implementation, so the internal scan algorithm and exact classification rules cannot be documented beyond the observed test behavior.

Enforced Rules

Package-level application binaries are prohibited

An application package containing a bin mapping is rejected with the message:

package bin bypasses the dsh launcher; applications use apps/cli profiles

The policy therefore treats package metadata as an entrypoint surface, not merely executable source files. A package cannot avoid the launcher requirement by declaring a command through its package manager metadata.

Executable source must be classified

The tests use a Node shebang (#!/usr/bin/env node) as the executable marker. An unclassified executable is rejected in all of the following locations:

• packages/example/app/src/bin.ts
• apps/example/rogue.mjs
• rogue.mjs at the repository root
• apps/rogue/src/bin.ts
• apps/cli/src/runtime-bootstrap.ts
• packages/sdk/rogue-python-runtime/src/bin.ts

Each case returns the same policy message:

executable source has no application/build/test classification

This consistency is important operationally: adding a new executable is not sufficient by itself. The executable must also belong to an accepted application, build, or test classification. The tests do not reveal the accepted classification syntax or metadata, so those details remain implementation details not found in source.

Application launcher scripts must use the CLI launcher

A script recognized as an application launcher must launch apps/cli/src/bin.ts. A root start:web script that directly runs a package entry is rejected with both of these messages:

• package.json scripts.start:web: application launcher script must launch apps/cli/src/bin.ts
• package.json scripts.start:web: application launcher script must not launch a package entry directly

The first message identifies the required target. The second expresses the architectural prohibition independently: even if a package entry is executable, it is not an acceptable application boundary.

Wrapper scripts cannot bypass the launcher

A dev:web script that invokes tsx scripts/dev-web.ts --poll, while the wrapper itself runs vite build --watch, is rejected because the wrapper does not launch apps/cli/src/bin.ts.

A classified demo wrapper is also not automatically trusted. When scripts/demo-ptc.mjs launches packages/example/app/src/bin.ts directly, the verifier reports:

• application launcher wrapper must launch apps/cli/src/bin.ts
• application launcher wrapper must not launch a package entry directly

Classification identifies a script's role; it does not grant permission to violate the launcher target rule.

Root demos need explicit launch classification

A root script named demo:new-app that invokes dsh --profile new-app is still rejected when it has no explicit dsh or in-process classification:

package.json scripts.demo:new-app: demo launcher has no explicit dsh or in-process classification

This distinguishes command content from policy classification. The command visibly uses dsh, but the demo script must also declare how the verifier should classify its launch role.

Validation Flow

The observed validation flow is:

1. The verifier receives a repository root.
2. It inspects package metadata and source layout.
3. It identifies executable sources and launcher-like scripts.
4. It checks whether each executable has an accepted application, build, or test classification.
5. It checks whether application launchers and wrappers target apps/cli/src/bin.ts rather than package entries.
6. It checks whether demo launchers have an explicit dsh or in-process classification.
7. It returns all violations as strings, preserving the path and, for package scripts, the script key.

The repository inventory test establishes the expected steady state: calling applicationEntrypointViolations(resolve(import.meta.dirname, '..')) for the repository under test returns an empty array.

Error Reporting

Violation messages are deliberately path-oriented. Source violations identify the relative file path, while package-script violations identify both package.json and the script name, for example package.json scripts.start:web or package.json scripts.demo:new-app.

The tests assert exact arrays and exact message order for each fixture. Consumers of the verifier should therefore treat the returned strings as stable diagnostic output unless the verifier's contract is intentionally changed. No exception behavior, logging behavior, or recovery behavior is shown in the supplied source.

Test-Driven Contract

The test suite provides the clearest contract currently available:

• The real repository launcher inventory must pass with [].
• A package bin declaration must fail.
• An unclassified executable must fail regardless of whether it is in a package, app, CLI workspace, repository root, or private Python carrier.
• A launcher wrapper must target apps/cli/src/bin.ts.
• A launcher wrapper must not directly invoke a package entry.
• A root demo must declare an explicit dsh or in-process classification.

Fixtures are created in temporary directories using mkdtempSync, then cleaned after each test with recursive forced removal. This isolates each rule and ensures that failures are attributable to the fixture's single policy violation.

Usage Examples

No code example available beyond the supplied source grounding. The grounding contains test excerpts, but it does not provide a runtime File Reference Base URL required for compliant source attribution of code blocks.

Configuration and Integration Points

The accepted classification keys, package naming conventions, and configuration schema are not shown in the supplied source and should be verified in the verifier implementation before being documented.

API Reference

applicationEntrypointViolations(root)

The test suite imports applicationEntrypointViolations from ./verify-application-entrypoints.ts and passes a resolved repository path. The function returns an array of violation strings; an empty array indicates that the inspected repository satisfies the entrypoint policy.

The exact TypeScript signature, synchronous/asynchronous contract, traversal behavior, and error conditions are not shown in the supplied source grounding. Those details are implementation details not found in source and should not be assumed.

Boundary Cases and Operational Notes

Private workspaces are still checked

The private package fixture packages/sdk/rogue-python-runtime demonstrates that private: true does not exempt an executable source from classification. Repository governance is based on entrypoint behavior and location, not only publication status.

The CLI workspace is not exempt

The fixture apps/cli/src/runtime-bootstrap.ts is rejected as an unclassified executable. This prevents the launcher workspace from accumulating additional executable dispatchers that could fragment startup behavior.

Classification and target validation are separate checks

The demo-wrapper test produces two diagnostics: one for the wrong launcher target and one for directly launching a package entry. The separate messages show that a wrapper can violate more than one rule at once, and callers should preserve all returned violations rather than stopping after the first.

Missing implementation details

The supplied source does not establish executable-file discovery rules beyond the tested shebang examples, the complete set of accepted classifications, how scripts are recognized as launchers, how dsh or in-process declarations are encoded, or whether symlinks and generated files are treated specially. These areas require the verifier implementation and repository configuration for authoritative documentation.

Related Links

• For CLI launcher behavior, see the implementation and documentation for apps/cli/src/bin.ts when available.
• For the verifier's complete classification schema, see verify-application-entrypoints.ts.
• For application-specific profiles, see the repository's apps/cli profile configuration when available.