@bardioc/create-bardioc-app 0.4.0

package/LICENSE

@@ -0,0 +1,5 @@
+MIT License
+
+Copyright (c) 2026 ALMATO AG. All rights reserved.
+
+This is an internal library for ALMATO AG.

package/README.md

@@ -0,0 +1,105 @@
+# @bardioc/create-bardioc-app
+
+Scaffold a Vite app wired for `@bardioc/app-sdk`.
+
+## Requirements
+
+- Node.js `>=20.19.0`
+
+## Install
+
+Configure the `@bardioc` scoped registry and install the CLI globally:
+
+```bash
+npm config set @bardioc:registry http://nexus.almato.com/repository/npm-group/ --location=user && npm install -g @bardioc/create-bardioc-app
+```
+
+If your default npm registry is not `https://registry.npmjs.org/`, set it in your user-level npm config before installing app dependencies.
+
+You can also run it without a global install:
+
+```bash
+npm exec --yes @bardioc/create-bardioc-app my-app -- --port 3005
+```
+
+Or with pnpm:
+
+```bash
+pnpm dlx @bardioc/create-bardioc-app my-app --port 3005
+```
+
+## Quick start
+
+```bash
+create-bardioc-app my-app --port 3005
+cd apps/my-app
+pnpm install
+bardioc login
+pnpm dev
+```
+
+## Generated app
+
+The generated app includes:
+
+- React + Vite project structure (or your chosen `--template`)
+- `@bardioc/app-sdk` dependency
+- `AppSdkProvider` wiring
+- optional host-backed standalone dev-session wiring via `.env`
+- a compact SDK demo with notification and transport examples
+- `public/app-manifest.json`
+
+### Release infra (out of the box)
+
+Every scaffolded app ships a lightweight versioning toolkit:
+
+- **Changesets** (`.changeset/` + `changeset`/`release:*` scripts) for semver-versioning the app
+- **`scripts/stamp-manifest.mjs`** — folds `package.json`'s version into the built `app-manifest.json`
+  so the WebOS app store shows the real release version (wired into `pnpm build` / `pnpm bundle`)
+- Two Claude skills under `.claude/commands/`: **`/changeset-app`** (bump locally) and
+  **`/refresh-bundle`** (rebuild the zip and swap it into a WebOS host checkout)
+
+### Opt-in tooling
+
+Heavier, environment-specific tooling is **off by default** — pass a flag to include it:
+
+- **`--with-pipeline`** — a **Bitbucket pipeline** (`bitbucket-pipelines.yml`) running
+  check-types/build/audit on PRs, with a publish step on `dev`. Publishing is **dormant** while the
+  app stays `"private": true` + unscoped (`pnpm changeset publish` no-ops); the generated `README.md`
+  documents how to enable it.
+- **`--with-link`** — the **`link:source` / `unlink:source`** dev flow (`scripts/link-source.mjs` +
+  `pnpm-workspace.yaml` + `.npmrc`) for developing against an in-tree `@bardioc/*` source checkout.
+
+## Standalone dev session
+
+Generated apps can opt into the same host-backed standalone dev-session flow used by the SDK examples.
+
+1. Copy `.env.example` to `.env`
+2. Fill in `VITE_APP_NAME`, `VITE_APP_ID`, and `DEV_AUTH_HOST_URL`
+3. Run `bardioc login` once for that host
+4. Set `VITE_ENABLE_DEV_AUTH=true`
+
+Important: standalone login will not start unless `VITE_ENABLE_DEV_AUTH=true` is present in `.env`. Running `pnpm dev` with only `VITE_APP_NAME` and `VITE_APP_ID` is not enough.
+
+When enabled, running `pnpm dev` outside the host iframe will use your stored CLI login to mint a fresh host dev session before the dev server starts, then route SDK transport calls through the local proxy into the host transport. `DEV_SESSION_KEY` no longer needs to be copied manually. If a request needs a specific scope, pass `scopeId` on that request.
+
+For public testing, run `pnpm dev:live` and use the emitted tunnel URL as the app's live URL in the host App Store configuration.
+
+## Options
+
+- `--template <name>` — framework template (default `vite`)
+- `--port <port>` — dev server port, default `3005`
+- `--with-pipeline` — add the Bitbucket CI/publish pipeline (off by default)
+- `--with-link` — add the `link:source` dev flow for local `@bardioc/*` checkouts (off by default)
+
+## Support
+
+For support, contact yevhenii.atlanov@almato.com.
+
+## License
+
+MIT.
+
+Copyright (c) 2026 ALMATO AG. All rights reserved.
+
+This is an internal library for ALMATO AG.

