@webjskit/cli 0.4.1 → 0.4.4

package/lib/create.js

@@ -87,9 +87,9 @@ export async function scaffoldApp(name, cwd, opts = {}) {
       '@web/test-runner': '^0.20.0',
       '@web/test-runner-playwright': '^0.11.0',
       'playwright': '^1.59.0',
-      // tsserver plugins for editor intelligence inside html`` templates.
-      // Order in tsconfig matters — see below.
-      'ts-lit-plugin': '^2.0.0',
+      // tsserver plugin for editor intelligence inside html`` templates.
+      // @webjskit/ts-plugin bundles ts-lit-plugin internally, so just one
+      // plugin entry is needed in tsconfig (see below).
       '@webjskit/ts-plugin': 'latest',
     },
   }, null, 2) + '\n');
@@ -104,14 +104,16 @@ export async function scaffoldApp(name, cwd, opts = {}) {
       noEmit: true,
       allowImportingTsExtensions: true,
       skipLibCheck: true,
-      // ts-lit-plugin: type-check + diagnostics inside html`` templates.
-      // @webjskit/ts-plugin: webjs-aware go-to-definition, "Unknown tag/attr"
-      // suppression for elements registered via Class.register('tag'), and
-      // attribute auto-complete sourced from `static properties`.
-      // Order matters — list ts-lit-plugin first; @webjskit/ts-plugin wraps
-      // it. Remove either entry if you don't want that capability.
+      // @webjskit/ts-plugin gives the editor:
+      //   • type-check + diagnostics inside html`` templates (via the
+      //     ts-lit-plugin it bundles internally)
+      //   • webjs-aware go-to-definition on custom-element tags
+      //   • "Unknown tag/attribute" suppression for elements registered
+      //     via Class.register('tag-name')
+      //   • attribute auto-complete sourced from `static properties`
+      //   • attribute-value type-check against `declare` annotations
+      // Editor-only — the framework runs without it.
       plugins: [
-        { name: 'ts-lit-plugin', strict: true },
         { name: '@webjskit/ts-plugin' },
       ],
     },
@@ -266,6 +268,27 @@ export async function POST(req: Request) {
   const body = await req.json();
   return Response.json(await createUser(body));
 }
+`);
+    // Minimal test stub so the scaffold passes `webjs check` (tests-exist)
+    // and `webjs test` runs cleanly. Replace these with real assertions
+    // once you wire the action/query to a real data source.
+    await writeFile(join(appDir, 'test', 'unit', 'users.test.ts'), `import { test } from 'node:test';
+import assert from 'node:assert/strict';
+
+import { listUsers } from '../../modules/users/queries/list-users.server.ts';
+import { createUser } from '../../modules/users/actions/create-user.server.ts';
+
+test('listUsers returns an array', async () => {
+  const users = await listUsers();
+  assert.ok(Array.isArray(users));
+});
+
+test('createUser returns a success envelope with the input echoed back', async () => {
+  const result = await createUser({ name: 'Test', email: 'test@example.com' });
+  assert.equal(result.success, true);
+  assert.equal(result.data.name, 'Test');
+  assert.equal(result.data.email, 'test@example.com');
+});
 `);
     await writeFile(join(appDir, 'modules', 'users', 'types.ts'), `export interface User {
   id: string;

package/lib/saas-template.js

@@ -133,6 +133,54 @@ export async function writeSaasFiles(appDir) {
     "",
   ].join('\n'));
 
