@webjskit/cli 0.4.0 → 0.4.2

package/lib/create.js

@@ -266,6 +266,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.0",
+  "version": "0.4.2",
   "type": "module",
   "description": "webjs CLI — dev, start, create, db",
   "bin": {
@@ -13,7 +13,7 @@
     "README.md"
   ],
   "dependencies": {
-    "@webjskit/server": "0.4.0"
+    "@webjskit/server": "0.4.1"
   },
   "publishConfig": {
     "access": "public"

package/templates/CONVENTIONS.md

@@ -6,7 +6,76 @@ how code should be structured, tested, and organized.
 
 Sections marked `<!-- OVERRIDE -->` contain defaults you can customize.
 Edit the content below the marker to change the convention for your project.
-The `webjs check` command validates your code against these conventions.
+
+---
+
+## How `CONVENTIONS.md` relates to `webjs check`
+
+These are **two separate mechanisms** that share a topic but don't read
+each other:
+
+| | This file (`CONVENTIONS.md`) | `webjs check` |
+|---|---|---|
+| **Kind** | Markdown documentation. | Programmatic linter (code in `node_modules/@webjskit/server/src/check.js`). |
+| **Audience** | Humans + AI agents who read the project. | Run from the CLI / CI. |
+| **Effect of editing this markdown** | Changes the rules AI agents follow when they write code. | **Zero.** The linter does not parse this file. |
+| **How to customize the LINTER** | n/a — it's hardcoded in `@webjskit/server`. | Disable rules via `package.json` or `webjs.conventions.js` (see below). |
+
+So when you edit a `<!-- OVERRIDE -->` section here, you're telling AI
+agents to follow a different convention — but `webjs check` will still
+enforce its hardcoded rules. If you want the linter to stop flagging
+something it currently flags, you have to **disable that rule** as a
+separate step.
+
+### Disabling a `webjs check` rule
+
+`webjs check --rules` prints the full list. To disable one, add to
+`package.json`:
+
+```jsonc
+{
+  "webjs": {
+    "conventions": {
+      "tests-exist": false,
+      "actions-in-modules": false
+    }
+  }
+}
+```
+
+Or create `webjs.conventions.js`:
+
+```js
+export default {
+  'tests-exist': false,
+};
+```
+
+Only `false` is meaningful — there's no way to tweak rule *behaviour* via
+config today, only to switch a whole rule on or off.
+
+### What `webjs check` enforces today
+
+Run `webjs check --rules` for the current set with descriptions. As of
+`@webjskit/server@0.4.1`:
+
+- `actions-in-modules` — `.server.{js,ts}` / `'use server'` files belong
+  in `modules/<feature>/actions/` or `queries/`. `lib/` is exempt
+  (cross-cutting server infra).
+- `one-function-per-action` — files inside `modules/*/actions/` or
+  `modules/*/queries/` should export exactly one async function.
+- `components-have-register` — `WebComponent` subclasses must call
+  `Class.register('tag')` or `customElements.define`.
+- `no-server-imports-in-components` — components must not import
+  `@prisma/client`, `node:*`, or `lib/*`.
+- `reactive-props-use-declare` — props listed in `static properties` must
+  use the `declare propName: Type` + constructor-default pattern (class
+  field initializers clobber the framework's reactive accessor).
+- `tag-name-has-hyphen` — custom element tags must contain a hyphen.
+- `tests-exist` — each `modules/<feature>/` should have a test file.
+- `no-json-data-files` — JSON files that look like a database (under
+  `data/`, or named `db.json` / `database.json` / `*-db.json`) are
+  forbidden; use Prisma + SQLite instead.
 
 ---
 
@@ -612,32 +681,12 @@ This project enforces a git workflow via agent-specific config files
 
 ## Overriding conventions
 
-To disable a convention check, add to your `package.json`:
-
-```json
-{
-  "webjs": {
-    "conventions": {
-      "actions-in-modules": false,
-      "one-function-per-action": false,
-      "tests-exist": false
-    }
-  }
-}
-```
-
-Or create `webjs.config.js`:
-
-```js
-export default {
-  conventions: {
-    'actions-in-modules': false,
-  },
-};
-```
+See the **"How `CONVENTIONS.md` relates to `webjs check`"** section at
+the top of this file. Short version: disable specific linter rules via
+`package.json` (`webjs.conventions.<rule>: false`) or `webjs.conventions.js`.
 
-Run `webjs check` to validate your app against these conventions.
-Run `webjs check --fix` to see suggested fixes for violations.
+Run `webjs check` to validate. Run `webjs check --rules` to list every
+rule with its description.
 
 ---