package/bin/create.mjs

@@ -0,0 +1,76 @@
+#!/usr/bin/env node
+
+import { readFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { getDefaultTemplate, listTemplates, parseArgs, scaffoldApp } from '../src/scaffold.js';
+
+const __dirname = fileURLToPath(new URL('.', import.meta.url));
+const TEMPLATES_DIR = join(__dirname, '..', 'templates');
+const packageJsonPath = join(__dirname, '..', 'package.json');
+const packageJson = JSON.parse(readFileSync(packageJsonPath, 'utf-8'));
+
+const args = process.argv.slice(2);
+
+if (args.includes('--help') || args.includes('-h') || args.length === 0) {
+  const templates = listTemplates(TEMPLATES_DIR);
+  const defaultTemplate = getDefaultTemplate(TEMPLATES_DIR);
+  console.log(`
+  Usage: create-bardioc-app <app-name> [options]
+
+  Options:
+    --template <name>  Framework template (default: ${defaultTemplate})
+    --port <port>      Dev server port (default: 3005)
+    --with-pipeline    Add the Bitbucket CI/publish pipeline (off by default)
+    --with-link        Add the link:source dev flow for local @bardioc/* checkouts (off by default)
+
+  Available templates:
+${templates.map(t => `    - ${t}`).join('\n')}
+
+  Examples:
+    npm exec --yes @bardioc/create-bardioc-app my-app
+    npm exec --yes @bardioc/create-bardioc-app my-app -- --template vue
+    npm exec --yes @bardioc/create-bardioc-app my-app -- --template angular --port 3010
+    npm exec --yes @bardioc/create-bardioc-app my-app -- --with-pipeline --with-link
+`);
+  process.exit(0);
+}
+
+const argsResult = parseArgs(args, TEMPLATES_DIR);
+
+if (!argsResult.valid) {
+  console.error(`Error: ${argsResult.error}`);
+  process.exit(1);
+}
+
+const { name, port, template, withPipeline, withLink } = argsResult;
+const destBase = resolve(process.cwd());
+const templateDir = join(TEMPLATES_DIR, template);
+
+console.log(`\nCreating apps/${name}/ with ${template} template...\n`);
+
+const result = scaffoldApp({
+  name,
+  port,
+  template,
+  templateDir,
+  destBase,
+  withPipeline,
+  withLink,
+});
+
+if (!result.success) {
+  console.error(`Error: ${result.error}`);
+  process.exit(1);
+}
+
+console.log(`  Done! Next steps:\n`);
+console.log(`    cd apps/${name}`);
+console.log(`    pnpm install`);
+console.log(`    bardioc login`);
+console.log(`    pnpm dev\n`);
+console.log(`  Open http://localhost:${port} to see your app.`);
+console.log(
+  `  Standalone host-backed auth now refreshes automatically from your CLI login during pnpm dev.`
+);
+console.log(`  Use "pnpm dev:live" for a public tunnel/live URL.\n`);

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@bardioc/create-bardioc-app",
+  "version": "0.4.0",
+  "description": "Scaffold a Bardioc app with framework templates (vite, react, vue, angular, svelte, solid, preact, nextjs)",
+  "license": "MIT",
+  "private": false,
+  "type": "module",
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=20.19.0"
+  },
+  "bin": {
+    "create-bardioc-app": "./bin/create.mjs"
+  },
+  "files": [
+    "bin",
+    "src",
+    "templates",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "bardioc",
+    "create",
+    "scaffold",
+    "vite",
+    "react"
+  ],
+  "devDependencies": {
+    "@vitest/coverage-v8": "4.1.5",
+    "@types/node": "^25.6.0",
+    "typescript": "^6.0.3",
+    "vitest": "4.1.5"
+  },
+  "scripts": {
+    "check-types": "tsc --noEmit",
+    "pack:check": "npm pack --dry-run",
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage",
+    "test:watch": "vitest"
+  }
+}

