@dashai/cli 0.3.0 → 0.3.1

package/dist/bin.js

@@ -381,12 +381,7 @@ function manifestJson(opts) {
     },
     module_kind: kind,
     owns: {
-      tables: [
-        {
-          slug: "items",
-          fields: [{ slug: "title", type: "text", required: true }]
-        }
-      ]
+      tables: []
     }
   };
   if (kind === "custom") {
@@ -505,41 +500,42 @@ function gitignore() {
     ""
   ].join("\n");
 }
-function envLocalExample() {
+function envLocalExample(apiUrl = SCAFFOLD_DEFAULT_API_URL) {
   return [
     "# Copy to .env.local + fill in real values.",
     "# These vars are auto-injected by `dashwise dev` (the unified dev loop)",
     "# from ~/.config/dashwise/auth.json \u2014 you only need to edit this file if",
     "# you want to point at a non-default backend or run `next dev` standalone.",
-    "DASHWISE_API_URL=http://localhost:3000",
+    `DASHWISE_API_URL=${apiUrl}`,
     "# Client-side mirror \u2014 Next.js inlines NEXT_PUBLIC_* into the browser",
     "# bundle so the SDK's <AuthProvider> can hit `/api/auth/sessions/me`",
     "# on the right origin. Should match DASHWISE_API_URL above.",
-    "NEXT_PUBLIC_DASHWISE_API_URL=http://localhost:3000",
+    `NEXT_PUBLIC_DASHWISE_API_URL=${apiUrl}`,
     "DASHWISE_API_TOKEN=",
     "DASHWISE_INSTALLATION_ID=local",
     ""
   ].join("\n");
 }
-function envLocal() {
+function envLocal(apiUrl = SCAFFOLD_DEFAULT_API_URL) {
   return [
     "# Local dev config \u2014 auto-generated by `dashwise module init`.",
-    "# Gitignored; safe to edit. `dashwise dev` (the unified loop) auto-",
-    "# injects DASHWISE_API_TOKEN from ~/.config/dashwise/auth.json AND",
+    `# Backend URL pinned to your logged-in CLI config (${apiUrl}). Gitignored;`,
+    "# safe to edit. `dashwise dev` (the unified loop) auto-injects",
+    "# DASHWISE_API_TOKEN from ~/.config/dashwise/auth.json AND",
     "# DASHWISE_DEV_SESSION_ID from the dev session it registers \u2014 so",
     "# you typically don't need to set either here. Change DASHWISE_API_URL",
-    "# (and NEXT_PUBLIC_DASHWISE_API_URL to match) to point at a non-default",
-    "# backend (e.g. https://api.dashwise.net).",
+    "# (and NEXT_PUBLIC_DASHWISE_API_URL to match) to point at a different",
+    "# backend.",
     "#",
     "# DASHWISE_INSTALLATION_ID is only needed AFTER you publish + install",
     "# the module in a workspace; until then dev mode (DASHWISE_DEV_SESSION_ID,",
     "# auto-set by `dashwise dev`) is the auth path.",
-    "DASHWISE_API_URL=http://localhost:3000",
+    `DASHWISE_API_URL=${apiUrl}`,
     "# Client-side mirror (must match DASHWISE_API_URL). Next.js inlines",
     "# NEXT_PUBLIC_* into the browser bundle so the SDK's AuthProvider can",
     "# call /api/auth/sessions/me on the right origin instead of bouncing",
     "# off the local module server with a 404.",
-    "NEXT_PUBLIC_DASHWISE_API_URL=http://localhost:3000",
+    `NEXT_PUBLIC_DASHWISE_API_URL=${apiUrl}`,
     "DASHWISE_API_TOKEN=",
     "DASHWISE_INSTALLATION_ID=",
     ""
@@ -1513,8 +1509,227 @@ function escapeHtml(s) {
 function isValidSlug(slug) {
   return /^[a-z][a-z0-9_-]*$/.test(slug);
 }
+function claudeMd(opts) {
+  const isCustom = (opts.kind ?? "hand_authored") === "custom";
+  return `# CLAUDE.md \u2014 ${opts.name}
+
+Instructions for AI coding agents (Claude Code, Cursor, etc.) working
+in this DashWise module. Read this before making changes.
+
+## What this module is
+
+A DashWise ${isCustom ? "**custom Next.js** module (full app runtime, machine-class)" : "**hand-authored simple** module (isolate runtime)"} authored against \`@dashai/sdk\`.
+Module slug: \`${opts.slug}\`.
+
+DashWise calls apps "modules". A module is a Next.js app + a
+manifest (\`module.json\`) declaring the tables it owns, modules it
+depends on, and actions it exposes. The DashWise backend hosts the
+data plane + auth; this module ships UI + business logic.
+
+## Spec-first, log-every-change
+
+This scaffold mirrors the dashwise-backend convention:
+
+- **\`spec.md\`** is the source of truth for what this module does \u2014
+  tables, fields, API contracts, business rules, error cases. Update
+  it BEFORE writing code that changes behavior. If a behavior isn't
+  in \`spec.md\`, it isn't real yet.
+- **\`agent-log.md\`** is an append-only log of every meaningful
+  change. Every commit that touches \`module.json\`, \`spec.md\`, a
+  schema mutation, or a public surface MUST add an entry. Format:
+
+  \`\`\`
+  ## YYYY-MM-DD HH:MM \u2014 <author or agent name>
+
+  **Change:** one-line summary
+  **Files:** comma-separated list of files
+  **Reason:** why this change was necessary
+  **Spec impact:** none | updated spec.md \xA7<section>
+  \`\`\`
+
+  Reverse chronological (newest first).
+
+## Schema changes go through the CLI, not by hand
+
+\`module.json\` is the manifest. The backend has its own copy that
+the runtime data plane uses. To keep them in sync, mutate via the
+CLI \u2014 \`dashwise table create\`, \`dashwise field add\`, etc. \u2014
+which calls the schema endpoints and rewrites the local
+\`module.json\` from the backend's response. Hand-edits to
+\`module.json\` won't sync until the next CLI mutation picks them up.
+
+Common commands:
+
+\`\`\`
+dashwise table create <slug> --field <slug:type[:required]>
+dashwise table delete <slug>
+dashwise field add <table> <slug:type[:required]>
+dashwise field remove <table> <slug>
+dashwise field set-type <table> <slug> <type>
+\`\`\`
+
+Allowed field types: \`text\`, \`long_text\`, \`number\`, \`boolean\`,
+\`date\`, \`datetime\`, \`single_select\`, \`multi_select\`,
+\`link_row\`, \`file\`, \`multi_file\`, \`email\`, \`url\`,
+\`phone\`, \`formula\`, \`ai\`.
+
+## Read + write data via the generated SDK
+
+The CLI's watcher regenerates typed clients into
+\`node_modules/@dashai/generated/\` every time \`module.json\` changes.
+Import from there:
+
+\`\`\`ts
+import { db, qb } from '@dashai/generated';
+
+// Simple CRUD
+const rows = await db.<table>.list();
+await db.<table>.create({ /* fields */ });
+
+// Query builder (joins, aggregates)
+const stats = await qb.from('<table>').where({ /* ... */ }).execute();
+\`\`\`
+
+The data plane authenticates via the per-module runtime token cached
+in \`~/.config/dashwise/auth.json#modules[${opts.slug}]\` after
+\`dashwise init\` provisions the dev install. \`dashwise dev\` injects
+this token into the Next.js child env automatically.
+
+## Auth in dev mode
+
+\`dashwise dev\` registers a dev-mode SSO session with the backend
+and injects \`DASHWISE_DEV_SESSION_ID\` so workspace members can sign
+into the locally-running module via DashWise SSO \u2014 no installed
+\`installation_id\` required.
+
+In Server Components: \`await getServerSession()\` (from
+\`@dashai/sdk/auth/server\`).
+In Client Components: \`useSession()\` (from
+\`@dashai/sdk/auth/client\`), wrapped in \`<AuthProvider>\` (already
+in \`app/layout.tsx\`).
+
+## Local dev lifecycle
+
+\`\`\`
+dashwise login                       # one-time, opens browser
+dashwise init [slug]                 # scaffold + provision dev install
+dashwise dev                         # watcher + next dev, auth env auto-injected
+dashwise module destroy-dev-install  # tear down when done (cleans backend + auth.json)
+\`\`\`
+
+## Engineering bar
+
+- **No hacks, shortcuts, or temporary "quick fixes" as final
+  implementations.** If something needs work, leave it as a stub and
+  open an issue / TODO with a clear name \u2014 don't bury a workaround.
+- **No silent error swallowing.** Catch what you can handle; surface
+  what you can't. Tests should assert error codes, not just status.
+- **No untyped \`any\`.** The generated SDK gives you types \u2014 use
+  them. If you need an escape hatch, add a \`@ts-expect-error\` with
+  a comment explaining why.
+- **No secrets in code or env files.** Use \`runtime.secrets[]\` in
+  \`module.json\`; values are encrypted at rest and resolved at
+  runtime.
+
+## Pointers
+
+- Full walkthrough \u2014 \`@dashai/cli\`'s [building-modules.md](https://github.com/Intuize/dashwise-cli/blob/main/docs/building-modules.md).
+- Manifest schema \u2014 \`@dashai/sdk/dist/manifest/schema.d.ts\` (generated from the backend Zod source of truth).
+- Query plane reference \u2014 same docs, \`Query AST v1 wire format\` section.
+`;
+}
+function specMd(opts) {
+  return `# ${opts.name} \u2014 Spec
+
+> Living document. Source of truth for what this module does. Update
+> this BEFORE changing code that changes behavior \u2014 see CLAUDE.md.
+
+## Notion
+
+(link to ticket / design doc here, or remove this section)
+
+## Overview
+
+One-sentence description of what this module does, who uses it, and
+what tables it owns.
+
+## Database schema
+
+| Table | Columns | Notes |
+|---|---|---|
+| (none yet) | run \`dashwise table create <slug> --field <slug:type>\` to add one | |
+
+## API / contract
+
+| Method | Path | Auth | Purpose |
+|---|---|---|---|
+| (none yet) | | | |
+
+## Business rules
+
+- (RBAC, validation, domain logic.)
+
+## Dependencies
+
+Modules this module reads from + which tables/actions:
+
+- (none yet \u2014 declare in \`module.json#dependencies[]\`)
+
+## Exposed tables + actions
+
+Tables or server-actions this module makes available to other
+modules:
+
+- (none yet)
+
+## Error cases
+
+- (what can go wrong + how it's handled)
+
+## Decisions
+
+- (architectural choices + the trade-offs that drove them)
+
+## Open questions
+
+- (anything blocking implementation)
+`;
+}
+function agentLogMd(opts) {
+  return `# Agent Log \u2014 ${opts.name}
+
+Append-only log of meaningful changes to this module. Every commit
+that touches \`module.json\`, \`spec.md\`, a schema, or a public
+surface MUST add an entry here in the same change.
+
+Format (reverse chronological, newest first):
+
+\`\`\`
+## YYYY-MM-DD HH:MM \u2014 <author or agent name>
+
+**Change:** one-line summary
+**Files:** comma-separated list of files
+**Reason:** why this change was necessary
+**Spec impact:** none | updated spec.md \xA7<section>
+
+(optional: longer context, verification steps, decisions deferred)
+\`\`\`
+
+---
+
+## ${(/* @__PURE__ */ new Date()).toISOString().slice(0, 10)} \u2014 dashwise module init
+
+**Change:** Scaffolded module \`${opts.slug}\` via \`dashwise module init\`.
+**Files:** entire scaffold (\`module.json\`, \`app/\`, \`components/\`, ...).
+**Reason:** initial scaffold.
+**Spec impact:** seeded \`spec.md\` template \u2014 fill in before first
+schema mutation.
+`;
+}
+var SCAFFOLD_DEFAULT_API_URL;
 var init_scaffold = __esm({
   "src/lib/scaffold.ts"() {
+    SCAFFOLD_DEFAULT_API_URL = "http://localhost:3000";
   }
 });
 async function selectWorkspace(opts) {
@@ -1622,15 +1837,22 @@ async function moduleInitCommand(slugArg, options) {
     kind,
     ...options.git !== void 0 ? { repositoryUrl: options.git } : {}
   };
+  const scaffoldApiUrl = resolveApiUrl();
   const files = [
     ["module.json", manifestJson(scaffoldOpts)],
     ["tsconfig.json", tsconfigJson()],
     ["next.config.mjs", nextConfig()],
     ["next-env.d.ts", nextEnvDts()],
     [".gitignore", gitignore()],
-    [".env.local.example", envLocalExample()],
-    [".env.local", envLocal()],
-    ["README.md", readme(scaffoldOpts)]
+    [".env.local.example", envLocalExample(scaffoldApiUrl)],
+    [".env.local", envLocal(scaffoldApiUrl)],
+    ["README.md", readme(scaffoldOpts)],
+    // HH-CC-FUP-5: agent-facing docs ship with every scaffold so AI
+    // coding agents (Claude Code, Cursor, etc.) have the spec + log
+    // discipline + SDK pointers loaded into context from byte one.
+    ["CLAUDE.md", claudeMd(scaffoldOpts)],
+    ["spec.md", specMd(scaffoldOpts)],
+    ["agent-log.md", agentLogMd(scaffoldOpts)]
   ];
   if (kind === "custom") {
     files.push(
@@ -5722,7 +5944,7 @@ fieldCmd.command("set-type <table-slug> <field-slug> <new-type>").description(
   }
 })();
 function getVersion() {
-  return "0.3.0";
+  return "0.3.1";
 }
 function parseIntOption(value) {
   const n = Number.parseInt(value, 10);