+  // test/unit/auth.test.ts — minimal stub so the scaffold passes
+  // `webjs check` (tests-exist) and `webjs test` runs cleanly out of the
+  // box. The signup/current-user functions import from lib/prisma.ts and
+  // lib/auth.ts, both of which need `prisma generate` to have run before
+  // they can be imported — so we deliberately test only the runtime-
+  // dependency-free types.ts here. Replace with real tests once Prisma
+  // is set up (run `npm install && npx prisma migrate dev --name init`).
+  await writeFile(join(appDir, 'test', 'unit', 'auth.test.ts'), [
+    "import { test } from 'node:test';",
+    "import assert from 'node:assert/strict';",
+    "",
+    "import type { User, ActionResult } from '../../modules/auth/types.ts';",
+    "",
+    "test('User shape: id is numeric, email is required', () => {",
+    "  const u: User = { id: 1, name: 'Test', email: 'test@example.com' };",
+    "  assert.equal(typeof u.id, 'number');",
+    "  assert.equal(typeof u.email, 'string');",
+    "});",
+    "",
+    "test('ActionResult: success envelope carries data', () => {",
+    "  const r: ActionResult<User> = {",
+    "    success: true,",
+    "    data: { id: 1, name: 'Test', email: 'test@example.com' },",
+    "  };",
+    "  assert.equal(r.success, true);",
+    "  if (r.success) assert.equal(r.data.email, 'test@example.com');",
+    "});",
+    "",
+    "test('ActionResult: failure envelope carries error + status', () => {",
+    "  const r: ActionResult<User> = {",
+    "    success: false,",
+    "    error: 'Email already registered',",
+    "    status: 409,",
+    "  };",
+    "  assert.equal(r.success, false);",
+    "  if (!r.success) {",
+    "    assert.equal(r.status, 409);",
+    "    assert.ok(r.error.length > 0);",
+    "  }",
+    "});",
+    "",
+    "// TODO: once you've run `npm install && npx prisma migrate dev` you can",
+    "// import { signup } from '../../modules/auth/actions/signup.server.ts'",
+    "// and { currentUser } from '../../modules/auth/queries/current-user.server.ts'",
+    "// and write real integration tests against a test SQLite DB.",
+    "",
+  ].join('\n'));
+
   // app/api/auth/[...path]/route.ts
   await mkdir(join(appDir, 'app', 'api', 'auth', '[...path]'), { recursive: true });
   await writeFile(join(appDir, 'app', 'api', 'auth', '[...path]', 'route.ts'), [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webjskit/cli",
-  "version": "0.4.1",
+  "version": "0.4.4",
   "type": "module",
   "description": "webjs CLI — dev, start, create, db",
   "bin": {
@@ -13,7 +13,7 @@
     "README.md"
   ],
   "dependencies": {
-    "@webjskit/server": "0.4.1"
+    "@webjskit/server": "0.4.2"
   },
   "publishConfig": {
     "access": "public"

package/templates/.cursorrules

@@ -80,5 +80,5 @@ Quality bar stays the same — just no blocking on questions.
 - One function per server action file (*.server.ts)
 - Components must call customElements.define('tag', Class)
 - Never import @prisma/client or node:* from client components
-- Use directives (classMap, styleMap, ref, etc.) from '@webjskit/core/directives'
+- Directives are deliberately minimal: only `unsafeHTML`, `live`, and `repeat` ship. Lit's `classMap` / `styleMap` / `ref` / `when` / `choose` / `guard` are NOT exported — use plain template-literal expressions (`class=${cond ? 'a' : 'b'}`, `${cond ? a : b}`) and lifecycle hooks (`this.query('#el')` in `firstUpdated`) instead.
 - See AGENTS.md for the complete directive decision guide

package/templates/.github/copilot-instructions.md

@@ -64,9 +64,9 @@ Every code change must include:
 ## Code patterns
 
 - Tagged template: html`<div>${value}</div>` with css`...` for styles
-- Components: extend WebComponent, use static tag/styles/properties, call Class.register('tag')
+- Components: extend WebComponent, declare `static properties` (and `static styles` for shadow-DOM components), call `Class.register('tag-name')` at the bottom of the file. The tag name is the argument to `.register()`, not a static field.
 - Server actions: *.server.ts files with one exported async function each
-- Directives: import { classMap, styleMap, ref, when, ... } from '@webjskit/core/directives'
+- Directives: webjs ships only `unsafeHTML`, `live`, and `repeat`. Lit's `classMap` / `styleMap` / `ref` / `when` / `choose` / `guard` are NOT exported — use plain template-literal expressions and lifecycle hooks instead.
 - Context: import { createContext, ContextProvider, ContextConsumer } from '@webjskit/core/context'
 - Task: import { Task, TaskStatus } from '@webjskit/core/task'
 - Routing: file-based under app/ (page.ts, layout.ts, route.ts, middleware.ts)

package/templates/.windsurfrules

@@ -67,8 +67,9 @@ The user should never have to ask for tests or documentation.
 ## Framework specifics
 
 - No build step: ES modules served directly
-- Web components with shadow DOM by default
+- Web components render into light DOM by default (so Tailwind / global CSS apply directly). Opt in to shadow DOM per component with `static shadow = true` when you need scoped styles, slot projection, or third-party-embed isolation.
+- Custom-element tag names are passed to `.register('tag-name')` — they are NOT a static field on the class.
 - One function per server action file (*.server.ts)
-- Use webjs directives: classMap, styleMap, ref, when, choose, guard, etc.
+- Directives are deliberately minimal: only `unsafeHTML`, `live`, and `repeat` ship. Use plain template-literal expressions (`class=${active ? 'btn active' : 'btn'}`, `style=${'color:' + color}`, `${cond ? a : b}`) and lifecycle hooks (`this.query('#el')` in `firstUpdated`) instead of Lit's `classMap` / `styleMap` / `ref` / `when` / `choose` / `guard`.
 - Use Context for cross-component data, Task for async data in components
 - Full API reference in AGENTS.md

package/templates/AGENTS.md

@@ -84,6 +84,34 @@ node_modules/@webjskit/
 Reaching straight for the source is the fastest way to resolve "why
 doesn't X work?" — no documentation guesswork, no stale blog posts.
 
+## Editor TS plugin — `@webjskit/ts-plugin`
+
+This scaffold's `tsconfig.json` lists a single tsserver plugin. It is
+editor-only — not required for the framework to run.
+
+```jsonc
+// tsconfig.json (already wired by the scaffold)
+"plugins": [
+  { "name": "@webjskit/ts-plugin" }
+]
+```
+
+`@webjskit/ts-plugin` bundles `ts-lit-plugin` internally (it's a runtime
+dependency of the plugin) and loads it programmatically — so users
+list one entry, not two. You get the full stack of template-literal
+intelligence (type-checking, diagnostics, go-to-def inside
+`` html`…` `` and `` css`…` `` templates) **plus** webjs-aware behaviour
+layered on top:
+
+- "Unknown tag/attribute" diagnostics are silenced for elements
+  registered via `Class.register('tag-name')`.
+- Attribute auto-complete sourced from each component's
+  `static properties`.
+- Attribute-value type-check against `declare propName: T` annotations.
+
+See [docs.webjs.com → Editor setup](https://docs.webjs.com/docs/editor-setup)
+for the full walkthrough.
+
 ## File conventions
 
 ```
@@ -172,9 +200,8 @@ import { rateLimit, cache, createAuth, Credentials, Session } from '@webjskit/se
 import { WebComponent, html, css } from '@webjskit/core';
 
 export class Counter extends WebComponent {
-  static tag = 'my-counter';       // required, must contain a hyphen
   static properties = { count: { type: Number } };
-  static styles = css`button { padding: 8px 12px; }`;
+  static styles = css`button { padding: 8px 12px; }`;   // shadow-DOM only
   // static shadow = true;          // opt into shadow DOM (default: light DOM)
   // static lazy = true;             // download JS only when scrolled into view
 
@@ -223,7 +250,7 @@ absolute URLs from `ctx.url`).
 
 ## Invariants (do not violate)
 
-1. Custom element tags must contain a hyphen. Set `static tag`, call `.register()`.
+1. Custom element tags must contain a hyphen. Pass the tag to `.register('tag-name')` at the bottom of the file. The tag is not a static field.
 2. Never import `@prisma/client` or `node:*` from client-reachable files —
    only from `.server.ts` modules or `lib/*.ts`.
 3. Event / property / boolean holes in `` html`` `` are unquoted: