@topolo/cli 0.4.8 → 0.5.0

package/dist/index.js

@@ -9,7 +9,7 @@ import { platform as platform2 } from "os";
 import { createInterface } from "readline/promises";
 import { stdin as input } from "process";
 
-// node_modules/@topolo/sdk/dist/index.js
+// ../topolo-sdk/dist/index.js
 function applyAuthHeaders(headers, credential) {
   if (credential.kind === "api_key") {
     headers.set("X-Api-Key", credential.apiKey);
@@ -3504,7 +3504,7 @@ function createTopolo(options) {
   };
 }
 
-// node_modules/@topolo/sdk/dist/node/credential-store.js
+// ../topolo-sdk/dist/node/credential-store.js
 import { mkdir, readFile, writeFile, chmod } from "fs/promises";
 import { existsSync } from "fs";
 import { homedir, platform } from "os";
@@ -5819,6 +5819,22 @@ function normalizeWorkspaceSwitcherMode(value) {
   if (mode === "required" || mode === "optional" || mode === "off") return mode;
   throw new Error("Invalid workspace switcher mode. Use required, optional, or off.");
 }
+function normalizeUiTemplate(value) {
+  const template = String(value || "operations").trim();
+  if (template === "operations" || template === "index" || template === "workbench" || template === "minimal") {
+    return template;
+  }
+  throw new Error("Invalid UI template. Use operations, index, workbench, or minimal.");
+}
+function normalizeFirstPartyAppDir(value) {
+  const requested = String(value).trim().replace(/\\/g, "/").replace(/^\.\//, "");
+  const appDir = requested.startsWith("apps/") ? requested.slice("apps/".length) : requested;
+  const segments = appDir.split("/");
+  if (!appDir || appDir.startsWith("/") || appDir.startsWith("apps/") || segments.some((segment) => !segment || segment === "." || segment === "..")) {
+    throw new Error("Invalid first-party app directory. Use a repository name such as TopoloForms or apps/TopoloForms.");
+  }
+  return appDir;
+}
 function normalizeTarget(value) {
   if (!value) return "platform";
   if (value === "platform" || value === "developer") return value;
@@ -5918,7 +5934,9 @@ function toPascalCase(value) {
   return value.split(/[-_]/).filter(Boolean).map((part) => acronyms.has(part.toLowerCase()) ? part.toUpperCase() : part.slice(0, 1).toUpperCase() + part.slice(1)).join("");
 }
 function toTitle(value) {
-  return value.replace(/^topolo[-_\s]*/i, "Topolo ").split(/[-_\s]+/).filter(Boolean).map((part) => part.slice(0, 1).toUpperCase() + part.slice(1)).join(" ");
+  const withoutVendorPrefix = value.replace(/^topolo[-_\s]+/i, "");
+  const source = withoutVendorPrefix.trim() ? withoutVendorPrefix : value;
+  return source.split(/[-_\s]+/).filter(Boolean).map((part) => part.slice(0, 1).toUpperCase() + part.slice(1)).join(" ");
 }
 function json(value) {
   return JSON.stringify(value, null, 2);
@@ -6024,6 +6042,9 @@ function packageJson(application, target, options) {
     devDependencies["@types/react-dom"] = "^19.2.2";
     devDependencies["@vitejs/plugin-react"] = "^4.7.0";
     if (target === "platform") {
+      devDependencies.autoprefixer = "10.5.0";
+      devDependencies.postcss = "8.5.6";
+      devDependencies.tailwindcss = "3.4.19";
       for (const packageName of PLATFORM_BROWSER_TOPOLO_PACKAGES) {
         dependencies[packageName] = topoloPackageVersion(packageName, target);
       }
@@ -6187,13 +6208,16 @@ function readme(application, target, options) {
       "- `@topolo-io/app-funnel` provides the generated public application funnel/landing surface.",
       "- `@topolo-io/app-shell` provides the generated route/auth bootstrap, product shell, login, callback, and loading surfaces.",
       "- `@topolo-io/app-launcher` provides shared app switching and handoff helpers.",
-      "- `@topolo-io/ui-kit` provides primitive account, command palette, icon, transition, and bug reporter UI.",
+      "- `@topolo-io/ui-kit` provides every control, table, panel, workbench, inspector, icon, transition, and bug reporter primitive used by the generated product surface.",
       "- `@topolo-io/auth-client` owns browser auth, callback exchange, token refresh, and logout.",
       "- `@topolo-io/api-key-management`, `@topolo-io/chat-widget`, `@topolo-io/notifications`, and `@topolo-io/resource-context` complete the AppShell capability baseline.",
       "- Every Topolo-owned browser dependency is emitted at `latest`; product-domain packages are added only when the app actually adopts that domain.",
       "- `.npmrc` routes private `@topolo-io` packages to GitHub Packages without storing credentials; public `@topolo` packages remain on npm. Local and CI environments must provide a GitHub Packages token.",
       "- Generated first-party browser apps start on the shared landing page at `/`, use the shared login page at `/login`, and complete sign-in on `/auth/callback` before entering the configured authenticated home.",
       "- The workspace selector renders in the top utility bar; Getting Started is an account-menu action and is not part of the left product rail.",
+      "- The default `operations` UI template separates dashboard, CRUD index, detail workbench, and inspector concerns. Use `--ui-template index`, `--ui-template workbench`, or `--ui-template minimal` only when that product shape is intentional.",
+      "- Every visible product navigation item includes a canonical icon so the shared sidebar remains usable when collapsed.",
+      "- `styles.css` contains only Tailwind directives; app-local controls, semantic tables, or replacement design-system CSS fail the generated UI contract test.",
       "- `vite.config.ts` includes the standard React plugin plus React runtime dedupe so linked Topolo packages resolve one browser React runtime."
     );
     if (options.api) {
@@ -6290,6 +6314,8 @@ function agentRules(application, target, options) {
     "- Start from `staging`, preserve other agents' work, and do not revert unrelated local changes.",
     "- Make contained changes at the real ownership boundary; do not patch around shared runtime, auth, launcher, shell, or resource-context issues locally.",
     "- Browser code should stay on the shared landing/login/callback/AppShell baseline generated by the scaffold.",
+    "- Keep every visible product navigation item on a canonical `@topolo-io/ui-kit/icons` icon so collapsed navigation remains complete.",
+    "- Use shared UI-kit controls, tables, panels, workbenches, and inspectors; the generated UI contract intentionally rejects app-local native controls and tables.",
     ...options.api ? ["- API code should stay on `@topolo-io/worker-runtime`, derive auth context from verified credentials, and preserve Nexus usage monitoring."] : [],
     ...hasScaffoldResources(options.resources) ? ["- Keep Cloudflare resource bindings in Wrangler, CloudControl, Env typing, docs, and README verification output in sync."] : [],
     "",
@@ -6640,7 +6666,36 @@ function mainTsx() {
     ""
   ].join("\n");
 }
-function stylesCss() {
+function tailwindConfigCjs() {
+  return [
+    "const { createTopoloTailwindConfig } = require('@topolo-io/design-tokens/tailwind.config.cjs');",
+    "",
+    "module.exports = createTopoloTailwindConfig({",
+    "  content: [",
+    "    './apps/web/index.html',",
+    "    './apps/web/src/**/*.{js,jsx,ts,tsx}',",
+    "  ],",
+    "});",
+    ""
+  ].join("\n");
+}
+function postcssConfigCjs() {
+  return [
+    "const path = require('node:path');",
+    "",
+    "module.exports = {",
+    "  plugins: {",
+    "    tailwindcss: { config: path.join(__dirname, 'tailwind.config.cjs') },",
+    "    autoprefixer: {},",
+    "  },",
+    "};",
+    ""
+  ].join("\n");
+}
+function stylesCss(target) {
+  if (target === "platform") {
+    return ["@tailwind base;", "@tailwind components;", "@tailwind utilities;", ""].join("\n");
+  }
   return [
     "/* Local app styles. Design tokens come from @topolo-io/design-tokens (imported in main.tsx). */",
     "/* Use hsl(var(--token)) for colors so light/dark themes flip from the shared shell. */",
@@ -6846,20 +6901,41 @@ export const APP_DISPLAY_NAME = '${escapeSingleQuoted(appName)}';
 `;
 }
 function platformAppRoutesTsx(experience) {
-  const nav = experience.navigationMode === "none" ? "" : "      nav: { id: 'home', label: HOME_LABEL },\n";
+  const nav = experience.navigationMode === "none" ? "" : "      nav: { id: 'home', label: HOME_LABEL, icon: LayoutDashboard },\n";
+  const recordsNav = experience.navigationMode === "none" ? "" : "      nav: { id: 'records', label: 'Records', icon: ListTree },\n";
+  const starterImports = experience.uiTemplate === "minimal" ? "" : "import RecordDetailRoute from './routes/RecordDetailRoute';\nimport RecordsRoute from './routes/RecordsRoute';\n";
+  const homeElement = experience.uiTemplate === "index" ? "<RecordsRoute />" : experience.uiTemplate === "workbench" ? "<RecordDetailRoute />" : "<HomeRoute />";
+  const starterRoutes = experience.uiTemplate === "minimal" ? "" : experience.uiTemplate === "operations" ? `    {
+      path: '/records',
+${recordsNav}      loading: { shell: NAVIGATION_MODE, content: 'table', title: 'Records' },
+      element: <RecordsRoute />,
+    },
+    {
+      path: '/records/:recordId/:section',
+      loading: { shell: NAVIGATION_MODE, content: 'split', title: 'Record' },
+      element: <RecordDetailRoute />,
+    },
+` : `    {
+      path: '/records/:recordId/:section',
+      loading: { shell: NAVIGATION_MODE, content: 'split', title: 'Record' },
+      element: <RecordDetailRoute />,
+    },
+`;
   return `import type { AppRoute } from '@topolo-io/app-shell';
+import { LayoutDashboard, ListTree } from '@topolo-io/ui-kit/icons';
 import { HOME_LABEL, HOME_PATH, NAVIGATION_MODE } from './app-config';
 import GettingStartedRoute from './routes/GettingStartedRoute';
 import HomeRoute from './routes/HomeRoute';
+${starterImports}
 
 export function createAppRoutes(appId: string): AppRoute[] {
   return [
     {
       path: HOME_PATH,
 ${nav}      loading: { shell: NAVIGATION_MODE, content: 'workspace', title: HOME_LABEL },
-      element: <HomeRoute />,
+      element: ${homeElement},
     },
-    {
+${starterRoutes}    {
       path: '/getting-started',
       loading: { shell: NAVIGATION_MODE, content: 'card-grid', title: 'Getting started' },
       element: <GettingStartedRoute appId={appId} />,
@@ -6868,7 +6944,8 @@ ${nav}      loading: { shell: NAVIGATION_MODE, content: 'workspace', title: HOME
 }
 `;
 }
-function platformHomeRouteTsx() {
+function platformHomeRouteTsx(uiTemplate) {
+  if (uiTemplate === "operations") return platformOperationsHomeRouteTsx();
   return `import { TopoloAppPage, TopoloAppPageHeader, useAuth } from '@topolo-io/app-shell';
 import { IntroTour } from '@topolo-io/tour';
 import { useTranslation } from '@topolo-io/ui-kit';
@@ -6904,6 +6981,148 @@ export default function HomeRoute() {
 }
 `;
 }
+function platformOperationsHomeRouteTsx() {
+  return `import { TopoloAppPage, TopoloAppPageHeader, useAuth } from '@topolo-io/app-shell';
+import { Button, ListRow, TopoloMetricStrip, TopoloOperationalPanel } from '@topolo-io/ui-kit';
+import { IntroTour } from '@topolo-io/tour';
+import { useNavigate } from 'react-router-dom';
+import { APP_NAME, HOME_LABEL, HOME_PATH, PRODUCT_TAGLINE } from '../app-config';
+import { STARTER_RECORDS } from './starter-records';
+
+// STARTER TEMPLATE: replace the sample metrics and activity with product data.
+export default function HomeRoute() {
+  const { user } = useAuth();
+  const navigate = useNavigate();
+  const active = STARTER_RECORDS.filter((record) => record.status === 'active').length;
+  return (
+    <TopoloAppPage width="none" data-tour="home-page">
+      <TopoloAppPageHeader eyebrow={APP_NAME} title={HOME_LABEL} description={PRODUCT_TAGLINE} actions={<Button onClick={() => navigate('/records')}>Open records</Button>} />
+      <TopoloMetricStrip metrics={[
+        { id: 'total', label: 'Total records', value: STARTER_RECORDS.length },
+        { id: 'active', label: 'Active', value: active, tone: 'success' },
+        { id: 'attention', label: 'Needs attention', value: STARTER_RECORDS.length - active, tone: 'warning' },
+      ]} />
+      <TopoloOperationalPanel title="Recent records" description="Keep operational summaries focused; detailed CRUD belongs in the index and workbench routes." action={<Button variant="secondary" onClick={() => navigate('/records')}>View index</Button>}>
+        <div className="grid gap-1">{STARTER_RECORDS.slice(0, 3).map((record) => <ListRow key={record.id} title={record.name} subtitle={record.owner} meta={record.updatedAt} onSelect={() => navigate(\`/records/\${record.id}/overview\`)} />)}</div>
+      </TopoloOperationalPanel>
+      <IntroTour appName={APP_NAME} role={user?.role} onOpenGettingStarted={() => navigate('/getting-started')} extraSteps={[{
+        id: 'home-page', target: '[data-tour="home-page"]', title: HOME_LABEL, content: PRODUCT_TAGLINE,
+        placement: 'bottom' as const, beforeStep: () => navigate(HOME_PATH),
+      }]} />
+    </TopoloAppPage>
+  );
+}
+`;
+}
+function platformStarterDataTs() {
+  return `// STARTER TEMPLATE: replace this file with the app's real API-backed domain model.
+export type StarterRecordStatus = 'active' | 'draft' | 'paused';
+
+export interface StarterRecord {
+  id: string;
+  name: string;
+  status: StarterRecordStatus;
+  owner: string;
+  summary: string;
+  updatedAt: string;
+}
+
+export const STARTER_RECORDS: StarterRecord[] = [
+  { id: 'starter-record-1', name: 'First starter record', status: 'active', owner: 'Product team', summary: 'Replace this sample with one app-specific concept.', updatedAt: 'Today' },
+  { id: 'starter-record-2', name: 'Second starter record', status: 'draft', owner: 'Operations', summary: 'Use the index for discovery and the workbench for focused editing.', updatedAt: 'Yesterday' },
+  { id: 'starter-record-3', name: 'Third starter record', status: 'paused', owner: 'Workspace admin', summary: 'Keep unrelated workflows on separate routes.', updatedAt: '3 days ago' },
+];
+`;
+}
+function platformRecordsRouteTsx() {
+  return `import { useMemo, useState, type FormEvent } from 'react';
+import { TopoloAppDataTable, TopoloAppEmptyState, TopoloAppFilterBar, TopoloAppPage, TopoloAppPageHeader, TopoloAppToolbar } from '@topolo-io/app-shell';
+import { Badge, Button, FormField, Input, SearchInput, Select, Table, TableBody, TableCell, TableHead, TableHeader, TableRow, TopoloRightPanel } from '@topolo-io/ui-kit';
+import { Plus } from '@topolo-io/ui-kit/icons';
+import { useNavigate } from 'react-router-dom';
+import { STARTER_RECORDS, type StarterRecord, type StarterRecordStatus } from './starter-records';
+
+// STARTER TEMPLATE: keep the index focused on discovery, filtering, and create entry.
+export default function RecordsRoute() {
+  const navigate = useNavigate();
+  const [records, setRecords] = useState<StarterRecord[]>(STARTER_RECORDS);
+  const [query, setQuery] = useState('');
+  const [status, setStatus] = useState('current');
+  const [createOpen, setCreateOpen] = useState(false);
+  const visible = useMemo(() => records.filter((record) => {
+    if (status !== 'current' && status !== 'all' && record.status !== status) return false;
+    return !query || record.name.toLowerCase().includes(query.toLowerCase());
+  }), [query, records, status]);
+
+  function createRecord(event: FormEvent<HTMLFormElement>) {
+    event.preventDefault();
+    const data = new FormData(event.currentTarget);
+    const name = String(data.get('name') || '').trim();
+    if (!name) return;
+    const record: StarterRecord = {
+      id: \`starter-record-\${Date.now()}\`, name, status: 'draft', owner: String(data.get('owner') || 'Workspace team'),
+      summary: String(data.get('summary') || 'Replace this starter form with domain fields.'), updatedAt: 'Just now',
+    };
+    setRecords((current) => [record, ...current]);
+    setCreateOpen(false);
+  }
+
+  return (
+    <TopoloAppPage width="none">
+      <TopoloAppPageHeader eyebrow="Starter CRUD" title="Records" description="A canonical index route with shared controls, shared tables, and a separate creation panel." actions={<Button leftIcon={<Plus size={16} />} onClick={() => setCreateOpen(true)}>New record</Button>} />
+      <TopoloAppToolbar><TopoloAppFilterBar>
+        <SearchInput className="w-64" value={query} onChange={(event) => setQuery(event.target.value)} placeholder="Search records" aria-label="Search records" />
+        <Select className="w-44" value={status} onChange={(event) => setStatus(event.target.value)} aria-label="Record status"><option value="current">Current</option><option value="active">Active</option><option value="draft">Draft</option><option value="paused">Paused</option><option value="all">All</option></Select>
+      </TopoloAppFilterBar><span className="text-sm text-muted-foreground">{visible.length} result{visible.length === 1 ? '' : 's'}</span></TopoloAppToolbar>
+      {visible.length ? <TopoloAppDataTable aria-label="Records"><Table>
+        <TableHeader><TableRow><TableHead>Name</TableHead><TableHead>Status</TableHead><TableHead>Owner</TableHead><TableHead>Updated</TableHead></TableRow></TableHeader>
+        <TableBody>{visible.map((record) => <TableRow className="cursor-pointer" key={record.id} tabIndex={0} onClick={() => navigate(\`/records/\${record.id}/overview\`)} onKeyDown={(event) => { if (event.key === 'Enter') navigate(\`/records/\${record.id}/overview\`); }}>
+          <TableCell><span className="grid gap-0.5"><strong>{record.name}</strong><small className="text-xs text-muted-foreground">{record.id}</small></span></TableCell>
+          <TableCell><RecordStatus status={record.status} /></TableCell><TableCell>{record.owner}</TableCell><TableCell>{record.updatedAt}</TableCell>
+        </TableRow>)}</TableBody>
+      </Table></TopoloAppDataTable> : <TopoloAppEmptyState title="No records match" description="Adjust the filters or create a record." action={<Button onClick={() => setCreateOpen(true)}>Create record</Button>} />}
+      <TopoloRightPanel open={createOpen} onOpenChange={setCreateOpen} title="Create record" description="Replace these starter fields with the smallest valid domain create flow." footer={<Button type="submit" form="starter-create-record">Create record</Button>}>
+        <form id="starter-create-record" className="grid gap-5" onSubmit={createRecord}><FormField label="Name"><Input name="name" required autoFocus /></FormField><FormField label="Owner"><Input name="owner" placeholder="Workspace team" /></FormField><FormField label="Summary"><Input name="summary" placeholder="What this record represents" /></FormField></form>
+      </TopoloRightPanel>
+    </TopoloAppPage>
+  );
+}
+
+export function RecordStatus({ status }: { status: StarterRecordStatus }) {
+  const tone = status === 'active' ? 'success' : status === 'paused' ? 'warning' : 'info';
+  return <Badge tone={tone}>{status}</Badge>;
+}
+`;
+}
+function platformRecordDetailRouteTsx() {
+  return `import { TopoloAppEmptyState } from '@topolo-io/app-shell';
+import { Button, CopyField, Tabs, TabsList, TabsTrigger, TopoloCommandBar, TopoloInspectorPanel, TopoloKeyValueRow, TopoloOperationalPanel, TopoloWorkbench } from '@topolo-io/ui-kit';
+import { useNavigate, useParams } from 'react-router-dom';
+import { RecordStatus } from './RecordsRoute';
+import { STARTER_RECORDS } from './starter-records';
+
+const sections = ['overview', 'activity', 'settings'] as const;
+
+// STARTER TEMPLATE: one selected record, one focused workflow, one inspector. The product sidebar remains the only left rail.
+export default function RecordDetailRoute() {
+  const navigate = useNavigate();
+  const { recordId, section: rawSection } = useParams();
+  const record = STARTER_RECORDS.find((item) => item.id === recordId) ?? STARTER_RECORDS[0];
+  const section = sections.includes(rawSection as (typeof sections)[number]) ? rawSection! : 'overview';
+  if (!record) return <TopoloAppEmptyState title="Record not found" description="Return to the index and choose another record." action={<Button onClick={() => navigate('/records')}>Back to records</Button>} />;
+  return (
+    <div className="-m-6 min-w-0 max-md:-m-4"><TopoloWorkbench layout="split" className="min-h-[calc(100dvh-4rem)] gap-0 overflow-hidden bg-background">
+      <main className="min-w-0 overflow-y-auto p-6 max-md:p-4">
+        <TopoloCommandBar eyebrow="Starter record" title={record.name} description={record.summary} meta={<RecordStatus status={record.status} />} actions={<Button>Edit record</Button>} />
+        <Tabs className="my-5" value={section} onValueChange={(next) => navigate(\`/records/\${record.id}/\${next}\`)}><TabsList>{sections.map((item) => <TabsTrigger key={item} value={item}>{item}</TabsTrigger>)}</TabsList></Tabs>
+        <TopoloOperationalPanel title={section === 'overview' ? 'Record overview' : section === 'activity' ? 'Record activity' : 'Record settings'} description="Replace this panel with one focused domain workflow. Do not combine unrelated concepts on this route."><TopoloKeyValueRow label="Owner" value={record.owner} /><TopoloKeyValueRow label="Updated" value={record.updatedAt} /></TopoloOperationalPanel>
+      </main>
+      <TopoloInspectorPanel className="m-4 ml-0 max-lg:m-4" title="Record context" description="Keep selected-record metadata and secondary actions here." sticky><TopoloKeyValueRow label="Status" value={<RecordStatus status={record.status} />} /><TopoloKeyValueRow label="Owner" value={record.owner} /><CopyField label="Record ID" value={record.id} /></TopoloInspectorPanel>
+    </TopoloWorkbench></div>
+  );
+}
+`;
+}
 function platformGettingStartedRouteTsx() {
   return `import { TopoloAppPage, useAuth } from '@topolo-io/app-shell';
 import { GettingStarted, type OnboardingGuideStep } from '@topolo-io/onboarding';
@@ -7857,7 +8076,7 @@ function topoloConformanceWorkflow(options) {
     "      - name: Install generated application",
     `        if: steps.app-token.outputs.token != '' || env.HAS_TOPOLO_CI_REPO_TOKEN == 'true'`,
     `        working-directory: ${appPath}`,
-    "        run: pnpm install --frozen-lockfile",
+    "        run: pnpm install --no-frozen-lockfile",
     "",
     "      - name: Run generated application quality gates",
     `        if: steps.app-token.outputs.token != '' || env.HAS_TOPOLO_CI_REPO_TOKEN == 'true'`,
@@ -8795,7 +9014,8 @@ ${coverageThresholds}
 function platformBrowserContractTest(application, experience) {
   const required = experience.workspaceSwitcher === "required";
   const enabled = experience.workspaceSwitcher !== "off";
-  const navExpectation = experience.navigationMode === "none" ? "    expect(home.nav).toBeUndefined();" : `    expect(home.nav).toEqual({ id: 'home', label: '${escapeSingleQuoted(experience.homeLabel)}' });`;
+  const navExpectation = experience.navigationMode === "none" ? "    expect(home.nav).toBeUndefined();" : `    expect(home.nav).toMatchObject({ id: 'home', label: '${escapeSingleQuoted(experience.homeLabel)}' });
+    expect(home.nav?.icon).toBeDefined();`;
   return `import { describe, expect, it, vi } from 'vitest';
 
 vi.mock('../src/app-identity', () => ({
@@ -8816,12 +9036,52 @@ describe('generated application contract', () => {
   });
 
   it('keeps Getting Started out of product navigation', () => {
-    const [home, gettingStarted] = createAppRoutes('app_test');
+    const routes = createAppRoutes('app_test');
+    const home = routes.find((route) => route.path === '${escapeSingleQuoted(experience.homePath)}')!;
+    const gettingStarted = routes.find((route) => route.path === '/getting-started')!;
     expect(home.path).toBe('${escapeSingleQuoted(experience.homePath)}');
 ${navExpectation}
     expect(gettingStarted.path).toBe('/getting-started');
     expect(gettingStarted.nav).toBeUndefined();
   });
+
+  it('keeps every visible route reachable when a sidebar is collapsed', () => {
+    for (const route of createAppRoutes('app_test').filter((candidate) => candidate.nav)) {
+      expect(route.nav?.icon).toBeDefined();
+    }
+  });
+});
+`;
+}
+function platformUiKitContractTest() {
+  return `import { readFileSync, readdirSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { describe, expect, it } from 'vitest';
+
+function sourceFiles(root: string): string[] {
+  return readdirSync(root).flatMap((entry) => {
+    const path = join(root, entry);
+    return statSync(path).isDirectory() ? sourceFiles(path) : path.endsWith('.tsx') ? [path] : [];
+  });
+}
+
+describe('generated shared UI contract', () => {
+  const sourceRoot = join(process.cwd(), 'src');
+  const source = sourceFiles(sourceRoot).map((path) => readFileSync(path, 'utf8')).join('\\n');
+
+  it('does not hand-roll controls or semantic tables in first-party routes', () => {
+    expect(source).not.toMatch(/<(button|input|select|textarea|table|thead|tbody|tr|th|td)(\\s|>)/);
+  });
+
+  it('keeps app-local CSS limited to the shared Tailwind pipeline', () => {
+    expect(readFileSync(join(sourceRoot, 'styles.css'), 'utf8').trim()).toBe('@tailwind base;\\n@tailwind components;\\n@tailwind utilities;');
+  });
+
+  it('scans app source and shared packages through the canonical token config', () => {
+    const config = readFileSync(join(process.cwd(), 'tailwind.config.cjs'), 'utf8');
+    expect(config).toContain('createTopoloTailwindConfig');
+    expect(config).toContain("./apps/web/src/**/*.{js,jsx,ts,tsx}");
+  });
 });
 `;
 }
@@ -8970,7 +9230,8 @@ function applicationScaffoldPayload(application, options = {}) {
   }
   const ownerType = target === "platform" ? "topolo_first_party" : "third_party";
   const distributionModel = target === "platform" ? "marketplace" : "organization_internal";
-  const appDir = options.appDir ?? catalogApplication?.appDir ?? (target === "platform" ? `Topolo${toPascalCase(id)}` : `topolo-${slug}`);
+  const requestedAppDir = options.appDir ?? catalogApplication?.appDir ?? (target === "platform" ? `Topolo${toPascalCase(id)}` : `topolo-${slug}`);
+  const appDir = target === "platform" ? normalizeFirstPartyAppDir(requestedAppDir) : requestedAppDir;
   const name = options.name ?? catalogApplication?.name ?? `topolo-${slug}`;
   const packageName = options.packageName ?? catalogApplication?.packageName ?? `topolo-${slug}`;
   const experience = {
@@ -8978,6 +9239,7 @@ function applicationScaffoldPayload(application, options = {}) {
     homeLabel: normalizeHomeLabel(options.homeLabel),
     navigationMode: normalizeNavigationMode(options.navigationMode),
     workspaceSwitcher: normalizeWorkspaceSwitcherMode(options.workspaceSwitcher),
+    uiTemplate: normalizeUiTemplate(options.uiTemplate),
     workspaceLabel: tenancy === "household" ? "Households" : "Workspaces",
     tagline: String(options.tagline || "").trim() || `Manage your work in ${toTitle(name)}.`
   };
@@ -9257,9 +9519,21 @@ function scaffoldFiles(options) {
         "does not fork the shared shell chrome",
         "keeps app-specific layout scoped under generated classes"
       ],
-      content: stylesCss()
+      content: stylesCss(target)
     }] : [],
     ...target === "platform" && options.browser ? [
+      {
+        path: `${browserBase}/tailwind.config.cjs`,
+        purpose: "Canonical shared-token Tailwind content configuration.",
+        requiredSignals: ["extends the shared Topolo token config", "scans app source correctly when Vite starts from the repository root"],
+        content: tailwindConfigCjs()
+      },
+      {
+        path: `${browserBase}/postcss.config.cjs`,
+        purpose: "PostCSS pipeline for shared Topolo utility classes.",
+        requiredSignals: ["loads the generated Tailwind config", "runs autoprefixer"],
+        content: postcssConfigCjs()
+      },
       {
         path: `${browserBase}/src/app-config.ts`,
         purpose: "Product route, navigation, context-switcher, and entry-surface configuration.",
@@ -9276,8 +9550,28 @@ function scaffoldFiles(options) {
         path: `${browserBase}/src/routes/HomeRoute.tsx`,
         purpose: "Focused authenticated home product surface.",
         requiredSignals: ["uses shared page primitives", "uses translation-safe product copy"],
-        content: platformHomeRouteTsx()
+        content: platformHomeRouteTsx(options.payload.experience.uiTemplate)
       },
+      ...options.payload.experience.uiTemplate === "minimal" ? [] : [
+        {
+          path: `${browserBase}/src/routes/starter-records.ts`,
+          purpose: "Clearly marked replaceable starter records for the generated UI template.",
+          requiredSignals: ["keeps sample data outside route components", "is explicitly marked for replacement"],
+          content: platformStarterDataTs()
+        },
+        {
+          path: `${browserBase}/src/routes/RecordsRoute.tsx`,
+          purpose: "Focused CRUD index template built exclusively from shared UI primitives.",
+          requiredSignals: ["uses shared table, search, select, button, and right-panel primitives", "keeps creation separate from the index"],
+          content: platformRecordsRouteTsx()
+        },
+        {
+          path: `${browserBase}/src/routes/RecordDetailRoute.tsx`,
+          purpose: "Focused record workbench template with collection rail and inspector.",
+          requiredSignals: ["uses the shared workbench and inspector primitives", "keeps detail sections URL-addressable"],
+          content: platformRecordDetailRouteTsx()
+        }
+      ],
       {
         path: `${browserBase}/src/routes/GettingStartedRoute.tsx`,
         purpose: "Focused role-aware onboarding route reached from the account menu.",
@@ -9560,6 +9854,12 @@ export default defineConfig({
             requiredSignals: ["proves API proxying", "proves non-API browser fallback"],
             content: platformWebWorkerTest(application, options.api)
           },
+          {
+            path: `${browserBase}/test/ui-kit-contract.test.ts`,
+            purpose: "Executable guard against hand-rolled first-party controls and broken shared styling.",
+            requiredSignals: ["rejects native controls and semantic tables in generated routes", "proves canonical Tailwind scanning and zero app-local design CSS"],
+            content: platformUiKitContractTest()
+          },
           {
             path: `${browserBase}/src/worker.ts`,
             purpose: "Browser Worker that serves assets and forwards API paths when an API target exists.",
@@ -10407,10 +10707,10 @@ function registerPlatformCommand(program2) {
   const platformApps = platform3.command("apps").description("Scaffold and operate first-party Topolo platform and personal applications");
   platformApps.command("scaffold <application>").description(
     "Generate a first-party Topolo scaffold for the platform or personal portfolio."
-  ).option("--json", "Output JSON").option("--no-json", "Output human-readable checklist").option("--app-dir <path>", "Application directory under apps/").option("--name <name>", "Application display/package source name").option("--package-name <name>", "package.json name").option("--production-url <url>", "Production browser URL").option("--service <id>", "Stable SDK/Auth app id for API-backed apps").option("--portfolio <portfolio>", "First-party portfolio: platform or personal").option(
+  ).option("--json", "Output JSON").option("--no-json", "Output human-readable checklist").option("--app-dir <path>", "Application repo name or apps/<repo> path").option("--name <name>", "Application display/package source name").option("--package-name <name>", "package.json name").option("--production-url <url>", "Production browser URL").option("--service <id>", "Stable SDK/Auth app id for API-backed apps").option("--portfolio <portfolio>", "First-party portfolio: platform or personal").option(
     "--surface-model <surfaceModel>",
     "First-party surface model: web_app, mobile_container, mobile_module, or messaging_surface"
-  ).option("--container-app-id <appId>", "Container app id when --surface-model mobile_module is used").option("--profile <profile>", "First-party scaffold profile such as spatial-assets").option("--with-d1", "Declare a D1 binding in the first-party scaffold").option("--with-r2", "Declare an R2 binding in the first-party scaffold").option("--with-queue", "Declare a Queue binding in the first-party scaffold").option("--with-workflow", "Declare a Workflow binding in the first-party scaffold").option("--with-container-processing", "Declare container-processing metadata in CloudControl").option("--home-path <path>", "Authenticated home route (default: /dashboard)").option("--home-label <label>", "Home navigation label (default: Dashboard)").option("--navigation-mode <mode>", "Product navigation: sidebar, topbar, or none").option("--workspace-switcher <mode>", "Workspace context selector: required, optional, or off").option("--tagline <text>", "Product-facing landing and home description").option("--write", "Write the generated scaffold files to disk").option("--repo-root <path>", "Directory where scaffold files should be written").option("--force", "Overwrite existing scaffold files when --write is set").option("--with-api", "Include the API/service baseline").option("--no-api", "Do not include API/service requirements").option("--no-browser", "Do not include browser-shell requirements").option(
+  ).option("--container-app-id <appId>", "Container app id when --surface-model mobile_module is used").option("--profile <profile>", "First-party scaffold profile such as spatial-assets").option("--with-d1", "Declare a D1 binding in the first-party scaffold").option("--with-r2", "Declare an R2 binding in the first-party scaffold").option("--with-queue", "Declare a Queue binding in the first-party scaffold").option("--with-workflow", "Declare a Workflow binding in the first-party scaffold").option("--with-container-processing", "Declare container-processing metadata in CloudControl").option("--home-path <path>", "Authenticated home route (default: /dashboard)").option("--home-label <label>", "Home navigation label (default: Dashboard)").option("--navigation-mode <mode>", "Product navigation: sidebar, topbar, or none").option("--workspace-switcher <mode>", "Workspace context selector: required, optional, or off").option("--ui-template <template>", "Shared UI starter: operations, index, workbench, or minimal").option("--tagline <text>", "Product-facing landing and home description").option("--write", "Write the generated scaffold files to disk").option("--repo-root <path>", "Directory where scaffold files should be written").option("--force", "Overwrite existing scaffold files when --write is set").option("--with-api", "Include the API/service baseline").option("--no-api", "Do not include API/service requirements").option("--no-browser", "Do not include browser-shell requirements").option(
     "--provision",
     "Provision the generated first-party app into Topolo Developers and Auth using the authenticated Topolo admin session"
   ).option(
@@ -10450,6 +10750,7 @@ function registerPlatformCommand(program2) {
         homeLabel: opts.homeLabel,
         navigationMode: opts.navigationMode,
         workspaceSwitcher: opts.workspaceSwitcher,
+        uiTemplate: opts.uiTemplate,
         tagline: opts.tagline
       });
       if (opts.workflowOnly && !payload.ciWorkflow) {

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "@topolo/cli",
-  "version": "0.4.8",
+  "version": "0.5.0",
+  "topoloPublishedVersion": "0.5.0",
   "description": "Command-line interface for Topolo developers, operators, and agents, with internal first-party scaffolding available under the topolo platform namespace.",
   "type": "module",
   "bin": {
@@ -11,10 +12,14 @@
     "skills"
   ],
   "scripts": {
+    "build:sdk": "pnpm --dir ../topolo-sdk build",
+    "prebuild": "pnpm run build:sdk",
     "build": "tsup",
     "dev": "tsup --watch",
+    "pretypecheck": "pnpm run build:sdk",
     "typecheck": "tsc --noEmit",
     "start": "node dist/index.js",
+    "pretest": "pnpm run build:sdk",
     "test": "vitest run",
     "test:watch": "vitest",
     "coverage": "vitest run --coverage"
@@ -23,7 +28,7 @@
     "commander": "^12.1.0"
   },
   "devDependencies": {
-    "@topolo/sdk": "latest",
+    "@topolo/sdk": "file:../topolo-sdk",
     "@types/node": "^20.12.0",
     "@vitest/coverage-v8": "^2.1.0",
     "tsup": "^8.0.0",