fix(create-objectstack): ship a .gitignore in scaffolded projects

[os-zhuang]

Found while fixing #3110 (PR #3119) — out of scope there, filed and fixed separately.

The bug

npx create-objectstack myapp produces a project with no .gitignore, so node_modules/ and .env are un-ignored for every new user.

npm pack / pnpm pack strip .gitignore from a tarball unconditionally, at every depth. The blank template committed one at src/templates/blank/.gitignore and tsup faithfully copied it to dist/templates/blank/.gitignore, but files: ["dist"] publishing dropped it on the way to the registry. The file was present in the repo, present in every local build, and absent from a real scaffold — which is why nothing caught it.

Verified against the published 15.1.1 tarball (not inferred):

$ tar tzf create-objectstack-15.1.1.tgz | grep templates/blank
package/dist/templates/blank/.dockerignore     ← ships
package/dist/templates/blank/Dockerfile
...                                            ← .gitignore absent

The strip list is .gitignore and .npmrc, not "every dotfile" — probed both packers directly. .dockerignore and .env.example pack fine, so .dockerignore is left literal rather than renamed on a guess.

The .env half

The template .gitignore never listed .env either. The template README has users write real secrets into one (POSTGRES_PASSWORD, OS_AUTH_SECRET, OS_SECRET_KEY), and docker-compose.yml:3 calls that file "never committed" — but only the prose said so; .dockerignore was the only file that listed it. So the restored rules now cover .env / .env.*.

The fix

Commit the template as _gitignore (a name npm does not strip) and restore the real name at copy time via a TEMPLATE_FILE_ALIASES map in the new template-copy.ts. copyDir moves there so a test can import it without running the CLI (index.ts calls program.parse() on import) — the same reason pkg-utils.ts exists.

Verification

Built, packed, installed the tarball into a clean project, and ran the real binary:

  Created files:
    + .gitignore          ← was absent
    + .dockerignore
    ...

$ git add -A     # after creating node_modules/ and a .env with secrets
  node_modules staged: 0   .env staged: 0

The ratchet

template-consistency.test.ts packs the real package, scaffolds from the extracted tarball with the real copy logic, and asserts every template file lands under its intended name. A source-level assertion would be false green here — the file only vanishes at publish. Reading the repo's own dist/ would be false green too: turbo's test task only dependsOn: ["^build"] (not its own build) and excludes dist/** from its inputs, so dist/ is routinely absent or stale, and a pass on it would be cached.

Both halves are guarded independently — confirmed by reverting each and watching it go red:

reverted	result
rename _gitignore → .gitignore (the original bug)	2 tests red, error text names the required alias
drop the alias mapping	1 test red

The file-set check alone cannot catch the second case (it applies the alias map to both sides, so an empty map agrees with itself on _gitignore) — which is why the literal .gitignore assertion is separate and commented as non-redundant.

Adding .npmrc or any other stripped dotfile to the template in future fails the same ratchet with a message naming the fix.

🤖 Generated with Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
spec	Ready	Preview, Comment	Jul 17, 2026 1:30pm

[github-actions]

📓 Docs Drift Check

This PR changes 1 package(s): create-objectstack.

7 hand-written doc(s) reference the affected code and may need an implementation-accuracy re-verification:

• content/docs/ai/skills-reference.mdx (via create-objectstack)
• content/docs/ai/skills.mdx (via create-objectstack)
• content/docs/getting-started/index.mdx (via create-objectstack)
• content/docs/getting-started/your-first-project.mdx (via create-objectstack)
• content/docs/plugins/packages.mdx (via create-objectstack)
• content/docs/releases/v15.mdx (via create-objectstack)
• content/docs/releases/v9.mdx (via create-objectstack)

Advisory only. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs origin/main → pass the list as args.docs.