@owlmeans/create-app 0.1.18-rc.55 → 0.1.18-rc.56

package/README.md

@@ -9,7 +9,7 @@ bun create @owlmeans/app my-app
 # or
 yarn create @owlmeans/app my-app
 # or
-npx @owlmeans/create-app@^0.1.18-rc.55 my-app
+npx @owlmeans/create-app@^0.1.18-rc.56 my-app
 ```
 
 ## What it generates
@@ -31,6 +31,13 @@ The web app ships a basic shadcn UI **navigation + layout** and a **Session** sc
 that creates, lists and removes items held in a **session-scoped in-memory resource**
 (`@owlmeans/static-resource`) on the backend — no database required.
 
+Logging goes through [`@owlmeans/log`](https://www.npmjs.com/package/@owlmeans/log), with the level
+set per environment and never in code: the api's `config.ts` reads `LOG_LEVEL` (default `info`) and
+`LOG_DEBUG` from the Bun runtime, the web's reads `VITE_LOG_LEVEL` (default `debug` under `vite`,
+`info` in a build) and `VITE_LOG_DEBUG` at build time. The shared `sources/common` config runs in
+both runtimes, so it sets no level and no `cfg.debug` flag. Local values go in the git-ignored
+`sources/api/.env` / `sources/web/.env`.
+
 By default the scaffolder also installs dependencies and **deploys agent guidance**
 into the project via [`@owlmeans/agent-skills`](https://www.npmjs.com/package/@owlmeans/agent-skills)
 (`.agents/skills/`).

package/build/args.js

@@ -5,7 +5,7 @@ Usage:
   npm create @owlmeans/app@latest <dir> [options]
   bun create @owlmeans/app <dir> [options]
   yarn create @owlmeans/app <dir> [options]
-  npx @owlmeans/create-app@^0.1.18-rc.55 <dir> [options]
+  npx @owlmeans/create-app@^0.1.18-rc.56 <dir> [options]
 
 Generates three workspaces (common + api + web) with shadcn UI navigation and
 layout, no authentication, and a session-scoped in-memory resource on the

package/build/run.js

@@ -50,7 +50,7 @@ export const run = async (args) => {
         log(args.install
             ? '\nDeploying agent skills via @owlmeans/agent-skills…'
             : '\nDeploying harness guidance via @owlmeans/agent-skills (general skills only — re-run'
-                + '\n`npx @owlmeans/agent-skills@^0.1.18-rc.46` after installing to add the package-specific ones)…');
+                + '\n`npx @owlmeans/agent-skills@^0.1.18-rc.47` after installing to add the package-specific ones)…');
         try {
             const result = await installSkills({
                 dir: dest,
@@ -62,7 +62,7 @@ export const run = async (args) => {
                 help: false,
             });
             if (result.code !== 0) {
-                process.stderr.write(`  agent-skills exited with code ${result.code} — you can re-run \`npx @owlmeans/agent-skills@^0.1.18-rc.46\` later.\n`);
+                process.stderr.write(`  agent-skills exited with code ${result.code} — you can re-run \`npx @owlmeans/agent-skills@^0.1.18-rc.47\` later.\n`);
             }
         }
         catch (err) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@owlmeans/create-app",
-  "version": "0.1.18-rc.55",
+  "version": "0.1.18-rc.56",
   "license": "MIT",
   "description": "Scaffold a fullstack OwlMeans Common app — common + api + web workspaces, shadcn UI navigation/layout, no auth, and a session-scoped in-memory resource, or --bare for the demo-free shell. Also usable programmatically via scaffold(). Deploys agent skills via @owlmeans/agent-skills by default.",
   "type": "module",