package/src/scaffold.d.ts

@@ -0,0 +1,50 @@
+export function toPascalCase(str: string): string;
+
+export function validateName(name: string | null): { valid: boolean; error?: string };
+
+export function parsePort(rawPort: string): { valid: boolean; port?: number; error?: string };
+
+export function replaceVars(content: string, vars: Record<string, string>): string;
+
+export function isTextTemplateFile(filePath: string): boolean;
+
+export function walkAndReplace(dir: string, vars: Record<string, string>): void;
+
+export function loadTemplateCatalog(templatesDir?: string): {
+  schemaVersion: number;
+  defaultTemplate: string;
+  templates: string[];
+};
+
+export function listTemplates(templatesDir?: string): string[];
+
+export function getDefaultTemplate(templatesDir?: string): string;
+
+export function parseArgs(
+  args: string[],
+  templatesDir?: string
+): {
+  valid: boolean;
+  name?: string;
+  port?: number;
+  template?: string;
+  withPipeline?: boolean;
+  withLink?: boolean;
+  error?: string;
+};
+
+export function scaffoldApp(params: {
+  name: string;
+  port: number;
+  template?: string;
+  templateDir: string;
+  destBase: string;
+  withPipeline?: boolean;
+  withLink?: boolean;
+}): {
+  success: boolean;
+  dest?: string;
+  name?: string;
+  port?: number;
+  error?: string;
+};

package/src/scaffold.js

