Refactor to shadcn-style direct imports (STARTUP-93)

[ian]

• Refactor @startupkit/analytics to minimal core with peer dependencies
• Update @startupkit/auth to use flexible peer dependencies (>=1.3.0)
• Update @repo/analytics to import directly from posthog-js and rudderstack
• Update @repo/auth to import directly from better-auth
• Remove version lock-in - projects control all upstream dependencies
• Add comprehensive documentation of shadcn principle
• Both packages build successfully

The shadcn principle: Import directly from upstream. Only use @startupkit/*
when it adds real value (utilities, orchestration, conventions).

Closes STARTUP-93

• Closes STARTUP-15: Fix this lint issue
• Closes STARTUP-16: Swap out rudderstack, add posthog js client instead

---

Summary by cubic

Refactors packages to shadcn-style direct imports so projects control upstream versions and avoid lock-in. Implements STARTUP-93 by slimming @startupkit/* to minimal utilities, pushing product code to @repo/*, and updating docs, CLI, and scripts.

• Refactors

  • @startupkit/analytics → minimal core: peer deps, new orchestrator/utils/types; removed built-in plugins; provider now forwards to passed plugins.
  • @startupkit/auth → flexible peer deps (better-auth >=1.3.0; relaxed Next/React ranges).
  • @repo/analytics → direct imports (posthog-js, RudderStack), type-safe client/server tracking and feature flags; now the recommended product analytics (docs updated).
  • @repo/auth → direct better-auth; server uses createAuth helper; provider wires identify/reset to analytics.
  • Docs → added PACKAGE_STRATEGY and QUICK_REFERENCE; @startupkit/analytics marked legacy (marketing-only) with migration guidance.

• New Features

  • CLI add: choose Local (@repo/) vs Centralized (@startupkit/), places files in the right folder, and prints next steps.
  • Version bump script: clearer output, updates template/app references to the new version, and commits changes.

[linear]

STARTUP-93 Figure out packages strategy

[cubic-dev-ai]

8 issues found across 31 files

Prompt for AI agents (all 8 issues)

Understand the root cause of the following 8 issues and fix them.


<file name="packages/analytics/package.json">

<violation number="1" location="packages/analytics/package.json:40">
Emptying the dependencies object removes the externals list that rollup.config.mjs derives from pkg.dependencies, so analytics/posthog-js will now be bundled instead of treated as peer deps—undoing the intended refactor.</violation>
</file>

<file name="REFACTOR_SUMMARY.md">

<violation number="1" location="REFACTOR_SUMMARY.md:87">
The example calls `rudderstack.track(...)` without defining a `rudderstack` instance, so readers copying this snippet will hit a ReferenceError. Consider either instantiating `RudderAnalytics` or updating the example to use the imported symbol correctly.</violation>
</file>

<file name="packages/analytics/src/AnalyticsProvider.tsx">

<violation number="1" location="packages/analytics/src/AnalyticsProvider.tsx:34">
Calling plugin.initialize inside useMemo runs during render, so Strict Mode will execute it twice and duplicate analytics initialization. Move this side effect into useEffect or similar lifecycle-safe code.</violation>
</file>

<file name="templates/repo/packages/analytics/README.md">

<violation number="1" location="templates/repo/packages/analytics/README.md:64">
The client `track` example calls the hook with a string event, but `useAnalytics().track` currently expects `never`, so this sample fails TypeScript checks.</violation>

<violation number="2" location="templates/repo/packages/analytics/README.md:74">
`getFeatureFlags` is not exported from `@repo/analytics`; this import example will crash when followed.</violation>
</file>

<file name="packages/analytics/README.md">

<violation number="1" location="packages/analytics/README.md:43">
The README usage example imports `@startupkit/analytics/ga`, `/plausible`, and `/posthog`, but those modules are not present in this package, so the documented setup will fail at runtime.</violation>
</file>

<file name="packages/analytics/src/types.ts">

<violation number="1" location="packages/analytics/src/types.ts:7">
Allowing plugins to return Promise&lt;void&gt; from track means an async plugin rejection will bubble out, but createAnalyticsOrchestrator just invokes plugin.track(...) without awaiting or catch. Either restrict this to void or update the orchestrator to handle the returned promise.</violation>
</file>

<file name="templates/repo/packages/auth/src/index.ts">

<violation number="1" location="templates/repo/packages/auth/src/index.ts:13">
Removing the email OTP client plugin from the auth client breaks the documented OTP sign-in flow; please restore an OTP plugin alongside the admin plugin.</violation>
</file>

_{React with 👍 or 👎 to teach cubic. Mention @cubic-dev-ai to give feedback, ask questions, or re-run the review.}

[cubic-dev-ai]

The client track example calls the hook with a string event, but useAnalytics().track currently expects never, so this sample fails TypeScript checks.

Prompt for AI agents

Address the following comment on templates/repo/packages/analytics/README.md at line 64:

<comment>The client `track` example calls the hook with a string event, but `useAnalytics().track` currently expects `never`, so this sample fails TypeScript checks.</comment>

<file context>
@@ -21,21 +48,212 @@ await track({
+  const { track } = useAnalytics();
+
+  const handleClick = () =&gt; {
+    track(&quot;BUTTON_CLICKED&quot;, { buttonId: &quot;cta&quot; });
+  };
+
</file context>

[linear]

STARTUP-15 Fix this lint issue

STARTUP-16 Swap out rudderstack, add posthog js client instead