@@ -30,7 +30,7 @@
     "template"
   ],
   "dependencies": {
-    "@owlmeans/agent-skills": "^0.1.18-rc.46"
+    "@owlmeans/agent-skills": "^0.1.18-rc.47"
   },
   "devDependencies": {
     "@owlmeans/dep-config": "workspace:*",

package/template/AGENTS.md

@@ -87,6 +87,17 @@ package that owns its browser consumer imports `apiConfigPlugin({ allow, deny? }
 nested `deny` selector when a public collection carries a credential. Databases, queues, SMTP,
 tokens, secrets and internal addresses never belong in an `allow` selector.
 
+## Logging (mandatory)
+
+Before adding any log line, catch block or `console` call, follow the `logging` skill (mechanics: `log`).
+
+- No `console.*`: `const log = logger('<scope>')` from `@owlmeans/log`, a deliberate level, the
+  `Error` itself to `log.error`; never secrets, tokens or personal content.
+- The level is set per environment, never in code: the api reads `LOG_LEVEL` / `LOG_DEBUG`
+  (default `info`), the web build reads `VITE_LOG_LEVEL` / `VITE_LOG_DEBUG` (`debug` under `vite`,
+  `info` in a build). Local values go in the git-ignored `sources/api/.env` / `sources/web/.env`.
+- Never set `cfg.debug = { all: true }` — it does not control logging and must not reach production.
+
 ## Skills
 
 Reusable guidance lives in `.agents/skills/<name>/SKILL.md`, deployed by `@owlmeans/agent-skills`
@@ -94,8 +105,9 @@ from the installed `@owlmeans/*` packages. Agents load a skill by topic, or you
 explicitly. Copilot and Codex read `.agents/skills/` directly; Claude Code reads the generated
 symlinks in `.claude/skills/` (see "Claude Code" below).
 
-- After adding or updating any `@owlmeans/*` dependency, run `npx @owlmeans/agent-skills@^0.1.18-rc.46` to refresh
+- After adding or updating any `@owlmeans/*` dependency, run `npx @owlmeans/agent-skills@^0.1.18-rc.47` to refresh
   the deployed skills.
+- `/logging` — before adding any log line, catch block or `console` call (mechanics: `/log`).
 - Deployed files carry an `AUTO-GENERATED` banner and are refreshed in place — never hand-edit them.
 - To capture your own guidance, see the `skill-authoring` skill; to turn repeatedly-used memory into
   a skill, `memory-promotion`. Keep it inside this repository, in `.agents/skills/` — never in a

package/template/README.bare.md

@@ -29,6 +29,19 @@ bun run dev
 > `sources/common/src/config.ts`). If you edit `sources/common`, restart `bun run dev` to
 > rebuild it before the API and web pick up the changes.
 
+## Logging
+
+Log through `@owlmeans/log` (`const log = logger('<scope>')`), never `console.*`. The level is set
+per environment, not in code:
+
+| Runtime | Variables | Default |
+|---|---|---|
+| api (`sources/api/src/config.ts`) | `LOG_LEVEL`, `LOG_DEBUG` | `info` |
+| web (`sources/web/src/config.ts`, build time) | `VITE_LOG_LEVEL`, `VITE_LOG_DEBUG` | `debug` under `vite`, `info` in a build |
+
+`*_DEBUG` lists scopes forced to debug (`*` for all). Local values go in `sources/api/.env` /
+`sources/web/.env` (git-ignored).
+
 ## Adding your first feature
 
 1. **`sources/common/src/entrypoints.ts`** — declare the route as an OwlMeans *entrypoint* and
@@ -53,5 +66,5 @@ them; write your own guidance as separate, un-bannered files. Refresh after addi
 `@owlmeans/*` packages:
 
 ```sh
-npx @owlmeans/agent-skills@^0.1.18-rc.46
+npx @owlmeans/agent-skills@^0.1.18-rc.47
 ```

package/template/README.md

@@ -7,3 +7,8 @@ An OwlMeans application has shared protocol declarations in `sources/common`, se
 and gates are declared once in common; runtime packages bind them without changing the declaration.
 
 Use `bun run build` from the project root to build every workspace.
+
+Logging goes through `@owlmeans/log`. The api's level comes from `LOG_LEVEL` (default `info`) and
+`LOG_DEBUG` (scopes forced to debug, `*` for all); the web build's from `VITE_LOG_LEVEL` (default
+`debug` under `vite`, `info` in a build) and `VITE_LOG_DEBUG`. Put local values in
+`sources/api/.env` / `sources/web/.env` (git-ignored).

package/template/_agents/skills/getting-started/SKILL.md

@@ -43,3 +43,22 @@ const sessions = await context.entrypoint(sessionProtocols.list).call({ query: {
 Use `schema<T>(...)` or `typed<T>(...)` at the contract boundary. Bind all route parents with their
 children. Keep organization entity values on the wire as `entitySlug`; database relations use
 `entityId` only.
+
+## Configuration per runtime
+
+The shared config in `common` (services, alias, security) is imported by both runtimes, so it
+never reads `process.env` or `import.meta.env`, and it never sets `cfg.debug = { all: true }`.
+Each runtime's own `config.ts` adds what depends on its environment — the log level above all
+(`logging`, `log`), behind a type-only `import type {} from '@owlmeans/log'`:
+
+```ts
+// api/src/config.ts — Bun runtime env
+cfg.log = { level: process.env.LOG_LEVEL || 'info', debug: process.env.LOG_DEBUG ?? '' }
+
+// web/src/config.ts — Vite build-time env, typed in vite-env.d.ts
+const env = import.meta.env
+cfg.log = { level: env.VITE_LOG_LEVEL || (env.PROD ? 'info' : 'debug'), debug: env.VITE_LOG_DEBUG ?? '' }
+```
+
+The server and client contexts apply `cfg.log` themselves; application code logs through
+`logger('<scope>')` from `@owlmeans/log`, never `console.*`.

package/template/_agents/skills/logging/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: logging
+description: Logging policy for any OwlMeans application — no bare console calls; every line through @owlmeans/log with a scope and a deliberate level; what belongs at info vs debug; never log secrets or personal content; debug off in production, with the level set per environment (a server's config file, a browser's build-time env); analytics events as a call option routed to plugins. Use when adding any log line or a catch block, debugging with prints, deciding what an operator should see in production, setting a log level for an environment, or reviewing code that calls console.
+user-invocable: false
+metadata:
+  scope: general
+---
+<!-- AUTO-GENERATED — do not edit. Regenerate via sync-agent-meta. -->
+
+# Logging — the policy
+
+The mechanics are the `log` skill (`@owlmeans/log`). This is what to do in application code.
+
+1. **No `console.*`.** `import { logger } from '@owlmeans/log'`, `const log = logger('<scope>')` once per
+   module, then `log.debug|info|warn|error(message, data?, options?)`. A scope is lowercase and
+   colon-separated (`orders`, `orders:import`).
+2. **Choose the level on purpose.** `debug` is for diagnosis (per request, progress, dumps) — it is OFF
+   in production. `info` is what an operator wants to read in production: a job started or stopped, a
+   subscription or payment event, a sign-in, a server listening. `warn`: it degraded and went on.
+   `error`: the work failed. A line that fires every few seconds is `debug` or `logThrottle`d.
+3. **Stable message, variable data.** `log.info('Order shipped', { orderId, carrier })` — not a
+   sentence assembled from values. Give a significant event a dotted name: `{ event: 'order.shipped' }`.
+4. **Pass the `Error`.** `log.error('Import failed', error)` — never `error.message` alone, never
+   `JSON.stringify(error)`. In a browser the `Error` object must reach `console.error`; the logger does
+   that, and an error reporter hooked there keeps working.
+5. **Never log secrets or personal content**: tokens, keys, passwords, authorization or cookie headers,
+   request or response bodies, user text, file contents, environment values. Log ids, names, sizes,
+   counts. A catch that only logs has not told the user anything — the user-facing report is a separate
+   step (a message, a state), and `log.error` is the operator's record.
+6. **Analytics are a parameter, not a second API.** `log.info('…', data, { analytics: 'event_name' })`
+   hands the call to the registered analytics plugins (`@owlmeans/web-log` for a tag manager); add
+   `console: false` to keep it out of the log. Only for events something should count.
+7. **The level is set per environment, never in code.** A server declares `cfg.log` leaves as config
+   file paths (a ConfigMap or a `LOG_LEVEL` environment variable); a browser takes a build-time
+   constant (`VITE_LOG_LEVEL`). Development defaults to `debug`, a production build to `info`. Do not
+   hard-code `cfg.debug = { all: true }` — `debug.all` does not control logging and must not be on in
+   production.
+8. **Tests read the log with `memoryPlugin()`**; they do not spy on `console`.

package/template/_agents/skills/reuse-code/SKILL.md

@@ -47,7 +47,7 @@ How you research the repo depends on whether `@owlmeans/*` is linked locally:
   **https://github.com/owlmeans/common** — `tree.md` and package READMEs — to find the right package.
 
 This is the same dev-linked detection `@owlmeans/agent-skills` uses (see its `detectLinked`). After
-adding an `@owlmeans/*` dependency, run `npx @owlmeans/agent-skills@^0.1.18-rc.46` to deploy its
+adding an `@owlmeans/*` dependency, run `npx @owlmeans/agent-skills@^0.1.18-rc.47` to deploy its
 skill. Prefer an `@owlmeans/*` package over a third-party library or bespoke code whenever one fits.
 
 ### Never add an OwlMeans dependency without an explicit range

package/template/_gitignore

@@ -6,6 +6,11 @@ dist
 bun.lock
 bun.lockb
 
+# Developer-local environment (LOG_LEVEL, VITE_LOG_LEVEL, …)
+.env
+.env.local
+.env.*.local
+
 # Generated Claude Code skill symlinks (canonical skills live in .agents/skills/)
 .claude/skills/*
 !.claude/skills/.gitkeep

package/template/sources/api/package.json

@@ -11,8 +11,9 @@
     "typecheck": "tsc -b"
   },
   "dependencies": {
-    "@owlmeans/server-app": "^0.1.18-rc.49",
-    "@owlmeans/static-resource": "^0.1.18-rc.36",
+    "@owlmeans/log": "^0.1.18-rc.0",
+    "@owlmeans/server-app": "^0.1.18-rc.50",
+    "@owlmeans/static-resource": "^0.1.18-rc.37",
     "__APP_SLUG__-common": "workspace:^"
   },
   "devDependencies": {

package/template/sources/api/src/config.ts

@@ -1,8 +1,15 @@
 import { config } from '@owlmeans/server-app'
 import { APP_API, commonConfig } from '__APP_SLUG__-common'
 import type { Config } from './types.js'
+// The module augmentation that gives the config its `log` field — a side-effect import only.
+import type {} from '@owlmeans/log'
 
 // The server listens on the APP_API service route's port (3000), declared in common/config.ts.
 const cfg = config<Config>(APP_API, commonConfig as Config)
 
+// The log level comes from the runtime environment, never from code: `info` unless LOG_LEVEL
+// says otherwise; LOG_DEBUG lists scopes forced to debug (`*` for all). Bun reads
+// `sources/api/.env` on its own.
+cfg.log = { level: process.env.LOG_LEVEL || 'info', debug: process.env.LOG_DEBUG ?? '' }
+
 export default cfg

package/template/sources/api/src/index.ts

@@ -1,9 +1,15 @@
+import { logger } from '@owlmeans/log'
 import { main } from '@owlmeans/server-app'
 import config from './config.js'
 import { makeContext } from './context.js'
 import { appBindings } from './entrypoints.js'
 import type { Config, Context } from './types.js'
 
+const log = logger('api')
+
 const context = makeContext<Config, Context>(config)
 
-main<{}, Config, Context>(context, appBindings)
+main<{}, Config, Context>(context, appBindings).catch(error => {
+  log.error('Start failed', error)
+  process.exit(1)
+})

package/template/sources/common/package.json

@@ -19,10 +19,10 @@
     "typecheck": "tsc -b"
   },
   "dependencies": {
-    "@owlmeans/config": "^0.1.18-rc.41",
+    "@owlmeans/config": "^0.1.18-rc.42",
     "@owlmeans/entrypoint": "^0.1.18-rc.39",
     "@owlmeans/error": "^0.1.18-rc.36",
-    "@owlmeans/resource": "^0.1.18-rc.37",
+    "@owlmeans/resource": "^0.1.18-rc.38",
     "@owlmeans/route": "^0.1.18-rc.33",
     "ajv": "^8.17.1"
   },

package/template/sources/common/src/config.ts

@@ -18,7 +18,8 @@ service({
   base: 'api',
 }, cfg)
 
-cfg.debug = { all: true }
+// No log level here: this file runs in Bun AND in the browser, so each runtime's own config.ts
+// sets `cfg.log` from its environment (api: LOG_LEVEL / LOG_DEBUG, web: VITE_LOG_LEVEL / VITE_LOG_DEBUG).
 cfg.alias = APP
 // Local dev serves the API over plain HTTP. Without this the web client builds https:// URLs
 // and every call fails. In production put the API behind TLS and remove this line.

package/template/sources/web/package.json

@@ -11,16 +11,17 @@
     "preview": "vite preview"
   },
   "dependencies": {
-    "@owlmeans/client": "^0.1.18-rc.48",
-    "@owlmeans/client-config": "^0.1.18-rc.41",
-    "@owlmeans/client-context": "^0.1.18-rc.45",
-    "@owlmeans/client-entrypoint": "^0.1.18-rc.44",
-    "@owlmeans/client-i18n": "^0.1.18-rc.47",
+    "@owlmeans/client": "^0.1.18-rc.49",
+    "@owlmeans/client-config": "^0.1.18-rc.42",
+    "@owlmeans/client-context": "^0.1.18-rc.46",
+    "@owlmeans/client-entrypoint": "^0.1.18-rc.45",
+    "@owlmeans/client-i18n": "^0.1.18-rc.48",
     "@owlmeans/entrypoint": "^0.1.18-rc.39",
+    "@owlmeans/log": "^0.1.18-rc.0",
     "@owlmeans/route": "^0.1.18-rc.33",
-    "@owlmeans/state": "^0.1.18-rc.36",
-    "@owlmeans/web-client": "^0.1.18-rc.58",
-    "@owlmeans/web-panel": "^0.1.18-rc.68",
+    "@owlmeans/state": "^0.1.18-rc.37",
+    "@owlmeans/web-client": "^0.1.18-rc.59",
+    "@owlmeans/web-panel": "^0.1.18-rc.69",
     "@radix-ui/react-label": "^2.1.0",
     "@radix-ui/react-navigation-menu": "^1.2.14",
     "@radix-ui/react-progress": "^1.1.0",

package/template/sources/web/src/config.ts

@@ -1,7 +1,15 @@
 import { config } from '@owlmeans/web-panel'
 import { APP_WEB, commonConfig } from '__APP_SLUG__-common'
 import type { Config } from './types.js'
+// The module augmentation that gives the config its `log` field — a side-effect import only.
+import type {} from '@owlmeans/log'
 
 const cfg: Config = config(APP_WEB, commonConfig as Config)
 
+// The log level is decided at BUILD time (the logger is configured before the first render):
+// `debug` under `vite`, `info` in a production build, unless `sources/web/.env` sets
+// VITE_LOG_LEVEL; VITE_LOG_DEBUG lists scopes forced to debug (`*` for all).
+const env = import.meta.env
+cfg.log = { level: env.VITE_LOG_LEVEL || (env.PROD ? 'info' : 'debug'), debug: env.VITE_LOG_DEBUG ?? '' }
+
 export default cfg

package/template/sources/web/src/vite-env.d.ts

@@ -1 +1,8 @@
 /// <reference types="vite/client" />
+
+interface ImportMetaEnv {
+  /** `debug` | `info` | `warn` | `error` | `silent`. Default: `debug` under `vite`, `info` in a build. */
+  readonly VITE_LOG_LEVEL?: string
+  /** Scopes forced to debug whatever the level is, e.g. `session,i18n` or `*`. */
+  readonly VITE_LOG_DEBUG?: string
+}