fix(ztd-cli): align scaffold cross-root imports with root aliases

[mk3008]

Summary

• Make generated projects define #libraries/* and #adapters/* alongside the existing #features/* and #tests/* aliases across package.json, tsconfig.json, and vitest.config.ts.
• Update scaffold/template files so imports that cross canonical roots use root aliases instead of deep relative paths.
• Document the root-boundary import policy and cover it with unit tests plus generated-project verification.

Verification

• pnpm --filter @rawsql-ts/ztd-cli test -- init.command.test.ts directoryFinding.docs.test.ts
• pnpm verify:generated-project-mode

Merge Readiness

• No baseline exception requested.
• Baseline exception requested and linked below.

Tracking issue: #778
Scoped checks run: pnpm --filter @rawsql-ts/ztd-cli test -- init.command.test.ts directoryFinding.docs.test.ts; pnpm verify:generated-project-mode
Why full baseline is not required: The pre-commit full baseline (pnpm test) is currently failing in unchanged areas: packages/ztd-cli/tests/agentsPolicy.unit.test.ts, packages/ztd-cli/tests/commandTelemetry.unit.test.ts, and packages/ztd-cli/tests/setupEnv.unit.test.ts. This PR does not modify the related source or test files, and the scoped checks above cover the changed scaffold contract.

CLI Surface Migration

• No migration packet required for this CLI change.
• CLI/user-facing surface change and migration packet completed.

No-migration rationale: CLI commands and flags do not change. The user-visible change is limited to generated project configuration and scaffolded import paths.
Upgrade note: Newly generated projects will expose #libraries/* and #adapters/* aliases and use them for cross-root imports.
Deprecation/removal plan or issue: none
Docs/help/examples updated: Yes. Updated packages/ztd-cli/README.md and packages/ztd-cli/templates/README.md.
Release/changeset wording: Added .changeset/ten-soft-camels-jump.md for @rawsql-ts/ztd-cli as a patch release.

Scaffold Contract Proof

• No scaffold contract proof required for this PR.
• Scaffold contract proof completed.

No-proof rationale: none
Non-edit assertion: Same-root local imports remain relative; the change only standardizes imports that cross canonical roots.
Fail-fast input-contract proof: packages/ztd-cli/tests/init.command.test.ts and packages/ztd-cli/tests/directoryFinding.docs.test.ts now assert alias definitions and generated cross-root imports for #libraries/* and #adapters/*.
Generated-output viability proof: pnpm verify:generated-project-mode passed after starter init, feature scaffold, and generated-project test execution with the new alias configuration.

Issue

• scaffold: ルート境界をまたぐ import を root alias に統一する #778

Customer Value

• Generated projects now make cross-root dependencies explicit at the import site.
• Scaffolded code is less sensitive to directory depth, which reduces follow-on churn when boundaries move or get nested.

Outcome

• ztd init now emits #features/*, #libraries/*, #adapters/*, and #tests/* consistently across runtime and TypeScript resolution surfaces.
• Starter/template files that crossed canonical roots were updated to use root aliases.
• Reviewer-facing docs and release metadata now describe the policy explicitly.

Acceptance Criteria

• Generated project config defines root aliases for the canonical roots: done
• Scaffold/template files avoid deep relative imports when crossing canonical roots: done
• Starter / smoke / feature scaffold generated-project verification passes: done
• Docs state the root-boundary alias policy: done
• Existing #features / #tests behavior stays aligned with the new aliases: done

Verification

• pnpm --filter @rawsql-ts/ztd-cli test -- init.command.test.ts directoryFinding.docs.test.ts
• pnpm verify:generated-project-mode
• git commit hook attempted the full baseline via pnpm test and exposed unrelated existing failures in unchanged files.

Repository Evidence

• packages/ztd-cli/src/commands/init.ts
• packages/ztd-cli/templates/tsconfig.json
• packages/ztd-cli/templates/vitest.config.ts
• packages/ztd-cli/templates/src/adapters/pg/sql-client.ts
• packages/ztd-cli/templates/src/adapters/console/repositoryTelemetry.ts
• packages/ztd-cli/templates/tests/support/testkit-client.webapi.ts
• packages/ztd-cli/tests/init.command.test.ts
• packages/ztd-cli/tests/directoryFinding.docs.test.ts
• scripts/verify-generated-project-mode.mjs
• .changeset/ten-soft-camels-jump.md

Supplementary Evidence

• The failed pre-commit full baseline output showed unrelated existing failures in unchanged tests. This is supplementary context for merge readiness, not the primary proof for the changed scaffold behavior.

Open Questions

• none

Merge Blockers

• none for this change

[coderabbitai]

📝 Walkthrough

Walkthrough

This PR extends the CLI scaffolding to support root-alias imports for libraries and adapters alongside the existing features and tests aliases. Template configurations, source files, and verification tooling are updated to enforce consistent root-alias usage across project boundaries.

Changes

Cohort / File(s)	Summary
Documentation & Release .changeset/ten-soft-camels-jump.md, packages/ztd-cli/README.md, packages/ztd-cli/templates/README.md	Added changeset documenting the patch release; updated README guidance to specify root-alias-first rule when imports cross canonical roots (#features/*, #libraries/*, #adapters/*, #tests/*).
Template Configuration packages/ztd-cli/templates/tsconfig.json, packages/ztd-cli/templates/vitest.config.ts, packages/ztd-cli/src/commands/init.ts	Extended path alias mappings and package.json imports to include #libraries and #adapters alongside existing #features and #tests aliases across all configuration layers.
Template Source Files packages/ztd-cli/templates/src/adapters/console/repositoryTelemetry.ts, packages/ztd-cli/templates/src/adapters/pg/sql-client.ts, packages/ztd-cli/templates/tests/support/testkit-client.webapi.ts	Updated type-only imports from relative paths to root aliases (e.g., ../../libraries/... → #libraries/...).
Tests & Verification packages/ztd-cli/tests/directoryFinding.docs.test.ts, packages/ztd-cli/tests/init.command.test.ts, scripts/verify-generated-project-mode.mjs	Extended test assertions and verification checks to validate new root-alias mappings in configuration files and alias-style imports in template source files; added helper function for file content validation.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

• [codex] add generated-project verification lane #721: Updates generated-project verification tooling and template test expectations to align with scaffolding changes.
• fix: unblock release PR verification #760: Modifies the same verification script (scripts/verify-generated-project-mode.mjs) with additional override and validation logic.
• docs(cli): remove tables/views scaffold guidance #616: Updates template import specifiers and scaffolding paths for adapter and test files.

Poem

🐰 Root aliases bloom in every corner,
Cross-root imports now stand tall and stronger,
No more relative hops and wiggly paths,
Stability thrives where #libraries laughs,
Structures may move, but aliases stay true! 🌟

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title 'fix(ztd-cli): align scaffold cross-root imports with root aliases' clearly summarizes the main change in the PR, which is aligning imports across canonical project roots with root aliases.
Description check	✅ Passed	Pull request description is comprehensive and well-structured, following the template with all required sections completed including Summary, Verification, Merge Readiness, CLI Surface Migration, and Scaffold Contract Proof.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch 778-scaffold-ルート境界をまたぐ-import-を-root-alias-に統一する

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}