@bardioc/create-bardioc-app 0.7.0 → 0.7.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bardioc/create-bardioc-app",
-  "version": "0.7.0",
+  "version": "0.7.1",
   "description": "Scaffold a Bardioc app with framework templates (vite, react, vue, angular, svelte, solid, preact, nextjs)",
   "license": "MIT",
   "private": false,
@@ -32,7 +32,7 @@
   "devDependencies": {
     "@vitest/coverage-v8": "^4.1.8",
     "@types/node": "^25.9.1",
-    "typescript": "6.0.3",
+    "typescript": "^7.0.2",
     "vitest": "^4.1.8"
   },
   "scripts": {

package/templates/_base/.changeset/README.md

@@ -5,13 +5,11 @@ as the `@bardioc/*` libraries.
 
 **To cut a release: run the `/changeset-app` skill** (or `npm run changeset`) — it picks the semver bump
 and applies it locally (`npm run release:version`), so `package.json`'s `version` always reflects the
-release. Commit the result with your PR; merging to `dev` runs the publish step in the pipeline.
+release. Commit the result with your PR.
 
 The skill is named `changeset-app` (not `changeset`) to avoid clashing with the `/changeset` command
 in `bardioc-desktop-frontend` when both repos are open in one workspace. It's app-agnostic — it reads
-the published package name from `package.json` — so the same skill file works in any app repo.
+the package name from `package.json` — so the same skill file works in any app repo.
 
-> **This app ships private + unscoped, so publishing is dormant.** `npm run changeset publish` no-ops on
-> a private package — versioning works, but nothing is pushed to a registry. To actually publish to
-> Nexus, scope the name (e.g. `@bardioc/<app>`), set `"private": false`, and add a
-> `publishConfig.registry`; then the pipeline's publish step starts shipping the built `dist/`.
+> **This app is not published to a registry.** It ships `"private": true`, so `npm run changeset publish`
+> no-ops — versioning works, and the release is the zip built by `npm run bundle`.

package/templates/_base/.claude/commands/changeset-app.md

@@ -1,15 +1,16 @@
 ---
 name: changeset-app
-description: Write a changeset for this app repo's single published package, pick the semver bump (default patch, major on breaking change), and apply the bump locally — keeping package.json's version in step with the release.
+description: Write a changeset for this app repo's single package, pick the semver bump (default patch, major on breaking change), and apply the bump locally — keeping package.json's version in step with the release.
 argument-hint: "[optional: summary, and/or 'minor'/'major' to override the bump]"
 ---
 
 # /changeset-app — Author + bump locally
 
-This is a **single-package hosted-app repo**: it publishes exactly one package (read its name from
+This is a **single-package hosted-app repo**: it holds exactly one package (read its name from
 this repo's `package.json` `name` field). This skill writes the `.changeset/*.md`, picks the **bump**,
 and **applies it** (`npm run release:version`), so `package.json`'s `version` always reflects the
-release. The result is committed with your PR; the pipeline only publishes.
+release. The result is committed with your PR. Nothing is published: the release is the zip built
+by `npm run bundle`.
 
 > Named `changeset-app` (not `changeset`) on purpose: `bardioc-desktop-frontend` ships its own
 > `/changeset`, and project commands don't namespace across repos — a shared name would collide
@@ -19,7 +20,7 @@ release. The result is committed with your PR; the pipeline only publishes.
 
 ## Step 0 — Identify the package
 
-Read the published package name from this repo's `package.json` `name` field. This is the **only**
+Read the package name from this repo's `package.json` `name` field. This is the **only**
 app-specific value — use it verbatim in the changeset frontmatter (Step 2). Everything else below is
 identical across app repos.
 
@@ -53,7 +54,7 @@ The user invoked this with: `$ARGUMENTS`
 
 If this change raises a `@bardioc/*` dependency in `package.json` (e.g. `@bardioc/ui` ↑ because
 the app now uses a new component/prop/type from it), that is a **release-relevant change**:
-write a changeset so the app's **own** version bumps as well. The published app version must
+write a changeset so the app's **own** version bumps as well. The app version must
 move whenever its required dependency set moves — otherwise the package.json version no longer
 identifies a distinct release.
 
@@ -95,10 +96,8 @@ manifest note below) — a bump alone does not update the zip.
   rebuild the zip and swap it into the host's `apps/webos-host/public/_apps/`. The committed
   `app-manifest.json` `version` is just a seed — the stamp overwrites it in the build output, so
   don't sync it by hand.
-- **Bump before merging to `dev`** so the release carries a fresh version. There is **no
-  release gate**: if you forget, `npm run changeset publish` just no-ops (green, "No unpublished
-  projects") rather than failing — the merge succeeds but publishes nothing until you bump. (While
-  the package is private, publish always no-ops regardless.)
-- Bumping locally is why CI needs **no git-write token** — the version is already in the PR;
-  the pipeline only runs `npm run changeset publish` (which publishes only if the version isn't on
-  Nexus yet and the package is publishable).
+- **Bump before merging to `dev`** so the zip built from it carries a fresh version. There is **no
+  release gate**: nothing fails if you forget.
+- Bumping locally is why CI needs **no git-write token** — the version is already in the PR.
+  Nothing is published: the app ships `"private": true`, and its release is the zip built by
+  `npm run bundle`.

package/templates/_base/.claude/commands/refresh-bundle.md

@@ -93,7 +93,7 @@ Do **not** commit unless the user asks.
 
 ## Notes
 
-- This app is decoupled from the host's workspace (its own `pnpm-lock.yaml`). Always run
+- This app is decoupled from the host's workspace (its own `package-lock.json`). Always run
   `npm run bundle` from inside `REPO`, never from the host root.
 - Removing the repo zip first (Step 2) is deliberate: it guarantees the copy in Step 4 is a
   brand-new build, never a leftover artifact.

package/templates/_base/AGENTS.md

@@ -0,0 +1,128 @@
+# {{DISPLAY_NAME}} — agent guide
+
+A Bardioc hosted app, scaffolded with `@bardioc/create-bardioc-app`. It runs in an iframe inside
+Bardioc OS and reaches the OS and the backend only through `@bardioc/app-sdk`. This file holds what
+every Bardioc app shares, whatever its framework; `CLAUDE.md` may add notes for this template.
+
+---
+
+## Commands
+
+The app uses **npm**, not pnpm or yarn: `npm run bundle` needs npm's lockfile for its SBOM and audit.
+
+```bash
+npm install
+npm run dev           # http://localhost:{{PORT}}
+npm run build         # → build output, with the manifest version stamped
+npm run bundle        # compliance gate + build → {{APP_NAME}}.zip
+npm run check-types
+npm run lint          # @bardioc/configs preset (not in the angular template)
+npm run format        # @bardioc/configs preset (not in the angular template)
+```
+
+---
+
+## Running it
+
+- **Inside the host** the app needs no setup: the OS provides the session.
+- **Standalone** (`npm run dev`), the dev host stands in for the OS (`installDevHost()` from
+  `@bardioc/app-sdk/dev`, in the app's entry: `src/main.*`, or `app/page.tsx` in nextjs). SDK
+  calls go through a dev-auth proxy that signs them with `DEV_SECRET`: the `bardiocDevAuth` Vite
+  plugin, or `scripts/dev.mjs` in the angular and nextjs templates. Set `DEV_SECRET` (from the App Store after registering the app) and
+  `API_BASE_URL` in `.env` (see `.env.example`). Without them every backend call fails with a
+  `BardiocError`; render that as an error state.
+- **Check dev auth in the browser**, not with `curl`: the proxy relays the browser's session, so
+  `curl localhost:{{PORT}}/rest/…` gets 401 even with a valid `DEV_SECRET`.
+- **`npm run preview`** (Vite templates) serves the build on port + 1000, not on `{{PORT}}`; trust
+  the `Local:` line it prints. A build opened outside the host renders in fallback fonts, because fonts come from the
+  host's `/fonts` contract.
+- Gate the SDK on `isInsideIframe()` / `isDevStandalone()` (`@bardioc/app-sdk/dev`), as
+  the app's entry does: with neither a host nor a dev session there is nothing to connect to.
+
+---
+
+## SDK — `@bardioc/app-sdk` 1.x
+
+Everything goes through one `Bardioc` object. The app's entry gets it: `connect()` from
+`@bardioc/app-sdk`, or `useSdk()` from `@bardioc/app-sdk/react` under `AppSdkProvider`.
+
+- **Graph** — `bardioc.graph.*`: `get(id)`, `getMany`, `getByXid`, `query(lucene, opts)`,
+  `gremlin(rootId, query)`, `create`, `update`, `delete`, `connect`, `history`, `timeseries.*`
+  (full list: the `GraphApi` type).
+  - `query` can resolve to a `{ items: [...] }` envelope: normalize before indexing.
+  - Escape `/` in Lucene as `\/` (`ogit\/_type:"…"`).
+  - Ids and types differ between instances: discover them with a wildcard `query('*')` instead of
+    hard-coding them.
+- **OS** — `bardioc.os.profile.get()`, `bardioc.os.organization.getStructure()`,
+  `bardioc.os.applications.list()` (full list: the `OsApi` type). Any other backend path:
+  `bardioc.bff.request({ path })`.
+- **Storage** — `bardioc.idb(store)`: app-scoped IndexedDB with `get`, `put`, `delete`,
+  `query({ prefix, limit })`. Standalone, it lives in this browser's IndexedDB.
+- **Host UI** — `bardioc.ui.notify(message, level)`, `bardioc.ui.setMenu(...)` /
+  `setCommands(...)` with `onCommand(id, run)` for the OS menu bar.
+- **Live events** — `bardioc.events.graph({ types }, onEvent)` resolves to the function that ends
+  the stream. No events arrive outside a valid session: render an empty state.
+- **Context** — `bardioc.context` (`osConfig` with theme and language, the app's `settings`) and
+  `bardioc.onContextChange(listener)`. Follow the OS theme and language.
+- **`bardioc.apps.*`** exists only inside the host; standalone it rejects with `unavailable`.
+
+### Errors
+
+Every failure is a `BardiocError` with a `code` (`invalid`, `unauthenticated`, `forbidden`,
+`not_found`, `conflict`, `rate_limited`, `unavailable`, `timeout`, …). HTTP failures also carry
+`status`. Both survive the trip through the host. Wrap every call and give each failure a visible
+state; never fall back to made-up data without labeling it.
+
+```typescript
+import { BardiocError } from '@bardioc/app-sdk';
+
+try {
+  return await bardioc.graph.get(id);
+} catch (error) {
+  if (error instanceof BardiocError && error.code === 'not_found') return null;
+  throw error;
+}
+```
+
+`unauthenticated` / `forbidden` mean the session is missing or lacks a permission: say so, rather
+than showing an empty result.
+
+---
+
+## Manifest — `public/app-manifest.json`
+
+Validated by `validateManifest` (`@bardioc/app-sdk`), also on build.
+
+- Required: `manifestVersion` (1 or 2), `id` (lowercase), `name`, `version`. `version` is stamped
+  from `package.json` on build, so bump it there, not here.
+- Optional: `description`, `entry`, `icon` (an `icon.svg` in `public/`, 64 KB or smaller),
+  `author` (`{ name, url? }`), `categories`, `showInDock`, `showInDockAppsMenu`.
+- `rules.roles`: the graph access the app requests at review, as role name →
+  `{ vertexRule?, edgeRule? }`.
+- `window`: `size` (`xs|sm|md|lg|xl` or `{ width, height, minWidth?, minHeight? }`), `resizable`,
+  `maximizable`, `minimizable`, `customScroll`, `centered`, `isHeaderless`, `isInstanceAware`,
+  `canHaveMultipleWindows`.
+
+---
+
+## Copy
+
+American English. Labels (titles, buttons, menu items, tabs, columns, field labels, placeholders,
+tooltips) in Title Case (`Add Station`, `Save and Close`). Descriptions, toasts, errors and
+validation messages as sentences ending with a period.
+
+---
+
+## Ship
+
+1. Bump `version` in `package.json`. For an app already in the Development Center it must be higher
+   than the last upload.
+2. `npm run bundle` → `{{APP_NAME}}.zip`, with the build output at the zip root. It needs the system
+   `zip` binary; on Windows, run `npm run build` and zip the build output's contents instead.
+3. Check the archive (`unzip -l {{APP_NAME}}.zip`): `app-manifest.json` and `index.html` at the top
+   level, with the version you set.
+4. Upload in Bardioc OS: **Development Center** → **Create App** → drop the zip (first time), or the
+   app's page → **New version** → **Upload version**. A new app starts as a draft: **Install**
+   tries it in your own OS, **Submit for review** publishes it through the App Store review.
+
+Don't ship any other way: `/refresh-bundle` only copies the zip into a local host checkout.

package/templates/_base/CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

package/templates/_base/README.md

@@ -38,9 +38,9 @@ template is the exception — Angular 19 pins TypeScript 5.8, which the presets
 
 > Available only if you scaffolded with `--with-link` (adds `scripts/link-source.mjs`,
 > `pnpm-workspace.yaml`, and `.npmrc`). Otherwise this section does not apply — every `@bardioc/*`
-> dep resolves from Nexus.
+> dep resolves from the npm registry.
 
-By default, every `@bardioc/*` dependency comes from Nexus. To develop against a local source
+By default, every `@bardioc/*` dependency comes from the npm registry. To develop against a local source
 checkout instead — for example, to edit `@bardioc/ui` and see HMR in this app — symlink the source
 repo into `.linked/`:
 
@@ -63,7 +63,7 @@ pnpm unlink:source <name>                                               # remove
 ### CI / Docker
 
 No `.linked/` directory exists, so the workspace glob matches nothing and `@bardioc/*` always
-resolves from Nexus. No overlay or CI-only workspace file needed.
+resolves from the npm registry. No overlay or CI-only workspace file needed.
 
 ## Build & Bundle
 
@@ -80,13 +80,12 @@ finding, and ships the SBOM and the reports inside the zip. `{{APP_NAME}}.zip` i
 to the Bardioc host as a hosted app. To swap a fresh build into a local WebOS host checkout, run the
 **`/refresh-bundle`** skill.
 
-## Release & Publishing
+## Release
 
 This app is versioned with [Changesets](https://github.com/changesets/changesets). **The version
-bump is done locally** (so CI needs no git-write token), and there is **no release gate** — a
-forgotten bump just publishes nothing rather than failing the deploy.
+bump is done locally** (so CI needs no git-write token), and nothing is published: the release is the zip built by `npm run bundle`.
 
-> The CI pipeline below (PR checks + the publish step) is present only if you scaffolded with
+> The CI pipeline below (PR checks) is present only if you scaffolded with
 > `--with-pipeline`. Without it, version locally with the steps below and bundle/ship by hand.
 
 **To cut a release:**
@@ -94,13 +93,8 @@ forgotten bump just publishes nothing rather than failing the deploy.
 1. On your feature branch, run the **`/changeset-app`** skill (or `npm run changeset`) — it picks the
    semver bump, writes `.changeset/*.md`, and applies it locally (`npm run release:version`). Commit the
    result with your PR. Then run **`/refresh-bundle`** so the new version reaches the shipped zip.
-2. Open a PR. The PR pipeline runs `check-types`, `build`, and `audit` in parallel. No publish.
-3. Merge to `dev`. CI runs again, then the publish step runs.
-
-> **Publishing is dormant by default.** This app ships `"private": true` with an unscoped name, so
-> `npm run changeset publish` cleanly no-ops. To publish to Nexus, scope the package name
-> (e.g. `@bardioc/{{APP_NAME}}`), set `"private": false`, and add a `publishConfig.registry` — then
-> the pipeline's publish step ships the built output (set `"files": ["<output-dir>"]` accordingly).
->
-> **CI prerequisite** (set as a Bitbucket repo/workspace variable, not in the repo):
-> `NEXUS_REPO_USER` / `NEXUS_REPO_PASS` — an account with `npm-releases` deploy rights.
+2. Open a PR. The PR pipeline runs `check-types`, `build`, and `audit` in parallel.
+3. Merge to `dev`. CI runs again.
+
+> **Publishing is not used.** This app ships `"private": true`, so `npm run changeset publish` cleanly
+> no-ops; the release is the zip built by `npm run bundle`.

package/templates/_opt-link/scripts/link-source.mjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 // Symlinks a local @bardioc/* source checkout into .linked/ and syncs its pnpm catalogs into
-// pnpm-workspace.yaml. Without a link the workspace glob matches nothing and deps resolve from Nexus.
+// pnpm-workspace.yaml. Without a link the workspace glob matches nothing and deps resolve from the npm registry.
 //   node link-source.mjs <path> [--as <name>]   link (name defaults to basename)
 //   node link-source.mjs --remove <name>        remove a link
 

package/templates/_opt-pipeline/bitbucket-pipelines.yml

@@ -5,35 +5,27 @@ options:
 
 definitions:
   caches:
-    pnpm: .pnpm-store
+    npm: ~/.npm
 
   steps:
     - step: &check-types
         name: Check types
         runs-on: ['almai', 'self.hosted', 'linux']
         caches:
-          - pnpm
+          - npm
         script:
-          - corepack enable && corepack prepare pnpm@10.33.0 --activate
-          - pnpm config set store-dir .pnpm-store
-          - npm config set @bardioc:registry http://nexus.almato.com/repository/npm-group/
-          - echo "//nexus.almato.com/repository/npm-group/:_auth=$(echo -n ${NEXUS_REPO_USER}:${NEXUS_REPO_PASS} | base64)" >> ~/.npmrc
-          - pnpm install --frozen-lockfile
-          - pnpm check-types
+          - npm ci
+          - npm run check-types
 
     - step: &build
         name: Build
         runs-on: ['almai', 'self.hosted', 'linux']
         caches:
-          - pnpm
+          - npm
         script:
-          - corepack enable && corepack prepare pnpm@10.33.0 --activate
-          - pnpm config set store-dir .pnpm-store
-          - npm config set @bardioc:registry http://nexus.almato.com/repository/npm-group/
-          - echo "//nexus.almato.com/repository/npm-group/:_auth=$(echo -n ${NEXUS_REPO_USER}:${NEXUS_REPO_PASS} | base64)" >> ~/.npmrc
-          - pnpm install --frozen-lockfile
+          - npm ci
           - export {{BUILD_ENV}}={{APP_NAME}}
-          - pnpm build
+          - npm run build
         artifacts:
           - {{OUT_DIR}}/**
 
@@ -41,41 +33,14 @@ definitions:
         name: Security audit
         runs-on: ['almai', 'self.hosted', 'linux']
         caches:
-          - pnpm
+          - npm
         script:
-          - corepack enable && corepack prepare pnpm@10.33.0 --activate
-          - pnpm config set store-dir .pnpm-store
-          - npm config set @bardioc:registry http://nexus.almato.com/repository/npm-group/
-          - echo "//nexus.almato.com/repository/npm-group/:_auth=$(echo -n ${NEXUS_REPO_USER}:${NEXUS_REPO_PASS} | base64)" >> ~/.npmrc
-          - pnpm install --frozen-lockfile
-          - pnpm audit --audit-level=high
-
-    # Publishes any version not yet on Nexus. The bump is done locally (pnpm release:version) and merged
-    # in the PR — no git write token, no release gate. Dormant while the app is `"private": true` +
-    # unscoped (changeset publish no-ops). To enable: scope the name, set private:false, add
-    # publishConfig.registry, and set `files` to the build output.
-    - step: &publish
-        name: Publish package to Nexus
-        runs-on: ['almai', 'self.hosted', 'linux']
-        caches:
-          - pnpm
-        script:
-          - corepack enable && corepack prepare pnpm@10.33.0 --activate
-          - pnpm config set store-dir .pnpm-store
-          - npm config set @bardioc:registry http://nexus.almato.com/repository/npm-group/
-          - echo "//nexus.almato.com/repository/npm-group/:_auth=$(echo -n ${NEXUS_REPO_USER}:${NEXUS_REPO_PASS} | base64)" >> ~/.npmrc
-          # npm publish auth must live in $HOME/.npmrc — changeset publish runs npm publish from the package dir.
-          - echo "//nexus.almato.com/repository/npm-releases/:_auth=$(echo -n ${NEXUS_REPO_USER}:${NEXUS_REPO_PASS} | base64)" >> "$HOME/.npmrc"
-          - echo "//nexus.almato.com/repository/npm-releases/:always-auth=true" >> "$HOME/.npmrc"
-          - pnpm install --frozen-lockfile
-          - export {{BUILD_ENV}}={{APP_NAME}}
-          - pnpm build
-          # Switch @bardioc to the writable npm-releases repo (npm-group is read-only; @scope:registry wins over publishConfig).
-          - npm config set @bardioc:registry http://nexus.almato.com/repository/npm-releases/
-          - pnpm changeset publish
+          - npm ci
+          - npm audit --omit=dev --audit-level=high
 
+# Nothing is published: the app ships as the zip built by `npm run bundle`.
 pipelines:
-  # PRs (and pushes to a PR's source branch) run everything except publish.
+  # PRs (and pushes to a PR's source branch).
   pull-requests:
     '**':
       - parallel:
@@ -83,18 +48,9 @@ pipelines:
           - step: *build
           - step: *audit
 
-  # Commits to `dev` run CI then publish. No gate: changeset publish no-ops when nothing is new.
   branches:
     dev:
       - parallel:
           - step: *check-types
           - step: *build
           - step: *audit
-      - step:
-          <<: *publish
-          trigger: automatic
-
-  custom:
-    # On-demand publish — re-run if a publish failed.
-    publish-package:
-      - step: *publish

package/templates/angular/package.json

@@ -32,7 +32,7 @@
     "@angular/platform-browser": "^19.2.12",
     "@angular/platform-browser-dynamic": "^19.2.12",
     "@angular/router": "^19.2.12",
-    "@bardioc/app-sdk": "^1.0.1",
+    "@bardioc/app-sdk": "^1.0.3",
     "rxjs": "~7.8.2",
     "tslib": "^2.8.1",
     "zone.js": "~0.15.1"

package/templates/nextjs/package.json

@@ -21,7 +21,7 @@
     "release:publish": "changeset publish"
   },
   "dependencies": {
-    "@bardioc/app-sdk": "^1.0.1",
+    "@bardioc/app-sdk": "^1.0.3",
     "next": "^15.3.2",
     "react": "^19.2.5",
     "react-dom": "^19.2.5"

package/templates/preact/package.json

@@ -22,7 +22,7 @@
     "release:publish": "changeset publish"
   },
   "dependencies": {
-    "@bardioc/app-sdk": "^1.0.1",
+    "@bardioc/app-sdk": "^1.0.3",
     "preact": "^10.26.7"
   },
   "devDependencies": {

package/templates/solid/package.json

@@ -22,7 +22,7 @@
     "release:publish": "changeset publish"
   },
   "dependencies": {
-    "@bardioc/app-sdk": "^1.0.1",
+    "@bardioc/app-sdk": "^1.0.3",
     "solid-js": "^1.9.7"
   },
   "devDependencies": {

package/templates/svelte/package.json

@@ -22,7 +22,7 @@
     "release:publish": "changeset publish"
   },
   "dependencies": {
-    "@bardioc/app-sdk": "^1.0.1",
+    "@bardioc/app-sdk": "^1.0.3",
     "svelte": "^5.33.14"
   },
   "devDependencies": {