@dashai/cli 0.12.1 → 0.14.0

package/dist/bin.js

@@ -428,6 +428,25 @@ async function getModuleBySlug(slug, options = {}) {
     options
   );
 }
+function isInstallGated(r) {
+  return r.install_gated === true;
+}
+async function installModule(moduleId, body, options = {}) {
+  return apiRequest(
+    "POST",
+    `/api/modules/${moduleId}/install`,
+    body,
+    options
+  );
+}
+async function listWorkspaceInstallations(workspaceId, options = {}) {
+  return apiRequest(
+    "GET",
+    `/api/modules/workspaces/${workspaceId}/installations`,
+    void 0,
+    options
+  );
+}
 async function applyDraftManifest(moduleId, manifest, options = {}) {
   return apiRequest(
     "PUT",
@@ -846,8 +865,14 @@ npm run dev:next            # next dev on :3000                  (terminal 2)
 - **\`module.json\`** \u2014 manifest (\`module_kind: 'custom'\`, \`runtime.kind: 'machine'\`).
 - **\`middleware.ts\`** \u2014 \`withAuth\` from \`@dashai/sdk/auth/middleware\`. Redirects unauthenticated requests through the DashWise SSO flow.
 - **\`app/layout.tsx\`** \u2014 wraps the tree in \`<AuthProvider>\` from \`@dashai/sdk/auth/client\`.
-- **\`app/page.tsx\`** \u2014 public landing (allowlisted in \`middleware.ts\`).
-- **\`app/dashboard/page.tsx\`** \u2014 Server Component requiring a valid session via \`getServerSession()\`.
+- **\`app/page.tsx\`** \u2014 the app's home at \`/\` (auth-gated; zero-click for platform users via \`autoSignIn\`). **This is where you build your app.**
+- **\`app/dashboard/page.tsx\`** \u2014 an additional example Server Component route, also session-gated via \`getServerSession()\`.
+
+The design is yours: edit the theme tokens in \`app/globals.css\` (they ship
+colored on purpose, as a starting point) and use any Tailwind colors or
+shadcn blocks you like. A manual "Sign in" landing page is only for a
+\`public_access_allowed\` module \u2014 re-add \`'/'\` to \`middleware.ts\` publicPaths
+and drop the home's session guard to build one.
 - **\`app/api/auth/callback/route.ts\`** \u2014 exchanges the SSO one-time code for a session cookie (uses \`exchangeCode()\` from the SDK).
 - **\`app/api/auth/sign-in/route.ts\`** \u2014 one entry point that calls the backend's \`POST /api/module-api/sso/start-url\` (authenticated with your \`dwk_\` key) and 302s the browser to the returned \`redirect_url\`. Same path in dev + prod.
 - **\`app/api/auth/sign-out/route.ts\`** \u2014 clears the session cookie + tells the backend to revoke.
@@ -924,18 +949,28 @@ function middlewareTs() {
 import { withAuth } from '@dashai/sdk/auth/middleware';
 
 export default withAuth({
-  // \`/sign-in-error\` is public so unauthenticated visitors can actually
-  // see the polished SSO error page \u2014 otherwise a sign-in failure would
-  // redirect-loop trying to re-authenticate.
-  publicPaths: ['/', '/about', '/sign-in-error'],
+  // Only the SSO error page is public. The app's home lives at \`/\`
+  // (app/page.tsx) and is auth-gated like the rest of the app \u2014 a
+  // signed-in platform user still lands there with ZERO clicks because
+  // \`autoSignIn\` (below) completes the handshake silently. There is no
+  // public "sign in" wall in front of your app by default.
+  //
+  // \`/sign-in-error\` stays public so a failed sign-in can render its
+  // error page instead of redirect-looping back into re-authentication.
+  //
+  // Building a \`public_access_allowed\` module that wants an ANONYMOUS
+  // landing page (a marketing / manual "Sign in with DashWise" screen)?
+  // Re-add \`'/'\` here AND make app/page.tsx public (drop its
+  // getServerSession guard). See the README's "Design & home" note.
+  publicPaths: ['/sign-in-error'],
   loginPath: '/api/auth/sign-in',
   // Silent sign-in: when a signed-in DashWise user opens the module through
   // the platform (in-app embed or the module subdomain), the SSO handshake
-  // completes with zero clicks \u2014 they land straight in the app, landing page
-  // included. It never touches:
+  // completes with zero clicks \u2014 they land straight on the page they asked
+  // for, the home at \`/\` included. It never touches:
   //   - anonymous visitors on public installs (no platform-session hint),
-  //   - local \`dashwise dev\` (no platform proxy \u2192 no hint header) \u2014 the
-  //     landing's "Sign in with DashWise" button stays your dev flow,
+  //   - local \`dashwise dev\` (no platform proxy \u2192 no hint header) \u2014 a
+  //     manual sign-in through /api/auth/sign-in stays your dev flow,
   //   - anything within 60s of a failed silent attempt (no redirect loops).
   autoSignIn: true,
 });
@@ -977,84 +1012,118 @@ export default function RootLayout({ children }: { children: React.ReactNode })
 `;
 }
 function appPageCustomTsx(opts) {
-  return `// Public landing page \u2014 listed in middleware.ts publicPaths.
+  return `// app/page.tsx \u2014 the app's REAL home, served at \`/\`. THIS IS YOUR APP.
+// Build it here.
+//
+// A signed-in DashWise user who opens this module through the platform
+// (in-app embed or the module subdomain) lands on THIS page with zero
+// clicks: the middleware's \`autoSignIn\` completes the SSO handshake
+// silently, so there is no sign-in wall in front of your app. The guard
+// below mirrors app/dashboard/page.tsx \u2014 no session \u2192 bounce through the
+// SSO flow and come right back to \`/\`.
 //
-// NOTE: signed-in DashWise users usually never see this page \u2014 the
-// middleware's \`autoSignIn\` signs them in silently and they land on the
-// page they asked for. This landing serves anonymous visitors (public
-// installs), local \`dashwise dev\`, and the rare failed silent attempt \u2014
-// its "Sign in with DashWise" button is the manual fallback that kicks
-// off the same SSO flow (via /api/auth/sign-in). After signing in, the
-// user lands on /dashboard (Server Component, session-validated).
+// A public, anonymous sign-in landing page is only for a
+// \`public_access_allowed\` module that wants an unauthenticated entry
+// point. To build one, re-add \`'/'\` to middleware.ts publicPaths and drop
+// the getServerSession guard here (see the README's "Design & home" note).
 //
-// Styling: shadcn/ui primitives (\`<Button>\`, \`<Card>\`) on Tailwind 4
-// theme tokens. Add more blocks via \`npx shadcn add @shadcn-studio/...\`
-// (see README's "Adding UI blocks" section).
+// The design is YOURS to own. These shadcn primitives sit on the theme
+// tokens in app/globals.css \u2014 edit the hues freely \u2014 and the full
+// Tailwind palette (bg-indigo-600, text-emerald-500, \u2026) is available too.
+// This colored starter look is a starting point, not a mandate.
 import Link from 'next/link';
-import { LogIn, LayoutDashboard } from 'lucide-react';
+import { getServerSession } from '@dashai/sdk/auth/server';
+import { redirect } from 'next/navigation';
+import { ArrowRight, Table2, Database, PenLine } from 'lucide-react';
 import { Button } from '@/components/ui/button';
 import {
   Card,
-  CardContent,
   CardDescription,
   CardHeader,
   CardTitle,
 } from '@/components/ui/card';
 
-export default function Page() {
+// force-dynamic: this page calls getServerSession() at render, which
+// reads DASHWISE_API_URL/KEY. \`next build\` statically PRERENDERS pages by
+// default and runs with NO DashWise env, so the SDK would throw
+// "missing apiBaseUrl" and the platform's first publish would fail with
+// an opaque BUILD_FAILED. Opting into dynamic rendering skips prerender.
+export const dynamic = 'force-dynamic';
+
+export default async function Home() {
+  const session = await getServerSession();
+  if (!session) {
+    redirect('/api/auth/sign-in?return_to=/');
+  }
   return (
-    <main className="flex min-h-dvh flex-col items-center justify-center gap-12 px-6 py-16">
-      <section className="flex max-w-2xl flex-col items-center gap-6 text-center">
-        <h1 className="text-balance text-4xl font-semibold tracking-tight sm:text-5xl">
+    <main className="mx-auto flex min-h-dvh max-w-4xl flex-col gap-10 px-6 py-12">
+      {/* Primary-colored hero \u2014 the default look is colored on purpose,
+          to signal the design is yours to change. */}
+      <section className="flex flex-col gap-4 rounded-2xl bg-primary px-8 py-12 text-primary-foreground shadow-sm">
+        <p className="text-sm font-medium uppercase tracking-wide opacity-80">
           ${escapeHtml(opts.name)}
+        </p>
+        <h1 className="text-balance text-4xl font-semibold tracking-tight sm:text-5xl">
+          Your app starts here.
         </h1>
-        <p className="text-balance text-lg text-muted-foreground">
-          A DashWise module. Sign in with your DashWise account to access the
-          dashboard and start using the workspace's data through the typed SDK.
+        <p className="max-w-xl text-pretty text-lg opacity-90">
+          Signed in as{' '}
+          <span className="font-medium">{session.user.email}</span>. This is the
+          real home of your module \u2014 edit{' '}
+          <code className="rounded bg-primary-foreground/15 px-1.5 py-0.5 font-mono">
+            app/page.tsx
+          </code>{' '}
+          to build it.
         </p>
-        <div className="flex flex-wrap items-center justify-center gap-3">
-          <Button asChild size="lg">
-            <Link href="/api/auth/sign-in?return_to=/dashboard">
-              <LogIn aria-hidden="true" />
-              Sign in with DashWise
-            </Link>
-          </Button>
-          <Button asChild variant="ghost" size="lg">
+        <div className="flex flex-wrap gap-3 pt-2">
+          <Button asChild size="lg" variant="secondary">
             <Link href="/dashboard">
-              <LayoutDashboard aria-hidden="true" />
-              Go to dashboard
+              See the example route
+              <ArrowRight aria-hidden="true" />
             </Link>
           </Button>
         </div>
       </section>
 
-      <Card className="w-full max-w-2xl">
-        <CardHeader>
-          <CardTitle>What you can do here</CardTitle>
-          <CardDescription>
-            This is a custom DashWise module \u2014 a full Next.js app authenticated
-            against the DashWise SSO. Edit \`app/page.tsx\` to replace this
-            landing page; everything else is yours to customize.
-          </CardDescription>
-        </CardHeader>
-        <CardContent className="text-sm text-muted-foreground">
-          <ul className="space-y-2">
-            <li>
-              Edit <code className="rounded bg-muted px-1.5 py-0.5">module.json</code>
-              {' '}to declare tables, dependencies, and runtime config.
-            </li>
-            <li>
-              Run <code className="rounded bg-muted px-1.5 py-0.5">dashwise dev</code>
-              {' '}for a one-command local loop with auth env vars auto-injected.
-            </li>
-            <li>
-              Import typed table clients from{' '}
-              <code className="rounded bg-muted px-1.5 py-0.5">@dashai/generated</code>
-              {' '}\u2014 the SDK regenerates on every manifest save.
-            </li>
-          </ul>
-        </CardContent>
-      </Card>
+      {/* A few colored pointers to get moving. */}
+      <section className="grid gap-4 sm:grid-cols-3">
+        <Card className="border-l-4 border-l-chart-1">
+          <CardHeader>
+            <Table2 className="size-5 text-chart-1" aria-hidden="true" />
+            <CardTitle className="text-base">Declare your data</CardTitle>
+            <CardDescription>
+              Add tables to{' '}
+              <code className="rounded bg-muted px-1 py-0.5 font-mono">module.json</code>{' '}
+              (or run{' '}
+              <code className="rounded bg-muted px-1 py-0.5 font-mono">dashwise table create</code>).
+            </CardDescription>
+          </CardHeader>
+        </Card>
+        <Card className="border-l-4 border-l-chart-2">
+          <CardHeader>
+            <Database className="size-5 text-chart-2" aria-hidden="true" />
+            <CardTitle className="text-base">Read it, typed</CardTitle>
+            <CardDescription>
+              Import{' '}
+              <code className="rounded bg-muted px-1 py-0.5 font-mono">db</code>{' '}
+              from{' '}
+              <code className="rounded bg-muted px-1 py-0.5 font-mono">@dashai/generated</code>{' '}
+              \u2014 regenerated on every manifest save.
+            </CardDescription>
+          </CardHeader>
+        </Card>
+        <Card className="border-l-4 border-l-chart-3">
+          <CardHeader>
+            <PenLine className="size-5 text-chart-3" aria-hidden="true" />
+            <CardTitle className="text-base">Write via server actions</CardTitle>
+            <CardDescription>
+              Mutate data from Server Actions / route handlers so the scoped{' '}
+              <code className="rounded bg-muted px-1 py-0.5 font-mono">dwk_</code>{' '}
+              key stays server-side.
+            </CardDescription>
+          </CardHeader>
+        </Card>
+      </section>
     </main>
   );
 }
@@ -1074,18 +1143,25 @@ import {
 } from '@/components/ui/card';
 
 /**
- * Auth-gated Server Component. The middleware ensures the user has
- * a session cookie before this page renders; \`getServerSession()\`
+ * An ADDITIONAL example route \u2014 your real home is app/page.tsx (\`/\`).
+ * This \`/dashboard\` page is here to show a second auth-gated Server
+ * Component: keep it, rename it, or delete it. The middleware ensures the
+ * user has a session cookie before this page renders; \`getServerSession()\`
  * validates the cookie against the backend's \`/api/auth/sessions/me\`
  * endpoint, returning the decoded \`Session\` (or \`null\` if stale).
  *
  * On a successful render, this is the polished session card \u2014 replace
  * the contents with whatever your module actually needs to show.
  */
+// force-dynamic: same reason as app/page.tsx \u2014 this route calls
+// getServerSession() at render, which needs DASHWISE_API_URL/KEY. Static
+// prerender during \`next build\` runs with no env \u2192 BUILD_FAILED. Opt out.
+export const dynamic = 'force-dynamic';
+
 export default async function Dashboard() {
   const session = await getServerSession();
   if (!session) {
-    redirect('/api/auth/sign-in?return_to=/dashboard');
+    redirect('/api/auth/sign-in?return_to=/');
   }
   return (
     <main className="mx-auto flex min-h-dvh max-w-3xl flex-col gap-6 px-6 py-12">
@@ -1138,7 +1214,9 @@ export default async function Dashboard() {
         <CardHeader>
           <CardTitle>Next steps</CardTitle>
           <CardDescription>
-            Replace this dashboard with your module's actual UI.
+            This is an extra example route \u2014 your real home is{' '}
+            <code className="rounded bg-muted px-1.5 py-0.5">app/page.tsx</code>.
+            Keep, rename, or delete this one.
           </CardDescription>
         </CardHeader>
         <CardContent className="space-y-2 text-sm text-muted-foreground">
@@ -1529,7 +1607,12 @@ export default config;
 `;
 }
 function globalsCss() {
-  return `@import "tailwindcss";
+  return `/* These theme tokens are a STARTING POINT \u2014 change the hues freely.
+   The default \`--primary\` is a violet/indigo and the \`--chart-*\` ramp is
+   a 5-hue set; swap them for your brand. The full Tailwind color palette
+   (bg-indigo-600, text-emerald-500, \u2026) is also available on top of these
+   tokens. This is YOUR design to own. */
+@import "tailwindcss";
 @import "tw-animate-css";
 @import "shadcn/tailwind.css";
 
@@ -1542,20 +1625,33 @@ function globalsCss() {
   --card-foreground: oklch(0.14 0 0);
   --popover: oklch(1 0 0);
   --popover-foreground: oklch(0.14 0 0);
-  --primary: oklch(0.2 0 0);
-  --primary-foreground: oklch(0.99 0 0);
-  --secondary: oklch(0.97 0 0);
-  --secondary-foreground: oklch(0.2 0 0);
-  --muted: oklch(0.97 0 0);
-  --muted-foreground: oklch(0.56 0 0);
-  --accent: oklch(0.97 0 0);
-  --accent-foreground: oklch(0.2 0 0);
+  /* Colored primary (violet/indigo, ~indigo-600). White foreground reads
+     cleanly on it (~5:1). Change the hue (275) to re-brand. */
+  --primary: oklch(0.55 0.22 275);
+  --primary-foreground: oklch(0.985 0 0);
+  /* secondary + muted stay near-neutral (clean UI) but carry a faint
+     violet tint so nothing is pure grayscale. */
+  --secondary: oklch(0.97 0.005 275);
+  --secondary-foreground: oklch(0.25 0.02 275);
+  --muted: oklch(0.97 0.005 275);
+  --muted-foreground: oklch(0.55 0.02 275);
+  /* accent = a soft, low-chroma wash of the primary hue. */
+  --accent: oklch(0.96 0.03 275);
+  --accent-foreground: oklch(0.4 0.1 275);
   --destructive: oklch(0.58 0.24 28.48);
   --border: oklch(0.92 0 0);
   --input: oklch(0.92 0 0);
-  --ring: oklch(0.71 0 0);
+  --ring: oklch(0.55 0.2 275);
   --radius: 0.625rem;
 
+  /* 5-hue chart ramp \u2014 distinct, readable hues for data viz + accents.
+     Wired to \`bg-chart-1\` \u2026 \`text-chart-5\` via the @theme block below. */
+  --chart-1: oklch(0.55 0.2 275);
+  --chart-2: oklch(0.6 0.13 195);
+  --chart-3: oklch(0.7 0.16 70);
+  --chart-4: oklch(0.65 0.17 145);
+  --chart-5: oklch(0.6 0.22 15);
+
   --font-sans:
     ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont,
     "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif;
@@ -1571,18 +1667,37 @@ function globalsCss() {
   --card-foreground: oklch(0.99 0 0);
   --popover: oklch(0.2 0 0);
   --popover-foreground: oklch(0.99 0 0);
-  --primary: oklch(0.92 0 0);
-  --primary-foreground: oklch(0.2 0 0);
-  --secondary: oklch(0.27 0 0);
+  /* Slightly lighter violet so it pops on the dark background; white
+     foreground stays readable (~4.8:1). */
+  --primary: oklch(0.58 0.21 275);
+  --primary-foreground: oklch(0.985 0 0);
+  --secondary: oklch(0.27 0.01 275);
   --secondary-foreground: oklch(0.99 0 0);
-  --muted: oklch(0.27 0 0);
-  --muted-foreground: oklch(0.71 0 0);
-  --accent: oklch(0.27 0 0);
-  --accent-foreground: oklch(0.99 0 0);
+  --muted: oklch(0.27 0.01 275);
+  --muted-foreground: oklch(0.71 0.02 275);
+  --accent: oklch(0.3 0.04 275);
+  --accent-foreground: oklch(0.97 0.01 275);
   --destructive: oklch(0.7 0.19 22.23);
   --border: oklch(0.27 0 0);
   --input: oklch(0.27 0 0);
-  --ring: oklch(0.56 0 0);
+  --ring: oklch(0.58 0.19 275);
+
+  --chart-1: oklch(0.62 0.19 275);
+  --chart-2: oklch(0.67 0.13 195);
+  --chart-3: oklch(0.75 0.15 70);
+  --chart-4: oklch(0.7 0.16 145);
+  --chart-5: oklch(0.67 0.2 15);
+}
+
+/* Wire the chart tokens into Tailwind's color namespace so \`bg-chart-1\`,
+   \`text-chart-2\`, \`border-l-chart-3\`, \u2026 resolve. (\`@import "shadcn/tailwind.css"\`
+   already maps the core tokens like \`--primary\`; this covers the ramp.) */
+@theme inline {
+  --color-chart-1: var(--chart-1);
+  --color-chart-2: var(--chart-2);
+  --color-chart-3: var(--chart-3);
+  --color-chart-4: var(--chart-4);
+  --color-chart-5: var(--chart-5);
 }
 
 * {
@@ -1853,13 +1968,13 @@ export default async function SignInErrorPage({ searchParams }: SignInErrorPageP
           )}
           <div className="flex flex-wrap gap-2 pt-2">
             <Button asChild>
-              <Link href="/api/auth/sign-in?return_to=/dashboard">
+              <Link href="/api/auth/sign-in?return_to=/">
                 <RefreshCw aria-hidden="true" />
                 Try again
               </Link>
             </Button>
             <Button asChild variant="ghost">
-              <Link href="/">Back to landing</Link>
+              <Link href="/">Back to home</Link>
             </Button>
           </div>
         </CardContent>
@@ -1941,10 +2056,10 @@ dashwise field remove <table> <slug>
 dashwise field set-type <table> <slug> <type>
 \`\`\`
 
-Allowed field types: \`text\`, \`long_text\`, \`number\`, \`boolean\`,
+Allowed field types (18): \`text\`, \`long_text\`, \`number\`, \`boolean\`,
 \`date\`, \`datetime\`, \`single_select\`, \`multi_select\`,
 \`link_row\`, \`file\`, \`multi_file\`, \`email\`, \`url\`,
-\`phone\`, \`formula\`, \`ai\`.
+\`phone\`, \`formula\`, \`ai\`, \`uuid\`, \`jsonb\`.
 
 ## Read + write data via the generated SDK
 
@@ -1959,8 +2074,10 @@ import { db, qb } from '@dashai/generated';
 const rows = await db.<table>.list();
 await db.<table>.create({ /* fields */ });
 
-// Query builder (joins, aggregates)
-const stats = await qb.from('<table>').where({ /* ... */ }).execute();
+// Query builder \u2014 a per-table getter (NOT a \`.from()\` call); \`.where()\`
+// takes a single clause object (field \u2192 value or field \u2192 operator), and
+// \`.execute()\` runs it. Chain \`.orderBy()\` / \`.limit()\` / \`.count()\` etc.
+const open = await qb.<table>.where({ status: { equal: 'open' } }).execute();
 \`\`\`
 
 The data plane authenticates via the per-module scoped \`dwk_\` API key
@@ -2006,7 +2123,37 @@ In Server Components: \`await getServerSession()\` (from
 In Client Components: \`useSession()\` (from
 \`@dashai/sdk/auth/client\`), wrapped in \`<AuthProvider>\` (already
 in \`app/layout.tsx\`).
-
+${isCustom ? `
+## Design & home
+
+You OWN the UI \u2014 layout, components, and colors. Edit the theme tokens in
+\`app/globals.css\` freely (they're a starting point, not a mandate), reach
+for any Tailwind color (\`bg-indigo-600\`, \`text-emerald-500\`, \u2026), and pull
+in more shadcn blocks (see the README's "Adding UI blocks").
+
+The app's **home is \`app/page.tsx\`, served at \`/\`** \u2014 build the real app
+there. It's auth-gated: a platform user lands on it zero-click (the
+middleware's \`autoSignIn\` signs them in silently), and \`app/dashboard/page.tsx\`
+is just an extra example route. A manual "Sign in with DashWise" landing
+page belongs ONLY to a \`public_access_allowed\` module that wants an
+anonymous entry point (re-add \`'/'\` to \`middleware.ts\` publicPaths + drop
+the home's session guard to build one).
+
+## Before you publish
+
+Add \`export const dynamic = 'force-dynamic'\` to the top of ANY page that
+reads the session or data at render (calls \`getServerSession()\` or a
+\`dwk_\`-authenticated data call). Without it, \`next build\` statically
+prerenders the page with NO DashWise env vars, the SDK throws
+\`missing apiBaseUrl\`, and the platform's first publish fails with an
+opaque \`BUILD_FAILED\`. The scaffolded \`app/page.tsx\` + \`app/dashboard/page.tsx\`
+already have it \u2014 any new session-gated page you add needs it too.
+
+A passing local \`npm run build\` is NOT proof: your \`.env.local\` supplies
+the env the platform build won't have, so it masks the failure. \`GET\` route
+handlers under \`app/api/*\` are dynamic by default in Next 15, so they don't
+hit this trap.
+` : ""}
 ## Local dev lifecycle
 
 \`\`\`
@@ -5200,6 +5347,386 @@ async function moduleDiffCommand(options) {
 // src/bin.ts
 init_init();
 
+// src/commands/module/install.ts
+init_api_client();
+init_config();
+init_manifest_io();
+
+// src/lib/module-lifecycle.ts
+init_api_client();
+init_output();
+init_workspaces();
+function isDevInstallKind(kind) {
+  return kind === "local" || kind === "sandbox";
+}
+function isRealRuntimeUrl(url) {
+  return !!url && /^https:\/\//i.test(url);
+}
+function isDraftVersion(v) {
+  return !v || v.includes("draft");
+}
+function compareSemver(a, b) {
+  const parse = (v) => v.split("-")[0].split(".").map((n) => Number.parseInt(n, 10) || 0);
+  const pa = parse(a);
+  const pb = parse(b);
+  for (let i = 0; i < 3; i++) {
+    const d = (pa[i] ?? 0) - (pb[i] ?? 0);
+    if (d !== 0) return d > 0 ? 1 : -1;
+  }
+  return 0;
+}
+function isUpdateAvailable(installedVersion, latestVersion) {
+  return !!installedVersion && !!latestVersion && !isDraftVersion(installedVersion) && !isDraftVersion(latestVersion) && compareSemver(latestVersion, installedVersion) > 0;
+}
+async function resolveWorkspaceWithFallback(opts) {
+  const fromCache = opts.userFlag === void 0 && opts.cachedWorkspaceId !== void 0;
+  const flag = opts.userFlag ?? (fromCache ? String(opts.cachedWorkspaceId) : opts.configDefault);
+  try {
+    return await selectWorkspace({
+      apiUrl: opts.apiUrl,
+      apiToken: opts.apiToken,
+      ...flag !== void 0 ? { flag } : {},
+      interactive: true
+    });
+  } catch (err) {
+    if (!fromCache || err instanceof ApiError) throw err;
+    info(
+      `Cached dev-install workspace ${code(String(opts.cachedWorkspaceId))} is no longer accessible \u2014 pick a workspace.`
+    );
+    return await selectWorkspace({
+      apiUrl: opts.apiUrl,
+      apiToken: opts.apiToken,
+      ...opts.configDefault !== void 0 ? { flag: opts.configDefault } : {},
+      interactive: true
+    });
+  }
+}
+
+// src/commands/module/install.ts
+init_output();
+async function moduleInstallCommand(slugArg, options) {
+  const slug = resolveSlug(slugArg, options.dir);
+  if (!slug) {
+    fail(
+      `No module slug \u2014 pass one (${code("dashwise module install <slug>")}) or run from a directory with a valid module.json.`
+    );
+    return 1;
+  }
+  if (!isLoggedIn()) {
+    fail(`Not logged in. Run ${code("dashwise login")} first.`);
+    return 1;
+  }
+  const cfg = readConfig();
+  if (!cfg) {
+    fail(`CLI config missing. Run ${code("dashwise login")}.`);
+    return 1;
+  }
+  const auth = { baseUrl: resolveApiUrl(), auth: { token: cfg.token } };
+  let mod;
+  try {
+    mod = await getModuleBySlug(slug, auth);
+  } catch (err) {
+    if (err instanceof ApiError && err.status === 404) {
+      fail(
+        `Module ${code(slug)} not found on the backend. Run ${code("dashwise module register")} + ${code("dashwise module publish")} first.`
+      );
+      return 1;
+    }
+    fail(`Could not resolve module ${code(slug)}: ${err.message}`);
+    return 1;
+  }
+  if (!mod.current_version) {
+    fail(
+      `Module ${code(slug)} has no published version yet \u2014 nothing to install. Run ${code("dashwise module publish")} first.`
+    );
+    return 1;
+  }
+  const targetVersion = options.version ?? mod.current_version;
+  let workspace2;
+  try {
+    workspace2 = await resolveWorkspaceWithFallback({
+      userFlag: options.workspace,
+      cachedWorkspaceId: readModuleEntry(slug)?.workspaceId,
+      configDefault: cfg.workspaceSlug,
+      apiUrl: resolveApiUrl(),
+      apiToken: cfg.token
+    });
+  } catch (err) {
+    fail(`Workspace selection failed: ${err.message}`);
+    return 1;
+  }
+  let existing;
+  try {
+    const installs = await listWorkspaceInstallations(workspace2.id, auth);
+    existing = installs.find((row2) => row2.module_id === mod.id);
+  } catch (err) {
+    fail(
+      `Could not read workspace installations: ${err.message}`
+    );
+    return 1;
+  }
+  let isUpgrade = false;
+  let devInstallToReplace;
+  let confirmedViaPicker = false;
+  if (existing && isDevInstallKind(existing.kind)) {
+    const resolution = await resolveDevInstallCollision(
+      existing,
+      slug,
+      workspace2.slug,
+      options
+    );
+    if (typeof resolution === "number") return resolution;
+    devInstallToReplace = existing;
+    confirmedViaPicker = resolution === "replace-confirmed";
+    existing = void 0;
+  } else if (existing) {
+    isUpgrade = true;
+    const installedVersion2 = existing.module_version?.version;
+    if (installedVersion2 && installedVersion2 === targetVersion) {
+      info(
+        `Already deployed at ${code(`v${installedVersion2}`)} \u2014 re-running is idempotent and repairs a failed provision.`
+      );
+    } else {
+      info(
+        `Existing production install #${existing.id}${installedVersion2 ? ` at ${code(`v${installedVersion2}`)}` : ""} \u2014 this will upgrade it to ${code(`v${targetVersion}`)}.`
+      );
+    }
+  }
+  if (!options.yes && process.stdout.isTTY && !confirmedViaPicker) {
+    const message = devInstallToReplace ? `Replace the dev install (revokes local-dev credentials) and install ${code(mod.slug)} ${code(`v${targetVersion}`)} into ${code(workspace2.slug)} as production?` : `${isUpgrade ? "Upgrade" : "Install"} ${code(mod.slug)} ${code(`v${targetVersion}`)} into workspace ${code(workspace2.slug)}?`;
+    const answer = await select({
+      message,
+      options: [
+        {
+          value: "go",
+          label: devInstallToReplace ? "Yes, replace the dev install + production-install" : isUpgrade ? "Yes, upgrade now" : "Yes, install now"
+        },
+        { value: "cancel", label: "No, abort" }
+      ],
+      initialValue: devInstallToReplace ? "cancel" : "go"
+    });
+    if (isCancel(answer) || answer === "cancel") {
+      fail("Aborted. Nothing was changed.");
+      return 130;
+    }
+  }
+  let devInstallReplaced = false;
+  if (devInstallToReplace) {
+    const destroyed = await replaceDevInstall(devInstallToReplace, slug, auth);
+    if (destroyed !== 0) return destroyed;
+    devInstallReplaced = true;
+  }
+  info("Provisioning the runtime \u2014 this can take a minute\u2026");
+  let result;
+  try {
+    result = await installModule(
+      mod.id,
+      {
+        workspaceId: workspace2.id,
+        ...options.version !== void 0 ? { version: options.version } : {},
+        ...options.force !== void 0 ? { force: options.force } : {}
+      },
+      auth
+    );
+  } catch (err) {
+    return surfaceInstallError(err, mod.slug, workspace2.slug, devInstallReplaced);
+  }
+  if (isInstallGated(result)) {
+    if (options.json) {
+      out(JSON.stringify(result));
+      return 0;
+    }
+    success(
+      `Install request ${code(`#${result.install_request.id}`)} queued (status: ${result.install_request.status}).`
+    );
+    info(
+      `This module requires author approval before it installs. Once approved, check with ${code(`dashwise module status ${mod.slug} --workspace ${workspace2.slug}`)}.`
+    );
+    return 0;
+  }
+  let row;
+  let verified = false;
+  try {
+    const after = await listWorkspaceInstallations(workspace2.id, auth);
+    row = after.find((r) => r.module_id === mod.id);
+    verified = row !== void 0;
+  } catch {
+  }
+  const publicUrl = row?.public_url ?? null;
+  const installedVersion = row?.module_version?.version ?? targetVersion;
+  const runtimeProvisioned = isRealRuntimeUrl(row?.runtime_url);
+  if (options.json) {
+    out(
+      JSON.stringify({
+        installation_id: result.installation.id,
+        kind: row?.kind ?? null,
+        version: installedVersion,
+        was_upgrade: result.was_upgrade,
+        public_url: publicUrl,
+        verified
+      })
+    );
+    return 0;
+  }
+  if (!verified) {
+    success(
+      `Installed ${code(mod.slug)} ${code(`v${targetVersion}`)} (install ${code(`#${result.installation.id}`)}).`
+    );
+    info(
+      `The verification read failed \u2014 run ${code(`dashwise module status ${mod.slug} --workspace ${workspace2.slug}`)} to see the deploy state and public URL.`
+    );
+    return 0;
+  }
+  if (runtimeProvisioned && publicUrl) {
+    success(
+      `Deployed ${code(mod.slug)} ${code(`v${installedVersion}`)} \u2014 live at ${code(publicUrl)}`
+    );
+    info(
+      `Install ${code(`#${result.installation.id}`)} (kind=${row?.kind ?? "unknown"}) in workspace ${code(workspace2.slug)}${result.was_upgrade ? " \u2014 upgraded in place." : "."}`
+    );
+  } else if (runtimeProvisioned) {
+    success(
+      `Installed ${code(mod.slug)} ${code(`v${installedVersion}`)} (install ${code(`#${result.installation.id}`)}, kind=${row?.kind ?? "unknown"}).`
+    );
+    warn(
+      `The runtime is provisioned, but this platform exposes no public host \u2014 there is no public URL to print. Ask the operator to configure the public module host; re-running install won't change this.`
+    );
+  } else {
+    success(
+      `Installed ${code(mod.slug)} ${code(`v${installedVersion}`)} (install ${code(`#${result.installation.id}`)}, kind=${row?.kind ?? "unknown"}).`
+    );
+    warn(
+      `No public URL yet \u2014 runtime provisioning didn't complete. Re-running ${code("dashwise module install")} is idempotent and repairs a failed provision.`
+    );
+  }
+  return 0;
+}
+function resolveSlug(slugArg, dir) {
+  if (slugArg) return slugArg;
+  try {
+    const manifest = readManifest(dir);
+    const slug = manifest?.module?.slug;
+    return typeof slug === "string" && slug.length > 0 ? slug : void 0;
+  } catch {
+    return void 0;
+  }
+}
+async function resolveDevInstallCollision(existing, slug, workspaceSlug, options) {
+  if (existing.kind === "sandbox") {
+    fail(
+      `Workspace ${code(workspaceSlug)} already has a ${code("kind=sandbox")} install of ${code(slug)} (id=${existing.id}), and only ONE install per (workspace, module) can exist.
+  A plain install would upgrade that row in place \u2014 but ${code("kind")} is immutable, so it would stay sandbox and hidden from the app sidebar.
+  The CLI can't destroy a sandbox install. Uninstall it from the dashboard first, or deploy with ${code("--workspace <other>")} to a separate workspace.`
+    );
+    return 1;
+  }
+  const explanation = `Workspace ${code(workspaceSlug)} already has the DEV install of ${code(slug)} (kind=local, id=${existing.id}) created by ${code("dashwise init")}.
+  Only ONE install per (workspace, module) can exist, and ${code("kind")} is immutable: a plain install would upgrade that row in place \u2014 the runtime would provision, but it would STAY a dev install, hidden from the app sidebar.
+  Options:
+    - ${code("--replace-dev-install")} \u2014 destroy the dev install, then fresh production install. Recommended when development is done. Note: this revokes the module's cached local-dev credentials, so local ${code("dashwise dev")} against this workspace needs a fresh ${code("dashwise init --force")} afterwards (which in turn cannot coexist with the production install here).
+    - ${code("--workspace <other>")} \u2014 deploy to a separate test/client workspace and keep this dev install. Recommended for ongoing development.`;
+  if (options.replaceDevInstall) return "replace";
+  if (process.stdout.isTTY && !options.yes) {
+    info(explanation);
+    const answer = await select({
+      message: `Replace the dev install of ${code(slug)} in ${code(workspaceSlug)} with a production install? (revokes local-dev credentials)`,
+      options: [
+        {
+          value: "replace",
+          label: "Replace \u2014 destroy the dev install, then production-install",
+          hint: "local `dashwise dev` here will need `dashwise init --force` afterwards"
+        },
+        { value: "cancel", label: "Cancel \u2014 I will deploy to another workspace" }
+      ],
+      initialValue: "cancel"
+    });
+    if (isCancel(answer) || answer === "cancel") {
+      fail("Aborted. Nothing was changed.");
+      return 130;
+    }
+    return "replace-confirmed";
+  }
+  fail(explanation);
+  return 1;
+}
+async function replaceDevInstall(existing, slug, auth) {
+  info(`Destroying dev install ${code(`#${existing.id}`)} (kind=local)\u2026`);
+  try {
+    await destroyDevInstallation(existing.id, auth);
+  } catch (err) {
+    if (err instanceof ApiError && err.code === "INSTALLATION_NOT_FOUND") {
+      warn("Dev install already gone server-side \u2014 continuing.");
+    } else if (err instanceof ApiError) {
+      fail(
+        `Could not destroy the dev install (${err.code} ${err.status}): ${err.message}`
+      );
+      return 1;
+    } else {
+      fail(`Could not destroy the dev install: ${err.message}`);
+      return 1;
+    }
+  }
+  const entry = readModuleEntry(slug);
+  if (entry && entry.installationId === existing.id) {
+    try {
+      removeModuleEntry(slug);
+      info(
+        `Removed ${code(slug)} from auth.json \u2014 its local-dev credentials are revoked. Local ${code("dashwise dev")} needs ${code("dashwise init --force")} (ideally against a different workspace).`
+      );
+    } catch (err) {
+      warn(
+        `Dev install destroyed but auth.json cleanup failed: ${err.message}. Remove the ${code(`modules["${slug}"]`)} entry from ${code("~/.config/dashwise/auth.json")} manually.`
+      );
+    }
+  }
+  return 0;
+}
+function surfaceInstallError(err, slug, workspaceSlug, devInstallReplaced) {
+  if (err instanceof ApiError) {
+    switch (err.code) {
+      case "INSTALL_NOT_INVITED":
+        fail(
+          `Module ${code(slug)} is invite-only and workspace ${code(workspaceSlug)} hasn't been invited.
+  Ask the module's author to invite this workspace (or open the install gate), then retry.`
+        );
+        break;
+      case "UPGRADE_BREAKS_CONSUMERS":
+        fail(
+          `Upgrading ${code(slug)} would break modules that consume its current schema.
+  Review the breaking changes, then re-run with ${code("--force")} to upgrade anyway.`
+        );
+        break;
+      case "FORBIDDEN":
+        fail(
+          `You must be an ADMIN of workspace ${code(workspaceSlug)} to install modules into it.`
+        );
+        break;
+      case "UNAUTHENTICATED":
+        fail(
+          `Auth rejected by the backend \u2014 your CLI token may be stale. Re-run ${code("dashwise login")} and try again.`
+        );
+        break;
+      default:
+        if (err.status === 400 && /publish/i.test(err.message)) {
+          fail(
+            `${err.message}
+  Run ${code("dashwise module publish")} first, then retry.`
+          );
+        } else {
+          fail(`Install failed (${err.code || err.status}): ${err.message}`);
+        }
+    }
+  } else {
+    fail(`Install failed: ${err.message}`);
+  }
+  if (devInstallReplaced) {
+    warn(
+      `Note: the dev install was already removed (that is not rolled back). Re-run ${code("dashwise module install")} to complete the production install, or ${code("dashwise init --force")} to restore local dev.`
+    );
+  }
+  return 1;
+}
+
 // src/commands/module/list.ts
 init_api_client();
 init_config();
@@ -5668,6 +6195,140 @@ function formatBytes2(n) {
   return `${(n / 1024 / 1024).toFixed(1)}MB`;
 }
 
+// src/commands/module/status.ts
+init_api_client();
+init_config();
+init_manifest_io();
+init_output();
+async function moduleStatusCommand(slugArg, options) {
+  let slug = slugArg;
+  if (!slug) {
+    try {
+      const manifest = readManifest(options.dir);
+      const fromManifest = manifest?.module?.slug;
+      if (typeof fromManifest === "string" && fromManifest.length > 0) {
+        slug = fromManifest;
+      }
+    } catch {
+    }
+  }
+  if (!slug) {
+    fail(
+      `No module slug \u2014 pass one (${code("dashwise module status <slug>")}) or run from a directory with a valid module.json.`
+    );
+    return 1;
+  }
+  if (!isLoggedIn()) {
+    fail(`Not logged in. Run ${code("dashwise login")} first.`);
+    return 1;
+  }
+  const cfg = readConfig();
+  if (!cfg) {
+    fail(`CLI config missing. Run ${code("dashwise login")}.`);
+    return 1;
+  }
+  const auth = { baseUrl: resolveApiUrl(), auth: { token: cfg.token } };
+  let mod;
+  try {
+    mod = await getModuleBySlug(slug, auth);
+  } catch (err) {
+    if (err instanceof ApiError && err.status === 404) {
+      fail(`Module ${code(slug)} not found on the backend.`);
+      return 1;
+    }
+    fail(`Could not resolve module ${code(slug)}: ${err.message}`);
+    return 1;
+  }
+  let workspace2;
+  try {
+    workspace2 = await resolveWorkspaceWithFallback({
+      userFlag: options.workspace,
+      cachedWorkspaceId: readModuleEntry(slug)?.workspaceId,
+      configDefault: cfg.workspaceSlug,
+      apiUrl: resolveApiUrl(),
+      apiToken: cfg.token
+    });
+  } catch (err) {
+    fail(`Workspace selection failed: ${err.message}`);
+    return 1;
+  }
+  let row;
+  try {
+    const installs = await listWorkspaceInstallations(workspace2.id, auth);
+    row = installs.find((r) => r.module_id === mod.id);
+  } catch (err) {
+    fail(`Could not read workspace installations: ${err.message}`);
+    return 1;
+  }
+  const latestVersion = row?.module?.current_version ?? mod.current_version;
+  if (!row) {
+    if (options.json) {
+      out(
+        JSON.stringify({
+          installed: false,
+          module: mod.slug,
+          workspace: { id: workspace2.id, slug: workspace2.slug },
+          latest_version: latestVersion
+        })
+      );
+      return 0;
+    }
+    info(
+      `${code(mod.slug)} is not installed in workspace ${code(workspace2.slug)}.` + (latestVersion ? ` Deploy it with ${code(`dashwise module install ${mod.slug} --workspace ${workspace2.slug}`)}.` : ` It has no published version yet \u2014 run ${code("dashwise module publish")} first.`)
+    );
+    return 0;
+  }
+  const runtimeProvisioned = isRealRuntimeUrl(row.runtime_url);
+  const state = runtimeProvisioned && row.public_url ? "live" : runtimeProvisioned ? "deployed" : "not_deployed";
+  const installedVersion = row.module_version?.version ?? null;
+  const updateAvailable = isUpdateAvailable(installedVersion, latestVersion);
+  if (options.json) {
+    out(
+      JSON.stringify({
+        installed: true,
+        module: mod.slug,
+        workspace: { id: workspace2.id, slug: workspace2.slug },
+        installation_id: row.id,
+        kind: row.kind ?? null,
+        version: installedVersion,
+        latest_version: latestVersion,
+        update_available: updateAvailable,
+        runtime_provisioned: runtimeProvisioned,
+        runtime_url: row.runtime_url,
+        public_url: row.public_url,
+        state
+      })
+    );
+    return 0;
+  }
+  const stateLabel = state === "live" ? "Live" : state === "deployed" ? "Deployed" : "Not deployed \u2014 runtime not provisioned";
+  out("");
+  kv("Module:", `${mod.slug} ${dim(`(id ${mod.id})`)}`);
+  kv("Workspace:", `${workspace2.slug} ${dim(`(id ${workspace2.id})`)}`);
+  kv("Install:", `#${row.id} ${dim(`(kind=${row.kind ?? "unknown"})`)}`);
+  kv(
+    "Version:",
+    `${installedVersion ?? dim("(unknown)")}${updateAvailable ? `  ${code(`update available: v${latestVersion} \u2014 run \`dashwise module install ${mod.slug}\``)}` : latestVersion ? `  ${dim(`(latest published: v${latestVersion})`)}` : ""}`
+  );
+  kv(
+    "Runtime:",
+    runtimeProvisioned ? `provisioned ${dim(`(${row.runtime_url})`)}` : "not provisioned"
+  );
+  kv("Public URL:", row.public_url ?? dim("(none)"));
+  kv("State:", stateLabel);
+  out("");
+  if (row.kind === "local") {
+    info(
+      `This is the ${code("kind=local")} dev install \u2014 hidden from the app sidebar. A production deploy needs ${code("dashwise module install --replace-dev-install")} (or ${code("--workspace <other>")}).`
+    );
+  } else if (state === "not_deployed") {
+    info(
+      `Re-run ${code(`dashwise module install ${mod.slug} --workspace ${workspace2.slug}`)} to (re-)provision the runtime \u2014 the install POST is idempotent.`
+    );
+  }
+  return 0;
+}
+
 // src/commands/module/pull-data.ts
 init_api_client();
 init_output();
@@ -6289,7 +6950,7 @@ function rangeSatisfied(version, range) {
   const op = opMatch[1] ?? "=";
   const target = parseSemver(opMatch[2]);
   if (!target) return false;
-  const cmp = compareSemver(vParts, target);
+  const cmp = compareSemver2(vParts, target);
   switch (op) {
     case "=":
       return cmp === 0;
@@ -6318,7 +6979,7 @@ function parseSemver(s) {
   if (!m) return null;
   return [Number(m[1]), Number(m[2]), Number(m[3])];
 }
-function compareSemver(a, b) {
+function compareSemver2(a, b) {
   for (let i = 0; i < 3; i++) {
     if (a[i] !== b[i]) return a[i] - b[i];
   }
@@ -9204,6 +9865,35 @@ moduleCmd.command("publish").description("Pack the current directory + upload it
     });
   }
 );
+moduleCmd.command("install [slug]").alias("deploy").description(
+  "Install (deploy) a published module into a workspace \u2014 provisions the runtime and prints the public URL. Upgrades/repairs an existing production install idempotently. Refuses to silently land on a dev install: use --replace-dev-install or --workspace <other>."
+).option("--workspace <slug-or-id>", "Target workspace (default: cached module workspace, config default, or interactive picker).").option("--version <semver>", "Install a specific published version (default: latest).").option("--force", "Proceed even when the upgrade breaks consumer modules (UPGRADE_BREAKS_CONSUMERS).").option(
+  "--replace-dev-install",
+  "Destroy the workspace's kind=local dev install first, then fresh production install. Revokes the module's cached local-dev credentials (re-run `dashwise init --force` for local dev afterwards)."
+).option("--dir <path>", "Project root for the module.json slug lookup (default: current directory).").option("-y, --yes", "Skip the confirmation prompt (for CI / scripted use).").option("--json", "Emit the final result as machine-readable JSON.").action(
+  async (slug, cmdOpts) => {
+    process.exitCode = await moduleInstallCommand(slug, {
+      ...cmdOpts.workspace !== void 0 ? { workspace: cmdOpts.workspace } : {},
+      ...cmdOpts.version !== void 0 ? { version: cmdOpts.version } : {},
+      ...cmdOpts.force !== void 0 ? { force: cmdOpts.force } : {},
+      ...cmdOpts.replaceDevInstall !== void 0 ? { replaceDevInstall: cmdOpts.replaceDevInstall } : {},
+      ...cmdOpts.dir !== void 0 ? { dir: cmdOpts.dir } : {},
+      ...cmdOpts.yes !== void 0 ? { yes: cmdOpts.yes } : {},
+      ...cmdOpts.json !== void 0 ? { json: cmdOpts.json } : {}
+    });
+  }
+);
+moduleCmd.command("status [slug]").description(
+  "Show a module's deploy state in a workspace: install kind, installed vs latest published version, runtime provisioning, and the public URL."
+).option("--workspace <slug-or-id>", "Target workspace (default: cached module workspace, config default, or interactive picker).").option("--dir <path>", "Project root for the module.json slug lookup (default: current directory).").option("--json", "Emit machine-readable JSON.").action(
+  async (slug, cmdOpts) => {
+    process.exitCode = await moduleStatusCommand(slug, {
+      ...cmdOpts.workspace !== void 0 ? { workspace: cmdOpts.workspace } : {},
+      ...cmdOpts.dir !== void 0 ? { dir: cmdOpts.dir } : {},
+      ...cmdOpts.json !== void 0 ? { json: cmdOpts.json } : {}
+    });
+  }
+);
 moduleCmd.command("query-log").description(
   "Read the per-module SDK query log. Default: 50 most recent entries. `--slow` filters to duration_ms > 500ms; `--since 1h` narrows by time; `--tail` streams new entries every 5s."
 ).option(
@@ -9381,7 +10071,7 @@ fieldCmd.command("set-type <table-slug> <field-slug> <new-type>").description(
   }
 })();
 function getVersion() {
-  return "0.12.1";
+  return "0.14.0";
 }
 function parseIntOption(value) {
   const n = Number.parseInt(value, 10);