[immakermatty]

Part 1 of 3 of M2 in plan DEV-6662 (#359): personal module creation, lazurio module create personalspace/<slug>. This PR is the generator core only; no command uses it yet. PR 2 (the checks and the dry run) and PR 3 (the real run) stack on this branch.

Why

The Operator decided on 2026-10-13 (root decision 0171, addendum of 2026-10-13) that a person's own modules live in their Personalspace as private repositories on their own GitHub account, and that the Platform holds the one module generator (root 0167): the root's planModuleScaffold and its stack templates move here, the personal form now, the Organization form under #267. No hosted Environment can run lazurio module create today (#267).

What

• src/modules/scaffold.ts: the pure planner ported from HumanAndMachines/Lazurio lazurio/module-scaffold-lib.mjs at a5615be0: the same six stacks, slug rules, placeholder engine, tree hash, slug-derived port choice, slot insert and refusal codes, in strict TypeScript with English messages.
• The templates (src/modules/templates/, 46 files from the root byte for byte plus _personal/AGENTS.md.tmpl) are embedded in the compiled executable as text through src/modules/scaffold-templates.ts. Every file ends in .tmpl, so none of them is an input of this repository's TypeScript, Biome or tests. Provenance and each deviation are in src/modules/templates/README.md.
• An Organization's plan is the root's byte for byte. The test holds the root's tree hash of every stack at a5615be0. A compiled binary run from / produces the same hash, so the templates really are embedded.
• The personal form (owner: {kind: "personal", login}):
  • company is the person's login. The runtime id is personalspace-<slug>-v1, not SHAPING's <login>-<slug>-v1: the catalog shows a runtime id as the app's display.id, and no output of a personal module names its owner (the rule the Personalspace tests enforce; a test checks that the catalog of generated personal modules never contains the login);
  • the slot is private to its owner: default_access: "private", required_roles: ["owner"], git.url git@github.com:<login>/<slug>.git, status: "active", no Teams (teams_not_allowed);
  • the _personal layer gives the module its own AGENTS.md.
  • Four placeholders (owner_label, pool_label, module_name, verify_command) replace the root's Organization-only wording. For an Organization they render the root's exact words.
• The reserved personal lease range: 23000–23099 (personalModulePortPool), beside the Environment's own ports (environmentPorts). The reasons are in F52 and below.
• The gateway's labels join the reserved slugs: t3code, mausbot, mausbot-webhook, browser, oauth2, api and well-known. A module's hostname is its slug.
• Docs: the decision F52 in docs/decisions.md.

The chosen port range and why

23000–23099 is 100 ports, the size of an Organization's pool. It is chosen to be:

• Below every Organization pool on record. Those start at 24000 and grow upward in blocks of 100: the root manual's example is 24000–24099 and the Organization template's 24900–24999. Machines' example Organization uses 20100–20199.
• Clear of the Environment's own ports: 443 and 4180 (gateway), 20000 (Launchpad), 3773 (T3 Code), 4102 and 4103 (MausBot and its webhook), 4848 and 9222 (browser), 4789 (Executor) and 4174 (resident Launchpad).
• Below every ephemeral range: Linux starts at 32768, macOS and Windows at 49152.

Deliberately not here

• No command, no I/O, no CLI exposure (PRs 2 and 3).
• The Organization form of the command stays in the root until Installed Platform CLI lacks module create/setup required by Organization skills #267.
• No lazurio module setup conformance checks (Installed Platform CLI lacks module create/setup required by Organization skills #267).
• No change to the Launchpad (M1 is separate work).

Verification

• bun run check:static: lint, typecheck, the public guard, the proof build and its smoke all pass.
• bun test --parallel=4 --timeout=20000: 2620 pass, 7 skip, 0 fail across 239 files.
• New tests/module-scaffold.test.ts (23 tests):
  • the root's planner tests on the port;
  • the root's tree hashes;
  • the personal form against the template's own placeholders and example slot (tests/fixtures/personalspace-template.ts, the template's main cf50036);
  • every stack's runtime and preparation read by the Platform's own readers;
  • every generated personal module listed by the catalog as personalspace/<module>: Bun apps executable, python-uv listed with default-app-invalid as the plan warns, none without an app;
  • the embedded templates equal to their directory.

Risks

• Two generators until Installed Platform CLI lacks module create/setup required by Organization skills #267. A change to a stack's files belongs in the root and here, or they drift. The golden hashes make drift visible here.
• Organization pools never use 23000–23099 only by convention today. Every pool on record is outside it. Organization pools: refuse a module_port_pool overlapping the reserved personal range 23000-23099 HumanAndMachines/Lazurio#545 asks the root doctor and the Organization template's check to refuse an overlap.

🤖 Generated with Claude Code

Note

Add Platform module generator for personal-form modules (M2 1/3)

Adds a Platform-owned scaffold planner plus a full set of embedded stack templates (Astro, Astro Starlight, Bun service, Vite React, Python uv, and none). This is the personal-module third of milestone 2.

• scaffold.ts builds the module manifest, workspace slot, port lease (personal pool 23,000–23,099), and renders templates with placeholder substitution. It validates owners, teams, versions, pools, ports, slugs, and template paths, and raises stable ModuleScaffoldError codes.
• scaffold-templates.ts exposes the immutable template catalog with CRLF-to-LF normalization; templates.d.ts types .tmpl imports.
• Generated apps share one pattern: listener lookup through module-kit, exit status 2 on missing/invalid listener configuration, health path from Lazurio runtime metadata, strict ports, and no .env loading.
• Python apps run a threaded HTTP server with Host-header allowlist (403 for foreign hosts), and generated start-contract tests verify health, foreign-host rejection, and SIGTERM exit 0 across stacks.
• Decision record for F52 and template documentation are added in decisions.md and the template README.

^{Macroscope summarized b61f447.}

[agentrozjedemeai]

Exact-head review of b61f447 (DEV-6662 M2 1/3). The focused scaffold suite passes (23/23), check:static passes, diff --check is clean, and CI is green. No CLI is introduced by this PR; the findings concern the new pure generator itself.

Changes requested:

1. [P1] Constrain the personal pool at the generator boundary. planModuleScaffold accepts a personal owner with any otherwise-valid PortPool: owner={kind:"personal",login:"example"}, slug="notes", stack="bun-service", pool={start:24000,end:24099} returns lease 24052. normalizePool (src/modules/scaffold.ts:700-715) checks only generic port validity; choosePort then uses that range (744-785). This permits a personal module plan to lease an Organization-pool port, contrary to F52/0171 and the documented reserved range. The template PR validates its own manifest, but this public core has no such check and callers can pass an older or unvalidated manifest. Refuse any personal pool not wholly within 23000-23099 (including an explicit --port via that pool), and add negative tests to this suite.
2. [P2] Align the personal login validator with the Personalspace contract. normalizeOwner accepts login "ab-" (src/modules/scaffold.ts:142,611-626), generating git@github.com:ab-/notes.git; the template validator isValidGitHubLogin rejects that owner. Please reject trailing-hyphen logins here too and test the boundary.

These are independent of #396/#399; please fix on a new head and request a fresh exact-head review.

[agentrozjedemeai]

The previous P1/P2 findings are resolved: personal pools are bounded to 23000–23099 before any lease (including an explicit port), and both owner kinds use the GitHub login pattern with no trailing hyphen. I checked the new boundary cases and template/owner paths at this exact head. Local: module-scaffold 23 pass, 0 fail; check:static passes; git diff --check clean. GitHub head checks pass; no unresolved threads. @immakermatty APPROVED for this exact commit; no merge performed.