Forge 1.0 API and UX freeze review

• Target release: 1.0.0-rc.1
• Review date: 2026-09-02
• Generator candidate: @rm-industries/create-forge@0.4.0-beta.6
• Content-model candidate: @rm-industries/content-model@0.2.0-alpha.0
• Tracking issue: FGE-093

This review freezes the documented public contracts that the first Forge 1.0 release candidate will validate. A breaking change to any frozen item requires a new release candidate and repetition of the compatibility, security, and production-use gates.

CLI command and options

The executable name is create-forge. npm users invoke the scoped package with npm create @rm-industries/forge@next. The positional destination is optional and defaults to the current directory in --yes mode.

The final help output is stored as an exact inline snapshot in packages/create-forge/src/cli.test.ts. It freezes these public options:

Positive and negative forms of the same Boolean option are mutually exclusive. Unknown options and excess positional arguments are errors. A non-interactive terminal must provide --yes or every generator value explicitly; it never waits for prompts.

Prompt and validation contract

Interactive prompts follow the table order above, ending with installation and Git confirmations. Text defaults match --yes; both confirmations default to enabled. Cancelling any prompt exits unsuccessfully with Project creation cancelled. and does not begin materialization.

Package names follow npm’s new-package rules. Site names must be non-empty. Plain-text metadata rejects control characters. Repository values are empty or owner/repository; canonical URLs are absolute HTTP(S) URLs. Destination paths must be non-empty and cannot traverse a parent, resolve to a filesystem root, or cross symbolic links while copying.

Exit and output contract

Success exits 0. Input, parse, cancellation, conflict, materialization, and ordinary child-process failures exit 1. An interrupted generator exits 130 for SIGINT or 143 for SIGTERM. Help and version exit 0.

Completion output reports the created path, dependency status, Git status, and only the remaining commands. Its installed, skipped, and current-directory forms are exact inline snapshots in packages/create-forge/src/reporter.test.ts. Diagnostics may become clearer after 1.0, but documented wording, parseable structure, and exit behavior cannot change incompatibly in a minor or patch release.

Forge does not emit telemetry or promotional output. NO_COLOR disables ANSI decoration, and removing color does not change wording.

Generated-project and configuration contract

Forge copies one bundled template, including dotfiles and executable modes. .gitignore.template becomes .gitignore. Only these generated values are customized:

• root package and lockfile names, with version 0.0.0 and private: true;
• site.name, site.description, site.author, site.url, and site.repository in src/config/site.ts; and
• deterministic, package-name-derived minute fields in the security and automation workflow schedules.

The v1 site configuration schema is SiteConfig: name, description, author, url, repository, language, socialImage, navigation, and socialLinks. Deployment derives Astro’s site origin and optional base pathname from the canonical URL. Content declarations remain under src/config/content-models/; authored Markdown remains under src/content/articles/; site-level CMS composition remains under src/integrations/sveltia/.

The generator refuses a non-empty destination unless an interactive user confirms it. It backs up overwritten files and rolls back the invocation when copying or customization fails. It never stages or commits generated files. Re-running Forge over an existing project is not an upgrade mechanism.

Package API and metadata assessment

@rm-industries/create-forge exposes the create-forge executable and no documented JavaScript library API. Its published files are the built executable, source map, and bundled template. --version is read from the installed package metadata, so prerelease and stable builds report themselves accurately.

@rm-industries/content-model remains an independently versioned public API with root, Astro, and Sveltia exports. Its semver contract is already defined in the support policy and is not widened by the generator freeze.

No mismatch requiring a breaking change was found. Freezing the reviewed behavior is therefore a documentation-and-test hardening change for the release candidate; it does not itself require a package version increment.

Verification record

• CLI help and completion output are protected by exact snapshots.
• Parsing, validation, prompting, cancellation, process exits, safe copying, rollback, token replacement, and reporting have unit and integration tests.
• The packed-package verification exercises installed --help, --version, and bundled assets outside the workspace.
• The compatibility matrix creates six isolated generated projects across the supported Node lines and Linux/macOS, including current-directory, install/no-install, and Git/no-Git variants.
• Generated output is compared through owned-value assertions and rejection of every unresolved template token; repository quality then runs inside the generated project.

The freeze is complete when this review, its snapshots, the generated-project diff review, and the full pull-request pipeline pass together.