@@ -0,0 +1,379 @@
+import {
+  cpSync,
+  existsSync,
+  readdirSync,
+  readFileSync,
+  renameSync,
+  statSync,
+  writeFileSync,
+} from 'node:fs';
+import { dirname, extname, join } from 'node:path';
+
+const TEMPLATE_MANIFEST_FILE = 'manifest.json';
+const DEFAULT_TEMPLATE = 'vite';
+const BASE_TEMPLATE_DIR = '_base';
+const PIPELINE_OVERLAY_DIR = '_opt-pipeline';
+const LINK_OVERLAY_DIR = '_opt-link';
+const DOTFILE_RENAMES = { _gitignore: '.gitignore', _npmrc: '.npmrc' };
+
+// Per-template values for the opt-in CI pipeline. Vite-family templates read the app slug from
+// VITE_APP_NAME and build to dist/; only Next.js differs.
+const DEFAULT_PIPELINE_VARS = { BUILD_ENV: 'VITE_APP_NAME', OUT_DIR: 'dist' };
+const TEMPLATE_PIPELINE_VARS = {
+  nextjs: { BUILD_ENV: 'NEXT_PUBLIC_APP_NAME', OUT_DIR: 'out' },
+};
+
+// Added to package.json scripts only when scaffolding with --with-link.
+const LINK_SCRIPTS = {
+  'link:source': 'node scripts/link-source.mjs',
+  'unlink:source': 'node scripts/link-source.mjs --remove',
+};
+
+// Boolean CLI flags → the result key they set.
+const BOOLEAN_FLAGS = {
+  '--with-pipeline': 'withPipeline',
+  '--with-link': 'withLink',
+};
+
+const TEXT_FILE_EXTENSIONS = new Set([
+  '.css',
+  '.d.ts',
+  '.html',
+  '.json',
+  '.js',
+  '.jsx',
+  '.md',
+  '.mjs',
+  '.mts',
+  '.svg',
+  '.ts',
+  '.tsx',
+  '.txt',
+  '.yml',
+  '.yaml',
+]);
+const TEXT_FILENAMES = new Set(['_gitignore', '_npmrc']);
+const TEXT_FILE_SUFFIXES = ['.env.example'];
+
+export function toPascalCase(str) {
+  return str
+    .split('-')
+    .map(w => w[0].toUpperCase() + w.slice(1))
+    .join('');
+}
+
+export function validateName(name) {
+  if (!name) {
+    return { valid: false, error: 'app name is required' };
+  }
+  if (!/^[a-z][a-z0-9-]*$/.test(name)) {
+    return { valid: false, error: 'name must be lowercase with hyphens (e.g. my-app)' };
+  }
+  return { valid: true };
+}
+
+export function parsePort(rawPort) {
+  if (!/^\d+$/.test(rawPort)) {
+    return { valid: false, error: 'port must be an integer between 1024 and 65535' };
+  }
+
+  const port = Number.parseInt(rawPort, 10);
+
+  if (Number.isNaN(port) || port < 1024 || port > 65535) {
+    return { valid: false, error: 'port must be an integer between 1024 and 65535' };
+  }
+
+  return { valid: true, port };
+}
+
+export function replaceVars(content, vars) {
+  let result = content;
+  for (const [key, value] of Object.entries(vars)) {
+    result = result.replaceAll(`{{${key}}}`, value);
+  }
+  return result;
+}
+
+export function isTextTemplateFile(filePath) {
+  return (
+    TEXT_FILENAMES.has(filePath.split('/').at(-1) ?? '') ||
+    TEXT_FILE_SUFFIXES.some(suffix => filePath.endsWith(suffix)) ||
+    TEXT_FILE_EXTENSIONS.has(extname(filePath))
+  );
+}
+
+export function walkAndReplace(dir, vars) {
+  for (const entry of readdirSync(dir)) {
+    const full = join(dir, entry);
+    if (statSync(full).isDirectory()) {
+      walkAndReplace(full, vars);
+    } else if (isTextTemplateFile(full)) {
+      const content = readFileSync(full, 'utf-8');
+      writeFileSync(full, replaceVars(content, vars));
+    }
+  }
+}
+
+function discoverTemplatesFromDirectory(templatesDir) {
+  if (!existsSync(templatesDir)) {
+    return [DEFAULT_TEMPLATE];
+  }
+
+  return readdirSync(templatesDir)
+    .filter(entry => {
+      if (entry === TEMPLATE_MANIFEST_FILE || entry.startsWith('_')) {
+        return false;
+      }
+      const full = join(templatesDir, entry);
+      return statSync(full).isDirectory();
+    })
+    .sort();
+}
+
+export function loadTemplateCatalog(templatesDir) {
+  const fallbackTemplates = discoverTemplatesFromDirectory(templatesDir);
+  const fallback = {
+    schemaVersion: 1,
+    defaultTemplate: fallbackTemplates.includes(DEFAULT_TEMPLATE)
+      ? DEFAULT_TEMPLATE
+      : (fallbackTemplates[0] ?? DEFAULT_TEMPLATE),
+    templates: fallbackTemplates,
+  };
+
+  if (!templatesDir) {
+    return fallback;
+  }
+
+  const manifestPath = join(templatesDir, TEMPLATE_MANIFEST_FILE);
+  if (!existsSync(manifestPath)) {
+    return fallback;
+  }
+
+  const manifest = JSON.parse(readFileSync(manifestPath, 'utf-8'));
+
+  if (manifest.schemaVersion !== 1) {
+    throw new Error(`unsupported template manifest schema version: ${manifest.schemaVersion}`);
+  }
+
+  if (!Array.isArray(manifest.templates) || manifest.templates.length === 0) {
+    throw new Error('template manifest must define a non-empty templates array');
+  }
+
+  const manifestTemplates = [...manifest.templates].sort();
+  const discoveredTemplates = [...fallbackTemplates].sort();
+  if (manifestTemplates.join(',') !== discoveredTemplates.join(',')) {
+    throw new Error(
+      `template manifest does not match templates directory. manifest=${manifestTemplates.join(',')} directory=${discoveredTemplates.join(',')}`
+    );
+  }
+
+  if (
+    typeof manifest.defaultTemplate !== 'string' ||
+    !manifestTemplates.includes(manifest.defaultTemplate)
+  ) {
+    throw new Error(
+      `template manifest defaultTemplate must be one of: ${manifestTemplates.join(', ')}`
+    );
+  }
+
+  return {
+    schemaVersion: manifest.schemaVersion,
+    defaultTemplate: manifest.defaultTemplate,
+    templates: manifestTemplates,
+  };
+}
+
+export function listTemplates(templatesDir) {
+  return loadTemplateCatalog(templatesDir).templates;
+}
+
+export function getDefaultTemplate(templatesDir) {
+  return loadTemplateCatalog(templatesDir).defaultTemplate;
+}
+
+function readFlagValue(args, index, flagName) {
+  const value = args[index + 1];
+  if (!value) {
+    return { valid: false, error: `missing value for ${flagName}` };
+  }
+
+  return { valid: true, value, nextIndex: index + 1 };
+}
+
+function parseTemplateArg(args, index, availableTemplates) {
+  const valueResult = readFlagValue(args, index, '--template');
+  if (!valueResult.valid) {
+    return valueResult;
+  }
+
+  if (!availableTemplates.includes(valueResult.value)) {
+    return {
+      valid: false,
+      error: `unknown template "${valueResult.value}". Available: ${availableTemplates.join(', ')}`,
+    };
+  }
+
+  return {
+    valid: true,
+    template: valueResult.value,
+    nextIndex: valueResult.nextIndex,
+  };
+}
+
+function parsePortArg(args, index) {
+  const valueResult = readFlagValue(args, index, '--port');
+  if (!valueResult.valid) {
+    return valueResult;
+  }
+
+  const portResult = parsePort(valueResult.value);
+  if (!portResult.valid) {
+    return portResult;
+  }
+
+  return {
+    valid: true,
+    port: /** @type {number} */ (portResult.port),
+    nextIndex: valueResult.nextIndex,
+  };
+}
+
+function isPositionalName(arg, index, commandOffset, name) {
+  return !arg.startsWith('--') && index >= commandOffset && !name && arg !== 'create';
+}
+
+function scanArgs(args, commandOffset, catalog) {
+  let name = null;
+  let port = 3005;
+  let template = catalog.defaultTemplate;
+  const flags = { withPipeline: false, withLink: false };
+  const availableTemplates = catalog.templates;
+
+  let index = 0;
+  while (index < args.length) {
+    const arg = args[index];
+
+    if (arg === '--port') {
+      const portResult = parsePortArg(args, index);
+      if (!portResult.valid) {
+        return portResult;
+      }
+      port = portResult.port;
+      index = portResult.nextIndex + 1;
+      continue;
+    }
+
+    if (arg === '--template') {
+      const templateResult = parseTemplateArg(args, index, availableTemplates);
+      if (!templateResult.valid) {
+        return templateResult;
+      }
+      template = templateResult.template;
+      index = templateResult.nextIndex + 1;
+      continue;
+    }
+
+    if (arg in BOOLEAN_FLAGS) {
+      flags[BOOLEAN_FLAGS[arg]] = true;
+      index++;
+      continue;
+    }
+
+    if (isPositionalName(arg, index, commandOffset, name)) {
+      name = arg;
+    }
+
+    index++;
+  }
+
+  return { valid: true, name, port, template, ...flags };
+}
+
+export function parseArgs(args, templatesDir) {
+  const firstPositionalArg = args.find(arg => !arg.startsWith('--'));
+  const commandOffset = firstPositionalArg === 'create' ? 1 : 0;
+  const catalog = loadTemplateCatalog(templatesDir);
+
+  const scan = scanArgs(args, commandOffset, catalog);
+  if (!scan.valid) {
+    return scan;
+  }
+
+  const nameValidation = validateName(scan.name);
+  if (!nameValidation.valid) {
+    return nameValidation;
+  }
+
+  return scan;
+}
+
+// Merges the link:source scripts into a scaffolded package.json (used only with --with-link).
+function addLinkScripts(dest) {
+  const pkgPath = join(dest, 'package.json');
+  if (!existsSync(pkgPath)) {
+    return;
+  }
+  const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'));
+  pkg.scripts = { ...pkg.scripts, ...LINK_SCRIPTS };
+  writeFileSync(pkgPath, `${JSON.stringify(pkg, null, 2)}\n`);
+}
+
+/**
+ * @param {object} params
+ * @param {string} params.name
+ * @param {number} params.port
+ * @param {string} [params.template]
+ * @param {string} params.templateDir
+ * @param {string} params.destBase
+ * @param {boolean} [params.withPipeline]
+ * @param {boolean} [params.withLink]
+ * @returns {{ success: boolean; dest?: string; name?: string; port?: number; error?: string }}
+ */
+export function scaffoldApp({
+  name,
+  port,
+  template,
+  templateDir,
+  destBase,
+  withPipeline = false,
+  withLink = false,
+}) {
+  const dest = join(destBase, 'apps', name);
+
+  if (existsSync(dest)) {
+    return { success: false, error: `directory "apps/${name}" already exists` };
+  }
+
+  const vars = {
+    APP_NAME: name,
+    DISPLAY_NAME: toPascalCase(name),
+    PORT: String(port),
+    ...(TEMPLATE_PIPELINE_VARS[template] ?? DEFAULT_PIPELINE_VARS),
+  };
+
+  const templatesRoot = dirname(templateDir);
+  const baseDir = join(templatesRoot, BASE_TEMPLATE_DIR);
+  if (existsSync(baseDir)) {
+    cpSync(baseDir, dest, { recursive: true });
+  }
+  cpSync(templateDir, dest, { recursive: true });
+
+  if (withPipeline) {
+    cpSync(join(templatesRoot, PIPELINE_OVERLAY_DIR), dest, { recursive: true });
+  }
+  if (withLink) {
+    cpSync(join(templatesRoot, LINK_OVERLAY_DIR), dest, { recursive: true });
+    addLinkScripts(dest);
+  }
+
+  walkAndReplace(dest, vars);
+
+  for (const [shipped, final] of Object.entries(DOTFILE_RENAMES)) {
+    const shippedSrc = join(dest, shipped);
+    if (existsSync(shippedSrc)) {
+      renameSync(shippedSrc, join(dest, final));
+    }
+  }
+
+  return { success: true, dest, name, port };
+}

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

@@ -0,0 +1,17 @@
+# Changesets
+
+This app versions itself with [Changesets](https://github.com/changesets/changesets) — the same flow
+as the `@bardioc/*` libraries.
+
+**To cut a release: run the `/changeset-app` skill** (or `pnpm changeset`) — it picks the semver bump
+and applies it locally (`pnpm 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.
+
+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.
+
+> **This app ships private + unscoped, so publishing is dormant.** `pnpm 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/`.

package/templates/_base/.changeset/config.json

@@ -0,0 +1,12 @@
+{
+  "$schema": "https://unpkg.com/@changesets/config@3.1.4/schema.json",
+  "changelog": "@changesets/cli/changelog",
+  "commit": false,
+  "fixed": [],
+  "linked": [],
+  "access": "restricted",
+  "baseBranch": "dev",
+  "updateInternalDependencies": "patch",
+  "onlyUpdatePeerDependentsWhenParentChanged": true,
+  "ignore": []
+}